跳转到主要内容

​
控制界面（浏览器）

控制界面是一个由 Gateway网关提供服务的小型 Vite + Lit 单页应用：
  • 默认地址：http://<host>:18789/
  • 可选前缀：设置 gateway.controlUi.basePath（例如 /openclaw）
它通过同一端口直接与 Gateway网关 WebSocket 通信。

​
快速打开（本地）

如果 Gateway网关在这台计算机上运行，请打开： 如果页面无法加载，请先启动 Gateway网关：openclaw gateway。 认证在 WebSocket 握手期间通过以下方式提供：
  • connect.params.auth.token
  • connect.params.auth.password 仪表板设置面板允许你存储令牌；密码不会被持久化。 新手引导向导默认会生成一个 Gateway网关令牌，首次连接时请在此处粘贴。

​
设备配对（首次连接）

当你从新浏览器或设备连接到控制界面时，Gateway网关需要进行一次性配对审批 — 即使你在同一个 Tailnet 上且 设置了 gateway.auth.allowTailscale: true。这是一项防止 未授权访问的安全措施。 你会看到：“disconnected (1008): pairing required” 审批设备： 
# 列出待处理的请求
openclaw devices list

# 通过请求 ID 审批
openclaw devices approve <requestId>
审批后，设备会被记住，除非你使用 openclaw devices revoke --device <id> --role <role> 撤销，否则不需要重新审批。参见 设备 CLI 了解令牌轮换和撤销。 说明：
  • 本地连接（127.0.0.1）会自动审批。
  • 远程连接（局域网、Tailnet 等）需要显式审批。
  • 每个浏览器配置文件会生成唯一的设备 ID，因此切换浏览器或 清除浏览器数据将需要重新配对。

​
当前功能

  • 通过 Gateway网关 WS 与模型聊天（chat.history、chat.send、chat.abort、chat.inject）
  • 在聊天中流式传输工具调用 + 实时工具输出卡片（智能体事件）
  • 渠道：WhatsApp/Telegram/Discord/Slack + 插件渠道（Mattermost 等）状态 + 二维码登录 + 每渠道配置（channels.status、web.login.*、config.patch）
  • 实例：在线列表 + 刷新（system-presence）
  • 会话：列表 + 每会话思考/详细模式覆盖（sessions.list、sessions.patch）
  • 定时任务：列表/添加/运行/启用/禁用 + 运行历史（cron.*）
  • Skills：状态、启用/禁用、安装、API 密钥更新（skills.*）
  • 节点：列表 + 能力（node.list）
  • 执行审批：编辑 Gateway网关或节点允许列表 + exec host=gateway/node 的询问策略（exec.approvals.*）
  • 配置：查看/编辑 ~/.openclaw/openclaw.json（config.get、config.set）
  • 配置：应用 + 带验证的重启（config.apply）并唤醒最后活跃的会话
  • 配置写入包含基础哈希保护，防止覆盖并发编辑
  • 配置模式 + 表单渲染（config.schema，包括插件 + 渠道模式）；原始 JSON 编辑器仍然可用
  • 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（status、health、models.list）
  • 日志：实时跟踪 Gateway网关文件日志，支持过滤/导出（logs.tail）
  • 更新：运行包/git 更新 + 重启（update.run）并附带重启报告

​
聊天行为

  • chat.send 是非阻塞的：它会立即确认并返回 { runId, status: "started" }，响应通过 chat 事件流式传输。
  • 使用相同的 idempotencyKey 重新发送时，运行中返回 { status: "in_flight" }，完成后返回 { status: "ok" }。
  • chat.inject 将助手备注追加到会话记录中，并广播 chat 事件用于仅 UI 更新（不触发智能体运行，不投递到渠道）。
  • 停止：
    • 点击停止（调用 chat.abort）
    • 输入 /stop（或 stop|esc|abort|wait|exit|interrupt）进行带外中止
    • chat.abort 支持 { sessionKey }（无需 runId）以中止该会话的所有活跃运行

​
Tailnet 访问（推荐）

​
集成 Tailscale Serve（首选）

将 Gateway网关保持在 local loopback 上，让 Tailscale Serve 通过 HTTPS 代理： 
openclaw gateway --tailscale serve
打开：
  • https://<magicdns>/（或你配置的 gateway.controlUi.basePath）
默认情况下，当 gateway.auth.allowTailscale 为 true 时，Serve 请求可以通过 Tailscale 身份头 （tailscale-user-login）进行认证。OpenClaw 通过使用 tailscale whois 解析 x-forwarded-for 地址并与头信息匹配来验证身份，且仅在请求通过带有 Tailscale x-forwarded-* 头的 local loopback 到达时才接受。如果你希望即使对 Serve 流量也要求令牌/密码，请设置 gateway.auth.allowTailscale: false（或强制 gateway.auth.mode: "password"）。

​
绑定到 Tailnet + 令牌

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
然后打开：
  • http://<tailscale-ip>:18789/（或你配置的 gateway.controlUi.basePath）
在 UI 设置中粘贴令牌（作为 connect.params.auth.token 发送）。

​
不安全的 HTTP

如果你通过明文 HTTP（http://<lan-ip> 或 http://<tailscale-ip>）打开仪表板， 浏览器运行在非安全上下文中并会阻止 WebCrypto。默认情况下， OpenClaw 会阻止没有设备身份的控制界面连接。 **推荐修复：**使用 HTTPS（Tailscale Serve）或在本地打开 UI：
  • https://<magicdns>/（Serve）
  • http://127.0.0.1:18789/（在 Gateway网关主机上）
降级示例（仅令牌，通过 HTTP）： 
{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}
这将为控制界面禁用设备身份 + 配对（即使在 HTTPS 上也是如此）。仅在 你信任网络时使用。 有关 HTTPS 设置指导，请参阅 Tailscale。

​
构建 UI

Gateway网关从 dist/control-ui 提供静态文件。使用以下命令构建： 
pnpm ui:build # 首次运行时自动安装 UI 依赖
可选的绝对基础路径（当你需要固定的资源 URL 时）： 
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
本地开发（独立的开发服务器）： 
pnpm ui:dev # 首次运行时自动安装 UI 依赖
然后将 UI 指向你的 Gateway网关 WS URL（例如 ws://127.0.0.1:18789）。

​
调试/测试：开发服务器 + 远程 Gateway网关控制界面是静态文件；WebSocket 目标可配置，可以

与 HTTP 源不同。当你想在本地使用 Vite 开发服务器但 Gateway网关运行在其他地方时，这很方便。
  1. 启动 UI 开发服务器：pnpm ui:dev
  2. 打开类似以下的 URL：
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
可选的一次性认证（如果需要）： 
http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789&token=<gateway-token>
说明：
  • gatewayUrl 在加载后存储到 localStorage 并从 URL 中移除。
  • token 存储在 localStorage 中；password 仅保存在内存中。
  • 当 Gateway网关在 TLS 之后（Tailscale Serve、HTTPS 代理等）时使用 wss://。
远程访问设置详情：远程访问。