安全模型

Control UI如何限制浏览器并验证自己的路由。

内容安全策略

Control UI 允许 same-origin 资产、data: URL、本地生成的 blob: URL 和远程 HTTPS 图像。远程 HTTP 图像被阻止。协议相关的图像 URL 遵循文档的方案。

实际使用中：

• 在相对路径（例如 /avatars/<id>）下提供的头像和图像仍然呈现，包括 UI 获取并转换为本地 blob: URL 的经过身份验证的头像路由。
• Inline data:image/... URL 仍呈现。
• 由 Control UI 创建的本地 blob: URL 仍会呈现。文本附件预览可以在发送附件之前读取这些本地字节。
• HTTPS 文字记录图像在聊天图像库和活动预览中呈现。浏览器直接联系图像主机，公开其网络地址；缩略图、扩展图像查看器和相邻图像预加载不发送页面引用。
• Markdown 附件和技能研讨会预览将远程图像保留为点击打开链接。插件 README 和代理文件预览会自动加载 HTTPS 图像并直接从浏览器联系其主机。
• 已验证 GitHub 帐户头像从 avatars.githubusercontent.com 渲染；头像助手继续拒绝任意远程头像 URL。
• GitHub 链接预览头像由网关从 GitHub 的固定头像主机获取，并作为有界 data: URL 返回；操作员浏览器永远不会联系远程化身主机。
• 默认情况下，链接图标处于打开状态。经过认证的Control UI通过网关请求它们；浏览器从不直接联系链接目标。 link-favicon 路由请求每个公共主机名HTTPS /favicon.ico，以严格的DNS-固定的SSRF检查原件URL每个重定向加上有限的时间、字节、并发性和图像验证。私人的、内部的和IP-字面目标被拒绝。这会公开这些站点的链接主机名和网关的网络地址。浏览器选项卡和普通外部链接悬停预览还可以通过经过身份验证的网关获取公共页面的标题、有界描述、声明的图标以及开放图谱或 Twitter 社交图像。这些匿名请求从不使用浏览器 cookie 或站点凭据；HTML、重定向和图像接收相同的公共网络检查和有限资源限制。浏览器接收经过验证的图像数据，而不是远程图像 URL。这也公开了目标页面URL（包括路径和查询）到该站点以及对其声明的图像主机的图像请求。普通链接预览从有意的悬停或键盘焦点开始，而不是转录预取；触摸点击保留正常导航。向导登录操作保留在外部，不会为预览而获取。插件拥有的预览保留自己的路由和凭据策略。放gateway.controlUi.automaticallyFetchFavicons: false禁用链接图标请求、浏览器选项卡页面预览和普通外部链接预览。实时浏览器屏幕截图是单独的并且仍然可用。
• 动画 PNG （APNG） 图标被接受为 PNG 图像。工作区图标和托管频道头像保留其动画；远程插件、目录和链接图标使用调整大小的 PNG 预览。
• 由通道元数据发出的远程头像 URL 在 Control UI 的头像助手处被剥离，并替换为内置的 logo/badge，因此受损或恶意通道无法强制从操作员浏览器获取任意远程图像。

页面元数据读取停止在 HTML 头末尾或 64 KiB 之后，以先到者为准；超出该限制的元数据将被忽略。网关在不构建页面 DOM 的情况下流式传输头部。匿名预览根据请求的主体和运行时配置修订使用有界缓存一小时（如果可用）或五分钟（如果不可用）； URL 片段共享相同的条目。重复的链接共享待处理的请求，声明相同社交图像和网站图标的页面会下载一次。 15 秒的预览截止时间包括队列等待、获取和图像工作。禁用自动图标或撤销请求的权限也会抑制缓存的预览。

浏览器端 CSP 限制本身始终开启且不可配置。

连接权限

Control UI 使用网关握手返回的授予范围。会话读者可以打开共享聊天，而无需轮询操作员专用的仪表板、计划任务、语音目录或提供商身份验证状态。受限表面被隐藏或显示访问消息。仪表板 FORBIDDEN 响应停止自动重试；重新连接会替换连接的授予范围。网关继续授权每个请求和订阅。

公共成绩单边界

公共线程使用与经过身份验证的 Control UI 相同的 /chat/... URL。匿名读者会收到一份单独的只读文档，而不会与操作员连接。 登录 经历受保护的同源切换并返回到具有该人员现有权限的线程。匿名线程路径上的身份标头不授权私有访问。私有线程和丢失线程具有相同的匿名不可用响应。

