Control UI：浏览器里的控制台

OpenClaw Control UI 是 Gateway 自带的浏览器控制台：openclaw dashboard 一条命令打开，会话、审批、文件、设置、终端全在一页。上一课说过日常入口有三类，这一课专讲最常用的这个。

它不是云端网站。Control UI 是一个 Vite + Solid 单页应用，由你自己的 Gateway 进程直接服务，本机默认地址 http://127.0.0.1:18789/——Gateway 停了页面就打不开。这是自托管的代价，也是「状态、记忆、凭据都在自己硬件上」的来源。

Control UI 在 v2026.8.1（「OpenClaw 2.0」）中整体重建：对话放在中心，文件、审批、设置、实时工作都贴在对话旁边（背景见 OpenClaw 2.0 新变化）。本教程基于 v2026.10.9。

学完你能做什么

• 用 openclaw dashboard 或 http://127.0.0.1:18789/ 打开 OpenClaw Control UI，并说清它和云端网页版的区别
• 完成 Gateway secret 认证与一次性设备配对；手机扫码、别的电脑也能连
• 分清侧栏 Pages / Sessions / Users 三区，用 Ctrl+K 命令面板快速跳转
• 在聊天框发消息、切模型，用 Details 面板看 workspace、分支与用量
• 管理会话与设置：Pin、重命名、归档、Snooze、生成公开只读分享链接；在设置页改外观、管插件、配 MCP 服务器、导入 Claude Code / Codex 记忆

你现在的困境

• 一直在终端里跟 Claw 聊，想翻旧记录、看它到底改了哪些文件，终端里滚不动
• Claw 请求审批时只在渠道里冒一句话，错过就沉底，想要个集中看、集中点的地方
• 想不碰配置文件就换模型、装插件、改界面——缺一个顺手的图形操作台

什么时候用这一招

当你需要：

• 一个全功能操作台：会话、文件、审批、设置、终端都在浏览器里
• 在手机或另一台电脑上查看、操作你的 Claw
• 日常操作不碰终端：开新会话、切模型、归档旧对话都是点一下

而且不想：

• 每次都 SSH 进机器改 openclaw.json
• 在终端 TUI 里翻长长的聊天记录
• 为了看一眼审批去翻日志文件

🎒 开始前的准备

• 完成了 日常使用导读，知道这一课在阶段里的位置
• Gateway 跑得起来：安装：5 分钟跑通 里 openclaw gateway status 应显示监听 18789；装不上先去 安装排错
• 一台较新的浏览器：Chrome 147+ / Firefox 150+ / Safari 26.2+（2026 年 10 月官方口径）
• （可选）手机上装了 OpenClaw App，想扫码配对

核心思路

Control UI 是什么？ 官方定义：一个 Vite + Solid 单页应用（SPA），由 Gateway 服务：

• 默认地址 http://<host>:18789/，本机就是 http://127.0.0.1:18789/
• 可选前缀 gateway.controlUi.basePath（比如挂到 /openclaw 子路径）
• 页面直接和同端口的 Gateway WebSocket 通信——没有中间服务器

和另外两个日常入口的关系：

入口	怎么打开	适合什么时候
Control UI（本课）	openclaw dashboard 或浏览器访问 18789	全功能操作台：会话、审批、文件、设置、终端
TUI	终端敲 openclaw	不开浏览器，快速聊两句
聊天渠道	飞书 / 企业微信 / Telegram 等	Claw 来你已有的 IM 里找你（场景实战）

安全模型先记一句话：Gateway 认证（token 或密码）在设备配对之前执行，本机回环连接也不绕过认证；Gateway 默认只监听本机（loopback），端口 18789。远程暴露的完整规则在 安全加固（一）。

跟我做

第 1 步：打开 OpenClaw Control UI——本机 18789 端口

为什么：Control UI 由 Gateway 服务，Gateway 没跑页面就打不开。先确认它活着，再开浏览器。

