Tailscale
OpenClaw 可以为 Gateway 仪表板和 WebSocket 端口自动配置 Tailscale Serve(tailnet)或 Funnel(公共)。这样可保持 Gateway 绑定到 loopback,同时由 Tailscale 提供 HTTPS、路由以及(对于 Serve)身份头。
Note
正在寻找分步设置?请参阅 为您的 Gateway 提供稳定的 HTTPS URL.
模式¶
gateway.tailscale.mode:
| 模式 | 行为 |
|---|---|
serve |
通过 tailscale serve 提供仅限 Tailnet 的 Serve。Gateway 保持在 127.0.0.1。 |
funnel |
通过 tailscale funnel 提供公共 HTTPS。需要共享密码。 |
off(默认) |
无 Tailscale 自动化。 |
状态和审计输出在此 OpenClaw Serve/Funnel 模式下使用 Tailscale 暴露。off 表示 OpenClaw 未管理 Serve 或 Funnel。它并不意味着本地 Tailscale 守护进程已停止或已注销。
配置示例¶
仅限 Tailnet(Serve)¶
打开:https://<magicdns>/(或您配置的 gateway.controlUi.basePath)
仅限 Tailnet(绑定到 Tailnet IP)¶
使用此方式可让 Gateway 直接监听 Tailnet IP,而不使用 Serve/Funnel:
从另一个 Tailnet 设备连接原生或 CLI 客户端:
- WebSocket:
ws://<tailscale-ip>:18789
浏览器 Control UI 可以使用纯 JavaScript Ed25519,通过直接的纯 HTTP 地址创建并签署设备身份。在使用 token/密码身份验证时,共享密钥仍然不能替代浏览器设备身份。
纯 HTTP 仍然是降级传输:身份签署不会加密页面、共享密钥或 Gateway 流量。对于 HTTPS,请优先使用 Tailscale Serve。请参阅 不安全 HTTP。
从 Tailnet 地址本身加载 Control UI 属于私有同源请求,无需 gateway.controlUi.allowedOrigins 条目。公共或跨源浏览器部署需要允许的来源。
Note
当存在可绑定的 Tailnet IPv4 时,Gateway 还要求为经过身份验证的同主机客户端使用 http://127.0.0.1:18789。如果启动时没有可用的 Tailnet 地址,则仅回退到 loopback。在 Tailscale 可用后重启,以添加直接 Tailnet 访问。这两种路径都不会增加 LAN 或公共暴露。
公共互联网(Funnel + 共享密码)¶
{
gateway: {
bind: "loopback",
tailscale: { mode: "funnel" },
auth: { mode: "password", password: "replace-me" },
},
}
优先使用 OPENCLAW_GATEWAY_PASSWORD,而不是将密码提交到磁盘。
Funnel URL 也可以从 tailnet 内的设备使用。Tailscale 将公共请求标记为 Funnel 流量,但会将 tailnet 对等节点转而通过其 Serve 身份路径发送。OpenClaw 在其专用监听器上识别这两种路径,并且仍然要求使用已配置的 Funnel 密码。
CLI 示例¶
身份验证¶
gateway.auth.mode 控制握手:
| 模式 | 使用场景 |
|---|---|
none |
仅限私有入口 |
token(默认) |
通过 OPENCLAW_GATEWAY_TOKEN 或配置使用共享 token |
password |
通过 OPENCLAW_GATEWAY_PASSWORD 或配置使用共享密钥 |
trusted-proxy |
身份感知反向代理;请参阅 可信代理身份验证 |
当 gateway.auth.mode 未设置时,已解析的密码会选择密码模式。如果没有,则默认使用 token。如果同时配置了 gateway.auth.token 和 gateway.auth.password,请显式设置模式。
当 token 模式没有凭据时,loopback 启动会生成一个仅运行时使用的 token,而不会将其写入配置。单独的 openclaw qr 命令仍然需要可用的已配置或提供的 token/密码身份验证。该仅启动时使用的 token 不会配置配对。请参阅 QR 身份验证解析。
Tailscale 身份头(仅 Serve)¶
当 tailscale.mode: "serve" 且 gateway.auth.allowTailscale 为 true 时,Control UI/WebSocket 身份验证可以使用 Tailscale 身份头(tailscale-user-login)代替 token/密码。OpenClaw 通过本地 Tailscale 守护进程(tailscale whois)解析请求的 x-forwarded-for 地址,并将其与头部登录信息匹配后,再接受该头部。只有当请求携带 Tailscale 的 x-forwarded-for、x-forwarded-proto 和 x-forwarded-host 头部到达 OpenClaw 专用的受管 Tailscale 监听器时,才符合条件。这些头部绝不会在普通 Gateway 监听器上建立受管 Serve 来源或无 token 身份验证。
此无 token 流程假设 Gateway 主机是受信任的。如果不受信任的本地代码可能在同一主机上运行,请设置 gateway.auth.allowTailscale: false,并改为要求 token/密码身份验证。
绕过范围:
- 适用于 Control UI WebSocket 身份验证表面以及用于 Control UI 个人资料头像的只读
GET/HEAD请求。其他 HTTP API 端点(/v1/*、/tools/invoke、/api/channels/*等)从不使用 Tailscale 身份头身份验证。它们始终遵循 Gateway 的常规 HTTP 身份验证模式。 - 对于已经携带浏览器设备身份的 Control UI 操作员会话,经过验证的 Tailscale 身份会跳过 bootstrap-token/QR 配对往返。
- 它不会绕过设备身份本身:无设备客户端仍会被拒绝,节点角色连接仍会经过常规配对和身份验证检查。
外部管理的 Serve 和 Funnel¶
当另一个服务拥有该路由时,您可以将原生 Tailscale Serve 或 Funnel 路由指向普通的 Gateway 监听器。在 gateway.trustedProxies 中严格限制该路由的直接来源,并确保它会覆盖或安全地重建 X-Forwarded-For。随后,OpenClaw 会将该请求视为通用的 trusted-proxy 入口,使用转发的客户端地址进行速率限制,并正常应用已配置的 Gateway 认证模式。由于 Funnel 是公开的,当 gateway.auth.mode 为 none 时,受 Gateway 保护的路由会拒绝外部管理的 Funnel 入口。请配置 token、password 或 trusted-proxy 认证。聚合的健康、就绪和启动检查将保留其现有的未认证响应,而不暴露详细的就绪或启动数据。参见 健康和就绪。
此兼容性路径不会授予受管理的 Tailscale 语义。gateway.auth.allowTailscale 无法提供无 token 认证。OpenClaw 不会调用 tailscale whois。它不会拥有或清理外部路由。如果没有明确受信任的来源以及有效的非回环转发客户端地址,受 Gateway 认证的路由会以 proxy_attribution_required 失败。如果代理通过回环连接,将 127.0.0.1 添加到 trustedProxies 会明确信任同一主机上的进程提供代理归属。除非主机上的每个进程都属于同一信任边界,否则请保持 token 或 password 认证启用。
备注¶
- Tailscale Serve/Funnel 要求已安装并登录
tailscaleCLI。 - 普通的
openclaw doctor会在维护和修复提示之前检查已配置的本地 Serve/Funnel 后端。它会列出已停止、已登出、等待批准、正在启动或不可用的后端,并打印下一步操作。此先决条件检查不会启用 Tailscale、更改路由或修改暴露/认证设置。由更新驱动的 Doctor 会将此建议推迟到更新后普通 Doctor 运行时,因为随附的更新器限制候选配置读取;修复仍为尽力而为。仅后端正在运行并不能证明 Serve/Funnel 路由或 Gateway 已就绪。 tailscale.mode: "funnel"除非认证模式为password,否则拒绝启动,以避免公开暴露。- OpenClaw 将 Serve/Funnel 作为前台 Tailscale 声明持有。只有在该声明激活后,Gateway 启动才会成功;停止或失去 Gateway 会自动释放它。
- 在启动期间停止也会在就绪之前释放该声明。如果 Tailscale 需要
sudo -n,清理会对 OpenClaw 启动的进程组使用sudo -n /bin/kill。使用sudo tailscale set --operator=$USER授予 Gateway 用户 Tailscale 操作员访问权限,以避免需要特权启动和清理。 - 启用受管理的入口后,启动可以在其受管理的端口上采用先前存在的后台 HTTPS 根路由。当目标恰好为
http://127.0.0.1:<configured-gateway-port>,或等效的localhostURL(可选带尾随斜杠)时,它会采用该路由。随后,启动会用专用的受管理监听器替换该路由并记录采用情况。指向其他目标的路由,或其端口与其他处理器或主机名共享的根路由,将保持不变。启动会报告冲突的 HTTPS 端口和恢复指导。Doctor 不会更改外部管理的配置。 - 受管理的入口不支持命名的 Tailscale Services,因为 Tailscale 要求它们作为持久后台路由运行。现有
gateway.tailscale.serviceName安装必须运行openclaw doctor --fix。Doctor 会禁用受管理的入口并移除该键。检查保留的 Service 路由,使用tailscale serve clear <service-name>清除它,然后如需要,使用gateway.tailscale.mode: "serve"启用设备 Serve。 - 旧版本可能会发布一个外部配置的默认 HTTPS Serve 路由,其目标为
gateway.bind: "lan"监听器。该路由不会自动获得受信任入口来源。运行openclaw doctor检查它。Doctor 不会更改配置,因为它无法证明谁拥有该路由。该路由可能属于当前 Tailscale 主机名,并且是旧 OpenClaw 版本遗留的。如果您确认这一点,仅使用tailscale serve --yes --https=443 --set-path=/ off或tailscale funnel --yes --https=443 --set-path=/ off移除其根处理器。然后手动配置gateway.bind: "loopback"加上gateway.tailscale.mode: "serve",并重启 Gateway。如果另一个服务必须保留所有权,请保持受管理的 Tailscale 入口关闭,并使用上述显式trustedProxies兼容性路径。 gateway.tailscale.preserveFunnel: true是一个已弃用的迁移保护。它在重新应用 Serve 之前检测外部配置的tailscale funnel路由。如果该路由仍指向普通的 Gateway 监听器,OpenClaw 会保持不变并发出警告,因为该路由不是受管理的入口。受 Gateway 认证的路由仅通过上述显式trustedProxies兼容性路径工作,并继续要求已配置的认证。插件认证的 webhook 路由(例如 Google Chat 和 SMS)继续使用其自身的签名和认证检查。要迁移,首先配置持久的gateway.auth.password(优先使用 SecretRef)或OPENCLAW_GATEWAY_PASSWORD。将gateway.auth.mode设置为password。运行openclaw config set gateway.tailscale.mode funnel。然后运行openclaw config unset gateway.tailscale.preserveFunnel。gateway.bind: "tailnet"使用直接 Tailnet 绑定(无 HTTPS,无 Serve/Funnel),并在有 Tailnet IPv4 可用时加上必需的本地127.0.0.1。否则,它仅回退到回环。gateway.bind: "auto"在检测到的容器中使用0.0.0.0,否则优先使用回环。使用tailnet可将直接网络暴露限制在 Tailnet,同时保留同一主机的回环访问。- 主 Serve/Funnel 路由暴露 Gateway Control UI + WS。节点通过同一 WS 端点连接。门户 分配单独的私有 Serve HTTPS 端口;它们从不继承 Funnel 暴露。Tailnet 授权或 ACL 必须允许门户端口以及 Gateway 端口。外部管理的路由不会自动分配门户入口。
Tailscale 先决条件和限制¶
- Serve 要求为你的 tailnet 启用 HTTPS。如果缺失,CLI 会提示。
- Tailnet Serve 流量会注入 Tailscale 身份头。公共 Funnel 流量改用 Funnel 标记,而 tailnet 对同一 Funnel URL 的访问遵循 Serve 身份路径。
- OpenClaw 托管的 Serve/Funnel 代理到专用的
127.0.0.1:<ephemeral-port>监听器,而普通本地客户端继续使用已配置的 Gateway 端口。启动会失败关闭,而不是共享监听器来源,并且当前台占用的 Gateway 所有者消失时,该占用会释放路由。 - 当 Gateway 在开机启动时先于本地 Tailscale 守护进程连接而启动(
tailscale status报告NoState或Starting,或者守护进程尚未接受连接)时,托管占用会最多等待 90 秒,并记录进度。任何其他守护进程状态都会立即失败关闭。 - 主机名发现接受最多 16 MiB 的状态输出,包括大型 tailnet 中的对等列表。如果发现失败,Gateway 会记录警告并保留其活动的 Serve/Funnel 占用,但托管门户仍不可用。在 Gateway 主机上检查
tailscale status --json,解决报告的错误,并重启 Gateway 以发布其主机名。 - Funnel 需要 Tailscale v1.38.3+、MagicDNS、启用 HTTPS 以及一个 funnel 节点属性。
- Funnel 仅支持通过 TLS 使用端口
443、8443和10000。 - macOS 上的 Funnel 需要开源 Tailscale 应用变体。
恢复孤立的前台占用¶
旧版 Gateway 可能在强制关机或中断的 sudo 支持启动后,留下一个仍在运行的前台 Tailscale 占用。更新会修复对新占用的清理,但不会自动移除所有权未经验证的现有占用。
如果启动报告 HTTPS 端口被占用,请运行 tailscale serve status --json。
在 Foreground 中检查报告的会话、主机名、路径和代理目标。
在 macOS 或 Linux 上,使用
ps -axo pid,ppid,args | grep '[t]ailscale' 检查候选 CLI 进程。在停止它之前,确认是哪个进程创建了该
路由,然后使用 kill -TERM <confirmed-pid> 停止它(对于 root 进程,使用 sudo kill -TERM <confirmed-pid>)。Tailscale 状态不会
报告占用方 PID。仅凭后端监听器 PID 或孤立的父进程并不能
证明所有权。如果另一个应用程序拥有该占用,请保持原样,
并在解决冲突之前保持 OpenClaw 托管入口关闭。
验证前台会话已从 tailscale serve status
--json 中消失,然后重启 Gateway。tailscale serve --https=443 --set-path=/ off
会移除后台 Web 处理器。它不会释放前台占用。
浏览器控制(远程 Gateway + 本地浏览器)¶
若要在一台机器上运行 Gateway,但在另一台机器上驱动浏览器,请在浏览器机器上运行一个 node host。让两台机器保持在同一 tailnet 中。Gateway 会将浏览器操作代理到节点。无需单独的控制服务器或 Serve URL。
避免在浏览器控制中使用 Funnel。将节点配对视为操作员访问。
了解更多¶
- Tailscale Serve 概述:https://tailscale.com/kb/1312/serve
tailscale serve命令:https://tailscale.com/kb/1242/tailscale-serve- Tailscale Funnel 概述:https://tailscale.com/kb/1223/tailscale-funnel
tailscale funnel命令:https://tailscale.com/kb/1311/tailscale-funnel
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw