Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

MCP

ZeroClaw 是一个 MCP 客户端：它连接到外部 Model Context Protocol 服务器，并将其工具暴露给智能体。每个 MCP 工具都以 <server>__<tool> 形式进行命名空间隔离（例如 filesystem__read_file），因此来自不同服务器的工具绝不会发生冲突。

配置 MCP

MCP 支持默认已启用，但在 mcp.servers 下至少配置一个服务器，并且通过其 mcp_bundles 将该服务器授予某个代理之前，不会暴露任何外部 MCP 工具（参见下文的按代理服务器作用域）。可通过网关、zerocode 或 zeroclaw config set 配置：

zeroclaw config set mcp.servers.filesystem.command npx

将 mcp.enabled = false 设置为禁用 MCP 工具加载，无需移除服务器定义。

按代理划分的服务器作用域（mcp_bundles）

一个 [[mcp.servers]] 条目只会 定义 一个服务器。某个 agent 实际连接哪些服务器，由该 agent 的 agents.<alias>.mcp_bundles 决定，而且模型默认是安全的：省略不代表授予。

  • 即使 mcp.servers 非空，没有 mcp_bundles 的代理也不会连接到任何 MCP 服务器。
  • 一个 bundle [mcp_bundles.<alias>] 通过其 mcp.servers 的 name 来命名它授予的服务器，并可带有可选的 exclude 列表。某个 agent 的授权是其引用的每个 bundle 所包含服务器的并集，再减去这些 bundle 中任一者排除的任何名称（deny 优先）。
  • 未知的 bundle 别名，或与任何已配置服务器都不匹配的 bundle 服务器名称，都不会授予任何权限。两者都会按失败即拒绝处理，并且在配置校验中作为非致命警告报告，因此，拼写错误会缩小 agent 的访问范围，而不是扩大它。
[[mcp.servers]]
name = "filesystem"
command = "npx"

[mcp_bundles.files]
servers = ["filesystem"]

[agents.assistant]
mcp_bundles = ["files"]   # 连接到 `filesystem`；没有这个的 agent 不会获得任何 MCP servers
  • 捆绑更改会在会话重启时生效。解析器（Config::mcp_servers_for_agent）在会话/代理构建时运行；在会话处于活动状态时编辑 [mcp_bundles.*] 或 agents.<alias>.mcp_bundles 不会更改该会话已连接的服务器。结束并重启受影响的会话以获取新的授权。

这是 connection 边界（也就是代理会与之通信的所有服务器）。下面的 allowed_tools / excluded_tools 控制是在已授权服务器所暴露内容之上的、按工具划分的 capability 边界。

传输

服务器通过三种传输方式之一进行访问（transport 字段）：

传输何时使用必填字段
stdio（默认）你生成的本地进程（Node.js 或 Python MCP 服务器）command、可选的 args、env
http一个通过 HTTP POST 使用 MCP 通信的远程服务器url，可选的 headers
sse通过 HTTP + Server-Sent Events 进行 MCP 通信的远程服务器url，可选的 headers

env（stdio）和 headers（http/sse）作为密钥存储；headers 通常携带用于上游服务器的 Authorization: Bearer … 令牌。

通过网关、zerocode 或 zeroclaw config set 添加服务器（例如 zeroclaw config set mcp.servers.filesystem.command npx）。stdio 服务器需要 command 以及可选的 args/env；http/sse 服务器需要 url 以及可选的 headers。各字段对应的命令请参见下方字段表。

Parallel Search MCP 提供公共网页搜索和页面提取功能，无需 Parallel 账户或 API 密钥。免费访问有速率限制。其 Streamable HTTP 端点使用 ZeroClaw 的 http 传输方式：

[[mcp.servers]]
name = "parallel"
transport = "http"
url = "https://search.parallel.ai/mcp"
headers = { "User-Agent" = "ZeroClaw" }

[mcp_bundles.web]
servers = ["parallel"]

[agents.assistant]
mcp_bundles = ["web"]

User-Agent 用于在项目范围内标识 ZeroClaw，以便 Parallel 统计集成的整体使用情况，从而了解采用情况并提供支持。如果传输方式发生变化，请继续在 HTTP 请求中保留此标头。保留现有标头；如果你已经设置了 User-Agent，请在其现有的项目和 HTTP 客户端标记后追加 ZeroClaw，而不是替换它们。

