Hermes Agent 完整使用指南
Hermes Agent 完整使用指南¶
版本: v2.2+ | 作者: Nous Research
官方文档: https://hermes-agent.nousresearch.com/docs
源码仓库: https://github.com/NousResearch/hermes-agent
目录¶
- 简介
- 安装
- 快速开始
- CLI 命令参考
- 配置系统
- 模型与 Provider
- 工具集(Toolsets)
- Slash 命令
- Skills 技能系统
- Memory 持久记忆
- Session 会话管理
- Cron 定时任务
- MCP 集成
- Gateway 消息网关
- Webhook 订阅
- 多 Agent 委派与协作
- Profile 多环境隔离
- 语音功能(STT/TTS)
- 浏览器自动化
- Kanban 多任务协作看板
- 安全与隐私
- 项目上下文文件
- 故障排除
- 附录:关键路径速查
1. 简介¶
Hermes Agent 是由 Nous Research 开发的开源 AI Agent 框架,运行在终端、消息平台和 IDE 中。与 Claude Code、Codex、OpenClaw 同属自主编程/任务执行 Agent 类别。
核心特点¶
| 特点 | 说明 |
|---|---|
| 自学习技能 | 从经验中保存可复用流程为 Skills,积累后越来越强 |
| 持久记忆 | 跨会话记住用户偏好、环境、教训 |
| 多平台网关 | 同一个 Agent 运行在 Telegram/Discord/Slack/WhatsApp/企业微信/飞书等 10+ 平台 |
| Provider 无关 | 支持 20+ LLM Provider,随时切换模型 |
| Profile 隔离 | 多个独立实例,各有独立配置/会话/技能/记忆 |
| 高度可扩展 | 插件、MCP 服务器、自定义工具、Webhook、Cron 定时 |
2. 安装¶
Linux / macOS / WSL2 / Android (Termux)¶
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Windows (PowerShell)¶
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
Windows / macOS (Desktop)¶
从官网下载 Hermes Desktop 安装程序直接安装。
安装后初始化¶
# 交互式设置向导
hermes setup
# 快速配置模型(推荐 Nous Portal 一键 OAuth)
hermes setup --portal
# 检查依赖和配置
hermes doctor
# 切换模型
hermes model
3. 快速开始¶
# 启动交互式聊天(默认行为)
hermes
# 单次查询(非交互)
hermes chat -q "法国的首都是什么?"
# 指定模型
hermes chat -q "写一个排序算法" -m anthropic/claude-sonnet-4
# 恢复上次会话
hermes --continue
# 恢复指定会话
hermes --resume <session-id>
4. CLI 命令参考¶
全局参数¶
hermes [flags] [command]
--version, -V 显示版本
--resume, -r SESSION 按 ID 或标题恢复会话
--continue, -c [NAME] 恢复最近会话
--worktree, -w 独立 git worktree 模式(并行 Agent)
--skills, -s SKILL 预加载技能(逗号分隔或重复 -s)
--profile, -p NAME 使用指定 Profile
--yolo 跳过危险命令审批
--pass-session-id 在系统提示中包含会话 ID
无子命令时默认执行
chat。
Chat 聊天¶
hermes chat [flags]
-q, --query TEXT 单次查询(非交互)
-m, --model MODEL 模型(如 anthropic/claude-sonnet-4)
-t, --toolsets LIST 逗号分隔的工具集列表
--provider PROVIDER 强制指定 Provider
-v, --verbose 详细输出
-Q, --quiet 静默模式
--checkpoints 启用文件系统检查点(/rollback)
--source TAG 会话来源标签
配置管理¶
hermes setup [section] 交互式向导 (model|terminal|gateway|tools|agent)
hermes model 交互式模型/Provider 选择器
hermes config 查看当前配置
hermes config edit 在 $EDITOR 中编辑 config.yaml
hermes config set KEY VAL 设置配置值
hermes config path 打印 config.yaml 路径
hermes config env-path 打印 .env 路径
hermes config check 检查缺失/过期配置
hermes config migrate 更新配置以包含新选项
hermes auth 交互式凭证管理器
hermes auth add PROVIDER 添加 OAuth 或 API Key 凭证
hermes auth list 列出已存储的凭证
hermes auth remove PROVIDER 删除已存储的凭证
hermes doctor [--fix] 检查依赖和配置
hermes status [--all] 显示组件状态
工具与技能¶
hermes tools 交互式工具启用/禁用(curses UI)
hermes tools list 显示所有工具及状态
hermes tools enable NAME 启用工具集
hermes tools disable NAME 禁用工具集
hermes skills list 列出已安装技能
hermes skills search QUERY 在技能中心搜索
hermes skills install ID 安装技能
hermes skills inspect ID 预览技能(不安装)
hermes skills config 按平台启用/禁用技能
hermes skills check 检查技能更新
hermes skills update 更新过时技能
hermes skills uninstall ID 删除技能
hermes skills publish PATH 发布到注册中心
hermes skills browse 浏览所有可用技能
hermes skills tap add REPO 添加 GitHub 仓库作为技能源
MCP 服务器¶
hermes mcp serve 将 Hermes 作为 MCP 服务器运行
hermes mcp add NAME 添加 MCP 服务器
hermes mcp remove NAME 移除 MCP 服务器
hermes mcp list 列出已配置的服务器
hermes mcp test NAME 测试连接
hermes mcp configure NAME 切换工具选择
Gateway 消息网关¶
hermes gateway run 前台运行网关
hermes gateway install 安装为后台服务
hermes gateway start/stop 控制服务
hermes gateway restart 重启服务
hermes gateway status 检查状态
hermes gateway setup 配置平台
会话管理¶
hermes sessions list 列出最近会话
hermes sessions browse 交互式选择器
hermes sessions export OUT 导出为 JSONL
hermes sessions rename ID T 重命名会话
hermes sessions delete ID 删除会话
hermes sessions prune 清理旧会话
hermes sessions stats 会话存储统计
Cron 定时任务¶
hermes cron list 列出任务
hermes cron create SCHED 创建任务("30m"、"every 2h"、"0 9 * * *")
hermes cron edit ID 编辑调度、提示、投递
hermes cron pause/resume ID 控制任务状态
hermes cron run ID 立即触发
hermes cron remove ID 删除任务
hermes cron status 调度器状态
Webhook 订阅¶
hermes webhook subscribe N 在 /webhooks/<name> 创建路由
hermes webhook list 列出订阅
hermes webhook remove NAME 移除订阅
hermes webhook test NAME 发送测试 POST
Profile 管理¶
hermes profile list 列出所有 Profile
hermes profile create NAME 创建(支持 --clone)
hermes profile use NAME 设置默认 Profile
hermes profile delete NAME 删除
hermes profile show NAME 显示详情
hermes profile alias NAME 管理包装脚本
hermes profile rename A B 重命名
hermes profile export NAME 导出为 tar.gz
hermes profile import FILE 从归档导入
凭证池¶
hermes auth add 交互式凭证向导
hermes auth list [PROVIDER] 列出池化凭证
hermes auth remove P INDEX 按 Provider + 索引移除
hermes auth reset PROVIDER 清除耗尽状态
其他命令¶
hermes insights [--days N] 使用分析
hermes update 更新到最新版本
hermes pairing list/approve/revoke DM 授权
hermes plugins list/install/remove 插件管理
hermes honcho setup/status Honcho 记忆集成
hermes memory setup/status/off 记忆 Provider 配置
hermes completion bash|zsh Shell 补全
hermes acp ACP 服务器(IDE 集成)
hermes claw migrate 从 OpenClaw 迁移
hermes uninstall 卸载 Hermes
5. 配置系统¶
配置文件位置¶
| 文件 | 用途 |
|---|---|
~/.hermes/config.yaml |
主配置文件 |
~/.hermes/.env |
API Key 和密钥 |
$HERMES_HOME/.env |
若设置了 HERMES_HOME |
~/.hermes/profiles/<name>/ |
Profile 独立配置 |
主要配置段¶
| 段 | 关键选项 |
|---|---|
model |
default, provider, base_url, api_key, context_length |
agent |
max_turns(90), tool_use_enforcement |
terminal |
backend(local/docker/ssh/modal), cwd, timeout(180) |
compression |
enabled, threshold(0.50), target_ratio(0.20) |
display |
skin, tool_progress, show_reasoning, show_cost |
stt |
enabled, provider(local/groq/openai/mistral) |
tts |
provider(edge/elevenlabs/openai/minimax/mistral/neutts) |
memory |
memory_enabled, user_profile_enabled, provider |
security |
tirith_enabled, website_blocklist |
delegation |
model, provider, max_iterations(50) |
checkpoints |
enabled, max_snapshots(50) |
终端后端¶
| 后端 | 说明 |
|---|---|
local |
本地直接运行(默认) |
docker |
Docker 容器隔离 |
ssh |
远程 SSH 执行 |
modal |
Modal 无服务器 |
singularity |
HPC Singularity/Apptainer |
vercel_sandbox |
Vercel Sandbox 云端 microVM |
上下文压缩¶
上下文超过阈值(默认 token 上限的 50%)时自动压缩,保留最近对话和关键信息:
compression:
enabled: true
threshold: 0.50 # token 使用超过 50% 时触发
target_ratio: 0.20 # 压缩到 20%
辅助模型¶
用于视觉分析、压缩、会话搜索等辅助任务:
hermes config set auxiliary.vision.provider <provider>
hermes config set auxiliary.vision.model <model>
6. 模型与 Provider¶
支持的 Provider¶
| Provider | 认证方式 | 环境变量 |
|---|---|---|
| OpenRouter | API Key | OPENROUTER_API_KEY |
| Anthropic | API Key | ANTHROPIC_API_KEY |
| Nous Portal | OAuth | hermes auth |
| OpenAI Codex | OAuth | hermes auth |
| GitHub Copilot | Token | COPILOT_GITHUB_TOKEN |
| Google Gemini | API Key | GOOGLE_API_KEY |
| DeepSeek | API Key | DEEPSEEK_API_KEY |
| xAI / Grok | API Key | XAI_API_KEY |
| Hugging Face | Token | HF_TOKEN |
| Z.AI / GLM | API Key | GLM_API_KEY |
| MiniMax | API Key | MINIMAX_API_KEY |
| Kimi / Moonshot | API Key | KIMI_API_KEY |
| Alibaba / DashScope | API Key | DASHSCOPE_API_KEY |
| Xiaomi MiMo | API Key | XIAOMI_API_KEY |
| Qwen OAuth | OAuth | hermes auth add qwen-oauth |
| 自定义端点 | 配置 | model.base_url + model.api_key |
切换模型¶
# 交互式选择
hermes model
# 直接指定
hermes chat -m anthropic/claude-sonnet-4 -q "你好"
# 在聊天中切换
/model deepseek/deepseek-chat
凭证池¶
支持多个 API Key 轮换,策略可选:
hermes auth add # 添加凭证
hermes auth list # 列出池化凭证
hermes config set credential_pools.strategy round_robin # 策略
可选策略:fill_first(默认)、round_robin、least_used、random
7. 工具集(Toolsets)¶
管理工具¶
hermes tools # 交互式 UI
hermes tools list # 列出所有工具及状态
hermes tools enable NAME # 启用
hermes tools disable NAME # 禁用
工具变更在
/reset(新会话)后生效。
可用工具集¶
| 工具集 | 功能 |
|---|---|
web |
网页搜索和内容提取 |
search |
仅网页搜索 |
browser |
浏览器自动化 |
terminal |
Shell 命令和进程管理 |
file |
文件读/写/搜索/补丁 |
code_execution |
沙箱 Python 执行 |
vision |
图像分析 |
image_gen |
AI 图像生成 |
video |
视频分析和生成 |
tts |
文本转语音 |
skills |
技能浏览和管理 |
memory |
持久跨会话记忆 |
session_search |
搜索历史会话 |
delegation |
子 Agent 委派 |
cronjob |
定时任务管理 |
clarify |
向用户提澄清问题 |
messaging |
跨平台消息发送 |
todo |
任务规划和跟踪 |
kanban |
多 Agent 工作队列 |
spotify |
Spotify 播放控制 |
homeassistant |
智能家居控制 |
discord |
Discord 集成 |
feishu_doc |
飞书文档 |
feishu_drive |
飞书云盘 |
yuanbao |
腾讯元宝集成 |
safe |
最小化低风险工具集 |
8. Slash 命令¶
在交互式会话中直接输入,以 / 开头。
会话控制¶
/new (/reset) 新建会话
/clear 清屏 + 新会话(CLI)
/retry 重新发送最后一条消息
/undo 撤销最后一次交互
/title [name] 命名会话
/compress 手动压缩上下文
/stop 终止后台进程
/rollback [N] 恢复文件系统检查点
/snapshot [sub] 创建或恢复状态快照
/background <prompt> 在后台运行提示
/queue <prompt> 排入下一轮执行
/steer <prompt> 在下次工具调用后注入消息(不中断)
/agents (/tasks) 显示活跃 Agent 和运行中的任务
/resume [name] 恢复命名会话
/goal [text] 设置持续目标(跨回合直到完成)
/redraw 强制 UI 重绘(CLI)
配置¶
/config 显示配置(CLI)
/model [name] 显示或切换模型
/personality [name] 设置人设
/reasoning [level] 设置推理级别 (none|minimal|low|medium|high|xhigh|show|hide)
/verbose 循环:off → new → all → verbose
/voice [on|off|tts] 语音模式
/yolo 切换审批跳过
/busy [sub] 控制忙碌时 Enter 行为(CLI)
/indicator [style] 选择 TUI 忙碌指示器(kaomoji|emoji|unicode|ascii)
/footer [on|off] 切换网关运行元数据脚注
/skin [name] 切换主题(CLI)
/statusbar 切换状态栏(CLI)
工具与技能¶
/tools 管理工具(CLI)
/toolsets 列出工具集(CLI)
/skills 搜索/安装技能(CLI)
/skill <name> 将技能加载到会话
/reload-skills 重新扫描技能目录
/reload 重新加载 .env 环境变量
/reload-mcp 重新加载 MCP 服务器
/cron 管理定时任务(CLI)
/curator [sub] 后台技能维护(status|run|pin|archive…)
/kanban [sub] 多 Profile 协作看板
/plugins 列出插件(CLI)
网关¶
/approve 批准待审批命令
/deny 拒绝待审批命令
/restart 重启网关
/sethome 设置当前聊天为首页频道
/update 更新 Hermes
/topic [sub] 启用 Telegram DM 主题会话
/platforms (/gateway) 显示平台连接状态
工具¶
/branch (/fork) 分支当前会话
/fast 切换优先/快速处理
/browser 打开 CDP 浏览器连接
/history 显示对话历史(CLI)
/save 保存对话到文件(CLI)
/copy [N] 复制最后一条助手回复到剪贴板
/paste 附加剪贴板图像
/image 附加本地图像文件
信息¶
/help 显示命令
/commands [page] 浏览所有命令(网关)
/usage Token 使用量
/insights [days] 使用分析
/status 会话信息
/profile 当前 Profile 信息
/debug 上传调试报告
退出¶
/quit (/exit, /q) 退出 CLI
9. Skills 技能系统¶
Skills 是 Hermes 的"程序性记忆"——解决复杂问题、发现工作流或获得纠正后,可将其持久化为技能文档,后续会话自动加载。
内置技能分类¶
- Autonomous AI Agents — 自主 AI Agent 相关(hermes-agent、computer-use 等)
- Creative — 创意生成(架构图、短视频、文案等)
- DevOps — 运维管理(Kanban、任务分解等)
- GitHub — GitHub 工作流(代码审查、Issue 转 PR 等)
- Infrastructure — 基础设施(CouchDB、Ubuntu 维护等)
- Integration — 集成模式
- Platforms — 平台配置(LightClaw 等)
- Productivity — 生产力工具(PDF、DOCX、PPTX、XLSX、Obsidian 等)
- Research — 研究(arXiv、竞争对手监控、引用溯源等)
- Software Development — 开发(TDD、调试、代码审查等)
技能管理¶
# 浏览技能中心
hermes skills browse
# 搜索
hermes skills search "PDF"
# 安装
hermes skills install <id>
# 预览
hermes skills inspect <id>
# 检查更新
hermes skills check
hermes skills update
# 删除
hermes skills uninstall <id>
# 发布
hermes skills publish <path>
在会话中使用¶
/skill <name> 手动加载技能
/reload-skills 重新扫描技能目录
Agent 自动创建技能¶
Hermes 会在解决复杂任务后自动创建技能,通过 Curator 系统管理生命周期:
- Curator CLI:
hermes curator status|run|pause|resume|pin|unpin|archive|restore|prune - Curator Slash:
/curator <subcommand>
Curator 只触碰 created_by: "agent" 的技能,不会修改内置或 Hub 安装的技能。
10. Memory 持久记忆¶
两个文件¶
| 文件 | 用途 | 字符限制 |
|---|---|---|
MEMORY.md |
Agent 个人笔记——环境事实、惯例、学习 | 2,200 字符 |
USER.md |
用户档案——偏好、沟通风格、期望 | 1,375 字符 |
存储在 ~/.hermes/memories/,会话开始时注入系统提示。
记忆工具操作¶
- add — 添加新条目
- replace — 替换现有条目(通过
old_text子串匹配) - remove — 移除条目
没有
read操作——内容自动注入系统提示。
Session Search(会话搜索)¶
所有会话存储在 SQLite (~/.hermes/state.db),支持 FTS5 全文搜索:
session_search(query="查找上次讨论的部署方案")
session_search(session_id="xxx", around_message_id=123)
记忆 vs 会话搜索¶
| 特性 | 持久记忆 | 会话搜索 |
|---|---|---|
| 容量 | ~1,300 tokens | 无限 |
| 速度 | 即时(系统提示内) | ~20ms FTS5 查询 |
| 用途 | 始终需要的关键事实 | 查找特定历史对话 |
| 管理 | Agent 手动维护 | 自动存储 |
配置¶
memory:
memory_enabled: true
user_profile_enabled: true
memory_char_limit: 2200
user_char_limit: 1375
write_approval: false # true = 需要审批才能写入
Learning Journey¶
/journey # TUI 显示学习时间线
/journey --play # 动画展示
11. Session 会话管理¶
会话控制¶
hermes sessions list 列出最近会话
hermes sessions browse 交互式选择
hermes sessions export OUT 导出为 JSONL
hermes sessions rename ID T 重命名
hermes sessions delete ID 删除
hermes sessions prune 清理旧会话(--older-than N days)
hermes sessions stats 存储统计
恢复会话¶
hermes --continue 恢复最近会话
hermes --resume <id> 恢复指定会话
hermes --resume <title> 按标题恢复
会话内操作¶
/new 新建会话
/branch 分支会话
/title <name> 命名
/history 查看历史
/save 保存到文件
12. Cron 定时任务¶
创建任务¶
# 每 30 分钟
hermes cron create "30m" "检查服务器状态"
# 每天 9:00
hermes cron create "0 9 * * *" "生成每日报告" --skill report-builder
# 每周一
hermes cron create "every monday 9am" "周报汇总"
# 一次性任务
hermes cron create "2026-09-01T09:00:00" "执行迁移"
管理任务¶
hermes cron list 列出任务
hermes cron edit <id> 编辑任务
hermes cron pause <id> 暂停
hermes cron resume <id> 恢复
hermes cron run <id> 立即触发
hermes cron remove <id> 删除
hermes cron status 调度器状态
高级功能¶
- Script 预检: 任务前运行脚本,
{"wakeAgent": false}可跳过 Agent - Context Chain:
context_from将前一个任务的输出注入后一个任务 - 多平台投递: 逗号分隔多个目标
- No-Agent 模式:
--no-agent --script watchdog.sh,脚本输出即结果 - Continuable:
attach_to_session: true,投递后可回复继续对话 - Bot-Chat 投递: 注入到另一个 Bot 的对话中
投递选项¶
| 选项 | 说明 |
|---|---|
"origin" |
返回创建来源 |
"local" |
保存到本地文件 |
"telegram" |
Telegram 首页频道 |
"discord" |
Discord 首页频道 |
"slack" |
Slack 首页频道 |
"feishu" |
飞书首页频道 |
"wecom" |
企业微信首页频道 |
"all" |
所有已连接的首页频道 |
13. MCP 集成¶
Hermes 内置 MCP 客户端,自动连接 MCP 服务器并将其工具作为一级工具使用。
安装 MCP SDK¶
pip install mcp
配置 MCP 服务器¶
在 ~/.hermes/config.yaml 添加:
mcp_servers:
# Stdio 传输(命令模式)
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
timeout: 30
# 通过 npx 的 GitHub 服务器
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
timeout: 60
# 通过 uvx 的时间服务器
time:
command: "uvx"
args: ["mcp-server-time"]
# HTTP 传输(远程服务器)
remote_api:
url: "https://mcp.example.com/mcp"
headers:
Authorization: "Bearer sk-xxx"
timeout: 180
工具命名¶
MCP 工具自动命名为 mcp_{server}_{tool},例如:
- mcp_filesystem_read_file
- mcp_github_list_issues
- mcp_time_get_current_time
MCP 采样¶
MCP 服务器可通过 sampling/createMessage 请求 Agent 的 LLM 补全:
mcp_servers:
my_server:
command: "npx"
args: ["-y", "my-server"]
sampling:
enabled: true
model: "gemini-3-flash"
max_tokens_cap: 4096
max_tool_rounds: 5
安全¶
- 环境变量过滤:子进程只继承安全的基线变量(PATH, HOME 等)
- 错误消息中的凭证自动脱敏
- 通过
env显式传递所需密钥
14. Gateway 消息网关¶
安装与运行¶
# 配置
hermes gateway setup
# 前台运行
hermes gateway run
# 安装为后台服务
hermes gateway install
# 控制
hermes gateway start/stop/restart/status
支持的平台¶
| 平台 | 说明 |
|---|---|
| Telegram | 个人/群组/频道 Bot |
| Discord | 服务器 Bot |
| Slack | Workspace Bot |
| 通过 WhatsApp Business API | |
| Signal | Signal Bot |
| Matrix | Matrix 协议 |
| 邮件收发 | |
| SMS | 短信 |
| DingTalk | 钉钉 |
| Feishu | 飞书 |
| WeCom | 企业微信 |
| Weixin | 微信 |
| BlueBubbles | iMessage |
| Home Assistant | 智能家居 |
| API Server | REST API(Open WebUI 等) |
| Webhooks | Webhook 触发 |
| Mattermost | Mattermost |
API Server¶
Hermes 可作为 OpenAI 兼容 API 服务器运行:
platforms:
api_server:
enabled: true
port: 8645
Open WebUI 等客户端可通过 API 连接。
15. Webhook 订阅¶
设置¶
# 方式一:向导
hermes gateway setup
# 方式二:手动配置
# config.yaml:
platforms:
webhook:
enabled: true
extra:
host: "0.0.0.0"
port: 8644
secret: "your-secret"
# 重启网关后验证
curl http://localhost:8644/health
创建订阅¶
hermes webhook subscribe github-issues \
--events "issues" \
--prompt "新 Issue #{issue.number}: {issue.title}\n作者: {issue.user.login}" \
--deliver telegram \
--deliver-chat-id "-100123456789"
常见模式¶
# GitHub PR 审查
hermes webhook subscribe github-prs \
--events "pull_request" \
--prompt "PR #{pull_request.number}: {pull_request.title}" \
--skills "github-code-review"
# Stripe 支付通知
hermes webhook subscribe stripe-payments \
--events "payment_intent.succeeded" \
--prompt "支付 {data.object.status}: {data.object.amount} 分"
# 直接投递(零 LLM 成本)
hermes webhook subscribe alerts \
--deliver telegram \
--deliver-chat-id "123456789" \
--deliver-only \
--prompt "⚠️ 警报: {alert.message}"
16. 多 Agent 委派与协作¶
delegate_task(同步委派)¶
# 单个任务
delegate_task(goal="分析代码性能", context="路径: /src/...")
# 并行批量
delegate_task(tasks=[
{goal: "任务1", context: "..."},
{goal: "任务2", context: "..."},
{goal: "任务3", context: "..."}
])
| 特性 | delegate_task | 生成 hermes 进程 |
|---|---|---|
| 隔离 | 独立对话,共享进程 | 完全独立进程 |
| 时长 | 分钟级 | 小时/天 |
| 工具 | 部分继承 | 完全工具访问 |
| 交互 | 不可 | 可(PTY 模式) |
生成独立 Hermes 进程¶
# 单次任务
hermes chat -q "研究 GRPO 论文并写总结"
# tmux 交互式
tmux new-session -d -s agent1 -x 120 -y 40 'hermes'
tmux send-keys -t agent1 '构建 FastAPI 认证服务' Enter
# 多 Agent 协作
tmux new-session -d -s backend -x 120 -y 40 'hermes -w'
tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'
-w参数启用 worktree 模式,避免 git 冲突。
17. Profile 多环境隔离¶
每个 Profile 有独立的配置、会话、技能、记忆。
hermes profile list 列出所有 Profile
hermes profile create work --clone 创建并克隆当前
hermes profile create personal 创建空白
hermes profile use work 设为默认
hermes profile delete old 删除
hermes profile show work 查看详情
hermes profile export work 导出 tar.gz
hermes profile import archive.tar.gz 导入
使用 Profile¶
hermes -p work 使用 work Profile
hermes profile use work 设为全局默认
Profile 路径¶
~/.hermes/profiles/<name>/
├── config.yaml
├── .env
├── skills/
├── sessions/
├── memories/
├── plugins/
└── cron/
18. 语音功能(STT/TTS)¶
STT(语音转文字)¶
自动转录消息平台的语音消息。
stt:
enabled: true
provider: local # local, groq, openai, mistral
local:
model: base # tiny, base, small, medium, large-v3
Provider 优先级:
1. local faster-whisper — 免费(pip install faster-whisper)
2. Groq Whisper — 免费额度(设置 GROQ_API_KEY)
3. OpenAI Whisper — 付费(设置 VOICE_TOOLS_OPENAI_KEY)
4. Mistral Voxtral — 付费(设置 MISTRAL_API_KEY)
TTS(文字转语音)¶
| Provider | 环境变量 | 免费? |
|---|---|---|
| Edge TTS | 无需 | ✅(默认) |
| ElevenLabs | ELEVENLABS_API_KEY |
有免费额度 |
| OpenAI | VOICE_TOOLS_OPENAI_KEY |
付费 |
| MiniMax | MINIMAX_API_KEY |
付费 |
| NeuTTS(本地) | 无需(pip install neutts[all]) |
✅ |
语音命令¶
/voice on 开启语音模式(语音输入 → 语音输出)
/voice tts 始终语音回复
/voice off 关闭语音
19. 浏览器自动化¶
启用¶
hermes tools enable browser
提供商¶
- Browserbase — 云端浏览器
- Camofox — 反检测浏览器
- 本地 Chromium — 通过 CDP 连接
使用¶
/browser 打开 CDP 浏览器连接
Agent 可以自动:
- 导航网页
- 填写表单
- 点击元素
- 提取内容
- 截图
- 处理弹窗(must_respond / auto_dismiss / auto_accept)
20. Kanban 多任务协作看板¶
基于 SQLite 的持久看板,用于多 Profile/多 Worker 协作。
CLI 操作¶
hermes kanban init 初始化看板
hermes kanban create 创建任务
hermes kanban list 列出任务
hermes kanban show <id> 查看任务详情
hermes kanban assign <id> 分配任务
hermes kanban complete <id> 完成任务
hermes kanban block <id> 阻塞任务
hermes kanban unblock <id> 解除阻塞
hermes kanban comment <id> 添加评论
hermes kanban archive <id> 归档
hermes kanban stats 统计
Slash 命令¶
/kanban tasks 列出任务
/kanban show <id> 详情
/kanban link 关联
Dispatcher¶
默认在网关中运行,自动:
- 回收过期 claim
- 提升就绪任务
- 原子性 claim 并生成 Worker
21. 安全与隐私¶
命令审批¶
# 默认:手动审批
hermes config set approvals.mode manual
# 智能审批(LLM 判断风险)
hermes config set approvals.mode smart
# 跳过所有审批
hermes config set approvals.mode off
hermes --yolo
密钥脱敏¶
默认开启,工具输出中的 API Key/Token 自动脱敏:
hermes config set security.redact_secrets true # 开启(默认)
hermes config set security.redact_secrets false # 关闭(仅调试用)
需要重启生效。
PII 脱敏¶
hermes config set privacy.redact_pii true # 开启
hermes config set privacy.redact_pii false # 关闭(默认)
技能写入保护¶
skills:
write_approval: true # 每次技能写入需审批
上下文文件安全¶
所有上下文文件经过威胁模式扫描,匹配提示注入的模式会被 [BLOCKED: ...] 替换。
22. 项目上下文文件¶
Hermes 在会话开始时自动读取项目上下文文件,注入系统提示。
文件优先级(首个匹配生效)¶
| 文件 | 发现规则 | 用途 |
|---|---|---|
.hermes.md / HERMES.md |
向上遍历到 git 根 | 分层项目规则 |
AGENTS.md / agents.md |
仅 cwd | 跨 Agent 通用指令 |
CLAUDE.md / claude.md |
仅 cwd | Claude 风格指令 |
.cursorrules |
仅 cwd | Cursor 迁移 |
SOUL.md(在$HERMES_HOME)独立加载,设置 Agent 身份。
大小限制¶
每个上下文文件上限 20,000 字符,超出部分 head+tail 截断。
禁用¶
hermes --ignore-rules # 跳过所有上下文文件注入
示例¶
# .hermes.md
# My Project
Hermes: 在此仓库中遵循以下规则。
## 构建
- 修改后必须运行 `make test`
- Python 使用 `uv run`,不用 `pip install`
## 风格
- 优先使用 `pathlib.Path`
- 生产代码不用 `print()`,用 `logger`
23. 故障排除¶
语音不工作¶
- 检查
stt.enabled: true - 安装 faster-whisper:
pip install faster-whisper - 重启:CLI 退出重进,Gateway 执行
/restart
工具不可用¶
hermes tools— 检查工具集是否启用- 检查
.env是否有必要的环境变量 /reset刷新会话
模型/Provider 问题¶
hermes doctor— 检查配置和依赖hermes auth— 重新认证- 检查
.env中的 API Key - Copilot 403:需要 Copilot 专用 OAuth(
hermes model→ GitHub Copilot)
变更不生效¶
- 工具/技能:
/reset开始新会话 - 配置: Gateway 执行
/restart,CLI 重启 - 代码: 重启进程
技能不显示¶
hermes skills list— 验证已安装hermes skills config— 检查平台启用- 手动加载:
/skill name
Gateway 问题¶
# 查看日志
grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20
# SSH 登出后 Gateway 停止
sudo loginctl enable-linger $USER
# 崩溃循环
systemctl --user reset-failed hermes-gateway
平台特定问题¶
| 问题 | 解决方案 |
|---|---|
| Discord Bot 无响应 | 启用 Message Content Intent |
| Slack 仅 DM 工作 | 订阅 message.channels 事件 |
| Windows Alt+Enter | 改用 Ctrl+Enter |
| Windows WinError 10106 | 检查 SYSTEMROOT 环境变量 |
| Windows 首次运行 400 | config.yaml 用 UTF-8 无 BOM 保存 |
辅助模型不工作¶
hermes config set auxiliary.vision.provider <provider>
hermes config set auxiliary.vision.model <model>
24. 附录:关键路径速查¶
| 查找内容 | 位置 |
|---|---|
| 配置选项 | hermes config edit 或在线文档 |
| 可用工具 | hermes tools list |
| Slash 命令 | /help 或 /commands |
| 技能目录 | hermes skills browse |
| Provider 设置 | hermes model |
| 平台设置 | hermes gateway setup |
| MCP 服务器 | hermes mcp list |
| Profile | hermes profile list |
| 定时任务 | hermes cron list |
| 记忆 | hermes memory status |
| 环境变量 | hermes config env-path |
| CLI 命令 | hermes --help |
| Gateway 日志 | ~/.hermes/logs/gateway.log |
| 会话文件 | hermes sessions browse |
| 源码 | ~/.hermes/hermes-agent/ |
文档版本: 2026-08-28 | 基于 Hermes Agent v2.2+
在线文档: https://hermes-agent.nousresearch.com/docs