我的知识与提示词库

Appearance

Claude Code + Codex MCP 协作完整方案（重梳理版） ​

更新时间：2026-02-27

1. 目标与分工 ​

  • Claude Code：主流程编排、代码实现、最终交付。
  • Codex MCP：关键节点复核、反证、风险审查。

2. 推荐架构 ​

2.1 个人版（推荐先跑通） ​

text
Claude Code (local) -> codex mcp-server (stdio)

2.2 团队版（共享服务） ​

text
Claude Client -> HTTPS(Nginx) -> supergateway(HTTP MCP)
              -> codex mcp-server(stdio)

3. 一次性配置（个人版） ​

3.1 注册 Codex MCP（只需一次） ​

bash
claude mcp add --scope user codex -- codex mcp-server

注意：

  • codex 是服务器名称（位置参数），不是选项。
  • 错误写法 --codex 会报：unknown option '--codex'。

3.2 验证 ​

bash
claude mcp list
claude mcp get codex

进入会话后：

text
/mcp

看到 codex 即可用。

4. 日常使用流程 ​

  1. 启动 claude。
  2. 在会话里执行 /mcp 确认 codex 在线。
  3. 在关键节点调用审查：
    • 设计阶段：让 codex 做反证（风险/反例/最小改动）。
    • 实施阶段：里程碑审查（接口、鉴权、数据模型、性能）。
    • 验收阶段：回归风险与缺失测试。

示例提示词：

text
请调用 codex 对当前方案做反证审查：
1) 最高风险3项
2) 每项反例
3) 最小修改建议
4) 需要新增的测试

5. 认证策略（重点） ​

5.1 核心区别 ​

  • Claude Code 自身请求失败（报 Please run /login）：是 Claude 登录态 问题。
  • codex mcp-server 失败：才是 codex 或中转配置问题。

5.2 Codex 走 API Key（不走 OAuth） ​

bash
export OPENAI_API_KEY='你的key'
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

应看到：Logged in using an API key ...

~/.codex/config.toml 示例（中转场景）：

toml
model_provider = "relay"

[model_providers.relay]
name = "relay"
base_url = "https://你的中转域名"
wire_api = "responses"
requires_openai_auth = false

关键点：

  • requires_openai_auth = false 才是不走 OAuth。
  • 中转服务端也必须支持 Authorization: Bearer <API_KEY>，否则仍可能 401。

6. 你这次问题的定位结论 ​

你遇到的报错：

text
API Error: 401 ... OAuth token has expired ... Please run /login

最终定位为：Claude Code 主 API OAuth 令牌过期，不是 claude mcp add 语法问题，也不是 codex 注册状态问题。

修复：

bash
claude auth logout
claude auth login
claude auth status

会话内也可直接执行 /login 触发重登。

7. 常见故障速查 ​

7.1 unknown option '--codex' ​

原因：把服务器名写成了 flag。 修复：

bash
claude mcp add --scope user codex -- codex mcp-server

7.2 codex: command not found ​

原因：本机未安装或 PATH 不可见。 修复：先安装 codex CLI，并在同一终端环境下重试。

7.3 API Error: 401 ... Please run /login ​

优先处理 Claude 登录态：

bash
claude auth login

若仍失败，再检查中转鉴权策略与 codex provider 配置。

7.4 claude mcp list 显示有 codex，但会话不可用 ​

修复顺序：

  1. 重启 claude 会话。
  2. claude mcp get codex 检查命令是否仍是 codex mcp-server。
  3. 必要时重新注册：
bash
claude mcp remove codex -s user
claude mcp add --scope user codex -- codex mcp-server

8. 团队版最小落地（摘要） ​

  1. codex mcp-server 作为后端进程。
  2. supergateway 将 stdio 转为 streamable HTTP。
  3. Nginx 暴露 /mcp（建议仅 443，对外隐藏内部端口）。
  4. 客户端通过 HTTP MCP 注册：
bash
claude mcp add --transport http --scope user \
  -H "X-MCP-Key: <TOKEN>" \
  codex-remote https://mcp.example.com/mcp

9. 是否每次都要 mcp add？ ​

不需要。 --scope user 是持久配置，注册一次即可跨会话生效。

仅在以下情况需要重加：

  • 手动 remove 过；
  • 换机器/换账号；
  • 启动命令或参数变更；
  • 使用 --strict-mcp-config（会忽略默认配置）。

10. 最短可执行清单 ​

bash
# 1) 只做一次：注册
claude mcp add --scope user codex -- codex mcp-server

# 2) 每次开工前：检查
claude mcp list
claude mcp get codex

# 3) 会话内检查
/mcp

# 4) 如出现 OAuth 过期
/login
# 或：
claude auth login