CLI 命令参考

本页涵盖在 Shell 中运行的终端命令。

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

全局入口

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

全局选项

选项	描述
--version, -V	显示版本并退出。
--profile <name>, -p <name>	选择本次调用使用的 Hermes 配置文件。覆盖通过 hermes profile use 设置的默认配置文件。
--resume <session>, -r <session>	通过 ID 或标题恢复之前的会话。
--continue [name], -c [name]	恢复最近的会话，或恢复与标题匹配的最近会话。
--worktree, -w	在隔离的 git worktree 中启动，用于并行 Agent 工作流。
--yolo	绕过危险命令审批提示。
--pass-session-id	在 Agent 的系统提示中包含会话 ID。
--ignore-user-config	忽略 ~/.hermes/config.yaml，回退到内置默认值。.env 中的凭据仍会加载。
--ignore-rules	跳过 AGENTS.md、SOUL.md、.cursorrules、记忆和预加载技能的自动注入。
--tui	启动 TUI 而非经典 CLI。等同于 HERMES_TUI=1。
--dev	与 --tui 配合使用：通过 tsx 直接运行 TypeScript 源码而非预构建包（用于 TUI 贡献者）。

顶层命令

命令	用途
hermes chat	与 Agent 进行交互式或单次聊天。
hermes model	交互式选择默认提供商和模型。
hermes fallback	管理当主模型出错时尝试的备用提供商。
hermes gateway	运行或管理消息网关服务。
hermes proxy	本地 OpenAI 兼容代理，用于附加 OAuth 提供商凭据。参见订阅代理。
hermes lsp	管理语言服务器协议集成（用于 write_file/patch 的语义诊断）。
hermes setup	交互式设置向导，用于配置全部或部分选项。
hermes whatsapp	配置并配对 WhatsApp 桥接。
hermes slack	Slack 辅助工具（当前：生成包含所有命令作为原生斜杠命令的应用清单）。
hermes auth	管理凭据 — 添加、列出、删除、重置、设置策略。处理 Codex/Nous/Anthropic 的 OAuth 流程。
hermes login / logout	已弃用 — 请改用 hermes auth。
hermes status	显示 Agent、认证和平台状态。
hermes cron	检查和触发定时任务调度器。
hermes kanban	多配置文件协作看板（任务、链接、调度器）。
hermes webhook	管理事件驱动激活的动态 Webhook 订阅。
hermes hooks	检查、审批或删除在 config.yaml 中声明的 Shell 脚本钩子。
hermes doctor	诊断配置和依赖问题。
hermes dump	可直接复制粘贴的设置摘要，用于支持/调试。
hermes debug	调试工具 — 上传日志和系统信息以获取支持。
hermes backup	将 Hermes 主目录备份为 zip 文件。
hermes checkpoints	检查/清理 ~/.hermes/checkpoints/（/rollback 使用的影子存储）。不带参数运行可查看状态概览。
hermes import	从 zip 文件还原 Hermes 备份。
hermes logs	查看、跟踪和过滤 Agent/网关/错误日志文件。
hermes config	显示、编辑、迁移和查询配置文件。
hermes pairing	审批或撤销消息配对码。
hermes skills	浏览、安装、发布、审计和配置技能。
hermes curator	后台技能维护 — 状态、运行、暂停、锁定。参见 Curator。
hermes memory	配置外部记忆提供商插件。特定于插件的子命令（如 hermes honcho）在其提供商激活时自动注册。
hermes acp	将 Hermes 作为 ACP 服务器运行，用于编辑器集成。
hermes mcp	管理 MCP 服务器配置，并将 Hermes 作为 MCP 服务器运行。
hermes plugins	管理 Hermes Agent 插件（安装、启用、禁用、删除）。
hermes tools	按平台配置启用的工具。
hermes computer-use	安装或检查 cua-driver 后端（macOS Computer Use）。
hermes sessions	浏览、导出、清理、重命名和删除会话。
hermes insights	显示 Token/费用/活动分析。
hermes claw	OpenClaw 迁移辅助工具。
hermes profile	管理配置文件 — 多个独立的 Hermes 实例。
hermes completion	打印 Shell 补全脚本（bash/zsh/fish）。
hermes version	显示版本信息。
hermes update	拉取最新代码并重新安装依赖。--check 在不拉取的情况下打印 commit 差异；--backup 在拉取前对 HERMES_HOME 进行快照。
hermes uninstall	从系统中删除 Hermes。

