config.example.yaml

# Configuration template using the v8 layout.
# Copy this file to config.yaml and replace the client keys and any enabled examples.
# Optional upstream credentials and request rules remain commented until configured.
# Existing legacy configuration files and /v0/management requests remain supported.
# When both spellings of a field are present, the v8 value wins (including false,
# 0, and empty collections), and the corresponding legacy field is removed on load/save.
# Legacy-only fields still work. GET requests and config-version: 8 alone do not
# migrate a legacy file; a successful configuration write through /v8/management does.
# The compatibility notes at the end show old spellings for existing deployments.
config-version: 8

# Optional model catalog sources: http(s) URLs or absolute local file paths.
# Each explicit source overrides --local-model; otherwise --local-model uses
# embedded catalogs, and normal mode uses the official remote sources.
# Failed refreshes retain the last valid catalog; custom sources never fall back
# to official URLs. Files and URLs are refreshed every 3 hours and on source changes.
# Home mode never loads the general catalog, even when explicitly configured.
models:
  catalog: ""
  codex-catalog: ""
  devin-catalog: ""

# Listener, TLS, network discovery, and server operation.
server:
  # Server host/interface to bind to. Default is empty ("") to bind all interfaces (IPv4 + IPv6).
  # Use "127.0.0.1" or "localhost" to restrict access to local machine only.
  host: ""

  # Server port
  port: 8317

  # Maximum allowed size (in bytes) for incoming HTTP request bodies.
  # Requests exceeding this limit are rejected with HTTP 413 Payload Too Large.
  # Default is 0 (disabled / no limit).
  max-request-body-bytes: 0

  # Global token for GitHub requests (for example, release and asset downloads).
  # A non-empty config token takes precedence over the GITHUB_TOKEN environment variable.
  # Leave empty to use GITHUB_TOKEN, or unauthenticated requests if neither is set.
  github-token: ""

  # IP addresses or CIDRs of proxies allowed to supply forwarded client IP headers.
  # An empty list (the default) does not trust forwarded headers. Restart after changing this setting.
  trusted-proxies: []
  # Example:
  # trusted-proxies:
  #   - 127.0.0.1
  #   - 192.0.2.0/24

  # TLS settings for HTTPS. When enabled, the server listens with the provided certificate and key.
  tls:
    enable: false
    cert: ""
    key: ""

  # When true, disable high-overhead request logging and HTTP middleware features to reduce per-request memory usage under high concurrency.
  commercial-mode: false

  # Enable local network mDNS / DNS-SD service discovery (RFC 6762 / RFC 6763).
  # When enabled, broadcasts _ai-gateway._tcp with API protocol subtypes on the local network.
  # NOTE for Docker users: Link-local multicast (224.0.0.251) cannot cross default NAT bridge networks.
  # To broadcast across the physical LAN, run the container with host networking (--net=host / network_mode: host).
  discovery:
    enabled: false
    # service-name: ""                  # Optional name prefix. Advertised as CPA-<ShortID> or <name>-<ShortID> (e.g. office-8F3B)
    # service-type: "_ai-gateway._tcp"  # Service type (RFC 6335 compliant)
    # subtypes:                         # DNS-SD API protocol subtypes to advertise
    #   - "_chat-completions"
    #   - "_responses"
    #   - "_messages"
    #   - "_generate-content"
    #   - "_interactions"
    # interfaces:
    #   include: []                     # White-listed interfaces (empty: auto-detect physical interfaces)
    #   exclude: []                     # Additional interface patterns to exclude
    # auth-required: true               # Advertise that credentials are required

    # advertise-management: false      # Advertise management availability

# Management API settings
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 /v0/management and /v8/management routes).
  secret-key: ""

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

  # Disable automatic periodic background updates of the management panel from GitHub (default: false).
  # When enabled, the panel is only downloaded on first access if missing, and never auto-updated afterward.
  # disable-auto-update-panel: false

  # Base URL of remote management API when using TUI client mode (cliproxyapi --tui).
  # Defaults to http://127.0.0.1:<port> if not set. Can also be set via --management-base-url.
  # base-url: "https://proxy.example.com"

  # GitHub repository for the management control panel. Accepts a repository URL or releases API URL.
  panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"

# Client authentication for the proxy API. These are not upstream provider keys.
access:
  # API keys for authentication
  api-keys:
    - "your-api-key-1"
    - "your-api-key-2"
    - "your-api-key-3"

# Optional credential concurrency and observation contracts.

# credentials:
#
#   # Credential concurrency is configured by Home in Home mode. The synthesized Home config is
#   # authoritative and local values, including the values below, are ignored. Do not use local
#   # configuration to override a Home concurrency policy.
#
#   concurrency:
#     # Revisions are system-owned metadata, not ordinary editable settings.
#     lifecycle-config-revision: 1
#     observation-barrier-revision: 0
#     cpa-heartbeat-timeout: "3s"
#     cpa-cancel-bound: "5s"
#     reclaim-grace: "5s"
#     cleanup-interval: "5s"
#     release-flush-interval: 250ms
#     release-max-backoff: 2s
#     busy-retry-min: 250ms
#     busy-retry-max: 1s
#     max-limit: 1000000
#
#   # Credential in-flight observation snapshot contract.
#
#   in-flight:
#     snapshot-interval: 2s
#     stale-after: 10s
#     max-part-bytes: 262144
#     max-part-count: 64
#     max-revision-bytes: 16777216
#     max-aggregate-groups: 100000
#     max-details: 10000
#     max-string-bytes: 256
#     staging-retention: 1m

# Routing strategy for selecting credentials when multiple match.
routing:
  strategy: "round-robin" # round-robin (default), weighted-round-robin, fill-first
  # weighted-round-robin uses each credential's integer weight (default 1, maximum 1,000,000).
  # Non-positive weights exclude the credential while this strategy is active.
  # For OAuth/file credentials, add a top-level numeric "weight" field to the auth JSON.
  # Enable universal session-sticky routing for all clients.
  # Explicit Claude Code, Codex, OpenCode, and pi session headers are preferred,
  # followed by prompt_cache_key, Responses conversation IDs, legacy body IDs,
  # execution or derived session identity, and the existing first-message hash fallback.
  # Automatic failover is always enabled when bound auth becomes unavailable.
  # An established binding outranks credential priority: once a session is bound, that
  # credential is kept even if a higher-priority credential recovers. Credential priority
  # still decides cold bindings, requests without a session, and post-failover rebinding.
  session-affinity: false # default: false
  # How long session-to-auth bindings are retained. Default: 1h
  session-affinity-ttl: "1h"
  # When true (default), subagents (child sessions with parent references) inherit and bind
  # to the parent's upstream credential across all providers (Claude, Codex, Antigravity, Gemini),
  # maximizing Prompt/KV Cache reuse and minimizing TTFT.
  # When false, subagents are distributed across the credential pool via the fallback selector
  # for maximum parallel concurrency.
  # Ignored when routing.session-affinity is false.
  session-affinity-subagents: true
  # Controls which credential failures rebind an established session to the failover credential:
  #   - "any" (default): any credential-attributed failure unbinds and rebinds on failover.
  #   - "quota": transient errors (408, 5xx, empty stream, buffer limit) fail over for that
  #     request only while keeping the session bound to its original credential; quota and auth
  #     errors (429, 401/402/403, 404/model support, invalid_grant) rebind as normal.
  # Ignored when routing.session-affinity is false.
  session-affinity-rebind-on: "any"

  # When true, unprefixed model requests only use credentials without a prefix (except when prefix == model name).
  force-model-prefix: false

  retry:
    # Number of additional credential retry rounds after the first round exhausts
    # its eligible credentials. Round 0 is the initial round; round r only admits
    # credentials whose effective request-retry is at least r. Explicit non-negative
    # credential/provider overrides take precedence; omitted or negative overrides
    # inherit this global value, and explicit 0 only admits round 0. New CPA nodes
    # send retry_round=0 for the initial round and increment it for additional rounds;
    # legacy dispatch methods omit the field and keep old semantics.
    # Additional rounds apply to HTTP 403, 408, 429, 500, 502, 503, and 504 failures.
    # Individual credential/provider overrides take precedence; 0 disables additional
    # rounds, while an omitted or negative override inherits this global setting.
    request-retry: 3

    # Maximum number of different credentials to try in each credential retry round
    # after per-credential round filtering. Set to 0 to try all available
    # credentials. Credentials skipped by this cap still age with the global round,
    # so the cap does not guarantee a fixed number of actual retries per credential.
    max-retry-credentials: 0

    # Maximum cooldown wait in seconds between retry rounds.
    # Set to 0 or below to never wait for credential cooldown.
    # Retry rounds that need no wait remain controlled by request-retry.
    max-retry-interval: 30

  cooldown:
    # When true, disable auth/model cooldown scheduling globally (prevents blackout windows after failure states).
    # A credential/provider disable-cooling value, when present, overrides this global value.
    disable-cooling: false

    # When true, persist per-auth cooldown status as .cds files next to auth files.
    # Default is false; when false, cooldown status is kept in memory only.
    save-cooldown-status: false

    # Cooldown duration in seconds for transient upstream errors (408/500/502/503/504/520-526).
    # Set to 0 to keep the legacy 60-second cooldown; set to -1 to disable transient error cooldowns.
    transient-error-cooldown-seconds: 0

