创建你的第一个 Agent

本指南带你从零创建第一个 Holon Agent。你将：

1. 安装 Holon
2. 启动运行时（单次执行与 daemon 模式）
3. 用 TUI 连接
4. 创建 Agent
5. 配置模型

耗时： 约 10 分钟（Homebrew）；约 15 分钟（源码构建）

前置条件

• Holon 已安装并在 PATH 上（见第 1 步）
• 一个模型提供商账号（Anthropic、OpenAI 或兼容服务）
• 基本的终端操作能力

第 1 步：安装 Holon

Holon v0.14.0 及以后版本以可安装发布形式分发。选择适合你的方式。

方式 A：Homebrew（推荐）

brew tap holon-run/tap
brew install holon

方式 B：直接下载二进制

从 GitHub Releases 页面 下载对应平台的最新二进制，放到 PATH 上：

# 示例：Linux amd64
curl -L https://github.com/holon-run/holon/releases/latest/download/holon-linux-amd64 -o holon
chmod +x holon
sudo mv holon /usr/local/bin/

可用平台：Linux amd64、macOS amd64、macOS arm64。

方式 C：源码构建

如果你偏好源码构建或打算给 Holon 做贡献：

git clone https://github.com/holon-run/holon.git
cd holon
cargo build --release

源码构建时，把下文示例中的 holon 命令替换为 cargo run --。例如 holon --help 变成 cargo run -- --help。

验证安装

holon --help

你应该看到带可用命令列表的 CLI 帮助输出。

第 2 步：启动 Holon 运行时

Holon 有两种运行模式：

• CLI 模式（默认）：单次命令，直接输出
• Daemon 模式：后台服务，支持 TUI

方式 A：CLI 模式（快速上手）

执行单条命令：

holon run "What is Holon?"

执行一轮后退出。适合快速任务，不适合交互式会话。

方式 B：Daemon 模式（Agent 场景推荐）

启动后台 daemon：

holon daemon start

这会把 Holon 作为后台服务启动，提供：

• Unix socket 位于 ~/.holon/run/holon.sock（本地访问）
• 供 TUI 和 HTTP 客户端使用的控制平面
• 跨会话的持久状态

验证 daemon 正在运行

holon daemon status

你应该看到包含默认 Agent 的运行时状态。

停止 daemon

holon daemon stop

第 3 步：用 TUI 连接

终端 UI（TUI） 提供与 Agent 协作的交互界面。

启动 TUI

holon tui

TUI 默认连接本地 Unix socket。

TUI 基础

TUI 界面包含：

• Agent 列表：当前 Agent 及其状态
• 活跃 Agent：正在接收你输入的 Agent
• 对话记录：会话历史
• 任务列表：后台任务和工作项

基本操作

• 输入消息后回车发送
• Ctrl+C 退出 TUI
• 方向键或 Page Up/Down 滚动历史

远程 TUI（可选）

连接远程 Holon 实例：

# 在远程主机上
holon serve --access lan --host 192.168.1.10 --token-file ~/.holon/remote.token

# 从本地机器
holon tui --connect http://192.168.1.10:7878 --token-file ~/.holon/remote.token

详见 Remote TUI Access RFC（英文）。

第 4 步：创建 Agent

Holon 支持面向不同用途的多种 Agent 类型。

默认 Agent

启动 Holon 时，它会自动在 ~/.holon/agents/main/ 创建一个默认 Agent。该 Agent：

• 拥有自己的 agent_home 和 AGENTS.md
• 可以有 Agent 本地 skills
• 保存会话历史和工作状态

创建命名 Agent

为特定角色创建专门化 Agent：

holon agent create reviewer

这会在 ~/.holon/agents/reviewer/ 创建一个使用默认角色契约初始化的新 Agent。

使用模板

模板提供可复用的 Agent 配置：

# 用已安装或已同步的模板 ID
holon agent create docs-helper --template holon-developer

# 用本地模板路径
holon agent create custom --template /path/to/template

# 用 GitHub 模板 URL
holon agent create github-agent --template https://github.com/owner/repo/tree/main/template-path

列出 Agent

holon agent list

在 TUI 中切换 Agent

在 TUI 中，通过 Agent 列表视图切换 Agent。

第 5 步：配置模型

推荐：用 holon onboard 快速配置

最快的配置方式是交互式引导向导：

holon onboard

在终端中，这会启动交互式 TUI，带你完成：

1. 选择提供商 — 从内置提供商（Anthropic、OpenAI、DeepSeek、Codex 等）或自定义提供商中选择
2. 录入凭据 — OpenAI Codex 走浏览器 OAuth 登录；其他提供商输入 API key （输入不会回显，也不会记入日志）
3. 选择模型 — 选择默认模型，或输入自定义模型 ID
4. 搜索配置 — 启用 DuckDuckGo 托管搜索、模型原生搜索，或保持禁用

holon onboard 会写入配置、安全保存凭据并打印摘要。这是首次配置的推荐路径。

手动配置（备选）

Holon 需要模型配置才能与 Anthropic、OpenAI 等提供商协作。

配置分层

Holon 使用三层配置：

1. 启动设置（环境变量、CLI 标志）
2. 运行时配置（config.json）
3. Agent 状态（按 Agent 覆盖）

详见 Runtime Configuration Surface RFC（英文）。

设置提供商凭据

方式 A：环境变量（快速上手）

# Anthropic
export ANTHROPIC_AUTH_TOKEN="your-api-key"

# OpenAI
export OPENAI_API_KEY="your-api-key"

方式 B：凭据存储（持久配置推荐）

安全保存凭据，避免暴露在 shell 历史或环境变量中：

holon config credentials set --kind api_key --stdin anthropic
# 粘贴你的 ANTHROPIC_AUTH_TOKEN 并回车

设置默认模型

holon config set model.default "anthropic@default/claude-sonnet-4-6"

Agent 级模型覆盖

单个 Agent 可以覆盖默认模型：

holon agent model set "anthropic@default/claude-sonnet-4-6" reviewer

Agent 模型覆盖的更多细节见配置参考（英文）。

验证模型配置

holon config get model.default
holon config doctor

查看可用模型：

holon config models list

下一步

你的第一个 Agent 已经跑起来了，接下来可以：

• 了解概念：阅读运行时模型（英文）和信任边界（英文）
• 试试示例：参见快速示例（英文）
• 构建集成：查看集成指南（英文）
• 参考文档：CLI 参考、HTTP 控制平面、配置参考（英文）

故障排查

daemon 启动失败

检查是否有其他实例在运行：

holon daemon status
holon daemon stop
holon daemon start

TUI 连接不上

确认 daemon 正在运行且 socket 存在：

ls ~/.holon/run/holon.sock
holon daemon status

模型错误

检查凭据：

echo $ANTHROPIC_AUTH_TOKEN
holon config get model.default

更多帮助见故障排查指南（英文）。