在 token/password 部署中，读取器可以识别浏览器持有的会话令牌或范围为当前网关地址和基本路径的配对设备凭证。受保护的探针返回 401 后，该存在只是打开应用程序 shell 的导航提示；读取器从不发送凭证或授权会话数据。应用程序的现有 WebSocket 和引导检查仍然适用。 204 探针会继续进入应用程序，而 403 会保留公共读者，即使存在本地凭据也是如此。可信代理和外部登录切换保留其现有的身份验证和权限检查。

Loopback HTTP 保留其公共读者支持。在无法发布的非安全入口上，token/password 聊天链接直接为应用程序 shell 提供服务，而无需查找或披露记录。为 shell 提供服务不授予任何网关或会话访问权限。

公共渲染器包括用户和助理文本，包括进度更新、工具调用摘要和共享图像。工具结果文本、推理、可执行小部件、隐藏消息和内部元数据保持私密。图像使用与当前出版物和文字记录条目绑定的公共媒体路径；其他附件显示为文件名片，没有下载链接。包含的文本保留凭证；发布前进行审查。限制性内容安全策略仅允许固定阅读器脚本；脚本 HTML 无法执行。响应保留 Cache-Control: no-store 和 Referrer-Policy: no-referrer。服务器端表示重用永远不会替代当前的发布检查，包括在 304 响应之前。

公共成绩单文档、预览卡、共享图像和共享命名空间发送 X-Robots-Tag: noindex, nofollow； HTML 阅读器和预览文档还包括机器人元标记。这些指令要求合规搜索引擎不要索引内容或跟踪其链接。它们不会阻止匿名下载、撤回现有副本或取代访问控制。社交预览爬虫仍然可以获取公共文档和图像。

任何知道公共线程 URL 的人都可以阅读其现有和未来发布的内容，直到创建者或网关管理员禁用访问权限。重新启用访问会恢复正常线程 URL，但不会恢复之前撤销的令牌链接。

登录代理必须仅公开公共线程文档和共享命名空间。确保会话条目登录切换、WebSocket、引导程序、API、媒体、仪表板和其他应用程序路由受到保护。详细的部署和撤销合同位于 公共会话记录 中。

头像路由认证

当配置了网关认证时，Control UI 的头像端点需要与 API 其余部分使用相同的网关令牌：

• GET /avatar/<agentId> 仅向已认证的调用方返回头像图像。GET /avatar/<agentId>?meta=1 在相同规则下返回头像元数据。
• 对这两个路由的未认证请求都会被拒绝（与同级的 assistant-media 路由一致），因此在其他受保护的主机上，头像路由不会泄露 agent 身份。
• Control UI 在获取头像时将网关令牌作为承载标头转发，并使用经过身份验证的 blob URL，以便图像仍然在仪表板中呈现。
• 浏览器头像 URL 包含不透明的 v 修订版。静态 PNG、JPEG 和 WebP 头像使用最大边长为 128 像素的缓存预览。动画图像、SVG 和其他可接受的数据 URL 格式保留其原始字节和编码。侧边栏和聊天窗格共享获取的图像，并且私有浏览器缓存可以避免在重新加载时下载未更改的字节。
• 源更改后刷新的元数据使用新的 URL。在共享的 60 秒新鲜度窗口之后，下一次身份刷新将替换本地头像文件。条件请求在返回 304 Not Modified 之前仍然需要身份验证。修订版本是缓存密钥，而不是访问令牌；未版本控制的图像请求保留原始图像。

如果你禁用网关认证（不建议在共享主机上这样做），头像路由也会变为未认证，与网关其余部分保持一致。

并发的个人资料照片请求可以共享 Gravatar 查找。每个 HTTP 请求都保留自己的超时和断开连接生命周期，因此过期或断开连接的请求不会中断另一个客户端加载同一张照片。

保存的个人资料照片使用与网关的个人资料目录绑定的有限内存缓存。提交的配置文件编辑和合并使缓存的表示无效；身份验证仍然在缓存响应和 304 Not Modified 之前运行。冷照片读取具有单独的并发预算，以保留共享状态读取容量。过载期间，端点将返回 503 Service Unavailable 和 Retry-After: 1，而不是永久查找失败。

助手媒体路由认证

本地图像预览遵循聊天的文件系统权限。项目聊天使用其会话工作区，包括托管工作树。完全访问或禁用仅工作区的文件系统保护还允许在该工作区之外预览图像。显式会话权限模式优先于代理的文件系统设置。

本地项目聊天中的助理 MEDIA: 附件解析会话工作区内的相对路径，包括托管工作树。该工作区中的绝对路径将在相同的文件访问检查下进行交付。选择项目不会授予对同级工作树的访问权限。