hermes chat

hermes chat [options]

常用选项：

选项	描述
-q, --query "..."	单次非交互式提示。
-m, --model <model>	覆盖本次运行的模型。
-t, --toolsets <csv>	启用逗号分隔的工具集列表。
--provider <provider>	强制使用指定提供商：auto、openrouter、nous、openai-codex、copilot-acp、copilot、anthropic、gemini、google-gemini-cli、huggingface、novita、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）、qwen-oauth、bedrock、opencode-zen、opencode-go、ai-gateway、azure-foundry、lmstudio、stepfun、tencent-tokenhub（别名 tencent、tokenhub）。
-s, --skills <name>	为会话预加载一个或多个技能（可重复指定或以逗号分隔）。
-v, --verbose	详细输出。
-Q, --quiet	程序化模式：抑制 Banner/Spinner/工具预览。
--image <path>	为单次查询附加本地图片。
--resume <session> / --continue [name]	直接从 chat 中恢复会话。
--worktree	为本次运行创建独立的 git worktree。
--checkpoints	在破坏性文件更改前启用文件系统检查点。
--yolo	跳过审批提示。
--pass-session-id	将会话 ID 传入系统提示。
--ignore-user-config	忽略 ~/.hermes/config.yaml，使用内置默认值。.env 中的凭据仍会加载。用于隔离 CI 运行、可复现的 Bug 报告和第三方集成。
--ignore-rules	跳过 AGENTS.md、SOUL.md、.cursorrules、持久化记忆和预加载技能的自动注入。与 --ignore-user-config 配合使用可实现完全隔离运行。
--source <tag>	用于过滤的会话来源标签（默认：cli）。对于不应出现在用户会话列表中的第三方集成，可使用 tool。
--max-turns <N>	每次对话轮次的最大工具调用迭代次数（默认：90，或 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、定时任务、通过管道传入提示的父进程），hermes -z 是最纯粹的单次入口：单一提示词进，最终响应文本出，stdout 和 stderr 上不输出任何其他内容。 没有 Banner、没有 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>	HERMES_INFERENCE_PROVIDER	覆盖本次运行的提供商

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

相同的 Agent、相同的工具、相同的技能 — 只是剥去所有交互式/装饰性层。如果你还需要在记录中包含工具输出，请使用 hermes chat -q；-z 专为"我只需要最终答案"的场景设计。

hermes model

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

hermes model

适用场景：

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

hermes model 与 /model — 了解区别

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

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

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

/model 斜杠命令（会话中）

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

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

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

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

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

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

提供商和基础 URL 的更改会自动持久化到 config.yaml。切换离开自定义端点时，过时的基础 URL 将被清除以防止泄漏到其他提供商。

hermes gateway

hermes gateway <subcommand>

子命令：

子命令	描述
run	在前台运行网关。推荐用于 WSL、Docker 和 Termux。
start	启动已安装的 systemd/launchd 后台服务。
stop	停止服务（或前台进程）。
restart	重启服务。
status	显示服务状态。
install	安装为 systemd（Linux）或 launchd（macOS）后台服务。
uninstall	删除已安装的服务。
setup	交互式消息平台设置。

选项：

选项	描述
--all	在 start / restart / stop 时：作用于所有配置文件的网关，而非仅活跃的 HERMES_HOME。在并行运行多个配置文件并希望在 hermes update 后全部重启时很有用。

WSL 用户

请使用 hermes gateway run 而非 hermes gateway start — WSL 的 systemd 支持不稳定。通过 tmux 保持持久运行：tmux new -s hermes 'hermes gateway run'。详情参见 WSL FAQ。

hermes lsp

hermes lsp <subcommand>

管理语言服务器协议集成。LSP 在后台运行真实的 语言服务器（pyright、gopls、rust-analyzer 等）， 并将其诊断信息注入 write_file 和 patch 使用的写后检查。 受 git 工作区检测约束——仅当 cwd 或编辑的文件位于 git 工作树内时，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]

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

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

直接跳转到某个部分而无需完整向导：

部分	描述
model	提供商和模型设置。
terminal	终端后端和沙箱设置。
gateway	消息平台设置。
tools	按平台启用/禁用工具。
agent	Agent 行为设置。

选项：

选项	描述
--quick	老用户运行时：仅提示缺失或未设置的项。跳过已配置的项。
--non-interactive	使用默认值/环境值，不显示提示。
--reset	在设置前将配置重置为默认值。
--reconfigure	向后兼容别名 — 现有安装上的 hermes setup 默认执行此操作。

hermes whatsapp

hermes whatsapp

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

hermes slack

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

生成 Slack 应用清单，将 COMMAND_REGISTRY 中的所有网关命令（/btw、/stop、/model……）注册为 Slack 原生斜杠命令，与 Discord 和 Telegram 保持功能对等。将输出粘贴到 https://api.slack.com/apps 中的 Slack 应用配置 → 你的应用 → Features → App Manifest → Edit，然后保存。如果 scope 或斜杠命令有变动，Slack 会提示重新安装。

标志	默认值	用途
--write [PATH]	stdout	写入文件而非 stdout。单独使用 --write 写入 $HERMES_HOME/slack-manifest.json。
--name NAME	Hermes	Slack 中的机器人显示名称。
--description DESC	默认描述	Slack 应用目录中显示的机器人描述。
--slashes-only	关闭	仅输出 features.slash_commands，用于合并到手动维护的清单中。

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

hermes login / hermes logout （已弃用）

警告

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

hermes auth

管理同一提供商的凭据池，用于密钥轮换。完整文档请参阅凭据池。

hermes auth                                              # 交互式向导
hermes auth list                                         # 显示所有池
hermes auth list openrouter                              # 显示特定提供商
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                             # 显示提供商的认证状态
hermes auth logout anthropic                             # 退出登录并清除存储的认证状态
hermes auth spotify                                      # 通过 PKCE 用 Spotify 认证 Hermes

子命令：add、list、remove、reset、status、logout、spotify。不带子命令调用时，启动交互式管理向导。

hermes status

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

选项	描述
--all	以可共享的脱敏格式显示所有详情。
--deep	运行可能耗时更长的深层检查。

hermes cron

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

子命令	描述
list	显示已调度的任务。
create / add	从提示词创建调度任务，可通过重复 --skill 附加一个或多个技能。
edit	更新任务的调度计划、提示词、名称、投递方式、重复次数或附加技能。支持 --clear-skills、--add-skill 和 --remove-skill。
pause	暂停任务而不删除。
resume	恢复已暂停的任务并计算下次运行时间。
run	在下次调度器触发时执行任务。
remove	删除已调度的任务。
status	检查定时任务调度器是否正在运行。
tick	运行到期的任务一次后退出。

hermes kanban

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

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

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

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

这是面向人类/脚本的操作界面。 由调度器生成的 Agent 工作者通过专用的 kanban_* 工具集（kanban_show、kanban_complete、kanban_block、kanban_create、kanban_link、kanban_comment、kanban_heartbeat）驱动看板，而非调用 hermes kanban。工作者在其环境中固定了 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、--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>"	追加评论。下一个认领任务的工作者会在其 kanban_show() 响应中读取到。
complete <id>	将任务标记为完成。标志：--result、--summary、--metadata。
block <id> "<reason>"	将任务标记为阻塞。同时将原因追加为评论。
unblock <id>	将阻塞的任务恢复为就绪状态。
archive <id>	从默认列表隐藏。gc 将删除临时工作区。
tail <id>	跟踪任务的事件流。
dispatch	在活跃看板上执行一次调度器遍历。标志：--dry-run、--max N、--json。
context <id>	打印工作者将看到的完整上下文（标题 + 正文 + 父任务结果 + 评论）。
specify <id> / specify --all	通过辅助 LLM 将 triage 列中的任务扩展为完整规格（标题 + 正文含目标、方案、验收标准），然后提升为 todo。标志：--tenant（将 --all 限定到某个租户）、--author、--json。在 config.yaml 的 auxiliary.triage_specifier 下配置模型。
gc	清除已归档任务的临时工作区。

