OpenClaw 系统架构详解
原文作者：Paolo Perazzo｜发布于 2026 年 2 月 11 日｜Products for Humans
引言
OpenClaw 是一个自托管的个人 AI 助手平台，运行在用户自己的基础设施上，同时能够接入你日常使用的各类消息应用（WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams）。该系统将 AI 视为一个基础设施问题，而非仅仅是提示词工程的挑战。
核心区别在于：OpenClaw 将"响应式聊天机器人"升级为"主动行动的智能体"，在用户自控的硬件上运行持久化助手，配备完善的会话管理、记忆系统、工具沙箱和消息路由机制。
高层架构概览
OpenClaw 采用以 Gateway（网关） 控制平面为核心的轮辐式架构，Gateway 负责：
- 作为 WebSocket 服务器，连接各消息平台和控制界面
- 将消息路由至 Agent Runtime（智能体运行时）
- 管理系统状态，包括会话、在线状态指示器和定时任务
- 通过身份认证和设备配对强制执行安全策略
Agent Runtime 负责：
- 基于 Pi Agent Core 库执行端到端 AI 交互
- 会话解析与上下文组装
- 带流式响应的模型调用
- 工具执行（可选沙箱化）
- 状态持久化
通过插件扩展
OpenClaw 通过四种插件类型实现扩展：
- Channel 插件 — 支持接入更多消息平台
- Memory 插件 — 替换存储后端
- Tool 插件 — 在内置功能之外添加自定义能力
- Provider 插件 — 接入自定义 LLM 提供商或自托管模型
插件系统通过 extensions/ 目录进行发现式加载，并基于 TypeBox Schema 进行校验。
核心组件
1. Channel 适配器
每个消息平台都有一个专用适配器，实现包含四项职责的通用接口：
身份认证：各平台方式不同（WhatsApp 通过 Baileys 扫码、Telegram/Discord 使用 Bot Token、iMessage 通过 macOS 原生集成）
入站消息解析：提取文本、处理媒体附件、响应表情互动，并维护线程上下文
访问控制：白名单指定允许交互的手机号或用户名；DM 策略控制陌生发件人处理方式（默认需要配对审批）；群组策略包括@提及要求
出站消息格式化：处理各平台特定的 Markdown 方言、消息字数限制、媒体上传和正在输入提示
2. 控制界面
Web UI — 基于 Lit Web Components，由 Gateway 在 http://127.0.0.1:18789/ 提供服务，支持聊天、配置、会话检查和健康监控
CLI — 基于 Commander.js 的命令行工具（openclaw.mjs），提供 Gateway 生命周期管理、Channel 配对和诊断功能
macOS App — 基于 Swift 的菜单栏应用，支持 Gateway 生命周期控制、语音唤醒以及 WebChat 嵌入
Mobile Nodes — iOS 和 Android 应用，作为 WebSocket 节点连接，暴露设备能力（摄像头、位置、录屏）
3. Gateway 控制平面
位于 src/gateway/server.ts，运行在 Node.js 22+ 上，默认绑定至 127.0.0.1:18789（仅回环地址，保障安全）。
设计原则：
- 每台主机唯一一个 Gateway（防止 WhatsApp 会话冲突）
- 完全类型化协议，带 JSON Schema 校验
- 事件驱动而非轮询
- 所有有副作用的操作都需要幂等键
- 本地连接自动批准；远程连接需要挑战-响应签名
4. Agent Runtime
实现于 src/agents/piembeddedrunner.ts，使用 Pi Agent Core 库，采用 RPC 风格调用和流式响应。
会话解析：私信映射至 main 会话；通过 Channel 的 DM 映射至 agent:main:<channel>:dm:<id>；群聊映射至 agent:main:<channel>:group:<id>
上下文组装：从 JSON 文件加载会话历史，根据工作区配置构建动态系统提示，通过语义搜索拉取相关记忆
执行循环：监听模型响应中的工具调用，拦截并执行工具（可在 Docker 沙箱中运行），将结果流回模型，持久化全部对话状态
系统提示架构：从多个来源合成：
- AGENTS.md — 核心 Agent 指令（内置默认）
- SOUL.md — 个性与语气指引（可选）
- TOOLS.md — 用户自定义工具约定（可选）
- 动态上下文（会话历史、技能、记忆搜索）
- 工具定义（自动从内置工具和插件生成）
交互与协调
Canvas 与 Agent-to-UI（A2UI）
Canvas 作为独立服务进程运行（默认端口 18793），提供隔离性。Agent 调用 Canvas 更新方法；Canvas 服务器解析嵌入在 HTML 中的 A2UI 属性；服务器通过 WebSocket 将内容推送至浏览器客户端。
A2UI 允许 Agent 生成带有特殊属性的声明式 HTML，无需 Agent 端编写 JavaScript 即可创建交互元素。用户点击会触发动作事件，以工具调用的形式转发给 Agent。
Canvas 支持跨平台：macOS（WebKit 视图）、iOS（SwiftUI）、Android（WebView）和 Web UI（浏览器标签页）。
语音唤醒与对话模式
macOS、iOS 和 Android 均支持始终在线的唤醒词检测（"Hey OpenClaw"）或按键通话快捷键。音频流送至 ElevenLabs 进行语音转写，Agent 处理请求后，通过 ElevenLabs TTS 播放回复。对话模式支持持续交谈并可检测打断。
多 Agent 路由
将不同的 Channel 或群组路由至各自独立的 Agent 实例，每个实例拥有独立的工作区、模型和行为配置。支持：
- 为不同社群设置独立的 AI 人格
- 差异化工具权限
- 为不受信任用户提供隔离沙箱
- 安全测试新行为
会话工具（Agent 间通信）
通过以下工具实现 Agent 间协作：
- sessions_list — 发现活跃会话
- sessions_send — 向其他会话发送消息
- sessions_history — 获取其他会话的对话记录
- sessions_spawn — 以编程方式创建新会话
定时任务与外部触发
Cron 任务可在指定时间调度 Agent 动作；Webhook 提供外部触发点，实现自动化和外部系统集成。
端到端消息流
阶段一：接收
Baileys 库接收 WhatsApp WebSocket 事件；WhatsApp 适配器解析事件，提取消息文本、媒体附件和发件人元数据。
阶段二：访问控制与路由
消息进入访问控制层（发件人白名单检查、首次 DM 的配对审批）。自动回复系统解析目标会话：私信为 main，Channel DM 为 agent:main:whatsapp:dm:<id>，群聊为 agent:main:whatsapp:group:<id>。
阶段三：上下文组装
Agent Runtime 从磁盘加载会话，读取工作区文件并注入相关技能来组装系统提示，通过记忆搜索查询语义相关的历史对话。
阶段四：模型调用
将富上下文打包后流式传输至配置的模型提供商。
阶段五：工具执行
运行时监听工具调用，拦截并执行（可在 Docker 沙箱中），将结果流回模型以整合到回复中。
阶段六：响应交付
响应分块回流至 Gateway；WhatsApp 适配器格式化每个分块，转换 Markdown 并遵守消息长度限制；消息通过 Baileys 发送至 WhatsApp 服务器；运行时持久化完整对话状态。
延迟预算：访问控制 <10ms；会话加载 <50ms；提示组装 <100ms；首 Token 200–500ms；工具执行因工具而异（bash ~100ms；浏览器自动化 1–3 秒）。
数据存储与状态管理
配置
主配置文件位于 ~/.openclaw/openclaw.json，使用 JSON5 格式（支持注释和尾随逗号）。采用分层覆盖机制：环境变量 > 配置文件值 > 内置默认值。
会话状态与压缩
会话以追加模式事件日志的形式存储在 ~/.openclaw/sessions/ 下，支持分支。自动压缩对旧对话进行摘要，以保持在模型上下文限制内；可选的"记忆刷新"将持久信息提升至记忆文件。
会话标识符编码了所有权与信任级别：agent:<agentId>:main 拥有完整权限；DM/群组会话使用 agent:<agentId>:<channel>:dm|group:<identifier> 并默认沙箱化。
记忆搜索
将可检索的对话记忆存储在 ~/.openclaw/memory/<agentId>.sqlite，使用带向量嵌入的 SQLite。混合检索结合了向量相似度（语义匹配）和 BM25 关键词相关性。
工作区记忆文件：
- MEMORY.md — 长期事实（仅在私有/主要会话中加载）
- memory/YYYY-MM-DD.md — 每日笔记
嵌入提供商选择顺序：本地模型 → OpenAI → Gemini → 如均不可用则禁用
索引管理：文件监听器监控记忆文件，带 1.5 秒防抖；检测到嵌入提供商变化时重新索引；支持实验性会话转录索引
凭证
敏感身份认证数据存储在 ~/.openclaw/credentials/，文件权限为 0600（仅所有者可读写），从版本控制中排除。
安全架构
1. 网络安全
Gateway 仅绑定至 127.0.0.1（回环地址）。远程访问需要：
- SSH 隧道（推荐用于 VPS）
- Tailscale Serve（仅限 Tailnet 的 HTTPS）
- Tailscale Funnel（暴露至公网）
2. 身份认证与设备配对
Token/密码认证：通过环境变量 OPENCLAW_GATEWAY_TOKEN 或配置 gateway.auth.mode: "password" 保护非回环绑定
设备配对：增加额外安全层——所有 WebSocket 客户端在握手时包含设备标识。本地连接自动批准；远程连接需签署挑战 nonce 并经过明确审批。已批准设备收到 Token 用于后续连接。
3. Channel 访问控制
DM 配对 — 陌生发件人触发配对流程，需通过唯一码审批。白名单明确指定交互权限。群组策略控制@提及要求和群组专属白名单。
4. 工具沙箱
基于 Docker 的沙箱机制按会话隔离工具执行。主会话在宿主机原生运行，拥有完整访问权限；DM/群组会话默认在临时容器中执行工具，拥有隔离文件系统、可选网络访问和可配置资源限制。
基于会话的安全边界：
- 主会话 — 完整宿主机访问
- DM 会话 — 默认沙箱化
- 群组会话 — 默认沙箱化
影响安全配置的因素：沙箱化内容（工具，非 Gateway）；容器粒度（按会话最强，共享最高效）；宿主机暴露程度（bind mount 增加能力与风险）；网络访问；逃逸路径
工具策略优先级：工具配置 → 提供商配置 → 全局策略 → 提供商策略 → Agent 策略 → 群组策略 → 沙箱策略
5. 提示注入防御
上下文隔离将用户输入与系统指令和工具结果分离。用户消息携带来源元数据。模型选择至关重要：文档推荐使用最新一代模型（Claude Opus 4.5）运行工具型机器人；较小模型需要通过只读工具、最小文件系统暴露、严格沙箱和严格白名单来补偿性地降低爆炸半径。
通过以下方式强制执行：Channel 访问控制（DM 通过配对锁定）、群组中的@提及门控、将链接/附件视为恶意输入、在沙箱中运行敏感操作、将机密信息从可访问的文件系统中移除。
部署架构
本地开发（macOS/Linux）
所有服务运行在开发者本机。Gateway 通过 pnpm dev（热重载）启动，绑定至 127.0.0.1:18789，仅本地可访问。回环地址无需认证；完整调试日志。
生产 macOS（菜单栏应用）
LaunchAgent 将 Gateway 作为后台服务运行，登录时自动启动。菜单栏应用提供原生生命周期管理，包含 WebChat UI 嵌入、语音唤醒、本地回环访问以及可选的 SSH/Tailscale 远程访问。支持 iMessage（需要真实 Mac 设备）。
Linux/VM（远程 Gateway）
Gateway 作为 systemd 服务在远程主机上运行，绑定至回环地址以保障安全。
方案 A：SSH 隧道（推荐）
将本地 127.0.0.1:18789 通过加密 SSH 隧道映射至远程 127.0.0.1:18789。
方案 B：Tailscale Serve
VPS 和客户端设备均加入 Tailscale 网络。VPS 使用 Serve 提供 HTTPS 访问（https://vps.tailnet.ts），无需管理 SSH 密钥/隧道。
Fly.io（容器化部署）
Gateway 在 Fly.io 管理的 Docker 容器中运行。持久化卷存储状态（部署后仍然保留）。托管 HTTPS 端点提供 TLS 终止。可通过互联网访问，需要强认证。
总结
OpenClaw 展示了一种现代个人 AI 基础设施理念：本地优先、自托管、完全可控。轮辐式 Gateway 设计实现了跨消息平台的统一访问；严格的安全边界防御不受信任的输入；带工具执行和持久会话的 Agent 原生运行时提供智能助手体验。
无论是在笔记本电脑上供个人使用，还是在 VPS 上实现 7×24 小时可用，用户始终掌控基础设施位置、暴露方式和数据存取。在专有 AI API 和围墙花园盛行的时代，OpenClaw 提供了一种替代方案：按用户意愿运行的助手，通过首选 Channel 访问，完全透明可查。
暂无评论，来发表第一条吧！