[OpenClaw 文档]网关与运维--Web 界面

本文档汇总了 OpenClaw 官方文档站 网关与运维 > Web 界面 子模块下的全部 5 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 Web

原文：https://docs.openclaw.ai/zh-CN/web

Gateway 网关会在与 Gateway 网关 WebSocket 相同的端口上提供一个小型浏览器 Control UI（Vite + Lit）：

• 默认：http://<host>:18789/
• 启用 gateway.tls.enabled: true 时：https://<host>:18789/
• 可选前缀：设置 gateway.controlUi.basePath（例如 /openclaw）

功能请参见 Control UI。本页其余部分重点介绍绑定模式、安全性和面向 Web 的界面。

Webhook

当 hooks.enabled=true 时，Gateway 网关还会在同一个 HTTP 服务器上暴露一个小型 webhook 端点。
身份验证和负载请参见 Gateway 网关配置 → hooks。

配置（默认开启）

当资源存在（dist/control-ui）时，Control UI 默认启用。
你可以通过配置控制它：

{
  gateway: {
    controlUi: { enabled: true, basePath: "/openclaw" }, // basePath 可选
  },
}

Tailscale 访问

集成 Serve（推荐）

将 Gateway 网关保持在 local loopback 上，并让 Tailscale Serve 为其做反向代理：

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

然后启动 gateway：

openclaw gateway

打开：

• https://<magicdns>/（或你配置的 gateway.controlUi.basePath）

Tailnet 绑定 + token

{
  gateway: {
    bind: "tailnet",
    controlUi: { enabled: true },
    auth: { mode: "token", token: "your-token" },
  },
}

然后启动 gateway（这个非 local loopback 示例使用共享密钥 token
身份验证）：

openclaw gateway

打开：

• http://<tailscale-ip>:18789/（或你配置的 gateway.controlUi.basePath）

公网（Funnel）

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password" }, // 或 OPENCLAW_GATEWAY_PASSWORD
  },
}

安全说明

• 默认情况下需要 Gateway 网关身份验证（token、password、trusted-proxy，或在启用时使用 Tailscale Serve 身份请求头）。
• 非 local loopback 绑定仍然需要 gateway 身份验证。实际上，这意味着使用 token/password 身份验证，或带 gateway.auth.mode: "trusted-proxy" 的身份感知反向代理。
• 向导默认会创建共享密钥身份验证，并且通常会生成一个
  gateway token（即使在 local loopback 上也是如此）。
• 在共享密钥模式下，UI 会发送 connect.params.auth.token 或
  connect.params.auth.password。
• 当 gateway.tls.enabled: true 时，本地仪表板和 status 辅助工具会渲染
  https:// 仪表板 URL 和 wss:// WebSocket URL。
• 在带身份信息的模式下，例如 Tailscale Serve 或 trusted-proxy，WebSocket 身份验证检查则会改为从请求头中满足。
• 对于非 local loopback 的 Control UI 部署，请显式设置 gateway.controlUi.allowedOrigins
  （完整 origin）。如果不设置，默认会拒绝 gateway 启动。
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true 会启用
  Host 头 origin 回退模式，但这是危险的安全降级。
• 使用 Serve 时，当 gateway.auth.allowTailscale 为 true 时，
  Tailscale 身份请求头可满足 Control UI/WebSocket 身份验证（无需 token/password）。
  HTTP API 端点不会使用这些 Tailscale 身份请求头；它们仍遵循
  gateway 的常规 HTTP 身份验证模式。设置
  gateway.auth.allowTailscale: false 可要求显式凭证。请参见
  Tailscale 和 安全。这个
  无 token 流程假定 gateway 主机是受信任的。
• gateway.tailscale.mode: "funnel" 要求 gateway.auth.mode: "password"（共享密码）。

构建 UI

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

pnpm ui:build

📄 控制界面

原文：https://docs.openclaw.ai/zh-CN/web/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" 时，密码认证也可用。

设备配对（首次连接）

当你从新浏览器或设备连接到 Control UI 时，Gateway 网关通常会要求进行一次性配对批准。这是一项安全措施，用于防止未授权访问。

你会看到： “已断开连接 (1008)：需要配对”

bash
openclaw devices list

bash
openclaw devices approve <requestId>

如果浏览器使用已更改的认证详情（角色/作用域/公钥）重试配对，之前的待处理请求会被取代，并创建新的 requestId。批准前请重新运行 openclaw devices list。

如果浏览器已经配对，而你将其从读取访问改为写入/admin 访问，这会被视为批准升级，而不是静默重连。OpenClaw 会保持旧批准处于活动状态，阻止更宽泛的重连，并要求你明确批准新的作用域集合。

批准后，该设备会被记住，不会要求重新批准，除非你用 openclaw devices revoke --device <id> --role <role> 撤销它。请参阅 Devices CLI 了解令牌轮换和撤销。

- 直接 local loopback 浏览器连接（127.0.0.1 / localhost）会自动批准。
- 当 gateway.auth.allowTailscale: true、Tailscale 身份验证通过，并且浏览器提供其设备身份时，Tailscale Serve 可以为 Control UI 操作员会话跳过配对往返。
- 直接 Tailnet 绑定、LAN 浏览器连接，以及没有设备身份的浏览器配置文件仍需要明确批准。
- 每个浏览器配置文件都会生成唯一设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。

个人身份（浏览器本地）

Control UI 支持按浏览器设置的个人身份（显示名称和头像），会附加到传出消息，用于在共享会话中归因。它存储在浏览器存储中，限定于当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久化，除了你实际发送的消息上正常的 transcript 作者元数据。清除站点数据或切换浏览器会将其重置为空。

