屏幕
screen 工具可让代理布置基于浏览器的 Control UI。它是一个类型化的布局和导航界面，而不是截图捕获或浏览器自动化。
仅当发起客户端声明 ui-commands 能力时，才会暴露该工具。工具运行时，所选人员发起请求的 Control UI 仍必须保持连接；否则 Gateway 返回 UNAVAILABLE。
客户端会在 Gateway 连接握手期间发送的 caps 数组中声明 ui-commands（参见 Gateway 协议）。内置 Control UI 已经声明了它，因此无需在那里开启任何设置。未声明它的客户端永远不会被提供 screen，因此工具缺失，而不是在调用时失败。
操作¶
| 操作 | 效果 | 可选输入 |
|---|---|---|
split_right |
将目标会话窗格向右拆分 | sessionKey（默认当前会话） |
split_down |
将目标会话窗格向下拆分 | sessionKey（默认当前会话） |
close_pane |
关闭目标会话窗格 | sessionKey（默认当前会话） |
focus |
聚焦目标会话窗格 | sessionKey（默认当前会话） |
navigate |
打开目标会话 | sessionKey（默认当前会话） |
sidebar_show / sidebar_hide |
显示或隐藏主侧边栏 | - |
terminal_show / terminal_hide |
显示或隐藏操作员终端面板 | dock（显示时为 bottom 或 right） |
browser_show / browser_hide |
显示或隐藏浏览器面板 | dock（显示时为 bottom 或 right） |
desktop_show / desktop_hide |
显示或隐藏远程桌面 | environmentId、sessionKey、dock（默认 right） |
portal_show / portal_hide |
显示或隐藏 Web 应用门户 | portalId、sessionKey、dock（默认 right） |
每个操作都接受可选的 user，即 Control UI 消息会话上下文中该人员已验证的 requester_profile.id。当多人已引导该轮次时，user 为必填项；代理会选择提出请求的人员，若不明确则询问他们。
对于运行在已附加环境上的原生应用，请使用其 environmentId 调用 desktop_show。对于 Web 应用，先为服务器端口打开一个门户，然后使用返回的 portalId 调用 portal_show。所选视图会在该对话的侧边栏中打开。隐藏视图不会停止其应用、关闭门户或释放环境。
桌面面板和计算机工具指向同一环境。screen 仅负责呈现它；计算机工具执行点击、输入和截图。
环境可能在配置完成前出现。桌面会显示启动进度，并在该确切机器可用时连接。在其应用启动期间，portal_show 可以接受 environmentId；就绪后将其替换为该应用的 portalId。待处理的 Portal 绝不会从门户列表中打开另一个应用。
成功命令会在 Gateway 向发起请求的浏览器发送类型化的 ui.command 事件后返回 { "ok": true }。
路由与安全¶
命令只会更改所选人员发起请求的 Control UI 连接。其他人的仪表板以及你的其他标签页会保持当前视图。sessionKey 选择要打开哪个会话；它不选择接收方。
Gateway 在接受消息时会捕获浏览器目标，并将其与排队轮次和 worker 执行一起保留。如果该浏览器断开连接，或该轮次没有 Control UI 目标，命令将以 UNAVAILABLE 失败。请从已打开的 Control UI 重新请求；命令绝不会回退到广播。
具有匹配权限的人员可以引导同一轮次。每个参与者都保留自己捕获的浏览器目标；user 只能选择轮次所有者或已接受的参与者。排队或被拒绝的引导不会添加参与者。如果所选人员的访问权限已变更，他们必须重新请求。
之前使用 ui.command 进行广播的独立 RPC 和 MCP 调用方，必须从发起请求的 Control UI 连接或在该连接中启动的代理轮次中调用它。如果没有该浏览器目标，它们现在会收到 UNAVAILABLE，即使其他仪表板已连接。这有意取代了旧版广播契约。
Gateway RPC 需要 operator.write。该工具只能更改呈现状态：它不能读取像素、截取屏幕截图、点击任意页面内容，或绕过所选会话和操作员面板的权限。
相关¶
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw