
Docker Agent 429 排查:3 类限流原因与修复
Docker Agent 报 429 时,先分清是谁在限你。Docker Agent 自己不会返回 429,这个状态码要么来自 Docker Hub,要么来自你配置的模型厂商。官方给的判断依据是:滥用限流返回一句极简的 429 Too Many Requests,拉取限额是带文档链接的长错误。
顺带确认你跑的是哪个:Sandboxes 里的 sbx run docker-agent 默认跑 docker-agent run --yolo,独立装的本体用 docker agent run agent.yaml。两者凭据都在宿主机,要查的地方一样。

原因一:Docker Hub 滥用限流
这是最容易误判的一类。Docker Hub 除了拉取次数限额,还有一道独立的滥用限流。官方原文说它针对对 Hub 属性的所有请求,包括网页、API 和镜像拉取,按 IPv4 或 IPv6 /64 子网计算,量级每分钟数千次,对所有账号等级一视同仁,Pro 用户也一样会被拦。
常见触发是 CI 多个 Job 共享出口 IP、内网几十人走同一个 NAT,或批量构建镜像时短时间发起大量 layer 拉取。账号没超额却频繁 429、错误只有一行纯文本,就是它。
处理按性价比排:
- 降并发,把同时拉镜像的 Job 砍一半观察,多数情况立刻缓解。
- 换出口,给 CI 或受限机器配独立出口 IP,别和其他人共用 NAT。
- 加缓存,在内网跑 registry mirror,让重复拉取不落到 Hub。
原因二:Docker Hub 拉取限额
这类跟账号等级挂钩。官方表格:未登录用户每 6 小时 100 次,按 IPv4 或 IPv6 /64 子网算;个人版登录 200 次;Pro、Team、Business 登录后不限。
注意「未登录」三个字。Docker Agent 在 Sandboxes 里跑时,宿主机登录了,但沙箱内 Docker Engine 未必带认证,拉取被算成匿名请求。这是最常被忽略的一环。
查当前额度用官方三步,本机需要有 curl 和 jq:
TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest
返回头会出现 ratelimit-limit: 100;w=21600 与 ratelimit-remaining: 20;w=21600,前者是 6 小时上限,后者是还剩多少。一行都没有,说明这个镜像不计入限额,或者你是付费订阅。官方还提醒过 GET 会真实消耗次数,HEAD 不会。
修复三条:确保发请求的身份是登录状态,包括沙箱内 Docker Engine;重度使用升 Pro;配 registry mirror 挡掉重复拉取。

原因三:模型厂商限速
这类跟 Docker 没关系,症状一样是 429。Docker Agent 支持的大厂里,OpenAI 走 OPENAI_API_KEY,Anthropic 走 ANTHROPIC_API_KEY,Google 走 GOOGLE_API_KEY 或 GEMINI_API_KEY,DeepSeek 走 DEEPSEEK_API_KEY。
多智能体场景最容易撞上。root agent 把任务分派给多个 sub agent,每个有自己的上下文和模型调用,一轮下来请求数翻好几倍,共用同一个 key 时很容易超过每分钟请求数。
识别方法:把请求里的 model 字段和厂商对上,OpenAI 的查 OpenAI 用量页,Anthropic 的查 Anthropic 额度页。厂商的 429 通常带 rate_limit_error 或 tokens per minute,跟 Docker Hub 那句纯文本完全不同。
处理办法:给不同 agent 配不同模型,官方文档就推荐过,贵留复杂推理,常规任务换本地模型;拆 key 分开算配额;或换 Docker Model Runner 本地跑,没有 key 也没有调用费用。
一个容易踩的坑:代理注入
在 Sandboxes 里跑 Docker Agent,凭据用 sbx secret set anthropic 这类命令存,值在宿主机钥匙串里。官方说明写得清楚:发请求时宿主机 HTTP/HTTPS 代理会拦截,查出匹配凭据,覆写认证头再转发,沙箱里只看到 proxy-managed 占位符,这是正常的。反过来,官方提醒过别在沙箱里把 key 设成无效值,那会打乱注入。
还有个更隐蔽的分支。凭据配置正确但 API 仍失败时,去看 sbx policy log 的 PROXY 列。走 transparent 代理的请求不做凭据注入,表现往往是 401,混在 429 里也常见。

速查表
| 现象 | 根因 | 第一步做什么 |
|---|---|---|
纯 429 Too Many Requests 一行 |
Docker Hub 滥用限流 | 降并发或换出口 IP |
| 带文档链接的长错误,提示拉取限额 | 拉取次数超限 | 确认登录身份,或升 Pro |
| 响应体含 rate_limit_error | 模型厂商限速 | 查厂商用量,拆 key 或换本地模型 |
| 401 而不是 429,配置看着没问题 | 代理未注入凭据 | 看 sbx policy log 的 PROXY 列 |
反过来做更快。先跑一遍 sbx diagnose,它检查 CLI 二进制、daemon 可达性、版本匹配和认证状态。
站内配合 Docker Agent 和 Gordon 区别 看定位,装不起来看 Docker Agent cagent 安装教程,额度看 Docker Agent 免费用。
官方依据是 Docker Hub 用量与限额、拉取用量说明 和 Sandboxes 故障排查。
常见问题
Docker Agent 429 是免费额度用完了吗
不一定。滥用限流对所有账号等级一视同仁,Pro 用户也可能撞上。先看形态:纯一行 429 是滥用限流,带文档链接的是拉取限额,响应体里有 rate_limit_error 的是模型厂商限速。
怎么查 Docker Hub 还剩多少拉取次数
先取 token,再对 ratelimitpreview 仓库发一次 HEAD 请求,读返回头里的 ratelimit-limit 与 ratelimit-remaining。HEAD 不消耗额度,GET 会。两个头都没有说明这个镜像或你的账号不计入限额。
为什么我明明登录了还被算成匿名请求
常见于 Sandboxes 场景。宿主机登录了,但沙箱内 Docker Engine 未必带认证,拉取被算成匿名,上限变成每 6 小时 100 次。确认沙箱内 Docker 也登录,或配 registry mirror 绕开重复拉取。
sbx diagnose 能查出 429 吗
查不出 429 本身,它检查安装与环境类问题:CLI 二进制缺失、daemon 不可达、版本不匹配、存储目录缺失、认证异常。但它能排掉大量「看着像限流其实是环境坏了」的误判。

京ICP备2024094994号-29