# Shared request/response behavior.
requests:
  # Proxy URL. Supports socks5/http/https protocols. Example: socks5://user:pass@192.168.1.1:1080/
  # Per-entry proxy-url also supports "direct" or "none" to bypass both the global proxy-url and environment proxies explicitly.
  proxy-url: ""

  # Maximum time, in seconds, for upstream TLS handshakes made by the shared built-in
  # uTLS client. It applies to both the Claude Code Anthropic transport and the Chrome
  # ChatGPT/Codex transport; the standard fallback transport is unaffected. The timer
  # starts after TCP or proxy connection establishment returns; it does not bound dialing
  # or proxy CONNECT. When the upstream path accepts the connection but never answers the
  # TLS ClientHello, the request would otherwise wait indefinitely and request-retry could
  # never engage. The bound applies only during the TLS handshake and is lifted once it
  # succeeds, so inference and long-running streams are never time-limited.
  # Set to 0 to disable (default).
  tls-handshake-timeout-seconds: 0

  # When true, forward filtered upstream response headers to downstream clients.
  # Default is false (disabled).
  passthrough-headers: false

  # When > 0, emit blank lines every N seconds for non-streaming responses to prevent idle timeouts.
  nonstream-keepalive-interval: 0

  # Streaming behavior (SSE keep-alives + safe bootstrap retries).
  # streaming:
  #   keepalive-seconds: 15         # Default: 0 (disabled). <= 0 disables keep-alives.
  #   bootstrap-retries: 1          # Default: 0 (disabled). Retries before first byte is sent.
  #   send-keepalive-before-ft: false # Default: false. When true and keepalive-seconds > 0, send SSE heartbeats before the first token.

  # Optional payload configuration
  # payload:
  #   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, antigravity
  #           from-protocol: "responses" # restricts the rule to the source protocol, options: openai, responses, gemini, claude
  #           headers: # all configured request headers must match; values support "*" wildcards
  #             X-Client-Tier: "tenant-*-region-*"
  #           match: # all payload JSON paths must equal the configured values
  #             - "metadata.client": "codex"
  #           not-match: # payload JSON paths must not equal the configured values
  #             - "metadata.mode": "dev"
  #           exist: # all payload JSON paths must exist and not be null
  #             - "tools.#(type==\"web_search\").type"
  #           not-exist: # all payload JSON paths must be missing or null
  #             - "metadata.disable_payload"
  #       params: # JSON path (gjson/sjson syntax) -> value
  #         "generationConfig.thinkingConfig.thinkingBudget": 32768
  #   default-raw: # Default raw rules set parameters using raw JSON when missing (must be valid JSON).
  #     - 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, antigravity
  #       params: # JSON path (gjson/sjson syntax) -> raw JSON value (strings are used as-is, must be valid JSON)
  #         "generationConfig.responseJsonSchema": "{\"type\":\"object\",\"properties\":{\"answer\":{\"type\":\"string\"}}}"
  #   override: # Override rules always set parameters, overwriting any existing values.
  #     - models:
  #         - name: "gpt-5.4-fast"
  #           protocol: "codex"
  #         - name: "gpt-5.5-fast"
  #           protocol: "codex"
  #       params:
  #         service_tier: priority
  #     - models:
  #         - name: "gpt-*" # Supports wildcards (e.g., "gpt-*")
  #           protocol: "codex" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex, antigravity
  #       params: # JSON path (gjson/sjson syntax) -> value
  #         "reasoning.effort": "high"
  #     - models:
  #         - name: "claude-fable-5-1"
  #           protocol: "claude"
  #       params:
  #         max_tokens: 128000 # override the final Claude Messages output budget after protocol translation
  #   override-raw: # Override raw rules always set parameters using raw JSON (must be valid JSON).
  #     - models:
  #         - name: "gpt-*" # Supports wildcards (e.g., "gpt-*")
  #           protocol: "codex" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex, antigravity
  #       params: # JSON path (gjson/sjson syntax) -> raw JSON value (strings are used as-is, must be valid JSON)
  #         "response_format": "{\"type\":\"json_schema\",\"json_schema\":{\"name\":\"answer\",\"schema\":{\"type\":\"object\"}}}"
  #   filter: # Filter rules remove specified parameters from 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, antigravity
  #       params: # JSON paths (gjson/sjson syntax) to remove from the payload
  #         - "generationConfig.thinkingConfig.thinkingBudget"
  #         - "generationConfig.responseJsonSchema"
  #     - models:
  #         - name: "gpt-*" # Supports wildcards (e.g., "gpt-*")
  #           protocol: "codex"
  #       params:
  #         # Flat tools array (standard OpenAI format or Codex CLI < 0.154):
  #         - 'tools.#(name=="apply_patch")'
  #         # Nested additional_tools structure in input[] (Codex CLI >= 0.154 "Responses Lite"):
  #         - 'input.#(type=="additional_tools")#.tools.#(name=="functions")#.tools.#(name=="apply_patch")#'

# Client-facing compatibility settings apply to both OAuth and API-key routes.
client:
  codex:
    # When false (default), only models that natively declare freeform apply_patch advertise it.
    # When true, non-template and bridged models supported by every routing executor also advertise "freeform".
    enable-apply-patch: false
    # When true, optimize Codex Desktop, codex-tui, and codex_cli_rs requests for multi-agent v2.
    # This refreshes Codex spawn_agent model details, removes message parameter encryption,
    # normalizes encrypted agent_message content for Codex, and converts agent_message input
    # into standard user messages for non-Codex upstream protocols.
    # Default false. Applies to both OAuth and API-key credentials across providers.
    # Legacy provider paths migrate here; this path wins conflicts, including explicit false.
    optimize-multi-agent-v2: false
    # Cache upstream web search results per session so replayed Codex web_search_call items
    # that omit results still retain search results in later turns.
    web-search-result-cache:
      enabled: false
      ttl: "24h"
      limit: 1024

