OpenClaw 项目深度解读

版本：2026.3.2 | 分析日期：2026-03-24 | 许可证：MIT

一、项目概述

1.1 OpenClaw 是什么

OpenClaw 是一个个人 AI 助手平台，核心理念是"运行在你自己的设备上、通过你已有的聊天渠道与你交互"。它不是一个云端 SaaS 产品，而是一个本地优先 (local-first) 的 AI 网关系统。

简单来说，OpenClaw 做的事情是：

用户在 WhatsApp/Telegram/Slack/Discord 等发消息
         ↓
   OpenClaw Gateway（本地网关）接收消息
         ↓
   调用 AI 模型（Claude/GPT 等）生成回复
         ↓
   将回复发送回对应的聊天渠道

![OpenClaw 消息流转全景：多渠道通过 Gateway 网关连接 AI 模型](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/01-infographic-openclaw-overview-1775150834972.png)

1.2 核心定位

维度	描述
产品类型	个人 AI 助手，非多租户 SaaS
部署方式	本地优先，支持自托管（Linux VPS、Docker、Fly.io）
消息渠道	22+ 种渠道：WhatsApp、Telegram、Slack、Discord、Signal、iMessage、IRC、Teams、Matrix、Feishu、LINE 等
AI 模型	多模型支持：Anthropic Claude、OpenAI GPT、Bedrock、本地 LLM（via llama.cpp）
技术栈	TypeScript (ESM)、Node.js 22+、pnpm monorepo
开源协议	MIT

![OpenClaw 核心定位六维度：产品类型、部署方式、消息渠道、AI 模型、技术栈、开源协议](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/02-infographic-core-positioning-1775150835971.png)

1.3 项目演进

项目经历了多次更名：Warelay → Clawdbot → Moltbot → OpenClaw，最终定位为开源的个人 AI 助手平台。

二、整体架构

2.1 架构总览

OpenClaw 采用经典的星型架构，Gateway（网关）是中心节点，所有组件通过 WebSocket 协议与 Gateway 通信：

WhatsApp / Telegram / Slack / Discord / Signal / iMessage / IRC / Teams / ...
                          │
                          ▼
            ┌─────────────────────────────┐
            │         Gateway              │
            │      (控制平面)               │
            │   ws://127.0.0.1:18789       │
            └──────────┬──────────────────┘
                       │
          ┌────────────┼────────────────┐
          │            │                │
     Pi Agent       CLI 工具          客户端
     (RPC 模式)    (openclaw …)      (macOS/iOS/Android)
                                      WebChat UI

2.2 分层架构

┌──────────────────────────────────────────────┐
│                CLI 入口层                      │
│   entry.ts → program.ts → 各命令模块           │
├──────────────────────────────────────────────┤
│              Gateway 网关层                    │
│   HTTP Server + WebSocket + 认证 + 事件总线    │
├──────────────────────────────────────────────┤
│            Channel 渠道层                      │
│   WhatsApp / Telegram / Discord / Slack / ... │
├──────────────────────────────────────────────┤
│            Agent 智能体层                      │
│   Pi Agent Runtime + 工具系统 + 会话管理       │
├──────────────────────────────────────────────┤
│            基础设施层                          │
│   Config / Logging / Media / Infra / Plugins  │
└──────────────────────────────────────────────┘

![OpenClaw 星型架构与五层分层架构](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/03-infographic-architecture-1775150836757.png)

三、项目目录结构

openclaw-2026.3.2/
├── src/                    # 核心源码（TypeScript）
│   ├── entry.ts            # CLI 主入口
│   ├── index.ts            # 库导出入口
│   ├── runtime.ts          # 运行时环境抽象
│   ├── cli/                # CLI 命令行工具
│   ├── commands/           # CLI 子命令实现
│   ├── gateway/            # Gateway 网关服务器
│   ├── config/             # 配置管理系统
│   ├── agents/             # Agent 智能体管理
│   ├── channels/           # 渠道抽象与路由
│   ├── discord/            # Discord 渠道实现
│   ├── signal/             # Signal 渠道实现
│   ├── imessage/           # iMessage 渠道实现
│   ├── line/               # LINE 渠道实现
│   ├── plugins/            # 插件系统
│   ├── plugin-sdk/         # 插件开发 SDK
│   ├── hooks/              # 钩子系统（Gmail 等）
│   ├── cron/               # 定时任务系统
│   ├── browser/            # 浏览器控制（CDP）
│   ├── media/              # 媒体处理管道
│   ├── memory/             # 记忆系统（向量 + SQLite）
│   ├── infra/              # 基础设施工具
│   ├── logging/            # 日志系统
│   ├── secrets/            # 密钥管理
│   ├── security/           # 安全审计
│   ├── acp/                # Agent Client Protocol
│   ├── auto-reply/         # 自动回复
│   ├── daemon/             # 守护进程管理
│   ├── markdown/           # Markdown 渲染
│   ├── process/            # 进程管理
│   └── shared/             # 共享工具
├── extensions/             # 扩展插件（monorepo 工作区包）
│   └── irc/                # IRC 渠道插件（示例）
├── apps/                   # 原生应用
│   ├── macos/              # macOS 菜单栏应用（SwiftUI）
│   ├── ios/                # iOS 节点应用（SwiftUI）
│   └── android/            # Android 节点应用（Kotlin）
├── skills/                 # 内置技能定义
│   ├── github/SKILL.md     # GitHub 技能
│   ├── slack/SKILL.md      # Slack 技能
│   ├── discord/SKILL.md    # Discord 技能
│   ├── weather/SKILL.md    # 天气查询技能
│   └── ...                 # 更多技能
├── docs/                   # 文档（Mintlify 托管）
├── scripts/                # 构建/部署/维护脚本
├── git-hooks/              # Git 钩子
├── patches/                # pnpm 补丁
├── package.json            # 项目主配置
├── pnpm-workspace.yaml     # monorepo 工作区配置
├── Dockerfile              # Docker 构建文件
├── fly.toml                # Fly.io 部署配置
└── AGENTS.md               # AI Agent 编码规范

四、核心模块详解

4.1 CLI 入口系统 (`src/entry.ts` → `src/cli/`)

启动流程：

openclaw.mjs (npm bin 入口)
    → src/entry.ts (主入口)
        → 设置进程标题 "openclaw"
        → 标准化环境变量 (normalizeEnv)
        → 启用编译缓存 (enableCompileCache)
        → 抑制 Node 实验性警告 (respawn 子进程)
        → 解析 CLI profile
        → 快速路径：--version / --help
        → 完整路径：import("./cli/run-main.js") → runCli()

src/entry.ts 的设计亮点：

isMainModule 守卫：防止作为依赖被 import 时重复执行 CLI 逻辑
respawn 机制：通过 spawn 子进程添加 --disable-warning=ExperimentalWarning 标志
快速路径：--version 和 --help 不需要加载完整 CLI 框架

CLI 命令结构（基于 Commander.js）：

命令	功能
`openclaw gateway run`	启动 Gateway 服务器
`openclaw agent`	与 AI Agent 交互
`openclaw onboard`	引导式初始设置向导
`openclaw channels login`	登录消息渠道
`openclaw config set`	修改配置
`openclaw status`	查看状态
`openclaw doctor`	诊断和修复
`openclaw message send`	发送消息
`openclaw tui`	终端 UI 模式
`openclaw plugins`	插件管理
`openclaw cron`	定时任务管理

![CLI 入口系统：启动流程与 10 大核心命令](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/04-infographic-cli-system-1775150837686.png)

4.2 Gateway 网关 (`src/gateway/`)

Gateway 是整个系统的核心控制平面，基于 Express.js HTTP 服务器 + WebSocket 实现。

核心职责：

WebSocket 控制平面 — 所有客户端（CLI、macOS app、iOS/Android nodes、WebChat）通过 WS 连接
消息路由 — 将入站消息从各渠道路由到正确的 Agent 会话
会话管理 — 维护多会话状态（main session、group sessions）
认证与安全 — Token 认证、DM 配对（pairing）机制
事件总线 — 广播事件给所有连接的客户端

关键文件：

gateway/server.ts — 服务器入口，导出 startGatewayServer
gateway/boot.ts — 启动编排逻辑
gateway/auth.ts — 认证中间件
gateway/hooks.ts — 生命周期钩子
gateway/events.ts — 事件系统
gateway/ws-log.ts — WebSocket 日志

Gateway 默认绑定：

地址：127.0.0.1（仅本地回环）
端口：18789
协议：ws://（本地环境不强制 TLS）

![Gateway 网关五大核心职责](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/05-infographic-gateway-1775150838643.png)

4.3 Channel 渠道系统 (`src/channels/` + 各渠道目录)

渠道系统是 OpenClaw 最大的子系统，负责与 22+ 种消息平台对接。

架构设计（适配器模式）：

每个渠道都实现了一套标准化的适配器接口：

typescript

interface ChannelPlugin {
  meta: ChannelMeta; // 渠道元数据
  setup?: ChannelSetupAdapter; // 初始化设置
  config?: ChannelConfigAdapter; // 配置管理
  auth?: ChannelAuthAdapter; // 认证
  messaging?: ChannelMessagingAdapter; // 消息收发
  outbound?: ChannelOutboundAdapter; // 出站消息
  streaming?: ChannelStreamingAdapter; // 流式响应
  group?: ChannelGroupAdapter; // 群组管理
  pairing?: ChannelPairingAdapter; // 配对机制
  security?: ChannelSecurityAdapter; // 安全策略
  status?: ChannelStatusAdapter; // 状态检查
  // ... 更多适配器
}

核心渠道（内置于 src/）：

渠道	SDK/库	实现目录
WhatsApp	@whiskeysockets/baileys	`src/` (channel-web.ts)
Telegram	grammy	`src/`
Discord	Carbon + discord.js	`src/discord/`
Slack	@slack/bolt	`src/`
Signal	signal-cli	`src/signal/`
iMessage (legacy)	imsg	`src/imessage/`
LINE	@line/bot-sdk	`src/line/`
Feishu	@larksuiteoapi/node-sdk	`src/`

扩展渠道（extensions/）：

渠道	类型
IRC	扩展插件
Microsoft Teams	扩展插件
Matrix	扩展插件
Zalo / Zalo Personal	扩展插件
BlueBubbles (iMessage)	扩展插件
Voice Call	扩展插件

DM 安全策略：

OpenClaw 默认采用 pairing（配对） 模式处理 DM：

未知发送者收到一个短配对码
Bot 不处理未配对用户的消息
管理员通过 openclaw pairing approve <channel> <code> 批准
被批准的发送者加入本地白名单

![渠道适配器模式与 22+ 消息渠道](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/06-infographic-channel-system-1775150839481.png)

4.4 Agent 智能体系统 (`src/agents/`)

OpenClaw 使用 Pi Agent 作为核心 AI Agent 运行时（由 Mario Zechner 开发的 @mariozechner/pi-agent-core 等包）。

Agent 运行模式：

RPC 模式 — Agent 通过 RPC 与 Gateway 通信，支持工具流式传输和块流式传输
会话隔离 — 每个对话（DM/群组）拥有独立的会话和上下文

会话模型：

main 会话 — 直接对话的默认会话
群组会话 — 每个群组隔离的独立会话
多 Agent 路由 — 可将不同渠道/账户路由到不同的 Agent 实例

Agent 工作区：

~/.openclaw/workspace/
├── AGENTS.md          # Agent 行为指令
├── SOUL.md            # Agent 人格定义
├── TOOLS.md           # 工具配置
└── skills/            # 技能目录
    ├── github/SKILL.md
    ├── weather/SKILL.md
    └── ...

工具系统（Tools）：

工具类别	说明
Browser	浏览器控制（Playwright + CDP）
Canvas	可视化工作区（A2UI）
Nodes	设备操作（摄像头、屏幕录制、通知）
Cron	定时任务
Sessions	跨会话通信（sessions_list / sessions_send）
Exec	执行 shell 命令
Skills	技能调用

![Agent 智能体系统全貌：运行模式、工作区与工具系统](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/07-infographic-agent-system-1775150840473.png)

4.5 插件系统 (`src/plugins/` + `src/plugin-sdk/`)

OpenClaw 有一个完善的插件 SDK，允许第三方开发者扩展功能。

插件注册模式：

typescript

// extensions/irc/index.ts
import type { ChannelPlugin, OpenClawPluginApi } from "openclaw/plugin-sdk";
import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";

