CPA 配置参数详解
从基础监听、TLS、管理接口到各类上游 provider 映射，整理一份适合查阅的 CPA 配置参数参考。
· 6 min read
目录
这篇文章整理的是 CPA 配置文件中的主要字段，适合作为查阅型文档使用。
第一次上手，先把前 6 节读一遍就够：顶层字段、TLS、管理接口、pprof、配额超限、路由。Provider 配置块和 payload 规则用到什么翻什么。
顶层基础字段 #
服务监听、日志、重试、代理、冷却都在这里配。
| 字段 | 类型 | 当前值/示例 | 是否生效 | 含义 | 常见取值/说明 |
|---|---|---|---|---|---|
host |
string |
"" |
生效 | 服务监听地址 | "" 表示监听所有网卡；127.0.0.1 / localhost 表示仅本机访问 |
port |
int |
8317 |
生效 | 服务监听端口 | 需要与 Docker 的 -p 宿主机端口:容器端口 对应 |
auth-dir |
string |
"~/.cli-proxy-api" |
生效 | 认证数据目录 | 支持 ~，通常保存 token、会话和认证缓存 |
api-keys |
list[string] |
["your-api-key-1", ...] |
生效 | 客户端访问代理时使用的 API Key | 这是代理入口鉴权，不是上游厂商的 key |
debug |
bool |
false |
生效 | 是否输出调试日志 | true 时日志会更详细 |
commercial-mode |
bool |
false |
生效 | 是否启用低开销模式 | 开启后会减少高开销中间件，适合高并发 |
logging-to-file |
bool |
false |
生效 | 是否写日志到文件 | false 时通常输出到 stdout |
logs-max-total-size-mb |
int |
0 |
生效 | 日志文件总大小上限（MB） | 0 表示不限制 |
error-logs-max-files |
int |
10 |
生效 | 最多保留多少个错误日志文件 | 0 表示不清理 |
usage-statistics-enabled |
bool |
false |
生效 | 是否启用内存中的使用统计聚合 | 会影响统计和监控能力 |
proxy-url |
string |
"" |
生效 | 全局上游代理地址 | 支持 socks5://、http://、https:// |
force-model-prefix |
bool |
false |
生效 | 是否强制按前缀路由模型 | 多凭据、多租户场景更常用 |
passthrough-headers |
bool |
false |
生效 | 是否把筛选后的上游响应头转发给客户端 | 默认关闭更稳妥 |
request-retry |
int |
3 |
生效 | 请求失败后的重试次数 | 常对 403、408、500、502、503、504 等状态码生效 |
max-retry-credentials |
int |
0 |
生效 | 单次失败最多尝试多少个不同凭据 | 0 表示可能尝试所有可用凭据 |
max-retry-interval |
int |
30 |
生效 | 等待冷却恢复的最大秒数 | 控制失败后的重试节奏 |
disable-cooling |
bool |
false |
生效 | 是否禁用冷却机制 | true 会关闭失败后的 cooldown 调度 |
ws-auth |
bool |
false |
生效 | 是否启用 WebSocket API 鉴权 | 对 /v1/ws 生效 |
enable-gemini-cli-endpoint |
bool |
false |
生效 | 是否启用 Gemini CLI 内部端点 | 默认关闭更安全 |
nonstream-keepalive-interval |
int |
0 |
生效 | 非流式响应 keepalive 间隔（秒） | >0 时会定期发送空行以防止超时 |
TLS 配置 #
当服务需要直接对外提供 HTTPS 时，再启用这里的证书配置。
| 字段 | 类型 | 当前值 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
tls.enable |
bool |
false |
生效 | 是否启用 HTTPS | false 表示当前通过 HTTP 提供服务 |
tls.cert |
string |
"" |
生效 | TLS 证书文件路径 | 仅在 enable: true 时需要配置 |
tls.key |
string |
"" |
生效 | TLS 私钥文件路径 | 仅在 enable: true 时需要配置 |
管理接口配置 remote-management
#
管理接口和内置控制面板的配置。
| 字段 | 类型 | 当前值 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
remote-management.allow-remote |
bool |
false |
生效 | 是否允许远程访问管理接口 | false 表示只允许 localhost 访问 |
remote-management.secret-key |
string |
"" |
生效 | 管理接口密钥 | 留空则禁用 Management API |
remote-management.disable-control-panel |
bool |
false |
生效 | 是否禁用内置管理面板 | true 时不下载也不暴露控制面板 |
remote-management.panel-github-repository |
string |
GitHub 仓库 URL | 生效 | 管理面板来源仓库 | 用于下载或更新管理面板资源 |
性能分析配置 pprof
#
只有在排查性能瓶颈、协程泄漏或内存问题时，通常才会开启。
| 字段 | 类型 | 当前值 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
pprof.enable |
bool |
false |
生效 | 是否启用 pprof 调试服务 | 建议只在排障时临时开启 |
pprof.addr |
string |
"127.0.0.1:8316" |
生效 | pprof 监听地址 | 建议仅绑定 localhost |
配额超限处理 quota-exceeded
#
配额耗尽后的兜底行为。
| 字段 | 类型 | 当前值 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
quota-exceeded.switch-project |
bool |
true |
生效 | 配额超限时是否自动切换项目 | 用于继续兜底请求 |
quota-exceeded.switch-preview-model |
bool |
true |
生效 | 配额超限时是否切换到 preview 模型 | 可以理解为一种降级策略 |
quota-exceeded.antigravity-credits |
bool |
true |
生效 | Antigravity 配额耗尽时是否额外重试一次 | 会尝试 enabledCreditTypes=["GOOGLE_ONE_AI"] |
路由配置 routing
#
多凭据都能处理同一模型时，这里决定走哪个。
| 字段 | 类型 | 当前值 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
routing.strategy |
string |
"round-robin" |
生效 | 多凭据命中时的选择策略 | round-robin 为轮询；fill-first 为优先打满第一个 |
流式与签名相关可选字段 #
流式响应和签名校验，目前配置文件里是注释状态。
| 字段 | 类型 | 示例值 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
streaming.keepalive-seconds |
int |
15 |
注释，未生效 | SSE 流式响应 keepalive 间隔 | <=0 表示禁用 |
streaming.bootstrap-retries |
int |
1 |
注释，未生效 | 首字节发出前允许的安全重试次数 | 主要影响流启动阶段 |
antigravity-signature-cache-enabled |
bool |
true |
注释，未生效 | 是否优先使用并校验缓存签名 | 主要针对 thinking block |
antigravity-signature-bypass-strict |
bool |
false |
注释，未生效 | 绕过模式下是否启用严格签名验证 | 更偏测试或兼容性开关 |
gemini-api-key 配置块字段
#
这是 Gemini 上游凭据的配置模板。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
gemini-api-key[].api-key |
string |
"AIzaSy...01" |
注释，未生效 | Gemini 的真实上游 API Key | 代理调用 Gemini 时使用 |
gemini-api-key[].prefix |
string |
"test" |
注释，未生效 | 模型请求前缀 | 例如 test/gemini-3-pro-preview |
gemini-api-key[].base-url |
string |
官方 URL | 注释，未生效 | Gemini API 基础地址 | 可用于自定义 endpoint |
gemini-api-key[].headers |
map |
X-Custom-Header: ... |
注释，未生效 | 附加请求头 | 发往该上游时固定携带 |
gemini-api-key[].proxy-url |
string |
socks5://... |
注释，未生效 | 单个 key 的专属代理 | 优先级高于顶层 proxy-url |
gemini-api-key[].models[].name |
string |
"gemini-2.5-flash" |
注释，未生效 | 上游真实模型名 | 与厂商侧保持一致 |
gemini-api-key[].models[].alias |
string |
"gemini-flash" |
注释，未生效 | 对客户端暴露的模型别名 | 客户端直接调用 alias 即可 |
gemini-api-key[].excluded-models[] |
list[string] |
"gemini-2.5-pro" 等 |
注释，未生效 | 从该 provider 中排除的模型 | 支持通配符 |
codex-api-key 配置块字段
#
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
codex-api-key[].api-key |
string |
"sk-atSM..." |
注释，未生效 | Codex 上游 API Key | 用于连接 Codex 兼容上游 |
codex-api-key[].prefix |
string |
"test" |
注释，未生效 | 路由前缀 | 用于区分不同凭据 |
codex-api-key[].base-url |
string |
"https://www.example.com" |
注释，未生效 | 自定义 Codex API 地址 | 非默认官方入口时使用 |
codex-api-key[].headers |
map |
自定义请求头 | 注释，未生效 | 上游附加头 | 例如授权头、额外标识 |
codex-api-key[].proxy-url |
string |
socks5://... |
注释，未生效 | 单 key 代理 | 会覆盖全局代理 |
codex-api-key[].models[].name |
string |
"gpt-5-codex" |
注释，未生效 | 上游模型名 | 实际调用的模型 ID |
codex-api-key[].models[].alias |
string |
"codex-latest" |
注释，未生效 | 客户端模型别名 | 便于统一命名 |
codex-api-key[].excluded-models[] |
list[string] |
"gpt-5.1" 等 |
注释，未生效 | 排除的模型 | 支持通配符 |
claude-api-key 配置块字段
#
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
claude-api-key[].api-key |
string |
"sk-atSM..." |
注释，未生效 | Claude 上游 API Key | 可直连官方或自定义上游 |
claude-api-key[].prefix |
string |
"test" |
注释，未生效 | 路由前缀 | 客户端可通过 test/... 指定 |
claude-api-key[].base-url |
string |
"https://www.example.com" |
注释，未生效 | 自定义 Claude endpoint | 非官方入口时使用 |
claude-api-key[].headers |
map |
自定义头 | 注释，未生效 | 附加请求头 | 用于兼容某些网关 |
claude-api-key[].proxy-url |
string |
socks5://... |
注释，未生效 | 单 key 代理 | 覆盖全局代理 |
claude-api-key[].models[].name |
string |
"claude-3-5-sonnet-20241022" |
注释，未生效 | 上游真实模型名 | 真实调用目标 |
claude-api-key[].models[].alias |
string |
"claude-sonnet-latest" |
注释，未生效 | 客户端别名 | 对外统一模型名 |
claude-api-key[].excluded-models[] |
list[string] |
"claude-opus-4-5-20251101" 等 |
注释，未生效 | 排除的模型 | 支持通配符 |
claude-api-key[].cloak.mode |
string |
"auto" |
注释，未生效 | 是否启用请求 cloaking | 常见值为 auto / always / never |
claude-api-key[].cloak.strict-mode |
bool |
false |
注释，未生效 | cloaking 严格模式 | true 时会更激进地替换 system 消息 |
claude-api-key[].cloak.sensitive-words[] |
list[string] |
"API"、"proxy" |
注释，未生效 | 需要做零宽混淆的词 | 用于规避敏感词直出 |
claude-api-key[].cloak.cache-user-id |
bool |
true |
注释，未生效 | 是否复用缓存的 user_id |
否则可能每次都生成新值 |
claude-api-key[].experimental-cch-signing |
bool |
false |
注释，未生效 | 是否启用实验性的 Claude Code 签名 | 一般建议保持关闭 |
claude-header-defaults
#
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
claude-header-defaults.user-agent |
string |
claude-cli/... |
注释，未生效 | 默认 User-Agent |
客户端未传时可补上 |
claude-header-defaults.package-version |
string |
"0.74.0" |
注释，未生效 | 默认包版本 | 用于模拟客户端版本 |
claude-header-defaults.runtime-version |
string |
"v24.3.0" |
注释，未生效 | 默认运行时版本 | 用于模拟运行环境 |
claude-header-defaults.os |
string |
"MacOS" |
注释，未生效 | 默认操作系统 | 可固定设备特征 |
claude-header-defaults.arch |
string |
"arm64" |
注释，未生效 | 默认 CPU 架构 | 常与 UA 配合使用 |
claude-header-defaults.timeout |
string |
"600" |
注释，未生效 | 默认超时头 | 客户端未传时补齐 |
claude-header-defaults.stabilize-device-profile |
bool |
false |
注释，未生效 | 是否固定设备指纹 | 与版本和设备模拟相关 |
codex-header-defaults
#
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
codex-header-defaults.user-agent |
string |
codex_cli_rs/... |
注释，未生效 | Codex OAuth 请求默认 UA | 对 HTTP 和 WS 都可能生效 |
codex-header-defaults.beta-features |
string |
"multi_agent" |
注释，未生效 | WS 请求默认 Beta 功能头 | 仅对 WebSocket 请求有效 |
openai-compatibility 配置块
#
用于接入 OpenAI 兼容格式的第三方上游，例如一些聚合平台或自建兼容网关。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
openai-compatibility[].name |
string |
"openrouter" |
注释，未生效 | Provider 名称 | 会出现在代理内部标识中 |
openai-compatibility[].prefix |
string |
"test" |
注释，未生效 | 路由前缀 | 用于区分 provider |
openai-compatibility[].base-url |
string |
"https://openrouter.ai/api/v1" |
注释，未生效 | OpenAI 兼容上游地址 | 第三方兼容平台常见写法 |
openai-compatibility[].headers |
map |
自定义头 | 注释，未生效 | 上游附加头 | 某些平台会要求特定 header |
openai-compatibility[].api-key-entries[].api-key |
string |
sk-or-v1-... |
注释，未生效 | 上游 API Key | 支持配置多把 key |
openai-compatibility[].api-key-entries[].proxy-url |
string |
socks5://... |
注释，未生效 | 某把 key 的专属代理 | 覆盖全局代理 |
openai-compatibility[].models[].name |
string |
"moonshotai/kimi-k2:free" |
注释，未生效 | 上游真实模型名 | 与平台侧名称保持一致 |
openai-compatibility[].models[].alias |
string |
"kimi-k2" |
注释，未生效 | 客户端别名 | 提供更短、更统一的名字 |
openai-compatibility[].models[].thinking.levels[] |
list[string] |
["low", "medium", "high"] |
注释，未生效 | 可暴露的 thinking 等级 | 适用于支持不同推理强度的模型 |
vertex-api-key 配置块
#
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
vertex-api-key[].api-key |
string |
"vk-123..." |
注释，未生效 | Vertex 上游 API Key | 作为 x-goog-api-key 使用 |
vertex-api-key[].prefix |
string |
"test" |
注释，未生效 | 路由前缀 | 用于多凭据路由 |
vertex-api-key[].base-url |
string |
"https://example.com/api" |
注释，未生效 | Vertex 兼容 endpoint | 不填时回落到 Google Vertex |
vertex-api-key[].proxy-url |
string |
socks5://... |
注释，未生效 | 单 key 代理 | 覆盖全局代理 |
vertex-api-key[].headers |
map |
自定义头 | 注释，未生效 | 上游附加头 | 用于兼容某些网关 |
vertex-api-key[].models[].name |
string |
"gemini-2.5-flash" |
注释，未生效 | 上游真实模型名 | 与 Vertex 侧保持一致 |
vertex-api-key[].models[].alias |
string |
"vertex-flash" |
注释，未生效 | 客户端别名 | 方便统一暴露 |
vertex-api-key[].excluded-models[] |
list[string] |
"imagen-*" 等 |
注释，未生效 | 排除的模型 | 支持通配符 |
ampcode 配置块
#
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
ampcode.upstream-url |
string |
"https://ampcode.com" |
注释，未生效 | Amp 上游地址 | 用于 OAuth 和管理功能入口 |
ampcode.upstream-api-key |
string |
"" |
注释，未生效 | 默认 Amp 上游 API Key | 未单独映射时使用 |
ampcode.upstream-api-keys[].upstream-api-key |
string |
"amp_key_for_team_a" |
注释，未生效 | 某组客户端映射到的 Amp 上游 key | 支持按客户端 key 分流 |
ampcode.upstream-api-keys[].api-keys[] |
list[string] |
"your-api-key-1" 等 |
注释，未生效 | 使用该上游 key 的本地客户端 key 列表 | 用于不同客户端走不同上游账号 |
ampcode.restrict-management-to-localhost |
bool |
false |
注释，未生效 | 是否将 Amp 管理路由限制为本机 | 属于安全增强项 |
ampcode.force-model-mappings |
bool |
false |
注释，未生效 | 是否先做模型映射再校验本地 key | 影响路由处理顺序 |
ampcode.model-mappings[].from |
string |
"claude-opus-4-5-20251101" |
注释，未生效 | Amp 请求的原模型名 | 即请求入口模型 |
ampcode.model-mappings[].to |
string |
"gemini-claude-opus-4-5-thinking" |
注释，未生效 | 代理内部替代模型名 | 用于兜底或兼容映射 |
oauth-model-alias
#
用于给各类 OAuth 渠道的模型增加别名，或者直接重命名暴露给客户端的名称。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
oauth-model-alias.<channel>[].name |
string |
"gemini-2.5-pro" |
注释，未生效 | 原始模型名 | 按 channel 单独配置 |
oauth-model-alias.<channel>[].alias |
string |
"g2.5p" |
注释，未生效 | 客户端可见别名 | 用于统一命名 |
oauth-model-alias.<channel>[].fork |
bool |
true |
注释，未生效 | 是否同时保留原名并新增 alias | false 更像重命名，true 更像复制出一个额外别名 |
支持的 channel 示例：gemini-cli、vertex、aistudio、antigravity、claude、codex、qwen、iflow、kimi。
oauth-excluded-models
#
用于在某个 OAuth 渠道下显式隐藏一部分模型。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
oauth-excluded-models.<channel>[] |
list[string] |
"gemini-2.5-pro"、"*-preview" 等 |
注释，未生效 | 按 channel 排除某些 OAuth 模型 | 支持精确匹配和通配符 |
payload 规则配置
#
这组规则用于在请求进入上游前，对请求体进行补默认值、强制覆盖或字段清洗。
payload.default
#
缺失时才补，不会覆盖用户已传的值。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
payload.default[].models[].name |
string |
"gemini-2.5-pro" |
注释，未生效 | 匹配的模型名 | 支持通配符 |
payload.default[].models[].protocol |
string |
"gemini" |
注释，未生效 | 限定协议 | 可选 openai、gemini、claude、codex、antigravity |
payload.default[].params |
map |
JSON path -> value | 注释，未生效 | 在参数缺失时补默认值 | 不会覆盖用户已有参数 |
payload.default-raw
#
和 payload.default 一样，但填的是原始 JSON，适合嵌套结构。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
payload.default-raw[].models[].name |
string |
"gemini-2.5-pro" |
注释，未生效 | 匹配模型 | 同上 |
payload.default-raw[].models[].protocol |
string |
"gemini" |
注释，未生效 | 限定协议 | 同上 |
payload.default-raw[].params |
map |
JSON path -> raw JSON | 注释，未生效 | 缺失时补原始 JSON 值 | 适合 schema 等复杂结构 |
payload.override
#
无论客户端有没有传值，都会强制覆盖。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
payload.override[].models[].name |
string |
"gpt-*" |
注释，未生效 | 匹配模型 | 支持通配符 |
payload.override[].models[].protocol |
string |
"codex" |
注释，未生效 | 限定协议 | 同上 |
payload.override[].params |
map |
"reasoning.effort": "high" |
注释，未生效 | 强制覆盖写入参数 | 无论用户是否传入都会覆盖 |
payload.override-raw
#
同 payload.override，用于复杂原始 JSON 结构。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
payload.override-raw[].models[].name |
string |
"gpt-*" |
注释，未生效 | 匹配模型 | 支持通配符 |
payload.override-raw[].models[].protocol |
string |
"codex" |
注释，未生效 | 限定协议 | 同上 |
payload.override-raw[].params |
map |
raw JSON | 注释，未生效 | 强制覆盖原始 JSON 参数 | 适合复杂结构 |
payload.filter
#
从请求里删掉不想透传或不兼容的字段。
| 字段 | 类型 | 示例 | 是否生效 | 含义 | 说明 |
|---|---|---|---|---|---|
payload.filter[].models[].name |
string |
"gemini-2.5-pro" |
注释，未生效 | 匹配模型 | 支持通配符 |
payload.filter[].models[].protocol |
string |
"gemini" |
注释，未生效 | 限定协议 | 同上 |
payload.filter[].params[] |
list[string] |
"generationConfig.thinkingConfig.thinkingBudget" |
注释，未生效 | 从请求中移除指定 JSON 路径 | 适合做兼容性清洗 |
结语 #
跑起来最少需要这几类：
- 服务监听：
host、port - 认证与入口鉴权：
auth-dir、api-keys - 上游网络：
proxy-url - 失败恢复：
request-retry、max-retry-credentials、disable-cooling - 多凭据路由：
routing.strategy - 管理能力：
remote-management.*
gemini-api-key、claude-api-key、openai-compatibility、payload.* 这些用到时再翻就行。