Control UI

Control UI 是一个由 Gateway 网关提供服务的小型 Vite + Lit 单页应用：

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

它通过同一端口直接连接 Gateway 网关 WebSocket。

快速打开（本地）

如果 Gateway 网关运行在同一台计算机上，请打开 http://127.0.0.1:18789/（或 http://localhost:18789/）。

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

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

• connect.params.auth.token
• connect.params.auth.password
• 当 gateway.auth.allowTailscale: true 时使用 Tailscale Serve 身份标头
• 当 gateway.auth.mode: "trusted-proxy" 时使用受信任代理身份标头

仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留令牌；密码不会持久化。新手引导通常会在首次连接时生成用于共享密钥身份验证的 Gateway 网关令牌，但当 gateway.auth.mode 为 "password" 时，也可使用密码身份验证。

设备配对（首次连接）

从新浏览器或设备连接通常需要进行一次性配对审批，显示为 disconnected (1008): pairing required。

openclaw devices list

openclaw devices approve <requestId>

如果浏览器使用已更改的身份验证详情（角色/权限范围/公钥）重试配对，之前的待处理请求将被取代，并创建新的 requestId；请在批准前重新运行 openclaw devices list。

将已配对浏览器从读取权限切换为写入/管理员权限会被视为审批升级，而不是静默重新连接：OpenClaw 会保持旧审批有效、阻止权限更广的重新连接，并要求你明确批准新的权限范围集合。

批准后，系统会记住该设备；除非使用 openclaw devices revoke --device <id> --role <role> 将其撤销，否则无需再次批准。有关令牌轮换、撤销以及 Paperclip / openclaw_gateway 首次运行审批流程，请参阅设备 CLI。

配对移动设备

已配对的管理员无需打开终端即可创建 iOS/Android 连接二维码：

创建设置代码需要 operator.admin；没有该权限的会话中，此按钮会被禁用。设置代码包含短期有效的引导凭据，因此在二维码和复制的代码有效期间，应像对待密码一样保护它们。进行远程配对时，Gateway 网关必须解析为 wss://（例如通过 Tailscale Serve/Funnel）；普通的 ws:// 仅限 local loopback 和私有 LAN 地址。有关完整的安全和回退详情，请参阅配对。

个人身份（浏览器本地）

Control UI 支持为每个浏览器设置个人身份（显示名称和头像），并将其附加到传出的消息中，以便在共享会话中注明归属。该身份存储在浏览器中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久化，但你发送的消息所含常规对话记录作者元数据除外。清除站点数据或切换浏览器会将其重置为空。

智能体头像覆盖项采用相同的浏览器本地模式：上传的覆盖项会在本地覆盖由 Gateway 网关解析的身份，且绝不会通过 config.patch 往返传输。共享的 ui.assistant.avatar 配置字段仍可供直接写入该字段的非 UI 客户端使用。

运行时配置端点

Control UI 从 /control-ui-config.json 获取其运行时设置，该路径相对于 Gateway 网关的 Control UI 基础路径解析（例如，基础路径为 /__openclaw__/ 时使用 /__openclaw__/control-ui-config.json）。该端点受到与 HTTP 表面其余部分相同的 Gateway 网关身份验证保护：未经身份验证的浏览器无法获取该端点，成功获取需要有效的 Gateway 网关令牌/密码、Tailscale Serve 身份或受信任代理身份。

Gateway 网关主机状态

在简单视图中打开 设置，即可查看 Gateway 网关主机 卡片，其中包含 Gateway 网关计算机、LAN 地址、操作系统、运行时、运行时间、CPU 负载、内存和状态卷磁盘空间。此卡片可见时，每 10 秒通过 system.info Gateway RPC 刷新一次，该 RPC 需要 operator.read 权限范围。旧版 Gateway 网关以及没有该权限范围的连接不会显示此卡片。

语言支持

Control UI 首次加载时会根据浏览器区域设置自行本地化。若要稍后覆盖此设置，请打开 Settings -> General -> Language（选择器位于 General 快速设置卡片中，而不在 Appearance 下）。