将这些条目合并到现有的 config.toml 中，并使用需要授予访问权限的代理的别名。将 "web" 添加到该代理现有的 mcp_bundles 列表中，而不是替换其其他授权。如果 web 捆绑包已存在，则将 "parallel" 添加到其 servers 列表中。更改授权后，保持 mcp.enabled = true 并重启受影响的会话。

智能体随后可以使用 parallel__web_search 和 parallel__web_fetch，但需遵守其常规工具授权和审批策略。调用时，查询内容、请求的 URL 以及提供的任何目标（objective）或上下文信息都会发送至 Parallel。一旦获得访问权限，智能体可在工作过程中选择使用这些工具。要撤销访问权限，请从授予该智能体的每个 bundle 中移除 "parallel"，或将其添加到已授予 bundle 的 exclude 列表中，然后重启会话。

编辑服务器

三个界面编辑同一个 [[mcp.servers]] 表：

  • config.toml：手动编辑下方所述的键。完整的表会在保存时往返写回。
  • zerocode TUI（/config -> mcp.servers）：一流的逐字段编辑器。该部分为每个服务器显示一行，并以服务器的 name 标注；进入某一行即可将 transport、command / url、headers、env 和 tool_timeout_secs 作为独立字段进行编辑。+ Add 会创建一个以你提供的名称为初始值的新条目；从别名列表中删除则会移除该条目。name 字段不支持内联编辑，因为在编辑过程中重命名这一自然键会使进行中的引用失效；目前如需重命名，请使用仪表板或手动编辑 config.toml。
  • Web 仪表板（配置 -> MCP servers -> 某个服务器）：与 TUI 相同的字段界面，每个服务器一个表单。

env 和 headers 都是键值映射，因此两种 UI 都会先显示一个容器行，随后每个条目显示一行（env.GITHUB_TOKEN、headers.Authorization，……）：

  • 添加条目：在 zerocode 中，选中显示 [+ Add entry] 的 env（或 headers）行，按 Enter，输入名称后按 Enter，然后输入值（输入内容隐藏）并按 Enter。在仪表板中，使用名称/值输入框以及映射下方的 Add entry。条目会立即保存，并在静态存储时加密。
  • 修改值：像编辑其他机密一样，直接编辑该条目自己的行。
  • 删除条目：删除该条目所在的行（使用 zerocode 的删除行快捷键，或点击仪表板中的垃圾桶按钮，然后点击 Save）。

值永远不会显示；容器行仅列出条目名称。在命令行中，使用 zeroclaw config set mcp.servers.<name>.env.<KEY> 可添加或替换一个条目；将其设置为空值则会删除该条目。无法直接设置裸映射路径（mcp.servers.<name>.env）。同一编辑器适用于配置中的每个密钥键/值映射（例如提供商的 extra_headers）。

服务器字段

从 schema 生成的各服务器字段（[[mcp.servers]]）：

args string[] · default []

stdio 传输的命令参数。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.args 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.args 字段。

zeroclaw config

zeroclaw config set mcp.servers.args <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__args=
command string · default ""

用于 stdio 传输的可执行文件。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.command 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.command 字段。

zeroclaw config

zeroclaw config set mcp.servers.command <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__command=
env 🔑 secret map · default {}

stdio 传输的可选环境变量。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.env 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.env 字段。

zeroclaw config

zeroclaw config set mcp.servers.env.<KEY>    # masked input, stored encrypted
zeroclaw config set mcp.servers.env.<KEY> # 空值会删除该条目

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__env=
headers 🔑 secret map · default {}

用于 HTTP/SSE 传输的可选 HTTP 标头。视为机密：这些值通常携带用于上游 MCP 服务器的 Bearer 令牌。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.headers 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.headers 字段。

zeroclaw config

zeroclaw config set mcp.servers.headers.<KEY>    # masked input, stored encrypted
zeroclaw config set mcp.servers.headers.<KEY> # 空值会删除该条目

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__headers=
max_response_bytes integer? · default null

