OpenClaw 源码与原理全解析

OpenClaw 是本地优先、可执行任务的开源AI智能体，核心是用自然语言指挥电脑完成真实操作（文件/浏览器/脚本/命令），基于 TypeScript+Node.js 开发，MIT 协议开源。

一、核心定位与技术栈

- 定位：AI 执行网关（The AI that actually does things），连接大模型与本地系统，实现思考→规划→执行→反馈闭环

- 技术栈：TypeScript、Node.js v22+、pnpm monorepo、SQLite+向量、Docker 沙箱、WebSocket、Playwright

- 核心架构：Gateway（中枢）+ Channels（多渠道）+ Agents（执行引擎）+ Memory（三级记忆）

二、源码目录结构（核心）

src/

├── gateway/

# 网关中枢：路由、鉴权、事件分发

├── channels/

# 多渠道适配：Telegram/Discord/飞书/钉钉等

├── agents/

# Agent 执行引擎（核心）

│ └── pi-embedded-runner/

# 嵌入式执行器（无RPC，性能高）

├── sessions/ # 会话管理

├── context-engine/

# 上下文构建与压缩

├── memory/ # 三级记忆系统

├── tools/

# 工具执行（文件/浏览器/命令）

├── plugins/ # 插件/技能（Skill）系统

└── routing/ # 消息路由

三、核心原理与知识点

1. 三层执行链路（核心流程）

- Orchestrator（大脑）：云端/本地 LLM 推理、任务拆解、ReAct 循环

- Gateway（协议桥）：鉴权、流量整形、消息统一格式、路由分发

- Pi-Embedded（执行端）：本地嵌入式运行，直接操作系统，无 RPC 开销

2. Agent 执行引擎（pi-embedded-runner）

入口：runEmbeddedPiAgent() （ src/agents/pi-embedded-runner/run.ts ）

- 执行流程

1. 获取 Session 锁（防并发冲突）

2. 构建 Prompt：注入 soul.md （人格）+ memory.md （长期记忆）+ 会话历史

3. 调用 LLM 流式推理

4. 工具调用 → Tool Policy Pipeline（安全检查）

5. 沙箱/Host 执行 → 结果返回 → 上下文压缩

- ReAct 循环： think → action → observation → repeat ，直到任务完成

3. 三级记忆架构（核心创新）

每个 Agent 独立工作区：

~/.openclaw/workspace/

- 短期记忆：

memory/YYYY-MM-DD.md （当日日志，自动加载最近2天）

- 近端记忆：

sessions/ （完整会话存档，滑动窗口压缩）

- 长期记忆：

memory.md （用户偏好、重要决策，每次对话加载）

- 存储实现：

SQLite + FTS5（全文检索）+ sqlite-vec（向量检索），混合 BM25+向量，RRF 融合排序

4. 工具执行与安全机制（Tool Policy Pipeline）

- 工具链：

文件系统、浏览器（Playwright）、Shell、搜索、自定义 Skill

- 安全策略（核心）

- 非主会话工具调用 → Docker 沙箱强制隔离

- 主会话 → Host 执行（需用户显式确认）

- 路径白名单、循环检测、权限校验、CSP 防 XSS

- Skill 系统：四层优先级（工作区 > 插件 > 用户 > 系统），热重载

5. 上下文压缩（Compaction）

- 触发：会话超模型 Token 窗口

- 逻辑：保留关键标识符、清理冗余 Token、重试机制

- 代码： src/agents/compaction.ts 及子模块

6. 多渠道统一（Channels）

- 对接：Telegram、Discord、Slack、飞书、钉钉、WebUI、CLI

- 机制：统一消息格式、Webhook/长连接、会话保持、OAuth 认证

四、关键源码文件与功能

- Gateway 入口：

src/gateway/server.ts （启动 WebSocket、加载配置、注册渠道）

-Agent 主循环：

src/agents/pi-embedded-runner/run.ts （ runEmbeddedPiAgent ）

- 工具策略：

src/agents/tool-policy-pipeline.ts （安全检查核心）

- 记忆检索：

src/memory/memory-search.ts （混合检索）

- 上下文构建：

src/context-engine/context-builder.ts

五、设计亮点

- 本地优先：数据/执行全本地，隐私可控

- 模型无关：兼容 Claude/GPT/Ollama 等

- 嵌入式执行：无 RPC，性能高、低延迟

- 沙箱安全：非信任会话强制隔离，企业级安全

- 插件化：Skill/Plugin 热加载，易扩展

六、一句话总结

OpenClaw 是本地 AI 执行中枢，用 Gateway 做路由、Agent 做执行、三级记忆做上下文、沙箱做安全，把自然语言变成电脑的真实操作。