OpenClaw Gateway HTTPS 自签名证书配置指南

适用场景：云服务器没有域名，或域名审核中，先用自签名证书启用 HTTPS

目录

  1. 原理说明
  2. 第一步：生成自签名证书
  3. 第二步：修改 Gateway 配置
  4. 第三步：重启 Gateway
  5. 第四步：验证 HTTPS
  6. 浏览器访问说明
  7. 允许跨域（可选）
  8. 后续升级到正式证书
  9. 常见问题

原理说明

自签名证书（Self-Signed Certificate）就是用你自己的服务器生成的证书，没有经过权威 CA（如 Let’s Encrypt、DigiCert）签名。

  • 加密通信完全有效 —— 数据传输是加密的，没人能窃听
  • 浏览器会提示不安全 —— 因为不在 CA 信任列表中，需要手动确认
  • 等域名下来后 —— 换成 Let’s Encrypt 证书就完全无警告了

第一步：生成自签名证书

1.1 创建证书存放目录

1
mkdir -p /etc/openclaw/tls

1.2 生成证书和私钥

1
2
3
4
5
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/openclaw/tls/server.key \
  -out /etc/openclaw/tls/server.crt \
  -subj "/CN=你的服务器IP或名称" \
  -addext "subjectAltName=IP:你的服务器IP,DNS:localhost"

参数说明：

参数 含义
-x509 生成自签名证书，而非证书签名请求
-nodes 私钥不加密（No DES），免密码启动
-days 3650 有效期 10 年（按需调整）
-newkey rsa:2048 同时生成新的 2048 位 RSA 私钥
-keyout 私钥输出路径
-out 证书输出路径
-subj 证书主体信息，CN 填你的服务器 IP 或任意标识
-addext 附加 SAN（Subject Alternative Name），必须加 IP 否则浏览器会报错

重要： subjectAltName 必须包含你的公网 IP，否则浏览器会提示「证书名称不匹配」。

1.3 查看证书信息（验证）

1
openssl x509 -in /etc/openclaw/tls/server.crt -noout -subject -dates

输出示例：

1
2
3
subject=CN = 111.228.60.248
notBefore=Jun 25 02:02:00 2026 GMT
notAfter=Jun 22 02:02:00 2036 GMT

第二步：修改 Gateway 配置

编辑 ~/.openclaw/openclaw.json，在 gateway 字段下添加 tls 配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "gateway": {
    "bind": "lan",
    "tls": {
      "enabled": true,
      "certPath": "/etc/openclaw/tls/server.crt",
      "keyPath": "/etc/openclaw/tls/server.key"
    },
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "http://你的公网IP:18789",
        "https://你的公网IP:18789"
      ]
    }
  }
}

注意： controlUi.allowedOrigins 需要同时加上 http:// 和 https:// 两个版本的地址，否则 WebChat 可能连不上。

第三步：重启 Gateway

1
openclaw gateway restart

重启后等待几秒钟，查看状态：

1
openclaw gateway status

看到 Dashboard: https://你的IP:18789/ 即代表 TLS 已生效。

第四步：验证 HTTPS

4.1 命令行验证

1
2
3
4
# 本地验证（用 -k 忽略自签名检查）
curl -sk https://127.0.0.1:18789/health

# 应返回：{"ok":true,"status":"live"}

4.2 验证 HTTP 是否被关闭

1
2
3
# HTTP 请求应该失败
curl -s http://127.0.0.1:18789/health
# 应无响应或连接被拒绝

4.3 查看证书详情

1
openssl s_client -connect 127.0.0.1:18789 -servername 127.0.0.1 </dev/null 2>/dev/null | openssl x509 -noout -text | head -20

浏览器访问说明

用 https://你的公网IP:18789 访问，浏览器会提示：

Chrome

1
2
您的连接不是私密连接
NET::ERR_CERT_AUTHORITY_INVALID

解决方法： 点击页面空白处，直接键盘输入 thisisunsafe（Chrome 的隐藏绕过命令），页面会自动刷新并进入。

或者点击「高级」→「继续前往 xxx.xxx.xxx.xxx（不安全）」

Edge

1
你的连接不是专用连接

解决方法： 点击「高级」→「继续前往 xxx.xxx.xxx.xxx（不安全）」

Firefox

1
警告：面临潜在安全风险

解决方法： 点击「高级」→「接受风险并继续」

只要点一次，浏览器会记住这个例外，下次不再提示。

允许跨域（可选）

如果你需要通过 WebChat 或其他前端页面访问 Gateway，需要在配置中添加跨域来源：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": true,
      "allowedOrigins": [
        "http://localhost:18789",
        "https://localhost:18789",
        "http://127.0.0.1:18789",
        "https://127.0.0.1:18789",
        "http://你的公网IP:18789",
        "https://你的公网IP:18789"
      ]
    }
  }
}

修改后同样需要重启 Gateway 才能生效。

后续升级到正式证书

域名审核通过后，升级到 Let’s Encrypt 正式证书：

5.1 安装 acme.sh

1
curl https://get.acme.sh | sh

5.2 申请证书

1
2
3
4
5
6
7
# 方式一：standalone 模式（需要临时占用 80 端口）
~/.acme.sh/acme.sh --issue -d your-domain.com --standalone

# 方式二：DNS API 模式（推荐，不需要 80 端口）
# 以 Cloudflare 为例：
export CF_Token="你的CloudflareAPI令牌"
~/.acme.sh/acme.sh --issue -d your-domain.com --dns dns_cf

5.3 安装到 Gateway 目录

1
2
3
~/.acme.sh/acme.sh --install-cert -d your-domain.com \
  --key-file /etc/openclaw/tls/server.key \
  --fullchain-file /etc/openclaw/tls/server.crt

5.4 重启 Gateway

1
openclaw gateway restart

acme.sh 会自动续期证书（每 60 天检查一次），证书更新后可能需要手动重启 Gateway（或配置续期钩子自动重启）。

常见问题

Q1: Gateway 启动不起来，端口被占用

1
2
3
4
5
6
7
8
# 查看占用端口的进程
ss -tlnp | grep 18789

# 强制杀掉旧进程
kill -9 <PID>

# 重新启动
openclaw gateway restart

Q2: 浏览器提示「证书名称不匹配」

生成证书时 -addext 没有包含正确的 IP。重新生成：

1
2
3
4
5
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/openclaw/tls/server.key \
  -out /etc/openclaw/tls/server.crt \
  -subj "/CN=你的公网IP" \
  -addext "subjectAltName=IP:你的公网IP"

Q3: 证书文件权限问题

私钥文件需要只有 root 可读：

1
2
chmod 600 /etc/openclaw/tls/server.key
chmod 644 /etc/openclaw/tls/server.crt

Q4: WebChat 连不上

检查 controlUi.allowedOrigins 是否同时包含了 http:// 和 https:// 两种协议。

Q5: 想关闭 HTTP 端口

Gateway 启用 TLS 后，默认只监听 HTTPS，不会同时监听 HTTP。如果发现 HTTP 仍然可用，检查配置是否有端口冲突或反向代理。

参考