连接指南

如果你在连接过程中遇到不会操作的地方，可以先使用微信扫一扫加入微信群咨询。

使用微信扫一扫进群

如果你要远程连接 OpenClaw，我们优先推荐使用 Tailscale。原因很简单：它通常不需要把 Gateway 直接暴露到公网，整体更安全，也更省心。

如果你更在意“固定域名 + 长期公网可用”，请直接看这篇专题教程：Cloudflare Tunnel 远程连接。

本文按这个顺序展开：

• Tailscale 远程连接（推荐）
• 局域网连接
• 局域网 + 公网反代（进阶）

两种常用方式都以 gateway 配置为核心，尤其是初始连接 token（gateway.auth.token）。

一、Tailscale 远程连接

Tailscale 是一个基于 WireGuard 的组网工具，可以把手机、平板和电脑放进同一个私有网络。

它的优势是：

• 不要求手机和主机处于同一个 Wi-Fi。
• 通常不需要自己做端口映射。
• 更适合外出、跨网络和长期远程访问。
• 对大多数自建场景来说，安全性也更容易控制。

下载 Android 版 APK下载 iOS 版

• 注册入口：tailscale.com/start
• 官方下载页：tailscale.com/download

如果你在中国大陆使用 iPhone / iPad，通常需要外区 App Store 账号才可下载 Tailscale。

要注意：不只是手机或平板要安装 Tailscale，运行 OpenClaw 的那台电脑也要安装 Tailscale，并登录同一个网络。你可以把它理解成：手机负责“连过来”，电脑负责“被找到”。两边都装好以后，远程连接才会更顺畅。

1) 先让 OpenClaw 自动改好配置（推荐）

如果你不想自己打开配置文件，最简单的办法就是：把下面整段提示词直接复制给你的 OpenClaw，它会按本文推荐的方式，帮你把 Tailscale 远程连接和 Control UI 控制台相关配置改好，你不需要自己先改占位符。

请帮我把当前这台 OpenClaw 主机改成适合 Tailscale 远程连接的配置，并保留 Control UI 控制台。要求如下：
1) 修改当前生效的 OpenClaw 配置文件，保持现有文件路径与其他无关配置不变
2) 如果这台机器还没有安装 Tailscale，或还没有登录 Tailscale 网络，请先明确告诉我，不要继续乱填配置
3) gateway.mode 设置为 "local"
4) gateway.bind 设置为 "lan"
5) gateway.port 优先使用 18789；如果 18789 已被占用，就保留当前可用端口，并明确告诉我最终端口
6) gateway.auth.mode 设置为 "token"
7) 保留已有 gateway.auth.token；如果不存在，就生成高强度 token 并写入
8) gateway.controlUi.enabled 设置为 true
9) gateway.controlUi.allowInsecureAuth 设置为 true
10) 自动获取当前主机的局域网 IP 和 Tailscale IP，并把下面这些地址写入 gateway.controlUi.allowedOrigins：
   - http://127.0.0.1:<gateway.port>
   - http://<当前主机局域网IP>:<gateway.port>
   - http://<当前主机 Tailscale IP>:<gateway.port>
11) gateway.tailscale.mode 设置为 "off"
12) 不要帮我重启 Gateway，只提醒我手动重启
13) 最后明确输出这三项信息：
   - 实际使用的端口
   - 当前主机的 Tailscale IPv4
   - 获取 token 的命令：openclaw config get gateway.auth.token

等 OpenClaw 改完配置后，你还需要自己手动重启 Gateway：

openclaw gateway restart

如果这条命令提示你不是守护服务方式，也不用担心，后面的“其他说明”里还有前台运行和 Docker 的重启方式。

2) 远程连接步骤

1. 主机和客户端设备都安装 Tailscale，并登录同一个网络。
2. 在 OpenClaw 主机上执行 tailscale ip -4，确认当前主机的 Tailscale IPv4。
3. 在 OpenClaw 主机上执行 openclaw config get gateway.auth.token，拿到连接 token。
4. 打开 ClawPilot App，添加服务器，把地址填成 <tailscale-ip>:<port>。
5. 认证方式选择 token，再把刚才拿到的 token 粘贴进去。
6. 如果你还要在浏览器里打开 Control UI 控制台，直接访问 http://<tailscale-ip>:<port>。

这里的端口通常是 18789。如果 OpenClaw 刚才告诉你它用了别的端口，就以它最终输出的端口为准。

3) 其他（按需看）

• 如果你的局域网 IP 或 Tailscale IP 后面发生了变化，记得同步更新 gateway.controlUi.allowedOrigins。
• 如果你要在浏览器里直接打开 http://<你的主机局域网IP>:<port> 或 http://<你的主机 Tailscale IP>:<port>，保留 controlUi.allowInsecureAuth = true 通常更省事，可以减少 Control UI 因浏览器环境差异导致的连接问题。
• openclaw gateway restart 只适用于已安装的守护服务；如果你是前台运行方式，停止旧进程后重新运行 openclaw gateway run；如果你是 Docker 方式，使用 docker compose restart openclaw-gateway。
• 如果你后面要折腾更进阶的 Tailscale serve 或 funnel 模式，再单独按官方文档配置，不要直接照抄本文这套常规配置。

