Hermes 工具系统的核心设计是「中央注册表 + 工具集分组」：每个工具在 tools/registry.py 注册，然后按场景打包成工具集（Toolset），按需启用。内置 30+ 工具，从终端执行到浏览器自动化，从 MCP 客户端到子代理，覆盖 AI Agent 的主要操作场景。扩展新工具只需改三个文件。

Hermes Agent 工具系统：内置 30+ 工具全解析与自定义工具开发教程

工具集（Toolset）架构

Hermes 把工具按用途分组为「工具集」，可以单独启用/禁用：

bash

hermes tools        # 交互式管理工具集启用状态
hermes --tools web,terminal  # 只启用 web 和 terminal 工具集

核心工具集：

工具集名	代表工具	需要的 Key
`web`	web_search, web_extract	Exa / Parallel / Firecrawl API Key
`browser`	browser_navigate, browser_click, browser_screenshot	Browserbase API Key
`code`	execute_code	无（本地沙箱）
`delegate`	delegate_task	无（子代理）
`mcp`	call_mcp_tool	MCP Server 配置
`memory`	memory_save, memory_search	无（本地 SQLite）
`vision`	vision_analyze, image_generate	FAL.ai / 视觉模型 Key
`ha`	ha_list_entities, ha_call_service	Home Assistant Token

所有工具集被打包进 _HERMES_CORE_TOOLS，默认全部加载，缺少对应 Key 的工具自动跳过（check_fn 返回 False）。

核心工具详解

terminal — 终端执行

最常用的工具，执行 shell 命令：

python

# 同步执行
terminal("ls -la /project")

# 后台执行（Gateway 模式会推送状态通知）
terminal("npm run build", background=True, check_interval=10)

Terminal 后端（在 config.yaml 里配置）：

后端	场景
`local`	本机执行（默认）
`docker`	隔离容器（推荐用于有风险的操作）
`ssh`	远程机器执行，API Key 留在本机
`modal`	Modal Cloud 临时容器
`singularity`	HPC 环境

SSH 后端的安全价值：Agent 代码跑在本机，命令执行在远程 server，.env 里的 API Key 不会暴露给 Agent。

file_tools — 文件操作

read_file      # 读文件
write_file     # 写文件
patch          # 按 diff 格式打补丁（保留上下文，最小修改）
search_files   # 在目录里搜索文件内容（支持正则）

patch 工具值得单独说：接受统一 diff 格式，不需要提供完整文件，只要上下文足够定位就能精确修改。大文件场景比 write_file 节省大量 token。

web_tools — 网页搜索与提取

web_search     # 搜索（Exa / Parallel / Firecrawl，按配置的 Key 自动选）
web_extract    # 提取指定 URL 的文本内容

多搜索引擎自动降级：配了 Exa Key → 优先 Exa；没有 Exa → 试 Parallel；没有 Parallel → 试 Firecrawl；都没有 → 报错。

browser_tool — 浏览器自动化

需要 Browserbase Cloud 账号（有 Free Tier），提供无头浏览器 API：

browser_navigate    # 打开 URL
browser_click       # 点击元素
browser_type        # 填写表单
browser_snapshot    # 页面截图（返回 base64 图片）
browser_scroll      # 滚动
browser_console     # 执行 JavaScript

默认开启基础 Stealth 模式（随机浏览器指纹 + 自动 CAPTCHA 识别）。配合多 Provider 路由里的视觉模型，可以做完整的视觉网页自动化。

delegate_tool — 子代理并发

python

delegate_task(
    prompt="分析这个 Python 函数的性能瓶颈",
    tools=["file_tools", "terminal"],
    context_files=["src/hotpath.py"]
)

并发限制：最多 3 个子代理同时运行，嵌套深度 2 层（子代理的子代理）。父代理同步阻塞等待子代理完成（ThreadPoolExecutor 实现），不是异步推送树。

这和 OpenClaw 的异步模式是明显差异：Hermes 子代理更简单可预测，OpenClaw 的 lane queue 吞吐量更高但复杂度更高。

mcp_tool — MCP 客户端

Hermes 可以作为 MCP 客户端，连接任意 MCP Server：

yaml

# ~/.hermes/config.yaml
mcp:
  servers:
    - name: filesystem
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    - name: github
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}

Hermes 也可以反过来作为 MCP Server，让 Claude Code 调用。详见 MCP Server 模式。

memory — 持久化记忆

memory_save     # 保存记忆（主动触发）
memory_search   # FTS5 全文检索历史记忆