• 支持的区域设置：en、ar、de、es、fa、fr、hi、id、it、ja-JP、ko、nl、pl、pt-BR、ru、th、tr、uk、vi、zh-CN、zh-TW
• 非英语翻译会在浏览器中延迟加载。
• 所选区域设置会保存在浏览器存储中，并在以后访问时复用。
• 缺失的翻译键会回退到英语。

文档翻译会针对同一组非英语区域设置生成，但文档站点内置的 Mintlify 语言选择器只列出 Mintlify 接受的区域设置代码。泰语（th）和波斯语（fa）文档仍会在发布仓库中生成；在 Mintlify 支持这些代码之前，它们可能不会出现在该选择器中。

外观主题

外观面板包含内置的 Claw、Knot 和 Dash 主题（默认为 Claw），另有一个浏览器本地 tweakcn 导入槽位。要导入主题，请打开 tweakcn 编辑器，选择或创建主题，点击 Share，然后将复制的链接粘贴到外观面板中。导入器还接受 https://tweakcn.com/r/themes/<id> 注册表 URL、类似 https://tweakcn.com/editor/theme?theme=amethyst-haze 的编辑器 URL、相对 /themes/<id> 路径、原始主题 ID，以及 amethyst-haze 等默认主题名称。

导入的主题仅存储在当前浏览器配置文件中；不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新这一个本地槽位；如果导入的主题处于启用状态，清除后会切换回 Claw。

外观面板还提供浏览器本地的文本大小设置，该设置与 Control UI 的其他偏好设置一同存储。它适用于聊天文本、编辑器文本、工具卡片和聊天侧边栏，并确保文本输入框的字号至少为 16px，以防移动版 Safari 在聚焦时自动缩放。

管理插件

打开侧边栏中的 插件，或使用相对于 所配置 Control UI 基础路径的 /settings/plugins，即可在不离开 Control UI 的情况下浏览和管理插件。例如，基础路径 /openclaw 使用 /openclaw/settings/plugins。即使所有可选插件均被禁用，该页面也始终 可用。

插件页面是一个包含四个标签页的中心：已安装 和 发现 在 /settings/plugins 管理插件代码，Skills 在 /skills 提供按智能体管理的技能管理器，工作坊 在 /skills/workshop 提供 Skill Workshop 提案审核。每个标签页都有自己的 URL，侧边栏则为 所有这些标签页显示单一的插件入口。

已安装 标签页按类别分组显示完整的本地清单，并提供概览计数。 每一行都可打开详情视图；其溢出（…）菜单可启用 或禁用插件，并为外部安装的插件提供 移除。该页面还会列出已配置的 MCP 服务器，并支持内联添加、禁用和移除。发现 标签页是商店：其中包含 OpenClaw 内置的精选插件、官方外部插件， 以及适用于热门服务的一键式 MCP 连接器。在搜索框中输入内容会内联查询 ClawHub，并追加一个 来自 ClawHub 分区，其中包含下载次数和来源验证徽章。深层链接可使用 /settings/plugins?tab=discover 直接指向商店。

Skills 标签页保留技能状态报告、启用/禁用开关、API 密钥输入和内联 ClawHub 技能搜索，其作用域限定为所选智能体。 工作坊 标签页保留 Skill Workshop 看板和今日 技能提案审核流程。查找技能创意 会按从新到旧的顺序审核 数量有限且内容充分的会话窗口，并将所有结果保留为待处理提案。面板会显示累计覆盖情况；扫描更早的工作 会从持久化游标处继续，然后在较早的历史记录全部扫描完毕后变为 扫描新工作。 禁用自主自我学习时仍可进行手动历史记录审核，并使用所选智能体配置的模型。

内置插件已存在于 Gateway 网关上，并显示 启用 或 禁用，而非 安装。例如，Workboard 内置于 OpenClaw 中，但默认处于禁用状态，因此其操作是 启用。内置插件 无法移除，只能禁用。

读取目录和搜索 ClawHub 需要 operator.read。安装、 启用、禁用或移除插件以及更改 MCP 服务器需要 operator.admin；对于只读操作员，这些操作会保持禁用状态。