在读取时强制执行的单个 HTTP/SSE JSON-RPC 响应正文可接受的最大字节数，此时正文尚未被解析，也未对其中嵌入的资源进行实例化。遭到入侵或行为异常的服务器无法强制分配无界的响应正文。这是_编码后的网络传输_上限，而不是解码后的实例化预算：None/0 使用内置默认值 16,078,168 字节；该值经过设置，可确保完整的 10 MiB 解码后嵌入资源 blob（其 base64 扩展部分加上 JSON-RPC 包络开销）仍能容纳。另一个 10 MiB 数值是解析后应用的解码后聚合 blob 预算，而不是此网络传输上限。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers，并设置 mcp.servers.max_response_bytes 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.max_response_bytes 字段。

zeroclaw config

zeroclaw config set mcp.servers.max_response_bytes <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__max_response_bytes=
name string · default ""

用作工具前缀的显示名称（<server>__<tool>）。当通过 create_map_key("mcp.servers", "<name>") 创建条目时，会从提供的 map_key 填充；#[serde(default)] 让宏在名称注入之前先从 {} 默认构造。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.name 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.name 字段。

zeroclaw config

zeroclaw config set mcp.servers.name <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__name=
pinned_resources string[] · default []

在代理启动时读取一次并注入到系统提示中的资源 URI，作为不可信的、来自服务器的上下文。每个 URI 都通过此服务器上的 resources/read 读取；如果某个 pin 位于不支持声明资源的服务器上，或者该代理的工具策略拒绝了该服务器，则会跳过并给出警告。每次运行只读取一次（不会刷新；也没有订阅）。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.pinned_resources 字段。

zerocode

在 Config 面板中，设置 mcp.servers.pinned_resources 字段。

zeroclaw config

zeroclaw config set mcp.servers.pinned_resources <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__pinned_resources=
tls_ca_cert_path string? · default —

用于此服务器 HTTP/SSE 传输的 PEM 编码 CA 证书或证书包的绝对路径，除默认根证书外还将信任该证书或证书包。证书和主机名验证仍处于启用状态。该路径必须指向大小不超过 1 MiB 的普通文件；文件缺失、无法读取、为空、过大、不是普通文件或无效时，将直接导致连接错误，而不会回退到默认信任存储。设置后，配置的 URL 和任何公布的 SSE 消息端点都必须使用 HTTPS；明文 URL 和降级重定向会被拒绝。stdio 不使用此设置。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.tls_ca_cert_path 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.tls_ca_cert_path 字段。

zeroclaw config

zeroclaw config set mcp.servers.tls_ca_cert_path <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__tls_ca_cert_path=
tool_timeout_secs integer? · default null

每次调用的可选超时时间（以秒为单位，在校验时设有硬性上限）。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.tool_timeout_secs 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.tool_timeout_secs 字段。

zeroclaw config

zeroclaw config set mcp.servers.tool_timeout_secs <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__tool_timeout_secs=
transport McpTransport · default "stdio"

传输类型（默认：stdio）。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.transport 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.transport 字段。

zeroclaw config

zeroclaw config set mcp.servers.transport <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__transport=
url string? · default null

HTTP/SSE 传输的 URL。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.url 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.url 字段。

zeroclaw config

zeroclaw config set mcp.servers.url <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__url=

tool_timeout_secs 是一个可选的单次调用超时时间；它必须大于 0，且上限为 600 秒。

自定义 CA 信任

对于证书由私有 CA 签发的 HTTP 或 SSE 服务器，请将 tls_ca_cert_path 设置为包含一个或多个 PEM 编码 CA 证书的绝对路径。配置的证书会添加到默认信任存储；证书链、过期时间和主机名验证仍保持启用状态。

相对路径、缺失、不可读、为空、过大、非普通文件或无效的 CA 文件，对于该服务器而言都是不可恢复的连接错误。该路径解析后必须指向不超过 1 MiB 的普通文件。系统会跟随符号链接，因此证书轮换以及通过符号链接发布证书包的挂载 secret 布局都能按配置工作；解析后的文件会在打开后进行验证，解析到目录、设备或 FIFO 的符号链接会被拒绝。设置此字段后，ZeroClaw 绝不会禁用验证或静默回退。配置的服务器 URL 以及 SSE 服务器公布的任何消息端点都必须使用 https://；在发送请求标头或内容之前，明文 URL 和降级重定向都会被拒绝。此值会在 MCP 会话启动时应用；更改后请重启受影响的会话。删除该字段并重启会话即可恢复使用默认信任存储。Stdio 服务器会忽略此设置。

