OpenClaw — 项目架构全解

01

项目概述

OpenClaw 的核心设计理念与项目定位

🎯

核心理念

一个本地优先、快速响应、始终在线的个人 AI 助手。它不是云服务，而是运行在你自己的设备上，尊重你的隐私和安全。

💬

多渠道接入

WhatsApp、Telegram、Slack、Discord、Signal、iMessage、微软 Teams 等 20+ 种渠道连接你的 AI 助手。

🛠️

真实操作

AI 不只是聊天——它能控制浏览器、执行 Shell 命令、操作文件系统、渲染 Canvas 界面。

🔌

可扩展架构

插件 SDK + Skills 技能系统，40 个扩展插件覆盖渠道与功能扩展。

📱

全平台覆盖

macOS Menu Bar App、iOS / Android Node、CLI、Web UI 五种客户端形态。

🔒

安全优先

DM 配对验证、Docker 沙箱隔离、工具白名单/黑名单、Tailscale 安全远程访问。

02

系统架构

Gateway 控制面为核心的星型架构

消息渠道层

WhatsApp Telegram Slack Discord Google Chat Signal iMessage WebChat Matrix Teams 飞书 +10

▼

🦞 Gateway 控制面

ws://127.0.0.1:18789

路由引擎会话管理 Pi Agent 工具引擎插件管理配置系统安全策略 Cron 调度

▼ ▼

客户端

CLI macOS App iOS Node Android Node Web UI

工具

浏览器 Canvas Shell Cron Skills

03

核心模块 `src/`

52 个子目录 · 4700+ 文件 · 系统的心脏

🌐

Gateway

src/gateway/

整个系统的中枢。WebSocket 服务器（默认端口 18789），所有客户端通过 WS 连接。负责会话管理、消息路由、健康检查与诊断。

WebSocket 控制面 349 文件

🤖

Agent 引擎

src/agents/

AI 智能体运行时，基于 Pi Agent 核心。以 RPC 模式运行，支持 tool streaming 和 block streaming。可调用浏览器、Shell、Canvas 等工具。

Pi Agent RPC 823 文件

💬

内建渠道

src/telegram/ discord/ slack/ signal/ ...

6 个内建消息渠道适配器，每个包含 channel.ts（协议适配）、commands.ts（聊天命令）、groups.ts（群组）、media.ts（媒体）。

WhatsAppBaileys TelegramgrammY SlackBolt Discorddiscord.js Signalsignal-cli iMessageimsg

⌨️

CLI 命令

src/cli/ · src/commands/

命令行入口 openclaw.mjs → entry.ts → commander.js 分发。支持 onboard、gateway、agent、message send、doctor、channels、config 等子命令。

commander.js 648 文件

⚙️

配置系统

src/config/

配置文件 ~/.openclaw/openclaw.json（JSON5），TypeBox Schema 强类型校验，支持环境变量覆盖。

TypeBox JSON5 230 文件

🌍

浏览器控制

src/browser/

基于 Playwright 管理专属 Chrome/Chromium 实例。支持 CDP 控制、截图、操作自动化、上传、Profile 管理。

Playwright CDP 155 文件

🎬

媒体管道

src/media/ · src/media-understanding/

图片/音频/视频处理管线。Transcription hooks（语音转文字）、文件大小限制、临时文件生命周期。使用 sharp 处理图片。

sharp Transcription 104 文件

🧠

记忆系统

src/memory/

插件式内存架构（同时只有一个 memory 插件激活）。支持 LanceDB 向量数据库，用于 Agent 长期记忆和上下文检索。

LanceDB 向量检索 96 文件

🔐

安全模型

src/security/ · src/pairing/

DM 配对验证、Docker 沙箱隔离、工具权限白名单/黑名单、Tailscale 安全远程访问。

配对沙箱 38 文件

🧩

插件系统

src/plugins/ · src/plugin-sdk/

插件加载与管理框架 + 开发 SDK。支持 npm 包分发和本地扩展加载。

SDK npm 分发 195 文件

📦

扩展插件 `extensions/`

40 个独立 pnpm workspace 包

每个扩展都是独立的 npm 包，可以单独安装、更新和发布。分为渠道扩展和功能扩展两大类。

