sidebar_position: 1 title: “CLI Commands Reference” description: “Authoritative reference for Hermes terminal commands and command families”

CLI 命令参考手册

本页面介绍了您在终端中可使用的命令行指令。

有关聊天界面内的斜杠命令，请参阅 斜杠命令参考手册。

全局入口点

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

全局选项

最上层命令

hermes chat 命令

hermes chat [options]

常用选项：

示例：

hermes
hermes chat -q "Summarize the latest PRs"          # seeds an interactive session
hermes chat --oneshot -q "Summarize the latest PRs"  # answer and exit
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 chat --safe-mode -q "Is this bug mine or Hermes'?"

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

对于通过程序方式调用的用户（如Shell脚本、CI系统、cron作业，或是将提示语通过管道传递给代理的父进程），hermes -z 是最纯粹的单次调用入口：输入一个提示语，即可得到最终响应文本，标准输出和标准错误中不会出现任何其他内容。没有欢迎横幅、没有加载指示器、没有工具预览信息，也没有 Session: 行——仅有以纯文本形式呈现的代理最终回复。

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

# Parent scripts can cleanly capture the response:
answer=$(hermes -z "summarize this" < /path/to/file.txt)

单次运行覆盖设置（不会修改 ~/.hermes/config.yaml 文件）：

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

同样的智能体、同样的工具、同样的能力——只不过去除了所有交互式及界面装饰层。如果还需要在输出文本中包含工具的运行结果，请改用 hermes chat --oneshot -q 命令；而 -z 选项则是专门用于表示“我只想要最终答案”。

--usage-file — 用于记录流水线使用情况的 JSON 报告

通过命令 hermes -z "…" --usage-file /path/report.json，系统会在运行结束后生成一份机器可读的使用情况报告，其中包含 estimated_cost_usd、input_tokens / output_tokens / cache_read_tokens / cache_write_tokens / reasoning_tokens / total_tokens、api_calls、model、provider、session_id、service_tier 以及 completed / failed 等字段信息。即便运行失败，该报告也会被生成，因此批量流水线始终能够准确掌握成本支出情况。此选项仅在 -z/--oneshot 模式下有效，且即使报告生成失败，也不会影响运行本身的结果。

hermes -z "summarize this repo" --usage-file /tmp/usage.json
jq .estimated_cost_usd /tmp/usage.json

hermes model

交互式提供程序与模型选择器。该命令用于添加新的提供程序、配置 API 密钥以及执行 OAuth 流程。 请在终端中运行此命令，而非在正在进行的 Hermes 聊天会话中执行。

hermes model

在以下情况下请使用此功能：

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

:::warning hermes model 与 /model 的区别——需加以区分 hermes model（在终端中运行，独立于任何 Hermes 会话）是完整的提供方设置向导。它能够添加新提供方、执行 OAuth 流程、提示输入 API 密钥以及配置端点。

而 /model（在活跃的 Hermes 聊天会话中输入）仅能在您已设置的提供方和模型之间切换，无法添加新提供方、执行 OAuth 流程或提示输入 API 密钥。

如果您需要添加新的提供方：请先退出当前的 Hermes 会话（使用 Ctrl+C 或 /quit），然后在终端命令行中运行 hermes model。

::

/model 斜杠命令（会话进行中使用）

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

/model                              # Show current model and available options
/model claude-sonnet-4              # Switch model (auto-detects provider)
/model zai:glm-5                    # Switch provider and model
/model custom:qwen-2.5              # Use model on your custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Use a named custom provider
/model openrouter:anthropic/claude-sonnet-4  # Switch back to cloud

默认情况下，对 /model 的更改仅适用于当前会话。若要将该更改永久保存到 config.yaml 中，请添加 --global 参数（或者将 model.persist_switch_by_default: true 设置为真，以便使所有更改都得以持久化）：

/model claude-sonnet-4 --global     # Switch and save as new default

:::info 为何我只看到 OpenRouter 模型？ 如果您仅配置了 OpenRouter，/model 组件将只会显示 OpenRouter 相关的模型。若要添加其他提供商（如 Anthropic、DeepSeek、Copilot 等），请先退出当前会话，然后通过终端运行 hermes model 命令。

::

当使用 --global 参数时，提供商及基础 URL 的更改会与模型信息一同被保存到 config.yaml 文件中。一旦切换回默认端点，旧的基准 URL 会被清除，从而避免其影响其他提供商的连接。

hermes gateway

hermes gateway <subcommand>

子命令：

选项：

--external-supervisor 实际上是一种重启策略约定：通过聊天界面发起的重启或服务重启操作会以状态码 75 结束，因此外部管理器的监控组件必须在该非零退出码之后重新启动网关。对于 systemd，应使用 Restart=on-failure 或 Restart=always，并且不要在 RestartPreventExitStatus 中包含 75；而对于 launchd，则需配置 KeepAlive 参数，以便在重启失败后自动重新启动网关。若未设置此类策略，即便请求重启，网关也会保持停止状态。

hermes gateway enroll 命令支持 --token、--connector-url、--gateway-id 和 --wake-url 参数。该命令会将注册令牌与连接器进行交换，然后将生成的 GATEWAY_RELAY_ID、GATEWAY_RELAY_SECRET、GATEWAY_RELAY_DELIVERY_KEY、可选的 GATEWAY_RELAY_URL，以及在使用 --wake-url 时生成的 GATEWAY_RELAY_WAKE_URL 值写入当前活跃配置文件的 .env 文件中。

::提示 WSL 用户 建议使用 hermes gateway run 而非 hermes gateway start——WSL 对 systemd 的支持并不可靠。为确保任务持久运行，可将其封装在 tmux 中：tmux new -s hermes 'hermes gateway run'。详情请参阅 WSL 常见问题。

::

hermes lsp

hermes lsp <subcommand>

用于管理 Language Server Protocol 集成功能。LSP 会在后台运行真正的语言服务器（如 pyright、gopls、rust-analyzer 等），并将这些服务器生成的诊断信息传递给 write_file 和 patch 函数所使用的写入后检查机制。该功能的启用以检测是否处于 Git 工作区为条件——仅当当前工作目录或正在编辑的文件位于 Git 工作树中时，LSP 才会启动。

