Claude Code 常见报错怎么查：连不上、401、模型不可用、配置不生效

这篇教程解决一个问题：Claude Code 报错了，或者装好了却不按你配的来，怎么最快找到原因。

先分清是哪一类，查的地方完全不同：

现象	属于	跳到
装不上，或者装完提示找不到 claude 命令	安装	第一类
能启动，一发消息就报 API Error、Not logged in、模型不可用	请求	第二类
能正常对话，但 CLAUDE.md、hook、MCP 服务器、权限规则不起作用	配置	第三类

第二类和第三类里的报错，本站都实际复现过，下面给的是原文。

实测环境
日期	2026-10-12
版本	Claude Code 2.1.296
系统	Ubuntu 24.04
连接方式	通过酷站AI 中转站，不是直连官方
复现的办法	用环境变量 CLAUDE_CONFIG_DIR 另指一个配置目录，里面放假的接口地址和假的 key，不碰真实的配置

先跑一次自查

不知道从哪查起，先在终端里运行（不是在 Claude Code 里面）：

claude doctor

它不启动会话，只打印安装和设置的诊断，Claude Code 起不来的时候也能用。正常环境下的输出（节选）：

Claude Code doctor
Running: native (2.1.296)
Platform: linux-x64
Path: /home/ccdemo/.local/share/claude/versions/2.1.296
Config install method: native
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Managed settings (remote): not fetched — not available with a custom ANTHROPIC_BASE_URL
Organization policy: not fetched with a custom ANTHROPIC_BASE_URL
Remote Control
- Not connected to the Anthropic API (api.anthropic.com)
- Not signed in to claude.ai
- claude.ai subscription auth not active
No installation issues found.

通过中转站用的读者注意：Managed settings: not fetched、Not signed in to claude.ai、Remote Control 下面那几行，都是因为设了自定义的接口地址，属于正常情况，不是故障。要看的是最后一行有没有 No installation issues found，以及中间有没有 Invalid settings 这样的段落。

已经在会话里的话，三个命令最常用：

命令	看什么
/status	现在用的是哪个接口地址、哪种凭据、哪些设置文件在生效
/context	上下文里实际加载了什么，CLAUDE.md 在不在
/doctor	一次完整的体检，下面单独讲

第一类：装不上、找不到命令

这一类没有实测，按官方文档整理。安装的完整步骤见安装 Claude Code。

你看到的	原因	怎么办
command not found: claude（Windows 上是“不是内部或外部命令”）	装上了，但安装目录不在 PATH 里	把安装目录加进 PATH，重开一个终端
syntax error near unexpected token '<'，或者报错里引了一段 HTML	下载到的不是安装脚本，是一个网页。通常是网络把请求拦了或者跳转了	检查网络和代理。国内的网络环境下最常见的就是这一条
curl: (22) The requested URL returned error: 403	同上，下载被拒绝	同上
TLS connect error、Could not create SSL/TLS secure channel	TLS 握手失败	更新系统的 CA 证书；Windows PowerShell 5.1 要先启用 TLS 1.2
Failed to fetch version from downloads.claude.ai	连不上下载服务器	检查网络；需要代理的话，运行安装命令之前设好 HTTPS_PROXY
The connection dropped while downloading the update	下载到一半断了。它会自己重试，最多三次	再运行一次 claude update；代理会掐断大文件的话换个网络
安装时只打印 Killed，或者 Installation was killed before it could finish (exit code 137)	内存不够，被系统杀掉了。小内存的云主机上常见	加交换分区，或者换大一点的机器。文档写的是安装约需 512MB 空闲内存，运行至少要 4GB 内存

第二类：请求报错

我们复现的六种

每一种都是用 claude -p "只回复两个字：收到" 跑的，记下了报错原文和从发出到报错的时间。

我们造的情况	报错原文	耗时
没有任何凭据	Not logged in · Please run /login	3 秒
接口地址连不上（指向本机一个没人监听的端口）	API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)	181 秒
接口地址的域名解析不了	API Error: Can't reach the API server — check your internet or DNS (ENOTFOUND)	179 秒
地址对，key 是错的	Failed to authenticate. API Error: 401 invalid or expired API key	188 秒
地址多写了一级 /v1	There's an issue with the selected model (claude-opus-5-5). It may not exist or you may not have access to it.	2 秒
模型名写错（--model claude-opus-9）	There's an issue with the selected model (claude-opus-9). It may not exist or you may not have access to it.	几秒

六次的退出码都是 1。逐条说。

Not logged in · Please run /login

