Hugging Face 模型已获授权，下载为什么仍报 401 或 403

模型页面已经显示可以访问，Python 下载 config.json 却报 GatedRepoError，或者同一环境里 login() 成功后仍收到 401。先核对程序请求的仓库与它实际使用的身份：浏览器中的批准不会自动传给另一个容器、Notebook 内核或服务进程。

下面使用 huggingface_hub 0.36.0 的接口和令牌优先级说明。Hub 上的访问批准与令牌策略由服务端管理，可能调整；应查看实际返回的错误正文，不能只靠 HTTP 状态码认定原因。

从完整报错中的 repo_id 开始

确认失败的是哪个模型和哪个文件。有些应用加载主模型后，还会下载 tokenizer、guardrail 或其他子模型；主模型获批，不代表这些独立仓库也已经授权。

用同一个用户账号打开那个仓库，完成它要求的协议确认或访问申请。自动批准和人工批准的等待方式不同，模型方也可能撤销授权。处于 pending 或 rejected 时，换一个 token 不会替这个账号取得访问资格。

登录成功，但服务仍用了另一份 token

0.36.0 中 HF_TOKEN 环境变量会覆盖机器保存的 token。更换本地登录凭据后，容器或启动配置里旧的 HF_TOKEN 仍可能被使用。HF_HOME、HF_TOKEN_PATH 的变化也会影响保存凭据的位置。

在真正报错的解释器入口检查变量是否存在和安装位置，不输出 token 的值。下面是诊断片段：

import os
import sys
import huggingface_hub

print("python:", sys.executable)
print("hub:", huggingface_hub.__version__)
print("HF_TOKEN set:", bool(os.environ.get("HF_TOKEN")))
print("HF_HOME:", os.environ.get("HF_HOME"))
print("HF_TOKEN_PATH:", os.environ.get("HF_TOKEN_PATH"))

服务、容器和交互终端可能使用不同配置，检查后在实际入口修正，启动新的进程或内核再验证。不要把真实令牌粘进命令行、代码库或日志；也不要为下载模型申请无关的写权限。

让同一令牌验证身份和文件访问

以下示例假定运行环境已通过受保护的配置提供 HF_TOKEN，repo_id 替换为报错里的实际模型仓库。它会访问 Hub 并下载一个配置文件，不能在无网络的离线环境中使用：

import os
from huggingface_hub import HfApi, hf_hub_download

token = os.environ["HF_TOKEN"]
repo_id = "organization/model-name"

identity = HfApi().whoami(token=token)
print("account:", identity["name"])

path = hf_hub_download(
    repo_id=repo_id,
    filename="config.json",
    token=token,
)
print("downloaded:", path)

账号输出只能证明这次 whoami 使用的身份，不能证明该账号有模型权限；后面的文件请求才核对目标资源访问。若失败文件不是 config.json，用真实文件名检查。成功后让 tokenizer 与模型加载沿用同一套凭据配置，避免一个调用显式传 token，另一个调用又回到旧环境变量。

fine-grained 权限也要覆盖目标模型

令牌所属账号应是获批账号，令牌本身还要具有所需的读取范围。fine-grained token 可能只覆盖另一个仓库；某些组织还要求令牌审批或只接受 fine-grained token。核对目标仓库的读权限、gated 资源相关授权及组织策略，不默认扩大到所有仓库。

401 可以出现在缺少、无效或被覆盖的凭据路径；403 也可能涉及访问批准、令牌范围、组织策略或其他访问限制。将服务端错误正文与账号、仓库、权限检查放在一起判断，比反复重新登录更可靠。

验收时不仅要下载一份公开配置，还要让原应用在实际运行环境中读取先前失败的受限文件。保留修改前的启动配置；回退时恢复配置，不将已经撤销或失效的旧 token 当作可用恢复凭据。