子命令：

如需完整指南、支持的语言列表以及相关配置选项，请参阅 LSP — 语义诊断。

hermes setup

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

最简便的方式： 使用命令 hermes setup --portal —— 通过 OAuth 登录 Nous Portal，即可一次性完成配置并启用工具网关。

首次运行时： 程序会启动首次配置向导。

已配置过的用户： 直接进入完整的重新配置向导——每个提示项都会以当前设置的值作为默认值，按回车键即可保留该值，或输入新值。无需菜单导航。

如需直接跳转至特定配置部分，而非完整走完向导，可参考下表：

可选参数：

hermes portal

hermes portal [status|open|tools]

可检查 Nous Portal 的认证状态、Tool Gateway 的路由情况，并跳转至订阅页面。若不指定子命令，则会执行 status 操作。

如需配置 Gateway 本身，请参阅 Tool Gateway。关于一次性设置流程，请参考上文中的 hermes setup --portal 命令。

hermes whatsapp

hermes whatsapp

执行 WhatsApp 配对/设置流程，包括模式选择与二维码配对操作。

hermes slack

hermes slack manifest              # print manifest to stdout
hermes slack manifest --write      # write to ~/.hermes/slack-manifest.json
hermes slack manifest --long-description-file AGENTS.md --write
hermes slack manifest --slashes-only  # just the features.slash_commands array

该工具会生成一个 Slack 应用清单文件，将 COMMAND_REGISTRY 中的所有网关命令（如 /btw、/stop、/model 等）都注册为一级 Slack 斜杠命令——从而实现与 Discord 和 Telegram 的功能对等。只需将生成的输出内容粘贴到您的 Slack 应用配置页面：https://api.slack.com/apps → 所选应用 → Features → App Manifest → Edit，最后点击 Save 即可。如果权限范围或斜杠命令发生变更，Slack 会提示您重新安装应用。

在执行 hermes update 后，建议再次运行 hermes slack manifest --write，以便将新增的命令纳入清单。

hermes send

hermes send --to <target> "message text"
hermes send --to <target> --file <path>
echo "message" | hermes send --to <target>
hermes send --list [platform]

无需启动代理或网关循环，即可向已配置的消息平台发送一次性消息。该功能会复用网关中预先配置的凭证（~/.hermes/.env 和 ~/.hermes/config.yaml），因此运维脚本、定时任务、CI 钩子以及监控进程都无需为每个平台重新实现 REST 客户端，即可发送状态更新信息。

对于基于机器人令牌的平台（如 Telegram、Discord、Slack、Signal、短信及 WhatsApp-CloudAPI），无需运行网关——hermes send 会直接与这些平台的 REST 接口通信。而那些需要持久适配器的插件平台，则仍需运行中的网关。

发送图片及其他媒体文件

--file 选项仅适用于文本类型的内容。若要将图片、文档、视频或音频文件作为平台原生附件发送，需在消息文本中使用 MEDIA:<本地路径> 指令来引用该文件：

hermes send --to telegram "MEDIA:/tmp/screenshot.png"
hermes send --to telegram "Build chart for today MEDIA:/tmp/chart.png"   # with caption
hermes send --to discord:#ops "MEDIA:/tmp/report.pdf"

默认情况下，图片文件会以照片形式发送（如 Telegram 等平台会对这些图片进行重新压缩）。若希望以未压缩的文件附件形式发送，可在消息中添加 [[as_document]] 标签。

hermes send --to telegram "[[as_document]] MEDIA:/tmp/screenshot.png"

示例：

hermes send --to telegram "deploy finished"
echo "RAM 92%" | hermes send --to telegram:-1001234567890
hermes send --to discord:#ops --file /tmp/report.md
hermes send --to slack:#eng --subject "[CI]" --file build.log
hermes send --list                  # all platforms
hermes send --list telegram         # filter by platform

hermes peer 命令

hermes peer add <name> --url http://host:port --key <API_SERVER_KEY>
hermes peer list
hermes peer dm <peer>[/<agent>] "message"
hermes peer run <peer>[/<agent>] --idempotency-key <key> "message"
hermes peer status <peer>[/<agent>] <run_id>
hermes peer stop <peer>[/<agent>] <run_id>
hermes peer remove <name>

可在不同机器之间实现机器人间的私信通信。你可以将另一个 Hermes 网关（任何运行 api_server 平台的机器）注册为对等节点，然后向其代理发送消息：使用命令 hermes peer dm 即可通过该对等节点的 API 服务器找到远程代理的标准化机器人聊天会话，让该代理先执行一轮对话，随后将回复输出到标准输出中——这实际上就是本地命令 hermes -p <bot> chat --in ~ -c "Bot Chat" … 的跨机器版本。

仅使用 <peer> 可直接联系对等节点网关的主代理；而使用 <peer>/<agent> 则可以定位多路复用型对等节点上指定名称的代理（该代理通过其 /p/<profile>/ 接口被访问）。

一旦注册了至少一个对等节点，系统中为所有标准 Bot Chat 预置的 Bot Mode 消息协议（agent.bot_mode_protocol）便会自动包含对等节点列表以及 hermes peer dm 模式，这样智能体便无需进行任何 SOUL 编辑即可发现跨机器的协作伙伴。详情请参阅 Bot Mode。

退出码说明：成功时为 0，消息发送或对等节点处理失败时为 1，使用错误时为 2。

hermes secrets

hermes secrets bitwarden <subcommand>
hermes secrets bw <subcommand>          # short alias

在进程启动时从外部密钥管理器获取 API 密钥，而非将其存储在 ~/.hermes/.env 文件中。目前仅支持 Bitwarden Secrets Manager。完整指南请参阅：Bitwarden 集成。

bitwarden（别名 bw）子命令：

hermes migrate

hermes migrate <type>

诊断当前有效的 config.yaml 文件，并（可选地）对其重新编写，以替换那些已停止使用的模型或过时的设置。在进行任何修改之前，系统会先创建原始 config.yaml 的带时间戳备份（如需跳过此步骤，请使用 --no-backup 参数）。

