OpenClaw 架构与源码解析适合什么读者？

OpenClaw 架构与源码解析适合希望系统掌握 OpenClaw 专题的读者，尤其是需要从概念快速过渡到实践的人。页面包含主题摘要、相关阅读和来源链接，便于形成可执行的学习路径。

阅读 OpenClaw 架构与源码解析需要多久？

当前页面预估阅读时长约 8 分钟。建议先读正文结论，再根据“同专题延伸”继续阅读，通常 20 到 40 分钟可以建立完整主题框架。

如何把 OpenClaw 架构与源码解析的内容用于实际项目？

先按正文中的关键概念完成最小可运行示例，再把示例嵌入你当前项目流程。你可以结合来源链接验证细节，并使用同专题文章补齐部署、协作和评估步骤。

OpenClaw 架构与源码解析

Q: OpenClaw 架构与源码解析 适合什么读者？

OpenClaw 架构与源码解析 适合希望系统掌握 OpenClaw 专题 的读者，尤其是需要从概念快速过渡到实践的人。页面包含主题摘要、相关阅读和来源链接，便于形成可执行的学习路径。

来源：github.com/openclaw/openclaw | docs.openclaw.ai | 整理时间：2026-04-06

概述

OpenClaw 不仅仅是一个聊天机器人包装器——它是一个结构化的 AI Agent 执行环境，包含会话管理、记忆系统、工具沙箱和消息路由。AI 模型提供智能，OpenClaw 提供执行环境。

技术栈：TypeScript (ESM) + Node.js 22+，pnpm monorepo，WebSocket RPC 协议。

项目结构

openclaw/
├── src/
│   ├── gateway/          # Gateway 控制平面核心
│   ├── agents/           # Agent 运行时
│   │   └── pi-embedded-runner/  # 执行引擎（4层管道）
│   ├── config/           # 配置 Schema（Zod/TypeBox）
│   ├── plugins/          # 插件加载器、注册表
│   ├── plugin-sdk/       # 插件开发 SDK
│   ├── cli/              # CLI 入口（Commander.js）
│   └── commands/         # CLI 命令实现
├── extensions/           # 40+ 插件包（频道、模型、工具）
├── apps/
│   ├── ios/              # iOS 应用（Swift/SwiftUI）
│   ├── macos/            # macOS 菜单栏应用
│   └── android/          # Android 应用（Kotlin/Jetpack Compose）
├── ui/                   # Web 控制台（Lit Web Components）
├── vendor/a2ui/          # Agent-to-UI 开放标准
└── docs/                 # 文档（含 i18n 中文）

核心架构：Gateway

Gateway（src/gateway/server.impl.ts）是整个系统的控制平面，运行在 127.0.0.1:18789。

职责

WebSocket RPC 服务：处理所有客户端通信
频道路由：管理 WhatsApp、Telegram、Discord 等适配器
Agent 编排：调度 Agent 运行，流式返回结果
会话管理：SessionManager 管理对话状态
设备配对：iOS/Android/macOS 设备注册
HTTP 服务：控制台 UI、Webhook、健康检查

通信协议（Protocol v3）

Gateway 使用 WebSocket RPC 协议，所有帧都是 JSON 编码，经过 Zod Schema 校验：

帧类型	用途
`ConnectFrame`	客户端握手，携带协议版本、角色（operator/node）
`RequestFrame`	RPC 方法调用，携带唯一关联 ID
`ResponseFrame`	成功/错误响应
`EventFrame`	服务端推送事件（agent、presence、health、tick）

30+ RPC 方法按领域组织：agent.*、chat.*、sessions.*、devices.*、cron.*、config.*。

WhatsApp / Telegram / Discord / ...
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       ws://127.0.0.1:18789    │
│                               │
│  ┌─────────┐  ┌───────────┐  │
│  │ Channel │  │ Session   │  │
│  │ Router  │  │ Manager   │  │
│  └────┬────┘  └─────┬─────┘  │
│       │             │         │
│  ┌────▼─────────────▼────┐   │
│  │    Agent Runtime      │   │
│  │  (pi-embedded-runner) │   │
│  └───────────────────────┘   │
└───────────────────────────────┘

Agent 运行时：4 层执行管道

Agent 运行时（src/agents/pi-embedded-runner/）采用4 层执行管道架构：

层级	函数	职责
L1	`runReplyAgent`	队列策略、命令检测、后处理、用量上报
L2	`runAgentTurnWithFallback`	重试循环：压缩、瞬态错误、角色冲突
L3	`runEmbeddedPiAgent`	队列管理、模型解析、认证轮换
L4	`runEmbeddedAttempt`	工作区设置、工具创建、单次模型调用、流式输出

单次对话生命周期

会话解析：确定会话 ID（main / dm:<channel>:<id> / group:<channel>:<id>）
上下文组装：会话历史 + 系统提示 + 记忆检索 + 技能注入
流式模型调用：向配置的模型提供商发起请求
工具调用执行：拦截并执行工具调用（可在 Docker 沙箱中）
状态持久化：将结果写回磁盘

系统提示词组装（模块化）

系统提示由多个文件按需组合：

AGENTS.md：核心 Agent 指令（内置默认）
SOUL.md：个性和语气（可选）
TOOLS.md：用户自定义工具约定（可选）
skills/<skill>/SKILL.md：按需注入的技能指令
记忆检索结果：语义相似的过往上下文
工具定义：自动生成自内置工具和插件

