Docker 部署 OpenClaw 常见报错排查与解决方案

步骤 1：确保容器在运行状态

docker ps | grep openclaw # 如果未运行，先启动：docker start openclaw

步骤 2：执行初始化命令

docker exec -it openclaw openclaw setup

步骤 3：按交互提示完成配置

? Choose your LLM provider: (Use arrow keys) ❯ Claude (Anthropic) OpenAI (GPT-4) Ollama (Local)
? Enter your API key: [sk-...]
? Configure gateway port: (8090)

步骤 4：验证初始化成功

docker exec openclaw openclaw config list # 应显示完整配置项，无报错

⚠️ 数据持久化建议
初始化时确保挂载数据卷，避免容器重建后配置丢失：

docker run -v openclaw_data:/root/.openclaw ... maoouhu/openclaw-chinese

错误三：control ui requires HTTPS or localhost

🔍 错误现象

• 本地 localhost:8090 访问正常
• 通过 IP 或域名远程访问时，浏览器报错：

control ui requires HTTPS or localhost

或页面显示 安全策略阻止 提示。

🎯 根因分析

这是浏览器安全机制（CSP/Secure Context）限制，非 OpenClaw 故障：

• localhost 被视为安全上下文，允许明文 HTTP
• 非本地 IP/域名访问时，浏览器强制要求 HTTPS
• 防止 Token 等敏感信息在公网明文传输

✅ 解决方案（任选其一）

方案 A：Token 认证绕过（开发测试用）
已在「错误一」中配置 Token 后，访问时追加参数：

http://your-server-ip:8090?token=YOUR_TOKEN

⚠️ 仅限内网测试，公网必须使用 HTTPS！

方案 B：配置 HTTPS 反向代理（生产推荐）

Nginx 配置示例：

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;
    }
}

步骤 2：设置信任代理（见错误四）

方案 C：配置浏览器例外（仅限开发）

• Chrome：chrome://flags/#unsafely-treat-insecure-origin-as-secure
• 添加你的 IP 并启用（不推荐长期使用）

错误四：Proxy headers detected from untrusted address

🔍 错误现象

配置 Nginx 反向代理后，日志报错：

Proxy headers detected from untrusted address: 172.18.0.1

或 Dashboard 显示 502 Bad Gateway。

🎯 根因分析

OpenClaw 的安全机制检测到反向代理转发的 X-Forwarded-* 头，但代理 IP 不在信任列表中。这是为了防止 IP 伪造攻击。

常见场景：

• Nginx 和 OpenClaw 在不同 Docker 网络
• 使用云厂商负载均衡（如阿里云 SLB、AWS ALB）
• 多层反向代理（Nginx → OpenClaw）

✅ 解决方案

步骤 1：确认你的代理 IP

# 查看 OpenClaw 容器日志中的实际 IP
docker logs openclaw | grep "untrusted address"
# 输出示例：untrusted address: 172.18.0.1

步骤 2：添加信任代理 IP

# 单个 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"]'

步骤 3：重启容器

docker restart openclaw

步骤 4：验证配置

docker exec openclaw openclaw config get gateway.trustedProxies # 应返回配置的 IP 数组

🔧 Docker Compose 场景特殊处理

如果 Nginx 和 OpenClaw 在同一 Compose 网络，使用容器名通信：

services:
  openclaw:
    image: maoouhu/openclaw-chinese
    networks:
      - openclaw_net
  nginx:
    image: nginx:alpine
    networks:
      - openclaw_net
    # 反向代理地址改为 http://openclaw:8090

此时信任 IP 应配置为 Docker 网关（通常是 172.x.x.1），或查看：

docker network inspect openclaw_openclaw_net | grep Gateway

📋 快速自检清单

🆘 仍有问题？

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