第 1 章 引言

OpenClaw 是一个开源的个人 AI 助手框架，支持多渠道集成，包括 WhatsApp、Telegram、Discord、Slack 等主流 messaging 平台。通过灵活的插件系统，OpenClaw 能够连接各种外部服务，实现跨平台的智能助手功能。

工具系统在 OpenClaw 中的核心地位

工具系统是 OpenClaw 区别于普通聊天机器人的关键所在。它赋予 AI 助手执行 Shell 命令、读写文件、浏览器控制、发送消息等能力，使 AI 能够真正「行动」而非仅仅「对话」。OpenClaw 的核心工具包括：

• 执行工具：exec、process（bash 是 exec 的别名）
• 文件系统工具：read、write、edit、apply_patch
• 会话管理工具：sessions_list、sessions_history、sessions_send、sessions_spawn
• 网络工具：web_search、web_fetch
• UI 交互工具：browser、canvas
• 消息工具：message

为什么需要工具策略控制

随着 AI 助手能力的增强，安全风险也相应增长。工具策略控制基于以下安全原则：

1. 最小特权原则（Principle of Least Privilege）：只授予 AI 完成工作所需的最小工具集
2. 纵深防御（Defense in Depth）：通过 Sandbox、Tool Policy、Elevated 三层防护控制工具调用
3. 威胁模型隔离：将 AI 限定在特定执行环境中，防止恶意输入导致系统受损

⚠️ 错误的工具配置可能导致：
• Prompt injection 攻击导致敏感数据泄露
• 未授权的远程代码执行
• 文件系统被恶意访问或修改

文章结构导览

本文档系统阐述 OpenClaw 的工具策略控制机制，涵盖核心工具详解、工具组设计、策略配置、供应商限制、安全最佳实践及完整配置示例。适合 OpenClaw 管理员、开发者和安全工程师阅读。

第 2 章 11 类工具详解

OpenClaw 提供了一套完整的工具集，覆盖从文件操作到 AI 媒体生成的各类需求。本章详细介绍 11 类工具的功能、使用场景及安全注意事项。

2.1 Runtime（运行时工具）

运行时工具负责命令执行和进程管理，是 Agent 与操作系统交互的基础接口。

工具名称	功能描述
exec	执行 Shell 命令，支持后台运行、PTY 终端、超时控制等
process	进程管理，支持 poll（轮询状态）、log（读取日志）、write（写入输入）、kill（终止进程）

典型使用场景：

• 执行系统命令进行环境检查或软件安装
• 启动长时间运行的服务并监控其状态
• 与交互式 CLI 工具（如 Node.js REPL）进行会话

{
  "tool": "exec",
  "params": {
    "command": "python script.py",
    "background": true,
    "timeout": 300
  }
}

安全注意事项：
• 敏感操作需用户确认，避免执行破坏性命令
• 使用 elevated 参数时需额外审批
• 优先使用 trash 而非 rm，确保可恢复

2.2 FS（文件系统工具）

文件系统工具提供对本地文件的读写和精确编辑能力，是 Agent 处理代码和文档的核心工具。

工具名称	功能描述
read	读取文件内容，支持文本和图片，可指定偏移量和行数限制
write	创建或覆盖文件，自动创建父目录
edit	精确文本替换，支持多段不重叠的编辑操作

典型使用场景：

• 读取配置文件分析系统设置
• 批量修改代码中的变量名或函数签名
• 创建新的项目文档或代码文件

{
  "tool": "edit",
  "params": {
    "path": "config.json",
    "edits": [
      { "oldText": "\"version\": \"1.0\"", "newText": "\"version\": \"2.0\"" }
    ]
  }
}

安全注意事项：
• write 会覆盖现有文件，确认路径正确
• edit 的 oldText 必须完全匹配，建议先 read 确认内容
• 大文件使用 offset 和 limit 分批读取

2.3 Sessions（会话管理工具）

会话管理工具用于管理 Agent 会话生命周期，支持会话列表查询、历史记录查看和子 Agent 创建。

工具名称	功能描述
sessions_list	列出当前运行的会话
sessions_history	查看指定会话的历史消息
sessions_send	向会话发送消息或命令
sessions_spawn	创建新会话（子 Agent）
sessions_yield	结束当前会话并等待子任务返回（系统内置，官方文档待补充）
session_status	获取当前会话状态信息

典型使用场景：

• 创建子 Agent 并行处理多个任务
• 监控长时间运行任务的状态
• 在会话间传递数据和上下文

安全注意事项：
• 子 Agent 继承父会话的部分权限，需谨慎授权
• 使用 sessions_yield 确保子任务结果正确返回
• 定期清理不再需要的会话，释放资源

