Module 1

你已经每天在用的 App,
都能成为你的 AI 助手入口

WhatsApp、微信、Slack、Telegram——你每天打开几十次的这些 App,OpenClaw 让它们全部变成你私人 AI 助手的对话窗口。同一个助手,在所有平台上为你服务,记住你的偏好,理解你的上下文。

OpenClaw 是什么? 一个运行在你自己设备上的个人 AI 助手平台。它的核心理念:你的数据待在你的设备上,你的助手在你已经在用的渠道里响应你。目前支持超过 25 种通讯平台。

你在 WhatsApp 上问一个问题——发生了什么

25+ 支持的平台

OpenClaw 把这些平台统统转化成你的 AI 对话入口:

💬
即时通讯
WhatsApp · Telegram · Signal · iMessage · LINE · WeChat · QQ · Zalo
💼
工作协作
Slack · Microsoft Teams · Mattermost · Matrix · Google Chat · Feishu
🎮
社区平台
Discord · Twitch · Nostr · IRC
🌐
专有系统
BlueBubbles · Synology Chat · Nextcloud Talk · Tlon · WebChat

三分钟启动:onboard 命令

真实代码 README.md → 快速开始
# 安装 OpenClaw
npm install -g openclaw
# 或用 pnpm / bun

# 运行引导向导(推荐)
openclaw onboard
# 这个命令会:
# 1. 引导你配置 Gateway
# 2. 设置你的工作区
# 3. 连接第一个通讯渠道
# 4. 验证连接是否正常
这段代码在说什么
npm install -g openclaw 全局安装 OpenClaw CLI,装一次到处用。支持 npm、pnpm 或 bun 包管理器
openclaw onboard 交互式引导向导,一步步帮你完成配置。比读文档快 10 倍——只需回答提问
Gateway / 工作区 / 渠道 三层配置:Gateway 是服务器核心;工作区是你的身份和设置;渠道是具体的通讯平台连接

模块测验

你在 Slack 上给 OpenClaw 发了一条消息,30 秒后你的 Telegram 也收到了同一个助手的回复(你同时在两个平台都连接了 OpenClaw)。这说明 OpenClaw 架构的什么特点?
你想在自己的电脑上运行 OpenClaw,同时接入 WhatsApp 和 Telegram。首先应该执行什么命令?
Module 2

Gateway:
所有消息的中央枢纽

想象一座大型机场的控制塔。无论是从哪个跑道起降,所有飞机都要和同一个控制塔通信。OpenClaw 的 Gateway 就是这座控制塔——所有平台的消息,都在这里汇聚、处理、分发。

Gateway 的核心职责

🔄
消息标准化
把 WhatsApp 的"wa_msg"格式、Slack 的"event"格式,统统转成统一的内部消息结构。上游不知道、也不需要知道消息来自哪里。
🧠
AI 路由
决定哪条消息交给哪个 AI 模型处理。可以给不同渠道配置不同的模型,甚至不同的人格。
🔌
扩展编排
调用已安装的扩展插件(天气、搜索、日历等),把结果注入 AI 的回复流程。
📤
响应分发
把 AI 的回复,通过正确的渠道适配器,发回到原始发送平台(可能还有格式转换)。

Entry.ts:Gateway 的启动序列

真实代码 src/entry.ts(启动文件)
function createGatewayEntryStartupTrace(argv: string[]) {
  const enabled =
    isTruthyEnvValue(
      process.env.OPENCLAW_GATEWAY_STARTUP_TRACE
    ) && argv.slice(2).includes("gateway");
  const started = performance.now();
  return {
    mark(name: string) {
      // 记录每个启动阶段的耗时
      const now = performance.now();
      emit(name, now - last, now - started);
    }
  };
}
这段代码在说什么
OPENCLAW_GATEWAY_STARTUP_TRACE 一个调试开关。设置这个环境变量为"true",就能看到 Gateway 启动的每个步骤花了多少毫秒
argv.slice(2).includes("gateway") 检查命令行参数里有没有"gateway"——只有启动 Gateway 模式时才开启追踪,避免干扰其他命令
performance.now() 高精度计时器,单位毫秒。用来测量每个启动步骤的耗时,找出启动瓶颈

Gateway 与渠道的对话

新消息到达!来自用户 @dan,内容:/weather 上海
收到。解析为统一格式:{platform: "telegram", userId: "@dan", text: "/weather 上海", command: "weather", args: ["上海"]}
识别到 /weather 命令,路由到天气扩展插件...
查询上海天气... 返回:晴,22°C,北风 3 级,明天有雨。
调用 AI 生成自然语言回复...
发送回复给 @dan:上海今天晴转多云,22°C,记得明天带伞!

