hermes-onboarding

Hermes 入门配置

基于可正常使用的基础聊天，为全新的 Hermes Agent 配置生产就绪的部署。

前提条件： 已安装 Hermes，并配置好主模型和提供方。运行 hermes doctor 验证。如果 Agent 无法完成正常聊天，请先停在此处并修复提供方。

触发词： onboard — 在宣布配置完成之前，配置好每一层。

适用场景

• 客户刚安装好 Hermes，基础聊天运行正常，需要完成全面配置
• 操作员要在新的 VPS 或机器上设置 Hermes，以供生产使用
• 客户希望从“能用”进一步实现“安全、启用记忆、持续运行并得到维护”

如果尚未配置主模型，请勿使用。请先修复提供方。

步骤 0 — 加载参考资料

加载 references/setup-details.md。其中包含配置片段、systemd 模板、DonSeTch MCP 配置、技能防护原则和详细程度示例。

完成条件： 参考文件已加载到上下文中。

步骤 1 — 检测环境

运行 references/setup-details.md § Detection 中的检测代码块。收集：

项目	方法
OS	uname -a
systemd	systemctl --version
Docker	docker --version
root 还是用户	whoami
容器还是裸机	head -5 /proc/1/cgroup
Hermes 路径	which hermes
Hermes 版本	hermes --version
主模型视觉能力	通过提供方文档检查模型能力，或使用 vision_analyze 进行测试

完成条件： 已检测并记录全部 8 项。无需用户输入。

步骤 2 — 提前询问问题

一次性向客户询问以下 3 个问题：

1. 客户姓名 — 用于配置文件名称和 soul.md 身份信息
2. 时区 — IANA 时区（例如 Asia/Singapore、America/New_York）
3. 网关平台 — Telegram、Discord、WhatsApp、Slack、Signal。收集机器人令牌或配对信息。令牌存储在 ~/.hermes/.env 中（chmod 600）。不要将令牌粘贴到聊天记录中。

如果步骤 1 检测到主模型缺少视觉能力，则增加第 4 个问题：

4. 具备视觉能力的辅助模型 — 用于视觉任务的模型和提供方是什么？默认：与主模型相同的提供方。

完成条件： 已回答所有提前询问的问题。仅在需要时询问视觉能力问题。

步骤 3 — 替代提供方和辅助模型

任务	命令	默认值
辅助视觉模型	hermes config set agent.aux_models.vision <model>	与主模型使用相同的提供方
嵌入模型	在 ~/.hermes/.env 中设置 NVIDIA_API_KEY	NVIDIA NIM (nemotron-3-embed-1b)
委派	保持默认设置（沿用主模型）	无需操作
备用提供方	hermes config set fallback_providers '[...]'	除非客户要求，否则跳过

如果没有 NVIDIA_API_KEY：帮助客户在 https://build.nvidia.com/nvidia/nemotron-3-embed-1b 获取免费密钥。备用方案：使用现有的 OPENROUTER_API_KEY，通过 OpenRouter 使用 bge-m3。

完成条件： 已配置辅助视觉模型（如有需要）。已设置 NVIDIA_API_KEY。已确认委派沿用主模型。

步骤 4 — 配置文件和 soul.md

1. 创建单个配置文件：hermes profile create <customer-name>
2. 询问客户提供 soul.md 内容：
   • Agent 名称（默认：“Hermes”）
   • 首选语言（默认：英语）
   • 个性（默认：商务型）
   • 特定领域的指令（可选）
3. 根据客户提供的内容编写 ~/.hermes/SOUL.md。参阅 references/setup-details.md § Soul.md template。

多配置文件：仅当客户明确表示需要单独的配置文件时才使用。

完成条件： 已创建配置文件。已根据客户提供的内容编写 soul.md。

步骤 5 — 网关和服务