Claude Code 没有找到任何凭据。用中转站的读者看到它，不要真去运行 /login，那是登录官方账号用的。原因几乎总是你设的接口地址和 key 没有被读到。按这个顺序查：

1. 设置文件的位置对不对。用户级的是 ~/.claude/settings.json。
2. 这个文件是不是合法的 JSON。写坏了它会被整个跳过，见下面第三类。
3. 两个变量是不是都写在 env 里面。
4. 是不是在别的终端里用 export 设的，现在这个终端里没有。

Connection refused 和 Can't reach the API server

请求根本没有到达对方。前者是地址通了但端口没人应，多半是端口或者协议（http 和 https）写错了，或者本机的代理没开。后者是域名解析失败，先检查域名有没有拼错。

要注意耗时：这两种我们都等了大约三分钟才看到报错。官方文档说明，Claude Code 遇到这类失败会自动重试，最多 10 次，每次间隔拉长，重试完了才把错误显示出来。所以命令“卡住不动”一两分钟，很可能是它在重试一个连不上的地址。不想等，先用 curl 直接测一下地址通不通，写法见Claude Code 接入中转站里“验证”一节。

401 invalid or expired API key

地址是通的，凭据被拒绝了。官方文档有一句话对中转站用户很重要：设了自定义接口地址时，401 后面的文字是网关自己的话，不是 Anthropic 的，运行 /login 也改变不了它。也就是说，这条报错要到中转站的控制台去查：key 有没有复制全、有没有被删、额度有没有用完、这把 key 是不是这家发的。

还有一种 401 是 key 放错了变量。ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 对应不同的请求头，中转站要的是哪一个，以它的文档为准。

这一条我们也等了三分钟左右，原因没有查。

地址多写了 /v1：报的是模型有问题

这是六种里最容易把人带偏的一种。接口地址应该只写到域名，Claude Code 会自己在后面拼上 /v1/messages。我们把地址写成 https://api.koozhan.com/v1，报错是：

There's an issue with the selected model (claude-opus-5-5). It may not exist or you may not have access to it.
Run --model to pick a different model.

报错里一个字没提地址，说的是模型不存在或者你没有权限。照着它的建议去换模型，换哪个都一样报。

所以看到这条报错，先核对接口地址，再怀疑模型。很多 OpenAI 兼容的工具要求地址带 /v1，从那边把地址复制过来就会中招。各种工具的地址该写到哪一级，见接入中转站的通用方法。

模型名真的写错了

报的是同一句话，前面多一段提示，说这个版本的模型目录里没有这个名字。除了拼错，还有一种情况：模型名是对的，但你这把 key 没有开通它。我们的实测环境里 claude-haiku-5-5 就是这样，见通过中转站用 Claude Code。

在会话里输入 /model 不带参数，从列表里选，可以避开拼写的问题。

其他常见的，按官方文档

下面这些没有复现，原文和处理办法来自官方的报错参考。

报错	意思	怎么办
API Error: 500 ...、502 Bad Gateway	服务端出错，和你的提示词、设置无关。设了自定义地址时，报错末尾会写网关的主机名	等一会儿再发。原来的消息还在对话里，输入“再试一次”就行
API Error: Repeated 529 Overloaded errors	服务端整体繁忙。不是你的额度用完了，也不算在额度里	过几分钟再试，或者用 /model 换一个模型，繁忙是按模型分的
API Error: Request rejected (429)	触发了这把 key 的速率限制	运行 /status 确认用的是你以为的那把 key；降低并发
Request timed out	在期限内没有等到响应，默认 10 分钟	重试。网络或代理慢的话调大 API_TIMEOUT_MS
Context limit reached · /compact or /clear to continue（-p 里是 Prompt is too long）	对话加上附带的文件超过了模型的上下文窗口	照提示做。见会话和上下文
API Error: 400 ... Extra inputs are not permitted ... context_management	中间的代理或网关把 anthropic-beta 请求头去掉了，接口不认识依赖它的字段	这是中转站要修的。临时的办法是启动前设 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
API Error: 400 ... "thinking.type.enabled" is not supported for this model	Claude Code 的版本太旧，带不动选的模型。文档列的最低版本：Opus 5.5 要 2.1.280，Sonnet 5.5 要 2.1.284	运行 claude update 再重启
API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation. 这一类	对话历史里工具调用和结果对不上了	照提示用 /rewind 退回到出问题之前

报错是中文的，或者措辞和上面这些都对不上，多半是中转站的网关自己生成的。怎么判断问题在哪一方，见通过中转站用 Claude Code里“出了问题，怎么判断是谁的”一节。

第三类：配置不生效

