Hermes Agent 快速上手

9 章 · 约 95 千字

官方文档「开始使用」全部内容，外加集成与命令参考。装上、跑通、知道常用命令怎么查。

快速入门

本页的 Python 依赖命令使用 PM 准备的源码环境。

依赖变更后，请重新激活该 checkout 并重启 Hermes。

本指南带你从零开始搭建一个能够应对实际使用的 Hermes 环境。完成安装、选择 provider（服务提供商）、验证对话正常运行，并了解出现问题时的处理方法。

更喜欢看视频？

Onchain AI Garage 制作了一套涵盖安装、配置和基本命令的 Masterclass 演示视频——如果你更习惯跟着视频操作，这是本页的绝佳补充。更多内容请查看完整的 Hermes Agent 教程与使用案例播放列表。

适用人群

全新用户，想以最短路径完成可用配置
正在切换 provider，不想因配置错误浪费时间
为团队、机器人或长期运行的工作流配置 Hermes
厌倦了"安装成功但什么都做不了"的情况

最快路径

根据你的目标选择对应行：

| | 目标 | 先做这步 | 再做这步

| 只想让 Hermes 在本机跑起来 | hermes setup | 运行一次真实对话并验证有响应

| 已知道要用哪个 provider | hermes model | 保存配置，然后开始聊天

| 想搭建机器人或长期运行的服务 | CLI 正常后运行 hermes gateway setup | 接入 Telegram、Discord、Slack 或其他平台

| 想使用本地或自托管模型 | hermes model → 自定义 endpoint | 验证 endpoint、模型名称和上下文长度

| 想要多 provider 故障转移 | 先运行 hermes model | 基础对话正常后再添加路由和故障转移

经验法则：如果 Hermes 无法完成一次正常对话，暂时不要添加更多功能。先让一次完整对话跑通，再逐步叠加 gateway、cron、skills、语音或路由。

1. 安装 Hermes Agent

在 macOS 或 Windows 上使用 Hermes Desktop 安装器（推荐）

如需同时安装命令行与桌面应用，请从我们的官网下载 Hermes Desktop 安装器并运行。

不使用 Hermes Desktop：

仅安装命令行版本（跟踪 main 分支）：

# Linux / macOS / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

源码脚本通过 PM 准备运行时。桌面软件包、Docker、Nix 和 Termux APT 是独立的安装方式。

请勿使用 pip install hermes-agent 替代受管理的安装。

Windows 原生安装可在 PowerShell 中运行 iex (irm https://hermes-agent.nousresearch.com/install.ps1)，无需 WSL。

aarch64 Android 设备请使用 Termux APT 指南，而非上述脚本。

安装完成后，重新加载 shell：

source ~/.bashrc   # 或 source ~/.zshrc

详细的安装选项、前置条件和故障排查，请参阅安装指南。

2. 选择 Provider

这是最重要的配置步骤。使用 hermes model 以交互方式完成选择：

hermes model

最简路径：Nous Portal

一个订阅涵盖 300+ 个模型，以及 Tool Gateway（网页搜索、图像生成、TTS、云端浏览器）。全新安装时：

hermes setup --portal

该命令一次性完成登录、设置 Nous 为 provider 并开启 Tool Gateway。

推荐默认选项：

| | Provider | 说明 | 配置方式

| Nous Portal | 订阅制，零配置 | 通过 hermes model 进行 OAuth 登录

| OpenAI Codex | ChatGPT 或 Codex 订阅，使用 Codex 模型 | 通过 hermes model → ChatGPT or Codex Subscription 进行设备码认证

| Anthropic | 直接使用 Claude 模型——Max 计划 + 额外用量积分（OAuth），或按 token 付费的 API key | hermes model → OAuth 登录（需要 Max + 额外积分），或 Anthropic API key

| OpenRouter | 跨多个 provider 的多模型路由 | 输入 API key

| Z.AI | GLM / Zhipu 托管模型 | 设置 GLM_API_KEY / ZAI_API_KEY

| Kimi / Moonshot | Moonshot 托管的编程和对话模型 | 设置 KIMI_API_KEY（或 Kimi-Coding 专用的 KIMI_CODING_API_KEY）

| Kimi / Moonshot China | 中国区 Moonshot endpoint | 设置 KIMI_CN_API_KEY

| Arcee AI | Trinity 模型 | 设置 ARCEEAI_API_KEY

| GMI Cloud | 多模型直连 API | 设置 GMI_API_KEY

| MiniMax (OAuth) | 通过浏览器 OAuth 使用 MiniMax-M2.7，无需 API key | hermes model → MiniMax (OAuth)

| MiniMax | 国际版 MiniMax endpoint | 设置 MINIMAX_API_KEY

| MiniMax China | 中国区 MiniMax endpoint | 设置 MINIMAX_CN_API_KEY

| Alibaba Cloud | 通过 DashScope 使用 Qwen 模型 | 设置 DASHSCOPE_API_KEY

| Hugging Face | 通过统一路由器使用 20+ 开源模型（Qwen、DeepSeek、Kimi 等） | 设置 HF_TOKEN

| AWS Bedrock | 通过原生 Converse API 使用 Claude、Nova、Llama、DeepSeek | IAM 角色或 aws configure（指南）

| Kilo Code | KiloCode 托管模型 | 设置 KILOCODE_API_KEY

| OpenCode Zen | 按需付费访问精选模型 | 设置 OPENCODE_ZEN_API_KEY

| OpenCode Go | $10/月订阅，访问开源模型 | 设置 OPENCODE_GO_API_KEY

| DeepSeek | 直接访问 DeepSeek API | 设置 DEEPSEEK_API_KEY

| NVIDIA NIM | 通过 build.nvidia.com 或本地 NIM 使用 Nemotron 模型 | 设置 NVIDIA_API_KEY（可选：NVIDIA_BASE_URL）

| GitHub Copilot | GitHub Copilot 订阅（GPT-5.x、Claude、Gemini 等） | 通过 hermes model 进行 OAuth，或设置 COPILOT_GITHUB_TOKEN / GH_TOKEN

| GitHub Copilot ACP | Copilot ACP agent 后端（在本地启动 copilot CLI） | hermes model（需要 copilot CLI + copilot login）

| Vercel AI Gateway | Vercel AI Gateway 路由 | 设置 AI_GATEWAY_API_KEY

| Custom Endpoint | VLLM、SGLang、Ollama 或任何兼容 OpenAI 的 API | 设置 base URL + API key

对于大多数初次使用的用户：选择一个 provider，接受默认值（除非你明确知道为何要修改）。完整的 provider 目录及环境变量和配置步骤请参阅 Providers 页面。

最低上下文要求：64K token

Hermes Agent 要求模型至少具备 64,000 个 token 的上下文窗口。上下文窗口较小的模型无法为多步骤工具调用工作流维持足够的工作内存，启动时将被拒绝。大多数托管模型（Claude、GPT、Gemini、Qwen、DeepSeek）均轻松满足此要求。如果你运行本地模型，请将其上下文大小设置为至少 64K（例如 llama.cpp 使用 --ctx-size 65536，Ollama 使用 -c 65536）。

提示

你可以随时通过 hermes model 切换 provider——没有锁定。所有支持的 provider 完整列表及配置详情，请参阅 AI Providers。

配置的存储方式

Hermes 将密钥与普通配置分开存储：

密钥和 token → ~/.hermes/.env
非密钥配置 → ~/.hermes/config.yaml

通过 CLI 设置值是最简便的方式，系统会自动将值写入正确的文件：

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

3. 运行第一次对话

hermes            # 经典 CLI
hermes --tui      # 现代 TUI（推荐）

你会看到一个欢迎横幅，显示你的模型、可用工具和 skills。使用一个具体且易于验证的 prompt（提示词）：

选择你的界面

Hermes 提供两种终端界面：经典的 prompt_toolkit CLI，以及更新的 TUI（支持模态覆盖层、鼠标选择和非阻塞输入）。两者共享相同的会话、斜杠命令和配置——分别用 hermes 和 hermes --tui 试试看。

Summarize this repo in 5 bullets and tell me what the main entrypoint is.

Check my current directory and tell me what looks like the main project file.

Help me set up a clean GitHub PR workflow for this codebase.

成功的标志：

横幅显示你选择的模型/provider
Hermes 无错误地回复
需要时能够使用工具（终端、文件读取、网页搜索）
对话可以正常进行超过一轮

如果以上都正常，你已经过了最难的部分。

4. 验证会话功能

继续之前，确认恢复功能正常：

hermes --continue    # 恢复最近的会话
hermes -c            # 简写形式

这应该会带你回到刚才的会话。如果不行，检查你是否在同一个 profile 下，以及会话是否实际已保存。当你同时管理多个配置或多台机器时，这一点很重要。

5. 尝试核心功能

使用终端

❯ What's my disk usage? Show the top 5 largest directories.

Agent 会代你执行终端命令并显示结果。

斜杠命令

输入 / 查看所有命令的自动补全下拉列表：

| | 命令 | 功能

| /help | 显示所有可用命令

| /tools | 列出可用工具

| /model | 交互式切换模型

| /personality pirate | 尝试一个有趣的人格

| /save | 保存对话

多行输入

按 Alt+Enter、Ctrl+J 或 Shift+Enter 换行。Shift+Enter 需要终端能将其作为独立序列发送（Kitty / foot / WezTerm / Ghostty 默认支持；iTerm2 / Alacritty / VS Code 终端需启用 Kitty 键盘协议）。Alt+Enter 和 Ctrl+J 在所有终端中均可使用。

中断 Agent

如果 agent 响应时间过长，输入新消息并按 Enter——这会中断当前任务并切换到你的新指令。Ctrl+C 同样有效。

6. 添加下一层功能

仅在基础对话正常后进行。按需选择：

机器人或共享助手

hermes gateway setup    # 交互式平台配置

接入 Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant（插件）或 Microsoft Teams。

自动化与工具

hermes tools — 按平台调整工具访问权限
hermes skills — 浏览并安装可复用的工作流
Cron — 仅在机器人或 CLI 配置稳定后使用

沙箱终端

为了安全起见，在 Docker 容器或远程服务器中运行 agent：

hermes config set terminal.backend docker    # Docker 隔离
hermes config set terminal.backend ssh       # 远程服务器

语音模式

# 在 Hermes 安装目录下运行（curl 安装器在 Linux/macOS 上将其放置于
# ~/.hermes/hermes-agent，在 Windows 上为 %LOCALAPPDATA%\hermes\hermes-agent）：
cd ~/.hermes/hermes-agent
python -c "import pm; pm.sync_venv(['voice'], explicit=True)"
# 包含 faster-whisper，用于免费的本地语音转文字

然后在 CLI 中输入：/voice on。按 Ctrl+B 开始录音。参阅语音模式。

Skills

hermes skills search kubernetes
hermes skills install openai/skills/k8s

或在聊天会话中使用 /skills。

MCP 服务器

# 添加到 ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

编辑器集成（ACP）

ACP 支持已包含在标准 [all] 扩展中，因此 curl 安装器已默认包含。直接运行：

hermes acp

（如果安装时未包含 [all]，请先运行 cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['acp'], explicit=True)"。）

参阅 ACP 编辑器集成。

常见故障模式

以下是最容易浪费时间的问题：

| | 现象 | 可能原因 | 解决方法

| Hermes 启动但回复为空或异常 | Provider 认证或模型选择有误 | 重新运行 hermes model，确认 provider、模型和认证信息

| 自定义 endpoint "可用"但返回乱码 | base URL、模型名称有误，或实际上不兼容 OpenAI | 先用独立客户端验证该 endpoint

| Gateway 启动但无法收到消息 | Bot token、白名单或平台配置不完整 | 重新运行 hermes gateway setup 并检查 hermes gateway status

| hermes --continue 找不到旧会话 | 切换了 profile 或会话从未保存 | 检查 hermes sessions list，确认你在正确的 profile 下

| 模型不可用或出现异常的故障转移行为 | Provider 路由或故障转移设置过于激进 | 在基础 provider 稳定之前关闭路由

| hermes doctor 标记配置问题 | 配置值缺失或已过期 | 修复配置，在添加功能前重新测试普通对话

恢复工具包

当感觉有问题时，按以下顺序操作：

hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
hermes gateway status

这个顺序能让你快速从"感觉哪里不对"回到已知的正常状态。

快速参考

| | 命令 | 说明

| hermes | 开始聊天

| hermes model | 选择 LLM provider 和模型

| hermes tools | 配置每个平台启用的工具

| hermes setup | 完整配置向导（一次性配置所有内容）

| hermes doctor | 诊断问题

| hermes update | 更新到最新版本

| hermes gateway | 启动消息 gateway

| hermes --continue | 恢复上次会话

下一步

CLI 指南 — 掌握终端界面
配置 — 自定义你的配置
消息 Gateway — 接入 Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant、Teams 等
工具与工具集 — 探索可用功能
AI Providers — 完整 provider 列表及配置详情
Skills 系统 — 可复用的工作流与知识
技巧与最佳实践 — 高级用户技巧

安装

使用一行安装命令，两分钟内即可启动并运行 Hermes Agent。

快速安装

一行安装命令（Linux / macOS / WSL2）

基于 git 的安装方式，跟踪 main 分支，可立即获取最新变更：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows（原生，PowerShell）

原生 Windows 无需 WSL 即可运行 Hermes——CLI、gateway、TUI 和工具均可原生运行。（原生安装与 WSL2 安装可干净共存；唯一仅限 WSL2 的功能见下方功能说明。）遇到 bug 请提交 issue。

打开 PowerShell 并运行：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

源码安装脚本克隆仓库，再由 PM 准备 Python 3.14、Node.js、npm、ripgrep、FFmpeg 和 Python 依赖。

缺少 Git 时，脚本下载经过 SHA-256 验证的 Git for Windows 到工具存储目录。

它不替换系统 Git，也不再使用 MinGit 或 hermes\node 的旧布局。

安装完成后，打开新终端以读取用户 PATH。

桌面软件包： MSIX/App Installer 是自包含的软件包，与源码脚本不同。

它要求 Windows 11 22H2 或更新版本，首次启动无需克隆源码或编译基础运行时。

打开 .appinstaller 文件安装并登记更新源。Microsoft Store 版本由商店更新。

Hermes-Setup.exe 则是下载并配置源码的引导安装程序。

macOS 的 DMG 包含应用；将它复制到 Applications 后启动。

其自动更新使用包含已签名应用的 ZIP。详情见桌面指南。

Android / Termux

aarch64 Android 设备可通过 Termux 安装预发布的 APT 软件包。软件包包含 Python、Node.js 和 TUI，无需在手机上编译核心依赖。请按照 Termux 指南配置签名仓库，然后运行 pkg install hermes-agent。桌面和服务器的安装脚本不支持 Termux。

功能与安装目录

Windows 的 CLI、TUI、gateway 和桌面应用可原生运行。

Dashboard 终端使用 pywinpty/ConPTY，不再是尚未实现的 POSIX-only 功能。

部分可选依赖仍受架构限制，请参阅 Windows 指南。

| POSIX 源码脚本 | ~/.hermes/hermes-agent/ | ~/.local/bin/hermes 包装器 | ~/.hermes/

| Windows 源码脚本 | %LOCALAPPDATA%\hermes\hermes-agent\ | %LOCALAPPDATA%\hermes\bin\ | %LOCALAPPDATA%\hermes\

| 桌面软件包 | 应用包内部 | 包内启动器；Windows 执行别名 | 平台默认数据目录

| Docker | /opt/hermes/ | 镜像入口和 hermes | 挂载的 /opt/data/

| Termux APT | $PREFIX/lib/hermes-agent/ | $PREFIX/bin/ 符号链接 | ~/.hermes/

HERMES_HOME 选择数据目录。POSIX 的 --dir 单独选择源码目录。

以 root 身份运行不再自动选择 /usr/local/lib 的 FHS 布局。

PM 的工具和 Python 环境代际位于独立目录，详见包管理。

不要为了修复应用而删除整个数据目录。

安装后

重新加载 shell 并开始聊天：

source ~/.bashrc   # 或：source ~/.zshrc
hermes             # 开始聊天！

如需稍后重新配置单项设置，使用以下专用命令：

hermes model          # 选择 LLM 提供商和模型
hermes tools          # 配置启用的工具
hermes gateway setup  # 配置消息平台
hermes config set     # 设置单个配置项
hermes setup          # 或运行完整的设置向导一次性配置所有内容

最快路径：Nous Portal

一个订阅涵盖 300+ 个模型以及 Tool Gateway（网络搜索、图像生成、TTS、云端浏览器）。无需逐一管理各工具的密钥：

hermes setup --portal

该命令一次性完成登录、设置 Nous 为提供商并开启 Tool Gateway。

前置条件

POSIX 源码脚本需要 Git、curl、tar 和 SHA-256 工具。源码构建还可能需要编译器和系统库。

Hermes 要求 Python 3.14（>=3.14,<3.15），工具版本由 pm/lock.json 决定。

自包含桌面软件包不要求用户自行编译基础依赖。

Nix 用户

如果你使用 Nix（在 NixOS、macOS 或 Linux 上），有专门的配置路径，包含 Nix flake、声明式 NixOS 模块和可选容器模式。请参阅 Nix & NixOS 配置指南。

手动 / 开发者安装

如果你想克隆仓库并从源码安装——用于贡献代码、从特定分支运行或完全控制虚拟环境——请参阅贡献指南中的开发环境配置章节。

非 Sudo / 系统服务用户安装

以目标服务用户运行源码安装脚本。由管理员预先安装构建所需工具和 Chromium 的系统库。

当前脚本不运行 Playwright 的 --with-deps，也不提供按发行版选择的 sudo 回退。

安装后，将 $HOME/.local/bin 加入服务用户的 PATH，并运行 hermes doctor。

请使用脚本生成的包装器，不要硬编码 venv/bin/hermes。

Linux 用户服务需要在注销后继续运行时，由管理员为该用户启用 lingering。

详见消息 Gateway。

故障排查

| | 问题 | 解决方案

| hermes: command not found | 重新加载 shell（source ~/.bashrc）或检查 PATH

| API key not set | 运行 hermes model 配置提供商，或 hermes config set OPENROUTER_API_KEY your_key

| 更新后配置丢失 | 运行 hermes config check，然后运行 hermes config migrate

