5.2 工具策略：允许、拒绝与分层策略

本节以官方工具治理为准，把“能不能调用工具”落到可配置、可审计的策略面。重点包括 tools.allow 与 tools.deny 的匹配语义、tools.profile 的默认策略选择、以及 channels.*.groups.*.tools 的按渠道/群组分层治理。目标是让系统默认安全、按需放开，并且在事故复盘时能回答“为什么这次允许、那次拒绝”。

5.2.1 官方工具策略结构：四个核心块

官方配置可拆成四个关键块：

• tools.allow：全局允许列表，支持通配符。

• tools.deny：全局拒绝列表，支持通配符，且优先级高于 allow。

• tools.profile：选择默认工具配置文件（minimal/coding/messaging/full）。

• channels.*.groups.*.tools：按渠道与群组分层限制工具（含 allow/deny 与 toolsBySender）。

一个重要默认行为是：若仅配置 deny，其余工具仍默认可用。生产环境应显式收敛高风险工具。

说明：本文中的 tool id / 通配符模式用于解释治理方法与分层思路；具体可用工具与精确命名请以你的版本、已启用插件与 status --deep 的实际输出为准。

5.2.2 工具与策略概念速查表

在深入配置之前，建议先明确系统里的概念与实际字段的映射关系：

概念	配置字段	默认值	别名或补充说明
默认场景模板	tools.profile	minimal	可选值：minimal, coding, messaging, full 等
工具分组	group:* 前缀	(根据版本自适应)	用于批量控制同类工具（如 group:runtime 指代命令执行类）
全局允许清单	tools.allow	[]	在严格配置下需显式声明
全局拒绝清单	tools.deny	[]	优先级最高：即使 allow 放行，命中 deny 也会被阻断

各 profile 包含的工具组如下：

Profile	包含的工具/组
minimal	仅 session_status
coding	group:fs、group:runtime、group:sessions、memory_search、memory_get、image
messaging	group:messaging、sessions_list、sessions_history、sessions_send、session_status
full	无限制（等同不设置 profile）

官方还支持通过 agents.list[].tools.profile 按智能体覆盖全局 profile。详见 Tools 文档。

5.2.3 allow/deny 语义：通配符与优先级

官方文档给出的关键语义：

• 通配符：支持 *（大小写不敏感）。

• 优先级：deny 覆盖 allow。

• 作用范围：先应用全局规则，再叠加命中的渠道/群组级工具限制。

[!WARNING] 通配符脚枪与 elevated 执行特权：在 allow 列表中过度使用 *（尤其是配合 tools.elevated 绕过沙箱提权时）意味着对所有未知插件无条件授权，极易造成权限静默放大。建议必须严控 allowFrom，避免 *，并总是将验证命令（如 security audit）纳入发布前检查。

注意：tools.elevated 是全局且基于发送者的配置，不能在 agents.list[].tools 中按智能体单独设置。如需限制特定智能体的提权行为，应在该智能体的 tools.deny 中禁止 exec。

配置示例（从“默认全开”收敛到“默认禁 shell 写操作”）：

{
  tools: {
    allow: ['*'],
    deny: ['group:runtime', 'write', 'edit', 'apply_patch'],
  },
}

具体例子：一次越权操作被拦截的完整链路

场景：部署在 Telegram 群的研发助手，某用户说“帮我删掉预发环境的那个出错的 Pod”。

1. 模型判定：模型推理后输出工具调用意图 exec，参数为 kubectl delete pod error-pod-xxx -n staging。

2. 策略校验：运行时检查全局 tools.deny 列表，发现 exec (或 group:runtime) 命中 deny 规则。

3. 拦截回注：系统不执行该命令，而是把拒绝原因回注到对话中。

4. 模型回复用户：“抱歉，我没有权限执行删除操作。请联系具备集群管理权限的运维同事，或在运维终端手动执行。”

在日志中，这条拦截会留下清晰的审计记录：

{
  "ts": "2026-02-20T10:30:15Z",
  "trace_id": "t-20260220-042",
  "event": "tool_denied",
  "tool": "exec",
  "rule": "tools.deny: group:runtime",
  "agent": "dev_assistant",
  "channel": "telegram",
  "sender": "user_987654"
}

这就是为什么安全边界必须由工具策略兜底，而不是写在提示词里——即使模型“想”执行，策略也能确定性地拦截。

5.2.4 按渠道与群组分层治理工具

当系统进入多渠道、多群、多入口场景后，官方提供了按渠道/群组粒度限制工具的能力：在 channels.*.groups.*.tools 下配置 allow/deny，并可通过 toolsBySender 做按发送者覆盖。参考：https://docs.openclaw.ai/channels/groups#groupchannel-tool-restrictions-optional。

具体例子：运维内部群 vs 外部客服群 假设同一个 OpenClaw 实例同时服务于外部 WhatsApp 群与内部研发 Telegram 群：

• 外部客服群：作为基础配置，只允许使用 web_search 或特定知识库工具解答问题。

• 内部研发群：对于特定的管理员账号（如 123456789），允许通过 toolsBySender 放开 group:runtime 这类命令执行工具来运行受限脚本；其他研发成员依然受基础策略管控。

配置示例：

{
  tools: {
    profile: 'coding',
    deny: ['group:runtime'],
  },
  channels: {
    whatsapp: {
      groups: {
        '*': {
          tools: { deny: ['group:runtime'] },
        },
      },
    },
    telegram: {
      groups: {
        '*': {
          tools: { deny: ['group:runtime', 'write', 'edit'] },
          toolsBySender: {
            '123456789': { alsoAllow: ['group:runtime'] },
          },
        },
      },
    },
  },
}

建议把“群聊策略更保守”作为运行基线。群聊策略见第3章，工具治理与渠道治理应联动。

• 3.4 配对、群聊策略与访问边界

5.2.5 按模型供应商定制工具策略

官方还支持通过 tools.byProvider 按模型供应商或具体模型定制工具策略。例如，对某些工具调用能力较弱的模型，可以限定其只使用最小工具集：

{
  tools: {
    profile: 'coding',
    byProvider: {
      'google-antigravity': { profile: 'minimal' },
      'openai/gpt-5.2': { allow: ['group:fs', 'sessions_list'] },
    },
  },
}

详见 Tools 文档。

5.2.6 子智能体工具限制：深度感知的分层禁用

当主智能体通过 sessions_spawn 派生子智能体时，子智能体的工具可用范围会被自动收窄。这是一个系统级的硬编码安全边界——即使配置中没有显式声明 deny，以下工具也会被禁用。了解这些隐式限制可以避免“子智能体为什么调不了某个工具”的排障弯路。

对所有子智能体禁用的工具（SUBAGENT_TOOL_DENY_ALWAYS）：

工具	禁用原因
gateway	系统管理工具，子智能体不应操控网关
agents_list	智能体列表属于管理面
whatsapp_login	交互式设置流程，不适合自动化子任务
session_status	状态查询应由父智能体统一管理
cron	调度权限应收敛在顶层
memory_search / memory_get	子智能体应通过 spawn prompt 接收相关信息，而非自行检索全局记忆
sessions_send	子智能体应通过 announce 协议回传结果，而非直接发消息

对叶子节点额外禁用的工具（SUBAGENT_TOOL_DENY_LEAF）：

当子智能体的生成深度达到 maxSpawnDepth（即不能再派生下级）时，还会额外禁用：

工具	禁用原因
sessions_spawn	叶子节点不能再派生子智能体
sessions_list / sessions_history	会话管理工具仅对协调者（orchestrator）开放

判定公式：isLeaf = depth >= max(1, floor(maxSpawnDepth))。也就是说，深度为 1 且 maxSpawnDepth 为 1 的子智能体就已经是叶子节点。

配置覆盖：系统级禁用可通过 tools.subagents.tools.alsoAllow 显式放行。例如，如果确实需要子智能体访问记忆：

{
  tools: {
    subagents: {
      tools: {
        alsoAllow: ["memory_search"]  // 显式覆盖系统级禁用
      }
    }
  }
}

这一设计体现了“纵深防御”原则：即使父智能体的提示词没有限制子智能体的行为，系统层面也会确保权限不会无限传递。

5.2.7 验收与回归：用配置证据与日志证据闭环

工具策略是否生效，建议用两类证据验收：

• 静态证据：配置里是否存在预期的 tools.deny 与 channels.*.groups.*.tools。

• 动态证据：日志是否出现工具允许/拒绝事件，并可追溯命中的策略键。

操作示例：

openclaw doctor --fix
openclaw status --deep
openclaw logs --follow --json

---

📚 延伸阅读：工具策略的设计理念与大模型安全攻防密切相关。关于提示注入、越权执行等攻击模式的深入分析，参见 《大模型安全权威指南》。