openclaw dashboard

你应该看到：浏览器自动打开 Control UI。也可以手动访问 http://127.0.0.1:18789/（或 http://localhost:18789/）。

页面打不开？官方文档给的顺序是先启动 Gateway：

openclaw gateway

再刷新浏览器。还是不行，对照下面「踩坑提醒」逐条排查。

• 浏览器打开了 http://127.0.0.1:18789/，能看到登录页或工作台

第 2 步：填入 Gateway secret——OpenClaw Control UI 的认证

为什么：Gateway 认证是第一道门，本机回环也不绕过。本地 onboarding 默认生成 token 模式的 Gateway secret。

登录页只有一个 Gateway secret 输入框：token 直接粘贴，密码手动输入（gateway.auth.mode 决定用哪个）。共享 token 在 Gateway 主机的交互式终端里查看：

openclaw gateway auth-token --show

你应该看到：终端打印出共享 token。粘贴进 Gateway secret 字段后连上工作台；左下角的连接指示器显示当前连接状态。

💡 secret 存在哪？

连接成功后，UI 只在 token 模式下把 secret 存进当前浏览器标签页的 session storage（仅限当前 Gateway 来源）；密码只留在内存里、从不落盘。配对完成后，浏览器后续连接用的是自己的按设备 token，不用再填 secret。

• Gateway secret 认证通过，进入登录后的界面

第 3 步：批准设备配对——新浏览器的第一次连接

为什么：认证通过后，新浏览器/设备的第一次连接通常还需要一次性配对批准——把「这台浏览器我认识」落进凭据库。

Gateway 主机上最省事的做法就是第 1 步的 openclaw dashboard：它打开一个短时效、一次性的配对链接，让当前浏览器直接拿到持久的管理员凭据，不用手动批准。

换一台浏览器/设备时，页面显示 disconnected (1008): pairing required 并等待，此时在 Gateway 主机执行：

openclaw devices list
openclaw devices approve <requestId>

你应该看到：页面保持开着，批准后自动连上（Check now 可立即重试）。批准过的设备会被记住，之后免配对；想撤销用 openclaw devices revoke --device <id> --role <role>。

💡 本机回环可以自动批准

直接从 127.0.0.1 / ::1 连接、且没有代理头的本机连接，在 Gateway 认证通过后会自动批准设备配对（token / 密码仍然要先过，这不是绕过认证）。想强制每台设备都手动批准，设 gateway.nodes.pairing.autoApproveLocal: false。

⚠️ 无痕窗口每次都是「新浏览器」

每个浏览器配置文件生成独立设备 ID；清浏览器数据、用无痕窗口（或设成「从不记住历史」的 Firefox）都会丢掉已配对的设备身份，下次又要重新配对。日常用固定的浏览器配置文件最省事。

• 浏览器完成配对，进入 Control UI 工作台

第 4 步：认识三区导航——Pages、Sessions 与 Users

为什么：2.0 重建后对话居中，左侧一条导航轨管全局。分清三个视图，后面所有操作都有归属。

视图	放什么	你最常在这做
Pages	内置页面、仪表盘、插件入口	打开 Automations、Templates、Systems 等页面
Sessions	全部会话	找回旧对话、开新会话
Users	在线的人	看谁在线、看别人的活动

导航轨的固定结构：顶部是当前 agent 的头像（点开 agent 菜单），头像下一个 +（New conversation，开新会话），底部是 Home、Inbox 和你的账号菜单。

三个立刻上手的手感：

• Ctrl+K（Mac 上 ⌘K）：命令面板——跳页面、切会话、搜命令
• Ctrl+B（Mac 上 ⌘B）：收起 / 展开侧栏
• Ctrl+Shift+O（Mac 上 ⌘⇧O）：浏览器里的 New Session 快捷键，直接聚焦聊天框

你应该看到：点 Sessions 视图，会话按三个分区排开——