示例：

# 创建第二个看板并在不切换的情况下添加任务
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。

所有操作也可作为网关中的斜杠命令（/kanban …）使用，具有相同的参数结构 — 包括 boards 子命令和 --board 标志。

hermes webhook

hermes webhook <subscribe|list|remove|test>

管理事件驱动 Agent 激活的动态 Webhook 订阅。需要在配置中启用 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} 负载引用的提示词模板。
--events	接受的事件类型，逗号分隔（如 issues,pull_request）。空 = 全部。
--description	人类可读的描述。
--skills	为 Agent 运行加载的技能名称，逗号分隔。
--deliver	投递目标：log（默认）、telegram、discord、slack、github_comment。
--deliver-chat-id	跨平台投递的目标聊天/频道 ID。
--secret	自定义 HMAC 密钥。省略时自动生成。
--deliver-only	跳过 Agent — 将渲染后的 --prompt 作为字面消息投递。零 LLM 费用，亚秒级投递。要求 --deliver 为真实目标（非 log）。

订阅持久化到 ~/.hermes/webhook_subscriptions.json，网关无需重启即可热加载。

hermes doctor

hermes doctor [--fix]

选项	描述
--fix	尽可能尝试自动修复。

hermes dump

hermes dump [--show-keys]

输出完整 Hermes 设置的紧凑纯文本摘要。专为在 Discord、GitHub Issues 或 Telegram 中寻求支持时复制粘贴而设计 — 无 ANSI 颜色、无特殊格式，只有数据。

选项	描述
--show-keys	显示脱敏的 API 密钥前缀（前后各 4 个字符），而非仅显示 set/not set。

包含内容

部分	详情
Header	Hermes 版本、发布日期、git commit 哈希
Environment	操作系统、Python 版本、OpenAI SDK 版本
Identity	活跃配置文件名称、HERMES_HOME 路径
Model	已配置的默认模型和提供商
Terminal	后端类型（local、docker、ssh 等）
API keys	所有 22 个提供商/工具 API 密钥的存在性检查
Features	启用的工具集、MCP 服务器数量、记忆提供商
Services	网关状态、已配置的消息平台
Workload	定时任务数量、已安装的技能数量
Config overrides	与默认值不同的配置值

示例输出

--- 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 和网关日志（每文件 512 KB 限制）以及脱敏的 API 密钥状态。密钥始终脱敏 — 不上传任何密钥。

粘贴服务按序尝试：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 配置、技能、会话和数据的 zip 归档。备份不包含 hermes-agent 代码库本身。

选项	描述
-o, --output <path>	zip 文件的输出路径（默认：~/hermes-backup-<timestamp>.zip）。
-q, --quick	快速快照：仅备份关键状态文件（config.yaml、state.db、.env、auth、定时任务）。比完整备份快得多。
-l, --label <name>	快照标签（仅与 --quick 配合使用）。

备份使用 SQLite 的 backup() API 进行安全复制，因此即使 Hermes 正在运行也能正确工作（WAL 模式安全）。

从 zip 中排除的内容：

• *.db-wal、*.db-shm、*.db-journal — SQLite 的 WAL/共享内存/日志附属文件。*.db 文件已通过 sqlite3.backup() 获得一致性快照；连同实时附属文件一起发送会导致还原时看到半提交状态。
• checkpoints/ — 每会话轨迹缓存。基于哈希键且每会话重新生成；无论如何都无法干净地移植到其他安装。
• 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 存储，执行大小上限。忽略 24h 幂等性标记。
clear	删除整个检查点基础。不可逆；除非加 -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                         # 清除所有内容

参见检查点与 /rollback了解完整架构和会话内命令。

hermes import

hermes import <zipfile> [options]

将之前创建的 Hermes 备份还原到 Hermes 主目录。归档中的所有文件会覆盖主目录中的现有文件；--force 仅跳过目标已有 Hermes 安装时出现的确认提示。

