OpenClaw 🦞

Tailscale

Tailscale（Gateway 仪表板）

OpenClaw 可以为 Gateway 仪表板和 WebSocket 端口自动配置 Tailscale Serve（tailnet）或 Funnel（公共）。这使 Gateway 保持绑定到环回，同时 Tailscale 提供 HTTPS、路由和（对于 Serve）身份头部。

模式

  • serve：通过 tailscale serve 的仅 Tailnet 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 时， 控制 UI/WebSocket 认证可以使用 Tailscale 身份头部 （tailscale-user-login）而无需提供令牌/密码。OpenClaw 通过本地 Tailscale 守护进程（tailscale whois）解析 x-forwarded-for 地址并将其与头部匹配来验证 身份，然后才接受它。 OpenClaw 仅当请求从环回到达并具有 Tailscale 的 x-forwarded-for、x-forwarded-proto 和 x-forwarded-host 头部时才将请求视为 Serve。 HTTP API 端点（例如 /v1/*、/tools/invoke 和 /api/channels/*） 仍然需要令牌/密码认证。 此无令牌流假设 Gateway 主机是受信任的。如果不受信任的本地代码 可能在同一主机上运行，禁用 gateway.auth.allowTailscale 并需要 令牌/密码认证。 要要求显式凭证，设置 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 设备连接：

  • 控制 UI：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 而非将密码提交到磁盘。

CLI 示例

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

说明

  • Tailscale Serve/Funnel 需要安装并登录 tailscale CLI。
  • 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 控制 UI + WS。节点通过 相同的 Gateway WS 端点连接，所以 Serve 可以用于节点访问。

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

如果你在一台机器上运行 Gateway 但想在另一台机器上驱动浏览器， 在浏览器机器上运行节点主机并保持两者在同一个 tailnet 上。 Gateway 将代理浏览器操作到节点；不需要单独的控制服务器或 Serve URL。

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

Tailscale 先决条件 + 限制

  • Serve 需要为你的 tailnet 启用 HTTPS；如果缺少，CLI 会提示。
  • Serve 注入 Tailscale 身份头部；Funnel 不注入。
  • Funnel 需要 Tailscale v1.38.3+、MagicDNS、启用 HTTPS 和 funnel 节点属性。
  • Funnel 仅支持 TLS 上的端口 443、8443 和 10000。
  • macOS 上的 Funnel 需要开源 Tailscale 应用程序变体。

了解更多