认识 OpenClaw - 工作原理

一、核心：Gateway 是唯一真相来源

Gateway（网关） 是 OpenClaw 的核心，负责：

会话管理（Sessions）
：维护所有对话的上下文与状态
消息路由（Routing）
：决定消息由哪个 Agent 处理、发往哪个会话
通道连接（Channel connections）
：与 WhatsApp、Telegram、Discord 等保持连接

所有会话状态、配置和路由逻辑都由 Gateway 统一管理，是系统的「唯一真相来源」。

二、整体架构（官方 Mermaid 图）

Chat apps + plugins  →  Gateway  →  Pi agent
                           ↓
                    ┌──────┼──────┐
                    ↓      ↓      ↓
                 CLI   Web UI   macOS app
                           ↓
                 iOS and Android nodes

入口
：聊天应用 + 插件（WhatsApp、Telegram、Discord、iMessage、Mattermost 等）
中心
：Gateway
出口
：Pi Agent、CLI、Web Control UI、macOS 应用、iOS/Android 节点

三、各组件关系与职责

组件	职责
聊天 App	用户发消息的界面，消息通过对应通道传给 Gateway
Gateway	接收消息、选择 Agent 和会话、调用 AI、把回复发回通道
Pi Agent	OpenClaw 内嵌的编码 Agent，负责实际对话与工具调用
Web Control UI	浏览器端管理界面，可聊天、配置、查看会话
macOS App	桌面端配套应用
iOS / Android 节点	移动端节点，通过配对与 Gateway 通信

四、消息流转详解

用户发消息
：在 WhatsApp、Telegram 等 App 中发送文本、图片或语音
通道接收
：对应通道（如 WhatsApp Web、Telegram Bot）收到消息
送入 Gateway
：通道将消息以统一格式传给 Gateway
路由与会话
：Gateway 根据 session.dmScope、bindings 等配置确定：

使用哪个 Agent
使用哪个会话（新建或复用）

调用 Agent
：消息进入 Agent 的上下文中，由 Pi 等模型处理
工具调用（可选）
：Agent 可能执行命令、读写文件、浏览网页等
回复生成
：Agent 生成回复，支持流式输出
发回通道
：Gateway 将回复发回对应通道
用户收到
：用户在聊天 App 中看到 AI 的回复

五、关键概念简要说明

概念	含义
Gateway	核心进程，管理通道、会话、路由和配置
Channel	与聊天平台对接的通道，如 WhatsApp、Telegram
Agent	AI 代理，默认使用 Pi，有独立工作区（workspace）和会话
Session	一次对话的上下文，由 `sessionKey` 标识，存储为 JSONL
Workspace	Agent 的工作目录，存放 USER.md、AGENTS.md、skills 等
Session key	会话标识，如 `main`（共享私聊）、`agent:::group:`（群聊）等

六、会话作用域（dmScope）

私聊如何划分会话由 session.dmScope 决定：

值	说明
`main`	默认，所有私聊共享一个会话（适合单人使用）
`per-peer`	按发送者 ID 隔离，跨通道同一人共享会话
`per-channel-peer`	按通道 + 发送者隔离（多用户推荐）
`per-account-channel-peer`	按账号 + 通道 + 发送者隔离（多账号场景）

多人使用时，建议设置 dmScope: "per-channel-peer"，避免不同用户共享同一会话导致信息泄露。

七、工作区与 Bootstrap 文件

Agent 使用一个 workspace 目录作为工作空间。其中可包含：

USER.md
— 用户简介与偏好
IDENTITY.md
— Agent 名称与风格
BOOTSTRAP.md
— 首次运行的初始化流程（完成后可删除）
TOOLS.md
— 工具使用说明与约定
SOUL.md
— 人设、边界与语气
AGENTS.md
— 操作说明与「记忆」

新会话开始时，这些文件会被注入到 Agent 上下文中（空白文件会跳过）。

八、状态存储位置

会话记录
：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
会话索引
：~/.openclaw/agents/<agentId>/sessions/sessions.json
工作区
：默认 ~/.openclaw/workspace，可配置