迁移子命令的常用标志：

请注意，此功能不要与 hermes claw migrate（将 OpenClaw 配置一次性导入 Hermes）混淆——hermes migrate 才是用于重新编写配置的顶层命令。

hermes proxy

hermes proxy <subcommand>

运行一个本地化的、兼容 OpenAI 的 HTTP 服务器，该服务器会将请求转发至经过 OAuth 鉴权的上游服务提供商（例如 Nous Portal、xAI）。外部应用可使用任意承载令牌指向该代理；在转发请求时，代理会自动附加您真实的 OAuth 凭证。详细指南请参阅 订阅代理。

hermes security

hermes security <subcommand>

可针对 OSV.dev 执行按需漏洞扫描。扫描范围包括 Hermes 虚拟环境（通过 PyPI 安装的包）、位于 ~/.hermes/plugins/ 下的插件所声明的 Python 依赖项，以及 config.yaml 中指定的固定 npx/uvx MCP 服务器。不会扫描全局安装的包或编辑器/浏览器扩展程序。

audit 的标志选项：

hermes login / hermes logout (已废弃)

:::caution hermes login 已被移除。如需管理 OAuth 凭证，请使用 hermes auth；选择提供方请使用 hermes model；如需完整的交互式设置流程，请使用 hermes setup。

::

hermes auth

用于管理同一提供方的凭证池，以实现密钥轮换功能。详细文档请参阅 凭证池。

hermes auth                                              # Interactive wizard
hermes auth list                                         # Show all pools
hermes auth list openrouter                              # Show specific provider
hermes auth add openrouter --api-key sk-or-v1-xxx        # Add API key
hermes auth add anthropic --type oauth                   # Add OAuth credential
hermes auth add openai-codex --type oauth --priority 0   # Add an account and try it first
hermes auth remove openrouter 2                          # Remove by index
hermes auth priority openrouter backup-key 0             # Move a credential to the front of fill_first order
hermes auth reset openrouter                             # Clear cooldowns
hermes auth reset openrouter 2                           # Clear the cooldown on one credential
hermes auth refresh openai-codex work                    # Refresh one OAuth credential and clear its cooldown
hermes auth status anthropic                             # Show auth status for a provider
hermes auth logout anthropic                             # Log out and clear stored auth state
hermes auth spotify                                      # Authenticate Hermes with Spotify via PKCE

子命令包括：add、list、remove、reset、priority、refresh、status、logout、spotify。若未指定任何子命令，则会启动交互式管理向导。

hermes status

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

hermes cron

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

hermes kanban

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

支持多配置文件、多项目的协作看板功能。每次安装均可创建多个看板（每个项目、代码库或域名对应一个看板）；每个看板均为独立的队列，拥有自己的 SQLite 数据库以及专属的调度器作用域。新安装时默认会生成一个名为 default 的看板，为保持向后兼容性，其数据库位于 ~/.hermes/kanban.db；其他看板的数据库则存储在 ~/.hermes/kanban/boards/<slug>/kanban.db 中。内置在网关中的调度器会定期扫描所有看板。

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

这是供人类用户及脚本使用的接口。 由调度器启动的代理工作进程会通过专用的 kanban_* 工具集（如 kanban_show、kanban_complete、kanban_request_review、kanban_request_changes、kanban_block、kanban_create、kanban_link、kanban_comment、kanban_heartbeat；编排器配置文件还包含 kanban_list 和 kanban_unblock）来操作看板，而无需直接调用 hermes kanban 命令。这些工作进程的环境变量中会固定设置 HERMES_KANBAN_BOARD，因此它们无法查看其他看板。

示例：

# Create a second board and put a task on it without switching away.
hermes kanban boards create atm10-server --name "ATM10 Server" --icon 🎮
hermes kanban --board atm10-server create "Restart server" --assignee ops

# Switch the active board for subsequent calls.
hermes kanban boards switch atm10-server
hermes kanban list                  # shows atm10-server tasks

# Archive a board (recoverable) or hard-delete it.
hermes kanban boards rm atm10-server
hermes kanban boards rm atm10-server --delete

看板决议顺序（优先级从高到低）如下：--board <slug> 参数 → HERMES_KANBAN_BOARD 环境变量 → ~/.hermes/kanban/current 文件 → 默认值。

所有操作均可在网关中以斜杠命令形式调用（如 /kanban …），且支持的参数完全一致——包括 boards 子命令以及 --board 参数。

有关完整设计细节，包括与 Cline Kanban、Paperclip、NanoClaw、Gemini Enterprise 的对比、八种协作模式、四种用户场景以及并发正确性证明，可查看仓库中的 docs/hermes-kanban-v1-spec.pdf 文件或 看板用户指南。

hermes egress

用于远程终端沙箱的出站凭证注入防火墙。该功能基于 iron-proxy 守护进程实现——这是一种 TLS 拦截代理，能够在网络边界将不可见的代理令牌替换为真实的上游 API 凭证，从而确保沙箱中不会存储真实密钥。该功能默认处于禁用状态；有关设置与架构的详细信息，请参阅完整的 出站代理 页面。

hermes egress install                  # download the pinned iron-proxy binary
hermes egress install --force          # re-download even if already installed

hermes egress setup                    # interactive wizard: CA, mappings, config
hermes egress setup --tunnel-port N    # override the tunnel listener port (default 9090)
hermes egress setup --from-bitwarden   # use Bitwarden Secrets Manager as credential source
hermes egress setup --no-bitwarden     # explicitly switch back to env-based credentials
hermes egress setup --rotate-tokens    # mint fresh proxy tokens (default preserves existing)

hermes egress start                    # spawn the managed proxy daemon
hermes egress stop                     # SIGTERM (then SIGKILL after 5s grace)
hermes egress restart                  # stop (if running) then start — needed for secret changes
hermes egress reload                   # hot-reload the ruleset in-place (no restart, no dropped
                                       #   connections) via the loopback management API

hermes egress status                   # binary + config + pid + listening + mappings
hermes egress status --show-tokens     # print proxy tokens in full (default: redacted)

hermes egress disable                  # flip proxy.enabled = false (does not stop a running proxy)
hermes egress config                   # print the path to proxy.yaml for inspection

