CPA中转站搭建教程：CLIProxyAPI + NewAPI 账号池网关

面向开发者和站长的 CPA中转站搭建教程：解释 CLIProxyAPI 与 NewAPI 分工、账号池架构、部署路径、接入测试、安全配置和常见排障。

先说结论

搭 CPA中转站，核心问题通常不是“装哪个面板”，而是怎么把 Codex、Claude Code、Gemini CLI、Grok Build 或 OpenAI 兼容上游变成稳定可管理的 API，再交给 NewAPI、团队用户或 AI 编程工具使用。

最常见的 CPA中转站架构是：

flowchart TD upstream("上游账号 / API") cpa("CLIProxyAPI / CPA") newapi("NewAPI") clients("客户端 / 用户") upstream -->|"OAuth / API Key"| cpa cpa -->|"统一 API"| newapi newapi -->|"Base URL / Token"| clients

这套方案更适合开发者、站长和小团队搭一个可控的账号池 API 网关。你可以用它自用、团队内部分发、测试不同上游，也可以研究中转站供应链；如果准备公网运营，需要先把风控、凭证安全、访问控制和合规边界想清楚。

CPA中转站是什么

CPA 通常是 CLIProxyAPI 的简称。官方文档把 CLIProxyAPI 定义为一个为 CLI 提供 OpenAI、Gemini、Claude、Codex、Grok 兼容 API 接口的代理服务器，并支持 OAuth 登录、多账户轮询、流式响应、函数调用、多模态输入和 OpenAI 兼容上游接入。

在 CPA + NewAPI 架构里，它的角色更具体：

层级负责什么
账号层Codex、Claude Code、Gemini CLI、Grok Build、AI Studio、OpenAI 兼容上游
CPA 层把账号、OAuth 登录态或上游 Key 转成统一 API
NewAPI 层渠道、用户、令牌、额度、模型价格和统一出口
客户端层Claude Code、Codex、Cursor、OpenCode、Cherry Studio、SDK

完整的 CPA中转站通常分两层：CPA 负责“账号如何变 API”，NewAPI 负责“API 如何分发给用户”。如果只自用，可以先不上 NewAPI；如果要多人使用，就需要分发层。

什么时候该用 CPA + NewAPI

不要一开始就把结构做重。CPA + NewAPI 能解决多人分发问题，但也会增加配置、排障和安全成本。

你的目标建议方案
只想自己把一个账号转 API先单独部署 CPA
想给 2-10 人团队发统一 KeyCPA + NewAPI 或 CPA + 轻量面板
想把 Codex、Claude Code、Gemini CLI 多个来源统一起来CPA + NewAPI 更合适
想做公开注册、充值、额度、价格管理NewAPI 这类分发层基本不可少
想把订阅账号能力公开售卖不建议，先确认平台条款、风控和凭证隔离

第一次部署建议先做一个只允许自己访问的内网或本地版本，用一个账号、一个模型、一个客户端跑通。确认 CPA 能调用、NewAPI 渠道能测试、客户端能稳定使用后，再接域名、Cloudflare、支付和用户系统。

部署前准备

准备这些东西：

  1. 一台 Linux 服务器，建议 Ubuntu 22.04+，至少 2 核 2GB 起步。
  2. Docker 和 Docker Compose v2。
  3. 一个域名，后续给 NewAPI 或对外 API 使用。
  4. 你合法持有的上游账号或 API Key。
  5. 一个只用于测试的低权限 API Key，不要一上来用主账号高额度 Key。

服务器端口建议：

服务常见端口建议
CPA / CLIProxyAPI8317只给 NewAPI 或可信 IP 访问
NewAPI3000通过域名和 HTTPS 对外
Nginx / Caddy80 / 443负责 TLS 和反向代理

如果 CPA 和 NewAPI 在同一台机器上，优先让 CPA 只监听本机或只允许内网访问。对外入口一般应该放在 NewAPI，而不是 CPA 管理面板。

第一步：部署 CLIProxyAPI，也就是 CPA

官方文档提供 macOS、Linux、Windows、Docker 和 Docker Compose 多种方式。站长场景建议用 Docker Compose，因为配置、认证目录和备份都更清楚。

官方 Docker 最小运行方式类似这样：

docker run --rm \
  -p 8317:8317 \
  -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml \
  -v /path/to/your/auth-dir:/root/.cli-proxy-api \
  eceasy/cli-proxy-api:latest

