架构

理解 OpenClaw 的 Gateway、Agent runtime、工具、插件、会话、节点、记忆、模型提供商和协议如何组合。

OpenClaw 是一个分层 Agent 平台。Gateway 管入口、认证、路由、事件和控制界面；Agent runtime 管提示词、工具、记忆、模型和执行；插件和节点向外扩展能力。

系统概览

Gateway

Gateway 是长期运行的控制平面。它负责：

• 提供 Control UI
• 暴露 WebSocket 和 HTTP 界面
• 管理认证和设备配对
• 连接聊天渠道
• 将入站消息路由到 session 和 Agent
• 发出事件
• 跟踪健康和用量
• 协调 nodes 和 paired clients

默认本地端口通常是 18789。

Wire Protocol

Gateway clients 使用 WebSocket 上的 JSON frames。常见形态是：

• 先建立连接
• request/response frames 处理 RPC 风格调用
• event frames 处理服务端推送
• auth 放在连接 handshake 中
• 有副作用的方法按需做幂等

具体协议会演进；构建 client 时，把 docs 和生成出来的 schemas 当作真源。

Agent Runtime

每轮运行时会组合：

• session state
• workspace context
• system prompt 和 runtime preface
• selected model provider
• visible tools
• active skills
• memory recall
• channel/runtime policy

Agent loop 仍然是：

1. 接收输入
2. 路由到 agent/session
3. 组装上下文
4. 调用模型
5. 执行工具
6. 观察结果
7. 回复或继续
8. 持久化 session 和 memory state

Tools、Skills、Plugins

• tools 是可调用动作
• skills 是 prompt-level 工作流指令
• plugins 是运行时扩展，可添加工具、渠道、providers、hooks、媒体和 skills

这个分层让 OpenClaw 不必把所有能力塞进核心 runtime。

Sessions 与 Memory

Sessions 保存对话和工具历史。Compaction 总结长上下文。长期记忆以 workspace 文件为基础，主要是 MEMORY.md 和 memory/YYYY-MM-DD*.md；memory search、QMD、active memory、dreaming 和 memory wiki 是围绕文件层增加的检索和整理路径。

Channels

Channels 是 ingress/egress adapters。Gateway 把 Telegram、WhatsApp、Slack、Discord、iMessage、Signal、WebChat 等统一成 routing events 和 message delivery。

Nodes

Nodes 是配对设备界面，可以暴露 camera、screen、location、Canvas、voice 和平台动作。配对后，应把 node 看作同一 operator trust boundary 的一部分。

Model Providers

Runtime 要协调：

• provider IDs
• model catalog
• auth profiles
• tool schema compatibility
• fallback behavior
• usage reporting

长会话里，provider-specific replay 和 tool-schema 行为是实际运维问题。

ACP 与 MCP

OpenClaw 可以扮演几种角色：

• ACP bridge：编辑器或 ACP client 连接 OpenClaw，OpenClaw 转发到 Gateway session
• ACP agents：OpenClaw 启动 Codex、Claude Code、Gemini CLI 等外部 harness
• MCP：让外部客户端或工具接入 OpenClaw conversation/capability

不要混淆这些角色。

Sandboxing

Sandboxing 作用于工具执行，不作用于 Gateway 进程本身。关键问题不是“有没有开沙盒”，而是哪类 session、哪些工具、什么 workspace access、哪些 escape paths。

Design Principles