如需更多诊断信息，运行 hermes doctor——它会告诉你确切缺少什么以及如何修复。

安装方式自动检测

Hermes 会自动检测安装方式（git 安装程序、Docker 或 NixOS），hermes update 会打印对应路径的更新命令。无需设置任何环境变量——检测基于安装目录结构（~/.hermes/hermes-agent/ 检出、Docker 镜像标记或 Nix store 路径）。hermes doctor 也会在其环境摘要中显示检测到的安装方式。

学习路径

Hermes Agent 功能丰富——CLI 助手、Telegram/Discord 机器人、任务自动化、强化学习训练等。本页帮助您根据自身经验水平和目标，确定从哪里开始、阅读哪些内容。

从这里开始

如果您尚未安装 Hermes Agent，请先阅读安装指南，然后完成快速入门。以下内容均假设您已完成安装。

如何使用本页

已知自己的水平？跳转至按经验水平表格，按照对应层级的阅读顺序进行。
有明确目标？跳至按使用场景，找到匹配的场景。
随便浏览？查看主要功能表格，快速了解 Hermes Agent 的全部能力。

按经验水平

| | 水平 | 目标 | 推荐阅读 | 预计时间

| 初级 | 快速上手，进行基本对话，使用内置工具 | 安装 → 快速入门 → CLI 用法 → 配置 | 约 1 小时

| 中级 | 搭建消息机器人，使用记忆、cron 任务、技能等高级功能 | 会话 → 消息 → 工具 → 技能 → 记忆 → Cron | 约 2–3 小时

| 高级 | 构建自定义工具、创建技能、使用强化学习训练模型、参与项目贡献 | 架构 → 添加工具 → 创建技能 → 贡献指南 | 约 4–6 小时

按使用场景

选择与您目标匹配的场景，每个场景均按推荐顺序链接到相关文档。

"我想要一个 CLI 编程助手"

将 Hermes Agent 用作交互式终端助手，用于编写、审查和运行代码。

安装
快速入门
CLI 用法
代码执行
上下文文件
技巧与窍门

提示

通过上下文文件将文件直接传入对话。Hermes Agent 可以读取、编辑并运行您项目中的代码。

"我想要一个 Telegram/Discord 机器人"

将 Hermes Agent 部署为您常用消息平台上的机器人。

安装
配置
消息概览
Telegram 配置
Discord 配置
语音模式
在 Hermes 中使用语音模式
安全

完整项目示例请参阅：

每日简报机器人
团队 Telegram 助手

"我想自动化任务"

调度周期性任务、运行批处理作业，或将多个 agent 动作串联起来。

快速入门
Cron 调度
批处理
委派
Hooks

提示

Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检查、自动报告——无需您在场。

"我想构建自定义工具/技能"

通过自定义工具和可复用技能包扩展 Hermes Agent。

插件
构建 Hermes 插件
工具概览
技能概览
MCP（模型上下文协议）
架构
添加工具
创建技能

提示

对于大多数自定义工具的创建，建议从插件开始。添加工具页面面向 Hermes 核心内置开发，而非常规用户/自定义工具路径。

"我想训练模型"

使用强化学习（RL）通过 Hermes Agent 内置的 RL 训练流水线对模型行为进行微调。

快速入门
配置
Atropos 强化学习环境（外部）
Provider 路由
架构

提示

强化学习训练在您已了解 Hermes Agent 如何处理对话和工具调用的基础上效果最佳。如果您是新手，请先完成初级路径。

"我想将其作为 Python 库使用"

以编程方式将 Hermes Agent 集成到您自己的 Python 应用中。

安装
快速入门
Python 库指南
架构
工具
会话

主要功能一览

不确定有哪些功能？以下是主要功能的快速目录：

| | 功能 | 说明 | 链接

| 工具 | Agent 可调用的内置工具（文件 I/O、搜索、Shell 等） | 工具

| 技能 | 可安装的插件包，用于添加新能力 | 技能

| 记忆 | 跨会话的持久化记忆 | 记忆

| 上下文文件 | 将文件和目录传入对话 | 上下文文件

| MCP | 通过模型上下文协议连接外部工具服务器 | MCP

| Cron | 调度周期性 agent 任务 | Cron

| 委派 | 生成子 agent 以并行处理工作 | 委派

| 代码执行 | 运行以编程方式调用 Hermes 工具的 Python 脚本 | 代码执行

| 浏览器 | 网页浏览与抓取 | 浏览器

| Hooks | 事件驱动的回调与中间件 | Hooks

| 批处理 | 批量处理多个输入 | 批处理

| 强化学习训练 | 使用强化学习微调模型 | Atropos（外部）

| Provider 路由 | 在多个 LLM provider 之间路由请求 | Provider 路由

下一步阅读

根据您当前所处阶段：

刚完成安装？ → 前往快速入门，运行您的第一次对话。
完成了快速入门？ → 阅读 CLI 用法和配置，自定义您的设置。
已熟悉基础？ → 探索工具、技能和记忆，释放 agent 的全部能力。
为团队部署？ → 阅读安全和会话，了解访问控制与对话管理。
准备好开发了？ → 进入开发者指南，了解内部机制并开始贡献。
想要实际示例？ → 查看指南部分，获取真实项目案例和技巧。

提示

您无需阅读所有内容。选择与您目标匹配的路径，按顺序跟随链接，即可快速上手。随时可以回到本页寻找下一步。

Platform Support

Hermes Agent maintains support for many platforms and distribution methods, but we can't support every possible install method.

Tier 1

We strive to never break installations and updates for these. Issues & regressions in Tier 1 are our first priority and take precedence over other platforms.

| | OS / Architecture | Installation methods | Notes

| macOS (Apple Silicon) | Hermes Desktop, install.sh |

| Windows 10 / 11 (x86_64, aarch64) | install.ps1, MSIX desktop | The MSIX package requires Windows 11 22H2 or later. Optional dependencies have architecture limits.

| Linux / WSL2 (x86_64, aarch64) | install.sh | We test on the latest Ubuntu and WSL2. If your distro has glibc, systemd, and follows the Filesystem Hierarchy Standard, it's likely to work pretty well.

| Docker Container (x86_64, aarch64) | docker pull | Docker installs do not support hermes update. Updating is done by running a new image.

Tier 2

These platforms are maintained in-tree only as a best effort.

Releases may break them, and we can't promise we'll fix them promptly when they break.

PRs will be accepted to fix issues with them, but they will take precedence below fixing issues with Tier 1 platforms.

| | OS / Architecture | Installation methods | Notes

| Nix (macOS, Linux, NixOS) | Nix flake and modules | Nix owns runtime installation and updates.

| Android / Termux (aarch64) | Signed APT repository, then pkg install hermes-agent | Prerelease package with Python, Node, and TUI. Not built by default: only releases cut with --with termux (and windows and macos-arm64) update the APT channel. Run the gateway in a Termux session; Android can terminate background processes.

Build targets and support priority

Stable releases build the macOS desktop bundle for Apple Silicon (arm64) only.

The Intel macOS (x64) bundle and the Termux APT package are not built by

default: a release includes them only when it is cut with

release.py release --with macos-intel or --with termux. A release

without macOS Intel replaces the one shared macOS stable update feed with an

arm64-only feed, so Intel Macs installed from a desktop bundle get no update

until a release is cut with --with macos-intel. A release without Termux

leaves the Termux APT channel on its previous release.

The Hermes-Setup.dmg bootstrap installer is built for Apple Silicon only, so

on an Intel Mac it reports "not supported on this Mac". Intel Macs can install

the CLI and run

hermes desktop, or use a darwin-x64 bundle from a release that included it.

Linux desktop packaging is disabled in the release workflow, although local

AppImage builds and native Linux PM bundle checks exist.

Unsupported

These platforms and distribution methods are not supported.

We suggest that you migrate to a supported distribution method or platform.

They may be broken right now, they may break more in the future.

PRs to fix them will not be accepted, and any code that keeps compatibility with them may be removed at any point.

Android / Termux on non-aarch64 devices (aarch64 is supported via our APT package)
installs via the AUR (we might upstream patches if it helps out <3)
32-bit x86 macOS. Intel x86_64 desktop bundles are built only for releases cut with --with macos-intel.
installs via pypi (e.g. uv tool install hermes-agent, pip install hermes-agent, etc.)
installs via brew (brew install hermes-agent)

If you are using an unsupported distribution method, please read the the installation guide to learn how to switch to a supported one.

在 Android 上使用 Termux

Hermes 的 Termux 软件包适用于 aarch64（arm64-v8a）设备，目前处于预发布测试阶段。

它包含 Python、Node.js、npm、uv、ripgrep、FFmpeg 和核心 Python 依赖。

安装时无需在手机上编译核心依赖或组装 Python 环境。

请使用标准 Termux 应用和前缀 /data/data/com.termux/files/usr。

其他架构或更改应用包名的 Termux 版本不受支持。

桌面和服务器的 install.sh 不是此平台的安装路径。

安装

安装仓库配置工具：

pkg install curl gnupg

下载公钥：

mkdir -p "$PREFIX/etc/apt/keyrings"
curl -fsSL \
  https://hermes-assets.nousresearch.com/releases/termux/canary/key.asc \
  -o "$PREFIX/etc/apt/keyrings/hermes-agent.asc"

检查主密钥指纹：

gpg --show-keys --with-fingerprint "$PREFIX/etc/apt/keyrings/hermes-agent.asc"

预期指纹：

C572 B5FD D1A2 9CCF A9A9 12B6 840B 0848 E139 156D

如果不一致，请停止。不要禁用签名验证。

添加 canary 仓库：

printf '%s\n' \
  "deb [signed-by=$PREFIX/etc/apt/keyrings/hermes-agent.asc] https://hermes-assets.nousresearch.com/releases/termux/canary hermes-canary main" \
  > "$PREFIX/etc/apt/sources.list.d/hermes-agent.list"

安装并配置：

pkg update
pkg install hermes-agent
hermes setup
hermes --tui

数据、更新和卸载

软件包位于 $PREFIX/lib/hermes-agent/。

$PREFIX/bin/ 中的 hermes、hermes-agent 和 hermes-acp 链接使用包内运行时。

它们不依赖 Termux 的 Python 或 Node.js 软件包。

数据位于 ~/.hermes/，或所选 HERMES_HOME。

pkg update
pkg upgrade hermes-agent

hermes update 拒绝修改 APT 所有的代码，改由包管理器更新。

Canary 版本带有 ~canary.TIMESTAMP，排序低于对应的正式版本。

卸载应用软件包：

pkg uninstall hermes-agent

APT 移除软件包和命令链接，但保留用户配置、会话、技能和记忆。

Gateway 和限制

使用 hermes gateway run 在 Termux 会话中运行 gateway。

当前 APT 路径不提供 systemd、launchd 或 Windows 计划任务。

Android 可能挂起或终止后台进程；唤醒锁不保证持续运行。

该包不包含 nemo-relay 导出器，也不包含 Electron 桌面应用。

本地 Chromium、桌面控制、Docker daemon 和音频设备集成不能因核心 CLI 可运行就视为可用。

第三方插件仍可能需要 Android 不支持的依赖。

故障排查时运行 hermes doctor，并提供 hermes --version 和完整错误。

缺少包内核心库或 TUI 输出属于软件包问题，不应要求用户重新编译。

更新与卸载

更新

使用单条命令更新至最新版本：

hermes update

官方仓库的源码安装默认跟踪 stable 渠道：最新正式发布的 vX.Y.Z GitHub 版本（不含草稿、预发布或 canary 标签），并检出其确切提交。hermes update 和桌面应用的更新按钮只会在正式版本之间升级，不再逐个提交跟进。Fork 和镜像仍跟踪各自的 main 分支。此命令还会更新依赖项，并提示你配置自上次更新以来新增的选项。

hermes update --set-channel main     # 改为跟踪 main 上的每个提交
hermes update --set-channel stable   # 恢复为仅正式版本

从未选择渠道的安装只会向前更新：已经比最新正式版本更新的检出（例如此前跟踪 main 的安装）会保持不动，直到发布更新的版本。显式运行 --set-channel stable 会把检出固定到该版本的确切提交，即使它更旧。Windows 应用商店、MSIX 和捆绑桌面安装不受影响。

提示

hermes update 会自动检测新的配置选项并提示你添加。如果跳过了该提示，可手动运行 hermes config check 查看缺失的选项，再运行 hermes config migrate 以交互方式添加。

更新过程

运行 hermes update 时，将依次执行以下步骤：

更新前快照 — Hermes 在每个 profile 的 state-snapshots/ 目录中保存指定的状态文件，包括配对数据、cron 任务、config.yaml、.env 和 auth.json。自动快速快照会跳过单个大于 1 GiB 的文件。updates.pre_update_backup 可选择 quick、full 或 off。完整归档遵循备份排除规则。恢复方法见快照与回滚。快速快照恢复的是状态文件，不是应用程序代码。
代码更新 — 检出所选渠道的目标（默认最新 stable 版本）并更新子模块
依赖安装 — 运行 python -m pm.cli install 以获取新增或变更的依赖项
配置迁移 — 检测自当前版本以来新增的配置选项并提示设置
Gateway 自动重启 — 更新完成后刷新正在运行的 gateway，使新代码立即生效。由服务管理的 gateway（Linux 上的 systemd、macOS 上的 launchd）通过服务管理器重启；手动启动的 gateway 在 Hermes 能将运行中的 PID 映射回某个 profile 时会自动重新启动。

仅预览：hermes update --check

想在拉取前确认是否有更新？运行 hermes update --check — 它会与所选渠道的目标（默认最新 stable 版本，main 渠道为 origin/main）比较。不修改任何文件，不重启 gateway。适合在以"是否有更新"为条件的脚本和 cron 任务中使用。

完整更新前备份：--backup

对于高价值 profile（生产环境 gateway、团队共享安装），可选择在拉取前对 HERMES_HOME（配置、认证、会话、技能、配对数据）进行完整备份：

hermes update --backup

或将其设为每次运行的默认行为：

# ~/.hermes/config.yaml
updates:
  pre_update_backup: full

updates.pre_update_backup 有三种模式：

quick 保存上述指定的状态文件。这是默认模式。
full 另加一份遵循备份排除规则的 zip 归档。大型数据目录可能需要几分钟。
off 禁用更新前备份。--no-backup 为单次运行选择此模式。

旧版布尔值仍然有效：true 等同于 full，false 等同于 off。

Windows：另一个 hermes.exe 正在运行

在 Windows 上，如果 hermes update 检测到另一个 hermes.exe 进程持有 venv 入口点可执行文件的句柄，它将拒绝运行 — 最常见的情况是 Hermes Desktop 应用启动的后端进程、另一个终端中打开的 hermes REPL，或正在运行的 gateway：

$ hermes update
✗ Another hermes.exe is running:
    PID 12345  hermes.exe

  Updating now would fail to overwrite ...\venv\Scripts\hermes.exe because
  Windows blocks REPLACE on a running executable.

  Close Hermes Desktop, exit any open `hermes` REPLs, and
  stop the gateway (`hermes gateway stop`) before retrying.
  Override with `hermes update --force` if you've already
  confirmed those processes will not write to the venv.

关闭列出的进程后重试。如果你确定并发进程不会造成干扰（极少见 — 通常仅在杀毒软件 shim 被误判时有用），可传入 --force 跳过检查。此时更新程序仍会以指数退避方式重试 .exe 重命名操作，对于顽固的文件锁，会通过 MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT) 将替换操作安排在下次重启时执行，以确保更新能够完成。

预期输出如下：

$ hermes update
Updating Hermes Agent...
📥 Pulling latest code...
Already up to date.  (or: Updating abc1234..def5678)
📦 Updating dependencies...
✅ Dependencies updated
🔍 Checking for new config options...
✅ Config is up to date  (or: Found 2 new options — running migration...)
🔄 Restarting gateways...
✅ Gateway restarted
✅ Hermes Agent updated successfully!

更新后建议的验证步骤

hermes update 处理主要的更新流程，但快速验证可确认一切正常落地：

git status --short — 若工作树出现意外的脏状态，请在继续前检查
hermes doctor — 检查配置、依赖项和服务健康状态
hermes --version — 确认版本已按预期更新
如果使用 gateway：hermes gateway status
如果 doctor 报告 npm audit 问题：在标记的目录中运行 npm audit fix

更新后工作树出现脏状态

如果 hermes update 后 git status --short 显示意外变更，请在继续前停下来检查。这通常意味着本地修改被重新应用到了更新后的代码之上，或依赖步骤刷新了锁文件。

终端在更新中途断开连接

hermes update 针对意外终端断开进行了保护：

更新会忽略 SIGHUP，因此关闭 SSH 会话或终端窗口不再会在安装中途终止它。pip 和 git 子进程继承此保护，因此 Python 环境不会因连接断开而处于半安装状态。
更新运行期间，所有输出会同步镜像到 ~/.hermes/logs/update.log。如果终端消失，重新连接后检查日志，确认更新是否完成以及 gateway 重启是否成功：

tail -f ~/.hermes/logs/update.log

Ctrl-C（SIGINT）和系统关机（SIGTERM）仍会被响应 — 这些是主动取消操作，而非意外中断。

你不再需要将 hermes update 包裹在 screen 或 tmux 中来应对终端断开。

查看当前版本

hermes --version

与 GitHub releases 页面上的最新版本进行比较。

从消息平台更新

你也可以直接从 Telegram、Discord、Slack、WhatsApp 或 Teams 发送以下命令进行更新：

/update

此命令会拉取最新代码、更新依赖项并重启正在运行的 gateway。Bot 在重启期间会短暂下线（通常为 5–15 秒），之后恢复服务。

手动更新

如果你是手动安装的（未使用快速安装脚本）：

cd /path/to/hermes-agent
export VIRTUAL_ENV="$(pwd)/venv"

# Pull latest code
git pull origin main

# Reinstall (picks up new dependencies)
python -m pm.cli install

# Check for new config options
hermes config check
hermes config migrate   # Interactively add any missing options

回滚说明

如果更新引入了问题，可以回滚到之前的版本：

cd /path/to/hermes-agent

# List recent versions
git log --oneline -10

# Roll back to a specific commit
git checkout <commit-hash>
python -m pm.cli install

# Restart the gateway if running
hermes gateway restart

