CLIProxyAPI 和 CPA Manager Plus：AI 网关与管理面板的组合用法

如果你在用 Codex、Claude Code、Gemini、Grok 或其他 OpenAI 兼容客户端，可能会遇到一个很现实的问题：模型能力本身不难接，难的是把 OAuth 登录、多账号轮询、请求失败排查、token 用量和费用估算放到同一套系统里管理。

CLIProxyAPI 和 CPA Manager Plus 正好可以组成这样一套方案。前者负责真正处理模型请求，后者负责管理、监控和观测。

两个项目分别是什么

CLIProxyAPI 是一个面向 AI CLI 和 SDK 的本地或自托管 API 网关。它提供 OpenAI、Gemini、Claude、Codex、Grok 兼容接口，支持 OAuth 登录、流式响应、工具调用、多模态输入、多账号轮询和上游 OpenAI 兼容 provider 接入。

简单说，CLIProxyAPI 是请求入口。Codex、Claude Code、OpenAI SDK、兼容 OpenAI API 的客户端，都可以把 base URL 指向它。

CPA Manager Plus 可以理解为 CLIProxyAPI 的管理与观测面板。它本身不替代 CLIProxyAPI 处理普通模型请求，而是连接到 CLIProxyAPI 的管理接口和用量队列，提供请求监控、费用分析、失败排查、账号健康巡检、Codex 配额检查、provider 管理和配置管理等能力。

它们的关系大概是这样：

Codex / Claude Code / OpenAI SDK / 其他兼容客户端
        |
        v
CLIProxyAPI
  - 接收普通模型请求
  - 处理 OAuth 与账号池
  - 路由到 Codex / Claude / Gemini / Grok / 上游 provider
  - 输出请求用量事件
        |
        v
CPA Manager Plus
  - 读取管理接口
  - 采集请求监控数据
  - 展示费用、失败、账号健康和配额状态

所以不要把 CPA Manager Plus 当成模型 API 的入口。客户端请求应该打到 CLIProxyAPI；CPA Manager Plus 负责在旁边帮你看清楚这些请求发生了什么。

为什么要把它们关联起来

单独使用 CLIProxyAPI 已经可以跑通很多场景，比如：

• 用 Codex 订阅跑 OpenAI 兼容请求。
• 用 Claude Code 账号提供 Claude 兼容接口。
• 用 Gemini、Grok 或 OpenAI 兼容 provider 做多模型接入。
• 用多账号轮询分摊额度和失败风险。

但当账号和请求变多后，运维问题会很快出现：

• 哪个账号已经失效？
• 哪个模型今天花费最高？
• 哪些请求失败最多？
• 是认证失败、额度不足、模型不支持，还是上游 provider 异常？
• Codex 账号什么时候恢复额度？
• 某个客户端 API Key 到底用了多少 token？

CPA Manager Plus 补上的就是这一层。它把 CLIProxyAPI 的使用情况变成可搜索、可过滤、可统计的面板，适合长期跑多账号池或多客户端接入的人。

推荐部署方式：Docker Compose 一起启动

如果是新环境，最省事的方式是用 Docker Compose 同时启动 CLIProxyAPI 和 CPA Manager Plus。

先准备 config.yaml：

host: ""
port: 8317

remote-management:
  secret-key: "replace-with-a-long-random-management-key"
  allow-remote: true

api-keys:
  - "replace-with-client-api-key"

usage-statistics-enabled: true
redis-usage-queue-retention-seconds: 60

这里有两个关键配置：

• remote-management.secret-key：CPA Manager Plus 连接 CLIProxyAPI 管理接口时要用。
• usage-statistics-enabled: true：开启请求用量事件，CPA Manager Plus 才能做请求监控和统计。

然后创建 docker-compose.yml：

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxy-api
    restart: unless-stopped
    ports:
      - "8317:8317"
      - "1455:1455"
      - "54545:54545"
      - "51121:51121"
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs

  cpa-manager-plus:
    image: seakee/cpa-manager-plus:latest
    container_name: cpa-manager-plus
    restart: unless-stopped
    ports:
      - "18317:18317"
    environment:
      HTTP_ADDR: "0.0.0.0:18317"
      USAGE_COLLECTOR_MODE: "auto"
    volumes:
      - cpa-manager-plus-data:/data
    depends_on:
      - cli-proxy-api

volumes:
  cpa-manager-plus-data:

启动服务：

mkdir -p auths logs
docker compose up -d

启动后打开管理页面：

http://你的服务器IP:18317/management.html

如果没有手动指定 CPA Manager Plus 的管理员密钥，可以从容器日志里查看首次生成的 admin key：