如果用 Docker Compose，官方流程是克隆仓库、复制 config.example.yaml 为 config.yaml，然后启动：

git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
cp config.example.yaml config.yaml
docker compose up -d

启动后先看日志：

docker compose logs -f

不要急着接 NewAPI。先确认 CPA 本身能跑起来，再处理账号登录和上游配置。

第二步：配置 CPA 的基础安全项

CPA 会处理配置、请求认证和账号凭证，安全配置要比普通博客后台更严肃。

在 config.yaml 里优先检查这些项：

host: "127.0.0.1"
port: 8317

remote-management:
  allow-remote: false
  secret-key: "换成强随机管理密钥"

auth-dir: "~/.cli-proxy-api"

api-keys:
  - "换成给 NewAPI 使用的强随机 key"

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

这里的重点不是照抄，而是理解边界：

  • host 如果填 127.0.0.1，CPA 只允许本机访问，适合同机 NewAPI。
  • remote-management.allow-remote 不要随便开，管理 API 能改运行时配置和认证文件。
  • secret-key 要用强随机值，不要用 admin、123456、项目名。
  • api-keys 是 CPA 对外服务认证，后面 NewAPI 接 CPA 时会用到。
  • auth-dir 是凭证目录，备份和权限都要管好。

如果 NewAPI 和 CPA 不在同一台服务器，8317 也不要直接全网开放。至少做防火墙白名单、反向代理认证、强密钥和日志审计。

第三步：登录或接入上游账号

CPA 支持多种上游，站长最常用的是 Codex、Claude Code、Gemini CLI 和 OpenAI 兼容提供商。

Docker Compose 场景下，官方文档给出的登录命令包括：

# OpenAI Codex
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login

# Claude Code
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --claude-login

# Gemini CLI
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --login

-no-browser 会打印登录地址，适合服务器环境。登录完成后，认证文件会进入你挂载的 auth-dir。这个目录就是账号池的核心资产。

如果你接的是 OpenAI 兼容上游，例如 OpenRouter 或其他兼容 Base URL，则在 CPA 的提供商配置中添加对应 base-url、api-key、模型列表和别名。

第四步：先用 CPA 做本地最小测试

在接 NewAPI 前，先用最小请求确认 CPA 可用。假设 CPA 暴露在本机 8317，并且你配置了 CPA_API_KEY：

export CPA_BASE_URL="http://127.0.0.1:8317/v1"
export CPA_API_KEY="填入 config.yaml 里的 api key"

curl -sS "$CPA_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $CPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-codex",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: cpa-ok"
      }
    ],
    "stream": false
  }'

如果这里失败，先不要改 NewAPI 渠道。优先排查 CPA：

错误优先检查
401CPA API Key 是否和 config.yaml 一致
404Base URL 是否应该带 /v1，模型名是否存在
429上游账号是否限流或额度耗尽
502 / 503上游登录态、代理、网络和账号状态
返回 HTML请求打到了错误的反代地址或面板端口

第五步：把 CPA 接入 NewAPI

NewAPI 这层主要负责把 CPA 变成一个可管理渠道。常见流程是：

  1. 登录 NewAPI 管理后台。
  2. 进入渠道管理，新增渠道。
  3. 渠道类型选择 OpenAI 兼容或对应兼容类型。
  4. Base URL 填 CPA 地址，例如 http://127.0.0.1:8317/v1。
  5. 密钥填 CPA 的 api-keys。
  6. 模型列表填你希望 NewAPI 暴露的模型。
  7. 保存后做渠道测试。
  8. 创建 NewAPI 令牌，再用 NewAPI 的 Base URL 给客户端使用。

同机部署时，NewAPI 到 CPA 可以走 127.0.0.1 或 Docker 网络服务名。公网用户不应该直接拿 CPA 的 Key，而是拿 NewAPI 发出的用户 Token。

CPA、NewAPI、客户端字段怎么对应

最容易填错的是 Base URL 和 API Key。按这个表先对齐：

位置Base URL 填什么API Key 填什么给谁用
CPA 本地测试http://127.0.0.1:8317/v1CPA config.yaml 里的 api-keys管理员自测
NewAPI 渠道CPA 的内网或本机地址，例如 http://127.0.0.1:8317/v1CPA api-keysNewAPI 调 CPA
终端客户端NewAPI 对外地址，例如 https://api.example.com/v1NewAPI 发出的用户令牌Codex、Claude Code、Cursor、SDK
不建议CPA 裸露公网地址CPA 底层 Key终端用户