ClawHub 安装通过 Gateway 网关运行，并沿用其他由 Gateway 网关中介的安装所采用的 相同信任、完整性和插件安装策略检查。安装 或移除插件代码需要重启 Gateway 网关。当插件和当前 Gateway 网关运行时支持时，启用或禁用已安装的插件无需重启即可生效； 否则，UI 会报告需要重启。使用 OAuth 的 MCP 连接器在添加后需要通过 CLI 执行一次 openclaw mcp login <name>。

该页面特意专注于清单、发现、安装、启用 和移除。对于任意 npm、git 或 本地路径来源、更新以及高级插件配置，请使用 openclaw plugins。

侧边栏导航

侧边栏将导航固定在可滚动的会话列表上方。在多 Agent 设置中，每个 Agent 都显示为可折叠的顶级区段；展开某个 Agent 可浏览其会话，而无需离开当前打开的聊天，折叠的 Agent 会显示未读指示器。在一个 Agent 内，列表分为 已固定、每个已连接渠道（Telegram、Slack、WhatsApp 等）对应的内置区段、用于绑定到托管工作树或 Exec 节点的会话的内置 工作 区段（行中显示 repo ⎇ branch 行及节点主机）、自定义组（会话 category），以及容纳其余会话的 聊天。渠道和工作区段会自动对行进行分类；将会话分配到自定义组始终具有最高优先级。打开会话时，选择高亮会随之移动，但不会重新排列各行。自上次读取后出现新活动的会话会显示未读圆点，打开后即标记为已读。每个会话行都有一个上下文菜单（烤肉串按钮或右键单击），其中包含固定/取消固定、标记为未读/已读、重命名、派生、移至组（包括新建组和从组中移除）、归档和删除；触控布局会始终显示直接固定按钮和菜单控件。按住 Cmd/Ctrl 单击可切换行的多选状态，按住 Shift 单击可按当前可见顺序扩展选择；随后在已选行上打开菜单，会提供批量操作（将 N 个标记为未读/已读、将 N 个移至组、归档 N 个、删除 N 个），并应用于所有已选会话；批量删除只需确认一次。将会话拖到自定义组或 聊天 即可移动。自定义组标题可折叠、展开或通过拖动重新排序；组名及其顺序保存在 Gateway 网关中（sessions.groups.*），因此可跨浏览器同步，而折叠状态保存在浏览器配置文件中。组标题也有一个菜单（烤肉串按钮或右键单击），其中包含重命名组、新建组和删除组；重命名或删除组会在服务器端更新其所有成员会话，包括已归档的会话；删除组会保留其中的会话，并将其移回聊天。会话列表标题中的唯一 + 会打开新建会话页面（见下文）。排序控件还提供“分组方式”切换项：分组（默认）或无，以显示单个扁平列表（已固定仍单独显示）；该选择保存在当前浏览器配置文件中。用量、自动化和插件默认固定；更多行会打开一个包含其他所有目标位置的菜单，其中包括插件提供的标签页。在该菜单中选择 编辑固定项目，或右键单击导航区域，即可固定或取消固定目标位置，并恢复默认设置。固定项目集保存在当前浏览器配置文件中，并在重新加载后继续保留。

新建会话页面

侧边栏会话列表标题中的 + 会在 /new 打开全页面草稿：在发送第一条消息之前不会创建任何内容。消息框上方的目标行用于选择会话的工作位置：Agent（多 Agent 设置）、Exec 的运行位置（Gateway 网关 · 本地，或公开 system.run 的已配对节点；需要 operator.admin）、文件夹（默认为 Agent 工作区；其他 Gateway 网关绝对路径需要 operator.admin 和工作树），以及可选的 工作树 开关和基础分支选择器（由 worktrees.branches 提供支持，因此不会执行 fetch），还可指定工作树名称（分支将变为 openclaw/<name>）。文件夹标签上的浏览按钮会打开一个内联目录选择器，由仅限管理员使用的 fs.listDir 方法提供支持。其顶层会显示 Gateway 网关和所有已知节点；离线节点以及不支持目录浏览的节点仍会显示，但处于禁用状态。选择 Gateway 网关后，会从当前文件夹或 Gateway 网关主目录开始浏览。选择具备相应能力的节点后，会浏览该节点的主机文件系统，将 Exec 绑定到该节点，并直接使用所选节点的绝对路径（托管工作树仍仅限 Gateway 网关）。提交时会使用第一条消息调用 sessions.create，因此运行会在同一次往返中启动，UI 也会跳转到新会话的聊天。如果 Gateway 网关创建了会话，但拒绝发送第一条消息，聊天会在重新加载后保留提示词和错误；重试会通过已创建的会话发送消息，而不会再创建一个会话。

