OpenClaw 远程 Web 访问调试示意图，显示服务器、HTTPS 锁、配对密钥和检查标记

OpenClaw 远程 Web 访问配置与调试全记录

🎧 收听播客版本

⏱️ 时长约3分4秒 | 📥 也可以在通勤、运动时收听

前言

在配置 OpenClaw 的远程 HTTPS Web 访问时，遇到了多个问题，经历了一系列的调试过程。本文记录了完整的问题排查和最终解决方案，希望能帮助遇到类似问题的开发者。

⚠️ 安全提示：本文中所有敏感信息（token、密钥、设备 ID 等）已进行脱敏处理，实际操作时请妥善保管这些信息。

初始问题

1. 安全警告

初始状态时，系统显示多个安全警告：

  • ✗ Open groupPolicy with elevated tools enabled
  • ✗ Small models require sandboxing and web tools disabled
  • ✗ Extensions exist but plugins.allow is not set
  • ✗ Feishu security warning
  • ✗ No auth rate limiting configured

2. SSL 协议错误

尝试通过 HTTPS 访问时，浏览器提示：

ERR_SSL_PROTOCOL_ERROR

3. Pairing Required 错误

配置 HTTPS 后，访问时提示：

disconnected (1008): pairing required

解决过程

第一阶段：安全配置修复

1. 修改 Feishu 组策略

将 groupPolicy 从 open 改为 allowlist，确保只有白名单用户可以触发。

{
  "channels": {
    "feishu": {
      "groupPolicy": "allowlist",
      "dmPolicy": "allowlist"
    }
  }
}

2. 清理小模型配置

删除不安全的 120B 小模型 fallback，保留更大的模型如 GLM-4.7、Qwen3 Coder 480B。

3. 启用沙箱

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all"
      }
    }
  }
}

4. 配置认证速率限制

{
  "gateway": {
    "auth": {
      "rateLimit": {
        "maxAttempts": 10,
        "windowMs": 60000,
        "lockoutMs": 300000
      }
    }
  }
}

5. 设置插件白名单

{
  "plugins": {
    "allow": ["telegram", "qqbot", "feishu"]
  }
}

第二阶段：TLS/HTTPS 配置

1. 生成自签名 SSL 证书

创建配置文件 openssl.cnf：

