模型与服务商

普通对话默认走一条主 Provider/Model 路由。你还可以按顺序设置文本 Fallback，让某个 Session 独立选择模型，并为图片、视频和语音配置专用路由。

选择配置入口

目标	推荐入口
设置一个服务商和主模型	anyy setup model
可视化管理全部模型路由	Dashboard → Models
新增或调整 Fallback	anyy setup model fallback 或 Dashboard → Models
核对实际路径与凭据状态	anyy config
只切换当前会话	Dashboard Chat 选择器或 TUI /model

第一次配置时，交互向导最直接：

anyy setup model

一条可用路由包含什么

1. Provider：Anyy 对接的服务系列；
2. Endpoint 与 Protocol：实际请求使用的 API 契约和 Base URL；
3. Authentication：API Key、支持的订阅登录，或可信本地服务的免 Key 连接；
4. Model：发给这个 Endpoint 的准确模型 ID。

哪些组合有效，由当前版本内置的 Provider Catalog 决定。模型名字相同，不代表可以放到任意协议或 Endpoint 下使用。

本地模型服务

先启动 Ollama 或 LM Studio，再从设置流程中选择。发现不到模型时，检查服务地址，并确认本地至少已经安装一个模型。

Compatible Endpoint

只有目标服务真正实现相应协议时，才选择 OpenAI-compatible 或 Anthropic-compatible。填写服务商要求的完整 Base URL 和准确模型 ID。

选择 Provider 就是在选择数据去向

服务商可能收到完成请求所需的提示词、上下文、附件和工具结果。配置前应了解其隐私、留存、账号和计费规则。

在 Dashboard 设置主模型

进入 Dashboard → Models → Main model：

Text、Image、Video 与 Voice 卡片会显示当前 Provider/Model，以及 Primary、Enabled、Disabled 或 Unavailable 状态。

1. 选择 Provider 类型；
2. 有多个选项时，继续选择 Service 与 Protocol；
3. 选择认证方式；
4. 填写 API Key，或完成支持的订阅登录；
5. 保留默认 Base URL，或填写可信兼容服务地址；
6. 刷新模型目录，必要时改为手动输入；
7. 选择模型和默认推理等级；
8. 点击 Test connection，通过后再 Save。

保存前的预览只展示非敏感配置；已经保存的 API Key 不会完整回显。

每次换连接要素后都重新测试

Provider、Endpoint、Protocol、凭据或 Model 任一项变化，都应重新执行 Test。配置里写着一个模型 ID，不代表服务端会接受真实请求。

终端流程：

anyy setup model
anyy config
anyy status

anyy config 会显示 Provider、Model、Endpoint、配置路径和凭据引用状态，但不会打印秘密明文。

后台刷新模型能力

Gateway 启动后会在后台尽力刷新模型能力元数据。若当前配置模型的 Provider Catalog 缓存仍在 24 小时有效期内，就不会重复请求该服务商；按已配置服务商筛选的 models.dev 元数据也使用 24 小时缓存。

刷新可能访问服务商的 Models Endpoint；该接口需要认证时会使用已经解析的凭据。Anyy 也可能从 models.dev 获取模型元数据。这个过程不会发送对话内容，也不是模型推理请求。刷新失败不会阻止 Gateway 启动，运行时会继续使用可用的缓存或随版本提供的数据。

需要立即核对目录时，在 Dashboard 主动选择 Refresh models，不必重启 Gateway。

认证与凭据

根据 Provider 能力，Dashboard 可以：

• 新增、替换或清除 API Key；
• 发起或重复 OAuth/订阅登录；
• 断开已经连接的订阅账号。

认证与当前 Provider Endpoint 绑定。切换 Service 或 Protocol 后，凭据范围和可发现的模型目录也可能改变。

Anyy 托管的凭据位于 <PROFILE_HOME>/secrets/，文件权限为 0600；config.yaml 只保存引用及非敏感路由信息。Key 不应进入提示词、Shell 历史、截图或 Issue。

设置 Fallback

从 Dashboard 的 Text 页面添加，或运行：

anyy setup model fallback

Fallback 按保存顺序尝试。每条路由都可以单独启用/停用，并控制：

• 是否允许降低推理能力；
• 是否允许使用更小的上下文窗口；
• 最多尝试多少次。

不再需要某条 Fallback 时，从它的详情页移除。

Fallback 是可用性路由，不会同时询问所有模型，也不会合并多个回答。

一次逻辑 Turn 仍可能对应多个物理请求：Anyy 可能重试临时故障、处理 Context Limit、刷新认证，或切换到兼容的 Fallback。失败路由还可能进入 Cooldown，让后续 Turn 直接从可用 Fallback 开始，而不是反复请求同一故障目标。这些尝试会增加延迟，也可能增加 Token 与服务商费用；排查时查看 Chat 的 Usage 与 Runtime Status。

真正需要冗余时，应使用相互独立的服务和凭据。同一 Endpoint 下配置两个模型，无法应对整个 Endpoint 宕机。

切换当前会话

主模型配置决定新会话默认值；已经存在的 Session 可以继续保留自己的 Provider、Model 和 Reasoning 状态。

Dashboard Chat 使用顶部模型/推理控件；TUI 使用：

/model
/provider
/effort

大幅切换模型或推理方式后，希望上下文干净时新建会话。切换 Effort 可能让 Prompt Cache 失效，增加输入 Token 费用。

图片与视频路由

Models 页面按 Text / Image / Video / Voice 分类。

只有 Catalog 明确声明支持对应输入时，主模型才能自动处理图片或视频；否则需要专用模型。理解路由还可以设置：

• 是否启用；
• auto 或 summary_first；
• Capability Prompt；
• Token/字符上限；
• Timeout；
• Thinking 行为。

summary_first 必须配置专用路由。手动填写的未知模型 ID 也应真实测试，Anyy 不会默认它支持媒体输入。

图片生成是另一条输出路由，拥有自己的 Provider/Model、默认宽高比、Timeout 和字节限制。用法见媒体理解与图像生成。

语音路由

Voice 页面包含：

• TTS：Provider、Model、Protocol、Voice、输出行为与试听；
• STT：Provider、Model、Protocol、默认语言与连接测试。

文本模型可用，不代表该 Provider 一定支持语音 Endpoint。只启用已经完成真实测试的路由。更多用法见语音与听写。

配置何时生效

Dashboard 通过正在运行的 Gateway 保存配置。新会话使用新的主模型；旧会话可能继续保留自己的选择。启用新的能力路由后，相关工具也可能需要新建会话才会出现。

常见问题

现象	处理方法
模型目录为空	检查认证和 Base URL，再点击 Refresh models
Test connection 失败	核对 Endpoint、凭据范围、Model ID 和账号权限
主模型显示不可用	打开详情，测试并保存一条有效路由
本地连接被拒绝	启动 Ollama/LM Studio，并核对地址
Fallback 没起作用	分别测试每条路由，确认启用状态和顺序
图片/视频要求专用模型	主模型没有声明能力，或选择了 summary_first
Chat 中没有刚保存的模型	在当前 Session 明确切换，或新建 Session
订阅登录过期	重新认证，或断开后连接正确账号
费用或延迟异常	核对 Provider、Model、Effort、Fallback 次数和媒体路由