Shell / BashAI
Docker 安装 OpenClaw 常见报错排查与解决方案
Docker 部署 OpenClaw 时可能遇到网关认证 Token 缺失、配置文件未初始化、非本地访问需 HTTPS 以及代理头信任地址校验失败等问题。解决方法涉及在容器内设置认证 Token、运行初始化脚本、配置 Nginx 反向代理启用 SSL 或将代理 IP 加入信任列表。修正 Docker 命令空格及网络配置后，可恢复服务正常访问。
Docker 部署 OpenClaw 时可能遇到网关认证 Token 缺失、配置文件未初始化、非本地访问需 HTTPS 以及代理头信任地址校验失败等问题。解决方法涉及在容器内设置认证 Token、运行初始化脚本、配置 Nginx 反向代理启用 SSL 或将代理 IP 加入信任列表。修正 Docker 命令空格及网络配置后，可恢复服务正常访问。
容器启动后日志出现：
Gateway auth is set to token, but no token is configured
或浏览器访问 Dashboard 时返回 401 Unauthorized。
OpenClaw 默认启用 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_TOKENAuthorization: Bearer YOUR_TOKEN容器启动后立即退出，日志显示：
Missing config. Run openclaw setup
或执行命令时提示配置缺失。
OpenClaw 首次运行必须初始化配置数据库，包括：
常见触发场景：
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
localhost:8090 访问正常control ui requires HTTPS or localhost
或页面显示 安全策略阻止 提示。
这是浏览器安全机制（CSP/Secure Context）限制，非 OpenClaw 故障：
localhost 被视为安全上下文，允许明文 HTTP方案 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://flags/#unsafely-treat-insecure-origin-as-secure配置 Nginx 反向代理后，日志报错：
Proxy headers detected from untrusted address: 172.18.0.1
或 Dashboard 显示 502 Bad Gateway。
OpenClaw 的安全机制检测到反向代理转发的 X-Forwarded-* 头，但代理 IP 不在信任列表中。这是为了防止 IP 伪造攻击。
常见场景：
步骤 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 openclawdocker exec openclaw cat /root/.openclaw/config.jsondocker exec openclaw openclaw setup --force💡 预防胜于治疗：建议首次部署时按顺序执行：初始化 → 配置 Token → 配置代理 → 启动服务，可避免 90% 的报错！
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online