首页网关与运维
网关与运维

OpenClaw 网关

统一的 API 网关,提供认证、路由、限流和监控功能,让你的 AI 智能体安全可靠地对外服务

Gateway 网关服务运行手册

最后更新:2025-12-09

是什么

  • 拥有单一 Baileys/Telegram 连接和控制/事件平面的常驻进程。
  • 替代旧版 gateway 命令。CLI 入口点:openclaw gateway。
  • 运行直到停止;出现致命错误时以非零退出码退出,以便 supervisor 重启它。

如何运行(本地)

bash
openclaw gateway --port 18789
# 在 stdio 中获取完整的调试/追踪日志:
openclaw gateway --port 18789 --verbose
# 如果端口被占用,终止监听器然后启动:
openclaw gateway --force
# 开发循环(TS 更改时自动重载):
pnpm gateway:watch
  • 配置热重载监视 ~/.openclaw/openclaw.json(或 OPENCLAW_CONFIG_PATH)。
    • 默认模式:gateway.reload.mode="hybrid"(热应用安全更改,关键更改时重启)。
    • 热重载在需要时通过 SIGUSR1 使用进程内重启。
    • 使用 gateway.reload.mode="off" 禁用。
  • 将 WebSocket 控制平面绑定到 127.0.0.1:<port>(默认 18789)。
  • 同一端口也提供 HTTP 服务(控制界面、hooks、A2UI)。单端口多路复用。
    • OpenAI Chat Completions(HTTP):/v1/chat/completions
    • OpenResponses(HTTP):/v1/responses
    • Tools Invoke(HTTP):/tools/invoke
  • 默认在 canvasHost.port(默认 18793)上启动 Canvas 文件服务器,从 ~/.openclaw/workspace/canvas 提供 http://<gateway-host>:18793/__openclaw__/canvas/。使用 canvasHost.enabled=false 或 OPENCLAW_SKIP_CANVAS_HOST=1 禁用。
  • 输出日志到 stdout;使用 launchd/systemd 保持运行并轮转日志。
  • 故障排除时传递 --verbose 以将调试日志(握手、请求/响应、事件)从日志文件镜像到 stdio。
  • --force 使用 lsof 查找所选端口上的监听器,发送 SIGTERM,记录它终止了什么,然后启动 Gateway 网关(如果缺少 lsof 则快速失败)。
  • 如果你在 supervisor(launchd/systemd/mac 应用子进程模式)下运行,stop/restart 通常发送 SIGTERM;旧版本可能将其显示为 pnpm ELIFECYCLE 退出码 143(SIGTERM),这是正常关闭,不是崩溃。
  • SIGUSR1 在授权时触发进程内重启(Gateway 网关工具/配置应用/更新,或启用 commands.restart 以进行手动重启)。
  • 默认需要 Gateway 网关认证:设置 gateway.auth.token(或 OPENCLAW_GATEWAY_TOKEN)或 gateway.auth.password。客户端必须发送 connect.params.auth.token/password,除非使用 Tailscale Serve 身份。
  • 向导现在默认生成令牌,即使在 loopback 上也是如此。
  • 端口优先级:--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789。

远程访问

  • 首选 Tailscale/VPN;否则使用 SSH 隧道:
bash
ssh -N -L 18789:127.0.0.1:18789 user@host
  • 然后客户端通过隧道连接到 ws://127.0.0.1:18789。
  • 如果配置了令牌,即使通过隧道,客户端也必须在 connect.params.auth.token 中包含它。

多个 Gateway 网关(同一主机)

通常不需要:一个 Gateway 网关可以服务多个消息渠道和智能体。仅在需要冗余或严格隔离(例如:救援机器人)时使用多个 Gateway 网关。

如果你隔离状态 + 配置并使用唯一端口,则支持。完整指南:多个 Gateway 网关。

服务名称

服务名称是配置文件感知的:

  • macOS:bot.molt.<profile>(旧版 com.openclaw.* 可能仍然存在)
  • Linux:openclaw-gateway-<profile>.service
  • Windows:OpenClaw Gateway (<profile>)

安装元数据

安装元数据嵌入在服务配置中:

  • OPENCLAW_SERVICE_MARKER=openclaw
  • OPENCLAW_SERVICE_KIND=gateway
  • OPENCLAW_SERVICE_VERSION=<version>

救援机器人模式:保持第二个 Gateway 网关隔离,使用自己的配置文件、状态目录、工作区和基础端口间隔。完整指南:救援机器人指南。

Dev 配置文件(--dev)

快速路径:运行完全隔离的 dev 实例(配置/状态/工作区)而不触及你的主设置。

bash
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# 然后定位到 dev 实例:
openclaw --dev status
openclaw --dev health

默认值(可通过 env/flags/config 覆盖):

  • OPENCLAW_STATE_DIR=~/.openclaw-dev
  • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
  • OPENCLAW_GATEWAY_PORT=19001(Gateway 网关 WS + HTTP)
  • 浏览器控制服务端口 = 19003(派生:gateway.port+2,仅 loopback)
  • canvasHost.port=19005(派生:gateway.port+4)
  • 当你在 --dev 下运行 setup/onboard 时,agents.defaults.workspace 默认变为 ~/.openclaw/workspace-dev。

派生端口(经验法则)

  • 基础端口 = gateway.port(或 OPENCLAW_GATEWAY_PORT / --port)
  • 浏览器控制服务端口 = 基础 + 2(仅 loopback)
  • canvasHost.port = 基础 + 4(或 OPENCLAW_CANVAS_HOST_PORT / 配置覆盖)
  • 浏览器配置文件 CDP 端口从 browser.controlPort + 9 .. + 108 自动分配(按配置文件持久化)。

每个实例的检查清单

  • 唯一的 gateway.port
  • 唯一的 OPENCLAW_CONFIG_PATH
  • 唯一的 OPENCLAW_STATE_DIR
  • 唯一的 agents.defaults.workspace
  • 单独的 WhatsApp 号码(如果使用 WA)

按配置文件安装服务:

bash
openclaw --profile main gateway install
openclaw --profile rescue gateway install

示例:

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 网关协议 和 Bridge 协议(旧版)。
  • 客户端必须发送的第一帧:req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }。
  • Gateway 网关回复 res {type:"res", id, ok:true, payload:hello-ok }(或 ok:false 带错误,然后关闭)。
  • 握手后:
    • 请求:{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • 事件:{type:"event", event, payload, seq?, stateVersion?}
  • 结构化 presence 条目:{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }(对于 WS 客户端,instanceId 来自 connect.client.instanceId)。
  • agent 响应是两阶段的:首先 res 确认 {runId,status:"accepted"},然后在运行完成后发送最终 res {runId,status:"ok"|"error",summary};流式输出作为 event:"agent" 到达。

方法(初始集)

health

完整健康快照(与 openclaw health --json 形状相同)

status

简短摘要

system-presence

当前 presence 列表

system-event

发布 presence/系统注释(结构化)

send

通过活跃渠道发送消息

agent

运行智能体轮次(在同一连接上流回事件)

node.list

列出已配对 + 当前连接的节点

node.describe

描述节点(能力 + 支持的命令)

node.invoke

在节点上调用命令(例如 canvas.*、camera.*)

node.pair.*

配对生命周期(request、list、approve、reject、verify)

另见:Presence 了解 presence 如何产生/去重以及为什么稳定的 client.instanceId 很重要。

事件

  • agent — 来自智能体运行的流式工具/输出事件(带 seq 标记)。
  • presence — presence 更新(带 stateVersion 的增量)推送到所有连接的客户端。
  • tick — 定期保活/无操作以确认活跃。
  • shutdown — Gateway 网关正在退出;payload 包括 reason 和可选的 restartExpectedMs。客户端应重新连接。

WebChat 集成

  • WebChat 是原生 SwiftUI UI,直接与 Gateway 网关 WebSocket 通信以获取历史记录、发送、中止和事件。
  • 远程使用通过相同的 SSH/Tailscale 隧道;如果配置了 Gateway 网关令牌,客户端在 connect 期间包含它。
  • macOS 应用通过单个 WS 连接(共享连接);它从初始快照填充 presence 并监听 presence 事件以更新 UI。

Gateway 网关服务管理(CLI)

使用 Gateway 网关 CLI 进行 install/start/stop/restart/status:

bash
openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow
注意事项
  • gateway status 默认使用服务解析的端口/配置探测 Gateway 网关 RPC(使用 --url 覆盖)。
  • gateway status --deep 添加系统级扫描(LaunchDaemons/系统单元)。
  • gateway status --no-probe 跳过 RPC 探测(在网络故障时有用)。
  • gateway status --json 对脚本是稳定的。

下一步

配置

了解如何配置网关的各项参数

认证

配置认证方式和权限控制

安全

学习网关的安全最佳实践

日志

配置和查看网关日志

Talk with Us