一文拆解 OpenClaw 全链路/技术栈 实现方式
OpenClaw是一个本地AI助手运行时,以Gateway网关为核心,通过WebSocket统一连接聊天平台与本地设备节点。系统基于Node.js/TypeScript,支持多AI模型,使AI能够安全操作电脑和服务。其智能体运行时处理用户请求,调用模型进行推理和工具执行(如运行命令、访问文件),并在严格的安全策略和沙箱环境下完成自动化任务,实现人机交互的智能控制。
下面的内容基于目前公开的 README 与官方文档(Gateway、Agent、Models、Session、Skills 等),以及若干架构解析文章整理而成。
目录
5.2 与 AI 的交互流程(Prompt/Tool/Memory 级别)
-
概要
OpenClaw 这个开源项目如何实现的?
-
采用 Gateway 为中心的分层架构:Gateway 负责一切 I/O 与会话,Agent Runtime 专注推理,Nodes 提供设备能力,Skills 提供扩展工具,Docker 提供沙箱隔离。
-
各部分之间通过统一的 WebSocket + JSON 协议交互,由 TypeBox 定义严格 schema。
底层交互原理是什么?
-
一条长期 WebSocket 连接承载所有控制流:
-
首先 connect 握手 + 鉴权 + 设备配对。
-
后续通过
req/res/event三种消息类型与 Gateway 通讯。
-
-
Gateway 把来自各渠道的消息映射到 session,再通过 Agent Runtime 调用模型与工具,最后再经原渠道返回。
是在什么样的技术栈上,增加了与 AI 模型的交互?
-
核心技术是 Node.js 22+ + TypeScript;
-
通过统一的“模型抽象层(models config + providers)”对接:
-
云端模型(Anthropic/OpenAI/OpenRouter 等)。
-
本地模型(通过 Ollama 等运行时)。
-
-
使用 CLI + Chat slash 命令提供模型选择/切换/扫描等功能。
与 AI 交互的实现是什么?
-
在 Agent 端构造复杂的 prompt(含 workspace 引导文件、技能列表、会话历史、安全提示),调用模型;
-
模型可输出工具调用指令,Gateway 执行工具、收集结果,再回馈给模型进行最终回答;
-
会话系统负责上下文裁剪、记忆写入与 session 生命周期管理。
补充拆解视角
-
安全:DM 配对机制、Docker 沙箱、exec 审批、节点权限控制。
-
扩展:Skills/ClawHub 插件机制、模型 provider 抽象。
-
多用户与团队场景:dmScope/sessionKey 设计、per-peer/多账号隔离。
-
部署模式:本地单机 vs 远程 Gateway + 多节点。
-
工程可维护性:协议 schema、自动代码生成、版本协商、idempotency 缓存。
-
先用“大图”回答:OpenClaw 本质上在做什么?
用一句话概括:
OpenClaw 是一个“以 Gateway 为中心”的本地 AI 助手运行时,把:
-
多个聊天/消息渠道(WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等)
-
一个统一的“智能体运行时(Pi Agent Runtime)”
-
一套可以执行脚本、访问本机、浏览器、Canvas UI 等的“工具/技能系统”
通过 WebSocket + 统一协议 串在一起,让任意大模型(Claude、OpenAI、Ollama 本地模型等)可以在一个安全可控的环境里,真正“操纵你的电脑”和各种服务。
你可以把它想成:
「一个常驻的本地控制平面(Gateway) + 一个可插拔的大模型大脑(Model) + 一组可扩展的工具与技能(Tools/Skills) + 会话/记忆/安全策略。」
-
整体架构:OpenClaw 是怎样实现的?
2.1 顶层架构分层
官方 README 和架构文档给出了一张简化示意图(文字化)[1][2]:
┌────────────────────────────────────┐
│ 消息平台客户端 │
│ │
WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / │
│ │
│ │
▼ │
┌───────────────────────────────────────────────────────────────┐
│ Gateway (网关) │
│ 控制平面 / 守护进程 │
│ ws://127.0.0.1:18789 │
└───────────────────────┬───────────────────────────────────────┘
│ WebSocket 协议
├──────────────────────┐
│ │
▼ ▼
┌──────────────┐ ┌─────────────────┐
│ Pi agent │ │ CLI (openclaw) │
│ (RPC 模式) │ │ │
└──────────────┘ └─────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌─────────────────┐
│ WebChat UI │ │ macOS app │
│ / 控制台 │ │ │
└──────────────┘ └─────────────────┘
│ │
└──────────┬───────────┘
│
▼
┌─────────────────────────┐
│ 移动端与桌面节点 │
│ iOS / Android / macOS │
└─────────────────────────┘
核心结构可以拆成 4 大块:
-
Gateway(网关守护进程)
-
单机唯一实例(One Gateway per host)。
-
负责:
-
与各聊天渠道(WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等)建立和维护连接。
-
管理所有“会话(Session)”与“智能体(Agents)”的路由。
-
承载 WebSocket 协议:所有客户端(CLI/Web UI/macOS App/Nodes)都通过 WS 与 Gateway 通信。
-
承载工具/技能系统调用、权限、审批、安全策略。
-
-
-
Pi Agent Runtime(“大脑”运行时)
-
内嵌的智能体执行引擎,来源于
pi-mono项目,但会话管理/工具接线是 OpenClaw 自己实现的[3]。 -
职责:
-
接受 Gateway 传来的“用户消息 + 会话上下文 + 可用工具列表”。
-
调用底层大模型进行推理,决定:
-
直接自然语言回复?
-
调用哪些工具(执行命令/访问浏览器/调用 Node 能力)?
-
-
组织工具调用链路(tool calling)与结果总结。
-
负责把多轮对话压缩、做记忆写入等。
-
-
-
Nodes(设备节点)
-
运行在 macOS / iOS / Android 或 headless 环境的“能力节点”。
-
通过 WebSocket 以
role: "node"连接 Gateway,并声明自己支持的能力 / 命令,如:-
system.run、system.notify -
canvas.*(可视化 Canvas UI) -
camera.*、screen.record -
location.get、VoiceWake/Talk 模式 等
-
-
Gateway 通过
node.invoke把某些工具调用转发给节点执行(比如在 macOS 上执行命令、弹通知、录屏)。
-
-
Skills(技能系统)与 Sandbox(沙箱执行环境)
-
Skills 是对“工具”的抽象封装,一般以目录+
SKILL.md的形式存在:-
描述能力、参数(YAML frontmatter + 元数据)。
-
实现文件(JS/TS / 其它可执行体)。
-
-
可以来源于:
-
打包自带(bundled skills)
-
本地 skills 目录(
~/.openclaw/skills) -
每个 agent 的 workspace 下
/skills -
ClawHub(在线技能仓库)
-
-
对于“非主会话”(如群聊等),执行会放在 Docker 沙箱 中,隔离与限制权限[1]。
-
-
底层交互原理:Gateway 协议是怎么设计/运作的?
3.1 一切通过 WebSocket + JSON 消息
传输层:纯 WebSocket 文本帧,负载是 JSON 文本[2]。
三类消息:
// 请求
{ "type": "req", "id": "uuid", "method": "connect" | "agent" | "send" | ..., "params": {...} }
// 响应
{ "type": "res", "id": "uuid", "ok": true/false, "payload": {...} | "error": {...} }
// 事件(服务器推送)
{ "type": "event", "event": "agent" | "presence" | "tick" | "chat" | ..., "payload": {...} }
-
首帧校验:首个有效帧必须是
connect请求,否则直接 hard close。 -
所有请求使用
id做匹配,一问一答;事件则是单向 server-push。
3.2 连接与鉴权(Handshake & Auth)
典型连接过程[2]:
-
Gateway 主动发出
connect.challenge事件:-
内容包含
nonce与时间戳,防重放防伪造。
-
-
客户端发送
req: connect,其中包含:-
minProtocol/maxProtocol:协商协议版本。 -
client:客户端信息(id、version、platform、mode)。 -
role:operator或node。 -
scopes:权限范围(如operator.read/operator.write/operator.approvals等)。 -
caps/commands/permissions:对 node 声明支持的功能。 -
auth.token:如果环境设了OPENCLAW_GATEWAY_TOKEN或启动参数--token,必须匹配。 -
device:设备身份(id、publicKey、signature、nonce、signedAt)。
-
-
Gateway 响应
res: hello-ok:-
协议版本、策略(如
tickIntervalMs)。 -
如果是首次 pairing,可能颁发
deviceToken,后续连接可复用该 token。
-
-
后续所有操作(发送消息、发起 agent 运行、查询状态)都复用这条 WebSocket 连接。
角色与权限:
-
role: "operator":CLI、控制台、Web UI 等控制平面客户端。 -
role: "node":设备节点,专注提供能力(system.run、camera、canvas 等)。 -
所有权限由
scopes与 node 的commands/permissions声明组合;Gateway 在服务端强制执行。
3.3 Agent 调用流程
一个典型“用户→AI→工具→结果”的完整链路:
-
用户消息到达
-
来自某个渠道(比如 Telegram 机器人、WhatsApp、Slack)。
-
接口库如 Baileys、grammY、Slack Bolt/Discord.js 等在 Gateway 里常驻。
-
-
Gateway 将消息映射到 Session
-
根据会话规则(dmScope、group key 等)确定 sessionKey 与 sessionId[4]。
-
加载该会话对应的历史 JSONL(只加载需要进入上下文的部分)。
-
-
Gateway 向 Agent Runtime 发送“执行请求”
-
包含:
-
当前消息文本/媒体信息
-
会话压缩后的上下文
-
当下可用的技能/工具列表(以紧凑 XML 列表注入 system prompt[5])
-
模型配置(primary + fallbacks)
-
-
-
Agent Runtime 与模型交互
-
由 Agent 决定在本轮对话中:
-
直接回答?
-
先调用 1~N 个工具?
-
-
若调用工具:
-
Gateway 收到工具调用请求(结构化 JSON),检查权限、幂等键(idempotencyKey)。
-
对于 host 工具(如本机 exec)或 sandbox 工具(Docker 容器内 exec),执行后把结果包装成“工具结果”再送回 Agent。
-
Agent 重新调用模型,把工具结果串联成最终自然语言回答。
-
-
-
Gateway 把回答通过原始渠道发回给用户
-
同时更新会话 JSONL transcript 与 session store(tokens、时间戳、origin 信息等)。
-
-
技术栈:在什么样的技术栈上,增加了与 AI 模型的交互?
4.1 核心运行时技术栈
-
语言与运行环境
-
Node.js ≥ 22(官方推荐)[1]
-
TypeScript(协议、Gateway、CLI、控制台大多基于 TS)
-
对 macOS/iOS/Android node:Swift/Kotlin/Objective‑C/Java 混合,具体实现依照各平台。
-
-
网络与协议
-
WebSocket (
ws) + JSON 文本 -
TypeBox 定义 Gateway 协议 Schema,自动生成:
-
JSON Schema(校验)
-
Swift models(给 iOS/macOS 客户端)
-
-
-
消息渠道库
-
WhatsApp:Baileys[1]
-
Telegram:grammY[1]
-
Slack:Bolt(官方 SDK)[1]
-
Discord:discord.js[1]
-
Signal:signal-cli
-
iMessage:BlueBubbles(推荐)或传统
imsg方式 -
Microsoft Teams、Matrix、Zalo 等通过扩展适配器。
-
-
UI 与桌面端
-
WebChat / 控制台:前端 SPA(React/Vue 一类),通过 Gateway WebSocket 访问。
-
macOS app:菜单栏应用,负责 Voice Wake/Talk、Canvas,以及远程 Gateway 控制等。
-
-
沙箱与部署
-
Docker(per-session sandbox 模式)。
-
Nix 支持、Docker 部署文件、WSL2 on Windows[1]。
-
Tailscale / SSH 隧道用于远程访问 Gateway。
-
4.2 AI 模型抽象层
文档中对模型交互抽象出了一个统一层[3]:
-
配置入口大致为:
{
agent: {
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.2", "ollama/llama3-70b"]
},
models: {
"anthropic/claude-opus-4-6": { alias: "Opus" },
"openai/gpt-5.2": { alias: "GPT-5.2" }
}
}
}
-
支持:
-
Anthropic(Claude Pro/Max 等)——官方推荐主力。
-
OpenAI(ChatGPT/GPT‑x)。
-
OpenRouter 等中转服务。
-
本地模型(通过 Ollama、Zen 等网关)。
-
-
CLI 支持丰富的模型管理命令:
-
openclaw models list/status/set/... -
openclaw models scan搜索 OpenRouter 免费模型并按工具支持、上下文长度、参数规模等排序。
-
关键点:
AI 提供商层通过统一抽象 + 配置驱动,Gateway/Agent 基本不感知具体厂商细节(只感知“某个具有工具/多模态能力的模型”)。
-
“与 AI 交互”的具体实现机制
你问题里的两点:
是在什么样的技术栈上,增加了与 AI 模型的交互?
与 AI 交互的实现是什么?
可以拆解为两个层面:
5.1 技术栈上如何接入 AI 模型?
-
Node.js + HTTP 客户端
-
在 Gateway/Agent Runtime 内部,通过 HTTP(S) 调用各大模型提供商的 REST/Streaming API。
-
支持流式响应(Server‑Sent Events 或 chunked stream)时,会将 chunk 逐步转发到 WebSocket 事件流中。
-
-
统一模型注册表(models.json + 配置)[3]
-
自定义 provider 写入
models.providers,实际序列化为~/.openclaw/agents/<agentId>/models.json。 -
支持设置:
-
基础 URL(baseUrl)
-
验证方式(OAuth / API key)
-
支持工具 / 不支持工具
-
是否支持图像等多模态。
-
-
-
CLI 与 Chat 命令的模型切换
-
通过
/model命令(或 CLIopenclaw models set)在会话中热切换模型,不需要重启 Gateway。
-
总结:
在 Node.js/TS 的 Gateway + Agent Runtime 中,定义了一个“模型抽象接口 + providers 配置”,所有具体的 HTTP 调用都托管在这一层,外层只关心“调用谁、支持工具否、最大 token 等元信息”。
5.2 与 AI 的交互流程(Prompt/Tool/Memory 级别)
1)提示构造(Prompt Building)
在每一次模型调用前,OpenClaw 会构造一个复杂的上下文输入,包括:
-
多段 system prompt:
-
AGENTS.md / SOUL.md / TOOLS.md / IDENTITY.md / USER.md 等 workspace 文件内容[3]。
-
动态注入的技能列表(XML 格式,紧凑编码,考虑 token 成本[5])。
-
当前安全策略提示(例如沙箱、审批、敏感操作告警)。
-
-
会话历史:
-
从 JSONL 中抽取近期对话 +必要的工具调用结果(经 session pruning 后)[4]。
-
-
当前消息:
-
用户最新输入、媒体/附件描述等。
-
2)工具调用(Tool Calling)
依据 Agent 文档[3]、Skills 文档[5]:
-
内置工具:
-
read/write/edit/exec/process/...等对文件系统 & 命令行操作。 -
浏览器控制(Chrome/Chromium CDP)。
-
cron / webhook / Gmail PubSub 等自动化。
-
Discord/Slack/Nodes/Canvas 等各种外部动作。
-
-
调用机制:
-
模型输出结构化的“工具调用计划”(取决于模型是否具备 function/tool calling 能力)。
-
Gateway 接到这些计划,按工具策略执行:
-
是否在沙箱内执行?
-
当前会话是否允许此工具?
-
是否需要人工审批(exec approvals)?
-
-
工具输出会回流给 Agent,作为下一次模型调用的输入(让模型“看到”自己的执行结果)。
-
3)队列与流式思考(Agent Loop & Streaming)
-
Queue 模式:
-
steer:当用户再次发消息时,中断当前工具链,跳到新问题(适合高交互场景)。 -
followup/collect:等当前一个回合结束后再处理排队消息。
-
-
Block Streaming:
-
可以选择:
-
按“文本结束”或“消息结束”来切分块。
-
控制 block size(默认 800–1200 字符),避免聊天软件被刷屏。
-
-
控制 UI / WebChat 会实时显示这些块以及工具调用进度。
-
-
会话/记忆系统:不仅仅是“聊天记录”
6.1 Session 与 Key 映射
Session 文档给出了非常细的规则[4]:
-
直接对话(DM):
-
默认
dmScope: "main":所有私聊共享一个“主会话”,适合纯个人使用。 -
多用户情况下推荐改成:
-
per-peer/per-channel-peer/per-account-channel-peer来保证各用户隔离。
-
-
-
群组/频道:
-
不同渠道的群组会映射到形如:
agent::<provider>:group:<groupId>的 key。 -
Telegram topic 等有
:topic:扩展。
-
-
其它触发源:
-
cron、webhook、node 调用,各自有独立的 session key 前缀。
-
6.2 存储 & 剪枝 & 记忆
-
存储位置:
-
~/.openclaw/agents/<agentId>/sessions/sessions.json→ 存储 session 元数据。 -
~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl→ 详细对话/工具调用记录。
-
-
内存管理:
-
session pruning:在真正调用模型前,对 context 中“历史工具结果”等进行剪枝,减少 token。 -
“memory flush”:在要自动压缩前,可以先引导模型把重要信息写成“持久笔记”(写入 workspace 文件),仅在 workspace 可写时执行。
-
-
生命周期与重置策略:
-
按时间(idleMinutes)、按每天固定时间(reset at 4:00)、按通道类型/渠道自定义。
-
/new或/reset命令可以手动重置会话。
-
结论:
OpenClaw 的记忆系统是“显式会话 + 隐式长期记忆”模式:
-
短期记忆通过 session context + JSONL 存储
-
长期记忆通过 workspace 文件(如 USER.md/AGENTS.md/自定义 notes)逐渐沉淀。
-
安全模型与沙箱执行:这是评估这类项目时必须拆解的点
你没有直接问安全问题,但这是理解 OpenClaw 时最值得额外拆解的视角。
7.1 默认安全策略
根据 README 与 Security 部分[1]:
-
DM 默认策略:
dmPolicy="pairing"-
陌生用户发私聊时,不直接触发 AI,只发送配对码。
-
需要在本地 CLI 执行
openclaw pairing approve <code>才会允许对方对话。
-
-
群组/公共渠道默认 不开启 任意用户直接调用高危工具,需要显式配置 allowFrom/群组 allowlist。
-
工具默认策略对非主会话(如群组)采用 Docker 沙箱模式,仅允许:
-
bash、process、read/write/edit等有限工具。 -
禁止
browser、canvas、nodes等高权限工具。
-
7.2 执行权限 & 审批机制
-
system.run等危险命令:-
可配置“需要审批”:当 AI 想执行时,Gateway 会广播
exec.approval.requested,有权限的 operator 再通过exec.approval.resolve决定是否放行。
-
-
节点权限:
-
permissions字段中精确标记每种能力(如screen.record)是否允许。 -
macOS 上还叠加 TCC 权限(屏幕录制、摄像头、麦克风等)。
-
实践建议:
-
真正把它放在个人工作环境时,应至少:
-
主会话不开沙箱,但极度慎重审查工具配置。
-
群组/公共场景全部启用 Docker 沙箱。
-
高危工具(浏览器自动化、系统脚本)加上人工审批。
-
-
可扩展性与工程性拆解:多几个“专业视角”
为了超出你原始问题,我再给几个常见工程/架构视角的拆解点:
8.1 “网关中心”架构的优劣
优点:
-
单一控制平面,方便:
-
统一安全策略
-
集中日志与监控
-
集中模型/工具配置
-
-
所有客户端/节点都只需要会 WebSocket + JSON 协议即可接入。
潜在问题:
-
Gateway 是单点:
-
一挂所有渠道都挂。
-
高可用要额外做进程监管、重启策略、甚至集群化。
-
8.2 “技能”与“插件市场”的生态策略
-
Skills 的形式(SKILL.md + 实现文件)使得:
-
开发者可以很快编写“熟悉的脚本”,通过简单 frontmatter 就变成“可被大模型使用的工具”。
-
ClawHub 作为技能仓库,可以形成生态(类似 VSCode 插件、Homebrew formula)。
-
工程上可以关注的点:
-
是否可写出“企业内部的技能仓库”(自建 ClawHub 或镜像)?
-
如何管理技能版本与回滚?
-
如何对第三方技能做安全审计 / 代码审查?
8.3 部署模式与团队使用模式
从文档看,几种典型部署方式:
-
纯本地单用户:
-
Gateway + Agent + 节点全部在一台个人电脑上。
-
主会话直连 host 工具,无 Docker 沙箱。
-
-
远程 Gateway,多设备节点:
-
在一台 Linux 服务器上跑 Gateway。
-
macOS/iOS/Android 作为节点连接执行各自本地操作。
-
通过 Tailscale/SSH 暴露 Web 控制台与 WebSocket 给各用户。
-
-
团队场景:
-
同一 Gateway 服务多个用户(小团队)。
-
每个用户通过 DM pairing 拿到自己的 session。
-
强烈需要启用 per-peer / per-channel-peer dmScope 与群组沙箱。
-
-
如果你打算“读源码/做二次开发”,建议的拆解路径
-
第一步:弄清协议和会话
-
从
docs/concepts/architecture.md和docs/gateway/protocol.md入手,理解:-
WebSocket 消息格式
-
connect / agent / send 等方法
-
会话是怎样从“某个频道 + 某个人/群组”映射成 sessionKey 的[2][4]
-
-
-
第二步:看 Agent 与 Workspace
-
读
docs/concepts/agent.md:-
Agent runtime 与模型是如何通过 RPC 对接?
-
Workspace 下 AGENTS/SOUL/TOOLS/USER 等文件如何注入到 prompt?
-
-
再看
docs/concepts/models.md:-
模型提供商是怎么抽象的?
-
如何扩展新 provider?
-
-
-
第三步:拆 Skills 与 Sandbox
-
读
docs/tools/skills.md与docs/tools/creating-skills.md:-
自己写一两个简单的技能(比如调用内部 HTTP 服务)。
-
观察在沙箱/非沙箱时行为有何不同。
-
-
-
第四步:安全与多用户场景
-
读
docs/gateway/security.md与 Session 文档:-
配 DM 策略、群组策略。
-
在 Docker 沙箱模式下挂载有限目录,观察安全边界。
-
-
-
第五步:根据自己需求扩展
-
需要新渠道:参考现有的 channels 文档与代码,按类似模式接入。
-
需要企业集成:写 Skills 调用内部 API;必要时在 models/providers 部署企业 LLM 网关。
-
References
[1] README. https://raw.githubusercontent.com/openclaw/openclaw/main/README.md [2] ARCHITECTURE. https://raw.githubusercontent.com/openclaw/openclaw/main/docs/concepts/architecture.md [3] AGENT RUNTIME. https://raw.githubusercontent.com/openclaw/openclaw/main/docs/concepts/agent.md [4] SESSION / MEMORY. https://raw.githubusercontent.com/openclaw/openclaw/main/docs/concepts/session.md [5] SKILLS SYSTEM. https://raw.githubusercontent.com/openclaw/openclaw/main/docs/tools/skills.md [6] MODELS / PROVIDERS. https://raw.githubusercontent.com/openclaw/openclaw/main/docs/concepts/models.md
更多推荐
所有评论(0)