Control UI

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

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

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

查看正在运行的会话时，Gateway 网关可以使用该智能体的实用模型生成简洁的状态摘要。聊天界面将其显示为单行状态标签，展开后会显示一张卡片，其中包含评估、计划进度、PR 和已用时间。当运行卡住或需要输入时，卡片可以自动展开一次；/btw 侧边聊天的优先级高于展开的卡片。

展开的卡片还可以接收有关该次运行的简短问题。回答仅使用观察器当前的摘要和经过净化且长度受限的备注，只在该会话的浏览器中保留，并且绝不会进入或中断主智能体运行。如果观察内容中没有答案，观察器会说明它无法得知。

第一个摘要到达后，它将取代启发式实时活动，作为该次运行的侧边栏副标题。最终的完成或失败摘要会在会话未读期间保持可见，之后该行将恢复为正常的工作副标题。

会话观察默认启用。在 Settings > Appearance > Sidebar 中，可以在整个 Gateway 网关范围内将其关闭、查看解析后的小模型及其来源，或者选择自动路由、禁用实用任务，或明确选择一个 agents.defaults.utilityModel。对应的配置控制项为 gateway.controlUi.sessionObserver: false 和 agents.defaults.utilityModel: ""。

快速打开（本地）

如果 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 网关身份验证先于设备配对运行。直接 local loopback 连接不会绕过令牌或密码身份验证。仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留令牌；密码不会持久化。配对后，浏览器可在后续连接中使用其存储的每设备令牌。

新手引导通常会配置 Gateway 网关令牌以用于共享密钥身份验证。如果 Gateway 网关以令牌模式启动但未配置令牌，它会改为为该进程生成临时运行时令牌。运行时令牌不会写入配置，因此 openclaw config get gateway.auth.token 无法获取它，并且没有该令牌的 local loopback 浏览器会被拒绝。运行 openclaw doctor --generate-gateway-token，重启 Gateway 网关，然后将配置的令牌粘贴到 Control UI 设置中。当 gateway.auth.mode 为 "password" 时，也可以改用密码身份验证。

设备配对（首次连接）

Gateway 网关身份验证成功后，从新浏览器或设备连接通常需要进行一次性配对批准，显示为 disconnected (1008): pairing required。

openclaw devices list

openclaw devices approve <requestId>

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

将已配对的远程浏览器从读取权限切换为写入/管理员权限会被视为批准升级，而不是静默重新连接：OpenClaw 会保持旧批准有效，阻止权限更广的重新连接，并要求你明确批准新的权限范围集合。符合条件的直接 local loopback Control UI 连接可在通过身份验证后静默批准升级。

批准后，设备会被记住，无需再次批准，除非使用 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 网关主机状态

打开 Settings → General，即可查看 Gateway Host 卡片，其中显示 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 支持这些代码之前，它们可能不会出现在该选择器中。

外观主题

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

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

Appearance 还提供 Text size 设置。它适用于聊天文本、编辑器文本、工具卡片和聊天侧边栏，并确保文本输入框字号至少为 16px，防止移动版 Safari 在获得焦点时自动缩放。

主题、主题模式、文本大小、语言和聊天显示偏好通过 Gateway 网关配置（ui.prefs）同步，因此它们会在你的设备间保持一致，智能体也可以通过审批关卡更改这些偏好——已连接的客户端会通过 Gateway 网关的 config.changed 通知实时应用更改。每个浏览器都会保留一个本地副本，以便即时启动；无法写入配置的客户端（仅查看权限范围、离线）会将更改仅保留在设备本地。请参阅配置参考。

OpenClaw 系统维护

打开设置 → 询问 OpenClaw，与系统设置和修复智能体对话。在新手引导之外，此页面每次访问最多显示一个可关闭的事件提示标签。对于常规 Gateway 网关流量，它会保持静默，仅在健康快照报告配置重新加载器已禁用、已配置渠道断开连接或性能下降、渠道探测失败或渠道凭据不可用时作出响应。只有在新事件更严重时，它才会替换待处理的提示标签；关闭或使用提示标签后，本次访问期间将不再显示事件提示。点击提示标签会将其诊断问题作为一条真实的 openclaw.chat 消息发送，因此对话记录会记下该请求，并由 OpenClaw 执行诊断。新手引导期间绝不会显示这些事件提示标签。

管理插件

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

插件中心包含四个标签页：已安装和发现用于管理 /settings/plugins 中的插件代码，Skills在 /skills 中托管按智能体划分的技能管理器，工作坊则在 /skills/workshop 中托管技能工作坊提案审查。每个标签页都保留自己的 URL， 而侧边栏只显示一个统一的插件入口。

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

