CLIProxyAPI：把多种 AI CLI 统一成兼容 API 的开源代理

工具>开源软件>AI
4.8k words

在使用 Codex、Claude Code、Gemini CLI 或其他 AI 编程工具时，常见的麻烦是：不同工具使用不同协议、认证方式和模型名称，切换账号或接入自定义客户端也不够方便。

CLIProxyAPI 提供了一个思路：在本机运行一个 Go 编写的代理服务，把多个 CLI 服务和上游模型统一暴露为 OpenAI、OpenAI Responses、Gemini 或 Claude 兼容接口。这样，原本只支持某一种协议的客户端，也可以通过一个本地端点访问已经配置好的模型来源。

本文根据 CLIProxyAPI 官方仓库 README、配置示例和用户手册整理，项目功能和版本信息以官方文档为准。

一、项目概览

项目 信息
项目定位 面向 CLI 模型的多提供商兼容 API 代理
实现语言 Go
支持平台 macOS、Linux、Windows，以及官方 Release 提供的其他构建目标
默认端口 8317
主要协议 OpenAI Chat Completions、OpenAI Responses、Gemini、Claude
认证方式 API Key、OAuth、上游兼容 API 配置
负载策略 轮询、加权轮询、优先填充等策略
开源协议 MIT
最新版本 v7.3.16（截至 2026-09-24）

CLIProxyAPI 不等于模型服务本身，也不会自动赠送任何模型额度。它负责的是协议适配、凭据管理、请求路由和多账号调度；使用者仍需要拥有相应的订阅、OAuth 授权或 API Key，并遵守服务商的使用条款。

二、它解决了什么问题

1. 统一不同客户端的调用协议

很多应用只支持 OpenAI 兼容接口，另一些工具则要求 Anthropic 或 Gemini 格式。CLIProxyAPI 可以把不同上游的请求和响应转换成客户端能够理解的协议。

例如，一个只支持 OpenAI SDK 的内部工具，可以通过本地 base_url 访问已经登录的 Codex、Gemini 或 Claude 账号，而不必为每一个服务单独实现一套适配器。

2. 管理多个账号并进行调度

项目支持 Gemini、OpenAI Codex、Claude Code 和 Grok Build 等多账号场景。配置多个凭据后，可以使用轮询、加权轮询或优先填充策略分配请求，并结合失败重试和冷却机制提高连续调用时的可用性。

这对个人开发者的多账号切换、团队内部的统一网关，以及需要隔离不同模型凭据的自动化任务都比较有用。

3. 同时支持流式、工具调用和多模态请求

官方功能列表包含：

  • 流式和非流式响应；
  • 在支持的场景下使用 WebSocket；
  • Function Calling / Tools；
  • 文本和图片等多模态输入；
  • OpenAI Responses 和 Gemini Interactions 等新接口形态；
  • 通过配置接入 OpenRouter 等 OpenAI 兼容上游。

具体能力仍取决于客户端、代理适配器和上游模型的共同支持，不能把协议兼容理解成所有模型功能都完全一致。

4. OAuth 登录与 API Key 可以并存

对于支持 OAuth 的 CLI 服务，可以通过 CLIProxyAPI 提供的认证流程完成登录；对于 Gemini API Key、Claude API Key 或其他 OpenAI 兼容服务，则可以直接写入配置。

这种方式适合把“订阅型 CLI 账号”和“标准 API 服务”放在同一个本地网关里管理。凭据默认存放在 ~/.cli-proxy-api，部署时应把这个目录当作敏感数据处理。

三、核心功能拆解

1. 多协议入口

客户端可以按自身支持的协议访问 CLIProxyAPI。常见入口包括 OpenAI 风格的 /v1/chat/completions、Responses 接口，以及 Claude 和 Gemini 兼容路径。统一入口的价值在于：更换上游时，业务代码和客户端配置通常只需要调整模型名或少量参数。

2. 凭据池与自动故障转移

当一个账号遇到额度、限流或临时服务错误时，代理可以根据重试和冷却配置切换其他可用凭据。routing.strategy 默认使用 round-robin，也可以根据账号权重或“优先使用当前账号”的需求调整。

这不是无限扩容方案：每个上游账号仍受自己的套餐、并发和速率限制约束。合理设置重试次数、冷却时间和账号权重，才能避免失败请求反复打到同一个不可用账号。

3. 管理 API 和控制面板

CLIProxyAPI 提供 Management API，用于查看和维护配置、凭据、日志、配额等资源。官方仓库也维护了独立的管理中心项目，适合不希望长期手工编辑 YAML 的用户。

管理接口权限较高，默认不允许远程管理。除非确实有跨机器运维需求，否则建议保持管理 API 只监听本机，并为管理接口设置独立的 secret-key。

4. 可嵌入的 Go SDK

如果你的项目不想以独立进程运行代理，CLIProxyAPI 还提供 Go SDK，可以把代理能力嵌入自己的 Go 服务。官方文档提供了基础用法、访问控制、凭据监听器和高级执行器/转换器示例。

嵌入方式适合需要自定义生命周期、路由或部署拓扑的开发者；普通使用者直接运行 Release 二进制会更简单。

四、最小配置示例