在 设置 中，专用侧边栏顶部提供 搜索设置 字段，用于快速查找设置区段。

侧边栏顶部的 搜索 字段会打开命令面板（⌘K）。单击侧边栏标题中的 OpenClaw 品牌标识，会打开简洁的新建会话起始屏幕。当有事项需要处理时——例如失败或逾期的 cron 作业、即将过期或已经过期的模型身份验证——侧边栏页脚上方会显示紧凑的提醒标签，单击后会跳转到负责该事项的页面。页脚以标签形式显示当前 Agent，包括头像（身份图像或表情符号）、名称、连接状态圆点和实时副标题，并提供用于新建会话的 +。单击该标签会打开 Agent 菜单，其中包含 Agent 切换器（多 Agent 设置）、“此 Agent 能做什么？”、Agent 设置、设置、移动端配对、文档、构建标签和颜色模式切换项。Agent 名单超过十个时会显示筛选字段，并优先列出已固定的 Agent；可在智能体设置页面固定或取消固定 Agent，固定项目集保存在浏览器配置文件中。选择 Agent 后，聊天、用量、自动化、任务、Workboard 和会话的范围都会限定到该 Agent。每个限定范围的页面都提供 Agent 控件，并可通过 所有 Agent 退出限定范围；这会扩大共享页面的范围，但不会更改具体的聊天 Agent，而直接会话链接仍会打开其目标会话。智能体设置页面会保留自己的 ?agent= 选择，不会跟随共享页面范围。当 Gateway 网关从源代码检出目录中运行，且所在分支不是 main 时，页脚还会以红色显示该分支名称，以便一眼看出这是非发布版 Gateway 网关（发布版安装永远不会显示）。按 Shift-Command-Comma 可打开 设置，且不会覆盖浏览器的 Command-Comma 快捷键。侧边栏标题中还包含折叠开关（⌘B）；折叠后会完全隐藏侧边栏，提供全宽工作区，使用浮动展开控件（或 ⌘B）可将其恢复；在 macOS 应用中，该开关改由标题栏原生承载。侧边栏是桌面端唯一的导航框架，不设顶部栏。较窄的视口会将侧边栏替换为滑出式抽屉，并显示紧凑的标题行，其中包含抽屉开关、品牌标识和命令面板搜索；在 macOS 应用中，该标题行会将标题栏留白整合为窗口控件旁的一条紧凑栏。导航使用常规浏览器历史记录，因此可通过浏览器的后退/前进按钮进行切换；macOS 应用还会在窗口控件旁添加原生侧边栏开关并支持触控板轻扫手势，侧边栏展开时，其右侧边缘会显示后退/前进按钮；侧边栏折叠时，则会显示原生搜索（命令面板）和新建会话按钮。

当前功能

导入智能体记忆

打开设置 → 导入记忆，将本地 Codex 或 Claude Code 记忆导入 OpenClaw 智能体。Gateway 网关会自行发现其所在主机上支持的本地记忆， 因此远程 Control UI 会从 Gateway 网关所在计算机导入，而不是从 浏览器所在计算机导入。

1. 选择目标智能体。
2. 检查检测到的源集合和 Markdown 文件名。文件内容 不会在计划响应中发送，也不会显示在页面上。
3. 选择要导入的集合并确认。应用操作会在写入前重新构建计划， 以便过期选择安全地失败。
4. 如果文件已存在，请启用替换现有导入内容，刷新 预览，然后确认替换。

Codex 仅导入其整合后的 MEMORY.md 和 memory_summary.md。Claude Code 会从项目自动记忆目录和已配置的 autoMemoryDirectory 导入 Markdown；它不会通过此页面导入会话、设置、指令或 凭据。文件会复制到所选工作区的 memory/imports/ 下， 活跃的记忆插件可以在此为其建立索引。源文件 绝不会被更改。

