9. 工具系统全景：70+ 工具与 Toolsets

本节目标：搞清楚 Hermes Agent 的工具系统怎么组织—工具、工具集、平台配置三层结构是什么，四类 Toolset 各自管什么，MCP 动态工具怎么接入，以及 Tool Gateway 和 Tool Search 这两个省心省钱的机制怎么用。学完你能在脑子里画出整个工具系统的全景图。

工具是 Agent 的手脚

智能体（Agent）光有脑子不够，得有手脚。模型负责想，工具负责干—读写文件、执行命令、搜索网页、生成图片，这些能力全部通过工具（Tools）暴露给 Agent。

Hermes Agent 当前最新稳定版 v2026.7.20 内置 70+ 工具，按功能归到 20+ 个工具集（Toolset）里，分为 Core / Composite / Platform / Dynamic 四类。工具集再按部署场景组合成平台配置，这就构成了一个清晰的三层结构：

工具（Tool）            ← 单个可调用函数，如 read_file、web_search
  └── 工具集（Toolset）     ← 相关工具的逻辑分组，如 file、web
        └── 平台配置          ← 哪个平台加载哪些工具集

这套设计的关键点：禁用一个工具集，里面的工具会从系统提示词里彻底消失。不是”不可调用”，是 Agent 压根不知道它存在。这样既省 token，也防止 Agent 误用不该用的工具。

四类 Toolset

Hermes 的工具集分四种，理解这个分类是掌握工具系统的钥匙。

Core（核心工具集）：单个逻辑分组，把一组相关工具打包。比如 file 工具集装着 read_file、write_file、patch、search_files 四个文件操作工具。

Composite（组合工具集）：把多个 Core 工具集按常见场景拼到一起。比如 debugging 工具集 = file + terminal + web，专门给调试场景用；coding 工具集更全，把文件、终端、搜索、网页、技能、浏览器、待办、记忆、会话检索、澄清、代码执行、委托、视觉全打包，适合软件开发的完整工作流。

Platform（平台工具集）：面向具体部署场景的完整工具配置。hermes-cli 是 CLI 交互会话的默认配置，包含文件、终端、网页、浏览器、记忆、技能、视觉、图片生成、待办、TTS、委托、代码执行、定时任务、会话检索、澄清，外加只读的 safe 组合。其他平台大多以它为基准做加减。

Dynamic（动态工具集）：运行时生成的工具集，主要是 MCP 服务器和插件注册的。每配一个 github MCP 服务器，运行时就冒出一个 mcp-github 工具集。

配置工具集的三种姿势

单会话临时指定

启动时用 --toolsets 参数直接指定：

hermes chat --toolsets web,file,terminal
hermes chat --toolsets debugging        # 组合工具集，展开成 file + terminal + web
hermes chat --toolsets all              # 全部启用

按平台写进配置文件

在 ~/.hermes/config.yaml 里给每个平台定工具集：

toolsets:
  - hermes-cli          # CLI 默认
  # - hermes-telegram   # 给 Telegram 网关单独覆盖

交互式管理

hermes tools                            # 打开 curses TUI，按平台开/关工具集

或者在会话里临时调整：

/tools list
/tools disable browser
/tools enable homeassistant

Tip

hermes tools 这个 TUI 是最直观的管理方式。它能按平台逐个开关工具集，操作粒度比配置文件更细，还能直接到单个工具级别。改完自动写回 config.yaml。

核心工具集速览

下面挑最常用的几个 Core 工具集讲讲，帮你建立直觉。完整的工具清单以官方 tools-reference.md 为准。

file - 文件操作

最基础的工具集，Agent 几乎所有任务都靠它读写文件。

工具	功能
`read_file`	读文件，带行号和分页
`write_file`	写文件，完全覆盖
`patch`	精确查找替换，带 9 种模糊匹配策略
`search_files`	按文件名或内容搜索，ripgrep 驱动

patch 比 write_file 安全得多—它用 old_string 定位要改的位置，找不到就报错，不会误覆盖整个文件。Agent 改代码首选 patch。

Note

官方文档明确说：终端工具里不要用 cat/head/tail，用 read_file；不要用 grep/rg/find，用 search_files。专用工具更快、更省 token，输出格式也更规整。

terminal - 命令执行

工具	功能
`terminal`	执行 Shell 命令，文件系统跨调用持久化
`process`	管理后台进程（list/poll/log/wait/kill/write）
`read_terminal`	读桌面 GUI 内嵌终端的当前输出（仅桌面版）

terminal 支持 background=true 跑长任务服务器，配合 notify_on_complete=true 还能在完成时自动通知，不用轮询。

终端后端有六种，决定命令在哪跑：

