收藏
返回版块

Hermes Agent 完整使用指南

Uncle Niu 社区管理员 2026年9月5日 12:22 114 次 0 条回复

Hermes Agent 完整使用指南

版本: v2.2+ | 作者: Nous Research
官方文档: https://hermes-agent.nousresearch.com/docs
源码仓库: https://github.com/NousResearch/hermes-agent


目录

  1. 简介
  2. 安装
  3. 快速开始
  4. CLI 命令参考
  5. 配置系统
  6. 模型与 Provider
  7. 工具集(Toolsets)
  8. Slash 命令
  9. Skills 技能系统
  10. Memory 持久记忆
  11. Session 会话管理
  12. Cron 定时任务
  13. MCP 集成
  14. Gateway 消息网关
  15. Webhook 订阅
  16. 多 Agent 委派与协作
  17. Profile 多环境隔离
  18. 语音功能(STT/TTS)
  19. 浏览器自动化
  20. Kanban 多任务协作看板
  21. 安全与隐私
  22. 项目上下文文件
  23. 故障排除
  24. 附录:关键路径速查

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 通过 WhatsApp Business API
Signal Signal Bot
Matrix Matrix 协议
Email 邮件收发
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. 故障排除

语音不工作

  1. 检查 stt.enabled: true
  2. 安装 faster-whisper:pip install faster-whisper
  3. 重启:CLI 退出重进,Gateway 执行 /restart

工具不可用

  1. hermes tools — 检查工具集是否启用
  2. 检查 .env 是否有必要的环境变量
  3. /reset 刷新会话

模型/Provider 问题

  1. hermes doctor — 检查配置和依赖
  2. hermes auth — 重新认证
  3. 检查 .env 中的 API Key
  4. Copilot 403:需要 Copilot 专用 OAuth(hermes model → GitHub Copilot)

变更不生效

  • 工具/技能: /reset 开始新会话
  • 配置: Gateway 执行 /restart,CLI 重启
  • 代码: 重启进程

技能不显示

  1. hermes skills list — 验证已安装
  2. hermes skills config — 检查平台启用
  3. 手动加载:/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

回复 (0)

暂无回复,快来抢沙发吧