顶级字段

deferred_loading bool · default false

通过 tool_search 按需加载 MCP 工具 schema，而非急切地将其包含在 LLM 上下文窗口中。启用后，系统提示中仅列出工具名称；LLM 必须先调用 tool_search 获取完整 schema，然后才能调用延迟加载的工具。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp 并设置 mcp.deferred_loading 字段。

zerocode

在 Config 窗格中，设置 mcp.deferred_loading 字段。

zeroclaw config

zeroclaw config set mcp.deferred_loading <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__deferred_loading=
servers McpServerConfig[] · default []

已配置的 MCP 服务器。#[nested] 注解使宏在 map_key_sections() 中将其暴露为一个 List 部分，因此控制面板的 + Add MCP server 操作和 POST /api/config/map-key?path=mcp.servers&key=<name> 端点会自动识别它（网关侧无需手动维护表）。#[natural_key = "name"] 使该 Vec 启用按元素属性路由（参见 route_vec_path 和 Configurable derive 的 #[natural_key] 分支）。有了它，set_prop("mcp.servers.<name>.url", ...) 和 get_prop("mcp.servers.<name>.transport") 会解析到对应元素自身的 set_prop / get_prop，并且从控制面板 / TUI 的视角来看，mcp.servers 部分的行为就像一个 HashMap<String, McpServerConfig>。name 本身通过 set_prop 变为只读；重命名经由 rename_map_key 处理，它会就地修改 name 字段。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp 并设置 mcp.servers 字段。

zerocode

在 Config 窗格中，设置 mcp.servers 字段。

zeroclaw config

zeroclaw config set mcp.servers <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers=

延迟加载

mcp.deferred_loading 默认为 false，因此已配置的 MCP 工具会被预先加载到模型上下文中。将其设置为 true 可仅将 MCP 工具的名称放入系统提示词中；LLM 会在调用工具前先调用内置的 tool_search 工具来获取该工具的完整 schema。当服务器暴露大量工具时，这能保持初始上下文窗口较小。

安全与批准

MCP 工具调用与其他所有工具一样，都需要经过相同的审批关卡，并受代理的风险配置文件（risk_profiles.<alias>）约束。tool_search 发现步骤会被自动批准，以便延迟加载的 MCP 能在非交互式会话中正常工作，但从 MCP 服务器发现的工具仍然遵循正常的审批策略：

  • 在自主性 level = full 下,未被覆盖的工具调用不会弹出提示(包括 MCP 工具)。always_ask 中的名称(或 "*")仍会弹出提示,即使在 Full 模式下也是如此。
  • 否则，MCP 工具调用会提示确认，除非其带前缀的名称（<server>__<tool>）在配置文件的 auto_approve 列表中。auto_approve = ["*"] 会批准所有内容；像 auto_approve = ["filesystem__read_file"] 这样的精确条目则只批准该工具。
  • always_ask 则相反：其中列出的名称（或 "*"）始终会弹出确认提示，优先级高于 auto_approve 以及完全自主模式。

授权：allowed_tools / excluded_tools

审批门控决定何时工具调用需要人工批准。授权门控决定代理是否可以调用工具。这两者相互独立。

将三个 MCP 工具控件保持在各自独立的维度上：

控制范围用于
tool_filter_groups提示/上下文泄露决定模型在某一轮对话中可见哪些 MCP 工具模式。
auto_approve / always_ask审批策略判断所选 MCP 工具调用是否需要操作员批准。
allowed_tools / excluded_tools能力策略决定该风险配置文件可使用哪些带前缀的工具名称。

