> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills/5.2_tool_policy.md).

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

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

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

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

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

* `tools.allow`：全局允许列表，支持通配符。
* `tools.deny`：全局拒绝列表，支持通配符，且优先级高于 allow。
* `tools.profile`：选择默认工具配置文件（`minimal`/`coding`/`messaging`/`full`）。
* 渠道分层策略：按具体渠道的群组/房间/peer 配置工具限制，例如 Telegram / WhatsApp 的 `groups.*`、Discord 的 `guilds.*.channels.*`、Slack 的 `channels.*` 等（含 `allow`/`deny` 与发送者覆盖）。

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

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

## 5.2.2 工具与策略概念速查表

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

| 概念     | 配置字段            | 默认值                        | 别名或补充说明                                                                                              |
| ------ | --------------- | -------------------------- | ---------------------------------------------------------------------------------------------------- |
| 默认场景模板 | `tools.profile` | `full` / 本地新配置常写入 `coding` | 可选值：`minimal`, `coding`, `messaging`, `full`；原始未设置语义接近 `full`，但当前本地 onboarding 生成的配置通常会显式使用 `coding` |
| 工具分组   | `group:*` 前缀    | (根据版本自适应)                  | 用于批量控制同类工具（如 `group:runtime` 指代命令执行类）                                                                |
| 全局允许清单 | `tools.allow`   | `[]`                       | 在严格配置下需显式声明                                                                                          |
| 全局拒绝清单 | `tools.deny`    | `[]`                       | 优先级最高：即使 allow 放行，命中 deny 也会被阻断                                                                      |

各 profile 包含的工具组如下：

| Profile     | 包含的工具/组                                                                                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimal`   | 仅 `session_status`                                                                                                                                                    |
| `coding`    | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate`；已配置的 bundle MCP 工具会通过 `bundle-mcp` overlay 暴露 |
| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status`；已配置的 bundle MCP 工具会通过 `bundle-mcp` overlay 暴露                                   |
| `full`      | 无限制（等同不设置 profile）                                                                                                                                                    |

官方还支持通过 `agents.list[].tools.profile` 按智能体覆盖全局 profile。详见 [Tools 文档](https://docs.openclaw.ai/tools#tool-profiles)。

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

**策略流水线速查**

在评估一次工具调用是否被允许时，系统按策略流水线逐层过滤候选工具：`tools.profile` 与 `tools.alsoAllow`、provider profile、全局策略、provider 策略、agent 策略、agent provider 策略、渠道/群组策略，最后再叠加 sandbox 与 subagent 策略。每一层内部都是 `deny` 优先；被前序 profile 或策略移除的工具，不能靠后续普通 `allow` 重新放回，只能使用对应层支持的 `alsoAllow` 做有意扩展。

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

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

> \[!WARNING] **通配符滥用**：在 `allow` 列表中过度使用 `*` 意味着对所有未知插件无条件授权，容易导致权限被静默放大。建议优先收紧 `tools.allow` / `tools.deny` 与渠道分层规则，避免长期保留 `allow: ['*']`，并总是将验证命令（如 `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",
  "traceId": "t-20260220-042",
  "event": "blocked_tool_call",
  "tool": "exec",
  "rule": "tools.deny: group:runtime",
  "agent": "dev_assistant",
  "channel": "telegram",
  "sender": "user_987654"
}
```

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

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

当系统进入多渠道、多群、多入口场景后，官方提供了按渠道、群组或频道粒度限制工具的能力：例如 Telegram / WhatsApp 可在 `groups.*.tools` 下配置 `allow`/`deny`，Discord 可按 `guilds.*.channels.*.tools` 收敛，Slack 可按频道配置，并可通过 `toolsBySender` 做按发送者覆盖。支持的精确路径以当前渠道文档和 `config schema` 为准。参考：[按群组限制工具](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: ['write', 'edit', 'apply_patch'],
  },
  channels: {
    whatsapp: {
      groups: {
        '*': {
          tools: { deny: ['group:runtime'] },
        },
      },
    },
    telegram: {
      groups: {
        '*': {
          tools: { deny: ['group:runtime', 'write', 'edit'] },
          toolsBySender: {
            'id:123456789': { alsoAllow: ['group:runtime'] },
          },
        },
      },
    },
  },
}
```

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

* [3.4 本地访问边界与设备批准](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop/3.4_pairing_groups.md)

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

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

```jsonc
{
  tools: {
    profile: 'coding',
    byProvider: {
      'google-antigravity': { profile: 'minimal' },
      'openai/<model-id>': { allow: ['group:fs', 'sessions_list'] },
    },
  },
}
```

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

## 5.2.6 子智能体工具限制：深度感知的分层收窄

当主智能体通过 `sessions_spawn` 派生子智能体时，OpenClaw 会先按父智能体或目标智能体的 profile 与工具策略解析可用工具，再叠加子智能体限制层。默认情况下，子智能体不会拿到会话类与系统类工具；当 `maxSpawnDepth >= 2` 时，深度 1 的 orchestrator 子智能体才会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 与 `sessions_history`，用于管理自己的下级。深度 2 及更深的叶子节点不能继续派生子智能体。

**默认限制的典型会话工具**：

| 工具                                   | 限制原因                                   |
| ------------------------------------ | -------------------------------------- |
| `sessions_list` / `sessions_history` | 会话管理与历史读取应默认收敛；仅 orchestrator 深度按配置开放。 |
| `sessions_send`                      | 子智能体通常通过 announce 链路回传结果，而非直接向外发消息。    |
| `sessions_spawn` / `subagents`       | 只有明确启用嵌套并处于 orchestrator 深度时才开放。       |

**配置收窄**：`tools.subagents.tools.allow` / `tools.subagents.tools.deny` 用于进一步限制子智能体工具面；`deny` 优先，`allow` 一旦设置就变成最终 allow-only 过滤器，不能把 profile 阶段已经移除的工具加回来。例如：

```jsonc
{
  tools: {
    subagents: {
      tools: {
        deny: ["gateway", "cron"],
        allow: ["read", "exec", "process"]
      }
    }
  }
}
```

如果确实需要给子智能体增加 profile 之外的工具，应在 profile 阶段使用顶层 `tools.alsoAllow` 或 per-agent `agents.list[].tools.alsoAllow`，然后再用子智能体 allow/deny 做收敛。不要把 `tools.subagents.tools.allow` 理解成“恢复被 profile 移除的工具”。

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

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

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

操作示例：

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

***