下面的内容基于目前公开的 README 与官方文档(Gateway、Agent、Models、Session、Skills 等),以及若干架构解析文章整理而成。

目录

概要

先用“大图”回答:OpenClaw 本质上在做什么?

整体架构:OpenClaw 是怎样实现的?

2.1 顶层架构分层

底层交互原理:Gateway 协议是怎么设计/运作的?

3.1 一切通过 WebSocket + JSON 消息

3.2 连接与鉴权(Handshake & Auth)

3.3 Agent 调用流程

技术栈:在什么样的技术栈上,增加了与 AI 模型的交互?

4.1 核心运行时技术栈

4.2 AI 模型抽象层

“与 AI 交互”的具体实现机制

5.1 技术栈上如何接入 AI 模型?

5.2 与 AI 的交互流程(Prompt/Tool/Memory 级别)

会话/记忆系统:不仅仅是“聊天记录”

6.1 Session 与 Key 映射

6.2 存储 & 剪枝 & 记忆

安全模型与沙箱执行:这是评估这类项目时必须拆解的点

7.1 默认安全策略

7.2 执行权限 & 审批机制

可扩展性与工程性拆解:多几个“专业视角”

8.1 “网关中心”架构的优劣

8.2 “技能”与“插件市场”的生态策略

8.3 部署模式与团队使用模式

如果你打算“读源码/做二次开发”,建议的拆解路径

概要



  1. 概要

  1. OpenClaw 这个开源项目如何实现的?

  • 采用 Gateway 为中心的分层架构:Gateway 负责一切 I/O 与会话,Agent Runtime 专注推理,Nodes 提供设备能力,Skills 提供扩展工具,Docker 提供沙箱隔离。

  • 各部分之间通过统一的 WebSocket + JSON 协议交互,由 TypeBox 定义严格 schema。

  1. 底层交互原理是什么?

  • 一条长期 WebSocket 连接承载所有控制流:

    • 首先 connect 握手 + 鉴权 + 设备配对。

    • 后续通过 req/res/event 三种消息类型与 Gateway 通讯。

  • Gateway 把来自各渠道的消息映射到 session,再通过 Agent Runtime 调用模型与工具,最后再经原渠道返回。

  1. 是在什么样的技术栈上,增加了与 AI 模型的交互?

  • 核心技术是 Node.js 22+ + TypeScript;

  • 通过统一的“模型抽象层(models config + providers)”对接:

    • 云端模型(Anthropic/OpenAI/OpenRouter 等)。

    • 本地模型(通过 Ollama 等运行时)。

  • 使用 CLI + Chat slash 命令提供模型选择/切换/扫描等功能。

  1. 与 AI 交互的实现是什么?

  • 在 Agent 端构造复杂的 prompt(含 workspace 引导文件、技能列表、会话历史、安全提示),调用模型;

  • 模型可输出工具调用指令,Gateway 执行工具、收集结果,再回馈给模型进行最终回答;

  • 会话系统负责上下文裁剪、记忆写入与 session 生命周期管理。

  1. 补充拆解视角

  • 安全:DM 配对机制、Docker 沙箱、exec 审批、节点权限控制。

  • 扩展:Skills/ClawHub 插件机制、模型 provider 抽象。

  • 多用户与团队场景:dmScope/sessionKey 设计、per-peer/多账号隔离。

  • 部署模式:本地单机 vs 远程 Gateway + 多节点。

  • 工程可维护性:协议 schema、自动代码生成、版本协商、idempotency 缓存。

  1. 先用“大图”回答:OpenClaw 本质上在做什么?

用一句话概括:

OpenClaw 是一个“以 Gateway 为中心”的本地 AI 助手运行时,把:

  • 多个聊天/消息渠道(WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等)

  • 一个统一的“智能体运行时(Pi Agent Runtime)”

  • 一套可以执行脚本、访问本机、浏览器、Canvas UI 等的“工具/技能系统”

通过 WebSocket + 统一协议 串在一起,让任意大模型(Claude、OpenAI、Ollama 本地模型等)可以在一个安全可控的环境里,真正“操纵你的电脑”和各种服务。

你可以把它想成:

「一个常驻的本地控制平面(Gateway) + 一个可插拔的大模型大脑(Model) + 一组可扩展的工具与技能(Tools/Skills) + 会话/记忆/安全策略。」


  1. 整体架构: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 大块:

  1. Gateway(网关守护进程)

    1. 单机唯一实例(One Gateway per host)。

    2. 负责:

      • 与各聊天渠道(WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等)建立和维护连接。

      • 管理所有“会话(Session)”与“智能体(Agents)”的路由。

      • 承载 WebSocket 协议:所有客户端(CLI/Web UI/macOS App/Nodes)都通过 WS 与 Gateway 通信。

      • 承载工具/技能系统调用、权限、审批、安全策略。

  2. Pi Agent Runtime(“大脑”运行时)

    1. 内嵌的智能体执行引擎,来源于 pi-mono 项目,但会话管理/工具接线是 OpenClaw 自己实现的[3]。

    2. 职责:

      • 接受 Gateway 传来的“用户消息 + 会话上下文 + 可用工具列表”。

      • 调用底层大模型进行推理,决定:

        • 直接自然语言回复?

        • 调用哪些工具(执行命令/访问浏览器/调用 Node 能力)?

      • 组织工具调用链路(tool calling)与结果总结。

      • 负责把多轮对话压缩、做记忆写入等。

  3. Nodes(设备节点)

    1. 运行在 macOS / iOS / Android 或 headless 环境的“能力节点”。

    2. 通过 WebSocket 以 role: "node" 连接 Gateway,并声明自己支持的能力 / 命令,如:

      • system.runsystem.notify

      • canvas.*(可视化 Canvas UI)

      • camera.*screen.record

      • location.get、VoiceWake/Talk 模式 等

    3. Gateway 通过 node.invoke 把某些工具调用转发给节点执行(比如在 macOS 上执行命令、弹通知、录屏)。

  4. Skills(技能系统)与 Sandbox(沙箱执行环境)

    1. Skills 是对“工具”的抽象封装,一般以目录+SKILL.md 的形式存在:

      • 描述能力、参数(YAML frontmatter + 元数据)。

      • 实现文件(JS/TS / 其它可执行体)。

    2. 可以来源于:

      • 打包自带(bundled skills)

      • 本地 skills 目录(~/.openclaw/skills

      • 每个 agent 的 workspace 下 /skills

      • ClawHub(在线技能仓库)

    3. 对于“非主会话”(如群聊等),执行会放在 Docker 沙箱 中,隔离与限制权限[1]。


  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]:

  1. Gateway 主动发出 connect.challenge 事件:

    1. 内容包含 nonce 与时间戳,防重放防伪造。

  2. 客户端发送 req: connect,其中包含:

    1. minProtocol / maxProtocol:协商协议版本。

    2. client:客户端信息(id、version、platform、mode)。

    3. roleoperatornode

    4. scopes:权限范围(如 operator.read / operator.write / operator.approvals 等)。

    5. caps/commands/permissions:对 node 声明支持的功能。

    6. auth.token:如果环境设了 OPENCLAW_GATEWAY_TOKEN 或启动参数 --token,必须匹配。

    7. device:设备身份(id、publicKey、signature、nonce、signedAt)。

  3. Gateway 响应 res: hello-ok

    1. 协议版本、策略(如 tickIntervalMs)。

    2. 如果是首次 pairing,可能颁发 deviceToken,后续连接可复用该 token。

  4. 后续所有操作(发送消息、发起 agent 运行、查询状态)都复用这条 WebSocket 连接。

角色与权限:

  • role: "operator":CLI、控制台、Web UI 等控制平面客户端。

  • role: "node":设备节点,专注提供能力(system.run、camera、canvas 等)。

  • 所有权限由 scopes 与 node 的 commands/permissions 声明组合;Gateway 在服务端强制执行。

3.3 Agent 调用流程

一个典型“用户→AI→工具→结果”的完整链路:

  1. 用户消息到达

    1. 来自某个渠道(比如 Telegram 机器人、WhatsApp、Slack)。

    2. 接口库如 Baileys、grammY、Slack Bolt/Discord.js 等在 Gateway 里常驻。

  2. Gateway 将消息映射到 Session

    1. 根据会话规则(dmScope、group key 等)确定 sessionKey 与 sessionId[4]。

    2. 加载该会话对应的历史 JSONL(只加载需要进入上下文的部分)。

  3. Gateway 向 Agent Runtime 发送“执行请求”

    1. 包含:

      • 当前消息文本/媒体信息

      • 会话压缩后的上下文

      • 当下可用的技能/工具列表(以紧凑 XML 列表注入 system prompt[5])

      • 模型配置(primary + fallbacks)

  4. Agent Runtime 与模型交互

    1. 由 Agent 决定在本轮对话中:

      • 直接回答?

      • 先调用 1~N 个工具?

    2. 若调用工具:

      • Gateway 收到工具调用请求(结构化 JSON),检查权限、幂等键(idempotencyKey)。

      • 对于 host 工具(如本机 exec)或 sandbox 工具(Docker 容器内 exec),执行后把结果包装成“工具结果”再送回 Agent。

      • Agent 重新调用模型,把工具结果串联成最终自然语言回答。

  5. Gateway 把回答通过原始渠道发回给用户

    1. 同时更新会话 JSONL transcript 与 session store(tokens、时间戳、origin 信息等)。


  1. 技术栈:在什么样的技术栈上,增加了与 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 基本不感知具体厂商细节(只感知“某个具有工具/多模态能力的模型”)。


  1. “与 AI 交互”的具体实现机制

你问题里的两点:

  1. 是在什么样的技术栈上,增加了与 AI 模型的交互?

  2. 与 AI 交互的实现是什么?

可以拆解为两个层面:

5.1 技术栈上如何接入 AI 模型?

  1. Node.js + HTTP 客户端

    1. 在 Gateway/Agent Runtime 内部,通过 HTTP(S) 调用各大模型提供商的 REST/Streaming API。

    2. 支持流式响应(Server‑Sent Events 或 chunked stream)时,会将 chunk 逐步转发到 WebSocket 事件流中。

  2. 统一模型注册表(models.json + 配置)[3]

    1. 自定义 provider 写入 models.providers,实际序列化为 ~/.openclaw/agents/<agentId>/models.json

    2. 支持设置:

      • 基础 URL(baseUrl)

      • 验证方式(OAuth / API key)

      • 支持工具 / 不支持工具

      • 是否支持图像等多模态。

  3. CLI 与 Chat 命令的模型切换

    1. 通过 /model 命令(或 CLI openclaw 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 会实时显示这些块以及工具调用进度。


  1. 会话/记忆系统:不仅仅是“聊天记录”

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)逐渐沉淀。


  1. 安全模型与沙箱执行:这是评估这类项目时必须拆解的点

你没有直接问安全问题,但这是理解 OpenClaw 时最值得额外拆解的视角。

7.1 默认安全策略

根据 README 与 Security 部分[1]:

  • DM 默认策略:dmPolicy="pairing"

    • 陌生用户发私聊时,不直接触发 AI,只发送配对码。

    • 需要在本地 CLI 执行 openclaw pairing approve <code> 才会允许对方对话。

  • 群组/公共渠道默认 不开启 任意用户直接调用高危工具,需要显式配置 allowFrom/群组 allowlist。

  • 工具默认策略对非主会话(如群组)采用 Docker 沙箱模式,仅允许:

    • bashprocessread/write/edit 等有限工具。

    • 禁止 browsercanvasnodes 等高权限工具。