docker compose logs cpa-manager-plus

第一次进入 CPA Manager Plus 时，通常需要填写这几项：

CPAMP 管理员密钥：从 cpa-manager-plus 日志里获取
CPA URL：http://cli-proxy-api:8317
CPA Management Key：config.yaml 里的 remote-management.secret-key
请求监控方式：auto

如果两个容器在同一个 Docker Compose 网络里，CPA URL 推荐写 http://cli-proxy-api:8317。不要在 CPA Manager Plus 容器里写 127.0.0.1:8317，因为那会指向 CPA Manager Plus 容器自己，而不是 CLIProxyAPI 容器。

登录账号

CLIProxyAPI 需要先拿到对应平台的认证信息。以 Docker Compose 部署为例，可以进入容器执行登录命令：

docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --claude-login
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --antigravity-login

具体支持哪些登录方式，以 CLIProxyAPI 当前文档和版本为准。登录完成后，认证文件会保存在前面挂载的 ./auths 目录里，后续容器重启也能复用。

客户端怎么接入

普通客户端只需要连接 CLIProxyAPI。

OpenAI 兼容客户端可以这样填：

Base URL: http://你的服务器IP:8317/v1
API Key:  config.yaml 里 api-keys 配置的值
Model:    CLIProxyAPI 暴露的模型名或别名

如果客户端和 CLIProxyAPI 在同一台机器，也可以用：

Base URL: http://127.0.0.1:8317/v1

Codex 这类工具通常也是把 provider 的 base URL 指到 CLIProxyAPI 的 /v1 端点，然后使用你在 api-keys 里配置的 key。请求经过 CLIProxyAPI 后，CPA Manager Plus 才会在监控面板里看到请求记录、token 用量、延迟、状态码和失败摘要。

日常使用流程

一套比较顺手的工作流是：

1. 在 CLIProxyAPI 里配置 API Key、OAuth 账号、模型别名和 provider。
2. 在客户端中把 base URL 指向 http://host:8317/v1。
3. 在 CPA Manager Plus 里查看 Dashboard、请求监控、费用分析和账号巡检。
4. 如果某个请求失败，先看 CPA Manager Plus 的失败摘要和账号维度统计。
5. 如果确认是认证、额度或 provider 配置问题，再回到 CLIProxyAPI 的账号、日志和配置里处理。

这样分工会比较清楚：CLIProxyAPI 负责跑流量，CPA Manager Plus 负责看流量。

常见问题

为什么 CPA Manager Plus 里没有请求记录？

优先检查三件事：

• 客户端请求是不是打到了 CLIProxyAPI，而不是绕过了它。
• CLIProxyAPI 配置里是否开启了 usage-statistics-enabled: true。
• CPA Manager Plus 首次设置里的 CPA URL 和 CPA Management Key 是否正确。

如果是 Docker Compose 内部互连，CPA URL 应该用服务名，例如：

http://cli-proxy-api:8317

CPA Manager Plus 能不能直接作为模型 API 使用？

不建议这样理解。普通模型请求入口是 CLIProxyAPI。CPA Manager Plus 的重点是管理、监控、分析和运维。

已经有 CLIProxyAPI 了，还能单独加 CPA Manager Plus 吗？

可以。只要现有 CLIProxyAPI 开启远程管理和用量事件，再单独启动 CPA Manager Plus，把 CPA URL、Management Key 和监控方式配置好即可。

生产环境要注意什么？

至少要注意这几件事：

• remote-management.secret-key 和客户端 API Key 要足够长，不能使用示例值。
• 不要把管理页面裸露在公网，建议放到反向代理、访问控制或内网后面。
• 定期备份 CPA Manager Plus 的 /data 数据卷。
• 定期备份 CLIProxyAPI 的认证文件目录。
• 升级前先看两个项目的 release note，尤其是管理接口和用量队列相关变更。

总结

CLIProxyAPI 和 CPA Manager Plus 的组合，本质上是“网关 + 面板”的结构。

CLIProxyAPI 负责真正接收模型请求、处理 OAuth、多账号轮询和 provider 路由；CPA Manager Plus 负责把这些请求转成可观察、可检索、可统计的管理界面。对只是临时试用的人来说，单独跑 CLIProxyAPI 就够了；对长期使用 Codex、Claude Code、多账号池或多个客户端的人来说，加上 CPA Manager Plus 会更容易定位失败、控制费用和维护账号健康。

参考：

• router-for-me/CLIProxyAPI
• CLIProxyAPI 中文手册
• seakee/CPA-Manager-Plus
• CPA Manager Plus 文档