OpenClaw 深度解读 — 321K Star 开源 AI 助手全景交互指南

// 00

OpenClaw 能做什么？

如果你对技术细节不感兴趣，只想知道"这东西对我有什么用"——看这里。OpenClaw 本质上是一个运行在你自己服务器上的私人 AI 助手，和 ChatGPT 不同的是：你拥有完全控制权，数据不离开你的设备。

💬

在任何聊天工具里用 AI

不用打开浏览器，直接在你常用的 WhatsApp / Telegram / Slack / 飞书里和 AI 对话。就像和朋友聊天一样自然。

🔒

数据完全自主可控

所有聊天记录、配置、密钥都存在你自己的机器上。没有第三方服务器存你的数据。你选哪个 AI 模型，数据就只到那个模型。

🤖

AI 帮你操作电脑

不只是聊天——它可以帮你执行 Shell 命令、操控浏览器、管理文件、发邮件、定时任务，是真正的"AI 助手"。

🧠

它能记住你说过的话

内置长期记忆系统。上周聊到的项目进展、你的偏好、重要信息——它都能通过语义搜索回忆起来，不是只记最近几条。

🔌

想用什么 AI 就用什么

不绑定单一 AI 提供商。今天用 GPT-4o，明天换 Claude，后天试本地 Ollama——一行配置搞定，还支持自动故障转移。

⏰

定时任务 & 自动化

设置 Cron 定时任务让 AI 每天早上给你发天气预报，监控 GitHub Issue，自动回复消息——7×24 小时不间断。

和 ChatGPT / Copilot 有什么区别？

对比项	OpenClaw	ChatGPT / Copilot
数据存储位置	你自己的服务器	OpenAI / Microsoft 云端
AI 模型选择	任意切换 35+ 提供商	仅限平台自有模型
消息渠道	22+ (WhatsApp/Slack/飞书…)	仅网页/APP
执行系统命令	支持（沙盒化）	不支持
浏览器控制	内置 Playwright AI	不支持
定时自动化	Cron + Webhook	不支持
长期记忆	向量 + FTS 语义搜索	有限记忆
费用	开源免费 + API 费用	$20/月订阅

// 01

快速开始 — 三步上手

OpenClaw 是一个基于 Node.js 的个人 AI 助手。你可以把它想象成一个运行在你自己服务器上的"AI 管家"，通过 WhatsApp、Telegram、Slack 等任意渠道与你对话。

Step 1 — 安装

需要 Node.js ≥ 22。一条命令全局安装：

bashnpm install -g openclaw@latest

Step 2 — 初始化引导

交互式向导帮你配置 AI 模型、消息渠道和安全设置：

bashopenclaw onboard --install-daemon

Step 3 — 启动 Gateway

Gateway 是核心服务进程，通过 WebSocket 管理所有连接：

bashopenclaw gateway --port 18789 --verbose

完成后，OpenClaw 会在后台运行。你可以通过任何已配置的渠道向它发消息，也可以用 openclaw dashboard 打开 Web 控制面板。

// 02

架构全景 — 一切如何运转

OpenClaw 采用 Gateway 中心化架构。所有消息都流经 Gateway（网关），它就像一个"总控台"：接收来自各渠道的消息，交给 AI Agent 处理，再把回复送回去。

📱 消息渠道

WhatsApp / Telegram
Slack / Discord ...

→

🌐 Gateway

WebSocket :18789
认证 · 路由 · 会话

→

🧠 Pi Agent

AI 推理引擎
工具调用 · 流式输出

→

🔌 扩展 & 技能

75 Extensions
53 Skills

一条消息的完整旅程

当你在 WhatsApp 上发一条"帮我查一下明天的天气"，OpenClaw 内部会经历以下 8 个步骤：

① 渠道接收 — WhatsApp 扩展通过 Baileys SDK 收到你的消息，转为统一的内部消息格式

② 安全检查 — SecurityAdapter 验证你的身份（DM 白名单 / 群组策略），外部内容加上注入防护标记

③ 会话路由 — 根据会话键 whatsapp/你的号码/你的ID 找到或创建 Session，加载历史上下文

④ 记忆检索 — Memory 系统做语义搜索，找到相关的长期记忆片段注入上下文

⑤ Agent 推理 — Pi Agent 收到完整上下文，调用配置的 AI 模型（如 GPT-4o）进行流式推理

⑥ 工具调用 — AI 判断需要查天气 → 调用 web-search Tool → 返回搜索结果 → AI 继续生成回复

⑦ 回复投递 — OutboundAdapter 将回复按 WhatsApp 的字符限制分块，通过 Baileys 发送回去

⑧ 持久化 — 完整对话追加到 Session JSONL 文件，关键信息可存入长期记忆

🌐

Gateway 网关