这一类不报错，所以更难查。配置没有生效，通常是三种原因之一：文件没有被加载，从另一个位置加载了，或者被别的设置盖掉了。

设置文件写坏了

我们故意把项目的 .claude/settings.json 少写了一个括号，里面本来有一条拒绝规则。claude doctor 能查出来：

Invalid settings
- /home/ccdemo/demo/f2-config/.claude/settings.json: Invalid or malformed JSON

但是不看 claude doctor 的话，你不会知道。同一个目录下运行 claude -p：

$ claude -p "只回复两个字：收到"
收到

正常回答，退出码 0，没有任何警告。文件写坏了，里面的规则就全部不生效，而它照常干活。 如果那条拒绝规则是你的安全防线，这个结果很危险。改完设置文件，跑一次 claude doctor 确认它被读进去了。

hook 不触发

最常见的写错是把 matcher 写成数组：

{ "matcher": ["Edit", "Write"], "hooks": [ ... ] }

claude doctor 的提示：

Invalid settings
- .claude/settings.json › hooks.PostToolUse.0: Invalid hook matcher (matcher: Invalid input: expected string, received array); matcher ignored.

交互式启动时也会拦一下，这一点比 -p 好：

  Settings Warning

  /home/ccdemo/demo/f2-config/.claude/settings.json
  └ hooks.PostToolUse."matcher": Invalid hook matcher (matcher: Invalid input: expected string, received array); matcher ignored.

  The values listed above were skipped; the rest of the file is in effect.

  ❯ 1. Continue
    2. Fix with Claude
    3. Exit and fix manually

选了继续之后输入 /hooks，显示的是 no hooks yet，这个 hook 没有登记上。

正确的写法是一个字符串，用 | 分开："matcher": "Edit|Write"。

/hooks 里有这个 hook 但就是不触发的话，官方文档说通常还是 matcher 的问题：工具名拼错了，匹配不到任何东西，而且不会报错。再查不出来，用 claude --debug 启动，日志里会记下每个事件检查了哪些 matcher、hook 的退出码和输出。hook 的写法见Hooks 实战。

MCP 服务器没有工具

我们在项目的 .mcp.json 里配了一个服务器，然后运行：

claude mcp list

notes: node ./tools/notes-server.js - ⏸ Pending approval (run `claude` to approve)

项目级的 MCP 服务器要先批准一次才会启用。当初弹出确认时如果被关掉了，它就一直是停用的，要到 /mcp 里去批准。

官方文档列的另外两种情况，我们没有复现：

• 显示启动失败。 常见原因是 command 或 args 里用了相对路径。相对路径是相对于你启动 Claude Code 的那个目录算的，不是相对于 .mcp.json 所在的位置。
• 显示已连接，但工具数是 0。 在 /mcp 里选 Reconnect；还是 0 的话，用 claude --debug=mcp 启动，到调试日志里看这个服务器的错误输出。

MCP 的配置见接 MCP 服务器实战。

CLAUDE.md 里写了，它不照做

先用 /context 看这个文件加载了没有。要注意子目录里的 CLAUDE.md 是用到那个目录时才加载的，不会出现在启动时的清单里。

加载了却不照做，官方文档的说法是问题多半出在写法上：一条要求含糊到可以有几种理解，两个文件里的要求互相矛盾，或者文件太长，单条规则得到的注意力变少。怎么写见CLAUDE.md 怎么写。

文档里还有一句值得记住：CLAUDE.md 是告诉它“我们这里是这样做的”，让它做出合适的判断；一定不能发生的事，要用权限规则或 hook 来保证，不要只写在 CLAUDE.md 里。

各样东西去哪看

命令	显示什么
/context	上下文里的全部内容，按类别分
/memory	各级 CLAUDE.md 和自动记忆的位置
/skills	可用的 skill
/hooks	已登记的 hook
/mcp	MCP 服务器和连接状态
/permissions	当前生效的允许和拒绝规则
/status	哪些设置来源在生效

设置是分层合并的。官方文档的顺序是：组织下发的托管设置最先；其余的里面，离得近的盖掉离得远的，本地设置（settings.local.json）优先于项目设置，项目设置优先于用户设置。命令行参数和环境变量是再上面的一层。一个设置不起作用，通常是被另一层盖掉了。

三个通用的办法

--debug：看它实际做了什么

claude --debug

日志写在 ~/.claude/debug/<会话 ID>.txt。一次最简单的 -p 调用，日志有 152 行，记录了启动、初始化、MCP、每次请求的耗时这些环节。

把日志发给别人之前先自己看一遍。我们专门检查了凭据有没有被写进去：日志里有 [REDACTED] 的标记，完整的 key 没有出现。但日志里仍然有你的目录路径、接口地址这类信息。