1. 配置网关：hermes gateway setup — 选择客户选定的平台并输入令牌
2. 将网关部署为 systemd 服务。使用 references/setup-details.md § 网关 systemd 单元中的模板：
   • Root 模式：/etc/systemd/system/hermes-gateway.service
   • 用户模式：~/.config/systemd/user/hermes-gateway.service + loginctl enable-linger $USER
   • 设置 TimeoutStopSec=240
3. 将仪表板部署为 systemd 服务。使用 references/setup-details.md § 仪表板 systemd 单元中的模板：
   • 设置 HERMES_DASHBOARD_TUI=1
   • 将 HERMES_PYTHON 设置为 venv Python 路径
   • 绑定选项 — 询问客户：
     • 回环地址（默认）： 绑定到 127.0.0.1。通过 SSH 隧道访问：ssh -L 9119:127.0.0.1:9119 user@host。安全性最高。无需更改防火墙。
     • 局域网（0.0.0.0）： 使用 --host 0.0.0.0 绑定到所有接口。同一网络上的任何设备都可通过 http://<host-ip>:9119 直接访问。适用于所有设备均可信的内部 WiFi/局域网。设置基本身份验证（步骤 5b），避免仪表板未受保护。
4. 启用并启动这两项服务
5. 设置时区：hermes config set timezone '<customer-timezone>' + timedatectl set-timezone '<tz>'

完成： 网关和仪表板已作为 systemd 服务运行。已通过网关发送测试消息。可通过 SSH 隧道访问仪表板，或通过启用基本身份验证的局域网访问。

步骤 5b — 仪表板基本身份验证（局域网模式下必需，所有模式下均建议启用）

Hermes 内置了基本身份验证提供程序。设置用户名和密码，避免仪表板未受保护。

1. 对密码进行哈希处理：

   python3 -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('customer-password'))"
   

2. 在 config.yaml 中设置（直接编辑 — hermes config set 会将嵌套值转换为字符串）：

   dashboard:
     basic_auth:
       username: admin
       password_hash: <hash-from-step-1>
   

3. 重启仪表板：systemctl restart hermes-dashboard
4. 验证：在浏览器中打开仪表板 URL — 应显示登录页面

仅限回环地址的部署可不设置（SSH 隧道已限制访问）。局域网部署则必须设置。

完成： 已配置基本身份验证。访问仪表板时会显示登录页面。

步骤 6 — 审批和终端后端

设置	值	命令
审批	smart	hermes config set approvals.mode smart
终端后端	docker（如果检测到）或 local	hermes config set terminal.backend docker

完成： 审批模式已设为 smart。终端后端已根据 Docker 检测结果设置。

步骤 7 — 压缩

根据模型上下文长度设置压缩：

上下文长度	阈值	目标比例
64K–128K	0.35	0.20
200K+	0.50	0.20

hermes config set compression.enabled true
hermes config set compression.threshold <value>
hermes config set compression.target_ratio 0.20

完成： 已启用压缩，阈值与模型上下文长度相匹配。

步骤 8 — 搜索和抓取后端（DonSeTch + 回退方案）

主要方案：DonSeTch MCP 服务（mcp_donsetch_web_search / web_fetch / web_crawl）。它可处理研究级查询、设有机器人访问限制的页面以及由 JS 渲染的内容。安装并接入后，再设置轻量级回退方案，用于查询单条事实。

8a — 安装 DonSeTch

npm install -g donsetch

8b — 注册为 MCP 服务

将其添加到 ~/.hermes/config.yaml 中的 mcp:（直接编辑 — hermes config set 会将嵌套值转换为字符串）：

  donsetch:
    command: /usr/local/lib/node_modules/donsetch/binaries/donsetch
    args:
      - mcp
      - --supervised
    env:
      DONGHOST_CHROME: /usr/bin/google-chrome-stable
      DONGHOST_NO_SANDBOX: '1'
    enabled: true

验证：运行 hermes plugins list，或查看会话信息，确认其中显示 donsetch 已连接并提供 3 个工具。通过 mcp_donsetch_web_search 使用查询进行测试。

8c — 备用后端（无需密钥的 Firecrawl）

