OpenClaw Gateway 架构深度解析：3 层认证 + 4 种部署，揭秘 Agent 神经中枢

运维有术

发布于 2026-04-01 19:42:13

5530

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划第 49 篇，OpenClaw 最佳实战「2026」系列第 19 篇大家好，欢迎来到 术哥无界 | ShugeX ｜运维有术。我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、Milvus 向量数据库的技术实践者与开源布道者！
Talk is cheap, let's explore。无界探索，有术而行。

图 1：OpenClaw Gateway 架构全景

如果你要设计一个 Agent 系统，如何让多个客户端（CLI、Web UI、移动 App）、多种能力（摄像头、屏幕录制、系统命令）、多个消息通道（WhatsApp、Telegram、飞书）协同工作？

更关键的是，如何保证这些组件既能灵活扩展，又能安全可控？

OpenClaw Gateway 给出了一个优雅的答案。作为一个 AI Agent 平台的神经中枢，它用统一的 WebSocket 协议、三层安全认证、插件化架构，构建了一个既安全又灵活的控制平面。

翻了一圈官方文档和源码，我发现它的设计有不少值得借鉴的地方。今天就来深入聊聊。

1. Gateway 是什么？

在 OpenClaw 的架构中，Gateway 扮演着神经中枢的角色。

如果把整个系统比作人体：

Agent 是大脑，负责思考和决策
Node 是手脚，提供摄像头、屏幕、系统命令等执行能力
Channel 是嘴巴和耳朵，连接 WhatsApp、Telegram 等消息平台
Gateway 就是脊髓，负责协调所有这些组件的通信和协作

它的核心职责包括：

协议层：统一所有客户端和节点的通信协议（WebSocket），处理身份认证、消息路由、会话管理

能力层：管理 Node 的能力声明（caps），控制哪些命令可以执行，审批敏感操作

消息层：对接各种消息通道（Channel Plugin），处理入站消息的解析、出站消息的发送

安全层：实施三层认证机制，管理设备配对，执行权限策略

图 2：Gateway 在系统中的位置和核心组件

从架构上看，Gateway 是一个典型的控制平面（Control Plane）设计 - 它不直接执行 Agent 的推理，也不直接操作硬件，而是作为一个中间层，协调所有组件的协作。

2. 通信协议设计

Gateway 的核心是单一的 WebSocket 协议。所有客户端（CLI、Web UI、macOS app、iOS/Android nodes、headless nodes）都通过 WebSocket 连接，并在握手时声明其角色（operator 或 node）和作用域。

这种统一协议的好处是：无论你用什么设备、什么客户端，都能用同一套协议与 Gateway 通信。

三种消息类型

WebSocket 通信只有三种消息类型，设计得很简洁：

Request（请求）：

{
  "type": "req",
  "id": "unique-request-id",
  "method": "connect",
  "params": { ... }
}

Response（响应）：

{
  "type": "res",
  "id": "unique-request-id",
  "ok": true,
  "payload": { ... }
}

Event（事件）：

{
  "type": "event",
  "event": "agent",
  "payload": { ... },
  "seq": 123,
  "stateVersion": 456
}

有意思的是 seq 和 stateVersion 这两个字段 - 它们支持状态同步和增量更新。当客户端重连时，可以通过这些序列号快速同步状态，而不需要重新传输所有数据。

幂等性键的设计

对于副作用方法（如 send、agent），Gateway 要求必须包含幂等性键（Idempotency Key）。

{
  "type": "req",
  "method": "send",
  "idempotencyKey": "unique-key-123",
  "params": { ... }
}

服务器会维护一个短期去重缓存，如果收到相同 idempotencyKey 的请求，会直接返回之前的响应，而不是重复执行。这在网络不稳定的环境下特别有用 - 客户端可以安全地重试，而不用担心重复发送消息。

三层认证机制

Gateway 的认证设计很 clever，采用了三层防护：

第一层：Gateway Token

