Codex CLI 接入 CoderPlan 教程

Setup steps

1. 1

   准备 Codex CLI 和 CoderPlan API Key

   先在本机安装 Codex CLI（`npm install -g @openai/codex`），终端里能运行 `codex`；再在 CoderPlan 控制台创建 `sk-` 开头的 API Key，并确认 API 使用额度足够完成一次测试调用。

2. 2

   为什么是 config.toml + auth.json 两个文件

   现在的 Codex CLI 是 Rust 重写版，把「路由」和「凭据」拆成两个文件存放：config.toml 决定请求发往哪里、走什么协议、用哪个模型；auth.json 只存放密钥。分工的好处是换模型不动密钥、换密钥不动路由。老教程里 `export OPENAI_BASE_URL=...` 的做法针对的是旧版 Node.js 实现——新版默认引导 ChatGPT 账号登录，环境变量不再可靠地切换供应商，所以本教程改用两个文件的官方配置方式。

   config.toml — 决定路由和模型

   Codex 启动时读取这个文件决定当前用哪个供应商。做法是把 CoderPlan 注册为一个自定义供应商，再用 model_provider 这一行激活它。

   Copy

   model_provider = "coderplan"model = "gpt-5.6-sol"[model_providers.coderplan]name = "CoderPlan"base_url = "https://api.coderplan.ai/v1"wire_api = "responses"requires_openai_auth = true

   auth.json — 决定用哪个密钥

   只需要一个 OPENAI_API_KEY 字段。它虽然沿用 OpenAI 的字段名，但值是你的 CoderPlan 密钥（下一步会解释为什么）。

   Copy

   {  "OPENAI_API_KEY": "sk-your-api-key"}

3. 3

   config.toml 每一行为什么这么填

   每一行都有明确的作用，理解之后排错会容易得多。文件路径是 `~/.codex/config.toml`（Windows 为 `%USERPROFILE%\.codex\config.toml`），没有就新建。

   1. `model_provider = "coderplan"`：激活 ID 为 coderplan 的供应商，对应下方的 `[model_providers.coderplan]` 配置表。以后想切回官方只改这一行；注意 `openai`、`ollama`、`lmstudio` 是 Codex 的保留 ID，不能拿来注册自定义供应商。
   2. `model = "gpt-5.6-sol"`：必须填价格页上真实存在的模型名，写官方宣传名或不存在的型号会直接报模型不可用。示例用的是 CoderPlan 常用的 GPT 系模型，以价格页为准。
   3. `[model_providers.coderplan]`：自定义供应商表，ID 自己起名即可，表里描述这个供应商怎么连。
   4. `base_url` 填到 `/v1` 为止：Codex 会在它后面自动拼接 `/responses` 等具体接口路径，多一层、少一层或带尾部斜杠都会 404。
   5. `wire_api = "responses"`：约定 Codex 与服务端用 Responses 协议（`POST /v1/responses`）通信，工具调用、多轮推理摘要都依赖它。CoderPlan 网关已实现该协议；填 `"chat"` 会退回老的 Chat Completions，能力受限。
   6. `requires_openai_auth = true`：让 Codex 复用内置的 OpenAI 认证槽位——从 auth.json 读取密钥，作为 Bearer token 发给上面配置的 base_url。少了这一行，Codex 不会把 auth.json 里的密钥用在自定义供应商上。
4. 4

   把 CoderPlan 密钥写入 auth.json

   auth.json 里只有一个字段 OPENAI_API_KEY，值填 CoderPlan 控制台生成的 `sk-` 密钥。字段名带 OPENAI 只是 Codex 复用内置认证槽位的命名习惯：配合上一步的 `requires_openai_auth = true`，这个值会原样作为 Bearer token 发给 config.toml 里配置的 CoderPlan endpoint，和 OpenAI 官方没有关系。

   文件位置

   macOS / Linux 在 `~/.codex/auth.json`；Windows 在 `%USERPROFILE%\.codex\auth.json`（资源管理器地址栏直接输入 `%USERPROFILE%\.codex`）。文件不存在就新建，注意保存为合法 JSON（双引号、无尾逗号）。

   Copy

   {  "OPENAI_API_KEY": "sk-your-api-key"}

   之前用 ChatGPT 登录过怎么办

   ChatGPT 登录态也存在 auth.json 里，写入 API Key 会替换掉登录态。如果需要在 ChatGPT 订阅和 CoderPlan 之间切换，可以用 cc-switch 管理多套配置一键切换，控制台「接入」弹窗也支持一键写入。

5. 5

   跑一次测试任务

   保存两个文件后，在任意项目目录运行 `codex`，先让它做一件小事，比如解释一个函数。能正常回答，说明路由、密钥、模型全链路已通；进入交互界面后也可以用 `/status` 查看当前供应商和模型是否是刚配置的。

   验证调用

   成功时 Codex 会正常返回模型回答；若报 401 或模型不存在，进入下一步排查。

   codex — verify

   ❯codex "用一句话解释 README 在说什么"

   README 介绍了本项目的用途和快速开始方式。
6. 6

   清理旧环境变量并排查 401

   如果之前按旧教程 `export OPENAI_BASE_URL` / `OPENAI_API_KEY` 过，建议从 `~/.zshrc`、`~/.bashrc` 里删掉：新版 Codex 以 config.toml 为准，残留变量不生效，还会干扰排查。遇到 401 unauthorized 时按顺序检查。

   1. auth.json 是否为合法 JSON、密钥是否完整复制（无多余空格、未少字符）。
   2. config.toml 的 TOML 语法是否正确——语法错误会让整段配置静默失效。
   3. base_url 是否以 `/v1` 结尾且不带尾部斜杠。
   4. 控制台确认 API 使用额度与目标模型权限可用。