Skills标签页保留技能状态报告、启用/禁用开关、API 密钥输入框以及内嵌的 ClawHub 技能搜索，其作用域限定为所选智能体。 工作坊标签页保留技能工作坊看板和针对 技能提案的“今日”审查流程。查找技能创意会从新到旧审查一个有界范围内的重要会话，并将所有结果保留为待处理提案。面板会显示累计覆盖范围；扫描更早的工作 会从持久化游标处继续，较早的历史记录扫描完毕后则变为扫描新工作。 即使自主自我学习已禁用，也可以手动审查历史记录，并使用所选智能体已配置的模型。

内置插件已存在于 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。

应用和扩展

从侧边栏的更多菜单、命令面板或侧边栏智能体菜单（获取应用）打开 应用，也可以使用相对于已配置 Control UI 基础路径的 /apps。此页面汇集了每个 OpenClaw 配套界面的安装链接： iOS 和 Android 应用、 与它们捆绑提供的 Apple Watch 和 Wear OS 配套应用、 macOS、Windows 和 Linux 桌面应用、 Chrome 扩展程序、包含 ClawHub 的应用内插件中心，以及 Discord 社区和文档。

侧边栏导航

侧边栏以智能体为中心组织所有内容。顶部的身份行表示当前活动智能体；其下方的页面部分以主页开头——即智能体持续更新的主会话，并带有表示未读或运行状态的徽章——随后是固定的目标位置（默认为自动化和插件）。页面标题上的自定义控件会打开一个菜单，其中包含所有其他目标位置，包括用量和插件提供的标签页，以及编辑固定项目；右键点击导航区域可直接打开固定项目编辑器。下方的会话列表分为多个区域：话题用于智能体的聊天会话（主会话保留在主页下；由主会话生成的会话会作为顶层话题显示在这里，具名话题不显示类型前缀），群组用于群聊和房间对话，编码用于绑定到托管工作树或 Exec 节点的会话（每行显示一条 repo ⎇ branch 信息以及节点主机）、由 ACP 支持的 harness 会话，以及 Codex/Claude CLI 目录。编码区域首次运行时默认折叠，并会记住你的选择；折叠后的标题会保留真实数量，并在其中的会话运行时显示运行指示器。自定义群组（会话的 category）和已固定行位于话题上方，将会话分配给自定义群组始终优先于自动区域分类。话题标题包含排序控件（创建时间或最后更新时间、分组方式，以及持久化的状态筛选器：活动、已归档或全部）和用于打开新建会话页面的 +。已归档行仍显示在原位置，以较暗样式并附带归档图标；它们不计入未读或需要关注状态，也不参与谱系提升。打开会话会移动选择高亮，但不会重新排列各行。具有近期子运行的父会话会显示展开控件和子会话数量；展开后，无需离开侧边栏即可检查嵌套子会话、实时或终止状态以及运行时。选择子会话会打开其聊天，并自动显示其祖先路径。子会话行不参与根级分组、固定、拖动、多选和分页；折叠区域不会占用可见页面配额。自上次阅读后有新活动的会话会显示未读圆点，打开后即标记为已读。智能体还可以发布一条简短且会过期的状态信息，并可选择通过精心设计的琥珀色图标请求关注；当你打开该会话、发送下一条消息、明确清除该状态或其 TTL 到期时，此声明会被清除。云端工作节点的生命周期状态使用地球徽章；本地会话和已收回的会话不显示位置徽章，因为本地执行是默认方式。每个根会话行都有上下文菜单（更多按钮或右键点击），其中包含固定/取消固定、标记为未读/已读、重命名、派生、移至群组（包括新建群组和从群组中移除）、归档或取消归档，以及删除；触控布局会始终显示直接固定和菜单控件。按住 Cmd/Ctrl 点击可切换根会话行的多选状态，按住 Shift 点击可按可见顺序扩展选择范围；随后在所选行上打开菜单时，会提供批量操作（将 N 个标记为未读/已读、将 N 个移至群组、归档 N 个、删除 N 个），这些操作会应用于所有选中的会话，批量删除只需确认一次。将根会话拖到已固定即可固定，或拖到自定义群组即可移动。自定义群组标题可以折叠、展开或通过拖动重新排序；群组名称及其顺序存储在 Gateway 网关中（sessions.groups.*），因此会在浏览器间保持一致，而折叠状态则保留在浏览器配置文件中。群组标题也有菜单（更多按钮或右键点击），其中包含重命名群组、新建群组和删除群组；重命名或删除群组会在服务器端更新所有成员会话，包括已归档的会话，而删除群组会保留其中的会话并将其移回话题。

