OpenClaw 核心技术深度解析(三):工具系统与策略引擎

OpenClaw 的工具系统是一个精心设计的双层架构：能力层负责扩展 Agent 的行动范围，策略层负责约束 Agent 的行动边界。两者的平衡，是构建安全可靠的 AI Agent 的核心挑战。

能力层：从 4 到 24+ 的扩展之路

Pi 内核提供 4 个基础工具（Read、Write、Edit、Bash），OpenClaw 在此基础上扩展到 24+ 个，覆盖了 AI Agent 需要的所有能力维度：

工具全景表

类别	工具	数量	说明
基础工具	read, write, edit, exec	4	Pi 核心工具的 OpenClaw 包装版
消息工具	message, sessions_send, sessions_spawn, sessions_list, sessions_history	5	跨会话通信与子 Agent 管理
浏览器工具	browser（13 个子操作）	1（13子）	navigate, snapshot, screenshot, act, tabs, open, focus, close, console, pdf 等
Web 工具	web_search, web_fetch	2	互联网搜索和网页抓取
媒体工具	image, tts	2	视觉分析和文本转语音
基础设施	gateway, nodes, cron, canvas, memory	5	网关管理、定时任务、画布、记忆搜索
通道工具	discord_actions, slack_actions, telegram_actions, whatsapp_actions	4	平台特定操作
代码工具	apply_patch, process	2	OpenAI Codex 补丁、后台任务

工具注册机制

所有工具都通过 Pi 统一的 AgentTool 接口注册。这个接口定义了：

interface AgentTool {
  name: string;           // 工具名称
  description: string;    // 工具描述（LLM 用来决定何时调用）
  parameters: JSONSchema; // 参数 schema
  execute: (params) =>Promise<ToolResult>; // 执行函数
}

Agent 循环不关心有多少工具——它只执行 LLM 选择的工具。这种设计使得工具的添加和移除对核心循环完全透明。

Pi 工具的生产级包装

OpenClaw 对 Pi 的 4 个基础工具进行了生产级加固，代码位于 src/agents/pi-tools.ts：

Pi 原始工具	OpenClaw 增强
Read	MIME 类型检测（防止读取二进制文件导致上下文污染）、超大图片自动清理、Claude Code 兼容性适配
Write	沙箱路径守卫（防止写入沙箱外部路径）、自动创建目录结构
Edit	参数标准化（old_string/new_string → oldText/newText）、沙箱路径验证
Bash	完全替换为 exec 工具 ——Docker 沙箱执行、后台进程管理、安全策略检查、超时处理、审批工作流

策略层：8 层工具策略系统

这是 OpenClaw 架构中最精密的安全机制。在任何工具执行之前，它必须通过 8 层允许/拒绝过滤器：

层级	策略名称	配置路径	说明
1	Profile 策略	`tools.profile`	命名策略预设（如 "safe"、"full"、"minimal"）
2	Provider Profile	`tools.byProvider.profile`	按 LLM 提供商覆盖（如 Anthropic 用一套，OpenAI 用另一套）
3	全局白名单	`tools.allow`	实例级限制，全局生效
4	Provider 白名单	`tools.byProvider.allow`	按提供商的全局限制
5	Agent 特定	`agents.{id}.tools.allow`	按 Agent ID 限制
6	Group 策略	通道级配置	通道级限制（如在 Discord 服务器中禁用 exec）
7	Sandbox 策略	沙箱配置	Docker 沙箱限制
8	Subagent 策略	子 Agent 配置	子 Agent 的工具限制

策略合并规则

最严格的组合胜出。 每一层都只能缩小可用工具范围，不能扩大。这意味着：

如果 Profile 策略允许 exec，但 Group 策略禁止，则 exec 不可用
如果全局白名单允许 browser，但 Sandbox 策略禁止，则 browser 不可用
子 Agent 的工具集永远是父 Agent 工具集的子集

实际场景

同一个 OpenClaw 实例，不同场景下的工具可用性：

场景	可用工具	原因
个人 WhatsApp DM	全部 24+ 工具	主会话，最高信任级别
Discord 群聊	15 个工具（无 exec、无 browser）	Group 策略禁用了高风险工具
沙箱化子 Agent	8 个工具（仅基础 + web）	Sandbox + Subagent 双重限制
Anthropic 提供商	20 个工具（无 apply_patch）	Provider 策略限制

Cedar 策略语言集成

BYU Pico Labs 团队还探索了将 Cedar 策略语言集成到 OpenClaw 的工具策略系统中。Cedar 允许用更声明式的方式定义策略：

permit(
  principal == Agent::"main",
  action == Action::"exec",
  resource
) when {
  resource.command.startsWith("git") ||
  resource.command.startsWith("npm")
};

这种方式比 YAML 配置更灵活，支持基于命令内容的细粒度控制。

工具开发指南

OpenClaw 的工具系统是可扩展的。开发自定义工具需要：

实现 AgentTool 接口
在工具注册表中注册
在策略配置中添加权限

工具的 description 字段至关重要——它是 LLM 决定何时调用该工具的唯一依据。一个好的工具描述应该：

明确说明工具的功能和适用场景
列出参数的含义和约束
给出使用示例

总结

OpenClaw 的工具系统展示了一个优雅的架构模式：能力无限扩展，安全层层收紧。4 个基础工具通过统一接口扩展到 24+，8 层策略系统确保每个工具在每个场景下都有恰当的权限。这种设计既保证了 Agent 的强大能力，又维护了多租户环境下的安全边界。

参考链接

The Agent Stack - OpenClaw Security Boundaries, Tool Risk, and Authorization
Penligent - Hardening the OpenClaw AI Frontier
Pico Labs - A Policy-Aware Agent Loop with Cedar and OpenClaw
Moely - OpenClaw Source Code Review
Valletta Software - OpenClaw Architecture Diagram 2026