清风微凉 Notes

Search

SearchSearch

08-config-reference

May 26, 2026, 5 min read

08. config.yaml 配置参考

CPA 的所有行为都在 /CLIProxyAPI/config.yaml（容器内路径）配置。这里只挑出真正常用 + 有坑的字段，详细字段以 config.example.yaml 为准。

顶层字段

host: ""                  # 监听地址；"" = 全部接口；"127.0.0.1" = 仅本机
port: 8317                # API 端口
 
tls:
  enable: false           # 启用就需要给 cert/key
  cert: ""
  key: ""
 
auth-dir: "~/.cli-proxy-api"   # OAuth 凭据存放目录（容器内 ~ = /root）
 
api-keys:
  - "sk-自己定一个长一点的"   # 客户端访问 CPA 用这个 key（Authorization: Bearer ...）
 
debug: false              # 详细日志
proxy-url: ""             # 上游代理；http/https/socks5
                          # 例：http://172.18.0.1:7890
                          # per-key 还能写 "direct" / "none" 强制直连
 
logging-to-file: false    # true = 写文件而不是 stdout
logs-max-total-size-mb: 0 # 日志总大小上限

管理面板

remote-management:
  allow-remote: false                # 是否允许非 localhost 访问管理 API
  secret-key: ""                     # 明文密码（启动时自动 bcrypt）
  disable-control-panel: false       # true 则 /management.html 直接 abort
  panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"
  # disable-auto-update-panel: false # true 则不自动更新面板

大坑：默认会从 GitHub Releases 拉面板，境内出口/共享代理 IP 容易遇到 403 rate limit 或 EOF。处理方法见 06-management-panel.md §3。

路由策略

routing:
  strategy: "round-robin"         # round-robin / fill-first
  session-affinity: false         # 同一 session 绑定到同一上游（避免对话上下文跳变）
  session-affinity-ttl: "1h"

配额

quota-exceeded:
  switch-project: true            # 配额满了换个 GCP project（Vertex/Gemini）
  switch-preview-model: true      # 自动降到 preview 模型续命
  antigravity-credits: true       # Claude 配额耗尽时用 Antigravity 兜底

重试

request-retry: 3                  # 单凭据重试次数（403/408/5xx）
max-retry-credentials: 0          # 多凭据切换上限；0 = 全部都试
max-retry-interval: 30            # 等待冷却凭据的最大秒数
disable-cooling: false            # 关掉冷却调度

OAuth 凭据（自动加载，一般不手写）

OAuth 登录写到 auth-dir 下的 *.json 文件，CPA file watcher 自动识别。手动加一份的场景很少。

API Key 类凭据（手写）

适合直接拿到了上游 API key 的场景（不走 OAuth）。

Gemini API Key（AI Studio）

gemini-api-key:
  - api-key: "AIzaSy..."
    prefix: "test"                          # 可选：要求客户端用 test/gemini-... 调用
    base-url: "https://generativelanguage.googleapis.com"
    proxy-url: "socks5://proxy.example.com:1080"  # 可选：per-key 代理
    models:
      - name: "gemini-2.5-flash"
        alias: "gemini-flash"
    excluded-models:
      - "gemini-2.5-pro"
      - "*-preview"

Codex API Key

codex-api-key:
  - api-key: "sk-..."
    base-url: "https://api.openai.com/v1"
    models:
      - name: "gpt-5-codex"
        alias: "codex-latest"

Claude API Key

claude-api-key:
  - api-key: "sk-ant-..."
    models:
      - name: "claude-3-5-sonnet-20241022"
        alias: "claude-sonnet-latest"
    cloak:                # 让请求看起来像 Claude Code（绕过部分检测）
      mode: "auto"
      strict-mode: false

OpenAI 兼容（OpenRouter / DeepSeek / 自建 vLLM 等）

openai-compatibility:
  - name: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: "sk-or-v1-..."
    models:
      - name: "moonshotai/kimi-k2:free"
        alias: "kimi-k2"

Vertex API Key

vertex-api-key:
  - api-key: "vk-..."
    base-url: "https://example.com/api"  # 可选；不填默认走 Google Vertex
    models:
      - name: "gemini-2.5-pro"
        alias: "vertex-pro"

模型别名（OAuth 通道）

API key 类已经在自己条目里写 models:，OAuth 通道（Gemini CLI / Codex / Claude Code）则用全局：

oauth-model-alias:
  gemini-cli:
    - name: "gemini-2.5-pro"
      alias: "g2.5p"
      fork: true              # true = 同时保留原名
  codex:
    - name: "gpt-5"
      alias: "g5"
  claude:
    - name: "claude-sonnet-4-5-20250929"
      alias: "cs4.5"

模型排除

oauth-excluded-models:
  gemini-cli:
    - "gemini-2.5-*"
    - "*-preview"
  claude:
    - "claude-3-5-haiku-20241022"

Payload 改写（高级）

让所有 gemini-2.5-pro 请求自动加 thinkingBudget：

payload:
  default:
    - models:
        - name: "gemini-2.5-pro"
          protocol: "gemini"
      params:
        "generationConfig.thinkingConfig.thinkingBudget": 32768
  override:
    - models:
        - name: "gpt-*"
          protocol: "codex"
      params:
        "reasoning.effort": "high"

四种规则：

  • default：缺失才设
  • default-raw：缺失才设，值是裸 JSON
  • override：总是覆盖
  • override-raw：总是覆盖，值是裸 JSON
  • filter：删除指定字段

JSON path 是 sjson 语法。

Amp 集成

ampcode:
  upstream-url: "https://ampcode.com"
  upstream-api-key: ""
  model-mappings:
    - from: "claude-opus-4-5-20251101"
      to: "gemini-claude-opus-4-5-thinking"

客户端伪装（重要）

Claude Code 的部分上游会校验 User-Agent / package version：

claude-header-defaults:
  user-agent: "claude-cli/2.1.44 (external, sdk-cli)"
  package-version: "0.74.0"
  runtime-version: "v24.3.0"
  os: "MacOS"
  arch: "arm64"
  stabilize-device-profile: false

Codex 类似：

codex-header-defaults:
  user-agent: "codex_cli_rs/0.114.0 (Mac OS 14.2.0; x86_64) vscode/1.111.0"
  beta-features: "multi_agent"

这些值需要随官方客户端版本走，太旧会被上游拒绝。CPA 自带兜底逻辑，但偶尔需要手动更新。

热更新

config.yaml 改了不需要 restart 容器：CPA 启动了 file watcher，会自动重新加载（OAuth 凭据增删也是）。但如果改的是端口、TLS 等启动期参数，需要 restart。

下一步：09-troubleshooting.md 常见问题。

Graph View

Backlinks