ComfyUI 模型下载总报 401：FLUX 与 SD3.5 门控仓库授权与目录配置

浏览器里能打开 FLUX.1 [dev] 或 Stable Diffusion 3.5 Large 的模型页，点了下载也能下，但一换到命令行或者 ComfyUI 里的下载节点，就弹出一大段红字：401 Client Error: Unauthorized for url: https://huggingface.co/black-forest-labs/FLUX.1-dev/resolve/main/flux1-dev.safetensors。很多人第一反应是查代理、换镜像、关防火墙，折腾半天没结果。其实这条报错跟网络通不通关系不大——服务器已经收到你的请求了，只是它认为“你没有权限拿这个文件”。这两个仓库都是 Hugging Face 上的门控（gated）仓库，下载前必须先完成一次授权动作，再让本地工具带着凭证去取文件。

先分清 401、403 和 404

这三种状态码在下载模型时表现完全不同，判断错了就会往错误方向排查：

所以“401 不是网络问题而是授权问题”这句话要补一句：401 是身份没带上，403 是身份带上了但没被批准。两个都属于授权环节，重装 CUDA、换下载器都解决不了。顺便说，用浏览器能下载是因为浏览器里带着你已登录的 Cookie，而命令行工具是另一套独立的凭证体系。

第一步：在模型页接受许可证

这是唯一无法用命令替代的一步，必须在网页上人工完成。

1. 登录 Hugging Face 账号，进入 black-forest-labs/FLUX.1-dev 或 stabilityai/stable-diffusion-3.5-large 的模型页。
2. 页面顶部会有一条门控提示条，写着需要同意许可才能访问，右侧是 “Agree and access repository” 一类的按钮。
3. 点击后通常要填一个简短表单（用途、所在地区等），提交即可。FLUX.1 [dev] 和 SD3.5 Large 一般是即时通过，少数仓库需要等待人工审核。
4. 状态变成 “You have been granted access to this repository” 才算真正拿到权限。如果按钮还在，就是没生效，刷新页面再看。

两个许可证的性质值得提前知道：FLUX.1 [dev] 是非商业许可，商用需要另行向 Black Forest Labs 申请授权；SD3.5 使用 Stability 社区许可证，年收入低于 100 万美元的商业使用免费，超过这条线要单独谈。许可证判断放在下载之前，比事后换模型省事得多。

另外，如果你用的是团队或组织的 token，管理员可能限制了可访问的仓库范围，这种情况下接受许可证也没用，需要让管理员把该仓库加进允许列表。

第二步：配置 token 并完成登录

授权通过后，需要一个能代表你身份的 token。在账号的 Settings → Access Tokens 里新建一个，类型选 Read 就够，不要图省事建 Write token 到处放。

新版 huggingface_hub（0.34 起）把命令行统一成了 hf，老命令 huggingface-cli 仍可用但会提示弃用：

# 新版 CLI
pip install -U huggingface_hub
hf auth login          # 按提示粘贴 read token
hf auth whoami         # 确认当前身份，能打印用户名就说明登录成功

# 老版本仍可这样写
huggingface-cli login
huggingface-cli whoami

登录成功后 token 会被写进本地缓存目录（默认 ~/.cache/huggingface/token，Windows 在用户目录下的 .cachehuggingfacetoken）。ComfyUI 里那些基于 huggingface_hub 的下载节点读的就是这里，所以先在系统里登录一次，往往能顺带解决节点里的 401。

不适合做交互登录的场景（容器、Docker、CI、远程服务器），直接用环境变量：

export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxx
# Windows PowerShell
# $env:HF_TOKEN = "hf_xxxxxxxxxxxxxxxxxxxxxxxx"

注意这个变量不要写进会被提交到 git 的脚本里，也不要在多人共用的机器上留在 .bashrc。

第三步：把文件放到 ComfyUI 认的目录

下载这一步最容易出错的不是命令本身，而是“文件该放哪”。FLUX.1 [dev] 和 SD3.5 Large 在 ComfyUI 里的组织方式并不一样，搞混了就会出现“文件明明在硬盘上，节点里却选不到”。

