openclaw 文档

简体中文

English

简体中文

English

Appearance

控制界面（浏览器） ​

控制界面是一个由Gateway提供的小型Vite + Lit单页应用：

  • 默认：http://<主机>:18789/
  • 可选前缀：设置 gateway.controlUi.basePath（例如 /openclaw）

它通过直接与同一端口上的Gateway WebSocket通信。

快速打开（本地） ​

如果Gateway在同一台计算机上运行，请打开：

如果页面加载失败，请先启动Gateway：openclaw gateway。

认证在WebSocket握手期间通过以下方式提供：

  • connect.params.auth.token
  • connect.params.auth.password 仪表板设置面板允许您存储令牌；密码不会被持久保存。 入门向导默认生成一个gateway令牌，因此在首次连接时将其粘贴到这里。

当前功能 ​

  • 通过Gateway WS与模型聊天（chat.history、chat.send、chat.abort、chat.inject）
  • 流式工具调用 + 聊天中的实时工具输出卡片（代理事件）
  • 通道：WhatsApp/Telegram/Discord/Slack + 插件通道（Mattermost等）状态 + QR登录 + 每通道配置（channels.status、web.login.*、config.patch）
  • 实例：在线列表 + 刷新（system-presence）
  • 会话：列表 + 每会话思考/详细覆盖（sessions.list、sessions.patch）
  • 定时任务：列表/添加/运行/启用/禁用 + 运行历史（cron.*）
  • 技能：状态、启用/禁用、安装、API密钥更新（skills.*）
  • 节点：列表 + 能力（node.list）
  • 执行批准：编辑gateway或节点白名单 + 为 exec host=gateway/node 询问策略（exec.approvals.*）
  • 配置：查看/编辑 ~/.clawdbot/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保持在环回上，让Tailscale Serve通过HTTPS代理它：

bash
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-* 标头命中环回时才接受这些请求。如果您希望即使对于Serve流量 也需要令牌/密码，请设置 gateway.auth.allowTailscale: false（或强制 gateway.auth.mode: "password"）。

绑定到 tailnet + 令牌 ​

bash
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）：

json5
{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" }
  }
}

这将禁用控制界面的设备身份 + 配对（即使在HTTPS上）。仅当您信任网络时使用。

有关HTTPS设置指南，请参阅Tailscale。

构建 UI ​

Gateway从 dist/control-ui 提供静态文件。使用以下命令构建它们：

bash
pnpm ui:build # 首次运行时自动安装UI依赖

可选绝对基础路径（当您想要固定的资源URL时）：

bash
CLAWDBOT_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

对于本地开发（单独的开发服务器）：

bash
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：
text
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

可选一次性认证（如果需要）：

text
http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789&token=<gateway-token>

注意事项：

  • gatewayUrl 在加载后存储在localStorage中并从URL中移除。
  • token 存储在localStorage中；password 仅保存在内存中。
  • 当Gateway在TLS后面时使用 wss://（Tailscale Serve、HTTPS代理等）。

远程访问设置详情：远程访问。