Gateway 是 OpenClaw 的心脏。它是一个 WebSocket 服务器，运行在端口 18789 上。

通信协议：
① 客户端连接 → 服务端发送 connect.challenge 质询
② 客户端发送认证参数（Token/密码）
③ 认证通过 → 服务端发送完整状态快照
④ 双向通信开始：请求帧 / 响应帧 / 事件帧

所有帧都使用 TypeBox Schema 做类型校验，确保数据完整性。

🧠

Pi Agent 推理引擎

Pi 是嵌入式 AI Agent 运行时。你可以把它理解为 OpenClaw 的"大脑"。

核心能力：
• 流式推理 — 支持流式/非流式两种模式
• 工具调用 — Agent 可调用已注册的工具（发消息、搜记忆、执行命令…）
• 车道并发 — 每个会话可开多个"车道"(Lane)，并行处理多个请求
• 速率控制 — 内置限流与超时保护

💬

会话模型 (Session)

每条对话都被追踪为一个 Session。

会话键格式：{channel}/{account}/{sender}

• per-sender — 每个用户一个独立会话（默认）
• global — 所有用户共享一个会话
• 支持自动重置（空闲超时 / 每日重置）
• 会话历史存储为 JSONL 文件，支持压缩和自动清理

🗄️

记忆系统 (Memory)

OpenClaw 拥有长期记忆能力，不只是聊天历史。

• 向量搜索 — 使用 Embeddings 做语义检索
• 全文搜索 — SQLite FTS 作为兜底方案
• 时间衰减 — 旧内容自动降权
• 数据源覆盖 memory/ 目录和 sessions/ 历史

// 04

配置深潜 — 掌控一切

OpenClaw 使用 openclaw.json5 作为配置文件。所有配置都经过 Zod Schema 校验，写错了会直接告诉你哪里不对。

核心配置结构

json5{
  // 🌐 网关设置
  "gateway": {
    "port": 18789,
    "auth": {
      "mode": "password",
      "password": "your-secret"
    }
  },
  // 🤖 AI 模型提供商
  "models": {
    "providers": {
      "openai": {
        "apiKey": {
          "source": "env",
          "id": "OPENAI_API_KEY"
        }
      }
    }
  },
  // 💬 渠道配置
  "channels": { ... },
  // 🧠 Agent 定义
  "agents": { ... },
  // 📦 会话 · 记忆 · 钩子
  "session": { ... },
  "memory": { ... }
}

关键配置详解

gateway.auth.mode

认证模式：none（不推荐）| token | password | trusted-proxy（反代场景）

models.providers

支持多个 AI 提供商并行配置，内置故障转移。密钥支持环境变量、文件、命令三种引用方式。

session.scope

per-sender（每人独立，默认）或 global（所有人共享）。还可配置空闲重置和每日重置。

session.maintenance

自动修剪旧会话 pruneAfter: "30d"，磁盘限制 maxDiskBytes: "10gb"。

secrets

三种来源：env（环境变量）、file（文件）、exec（运行命令获取），运行时动态解析，不硬编码。

实战：Telegram + OpenAI 最小配置

从零到可用只需要这些配置。先设置环境变量，再写配置文件：

bash# 设置环境变量（或写入 .env）
export OPENAI_API_KEY="sk-..."
export TELEGRAM_BOT_TOKEN="123456:ABC-..."

json5// openclaw.json5 — 最小可用配置
{
  "gateway": {
    "port": 18789,
    "auth": { "mode": "password", "password": "my-secret-123" }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": { "source": "env", "id": "OPENAI_API_KEY" }
      }
    }
  },
  "channels": {
    "telegram": {
      "token": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" }
    }
  },
  "agents": {
    "default": {
      "model": "gpt-4o",
      "systemPrompt": "你是一个有用的中文助手。"
    }
  }
}

保存后运行 openclaw gateway 即可。在 Telegram 搜索你的 Bot 发消息就能收到回复。

进阶：多模型故障转移 + 会话管理

json5{
  "models": {
    "providers": {
      "anthropic": { "apiKey": { "source": "env", "id": "ANTHROPIC_API_KEY" } },
      "openai":    { "apiKey": { "source": "env", "id": "OPENAI_API_KEY" } }
    }
  },
  // 主力 Claude，挂了自动切换到 GPT-4o
  "agents": {
    "default": { "model": "claude-sonnet-4-20250514" }
  },
  "session": {
    "scope": "per-sender",           // 每人独立会话
    "reset": { "mode": "idle", "idleMinutes": 60 }, // 空闲1小时重置
    "maintenance": {
      "pruneAfter": "30d",        // 30天后清理
      "maxDiskBytes": "5gb"       // 磁盘上限
    }
  }
}

插件 & 扩展 — 无限可能