const plugin = {
  id: "irc",
  name: "IRC",
  description: "IRC channel plugin",
  configSchema: emptyPluginConfigSchema(),
  register(api: OpenClawPluginApi) {
    api.registerChannel({ plugin: ircPlugin as ChannelPlugin });
  },
};

export default plugin;

Plugin SDK 导出的核心类型：

OpenClawPluginApi — 插件注册 API
ChannelPlugin — 渠道插件接口
PluginRuntime — 运行时访问
OpenClawConfig — 配置读取
Webhook 工具函数、状态帮助函数、配对与认证工具

插件安装方式：

npm 包分发 (npm install)
本地 extension loading（开发模式）
通过 openclaw plugins 命令管理

4.6 配置系统 (`src/config/`)

配置系统使用 Zod 进行 schema 验证，配置文件为 JSON5 格式。

配置文件位置：

~/.openclaw/openclaw.json

最小配置示例：

json5

{
  agent: {
    model: "anthropic/claude-opus-4-6",
  },
}

配置 Schema 覆盖约 30+ 个顶层域：

配置域	说明
`agent`	Agent 模型和行为
`channels.whatsapp`	WhatsApp 渠道配置
`channels.telegram`	Telegram 渠道配置
`channels.discord`	Discord 渠道配置
`channels.slack`	Slack 渠道配置
`channels.signal`	Signal 渠道配置
`gateway`	Gateway 服务器配置
`browser`	浏览器控制配置
`agents.defaults`	Agent 默认值
`agents.routes`	多 Agent 路由规则
`security`	安全策略
`logging`	日志配置

4.7 媒体处理管道 (`src/media/`)

负责处理图片、音频、视频等多媒体内容：

图片处理 — 使用 sharp 进行图片操作（压缩、转换、裁剪）
音频处理 — 使用 node-edge-tts (TTS)、opusscript (Opus 编码)
MIME 检测 — 使用 file-type 检测文件类型
Base64 编解码 — 媒体内容的序列化传输
存储管理 — 临时文件生命周期管理

4.8 记忆系统 (`src/memory/`)

支持持久化的对话记忆：

SQLite 存储 — 基于 SQLite 的持久化存储
向量检索 — 使用 sqlite-vec 进行向量相似度搜索（MMR 算法）
混合检索 — 结合关键词和向量的混合检索策略

4.9 浏览器控制 (`src/browser/`)

基于 Playwright + Chrome DevTools Protocol (CDP) 的浏览器自动化：

管理独立的 OpenClaw 专用 Chrome/Chromium 实例
支持页面快照、DOM 操作、文件上传
浏览器 profile 隔离

4.10 定时任务 (`src/cron/`)

基于 croner 库的 cron 调度系统：

支持标准 cron 表达式
任务持久化存储
执行日志追踪
错峰执行 (stagger)

五、应用层 (apps/)

5.1 macOS 应用 (SwiftUI)

类型：菜单栏应用（menu bar app）
功能：Gateway 控制、Voice Wake（唤醒词）、Push-to-Talk、WebChat、调试工具
技术：SwiftUI + Observation 框架
通信：通过 Gateway WebSocket 协议

5.2 iOS 应用 (SwiftUI)

类型：设备节点（Node）
功能：Canvas 画布、Voice Wake、Talk Mode、摄像头、屏幕录制、Bonjour 发现 + 设备配对
通信：通过 WS 配对到 Gateway

5.3 Android 应用 (Kotlin)

类型：设备节点（Node）
功能：聊天、语音、Canvas、摄像头/屏幕录制、Android 设备命令（通知/位置/SMS/照片/联系人/日历等）
通信：通过 WS 配对到 Gateway

六、技能系统 (Skills)

Skills 是 Agent 可以调用的预定义能力模块，每个技能由一个 SKILL.md 文件描述。

内置技能列表：

技能	说明
`github`	GitHub 操作（Issues/PRs/代码）
`slack`	Slack 消息和管理
`discord`	Discord 操作
`weather`	天气查询
`notion`	Notion 操作
`trello`	Trello 看板管理
`canvas`	Canvas 画布控制
`clawhub`	ClawHub 技能仓库搜索
`gemini`	Google Gemini 模型
`openhue`	Philips Hue 智能灯控制
`camsnap`	摄像头拍照
`tmux`	tmux 终端管理
`browser`	浏览器操作
`imsg`	iMessage 操作