选项	描述
-f, --force	跳过现有安装的确认提示。

注意

导入前请停止网关，以避免与运行中的进程冲突。

示例

hermes import ~/hermes-backup-20260423.zip           # 覆盖现有配置前提示确认
hermes import ~/hermes-backup-20260423.zip --force   # 无提示覆盖

hermes logs

hermes logs [log_name] [options]

查看、跟踪和过滤 Hermes 日志文件。所有日志存储在 ~/.hermes/logs/（非默认配置文件为 <profile>/logs/）。

日志文件

名称	文件	捕获内容
agent（默认）	agent.log	所有 Agent 活动 — API 调用、工具分发、会话生命周期（INFO 及以上）
errors	errors.log	仅警告和错误 — agent.log 的过滤子集
gateway	gateway.log	消息网关活动 — 平台连接、消息分发、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	显示当前配置值。
edit	在编辑器中打开 config.yaml。
set <key> <value>	设置配置值。
path	打印配置文件路径。
env-path	打印 .env 文件路径。
check	检查缺失或过时的配置。
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	技能注册表的分页浏览器。
search	搜索技能注册表。
install	安装技能。
inspect	预览技能而不安装。
list	列出已安装的技能。
check	检查已安装的 Hub 技能是否有上游更新。
update	在有上游变更时重新安装 Hub 技能。
audit	重新扫描已安装的 Hub 技能。
uninstall	删除通过 Hub 安装的技能。
reset	取消标记为 user_modified 的捆绑技能，方法是清除其清单条目。加 --restore 时，同时将用户副本替换为捆绑版本。
publish	将技能发布到注册表。
snapshot	导出/导入技能配置。
tap	管理自定义技能来源。
config	按平台交互式启用/禁用技能配置。

常用示例：

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（单文件 SKILL.md）
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 可以覆盖第三方/社区技能的非危险策略阻止。
• --force 不能覆盖 dangerous 扫描判定。
• --source skills-sh 搜索公共 skills.sh 目录。
• --source well-known 让 Hermes 指向暴露 /.well-known/skills/index.json 的站点。
• 传入 http(s)://…/*.md URL 直接安装单文件 SKILL.md。当 frontmatter 无 name: 且 URL slug 不是有效标识符时，交互式终端会提示输入名称；非交互式环境（TUI 中的 /skills install、网关平台）需要改用 --name <x>。

hermes curator

hermes curator <subcommand>

Curator 是一个辅助模型后台任务，定期审查 Agent 创建的技能、清理过时技能、合并重叠技能并归档废弃技能。捆绑技能和通过 Hub 安装的技能永不会被修改。归档可恢复；永不自动删除。

子命令	描述
status	显示 Curator 状态和技能统计
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>	锁定技能，Curator 永远不会自动转换它
unpin <skill>	解除技能锁定
restore <skill>	还原已归档的技能
archive <skill>	手动归档技能
prune	手动清理 Curator 通常会自动清理的技能
list-archived	列出已归档的技能（可通过 restore 恢复）

新安装时，第一次计划运行会延迟一个完整的 interval_hours（默认 7 天）— 网关不会在 hermes update 后的第一次触发时立即执行 Curator。使用 hermes curator run --dry-run 提前预览。

参见 Curator 了解行为和配置。

hermes fallback

hermes fallback <subcommand>

管理备用提供商链。当主模型遇到速率限制、过载或连接错误时，备用提供商会按顺序被尝试。

子命令	描述
list（别名：ls）	显示当前备用链（无子命令时的默认行为）
add	选择提供商 + 模型（与 hermes model 相同的选择器）并追加到链末尾
remove（别名：rm）	选择要从链中删除的条目
clear	删除所有备用条目

参见备用提供商。

hermes hooks

hermes hooks <subcommand>

检查 ~/.hermes/config.yaml 中声明的 Shell 脚本钩子，针对合成负载测试它们，并管理 ~/.hermes/shell-hooks-allowlist.json 中的首次使用同意白名单。

