配置 — 工具策略

决定某次运行可以调用哪些工具的策略层：tools.profile、工具组、沙箱工具门、tools.codeMode，以及在其之上评估的 allow/deny 策略面。

工具配置文件¶

tools.profile 在 tools.allow/tools.deny 之前设置基础允许列表：

full 配置文件选择工具；它不会授予 完全访问 执行权限。 聊天中的 执行权限 菜单控制该会话中可用工具可以执行的操作。全局、代理、提供程序、allow/deny、所有者、文件系统、沙箱和执行限制仍然适用。目录条目并不意味着工具或插件已在当前会话中配置、连接或获得授权。

代理的 工具 设置包含运行依赖工具，例如 github_identity_status、github_publish 和 transcripts，因此 全部禁用 还会为它们添加显式拒绝。它们的目录行不会绕过 GitHub 工作区和身份检查，也不会绕过会议转录调用者检查。

coding 和 messaging 还包含 主题工具，并隐式允许 bundle-mcp（已配置的 MCP 服务器）。

tts 工具 不属于任何受限配置文件。若要允许处于 minimal、coding 或 messaging 的代理调用它，请将 tts 添加到 tools.alsoAllow。自动 TTS 不是工具，因此配置文件不会影响它。

未设置的配置文件同样会使核心工具保持未过滤状态，但其本身不会选择可选插件工具。显式的 full 会为插件工具选择贡献一个通配符，包括来自已启用插件的可选工具。插件配置、可用性以及独立策略限制仍然适用。

minimal、coding 和 messaging 配置文件包含 gateway，但仅包含 update.run 操作。这让所有者可以通过现有工具请求 OpenClaw 更新，而无需授予配置读取权限。更新使用与 /update 和 Control UI 相同的 Gateway 处理程序。外部聊天更新需要当前所有者授权和 commands.restart；Control UI 更新保留其操作员授权。

full 配置文件和未设置的配置文件会保留该工具的配置读取操作。在受限配置文件中，请显式将 gateway 添加到 tools.alsoAllow，以启用 config.get 和 config.schema.lookup。如果特定提供程序的配置文件也受限，其 alsoAllow 也必须授予 gateway。现有的全局、代理、提供程序、会话、沙箱和运行时 allow/deny 限制仍决定该工具是否可用。子代理和非所有者限制仍然适用。

工具组¶

suggest_task 允许代理提出已确认的后续工作，而不会立即开始执行。工作目录必须是绝对路径，但不需要是 Git 检出。支持本地调试和非代码任务。Control UI 会将标题和摘要显示为可操作的标签；由 Gateway 支持的 TUI 会显示等效的交互式提示。在新会话中开始 会在该目录中打开一个普通会话，并发送完整的任务提示。新会话会被指示：如果隔离变得必要，在创建或切换到 worktree 之前先询问用户。没有预先选择 worktree 或执行目标。dismiss_task 通过 suggest_task 返回的临时 task_id 撤回仍处于待处理状态的提议。

只有当发起操作的操作界面能够接收并处理 Gateway 任务建议事件时，才会提供这些工具。通道会话和本地/嵌入式 TUI 会话不会接收这些事件；通道传输需要在能够安全暴露此流程之前，具备可移植的类型化任务操作。建议是进程本地的，Gateway 重启后会消失。这两个工具仍保留在 coding 配置和 group:sessions 中，因此当界面支持它们时，常规的 tools.allow 和 tools.deny 策略会自动配置它们。

openclaw 负责 OpenClaw 的设置和修复。它同时属于 group:automation 和 group:openclaw，因此现有的分组允许和拒绝现在都会 包含此辅助工具。分组拒绝会覆盖显式的 openclaw 允许。该 辅助工具不会添加到 minimal、coding 或 messaging；请使用 tools.alsoAllow 在受限配置中选择它。目录发现不会绕过其 所有者、沙箱、直接调用或执行权限检查。

pdf 同时属于 group:media 和 group:openclaw。分组拒绝也涵盖 PDF，并会覆盖显式的 pdf 允许项。如果现有配置需要保留 PDF 访问权限，请移除或缩小冲突的分组拒绝。分组授权不会绕过 PDF 模型和身份验证要求。

transcripts 出现在目录的 Media 部分，但不是 group:media 或 group:openclaw 的成员，因此保留现有的分组授权和拒绝。 请通过名称显式选择它，或通过完整配置选择；受限配置可以 使用 tools.alsoAllow。当前调用者和捕获访问检查仍然适用。

沙箱工具策略中的 MCP 与插件工具¶

已配置的 MCP 服务器会在 bundle-mcp 插件 ID 下作为插件拥有的工具暴露。常规工具配置可以允许它们，但 tools.sandbox.tools 是沙箱会话的额外关卡。如果沙箱模式为 "all" 或 "non-main"，当 MCP/插件工具需要可见时，请在沙箱工具允许列表中包括以下其中一项：

• bundle-mcp 用于来自 mcp.servers 的 OpenClaw 管理的 MCP 服务器
• 特定原生插件的插件 id
• group:plugins 用于所有已加载的插件拥有的工具
• 当你只想使用一个服务器时，使用精确的 MCP 服务器工具名称或服务器通配符，例如 outlook__send_mail 或 outlook__*

服务器通配符使用 provider-safe 的 MCP 服务器前缀，而不一定是原始的 mcp.servers 键。非 [A-Za-z0-9_-] 字符会变为 -，不以字母开头的名称会添加 mcp- 前缀，过长或重复的前缀可能会被截断或添加后缀；例如，mcp.servers["Outlook Graph"] 会使用类似 outlook-graph__* 的通配符。

每次运行的 toolsAllow 上限也接受针对已配置 MCP 服务器的通配符，例如 outlook* 或 out*graph*。这些通配符可能会触发跨所有已启用静态 MCP 服务器的目录发现，就像 outlook__* 一样；它们不会限制哪些服务器连接。发现过程是保守的，即使最终没有工具匹配也可能运行。最终的工具允许/拒绝策略和沙箱策略仍然适用，已禁用的服务器仍会被排除，除非由会话覆盖显式启用，并且请求者作用域服务器仍需要其已验证的请求者上下文。

{
  agents: { defaults: { sandbox: { mode: "all" } } },
  mcp: {
    servers: {
      outlook: { command: "node", args: ["./outlook-mcp.js"] },
    },
  },
  tools: {
    sandbox: {
      tools: {
        alsoAllow: ["web_search", "web_fetch", "memory_search", "memory_get", "bundle-mcp"],
      },
    },
  },
}

如果没有该沙箱层条目，MCP 服务器仍可能成功加载，但其工具会在 provider 请求之前被过滤。使用 openclaw doctor 来捕获 mcp.servers 中 OpenClaw 管理服务器的这种配置形态。从捆绑插件清单或 Claude .mcp.json 加载的 MCP 服务器使用相同的沙箱门控，但该诊断目前尚未枚举这些来源；如果它们的工具在沙箱化回合中消失，请使用相同的允许列表条目。

tools.codeMode¶

tools.codeMode 控制通用的 OpenClaw 代码模式界面。当对带有工具的某次运行启用时，常规 OpenClaw 工具会移到 guest 目录桥后面，MCP 工具可通过生成的 MCP 命名空间使用。模型通常可以看到 exec 和 wait；像 computer 这样其结构化结果无法跨越仅 JSON 桥的工具会保持直接可用。

enabled 默认为 false，即使对象设置了其他 Code Mode 选项也是如此。如果只想对目录条目标记了 compat.codeMode: "preferred" 的模型启用代码模式，请显式启用 "auto"。参见 Code Mode - 按模型自动激活。

executor 默认为 "node"，它使用 node:vm 进行受信任主机执行，而不是安全隔离。设置 "quickjs" 可使用捆绑的加固 guest 执行器。Agent 级设置会覆盖全局选择。有关信任边界和 继续行为，参见 Code Mode 执行器。

{
  tools: {
    codeMode: {
      enabled: "auto",
      executor: "node",
    },
  },
}

短写法也被接受：

{
  tools: { codeMode: "auto" },
}

enabled: true 会为每个具备工具能力的运行强制开启代码模式，无论模型如何。

在代码模式中，MCP 声明通过只读虚拟 API 文件表面暴露。Guest 代码可以调用 API.list("mcp") 和 API.read("mcp/<server>.d.ts")，在调用 MCP.<server>.<tool>() 之前检查 TypeScript 风格的签名。有关 运行时契约、限制和调试步骤，参见 Code Mode。

tools.allow / tools.deny¶

全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 * 通配符。即使 Docker 沙箱关闭时也会应用。

{
  tools: { deny: ["browser", "canvas"] },
}

write 和 apply_patch 是独立的工具 id。allow: ["write"] 也会为兼容模型启用 apply_patch，但 deny: ["write"] 不会拒绝 apply_patch。若要阻止所有文件修改，请拒绝 group:fs 或显式列出每个修改工具：

{
  tools: { deny: ["write", "edit", "apply_patch"] },
}

图像检查工具是 view_image。如果旧配置仍在允许、alsoAllow 或拒绝列表中命名 image，请运行 openclaw doctor --fix 以重写受支持的全局、按 agent、provider、沙箱、发送者、通道和 Gateway 策略表面。Doctor 会保留可能仍匹配其他工具的模式，例如 image*，并在该模式不再覆盖 检查时添加 view_image。已经覆盖两个名称的模式，例如 * 或 *image*， 保持不变。

tools.byProvider¶

进一步限制特定 provider 或模型的工具。顺序：基础 profile → provider profile → allow/deny。

{
  tools: {
    profile: "coding",
    byProvider: {
      anthropic: { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

tools.toolsBySender¶

限制当前回合来源请求者的工具。这是在通道访问控制之上的纵深防御；发送者值必须来自通道适配器，而不是消息文本。它不会验证模型提示中的其他内容；参见 请求者作用域控制和提示上下文。

{
  tools: {
    toolsBySender: {
      "channel:discord:1234567890123": { alsoAllow: ["group:fs"] },
      "id:guest-user-id": { deny: ["group:runtime", "group:fs"] },
      "*": { deny: ["exec", "process", "write", "edit", "apply_patch"] },
    },
  },
}

键使用显式前缀：channel:<channelId>:<senderId>、id:<senderId>、e164:<phone>、username:<handle>、name:<displayName> 或 "*"。通道 id 是规范的 OpenClaw id；诸如 teams 之类的别名会规范化为 msteams。运行 openclaw doctor --fix 可将已弃用的无前缀键迁移到 id: 条目。匹配顺序为 channel+id、id、e164、username、name，最后是通配符。

每个代理的 agents.entries.*.tools.toolsBySender 在匹配时会覆盖全局发送者匹配，即使策略为空 {}。

tools.elevated¶

控制沙箱外的高权限 exec 访问：

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}

• 每个代理的覆盖项（agents.entries.*.tools.elevated）只能进一步限制。
• /elevated on|off|ask|full 按会话存储状态；内联指令仅应用于单条消息。
• 高权限 exec 会绕过沙箱，并使用配置的逃逸路径（默认为 gateway，当 exec 目标为 node 时为 node）。