跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
JavaScriptNode.jsAI

OpenClaw 原理详解：自托管 AI 网关架构深度剖析

OpenClaw 是一个自托管的多渠道 AI 代理网关，连接 WhatsApp、Telegram 等聊天应用与 AI 编码代理。其架构采用单一网关模式，支持多节点和客户端接入，通过 WebSocket 通信。核心功能包括分层会话管理、类型安全的工具系统、多代理路由及工作空间记忆持久化。提供命令行、Web UI 及原生应用控制界面，强调数据隐私控制和本地部署能力，适合开发者构建个人 AI 助手。

人间过客发布于 2026/3/25更新于 2026/10/26111 浏览
OpenClaw 原理详解：自托管 AI 网关架构深度剖析

OpenClaw 原理详解：自托管 AI 网关架构深度剖析

一、什么是 OpenClaw？

OpenClaw 🦞 是一个自托管网关，运行在你的机器（或服务器）上，作为聊天应用和 AI 助手之间的桥梁。它的核心理念是：无需放弃数据控制权，无需依赖托管服务，就能拥有一个随时待命的个人 AI 助手。

核心特点
  • 自托管：运行在你的硬件上，你的规则
  • 多渠道：一个网关进程同时服务 WhatsApp、Telegram、Discord 等
  • 代理原生：为编码代理构建，支持工具使用、会话、记忆和多代理路由
  • 开源：MIT 许可，社区驱动
适用人群

开发者和高级用户，希望从任何地方通过消息应用与个人 AI 助手交互，同时保持对数据和隐私的完全控制。

二、整体架构

OpenClaw 的架构设计遵循单一网关、多客户端、多节点的模式：

组件职责连接方式
Gateway（网关）维护所有消息渠道连接，暴露 WebSocket API，管理会话和路由WebSocket (18789 端口)
Channels（渠道）WhatsApp (Baileys)、Telegram (grammY)、Discord (discord.js) 等各自协议
Clients（客户端）macOS 应用、CLI、Web 管理界面WebSocket
Nodes（节点）iOS/Android/桌面节点，提供 Canvas、相机、屏幕录制等功能WebSocket (role: node)
Agent（代理）嵌入的 Pi 代理运行时，处理用户请求和工具调用内部 RPC

三、网关工作原理

3.1 连接生命周期

所有客户端（包括渠道、控制客户端和节点）通过 WebSocket 连接到网关：

AI 代理网关客户端 loop
req:connect (握手) -> res (ok) + hello-ok 快照
event:presence (状态更新)
event:tick (心跳)
req:agent (发送消息) -> 转发请求流式响应
event:agent (流式事件) -> res:agent (最终结果)
3.2 协议细节
  • 传输层：WebSocket，JSON 文本帧
  • 首帧要求：必须是 connect 握手帧
  • 请求格式：{type:"req", id, method, params}
  • 响应格式：{type:"res", id, ok, payload|error}
  • 事件推送：{type:"event", event, payload, seq}
3.3 认证与配对
  • 网关令牌：通过 OPENCLAW_GATEWAY_TOKEN 或 --token 设置
  • 设备配对：新设备需要配对批准，网关颁发设备令牌
  • 本地信任：环回地址或同一 Tailscale 网络的连接可自动批准
  • 签名挑战：所有连接必须签名 connect.challenge nonce

四、会话管理系统

4.1 会话键设计

OpenClaw 使用分层会话键来隔离不同场景的对话上下文：

