第六章：工具系统与终端后端

如果说”模型”是 Hermes 的脑，那”工具”就是它伸出去的手。Hermes 内置 68 个工具、52 个 toolset、6 大类后端——本章把工具体系完整拆解：什么工具、怎么按平台启用、怎么换执行环境（local/docker/ssh/daytona/modal/singularity）、怎么用 execute_code 把多步流水线压成一次推理、以及最重要的——怎么安全地让它在你电脑上敲命令。

6.1 工具体系总览

Hermes 工具体系有三层概念：

工具（Tool）          ← 一个具体的可调用函数（read_file、terminal、web_search…）
  └─ 工具集（Toolset） ← 工具的逻辑分组（web、file、terminal、browser、memory…）
       └─ 平台预设      ← 不同入口默认开哪几组（hermes-cli / hermes-telegram / …）

每次启动一个会话，Hermes 会把”当前平台 → 启用 toolset → 收集工具 schema”流水线跑一遍，把工具列表和 schema 发给模型。

6.2 全部工具按用途分类

下面这张表是从官方 reference/tools-reference.md 抽出的核心摘要，按”在工作中真正用得到的语义类目”重组：

内置 68 个数字会随版本演进；工具最权威列表请以 hermes tools list 与 reference/tools-reference.md 为准。

6.3 Toolset：把工具分组并按平台启用

每个 toolset 大概对应一类能力。常见 toolset 名称：

web, search, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant, messaging, spotify, discord, discord_admin, debugging, safe, rl, kanban。

6.3.1 平台预设

不同入口需要的工具不同：

6.3.2 配置方式：hermes tools

最简单：

hermes tools

进入交互菜单，按”平台”维度勾选启用哪些 toolset；保存后写到 config.yaml：

toolsets:
  hermes-cli:
    - web
    - terminal
    - file
    - browser
    - skills
    - memory
    - session_search
    - todo
    - clarify
    - code_execution
    - delegation
    - cronjob
  hermes-telegram:
    - web
    - file
    - skills
    - memory
    - todo
    - send_message
  hermes-wecom:
    - web
    - file
    - skills
    - memory

6.3.3 临时覆盖

hermes chat --toolsets "web,terminal,file"

只本次会话生效。

6.3.4 安全/限制 toolset：safe / debugging

• safe：只保留只读 / 不写盘 / 不执行命令的工具，适合演示或公网 bot；
• debugging：开启 /debug 风格更详细日志的工具。

6.4 终端工具与 6 种后端

terminal 是日常最重要的工具。Hermes 把它做成抽象接口，可挂在 6 种后端之一（外加内嵌 tmux 视图）：

切换只需一行：

hermes config set terminal.backend docker

或在 TUI /terminal docker（如 plugin 已加）。

6.4.1 Docker 后端（推荐用于生产）

terminal:
  backend: docker
  docker:
    image: ghcr.io/nousresearch/hermes-sandbox:latest
    read_only: true
    network_mode: bridge
    cap_drop:
      - ALL
    user: "1000:1000"
    working_dir: /workspace
    binds:
      - "${HOME}/code:/workspace:rw"
      - "${HOME}/.hermes:/hermes:ro"
    env_passthrough:
      - GITHUB_TOKEN
      - OPENROUTER_API_KEY

Hermes 会在每条 terminal 调用前后做两件事：

1. 启动一个短生命周期 / 长生命周期容器（按 terminal.docker.persistent 配置）；
2. 通过 tools/credential_files.py 把临时凭据文件挂入 /run/secrets/，避免 env 泄漏。

6.4.2 SSH 后端

terminal:
  backend: ssh
  ssh:
    host: ops.example.com
    user: deploy
    identity_file: ~/.ssh/id_ed25519
    port: 22
    request_pty: true
    keep_alive: 30

Hermes 会自动复用一个长连 SSH 会话，避免每条命令都建连。hermes doctor 会检测连通性。

6.4.3 Daytona / Modal Serverless

这两个是 Hermes 的”杀手特性”之一：你可以让 Hermes 在云端”长寿命且空闲零成本”的环境中跑命令——你的笔记本关掉它依然在工作。