受信任的音频附件在播放期间使用相同的会话工作区边界。混合回复会为每个被拒绝的附件保留一个单独的失败卡以及成功传送的媒体。

附件暂存和可信音频保留请求发件人的读取限制。当源会话的权限模式、工作区或执行位置发生更改或轮次被取消时，挂起的读取和复制就会停止。被拒绝的暂存文件在交付前会被清理。

即使具有完全访问权限，分派给云工作人员的会话也无法读取网关本地文件路径。 Dispatch 还会撤销待处理的本地预览和下载。网关拥有的入站上传仍然可用。

完全访问权限还可以保留代理配置的工作区中现有附件的播放和下载。它不允许任意外部非图像文件。

启用工作区保护后，外部图像将显示 允许的文件夹之外。将鼠标悬停在其文件名上以检查源路径。管理员可以选择 允许 image 预览该确切文件，而无需更改会话的权限或允许其父文件夹。该津贴使用短暂的媒体票；替换文件或重新启动网关需要新的配额。

当配置了网关认证时，助手本地媒体预览使用一个两步路由：

• GET /__openclaw__/assistant-media?meta=1&source=<path>&sessionKey=<key>&agentId=<id> 需要正常的 Control UI 操作员身份验证并访问所选会话；在检查可用性时，浏览器将网关令牌作为承载标头发送。
• 保存的消息附件也带有messageId。仅当附件的当前可见消息属于他们可以读取的对话（包括保留的排队或停止的输入）时，具有 operator.sessions.read 的读者才能打开附件。网关根据该消息保存的附件引用或支持的辅助媒体指令验证来源；单独的会话密钥或文件名永远不会授予文件访问权限。这些读取保留相同的文件系统限制。独立文件读取仍然需要 operator.read。
• 成功的元数据响应包括适用于文件、会话和消息的短暂 mediaTicket。显式外部映像许可使用经过身份验证的管理员 POST 到与 meta=1&allow=1 相同的路由。
• 浏览器呈现的图像、音频、视频和文档 URL 使用 mediaTicket=<ticket> 而不是活动网关令牌或密码。票证很快就会过期，并且无法授权其他来源。

门票仍受发行读者当前访问权限的约束。失去会话可见性或角色权限会阻止对现有票证的新读取，甚至在票证过期之前也是如此。

这使媒体呈现与浏览器本机媒体元素兼容，而无需将可重用网关凭据放入可见媒体 URL 中。

使用本机图像元素呈现的上传和本地聊天图像预览在临时连接或元数据更新失败期间保持已加载的图像可见。该容错能力仅适用于已安装的映像；它不会延长其媒体票或授权新的阅读。滚动可以重复使用来自有界内存预览缓存的已成功解码的图像，同时其现有元数据和票据保持有效，而无需下载其他图像或加载占位符。明确丢失或拒绝访问的响应，或者对源、凭据或访问范围的更改，都会清除保留的图像。当 UI 收到共享失效、角色配置更改或角色重新分配的连接关闭时，缓存的预览必须在重新安装之前通过新的准入。

如果在可用性检查成功后上传或本地图像字节无法加载或解码，则损坏的预览将变为带有 Retry 的 Unavailable 卡。本机映像错误不会显示 HTTP 状态，因此 UI 不会自动重复字节请求。 Retry 在再次加载映像之前检查当前可用性和访问权限；它不授予外部文件夹津贴或延长现有机票。

当新会话的工作区或工作树详细信息到达时，上传的图像也保持可见。媒体访问会在后台重新检查，而不会用加载卡替换加载的预览。

/api/chat/media/outgoing/... 下生成的图像使用与 artifacts.download 相同的功能原理。经过身份验证的 WebSocket 请求授权转录工件并返回短暂的 URL。 HTTP 媒体路由在提供字节之前重新检查工件是否仍然属于转录本。在兼容窗口期间，先前的共享所有者承载路径仍可用于较旧的 Control UI 客户端。

审批链接

操作员审批通知可以深层链接到 独立审批文档 。 URL 在批准的整个生命周期内保持稳定，并且可以在您自己的设备之间安全转发：它识别批准，从不授权。

• 审批命名空间由网关在 all HTTP 方法的插件 HTTP 路由之前保留，因此插件路由永远不会隐藏或拦截审批文档。
• 打开审批文档需要与Control UI的其余部分相同的网关身份验证（token/password、Tailscale服务身份或可信代理身份）；凭证绝不是批准 URL 的一部分。
• 当 Control UI 服务被禁用时，对命名空间的请求将返回 404，而不是落入插件处理程序。
• 在批准文档上登录对于该页面来说是短暂的：它不会覆盖同一浏览器中完整 Control UI 保存的网关选择或设置。