OpenClaw 核心工具与策略控制

第 1 章 引言OpenClaw 是一个开源的个人 AI 助手框架支持多渠道集成包括 WhatsApp、Telegram、Discord、Slack 等主流 messaging 平台。通过灵活的插件系统OpenClaw 能够连接各种外部服务实现跨平台的智能助手功能。工具系统在 OpenClaw 中的核心地位工具系统是 OpenClaw 区别于普通聊天机器人的关键所在。它赋予 AI 助手执行 Shell 命令、读写文件、浏览器控制、发送消息等能力使 AI 能够真正「行动」而非仅仅「对话」。OpenClaw 的核心工具包括执行工具exec、processbash 是 exec 的别名文件系统工具read、write、edit、apply_patch会话管理工具sessions_list、sessions_history、sessions_send、sessions_spawn网络工具web_search、web_fetchUI 交互工具browser、canvas消息工具message为什么需要工具策略控制随着 AI 助手能力的增强安全风险也相应增长。工具策略控制基于以下安全原则最小特权原则Principle of Least Privilege只授予 AI 完成工作所需的最小工具集纵深防御Defense in Depth通过 Sandbox、Tool Policy、Elevated 三层防护控制工具调用威胁模型隔离将 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创建新会话子 Agentsessions_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文字转语音将文本转换为语音输出系统内置官方文档待补充pdfPDF 分析提取和分析 PDF 文档内容2.11 Agent OrchestrationAgent 编排工具Agent 编排工具用于管理和协调多个 Agent。工具名称功能描述agents_list列出当前可用的 Agent 及其配置subagents管理子 Agent支持 list/steer/killDepth-1 orchestrator 场景第 3 章 工具组Tool Groups设计3.1 工具组的概念与作用OpenClaw 提供了工具组Tool Groups机制通过简写形式group:*来引用预定义的工具集合。这一设计大大简化了复杂环境下的工具策略配置。3.2 真实的工具组清单OpenClaw 官方文档定义了以下工具组工具组包含的工具group:runtimeexec、processbash是exec的别名group:fsread、write、edit、apply_patchgroup:sessionssessions_list、sessions_history、sessions_send、sessions_spawn、session_statusgroup:memorymemory_search、memory_getgroup:webweb_search、web_fetchgroup:uibrowser、canvasgroup:automationcron、gatewaygroup:messagingmessagegroup:nodesnodesgroup:openclaw所有内置工具排除提供商插件3.3 配置示例在 Sandbox 策略中使用工具组{ tools: { sandbox: { tools: { allow: [group:runtime, group:fs, group:sessions, group:memory], }, }, }, }3.4 工具组 vs 单独工具名的优劣对比对比维度工具组单独工具名配置简洁性✅ 一行引用多个工具❌ 需逐个列出可维护性✅ 新增工具自动包含❌ 需手动更新粒度控制⚠️ 粒度较粗✅ 精细控制可读性✅ 语义清晰⚠️ 工具列表冗长最佳实践在大多数场景下使用工具组获取简洁性需要精细控制时使用单独工具名覆盖。3.5 工具组展开原理工具组采用懒加载展开机制解析阶段配置文件加载时group:*标记被记录但暂不展开匹配阶段当 AI 请求调用工具时策略引擎展开工具组并匹配实际工具名缓存阶段展开后的映射会被缓存以提升后续匹配性能第 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最低权限仅允许查看会话状态codinggroup:fs、group:runtime、group:sessions、group:memory、image代码开发场景messaginggroup: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_fetch4.大小写不敏感——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 章 按供应商限制byProvider5.1 设计理念OpenClaw 支持多个 AI 模型提供商如 OpenAI、Google、阿里通义等。不同提供商的模型能力和安全特性各不相同OpenClaw 允许按提供商 ID 定制工具权限。即使全局策略允许某些工具也可以针对特定提供商进一步收紧权限。例如你信任 OpenAI 模型的代码生成能力但希望限制第三方模型的权限。5.2 配置格式tools.byProvider是一个键值对对象Key 支持两种格式provider——按提供商 ID 匹配如google-antigravityprovider/model——按提供商/模型精确匹配如openai/gpt-5.2每个值是一个标准的工具策略对象支持profile、allow、deny和alsoAllow。5.3 解析顺序工具权限的最终计算遵循严格顺序Step 1Base Profile应用 tools.profile 确定基础工具集Step 2Provider Profile应用 byProvider[provider].profile 进行提供商级约束Step 3Provider 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渠道 ProviderProfile说明maindashscopecoding主 Agent 使用通义千问具备开发能力assistantgoogle-antigravityminimal alsoAllowGoogle 模型仅允许基础操作group-botdiscordmessagingDiscord 群组机器人仅允许消息通信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 实现了三层递进的安全防护机制层级配置路径作用Sandboxagents.defaults.sandbox.*决定工具在哪里运行Docker 容器 vs 宿主机Tool Policytools.*决定哪些工具可用/可调用Elevatedtools.elevated.*exec 专用的宿主机逃逸通道关键理解Sandbox 控制「在哪里运行」Tool Policy 控制「能否运行」Elevated 是「逃脱沙箱」的例外通道。6.2 工具调用审计维度审计工具调用时应关注以下维度调用者身份哪个 channel/sender 触发了工具调用工具类型执行的工具属于哪个工具组执行环境sandboxed 还是 host权限来源通过 tool policy 还是 elevated 获得执行权调用结果成功/失败/被拒绝使用命令查看实际执行路径openclaw sandbox explain openclaw sandbox explain --session agent:main:main openclaw sandbox explain --agent work openclaw sandbox explain --json6.3 安全配置检查清单gateway.bind是否为 loopback本地模式DM 策略是否为pairing配对验证群组是否启用requireMention提及触发工具配置是否为最小化profile: messagingElevated 是否禁用或限制allowFrom关键工具gateway、cron是否在 deny 列表6.4 常见 sandbox jail 问题排查症状工具被 Sandbox 策略阻止诊断openclaw sandbox explain修复方案禁用 sandbox 模式agents.defaults.sandbox.mode: off在 sandbox 工具策略中放行移除deny列表或添加allow列表检查 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家庭成员allworkspaceAccess: ro仅读工具public公共查询allworkspaceAccess: 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 会自动重载配置无需重启工具策略变更即时生效。