记忆存储在 SQLite（~/.hermes/sessions/ 下），FTS5 支持全文检索。不同于 Claude Code 的 CLAUDE.md（静态文本），Hermes 记忆是动态累积的，AI 可以主动写入和检索。

自定义工具：三文件规律

添加新工具只需修改 3 个文件：

1. 创建 `tools/your_tool.py`

python

import json
import os
from tools.registry import registry

def check_requirements() -> bool:
    """工具可用性检查，Key 缺失时返回 False（工具被跳过，不报错）"""
    return bool(os.getenv("YOUR_API_KEY"))

def your_tool(query: str, task_id: str = None) -> str:
    """工具实现，必须返回 JSON string"""
    # 调用你的 API / 执行逻辑
    result = {"data": f"processed: {query}"}
    return json.dumps(result)

# 注册到中央 registry
registry.register(
    name="your_tool",
    toolset="your_toolset",
    schema={
        "name": "your_tool",
        "description": "工具的描述，AI 会读这个来决定什么时候调用",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "查询内容"
                }
            },
            "required": ["query"]
        }
    },
    handler=lambda args, **kw: your_tool(
        query=args.get("query", ""),
        task_id=kw.get("task_id")
    ),
    check_fn=check_requirements,
    requires_env=["YOUR_API_KEY"],
)

2. 在 `model_tools.py` 添加导入

找到 _discover_tools() 函数，加一行：

python

from tools.your_tool import your_tool  # noqa: F401

3. 在 `toolsets.py` 加到工具集

把工具名加入合适的工具集，或创建新工具集：

python

_HERMES_CORE_TOOLS = [
    # ... 现有工具
    "your_tool",  # 加到这里
]

关键注意点：

Handler 必须返回 JSON string（不是 dict）
check_fn 返回 False 时工具被静默跳过，AI 不知道它存在——不要报错
Schema description 是 AI 决定调用时机的依据，写清楚「什么时候用」「用来做什么」
用 get_hermes_home() 管理状态文件路径，不要硬编码 ~/.hermes（破坏 Profile 隔离）

FAQ

Q: 工具的 description 多长合适？

50~200 字最佳。太短 AI 理解不了用途，太长占 token。重点是：这个工具解决什么问题、什么情况下调用、关键参数是什么。

Q: 工具调用失败怎么处理？

Handler 返回 JSON error 字符串（不要抛异常）：

python

except Exception as e:
    return json.dumps({"error": str(e), "success": False})

Registry 有错误包装，但显式处理更可控。

Q: delegate_task 和直接提问有什么区别？

delegate_task 启动一个独立的子 Agent 实例，有独立的工具调用预算和上下文。适合需要多步工具调用的子任务（比如「分析这个仓库的依赖」），不适合简单的问答。并发 3 个可以并行处理多个独立子任务。

Skills 详解

已知问题

已知问题

Hermes Agent 工具系统：内置 30+ 工具全解析与自定义工具开发教程

工具集（Toolset）架构

核心工具详解

terminal — 终端执行

file_tools — 文件操作

web_tools — 网页搜索与提取

browser_tool — 浏览器自动化

delegate_tool — 子代理并发

mcp_tool — MCP 客户端

memory — 持久化记忆

自定义工具：三文件规律

1. 创建 `tools/your_tool.py`

2. 在 `model_tools.py` 添加导入

3. 在 `toolsets.py` 加到工具集

FAQ

Hermes Agent 工具系统：内置 30+ 工具全解析与自定义工具开发教程 ​

工具集（Toolset）架构 ​

核心工具详解 ​

terminal — 终端执行 ​

file_tools — 文件操作 ​

web_tools — 网页搜索与提取 ​

browser_tool — 浏览器自动化 ​

delegate_tool — 子代理并发 ​

mcp_tool — MCP 客户端 ​

memory — 持久化记忆 ​

自定义工具：三文件规律 ​

1. 创建 tools/your_tool.py ​

2. 在 model_tools.py 添加导入 ​

3. 在 toolsets.py 加到工具集 ​

FAQ ​

Hermes Agent 工具系统：内置 30+ 工具全解析与自定义工具开发教程

工具集（Toolset）架构

核心工具详解

terminal — 终端执行

file_tools — 文件操作

web_tools — 网页搜索与提取

browser_tool — 浏览器自动化

delegate_tool — 子代理并发

mcp_tool — MCP 客户端

memory — 持久化记忆

自定义工具：三文件规律

1. 创建 `tools/your_tool.py`

2. 在 `model_tools.py` 添加导入

3. 在 `toolsets.py` 加到工具集

FAQ