Docker 部署 OpenClaw 常见报错排查与解决指南

server {
    listen 443 ssl http2;
    server_name openclaw.yourdomain.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8090;
        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 $scheme;
    }
}

代理头信任问题

配置 Nginx 反向代理后，若日志报错 Proxy headers detected from untrusted address，说明 OpenClaw 检测到转发的 X-Forwarded-* 头，但代理 IP 不在信任列表中。这是为了防止 IP 伪造攻击。

首先查看日志中的实际代理 IP：

docker logs openclaw | grep "untrusted address"

假设输出为 172.18.0.1，则需将其加入信任列表：

# 单个 IP
docker exec openclaw openclaw config set gateway.trustedProxies '["172.18.0.1"]'

# 多个 IP（JSON 数组格式）
docker exec openclaw openclaw config set gateway.trustedProxies '["127.0.0.1", "172.18.0.0/16"]'

# 信任所有私有网段（内网环境简化配置）
docker exec openclaw openclaw config set gateway.trustedProxies '["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "127.0.0.1"]'

修改后重启容器并验证：

docker restart openclaw
docker exec openclaw openclaw config get gateway.trustedProxies

如果是 Docker Compose 场景且 Nginx 与 OpenClaw 在同一网络，建议使用容器名通信，此时信任 IP 应配置为 Docker 网关地址（通常是 172.x.x.1），可通过 docker network inspect 查询。

快速自检清单

仍有问题？

1. 查看完整日志：docker logs --tail 100 openclaw
2. 检查配置文件：docker exec openclaw cat /root/.openclaw/config.json
3. 重置配置（慎用）：docker exec openclaw openclaw setup --force
4. 提交 Issue：附上日志和配置到 GitHub Issues

预防胜于治疗，建议首次部署按顺序执行：初始化 → 配置 Token → 配置代理 → 启动服务，可避免绝大多数报错。