同样的浏览器本地模式也适用于 assistant 头像覆盖。上传的 assistant 头像只会在本地浏览器中覆盖 Gateway 网关解析出的身份，并且绝不会通过 config.patch 往返传输。共享的 ui.assistant.avatar 配置字段仍可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关或自定义仪表板）。

运行时配置端点

Control UI 会从 /__openclaw/control-ui-config.json 获取其运行时设置。该端点与 HTTP 表面的其余部分一样，受同一 Gateway 网关认证保护：未认证的浏览器无法获取它，成功获取需要已有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或可信代理身份。

语言支持

Control UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若稍后要覆盖它，请打开 Overview -> Gateway Access -> Language。区域设置选择器位于 Gateway Access 卡片中，而不是 Appearance 下。

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

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

外观主题

Appearance 面板保留内置的 Claw、Knot 和 Dash 主题，另加一个浏览器本地 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。

它现在能做什么

- 通过 Gateway 网关 WS 与模型聊天（chat.history、chat.send、chat.abort、chat.inject）。
- 聊天历史刷新会请求一个有界的近期窗口，并对每条消息设置文本上限，这样大型会话不会在聊天可用前强制浏览器渲染完整 transcript 负载。
- 通过浏览器实时会话进行 Talk。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，而仅后端实时语音插件使用 Gateway 网关中继传输。客户端拥有的提供商会话以 talk.client.create 开始；Gateway 网关中继会话以 talk.session.create 开始。中继会将提供商凭证保留在 Gateway 网关上，同时浏览器通过 talk.session.appendAudio 流式传输麦克风 PCM，并通过 talk.client.toolCall 转发 openclaw_agent_consult 提供商工具调用，以应用 Gateway 网关策略和更大的已配置 OpenClaw 模型。
- 在聊天中流式传输工具调用和实时工具输出卡片（智能体事件）。

- 渠道：内置渠道加上内置/外部插件渠道的状态、二维码登录和按渠道配置（channels.status、web.login.*、config.patch）。
- 渠道探测刷新会在较慢的提供商检查完成期间保持上一份快照可见；当探测或审核超过其 UI 预算时，会标记部分快照。
- 实例：在线状态列表 + 刷新（system-presence）。
- 会话：默认列出已配置智能体会话，从陈旧的未配置智能体会话键回退，并应用按会话的模型/thinking/fast/verbose/trace/reasoning 覆盖（sessions.list、sessions.patch）。
- Dreams：Dreaming 状态、启用/禁用开关，以及 Dream Diary 阅读器（doctor.memory.status、doctor.memory.dreamDiary、config.patch）。

- Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（cron.*）。
- Skills：状态、启用/禁用、安装、API key 更新（skills.*）。
- 节点：列表 + 能力（node.list）。
- Exec 批准：编辑 Gateway 网关或节点 allowlist + exec host=gateway/node 的询问策略（exec.approvals.*）。

- 查看/编辑 ~/.openclaw/openclaw.json（config.get、config.set）。
- 通过验证应用 + 重启（config.apply），并唤醒最后一个活动会话。
- 写入包含 base-hash 防护，以防覆盖并发编辑。
- 写入（config.set/config.apply/config.patch）会对提交的配置负载中的引用预检活动 SecretRef 解析；未解析的活动提交引用会在写入前被拒绝。
- Schema + 表单渲染（config.schema / config.schema.lookup，包括字段 title / description、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；Raw JSON 编辑器只有在快照具备安全原始往返能力时才可用。
- 如果快照无法安全往返原始文本，Control UI 会强制使用 Form 模式，并对该快照禁用 Raw 模式。
- Raw JSON 编辑器的 “Reset to saved” 会保留原始作者形态（格式、注释、$include 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑能在重置后保留。
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防意外发生对象到字符串的破坏性转换。

- 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（status、health、models.list）。
- 事件日志包含 Control UI 刷新/RPC 耗时、慢聊天/配置渲染耗时，以及当浏览器公开相关 PerformanceObserver 条目类型时记录的长动画帧或长任务浏览器响应性条目。
- 日志：带过滤/导出的 Gateway 网关文件日志实时 tail（logs.tail）。
- 更新：运行 package/git 更新 + 重启（update.run）并生成重启报告，然后在重新连接后轮询 update.status 以验证正在运行的 Gateway 网关版本。

- 对于隔离作业，投递默认会公告摘要。如果你想要仅内部运行，可以切换为 none。
- 当选择公告时，会显示渠道/目标字段。
- Webhook 模式使用 delivery.mode = "webhook"，并将 delivery.to 设置为有效的 HTTP(S) webhook URL。
- 对于主会话作业，webhook 和 none 投递模式可用。
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron exact/stagger 选项、智能体模型/thinking 覆盖，以及尽力而为投递开关。
- 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修复。
- 设置 cron.webhookToken 可发送专用 bearer token；如果省略，webhook 发送时不会带认证标头。
- 已弃用的回退：存储的旧作业如果带有 notify: true，在迁移前仍可使用 cron.webhook。

聊天行为