[req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
x509_extensions = v3_req

[dn]
C = CN
ST = Shanghai
L = Shanghai
O = OpenClaw
OU = Gateway
CN = openclaw.local

[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
DNS.2 = *.local
IP.1 = <服务器IP>
IP.2 = 127.0.0.1

生成证书和私钥：

mkdir -p ~/.openclaw/ssl

openssl req -x509 -new -nodes -sha256 -days 365 \
  -keyout ~/.openclaw/ssl/server.key \
  -out ~/.openclaw/ssl/server.crt \
  -config openssl.cnf

chmod 600 ~/.openclaw/ssl/server.key
chmod 644 ~/.openclaw/ssl/server.crt

2. 配置 TLS

将证书内容直接嵌入到 JSON 配置中：

# 读取证书并转换为带换行符的字符串格式
CERT=$(cat ~/.openclaw/ssl/server.crt | sed 's/$/\\n/' | tr -d '\n')
KEY=$(cat ~/.openclaw/ssl/server.key | sed 's/$/\\n/' | tr -d '\n')

# 更新配置
jq --arg cert "$CERT" --arg key "$KEY" \
  '.gateway.tls.tlsOptions.cert = $cert | .gateway.tls.tlsOptions.key = $key' \
  openclaw.json

第三阶段：设备配对问题（核心问题）

1. 分析错误日志

查看日志发现：

{
  "cause": "pairing-required",
  "deviceId": "aedcfa948e8244b060e2b32d3f9a940da4536c563cb7e6a1011797a216d00694",
  "reason": "not-paired",
  "host": "www.example.com:18789",
  "origin": "https://www.example.com:18789"
}

2. 检查配对状态

# 查看已配对的设备
cat ~/.openclaw/devices/paired.json

# 查看待配对的设备
cat ~/.openclaw/devices/pending.json

发现设备 ID 存在于 pending.json 但未被批准。

3. 手动配对设备

将待配对设备从 pending.json 移至 paired.json：

{
  "aedcfa948e8244b060e2b32d3f9a940da4536c563cb7e6a1011797a216d00694": {
    "deviceId": "aedcfa948e8244b060e2b32d3f9a940da4536c563cb7e6a1011797a216d00694",
    "publicKey": "349hVVrS6mKXZ1E-aspfgvnTk05lQGJQmiSB79M5Pkk",
    "platform": "MacIntel",
    "clientId": "openclaw-control-ui",
    "clientMode": "webchat",
    "role": "operator",
    "roles": ["operator"],
    "scopes": ["operator.admin", "operator.approvals", "operator.pairing"],
    "tokens": {
      "operator": {
        "token": "<自动生成的token>",
        "role": "operator",
        "scopes": ["operator.admin", "operator.approvals", "operator.pairing"],
        "createdAtMs": 1771419235347,
        "lastUsedAtMs": 1771419235347
      }
    },
    "createdAtMs": 1771419235347,
    "approvedAtMs": 1771419235347,
    "remoteIp": "<客户端IP>"
  }
}

清空 pending.json：

echo '{}' > ~/.openclaw/devices/pending.json

重启 Gateway：

openclaw gateway restart

4. 多浏览器设备 ID 问题

问题表现：之前配对的 Safari 设备 ID，切换到 Chrome 后又出现 “pairing required”。

原因：每个浏览器会生成不同的设备 ID。

解决方案：将新浏览器的设备 ID 也添加到 paired.json。

建议：长期使用同一浏览器访问，避免频繁切换导致重复配对。

最终完整配置

openclaw.json 关键配置

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowInsecureAuth": false
    },
    "auth": {
      "mode": "token",
      "token": "<your-gateway-token>",
      "rateLimit": {
        "maxAttempts": 10,
        "windowMs": 60000,
        "lockoutMs": 300000
      }
    },
    "tls": {
      "enabled": true,
      "tlsOptions": {
        "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
        "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "groupPolicy": "allowlist"
    },
    "feishu": {
      "enabled": true,
      "groupPolicy": "allowlist",
      "dmPolicy": "allowlist"
    }
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all"
      },
      "model": {
        "primary": "nvidia/z-ai/glm4.7",
        "fallbacks": [
          "zai/glm-4.7-flash",
          "nvidia/qwen/qwen3-coder-480b-a35b-instruct"
        ]
      }
    }
  },
  "plugins": {
    "allow": ["telegram", "qqbot", "feishu"]
  }
}

关键问题总结

问题现象解决方案
SSL 协议错误ERR_SSL_PROTOCOL_ERROR嵌入式 TLS 证书配置
Pairing Requireddisconnected (1008): pairing required将设备 ID 添加到 paired.json
多浏览器设备 ID切换浏览器后重新报配对错误为每台设备/浏览器添加配对
安全警告多个 CRITICAL 级别警告调整策略、启用沙箱、配置速率限制

重要注意事项

1. 证书管理

  • 自签名证书会触发浏览器安全警告，需要手动信任
  • 证书有效期 365 天，到期需重新生成
  • 生产环境建议使用正规 CA 签发的证书

2. 设备配对

  • 每个浏览器/设备有唯一设备 ID
  • 清除浏览器数据会生成新的设备 ID
  • 建议长期使用同一浏览器访问

3. 安全建议

  • ✅ 保持 allowInsecureAuth = false
  • ✅ 启用 sandbox.mode = "all"
  • ✅ 配置 auth.rateLimit
  • ✅ 设置 groupPolicy = "allowlist"
  • ✅ 设置 plugins.allow 白名单

4. 防火墙配置

确保服务器防火墙开放 18789 端口：

# Ubuntu/Debian
ufw allow 18789/tcp

# CentOS/RHEL
firewall-cmd --permanent --add-port=18789/tcp
firewall-cmd --reload

# macOS (pf)
echo "pass in proto tcp from any to any port 18789" | sudo pfctl -ef -

测试验证