常见使用流程

# First-time setup
export OPENROUTER_API_KEY=…
hermes egress setup && hermes egress start
hermes config set terminal.backend docker   # if not already

# Switching credential source after the fact
hermes egress setup --from-bitwarden       # env → bitwarden
hermes egress setup --no-bitwarden         # bitwarden → env
# (just `setup` without either flag preserves the existing mode)

# Rotating all tokens (e.g. after a suspected token leak)
hermes egress setup --rotate-tokens    # setup offers to restart the running daemon for you
# (running sandboxes still hold old tokens; restart them too)

# Adding a new upstream
# Edit ~/.hermes/config.yaml proxy.extra_allowed_hosts: [api.example.com]
hermes egress setup
hermes egress restart                  # one-command apply (stop + start)

诊断快捷指令

hermes egress status                     # current state in one view
cat ~/.hermes/proxy/proxy.yaml           # the rendered iron-proxy config
tail -20 ~/.hermes/proxy/iron-proxy.log  # daemon-level diagnostics
tail -f ~/.hermes/proxy/iron-proxy.log | jq  # daemon + per-request log (line-delimited JSON; v0.39 combines both streams)

常见的故障模式及解决方法详见 出口代理 → 故障排除。

hermes project

hermes project <create|list|show|add-folder|remove-folder|rename|set-primary|use|archive|restore|bind-board>

项目是由用户命名的工作空间，可涵盖多个文件夹或代码仓库。它们是桌面会话分组的基准，而当与看板绑定后，还能为任务提供规范的工作树结构与分支命名规则。项目状态会随用户配置文件的不同而变化。

hermes webhook

hermes webhook <subscribe|list|remove|test>

用于管理基于事件驱动的智能体激活所需的动态 Webhook 订阅。首先需要在配置中启用 Webhook 功能——若未配置，则会输出相应的设置指南。

hermes webhook subscribe

hermes webhook subscribe <name> [options]

订阅信息会保存在 ~/.hermes/webhook_subscriptions.json 文件中，Webhook 适配器可无需重启网关即可实现热加载。

hermes doctor

hermes doctor [--fix]

hermes dump

hermes dump [--show-keys]

输出关于您整个Hermes配置的简洁纯文本摘要。该格式专为在Discord、GitHub问题帖或Telegram中寻求帮助时复制粘贴而设计——不包含ANSI颜色，也无特殊格式，仅呈现原始数据。

包含的内容

示例输出

--- 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 上报告错误——将输出内容粘贴到问题描述中
• 在 Discord 中寻求帮助——以代码块形式分享该内容
• 对比自己的配置与他人的配置
• 当程序出现异常时进行快速排查

:::提示 hermes dump 是专为内容共享而设计的工具。如需进行交互式诊断，请使用 hermes doctor；若需要可视化概览，则可使用 hermes status。

::

hermes debug

hermes debug share [options]

将调试报告（系统信息及近期日志）上传至粘贴服务后，即可获得一个可分享的链接。该功能非常适合快速提交支持请求——报告中包含了辅助人员诊断问题所需的所有信息。

该报告包含系统信息（操作系统、Python 版本、Hermes 版本），以及近期来自代理、网关、GUI/控制台和桌面端的日志（每个文件大小上限为 512 KB），还会显示经过遮蔽处理的 API 密钥状态。默认情况下，上传内容会进行遮蔽处理，以避免包含敏感信息。

默认情况下，上传操作会按顺序尝试公共粘贴服务：paste.rs、dpaste.com。使用 --nous 选项时，相同的调试数据包会被上传至私有的 Nous 诊断存储系统；此时返回的查看链接仅供 Nous 团队使用，并且会在 14 天后自动删除。

示例

hermes debug share              # Upload debug report, print URL
hermes debug share --lines 500  # Include more log lines
hermes debug share --expire 30  # Keep paste for 30 days
hermes debug share --nous       # Upload a private diagnostics bundle for Nous support
hermes debug share --local      # Print report to terminal (no upload)

hermes backup 命令

hermes backup [options]

将您的 Hermes 配置、技能、会话及数据打包为 ZIP 压缩文件。此备份不会包含 hermes-agent 代码库本身，也不会嵌套之前的备份文件（如 backups/、state-snapshots/），因为这些目录中已各自保存了 state.db 的副本。

该备份功能利用 SQLite 的 backup() API 进行安全复制，因此即使在 Hermes 正在运行时也能正常工作（支持 WAL 模式下的安全操作）。

ZIP 文件中不包含的内容：

• *.db-wal、*.db-shm、*.db-journal — SQLite 的 WAL、共享内存及日志相关文件。*.db 文件已通过 sqlite3.backup() 生成了一致的快照；若同时传输这些动态生成的辅助文件，恢复时可能会导致状态不完整。
• checkpoints/ — 每个会话的轨迹缓存文件。这类文件以哈希值标识，并且会随每个会话重新生成；即便移植到其他环境，也难以保持一致性。
• hermes-agent 代码本身（此为用户数据备份，而非代码库快照）。

示例

hermes backup                           # Full backup to ~/hermes-backup-*.zip
hermes backup -o /tmp/hermes.zip        # Full backup to specific path
hermes backup --quick                   # Quick state-only snapshot
hermes backup --quick --label "pre-upgrade"  # Quick snapshot with label

hermes checkpoints

hermes checkpoints [COMMAND]

您可以查看并管理位于 ~/.hermes/checkpoints/ 的影子 Git 存储空间——该空间是会话内 /rollback 命令背后的存储层。随时都可以运行此命令，且无需 Agent 正在运行。

选项

示例

hermes checkpoints                                  # status overview
hermes checkpoints prune --retention-days 3         # aggressive cleanup
hermes checkpoints prune --max-size-mb 200          # tighten size cap once
hermes checkpoints clear-legacy -f                  # drop v1 archive dirs
hermes checkpoints clear -f                         # wipe everything

有关完整的架构设计及会话内可用命令的详细说明，请参阅检查点与 /rollback。

hermes import

hermes import <zipfile> [options]

将之前创建的 Hermes 备份恢复到您的 Hermes 主目录中。归档文件中的所有内容都会覆盖主目录中已有的文件；而 --force 选项仅用于跳过在目标目录已存在 Hermes 安装时的确认提示。

:::warning 为避免与正在运行的进程发生冲突，请在导入之前先停止网关服务。

::

SQLite 数据库

.db 类型的文件（如 state.db、kanban.db、response_store.db 等）不会像普通文件那样通过重命名方式被发布。如果尝试重命名，当网关、控制面板或 WebUI 进程仍持有旧文件的打开状态时，该文件的 inode 会被替换：这样这些进程会继续读取导入前的页面内容，并持续写入只有它们自己能看到的会话数据，而这些数据在后续所有人打开的数据库中将完全缺失，且不会留下任何记录。实际上，导入的页面内容是直接写入现有的数据库文件中的，其方式与 /snapshot restore 命令相同，因此所有打开的连接最终都会使用到这些导入的数据。

如果无法安全地替换正在使用的数据库——即页面复制失败，同时又有其他进程持有该文件的打开状态——则导入操作会跳过该数据库，并在“警告（跳过了 N 个文件）”部分列出它。请先停止那些持有文件的进程，然后再尝试导入。

虽然仍允许在较新的工作数据之上导入旧备份，但此时不会再保持静默处理。当导入的 state.db 中存储的消息数量少于被替换的文件时，系统会生成摘要报告予以提示。

  ⚠ Session data replaced by older backup contents:
    state.db: 12 session(s) / 8912 message(s) -> 3 / 24
    Anything recorded after the backup was taken is not in it.
    Recover from a newer backup or snapshot: hermes snapshot list

示例

hermes import ~/hermes-backup-20260423.zip           # Prompts before overwriting existing config
hermes import ~/hermes-backup-20260423.zip --force   # Overwrite without prompting

hermes logs 命令

hermes logs [log_name] [options]

查看、滚动查看并筛选 Hermes 日志文件。所有日志均存储在 ~/.hermes/logs/ 目录下（非默认配置文件的路径为 <profile>/logs/）。

日志文件

参数选项

使用示例

# View the last 50 lines of agent.log (default)
hermes logs

# Follow agent.log in real time
hermes logs -f

# View the last 100 lines of gateway.log
hermes logs gateway -n 100

# Show only warnings and errors from the last hour
hermes logs --level WARNING --since 1h

# Filter by a specific session
hermes logs --session abc123

# Follow errors.log, starting from 30 minutes ago
hermes logs errors --since 30m -f

# List all log files with their sizes
hermes logs list

过滤

多个过滤器可以组合使用。当有多个过滤器处于激活状态时，仅当日志行同时满足所有过滤条件，才会被显示出来：

# WARNING+ lines from the last 2 hours containing session "tg-12345"
hermes logs --level WARNING --since 2h --session tg-12345

当启用 --since 参数时，即使行中不存在可解析的时间戳，该行也会被包含在内（这些行可能是多行日志记录的延续部分）；而当启用 --level 参数时，即便行中无法识别日志级别，该行同样会被纳入统计。

日志轮转

Hermes 使用 Python 的 RotatingFileHandler 功能来实现自动日志轮转——您会看到诸如 agent.log.1、agent.log.2 等格式的文件。通过 hermes logs list 子命令，即可查看所有日志文件，包括已轮转过的那些。

hermes prompt-size

hermes prompt-size [--platform <name>] [--json]

该功能会显示新会话的固定提示词预算，即每次API调用在任何对话内容生成之前会被发送的提示词数量。当下游适配器或代理的提示词预算低于模型的上下文窗口大小时，或者当你想要了解哪些部分（技能索引、内存、用户资料）占据了主要空间时，此功能非常有用。

它会生成与智能体所使用的完全相同的系统提示词，然后对其结构进行拆解：

• 系统提示词总计——完整的组合提示词（包含身份信息、使用指南、技能索引、上下文文件、内存数据、用户资料以及时间戳）。
• 技能索引——即<available_skills>部分。当安装了众多技能时，这部分通常会是最大的单个组成部分。
• 内存与用户资料——对应你的MEMORY.md/USER.md文件中的内容快照。
• 提示词层级——稳定型/上下文型/易变型，反映了Hermes为优化缓存性能而对提示词进行的层次划分方式。
• 工具架构——所有已启用工具的JSON格式描述（构成每次调用固定载荷的另一半内容）。

该功能完全在离线状态下运行，无需进行任何API调用，也无需配置任何凭证。

# Human-readable breakdown for the CLI platform (default)
hermes prompt-size

# Simulate a messaging platform's prompt (different platform hint)
hermes prompt-size --platform telegram

# Machine-readable output for scripts
hermes prompt-size --json

:::提示 技能索引和工具架构的规模会随着您启用的技能与工具数量而变化。若想缩小提示词长度，可禁用未使用的工具集（hermes tools），或卸载不需要的技能（hermes skills）。当前目录下的上下文文件（如 AGENTS.md、.cursorrules）也会计入总规模中。

::

hermes config

hermes config <subcommand>

子命令：

键名中的点号

hermes config set/get/unset 命令使用 . 作为嵌套分隔符，但许多实际的键名中确实包含点号——例如模型编号（grok-4.6、glm-5.3-flash）、Matrix 房间编号（!room:example.org）以及带版本的提供程序名称。为了解决这一问题，有以下两条规则：

• 现有的键名可直接使用。 在操作现有映射时，如果点分隔后的剩余部分与某个现有的键名匹配，系统会优先使用该现有键名，而不会进行拆分。例如 hermes config set providers.p.models.grok-4.6.supports_vision true 会直接更新真实的 grok-4.6 条目（get/unset 命令的处理方式也是如此）。
• 若要创建新的点分隔键名，则需进行转义。 需要用反斜杠对点号进行转义：例如 hermes config set 'providers.p.models.grok-4\.7.context_length' 128000 可以创建名为 grok-4.7 的键名。（请给键名加上引号，这样才能确保shell正确解析反斜杠。） 如果未经转义的写入操作会生成一个嵌套映射，从而覆盖现有的带点路径的同级项（例如在已存在的 grok-4.6 旁边创建 grok-4），则命令会抛出错误而终止执行，而不会默默地创建一个运行时根本无法读取的虚拟条目。