回滚到特定发布标签：

git checkout v0.6.0
python -m pm.cli install

注意

如果新增了配置选项，回滚可能导致配置不兼容。回滚后运行 hermes config check，如果遇到错误，请从 config.yaml 中删除无法识别的选项。

Nix 用户注意事项

如果你通过 Nix flake 安装，更新由 Nix 包管理器负责：

# Update the flake input
nix flake update hermes-agent

# Or rebuild with the latest
nix profile upgrade hermes-agent

Nix 安装是不可变的 — 回滚由 Nix 的 generation 系统处理：

nix profile rollback

详情参见 Nix 安装。

卸载

hermes uninstall

卸载程序会提供选项，让你保留配置文件（~/.hermes/）以便将来重新安装。

手动卸载

rm -f ~/.local/bin/hermes
rm -rf /path/to/hermes-agent
rm -rf ~/.hermes            # 可选 — 如计划重新安装则保留

信息

如果你将 gateway 安装为系统服务，请先停止并禁用它：

hermes gateway stop
# Linux: systemctl --user disable hermes-gateway
# macOS: launchctl remove ai.hermes.gateway

Nix & NixOS 安装配置

Hermes Agent 提供了一个 Nix flake，支持三个层级的集成：

| | 层级 | 适用对象 | 提供内容

| nix run / nix profile install | 任意 Nix 用户（macOS、Linux） | 包含所有依赖的预构建二进制文件——然后使用标准 CLI 工作流

| NixOS 模块（原生） | NixOS 服务器部署 | 声明式配置、加固的 systemd 服务、托管密钥

| NixOS 模块（容器） | 需要自我修改能力的 Agent | 以上所有功能，加上一个持久化 Ubuntu 容器，Agent 可在其中执行 apt/pip/npm install

与标准安装的区别

curl | bash 安装程序自行管理 Python、Node 及依赖项。Nix flake 替代了所有这些——每个 Python 依赖都是由 uv2nix 构建的 Nix derivation，运行时工具（Node.js、git、ripgrep、ffmpeg）已封装进二进制文件的 PATH 中。不需要运行时 pip，不需要激活 venv，不需要 npm install。

对于非 NixOS 用户，这只影响安装步骤。之后的操作（hermes setup、hermes gateway install、编辑配置）与标准安装完全相同。

对于 NixOS 模块用户，整个生命周期有所不同：配置存放在 configuration.nix 中，密钥通过 sops-nix/agenix 管理，服务是一个 systemd 单元，CLI 配置命令被屏蔽。管理 hermes 的方式与管理其他 NixOS 服务相同。

PM 固定版本

nix/npm-pinned.nix 和 nix/pm-packages.nix 读取 PM 锁文件。

nix build .#pm-ripgrep 等输出解包对应的固定归档，不等于完整应用或所有平台的运行证明。

应用仍由 uv2nix 环境和 Nix 包装器组成。

nix/pythonLock.nix 从 pm/lock.json 读取 Python 主/次版本。

uv2nix 环境、覆盖包、插件依赖和开发 shell 使用同一个解释器系列。

如果固定的 nixpkgs 不提供该系列，求值直接失败，不回退到其他 Python。

原生 Nix 求值和构建仍由 CI 验证。通过 Nix 更新，不要向 Nix store 执行 pip 安装。

前提条件

已启用 flakes 的 Nix — 推荐使用 Determinate Nix（默认启用 flakes）
API 密钥，用于你想使用的服务（至少需要一个 OpenRouter 或 Anthropic 密钥）

快速开始（任意 Nix 用户）

无需克隆仓库。Nix 会自动获取、构建并运行所有内容：

# 直接运行（首次使用时构建，之后使用缓存）
nix run github:NousResearch/hermes-agent -- setup
nix run github:NousResearch/hermes-agent -- chat

# 或持久化安装
nix profile install github:NousResearch/hermes-agent
hermes setup
hermes chat

执行 nix profile install 后，hermes、hermes-agent 和 hermes-acp 将出现在你的 PATH 中。之后的工作流与标准安装完全相同——hermes setup 引导你完成提供商选择，hermes gateway install 设置 launchd（macOS）或 systemd 用户服务，配置存放在 ~/.hermes/。

从本地克隆构建

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
nix build
./result/bin/hermes setup

NixOS 模块

该 flake 导出 nixosModules.default——一个完整的 NixOS 服务模块，以声明式方式管理用户创建、目录、配置生成、密钥、文档和服务生命周期。

备注

此模块需要 NixOS。对于非 NixOS 系统（macOS、其他 Linux 发行版），请使用 nix profile install 和上述标准 CLI 工作流。

添加 Flake 输入

# /etc/nixos/flake.nix（或你的系统 flake）
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hermes-agent.url = "github:NousResearch/hermes-agent";
  };

  outputs = { nixpkgs, hermes-agent, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        hermes-agent.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

最小化配置

# configuration.nix
{ config, ... }: {
  services.hermes-agent = {
    enable = true;
    settings.model.default = "anthropic/claude-sonnet-4";
    environmentFiles = [ config.sops.secrets."hermes-env".path ];
    addToSystemPackages = true;
  };
}

就这些。nixos-rebuild switch 会创建 hermes 用户、生成 config.yaml、连接密钥并启动 gateway——这是一个长期运行的服务，将 Agent 连接到消息平台（Telegram、Discord 等）并监听传入消息。

密钥是必需的

上面的 environmentFiles 行假设你已配置 sops-nix 或 agenix。该文件至少应包含一个 LLM 提供商密钥（例如 OPENROUTER_API_KEY=sk-or-...）。完整设置请参阅密钥管理。如果你还没有密钥管理器，可以先使用普通文件——只需确保它不是全局可读的：

echo "OPENROUTER_API_KEY=sk-or-your-key" | sudo install -m 0600 -o hermes /dev/stdin /var/lib/hermes/env

services.hermes-agent.environmentFiles = [ "/var/lib/hermes/env" ];

addToSystemPackages

设置 addToSystemPackages = true 有两个作用：将 hermes CLI 添加到系统 PATH，并在系统范围内设置 HERMES_HOME，使交互式 CLI 与 gateway 服务共享状态（会话、技能、cron）。不设置此项时，在 shell 中运行 hermes 会创建独立的 ~/.hermes/ 目录。

容器感知 CLI

信息

当 container.enable = true 且 addToSystemPackages = true 时，主机上的所有 hermes 命令都会自动路由到托管容器中执行。这意味着你的交互式 CLI 会话在与 gateway 服务相同的环境中运行——可以访问所有容器内安装的包和工具。

路由是透明的：hermes chat、hermes sessions list、hermes --version 等命令都会在底层 exec 进容器
所有 CLI 参数原样转发
如果容器未运行，CLI 会短暂重试（交互式使用时显示 5 秒 spinner，脚本中静默等待 10 秒），然后以明确的错误退出——不会静默回退
对于在 hermes 代码库上工作的开发者，设置 HERMES_DEV=1 可绕过容器路由，直接运行本地检出版本

设置 container.hostUsers 可创建 ~/.hermes 到服务状态目录的符号链接，使主机 CLI 和容器共享会话、配置和记忆：

services.hermes-agent = {
  container.enable = true;
  container.hostUsers = [ "your-username" ];
  addToSystemPackages = true;
};

hostUsers 中列出的用户会自动加入 hermes 组以获得文件权限访问。

Podman 用户： NixOS 服务以 root 身份运行容器。Docker 用户通过 docker 组 socket 获得访问权限，但 Podman 的 rootful 容器需要 sudo。为你的容器运行时授予免密 sudo：

security.sudo.extraRules = [{
  users = [ "your-username" ];
  commands = [{
    command = "/run/current-system/sw/bin/podman";
    options = [ "NOPASSWD" ];
  }];
}];

CLI 会自动检测何时需要 sudo 并透明地使用它。没有此配置，你需要手动运行 sudo hermes chat。

验证运行状态

执行 nixos-rebuild switch 后，检查服务是否正在运行：

# 检查服务状态
systemctl status hermes-agent

# 查看日志（Ctrl+C 停止）
journalctl -u hermes-agent -f

# 如果 addToSystemPackages 为 true，测试 CLI
hermes --version
hermes config       # 显示生成的配置

选择部署模式

模块支持两种模式，由 container.enable 控制：

| | | 原生（默认） | 容器

| 运行方式 | 主机上加固的 systemd 服务 | 持久化 Ubuntu 容器，/nix/store 以只读方式绑定挂载

| 安全性 | NoNewPrivileges、ProtectSystem=strict、PrivateTmp | 容器隔离，内部以非特权用户运行

| Agent 可自行安装包 | 否——仅限 Nix 提供的 PATH 上的工具 | 是——apt、pip、npm 安装的包在重启后持久保留

| 配置界面 | 相同 | 相同

| 适用场景 | 标准部署、最高安全性、可重现性 | Agent 需要运行时安装包、可变环境、实验性工具

启用容器模式只需添加一行：

{
  services.hermes-agent = {
    enable = true;
    container.enable = true;
    # ... 其余配置相同
  };
}

信息

容器模式通过 mkDefault 自动启用 virtualisation.docker.enable。如果你使用 Podman，请设置 container.backend = "podman" 并将 virtualisation.docker.enable 设为 false。

配置

声明式设置

settings 选项接受任意 attrset，并将其渲染为 config.yaml。它支持跨多个模块定义的深度合并（通过 lib.recursiveUpdate），因此你可以将配置拆分到多个文件中：

# base.nix
services.hermes-agent.settings = {
  model.default = "anthropic/claude-sonnet-4";
  toolsets = [ "all" ];
  terminal = { backend = "local"; timeout = 180; };
};

# personality.nix
services.hermes-agent.settings = {
  display = { compact = false; personality = "kawaii"; };
  memory = { memory_enabled = true; user_profile_enabled = true; };
};

两者在求值时深度合并。Nix 声明的键始终优先于磁盘上现有 config.yaml 中的键，但 Nix 未涉及的用户添加键会被保留。这意味着如果 Agent 或手动编辑添加了 skills.disabled 或 streaming.enabled 等键，它们在 nixos-rebuild switch 后仍会保留。

模型命名

settings.model.default 使用你的提供商所期望的模型标识符。使用 OpenRouter（默认）时，格式如 "anthropic/claude-sonnet-4" 或 "google/gemini-3-flash"。如果直接使用提供商（Anthropic、OpenAI），请将 settings.model.base_url 指向其 API，并使用其原生模型 ID（例如 "claude-sonnet-4-20250514"）。未设置 base_url 时，Hermes 默认使用 OpenRouter。

查找可用配置键

运行 nix build .#configKeys && cat result 可查看从 Python DEFAULT_CONFIG 中提取的所有叶配置键。你可以将现有的 config.yaml 粘贴到 settings attrset 中——结构是 1:1 对应的。

完整示例：所有常用自定义设置

{ config, ... }: {
  services.hermes-agent = {
    enable = true;
    container.enable = true;

    # ── 模型 ──────────────────────────────────────────────────────────
    settings = {
      model = {
        base_url = "https://openrouter.ai/api/v1";
        default = "anthropic/claude-opus-4.6";
      };
      toolsets = [ "all" ];
      max_turns = 100;
      terminal = { backend = "local"; cwd = "."; timeout = 180; };
      compression = {
        enabled = true;
        threshold = 0.85;
        summary_model = "google/gemini-3-flash-preview";
      };
      memory = { memory_enabled = true; user_profile_enabled = true; };
      display = { compact = false; personality = "kawaii"; };
      agent = { max_turns = 60; verbose = false; };
    };

    # ── 密钥 ────────────────────────────────────────────────────────
    environmentFiles = [ config.sops.secrets."hermes-env".path ];

    # ── 文档 ──────────────────────────────────────────────────────────
    documents = {
      "USER.md" = ./documents/USER.md;
    };

    # ── MCP 服务器 ────────────────────────────────────────────────────
    mcpServers.filesystem = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
    };

    # ── 容器选项 ──────────────────────────────────────────────────────
    container = {
      image = "ubuntu:24.04";
      backend = "docker";
      hostUsers = [ "your-username" ];
      extraVolumes = [ "/home/user/projects:/projects:rw" ];
      extraOptions = [ "--gpus" "all" ];
    };

    # ── 服务调优 ─────────────────────────────────────────────────────
    addToSystemPackages = true;
    extraArgs = [ "--verbose" ];
    restart = "always";
    restartSec = 5;
  };
}

逃生舱：自带配置文件

如果你希望完全在 Nix 之外管理 config.yaml，请使用 configFile：

services.hermes-agent.configFile = /etc/hermes/config.yaml;

这会完全绕过 settings——不合并，不生成。每次激活时，该文件会原样复制到 $HERMES_HOME/config.yaml。

自定义速查表

Nix 用户最常见自定义需求的快速参考：

| | 我想要... | 选项 | 示例

| 更改 LLM 模型 | settings.model.default | "anthropic/claude-sonnet-4"

| 使用不同的提供商端点 | settings.model.base_url | "https://openrouter.ai/api/v1"

| 添加 API 密钥 | environmentFiles | [ config.sops.secrets."hermes-env".path ]

| 给 Agent 设置个性 | ${services.hermes-agent.stateDir}/.hermes/SOUL.md | 直接管理该文件

| 添加 MCP 工具服务器 | mcpServers.<name> | 参见 MCP 服务器

| 将主机目录挂载到容器 | container.extraVolumes | [ "/data:/data:rw" ]

| 为容器传入 GPU 访问 | container.extraOptions | [ "--gpus" "all" ]

| 使用 Podman 替代 Docker | container.backend | "podman"

| 在主机 CLI 和容器间共享状态 | container.hostUsers | [ "sidbin" ]

| 为 Agent 提供额外工具 | extraPackages | [ pkgs.pandoc pkgs.imagemagick ]

| 使用自定义基础镜像 | container.image | "ubuntu:24.04"

| 覆盖 hermes 包 | package | inputs.hermes-agent.packages.${system}.default.override { ... }

| 更改状态目录 | stateDir | "/opt/hermes"

| 设置 Agent 的工作目录 | workingDirectory | "/home/user/projects"

密钥管理

切勿将 API 密钥放入 settings 或 environment

Nix 表达式中的值会进入 /nix/store，该目录是全局可读的。请始终使用带有密钥管理器的 environmentFiles。

environment（非密钥变量）和 environmentFiles（密钥文件）在激活时（nixos-rebuild switch）都会合并到 $HERMES_HOME/.env 中。Hermes 在每次启动时读取此文件，因此更改在 systemctl restart hermes-agent 后生效——无需重建容器。

sops-nix

{
  sops = {
    defaultSopsFile = ./secrets/hermes.yaml;
    age.keyFile = "/home/user/.config/sops/age/keys.txt";
    secrets."hermes-env" = { format = "yaml"; };
  };

  services.hermes-agent.environmentFiles = [
    config.sops.secrets."hermes-env".path
  ];
}

密钥文件包含键值对：

# secrets/hermes.yaml（使用 sops 加密）
hermes-env: |
    OPENROUTER_API_KEY=sk-or-...
    TELEGRAM_BOT_TOKEN=123456:ABC...
    ANTHROPIC_API_KEY=sk-ant-...

agenix

{
  age.secrets.hermes-env.file = ./secrets/hermes-env.age;

  services.hermes-agent.environmentFiles = [
    config.age.secrets.hermes-env.path
  ];
}

OAuth / 认证预置

对于需要 OAuth 的平台（例如 Discord），使用 authFile 在首次部署时预置凭据：

{
  services.hermes-agent = {
    authFile = config.sops.secrets."hermes/auth.json".path;
    # authFileForceOverwrite = true;  # 每次激活时强制覆盖
  };
}

仅当 auth.json 不存在时才复制该文件（除非 authFileForceOverwrite = true）。运行时 OAuth token 刷新会写入状态目录，并在重建后保留。

文档

documents 选项将文件安装到 Agent 的工作目录（即 workingDirectory，Agent 将其作为工作区读取）。Hermes 按约定查找特定文件名：

USER.md — 关于 Agent 正在交互的用户的上下文信息。
你放置在此处的任何其他文件对 Agent 都可见，作为工作区文件。

Agent 身份文件是独立的：Hermes 从 $HERMES_HOME/SOUL.md 加载其主要 SOUL.md，在 NixOS 模块中对应 ${services.hermes-agent.stateDir}/.hermes/SOUL.md。将 SOUL.md 放入 documents 只会创建一个工作区文件，不会替换主角色文件。

{
  services.hermes-agent.documents = {
    "USER.md" = ./documents/USER.md;  # 路径引用，从 Nix store 复制
  };
}

值可以是内联字符串或路径引用。文件在每次 nixos-rebuild switch 时安装。

MCP 服务器

mcpServers 选项以声明式方式配置 MCP（Model Context Protocol，模型上下文协议）服务器。每个服务器使用 stdio（本地命令）或 HTTP（远程 URL）传输方式。

stdio 传输（本地服务器）

{
  services.hermes-agent.mcpServers = {
    filesystem = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
    };
    github = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-github" ];
      env.GITHUB_PERSONAL_ACCESS_TOKEN = "\${GITHUB_TOKEN}"; # 从 .env 解析
    };
  };
}

提示

env 值中的环境变量在运行时从 $HERMES_HOME/.env 解析。使用 environmentFiles 注入密钥——切勿将 token 直接放入 Nix 配置。

HTTP 传输（远程服务器）

{
  services.hermes-agent.mcpServers.remote-api = {
    url = "https://mcp.example.com/v1/mcp";
    headers.Authorization = "Bearer \${MCP_REMOTE_API_KEY}";
    timeout = 180;
  };
}

带 OAuth 的 HTTP 传输

对于使用 OAuth 2.1 的服务器，设置 auth = "oauth"。Hermes 实现了完整的 PKCE 流程——元数据发现、动态客户端注册、token 交换和自动刷新。

{
  services.hermes-agent.mcpServers.my-oauth-server = {
    url = "https://mcp.example.com/mcp";
    auth = "oauth";
  };
}

Token 存储在 $HERMES_HOME/mcp-tokens/<server-name>.json 中，在重启和重建后持久保留。

无头服务器上的初始 OAuth 授权首次 OAuth 授权需要基于浏览器的同意流程。在无头部署中，Hermes 将授权 URL 打印到 stdout/日志，而不是打开浏览器。

