Hermes Agent 使用技巧与技能全景报告

①Hermes 是什么

Hermes Agent 是 Nous Research 推出的个人 AI agent 框架。和单纯的聊天机器人不同，它强调的是「同一个大脑跑在多个入口」——同一个 agent 核心，既能跑命令行，也能接消息平台，还能开桌面窗口。

它能接的入口

它和普通 AI 助手的三个关键差别

• 会跨会话记东西——内置记忆（MEMORY.md / USER.md）+ 会话库（SQLite + FTS5 全文检索），能靠 session_search 把「上周五那个 bug」找回来
• 会自己沉淀技能——完成任务的过程可以固化成「技能」，下次自动按需加载。官方有 /learn 命令专门干这个
• 有真环境——真实的终端和浏览器，能跑命令、改文件、开网页，还能把任务派给子代理并行做

官方信息源

②五分钟上手

安装

# Linux / macOS / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows 原生 PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

安装器会自动处理依赖：uv、Python 3.11、Node.js、ripgrep、ffmpeg。前提只需 git，Linux 额外需要 curl 和 xz-utils。

可选跳过项：--skip-browser（不装 Chromium）、--skip-computer-use、--no-skills（不预置技能）。

配置：一条命令覆盖模型 + 工具

hermes setup --portal

这一步做一次 OAuth，同时搞定模型和四个工具网关（网页搜索、图片生成、TTS 语音、云浏览器），不用给每个工具单独配 key。只想换模型端点用 hermes model；要接机器人再跑 hermes gateway setup。

官方推荐的落地顺序

文档里有一条我很认同的规则：在一次干净的对话没跑通之前，不要叠加网关、定时任务、技能、语音。顺序是：

1. 装好 → hermes 能聊天
2. hermes -c 能恢复会话
3. 再配 hermes gateway setup 接机器人
4. 最后才是技能、定时任务、语音

更新与迁移

③核心概念对照表

这一节是最值得先看懂的——四个概念经常被混着用，但各管一摊，用错地方要么浪费 token，要么根本不起作用。

选哪个？两条判断口诀

• 会写进参考文档的 → 技能；会写在便利贴上的 → 记忆。
• 能表达成「说明 + 命令 + 既有工具」的 → 做成技能；必须每次精确执行、涉及鉴权流的 → 做成工具。需要改 agent 本身行为的 → 插件。

容量与成本的硬数字

④实用技巧 20 条

以下每条都标了来源：官方表示出自官方文档，第三方表示来自社区/博客，未标注的为我本机实测。

命令行效率（最容易立刻见效）

1. 多行输入不发送：Alt+Enter 或 Ctrl+J 插入换行。注意 Shift+Enter 只在 Kitty / foot / WezTerm / Ghostty 这类支持独立按键的终端有效，iTerm2、Alacritty、VS Code 终端需要先启用 Kitty 键盘协议。官方
2. 中断与重定向：Ctrl+C 按一次中断当前回复，然后输入新消息即可改方向；2 秒内双击 Ctrl+C 才是强制退出。官方
3. 直接粘截图：Ctrl+V 把剪贴板里的图片粘进对话，自动走视觉分析——报错弹窗、界面截图不用先存成文件再传。官方
4. Tab 补全命令和技能：输入 / 后按 Tab，列出全部内置命令和已装技能。官方
5. 会话恢复精确到标题：hermes -c 恢复上一次；hermes -r "标题" 按标题挑。恢复不上先看 hermes sessions list 确认 profile 对不对。官方
6. 工具输出太吵：/verbose 在 off → new → all → verbose 之间循环，调你想要的详细度。官方
7. 大批量粘贴不炸：自动检测多行粘贴，代码块不会被拆成好几条消息。官方

提示词与项目上下文