在配置中设置 web.search_backend: firecrawl。如果未设置 FIRECRAWL_API_KEY，Hermes 会使用 Firecrawl 的匿名公共云模式（api.firecrawl.dev，不带认证头）——已验证：显式选择且无凭据时会路由到无密钥模式，无需任何安装步骤。它同时支持搜索和提取。

如果客户之后购买 Firecrawl 套餐，设置 FIRECRAWL_API_KEY——同一后端会自动切换为密钥模式，无需更改配置。

仅当客户反对调用匿名云服务时，才考虑以下替代方案：

• 有 Docker：部署 SearXNG（references/setup-details.md § SearXNG 部署），设置 web.search_backend: searxng
• 没有 Docker：pip install ddgs，设置 web.search_backend: ddgs

备用方案适用于单一事实的快速查询（一个 URL、一个版本、一个价格），也能覆盖 DonSeTch 服务宕机的情况。

8d — SOUL.md 中的 Web 路由规则

在第 4 步（编写 soul.md）时，将 Web 路由部分写入客户的 SOUL.md，而不是之后再写。使用 references/setup-details.md § Web 工具路由（SOUL.md 模板）中的模板。核心规则：

• 研究或精确搜索、比较、多来源验证 → 优先使用 mcp_donsetch_web_search
• 内置 web_search = 仅用于单一事实的快速查询
• 有反爬虫屏障、验证码，或由 JS 渲染的 URL → 使用 mcp_donsetch_web_fetch；内置 web_extract = 仅用于普通页面
• 全站内容清点 → 使用 mcp_donsetch_web_crawl
• 需要认证的网站、文件上传、交互式流程 → 使用 browser_exec
• 扫描版 PDF/OCR → 使用 pdftoppm + tesseract，而不是 donsetch
• LAN/回环 URL → 使用内置工具（donsetch 会拦截 SSRF）

8e — DonSeTch 每周更新 cron

安装发布二进制自更新程序（不从源代码构建——依赖更少）：

# Script ships with the onboarding skill
cp ~/.hermes/skills/agent-ops/hermes-onboarding/scripts/donsetch_update.sh ~/.hermes/scripts/
chmod +x ~/.hermes/scripts/donsetch_update.sh
hermes cron create --name "DonSeTch weekly update" --schedule "0 9 * * 1" --mode no_agent ~/.hermes/scripts/donsetch_update.sh

该脚本会检查 GitHub 的 releases/latest（已发布且带资源文件的版本），而不是标签——只有标签、没有已发布资源文件时，donsetch update 会返回 404。如果已是最新版本，则静默运行（stdout 为空）：no_agent cron 仅在失败或有更新时发出提醒。

如果客户有 Nous Portal：Tool Gateway 搜索已处于启用状态。仍需安装 DonSeTch 和备用方案——Tool Gateway 搜索无法抓取有反爬虫屏障的页面。

完成： DonSeTch 已安装并作为 MCP 服务连接（3 个工具）。已设置备用后端。已将 Web 路由规则写入 SOUL.md。已启用更新 cron。已通过测试查询验证搜索。

第 9 步 — 提取

验证无密钥提取功能正常。第 1 步记录了 Hermes 版本——确认版本为 0.20.5+，以支持无密钥 MCP 环（exa、parallel、tavily、firecrawl、keenable）：

hermes chat -q "Extract the content from https://example.com"

如果提取成功，则无需操作。如果客户希望固定使用某个后端，设置 web.extract_backend: firecrawl——无需 API 密钥即可使用无密钥匿名模式（机制与第 8c 步相同）；之后设置 FIRECRAWL_API_KEY 即可升级为密钥模式。

完成： 已验证无密钥提取功能正常。

第 10 步 — 记忆（Mnemosyne）

1. 启用 Mnemosyne：hermes memory setup → 选择 Mnemosyne
2. 确认已设置 NVIDIA_API_KEY（来自第 3 步）——Mnemosyne 使用它生成嵌入
3. 验证记忆功能正常：mnemosyne_recall({"query": "test", "limit": 1})

完成： 已启用 Mnemosyne。已确认嵌入密钥。已验证记忆检索功能。

第 11 步 — 技能编写防护准则

将 Matt Pocock 的 7 条原则应用于自动生成的技能。参见 references/setup-details.md § 技能防护准则。Agent 应依据这些原则审核所创建的任何技能。

如需完整的技能编写验证，请加载随附技能：skill_view(name='hermes-agent-skill-authoring')。这是 Hermes 内置技能——每次安装都会随 software-development 类别一同提供。

完成： 已加载防护准则。Agent 知道在哪里查找完整的技能编写验证内容。

第 12 步 — 技能检索插件（BM25）

从 agent-skills 仓库安装 skill-retrieval 插件。该插件会将系统提示词中的完整技能列表替换为精简的纯名称索引，并通过 pre_llm_call 钩子在每轮注入排名靠前的相关描述。它会遵循命名配置、skills.external_dirs、禁用列表以及平台／条件门控——其语料与 Hermes 自身解析的内容一致。安装时保持禁用。只有在技能数量或令牌开销达到需要时才启用。

12a — 安装（禁用）

hermes plugins install moonlight-lupin/agent-skills/plugins/skill-retrieval --no-enable

12b — 评估是否需要启用

运行评估，测量技能数量和开销比例：

python3 -c "
import yaml, pathlib, glob, os, re, sys

# Count skills the way Hermes resolves them: discovery helpers when importable
# (honors named profiles, external_dirs, plugin-bundled skills, symlinks),
# glob fallback for standalone contexts.
count = 0; total_chars = 0
try:
    from hermes_constants import get_skills_dir
    from agent.skill_utils import get_all_skills_dirs, get_project_skills_dirs, iter_skill_index_files
    from agent.prompt_builder import _parse_skill_file, _skill_should_show, extract_skill_conditions, _current_session_platform_hint
    hint = _current_session_platform_hint() or None
    seen = set()
    for root in list(get_project_skills_dirs()) + list(get_all_skills_dirs()):
        for f in iter_skill_index_files(root, 'SKILL.md'):
            try:
                ok, fm, desc = _parse_skill_file(f)
                if not ok or not desc: continue
                name = fm.get('name', '')
                if name in seen: continue
                if not _skill_should_show(extract_skill_conditions(fm), None, None, hint): continue
                seen.add(name); count += 1
                total_chars += min(len(desc), 200)
            except Exception: pass
    # Plugin-bundled skills also occupy the system prompt (keyed prefix:name)
    from hermes_constants import get_hermes_home
    plugins_root = get_hermes_home() / 'plugins'
    if plugins_root.is_dir():
        for pdir in sorted(plugins_root.iterdir()):
            pskills = pdir / 'skills'
            if not pdir.is_dir() or pdir.name.startswith('.') or not pskills.is_dir(): continue
            for f in iter_skill_index_files(pskills, 'SKILL.md'):
                try:
                    ok, fm, desc = _parse_skill_file(f)
                    if not ok or not desc: continue
                    name = fm.get('name', '')
                    if name in seen: continue
                    if not _skill_should_show(extract_skill_conditions(fm), None, None, hint): continue
                    seen.add(name); count += 1
                    total_chars += min(len(desc), 200)
                except Exception: pass
except ImportError:
    for f in glob.glob(os.path.expanduser('~/.hermes/skills/**/SKILL.md'), recursive=True):
        try:
            text = pathlib.Path(f).read_text()
            m = re.match(r'^---\n(.*?)\n---\n', text, re.DOTALL)
            if not m: continue
            fm = yaml.safe_load(m.group(1))
            if not fm: continue
            desc = fm.get('description', '')
            if desc:
                count += 1
                total_chars += min(len(desc), 200)
        except Exception: pass

desc_tokens = total_chars // 4

# Context window: provider-aware resolution when Hermes is importable
# (covers OpenRouter probing and cached per-model metadata), else config,
# else 128K default.
ctx = 0
try:
    from model_tools import _resolve_active_context_length
    ctx = int(_resolve_active_context_length() or 0)
