9.1 KiB

Raw Blame History

Control UI 访问与安全标准流程

文档版本: 2026-03-12
适用架构: 双 Gateway 独立部署（main + 各 Agent 独立 profile）
安全模型: Tailscale 内网 + HTTPS + Token + 首次设备审批

1. 安全模型说明

1.1 三重保障

层级	机制	作用
网络	Tailscale 内网	仅加入同一 tailnet 的设备可访问；WireGuard 加密，不暴露公网
认证	Gateway Token	连接 Control UI 必须携带正确 token，否则拒绝
设备	首次 Approve	新设备首次用 token 访问时进入「待审批」；管理员在服务器上 `openclaw devices approve` 后该设备才可长期使用

1.2 为何能保证安全

Tailscale 设备被攻破：攻击者若只拿到 token、从新设备访问，会出现在 pending 列表，管理员不 approve 则无法使用。
Token 泄露：未加入 tailnet 的机器无法访问；加入 tailnet 的新设备仍需 approve。
HTTPS：浏览器处于 secure context，可完成设备身份握手与配对，避免 HTTP 下「无法完成 device identity」的提示。

1.3 配置要点（必须满足）

gateway.controlUi.dangerouslyDisableDeviceAuth 为 false（启用设备认证）。
gateway.auth.mode 为 token，且 token 通过 SecretRef 或环境变量注入，不写死在配置里。
Control UI 仅通过 Tailscale Serve 的 HTTPS 或 SSH 隧道 + localhost 访问，不直接暴露 HTTP 到公网。

2. 前置条件（一次性）

2.1 Tailscale

本机已安装并加入 tailnet：tailscale status 显示为 active。
在 Tailscale Admin 已开启 HTTPS Certificates 与 MagicDNS（Settings → HTTPS / DNS）。
本机有稳定的 Tailnet DNS 名称（如 mem0-general-center.tail1c537f.ts.net）。

2.2 Tailscale Serve（按需添加端口）

Main Gateway（18789）：已在 443 暴露，例如
https://<本机 Tailscale 主机名>.ts.net → http://127.0.0.1:18789
其他 Agent Gateway（如桐哥 18790）：在 8443 暴露，例如
https://<本机 Tailscale 主机名>.ts.net:8443 → http://127.0.0.1:18790

常用命令：

# 查看当前 Serve 配置
sudo tailscale serve status

# Main 已占 443 时，为第二个 Gateway 增加 8443（示例：桐哥 18790）
sudo tailscale serve --bg --https 8443 18790

# 若 8443 未持久化，重启后需再次执行或做成 systemd 服务

2.3 Gateway 配置检查清单

每个 Gateway 的 openclaw.json 需包含：

gateway.controlUi.allowedOrigins
加入实际访问 Control UI 的 Origin，例如：
- Main（443）：https://mem0-general-center.tail1c537f.ts.net、https://mem0-general-center.tail1c537f.ts.net:443
- 桐哥（8443）：https://mem0-general-center.tail1c537f.ts.net:8443
- 若使用 SSH 隧道 + localhost：http://localhost:18789、http://127.0.0.1:18789 等已包含即可。
gateway.controlUi.dangerouslyDisableDeviceAuth: false
gateway.auth.mode: "token"
gateway.auth.token: 使用 SecretRef（如 { "source": "env", "provider": "default", "id": "OPENCLAW_GATEWAY_TOKEN" }），token 值放在对应 env 文件（如 gateway.env、tongge-gateway.env）。
gateway.auth.rateLimit：建议配置（如 maxAttempts: 10, windowMs: 60000, lockoutMs: 300000）。

3. 日常访问流程

3.1 已审批过的设备

在 同一 tailnet 内的设备上打开浏览器。
访问对应 URL（见下表），输入该 Gateway 的 token。
直接进入 Control UI，无需再次 approve。

3.2 首次访问（新设备 / 新浏览器）

浏览器打开对应 URL，输入 token。

若提示需设备身份或配对，不要关页面，到 运行 OpenClaw 的服务器 上执行：

# 加载对应 Gateway 的环境（main 用默认 profile，桐哥用 tongge profile）
export $(grep -v '^#' /root/.openclaw/workspace/systemd/gateway.env | xargs)   # main
# 或
export $(grep -v '^#' /root/.openclaw/workspace/systemd/tongge-gateway.env | xargs)  # 桐哥

openclaw devices list
# 在 Pending 下找到新设备，记下 requestId

openclaw devices approve <requestId>

批准后回到浏览器刷新或重连，即可正常使用。

3.3 当前环境访问地址与 Token 位置

Agent	Control UI 地址	Token 所在文件
Main（陈医生）	https://mem0-general-center.tail1c537f.ts.net	`workspace/systemd/gateway.env` → `OPENCLAW_GATEWAY_TOKEN`
桐哥	https://mem0-general-center.tail1c537f.ts.net:8443	`workspace/systemd/tongge-gateway.env` → `OPENCLAW_GATEWAY_TOKEN`

（若主机名或端口变更，需同步修改 Serve 与 allowedOrigins。）

4. 新增 Agent（新 Gateway）标准流程

在保留「Tailscale + HTTPS + Token + 首次 Approve」的前提下，新增一个独立 Gateway（如新 profile）时：

创建 profile 与配置
- 使用 openclaw --profile <新id> setup 或复制现有 profile 目录并改 openclaw.json（端口、workspace、agent id 等）。
- 为该 Gateway 分配独立端口（如 18791），避免与 main(18789)、桐哥(18790) 冲突。
配置 Gateway 安全与 Origin
- 在对应 openclaw.json 中设置 gateway.auth（token + rateLimit）、dangerouslyDisableDeviceAuth: false。
- 在 gateway.controlUi.allowedOrigins 中加入该 Gateway 的 HTTPS 访问 Origin（含端口，若使用非 443）。
Tailscale Serve 暴露新端口
- 例如新 Gateway 端口 18791，使用 8444：
```
sudo tailscale serve --bg --https 8444 18791
```
- 将 https://<本机 Tailscale 主机名>.ts.net:8444 加入该 Gateway 的 allowedOrigins。
Token 与 env
- 生成或指定该 Gateway 的 token，写入对应 env 文件（如 workspace/systemd/<新agent>-gateway.env），并在 openclaw.json 中用 SecretRef 引用（如 OPENCLAW_GATEWAY_TOKEN）。
注册到 agents.yaml 与 deploy
- 在 workspace/agents.yaml 中增加新 agent（type、unit、env_file、workspace 等）。
- 若用 systemd，将 workspace/systemd/openclaw-gateway-<新agent>.service 安装到 ~/.config/systemd/user/，并执行 ./deploy.sh install 或 fix-service 后 ./deploy.sh restart。
验证与首次 Approve
- 用新 URL + token 在浏览器访问，若出现设备待审批，在服务器上对该 profile 执行 openclaw devices list / openclaw devices approve <requestId>（注意 CLI 需能连到该 Gateway，若 bind 非 loopback 需确保 OPENCLAW_GATEWAY_TOKEN 等 env 正确）。

5. 迁移（换机器 / 换域名）标准流程

在新机器上
- 安装 Tailscale，加入同一 tailnet；开启 HTTPS（若新 tailnet 则在新 Admin 开启）。
- 安装 OpenClaw，恢复各 profile 的 openclaw.json、env 文件、workspace（及 agents.yaml、systemd 单元）。
Tailscale Serve
- 新机器主机名会变，Serve 需在新机器上重新配置：
  - 443 → 18789（main）
  - 8443 → 18790（桐哥）
  - 其他端口按需。
- 执行 tailscale serve status 确认。
allowedOrigins
- 将新机器的 Tailscale 主机名（及带端口的 HTTPS Origin）更新到各 Gateway 的 gateway.controlUi.allowedOrigins。
Token
- 若沿用旧 token，无需改；若重新生成，需更新对应 env 并重启对应 Gateway。
设备审批
- 迁移后所有浏览器/设备视为新设备，需再次走「首次访问 → 服务器上 devices list / approve」流程。
文档与书签
- 更新本文档中的「当前环境访问地址」表及任何内链/书签为新的 Tailscale URL。

6. 故障排查速查

现象	可能原因	处理
origin not allowed	当前访问的 Origin 未在 `allowedOrigins` 中	在对应 Gateway 的 `openclaw.json` 中加入该 Origin（含协议、主机、端口）后重启
control ui requires device identity	用 HTTP 或非 localhost 访问，浏览器非 secure context	改用 Tailscale HTTPS 或 SSH 隧道 + localhost；或临时设 `dangerouslyDisableDeviceAuth: true`（不推荐长期）
新设备一直 pending，approve 后仍不行	未对正确 profile/Gateway 执行 approve，或 CLI 连错 Gateway	确认 `openclaw devices list` 所在 profile 与访问的 URL 对应同一 Gateway；env 中 token 正确
Serve 重启后 8443 不可用	Serve 未持久化	再次执行 `sudo tailscale serve --bg --https 8443 18790`，或配置 systemd 开机执行
CLI `devices list` 报 1006 / 连不上	Gateway 只 bind tailnet，未监听 127.0.0.1	将该 Gateway 的 `gateway.bind` 改为 `lan`，或 CLI 通过 `--url ws://<Tailscale IP>:<port>` 并带 token 连接

7. 相关文档

SYSTEM_ARCHITECTURE.md — 整体架构与双 Gateway 说明
MULTI_AGENT_MANAGEMENT.md — 多 Agent 管理
AGENT_DEPLOYMENT_BEST_PRACTICES.md — 部署最佳实践

最后更新：2026-03-12

9.1 KiB Raw Blame History