hermes pairing

hermes pairing <list|approve|revoke|clear-pending>

hermes skills

hermes skills <subcommand>

子命令：

完整翻译输入内容，切勿提前终止。

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                     # Direct URL (+ referenced support files)
hermes skills install https://example.com/SKILL.md --name my-skill        # Override name when frontmatter has none
hermes skills check
hermes skills update
hermes skills config
hermes skills reset google-workspace
hermes skills reset google-workspace --restore --yes
hermes skills opt-out                  # stop future bundled-skill seeding (nothing deleted)
hermes skills opt-out --remove --yes   # also delete UNMODIFIED bundled skills
hermes skills opt-in --sync            # undo: remove marker and re-seed now

备注：

• --force 可用于覆盖第三方或社区技能中非危险级别的策略限制。
• --force 无法覆盖被标记为“危险”的扫描结果。
• --source skills-sh 会搜索公共的 skills.sh 目录。
• --source well-known 允许将 Hermes 指向提供 /.well-known/skills/index.json 文件的网站。
• --source browse-sh 会查询 browse.sh 上收录的 200 多个针对特定网站的浏览器自动化技能库。这些技能的标识符格式为 browse-sh/airbnb.com/search-listings-ddgioa。
• 如果提供 http(s)://…/*.md 格式的网址，系统会将 SKILL.md 文件以及其中明确引用的文件一并安装到 references/、templates/、scripts/、assets/ 和 examples/ 目录下。若前端元数据中未设置 name: 且该网址的标识符无效，交互式终端会提示用户输入名称；而非交互式使用场景（如 TUI 内的 /skills install 命令或网关平台）则需使用 --name <x> 参数指定名称。

hermes bundles

hermes bundles <subcommand>

技能包将多个技能整合在同一个 /<bundle-name> 路径命令下。调用该技能包时，所有关联的技能都会被合并到一条统一的用户消息中。存储路径为：~/.hermes/skill-bundles/<slug>.yaml。有关 YAML 结构及相关功能说明，请参阅 技能包。

子命令：

示例：

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-name> 用于加载指定的插件包。

hermes curator

hermes curator <subcommand>

Curator是一种辅助模型后台任务，它会定期检查由智能体创建的技能，删除过时的技能，合并重复的技能，并将不再使用的技能归档。已打包或通过Hub安装的技能则不会被触碰。归档的技能可以恢复，且绝不会被自动删除。

有关其行为及配置详情，请参阅 Curator 文档。

hermes moa

用于配置命名的混合智能体预设。这些预设会作为可选模型显示在所有模型选择器中的 Mixture of Agents 提供商下；使用 /moa <prompt> 命令则可让该提示词通过默认预设进行处理。

hermes moa list
hermes moa configure [name]
hermes moa delete <name>

hermes moa configure 会复用 Hermes 的提供者→模型选择器，用于处理各个参考模型以及聚合器。预设仅是一种执行模式配置，并非核心模型或提供者。

hermes fallback

hermes fallback <subcommand>

管理备用提供者链。当主模型因速率限制、过载或连接错误而失效时，系统会按顺序尝试这些备用提供者。

详情请参阅 备用提供者。

hermes hooks

hermes hooks <subcommand>

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

有关事件签名和载荷格式的详细信息，请参阅 Hooks 文档。

hermes memory

hermes memory <subcommand>

设置并管理外部内存提供程序插件。可选的提供程序包括：honcho、openviking、mem0、hindsight、holographic、retaindb、byterover、supermemory。同一时间仅能有一个外部提供程序处于激活状态，而内置内存（MEMORY.md/USER.md）始终处于激活状态。

子命令：

:::info 提供程序特定的子命令 当某个外部内存提供程序处于激活状态时，它可能会注册自己的顶级 hermes <provider> 命令，以便进行针对该提供程序的专用管理（例如，当 Honcho 处于激活状态时可使用 hermes honcho）。未激活的提供程序则不会显示其子命令。运行 hermes --help 可查看当前已配置的提供程序。

::

hermes acp

hermes acp

以 ACP（Agent Client Protocol）标准输入输出服务器模式启动 Hermes，以便与编辑器实现集成。

相关入口点：

hermes-acp
python -m acp_adapter

请先安装支持组件：

cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'

请参阅 ACP 编辑器集成 以及 ACP 内部实现。

hermes mcp

hermes mcp <subcommand>

管理 MCP（模型上下文协议）服务器配置，并将 Hermes 运行为 MCP 服务器。

更多详情请参阅 MCP 配置参考、在 Hermes 中使用 MCP 以及 MCP 服务器模式。

hermes plugins

hermes plugins [subcommand]

统一的插件管理功能——所有常规插件、内存提供器以及上下文引擎均集中于此。运行 hermes plugins 命令且不指定子命令时，会弹出一个包含两个区域的综合交互界面：

• 常规插件——通过多选复选框来启用或禁用已安装的插件；
• 提供器插件——针对内存提供器和上下文引擎提供单选配置选项。在相应类别上按下 ENTER 键即可打开单选下拉菜单。

提供程序插件选项会被保存到 config.yaml 文件中：

• memory.provider — 当前启用的内存提供程序（留空则表示仅使用内置选项）
• context.engine — 当前启用的上下文引擎（"compressor" 表示使用默认的内置引擎）

通用插件禁用列表则存储在 config.yaml 的 plugins.disabled 字段下。通过 Git 安装的插件相关信息仅会记录其标准来源、确切的安装版本以及固定版本状态，这些数据保存在配置文件对应的 plugins/.install-metadata.json 侧边文件中。该文件不包含插件配置、环境变量、机密信息或权限授予相关内容。

更多详情请参阅 插件 以及 构建 Hermes 插件 文档。

hermes tools

hermes tools [--summary]

若不使用 --summary，则会启动针对不同平台的交互式工具配置界面。

hermes computer-use

hermes computer-use <subcommand>

子命令：