except Exception:
    pass
if not ctx:
    try:
        with open(os.path.expanduser('~/.hermes/config.yaml')) as fh:
            cfg = yaml.safe_load(fh) or {}
        ctx = int(cfg.get('model', {}).get('context_length', 0))
    except Exception:
        pass
if not ctx:
    ctx = 128000

skill_ratio = desc_tokens / ctx if ctx else 0
SKILL_COUNT_THRESHOLD = 50
SKILL_RATIO_THRESHOLD = 0.05  # 5% of context from skill descriptions alone

print(f'Skills: {count}')
print(f'Skill description tokens: ~{desc_tokens} ({skill_ratio:.1%} of {ctx} context)')
print(f'Thresholds: skill count > {SKILL_COUNT_THRESHOLD} OR skill ratio > {SKILL_RATIO_THRESHOLD:.0%}')

if count > SKILL_COUNT_THRESHOLD or skill_ratio > SKILL_RATIO_THRESHOLD:
    print('RECOMMEND: enable skill-retrieval plugin')
else:
    print('RECOMMEND: keep disabled — overhead within healthy range')
"

以下两个阈值会触发启用建议：

• 技能数量 > 50 — 系统提示词中的完整技能列表会超过约 2.5K 个令牌。插件的精简索引约为 2.3K 个令牌，节省的开销大于其自身成本。
• 技能描述开销 > 上下文窗口的 5% — 仅技能描述就占到 5% 时，与固定开销（工具架构、系统提示词、行为规则）相加，总开销会超过 15%。input-token-overheads 技能指出，15% 是健康范围的上限。如果客户想要更深入的分析，请加载该技能进行完整的开销审计。

12c — 如有建议则启用

hermes plugins enable skill-retrieval

重启会话以使插件生效。每轮注入由 pre_llm_call 钩子执行；纯名称精简则在构建提示词时应用。

如果不建议启用，插件会保持已安装但禁用的状态。添加技能后请重新运行此评估——客户之后可以启用插件。

12d — 未启用时记录到记忆中

如果未启用插件，请存储一条 Mnemosyne 记忆，让 Agent 记住存在这条升级路径：

mnemosyne_remember(
    content="Skill-retrieval plugin (BM25) is installed but disabled. Enable with `hermes plugins enable skill-retrieval` if skill count exceeds 50 or input token overhead from skill descriptions exceeds 5% of context window. Re-run the Step 12b assessment after adding skills.",
    importance=0.6,
    scope="global",
    source="onboarding",
    veracity="stated"
)

完成： skill-retrieval 插件已安装（禁用）。仅当技能数量 > 50 或技能开销 > 上下文窗口的 5% 时，才建议启用。如果插件保持禁用，Mnemosyne 记忆会记录这条升级路径。

第 13 步 — 轻量级 RAG（library-rag）

1. 从 agent-skills 仓库安装 library-rag 技能
2. 按照 library-rag 的入门工作流操作（目录、NVIDIA API 密钥、首个索引）
3. 如果客户希望搜索工具自动可用，则在 config.yaml 中注册 MCP 服务

注意：索引每个分块约增长 8KB。从小型语料库开始。包含 50 本书的书库约为 100MB。完整的研究资料库可能超过 1GB。

完成： library-rag 已安装。首份文档已建立索引。MCP 服务已注册（如果客户选择启用）。

第 14 步 — 浏览器自动化（CDP）

1. 检查是否已安装 Chromium：which chromium-browser || which chromium || which google-chrome
2. 如果缺少，则安装：apt install -y chromium-browser（或对应平台的命令）
3. 设置浏览器后端：hermes config set browser.cdp_url http://127.0.0.1:9222
4. 按照 references/setup-details.md § "CDP browser systemd service" 中的说明，安装带有内存保护限制和空闲标签页清理功能的 chrome-cdp systemd 服务。无头 Chrome 的渲染进程会在数周内持续泄漏内存——内存上限、每 6 小时清理一次以及每周重启可避免其耗尽主机资源。
5. 验证：Agent 能够打开浏览器标签页并导航
6. 验证清理功能：journalctl -t chrome-cdp-drain -n 1 显示活动记录（defer 也可以）；systemctl list-timers 'chrome-cdp*' 显示两个计时器均已启用