# Shared upstream behavior applies to OAuth and API-key credentials.
upstream:
  codex:
    # Experimental full-duplex Codex Responses WebSocket steering (default: false).
    # Keeps one upstream account/model per socket; accepted input is never replayed.
    response-steering: false
    # Disable forcing the official Codex User-Agent and Originator headers on HTTP/SSE and WebSocket requests.
    disable-codex-cloaking: false
    # Hold back the frames that carry nothing the client has seen - the handshake (response.created,
    # response.in_progress, the websocket metadata frames), keepalive heartbeats, and the *.added
    # announcements of an item or part that is still empty - until the upstream emits its first
    # generated event. Anything else, including a server-side tool item such as web_search_call and
    # any frame not on that list, releases the stream immediately. On the SSE transport the lines that
    # are not `data:` frames - comments, `event:` lines, blank separators - are held alongside them.
    # The hold is bounded by a frame budget and a 1 MiB byte budget, not by wall-clock time: an
    # upstream that trickles frames holds the response headers for as long as the client will wait.
    # Why: the upstream smuggles `server_is_overloaded` rejections *inside* an HTTP 200 stream,
    # right after those handshake events, instead of returning 503 on the wire. Buffering them
    # keeps the downstream response headers uncommitted long enough to transparently retry on
    # another credential. Only overload/rate-limit rejections trigger failover; every other terminal
    # failure is still delivered in-stream exactly as before. One pre-existing behaviour is worth
    # knowing, because this option makes the window it lives in much longer: if the stream ends while
    # the bootstrap is still holding, the attempt ends instead of the error reaching the client, and
    # whether another credential is then tried depends on how it ended. A clean end with no terminal
    # event is request-scoped on SSE, so nothing else is tried; a websocket close, or a transport error
    # such as a dropped connection on either transport, is not, so the request may be retried on
    # another credential. None of that is new, but before this option the hold ended at the first
    # keepalive, so it was rare; now it can span the whole reasoning phase.
    # Trade-off: response headers are delayed until generation starts. Because heartbeats are held
    # too, the delay now ends at the first generated token rather than at the first heartbeat. The
    # budget bounds how much is held, not how long: 48 SSE lines, which measures out as 15 heartbeats
    # of the three-line event:/data:/blank shape, 23 of a two-line ": keepalive" comment followed by
    # its blank separator, or 47 of a bare ": keepalive" with no separator - one short of the obvious
    # division, because the rejection frame's own event: line comes out of the same budget before its
    # data: line is parsed. An upstream that sends the rejection as a bare data: line with no event:
    # line gets the round number instead. At a 10s upstream heartbeat that is 150s, 230s or 470s of
    # uncommitted response headers depending on the framing the upstream picks, all of it past nginx's
    # 60s default proxy_read_timeout, so raise the timeouts in front of the proxy before enabling this.
    # Those seconds bound what the buffer holds, not when the response headers are committed. Headers
    # are committed on the first chunk the downstream translator actually produces, so for a format
    # that renders the handshake as nothing - Chat Completions and Gemini do - they stay uncommitted
    # past the budget, until the first generated token. That is not specific to the budget: any frame
    # that releases the buffer has always behaved this way.
    # The websocket transport spends the same 48 differently - one per message read, whether the loop
    # holds it or skips it, with no framing to divide by - so there it is 48 heartbeats, about 480s.
    # Two cases no budget covers: a websocket peer that sends only ping frames, which the library
    # answers inside the read call, leaving only the 5 minute websocket read deadline; and an upstream
    # that stops mid-line on SSE, where the scanner never returns and only the request context ends the
    # wait. Neither is made worse by this option - with it off the same stalled line stalls the
    # conductor instead, which waits on the same context - but a client-side request timeout, not
    # proxy_read_timeout, is what bounds them.
    # Default: false
    stream-bootstrap-buffering: false
    # Optional maximum duration to hold back uncommitted response headers during bootstrap buffering.
    # When set (e.g. "20s"), if the time ceiling is reached before the first generated token,
    # the stream is released to the client and further in-stream overloads are delivered rather
    # than failed over. This bounds how long trickled heartbeats or early empty frames can delay
    # response headers before streaming begins.
    # Recommendation: If your CPA is deployed behind a reverse proxy with a strict read timeout
    # (e.g. Nginx default proxy_read_timeout 60s or Cloudflare 100s timeout), setting this to "20s"
    # is strongly recommended to guarantee headers commit well before proxy timeouts while retaining
    # a comfortable 20s window to fail over early scheduling overloads.
    # Note: The timeout check is evaluated as upstream frames arrive; it never aborts the upstream
    # connection. Downstream headers are committed as soon as the downstream translator emits chunks
    # (for formats that render handshake/heartbeats, headers commit immediately on release; for
    # formats like Chat Completions and Gemini that render nothing until the first text token, headers
    # commit when that first token arrives).
    # When unset or set to "0", "0s", "none", "unlimited", "disabled", "off", or "never", no time ceiling
    # is applied, and buffering relies purely on the 48-frame and 1MB byte budget.
    # Default: "0" (unlimited)
    stream-bootstrap-timeout: "0"
    # When true, enable opt-in compatibility for orphan Codex delegation outputs.
    # Converts orphan function_call_output items from codex_app/create_thread and
    # codex_app/send_message_to_thread (which lack a valid call_id or matching function_call)
    # into standard user messages across Responses and non-Codex protocols when the request
    # header contains X-Openai-Subagent: collab_spawn.
    orphan-delegation-compatibility: false
    # When true, scope Codex usage_limit_reached quota cooldowns to the requested model rather
    # than cooling down the entire credential across all sibling models.
    # Default: false
    model-level-cooling: false

  claude:
    # When true, scope quota cooldowns to the requested model rather than cooling down
    # the entire credential across all sibling models. Default is false.
    model-level-cooling: false

    # When true, enable Codex client tool_search on Claude Responses routes. Credentials on
    # api.anthropic.com (or keys with native-tool-search: true) receive it as Anthropic native
    # tool search (defer_loading + tool_reference), which keeps the prompt-cache prefix stable
    # across tool discoveries; other credentials fall back to the plain translation. The Codex
    # model catalog advertises supports_search_tool for a Claude model only when every
    # credential serving it supports native tool search.
    # Default false keeps the translation and catalog behavior that predate tool_search support.
    tool-search: false

    # Days to retain the cloaked currentDate pin per session, so an idle gap or a credential
    # switch cannot re-anchor the date and invalidate earlier thinking signatures and the
    # prompt cache. Default 7; an explicit 0 keeps the continuity-scoped pin (1h lifetime).
    session-date-pin-days: 7

    # When true, disable Claude request cloaking on OAuth and API-key CLI profiles (the Claude Code CLI disguise and
    # system prompt replacement), so the original system prompt is passed through to Claude as-is.
    # Credential attributes and explicit per-key cloak modes override this shared default.
    # Default false keeps the per-client "auto" behavior (cloak only non-Claude-Code clients).
    # API-key overrides use api-keys.claude[].keys[].cloak.mode.
    disable-claude-cloak-mode: false

    # When true, return original model IDs in Anthropic model list responses instead of cloaked IDs.
    disable-cloaking-model-list: false

    # Anthropic-Beta is assembled per request rather than sent as a fixed list, matching
    # Claude Code: context-1m sits right after claude-code, mid-conversation-system
    # is added only for models that accept a role=system turn, advanced-tool-use only when
    # the request uses tool search (deferred tools) or another advanced tool-use feature,
    # afk-mode sits between fast-mode and extended-cache-ttl, and server-side-fallback / fallback-credit /
    # structured-outputs trail effort. On direct api.anthropic.com a caller may only ask for
    # betas real Claude Code also sends, and they are placed at their observed positions;
    # anything else is dropped so the outgoing set stays one a real client could produce.
    # Other Anthropic-compatible upstreams still forward caller betas verbatim.
    #
    # Shared Claude CLI fingerprint defaults. Update only after measuring a new Claude Code release.
    # Unconfirmed clients use this CLI baseline. Verified native Claude Code CLI, sdk-cli,
    # sdk-ts, and VSCode requests preserve their measured entrypoint when the Claude Code version is a
    # patch release in the configured major/minor line at or above this baseline. Older versions
    # and newer major/minor lines fall back to the baseline until measured. In legacy mode,
    # timeout is a fallback and
    # verified native OS/arch values remain client-supplied. When stabilize-device-profile is
    # enabled, OS/arch are pinned to the values below and cached profiles remain constrained to
    # the same exact software baseline rather than learning newer client versions.
    # header-defaults:
    #   user-agent: "claude-cli/2.1.280 (external, cli)"
    #   package-version: "0.112.1"
    #   runtime-version: "v26.3.0"
    #   os: "MacOS"
    #   arch: "arm64"
    #   timeout: "600"
    #   timezone: "Asia/Singapore"  # fallback IANA timezone for cloaked currentDate; a credential JSON "timezone" takes priority
    #   stabilize-device-profile: false  # optional, default false; set true to enable per-auth fingerprint pinning
    #   # Advanced operator overrides for exact-parity or gateway lanes. They apply to every Claude
    #   # request, after the per-request derivation above, and can produce a beta set real Claude Code
    #   # never sends, which api.anthropic.com may reject. Names are matched exactly; strip runs first.
    #   # A credential's own "headers" entries are more specific and keep precedence where they already
    #   # did: Anthropic-Beta on custom gateways and x-client-request-id everywhere.
    #   anthropic-beta-strip: []   # remove these names from the derived or caller-supplied set, keeping order
    #   anthropic-beta-append: []  # append these names at the end unless already present
    #   # Cloaked requests to api.anthropic.com get a "diagnostics" body field like Claude Code, which in
    #   # turn adds cache-diagnosis-2026-04-07. Set false to stop injecting it (default true).
    #   inject-diagnostics: true
    #   # x-client-request-id on first-party CLI-profile requests: "on" (default) synthesizes a fresh
    #   # UUID per request (a confirmed Claude Code client keeps its own), "passthrough" forwards only
    #   # the caller's value and never synthesizes one, "off" never sends the header.
    #   client-request-id: "on"

  xai:
    # When true, inject the native x_search tool when the request does not declare it.
    # The injected tool is also added to tool_choice.allowed_tools when applicable.
    inject-x-search: false

