错误五：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，检查：
- 网络是否可访问
ghcr.io（部分企业防火墙拦截） - 使用镜像代理：
docker pull dockerproxy.com/ghcr.io/maoouhu/openclaw-chinese:latest
📋 快速自检清单（完整版）
| 检查项 | 命令 | 预期结果 |
|---|---|---|
| 容器运行状态 | `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 exec openclaw openclaw devices list | 无 PENDING 设备 |
| 数据卷权限 | docker exec openclaw ls -la /root/.openclaw | 显示 root 可写 |
| 镜像拉取 | `docker images | grep openclaw` |
🆘 仍有问题？
- 查看完整日志：
docker logs --tail 200 openclaw 2>&1 - 检查系统资源：
docker stats openclaw（查看 CPU/内存） - 提交 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 报错都能迎刃而解！
