第三章：安装、初始化与首次对话

本章把”从零安装 → 选模型 → 第一次成功对话 → 排错”完整跑一遍。覆盖 Linux、macOS、WSL2、Termux（Android）、Nix 五种典型环境，并解释 hermes setup、hermes model、hermes config、hermes doctor 等关键命令。

3.1 系统要求

Hermes Agent 官方支持以下操作系统：

唯一硬性前置依赖只有 git。其它依赖（uv、Python 3.11、Node.js v22、ripgrep、ffmpeg）安装器会自动装好；模型上下文窗口要求 ≥ 64K tokens——绝大多数主流模型自然达标，本地模型需要在 llama.cpp（--ctx-size 65536）或 Ollama（-c 65536）侧设置。

3.2 一行命令安装

3.2.1 Linux / macOS / WSL2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

执行后安装器会：

1. 检测 / 装好 uv；
2. 用 uv 创建 Python 3.11 虚拟环境；
3. 装好 ripgrep、ffmpeg、Node.js v22；
4. 把仓库克隆到 ~/.hermes/hermes-agent/；
5. 在 ~/.hermes/hermes-agent/ 下执行 uv pip install -e ".[all]"；
6. 把 hermes 软链到 ~/.local/bin/hermes。

最后一步是让你 reload shell：

source ~/.bashrc      # 或 source ~/.zshrc
hermes                # 进入 TUI

安装目录布局

Root 模式适合多用户共享机器，每个用户依然在自己的 ~/.hermes/ 里维护身份与数据。

3.2.2 Android / Termux

Termux 上同一条命令即可，安装器自动识别：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

它会：用 Termux pkg 装系统依赖、用 python -m venv 建虚拟环境、自动 export ANDROID_API_LEVEL、用 pip 安装 .[termux] 子集（默认跳过尚未通过测试的浏览器和 WhatsApp 部分）。完整人工流程见官方 Termux Guide。

3.2.3 Native Windows

不支持。请装 WSL2，然后在 WSL 内执行 Linux 流程。

3.2.4 NixOS / Nix Flake

仓库根目录提供 flake.nix：

nix run github:NousResearch/hermes-agent

或在 NixOS configuration 中以 module 形式引入；详细见官方 getting-started/nix-setup.md。

3.2.5 开发者源码安装

为贡献者或希望从指定分支跑：

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./setup-hermes.sh    # 自动安装 uv、建 venv、装 .[all]、软链 ~/.local/bin/hermes
./hermes             # 直接跑（无需手动 source venv）

或全手工：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

pyproject.toml 提供如下 extra：all、voice、messaging、tts-premium、mcp、termux、dev。按需组合。

3.3 首次启动与 setup 向导

hermes setup

setup 是个完整的交互式向导，按顺序引导你：

1. 从 OpenClaw 迁移（若检测到 ~/.openclaw），可跳过；
2. 选 Provider —— 即第五章会展开的那张表（Nous Portal、OpenRouter、Anthropic、OpenAI、Z.AI/GLM、Kimi、MiniMax、DeepSeek、HuggingFace、自定义端点等）；
3. 填 API Key（或走 OAuth，比如 Nous Portal、Anthropic Max、Codex、GitHub Copilot、MiniMax OAuth）；
4. 选默认 personality（可后续 /personality 切换）；
5. 配置 toolset（默认按平台预设启用一组合理工具）；
6. 可选：要不要现在就配 Gateway（Telegram/Discord 等）。

完成后，setup 会把：

• 机密（Key/Token）写入 ~/.hermes/.env；
• 非机密配置写入 ~/.hermes/config.yaml。

如果你已经知道自己要什么、想跳过完整向导，可以单独跑：

hermes model            # 选 Provider 和模型
hermes tools            # 配每个平台启用哪些 toolset
hermes gateway setup    # 配消息平台
hermes config set       # 设置单个 key

3.4 第一条对话

hermes

进入 TUI 后随便说一句：

你好，给我列一下当前目录有哪些文件

正常情况下你会看到：

1. 一个状态行显示在用模型 / 上下文余量 / personality；
2. 一个”思考”动画（KawaiiSpinner）；
3. Agent 决定调用 terminal 工具运行 ls；
4. 工具结果以紧凑视图打出；
5. Agent 用自然语言总结结果。

如果它没动作（什么也没说），90% 的概率是模型 Key 没生效——下一节就是排错。

3.5 数据目录布局：~/.hermes/

所有用户级数据都在 $HERMES_HOME（默认 ~/.hermes/）下：

~/.hermes/
├── config.yaml             # 非机密配置
├── .env                    # 机密：API Key、Token、OAuth refresh token 等
├── SOUL.md                 # 人格/身份文件
├── memories/
│   ├── MEMORY.md           # 环境/约定记忆，约 800 token
│   └── USER.md             # 用户画像，约 500 token
├── skills/                 # 技能根目录
│   ├── plan/               # 内置：规划技能
│   ├── github-pr-workflow/ # 内置：GH PR 流
│   └── openclaw-imports/   # 从 OpenClaw 迁移过来的
├── hooks/                  # 网关 hooks（HOOK.yaml + handler.py）
├── plans/                  # /plan 技能输出位置
├── hermes.db               # SQLite：会话、任务、cron、轨迹
├── kanban.db               # SQLite：Kanban 任务
├── checkpoints/            # 文件改动 checkpoint 快照
├── plugins/                # 用户安装的插件
├── profiles/               # Profile 隔离目录（多份身份/配置）
├── logs/                   # 运行日志
└── hermes-agent/           # 源码（如果是用户级安装）

理解这套布局，后续做备份、迁移、Profile 切换都会非常顺手。

