配置字段参考

路径约定：本文档中模块路径均相对于 src/coding/proxy/。

定位：本文档是所有配置参数的规范来源（Single Source of Truth）。设计模式章节和模块详情中引用参数默认值时，统一链接至此。

[TOC]

1. 配置模块结构

配置模型已从单体 schema.py 正交拆分为 5 个子模块：

子模块	文件	核心类型
server	`config/server.py`	`ServerConfig`, `DatabaseConfig`, `LoggingConfig`
vendors	`config/vendors.py`	`AnthropicConfig`, `CopilotConfig`, `AntigravityConfig`, `ZhipuConfig`, `MinimaxConfig`, `KimiConfig`, `DoubaoConfig`, `XiaomiConfig`, `AlibabaConfig`
resiliency	`config/resiliency.py`	`CircuitBreakerConfig`, `RetryConfig`, `FailoverConfig`, `QuotaGuardConfig`
routing	`config/routing.py`	`VendorType`, `VendorConfig`, `ModelMappingRule`, `ModelPricingEntry`
auth_schema	`config/auth_schema.py`	`AuthConfig`

config/schema.py 作为聚合入口点 re-export 所有符号，并保留 ProxyConfig 顶层模型及旧格式迁移逻辑。

2. 配置搜索优先级

config/loader.py 按以下顺序搜索配置文件：

flowchart TD
    A["CLI --config 参数<br/>（显式指定）"] -->|"未指定"| B["./config.yaml<br/>（项目根目录）"]
    B -->|"不存在"| C["~/.coding-proxy/config.yaml<br/>（用户目录）"]
    C -->|"不存在"| D["Pydantic 默认值"]

    style A fill:#1a5276,color:#fff
    style D fill:#7b241c,color:#fff

环境变量展开：语法 ${VARIABLE_NAME}，递归处理 dict/list/str，未定义变量保留原文。

3. 服务器配置

3.1 ServerConfig

字段	类型	默认值	说明
`host`	str	`"127.0.0.1"`	监听地址
`port`	int	`3392`	监听端口

3.2 DatabaseConfig

字段	类型	默认值	说明
`path`	str	`"~/.coding-proxy/usage.db"`	SQLite 数据库文件路径
`compat_state_path`	str	`"~/.coding-proxy/compat.db"`	兼容性会话存储路径
`compat_state_ttl_seconds`	int	`86400`	兼容性会话 TTL（秒）

3.3 LoggingConfig

字段	类型	默认值	说明
`level`	str	`"INFO"`	控制台日志级别
`file`	str \| null	`null`	文件日志路径（`null` 时输出到控制台）
`max_bytes`	int	`5242880`	单个日志文件最大字节数（5 MB），触发轮转
`backup_count`	int	`5`	保留的已压缩备份文件数

3.4 AuthConfig

字段	类型	默认值	说明
`token_store_path`	str	`""`	Token Store 文件路径（空则使用默认）

4. VendorConfig 通用字段

字段	类型	默认值	说明
`vendor`	enum	--	供应商类型：`anthropic` / `copilot` / `antigravity` / `zhipu` / `minimax` / `kimi` / `doubao` / `xiaomi` / `alibaba`
`enabled`	bool	`true`	是否启用
`base_url`	str	`""`	API 基础 URL（留空使用各供应商默认值）
`timeout_ms`	int	`300000`	请求超时（毫秒）

5. VendorConfig 弹性字段

字段	类型	默认值	说明
`circuit_breaker`	config \| None	`None`	熔断器配置（None = 终端层）
`retry`	config	`RetryConfig()`	重试策略配置
`quota_guard`	config	`QuotaGuardConfig()`	日度配额守卫配置
`weekly_quota_guard`	config	`QuotaGuardConfig()`	周度配额守卫配置
`concurrency`	config \| None	`None`	`[zhipu]` 每模型并发限制（详见 5.5）

5.1 CircuitBreakerConfig — 熔断器参数

设计语义：参见设计模式 -- Circuit Breaker

字段	类型	默认值	说明
`failure_threshold`	int	`3`	触发 OPEN 的连续失败次数
`recovery_timeout_seconds`	int	`300`	OPEN → HALF_OPEN 等待秒数
`success_threshold`	int	`2`	HALF_OPEN → CLOSED 所需连续成功数
`max_recovery_seconds`	int	`3600`	指数退避最大恢复时间（秒）

5.2 QuotaGuardConfig — 配额守卫参数

设计语义：参见设计模式 -- QuotaGuard State Machine

字段	类型	默认值	说明
`enabled`	bool	`false`	是否启用配额守卫
`token_budget`	int	`0`	滑动窗口内的 Token 预算上限
`window_hours`	float	`5.0`	滑动窗口大小（小时）
`threshold_percent`	float	`99.0`	触发 QUOTA_EXCEEDED 的用量百分比阈值
`probe_interval_seconds`	int	`300`	QUOTA_EXCEEDED 状态下探测间隔（秒）

5.3 RetryConfig — 重试策略参数

设计语义：参见设计模式 -- Retry with Full Jitter

