CLIProxyAPI 一站式部署指南：把 Gemini、Claude、Codex 统一变成本地 API

一个代理搞定多模型 API 不统一的痛点

2026-07-24 约 2696 字预计阅读 6 分钟

/images/Code-Art-Studio-images/cli-proxy-api-unified-local-api/cli-proxy-api-unified-local-api.webp

CLIProxyAPI 一站式部署指南：把 Gemini、Claude、Codex 统一变成本地 API

这是什么？

CLIProxyAPI 是一个开源代理服务器，目前 GitHub 上已有 39K+ Stars。它用 Go 语言编写，核心作用是把 Antigravity、ChatGPT Codex、Claude Code、Grok Build 等命令行 AI 工具的调用能力，统一包装成 OpenAI / Gemini / Claude / Codex 兼容的 API 接口。

简单说：你只需要写一套 API 调用代码，就能通过 CLIProxyAPI 访问 Gemini、Claude、GPT、Grok 等模型，甚至可以通过网页 OAuth 免费使用 Gemini 3.1 Pro、GPT 5.5 等高级模型。

这个项目的核心价值是解决“接口不统一”的痛点。原本每个 AI 命令行工具都有自己的调用方式，开发者想切换模型或同时使用多个模型非常麻烦。CLIProxyAPI 把这些 CLI 工具变成了统一风格的 API 服务，还能通过 OAuth 机制自动处理多账户登录，把一个账号的免费额度，变成可编程调用的本地 API。

官方文档：https://help.router-for.me/cn/introduction/what-is-cliproxyapi

部署方案选型

CLIProxyAPI 支持 Docker Compose、WSL 直跑、Windows 原生三种部署方式。对大多数只想尽快恢复可用的人，建议先看下面这张对比表：

方案	适用场景	优点	缺点
Docker Compose	长期常驻、版本固化	环境一致、升级回滚方便	多一层容器网络、OAuth 回调端口映射复杂
WSL 直跑	已有 Linux 开发环境	输出直观、调试方便	需处理 WSL 与 Windows 之间的代理穿透
Windows 原生	不想折腾代理的用户	直接继承宿主机网络、OAuth 流程最顺畅	需手动管理后台启动

如果你的工作流已经长期跑在 Win11 + WSL2 上，且最在意的是“少碰代理坑、先跑通再说”，那么 Windows 11 原生直跑 通常是更合适的第一选择。Docker 更适合在你已经验证稳定之后，再把它封装成长期基础设施。

Windows 原生部署实战

第一步：下载与目录准备

从 GitHub Releases 下载最新 Windows 版本。写作本文时，官方已发布到 v7.2.97，说明项目维护非常活跃。

建议在 Windows 上建一个固定目录，后续配置、认证、日志都放在这里：

mkdir D:\CLIProxyAPI -Force
mkdir D:\CLIProxyAPI\auths -Force
mkdir D:\CLIProxyAPI\logs -Force

把下载的 zip 包解压到 D:\CLIProxyAPI，确保目录下有 cli-proxy-api.exe 和 config.example.yaml。

第二步：最小配置

官方基础配置页说明，程序默认读取项目根目录下的 config.yaml，也支持用 --config 显式指定路径。先把 config.example.yaml 复制成 config.yaml，再改下面几个关键项。

最容易搞混的一点是：api-keys 是客户端访问 CLIProxyAPI 时要带的 Key，不是上游模型供应商的 Key。 Gemini、Claude、Codex、OpenRouter 的密钥，要填到各自独立配置段里。

推荐先改成这份“能跑起来的最小模板”：

host: "127.0.0.1"
port: 8317

remote-management:
  allow-remote: false
  secret-key: ""
  disable-control-panel: false

auth-dir: "D:/CLIProxyAPI/auths"

api-keys:
  - "sk-local-001"

debug: false
request-log: false
logging-to-file: true
usage-statistics-enabled: true

proxy-url: ""
request-retry: 3

quota-exceeded:
  switch-project: true
  switch-preview-model: true

改的时候注意几个版本细节：官方中文配置详解已经把 Gemini 官方 Key 的新字段写成 gemini-api-key，旧字段 generative-language-api-key 会自动迁移，所以新配置优先用新字段。OpenAI 兼容供应商里旧字段 api-keys 也会自动迁移为 api-key-entries。

第三步：启动与自测

保存后，在 PowerShell 里启动服务：