方案 A：交互式引导 — 通过 docker exec（容器）或 sudo -u hermes（原生）运行一次流程：

# 容器模式
docker exec -it hermes-agent \
  hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth

# 原生模式
sudo -u hermes HERMES_HOME=/var/lib/hermes/.hermes \
  hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth

容器使用 --network=host，因此 127.0.0.1 上的 OAuth 回调监听器可从主机浏览器访问。

方案 B：预置 token — 在工作站上完成流程，然后复制 token：

hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth
scp ~/.hermes/mcp-tokens/my-oauth-server{,.client}.json \
    server:/var/lib/hermes/.hermes/mcp-tokens/
# 确保：chown hermes:hermes，chmod 0600

Sampling（服务器发起的 LLM 请求）

部分 MCP 服务器可以向 Agent 请求 LLM 补全：

{
  services.hermes-agent.mcpServers.analysis = {
    command = "npx";
    args = [ "-y" "analysis-server" ];
    sampling = {
      enabled = true;
      model = "google/gemini-3-flash";
      max_tokens_cap = 4096;
      timeout = 30;
      max_rpm = 10;
    };
  };
}

托管模式

当 hermes 通过 NixOS 模块运行时，以下 CLI 命令会被屏蔽，并显示指向 configuration.nix 的描述性错误：

| | 被屏蔽的命令 | 原因

| hermes setup | 配置是声明式的——请在 Nix 配置中编辑 settings

| hermes config edit | 配置由 settings 生成

| hermes config set <key> <value> | 配置由 settings 生成

| hermes gateway install | systemd 服务由 NixOS 管理

| hermes gateway uninstall | systemd 服务由 NixOS 管理

这可以防止 Nix 声明的内容与磁盘上实际内容之间产生漂移。检测使用两个信号：

HERMES_MANAGED=true 环境变量——由 systemd 服务设置，对 gateway 进程可见
.managed 标记文件，位于 HERMES_HOME 中——由激活脚本设置，对交互式 shell 可见（例如 docker exec -it hermes-agent hermes config set ... 也会被屏蔽）

要更改配置，请编辑你的 Nix 配置并运行 sudo nixos-rebuild switch。

容器架构

信息

本节仅在使用 container.enable = true 时相关。原生模式部署可跳过。

启用容器模式后，hermes 在持久化 Ubuntu 容器内运行，Nix 构建的二进制文件以只读方式从主机绑定挂载：

主机                                    容器
────                                    ─────────
/nix/store/...-hermes-agent-0.1.0  ──►  /nix/store/... (ro)
~/.hermes -> /var/lib/hermes/.hermes       （符号链接桥接，按 hostUsers）
/var/lib/hermes/                    ──►  /data/          (rw)
  ├── current-package -> /nix/store/...    （符号链接，每次重建更新）
  ├── .gc-root -> /nix/store/...           （防止 nix-collect-garbage）
  ├── .container-identity                  （sha256 哈希，触发重建）
  ├── .hermes/                             （HERMES_HOME）
  │   ├── .env                             （从 environment + environmentFiles 合并）
  │   ├── config.yaml                      （Nix 生成，激活时深度合并）
  │   ├── .managed                         （标记文件）
  │   ├── .container-mode                  （路由元数据：backend、exec_user 等）
  │   ├── state.db, sessions/, memories/   （运行时状态）
  │   └── mcp-tokens/                      （MCP 服务器的 OAuth token）
  ├── home/                                ──►  /home/hermes    (rw)
  └── workspace/                           （MESSAGING_CWD）
      ├── SOUL.md                          （来自 documents 选项）
      └── （Agent 创建的文件）

容器可写层（apt/pip/npm）：   /usr, /usr/local, /tmp

Nix 构建的二进制文件能在 Ubuntu 容器内运行，是因为 /nix/store 被绑定挂载——它携带自己的解释器和所有依赖，不依赖容器的系统库。容器入口点通过 current-package 符号链接解析：/data/current-package/bin/hermes gateway run --replace。执行 nixos-rebuild switch 时，只更新符号链接——容器继续运行。

各事件的持久性

| systemctl restart hermes-agent | 否 | 保留 | 保留 | 保留

| nixos-rebuild switch（代码变更） | 否（更新符号链接） | 保留 | 保留 | 保留

| 主机重启 | 否 | 保留 | 保留 | 保留

| nix-collect-garbage | 否（GC root） | 保留 | 保留 | 保留

| 镜像变更（container.image） | 是 | 保留 | 保留 | 丢失

| 卷/选项变更 | 是 | 保留 | 保留 | 丢失

| environment/environmentFiles 变更 | 否 | 保留 | 保留 | 保留

仅当容器的身份哈希发生变化时才会重建容器。哈希涵盖：schema 版本、镜像、extraVolumes、extraOptions 和入口点脚本。环境变量、settings、文档或 hermes 包本身的变更不会触发重建。

可写层丢失

当身份哈希发生变化（镜像升级、新卷、新容器选项）时，容器会被销毁并从 container.image 的全新拉取重建。可写层中通过 apt install、pip install 或 npm install 安装的包将丢失。/data 和 /home/hermes 中的状态会保留（这些是绑定挂载）。

如果 Agent 依赖特定包，考虑将其烘焙到自定义镜像中（container.image = "my-registry/hermes-base:latest"），或在 Agent 的 SOUL.md 中编写安装脚本。

GC Root 保护

preStart 脚本在 ${stateDir}/.gc-root 创建一个指向当前 hermes 包的 GC root。这可以防止 nix-collect-garbage 删除正在运行的二进制文件。如果 GC root 损坏，重启服务会重新创建它。

插件

NixOS 模块支持声明式插件安装——无需命令式的 hermes plugins install。

目录插件（extraPlugins）

对于只包含 plugin.yaml + __init__.py 的源码树插件（例如 hermes-lcm）：

services.hermes-agent.extraPlugins = [
  (pkgs.fetchFromGitHub {
    owner = "stephenschoettler";
    repo = "hermes-lcm";
    rev = "v0.7.0";
    hash = "sha256-...";
  })
];

插件在激活时以符号链接方式安装到 $HERMES_HOME/plugins/。Hermes 通过其正常的目录扫描发现它们。从列表中移除插件并运行 nixos-rebuild switch 会删除符号链接。

入口点插件（extraPythonPackages）

对于通过 [project.entry-points."hermes_agent.plugins"] 注册的 pip 打包插件（例如 rtk-hermes）：

services.hermes-agent.extraPythonPackages = [
  (config.services.hermes-agent.package.python.pkgs.buildPythonPackage {
    pname = "rtk-hermes";
    version = "1.0.0";
    src = pkgs.fetchFromGitHub {
      owner = "ogallotti";
      repo = "rtk-hermes";
      rev = "v1.0.0";
      hash = "sha256-...";
    };
    format = "pyproject";
    build-system = [ config.services.hermes-agent.package.python.pkgs.setuptools ];
  })
];

该包的 site-packages 会添加到 hermes wrapper 的 PYTHONPATH 中。importlib.metadata 在会话启动时发现入口点。

可选依赖组（extraDependencyGroups）

对于已在 hermes-agent 的 pyproject.toml 中声明的可选 extras（例如 honcho 等记忆提供商），使用 extraDependencyGroups 在构建时将其包含到封闭的 venv 中：

services.hermes-agent = {
  extraDependencyGroups = [ "honcho" ];
  settings.memory.provider = "honcho";
};

这由 uv 与核心依赖在单次解析中完成——不需要 PYTHONPATH 补丁，没有冲突风险。可用的组与 pyproject.toml 中 [project.optional-dependencies] 的键对应（例如 "honcho"、"voice"、"matrix"、"mistral"、"bedrock"）。

何时使用哪个：

| | 需求 | 选项

| 启用 pyproject.toml 可选 extra | extraDependencyGroups

| 添加不在 pyproject.toml 中的外部 Python 插件 | extraPythonPackages

| 添加系统二进制文件（pandoc、jq 等） | extraPackages

| 添加基于目录的插件源码树 | extraPlugins

组合使用

带有第三方 Python 依赖的目录插件需要同时使用两个选项：

services.hermes-agent = {
  extraPlugins = [ my-plugin-src ];          # 插件源码
  extraPythonPackages = [ config.services.hermes-agent.package.python.pkgs.redis ];  # 其 Python 依赖
  extraPackages = [ pkgs.redis ];            # 其需要的系统二进制文件
};

使用 Overlay

外部 flake 可以直接覆盖包：

{
  inputs.hermes-agent.url = "github:NousResearch/hermes-agent";
  outputs = { hermes-agent, nixpkgs, ... }: {
    nixpkgs.overlays = [ hermes-agent.overlays.default ];
    # 然后：
    #   pkgs.hermes-agent.override { extraPythonPackages = [...]; }
    #   pkgs.hermes-agent.override { extraDependencyGroups = [ "honcho" ]; }
  };
}

插件配置

插件仍需在 config.yaml 中启用。通过声明式 settings 添加：

services.hermes-agent.settings.plugins.enabled = [
  "hermes-lcm"
  "rtk-rewrite"
];

备注

构建时冲突检查可防止插件包覆盖核心 hermes 依赖。如果插件提供了封闭 venv 中已有的包，nixos-rebuild 会以明确的错误失败。

开发

开发 Shell

该 flake 提供包含 dev 依赖组的可编辑 Python 环境，解释器主/次版本来自 PM 锁文件。

HERMES_PYTHON 指向该解释器，不会把 Python 依赖安装到仓库内的 .venv。

shell 还提供 Node.js 和运行时工具。npm hook 根据输入变更刷新 JS workspaces。

cd hermes-agent
nix develop
"$HERMES_PYTHON" -c "import sys; print(sys.executable); print(sys.version)"
hermes setup
hermes chat

direnv（推荐）

包含的 .envrc 会自动激活开发 shell：

cd hermes-agent
direnv allow    # 仅需一次
# Nix 复用已构建的 Python 环境，npm hook 检查 JS 输入。

Flake 检查

该 flake 包含在 CI 和本地运行的构建时验证：

# 运行所有检查
nix flake check

# 单独检查
nix build .#checks.x86_64-linux.package-contents   # 二进制文件存在 + 版本
nix build .#checks.x86_64-linux.entry-points-sync  # pyproject.toml ↔ Nix 包同步
nix build .#checks.x86_64-linux.cli-commands        # gateway/config 子命令
nix build .#checks.x86_64-linux.managed-guard       # HERMES_MANAGED 屏蔽变更操作
nix build .#checks.x86_64-linux.bundled-skills      # 包中存在 skills
nix build .#checks.x86_64-linux.config-roundtrip    # 合并脚本保留用户键

每项检查的验证内容 | | 检查 | 测试内容

| package-contents | hermes 和 hermes-agent 二进制文件存在且 hermes --version 可运行

| entry-points-sync | pyproject.toml 中 [project.scripts] 的每个条目在 Nix 包中都有对应的封装二进制文件

| cli-commands | hermes --help 暴露 gateway 和 config 子命令

| managed-guard | HERMES_MANAGED=true hermes config set ... 打印 NixOS 错误

| bundled-skills | skills 目录存在，包含 SKILL.md 文件，wrapper 中设置了 HERMES_BUNDLED_SKILLS

| config-roundtrip | 7 种合并场景：全新安装、Nix 覆盖、用户键保留、混合合并、MCP 累加合并、嵌套深度合并、幂等性

选项参考

核心

| | 选项 | 类型 | 默认值 | 描述

| enable | bool | false | 启用 hermes-agent 服务

| package | package | hermes-agent | 使用的 hermes-agent 包

| user | str | "hermes" | 系统用户

| group | str | "hermes" | 系统组

| createUser | bool | true | 自动创建用户/组

| stateDir | str | "/var/lib/hermes" | 状态目录（HERMES_HOME 的父目录）

| workingDirectory | str | "${stateDir}/workspace" | Agent 工作目录（MESSAGING_CWD）

| addToSystemPackages | bool | false | 将 hermes CLI 添加到系统 PATH 并在系统范围内设置 HERMES_HOME

配置

| | 选项 | 类型 | 默认值 | 描述

| settings | attrs（深度合并） | {} | 声明式配置，渲染为 config.yaml。支持任意嵌套；多个定义通过 lib.recursiveUpdate 合并

| configFile | null 或 path | null | 现有 config.yaml 的路径。设置后完全覆盖 settings

密钥与环境

| | 选项 | 类型 | 默认值 | 描述

| environmentFiles | listOf str | [] | 包含密钥的 env 文件路径。激活时合并到 $HERMES_HOME/.env

| environment | attrsOf str | {} | 非密钥环境变量。在 Nix store 中可见——请勿在此放置密钥

| authFile | null 或 path | null | OAuth 凭据预置文件。仅在首次部署时复制

| authFileForceOverwrite | bool | false | 每次激活时始终从 authFile 覆盖 auth.json

文档

| | 选项 | 类型 | 默认值 | 描述

| documents | attrsOf (either str path) | {} | 工作区文件。键为文件名，值为内联字符串或路径。激活时安装到 workingDirectory

MCP 服务器

| | 选项 | 类型 | 默认值 | 描述

| mcpServers | attrsOf submodule | {} | MCP 服务器定义，合并到 settings.mcp_servers

| mcpServers.<name>.command | null 或 str | null | 服务器命令（stdio 传输）

| mcpServers.<name>.args | listOf str | [] | 命令参数

| mcpServers.<name>.env | attrsOf str | {} | 服务器进程的环境变量

| mcpServers.<name>.url | null 或 str | null | 服务器端点 URL（HTTP/StreamableHTTP 传输）

| mcpServers.<name>.headers | attrsOf str | {} | HTTP 头，例如 Authorization

| mcpServers.<name>.auth | null 或 "oauth" | null | 认证方式。"oauth" 启用 OAuth 2.1 PKCE

| mcpServers.<name>.enabled | bool | true | 启用或禁用此服务器

| mcpServers.<name>.timeout | null 或 int | null | 工具调用超时（秒，默认：120）

| mcpServers.<name>.connect_timeout | null 或 int | null | 连接超时（秒，默认：60）

| mcpServers.<name>.tools | null 或 submodule | null | 工具过滤（include/exclude 列表）

| mcpServers.<name>.sampling | null 或 submodule | null | 服务器发起 LLM 请求的 sampling 配置

服务行为

| | 选项 | 类型 | 默认值 | 描述

| extraArgs | listOf str | [] | hermes gateway 的额外参数

| extraPackages | listOf package | [] | Agent 可用的额外包。添加到 hermes 用户的每用户 profile，终端命令、skills 和 cron 任务均可见

| extraPlugins | listOf package | [] | 以符号链接方式安装到 $HERMES_HOME/plugins/ 的目录插件包。每个包必须包含 plugin.yaml

| extraPythonPackages | listOf package | [] | 添加到 PYTHONPATH 用于入口点插件发现的 Python 包。使用所选包的 python.pkgs 构建

| extraDependencyGroups | listOf str | [] | 包含到封闭 venv 中的 pyproject.toml 可选 extras（例如 ["honcho"]）。由 uv 解析——无冲突

| restart | str | "always" | systemd Restart= 策略

| restartSec | int | 5 | systemd RestartSec= 值

容器

| | 选项 | 类型 | 默认值 | 描述

| container.enable | bool | false | 启用 OCI 容器模式

| container.backend | enum ["docker" "podman"] | "docker" | 容器运行时

| container.image | str | "ubuntu:24.04" | 基础镜像（运行时拉取）

| container.extraVolumes | listOf str | [] | 额外卷挂载（host:container:mode）

| container.extraOptions | listOf str | [] | 传递给 docker create 的额外参数

| container.hostUsers | listOf str | [] | 获得 ~/.hermes 符号链接（指向服务 stateDir）的交互式用户，自动加入 hermes 组

目录结构

原生模式

/var/lib/hermes/                     # stateDir（归 hermes:hermes 所有，权限 0750）
├── .hermes/                         # HERMES_HOME
│   ├── config.yaml                  # Nix 生成（每次重建深度合并）
│   ├── .managed                     # 标记：CLI 配置变更被屏蔽
│   ├── .env                         # 从 environment + environmentFiles 合并
│   ├── auth.json                    # OAuth 凭据（预置后自我管理）
│   ├── gateway.pid
│   ├── state.db
│   ├── mcp-tokens/                  # MCP 服务器的 OAuth token
│   ├── sessions/
│   ├── memories/
│   ├── skills/
│   ├── cron/
│   └── logs/
├── home/                            # Agent HOME
└── workspace/                       # MESSAGING_CWD
    ├── SOUL.md                      # 来自 documents 选项
    └── （Agent 创建的文件）

容器模式

相同的布局，挂载到容器中：

| | 容器路径 | 主机路径 | 模式 | 说明

| /nix/store | /nix/store | ro | Hermes 二进制文件 + 所有 Nix 依赖

| /data | /var/lib/hermes | rw | 所有状态、配置、工作区

| /home/hermes | ${stateDir}/home | rw | 持久化 Agent home——pip install --user、工具缓存

| /usr、/usr/local、/tmp | （可写层） | rw | apt/pip/npm 安装——重启后持久，重建后丢失

更新

# 更新 flake 输入（在包含 flake.nix 的目录中运行）
cd /etc/nixos && nix flake update hermes-agent

# 重建
sudo nixos-rebuild switch

在容器模式下，current-package 符号链接会更新，Agent 在重启时获取新的二进制文件。不会重建容器，不会丢失已安装的包。

故障排查

Podman 用户

以下所有 docker 命令在 podman 中同样适用。如果你设置了 container.backend = "podman"，请相应替换。

服务日志

# 两种模式使用相同的 systemd 单元
journalctl -u hermes-agent -f

# 容器模式：也可直接查看
docker logs -f hermes-agent

容器检查

systemctl status hermes-agent
docker ps -a --filter name=hermes-agent
docker inspect hermes-agent --format='{{.State.Status}}'
docker exec -it hermes-agent bash
docker exec hermes-agent readlink /data/current-package
docker exec hermes-agent cat /data/.container-identity

强制重建容器

如果需要重置可写层（全新 Ubuntu）：

sudo systemctl stop hermes-agent
docker rm -f hermes-agent
sudo rm /var/lib/hermes/.container-identity
sudo systemctl start hermes-agent

验证密钥已加载

