Tailscale（网关面板）

OpenClaw 可以自动配置 Tailscale Serve（tailnet 内部）或 Funnel（公网）来暴露网关面板和 WebSocket 端口。网关本身仍绑定在回环地址，由 Tailscale 提供 HTTPS、路由和（Serve 模式下的）身份 header。

模式

  • serve：通过 tailscale serve 提供 tailnet 内访问。网关保持监听 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 身份 header（tailscale-user-login），无需提供 token/密码。OpenClaw 通过本地 Tailscale 守护进程（tailscale whois）解析 x-forwarded-for 地址来验证身份，并与 header 进行匹配。OpenClaw 只有在请求来自回环地址并携带 Tailscale 注入的 x-forwarded-for、x-forwarded-proto 和 x-forwarded-host header 时才将其视为 Serve 请求。 HTTP API 端点（例如 /v1/*、/tools/invoke 和 /api/channels/*）仍需要 token/密码认证。 这种免 token 流程假设网关主机是受信的。如果同一主机上可能运行不受信的代码，请禁用 gateway.auth.allowTailscale 并改用 token/密码认证。 要强制使用显式凭证，设置 gateway.auth.allowTailscale: false 或指定 gateway.auth.mode: "password"。

配置示例

tailnet 内访问（Serve）

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

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

tailnet 内访问（直接绑定 Tailnet IP）

不走 Serve/Funnel，让网关直接监听 Tailnet IP。

{
  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 时拒绝启动，防止公网暴露。
  • 设置 gateway.tailscale.resetOnExit 可让 OpenClaw 在关闭时撤销 tailscale serve 或 tailscale funnel 配置。
  • gateway.bind: "tailnet" 是直接的 Tailnet 绑定（没有 HTTPS，没有 Serve/Funnel）。
  • gateway.bind: "auto" 优先选择回环；需要 Tailnet 时请使用 tailnet。
  • Serve/Funnel 只暴露网关控制 UI + WS。节点通过同一个网关 WS 端点连接，所以 Serve 也能用于节点访问。

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

如果网关在一台机器上运行，但你想在另一台机器上控制浏览器，可以在浏览器所在机器上运行节点主机，并让两者都在同一个 tailnet 内。网关会将浏览器操作代理到节点，无需额外的控制服务器或 Serve URL。

浏览器控制不要使用 Funnel；节点配对应等同于操作员访问。

Tailscale 前提条件与限制

  • Serve 要求你的 tailnet 启用了 HTTPS；CLI 会在缺失时提示。
  • Serve 注入 Tailscale 身份 header；Funnel 不注入。
  • Funnel 需要 Tailscale v1.38.3+、MagicDNS、HTTPS 启用，以及 funnel 节点属性。
  • Funnel 仅支持通过 TLS 的 443、8443 和 10000 端口。
  • macOS 上的 Funnel 需要开源版本的 Tailscale 应用。

了解更多

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