• Other：普通对话；Groups：群 / 房间；Coding：绑定 worktree 或 exec 节点的会话，行里带 repo ⎇ branch

• 标题行的 My sessions / Involving me / All owners 芯片切换看谁的会话

• Filter & sort 里按状态（Active / Snoozed / Archived / All）、分组、排序过滤；Show message preview 可打开消息预览

• 能用 Ctrl+K 打开命令面板，并在三个视图之间切换

第 5 步：和 Claw 对话——composer、模型与 Details 面板

为什么：聊天是 Control UI 的中心。发消息之外，这一步把「看得见它在干什么」的几个挂件认全。

点导航轨的 +（或 Sessions 里的 New session）：New session 页可以选 agent、Workspace（保存过的项目 / 最近文件夹 / 仓库 URL）、模型，然后发出第一条消息。

你应该看到：

• 回复流式出现；完成的回合把过程折叠成 Worked for 2m 3s 一行，点开看工具调用明细
• 聊天框（composer）里有模型选择器——不碰配置文件就能切模型（写法回顾：provider/model，见 连接模型总览）
• composer 的上下文环显示用量摘要、最近一轮 token 和套餐限额；View context 打开完整报告
• 聊天头部的 Details 面板：Environment（workspace 名、分支、worktree、执行设备、模型）、Changes（PR、变更统计、检查）
• Claw 需要审批或提问时，侧栏对应会话行出现注意力图标，点开能看到具体请求

新会话的名字自动取自开场任务，之后只有你或 agent 显式重命名才会改。

💡 后台开小会话，不打断当前对话

Ctrl+K 打开命令面板，把图片或文件拖进面板（或直接粘贴图片），面板切换成 New session 模式；补一句指令、调好会话设置，Ctrl+Enter 发出——当前对话一点没动，文件也不会自己发出去。

• 发出一条消息并收到回复；打开过一次 Details 面板

第 6 步：管理会话——Pin、重命名、归档与分享

为什么：对话多了就要收纳。会话菜单（右键侧栏行，或聊天头部的操作菜单）把常用动作收在一起。

操作	效果
Pin / Unpin	固定在 Sessions 顶部的 Pinned 区
Rename	点聊天头部标题直接改；Enter 保存、Escape 取消
Archive / Restore	从 Active 列表收起（Ctrl+Shift+A 归档当前聊天），历史仍可读，可 Undo
Snooze / Wake	暂时隐藏：1 小时 / 3 小时 / 今晚 18:00 / 明早 9:00 / 下周一 9:00
Move to group	挪进自定义分组；分组名和顺序存在 Gateway，跨浏览器跟随
Icon & color	给会话行配 emoji / 图标和颜色条（Advanced 菜单）

Snooze 只是「先藏起来」：会话本身照常运行——你给它发消息、agent 跑完一轮或到了唤醒时间，它就自己回到 Active 列表；想提前叫醒，用菜单里的 Wake session。

公开分享一个会话：聊天头部 Session sharing → Enable public access… → 确认 Make public → Copy public link。拿到链接的人以只读身份看对话文字、符合条件的图片和折叠的工具摘要；他们不能发消息，也拿不到你的权限。

⚠️ 公开前先自己读一遍

公开页面的文字不做脱敏——对话里出现过密码、Key 之类的内容会原样可见。发布前检查一遍对话；关闭公开访问不能收回别人已保存的副本。

你应该看到：Pin 的会话固定在 Sessions 顶部的 Pinned 区；归档的会话从 Active 列表消失、确认条上可 Undo，历史记录仍可读。

• 把一个常用会话 Pin 到顶部，并把一个旧会话归档

第 7 步：设置页与侧面板——外观、插件、MCP 与终端

为什么：日常的图形化配置集中在 Settings；干活用的工具挂在聊天右侧的侧面板。

Settings（侧栏底部账号菜单 → Settings）：

