GPT + Codex CLI + CodexPro 三位一体：AI 编程协作工作流配置与验证

1. 为什么要把 GPT、Codex CLI、CodexPro 拆开用

很多人第一次把 GPT 接到本地仓库后，会本能地想让它在聊天窗口里把活全干完：读文件、改代码、跑测试、写文档，一条龙。我试过，结果是上下文越滚越长，改到第三个文件时它已经忘了第一个文件为什么改，最后连自己动了哪些路径都说不清。

GPT、Codex CLI、CodexPro 这三个东西，名字听着像一家人，实际职责完全不同。GPT 是那个能跟你讨论架构、帮你把模糊需求拆成明确任务的角色；Codex CLI 是真正在本地终端里读仓库、改文件、跑命令的执行者；CodexPro 则是把 GPT 会话和本地工作区连起来的连接层，让 GPT 能通过 MCP 看到你项目里的文件状态。三者分工清楚，AI 编程才不会退化成一场没有边界的聊天。

这篇要解决的问题很具体：怎么用一套统一的 Key 和 API 通道，把这三个工具串成一条可复现的链路。你会在下面看到settings.json和config.toml的骨架、多工具接力改代码跑测试的完整过程，以及能直接复制粘贴的连通性验证动作。适合已经能让 GPT 访问本地仓库、但流程还很乱的开发者。

2. 前置准备：统一 Key 与 API 通道

在配任何工具之前，先把通道统一。三个工具如果各用各的 Key、各走各的地址，排障时你会分不清是哪个环节断了。我的做法是全部指向同一个 API 入口，Key 也复用同一把。

TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 base_url 使用。Key 在控制台的 API Keys 页面生成，生成后先别急着填进各个工具，先单独验证一次通道是否通。

curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ | head -c 400

如果返回里能看到模型列表的 JSON 结构，说明 Key 和通道都没问题。这一步别跳过，后面 Codex CLI 报 401 的时候你会感谢自己先验过。

环境变量建议统一命名，避免每个工具读不同的变量名：

export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

把这两行写进~/.zshrc或~/.bashrc，新开终端自动生效。Windows 下用系统环境变量面板设置，或者 PowerShell 里$env:TAOTOKEN_API_KEY="sk-..."临时用。

注意：Key 不要硬编码进任何会提交到 Git 的文件。settings.json和config.toml里用环境变量引用，别直接写明文。

3. 可复制配置：settings.json 与 config.toml 骨架

3.1 Codex CLI 的 config.toml

Codex CLI 读取~/.codex/config.toml。核心是把模型提供方指向统一通道，并声明模型名。下面是一个能直接用的骨架：

# ~/.codex/config.toml model = "gpt-4o" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat" [sandbox] mode = "workspace-write" [approval] policy = "on-request"

几个参数说明一下。wire_api = "chat"表示走 Chat Completions 协议，兼容性最好。sandbox.mode = "workspace-write"允许 Codex 在当前工作区内写文件，但不会碰工作区外的路径。approval.policy = "on-request"意味着执行敏感命令前会问你，既不会完全放手，也不会每步都拦。

如果你想让 Codex 在跑测试时更顺，可以把 approval 调成never，但只建议在容器或临时目录里这么干。本地主力仓库还是保留on-request。

3.2 CodexPro 的 settings.json

CodexPro 作为 MCP 连接层，配置放在~/.codexpro/settings.json。它需要知道两件事：连哪个 API 通道，以及暴露哪个本地工作区给 GPT 会话。

