Skip to main content

1. OpenClaw Gateway（网关）运行手册

Gateway（网关）是 OpenClaw 的常驻进程：它负责维护各消息渠道连接、承载控制与事件平面，并作为会话、路由与渠道状态的统一入口。简单理解：你能不能“连上 OpenClaw”、控制台能不能打开、消息能不能进来，很多时候就看 Gateway 是否在正常运行。

1. OpenClaw Gateway（网关）运行手册1. 什么时候需要关心网关2. 最快启动方式（本地）3. 网关提供了哪些“对外接口”4. 热重载与“需要重启”的更改5. 认证与远程访问（最容易踩坑）5.1 网关认证（token/password）5.2 远程访问的推荐方式：先隧道再访问5.3 控制台通过纯 HTTP 打不开（device identity required）6. 多实例与“救援机器人”模式7. 排错顺序，基本都能定位7.1 先看状态7.2 网关起不来：配置校验失败7.3 常见现象：服务已安装但实际没跑

1. 什么时候需要关心网关​

大多数情况下，你只需要让它稳定运行即可；仅在下面这些场景需要专门检查/学习网关：

  • Jetson 上用浏览器打开控制台经常报错，准备改用 TUI 或远程访问
  • 配置改了但“感觉没生效”，怀疑热重载/重启没有触发
  • 想把控制台开放给局域网或通过 SSH/Tailscale 远程访问
  • 想做多实例隔离（例如“救援机器人”/冗余）
  • 端口冲突、进程起不来、服务“看起来已安装但没有在跑”

2. 最快启动方式（本地）​

在网关主机（例如 Jetson）上执行：

xxxxxxxxxx openclaw gateway

常用参数：

​ x # 打印更完整的调试/追踪信息到当前终端（便于排查） openclaw gateway \--port 18789 \--verbose ​ # 端口被占用时，尝试终止占用端口的监听器并强制启动 openclaw gateway \--port 18789 \--force

端口优先级（从高到低）：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789。

3. 网关提供了哪些“对外接口”​

同一个端口（默认 18789）会同时提供 WebSocket 控制平面和 HTTP 服务（控制界面、hooks、A2UI 等），属于“单端口多路复用”。

你常见会用到的点：

  • 本地控制台：http://127.0.0.1:18789/
  • OpenAI Chat Completions 兼容接口：/v1/chat/completions
  • OpenResponses 接口：/v1/responses
  • 工具调用接口：/tools/invoke

另外，网关默认还会启动 Canvas 静态文件服务（默认端口 18793），用于提供可编辑的 HTML/A2UI 资源（默认从 ~/.openclaw/workspace/canvas 提供）。需要禁用可设置 canvasHost.enabled=false 或 OPENCLAW_SKIP_CANVAS_HOST=1。

4. 热重载与“需要重启”的更改​

网关会监视 ~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH 指定路径），配置更新通常会自动应用 。默认重载模式为 gateway.reload.mode="hybrid"：安全更改热应用，关键更改会触发重启。

你可以显式配置重载行为：

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

经验建议：

  • 改模型、智能体、路由等业务配置，通常不需要你手动重启
  • 改 gateway.*（端口、绑定、认证、TLS、HTTP 等）属于基础设施更改，更容易触发重启

5. 认证与远程访问（最容易踩坑）​

5.1 网关认证（token/password）​

网关默认启用认证：可以设置 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）或 gateway.auth.password。客户端连接时需要在 connect.params.auth.token/password 中携带。

如果你使用向导流程，通常会默认生成 token（即使只绑定在 loopback 上）。

5.2 远程访问的推荐方式：先隧道再访问​

最推荐：Tailscale/VPN。其次：SSH 隧道。

示例（把远端 18789 映射到本机 18789）：

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

然后你在本机访问：

  • Web：http://127.0.0.1:18789/
  • WS：ws://127.0.0.1:18789

注意：即使走隧道，如果网关配置了 token，客户端仍然要带 token 才能连上。

5.3 控制台通过纯 HTTP 打不开（device identity required）​

如果你在局域网用 http://<lan-ip>:18789/ 打开控制台，浏览器可能处于非安全上下文，导致 WebCrypto 受限，从而无法生成设备身份，出现 device identity required / connect failed。[^gateway_troubleshooting]

优先修复路线：

  • 本机打开：http://127.0.0.1:18789/
  • 远程场景用 Tailscale Serve 提供 HTTPS
  • 必须用 HTTP 时，开启 gateway.controlUi.allowInsecureAuth: true 并使用网关 token（仅 token 模式，不走设备身份/配对）[^gateway_troubleshooting]

6. 多实例与“救援机器人”模式​

仅在需要时再尝试此操作

通常一台主机只跑一个网关就够了；只有在需要冗余或强隔离（例如救援机器人）时，才建议跑多个网关实例。

多实例的核心原则是“全隔离 + 不冲突”：

  • 不同的 gateway.port
  • 不同的 OPENCLAW_CONFIG_PATH
  • 不同的 OPENCLAW_STATE_DIR
  • 不同的工作区（agents.defaults.workspace）

在 dev 配置文件下，你可以快速启动一个完全隔离的开发实例，不影响主环境：

xxxxxxxxxx openclaw \--dev setup openclaw \--dev gateway \--allow-unconfigured openclaw \--dev status openclaw \--dev health

7. 排错顺序，基本都能定位​

7.1 先看状态​

按顺序执行：[^gateway_troubleshooting]

xxxxxxxxxx openclaw status openclaw status \--all openclaw status \--deep

常用补充命令：

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

7.2 网关起不来：配置校验失败​

OpenClaw 配置是严格 schema 校验：未知键、类型错误或无效值都可能导致网关拒绝启动。

当校验失败时通常只有诊断类命令可用（例如 openclaw doctor / logs / health / status）。建议直接：

xxxxxxxxxx openclaw doctor

7.3 常见现象：服务已安装但实际没跑​

如果你用 systemd/launchd/schtasks 等把网关装成服务，显示“已加载/已安装”不等于进程在运行。优先看：[^gateway_troubleshooting]

openclaw gateway status openclaw logs \--follow