• Appearance：主题外观，连浏览器标签页图标都能换（Default / Agent avatar / Lobsterdex）
• Plugins：一键安装与发现插件
• Updates：stable / beta 通道有新版本时出现 Available 徽标（账号菜单里也有 Updates 入口）
• MCP：加 / 启用 / 停用 MCP 服务器（Streamable HTTP、SSE、stdio 三种传输）——深入玩法见 MCP 接入
• Import Memory：把 Claude Code / Codex / Hermes 的本地记忆导入某个 agent——细节在 记忆系统
• Labs：开实验特性，比如 Templates（Pages 里多一个官方模板发现页）和 Speech bubbles（气泡对话视图）
• 顶部 Search settings 按页面和配置字段名搜索，不用一个个翻

侧面板（聊天右侧，+ 菜单或头部 Layout 菜单打开）：

• Terminal：操作员终端，默认开启（gateway.terminal.enabled），需要 operator.admin 权限，在当前 agent 的 workspace 开一个宿主机 PTY；快捷键 Ctrl+` （Ctrl 加反引号）快速开关
• Browser：Claw 的浏览器操作结果在这里看
• Files：浏览 workspace 文件；悬停文件行出现 Download file，PDF 最大 16 MiB 可预览；预览工具栏 ⋯ 菜单里 Attach to session 把文件附到下一条消息
• Subagents：看子代理的运行情况和只读 transcript（聊天里也能用 /subagents list 等命令）
• Processes：会话后台 exec 命令的状态与输出，Stop 精确停那一条进程

Ask OpenClaw：Settings → Ask OpenClaw（或 Home 停靠栏的 Ask OpenClaw 标签）——专门管系统安装与修理的 agent，聊天式说 configure gateway、import memory 就能走引导向导。

⚠️ 操作员终端是宿主机 shell

Gateway 本地终端不受沙箱限制，继承 Gateway 进程环境——Gateway 能读到的凭据它也能读到，直接写文件还会绕过 OPENCLAW_CONFIG_READONLY 这类限制。不想要这个能力：设 gateway.terminal.enabled: false，或部署时用环境变量 OPENCLAW_DISABLE_GATEWAY_LOCAL_TERMINALS=1 彻底禁掉。

你应该看到：Settings 顶部有 Search settings 搜索框——输入 Typography 这类词能直接跳到 Appearance 里的对应设置项；侧面板的标签可以拖动排序、单独关闭，互不影响。

• 在 Settings 里找到 MCP 和 Import Memory 两个页面；打开过一次 Terminal 面板

第 8 步（可选）：远程与手机访问 Control UI

为什么：Claw 跑在家里机器或 VPS 上，人不在跟前时也要能连。

方式 A（推荐）：Tailscale Serve 暴露 HTTPS

openclaw gateway --tailscale serve

访问 https://<magicdns>/。gateway.auth.allowTailscale: true 时可走 Tailscale 身份认证，已带设备身份的浏览器还能跳过配对往返。

方式 B：手机扫码配对

已配对的管理员在 Control UI 里：Devices → Pair device 生成二维码 → 手机 App 里 Settings → Gateway 扫码（或粘贴 setup code）→ 出现 Pending approval 时审一眼角色和权限再批准。生成 setup code 需要 operator.admin。

方式 C：装成 PWA

Control UI 自带 manifest 和 service worker，现代浏览器可以「安装」成独立应用；装好后 Web Push 能在标签页关着时推送通知——包括待处理的 exec / 插件审批。

⚠️ 别裸奔到公网

Gateway 默认只监听本机；改成非 loopback 监听必须配认证，否则拒绝启动（fail closed）。局域网 http://<内网IP> 能打开但属于降级传输，尽量用 HTTPS。完整规则见 安全加固（一）。

你应该看到：方式 A 下 https://<magicdns>/ 打开和本机一样的 Control UI；方式 B 下手机扫码后 App 自动连接，批准完 Pending approval 就配对成功；方式 C 下安装后 Control UI 以独立应用窗口运行，不占浏览器标签页。

• （可选）手机完成扫码配对，或 Tailscale HTTPS 能打开 Control UI

检查点 ✅

• openclaw dashboard 能打开 Control UI，本机地址 http://127.0.0.1:18789/
• Gateway secret 认证通过，浏览器完成一次性设备配对
• 能说出 Pages / Sessions / Users 各放什么，Ctrl+K 能打开命令面板
• 在 Control UI 里发出过消息、切过模型、打开过 Details 面板
• 完成过至少一次会话管理（Pin / 归档 / 重命名任一）

踩坑提醒

❌ 页面打不开或一片空白

三层原因，按序排查：

1. Gateway 没跑：Control UI 是 Gateway 服务的页面，进程停了必然打不开。先 openclaw gateway（前台跑起来看日志），或确认后台服务在运行
2. 浏览器扩展拦了模块应用：页面空白、DevTools 又没报错时，官方文档指向「注入所有页面的扩展（尤其是带 <all_urls> content script 的那种）」。禁用这类扩展、换无痕窗口或干净配置文件试；页面自带的恢复面板 Try again 可以直接重载
3. 更新后显示 Protocol mismatch：旧标签页或 service worker 缓存还在跑更新前的 UI 包。先 openclaw dashboard 重开 + 强制刷新；不行就清掉该来源的站点数据，或换无痕窗口验证

Windows 上还有一种：主机 127.0.0.1 正常、局域网地址却打不开——防火墙或组策略拦了 LAN 地址。在 Windows 主机跑 openclaw gateway status --deep，它会报告疑似被拦的端口和本地防火墙规则。

❌ disconnected (1008): pairing required 一直转圈

原因：新浏览器首次连接需要一次性配对批准，请求还没人批。

正确做法：页面保持开着（批准后自动连上），在 Gateway 主机 openclaw devices list 看请求、openclaw devices approve <requestId> 批准。两种失败长相要分清：被明确拒绝显示 Access request declined（可点 Request again 再申请）；没人理会显示 Access request expired（重新打开页面会再发一次请求）。

注意：如果浏览器重试时角色或权限变了，旧请求会被新的 requestId 顶掉——批准前重新 list 一次，别批一个已经失效的请求。

❌ token 模式下本机浏览器也被拒

原因：Gateway 以 token 模式启动但没配置 token 时，会生成一个临时运行时 token——不写进配置、无法找回，没拿到它的浏览器一律拒绝，本机也不例外。

正确做法（官方文档给的修复三步）：

openclaw doctor --generate-gateway-token   # 生成正式 token 写进配置
# 然后重启 Gateway
openclaw gateway auth-token --show         # 交互式终端里查看，粘贴进登录页

❌ 浏览器太旧，进不了界面

原因：Control UI 需要较新的浏览器能力。官方口径（2026 年 10 月）：Chrome 147+、Firefox 150+，以及 macOS 26.2 / iOS 26.2 / iPadOS 26.2+ 上的 Safari 26.2+（或最近六个月内发布的 Chrome / Firefox）。

正确做法：升级浏览器。缺关键能力的浏览器会先看到更新提示页；完全不支持模块脚本的直接显示 This browser is not supported。原生 App 里遇到可以点 Open in browser，换系统默认浏览器打开。

❌ 无痕 / 隐私窗口每次都要重新配对

原因：每个浏览器配置文件一个设备 ID；丢弃站点数据的窗口（无痕、Firefox「从不记住历史」）每次都当新浏览器。

正确做法：日常用固定配置文件连 Control UI；配对设备列表越攒越长时，用 openclaw devices remove <deviceId> 清掉不再用的旧条目。

进阶技巧（可选）

关掉 Control UI 不动机器人。 gateway.controlUi.enabled: false 热生效——只停页面和静态资源，机器人与已有 Gateway 连接照跑；改回 true 恢复服务，缺的资源会在后台补齐。但改 basePath / 资源根目录仍需重启 Gateway：

{
  gateway: {
    controlUi: {
      enabled: true,
      basePath: "/openclaw",   // 挂到子路径；改这个要重启
    },
  },
}

只读配置横幅。 用 OPENCLAW_CONFIG_READONLY=1（或 OPENCLAW_NIX_MODE=1）启动的 Gateway，Control UI 顶部显示 Gateway configuration is read-only——配置只能看不能改。想引导大家去自己的流程改配置，设 OPENCLAW_CONFIG_READONLY_NOTICE 换成你的提示文字（以空格 + 绝对 URL 结尾会自动多一个 Learn more 链接）。

多 Gateway 别认错。 同时管几台 Gateway 时，给每台配 gateway.controlUi.environment：

{
  gateway: {
    controlUi: {
      environment: { label: "edge", color: "amber" },
    },
  },
}

浏览器会出现 2px 顶色条、侧栏标签、标题后缀和配套 favicon，一眼分清连的是哪台。颜色可用 teal / amber / purple / coral / pink / blue / green / red / gray，label 限 1–24 字符。

断线了别慌。 连接断开时，已加载的目录、自动化编辑器、Import Memory 选择、活动历史、审批队列都留在内存里不丢；左下角指示器显示 Reconnecting… 自动重连，自动恢复停下来才出现 Retry 按钮。但记住一条：保存编辑、批准请求这类 Gateway 动作需要 live 连接，重连不会自动重放它们——重连后把没确认的操作手动补一遍。

本课小结

✅ OpenClaw Control UI 是 Gateway 服务的浏览器控制台：openclaw dashboard 打开，本机 http://127.0.0.1:18789/，与 Gateway WebSocket 同端口通信——不是云端网站。

✅ 连接三道门走顺了：Gateway secret（token / 密码）→ 一次性设备配对（openclaw dashboard 一步到位或 devices list / approve）→ 之后按设备 token 免配对。

✅ 界面地图记住了：导航轨 = Pages / Sessions / Users + 顶部 agent 头像 + 底部 Home / Inbox / 账号；Ctrl+K 命令面板、Ctrl+B 收侧栏、Ctrl+Shift+O 开新会话。

✅ 日常动作有了固定入口：聊天框切模型、Details 看 workspace 与用量、会话菜单 Pin / 归档 / Snooze、Session sharing 出只读公开链接、Settings 管外观 / 插件 / MCP / 记忆导入、侧面板挂 Terminal / Browser / Files / Subagents。

配置键 / 命令	作用	说明
gateway.controlUi.enabled	开关 Control UI	热生效；关掉不影响机器人和已有连接
gateway.controlUi.basePath	子路径前缀	如 /openclaw；改它要重启 Gateway
gateway.auth.mode	token / password	登录页 Gateway secret 填对应值
gateway.terminal.enabled	操作员终端开关	默认开；需要 operator.admin
openclaw dashboard	打开 / 修复配对	短时效一次性配对链接
openclaw gateway auth-token --show	查看共享 token	在 Gateway 主机交互式终端跑
openclaw devices list / approve	配对审批	新浏览器首次连接
openclaw gateway --tailscale serve	HTTPS 远程访问	推荐 Tailnet 方式

命令与配置的完整速查见 CLI 命令与配置速查。

下一课预告

Control UI 的聊天框不只能打字——/model、/think、/new 这些斜杠命令在网页版和聊天渠道里同样生效。下一课 聊天命令速成：/model、/think 与斜杠命令 把最常用的一批过一遍。

你会学到：

• /model 家族：/model list 看目录、/model <name> 切换、/model status 查状态
• /think <level> 调思考档位，/fast 快速模式
• /new、/reset 管理会话生命周期
• /skill <name> 万能入口——把技能当命令调

相关教程

• OpenClaw 2.0 新变化
• 记忆系统：让 Claw 记住你
• 安全加固（一）：访问控制与身份