赛博鸡蛋
指南目录(34 篇)

通用

Codex CLI 第三方 API 通用教程:Responses 配置与本地协议桥接

新版 Codex CLI 已不再支持旧的 chat 协议,要求上游提供 Responses API。原生支持 Responses 的平台可直接写进 ~/.codex/config.toml;只有 Chat Completions 接口的免费平台,通过本机网关转换协议即可正常接入。

适用对象
想用自备第三方免费 API Key 驱动 OpenAI Codex CLI 的开发者
预计用时
约 8 分钟
更新时间

准备

  • 已全局安装 @openai/codex
  • 原生支持 Responses API 的平台密钥,或已在本机运行 Magpie 网关

步骤

  1. 判断上游平台能否直连,还是需要本地转换协议

    当前版本的 Codex CLI 固定发送 Responses API 请求,并且读写本地文件依赖模型自身的工具调用(Tool Calling)能力:

    • 可直连的平台:原生提供 Responses API 端点的服务商,例如 阿里云百炼北京地域(见 Codex 接入百炼教程)、River AI(新账号送 $25 额度,地址 https://api.river.ai/v1)、Vercel AI Gateway 等。
    • 需转换协议的平台:像硅基流动、火山方舟、Groq、百度千帆以及多数 OpenRouter 免费模型只开放 Chat Completions。先在本机启动 Magpie 或 CLIProxyAPI,由本地网关把 Responses API 实时转成上游的 Chat Completions。
  2. 编辑用户级 ~/.codex/config.toml

    打开用户主目录下的 ~/.codex/config.toml(注意顶层的 model_provider 和 model 必须放在所有 [...] 表头之前;自定义名称避开 openai、ollama、lmstudio 三个内置保留词)。

    下面给出直连原生 Responses 平台与连接本机 Magpie 网关的两种写法,按实际选用一套:

    toml
    model_provider = "river"
    model = "deepseek-ai/DeepSeek-V4.1-Flash"
    
    # 写法 1:直连原生支持 Responses API 的平台
    [model_providers.river]
    name = "River AI"
    base_url = "https://api.river.ai/v1"
    env_key = "RIVER_API_KEY"
    wire_api = "responses"
    
    # 写法 2:连接本机 Magpie 网关(桥接任意 Chat Completions 平台)
    [model_providers.magpie_local]
    name = "Magpie Local"
    base_url = "http://127.0.0.1:3425/v1"
    env_key = "MAGPIE_LOCAL_KEY"
    wire_api = "responses"
  3. 导出环境变量并验证文件操作

    在终端设置 env_key 对应的环境变量后启动 codex(注意 config.toml 里 env_key 写的是环境变量名,不要把 sk-... 密钥直接填进去;若走本机 magpie_local,变量值随便设一个非空字符串即可):

    bash
    export RIVER_API_KEY="你的平台API_Key"
    codex
  4. 常见状态码排查

    进入会话先发一句短问题,再让它读取并修改一个测试文件:

    • 401 Unauthorized:当前终端未导出 env_key 指定的变量,或密钥与平台不匹配;
    • 404 Not Found:该平台实际未开放 /responses 路径,改走本机网关桥接即可;
    • 能对话但无法改文件:更换一个支持工具调用的编程模型。

注意事项

  • 自定义提供商只能在用户主目录 ~/.codex/config.toml 中声明,写在项目目录 .codex/config.toml 里的 model_providers 会被忽略。
  • 使用第三方 Key 时费用与额度由对应平台结算,与 ChatGPT 账号内的 Codex credits 互不影响;每次修改 config.toml 后需重启 codex 进程生效。

常见问题

只要兼容 OpenAI 的平台都能直接写进 config.toml 吗?

不能只看「OpenAI 兼容」四个字。大多数平台只兼容 /chat/completions,而当前 Codex CLI 需要 /responses;不支持 Responses 的平台用 Magpie 或 CC Switch 转接即可。

只想给官方 OpenAI 接口换个代理地址,也要新建 provider 吗?

不需要,单纯替换官方 OpenAI 地址只需在顶层设置 openai_base_url,不必新建 model_providers。

参考链接

相关指南

搜索优惠

提交优惠线索

粘贴官方活动页、定价页或文档链接,每日定时核验通过后发布。

无需注册,提交后可查看审核进度