agent:<agentId>:<channel>:<type>:<id>
会话类型键格式说明
直接消息 (默认)agent:main:main所有 DM 共享主会话
直接消息 (隔离)agent:main:whatsapp:dm:+15555550123按渠道 + 发送者隔离
群聊agent:main:whatsapp:group:<groupId>每个群组独立会话
Telegram 话题agent:main:telegram:group:<groupId>-topic:<threadId>话题隔离
Cron 任务cron:<jobId>隔离的自动化任务
4.2 会话重置策略
{ session: { reset: { mode: "daily", // 每日重置 atHour: 4, // 凌晨 4 点 idleMinutes: 120, // 或 120 分钟空闲后重置 }, dmScope: "per-channel-peer", // 推荐：按渠道 + 发送者隔离 } }
4.3 会话存储
  • 会话元数据：~/.openclaw/agents/<agentId>/sessions/sessions.json
  • 对话记录：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
  • 维护策略：自动修剪旧会话、归档转录文件、轮转存储

五、工具系统

OpenClaw 为 AI 代理提供第一类工具，无需 shell 调用，类型安全：

5.1 核心工具组
工具组包含工具用途
group:fsread, write, edit, apply_patch文件操作
group:runtimeexec, bash, process命令执行
group:sessionssessions_list, sessions_history, sessions_send会话管理
group:memorymemory_search, memory_get记忆检索
group:webweb_search, web_fetch网络搜索
group:uibrowser, canvas浏览器和画布自动化
group:messagingmessage消息发送
group:nodesnodes节点控制
5.2 工具策略
{ tools: { profile: "coding", // 基础配置：coding | messaging | minimal | full allow: ["group:fs", "browser"], // 白名单 deny: ["group:runtime"], // 黑名单（优先） byProvider: { "google-antigravity": { profile: "minimal" }, // 按提供商限制 }, } }
5.3 浏览器自动化流程
Start -> browser: status -> Browser Running? -> Yes -> browser: snapshot -> browser: act -> Need Screenshot? -> Yes -> browser: screenshot -> Done

六、多代理路由

OpenClaw 支持运行多个隔离的代理，每个代理有独立的工作空间和会话：

{ agents: { list: [ { id: "home", default: true, workspace: "~/.openclaw/workspace-home" }, { id: "work", workspace: "~/.openclaw/workspace-work" }, ], bindings: [ { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }, { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }, ], } }
路由匹配流程
Message Received -> Has Binding Rule? -> Yes -> Match Channel/Account -> Route to Agent -> Load Workspace -> Inject Config Files -> Agent Responds

七、工作空间与记忆系统

7.1 工作空间文件
文件用途
AGENTS.md操作指令和"记忆"
SOUL.md人格、边界、语气
TOOLS.md用户维护的工具笔记
BOOTSTRAP.md一次性首次运行仪式（完成后删除）
IDENTITY.md代理名称/氛围/表情符号
USER.md用户档案和偏好
7.2 记忆持久化
心跳维护 -> 短期记忆 -> 提炼 -> 长期记忆 -> 定期审查

八、安全与权限

8.1 DM 访问控制
{ channels: { whatsapp: { dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, // 群聊需要@提及 }, }, }, }
8.2 沙箱隔离
{ agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, }, }
8.3 工具权限
  • 执行批准：exec 命令可配置为需要用户批准
  • 工作空间限制：apply_patch 默认仅限工作空间内
  • 提升权限：elevated 模式需要显式配置

九、自动化能力

9.1 心跳检查
{ agents: { defaults: { heartbeat: { every: "30m", target: "last", // last | whatsapp | telegram | discord | none }, }, }, }
9.2 Cron 任务
{ cron: { enabled: true, maxConcurrentRuns: 2, sessionRetention: "24h", }, }
9.3 Webhooks
{ hooks: { enabled: true, token: "shared-secret", mappings: [ { match: { path: "gmail" }, action: "agent", agentId: "main", deliver: true, }, ], }, }

十、配置热重载

OpenClaw 支持配置热重载，无需手动重启：

{ gateway: { reload: { mode: "hybrid" }, // hybrid | hot | restart | off }, }
模式行为
hybrid (默认)安全更改立即生效，关键更改自动重启
hot仅热应用安全更改，需要重启时记录警告
restart任何更改都重启网关
off禁用文件监视，手动重启生效

十一、快速开始

11.1 安装
npm install -g openclaw@latest
11.2 初始化
openclaw onboard --install-daemon
11.3 配置渠道
openclaw channels login # WhatsApp 配对
11.4 启动网关
openclaw gateway --port 18789
11.5 打开控制 UI

访问 http://127.0.0.1:18789

十二、总结

OpenClaw 的核心创新在于：

  1. 统一网关架构：一个进程服务所有渠道，简化部署和维护
  2. 会话隔离：灵活的会话键设计，支持多用户、多场景隔离
  3. 工具系统：类型安全的内置工具，无需 shell 调用
  4. 自托管优先：数据完全掌控，隐私有保障
  5. 扩展性强：插件系统支持自定义渠道和工具

对于希望构建个人 AI 助手的开发者来说，OpenClaw 提供了一个开箱即用、高度可定制的基础架构。无论是简单的消息回复机器人，还是复杂的多代理协作系统，OpenClaw 都能胜任。

参考资源

  • 官方文档：https://docs.openclaw.ai
  • GitHub: https://github.com/openclaw/openclaw

目录

  1. OpenClaw 原理详解：自托管 AI 网关架构深度剖析
  2. 一、什么是 OpenClaw？
  3. 核心特点
  4. 适用人群
  5. 二、整体架构
  6. 三、网关工作原理
  7. 3.1 连接生命周期
  8. 3.2 协议细节
  9. 3.3 认证与配对
  10. 四、会话管理系统
  11. 4.1 会话键设计
  12. 4.2 会话重置策略
  13. 4.3 会话存储
  14. 五、工具系统
  15. 5.1 核心工具组
  16. 5.2 工具策略
  17. 5.3 浏览器自动化流程
  18. 六、多代理路由
  19. 路由匹配流程
  20. 七、工作空间与记忆系统
  21. 7.1 工作空间文件
  22. 7.2 记忆持久化
  23. 八、安全与权限
  24. 8.1 DM 访问控制
  25. 8.2 沙箱隔离
  26. 8.3 工具权限
  27. 九、自动化能力
  28. 9.1 心跳检查
  29. 9.2 Cron 任务
  30. 9.3 Webhooks
  31. 十、配置热重载
  32. 十一、快速开始
  33. 11.1 安装
  34. 11.2 初始化
  35. 11.3 配置渠道
  36. 11.4 启动网关
  37. 11.5 打开控制 UI
  38. 十二、总结
  39. 参考资源

更多推荐文章

查看全部
  • 动态规划：买卖股票的最佳时机 I、II、III 详解
  • 2024 中文大模型基准测评报告：核心指标与性能分析
  • Spring Web MVC 核心概念与实战指南
  • Java 手写 AI Agent：ZenoAgent 核心设计与实现
  • AI 大模型技术入门与全栈开发实战指南
  • 2026 年 3 月 GitHub 榜单深度解析：AI 代理与工业级落地
  • AI 热榜观察：OpenClaw 之外的 5 个关键趋势
  • 国内如何付费升级 GitHub Copilot 专业版
  • C++ 哈希表封装实战：从原理到 unordered_map 底层优化
  • DEIM 实时目标检测算法及 Visdrone2019 数据集实战
  • AI Coding 核心指南：从上下文工程到任务拆解策略
  • 大模型训练实战经验总结
  • RK3588 与 FPGA 基于 XDMA 的 PCIe 通信实践
  • Flask 框架从入门到实战完整指南
  • Docker 零基础入门：核心概念与使用价值
  • GitHub Copilot 提示词工程实战指南
  • AI 智能体 (Agent) 的 5 个能力级别详解
  • Spring 7 弃用 JSR 305，全面采用 JSpecify 空安全注解
  • ResNext 网络核心技术解析及 UCI-HAR 数据集实验分析
  • C++ std::promise 原理与实战解析

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online