跳转至

Cloudflare Tunnel 与 Access

在 loopback 上运行 Gateway,通过 Cloudflare Tunnel 发布它,并让 Cloudflare Access 在每个请求到达 OpenClaw 之前对其进行身份验证。Gateway 保持 gateway.bind: "loopback",因此不会暴露任何端口,也无需入站防火墙规则;cloudflared 从主机发起出站连接。

这是除 Tailscale 和 SSH 隧道 之外,又一种受支持的远程访问拓扑。当你希望在 Control UI 前获得稳定的公共 HTTPS URL 和身份提供商 SSO 时,可以选择这种拓扑。

开始之前

  • 一个 Cloudflare 账户,包含你主机名的区域,并已启用 Cloudflare Zero Trust。
  • 在 Gateway 主机上以及任何将使用 CLI 的机器上安装 cloudflared。
  • 一个运行中的 Gateway,位于 127.0.0.1:18789,并带有 gateway.bind: "loopback"。
  • 熟悉本拓扑所使用的 受信代理认证。

各部分如何协同

browser / CLI / node  ->  Cloudflare Access (identity)  ->  Tunnel  ->  127.0.0.1:18789

Access 对请求进行身份验证并注入身份标头。Gateway 不会重新验证用户身份,也不会验证 Access JWT 签名;它会检查受信代理来源和已配置的标头是否存在,然后信任用户标头。由于 allowLoopback 也允许其他本地进程提供这些标头,因此请将 Gateway 端口保持为主机私有,并且只在该主机上运行受信任的工作负载。

步骤 1:将隧道路由到 loopback

添加一条 ingress 规则,将你的主机名映射到 Gateway 端口,然后在 Gateway 主机上将 cloudflared 作为服务运行:

tunnel: <tunnel-id>
credentials-file: /root/.cloudflared/<tunnel-id>.json
ingress:
  - hostname: gateway.example
    service: http://localhost:18789
  - service: http_status:404

请参阅 Cloudflare 官方文档,了解如何创建隧道和 DNS 记录。

步骤 2:使用 Access 保护主机名

为 gateway.example 创建一个 Access 应用程序,并设置一个允许你用户访问的策略。请注意 Access 在已验证请求上添加的两个标头,因为 Gateway 会在下一步中使用它们:

  • cf-access-authenticated-user-email — 已验证的身份。
  • cf-access-jwt-assertion — Access 的签名断言。OpenClaw 仅检查该标头是否存在且非空;它不会验证 JWT 签名。

OIDC 登录与现有人员

对于 OIDC 登录,请配置一个 Access 策略,通过该身份提供商允许目标用户访问。例如,使用提供商维护的签名角色声明。GitHub 组织策略适用于 GitHub 身份提供商;它不会通过单独的 OIDC 提供商授予访问权限。

OpenClaw 通过 Cloudflare Access 的身份端点验证 OIDC 身份,并要求其电子邮件与已验证的用户标头匹配。然后,它通过现有的人员资料来解析该电子邮件。使用相同的电子邮件会保留该人员的资料和角色;使用不同的电子邮件则需要借助现有的关联别名才能解析到该人员。GitHub 登录会继续验证不可变的 GitHub 账户 ID。身份验证失败时不会回退到电子邮件匹配。

让身份提供商负责验证电子邮件的所有权。创建 OpenClaw 人员资料并不会授予通过 Cloudflare Access 访问的权限。

通过 OIDC 验证 GitHub 署名

OIDC 提供商可以提供已验证的 GitHub 账户,而无需更改登录电子邮件或用于发布拉取请求的账户。这是可选的,并且在你明确信任某个 Access 签发者、身份提供商 ID 和声明名称之前,该功能处于禁用状态:

{
  gateway: {
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "cf-access-authenticated-user-email",
        requiredHeaders: ["cf-access-jwt-assertion"],
        cloudflareAccessOidc: {
          issuer: "https://example.cloudflareaccess.com",
          providerId: "your-access-identity-provider-id",
          githubAccountIdClaim: "https://openclaw.ai/github-account-id",
        },
      },
    },
  },
}

