openclaw的gateway详解

1. Gateway 在 OpenClaw 里的定位

OpenClaw 不是单纯的"LLM API 代理"，而是一个运行在你设备/服务器上的个人 AI 助手系统。官方 README 里把 Gateway 描述为 control plane，产品主体是跨渠道运行的 assistant：它可以接 WhatsApp、Telegram、Slack、Discord、iMessage、Matrix、Teams、WebChat 等渠道。([GitHub][1])

可以把 Gateway 理解成 OpenClaw 的"大脑中枢 + 交通枢纽"：

text 复制代码

Telegram / WhatsApp / Slack / WebChat / CLI
                │
                ▼
        OpenClaw Gateway
  ┌─────────────────────────┐
  │ 认证 / 配对 / 权限        │
  │ 渠道路由 / 会话管理        │
  │ Agent 运行 / 模型调用      │
  │ 工具调用 / 节点调用        │
  │ 配置 / 日志 / 健康检查     │
  └─────────────────────────┘
                │
      ┌─────────┴─────────┐
      ▼                   ▼
 LLM Providers        Nodes
 OpenAI/Anthropic     iOS/Android/macOS
 Gemini/OpenRouter    camera/screen/canvas

它负责接收渠道消息、选择对应 agent/session、调用模型和工具、再把结果投递回原渠道。官方远程访问文档给了一个典型链路：Telegram 消息到 Gateway，Gateway 运行智能体，必要时通过 WebSocket 调用节点工具，节点返回结果后 Gateway 再发回 Telegram。([OpenClaw][2])

2. Runtime 模型：一个常驻进程，一个复用端口

Gateway 是一个 always-on process 。它同时承担路由、控制平面、渠道连接等职责，而且默认使用一个复用端口。这个端口同时服务 WebSocket 控制/RPC、OpenAI 兼容 HTTP API、Control UI、hooks 等能力。默认绑定模式是 loopback，默认需要认证。([OpenClaw][3])

默认启动端口是 18789，端口解析顺序是：

text 复制代码

--port
→ OPENCLAW_GATEWAY_PORT
→ gateway.port
→ 18789

绑定模式解析顺序是：

text 复制代码

CLI / override
→ gateway.bind
→ loopback

这意味着你本地直接跑通常就是 127.0.0.1:18789，不要默认把它暴露到公网。([OpenClaw][3])

启动和检查常用命令：

bash 复制代码

openclaw gateway --port 18789

# 调试输出到 stdio
openclaw gateway --port 18789 --verbose

# 强制清掉占用端口的监听器再启动
openclaw gateway --force

# 状态检查
openclaw gateway status
openclaw status
openclaw logs --follow

# 渠道探测
openclaw channels status --probe

健康基线一般看 Runtime: running 和 RPC probe: ok；渠道检查则用 openclaw channels status --probe 做逐账号实时探测。([OpenClaw][3])

3. Gateway 对外暴露两类核心接口

A. WebSocket 控制平面协议

Gateway 的 WS 协议是 OpenClaw 的 单一控制平面 + 节点传输协议 。CLI、Web UI、macOS app、iOS/Android 节点、headless node 都通过 WebSocket 连接，并在握手时声明角色和作用域。传输层是 WebSocket，文本帧里放 JSON payload，第一帧必须是 connect。([OpenClaw][4])

握手大致是这样：

json 复制代码

{
  "type": "req",
  "id": "...",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "auth": { "token": "..." }
  }
}

成功后 Gateway 返回 hello-ok，里面包含协议版本、策略信息，必要时还会签发 deviceToken。([OpenClaw][4])

WS 帧主要有三种：

text 复制代码

请求：{ type: "req", id, method, params }
响应：{ type: "res", id, ok, payload | error }
事件：{ type: "event", event, payload, seq?, stateVersion? }

有副作用的方法需要幂等键。([OpenClaw][4])

角色主要分两类：

text 复制代码

operator = 控制平面客户端，比如 CLI / UI / 自动化
node     = 能力宿主，比如 camera / screen / canvas / system.run

node 在连接时声明 caps、commands、permissions，Gateway 会把这些视为能力声明，并在服务端强制执行允许列表。([OpenClaw][4])

B. OpenAI 兼容 HTTP API

Gateway 还暴露一组 OpenAI 兼容端点：

text 复制代码

GET  /v1/models
GET  /v1/models/{id}
POST /v1/embeddings
POST /v1/chat/completions
POST /v1/responses
POST /tools/invoke

这些接口运行在主 Gateway 端口上，和 Gateway 其他 HTTP API 共享同一认证边界。/v1/models 是 agent-first 设计，会返回 openclaw、openclaw/default 和 openclaw/<agentId>；openclaw/default 是稳定别名，指向当前默认 agent。需要覆盖后端模型时可以用 x-openclaw-model。([OpenClaw][3])

这意味着你可以把 Open WebUI、LobeChat、LibreChat 等支持 OpenAI API 的前端接到 OpenClaw Gateway 上，但语义上它不是简单"转发到 OpenAI"，而是把请求路由到 OpenClaw 的 agent/session/model/tool 体系里。

4. 请求链路怎么走

一个典型消息链路可以拆成 7 步：

text 复制代码

1. 渠道收到消息
   例如 Telegram / WhatsApp / WebChat / Slack

2. Gateway 做入口校验
   包括认证、配对、allowlist、dmPolicy、groupPolicy、mentionPatterns

3. Gateway 解析路由
   判断 channel/account/peer/group/thread 对应哪个 agent、哪个 session

4. Agent runner 启动或复用会话
   加载 workspace、system prompt、skills、memory、model 配置

5. 调用模型和工具
   可能调用 provider API、browser、skills、local exec、node.invoke 等

6. 如果需要设备能力，Gateway 调 node
   比如 iOS/macOS 节点上的 camera、screen、canvas、location、system.run

7. Gateway 将结果投递回原渠道
   或者只写入 session，不外发

OpenClaw 的配置支持多 agent 路由，例如 home 和 work 两个 agent 各有独立 workspace，并通过 bindings 把不同 WhatsApp 账号路由到不同 agent。([OpenClaw][5])

5. 配置系统

主配置文件默认是：

bash 复制代码

~/.openclaw/openclaw.json

它是 JSON5 配置；如果文件不存在，OpenClaw 会使用安全默认值。常见配置用途包括：连接渠道、控制谁能给 bot 发消息、设置模型/工具/沙箱/cron/hooks、调整会话/媒体/网络/UI 等。([OpenClaw][5])

最小配置示例：

js 复制代码

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

官方示例里 agents.defaults.workspace 是 agent 默认工作目录，channels.whatsapp.allowFrom 控制允许的 WhatsApp 发送方。([OpenClaw][5])

配置可以通过四种方式改：

bash 复制代码

openclaw onboard
openclaw configure

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

也可以直接编辑 ~/.openclaw/openclaw.json，或者打开本地 Control UI 的 Config 标签页。Gateway 会基于实时 schema 渲染配置表单，并暴露 config.schema.lookup 给下钻式 UI/工具使用。([OpenClaw][5])

OpenClaw 的配置校验比较严格：未知键、类型错误、无效值都会导致 Gateway 拒绝启动；出问题时主要用 openclaw doctor 定位，并可用 openclaw doctor --fix 尝试修复。([OpenClaw][5])

6. 热重载机制

Gateway 会监视配置文件并自动应用变更。默认重载模式是 hybrid：

js 复制代码

{
  gateway: {
    reload: {
      mode: "hybrid",
      debounceMs: 300
    }
  }
}

四种模式含义：

text 复制代码

hybrid  默认。安全变更热应用，关键变更自动重启
hot     只热应用安全变更，需要重启时仅记录警告
restart 任意配置变更都重启 Gateway
off     禁用文件监视，下次手动重启生效

大多数字段可以热应用，比如 channels.*、agents、models、hooks、cron、session、tools、skills、ui、bindings 等；但 gateway.* 中的 port、bind、auth、TLS、HTTP，以及 discovery、canvasHost、plugins 等基础设施项需要重启。([OpenClaw][5])

7. 认证与权限模型

Gateway 默认要求认证。共享密钥可以放在：

text 复制代码

gateway.auth.token
gateway.auth.password
OPENCLAW_GATEWAY_TOKEN
OPENCLAW_GATEWAY_PASSWORD

非 loopback 的身份感知反向代理可以使用 gateway.auth.mode: "trusted-proxy"。([OpenClaw][3])

WS 协议里，认证可以通过 connect.params.auth.token 或 connect.params.auth.password 完成；Tailscale Serve 或 trusted-proxy 这类身份模式则通过请求头满足认证检查。gateway.auth.mode: "none" 会跳过共享密钥认证，官方明确提示不要把它暴露在公共或不受信任入口。([OpenClaw][4])

成功配对后，Gateway 会签发设备令牌，令牌绑定到该连接的角色和作用域。后续连接可以复用 device token；令牌也可以通过 device.token.rotate 和 device.token.revoke 轮换/撤销。([OpenClaw][4])

权限上，operator 常见 scope 包括：

text 复制代码

operator.read
operator.write
operator.admin
operator.approvals
operator.pairing
operator.talk.secrets

一些关键操作会强制更高权限。例如 config.*、exec.approvals.*、wizard.*、update.* 等核心管理员前缀解析为 operator.admin；system.run 相关 node 配对审批也需要更严格的 scope 组合。([OpenClaw][4])

8. 远程访问：推荐 SSH / Tailscale，不推荐裸露端口

官方推荐的远程模式是：Gateway 运行在一台持续在线的主机上，客户端通过 SSH 隧道或 tailnet/VPN 连接。默认 Gateway WebSocket 绑定到 loopback，远程使用时通过 SSH 转发本地端口，或者用 Tailscale/VPN 减少隧道需求。([OpenClaw][2])