💬 渠道扩展 (14)

bluebubblesiMessage（推荐方案）

googlechatGoogle Chat

msteamsMicrosoft Teams

matrixMatrix 协议

feishu飞书

ircIRC

mattermostMattermost

nextcloud-talkNextcloud Talk

nostrNostr 协议

synology-chatSynology Chat

tlonTlon (Urbit)

twitchTwitch

zaloZalo (OA)

zalouserZalo (个人)

🧩 功能扩展 (10+)

voice-call语音通话

diffs代码差异展示

memory-core记忆核心

memory-lancedbLanceDB 向量记忆

llm-taskLLM 任务管理

device-pair设备配对

copilot-proxyCopilot 代理

open-prose文本处理

diagnostics-otelOpenTelemetry

acpxAgent Client Protocol

lobsterLobster 整合

thread-ownership线程归属

05

原生客户端 `apps/`

三大平台原生体验

🍎

macOS App

apps/macos/

Swift · SwiftUI · @Observable

Menu Bar 控制面（启停 Gateway、健康状态）
Voice Wake 唤醒词 + 按住说话
WebChat + 调试工具
远程 Gateway SSH 控制
Node 模式（system.run / system.notify）

360 文件

📱

iOS Node

apps/ios/

Swift · SwiftUI · XcodeGen

通过 WebSocket 配对到 Gateway
Canvas 可视化工作空间
Voice Wake + Talk Mode
摄像头、屏幕录制
Bonjour 设备发现

137 文件

🤖

Android Node

apps/android/

Kotlin · Gradle

Connect / Chat / Voice 标签页
Canvas、摄像头、屏幕录制
设备命令（通知/位置/短信/照片）
联系人 / 日历 / 运动数据
应用更新管理

144 文件

📦 apps/shared/OpenClawKit — iOS 与 macOS 共享的 Swift 库（118 文件）

06

数据流

从用户发送消息到收到回复的完整流程

1

👤 用户发送消息

通过 WhatsApp / Telegram / Slack 等任意渠道发送消息

→

2

📡 渠道适配器

对应渠道的 channel.ts 接收消息，标准化消息格式

→

3

🌐 Gateway 路由

WebSocket 传递到 Gateway，路由引擎匹配到正确的会话

→

4

🤖 Pi Agent

Agent 引擎处理消息，决定是直接回复还是需要调用工具

→

5

🛠️ 工具执行

可选：调用浏览器/Shell/Canvas/文件系统等工具

→

6

💬 回复返回

生成最终回复 → Gateway 路由回原渠道 → 用户看到回复

07

关键技术依赖

驱动 OpenClaw 的核心第三方库

🤖 AI & Agent

@mariozechner/pi-agent-coreAgent 运行时核心

@mariozechner/pi-aiAI 模型调用层

@mariozechner/pi-coding-agent编码 Agent

💬 渠道 SDK

@whiskeysockets/baileysWhatsApp Web 协议

grammyTelegram Bot API

@slack/boltSlack App 框架

discord.js (via @buape/carbon)Discord

🏗️ 基础设施

expressHTTP 服务器

wsWebSocket 服务器

playwright-core浏览器自动化

commanderCLI 框架

🔧 工具链

@sinclair/typebox运行时类型校验

sharp图片处理

zodSchema 校验

vitest测试框架

tsdownTypeScript 构建

oxlint / oxfmtLint 与格式化

08

安全模型

强默认，不牺牲能力

🏠

本地优先

Gateway 默认绑定 127.0.0.1（loopback），不对外暴露

🔑

DM 配对验证

未知发送者必须先通过配对码验证。openclaw pairing approve <channel> <code>

📦

Docker 沙箱

非 main 会话可在 Docker 容器中隔离运行。sandbox.mode: "non-main"

📋

工具权限

白名单：bash、process、read、write、edit、sessions_*
黑名单：browser、canvas、nodes、cron、discord、gateway

🌐

Tailscale 集成

Serve（内网访问）或 Funnel（公网访问），密码认证保护

🩺

安全诊断

openclaw doctor 检测并标记风险配置（DM 策略等）

09

构建与开发

开发工作流和关键命令

📥 安装

pnpm install

🔨 构建

pnpm build

