Provider 配置参考

本页是模型 Provider 配置字段的紧凑参考。Provider setup、profile id、alias、自定义 endpoint 和运行检查见 Provider 集成。主模型、辅助模型和 fallback 路由流程见 配置模型。

Anyy 从 config.yaml 读取 Provider 配置，严格校验未知 YAML 字段，然后把 主模型的简写形式和结构化形式归一化为同一个运行时视图。

最小结构

providers:
  - id: openrouter
    profile: openrouter
    credential_ref: env:OPENROUTER_API_KEY
    default_model: anthropic/claude-sonnet-4

default_model: openrouter/anthropic/claude-sonnet-4
main_model:
  provider_id: openrouter
  model: anthropic/claude-sonnet-4

default_model 是 provider/model 简写。main_model 是结构化形式。手写配置时二选一即可； 只要 provider 和 model 都存在，Anyy 会在加载时补齐另一种形式。

主模型字段

字段	类型	含义
default_model	string	provider_id/model_id 简写。配置了 providers 时，provider id 必须存在。
main_model.provider_id	string	普通聊天和工具轮次使用的 Provider id。
main_model.model	string	传给该 Provider 的模型 id。

如果两种形式都存在，请保持一致。设置向导会同时写入两种形式，方便命令、Dashboard 和旧配置读取逻辑看到同一个主模型。

Provider 条目

providers 下的每一项定义一个后端连接。

字段	类型	含义
id	string	必填，唯一 Provider id；也是 default_model 的前缀。
profile	string	可选的内置 profile。省略时，Anyy 可从已知 Provider id 推断。
api_mode	string	协议适配模式。没有 profile 提供默认值时必填。
auth_mode	string	认证方式。默认来自 profile；没有 profile 时默认为 api_key。
auth_profile	string	profile 有多种认证路径时，用来选择具体认证项。
base_url	string	Provider endpoint。没有 profile 默认 endpoint 时必填。
models_url	string	可选的模型目录 endpoint；支持时用于列出模型。
credential_ref	string	推荐使用的凭据引用；同时存在时覆盖 api_key_ref。
api_key_ref	string	兼容旧配置的 API key 引用；新配置优先用 credential_ref。
default_model	string	Provider 本地默认模型，供 setup/status 等界面展示。
models	list	可选的手工模型条目和单模型能力覆盖。
aliases	map	可选的模型别名映射。
auxiliary_models	map	可选的 Provider 本地辅助模型别名。
capabilities	map	Provider 级能力覆盖。
fallback_chain	list	Provider 本地 fallback 链。
enabled	bool	可选开关；省略表示启用。

未知字段会导致配置校验失败。Provider id 一旦被会话或配置引用，应尽量保持稳定。

API Modes

api_mode 必须是以下值之一：

值	用途
openai-compatible	OpenAI-compatible chat/completions endpoint，以及很多托管模型路由。
anthropic-messages	Anthropic Messages-compatible endpoint。
google-gemini	原生 Google Gemini API。
openai-responses	OpenAI Responses API。
codex-responses	openai-codex profile 使用的 Codex Responses 后端。

不要自创适配器名称。例如 DeepSeek 使用 openai-compatible；deepseek-compatible 会被拒绝。

Provider Profiles

Setup-ready profile id、profile alias、blocked setup entry、自定义 endpoint 形态和 auth-mode 指引统一见 Provider 集成。

本 reference 只聚焦在选定 provider 形态后，YAML 接受哪些字段。

凭据

Provider 凭据引用使用 secret 系统的引用形式：env:NAME、file:/path/to/token 或 secret:name。Provider 凭据字段不允许写 literal 凭据。

credential_ref 是推荐字段。若同时存在 credential_ref 和 api_key_ref，Anyy 使用 credential_ref 作为有效凭据，并继续校验旧的 api_key_ref。

认证方式规则：