新建会话页面

侧边栏会话列表标题中的 + 会在 /new 打开一个全页面草稿：在你发送第一条消息之前，不会创建任何内容。统一的位置选择器用于选择工作文件夹，并允许管理员操作员选择执行目标：Gateway 网关 · 本地、公开 system.run 的已配对节点，或可用的云端配置文件。文件夹默认为 Agent 工作区；其他 Gateway 网关绝对路径需要 operator.admin，但无需是 Git 检出目录即可直接运行。当所选 Gateway 网关文件夹是 Git 检出目录时，同一选择器会提供可选的工作树隔离功能，其中包含由 worktrees.branches 支持的基础分支选择器（不执行 fetch），以及可选的工作树名称（分支将变为 openclaw/<name>）。云端工作节点必须使用该托管工作树路径；已配对节点绝不会提供此选项。编辑器页脚用于选择新会话的模型和推理级别。其中的隐身模式开关会创建一个仅限 Web 的话题，其会话条目、对话记录和压缩状态会一直保存在内存中，直到 Gateway 网关重启；OpenClaw 也会跳过其自动记忆刷新。智能体仍保留常规工具，因此明确的保存请求或由工具驱动的文件写入仍可能持久化数据。模型提供商仍会处理消息，并且不含内容的审计元数据仍会被记录。云端启动会在将会话分派给工作节点之前，持久化所选的模型和推理设置。

在多用户 Gateway 网关中，只有具有管理员权限范围的连接才能创建或查看隐身话题，其他会话也无法通过智能体会话工具或对话记录搜索访问它们。隐身模式可防止内容被持久存储或被其他经由 Gateway 网关的用户访问，但无法防范 Gateway 网关所有者或进程操作员，因为他们始终可以观察实时会话。

浏览文件夹会打开位置选择器的内嵌目录浏览器，该浏览器由仅限管理员使用的 fs.listDir 方法支持，其作用域限定为所选 Gateway 网关或节点。Gateway 网关和支持浏览的节点会列出其文件系统；不支持 fs.listDir 但具备执行能力的节点仍接受手动输入的绝对路径。最近使用的位置可以同时恢复文件夹及其所属节点，而不会在不同主机之间传递路径。提交时会调用 sessions.create 并附带第一条消息，因此运行会在同一次往返中启动，UI 随后跳转到新会话的聊天。如果 Gateway 网关创建了会话，但拒绝发送第一条消息，聊天会在重新加载后保留提示词和错误；重试会通过已创建的会话发送该消息，而不是再创建一个会话。

在设置中，专用侧边栏包含询问 OpenClaw，并在顶部提供搜索设置字段，以便快速查找设置部分。

在桌面网页中，内容区域左上角固定着一组控件——对应 macOS 标题栏条带的网页版本——其中包含侧边栏折叠开关（⌘B）和命令面板搜索按钮（⌘K）。点击侧边栏顶部的智能体身份行会打开智能体菜单；主页会打开主会话。当有事项需要处理时——定时任务失败或逾期、模型身份验证即将过期或已过期——侧边栏页脚上方会显示紧凑的提醒标签，点击即可前往对应页面。身份行显示智能体的头像（身份图片或表情符号）、名称、连接状态点和实时副标题。其智能体范围菜单包含内联智能体切换器（多智能体设置）、新建智能体、“此智能体能做什么？”和智能体设置。智能体超过十个时，名单会提供筛选字段并优先列出已置顶的智能体；可在智能体设置页面置顶或取消置顶智能体，置顶集合存储在浏览器配置文件中。选择智能体后，聊天以及用量、自动化、任务、Workboard 和会话都会限定到该智能体。每个限定范围的页面都提供一个智能体控件，并可通过所有智能体退出该范围；这会扩大共享页面的范围，但不会更改具体的聊天智能体，而直接会话链接仍会打开其目标。智能体设置页面保留自身的 ?agent= 选择，不跟随共享页面范围。页脚是一张占据全宽的身份卡片，离线时仍可使用，并会在最后已知的账户名称下方显示正在重新连接…。它会打开应用/账户菜单，其中的个人资料身份标题下依次为设置、用量、移动端配对、获取应用、帮助（帮助、Discord、文档和更新日志）、必要时显示的离线重试操作、版本/构建标签以及颜色模式开关。点击构建标签会打开“关于”页面。当 Gateway 网关从源码检出目录运行，且所在分支不是 main 时，页脚还会以红色显示该分支名称，以便一眼识别非发布版 Gateway 网关（发布版安装永远不会显示）。在 Apple 平台上按 Shift-Command-Comma，或在其他平台上按 Ctrl-Shift-Comma，可打开设置，且不会覆盖浏览器原有的 Command-Comma 快捷键。折叠侧边栏（通过 ⌘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 页面上添加、启用、禁用或移除服务器。明确选择 Streamable HTTP、SSE 或 stdio；stdio 命令行接受带引号的参数，例如包含空格的路径。使用插件页面进行一键连接和发现。
5. 编辑作用域内的 mcp 配置部分，以设置环境变量、工作目录、标头、TLS/mTLS 路径、OAuth 元数据、工具筛选器和 Codex 投影元数据等高级服务器字段。
6. 使用 Save 写入配置；如果要让正在运行的 Gateway 网关应用已更改的配置，请使用 Save & Publish。
7. 在终端中运行 openclaw mcp status --verbose、openclaw mcp doctor --probe 或 openclaw mcp reload，分别执行静态诊断、实时验证或清除缓存的运行时。