对于运行时发现的 MCP 工具，能力契约有一个 MCP 特定的例外：

  • 如果风险配置文件中的 allowed_tools 被省略或为空，则不施加任何授权约束；每个已发现的工具（MCP 或内置工具）均可调用。空列表是旧版的无限制状态，而不是全部拒绝。若要设置显式的全部拒绝门禁，请设置同级的 deny_all_tools = true：它同样会拒绝 MCP 工具（全部拒绝模式下不存在 __ 自动放行），且不能与非空的 allowed_tools 同时使用。
  • 如果 allowed_tools 非空，则任何名称包含 __（<server>__<tool> 约定）的 MCP 工具都会自动纳入生效的允许列表，而无需单独列出。非 MCP 内置工具仍然需要精确列出条目。
  • excluded_tools 始终会进行排除，包括从自动接纳的 MCP 集合中排除。要阻止单个 MCP 工具，例如 filesystem__write_file，同时保持 filesystem 服务器的其余部分可访问，请将其放入 excluded_tools。

原因在于：在这个例外之前，任何将 allowed_tools 列表固定下来以锁定其内置能力范围的 agent，都会无声地丢失所有 MCP 工具，即使是操作员显式配置的工具也不例外。代价是，在一个固定了 allow-list 的配置文件下，deny-list 现在成了操作员阻止破坏性 MCP 能力的主要手段。

如果你想要此更改之前的严格模式，即只允许你显式列出的 MCP 工具，而不自动放行 __，请将一个显式的 allowed_tools 条目与每个需要阻止的破坏性同级工具对应的 excluded_tools 条目组合起来：

[risk_profiles.assistant]
allowed_tools = [
  "file_read",
  "filesystem__read_file",
]
# 阻止原本会通过上面的 `__` 例外自动加入的破坏性同类工具。
excluded_tools = [
  "filesystem__write_file",
]
auto_approve = [
  "filesystem__read_file",
]

MCP __ 自动放行例外仅限于风险配置的 allowed_tools。调用方在每次运行时提供的允许列表，比如 cron 作业的 allowed_tools，或任何其他将显式列表传入运行时的受限调用，仍然按严格的显式列表交集处理，不会再叠加 __ 自动放行。将自身限制为 allowed_tools = ["cron_add"] 的 cron 作业，即使代理的风险配置原本会通过 __ 约定自动放行 filesystem__write_file，也不会把 filesystem__write_file 暴露给模型；无论配置了多少 MCP 服务器，每次运行时的收窄范围仍然是可靠的能力边界。

auto_approve 本身并不会向模型隐藏工具；它只是在模型选择该工具后自动回答审批询问。使用 tool_filter_groups 来减少提示噪声，使用 allowed_tools / excluded_tools 来强制实施能力边界。

有关每个配置文件的完整字段范围，请参阅 Autonomy levels；有关每个 MCP 字段及其默认值，请参阅 Config reference。

MCP 资源和提示词

除了 MCP tools，ZeroClaw 还会从已连接的服务器公开 MCP resources 和 prompts。

工具

有两个内置工具可用（受你的代理工具访问策略限制）：

  • mcp_resources: action: "list"（可选 server、cursor）列出资源；带 uri（前缀为 <server>__<uri>）的 action: "read" 返回内容。
  • mcp_prompts: action: "list" 列出提示；action: "get" 携带 name（前缀为 <server>__<name>）和可选的 arguments 时，返回渲染后的提示消息。

不通告 resource/prompt 能力的服务器会被跳过，对它们的调用会返回明确的“does not support”错误。

将资源固定到上下文中

每个 MCP 服务器条目都接受一个可选的 pinned_resources 字段：这是一个资源 URI 列表，会在启动时读取一次并注入到系统提示中。通过与定义服务器相同的配置入口（网关、zerocode，或 zeroclaw config set，如 Configure MCP 中所示）进行设置，指定你希望代理始终可用的资源。该字段默认为空，因此未设置它的服务器不受影响。

固定内容每次运行只读取一次（不实时刷新），并标记为 trust="untrusted-external"，因此模型将其视为数据，而不是指令。

工具结果中嵌入的资源 Blob

当 MCP tools/call 的结果中包含一个内容项，其结构为 type: "resource" 且嵌套了 blob（base64）时，ZeroClaw 不会将该 base64 内容转储到模型上下文中。相反，它会将字节数据落盘到会话工作区的 uploads/ 目录下（使用与 ACP 入站 resource.blob 相同的共享辅助函数和 10 MB 大小限制），并从面向模型的工具输出中屏蔽该 blob，替换为 materialized 引用：非图像 MIME 类型使用 [Document: …] 标记，图像 MIME 类型则使用保存后的纯路径；对于图像，会作为附件声明在工具结果上，而不是以标记形式写入文本。该行为由内容结构而非工具名称决定。物化不会自动将文件投递给 ACP 客户端；当需要出站投递时，智能体仍需调用 deliver_file。参见 ACP session/prompt blob 入站。