7.2 执行权限 & 审批机制

  • system.run 等危险命令:

    • 可配置“需要审批”:当 AI 想执行时,Gateway 会广播 exec.approval.requested,有权限的 operator 再通过 exec.approval.resolve 决定是否放行。

  • 节点权限:

    • permissions 字段中精确标记每种能力(如 screen.record)是否允许。

    • macOS 上还叠加 TCC 权限(屏幕录制、摄像头、麦克风等)。

实践建议:

  • 真正把它放在个人工作环境时,应至少:

    • 主会话不开沙箱,但极度慎重审查工具配置。

    • 群组/公共场景全部启用 Docker 沙箱。

    • 高危工具(浏览器自动化、系统脚本)加上人工审批。


  1. 可扩展性与工程性拆解:多几个“专业视角”

为了超出你原始问题,我再给几个常见工程/架构视角的拆解点:

8.1 “网关中心”架构的优劣

优点:

  • 单一控制平面,方便:

    • 统一安全策略

    • 集中日志与监控

    • 集中模型/工具配置

  • 所有客户端/节点都只需要会 WebSocket + JSON 协议即可接入。

潜在问题:

  • Gateway 是单点:

    • 一挂所有渠道都挂。

    • 高可用要额外做进程监管、重启策略、甚至集群化。

8.2 “技能”与“插件市场”的生态策略

  • Skills 的形式(SKILL.md + 实现文件)使得:

    • 开发者可以很快编写“熟悉的脚本”,通过简单 frontmatter 就变成“可被大模型使用的工具”。

    • ClawHub 作为技能仓库,可以形成生态(类似 VSCode 插件、Homebrew formula)。

工程上可以关注的点:

  • 是否可写出“企业内部的技能仓库”(自建 ClawHub 或镜像)?

  • 如何管理技能版本与回滚?

  • 如何对第三方技能做安全审计 / 代码审查?

8.3 部署模式与团队使用模式

从文档看,几种典型部署方式:

  1. 纯本地单用户:

    1. Gateway + Agent + 节点全部在一台个人电脑上。

    2. 主会话直连 host 工具,无 Docker 沙箱。

  2. 远程 Gateway,多设备节点:

    1. 在一台 Linux 服务器上跑 Gateway。

    2. macOS/iOS/Android 作为节点连接执行各自本地操作。

    3. 通过 Tailscale/SSH 暴露 Web 控制台与 WebSocket 给各用户。

  3. 团队场景:

    1. 同一 Gateway 服务多个用户(小团队)。

    2. 每个用户通过 DM pairing 拿到自己的 session。

    3. 强烈需要启用 per-peer / per-channel-peer dmScope 与群组沙箱。


  1. 如果你打算“读源码/做二次开发”,建议的拆解路径

  1. 第一步:弄清协议和会话

    1. docs/concepts/architecture.mddocs/gateway/protocol.md 入手,理解:

      • WebSocket 消息格式

      • connect / agent / send 等方法

      • 会话是怎样从“某个频道 + 某个人/群组”映射成 sessionKey 的[2][4]

  2. 第二步:看 Agent 与 Workspace

    1. docs/concepts/agent.md

      • Agent runtime 与模型是如何通过 RPC 对接?

      • Workspace 下 AGENTS/SOUL/TOOLS/USER 等文件如何注入到 prompt?

    2. 再看 docs/concepts/models.md

      • 模型提供商是怎么抽象的?

      • 如何扩展新 provider?

  3. 第三步:拆 Skills 与 Sandbox

    1. docs/tools/skills.mddocs/tools/creating-skills.md

      • 自己写一两个简单的技能(比如调用内部 HTTP 服务)。

      • 观察在沙箱/非沙箱时行为有何不同。

  4. 第四步:安全与多用户场景

    1. docs/gateway/security.md 与 Session 文档:

      • 配 DM 策略、群组策略。

      • 在 Docker 沙箱模式下挂载有限目录,观察安全边界。

  5. 第五步:根据自己需求扩展

    1. 需要新渠道:参考现有的 channels 文档与代码,按类似模式接入。

    2. 需要企业集成:写 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

Logo

有“AI”的1024 = 2048,欢迎大家加入2048 AI社区

更多推荐