一句话：CPA Key 给 NewAPI，不要直接给终端用户；终端用户拿 NewAPI 的 Base URL 和 Token。

第六步：给开发者客户端使用

CPA中转站的最终价值，是让开发者工具能稳定接入。不同客户端要看协议。

Codex

官方文档的 Codex 客户端配置思路是修改 ~/.codex/config.toml 和 ~/.codex/auth.json。如果直接连 CPA，base_url 通常类似：

model_provider = "cliproxyapi"
model = "gpt-5.5"
model_reasoning_effort = "high"

[model_providers.cliproxyapi]
name = "cliproxyapi"
base_url = "http://127.0.0.1:8317/v1"
wire_api = "responses"

auth.json：

{
  "OPENAI_API_KEY": "sk-dummy"
}

如果你让用户走 NewAPI，就把 base_url 换成 NewAPI 对外地址，把 Key 换成 NewAPI 令牌。

如果你使用 OAuth 登录模式，官方示例还会用 experimental_bearer_token、requires_openai_auth 和 supports_websockets 等字段。不要把所有配置混在一起；先选一种模式跑通，再继续改模型和推理等级。

Claude Code

Claude Code 常见环境变量包括：

export ANTHROPIC_BASE_URL="http://127.0.0.1:8317"
export ANTHROPIC_AUTH_TOKEN="填入可用 key"
export ANTHROPIC_DEFAULT_OPUS_MODEL="gpt-5-codex(high)"
export ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5-codex(medium)"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5-codex(low)"

注意：普通 OpenAI chat 请求能通，不代表 Claude Code 一定能用。Claude Code 对模型名、流式、Anthropic 兼容行为更敏感，必须单独测试。

CC Switch

如果你经常在官方 API、NewAPI、CPA、本地模型之间切换，可以把跑通后的 Base URL 和 Key 放进 CC Switch 管理。顺序一定是先手动跑通，再交给配置管理工具。

CPA中转站常见架构

自用架构

flowchart TD client("本机客户端") cpa("CPA") upstream("Codex / Claude Code / Gemini CLI / 兼容上游") client -->|"本地调用"| cpa cpa -->|"账号路由"| upstream

适合开发者自己用，结构简单，问题少。

小团队架构

flowchart TD clients("团队客户端") newapi("NewAPI") cpa("CPA") upstream("多个账号 / 多个上游") clients -->|"Base URL / Key"| newapi newapi -->|"额度 / 渠道"| cpa cpa -->|"账号路由"| upstream

适合 2-20 人团队。NewAPI 负责发 Key、限制额度和看用量，CPA 负责账号池。

公开分发架构

flowchart TD users("用户 / 客户端") edge("域名 / HTTPS / WAF / 反代") newapi("NewAPI") cpa("CPA 内网服务") upstream("账号池 / 上游 API / OAuth 登录态") users -->|"请求"| edge edge -->|"转发"| newapi newapi -->|"渠道调用"| cpa cpa -->|"账号路由"| upstream

如果要对外分发，重点已经不只是部署 CPA，还要考虑支付、风控、滥用、日志、备份、账号异常和客服。

上线前检查清单

检查项合格标准
CPA 管理接口不裸露公网，强密钥，最好只允许本机或白名单
CPA API Key强随机，和管理密钥分开
认证目录有备份，有权限控制，不进公开仓库
NewAPI 渠道渠道测试通过，模型列表和价格不乱填
客户端测试curl、Codex、Claude Code 至少各跑一次最小请求
日志能看到失败原因，但不记录明文用户 Key
风控单用户额度、频率限制、异常请求处理
域名和证书对外只暴露 HTTPS

最容易踩的坑

1. CPA 和 NewAPI 的 Base URL 填错

CPA 自身面板地址、CPA API 地址、NewAPI 对外地址不是一回事。

地址用途
http://127.0.0.1:8317CPA 服务或管理面板
http://127.0.0.1:8317/v1OpenAI 兼容 API 常用地址
https://api.example.com/v1NewAPI 对外给用户的地址

客户端填错地址时，常见表现是 404、返回 HTML、模型不存在。

2. 把 CPA Key 直接发给用户

如果你是站长，不要把 CPA 的底层 Key 发给终端用户。用户应该拿 NewAPI 的令牌。CPA Key 泄露后，别人可能绕过你的用户、额度和计费层。

3. 只看能不能回复，不测工具链

中转站能回答一句话，只能说明最小 chat 请求通了。开发者还要测：

  • 流式输出是否稳定。
  • Codex 的 Responses 协议是否可用。
  • Claude Code 的 Anthropic 兼容变量是否生效。
  • 长上下文是否被截断。
  • NewAPI 后台扣费和返回 usage 是否大体一致。

4. 过早打开远程管理

CLIProxyAPI 的管理 API 可以管理运行时配置和认证文件，官方文档也明确管理 API 请求需要管理密钥。远程管理不是不能开，而是不能裸开。

5. 把账号池当成 SLA

多账号轮询只能缓解单账号限流，不等于服务稳定。上游改规则、账号风控、OAuth 失效、模型下线，都会让 CPA中转站突然出问题。

常见报错怎么排

现象优先检查
401 UnauthorizedKey 填错，或把 NewAPI 用户 Key 填到了 CPA 测试里
404 Not FoundBase URL 层级错了，常见是漏了 /v1 或打到面板地址
429 Too Many Requests上游账号限流、额度耗尽，或客户端重试过快
502 / 503CPA 上游登录态失效、网络代理异常、账号不可用
返回 HTML请求打到了 NewAPI 面板、Nginx 默认页或错误域名
模型不存在CPA 模型名、NewAPI 模型映射、客户端模型名没有对齐
普通 curl 能通，Claude Code / Codex 不通协议、流式、Responses API 或 Anthropic 兼容配置不匹配

排障顺序

出问题时按这条链路排，不要只在 NewAPI 面板里反复调整：

  1. 上游账号是否正常：登录态、额度、封禁、区域、代理。
  2. CPA 是否正常：日志、配置、模型名、API Key、认证目录。
  3. CPA 最小 curl 是否正常：先绕过 NewAPI 测。
  4. NewAPI 渠道是否正常：Base URL、密钥、模型映射、渠道状态。
  5. 客户端是否正常：Codex、Claude Code、Cursor 的协议和环境变量。
  6. 反向代理是否正常：Nginx、Cloudflare、HTTPS、请求头、超时。

这个顺序能省很多时间。很多“模型不可用”看起来像客户端配置问题，实际是 CPA 登录态、Base URL 或上游账号先出了问题。

这篇教程适合的最终方案

使用场景推荐方案适用边界
开发者自用✅ CPA 单独部署 + 本地客户端直接连最简单，适合先跑通账号、模型和客户端
小团队✅ CPA + NewAPI + 内部令牌 + 白名单访问适合团队共用 Base URL、Token 和额度管理
小规模公开分发🟡 CPA 内网部署 + NewAPI 对外 + HTTPS + 额度限制 + 日志审计可以试运营，但要控制用户规模和上游风险
不建议❌ CPA 裸露公网 + 管理密钥弱口令 + 直接给用户 CPA Key + 无风控售卖会绕过用户、额度和访问控制，不适合真实运营

参考资料

CPA中转站 CLIProxyAPI NewAPI 中转站搭建 账号池 Docker

相关工具

CLIProxyAPI：CPA中转站账号池 API 网关 一个面向开发者和站长的开源 API 代理网关，常用于 CPA中转站、账号池、CLI 转 API、Codex / Claude Code / Gemini CLI 多账号轮询和 OpenAI 兼容分发。 CC Switch 管理 Claude Code 与 Codex 配置 一个面向开发者的配置管理工具，适合整理 Claude Code、Codex、Gemini CLI、OpenCode、provider 档案、Base URL、API Key、MCP、prompts 和 skills。 API Relay Check：中转站检测与模型掺水验证工具 一个面向 AI API 中转站的验证入口，用于小额验货：检查中转站是否疑似掺水、模型冒充、隐藏注入、Token 用量异常、TTFT 过慢、SSE 流不稳定，以及 Claude Code / Codex 接入风险。

相关错误

Error 401 Unauthorized：AI API 中转站认证排查 401 是认证失败信号。先检查当前加载的是哪一个 Key、请求打到哪个 Base URL、header 格式是否正确，以及这个 Key 是否仍然在对应 provider 中有效。 Error 429 Too Many Requests：AI API 中转站限流排查 429 通常是限流或额度信号。先检查 Retry-After、请求频率、账号余额、模型限制，以及工具是否在循环重试同一个失败调用。 Claude Code / Codex 503 No available accounts：中转站账号池不可用排查 先不要盲目换 Key。这个错误通常说明账号池、供应商、分组或模型路由暂时不可用。先测最小请求、确认模型和分组，再判断是等待恢复、降低上下文，还是换 provider。