3.6 Profile：一台机器跑多个身份

许多用户希望在同一台机器上区分”工作 Hermes”和”个人 Hermes”，或区分”中国区 Kimi”和”国际 Anthropic”。Hermes 的解决方案是 Profile。

hermes profile list
hermes profile create work
hermes profile use work     # 后续命令都在 work profile 下
hermes profile use default  # 切回默认

Profile 会被 HERMES_HOME 与若干路径常量感知（hermes_constants.py），各 Profile 拥有独立的：config、记忆、技能、会话、cron、kanban、profile 进程锁。

也可以临时通过环境变量切：

HERMES_PROFILE=work hermes

更多见 user-guide/profiles.md。

3.7 几个关键 CLI 命令速查

hermes <subcmd> --help 几乎都有详细帮助。

3.8 配置文件 config.yaml 与 .env

Hermes 把”机密”和”普通配置”分开管理：

• ~/.hermes/.env（机密）：所有 API Key、OAuth Token、SSH key 路径；以 KEY=VALUE 格式存储，每行一条。
• ~/.hermes/config.yaml（非机密）：模型、toolset、UI 主题、cron、Gateway 等结构化配置。

最优雅的写入方式是用 hermes config set —— 它会自动判断该值是不是机密、写到正确文件：

hermes config set model anthropic/claude-opus-4.6   # → config.yaml
hermes config set terminal.backend docker           # → config.yaml
hermes config set OPENROUTER_API_KEY sk-or-...      # → .env

config.yaml 常见 key（节选，第五章详细展开）：

model: anthropic/claude-opus-4.6
auxiliary_model: openrouter/openai/gpt-5-mini
fallback_models:
  - openrouter/anthropic/claude-3.5-sonnet
  - openrouter/openai/gpt-5
terminal:
  backend: docker
  docker:
    image: ghcr.io/nousresearch/hermes-sandbox:latest
    read_only: true
toolsets:
  hermes-cli: [web, terminal, file, browser, vision, skills, memory, session_search, todo, clarify, code_execution, delegation, cronjob]
  hermes-telegram: [web, search, terminal, file, vision, skills, memory, todo, send_message]
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
hooks:
  pre_terminal: ~/.hermes/hooks/redact-secrets/handler.sh

3.9 升级：hermes update

hermes update          # 拉 main 并 uv pip install -e .[all]
hermes update --check  # 仅检查
hermes update --branch foo  # 切换分支

升级后建议：

hermes config check
hermes config migrate
hermes doctor

迁移会把老 schema 的 config.yaml 升级到新版本（保留你的所有自定义）。

3.10 排错：hermes doctor

hermes doctor 会逐项检查：

• Python / Node 版本；
• uv、ripgrep、ffmpeg 是否在 PATH；
• ~/.hermes/.env / config.yaml 是否可读、字段是否合法；
• 当前 Provider 的 Key 是否能成功 ping 接口；
• 模型上下文长度是否 ≥ 64K；
• 终端后端是否可用（docker daemon、ssh 通连、modal token 等）；
• Gateway 平台依赖是否齐全（如 discord.py[voice] for Discord VC）。

输出会逐条标红/标黄，并给出修复建议。如果你在 issues 里求助，附上 hermes doctor 的输出会大幅提升被回答的速度。

3.10.1 常见报错速查

3.11 从 OpenClaw 迁移

如果你之前在用 OpenClaw（Hermes 的前身）：

hermes claw migrate              # 交互式迁移（full 预设）
hermes claw migrate --dry-run    # 只预览要迁哪些
hermes claw migrate --preset user-data   # 不带 secret
hermes claw migrate --overwrite  # 覆盖已存在

会迁移：SOUL.md、MEMORY.md、USER.md、用户技能（→ ~/.hermes/skills/openclaw-imports/）、命令白名单、IM 平台配置、TTS 资产、AGENTS.md、白名单内的 API Key。

完整文档见 guides/migrate-from-openclaw.md。

3.12 卸载与重置

完全卸载：

rm -rf ~/.hermes
rm -f ~/.local/bin/hermes
# Root 安装：sudo rm -rf /usr/local/lib/hermes-agent /usr/local/bin/hermes

只重置配置而保留代码：

mv ~/.hermes/config.yaml ~/.hermes/config.yaml.bak
mv ~/.hermes/.env        ~/.hermes/.env.bak
hermes setup

只想换 Profile：hermes profile create new && hermes profile use new。

3.13 一次完整的”新机器开局”演练

把上面的内容串起来，一次完整开局大约长这样：

# 1) 安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

# 2) 初始化（选 OpenRouter，填 Key）
hermes setup

# 3) 先试一下能不能聊
hermes
> 你好，今天几号？

# 4) 试一下 Agent 调工具
> 把当前目录里所有 .md 文件统计出有多少行，最长的前 5 个

# 5) 让它学一点关于你的事
> 我在 Ubuntu 22.04 上工作，喜欢简洁回答，项目都放在 ~/code/

# 6) 让它给自己写第一条记忆
> 把上面这些信息记到记忆里

# 7) 看看它写了啥
cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md

# 8) 升级、体检
hermes update
hermes doctor

到这里你已经完成了”零基础上手”。

3.14 本章小结

本章你应该已经掌握：

• Hermes 的 OS 支持矩阵与硬性要求；
• 一行命令安装 + Termux/Nix/源码三种替代路径；
• hermes setup、hermes model、hermes config set、hermes doctor 各自的角色；
• ~/.hermes/ 目录结构与”机密 vs 配置”的分离；
• Profile 概念，多身份共存；
• 升级、迁移 OpenClaw、排错的标准流程。

下一章我们正式钻进日常使用的大头：CLI/TUI 与会话管理。