规划和应用需要 operator.admin。只要存在状态，每次应用都会创建经过验证的 OpenClaw 备份、写入经过脱敏的迁移报告，并在替换现有目标文件前保留 项目级备份。有关路径和 回忆行为，请参阅记忆概览。

MCP 页面

专用的 MCP 页面是用于查看 mcp.servers 下由 OpenClaw 管理的 MCP 服务器的操作员视图。它本身不会启动 MCP 传输；可以使用它检查和编辑已保存的配置，需要实时服务器验证时再使用 openclaw mcp doctor --probe。

典型工作流：

1. 从侧边栏打开 MCP。
2. 检查摘要卡片中的服务器总数、已启用、OAuth 和已过滤服务器数量。
3. 检查每个服务器行中的传输、启用状态、身份验证、过滤器、超时和命令提示。
4. 在插件页面上管理服务器（添加、启用/禁用、移除）。该页面是 mcp.servers 唯一的交互式写入方；此处的行列表会链接到该页面。
5. 编辑限定范围的 mcp 配置部分，以设置服务器定义、请求头、TLS/mTLS 路径、OAuth 元数据、工具过滤器和 Codex 投影元数据。
6. 使用保存写入配置；如果需要让正在运行的 Gateway 网关应用更改后的配置，则使用保存并发布。
7. 从终端运行 openclaw mcp status --verbose、openclaw mcp doctor --probe 或 openclaw mcp reload，分别执行静态诊断、实时验证或清除缓存的运行时。

该页面会在渲染前对包含凭据的类 URL 值进行脱敏，并在命令片段中引用服务器名称，以确保复制的命令在名称包含空格或 shell 元字符时仍能正常运行。完整的 CLI 和配置参考：MCP。

活动选项卡

活动选项卡位于设置 › 系统中，紧邻日志和调试。它是一个临时的浏览器本地实时工具活动观察器，数据来自为聊天工具卡片提供支持的同一个 Gateway 网关 session.tool / 工具事件流。它不会添加其他 Gateway 网关事件系列、端点、持久活动存储、指标数据源或外部观察器流。

活动条目仅保留经过净化的摘要以及经过脱敏和截断的输出预览。工具参数值不会存储在活动状态中；UI 会显示参数已隐藏，并且只记录参数字段数量。内存中的列表随当前浏览器选项卡存在，在 Control UI 内导航时保留，并在页面重新加载、切换会话或点击清除时重置。

操作员终端

可停靠的操作员终端默认禁用。要启用它，请设置 gateway.terminal.enabled: true 并重启 Gateway 网关。终端需要 operator.admin 连接，并在活动 Agent 工作区中打开主机 PTY。新选项卡跟随当前选定的聊天智能体。

使用 Ctrl + 反引号 切换停靠面板。布局支持停靠在底部或右侧，可随浏览器视口调整大小，并可保留多个 shell 选项卡。有关 gateway.terminal.enabled 和可选的 gateway.terminal.shell 覆盖项，请参阅 Gateway 配置。

在会话侧边栏中发现的 Codex 和 Claude Code 会话可以在同一个终端面板内通过其原生 CLI 打开。在设置 › 聊天中，将 Codex/Claude 会话打开方式设置为终端，这样正常点击某一行时便会打开 codex resume 或 claude --resume；默认仍使用只读的 OpenClaw 查看器。行的右键菜单或三点菜单始终提供这两个选项；符合条件的会话还会在查看器标题栏中显示在终端中打开。

资格按会话和主机分别判定。Gateway 网关本地会话会在 Gateway 网关主机上启动由提供商负责的恢复命令。已配对节点上的会话会在所属节点上启动已加入允许列表的提供商命令，并且仅中继该 PTY 的输出、输入和调整大小事件；这不会暴露通用节点 shell，也不会接受浏览器提供的命令。未公布匹配的终端恢复命令的节点（包括不支持双工流式传输的嵌入式工作节点桥接器）仍可使用查看器，但会显示终端打开功能不可用。

