Claude Code 报出 “Authentication failed” 时,很多人第一反应是删掉 ~/.claude 整个目录重来。这个做法能解决一部分缓存问题,但会把定位线索一起抹掉。我通常按固定顺序处理,每步都留验证方式和回滚边界。
先确认现象,再决定动哪里
当 Claude Code 报出 “Authentication failed” 时,不要立刻删除配置重来。先确认当前使用的是 API Key 还是 OAuth 登录。在终端执行 `echo $ANTHROPIC_API_KEY`,如果变量为空,说明认证信息尚未注入;如果变量值前后有空格,会导致读取失败。同时对比 Claude 控制台中的密钥与本地值是否一致,排除复制时漏字符的情况。这一步能快速将问题范围缩小到认证信息本身,而不是深层配置错误。
需要结合环境确认的一点是:如果常用 OAuth 登录,ANTHROPIC_API_KEY 为空属于正常现象,此时应直接检查 ~/.claude/.credentials.json 是否存在、可读。该文件存在且内容完整,说明凭据没有丢,问题可能出在请求链路。反过来,环境变量里带密钥但开头或结尾有空格时,bash 不会主动修剪,服务端收到的是错误字符串,单看控制台容易漏掉这个细节。
建议的处理顺序
若确认 API Key 无误,可以尝试清除本地缓存并重新认证。Claude Code 的凭据通常存放在用户目录下的 `.claude` 文件夹中,例如 `~/.claude/.credentials.json`。备份该文件后将其删除,再运行 `claude login` 重新走一遍登录流程。如果是团队共享机器,注意区分系统登录用户,避免误删他人配置。重新登录后,用 `claude` 启动一个最小会话,确认是否恢复。
备份这步建议写成命令,而不是手动拖动文件:
cp ~/.claude/.credentials.json ~/.claude/.credentials.json.bak删除凭据后重新登录仍然失败时,把备份恢复回去,并保存终端完整报错输出。删除凭据只能重置认证状态,不能修复网络或系统时间方面的问题,所以建议在确认凭据本身有误之后再执行删除,而不是一开始就做。
网络层拦截和请求链路检查
认证失败也可能是网络层拦截或代理设置导致的。在受控网络环境中,HTTPS 代理会改写请求头,使 Claude Code 携带的 token 失效。可以检查 `http_proxy`、`https_proxy`、`no_proxy` 三个环境变量,确保目标域名 `api.anthropic.com` 没有被错误地排除在代理之外,同时也不要在代理规则中强制对请求进行身份重写。如果无法调整代理,则尝试关闭代理后直接连接,观察报错是否变化,以此区分问题来源。
检查代理变量用一条命令就能看完:
env | grep -i proxy如果输出中 no_proxy 列表没有 api.anthropic.com,请求会走系统代理,一旦代理规则对 HTTPS 做身份重写,请求头里的 token 就可能失效。临时 unset http_proxy https_proxy 后再发起一次认证请求,观察报错是否变化,这比反复重新登录更能说明问题。此处只涉及环境变量层面的排查,不绑定具体代理软件。
权限和系统时间:两个容易被忽略的变量
凭据文件放在 ~/.claude 下时,先运行 ls -la ~/.claude 看所有者和权限位。文件属于 root 或其它用户,当前进程读取时会被拒绝,报错表现与认证失败相同。确认归属后用 chown $(whoami) ~/.claude/.credentials.json 改回当前用户,再重试登录。权限调整只针对 .claude 目录做最小改动,不要对用户主目录执行 chmod -R 777,那会让其它进程也能读到密钥文件。
系统时间偏移是另一类常见原因。token 校验依赖时间戳,本地时钟与标准时间差出几分钟,服务端就可能判定请求无效。先执行 date 查看当前时间,再确认自动时间同步是否开启;服务器使用 NTP 时,检查同步服务是否在运行。容器和虚拟机的时区设置也会影响时间字符串,但最常见的情况仍是时钟未同步,校准后重新发起一次请求即可确认。
验证与回滚
每完成一项调整,都用同一个最小操作验证:新开终端会话,进入空目录,运行 claude 并发送一句最简单的消息,不要直接恢复大型任务,避免会话缓存干扰判断。备份过凭据且确认恢复成功的,把 .bak 文件移到用户目录之外,避免备份文件留在原目录干扰下次排查。
上述步骤都试过仍然失败时,把范围进一步缩小到服务端:在控制台创建一个临时 API Key,在干净终端里用 ANTHROPIC_API_KEY=临时密钥 claude 启动一次。临时密钥只用于确认服务端是否对当前账号有限制,验证完毕后立即吊销,不要把它写进任何配置文件。
后续维护
认证问题解决之后,维护重点放在密钥存放位置和轮换周期上。不要把 API Key 写进全局环境变量,环境变量对当前终端所有进程可见,多人共用的机器上泄露面太大。要写就写在 .bashrc 或 .zshrc 这类私有文件里,并把文件权限收紧到 chmod 600。只要怀疑密钥曾出现在日志、截图或 Git 提交记录中,直接在控制台吊销并重新生成,不要抱着先观察一下的心态继续使用。