字段	类型	默认值	说明
`max_retries`	int	`2`	最大重试次数
`initial_delay_ms`	int	`500`	初始延迟（毫秒）
`max_delay_ms`	int	`5000`	最大延迟（毫秒）
`backoff_multiplier`	float	`2.0`	退避倍数
`jitter`	bool	`true`	是否启用抖动

5.4 FailoverConfig — 故障转移参数

设计语义：参见请求生命周期 -- 故障转移判定

字段	类型	默认值
`status_codes`	list[int]	`[429, 403, 503, 500, 529]`
`error_types`	list[str]	`["rate_limit_error", "overloaded_error", "api_error"]`
`error_message_patterns`	list[str]	`["quota", "limit exceeded", "usage cap", "capacity", "internal network failure"]`

5.5 ZhipuConcurrencyConfig — Zhipu 每模型并发参数

仅对 vendor: zhipu 生效，基于 asyncio.Semaphore 实现 FIFO 公平排队。

字段	类型	默认值	说明
`default`	int	`3`	全局默认并行度（适用于所有未在 `models` 中显式覆盖的模型）；取值范围 `[1, 20]`
`models`	map[str → int]	`{}`	按映射后模型名（如 `glm-5v-turbo` / `glm-5.1` / `glm-4.5-air`）自定义并行度上限

YAML 示例：

- vendor: zhipu
  concurrency:
    default: 3
    models:
      glm-5v-turbo: 5
      glm-5.1: 2

行为语义：

信号量按映射后模型名键控，与上游真实承载模型对齐；流式与非流式请求共用同一槽位。
槽位满时新请求按 FIFO 顺序排队，直到任一在途请求释放槽位才被唤醒。
429 重试期间持续占用槽位（重试视为同一请求的延续）。
顶层 concurrency 字段缺省为 None → 转发至 ZhipuConfig 时回退默认值 default=3；如需完全关闭限流，可在 ZhipuConfig 构造层显式置 null（一般无需操作）。

6. 供应商专属字段

6.1 Copilot 专属字段

字段	类型	默认值	说明
`github_token`	str	`""`	GitHub OAuth token / PAT（支持 `${ENV_VAR}`）
`account_type`	str	`"individual"`	账号类型：`individual` / `business` / `enterprise`
`token_url`	str	`"https://..."`	Token 交换端点
`models_cache_ttl_seconds`	int	`300`	模型列表缓存 TTL

6.2 Antigravity 专属字段

字段	类型	默认值	说明
`client_id`	str	`""`	Google OAuth2 Client ID
`client_secret`	str	`""`	Google OAuth2 Client Secret
`refresh_token`	str	`""`	Google OAuth2 Refresh Token
`model_endpoint`	str	`"models/claude-sonnet-4-20250514"`	Gemini 模型端点路径

6.3 原生 Anthropic 兼容供应商共用字段

适用于 zhipu / minimax / kimi / doubao / xiaomi / alibaba。

字段	类型	默认值	说明
`api_key`	str	`""`	API Key（支持 `${ENV_VAR}`）

7. 模型映射规则

7.1 ModelMappingRule 字段

字段	类型	说明
`pattern`	str	匹配模式（精确/通配符/正则）
`target`	str	目标模型名称
`is_regex`	bool	是否为正则表达式（默认 `false`）
`vendors`	list[str]	规则作用域（留空应用于所有原生兼容供应商）

7.2 ModelPricingEntry 字段

字段	类型	说明
`vendor`	str	供应商名称
`model`	str	实际模型名
`input_cost_per_mtok`	float	输入 Token 单价（$/百万 token，支持 `$`/`¥` 前缀）
`output_cost_per_mtok`	float	输出 Token 单价
`cache_write_cost_per_mtok`	float	缓存创建 Token 单价
`cache_read_cost_per_mtok`	float	缓存读取 Token 单价

8. tiers — 显式优先级

字段	类型	说明
`tiers`	list[VendorType] \| None	降级链路优先级（None 时回退 vendors 顺序）

9. vendors 列表格式（推荐）

推荐使用 vendors 列表格式，每个 vendor 自包含其弹性配置：

vendors:
  - vendor: anthropic
    enabled: true
    base_url: https://api.anthropic.com
    timeout_ms: 300000
    circuit_breaker:
      failure_threshold: 3
      recovery_timeout_seconds: 300
    quota_guard:
      enabled: false
    weekly_quota_guard:
      enabled: false

  - vendor: copilot
    enabled: false
    github_token: "${GITHUB_TOKEN}"
    account_type: individual
    circuit_breaker:
      failure_threshold: 3
    quota_guard:
      enabled: true
      token_budget: 3000000
      window_hours: 4.0

  - vendor: zhipu
    enabled: true
    api_key: "${ZHIPU_API_KEY}"
    # 无 circuit_breaker -> 终端层

  - vendor: minimax
    enabled: false
    api_key: "${MINIMAX_API_KEY}"

tiers: [anthropic, copilot, zhipu]  # 显式优先级（可选）

Legacy Flat 格式（向后兼容）