Canvas:AI 的可视化画布

除了文字聊天,OpenClaw 还支持Canvas——一个你可以控制的实时展示面板。当 AI 的回答需要图表、代码、格式化表格时,它可以把内容渲染到 Canvas 上。

💡 为什么这很重要: 纯文字对话有其局限——复杂数据在聊天气泡里很难阅读。Canvas 把 AI 助手从"发短信的朋友"升级为"在白板上给你做演示的顾问"。特别适合数据分析、代码审查、规划可视化等场景。
你用 Slack 问 OpenClaw "给我看一下本周的销售数据趋势",OpenClaw 应该怎么展示最合适?
Module 3

扩展系统:
给助手装上超能力

一个基础的 AI 助手能聊天。但当它会查天气、能生成图片、可以控制智能家居、能读取你的日历——它就从聊天机器人变成了真正的私人助理。这就是 OpenClaw 扩展系统的价值。

已有的官方扩展

🧠
memory-lancedb
长期记忆:用向量数据库记住你的偏好、历史对话要点。助手越用越懂你。
🎨
image-generation-core
图片生成:接入 DALL-E、Stable Diffusion 等图像 AI,在聊天里直接生成图片。
🗣️
azure-speech
语音能力:文字转语音(TTS)和语音转文字(STT),让助手能说能听。
🤖
lmstudio
本地模型:接入 LM Studio 运行的本地大模型,完全离线使用,零数据外泄。
🛠️
skill-workshop
技能工坊:可视化创建自定义技能,无需编码。定义触发词、执行步骤、返回格式。
🌙
moonshot
月之暗面模型适配器:接入 Moonshot(Kimi)AI,支持超长上下文对话。

扩展 SDK:如何构建自己的超能力

真实代码 packages/plugin-sdk/src/plugin-entry.ts
// 一个扩展的基本结构
export interface PluginEntry {
  // 扩展的唯一标识符
  id: string;
  // 扩展提供的能力描述
  capabilities: string[];
  // 初始化:连接外部服务
  initialize(config: PluginConfig): Promise;
  // 处理用户请求
  handleRequest(
    request: PluginRequest
  ): Promise;
}
这段代码在说什么
export interface PluginEntry 定义了所有扩展必须实现的"合同"。就像插座的标准接口——任何符合这个接口的扩展,都能接入 OpenClaw
capabilities: string[] 这个扩展能做什么?比如 ["image_generation", "dalle3"]。Gateway 根据这个决定什么时候调用这个扩展
initialize(config): Promise<void> 启动时初始化,连接 API 服务、读取配置、建立连接。Promise 表示这是异步操作——等连接建好再继续
handleRequest(request): Promise<PluginResponse> 核心功能:接收用户请求,执行扩展逻辑,返回结果给 Gateway

一个扩展如何被调用的全过程

💡 关键设计: 扩展是松耦合的。Gateway 不需要知道 image-generation-core 是怎么实现的,只知道它能"处理图像生成请求"。这意味着你可以换一个不同的图像生成扩展,Gateway 完全不用修改。

模块测验

你想让 OpenClaw 能访问你的谷歌日历,在你说"明天我有什么安排"时自动查询。这需要什么?
OpenClaw 的扩展系统使用松耦合设计(通过 PluginEntry 接口通信)。这带来的最大实际好处是?
Module 4

渠道适配器:
每个平台都有自己的语言

WhatsApp 的消息格式和 Slack 的完全不同。Discord 的 webhook 和 Telegram 的 Bot API 工作原理也不一样。渠道适配器是翻译官——把每个平台独特的"方言"翻译成 OpenClaw 的"普通话"。

Webhook vs 轮询:两种接收消息的方式

OpenClaw 支持两种方式接收来自平台的消息:

📡
Webhook(推送模式)
平台主动推送消息到你的服务器。实时性好,效率高。需要你的服务器有公网地址。WhatsApp、Slack、Discord 使用此方式。
🔄
轮询(拉取模式)
OpenClaw 主动定期询问平台"有新消息吗"。适合不支持 Webhook 的平台。延迟稍高,但更简单。某些 IRC/Legacy 系统使用此方式。
本地部署的挑战: Webhook 需要平台能访问到你的服务器地址。如果你在家运行 OpenClaw,你的家庭网络可能没有固定公网 IP。OpenClaw 的文档提供了通过反向代理解决这个问题的方案。

跨平台消息同步的核心结构