8. 别让 AI 猜谜。官方给的对比：说「修一下登录」不如说「修 api/handlers.py 第 47 行的 TypeError，因为 parse_body() 返回了 None」。给具体路径 + 错误堆栈，一次性到位。官方
9. 重复指令写进 AGENTS.md。顶层 AGENTS.md 在启动时自动加载；子目录的 AGENTS.md 由 subdirectory_hints.py 在工具调用期间延迟发现并注入，不会预先占系统提示。
10. Cursor 用户有彩蛋：Hermes 也读 .cursorrules 和 .cursor/rules/*.mdc，从工作目录自动加载——你在 Cursor 里写的规则文件不用重写一遍。官方
11. 人格和项目指令分开放：~/.hermes/SOUL.md 放实例级的持久人格（系统提示槽位 #1），AGENTS.md 放项目指令。但上下文文件要精简，因为每条消息都注入。

最被低估的功能：/learn

12. 把任何素材变成技能：官方 /learn 命令有四种用法——

    /learn the REST client in ~/projects/acme-sdk, focus on auth + pagination
    /learn https://docs.example.com/api/quickstart
    /learn how I just deployed the staging server    ← 把刚才的操作流程固化
    /learn ~/books/xxx.pdf                            ← 大素材会变成知识库型技能

    大来源会拆成「精简 SKILL.md + 索引 + references/ 每章一个提炼文件」的结构。官方

省钱与性能（这部分最实在）

13. 把辅助任务指向便宜模型。视觉识别、审批分类、上下文压缩、会话标题这些辅助任务默认走主模型；如果你主模型是贵的推理模型，成本会很显眼。用 hermes model → Configure auxiliary models 单独指。可配的槽位有 vision、title_generation、tts_audio_tags、compression、approval、triage_specifier、kanban_decomposer、profile_describer、delegation。官方
14. 干活派给便宜的子代理。delegation.model / delegation.provider 能让子代理跑便宜模型，主对话留在大模型上。这是官方在多模型分工上的推荐做法。官方
15. 反复切模型很贵。/model 每次切换都会重置提示缓存，切换后第一条消息按全价重读整段对话。长会话里优先 delegate 或开新会话，别反复切模型。官方
16. 顺手量一下固定开销：hermes prompt-size 离线拆解系统提示和工具 schema 的字节占用，用来定位「为什么还没说话就花了这么多」。官方
17. 控制推理强度：/reasoning none|minimal|low|medium|high|xhigh，或 /fast 切快速模式。官方

工程与运维

18. 危险操作隔离到容器：hermes config set terminal.backend docker。Docker 后端的隔离强度不低：--cap-drop ALL 只回加两个能力、no-new-privileges、--pids-limit 256、/tmp 512MB 限额 tmpfs，容器空闲 300 秒自动回收。官方
19. 需要记忆的连续操作用持久 shell：terminal.persistent_shell: true 能记住 cd 和 export；本地临时开是 export TERMINAL_LOCAL_PERSISTENT=true。官方
20. 把渲染结果当文件交付：在回复里附 [[as_document]]，图表、截图这类需要原文件的场景就不会被当成预览缩略图。官方

⑤技能体系全景

技能是 Hermes 最核心的扩展方式：把你反复要教它的流程，写成一份按需加载的说明书。

5.1 渐进披露：三级加载，token 花在刀刃上

这个设计解释了为什么技能的 description 必须精简：它是唯一常驻的部分，而且系统提示在第 57 个字符处就截断了。

5.2 每个技能自动变成斜杠命令

/k8s deploy the staging manifest          ← 带参数直接执行
/k8s                                       ← 只加载，让 agent 反问你
github-pr-workflow /test-driven-development fix issue #123   ← 多个技能叠加

只在 CLI 里列技能：hermes chat --toolsets skills -q "What skills do you have?"

5.3 内置技能（装了就有，13 个分类）

5.4 可选技能：534 个，22 大类

仓库里随附但默认不激活，需要显式安装：hermes skills install official/<分类>/<技能>

5.5 技能市场：Skills Hub 完整命令

统一入口是 hermes skills。支持多个来源：official（仓库可选技能）、skills.sh（Vercel 的公开目录）、well-known（站点自行发布的技能端点）、GitHub 直连（openai/skills、anthropics/skills、huggingface/skills 等）、以及直接给 URL。

标识的写法很灵活，都支持：

official/productivity/docx
openai/skills/k8s
skills-sh/vercel-labs/json-render/json-render-react
well-known:https://domain/.well-known/skills/<name>
https://example.com/SKILL.md          ← 直接给 URL，连它引用的附件一起装

信任分级（安装时会做安全扫描）

5.6 写一个技能：SKILL.md 规范

目录结构（~/.hermes/skills/<分类>/<名字>/）：

SKILL.md          ← 必需
references/       ← 分主题补充文档（推荐：细节都放这）
templates/        ← 输出模板
scripts/          ← 辅助脚本（别让模型每次现写解析器）
assets/ examples/

frontmatter 最小形态：

---
name: my-skill-name
description: Concise capability statement, under sixty chars.
version: 0.1.0
author: 真实姓名 (github-handle), Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [Short, Descriptive, Tags]
    related_skills: [other-skill]
---

正文推荐段落顺序：# 名字 Skill → 2-3 句简介 → ## When to Use（含「不要用在什么场景」）→ ## Prerequisites → ## How to Run → ## Quick Reference → ## Procedure（每步带可检查的完成判据）→ ## Pitfalls → ## Verification。

几条最硬的规则（官方 HARDLINE）

• description ≤ 60 字符，一句话，以句号结尾。不许用 powerful / comprehensive / seamless / advanced 这类营销词；不许重复技能名；触发词必须落在前 57 字符内
• author 必须人类在前：张三 (zhangsan), Hermes Agent。不能只写「Hermes Agent」——那等于把功劳给工具
• 正文里点名 Hermes 原生工具（terminal、read_file、patch、search_files…），不能写已被包装的 shell 命令（grep → search_files、cat → read_file、sed → patch）
• platforms 要按实际调用审计，不能照抄别的技能：用到 bash 管道/heredoc 就不能写 windows，用到 osascript 只能 macos
• related_skills 必须真实存在，不能指向计划中的技能或本地私有技能
• 技能是沉淀的规则，不是日志：不写 PR 号、日期、聊天记录摘录

5.7 本机实况（实测）

⑥模型与提供商

6.1 支持哪些模型来源

Hermes 的 provider 是插件化的，本机源码里就能看到 26 个 provider 插件。文档里列出的凭据环境变量（部分）：

6.2 不用 key 的 OAuth 方式

hermes model 里可选：OpenAI Codex（设备码）、Anthropic Claude、Nous Portal、MiniMax OAuth、xAI Grok OAuth、Qwen OAuth。也可以用 hermes auth add <provider> 直接加。

6.3 本地模型：能跑，但有门槛

社区经验：首次测试别让本地模型纯聊天，让它做工具型任务（列目录、抓网页、总结本地文档）才看得出真实能力。

6.4 成本相关的旋钮

⑦踩坑清单

这一节全部来自官方 FAQ 与本机实测，属于「不知道就会浪费一晚上」的类型。

上下文与缓存

• 上下文长度检测错，是最隐蔽的一类问题。模型实际窗口比 Hermes 认定的大，会造成没必要的压缩和「变笨」；比认定值小，会触发服务端静默截断或直接报超长。核对方式：启动行会打印 📊 Context limit: 128000 tokens，或看 /usage；显式修正用 model.context_length: 131072。
• 换模型 / /reload-mcp / 中途增删工具，都会让提示缓存失效，第一条消息按全价重读整段对话。长会话里优先 delegate 或开新会话。
• micro-compaction 省的是占用、花的是缓存。它每轮都破坏缓存前缀，对按 token 计费的云端模型不一定划算。开之前先算账。
• lean 尾巴模式下，历史工具结果会变成单行存根（带恢复指针的 stub）。如果某个结果里有你后面要用的细节，别假设原文还在上下文里，靠摘要锚点或 session_search 找回来。

安装与环境

• 别用 sudo 混装。官方安装器装到用户目录；混用 sudo 会造成 /usr/local/bin/hermes 和 ~/.local/bin/hermes 并存、调错解释器。经典症状是 ModuleNotFoundError: No module named 'dotenv'——说明你手动跑了仓库源码而不是 venv 启动器。
• ~/.bashrc 里放重活会拖垮每一次命令。Hermes 会起大量非交互 shell，慢初始化（nvm）、需要 TTY 的东西（tmux/read/菜单）、无条件 echo 都会造成超时或输出污染。解法是在顶部加守卫：case $- in *i*) ;; *) return;; esac。
• 无 sudo 的服务账号还要两件事：管理员跑一次 sudo npx playwright install-deps chromium；并且 sudo loginctl enable-linger <用户>，否则登出即停、开机不自启。
• 国内安装实测：仓库超 80MB，建议 git clone --depth 1；PyPI 常超时，改清华源 -i https://pypi.tuna.tsinghua.edu.cn/simple/。第三方

消息平台与附件

• Telegram 群里看不到消息 = Privacy Mode 默认开着，而且改完设置必须把 bot 移出群再加回来才会刷新。不想动全局隐私设置就把 bot 设成群管理员。
• Docker 后端里发附件会踩路径坑：附件是由宿主机的网关进程读取的，所以你必须把宿主目录挂进容器，写 MEDIA: 时用宿主可见路径。在容器里写 /workspace/report.txt 然后发 MEDIA:/workspace/... 是发不出去的。
• 无头 cron 脚本拿不到 Hermes 的密钥：子进程环境被净化，provider 凭据不会继承。必须显式 terminal.env_passthrough: [MY_TOKEN] 并在该 profile 的 .env 里定义。
• no-agent 看门狗的空 stdout 语义是「正常，别吵我」：stdout 为空就静默不发，非零退出或超时才告警。所以脚本里别随手 echo 无关内容，否则每次 tick 都会打扰你。

多 profile（社区反馈的开箱坑）

• 每个 profile 是完全隔离的：独立 config.yaml、.env、SOUL.md、state.db、sessions、skills、cron。用 hermes profile create coder 会生成 ~/.local/bin/coder 别名（等价 hermes -p coder）。第三方
• 坑一：各 profile 的网关端口必须手动改成不同值。
• 坑二：两个 profile 用同一个 bot token 时，系统会拒绝第二个网关启动。
• 坑三（官方 issue）：hermes update 只迁移当前活跃 profile 的 config schema，兄弟 profile 会静默漂移（#81797、#20438）。
• 坑四（官方 issue）：桌面端崩溃/重启会重置非默认 profile 的 config.yaml 并把 .env 整个删除（#45758，已修复）。

技能相关

• 新写的技能本会话看不到——技能加载器在会话启动时初始化，这是预期行为，不是 bug。
• 技能目录不是安全边界（见 5.7 的提醒）。

⑧社区与生态

官方渠道

中文资源

• HermesCN 中文社区教程（18 课，五阶段：成功与安全 → 日常方法 → 接入与自动化 → 扩展与协作 → 综合实战）
  hermescn.org/docs/tutorials
• 官方中文技巧页：/docs/zh-Hans/guides/tips
• 掘金有「多 agent 配置」（profile 当多 agent 用）、「企业微信对接」等实战文
• B 站有多个部署/接入教程视频
• CSDN 有排查三层法的长文：依赖层（hermes: command not found 查 PATH）→ 网络层（查 GitHub/API 连通与镜像）→ 权限层；并建议用 hermes doctor 自诊断、升级后跑 hermes config migrate

社区玩法（值得借鉴的两个）

• 用 profile 当多 agent：一个 profile 就是一套完全隔离的环境，可以给不同「员工」配不同价位的模型。有作者直接让主 agent 用中文引导创建 profile 并填 AGENTS.md/SOUL.md。第三方
• Oracle 免费层 + 自建聚合 API：有人用 Oracle Cloud 免费层 24/7 跑 Hermes，配自建的 OpenAI 兼容聚合层（自动在 Gemini/Groq/Mistral/DeepInfra 之间切换免费额度）+ WhatsApp 桥。评论区还有用 Obsidian 库当多个 agent 的共享第二大脑。第三方（注意：Oracle 免费层有被回收的风险）

和其他框架的对比

有一篇 Towards AI 的实测（2026-05-18，第三方）称同批 18 个任务 Hermes 胜 14 个，输的 4 个全是纯编码场景；作者认为它的胜负手是 SQLite + FTS5 的会话库能记住「上周五那个 bug」。社区多数人的结论是两个一起跑，而不是二选一。

⑨存疑与未验证

这份报告坚持标注来源，也如实列出没验证到的部分，避免把二手说法当事实。

• GitHub 星标数字多个来源不一致（248.1k / 210.9k / 242.5k / 135k 等），无法核实，以仓库页直读为准，本报告未采用。
• Reddit 大部分帖子抓不到正文（工具被拦），只有摘要级信息；仅一条自托管帖抓到了正文。
• 官方 X/Twitter 与 Discord 公告无法直接访问，「用 Claude SDK 让 Claude Code 订阅可用于 Hermes」这类消息只有第三方转述。
• 技能市场的量化数字（如「收录 90,700 个技能、来自 11 个 registry」「技能索引约 3000 token」）来自第三方站点，官方文档未给出，未逐一验证。
• 中文搜索路径基本空缺：本次未获取到可引用的知乎条目 URL。
• B 站/YouTube 视频没有实际播放，仅依据标题与简介。
• 本次精读的是官方文档 230 页里的 25 页（覆盖安装、配置、技能、记忆、工具、cron、委派、插件、MCP、CLI、压缩、FAQ、技巧、桌面、安全），其余约 200 页（各平台单独页、开发者内部实现页）未逐字精读，本报告未对其内容做推测。