1. 为什么 Agents SDK 接自定义 API 总在第一步卡住OpenAI Agents SDK 是 OpenAI 官方出的轻量 Agent 编排框架核心就三样东西Agent角色指令模型、Runner执行循环、Tools工具调用。它默认会去连 OpenAI 官方端点但很多人手里跑的是自建推理服务、公司内网的 OpenAI-Compatible 网关或者统一 Key 的聚合通道。这时候如果不改配置SDK 会直接拿api.openai.com去发请求结果就是 401 或者连接超时。我试过在一个内网环境里部署模型服务监听在192.168.31.15:8000/v1接口格式完全兼容 OpenAI 的/chat/completions但 Agents SDK 死活连不上。问题不在模型服务而在于 SDK 的默认客户端没有指向这个地址。Agents SDK 提供了set_default_openai_client和OpenAIChatCompletionsModel两个入口来覆盖默认行为只要把AsyncOpenAI的base_url和api_key配对就能让整个 Runner 走自定义通道。这篇要解决的就是这个落地问题给你一份可复制的config.toml骨架把base_url、api_key、model三个字段拆清楚再配一个最小 Agent 示例跑一次对话请求验证连通性。适合已经在用 Agents SDK、但需要把模型请求切到自定义 OpenAI-Compatible API 的开发者。如果你还没拿到可用的 Key 和统一通道可以先去 TaoToken 的 API Keys 页面 生成一个后面配置里直接填进去就能跑。2. 前置准备统一 Key 与 API 通道怎么接在写config.toml之前先把两件事定下来Key 从哪来、base_url 填什么。Agents SDK 本身不关心你用的是官方还是兼容端点它只认AsyncOpenAI客户端里的base_url和api_key。所以只要有一个兼容 OpenAI 协议的统一通道就能把 SDK 的请求导过去。统一通道的好处是一个 Key 可以覆盖多个模型base_url 固定不用为每个模型单独配环境变量。TaoToken 的接入方式就是这种形态API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions路径。你可以在 控制台 里看到当前 Key 的可用模型列表然后在 接入文档 里确认 base_url 的拼接规则。这里有个容易踩的坑base_url 到底要不要带/v1。OpenAI 官方 SDK 的AsyncOpenAI默认会在 base_url 后面拼/chat/completions所以如果你填的是https://taotoken.net/api实际请求会打到https://taotoken.net/api/chat/completions。但兼容端点通常要求路径是/v1/chat/completions所以 base_url 应该写成https://taotoken.net/api/v1。这个细节在 config.toml 里必须写对否则会返回 404。另外Agents SDK 默认走的是 Responses API而大多数兼容端点只实现了 Chat Completions。所以必须显式调用set_default_openai_api(chat_completions)否则 SDK 会发一个兼容端点不认识的请求格式。这一步在后面的代码里会体现。3. config.toml 骨架base_url、api_key、model 三字段Agents SDK 本身没有内置读取config.toml的机制但我们可以用 Python 的tomllib3.11或tomli来加载配置然后把值注入到AsyncOpenAI和Agent里。这样做的目的是把环境相关的参数从代码里抽出来换环境时只改配置文件不动业务逻辑。下面是一份可直接复制的config.toml骨架# config.toml [openai] # 统一通道的 API 地址注意带 /v1 base_url https://taotoken.net/api/v1 # 从控制台生成的 Key不要提交到 git api_key sk-你的实际Key # 默认模型名需与通道支持的模型列表一致 model gpt-4o [agent] name Assistant instructions You are a helpful assistant. temperature 0.7三个字段的作用分别是base_url决定请求打到哪个网关api_key做鉴权model告诉 Agent 用哪个模型。注意model字段在 Agents SDK 里不是直接传给Agent的而是传给OpenAIChatCompletionsModel的构造函数。所以加载配置后代码里要这样映射import tomllib with open(config.toml, rb) as f: cfg tomllib.load(f) base_url cfg[openai][base_url] api_key cfg[openai][api_key] model_name cfg[openai][model]如果你用的是 Python 3.10 或更早版本把tomllib换成tomli即可安装命令是pip install tomli。这一步没有额外依赖Agents SDK 本身会装好openai包。注意api_key不要硬编码在代码里也不要把config.toml提交到公开仓库。生产环境建议用环境变量覆盖或者用密钥管理服务注入。4. 最小 Agent 示例从加载配置到跑通一次对话配置就绪后写一个最小可运行的 Agent。核心步骤是加载 config.toml → 创建 AsyncOpenAI 客户端 → 设为默认客户端 → 声明使用 chat_completions → 构造 Agent → 用 Runner 执行。import asyncio import os import tomllib from agents import ( Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel, ModelSettings, set_default_openai_client, set_default_openai_api, enable_verbose_stdout_logging, ) # 1. 加载配置 with open(config.toml, rb) as f: cfg tomllib.load(f) base_url cfg[openai][base_url] api_key cfg[openai][api_key] model_name cfg[openai][model] # 2. 创建自定义 OpenAI 客户端 openai_client AsyncOpenAI( api_keyapi_key, base_urlbase_url, ) # 3. 覆盖 SDK 默认客户端和 API 类型 set_default_openai_client(openai_client) set_default_openai_api(chat_completions) # 4. 打开详细日志方便排查连通性问题 enable_verbose_stdout_logging() async def main(): agent Agent( namecfg[agent][name], instructionscfg[agent][instructions], modelOpenAIChatCompletionsModel( modelmodel_name, openai_clientopenai_client, ), model_settingsModelSettings( temperaturecfg[agent][temperature], ), ) result await Runner.run( agent, 用一句话解释什么是递归。, ) print(模型返回, result.final_output) if __name__ __main__: asyncio.run(main())这段代码里有两个关键点。第一set_default_openai_client(openai_client)让 Runner 内部所有默认请求都走我们传入的客户端这样即使 Agent 没有显式指定openai_client也会用统一通道。第二set_default_openai_api(chat_completions)强制 SDK 使用 Chat Completions 协议而不是默认的 Responses API。兼容端点通常只实现了前者漏掉这行会报 404 或 400。enable_verbose_stdout_logging()会打印请求和响应的详细日志第一次接入时建议打开确认请求确实打到了https://taotoken.net/api/v1/chat/completions。如果日志里出现的是api.openai.com说明set_default_openai_client没生效检查一下调用顺序。5. 连通性验证一次请求看结果与日志跑起来之后终端会先输出 SDK 的请求日志然后是模型返回。成功的标志有两个日志里出现POST https://taotoken.net/api/v1/chat/completions以及最后打印出模型生成的文本。如果模型返回类似「递归是函数调用自身来解决问题的编程技巧」说明整条链路通了。如果返回的是 401检查api_key是否填对、是否有多余空格。如果返回 404检查base_url是否带了/v1以及set_default_openai_api(chat_completions)是否在Runner.run之前调用。你也可以用curl单独验证通道本身是否可用排除 SDK 层面的干扰curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的实际Key \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: ping}], max_tokens: 16 }如果curl能返回正常的 JSON但 Agents SDK 报错那问题就在 SDK 配置上重点检查set_default_openai_client和set_default_openai_api的调用顺序。如果curl也失败那就是 Key 或 base_url 的问题去 模型对话页面 手动发一条消息确认 Key 本身有效。实测下来最常见的失败原因是 base_url 写成了https://taotoken.net/api而不是https://taotoken.net/api/v1导致请求路径变成/api/chat/completions网关找不到路由。另一个常见原因是忘了set_default_openai_api(chat_completions)SDK 发了 Responses API 的请求体兼容端点解析失败。6. 本篇常见错排查报错一openai.AuthenticationError: 401Key 无效或没传。检查config.toml里的api_key是否以sk-开头有没有被引号包裹导致多出空格。如果 Key 是从环境变量读的确认os.getenv返回的不是None。报错二openai.NotFoundError: 404base_url 路径不对。兼容端点的完整路径是{base_url}/chat/completions所以 base_url 必须包含/v1。另外确认set_default_openai_api(chat_completions)已调用否则 SDK 会请求/responses路径。报错三TypeError: NoneType object is not callableset_default_openai_client在Runner.run之后才调用。所有全局设置必须在构造 Agent 和调用 Runner 之前完成。报错四模型名不识别config.toml里的model字段必须与通道支持的模型列表一致。去 接入文档 核对可用模型名不要凭记忆填。报错五请求超时如果 base_url 指向内网地址确认当前机器能访问该地址。用curl或ping先测网络连通性再跑 SDK。排查顺序建议先curl验证通道再检查 config.toml 三个字段最后检查 SDK 的两行全局设置。大部分问题都出在 base_url 的/v1和set_default_openai_api这两处。7. 下一步把配置固化到长期编码流程跑通一次对话只是起点。如果你打算把 Agents SDK 用在日常编码或 Agent 工作流里建议把config.toml纳入项目模板Key 用环境变量覆盖base_url 和 model 按环境分文件管理。这样换通道时只改配置不动代码。对于需要长期跑 Agent 任务的场景可以关注 Coding Plan 的额度方案把统一 Key 和 API 通道固定下来避免每次调试都重新配。如果你用的是 Claude Code 这类工具也可以参考 ClaudeCodeAnthropic 接入说明把同一套通道复用到不同客户端。最后留一个实用技巧在config.toml旁边放一个config.local.toml用.gitignore排除本地调试时优先读 local 文件。这样团队协作时公共配置和私有 Key 分离不会因为误提交 Key 导致泄露。
