控制界面

• 通过 Gateway 网关 WS 与模型聊天（chat.history、chat.send、chat.abort、chat.inject）。
• 聊天历史刷新会请求一个有界的近期窗口，并为每条消息设置文本上限，因此大型会话不会迫使浏览器在聊天可用前渲染完整转录负载。
• 通过浏览器实时会话使用 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 模型。
• 在聊天中流式传输工具调用和实时工具输出卡片（智能体事件）。

• 渠道：内置渠道以及内置/外部插件渠道的 Status、二维码登录和按渠道配置（channels.status、web.login.*、config.patch）。
• 渠道探测刷新会在较慢的提供商检查完成前保持上一份快照可见，并在探测或审计超过其 UI 预算时标记局部快照。
• 实例：在线列表 + 刷新（system-presence）。
• 会话：列表 + 按会话设置的模型/思考/快速/详细/跟踪/推理覆盖（sessions.list、sessions.patch）。
• 梦境：Dreaming 状态、启用/禁用开关和 Dream Diary 阅读器（doctor.memory.status、doctor.memory.dreamDiary、config.patch）。

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

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

• 调试：Status/健康/Models 快照 + 事件日志 + 手动 RPC 调用（status、health、models.list）。
• 事件日志包括控制 UI 刷新/RPC 计时、较慢的聊天/配置渲染计时，以及在浏览器暴露这些 PerformanceObserver 条目类型时记录的长动画帧或长任务浏览器响应性条目。
• 日志：Gateway 网关文件日志实时尾随，支持过滤/导出（logs.tail）。
• 更新：运行 package/git 更新 + 重启（update.run）并生成重启报告，然后在重新连接后轮询 update.status 以验证正在运行的 Gateway 网关版本。

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

• chat.send 是非阻塞的：它会立即以 { runId, status: "started" } 确认，响应通过 chat 事件流式传输。
• 聊天上传接受图像以及非视频文件。图像保留原生图像路径；其他文件会作为托管媒体存储，并在历史记录中显示为附件链接。
• 使用相同的 idempotencyKey 重新发送时，运行期间返回 { status: "in_flight" }，完成后返回 { status: "ok" }。
• 为了 UI 安全，chat.history 响应有大小限制。当转录条目过大时，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 尚无已保存的仪表板会话，则回退到该 agent 的主会话。
• 在桌面宽度下，聊天控件保持在一个紧凑行中，并在向下滚动转录时折叠；向上滚动、返回顶部或到达底部会恢复控件。
• 连续重复的纯文本消息会渲染为一个带计数徽章的气泡。携带图像、附件、工具输出或画布预览的消息不会折叠。
• 聊天标题中的模型和 thinking 选择器会通过 sessions.patch 立即修补活跃会话；它们是持久会话覆盖项，而不是仅限单轮的发送选项。
• 在 Control UI 中输入 /new 会创建并切换到与 New Chat 相同的全新仪表板会话。输入 /reset 会保留 Gateway 网关对当前会话的显式原地重置。
• 聊天模型选择器请求 Gateway 网关配置的模型视图。如果存在 agents.defaults.models，该允许列表会驱动选择器。否则，选择器会显示显式的 models.providers.*.models 条目，以及具有可用身份验证的提供商。完整目录仍可通过调试 models.list RPC 使用 view: "all" 获取。
• 当新的 Gateway 网关会话用量报告显示上下文压力较高时，聊天编辑器区域会显示上下文提示，并在建议压缩级别下显示一个紧凑按钮，用于运行常规会话压缩路径。过期的 token 快照会被隐藏，直到 Gateway 网关再次报告新的用量。

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

在 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 浏览器 WebRTC SDP 交换、Google Live 受限 token 浏览器 WebSocket 设置，以及带有假麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。

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

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

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

allowInsecureAuth 只是一个本地兼容性开关：

• 它允许 localhost 控制 UI 会话在非安全 HTTP 上下文中无需设备身份即可继续。
• 它不会绕过配对检查。
• 它不会放宽远程（非 localhost）设备身份要求。

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

• 成功的受信任代理身份验证可以接纳没有设备身份的操作员控制 UI 会话。
• 这不会扩展到节点角色控制 UI 会话。
• 同主机 loopback 反向代理仍不满足受信任代理身份验证；请参阅受信任代理身份验证。

• 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 只会在顶层窗口中接受（不能嵌入），以防止点击劫持。
• 非环回控制 UI 部署必须显式设置 gateway.controlUi.allowedOrigins（完整来源）。这包括远程开发设置。
• Gateway 网关启动时可能会根据有效运行时绑定和端口预置本地来源，例如 http://localhost:<port> 和 http://127.0.0.1:<port>，但远程浏览器来源仍需要显式条目。
• 除非用于严格受控的本地测试，否则不要使用 gateway.controlUi.allowedOrigins: ["*"]。它表示允许任何浏览器来源，而不是“匹配我正在使用的任何主机”。
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true 会启用 Host 标头来源回退模式，但这是危险的安全模式。