MCP 的另外两种二进制内容形式按如下方式映射。一个 type: "image" 项（包含 base64 data 与 mimeType）的处理方式相同：物化到磁盘，并将该内容项改写为一个文本项，其中包含保存后的纯路径；同时将该图片声明为工具结果的附件，多模态管线会将其提升为原生的 provider 图片内容块。该项的 annotations/_meta 及其他非二进制字段均予保留。仅物化视觉管线支持的位图格式：PNG、JPEG、WebP 和 GIF。当声明的 mimeType 指向上述类型之一时，磁盘文件扩展名由该 mimeType 推导（规范化为不区分大小写的核心类型，丢弃参数）；否则根据解码后字节的嗅探结果推导。扩展名必须与字节内容一致，因为加载器优先采用路径扩展名而非魔数（magic）。若图片的类型既不是受支持的声明类型，也无法识别为受支持的签名，则降级为 [attachment unavailable: …]，且不写入磁盘。type: "audio" 项在此路径中不进行物化，因为目前没有任何 provider 能将音频路径解析为内容块，因此其 data 会被剥离，替换为不触发物化的 [audio attachment: <mime>] 占位符。无论何种情况，原始 base64 都不会传递给模型，包括 data 为空或不是字符串的畸形 image/audio 项。

由于结果来自不受信任的服务器，在解码、哈希或写入任何载荷之前，每次调用会强制执行两项限制：每个 tools/call 结果最多 64 个可物化的二进制条目（资源 blob 加上有效的图像条目），以及所有条目估算解码后总大小最多 10 MiB。若结果超出任一限制，所有此类条目都会被降级为 [attachment unavailable: …] 标记，且不会向磁盘写入任何内容，因此大量空的或极小的条目无法迫使逐项处理。每个单独的载荷仍受相同的每文件 10 MB 限制约束。

除这些 解码后 的预算外，每个 HTTP/SSE MCP 服务器还具有传输层响应正文上限 max_response_bytes，该上限会在解析正文之前针对原始 编码后的 网络字节强制执行，因此服务器无法强制进行无界读取。它不是上面的 10 MiB 解码后限制：默认值为 16,078,168 bytes，这是 10 MiB 解码后聚合大小加上 JSON-RPC 封装预留空间后的 base64 扩展大小，因此接近上限的有效 blob 仍可完成物化。在服务器上设置 max_response_bytes 可覆盖此限制；设置为 0 或不设置则使用该默认值。

安全

资源和提示内容源自已配置的 MCP 服务器，并被视为不可信：在进入上下文之前，它会经过来源封装、秘密清理和长度限制。对 mcp_resources / mcp_prompts 以及特定服务器的访问由你代理的工具访问策略（风险配置）控制，并且在委派给子代理时会正确收紧。

示例：构建远程代理（gbr）

Build Remote Agent 是一款配对设备：手机应用可以旁观此 ZeroClaw 主机（也可以向其注入输入），通过免费的 MIT 许可 gbr-agent 实现。协议 gbr/1。由 Linespotting AB 开发的独立产品。与 xAI 或 SpaceX 无关联。

在 host 上运行 gbr-agent。不要将其复制到沙箱中。仅连接回环 Bot API http://127.0.0.1:8788，或通过 stdio 连接 gbr-mcp。手机仅作为旁观者，并拥有否决权。切勿在 config.toml 中以明文形式粘贴邮箱密钥。ZeroClaw 聊天渠道不属于 gbr/1。

环回地址限制的是 network 暴露范围，它不是进程身份验证。本地的其他进程仍可调用 :8788，除非你设置 GBR_BOT_REQUIRE_KEY=1，并通过 ZeroClaw 密钥托管的 MCP env 为 gbr-mcp 提供匹配的邮箱密钥（而不是在 config.toml 中写入明文邮箱密钥）。

gbr-mcp 会把工具调用参数以 info 级别记录到 ~/.gbr/logs/gbr-mcp-YYYY-MM-DD.jsonl，默认保留 7 天。密钥脱敏不会去除普通的注入文本。如需安全的基线配置，请在 ZeroCode Config 中为 gbr 服务器的 env 设置 GBR_MCP_LOG_BODIES=0。如果不希望在 ZeroClaw 历史之外再保留一份持久化数据，请删除或禁用这些日志。

省略 mcp_bundles 不等于授权：需要定义服务器并授予其权限。

需要 Node.js 20+（mcp/gbr-mcp 的 engines.node >=20）。固定使用 GitHub Release v0.6.2（先校验安装脚本的校验和，再校验二进制文件）。不要直接粘贴线上网站的 curl | bash。参见 PINNED-INSTALL.md。

Terminal 1（保持此进程运行）：

gbr-agent version    # 需要 v0.6.2
export GBR_BOT_REQUIRE_KEY=1
gbr-agent pair
gbr-agent run

配对完成后，请从手机的设置 -> Bot API 中获取邮箱密钥，或从主机配对文件 ~/.gbr/device.json 中的 mailbox_key 获取。已固定版本的 gbr-mcp 客户端从其选项或进程环境中读取 GBR_MAILBOX_KEY，不会加载该配对文件。启用 GBR_BOT_REQUIRE_KEY=1 时，若新的 shell 未提供该密钥，将导致未授权的 Bot API 请求。

终端 2（MCP 安装与诊断；gbr-agent run 必须已经启动）。将密钥粘贴到静默提示中，以免该值被存储在 shell 历史记录中：

git clone --branch v0.6.2 --depth 1 https://github.com/LinespottingOrg/GrokBuildRemote-Agents.git
cd GrokBuildRemote-Agents/mcp/gbr-mcp
node -v    # v20+
npm install --ignore-scripts
IFS= read -rs GBR_MAILBOX_KEY   # 粘贴密钥后按 Enter；不回显，不写入历史记录
export GBR_MAILBOX_KEY
export GBR_MCP_LOG_BODIES=0
node bin/gbr-mcp.js --diagnose

源标签已固定，但此版本没有 npm lockfile，因此依赖版本在安装时才解析。--ignore-scripts 可阻止依赖的生命周期脚本在安装期间运行；但它并不能使下载的依赖变得可信，也无法阻止这些依赖的代码在 MCP 服务器启动时运行。

上面的 export 行仅对当前这个诊断 shell 生效。它们并不会配置由 ZeroClaw 启动的 gbr 服务器。请定义该服务器并为其授权：

[[mcp.servers]]
name = "gbr"
command = "node"
args = ["/absolute/path/to/GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js"]

[mcp_bundles.gbr]
servers = ["gbr"]

[agents.assistant]
mcp_bundles = ["gbr"]

然后通过 ZeroCode Config（/config -> mcp.servers -> gbr -> env）为该服务器的 env 同时设置 GBR_MAILBOX_KEY 和 GBR_MCP_LOG_BODIES=0。GBR_MAILBOX_KEY 是敏感字段，请使用掩码输入提示（加密的密钥存储），或使用 1Password 引用 op://vault/item/field。不要将原始密钥写入 config.toml。对应的 CLI 命令如下：

zeroclaw config set mcp.servers.gbr.env.GBR_MAILBOX_KEY
zeroclaw config set mcp.servers.gbr.env.GBR_MCP_LOG_BODIES 0

所有 MCP 环境变量值都使用 ZeroClaw 的掩码密钥提示，因此末尾的 0 不会被当作取值消耗。请在该提示处输入 0。

重新启动受影响的会话（在更改 bundles 或 env 之后）。在使用 GBR_BOT_REQUIRE_KEY=1 运行 gbr-agent run 后，仅使用 HTTP 而未使用 MCP 时：

IFS= read -rs GBR_MAILBOX_KEY
export GBR_MAILBOX_KEY
curl -sS -H X-GBR-Key: $GBR_MAILBOX_KEY http://127.0.0.1:8788/health
curl -sS -H X-GBR-Key: $GBR_MAILBOX_KEY http://127.0.0.1:8788/v1/sessions

文档：BOT-API.md