会话在断开连接后仍会保留：页面重新加载、笔记本电脑休眠或网络短暂中断时，会话将在 Gateway 网关上分离而不是被终止；重新连接后，同一浏览器选项卡会重新附加，并重放最近的输出。已分离的会话会在 gateway.terminal.detachedSessionTimeoutSeconds 后终止（默认 300 秒；0 可恢复为断开连接时终止）。terminal.list 显示可附加的会话，terminal.attach 接管其中一个会话（类似 tmux 的接管），而 terminal.text 可在不附加的情况下以纯文本形式读取会话的最近输出，这是为智能体和工具提供的功能。

终端还可以通过 /?view=terminal 以全屏、仅包含终端的文档形式使用。iOS 和 Android 应用会将此页面嵌入其终端屏幕，并复用已存储的 Gateway 网关凭据；可用性受相同的 gateway.terminal.enabled 和 operator.admin 条件控制，当所连接的 Gateway 网关不提供终端时，该页面会显示通知。

浏览器面板

Control UI 提供了一个可停靠的浏览器面板，可在任何普通网页浏览器中呈现由 Gateway 网关控制的浏览器（即智能体通过浏览器工具操控的同一个浏览器），无需原生 WebView。当连接的 Gateway 网关向 operator.admin 连接公布 browser.request 时，该面板就会出现；会话工作区栏中的地球按钮可切换其显示状态。该面板显示实时页面快照，并提供选项卡、可编辑的 URL 栏、后退/前进/重新加载以及在你的浏览器中打开功能；可停靠在右侧或底部，并将点击、滚轮滚动和基本键盘输入转发到远程页面。

两种捕获模式可为智能体打包页面上下文：

• 标注（铅笔）：在页面上自由绘制标记。点击发送到聊天会将笔画合成到截图中，把图像附加到活动聊天编辑器，并预填一段提示词，其中描述页面 URL、标题以及每个标记区域，使智能体准确了解你圈出了哪些内容。
• 检查（指针）：悬停时查看光标下的元素（选择器、无障碍名称、角色、尺寸）；点击后会通过同一个编辑器流程发送该元素的详细信息以及突出显示后的截图。检查、滚轮滚动以及后退/前进功能需要 browser.evaluateEnabled（默认启用）。

macOS 应用会为在仪表板中点击的链接保留其原生链接浏览器侧边栏；浏览器面板也可在其中使用，并且是在其他所有平台上标注页面的方式。

聊天行为

连接丢失和重新连接

会话建立后，Gateway 网关连接中断不会将你登出。客户端使用退避机制（从 800 ms 到最长 15 s）自动重试期间，仪表板仍保持可见，顶部栏下方会显示一个浮动的琥珀色“Gateway 网关连接已丢失 — 正在重新连接…”胶囊提示。连接恢复前，实时更新以及实时/会话操作会暂停；胶囊提示中的 立即重试 会强制立即尝试连接。聊天内容仍可编辑：普通文本和附件发送内容会保存在当前标签页按 Gateway 网关/会话限定的浏览器存储中，显示为等待重新连接，并在 Gateway 网关恢复后自动发送。离线时，实时控件和斜杠命令仍不可用。

如果此浏览器已有凭据（已配置的令牌/密码或已批准的设备令牌），首次打开和重新加载时会在连接建立期间显示一个小型 OpenClaw 动画标志，而不会短暂显示登录门禁。仅当尚未存储凭据，或 Gateway 网关主动拒绝凭据（令牌/密码错误、配对已撤销）时，才会显示登录门禁——这些状态需要你提供输入，而不是继续等待。

PWA 安装和 Web Push

Control UI 提供 manifest.webmanifest 和 Service Worker，因此现代浏览器可以将其安装为独立 PWA。借助 Web Push，即使标签页或浏览器窗口未打开，Gateway 网关也能唤醒已安装的 PWA 并发送通知。

如果 OpenClaw 更新后页面立即显示 协议不匹配，请先使用 openclaw dashboard 重新打开仪表板并执行强制刷新。如果仍然失败，请清除仪表板来源的站点数据，或在浏览器无痕窗口中测试；旧标签页或浏览器 Service Worker 缓存可能继续运行更新前的 Control UI 软件包，并连接到较新的 Gateway 网关。

如需固定密钥（多主机部署、密钥轮换或测试），可通过 Gateway 网关进程上的环境变量覆盖 VAPID 密钥对：

