手头同时用着 Codex CLI、Claude Code偶尔还要切到 xAI 的模型每个客户端都要单独配 API Key、单独设置模型名、单独维护一套配置文件时间一长整个环境就是一团乱麻。CLIProxyAPI 这个本地代理工具解决的就是这个痛点它在本地起一个代理服务统一接收各个 CLI 客户端的请求再根据配置把流量转发到不同的上游模型服务真正做到“一套配置多个客户端接入”。这篇文章我会从零开始梳理 CLIProxyAPI 的本地部署全过程包括为什么需要这样一层代理、配置文件怎么设计、Codex/Claude/xAI 分别怎么接入以及我在实际踩坑中总结的排查方法。无论你是刚接触 AI 编码工具的新手还是已经在多客户端之间反复横跳的老手这套方案都能让你的环境干净很多。1. 为什么需要 CLIProxyAPI一个本地代理解决多模型接入1.1 手头三五个客户端的真实痛点先说现状。现在很多开发者电脑上不止装一个 AI 编码工具Codex 负责一部分代码生成Claude Code 在某些场景下效果更好xAI 的模型也时不时要对比一下。每个工具都有自己的 endpoint 配置、自己的 API Key、自己的模型标识方式。更麻烦的是有些客户端默认只连官方服务你想把它切到别的模型就得去翻环境变量、改配置文件甚至要装额外的切换工具。我之前就遇到过这种情况Codex CLI 默认走 OpenAI 的接口我想让它调用 xAI 的模型得手动指定 base URLClaude Code 默认走 Anthropic 接口我想让它走本地模型又得改 base URL。两套客户端的配置方式还不一样一个用OPENAI_BASE_URL一个用ANTHROPIC_BASE_URL。改来改去环境变量堆了一大堆哪天忘了哪条生效排查起来非常痛苦。还有个安全层面的问题。API Key 分散在各个客户端的配置里如果某个工具要共享配置给别人或者上传到 dotfiles 仓库Key 很容易泄露。使用统一代理后Key 只存在代理这一层客户端本身不需要知道任何上游的密钥风险面一下就收窄了。1.2 本地代理模式的设计思路与优势CLIProxyAPI 之所以选择“本地代理”而不是“改客户端源码”或者“写一堆脚本”来解决问题核心原因有三个。第一是协议兼容性。Codex CLI、Claude Code 这些工具虽然各自有自己的接口习惯但底层基本都是 HTTP 请求而且大多数支持通过环境变量或配置文件来覆盖 API 的 base URL。代理要做的事情就是把它们各自发出的请求“接住”再翻译成目标上游认识的形式转发出去。第二是配置集中化。所有上游服务的地址、密钥、模型映射关系只维护一份配置文件。客户端那边只需要指到本地代理完全不用关心最后的流量去了哪家服务商。这相当于在客户端和模型服务商中间加了一层“路由”你想切模型改代理配置就行客户端一行不用动。第三是观察和调试方便。代理这层可以打印日志、记录请求耗时、统计 token 用量。你可以清楚地看到每次请求走了哪条链路、用了哪个模型、花了多长时间。直接对接官方服务的时候这些信息是拿不到的。2. 本地部署前的环境准备2.1 安装方式与版本确认CLIProxyAPI 的部署方式比较常规目前主流的有三种直接下载预编译二进制、通过包管理器安装、从源码编译。方式一下载预编译二进制这是最推荐也是最快的方式。去项目的 Release 页面找到对应你操作系统和 CPU 架构的压缩包解压后把可执行文件放到~/bin或者其他 PATH 目录里。# 以 Linux x64 为例 wget https://example.com/cliproxyapi/releases/download/v0.6.0/cliproxyapi_linux_amd64.tar.gz tar -xzf cliproxyapi_linux_amd64.tar.gz sudo mv cliproxyapi /usr/local/bin/ # 验证安装 cliproxyapi version方式二包管理器安装如果你用的是 Homebrew可以尝试brew install cliproxyapimacOS 用户用 Homebrew 的好处是升级方便brew upgrade cliproxyapi一条命令搞定。但要注意包管理器里的版本可能不是最新的如果你需要某个新功能还是建议从 Release 页面手动下载。方式三源码编译适合有 Rust/Go 环境并且想自己改代码的开发者。项目源码克隆下来后直接用项目提供的构建脚本编译编译产物同样放到 PATH 目录。这种方式的优点是能拿到最新主分支的功能缺点是编译时间较长而且如果项目依赖有更新可能需要处理一下依赖版本冲突。我自己的建议是只是想用工具直接方式一macOS 用户且不追求最新功能用方式二想二次开发或者提 PR用方式三。安装完第一步运行cliproxyapi version确认版本号。我遇到过拿老版本瞎折腾半天最后发现是版本太旧不支持某个配置项的情况。如果你准备照着这篇文章操作建议先用最新稳定版。2.2 配置文件结构与密钥处理CLIProxyAPI 的核心是一个 YAML 配置文件默认路径是~/.cliproxyapi/config.yaml也支持通过环境变量指定配置文件位置export CLIPROXYAPI_CONFIG/path/to/your/config.yaml cliproxyapi serve配置文件大体上有下面几个部分server: host: 127.0.0.1 port: 8787 upstreams: - name: openai type: openai base_url: https://api.openai.com/v1 api_key_env: OPENAI_API_KEY - name: anthropic type: anthropic base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY - name: xai type: openai base_url: https://api.x.ai/v1 api_key_env: XAI_API_KEY - name: local-ollama type: openai base_url: http://localhost:11434/v1 api_key: ollama models: - name: codex upstream: openai model_mapping: gpt-5 - name: claude upstream: anthropic model_mapping: claude-sonnet-4-20250514 - name: grok upstream: xai model_mapping: grok-4这里有几个关键点要注意。密钥通过环境变量引用不直接写在配置文件里。api_key_env指定的是环境变量的名字实际 Key 从环境变量里读取。这样配置文件本身可以放心交给版本管理不用担心密钥泄露。每一个 upstream 都要指定类型。OpenAI 和 xAI 都兼容 OpenAI 的接口格式所以类型都填openaiAnthropic 是独立的协议填anthropic。千万别把 Anthropic 的接口配成 openai 类型否则请求格式完全对不上各种 4xx 错误会让你怀疑人生。端口默认 8787绑定地址建议写127.0.0.1不要写0.0.0.0。这个代理会转发你所有的 API 请求和密钥信息如果绑定到局域网相当于把密钥开放给了同一网络下的所有设备完全没必要冒这个风险。配置写好后可以先跑一个语法检查命令确认格式没问题再启动服务cliproxyapi config check这一步会帮你找出 YAML 里缩进错误、必填字段缺失等问题比启动后报错再排查要快得多。3. 核心配置统一接入 Codex、Claude、xAI3.1 接入 Codex从官方端点切到本地代理Codex CLI 默认情况下走的是 OpenAI 官方接口。要让它走本地代理核心就是设置环境变量把它默认的 base URL 指向本地代理的地址。首先在你的 shell 配置文件比如~/.bashrc、~/.zshrc里加一行export OPENAI_BASE_URLhttp://127.0.0.1:8787这里有个容易踩坑的地方CLIProxyAPI 的代理地址是http://127.0.0.1:8787不带/v1后缀。很多接口地址都是http://host:port/v1这种形式但经过代理转发后具体路径由代理自己拼接所以客户端配到根路径就行。如果你在代理前面还挂了别的服务按实际情况调整。配置完成后重启终端或者source ~/.zshrc让环境变量生效然后运行 Codexcodex启动后你可以在 CLIProxyAPI 的日志里看到类似这样的记录127.0.0.1 - POST /v1/responses 200 1.23s这就说明请求确实经过了本地代理。我实际使用中遇到过一种情况环境变量配好了但 Codex 的请求还是直接打到官方端点。排查后发现是 Codex 内部有个配置文件的优先级比环境变量高。解决方法是在 Codex 的配置文件里把 base URL 也指到本地代理。Codex 的配置一般在~/.codex/config.toml找到类似下面的内容model gpt-5 model_provider openai然后在同一份配置里加上或确认base_url[model_providers.openai] name OpenAI base_url http://127.0.0.1:8787 api_key local-proxy-key注意这里api_key随便填一个非空字符串就行因为实际密钥由代理去读取和转发Codex 本身不需要知道真实 Key。改完配置后重启 Codex。如果还是走官方端点建议先检查环境变量是否真的加载成功echo $OPENAI_BASE_URL3.2 接入 ClaudeClaude Code 的兼容配置Claude Code 默认走 Anthropic 接口。要让它的请求也进本地代理同样是用环境变量覆盖默认端点。在 shell 配置文件里加export ANTHROPIC_BASE_URLhttp://127.0.0.1:8787这个变量告诉 Claude Code所有本应发往 Anthropic 的请求都发给本地代理。代理收到请求后根据配置里的模型映射关系转发到对应的上游服务。Claude Code 启动后CLIProxyAPI 日志里应该出现类似127.0.0.1 - POST /v1/messages 200 2.01s这里有一个我在实际使用中踩过的坑。Claude Code 某些版本对ANTHROPIC_BASE_URL的路径处理方式比较特殊有的人填http://127.0.0.1:8787有的人填http://127.0.0.1:8787/v1。如果你发现请求到了代理但返回 404大概率是路径多了一层/v1。我的经验是先不带/v1测试如果 404 就加上再试。两种都试过之后以日志里实际收到请求路径为准。Claude Code 的配置也可以通过配置文件设置。它支持一个 JSON 配置文件来管理 API Key 和端点位置通常在~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:8787, ANTHROPIC_AUTH_TOKEN: local-proxy-key } }如果你同时开了多个终端工具建议环境变量和配置文件统一用一种方式避免两边优先级不一致导致的混乱。3.3 接入 xAI 与其他 OpenAI 兼容服务xAI 的接口是 OpenAI 兼容的所以配置和接入 OpenAI 基本一样。区别在于代理配置里 upstream 的 base_url 要指向 xAI 的地址而且 xAI 需要单独一个 API Key。CLIProxyAPI 配置里的 upstream 部分upstreams: - name: xai type: openai base_url: https://api.x.ai/v1 api_key_env: XAI_API_KEY然后在环境变量里设置export XAI_API_KEY你的xAI密钥这时候问题来了Codex CLI 走代理时它并不关心代理后面是哪家供应商它只会把请求发到本地代理请求头里带的是它自己配置的api_key比如刚才那个local-proxy-key。代理根据模型名这个信息决定这个请求应该转发到哪个 upstream然后替换成真正的密钥发出去。所以当你想要用 xAI 的模型时你需要在 models 环境里定义一个模型并把它映射到 xAI 上游models: - name: grok upstream: xai model_mapping: grok-4然后在 Codex 里指定模型为grokcodex --model grok这样请求到了代理代理看到模型名是grok就把请求转发给 xAI 上游并使用XAI_API_KEY来完成认证。这个模式同样适用于其他 OpenAI 兼容服务。现在很多模型服务商都提供 OpenAI 兼容的接口你只要在 upstreams 里加一段、在 models 里加一条映射然后用--model参数切换就行。这也是用代理统一接入多个模型服务最大的价值。3.4 接入本地 Ollama 等私有模型服务聊完云服务再来说说本地模型。热词里频繁出现“ollama本地部署”“本地部署大语言模型”说明不少人在本地跑开源模型。CLIProxyAPI 也能把这些本地模型统一管理起来。Ollama 默认提供 OpenAI 兼容接口地址是http://localhost:11434/v1。在 CLIProxyAPI 配置里加一个 upstreamupstreams: - name: local-ollama type: openai base_url: http://localhost:11434/v1 api_key: ollama-key这里api_key写成任意字符串就行因为本地 Ollama 本身不做严格认证但代理需要有一个 Key 来填充请求头。然后定义一个模型映射models: - name: local-llama32 upstream: local-ollama model_mapping: llama3.2之后在 Codex CLI 里用--model local-llama32或在 Claude Code 里通过配置指定模型请求就会自动被代理路由到本地 Ollama。这样你就可以在云端模型和本地开源模型之间自由切换而不用改任何客户端配置只需要在代理配置里定义好映射关系。我当时接本地模型还有个额外目的测试一些提示词或者做离线开发。断网的时候本地模型还能继续扛一部分工作不至于完全干不了活。4. 实操过程中的参数调优与验证方法4.1 模型名映射理解请求转发的核心逻辑CLIProxyAPI 最核心的机制之一就是模型名映射。理解了这个机制整个代理的配置思路就通了。客户端发出的请求里带有模型名比如 Codex 可能发gpt-5Claude Code 可能发claude-sonnet-4。代理收到请求后会拿这个模型名去跟models配置做匹配。匹配上的话就用该条规则里指定的upstream和model_mapping来重写请求再转发出去。举个例子。假设你在 Codex 里配置的是models: - name: grok upstream: xai model_mapping: grok-4当 Codex 发出模型名为grok的请求时代理把模型名重写为grok-4然后把请求发到 xai 上游。这个机制的好处是模型真实名称和客户端感知名称解耦。哪怕上游改了模型代号你只需要改代理配置里的一行model_mapping客户端完全不用动。在实际配置中可以分几类来管理模型Codex/OpenAI 系映射到 OpenAI 官方模型比如gpt-5、gpt-5-mini。Anthropic 系映射到 Claude 各型号例如claude-sonnet-4-20250514注意要带日期后缀这是 Anthropic 模型的常见命名方式。xAI 系映射到 Grok 各版本。本地模型映射到 Ollama 里的模型名比如llama3.2、qwen2.5。有个容易出错的地方是model_mapping是否带-和日期。Anthropic 的模型名比较严格把日期写错会直接报model not found。建议每次配置前先去各服务商文档确认当前最新的模型标识。4.2 验证与日志追踪配置写好后关键一步是验证链路是否真的如预期。我的习惯是分三步走。第一步是启动代理确认监听端口正常cliproxyapi serve --config ~/.cliproxyapi/config.yaml看到类似server listening on 127.0.0.1:8787的日志说明代理已经起来了。第二步是直接用 curl 模拟客户端请求验证代理能否正确转发。以模拟 Codex 的/v1/responses请求为例curl -X POST http://127.0.0.1:8787/v1/responses \ -H Authorization: Bearer local-proxy-key \ -H Content-Type: application/json \ -d { model: grok, input: say hello }如果模型名映射正确、上游密钥有效你会收到来自 xAI 的真实响应。这一步的好处是绕过客户端直接验证代理配置是否正确。如果 curl 通了但客户端不行那问题基本出在客户端配置上如果 curl 都不通问题出在代理或上游配置上。第三步是打开 Log level 到 debug看完整的请求和响应头。CLIProxyAPI 一般支持--log-level debug参数cliproxyapi serve --config ~/.cliproxyapi/config.yaml --log-level debugDebug 模式下你可以看到客户端实际发来的模型名、代理重写后的模型名、上游返回的状态码。有一次我遇到模型 404 的问题就是靠 debug 模式里看到代理重写后的模型名还是旧的才定位到model_mapping没生效是配置里缩进不对导致规则没加载上。另一个很实用的验证方法是分别用不同的模型发起简单请求观察代理日志里每次请求的转发目标和耗时。这样你能直观地看到路由是否正确、各上游的响应速度如何。5. 常见问题与排查技巧实录5.1 处理 Codex endpoint 报错很多人在切换本地代理时会遇到一个典型报错大意是local proxy failed while handling codex endpoint /responses。这个报错在热词里也出现了说明踩中的人不少。这个报错的直接意思是Codex CLI 发出请求后本地代理在处理/responses这个端点时出了问题没有返回一个合法的响应。可能的根因有几种第一种是代理没起来或端口不对。这种情况最常见。Codex 配置的 base URL 指向8787但代理实际监听在别的端口或者根本没启动。排查方法很简单浏览器或 curl 访问http://127.0.0.1:8787如果连接被拒绝说明代理确实没起来或端口不对。用ss -lntp | grep 8787或者lsof -i :8787确认监听状态。第二种是路径不匹配。Codex 实际请求的是/v1/responses而代理可能默认不处理这个路径或者在 upstream 转发时路径拼接出问题。这种情况表现是代理能收到请求但处理完后返回 404 或 500。排查方法是开启 debug 日志看代理收到的完整路径和转发后的完整路径。第三种是模型映射缺失。代理收到请求后发现请求里的模型名没有在models配置里定义于是拒绝处理。这种在日志里通常会有一条类似model not found的记录。解决方案是把模型名补到models配置里并指定正确的 upstream。我把这个报错的处理思路整理成一条排查链路先确认代理进程活着再确认端口匹配再确认调试日志里的请求路径最后确认模型映射存在。按这个顺序走大部分问题都能定位。5.2 认证失败、超时、端口冲突等常见问题汇总多客户端接入时还有一些高频问题几乎每个人都会遇到。认证失败401/403。如果你确认密钥没错但请求还是 401先检查是不是客户端在请求头里覆盖了Authorization。有些 CLI 工具会把自己配置的 Key 原样带过去代理端如果强制用请求头的 Key 而不是环境变量的 Key就会导致认证失败。解决方案是在代理配置里查看是否支持“忽略客户端 Authorization”通常叫override_auth或类似字段功能开启后代理一律用api_key_env指向的真实密钥。请求超时到 30 秒以上。本地模型对长上下文的处理很慢尤其没有 GPU 的机器。CLIProxyAPI 默认超时时间可能只有 30 秒需要在配置里调高server: request_timeout_seconds: 300另外config.yaml里还可以配置并发连接数上限。如果同时开了多个客户端或并行跑多个请求默认并发可能不够用请求会排队表现也是变慢。适当调高并发值可以缓解。端口被占用。8787 这个端口被其他服务占用时会启动失败。修改server.port即可。改了端口之后记得把所有客户端的 base URL 都同步改一下否则客户端还是指向旧端口。AI 客户端提示模型不支持。有些 CLI 工具会自己维护一个“已知模型列表”如果客户端发出的模型名不在它的列表里可能直接拒绝发送请求。这种情况下先手动改客户端的配置把模型设置为它认识的任意一个再依赖代理的model_mapping把模型名重写成真实目标。比如 Codex 里可以填gpt-5代理收到后把它重写成grok-4客户端不会报错流量也走到了正确的上游。下面做一个速查表供参考现象可能原因排查方法解决方案Connection refused代理未启动或端口不对lsof -i :8787启动代理确认端口匹配404 Not Found请求路径缺/v1debug 日志查看实际路径调 base URL 路径401 Unauthorized客户端覆盖了 Authorization 头看代理日志中的请求头开启 ignore client authmodel not found模型映射缺失或映射错误debug 日志看重写后模型名补全 models 配置请求超时上游处理慢超时时间太短查看响应耗时统计调大 timeout 和并发启动失败端口占用8787 被占用lsof -i :8787改 server.port某个客户端能通其他不通客户端 base URL 配置不一致对比各客户端环境变量统一为同一代理地址6. 实际使用中的几点经验与建议部署完 CLIProxyAPI 并接入多个客户端之后我最大的感受是环境一下子就清爽了。以前打开终端env | grep -i api能刷一屏现在只剩几个代理相关的变量。所有密钥都收拢到环境变量和代理配置里管理成本低了很多。这里有几个我自己实践下来很受用的建议。第一密钥别散着放。集中放到一台机器或者一个加密的 dotfile 管理工具里代理配置里只留api_key_env的字段名。这样就算配置文件被别人拿走也只是一堆字段名真正的密钥还在你自己手里。第二可以写一个简单的启动脚本一键起代理#!/bin/bash source ~/.env cliproxyapi serve --config ~/.cliproxyapi/config.yaml --log-level info把这条命令做成 alias比如proxy-start以后要启动服务就不用打一长串参数。关掉代理的时候记得检查所有客户端是否还在使用不然客户端会一直在连接失败中重试。第三如果多个项目需要不同的模型配置CLIProxyAPI 也支持加载不同的配置文件。比如项目 A 用 OpenAI项目 B 用本地模型那就准备两份 config需要哪个就启动哪个。这是后期扩展很实用的做法。第四每隔一段时间看一下上游服务的模型列表。模型命名变化比较频繁尤其 Anthropic 的带日期型号和 xAI 的版本号过期了就去改一下model_mapping。这个操作一分钟就能完成但能避免很多次“为什么突然全部报错”的困惑。最后再提醒一句本地代理这类工具配置逻辑其实不难难点全在处理各种客户的“个性”上。遇到问题时先开 debug 日志日志会告诉你请求长什么样、代理做了什么、上游回了什么。把日志看明白九成问题都能自己解决。