最基础的共享密钥认证。通过 OPENCLAW_GATEWAY_TOKEN 环境变量或配置文件设置，客户端必须在握手时提供正确的 token 才能建立连接。

{
  gateway: {
    auth: { 
      mode: "token", 
      token: "${OPENCLAW_GATEWAY_TOKEN}" 
    }
  }
}

第二层：Device Identity

每个 WebSocket 客户端必须包含设备身份：

{
  "device": {
    "id": "device_fingerprint",
    "publicKey": "...",
    "signature": "...",
    "signedAt": 1737264000000,
    "nonce": "..."
  }
}

这里用的是非对称加密 - 客户端用私钥签名，Gateway 用公钥验证。签名载荷绑定 platform + deviceFamily，防止重放攻击。

第三层：Pairing Approval

即使通过了前两层认证，新设备 ID 仍需要显式批准才能使用。Gateway 会签发一个设备令牌（device token）用于后续连接。

# 查看待配对设备
openclaw devices list

# 批准设备
openclaw devices approve <requestId>

但有个 clever 的设计：本地连接（loopback 或 tailnet 地址）可以自动批准。这意味着你在自己电脑上用 CLI 或 macOS App 时，不需要手动批准，体验很流畅。但如果是远程设备连接，就必须显式批准，保证安全性。

图 3：三层认证流程

连接生命周期

一个完整的连接流程是这样的：

客户端发起 WebSocket 连接
Gateway 发送 connect.challenge 事件（包含 nonce 和时间戳）
客户端响应 connect 请求（包含设备身份签名）
Gateway 验证 token、设备签名、配对状态
如果是新设备，触发配对审批流程
审批通过后，签发 device token，连接建立
定期发送 tick 心跳事件，超时未响应则断开

这种设计的精妙之处在于：既保证了安全性，又通过本地自动审批保持了良好的用户体验。这种平衡很难得。

你在项目中用过类似的 Agent 系统吗？欢迎在评论区聊聊你的经验。

3. 插件化渠道接入

Gateway 的另一个亮点是插件化的 Channel 架构。

如果你想接入一个新的消息通道（比如企业微信、钉钉），不需要修改 Gateway 的核心代码，只需要实现一个 Channel Plugin。

ChannelPlugin 接口设计

一个 Channel Plugin 必须实现以下接口：

interface ChannelPlugin {
  id: string;
  meta: ChannelMeta;

// 必须实现
  capabilities: ChannelCapabilities;
  config: {
    listAccountIds(cfg: Config): string[];
    resolveAccount(cfg: Config, accountId?: string): AccountConfig;
  };
  outbound: {
    deliveryMode: "direct" | "gateway";
    sendText(params: SendTextParams): Promise<SendResult>;
  };
}

capabilities 声明这个通道支持哪些功能：

interface ChannelCapabilities {
  chatTypes?: ("direct" | "group")[];  // 支持的聊天类型
  polls?: boolean;                     // 投票支持
  threads?: boolean;                   // 线程支持
  media?: {                            // 媒体支持
    images?: boolean;
    audio?: boolean;
    video?: boolean;
    files?: boolean;
  };
  reactions?: boolean;                 // 表情反应
  editMessages?: boolean;              // 消息编辑
  deleteMessages?: boolean;            // 消息删除
  typingIndicator?: boolean;           // 打字指示器
}

config 负责账户管理 - 如果你有多个账户（比如个人 WhatsApp 和工作 WhatsApp），通过 listAccountIds 和 resolveAccount 来区分。

outbound 负责消息发送 - deliveryMode 可以是 direct（直接发送）或 gateway（通过 Gateway 转发）。

能力声明驱动

关键设计在于：Gateway 的核心消息处理逻辑会根据 capabilities 动态调整。

举个例子：

// 如果通道支持 threads
capabilities: { threads: true }

// Gateway 会自动：
// 1. 会话键包含 thread ID
// 2. 回复消息包含 thread context
// 3. 调用插件的 threading.resolveThread() 方法