OpenClaw 的扩展能力来自 Plugin SDK。每个扩展通过 definePluginEntry() 注册自己的能力——模型提供商、渠道适配器、媒体处理器、搜索引擎，应有尽有。

// 07

安全架构 — 纵深防御

OpenClaw 采用多层防御策略。从网关认证到注入检测，从密钥管理到审计日志，每一层都在保护你的数据安全。

🔐

认证与授权

四种认证模式：
• none 无认证（仅限本地调试）
• token 令牌认证
• password 密码认证
• trusted-proxy 反向代理信任

内置暴力破解防护：指数退避的速率限制器，按 IP 追踪失败次数。

🛡️

注入攻击防护

外部内容（用户输入、网页抓取等）自动被包裹在安全标记中：

<<>>

同时在 LLM 上下文前注入安全警告，防止"忽略以上所有指令"类型的提示词注入攻击。

🔑

密钥管理

密钥不硬编码在配置文件中，而是使用引用：
• env — 从环境变量读取
• file — 从文件读取
• exec — 运行命令获取

密钥比对使用 timingSafeEqual 防止时序攻击。

📋

审计 & 扫描

• 运行时审计 — 所有操作留痕
• 技能扫描器 — 检测恶意代码
• 危险配置检测 — 正则匹配危险模式
• 危险工具检测 — 标记高风险工具调用
• DM 策略 — 允许/阻止列表控制私聊权限

// 08

技术栈 — 底层解剖

OpenClaw 选择 TypeScript 作为核心语言，运行在 Node.js ≥ 22 上。这不是随便选的——TypeScript 提供类型安全，Node.js 提供异步 I/O 和庞大的 npm 生态。

关键依赖解读

@whiskeysockets/baileys

WhatsApp Web 逆向工程库，实现无需官方 API 的 WhatsApp 接入

@grammyjs/runner

Telegram Bot 框架，高性能并发消息处理

@slack/bolt

Slack 官方 SDK，处理事件、命令和交互

@modelcontextprotocol/sdk

MCP 协议 SDK，支持连接 MCP 服务器扩展能力

better-sqlite3 + node:sqlite

本地 SQLite 存储，支持 FTS 全文搜索和向量索引

// 09

CLI 命令全览

OpenClaw 提供丰富的命令行工具，所有命令通过 openclaw <command> 调用。命令采用懒加载设计，按需导入，不拖慢启动速度。

初始化 & 配置

setup初始化本地配置

onboard交互式引导

configure交互式凭证配置

config get/set非交互配置读写

运行 & 管理

gateway run启动网关服务

dashboard打开 Web 面板

status查看渠道健康状态

health获取网关健康信息

doctor健康检查+修复

会话 & 消息

message send发送消息

sessions list查看对话列表

agent单轮 Agent 调用

agents add/list管理 Agent

memory search搜索记忆

浏览器 & 媒体

browser管理专属浏览器

backup创建/验证备份

reset重置本地配置

uninstall卸载网关+数据

// 10

媒体管道 & 浏览器控制

OpenClaw 不只是文字聊天——它可以处理图片、语音，甚至操控一个真实的浏览器为你完成任务。

🖼️

媒体管道

所有媒体文件经过沙盒化处理：

• 大小限制：单文件最大 5MB
• TTL 自动清理：默认 2 分钟后自动删除
• SSRF 防护：下载前验证 hostname
• 文件名消毒：去除危险字符，UUID 化
• MIME 检测：自动识别文件类型
• 安全权限：0o644 权限模型

🌍

浏览器控制

内置 Chrome/Chromium 控制系统：

• 独立 HTTP 服务器（默认 127.0.0.1:9222）
• Playwright AI 智能操作
• 多标签页管理与会话隔离
• 实时浏览器画面流
• Token/密码认证保护
• 仅限 localhost 访问

// 10.5

部署方案 — 从个人到生产

OpenClaw 支持多种部署方式。个人用一台树莓派就够，团队用可以部署到云服务器。

🖥️

方式 1：本地直接运行

最简单的方式。安装后直接启动，适合个人使用和开发调试。

bashnpm i -g openclaw@latest
openclaw onboard --install-daemon
# 守护进程会自动启动，开机自启

🐳

方式 2：Docker 容器

隔离环境，适合服务器部署。挂载配置和数据目录即可。

bashdocker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

☁️

方式 3：云服务 + 反向代理

生产部署推荐。用 Nginx 反代 + Let's Encrypt SSL，配合 trusted-proxy 认证模式。

json5// 反代场景配置
{
  "gateway": {
    "auth": { "mode": "trusted-proxy" },
    "trustedProxy": ["127.0.0.1"]
  }
}

守护进程支持