Set-Location D:\CLIProxyAPI
.\cli-proxy-api.exe --config D:\CLIProxyAPI\config.yaml

如果 logging-to-file 设为 true，日志会写入 logs 目录；第一阶段不建议急着填上游 Key，先确认“程序能启动、端口能监听、本地鉴权能工作”。

新开一个 PowerShell 窗口做自检：

curl.exe -H "Authorization: Bearer sk-local-001" http://127.0.0.1:8317/v1/models

如果返回模型列表 JSON，说明程序启动成功、端口监听成功、配置文件被正确读取、api-keys 鉴权正常。常见的失败原因只有三类：YAML 缩进错误、程序没真正启动、8317 端口被占用。

第四步：接入上游模型

本地代理跑通之后，再根据你现有的账号情况，逐步把上游模型接进去。

如果你有 Google 官方 Key，可以启用 gemini-api-key；如果你有 Claude 官方或中转 Key，可以启用 claude-api-key；如果你有 Codex / OpenAI 中转 Key，可以启用 codex-api-key；如果你使用 OpenRouter、火山引擎、硅基流动等 OpenAI 兼容供应商，可以在 openai-compatibility 里配置。

另外，CLIProxyAPI 还支持 OAuth 网页登录方式，包括 Gemini、Codex、Claude、Qwen、iFlow 等。OAuth 登录后，认证文件会存入 auth-dir，程序会自动做多账号轮询和配额切换。对只想先验证服务通不通的人，建议优先做 Gemini 登录，最容易先出结果。

客户端接入方式

服务启动后，最常用的三个接口是 GET /v1/models、POST /v1/chat/completions 和供 Claude 风格客户端使用的 POST /v1/messages。

OpenAI 兼容 SDK 只要把 base_url 改成 http://127.0.0.1:8317/v1 就能直接使用，api_key 可以填 dummy，因为很多 SDK 强制要求这个字段存在。

curl 自检示例：

curl http://127.0.0.1:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-local-001" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [
      {"role": "user", "content": "你好，给我一句话介绍 CLIProxyAPI"}
    ],
    "stream": false
  }'

Python 接入示例：

from openai import OpenAI

client = OpenAI(
    api_key="sk-local-001",
    base_url="http://127.0.0.1:8317/v1"
)

resp = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "你好"}]
)

print(resp.choices[0].message.content)

如果你要把它用在 Claude Code 中，可以把 ANTHROPIC_BASE_URL 指向本地代理；如果要用在 Codex 中，可以在 ~/.codex/config.toml 里把 provider 指向本地的 responses 兼容接口。

常见坑与排错

配额打满：打开 quota-exceeded.switch-project: true 和 switch-preview-model: true，程序会在多账号之间自动切换，Gemini 正式版额度耗尽后也会自动切到 Preview 变体。

代理问题：官方配置支持全局 proxy-url，也支持给单个 Key 单独写 proxy-url。第一轮建议先留空测试，这样最容易分清是程序问题还是代理问题。

改了配置没生效：CLIProxyAPI 默认会监听配置文件和 auth-dir 变化并热重载，所以更常见的真实原因其实是字段写错、路径写错、端口没映射或 OAuth 回调端口被占用。

远程管理要小心：remote-management.allow-remote: false 时只有 localhost 能访问管理接口；secret-key 为空时，整个管理 API 会直接变成 404，相当于禁用。

总结

CLIProxyAPI 最大的意义，是让你不必再为“每个模型有各自 API、每个工具有各自协议”这件事反复折腾。通过它，你可以把多个 CLI 工具和多个 API Key 统一到本地一个 http://127.0.0.1:8317 上，再用标准 OpenAI / Gemini / Claude / Codex 协议访问。

对大多数个人用户和开发者，推荐顺序是：先 Windows/WSL 原生直跑跑通 → 再按需接入上游 Key 和 OAuth → 最后如果确需长期固化，再封装进 Docker Compose。

关联阅读

[[CLIProxyAPI-一款强大的可以实现大模型服务API调用自由的工具]]
[router-for-me_CLIProxyAPI_ Wrap Gemini CLI, Antig](router-for-me_CLIProxyAPI_ Wrap Gemini CLI, Antig.md)

–全文完–

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：　　　《内容已折叠，点击展开》

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。　　　　　　　　　　　　　　　　　　　　　《内容已折叠，点击展开》

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

转载请注明来自https://oklife.me。