有关防检测或云浏览器需求的升级方案，请参阅 Browserbase 和 Firecrawl 的文档。

完成： CDP 浏览器已配置 systemd 服务、内存上限、清理和重启计时器。Chromium 已可用。浏览器测试通过。清理计时器已启用。

步骤 15 — 工具集审核

1. 运行 hermes tools list
2. 按以下类别展示工具集：

类别	工具集
必需（保留）	terminal、file、web、search、browser、code_execution、memory、session_search、todo、skills、cronjob、clarify
可选（询问）	vision、image_gen、tts、delegation、messaging、kanban
高级（默认关闭）	spotify、homeassistant、discord、discord_admin、feishu_doc、feishu_drive、yuanbao、rl、debugging、x_search、video

3. 询问客户要保留哪些可选工具集
4. 禁用不需要的工具集：hermes tools disable <name>

注意：messaging = 跨平台消息发送（仅适用于多平台设置）。rl = 强化学习工具。debugging = 用于 Hermes 开发的额外内省功能。

完成： 工具集已审核。不需要的工具集已禁用。客户已确认可选工具集。

步骤 16 — 确认详细程度

展示 references/setup-details.md § Verbosity 中的 4 种 tool_progress 模式及示例，并请客户确认。

模式	显示内容
off	仅显示最终回复，不显示工具输出
new	每个工具显示一行，跳过连续重复项
all	每次工具调用显示一行，并显示耗时（默认）
verbose	与 all 相同，另显示完整工具参数

建议启用 show_cost: true 以追踪开支。

hermes config set display.tool_progress all
hermes config set display.show_cost true

完成： 已确认详细程度。已启用 show_cost。

步骤 17 — Cron fleet 默认模型

设置 Cron fleet 默认模型，以避免切换提供商时触发漂移保护失败：

hermes config set cron.model_provider <main-provider>
hermes config set cron.model <main-model>

完成： 已设置 Cron fleet 默认模型。未来未固定模型的 Cron 作业在切换提供商时不会失败。

步骤 18 — 维护定时任务

创建 4 个定时任务，并记录 1 个触发式流程：

定时任务	计划	模式	内容
记忆整合	每 4 天，02:00	no_agent	mnemosyne_sleep.sh — 将工作记忆转为情景记忆。完成后静默运行。
备份 + 更新 + 健康检查	每周（周日，03:00）	Agent	执行 hermes backup（最多保留 2 份），然后执行 hermes update，再进行更新后健康检查（必要时重新应用 LAN 补丁）。失败时发出警报。
每周健康检查	每周（周日，06:00）	no_agent	weekly_health_check.sh — 汇总报告：主机状态、磁盘使用情况、日志异常、输入令牌开销。状态正常时静默运行。任何检查发现问题时，发送包含详细信息的警报。
输入令牌审计	每 30 天，09:30	Agent	运行 input-token-overheads 技能的汇总审计（scripts/audit.py --days 30）：对使用者排序、预先检查可调整项、报告与上一基线的差异，并根据已验证的配置值提出更改建议。每次运行都会生成完整报告——这是每周检查仅抽样执行的深度审计。需要安装 input-token-overheads 技能（见步骤 20）。
DonSeTch 每周更新	每周（周一，09:00）	no_agent	donsetch_update.sh — 发布二进制文件自更新程序。依据 GitHub releases/latest 判断，而非标签。已是最新版本时静默运行。见步骤 8e。

备份 + 更新定时任务以 Agent 模式运行（而非 no_agent），因为更新后健康检查可能需要重新应用被 hermes update 覆盖的仪表板补丁。no_agent 脚本无法重新应用补丁或运行 skill_view。

