OpenCLAW 局域网 HTTPS 访问完整教程

教程背景

为什么有这个教程？

OpenCLAW 默认只允许本机访问（127.0.0.1），这出于安全考虑。但实际使用中，我们经常需要从局域网其他设备访问 OpenCLAW，例如：

• 在 Mac 上访问 Ubuntu 服务器上的 OpenCLAW

• 在手机上测试 OpenCLAW 功能

• 团队成员共享一个 OpenCLAW 实例

我遇到的问题

1. 直接绑定局域网 IP 无法访问
• 错误提示：control ui requires device identity (use HTTPS or localhost secure context)
• 即使设置 "bind": "lan"，浏览器也会阻止 HTTP 访问

1. 浏览器安全策略限制
• 局域网 HTTP 访问被视为”不安全上下文”
• 浏览器要求这类功能必须在 HTTPS 或 localhost 环境下运行
• OpenCLAW 的 Control UI 使用 Web Crypto API 进行设备认证

1. 证书配置复杂
• 局域网环境没有域名，无法使用 Let’s Encrypt 等公共 CA
• 传统 HTTPS 配置需要购买域名和 SSL 证书

解决方案

使用 mkcert 生成本地信任的 HTTPS 证书：

• ✅ 免费，无需域名

• ✅ 浏览器完全信任（安装根证书后）

• ✅ 支持局域网 IP 证书

• ✅ 配置简单，5 分钟搞定

目录

1. 环境要求

1. 服务端配置（Ubuntu）

1. 客户端配置（Mac/Windows/Linux）

1. 访问测试

1. 常见问题

环境要求

服务端配置（Ubuntu）

步骤 1：安装 mkcert

# Debian/Ubuntusudo apt install mkcertmkcert -install# 或使用二进制curl -JLO "https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64"chmod +x mkcert-v1.4.4-linux-amd64sudo mv mkcert-v1.4.4-linux-amd64 /usr/local/bin/mkcertmkcert -install

步骤 2：生成局域网证书

# 创建证书目录mkdir -p ~/.openclaw/sslcd ~/.openclaw/ssl# 生成证书（替换为你的局域网IP）mkcert 192.168.31.161 localhost 127.0.0.1

生成后会输出：

Created a new certificate valid for the following names 📜 - "192.168.31.161" - "localhost" - "127.0.0.1"The certificate is at "./192.168.31.161+2.pem"The key is at "./192.168.31.161+2-key.pem"

步骤 3：获取根证书内容

# 查看根证书路径mkcert -CAROOT# 查看根证书内容（后续需要用到这个文件）cat $(mkcert -CAROOT)/rootCA.pem

步骤 4：配置 OpenCLAW

编辑 ~/.openclaw/openclaw.json：

{  "gateway": {    "port": 8080,    "mode": "local",    "bind": "lan",    "tls": {      "enabled": true,      "certPath": "/home/Username/.openclaw/ssl/192.168.31.161+2.pem",      "keyPath": "/home/Username/.openclaw/ssl/192.168.31.161+2-key.pem"    },    "controlUi": {      "allowedOrigins": [        "https://localhost:8080",        "https://127.0.0.1:8080",        "https://192.168.31.161:8080"      ]    },    "auth": {      "mode": "token",      "token": "你的 token"    }  }}

步骤 5：重启 OpenCLAW

# 停止旧实例openclaw gateway stop# 启动新实例openclaw gateway

客户端配置（Mac/Windows/Linux）

Mac 客户端

1. 安装 mkcert

# 使用 Homebrewbrew install mkcert

2. 安装根证书

方法 A：文件导入

1. 从服务器复制 rootCA.pem 这个文件到Mac上

1. 打开 钥匙串访问

1. 拖入证书到 “系统” 钥匙串

1. 双击证书 → 展开”信任” → 设为”始终信任”

1. 输入密码确认

3. 重启浏览器

完全关闭 Edge/Chrome，然后重新打开。

Windows 客户端

1. 安装 mkcert

# 使用 Chocolateychoco install mkcert# 或使用 Scoopscoop install mkcert

2. 安装根证书

1. 从服务器复制 rootCA.pem 这个文件到Windows

1. 双击 rootCA.pem

1. 点击 “安装证书”

1. 选择 “本地计算机” → 下一步

1. 选择 “将所有的证书都放入下列存储”

1. 点击 “浏览” → 选择 “受信任的根证书颁发机构”

1. 完成安装

3. 重启浏览器

Linux 客户端

1. 导入根证书

# 创建证书文件cat > /tmp/rootCA.pem << 'EOF'-----BEGIN CERTIFICATE-----（粘贴服务器的 rootCA.pem 内容）-----END CERTIFICATE-----EOF# Firefox：导入到浏览器certutil -d sql:$HOME/.mozilla/firefox/*.default-release -A -t "P,," -n "mkcert" -i /tmp/rootCA.pem# Chrome/Chromium：导入到 nss 数据库certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n "mkcert" -i /tmp/rootCA.pem

提示：如果 certutil 未安装，运行 sudo apt install libnss3-tools

2. 重启浏览器

访问测试 HTTPS 访问

在客户端浏览器访问：

https://192.168.31.161:8080

应该能显示HTTPS安全锁标志 🔒

常见问题

1. 证书错误 ERR_CERT_AUTHORITY_INVALID

原因：根证书未安装到客户端

解决：重新执行客户端配置步骤，确保证书安装到”受信任的根证书颁发机构”

2. CORS 错误 origin not allowed

原因：客户端 IP 不在白名单

解决：在 openclaw.json 中添加客户端 IP：

"controlUi": {  "allowedOrigins": [    "https://192.168.31.161:8080",    "https://你的客户端IP:8080"  ]}

3. WebSocket 连接失败

原因：防火墙阻止

解决：

# Ubuntu 开放端口sudo ufw allow 8080/tcp

4. 证书过期

mkcert 证书默认有效期 2 年，过期后重新生成：

# 在服务端重新生成cd ~/.openclaw/sslmkcert 192.168.31.161 localhost 127.0.0.1# 重启 OpenCLAWopenclaw gateway restart

5. 多客户端访问

每个客户端都需要安装根证书。

安全建议

1. Token 安全
   ：不要泄露 gateway.auth.token

1. 防火墙
   ：只开放必要端口

1. 定期更新
   ：保持 OpenCLAW 和 mkcert 更新

1. 备份证书
   ：备份 ~/.openclaw/ssl/ 目录

1. 私钥保密
   ：永远不要分享 -key.pem 文件

完成！ 现在可以通过局域网的 HTTPS 安全地访问 OpenCLAW 了！🎉