SSH 隧道示例：

bash 复制代码

ssh -N -L 18789:127.0.0.1:18789 user@host

建立隧道后，本机 CLI 可以通过 ws://127.0.0.1:18789 访问远程 Gateway；如果用 --url 指向转发后的 URL，CLI 不会自动复用隐式配置/环境凭证，需要显式传 --token 或 --password。([OpenClaw][2])

远程默认配置可以这样写：

js 复制代码

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token"
    }
  }
}

当 Gateway 只绑定 loopback 时，URL 保持 ws://127.0.0.1:18789，先建立 SSH 隧道。([OpenClaw][2])

安全原则：

text 复制代码

优先：loopback + SSH / Tailscale Serve
谨慎：lan / tailnet / custom bind
避免：公网裸露 + 弱密码 / 无认证

官方远程访问安全规则明确建议：保持 Gateway 只绑定 loopback，除非你确定需要非 loopback 绑定；非 loopback 绑定必须使用 gateway 认证 token/password，或 trusted-proxy 身份感知反向代理。([OpenClaw][2])

9. 多 Gateway：一般不需要

大多数场景每台机器只跑一个 Gateway。单个 Gateway 可以托管多个 agent 和渠道。只有需要严格隔离、冗余、救援配置时，才建议同主机多 Gateway。([OpenClaw][3])

如果确实要跑多个实例，需要隔离这些东西：

text 复制代码

唯一 gateway.port
唯一 OPENCLAW_CONFIG_PATH
唯一 OPENCLAW_STATE_DIR
唯一 agents.defaults.workspace

示例：

bash 复制代码

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

OPENCLAW_CONFIG_PATH=~/.openclaw/b.json \
OPENCLAW_STATE_DIR=~/.openclaw-b \
openclaw gateway --port 19002

如果多个 Gateway 同时响应，openclaw gateway probe 可能会警告 multiple reachable gateways。([OpenClaw][3])

10. 常见排障路径

先跑这一组：

bash 复制代码

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

官方排障手册建议按这个顺序检查；正常信号包括 openclaw gateway status 显示 Runtime: running 和 RPC probe: ok，doctor 没有阻塞性配置/服务问题，channels status --probe 显示逐账号传输状态和探测结果。([OpenClaw][6])

常见故障对照：

现象	可能原因	处理方向
`EADDRINUSE` / already listening	端口被占用或已有 Gateway	换端口、停止旧进程、`gateway status --deep`
`unauthorized`	token/password/device token 不匹配	检查 `gateway.auth.*`、环境变量、远程 token
Dashboard 连接不上	URL、Origin、设备身份、认证模式问题	查 `gateway.controlUi.allowedOrigins`、device auth、日志
渠道在线但没回复	配对、allowlist、群提及门控、路由不匹配	查 `pairing list`、`channels` 配置、日志
配置改完 Gateway 起不来	schema 校验失败	`openclaw doctor` / `doctor --fix`

官方故障排除页特别提到：没有回复时要先检查配对、群组 mention gate、渠道/群组 allowlist；日志里 drop guild message (mention required) 表示群消息需要提及，pairing request 表示发送者需要批准，blocked / allowlist 表示被策略过滤。([OpenClaw][6])

11. 总结

OpenClaw Gateway 是整个 OpenClaw 系统的常驻控制面、消息路由器、Agent 运行入口、OpenAI-compatible API server、设备节点调度器和运维面板后端。

它不是只做：

text 复制代码

HTTP 请求 → LLM provider → 返回

而是做：

text 复制代码

多渠道消息
→ 身份/权限/配对
→ agent/session 路由
→ 模型/工具/技能/节点调用
→ 状态/日志/健康/配置管理
→ 多渠道投递

实际部署建议：

text 复制代码

本机开发：openclaw gateway --port 18789 --verbose
长期运行：openclaw onboard --install-daemon
远程访问：loopback + SSH tunnel / Tailscale
生产安全：强 token、不开 auth none、不裸露公网、最小化 node 权限
多用户/多场景：用 multi-agent + bindings，不要随便开多个 Gateway

参考链接：

1\]: https://github.com/openclaw/openclaw "GitHub - openclaw/openclaw: Your own personal AI assistant. Any OS. Any Platform. The lobster way. · GitHub" \[2\]: https://docs.openclaw.ai/zh-CN/gateway/remote "远程访问 - OpenClaw" \[3\]: https://docs.openclaw.ai/zh-CN/gateway "Gateway 网关运行手册 - OpenClaw" \[4\]: https://docs.openclaw.ai/zh-CN/gateway/protocol "Gateway 网关协议 - OpenClaw" \[5\]: https://docs.openclaw.ai/zh-CN/gateway/configuration "Configuration - OpenClaw" \[6\]: https://docs.openclaw.ai/zh-CN/gateway/troubleshooting "故障排除 - OpenClaw"