如果你更愿意手动改配置，可以参考下面这份最常用配置：

{
  gateway: {
    mode: "local",
    bind: "lan",
    port: 18789,
    auth: {
      mode: "token",
      token: "你的连接 token",
    },
    controlUi: {
      enabled: true,
      allowInsecureAuth: true,
      allowedOrigins: [
        "http://127.0.0.1:18789",
        "http://<你的主机局域网IP>:18789",
        "http://<你的主机 Tailscale IP>:18789",
      ],
    },
    tailscale: {
      mode: "off",
    },
  },
}

这套配置适合同时满足两类场景：

• 客户端通过 Tailscale IP 远程连接：<tailscale-ip>:<gateway.port>
• 浏览器打开 Control UI 控制台：http://<tailscale-ip>:<gateway.port>

二、局域网连接

适用场景：手机和 OpenClaw 主机在同一局域网（同一个 Wi-Fi 或同网段）。

1) 推荐配置（保留 Control UI 控制台）

{
  gateway: {
    mode: "local",
    bind: "lan",
    port: 18789,
    auth: {
      mode: "token",
      token: "你的连接 token",
    },
    controlUi: {
      enabled: true,
      allowInsecureAuth: true,
      allowedOrigins: [
        "http://127.0.0.1:18789",
        "http://<你的主机局域网IP>:18789",
      ],
    },
    tailscale: {
      mode: "off",
    },
  },
}

要点：

• bind = lan 表示同网段设备可访问。
• 保留 token 认证，不建议改成 none。
• 保留 Control UI 控制台时，需要配置 controlUi.allowedOrigins。
• 当 Control UI 控制台通过明文 HTTP 访问时，建议加上 controlUi.allowInsecureAuth = true 提升兼容性。

2) 获取 token

优先使用 CLI：

openclaw config get gateway.auth.token

也可以直接查看配置文件：

jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json

如果你用了自定义配置路径（例如设置过 OPENCLAW_CONFIG_PATH 或 OPENCLAW_STATE_DIR），优先使用 openclaw config get gateway.auth.token，它会按当前生效配置读取。

3) 修改后验证与重启

1. 执行 openclaw doctor，先确认配置无错误。
2. daemon 安装方式：openclaw gateway restart
3. 前台运行方式：停止旧进程后重新运行 openclaw gateway run
4. Docker 方式：docker compose restart openclaw-gateway

4) 客户端连接

1. 填入主机局域网 IP 和 gateway.port。
2. 认证方式选择 token。
3. 粘贴 gateway.auth.token。

三、局域网 + 公网反代配置（进阶）

这部分适合你要把 Control UI 控制台稳定暴露给公网访问，但又不想直接把 OpenClaw Gateway 裸露在公网端口上的场景。

1) 什么是反代（Reverse Proxy）

反向代理就是在 OpenClaw 前面再放一层入口服务（比如 Nginx / Caddy / Traefik）：

• 外部用户只访问代理入口（优先 443；家宽受限时用可放行端口）。
• 代理再把请求转发到内网或本机的 127.0.0.1:18789。
• TLS 证书、域名、限流、WAF 等能力优先放在代理层处理。

简单理解：OpenClaw 负责业务，代理负责“门口安检”。

2) 开始前必须满足的网络条件

• 你必须具备公网可达能力，否则公网反代无法从互联网访问到你的入口。
• 统一建议：无论家庭宽带还是云服务器，都把域名托管到 Cloudflare，并开启代理（橙云）+ SSL 访问。
• 家庭宽带场景至少需要：
  • 运营商分配公网 IP（非 CGNAT）。小技巧：可以打电话给电信/移动，说你要装监控，他们会给你分配公网 IP。
  • 路由器端口转发（把运营商允许的外网端口转发到你的反代监听端口，不要直转 18789）。
  • DDNS（当家庭公网 IP 变化时自动更新域名解析）。
• 云服务器场景通常更直接：
  • 自带固定公网 IP。
  • 配置比家宽简单，不需要 DDNS。

如果不满足公网条件，建议继续使用 Tailscale，而不是公网反代。

3) 为什么统一建议 Cloudflare（橙云）

• 隐藏源站 IP：外部请求先到 Cloudflare，可减少对源站的直接扫描与探测。
• HTTPS 落地更简单：证书、TLS 策略和强制 HTTPS 可以统一在边缘层管理。
• 安全能力更完整：可直接叠加 WAF、Bot 防护、Rate Limit、基础访问规则。
• 运维一致性更好：家庭宽带和云服务器可以共用同一套域名与安全策略。
• 问题定位更快：有统一的边缘访问日志和安全事件视角。

边界说明：

• 橙云不是“免配置安全”。源站仍要保留 Gateway 鉴权（token/password）和最小暴露策略。
• Cloudflare 反向代理当前支持的 HTTPS 端口包括：443、2053、2083、2087、2096、8443。
• Cloudflare 反向代理当前支持的 HTTP 端口包括：80、8080、8880、2052、2082、2086、2095。
• 如果你的网络环境不放行 443/80，要从上述可代理端口中选择，并同步反代监听端口与外网放行策略。

