1. 项目概述一个让 Claude Code 无缝切换 ChatGPT 后端的代理如果你和我一样是 Claude Code 的深度用户同时又持有 ChatGPT Plus/Pro 订阅那你可能也遇到过类似的困境Anthropic 的 API 配额用完了或者某个任务你觉得 GPT 的 Codex 模型可能更擅长但又不愿意离开已经用顺手的 Claude Code 界面、快捷键和 MCP 工具生态。这个项目chatgpt-codex-proxy就是为了解决这个痛点而生的。简单来说它是一个运行在你本地的 API 代理服务器。它的核心功能是“偷梁换柱”当你的 Claude Code 客户端就是那个命令行工具claude向 Anthropic 的官方 API 发送请求时这个代理会拦截这些请求将其“翻译”成 ChatGPT Codex 后端能理解的格式然后使用你的 ChatGPT 账户权限去调用 Codex最后再把 Codex 的响应“翻译”回 Claude Code 能理解的 Anthropic API 格式。对你而言整个过程是完全无感的你依然在终端里敲着claude命令用着/write、/edit这些熟悉的指令但背后干活的大脑已经换成了 GPT。这不仅仅是省下一个 API 密钥的钱更重要的是它保留了完整的工作流连续性。尤其是 Claude Code 赖以成名的 MCPModel Context Protocol工具生态比如直接操作文件的 Stitch、管理任务的 Linear、甚至控制浏览器的 Chrome DevTools通过这个代理都能原封不动地让 GPT 模型调用。这一点是其他任何单纯的“API 兼容层”项目都难以做到的。2. 核心设计思路与方案选型2.1 为什么选择代理模式而非客户端修改市面上已经有一些项目如 ChatMock提供了 OpenAI 兼容的 API 端点但它们通常要求你改变使用方式比如换用其他兼容 OpenAI 的客户端。chatgpt-codex-proxy选择了一条更“狡猾”但也对用户更友好的路完全兼容 Anthropic Messages API。Claude Code 客户端在启动时会读取两个关键的环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。前者指定 API 的基地址后者是认证密钥。这个代理的核心思路就是我们提供一个本地服务其 API 路径和请求/响应格式与 Anthropic 官方 API (https://api.anthropic.com/v1/messages) 完全一致。然后我们只需让 Claude Code 连接到我们的本地服务通过修改ANTHROPIC_BASE_URL并随便设置一个ANTHROPIC_API_KEY因为代理内部会使用 ChatGPT 的 OAuth 登录信息这个 Key 实际上不会被用到就完成了“劫持”。这种设计的优势显而易见零侵入性无需修改 Claude Code 客户端的任何一行代码。这对于一个闭源的命令行工具来说是唯一可行的方案。功能完整性由于完全模拟了官方 APIClaude Code 的所有功能包括流式响应、多轮对话、系统提示词尤其是工具调用都能得到支持。配置简单用户只需要改两个环境变量其他一切照旧。2.2 技术栈选择Node.js Express项目选择了 Node.js 生态具体是 Express 框架。这是一个非常务实的选择快速原型与迭代对于处理 HTTP 请求、进行 JSON 转换、管理中间件这类任务Express 生态成熟开发效率高。良好的流处理支持项目需要处理 Server-Sent Events (SSE) 以实现流式响应Node.js 的 Stream API 和 Express 对此有很好的支持。丰富的生态系统用于 OAuth 认证、HTTP 客户端、配置文件解析等周边功能的 NPM 包唾手可得。适合个人工具作为一个主要在本地运行的个人效率工具Node.js 的轻量级和跨平台特性非常合适。从项目结构看它采用了清晰的模块化设计将认证 (auth.ts)、请求/响应转换 (transformers/)、Codex 客户端 (codex/)、MCP 工具集成 (mcp/) 等关注点分离代码可读性和可维护性都很好。2.3 核心挑战与解决方案协议桥接与 MCP 工具注入这个项目本质上是一个复杂的“协议转换器”。它需要处理两个不同提供商Anthropic 和 OpenAI/ChatGPT在 API 设计上的诸多差异。这不仅仅是字段名映射那么简单。1. 请求/响应格式转换消息角色映射Anthropic 使用user,assistant而 Codex 使用human,assistant。代理需要做转换。系统提示词Anthropic 的system字段需要映射到 Codex 的instructions字段。工具调用格式两者都支持tool_use和tool_result但具体的 JSON Schema 可能有细微差别需要确保无损转换。流式响应两者都使用 SSE但事件名称和数据块格式不同。代理需要实时翻译数据流。2. MCP 工具注入项目的杀手锏这是本项目区别于其他简单代理的核心。Claude Code 的 MCP 工具配置存储在~/.claude.json文件中。当 Claude Code 连接到官方后端时它会将这些工具的信息“注册”到会话中。但当我们把请求转发给 Codex 时Codex 后端对这些工具一无所知。项目的解决方案非常巧妙代理在启动时主动去读取用户的~/.claude.json文件然后自己作为“客户端”去连接配置好的每一个 MCP 服务器无论是 HTTP 还是 stdio 类型。连接成功后它会向 MCP 服务器发起tools/list请求获取所有可用工具的 Schema名称、描述、参数等并将这些 Schema 缓存在内存中。此后每当代理收到 Claude Code 发来的/v1/messages请求时它除了转换基本消息内容还会把缓存的 MCP 工具 Schema 附加到请求的tools数组中再转发给 Codex。这样Codex 在生成回复时就能“看到”并尝试调用这些工具。当 Codex 返回一个tool_use响应时代理会将其转换回 Anthropic 格式发回给 Claude Code。Claude Code 接收到后会像往常一样去执行真正的 MCP 工具调用并将结果 (tool_result) 通过代理传回给 Codex完成整个循环。3. 并行工具调用的安全处理Claude 和 GPT 都支持parallel_tool_calls并行工具调用。但对于文件操作类工具如编辑、写入、删除文件或 Bash 命令执行并行调用可能导致竞态条件或不可预知的结果。项目对此做了安全处理当检测到请求中包含这类“有状态”或“可变”的工具时代理会自动在转发给 Codex 的请求中禁用parallel_tool_calls选项强制串行执行确保了操作的安全性。3. 从零开始的详细部署与配置指南3.1 环境准备与项目初始化首先确保你的系统满足基本要求Node.js版本需要在 18.x 或以上。你可以通过node -v命令检查。npm通常随 Node.js 一起安装用npm -v检查。Git用于克隆代码仓库。一个有效的 ChatGPT Plus 或 Pro 订阅这是调用 Codex 后端的前提。接下来我们获取并初始化项目# 1. 克隆项目代码到本地 git clone https://github.com/insightflo/chatgpt-codex-proxy.git cd chatgpt-codex-proxy # 2. 安装项目依赖 # 这里使用 npm install 即可。项目使用 TypeScript依赖包包括 express、axios 等。 npm install # 3. 构建项目将 TypeScript 编译为 JavaScript # 查看 package.json通常 npm run build 命令会执行 tsc 编译。 npm run build注意如果npm run build失败请先检查tsconfig.json是否存在以及 TypeScript 是否已正确安装通常是开发依赖。你也可以尝试直接运行npx tsc。3.2 认证登录关联你的 ChatGPT 账户项目使用 OAuth 2.0 进行认证这意味着你不需要处理复杂的 API Key只需用浏览器登录你的 ChatGPT 账户即可。# 运行登录命令 npm run login执行这个命令后你的默认浏览器会自动打开一个 ChatGPT 的官方登录页面。请使用你的 ChatGPT Plus/Pro 账户登录并授权。授权成功后浏览器页面会提示“登录成功”你可以关闭它。此时代理已经将获取到的认证令牌Token安全地存储在你的本地文件系统中通常是~/.config/chatgpt-codex-proxy/token.json。实操心得第一次登录时请确保浏览器没有禁用弹出窗口。如果登录页面没有自动打开检查命令行输出可能会有一个 URL你可以手动复制到浏览器中打开。登录过程只会在本地和 ChatGPT 官方服务器之间通信代理项目本身不会获取你的密码。你可以随时查看登录状态或登出# 查看当前认证状态 npm run status # 删除本地存储的令牌登出 npm run logout3.3 启动代理服务器完成登录后就可以启动代理服务了。项目提供了开发模式和“生产”模式。# 开发模式启动支持代码热重载修改代码后自动重启 npm run dev # 或者以生产模式启动编译后的代码运行 npm run start默认情况下代理服务器会启动在http://127.0.0.1:19080。你会在终端看到服务器成功启动的日志。关键检查点看到类似Server is running on http://127.0.0.1:19080的日志。可以另开一个终端用curl测试健康检查端点curl -fsS http://127.0.0.1:19080/health应该返回OK。3.4 配置 Claude Code 客户端使用代理这是最关键的一步告诉 Claude Code 去连接我们刚启动的本地代理而不是官方的 Anthropic 服务器。方法一临时环境变量推荐初次测试在新的终端窗口中执行以下命令export ANTHROPIC_BASE_URLhttp://127.0.0.1:19080 export ANTHROPIC_API_KEYdummy # 这个值任意但不能为空 claude现在启动的 Claude Code 会话其所有请求都将发送到你的本地代理并由 ChatGPT Codex 后端处理。方法二创建 Shell 别名/函数长期使用为了避免每次都要输入环境变量可以将项目 README 中提供的gpt()shell 函数添加到你的~/.zshrc或~/.bashrc文件中。# 编辑你的 shell 配置文件例如 nano ~/.zshrc # 在文件末尾添加以下函数 gpt() { emulate -L zsh local proxy_port${CHATGPT_CODEX_PROXY_PORT:-19080} local token${ANTHROPIC_AUTH_TOKEN:-${ANTHROPIC_API_KEY:-dummy}} export ANTHROPIC_BASE_URLhttp://127.0.0.1:${proxy_port} export ANTHROPIC_AUTH_TOKEN$token export ANTHROPIC_API_KEY${ANTHROPIC_API_KEY:-$token} export API_TIMEOUT_MS${API_TIMEOUT_MS:-90000} export PASSTHROUGH_MODE${PASSTHROUGH_MODE:-true} unset CLAUDE_CONFIG_DIR echo Using local Codex proxy on :${proxy_port} claude $ } # 保存文件后重新加载配置 source ~/.zshrc之后你只需要在终端中输入gpt就可以一键启动连接了代理的 Claude Code。gpt --model claude-3-5-sonnet-20241022这样的命令也能正常工作。4. 高级配置与核心功能详解4.1 模型映射与 Passthrough 模式Claude Code 请求中会携带模型名称如claude-3-5-sonnet-20241022。代理需要决定将其转发给哪个 Codex 模型。这里有两种模式1. Passthrough 模式 (默认PASSTHROUGH_MODEtrue)在此模式下代理几乎不做任何修改直接将 Claude Code 发送的模型名转发给 Codex 后端。这意味着你可以在 Claude Code 中直接指定 Codex 的模型名gpt --model gpt-5.2-codex gpt --model gpt-5.3-codex-spark这给了你最大的灵活性但需要你记住 Codex 的模型名。2. 映射模式 (PASSTHROUGH_MODEfalse)在此模式下代理内置了一个映射表自动将 Claude 的模型系列映射到推荐的 Codex 模型上。例如claude-3-5-sonnet-20241022-gpt-5.2-codexclaude-3-haiku-20240307-gpt-5.3-codex-spark你可以通过环境变量覆盖默认映射# 在启动代理前设置或放在 .env 文件中 export ANTHROPIC_DEFAULT_SONNET_MODELgpt-5.3-codex-xhigh # 为 Sonnet 系列指定更高推理强度的模型 export ANTHROPIC_DEFAULT_HAIKU_MODELgpt-5.3-codex-spark # 为 Haiku 指定速度优化模型如何选择如果你习惯使用 Claude 的模型名或者想在不同模型间快速切换而不改命令就用映射模式。如果你追求极致的控制力明确知道自己想用哪个 Codex 变体就用 Passthrough 模式。4.2 MCP 工具注入配置这是本项目的精髓。要让 GPT 也能使用你的 MCP 工具如 Stitch 操作文件、Linear 管理任务你需要显式启用它。首先确保你的 Claude Code 已经配置好了 MCP 服务器~/.claude.json文件中有正确的配置。然后创建或编辑项目根目录下的.env文件复制.env.examplecp .env.example .env nano .env在.env文件中找到并设置PROXY_MCP_SERVERS变量# 启用所有在 ~/.claude.json 中配置的 MCP 服务器 PROXY_MCP_SERVERSall # 或者只启用特定的服务器名字必须与 ~/.claude.json 中的 key 匹配 PROXY_MCP_SERVERSstitch,linear,chrome-dev-tools保存后重启你的代理服务器。在启动日志中你应该能看到类似以下的输出表明 MCP 工具加载成功[mcp-registry] connecting to: stitch, linear, chrome-dev-tools [mcp-registry] stitch: 8 tools loaded [mcp-registry] linear: 6 tools loaded [mcp-registry] chrome-dev-tools: 12 tools loaded [mcp-registry] ready: 26 total MCP tools现在当你使用gpt命令启动会话时GPT 模型就能“看到”并使用这些工具了。你可以尝试让 GPT 帮你写文件 (/write)、编辑代码 (/edit)或者通过 Linear 工具创建任务。重要提示MCP 工具注入是代理在启动时一次性完成的。如果你在代理运行期间在 Claude Code 里添加或删除了 MCP 服务器配置需要重启代理才能生效。4.3 推理强度Effort控制Claude Code 界面有一个“推理强度”Effort滑块但这仅对原生 Claude 模型有效。当使用 GPT 模型时这个设置不会被发送到 API。为了控制 GPT Codex 模型的推理强度这会影响速度、成本和输出质量你需要通过选择不同的模型变体来实现。Codex 模型通常有后缀来标识其“努力等级”-spark: 低强度速度极快适合简单补全。-low/-medium: 低/中强度。-high: 高强度默认选择。-xhigh: 极高强度用于最复杂的问题。配置方法在 Passthrough 模式直接在命令中指定完整模型名如gpt --model gpt-5.3-codex-xhigh。在映射模式通过环境变量为特定 Claude 家族指定 Codex 模型如export ANTHROPIC_DEFAULT_SONNET_MODELgpt-5.3-codex-xhigh。全局默认在.env文件中设置PROXY_DEFAULT_EFFORThigh。但注意这只是一个后备选项优先级低于上述两种方式。5. 实战问题排查与经验分享即使配置正确在实际使用中也可能遇到各种问题。下面是我在深度使用过程中总结的常见问题及其解决方法。5.1 连接与认证问题问题运行npm run login后浏览器没有自动打开或登录失败。检查命令行是否输出了一个 URL可以手动复制到浏览器打开。可能原因某些系统或终端配置可能阻止了自动打开。确保你没有禁用浏览器的弹出窗口。解决手动打开链接完成 OAuth 流程。如果登录页面提示错误请确认你的 ChatGPT 账户是 Plus/Pro 订阅状态。问题启动gpt后Claude Code 提示“Invalid API Key”或“Authentication Error”。检查首先确认代理服务器是否正在运行 (npm run dev的终端是否活跃)。检查运行curl -fsS http://127.0.0.1:19080/health。如果不返回OK说明代理服务未正常运行。检查环境变量ANTHROPIC_BASE_URL是否设置正确echo $ANTHROPIC_BASE_URL应该显示http://127.0.0.1:19080。解决ANTHROPIC_API_KEY可以设置为任意非空字符串如dummy。重点是ANTHROPIC_BASE_URL必须指向正确的本地代理地址和端口。5.2 MCP 工具不工作问题代理日志显示 MCP 工具已加载但在 Claude Code 中 GPT 似乎看不到工具或者调用失败。检查代理启动日志中是否成功加载了你期望的工具数量如果显示0 tools loaded可能是PROXY_MCP_SERVERS配置错误或者~/.claude.json中的服务器名不匹配。检查你的 MCP 服务器本身是否运行正常可以先用原生 Claude Code不通过代理测试一下工具是否能正常工作。一个常见陷阱某些 MCP 服务器尤其是 stdio 类型的可能需要特定的环境变量或路径才能启动。代理进程在启动时加载 MCP 服务器其环境可能与你的交互式 Shell 环境不同。确保 MCP 服务器的命令在代理的上下文中可执行。排查步骤在.env中设置PROXY_MCP_SERVERSall重启代理仔细观察启动日志有无报错。尝试先只启用一个最简单的 MCP 服务器比如本地的文件系统工具进行测试。查看代理的详细日志如果开启了日志输出看是否有 MCP 握手或工具列表请求失败的信息。5.3 性能与稳定性问题问题响应速度变慢或者偶尔出现超时错误。网络因素代理本身在本地延迟极低。速度瓶颈可能在你的网络连接到 ChatGPT 服务器的速度或者 ChatGPT 后端当时的负载。模型选择使用-xhigh等更高强度的模型响应时间会显著长于-spark或-low模型。根据任务复杂度合理选择模型。超时设置Claude Code 客户端和代理都有超时设置。如果任务非常复杂GPT 需要长时间推理可能会触发超时。你可以尝试增加超时时间# 启动 gpt 时设置更长的超时单位毫秒 API_TIMEOUT_MS180000 gpt代理日志检查代理服务器的控制台输出看是否有错误信息。有时 ChatGPT 后端会返回非标准错误代理转换时可能出错。问题长时间运行后代理似乎“卡住”了不再响应。可能原因内存泄漏或某个连接未正确关闭。作为本地开发工具长时间运行的稳定性可能不如生产级软件。解决定期重启代理服务 (CtrlC停止再npm run dev)。可以考虑使用pm2等进程管理工具来守护和自动重启代理进程但这需要额外的配置。5.4 模型与功能限制需要清醒认识到这不是一个完美的无缝替代方案。由于 Anthropic 和 OpenAI 的 API 存在固有差异某些功能无法支持或受限功能特性支持情况说明与应对基础对话✅ 完整支持文本聊天、多轮对话都没问题。流式输出✅ 完整支持SSE 流式传输体验与原版一致。系统提示词✅ 支持自动从system映射到instructions。工具调用✅核心优势完整支持包括 MCP 工具注入。图像输入⚠️有限支持Codex 后端对图像输入的支持可能不如 Claude Vision 全面复杂图像描述可能出错。Temperature❌不支持ChatGPT Codex 后端不支持动态调整temperature参数。输出随机性固定。Max Tokens❌不支持无法通过 API 限制生成的最大 token 数由后端控制。停止序列⚠️可能不支持Anthropic 的stop_sequences参数可能无法完美映射到 Codex。个人经验对于纯代码生成、文本分析、逻辑推理等任务这个代理工作得非常好几乎感觉不到差异。但在涉及创造性写作需要调整随机性或需要精确控制生成长度时你会感受到限制。我的建议是将其视为一个功能增强和后备方案而不是完全的 Claude 替代品。当 Claude 配额用尽或者你明确觉得某个任务 GPT 更擅长时再切换到代理模式。6. 安全考量与生产部署建议项目作者在 README 中明确强调此代理设计为仅在本地个人机器上使用。这是非常重要的安全提示。为什么令牌安全npm run login获取的 OAuth 令牌具有访问你 ChatGPT 账户的权限。该令牌默认存储在本地文件。如果代理暴露在公网 (0.0.0.0)且没有额外的认证任何人都可能向你的代理发送请求消耗你的 ChatGPT 额度。MCP 工具暴露MCP 服务器可能具有很高的权限如文件读写、执行命令。如果代理暴露攻击者可能通过它间接调用你的 MCP 工具造成安全风险。安全使用准则始终绑定到 localhostnpm run dev默认就是127.0.0.1不要修改。保护令牌文件确保存储令牌的文件如~/.config/chatgpt-codex-proxy/token.json权限设置为600仅所有者可读写。谨慎对待 MCP 配置只启用你信任的 MCP 服务器。定期检查~/.claude.json中的配置。如果你必须在服务器上部署不推荐强制认证在代理前设置一个反向代理如 Nginx配置 HTTP 基本认证或更安全的 JWT 认证。严格限制 CORS只允许你信任的源域名访问。实施速率限制防止滥用。使用 HTTPS绝对不要在不安全的网络上传输令牌和对话内容。监控日志密切关注访问日志和错误日志。对于绝大多数用户最好的做法就是让它安安静静地运行在你的笔记本电脑上作为一个提升个人工作效率的“瑞士军刀”。