深入理解 OpenClaw 技术架构与实现原理（中篇）

开篇回顾

上篇我们了解了 OpenClaw 的核心架构：三层模型、WebSocket 协议、会话管理和记忆系统。

中篇我们将深入工具执行、安全沙箱、多 Agent 协作和插件系统，这些是 OpenClaw 从"能聊天"到"能办事"的关键。

六、工具执行与安全

6.1 工具执行流程

当 Agent 调用工具时，OpenClaw 执行以下流程：

1. Agent 发出工具调用请求2. 网关验证工具是否在允许列表中3. 检查是否需要审批（如 exec 命令）4. 执行工具（可能在沙箱中）5. 捕获输出和错误6.  sanitization（清理敏感信息和大文件）7. 返回结果给 Agent8. 持久化到会话记录

工具钩子： OpenClaw 提供丰富的钩子，允许在工具执行前后插入自定义逻辑：

• before_tool_call：工具调用前拦截参数
• after_tool_call：工具调用后处理结果
• tool_result_persist：持久化前转换结果

示例（插件钩子）：

// 插件注册钩子plugin.hooks.register('before_tool_call', async (ctx) => {if (ctx.tool === 'exec' && ctx.params.command.startsWith('rm')) {thrownewError('删除命令被禁止');  }});

6.2 执行审批机制

对于高风险操作（如 shell 命令），OpenClaw 支持执行审批：

1. 网关广播 exec.approval.requested 事件
2. 授权客户端（需要 operator.approvals 作用域）调用 exec.approval.resolve 审批
3. 审批通过后执行命令

系统运行计划： 对于 host=node 的执行请求，必须包含 systemRunPlan（规范的命令/工作目录/会话元数据），缺少此字段的请求会被拒绝。

配置示例：

