OpenClaw 整体架构
什么是 OpenClaw？
OpenClaw 是一个自托管的 AI 助手平台，运行在你自己的设备上（笔记本、服务器、Mac Mini、云容器）。
它做两件事：
- 把各种聊天平台（WhatsApp、Telegram、Discord、飞书...）接入一个统一的 AI Agent
- 让 AI Agent 拥有工具能力（浏览器、文件操作、定时任务等），而不只是聊天
与普通聊天机器人的区别：普通机器人是"收到消息 → 调 API → 回复"。OpenClaw 是一套完整的基础设施------有会话管理、记忆系统、工具权限、消息路由、多 Agent 调度。
数据自主权：AI 模型的 API 调用走云端（Anthropic、OpenAI 等），但对话记录、工具执行、会话状态、调度逻辑全部留在你自己的设备上。
核心架构
OpenClaw 的架构可以用一句话概括：渠道适配 → 中央网关 → Agent 处理 → 回复分发。
┌──────────────────────────────────────────────────────────┐
│ 用户层 │
│ WhatsApp Telegram Discord 飞书 Web UI CLI │
└────┬──────────┬──────────┬────────┬──────┬───────┬───────┘
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
┌──────────────────────────────────────────────────────────┐
│ 渠道适配器 (Channel Plugin) │
│ • 认证（Bot Token / QR 码 / OAuth） │
│ • 消息解析（文字/图片/音视频 → 统一格式） │
│ • 访问控制（白名单、配对、群策略） │
│ • 发送格式化（Markdown 转换、长消息切分、媒体上传） │
└────────────────────────┬────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ Gateway（业务网关） │
│ • WebSocket 服务器 (默认 :18789) │
│ • 消息路由 → 决定交给哪个 Agent │
│ • 会话管理 → Session Key 标识每个对话 │
│ • 事件分发 → 实时通知 UI │
│ • 定时任务 → Cron │
│ • 状态持久化 → 文件系统 │
└────────────────────────┬────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ Agent 运行时 │
│ • 组装上下文（历史对话 + 系统提示词 + 记忆检索） │
│ • 调用 AI 模型（Claude / GPT / Gemini 等） │
│ • 执行工具（浏览器、命令行、文件操作等） │
│ • 保存状态（会话追加写入 JSONL） │
└──────────────────────────────────────────────────────────┘三大核心模块
1. 渠道适配器 (Channel Plugin)
作用：把不同平台的消息翻译成统一格式，把统一的回复翻译回平台格式。
代码位置：
- 内置渠道：
src/telegram/、src/discord/、src/slack/、src/signal/、src/imessage/、src/web/（WhatsApp） - 插件渠道：
extensions/feishu/、extensions/matrix/、extensions/msteams/等
每个渠道实现一个 ChannelPlugin 对象（见 01-tech-basics.md 中的适配器组合模式）。
2. Gateway（业务网关）
作用：消息调度中心，24x7 运行。
关键区别：这不是 Nginx 那种网络网关。它是有状态的业务网关，管理着：
- 所有渠道的长连接
- 所有会话的状态
- 配置的热加载
- 定时任务调度
代码位置 ：src/gateway/server.impl.ts
3. Agent 运行时
作用：真正的 AI 处理引擎。
执行循环：
- 加载会话历史
- 组装系统提示词 + 检索相关记忆
- 注册可用工具
- 调用 AI 模型
- 如果模型要求调用工具 → 执行工具 → 把结果喂回模型 → 重复
- 收集最终回复 → 保存状态 → 返回
代码位置 ：src/agents/pi-embedded-runner/run.ts
数据存储
所有数据都在本地文件系统：
| 数据 | 路径 | 格式 | 说明 |
|---|---|---|---|
| 配置 | ~/.openclaw/openclaw.json |
JSON5 | 支持注释、尾逗号 |
| 会话 | ~/.openclaw/sessions/ |
JSONL | 追加写入，支持压缩 |
| 记忆 | ~/.openclaw/memory/ |
SQLite + 向量 | 混合搜索（语义 + 关键词） |
| 凭据 | ~/.openclaw/credentials/ |
各类格式 | 权限 0600 |
控制界面
四种方式与 OpenClaw 交互：
- Web UI --- 浏览器访问
http://localhost:18789，聊天 + 配置管理 + 状态监控 - CLI ---
openclaw gateway run、openclaw agent、openclaw doctor等命令 - macOS 菜单栏应用 --- 一键启动/停止网关、语音唤醒
- 移动端 --- iOS/Android App，通过 WebSocket 连接网关
插件系统
OpenClaw 的可扩展性通过插件实现，不需要修改核心代码：
| 插件类型 | 用途 | 注册方式 |
|---|---|---|
| 渠道插件 | 接入新聊天平台 | registerChannel() |
| 工具插件 | 给 Agent 添加新能力 | registerTool() |
| 模型提供商插件 | 接入自定义 AI 模型 | registerProvider() |
| HTTP 路由插件 | 添加 webhook 端点 | registerHttpRoute() |
| 命令插件 | 扩展 CLI 命令 | registerCli() |
插件存放在 extensions/ 目录，每个是独立的 npm 包，通过 openclaw.plugin.json 声明元数据。
安全架构（概览）
| 层级 | 机制 |
|---|---|
| 网络 | 默认绑定 127.0.0.1，远程访问走 SSH 隧道或 Tailscale |
| 身份 | Token/密码认证 + 设备配对 |
| 渠道 | 白名单 + DM 配对审批 + 群聊策略 |
| 工具 | 主会话完全信任，外部会话沙箱隔离 |
详见 10-安全架构。
下一步
- 想看消息全链路？→ 03-消息流转
- 想理解关键设计决策？→ 04-设计原理
- 想深入 Gateway？→ 05-Gateway 深度解析