• OPENCLAW_VAPID_PUBLIC_KEY
• OPENCLAW_VAPID_PRIVATE_KEY
• OPENCLAW_VAPID_SUBJECT（默认为 https://openclaw.ai）

Control UI 使用以下受权限范围限制的 Gateway 网关方法注册和测试浏览器订阅：

• push.web.vapidPublicKey 获取当前 VAPID 公钥。
• push.web.subscribe 注册一个 endpoint 以及 keys.p256dh/keys.auth。
• push.web.unsubscribe 移除已注册的端点。
• push.web.test 向调用方的订阅发送测试通知。

托管嵌入内容

助手消息可以使用 [embed ...] 短代码内联渲染托管的 Web 内容。iframe 沙箱策略由 gateway.controlUi.embedSandbox 控制：

内置 Canvas 插件还提供 show_widget，用于直接通过工具调用渲染自包含 SVG 或 HTML。浏览器会声明 inline-widgets Gateway 网关能力，聊天历史记录重新加载后，生成的 Canvas 文档仍然可用。来自渠道的运行不会获得此工具。

{  gateway: {    controlUi: {      embedSandbox: "scripts",    },  },}

默认情况下，绝对外部 http(s) 嵌入 URL 仍会被阻止。要允许 [embed url="https://..."] 加载第三方页面，请设置 gateway.controlUi.allowExternalEmbedUrls: true。

聊天消息宽度

聊天转录使用与编辑器对齐、居中且易于阅读的框架。助手和工具输出在该框架内保持左对齐，而用户气泡保持右对齐。宽屏显示器部署可以通过设置 gateway.controlUi.chatMessageMaxWidth 覆盖转录宽度，无需修改内置 CSS：

{  gateway: {    controlUi: {      chatMessageMaxWidth: "min(1280px, 82%)",    },  },}

该值会在传入浏览器前进行验证。支持的形式包括 960px 或 82% 等普通长度和百分比，以及受约束的 min(...)、max(...)、clamp(...)、calc(...) 和 fit-content(...) 宽度表达式。

Tailnet 访问（推荐）

openclaw gateway --tailscale serve

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

不安全的 HTTP

如果通过普通 HTTP（http://<lan-ip> 或 http://<tailscale-ip>）打开仪表板，浏览器会在非安全上下文中运行并阻止 WebCrypto。默认情况下，OpenClaw 会阻止没有设备身份的 Control UI 连接。

已记录的例外情况：

• 仅限 localhost 的不安全 HTTP 兼容模式，使用 gateway.controlUi.allowInsecureAuth=true
• 通过 gateway.auth.mode: "trusted-proxy" 成功完成操作员 Control UI 身份验证
• 应急使用的 gateway.controlUi.dangerouslyDisableDeviceAuth=true

**建议的修复方法：**使用 HTTPS（Tailscale Serve），或在本地通过 https://<magicdns>/（Serve）或 http://127.0.0.1:18789/（在 Gateway 网关主机上）打开 UI。

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

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

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

内容安全策略

Control UI 附带严格的 img-src 策略：仅允许同源资源、data: URL，以及本地生成的 blob: URL。远程 http(s) 和协议相对图片 URL 会被浏览器拒绝，并且绝不会发起网络获取请求。

实际行为如下：

• 通过相对路径提供的头像和图片（例如 /avatars/<id>）仍可正常呈现，包括 UI 获取并转换为本地 blob: URL 的已认证头像路由。
• 内联 data:image/... URL 仍可正常呈现。
• 由 Control UI 创建的本地 blob: URL 仍可正常呈现。
• GitHub 链接预览头像由 Gateway 网关从 GitHub 的固定头像主机获取，并以受限的 data: URL 返回；操作员的浏览器绝不会联系远程头像主机。
• 渠道元数据发出的远程头像 URL 会在 Control UI 的头像辅助函数中被移除，并替换为内置徽标/徽章，因此受到入侵或存在恶意行为的渠道无法强制操作员浏览器从任意远程地址获取图片。

此功能始终启用，且不可配置。

头像路由身份验证

配置 Gateway 网关身份验证后，Control UI 头像端点需要使用与 API 其余部分相同的 Gateway 网关令牌：