// 如果通道支持媒体
capabilities: { 
  media: { images: true } 
}

// Gateway 会自动：
// 1. 下载入站图片
// 2. 调用视觉理解模型
// 3. 把图片内容传递给 Agent

这种能力驱动（Capability-Driven）的设计，让 Gateway 的核心代码不需要为每个通道写特殊逻辑，只需要根据 capabilities 调用对应的插件方法即可。

图 4：ChannelPlugin 接口设计

实战示例：飞书插件

看看飞书（Feishu）插件的能力声明：

{
  id: "feishu",
  capabilities: {
    chatTypes: ["direct", "group"],
    media: {
      images: true,
      audio: true,
      video: true,
      files: true
    },
    streaming: true,        // 支持流式输出
    blockStreaming: true,   // 支持块级流式
    reactions: false        // 不支持表情反应
  }
}

配置也很简单：

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",  // DM 策略：需要配对
      domain: "feishu",     // 或 "lark"
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "My AI assistant",
          connectionMode: "websocket"  // 或 "webhook"
        }
      }
    }
  }
}

飞书插件的一个特色是支持流式输出 - Agent 的回复可以实时显示在飞书卡片中，而不是等整段回复生成完才发送。这在长回复时体验好很多。

实战示例：Telegram 插件

Telegram 插件的能力声明：

{
  id: "telegram",
  capabilities: {
    chatTypes: ["direct", "group"],
    polls: true,            // 支持投票
    threads: false,         // 不支持线程
    media: { images: true, audio: true, video: true, files: true },
    reactions: true,        // 支持表情反应
    editMessages: true,     // 支持编辑消息
    deleteMessages: true,   // 支持删除消息
    typingIndicator: true,  // 支持打字指示器
    streaming: {
      supportsStreaming: true,
      streamMode: "partial"// 部分流式
    }
  }
}

Telegram 插件有个独特特性：Forum Topics（论坛主题）。你可以在一个 Telegram 群组里创建多个主题，每个主题绑定不同的 Agent：

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },    // 主题 1 → main agent
            "3": { agentId: "zu" },      // 主题 3 → zu agent
            "5": { agentId: "coder" }    // 主题 5 → coder agent
          }
        }
      }
    }
  }
}

这样，同一个群组的不同主题，可以有不同的 Agent 响应，很灵活。

4. 消息路由与会话管理

Gateway 的消息路由设计采用了分层优先级绑定机制。

分层优先级绑定

当你配置多个 Agent 和多个通道时，Gateway 需要知道：一条来自 WhatsApp 的消息，应该由哪个 Agent 处理？

绑定配置的优先级从高到低：

Group/Topic 级别绑定（最高优先级）

{
  bindings: [
    {
      agentId: "work",
      match: { 
        channel: "slack", 
        accountId: "company",
        group: "dev-team" 
      }
    }
  ]
}

DM 级别绑定

{
  bindings: [
    {
      agentId: "home",
      match: { 
        channel: "whatsapp", 
        accountId: "personal",
        peer: "+15555550123" 
      }
    }
  ]
}

Channel 级别绑定

{
  bindings: [
    {
      agentId: "default",
      match: { channel: "telegram" }
    }
  ]
}

全局默认 Agent（最低优先级）

{
  agents: {
    default: "main"
  }
}

这种分层设计让你可以精确控制：工作 Slack 的消息由工作 Agent 处理，个人 WhatsApp 的消息由个人 Agent 处理，Telegram 群组的消息由默认 Agent 处理。

Session 隔离策略

Gateway 默认采用 per-channel-peer 的会话隔离策略：

{
  session: {
    dmScope: "per-channel-peer"  // 每个 channel+peer 独立会话
  }
}

这意味着：

WhatsApp 用户 A 和 Telegram 用户 A 是两个独立的会话
同一个用户在不同通道的消息不会混淆
Agent 可以针对不同通道的用户维护独立的状态

如果通道支持 threads，会话键还会包含 thread ID：

sessionKey: "whatsapp:+15555550123:thread-123"

这样，同一个用户的不同线程对话也是独立的。

跨平台身份链接

虽然默认是 per-channel-peer 隔离，但你可以通过身份链接（Identity Linking）实现跨平台的用户识别。

配置示例：

{
  identity: {
    linking: {
      enabled: true,
      providers: ["email", "phone"]
    }
  }
}

这样，如果一个用户在 WhatsApp 用手机号 +1-555-555-0123，在 Telegram 也绑定了同一个手机号，Gateway 可以识别为同一个用户，共享部分上下文。

不过这是个可选功能，默认情况下每个通道的用户都是独立的。

5. Agent 装备机制

Gateway 对 Agent 的控制是通过装备（Equipping）机制实现的。你可以控制每个 Agent 有哪些 Skills、可以使用哪些 Tools、有什么权限。

Skills 注入（知识边界）

Skills 是 Agent 的知识边界 - 你可以让不同的 Agent 访问不同的知识库：

{
  agents: {
    list: [
      {
        id: "home",
        skills: {
          directories: ["~/.openclaw/skills/home"],
          search: { enabled: true }
        }
      },
      {
        id: "work",
        skills: {
          directories: ["~/.openclaw/skills/work"],
          search: { enabled: true }
        }
      }
    ]
  }
}

这样，工作 Agent 只能访问工作相关的知识库，个人 Agent 只能访问个人知识库，实现了知识的隔离。

Tools 过滤（能力边界）

Tools 是 Agent 的能力边界 - 你可以限制每个 Agent 能使用哪些工具：

{
  agents: {
    list: [
      {
        id: "messaging",
        tools: {
          profile: "messaging",  // 预定义的 messaging profile
          allow: ["group:communication"],
          deny: ["exec", "browser"]
        }
      },
      {
        id: "automation",
        tools: {
          profile: "minimal",
          allow: ["exec", "fs", "browser"]
        }
      }
    ]
  }
}

profile 是预定义的工具集：

messaging：只包含消息相关的工具
minimal：只包含最基础的工具
full：包含所有工具（谨慎使用）

allow/deny 可以精细控制：

allow: ["group:communication"] 允许所有通信类工具
deny: ["exec"] 禁止执行系统命令

多层安全策略管道

Gateway 的安全策略是多层管道：

第一层：Gateway 全局策略

{
  gateway: {
    nodes: {
      allowCommands: ["camera.snap", "canvas.navigate"],
      denyCommands: ["system.run"]
    }
  }
}

第二层：Agent 级别策略

{
  agents: {
    list: [{
      id: "safe",
      tools: {
        deny: ["exec", "browser"]
      }
    }]
  }
}

第三层：Exec 审批机制

即使通过了前两层，执行敏感命令仍需要审批：

// ~/.openclaw/exec-approvals.json
{
  "mode": "ask",  // deny | ask | allowlist | full
  "allowlist": [
    "/usr/bin/git",
    "/usr/bin/docker"
  ]
}

审批模式：

deny：拒绝所有命令
ask：每次都询问（推荐）
allowlist：仅允许白名单中的命令
full：允许所有命令（危险）

当 Agent 要执行命令时，Gateway 会发送 exec.approval.requested 事件给 Operator（CLI 或 Web UI），等待人工批准或拒绝。

这种多层防护的设计，让你可以根据安全需求灵活配置。对于个人使用的 Agent，可以宽松一些；对于生产环境的 Agent，可以严格一些。

你在项目中用过类似的 Agent 系统吗？欢迎在评论区聊聊你的经验。

6. Node 架构：远程能力宿主

Node 是 Gateway 的能力扩展点 - 它可以是你的 iPhone（提供摄像头、地理位置）、你的 Mac（提供浏览器、系统命令）、或者一个云端的无头节点（提供持久化存储、定时任务）。

设备配对流程

Node 连接 Gateway 的流程：

┌─────────────┐
│  Node 连接  │
│  WebSocket  │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ 发送 connect    │
│ + device identity│
└──────┬──────────┘
       │
       ▼
┌──────────────────┐      ┌─────────────┐
│ Gateway 检查     │──No──▶│ 拒绝连接    │
│ device.id 是否   │      └─────────────┘
│ 已配对?          │
└──────┬───────────┘
       │Yes
       ▼
┌──────────────────┐
│ 创建 device      │
│ pairing request  │
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│ Operator 审批     │
│ (CLI/UI)         │
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│ 签发 device      │
│ token            │
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│ 返回 hello-ok    │
│ + deviceToken    │
└──────────────────┘

配对状态存储：

待处理请求：~/.openclaw/devices/pending.json
已配对设备：~/.openclaw/devices/paired.json

审批命令：

# 查看待配对设备
openclaw devices list

# 批准设备
openclaw devices approve <requestId>

# 拒绝设备
openclaw devices reject <requestId>

能力声明与命令白名单

Node 在连接时要声明自己提供哪些能力：

{
  "role": "node",
"caps": [
    "camera",      // 摄像头
    "canvas",      // Canvas UI
    "screen",      // 屏幕录制
    "location",    // 地理位置
    "voice"        // 语音
  ],
"commands": [
    "camera.snap",           // 拍照
    "canvas.navigate",       // Canvas 导航
    "screen.record",         // 屏幕录制
    "location.get"           // 获取位置
  ],
"permissions": {
    "camera.capture": true,
    "screen.record": false
  }
}

Gateway 会维护一个命令白名单：

{
  gateway: {
    nodes: {
      allowCommands: ["camera.snap", "canvas.navigate"],
      denyCommands: ["system.run"]
    }
  }
}

当 Agent 要调用 Node 的某个命令时，Gateway 会检查：

Node 是否声明了这个命令？
命令是否在白名单中？
Node 的 permissions 是否允许？

只有全部通过，才会把命令转发给 Node 执行。

安全审批机制

对于敏感操作（如执行系统命令），还有额外的审批机制：

{
  tools: {
    exec: {
      host: "node",        // 在 Node 上执行
      node: "build-node",  // 指定 Node
      approvals: {
        mode: "ask"        // 每次都询问
      }
    }
  }
}

时序图：

Agent         Gateway       Node          Operator
  │             │            │               │
  │ exec cmd    │            │               │
  ├────────────>│            │               │
  │             │ check mode │               │
  │             │ = ask      │               │
  │             │            │               │
  │             │ exec.approval.requested   │
  │             ├───────────────────────────>│
  │             │            │               │
  │             │            │  approve/reject│
  │             │            │<──────────────│
  │             │            │               │
  │             │ invoke cmd │               │
  │             ├───────────>│               │
  │             │            │               │
  │             │    result  │               │
  │             │<───────────┤               │
  │    response │            │               │
  │<────────────┤            │               │

断连清理与超时处理

Node 断开连接时，Gateway 会自动清理临时资源：

{
  gateway: {
    ws: {
      pingIntervalMs: 30000,   // 30 秒发送一次心跳
      pongTimeoutMs: 10000     // 10 秒未响应视为超时
    }
  }
}

超时未响应的 Node 会被断开连接，并清理：

浏览器会话
Canvas 状态
临时文件

这种自动清理机制，避免了资源泄漏。

图 5：Node 配对与通信流程

7. Canvas Host：Agent 可编辑的 Web 界面

Canvas Host 是 Gateway 的一个独特功能 - 它提供了一个Agent 可编辑的 HTML/CSS/JS 工作区。

`/openclaw/canvas/` 的用途

Gateway 的 HTTP 服务器（默认端口 18789）提供了一个特殊路径：

http://<gateway-host>:18789/__openclaw__/canvas/
├── index.html           # 默认首页
├── assets/
│   ├── app.css         # 样式文件
│   └── app.js          # 脚本文件
└── widgets/
    └── todo/
        └── index.html  # 自定义组件

Agent 可以通过工具 API 创建、修改这些文件：

# 显示/隐藏面板
openclaw nodes canvas present --node <id>
openclaw nodes canvas hide --node <id>

# 导航到 URL 或路径
openclaw nodes canvas navigate --node <id> --url "/"

# 执行 JavaScript
openclaw nodes canvas eval --node <id> --js "document.title"

# 捕获快照
openclaw nodes canvas snapshot --node <id>

Agent-editable HTML/CSS/JS 机制

Canvas 的核心设计是：Agent 可以动态生成和修改 HTML/CSS/JS。

存储位置（macOS App）：

~/Library/Application Support/OpenClaw/canvas/<session>/

URL Scheme：

openclaw-canvas://<session>/<path>

示例：

openclaw-canvas://main/ → <canvasRoot>/main/index.html
openclaw-canvas://main/widgets/todo/ → <canvasRoot>/main/widgets/todo/index.html

安全限制：

阻止目录遍历攻击
文件必须在 session 根目录下
使用自定义 URL scheme（不依赖 loopback 服务器）

更有意思的是，Canvas 内的 JavaScript 可以触发新的 Agent 运行：

// Canvas 内触发新的 Agent 运行
window.location.href = "openclaw://agent?message=Review%20this%20design";

这样，Agent 可以生成一个 UI，用户点击 UI 的某个按钮，又可以触发新的 Agent 任务。

A2UI 协议：声明式 UI

除了手写 HTML，Gateway 还支持 A2UI（Agent-to-UI）协议 - 一种声明式 UI 协议。

A2UI v0.8 协议示例（JSONL 格式）：

{"surfaceUpdate":{"surfaceId":"main","components":[...]}}
{"beginRendering":{"surfaceId":"main","root":"root"}}

组件示例：

{
  "surfaceUpdate": {
    "surfaceId": "main",
    "components": [
      {
        "id": "root",
        "component": {
          "Column": {
            "children": {
              "explicitList": ["title", "content"]
            }
          }
        }
      },
      {
        "id": "title",
        "component": {
          "Text": {
            "text": {"literalString": "Canvas (A2UI v0.8)"},
            "usageHint": "h1"
          }
        }
      }
    ]
  }
}

A2UI 的优势是服务器推送渲染 - Agent 可以逐步推送 UI 组件，而不需要一次性生成完整的 HTML。

8. 四种部署形态

OpenClaw Gateway 支持四种部署形态，适应不同的使用场景。

部署形态 1：本地 Gateway + 远程 Node

┌──────────────────────┐
│  Local Machine       │
│  ┌────────────────┐  │
│  │ Gateway        │  │
│  │ (18789)        │  │
│  └────────┬───────┘  │
│           │ WS       │
└───────────┼──────────┘
            │
    ┌───────┴────────┐
    │   Internet /   │
    │   Tailnet      │
    └───────┬────────┘
            │
    ┌───────┴──────────┐
    │  Remote Node     │
    │  (iOS/Android/   │
    │   Headless)      │
    └──────────────────┘

适用场景：

个人助理
日常使用
数据隐私优先

配置示例：

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "your-token" }
  },
  channels: {
    whatsapp: { enabled: true },
    telegram: { enabled: true }
  }
}

优点：

完全掌控数据
低延迟
无需公网暴露

缺点：

Gateway 必须持续运行
节点需要远程访问能力

部署形态 2：远程 Gateway + 本地客户端

┌──────────────────────┐
│  V** / Cloud Host    │
│  ┌────────────────┐  │
│  │ Gateway        │  │
│  │ (18789)        │  │
│  └────────┬───────┘  │
│           │ Tailscale│
└───────────┼──────────┘
            │
    ┌───────┴────────┐
    │   Tailnet      │
    └───────┬────────┘
            │
    ┌───────┴──────────┐
    │  Local Machine   │
    │  - macOS App     │
    │  - CLI           │
    │  - WebChat       │
    └──────────────────┘

适用场景：

团队共享
24/7 可用
多设备访问

配置示例（Tailscale）：

{
  gateway: {
    bind: "loopback",
    auth: { 
      mode: "token", 
      token: "${OPENCLAW_GATEWAY_TOKEN}" 
    },
    tailscale: {
      mode: "serve"
    }
  }
}

Tailscale Serve 方式（推荐）：

# 在 V** 上
tailscale serve --bg --https=443 127.0.0.1:18789

优点：

24/7 在线
多人协作
自动备份

缺点：

需要 V** 成本
网络依赖
数据在远程

部署形态 3：远程 Gateway + 本地 Node

┌──────────────────────┐
│  V** / Cloud Host    │
│  ┌────────────────┐  │
│  │ Gateway        │  │
│  │ (18789)        │  │
│  └────────┬───────┘  │
└───────────┼──────────┘
            │
    ┌───────┴────────┐
    │   Internet     │
    └───────┬────────┘
            │
    ┌───────┴──────────┐
    │  Local Node      │
    │  (macOS/Headless)│
    │  - Browser       │
    │  - exec          │
    └──────────────────┘

适用场景：

远程消息接收
本地执行能力
安全性要求高

配置示例：

{
  gateway: {
    bind: "loopback",
    auth: { mode: "token", token: "..." }
  },
  tools: {
    exec: {
      host: "node",
      node: "build-node"
    }
  }
}

Node Host 启动：

# 本地机器上运行
openclaw node run \
  --host gateway.example.com \
  --port 18789 \
  --display-name "Build Node"

优点：

Gateway 集中管理
Node 本地执行
灵活扩展

缺点：

Node 需要持续在线
配置复杂度高

部署形态 4：Docker 容器化部署

┌────────────────────────────────┐
│  Docker Host                   │
│  ┌──────────────────────────┐  │
│  │  openclaw-gateway        │  │
│  │  - Gateway (18789)       │  │
│  │  - Channels              │  │
│  └──────────────────────────┘  │
│  ┌──────────────────────────┐  │
│  │  openclaw-sandbox        │  │
│  │  - Agent execution       │  │
│  │  - Isolated workspace    │  │
│  └──────────────────────────┘  │
└────────────────────────────────┘

快速启动：

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 运行设置脚本
./docker-setup.sh

环境变量：

# 使用预构建镜像
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

# 启用沙箱
export OPENCLAW_SANDBOX=1

# 持久化 home 目录
export OPENCLAW_HOME_VOLUME="openclaw_home"

优点：

环境隔离
易于部署
可移植性强

缺点：

性能开销
调试复杂
存储管理

图 6：四种部署形态对比

9. 生产环境最佳实践

远程访问方案

推荐方案：Tailscale

{
  gateway: {
    bind: "loopback",
    tailscale: {
      mode: "serve",
      serve: {
        enabled: true,
        tls: "auto"
      }
    },
    auth: {
      allowTailscale: true  // 允许 Tailscale 身份认证
    }
  }
}

优点：

无需 SSH 隧道
自动 TLS
身份感知
零信任网络

缺点：

需要 Tailscale 账号
依赖第三方服务

备选方案：SSH 隧道

# 持久化隧道（autossh）
autossh -M 0 -f -N \
  -L 18789:127.0.0.1:18789 \
  -o ServerAliveInterval=60 \
  -o ServerAliveCountMax=3 \
  user@gateway-host

配置热重载

Gateway 支持配置热重载，大部分配置修改不需要重启：

{
  gateway: {
    reload: {
      mode: "hybrid",      // hot | hybrid | restart | off
      debounceMs: 300      // 防抖延迟
    }
  }
}

热重载支持范围：