FLUX.1 [dev] 的文本编码器来自 comfyanonymous/flux_text_encoders 仓库，它是公开的，不需要授权也不需要 token。显存紧张时选 t5xxl_fp8_e4m3fn 版本，质量损失很小。

下载命令示例：

cd ~/ComfyUI

# FLUX.1 [dev] 扩散模型本体
hf download black-forest-labs/FLUX.1-dev flux1-dev.safetensors 
  --local-dir models/diffusion_models

# FLUX.1 [dev] 的 VAE
hf download black-forest-labs/FLUX.1-dev ae.safetensors 
  --local-dir models/vae

# SD3.5 Large 一体化权重
hf download stabilityai/stable-diffusion-3.5-large sd3.5_large.safetensors 
  --local-dir models/checkpoints

这里有个非常隐蔽的坑：--local-dir 会保留文件在仓库里的相对路径。比如你去 SD3.5 仓库里单独下一个 text_encoders/clip_l.safetensors，并指定 --local-dir models/text_encoders，最终落盘位置会变成 models/text_encoders/text_encoders/clip_l.safetensors——多套了一层同名目录。ComfyUI 只扫描指定目录的顶层，多套的这一层会导致文件“消失”。遇到这种情况，手动把文件挪上一层即可。

如果你的模型统一放在别的硬盘或 NAS 上，别用软链接硬凑，用 ComfyUI 根目录下的 extra_model_paths.yaml 声明额外路径更稳，示例配置里已经有现成的段落，改 base_path 和下面的子目录映射就行。

第四步：确认 ComfyUI 真的认到了模型

下载完先核对两件事，再去看界面：

# 文件大小是否合理，远小于预期说明下载中断
ls -lh models/diffusion_models/ models/checkpoints/

# 检查有没有残留的未完成文件
find models -name "*.incomplete" -o -name "*.part"

flux1-dev.safetensors 应在 20 GB 以上，sd3.5_large.safetensors 在 15 GB 左右。有 .incomplete 文件说明上次下载被中断，删掉重下，别指望 ComfyUI 能读半个文件。

然后重启 ComfyUI（或点界面上的 Refresh 刷新节点定义），按模型类型找对应的加载节点：

• FLUX.1 [dev]：用 Load Diffusion Model 节点，下拉框里应出现 flux1-dev.safetensors；注意它不会出现在 CheckpointLoaderSimple 里，因为它只是扩散模型，不含 VAE 和文本编码器。
• SD3.5 Large：用 Load Checkpoint 节点，下拉框里应出现 sd3.5_large.safetensors。
• 文本编码器和 VAE 分别在 Load CLIP、Load VAE 节点里确认。

常见路径错误速查

• 把 flux1-dev.safetensors 丢进 models/checkpoints：CheckpointLoaderSimple 列表里能看到，但加载会报缺 VAE、缺 CLIP 之类的错误。它属于 diffusion_models。
• 只下了扩散模型：报错信息里出现 clip_l、t5xxl 或 ae.safetensors 找不到，就是配套文件没下。
• 目录名拼错或多层嵌套：diffusion_model、diffusion-models、unet 都不是正确名字，当前版本用 diffusion_models。
• 用 root 或 sudo 下载：文件属主变成 root，普通用户启动的 ComfyUI 读不到，表现同样是“下拉框为空”。用 ls -l 看一眼属主。
• 文件名被改过：ComfyUI 靠扩展名识别，flux1-dev(1).safetensors 能读，flux1-dev.safetensors.txt 或去掉扩展名就不行。
• 网盘同步目录里的占位文件：显示有文件但大小为 0，属于同步未落地，不算下载成功。

验证通过之后

判断标准很简单：四个加载节点里都能在下拉框中选中对应文件，队列跑一次不报缺文件或权限错误，就说明授权、下载、目录、识别这条链路通了。此时再去看采样步数、guidance、分辨率这些参数才有意义——那属于另一个话题，和 401 无关。

如果仍然报 401，按这个顺序回退检查：hf auth whoami 是否打印出正确用户名 → 模型页是否显示已获得访问权限 → 当前 shell 里是否存在覆盖性的 HF_TOKEN 环境变量 → 是否用了组织 token 且缺少仓库白名单。四步走完，问题基本就定位了。