openclaw onboard --install-daemon 会自动检测你的操作系统，安装对应的守护进程：
• Linux → systemd service（systemctl start openclaw）
• macOS → launchd plist（开机自启 + 崩溃自动重启）
• Windows → schtasks 计划任务
用 openclaw doctor 随时检查服务状态和修复问题。

// FAQ

常见问题

从社区中收集的高频问题，给小白和开发者答疑。

Q：我不懂编程，能用 OpenClaw 吗？

可以。安装只需要一行命令，openclaw onboard 会通过交互式向导一步步引导你完成配置。你只需要有一个 AI 提供商的 API Key（如 OpenAI）和一个消息平台的 Bot Token。

Q：需要什么样的服务器？

非常轻量。1 核 1GB 内存的 VPS 就够个人使用。甚至树莓派 4 也能跑。需要 Node.js 22+ 和稳定的网络连接。如果启用浏览器控制功能，建议至少 2GB 内存。

Q：OpenClaw 本身收费吗？

OpenClaw 完全开源免费（MIT 协议）。你只需要为使用的 AI 模型 API 付费（如 OpenAI 按用量计费）。如果用本地模型（Ollama + 开源模型），连 API 费用都没有。

Q：安全吗？别人能看到我的聊天记录吗？

数据完全存在你自己的服务器。Gateway 支持 Token/密码认证，暴力破解有指数退避防护。外部内容有注入攻击防护。密钥使用时间安全比较防时序攻击。默认只允许配对的设备访问。

Q：我想开发自己的插件，怎么做？

创建一个 npm 包，声明 openclaw.plugin.json 清单文件，导出 definePluginEntry() 注册函数。通过 api.registerProvider() / api.registerChannelPlugin() 等方法注册能力。详见 plugin-sdk 的类型定义。

Q：能同时连多个渠道吗？

可以。你可以同时配置 WhatsApp + Telegram + Slack + Discord，它们共享同一个 AI Agent。每个渠道的每个用户有独立的会话（per-sender 模式），互不干扰。

Q：和 Dify / Coze / FastGPT 等平台有什么区别？

最大区别：OpenClaw 是个人助手而非团队平台。它不做工作流编排 UI，而是深度集成到你的日常通讯工具中。它能执行系统命令、控制浏览器、管理文件——是真正的计算机 Agent，不只是聊天机器人。

// 设计决策

架构设计模式 & 技术决策

给想深入了解或贡献代码的开发者——为什么 OpenClaw 的代码是这样组织的。

为什么选 TypeScript？

• 类型安全：531K 行代码没有类型系统会是灾难。Zod + TypeBox 做运行时校验，TypeScript 做编译时校验，双保险。
• npm 生态：Baileys(WhatsApp)、Grammy(Telegram)、Bolt(Slack) 等 SDK 全是 JS/TS 生态，零适配成本。
• 异步 I/O：Node.js 的事件循环天然适合处理大量并发的渠道连接和 API 调用。

核心设计模式

• 适配器模式：每个渠道实现统一接口（10 个 Adapter），新增渠道不改核心代码
• 插件注册模式：definePluginEntry() + api.register*()，运行时依赖注入
• 门面模式：PluginRuntime 封装复杂子系统，插件只看到简洁 API
• 策略模式：认证(4种模式)、投递(direct/gateway/hybrid)、存储(SQLite/LanceDB)

WebSocket 协议设计

• 三种帧类型：RequestFrame(请求)、ResponseFrame(响应)、EventFrame(推送)——对应 RPC + 事件广播两种通信模式
• 连接握手：Server 先发 challenge nonce → Client 回传认证 → Server 下发全量快照 + 可用 methods/events 列表
• 状态同步：初始全量快照 + 后续增量 delta，带版本号防乱序

代码组织哲学

• 按领域分目录：13 个 src/ 子目录对应 13 个业务领域，互不交叉
• 懒加载 CLI：每个命令独立 import()，启动只加载 commander 壳
• Skills = 文档不是代码：SKILL.md 教 AI 怎么用工具，而非硬编码行为
• Schema-first：Zod Schema 定义配置 → 自动生成 JSON Schema → 自动生成帮助文本 → 自动验证

// 加入社群

想玩转 OpenClaw？别自己踩坑

这个网站的作者娇姐，专注 OpenClaw 实战。从入门到精通的全套资料，都是自己踩坑整理的。

扫码关注 & 联系娇姐

公众号：娇姐话AI圈

关注获取 OpenClaw 最新教程 & 玩法

添加娇姐微信

备注「OpenClaw」· 咨询资料包 / 社群

说句实话：内容是娇姐自己踩坑过程中整理的，AI 辅助归纳后人工审核。尽量准确但不敢说完美。
有看不懂或者发现有问题的地方，群里一起聊，说不定有大佬能解答 :)

OpenClaw