Claude Code 常见问题排查

本文面向通过 RootFlowAI 使用 Claude Code CLI 或编辑器扩展的用户，按安装、配置、认证、额度和网络问题给出排查顺序。首次接入请先完成安装与配置教程。说明核对于 2026-09-19，客户端更新后的行为以文末官方资料为准。

排查从当前版本、实际地址和凭据来源开始。修改设置前备份涉及的文件，保留聊天记录、MCP、插件和权限配置；无需把删除整个 .claude 目录作为常规修复步骤。

先做三项检查

1. 在实际运行 Claude Code 的环境执行 claude --version，记录版本与安装方式。Windows、WSL、Remote SSH 和本机编辑器可能运行不同的客户端。
2. 进入 Claude Code 执行 /status，在本机核对 Anthropic base URL 是否为 https://api.rootflowai.com，并查看凭据来源。不要把含凭据、个人路径或账户信息的完整截图直接发给他人。
3. 在账户中心核对令牌状态、分组、模型权限、有效期、额度限制及 IP 白名单。RootFlowAI 网关接入通常使用 ANTHROPIC_AUTH_TOKEN，配置方法见安装教程。

claude --version 能确认命令可执行，/status 能帮助核对当前配置；它们不能证明目标模型或工具调用一定成功。需要检查安装和配置诊断时，可按官方指引运行 claude doctor，分享诊断结果前先脱敏。

按症状定位

命令不可用与版本冲突

macOS / Linux

在需要使用 Claude Code 的终端查看命令位置：

command -v claude
which -a claude

没有输出时，先检查安装是否完成及安装目录是否已加入 PATH。原生安装通常位于 ~/.local/bin/claude；npm 和 Homebrew 的路径可能不同。按安装教程选择对应方式，并在安装或持久化 PATH 更新后重新打开终端。

出现多个位置时，确认当前使用哪一份，再按官方说明处理重复安装。不要直接清理全部 npm 缓存或 Claude 用户数据来替代定位。

Windows PowerShell

Get-Command claude -All -ErrorAction SilentlyContinue
where.exe claude

原生安装通常位于 %USERPROFILE%\.local\bin\claude.exe。确认安装器已完成、该目录位于用户 PATH，并重新打开终端。仅安装 VS Code 扩展不会自动在独立终端中提供 claude 命令。

在 WSL 中运行时，按 Linux 环境检查；在 Remote SSH 中运行时，检查远程主机上的安装与配置。

PowerShell 提示禁止运行脚本

如果错误明确指向 npm.ps1 或 npm 安装生成的 claude.ps1，可以先使用同一安装提供的 .cmd 启动器：

npm.cmd --version
claude.cmd --version

只有对应 npm 启动器存在时才适用。原生安装使用 claude.exe，不依赖这些 .ps1 启动脚本；需要切换安装方式时按安装教程处理。

执行策略由个人或组织管理。只有确认需要使用 PowerShell 脚本启动器、并了解本机策略后，才按官方脚本限制说明调整合适的范围；受管设备应联系管理员。不要把全局放宽执行策略作为所有报错的通用步骤。

地址、环境变量与设置冲突

只检查变量是否设置

下面的命令只显示变量是否有非空值，不打印密钥。它们只检查当前进程环境，不会自动读取 Claude 的用户/项目设置文件，也不能验证凭据是否有效。

macOS / Linux（Bash 或 zsh）：

for name in ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY; do
  if [ -n "$(printenv "$name")" ]; then
    printf '%s: 已设置（值已隐藏）\n' "$name"
  else
    printf '%s: 未设置或为空\n' "$name"
  fi
done

Windows PowerShell：

foreach ($name in @("ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY")) {
    $value = [Environment]::GetEnvironmentVariable($name, "Process")
    $state = if ([string]::IsNullOrEmpty($value)) { "未设置或为空" } else { "已设置（值已隐藏）" }
    "{0}: {1}" -f $name, $state
}

运行时关闭 shell 跟踪或终端录制中可能记录变量值的调试功能。不要用输出全部环境变量的命令收集支持材料，也不要在公开日志中启用带认证请求的详细跟踪。

按实际来源修改

在本机检查以下位置是否存在旧地址、重复凭据或冲突模型配置：

设置优先级与具体配置来源有关，不能只看一个 JSON 文件推断最终结果。修改前在本机安全位置备份涉及的文件，每次只改已确认冲突的字段，再重新启动会话，用 /status 核对。备份可能含密钥，也不要上传或放进仓库。

