企业官网建设流程全解析

手里的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 之前，我确实也试过另外两种方案，各有各的坑。这里整理成表格，方便你对比之后做决定。

直接改环境变量的方式，应付"一个工具接一个供应商"的场景还行，但一旦涉及多模型切换就会很痛苦。比如 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_KEY

Route 是请求的转发规则。最简单的规则是按模型名匹配，也可以按前缀匹配。比如我希望所有claude-开头的模型名都走 Anthropic，所有grok-开头的模型名都走 xAI，其余走默认的 OpenAI：

routes: - 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 与 DeepSeek

4.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 = "responses"

wire_api = "responses"这行很关键。Codex 默认走 OpenAI 的 Responses API，即/v1/responses这个端点，而不是大家更熟悉的/v1/chat/completions。CLIProxyAPI 需要对 Responses API 的请求做协议转换，才能转发给那些只支持 Chat Completions 的供应商。

设置好之后，在 shell 里导出一个占位密钥：

export LOCAL_GATEWAY_KEY=local-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_URL=http://127.0.0.1:8787 export ANTHROPIC_AUTH_TOKEN=local-dev-key export ANTHROPIC_MODEL=claude-sonnet-4

Claude 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 上还遇到了Claude's 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，网关就会自动转发到 xAI，Codex 和 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 报错速查表

我把这段时间自己遇到和帮朋友排查过的问题整理成一份速查表，按报错信息、可能原因、解决手段排列，方便你按图索骥。

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 编码工具要管理，不妨试试把接入层收敛到一个本地网关，配置一次，长期受益。后面如果再接入新的模型服务商，我还会继续补充这个项目的实战经验。