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 工作树。
--yolo	跳过危险命令的审批提示。
--pass-session-id	将会话 ID 包含在代理的系统提示中。

顶层命令

命令	用途
hermes chat	与代理进行交互式或单次对话。
hermes model	交互式选择默认提供者和模型。
hermes gateway	运行或管理消息网关服务。
hermes setup	交互式设置向导，用于全部或部分配置。
hermes whatsapp	配置并配对 WhatsApp 桥接。
hermes auth	管理凭据 — 添加、列出、删除、重置、设置策略。处理 Codex/Nous/Anthropic 的 OAuth 流程。
hermes login / logout	已弃用 — 请改用 hermes auth。
hermes status	显示代理、认证和平台状态。
hermes cron	检查并触发定时调度器。
hermes webhook	管理事件驱动激活的动态 Webhook 订阅。
hermes doctor	诊断配置和依赖项问题。
hermes dump	可复制粘贴的设置摘要，用于支持/调试。
hermes logs	查看、实时跟踪和过滤代理/网关/错误日志文件。
hermes config	显示、编辑、迁移和查询配置文件。
hermes pairing	批准或撤销消息配对码。
hermes skills	浏览、安装、发布、审计和配置技能。
hermes honcho	管理 Honcho 跨会话记忆集成。
hermes memory	配置外部记忆提供者。
hermes acp	以 ACP 服务器模式运行 Hermes，用于编辑器集成。
hermes mcp	管理 MCP 服务器配置，并以 MCP 服务器模式运行 Hermes。
hermes plugins	管理 Hermes 代理插件（安装、启用、禁用、移除）。
hermes tools	配置各平台启用的工具。
hermes sessions	浏览、导出、清理、重命名和删除会话。
hermes insights	显示 token/成本/活动分析。
hermes claw	OpenClaw 迁移辅助工具。
hermes profile	管理配置文件 — 多个隔离的 Hermes 实例。
hermes completion	输出 shell 补全脚本（bash/zsh）。
hermes version	显示版本信息。
hermes update	拉取最新代码并重新安装依赖项。
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、huggingface、zai、kimi-coding、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、alibaba。
-s, --skills <name>	为会话预加载一个或多个技能（可重复或以逗号分隔）。
-v, --verbose	详细输出。
-Q, --quiet	程序化模式：抑制横幅/旋转图标/工具预览。
--resume <session> / --continue [name]	直接从 chat 命令中恢复会话。
--worktree	为此运行创建一个隔离的 git 工作树。
--checkpoints	在破坏性文件更改前启用文件系统检查点。
--yolo	跳过审批提示。
--pass-session-id	将会话 ID 传递到系统提示中。
--source <tag>	会话来源标签，用于过滤（默认：cli）。使用 tool 表示第三方集成，不应出现在用户会话列表中。
--max-turns <N>	每轮对话的最大工具调用迭代次数（默认：90，或配置中的 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 model

交互式提供者 + 模型选择器。

hermes model

在以下情况下使用此命令：

• 切换默认提供者
• 在模型选择过程中登录 OAuth 支持的提供者
• 从提供者特定的模型列表中选择
• 配置自定义/自托管端点
• 将新默认值保存到配置中

/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

提供方和基础 URL 的更改会自动保存到 config.yaml 中。当切换出自定义端点时，旧的基础 URL 会被清除，以防止泄露到其他提供方。

hermes gateway

hermes gateway <subcommand>

子命令：

子命令	描述
run	在前台运行网关。
start	启动已安装的网关服务。
stop	停止服务。
restart	重启服务。
status	显示服务状态。
install	作为用户服务安装（Linux 上为 systemd，macOS 上为 launchd）。
uninstall	移除已安装的服务。
setup	交互式消息平台设置。

hermes setup

hermes setup [model|terminal|gateway|tools|agent] [--non-interactive] [--reset]

使用完整向导，或直接跳转到某个部分：

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

选项：

选项	描述
--non-interactive	使用默认值 / 环境变量，不进行提示。
--reset	在设置前将配置重置为默认值。