issuer 是 Access 团队源,末尾不带斜杠。providerId 是 Access 中所选集成的 ID,而不是其名称或 OIDC 用户主体。提供商必须验证 GitHub 账户的所有权,并将其绑定到已验证的登录电子邮件。其 ID 令牌必须包含一个规范的、正数十进制字符串形式的账户 ID,例如 "12345",且处于 JavaScript 的安全整数范围内。配置 Access 以转发该精确的 自定义 OIDC 声明。OpenClaw 从已验证的 /cdn-cgi/access/get-identity 响应中的 oidc_fields 读取该声明;如果 oidc_fields 不存在,则从 custom 中读取,然后通过 GitHub 验证数字账户,以获取其当前的公开登录名。如果存在 oidc_fields 容器,则以它为准:如果首选容器缺少该声明或其值无效,OpenClaw 不会重试 custom。身份提供商的 Test 预览使用 oidc_fields;请在重新登录后检查已认证的身份端点,以验证 OpenClaw 所消费的响应。

如果可选声明缺失或格式错误,或者签发者/提供商未被选择,则保持普通的仅电子邮件解析。格式错误的声明绝不会发送到 GitHub,也不会用于创建关联或公开署名。如果可选的 GitHub 账户查找失败,OpenClaw 将通过正常的资料和访问策略检查来解析已认证的电子邮件。现有的已授权资料或有效的电子邮件邀请仍然可以登录。仅限 GitHub 的访问要求不能通过电子邮件回退来满足。

查找失败不会创建 GitHub 身份或公开署名。现有的已验证匹配关联和已保存的共同作者偏好保持不变;后续成功的查找可以完成或刷新该关联。此行为同时适用于 oidc_fields 和 custom。无效的 Access 身份验证、主体不匹配、有效账户声明的资料绑定冲突,以及已过期或已撤销的访问权限,仍然无法通过其常规检查。

现有电子邮件配置文件会保留其身份、角色和已保存的共同作者偏好。冲突的 GitHub 账户不会自动合并配置文件或转移电子邮件;管理员必须通过现有的 users.linkEmail 操作来解决。这也适用于以下情况:首次使用的电子邮件认领了一个已属于另一配置文件的账户——必须先显式关联该电子邮件,之后它才能继承该配置文件的角色。显式关联的辅助账户在公开署名中仍保留配置文件的主账户。参见网关配置文件与 GitHub 署名。

第 3 步:在网关中信任这些请求头

将 gateway.auth.mode 设置为 trusted-proxy,并指定 Access 请求头的名称。此处必须启用 allowLoopback:cloudflared 从 127.0.0.1 连接,而 trusted-proxy 认证在其他情况下期望非 loopback 代理。

{
  gateway: {
    bind: "loopback",
    publicOrigin: "https://gateway.example",
    trustedProxies: ["127.0.0.1", "::1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "cf-access-authenticated-user-email",
        requiredHeaders: ["cf-access-jwt-assertion"],
        allowLoopback: true,
      },
    },
  },
}

要求 cf-access-jwt-assertion 是第二次存在性检查,而非加密验证。能够连接到网关的本地进程可以提交这两个请求头,因此不要将此设置视为针对不受信任的本地代码的防御手段。安全边界是锁定的 loopback 端口,加上 Cloudflare Access,并且隧道是外部流量的唯一入口。

publicOrigin 提供外部会话链接、agent 链接说明,以及在省略 controlUi.allowedOrigins 时的浏览器来源默认值。只有当需要不同的浏览器策略时,你才需要显式的允许列表;该列表会替换默认值,而不是在默认值基础上追加。有关配置文件、角色、GitHub 和运维设置,请参见部署团队服务器。

第 4 步:决定节点与 worker 如何接入

Access 会保护主机名上的所有路由,包括节点使用的路由。节点可以在其所需的每一段路径上向 Access 认证——加入请求、主网关 WebSocket、worker socket 和 worker 传输——因此推荐路径不会公开暴露任何内容。

推荐做法:为节点提供 Access 服务令牌。 在应用程序中添加 Service Auth 策略,然后在节点主机上:

export CF_ACCESS_CLIENT_ID="<client-id>"
export CF_ACCESS_CLIENT_SECRET="<client-secret>"
openclaw connect https://gateway.example/j/<code> --service

