引导配置

holon onboard 是配置 Holon 最快的方式。它会启动一个交互式终端 UI 向导，带你完成提供商选择、凭据录入、模型选择和搜索配置，并把结果写入 Holon 配置和凭据存储。

什么时候用引导配置

首次安装 — 你刚安装 Holon，需要在创建 Agent 前配置模型提供商。
切换提供商 — 你想更换默认提供商或模型，且偏好引导式流程而非手工编辑配置。
凭据修复 — 已保存的凭据过期或失效，Holon 检测到需要处理。

快速开始

holon onboard

这会启动交互式 TUI。完成后你就拥有可用的默认模型配置——不需要手动编辑配置文件。

引导流程

向导共五步。用方向键导航，回车选择，Esc 返回。每一步确认后才进入下一步。

1. 选择提供商

从内置列表中选择你的模型提供商：

Anthropic — 通过 Anthropic Messages API 使用 Claude 模型（API key）
OpenAI — 通过 OpenAI API 使用 GPT 和 o 系列模型（API key）
OpenAI Codex — Codex 托管模型（浏览器 OAuth 登录）
DeepSeek — DeepSeek 模型（API key）
Gemini — Google Gemini 模型（API key）
自定义提供商 — 任何 OpenAI 兼容端点

向导只显示尚未配置的提供商。如果已经配置了一个提供商并想切换，向导会把它作为更新候选显示。

2. 录入凭据

凭据步骤取决于提供商：

API key 提供商 — 输入 key。输入不会回显到屏幕，也不会以明文存进配置文件。
OpenAI Codex（OAuth） — 向导打开浏览器完成 OAuth 登录，然后自动捕获凭据。
免凭据提供商 — 跳过；直接完成配置，无需认证。

凭据保存在 ~/.holon/credentials.json 的 Holon 凭据存储中，而不是 config.json。这样密钥不会出现在配置文件和 shell 历史里。该存储是单个加密的 JSON 文件。

3. 选择模型

选择默认模型。向导列出该提供商的常用模型并附简短说明。如果列表中没有你想要的，也可以直接输入自定义模型 ID。

选中的可执行路由会以规范的 provider@endpoint/model 形式写入 model.default。之后可以按 Agent 覆盖（holon agent model set）；旧的 provider/model 写法仍然接受。

4. 搜索配置

Holon Agent 可以把 WebSearch 作为内置工具使用。向导提供三种搜索模式：

模式	行为
禁用	不提供网页搜索能力
自动	优先使用模型原生搜索（如可用），否则回退到托管 DuckDuckGo
托管（DuckDuckGo）	使用 Holon 内置的 DuckDuckGo 搜索提供商

搜索配置之后可以用 holon config set 修改。

5. 确认并应用

应用之前，向导会展示所有选择的摘要。确认后写入配置和凭据存储。完成后 Holon 会打印确认摘要。

引导完成之后

引导完成后，Holon 配置即可使用：

# 检查配置
holon config doctor

# 查看默认模型
holon config get model.default

# 启动 daemon 并创建第一个 Agent
holon daemon start
holon agent create my-first-agent

完整流程见创建你的第一个 Agent。

凭据修复

如果已保存的凭据失效——例如 API key 过期或 OAuth token 被撤销——Holon 会在启动时检测到，并建议重新运行引导：

holon onboard

向导会显示哪个提供商的凭据有问题，并引导你更新。其他提供商的已有配置不受影响。

当凭据修复针对的是已配置的提供商时，向导在覆盖前会要求确认——它会显示受影响的提供商并请你确认更新。

非交互式诊断

如果不想进入交互式向导，只想查看引导状态，使用 --json：

holon onboard --json

这会打印机器可读的引导报告，包含每部分的状态：

configured — 已配置且工作正常
missing — 尚未配置
unavailable — 提供商不可达
restricted — 部分配置完成，需要处理
skipped — 有意跳过或不适用
failed — 配置尝试失败，需要修复

每部分包含 summary 字符串、可选的 details，以及带建议 CLI 命令的 actions。

配置文件

文件	用途
`~/.holon/config.json`	提供商定义、模型默认值、搜索设置
`~/.holon/credentials.json`	加密的凭据配置（API key、OAuth token）

引导配置会写入这两个文件。不要直接编辑凭据文件；请使用 holon onboard 或 holon config credentials。

CLI 参考

holon onboard [--json]

标志	说明
`--json`	以 JSON 打印引导诊断并退出（非交互）