hermes whatsapp

hermes whatsapp

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

hermes login / hermes logout (已弃用)

警告

hermes login 已移除。请使用 hermes auth 管理 OAuth 凭证，使用 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 remove openrouter 2                          # Remove by index
hermes auth reset openrouter                             # Clear cooldowns

子命令：add、list、remove、reset。若未指定子命令，则启动交互式管理向导。

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	在下一个调度器 tick 触发任务。
remove	删除已安排的任务。
status	检查 cron 调度器是否正在运行。
tick	执行所有到期的任务一次后退出。

hermes webhook

hermes webhook <subscribe|list|remove|test>

管理用于事件驱动代理激活的动态 Webhook 订阅。需要在配置中启用 Webhook 平台——若未配置，将打印设置说明。

子命令	描述
subscribe / add	创建一个 Webhook 路由。返回 URL 和 HMAC 密钥，用于在您的服务上配置。
list / ls	显示所有代理创建的订阅。
remove / rm	删除一个动态订阅。配置文件中的静态路由不受影响。
test	发送测试 POST 请求以验证订阅是否正常工作。

hermes webhook subscribe

hermes webhook subscribe <name> [options]

选项	描述
--prompt	包含 {dot.notation} 负载引用的提示模板。
--events	以逗号分隔的要接受的事件类型（例如 issues,pull_request）。空值 = 所有事件。
--description	人类可读的描述。
--skills	以逗号分隔的技能名称，用于代理运行时加载。
--deliver	交付目标：log（默认）、telegram、discord、slack、github_comment。
--deliver-chat-id	用于跨平台交付的目标聊天/频道 ID。
--secret	自定义 HMAC 密钥。若省略则自动生成。

订阅会持久化保存至 ~/.hermes/webhook_subscriptions.json，并由 Webhook 适配器热重载，无需重启网关。

hermes doctor

hermes doctor [--fix]

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

hermes dump

hermes dump [--show-keys]

输出您整个 Hermes 设置的紧凑、纯文本摘要。专为复制粘贴到 Discord、GitHub 问题或 Telegram 中请求支持而设计——无 ANSI 颜色，无特殊格式，仅包含数据。

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

包含内容

区段	详情
头部	Hermes 版本、发布日期、git 提交哈希
环境	操作系统、Python 版本、OpenAI SDK 版本
身份	活跃配置文件名称、HERMES_HOME 路径
模型	配置的默认模型和提供方
终端	后端类型（本地、docker、ssh 等）
API 密钥	所有 22 个提供方/工具 API 密钥的存在性检查
功能	已启用的工具集、MCP 服务器数量、记忆提供方
服务	网关状态、配置的消息平台
工作负载	定时任务数量、已安装技能数量
配置覆盖	与默认值不同的任何配置值

示例输出

--- 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 —— 将转储内容粘贴到问题中
• 在 Discord 中寻求帮助 —— 以代码块形式分享
• 与他人设置进行对比
• 当某项功能异常时快速进行健康检查

提示

hermes dump 专为共享设计。如需交互式诊断，请使用 hermes doctor。如需可视化概览，请使用 hermes status。

hermes logs

hermes logs [log_name] [options]

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

日志文件

名称	文件	记录内容
agent（默认）	agent.log	所有代理活动 —— 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（天）。

示例

# 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 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 安装的技能。
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 check
hermes skills update
hermes skills config

备注：

• --force 可覆盖第三方/社区技能的非危险策略限制。
• --force 不会覆盖 dangerous 扫描结果。
• --source skills-sh 用于搜索公共的 skills.sh 目录。
• --source well-known 允许 Hermes 指向一个提供 /.well-known/skills/index.json 的站点。

hermes honcho

hermes honcho [--target-profile NAME] <subcommand>

管理 Honcho 跨会话记忆集成。此命令由 Honcho 记忆提供方插件提供，仅当配置中 memory.provider 设置为 honcho 时可用。

