OpenClaw 项目介绍

项目定位

OpenClaw 是一个运行在你自己设备上的个人 AI 助手网关。它通过你已经在使用的消息渠道（WhatsApp、Telegram、Slack、Discord、Signal、iMessage 等）与你交互，同时支持语音、图像、视频和 Canvas 渲染能力。网关只是控制平面，产品本身是一个始终在线、本地化、快速响应的助手。

如果你需要一个私人的、单用户的、感觉像本地原生应用的 AI 助手，OpenClaw 就是为此设计的。

核心能力

多消息渠道网关：一个 Gateway 进程同时维护 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat 等 20+ 渠道连接
嵌入式 Agent 运行时：基于 “pi-agent-core” 的完整 Agent 循环（摄入 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化）
多 Agent 路由：支持多个完全隔离的 Agent（独立工作区、会话、认证配置），适合多用户或个人/工作分离场景
35+ 模型提供商：OpenAI、Anthropic、Google、DeepSeek、Ollama、vLLM、SGLang 等，支持 OAuth 和 API Key 认证
可扩展插件架构：Provider 插件、通道插件、工具插件、Hook 插件，通过 openclaw/plugin-sdk 注册能力
记忆与上下文管理：Markdown 文件记忆、语义搜索（FTS5 + sqlite-vec）、自动上下文压缩（Compaction）、Dreaming 背景整合
设备节点：macOS/iOS/Android 节点通过 WebSocket 配对，支持相机、屏幕录制、位置、语音等能力
语音交互：Voice Wake 唤醒词、Talk Mode（Realtime / STT-TTS / Transcription）、ElevenLabs TTS
Canvas / A2UI：Agent 驱动的可视化工作区，从文本输出中提取交互式 UI 规范并渲染

技术栈

层级	技术
运行时	Node.js 22+ (ESM)
语言	TypeScript
配置校验	TypeBox / JSON Schema
插件加载	jiti (in-process)
传输协议	WebSocket (控制平面) + HTTP API
存储	SQLite (默认)、JSONL (会话记录)
包管理	pnpm workspace monorepo
构建	tsdown (rolldown-based)
测试	Vitest

架构概览

快速体验

# 安装（需要 Node.js 22+）
npm install -g openclaw

# 启动引导向导
openclaw onboard

# 启动网关
openclaw gateway --port 18789

# 查看状态
openclaw status
openclaw gateway status

教程导读

本项目教程分为 AI 和 Dev 两个方向，共 25 章：

AI 教程（14 章）聚焦 OpenClaw 的 Agent 设计决策：

Agent 核心循环的实现方案 — 双层嵌套队列、生命周期事件流、外层重试循环
系统提示的组装策略 — 缓存边界、Bootstrap 文件注入、Prompt Mode、确定性排序
工具调用与共享 Message 工具 — 内置工具集、共享 message 工具架构、审批机制
流式传输的双层架构 — block streaming + preview streaming、围栏感知分块
记忆系统：Markdown 文件与 Dreaming — SQLite + FTS5 + sqlite-vec、三种 Dreaming 模式
上下文压缩：可插拔 Compaction — 自适应分块、渐进式摘要、三级回退
模型故障转移：Auth Profile 旋转 — 两阶段故障转移、冷却机制、WHAM 集成
多 Agent 路由与委托架构 — Session 隔离、Delegate 架构、Harness 选择
MCP 集成 — MCP 工具服务端点与工具生态集成
安全沙箱与工具策略 — Docker/SSH/Browser 沙箱、工具策略、节点执行安全
会话修剪与上下文引擎 — ContextEngine 接口、Legacy 引擎、上下文投影
队列与消息路由 — per-session lane、四种队列模式、线程绑定
语音交互模式 — Realtime/STT-TTS/Transcription、WebRTC、Voice Wake
Canvas 与 A2UI 渲染 — JSON 提取、短代码解析、围栏感知渲染

Dev 教程（11 章）聚焦 OpenClaw 的工程实践：

插件架构的四层模型 — Manifest → Enablement → Loading → Consumption
网关 WebSocket 协议设计 — JSON-over-WebSocket RPC、Challenge-Nonce 握手
通道插件的共享 Message 工具架构 — 18 种适配器、消息信封、动作发现
Provider 插件的多能力注册模型 — 100+ 字段接口、动态模型目录、缓存感知提示
SDK 子路径设计 — 54 个子路径、窄导入、导入边界强制
配置与状态管理 — 六层加载、Snapshot 热重载、SecretRef、崩溃恢复
技能系统与 Hook 系统 — SKILL.md、36 种 Typed Hook、动态导入缓存失效
扩展系统与 Bundled 分发 — 120+ 内置扩展、ClawHub、三层边界检查
设备节点与配对协议 — 8 字符配对码、Ed25519 签名、Bootstrap Token
守护进程与服务管理 — launchd/systemd/schtasks、服务审计
通道消息生命周期 — 入站事件、ReplyDispatcher、Turn 管理

源码版本：本教程基于 OpenClaw v2026.5.20 (commit 7f499643) 分析。所有知识点均来自源码探索、官方文档和 TypeScript 定义文件验证。