--safe-mode：先排除自己的配置

claude --safe-mode

这个模式下，CLAUDE.md、skill、插件、hook、MCP 服务器、自定义命令和子代理都不加载；登录、选模型、内置工具和权限照常。问题在这个模式下消失了，原因就在被关掉的那几样里，再逐个排查。

我们验证了它确实不加载 CLAUDE.md：在一个带 CLAUDE.md 的项目里问项目约定，它回答 CLAUDE.md 的内容不在上下文里。

用一个全新的配置目录

安全模式下问题还在，或者怀疑的就是设置本身，可以完全不用自己的配置启动一次：

mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

CLAUDE_CONFIG_DIR 把配置目录换成一个新的，--setting-sources user 关掉项目级的配置。这篇里的报错就是用这个变量复现的。全新的目录里没有凭据，所以第一次会回到“没登录”的状态；通过中转站用的话，要在这个新目录里另放一份带接口地址和 key 的 settings.json。

问题在全新的配置下没有了，说明原因在你的 ~/.claude 里；还在，就和你的配置无关。

/doctor：能自动修，但提议要看清再点

会话里的 /doctor 和终端里的 claude doctor 不是一回事。它是让模型来做一次完整的体检，查安装、设置文件、没在用的扩展、重复的子代理、CLAUDE.md 里多余的内容，然后提出修改建议，你确认后它才改。

我们在那个 hook 写错的目录里跑了一次。它查出了问题，说明了原因，并且没有自作主张去改：

- 5 Hooks: This project's .claude/settings.json has a PostToolUse hook that runs
  echo edited >> /tmp/f2-hook.log.
  - Problem: its "matcher" is an array (["Edit","Write"]). Hook matchers have to be a string,
    here "matcher": "Edit|Write". As written, the hook probably never fires and may show up
    as a settings error. Since this is a checked-in file, I haven't changed it; I can fix it
    if you'd like.

三点要知道：

• 它不是免费的。 这次 /doctor 让模型工作了 1 分 28 秒，/cost 显示 0.46 美元。终端里的 claude doctor 不调用模型，不花钱。
• 它的建议不全是修错。 这次它还提议把 auto 模式写成所有项目的默认权限模式，并标成了“推荐”。这是一项会改变它行为的设置，和我们要查的问题无关，我们选了不改。弹出来的每一项都读一下再决定。
• 它的结论是模型的判断。 这次有一条和 claude doctor 对不上：它说后台自动更新是关着的，而 claude doctor 显示的是 Auto-updates: enabled。我们没有深究哪个对。两边说法不一样的时候，以 claude doctor 这种程序直接报的状态为准去核实。

卡住了，或者越来越慢

按官方文档：

• 没有反应：按 Ctrl+C 取消当前操作。还不行就关掉终端重开。对话不会丢，在同一个目录下运行 claude --resume 接回来。
• 占用很高、变慢：用 /compact 压缩上下文；大的任务之间重启一次；用 claude --safe-mode 看是不是某个插件、MCP 服务器或 hook 引起的。
• Autocompact is thrashing：自动压缩成功了，但某个大文件或者工具的大段输出马上又把上下文填满，连着几次之后它就不再重试了。让它分段读那个大文件，或者把这件事交给子代理。

还是解决不了

• 会话里输入 /feedback，直接向 Anthropic 反馈。
• 到 GitHub 仓库搜有没有同样的问题。
• 账号、订阅、账单的问题找 Anthropic 的客服，不在 GitHub 上提。
• 通过中转站用的，401、额度、某个模型用不了这类问题，找中转站。

这次实测没有覆盖到的

• 第一类安装问题全部没有实测。 环境是已经装好的 Linux 服务器。
• 服务端的报错没有复现：5xx、529、429、超时、上下文超限都是照官方文档写的。
• 401 那一次为什么等了三分钟，没有查。
• 只在一家中转站上试过。 key 错误时返回的文字是这家网关的，别家的措辞会不同。
• 设置文件写坏时交互式启动会显示什么，没有试，只试了 claude doctor 和 claude -p。hook 写错的那种，三种方式都试了。
• MCP 服务器启动失败、工具数为 0 的情况没有复现。
• macOS 和 Windows 没有测，VS Code 扩展和桌面应用里的报错也没有涉及。

相关文章

• 安装 Claude Code
• Claude Code 接入中转站
• 通过中转站用 Claude Code：哪些功能和直连一样，哪些不一样
• 把 Claude Code 接进脚本和 CI：脚本里怎么判断一次运行成没成