该页面会在渲染前隐去包含凭据的 URL 类值，并在命令片段中用引号括起服务器名称，因此复制的命令即使包含空格或 shell 元字符也仍能正常运行。完整的 CLI 和配置参考：MCP。

活动选项卡

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

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

操作员终端

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

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

经所有者授权且不受沙箱隔离的智能体可以使用 terminal 工具执行需要操作员观察的长时间或交互式工作。每次工具调用都可以打开、读取、写入、调整大小、关闭或列出该智能体自己的 Gateway 网关 PTY。新会话默认会打开一个共同连接的 Control UI 选项卡，使智能体和操作员共享输出，双方都可以输入或调整大小。智能体访问权限严格限定于具体会话：智能体无法读取或控制由操作员创建的终端，也无法读取或控制由其他智能体会话打开的终端。

将一个或多个文件拖到活动终端上，或使用回形针按钮选择文件。OpenClaw 会将每个文件暂存到 PTY 所在的机器上，并在光标处粘贴经过 shell 引号处理的绝对路径；它绝不会按 Enter 或执行输入。紧凑的批次指示器会显示当前文件和已完成数量。取消操作会停止批次中的剩余文件而不粘贴路径；传输失败的文件会保持可见，因此可以从该文件处重试，而无需重新上传已完成的文件。支持图片、PDF、压缩包及其他文件类型，每个文件最大 16 MiB。在 POSIX 主机上，暂存文件使用私有的系统临时目录（目录模式为 0700，文件模式为 0600）；在 Windows 上，则使用用户配置文件 ACL 边界内的目录，并设置 24 小时清理计时器，因此需要保留的内容应移动或复制到其他位置。

路径插入支持 PowerShell、cmd.exe 以及可识别的 POSIX shell（sh、Bash、Dash、Ash、Ksh、Zsh 和 Fish），包括 Windows 上的 Git Bash。系统会拒绝其他 shell 覆盖设置，因为无法安全推断其引号规则；要获得原生 WSL 终端和 Linux 上传路径，请在 WSL 内运行 Gateway 网关。包含 % 或 ! 的 cmd.exe 路径也会被拒绝，因为该 shell 即使在双引号内也会展开这些字符。

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

资格按会话和主机分别确定。Gateway 网关本地会话会在 Gateway 网关主机上启动由提供商所有的恢复命令。已配对节点会在所属节点上启动允许列表中的提供商命令，并且仅中继该 PTY 的输出、输入和调整大小事件；这不会暴露通用节点 shell，也不会接受浏览器提供的命令。文件上传使用独立且有大小限制的 terminal.upload 节点命令，并始终绑定到已打开的终端会话。该命令首次出现时，请批准节点配对升级。未声明匹配终端恢复命令的节点（包括不支持双工流式传输的嵌入式工作节点桥接器）仍可使用查看器，但会显示终端打开功能不可用；旧版节点仍可运行终端，但无法接收拖入的文件。

连接所有的会话可在断开连接后继续存活：页面重新加载、笔记本电脑休眠或短暂网络中断时，会话会在 Gateway 网关上分离，而不是被终止；重新连接后，同一浏览器选项卡会重新连接该会话并重放最近的输出。分离的连接所有会话会在 gateway.terminal.detachedSessionTimeoutSeconds 后被终止（默认 300 秒；0 可恢复为断开连接即终止）。连接到这类会话时，仍采用类似 tmux 的接管方式。

