Claude Code 学习站
v2.1.207
对齐 Claude Code v2.1.207 · 112/112 条深度指南已核查 · 最后更新 2026-07-12

Claude Code 报错速查

把终端里看到的报错原文对到下面任一条:含义 → 分步修复 → 官方来源。 覆盖安装 EACCES、登录 OAuth 无头、429 限流、529 满载、上下文窗口满、 模型无访问权限、MCP 连接失败等常见错误。每条修复均对照官方 troubleshoot / errors 文档核对,逐条带来源,不编造。

安装3登录 / 认证2用量 / 限流2服务端1网络1上下文窗口2请求 / 模型2MCP / 配置1

安装

3 条
command not found: claude

含义: 安装成功了,但安装目录不在 shell 的 PATH 里。native 安装器把 claude 放在 macOS/Linux 的 ~/.local/bin/claude、Windows 的 %USERPROFILE%\.local\bin\claude.exe。不同平台报错文案略有差异:zsh 是 "command not found: claude",CMD 是 "'claude' is not recognized as an internal or external command"。VS Code 扩展自带私有 CLI 副本,不会把 claude 加进 PATH。

修复
  1. 1确认安装目录在 PATH 里:macOS/Linux 跑 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"。
  2. 2若无输出,Zsh 加 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc 后 source ~/.zshrc;Bash 改 ~/.bashrc。或直接关掉重开终端。
  3. 3Windows PowerShell:用 [Environment]::SetEnvironmentVariable 把 $env:USERPROFILE\.local\bin 加进 User PATH,再重启终端。
  4. 4改完跑 claude --version 验证。
查看详情
相关命令:/doctor
Troubleshoot install · command not found / Verify your PATH
Permission errors during installation (EACCES / not writable)

含义: native 安装器需要对 ~/.local/bin/ 和 ~/.claude/ 有写权限,目录不可写就装失败。如果之前用 npm 全局装(npm install -g)碰到 npm 自身的权限错误,根因是 npm 全局目录归属。

修复
  1. 1检查目录可写:test -w ~/.local/bin && echo writable || echo 'not writable';test -w ~/.claude && echo writable || echo 'not writable'。
  2. 2不可写就建目录并把自己设为属主:sudo mkdir -p ~/.local/bin 然后 sudo chown -R $(whoami) ~/.local。
  3. 3若是 npm 全局装碰到 npm 权限错,改用 native 安装器:curl -fsSL https://claude.ai/install.sh | bash(不要用 sudo npm install -g)。
查看详情
相关命令:/doctor
Troubleshoot install · Check directory permissionsTroubleshoot install · Permission errors during installation
Killed

含义: 在低内存 Linux(VPS / 云实例)上安装时,Linux OOM killer 因系统内存耗尽而终止了安装进程,日志里会出现类似 "34803 Killed"。Claude Code 安装至少需要 4 GB 可用 RAM。

修复
  1. 1加 swap 交换空间:sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile,然后重跑 curl -fsSL https://claude.ai/install.sh | bash。
  2. 2安装前关掉其它进程腾内存。
  3. 3条件允许就换更大内存的实例(至少 4 GB RAM)。
查看详情
相关命令:/doctor
Troubleshoot install · Install killed on low-memory Linux servers

登录 / 认证

2 条
OAuth error: Invalid code. Please make sure the full code was copied

含义: 登录码过期或复制粘贴时被截断;在 WSL2 / SSH / 容器里运行时浏览器常开在另一台主机上,本地回调服务器收不到重定向,登录后浏览器只显示一段 code。

修复
  1. 1在交互登录提示处按 c 复制 OAuth URL,粘到本机浏览器打开;登录后把显示的 code 粘回终端 "Paste code here if prompted" 处。
  2. 2WSL2 里浏览器不自动打开时:export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe" 后重跑 claude。
  3. 3粘贴 code 无反应时改用 claude auth login,它从标准输入读取粘贴的 code。
  4. 4登录整体出问题且原因不明时,先 /logout 再关闭重启 claude 走一遍干净的重新认证。