在当前终端直接设置变量后，可从同一个终端启动 Claude；修改持久化环境或 shell 配置后，需要让实际启动环境重新加载。无需对所有系统机械执行 source ~/.zshrc。

401、认证冲突或一直要求登录

1. 确认正在使用 RootFlowAI 创建的有效令牌，且实际地址为 https://api.rootflowai.com。
2. 按安装教程核对 ANTHROPIC_AUTH_TOKEN，并检查是否同时保留了其他服务的 ANTHROPIC_API_KEY、凭据助手或 CC Switch Provider。先确认来源，再修改具体配置。
3. 首次启动时，交互式 CLI 的项目级 env 设置可能尚未加载。按官方网关指引，将接入配置放在当前终端或用户级设置中，再检查 /status。
4. 令牌被撤销、泄露或过期时才需要相应替换或续期；普通充值不要求自动更换 Key。

/logout 处理登录状态，不能修复所有网关 Key、权限或余额问题。需要验证地址与认证时，使用免费模型列表检查；列表成功仍不等于模型生成一定成功。

403、地区限制与网络错误

先记录报错阶段：下载客户端、厂商账号登录、免费检查，还是实际模型请求。这些步骤可能访问不同的服务。

• 下载或厂商登录报错：按官方安装与登录排查核对网络、系统时间、证书和服务可用地区。
• 网关调用返回 JSON 错误：结合错误体核对令牌限制、模型分组、权限和请求 ID，不能只凭 403 判断余额。
• 返回 HTML 的 403、网关未收到请求或 TLS 错误：可能涉及网络代理、证书、防火墙或接入层。向支持提供脱敏证据，由对应维护方定位；不要通过关闭证书校验来掩盖问题。

可先做不带 Key 的服务入口检查：

curl --silent --show-error --fail \
  --connect-timeout 5 --max-time 10 \
  https://api.rootflowai.com/api/status

预期为 HTTP 200 且 JSON 中 success 为 true。这只能说明本次请求能到达服务入口，不验证 Key、余额、模型权限或模型首字延迟。更多线路与余额检查见CC Switch 教程。

余额不足、404 与模型不可用

遇到余额错误时，先用 /status 确认请求确实发往 RootFlowAI，再核对账户余额、Key 限额与消费日志。账户有余额并不保证每个 Key 仍有可用额度或目标模型权限；清空本地聊天和配置不会增加余额。

遇到 404 时，检查 Base URL 是否误填了门户域名、完整接口路径或重复的 /v1。Claude Code 应使用 https://api.rootflowai.com，客户端负责请求 /v1/messages。

遇到模型不存在或无可用渠道时，按价格页核对完整模型 ID、分组和令牌权限。不要假设未知模型会自动替换为另一款模型。协议选择和错误含义见API 参考，额度单位见计费说明。

Windows Shell 与编辑器差异

如果旧版客户端提示必须安装 Git Bash，先核对版本和安装方式。当前官方 Windows 客户端支持 Git Bash 或 PowerShell 工具；特殊环境、策略或旧版本仍可能需要单独配置，参见官方 Windows 说明。

终端能用而 VS Code/Cursor 扩展不能用时，检查编辑器用户设置中的 claudeCode.environmentVariables，按安装教程配置地址和凭据。编辑器不一定继承当前终端变量；Remote SSH、WSL 与本机扩展也可能读取不同环境。Claude 桌面 App 另有配置流程，不能直接套用扩展设置。

超时、429 与 5xx

先查看服务状态，保留调用时间、模型、请求 ID 与脱敏错误。429 应结合错误类型和 Retry-After 等信息降低频率或并发；临时错误采用有上限的退避，不要立即无限重试。

客户端超时不能单独证明服务端未执行或未计费。重新提交前，核对消费记录和任务是否已产生结果；自动重试或重新运行包含写文件、外部工具的任务时，也要检查原操作是否已经完成。

联系支持时提供什么

提供操作系统、运行环境、Claude Code 版本、安装方式、报错阶段、时间、模型、分组和请求 ID。错误消息保留定位所需信息，遮盖 Key、认证头、导入链接、私人文件路径与提示内容。

配置截图只保留相关字段的脱敏结果；不要上传整个 .claude 目录、原始配置备份或完整环境变量列表。可从账户支持反馈问题。

官方参考

• 安装与登录故障排查
• 配置诊断
• 设置文件与优先级
• LLM 网关连接与认证