terminal:
  backend: daytona
  daytona:
    workspace: my-hermes
    api_url: https://app.daytona.io
    region: us-east-1

terminal:
  backend: modal
  modal:
    app: hermes-sandbox
    image: hermes/sandbox:latest
    cpu: 4
    memory_mb: 8192
    timeout_idle_seconds: 600

第一次使用前需要：

daytona auth login        # 或 modal token new
hermes config set DAYTONA_API_TOKEN ...
hermes config set MODAL_TOKEN_ID ...  # 等

6.4.4 Singularity（HPC）

学院/超算环境常见：

terminal:
  backend: singularity
  singularity:
    image: /scratch/$USER/hermes.sif
    binds:
      - /scratch/$USER:/work

6.5 命令审批与白名单：approval.py

Hermes 默认对”危险命令”启用审批（用户需在 TUI 里按 y）：

• rm -rf /、rm -rf ~、mkfs、dd of=/dev/...、chmod -R 777 /、curl ... | sudo bash 等；
• 含 sudo 的任何命令；
• 跨网络发数据的 curl/scp/rsync 到外部 host 等。

可在 config.yaml 自定义：

approval:
  always_allow:
    - "^ls( |$)"
    - "^git (status|diff|log)"
  always_deny:
    - "rm -rf /"
  require_confirmation:
    - "^sudo "
    - "^mkfs"
    - "^dd "

Gateway 模式下，审批可以走 DM 配对（gateway/pairing.py）：让 Hermes 在 Telegram DM 里等你点 ✅。

6.6 process 工具：长进程管理

terminal 适合一次性命令；如果是 web 服务、watch 编译这种”持续运行”的进程，用 process 工具：

process(action="start", name="api", cmd="uvicorn main:app --port 8000")
process(action="logs", name="api", tail=100)
process(action="stop", name="api")
process(action="list")

后台进程通过 tools/process_registry.py 统一存活、日志、PID 管理。

6.7 execute_code：把多步流水线压成一次推理

这是 Hermes 工程上最优雅的设计之一——所谓 Programmatic Tool Calling。

execute_code(language="python", code="""
import json

repos = json.loads(_call_tool("read_file", {"path": "repos.json"})["content"])
results = []
for r in repos:
    out = _call_tool("terminal", {"cmd": f"git ls-remote {r['url']} HEAD"})
    results.append({"name": r["name"], "head": out["stdout"].split()[0]})
_call_tool("write_file", {"path": "snapshot.json", "content": json.dumps(results, indent=2)})
""")

_call_tool 是 Hermes 注入到沙箱 Python 进程里的 RPC bridge——你写出的 Python 代码可以直接调用任何 Hermes 工具，避免几十轮”工具调用 → 模型规划下一步”。

适合：批处理、聚合、数据转换、文件遍历、解析复杂 JSON 等场景。

6.8 delegate_task：子代理并行

delegate_task(tasks=[
    {"goal": "搜集 OpenAI 最近 5 篇论文要点", "toolsets": ["web"]},
    {"goal": "搜集 Anthropic 最近 5 篇论文要点", "toolsets": ["web"]},
    {"goal": "搜集 DeepMind 最近 5 篇论文要点", "toolsets": ["web"]},
])

子代理特点：

• 完全空白对话（没有父 Agent 历史，必须把所有需要的信息塞 goal/context）；
• 自己的 toolset 限制；
• 默认最多 3 个并发，可配；
• 父 Agent 只看到每个子代理的 结构化总结（修改了什么、遇到了什么）。

详细 patterns 见第十一章和官方 guides/delegation-patterns.md。

6.9 浏览器工具与多种后端

browser_* 工具支持 5 种后端：

切换：hermes tools → browser → 选 backend。

6.10 Web 搜索与 web_extract

web_search 默认按以下次序选后端：

1. Nous Tool Gateway（订阅用户零配置）；
2. Tavily（TAVILY_API_KEY）；
3. Brave（BRAVE_API_KEY）；
4. Bing（BING_API_KEY）；
5. DuckDuckGo（无 Key 但限速）。