--target-profile 标志允许你在不切换到该配置文件的情况下管理另一个配置文件的 Honcho 配置。

子命令：

子命令	描述
setup	重定向到 hermes memory setup（统一的设置路径）。
status [--all]	显示当前 Honcho 配置和连接状态。--all 显示跨配置文件的概览。
peers	显示所有配置文件中的对等身份。
sessions	列出已知的 Honcho 会话映射。
map [name]	将当前目录映射到一个 Honcho 会话名称。省略 name 以列出当前映射。
peer	显示或更新对等名称和辩证推理级别。选项：--user NAME、--ai NAME、--reasoning LEVEL。
mode [mode]	显示或设置回忆模式：hybrid、context 或 tools。省略以显示当前模式。
tokens	显示或设置上下文和辩证的 token 预算。选项：--context N、--dialectic N。
identity [file] [--show]	种子或显示 AI 对等身份表示。
enable	为当前活动配置文件启用 Honcho。
disable	为当前活动配置文件禁用 Honcho。
sync	将 Honcho 配置同步到所有现有配置文件（创建缺失的主机块）。
migrate	从 openclaw-honcho 迁移到 Hermes Honcho 的逐步迁移指南。

hermes memory

hermes memory <subcommand>

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

子命令：

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

hermes acp

hermes acp

以 ACP（Agent Client Protocol）stdio 服务器模式启动 Hermes，用于编辑器集成。

相关入口点：

hermes-acp
python -m acp_adapter

请先安装支持：

pip install -e '.[acp]'

参见 ACP 编辑器集成 和 ACP 内部原理。

hermes mcp

hermes mcp <subcommand>

管理 MCP（Model Context Protocol）服务器配置，并以 MCP 服务器模式运行 Hermes。

子命令	描述
serve [-v|--verbose]	以 MCP 服务器模式运行 Hermes — 向其他智能体暴露对话。
add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth|header]	添加一个 MCP 服务器并自动发现工具。
remove <name>（别名：rm）	从配置中移除一个 MCP 服务器。
list（别名：ls）	列出已配置的 MCP 服务器。
test <name>	测试与 MCP 服务器的连接。
configure <name>（别名：config）	切换服务器的工具选择。

参见 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 时，将启动按平台划分的交互式工具配置 UI。

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、~/.moldbot）和配置文件名（clawdbot.json、moldbot.json）。

选项	描述
--dry-run	预览将要迁移的内容，但不写入任何数据。
--preset <name>	迁移预设：full（默认，包含密钥）或 user-data（不包含 API 密钥）。
--overwrite	在冲突时覆盖现有的 Hermes 文件（默认：跳过）。
--migrate-secrets	在迁移中包含 API 密钥（使用 --preset full 时默认启用）。
--source <path>	自定义的 OpenClaw 目录（默认：~/.openclaw）。
--workspace-target <path>	工作区指令（AGENTS.md）的目标目录。
--skill-conflict <mode>	处理技能名称冲突：skip（默认）、overwrite 或 rename。
--yes	跳过确认提示。

迁移内容

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

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

归档以供手动审查： 定时任务、插件、钩子/Webhook、记忆后端（QMD）、技能注册表配置、UI/身份、日志、多代理设置、频道绑定、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 including API keys
hermes claw migrate --preset full

# 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 profile

hermes profile <subcommand>

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

子命令	描述
list	列出所有配置文件。
use <name>	设置一个持久默认配置文件。
create <name> [--clone] [--clone-all] [--clone-from <source>] [--no-alias]	创建新配置文件。--clone 从当前活动配置文件复制配置、.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 归档文件导入配置文件。

示例：

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 -p work chat -q "Hello from work profile"

hermes completion

hermes completion [bash|zsh]

将 shell 补全脚本输出到 stdout。在 shell 配置文件中源码该输出，以实现 Hermes 命令、子命令和配置文件名的 Tab 补全。

示例：

# Bash
hermes completion bash >> ~/.bashrc

# Zsh
hermes completion zsh >> ~/.zshrc

维护命令

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

参见

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