Docker 安装 OpenClaw 报错排查完全手册（续）：如何解决pairing required，EACCES: permission deniedDocker 拉取镜像提示 `denied

按错误关键词 Ctrl+F 秒搜定位，建议与上篇配合收藏！

---

错误五：pairing required

🔍 错误现象

• 新设备首次连接时，日志显示：

pairing required

• 或 Dashboard 提示 “等待管理员批准”
• 命令行设备列表显示 PENDING 状态

🎯 根因分析

OpenClaw 采用设备配对机制保障安全：每台新设备（浏览器/客户端）首次连接时，必须经管理员手动批准，防止未授权访问。这类似于蓝牙配对或 SSH 密钥认证。

常见触发场景：

• 首次从手机/另一台电脑访问 Dashboard
• 清除浏览器缓存后重新连接
• 容器重建导致设备 ID 变更

✅ 解决方案

步骤 1：查看待批准设备列表

docker exec openclaw openclaw devices list

输出示例：

ID          NAME            STATUS    
----------  --------------  ----------
dev_abc123  Chrome macOS    PENDING   
dev_def456  iPhone Safari   PENDING   

步骤 2：批准指定设备

# 批准单个设备
docker exec openclaw openclaw devices approve dev_abc123

# 批量批准所有待处理设备
docker exec openclaw openclaw devices approve --all

步骤 3：拒绝可疑设备（可选）

docker exec openclaw openclaw devices reject dev_suspicious

步骤 4：设备端刷新页面
批准后，设备端重新访问 Dashboard 即可正常连接。

🔧 自动化批准（内网环境专用）

如果处于可信内网，可关闭配对验证：

docker exec openclaw openclaw config set gateway.pairingRequired false
docker restart openclaw

⚠️ 安全警告：公网部署严禁关闭，否则任何人可直连你的 AI 助手！

---

错误六：gateway token mismatch

🔍 错误现象

• 访问 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：根据日志关键词处理

日志关键词	解决方案
Missing config	执行 docker exec openclaw openclaw setup
port already in use	更换端口映射 -p 8091:8090
database is locked	删除锁文件 docker exec openclaw rm /root/.openclaw/*.db-journal
out of memory	增加 Docker 内存限制 --memory=1g

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

---

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

检查项	命令	预期结果
容器运行状态	docker ps | grep openclaw	显示 Up 状态
配置是否初始化	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	显示 LISTEN
设备配对状态	docker exec openclaw openclaw devices list	无 PENDING 设备
数据卷权限	docker exec openclaw ls -la /root/.openclaw	显示 root 可写
镜像拉取	docker images | grep openclaw	显示镜像信息

---

🆘 仍有问题？

1. 查看完整日志：docker logs --tail 200 openclaw 2>&1
2. 检查系统资源：docker stats openclaw（查看 CPU/内存）
3. 重置完全局状态：

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

4. 提交 Issue：附上 docker logs 和 docker inspect openclaw 输出到 GitHub Issues

---

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