查看详情
相关命令:/login/logout/status
Troubleshoot install · OAuth error: Invalid codeTroubleshoot install · OAuth login fails in WSL2, SSH, or containers
This organization has been disabled

含义: 明明有有效订阅却报 "API Error: 400 ... This organization has been disabled",是因为环境里残留的 ANTHROPIC_API_KEY 覆盖了订阅登录。环境变量优先级高于 /login,常见于旧公司/旧项目的 key 还留在 shell profile 或 .env 里;-p 非交互模式下 key 一旦存在必定被用。

修复
  1. 1在当前 shell 取消变量并重启:unset ANTHROPIC_API_KEY 然后 claude。
  2. 2永久生效:删掉 ~/.zshrc / ~/.bashrc / ~/.profile 里的 export ANTHROPIC_API_KEY=... 行;Windows 检查 $PROFILE 和 User 环境变量。
  3. 3跑 /status 确认当前激活的认证方式已切回订阅。
查看详情
相关命令:/login/status/logout
Error reference · This organization has been disabledTroubleshoot install · This organization has been disabled with an active subscription

用量 / 限流

2 条
API Error: Request rejected (429)

含义: 触达了 API key / Amazon Bedrock 项目 / Google Vertex AI 项目所配的速率限制。注意它跟订阅的 "用量上限" 不是一回事——这是 provider 侧的 rate limit。Claude Code 已自动重试多次(指数退避,最多 10 次)后才把这条报错抛给你。

修复
  1. 1跑 /status 确认当前激活的 credential 是你预期的那个;环境里残留的 ANTHROPIC_API_KEY 可能把请求路由到了低档 key。
  2. 2去 provider 控制台查当前限额,需要就申请更高 tier。
  3. 3降并发:调低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY、别同时跑大量子代理,或用 /model 切到更小的模型跑高频脚本。
查看详情
相关命令:/status/model
Error reference · Request rejected (429)
You've hit your session limit · resets 3:45pm

含义: 订阅套餐含一个滚动用量额度,用完后会按时间窗封锁后续请求,直到报错里显示的 reset 时间。文案还有 "You've hit your weekly limit"、"You've hit your Opus limit" 等变体。

修复
  1. 1等报错里显示的 reset 时间。
  2. 2跑 /usage 查套餐限额和重置时间。
  3. 3跑 /usage-credits 在 Pro/Max 上加购用量(Team/Enterprise 向管理员申请);要升套餐看 claude.com/pricing。
查看详情
相关命令:/usage/model
Error reference · You've hit your session limit

服务端

1 条
API Error: Repeated 529 Overloaded errors

含义: API 跨所有用户临时满载,Claude Code 已重试多次后才显示这条。529 不计入你的用量配额。容量是按模型单独跟踪的。

修复
  1. 1去 status.claude.com(或报错里指明的 provider 状态页)看容量公告。
  2. 2过几分钟再试。
  3. 3跑 /model 切到另一个模型继续干活——某个模型高负载时 Claude Code 会提示你这么做(如 "Opus is experiencing high load, please use /model to switch to Sonnet")。
查看详情
相关命令:/model
Error reference · Repeated 529 Overloaded errors

网络

1 条
TLS connect error / unable to get local issuer certificate

含义: TLS 握手失败,通常是系统 CA 证书过期,或公司代理在做 TLS 拦截(self-signed / SELF_SIGNED_CERT_IN_CHAIN)。安装阶段和运行阶段都可能撞上。

修复
  1. 1更新系统 CA 证书:Ubuntu/Debian 跑 sudo apt-get update && sudo apt-get install ca-certificates;macOS 更新系统即更新根证书。
  2. 2公司代理做 TLS 拦截时,安装用 curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash。
  3. 3装好后让 Claude Code 的 API 请求信任同一份 CA:export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem。切勿用 NODE_TLS_REJECT_UNAUTHORIZED=0 关掉校验。
查看详情
相关命令:/doctor
Troubleshoot install · TLS or SSL connection errorsError reference · SSL certificate errors