子命令	描述
list（别名：ls）	列出已配置的钩子，包括匹配器、超时和同意状态
test <event>	针对合成负载触发所有匹配 <event> 的钩子
revoke（别名：remove、rm）	删除命令的白名单条目（下次重启后生效）
doctor	检查每个已配置的钩子：执行位、白名单、mtime 漂移、JSON 有效性和合成运行计时

参见钩子了解事件签名和负载格式。

hermes memory

hermes memory <subcommand>

设置和管理外部记忆提供商插件。可用提供商：honcho、openviking、mem0、hindsight、holographic、retaindb、byterover、supermemory。一次只能激活一个外部提供商。内置记忆（MEMORY.md/USER.md）始终处于激活状态。

子命令：

子命令	描述
setup	交互式提供商选择和配置。
status	显示当前记忆提供商配置。
off	禁用外部提供商（仅使用内置）。

提供商特定子命令

当外部记忆提供商激活时，它可能会注册自己的顶层 hermes <provider> 命令用于特定于提供商的管理（例如，Honcho 激活时的 hermes honcho）。未激活的提供商不暴露其子命令。运行 hermes --help 查看当前已连接的命令。

hermes acp

hermes acp

将 Hermes 作为 ACP（Agent Client Protocol）stdio 服务器启动，用于编辑器集成。

相关入口点：

hermes-acp
python -m acp_adapter

首先安装支持：

pip install -e '.[acp]'

参见 ACP 编辑器集成和 ACP 内部机制。

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）	从配置中删除 MCP 服务器。
list（别名：ls）	列出已配置的 MCP 服务器。
test <name>	测试与 MCP 服务器的连接。
configure <name>（别名：config）	切换服务器的工具选择。
login <name>	强制重新认证基于 OAuth 的 MCP 服务器。

参见 MCP 配置参考、与 Hermes 配合使用 MCP 和 MCP 服务器模式。

hermes plugins

hermes plugins [subcommand]

统一插件管理 — 通用插件、记忆提供商和上下文引擎集于一处。不带子命令运行 hermes plugins 会打开包含两个部分的复合交互界面：

• 通用插件 — 多选复选框，用于启用/禁用已安装的插件
• 提供商插件 — 记忆提供商和上下文引擎的单选配置。在类别上按 ENTER 打开单选框。

子命令	描述
（无）	复合交互界面 — 通用插件切换 + 提供商插件配置。
install <identifier> [--force]	从 Git URL 或 owner/repo 安装插件。
update <name>	拉取已安装插件的最新变更。
remove <name>（别名：rm、uninstall）	删除已安装的插件。
enable <name>	启用已禁用的插件。
disable <name>	禁用插件而不删除。
list（别名：ls）	列出已安装的插件及其启用/禁用状态。

提供商插件选择保存到 config.yaml：

• memory.provider — 活跃的记忆提供商（空 = 仅使用内置）
• context.engine — 活跃的上下文引擎（"compressor" = 内置默认）

通用插件禁用列表存储在 config.yaml 的 plugins.disabled 下。

参见插件和构建 Hermes 插件。

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 工具集使用的 cua-driver 二进制文件的稳定入口点。它运行与首次启用 Computer Use 时 hermes tools 调用的相同上游安装程序，因此如果工具集切换未触发安装（例如，在老用户设置上），可以安全地用于重新运行安装。

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>	处理技能名称冲突：skip（默认）、overwrite 或 rename。
--yes	跳过确认提示。

迁移内容

迁移涵盖 30+ 个类别，包括角色设定、记忆、技能、模型提供商、消息平台、Agent 行为、会话策略、MCP 服务器、TTS 等。项目要么直接导入到 Hermes 等价项，要么归档以供手动审查。

直接导入： SOUL.md、MEMORY.md、USER.md、AGENTS.md、技能（4 个来源目录）、默认模型、自定义提供商、MCP 服务器、消息平台 token 和白名单（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、Agent 默认值（推理努力、压缩、人类延迟、时区、沙箱）、会话重置策略、审批规则、TTS 配置、浏览器设置、工具设置、执行超时、命令白名单、网关配置以及来自 3 个来源的 API 密钥。

归档供手动审查： 定时任务、插件、钩子/Webhook、记忆后端（QMD）、技能注册表配置、UI/身份、日志、多 Agent 设置、频道绑定、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。