如果 Agent 启动但无法向 LLM 提供商认证，检查 .env 文件是否正确合并：

# 原生模式
sudo -u hermes cat /var/lib/hermes/.hermes/.env

# 容器模式
docker exec hermes-agent cat /data/.hermes/.env

GC Root 验证

nix-store --query --roots $(docker exec hermes-agent readlink /data/current-package)

常见问题

| | 现象 | 原因 | 解决方法

| Cannot save configuration: managed by NixOS | CLI 守卫已激活 | 编辑 configuration.nix 并执行 nixos-rebuild switch

| 容器意外重建 | extraVolumes、extraOptions 或 image 发生变更 | 预期行为——可写层重置。重新安装包或使用自定义镜像

| hermes --version 显示旧版本 | 容器未重启 | systemctl restart hermes-agent

| /var/lib/hermes 权限拒绝 | 状态目录为 0750 hermes:hermes | 使用 docker exec 或 sudo -u hermes

| nix-collect-garbage 删除了 hermes | GC root 缺失 | 重启服务（preStart 会重新创建 GC root）

| no container with name or ID "hermes-agent"（Podman） | Podman rootful 容器对普通用户不可见 | 为 podman 添加免密 sudo（参见容器模式章节）

| unable to find user hermes | 容器仍在启动中（入口点尚未创建用户） | 等待几秒后重试——CLI 会自动重试

| 通过 extraPackages 添加的工具在终端中找不到 | 需要 nixos-rebuild switch 更新每用户 profile | 重建并重启：nixos-rebuild switch && systemctl restart hermes-agent

Nous Portal

Nous Portal 是 Nous Research 的统一订阅网关，也是运行 Hermes Agent 的推荐方式。一次 OAuth 登录，即可替代原本需要手动配置的各模型厂商独立账号、API 密钥和计费关系。

如果你只有时间配置一件事，就配置这个。最快路径：

hermes setup --portal

这条命令会完成 Portal OAuth 认证，让你选择一个 Nous 模型，在 config.yaml 中将 Nous 设为推理提供商，并开启 Tool Gateway。完成后即可立即运行 hermes chat。

还没有订阅？前往 portal.nousresearch.com/manage-subscription 注册，然后回来运行上面的命令。

订阅包含的内容

300+ 前沿模型，统一账单

Portal 代理了来自整个生态系统的精选 agentic 模型目录——统一计入你的 Nous 订阅，而非每个厂商单独充值。

| | 系列 | 模型

| Anthropic Claude | Opus、Sonnet、Haiku（4.x 系列）

| OpenAI | GPT-5.4、o 系列推理模型

| Google Gemini | 2.5 Pro、2.5 Flash

| DeepSeek | DeepSeek V3.2、DeepSeek-R1

| Qwen | Qwen3 系列、Qwen Coder

| Kimi / Moonshot | Kimi-K2、Kimi-Latest

| GLM / Zhipu | GLM-4.6、GLM-4-Plus

| MiniMax | M2.7、M1

| xAI | Grok-4、Grok-3

| Hermes | Hermes-4-70B、Hermes-4-405B（对话，见下方说明）

| + 其他所有模型 | 240+ 额外模型——完整的 agentic 前沿生态

底层上，Portal 会为每个模型选择最合适的后端——部分模型通过 OpenRouter 路由，其他模型则通过专有或备用提供商，且某个模型的路由方式可能随时间调整。所有用量都统一计入你的 Nous 订阅。在会话中途用 /model 即可在 Claude Sonnet 4.6（适合代码）和 Gemini 2.5 Pro（适合长上下文）之间切换——无需新凭证，无需充值，不会遇到余额为零的意外报错。

备注

由于路由是按模型进行的，并非总是经过 OpenRouter，OpenRouter 专有的请求扩展（如 provider 路由偏好、session_id 粘性路由或顶层 cache_control）不属于 Portal 的 API 契约，可能会被忽略，具体取决于该模型由哪个后端提供服务。

Nous Tool Gateway

同一订阅还解锁了 Tool Gateway，将 Hermes Agent 的工具调用路由至 Nous 托管的基础设施。五个后端，一次登录：

| | 工具 | 合作方 | 功能说明

| 网页搜索与抓取 | Nous 托管 | Agent 级搜索与整页内容提取。无需搜索 API 密钥，无需管理速率限制。

| 图像生成 | FAL | 单一端点下的九个模型：FLUX 2 Klein 9B、FLUX 2 Pro、Z-Image Turbo、Nano Banana Pro（Gemini 3 Pro Image）、GPT Image 1.5、GPT Image 2、Ideogram V3、Recraft V4 Pro、Qwen Image。

| 文字转语音 | OpenAI TTS | 无需独立 OpenAI 密钥的高质量 TTS。在各消息平台上启用语音模式。

| 云端浏览器自动化 | Browser Use | 用于 browser_navigate、browser_click、browser_type、browser_vision 的无头 Chromium 会话。无需 Browserbase 账号。

| 云端终端沙箱 | Modal | 用于代码执行的无服务器终端沙箱（可选附加项）。

不使用 gateway 的话，接入上述每项服务意味着：一个网页搜索账号、一个 FAL 账号、一个 Browser Use 账号、一个 OpenAI 密钥、一个 Modal 账号——五次独立注册、五个独立控制台、五套独立充值流程。使用 gateway 后，所有内容通过一个订阅统一路由。

你也可以只启用特定的 gateway 工具（例如只开启网页搜索，不开启图像生成）——详见下方将 gateway 与自有后端混用。

凭证不落入 dotfiles

由于所有请求都通过一个经 OAuth 认证的 Portal 会话路由，你不会积累一个包含十几个长期 API 密钥的 .env 文件。磁盘上唯一的凭证是 ~/.hermes/auth.json 中的 refresh token（刷新令牌），Hermes 会在每次请求时从中生成短期 JWT——详见下方令牌处理。

跨平台一致性

原生 Windows 上，逐个配置 API 密钥是其最大痛点——在 Windows 上分别安装网页搜索账号、FAL 账号、Browser Use 账号、OpenAI 密钥，是整个 agent 配置过程中摩擦最高的部分。Portal 订阅消除了这一问题：一次 OAuth 覆盖模型和所有 gateway 工具，Windows 用户无需手动配置四个后端，即可获得与 macOS/Linux 相同的体验。

关于 Hermes 4 的说明

Nous Research 自家的 Hermes 4 系列（Hermes-4-70B、Hermes-4-405B）通过 Portal 提供，享有大幅折扣。这些是前沿混合推理对话模型——在数学、科学、指令遵循、schema 遵从、角色扮演和长文写作方面表现出色。

但不建议在 Hermes Agent 内部使用它们。Hermes 4 针对对话和推理进行了调优，而非 agent 所依赖的高频工具调用循环。请将它们用于研究工作流，或通过订阅代理从其他工具调用——但在 agent 场景下，请从目录中选择前沿 agentic 模型：

/model anthropic/claude-sonnet-4.6     # 最佳通用 agentic 模型
/model openai/gpt-5.4                  # 强推理 + 工具调用
/model google/gemini-2.5-pro           # 超大上下文窗口
/model deepseek/deepseek-v3.2          # 高性价比代码模型

Portal 自身的模型信息页也有相同警告，因此这不是 Hermes 侧的主观意见——这是 Nous Research 的官方指导。

配置

全新安装——一条命令

hermes setup --portal

一次性完成全部配置：

打开浏览器跳转至 portal.nousresearch.com 进行 OAuth 登录
将 refresh token 存储至 ~/.hermes/auth.json
让你从精选列表中选择一个 Nous 模型（也可跳过以保留当前模型）
在 ~/.hermes/config.yaml 中将 Nous 设为推理提供商（当你选择模型时）
开启 Tool Gateway（网页、图像、TTS、浏览器路由）
返回终端，即可运行 hermes chat

如果还没有订阅，请先在 portal.nousresearch.com/manage-subscription 注册。

已有安装——在现有提供商旁添加 Portal

如果你已经配置了 OpenRouter、Anthropic 或其他提供商，想在此基础上添加 Portal：

hermes model
# 从提供商列表中选择 "Nous Portal"
# 浏览器打开，登录，完成

你现有的提供商配置保持不变。可以在会话中途用 /model 切换，或在会话间用 hermes model 切换——Portal 成为你的可用提供商之一，而非唯一选项。

无头环境 / SSH / 远程配置

OAuth 需要浏览器，但回调的 loopback 运行在 Hermes 所在的机器上。对于远程主机，请参阅 OAuth over SSH / 远程主机——与其他基于 OAuth 的提供商相同的方式同样适用于 Portal（ssh -L 端口转发）。

Profile 配置

如果你使用 Hermes profiles（配置文件），Portal 的 refresh token 会通过共享令牌存储自动在所有 profile 间共享。在任意 profile 上登录一次，其余 profile 自动获取——无需为每个 profile 重复 OAuth 流程。

日常使用 Portal

查看当前配置状态

hermes portal            # 登录 Nous Portal 并完成配置（一键引导）
hermes portal info       # 登录状态、订阅信息、模型与 gateway 路由
hermes portal tools      # 详细的 Tool Gateway 目录及每个工具的路由信息
hermes portal open       # 在浏览器中打开订阅管理页面

hermes portal（不带子命令）是 hermes auth add nous --type oauth 的易记别名——它会登录、让你选择 Nous 模型、把 Nous 设为推理服务商，并提供 Tool Gateway 启用选项（与 hermes setup --portal 等价，与首次快速设置走的是同一套 Nous 流程）。

hermes portal info 给出高层概览：

  Nous Portal
  ───────────
  Auth:    ✓ logged in
  Portal:  https://portal.nousresearch.com
  Model:   ✓ using Nous as inference provider

  Tool Gateway
  ────────────
  Web search & extract  via Nous Portal
  Image generation      via Nous Portal
  Text-to-speech        via Nous Portal
  Browser automation    via Nous Portal
  Cloud terminal        not configured

切换模型

在会话中：

/model anthropic/claude-sonnet-4.6
/model openai/gpt-5.4
/model google/gemini-2.5-pro

或打开选择器：

/model
# 方向键选择，回车确认

在会话外（完整配置向导，适合添加新提供商时使用）：

hermes model

将 gateway 与自有后端混用

如果你已有 Browserbase 账号并希望继续使用，同时通过 Nous 路由网页搜索和图像生成，这是支持的。使用 hermes tools 为每个工具单独选择后端：

hermes tools
# → 网页搜索       → "Nous Subscription"
# → 图像生成       → "Nous Subscription"
# → 浏览器         → "Browserbase"（你的现有密钥）
# → TTS            → "Nous Subscription"

Tool Gateway 是按工具单独选择启用的，而非全部或全不。完整的每工具配置矩阵请参阅 Tool Gateway 文档。

订阅管理

随时管理套餐、查看用量或升级/取消：

网页端： portal.nousresearch.com/manage-subscription
CLI 快捷方式： hermes portal open（在默认浏览器中打开同一页面）

配置参考

运行 hermes setup --portal 后，~/.hermes/config.yaml 将如下所示：

model:
  provider: nous
  default: anthropic/claude-sonnet-4.6     # 或你选择的其他模型
  base_url: https://inference.nousresearch.com/v1

Tool Gateway 设置位于各自工具的配置节下：

web:
  backend: nous       # 网页搜索/抓取通过 Tool Gateway 路由

image_gen:
  provider: nous

tts:
  provider: nous

browser:
  backend: nous

OAuth refresh token 单独存储在 ~/.hermes/auth.json（不在 config.yaml 中——凭证与配置有意分开存放）。

令牌处理

Hermes 在每次推理调用时从存储的 Portal refresh token 生成短期 JWT，而非复用长期 API 密钥。令牌生命周期完全自动管理——刷新、生成、在瞬时 401 时重试——你无需关心这些细节。

如果 Portal 使 refresh token 失效（修改密码、手动撤销、会话过期），失效的 refresh token 会被本地隔离，Hermes 停止重放该令牌，你不会看到一连串相同的 401 错误。下一次调用会显示清晰的"需要重新认证"提示。运行 hermes auth add nous 重新登录；隔离状态在下次成功登录时自动清除。

故障排查

hermes portal info 显示"not logged in"

你尚未完成 OAuth 流程，或 refresh token 已被清除。运行：

hermes portal

或使用 hermes model 重新选择 Nous Portal。

会话中途收到"需要重新认证"提示

你的 Portal refresh token 已失效（修改密码、手动撤销或会话过期）。运行 hermes auth add nous，下一次请求将使用新凭证。旧令牌的隔离状态在成功重新登录后自动清除。

想使用 Portal 未暴露的特定提供商模型

Portal 会为每个模型选择合适的后端——部分模型通过 OpenRouter 路由，其他模型则通过专有或备用提供商——因此 OpenRouter 支持的大多数模型通常都可用。如果某个模型未出现在 /model 中，可直接尝试 OpenRouter 风格的 slug：

/model anthropic/claude-opus-4.6

如果某个模型确实缺失，请提交 issue——我们将 Portal 目录同步至 Hermes，缺口通常意味着可以更新的路由配置。

账单未出现在我的 Portal 账号中

先检查 hermes portal info——如果显示你正在使用其他提供商（Model: currently openrouter 而非 using Nous as inference provider），说明本地配置已偏离。运行 hermes model，选择 Nous Portal，下一次请求将通过你的订阅路由。

另请参阅

Tool Gateway —— 每个 gateway 工具的完整详情、每工具配置及定价
订阅代理 —— 在非 Hermes 工具（其他 agent、脚本、第三方客户端）中使用你的 Portal 订阅
语音模式 —— 使用 Portal 的 OpenAI TTS 进行语音对话
AI 提供商 —— 完整提供商目录，供对比参考
OAuth over SSH —— 从远程主机或纯浏览器环境登录
Profiles —— 多个 Hermes 配置共享一个 Portal 登录

CLI 命令参考

本页的 Python 依赖命令使用 PM 准备的源码环境。

依赖变更后，请重新激活该 checkout 并重启 Hermes。

本页介绍从 shell 运行的终端命令。

关于聊天内斜杠命令，请参阅斜杠命令参考。

全局入口

hermes [global-options] <command> [subcommand/options]

全局选项

| | 选项 | 说明

| --version, -V | 显示版本并退出。

| --profile <name>, -p <name> | 选择本次调用使用的 Hermes profile（配置文件）。覆盖 hermes profile use 设置的粘性默认值。

| --resume <session>, -r <session> | 通过 ID 或标题恢复之前的会话。

| --continue [name], -c [name] | 恢复最近的会话，或恢复最近一个匹配标题的会话。

| --worktree, -w | 在隔离的 git worktree 中启动，用于并行 agent 工作流。

| --yolo | 跳过危险命令的审批提示。

| --pass-session-id | 在 agent 的 system prompt（系统提示词）中包含会话 ID。

| --ignore-user-config | 忽略 ~/.hermes/config.yaml，回退到内置默认值。.env 中的凭据仍会加载。

| --ignore-rules | 跳过 AGENTS.md、SOUL.md、.cursorrules、memory（记忆）和预加载 skill 的自动注入。

| --tui | 启动 TUI 而非经典 CLI。等同于 HERMES_TUI=1。

| --dev | 与 --tui 配合使用：通过 tsx 直接运行 TypeScript 源码而非预构建包（供 TUI 贡献者使用）。

顶级命令

| | 命令 | 用途

| hermes chat | 与 agent 进行交互式或单次聊天。

| hermes model | 交互式选择默认 provider 和模型。

| hermes fallback | 管理主模型出错时依次尝试的 fallback provider。

| hermes gateway | 运行或管理消息 gateway 服务。

| hermes proxy | 本地 OpenAI 兼容代理，附加 OAuth provider 凭据。参见订阅代理。

| hermes lsp | 管理 Language Server Protocol 集成（为 write_file/patch 提供语义诊断）。

| hermes setup | 全部或部分配置的交互式设置向导。

| hermes whatsapp | 配置并配对 WhatsApp 桥接。

| hermes slack | Slack 辅助工具（当前功能：生成将每条命令注册为原生斜杠命令的 app manifest）。

| hermes auth | 管理凭据——添加、列出、删除、重置、设置策略。处理 Codex/Nous/Anthropic 的 OAuth 流程。

| hermes login / logout | 已弃用 — 请改用 hermes auth。

| hermes status | 显示 agent、auth 和平台状态。

| hermes cron | 检查并触发 cron 调度器。

| hermes kanban | 多 profile 协作看板（任务、链接、调度器）。

| hermes webhook | 管理用于事件驱动激活的动态 webhook 订阅。

| hermes hooks | 检查、审批或删除 config.yaml 中声明的 shell 脚本 hook。

| hermes doctor | 诊断配置和依赖问题。

| hermes security audit | 对 venv、plugin 依赖和固定 MCP 服务器进行按需供应链审计（OSV.dev）。

| hermes dump | 可直接复制粘贴的设置摘要，用于支持/调试。

| hermes debug | 调试工具——上传日志和系统信息以获取支持。

| hermes backup | 将 Hermes 主目录备份为 zip 文件。

| hermes checkpoints | 检查/修剪/清除 ~/.hermes/checkpoints/（/rollback 使用的影子存储）。不带参数运行可查看状态概览。

| hermes import | 从 zip 文件恢复 Hermes 备份。

| hermes logs | 查看、跟踪和过滤 agent/gateway/错误日志文件。

| hermes config | 显示、编辑、迁移和查询配置文件。

| hermes pairing | 审批或撤销消息配对码。

| hermes skills | 浏览、安装、发布、审计和配置 skill。

| hermes bundles | 将多个 skill 归组到单个 /<name> 斜杠命令下。参见 Skill Bundles。

| hermes curator | 后台 skill 维护——状态、运行、暂停、固定。参见 Curator。

| hermes memory | 配置外部 memory provider。当对应 provider 激活时，特定于 plugin 的子命令（如 hermes honcho）会自动注册。

| hermes acp | 将 Hermes 作为 ACP 服务器运行，用于编辑器集成。

| hermes mcp | 管理 MCP 服务器配置，并将 Hermes 作为 MCP 服务器运行。

| hermes plugins | 管理 Hermes Agent plugin（安装、启用、禁用、删除）。

| hermes portal | Nous Portal 状态、订阅链接和 Tool Gateway 路由。参见 Tool Gateway。

