openclaw 文档

简体中文

English

简体中文

English

Appearance

Tailscale（Gateway dashboard） ​

OpenClaw 可以自动配置 Tailscale Serve（tailnet 内）或 Funnel（公网）来暴露 Gateway dashboard 与 WebSocket 端口。这样 Gateway 仍可保持绑定 loopback，同时由 Tailscale 提供 HTTPS、路由，以及（Serve 模式下）身份 headers。

模式 ​

  • 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 或 config 共享密钥）

当 tailscale.mode = "serve" 且 gateway.auth.allowTailscale 为 true 时，来自 Serve proxy 的合法请求可以通过 Tailscale 身份 headers（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 headers 时，才会把它当作 Serve 请求。

若要强制使用显式凭据，可设置 gateway.auth.allowTailscale: false 或强制 gateway.auth.mode: "password"。

配置示例 ​

仅 tailnet（Serve） ​

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

打开：https://<magicdns>/（或你配置的 gateway.controlUi.basePath）

仅 tailnet（直接绑定 Tailnet IP） ​

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

json5
{
  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 + 共享密码） ​

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

相比把密码写入磁盘，更推荐使用 OPENCLAW_GATEWAY_PASSWORD。

CLI 示例 ​

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

备注 ​

  • Tailscale Serve/Funnel 需要安装并登录 tailscale CLI。
  • tailscale.mode: "funnel" 在 auth mode 不是 password 时会拒绝启动，以避免公网暴露风险。
  • 如果你希望 OpenClaw 在退出时撤销 tailscale serve 或 tailscale funnel 的配置，可设置 gateway.tailscale.resetOnExit。
  • gateway.bind: "tailnet" 是直接 Tailnet bind（无 HTTPS、无 Serve/Funnel）。
  • gateway.bind: "auto" 会优先 loopback；若想强制 Tailnet-only 请用 tailnet。
  • Serve/Funnel 只暴露 Gateway control UI + WS。nodes 也连接同一个 Gateway WS，因此 Serve 也可以用于 node 访问。

Browser control（远程 Gateway + 本地浏览器） ​

如果你在一台机器上运行 Gateway，但希望在另一台机器上驱动浏览器，请在浏览器所在机器运行一个 node host，并让两台机器在同一个 tailnet 内。 Gateway 会把 browser actions 代理到 node；不需要额外的控制 server 或 Serve URL。

避免用 Funnel 做 browser control；应把 node pairing 当作 operator access 一样严格对待。

Tailscale 前置条件与限制 ​

  • Serve 需要为 tailnet 启用 HTTPS；若缺失 CLI 会提示。
  • Serve 会注入 Tailscale 身份 headers；Funnel 不会。
  • Funnel 需要 Tailscale v1.38.3+、MagicDNS、启用 HTTPS，以及 funnel node attribute。
  • Funnel 仅支持通过 TLS 使用端口 443、8443、10000。
  • macOS 上使用 Funnel 需要开源版 Tailscale app。

了解更多 ​

  • 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