每周健康检查脚本（~/.hermes/scripts/weekly_health_check.sh）会将四项检查整合为一份报告：

1. 主机状态 — 通过 systemd-detect-virt 和 /proc/device-tree/model 检测主机类型（Raspberry Pi、VM、裸机、Mac、Windows/WSL），并报告运行时间和平均负载。
2. 磁盘使用情况 — 使用 df -h 检查所有挂载点。任何挂载点使用率超过 80% 时发出警报。
3. 日志异常 — 运行 log-analyzer 扫描（analyze_logs.py --since 7d --quiet）和 state_failures.py --quiet --days 7。报告错误聚类、速率限制、超时、工具失败、崩溃和会话失败。
4. 输入令牌开销 — 统计技能数量，并测量技能描述相对于上下文窗口的令牌开销。技能数量 > 50 或技能开销 > 上下文的 5% 时发出警报。建议启用 skill-retrieval 插件。

脚本始终会输出报告（即使一切正常），并会在发现警报时，通过 建议操作 部分列出具体的补救步骤。定时任务会将报告发送到客户的主频道。

系统会根据各项检查的结果有条件地生成建议操作：

警报	建议操作
负载过高（> CPU 容量的 80%）	使用 top 或 htop 检查是否有失控进程
磁盘使用率超过 80%	运行磁盘清理技能（skill_view(name='disk-cleanup')）
日志中存在错误聚类	检查出现频率最高的错误；如果是基础设施问题，则安排修复
触发速率限制	检查提供商配额，或在 ~/.hermes/.env 中轮换 API 密钥
存在超时聚类	检查与受影响端点的网络连接
工具成功率低于 95%	检查失败的工具调用和相关配置
技能开销超过阈值	启用 skill-retrieval 插件（hermes plugins enable skill-retrieval）

所有检查均通过时，建议操作部分显示：“无需采取操作。所有检查均已通过。”

在入门配置期间安装脚本：

# Script ships with the onboarding skill at scripts/weekly_health_check.sh
cp ~/.hermes/skills/agent-ops/hermes-onboarding/scripts/weekly_health_check.sh ~/.hermes/scripts/
chmod +x ~/.hermes/scripts/weekly_health_check.sh

触发式（非定时）流程：更新后健康检查 — 运行 hermes doctor，验证网关和仪表板状态，并在需要时重新应用补丁。见 references/setup-details.md § 更新后健康检查。在每周定时任务之外手动执行任何 hermes update 后，也需触发此流程。

创建输入令牌审计定时任务（Agent 模式——需要使用 skill_view 并进行推理）：

Prompt skeleton (adapt to the customer):

"You are the input-token auditor. Load the `input-token-overheads` skill and run
its scripts/audit.py for the last 30 days. Compare against the previous audit's
baseline (read it from the prior cron output if available, else establish this
run as the first baseline). Pre-check every lever before proposing changes:
read current values with `hermes config get`, confirm mechanisms against
config_defaults.py or the Hermes docs, mark unverifiable claims UNVERIFIED.
Report under 600 words: (1) total vs baseline with % change, (2) breakdown by
task, (3) verdict on any previously applied changes with proving numbers,
(4) top 3 remaining consumers, (5) one recommended next tweak citing the
pre-checked current value."

Schedule: every 30 days. Delivery: customer's home channel.

**完成：**已创建 4 个定时任务。已安装每周健康检查脚本。已记录更新后流程。

步骤 19 — 验证摘要

1. 运行 hermes doctor
2. 检查每一项：