# API-key upstreams are separate from access.api-keys (client authentication).
# Each provider contains named groups: one base-url, shared settings, and a keys list.
# Add another group for another endpoint; base-url belongs to the group, not a key.
# Shared settings retain their provider-specific validation and meaning.
# Missing/null per-key overrides inherit the group value, then the runtime fallback.
# Explicit false, 0, empty strings, and empty collections override inheritance when
# supported by the field. Map/list overrides replace the inherited value as a whole.
# Negative request-retry values retain the global fallback; weight belongs to each key.
# An empty proxy-url falls back to requests.proxy-url; direct bypasses proxy settings.
# Shared provider defaults belong to upstream; OAuth-only features remain under oauth.providers.
# Keep differing legacy policies in separate groups or preserve them as key overrides.
# Uncomment the api-keys root and only the provider examples you want to configure.
# Replace placeholder keys/URLs before using them.

# BEGIN API KEY EXAMPLES

# api-keys:
#
#   # Gemini API keys
#
#   gemini:
#     - name: gemini-1
#       priority: 0 # larger values take precedence when selecting credentials
#       prefix: "test" # optional: require calls like "test/gemini-3-pro-preview" to target this credential
#       disable-cooling: false # optional override: true disables cooling, false enables it; omit to inherit global
#       request-retry: 3 # optional per-auth override; 0 disables additional rounds; omit or set < 0 to inherit global
#       request-scoped-errors: # optional: custom rules to classify upstream errors by status and body patterns
#         - status: 400        # HTTP status code to match
#           match:             # optional: string contains matching
#             - "maximum_context_length"
#             - "context_length_exceeded"
#           match-regexr:      # optional: regular expression matching
#             - "maximum_context_length$"
#             - "^context_length_exceeded"
#           action: "stop"     # "stop" (return error, no cooling), "stop-and-cooldown" (return error and cool down),
#                              # "continue" (try next credential, no cooling), "continue-and-cooldown" (try next credential and cool down)
#       base-url: "https://generativelanguage.googleapis.com"
#       headers:
#         X-Custom-Header: "custom-value"
#         # Values starting with "$" dynamically copy the header value from downstream client requests.
#         # If the client did not send the specified header, the header is omitted.
#         # X-Claude-Code-Session-Id: "$ABC" # copies client's "ABC" header
#       proxy-url: "socks5://proxy.example.com:1080"
#       # proxy-url: "direct" # optional: explicit direct connect for this credential
#       models:
#         - name: "gemini-2.5-flash" # upstream model name
#           alias: "gemini-flash"    # client alias mapped to the upstream model
#           display-name: "Gemini Flash" # optional catalog display name
#           max-context-length: 1048576 # optional: override Codex client context window metadata
#           is-compat: false             # optional: preserve thinking blocks with empty signatures for compatible upstreams
#           thinking:                    # optional: exact thinking capability for this configured model
#             levels: ["high", "medium", "low", "none", "auto"]
#             # For budget-based models, replace levels with these capabilities:
#             # min: 1024
#             # max: 32768
#             # zero-allowed: true
#             # dynamic-allowed: true
#       excluded-models:
#         - "gemini-2.5-pro"     # exclude specific models from this provider (exact match)
#         - "gemini-2.5-*"       # wildcard matching prefix (e.g. gemini-2.5-flash, gemini-2.5-pro)
#         - "*-preview"          # wildcard matching suffix (e.g. gemini-3-pro-preview)
#         - "*flash*"            # wildcard matching substring (e.g. gemini-2.5-flash-lite)
#       keys:
#         - api-key: "AIzaSy...01"
#           weight: 5 # optional: weighted-round-robin share; omitted defaults to 1; maximum 1,000,000
#         # A second key shares this group's endpoint, headers, and models.
#         - api-key: "replace-with-second-gemini-key"
#           weight: 2
#           priority: null # inherit the group priority
#           prefix: null # inherit the group prefix
#           proxy-url: "direct" # override the group proxy for this key
#           headers: null # inherit the complete group header map
#           models: null # inherit the complete group model list
#           excluded-models: [] # explicitly clear the inherited exclusions
#           disable-cooling: false # an explicit false overrides a true group setting
#           request-retry: 0 # explicitly disable additional rounds for this key
#           request-scoped-errors: null # inherit the group rules
#     - name: gemini-2
#       keys:
#         - api-key: "AIzaSy...02"
#
#   # Native Interactions API keys
#   # These keys are used only for direct /v1beta/interactions execution. Regular api-keys.gemini entries still
#   # send Gemini generateContent/streamGenerateContent requests when the client enters through the interactions API.
#
#   interactions:
#     - name: interactions-1
#       prefix: "native" # optional: require calls like "native/gemini-3-pro-preview" to target this credential
#       disable-cooling: false # optional override: true disables cooling, false enables it; omit to inherit global
#       request-retry: 3 # optional per-auth override; 0 disables additional rounds; omit or set < 0 to inherit global
#       request-scoped-errors: # optional: custom rules to classify upstream errors by status and body patterns
#         - status: 400
#           match:
#             - "invalid_argument"
#           action: "continue"
#       base-url: "https://generativelanguage.googleapis.com"
#       headers:
#         X-Custom-Header: "custom-value"
#         # Values starting with "$" dynamically copy the header value from downstream client requests.
#         # If the client did not send the specified header, the header is omitted.
#         # X-Claude-Code-Session-Id: "$ABC" # copies client's "ABC" header
#       proxy-url: "socks5://proxy.example.com:1080"
#       # proxy-url: "direct" # optional: explicit direct connect for this credential
#       models:
#         - name: "gemini-2.5-flash" # upstream model name
#           alias: "native-gemini-flash" # client alias mapped to the upstream model
#           max-context-length: 1048576 # optional: override Codex client context window metadata
#           is-compat: false             # optional: preserve thinking blocks with empty signatures for compatible upstreams
#           thinking:                    # optional: exact thinking capability for this configured model
#             levels: ["high", "medium", "low", "none", "auto"]
#       excluded-models:
#         - "gemini-2.5-pro"
#       keys:
#         - api-key: "AIzaSy...03"
#           weight: 5 # optional: weighted-round-robin share; omitted defaults to 1; maximum 1,000,000
#
#   # Vertex API keys (Vertex-compatible endpoints, base-url is optional)
#
#   vertex:
#     - name: vertex-1
#       prefix: "test"                              # optional: require calls like "test/vertex-pro" to target this credential
#       disable-cooling: false                       # optional override: true disables cooling, false enables it; omit to inherit global
#       request-retry: 3                             # optional per-auth override; 0 disables additional rounds; omit or set < 0 to inherit global
#       base-url: "https://example.com/api"         # optional, e.g. https://zenmux.ai/api; falls back to Google Vertex when omitted
#       proxy-url: "socks5://proxy.example.com:1080" # optional per-key proxy override
#       # proxy-url: "direct" # optional: explicit direct connect for this credential
#       # interactions: true                        # optional: opt into native Vertex Interactions API routing (/v1beta1/interactions). For service account JSON files under auths/, add "interactions": true at the root of the file.
#       headers:
#         X-Custom-Header: "custom-value"
#         # Values starting with "$" dynamically copy the header value from downstream client requests.
#         # If the client did not send the specified header, the header is omitted.
#         # X-Claude-Code-Session-Id: "$ABC" # copies client's "ABC" header
#       models:                                     # optional: map aliases to upstream model names
#         - name: "gemini-2.5-flash"                # upstream model name
#           alias: "vertex-flash"                   # client-visible alias
#           display-name: "Vertex Flash"            # optional catalog display name
#           thinking:                                # optional: exact thinking capability for this configured model
#             levels: ["high", "medium", "low", "none", "auto"]
#         - name: "gemini-2.5-pro"
#           alias: "vertex-pro"
#       excluded-models:                            # optional: models to exclude from listing
#         - "imagen-3.0-generate-002"
#         - "imagen-*"
#       keys:
#         - api-key: "vk-123..."                        # x-goog-api-key header
#           weight: 5                                    # optional: weighted-round-robin share; omitted defaults to 1; maximum 1,000,000
#
#   # Codex API keys
#
#   codex:
#     - name: codex-1
#       prefix: "test" # optional: require calls like "test/gpt-5-codex" to target this credential
#       disable-cooling: false # optional override: true disables cooling, false enables it; omit to inherit global
#       request-retry: 3 # optional per-auth override; 0 disables additional rounds; omit or set < 0 to inherit global
#       request-scoped-errors: # optional: custom rules to classify upstream errors by status and body patterns
#         - status: 400
#           match:
#             - "context_window_exceeded"
#           action: "stop-and-cooldown"
#       base-url: "https://www.example.com" # use the custom codex API endpoint
#       headers:
#         X-Custom-Header: "custom-value"
#         # Values starting with "$" dynamically copy the header value from downstream client requests.
#         # If the client did not send the specified header, the header is omitted.
#         # X-Claude-Code-Session-Id: "$ABC" # copies client's "ABC" header
#       proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override
#       # proxy-url: "direct" # optional: explicit direct connect for this credential
#       models:
#         - name: "gpt-5-codex"   # upstream model name
#           alias: "codex-latest" # client alias mapped to the upstream model
#           display-name: "Codex Latest" # optional catalog display name
#           max-context-length: 1048576 # optional: override Codex client context window metadata
#           force-mapping: true    # optional: rewrite response model fields back to the alias
#           # Preserve thinking blocks with empty signatures for compatible upstreams.
#           # client.codex.optimize-multi-agent-v2 applies to both OAuth and API-key credentials.
#           is-compat: false
#           # Optional: enable configuration_update for this API-key model; omitted defaults to false.
#           support-configuration-update: false
#           thinking:              # optional: exact thinking capability for this configured model
#             levels: ["xhigh", "high", "medium", "low"]
#       excluded-models:
#         - "gpt-5.1"         # exclude specific models (exact match)
#         - "gpt-5-*"         # wildcard matching prefix (e.g. gpt-5-medium, gpt-5-codex)
#         - "*-mini"          # wildcard matching suffix (e.g. gpt-5-codex-mini)
#         - "*codex*"         # wildcard matching substring (e.g. gpt-5-codex-low)
#       keys:
#         - api-key: "sk-atSM..."
#           weight: 5 # optional: weighted-round-robin share; omitted defaults to 1; maximum 1,000,000
#           disable-codex-cloaking: false # optional: true disables cloaking; OAuth provider settings do not apply here
#           alpha-search: false # optional: allow this key to serve /v1/alpha/search via base-url + /alpha/search
#           websockets: false # optional: use the Codex upstream WebSocket transport
#
#   # Claude API keys
#
#   claude:
#     - name: claude-1
#       keys:
#         - api-key: "sk-atSM..." # use the official claude API key, no need to set the base url
#     - name: claude-2
#       prefix: "test" # optional: require calls like "test/claude-sonnet-latest" to target this credential
#       disable-cooling: false # optional override: true disables cooling, false enables it; omit to inherit global
#       request-retry: 3 # optional per-auth override; 0 disables additional rounds; omit or set < 0 to inherit global
#       request-scoped-errors: # optional: custom rules to classify upstream errors by status and body patterns
#         - status: 400
#           match:
#             - "prompt is too long"
#           action: "stop"
#       base-url: "https://www.example.com" # use the custom claude API endpoint
#       headers:
#         X-Custom-Header: "custom-value"
#         # Values starting with "$" dynamically copy the header value from downstream client requests.
#         # If the client did not send the specified header, the header is omitted.
#         # X-Claude-Code-Session-Id: "$ABC" # copies client's "ABC" header
#       proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override
#       # proxy-url: "direct" # optional: explicit direct connect for this credential
#       models:
#         - name: "claude-3-5-sonnet-20241022" # upstream model name
#           alias: "claude-sonnet-latest"      # client alias mapped to the upstream model
#           display-name: "Claude Sonnet"      # optional catalog display name
#           max-context-length: 1048576         # optional: override Codex client context window metadata
#           force-mapping: true                 # optional: rewrite response model fields back to the alias
#           is-compat: false                    # optional: preserve thinking blocks with empty signatures for compatible upstreams
#           thinking:                           # optional: exact thinking capability for this configured model
#             levels: ["max", "xhigh", "high", "medium", "low", "minimal", "none", "auto"]
#       excluded-models:
#         - "claude-opus-4-5-20251101" # exclude specific models (exact match)
#         - "claude-3-*"               # wildcard matching prefix (e.g. claude-3-7-sonnet-20250219)
#         - "*-thinking"               # wildcard matching suffix (e.g. claude-opus-4-5-thinking)
#         - "*haiku*"                  # wildcard matching substring (e.g. claude-3-5-haiku-20241022)
#       keys:
#         - api-key: "sk-atSM..."
#           weight: 5 # optional: weighted-round-robin share; omitted defaults to 1; maximum 1,000,000
#           rebuild-mid-system-message: false # optional: default is false; when true, move messages with role "system" into the top-level Claude system field
#           native-tool-search: false # optional: default is false; when true, trust this key's custom base-url with Anthropic native tool search (defer_loading + tool_reference) for Codex tool_search; requires upstream.claude.tool-search: true
#           cloak:                         # optional: explicitly enable request cloaking for non-Claude-Code clients
#             mode: "auto"                 # "auto" (default inside this block): cloak only when client is not Claude Code
#                                          # "always": cloak every unconfirmed client; confirmed native Claude Code still passes through
#                                          # "never" / "uncloak": never apply cloaking; on non-CLI API keys, also strip incoming Claude Code identity/billing attribution
#             # This "cloak" block applies to this api-keys.claude key entry only. For Claude OAuth
#             # credentials, set the same options in the auth/token JSON file via "cloak_mode" /
#             # "cloak_strict_mode" / "cloak_sensitive_words" / "cloak_cache_user_id".
#             # upstream.claude.disable-claude-cloak-mode is the shared default; this key can override it.
#             strict-mode: false           # false (default): legacy-model whitelist uses a user system-reminder;
#                                          # all other and future models use messages[].role=system
#                                          # true: strip caller prompts and keep only Claude Code billing and identity blocks
#             sensitive-words:             # optional: words to obfuscate with zero-width characters
#               - "API"
#               - "proxy"
#             cache-user-id: true          # optional: default is false; set true to reuse cached user_id per API key instead of generating a random one each request
#             # Every custom tool on a cloaked OAuth request automatically uses a caller-stable opaque mcp__<server>__<tool> alias.
#
#           # fingerprint-profile (optional, top-level on this api-keys.claude key entry; not a cloak sub-field):
#           # OAuth and API-key fingerprints are different contracts.
#           #   - Real Claude OAuth stays on the strict Claude Code CLI wire fingerprint.
#           #   - API keys (official Anthropic, custom gateways, Kimi) stay loose and
#           #     caller-owned unless this field is set.
#           #
#           # Default (omit / empty): keep the caller request fingerprint and headers.
#           # Official api.anthropic.com API keys do not add extra CLI betas/identity unless
#           # this field is set. Custom gateways and delegated providers are the same.
#           #
#           # Controls request fingerprint only on /v1/messages (and related Claude executor paths).
#           # Auth scheme stays API key (x-api-key on api.anthropic.com; Bearer on custom base-url).
#           # Does NOT enable OAuth refresh, profile fetch, or OAuth-cancellation semantics.
#           #
#           # Values:
#           #   omit / empty        = caller-owned API-key fingerprint (respects caller)
#           #   "claude-code-cli"   = same Messages fingerprint as Claude Code OAuth CLI,
#           #                         including official Anthropic API keys: OAuth Anthropic-Beta
#           #                         set, CCH signing on api.anthropic.com, stable CLI
#           #                         metadata.user_id / session_id / device identity.
#           #                         API keys seed identity from the key;
#           #                         delegated OAuth providers use stable auth ID instead of
#           #                         rotating access tokens. "oauth-cli" is a legacy alias.
#           #
#           # count_tokens keeps the native model/messages/tools shape for every origin, including
#           # Kimi opt-in. It does not send billing/CCH, currentDate, metadata, or diagnostics.
#           #
#           # CCH: the billing block may carry a per-request cch hash. CPA emits it exactly where
#           # Claude Code does, which is api.anthropic.com (first-party) and Vertex only. An opt-in
#           # on any other gateway (including Kimi) still sends the billing block, but without cch,
#           # so a per-request hash cannot bust that gateway's prompt cache. api.anthropic.com
#           # strips the block itself (0 tokens, no cache impact). Kimi drops the whole block by
#           # default and keeps it, unsigned, after an explicit fingerprint opt-in.
#           # A real Claude OAuth credential always signs, on every upstream: a downstream Claude
#           # Code pointed at CPA cannot produce that value itself.
#           #
#           # Example group under api-keys.claude (official Anthropic or a Messages gateway):
#           #   - name: cli-compatible-gateway
#           #     # base-url: "https://gateway.example"   # omit for api.anthropic.com
#           #     keys:
#           #       - api-key: "your-key"
#           #         fingerprint-profile: "claude-code-cli"
#           #         cloak:
#           #           mode: "always"   # recommended when upstream rejects non-CLI clients
#           #
#           # Delegated Anthropic Messages OAuth files (Kimi, etc.) use "fingerprint_profile"
#           # in the auth JSON. Refresh keeps it. Example:
#           #   {
#           #     "type": "kimi",
#           #     "access_token": "...",
#           #     "refresh_token": "...",
#           #     "fingerprint_profile": "claude-code-cli"
#           #   }
#           #   Legacy "fingerprint-profile" credentials remain supported and are normalized at load time.
#           # fingerprint-profile: "claude-code-cli" # optional api-keys.claude key field; default is empty (caller-owned); uncomment to opt in
#           experimental-cch-signing: false # deprecated compatibility field; CCH is generated automatically
#                                           # for real Claude OAuth on any upstream, and for claude-code-cli profiles
#                                           # only on api.anthropic.com; Vertex keeps provider-native signing
#
#   # xAI API keys
#   # Uses the native xAI executor, including its Responses namespace-tool handling.
#
#   xai:
#     - name: xai-1
#       prefix: "xai" # optional: require calls like "xai/grok-4.5" to target this credential
#       disable-cooling: false # optional override: true disables cooling, false enables it; omit to inherit global
#       request-retry: 3 # optional per-auth override; 0 disables additional rounds; omit or set < 0 to inherit global
#       request-scoped-errors: # optional: custom rules to classify upstream errors by status and body patterns
#         - status: 400
#           match:
#             - "rate_limit_exceeded"
#           action: "continue-and-cooldown"
#       base-url: "https://api.x.ai/v1" # xAI-compatible Responses API endpoint
#       headers:
#         X-Custom-Header: "custom-value"
#         # Values starting with "$" dynamically copy the header value from downstream client requests.
#         # If the client did not send the specified header, the header is omitted.
#         # X-Claude-Code-Session-Id: "$ABC" # copies client's "ABC" header
#       proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override
#       # proxy-url: "direct" # optional: explicit direct connect for this credential
#       models:
#         - name: "grok-4.5"       # upstream model name
#           alias: "grok-latest"   # client alias mapped to the upstream model
#           display-name: "Grok Latest" # optional catalog display name
#           max-context-length: 1048576 # optional: override Codex client context window metadata
#           force-mapping: true     # optional: rewrite response model fields back to the alias
#           is-compat: false        # optional: preserve thinking blocks with empty signatures for compatible upstreams
#           thinking:               # optional: exact thinking capability for this configured model
#             levels: ["xhigh", "high", "medium", "low"]
#       excluded-models:
#         - "grok-4.1"             # exclude specific models (exact match)
#         - "grok-3-*"             # wildcard matching prefix
#       keys:
#         - api-key: "xai-..."
#           weight: 5 # optional: weighted-round-robin share; omitted defaults to 1; maximum 1,000,000
#           websockets: true # optional: use the xAI upstream websocket transport for downstream websocket requests
#
#   # Meta API keys (Muse Code)
#   # Uses the native Meta executor targeting https://api.meta.ai/v1.
#
#   meta:
#     - name: meta-1
#       prefix: "meta" # optional: require calls like "meta/muse-spark-1.3" to target this credential
#       disable-cooling: false # optional override: true disables cooling, false enables it; omit to inherit global
#       request-retry: 3 # optional per-auth override; 0 disables additional rounds; omit or set < 0 to inherit global
#       base-url: "https://api.meta.ai/v1" # optional: defaults to https://api.meta.ai/v1
#       proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override
#       models:
#         - name: "muse-spark-1.3" # upstream model name
#           alias: "muse-latest"   # client alias mapped to the upstream model
#       excluded-models:
#         - "muse-spark-1.1"
#       keys:
#         - api-key: "..."
#           weight: 5 # optional: weighted-round-robin share; omitted defaults to 1; maximum 1,000,000
#
#   # OpenAI compatibility providers
#
#   openai-compatibility:
#     - name: "openrouter" # The name of the provider; it will be used in the user agent and other places.
#       disabled: false # optional: set to true to disable this provider without removing it
#       prefix: "test" # optional: require calls like "test/kimi-k2" to target this provider's credentials
#       base-url: "https://openrouter.ai/api/v1" # The base URL of the provider.
#       support-prompt-cache-key: false # optional: derive prompt_cache_key for requests from all input protocols
#       disable-cooling: false # optional provider override: true disables cooling, false enables it; omit to inherit global
#       request-retry: 3 # optional per-provider override; 0 disables additional rounds; omit or set < 0 to inherit global
#       request-scoped-errors: # optional: custom rules to classify upstream errors by status and body patterns
#         - status: 400
#           match:
#             - "maximum_context_length"
#             - "context_length_exceeded"
#           match-regexr:
#             - "maximum_context_length$"
#             - "^context_length_exceeded"
#           action: "stop" # "stop", "stop-and-cooldown", "continue", "continue-and-cooldown"
#       headers:
#         X-Custom-Header: "custom-value"
#         # Values starting with "$" dynamically copy the header value from downstream client requests.
#         # If the client did not send the specified header, the header is omitted.
#         # X-Claude-Code-Session-Id: "$ABC" # copies client's "ABC" header
#       keys:
#         - api-key: "sk-or-v1-...b780"
#           weight: 5 # optional: weighted-round-robin share; omitted defaults to 1; maximum 1,000,000
#           proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override
#           # proxy-url: "direct" # optional: explicit direct connect for this credential
#         - api-key: "sk-or-v1-...b781" # without proxy-url
#       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.
#           display-name: "Kimi K2"         # optional catalog display name
#           max-context-length: 1048576    # optional: override Codex client context window metadata
#           image: false                   # optional: set true to allow this model on /v1/images/generations and /v1/images/edits (not chat/responses image input)
#           input-modalities: [text, image] # optional: declare /v1/chat/completions and /v1/responses multimodal input for Codex clients. Use [text] for upstreams that reject multimodal tool result content.
#           output-modalities: [text]       # optional: declare output modalities when known
#           is-compat: false                # optional: preserve Claude thinking blocks for compatible upstreams
#           use-max-completion-tokens: false # optional: default false (uses max_tokens); set true to use max_completion_tokens
#           thinking:                      # optional: omit to default to levels ["low","medium","high"]. Exceeding levels (e.g. "max", "xhigh") are clamped to "high"; explicitly declare levels here if the upstream supports them
#             levels: ["low", "medium", "high"]
#         # You may repeat the same alias to build an internal model pool.
#         # The client still sees only one alias in the model list.
#         # Requests to that alias will round-robin across the upstream names below,
#         # and if the chosen upstream fails before producing output, the request will
#         # continue with the next upstream model in the same alias pool.
#         - name: "deepseek-v3.1"
#           alias: "claude-opus-4.66"
#         - name: "glm-5"
#           alias: "claude-opus-4.66"
#         - name: "kimi-k2.5"
#           alias: "claude-opus-4.66"