从官方仓库下载对应平台的 Release 压缩包，复制 config.example.yaml 为 config.yaml，先使用本机监听和一个临时 API Key 验证服务是否正常：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 仅监听本机，避免代理端点被局域网或公网直接访问
host: "127.0.0.1"
port: 8317

# 下游客户端访问 CLIProxyAPI 时使用的密钥
api-keys:
  - "replace-with-a-long-random-key"

# 管理接口默认只允许本机访问
remote-management:
  allow-remote: false
  secret-key: "replace-with-a-separate-management-key"

# OAuth 凭据和认证记录的目录
auth-dir: "~/.cli-proxy-api"

# 多账号路由策略
routing:
  strategy: "round-robin"

这里的两个密钥必须替换成随机值，并且不要提交到 Git 仓库。配置修改后重启服务，再按照官方认证指南完成对应提供商的 OAuth 登录或 API Key 配置。

五、用 OpenAI 兼容客户端调用

以 OpenAI Chat Completions 风格的请求为例，model 使用你在 CLIProxyAPI 中实际可用的模型名称：

1
2
3
4
5
6
7
8
9
10
curl http://127.0.0.1:8317/v1/chat/completions \
  -H "Authorization: Bearer replace-with-a-long-random-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "请用一句话介绍 CLIProxyAPI"}
    ],
    "stream": false
  }'

在 OpenAI SDK 中，通常只需要把 base_url 指向 http://127.0.0.1:8317/v1，把 API Key 设置为配置文件中的下游密钥。Claude Code、Gemini 客户端以及各类 AI 编程工具则应按照官方文档使用对应的协议入口和环境变量。

六、为什么值得推荐

1. 对客户端改动小

大量 SDK 和 AI 工具已经支持 OpenAI 或 Anthropic 兼容端点。CLIProxyAPI 把复杂的上游差异集中在代理层，客户端通常只需要修改端点、密钥和模型名。

2. 适合多账号和多模型工作流

账号轮询、权重、冷却和失败重试，让它比“手动切换配置文件”更适合持续运行的脚本、IDE 插件和 Agent 工作流。

3. 本地部署，边界清晰

代理可以只运行在开发机或内网服务器上，凭据和请求路径由使用者控制。对于不希望把所有客户端直接绑定到某一家 API 网关的场景，本地中间层更容易审计和迁移。

4. 生态扩展性较好

官方仓库已经列出了桌面托盘、配额看板、VS Code 扩展、管理面板等衍生项目，也提供 Go SDK 和插件机制。用户可以先从命令行二进制开始，后续再按需要增加管理界面。

5. MIT 协议，便于集成

MIT 协议对二次开发和商业集成较友好。不过，接入的上游服务、OAuth 账号和模型使用仍然受各自服务条款约束，开源协议并不会替代这些合规要求。

七、安全配置不能省略

CLIProxyAPI 处理的是模型凭据和可能包含敏感代码、日志、提示词的请求，部署时建议至少遵守以下原则：

  1. 默认将 host 设置为 127.0.0.1，不要无意中监听所有网卡；
  2. 为客户端 API Key 和 Management API 的 secret-key 使用不同的高强度随机值；
  3. 不要把 config.yaml、auth-dir、OAuth 文件和请求日志提交到公开仓库；
  4. 确需远程访问时，优先通过 VPN、SSH 隧道或反向代理的 HTTPS 入口，不要直接把管理 API 暴露到公网；
  5. 为反向代理正确配置可信代理来源，避免错误接受伪造的客户端 IP；
  6. 定期查看上游账号的登录记录、配额和异常请求，及时撤销不再使用的凭据。

特别需要注意的是：官方示例中的 host: "" 会绑定所有接口，适合了解行为但不适合作为公网部署的默认安全配置。管理 API 的 allow-remote 也不应在没有额外访问控制的情况下开启。

八、适合哪些人

CLIProxyAPI 比较适合：

  • 同时使用 Codex、Claude Code、Gemini 或 Grok 等 CLI 工具的开发者；
  • 想让多个 OpenAI 兼容客户端共用一套本地模型入口的人；
  • 需要多账号轮询、失败切换和配额冷却的自动化任务；
  • 想在局域网内统一管理 AI 工具，但仍希望自己掌握凭据和部署边界的团队；
  • 需要把协议适配能力嵌入 Go 服务的开发者。

如果你只调用一个模型、只有一个客户端，并且官方 SDK 已经满足需求，那么直接使用官方 API 往往更简单。CLIProxyAPI 的价值主要体现在“多提供商、多账号、多客户端”这几个条件同时出现时。

九、总结

CLIProxyAPI 可以理解为 AI CLI 服务的本地协议网关：它不负责创造模型能力，而是把认证、协议转换、账号池、路由、重试和管理能力集中到一个可自托管的 Go 服务中。

它最值得推荐的地方，是让客户端和上游服务解耦。你可以保留熟悉的 OpenAI 或 Claude 客户端调用方式，再根据需要切换授权来源、账号池和模型提供商。只要把密钥保护、监听地址和管理接口权限配置好，CLIProxyAPI 很适合作为个人开发环境或内部 AI 工具链的统一入口。

项目地址与资料