配置模型、凭据与回退

在为 Agent 指定模型之前，先确保拥有可用的提供商连接。关于路由标识定义与回退机制，请参阅模型、提供商与路由。

前置条件

具备对目标 Holon 运行时的操作权限。
拥有模型提供商账号或本地模型推理服务。
具备修改共享配置的权限。全局默认配置与凭据会影响多个 Agent。

请在操作者终端中运行以下命令。切勿将敏感凭据直接粘贴至 Agent 对话、截图、执行日志或 Issue 报告中。

配置步骤

检查已注册的提供商与配置健康状态：
```
holon config providers list
holon config doctor
```
若需交互式配置（包括支持 OAuth 或设备登录的服务商）：
```
holon onboard
```
根据向导完成所选服务商的配置。若使用 API Key，建议通过标准输入保存，再将配置 Profile 关联至提供商。以下以内置的 deepseek 提供商为例：
```
holon config credentials set --kind api_key --stdin deepseek
```
输入 Key 并按 Ctrl+D 结束输入，随后执行关联命令：
```
holon config set providers.deepseek.auth.source credential_profile
holon config set providers.deepseek.auth.profile deepseek
holon config set providers.deepseek.auth.kind api_key
```
Profile 名称属于自定义标识，不会自动映射到同名提供商。另外，也可以在启动守护进程的环境中直接注入对应的环境变量；而在独立的客户端终端中 export 环境变量并不会影响已在后台运行的守护进程。切勿在共享命令历史中使用 --material 传递明文密钥。
认证完成后列出可用模型：
```
holon config models list
```
从输出中选择可用的交互路由。标准路由格式为 provider@endpoint/model，例如 deepseek@default/deepseek-v4-pro。实际可用性仍取决于你的账号权限、网络端点与配置情况。
将选定的路由设为全局默认：
```
holon config set model.default "deepseek@default/deepseek-v4-pro"
holon config get model.default
```
若要为某个已有 Agent 单独覆盖配置：
```
holon agent model set "anthropic@default/claude-sonnet-4-6" reviewer
holon agent model get reviewer
```
请使用当前环境中真实可用的路由；上述两个示例需要不同的提供商连接。执行 holon agent model clear reviewer 可清除单独覆盖，让该 Agent 恢复使用全局默认配置。
配置回退策略：
```
# 自动回退：每个已认证提供商自动挑选一个首选路由
holon config set model.fallbacks '["auto"]'

# 或显式指定一组已完成认证的有序回退路由
holon config set model.fallbacks '["anthropic@default/claude-sonnet-4-6"]'
```
仅保留你打算使用的回退策略。Agent 级别的覆盖仅替换主路由，全局默认不会隐式作为回退追加在末尾。未配置或为空时系统使用自动回退。若要强制限定单一路由并完全禁用回退，可执行：
```
holon config set runtime.disable_provider_fallback true
```
该设置为全局生效。需要恢复回退时将其重置为 false。在启用附加提供商前，请确认提示词可能发送到的第三方范围。
留意命令在 stderr 输出的提示。部分持久化改动可能需要重启守护进程才能生效。若有提示，等待当前活跃工作平稳结束后，按标准流程重启守护进程。随后发起单次测试：
```
holon config doctor
holon run --agent reviewer "用一句话输出问候语。不要使用任何工具，不要修改任何文件。"
holon agent get reviewer --detail full
holon transcript --agent reviewer --limit 20
```

确认配置生效

模型列表与 doctor 报告应当显示主路由可用。测试请求会返回一段简短回复。在 Agent 详情中，检查 model.requested_model、model.active_model 以及 model.fallback_active（若存在），并对照对话记录中的提供商元数据。这有助于分清所请求的偏好路由与发生回退后实际使用的路由。切勿单凭模型在自然语言回复中的自我介绍来判断。

本地或自定义端点

若使用本地 Ollama 服务，先在 Ollama 中拉取模型，然后选择其可用路由（例如 ollama@default/<installed-model>）。对于默认的本机 Ollama 服务，无需配置 API Key。

若配置自定义提供商，请使用专用管理命令：

holon config providers set my-proxy \
  --transport openai_chat_completions \
  --base-url "https://my-proxy.example.com/v1" \
  --credential-source env \
  --credential-env MY_PROXY_API_KEY \
  --credential-kind api_key

替换端点并在守护进程环境中配置凭据。在正式选用前先执行 holon config models list 检查。端点、计划与模型元数据字段详见配置参考。

单独配置图像工具

挑选支持对应能力且守护进程已具备访问凭据的路由。例如，在配置好对应提供商后：

holon config set vision.default "anthropic@default/claude-sonnet-4-6"
holon config set image_generation.default "openai@default/gpt-image-2"
holon config get vision.default
holon config get image_generation.default

这些设置不会影响日常对话模型。遵循可能出现的重启提示，随后使用无害的本地图像测试图像观察，或发送简单请求测试图像生成。重点检查工具的实际返回结果与提供商选择，而非仅看存储的配置。图像生成可能会产生第三方服务费用。

若未显式指定专用路由，工具将按内置发现规则运作。能力与传输协议要求详见视觉模型选择与生图路由。单纯文本对话能够正常运行，不能证明图像工具已经就绪。

故障排查

凭据缺失或过期： 针对 OAuth 重新运行 holon onboard，或通过标准输入更新凭据 Profile。检查该提供商配置的凭据来源。
路由未知或不可用： 从模型列表中复制完整路由标识，并检查端点与账号权限。元数据声明并不会自动为账号开通模型权限。
命中了非预期的提供商： 检查 Agent 覆盖设置、回退策略以及实际的执行元数据，评估是否需要全局禁用回退。
存储的配置与运行时表现不一致： 查看 stderr 中的生效途径说明或重启提示。避免重复写入同一个配置键。
自定义编目修改报错： models.catalog 属于对象值。添加单条覆盖时务必保留不相关的现有项，避免误用单项字典覆盖整个映射表。

关于仅用于非权威建议的决策模型配置，请参阅配置咨询决策。