無題

OpenClaw Control UI 局域网访问配置文档

概述

本文档详细记录了如何配置 OpenClaw Control UI 以支持局域网访问的完整过程。

系统信息

  • 服务器 IP：192.168.66.124
  • OpenClaw 版本：2026.3.2
  • 操作系统：Linux (Ubuntu 24.04)
  • Nginx 版本：1.24.0

配置文件修改

1. OpenClaw 主配置文件

文件路径：/root/.openclaw/openclaw.json

Gateway 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "lan",
  "controlUi": {
    "allowedOrigins": [
      "https://192.168.66.124",
      "http://192.168.66.124:18789",
      "http://localhost:18789",
      "http://127.0.0.1:18789"
    ]
  },
  "auth": {
    "mode": "token",
    "token": "7d7bf87d5521d031874b65e551c2d7ae1ce67dfd2ca969ff"
  },
  "tailscale": {
    "mode": "off",
    "resetOnExit": false
  },
  "nodes": {
    "denyCommands": [
      "camera.snap",
      "camera.clip",
      "screen.record",
      "contacts.add",
      "calendar.add",
      "reminders.add",
      "sms.send"
    ]
  }
}

关键修改说明

  • **gateway.bind**：从 loopback 改为 lan，允许局域网访问
  • **gateway.controlUi.allowedOrigins**：新增 HTTPS 地址支持
  • **gateway.auth.token**：网关访问令牌

2. Nginx 反向代理配置

文件路径：/etc/nginx/conf.d/openclaw.conf

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
server {
    listen 443 ssl;
    server_name 192.168.66.124;

    ssl_certificate /root/.openclaw/ssl/cert.pem;
    ssl_certificate_key /root/.openclaw/ssl/key.pem;

    ssl_session_timeout 5m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 86400;
    }
}

server {
    listen 80;
    server_name 192.168.66.124;
    return 301 https://$server_name$request_uri;
}

3. SSL 证书

路径：/root/.openclaw/ssl/

  • **cert.pem**：公钥证书（自签名，有效期 10 年）
  • **key.pem**：私钥（权限 600）

证书信息：

1
2
3
4
Subject: C=CN; ST=YourState; L=YourCity; O=YourOrganization; OU=YourUnit; CN=192.168.66.124
有效期：2026-03-05 至 2036-03-02
加密算法：RSA 2048
签名算法：sha256WithRSAEncryption

访问地址

HTTPS 访问（推荐）

地址：https://192.168.66.124/#token=7d7bf87d5521d031874b65e551c2d7ae1ce67dfd2ca969ff

浏览器警告：自签名证书会显示安全警告，点击”高级” -> “继续前往”。

HTTP 访问（备用）

地址：http://192.168.66.124:18789/#token=7d7bf87d5521d031874b65e551c2d7ae1ce67dfd2ca969ff

设备配对详细操作流程

设备配对基础概念

OpenClaw 有两种主要的配对机制：

  • 设备配对 (Device Pairing): 用于控制 UI、CLI 等设备的认证
  • 节点配对 (Node Pairing): 用于 iOS/Android 应用等远程节点的认证（使用 nodes 命令）

查看和管理配对状态

列出所有待处理和已配对的设备

1
2
3
4
5
6
7
8
# 列出所有设备配对信息（包括待处理和已配对）
openclaw devices list

# 以 JSON 格式输出
openclaw devices list --json

# 高级选项
openclaw devices list --url <gateway-url> --token <token> --timeout <ms>

输出示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Pending (1)
┌──────────────────────────────────────┬──────────────────────────────────┬──────────┬────────────┬──────────┬────────┐
│ Request                              │ Device                           │ Role     │ IP         │ Age      │ Flags  │
├──────────────────────────────────────┼──────────────────────────────────┼──────────┼────────────┼──────────┼────────┤
│ 22c83b83-0273-4332-b953-7d662d28b5ff │ 6a25ced5d82587d5f72a0c03bc61a633 │ operator │            │ just now │        │
│                                      │ d0f49e39d0d135d43546ebd6869b8a9f │          │            │          │        │
└──────────────────────────────────────┴──────────────────────────────────┴──────────┴────────────┴──────────┴────────┘
Paired (2)
┌─────────────────────────────┬────────────┬────────────────────────────────────────────────┬────────────┬────────────┐
│ Device                      │ Roles      │ Scopes                                         │ Tokens     │ IP         │
├─────────────────────────────┼────────────┼────────────────────────────────────────────────┼────────────┼────────────┤
│ 5a70603d8c036c67837a75a4d8b │ operator   │ operator.admin, operator.approvals, operator.  │ operator   │            │
│ 57309c5754e5ba2676f2fac67f9 │            │ pairing                                        │            │            │
│ 114d71b094                  │            │                                                │            │            │
│ dbd755d39f103b4485d6078fe70 │ operator   │ operator.read, operator.admin, operator.       │ operator   │            │
│ 945b54194515e2895941228fa17 │            │ write, operator.approvals, operator.pairing    │            │            │
│ a4f1445fc8                  │            │                                                │            │            │
└─────────────────────────────┴────────────┴────────────────────────────────────────────────┴────────────┴────────────┘

设备配对流程

批准待处理的配对请求

1
2
3
4
5
6
7
8
# 批准特定请求（使用 requestId）
openclaw devices approve <requestId>

# 批准最新的待处理请求
openclaw devices approve --latest

# 以 JSON 格式输出
openclaw devices approve <requestId> --json

示例：

1
openclaw devices approve 22c83b83-0273-4332-b953-7d662d28b5ff

拒绝待处理的配对请求

1
2
3
4
5
# 拒绝特定请求
openclaw devices reject <requestId>

# 拒绝最新的待处理请求
openclaw devices reject --latest

令牌管理

轮换设备令牌

1
2
3
4
5
# 轮换设备令牌
openclaw devices rotate --device <deviceId> --role <role> [--scope <scope...>]

# 示例：轮换 operator 角色的令牌并添加新的作用域
openclaw devices rotate --device 5a70603d8c036c67837a75a4d8b57309c5754e5ba2676f2fac67f9114d71b094 --role operator --scope operator.read --scope operator.write

撤销设备令牌

1
2
3
4
5
# 撤销设备令牌
openclaw devices revoke --device <deviceId> --role <role>

# 示例：撤销 operator 角色的令牌
openclaw devices revoke --device 5a70603d8c036c67837a75a4d8b57309c5754e5ba2676f2fac67f9114d71b094 --role operator

配对相关配置

控制 UI 不安全认证（容器化部署）

对于 Docker/Kubernetes 等容器化部署，需要启用不安全认证以避免配对要求：

1
2
3
4
5
# 启用控制 UI 不安全认证
openclaw config set gateway.controlUi.allowInsecureAuth true

# 重启网关
openclaw gateway restart

配置文件位置

设备配对信息存储在以下位置：

  • 待处理请求: ~/.openclaw/devices/pending.json
  • 已配对设备: ~/.openclaw/devices/paired.json
  • 节点配对: ~/.openclaw/nodes/ 目录

配对超时

  • 设备配对超时: 待处理请求 5 分钟后自动过期
  • 通道配对超时: WhatsApp 等通道配对代码 1 小时后过期

已配对设备列表

设备 ID 角色 权限范围 状态
5a70603d8c036c67837a75a4d8b57309c5754e5ba2676f2fac67f9114d71b094 operator operator.admin, operator.approvals, operator.pairing 已批准
dbd755d39f103b4485d6078fe70945b54194515e2895941228fa17a4f1445fc8 operator operator.read, operator.admin, operator.write, operator.approvals, operator.pairing 已配对

启动命令

启动 OpenClaw 网关

1
openclaw gateway --force &

重启 Nginx

1
systemctl restart nginx

检查运行状态

1
2
3
4
5
6
7
8
9
10
11
# 检查 OpenClaw 进程
ps aux | grep -E "(node|openclaw)" | grep -v grep

# 检查端口监听
ss -tuln | grep -E "(443|18789)"

# 检查网关健康状态
openclaw health

# 检查设备状态
openclaw devices list

常用命令

配置管理

1
2
3
4
5
6
7
8
# 查看配置
openclaw config get

# 修改配置
openclaw config set <key> <value>

# 验证配置
openclaw config validate

配对管理

设备配对管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 列出所有待处理和已配对的设备
openclaw devices list

# 列出所有待处理和已配对的设备（JSON格式）
openclaw devices list --json

# 批准最新配对请求
openclaw devices approve --latest

# 批准特定请求（使用 requestId）
openclaw devices approve <requestId>

# 拒绝最新配对请求
openclaw devices reject --latest

# 拒绝特定请求（使用 requestId）
openclaw devices reject <requestId>

# 轮换设备令牌
openclaw devices rotate --device <deviceId> --role <role> [--scope <scope...>]

# 撤销设备令牌
openclaw devices revoke --device <deviceId> --role <role>

# 清除所有配对信息
openclaw devices clear

节点配对管理（iOS/Android 应用）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 列出待处理的节点配对
openclaw nodes pending

# 列出所有已配对的节点
openclaw nodes status

# 批准节点配对
openclaw nodes approve <requestId>

# 拒绝节点配对
openclaw nodes reject <requestId>

# 重命名节点
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

网关管理

1
2
3
4
5
6
7
8
# 停止网关
pkill -f openclaw-gateway

# 重启网关
openclaw gateway --force &

# 检查网关状态
openclaw gateway probe

故障排除

常见问题

1. control ui requires device identity

原因：页面需要 HTTPS 安全上下文
解决：使用 HTTPS 地址访问

2. unauthorized: gateway token missing

原因：Control UI 需要网关访问令牌
解决：使用包含 #token= 参数的 URL 访问

3. pairing required

原因：设备未完成配对
解决：使用 openclaw devices approve --latest 批准配对请求

4. 浏览器安全警告

原因：使用自签名证书
解决：点击”高级” -> “继续前往”

配对相关故障排除

1. 容器化部署中 “pairing required” 错误

问题: Web UI 显示 “disconnected (1008): pairing required”

解决方案:

1
2
3
4
5
6
7
# 启用不安全认证（推荐）
openclaw config set gateway.controlUi.allowInsecureAuth true
openclaw gateway restart

# 或使用 Docker Compose
docker compose run --rm openclaw-cn-cli config set gateway.controlUi.allowInsecureAuth true
docker compose restart openclaw-cn-gateway

2. 无法连接到网关

问题: 无法列出设备或批准配对请求

解决方案:

1
2
3
4
5
6
7
8
9
10
11
# 检查网关健康状态
openclaw health

# 检查网关运行状态
openclaw gateway probe

# 查看网关日志
openclaw logs --follow

# 运行系统诊断
openclaw doctor

3. 控制 UI 访问问题

问题: Control UI 需要设备身份验证

解决方案:

1
2
3
4
5
# 确保使用正确的令牌访问
openclaw dashboard --no-open

# 检查网关配置
openclaw config get gateway.auth.token

4. 配对请求未显示

问题: 待处理的配对请求未在列表中显示

解决方案:

1
2
3
4
5
6
7
8
# 检查待处理请求文件
cat ~/.openclaw/devices/pending.json

# 检查网关日志以获取错误
openclaw logs --follow | grep -i pairing

# 清除过期的待处理请求
openclaw devices list --json | jq '.pending | map(select(.ts < now - 300000))'

安全建议

1. 证书安全

  • 自签名证书仅用于内部测试
  • 生产环境建议使用 CA 颁发的证书

2. 访问控制

  • 网关 token 应保持机密
  • 定期轮换 token：openclaw config set gateway.auth.token <newToken>

3. 网络安全

  • 网关默认仅允许白名单设备访问
  • 配置 gateway.auth.rateLimit 防止暴力破解：
1
2
3
4
5
6
7
8
"auth": {
  "mode": "token",
  "rateLimit": {
    "maxAttempts": 10,
    "windowMs": 60000,
    "lockoutMs": 300000
  }
}

版本信息

  • 文档创建时间：2026-03-05
  • 最后修改时间：2026-03-05（添加配对相关操作说明）