工具：概述

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

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

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

在添加内置工具或用外部集成替换现有工具之前，请先参阅内置工具清单，选择最小且可持续的归属位置。在替代方案真实可用、有文档记录并经过独立审查之前，现有的可正常工作的内置集成将保持可用。这一“替换优先“规则是已采纳的 RFC #6165 政策，记录于清单中的替换优先策略一节。

最小工具集和完整工具集

除非选择 minimal，否则配置使用 full：即本二进制文件所包含、且符合其现有配置、前置条件和权限规则的全部内置项。设置和配置生成会写入 optional = [“*”]。不含 [tools] 的文件，或含有 [tools] 但没有 optional 的文件，同样按 full 加载，因此升级到 v0.8.6 后，现有工具的可用性保持不变。已有的显式选择会被保留。

[tools]
optional = ["*"] # 完整；默认值

Minimal 为可选模式：在 Chat 中提供十一个内置工具，在 Code/ACP 中提供八个内置工具，其中 Code/ACP 仍排除持久化记忆工具。Chat 的十一个工具为 shell、file_read、file_write、file_edit、glob_search、content_search、memory_recall、memory_store、memory_forget、web_fetch 和 git_operations。现有策略可以缩小任一工具目录的范围。

[tools]
optional = [] # minimal

用于最小安装加选定扩展的可调用名称：

[tools]
optional = ["calculator", "cron_list", "sessions_history"]

通配符与具名条目取并集：["*", "calculator"] 与 ["*"] 的选择结果相同，不会出现重复工具。Full 并非固定的工具数量，实际生效的工具目录由已配置的集成、运行时能力和策略共同决定。它并不会启用所有集成。选择某个工具不会安装浏览器或厂商 CLI，不会提供凭据，不会启用已禁用的集成，也不会授予权限。Full 同样保留 Code/ACP 现有的记忆排除规则。

选择发生在构造函数运行之前。未被选中的工具不会贡献任何 schema 或工具目录提示文本。风险配置、调用方收窄、审批、路径/网络策略和回执仍然适用。显式指定的 MCP 服务器、技能、插件和外设保留其现有的激活与授权路径。渐进式 schema 披露是一项独立功能,不属于这些设置。

要选择最小化安装,请在 [tools] 中设置 optional = [],或运行:

zeroclaw config set tools.optional '[]' --no-interactive

重新加载守护进程以使选择更改生效。配置架构版本保持为 3。对于没有 [tools] 的现有文件，zeroclaw config migrate 会记录 optional = ["*"]；普通保存同样会保留选择器意图。

构建与升级路径

一个发布矩阵包含十个构建目标，归档文件名保持不变。Android 为实验性目标，允许失败；发布需要其余九个目标全部通过。不存在第二个兼容性归档矩阵，也没有专用的 compat-tools 镜像。历史遗留的 all-features Docker 镜像比 dist 涵盖范围更广，包括额外的渠道和硬件功能。

dist 包含 tools-compat（tools-saas、tools-coding-cli、tools-external）。dist-compat 是同一构建的兼容别名。普通 Cargo 默认配置构建的体积更小：自定义源码构建可以省略适配器。在 optional 中命名的、未编译进二进制文件的外部适配器会给出明确的诊断信息；full 只选择该二进制文件实际包含的适配器，对其余适配器不报告任何信息。已启用的厂商/CLI 部分保留其现有的缺失功能诊断信息。运行时配置无法添加未编译进来的代码。请构建标准选择以恢复它：

# 从源码检出目录运行；请使用你打算运行的目标。
TARGET=x86_64-unknown-linux-gnu
FEATURES="$(cargo run --quiet --locked -p xtask --bin generate -- features --selection dist --target "$TARGET")"
cargo build --release --locked --bin zeroclaw --target "$TARGET" --no-default-features --features "$FEATURES"
# 对于本地 Linux 镜像，解析其构建目标的功能特性。
docker build -t zeroclaw-dist-local .

对于 Homebrew formula 中省略了 adapters 的安装，请将标准源码构建的二进制文件与包管理器安装的二进制文件并行运行，并使用其各自独立的配置、数据和服务路径。配置项无法改变 bottle 的编译功能。源码构建的用户还可以选择现有的单个tool-*功能或tools-compat，但仍需要进行运行时选择。