{ "api": { "baseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "model": "gpt-4o" }, "workspace": { "root": "${HOME}/projects/my-repo", "readOnly": false, "ignore": [".git", "node_modules", "dist", ".env"] }, "mcp": { "transport": "stdio", "serverName": "codexpro" } }

workspace.root指向你要协作的仓库根目录。ignore列表很重要，把.git、node_modules、.env排除掉，避免 GPT 会话读到敏感信息或把依赖目录当成源码分析。readOnly设成false表示允许通过 CodexPro 触发写操作，但实际写还是由 Codex CLI 执行，CodexPro 只负责传递意图和读取状态。

3.3 两个配置的职责边界

把这两个文件配好，三个工具就共享了同一把 Key 和同一个 base_url。后面任何一环出问题，你只需要检查这一个通道。

4. 验证请求：从连通性到多工具接力

4.1 第一步：验证 Codex CLI 能读到模型

配完config.toml后，在终端里跑：

codex --version codex "列出当前目录下的文件，不要修改任何东西"

如果 Codex 能返回文件列表，说明它已经通过taotokenprovider 连上了模型，并且沙箱允许读取。如果报401，回去检查TAOTOKEN_API_KEY是否在当前 shell 里生效；如果报model not found，检查model字段拼写。

4.2 第二步：验证 CodexPro 的 MCP 连接

CodexPro 通常以 MCP server 形式启动。启动后，在 GPT 会话里应该能看到codexpro这个 server 暴露的工具。验证方式是让 GPT 调用一次只读操作：

请通过 codexpro 读取 workspace 根目录下的 README.md 前 20 行。

如果 GPT 能返回 README 内容，说明 CodexPro 的workspace.root配对了，MCP 传输也通了。如果返回空或报错，检查settings.json里的root路径是否存在，以及ignore是否误伤了目标文件。

4.3 第三步：多工具接力改一个真实文件

现在走一遍完整链路。目标：给README.md补充安装说明。

先在 GPT 会话里让它产出 handoff，保存到.agents/codex/inbox/：

mkdir -p .agents/codex/inbox .agents/codex/reports

GPT 产出的 handoff 内容大致如下，你手动存成HANDOFF-0002-update-readme.md：

# HANDOFF-0002: Update README Installation ## Objective 补充 README.md 的安装说明，包含环境要求、安装命令、验证步骤。 ## Scope 仅修改 README.md，不动其他文件。 ## Acceptance Criteria - 包含 Prerequisites 小节 - 包含 Installation 小节 - 包含 Verification 小节

然后在终端里让 Codex CLI 执行这个 handoff：

codex "执行 .agents/codex/inbox/HANDOFF-0002-update-readme.md，修改后运行 git diff -- README.md 并把结果写入 .agents/codex/reports/HANDOFF-0002-report.md"

Codex 会读取 handoff、编辑 README、跑 diff，然后写报告。执行前先看一眼 Git 状态：

git status --short

执行后再看一次，确认只有 README.md 被改动：

git status --short git diff -- README.md

4.4 第四步：GPT 复审报告

Codex 写完后，.agents/codex/reports/HANDOFF-0002-report.md里会有改动摘要。回到 GPT 会话，通过 CodexPro 读取这份报告：

请通过 codexpro 读取 .agents/codex/reports/HANDOFF-0002-report.md，判断验收标准是否满足，并给出下一轮建议。

GPT 读到报告后，会告诉你三个小节是否都补上了、有没有遗漏。如果满足，这一轮就闭环了；如果不满足，它再产出一份新的 handoff，进入下一轮。

5. 本篇常见错排查

5.1 Codex CLI 报 401 或 403

最常见的原因是环境变量没生效。config.toml里写的是env_key = "TAOTOKEN_API_KEY"，Codex 启动时会去读这个变量。如果你在~/.zshrc里 export 了但没 source，或者用的是 GUI 启动的终端，变量可能不在。验证方法：

echo $TAOTOKEN_API_KEY

输出为空就是没生效。重新 source 或新开终端。

5.2 CodexPro 读不到文件

先确认settings.json里的workspace.root是绝对路径，且没有拼错。然后检查ignore列表，如果你把docs或src误加进去了，GPT 就看不到那些目录。另外，CodexPro 启动时的工作目录和root是两回事，别混淆。

5.3 Codex 改了不该改的文件

这是沙箱和 handoff 范围没对齐。sandbox.mode = "workspace-write"允许写整个工作区，但 handoff 里写了Scope: 仅修改 README.md。如果 Codex 越界改了别的文件，说明 handoff 的约束不够强。解决办法是在 handoff 里加一条Files to Modify白名单，并在执行后立刻git diff --stat检查。

5.4 MCP 连接超时

CodexPro 的 MCP 传输默认走 stdio，如果 GPT 客户端配置的是 HTTP 传输，就会连不上。检查settings.json里的mcp.transport是否和客户端一致。stdio 模式下，CodexPro 必须由客户端作为子进程启动，不能单独跑在另一个终端里。

5.5 模型返回内容被截断

长任务里 GPT 或 Codex 的输出可能被 max tokens 截断。Codex CLI 可以在config.toml里加max_output_tokens，但更根本的办法是把大任务拆成多个 handoff，每个 handoff 只覆盖一个小目标。一次改三个文件、跑五条命令，截断概率很高。

6. 把通道固定下来，长期跑这套工作流

这套工作流跑顺之后，你会发现最省心的做法是：所有工具共用同一个 API 通道，Key 只维护一份，base_url 只改一处。Codex CLI 负责本地执行，CodexPro 负责把 GPT 会话和仓库连起来，GPT 负责规划和复审。三者之间靠.agents/codex/inbox/和.agents/codex/reports/两个目录传递 handoff 和报告，Git 作为最后的安全网。

如果你还没生成 Key，可以去控制台的 API Keys 页面创建一把，然后按上面的curl先验一次通道。接入文档里有各工具更细的参数说明，配config.toml和settings.json时对着看会快很多。长期做编码和 Agent 任务的话，Coding Plan 的额度模型更适合这种多轮接力的场景，不用每轮都担心 token 消耗。通道固定下来之后，你只需要关注 handoff 写得清不清楚、验收标准定得够不够硬，剩下的交给 Codex 执行就行。