手里的AI编码工具越来越多Codex CLI、Claude Code、xAI 的 Grok 工具链……每个工具都默认绑定一家模型供应商。Codex 只认 OpenAI 的模型Claude Code 默认走 Anthropic 的接口想换个模型就得翻配置、改环境变量、折腾认证方式一天里有半天耗在这上面。CLIProxyAPI 要解决的就是这个痛点在本地起一个统一的 API 请求网关把多个模型服务收口到一个地址上。Codex、Claude、xAI甚至 DeepSeek都能通过这一个入口按需路由切换模型不再是改代码改配置的体力活。这篇文章我会把 CLIProxyAPI 的本地部署从头到尾走一遍包括为什么需要这样一层网关、部署前怎么规划、配置文件怎么写、怎么把三个主流 CLI 工具接进来以及我在实际使用中踩过的坑。适合已经装了 Codex 或 Claude Code、想接入更多模型服务的开发者也适合正在为每个工具一套配置头疼的人参考。内容不涉及太深的内核原理照着操作就能跑通。1. 为什么要统一接入CLI 工具与模型供应商的绑定现状1.1 每个 CLI 工具都在逼你做选择题先盘一下现状。Codex CLI 是 OpenAI 官方出的命令行编程助手默认调用 OpenAI 的模型服务模型名、接口路径、鉴权方式都是按 OpenAI 的规范来的。Claude Code 是 Anthropic 家的终端工具走的是 Anthropic Messages API请求体格式和 Codex 完全不同。xAI 的 Grok 系列模型接口虽然兼容 OpenAI 格式但它自己也有独立的 base URL 和模型命名体系。问题就出在这里每多装一个 CLI 工具就多一套需要维护的配置。API Key 分散在多个环境变量里模型的可用性、计费方式、速率限制也各不相同。你很可能遇到这种场景——Codex 默认的模型在当前账号下不可用但你想继续用 Codex 这个客户端只是把底层模型换成 DeepSeek 或者 Grok。又或者你想在 Claude Code 里用别的模型但它的请求格式是 Anthropic 的普通 OpenAI 兼容接口根本不认。我打个比方这就像家里买了一堆电器每个都自带一个专用插头插座还不通用。你只能在墙上装一堆转换头用哪个插哪个。时间一长转换头比电器还多哪个插头对应哪个电器全靠记忆。CLIProxyAPI 做的事情就是把这一堆转换头统一成一个接线板所有电器都插在同一个接线板上由接线板决定电流往哪路走。1.2 CLIProxyAPI 的网关思路统一入口、按需路由CLIProxyAPI 的核心设计并不复杂在本地启动一个 HTTP 服务对外暴露一个统一的、兼容主流 CLI 工具的 API 入口收到请求后根据配置好的规则把请求转发到真正的模型供应商再把响应原样返回给 CLI 工具。它做的是应用层的请求转发和协议适配不是网络层的中转工具。所有流量都发生在你本机到模型服务商之间CLIProxyAPI 只是在中间加了一道调度闸口。它的关键能力有几块统一端点所有 CLI 工具都把 base URL 指向本机网关不用再记各家厂商的域名和路径。模型映射请求里带的模型名可以按规则改写。比如 Codex 请求gpt-5网关可以把它映射成 xAI 的grok-3再发出去。密钥托管各家的 API Key 统一写在网关配置里CLI 工具只需要配一个本地占位 Key真实密钥不外泄。协议转换能处理 OpenAI Responses API、Chat Completions API 和 Anthropic Messages API 之间的格式差异这是它能同时服务 Codex 和 Claude Code 的关键。请求日志每条请求走哪个供应商、耗时多少、状态码如何都有记录排查问题非常方便。和每个工具各自改环境变量相比网关方案的最大优势是收敛。所有变更都集中在网关配置文件里CLI 工具端只需要一次性配置好 base URL 和模型名以后换模型、换供应商都不用再动。对于经常在多个模型之间对比编码效果的开发者来说这种统一接入层的价值很明显。2. 部署准备环境、安装与方案选型2.1 运行环境与安装方式CLIProxyAPI 依赖 Node.js 运行时建议使用 18 及以上版本我用的是 20 LTS跑了一个多月没出过问题。如果你本机有 Docker也可以选择容器方式部署适合不想把 Node 环境搞乱的场景。二选一即可我下面以 Node 方式为主讲。安装很简单全局装一下就行npm install -g cliproxyapi装完执行cliproxyapi --version能看到版本号就说明成功了。macOS 上用 Homebrew 装 Node 的话可能需要留意全局 bin 目录是否在 PATH 里否则会提示命令找不到。Windows 上如果 npm 全局目录没有加入系统 PATH同样会遇到类似问题这个我在后面的排查章节会详细说。安装之后项目本身不需要创建特定目录配置文件放哪里由你决定。我习惯在用户目录下建一个~/.cliproxyapi/目录专门放配置和日志干净也容易备份。2.2 三种接入方式的对比为什么选网关在决定使用 CLIProxyAPI 之前我确实也试过另外两种方案各有各的坑。这里整理成表格方便你对比之后做决定。方案优点缺点直接改 CLI 工具的环境变量零额外依赖改完立刻生效每个工具都要单独设置模型切换不灵活容易改乱自写一个转发脚本完全可控按需定制要处理协议差异、鉴权、错误重试开发和维护成本高CLIProxyAPI 网关统一配置、支持协议转换、自带日志多一层本地进程初次配置需要理解路由概念直接改环境变量的方式应付一个工具接一个供应商的场景还行但一旦涉及多模型切换就会很痛苦。比如 Codex CLI 想临时切到 Grok 上跑一轮代码审查你得改环境变量、改模型名、重启终端搞完再切回来。一天切三五次效率消耗非常大。自写转发脚本的问题在于你以为只是转发请求实际还要处理请求体里模型名的改写、不同 API 格式的转换、鉴权头的注入、超时重试、流式响应的透传……这些逻辑看着简单写起来全是细节。我自己写过一版只支持 Chat Completions 格式遇到 Codex 的 Responses API 就抓瞎了。所以最后我还是选择了成熟的网关方案让 CLIProxyAPI 去处理这些脏活累活。提示如果只是临时用一次直接改环境变量完全够用。但如果你和我一样需要长期在多个模型间切换网关是一次投入、长期省事的方案。3. 本地部署完整流程从配置文件到第一个请求3.1 初始化与配置骨架安装好之后执行初始化命令生成配置骨架cliproxyapi init默认会在当前目录生成cliproxyapi.yaml配置文件同时创建一个logs/目录存放运行日志。我建议把生成的配置文件挪到~/.cliproxyapi/目录下统一管理后续启动时用-c参数指定路径。初始化的配置骨架大致长这样server: host: 127.0.0.1 port: 8787 providers: - name: codex type: openai base_url: https://api.openai.com/v1 api_key_env: OPENAI_API_KEY - name: claude type: anthropic base_url: https://api.anthropic.com/v1 api_key_env: ANTHROPIC_API_KEY - name: xai type: openai base_url: https://api.x.ai/v1 api_key_env: XAI_API_KEY routes: - model: * provider: codex先不用急着改把结构看懂就行。server段控制网关监听的本机地址和端口providers段声明上游模型服务商routes段决定请求按什么规则转发。默认的逻辑是把所有请求都转发给 OpenAI你只需要在这个基础上添加路由规则。3.2 配置文件逐段拆解provider、route、model_map实际使用中我的配置比骨架复杂不少。核心要理解三个概念provider、route、model_map。Provider 是上游服务的声明每个 provider 至少需要定义名称、协议类型、base URL 和 API Key 来源。api_key_env字段指向一个环境变量名网关启动时会从环境变量里读取真实的密钥这样密钥不会明文落在配置文件里更安全。例如providers: - name: codex type: openai base_url: https://api.openai.com/v1 api_key_env: OPENAI_API_KEYRoute 是请求的转发规则。最简单的规则是按模型名匹配也可以按前缀匹配。比如我希望所有claude-开头的模型名都走 Anthropic所有grok-开头的模型名都走 xAI其余走默认的 OpenAIroutes: - model_prefix: claude- provider: claude strip_prefix: true - model_prefix: grok- provider: xai strip_prefix: true - model: * provider: codex这里的strip_prefix开关很实用。开启后claude-sonnet-4这个模型名在转发给 Anthropic 之前会被改写成sonnet-4这样各家服务商收到的模型名是它们自己能识别的格式。Model_map 则是精确的模型名映射适合处理客户端写死了一个模型名、但你不想改客户端的场景。比如 Codex CLI 默认请求gpt-5你想让它实际走 DeepSeek就配置model_map: gpt-5: deepseek-chat组合使用 route 和 model_map可以做到非常灵活的路由策略。我的做法是客户端模型名保持前缀语义网关负责翻译和路由客户端永远不用改。3.3 启动网关并验证连通性配置写好后启动网关cliproxyapi start -c ~/.cliproxyapi/cliproxyapi.yaml启动日志会显示监听地址默认是http://127.0.0.1:8787。只监听本机回环地址是刻意的安全选择网关不要暴露到局域网或公网否则任何能访问到这个端口的人都能借用你的 API Key 发起请求账单会很酸爽。验证网关是否正常工作先请求一下模型列表curl http://127.0.0.1:8787/v1/models \ -H Authorization: Bearer local-dev-key能返回 JSON 列表就说明服务起来了。再发一个真实的对话请求测试模型映射和转发链路curl http://127.0.0.1:8787/v1/chat/completions \ -H Authorization: Bearer local-dev-key \ -H Content-Type: application/json \ -d { model: gpt-5, messages: [{role: user, content: ping}] }如果配置了gpt-5到 DeepSeek 的映射这段请求会经过网关转发到 DeepSeek再返回结果。响应里带上了实际使用的模型名你可以核对路由是否生效。这一步通了后面接 CLI 工具就顺理成章了。注意网关本身不会缓存模型列表。/v1/models返回的内容是它向上游查询后聚合的结果首次访问会因为多一跳网络请求而稍微慢一点属正常现象。4. 三个 CLI 工具的实战接入Codex、Claude Code、xAI 与 DeepSeek4.1 Codex CLI 接入把默认模型改成任意供应商Codex CLI 的配置文件在~/.codex/config.toml。要让 Codex 走本地网关需要定义一个自定义 provider并把默认模型和 provider 指到网关model gpt-5 model_provider local-gateway [model_providers.local-gateway] name Local Gateway base_url http://127.0.0.1:8787/v1 env_key LOCAL_GATEWAY_KEY wire_api responseswire_api responses这行很关键。Codex 默认走 OpenAI 的 Responses API即/v1/responses这个端点而不是大家更熟悉的/v1/chat/completions。CLIProxyAPI 需要对 Responses API 的请求做协议转换才能转发给那些只支持 Chat Completions 的供应商。设置好之后在 shell 里导出一个占位密钥export LOCAL_GATEWAY_KEYlocal-dev-key这个 Key 只是让 Codex 能通过本地网关的鉴权真实密钥在网关配置里。然后运行codex正常情况下它就会把请求发给本地网关由网关根据模型映射决定到底调用哪家模型。我踩过的一个典型坑是Codex 在某些账号下会报The gpt-5.6-sol model is not supported when using codex with a chatgpt account。这是账号权限问题默认模型在当前账号下不可用。两个解决思路一是用 API Key 认证而不是 ChatGPT 账号登录二是把本地网关配置里对应模型的映射改掉让 Codex 请求的模型名落到你有权限的服务上。用网关方案时第二种思路更省事因为完全不用动 Codex 的认证方式。4.2 Claude Code 接入环境变量与协议转换Claude Code 接入网关的方式和 Codex 不同它主要通过环境变量指定 API 地址和令牌。我的做法是在 shell 配置里加上export ANTHROPIC_BASE_URLhttp://127.0.0.1:8787 export ANTHROPIC_AUTH_TOKENlocal-dev-key export ANTHROPIC_MODELclaude-sonnet-4Claude Code 默认走 Anthropic 的 Messages API也就是/v1/messages端点。网关收到请求后需要基于配置做协议转换把 Anthropic 格式的请求体转成上游目标服务支持的格式。如果上游本身就是 Anthropic那直接透传如果上游是 OpenAI 兼容服务则需要把system、messages等字段重新组装成 OpenAI 格式。这里有个容易踩的坑Claude Code 启动时经常报claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这不是网关的问题而是 Node 全局安装目录没在 PATH 里。macOS 或 Linux 下检查 npm 的 global bin 目录Windows 下检查 npm 前缀目录把它加进 PATH 后重新打开终端即可。如果你在 Windows 上还遇到了Claudes workspace requires the virtual machine platform on windows这类提示那是系统缺少虚拟化组件。到启用或关闭 Windows 功能里勾选虚拟机平台和Windows 虚拟机监控程序平台重启后再试。这属于运行环境依赖和网关配置无关但出现频率不低一起列出来省得你排查半天。4.3 xAI 与 DeepSeek 扩展接入一个配置搞定新供应商xAI 的 Grok 模型接口兼容 OpenAI 格式所以接进来非常简单。在 providers 里加一段- name: xai type: openai base_url: https://api.x.ai/v1 api_key_env: XAI_API_KEY再在 routes 里加一条前缀规则把所有grok-开头的模型名路由到 xAI。这样在任何 CLI 工具里把模型名写成grok-3网关就会自动转发到 xAICodex 和 Claude Code 都能用上 Grok。DeepSeek 的接入也走同样的路它同样提供 OpenAI 兼容接口- name: deepseek type: openai base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY我实际用的路由规则大致是这样routes: - model_prefix: claude- provider: claude strip_prefix: true - model_prefix: grok- provider: xai strip_prefix: true - model_prefix: deepseek- provider: deepseek strip_prefix: true - model: * provider: codex这样设计的好处是模型名天然带有供应商前缀一眼就知道当前请求会走哪家。想换供应商只需改模型名或者调路由顺序CLI 工具端完全不用动。新增一个供应商的成本也就一两分钟的事。这也是我推荐用网关而不是环境变量的根本原因环境变量方案下接一个新模型要改所有工具而网关方案下只改一处。5. 高频报错与排查实录5.1 报错速查表我把这段时间自己遇到和帮朋友排查过的问题整理成一份速查表按报错信息、可能原因、解决手段排列方便你按图索骥。报错信息可能原因解决手段cc switch local proxy failed while handling codex endpoint /responsesCodex 切换到本地代理时网关未实现或未正确路由/v1/responses端点检查 Codex 配置里wire_api是否为responses确认网关版本支持 Responses API 协议转换看网关日志确认请求是否到达The gpt-5.6-sol model is not supported when using codex with a chatgpt accountChatGPT 账号没有该模型的访问权限改用 API Key 认证或在网关 model_map 中把该模型映射到你有权限的模型claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称Node 全局安装目录不在系统 PATH找到 npm 全局 bin 目录并加入 PATH重启终端failed to start claudes workspace rpc error -1: sdk version not verifiedClaude Desktop 或工作区的运行时组件版本异常完全退出 Claude 相关进程重新运行claude命令必要时重装 CLI 组件claudes workspace requires the virtual machine platform on windowsWindows 缺少虚拟机平台功能在 Windows 功能中启用虚拟机平台和Windows 虚拟机监控程序平台codex ran out of room in the models context上下文超长超出模型窗口清理历史会话减少输入内容切换上下文窗口更大的模型请求正常但响应为空或超时上游服务网络慢流式响应未正确透传API Key 无效查看网关日志的耗时字段用 curl 直连上游对比测试5.2 三个典型排查过程第一个是 Codex 切换到本地网关时的/responses报错。这个问题我印象很深因为第一次遇到时完全没头绪。报错指向的是 Codex 在操作本地代理时处理/responses端点失败。排查思路是三层先看 Codex 配置文件里的base_url是不是指向http://127.0.0.1:8787/v1再看网关日志里有没有收到来自 Codex 的请求最后确认网关是否启用了 Responses API 的协议转换。我那次的问题出在网关配置里把上游服务类型配成了纯 Chat Completions 格式导致 Responses 格式的请求在转换时抛异常调整 provider 类型后解决。第二个是 Claude Code 命令找不到。这个问题在 Windows 上尤其常见原因是 npm 全局安装的可执行文件目录没有进入系统 PATH。解决办法是先执行npm prefix -g找到全局目录把目录加入 PATH然后重开终端。macOS 上如果用了 nvm则要检查当前 Node 版本对应的 bin 路径。第三个是接入 DeepSeek 后请求一直超时。全局日志里能看到请求出去了但迟迟没有响应。用 curl 直接请求 DeepSeek 接口发现是通的问题出在网关的流式响应透传上。部分模型服务在返回流式响应时结束标记的格式有细微差异老版本网关处理不了。升级 CLIProxyAPI 之后问题消失。如果你也遇到类似情况优先检查版本是不是太旧。5.3 使用技巧与避坑清单最后分享几个我平时用得顺手的小技巧都是文档里不会写的东西。日志是排查问题的第一利器。CLIProxyAPI 的日志会详细记录每条请求的来源工具、目标模型、路由结果、耗时和错误信息。遇到问题先翻日志比盲改配置高效得多。建议启动时把日志级别调到 debug链路信息会更全。密钥管理要养成习惯。真实 API Key 统一用环境变量注入CLI 工具端只配占位 Key。这样即使配置文件被同步到 Git 仓库也不会泄露真实密钥。我把~/.cliproxyapi/cliproxyapi.yaml加入 Git 忽略列表同时单独维护一份.env文件存放真实密钥。配置尽量做到可解释。我在 routes 和 model_map 里每条规则都加注释说明这个映射的用途。时间一长没有注释的配置很容易变成天书。上个月我为了排查一个误路由问题就是因为配置里一条规则没有注释自己都忘了当初为什么这么写。注意修改配置文件后需要重启网关才能生效。CLIProxyAPI 目前没有配置热加载如果你加了新供应商或改了路由记得重启一下别问我怎么知道的。写在最后这套本地网关我用了也有一段时间了最大的感受是工具链的复杂性被挡在了配置文件之外。Codex 和 Claude Code 在我电脑上一直保持默认状态平时切换模型只改网关配置再也不用来回折腾环境变量。如果你也有一堆 AI 编码工具要管理不妨试试把接入层收敛到一个本地网关配置一次长期受益。后面如果再接入新的模型服务商我还会继续补充这个项目的实战经验。