旧的 flat 格式字段（primary/copilot/antigravity/fallback/circuit_breaker/*_quota_guard）仍受支持，通过 ProxyConfig._migrate_legacy_fields() 自动迁移为 vendors 列表格式。

迁移规则：

anthropic 字段名 → primary
zhipu 字段名 → fallback
若无 vendors 字段，从 legacy flat 字段自动生成 vendors 列表
迁移时发出 INFO 日志建议迁移至新格式

10. native_api — 原生 API 透传配置

定义位置：native_api/config.py

端点：/api/{openai,gemini,anthropic}/** catch-all 透传通道；认证头由客户端自带，proxy 不保管凭据。

10.1 NativeApiConfig 顶层字段

字段	类型	默认值	说明
`openai`	`NativeProviderConfig`	内置官方 URL，`enabled=true`	OpenAI chat / responses / embeddings 等
`gemini`	`NativeProviderConfig`	内置官方 URL，`enabled=true`	Gemini generateContent / embedContent 等
`anthropic`	`NativeProviderConfig`	内置官方 URL，`enabled=true`	Anthropic messages / count_tokens / batches

10.2 NativeProviderConfig 字段

字段	类型	默认值	说明
`enabled`	bool	`true`	是否启用该 provider 的原生透传端点（默认启用，开箱即用）
`base_url`	str	见下方内置默认	上游 API base_url（纯域名前缀，不含 `/v1`）
`timeout_ms`	int	`300000`	单次请求超时（毫秒），LLM 大模型建议 ≥ 120s
`connect_timeout_ms`	int	`15000`	连接建立超时（毫秒）

10.3 内置默认 `base_url`

Provider	内置默认
`openai`	`https://api.openai.com`
`gemini`	`https://generativelanguage.googleapis.com`
`anthropic`	`https://api.anthropic.com`

10.4 `base_url` 三级覆写优先级

由 NativeApiConfig._apply_env_overrides @model_validator(mode="after") 注入：

env var（运行时） > YAML 显式字段（部署时） > Pydantic 内置默认（兜底）

环境变量	覆写目标
`NATIVE_OPENAI_BASE_URL`	`openai.base_url`
`NATIVE_GEMINI_BASE_URL`	`gemini.base_url`
`NATIVE_ANTHROPIC_BASE_URL`	`anthropic.base_url`

空串或纯空白视作未设置，保留上一层值（避免"未设置 env → 空串覆盖内置默认"陷阱）。

ANTHROPIC_BASE_URL（client → proxy，Claude Code 使用）与 NATIVE_ANTHROPIC_BASE_URL（proxy → upstream，原生透传使用）方向正交，勿混用。参见用户指引 § 4.7 native_api。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

配置字段参考

1. 配置模块结构

2. 配置搜索优先级

3. 服务器配置

3.1 ServerConfig

3.2 DatabaseConfig

3.3 LoggingConfig

3.4 AuthConfig

4. VendorConfig 通用字段

5. VendorConfig 弹性字段

5.1 CircuitBreakerConfig — 熔断器参数

5.2 QuotaGuardConfig — 配额守卫参数

5.3 RetryConfig — 重试策略参数

5.4 FailoverConfig — 故障转移参数

5.5 ZhipuConcurrencyConfig — Zhipu 每模型并发参数

6. 供应商专属字段

6.1 Copilot 专属字段

6.2 Antigravity 专属字段

6.3 原生 Anthropic 兼容供应商共用字段

7. 模型映射规则

7.1 ModelMappingRule 字段

7.2 ModelPricingEntry 字段

8. tiers — 显式优先级

9. vendors 列表格式（推荐）

Legacy Flat 格式（向后兼容）

10. native_api — 原生 API 透传配置

10.1 NativeApiConfig 顶层字段

10.2 NativeProviderConfig 字段

10.3 内置默认 `base_url`

10.4 `base_url` 三级覆写优先级

FilesExpand file tree

config-reference.md

Latest commit

History

config-reference.md

File metadata and controls

配置字段参考

1. 配置模块结构

2. 配置搜索优先级

3. 服务器配置

3.1 ServerConfig

3.2 DatabaseConfig

3.3 LoggingConfig

3.4 AuthConfig

4. VendorConfig 通用字段

5. VendorConfig 弹性字段

5.1 CircuitBreakerConfig — 熔断器参数

5.2 QuotaGuardConfig — 配额守卫参数

5.3 RetryConfig — 重试策略参数

5.4 FailoverConfig — 故障转移参数

5.5 ZhipuConcurrencyConfig — Zhipu 每模型并发参数

6. 供应商专属字段

6.1 Copilot 专属字段

6.2 Antigravity 专属字段

6.3 原生 Anthropic 兼容供应商共用字段

7. 模型映射规则

7.1 ModelMappingRule 字段

7.2 ModelPricingEntry 字段

8. tiers — 显式优先级

9. vendors 列表格式（推荐）

Legacy Flat 格式（向后兼容）

10. native_api — 原生 API 透传配置

10.1 NativeApiConfig 顶层字段

10.2 NativeProviderConfig 字段

10.3 内置默认 base_url

10.4 base_url 三级覆写优先级

10.3 内置默认 `base_url`

10.4 `base_url` 三级覆写优先级