TypeScript → dist/ (via tsdown)

🧪 测试

pnpm test

Vitest · 70% 覆盖率阈值

✅ 检查

pnpm check

格式 + TypeScript + Lint

🔄 开发

pnpm gateway:watch

热重载开发模式

🌐 UI

pnpm ui:dev

Web UI 开发服务器

10

项目目录全景

一览 OpenClaw 的文件组织

openclaw-main/
├── 📁 src/                 ← 核心源代码 (4700+ 文件)
│   ├── gateway/            ← Gateway 控制面 WebSocket 服务器
│   ├── agents/             ← Pi Agent AI 引擎
│   ├── telegram/           ← Telegram 渠道 (grammY)
│   ├── discord/            ← Discord 渠道
│   ├── slack/              ← Slack 渠道 (Bolt)
│   ├── signal/             ← Signal 渠道
│   ├── imessage/           ← iMessage 渠道
│   ├── web/                ← WhatsApp Web 渠道
│   ├── channels/           ← 渠道通用逻辑
│   ├── routing/            ← 消息路由引擎
│   ├── cli/                ← CLI 入口层
│   ├── commands/           ← CLI 子命令
│   ├── config/             ← 配置系统 (TypeBox)
│   ├── browser/            ← 浏览器控制 (Playwright)
│   ├── media/              ← 媒体管道
│   ├── memory/             ← 记忆系统
│   ├── security/           ← 安全模型
│   ├── plugins/            ← 插件管理
│   ├── plugin-sdk/         ← 插件开发 SDK
│   ├── sessions/           ← 会话管理
│   ├── cron/               ← 定时任务
│   ├── hooks/              ← Webhook 处理
│   ├── tts/                ← 文本转语音
│   ├── canvas-host/        ← Canvas A2UI
│   └── ...                 ← 更多模块
├── 📁 extensions/          ← 40 个扩展插件
│   ├── bluebubbles/        ← iMessage (推荐)
│   ├── msteams/            ← Microsoft Teams
│   ├── matrix/             ← Matrix 协议
│   ├── feishu/             ← 飞书
│   ├── voice-call/         ← 语音通话
│   ├── memory-lancedb/     ← 向量记忆
│   └── ...
├── 📁 apps/               ← 原生客户端
│   ├── macos/              ← macOS Menu Bar (Swift)
│   ├── ios/                ← iOS Node (Swift)
│   ├── android/            ← Android Node (Kotlin)
│   └── shared/             ← 共享 Swift 库
├── 📁 ui/                 ← Web UI (控制面)
├── 📁 docs/               ← 项目文档 (Mintlify)
├── 📁 scripts/            ← 构建/测试/发布脚本
├── 📁 skills/             ← 内置 Skills 技能
├── 📄 package.json          ← 项目配置 (v2026.3.8)
├── 📄 openclaw.mjs          ← CLI 入口
├── 📄 Dockerfile            ← Docker 构建
├── 📄 docker-compose.yml    ← Docker Compose
└── 📄 tsconfig.json         ← TypeScript 配置

🦞 OpenClaw

项目概述

核心理念

多渠道接入

真实操作

可扩展架构

全平台覆盖

安全优先

系统架构

消息渠道层

🦞 Gateway 控制面

客户端

工具

核心模块 src/

Gateway

Agent 引擎

内建渠道

CLI 命令

配置系统

浏览器控制

媒体管道

记忆系统

安全模型

插件系统

更多核心模块

扩展插件 extensions/

💬 渠道扩展 (14)

🧩 功能扩展 (10+)

原生客户端 apps/

macOS App

iOS Node

Android Node

数据流

👤 用户发送消息

📡 渠道适配器

🌐 Gateway 路由

🤖 Pi Agent

🛠️ 工具执行

💬 回复返回

关键技术依赖

🤖 AI & Agent

💬 渠道 SDK

🏗️ 基础设施

🔧 工具链

安全模型

本地优先

DM 配对验证

Docker 沙箱

工具权限

Tailscale 集成

安全诊断

构建与开发

📥 安装

🔨 构建

🧪 测试

✅ 检查

🔄 开发

🌐 UI

项目目录全景

核心模块 `src/`

扩展插件 `extensions/`

原生客户端 `apps/`