技能分发方式：

内置技能 (bundled) — 随 OpenClaw 安装
托管技能 (managed) — 通过 ClawHub (clawhub.com) 分发
工作区技能 (workspace) — 用户本地定义在 ~/.openclaw/workspace/skills/

![技能系统：3 种分发方式与 14 个内置技能](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/08-infographic-skills-system-1775150841343.png)

七、构建与开发工具链

7.1 技术选型

工具	用途
TypeScript	主要开发语言（严格模式，ESM）
pnpm	包管理器（monorepo 支持）
tsdown	TypeScript 打包（ESBuild-based）
Vitest	测试框架（V8 覆盖率）
Oxlint	Lint 工具（Rust 实现，高性能）
Oxfmt	代码格式化工具
tsgo	TypeScript 类型检查（Go 实现的 TS 编译器预览版）
Commander.js	CLI 框架
Express 5	HTTP 服务器
Zod	Schema 验证
sharp	图片处理
Playwright	浏览器自动化

7.2 核心命令

bash

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 类型检查
pnpm tsgo

# Lint + 格式检查
pnpm check

# 运行测试
pnpm test

# 覆盖率测试
pnpm test:coverage

# 开发模式（自动重载）
pnpm gateway:watch

# CLI 开发
pnpm openclaw <command>

7.3 Monorepo 结构

通过 pnpm-workspace.yaml 管理多个工作区：

yaml

packages:
  - . # 主包 (openclaw)
  - ui # Web UI
  - packages/* # 共享包
  - extensions/* # 扩展插件

7.4 测试体系

测试类型	配置	命令
单元测试	`vitest.unit.config.ts`	`pnpm test:fast`
E2E 测试	`vitest.e2e.config.ts`	`pnpm test:e2e`
渠道测试	`vitest.channels.config.ts`	`pnpm test:channels`
Gateway 测试	`vitest.gateway.config.ts`	`pnpm test:gateway`
扩展测试	`vitest.extensions.config.ts`	`pnpm test:extensions`
Live 测试	`vitest.live.config.ts`	`pnpm test:live`
Docker 测试	Shell 脚本	`pnpm test:docker:all`

覆盖率要求：70% lines/branches/functions/statements

![构建与开发工具链：技术选型与测试体系](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/09-infographic-toolchain-1775150842201.png)

八、部署方式

8.1 本地安装（推荐）

bash

npm install -g openclaw@latest
openclaw onboard --install-daemon

安装守护进程后 Gateway 会以 launchd/systemd 服务运行。

8.2 Docker 部署

bash

docker build -t openclaw .
docker run -p 18789:18789 openclaw

项目提供了 Dockerfile、docker-compose.yml、Dockerfile.sandbox（沙箱模式）。

8.3 Fly.io 部署

配置文件：fly.toml / fly.private.toml，支持一键部署到 Fly.io 平台。

8.4 远程访问

Tailscale Serve/Funnel — 通过 Tailscale 暴露 Gateway（推荐）
SSH 隧道 — 传统 SSH 端口转发
密码认证 — Funnel 模式强制要求密码

九、安全模型

9.1 核心原则

OpenClaw 的安全设计是一个刻意的权衡：在保持强大能力的同时采用安全的默认值。

9.2 关键安全机制

机制	说明
DM 配对	默认对未知发送者要求配对验证
白名单	`allowFrom` 控制谁可以与 Bot 交互
沙箱模式	非 main 会话可在 Docker 沙箱中运行
Elevated 权限	需要显式启用的提升权限模式
密钥管理	`~/.openclaw/credentials/` 存储凭证
SSRF 防护	`src/infra/net/ssrf.ts` 防止服务端请求伪造
安全审计	`openclaw doctor` 检测风险配置

9.3 信任模型

main 会话：Agent 拥有主机完全访问权限（单用户设计）
群组/渠道会话：可配置沙箱模式 (sandbox.mode: "non-main")
操作者信任：操作者被视为可信，恶意操作者不在威胁模型内
入站 DM：默认视为不可信输入

![安全模型：7 大安全机制与三层信任模型](https://qn.huat.xyz/blog/article-Illustration/OpenClaw 项目深度解读/10-infographic-security-model-1775150843085.png)

十、关键依赖分析

10.1 消息渠道 SDK

依赖	用途
`@whiskeysockets/baileys`	WhatsApp Web 协议
`grammy`	Telegram Bot API
`@buape/carbon`	Discord 交互
`@slack/bolt`	Slack 应用框架
`@discordjs/voice`	Discord 语音
`@larksuiteoapi/node-sdk`	飞书 SDK
`@line/bot-sdk`	LINE Messaging API

10.2 AI / Agent

依赖	用途
`@mariozechner/pi-agent-core`	Pi Agent 核心运行时
`@mariozechner/pi-ai`	AI 模型抽象层
`@mariozechner/pi-coding-agent`	编码 Agent
`@mariozechner/pi-tui`	终端 UI Agent
`@aws-sdk/client-bedrock`	AWS Bedrock (Claude)
`@agentclientprotocol/sdk`	Agent Client Protocol

10.3 基础设施

依赖	用途
`express`	HTTP 服务器 (v5)
`ws`	WebSocket
`commander`	CLI 框架
`zod`	Schema 验证
`sharp`	图片处理
`playwright-core`	浏览器自动化
`better-sqlite3`	SQLite 数据库
`sqlite-vec`	SQLite 向量扩展
`pdfjs-dist`	PDF 解析
`chokidar`	文件监视

十一、设计亮点与工程实践

11.1 渠道无关的消息抽象

OpenClaw 通过 ChannelPlugin 接口实现了完全的渠道无关性。新增渠道只需实现标准适配器接口，无需修改核心逻辑。

11.2 插件化架构

核心保持精简，可选功能通过插件实现。这种设计让 OpenClaw 的核心安装包小巧，同时通过插件生态扩展无限可能。

11.3 本地优先的隐私设计

所有数据存储在本地（~/.openclaw/），不依赖云端存储。用户完全控制自己的数据和密钥。

11.4 严格的代码质量管控

Oxlint（Rust 实现的 Lint）替代 ESLint，速度大幅提升
Oxfmt 格式化
tsgo（Go 实现的 TS 类型检查器）替代 tsc，构建速度极快
V8 覆盖率阈值 70%
pre-commit hooks 强制检查

11.5 多平台支持

通过 Gateway 协议的统一设计，同一个后端可以同时服务 CLI、Web UI、macOS 菜单栏应用、iOS 应用和 Android 应用。

十二、Chat 命令系统

用户可以在聊天渠道中通过斜杠命令控制 Agent：

命令	功能
`/status`	查看会话状态（模型、Token 使用量）
`/new` / `/reset`	重置会话
`/compact`	压缩会话上下文
`/think <level>`	设置思考级别（off/minimal/low/medium/high/xhigh）
`/verbose on/off`	详细模式开关
`/usage off/tokens/full`	使用量显示
`/restart`	重启 Gateway（仅 owner）
`/activation mention/always`	群组激活模式

十三、项目愿景与未来方向

根据 VISION.md，当前优先级：

核心优先级：

安全与安全默认值
Bug 修复与稳定性
初次安装的可靠性和用户体验

后续优先级：

支持所有主要模型提供商
改进主要消息渠道支持
性能和测试基础设施
更好的 computer-use 和 Agent 能力
CLI 和 Web 前端的人体工程学
macOS / iOS / Android / Windows / Linux 伴侣应用

明确不合并的内容：

核心中的新技能（应发布到 ClawHub）
全文档翻译集
不明确属于模型提供商类别的商业服务集成
核心中的一等 MCP 运行时（使用 mcporter 桥接）
Agent 层级框架（manager-of-managers）

十四、快速上手指南

bash

# 1. 全局安装
npm install -g openclaw@latest

# 2. 运行初始化向导
openclaw onboard --install-daemon

# 3. 启动 Gateway
openclaw gateway --port 18789 --verbose

# 4. 发送测试消息
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# 5. 与 Agent 对话
openclaw agent --message "帮我写一个 Hello World" --thinking high

总结

OpenClaw 是一个设计精良的开源个人 AI 助手平台，其核心架构围绕 Gateway 网关 构建，通过 插件化的渠道适配器 连接 22+ 种消息平台，使用 Pi Agent 运行时驱动 AI 交互。项目采用 TypeScript + pnpm monorepo 架构，拥有完善的测试体系、安全模型和部署方案。

OpenClaw 项目深度解读 ​

一、项目概述 ​

1.1 OpenClaw 是什么 ​

1.2 核心定位 ​

1.3 项目演进 ​

二、整体架构 ​

2.1 架构总览 ​

2.2 分层架构 ​

三、项目目录结构 ​

四、核心模块详解 ​

4.1 CLI 入口系统 (src/entry.ts → src/cli/) ​

4.2 Gateway 网关 (src/gateway/) ​

4.3 Channel 渠道系统 (src/channels/ + 各渠道目录) ​

4.4 Agent 智能体系统 (src/agents/) ​

4.5 插件系统 (src/plugins/ + src/plugin-sdk/) ​

4.6 配置系统 (src/config/) ​

4.7 媒体处理管道 (src/media/) ​

4.8 记忆系统 (src/memory/) ​

4.9 浏览器控制 (src/browser/) ​

4.10 定时任务 (src/cron/) ​

五、应用层 (apps/) ​

5.1 macOS 应用 (SwiftUI) ​

5.2 iOS 应用 (SwiftUI) ​

5.3 Android 应用 (Kotlin) ​

六、技能系统 (Skills) ​

七、构建与开发工具链 ​

7.1 技术选型 ​

7.2 核心命令 ​

7.3 Monorepo 结构 ​

7.4 测试体系 ​

八、部署方式 ​

8.1 本地安装（推荐） ​

8.2 Docker 部署 ​

8.3 Fly.io 部署 ​

8.4 远程访问 ​

九、安全模型 ​

9.1 核心原则 ​

9.2 关键安全机制 ​

9.3 信任模型 ​

十、关键依赖分析 ​

10.1 消息渠道 SDK ​

10.2 AI / Agent ​

10.3 基础设施 ​

十一、设计亮点与工程实践 ​

11.1 渠道无关的消息抽象 ​

11.2 插件化架构 ​

11.3 本地优先的隐私设计 ​

11.4 严格的代码质量管控 ​

11.5 多平台支持 ​

十二、Chat 命令系统 ​

十三、项目愿景与未来方向 ​

十四、快速上手指南 ​

总结 ​

OpenClaw 项目深度解读

一、项目概述

1.1 OpenClaw 是什么

1.2 核心定位

1.3 项目演进

二、整体架构

2.1 架构总览

2.2 分层架构

三、项目目录结构

四、核心模块详解

4.1 CLI 入口系统 (`src/entry.ts` → `src/cli/`)

4.2 Gateway 网关 (`src/gateway/`)

4.3 Channel 渠道系统 (`src/channels/` + 各渠道目录)

4.4 Agent 智能体系统 (`src/agents/`)

4.5 插件系统 (`src/plugins/` + `src/plugin-sdk/`)

4.6 配置系统 (`src/config/`)

4.7 媒体处理管道 (`src/media/`)

4.8 记忆系统 (`src/memory/`)

4.9 浏览器控制 (`src/browser/`)

4.10 定时任务 (`src/cron/`)

五、应用层 (apps/)

5.1 macOS 应用 (SwiftUI)

5.2 iOS 应用 (SwiftUI)

5.3 Android 应用 (Kotlin)

六、技能系统 (Skills)

七、构建与开发工具链

7.1 技术选型

7.2 核心命令

7.3 Monorepo 结构

7.4 测试体系

八、部署方式

8.1 本地安装（推荐）

8.2 Docker 部署

8.3 Fly.io 部署

8.4 远程访问

九、安全模型

9.1 核心原则

9.2 关键安全机制

9.3 信任模型

十、关键依赖分析

10.1 消息渠道 SDK

10.2 AI / Agent

10.3 基础设施

十一、设计亮点与工程实践

11.1 渠道无关的消息抽象

11.2 插件化架构

11.3 本地优先的隐私设计

11.4 严格的代码质量管控

11.5 多平台支持

十二、Chat 命令系统

十三、项目愿景与未来方向

十四、快速上手指南

总结