| hermes tools | 按平台配置已启用的工具。

| hermes computer-use | 安装或检查 cua-driver 后端（macOS Computer Use）。

| hermes sessions | 浏览、导出、修剪、重命名和删除会话。

| hermes insights | 显示 token/费用/活动分析。

| hermes claw | OpenClaw 迁移辅助工具。

| hermes dashboard | 启动用于管理配置、API 密钥和会话的 Web 控制台。

| hermes profile | 管理 profile——多个隔离的 Hermes 实例。

| hermes completion | 打印 shell 补全脚本（bash/zsh/fish）。

| hermes --version | 显示版本信息。

| hermes update | 拉取最新代码并重新安装依赖。--check 预览而不安装；--backup 在拉取前对 HERMES_HOME 进行快照。

| hermes uninstall | 从系统中删除 Hermes。

hermes chat

hermes chat [options]

常用选项：

| | 选项 | 说明

| -q, --query "..." | 单次非交互式 prompt。

| -m, --model <model> | 覆盖本次运行的模型。

| -t, --toolsets <csv> | 启用逗号分隔的 toolset 集合。

| --provider <provider> | 强制指定 provider：auto、openrouter、nous、openai-codex、copilot-acp、copilot、anthropic、gemini、huggingface、novita（别名 novita-ai、novitaai）、openai-api、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、minimax-oauth、kilocode、xiaomi、arcee、gmi、alibaba、alibaba-coding-plan（别名 alibaba_coding）、deepseek、nvidia、ollama-cloud、xai（别名 grok）、xai-oauth（别名 grok-oauth）、qwen-oauth、bedrock、opencode-zen、opencode-go、ai-gateway、azure-foundry、lmstudio、stepfun、tencent-tokenhub（别名 tencent、tokenhub）。

| -s, --skills <name> | 为会话预加载一个或多个 skill（可重复或逗号分隔）。

| -v, --verbose | 详细输出。

| -Q, --quiet | 程序化模式：抑制横幅/spinner/工具预览。

| --image <path> | 为单次查询附加本地图片。

| --resume <session> / --continue [name] | 直接从 chat 恢复会话。

| --worktree | 为本次运行创建隔离的 git worktree。

| --checkpoints | 在破坏性文件变更前启用文件系统 checkpoint。

| --yolo | 跳过审批提示。

| --pass-session-id | 将会话 ID 传入 system prompt。

| --ignore-user-config | 忽略 ~/.hermes/config.yaml，使用内置默认值。.env 中的凭据仍会加载。适用于隔离的 CI 运行、可复现的 bug 报告和第三方集成。

| --ignore-rules | 跳过 AGENTS.md、SOUL.md、.cursorrules、持久 memory 和预加载 skill 的自动注入。与 --ignore-user-config 组合可实现完全隔离的运行。

| --source <tag> | 用于过滤的会话来源标签（默认：cli）。对于不应出现在用户会话列表中的第三方集成，使用 tool。

| --max-turns <N> | 每个对话轮次的最大工具调用迭代次数（默认：500，或 config 中的 agent.max_turns）。

示例：

hermes
hermes chat -q "Summarize the latest PRs"
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills
hermes chat --quiet -q "Return only JSON"
hermes chat --worktree -q "Review this repo and open a PR"
hermes chat --ignore-user-config --ignore-rules -q "Repro without my personal setup"

hermes -z <prompt> — 脚本化单次调用

对于程序化调用方（shell 脚本、CI、cron、通过管道传入 prompt 的父进程），hermes -z 是最纯粹的单次入口：单个 prompt 输入，最终响应文本输出，stdout 和 stderr 上不输出任何其他内容。无横幅、无 spinner、无工具预览、无 Session: 行——只有 agent 的最终回复纯文本。

hermes -z "What's the capital of France?"
# → Paris.

# 父脚本可以干净地捕获响应：
answer=$(hermes -z "summarize this" < /path/to/file.txt)

单次运行覆盖（不修改 ~/.hermes/config.yaml）：

| | 标志 | 等效环境变量 | 用途

| -m / --model <model> | HERMES_INFERENCE_MODEL | 覆盖本次运行的模型

| --provider <provider> | (无) | 覆盖本次运行的 provider

hermes -z "…" --provider openrouter --model openai/gpt-5.5
# 或：
HERMES_INFERENCE_MODEL=anthropic/claude-sonnet-4.6 hermes -z "…"

相同的 agent、相同的工具、相同的 skill——只是剥离了所有交互式/装饰性层。如果你还需要在记录中包含工具输出，请改用 hermes chat -q；-z 专门用于"我只需要最终答案"的场景。

hermes model

交互式 provider + 模型选择器。这是添加新 provider、设置 API 密钥和运行 OAuth 流程的命令。从终端运行——不要在活跃的 Hermes 聊天会话内部运行。

hermes model

在以下情况使用此命令：

添加新 provider（OpenRouter、Anthropic、Copilot、DeepSeek、自定义等）
登录基于 OAuth 的 provider（Anthropic、Copilot、Codex、Nous Portal）
输入或更新 API 密钥
从 provider 特定的模型列表中选择
配置自定义/自托管端点
将新默认值保存到 config

hermes model 与 /model——了解区别

hermes model（从终端运行，在任何 Hermes 会话外部）是完整的 provider 设置向导。它可以添加新 provider、运行 OAuth 流程、提示输入 API 密钥并配置端点。

/model（在活跃的 Hermes 聊天会话中输入）只能在已设置好的 provider 和模型之间切换。它无法添加新 provider、运行 OAuth 或提示输入 API 密钥。

如果需要添加新 provider：先退出 Hermes 会话（Ctrl+C 或 /quit），然后从终端提示符运行 hermes model。

/model 斜杠命令（会话中途）

无需离开会话即可在已配置的模型之间切换：

/model                              # 显示当前模型和可用选项
/model claude-sonnet-4              # 切换模型（自动检测 provider）
/model zai:glm-5                    # 切换 provider 和模型
/model custom:qwen-2.5              # 在自定义端点上使用模型
/model custom                       # 从自定义端点自动检测模型
/model custom:local:qwen-2.5        # 使用命名的自定义 provider
/model openrouter:anthropic/claude-sonnet-4  # 切换回云端

默认情况下，/model 的更改仅对当前会话生效。添加 --global 可将更改持久化到 config.yaml：

/model claude-sonnet-4 --global     # 切换并保存为新默认值

如果我只看到 OpenRouter 模型怎么办？

如果你只配置了 OpenRouter，/model 将只显示 OpenRouter 模型。要添加其他 provider（Anthropic、DeepSeek、Copilot 等），请退出会话并从终端运行 hermes model。

Provider 和 base URL 的更改会自动持久化到 config.yaml。从自定义端点切换走时，过时的 base URL 会被清除，以防止其泄漏到其他 provider。

hermes gateway

hermes gateway <subcommand>

子命令：

| | 子命令 | 说明

| run | 在前台运行 gateway。推荐用于 WSL、Docker 和 Termux。

| start | 启动已安装的 systemd/launchd 后台服务。

| stop | 停止服务（或前台进程）。

| restart | 重启服务。

| status | 显示服务状态。

| list | 列出所有 profile 及每个 profile 的 gateway 当前是否运行（有 PID 时显示）。当你并行运行多个 profile 并需要单一概览时很方便。

| install | 安装为 systemd（Linux）或 launchd（macOS）后台服务。

| uninstall | 删除已安装的服务。

| setup | 交互式消息平台设置。

选项：

| | 选项 | 说明

| --all | 在 start / restart / stop 时：对每个 profile 的 gateway 执行操作，而不仅限于活跃的 HERMES_HOME。当你并行运行多个 profile 并希望在 hermes update 后全部重启时很有用。

| --no-supervise | 在 run 时：在 s6-overlay Docker 镜像内部，跳过 s6 自动监管，退回到 pre-s6 前台语义——gateway 作为容器主进程运行，无自动重启。在 s6 镜像之外为空操作。等同于设置 HERMES_GATEWAY_NO_SUPERVISE=1。

WSL 用户

使用 hermes gateway run 而非 hermes gateway start——WSL 的 systemd 支持不稳定。用 tmux 包裹以保持持久运行：tmux new -s hermes 'hermes gateway run'。详见 WSL FAQ。

hermes lsp

hermes lsp <subcommand>

管理 Language Server Protocol 集成。LSP 在后台运行真实的语言服务器（pyright、gopls、rust-analyzer 等），并将其诊断信息输入 write_file 和 patch 使用的写后检查。受 git 工作区检测限制——仅当 cwd 或编辑的文件位于 git worktree 内时，LSP 才会运行。

子命令：

| | 子命令 | 说明

| status | 显示服务状态、已配置的服务器、安装状态。

| list | 打印支持的服务器注册表。传入 --installed-only 可跳过缺失的服务器。

| install <id> | 主动安装某个服务器的二进制文件。

| install-all | 安装所有具有已知自动安装方案的服务器。

| restart | 关闭正在运行的客户端，以便下次编辑时重新启动。

| which <id> | 打印某个服务器的已解析二进制路径。

完整指南、支持的语言和配置项，请参阅 LSP — 语义诊断。

hermes setup

hermes setup [model|tts|terminal|gateway|tools|agent] [--non-interactive] [--reset] [--quick] [--reconfigure] [--portal]

首次运行：启动首次使用向导。

已配置用户：直接进入完整重新配置向导——每个提示都以当前值作为默认值，按 Enter 保留或输入新值。无菜单。

跳转到某个部分而非完整向导：

| | 部分 | 说明

| model | Provider 和模型设置。

| terminal | 终端后端和沙箱设置。

| gateway | 消息平台设置。

| tools | 按平台启用/禁用工具。

| agent | Agent 行为设置。

选项：

| | 选项 | 说明

| --quick | 在已配置用户运行时：仅提示缺失或未设置的项目，跳过已配置的项目。

| --non-interactive | 使用默认值/环境变量，不显示提示。

| --reset | 在设置前将配置重置为默认值。

| --reconfigure | 向后兼容别名——在已有安装上裸运行 hermes setup 现在默认执行此操作。

| --portal | 一键 Nous Portal 设置：通过 OAuth 登录，将 Nous 设为推理 provider，并选择加入 Tool Gateway。跳过向导其余部分。

hermes portal

hermes portal [status|open|tools]

检查 Nous Portal 认证、Tool Gateway 路由，并访问订阅页面。不带子命令时运行 status。

| | 子命令 | 说明

| status（默认） | Portal 认证状态 + 每个工具的 Tool Gateway 路由摘要。不带子命令时也会显示。

| open | 在默认浏览器中打开 portal.nousresearch.com/manage-subscription。

| tools | 列出每个 Tool Gateway 合作伙伴（Firecrawl、FAL、OpenAI TTS、Browser Use、Modal）及哪些通过 Nous 路由。

关于 gateway 本身的配置，请参阅 Tool Gateway。关于一键设置路径，请参阅上方的 hermes setup --portal。

hermes whatsapp

hermes whatsapp

运行 WhatsApp 配对/设置流程，包括模式选择和二维码配对。

hermes slack

hermes slack manifest              # 将 manifest 打印到 stdout
hermes slack manifest --write      # 写入 ~/.hermes/slack-manifest.json
hermes slack manifest --slashes-only  # 仅输出 features.slash_commands 数组

生成一个 Slack app manifest，将 COMMAND_REGISTRY 中的每条 gateway 命令（/btw、/stop、/model 等）注册为一等公民 Slack 斜杠命令——与 Discord 和 Telegram 保持一致。将输出粘贴到你的 Slack app 配置中：https://api.slack.com/apps → 你的 app → Features → App Manifest → Edit，然后点击 Save。如果 scope 或斜杠命令有变化，Slack 会提示重新安装。

| | 标志 | 默认值 | 用途

| --write [PATH] | stdout | 写入文件而非 stdout。裸 --write 写入 $HERMES_HOME/slack-manifest.json。

| --name NAME | Hermes | Slack 中的机器人显示名称。

| --description DESC | 默认简介 | Slack app 目录中显示的机器人描述。

| --slashes-only | 关闭 | 仅输出 features.slash_commands，用于合并到手动维护的 manifest 中。

hermes update 后重新运行 hermes slack manifest --write 以获取新增命令。

hermes login / hermes logout （已弃用）

警告

hermes login 已被移除。请使用 hermes auth 管理 OAuth 凭据，使用 hermes model 选择 provider，或使用 hermes setup 进行完整的交互式设置。

hermes auth

管理同一 provider 的密钥轮换凭据池。完整文档请参阅凭据池。

hermes auth                                              # 交互式向导
hermes auth list                                         # 显示所有池
hermes auth list openrouter                              # 显示特定 provider
hermes auth add openrouter --api-key sk-or-v1-xxx        # 添加 API 密钥
hermes auth add anthropic --type oauth                   # 添加 OAuth 凭据
hermes auth remove openrouter 2                          # 按索引删除
hermes auth reset openrouter                             # 清除冷却时间
hermes auth status anthropic                             # 显示某 provider 的认证状态
hermes auth logout anthropic                             # 登出并清除已存储的认证状态

子命令：add、list、remove、reset、status、logout。Spotify 登录已移至插件目录 spotify 插件的 hermes spotify login。不带子命令调用时，启动交互式管理向导。

hermes status

hermes status [--all] [--deep]

| | 选项 | 说明

| --all | 以可分享的脱敏格式显示所有详情。

| --deep | 运行可能耗时更长的深度检查。

hermes cron

hermes cron <list|create|edit|pause|resume|run|remove|status|tick>

| | 子命令 | 说明

| list | 显示已调度的任务。

| create / add | 从 prompt 创建调度任务，可通过重复 --skill 附加一个或多个 skill。

| edit | 更新任务的调度、prompt、名称、投递方式、重复次数或附加的 skill。支持 --clear-skills、--add-skill 和 --remove-skill。

| pause | 暂停任务而不删除。

| resume | 恢复已暂停的任务并计算下次未来运行时间。

| run | 在下次调度器 tick 时触发任务。

| remove | 删除调度任务。

| status | 检查 cron 调度器是否正在运行。

| tick | 运行到期任务一次后退出。

hermes kanban

hermes kanban [--board <slug>] <action> [options]

多 profile、多项目协作看板。每个安装可托管多个看板（每个项目、仓库或领域一个）；每个看板是独立的队列，拥有自己的 SQLite 数据库和调度器作用域。新安装从名为 default 的单个看板开始，其数据库为 ~/.hermes/kanban.db（向后兼容）；其他看板位于 ~/.hermes/kanban/boards/<slug>/kanban.db。嵌入在 gateway 中的调度器每次 tick 扫描所有看板。

全局标志（适用于以下所有操作）：

| | 标志 | 用途

| --board <slug> | 操作特定看板。默认为当前看板（通过 hermes kanban boards switch、HERMES_KANBAN_BOARD 环境变量或 default 设置）。

这是人工/脚本操作界面。调度器生成的 agent worker 通过专用的 kanban_* toolset（kanban_show、kanban_complete、kanban_block、kanban_create、kanban_link、kanban_comment、kanban_heartbeat；编排器 profile 还可使用 kanban_list 和 kanban_unblock）驱动看板，而非调用 hermes kanban。Worker 的环境中固定了 HERMES_KANBAN_BOARD，因此物理上无法看到其他看板。

| | 操作 | 用途

| init | 如果缺少则创建 kanban.db。幂等操作。

| boards list / boards ls | 列出所有看板及任务数量。支持 --json、--all（包含已归档）。

| boards create <slug> | 创建新看板。标志：--name、--description、--icon、--color、--switch（设为活跃）。Slug 为 kebab-case，自动转小写。

| boards switch <slug> / boards use | 将 <slug> 持久化为活跃看板（写入 ~/.hermes/kanban/current）。

| boards show / boards current | 打印当前活跃看板的名称、数据库路径和任务数量。

| boards rename <slug> "<name>" | 更改看板的显示名称。Slug 不可变。

| boards rm <slug> | 归档（默认）或硬删除看板。--delete 跳过归档步骤。已归档看板移至 boards/_archived/<slug>-<ts>/。default 看板拒绝此操作。

| create "<title>" | 在活跃看板上创建新任务。标志：--body、--assignee、--parent（可重复）、--workspace scratch|worktree|dir:<path>、--tenant、--priority、--triage、--idempotency-key、--max-runtime、--max-retries、--skill（可重复）。

| list / ls | 列出活跃看板上的任务。可用 --mine、--assignee、--status、--tenant、--archived、--json 过滤。

| show <id> | 显示任务及其评论和事件。--json 用于机器输出。

| assign <id> <profile> | 分配或重新分配。使用 none 取消分配。任务运行时拒绝此操作。

| link <parent> <child> | 添加依赖关系。检测循环依赖。两个任务必须在同一看板上。

| unlink <parent> <child> | 删除依赖关系。

| claim <id> | 原子性地认领就绪任务。打印已解析的工作区路径。

| comment <id> "<text>" | 追加评论。下一个认领该任务的 worker 会在其 kanban_show() 响应中读取到它。

| complete <id> | 将任务标记为完成。标志：--result、--summary、--metadata。

| block <id> "<reason>" | 将任务标记为等待人工输入。同时将原因追加为评论。

| schedule <id> "<reason>" | 将时间延迟/后续工作停放到 scheduled 状态，使其不显示为人工阻塞项。

| unblock <id> | 将已阻塞或已调度的任务返回就绪状态（如果依赖仍未完成则返回 todo）。

| archive <id> | 从默认列表中隐藏。gc 将删除 scratch 工作区。

| tail <id> | 跟踪任务的事件流。

| dispatch | 对活跃看板执行一次调度器扫描。标志：--dry-run、--max N、--failure-limit N、--json。

| context <id> | 打印 worker 将看到的完整上下文（标题 + 正文 + 父任务结果 + 评论）。

| specify <id> / specify --all | 通过辅助 LLM 将 triage 列中的任务细化为具体规格（标题 + 包含目标、方案、验收标准的正文），然后将其提升到 todo。标志：--tenant（将 --all 限定到一个 tenant）、--author、--json。在 config.yaml 的 auxiliary.triage_specifier 下配置模型。

