近半年身边搞AI应用的朋友几乎人手装了 Codex CLI、Gemini CLI 或 Claude Code。这些命令行工具交互体验确实好但它们都有一个共同毛病各家协议不互通、配置互相独立。你手里明明已经在某个 CLI 里配好了模型额度想把它暴露成一个标准 API 端点给 ChatBox、自研程序、或者团队内部工具调用却得写一堆胶水代码去对接。CLI Proxy API 这类方案就是把本地 CLI 包装成一个统一的 API 服务对外兼容 OpenAI / Gemini / Claude / Qwen 几家常见协议格式对内统一转发到你已经配置好的 CLI 后端。这篇文章我会结合实测完整过程把这类工具的原理、选型逻辑、配置要点、协议转换细节和排错经验一次讲清楚适合正在纠结怎么把命令行模型能力接入自己系统的开发者参考。1. 方案拆解为什么要走CLI 转 API这条路1.1 CLI 本质上是藏起来的 HTTP 客户端很多人把 Codex CLI、Claude Code 这类工具当成终端里的聊天机器人但实际上它们全都是标准的 HTTP API 客户端。你敲一句 promptCLI 内部会组装请求发给对应的模型服务端点再把流式返回渲染成终端里的增量文字。既然本质是客户端那就意味着它依赖三样东西API 地址、认证凭证、请求格式。CLI Proxy API 的思路很直接在本地起一个 HTTP 服务让它冒充模型厂商的 API 端点把外部传入的 OpenAI / Anthropic / Gemini / DashScope 格式请求转换成目标 CLI 能理解的形式再调用本机的 CLI 可执行文件去真正执行最后把结果流式转发回调用方。这等于在客户端和模型之间插了一层翻译官所有协议差异都在这层消化掉。这样做还有个额外收益很多 CLI尤其是 Codex CLI具备 agent 式任务执行能力能自己规划步骤、调用工具、迭代修改文件。这类能力原本只能在终端里用一旦包装成 API就能被 CI/CD 流水线、自动化脚本、消息机器人调用价值完全不一样了。1.2 四家厂商 API 风格的差异有多大先看各家对外协议的核心差异维度OpenAIAnthropicGeminiQwen / DashScope对话端点/v1/chat/completions/v1/messages/v1beta/models/{model}:generateContent/compatible-mode/v1/chat/completionssystem 消息messages 数组内 rolesystem单独 system 字段系统指令单独字段messages 数组内 rolesystem角色范围system/user/assistant/tooluser/assistantsystem独立user/model无 assistantsystem/user/assistant/tool流式格式SSE data 增量SSE event 分块Server-Sent Events 分块SSE data 增量工具调用tool_calls 字段tool_use / tool_resultfunctionCall / functionResponsetool_calls 字段类似 OpenAI可以看到OpenAI 是最通用的格式Qwen 的兼容模式也基本照抄 OpenAI而 Anthropic 和 Gemini 差异很大。CLI Proxy API 的价值恰恰在于把这四套协议归一化成一套大多数场景下统一对外暴露 OpenAI 格式调用方成本最低。1.3 为什么不直接用统一网关或直连官方 API做模型 API 聚合这事社区已有不少成熟方案比如 one-api、new-api、LiteLLM。那为什么还要CLI 转 API我从几个维度做了对比对比项CLI Proxy API统一网关 one-api/new-api直连各家官方 API配置成本低复用 CLI 现有配置中需逐家配置渠道和 Key低但需要注册多家账号额度利用能复用订阅型/包月型 CLI 额度只能承载 API Key 类额度各账号独立单独计费Agent 类能力可暴露 CLI 的 agent 执行能力通常只转发纯对话取决于厂商是否提供协议转换支持 OpenAI/Anthropic/Gemini/Qwen以 OpenAI 为主其他需插件无转换格式原生并发能力弱单机 CLI 进程受限强可水平扩展取决于官方限流适合场景个人工具、内网自动化、小团队多 Key 多模型集中管理、对外变现生产级应用直连所以我的判断是CLI Proxy API 不是要取代统一网关而是补齐复用 CLI 配置与额度这一块拼图。个人开发者、小团队、内网自动化场景下它部署最简单、成本最低。如果你要做对外的高并发服务还是老老实实走官方 API 加网关。2. 部署与核心配置实操2.1 工具选型和环境准备社区里这类工具不少像 cc-switch 的 Local Proxy 功能、codex-proxy、cli-proxy 等等底层原理基本一致。我这次以 cc-switch 这一类内置 Local Proxy 的工具为例做说明它同时支持把 Codex CLI 和 Claude Code 包装成兼容端点日常使用比较省心。不同工具细节上有差异但核心配置项是通用的下面讲的方法换成别的实现也能照搬。环境方面需要准备三样东西运行时Node.js 18 或 Python 3.10取决于你选用的工具要求。目标 CLI至少装好一个你要暴露的 CLI比如 Codex CLI并保证它本身能正常工作。上游模型配置CLI 里要能成功跑通某个模型比如通过环境变量指向 DeepSeek、通义千问或其他兼容端点的供应商。这里提个建议先确保 CLI 在终端里能正常对话再上代理层。很多人一开始代理起不来最后发现是 CLI 本身就没配好白白浪费排查时间。2.2 核心配置项逐一拆解以典型的 cli-proxy 类工具为例配置文件大致长这样server: host: 127.0.0.1 port: 8787 api_key: sk-local-proxy-123 # 调用方访问时需要的认证 Key upstreams: codex: provider: codex cli_path: /usr/local/bin/codex env: OPENAI_BASE_URL: https://api.deepseek.com/v1 OPENAI_API_KEY: sk-xxxx OPENAI_MODEL: deepseek-chat models: - codex-deepseek claude: provider: claude cli_path: /usr/local/bin/claude env: ANTHROPIC_BASE_URL: https://your-gateway.example.com ANTHROPIC_AUTH_TOKEN: sk-xxxx models: - claude-local mappings: - from: gpt-4o-mini # 对外暴露的模型名 to: codex-deepseek # 实际调用的上游 - from: claude-sonnet to: claude-local几个关键参数的理解server.host强烈建议绑127.0.0.1不要直接绑0.0.0.0暴露到局域网。需要跨机器访问时优先通过 Nginx 加一层 TLS 和鉴权再转发。server.api_key这是你暴露给调用方的认证 Key和上游厂商的 Key 完全独立。所有请求必须带Authorization: Bearer sk-local-proxy-123才会被接受。upstreams.*.env这里设置的环境变量会注入到被调用的 CLI 进程中。Codex CLI 读OPENAI_BASE_URL和OPENAI_API_KEYClaude Code 读ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。这部分相当于把你在终端里的 CLI 配置固化成代理配置。mappings模型名映射表。对外你可以暴露任何名字比如gpt-4o-mini对内映射到真正要调用的上游模型。这是兼容层的核心各种程序只需要认你给的模型名底层换厂商完全不影响调用方。2.3 启动与首次请求验证配置完之后用命令行启动服务cli-proxy start --config ./proxy.yaml看到类似listening on 127.0.0.1:8787的日志就说明起来了。先用 curl 做一次最简单的验证curl http://127.0.0.1:8787/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-local-proxy-123 \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话介绍你自己}], stream: false }如果配置正确你会收到一个 OpenAI 格式的 JSON 响应choices[0].message.content里有模型返回的文本。此时再开一个终端跑curl http://127.0.0.1:8787/v1/models应该能看到你配置的所有对外模型名。我建议第一次验证时先在浏览器或终端里直接跑目标 CLI 确认上游 OK再测代理层。真出问题时日志里会同时打印本次请求命中了哪个上游、上游返回了什么按链路一层层查最快。3. 多协议兼容与请求转发细节3.1 OpenAI 格式如何路由到不同 CLI对外统一暴露 OpenAI 格式的最大好处是市面上几乎所有开源应用都原生支持ChatBox、NextChat、LobeChat 之类的产品填一个 Base URL 和 Key 就能接入。路由逻辑上代理层拿到请求后先用model字段查映射表确定走哪个上游再把 OpenAI 格式的消息数组转换成上游需要的格式。这里有一个容易忽略的点OpenAI 的messages里可能包含system、tool、tool_calls等角色而有些上游 CLI 并不支持把这些原样透传。稳妥的做法是让代理在转换时做一次归一化把系统提示词抽出来单独处理工具调用历史按上游格式重组而不是简单把 JSON 原封不动转发。3.2 Anthropic 格式的转换要点如果你想直接暴露 Anthropic 原生格式也就是客户端按 Claude API 的方式调用你的代理代理层需要处理几个关键差异system字段要单独提取不能混在messages里。角色只有user和assistantOpenAI 的system消息要转换成第一条user消息或在system字段携带。max_tokens是必填参数OpenAI 请求里没有的话要补一个默认值否则 Claude 协议会直接报错。流式返回的 event 类型不同Anthropic 是message_start、content_block_delta、message_stop而 OpenAI 是带choices[0].delta的 data 块。代理层要做事件类型转换。实际使用中如果你主要服务的客户端是 OpenAI 系没必要强行暴露 Anthropic 原生格式直接在 OpenAI 兼容层上做转换反而更简单。Anthropic 原生格式更适合给 Claude Code 这类本来就只认自家协议的工具用。3.3 Gemini 格式的转换处理Gemini 的请求结构和其他三家差异最大消息角色叫user和model内容放在contents[].parts[]里参数集中在generationConfig。如果你要把 Gemini CLI 暴露成 OpenAI 兼容端点转换逻辑大概是OpenAI 的messages数组转换成contents每条消息的content字符串放进parts[].text。temperature、max_tokens、top_p映射到generationConfig对应的字段。流式响应里 Gemini 返回的是candidates[].content.parts[].text的增量代理层要把它包装成 OpenAI 的delta.content。Gemini CLI 有一个坑它的登录态不一定稳定尤其是频繁调用时容易出现 sign-in 失效。我的经验是给 Gemini CLI 配置一个独立的环境变量来指定 API Key不要依赖浏览器登录态否则代理层很容易出现上午能用下午 401的灵异现象。3.4 Qwen / DashScope 兼容端点的特殊性Qwen 系模型走 DashScope 的 OpenAI 兼容模式时整体格式和 OpenAI 几乎一样转换成本最低。但有一个细节要注意部分通义模型的 thinking 模式会返回reasoning_content字段如果你在后续多轮对话里需要把它传回给 API代理层就必须保留这个字段而不能丢弃否则上游会报 400。这个问题下面排查部分还会细说。如果你直接用 Qwen Code 这类 CLI它本质上也是调用 DashScope 的 OpenAI 兼容端点所以代理层几乎不需要做消息格式转换做好模型映射和鉴权转发就够了。这也是为什么我建议尽可能选择原生 OpenAI 兼容的上游——协议转换越少出问题的概率越低。3.5 流式响应与工具调用的处理流式响应是 CLI 转 API 里最容易翻车的地方。各家协议虽然都是 SSE但事件格式完全不同。代理层的职责是把上游的流式数据逐段消费重新包装成统一的 OpenAI SSE 格式并且要保证finish_reason、usage等收尾信息能正确回传。工具调用function calling则复杂得多。如果一个客户端同时发起了工具调用代理层必须把 OpenAI 格式的tools定义转换成目标 CLI 能理解的格式并在模型返回工具调用后把执行结果传回给模型继续生成。这部分对一些只支持纯对话的 CLI 来说是无解的只能选择禁用它或者在上游层配置一个支持工具调用的 OpenAI 兼容模型。4. 常见问题与排查技巧实录4.1 认证类错误401 Unauthorized 与 login failed在实际使用中最容易碰到的是两类认证错误。第一类是代理层返回401 Unauthorized这通常是你调用代理时带的 API Key 和server.api_key配置不一致。排查方法很简单直接 curl 一次去掉Authorization头如果还是 401说明代理层配置没问题问题在调用方没有正确带 Key。第二类是代理层能启动但转发给上游时上游返回login failed或This client is no longer supported。这种大概率是 CLI 自身的登录态失效了。前端能登录不代表 CLI 的 token 仍然有效尤其是 Gemini 这类对客户端版本有强校验的服务升级 CLI 到最新版往往就能解决this client is no longer supported这类报错。我的建议是把 CLI 的认证方式尽量从交互式登录改成环境变量注入 API Key代理进程每次启动时都能拿到有效凭证稳定性会好很多。4.2 请求格式类错误400 与 thinking 模式问题如果你看到下面这种 400 报错upstream_status: http 400 cause: the reasoning_content in the thinking mode must be passed back to the api.这说明你用的上游比如 DeepSeek 系模型开了 thinking / 推理模式协议要求多轮对话时必须把上一轮返回的reasoning_content原样传回代理层在转换消息时把它丢弃了。解决办法有三个方向第一在代理配置里关闭思考模式或者选择非 thinking 的模型第二修改代理的消息转换逻辑把reasoning_content透传或合并到上下文里第三避免使用多轮对话每次请求都发独立问题绕开必须回传推理内容的限制。另一个高频的 400 是this models maximum context length is 1048576 tokens这类报错不是代理层的问题而是上下文超出了模型限制。排查时先看是不是调用方在一次请求里塞了超长文本再看是不是多轮历史被代理层重复累积了。不少代理工具在转发消息时会把会话历史整体传给上游一旦历史膨胀就很容易打满上下文。4.3 网络与上游类错误502、503 与超时502 Bad Gateway是代理层最常见的故障信号含义是代理能收到你的请求但它背后的上游没给出合法响应。可能原因包括目标 CLI 进程启动失败、CLI 路径配置错误、上游模型服务本身挂了、或者上游返回了代理层无法解析的内容。操作上关键是先关掉代理的流式转发手动在终端跑一次目标 CLI确认 CLI 自身能否正常出结果。如果 CLI 没问题再检查代理调用 CLI 的方式比如cli_path是否指向正确。503 Service Unavailable则基本是上游模型服务在限流或过载特别集中出现在各家模型的热门时段。策略上可以给代理配置多个上游做 fallback或者在上游模型服务侧开通更高的并发配额。另外如果代理日志里有大量超时记录检查一下是不是代理每次请求都新拉起一个 CLI 进程如果是建议改成进程复用模式否则每次请求都要吃一遍 CLI 启动时间并发一高必然超时。4.4 路径与端点错误404 Not Found有朋友会碰到类似这样的 404cc switch local proxy failed while handling codex endpoint /responses. provider: deepseek这通常不是代理没启动而是代理只实现了/v1/chat/completions端点但 Codex CLI 调用的是/v1/responses端点两边路径对不上。Codex 系列工具比较特殊它原生走的是 Responses API 而不是传统的 Chat Completions API。解决思路有两个一是让代理工具支持/v1/responses路径并做内部转换很多活跃维护的代理工具已经实现了二是把 Codex CLI 的端点配置指到支持/v1/responses的服务商避免路径不匹配。排查这类问题时直接在代理日志里看请求落到了哪个路径、转发给了谁比对着文档猜快得多。不同版本的工具行为差异很大升级到最新版也常常能解决路径兼容问题。4.5 CLI 环境与路径问题还有一个经常被忽略的坑unable to locate the codex cli binary. set codex cli path or ensure the executable is in PATH代理进程调用 CLI 时默认依赖系统的PATH环境变量去寻找可执行文件。但如果你是通过图形界面启动代理、或通过 init 守护进程拉起服务PATH往往和你终端里不一样于是找不到 CLI。解决办法是在代理配置里显式指定cli_path绝对路径。还有一个 Windows 下的特殊坑部分 Electron 壳包装的 CLI 实际可执行文件在安装目录深处直接用where命令找到的路径不一定能被代理正确调用建议先手动在命令行里执行一次这个路径确认能正常运行再写入配置。5. 实测结论与生产化建议5.1 延迟、并发与稳定性观察我实际跑了一段时间结论可以概括为延迟取决于 CLI 启动方式并发取决于 CLI 实现。如果把每个请求都新拉起一个 CLI 进程单次请求的固定开销可能多出 500ms 到 2 秒不等流式首字延迟会更明显。改成常驻进程复用模式后TTFB 能回到和直连 API 接近的水平。CLI 代理的并发能力天然有限毕竟所有请求都走本地 CLI单进程模型下并发超过 5 到 10 个就会出现排队。如果你打算做高并发服务我建议别在这条路上死磕直接在上游用官方 API 加网关会更可控。从稳定性看最容易拖垮代理的其实是 CLI 本身比如登录态过期、交互式确认弹窗、CLI 更新后配置格式变化。对策就一句话——把所有能通过环境变量配置的都放进环境变量让 CLI 变成一个无交互的后端程序而不是一个终端工具。5.2 用 systemd 或 Docker 把服务托管起来本地调试时终端挂着没问题但你想长时间运行最好还是用守护进程托管。Linux 下我习惯写一个简单的 systemd unit[Unit] DescriptionCLI Proxy API Afternetwork.target [Service] Typesimple Useryouruser ExecStart/usr/local/bin/cli-proxy start --config /etc/cli-proxy/proxy.yaml Restartalways RestartSec3 EnvironmentPATH/usr/local/bin:/usr/bin:/bin [Install] WantedBymulti-user.target注意我显式设置了PATH就是为了避免前面提到的 CLI binary 找不到的问题。如果你有多套环境要部署用 Docker 会更省心把 CLI 和代理工具一起打包进镜像配置通过环境变量注入但要注意容器内 CLI 的认证凭证管理不要直接写死在镜像层。5.3 接入自动化场景的扩展思路CLI 包装成 API 之后玩法就多了。我自己试过的几个场景把本地 CLI 接进微信/钉钉机器人团队群里直接问问题机器人转发给代理模型能力全员复用。在 CI 流水线里调用 agent 型 CLI让它审查代码、生成 commit message一次性提交到 PR comment 里。用 OpenAI SDK 写个批量评测脚本同时压测多个本地 CLI 上游对比不同模型在同一批 prompt 上的效果。配合统一网关把代理层暴露出去的 Key 统一纳管再也不用担心 Key 散落各处。最后一个建议如果你打算长期用这个方案需要为它补上日志采集和基础的可观测性把每次请求的模型名、上游耗时、token 消耗记录下来。这不是可选项而是排障的刚需。没有日志的代理出问题时就像在黑灯瞎火的厨房里找一把掉在地上的刀片你只能靠猜。我自己实际用下来的体会是CLI Proxy API 最适合的场景是把已经在 CLI 里配好的模型能力快速暴露给其他程序省掉重复配置和协议适配。别指望它替代生产级 API 网关也别在高并发场景强行上但在个人效率工具、团队内部自动化、模型横向评测这些场景里它确实是目前最轻量、最灵活的接法。推荐你从一个小场景开始试比如把一个通义或 DeepSeek 的 CLI 暴露给 ChatBox 使用跑通一次流程之后再逐步加模型、加映射、加自动化你会对这套链路有更完整的掌控感。