4) 推荐拓扑（安全优先）

建议拓扑：

Internet -> Cloudflare -> 反代（Nginx/Caddy） -> OpenClaw Gateway(127.0.0.1:18789)

关键点：

• Gateway 建议保持 bind = loopback，不要直接监听公网网卡。
• 公网只开放代理端口（例如 443 或你实际可放行的高位端口），不要直接开放 18789。
• Control UI 控制台使用 HTTPS 域名访问，优先避免明文 HTTP。

5) 参考配置（公网反代 + HTTPS）

{
  gateway: {
    mode: "local",
    bind: "loopback",
    port: 18789,
    auth: {
      mode: "token",
      token: "你的高强度 token",
      // 需要身份代理时可改为 trusted-proxy，并配置 auth.trustedProxy
      // mode: "trusted-proxy",
      // trustedProxy: { userHeader: "x-forwarded-user" },
    },
    trustedProxies: ["127.0.0.1", "::1"],
    allowRealIpFallback: false,
    controlUi: {
      enabled: true,
      allowInsecureAuth: false,
      allowedOrigins: ["https://control.example.com"],
    },
    tailscale: {
      mode: "off",
    },
  },
}

6) gateway.trustedProxies 到底做什么

trustedProxies 是“你信任的代理 IP 列表”。OpenClaw 会用它来判断哪些转发头可以相信。

• 在 OpenClaw 语义里，trustedProxies 应该只填写你自己控制的反代出口 IP。
• 配置后，Gateway 会优先使用 X-Forwarded-For 计算真实客户端 IP。
• 默认不会信任 X-Real-IP（allowRealIpFallback 默认 false，属于 fail-closed 设计）。
• 如果代理和 Gateway 在同机（最常见），通常应包含 127.0.0.1 和 ::1。

如果你使用 auth.mode = "trusted-proxy"，trustedProxies 还是强制项；缺失会导致 Gateway 启动失败。

代理层额外安全建议：

• 覆盖（overwrite）X-Forwarded-For，不要使用“追加链路”的做法。
• 反代层强制 HTTPS，HTTP 只做 301 跳转。
• 打开 Cloudflare 的 WAF / Bot 防护 / Rate Limit。
• 定期轮换 gateway.auth.token 并限制运维端登录来源。

示例（推荐）：

proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;

不推荐（会追加未受信任链路）：

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

7) 两类部署路径（均建议 Cloudflare 橙云，简版步骤）

家庭宽带（有公网 IP）：

1. 确认 WAN 口是公网 IP（不是 100.64.0.0/10 这类 CGNAT 地址）。
2. 在路由器把“可放行的外网端口”转发到反代主机监听端口（不要直转 18789）。
3. 在 Cloudflare 托管域名，并用 DDNS/更新脚本把家庭公网 IP 动态同步到 Cloudflare DNS 记录。
4. 开启 Cloudflare 代理（橙云）并启用 SSL（推荐 Full/Strict）。
5. 域名启用 HTTPS 后，仅通过 https://你的域名（或 https://你的域名:端口）访问 Control UI 控制台。

云服务器（固定公网 IP）：

1. 在 Cloudflare 托管域名，A 记录指向云服务器公网 IP。
2. 开启 Cloudflare 代理（橙云）并启用 SSL（推荐 Full/Strict）。
3. 服务器只开放 80/443（或仅 443），不要对公网开放 18789。
4. 反代到 127.0.0.1:18789，并把 controlUi.allowedOrigins 固定为你的 HTTPS 域名。

四、最小排查顺序

1. openclaw doctor
2. openclaw gateway status --deep
3. 确认客户端填写的端口与 gateway.port 一致
4. 确认 token 与 gateway.auth.token 完全一致
5. 远程场景再执行 tailscale status
6. 如果启动失败，优先检查是否遗漏 gateway.controlUi.allowedOrigins

五、关键字段速览（两种连接方式通用）

{
  gateway: {
    mode: "local",
    bind: "lan",
    port: 18789,
    auth: {
      mode: "token",
      token: "请替换成你自己的长 token",
    },
    controlUi: {
      enabled: true,
      allowInsecureAuth: true,
    },
    tailscale: {
      mode: "off",
    },
  },
}

字段说明：

• gateway.mode 日常自建场景建议保持 local。
• gateway.bind 本文前面两种常用接入方式都统一用 lan，这样一份配置通常就够用。
• gateway.port 默认端口是 18789。
• gateway.auth.mode 建议用 token。
• gateway.auth.token 客户端首次连接需要的鉴权 token。
• gateway.controlUi.allowInsecureAuth 如果你经常直接用浏览器打开 HTTP 地址，通常建议保留为 true，兼容性更好。
• gateway.tailscale.mode 本文默认保持 off；更进阶的 Tailscale 用法再单独参考官方文档。

参考资料

• OpenClaw Gateway Configuration
• OpenClaw Configuration Reference
• OpenClaw Tailscale
• OpenClaw Security
• Tailscale Start
• Tailscale Download

源码核对时间：2026-02-26