Tailscale

OpenClaw 可為閘道儀表板與 WebSocket 連接埠自動設定 Tailscale Serve（tailnet）或 Funnel（公開）。如此可讓閘道繫結至迴環介面，同時由 Tailscale 提供 HTTPS、路由，以及（針對 Serve）身分識別標頭。

​

模式

gateway.tailscale.mode：

模式	行為
serve	透過 tailscale serve 提供僅限 Tailnet 的 Serve。閘道會維持在 127.0.0.1。
funnel	透過 tailscale funnel 提供公開 HTTPS。需要共用密碼。
off（預設）	不使用 Tailscale 自動化。

狀態與稽核輸出使用 Tailscale 暴露方式 來表示此 OpenClaw Serve/Funnel 模式。off 表示 OpenClaw 未管理 Serve 或 Funnel；這不表示本機 Tailscale 常駐程式已停止或登出。

​

設定範例

​

僅限 Tailnet（Serve）

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

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

若要透過具名 Tailscale Service 而非裝置主機名稱公開控制介面，請將 gateway.tailscale.serviceName 設為 Service 名稱：

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve", serviceName: "svc:openclaw" },
  },
}

啟動時便會將 Service URL 回報為 https://openclaw.<tailnet-name>.ts.net/，而非裝置主機名稱。Tailscale Services 要求主機是 tailnet 中已核准且具標籤的節點——啟用此功能前，請先在 Tailscale 中設定標籤並核准 Service，否則 tailscale serve --service=... 會在閘道啟動期間失敗。

​

僅限 Tailnet（繫結至 Tailnet IP）

使用此設定可讓閘道直接接聽 Tailnet IP，而不使用 Serve/Funnel：

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

從另一部 Tailnet 裝置連線：

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

若存在可繫結的 Tailnet IPv4，閘道也會要求已驗證的同主機用戶端使用 http://127.0.0.1:18789。若啟動時沒有可用的 Tailnet 位址，則只會退回迴環介面；請在 Tailscale 可用後重新啟動，以新增直接 Tailnet 存取。這兩種路徑都不會新增 LAN 或公開暴露。

​

公開網際網路（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

​

驗證

gateway.auth.mode 控制交握：

模式	使用情境
none	僅限私人入口
token（設定 OPENCLAW_GATEWAY_TOKEN 時的預設值）	共用權杖
password	透過 OPENCLAW_GATEWAY_PASSWORD 或設定提供共用密碼
trusted-proxy	可識別身分的反向 Proxy；請參閱受信任的 Proxy 驗證

​

Tailscale 身分識別標頭（僅限 Serve）

當 tailscale.mode: "serve" 且 gateway.auth.allowTailscale 為 true 時，控制介面/WebSocket 驗證可使用 Tailscale 身分識別標頭（tailscale-user-login），而非權杖/密碼。OpenClaw 會透過本機 Tailscale 常駐程式（tailscale whois）解析請求的 x-forwarded-for 位址，並在接受請求前確認其與標頭中的登入身分相符，以驗證該標頭。只有當請求來自迴環介面，且帶有 Tailscale 的 x-forwarded-for、x-forwarded-proto 與 x-forwarded-host 標頭時，才符合使用此路徑的資格。

此無權杖流程假設閘道主機值得信任。如果不受信任的本機程式碼可能在同一主機上執行，請設定 gateway.auth.allowTailscale: false，並改為要求權杖/密碼驗證。

略過驗證的範圍：

• 僅適用於控制介面的 WebSocket 驗證介面。HTTP API 端點（/v1/*、/tools/invoke、/api/channels/* 等）絕不使用 Tailscale 身分識別標頭驗證；它們一律遵循閘道的一般 HTTP 驗證模式。
• 對於已帶有瀏覽器裝置身分識別的控制介面操作員工作階段，經驗證的 Tailscale 身分可略過啟動權杖/QR Code 配對往返流程。
• 這不會略過裝置身分識別本身：缺少裝置身分的用戶端仍會遭拒，而節點角色連線仍須通過一般配對與驗證檢查。

​

注意事項

• Tailscale Serve/Funnel 要求已安裝並登入 tailscale 命令列介面。
• 除非驗證模式為 password，否則 tailscale.mode: "funnel" 會拒絕啟動，以避免公開暴露。
• gateway.tailscale.serviceName 僅適用於 Serve 模式，並會傳遞至 tailscale serve --service=<name>。該值必須使用 Tailscale 的 svc:<dns-label> 格式，例如 svc:openclaw。Tailscale 要求 Service 主機是具標籤的節點，且在 Serve 發布 Service 前，可能需要先在管理控制台中核准。
• gateway.tailscale.resetOnExit 會在關閉時復原 tailscale serve/tailscale funnel 設定。
• gateway.tailscale.preserveFunnel: true 會讓外部設定的 tailscale funnel 路由在閘道重新啟動後仍維持運作。使用 mode: "serve" 時，OpenClaw 會在重新套用 Serve 前檢查 tailscale funnel status，若已有 Funnel 路由涵蓋閘道連接埠，便會略過套用。由 OpenClaw 管理的 Funnel 僅限密碼原則維持不變。
• gateway.bind: "tailnet" 使用直接 Tailnet 繫結（無 HTTPS、無 Serve/Funnel），並在 Tailnet IPv4 可用時要求本機 127.0.0.1；否則只會退回迴環介面。
• gateway.bind: "auto" 優先使用迴環介面；使用 tailnet 可將網路暴露限制在 Tailnet 內，同時保留同主機迴環存取。
• Serve/Funnel 只會公開 閘道控制介面 + WS。節點會透過相同的閘道 WS 端點連線，因此 Serve 也適用於節點存取。

​

Tailscale 必要條件與限制

• Serve 要求為你的 tailnet 啟用 HTTPS；若尚未啟用，命令列介面會提示。
• Serve 會注入 Tailscale 身分識別標頭；Funnel 不會。
• Funnel 要求 Tailscale v1.38.3+、MagicDNS、已啟用 HTTPS，以及 funnel 節點屬性。
• Funnel 僅支援透過 TLS 使用連接埠 443、8443 與 10000。
• macOS 上的 Funnel 要求使用開放原始碼版本的 Tailscale 應用程式。

​

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

若要在一部機器上執行閘道，但操控另一部機器上的瀏覽器，請在瀏覽器所在的機器上執行節點主機，並讓兩者位於同一個 tailnet。閘道會將瀏覽器操作代理至該節點；不需要另外的控制伺服器或 Serve URL。

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

​

深入瞭解

• Tailscale Serve 概覽：https://tailscale.com/kb/1312/serve
• tailscale serve 命令：https://tailscale.com/kb/1242/tailscale-serve
• Tailscale Funnel 概覽：https://tailscale.com/kb/1223/tailscale-funnel
• tailscale funnel 命令：https://tailscale.com/kb/1311/tailscale-funnel

​

相關內容

• 遠端存取
• 探索
• 驗證