AI Agent / 系统课时

排查安装与认证问题

排查安装与认证问题

这一节建立一条固定诊断链:先判断 shell 是否能找到正确的 claude 可执行文件,再核对版本与安装冲突,随后检查 claude doctor 的诊断结果,最后处理登录、凭据优先级和网络问题,避免反复重装却没有定位根因。

学习目标

  • 区分“命令不可用”“路径指错”“版本冲突”和“认证失败”
  • 使用版本、PATH 与诊断命令收集可复现证据
  • 按凭据、网络、账户权限的顺序修复登录问题

先确认命令到底指向哪里

安装成功但出现 command not found,通常应先检查 PATH,而不是立即重装。Claude Code 的当前官方文档还建议在能找到命令后用 claude --version 验证版本,并用 claude doctor 做只读安装与配置诊断。:contentReference[oaicite:0]{index=0}

macOS 或 Linux 可以一次收集路径、重复安装和诊断信息:

bash
printf 'resolved: '
command -v claude || true
which -a claude || true
if command -v claude >/dev/null 2>&1; then
  claude --version
  claude doctor
fi

预期输出

text
resolved: /home/<USER>/.local/bin/claude
/home/<USER>/.local/bin/claude
<VERSION> (Claude Code)
<VALUE>

实际用户名、版本和诊断内容可能不同。若 resolved: 后没有路径,先修 PATH;若 which -a claude 返回多个位置,再排查旧的 npm、Homebrew 或其他安装是否抢在当前版本之前。Windows 可用 where.exe claude 完成同类检查。官方当前安装路径说明中,原生安装默认位于 macOS/Linux 的 ~/.local/bin/claude 或 Windows 的 %USERPROFILE%\.local\bin\claude.exe。:contentReference[oaicite:1]{index=1}

Claude Code 安装与认证故障定位流程

修复 PATH 与版本冲突

如果原生安装文件存在但 PATH 没包含 ~/.local/bin,可以先在当前 shell 临时补上,再验证版本。确认有效后,再把同样设置写入当前 shell 的启动文件。

bash
export PATH="$HOME/.local/bin:$PATH"
claude --version

预期输出

text
<VERSION> (Claude Code)

若补 PATH 后版本仍不是预期版本,优先看 which -a claude 的第一项,因为 shell 实际执行的是最先匹配的路径。多个安装来源并存容易造成“更新成功但版本没变”;官方排障页也建议保留一个安装来源,并清理不再使用的旧安装。:contentReference[oaicite:2]{index=2}

登录失败先看认证来源

能启动 CLI 但模型请求失败时,先在 Claude Code 会话中运行 /status,确认当前使用的是订阅 OAuth、API key、云厂商凭据还是其他配置。Claude Code 存在凭据优先级;例如已设置且被批准使用的 ANTHROPIC_API_KEY 可以覆盖订阅登录,所以“浏览器已经登录成功”并不保证实际请求使用的是该账号。:contentReference[oaicite:3]{index=3}

不要直接打印密钥值。只列出相关环境变量名称即可:

bash
env | awk -F= '/^ANTHROPIC_/ {print $1}'

预期输出

text
ANTHROPIC_API_KEY
<VALUE>

如果这里出现了你不打算使用的旧凭据,先从当前 shell 和启动文件中移除它,再重新启动 Claude Code。若你本来就通过 API key、Bedrock、Google Cloud 或 Microsoft Foundry 工作,则不要删除对应变量,而应继续检查该凭据本身是否有效。

重置登录并区分权限问题

原因不明确的 OAuth 故障,可以在 Claude Code 内执行 /logout,退出后重新运行 claude 完成登录;令牌过期时也可以使用 /login 重新认证。官方排障文档同时指出,远程终端或粘贴回调有问题时可用 claude auth login 作为替代入口。:contentReference[oaicite:4]{index=4}

bash
claude auth login

预期输出

text
<AUTHORIZATION_URL_OR_LOGIN_PROMPT>

如果重新认证后仍返回 403,就不要继续清缓存或重装二进制。此时重点检查订阅是否有效、Console 账户是否具备 Claude Code/Developer 权限,以及公司代理是否拦截请求;这些都属于“命令和登录流程正常,但服务端拒绝访问”的范围。:contentReference[oaicite:5]{index=5}

最终判断应落到证据上:命令解析到唯一且正确的可执行文件、版本符合预期、claude doctor 没有未处理的关键告警、/status 显示预期认证来源,并且一次真实请求能够成功完成。只有这条链中的哪一环失败,才修哪一环。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查安装与认证问题

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通