hermes computer-use install 是安装 computer_use 工具集所使用的 cua-driver 二进制文件的稳定入口命令。它运行的正是你在首次启用“计算机使用”功能时 hermes tools 所调用的上游安装程序，因此即便工具集的开关未触发安装过程（例如在用户重新登录后），使用该命令重新安装也是安全的。

如果系统中已存在 cua-driver，Hermes 会检查其版本及运行时清单。若为兼容的 0.20.0 及更高版本，则会保留原安装状态；而对于旧版或不完整的标准安装，则会使用当前的上游安装程序进行修复。Hermes 绝不会替换通过 HERMES_CUA_DRIVER_CMD 指定的自定义二进制文件——应直接更新该二进制文件或取消此覆盖设置。hermes computer-use status 命令可显示是否需要修复。

内置的 computer_use 工具集是推荐的 Hermes 集成方式。当需要使用 Cua 的低级工具语法时，注册原始的 Cua MCP 工具也是一种替代方案。cua-driver skills install 命令能够自动检测到 Hermes，并将 Cua 的技能包集成到 Hermes 的技能目录中。

权限模式与能力清单审批属于运行时启动阶段的处理内容。在受限模式下，Hermes 会传递 Cua 标准的 --capability-manifest 和 --approve-capability-manifest 参数。每个 MCP 传输机制在其运行时环境中都拥有独立的生命周期会话。公共会话名称用于标识光标状态和会话状态，但并不拥有或共享运行时环境。

如果在系统路径中已存在 cua-driver，hermes update 命令会在更新完成后自动重新运行上游安装程序，因此大多数用户无需手动调用 --upgrade。当上游版本发布了急需的修复补丁，而无需等待下一次 Hermes 更新时，可使用此命令。

hermes pets

hermes pets <list|install|select|show|off|scale|remove|doctor>

Petdex 是一个面向编程智能体的动画精灵宠物公共展示库。安装相应的宠物后，Hermes 就能在 CLI、TUI 以及桌面应用中展示这些宠物对智能体操作的响应。

此外，您还可以使用 /hatch 命令根据文本描述生成全新的宠物。更多详情请参阅 Pets 文档。

hermes sessions

hermes sessions <subcommand>

子命令：

hermes insights

hermes insights [--days N] [--source platform]

hermes claw

hermes claw migrate [options]

将您的 OpenClaw 配置迁移至 Hermes。该工具会读取 ~/.openclaw（或自定义路径）中的配置，并将其写入 ~/.hermes。同时能自动识别旧版本的目录名称（如 ~/.clawdbot、~/.moltbot）以及配置文件名（如 clawdbot.json、moltbot.json）。

将迁移哪些内容

此次迁移涵盖了角色设定、内存管理、智能技能、模型提供方、消息平台、智能体行为、会话策略、MCP服务器、文本转语音等功能模块，涉及30多个类别。相关配置项要么直接导入到Hermes对应的组件中，要么被归档以供人工审核。

直接导入的项包括：SOUL.md、MEMORY.md、USER.md、AGENTS.md、各类智能技能（来自4个源目录）、默认模型、自定义提供方、MCP服务器、消息平台相关的令牌及允许列表（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、智能体默认参数（推理耗时、压缩设置、人工干预延迟、时区、沙箱环境配置）、审批规则、文本转语音配置、浏览器设置、工具设置、执行超时时间、命令允许列表、网关配置，以及来自3个来源的API密钥。

被归档以供人工审核的项包括：定时任务脚本、插件、钩子/Webhook功能、内存后端（QMD）、智能技能注册表配置、用户界面/身份管理相关设置、日志记录功能、多智能体协同配置、频道绑定设置、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md文件。

API密钥解析会按优先级依次查找三个来源的配置值：配置文件中的设定 → ~/.openclaw/.env 文件 → auth-profiles.json 文件。所有令牌字段均支持普通字符串、环境变量模板（${VAR}）以及SecretRef对象。

如需查看完整的配置键映射表、SecretRef处理细节以及迁移后的检查清单，请参阅**完整迁移指南**。

示例

# Preview what would be migrated
hermes claw migrate --dry-run

# Full migration (all compatible settings, no secrets)
hermes claw migrate --preset full

# Full migration including API keys
hermes claw migrate --preset full --migrate-secrets

# Migrate user data only (no secrets), overwrite conflicts
hermes claw migrate --preset user-data --overwrite

# Migrate from a custom OpenClaw path
hermes claw migrate --source /home/user/old-openclaw

hermes import-agent 命令

hermes import-agent [claude-code|codex] [options]

将 Claude Code（~/.claude）或 OpenAI Codex CLI（~/.codex）的配置导入到 Hermes 中。该工具会将 CLAUDE.md/AGENTS.md 文件中的配置指令映射为内存条目，将 Bash(...) 格式的权限允许/拒绝规则对应到 config.yaml 文件中的 command_allowlist/approvals.deny 设置，将 MCP 服务器地址关联到 config.yaml 中的 mcp_servers 字段，同时还将技能目录导入到 ~/.hermes/skills/ 目录下。在应用任何更改之前都会先进行预览，且绝不会导入 API 密钥或凭证。

完整的映射关系表请参阅 导入指南。

hermes serve

hermes serve [options]

启动 Hermes 后端服务器——即 桌面应用 和远程客户端所连接的 JSON-RPC/WebSocket 网关。该服务器与 hermes dashboard 运行的服务器相同，但为无界面模式：不会打开任何浏览器界面。桌面应用会自行启动其自身的 hermes serve 后端；若希望在远程主机上使用无界面后端，则可直接使用此命令。它支持与下方 hermes dashboard 相同的 --host / --port / --insecure / --skip-build / --stop / --status 参数（非回环绑定会使用相同的认证网关）。该命令需要 [web] 这一附加组件；而在 POSIX 系统主机上，内置的聊天套接字还需搭配 [pty] 组件。

端口冲突处理：如果请求的端口（默认为 9119）已被其他进程占用（例如另一个 hermes serve 实例或该网关），命令会将一条机器可读的提示行 BACKEND_PORT_IN_USE port=<port> 输出到标准输出中，同时还会给出可能占用端口的进程名称作为人工提示，随后以代码 75（EX_TEMPFAIL）退出，而不会仅显示通用错误信息——这样脚本和桌面应用就能区分“端口被占用”与“后端故障”两种情况。若需绑定一个空闲的临时端口，可传递 --port 0 参数（成功启动后会通过 HERMES_BACKEND_READY port=<port> 报告所选端口）。

