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

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

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

人间过客发布于 2026/3/25更新于 2026/7/2044 浏览
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. 参考资源
  • 免费图片AI生成工具免费生成了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 免费图片视频在线生成30秒，将你的创意变成现实开始设计
  • X/Twitter免费视频下载器免登陆无限额度免费视频解析下载了解详情
  • 100+免费在线小游戏爽一把
极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

更多推荐文章

查看全部
  • AI 图像生成指南：从原理到实战
  • 王立威教授解析：从理论视角看大模型的聪明与愚蠢
  • 基于 LangChain 开发大模型 RAG 知识问答应用
  • FPGA 实现高速数字信号处理的核心技术与工程实践
  • Web 项目 UI 自动化测试实战：从零搭建博客系统测试框架
  • C++ 位运算实战：从基础操作到经典算法题解
  • Python Web 框架对比与实战：Django vs Flask vs FastAPI
  • 从 Prompt 到爆款短片：AI视频生成 10 分钟上手指南
  • CC-Switch：AI 编码助手配置管理工具
  • LLM 大模型技术：入门、应用场景与行业机遇分析
  • 两个月从入门到独立进行漏洞挖掘的渗透测试指南
  • PyCharm 与 GitHub Copilot 配置指南：学生认证流程详解
  • 基于 Spring Cloud 的分布式智能推荐系统实现
  • GitHub 十大 Claude Skills 精选，实战提升开发效率
  • VLA 机器人革命：解析 10 篇关键视觉 - 语言 - 动作模型论文
  • EgoPoseFormer v2：AR/VR 第一视角人体动捕技术解析
  • iceoryx 附录：C++ 内存模型与原子操作详解
  • SkyWalking 与 Spring Cloud Alibaba 全链路追踪实战
  • OpenClaw 数字员工核心逻辑与架构全景解析
  • 前端响应式进阶：从 vw/vh 到 clamp() 的痛点与进化

相关免费在线工具

  • 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