# END API KEY EXAMPLES

# OAuth/file-backed credentials. Token material stays in the credential store.
oauth:
  # Authentication directory (supports ~ for home directory)
  auth-dir: "~/.cli-proxy-api"

  # Core auth auto-refresh and manual refresh-all worker pool size (OAuth/file-based auth token refresh).
  # When > 0, overrides the default worker count (16).
  # auth-auto-refresh-workers: 16

  # Global OAuth model name aliases (per channel)
  # These aliases rename model IDs for both model listing and request routing.
  # Supported channels: vertex, aistudio, antigravity, claude, codex, kimi, xai, meta.
  # NOTE: These aliases do not apply to any of the upstream groups under api-keys.
  # NOTE: Because aliases affect the merged /v1 model list and merged request routing, overlapping
  # client-visible names can become ambiguous across providers. For strict backend pinning, use
  # unique aliases/prefixes or avoid overlapping names.
  # You can repeat the same name with different aliases to expose multiple client model names.
  # Optional per-entry fields:
  #   fork: true                  # keep the upstream model and also expose the alias as a separate client-visible model
  #   display-name: "Model Name" # override the human-readable name shown in model catalogs
  #   force-mapping: true         # rewrite upstream response model fields back to the client-visible alias (example below uses antigravity only)
  # Per-auth OAuth aliases can also be stored in an OAuth auth JSON file as "model_aliases".
  # Legacy "model-aliases" credentials remain supported and are normalized at load time.
  # They apply only to that selected auth and take precedence over global aliases for the same client-visible alias.
  # Example auth JSON:
  # {
  #   "type": "codex",
  #   "email": "user@example.com",
  #   "model_aliases": [
  #     {"name": "gpt-5.3-codex-spark", "alias": "gpt-5.5"},
  #     {"name": "gpt-5.3-codex-spark", "alias": "gpt-5.4"}
  #   ]
  # }
  # model-alias:
  #   vertex:
  #     - name: "gemini-2.5-pro"
  #       alias: "g2.5p"
  #   aistudio:
  #     - name: "gemini-2.5-pro"
  #       alias: "g2.5p"
  #   antigravity:
  #     - name: "gemini-pro-agent"                   # upstream Antigravity model id
  #       alias: "gemini-3.1-pro-preview"            # client-visible id (Gemini 3.1 Pro Preview)
  #       display-name: "Antigravity Gemini 3.1 Pro" # optional catalog display name
  #       fork: true
  #       force-mapping: true
  #   claude:
  #     - name: "claude-sonnet-4-5-20250929"
  #       alias: "cs4.5"
  #   codex:
  #     - name: "gpt-5"
  #       alias: "g5"
  #   kimi:
  #     - name: "kimi-k2.5"
  #       alias: "k2.5"
  #   xai:
  #     - name: "grok-4.3"
  #       alias: "grok-latest"
  #   meta:
  #     - name: "muse-spark-1.3"
  #       alias: "muse-latest"
  #   sample-provider:                  # plugin provider keys are supported for OAuth plugins
  #     - name: "sample-model-latest"
  #       alias: "sample-latest"

  # OAuth provider model settings (per channel)
  # Allows overriding model-level capabilities (such as context window) for OAuth credentials.
  # Supported channels: vertex, aistudio, antigravity, claude, codex, kimi, xai, meta.
  # settings:
  #   codex:
  #     - name: "gpt-6-sol"
  #       max-context-length: 524288 # overrides context window advertised to Codex clients
  #     - name: "gpt-6-astra"
  #       max-context-length: 1048576

  # OAuth provider excluded models
  # Applies to OAuth/file-backed credentials of each provider.
  # A credential's own non-empty "excluded_models" list (set in its auth JSON file) takes priority
  # over these rules for that credential and is not merged with them. Credentials without their own
  # list (missing, empty, or null) inherit the current rules here; changes to these rules
  # take effect for them on config reload.
  # excluded-models:
  #   vertex:
  #     - "gemini-3-pro-preview"
  #   aistudio:
  #     - "gemini-3-pro-preview"
  #   antigravity:
  #     - "gemini-3-pro-preview"
  #   claude:
  #     - "claude-3-5-haiku-20241022"
  #   codex:
  #     - "gpt-5-codex-mini"
  #   kimi:
  #     - "kimi-k2-thinking"
  #   xai:
  #     - "grok-3-mini"
  #   meta:
  #     - "muse-spark-1.1"

  # OAuth provider request-scoped error rules (custom error classification for OAuth credentials)
  # request-scoped-errors:
  #   vertex:
  #     - status: 400
  #       match:
  #         - "maximum_context_length"
  #         - "context_length_exceeded"
  #       match-regexr:
  #         - "maximum_context_length$"
  #         - "^context_length_exceeded"
  #       action: "stop" # options: "stop", "stop-and-cooldown", "continue", "continue-and-cooldown"
  #   aistudio:
  #     - status: 400
  #       match:
  #         - "invalid_argument"
  #       action: "stop"
  #   antigravity:
  #     - status: 500
  #       match:
  #         - "internal_server_error"
  #       action: "stop-and-cooldown"
  #   claude:
  #     - status: 400
  #       match:
  #         - "prompt is too long"
  #       action: "stop"
  #   codex:
  #     - status: 400
  #       match:
  #         - "context_window_exceeded"
  #       action: "stop"
  #   kimi:
  #     - status: 400
  #       match:
  #         - "length_limit"
  #       action: "stop"
  #   xai:
  #     - status: 400
  #       match:
  #         - "max_tokens_exceeded"
  #       action: "stop"
  #   meta:
  #     - status: 400
  #       match:
  #         - "context_length_exceeded"
  #       action: "stop"

  # Provider options below apply to OAuth/file-backed credentials.
  # API-key credentials use their own group/key options.
  providers:
    aistudio:
      # When true, enable authentication for the WebSocket API (/v1/ws).
      ws-auth: true

    # Codex provider behavior.
    codex:
      # Terminate and relay Codex Live WebRTC audio and DataChannel traffic in this process.
      # This requires inbound UDP reachability. Keep disabled to preserve direct media behavior.
      live-media-relay:
        enabled: false
        # Maximum concurrent media sessions. Zero uses the default of 32.
        max-sessions: 32
        # Reject downstream SDP candidates that target private, loopback, link-local, or unspecified IPs.
        # Keep false for local or trusted-network Codex Desktop connections.
        disable-private-remote-ips: false
        # Public IPv4 or IPv6 address advertised when CPA is behind 1:1 NAT.
        public-ip: ""
        # Optional UDP allocation range. Both values must be set together and provide at least two ports per session.
        udp-port-min: 0
        udp-port-max: 0
        # Optional STUN/TURN servers. TURN credentials are never returned by the JSON config API.
        # Without a concrete global/per-auth proxy-url, WebRTC uses normal direct ICE/STUN/TURN connectivity.
        # With http, https, socks5, or socks5h proxy-url, the OpenAI-facing leg is forced through
        # authenticated ICE-TCP over that proxy and never falls back to UDP or a direct connection.
        # The Codex Desktop-facing leg remains direct, and configured ICE servers still apply to it.
        # ice-servers:
        #   - urls:
        #       - "stun:stun.example.com:3478"
        #   - urls:
        #       - "turn:turn.example.com:3478?transport=udp"
        #     username: "user"
        #     credential: "secret"

      # Identifier (agent_name_hint and User-Agent prefix) for Sign in with ChatGPT (SIWC) OAuth and API requests.
      signin-with-chatgpt-identifier: "CLIProxyAPI"

      # Default headers for Codex OAuth model requests.
      # These are used only for file-backed/OAuth Codex requests when the client
      # does not send the header. `user-agent` applies to HTTP and websocket requests;
      # `beta-features` only applies to websocket requests. They do not apply to api-keys.codex entries.
      # 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"

    # Antigravity provider behavior.
    antigravity:
      # sensitive-words:              # optional: words to obfuscate with zero-width characters in system instructions
      #   - "API"
      #   - "proxy"
      # connection-pool:              # optional: upstream HTTP connection pool settings
      #   enabled: false             # whether to enable connection pooling (default: false)
      #   idle-conn-timeout: "30s"    # idle keep-alive timeout (default: 30s, capped at 210s)
      #   max-idle-conns-per-host: 2  # max idle connections per host per credential (default: 2)
      # Use credits as a last resort after free-tier Claude quota is exhausted.
      antigravity-credits: true

      # Signature cache validation for thinking blocks (Antigravity/Claude).
      # When true (default), cached signatures are preferred and validated.
      # When false, client signatures are used directly after normalization (bypass mode for testing).
      # signature-cache-enabled: true

      # Bypass mode signature validation strictness (only applies when signature cache is disabled).
      # When true, validates full Claude protobuf tree (Field 2 -> Field 1 structure).
      # When false (default), only checks R/E prefix + base64 + first byte 0x12.
      # signature-bypass-strict: false

    # Devin provider behavior.
    # devin:
    #   sensitive-words:             # optional: words to obfuscate with zero-width characters in system instructions and prompts
    #     - "API"
    #     - "proxy"

