CLIProxyAPI 教程 – 让 Claude Code 免费用上 GPT 模型

1. 为什么要在 Claude Code 里接 GPT 模型Claude Code 是目前终端里体验相当顺手的编码 Agent但它的默认模型通道只认 Anthropic 协议。问题来了你手上可能同时有 GPT 系列、Codex 系列、Kimi、Gemini 的额度写前端时想用视觉理解强的模型处理长文档时想换上下文更稳的模型结果每次都要退出 Claude Code、切到另一个客户端、重新贴一遍上下文。这种来回切换的损耗比模型本身的能力差距更影响效率。CLIProxyAPI 解决的正是这个断层。它是一个自托管的 AI API 网关把 Codex、Claude Code、Gemini、Grok、Kimi 以及其他 OpenAI 兼容上游统一转换成常见的 OpenAI、Anthropic、Gemini 接口。对 Claude Code 来说它走的是 Anthropic 协议对应/v1/messages而你要接的 GPT 模型则通过 OpenAI 兼容通道暴露出来。网关在中间做协议翻译Claude Code 完全无感。这篇教程聚焦一件事在 Claude Code 里稳定调用 GPT 模型。我会给出可复制的settings.json骨架、连通性验证动作以及实测中踩过的坑。适合已经装好 Claude Code、想扩展模型池的开发者也适合想用统一 Key 管理多模型通道的团队。核心检索词先摆出来CLIProxyAPI 是什么、Claude Code 怎么接 GPT、API 网关怎么配、Codex 通道怎么复用。需要说明的是CLIProxyAPI 本身是开源项目负责协议转换和本地路由而模型通道的 Key 管理、额度分发我用的是 TaoToken 的统一 Key 方案来配合这样不用在多个供应商后台之间反复登录。两者职责不同下面会分开讲。2. TaoToken 前置准备拿到统一 Key 和 API 通道在动 CLIProxyAPI 之前先把上游通道准备好。CLIProxyAPI 需要一个能访问 GPT 模型的 OpenAI 兼容端点以及对应的 API Key。如果你已经有官方 Key可以直接跳到第 3 节如果想让多个模型共用一个 Key、统一计费和额度可以按下面的方式准备。TaoToken 的定位是统一 Key / API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册后在控制台创建 API Key这个 Key 会作为 CLIProxyAPI 的上游凭证。具体动作分三步。第一步打开控制台页面 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后进入 API Keys 管理。第二步新建一个 Key命名建议带上用途比如cliproxy-gpt方便后续在网关配置里对应。第三步复制 Key 字符串注意只显示一次先存到本地密码管理器。这里有个容易忽略的点CLIProxyAPI 的下游 Key给 Claude Code 用的和上游 Key访问 GPT 模型的是两套东西。下游 Key 是你在config.yaml里自己生成的随机串Claude Code 用它来访问本地网关上游 Key 才是 TaoToken 控制台里创建的那个网关用它去请求真实模型。很多人第一次配的时候把两者搞混结果 Claude Code 报 401其实是下游 Key 填错了。如果你还想在浏览器里先验证模型是否可用可以打开模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 选一个 GPT 模型发一条测试消息。能正常返回说明上游 Key 和通道都没问题再去配网关就少一层变量。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Base URL 和鉴权头的标准写法。CLIProxyAPI 的上游配置里Base URL 一般填https://taotoken.net/api鉴权用Authorization: Bearer 你的Key。注意 API 地址不带 UTM 参数保持干净。3. 可复制配置CLIProxyAPI 的 config.yaml 与 Claude Code settings.json这一节是全文的核心给出两份可直接抄的配置。先装 CLIProxyAPI再配网关最后配 Claude Code。3.1 安装 CLIProxyAPI官方项目地址是 https://github.com/router-for-me/CLIProxyAPI 。安装可以直接让 Claude Code 或 Codex 帮你做把下面这段提示词发过去请在 Windows 上帮我安装并配置 CLIProxyAPI。 官方项目地址https://github.com/router-for-me/CLIProxyAPI 要求 1. 只从该项目的官方 GitHub Releases 下载最新版本 2. 根据电脑架构选择 windows_amd64 或 windows_arm64 安装包 3. 安装到当前用户目录下的 CLIProxyAPI 文件夹 4. 复制 config.example.yaml 为 config.yaml 5. 将服务绑定到 127.0.0.1端口使用 8317 6. 关闭远程管理生成随机的管理密码和下游 API Key 7. 保留默认 auth-dir不要读取、复制或展示 OAuth Token 8. 需要登录 Codex 账号时暂停操作告诉我应该执行的命令 9. 登录完成后启动服务并请求 /healthz 和 /v1/models 检查是否成功 10. 最后告诉我 Base URL、API Key 在配置文件中的位置以及当前可用的模型列表。 请直接执行能够自动完成的步骤。遇到报错时先检查日志并尝试修复。安装完成后登录 Codex 账号需要手动在 PowerShell 里执行.\cli-proxy-api.exe --config .\config.yaml --codex-login浏览器会弹出登录页完成后回到终端。这一步的 OAuth Token 会存到auth-dir不要手动去读或复制它。3.2 config.yaml 骨架下面是网关的核心配置骨架重点是port、api-keys和上游openai段。把上游 Base URL 指向 TaoToken 的 API 地址Key 填你在控制台创建的那个。# CLIProxyAPI 配置骨架 port: 8317 host: 127.0.0.1 remote-management: false # 下游 Key给 Claude Code 用的自己生成随机串 api-keys: - sk-local-你的随机下游Key # 上游OpenAI 兼容通道指向 TaoToken openai: - name: taotoken-gpt base-url: https://taotoken.net/api api-key: sk-你的TaoToken上游Key models: - gpt-4o - gpt-4o-mini - o1-mini # Anthropic 协议入口Claude Code 走这里 anthropic: enabled: true path: /v1/messages auth-dir: ./auth几个参数说明。port: 8317是本地监听端口Claude Code 的 Base URL 会指向http://127.0.0.1:8317。remote-management: false关闭远程管理避免局域网内被访问。api-keys下的字符串是下游 KeyClaude Code 请求时带的就是它。openai段的base-url和api-key是上游凭证指向 TaoToken。models列表按你实际可用的模型填不确定就先留空启动后用/v1/models查。3.3 Claude Code settings.json 骨架Claude Code 的配置在用户目录下的.claude/settings.json。核心是把 Anthropic 的 Base URL 指向本地网关并带上下游 Key。{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:8317, ANTHROPIC_API_KEY: sk-local-你的随机下游Key, ANTHROPIC_MODEL: gpt-4o, ANTHROPIC_SMALL_FAST_MODEL: gpt-4o-mini } }这里ANTHROPIC_BASE_URL指向网关ANTHROPIC_API_KEY填下游 KeyANTHROPIC_MODEL指定主模型ANTHROPIC_SMALL_FAST_MODEL指定快速模型。CLIProxyAPI 会把 Anthropic 协议的/v1/messages请求翻译成 OpenAI 兼容请求再转发给上游 GPT 模型。如果你用的是 Coding Plan 长期编码场景建议把模型固定成上下文更稳的那个避免频繁切换导致会话状态丢失。Coding Plan 入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里面有适合 Agent 长任务的额度方案。4. 验证请求从 /healthz 到 Claude Code 实际调用配置写完不代表通了必须做连通性验证。分三层网关自身健康、模型列表可读、Claude Code 实际调用成功。4.1 检查网关健康启动服务窗口不要关.\cli-proxy-api.exe --config .\config.yaml另开一个终端请求健康检查Invoke-RestMethod -Uri http://127.0.0.1:8317/healthz返回ok或类似状态说明网关进程正常。4.2 检查模型列表用下游 Key 请求/v1/models确认上游模型已加载$match Get-Content .\config.yaml | Select-String ^\s*-\s*([^])\s*$ | Select-Object -First 1 $key $match.Matches[0].Groups[1].Value.Trim() $result Invoke-RestMethod -Uri http://127.0.0.1:8317/v1/models -Headers { Authorization Bearer $key } $result.data | Select-Object id能看到模型名称说明四件事同时成立服务启动成功、客户端密钥正确、OAuth 账号已加载、上游模型可访问。如果这里报 401检查下游 Key 是否和config.yaml里api-keys一致如果报 502检查上游 Base URL 和 TaoToken Key。4.3 Claude Code 实际调用打开 Claude Code直接问一个需要模型能力的问题比如让它写一段代码。如果返回正常说明协议翻译链路通了。有个有趣的现象你问 Claude Code 它是什么模型它可能仍然嘴硬说是 Claude 的某个型号但实际芯子已经被换成 GPT 了。这是因为它读的是系统提示里的自我认知而不是真实后端。想更直观地验证可以让 Claude Code 跑一个具体任务比如在当前空目录里开发一个个人任务看板要求原生 HTML/CSS/JS、三列布局、localStorage 存储、JSON 导入导出、深色模式。如果它能直接创建文件并给出可运行结果说明 GPT 模型确实在背后工作。5. 本篇常见错排查配这套东西报错集中在几个地方。我按出现频率排一下。401 Unauthorized最常见。九成是下游 Key 填错。Claude Code 的ANTHROPIC_API_KEY必须和config.yaml里api-keys下的字符串完全一致包括前缀。注意别把 TaoToken 的上游 Key 填到这里。502 Bad Gateway网关能收到请求但转发上游失败。检查openai段的base-url是否是https://taotoken.net/apiapi-key是否是控制台创建的那个。如果 Key 过期或被删也会 502。模型列表为空/v1/models返回空数组。可能是models列表没填或者上游通道没正确加载。先确认 TaoToken 控制台里该 Key 有可用模型再检查config.yaml缩进是否正确YAML 对空格敏感。Claude Code 启动报协议错误检查ANTHROPIC_BASE_URL是否带了/v1后缀。CLIProxyAPI 的 Anthropic 入口是/v1/messagesBase URL 只填到端口即可不要重复加路径。端口被占用8317 被其他进程占用时改config.yaml的port同时同步改 Claude Code 的ANTHROPIC_BASE_URL。两边必须一致。OAuth Token 失效Codex 登录态过期后上游会拒绝请求。重新执行--codex-login登录即可。不要手动去auth-dir里改 Token 文件。排查顺序建议先/healthz再/v1/models最后 Claude Code 实际调用。逐层排除比一上来就怀疑 Claude Code 配置要快得多。接入相关的细节可以对照 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 里的 Key 管理说明确认上游凭证状态。6. 长期编码场景的接入建议如果你只是偶尔在 Claude Code 里试一下 GPT 模型上面的配置够用了。但如果是长期编码、Agent 长任务有几个点值得提前规划。第一模型选择要固定。Claude Code 的会话状态和模型绑定频繁切换模型会导致上下文理解断裂。建议在settings.json里把ANTHROPIC_MODEL固定成你主力用的那个需要换模型时再手动改配置重启。第二下游 Key 和上游 Key 分离管理。下游 Key 泄露只影响本地网关上游 Key 泄露影响额度。定期轮换上游 Key在 TaoToken 控制台删除旧 Key 即可。第三网关进程要常驻。CLIProxyAPI 启动后窗口不能关建议用 Windows 任务计划或 nssm 注册成服务开机自启。这样 Claude Code 随时可用不用每次手动拉起来。第四多模型路由可以后续扩展。CLIProxyAPI 支持同一供应商配多个账号也支持 Codex、Claude、Antigravity、Kimi、xAI 等登录流程。你可以在config.yaml里加多个上游段按任务类型分流。写前端时走视觉强的模型处理长文档时走上下文稳的模型。长期编码和 Agent 场景Coding Plan 的额度模型更适合入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。配合 CLIProxyAPI 的本地网关Claude Code 就能在一个终端里调用多个模型通道不用来回切客户端。这套组合实测下来最大的收益不是省钱而是把切换成本降到了零——你只需要在配置里改一行模型名剩下的交给网关。