Skip to content
OpenClaw Docs

Tailscale

Tailscale (Gateway 儀表板)

Section titled “Tailscale (Gateway 儀表板)”

OpenClaw 可以針對 Gateway 儀表板和 WebSocket 連接埠，自動設定 Tailscale Serve (tailnet) 或 Funnel (公開)。這讓 Gateway 保持在 loopback 上，同時由 Tailscale 提供 HTTPS、路由以及 (針對 Serve 的) 身分標頭。

模式

Section titled “模式”
  • serve：透過 tailscale serve 僅限 Tailnet 的 Serve。Gateway 維持在 127.0.0.1 上。
  • funnel：透過 tailscale funnel 提供公開 HTTPS。OpenClaw 需要一個共用密碼。
  • off：預設值 (無 Tailscale 自動化)。

驗證

Section titled “驗證”

設定 gateway.auth.mode 以控制交握：

  • token (設定 OPENCLAW_GATEWAY_TOKEN 時的預設值)
  • password (透過 OPENCLAW_GATEWAY_PASSWORD 或設定提供共用金鑰)

當 tailscale.mode = "serve" 且 gateway.auth.allowTailscale 為 true 時， Control UI/WebSocket 驗證可以使用 Tailscale 身分標頭 (tailscale-user-login) 而無需提供 token/密碼。OpenClaw 會透過本機 Tailscale daemon (tailscale whois) 解析 x-forwarded-for 位址來驗證身分，並在 accepting 前與標頭進行比對。 只有當請求來自 loopback 且帶有 Tailscale 的 x-forwarded-for、x-forwarded-proto 和 x-forwarded-host 標頭時，OpenClaw 才會將其視為 Serve 請求。 HTTP API 端點 (例如 /v1/*、/tools/invoke 和 /api/channels/*) 仍然需要 token/密碼驗證。 這個無 token 的流程假設 gateway 主機是受信任的。如果不受信任的本機程式碼 可能在同一台主機上執行，請停用 gateway.auth.allowTailscale 並改為要求 token/密碼驗證。 若要要求明確的憑證，請設定 gateway.auth.allowTailscale: false 或 強制 gateway.auth.mode: "password"。

設定範例

Section titled “設定範例”

僅限 Tailnet (Serve)

Section titled “僅限 Tailnet (Serve)”
{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

開啟：https://<magicdns>/ （或您設定的 gateway.controlUi.basePath）

僅限 Tailnet（綁定至 Tailnet IP）

Section titled “僅限 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

注意：在此模式下，loopback (http://127.0.0.1:18789) 將無法運作。

公開網際網路（Funnel + 共用密碼）

Section titled “公開網際網路（Funnel + 共用密碼）”
{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "replace-me" },
  },
}

優先使用 OPENCLAW_GATEWAY_PASSWORD 而非將密碼寫入磁碟。

CLI 範例

Section titled “CLI 範例”
Terminal window
openclaw gateway --tailscale serve
openclaw gateway --tailscale funnel --auth password

備註

Section titled “備註”
  • 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" 優先使用 loopback；如果您只要 Tailnet，請使用 tailnet。
  • Serve/Funnel 僅會公開 Gateway 控制介面 + WS。節點透過 同一個 Gateway WS 端點連線，因此 Serve 可用於節點存取。

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

Section titled “瀏覽器控制（遠端 Gateway + 本機瀏覽器）”

如果您在一台機器上執行 Gateway，但想在另一台機器上操作瀏覽器， 請在瀏覽器機器上執行 node host，並將兩者保持在同一個 tailnet 中。 Gateway 會將瀏覽器操作代理至節點；不需要額外的控制伺服器或 Serve URL。

避免使用 Funnel 進行瀏覽器控制；將節點配對視為操作員存取。

Tailscale 先決條件 + 限制

Section titled “Tailscale 先決條件 + 限制”
  • Serve 需要為您的 tailnet 啟用 HTTPS；如果缺少該功能，CLI 會提示您。
  • Serve 會注入 Tailscale 身份標頭；Funnel 則不會。
  • Funnel 需要 Tailscale v1.38.3+、MagicDNS、啟用 HTTPS 以及一個 funnel 節點屬性。
  • Funnel 在 TLS 上僅支援連接埠 443、8443 和 10000。
  • 在 macOS 上使用 Funnel 需要開放原始碼的 Tailscale 應用程式版本。

深入了解

Section titled “深入了解”