门户
Portals 将运行在 Gateway 主机或节点支持的云 worker 上的开发服务器暴露给操作员的浏览器。它们代理 HTTP 和 WebSockets 以支持实时重载,并显示在 Control UI → Portals 中。
快速开始¶
请智能体打开一个 portal:
- “在 portal 中给我展示。”
- “在 portal 中启动应用。”
智能体会为应用的端口打开一个 portal,然后通过后台 exec 调用启动开发服务器。打开 portal 会分配其代理路由;它不会向你的服务器注入环境变量。智能体会在该 exec 命令自身的环境中设置 PORT(它打开的端口)和 PUBLIC_URL(返回的无 token 的 publicUrl,包括其初始路径),以便应用绑定到预期端口并生成正确的绝对 URL。
对于位于节点支持的云 worker 上的会话(包括捆绑的 Crabbox 提供商),开发服务器运行在 worker 上。每个 portal 连接都会获得自己的单次使用票据,已注册的节点会在连接到所选 loopback 端口之前,通过固定 TLS 证书到 Gateway 的 WebSocket 兑换该票据。这使用现有的已认证节点通道,而不会将 worker 暴露给入站流量或创建 SSH 隧道。停止或替换 worker 会关闭其 portals。
后台开发服务器在智能体完成回复后仍会继续运行。同一 worker 环境中的后续轮次可以使用 process 检查或停止它。关闭 portal 只会关闭代理;它不会停止服务器。有关进程生命周期和容量详情,请参阅 Worker 后台进程。
智能体还可以使用附加到其现有对话的临时 Crabbox,而无需移动会话的主工作区。它将附件的 environmentId 传递给 portal 工具,并使用 screen 配合 portal_show 和返回的 portalId,在聊天侧边栏中打开该精确预览。应用的命令通过该环境上的 Crabbox 工具运行。其托管的后台进程会在已完成的轮次后继续存在;停止附件会关闭其应用和 portals。该 portal 保留下文所述的相同独立源网络与访问契约。
打开路由并不能证明应用正在运行,也不能证明远程浏览器可以访问它。在 Control UI → Portals 中打开返回的 URL,并验证页面、静态资源和实时重载是否正常工作。原样使用返回的 URL;将其 scheme、主机名或端口替换为 Gateway 的地址并不会创建 ingress 路由。
远程访问¶
当操作员和 Gateway 共享 tailnet 时,优先使用托管私有 Tailscale Serve。否则,请配置下文所述的私有通配符 ingress。仅暴露 Gateway 端点的隧道或反向代理不会暴露应用 portals。
托管私有 Tailscale Serve¶
当托管 Gateway Tailscale ingress 处于激活状态时,每个 portal 都会在托管主机名上获得自己的私有 Serve HTTPS 端口。该 portal 拥有一个前台路由声明,直到其关闭。关闭它、失去其声明、停止其 worker 或重启 Gateway 都会撤回该路由。由其他应用拥有的现有路由不会被 portals 采用或清除。
Portal 路由使用 Serve,绝不使用 Funnel,即使 Gateway 使用 Funnel 也是如此。操作员的浏览器必须位于 tailnet 上。对端口 443 的 Gateway 访问并不能证明可以访问 portal 的独立 HTTPS 端口:限制性 tailnet 授权或 ACL 必须允许返回 URL 中的端口。OpenClaw 不会编辑这些策略。Portal bearer 身份验证仍然必需;Gateway identity-header 身份验证不会授予 portal 访问权限。
私有通配符反向代理¶
使用专用的 DNS 命名空间,例如 preview.example.net,并与 Gateway 和 Control UI 主机名分开。配置一个私有 HTTPS 通配符路由,而不是为每个应用配置一个手动路由:
domain 是裸 DNS 后缀,不包含 scheme、通配符前缀、路径或端口。port 是专用 ingress 监听器在 127.0.0.1 上的 TCP 端口,而不是应用端口或外部 HTTPS 端口。通过重启 Gateway 应用此 Gateway 配置。配置后,通配符 ingress 优先于托管 portal Serve 路由。
按如下方式设置操作员拥有的反向代理:
- 将
*.preview.example.net解析到操作员浏览器可访问的私有 HTTPS 边缘。部署覆盖该通配符的浏览器信任 TLS 证书。默认情况下不要使预览命名空间可公开访问。 - 在端口
443上终止 HTTPS,并将请求转发到 Gateway 主机上的http://127.0.0.1:18890。保留原始Host头、完整请求路径和查询参数,以及 WebSocket 升级。对流式响应禁用响应缓冲。不要剥离路径前缀,也不要转发到 Gateway 的普通 HTTP 端口。 - 使用网络访问控制或覆盖该通配符的显式身份感知访问策略,保持边缘私有。保持 loopback 后端对不受信任主机不可访问。对 Gateway 主机名的身份验证不会自动保护预览通配符。在转发到后端之前,移除边缘注入的身份和凭据头。Portal 会剥离 Tailscale 和 Cloudflare Access 头,但无法识别每个自定义身份验证边缘的头。应用
Authorization头会被保留。 - 打开一个 portal,并从远程浏览器验证精确返回的 HTTPS URL,包括静态资源、导航和 WebSocket 实时重载。主机本地 fetch 或成功的 Gateway 连接不属于此验证。
OpenClaw 不会安装 DNS 记录、颁发证书、配置反向代理,或将 Gateway 访问策略复制到该命名空间。位于另一台机器上的代理需要一条单独保护到 loopback 后端的路径;该路径不会由此设置创建。边缘登录页面或第三方 cookie 限制可能会阻止 iframe 加载,即使新标签页可以正常工作。
每个门户在其生命周期内都会获得配置后缀下的一个随机主机名。 只有处于活动状态的门户主机名才会路由到应用程序;未知或已关闭的主机名 无法选择本地端口或 Gateway API。关闭门户会删除其映射 和活跃连接。共享入口监听器属于 Gateway; 外部通配符 DNS、证书和代理在门户关闭和 Gateway 重启期间仍由操作员拥有。
直接和本地监听器¶
在未配置通配符入口或托管 Tailscale 入口的情况下,返回的
URL 描述的是实际的直接监听器及其 HTTP 或 TLS 方案。直接
监听器使用 Gateway 的绑定接口。当可用时,通配符监听器会通告
Gateway 发现的私有局域网 IPv4 地址,因此该局域网上的浏览器
无需配置入口即可使用返回的 URL。发布的地址
在门户生命周期内保持固定;网络变更后请重新打开门户。
如果没有可用的私有局域网地址,通配符监听器会发布回环 URL。
回环 URL 仅在 Gateway 主机上有效,而不是在不相关的远程浏览器上有效。
直接 TLS 监听器会复用 Gateway 证书。该服务优先选择
来自 gateway.publicOrigin 或已配置 Control
UI 来源的证书有效主机名,然后是证书有效的绑定地址,再是证书中的
具体 DNS 名称。仅凭通配符证书名称无法确定目标;
当需要具体主机名时,请配置现有的 gateway.publicOrigin。
主机名必须解析到 Gateway,并且返回的端口必须可访问。
直接 TLS 不需要额外的门户入口配置。
发现机制和证书名称不会通过防火墙、 容器端口映射或远程代理建立可达性。仅 Gateway 的 HTTPS 代理仍然 需要上述入口路径之一;更改显示的 URL 不会 公开其门户端口。
HTTPS 门户使用安全的分区 cookies,因此当 Control UI 位于另一个站点时,其身份验证也能正常工作。当
Control UI 使用相同方案和主机名时,直接 HTTP 门户可以嵌入;支持不同端口。
否则,Portals 页面会提供新标签页启动,而不是嵌入预览,
因为嵌入预览的身份验证 cookies 可能会被阻止。该链接保持服务发布的
URL 不变。明确使用
SameSite=Strict 或 SameSite=Lax 限制自身 cookies 的应用程序
会保留该策略。
声明开发服务器¶
可选地,将 .openclaw/portals.json 提交到工作区仓库,以便代理发现可用的开发服务器:
{
"portals": [
{
"name": "web",
"command": "pnpm dev",
"cwd": ".",
"port": 3000,
"title": "App",
"description": "Use the seeded test account."
}
]
}
Gateway 永远不会自动执行这些命令。代理读取该文件并决定何时运行已声明的服务器。
| 字段 | 必需 | 描述 |
|---|---|---|
name |
是 | 代理用于识别服务器的稳定名称。 |
command |
是 | 代理使用后台 exec 启动的命令。 |
port |
是 | 应用程序监听的本地 TCP 端口。 |
cwd |
否 | 相对于工作区根目录的工作目录。 |
title |
否 | 显示在 Portals 页面上的标题。 |
description |
否 | 显示在门户旁边的操作员指南。 |
path |
否 | 初始 URL 路径。必须以 / 开头。 |
应用程序契约¶
应用程序必须遵循 PORT。当需要生成绝对 URL 时,请使用 PUBLIC_URL。
服务器可以监听 IPv4 或 IPv6 回环(127.0.0.1 或 ::1),无论是在 Gateway 主机上还是 worker 上,即使机器的 localhost 记录只列出了一个地址族。当通过反向代理连接时,worker 流也会保留节点配置的 Gateway 上下文路径。
代理会将 Host 重写为本地目标,因此 Vite 和 Next.js 等典型开发服务器无需额外配置。WebSocket 和热模块替换通过同一门户进行代理。
流式 HTTP 响应(包括服务器发送事件)会转发响应头,而不会等待第一个正文块。
可用性与配置¶
portal 工具遵循普通工具策略,如 工具配置 中所述。可选的 gateway.portals.ingress 设置仅配置上述私有通配符入口;它不会授予工具访问权限。
开箱即用:
portal属于group:ui和coding配置文件,因此编码代理拥有它,而messaging和minimal代理没有。- 沙箱会话永远不会收到它,因为打开门户会在 Gateway 主机上启动一个监听器。
- 它被阻止用于 HTTP
POST /tools/invoke。全局工具(包括 Gateway 主机端口和主要 worker 放置)仍然仅限会话所有者。 - 非所有者可以为其对话所附加的专用次要 worker 收到一个受限工具。提供商必须明确证明当前租约不是共享主机。未知分类、共享机器或缺少附加会隐藏此模式。Gateway 重启后,新的提供商检查必须再次使租约符合条件。
- 主要云 worker 放置仅在其已注册节点通告 portal-stream 支持时才会收到它。不具备该能力的旧节点捆绑包在该放置模式下不会收到该工具。
要在所有地方关闭门户,请在全局策略中拒绝该工具:
要为单个代理关闭门户,同时保持其他代理不变:
tools.profile、tools.allow、byProvider 和 toolsBySender 对 portal 的应用方式与对其他任何工具相同,因此门户也可以限制为特定提供商、模型或发送者,而无需门户特定设置。
受限工具会自动选择该会话的附件。它没有 environmentId 覆盖,也不能暴露 Gateway 主机端口。其 portal.session.open、portal.session.list 和 portal.session.close RPC 要求对指定会话具有当前写权限,并且具有其生效的 portal 工具策略。自身会话写授权仅适用于其自身会话;更广泛的协作者保留现有的会话共享规则。必需的沙箱隔离以及所有 modelSelectionLocked: true 的会话都排除此模式。对锁定会话的支持需要一个准备好的会话所有权契约,包括原生和导入的会话所有权;现有的 owner 工具在其普通策略下仍然可用。这不会更改主要 worker-turn 放置权限,也不会授予访问其他已附加环境的权限。
作用域预览具有自己的资源身份。通过全局工具和受限工具打开同一应用程序端口会生成不同的链接;关闭或退役作用域预览不会关闭全局预览。在同一会话实例和附件中重复打开会复用该作用域链接。受限列表和关闭操作仅覆盖这些作用域预览。
对于次要附件,工具可用性会检查会话策略和专用机器资格。每次打开和连接都会单独验证当前节点的 portal-stream 支持。因此,符合条件的附件可能在其节点离线或需要更新时显示该工具;请重新连接或更新该 worker 节点,然后重试。
临时 provider 检查错误会为同一租约、节点和所有者保留最后一次显式资格。一次成功的检查如果省略主机分类、报告共享主机,或不再识别活动租约,则会撤回受限能力及其预览。
在 direct 模式下,portal 监听器绑定与 Gateway 相同的接口。绑定到 LAN 或 tailnet 地址的 Gateway 也会在该网络上发布其 direct portal 监听器端口。Managed Serve 使用私有 loopback 后端;配置的通配符入口使用专用 loopback 监听器。访问其中一个仍然需要 portal token,但当 Gateway 主机根本不应提供操作员可访问的应用程序端口时,应拒绝该工具。
安全模型¶
每个 portal 使用单独的源:在 direct/Serve 模式下使用其自己的端口,或使用通配符入口时使用其自己的主机名。切勿将任意应用程序挂载到 Control UI 源上,即使是在不同的 URL 路径下。访问需要 portal URL 中的 token。在首次请求时,代理会将该 token 存储在 HttpOnly cookie 中,并将其从后续上游请求中移除。代理本身验证此 cookie,并且永远不会将其转发到应用程序。
浏览器 cookie 是按主机名作用域划分的,而不是按端口作用域划分的,因此代理为每个 portal 实例提供一个随机的 oc_portal_<instance>_ cookie 名称前缀。请求仅转发具有当前 portal 前缀的 cookie,并在到达应用程序之前去除该前缀;Gateway cookie、无前缀 cookie 以及来自同级或已关闭 portal 的 cookie 会被丢弃。应用程序 Set-Cookie 响应会收到该前缀,并且任何 Domain 属性都会被移除,以便 cookie 保持仅主机。
通配符入口对 portal 认证使用 Secure; SameSite=None; Partitioned,以便嵌入式请求可以在不同的顶级站点下保持已认证状态。应用程序 cookie 也会收到 Secure 和 Partitioned;没有显式 SameSite 属性的 cookie 会收到 SameSite=None。显式的应用程序 SameSite=Lax 或 SameSite=Strict 限制保持不变,并且可能会阻止跨站点嵌入式会话。Partitioned cookie 的作用域是顶级站点,因此在新标签页中打开 portal 可能会创建单独的应用程序会话。浏览器策略仍可能阻止嵌入;代理不会覆盖它们。
服务返回 publicUrl 作为权威的无 token 应用程序 URL,并返回 url 作为其经过身份验证的启动 URL。listenPort 是传输元数据,而不是浏览器 URL 模板。只读列表和变更事件会省略 url 和 tokenQuery;授权客户端使用写权限重新获取它们。请勿将 bearer 凭据放入 PUBLIC_URL,或在日志或截图中共享它。
经过身份验证的 portal URL 是可共享的 bearer 链接,包括会话作用域预览。完成一个 turn 或撤销其发起者不会使已复制的 URL 失效。撤销会阻止该 actor 启动或管理预览。会话作用域资源在其会话被重置或删除、其附件被退役、其环境停止或 Gateway 重启时结束。失去 provider 的显式专用机器资格也会撤回作用域预览。关闭 portal 可立即撤回共享链接。
Portal 仅代理 Gateway 主机或节点支持的云 worker 上选定的开发服务器。Worker 连接使用一次性票据和已注册节点的 TLS 固定 Gateway 连接;它们从不暴露公共 worker 端口,也不需要 SSH 转发。Portal 从不提供 Gateway 数据,并且每个 portal 都会在 Gateway 重启时结束。
限制¶
- 旧版 node bundle 不支持 portal-stream,无法打开 worker portal。请更新 node bundle,或使用
sessions.move将会话移回 Gateway。 - 基于 SSH 的
remote-exec放置(包括 Codex 会话)不会运行 OpenClaw worker 工具循环,因此portal工具在那里不适用。当需要 Gateway 托管的 portal 时,请使用sessions.move将会话移回 Gateway。 - 仅 Gateway 的代理、SSH 隧道或外部管理的 Serve 路由不会自动创建 portal 入口。请配置私有通配符入口或 OpenClaw 管理的 Serve。UI 会将远程 loopback URL 报告为需要入口;它不会编造一个可访问的 URL。
- 浏览器可达性检查仅验证传输。响应可能是身份验证页面或等待页面,而不是渲染后的应用程序。被 Content Security Policy 阻止的检查对 iframe 可达性没有任何说明。
- Portal 入口不会继承 Gateway 可信代理身份、Cloudflare Access 策略或 tailnet ACL 授权。请单独配置并验证这些边界。
- 该前缀隔离转发到每个目标的 cookie;它不会创建单独的浏览器 cookie 存储。在 direct/Serve 模式下,浏览器端代码可以通过
document.cookie看到同一主机名上同级 portal 的非HttpOnlycookie。通配符入口分隔主机名,但位于常见 DNS 后缀下的 portal 不一定是单独的站点,并且 cookie 名称前缀仍然适用。对敏感应用程序 cookie 使用HttpOnly。在浏览器代码中管理 cookie 的应用程序必须考虑该前缀;浏览器代码直接写入的无前缀 cookie 不会被转发到目标。
故障排除¶
门户显示 502 等待页面¶
代理已就绪,但应用未在所选端口上监听,或其工作节点暂时断开连接。页面会自动重试。请检查后台进程,确认服务器遵循 PORT,并验证工作节点已连接。
升级到不可用工作节点的 WebSocket 会返回相同的 502 等待响应并关闭连接。请在应用或工作节点再次可用后重新连接。
无法从此浏览器访问门户¶
请检查实际返回的门户 URL,而不是替换 Gateway 主机:
- 使用远程 Gateway 的回环 URL: 请在 Gateway 主机上打开它,或配置 托管私有 Serve 或泛域名 ingress。仅转发 Gateway 端口 不会转发门户。
- 托管 Serve URL 超时: 请验证 tailnet 成员资格以及对
返回的 HTTPS 端口的访问权限,而不仅仅是
443。检查其托管 claim 是否保持活动状态。 - 泛域名 URL 的 DNS 或 TLS 失败: 请检查泛域名 DNS 和证书覆盖范围。 确认私有边缘可从浏览器访问。
- 泛域名 URL 返回未知主机响应: 请保留原始
Host标头,如果其生命周期已结束,请重新打开门户。不要将其重写为 回环后端主机名。 - 页面加载但流式传输或实时重载失败: 请保留 WebSocket 升级
和请求路径,禁用缓冲,并检查应用的
PUBLIC_URL。 - 新标签页可用但预览不可用: 请检查边缘身份验证、 框架策略和浏览器 Cookie 限制。仅被阻止的可达性检查 本身并不能证明 iframe 不可访问。
修正 ingress 后,请选择 重试。如果其路由已
撤回,请重新打开门户;当 PUBLIC_URL 发生变化时,请使用新的 PUBLIC_URL 重启应用。
关闭门户¶
请要求智能体“关闭门户”,或使用 Control UI → Portals 页面上的关闭按钮。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw