JavaScriptNode.jsAI
OpenClaw 原理详解：自托管 AI 网关架构深度剖析
OpenClaw 是一个自托管的多渠道 AI 代理网关，连接 WhatsApp、Telegram 等聊天应用与 AI 编码代理。其架构采用单一网关模式，支持多节点和客户端接入，通过 WebSocket 通信。核心功能包括分层会话管理、类型安全的工具系统、多代理路由及工作空间记忆持久化。提供命令行、Web UI 及原生应用控制界面，强调数据隐私控制和本地部署能力，适合开发者构建个人 AI 助手。
OpenClaw 是一个自托管的多渠道 AI 代理网关，连接 WhatsApp、Telegram 等聊天应用与 AI 编码代理。其架构采用单一网关模式，支持多节点和客户端接入，通过 WebSocket 通信。核心功能包括分层会话管理、类型安全的工具系统、多代理路由及工作空间记忆持久化。提供命令行、Web UI 及原生应用控制界面，强调数据隐私控制和本地部署能力，适合开发者构建个人 AI 助手。
OpenClaw 🦞 是一个自托管网关，运行在你的机器（或服务器）上，作为聊天应用和 AI 助手之间的桥梁。它的核心理念是：无需放弃数据控制权，无需依赖托管服务，就能拥有一个随时待命的个人 AI 助手。
开发者和高级用户，希望从任何地方通过消息应用与个人 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 |
所有客户端（包括渠道、控制客户端和节点）通过 WebSocket 连接到网关：
AI 代理网关客户端 loop
req:connect (握手) -> res (ok) + hello-ok 快照
event:presence (状态更新)
event:tick (心跳)
req:agent (发送消息) -> 转发请求流式响应
event:agent (流式事件) -> res:agent (最终结果)
connect 握手帧{type:"req", id, method, params}{type:"res", id, ok, payload|error}{type:"event", event, payload, seq}OPENCLAW_GATEWAY_TOKEN 或 --token 设置connect.challenge nonceOpenClaw 使用分层会话键来隔离不同场景的对话上下文：
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> | 隔离的自动化任务 |
{ session: { reset: { mode: "daily", // 每日重置 atHour: 4, // 凌晨 4 点 idleMinutes: 120, // 或 120 分钟空闲后重置 }, dmScope: "per-channel-peer", // 推荐：按渠道 + 发送者隔离 } }
~/.openclaw/agents/<agentId>/sessions/sessions.json~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonlOpenClaw 为 AI 代理提供第一类工具，无需 shell 调用，类型安全：
| 工具组 | 包含工具 | 用途 |
|---|---|---|
group:fs | read, write, edit, apply_patch | 文件操作 |
group:runtime | exec, bash, process | 命令执行 |
group:sessions | sessions_list, sessions_history, sessions_send | 会话管理 |
group:memory | memory_search, memory_get | 记忆检索 |
group:web | web_search, web_fetch | 网络搜索 |
group:ui | browser, canvas | 浏览器和画布自动化 |
group:messaging | message | 消息发送 |
group:nodes | nodes | 节点控制 |
{ tools: { profile: "coding", // 基础配置：coding | messaging | minimal | full allow: ["group:fs", "browser"], // 白名单 deny: ["group:runtime"], // 黑名单（优先） byProvider: { "google-antigravity": { profile: "minimal" }, // 按提供商限制 }, } }
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
| 文件 | 用途 |
|---|---|
AGENTS.md | 操作指令和"记忆" |
SOUL.md | 人格、边界、语气 |
TOOLS.md | 用户维护的工具笔记 |
BOOTSTRAP.md | 一次性首次运行仪式（完成后删除） |
IDENTITY.md | 代理名称/氛围/表情符号 |
USER.md | 用户档案和偏好 |
心跳维护 -> 短期记忆 -> 提炼 -> 长期记忆 -> 定期审查
{ channels: { whatsapp: { dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, // 群聊需要@提及 }, }, }, }
{ agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, }, }
exec 命令可配置为需要用户批准apply_patch 默认仅限工作空间内elevated 模式需要显式配置{ agents: { defaults: { heartbeat: { every: "30m", target: "last", // last | whatsapp | telegram | discord | none }, }, }, }
{ cron: { enabled: true, maxConcurrentRuns: 2, sessionRetention: "24h", }, }
{ 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 | 禁用文件监视，手动重启生效 |
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw channels login # WhatsApp 配对
openclaw gateway --port 18789
访问 http://127.0.0.1:18789
OpenClaw 的核心创新在于：
对于希望构建个人 AI 助手的开发者来说，OpenClaw 提供了一个开箱即用、高度可定制的基础架构。无论是简单的消息回复机器人，还是复杂的多代理协作系统，OpenClaw 都能胜任。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online