• GET /avatar/<agentId> 仅向已认证的调用方返回头像图片。GET /avatar/<agentId>?meta=1 按照相同规则返回头像元数据。
• 对任一路由的未认证请求都会被拒绝（与同级智能体媒体路由一致），因此头像路由不会在其他部分受到保护的主机上泄露智能体身份。
• Control UI 获取头像时会将 Gateway 网关令牌作为 bearer 标头转发，并使用经过身份验证的 blob URL，使图片仍能在仪表板中呈现。

如果禁用 Gateway 网关身份验证（不建议在共享主机上这样做），头像路由也会与 Gateway 网关的其余部分一样变为无需身份验证。

智能体媒体路由身份验证

配置 Gateway 网关身份验证后，智能体本地媒体预览使用两步路由：

• GET /__openclaw__/assistant-media?meta=1&source=<path> 需要常规的 Control UI 操作员身份验证；浏览器检查可用性时会将 Gateway 网关令牌作为 bearer 标头发送。
• 成功的元数据响应包含一个短期有效的 mediaTicket，其作用域仅限于该确切源路径。
• 浏览器呈现的图片、音频、视频和文档 URL 使用 mediaTicket=<ticket>，而不是有效的 Gateway 网关令牌或密码。该票据会很快过期，且无法授权其他源。

这样既能使媒体呈现与浏览器原生媒体元素兼容，又不会在可见的媒体 URL 中放入可重复使用的 Gateway 网关凭据。

审批链接

操作员审批通知可深度链接到保留的 ${controlUiBasePath}/approve/{approvalId} 命名空间下提供的独立审批文档（例如 /approve/<approvalId>，或配置基础路径时的 /openclaw/approve/<approvalId>）。该 URL 在审批的整个生命周期内保持稳定，并可安全地在你自己的设备之间转发：它仅标识审批，绝不会为审批授权。

• 单段 /approve/<approvalId> 命名空间由 Gateway 网关在插件 HTTP 路由之前为所有 HTTP 方法保留，因此插件路由绝不能遮蔽或截获审批文档。
• 打开审批文档需要使用与 Control UI 其余部分相同的 Gateway 网关身份验证（令牌/密码、Tailscale Serve 身份或可信代理身份）；凭据绝不会成为审批 URL 的一部分。
• 禁用 Control UI 服务时，对该命名空间的请求会返回 404，而不会回退到插件处理程序。
• 在审批文档中登录仅对该页面临时有效：它不会覆盖同一浏览器中完整 Control UI 保存的 Gateway 网关选择或设置。

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

pnpm ui:build

可选的绝对基础路径（固定资源 URL）：

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

本地开发（独立开发服务器）：

pnpm ui:dev

然后将 UI 指向你的 Gateway 网关 WS URL（例如 ws://127.0.0.1:18789）。

Control UI 空白页面

如果浏览器加载了空白仪表板，并且开发者工具未显示有用的错误，则可能是某个扩展程序或早期内容脚本阻止了 JavaScript 模块应用求值。静态页面包含一个纯 HTML 恢复面板；当启动后未注册 <openclaw-app> 时，该面板会显示。

更改浏览器环境后，使用面板中的重试操作；也可以在完成以下检查后手动重新加载：

• 禁用会向所有页面注入内容的扩展程序，尤其是带有 <all_urls> 内容脚本的扩展程序。
• 尝试使用隐私窗口、全新的浏览器配置文件或其他浏览器。
• 保持 Gateway 网关运行，并在更换浏览器后验证同一仪表板 URL。

调试/测试：开发服务器 + 远程 Gateway 网关

Control UI 由静态文件组成；WebSocket 目标可配置，并且可以与 HTTP 来源不同。当需要在本地运行 Vite 开发服务器，而 Gateway 网关在其他位置运行时，这会很方便。

pnpm ui:dev

http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789

http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>

{  gateway: {    controlUi: {      allowedOrigins: ["http://localhost:5173"],    },  },}

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

相关内容

• 仪表板 — Gateway 网关仪表板
• 健康检查 — Gateway 健康监控
• TUI — 终端用户界面
• WebChat — 基于浏览器的聊天界面