智能体所有的会话不绑定到浏览器连接。terminal.attach 会将每个浏览器添加为查看器，而不会取得所有权；关闭查看器选项卡只会分离该浏览器。PTY 会持续运行，直到所属智能体将其关闭、其进程退出、策略将其禁用或 Gateway 网关关闭。terminal.list 会将每个条目标记为连接所有或智能体所有；terminal.text 允许管理员连接在不附加会话的情况下读取最近的纯文本输出。

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

浏览器面板

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

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

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

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

聊天行为

连接丢失和重新连接

会话建立后，Gateway 网关连接断开不会让你退出登录。客户端使用退避策略（从 800 ms 到最多 15 s）自动重试时，控制面板会保持可见，并在顶部栏下方显示一个悬浮的琥珀色“Gateway connection lost — Reconnecting…”胶囊提示。连接恢复前，实时更新以及实时/会话操作会暂停；胶囊提示中的 Retry now 会强制立即尝试重新连接。聊天内容仍可编辑：普通文本和附件发送会保存在当前标签页按 Gateway 网关/会话限定范围的浏览器存储中，显示为等待重新连接，并在 Gateway 网关恢复后自动发送。离线期间，实时控件和斜杠命令仍不可用，但 Stop 可以将确切的本地运行 ID 加入队列以便重放。仅针对会话的停止操作不会重放，因为连接恢复前该会话中可能已经启动了较新的任务。

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

PWA 安装和 Web Push

Control UI 随附 manifest.webmanifest 和一个 Service Worker，因此现代浏览器可以将其安装为独立 PWA。即使标签页或浏览器窗口未打开，Web Push 也允许 Gateway 网关通过通知唤醒已安装的 PWA。

在 macOS 应用内，通知设置页面显示应用的原生通知权限，而不是浏览器推送权限，因为应用通过原生方式发送通知。

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

从已弃用的 push/vapid-keys.json 和 push/web-push-subscriptions.json 存储升级时，openclaw doctor --fix 会导入其中的数据。运行该修复前请停止 Gateway 网关，以免旧进程在导入期间重新创建已弃用的状态。升级后使用 Web Push 前请运行该修复；只要任一已弃用来源或中断的 Doctor 声明仍然存在，注册、投递、删除和密钥解析都会拒绝继续执行。Gateway 网关运行时仅对 SQLite 进行读写。

如果需要固定密钥（多主机部署、机密轮换或测试），可通过 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 控制：

核心 show_widget 工具直接通过工具调用呈现自包含的 SVG 或 HTML。浏览器和受支持的原生聊天客户端会公布 inline-widgets Gateway 网关能力，聊天历史重新加载后，生成的 Canvas 文档仍然可用。Discord Activities 在 Discord 上提供同名工具；来自其他渠道的运行不会获得该工具。

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

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

聊天对话记录布局

聊天记录采用与编辑器对齐、居中且易于阅读的框架。在该框架内，助手和工具的输出保持左对齐，而你自己的消息保持右对齐。在多用户会话中（例如由渠道插件中继的群聊），来自其他已标明身份的参与者的消息会左对齐显示，并附带作者的头像、姓名以及每个身份对应的稳定颜色，因此只有已登录查看者的消息会被视为“我的消息”。当存在两名或更多已标明身份的参与者时，助手回复会带有一个小型“正在回复姓名”标记，指出触发该轮次的参与者。系统条目（例如本地斜杠命令输出）会呈现为不带头像的居中通知行。

聊天消息宽度

使用宽屏显示器时，可以在 设置 → 聊天 → 消息宽度 下覆盖聊天记录宽度。该偏好设置保存在相应浏览器的本地存储中。支持的 形式包括普通长度和百分比，例如 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 连接。

受支持的无设备身份例外是通过 gateway.auth.mode: "trusted-proxy" 成功完成操作员 Control UI 身份验证。不存在可禁用设备身份的持久化配置开关。

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

有关 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 网关令牌或密码。该凭据很快过期，且无法授权其他源。

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

审批链接

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

• Gateway 网关会在插件 HTTP 路由之前，为所有 HTTP 方法保留单段式 /approve/<approvalId> 命名空间，因此插件路由绝不可能遮蔽或拦截审批文档。
• 打开审批文档需要与 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 空白页面

如果浏览器加载了空白仪表板，并且 DevTools 未显示有用的错误，则可能是某个扩展或提前运行的内容脚本阻止了 JavaScript 模块应用求值。静态页面包含一个纯 HTML 恢复面板，如果启动后 <openclaw-app> 未注册，该面板便会出现。

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

• 禁用会向所有页面注入内容的扩展，尤其是带有 <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 — 基于浏览器的聊天界面