后端	执行位置	典型场景
`local`（默认）	本机当前用户权限	个人开发
`docker`	隔离容器	生产沙箱
`ssh`	远程服务器	远程开发、隔离
`singularity`	HPC 容器	集群计算
`modal`	云沙箱	无服务器
`daytona`	托管云工作区	持久远程环境

# ~/.hermes/config.yaml
terminal:
  backend: docker
  docker_image: python:3.11-slim
  container_persistent: true    # 文件系统跨会话保留

Warning

Docker 后端是「一个长寿命容器，整个进程共享」—不是每条命令起一个新容器。你 pip install 装的东西，后续调用都在。这点和很多人想象的不一样，用的时候心里有数。

web - 网页搜索与提取

工具	功能
`web_search`	搜网页，默认返回最多 5 条结果（标题+URL+摘要）
`web_extract`	提取网页正文，返回 markdown；也能直接吃 PDF 链接

web_search 支持 limit 参数（1-100），查询词会透传给后端，所以 site:domain、filetype:pdf、"精确短语" 这些操作符在后端支持时能用。

需要配搜索 API Key 才能用，支持 EXA、Parallel、Firecrawl、Tavily 等后端。

browser - 浏览器自动化

完整的浏览器控制能力，10 个核心工具加 2 个 CDP 网关工具：

工具	功能
`browser_navigate`	导航到 URL，必须先调它
`browser_snapshot`	取页面无障碍树的文本快照，带 ref ID
`browser_click`	按 ref ID 点击元素
`browser_type`	往输入框打字
`browser_scroll`	滚动页面
`browser_press`	按键
`browser_back`	后退
`browser_vision`	截图并用视觉 AI 分析
`browser_console`	取控制台输出和 JS 错误
`browser_get_images`	列出页面所有图片

browser_cdp 和 browser_dialog 这两个是 CDP 门控工具—只有会话启动时能连上 Chrome DevTools Protocol 端点（通过 /browser connect、browser.cdp_url 配置、Browserbase 或 Camofox）才会注册。

Tip

简单信息检索优先用 web_search 或 web_extract，更快更便宜。只有需要交互（点击、填表、登录）才上 browser 工具集，因为启动浏览器实例更耗资源。

其他常用工具集

memory：持久化跨会话记忆
skills：技能的增删改查（skills_list、skill_view、skill_manage）
delegation：派子 Agent 并行干活（delegate_task）
code_execution：跑能调用 Hermes 工具的 Python 脚本（execute_code）
cronjob：定时任务管理（cronjob）
vision：图片分析（vision_analyze）
image_gen / video_gen：图片/视频生成，需对应后端
tts：文字转语音（text_to_speech）
todo：会话内任务清单
clarify：Agent 需要澄清时问用户
session_search：搜历史会话，FTS5 全文检索
computer_use：后台桌面控制，不抢用户鼠标焦点
homeassistant：智能家居控制（需 HASS_TOKEN）
kanban：多 Agent 看板协作，需显式启用

safe - 只读研究组合

safe 是个特殊的组合工具集，只装只读工具：image_generate、vision_analyze、web_extract、web_search。没有文件写入、没有终端、没有代码执行。适合给 Agent 做纯调研任务，限制爆炸半径。

平台工具集的差异

大部分消息平台直接用 hermes-cli 的全套工具。少数有差异：

平台工具集	和 hermes-cli 的差异
`hermes-acp`	砍掉 clarify、cronjob、image_generate、TTS 和全部 Home Assistant 工具，聚焦 IDE 编码
`hermes-api-server`	砍掉 clarify 和 TTS，其余保留，适合程序化访问
`hermes-discord`	在 hermes-cli 基础上加 `discord` 和 `discord_admin`
`hermes-feishu`	加 5 个飞书文档/云盘评论工具
`hermes-yuanbao`	加 5 个腾讯元宝 DM/群/表情工具
`hermes-gateway`	内部网关编排工具集，所有 `hermes-<平台>` 的并集

Note

