Claude Code 鉴权 token 过期怎么刷新?

文章导读
遇到 Claude Code 提示鉴权过期,我一般是先确认现象,而不是马上重新登录。终端里出现“Authentication expired”或“Unauthorized”时,先排除网络问题,再看本地日志。
📋 目录
  1. 壹 重新触发 OAuth 登录
  2. 贰 使用 API 密钥时如何刷新
  3. 叁 容易踩的坑:凭据冲突
  4. 肆 刷新后怎么验证
  5. 伍 风险与后续维护
A A

遇到 Claude Code 提示鉴权过期,我一般是先确认现象,而不是马上重新登录。终端里出现“Authentication expired”或“Unauthorized”时,先排除网络问题,再看本地日志。

当Claude Code返回类似“Authentication expired”或“Unauthorized”的报错,且网络连接正常时,通常是鉴权token已经过期。可以先查看本地日志文件(如`~/.claude/logs`下对应会话记录),确认是否出现`access_token expired`或`invalid_token`等关键字。若此前从未成功登录,则属于配置缺失而非过期,需要区分处理。检查`~/.claude`目录下是否存在缓存的凭据文件,文件存在但认证仍然失败,基本可以判定是token过期。

日志里的关键字能帮你区分两类问题:`invalid_token` 表示 token 本身失效,`expired` 则明确是过期。如果 `~/.claude` 下根本没有凭据文件,那次登录可能从未成功,或者是配置被清理过,不是刷新能解决的。

重新触发 OAuth 登录

对于使用默认 OAuth 方式登录的用户,刷新 token 通常不需要手动改文件。

最直接的刷新方式是重新触发登录流程。在终端直接运行`claude`命令,当Code检测到现有token失效时,通常会自动唤起浏览器进入OAuth授权页面;如果是在无桌面环境下,可运行`claude --login`强制启动登录。授权完成后,新token会写入本地配置目录。注意刷新后需要重启Claude Code进程,否则当前会话仍会使用旧的token调用API。

`claude --login` 在无桌面环境里会输出一个授权链接,复制到本地浏览器打开,完成授权后把回调链接粘回终端。这个过程不涉及 API 密钥,所以如果之前用的是 OAuth,这里不需要担心密钥泄露。

Claude Code 鉴权 token 过期怎么刷新?

使用 API 密钥时如何刷新

如果走的是 API 密钥而不是 OAuth,刷新的地方就在环境变量。

先确认 `ANTHROPIC_API_KEY` 在哪个配置文件里设置,常见是 `~/.bashrc` 或 `~/.zshrc`。用新密钥替换旧值后,执行 `export ANTHROPIC_API_KEY=新密钥` 让当前 shell 生效。注意不要直接在命令行写下密钥,这样会进 shell 历史,建议用 `read -s` 或者密钥管理工具注入。

可以用下面这行命令快速定位配置文件和当前生效值:

grep -n "ANTHROPIC_API_KEY" ~/.bashrc ~/.zshrc 2>/dev/null; env | grep ANTHROPIC_API_KEY

注意,`export` 命令只对当前终端进程生效。如果想持久化,需要把新值写进对应的 rc 文件,然后 `source ~/.bashrc` 或重新打开终端。

容易踩的坑:凭据冲突

不要同时设置`ANTHROPIC_API_KEY`环境变量和本地登录凭据,因为Claude Code会优先选择其中一种,两种同时存在时可能让旧token继续被引用,造成“刷新了但没用”的假象。删除本地凭据文件(如`~/.claude/credentials.json`)前务必备份,避免误删团队级配置。在CI/CD等自动化环境中,不要依赖手动刷新,应改用短时密钥并配合密钥轮换机制。

我遇到过几次“刷新后仍然报错”的情况,最后都是环境变量里残留了旧 key。Claude Code 优先读环境变量,本地登录的 token 被晾在一边,所以你无论重新登录多少次,调用的还是旧 key。处理方式是先清掉环境变量,或者反过来把本地凭据删掉,只留一种认证方式。

Claude Code 鉴权 token 过期怎么刷新?

刷新后怎么验证

刷新成功不代表立刻可用,建议按顺序确认两步:

  1. 运行 claude --version,确认程序能正常启动,没有解析或配置加载错误。
  2. 启动一个极简对话请求,直接输入一句“hi”并回车,看是否返回正常响应。

如果新 token 立即再次失效,先检查系统时钟是否与 NTP 同步。偏差过大时,JWT 校验会失败,这时候 token 本身没问题,是时间基准不对。另外也要排查网络中间设备是否篡改了认证请求,这类问题在跳过那些设备后往往消失。

风险与后续维护

刷新 token 不会中断已经启动的任务,但正在运行的长任务如果跨越 token 过期节点,仍可能在下一次 API 调用时失败。重新认证后,原先通过企业 SSO 申请的临时角色权限可能需要重新审批,这类权限一般绑定用户身份而非 token。

如果 token 频繁过期,不要只想着手动刷新。建议查看所在组织的 IAM 策略或 API Key 的权限范围,确认是否存在过短的 TTL 配置。一个需要留意的点是,很多团队会把 token 过期时间设得比正常会话时间短,导致长任务频繁中断,这时更适合调整服务端策略,而不是每次手动处理。

总的处理顺序是:先看日志和凭据文件确认 token 确实过期,再按当前认证方式选择 OAuth 重新登录或更新环境变量,然后验证命令和对话请求。遇到反复失效时,把注意力从“刷新动作”转向“为什么刷新无效”,从环境变量冲突、系统时间和网络策略三个方向排查。