# Image and video behavior.
multimedia:
  # disable-image-generation supports: false (default), true, "chat", or "passthrough".
  # - true: disable image_generation everywhere (also returns 404 for /v1/images/generations and /v1/images/edits).
  # - "chat": disable image_generation injection on non-images endpoints, but keep /v1/images/generations and /v1/images/edits enabled.
  # - "passthrough": never inject or strip image_generation on non-images endpoints (forward the client payload unchanged); behaves like "chat" on /v1/images/* endpoints.
  disable-image-generation: false

  # Base model used by the legacy hosted image_generation tool path when a Codex image request is not proxied directly through the Image API.
  # Must start with "gpt-" (case-insensitive). If unset or invalid, defaults to "gpt-5.4-mini".
  # gpt-image-2-base-model: "gpt-5.4-mini"

  # How long video IDs returned by /openai/v1/videos and xAI video creation stay bound
  # to the credential that created them. Default: 3h.
  video-result-auth-cache-ttl: "3h"

# Application logs, request logs, usage aggregation, and profiling.
observability:
  logs:
    # Enable debug logging
    debug: false

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

    # Maximum total size (MB) of log files under the logs directory. When exceeded, the oldest log
    # files are deleted until within the limit. Set to 0 to disable.
    logs-max-total-size-mb: 0

    # Maximum number of error log files retained when request logging is disabled.
    # When exceeded, the oldest error log files are deleted. Default is 10. Set to 0 to disable cleanup.
    error-logs-max-files: 10

    # Record proxy request/response logs. Management requests are excluded.
    request-log: false

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

    # How long (in seconds) usage queue items are retained in memory for the Management API.
    # The local Redis RESP usage output is disabled.
    # Default: 60. Max: 3600.
    redis-usage-queue-retention-seconds: 60

  # Enable pprof HTTP debug server (host:port). Keep it bound to localhost for safety.
  pprof:
    enable: false
    addr: "127.0.0.1:8316"

