新手必藏｜Claude Code 常见报错清单：照着检查就能快速定位

小海AI编程

352人浏览 · 2026-07-28 10:21:48

小海AI编程 · 2026-07-28 10:21:48 发布

Claude Code 已经安装完成，却找不到 claude 命令、提示 Invalid API Key，或者修改 settings.json 后没有生效？

先别反复重装。

本文按照：安装与 PATH → 配置文件 → API 与模型

三个层级排查，直接根据报错现象找到对应解决方法。

如果还没有安装 Claude Code，建议先完成上一篇安装配置教程；本文只解决安装后的命令、API 和配置问题。

📌 一、快速定位

先对照下面的表格，判断问题大致出在哪一层。

报错现象	问题位置	优先检查
找不到 `claude` 命令	安装或 PATH	安装目录、环境变量
`claude --version` 异常	安装状态	终端、安装方式
PowerShell 脚本无法执行	执行策略	PowerShell 报错提示
提示 `Invalid API Key`	密钥或接口地址	`settings.json`
修改配置没有变化	文件路径或 JSON 格式	配置文件位置
仍然调用旧模型	模型配置	模型 ID
启动后请求无响应	网络或接口	网络、API 地址

推荐排查顺序：运行版本命令 → 检查 PATH → 核对配置文件 → 检查 API → 确认模型

⚠️ 最关键的判断标准：

claude --version 能正常显示，说明 Claude Code 已经安装成功。后续出现 API、配置或模型问题，不需要重新安装。

⚠️ 二、安装与命令报错

1. 找不到 `claude`

报错现象

运行下面任意命令时，终端提示无法识别：

claude

claude --version

常见原因

Claude Code 没有安装完成；
安装目录未加入 PATH；
修改 PATH 后没有重新打开终端。

解决方法

Windows 用户重点检查 Claude Code 安装目录是否已加入用户变量中的 Path。

参考路径：

C:\Users\你的用户名\.local\bin

添加顺序：系统属性 → 环境变量 → 用户变量中的 Path → 编辑 → 新建 → 填入安装路径

保存后关闭当前终端，再重新打开 PowerShell。

macOS、Linux 用户安装完成后，也需要重新打开终端再验证。

验证结果

claude --version

能够显示版本号，说明安装和命令环境已经恢复正常。

2. PowerShell 脚本报错

报错现象

通过 PowerShell 安装时，提示脚本无法执行或受到执行策略限制。

常见原因

Windows PowerShell 执行策略阻止了安装脚本运行。

解决方法

以管理员身份打开 PowerShell，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

然后重新执行安装命令：

irm https://claude.ai/install.ps1 | iex

验证结果

安装结束后重新打开终端，运行：

claude --version

能显示版本号即可停止重复安装。

3. 版本命令异常

如果 claude --version 没有正常返回结果，可以依次检查：

是否已经完成 Claude Code 安装；
Windows 是否正确配置 PATH；
是否关闭并重新打开终端；
Windows 用户的 Git 是否正常。

验证 Git：

git --version

如果 Git 和 PATH 均正常，但终端仍无法识别 claude，再考虑重新执行对应系统的安装命令。

⚙️ 三、配置文件报错

Claude Code 已经可以正常运行，但出现 API、配置或模型问题，重点检查 settings.json。

1. 确认配置路径

系统	配置文件路径
Windows	`C:\Users\用户名\.claude\settings.json`
macOS	`~/.claude/settings.json`
Linux、WSL	`~/.claude/settings.json`

如果文件不存在，可以在对应目录新建 settings.json。

macOS、Linux 和 WSL 用户也可以运行：

vim ~/.claude/settings.json

2. 核对标准配置

完整配置只需保留一份：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
    "ANTHROPIC_BASE_URL": "https://api.letaicode.cn/claude",
    "ANTHROPIC_MODEL": "claude-fable-5",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-fable-5"
  }
}

保存前完成下面的检查：

检查项	正确状态
配置路径	位于对应系统的 `.claude` 目录
文件名	`settings.json`
API 密钥	已替换为真实密钥
密钥类型	与 Claude Code 接口匹配
API 地址	`https://api.letaicode.cn/claude`
模型 ID	拼写完整、没有多余空格
JSON 格式	引号、逗号、大括号完整
配置刷新	保存后重新打开终端

3. `Invalid API Key`

报错现象

Invalid API Key · Please run /login

常见原因

ANTHROPIC_AUTH_TOKEN 没有替换；
API 密钥复制不完整；
密钥类型不匹配；
API 地址填写错误；
JSON 格式损坏。

解决方法

重点核对：

"ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌"

以及：

"ANTHROPIC_BASE_URL": "https://api.letaicode.cn/claude"

将示例令牌替换为真实密钥，保存配置后关闭当前终端，再重新启动 Claude Code。

验证结果

进入项目目录并运行：

claude

如果能够正常进入交互界面并发送请求，说明 API 配置已经生效。

4. `settings.json` 不生效

报错现象

修改配置后，Claude Code 仍然读取旧设置。

常见原因

配置文件保存到了错误目录；
文件名或扩展名错误；
JSON 格式不完整；
修改后没有重新打开终端。

解决方法

依次确认：

文件位于对应系统的 .claude 目录；
文件名确实为 settings.json；
配置项名称没有修改；
JSON 引号、逗号和大括号完整；
保存后关闭并重新打开终端。

💡 只要 claude --version 正常，配置不生效就与安装无关，不需要重新安装 Claude Code。

5. 模型没有切换

报错现象

已经修改模型，但启动后仍然调用原来的模型。

常见原因

修改了错误的配置项；
模型 ID 拼写错误；
模型 ID 前后存在空格；
配置没有重新加载。

两个模型配置项的作用：

配置项	作用
`ANTHROPIC_MODEL`	指定主模型
`ANTHROPIC_SMALL_FAST_MODEL`	指定快速模型

如果只切换主模型，修改这一行即可，比如：

"ANTHROPIC_MODEL": "claude-opus-4-8"

修改完成后保存文件，重新打开终端并启动 Claude Code。

🌐 四、请求没有响应

报错现象

Claude Code 能正常启动，但发送请求后长时间没有响应。

常见原因

当前网络连接不稳定；
API 地址填写错误；
API 密钥类型不匹配；
模型 ID 填写错误；
新配置尚未重新加载。

解决方法

按照下面的顺序检查：

确认当前网络连接正常；
核对 API 密钥是否为对应类型；
检查 API 地址：

https://api.letaicode.cn/claude

检查模型 ID 是否填写正确；
保存配置并重新打开终端；
再次进入项目启动 Claude Code。

可以通过下面的结果快速区分问题：

检查结果	问题位置
`claude --version` 无法运行	安装或 PATH
能显示版本，但提示 API Key 错误	密钥或 API 地址
能启动，但仍使用旧模型	模型配置
配置正确，但请求无响应	网络或接口连接