Tailscale（Gateway 控制面板）

OpenClaw 可以为 Gateway 控制面板和 WebSocket 端口自动配置 Tailscale Serve（tailnet 内部）或 Funnel（公网）。这样可以让 Gateway 绑定到本地回环地址，同时由 Tailscale 提供 HTTPS、路由以及（对于 Serve 模式）身份标识头。

模式

  • serve：仅限 tailnet 内部访问，通过 tailscale 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 时，有效的 Serve 代理请求可以通过 Tailscale 身份标识头（tailscale-user-login）进行认证，无需提供 token 或密码。OpenClaw 会通过本地 Tailscale 守护进程（tailscale whois）解析 x-forwarded-for 地址来验证身份，并在接受请求前将其与标识头进行匹配。

OpenClaw 只会在请求来自本地回环地址且带有 Tailscale 的 x-forwarded-for、x-forwarded-proto 和 x-forwarded-host 标识头时，才将其视为 Serve 请求。

如果要强制要求明确的凭据，可以设置 gateway.auth.allowTailscale: false 或强制使用 gateway.auth.mode: "password"。

配置示例

仅限 tailnet 内部（Serve）

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

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

仅限 tailnet 内部（绑定到 Tailnet IP）

当你希望 Gateway 直接监听 Tailnet IP 地址时使用此方式（不使用 Serve/Funnel）。

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

从 Tailnet 内的其他设备连接：

  • 控制界面：http://<tailscale-ip>:18789/
  • WebSocket：ws://<tailscale-ip>:18789

注意：在此模式下，本地回环地址（http://127.0.0.1:18789）无法使用。

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

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

建议使用 OPENCLAW_GATEWAY_PASSWORD 环境变量，而不是将密码写入配置文件。

命令行示例

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

注意事项

  • Tailscale Serve/Funnel 需要安装 tailscale 命令行工具并已登录。
  • tailscale.mode: "funnel" 会拒绝启动，除非认证模式设置为 password，以避免公网暴露。
  • 如果希望 OpenClaw 在关闭时撤销 tailscale serve 或 tailscale funnel 配置，可以设置 gateway.tailscale.resetOnExit。
  • gateway.bind: "tailnet" 是直接绑定到 Tailnet（无 HTTPS，无 Serve/Funnel）。
  • gateway.bind: "auto" 优先使用本地回环地址；如果只想用 Tailnet，请使用 tailnet。
  • Serve/Funnel 只暴露 Gateway 控制界面 + WebSocket。节点通过相同的 Gateway WebSocket 端点连接，所以 Serve 可以用于节点访问。

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

如果你在一台机器上运行 Gateway，但想在另一台机器上控制浏览器，可以在浏览器所在的机器上运行一个 node host，并确保两台机器都在同一个 tailnet 中。Gateway 会将浏览器操作代理到节点；不需要单独的控制服务器或 Serve URL。

避免使用 Funnel 进行浏览器控制；将节点配对视为操作员访问。

Tailscale 前置条件和限制

  • Serve 需要为你的 tailnet 启用 HTTPS；如果缺少，命令行工具会提示。
  • Serve 会注入 Tailscale 身份标识头；Funnel 不会。
  • Funnel 需要 Tailscale v1.38.3+、MagicDNS、启用 HTTPS 以及 funnel 节点属性。
  • Funnel 仅支持通过 TLS 使用端口 443、8443 和 10000。
  • macOS 上的 Funnel 需要使用开源版本的 Tailscale 应用。

了解更多