类别	字段	需要重启?
Channels	channels.*	❌
Agent & models	agent, agents, models	❌
Automation	hooks, cron, heartbeat	❌
Sessions & messages	session, messages	❌
Tools & media	tools, browser, skills	❌
UI & misc	ui, logging, bindings	❌
Gateway server	gateway.port, gateway.bind, gateway.auth	✅
Infrastructure	discovery, canvasHost, plugins	✅

最佳实践：

开发环境：使用 mode: "hot"

{
  gateway: {
    reload: { mode: "hot" }
  }
}

生产环境：使用 mode: "hybrid"（默认）

{
  gateway: {
    reload: { mode: "hybrid" }
  }
}

配置变更流程：

# 1. 编辑配置
vim ~/.openclaw/openclaw.json

# 2. 验证配置
openclaw doctor

# 3. 应用配置（hybrid 模式自动重启）
# 或手动重启
openclaw gateway restart

监控与健康检查

健康检查端点：

# 存活检查
curl http://127.0.0.1:18789/healthz

# 就绪检查
curl http://127.0.0.1:18789/readyz

# 深度健康检查
openclaw health --token "$OPENCLAW_GATEWAY_TOKEN"

日志管理：

{
  logging: {
    level: "info",
    redactSensitive: true,
    file: {
      enabled: true,
      path: "/tmp/openclaw/gateway.log",
      maxSizeBytes: "10mb",
      maxFiles: 5
    }
  }
}

告警配置：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        onMissed: "alert"  // 错过心跳时告警
      }
    }
  }
}

常见问题排查：

# Gateway 启动失败
lsof -i :18789           # 检查端口占用
openclaw doctor          # 检查配置
openclaw logs --follow   # 查看日志

# Node 连接断开
ping gateway-host        # 检查网络
openclaw devices list    # 检查认证
env | grep OPENCLAW_GATEWAY  # 检查 token

# 消息发送失败
openclaw channels status  # 检查通道状态
openclaw pairing list <channel>  # 检查权限
tail -f ~/.openclaw/logs/gateway.log  # 检查日志

# 性能下降
docker stats  # Docker 部署
top           # 本地部署
openclaw sessions list  # 检查会话数
openclaw sessions prune --older-than 7d  # 清理旧会话

10. 总结

OpenClaw Gateway 的设计有几个值得借鉴的地方：

统一的 WebSocket 协议：所有客户端和节点用同一套协议通信，简化了架构，实现了控制平面和节点传输的统一。

三层认证机制：Gateway Token、Device Identity、Pairing Approval 三层防护，既保证了安全性，又通过本地自动审批保持了良好的用户体验。这种平衡很难得。

能力驱动的插件架构：通过 Capabilities 声明，核心消息处理逻辑可以动态适应不同通道的特性，实现了高度解耦。添加新的消息通道，只需要实现一个插件，不需要修改核心代码。

灵活的部署形态：从本地单机到云端多租户，从 SSH 隧道到 Tailscale 零信任网络，OpenClaw 提供了完整的部署方案，适应各种场景。

生产级安全隔离：基于 Docker 的沙箱、工具策略、权限控制的三重隔离，为企业级部署提供了安全保障。

Canvas Host 的 Agent-Editable 设计：允许 Agent 动态生成和修改 HTML/CSS/JS，结合 A2UI 协议，为 AI Agent 提供了强大的 UI 能力。这是个很有想象力的设计。

如果你正在设计一个 Agent 系统，或者对 AI Agent 平台的架构感兴趣，OpenClaw Gateway 的设计值得深入研究。

相关资源

OpenClaw 官方文档：https://docs.openclaw.ai/

Gateway Protocol 规范：https://docs.openclaw.ai/gateway/protocol

Channel Plugin 开发指南：https://docs.openclaw.ai/tools/plugin

Docker 部署文档：https://docs.openclaw.ai/install/docker

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待！

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2026-03-10，如有侵权请联系 cloudcommunity@tencent.com 删除

架构

本文分享自运维有术微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！