项目	检查方式
Gateway	systemctl status hermes-gateway + 测试消息
Dashboard	systemctl status hermes-dashboard + URL 可访问
Dashboard 身份验证	浏览器显示登录页面（LAN 模式），或 SSH 隧道可正常工作（loopback）
Memory	mnemosyne_recall 返回结果
搜索（主用）	mcp_donsetch_web_search 测试查询返回结果；会话信息显示 donsetch 已连接且有 3 个工具
搜索（备用）	web_search 测试查询通过无需密钥的 firecrawl 返回结果
网页路由	SOUL.md 包含网页路由部分（优先使用 donsetch，单事实查询使用内置工具）
内容提取	web_extract 测试 URL 返回内容
浏览器	CDP 浏览器已打开并完成导航
Crons	hermes cron list 显示 5 个作业（包括 DonSeTch 每周更新）
每周健康检查	~/.hermes/scripts/weekly_health_check.sh 存在且可执行
输入 token 审计	hermes cron list 显示一个 30 天审计作业；已安装 input-token-overheads 技能，且 scripts/audit.py 可运行
时区	hermes config get timezone 与客户提供的信息一致
审批	hermes config get approvals.mode 返回 smart
终端后端	hermes config get terminal.backend 与检测结果一致
压缩	hermes config get compression.threshold 与模型上下文一致
Cron Fleet 默认值	已设置 hermes config get cron.model
工具集	hermes tools list 仅显示已启用的必需工具集
详细程度	hermes config get display.tool_progress 与客户的选择一致
show_cost	hermes config get display.show_cost 返回 true
配置档案	hermes profile list 显示客户配置档案
Soul.md	~/.hermes/SOUL.md 存在且包含客户提供的信息
技能护栏	已从参考资料加载 7 项原则
技能检索插件	hermes plugins list 显示已安装 skill-retrieval（根据评估结果启用或禁用）
Library-rag	hermes skills list 显示 library-rag（如果选择启用）
使用场景	客户已作答，并已推荐技能

3. 展示配置快照：提供商、模型、辅助模型、gateway 平台、记忆后端、搜索后端、浏览器后端、压缩设置、cron 作业、soul.md 路径、配置档案名称
4. 展示每一项的通过/失败状态

完成： 已检查所有验证项。已展示配置快照。已标记失败项并提供故障排除步骤。

步骤 20 — 使用场景与技能推荐

询问：“你会用 Hermes 做什么？”

根据回答，从 Skills Hub 推荐 3-5 个技能：

hermes skills search <use-case-keyword>

安装客户选择的技能：hermes skills install <id>

另外，还要从此仓库（agent-ops/input-token-overheads）安装 input-token-overheads 技能——步骤 18 中的 30 天审计 cron 依赖此技能。

完成： 已记录使用场景。已推荐并安装相关技能。已安装 input-token-overheads 技能，供步骤 18 中的审计 cron 使用。

常见陷阱

• 使用 --replace 导致网关崩溃循环： 多个配置文件的 systemd 单元文件中切勿使用 --replace。它会向其他网关进程发送 SIGTERM。
• TimeoutStopSec 设置过短： 始终设置为 240s。默认的 90s 会导致 WhatsApp/Telegram 桥接在排空过程中被 SIGKILL。
• Cron 漂移防护： 未固定模型的 cron 作业会在全局模型变更时安全失败。请尽早设置 cron 集群默认值（第 17 步）。
• SearXNG IP 信誉： Google/Brave 可能会屏蔽数据中心 IP。没有配置层面的解决办法——请使用住宅代理，或接受回退到 DDG。这只影响备用后端；DonSeTch 是主要搜索路径。
• library-rag 中重复索引： 将原始文件保存在 LIBRARY_ROOT 之外。只有结构化 Markdown 才放在 LIBRARY_ROOT 下。
• plugins.enabled 字符串化： hermes config set plugins.enabled '["a"]' 会将其存储为 JSON 字符串，而非 YAML 列表。请直接编辑 config.yaml 来配置插件列表。
• 局域网中的 Dashboard TUI： 需要 HERMES_PYTHON 环境变量以及 CORS/loopback 补丁。请参阅 hermes-service-deployment 技能参考资料。

验证

第 19 步的验证表是判断设置是否完整的唯一标准。请勿在此重复该表。

在宣布引导流程完成之前，所有项目都必须通过。未通过的项目请根据“常见陷阱”部分中的步骤进行故障排除。