OpenClawSkills
GitHub
深入探讨 • 8 分钟阅读

架构

深入探讨 OpenClaw 的网关中心设计、网络模型和代理执行循环。

OpenClaw 围绕网关中心架构构建，其中单个长期运行的进程管理所有通道连接并提供统一的控制平面。这种设计确保了可靠性、安全性和简洁性。

Tutorial.step

核心组件

网关

网关（<code>openclaw gateway</code>）是 OpenClaw 的核心。它是一个单一进程，负责：

  • 管理所有通道连接（WhatsApp、Telegram、Discord 等）。
  • 在端口 <strong>18789</strong>（默认）上提供 WebSocket 控制平面。
  • 处理会话管理和路由。
  • 提供控制 UI / 仪表板。
  • 管理视觉界面的 <strong>Canvas 主机</strong>。
  • 协调代理间通信。

稳定性提示

建议每台主机使用一个网关。它是唯一允许拥有 WhatsApp Web 会话的进程，确保稳定性并防止冲突。
Tutorial.step

网络模型

OpenClaw 使用 <strong>回环优先</strong> 方法以获得最大安全性：

  • <strong>默认：</strong> 网关 WebSocket 运行在 <code>ws://127.0.0.1:18789</code>（仅限本地主机）。
  • <strong>远程访问：</strong> 使用 SSH 隧道、Tailscale 或配置带有身份验证令牌的 <code>--bind</code> 以实现安全的外部访问。
  • <strong>Canvas 主机：</strong> 端口 <strong>18793</strong> 上的专用 HTTP 文件服务器，为高性能节点 WebView 提供 <code>/__openclaw__/canvas/</code>。

架构概览

WhatsApp / Telegram / Discord / iMessage (+ plugins)
            │
            ▼
┌───────────────────────────────────────────────┐
│                 Gateway                   │  ws://127.0.0.1:18789
│            (Single Source of Truth)          │
│                                              │  http://<host>:18793
└───────────────────────┬───────────────────────┘
                        │
  ┌─────────────────────┼─────────────────────┐
  │                     │                     │
  ▼                     ▼                     ▼
OpenClaw Agent (RPC)      CLI Tool      Native Apps (iOS/macOS)
Tutorial.step

代理循环

代理循环是定义如何处理消息的核心处理周期：

  1. <strong>接收消息：</strong> 连接的通道接收传入消息。
  2. <strong>会话路由：</strong> 消息被路由到适当的会话（主会话、群组会话或隔离会话）。
  3. <strong>上下文加载：</strong> 代理加载相关的历史上下文、记忆和工具。
  4. <strong>LLM 处理：</strong> 结构化请求被发送到 LLM 提供商（Claude、GPT 等）。
  5. <strong>工具执行：</strong> 代理根据需要自主执行工具（浏览器、文件系统、shell）。
  6. <strong>响应流式传输：</strong> 最终响应实时流式传输回通道。
  7. <strong>记忆更新：</strong> 对话被索引并保存到工作区。
Tutorial.step

会话模型

会话类型
  • <strong>主会话：</strong> 将所有直接消息折叠到共享上下文中。
  • <strong>群组会话：</strong> 每个群组聊天获得一个隔离的工作区。
  • <strong>隔离会话：</strong> 为特定的安全或临时需求创建。
会话功能
  • <strong>激活模式：</strong> 控制响应性（仅提及、始终等）。
  • <strong>队列管理：</strong> 高效处理并发请求。
  • <strong>沙盒：</strong> 多租户环境的可选 Docker 隔离。
Tutorial.step

工作区结构

OpenClaw 是 <strong>文件系统优先</strong> 的。所有内容都存储在配置和工作区目录中：

File Hierarchy
~/.openclaw/openclaw.json    # Configuration file
~/.openclaw/credentials/     # Secure channel tokens
~/.openclaw/workspace/       # Workspace Root
├── AGENTS.md                # Agent persona definitions
├── SOUL.md                  # Core personality & logic
├── TOOLS.md                 # Custom tool definitions
├── skills/                  # Plugin/Skill directory
└── sessions/                # Active conversation states
Tutorial.step

多代理路由

OpenClaw 支持基于以下条件的高级消息路由：

  • <strong>通道：</strong> WhatsApp 和 Discord 使用不同的代理。
  • <strong>账户/对等方：</strong> 将特定联系人路由到专用角色。
  • <strong>工作区隔离：</strong> 每个代理可以锁定到自己的目录和技能集。
Tutorial.step

流式传输与协议

流式传输与分块

OpenClaw 使用 <strong>块流式传输</strong> 以分块形式发送响应以提高感知速度。它还支持 <strong>Telegram 草稿流式传输</strong>，实时显示输入指示器和草稿。

通信协议
  • <strong>WebSocket：</strong> 用于实时传递和控制 UI 更新。
  • <strong>RPC（远程过程调用）：</strong> 代理用于工具调用和上下文查询。