汉兴人工智能OPEN CAIO启动企业 AI 诊断
企业 AI 转型
产品体系本地部署业务解决方案企业 AI 转型
AGI 实验室实验室首页研究成果工具入门
生态计划蓝血菁英城市合作伙伴
关于汉兴
启动企业 AI 诊断

MANUAL 04 · HERMES

从零搭起一个能干活的助手

两册教材。基础篇 14 章把一个 Agent 从安装带到能跑，进阶篇 8 个模块讲自定义工具、定时工作流、安全审批与多 Agent 调度。四本里唯一按教材体例写的一套。

打开手册回到四本总览
出品
Nous Research · 两册教材
手册
基础 14 章，进阶 8 个模块
自测
8 项上手检查清单，勾完即算合格
适合
想系统学一遍 Agent 全流程的人

WHAT IT SOLVES

先懂结构，再挑工具

另外三本各自绑着一个具体工具，这两册讲的是它们共同的那套结构。

Hermes 这两册更像一门课：它把 Agent 的组成部分逐个拆开——模型与供应商、工具系统、技能、记忆、身份、网关，每一块都讲清楚它是什么、配在哪里、出问题怎么查。学完再去看别的工具，会发现它们只是同一套结构的不同实现，迁移成本因此低很多。

基础篇交付一个可运行的最小系统：装好、配第一个 API Key、开始对话、装技能、给它记忆、换一个身份、接上消息平台。每一步都有对应的命令和配置文件位置，不是概念介绍。

进阶篇处理的是「交给别人用」之后才会遇到的问题：写自己的工具、用 Cron 排定时任务、把人格与约束写成 SOUL.md、给写入操作加审批链、跑安全扫描、用 Delegation 让子 Agent 分工，以及用 Computer Use 直接操作桌面。这一册假设你已经有一个跑得起来的 Agent。

WHAT IT DOES

两册合起来讲透的八件事

基础篇给结构与最小可用，进阶篇给交付给别人用之前要补的东西。

TOOLS

工具系统

查看、启停与配置工具，手册给了一张核心工具矩阵，说明每个工具管什么。

SKILLS

技能 Skills

安装、管理与理解技能的运行方式，进阶篇教你按 Schema 加 Handler 写自己的。

MEMORY

记忆系统

两类记忆文件，讲清各自何时被读到、怎么管理、什么时候该手动清理。

IDENTITY

多身份 Profile

一台机器上多个身份，各自独立的配置、记忆与技能，进阶篇再讲分发与隔离。

PERSONA

SOUL.md

把人格与约束写成文件。进阶篇给了 System Prompt 的三层架构与约束写法差异。

GATEWAY

网关与平台

接入消息平台，基础篇有微信接入示例，进阶篇讲多平台并发与自定义平台接入。

SAFETY

安全与合规

写入审批链、自动安全扫描、沙箱执行，外加一份数据隐私检查清单。

ORCHESTRATION

多 Agent 调度

Delegation 调度架构、子 Agent 选型策略与看板，用于把长任务拆给多个 Agent。

THE COURSE

从装好，到能带团队用

三级各有一套实验、一件可见产物和一张验收清单。做不完上一级的清单，就不要开始下一级。

STARTER2–3 小时

入门上手

装好 Hermes，配好第一个模型供应商，在终端里跑通一次会真正调用工具的对话，并看懂它每一步在做什么。

前置**这一本的起点和另外三本不一样，如实写在前面**：Hermes 是终端优先的工具，官方文档默认读者已经会开终端、会敲命令、看得懂报错，正文直接从安装讲起，没有零基础入口。所以进这一级之前你需要：能熟练使用 macOS / Linux / WSL2 的终端；知道 ~/.xxx 这类隐藏目录是什么；能读懂一段 Python 报错的大意（不要求会写）。环境侧只有 Git 是硬前置，安装脚本会自行准备 Python 3.11（经 uv）、Node.js、ripgrep 与 ffmpeg；Linux 另需 curl 与 xz-utils。另外要准备一个模型供应商的凭据（Nous Portal / OpenRouter / OpenAI / Anthropic 等）。完全没碰过命令行的同事，建议先从 OpenClaw 那本入门，再回来读这本。

