2. 快速开始

本章会带你在大约 10 分钟内从零开始,得到一个能正常工作的智能体。你会安装 CLI、启动本地网关、创建一个智能体、发出第一条消息,并学会日常会用到的三四个命令。

2.1 前置条件

你需要:

  • Node.js 20 或更新 —— 用 node --version 检查。
  • 一个 PostgreSQL 数据库 —— 本地 Postgres、Docker Postgres,或托管的 Postgres URL 都行。
  • 至少一个模型供应商的 API key —— Anthropic、OpenAI 或 OpenRouter。

如果手边没有 Postgres,仓库根目录的 docker-compose.yml 可以拉起一个:

docker compose up -d postgres

2.2 安装 CLI

npm install -g openhermit

这会安装 hermit 命令。确认它能用:

hermit --version

2.3 运行 Setup Wizard

最快的方式是交互式向导。它会一次性引导你配置数据库 URL、模型供应商和第一个智能体。

hermit setup

向导会询问下面这些信息:

  • Postgres URL —— 例如 postgres://postgres:postgres@localhost:5432/openhermit。
  • 供应商 —— anthropic、openrouter 或 openai。
  • API key —— 粘贴你从供应商那里得到的 key。
  • 第一个智能体 ID —— 取一个简短的名字,比如 main。

向导会创建网关配置、执行数据库迁移、并在后台启动网关。

2.4 验证安装

hermit doctor

doctor 会检查:网关是否运行、数据库能否连通、API key 是否生效、智能体是否注册成功。如果它报错,错误信息会告诉你哪个环节出了问题。

hermit status

status 给你一屏概览:有哪些智能体、各自是否启用、连接了哪些通道。

2.5 发送第一条消息

两种方式。

从终端 —— 打开交互式聊天:

hermit chat --agent main

你会看到一个提示符。输入消息并按回车,智能体会以流式方式回复。

从 Web 界面 —— 启动 Web 服务:

hermit web start

它会显示一个 URL(默认 http://localhost:4310)。在浏览器打开,选中你的智能体,开始聊。网关本身监听在 http://localhost:4000。

两种方式下,对话都会作为一个 会话(session) 持久化,重启后依然存在。

2.6 最常用的五条命令

下面这些命令今天就值得记住:

命令用途
hermit status智能体、通道、网关状态的一屏概览。
hermit chat --agent <id>打开与某个智能体的交互式聊天。
hermit logs -f跟踪网关日志;卡住时很有用。
hermit config show --agent <id>打印某个智能体当前的配置。
hermit agents list列出本实例中的所有智能体。

完整命令参考:第 19 章 · CLI 速查表。

2.7 接下来

你已经有了一个能跑的智能体。常见的下一步: