Web

Gateway 在与 Gateway WebSocket 相同的端口上提供轻量级的浏览器 Control UI（Vite + Lit）：

• 默认：http://<host>:18789/
• 启用 gateway.tls.enabled: true 时：https://<host>:18789/
• 可选前缀：设置 gateway.controlUi.basePath（例如 /openclaw）

具体功能见 Control UI。本页介绍绑定模式、安全性及其他面向 Web 的接口。

配置（默认开启）¶

当资源存在（dist/control-ui）时，Control UI 默认启用：

{
  gateway: {
    controlUi: { enabled: true, basePath: "/openclaw" }, // basePath optional
  },
}

Webhooks¶

当 hooks.enabled=true 时，Gateway 还会在同一 HTTP 服务器上暴露一个 webhook 端点。认证与负载格式请参阅 Gateway 配置参考中的 hooks。

Admin HTTP RPC¶

POST /api/v1/admin/rpc 通过 HTTP 暴露选定的 Gateway 控制面（control-plane）方法。默认关闭；仅当启用了 admin-http-rpc 插件时才会注册。认证模型、允许的方法以及与 WebSocket API 的对比，请参阅 Admin HTTP RPC。

Tailscale 访问¶

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

openclaw gateway

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password" }, // or OPENCLAW_GATEWAY_PASSWORD
  },
}

安全说明¶

• 默认需要 Gateway 认证：token、password、trusted-proxy，或启用时的 Tailscale Serve 身份头。
• 非 loopback 绑定仍然需要 Gateway 认证：token/password 认证，或带有 gateway.auth.mode: "trusted-proxy" 的能识别身份的反向代理。
• 本地引导流程默认以 token 模式生成 Gateway secret，即使在 loopback 上也是如此，不会询问 token 还是 password。现有 password 模式会被保留；--gateway-auth password 或 --gateway-password <value> 可显式选择该模式。Funnel 仍然要求 password 模式。
• UI 使用一个 Gateway secret 字段。Gateway 接受 connect.params.auth.token 或 connect.params.auth.password 中的 secret；gateway.auth.mode 决定使用哪个已配置值。成功建立 token 模式连接后，UI 会将 secret 保存在仅限当前浏览器标签页和当前 Gateway 的会话存储（session storage）中。Password 仅保存在内存中，从不持久化。
• 启用 gateway.tls.enabled: true 时，本地仪表板/状态辅助工具会渲染 https:// URL 和 wss:// WebSocket URL。
• 在带有身份信息的模式（Tailscale Serve、trusted-proxy）中，WebSocket 认证检查通过请求头满足，而无需共享 secret。
• 对于公开的非 loopback Control UI 部署，请显式设置 gateway.controlUi.allowedOrigins（完整来源）。对于 loopback、RFC1918/链路本地、.local、.ts.net 和 Tailscale CGNAT 主机，私有同源加载无需该设置即可被接受。
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback: true 会启用 Host 头来源回退；这是一种危险的安全降级。
• 使用 Serve 时，当 gateway.auth.allowTailscale: true，Tailscale 身份头可满足 Control UI/WebSocket 认证（无需 token/password）。HTTP API 端点不使用 Tailscale 身份头；它们始终遵循 Gateway 的正常 HTTP 认证模式。设置 gateway.auth.allowTailscale: false 可在 Serve 下也要求显式凭据。这种无 token 流程假设 Gateway 主机本身是可信的。参见 Tailscale 与 安全。

构建 UI¶

Gateway 从 dist/control-ui 提供静态文件：

pnpm ui:build