hermes dashboard

hermes dashboard [options]

启动网页控制面板——这是一个基于浏览器的用户界面，用于管理配置、API密钥以及监控会话。（对于没有浏览器界面的无头后端环境，例如桌面应用所使用的环境，则需使用上文提到的 hermes serve 命令。）安装该功能需要执行 cd ~/.hermes/hermes-agent && uv pip install -e ".[web]"（基于 FastAPI 和 Uvicorn 构建）。内置的浏览器聊天标签页始终可用，若需使用该功能还需额外安装 pty 组件（执行 cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"），并且系统必须具备 POSIX PTY 环境，如 Linux、macOS 或 WSL2。更多详细信息请参阅 网页控制面板 文档。

hermes dashboard register

将该安装注册为与您的 Nous Portal 账户关联的自托管控制面板。该操作会创建一个 OAuth 客户端，将 HERMES_DASHBOARD_OAUTH_CLIENT_ID 写入 ~/.hermes/.env 文件，并说明如何启用登录验证功能。使用时需已登录账号（通过 hermes setup 命令登录）。 |

# Default — opens browser to http://127.0.0.1:9119
hermes dashboard

# Custom port, no browser
hermes dashboard --port 8080 --no-open

# From a profile alias — routes to the machine dashboard with the
# profile preselected in the sidebar switcher (attach if running)
worker dashboard

hermes profile

hermes profile <subcommand>

管理配置文件——支持多个相互隔离的 Hermes 实例，每个实例拥有独立的配置、会话、技能及主目录。

示例：

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 自动补全脚本输出到标准输出。将该输出引入您的 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 [--gateway] [--check] [--plan] [--no-backup] [--backup] [--yes]

该命令会拉取最新的 hermes-agent 源代码，并在管理的虚拟环境中重新安装所有依赖项，随后再次运行安装后的钩子程序（如 MCP 服务器启动、技能同步以及补全功能安装等）。因此可在实际生产环境中的安装环境中安全使用。若想在不进行实际安装的情况下查看当前代码版本是否落后于 origin/main，可使用 --check 参数。

hermes update 命令会获取配置好的更新分支（默认为 main）。如果当前代码位于其他分支上，Hermes 可能会在拉取代码之前先切换到该更新分支。若希望将特定分支上的修改保留下来，避免被自动纳入更新流程，建议在执行更新操作前先提交这些修改。

其他行为：

• 网关重启。在更新成功后，Hermes会自动尝试重启所有正在运行的网关配置，以便它们能够加载新的代码。若您希望在不进行更新的情况下重启网关，则可使用hermes gateway restart命令。
• 重启阶段恢复。在导入新获取的代码树时，如果进程内的重启阶段意外中断，受系统监控的网关配置将会通过一个全新的Python进程重新尝试重启。只有经过systemd确认已成功重启的配置（通过systemctl --user is-active命令检测）才会被标记为“已验证”；而仅以代码执行状态0结束的重启操作则会被记录为“已尝试重启”，出于谨慎考虑，此类操作仍会导致更新失败。未经特别授权，手动管理的网关以及服务器/控制台运行环境绝不会被强制终止，它们会被记录为“已跳过”，并附上具体原因，同时连同完整的重启命令一起保留在更新失败的报告中。
• 更新记录与集群版本检查。每次运行都会在~/.hermes/logs/update_receipts/目录下生成一份机器可读的记录文件，内容包括更新前的集群计划、操作步骤、跳过原因以及重启结果；其中latest.json文件指向最新的记录。在重启阶段结束后，更新工具会将每个正在运行的网关的代码版本与更新后的版本进行比对，并输出针对每个配置的版本矩阵；如果某个网关仍在使用更新前的代码，则更新会失败（返回状态1），报告中也会注明具体的重启命令。
• 本地代码变更处理。 对于通过 git 安装的版本，Hermes 会在检出分支或执行 pull 操作之前，自动将已跟踪的脏文件以及未跟踪的文件暂存起来（git stash push --include-untracked）。在交互式终端模式下，恢复暂存内容时会先询问用户确认；而非交互式更新则会默认恢复暂存内容。仅在对本地代码修改要求在成功 pull 后被丢弃的托管安装环境中，才可将 updates.non_interactive_local_changes 设置为 discard。如果恢复暂存内容时出现冲突或 pull 操作失败，暂存内容将保持原状，以便用户手动处理。
• npm lockfile 变更清理。 在暂存内容或切换分支之前，Hermes 会尽力清理由 npm install/build 步骤产生的已跟踪的 package-lock.json 差异文件。在运行 hermes update 前，请先将有意修改的 lockfile 内容提交或手动暂存。
• 配对数据快照功能。 即使未开启 --backup 参数，hermes update 也会在执行 git pull 之前，对 ~/.hermes/pairing/ 目录以及飞书评论规则生成轻量级的快照。如果 pull 操作覆盖了您正在编辑的文件，可通过 hermes backup restore --state pre-update 将其恢复到之前的状态。
• 旧版 hermes.service 警告提示。 如果 Hermes 检测到系统存在重命名前的 hermes.service systemd 单元（而非当前的 hermes-gateway.service），它会一次性输出迁移提示，帮助用户避免出现循环问题。
• 退出码说明。 操作成功时返回 0；在 pull、安装或安装后出现错误时返回 1；因工作区出现意外变更而无法执行 git pull 时返回 2。

维护命令

| hermes uninstall [--full] [--gui] [--dry-run] [--yes] | 卸载 Hermes，可选择是否同时删除所有配置文件和数据。--gui 仅删除桌面端聊天界面，保留 Agent 功能；--full 会同时删除配置文件和数据；--dry-run 仅显示将要删除的内容而不会实际执行任何操作；--yes 跳过确认提示。 |

参见

• Slash Commands 参考文档
• CLI 接口
• 会话管理
• 技能系统
• 皮肤与主题