kanban 工具集是个特例。它不会被 all/* 通配符启用—必须显式列出 kanban，或者是由看板调度器派生的工作者（HERMES_KANBAN_TASK 环境变量）。因为它会改共享看板状态，默认保持关闭。

MCP：动态工具的前缀规则

MCP（Model Context Protocol）让 Hermes 不改核心代码就能接入外部工具服务器—GitHub、数据库、文件系统、内部 API 等等。

配一个 MCP 服务器，运行时会自动生成一个 mcp-<服务器名> 工具集。工具名带 mcp_<服务器>_ 前缀。比如配了 github 服务器：

# ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

生成的工具集叫 mcp-github，里面的工具叫 mcp_github_create_issue、mcp_github_list_issues 这种。你可以像管内置工具集一样在 --toolsets 或平台配置里引用它。

MCP 服务器分两类：

stdio 本地服务器：子进程形式本地跑，通过标准输入输出通信，适合访问本地资源
HTTP 远程服务器：直接连远端端点，支持 Bearer Token 和 OAuth 2.1 认证

Tip

MCP 子进程的环境变量是过滤过的，默认只传 PATH、HOME、USER、LANG 这些基础变量，你的 API Key 不会泄露。只有你在 env: 块里显式声明的变量才传进去。MCP 工具的错误信息返回给 LLM 前也会自动脱敏，敏感信息替换成 [REDACTED]。

Nous Tool Gateway：一个订阅搞定所有工具

这是省钱省心的关键功能。Tool Gateway 包含在 Nous Portal 付费订阅里，把网页搜索、图片生成、TTS、云端浏览器这四类工具的云端实现打包给你用，不用再分别申请 Firecrawl、FAL、OpenAI、Browser Use 的 API Key。

工具	你能得到什么
网页搜索与提取	Firecrawl 驱动的搜索和全文提取，无速率限制
图片生成	9 种模型：FLUX 2 Klein、FLUX 2 Pro、Z-Image Turbo、Nano Banana Pro、GPT Image 1.5/2、Ideogram V3、Recraft V4 Pro、Qwen Image
文字转语音	OpenAI TTS 语音
云端浏览器	Browser Use 驱动的无头 Chromium，`browser_navigate`/`click`/`type`/`vision` 全可用

三种开启方式：

hermes setup --portal     # 全新安装：OAuth + 设 Nous 为 provider + 开启 Gateway，一条命令
hermes model              # 切推理 provider 到 Nous Portal，顺带问你要不要全开 Gateway
hermes tools              # 逐工具开启，挑「Nous Subscription」当 provider

Gateway 是按工具粒度的，想怎么混就怎么混：全走 Nous、只让网页和图片走 Gateway 自己留 ElevenLabs 的 TTS、只让没 Key 的工具走 Gateway—都行。随时用 hermes tools 切换。

hermes portal info        # 看 Portal 认证 + Gateway 路由汇总
hermes portal tools       # 看每个工具当前走哪

Note

Gateway 不是锁定。use_gateway: true 时走 Nous，false 时用你 .env 里的直连 Key。Key 留着不动，随时能切回去。

Tool Search：工具太多时的渐进式加载

当你挂了很多 MCP 服务器或非核心插件工具，它们的 JSON Schema 会占掉相当一部分上下文窗口—哪怕这一轮只用得上其中几个。

Tool Search 就是解决这个问题的。开启后，MCP 和插件工具会从模型可见的工具数组里移除，替换成三个桥接工具：

tool_search(query, limit?)     - 搜索延迟加载的工具目录
tool_describe(name)            - 加载某个工具的完整 Schema
tool_call(name, arguments)     - 调用延迟工具

模型需要某个工具时，先 tool_search 找，再 tool_describe 看参数，最后 tool_call 调用。Hermes 会把桥接调用拆开，底层工具正常执行，钩子和审批都按真实工具名跑。

默认是 auto 模式：只有延迟工具的 Schema 占上下文超过 10% 时才激活。低于这个阈值就是纯透传，零开销。

tools:
  tool_search:
    enabled: auto       # auto（默认）/ on / off
    threshold_pct: 10   # auto 模式的触发阈值，百分比
    search_default_limit: 5
    max_search_limit: 20

Warning

Tool Search 有个固有代价：第一次用某个冷工具时，要多花一两个模型调用来找和加载 Schema。它是「工具多但每轮用得少」时的优化，工具本来就不多时反而添堵。auto 默认已经帮你权衡好了，别没事设成 on。

Note

Hermes 核心工具（terminal、read_file、browser_*、web_search 等）永远不会被延迟加载，始终直接暴露。只有 MCP 工具和非核心插件工具才会被 Tool Search 接管。

自定义工具集

你可以把现有工具集组合成项目专属的：

# ~/.hermes/config.yaml
custom_toolsets:
  data-science:
    - file
    - terminal
    - code_execution
    - web
    - vision
  writing:
    - file
    - web
    - memory

hermes chat --toolsets data-science

这样不同项目用不同工具组合，既省 token 又限制 Agent 能力范围。

一句话记住

工具系统三层结构：工具归工具集，工具集归平台配置。四类 Toolset 里 Core 是原子，Composite 是套餐，Platform 是开箱即用，Dynamic 是 MCP 和插件。要省心用 Tool Gateway，要省 token 用 Tool Search，要精确控制就自定义工具集。