# Standard dynamic library plugins are trusted in-process code. They are disabled by default.
# Build Go examples with go build -buildmode=c-shared for the target GOOS/GOARCH.
# Other languages can implement the same C ABI and JSON method protocol.
# Plugin executors require a matching auth record with the same provider key.
# If the same provider is configured as OpenAI-compatible, the native executor wins.
# Plugin command-line flags and Management API routes are optional capabilities.
# Existing native flags/routes and higher-priority plugin flags/routes cannot be replaced.
# Plugin list Management API reads Logo and ConfigFields from plugin metadata for management UI display.
# Per-plugin enabled only controls plugins.configs.<pluginID>.enabled and does not implicitly change global plugins.enabled.
plugins:
  enabled: false
  dir: "plugins"
  # Additional plugin store registries. The built-in official registry is always included.
  # store-sources:
  #   - "https://example.com/cliproxy-plugins/registry.json"
  # Optional plugin store auth rules. Secrets are read from environment variables.
  # Tokens are not stored in plugin manifests or node status.
  # store-auth:
  #   - match: "https://plugins.example.com/bearer/"
  #     apply-to: ["registry", "artifact"]
  #     type: "bearer"
  #     token-env: "CLIPROXY_PLUGIN_STORE_TOKEN"
  #     allow-insecure: false
  #   - match: "https://plugins.example.com/basic/"
  #     apply-to: ["registry", "artifact"]
  #     type: "basic"
  #     username-env: "CLIPROXY_PLUGIN_STORE_USER"
  #     password-env: "CLIPROXY_PLUGIN_STORE_PASSWORD"
  #     allow-insecure: false
  #   - match: "https://plugins.example.com/header/"
  #     apply-to: ["registry", "artifact"]
  #     type: "header"
  #     header-name: "X-Plugin-Token"
  #     header-value-env: "CLIPROXY_PLUGIN_STORE_HEADER_TOKEN"
  #     allow-insecure: false
  #   - match: "https://api.github.com/repos/example/"
  #     apply-to: ["registry", "artifact"]
  #     type: "github-token"
  #     token-env: "CLIPROXY_PLUGIN_GITHUB_TOKEN"
  #     allow-insecure: false

  # Home owns this revision; it is not an ordinary editable setting.
  # auth-revision: 0

  configs:
    example:
      enabled: true
      priority: 1
      config1: true
      config2: "string"
      config3: 3
      mode: "safe" # enum example: safe, fast
      config-list: ["a", "b"]
      config-object:
        mode: "safe"

