> ## Documentation Index > Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt > Use this file to discover all available pages before exploring further. # 控制 UI 控制 UI 是一个由 Gateway 提供的、基于 **Vite + Lit** 的单页应用： * 默认：`http://:18789/` * 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`） 它通过同一端口上**直接**连接到 Gateway WebSocket。 当你查看一个正在运行的会话时，Gateway 会立即将模型最新的安全前导语作为会话标题显示出来。如果有可用的实用模型，在积累了足够的活动后，它可以用更丰富的紧凑状态摘要来替换该标题。聊天在一个 **会话侧栏** 中呈现结果：其紧凑胶囊显示实时摘要，而展开后的侧栏显示评估、计划进度、拉取请求、已用时间，以及一个只读的伴随线程。当运行变得卡住或需要输入时，侧栏可以展开一次；而已完成或失败的运行则会保留一个冻结的“已完成”时间，该时间基于最终摘要。在宽聊天面板中，展开后的侧栏会停靠为右侧 400 px 的列；在较窄和移动端布局中，它则保持为覆盖层。 伴随线程会在不进入或不中断主代理运行的情况下，回答关于所选会话及其项目的问题。它使用实用模型，并对目标会话的历史/搜索以及代理工作区具有只读访问权限。这个有边界的线程保存在 Gateway 内存中，当你在控制 UI 中切换会话时会被恢复，并且会在侧栏的垃圾桶按钮、会话重置、Gateway 重启或空闲过期后被清除。它永远不会进入 `chat.history`。在主控制 UI 的编辑器中输入 `/btw ` 或 `/side ` 即可打开侧栏并在其中提问；其他客户端会保持其现有的 BTW 行为。 在聊天消息中高亮文本会提供 **更多详情**，它会立即询问伴随线程，以及 **在侧边聊天中提问**，它会打开侧栏并附上一份可编辑的引用草稿。 该标题拥有该运行的侧边栏副标题，而不是依赖启发式的实时活动。它会与官方 iOS 和 Android 会话列表共享。最终完成或失败的摘要在会话未读期间仍会可见，之后该行会恢复为其正常的工作副标题。 会话观察默认已启用。安全前导语标题不需要实用模型；实用模型只负责更丰富的评估和终态摘要。在 **设置 > 外观 > 侧栏** 中，你可以在整个 gateway 范围内关闭观察，检查已解析的小模型及其来源，或者选择自动路由、禁用实用任务，或显式选择 `agents.defaults.utilityModel`。等效的配置控制项是 `gateway.controlUi.sessionObserver: false` 和 `agents.defaults.utilityModel: ""`。 ## 快速打开（本地） 如果 Gateway 正在同一台电脑上运行，请打开 [http://127.0.0.1:18789/](http://127.0.0.1:18789/)（或 [http://localhost:18789/](http://localhost:18789/)）。 如果页面无法加载，请先启动 Gateway：`openclaw gateway`。 在原生 Windows LAN 绑定中，即使 `127.0.0.1` 在 Gateway 主机上可用，Windows 防火墙或组织管理的组策略仍可能阻止所显示的 LAN URL。请在 Windows 主机上运行 `openclaw gateway status --deep`；它会报告可能被阻止的端口、配置文件不匹配以及本地防火墙规则，而这些规则可能会被策略忽略。 认证会在 WebSocket 握手期间通过以下方式提供： * `connect.params.auth.token` * `connect.params.auth.password` * 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份头 * 当 `gateway.auth.mode: "trusted-proxy"` 时使用受信任代理身份头 Gateway 身份验证在设备配对之前执行。直接的回环连接不会绕过令牌或密码认证。仪表盘设置面板会为当前浏览器标签页会话和所选 Gateway URL 保留一个令牌；密码不会持久化。配对后，浏览器在后续连接中可以使用其为每个设备存储的令牌。 引导流程通常会为共享密钥认证配置 Gateway 令牌。如果 Gateway 在令牌模式下启动时未配置令牌，则会为该进程生成一个临时运行时令牌。运行时令牌不会写入配置，因此无法恢复；不带有该令牌的回环浏览器连接也会被拒绝。运行 `openclaw doctor --generate-gateway-token`，重启 Gateway，然后在交互式终端中运行 `openclaw gateway auth-token --show`，并将输出粘贴到 Control UI 设置中。当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码认证。 ## 设备配对（首次连接） 网关认证成功后，从新浏览器或设备进行连接通常需要**一次性配对批准**，此时会显示 `disconnected (1008): pairing required`。在网关主机上，`openclaw dashboard` 是推荐的所有者操作路径：它会打开一个短期有效、仅可使用一次的配对链接，并为该确切的已签名浏览器保留持久的管理员凭据。在同一浏览器中打开新的链接，也可以修复之前受限的凭据；其他浏览器配置文件无法继承或重放此授权。 当你从一个使用已弃用的 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` 破窗设置的版本直接升级时， OpenClaw 会保留基于令牌/密码或受信任代理认证的 Control UI 访问， 仅用于配对修复。如果浏览器处于普通 HTTP 且无法创建设备身份， 请先通过 HTTPS 或 localhost 重新打开它。然后在警告横幅中点击 **保护此浏览器**。 网关只有在已签名的浏览器明确完成配对后，才会恢复正常的设备认证强制；它绝不会为无设备身份的浏览器创建或批准身份。 当另一位操作员设备已经配对时，此迁移不可用。 Gateway 启动和 `openclaw doctor --fix` 都会明确报告此次迁移，而不是静默丢弃旧密钥。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw devices list ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw devices approve ``` 如果浏览器使用变更后的认证信息（角色/作用域/公钥）重试配对，之前的待处理请求会被新的请求覆盖，并创建新的 `requestId`；在批准前请重新运行 `openclaw devices list`。 通过普通的已存储或共享凭据，将已配对浏览器从读取权限切换为写入/管理员权限，会被视为权限批准升级，而不是静默重新连接：OpenClaw 会保留旧的批准，阻止权限更宽的重新连接，并要求你明确批准新的作用域集合。唯一的狭义例外是由网关主机上的 `openclaw dashboard` 或图形化引导流程发起的新所有者交接；它只能升级兑换该一次性交接的同一个已签名浏览器。 一旦批准，设备就会被记住，除非你使用 `openclaw devices revoke --device --role ` 撤销它，否则不会再次要求重新批准。有关令牌轮换、撤销，以及 Paperclip / `openclaw_gateway` 首次运行批准流程，请参阅 [设备 CLI](/cli/devices)。 * 来自回环 TCP 对等端（`127.0.0.1` 或 `::1`，通常通过 `localhost` 访问）的直接本地 Control UI 连接，在没有转发/代理标头的情况下，只有在网关认证成功且浏览器提供设备身份后，才能自动批准设备配对。在令牌/密码模式下，首次连接仍需要配置的共享密钥；此自动批准并不绕过令牌验证。 * 只有在明确配置 `gateway.auth.mode: "none"` 时，直接回环连接才不需要共享密钥。这会禁用网关认证，并不是推荐的 Control UI 设置。只有在各自的身份检查成功时，Tailscale Serve 和受信任代理模式才能避免粘贴共享密钥。 * 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证成功且浏览器提供其设备身份时，Tailscale Serve 可以为 Control UI 操作员会话跳过配对往返。无设备身份的浏览器和节点角色连接仍遵循正常的设备检查。 * 直接 Tailnet 绑定和局域网浏览器连接仍需要显式批准。没有设备身份的浏览器配置无法使用回环自动批准。 * 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据都需要重新配对。 * 隐私窗口以及退出时会丢弃网站数据的浏览器配置文件（包括 Firefox 的“从不记住历史记录”模式）也会丢弃存储的设备身份和按设备区分的令牌。它们每次重启后都会显示为新浏览器；请使用持久化的浏览器配置文件以保持配对，并在已配对设备列表变得过长时，使用 `openclaw devices remove ` 删除过时条目。 ## 配对移动设备 已配对的管理员无需打开终端即可创建 iOS/Android 连接二维码： 选择 **设备**，然后在 **设备** 卡片中点击 **配对移动设备**。 在 OpenClaw 移动应用中，打开 **设置** → **网关** 并扫描二维码。你也可以改为复制并粘贴设置代码。 官方 iOS/Android 应用会自动连接。如果 **待批准** 显示有请求，请在批准前检查其角色和权限范围。 创建设置代码需要 `operator.admin`；对于不具备该权限的会话，该按钮会被禁用。设置代码包含一个短期有效的引导凭据，因此在其有效期间，请将二维码和复制的代码视为密码。对于远程配对，Gateway 必须解析为 `wss://`（例如，通过 Tailscale Serve/Funnel）；普通的 `ws://` 仅限于回环和私有局域网地址。有关完整的安全性和回退细节，请参见 [配对](/channels/pairing#pair-from-the-control-ui-recommended)。 ## 个人身份（浏览器本地） 控制 UI 支持为每个浏览器提供一个个人身份（显示名称和头像），并附加到发出的消息中，用于在共享会话中的归属标识。它存储在浏览器存储中，作用范围限定于当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久保存，超出你发送消息上的正常会话记录作者元数据范围。清除站点数据或切换浏览器会将其重置为空。 助手头像覆盖遵循相同的浏览器本地模式：上传的覆盖内容会在本地叠加到网关解析出的身份上，并且不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段对于直接写入该字段的非 UI 客户端仍然可用。 ## 运行时配置端点 控制 UI 从 `/control-ui-config.json` 获取其运行时设置，该路径相对于网关的控制 UI 基础路径解析（例如，在基础路径为 `/__openclaw__/` 时，解析为 `/__openclaw__/control-ui-config.json`）。该端点受网关 HTTP 身份验证保护：未经身份验证的浏览器无法获取它，成功获取需要有效的网关令牌/密码或受信任的代理身份。Tailscale 标头身份验证适用于控制 UI WebSocket，而不适用于此 HTTP 端点。 ## 网关主机状态 打开 **设置 → 连接**，即可查看 **网关主机**卡片，其中包含网关机器、局域网地址、操作系统、运行时、运行时间、CPU 负载、内存和状态卷磁盘空间。卡片在可见时会通过 `system.info` 网关 RPC 每 10 秒刷新一次，该 RPC 需要 `operator.read` 作用域。较旧的网关以及不具备该作用域的连接不会显示此卡片。 ## 语言支持 控制界面会根据浏览器区域设置在首次加载时进行本地化。若要稍后覆盖此设置，请打开 **设置 → 外观 → 语言**。 * 支持的区域设置：`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 编辑器](https://tweakcn.com/editor/theme)，选择或创建一个主题，点击 **分享**，然后将复制的链接粘贴到外观面板中。导入器也接受 `https://tweakcn.com/r/themes/` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对路径 `/themes/`、原始主题 ID，以及默认主题名称（例如 `amethyst-haze`）。 导入的主题仅存储在当前浏览器配置中；它们不会写入网关配置，也不会在设备之间同步。替换已导入的主题会更新这个本地槽位；如果清除此项且该导入主题正处于启用状态，则会切回 Claw。 外观面板还提供了文本大小设置。它适用于聊天文本、消息编辑器文本、工具卡片和聊天侧边栏，并会将文本输入框至少保持为 16px，以免移动端 Safari 在聚焦时自动缩放。 主题、主题模式、语言和聊天显示偏好会通过网关配置（`ui.prefs`）同步，因此这些设置会随你在不同设备和代理之间同步；代理可以通过审批门控更改这些设置——已连接的客户端会通过网关的 `config.changed` 通知实时应用更改。每个浏览器都会保留一个本地镜像，以便即时启动。文本大小仍仅保存在浏览器本地。显式设置为只读的连接只会在该浏览器中应用偏好更改，不会尝试写入配置。离线期间所做的更改会一直排队，直到之后建立连接并能够写入配置；在只读重连时，这些更改仍会继续作为浏览器本地偏好处理。请参阅[配置参考](/gateway/configuration-reference#ui)。 ## OpenClaw 系统维护 打开 **Settings → Ask OpenClaw**，即可与系统设置和修复代理对话。页面会渲染一个居中的聊天界面，带有动画版的 OpenClaw 吉祥物；当有轮次正在进行时，它会切换为思考姿势。对话不会被困在 Settings 中：线程工作区栏中的龙虾按钮会将同一个实时会话切换为可停靠面板（位于右侧或底部，位置和大小会保存在浏览器配置文件中），而在完整页面对话进行到一半时离开页面会自动将聊天最小化到该停靠区，因此会话会跟随你。完整的 Ask OpenClaw 页面打开时，停靠区会自动隐藏。 每条聊天消息都会携带你当前正在查看的 Control UI 页面，作为不受信任的环境提示，因此像“配置这个频道”或“为什么这个页面是空的？”之类的请求，会根据你正在查看的页面来解析。 引导式频道设置、工作区技能设置、网页搜索提供商设置和本地 Gateway 设置会作为托管向导在聊天中运行。向导问题会保留在对话中，涉及机密信息的步骤会在浏览器中遮蔽输入，成功的配置流程会被审计并重新验证。如果所选的网页搜索提供商需要安装插件，而安装失败，设置流程会停止并报告失败，而不是假装提供商已经配置完成。 对于 Gateway 设置，请说 `configure gateway`，以选择端口、绑定地址、令牌或密码身份验证，以及 Tailscale 暴露方式。在第一个问题出现之前，网页界面会警告：应用已保存的设置需要重启，这可能会导致聊天断开，或需要重新登录 Control UI。向导只会修改配置；准备好应用设置时，请说 `restart gateway`。它只管理本地 Gateway，因此远程模式的更改仍需在 `openclaw onboard` 或 `openclaw configure` 中进行。 请说 `import memory`，将检测到的本地记忆复制到现有的默认代理工作区中。此流程不会更改配置，也不会导入凭据或技能，不需要重启 Gateway，并会区分已确认的导入、没有可导入内容、提供商失败，以及可能已有部分文件被复制的失败情况。如果默认工作区不存在，请先完成入门流程。关于可以针对其他代理或替换现有导入的更广泛页面，请参阅[导入助手记忆](#import-assistant-memory)，有关操作和审批约定，请参阅 [`openclaw setup`](/cli/openclaw)。 在入门流程之外，此页面每次访问最多只会显示一个可关闭的事件标签。它对常规 Gateway 流量保持静默，只对报告以下情况的健康快照作出反应：配置重新加载器已禁用、已配置的频道断开连接/降级、频道探测失败，或频道凭据不可用。只有当更新后的事件更严重时，才会替换待处理标签；关闭标签或使用标签后，该次访问的事件提示将被静音。点击标签会将其诊断问题作为真实的 `openclaw.chat` 消息发送，因此对话记录会保留该请求，而 OpenClaw 会执行诊断。入门流程从不显示这些事件标签。 ## 管理插件 在侧边栏中打开 **Plugins**，或者使用相对于已配置 Control UI 基础路径的 `/settings/plugins`，即可在不离开 Control UI 的情况下浏览和管理插件。例如，基础路径为 `/openclaw` 时，会使用 `/openclaw/settings/plugins`。即使所有可选插件都被禁用，该页面也始终可用。 Plugins 是一个包含四个选项卡的中心：**Installed** 和 **Discover** 用于在 `/settings/plugins` 管理插件代码，**Skills** 承载位于 `/skills` 的每个代理技能管理器，**Workshop** 承载位于 `/skills/workshop` 的 Skill Workshop 提案审核。每个选项卡都有自己独立的 URL，侧边栏则对所有选项卡仅显示一个 Plugins 入口。 **Installed** 选项卡会按类别分组显示完整的本地清单，并提供概览计数。每一行都可以打开详情视图；其溢出菜单（`…`）可用于启用或禁用插件，并为外部安装的插件提供 **Remove** 选项。该选项卡还会列出已配置的 [MCP 服务器](/cli/mcp)，并支持直接添加、禁用和移除服务器。相同的服务器控制项也位于 **Settings → MCP**。**Discover** 选项卡是插件商店：其中包含 OpenClaw 自带的精选插件、官方外部插件，以及适用于热门服务的一键式 MCP 连接器。在搜索框中输入内容会以内嵌方式查询 [ClawHub](https://clawhub.ai/plugins)，并追加一个 **From ClawHub** 区块，其中显示下载次数和来源验证徽章。可以使用 `/settings/plugins/discover` 直接打开商店。 **Skills** 选项卡保留技能状态报告、启用/禁用切换、API 密钥输入，以及就地 ClawHub 技能搜索，范围限定于所选代理。**Workshop** 选项卡保留 Skill Workshop 看板和面向 [skill proposals](/tools/skill-workshop) 的 Today 审核流程。**Find skill ideas** 会回顾从最新到最旧的一段有限范围内的重要会话，并将任何结果作为待处理提案保留。该面板显示累计覆盖范围；**Scan earlier work** 会从持久化的游标继续扫描，直到更早的历史耗尽后，按钮会变为 **Scan new work**。当自动自学习被禁用时，手动历史审查仍可工作，并使用所选代理已配置的模型。 内置插件已经存在于 Gateway 上，并显示 **Enable** 或 **Disable**，而不是 **Install**。例如，Workboard 已随 OpenClaw 包含但默认禁用，因此其操作是 **Enable**。捆绑插件不能被移除，只能被禁用。 读取目录和搜索 ClawHub 需要 `operator.read`。安装、启用、禁用或移除插件，以及更改 MCP 服务器，需要 `operator.admin`；对于只读操作者，这些操作会保持禁用状态。 ClawHub 安装通过 Gateway 运行，并与其他由 Gateway 中介的安装保持相同的信任、完整性和插件安装策略检查。安装或移除插件代码需要重启 Gateway。启用或禁用已安装的插件，在插件和当前 Gateway 运行时都支持的情况下可以无需重启；否则 UI 会提示需要重启。基于 OAuth 的 MCP 连接器在添加后，需要通过 CLI 执行一次 `openclaw mcp login `。 该页面有意聚焦于清单、发现、安装、启用和移除。对于任意 npm、git 或本地路径来源、更新以及高级插件配置，请使用 [`openclaw plugins`](/cli/plugins)。 ## 应用和扩展 从侧边栏 **更多** 菜单、命令面板或侧边栏代理菜单（**获取应用**）中打开 **应用**，或者使用相对于已配置 Control UI 基础路径的 `/apps`。该页面汇集了 OpenClaw 各个配套界面的安装链接： [iOS](/platforms/ios) 和 [Android](/platforms/android) 应用，以及随附其中的 Apple Watch 和 Wear OS 配套应用，[macOS](/platforms/macos)、[Windows](/platforms/windows) 和 [Linux](/platforms/linux) 桌面应用，[Chrome 扩展](/tools/chrome-extension)，应用内插件中心 [ClawHub](https://clawhub.ai)，以及 Discord 社区和文档。 ## 侧边栏导航 侧边栏围绕代理组织所有内容。顶部的身份行是当前活动代理；其下方，**页面** 部分以 **主页** 开头——这是代理的滚动主会话，带有未读或运行中状态标记——随后是固定的目的地（默认是 **自动化** 和 **插件**）。页面标题上的自定义控件会打开一个菜单，包含其他所有目的地，包括 **用量** 和由插件提供的选项卡，以及 **编辑固定项目**；在导航区域上右键会直接打开固定项编辑器。下方的会话列表分为几个区域：**线程** 用于代理的聊天会话（主会话保留在主页之后；它创建的会话会作为顶级线程出现在这里，命名线程则不带类型前缀）、**群组** 用于群组和房间对话，以及 **编码** 用于绑定到受管理工作树或执行节点的会话（行内显示 `repo ⎇ branch` 以及节点主机），还包括基于 ACP 的 harness 会话，以及 Codex/Claude CLI 目录。编码在首次运行时默认折叠，并会记住你的选择；其折叠后的标题会保留真实数量，并在其中包含的会话工作时显示运行中指示器。自定义分组（会话的 `category`）和 **已固定** 行位于线程之上，将会话分配到自定义分组始终优先于自动区域分类。线程标题包含排序控件（创建时间或最后更新、分组方式，以及持久化的 **状态** 过滤器：活跃、已归档或全部）和打开新建会话页面的 **+**。已归档行保持内联显示，带有归档图标并呈灰暗状态；它们不计入未读或关注状态，也不会参与血缘晋升。打开会话只会移动选中高亮，不会重新排序行。具有近期子运行的父会话会显示展开箭头和子项数量；展开后可在不离开侧边栏的情况下查看嵌套子会话、实时或终止状态以及运行时间。选择某个子会话会打开其聊天并自动显示其祖先路径。子行不参与根级分组、固定、拖拽、多选和分页；折叠的区域不会消耗可见页面预算。自上次阅读后有新活动的会话会显示未读圆点，打开后会将其标记为已读。代理还可以发布一条简短的、会过期的状态行，并可选地使用精心设计的琥珀色图标请求关注；当你打开会话、发送下一条消息、显式清除它或其 TTL 到期时，该声明会消失。云工作器生命周期状态使用地球徽标；本地和已回收会话不显示位置徽标，因为本地执行是默认行为。每个根会话行都有一个上下文菜单（三点按钮或右键），包含固定/取消固定、标记为未读/已读、重命名、分叉、移动到分组（包括新建分组和从分组中移除）、归档或取消归档，以及删除；触控布局会保持直接固定和菜单控件可见。Cmd/Ctrl 单击可将根行切换为多选，Shift 单击会沿可见顺序扩展选择；在已选行上打开菜单时，会提供批量操作（将 N 个标记为未读/已读、将 N 个移动到分组、归档 N 个、删除 N 个），这些操作会应用于所有已选会话，批量删除只需一次确认。将根会话拖到 **已固定** 上即可固定它，或拖到自定义分组上将其移动过去。自定义分组标题可以折叠、展开或拖动以重新排序；分组名称及其顺序保存在网关（`sessions.groups.*`）中，因此会在不同浏览器间同步，而折叠状态则保留在浏览器配置文件中。分组标题也有菜单（三点按钮或右键），包含重命名分组、新建分组和删除分组；重命名或删除分组会在服务器端更新所有成员会话，包括已归档的会话，而删除分组会保留其会话并将它们移回线程。 ## 新会话页面 侧边栏会话列表标题中的 **+** 会在 `/new` 打开一个整页草稿：在发送第一条消息之前不会创建任何内容。统一的 **位置** 选择器用于选择工作文件夹；对于管理员操作员，还可选择执行目标：**Gateway · 本地**、公开 `system.run` 的配对节点，或可用的云配置文件。文件夹默认指向代理工作区；若要使用另一条 Gateway 绝对路径，则需要 `operator.admin`，但它可以直接运行，无需是 Git 检出目录。当所选的 Gateway 文件夹是 Git 检出目录时，同一个选择器会提供可选的 **Worktree** 隔离，并带有一个由 `worktrees.branches` 支持的基础分支选择器（不执行 fetch）以及可选的 worktree 名称（分支将变为 `openclaw/`）。云工作节点需要该受管 worktree 路径；配对节点则从不显示它。撰写区底部栏用于选择新会话的模型和推理级别。其 **隐身** 开关会创建一个仅限网页的线程，其会话条目、转录和压缩状态都会保留在内存中，直到 Gateway 重启；OpenClaw 也会跳过其自动内存刷新。代理仍然保留其正常工具，因此显式保存请求或工具驱动的文件写入仍可能持久化数据。模型提供方仍会处理消息，且无内容的审计元数据仍会被记录。云端启动会在把会话派发到其工作节点之前，先持久化其模型和推理选择。 在多用户 gateway 上，只有管理员范围的连接才能创建或查看隐身线程，其他会话也无法通过代理会话工具或转录搜索访问它们。隐身保护的是存储以及其他经由 gateway 中介的用户，而不是 gateway 所有者或进程操作员；后者始终可以观察实时会话。 **浏览文件夹** 会打开位置选择器内联的目录浏览器，它由仅管理员可用的 `fs.listDir` 方法支持，并限定在所选的 Gateway 或节点范围内。Gateway 和支持浏览的节点会列出其文件系统；一个具备执行能力但没有 `fs.listDir` 的节点仍然接受输入的绝对路径。最近位置可以将文件夹及其所属节点一并恢复，而不会跨主机携带路径。提交时会调用 `sessions.create` 并附带第一条消息，因此运行会在同一次往返中开始，UI 也会跳转到新会话的聊天界面。如果 Gateway 创建了会话但拒绝了那次首发消息，聊天在重新加载后会保留提示词和错误；**重试** 会通过已创建的会话重新发送，而不是再创建一个新的。 在 **设置** 中，专用侧边栏包含 **询问 OpenClaw**，并以一个 **搜索设置** 字段开头，用于快速查找设置分区。 在桌面网页端，内容区域左上角有一个固定的控制组——它是 macOS 标题栏条带的网页对应物——其中包含侧边栏折叠切换（⌘B）和命令面板搜索按钮（⌘K）。点击侧边栏顶部的代理身份行会打开代理菜单；**主页** 会打开主会话。当需要处理某些事项时——如失败或逾期的 cron 作业、即将过期或已过期的模型授权——会在侧边栏底部栏上方显示紧凑的提醒徽标，并可点击跳转到对应页面。身份行显示代理的头像（身份图片或表情符号）、名称、连接状态点以及实时副标题。其按代理范围的菜单包含内联代理切换器（多代理设置）、**新建代理**、"这个代理能做什么？" 和 **代理设置**。超过十个代理的名单会显示过滤字段，并优先列出已固定的代理；可在代理设置页面固定或取消固定代理，固定集合保存在浏览器配置文件中。选择某个代理会将聊天、用量、自动化、任务、工作板和会话限定到该代理。每个受限页面都提供一个 **代理** 控件，其中 **所有代理** 作为退出选项；这会扩大共享页面范围，但不会改变具体的聊天代理，而直接会话链接仍会打开其目标会话。代理设置页面保持其自己的 [URL 选择](/web/urls#route-table)，不会跟随共享页面范围。底部栏是一张通栏身份卡，即使离线也可用，并在上次已知的账户名称下方显示 **正在重新连接…**。它会打开应用/账户菜单，其中的个人资料身份头部之后依次是 **设置**、**用量**、移动设备配对、**获取应用**、**帮助**（帮助、Discord、文档和更新日志）、在需要时提供离线重试操作、版本/构建徽标以及颜色模式切换。构建徽标会打开关于页面。当 gateway 从源码检出目录运行且所在分支不是 `main` 时，底部栏还会用红色显示该分支名称，以便一眼看出这是非发布版 gateway（发布版安装从不显示它）。在 Apple 平台上按 Shift-Command-Comma，或在其他平台上按 Ctrl-Shift-Comma，会打开 **设置**，且不会覆盖浏览器原生的 Command-Comma 快捷键。折叠侧边栏（⌘B 或该控制组的切换按钮）会将其完全隐藏，以获得全宽工作区；在折叠状态下，左上角控制组会保留展开切换和搜索，并新增一个新线程按钮——这与 macOS 应用在标题栏中原生承载的内容相呼应。桌面端仅侧边栏是导航外壳，没有顶部栏。窄视口会将侧边栏替换为一个抽屉式侧滑面板，面板后方有一条紧凑的头部行，包含抽屉切换、品牌和命令面板搜索；在手机上，聊天会把那条导航行吸收到自己的标题栏中，菜单和搜索控件位于会话标题旁。在 macOS 应用中，单独的头部行会将标题栏留白折叠为控制按钮旁的一条紧凑条带。导航使用普通浏览器历史记录，因此浏览器的后退/前进按钮可以在其中切换；macOS 应用在窗口控制按钮旁增加了原生侧边栏切换，以及触控板滑动手势，并在侧边栏展开时于其右边缘提供后退/前进按钮，在折叠时提供原生搜索（命令面板）和新会话按钮。 待批准事项也会在侧边栏底部栏上方贡献一个提醒徽标；\ 选择它即可打开所属的审批页面。 ## 它目前能做什么 * 通过 Gateway WS（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）与模型聊天。已归档的会话会保持编辑框禁用，并在对话可以继续前显示带有 **取消归档** 操作的横幅。 * 聊天历史刷新会请求有界的最近窗口，并限制每条消息的文本长度，因此大型会话不会迫使浏览器在聊天可用前渲染完整的对话记录载荷。 * 将鼠标悬停在公开 GitHub issue 或 pull request 链接上，或使用键盘将其聚焦时，会显示其状态、标题、作者、近期活动、评论和变更统计信息。连接的 Gateway 会获取并缓存公开元数据，但不会更改链接目标，即使 UI 使用的是远程 Gateway 也是如此。Gateway 会在确认仓库为公开仓库后，在可用时使用 `GH_TOKEN` 或 `GITHUB_TOKEN`；否则会使用 GitHub 的匿名 API，并采用更长的缓存时间。 * 通过浏览器实时会话进行对话。OpenAI 支持浏览器 WebRTC 和由 Gateway 中继的提供方 WebSocket，Google Live 使用通过 WebSocket 传输的受限一次性浏览器令牌，而仅后端实时语音插件使用 Gateway 中继。支持视频的浏览器会话可以在设置中选择设备本地摄像头，或从实时预览中切换摄像头；浏览器会为实时提供方采集 JPEG 帧，而不会通过 Gateway 传输摄像头视频。客户端自有的提供方会话通过 `talk.client.create` 启动；Gateway 中继会话通过 `talk.session.create` 启动。中继会将提供方凭据保留在 Gateway 上，同时浏览器通过 `talk.session.appendAudio` 传输麦克风 PCM，将提供方委派或 `openclaw_agent_consult` 工具调用通过 Gateway 策略和配置更大的 OpenClaw 模型进行转发，并通过 `talk.client.steer` 或 `talk.session.steer` 路由活动运行中的语音控制。浏览器 WebRTC GPT-Live 在 Gateway 所有的 sideband 上进行委派，但每次委派都具有相同的语音确认门控和浏览器所有的 `talk.client.steer` 生命周期；更新的语音任务也可以取代正在运行的委派。Gateway 中继的 GPT-Live 使用常规的中继咨询和控制路径。在 **设置 → 对话** 中配置实时提供方、模型和扬声器语音，其选择器来自 `talk.catalog`，并显示所选项是否已准备好使用。 * 在聊天中串流工具调用和实时工具输出卡片（代理事件）。工具活动会以感知类型的行进行渲染：shell 命令显示带语法高亮的命令和终端样式输出；受支持的编辑和写入调用显示有界的内联差异、可用时显示行号，以及 `+新增 -删除` 统计信息；连续调用会折叠为类似“运行了 13 个命令，读取了 6 个文件，编辑了 9 个文件”的摘要。运行期间，最新的运行中调用会命名分组标题。展开某一行可查看其剩余参数和原始输出。 * 可选的 AI 目的标题用于复杂工具调用（较长的 shell 命令、参数较多的插件工具），通过 `gateway.controlUi.toolTitles: true` 启用（默认关闭）。标题来自批处理的 `chat.toolTitles` 方法，该方法通过标准实用模型路由——优先使用显式的 `utilityModel`（由操作员选择的提供方，与其他实用任务相同），否则使用会话提供方声明的小模型默认值——并在 Gateway 端按代理缓存。当选择退出时，或没有可用的廉价模型时，行会保留确定性标签，且不会发起模型调用。 * 启动或关闭模型建议的临时后续任务；接受建议后，会使用提议的提示词打开一个新的受管工作树会话。 * 活动选项卡提供基于浏览器本地、优先脱敏的现有 `session.tool` / 工具事件传送实时工具活动摘要。 * 频道：内置频道以及捆绑/外部插件频道的状态、二维码登录和按频道配置（`channels.status`、`web.login.*`、`config.patch`）。 * 频道探测刷新会在缓慢的提供方检查完成期间保持显示之前的快照，并在探测或审计超出 UI 时间预算时标记部分快照。 * 线程（`/sessions` 工作区页面，旁边还有 **工作树** 选项卡）：默认列出已配置代理的会话，固定常用会话，重命名会话，归档或恢复非活动会话，从过时的未配置代理会话键回退，并应用每个会话的模型/思考/快速/详细/追踪/推理覆盖项（`sessions.list`、`sessions.patch`）。三向 **活动 / 已归档 / 全部** 筛选器同时控制此页面和侧边栏；“全部”会调暗已归档行并明确标记它们。已归档会话会保留其记录，绝不会自动清理，并会一直搁置，直到明确取消归档或删除。活动会话自上次读取后有活动时，其行会显示未读点，并提供标记为未读/标记为已读操作（`sessions.patch { unread }`）；分支操作会将记录分支到新会话（`sessions.create { parentSessionKey, fork: true }`）。表格上方的概览磁贴会汇总已加载的会话列表（会话数量、实时运行数、未读会话数、总 token 数，以及可用时的已归档数量）；每一行带有类型图标和实时运行点，状态显示为普通圆点加标签；当会话报告 token 和上下文大小时，Tokens 列会显示上下文窗口使用率。行管理操作位于每行菜单中（省略号按钮或右键），与侧边栏的会话菜单相对应；行抽屉还会在其他会话详情旁显示代理运行时和运行时长。 * 原生 Claude 和 Codex 侧边栏目录每次串流一个主机，随后在节点连接状态变化、页面获得焦点以及可见期间最多每 30 秒重新协调一次。目录变化会触发更快的后续扫描，因此在原生工具中创建的会话无需重新加载 Control UI 即可显示。Claude Desktop 行在存在本地自定义分组标签时也会保留该标签；OpenClaw 从 Desktop 的本地存储中读取该映射，绝不会写入其中。 * 会话分组：“分组依据”控件可按自定义分组、频道、类型、代理或日期，将会话表组织成不同部分。自定义分组通过 `sessions.patch`（`category`）按会话持久化，因此从消息频道（Discord、Telegram、WhatsApp……）启动的会话也可以分类；可将行拖到某个部分上分配分组，也可使用每行的分组选择器，并通过“新建分组”操作创建分组。 * 记忆（Agents 页面中作用域限定为所选代理的选项卡）：梦境状态、启用/禁用切换和梦境日记阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。启用 `memory-wiki` 插件后，日记视图会增加 **导入的洞察** 和 **记忆 Wiki** 子选项卡，用于浏览导入的源聊天和编译后的 wiki——包括聚类综合、实体和概念页面，以及带注释的来源和报告，其中包含声明、未决问题、矛盾和内联页面预览（`wiki.importInsights`、`wiki.overview`、`wiki.get`）。 * 导入记忆（`/memory-import`，从 Agents 页面的“记忆”选项卡进入）：预览并将本地 Claude Code 自动记忆、Codex 合并记忆或 Hermes 记忆文件复制到所选代理工作区（`migrations.memory.plan`、`migrations.memory.apply`）。 * 引导记忆导入：当 Control UI 以[引导模式](/web/urls#special-documents-and-startup-modes)打开时，单页对话框会提供使用相同 plan/apply 流程导入检测到的记忆；跳过后，设置页面仍是之后的入口。 * 自动化（cron 作业）：在“自动化/运行历史”选项卡切换上方显示统计卡片（自动化数量、失败数量、调度器状态、下次唤醒）；“自动化”选项卡以可过滤表格列出作业（全部/活动/暂停、搜索、计划和最近运行过滤器、每行操作菜单），下方有起始建议，而“运行历史”选项卡显示所有自动化的最近运行（`cron.*`）。 * 任务：实时活跃与最近后台任务账本，带关联会话和取消功能（`tasks.*`）。聊天的后台任务侧栏会将运行中和已完成工作分组；选择某一行会在侧栏中打开一个紧凑的详情视图，包含返回按钮、受限提示词、实时活动以及输出或错误摘要。 * 插件：浏览已安装清单和精选商店，搜索 ClawHub，安装和移除插件代码，以及启用或禁用已安装插件（`plugins.*`）；MCP 服务器行通过配置方法编辑 `mcp.servers`。 * 技能：状态、启用/禁用、安装、API 密钥更新（`skills.*`）。 * 设备：一个清单整合了已配对设备记录、节点目录和在线存在状态（`device.pair.list`、`node.list`、`system-presence`）。Gateway 主机固定在最前；已配对客户端显示连接状态、角色、令牌、能力和命令。重复配对会折叠为可展开分组，而 **清理 N 个过时项** 会批量移除经管理员确认的离线重复项，这些重复项要么是自动批准的（静默本地、受信任 CIDR 或 SSH 验证），要么早于批准来源记录。可移除条目（`node.pair.remove`、`device.pair.remove`），设备配对和节点重新批准可在行内处理（`device.pair.*`、`node.pair.approve`/`reject`），移动设备设置代码也可从同一张卡片创建。 * 执行审批：编辑 gateway 或 node 允许列表，并为 `exec host=gateway/node` 询问策略（`exec.approvals.*`）。 * 查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。 * 设置导航顶部从询问 OpenClaw、个人资料、外观和通知开始；连接（连接、频道、通信、对话、设备）；代理与工具（代理、实验室、模型、MCP、记忆、自动化）；隐私与安全（安全、审批）；以及系统（基础设施、高级、调试、日志、关于）。语言位于外观页面，模型默认值位于模型页面，Gateway 主机详情位于连接页面。 * 隐私与安全：在由 schema 驱动的 `security`/`approvals` 部分上方，提供 Gateway 身份验证、执行策略、浏览器启用、工具配置文件、设备身份验证和移动配对的整理行。 * 审批包含已解决的执行、插件和系统代理请求按最新优先排列的 30 天历史记录。可按类型筛选，或翻阅较早的行，以查看 Gateway 记录的决定、原因、来源会话和解决者归属。 * Labs 展示已发布的实验性开关。当前条目为代码模式和群集，并会立即保存 `tools.codeMode.enabled` 和 `tools.swarm.enabled`；未发布的实验不会显示，也不会写入推测性的配置键。 * 通知：浏览器 Web Push 状态、订阅/取消订阅以及测试发送。 * 高级：所有没有专属整理入口的配置部分，以及原始 JSON5 编辑器（此前为“常规”页面的高级模式）。 * 模型设置（`/settings/model-setup`）是模型提供方的子页面，可从其标题栏进入。 * 代理：一个设置页面（**设置 → 代理**、`/settings/agents`），包含用于共享模板的 **代理默认值** 行，以及每个代理的选项卡（概览、文件、工具、技能、频道、自动化、记忆）。概览选项卡编辑代理身份——显示名称、表情符号和头像图片；浏览器会在 `agents.update` 之前对图片进行缩小并限制大小。保存会存储已配置的身份字段，并将其同步到工作区 `IDENTITY.md`；已配置的值优先于对同一文件字段的手动编辑。 * 个人资料：一个显示默认代理身份的设置页面，并提供全期使用统计——累计 token 数、峰值日期、最长会话、活动连续记录、一整年的 token 热力图、常用工具和频道亮点（`usage.cost`、`sessions.usage`）。 * MCP 有专用设置页面，其中包含服务器行（传输方式、启用状态、OAuth/筛选/并行摘要）、直接添加/启用/禁用/移除控件、常用操作员命令以及作用域限定的 `mcp` 配置编辑器。插件页面仍是一键连接器和发现功能的入口。 * 模型提供方：一个设置页面，列出每个已配置的模型提供方及其品牌图标、身份验证状态（`models.authStatus`）、模型可用性（`models.list`）、提供方报告的实时计划/配额/计费数据（`usage.status`），以及过去 30 天的本地会话支出（`sessions.usage`）。刷新操作会重新读取凭据状态和提供方使用情况。 * 连接：一个设置页面（位于 **连接** 下），负责管理控制面板自身的 Gateway 链接——WebSocket URL、Gateway 令牌、密码和默认会话键——以及最新握手快照（状态、运行时间、tick 间隔、上次频道刷新时间）。离线登录门负责处理断开连接的情况；此页面用于在连接状态下编辑连接。 * 通过验证应用并重启（`config.apply`），然后唤醒上次活动的会话。 * 写入操作包含基础哈希保护，以防覆盖并发编辑。 * 写入操作（`config.set`/`config.apply`/`config.patch`）会预先解析所提交配置载荷中引用的活动 SecretRef；未解析的活动提交引用会在写入前被拒绝。 * 表单保存会丢弃无法从已保存配置恢复的过时脱敏占位符，同时保留仍映射到已保存密钥的脱敏值。 * schema 和表单渲染来自 `config.schema` / `config.schema.lookup`，包括字段 `title`/`description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件和频道 schema。只有当快照具备安全的原始往返能力时，才提供原始 JSON 编辑器；否则 Control UI 会强制使用表单模式。 * 原始 JSON 编辑器的“重置为已保存”会保留原始编写的形状（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑会在重置后保留。 * 结构化 SecretRef 对象值在表单文本输入中以只读方式渲染，以防止意外将对象转换为字符串造成损坏。 * 基于会话的 token 和预估成本分析与提供方计费分开。 * 提供方卡片会调用 `usage.status`，并显示已配置提供方插件上报的实时计划名称、配额窗口、余额、支出和预算。 * 提供方使用情况失败不会阻塞会话/成本仪表板；不可用的提供方卡片会显示其自身错误状态。 * 调试：状态/健康状况/模型快照、事件日志，以及手动 RPC 调用（`status`、`health`、`models.list`）。 * 事件日志包含 Control UI 刷新/RPC 耗时、缓慢的聊天/配置渲染耗时，以及当浏览器暴露这些 PerformanceObserver 条目类型时，针对长动画帧或长任务的浏览器响应性条目。 * 日志：带过滤/导出的 Gateway 文件日志实时尾随（`logs.tail`）。 * 更新：执行包/git 更新并重启（`update.run`），附带重启报告，然后在重新连接后轮询 `update.status`，以验证正在运行的 Gateway 版本。 * 选择一行会打开全页详情视图，标题栏包含“活动/暂停”切换和“立即运行”（其菜单中还有“到期时运行”、克隆和移除）；“设置”选项卡可行内编辑自动化（提示词、详情、频率、高级覆盖项），“运行历史”选项卡显示该自动化的运行记录。 * 表格下方的起始自动化会使用可编辑的提示词和计划预填创建表单。 * 对于隔离任务，交付方式默认为发布摘要；切换为无则仅用于内部运行。 * 选择发布时会出现频道/目标字段。 * webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设为有效的 HTTP(S) webhook URL。 * 对于主会话任务，可使用 webhook 和无两种交付方式。 * 高级编辑控件包括运行后删除、清除代理覆盖项、cron 精确/错峰选项、代理模型/思考覆盖项，以及尽力交付切换。 * 表单验证为行内字段级错误；无效值会禁用保存按钮，直到修正为止。 * 将 `cron.webhookToken` 设为专用 bearer token；若省略，则 webhook 发送时不带认证头。 * `cron.webhook` 是已退役的旧回退项，会被当前配置验证拒绝。运行 `openclaw doctor --fix` 可迁移仍使用 `notify: true` 的已存储作业，使其改为显式的按作业 webhook 或完成交付，并移除旧键。 ## 导入助手记忆 打开 **设置** → **导入记忆**，将本地 Codex、Claude Code 或 Hermes 记忆导入 OpenClaw 代理。网关会在其自身主机上自动发现受支持的本地记忆，因此远程控制界面会从网关所在计算机导入，而不是从浏览器所在计算机导入。 1. 选择目标代理。 2. 审阅检测到的源集合和 Markdown 文件名。文件内容不会在计划响应中发送，也不会显示在页面上。 3. 选择要导入的集合并确认。应用会在写入前重新构建计划，因此过时的选择会安全失败。 4. 如果文件已存在，启用 **替换现有导入**，刷新预览，然后确认替换。 Codex 仅导入其汇总后的 `MEMORY.md` 和 `memory_summary.md`。Claude Code 会从项目自动记忆目录以及已配置的 `autoMemoryDirectory` 导入 Markdown；它不会通过此页面导入会话、设置、指令或凭据。文件会被复制到所选工作区下的 `memory/imports/` 中，活动记忆插件可在此对其进行索引。源文件不会被更改。 如需更简便的对话路径，请打开 **设置 → 询问 OpenClaw** 并说 `import memory`。聊天向导只会将新检测到的记忆复制到现有的默认代理工作区；它不会选择其他目标代理，也不会替换冲突项。它会报告每个源已确认的复制数量，并在可能于部分复制后发生失败时发出警告。当你需要选择目标、预览文件或进行替换时，请使用专用的导入记忆页面。 规划和应用需要 `operator.admin` 权限。每次应用都会在状态存在时创建经过验证的 OpenClaw 备份，写入已脱敏的迁移报告，并在替换现有目标文件前保留项目级备份。有关路径和召回行为，请参阅[记忆概览](/concepts/memory#import-from-coding-assistants)。 ## MCP 页面 专用的 MCP 页面是面向 OpenClaw 管理的 `mcp.servers` 下 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. 使用 **保存** 进行配置写入，或使用 **保存并发布** 让正在运行的 Gateway 应用更改后的配置。 7. 在终端中运行 `openclaw mcp status --verbose`、`openclaw mcp doctor --probe` 或 `openclaw mcp reload`，用于静态诊断、实时验证或清除缓存运行时。 在渲染之前，此页面会对包含凭据的类 URL 值进行脱敏，并在命令片段中为服务器名称加引号，这样复制后的命令在包含空格或 shell 元字符时仍可正常工作。完整的 CLI 和配置参考： [MCP](/cli/mcp)。 ## Activity 标签页 Activity 标签页位于 **Settings › System** 中，紧挨着 Logs 和 Debug。它是一个临时的、浏览器本地的观察器，用于查看实时工具活动，来源于与 Chat 工具卡片相同的 Gateway `session.tool` / 工具事件流。它不会添加另一种 Gateway 事件类别、端点、持久化活动存储、指标馈送或外部观察器流。 Activity 条目只保留已脱敏摘要和经过脱敏、截断的输出预览。工具参数值不会存储在 Activity 状态中；UI 会显示这些参数已被隐藏，并且只记录参数字段数量。内存中的列表会随当前浏览器标签页变化，在 Control UI 内导航时会保留，并在页面重新加载、会话切换或点击 **Clear** 时重置。 ## 操作终端 停靠式操作终端默认已启用；如需关闭，请设置 `gateway.terminal.enabled: false` 并重启 Gateway。终端需要 `operator.admin` 连接，并会在当前活跃的 agent 工作区中打开一个主机 PTY。新标签页会跟随当前选中的聊天 agent。 该终端是一个不受限制的主机 shell，并会继承 Gateway 进程环境。如果在不应让管理员操作员获得主机 shell 的部署中，请使用 `gateway.terminal.enabled: false` 将其禁用。对于 `sandbox.mode: "all"` 的 agent，OpenClaw 会拒绝终端会话；将某个活跃 agent 更改为该模式会关闭其现有的以及进行中的终端会话。 使用 **Ctrl + backtick** 切换停靠面板。布局支持底部和右侧停靠，会随浏览器视口调整大小，并可保留多个 shell 标签页。有关 `gateway.terminal.enabled` 以及可选的 `gateway.terminal.shell` 覆盖项，请参阅 [Gateway 配置](/gateway/configuration-reference#gateway)。 经所有者授权且未受沙箱限制的 agent 可使用 `terminal` 工具进行耗时或交互式工作，供操作员监看。每次工具调用都可打开、读取、写入、调整大小、关闭或列出该 agent 自己的 Gateway PTY。新会话默认会打开一个并排的 Control UI 标签页，因此 agent 和操作员共享输出，任一方都可以输入或调整大小。Agent 的访问权限严格限定在会话级别：某个 agent 不能读取或控制由操作员创建的终端，也不能读取或控制由其他 agent 会话打开的终端。 将一个或多个文件拖到活动终端上，或使用回形针按钮选择文件。OpenClaw 会把每个文件暂存到拥有该 PTY 的机器上，并在光标处粘贴带 Shell 引号的绝对路径；它绝不会按 Enter 或执行输入内容。紧凑的批次指示器会显示当前文件和已完成计数。取消会停止剩余批次而不会粘贴路径；失败的传输会保持可见，因此你可以从该文件继续重试，而无需重新上传已完成的文件。支持图片、PDF、压缩包及其他文件类型，每个文件最大 16 MiB。暂存文件会使用 POSIX 主机上的私有系统临时目录（目录模式 `0700`，文件模式 `0600`），或 Windows 上用户配置文件 ACL 边界下的目录，并附带 24 小时清理计时器，因此请将任何需要保留的内容移动或复制出来。 路径插入支持 PowerShell、`cmd.exe` 和已识别的 POSIX shells（`sh`、Bash、Dash、Ash、Ksh、Zsh 和 Fish），包括 Windows 上的 Git Bash。其他 shell 覆盖项会被拒绝，因为无法安全推断其引用规则；如需原生 WSL 终端和 Linux 上传路径，请在 WSL 内运行 Gateway。`cmd.exe` 中包含 `%` 或 `!` 的路径也会被拒绝，因为该 shell 即使在双引号内也会展开这些字符。 在 sessions 侧边栏中发现的 Codex 和 Claude Code 会话可以在同一终端面板内以其原生 CLI 打开。在 **Settings › Chat** 中，将 **Open Codex/Claude threads in** 设置为 **Terminal**，即可让普通行点击打开 `codex resume` 或 `claude --resume`；默认仍为只读的 OpenClaw 查看器。对某一行的右键菜单或三点菜单始终提供这两种选择，并且当该会话符合条件时，查看器标题栏会包含 **Open in terminal**。 资格判定按会话和主机分别进行。Gateway 本地会话会在 Gateway 主机上启动由提供方拥有的 resume 命令。成对节点会话会在所属节点上启动允许列表中的提供方命令，并且只转发该 PTY 的输出、输入和调整大小事件；这不会暴露通用节点 shell，也不会接受浏览器提供的命令。文件上传使用单独的、大小受限的 `terminal.upload` 节点命令，并且仍绑定到已打开的终端会话。请在该命令首次出现时批准节点配对升级。不提供匹配的 terminal-resume 命令的节点，包括没有双向流式传输的嵌入式 worker bridge，会继续保留查看器并将打开终端显示为不可用；较旧的节点仍然可以运行终端，但不能接收拖拽文件。 由连接拥有的会话在断开连接后会继续存在：页面刷新、笔记本睡眠或网络抖动不会终止会话，而是会在 Gateway 上解除绑定，之后同一浏览器标签页会在重新连接时重新附加，并回放最近的输出。已分离的连接拥有会话会在 `gateway.terminal.detachedSessionTimeoutSeconds` 之后被终止（默认 300 秒；设为 `0` 可恢复为断开即终止）。附加这类会话时仍采用 tmux 风格的接管方式。 由 agent 拥有的会话不绑定浏览器连接。`terminal.attach` 会将每个浏览器添加为查看者而不转移所有权，关闭查看器标签页只会分离该浏览器。PTY 会一直保留，直到拥有它的 agent 关闭它、其进程退出、策略将其禁用，或 Gateway 关闭。`terminal.list` 会将每个条目标记为由连接拥有或由 agent 拥有，`terminal.text` 则允许管理员连接在不附加的情况下读取最近的纯文本输出。 终端也可作为 [全屏终端文档](/web/urls#special-documents-and-startup-modes) 使用。iOS 和 Android 应用会在其 Terminal 界面中嵌入此页面，并复用已保存的 Gateway 凭据；可用性遵循相同的 `gateway.terminal.enabled` 和 `operator.admin` 门禁条件，并且当连接的 Gateway 不提供终端时，页面会显示提示。 ## 浏览器面板 Control UI 自带一个可停靠的浏览器面板，它会在任何普通网页浏览器中渲染由 Gateway 控制的浏览器（也就是代理通过 [浏览器工具](/tools/browser-control) 操作的那个浏览器）——无需原生 webview。当前连接的 Gateway 向 `operator.admin` 连接通告 `browser.request` 时，该面板会显示；线程工作区侧边栏中的地球按钮可切换它。该面板会显示带标签页的实时页面快照、可编辑的 URL 栏、后退/前进/刷新，以及在浏览器中打开，并可停靠在右侧或底部，同时将点击、滚轮滚动和基础输入转发到远程页面。 有两种捕获模式可为代理打包页面上下文： * **标注（铅笔）**：在页面上自由绘制标记。**发送到聊天** 会将这些笔画合成为截图，把图片附加到当前聊天编辑器，并预填一段提示，说明页面 URL、标题以及每个标记区域，这样代理就能准确知道你圈出了什么。 * **检查（指针）**：悬停可查看光标下的元素（选择器、可访问名称、角色、大小）；点击则会通过同样的编辑器流程发送该元素的详细信息以及一张高亮截图。检查、滚轮滚动和前进/后退需要 `browser.evaluateEnabled`（默认开启）。 macOS 应用会为在仪表盘中点击的链接保留其原生链接浏览器侧边栏；浏览器面板在该平台同样可用，并且是在其他所有平台上为页面添加标注的方式。 ## Composer 能力菜单 选择聊天编辑器旁边的 **+**，即可在一个菜单中打开附件和会话能力： * **技能** 可为此会话启用或禁用单个技能。 * **连接器** 可为此会话启用或禁用已配置的 MCP 服务器。**会话**标签会标记与继承配置不同的值。**浏览连接器**会在**发现**页面打开插件页面。 * **网页搜索** 可为此会话启用或禁用托管网页搜索，以及原生 OpenAI 和 Codex 搜索。 * **管理插件** 可打开插件页面。 这些控件是稀疏的会话覆盖项，类似于聊天标题栏中的模型和思考设置。未设置覆盖项的能力会继承当前代理或全局配置，而 OpenClaw 会在下一次运行实例化其工具和技能时应用解析后的值。编辑器页脚中的 **N 个会话覆盖项**标签可重新打开菜单；选择其中的清除操作，即可一键移除所有能力覆盖项。 在**连接器**中，管理员可以选择**添加 MCP 服务器…**并选择作用域。**此会话**会将服务器定义全局保存但默认禁用，然后仅在当前会话中启用。**处处**会将定义全局保存并启用。传输、身份验证及其他服务器定义字段始终是全局的。会话策略可以覆盖服务器启用状态，并通过**工具访问权限**拒绝单个工具。 一次运行发现连接器的工具后，**工具访问权限**会列出这些工具。在此之前，它会说明列表为空的原因，而不是报告工具数量为零：新添加的服务器尚未连接、已连接的服务器尚未完成工具列表，或者运行时目录早于配置更改。在 Codex 运行框架上运行的会话会将其 MCP 连接保留在 Codex 内部，因此其工具不会显示在此处。 能力开关会一直处于禁用状态，直到网关、会话和运行时配置加载完成；只读操作员无法更改这些开关。添加服务器需要管理员权限。请参阅[连接 MCP 服务器](/tools/mcp)，了解设置、CLI 和配置路径。 原文已经是中文，无需翻译。 ## 连接丢失与重新连接 一旦会话建立，Gateway 连接断开不会让你登出。仪表板仍会保持可见，顶栏下方会显示一个悬浮的琥珀色“Gateway 连接丢失 — 正在重新连接…”提示条；与此同时，客户端会以退避策略自动重试（800 ms 到 15 s）。在连接恢复之前，实时更新和 realtime/session 操作会暂停；提示条中的 **立即重试** 会强制立即尝试。聊天仍可编辑：普通文本和附件发送内容会保存在当前标签页的 gateway/session 作用域浏览器存储中，显示为等待重新连接，并在 Gateway 恢复后自动发送。离线期间，实时控制和斜杠命令仍不可用，不过 **停止** 可以排队一个精确的本地运行 ID 以供回放。仅限会话的停止不会被回放，因为在连接恢复前，该会话中可能已经开始了更新的工作。 当此浏览器已经持有凭据（已配置的 token/password 或已批准的设备 token）时，首次打开和重新加载会在连接建立期间显示一个小型动画 OpenClaw 标记，而不是闪现登录门。只有在尚未存储凭据，或 Gateway 主动拒绝它们（无效 token/password、已撤销的配对）时，才会显示登录门——这些状态需要你的输入，而不是等待。 ## PWA 安装和 Web Push Control UI 附带 `manifest.webmanifest` 和 service worker，因此现代浏览器可以将其安装为独立的 PWA。Web Push 允许 Gateway 在标签页或浏览器窗口未打开时也能通过通知唤醒已安装的 PWA。 在 macOS 应用中，Notifications 设置页面显示的是应用的原生通知权限，而不是浏览器推送，因为该应用是以原生方式投递通知的。 请参阅[通知](/web/notifications)，了解浏览器和 macOS 的设置步骤。 如果 OpenClaw 更新后页面立即显示 **协议不匹配**，请先使用 `openclaw dashboard` 重新打开控制面板，然后执行硬刷新。如果仍然失败，请清除控制面板来源的站点数据，或在浏览器隐私窗口中测试；旧标签页或浏览器 service worker 缓存可能会继续运行更新前的 Control UI 包，并尝试连接更新后的 Gateway。 | 位置 | 它的作用 | | -------------------------------------------------- | ------------------------------------ | | `ui/public/manifest.webmanifest` | PWA 清单。浏览器在可以访问到它后会提供“安装应用”。 | | `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 | | `state/openclaw.sqlite` → `web_push_vapid_keys` | 自动生成的 VAPID 密钥对，用于对 Web Push 载荷进行签名。 | | `state/openclaw.sqlite` → `web_push_subscriptions` | 持久化的浏览器订阅端点、密钥和注册时间戳。 | 从已废弃的 `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` 向已注册的浏览器订阅发送测试通知。 Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参见 [Configuration](/gateway/configuration)）以及 `push.test` 方法，后者面向原生移动端配对。 ## 托管嵌入 助手消息可以通过 `[embed ...]` 短代码以内联方式渲染托管的网页内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制： 核心的 [`show_widget`](/tools/show-widget) 工具会直接根据工具调用渲染自包含的 SVG 或 HTML。浏览器和受支持的原生聊天客户端会声明 `inline-widgets` Gateway 能力，并且在聊天历史重新加载时，生成的 Canvas 文档仍然可用。Discord Activities 在 Discord 上提供相同的工具名称；其他由频道发起的运行不会获得它。 禁用托管嵌入中的脚本执行。 允许交互式嵌入，同时保持源隔离；通常足以满足自包含的浏览器游戏/小部件。 在 `allow-scripts` 基础上添加 `allow-same-origin`，适用于那些有意需要更强权限的同站文档。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { controlUi: { embedSandbox: "scripts", }, }, } ``` 仅当嵌入文档确实需要同源行为时才使用 `trusted`。对于大多数 agent 生成的游戏和交互式画布，`scripts` 是更安全的选择。 绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。若要让 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。 ## 聊天记录布局 聊天记录使用一个居中的可读框架，并与输入区对齐。助手和工具输出保持左对齐，而你自己的消息在该框架内保持右对齐。在多用户会话中（例如从频道插件转发的群聊），来自其他已标注参与者的消息会左对齐显示，并带有作者头像、名称以及稳定的按身份着色，因此只有已登录查看者的消息会被视为“我的”。当存在两个或更多已标注参与者时，助手回复会带有一个小的“回复给 name”标记，用于标明触发该轮回复的参与者。系统条目（例如本地斜杠命令输出）会作为居中的通知行显示，不带头像。 ## 聊天消息宽度 宽屏显示器用户可以在 **Settings → Chat → Message width** 下覆盖对话记录的宽度。该偏好会保存在该浏览器的本地存储中。支持的 形式包括普通长度值和百分比，例如 `960px` 或 `82%`，以及受约束的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 宽度表达式。 ## Tailnet 访问（推荐） 让 Gateway 保持在 loopback 上运行，并让 Tailscale Serve 通过 HTTPS 代理它： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway --tailscale serve ``` 打开 `https:///`（或你配置的 `gateway.controlUi.basePath`）。 默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行身份验证。OpenClaw 会通过使用 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与标头进行匹配来验证身份，并且仅接受来自 loopback 且带有 Tailscale `x-forwarded-*` 标头的请求。对于使用浏览器设备身份的 Control UI 操作员会话，此经过验证的 Serve 路径还会跳过设备配对流程；无设备浏览器和节点角色连接仍会遵循正常的设备检查。若希望即使对于 Serve 流量也要求显式的共享密钥凭据，请将 `gateway.auth.allowTailscale: false`，然后使用 `gateway.auth.mode: "token"` 或 `"password"`。 对于该异步 Serve 身份验证路径，同一客户端 IP 和身份验证范围的失败身份验证尝试会在写入速率限制之前进行串行处理。因此，来自同一浏览器的并发错误重试可能会在第二个请求中显示 `retry later`，而不是让两个普通的不匹配请求并行竞争。 无令牌的 Serve 身份验证假定 Gateway 主机是受信任的。如果不受信任的本地代码可能在该主机上运行，请要求使用令牌/密码身份验证。 ## 不安全 HTTP 如果你通过普通 HTTP（`http://` 或 `http://`）打开仪表盘，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。OpenClaw 会拒绝没有设备身份的令牌/密码 Control UI 连接；共享密钥无法替代浏览器身份。 支持的无设备例外是通过 `gateway.auth.mode: "trusted-proxy"` 成功进行操作员 Control UI 认证。没有一个可持久化的配置开关可以禁用设备身份。 \*\*推荐修复：\*\*使用 HTTPS（Tailscale Serve）或在本地打开 UI：`https:///`（Serve）或 `http://127.0.0.1:18789/`（在 gateway 主机上）。 * 成功的可信代理认证可以允许**操作员** Control UI 会话在没有设备身份的情况下接入。 * 这不适用于节点角色的 Control UI 会话。 * 同主机回环反向代理要求同时在 `gateway.trustedProxies` 中配置回环地址，并将 `gateway.auth.trustedProxy.allowLoopback: true`；请参见[可信代理认证](/gateway/trusted-proxy-auth)。 有关 HTTPS 设置指南，请参见 [Tailscale](/gateway/tailscale)。 ## 内容安全策略 Control UI 实施了严格的 `img-src` 策略：仅允许**同源**资源、`data:` URL 和本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 将被浏览器拒绝，且不会发起网络请求。 实际使用中： * 通过相对路径提供的头像和图片（例如 `/avatars/`）仍然可以正常渲染，包括 UI 获取并转换为本地 `blob:` URL 的需要身份验证的头像路由。 * 内联的 `data:image/...` URL 仍然可以正常渲染。 * Control UI 创建的本地 `blob:` URL 仍然可以正常渲染。 * GitHub 链接预览头像由 Gateway 从 GitHub 的固定头像主机抓取，并以受限的 `data:` URL 返回；操作员浏览器不会连接远程头像主机。 * 通道元数据发出的远程头像 URL 会在 Control UI 的头像辅助逻辑中被移除，并替换为内置的 logo/badge，因此即使通道被攻破或恶意，也无法强制操作员浏览器发起任意远程图片请求。 此功能始终启用，且不可配置。 ## 头像路由认证 当配置了网关认证时，Control UI 的头像端点需要与 API 其余部分使用相同的网关令牌： * `GET /avatar/` 仅向已认证的调用方返回头像图像。`GET /avatar/?meta=1` 在相同规则下返回头像元数据。 * 对这两个路由的未认证请求都会被拒绝（与同级的 assistant-media 路由一致），因此在其他受保护的主机上，头像路由不会泄露 agent 身份。 * Control UI 在获取头像时会将网关令牌作为 bearer 头转发，并使用已认证的 blob URL，这样图像仍然可以在仪表板中正常渲染。 如果你禁用网关认证（不建议在共享主机上这样做），头像路由也会变为未认证，与网关其余部分保持一致。 ## 助手媒体路由认证 当配置了网关认证时，助手本地媒体预览使用一个两步路由： * `GET /__openclaw__/assistant-media?meta=1&source=` 需要正常的控制界面操作员认证；浏览器在检查可用性时会将网关令牌作为 bearer 头发送。 * 成功的元数据响应会包含一个短期有效的 `mediaTicket`，并且仅限于该精确的源路径。 * 浏览器渲染的图像、音频、视频和文档 URL 使用 `mediaTicket=`，而不是当前的网关令牌或密码。该票据会很快过期，且不能用于授权其他源。 这使媒体渲染能够兼容浏览器原生媒体元素，同时不会把可复用的网关凭据暴露在可见的媒体 URL 中。 位于 `/api/chat/media/outgoing/...` 下的生成图像通过 `artifacts.download` 使用相同的能力原则。经过身份验证的 WebSocket 请求会授权 transcript 工件，并返回一个短期有效的 URL。HTTP 媒体路由在提供字节前会重新检查该工件是否仍然属于该 transcript。在兼容性窗口期间，之前的共享所有者 bearer 路径仍可供较旧的控制界面客户端使用。 ## 审批链接 操作员审批通知可以深度链接到一个[独立的审批文档](/web/urls#special-documents-and-startup-modes)。该 URL 在审批的整个生命周期内保持稳定，并且可以安全地在你自己的设备之间转发：它标识的是审批本身，绝不会对其进行授权。 * 审批命名空间由网关预先保留，优先于所有 HTTP 方法的插件 HTTP 路由，因此插件路由永远不可能遮蔽或拦截审批文档。 * 打开审批文档需要与控制界面其余部分相同的网关认证（token/password、Tailscale Serve 身份或受信任代理身份）；凭据绝不会出现在审批 URL 中。 * 当控制界面服务被禁用时，对该命名空间的请求会返回 `404`，而不是继续交给插件处理程序。 * 在审批文档上登录是该页面的临时状态：它不会覆盖同一浏览器中由完整控制界面保存的网关选择或设置。 网关从 `dist/control-ui` 提供静态文件： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm ui:build ``` 可选的绝对基础路径（固定资源 URL）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build ``` 本地开发（独立开发服务器）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm ui:dev ``` 然后将 UI 指向你的网关 WS URL（例如 `ws://127.0.0.1:18789`）。 ## 空白控制界面 如果浏览器加载了空白仪表盘，并且开发者工具没有显示有用的错误，某个扩展或早期内容脚本可能阻止了 JavaScript 模块应用的执行。静态页面包含一个纯 HTML 恢复面板，当 `` 在启动后未注册时会出现。 在更改浏览器环境后，使用面板中的 **重试** 操作，或在完成以下检查后手动重新加载： * 禁用会注入到所有页面的扩展，尤其是带有 `` 内容脚本的扩展。 * 尝试无痕窗口、干净的浏览器配置文件，或其他浏览器。 * 保持网关运行，并在更改浏览器后验证同一个仪表盘 URL。 ## 调试/测试：开发服务器 + 远程 Gateway Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP origin。当你希望本地使用 Vite 开发服务器，而 Gateway 运行在其他地方时，这很方便。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm ui:dev ``` 按照 [远程 Gateway URL 交接](/web/urls#remote-gateway-handoff) 参考文档获取编码后的 Gateway URL 和可选的一次性凭据。 * 公共的、非回环的 Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整 origin）。来自回环地址、RFC1918/link-local、`.local`、`.ts.net` 或 Tailscale CGNAT 主机的私有同源 LAN/Tailnet 加载，无需启用 Host-header 回退即可接受。 * Gateway 启动时可能会根据实际运行时绑定地址和端口，注入本地 origin，例如 `http://localhost:` 和 `http://127.0.0.1:`，但远程浏览器 origin 仍然需要显式配置。 * 除非用于严格受控的本地测试，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`；这表示允许任何浏览器 origin，而不是“匹配我正在使用的任意主机”。 * `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host-header origin 回退模式，但这是一个危险的安全模式。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { controlUi: { allowedOrigins: ["http://localhost:5173"], }, }, } ``` 远程访问设置详情：[远程访问](/gateway/remote)。 ## 相关内容 * [仪表盘](/web/dashboard) — 网关仪表盘 * [健康检查](/gateway/health) — 网关健康监控 * [TUI](/web/tui) — 终端用户界面 * [WebChat](/web/webchat) — 基于浏览器的聊天界面。