2.4 Memory（记忆系统工具）

记忆系统工具提供语义搜索和记忆片段读取功能，帮助 Agent 检索历史信息和长期记忆。

工具名称	功能描述
memory_search	语义搜索 MEMORY.md 和 memory/*.md 文件
memory_get	安全读取指定记忆文件的片段内容

典型使用场景：

• 检索用户偏好和历史决策
• 查找相关项目背景信息
• 获取之前会话中的重要结论

安全注意事项：
• memory_search 仅在主会话中加载 MEMORY.md，共享上下文（如 Discord）中不加载
• 记忆文件可能包含敏感信息，注意访问控制

2.5 Web（网络访问工具）

网络访问工具用于从 URL 获取和提取可读内容，支持 HTML 到 Markdown/Text 的转换。

工具名称	功能描述
web_fetch	获取 URL 内容并提取为 Markdown 或纯文本

典型使用场景：快速获取网页文章内容、收集技术文档、监控特定网页内容变化。

安全注意事项：
• 避免访问恶意或不安全的网站
• 设置合理的 maxChars 限制，避免处理过大内容

2.6 UI（界面交互工具）

界面交互工具提供浏览器自动化和画布渲染控制能力，支持复杂的 Web 操作和可视化任务。

工具名称	功能描述
browser	浏览器控制，支持导航、截图、点击、输入、表单填充等
canvas	画布渲染与控制，支持 present/hide/navigate/eval/snapshot 等操作

安全注意事项：
• 浏览器自动化可能触发网站的安全机制
• 处理登录状态时注意保护凭证安全
• 使用 profile: "user" 时确保用户在场

2.7 Automation（自动化工具）

自动化工具用于系统级任务调度和服务管理。

工具名称	功能描述
cron	定时任务管理，支持创建、列出、删除周期性任务
gateway	网关服务管理，支持状态检查、启动、停止、重启

安全注意事项：
• 定时任务可能持续消耗系统资源，合理设置频率
• 网关重启会影响所有正在运行的会话

2.8 Messaging（消息通信工具）

消息通信工具支持跨渠道消息发送，覆盖 Discord、Telegram、WhatsApp 等多种平台。

工具名称	功能描述
message	跨渠道消息发送，支持文本、媒体、回复、反应等多种消息类型

安全注意事项：
• 不要泄露用户的私人信息到群组或公共频道
• 群聊中注意发言时机，避免过度打扰

2.9 Nodes（节点管理工具）

节点管理工具用于控制配对的远程设备，如手机、平板等。

工具名称	功能描述
nodes	配对设备控制，支持摄像头访问、屏幕截图、位置获取、通知推送等

安全注意事项：
• 访问摄像头和位置信息涉及隐私，需用户授权
• 节点配对需要正确的 bootstrap token 和配对码

2.10 Media（媒体生成工具）

媒体生成工具提供 AI 驱动的多媒体内容创建和分析能力。

工具名称	功能描述
image	图像分析，使用视觉模型分析图片内容
image_generate	图像生成，基于文本提示创建图片（系统内置，官方文档待补充）
music_generate	音乐生成，创建 AI 音乐曲目（系统内置，官方文档待补充）
video_generate	视频生成，创建 AI 视频内容（系统内置，官方文档待补充）
tts	文字转语音，将文本转换为语音输出（系统内置，官方文档待补充）
pdf	PDF 分析，提取和分析 PDF 文档内容

2.11 Agent Orchestration（Agent 编排工具）

Agent 编排工具用于管理和协调多个 Agent。

工具名称	功能描述
agents_list	列出当前可用的 Agent 及其配置
subagents	管理子 Agent，支持 list/steer/kill（Depth-1 orchestrator 场景）

第 3 章 工具组（Tool Groups）设计

3.1 工具组的概念与作用

OpenClaw 提供了工具组（Tool Groups）机制，通过简写形式 group:* 来引用预定义的工具集合。这一设计大大简化了复杂环境下的工具策略配置。

3.2 真实的工具组清单

OpenClaw 官方文档定义了以下工具组：

工具组	包含的工具
group:runtime	exec、process（bash 是 exec 的别名）
group:fs	read、write、edit、apply_patch
group:sessions	sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
group:memory	memory_search、memory_get
group:web	web_search、web_fetch
group:ui	browser、canvas
group:automation	cron、gateway
group:messaging	message
group:nodes	nodes
group:openclaw	所有内置工具（排除提供商插件）

3.3 配置示例

在 Sandbox 策略中使用工具组：

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

3.4 工具组 vs 单独工具名的优劣对比

对比维度	工具组	单独工具名
配置简洁性	✅ 一行引用多个工具	❌ 需逐个列出
可维护性	✅ 新增工具自动包含	❌ 需手动更新
粒度控制	⚠️ 粒度较粗	✅ 精细控制
可读性	✅ 语义清晰	⚠️ 工具列表冗长

最佳实践：在大多数场景下使用工具组获取简洁性，需要精细控制时使用单独工具名覆盖。

3.5 工具组展开原理

工具组采用懒加载展开机制：

1. 解析阶段：配置文件加载时，group:* 标记被记录但暂不展开
2. 匹配阶段：当 AI 请求调用工具时，策略引擎展开工具组并匹配实际工具名
3. 缓存阶段：展开后的映射会被缓存以提升后续匹配性能

第 4 章 工具策略配置

OpenClaw 的工具策略系统是一套多层权限控制机制，确保每个 Agent 只能访问其职责范围内的工具。理解这套模型对于生产环境的安全部署至关重要。

4.1 工具权限模型架构

OpenClaw 的工具权限控制遵循三层递进结构：

第一层：Profile（基础预设）
选择 minimal / coding / messaging / full

第二层：Allow/Deny（精确控制）
通过白名单/黑名单精确控制

第三层：byProvider（按渠道覆盖）
按提供商 ID 定制权限

每一层都在前一层的基础上叠加约束，最终的权限集合是所有层叠加后的交集。deny 始终优先于 allow——这是不可逾越的安全底线。

4.2 预设配置文件详解

OpenClaw 内置了四个预设工具配置文件（Tool Profiles），定义在 tools.profile 字段中：

Profile	包含内容	适用场景
minimal	仅 session_status	最低权限，仅允许查看会话状态
coding	group:fs、group:runtime、group:sessions、group:memory、image	代码开发场景
messaging	group:messaging、sessions_list、sessions_history、sessions_send、session_status	消息通信场景
full	无限制（等同于未设置 profile）	完全信任场景

默认行为：本地新配置默认使用 tools.profile: "messaging"。这意味着开箱即用的 Agent 只能发送消息和查看会话状态，无法执行命令或读写文件。

4.3 Allow/Deny 规则

在 Profile 基础上，可以通过 tools.allow 和 tools.deny 进行精确控制：

核心规则：
1. deny 始终优先——任何出现在 deny 列表中的工具都被阻止，无论其他配置如何
2. allow 非空时，白名单生效——如果 allow 列表非空，则只有列表中的工具可用，其余全部被阻止
3. 支持 * 通配符——如 "web_*" 可匹配 web_search 和 web_fetch
4. 大小写不敏感——"Browser" 和 "browser" 等价

// 示例：允许大部分工具，但禁止浏览器和画布
{
  tools: {
    profile: "full",
    deny: ["browser", "canvas"],
  },
}

// 示例：最小化白名单
{
  tools: {
    profile: "minimal",
    allow: ["read", "write", "exec", "process"],
  },
}

4.4 alsoAllow 追加机制

在某个 Profile 的基础上额外添加工具：

{
  tools: {
    profile: "messaging",
    alsoAllow: ["web_fetch", "image"],
  },
}

这比手动展开 Profile 再添加额外工具要简洁得多。

4.5 渐进式配置路径

推荐的配置演进路径（从最严格到最宽松）：

// 阶段一：最小权限
{ "tools": { "profile": "minimal" } }

// 阶段二：消息通信
{ "tools": { "profile": "messaging" } }

// 阶段三：代码开发
{
  "tools": {
    "profile": "coding",
    "alsoAllow": ["web_fetch", "web_search"],
    "deny": ["browser"],
  },
}

// 阶段四：完全信任
{ "tools": { "profile": "full" } }

4.6 沙盒工具策略

当 Agent 运行在 Docker 沙盒中时，还有额外一层 tools.sandbox.tools 控制：

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

这层策略仅在沙盒模式启用时生效，用于限制容器内可使用的工具。

第 5 章 按供应商限制（byProvider）

5.1 设计理念

OpenClaw 支持多个 AI 模型提供商（如 OpenAI、Google、阿里通义等）。不同提供商的模型能力和安全特性各不相同，OpenClaw 允许按提供商 ID 定制工具权限。

即使全局策略允许某些工具，也可以针对特定提供商进一步收紧权限。例如，你信任 OpenAI 模型的代码生成能力，但希望限制第三方模型的权限。

5.2 配置格式

tools.byProvider 是一个键值对对象，Key 支持两种格式：

• provider——按提供商 ID 匹配，如 "google-antigravity"
• provider/model——按提供商/模型精确匹配，如 "openai/gpt-5.2"

每个值是一个标准的工具策略对象，支持 profile、allow、deny 和 alsoAllow。

5.3 解析顺序

工具权限的最终计算遵循严格顺序：

Step 1：Base Profile
应用 tools.profile 确定基础工具集

Step 2：Provider Profile
应用 byProvider[provider].profile 进行提供商级约束

Step 3：Provider Allow/Deny
应用 byProvider[provider].allow/deny 精确调整

关键点：如果 byProvider 配置了 profile: "minimal"，则该提供商的模型只能使用 session_status，无论全局 tools.profile 设置为何值。

5.4 实战示例

{
  tools: {
    profile: "coding",                          // 全局：代码开发权限
    byProvider: {
      "google-antigravity": {
        profile: "minimal",                     // Google 模型：仅允许最小权限
      },
      "openai/gpt-5.2": {
        allow: ["group:fs", "sessions_list"],   // GPT-5.2：仅允许文件系统和会话列表
      },
      "dashscope": {
        profile: "coding",                      // 通义千问：保持 coding 权限
        alsoAllow: ["web_fetch"],               // 额外允许网络抓取
      },
    },
  },
}

5.5 生产环境最佳实践

Agent	渠道 Provider	Profile	说明
main	dashscope	coding	主 Agent 使用通义千问，具备开发能力
assistant	google-antigravity	minimal + alsoAllow	Google 模型仅允许基础操作
group-bot	discord	messaging	Discord 群组机器人仅允许消息通信

5.6 Per-Agent 策略

每个 Agent 可以独立定义 tools 配置：

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          profile: "coding",
          byProvider: { "dashscope": { profile: "coding" } },
        },
      },
      {
        id: "group-bot",
        tools: { profile: "messaging" },
      },
    ],
  },
}

这确保了不同职责的 Agent 拥有不同的权限边界，实现了最小特权原则。

第 6 章 工具调用审计与安全最佳实践

6.1 三层防护关系

OpenClaw 实现了三层递进的安全防护机制：

层级	配置路径	作用
Sandbox	agents.defaults.sandbox.*	决定工具在哪里运行（Docker 容器 vs 宿主机）
Tool Policy	tools.*	决定哪些工具可用/可调用
Elevated	tools.elevated.*	exec 专用的宿主机逃逸通道

关键理解：Sandbox 控制「在哪里运行」，Tool Policy 控制「能否运行」，Elevated 是「逃脱沙箱」的例外通道。

6.2 工具调用审计维度

审计工具调用时，应关注以下维度：

1. 调用者身份：哪个 channel/sender 触发了工具调用
2. 工具类型：执行的工具属于哪个工具组
3. 执行环境：sandboxed 还是 host
4. 权限来源：通过 tool policy 还是 elevated 获得执行权
5. 调用结果：成功/失败/被拒绝

使用命令查看实际执行路径：

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

6.3 安全配置检查清单

• gateway.bind 是否为 loopback（本地模式）
• DM 策略是否为 pairing（配对验证）
• 群组是否启用 requireMention（提及触发）
• 工具配置是否为最小化 profile: "messaging"
• Elevated 是否禁用或限制 allowFrom
• 关键工具（gateway、cron）是否在 deny 列表

6.4 常见 "sandbox jail" 问题排查

症状：工具被 Sandbox 策略阻止

诊断：openclaw sandbox explain

修复方案：

1. 禁用 sandbox 模式：agents.defaults.sandbox.mode: "off"
2. 在 sandbox 工具策略中放行：移除 deny 列表或添加 allow 列表
3. 检查 non-main 模式陷阱：sandbox.mode: "non-main" 下，群组/频道消息默认 sandboxed

第 7 章 完整配置示例

7.1 生产环境推荐配置

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "replace-with-long-random-token" },
  },
  session: {
    dmScope: "per-channel-peer",
  },
  tools: {
    profile: "messaging",
    deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"],
    fs: { workspaceOnly: true },
    elevated: { enabled: false },
  },
  channels: {
    whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } },
  },
}

7.2 多 Agent 差异化配置示例

Agent ID	用途	Sandbox 模式	工具策略
personal	个人助手	off	全部工具
family	家庭成员	all + workspaceAccess: "ro"	仅读工具
public	公共查询	all + workspaceAccess: "none"	仅消息工具

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: ["read"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
      {
        id: "public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: ["sessions_list", "sessions_history"],
          deny: ["read", "write", "exec", "browser", "gateway", "cron"],
        },
      },
    ],
  },
}

7.3 配置验证与热重载机制

# 检查配置语法和常见错误
openclaw doctor

# 深度安全审计
openclaw security audit --deep

热重载：修改 openclaw.json 后，Gateway 会自动重载配置（无需重启），工具策略变更即时生效。