Tailscale（Gateway 儀表板）

OpenClaw 可以自動設定 Tailscale Serve（tailnet 內部）或 Funnel（公開）來處理 Gateway 儀表板和 WebSocket 連接埠。這讓 Gateway 保持綁定在 loopback，由 Tailscale 提供 HTTPS、路由，以及（Serve 模式下的）identity header。

模式

  • serve：僅 tailnet 內部，透過 tailscale serve。Gateway 保持在 127.0.0.1。
  • funnel：公開 HTTPS，透過 tailscale funnel。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 identity header（tailscale-user-login），不需提供 token/password。OpenClaw 會透過本機 Tailscale daemon（tailscale whois）解析 x-forwarded-for 位址並與 header 比對來驗證身分。OpenClaw 只有在請求從 loopback 進入且帶有 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"。

設定範例

僅限 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 裝置連線：

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

注意：loopback（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 時會拒絕啟動，避免公開暴露。
  • 設定 gateway.tailscale.resetOnExit 可讓 OpenClaw 在關閉時還原 tailscale serve 或 tailscale funnel 設定。
  • gateway.bind: "tailnet" 是直接 Tailnet 綁定（無 HTTPS、無 Serve/Funnel）。
  • gateway.bind: "auto" 優先使用 loopback；如果需要 Tailnet-only，請用 tailnet。
  • Serve/Funnel 只暴露 Gateway control UI + WS。節點連線走相同的 Gateway WS 端點，因此 Serve 也適用於節點存取。

瀏覽器控制（遠端 Gateway + 本機瀏覽器）

如果你在一台機器上跑 Gateway 但想操控另一台機器上的瀏覽器，請在瀏覽器所在機器上跑一個 node host，並讓兩者在同一個 tailnet 中。Gateway 會把瀏覽器動作代理到節點上，不需要另外的控制伺服器或 Serve URL。

避免用 Funnel 做瀏覽器控制；把節點配對當作操作者存取來對待。

Tailscale 前置條件 + 限制

  • Serve 需要你的 tailnet 已啟用 HTTPS；CLI 會在缺少時提示。
  • Serve 會注入 Tailscale identity header；Funnel 不會。
  • Funnel 需要 Tailscale v1.38.3+、MagicDNS、已啟用 HTTPS，以及 funnel node attribute。
  • Funnel 僅支援 TLS 的 443、8443 和 10000 連接埠。
  • macOS 上的 Funnel 需要開源版本的 Tailscale app。

深入了解

arrow_back
上一頁
Remote Gateway Readme
下一頁
Formal Verification
arrow_forward