1. 检查 TLS 加载

# 查看日志确认 TLS 启动
tail -f ~/Library/Logs/openclaw-gateway.log | grep -i "listen\|tls\|ssl"

2. 验证设备配对

# 查看已配对设备
jq 'keys' ~/.openclaw/devices/paired.json

3. 访问测试

  • 浏览器访问：https://your-domain.com:18789
  • Control UI 应能正常加载
  • WebSocket 连接状态应保持连接

故障排查清单

当遇到远程访问问题时，按以下顺序检查：

  1. 端口监听：netstat -tlnp | grep 18789
  2. 防火墙：iptables -L -n | grep 18789 或 ufw status
  3. TLS 配置：检查 gateway.tls 是否正确
  4. 设备配对：检查 ~/.openclaw/devices/paired.json
  5. 配对请求：检查 ~/.openclaw/devices/pending.json
  6. 错误日志：tail -f ~/Library/Logs/openclaw-gateway.log

核心经验总结

这次调试过程让我学到几个关键经验：

1. 设备配对是关键

OpenClaw 的远程访问有严格的设备认证机制。即使配置了正确的 TLS，如果设备未配对，仍然无法访问。错误日志中的 pairing-required 是最直接的提示。

2. TLS 配置方式

文件路径方式配置 TLS 在某些情况下可能不生效，推荐使用嵌入式证书方式（将证书内容直接写入 JSON 字符串）。

3. 多浏览器设备 ID

每个浏览器会生成不同的设备 ID，这是浏览器安全机制的一部分。如果你需要在不同浏览器中访问，需要分别为每个浏览器进行配对。

4. 安全配置要同步

启用远程访问前，务必检查安全配置：

  • groupPolicy 设置为 allowlist
  • sandbox.mode 设置为 "all"
  • 启用认证速率限制
  • 配置插件白名单

5. 查看待配对设备

当出现 pairing required 错误时，首先检查 pending.json 文件：

cat ~/.openclaw/devices/pending.json

可以看到待配对的设备信息，包括设备 ID、平台、客户端模式等。将这些信息复制到 paired.json 并设置 approvedAtMs，然后重启 Gateway 即可。

相关文档

常见问题（FAQ）

Q1: 自签名证书浏览器报不安全怎么办？

A: 自签名证书会导致浏览器显示”不安全”警告，这是正常的。点击”高级”→“继续访问”即可。生产环境建议使用 Let’s Encrypt 等正规 CA 签发的证书。

Q2: 换了新设备怎么配对？

A: 新设备首次访问时，设备 ID 会出现在 pending.json 中。将该设备的完整配置复制到 paired.json，设置 approvedAtMs 为当前时间戳，然后重启 Gateway。

Q3: 配对后还是无法访问？

A: 检查以下几点：

  1. TLS 配置是否正确（查看日志）
  2. 防火墙是否开放 18789 端口
  3. bind 设置是否为 lan 或 any
  4. 浏览器是否信任了自签名证书

Q4: 如何查看当前已配对的设备？

A: 查看 ~/.openclaw/devices/paired.json，里面包含了所有已配对设备的详细信息。

结语

配置 OpenClaw 的远程 Web 访问涉及多个安全层面：TLS 加密、设备认证、访问控制等。通过系统性的排查，最终发现核心问题是设备配对机制，而不是 TLS 配置本身。

希望本文能帮助其他开发者快速定位和解决类似问题。如果遇到其他问题，欢迎在 GitHub Issues 中交流。

文档版本: 1.0 最后更新: 2026-02-18 适用版本: OpenClaw 2026.2.15+

相关文章：

Related Posts

一次配置修改导致的 Gateway 启动失败

记录一次添加错误配置参数导致 OpenClaw Gateway 启动失败的经历，包括问题现象、排查过程、解决思路和预防措施。

OpenClaw 配置调试实战：解决飞书插件冲突和 Ollama 自动配置陷阱

记录解决 OpenClaw 长期告警的两个顽固问题：飞书插件 duplicate plugin id 错误，以及 Ollama 反复自动注入配置的排查过程与解决方案。