上下文窗口

2 条
Prompt is too long

含义: 对话加附带文件超过了模型的上下文窗口(context window 满)。自动压缩默认开启、通常能避免这条;若你设了 DISABLE_AUTO_COMPACT 就容易撞上。

修复
  1. 1跑 /compact 把早期对话压成摘要腾空间,或 /clear 开新会话。
  2. 2跑 /context 看是什么在吃窗口:系统提示、工具、记忆文件、消息。
  3. 3用 /mcp disable <name> 关掉没在用的 MCP server,移走它们的工具定义。
  4. 4精简过大的 CLAUDE.md,或改成按路径加载的 path-scoped 规则。
查看详情
相关命令:/compact/context/clear/mcp
Error reference · Prompt is too long
Responses seem lower quality than usual

含义: 答案变弱但没报错,通常是对话状态(而非模型本身)的问题:可能 /model 选到了更小的模型、effort 档偏低、上下文接近满载,或过时的 CLAUDE.md / MCP 工具定义在吃 context 并带偏回答。Claude Code 不会悄悄换模型版本。

修复
  1. 1跑 /model 确认在预期模型上;跑 /effort 查推理档,难调试/设计任务调高。
  2. 2跑 /context 看窗口满载程度,接近上限就在自然断点 /compact 或 /clear。
  3. 3跑 /doctor 找过大的记忆文件和子代理定义;答错时优先按 Esc 两次或 /rewind 回退重述,而不是在串内纠正。
查看详情
相关命令:/model/context/compact/doctor
Error reference · Responses seem lower quality than usual

请求 / 模型

2 条
There's an issue with the selected model

含义: 配置的模型名没被识别,或你的账号没有访问权限。完整文案:"There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model." 常见于某处残留了过时的模型 ID。

修复
  1. 1交互 CLI 里跑 /model 从账号可用模型中重选;非交互 -p 模式用 --model 传有效 alias/ID 或设 ANTHROPIC_MODEL。
  2. 2用 sonnet / opus 这类 alias 而非完整版本号,alias 会解析到维护中的默认值不会过时。
  3. 3若错误反复出现,按优先级排查残留 ID:--model 旗标 > ANTHROPIC_MODEL 环境变量 > .claude/settings.local.json > 项目 .claude/settings.json > ~/.claude/settings.json,删掉过时值。
查看详情
相关命令:/model/status
Error reference · There's an issue with the selected model
"thinking.type.enabled" is not supported for this model

含义: Claude Code 版本低于 Opus 4.7 / 4.8 的最低要求,CLI 发了模型已不再接受的 thinking 配置。完整文案提示改用 "thinking.type.adaptive" 与 "output_config.effort"。

修复
  1. 1跑 claude update 升级并重启:Opus 4.7 需 v2.1.111+,Opus 4.8 需 v2.1.154+。
  2. 2若无法升级,跑 /model 改选 Opus 4.6 或 Sonnet。
查看详情
相关命令:/update/model
Error reference · thinking.type.enabled is not supported for this model

MCP / 配置

1 条
MCP server failed to connect or authenticate

含义: 某个 MCP server 没能加载/连接/认证。这类问题归在 MCP 与配置调试范畴,而非 Claude API 报错;设置没生效、hook 没触发、MCP server 没加载也都属于配置层。

修复
  1. 1在 Claude Code 里跑 /doctor 一次性自检安装、设置、MCP server 配置与上下文用量;若 claude 根本起不来,在 shell 里跑 claude doctor。
  2. 2跑 /mcp 查看/管理 MCP server 状态;没在用的用 /mcp disable <name> 关掉以释放上下文。
  3. 3排查配置问题(设置未生效 / MCP 未加载)参见官方 Debug your configuration;用 claude --safe-mode 起一个禁用全部定制的会话定位是哪个插件/MCP/hook 的锅。
查看详情
相关命令:/doctor/mcp
Error reference · Report an error (MCP server failed to connect)Troubleshooting · run /doctor / safe-mode