插件系统

OpenClaw 的扩展能力基于能力注册式插件模型。

插件发现顺序

配置显式路径（plugins.load.paths）
工作区插件（<workspace>/.openclaw/extensions/）
全局插件（~/.openclaw/extensions/）
内置插件（随 OpenClaw 发布）

注册 API（`OpenClawPluginApi`）

方法	用途
`registerProvider(spec)`	注册 AI 模型提供商
`registerTool(tool)`	注册 Agent 工具
`registerHook(hook)`	订阅生命周期事件
`registerChannel(channel)`	注册聊天平台适配器
`registerService(service)`	注册后台服务
`registerGatewayRoute(route)`	注册 HTTP 路由
`registerSpeechProvider(...)`	注册语音合成
`registerWebSearchProvider(...)`	注册网页搜索

频道插件（25+ 平台）

WhatsApp（Baileys）、Telegram（grammY）、Discord（discord.js）、Slack、Signal、iMessage（BlueBubbles）、Matrix、IRC、LINE、微信（腾讯插件）、飞书等。

技能系统（Skills）

技能是以 SKILL.md 文件存储的模块化指令集，遵循 AgentSkills.io 规范。

技能来源（按优先级）

工作区技能（<workspace>/skills/）—— 每个 Agent 独立，最高优先
托管技能（~/.openclaw/skills/）—— 全局共享
内置技能—— 随 OpenClaw 发布
额外目录—— 通过 skills.load.extraDirs 配置

技能特性

需求门控：按操作系统、二进制可用性、环境变量自动匹配
自动安装：依赖缺失时自动安装（brew > uv > node > go > download）
按需注入：不是所有技能都注入每个提示词，按相关性选择
会话快照：保证对话过程中的提示词一致性

记忆系统

会话状态

会话以追加式 JSONL 事件日志存储在 ~/.openclaw/sessions/
会话 ID 编码信任边界：
- agent:<agentId>:main —— 完全权限
- agent:<agentId>:<channel>:dm:<id> —— 沙箱隔离
- agent:<agentId>:<channel>:group:<id> —— 沙箱隔离
上下文超出 Token 预算时自动压缩（compaction），可选在压缩前刷入记忆

长期记忆

存储：~/.openclaw/memory/<agentId>.sqlite（SQLite + sqlite-vec）
混合搜索：向量相似度（余弦）+ BM25 关键词匹配，加权合并
记忆文件：MEMORY.md（长期事实，仅私有会话）、memory/YYYY-MM-DD.md（每日笔记）
嵌入模型：自动选择本地模型 > OpenAI > Gemini > 禁用

安全模型

信任模型

OpenClaw 设计为单用户受信操作者模式，不是多租户隔离系统。

边界	信任级别
Gateway 配置/状态	受信（控制一切）
已认证调用者	受信（操作者级别）
频道消息	不受信（潜在注入）
插件/技能	受信代码（进程内运行）

纵深防御

网络：默认仅本地回环（127.0.0.1），远程访问需 SSH 隧道/Tailscale/Fly.io
认证：Token、密码或设备配对模式
DM 配对：默认需要 openclaw pairing approve 审批
工具沙箱：Docker 隔离，seccomp/AppArmor 配置，可配置网络模式
安全审计：openclaw security audit 命令检查配置、沙箱、频道、工具、技能

工具策略优先级（从宽到严）

Global > Provider > Agent > Group > Sandbox

后者覆盖前者，确保细粒度控制。

模型提供商支持

提供商	模型	特性
Anthropic	Claude 4.6 系列	Prompt Cache、Fallback
OpenAI	GPT-5.4	Codex 支持
Google	Gemini 3.1	OAuth CLI
GitHub Copilot	—	设备登录、运行时 Token 交换
Ollama	本地模型	完全离线
Mistral、MiniMax、Moonshot 等	—	多密钥轮换处理 429

Agent 间通信（A2A）

Agent 之间通过会话工具协作：

工具	功能
`sessions_list`	发现所有活跃 Agent 会话
`sessions_send`	向另一个会话发送消息
`sessions_history`	获取其他会话的对话记录
`sessions_spawn`	创建新会话委托任务

典型场景：一个 Agent 写代码，另一个 Agent 审查；主 Agent 把任务委托给专业子 Agent。

部署模式

模式	说明
本地开发	`pnpm dev`，热重载，无认证
macOS 生产	LaunchAgent + 菜单栏应用 + Voice Wake
Linux/VPS	systemd 服务 + SSH 隧道或 Tailscale
Fly.io	Docker 容器 + 持久卷 + 托管 HTTPS

关键源码文件索引

文件	说明
`src/gateway/server.impl.ts`	Gateway 启动和核心接线
`src/agents/pi-embedded-runner/run.ts`	Agent 执行入口
`src/agents/pi-embedded-runner/run/attempt.ts`	单次模型调用（L4）
`src/agents/pi-embedded-runner/compact.ts`	上下文压缩
`src/plugins/loader.ts`	插件发现和加载
`src/plugins/registry.ts`	插件注册 API
`src/agents/skills-status.ts`	技能扫描、状态、安装
`src/security/audit.ts`	安全审计系统
`extensions/memory-core/index.ts`	记忆插件实现