跟做实验

  1. 01安装。Linux / macOS / WSL2 / Termux 执行 curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash；Windows PowerShell 执行 iex (irm https://hermes-agent.nousresearch.com/install.ps1)；想要图形界面的可以从官网下载桌面安装包。
  2. 02重载 shell：source ~/.zshrc（或 ~/.bashrc），让 hermes 命令进入 PATH。
  3. 03体检：hermes doctor。它会把缺什么、怎么补一条条列出来，先把它报的问题清干净。
  4. 04配模型：hermes model 走交互式选择供应商与模型；用 Nous Portal 的话可以直接 hermes setup --portal 一步配完。
  5. 05第一次对话：直接敲 hermes 进经典 CLI，或 hermes --tui 进 TUI（官方推荐）。先让它做最小的事——「列出当前目录」「读一下 README.md 并用三句话概括」。
  6. 06看清它怎么动手：观察它调用了 terminal、read_file 这些工具，而不是凭空作答。用 /tools 看当前可用工具，/help 看会话内命令。
  7. 07确认状态与落盘位置：hermes status 看模型、凭据、平台状态；hermes config path 看配置文件在哪。确认密钥进的是 ~/.hermes/.env，其余设置进 ~/.hermes/config.yaml。
  8. 08收尾：hermes --continue 恢复刚才那次会话，确认历史还在。

做完你手上会多出一个装好并通过 hermes doctor 的 Hermes、一份配好模型的 ~/.hermes/config.yaml、一次真的调用了工具的会话记录，以及一句你自己能说清楚的话：这次任务里它调了哪几个工具、为什么。

验收清单

  • hermes doctor 输出里没有未解决的缺失项。
  • hermes status 能看到当前模型与凭据状态正常。
  • 一次对话里它至少调用了一个工具（terminal 或 read_file），而不是只输出文字。
  • 你能指出 API Key 存在 ~/.hermes/.env、其余配置在 ~/.hermes/config.yaml。
  • hermes --continue 能把上一次会话接回来。
  • 能说出 Agent / Tool / Skill / Memory / Gateway 这五个词各自管什么。

常见错误

装完 hermes 命令找不到
shell 没重载。source ~/.zshrc 或 ~/.bashrc 后重试，仍不行就开一个新终端窗口。
它只会聊天，不调用工具
两种原因：工具集没启用，或者你选的模型不支持函数调用。先 hermes tools 看工具集状态，再确认模型支持 function calling。
模型调用报 401
凭据没配好或过期。hermes status 看凭据状态，hermes auth status / hermes auth add 重新设置。注意官方的凭据命令是 hermes auth，不是 hermes login。
装的时候卡在依赖上
官方安装脚本会自己准备 Python 3.11、Node.js、ripgrep 与 ffmpeg；Linux 上先确保有 curl 与 xz-utils，桌面版另需 g++ 或 build-essential。硬前置只有 Git。
一上来就让它做一件很大的事
第一次对话的目的是看清它的工作方式，不是验证它多能干。用最小的任务观察它调了什么工具、在哪一步停下来问你。

安全Hermes 的 terminal 与文件工具默认拥有你这个用户的完整权限。入门阶段的安全底线是三条：第一，先在一个无关紧要的目录里练手，不要一上来就让它进你的正式项目；第二，不要用 --yolo（它会跳过审批提示），也不要因为审批弹得烦就关掉审批；第三，密钥只写 ~/.hermes/.env，永远不要贴进对话、截图或代码仓库。官方还内置了一份硬性拦截清单，rm -rf /、fork 炸弹、格式化磁盘这类命令即使开了 --yolo 也不会执行——但这是最后一道网，不是你可以偷懒的理由。

ADVANCED6–8 小时，建议分两天

独立交付

把通用 Agent 调成「你的」Agent：写 SOUL.md 定人格、用记忆让它跨会话认识你、按任务装技能、开审批与沙箱，并用 Profile 把不同用途彻底隔开，完成一次真实任务的端到端交付。

前置已完成入门级，且能读懂 YAML（config.yaml 全靠它）。手上有一个每周重复几次的真实任务作为练习对象。这一级还不要求写 Python，但要能看懂别人写的技能里在做什么。

跟做实验

  1. 01写人格：编辑 ~/.hermes/SOUL.md（自定义家目录则是 $HERMES_HOME/SOUL.md）。它占系统提示的第一格，只从 HERMES_HOME 读，不会从当前工作目录读。写语气、直率程度、遇到不确定怎么办这类稳定的东西，改完下一次会话生效。
  2. 02让它认识你：对话里直接说「记住我……」，Agent 会用 memory 工具写入。两个文件分工明确——~/.hermes/memories/MEMORY.md 是它自己的笔记（上限 2200 字符），~/.hermes/memories/USER.md 是对你的了解（上限 1375 字符）。写满会报错而不是静默丢弃，这时要合并或删旧条目。
  3. 03理解记忆为什么「不立刻生效」：记忆在会话开始时作为冻结快照注入系统提示，为的是保住前缀缓存。会话中写入会立刻落盘，但要等下一次会话才出现在提示里。想立刻看到效果就 /reset 或重开会话。
  4. 04配工具集：hermes tools 交互式管理，也可以 hermes chat --toolsets "web,terminal" 临时指定。常用工具集有 web、search、terminal、file、browser、vision、memory、code_execution、delegation、cronjob 等。原则同样是从小往大加。
  5. 05装技能：hermes skills browse 浏览，hermes skills search <关键词> 搜索，hermes skills install <标识> 安装（带安全扫描），hermes skills list 查看。技能装在 ~/.hermes/skills/，用 /技能名 [指令] 调用，也可以叠着用。
  6. 06让它自己长技能：Hermes 会在完成复杂任务（5 次以上工具调用）、踩过错又解决、或发现了非平凡流程之后，用 skill_manage 自建技能。想让每次改动都过人工审核，设 skills.write_approval: true；想扫描 Agent 自建技能里的危险模式，开 skills.guard_agent_created: true。
  7. 07上安全：审批默认是 smart 档（用一个辅助模型评估风险，低风险自动放行、拿不准就升级问人），也可以切 manual（每条危险命令都问）或 off。要更硬的隔离就把执行搬进容器：hermes config set terminal.backend docker。注意 docker / modal / daytona 后端会跳过逐条审批，因为容器本身就是边界。
  8. 08分身：hermes profile create <名字> 建一个独立实例，它有自己的配置、记忆、会话与技能，目录在 ~/.hermes/profiles/<名字>/（默认 profile 就是 ~/.hermes 本身）。用 hermes -p <名字> <任意子命令> 或 create 时生成的别名切换。
  9. 09用第 0 步选的真实任务走一遍完整流程，把反复交代的那几句话补进 SOUL.md，把摸索出来的流程沉淀成一个技能。

做完你手上会多出一份写完的 SOUL.md、一对有真实内容的 MEMORY.md / USER.md、一个按任务裁剪过的工具集配置、至少一个自己装或自己沉淀的技能、一个用于特定用途的独立 Profile，以及一次从头到尾由 Hermes 完成的真实任务记录。

验收清单

  • 改完 SOUL.md 后新开会话，说话风格明显跟着变了。
  • /reset 或重开会话后，它还记得你让它记住的偏好。
  • MEMORY.md 与 USER.md 的内容你逐条读过，没有过期或错误的条目。
  • 工具集是按任务裁剪过的，你能说清为什么留下这几个、去掉那几个。
  • 至少一个技能可以用 /技能名 调起来并真的改变了它的做法。
  • 危险命令会先走审批：能演示一次「它请求执行，你拒绝，它停下来」。
  • 至少有两个 Profile，各自的记忆与会话互不可见。
  • 同一个真实任务，第二次执行比第一次更省事——因为规则和技能已经沉淀下来了。

常见错误

改了 MEMORY.md，当前会话里没反应
记忆是会话开始时冻结注入的，为的是保住前缀缓存。写入立刻落盘，但要下一次会话才进提示。/reset 或重开会话即可。
记忆写不进去，工具报错
MEMORY.md 2200 字符、USER.md 1375 字符是硬上限，满了会直接报错而不是悄悄丢。让它先合并或删除旧条目，或者接一个外部记忆供应商。
SOUL.md 写了一堆「建议」，它不照做
建议式写法很弱。把「最好简洁一点」改成可判定的约束：「每条回复不超过 3 句话，超了先删减再发送」。
两个终端同时用同一个 Profile
两个进程都会自动写记忆，并在会话开始时各自加载对方的写入，状态会越滚越乱。Profile 存在的意义就是防这件事——一个进程一个 Profile；确实要共享记忆就接外部记忆供应商。
切到 docker 后端之后，审批提示没了
这是设计如此：docker / modal / daytona 后端把容器当成隔离边界，逐条审批被跳过。要保留逐条审批就用 local 或 ssh 后端。
把密钥写进 config.yaml
规矩是密钥进 .env，其余设置进 config.yaml。而且 Hermes 会硬拦对 .env、auth.json、~/.ssh/、~/.aws/ 这类路径的写入——它自己都不允许覆盖的东西，你更不该往别处抄。

安全这一级开始真正把权力交出去，所以顺序不能颠倒：先写清 SOUL.md 的边界，再决定开哪些工具集，再确认审批档位，最后才让它碰你的正式项目。三条具体的线：第一，--yolo 和把审批切到 off 是同一件事的两种说法，团队环境里不要用；第二，装第三方技能等于在本机跑别人的代码，安装时的扫描是提示不是保证，来源不明的不要装；第三，Hermes 的 web 工具默认会拦内网、回环与云元数据地址（防 SSRF），只有在你确实需要访问内网、且清楚后果时才设 security.allow_private_urls: true。

MASTERY12–16 小时，建议按周推进

精通治理

从使用者变成构建者：写自己的工具、把重复工作交给定时任务、用子 Agent 拆分长任务、接入 MCP 生态、把 Profile 当代码分发，并建立起备份、升级、日志与故障定位的一整套运维习惯。

前置已完成进阶级并持续在用。这一级要求你能写 Python（自定义工具就是 Python 代码加一份 plugin.yaml），会看 JSON Schema，理解容器与环境变量隔离。有一台可以长期运行的机器用于网关与定时任务。

跟做实验

  1. 01写第一个自定义工具：在 ~/.hermes/plugins/ 下建一个目录，放 plugin.yaml 与 Python 代码。启动 Hermes 后你的工具会和内置工具一起出现在模型可调用列表里。官方明确建议走插件路线，而不是改 Hermes 核心。写 schema 时记住 description 是写给模型看的，说清「什么时候用」比说清「怎么实现」重要。
  2. 02上定时任务：hermes cron create "0 8 * * *" "汇总昨天的数据并给出异常提示" [--skill <名>] [--workdir <路径>]，用 hermes cron list|status|run|edit|pause|resume|remove 管理，hermes cron runs [job-id] --limit 20 看历史。投递目标支持 origin、local 以及 telegram / discord / slack / whatsapp / signal / matrix / email / sms / 飞书 / 企业微信 / 微信等，可以写成 telegram:123456 这种精确目标或 "telegram,discord" 这种列表。注意：cron 执行里禁用了 cron 管理工具，防止任务自己再排任务造成失控。
  3. 03拆长任务：开启并使用 delegate_task。参数里 goal 是目标、context 是背景（子 Agent 从零上下文起步，这一项最容易写漏）、tasks 可批量并行、role 取 leaf（默认，不能再委派）或 orchestrator（可再派工），max_iterations 每个子 Agent 默认 50 轮。并发默认最多 3 个子 Agent，用 delegation.max_concurrent_children 或同名环境变量调整；嵌套深度由 max_spawn_depth 控制（默认 1，即扁平委派）。
  4. 04知道委派的边界：leaf 子 Agent 不能调用 delegate_task、clarify、memory、send_message、cronjob——也就是说它不会替你改记忆、不会替你发消息、不会自己排任务。需要跨进程存活的长任务，用 cronjob (action=create) 排一个独立运行，而不是靠父会话一直等。
  5. 05接 MCP：作为 Client，hermes mcp catalog 看目录、hermes mcp install <name> 装、hermes mcp add <name> --preset <preset> 加自定义服务、hermes mcp configure <name> 挑要暴露的工具、hermes mcp login <server> 走 OAuth、hermes mcp test 测连通，会话里 /reload-mcp 重载。作为 Server，hermes mcp serve 起一个 stdio MCP 服务，让 Claude Code、Cursor 等客户端调用 Hermes 的工具链。
  6. 06多 Agent 协作看板：hermes kanban 提供跨 Profile 的共享任务板（init / boards / create / assign / claim / dispatch / tail 等）。它和 delegation 的区别是异步：任务丢进板子，谁空谁接，而不是父 Agent 同步等待。
  7. 07把 Profile 当代码：hermes profile export / import 打包分发，hermes profile install / update 从远端安装与更新。团队里建一个基线 Profile（通用技能 + 安全配置），成员各自派生再定制自己的 SOUL.md。
  8. 08加固安全：hermes security audit 做供应链漏洞扫描（--json、--fail-on 可接 CI）；把执行搬进容器（terminal.backend 选 docker / ssh / modal / daytona / vercel_sandbox / singularity）；需要限制出网就用 hermes egress 装并启用出网防火墙；密钥想交给外部管理器就用 hermes secrets bitwarden。另外了解一下 HERMES_WRITE_SAFE_ROOT——它把写入限制在指定目录前缀下，官方 Docker 镜像里默认就设了。
  9. 09备份、升级与排错闭环：hermes backup -o <路径> 打包、hermes import -f <包> 恢复；hermes update --check 看有没有新版本，hermes update 升级（默认会备份，--no-backup 才跳过）。排错固定三板斧：hermes doctor → hermes logs --level ERROR（还可按 agent / errors / gateway 分流）→ hermes prompt-size 看系统提示各段占了多少。要向别人求助就 hermes debug share 导出诊断包（默认会脱敏）。

做完你手上会多出至少一个自己写的、在真实任务里被调用过的自定义工具；一条稳定运行的定时任务并有投递记录；一次用子 Agent 并行完成的多步任务；一个接进来的 MCP Server 或一次 Hermes 作为 MCP Server 被其他客户端调用的记录；一个可分发的基线 Profile；以及一页运维手册（怎么备份、怎么升级、出事先跑哪三条命令）。

验收清单

  • 自定义工具能被模型自己选中调用，不需要你在提示词里手把手指定。
  • 定时任务连续三天按时触发，hermes cron runs 里有对应记录，投递也确实到达了目标平台。
  • 跑过一次并行委派，能说清 context 里写了什么、为什么子 Agent 靠它就能独立干活。
  • 能解释 leaf 子 Agent 不能做哪五件事，以及为什么这个限制是合理的。
  • 至少接通一个 MCP Server，hermes mcp list 里能看到并测试通过。
  • hermes security audit 跑过并处理了报出的问题；生产用途的执行已进容器。
  • 备份做过并且真的用 hermes import 恢复过一次，不是只生成了压缩包。
  • 跑过一次 hermes update，升级前后都能正常对话，出问题知道怎么回退。
  • hermes prompt-size 的输出你看得懂：能指出是 SOUL、技能索引还是记忆占了大头。

常见错误

自定义工具写好了，模型从来不用它
schema 的 description 是写给模型看的说明书。把它写成「当用户提到 X / Y / Z 时用这个工具」这类触发条件，而不是描述内部实现。
子 Agent 干出来的东西完全跑偏
context 写漏了。子 Agent 从零对话历史起步，父会话里所有心照不宣的背景它一无所知，必须显式写进 context。
委派任务里想让子 Agent 顺手记一笔或发个消息
做不到，也不该做。leaf 子 Agent 被明确禁止调用 memory、send_message、clarify、cronjob 与 delegate_task。要跨进程存活的长任务改用 cronjob (action=create) 排一个独立运行。
定时任务里让 Agent 再排一个定时任务
cron 执行中 cron 管理工具是被禁用的，防的就是排程失控。需要多阶段就在外面排多条任务，用状态文件串起来。
回复突然中断，看不出原因
先看 agent.max_turns 是不是到顶（默认 500）。再 hermes logs --level ERROR 找具体堆栈。
上下文老是爆
hermes prompt-size 先看是谁占的：SOUL 太长、技能索引太大还是记忆塞满了。另外 compression.enabled 默认开启，compression.threshold 默认在 0.50，即达到上下文上限一半时自动压缩——先确认它有没有被关掉。
把密钥当环境变量传给工具，结果读不到
execute_code 与 terminal 会主动剥掉含 KEY / TOKEN / SECRET / PASSWORD 等字样的环境变量。技能要合法透传必须在 required_environment_variables 里声明。这是保护，不是 bug。

安全构建者阶段的安全责任比使用者大一个量级，因为你写的工具会成为模型的新能力。四条：第一，自定义工具要自己做输入校验和错误处理，不要把用户输入直接拼进 shell 命令；第二，生产用途一律把执行放进容器（terminal.backend 设 docker 或远程沙箱），需要限制出网就再叠一层 hermes egress；第三，把 hermes security audit 接进 CI（--fail-on 可以让它在发现问题时直接失败），别等出事才扫；第四，分发 Profile 之前先自己过一遍——里面的 SOUL.md、技能和配置会原样跑在同事的机器上，你分发的是一段可执行的判断，不是一份文档。

SYLLABUS

十六节，四本课程同一套骨架

小节顺序就是学习顺序。四本用同一份目录，读完一本，第二本可以直接跳到你要的那一节。

  1. 01

    这是什么，适合谁

    Hermes Agent 是 Nous Research 开源（MIT）的 AI Agent。它的定位官方写得很直白：一个会随着你使用而变得更强的自主 Agent——完成复杂任务后会把流程沉淀成技能，跨会话保留对你的了解，下次遇到类似的活直接调用。 它是终端优先的：主界面是 CLI 与 TUI，配好网关之后同一个 Agent 才出现在消息平台上。这和 OpenClaw「先有聊天窗口，再谈其他」的顺序正好相反，也是两者最本质的区别。 适合已经在终端里工作的人：开发者、数据分析、需要把重复流程自动化的运营。不适合完全没碰过命令行的同事——官方文档不提供零基础入口，正文直接从安装开始。

  2. 02

    安装前检查

    这一节要特别说清楚一件事：**Hermes 的读者起点和另外三本不同**。Claude Code、Codex CLI、OpenClaw 的手册都另设零基础入口，Hermes 没有——官方文档默认你已经会用终端，正文从安装命令开始。我们不为了四本齐整而假装它零基础。 所以装之前先诚实评估：你会开终端、会 cd、会看懂一段报错的大意吗？不会的话先去读 OpenClaw 那本，把这三关过掉再回来。 环境侧反而简单：官方文档说硬前置只有 Git，安装脚本会自己准备 Python 3.11（经 uv，不需要 sudo）、Node.js、ripgrep 与 ffmpeg。支持 Linux、macOS、WSL2、Windows、Android（Termux）与 NixOS；Linux 另需 curl 与 xz-utils，桌面版另需 g++ 或 build-essential。

  3. 03

    第一次成功运行

    目标：在终端里完成一次真正调用了工具的对话。判据不是「它回答了」，而是「它先去看了，再回答」。

  4. 04

    入门项目

    入门项目选「让它替你完成一件你原本要手动做十分钟的小事」，范围限定在一个无关紧要的目录里。典型的三个：把一个目录的文件按类型整理成清单；读一份长文档产出摘要与行动项；查一件需要上网确认的事并给出出处。 重点不是结果多漂亮，而是你要盯着它每一步：它先调了什么工具？在哪一步停下来问你？哪一步它自作主张了？这些观察是你后面写 SOUL.md 约束的原始素材。

  5. 05

    项目规则与上下文

    Hermes 的规则主要落在 ~/.hermes/SOUL.md（自定义家目录则是 $HERMES_HOME/SOUL.md）。它占系统提示的第一格，是 Agent 的主身份，会替换掉内置的默认人格；只从 HERMES_HOME 读取，不会从当前工作目录读，所以不同项目共用同一份人格，项目差异靠 Profile 隔开。 注入前会先过一遍安全扫描与截断：官方对上下文文件做提示注入、隐藏凭据与不可见 Unicode 的检查。文件不存在时 Hermes 会自建一份起步模板，已有文件永远不会被覆盖；文件为空或读不出来时回落到内置默认身份。 写法上只有一条要记住：约束式远强于建议式。「最好简洁一点」是建议，「每条回复不超过 3 句话，超了先删减再发送」是约束。

  6. 06

    权限、安全与审批

    Hermes 的安全是纵深防御，官方文档分了好几层，值得逐层记住。 命令审批三档：smart（默认，用辅助模型评估风险，低风险自动放行、拿不准的升级问人）、manual（每条危险命令都问）、off（全关）。--yolo 会绕过审批提示，可以从 CLI 参数、/yolo 斜杠命令或环境变量开启，开着的时候界面会持续显示警告。此外还有一份硬性拦截清单：rm -rf /、fork 炸弹、格式化磁盘这类命令即使开了 yolo 也不会执行。 写入保护是硬拦：~/.ssh/、~/.aws/、/etc/sudoers、Hermes 自己的 .env / auth.json / mcp-tokens/、项目里的 .env / .env.local / .envrc 都不能被覆盖。另有 HERMES_WRITE_SAFE_ROOT 环境变量把写入限制在某个目录前缀下，官方 Docker 镜像默认设了它。 执行隔离看后端：local 与 ssh 会走审批检查；docker、modal、daytona 把容器当边界，跳过逐条审批。Docker 容器以 --cap-drop ALL、--security-opt no-new-privileges 等加固参数运行并限制 CPU、内存、磁盘与进程数。 密钥保护：execute_code 与 terminal 会剥掉含 KEY / TOKEN / SECRET / PASSWORD 等字样的环境变量，技能要合法透传得在 required_environment_variables 里声明；MCP 子进程默认只透传 PATH、HOME、USER 这类安全变量；MCP 工具的报错会在返回给模型前脱敏。 网络侧默认拦截 SSRF：私有网段、回环、云元数据地址与链路本地地址都会被 web 工具拒绝，确需内网访问才设 security.allow_private_urls: true。

  7. 07

    文件、工具与外部系统

    内置工具按类别划分：网络（web_search、web_extract、x_search）、终端与文件（terminal、process、read_file、patch）、浏览器（browser_navigate、browser_snapshot、browser_vision）、媒体（vision_analyze、image_generate、text_to_speech）、编排（todo、clarify、execute_code、delegate_task）、记忆与检索（memory、session_search）、自动化（cronjob），以及各类集成（Home Assistant、MCP 服务器工具）。 工具集是开关的粒度：web、search、terminal、file、browser、vision、image_gen、skills、tts、todo、memory、session_search、cronjob、code_execution、delegation、clarify、homeassistant、messaging、spotify、discord、debugging、safe 等，可以按平台分别启停（官方给了 hermes-cli、hermes-telegram 这类平台预设）。 外部系统走两条路：MCP 把外部工具接进来，插件把你自己的代码变成工具。

  8. 08

    记忆与长期任务

    记忆是两个文件，都在 ~/.hermes/memories/：MEMORY.md 是 Agent 自己的笔记（环境事实、踩过的坑、学到的教训），上限 2200 字符；USER.md 是对你的了解（偏好、沟通风格），上限 1375 字符。 有一条设计必须理解，否则会一直觉得「记忆没生效」：两个文件在会话开始时作为**冻结快照**注入系统提示，为的是保住 LLM 的前缀缓存。会话中的写入立刻落盘，但要等下一次会话才出现在提示里。 memory 工具只有 add / replace / remove 三个动作，没有 read——因为内容本来就已经注入。写满时工具会明确报错而不是静默丢弃，这时必须先合并或删旧条目。需要更大容量或语义检索、知识图谱，可以接外部记忆供应商（官方提供 Honcho、Mem0 等多个插件）。 长期任务不要靠让会话一直挂着。跨进程存活的活交给 cron（下一节），子任务并行交给 delegation（第 09 节）。

  9. 09

    多 Agent 协作

    Hermes 的多 Agent 有三种形态，别混为一谈。 一是 **Profile**：同一份安装下的多个隔离实例，各自有配置、记忆、会话、技能与网关服务，目录在 ~/.hermes/profiles/<名字>/（默认 profile 就是 ~/.hermes 本身）。这是「分身」，不是「协作」。硬规矩：绝不要让两个进程指向同一个 Profile——两边都会自动写记忆，又各自在会话开始时加载对方的写入，状态会滚雪球式损坏。 二是 **Delegation**：父 Agent 用 delegate_task 派子 Agent 干独立子任务，同步等待汇总。参数有 goal、context（子 Agent 零上下文起步，这一项最关键）、tasks（批量并行）、role（leaf 默认不能再委派 / orchestrator 可再派工）、max_iterations（默认 50）。默认并发上限 3，由 delegation.max_concurrent_children 控制；嵌套深度由 max_spawn_depth 控制（默认 1）。子 Agent 继承父 Agent 已启用的工具集，不能给自己开新能力。leaf 子 Agent 被禁止调用 delegate_task、clarify、memory、send_message 与 cronjob。 三是 **Kanban**：跨 Profile 的共享任务板，异步调度——任务丢进板子，哪个 Agent 空闲哪个接。和 delegation 的同步等待正好互补。

  10. 10

    自动化和团队使用

    定时任务用 hermes cron：create "<schedule>" "<prompt>" 建，还可以带 --skill <名> 指定用哪个技能、--workdir <路径> 指定工作目录；list / status / edit / pause / resume / run / remove / tick 管理，runs [job-id] --limit 20（别名 history）看运行历史。投递目标很丰富：origin（回到发起的地方）、local，以及 telegram、discord、slack、whatsapp、signal、matrix、mattermost、email、sms、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles、qqbot、all，支持 telegram:123456 这样的精确目标和 "telegram,discord" 这样的列表。 团队使用靠网关：一个后台进程连上所有已配置的平台，处理会话、跑 cron、投递语音消息。官方文档列出的平台包括 Telegram、Discord、Slack、Google Chat、WhatsApp（含 Cloud API）、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、钉钉、飞书/Lark、企业微信、微信、BlueBubbles（iMessage）、QQ、腾讯元宝、Microsoft Teams、LINE、ntfy、SimpleX、IRC、Webhooks 等。 访问控制走环境变量：各平台各有 *_ALLOWED_USERS（如 TELEGRAM_ALLOWED_USERS），另有跨平台的 GATEWAY_ALLOWED_USERS；GATEWAY_ALLOW_ALL_USERS=true 官方明确不推荐用于有终端权限的 bot。更省事的做法是 DM 配对：陌生人首次私聊拿到一次性配对码，你用 hermes pairing approve 批准。

  11. 11

    调试与高频故障

    排错顺序固定：hermes doctor → hermes logs → hermes prompt-size。官方的说法是绝大多数问题在 doctor 的输出里就有答案，剩下的靠日志和提示词体积定位。

  12. 12

    生产使用边界

    Hermes 的三条边界很清楚。 第一，它是终端优先的开发者工具，不是给不懂命令行的同事直接用的产品。可以通过网关把它接到聊天平台让同事用，但配置、排错、升级仍然需要一个懂终端的人负责。团队里没有这样一个人，就不要上生产。 第二，默认执行环境是你的本机，权限等同于你这个用户。上生产必须把执行搬进容器或远程沙箱（terminal.backend 设 docker / ssh / modal / daytona / vercel_sandbox / singularity），需要限制出网再叠 hermes egress。用 local 后端跑生产任务，等于把一个自主 Agent 直接放在你的主目录里。 第三，它的自学习特性是双刃剑：Agent 会自建技能、自写记忆，这让它越用越顺手，也意味着它的行为会随时间漂移。交给别人用之前，把 skills.write_approval 与 memory.write_approval 打开，并把 skills.guard_agent_created 也考虑上——你要能回答「上周它给自己加了什么本事」。 还有一条不是边界但要提前算清楚：官方文档更新很快，命令与配置项会变。任何写死了命令名的内部文档，都要标上「按哪一版核对的」，否则半年后没人知道它还准不准。

  13. 13

    入门项目验收

    入门只验一件事：它在你的机器上活着，并且会动手，不只是会说话。

  14. 14

    进阶项目验收

    进阶验的是「它是不是你的」：人格、记忆、技能、隔离四件事都落到文件上，而不是靠你每次在提示词里重复交代。

  15. 15

    精通项目验收

    精通验的是「能不能长期交给它」：你写的工具在被使用、定时任务在稳定触发、出事能查、升级能回退。

  16. 16

    速查卡与术语表

    命令速查（全部来自官方 CLI 参考）： hermes 进 CLI · hermes --tui 进 TUI · hermes -c / --continue 恢复最近会话 · -r / --resume <会话> 指定恢复 hermes doctor [--fix] 诊断 · hermes status [--all|--deep] 状态 · hermes version 版本 hermes setup 配置向导（可带 --portal）· hermes config show|edit|get|set|unset|path|check 配置 hermes model 选模型 · hermes fallback 备用链路 · hermes auth add|list|status|logout 凭据 hermes tools [--summary] 工具集 · hermes skills browse|search|install|list|check 技能 hermes memory setup|status|off 记忆 · hermes sessions list|export|delete|prune 会话 hermes profile list|use|create|export|import|install|update 多身份 hermes gateway run|setup|install|start|stop|status 网关 · hermes pairing list|approve|revoke 配对 hermes cron create|list|status|edit|run|pause|resume|remove|runs 定时 hermes mcp catalog|install|add|configure|login|test|serve|list MCP hermes kanban 多 Agent 看板 · hermes plugins install|list|doctor 插件 hermes security audit 供应链扫描 · hermes egress 出网防火墙 · hermes secrets bitwarden 外部密钥 hermes logs（agent / errors / gateway）· hermes prompt-size · hermes debug share · hermes dump hermes backup -o <路径> / hermes import -f <包> 备份恢复 · hermes update [--check] 升级 全局参数：-p <名字> 选 Profile、--yolo 跳过审批（不建议）、--in <目录> 换目录、-w / --worktree 用独立 git worktree、--ignore-user-config 忽略用户配置。 会话内命令：/reset 重置会话（重读 SOUL.md 与记忆）· /tools 看工具 · /skills 看技能 · /help 全部命令 · /技能名 [指令] 调用技能 · /reload-mcp 重载 MCP。

INSIDE THE MANUAL

两册，各管一段

基础篇读完能跑，进阶篇读完能交给别人用。

基础篇 · 14 章

从安装到接上消息平台

  1. 01快速开始 · 安装与第一个 API Key
  2. 02核心概念
  3. 03第一次对话
  4. 04配置文件详解
  5. 05模型与供应商
  6. 06工具系统
  7. 07技能 Skills
  8. 08记忆系统
  9. 09多身份 Profile
  10. 10灵魂档案 SOUL.md
  11. 11网关与消息平台
  12. 12定时 · 安全 · 调度
  13. 13命令速查表
  14. 14故障排查

进阶篇 · 8 模块

交给别人用之前要补的东西

  1. 01自定义工具开发
  2. 02Cron 自动化工作流
  3. 03SOUL.md 深度工程
  4. 04网关深度配置
  5. 05安全与合规
  6. 06Profile 工程化
  7. 07多 Agent 调度与协作
  8. 08Computer Use 桌面自动化

上手检查清单

8 项，从「装好 Hermes」一路打勾到「成功启动过 Gateway 网关」，全选即算合格。基础篇另附实战案例、常见问题与术语表，进阶篇另有 MCP 协议集成与调试诊断两章可随时查。

WHERE TO START

第一天做这三件事

先把一次完整对话跑通，再去碰配置文件。

01

装起来

执行 pip install hermes-agent，用 hermes version 与 hermes doctor 验一遍环境，再配上第一个 API Key。

基础篇 · 第 1 章

02

先跑通一次对话

把交互式对话跑起来，试几个对话内快捷命令，看清它怎么调工具。这一步之前不要改配置文件。

基础篇 · 第 3 章

03

按顺序往下读

从配置文件一章起，一章补一块能力，基础篇读完再开进阶篇。检查清单上的 8 项打完勾，这一册就算过了。

基础篇 · 第 4 章起

OPEN THE MANUAL

打开 Hermes 手册

两册分开读：先基础篇，再进阶篇。

NEXT STEP

手册解决怎么用，现场解决用在哪

带一个真实的业务问题来，我们和你的团队一起判断这些工具该落在哪一步。

预约企业 AI 诊断四本手册总览