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

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

> \[!NOTE] 所有工具配置都位于 `openclaw.json`（或等效配置文件）的 `tools` 块中。配置的优先级、覆盖规则与验证方式参见[第四章”配置与模型接入”](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models)。

## 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` | `full`    | 可选值：`minimal`, `coding`, `messaging`, `full`；不设置时等同 `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 文档](https://docs.openclaw.ai/tools#tool-profiles-base-allowlist)。

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

**优先级速查表**

在评估一次工具调用是否被允许时，系统按以下优先级从高到低判定：

| 优先级   | 规则层                               | 说明                                            |
| ----- | --------------------------------- | --------------------------------------------- |
| 1（最高） | `tools.deny`                      | 命中即拒绝，无论其他规则如何配置                              |
| 2     | `channels.*.groups.*.tools.deny`  | 渠道/群组级拒绝，叠加在全局规则之上                            |
| 3     | `channels.*.groups.*.tools.allow` | 渠道/群组级允许                                      |
| 4     | `tools.allow`                     | 全局允许列表                                        |
| 5（最低） | `tools.profile`                   | 基础工具集合（`minimal`/`coding`/`messaging`/`full`） |

一条经验法则：**拒绝规则永远优先于允许规则**。

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

* 通配符：支持 `*`（大小写不敏感）。
* 优先级：deny 覆盖 allow。
* 作用范围：先应用全局规则，再叠加命中的渠道/群组级工具限制。

> \[!WARNING] **通配符滥用**：在 `allow` 列表中过度使用 `*` 意味着对所有未知插件无条件授权，容易导致权限被静默放大。建议必须严控 `allowFrom`，避免 `*`，并总是将验证命令（如 `security audit`）纳入发布前检查。

> \[!NOTE] **`tools.elevated` 不是工具放行机制，而是 `exec` 专用的宿主机逃逸口**。当智能体运行在沙箱中时，`elevated` 允许 `exec` 命令在宿主机而非容器内执行，但它**不授予额外工具访问权**——工具的允许/拒绝仍完全由上述优先级表决定。`elevated` 支持全局配置（`tools.elevated.*`）和按智能体配置（`agents.list[].tools.elevated.*`），可通过 `allowFrom` 限定可触发的供应商。详见 [Sandbox vs Tool Policy vs Elevated](https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated)。

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

```jsonc
{
  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. **模型回复用户**：“抱歉，我没有权限执行删除操作。请联系具备集群管理权限的运维同事，或在运维终端手动执行。”

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

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

配置示例：

```jsonc
{
  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 配对、群聊策略与访问边界](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop/3.4_pairing_groups)

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

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

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

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

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

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

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

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

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

操作示例：

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

***