openClaw_agent_dm/docs/CONTROL_UI_ACCESS_AND_SECURITY.md

# 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`

常用命令：

```bash
# 查看当前 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 已审批过的设备

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

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

1. 浏览器打开对应 URL，输入 token。
2. 若提示需设备身份或配对，**不要关页面**，到 **运行 OpenClaw 的服务器** 上执行：
   ```bash
   # 加载对应 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.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）时：

1. **创建 profile 与配置**
   - 使用 `openclaw --profile <新id> setup` 或复制现有 profile 目录并改 `openclaw.json`（端口、workspace、agent id 等）。
   - 为该 Gateway 分配**独立端口**（如 18791），避免与 main(18789)、桐哥(18790) 冲突。

2. **配置 Gateway 安全与 Origin**
   - 在对应 `openclaw.json` 中设置 `gateway.auth`（token + rateLimit）、`dangerouslyDisableDeviceAuth: false`。
   - 在 `gateway.controlUi.allowedOrigins` 中加入该 Gateway 的 **HTTPS 访问 Origin**（含端口，若使用非 443）。

3. **Tailscale Serve 暴露新端口**
   - 例如新 Gateway 端口 18791，使用 8444：
     ```bash
     sudo tailscale serve --bg --https 8444 18791
     ```
   - 将 `https://<本机 Tailscale 主机名>.ts.net:8444` 加入该 Gateway 的 `allowedOrigins`。

4. **Token 与 env**
   - 生成或指定该 Gateway 的 token，写入对应 env 文件（如 `workspace/systemd/<新agent>-gateway.env`），并在 `openclaw.json` 中用 SecretRef 引用（如 `OPENCLAW_GATEWAY_TOKEN`）。

5. **注册到 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`。

6. **验证与首次 Approve**
   - 用新 URL + token 在浏览器访问，若出现设备待审批，在服务器上对**该 profile** 执行 `openclaw devices list` / `openclaw devices approve <requestId>`（注意 CLI 需能连到该 Gateway，若 bind 非 loopback 需确保 `OPENCLAW_GATEWAY_TOKEN` 等 env 正确）。

---

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

1. **在新机器上**
   - 安装 Tailscale，加入同一 tailnet；开启 HTTPS（若新 tailnet 则在新 Admin 开启）。
   - 安装 OpenClaw，恢复各 profile 的 `openclaw.json`、env 文件、workspace（及 agents.yaml、systemd 单元）。

2. **Tailscale Serve**
   - 新机器主机名会变，Serve 需在新机器上重新配置：
     - 443 → 18789（main）
     - 8443 → 18790（桐哥）
     - 其他端口按需。
   - 执行 `tailscale serve status` 确认。

3. **allowedOrigins**
   - 将新机器的 Tailscale 主机名（及带端口的 HTTPS Origin）更新到各 Gateway 的 `gateway.controlUi.allowedOrigins`。

4. **Token**
   - 若沿用旧 token，无需改；若重新生成，需更新对应 env 并重启对应 Gateway。

5. **设备审批**
   - 迁移后所有浏览器/设备视为新设备，需再次走「首次访问 → 服务器上 devices list / approve」流程。

6. **文档与书签**
   - 更新本文档中的「当前环境访问地址」表及任何内链/书签为新的 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](./SYSTEM_ARCHITECTURE.md) — 整体架构与双 Gateway 说明  
- [MULTI_AGENT_MANAGEMENT.md](./MULTI_AGENT_MANAGEMENT.md) — 多 Agent 管理  
- [AGENT_DEPLOYMENT_BEST_PRACTICES.md](./AGENT_DEPLOYMENT_BEST_PRACTICES.md) — 部署最佳实践  

---

*最后更新：2026-03-12*