openclaw connect 会将这些值以环境变量 SecretRef 的形式持久化存储在 gateway.cloudflareAccess.clientId / clientSecret 下;参见节点 CLI。唯一的代价是节点需要在执行加入命令之前就具备这两个值,因此加入链接不再能单独完成即贴即用。

备选方案:豁免自认证路由。 允许 /j/* 和 /__openclaw__/worker 无需 Access 身份即可访问,同时保持 worker 路由上的 WebSocket 升级功能。两者各自强制使用短期凭证——加入码是带有 TTL 的单次使用凭证,按 IP 限速,失败时返回不透明的 404;worker 准入携带自己的过期凭证。这样可以保持加入链接的即贴即用,代价是这两个路由可被公开访问。除非你需要这种接入流程,否则优先使用服务令牌。参见节点。

如果两者都不采用,openclaw connect 在通过隧道连接时会失败,即使浏览器可以正常工作,因为加入请求会被重定向到 Access 登录页面。

第 5 步:连接每个客户端

控制界面(Control UI)。 打开 https://gateway.example 并通过 Access 登录。使用 trusted-proxy 认证时,网关会将你的 Access 身份映射为操作员会话。

如果聊天进行期间 Access 过期,聊天连接可以保持活动,而新的图片和文件请求需要重新获得网站访问权限。控制界面首先会尝试通过隐藏的、沙盒化的浏览器导航自动续期。如果你的全局 Cloudflare Access 会话仍然有效,并且浏览器允许其 cookie,Access 可以签发新的应用 cookie,而无需再次登录。OpenClaw 会在重试失败的附件之前验证访问权限,从而保持你的对话和未发送草稿处于打开状态。

如果续期仍需要登录,控制界面会打开一个登录以继续加载内容对话框。全局会话过期、身份提供方质询或第三方 cookie 被阻止都可能需要这个手动步骤。自动续期不会延长在 Cloudflare Access 中配置的会话时长。选择登录,在新标签页中完成认证,然后返回对话。可见的失败附件会在访问验证通过后重试;原始对话和未发送草稿保持打开。再次检查会重复访问检查,暂不会关闭提示而不中断聊天。普通网络故障和文件缺失不会触发此对话框。

CLI 和 TUI。 它们不携带浏览器 cookie,因此在 WebSocket 升级时会出示 Access 令牌。按照远程访问中的说明配置 gateway.remote.edgeAuth,然后运行一次 cloudflared access login https://gateway.example 以缓存令牌。

节点。 按照第 4 步中选择的方案操作。

验证

openclaw tui

预期 TUI 会连接 wss://gateway.example 并显示 connected。首次连接可能会报告 device pairing required;在控制界面的 设置 → 设备 下批准该请求,或在网关主机上运行 openclaw devices approve --latest 预览请求,然后重新运行它打印出的批准命令。

能够到达网关自身的配对提示,这本身就是 Access 认证已通过的证明——未经认证的请求永远无法走到这一步。

生产就绪

  • 保持 gateway.bind: "loopback"。绑定到更宽的地址范围会重新将网关暴露在隧道旁边,并完全绕过 Access。
  • 保持 trustedProxies 仅限 loopback。这是网关会信任其身份请求头的地址列表。
  • trustedProxy.deviceAutoApprove 可以为通过 Access 认证的身份自动配对设备。它省去了手动批准步骤;只有当你接受“任何通过 Access 的人都能获得具有你所列出作用域的已配对设备”这一事实时,才启用它。
  • Access 令牌会按应用程序的会话时长过期。CLI 用户需要在令牌失效后重新运行 cloudflared access login。

故障排除

症状 原因及解决方法
来自 CLI 或 TUI 的 gateway rejected websocket upgrade (HTTP 302) Access 拦截了升级请求。配置 gateway.remote.edgeAuth;参见 远程访问。
浏览器可用,但 openclaw connect 失败 节点路由仍位于 Access 之后。应用第 4 步中的任一选项。
Exec provider ... exited with code 1 exec 密钥提供程序在清理后的环境中运行;cloudflared 需要 passEnv: ["HOME"] 才能读取其缓存的 Token。
secrets.providers.*.command must not be a symlink 将 command 指向已解析的二进制文件,而不是包管理器符号链接。
Gateway 启动但每个请求都是匿名的 allowLoopback 未设置,因此来自本地 cloudflared 的标头被忽略。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw