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

本文转载自：微信公众号「阿里云开发者」
原文链接：https://mp.weixin.qq.com/s/wVcItgqsCiwl9-PZ56z27w
作者：踏天
转载时间：2026-03-27

一、背景

最近OpenClaw如日中天，俨然已经是当下最热门并实用的个人助理。OpenClaw已经是我每日深度使用的效率工具，作为技术人，忍不住想系统性扒一下其技术架构与实现细节。当然了，本文也是通过与一堆Agent协作完成，包括OpenClaw、OpenCode、ClaudeCode、NotebookLLM、DeRisk等。

OpenClaw 在面向个人助手方向上，不仅仅体现在其灵活先进的智能体架构，还有其围绕个人助手方向的各种工具与生态的完整实现，是各类技术与工具的集大成者。 最让人惊讶的是，这些能力的基本全部通过AI-Coding实现，可以说彻底改变了软件开发的范式，而且清晰简洁的架构设计与表达，比传统人类编程的系统具有更高的标准，可以说是开启新的软件构建范式的开山之作，非常值得深入的研究。

由于OpenClaw涉及的技术点非常多，所以文章篇幅会显得很长。 这里建议大家按照感兴趣的模块，分模块阅读了解：

1. 统一控制平面Gateway网关
2. Agentic Loop/Pi Loop
3. 定时任务系统
4. 工具系统
5. Channels
6. 上下文管理
7. SubAgent子智能体
8. SandBox沙箱系统
9. 记忆管理
10. Skills模块
11. Session管理
12. 自进化机制
13. 工作区与Agent路由
14. Nodes
15. 安全策略
16. 配置管理

二、OpenClaw总体架构

如下图所示为OpenClaw的技术架构图，其架构设计上是以本地优先(Local-First)多端联动为核心，建立一个高度灵活且可拓展的个人AI助手系统。其架构可以概括为一个以**Gateway(网关)**为核心的控制平面的分布式系统。

1.核心控制平面: Gateway(网关)

Gateway是OpenClaw的心脏，充当系统的单一控制平面

• 功能职责: 负责管理会话(Sessions)、状态感知(Presence)、配置、定时任务(Cron)、网络钩子(Webhooks)以及控制界面(Control UI)和Canvas宿主
• 通信协议: 基于WebSocket(WS) 网络构建，为所有客户端、工具和事件提供统一的连接通道。
• 运行环境: 推荐在 Node ≥22 环境下运行，通常作为守护进程（Daemon）常驻后台。

2.智能体运行时: Pi Agent

Pi Agent是处理逻辑和生成回复的核心引擎:

• RPC模型: Pi Agent以 RPC(远程过程调用) 模式运行，支持工具流(Tool Streaming)和块流(Block Streaming)，确保响应的高效与实时性。
• 多智能体路由: 系统能够将来自不同频道、账户或同伴的输入路由到相互隔离的智能体(拥有独立的Workspace和会话)
• 会话模型: 提供 main 模式用户直接对话，并支持群组隔离、激活模式切换和队列管理。

3.连接生态: Channels(频道)

OpenClaw的一大特色是其极强的连接性，它将AI能力注入到用户已有的社交生态中。

• 多频道集成：原生支持包括 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、Matrix 以及 Zalo 等多种通讯平台
• 路由规则: 具备复杂的群组路由逻辑，包括提及门控（Mention gating）、回复标签处理以及针对不同频道的自动消息分块。

4.设备节点与伴侣应用: Nodes & Apps

通过将不同设备定义为”节点”，OpenClaw 实现了跨设备的硬件控制：

• 跨平台支持：包括 macOS 菜单栏应用、iOS 节点和 Android 节点。
• 硬件能力调用：通过 node.invoke 协议，智能体可以远程调用各节点上的硬件功能，如摄像头拍照/录码、屏幕录制、地理位置获取以及 macOS 特有的系统命令执行（system.run）。
• Voice Wake & Talk Mode：利用 ElevenLabs 等技术，在 macOS/iOS/Android 上提供始终在线的语音唤醒和连续对话能力。

5.工具与自动化：Tools & Skills

架构中集成了丰富的生产力工具：

• 浏览器控制：内置托管的 Chrome/Chromium 实例，支持快照、动作执行和文件上传。
• Live Canvas：基于 A2UI 构建的实时交互画布，允许智能体驱动视觉化的工作空间。
• 技能平台 (ClawHub)：提供技能注册表，支持捆绑技能、托管技能和工作区技能的自动搜索与安装。

6.安全与沙箱机制 (Security & Sandboxing)

由于 OpenClaw 会连接到真实的社交媒体和本地文件系统，安全性被置于重要位置：

• DM 配对策略：默认情况下，未知发送者必须通过配对码验证，bot 才会处理其消息，以防止不受信任的输入。
• Docker 沙箱：支持将非主会话（如群组或外部频道）放入独立的 Docker 容器中运行，限制其对主机的访问权限，并对敏感工具（如浏览器、系统命令）进行黑白名单管理。

