03 - 工具集成解决方案设计
!-- Skills 系统与 MCP 协议的集成机制详解 --
工具集成架构概览
OpenClaw 能够集成数百种不同工具，其核心在于标准化的工具抽象层和插件式的 Skills 系统。这种设计使得新工具的添加不需要修改核心代码，只需遵循约定的接口规范即可。
三层工具体系
┌─────────────────────────────────────────────┐
│ Agent Runtime (Pi) │
│ - 工具选择、参数生成、结果解析 │
└──────────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Tool Registry (工具注册表) │
│ - 工具发现、权限检查、沙盒路由 │
└──────────────┬──────────────────────────┘
│
┌──────┴──────┬──────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Bundled │ │Workspace │ │ MCP │
│ Skills │ │ Skills │ │ Servers │
└──────────┘ └──────────┘ └──────────┘Skills 系统详解
Skill 定义规范
每个 Skill 遵循严格的文件约定：
目录结构:
~/.openclaw/workspace/skills/<skill-name>/
├── SKILL.md # Skill 主文档 (必需)
├── package.json # 依赖配置 (可选)
└── src/ # 源代码 (可选)SKILL.md 模板:
# Skill: 数据分析助手
## 描述
提供常见的数据分析任务，包括 CSV 处理、统计计算和可视化生成。
## 能力
### capability: csv_stats
计算 CSV 文件的统计摘要。
- **输入**: file_path (string)
- **输出**: summary (object)
### capability: chart_generate
生成数据可视化图表。
- **输入**: data (array), chart_type (string)
- **输出**: chart_url (string)Skill 加载流程
1. Gateway 启动扫描 ~/.openclaw/workspace/skills/
2. 解析每个 SKILL.md 提取 capability 定义
3. 加载对应的 JavaScript/TypeScript 执行模块
4. 注册到 Tool Registry，关联到权限组
5. Agent 可通过工具描述自动发现和调用Skill 权限隔离
OpenClaw 通过沙盒机制限制非主会话的工具访问：
主会话 (main session):
- 直接在主机执行，完全权限
- 用于用户直接对话，信任度高
非主会话 (groups/channels):
- 在 Docker 沙盒内执行
- 默认 allowlist: bash, process, read, write, edit, sessions_*
- 默认 denylist: browser, canvas, nodes, cron, discord, gateway
配置示例:
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"allowlist": ["bash", "read", "write"],
"denylist": ["browser", "canvas"]
}
}
}
}Model Context Protocol (MCP) 集成
MCP 概念
MCP 是 OpenClaw 支持的标准化工具协议，允许将外部工具服务器无缝集成到 Agent 工作流。它解决了”为每个 AI 模型和工具编写自定义集成代码”的复杂性问题。
MCP Server 集成
支持的 MCP Server:
- clawd-mcp: OpenClaw Gateway 和 Moltbook 集成
- openapi-mcp: 将任何 OpenAPI 规范转换为 AI 可访问工具
- mcp-playbook: 项目文档管理和对话日志
MCP Server 配置:
{
"mcpServers": {
"clawd-mcp": {
"url": "https://glama.ai/mcp/servers/@sandraschi/clawd-mcp",
"capabilities": ["discord", "telegram", "whatsapp"]
},
"openapi-mcp": {
"url": "https://github.com/jedisct1/openapi-mcp",
"specPath": "./openapi-spec.yaml"
}
}
}MCP 工具调用流程
Agent 请求 → Tool Registry 检测 MCP 工具
↓
生成 MCP 标准化调用参数
↓
发送到 MCP Server (HTTP/WS)
↓
MCP Server 执行并返回结果
↓
Tool Registry 格式化结果
↓
Agent 继续处理ClawHub 生态
ClawHub 注册表
ClawHub 是 OpenClaw 的技能注册中心，类似于 npm registry：
- 发现: Agent 可自动搜索和推荐相关技能
- 安装: 一键安装到本地 workspace
- 版本管理: 支持技能版本更新和回滚
- 质量评分: 社区评分和使用统计
ClawHub 工作流
用户请求 "发送邮件"
↓
Agent 调用 skills_search 工具
↓
搜索 ClawHub API 获取相关技能
↓
发现 "gmail-smtp-skill" (评分 4.8)
↓
Agent 调用 skills_install 安装技能
↓
Skill 加载到 Tool Registry
↓
Agent 执行邮件发送任务内置工具能力
Browser 控制工具
OpenClaw 管理专用的 Chrome/Chromium 浏览器实例：
能力:
browser.navigate: 导航到 URLbrowser.snapshot: 获取页面截图browser.click: 点击元素browser.type: 输入文本browser.upload: 文件上传
CDP 集成: 使用 Chrome DevTools Protocol 实现精确控制
Canvas + A2UI
Canvas 是 Agent 驱动的可视化工作区：
Canvas 命令:
canvas.push: 更新 HTML 内容canvas.eval: 执行 JavaScript 代码canvas.snapshot: 获取当前状态
A2UI (Agent-to-UI):
- 将 Agent 思维过程可视化渲染
- 支持交互式界面元素
- 双向数据绑定
Cron + Webhook
定时任务:
// ~/.openclaw/workspace/cron.yaml
- name: "daily_report"
schedule: "0 9 * * *"
message: "生成每日销售报告"Webhook 触发:
- Gateway 暴露 HTTP 端点接收外部事件
- 支持签名验证和速率限制
- 可配置触发条件和处理流程
工具调用安全机制
权限检查流程
工具调用请求
↓
提取工具名称和参数
↓
查询 Tool Registry 获取权限组
↓
检查 Session 沙盒模式
↓
验证 allowlist/denylist
↓
检查用户授权 (如需要)
↓
执行工具或拒绝访问幂等性保证
所有有副作用的工具调用必须提供幂等键：
{
"method": "send",
"params": {
"to": "+1234567890",
"message": "Hello",
"idempotencyKey": "msg-1234567890"
}
}Gateway 维护短期去重缓存，防止重复执行。
结论
OpenClaw 的工具集成机制通过三层体系 (Bundled Skills → Workspace Skills → MCP Servers) 实现了灵活性和安全性的平衡。其核心创新是标准化工具定义和运行时权限隔离，使得在不牺牲安全性的前提下支持数百种工具的无缝集成。ClawHub 生态进一步简化了技能发现和安装流程，降低了扩展门槛。