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

Docker 部署 OpenClaw 常见报错排查与解决方案 | 极客日志

Docker 安装 OpenClaw 报错排查

错误一：`Gateway auth is set to token, but no token is configured`

🔍 错误现象

容器启动后日志出现：

Gateway auth is set to token, but no token is configured

或浏览器访问 Dashboard 时返回 401 Unauthorized。

🎯 根因分析

OpenClaw 默认启用 Token 认证机制 保护远程访问安全，但你尚未设置具体的 Token 值。这通常发生在：

首次部署后直接进入配置阶段
手动修改配置时误删了 token 字段
从旧版本升级后配置未迁移

✅ 解决方案

步骤 1：进入容器执行配置命令

docker exec openclaw openclaw config set gateway.auth.token YOUR_TOKEN

将 YOUR_TOKEN 替换为强密码（建议 16 位以上随机字符串）

步骤 2：验证配置是否生效

docker exec openclaw openclaw config get gateway.auth.token # 应返回你设置的 token 值

步骤 3：重启容器使配置生效

docker restart openclaw

步骤 4：访问时携带 Token

浏览器访问：https://your-domain.com?token=YOUR_TOKEN
API 调用：Header 中添加 Authorization: Bearer YOUR_TOKEN

错误二：`Missing config. Run openclaw setup`

🔍 错误现象

容器启动后立即退出，日志显示：

Missing config. Run openclaw setup

或执行命令时提示配置缺失。

🎯 根因分析

OpenClaw 首次运行必须初始化配置数据库，包括：

创建默认配置文件
初始化 SQLite/PostgreSQL 数据库
设置默认网关和模型参数

常见触发场景：

直接 docker run 但未执行初始化
数据卷挂载错误导致配置丢失
容器重建后未重新初始化

✅ 解决方案

步骤 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

📋 快速自检清单

检查项	命令	预期结果
容器运行状态	`docker ps	grep openclaw`
配置是否初始化	`docker exec openclaw openclaw config list`	无报错，显示配置
Token 是否设置	`docker exec openclaw openclaw config get gateway.auth.token`	返回非空值
信任代理配置	`docker exec openclaw openclaw config get gateway.trustedProxies`	包含你的代理 IP
端口是否监听	`docker exec openclaw netstat -tlnp	grep 8090`

🆘 仍有问题？

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

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

Docker 安装 OpenClaw 报错排查

错误一：`Gateway auth is set to token, but no token is configured`

🔍 错误现象

🎯 根因分析

✅ 解决方案

错误二：`Missing config. Run openclaw setup`

🔍 错误现象

🎯 根因分析

✅ 解决方案

错误三：`control ui requires HTTPS or localhost`

🔍 错误现象

🎯 根因分析

✅ 解决方案（任选其一）

错误四：`Proxy headers detected from untrusted address`

🔍 错误现象

🎯 根因分析

✅ 解决方案

📋 快速自检清单

🆘 仍有问题？

更多推荐文章

相关免费在线工具

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

Docker 安装 OpenClaw 报错排查

错误一：Gateway auth is set to token, but no token is configured

🔍 错误现象

🎯 根因分析

✅ 解决方案

错误二：Missing config. Run openclaw setup

🔍 错误现象

🎯 根因分析

✅ 解决方案

错误三：control ui requires HTTPS or localhost

🔍 错误现象

🎯 根因分析

✅ 解决方案（任选其一）

错误四：Proxy headers detected from untrusted address

🔍 错误现象

🎯 根因分析

✅ 解决方案

📋 快速自检清单

🆘 仍有问题？

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

错误一：`Gateway auth is set to token, but no token is configured`

错误二：`Missing config. Run openclaw setup`

错误三：`control ui requires HTTPS or localhost`

错误四：`Proxy headers detected from untrusted address`