User Guide

完整配置示例

ProxyCast 完整 YAML 配置示例

完整配置示例

本文档提供 ProxyCast 的完整 YAML 配置示例,包含所有新增功能。

基础配置

# 服务器配置
server:
  host: "127.0.0.1"
  port: 8999
  api_key: "proxy_cast"
  
  # TLS/HTTPS 配置
  tls:
    enable: false
    cert_path: "/path/to/cert.pem"
    key_path: "/path/to/key.pem"

# 全局代理 URL(支持 socks5/http/https)
proxy_url: "socks5://127.0.0.1:1080"

# 认证目录(存储 OAuth Token 文件)
auth_dir: "~/.proxycast/auth"

远程管理配置

# 远程管理 API 配置
remote_management:
  # 是否允许远程访问(非 localhost)
  allow_remote: false
  # 管理 API 密钥(为空时禁用管理 API)
  secret_key: "your-secret-key"
  # 是否禁用控制面板
  disable_control_panel: false

配额超限配置

# 配额超限自动切换策略
quota_exceeded:
  # 是否自动切换到下一个凭证
  switch_project: true
  # 是否尝试使用预览模型
  switch_preview_model: true
  # 冷却时间(秒)
  cooldown_seconds: 300

Amp CLI 集成配置

# Amp CLI 配置
ampcode:
  # 上游 URL
  upstream_url: "https://ampcode.com"
  # 是否限制管理端点只能从 localhost 访问
  restrict_management_to_localhost: false
  # 模型映射列表
  model_mappings:
    - from: "claude-opus-4.5"
      to: "claude-sonnet-4"
    - from: "gpt-5"
      to: "gemini-2.5-pro"
    - from: "claude-3-opus-20240229"
      to: "claude-3-5-sonnet-20241022"

凭证池配置

OAuth Provider

credential_pool:
  # Kiro OAuth 凭证
  kiro:
    - id: "kiro-main"
      token_file: "kiro/main-token.json"
      disabled: false
      proxy_url: "socks5://proxy1:1080"  # 可选:单独代理
    - id: "kiro-backup"
      token_file: "kiro/backup-token.json"
      disabled: false

  # Gemini OAuth 凭证
  gemini:
    - id: "gemini-main"
      token_file: "gemini/oauth_creds.json"
      disabled: false

  # Qwen OAuth 凭证
  qwen:
    - id: "qwen-main"
      token_file: "qwen/oauth_creds.json"
      disabled: false

  # Codex OAuth 凭证
  codex:
    - id: "codex-main"
      token_file: "codex/oauth.json"
      proxy_url: "http://proxy2:8080"

iFlow Provider

credential_pool:
  # iFlow 凭证(支持 OAuth 和 Cookie)
  iflow:
    # OAuth 模式
    - id: "iflow-oauth"
      token_file: "iflow/oauth.json"
      auth_type: "oauth"
      disabled: false
    # Cookie 模式
    - id: "iflow-cookie"
      auth_type: "cookie"
      cookies: "session_id=abc123; auth_token=xyz789"
      disabled: false

API Key Provider

credential_pool:
  # OpenAI API Key
  openai:
    - id: "openai-main"
      api_key: "sk-xxx..."
      base_url: "https://api.openai.com/v1"
      disabled: false
      proxy_url: "http://proxy:8080"

  # Claude API Key
  claude:
    - id: "claude-main"
      api_key: "sk-ant-xxx..."
      base_url: "https://api.anthropic.com"
      disabled: false

Gemini API Key 多账号

credential_pool:
  # Gemini API Key 多账号负载均衡
  gemini_api_keys:
    - id: "gemini-key-1"
      api_key: "AIzaSy...01"
      base_url: "https://generativelanguage.googleapis.com"
      proxy_url: "socks5://proxy1:1080"
      excluded_models:
        - "gemini-2.5-pro"      # 排除特定模型
        - "gemini-2.5-*"        # 通配符前缀匹配
        - "*-preview"           # 通配符后缀匹配
      disabled: false
    - id: "gemini-key-2"
      api_key: "AIzaSy...02"
      disabled: false

Vertex AI Provider

credential_pool:
  # Vertex AI 凭证
  vertex_api_keys:
    - id: "vertex-main"
      api_key: "vk-123..."
      base_url: "https://example.com/api"
      proxy_url: "socks5://proxy:1080"
      # 模型别名映射
      models:
        - name: "gemini-2.0-flash"
          alias: "vertex-flash"
        - name: "gemini-1.5-pro"
          alias: "vertex-pro"
      disabled: false

路由配置

# 路由配置
routing:
  # 默认 Provider
  default_provider: "kiro"
  
  # 路由规则
  rules:
    - pattern: "claude-*"
      provider: "kiro"
      priority: 1
    - pattern: "gemini-*"
      provider: "gemini"
      priority: 2
    - pattern: "gpt-*"
      provider: "openai"
      priority: 3
  
  # 模型别名
  model_aliases:
    "claude-latest": "claude-sonnet-4-5-20250514"
    "gemini-latest": "gemini-2.5-pro"
  
  # 排除列表
  exclusions:
    kiro:
      - "claude-3-opus-*"
    gemini:
      - "gemini-1.0-*"

重试配置

# 重试配置
retry:
  max_retries: 3
  base_delay_ms: 1000
  max_delay_ms: 30000
  auto_switch_provider: true

日志配置

# 日志配置
logging:
  enabled: true
  level: "info"
  retention_days: 7
  include_request_body: false

参数注入配置

# 参数注入配置
injection:
  enabled: true
  rules:
    - id: "thinking-budget"
      pattern: "gemini-2.5-*"
      parameters:
        generationConfig:
          thinkingConfig:
            thinkingBudget: 32768
      mode: "default"  # default: 仅在参数缺失时设置
      priority: 1
      enabled: true
    - id: "reasoning-effort"
      pattern: "gpt-*"
      parameters:
        reasoning:
          effort: "high"
      mode: "override"  # override: 总是覆盖
      priority: 2
      enabled: true

完整配置示例

以下是一个完整的配置文件示例:

# ProxyCast 完整配置示例
server:
  host: "127.0.0.1"
  port: 8999
  api_key: "proxy_cast"
  tls:
    enable: false
    cert_path: ""
    key_path: ""

proxy_url: ""
auth_dir: "~/.proxycast/auth"

remote_management:
  allow_remote: false
  secret_key: ""
  disable_control_panel: false

quota_exceeded:
  switch_project: true
  switch_preview_model: true
  cooldown_seconds: 300

ampcode:
  upstream_url: ""
  restrict_management_to_localhost: false
  model_mappings: []

credential_pool:
  kiro:
    - id: "kiro-main"
      token_file: "kiro/main-token.json"
      disabled: false
  gemini: []
  qwen: []
  openai: []
  claude: []
  gemini_api_keys: []
  vertex_api_keys: []
  codex: []
  iflow: []

routing:
  default_provider: "kiro"
  rules: []
  model_aliases: {}
  exclusions: {}

retry:
  max_retries: 3
  base_delay_ms: 1000
  max_delay_ms: 30000
  auto_switch_provider: true

logging:
  enabled: true
  level: "info"
  retention_days: 7
  include_request_body: false

injection:
  enabled: false
  rules: []