Tailscale（Gateway 控制台）

OpenClaw 可以自动配置 Tailscale Serve（内网）或 Funnel（公网）来托管 Gateway 控制台和 WebSocket 端口。这样 Gateway 本身可以继续绑定到本地回环地址，由 Tailscale 负责提供 HTTPS、路由，以及（Serve 模式下）身份验证 Header。

如果远程节点网络不通，先不要直接切 Funnel。先确认两台机器是否在同一个 Tailnet、MagicDNS 是否能解析、Gateway 绑定的是 loopback 还是 tailnet，再决定用 Serve、Funnel，还是直接监听 Tailnet IP。

模式

serve：通过 tailscale serve 提供仅限内网的 Serve 访问，Gateway 保持绑定到 127.0.0.1。
funnel：通过 tailscale funnel 提供公网 HTTPS 访问，OpenClaw 需要配置共享密码。
off：默认值，不启用 Tailscale 自动化。

认证

通过 gateway.auth.mode 控制握手方式：

token（设置了 OPENCLAW_GATEWAY_TOKEN 时的默认值）
password（通过 OPENCLAW_GATEWAY_PASSWORD 或配置文件设置共享密钥）

当 tailscale.mode = "serve" 且 gateway.auth.allowTailscale 为 true 时，Control UI/WebSocket 认证可以使用 Tailscale 身份 Header（tailscale-user-login），无需提供 token 或密码。OpenClaw 会通过本地 Tailscale 守护进程（tailscale whois）解析 x-forwarded-for 地址，并与 Header 匹配后才接受请求。只有来自本地回环、且同时带有 Tailscale 的 x-forwarded-for、x-forwarded-proto、x-forwarded-host Header 的请求，才会被识别为 Serve 请求。

HTTP API 端点（如 /v1/*、/tools/invoke、/api/channels/*）仍然需要 token/password 认证。

这种无 token 流程前提是 Gateway 主机是可信的。如果同一主机上可能有不受信任的本地代码运行，请禁用 gateway.auth.allowTailscale 并改用 token/password 认证。

如需强制明确凭据，设置 gateway.auth.allowTailscale: false 或 gateway.auth.mode: "password"。

配置示例

仅限内网（Serve）

json5

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

访问地址：https://<magicdns>/（或你配置的 gateway.controlUi.basePath）

直接绑定到内网 IP（无 Serve/Funnel）

当你想让 Gateway 直接监听 Tailnet IP 时使用，不经过 Serve/Funnel 代理。

json5

{
  gateway: {
    bind: "tailnet",
    auth: { mode: "token", token: "your-token" },
  },
}

从另一台 Tailnet 设备连接：

Control UI：http://<tailscale-ip>:18789/
WebSocket：ws://<tailscale-ip>:18789

注意：此模式下回环地址（http://127.0.0.1:18789）不可用。

公网访问（Funnel + 共享密码）

json5

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "replace-me" },
  },
}

建议使用 OPENCLAW_GATEWAY_PASSWORD 环境变量，而不是把密码写进文件。

CLI 示例

bash

openclaw gateway --tailscale serve
openclaw gateway --tailscale funnel --auth password

远程节点网络不通怎么查

按这个顺序排查：

在两台机器上运行 tailscale status，确认都已登录同一个 Tailnet。
从客户端 ping 远端 Tailnet IP，确认基础网络可达。
如果使用 MagicDNS，先访问 https://<magicdns>/，失败时改用 Tailnet IP 验证。
如果配置 gateway.bind: "loopback"，只能通过 Serve/Funnel 或 SSH 隧道访问，不能直接连远端 IP。
如果配置 gateway.bind: "tailnet"，从另一台设备访问 http://<tailscale-ip>:18789/，不要再用本机 127.0.0.1。
Funnel 模式只在确实需要公网访问时使用，并且必须配共享密码。

注意事项

Tailscale Serve/Funnel 需要已安装并登录的 tailscale CLI。
tailscale.mode: "funnel" 如果认证模式不是 password 则拒绝启动，以防止公网暴露。
设置 gateway.tailscale.resetOnExit 可让 OpenClaw 在关闭时撤销 tailscale serve 或 tailscale funnel 配置。
gateway.bind: "tailnet" 是直接绑定 Tailnet IP（无 HTTPS，无 Serve/Funnel）。
gateway.bind: "auto" 默认优先本地回环；如需 Tailnet 访问则使用 tailnet。
Serve/Funnel 仅暴露 Gateway 控制台 + WebSocket。节点通过同一 Gateway WS 端点连接，因此 Serve 也可用于节点访问。

浏览器控制（远端 Gateway + 本地浏览器）

如果你在一台机器上运行 Gateway，而想驱动另一台机器上的浏览器，可以在浏览器所在机器上运行一个节点主机，并让两台机器都加入同一个内网。Gateway 会通过节点代理浏览器操作，无需单独的控制服务器或 Serve URL。

浏览器控制避免使用 Funnel；把节点配对当作运维人员访问来对待。

Tailscale 前提条件与限制

Serve 需要为你的内网启用 HTTPS；CLI 会在缺少时提示。
Serve 会注入 Tailscale 身份 Header；Funnel 不会。
Funnel 需要 Tailscale v1.38.3+、MagicDNS、启用 HTTPS，以及一个 funnel 节点属性。
Funnel 仅支持 TLS 端口 443、8443 和 10000。
macOS 上的 Funnel 需要使用开源版 Tailscale 应用。

Tailscale（Gateway 控制台） ​

模式 ​

认证 ​

配置示例 ​

仅限内网（Serve） ​

直接绑定到内网 IP（无 Serve/Funnel） ​

公网访问（Funnel + 共享密码） ​

CLI 示例 ​

远程节点网络不通怎么查 ​

注意事项 ​

浏览器控制（远端 Gateway + 本地浏览器） ​

Tailscale 前提条件与限制 ​

延伸阅读 ​

Tailscale（Gateway 控制台）

模式

认证

配置示例

仅限内网（Serve）

直接绑定到内网 IP（无 Serve/Funnel）

公网访问（Funnel + 共享密码）

CLI 示例

远程节点网络不通怎么查

注意事项

浏览器控制（远端 Gateway + 本地浏览器）

Tailscale 前提条件与限制

延伸阅读