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'],
  },
}
```sql

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

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

1. **模型判定**：模型推理后输出工具调用意图 `exec`，参数为 `kubectl delete pod error-pod-xxx -n staging`。
2. **策略校验**：运行时检查全局 `tools.deny` 列表，发现 `exec` (或 `group:runtime`) 命中 deny 规则。
3. **拦截回注**：系统不执行该命令，而是把拒绝原因回注到对话中。
4. **模型回复用户**：“抱歉，我没有权限执行删除操作。请联系具备集群管理权限的运维同事，或在运维终端手动执行。”

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

```json
{
  "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"
}
```text

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

### 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` 这类命令执行工具来运行受限脚本；其他研发成员依然受基础策略管控。

配置示例：

```json5
{
  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'] },
          },
        },
      },
    },
  },
}
```text

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

- [3.4 配对、群聊策略与访问边界](../03_minimal_loop/3.4_pairing_groups.md)

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

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

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

详见 [Tools 文档](https://docs.openclaw.ai/tools#provider-specific-tool-policy)。

### 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` 显式放行。例如，如果确实需要子智能体访问记忆：

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

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

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

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

- 静态证据：配置里是否存在预期的 `tools.deny` 与 `channels.*.groups.*.tools`。
- 动态证据：日志是否出现工具允许/拒绝事件，并可追溯命中的策略键。

操作示例：

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

---

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