Skip to content

00-setup.md

Latest commit

 

History

History
51 lines (33 loc) · 2.21 KB

00-setup.md

File metadata and controls

51 lines (33 loc) · 2.21 KB

00. 环境准备

你会配置什么

这个项目只需要三类环境变量：

  • OPENAI_API_KEY：官方 OpenAI API key，或兼容服务提供的 key。
  • OPENAI_BASE_URL：可选。填写后会使用 OpenAI-compatible 服务。
  • OPENAI_MODEL：模型名。官方 API 和兼容服务的模型名通常不同。

ChatGPT Plus 与 API key

ChatGPT Plus 是 ChatGPT 产品订阅，不等同于 OpenAI API 额度或 API key。Agents SDK 是开发者 SDK，它通过 API 请求调用模型，所以必须有 API key，或一个兼容 OpenAI API 协议的服务。

官方 OpenAI API

.env 示例：

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5.4-mini

不填写 OPENAI_BASE_URL 时，项目使用官方 OpenAI API。为了让前 6 节课都保持旧的 messages 学习路径，项目默认仍然把 SDK 配置为 chat_completions 模式。

OpenAI-compatible baseURL

.env 示例：

OPENAI_API_KEY=dummy
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=your-model-name

填写 OPENAI_BASE_URL 时，项目会创建自定义 OpenAI({ baseURL, apiKey }) 客户端，并用 setDefaultOpenAIClient() 注入 Agents SDK。项目同样使用 chat_completions 模式，因为多数兼容服务优先兼容的是 /chat/completions 这一类 messages 接口。

兼容服务模式下，项目默认关闭 OpenAI tracing 导出。原因是 tracing 默认会上传到 OpenAI 官方 tracing 服务，而兼容服务的 API key 通常不能用于 OpenAI 官方 tracing API。

新的 Responses 风格

pnpm lesson:07 会单独演示 responses 模式。它需要官方 OpenAI API；如果你配置了 OPENAI_BASE_URL，本课会主动提示移除，因为兼容服务不一定实现 OpenAI Responses API。

常见错误

  • 缺少 OPENAI_API_KEY：复制 .env.example 为 .env 并填写。
  • 只有 ChatGPT Plus：需要额外获取 API key，或使用兼容服务。
  • baseURL 404：确认地址是否包含 /v1。
  • 模型不存在：把 OPENAI_MODEL 改成服务实际支持的模型名。
  • tool calling 失败：兼容服务可能不支持工具调用或结构化输出。
  • 第 7 课提示需要官方 OpenAI API：这是预期行为，Responses 风格不作为兼容服务默认路径。