| decompose <id> / decompose --all | 将 triage 列中的任务按描述拆分为子任务图，路由到专业 profile（编排器驱动路径）。当 LLM 判断任务不适合拆分时，回退到 specify 风格的单任务提升。与 specify 相同的标志。在 config.yaml 的 auxiliary.kanban_decomposer 下配置模型。当 kanban.auto_decompose: true（默认）时，每次调度器 tick 也会自动运行。参见自动与手动编排。

| gc | 删除已归档任务的 scratch 工作区。

示例：

# 创建第二个看板并在不切换的情况下向其添加任务。
hermes kanban boards create atm10-server --name "ATM10 Server" --icon 🎮
hermes kanban --board atm10-server create "Restart server" --assignee ops

# 切换活跃看板以供后续调用使用。
hermes kanban boards switch atm10-server
hermes kanban list                  # 显示 atm10-server 的任务

# 归档看板（可恢复）或硬删除。
hermes kanban boards rm atm10-server
hermes kanban boards rm atm10-server --delete

看板解析顺序（优先级从高到低）：--board <slug> 标志 → HERMES_KANBAN_BOARD 环境变量 → ~/.hermes/kanban/current 文件 → default。

所有操作也可作为 gateway 中的斜杠命令使用（/kanban …），参数界面相同——包括 boards 子命令和 --board 标志。

完整设计——与 Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise 的对比、八种协作模式、四个用户故事、并发正确性证明——请参阅 Kanban 用户指南。

hermes webhook

hermes webhook <subscribe|list|remove|test>

管理用于事件驱动 agent 激活的动态 webhook 订阅。需要在 config 中启用 webhook 平台——如未配置，将打印设置说明。

| | 子命令 | 说明

| subscribe / add | 创建 webhook 路由。返回要在你的服务上配置的 URL 和 HMAC 密钥。

| list / ls | 显示所有 agent 创建的订阅。

| remove / rm | 删除动态订阅。不影响 config.yaml 中的静态路由。

| test | 发送测试 POST 以验证订阅是否正常工作。

hermes webhook subscribe

hermes webhook subscribe <name> [options]

| | 选项 | 说明

| --prompt | 带有 {dot.notation} payload 引用的 prompt 模板。

| --events | 要接受的逗号分隔事件类型（如 issues,pull_request）。为空则接受所有。

| --description | 人类可读的描述。

| --skills | 为 agent 运行加载的逗号分隔 skill 名称。

| --deliver | 投递目标：log（默认）、telegram、discord、slack、github_comment。

| --deliver-chat-id | 跨平台投递的目标聊天/频道 ID。

| --secret | 自定义 HMAC 密钥。省略时自动生成。

| --deliver-only | 跳过 agent——将渲染后的 --prompt 作为字面消息投递。零 LLM 成本，亚秒级投递。要求 --deliver 为真实目标（非 log）。

| --script | 位于 ~/.hermes/scripts/ 下的过滤/转换脚本。webhook payload 以 JSON 形式通过 stdin 传入；JSON stdout 会替换 payload，空 stdout、[SILENT] 或非零退出码会忽略该 webhook。参见脚本过滤与转换。

订阅持久化到 ~/.hermes/webhook_subscriptions.json，webhook 适配器无需重启 gateway 即可热重载。

hermes doctor

hermes doctor [--fix]

| | 选项 | 说明

| --fix | 尽可能尝试自动修复。

hermes dump

hermes dump [--show-keys]

输出整个 Hermes 设置的紧凑纯文本摘要。专为复制粘贴到 Discord、GitHub issue 或 Telegram 寻求支持而设计——无 ANSI 颜色、无特殊格式，只有数据。

| | 选项 | 说明

| --show-keys | 显示脱敏的 API 密钥前缀（首尾各 4 个字符），而非仅显示 set/not set。

包含内容

| | 部分 | 详情

| Header | Hermes 版本、发布日期、git commit hash

| Environment | 操作系统、Python 版本、OpenAI SDK 版本

| Identity | 活跃 profile 名称、HERMES_HOME 路径

| Model | 已配置的默认模型和 provider

| Terminal | 后端类型（local、docker、ssh 等）

| API keys | 所有 22 个 provider/工具 API 密钥的存在性检查

| Features | 已启用的 toolset、MCP 服务器数量、memory provider

| Services | Gateway 状态、已配置的消息平台

| Workload | Cron 任务数量、已安装 skill 数量

| Config overrides | 与默认值不同的所有 config 值。其中的凭据会被脱敏：fallback_providers 条目的 api_key，以及其 base_url 中的凭据（userinfo、key/token 查询参数、签名 URL 的签名）。

示例输出

--- hermes dump ---
version:          0.8.0 (2026.4.8) [af4abd2f]
os:               Linux 6.14.0-37-generic x86_64
python:           3.11.14
openai_sdk:       2.24.0
profile:          default
hermes_home:      ~/.hermes
model:            anthropic/claude-opus-4.6
provider:         openrouter
terminal:         local

api_keys:
  openrouter           set
  openai               not set
  anthropic            set
  nous                 not set
  firecrawl            set
  ...

features:
  toolsets:           all
  mcp_servers:        0
  memory_provider:    built-in
  gateway:            running (systemd)
  platforms:          telegram, discord
  cron_jobs:          3 active / 5 total
  skills:             42

config_overrides:
  agent.max_turns: 250
  compression.threshold: 0.85
  display.streaming: True
--- end dump ---

使用场景

在 GitHub 上报告 bug——将 dump 粘贴到 issue 中
在 Discord 中寻求帮助——在代码块中分享
与他人对比设置
出现问题时快速进行健全性检查

提示

hermes dump 专为分享而设计。交互式诊断请使用 hermes doctor。可视化概览请使用 hermes status。

hermes debug

hermes debug share [options]

将调试报告（系统信息 + 近期日志）上传到粘贴服务并获取可分享的 URL。适用于快速支持请求——包含帮助者诊断问题所需的一切信息。

| | 选项 | 说明

| --lines <N> | 每个日志文件包含的日志行数（默认：200）。

| --expire <days> | 粘贴过期天数（默认：7）。

| --local | 在本地打印报告而非上传。

报告包含系统信息（操作系统、Python 版本、Hermes 版本）、近期 agent 和 gateway 日志（每文件 512 KB 限制）以及脱敏的 API 密钥状态。密钥始终脱敏——不会上传任何密钥；这也涵盖系统 dump（包括 fallback_providers 条目及其 URL 中的凭据）和 gateway 的 /debug 报告。

依次尝试的粘贴服务：paste.rs、dpaste.com。

示例

hermes debug share              # 上传调试报告，打印 URL
hermes debug share --lines 500  # 包含更多日志行
hermes debug share --expire 30  # 粘贴保留 30 天
hermes debug share --local      # 在终端打印报告（不上传）

hermes backup

hermes backup [options]

创建 Hermes 配置、skill、会话和数据的 zip 归档。备份不包含 hermes-agent 代码库本身。

| | 选项 | 说明

| -o, --output <path> | zip 文件的输出路径（默认：~/hermes-backup-<timestamp>.zip）。

| -q, --quick | 快速快照：仅包含关键状态文件（config.yaml、state.db、.env、auth、cron 任务）。比完整备份快得多。

| -l, --label <name> | 快照标签（仅与 --quick 配合使用）。

备份使用 SQLite 的 backup() API 进行安全复制，因此即使 Hermes 正在运行也能正确工作（WAL 模式安全）。

zip 中排除的内容：

*.db-wal、*.db-shm、*.db-journal — SQLite 的 WAL/共享内存/日志附属文件。*.db 文件已通过 sqlite3.backup() 获得一致快照；将活跃附属文件一并打包会导致恢复时看到半提交状态。
checkpoints/ — 每会话轨迹缓存。以 hash 为键，每次会话重新生成；无论如何都无法干净地移植到其他安装。
hermes-agent 代码本身（这是用户数据备份，不是仓库快照）。

示例

hermes backup                           # 完整备份到 ~/hermes-backup-*.zip
hermes backup -o /tmp/hermes.zip        # 完整备份到指定路径
hermes backup --quick                   # 仅状态快速快照
hermes backup --quick --label "pre-upgrade"  # 带标签的快速快照

hermes checkpoints

hermes checkpoints [COMMAND]

检查和管理 ~/.hermes/checkpoints/ 处的影子 git 存储——会话内 /rollback 命令的存储层。可随时安全运行；不需要 agent 正在运行。

| | 子命令 | 说明

| status（默认） | 显示总大小、项目数量和每个项目的详情。裸 hermes checkpoints 等同于此。

| list | status 的别名。

| prune | 强制执行清理——删除孤立和过期项目，GC 存储，强制执行大小上限。忽略 24 小时幂等性标记。

| clear | 删除整个 checkpoint 基础存储。不可逆；除非使用 -f 否则要求确认。

| clear-legacy | 仅删除 v1→v2 迁移产生的 legacy-<timestamp>/ 归档。

选项

| | 选项 | 子命令 | 说明

| --limit N | status、list | 最多列出的项目数（默认 20）。

| --retention-days N | prune | 删除 last_touch 早于 N 天的项目（默认 7）。

| --max-size-mb N | prune | 在孤立/过期清理后，删除每个项目最旧的 commit，直到总存储大小 ≤ N MB（默认 500）。

| --keep-orphans | prune | 跳过删除工作目录不再存在的项目。

| -f, --force | clear、clear-legacy | 跳过确认提示。

示例

hermes checkpoints                                  # 状态概览
hermes checkpoints prune --retention-days 3         # 激进清理
hermes checkpoints prune --max-size-mb 200          # 一次性收紧大小上限
hermes checkpoints clear-legacy -f                  # 删除 v1 归档目录
hermes checkpoints clear -f                         # 清除所有内容

完整架构和会话内命令，请参阅 Checkpoints 与 /rollback。

hermes import

hermes import <zipfile> [options]

将之前创建的 Hermes 备份恢复到 Hermes 主目录。归档中的所有文件会覆盖 Hermes 主目录中的现有文件；--force 仅跳过当目标已有 Hermes 安装时触发的确认提示。

| | 选项 | 说明

| -f, --force | 跳过已有安装的确认提示。

注意

导入前请停止 gateway，以避免与正在运行的进程冲突。

示例

hermes import ~/hermes-backup-20260423.zip           # 覆盖现有配置前提示确认
hermes import ~/hermes-backup-20260423.zip --force   # 不提示直接覆盖

hermes logs

hermes logs [log_name] [options]

查看、跟踪和过滤 Hermes 日志文件。所有日志存储在 ~/.hermes/logs/（非默认 profile 存储在 <profile>/logs/）。

日志文件

| | 名称 | 文件 | 记录内容

| agent（默认） | agent.log | 所有 agent 活动——API 调用、工具调度、会话生命周期（INFO 及以上）

| errors | errors.log | 仅警告和错误——agent.log 的过滤子集

| gateway | gateway.log | 消息 gateway 活动——平台连接、消息调度、webhook 事件

选项

| | 选项 | 说明

| log_name | 要查看的日志：agent（默认）、errors、gateway，或 list 以显示可用文件及大小。

| -n, --lines <N> | 显示的行数（默认：50）。

| -f, --follow | 实时跟踪日志，类似 tail -f。按 Ctrl+C 停止。

| --level <LEVEL> | 显示的最低日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL。

| --session <ID> | 过滤包含会话 ID 子字符串的行。

| --since <TIME> | 显示相对时间之前的行：30m、1h、2d 等。支持 s（秒）、m（分钟）、h（小时）、d（天）。

| --component <NAME> | 按组件过滤：gateway、agent、tools、cli、cron。

示例

# 查看 agent.log 的最后 50 行（默认）
hermes logs

# 实时跟踪 agent.log
hermes logs -f

# 查看 gateway.log 的最后 100 行
hermes logs gateway -n 100

# 仅显示最近一小时的警告和错误
hermes logs --level WARNING --since 1h

# 按特定会话过滤
hermes logs --session abc123

# 从 30 分钟前开始跟踪 errors.log
hermes logs errors --since 30m -f

# 列出所有日志文件及其大小
hermes logs list

过滤

过滤器可以组合使用。当多个过滤器同时激活时，日志行必须通过所有过滤器才会显示：

# 最近 2 小时内包含会话 "tg-12345" 的 WARNING+ 行
hermes logs --level WARNING --since 2h --session tg-12345

当 --since 激活时，没有可解析时间戳的行会被包含（它们可能是多行日志条目的续行）。当 --level 激活时，没有可检测级别的行会被包含。

日志轮转

Hermes 使用 Python 的 RotatingFileHandler。旧日志会自动轮转——查找 agent.log.1、agent.log.2 等。hermes logs list 子命令显示所有日志文件，包括已轮转的。

hermes config

hermes config <subcommand>

子命令：

| | 子命令 | 说明

| show | 显示当前 config 值。

| edit | 在编辑器中打开 config.yaml。

| set <key> <value> | 设置 config 值。

| path | 打印 config 文件路径。

| env-path | 打印 .env 文件路径。

| check | 检查缺失或过期的 config。

| migrate | 交互式添加新引入的选项。

hermes pairing

hermes pairing <list|approve|revoke|clear-pending>

| | 子命令 | 说明

| list | 显示待处理和已审批的用户。

| approve <platform> <code> | 审批配对码。

| revoke <platform> <user-id> | 撤销用户的访问权限。

| clear-pending | 清除待处理的配对码。

hermes skills

hermes skills <subcommand>

子命令：

| | 子命令 | 说明

| browse | 分页浏览 skill 注册表。

| search | 搜索 skill 注册表。

| install | 安装 skill。

| inspect | 预览 skill 而不安装。

| list | 列出已安装的 skill。

| check | 检查已安装的 hub skill 是否有上游更新。

| update | 在有上游变更时重新安装 hub skill。

| audit | 重新扫描已安装的 hub skill。

| uninstall | 删除通过 hub 安装的 skill。

| reset | 通过清除 manifest 条目，取消将捆绑 skill 标记为 user_modified 的状态。使用 --restore 时，还会将用户副本替换为捆绑版本。

| publish | 将 skill 发布到注册表。

| snapshot | 导出/导入 skill 配置。

| tap | 管理自定义 skill 来源。

| config | 按平台交互式启用/禁用 skill 配置。

常用示例：

hermes skills browse
hermes skills browse --source official
hermes skills search react --source skills-sh
hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect official/security/1password
hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react
hermes skills install official/migration/openclaw-migration
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills install https://sharethis.chat/SKILL.md                     # 直接 URL（含引用的支持文件）
hermes skills install https://example.com/SKILL.md --name my-skill        # frontmatter 无名称时覆盖名称
hermes skills check
hermes skills update
hermes skills config
hermes skills reset google-workspace
hermes skills reset google-workspace --restore --yes

注意：

--force 可以覆盖第三方/社区 skill 的非危险性策略阻止。
--force 不覆盖 dangerous 扫描结论。
--source skills-sh 搜索公共 skills.sh 目录。
--source well-known 允许你将 Hermes 指向暴露 /.well-known/skills/index.json 的站点。
--source browse-sh 搜索 browse.sh 包含 200+ 站点特定浏览器自动化 skill 的目录。标识符形如 browse-sh/airbnb.com/search-listings-ddgioa。
传入 http(s)://…/*.md URL 可安装 SKILL.md，以及其中明确引用且位于 references/、templates/、scripts/、assets/ 和 examples/ 下的文件。当 frontmatter 没有 name: 且 URL slug 不是有效标识符时，交互式终端会提示输入名称；非交互式界面（TUI 内的 /skills install、gateway 平台）需要改用 --name <x>。

hermes bundles

hermes bundles <subcommand>

Skill bundle 将多个 skill 归组到一个 /<bundle-name> 斜杠命令下。调用 bundle 会将每个引用的 skill 加载到单个合并的用户消息中。存储位置：~/.hermes/skill-bundles/<slug>.yaml。YAML schema 和行为请参阅 Skill Bundles。

子命令：

| | 子命令 | 说明

| list | 列出已安装的 bundle（不带子命令时的默认行为）

| show <name> | 显示某个 bundle 的名称、描述、skill 和文件路径

| create <name> | 创建新 bundle。传入 --skill <id>（可重复）或省略以进行交互式输入。支持 --description、--instruction、--force。

| delete <name> | 删除 bundle 文件

| reload | 重新扫描 ~/.hermes/skill-bundles/ 并报告新增/删除的 bundle

示例：

hermes bundles create backend-dev \
  --skill github-code-review \
  --skill test-driven-development \
  --skill github-pr-workflow \
  -d "Backend feature work"

hermes bundles list
hermes bundles show backend-dev
hermes bundles delete backend-dev

在聊天会话中，/bundles 列出已安装的 bundle，/<bundle-name> 加载某个 bundle。

hermes curator

hermes curator <subcommand>

Curator 是一个辅助模型后台任务，定期审查 agent 创建的 skill，修剪过期的，合并重叠的，并归档过时的。捆绑和通过 hub 安装的 skill 不会被触及。归档可恢复；不会发生自动删除。

| | 子命令 | 说明

| status | 显示 curator 状态和 skill 统计

| run | 立即触发 curator 审查（阻塞直到 LLM 处理完成）

| run --background | 在后台线程中启动 LLM 处理并立即返回

| run --dry-run | 仅预览——生成审查报告但不进行任何修改

| backup | 手动对 ~/.hermes/skills/ 进行 tar.gz 快照（curator 在每次真实运行前也会自动快照）

| rollback | 从快照恢复 ~/.hermes/skills/（默认使用最新快照）

| rollback --list | 列出可用快照

| rollback --id <ts> | 按 id 恢复特定快照

| rollback -y | 跳过确认提示

| pause | 暂停 curator 直到恢复

| resume | 恢复已暂停的 curator

| pin <skill> | 固定 skill，使 curator 永不自动转换其状态

| unpin <skill> | 取消固定 skill

| restore <skill> | 恢复已归档的 skill

| archive <skill> | 手动归档 skill

| prune | 手动修剪 curator 通常会清理的 skill

| list-archived | 列出已归档的 skill（可通过 restore 恢复）

在全新安装时，第一次计划运行会延迟一个完整的 interval_hours（默认 7 天）——gateway 不会在 hermes update 后的第一次 tick 时立即执行 curator。使用 hermes curator run --dry-run 在此之前预览。

行为和配置请参阅 Curator。

hermes fallback

hermes fallback <subcommand>