auth_mode	凭据规则
api_key	使用 credential_ref 或 api_key_ref。
oauth	需要引用凭据时用 credential_ref；api_key_ref 会被拒绝。
external_process	需要引用凭据时用 credential_ref；api_key_ref 会被拒绝。
aws_sdk	需要引用凭据时用 credential_ref；api_key_ref 会被拒绝。
none	不允许任何凭据引用，且 base URL 必须是本地或私网地址。

auth_mode: none 适用于本地或私有 Provider，例如本机 LM Studio endpoint。公共互联网 endpoint 不能使用该模式。

模型

手工模型条目是可选的。它适合 Provider 模型目录为空、需要友好显示名，或某个模型需要单独能力覆盖的场景。

providers:
  - id: local
    profile: lmstudio
    models:
      - id: local-model
        display_name: Local Model
        capabilities:
          tool_calls: true
          streaming: true
          max_context_tokens: 32768

models[].id 是传给 Provider 的模型 id。models[].capabilities 会覆盖或补充 Provider 级能力。

能力覆盖

能力字段是精确覆盖。想沿用内置 profile 或 Provider adapter 的判断时，请省略该字段。

布尔能力字段包括：

developer_messages, tool_choice_without_tools, streaming, tool_calls, json_schema, usage_metadata, multimodal_input, video_input, image_generation, reasoning_input, reasoning_output, reasoning_replay, reasoning_requires_same_provider, reasoning_requires_same_model, prompt_cache_explicit, prompt_cache_implicit, credential_refresh, credential_pool, account_scoped_rate_limits。

数值和字符串能力字段：

字段	含义
max_context_tokens	Anyy 应假定的最大上下文窗口。
max_output_tokens	Anyy 请求或允许的最大输出 tokens。
max_request_bytes	请求大小护栏。
max_tool_result_chars	Provider 兼容性需要的工具结果预算。
prompt_cache_ttl	支持 prompt cache 的 Provider 可使用的 TTL 标签。

负数 token 或输出限制会在校验时被拒绝。

辅助模型

辅助模型槽位在顶层配置，不写在 Provider 条目内部：

auxiliary_models:
  image_understanding:
    - provider_id: gemini
      model: gemini-2.5-flash
  video_understanding: []
  speech_synthesis: []
  search: []
  image_generation: []

可用槽位是 fallback、image_understanding、video_understanding、speech_synthesis、 search、image_generation。

每个条目接受：

字段	含义
provider_id	该辅助任务使用的 Provider id。
model	传给该 Provider 的模型 id。
enabled	可选开关；省略表示启用。
extra_body	支持时传给 Provider 的额外请求体字段。
allow_reasoning_drop	需要时允许 fallback 放弃 reasoning 连续性。
allow_context_drop	需要时允许 fallback 不带完整上下文重试。
max_attempts	该条目的重试限制。

当一边为空时，图片和视频辅助条目会和 media_understanding.image.models、 media_understanding.video.models 互相映射，保持新旧配置形状兼容。

Fallback 链

推荐的 setup 路径会把 fallback 模型写到 auxiliary_models.fallback：

auxiliary_models:
  fallback:
    - provider_id: openrouter
      model: anthropic/claude-sonnet-4
      max_attempts: 1
    - provider_id: gemini
      model: gemini-2.5-pro
      allow_reasoning_drop: true

运行时，如果主 Provider 没有显式 fallback_chain，Anyy 会把该列表复制为主 Provider 的有效 fallback 链。

Provider 本地 fallback_chain 使用同样字段。每个 provider_id 都必须指向已配置的 Provider，且 max_attempts 不能为负数。

Fallback 是容错路径，不是绕过能力要求的方式。如果候选模型无法满足必需的工具、媒体、上下文或 reasoning 连续性要求，仍可能被跳过。

校验与排查

手工编辑 config.yaml 后运行 anyy config。它会打印解析后的 Provider、API mode、 认证引用状态、模型和 max-turn 设置。

更广泛的运行时检查使用 anyy doctor。实际 Provider 请求失败仍会在模型被调用时暴露； config.yaml 里没有单独的 Provider health-check 配置块。