web_extract 把页面拉下来转成 Markdown（去掉广告、导航），交给模型做总结/抽取。

6.11 Vision、Image Generation、TTS

• Vision：模型本身支持视觉就走主模型；不支持就走 vision_model/auxiliary_model。粘贴图片 (@clipboard) 即用。
• Image Generation：FAL.ai 后端，可选 9 个模型（FLUX 2 Klein/Pro、GPT-Image 1.5/2、Nano Banana Pro、Ideogram V3、Recraft V4 Pro、Qwen-Image、Z-Image Turbo）。
• TTS：Edge TTS（免费）、ElevenLabs、OpenAI TTS、MiniMax、Mistral Voxtral、Google Gemini、xAI、NeuTTS、KittenTTS、Piper，再加自定义 command provider。

第十一章会展开它们。

6.12 Tool Gateway：订阅用户的便捷捷径

Nous Portal 订阅用户可以直接用 Tool Gateway：web search、image gen、TTS、browser 都走 Nous 的统一服务，不用自己配 Tavily/Brave/Browserbase 等密钥。

hermes model
# 选 Nous Portal → OAuth
hermes tools
# 启用 Tool Gateway 后端

6.13 安装可选 extras 解锁更多工具

# 进入仓库目录后：
uv pip install -e ".[voice]"        # CLI 麦克风/扬声器
uv pip install -e ".[messaging]"    # Discord/Telegram/Aiohttp
uv pip install -e ".[tts-premium]"  # ElevenLabs
uv pip install -e ".[mcp]"          # MCP 客户端
uv pip install -e ".[all]"          # 一把梭

hermes_agent 在 pyproject.toml 中清晰划分了 extras，避免把所有依赖都塞进基础包。

6.14 自定义工具与插件

如果某个能力 Hermes 没有，你有三条路：

1. 写 MCP server（首选，无侵入）—— 第八章详解；
2. 写 Hermes 插件（plugins/<name>/）—— 第十二章详解；
3. 修改 tools/registry.py 加 native 工具（仅供贡献者）。

6.15 实战 1：让 Hermes 永远在 Docker 沙箱里跑

terminal:
  backend: docker
  docker:
    image: ghcr.io/nousresearch/hermes-sandbox:latest
    read_only: true
    cap_drop: [ALL]
    user: "1000:1000"
    working_dir: /workspace
    binds:
      - "${HOME}/code:/workspace:rw"
    env_passthrough:
      - OPENROUTER_API_KEY
      - GITHUB_TOKEN
approval:
  require_confirmation: ["^sudo ", "^rm -rf "]

效果：Agent 永远在容器内执行命令，对宿主只读绑定 ~/code，敏感凭据通过 env_passthrough 而非整个环境注入。

6.16 实战 2：Daytona Serverless”长寿命空闲零成本”

terminal:
  backend: daytona
  daytona:
    workspace: hermes-ops

第一次启动会触发 Daytona 创建工作空间，之后 Hermes 每次跑命令都唤醒它；空闲会自动 hibernate，按需收费。

6.17 实战 3：在 Telegram 用安全工具集

toolsets:
  hermes-telegram:
    - web
    - search
    - file
    - skills
    - memory
    - todo
    - send_message
approval:
  require_confirmation:
    - ".*"   # Telegram 端任何工具调用都先 DM 配对授权

这样即使 bot 被暴露给团队，也不会被人滥用让它跑 rm -rf。

6.18 本章小结

• Hermes 的工具体系按 工具 → 工具集 → 平台预设 三级组织；
• 终端工具支持 6 种后端，可一行切换，让 Agent 跑在本地、容器、SSH、Daytona、Modal、Singularity；
• execute_code 把多步流水线压成一次推理；delegate_task 让子代理并行；
• 内置 审批机制 + 白名单 + 命令检测，是安全的核心保障；
• 浏览器、视觉、图像、TTS、Web 搜索都各有多后端可选；
• Tool Gateway 让订阅用户零配置上车；
• 三种自定义路径：MCP、Plugin、Native，下一章开始我们就进入”让 Agent 自我成长”的核心：技能与记忆。