- chat.send 是非阻塞的：它会立即以 { runId, status: "started" } 确认，响应则通过 chat 事件流式传输。
- Chat 上传接受图片以及非视频文件。图片保留原生图片路径；其他文件会存储为托管媒体，并在历史记录中显示为附件链接。
- 使用相同的 idempotencyKey 重新发送时，运行期间会返回 { status: "in_flight" }，完成后会返回 { status: "ok" }。
- chat.history 响应会限制大小以保证 UI 安全。当转录条目过大时，Gateway 网关可能会截断长文本字段，省略较重的元数据块，并用占位符（[chat.history omitted: message too large]）替换过大的消息。
- 助手/生成的图片会持久化为托管媒体引用，并通过经过认证的 Gateway 网关媒体 URL 返回，因此重新加载不依赖原始 base64 图片载荷继续保留在聊天历史响应中。
- 渲染 chat.history 时，Control UI 会从可见助手文本中剥离仅用于显示的内联指令标签（例如 [[reply_to_*]] 和 [[audio_as_voice]]）、纯文本工具调用 XML 载荷（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 以及被截断的工具调用块），以及泄漏的 ASCII/全角模型控制令牌，并省略其全部可见文本仅为精确静默令牌 NO_REPLY / no_reply 或 Heartbeat 确认令牌 HEARTBEAT_OK 的助手条目。
- 在活跃发送期间以及最终历史刷新期间，如果 chat.history 短暂返回较旧的快照，聊天视图会继续显示本地乐观用户/助手消息；一旦 Gateway 网关历史追上，规范转录会替换这些本地消息。
- 实时 chat 事件表示投递状态，而 chat.history 是从持久会话转录重建的。工具最终事件之后，Control UI 会重新加载历史，并只合并一小段乐观尾部；转录边界记录在 WebChat 中。
- chat.inject 会向会话转录追加一条助手注记，并广播一个 chat 事件用于仅 UI 更新（无 agent 运行，无 channel 投递）。
- 聊天标题会先显示 agent 筛选器，再显示会话选择器，且会话选择器受所选 agent 限定。切换 agent 时，只显示与该 agent 绑定的会话；如果它还没有保存的仪表板会话，则回退到该 agent 的主会话。
- 在桌面宽度下，聊天控件会保持在一行紧凑排列，并在向下滚动转录时收起；向上滚动、回到顶部或到达底部时会恢复控件。
- 连续重复的纯文本消息会渲染为一个气泡并带有计数徽章。携带图片、附件、工具输出或画布预览的消息不会被折叠。
- 聊天标题中的模型和思考选择器会通过 sessions.patch 立即修补活跃会话；它们是持久会话覆盖项，而不是仅限单轮的发送选项。
- 如果你在同一会话的模型选择器更改仍在保存时发送消息，编辑器会先等待该会话补丁完成，再调用 chat.send，这样发送会使用所选模型。
- 在 Control UI 中输入 /new 会创建并切换到与 New Chat 相同的全新仪表板会话，但当配置了 session.dmScope: "main" 且当前父级是该 agent 的主会话时除外；在这种情况下，它会就地重置主会话。输入 /reset 会保留 Gateway 网关对当前会话的显式就地重置。
- 聊天模型选择器会请求 Gateway 网关配置的模型视图。如果存在 agents.defaults.models，该允许列表会驱动选择器，包括保持提供商范围目录动态的 provider/* 条目。否则，选择器会显示显式的 models.providers.*.models 条目以及具有可用认证的提供商。完整目录仍可通过调试 models.list RPC 并使用 view: "all" 获得。
- 当新的 Gateway 网关会话用量报告包含当前上下文令牌时，聊天编辑器区域会显示一个紧凑的上下文用量指示器。它会在上下文压力较高时切换为警告样式，并在达到建议压缩级别时显示一个紧凑按钮，用于运行常规会话压缩路径。过期的令牌快照会隐藏，直到 Gateway 网关再次报告新的用量。

Talk 模式使用已注册的实时语音提供商。配置 OpenAI 时，使用 talk.realtime.provider: "openai" 加上 talk.realtime.providers.openai.apiKey、OPENAI_API_KEY 或 openai-codex OAuth 配置文件之一；配置 Google 时，使用 talk.realtime.provider: "google" 加上 talk.realtime.providers.google.apiKey。浏览器绝不会收到标准提供商 API key。OpenAI 会收到一个用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到一个一次性受限 Live API 认证令牌，用于浏览器 WebSocket 会话，其中指令和工具声明由 Gateway 网关锁定到令牌中。只暴露后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭证和供应商套接字保留在服务器端，而浏览器音频会通过经过认证的 Gateway 网关 RPC 传输。Realtime 会话提示词由 Gateway 网关组装；talk.client.create 不接受调用方提供的指令覆盖。

Chat 编辑器在 Talk 开始/停止按钮旁包含一个 Talk 选项按钮。这些选项会应用于下一个 Talk 会话，并可覆盖提供商、传输、模型、语音、推理强度、VAD 阈值、静默时长和前缀填充。当某个选项为空时，Gateway 网关会在可用时使用配置的默认值，否则使用提供商默认值。选择 Gateway 网关中继会强制使用后端中继路径；选择 WebRTC 会保持会话由客户端拥有，如果提供商无法创建浏览器会话，则失败，而不是静默回退到中继。

在 Chat 编辑器中，Talk 控件是麦克风听写按钮旁的波形按钮。Talk 启动时，编辑器状态行先显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或者当实时工具调用正在通过 `talk.client.toolCall` 咨询配置的更大模型时显示 `Asking OpenClaw...`。

维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 后端 WebSocket 桥接、OpenAI 浏览器 WebRTC SDP 交换、Google Live 受限令牌浏览器 WebSocket 设置，以及带有模拟麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。

- 点击 Stop（调用 chat.abort）。
- 运行处于活跃状态时，普通后续消息会排队。点击排队消息上的 Steer，可将该后续消息注入正在运行的轮次。
- 输入 /stop（或独立的中止短语，如 stop、stop action、stop run、stop openclaw、please stop）以带外中止。
- chat.abort 支持 { sessionKey }（无 runId）来中止该会话的所有活跃运行。

- 当运行被中止时，部分助手文本仍可显示在 UI 中。
- 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中。
- 持久化条目包含中止元数据，使转录消费者可以区分中止部分和正常完成输出。

PWA 安装和 Web Push

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

当你想固定密钥（用于多主机部署、密钥轮换或测试）时，可在 Gateway 网关进程上通过环境变量覆盖 VAPID 密钥对：

• OPENCLAW_VAPID_PUBLIC_KEY
• OPENCLAW_VAPID_PRIVATE_KEY
• OPENCLAW_VAPID_SUBJECT（默认为 mailto:openclaw@localhost）

Control UI 使用这些受 scope 限制的 Gateway 网关方法来注册和测试浏览器订阅：

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

Web Push 独立于 iOS APNS 中继路径（参见 配置 了解由中继支持的推送）以及现有的 push.test 方法，后者面向原生移动配对。

托管嵌入

助手消息可以使用 shortcode 内联渲染托管 Web 内容。iframe 沙箱策略由 gateway.controlUi.embedSandbox 控制：

禁用托管嵌入中的脚本执行。

允许交互式嵌入，同时保持来源隔离；这是默认值，通常足够用于自包含的浏览器游戏/小组件。

在 allow-scripts 之上添加 allow-same-origin，用于有意需要更强权限的同站点文档。

示例：

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

仅当嵌入文档确实需要同源行为时才使用 trusted。对于大多数 agent 生成的游戏和交互式画布，scripts 是更安全的选择。

默认会继续阻止绝对外部 http(s) 嵌入 URL。如果你有意希望 加载第三方页面，请设置 gateway.controlUi.allowExternalEmbedUrls: true。

聊天消息宽度

分组聊天消息使用可读的默认最大宽度。宽屏部署可以通过设置 gateway.controlUi.chatMessageMaxWidth 来覆盖它，而无需修补内置 CSS：

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

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

Tailnet 访问（推荐）

将 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 通过 HTTPS 代理它：

```bash
openclaw gateway --tailscale serve
```

打开：

- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）

默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行身份验证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与该标头匹配来验证身份，并且只有当请求通过 local loopback 且带有 Tailscale 的 `x-forwarded-*` 标头命中时才接受这些请求。对于带有浏览器设备身份的 Control UI 操作员会话，这条已验证的 Serve 路径也会跳过设备配对往返；无设备浏览器和节点角色连接仍会遵循正常的设备检查。如果你希望即使对 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。

对于这条异步 Serve 身份路径，来自同一客户端 IP 和身份验证作用域的失败身份验证尝试，会在写入速率限制之前被串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配请求并行竞争。

<Warning>
无令牌 Serve 身份验证假定 Gateway 网关主机可信。如果不受信任的本地代码可能在该主机上运行，请要求令牌/密码身份验证。
</Warning>

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

然后打开：

- `http://<tailscale-ip>:18789/`（或你配置的 `gateway.controlUi.basePath`）

将匹配的共享密钥粘贴到 UI 设置中（作为 `connect.params.auth.token` 或 `connect.params.auth.password` 发送）。

不安全的 HTTP

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

已记录的例外：

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

推荐修复：使用 HTTPS（Tailscale Serve）或在本地打开 UI：

• https://<magicdns>/（Serve）
• http://127.0.0.1:18789/（在 Gateway 网关主机上）

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

`allowInsecureAuth` 只是本地兼容性开关：

- 它允许 localhost Control UI 会话在非安全 HTTP 上下文中无设备身份继续进行。
- 它不会绕过配对检查。
- 它不会放宽远程（非 localhost）设备身份要求。

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

<Warning>
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，是严重的安全降级。紧急使用后请尽快恢复。
</Warning>

- 成功的可信代理身份验证可以允许操作员 Control UI 会话无设备身份进入。
- 这不会扩展到节点角色 Control UI 会话。
- 同主机 local loopback 反向代理仍然不满足可信代理身份验证；请参阅可信代理身份验证。

有关 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 仍会渲染。
• 渠道元数据发出的远程头像 URL 会在 Control UI 的头像助手中被剥离，并替换为内置徽标/徽章，因此被攻陷或恶意的渠道无法强制操作员浏览器发起任意远程图片获取。

你无需更改任何内容即可获得此行为，它始终启用且不可配置。

头像路由身份验证

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

• GET /avatar/<agentId> 仅向已认证调用方返回头像图片。GET /avatar/<agentId>?meta=1 按同一规则返回头像元数据。
• 对任一路由的未认证请求都会被拒绝（与同级 assistant-media 路由一致）。这可以防止头像路由在原本受保护的主机上泄漏智能体身份。
• 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 中。

构建 UI

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> 在启动后未注册时会显示。

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

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

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

Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 来源。当你希望在本地使用 Vite 开发服务器、而 Gateway 网关在其他地方运行时，这很方便。

bash
pnpm ui:dev

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

可选的一次性身份验证（如果需要）：

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

- gatewayUrl 会在加载后存储到 localStorage，并从 URL 中移除。
- 如果你通过 gatewayUrl 传入完整的 ws:// 或 wss:// 端点，请对 gatewayUrl 值进行 URL 编码，以便浏览器正确解析查询字符串。
- 只要可能，token 应通过 URL 片段（#token=...）传入。片段不会发送到服务器，从而避免请求日志和 Referer 泄漏。旧版 ?token= 查询参数仍会为兼容性导入一次，但只作为兜底，并且会在引导后立即剥离。
- password 仅保存在内存中。
- 设置 gatewayUrl 后，UI 不会回退到配置或环境凭证。请显式提供 token（或 password）。缺少显式凭证会报错。
- 当 Gateway 网关位于 TLS 后方时（Tailscale Serve、HTTPS 代理等），请使用 wss://。
- gatewayUrl 只在顶层窗口中接受（不接受嵌入式窗口），以防止点击劫持。
- 非 local loopback 的 Control UI 部署必须显式设置 gateway.controlUi.allowedOrigins（完整来源）。这包括远程开发设置。
- Gateway 网关启动可能会根据有效运行时绑定和端口填充本地来源，例如 http://localhost:<port> 和 http://127.0.0.1:<port>，但远程浏览器来源仍需要显式条目。
- 除非是严格受控的本地测试，否则不要使用 gateway.controlUi.allowedOrigins: ["*"]。它表示允许任意浏览器来源，而不是“匹配我正在使用的任何主机”。
- gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true 会启用 Host 标头来源回退模式，但这是危险的安全模式。

示例：

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

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

相关

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

📄 仪表盘

原文：https://docs.openclaw.ai/zh-CN/web/dashboard

Gateway 网关仪表盘是默认在 / 提供服务的浏览器控制 UI
（可用 gateway.controlUi.basePath 覆盖）。

快速打开（本地 Gateway 网关）：

• http://127.0.0.1:18789/（或 http://localhost:18789/）
• 使用 gateway.tls.enabled: true 时，对 WebSocket 端点使用 https://127.0.0.1:18789/ 和
  wss://127.0.0.1:18789。

关键参考：

• 控制 UI，了解用法和 UI 能力。
• Tailscale，了解 Serve/Funnel 自动化。
• Web 界面，了解绑定模式和安全说明。

身份验证会在 WebSocket 握手期间通过配置的 Gateway 网关
auth 路径强制执行：

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

请参阅 Gateway 网关配置中的 gateway.auth。

安全注意事项：控制 UI 是一个管理界面（聊天、配置、exec 审批）。
不要将其公开暴露。UI 会把仪表盘 URL 令牌保存在当前浏览器标签页会话和所选 Gateway 网关 URL 的 sessionStorage 中，并在加载后从 URL 中移除它们。
优先使用 localhost、Tailscale Serve 或 SSH 隧道。

快速路径（推荐）

• 新手引导完成后，CLI 会自动打开仪表盘并打印一个干净的（不带令牌的）链接。
• 随时重新打开：openclaw dashboard（复制链接，尽可能打开浏览器，如果是无头环境则显示 SSH 提示）。
• 如果剪贴板和浏览器打开都失败，openclaw dashboard 仍会打印
  干净的 URL，并告诉你使用来自 OPENCLAW_GATEWAY_TOKEN 或
  gateway.auth.token 的令牌作为 URL 片段键 token；它不会在日志中打印令牌
  值。
• 如果 UI 提示进行共享密钥身份验证，请将配置的令牌或
  密码粘贴到控制 UI 设置中。

身份验证基础（本地与远程）

• Localhost：打开 http://127.0.0.1:18789/。
• Gateway 网关 TLS：当 gateway.tls.enabled: true 时，仪表盘/Status 链接使用
  https://，控制 UI WebSocket 链接使用 wss://。
• 共享密钥令牌来源：gateway.auth.token（或
  OPENCLAW_GATEWAY_TOKEN）；openclaw dashboard 可以通过 URL 片段传递它
  以进行一次性引导，控制 UI 会将它保存在当前浏览器标签页会话和所选 Gateway 网关 URL 的 sessionStorage 中，而不是 localStorage。
• 如果 gateway.auth.token 由 SecretRef 管理，openclaw dashboard
  会按设计打印/复制/打开一个不带令牌的 URL。这样可以避免在 shell 日志、剪贴板历史记录或浏览器启动
  参数中暴露外部管理的令牌。
• 如果 gateway.auth.token 配置为 SecretRef，但在你的
  当前 shell 中未解析，openclaw dashboard 仍会打印一个不带令牌的 URL，并附带
  可操作的身份验证设置指引。
• 共享密钥密码：使用配置的 gateway.auth.password（或
  OPENCLAW_GATEWAY_PASSWORD）。仪表盘不会在重新加载后持久保存密码。
• 携带身份的模式：当 gateway.auth.allowTailscale: true 时，Tailscale Serve 可以通过身份标头满足控制 UI/WebSocket
  身份验证；具备身份感知能力的非 local loopback 反向代理可以满足
  gateway.auth.mode: "trusted-proxy"。在这些模式下，仪表盘不需要
  为 WebSocket 粘贴共享密钥。
• 非 localhost：使用 Tailscale Serve、非 local loopback 共享密钥绑定、
  具备身份感知能力且使用 gateway.auth.mode: "trusted-proxy" 的非 local loopback 反向代理，或 SSH 隧道。HTTP API 仍使用
  共享密钥身份验证，除非你有意运行私有入口
  gateway.auth.mode: "none" 或受信代理 HTTP 身份验证。请参阅
  Web 界面。

如果你看到 “unauthorized” / 1008

• 确保 Gateway 网关可访问（本地：openclaw status；远程：SSH 隧道 ssh -N -L 18789:127.0.0.1:18789 user@host，然后打开 http://127.0.0.1:18789/）。
• 对于 AUTH_TOKEN_MISMATCH，当 Gateway 网关返回重试提示时，客户端可以使用缓存的设备令牌进行一次可信重试。该缓存令牌重试会复用该令牌缓存的已批准 scopes；显式 deviceToken / 显式 scopes 调用方会保留其请求的 scope 集。如果该重试后身份验证仍失败，请手动解决令牌漂移。
• 对于 AUTH_SCOPE_MISMATCH，设备令牌已被识别，但未携带仪表盘请求的 scopes；请重新配对或批准请求的 scope 合约，而不是轮换共享 Gateway 网关令牌。
• 在该重试路径之外，连接身份验证优先级为：先显式共享令牌/密码，然后显式 deviceToken，然后存储的设备令牌，最后引导令牌。
• 在异步 Tailscale Serve 控制 UI 路径上，同一
  {scope, ip} 的失败尝试会在失败身份验证限流器记录它们之前被串行化，因此
  第二个并发的错误重试可能已经显示 retry later。
• 有关令牌漂移修复步骤，请遵循令牌漂移恢复检查清单。
• 从 Gateway 网关主机检索或提供共享密钥：
• 令牌：openclaw config get gateway.auth.token
• 密码：解析配置的 gateway.auth.password 或
  OPENCLAW_GATEWAY_PASSWORD
• SecretRef 管理的令牌：解析外部 secret 提供商，或在此 shell 中导出
  OPENCLAW_GATEWAY_TOKEN，然后重新运行 openclaw dashboard
• 未配置共享密钥：openclaw doctor --generate-gateway-token
• 在仪表盘设置中，将令牌或密码粘贴到身份验证字段，
  然后连接。
• UI 语言选择器位于 概览 -> Gateway 网关访问 -> 语言。
  它属于访问卡片，而不是外观部分。

相关

• 控制 UI
• WebChat

📄 网页聊天

原文：https://docs.openclaw.ai/zh-CN/web/webchat

Status：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信。

它是什么

• 面向 Gateway 网关的原生聊天 UI（没有嵌入式浏览器，也没有本地静态服务器）。
• 使用与其他渠道相同的会话和路由规则。
• 确定性路由：回复始终返回 WebChat。

快速开始

1. 启动 Gateway 网关。
2. 打开 WebChat UI（macOS/iOS 应用）或 Control UI 聊天标签页。
3. 确保配置了有效的 Gateway 网关认证路径（默认使用共享密钥，
   即使在回环上也是如此）。

工作方式（行为）

• UI 连接到 Gateway 网关 WebSocket，并使用 chat.history、chat.send 和 chat.inject。
• 为了稳定性，chat.history 是有边界的：Gateway 网关可能会截断较长的文本字段、省略较重的元数据，并将过大的条目替换为 [chat.history omitted: message too large]。
• 对于现代追加式会话文件，chat.history 会跟随活动转录分支，因此废弃的重写分支和被取代的提示词副本不会在 WebChat 中渲染。
• 压缩条目会渲染为显式的已压缩历史分隔线。分隔线会说明更早的轮次已保留在检查点中，并链接到会话检查点控件；在权限允许时，操作者可以在那里分支或恢复压缩前视图。
• Control UI 会记住 chat.history 返回的后端 Gateway 网关 sessionId，并在后续 chat.send 调用中包含它，因此重新连接和页面刷新会继续同一个已存储对话，除非用户启动或重置会话。
• Control UI 会在生成新的 chat.send 运行 ID 之前，合并同一会话、消息和附件的重复进行中提交；Gateway 网关仍会对复用相同幂等键的重复请求去重。
• 工作区启动文件和待处理的 BOOTSTRAP.md 指令会通过智能体系统提示词的项目上下文提供，而不是复制到 WebChat 用户消息中。Bootstrap 截断只会添加一条简洁的系统提示词恢复通知；详细计数和配置旋钮保留在诊断界面上。
• chat.history 还会进行显示规范化：仅运行时使用的 OpenClaw 上下文、
  入站信封包装器、内联投递指令标签
  如 [[reply_to_*]] 和 [[audio_as_voice]]、纯文本工具调用 XML
  载荷（包括 <tool_call>...</tool_call>、
  <function_call>...</function_call>、<tool_calls>...</tool_calls>、
  <function_calls>...</function_calls> 以及截断的工具调用块），以及
  泄漏的 ASCII/全角模型控制标记都会从可见文本中剥离，
  并且整段可见文本仅为精确静默
  标记 NO_REPLY / no_reply 的助手条目会被省略。
• 带推理标记的回复载荷（isReasoning: true）会从 WebChat 助手内容、转录回放文本和音频内容块中排除，因此仅思考载荷不会显示为可见助手消息或可播放音频。
• chat.inject 会将一条助手备注直接追加到转录中，并广播给 UI（不会运行智能体）。
• 已中止的运行可以让部分助手输出继续显示在 UI 中。
• 当存在已缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中，并用中止元数据标记这些条目。
• 历史始终从 Gateway 网关获取（没有本地文件监听）。
• 如果 Gateway 网关无法访问，WebChat 为只读。

转录和投递模型

WebChat 有两条独立的数据路径：

• 会话 JSONL 文件是持久的模型/运行时转录。对于正常的智能体运行，Pi 会通过其会话管理器持久化模型可见的 user、assistant 和 toolResult 消息。WebChat 不会将任意投递、状态或辅助文本写入该转录。
• Gateway 网关 ReplyPayload 事件是实时投递投影。它们可以针对 WebChat/渠道显示、分块流式传输、指令标签、媒体嵌入、TTS/音频标志和 UI 兜底行为进行规范化。它们本身不是规范会话日志。
• 只有当 Gateway 网关在正常 Pi 助手轮次之外拥有一条已显示消息时，WebChat 才会注入助手转录条目：chat.inject、非智能体命令回复、已中止的部分输出，以及 WebChat 管理的媒体转录补充。
• chat.history 会读取已存储的会话转录并应用 WebChat 显示投影。如果运行期间出现实时助手文本，但在历史重新加载后消失，先检查原始 JSONL 是否包含助手文本，再检查 chat.history 投影是否将其剥离，然后检查 Control UI 乐观尾部合并是否用持久化快照替换了本地投递状态。

正常智能体运行的最终答案应该是持久的，因为 Pi 会写入助手 message_end。任何将已投递最终载荷镜像到转录中的兜底，都必须先避免重复写入 Pi 已经写入的助手轮次。

Control UI 智能体工具面板

• Control UI /agents 工具面板有两个独立视图：
• 当前可用使用 tools.effective(sessionKey=...)，并显示当前
  会话在运行时实际可以使用的内容，包括核心、插件和渠道拥有的工具。
• 工具配置使用 tools.catalog，并专注于配置文件、覆盖项和
  目录语义。
• 运行时可用性以会话为作用域。在同一个智能体上切换会话可能会改变
  当前可用列表。
• 配置编辑器并不表示运行时可用；有效访问仍然遵循策略
  优先级（allow/deny、按智能体以及提供商/渠道的覆盖项）。

远程使用

• 远程模式通过 SSH/Tailscale 隧道传输 Gateway 网关 WebSocket。
• 你不需要运行单独的 WebChat 服务器。

配置参考（WebChat）

完整配置：配置

WebChat 选项：

• gateway.webchat.chatHistoryMaxChars：chat.history 响应中文本字段的最大字符数。当转录条目超过此限制时，Gateway 网关会截断较长的文本字段，并且可能用占位符替换过大的消息。客户端还可以发送按请求设置的 maxChars，以覆盖单次 chat.history 调用的默认值。

相关全局选项：

• gateway.port、gateway.bind：WebSocket 主机/端口。
• gateway.auth.mode、gateway.auth.token、gateway.auth.password：
  共享密钥 WebSocket 认证。
• gateway.auth.allowTailscale：启用后，浏览器 Control UI 聊天标签页可以使用 Tailscale
  Serve 身份标头。
• gateway.auth.mode: "trusted-proxy"：面向位于支持身份感知的非回环代理来源之后的浏览器客户端的反向代理认证（请参阅受信任代理认证）。
• gateway.remote.url、gateway.remote.token、gateway.remote.password：远程 Gateway 网关目标。
• session.*：会话存储和主键默认值。

相关内容

• Control UI
• Dashboard

📄 终端用户界面

原文：https://docs.openclaw.ai/zh-CN/web/tui

快速开始

Gateway 网关模式

1. 启动 Gateway 网关。

openclaw gateway

2. 打开 TUI。

openclaw tui

3. 输入消息并按 Enter。

远程 Gateway 网关：

openclaw tui --url ws://<host>:<port> --token <gateway-token>

如果你的 Gateway 网关使用密码认证，请使用 --password。

本地模式

不通过 Gateway 网关运行 TUI：

openclaw chat
# or
openclaw tui --local

注意：

• openclaw chat 和 openclaw terminal 是 openclaw tui --local 的别名。
• --local 不能与 --url、--token 或 --password 组合使用。
• 本地模式会直接使用嵌入式智能体运行时。大多数本地工具可以工作，但仅 Gateway 网关可用的功能不可用。
• openclaw 和 openclaw crestodian 也使用这个 TUI shell，其中 Crestodian 作为本地设置和修复聊天后端。

你会看到什么

• 标头：连接 URL、当前智能体、当前会话。
• 聊天日志：用户消息、助手回复、系统通知、工具卡片。
• Status 行：连接/运行状态（正在连接、运行中、流式传输中、空闲、错误）。
• 页脚：连接状态 + 智能体 + 会话 + 模型 + 思考/快速/详细/跟踪/推理 + token 计数 + 交付。
• 输入区：带自动补全的文本编辑器。

心智模型：智能体 + 会话

• 智能体是唯一 slug（例如 main、research）。Gateway 网关会公开该列表。
• 会话属于当前智能体。
• 会话键存储为 agent:<agentId>:<sessionKey>。
• 如果你输入 /session main，TUI 会将其展开为 agent:<currentAgent>:main。
• 如果你输入 /session agent:other:main，你会显式切换到该智能体会话。
• 会话范围：
• per-sender（默认）：每个智能体有多个会话。
• global：TUI 始终使用 global 会话（选择器可能为空）。
• 当前智能体 + 会话始终显示在页脚中。
• 在没有 --session 的情况下启动时，Gateway 网关模式 TUI 会恢复同一 Gateway 网关、智能体和会话范围的上次所选会话，前提是该会话仍然存在。传入 --session、/session、/new 或 /reset 仍然是显式操作。

发送 + 交付

• 消息会发送到 Gateway 网关；默认关闭向提供商交付。
• 开启交付：
• /deliver on
• 或使用设置面板
• 或以 openclaw tui --deliver 启动

选择器 + 叠加层

• 模型选择器：列出可用模型并设置会话覆盖项。
• 智能体选择器：选择不同的智能体。
• 会话选择器：显示当前智能体在过去 7 天内更新的最多 50 个会话。使用 /session <key> 跳转到较旧的已知会话。
• 设置：切换交付、工具输出展开和思考可见性。

键盘快捷键

• Enter：发送消息
• Esc：中止正在运行的任务
• Ctrl+C：清空输入（按两次退出）
• Ctrl+D：退出
• Ctrl+L：模型选择器
• Ctrl+G：智能体选择器
• Ctrl+P：会话选择器
• Ctrl+O：切换工具输出展开
• Ctrl+T：切换思考可见性（重新加载历史）

斜杠命令

核心：

• /help
• /status
• /agent <id>（或 /agents）
• /session <key>（或 /sessions）
• /model <provider/model>（或 /models）

会话控制：

• /think <off|minimal|low|medium|high>
• /fast <status|on|off>
• /verbose <on|full|off>
• /trace <on|off>
• /reasoning <on|off|stream>
• /usage <off|tokens|full>
• /elevated <on|off|ask|full>（别名：/elev）
• /activation <mention|always>
• /deliver <on|off>

会话生命周期：

• /new 或 /reset（重置会话）
• /abort（中止正在运行的任务）
• /settings
• /exit

仅本地模式：

• /auth [provider] 会在 TUI 内打开提供商认证/登录流程。

其他 Gateway 网关斜杠命令（例如 /context）会转发到 Gateway 网关，并显示为系统输出。请参阅斜杠命令。

本地 shell 命令

• 在一行前加上 !，即可在 TUI 主机上运行本地 shell 命令。
• TUI 会在每个会话中提示一次，以允许本地执行；拒绝后，! 在该会话中保持禁用。
• 命令会在 TUI 工作目录中的全新非交互式 shell 内运行（没有持久的 cd/环境变量）。
• 本地 shell 命令会在其环境中收到 OPENCLAW_SHELL=tui-local。
• 单独的 ! 会作为普通消息发送；前导空格不会触发本地执行。

从本地 TUI 修复配置

当当前配置已经通过验证，并且你希望嵌入式智能体在同一台机器上检查它、与文档对比并帮助修复漂移，而不依赖正在运行的 Gateway 网关时，请使用本地模式。

如果 openclaw config validate 已经失败，请先从 openclaw configure 或 openclaw doctor --fix 开始。openclaw chat 不会绕过无效配置保护。

典型循环：

1. 启动本地模式：

openclaw chat

2. 询问智能体你希望检查的内容，例如：

Compare my gateway auth config with the docs and suggest the smallest fix.

3. 使用本地 shell 命令获取精确证据并验证：

!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor

4. 使用 openclaw config set 或 openclaw configure 应用小范围更改，然后重新运行 !openclaw config validate。
5. 如果 Doctor 建议自动迁移或修复，请先审查它，然后运行 !openclaw doctor --fix。

提示：

• 优先使用 openclaw config set 或 openclaw configure，而不是手动编辑 openclaw.json。
• openclaw docs "<query>" 会从同一台机器搜索实时文档索引。
• 当你需要结构化 schema 和 SecretRef/可解析性错误时，openclaw config validate --json 很有用。

工具输出

• 工具调用会显示为带有参数 + 结果的卡片。
• Ctrl+O 在折叠/展开视图之间切换。
• 工具运行时，部分更新会流式传输到同一张卡片中。

终端颜色

• TUI 会让助手正文文本保持为你的终端默认前景色，以便深色和浅色终端都保持可读。
• 如果你的终端使用浅色背景且自动检测错误，请在启动 openclaw tui 前设置 OPENCLAW_THEME=light。
• 若要改为强制使用原始深色调色板，请设置 OPENCLAW_THEME=dark。

历史 + 流式传输

• 连接时，TUI 会加载最新历史（默认 200 条消息）。
• 流式传输响应会就地更新，直到最终完成。
• TUI 还会监听智能体工具事件，以提供更丰富的工具卡片。

连接详情

• TUI 会以 mode: "tui" 注册到 Gateway 网关。
• 重新连接会显示一条系统消息；事件缺口会在日志中显示。

选项

• --local：针对本地嵌入式智能体运行时运行
• --url <url>：Gateway 网关 WebSocket URL（默认为配置或 ws://127.0.0.1:<port>）
• --token <token>：Gateway 网关 token（如需要）
• --password <password>：Gateway 网关密码（如需要）
• --session <key>：会话键（默认：main，当范围为 global 时则为 global）
• --deliver：将助手回复交付给提供商（默认关闭）
• --thinking <level>：覆盖发送时的思考级别
• --message <text>：连接后发送初始消息
• --timeout-ms <ms>：智能体超时时间，单位为 ms（默认为 agents.defaults.timeoutSeconds）
• --history-limit <n>：要加载的历史条目数（默认 200）

设置 --url 时，TUI 不会回退到配置或环境凭据。请显式传入 --token 或 --password。缺少显式凭据会报错。在本地模式下，不要传入 --url、--token 或 --password。

故障排除

发送消息后没有输出：

• 在 TUI 中运行 /status，确认 Gateway 网关已连接且处于空闲/忙碌状态。
• 检查 Gateway 网关日志：openclaw logs --follow。
• 确认智能体可以运行：openclaw status 和 openclaw models status。
• 如果你期望消息出现在聊天渠道中，请启用交付（/deliver on 或 --deliver）。

连接故障排除

• disconnected：确保 Gateway 网关正在运行，并且你的 --url/--token/--password 正确。
• 选择器中没有智能体：检查 openclaw agents list 和你的路由配置。
• 会话选择器为空：你可能处于 global 范围，或者还没有任何会话。

相关

• 控制界面 — 基于 Web 的控制界面
• 配置 — 检查、验证和编辑 openclaw.json
• Doctor — 引导式修复和迁移检查
• CLI 参考 — 完整 CLI 命令参考