# Legacy compatibility reference (comments only; not part of this v8 template).
# Old files and /v0/management still work without a v8 write. Existing legacy-only
# fields remain in their old locations until a successful v8 configuration write.
# When manually mixing layouts, a present new field wins over its legacy equivalent.
# To deliberately use an old field again, remove its corresponding new field first.
# Client keys moved from the old api-keys list to access.api-keys; the new root
# api-keys is reserved for provider groups. These cannot share one YAML key.
#
# Old spellings shown for reference:
#   host: ""                         # now server.host
#   port: 8317                       # now server.port
#   remote-management:               # now management
#     allow-remote: false
#     secret-key: ""
#   api-keys: ["your-api-key-1"]      # now access.api-keys
#   request-retry: 3                 # now routing.retry.request-retry
#   debug: false                     # now observability.logs.debug
#   proxy-url: ""                    # now requests.proxy-url
#   auth-dir: "~/.cli-proxy-api"     # now oauth.auth-dir
#   codex:                           # now oauth.providers.codex
#     disable-codex-cloaking: false
#   codex-api-key:                   # now api-keys.codex groups with keys
#     - api-key: "your-upstream-key"
#       base-url: "https://codex.example.com"
#
# Compatibility-only quota switches have no new v8 counterpart. They remain
# readable/editable in legacy files and through /v0/management, but are omitted
# from the active v8 template:
#   quota-exceeded:
#     switch-project: true
#     switch-preview-model: true
# antigravity-credits moved to oauth.providers.antigravity.antigravity-credits.