docker镜像拉取失败通常由网络、配置、权限或镜像源问题交织导致，需依报错关键词定向排查：如“i/o timeout”聚焦网络与dns，“unauthorized”检查认证，“manifest unknown”核对镜像名与标签，并依次验证连通性、dns解析、docker配置生效、用户权限及镜像存在性。
拉取失败通常不是单一原因，而是网络、配置、权限或镜像源几类问题交织导致。直接看报错关键词比盲目重试更高效——比如出现 “i/o timeout” 多是网络或代理问题；“unauthorized” 说明认证缺失；“manifest unknown” 往往是镜像名或标签写错了。
查网络连通性与 DNS 解析
这是最常被跳过的一步，但却是多数超时问题的根源。
- 先测试基础连通：
ping registry-1.docker.io。不通就说明本地网络或防火墙阻断了出站请求 - 再验证 DNS：
nslookup registry-1.docker.io或dig registry-1.docker.io。若解析失败或返回空结果，需检查/etc/resolv.conf，临时换为8.8.8.8或114.114.114.114 - 最后模拟 Docker 请求：
curl -v https://registry-1.docker.io/v2/。能返回 HTTP 200 才算真正通了；如果卡住或报connection refused，说明代理、防火墙或中间网关有问题
确认 Docker 配置是否生效
很多人改了 /etc/docker/daemon.json 却忘了重启，或者格式写错导致配置被忽略。
OpenClaw Docker Setup
下载
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
- 检查配置文件语法：
sudo jsonlint /etc/docker/daemon.json（没装可先pip install jsonlint） - 重点核对
registry-mirrors地址是否有效（推荐用阿里云、中科大或网易镜像源，如https://<your-id>.mirror.aliyuncs.com</your-id>） - 改完必须执行：
sudo systemctl daemon-reload && sudo systemctl restart docker，然后用docker info | grep -A 1 "Registry Mirrors"确认已加载
验证权限与认证状态
非 root 用户没加 docker 组，或私有仓库没登录，都会静默失败。
- 运行
groups查当前用户是否在docker组里；不在就执行sudo usermod -aG docker $USER，然后退出终端重登 - 拉私有镜像时报
unauthorized？先docker login your-registry.example.com，再检查~/.docker/config.json是否存有对应 auth 记录 - 如果是 CI/CD 环境（如 GitHub Actions），确保 secret 中的 registry token 正确且未过期
排除镜像本身的问题
有时候不是你的环境问题，而是镜像名、标签或仓库服务出了状况。
- 用
docker search nginx确认镜像存在；再查官方页或仓库文档，确认你写的标签（如:alpine、:1.25）确实被发布 - 访问 Docker Hub 或私有仓库 Web 页面，手动搜索该镜像，看能否打开详情页
- 如果所有镜像都拉不动，但
curl和ping都正常，可能是 Docker Hub 临时故障——可查看 status.docker.com 确认服务状态