统一消息格式(概念)
// 所有渠道的消息被标准化为:
interface UnifiedMessage {
  id: string;           // 唯一消息 ID
  platform: string;     // "whatsapp" | "slack" | ...
  userId: string;       // 发送者身份
  workspaceId: string;  // 所属工作区
  text?: string;        // 文字内容
  attachments?: {       // 附件(图片、文件等)
    type: string;
    url: string;
  }[];
  timestamp: Date;      // 发送时间
}
这段代码在说什么
platform: "whatsapp" | "slack" | ... 记录消息来自哪个平台。这让 AI 可以知道上下文——Slack 的对话风格和 WhatsApp 私聊不同
workspaceId: string 工作区 ID:支持一个 Gateway 服务多个"身份"——比如你的工作助手和私人助手是完全独立的配置
attachments?: [...] 可选的附件列表。? 表示"可能有也可能没有"。图片、文件、语音消息都归类在这里

iOS/Android 原生应用:语音助手的硬件层

OpenClaw 在 iOS 和 Android 上有原生应用(Swift / Kotlin 开发),这让它能使用手机的麦克风和扬声器,实现真正的语音对话:

嘿,帮我把明天下午三点的会议推迟到四点
🎤 录音结束,转文字完成...
接收到语音转文字消息,路由到日历扩展...
找到明天15:00的会议:Team Sync,修改时间到16:00,已更新
🔊 播放:"好的,已将明天下午三点的 Team Sync 改到四点。"

模块测验

你在家里的电脑上运行 OpenClaw,想接收 WhatsApp 消息(Webhook 模式)。但你的家庭宽带没有固定公网 IP。你应该怎么解决?
你同时在 Slack 和微信上和 OpenClaw 聊天,两个对话有完全不同的话题。OpenClaw 如何保证两个对话的上下文不混淆?
Module 5

本地优先:
你的数据,只属于你

大多数 AI 服务把你的对话发送到他们的云端服务器处理,存储在他们的数据库里。OpenClaw 的设计哲学正好相反:本地优先(Local-first)——计算在你的设备上,数据留在你手里。

本地运行 vs 云端服务的真正区别

☁️
传统云端 AI 服务
你的消息 → 发到他们服务器 → AI 处理 → 返回结果。你的数据经过第三方。延迟:网络往返时间。
💻
OpenClaw 本地模式
你的消息 → 本地 Gateway → 本地 AI 模型 → 本地返回。数据不离开你的设备。延迟:内存级别。
混合模式也支持: 你可以选择:对敏感对话用本地模型,对复杂任务用云端 API(GPT-4、Claude 等)。OpenClaw 的模型路由让你自由配置这个策略。

本地模型接入:LM Studio 扩展

真实配置 extensions/lmstudio
{
  "extension": "lmstudio",
  "config": {
    "baseUrl": "http://localhost:1234",
    "model": "llama-3.2-3b",
    "contextLength": 8192,
    "temperature": 0.7
  },
  "routing": {
    "defaultForPlatforms": ["telegram"],
    "fallback": "openai"
  }
}
这段代码在说什么
"baseUrl": "http://localhost:1234" 连接到在本机 1234 端口运行的 LM Studio。localhost 表示"本机",数据不出本机
"model": "llama-3.2-3b" 使用 Llama 3.2(3B 参数版本)作为本地模型。3B 模型对普通电脑友好,4GB 内存即可运行
"defaultForPlatforms": ["telegram"] Telegram 的对话默认用本地模型——隐私要求高的场景走本地,复杂任务走云端
"fallback": "openai" 如果本地模型无法处理,回退到 OpenAI。智能降级,不影响用户体验

长期记忆:向量数据库的魔法

memory-lancedb 扩展用向量数据库 LanceDB 实现助手的长期记忆:

我不喜欢太正式的语气,跟我说话随意一点
💾 存储偏好:{type: "tone", value: "casual", strength: 0.9}
帮我写一封给客户的道歉信
🔍 检索相关记忆... 找到:用户偏好轻松语气(相关性 0.87)
好嘞!草稿来了,我尽量写得直接点: "嗨 [客户名],上次的事儿真的很抱歉..."
💡 这就是"越用越懂你"的底层: 不是魔法,是向量搜索。每次对话都在悄悄丰富助手对你的理解,下次对话时,最相关的记忆会被检索出来,让助手的回答更贴合你的偏好和上下文。

终极测验:整合所有知识

你是一家律师事务所的合伙人,想用 OpenClaw 为团队搭建内部 AI 助手,但客户案件信息绝对不能上传到任何外部服务器。最合适的配置方案是?
你发现 OpenClaw 的某个扩展出了 bug,想临时禁用它,同时保证其他功能正常工作。根据 OpenClaw 的松耦合扩展架构,这意味着?