Docker 安装 OpenClaw 常见报错排查：配对、权限及镜像拉取问题

• 访问 Dashboard 时返回：

gateway token mismatch

• 或页面显示'Token 验证失败，请重新登录'
• API 调用返回 401 Unauthorized

🎯 根因分析

客户端提供的 Token 与服务端配置不匹配，常见原因：

• URL 中的 ?token=xxx 参数拼写错误
• Token 被重置后，旧书签/缓存未更新
• 多实例部署时，请求路由到了不同容器

✅ 解决方案

步骤 1：获取当前有效 Token URL

docker exec openclaw openclaw dashboard --print-url

输出示例：

https://openclaw.yourdomain.com?token=sk_live_abc123xyz789

步骤 2：直接使用输出的完整 URL 访问

• 复制命令行输出的完整链接（含 token 参数）
• 浏览器无痕模式打开，排除缓存干扰

步骤 3：重置 Token（如已泄露）

# 生成新 Token
docker exec openclaw openclaw config set gateway.auth.token $(openssl rand -hex 16)
docker restart openclaw
# 重新获取 URL
docker exec openclaw openclaw dashboard --print-url

步骤 4：更新书签和客户端配置

• 删除浏览器旧书签
• 更新手机/Discord Bot 等客户端的 Token 配置

🔧 持久化 Token 配置 避免容器重建后 Token 变更，使用环境变量：

docker run -e OPENCLAW_GATEWAY_TOKEN=your_fixed_token maoouhu/openclaw-chinese

错误七：容器启动后立即退出

🔍 错误现象

• docker ps 显示容器 Exited (1) 状态
• 启动命令执行后秒退，无法保持运行
• 日志为空或仅显示启动命令

🎯 根因分析

容器启动失败的最常见根因是前置依赖未满足：

• 未执行 openclaw setup 初始化配置
• 数据库文件损坏或权限不足
• 端口被占用（8090 冲突）
• 内存不足（OpenClaw 建议最低 512MB）

✅ 解决方案

步骤 1：查看退出日志

# 查看最后 50 行日志
docker logs --tail 50 openclaw
# 实时跟踪启动过程
docker logs -f openclaw

步骤 2：根据日志关键词处理

步骤 3：强制重新初始化（终极方案）

# 停止并删除容器
docker stop openclaw && docker rm openclaw
# 清理数据卷（注意备份）
docker volume rm openclaw_data
# 重新创建并初始化
docker run -d --name openclaw \
  -v openclaw_data:/root/.openclaw \
  -p 8090:8090 \
  maoouhu/openclaw-chinese
docker exec -it openclaw openclaw setup

步骤 4：健康检查配置 在 docker-compose.yml 中添加自动重启：

services:
  openclaw:
    image: maoouhu/openclaw-chinese
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/health"]
      interval: 30s
      timeout: 10s
      retries: 3

错误八：EACCES: permission denied

🔍 错误现象

• 日志显示文件系统权限错误：

EACCES: permission denied, open'/root/.openclaw/config.json'

• 或 sqlite3 报错数据库只读
• 容器反复重启但无法写入数据

🎯 根因分析

OpenClaw 默认以 root 用户（UID 0）运行，写入 /root/.openclaw 目录。使用 bind mount（本地路径映射）时，宿主机目录权限与容器内不匹配，导致写入失败。

对比：

• ❌ Bind mount：-v /home/user/openclaw:/root/.openclaw（易出权限问题）
• ✅ Named volume：-v openclaw_data:/root/.openclaw（Docker 自动管理权限）

✅ 解决方案

方案 A：使用 Named Volume（推荐）

# 创建命名卷
docker volume create openclaw_data
# 运行容器
docker run -d --name openclaw \
  -v openclaw_data:/root/.openclaw \
  -p 8090:8090 \
  maoouhu/openclaw-chinese

方案 B：修正 Bind Mount 权限（如需本地目录）

# 创建目录并设置权限
mkdir -p /home/user/openclaw
chmod 777 /home/user/openclaw
# 临时方案，生产环境建议 755 + 正确属主
# 运行容器
docker run -d --name openclaw \
  -v /home/user/openclaw:/root/.openclaw \
  -p 8090:8090 \
  maoouhu/openclaw-chinese

方案 C：指定容器用户（高级）

# 以当前用户权限运行（UID:GID 匹配宿主机）
docker run -d --name openclaw \
  --user $(id -u):$(id -g) \
  -v openclaw_data:/root/.openclaw \
  -p 8090:8090 \
  maoouhu/openclaw-chinese

🔧 权限诊断命令

# 查看容器内目录权限
docker exec openclaw ls -la /root/.openclaw
# 查看宿主机 bind mount 权限（如使用）
ls -la /home/user/openclaw

错误九：Docker 拉取镜像提示 denied

🔍 错误现象

• 执行 docker pull 时报错：

Error response from daemon: Head "https://ghcr.io/v2/...": denied: denied

• 或 docker run 时提示镜像不存在
• 登录 GitHub Container Registry 后仍失败

🎯 根因分析

GitHub Container Registry (ghcr.io) 的令牌缓存冲突。你可能曾经：

• 登录过 ghcr.io 但令牌过期
• 使用 docker login ghcr.io -u USERNAME 但密码是旧版 Token
• GitHub 账户权限变更（如仓库从 Public 转为 Private）

✅ 解决方案

步骤 1：登出并清理缓存

# 登出 ghcr.io
docker logout ghcr.io
# 清理所有登录凭证（可选，彻底重置）
docker logout

步骤 2：重新登录（如需私有镜像）

# 生成 GitHub Personal Access Token (classic)
# 权限勾选：read:packages
# 地址：https://github.com/settings/tokens
# 登录（密码处粘贴 Token，非 GitHub 密码）
docker login ghcr.io -u YOUR_GITHUB_USERNAME
Password: <粘贴 Token>

步骤 3：重新拉取镜像

# 使用正确镜像地址（OpenClaw 汉化版）
docker pull ghcr.io/maoouhu/openclaw-chinese:latest
# 或使用 Docker Hub 镜像（如可用）
docker pull maoouhu/openclaw-chinese:latest

步骤 4：验证镜像

docker images | grep openclaw
# 应显示 maoouhu/openclaw-chinese 或 ghcr.io/maoouhu/openclaw-chinese

🔧 免登录拉取（Public 镜像）

OpenClaw 汉化版为 Public 仓库，无需登录：

# 直接拉取，跳过登录步骤
docker pull ghcr.io/maoouhu/openclaw-chinese:latest

如果仍提示 denied，检查：

1. 网络是否可访问 ghcr.io（部分企业防火墙拦截）
2. 使用镜像代理：docker pull dockerproxy.com/ghcr.io/maoouhu/openclaw-chinese:latest

📋 快速自检清单（完整版）

🆘 仍有问题？

1. 查看完整日志：docker logs --tail 200 openclaw 2>&1
2. 检查系统资源：docker stats openclaw（查看 CPU/内存）
3. 提交 Issue：附上 docker logs 和 docker inspect openclaw 输出到 GitHub Issues

重置完全局状态：

docker stop openclaw
docker rm openclaw
docker volume rm openclaw_data
docker system prune -f
# 然后重新部署

💡 部署口诀：先初始化，再配 Token，检查代理，最后看权限。按此顺序排查，99% 的 Docker 报错都能迎刃而解！