标准 dist 版本在七个受支持的原生 64 位目标上包含插件宿主和 plugins-wasm-cranelift：x86_64 和 aarch64 架构的 GNU 与 musl Linux、两种 macOS 架构，以及 x86_64 Windows MSVC。ARMv6/ARMv7 省略 Cranelift 和 Prometheus；实验性 Android 省略 Cranelift 和 WhatsApp Web。Cargo 默认配置不包含插件宿主。编译宿主后，plugins.enabled 和 plugins.auto_discover 仍为 false；同意、信任、授权和已配置的激活仍然适用。仅运行时的预编译 .cwasm 支持和 Pulley 不能替代可移植的注册表 .wasm 编译。目标策略来源于 Cargo.toml 中的 package.metadata.zeroclaw。

Minimal 是一种运行时目录选择。标准的 dist 仍然包含已编译的原生适配器，因此仅靠 minimal 并不能作为 工具抽离工作 二进制体积的证据。Container、Kubernetes 和 Nix 的默认配置省略了 [tools]，与其他配置一样加载完整版本；若要使用 minimal，请在其中设置 optional = []。

内置工具

以下内置功能在编译并选中后可用，full 配置会为其中所有功能启用；上方列出的十一个工具组成最小集。此列表并非核心集。关于核心集以及运行时注册表所构建的各工具所属层级，请参阅 层级与保留的核心集。

AnySearch 提供方

AnySearch 是 web_search_tool 的一个显式启用、需要主动选择的后端：

[web_search]
search_provider = "anysearch"
# 可选;省略则使用 AnySearch 较低的、有速率限制的匿名配额。
anysearch_api_key = "..."

搜索查询和已配置的结果数量上限会发送至 https://api.anysearch.com/v1/search。配置了 anysearch_api_key 时，ZeroClaw 仅将其作为 Bearer 授权头发送；未配置密钥时，不会发送 Authorization 头。因此，即使在匿名模式下，选择该提供方也会把搜索查询发送给第三方服务。它不会更改默认提供方，也不会作为自动回退使用。

额外的第一方内置项，包含在完整版中，不包含在精简版中：

选定的工具还保留以下前提条件：

内置架构发现

通过 ZeroCode Config 编辑器在智能体的运行时配置文件上启用 deferred_builtin_tools，以减少发送给模型的内置工具目录。该选项默认为 false，即保持即时加载 schema。此设置与 MCP 的 deferred_loading 选项相互独立。

当启用时，已获许可的 shell、file_read、file_write、file_edit、memory_recall 和 memory_store 工具的架构保持可见。其他已启用的内置工具以紧凑的发现列表形式呈现。模型使用 tool_search 配合关键词或 select:<tool_name> 来检索完整定义。被选中的架构会出现在后续的原生工具请求中；文本提供方则在搜索结果中接收该定义。

工具发现不会授予权限，也不会改变工具审批。Agent 策略、委托主体限制和调用方白名单仍然适用，会话收窄工具集之后同样如此。内置可执行程序保留在现有的限定范围注册表中，因此记忆路由不会保留单独的过期工具实例。如果策略不允许 tool_search，其余内置工具 schema 保持即时加载。工具列表端点仍会列出完整的已准入注册表。

扩展协议

除了内置工具外，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 是一个允许列表。省略该字段与显式设置为空列表（allowed_tools = []）含义相同，都表示遗留状态：不施加任何授权约束。非空列表对内置工具而言是一个封闭集合（并且，通过下文的 MCP 例外，会自动放行带命名空间的 MCP 工具）。空列表不表示全部拒绝；若要实现全部拒绝，请设置同级字段 deny_all_tools = true，它会同时拒绝内置工具、MCP 工具和技能定义的工具。同时设置 deny_all_tools = true 和非空的 allowed_tools 是配置错误，加载时会被拒绝。
• 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 的风险配置文件会自动允许它们。

如果你需要在完全自主模式下进行更细粒度的管控,可以把敏感工具放进每个配置文件中的 always_ask 列表:即使 level = "full",这些工具仍会提示确认(或失败关闭)。只有当你需要整套风险等级矩阵时,才需要将配置文件切换为 read_only 或 supervised;如果只需要处理少数例外情况,则无需这样做。

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

另见

• MCP
• 工具执行生命周期
• ACP
• 浏览器自动化
• 安全 → 概述