Gated 仓库无权访问：需要登录并同意协议（Llama / Flux 等）

GatedRepoError: 401 Client Error. Cannot access gated repo for url https://huggingface.co/<repo>/resolve/main/<file>. Access to model <repo> is restricted and you are not in the authorized list. Visit https://huggingface.co/<repo> to ask for access.
（注：以上为转述文本，非逐字原文。）

现象与触发场景

常见触发场景：

• 在 Hugging Face 官网没有点同意该模型的使用协议，未进入授权名单
• 本机没有配置 HF token，或 token 已失效/被撤销
• 使用 hf-mirror 等镜像站下载 Gated 仓库（镜像站不支持登录，必须自带 token）
• 仓库本身是私有或已改名，工具报的是 RepositoryNotFoundError 401

根因

• Hugging Face 的 gated repo 需要「账号登录 + 在模型页申请并获得许可」两步，缺任一步服务端都会返回 401，客户端据此抛出 GatedRepoError；为防探测，部分情况返回的是 RepositoryNotFoundError（同样带 401）。
• token 只在网页端登录过、没有传给命令行/脚本进程；huggingface-cli 需要 --token 参数，hfd 需要 --hf_username/--hf_token。
• 国内镜像站出于账号安全不提供登录，所以镜像只能解决「网通不通」，不能解决「有没有授权」。

解决步骤

已按「最可能有效」排序。请从上往下做，每做完一步用「验证」确认，不要一次改五处。

1. 在 Hugging Face 官网完成授权申请
   用浏览器登录 huggingface.co，打开对应模型页，填写并提交使用协议申请，等待状态变为已授权（部分模型是即时通过）。这一步必须在官网完成，镜像站无法代办。
2. 创建 Access Token 并在下载命令里显式传入
   在官网 Settings → Access Tokens 新建一个 read 权限 token，然后在下载时带上。注意不要把自己的 token 贴进公开 issue 或截图里。
   pip install -U huggingface_hub
   huggingface-cli download --token hf_*** --resume-download meta-llama/Llama-2-7b-hf --local-dir Llama-2-7b-hf
   # 使用镜像站下载 gated 仓库时必须自带 token
   HF_ENDPOINT=https://hf-mirror.com huggingface-cli download --token hf_*** --resume-download <repo> --local-dir <dir>
3. 让 ComfyUI 进程拿到 token（环境变量方式）
   在启动 ComfyUI 的环境里设置 HF_TOKEN，使依赖 huggingface_hub 的节点自动携带凭据；Windows 用 setx 后需完全重启 ComfyUI。拿到文件后也可以直接手工下载放进 models 对应目录，彻底避免运行时鉴权。
   setx HF_TOKEN hf_***
   # Linux
   export HF_TOKEN=hf_***

验证是否修好

补充说明

[未核实] 本条 error_text 按 huggingface_hub 的 GatedRepoError 通行英文措辞整理，未逐字取到 ComfyUI 场景的原文堆栈，故标记 error_text_verbatim=false。可核实的相近来源为 ComfyUI_PuLID_Flux_ll issue #30（标题即为 huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error）与 huggingface 官方 HfApi 文档中 GatedRepoError 的定义。

来源

1. [170] （节点仓库 issue）　huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. · Is　https://github.com/lldacing/ComfyUI_PuLID_Flux_ll/issues/30
2. [161] （官方文档）　🤗 HF-Mirror — 常见问题：有些项目需要登录，如何下载？　https://hf-mirror.com/
3. [169] （官方文档）　Hf Api Client — GatedRepoError / RepositoryNotFoundError　https://huggingface.co/docs/huggingface_hub/v0.35.0.rc1/package_reference/hf_api

本条报错提到的节点仓库

下面这些节点仓库的名字出现在本条报错的正文里。这里只说「名字出现过」，没有断定问题就是它引起的； 点进去可以看这个包的用途、适配模型与下载量。

这条报错要用到的东西

按本条报错所属的类别（网络、下载与访问（含国内网络环境））列出站内相关的下载包与板块入口。 它们不是「必须下载才能修好」，而是这一类问题里最常要动到的东西；具体怎么做，以上面的解决步骤为准。

同一类别的其他条目

返回报错库