指南目录(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 网关
步骤
判断上游平台能否直连,还是需要本地转换协议
当前版本的 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。
- 可直连的平台:原生提供
编辑用户级 ~/.codex/config.toml
打开用户主目录下的
~/.codex/config.toml(注意顶层的model_provider和model必须放在所有[...]表头之前;自定义名称避开openai、ollama、lmstudio三个内置保留词)。下面给出直连原生 Responses 平台与连接本机 Magpie 网关的两种写法,按实际选用一套:
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"导出环境变量并验证文件操作
在终端设置
env_key对应的环境变量后启动codex(注意config.toml里env_key写的是环境变量名,不要把sk-...密钥直接填进去;若走本机magpie_local,变量值随便设一个非空字符串即可):export RIVER_API_KEY="你的平台API_Key" codex常见状态码排查
进入会话先发一句短问题,再让它读取并修改一个测试文件:
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。
参考链接
- Codex 自定义模型提供商官方文档developers.openai.com/codex/config-advanced
- Codex 配置文件完整参考learn.chatgpt.com/docs/config-file/config-reference