7.部署与远程访问

• 本地/远程灵活部署：Gateway 可以运行在本地或小型 Linux 实例上。
• 内网穿透：集成 Tailscale Serve/Funnel 或 SSH 隧道，使用户能够安全地从远程访问 Gateway 面板和 WebSocket 服务。

三、各系统模块详解

3.1 统一控制平面Gateway网关

3.1.1、核心定位

Gateway 是 OpenClaw 的统一控制平面，是一个 WebSocket 服务器，负责：

1. 消息路由 - 所有频道（Telegram、Discord、Slack 等）的消息路由
2. 会话管理 - Agent 会话的生命周期管理
3. 工具调用 - Agent 工具的执行协调
4. 节点通信 - iOS/Android 等移动节点的通信桥接
5. HTTP API - 提供 OpenAI 兼容的 REST API

3.1.2、架构模型

3.1.3、关键特性

3.1.4、协议机制

连接握手流程：

1
2
3
4
5
6

Gateway ───────────────────── Client
  │                              │
  │◄──── connect.challenge ──────│ (可选：带 nonce 的挑战)
  │─────── connect (req) ──────►│ 携带 auth + role + scopes
  │◄────── hello-ok (res) ──────│ 返回 policy + 设备令牌
  │◄─────── events ──────────────│ 持续推送状态变更

帧类型：

• Request: {type:"req", id, method, params}
• Response: {type:"res", id, ok, payload|error}
• Event: {type:"event", event, payload, seq?, stateVersion?}

3.1.5、认证模式

安全强制：

• 非环回地址绑定必须启用认证
• 明文 ws:// 禁止连接非本机地址（CWE-319）

3.1.6、绑定模式

3.1.7、服务生命周期

macOS (launchd)：

1
2
3
4

openclaw gateway install   # 安装 LaunchAgent
openclaw gateway start     # 启动服务
openclaw gateway stop      # 停止服务
openclaw gateway restart   # 重启服务

Linux (systemd)：

1
2

openclaw gateway install
systemctl --user enable --now openclaw-gateway.service

3.1.8、配置热重载

3.1.9、关键配置项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "your-token"
    },
    "tls": {
      "enabled": true,
      "certPath": "/path/to/cert.pem",
      "keyPath": "/path/to/key.pem"
    },
    "reload": {
      "mode": "hybrid",
      "debounceMs": 300
    }
  }
}

3.1.10、常用命令

1
2
3
4
5
6
7
8
9
10
11
12

# 启动网关
openclaw gateway --port 18789
# 查看状态
openclaw gateway status
openclaw gateway status --deep  # 深度检查
# 健康检查
openclaw gateway health
openclaw channels status --probe
# 发现局域网网关
openclaw gateway discover
# 查看日志
openclaw logs --follow

3.1.11、核心源码位置

3.2 Agentic Loop / Pi Loop

如下图所示为OpenClaw的整个推理循环架构，也是构成整个系统执行的大脑思考核心。系统中所有的运行逻辑都由推理循环架构来控制，也就是AgenticLoop，OpenClaw的推理循环是一个事件驱动的架构：

1. 主循环 (run.ts) 负责错误处理、重试、profile轮换
2. 尝试层 (attempt.ts) 负责单次LLM调用的完整生命周期
3. 事件订阅 (subscribe.ts) 处理流式响应和工具调用
4. 工具循环 由底层SDK自动管理，当模型返回 tool_use 时自动执行工具并继续调用。

3.2.1 核心推理循环

主循环架构 (runEmbeddedPiAgent in run.ts:192)

1
2
3
4
5
6
7
8
9

runEmbeddedPiAgent() 
 └── while (true) {    // 行538 - 主重试循环
      ├── 检查重试次数限制 (MAX_RUN_LOOP_ITERATIONS)
      ├── 调用 runEmbeddedAttempt()  // 单次推理尝试
      ├── 处理 context overflow → 自动压缩
      ├── 处理 auth failure → profile轮换
      ├── 处理 timeout → 重试或报错
      └── 成功则返回 payloads
     }

单次推理尝试 (runEmbeddedAttempt in run/attempt.ts:306)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