API 密钥解析按优先级检查三个来源：配置值 → ~/.openclaw/.env → auth-profiles.json。所有 token 字段均处理纯字符串、环境变量模板（${VAR}）和 SecretRef 对象。

完整的配置键映射、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 密钥和监控会话。需要 pip install hermes-agent[web]（FastAPI + Uvicorn）。完整文档参见 Web 仪表盘。

选项	默认值	描述
--port	9119	Web 服务器运行端口
--host	127.0.0.1	绑定地址
--no-open	—	不自动打开浏览器

# 默认 — 打开浏览器到 http://127.0.0.1:9119
hermes dashboard

# 自定义端口，不打开浏览器
hermes dashboard --port 8080 --no-open

hermes profile

hermes profile <subcommand>

管理配置文件 — 多个独立的 Hermes 实例，每个都有自己的配置、会话、技能和主目录。

子命令	描述
list	列出所有配置文件。
use <name>	设置固定默认配置文件。
create <name> [--clone] [--clone-all] [--clone-from <source>] [--no-alias]	创建新配置文件。--clone 从活跃配置文件复制 config、.env 和 SOUL.md。--clone-all 复制所有状态。--clone-from 指定来源配置文件。
delete <name> [-y]	删除配置文件。
show <name>	显示配置文件详情（主目录、配置等）。
alias <name> [--remove] [--name NAME]	管理快速访问配置文件的包装脚本。
rename <old> <new>	重命名配置文件。
export <name> [-o FILE]	将配置文件导出为 .tar.gz 归档（本地备份）。
import <archive> [--name NAME]	从 .tar.gz 归档导入配置文件（本地恢复）。
install <source> [--name N] [--alias] [--force] [-y]	从 git URL 或本地目录安装配置文件分发。
update <name> [--force-config] [-y]	重新拉取分发；保留用户数据（记忆、会话、认证）。
info <name>	显示配置文件的分发清单（版本、要求、来源）。

示例：

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 配置文件中加载输出，即可获得 Hermes 命令、子命令和配置文件名称的 Tab 补全。

示例：

# Bash
hermes completion bash >> ~/.bashrc

# Zsh
hermes completion zsh >> ~/.zshrc

# Fish
hermes completion fish > ~/.config/fish/completions/hermes.fish

hermes update

hermes update [--check] [--backup] [--restart-gateway]

拉取最新的 hermes-agent 代码并在 venv 中重新安装依赖，然后重新运行安装后钩子（MCP 服务器、技能同步、补全安装）。可以在运行的安装上安全执行。

选项	描述
--check	并排打印当前 commit 和最新 origin/main commit，同步时退出 0，落后时退出 1。不拉取、不安装、不重启任何内容。
--backup	在拉取前创建 HERMES_HOME 的带标签预更新快照（配置、认证、会话、技能、配对数据）。默认关闭 — 以前的始终备份行为在大型主目录上会增加几分钟更新时间。通过在 config.yaml 中设置 update.backup: true 永久开启。
--restart-gateway	成功更新后重启运行中的网关服务。如果安装了多个配置文件，隐含 --all 语义。

附加行为：

• 配对数据快照。 即使 --backup 关闭，hermes update 也会在 git pull 前对 ~/.hermes/pairing/ 和飞书评论规则进行轻量快照。如果拉取重写了正在编辑的文件，可以用 hermes backup restore --state pre-update 回滚。
• 旧版 hermes.service 警告。 如果 Hermes 检测到预重命名的 hermes.service systemd 单元（而非当前的 hermes-gateway.service），会打印一次性迁移提示，帮助避免循环重启问题。
• 退出码。 0 表示成功，1 表示拉取/安装/安装后错误，2 表示阻止 git pull 的工作树意外变更。

维护命令

命令	描述
hermes version	打印版本信息。
hermes update	拉取最新变更并重新安装依赖。
hermes uninstall [--full] [--yes]	删除 Hermes，可选择删除所有配置/数据。

另请参阅

• 斜杠命令参考
• CLI 界面
• 会话
• 技能系统
• 皮肤与主题