大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



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 管理员、开发者和安全工程师阅读。

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

2.1 Runtime（运行时工具）

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

典型使用场景：

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

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

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

2.2 FS（文件系统工具）

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

典型使用场景：

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

 { "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 创建。

典型使用场景：

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

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

2.4 Memory（记忆系统工具）

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

典型使用场景：

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

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

2.5 Web（网络访问工具）

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

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

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

2.6 UI（界面交互工具）

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

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

2.7 Automation（自动化工具）

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

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

2.8 Messaging（消息通信工具）

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

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

2.9 Nodes（节点管理工具）

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

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

2.10 Media（媒体生成工具）

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

2.11 Agent Orchestration（Agent 编排工具）

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

3.1 工具组的概念与作用

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

3.2 真实的工具组清单

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. 缓存阶段：展开后的映射会被缓存以提升后续匹配性能

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

4.1 工具权限模型架构

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

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

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

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

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

4.2 预设配置文件详解

OpenClaw 内置了四个预设工具配置文件（Tool Profiles），定义在 tools.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.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 生产环境**实践

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.1 三层防护关系

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

关键理解：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.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 差异化配置示例

 { 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 会自动重载配置（无需重启），工具策略变更即时生效。