runEmbeddedAttempt()
  ├── 1. 准备阶段
  │    ├── 创建 workspace 和 session
  │    ├── 解析 tools (createOpenClawCodingTools)
  │    ├── 构建 system prompt
  │    └── 创建 session manager
  │
  ├── 2. 会话初始化
  │    ├── createAgentSession()  // 行688
  │    ├── 设置 streamFn (LLM调用函数)
  │    └── 安装事件订阅器 subscribeEmbeddedPiSession()  // 行921
  │
  ├── 3. 执行推理
  │    ├── await activeSession.prompt(effectivePrompt)  // 行1180-1182
  │    │    └── 调用 LLM API(streamSimple/streamFn)
  │    └── 事件流处理:
  │         ├── message_start/message_update/message_end → handleMessageStart/Update/End
  │         ├── tool_execution_start/update/end → handleToolExecutionStart/Update/End
  │         └── agent_start/agent_end → handleAgentStart/End
  │
  └── 4. 返回结果
       ├── assistantTexts(生成的文本)
       ├── toolMetas(工具调用元数据)
       └── usage(token使用统计)

3.2.2 关键调用链

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

用户消息
  ↓
runAgentTurnWithFallback() (agent-runner-execution.ts:72)
  ↓
runEmbeddedPiAgent() (pi-embedded-runner/run.ts:192)
  ↓ [while循环 - 重试]
runEmbeddedAttempt() (pi-embedded-runner/run/attempt.ts:306)
  ↓
createAgentSession() + activeSession.prompt()
  ↓ [LLM调用 + 工具循环]
subscribeEmbeddedPiSession() → 事件处理器
  ↓
onPartialReply / onBlockReply / onToolResult
  ↓
回复消息发送

3.3 定时任务系统

在OpenClaw中，定时任务是非常重要的一个基础设施，OpenClaw非常多的工作都是长任务，定时任务可以很好的满足这些长任务在后台单次或者周期性运行的诉求，同时与Heatbeat交互使得整个系统的交互更加拟人化，有些定时回复与交流，往往给人意想不到的拟人化体验。

3.3.1、核心架构

3.3.2、调度类型

1
2
3
4

type CronSchedule =
  | { kind: "at"; at: string }          // 一次性任务，指定时间
  | { kind: "every"; everyMs: number; anchorMs?: number }  // 周期性任务
  | { kind: "cron"; expr: string; tz?: string; staggerMs?: number }  // Cron表达式

支持的调度模式：

1. at - 一次性任务，执行后自动禁用
2. every - 固定间隔执行
3. cron - 标准cron表达式，支持时区和stagger

3.3.3、定时器机制

核心实现在 src/cron/service/timer.ts:

1
2
3
4
5
6
7
8
9
10
11
12

const MAX_TIMER_DELAY_MS = 60_000;  // 最大延迟60秒
const MIN_REFIRE_GAP_MS = 2_000;    // 最小重触发间隔2秒

// 定时器armed函数
export function armTimer(state: CronServiceState){
  const nextAt = nextWakeAtMs(state);  // 计算下次唤醒时间
  const delay = Math.max(nextAt - now, 0);
  const clampedDelay = Math.min(delay, MAX_TIMER_DELAY_MS);
  state.timer = setTimeout(() => {
    void onTimer(state).catch(...);
  }, clampedDelay);
}

关键特性：

• 定时器最大延迟60秒，防止时钟漂移
• 支持并发运行控制 (maxConcurrentRuns)
• 错误指数退避 (30s → 1min → 5min → 15min → 60min)
• 自动清理卡住的任务 (2小时超时)

3.3.4、任务持久化机制

存储位置：默认路径: ~/.openclaw/cron/jobs.json

3.3.5、任务恢复机制

启动恢复流程 (src/cron/service/ops.ts):

1. 加载存储
2. 清理卡住的任务
3. 运行错过的任务
4. 重新计算下次运行时间
5. 启动定时器

3.3.6、任务执行类型

两种执行模式：

1. Main Session (sessionTarget: “main”) - 注入系统事件到主会话
2. Isolated Agent (sessionTarget: “isolated”) - 独立agent会话执行

3.3.7、与Heartbeat的集成

定时任务通过Heartbeat机制唤醒agent，支持 next-heartbeat 和 now 两种Wake模式。

3.3.8、Webhook通知

支持任务完成后的Webhook回调。

3.3.9、CLI命令

1
2
3
4
5
6

openclaw cron status     # 查看调度器状态
openclaw cron list      # 列出任务
openclaw cron add       # 添加任务
openclaw cron edit      # 编辑任务
openclaw cron remove <id>  # 删除任务
openclaw cron run <id>     # 手动触发任务

3.3.10、关键设计特点

1. 单一定时器设计 - 只维护一个定时器，基于最近任务的nextRunAtMs
2. 文件持久化 - JSON存储，支持跨进程共享
3. 错误隔离 - 单个任务失败不影响其他任务
4. 自动恢复 - 启动时检测并运行错过的任务
5. 并发控制 - 可配置最大并发任务数
6. 进度追踪 - 完整的运行日志和状态跟踪
7. Agent集成 - 可通过cron工具在agent中管理任务

篇幅原因更多精彩内容在《深入理解OpenClaw技术架构与实现原理（下）》，请持续关注～

本文转载自微信公众号「阿里云开发者」，作者：踏天