{  tools: {    exec: {      approvalRequired: true,      allowlist: ["git", "npm", "pnpm"],  // 无需审批的命令      denylist: ["rm", "sudo", "curl"]     // 禁止的命令    }  }}

6.3 沙箱执行

OpenClaw 支持 Docker 沙箱执行工具，隔离风险：

沙箱模式：

作用域：

配置示例：

{  agents: {    list: [      {        id: "family",        sandbox: {          mode: "all",          scope: "agent",          docker: {            image: "node:20-alpine",            setupCommand: "apt-get update && apt-get install -y git curl",            workspaceAccess: "rw"  // 工作空间读写权限          }        }      }    ]  }}

安全最佳实践：

1. 最小权限原则：只允许必要的工具
2. 沙箱隔离：对不受信任的 Agent 启用沙箱
3. 命令白名单：限制可执行的命令
4. 审计日志：记录所有工具调用

七、多 Agent 协作

7.1 多 Agent 架构

OpenClaw 支持在单个网关进程中运行多个隔离的 Agent，每个 Agent 有：

• 独立的工作空间（workspace）
• 独立的状态目录（agentDir）
• 独立的会话存储
• 独立的认证配置

物理隔离：

~/.openclaw/├── agents/│   ├── main/│   │   ├── agent/          # 状态目录（认证、模型注册）│   │   └── sessions/       # 会话存储│   ├── work/│   │   ├── agent/│   │   └── sessions/│   └── personal/│       ├── agent/│       └── sessions/├── workspace-main/├── workspace-work/└── workspace-personal/

7.2 路由绑定（Bindings）

消息路由通过 bindings 配置，遵循最具体匹配优先原则：

匹配优先级（从高到低）：

1. peer 精确匹配（DM/群组/频道 ID）
2. parentPeer 匹配（线程继承）
3. guildId + roles（Discord 角色路由）
4. guildId（Discord 服务器）
5. teamId（Slack 团队）
6. accountId 匹配
7. 渠道级匹配（accountId: "*"）
8. 默认 Agent（第一个或标记为 default 的）

配置示例：

{  bindings: [    // 优先级 1：精确匹配特定 DM    {      agentId: "ceo",      match: {        channel: "whatsapp",        peer: { kind: "direct", id: "+8613800138000" }      }    },    // 优先级 3：Discord 角色路由    {      agentId: "moderator",      match: {        channel: "discord",        guildId: "123456789",        roles: ["moderator"]      }    },    // 优先级 6：账号级匹配    {      agentId: "work",      match: { channel: "telegram", accountId: "work" }    },    // 优先级 7：渠道级 fallback    {      agentId: "main",      match: { channel: "whatsapp" }    }  ]}

7.3 跨 Agent 通信

OpenClaw 支持 Agent 之间互相发送消息（需显式启用）：

{  tools: {    agentToAgent: {      enabled: true,      allow: ["main", "work", "personal"]  // 允许互相通信的 Agent    }  }}

使用场景：

1. 任务分发：主 Agent 接收任务，分发给专业 Agent
2. 上下文隔离：敏感对话在独立 Agent 中处理
3. 负载均衡：高峰时段分散请求

示例（主 Agent 分发给编码 Agent）：

// 主 Agent 调用 sessions_send 工具{tool: "sessions_send",params: {agentId: "coding",sessionKey: "agent:coding:main",message: "请帮我审查这段代码：..."  }}

7.4 子 Agent（Sub-Agent）

OpenClaw 支持动态 spawns 子 Agent处理专门任务：

运行时选项：

模式：

配置示例：

{  sessions_spawn: {    runtime: "subagent",    mode: "run",    task: "分析这个 GitHub 仓库的代码结构",    attachments: [...],  // 可选附件    timeoutSeconds: 300,    cleanup: "delete"    // 完成后删除  }}

子 Agent 管理： 父 Agent 可以通过 subagents 工具管理子 Agent：

• list：列出活跃的子 Agent
• steer：发送指导消息
• kill：终止子 Agent

八、插件系统

8.1 插件架构

OpenClaw 的插件系统允许扩展核心功能，插件可以：

1. 注册钩子：拦截 Agent 循环和网关事件
2. 提供工具：添加自定义工具
3. 扩展渠道：支持新的通讯平台
4. 修改配置：动态调整运行时行为

插件生命周期：

1. 网关启动 → 加载插件2. 插件注册钩子和工具3. 运行时触发钩子4. 网关关闭 → 插件清理

8.2 核心钩子

Agent 循环钩子：

网关钩子：

内部钩子（Gateway Hooks）： 除了插件钩子，OpenClaw 还支持脚本钩子（内部钩子），通过配置触发外部脚本：

{  hooks: {    "agent:bootstrap": "/path/to/script.sh",  // 构建引导文件前    "command:/new": "/path/to/new-handler.sh" // /new 命令触发  }}

8.3 插件开发示例

最小插件：

// my-plugin/index.jsmodule.exports = {name: 'my-plugin',version: '1.0.0',asyncinstall(pluginAPI) {// 注册钩子    pluginAPI.hooks.register('before_tool_call', async (ctx) => {console.log(`工具调用：${ctx.tool}`);    });// 注册工具    pluginAPI.tools.register('hello', {description: '说你好',asyncexecute(params) {return { text: `你好，${params.name}!` };      }    });  },asyncuninstall() {// 清理资源  }};

注册插件：

{  plugins: {    slots: {      memory: "my-plugin"  // 替换默认记忆插件    },    list: ["my-plugin"]    // 加载的插件列表  }}

8.4 技能 vs 插件

技能（Skills）：

• 可复用的 Agent 能力模块
• 包含文档（SKILL.md）、脚本、配置
• 通过 ClawHub 安装和管理
• 运行在 Agent 上下文中

插件（Plugins）：

• 扩展 OpenClaw 核心功能
• 可以注册钩子和工具
• 运行在网关进程中
• 更底层的扩展点

关系： 技能可以依赖插件提供的工具，插件可以为技能提供基础设施。

九、模型管理

9.1 模型提供商

OpenClaw 支持多家大模型提供商：

模型别名： 可以在配置中定义别名，简化模型引用：

{  models: {    providers: {      anthropic: { apiKey: "..." },      dashscope: { apiKey: "..." }    },    aliases: {      "fast": "anthropic/claude-sonnet-4-5",      "smart": "anthropic/claude-opus-4-6",      "china": "dashscope/qwen3.5-plus"    }  }}

使用时：

{  agents: {    defaults: {      model: "fast"  // 使用别名    }  }}

9.2 模型故障转移

OpenClaw 支持自动故障转移，当主模型不可用时切换到备用模型：

{  agents: {    defaults: {      models: [        { ref: "anthropic/claude-sonnet-4-5", priority: 1 },        { ref: "google/gemini-2.0-flash", priority: 2 },        { ref: "dashscope/qwen3.5-plus", priority: 3 }      ],      modelFailover: {        enabled: true,        maxRetries: 3,        retryDelayMs: 1000      }    }  }}

故障转移策略：

1. 按优先级尝试模型
2. 达到最大重试次数后放弃
3. 记录故障历史用于诊断

9.3 思维链（Reasoning）

OpenClaw 支持思维链流式输出（适用于支持 reasoning 的模型）：

配置：

{  agents: {    defaults: {      thinking: "on",  // 或 "off", "stream"      reasoning: {        enabled: true,        stream: true   // 流式输出推理过程      }    }  }}

运行时控制： 用户可以通过命令切换：

• /reasoning on：启用推理
• /reasoning off：禁用推理
• /reasoning stream：流式输出推理

注意：推理过程默认不发送给用户，除非显式启用流式。

十、心跳与主动任务

10.1 心跳机制

OpenClaw 支持心跳轮询，定期检查需要关注的任务：

心跳文件： HEARTBEAT.md 包含待检查任务列表，空文件表示跳过心跳。

心跳检查内容（示例）：

1. 邮件：检查紧急未读邮件
2. 日历：未来 24-48 小时的事件
3. 提及：社交媒体通知
4. 天气：相关天气预报

心跳状态跟踪：

// memory/heartbeat-state.json{"lastChecks":{"email":1703275200,"calendar":1703260800,"weather":null}}

10.2 Cron 任务

对于精确时间要求高的任务，使用 Cron：

一次性提醒：

/remind 20 分钟后 开会

周期性任务：

{  cron: {    jobs: [      {        id: "daily-standup",        schedule: "0 9 * * 1-5",  // 工作日 9:00        command: "发送站会提醒",        agentId: "main",        sessionKey: "cron:daily-standup"      }    ]  }}

心跳 vs Cron：

小结

中篇我们深入了 OpenClaw 的核心能力：

1. 工具执行：审批机制、沙箱隔离、钩子扩展
2. 多 Agent 协作：路由绑定、跨 Agent 通信、子 Agent
3. 插件系统：钩子、工具、生命周期
4. 模型管理：多提供商、故障转移、思维链
5. 主动任务：心跳轮询、Cron 调度

下篇我们将探讨：

• 生产环境部署
• 安全加固与审计
• 性能优化
• 故障排查与运维
• 最佳实践与案例

敬请期待！

参考资料：

• OpenClaw 官方文档：https://docs.openclaw.ai^[1]
• GitHub 仓库：https://github.com/openclaw/openclaw^[2]
• 社区 Discord：https://discord.com/invite/clawd^[3]

引用链接