Basic Configuration

Configuration File

The server uses a YAML configuration file (config.yaml) located in the project root directory by default. You can specify a different configuration file path using the --config flag:

./cli-proxy-api --config /path/to/your/config.yaml

debug: false gemini-api-key:

Example Configuration File

# Server port
port: 8317

# Management API settings
remote-management:
  # Whether to allow remote (non-localhost) management access.
  # When false, only localhost can access management endpoints (a key is still required).
  allow-remote: false

  # Management key. If a plaintext value is provided here, it will be hashed on startup.
  # All management requests (even from localhost) require this key.
  # Leave empty to disable the Management API entirely (404 for all /v0/management routes).
  secret-key: ""

  # Disable the bundled management control panel asset download and HTTP route when true.
  disable-control-panel: false

# Authentication directory (supports ~ for home directory). If you use Windows, please set the directory like this: `C:/cli-proxy-api/`
auth-dir: "~/.cli-proxy-api"

# API keys for authentication
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"

# Enable debug logging


# When true, write application logs to rotating files instead of stdout
logging-to-file: false

# When false, disable in-memory usage statistics aggregation
usage-statistics-enabled: false

# Proxy URL. Supports socks5/http/https protocols. Example: socks5://user:[email protected]:1080/
proxy-url: ""

# Number of times to retry a request. Retries will occur if the HTTP response code is 403, 408, 500, 502, 503, or 504.
request-retry: 3

# Quota exceeded behavior
quota-exceeded:
  switch-project: true # Whether to automatically switch to another project when a quota is exceeded
  switch-preview-model: true # Whether to automatically switch to a preview model when a quota is exceeded

# When true, enable authentication for the WebSocket API (/v1/ws).
ws-auth: false

# Gemini API keys (preferred)
gemini-api-key:
  - api-key: "AIzaSy...01"
    base-url: "https://generativelanguage.googleapis.com"
    headers:
      X-Custom-Header: "custom-value"
    proxy-url: "socks5://proxy.example.com:1080"
  - api-key: "AIzaSy...02"

# Codex API keys
codex-api-key:
  - api-key: "sk-atSM..."
    base-url: "https://www.example.com" # use the custom codex API endpoint
    headers:
      X-Custom-Header: "custom-value"
    proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override

# Claude API keys
claude-api-key:
  - api-key: "sk-atSM..." # use the official claude API key, no need to set the base url
  - api-key: "sk-atSM..."
    base-url: "https://www.example.com" # use the custom claude API endpoint
    headers:
      X-Custom-Header: "custom-value"
    proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override
    models:
      - name: "claude-3-5-sonnet-20241022" # upstream model name
#        alias: "claude-sonnet-latest" # client alias mapped to the upstream model

# OpenAI compatibility providers
openai-compatibility:
  - name: "openrouter" # The name of the provider; it will be used in the user agent and other places.
    base-url: "https://openrouter.ai/api/v1" # The base URL of the provider.
    headers:
      X-Custom-Header: "custom-value"
    # Persisted format with per-key proxy support:
    api-key-entries:
      - api-key: "sk-or-v1-...b780"
        proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override
      - api-key: "sk-or-v1-...b781" # without proxy-url
    # Compatibility: legacy api-keys are migrated into api-key-entries on load and removed on save.
    models: # The models supported by the provider.
      - name: "moonshotai/kimi-k2:free" # The actual model name.
        alias: "kimi-k2" # The alias used in the API.

payload: # Optional payload configuration
  default: # Default rules only set parameters when they are missing in the payload.
    - models:
        - name: "gemini-2.5-pro" # Supports wildcards (e.g., "gemini-*")
          protocol: "gemini" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex
      params: # JSON path (gjson/sjson syntax) -> value
        "generationConfig.thinkingConfig.thinkingBudget": 32768
  override: # Override rules always set parameters, overwriting any existing values.
    - models:
        - name: "gpt-*" # Supports wildcards (e.g., "gpt-*")
          protocol: "codex" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex
      params: # JSON path (gjson/sjson syntax) -> value
        "reasoning.effort": "high"