OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Web 界面

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 默认启用：

json5
{  gateway: {    controlUi: { enabled: true, basePath: "/openclaw" }, // basePath 可选  },}

Webhooks

当 hooks.enabled=true 时，Gateway 网关还会在同一 HTTP 服务器上公开一个 webhook 端点。有关身份验证和载荷的信息，请参阅 Gateway 配置参考中的 hooks。

管理 HTTP RPC

POST /api/v1/admin/rpc 通过 HTTP 公开部分 Gateway 网关控制平面方法。默认关闭；仅在启用 admin-http-rpc 插件时注册。有关身份验证模型、允许的方法以及与 WebSocket API 的比较，请参阅管理 HTTP RPC。

Tailscale 访问

集成式 Serve（推荐）

让 Gateway 网关保持在环回地址上，并由 Tailscale Serve 进行代理：

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

启动 Gateway 网关：

bash
openclaw gateway

打开 https://<magicdns>/（或你配置的 gateway.controlUi.basePath）。

Tailnet 绑定 + 令牌

json5
{  gateway: {    bind: "tailnet",    controlUi: { enabled: true },    auth: { mode: "token", token: "your-token" },  },}

启动 Gateway 网关（此非环回示例使用共享密钥令牌身份验证）：

bash
openclaw gateway

打开 http://<tailscale-ip>:18789/（或你配置的 gateway.controlUi.basePath）。

公共互联网（Funnel）

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

tailscale.mode: "funnel" 需要 gateway.auth.mode: "password"；Serve 和 Funnel 都需要 gateway.bind: "loopback"。

安全注意事项

  • 默认需要 Gateway 网关身份验证：令牌、密码、可信代理，或启用时的 Tailscale Serve 身份标头。
  • 非环回绑定仍然需要 Gateway 网关身份验证：令牌/密码身份验证，或配有 gateway.auth.mode: "trusted-proxy" 的身份感知型反向代理。
  • 新手引导向导默认创建共享密钥身份验证，并且通常会生成 Gateway 网关令牌，即使在环回地址上也是如此。
  • 在共享密钥模式下，UI 会在 WebSocket 握手期间发送 connect.params.auth.token 或 connect.params.auth.password。
  • 使用 gateway.tls.enabled: true 时，本地仪表板/状态辅助工具会呈现 https:// URL 和 wss:// WebSocket URL。
  • 在携带身份信息的模式（Tailscale Serve、trusted-proxy）下，WebSocket 身份验证检查通过请求标头而非共享密钥完成。
  • 对于公开的非环回 Control UI 部署，请显式设置 gateway.controlUi.allowedOrigins（完整来源）。对于环回地址、RFC1918/链路本地地址、.local、.ts.net 和 Tailscale CGNAT 主机，无需设置即可接受私有同源加载。
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback: true 会启用 Host 标头来源回退；这是一种危险的安全降级。
  • 使用 Serve 时，如果 gateway.auth.allowTailscale: true，Tailscale 身份标头即可满足 Control UI/WebSocket 身份验证要求（无需令牌/密码）。HTTP API 端点不使用 Tailscale 身份标头；它们始终遵循 Gateway 网关的常规 HTTP 身份验证模式。设置 gateway.auth.allowTailscale: false 可要求即使通过 Serve 访问也必须提供显式凭据。此无令牌流程假定 Gateway 网关主机本身可信。请参阅 Tailscale和安全。

构建 UI

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

bash
pnpm ui:build
Was this useful?
On this page

On this page