工具：概述

工具是代理的双手。工具是模型可在对话过程中调用的一种能力，可运行 shell 命令、获取 HTTP URL、打开浏览器、写入文件、读取传感器。每次工具调用都受安全策略约束。启用回执时，成功执行可以包含工具回执。

不要将工具与 zeroclaw CLI 子命令混淆。CLI 命令用于操作员；工具用于智能体。

智能体通过其引用的 skill、knowledge 和 MCP bundles 获取其工具；有关 bundles 如何附加到智能体，请参见 Agents。关于从提供方工具调用到批准、分发、接收、observer 事件和 history 条目的 turn-level 路径，请参见 Tool execution lifecycle。

在添加内置工具或用外部集成替换某个内置工具之前，请使用 Built-In Tool Inventory 选择最小且持久的归宿。

内置工具

最小化构建包含以下内容：

工具	它的作用
`shell`	在工作区目录中执行 shell 命令。受命令允许/拒绝列表的约束
`file_read`	读取带行号的文件；支持部分读取以及对二进制文件进行 base64 编码（路径必须位于工作区内，除非 autonomy 允许其他情况）
`file_write`	写入文件（相同的路径约束）
`file_edit`	在文件中将精确匹配的字符串替换为新内容
`glob_search`	列出工作区中与 glob 模式匹配的文件
`content_search`	在工作区内通过正则表达式搜索文件内容（使用 ripgrep，并以 grep 作为后备方案）
`http_request`	向允许列表中的域名发送 HTTP GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS 请求
`web_search_tool`	网页搜索。提供程序可配置：DuckDuckGo（默认，无需密钥）、Brave、Tavily、SearXNG、Jina 或 Bocha
`web_fetch`	获取页面并返回纯净的纯文本
`browser`	无头浏览器自动化。请参阅浏览器自动化
`memory_recall`	在长期记忆中搜索相关的事实、偏好或上下文
`memory_store`	将事实、偏好或备注存储到长期记忆中
`ask_user`	向当前活动频道发送一个问题并等待回复。支持可选的 `choices` 以获得结构化响应（Telegram 上为内联键盘，CLI 上为编号列表）。在 ACP 上，`choices` 为必填项：自由格式的提问将等待 ACP elicitation RFD。参数：`question`（必填）、`choices`（可选列表）、`timeout_secs`（默认 600）。
`escalate_to_human`	发送带有紧急程度路由的结构化升级消息。`high` / `critical` 紧急程度会额外通知 `[escalation] alert_channels` 中列出的所有频道。参数：`summary`（必填）、`context`（可选）、`urgency`（`low`/`medium`/`high`/`critical`，默认 `medium`）、`wait_for_response`（布尔值，默认 false）、`timeout_secs`（默认 600）。在 ACP 上，如果频道无法接收自由格式的回复，`wait_for_response: true` 会立即失败（等待 ACP elicitation RFD）。

始终与内置项一起注册：

工具	备注
`cron_*`	管理计划任务：`cron_add`、`cron_list`、`cron_remove`、`cron_update`、`cron_run`、`cron_runs`
`schedule`	仅 Shell 的一次性/周期性调度
`memory_forget`、`memory_export`、`memory_purge`	长期记忆管理
`spawn_subagent`、`delegate`	在子智能体中运行子任务

有条件注册：

工具	已启用
`knowledge`	`[knowledge].enabled = true`。存储结构化关系记忆；参见 Relationship memory
硬件探针	`--features hardware`：GPIO 读取/写入、设备发现、固件刷写
`sop_*` 工具	在启用 SOP 运行时后注册（将 `sop.sops_dir` 设置为非空值；默认未设置，即禁用该运行时；文档中的值为 `shared/sops`）：运行并检查 SOP
`discord_search`	当 Discord 别名启用 `archive` 时注册

扩展协议

除了内置工具外，ZeroClaw 还支持 MCP（模型上下文协议）扩展接口。连接任意 MCP 服务器（Claude Code 的文件系统、Playwright 或您自己的服务器），代理在启动时即可自动获取其工具。

对于编辑器将 ZeroClaw 作为子进程驱动的 IDE 侧集成，请参阅 ACP：Agent Client Protocol 归类于 channels，因为它是一个入站的会话管理接口，而非 agent 调用的工具。

编写工具

在 zeroclaw-api 中实现 Tool 特质：

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync + Attributable {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;   // 参数的 JSON Schema
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
}
}

每个 Tool 同时也是 Attributable，因此工具调用的日志输出和审计追踪会携带与运行时其余部分相同的 <kind>.<alias> 归属信息。

通过运行时的工具工厂进行注册。完整模式请参阅开发 → 插件协议。

向模型描述工具

工具描述为 Mozilla Fluent 字符串：每个工具一条，按区域设置进行本地化。这样既能让工具描述在模型的上下文窗口中保持简洁，又能实现 UI 本地化。

权威来源：crates/zeroclaw-runtime/locales/en/tools.ftl。翻译通过 cargo fluent fill --locale <code> 生成和维护（详见维护者 → 文档与翻译）。

风险与审批

每次工具调用都按风险进行分类：

低（只读，无副作用）：file_read、memory_recall、对允许的域执行 http_request GET
中等（修改本地状态）：file_write、使用已知安全命令的 shell
高（破坏性或远程副作用）：执行未知命令的 shell、向无限制 URL 发送的 http_request POST

自主级别决定了每个风险级别在无需操作员批准的情况下可以执行的操作。默认值（Supervised）：低风险运行，中风险询问，高风险阻止。

启用收据后，成功执行会收到一个 tool receipt。被拒绝、阻止、替换、失败或中断的调用不会收到收据。

在非 CLI 通道上禁用工具

架构中没有针对每个通道的 tools_allow / tools_deny 字段。工具门控由智能体的风险配置文件（[risk_profiles.<alias>]）管理：

excluded_tools 会将列出的工具从所有非 CLI 渠道（Discord、Telegram、Bluesky、Matrix、Slack 等）中移除，同时保持本地 CLI 不受影响。其粒度是二元的（CLI vs 非 CLI），而不是按单个渠道区分。它还会从运行时解析的 agentic-delegate 允许列表中减去这些工具，这是阻止下面规则原本会自动接纳的单个 <server>__<tool> MCP 名称的唯一方法。
allowed_tools 则相反：它是代理在 agentic 模式下可调用工具的允许列表（为空或省略都表示没有授权约束；TOML 配置不会区分这两种情况）。
MCP 异常：当 allowed_tools 非空时，运行时发现的 MCP 工具（任何包含 __ 的名称，即 <server>__<tool> 约定）会自动加入生效的允许列表，而无需逐个列出。这样可以让 #7464 之后的 eager-MCP 默认配置继续适用于那些已经固定了显式允许列表的代理。要阻止单个 MCP 工具，请将它们列入 excluded_tools。
MCP 异常仅限于 risk profile 的 allowed_tools。调用方提供的按运行时的允许列表（cron job 的 allowed_tools、缩小范围的委托调用等）仍然按严格的显式列表交集处理。一个将自身收窄为 allowed_tools = ["cron_add"] 的任务，不会暴露它未命名的运行时发现的 MCP 包装器，即使 agent 的风险配置文件会自动允许它们。

如果你需要更细粒度的控制，可以将配置文件的 level 降至 read_only 或 supervised，并依靠每个配置文件的 auto_approve / always_ask 列表，让敏感工具在操作员批准后才能执行。

有关每个配置文件字段的完整集合，请参阅自治级别。

ZeroClaw Docs