04 · 工具系统与终端后端

Hermes 的工具系统决定 agent 能做什么。**终端后端（terminal backend）**决定这些动作在哪里发生。新手必须把这两个问题分开——否则会把"开了 terminal toolset（终端工具集）"和"命令在本机执行"混成一件事，结果让一个不可信任务在本机直接跑命令。

官方资料：Tools & Toolsets、Configuration、Toolsets Reference、Tools Reference、Security。

Toolset 不是 backend

**Toolset（工具集）**是按用途分组的工具包，常见有：

• web / search：搜索和抽取网页内容。
• file：读写文件。
• terminal：执行 shell 命令。
• browser：页面导航、快照、视觉自动化（playwright 风）。
• memory / session_search：长期记忆写入与跨 session 历史检索。
• skills：加载可复用流程（agent 自创 + 手动 skill）。
• cronjob / messaging：定时任务和消息投递。
• delegation / code_execution：委派子代理和程序化 Python 执行。

完整工具清单按官方 Toolsets Reference 当前列表为准——具体工具集随版本更新。

**Terminal backend（终端后端）**是 shell 命令的执行环境：

• local：本机直接跑——快但没有任何隔离，命令对本机有完全权限。
• docker：在一个长生命周期 Docker 容器内跑——有隔离但容器内状态会持久共享（详见下文 Docker 的误区）。
• ssh：通过 SSH 跑到远程服务器——把"Hermes 在哪"和"命令在哪"完全解耦。
• singularity：HPC（高性能计算）或 Docker 不可用的共享机器，常见于科研集群。
• modal / daytona：云端 sandbox（隔离沙箱）/ workspace——闲置免费、按需启动的 serverless 环境。
• vercel_sandbox：Vercel 的 microVM（微型虚拟机）+ 快照支持的云端执行环境。

一句话总结：toolset 决定它能拿什么工具，backend 决定命令实际在哪里跑——两个问题独立配置，互不替代。

把这两件事放在同一张图里看，就是横轴×纵轴的矩阵——任意一条命令都对应"开了哪个 toolset"+"跑在哪个 backend"两个独立坐标：

flowchart TB
    subgraph TS["② toolset 维度 · 调什么"]
        T1["web<br/>搜索"]
        T2["file<br/>读写"]
        T3["terminal<br/>执行"]
        T4["browser<br/>浏览"]
        T5["memory<br/>记忆"]
        T6["skills<br/>技能"]
    end
    subgraph BE["① backend 维度 · 在哪跑"]
        B1["local<br/>本机直跑<br/>无隔离"]
        B2["docker<br/>容器<br/>持久共享"]
        B3["ssh<br/>远程主机"]
        B4["modal/daytona<br/>vercel_sandbox<br/>云端 sandbox"]
        B5["singularity<br/>HPC"]
    end
    TS -->|"决定 agent<br/>能调什么"| RUN["⚡ 命令实际执行"]
    BE -->|"决定 shell 命令<br/>实际在哪台机器"| RUN
    style B1 fill:#fde2e2,stroke:#c43d3d
    style RUN fill:#fde7c2,stroke:#d4761a

红色 local 是默认且最危险的——开了 terminal toolset 不等于隔离，命令会直接跑在你打开 Hermes 的那台机器上。关键 mismatch：很多事故来自只看到 toolset 维度（"我开了哪些工具"），却没意识到 backend 维度（"命令实际在哪台机器"）始终是另一个独立维度。

最小工具集

按任务开工具：

查资料        -> web/search
读文件        -> file read
改文件        -> file + patch
跑测试        -> terminal + 明确 backend
操作页面      -> browser
回查历史      -> session_search
长期事实      -> memory
复用流程      -> skills
定时任务      -> cronjob
跨平台通知    -> messaging/send_message

工具越多，权限越大，错误来源也越多。第一次使用只开最少能力：普通对话稳定后，再读文件，再运行低风险命令。

Backend 选择

local 没有隔离。docker 有隔离但不是每条命令全新容器。ssh 有主机边界但需要管理远端凭据。云 sandbox 有成本、持久化和凭据同步边界。

Docker 的误区

Hermes Docker backend 是一个长生命周期容器。它会把后续 terminal、file、execute_code 调用通过 docker exec 送进去，进程生命周期内会保留包、文件和工作目录状态。

这有两个后果：

• 好处：一次安装的依赖后续可用，像远程开发容器。
• 风险：并行 subagents、/new、/reset 仍可能共享同一容器状态。

如果你需要并行隔离，不能只说“用 Docker”。还要规划每个任务的工作目录、volume、env、写入路径和清理方式。

后台进程

测试、构建、服务启动、长时间诊断适合后台进程。它们必须能启动、轮询、读取日志、等待和终止。

terminal(command="pytest -v tests/", background=true)
process(action="poll", session_id="proc_abc123")
process(action="log", session_id="proc_abc123")
process(action="kill", session_id="proc_abc123")

不要把发布、删除、数据库迁移、账单变更这类高风险动作直接后台化。后台不是降低风险，只是让任务离开当前交互视线。

Nous Tool Gateway 的边界

Nous Portal 付费用户可以通过 Tool Gateway 使用 web search、image generation、TTS、browser automation 等能力，减少单独配置工具 API key 的成本。

但 Tool Gateway 只解决“工具供应商凭据”问题，不解决“哪些人和平台能调用工具”的问题。Gateway 用户、toolsets、terminal backend、allowlist 仍要单独管。

风险不只来自 shell

即使关闭 terminal，也仍有副作用：

• file 可以读写文件。
• browser 可以操作网页和登录态。
• messaging 可以外发内容。
• memory 会影响后续 session。
• skills 可能加载脚本和密钥需求。
• MCP tools 可能连接数据库、GitHub、Slack 或浏览器。

安全边界要按整体工具能力设计，而不是只盯 shell。

验收清单

你应该能用一句话回答下面 7 个问题。任何一项答不上来，说明工具 / 后端边界没真正搞清楚——先停下来弄清，再开下一个工具：

• 当前启用了哪些 toolset？（hermes config show 看 toolsets 字段）
• 每个 toolset 为什么需要？（不能回答 = 应该关掉）
• Terminal backend 是 local、docker、ssh 还是云端？（hermes config show 看 terminal.backend 字段，或直接看 ~/.hermes/config.yaml）
• 命令实际在哪个环境运行？（让 Hermes 跑一条 pwd && hostname 验证）
• 哪些 env vars（环境变量）会进入 backend？（敏感变量是否会泄漏到容器或远端）
• 日志、输出文件和后台进程状态在哪里看？（~/.hermes/logs/ + process(action="log")）
• 不需要的工具如何关闭？（hermes config set toolsets.<name> false 或编辑 yaml）

官方资料

• Tools & Toolsets
• Tools Reference（完整工具清单）
• Toolsets Reference（toolset 分组）
• Security（命令审批、用户授权、容器隔离）
• Docker Backend（Docker 后端深入）
• Checkpoints & Rollback（破坏性操作的回滚机制）

下一步