管理 fallback provider 链。当主模型因速率限制、过载或连接错误而失败时，按顺序尝试 fallback provider。

| | 子命令 | 说明

| list（别名：ls） | 显示当前 fallback 链（不带子命令时的默认行为）

| add | 选择 provider + 模型（与 hermes model 相同的选择器）并追加到链末尾

| remove（别名：rm） | 选择要从链中删除的条目

| clear | 删除所有 fallback 条目

参见 Fallback Providers。

hermes hooks

hermes hooks <subcommand>

检查 ~/.hermes/config.yaml 中声明的 shell 脚本 hook，针对合成 payload 测试它们，并管理 ~/.hermes/shell-hooks-allowlist.json 处的首次使用同意许可名单。

| | 子命令 | 说明

| list（别名：ls） | 列出已配置的 hook 及其匹配器、超时和同意状态

| test <event> | 针对合成 payload 触发匹配 <event> 的所有 hook

| revoke（别名：remove、rm） | 删除某个命令的许可名单条目（下次重启后生效）

| doctor | 检查每个已配置的 hook：可执行位、许可名单、mtime 漂移、JSON 有效性和合成运行计时

事件签名和 payload 格式请参阅 Hooks。

hermes memory

hermes memory <subcommand>

设置和管理外部 memory provider plugin。可用 provider：honcho、openviking、mem0、hindsight、holographic、retaindb、byterover、supermemory。同一时间只能有一个外部 provider 处于活跃状态。内置 memory（MEMORY.md/USER.md）始终处于活跃状态。

子命令：

| | 子命令 | 说明

| setup | 交互式 provider 选择和配置。

| status | 显示当前 memory provider 配置。

| off | 禁用外部 provider（仅使用内置）。

Provider 特定子命令

当外部 memory provider 处于活跃状态时，它可能会注册自己的顶级 hermes <provider> 命令用于 provider 特定管理（例如 Honcho 激活时的 hermes honcho）。未激活的 provider 不暴露其子命令。运行 hermes --help 查看当前已连接的命令。

hermes acp

hermes acp

将 Hermes 作为 ACP（Agent Client Protocol）stdio 服务器启动，用于编辑器集成。

hermes mcp

hermes mcp <subcommand>

管理 MCP（Model Context Protocol）服务器配置，并将 Hermes 作为 MCP 服务器运行。

| | 子命令 | 说明

| serve [-v|--verbose] | 将 Hermes 作为 MCP 服务器运行——向其他 agent 暴露对话。

| add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth|header] | 添加 MCP 服务器并自动发现工具。

| remove <name>（别名：rm） | 从 config 中删除 MCP 服务器。

| list（别名：ls） | 列出已配置的 MCP 服务器。

| test <name> | 测试与 MCP 服务器的连接。

| configure <name>（别名：config） | 切换服务器的工具选择。

| login <name> | 强制重新认证基于 OAuth 的 MCP 服务器。

参见 MCP 配置参考、在 Hermes 中使用 MCP 和 MCP 服务器模式。

hermes plugins

hermes plugins [subcommand]

统一的 plugin 管理——通用 plugin、memory provider 和 context engine 集于一处。不带子命令运行 hermes plugins 会打开包含两个部分的复合交互界面：

General Plugins — 多选复选框，用于启用/禁用已安装的 plugin
Provider Plugins — 单选配置，用于 Memory Provider 和 Context Engine。在某个类别上按 ENTER 打开单选选择器。

| | 子命令 | 说明

| （无） | 复合交互界面——通用 plugin 切换 + provider plugin 配置。

| install <identifier> [--force] | 从 Git URL 或 owner/repo 安装 plugin。

| update <name> | 拉取已安装 plugin 的最新变更。

| remove <name>（别名：rm、uninstall） | 删除已安装的 plugin。

| enable <name> | 启用已禁用的 plugin。

| disable <name> | 禁用 plugin 而不删除。

| list（别名：ls） | 列出已安装的 plugin 及启用/禁用状态。

Provider plugin 选择保存到 config.yaml：

memory.provider — 活跃 memory provider（为空 = 仅内置）
context.engine — 活跃 context engine（"compressor" = 内置默认值）

通用 plugin 禁用列表存储在 config.yaml 的 plugins.disabled 下。

参见 Plugins 和构建 Hermes Plugin。

hermes tools

hermes tools [--summary]

| | 选项 | 说明

| --summary | 打印当前已启用工具摘要并退出。

不带 --summary 时，启动交互式按平台工具配置界面。

hermes computer-use

hermes computer-use <subcommand>

子命令：

| | 子命令 | 说明

| install | 运行上游 cua-driver 安装程序（仅 macOS）。

| install --upgrade | 即使 cua-driver 已在 PATH 中也重新运行安装程序。上游脚本始终拉取最新版本，因此这会执行原地升级。

| status | 打印 cua-driver 是否在 $PATH 中以及已安装的版本。

hermes computer-use install 是安装 computer_use toolset 使用的 cua-driver 二进制文件的稳定入口。它运行与首次启用 Computer Use 时 hermes tools 调用的相同上游安装程序，因此如果 toolset 切换未触发安装（例如在已配置用户的设置中），可以安全地用于重新运行安装。

hermes update 在更新结束时，如果 cua-driver 在 PATH 中，会自动重新运行上游安装程序，因此大多数用户不需要手动调用 --upgrade。当上游发布了你现在就想要的修复，而不想等待下次 Hermes 更新时，使用此选项。

hermes sessions

hermes sessions <subcommand>

子命令：

| | 子命令 | 说明

| list | 列出最近的会话。

| browse | 带搜索和恢复功能的交互式会话选择器。

| export <output> [--session-id ID] | 将会话导出为 JSONL。

| delete <session-id> | 删除单个会话。

| prune | 删除旧会话。

| stats | 显示会话存储统计信息。

| rename <session-id> <title> | 设置或更改会话标题。

hermes insights

hermes insights [--days N] [--source platform]

| | 选项 | 说明

| --days <n> | 分析最近 n 天（默认：30）。

| --source <platform> | 按来源过滤，如 cli、telegram 或 discord。

hermes claw

hermes claw migrate [options]

将 OpenClaw 设置迁移到 Hermes。从 ~/.openclaw（或自定义路径）读取并写入 ~/.hermes。自动检测旧版目录名（~/.clawdbot、~/.moltbot）和配置文件名（clawdbot.json、moltbot.json）。

| | 选项 | 说明

| --dry-run | 预览将迁移的内容而不写入任何内容。

| --preset <name> | 迁移预设：full（所有兼容设置）或 user-data（排除基础设施配置）。两种预设都不导入密钥——需要显式传入 --migrate-secrets。

| --overwrite | 在冲突时覆盖现有 Hermes 文件（默认：当计划有冲突时拒绝应用）。

| --migrate-secrets | 在迁移中包含 API 密钥。即使在 --preset full 下也需要显式指定。

| --no-backup | 跳过迁移前对 ~/.hermes/ 的 zip 快照（默认情况下，在应用前会将单个还原点归档写入 ~/.hermes/backups/pre-migration-*.zip；可用 hermes import 恢复）。

| --source <path> | 自定义 OpenClaw 目录（默认：~/.openclaw）。

| --workspace-target <path> | 工作区说明（AGENTS.md）的目标目录。

| --skill-conflict <mode> | 处理 skill 名称冲突：skip（默认）、overwrite 或 rename。

| --yes | 跳过确认提示。

迁移内容

迁移涵盖 30+ 个类别，包括 persona、memory、skill、模型 provider、消息平台、agent 行为、会话策略、MCP 服务器、TTS 等。条目要么直接导入到 Hermes 等效项，要么归档以供手动审查。

直接导入： SOUL.md、MEMORY.md、USER.md、AGENTS.md、skill（4 个源目录）、默认模型、自定义 provider、MCP 服务器、消息平台 token 和许可名单（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、agent 默认值（推理努力程度、压缩、人工延迟、时区、沙箱）、审批规则、TTS 配置、浏览器设置、工具设置、执行超时、命令许可名单、gateway 配置以及来自 3 个来源的 API 密钥。

归档以供手动审查： Cron 任务、plugin、hook/webhook、memory 后端（QMD）、skill 注册表配置、UI/身份、日志、多 agent 设置、频道绑定、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。

API 密钥解析按优先级顺序检查三个来源：config 值 → ~/.openclaw/.env → auth-profiles.json。所有 token 字段处理纯字符串、环境变量模板（${VAR}）和 SecretRef 对象。

完整的 config 键映射、SecretRef 处理详情和迁移后检查清单，请参阅**完整迁移指南**。

示例

# 预览将迁移的内容
hermes claw migrate --dry-run

# 完整迁移（所有兼容设置，不含密钥）
hermes claw migrate --preset full

# 包含 API 密钥的完整迁移
hermes claw migrate --preset full --migrate-secrets

# 仅迁移用户数据（不含密钥），覆盖冲突
hermes claw migrate --preset user-data --overwrite

# 从自定义 OpenClaw 路径迁移
hermes claw migrate --source /home/user/old-openclaw

hermes dashboard

hermes dashboard [options]

启动 Web 控制台，用于管理配置、API 密钥和会话。FastAPI、Uvicorn 和平台 PTY 辅助库是核心依赖。web extra 提供 HTTP 栈的精确约束，标准 PM 安装通过 all 选择它。如依赖损坏，请运行 hermes pm repair。内嵌 Chat 标签页需要 POSIX PTY 环境，例如 Linux、macOS 或 WSL2。请参阅 Web 控制台。

| | 选项 | 默认值 | 说明

| --port | 9119 | Web 服务器运行端口

| --host | 127.0.0.1 | 绑定地址

| --no-open | — | 不自动打开浏览器

| --insecure | 关闭 | 已弃用 / 无实际作用。此参数曾用于在非回环绑定上绕过鉴权；自 2026 年 6 月安全加固后，公网绑定始终需要用户名/密码或 OAuth 鉴权提供方。若需保持仅本地访问，请绑定 127.0.0.1 并通过隧道连接。

| --stop | — | 停止正在运行的 hermes dashboard 进程并退出。

| --status | — | 列出正在运行的 hermes dashboard 进程并退出。

# 默认——在浏览器中打开 http://127.0.0.1:9119
hermes dashboard

# 自定义端口，不打开浏览器
hermes dashboard --port 8080 --no-open

hermes profile

hermes profile <subcommand>

管理 profile——多个隔离的 Hermes 实例，每个实例拥有自己的 config、会话、skill 和主目录。

| | 子命令 | 说明

| list | 列出所有 profile。

| use <name> | 设置粘性默认 profile。

| create <name> [--clone] [--clone-all] [--clone-from <source>] [--no-alias] | 创建新 profile。--clone 从活跃 profile 复制 config、.env、SOUL.md 和 skills。--clone-all 复制所有状态。--clone-from 指定源 profile，除非与 --clone-all 配合使用，否则会隐含 config 克隆。

| delete <name> [-y] | 删除 profile。

| show <name> | 显示 profile 详情（主目录、config 等）。

| alias <name> [--remove] [--name NAME] | 管理快速访问 profile 的包装脚本。

| rename <old> <new> | 重命名 profile。

| export <name> [-o FILE] | 将 profile 导出为 .tar.gz 归档（本地备份）。

| import <archive> [--name NAME] | 从 .tar.gz 归档导入 profile（本地恢复）。

| install <source> [--name N] [--alias] [--force] [-y] | 从 git URL 或本地目录安装 profile 发行版。

| update <name> [--force-config] [-y] | 重新拉取发行版；保留用户数据（memory、会话、auth）。

| info <name> | 显示 profile 的发行版 manifest（版本、依赖、来源）。

示例：

hermes profile list
hermes profile create work --clone
hermes profile use work
hermes profile alias work --name h-work
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes profile install github.com/user/my-distro --alias
hermes profile update work
hermes -p work chat -q "Hello from work profile"

hermes completion

hermes completion [bash|zsh|fish]

将 shell 补全脚本打印到 stdout。在 shell profile 中 source 输出内容，即可对 Hermes 命令、子命令和 profile 名称进行 Tab 补全。

示例：

# Bash
hermes completion bash >> ~/.bashrc

# Zsh
hermes completion zsh >> ~/.zshrc

# Fish
hermes completion fish > ~/.config/fish/completions/hermes.fish

hermes pm

PM 管理工具和 Python 依赖，不负责替换应用发布包。

源码开发先运行一次 setup 脚本，然后用 Bash source ./activate 或 PowerShell . .\activate.ps1 激活已有环境。

使用 deactivate 恢复激活前的环境。

详见PM 开发工作流，包括依赖更新和测试环境。

hermes update

hermes update [--check] [--backup] [--restart-gateway]

拉取最新的 hermes-agent 代码并在受管理的 venv 中重新安装依赖，然后重新运行安装后 hook（MCP 服务器、skill 同步、补全安装）。可在运行中的安装上安全执行。官方仓库的源码检出默认跟踪 stable 渠道（最新正式发布的 vX.Y.Z 版本）；运行 hermes update --set-channel main 改为跟踪 main 上的每个提交，hermes update --set-channel stable 切换回来。使用 --check 查看你的检出是否落后于所选渠道，而不安装。

| | 选项 | 说明

| --check | 并排打印当前 commit 和所选渠道的目标 commit，同步时退出码为 0，落后时为 1。不拉取、不安装、不重启任何内容。

| --backup | 在拉取前创建 HERMES_HOME 的带标签预更新快照（config、auth、会话、skill、配对数据）。默认关闭——之前的始终备份行为在大型主目录上每次更新会增加数分钟。通过 config.yaml 中的 update.backup: true 永久开启。

| --restart-gateway | 成功更新后重启正在运行的 gateway 服务。如果安装了多个 profile，隐含 --all 语义。

附加行为：

配对数据快照。即使 --backup 关闭，hermes update 也会在 git pull 前对 ~/.hermes/pairing/ 和 Feishu 评论规则进行轻量快照。如果拉取覆盖了你正在编辑的文件，可以用 hermes backup restore --state pre-update 回滚。
旧版 hermes.service 警告。如果 Hermes 检测到预重命名的 hermes.service systemd 单元（而非当前的 hermes-gateway.service），会打印一次性迁移提示，帮助你避免循环重启问题。
退出码。成功时为 0，拉取/安装/安装后错误时为 1，阻止 git pull 的意外工作树变更时为 2。

维护命令

| | 命令 | 说明

| hermes --version | 打印版本信息。

| hermes update | 拉取最新变更并重新安装依赖。

| hermes uninstall [--full] [--yes] | 删除 Hermes，可选择删除所有 config/数据。

另请参阅

斜杠命令参考
CLI 界面
会话
Skill 系统
皮肤与主题

目录

快速入门

更喜欢看视频？​

适用人群​

最快路径​

1. 安装 Hermes Agent​

在 macOS 或 Windows 上使用 Hermes Desktop 安装器（推荐）​

不使用 Hermes Desktop：​

2. 选择 Provider​

配置的存储方式​

3. 运行第一次对话​

4. 验证会话功能​

5. 尝试核心功能​

使用终端​

斜杠命令​

多行输入​

中断 Agent​

6. 添加下一层功能​

机器人或共享助手​

自动化与工具​

沙箱终端​

语音模式​

Skills​

MCP 服务器​

编辑器集成（ACP）​

常见故障模式​

恢复工具包​

快速参考​

下一步​

安装

快速安装​

一行安装命令（Linux / macOS / WSL2）​

Windows（原生，PowerShell）​

Android / Termux​

功能与安装目录​

安装后​

前置条件​

手动 / 开发者安装​

非 Sudo / 系统服务用户安装​

故障排查​

安装方式自动检测​

学习路径

如何使用本页​

按经验水平​

按使用场景​

"我想要一个 CLI 编程助手"​

"我想要一个 Telegram/Discord 机器人"​

"我想自动化任务"​

"我想构建自定义工具/技能"​

"我想训练模型"​

"我想将其作为 Python 库使用"​

主要功能一览​

下一步阅读​

Platform Support

Tier 1​

Tier 2​

Build targets and support priority​

Unsupported​

在 Android 上使用 Termux

安装​

数据、更新和卸载​

Gateway 和限制​

更新与卸载

更新​

更新过程​

仅预览：hermes update --check​

完整更新前备份：--backup​

Windows：另一个 hermes.exe 正在运行​

更新后建议的验证步骤​

终端在更新中途断开连接​

查看当前版本​

从消息平台更新​

手动更新​

回滚说明​

Nix 用户注意事项​

卸载​

手动卸载​

Nix & NixOS 安装配置

PM 固定版本​

前提条件​

更喜欢看视频？

适用人群

最快路径

1. 安装 Hermes Agent

在 macOS 或 Windows 上使用 Hermes Desktop 安装器（推荐）

不使用 Hermes Desktop：

2. 选择 Provider

配置的存储方式

3. 运行第一次对话

4. 验证会话功能

5. 尝试核心功能

使用终端

斜杠命令

多行输入

中断 Agent

6. 添加下一层功能

机器人或共享助手

自动化与工具

沙箱终端

语音模式

Skills

MCP 服务器

编辑器集成（ACP）

常见故障模式

恢复工具包

快速参考

下一步

快速安装

一行安装命令（Linux / macOS / WSL2）

Windows（原生，PowerShell）

Android / Termux

功能与安装目录

安装后

前置条件

手动 / 开发者安装

非 Sudo / 系统服务用户安装

故障排查

安装方式自动检测

如何使用本页

按经验水平

按使用场景

"我想要一个 CLI 编程助手"

"我想要一个 Telegram/Discord 机器人"

"我想自动化任务"

"我想构建自定义工具/技能"

"我想训练模型"

"我想将其作为 Python 库使用"

主要功能一览

下一步阅读

Tier 1

Tier 2

Build targets and support priority

Unsupported

安装

数据、更新和卸载

Gateway 和限制

更新

更新过程

仅预览：hermes update --check

完整更新前备份：--backup

Windows：另一个 hermes.exe 正在运行

更新后建议的验证步骤

终端在更新中途断开连接

查看当前版本

从消息平台更新

手动更新

回滚说明

Nix 用户注意事项

卸载

手动卸载

PM 固定版本

前提条件

快速开始（任意 Nix 用户）

NixOS 模块

添加 Flake 输入

最小化配置

容器感知 CLI

验证运行状态

选择部署模式

配置