只要一直做 AI 编程，就必定会遇到错误。红字一冒出来，手就停住——那段时间，正是生产力最大的敌人。但请放心。在 Claude Code 等 AI 编程工具里碰到的错误，绝大多数都是固定套路的重复。只要能认出类型，处理几乎是机械化的。这一章，就是你卡住时最先翻开的故障分诊（切分）地图。
成为「不被错误绊住」的自己
🧭 先备一篇总汇文章。 把常见错误横向汇总的总集，是「Claude Code 常见错误与处理方法总汇」。本章是俯瞰各类别的地图，链接里的单篇文章则给出具体的消息示例和步骤。收藏起来，卡住时从这里往下查是个好办法。
错误要按「类型」来切分
处理的第一步，是分辨「这是哪一类错误」。原因所在的层不同，要修的地方也不同。在细读具体消息之前，先把它归到下面 6 类中的一类。归好类的那一刻，处理就定了八成。
压根启动不了·没这命令。入口的问题。↓详细
登不上·认证掉了。与账号的连接。↓详细
通信不了·服务器拥堵。链路与服务器端的问题。↓详细
达到上限·处于不可用时段。套餐与用量的问题。↓详细
太长·塞太满。所给信息量的问题。↓详细
扩展·工具调用失败。周边功能的问题。↓详细
💡 分辨的诀窍。 靠错误文里的一个关键词就能猜个八九。command not found→①，authentication／login→②，connection／network／529→③，usage limit→④，too long→⑤，MCP／tool→⑥。在通读整条消息之前，先找找这个词。
① 安装·启动类 —— 找不到命令
第一道关卡是「压根启动不了」。安装中途失败了，或者路径（PATH）没配好，敲了命令也没反应。卡在这里就没法往下走，所以要沉住气检查入口。
症状：敲 claude 时回「没有这条命令」。
原因：安装位置没配到 PATH，shell 没重新加载，或安装本身未完成。
对策：重新打开终端／检查 PATH／重新安装。按顺序试，大多能脱身。
症状：安装途中报错停下／被权限（permission）挡住。
原因：Node.js 版本过旧、权限不足、经网络拉取包失败。
对策：更新前提环境（Node 等），重新审视管理员权限和安装方式。公司网络还要怀疑代理。
🔧 详细步骤在此。 安装失败与 command not found 的原因切分和具体修法，整理在「command not found / 安装错误的修法」里。安装绊住了，按第 2 章「开始使用 Claude Code」的步骤重装一遍是最快的。
② 登录·认证类 —— 认证过不去
这是能启动，却在登录或认证处被挡的套路。表现为浏览器认证走不通，或用了一阵后突然被登出。这是账号与工具的「握手」错位了。
症状：登录界面走不下去／被认证错误挡住／认证用的浏览器打不开。
原因：认证令牌过期·损坏、重定向失败、套餐或目标账号弄错、时间不对。
对策：先登出再重新登入／清掉保存的认证信息再认证／确认账号是否正确。
看着像「认证错误」，实则只是套餐或合约对象不对。
同时用多个账号的人，先确认当前登录的账号和套餐类型。公司发的和自用的混在一起，是典型陷阱。
🔑 详细步骤在此。 认证过不去时的重新登录、令牌重取步骤，见「登录·认证错误的处理」。多数重新登入即可解决，若还不行，也怀疑一下网络端（③）。
③ 连接·网络类 —— 连不上·拥堵
这里的原因分成「自己端」和「服务器端」两头，切分是关键。是你的线路或代理堵住了，还是服务器一时拥堵？前者你能自己修，后者的基本方针是等待·减负。
症状：连不上·超时·通信中途断开。
原因：网络线路不稳、公司代理或防火墙拦截、VPN、证书或 DNS 问题。
对策：换条线路试／关掉 VPN／检查代理设置。公司网络就向管理员确认放行对象。
症状：返回 overloaded 或 5xx。自己的设置明明没错却失败。
原因：服务器端一时高负载·故障。不是你的代码或设置的错。
对策：稍等再试／避开拥堵时段／查看故障信息（状态页）。
⚠️ 切分的判断标准。 若别的网站和服务都正常，唯独 AI 工具挂掉，多半是服务器端（529/500），对策是「等」。若其他通信也不稳，那就是自己端（线路·代理·VPN）。详见「连接·网络·代理错误」和「529 overloaded / 500 错误的含义与处理」。
④ 使用限制类 —— 达到上限
这不是错误，而是「已达上限，现在用不了」的通知。各套餐对单位时间、单位周的用量设有上限，触到就会临时停用。它不是故障，与其去「修」，不如用用法和套餐来调整才是正解。
症状：显示「已达使用上限」，一段时间内用不了。
原因：触到套餐的用量上限。短时间内跑大任务或长对话，会更快触到。
对策：等到重置／把对话拆开轻量使用／必要时重新审视套餐。
症状：周中就达上限／重置时点感觉比想的早或晚。
原因：周额度可能以首次使用为起点计，未必是日历周这类机制。
对策：正确理解重置的计法，把消耗大的工作有计划地分配。
📊 上限靠「管理」几乎能避开。 上限的含义与等待时长的思路见「达到使用上限时的处理」，周重置的计法见「周上限提前重置的机制」。至于本就不易触到上限的用法，会在第 7 章「成本与效率」里集中讲。
⑤ 输入·上下文类 —— 太长了
AI 一次能处理的信息量（上下文）有上限。对话拖长，或把巨大文件整个丢过去，就会被「输入太长」拒绝。这是塞太满的信号，对策是减少所给的量·切分。
症状：提示「输入太长」，指令不执行。
原因：对话历史累积、读入巨大文件或大量文件、粘贴的日志太长。
对策：整理·摘要对话／开新对话／只给需要的范围／把任务切小。
症状：思考（thinking）相关处理出错，响应中断。
原因：对话状态不一致，或历史牵扯出的内部处理错位。长对话里易发。
对策：重开新对话／把相关来回拆分。多数刷新一下即可解决。
✂️ 「太长」能靠设计来防。 具体的减量法见「prompt is too long 的处理」，thinking 周边的毛病见「thinking block 错误的处理」。而把任务切小本就是根本之策，这与第 4 章「会请求」讲的下指令方式直接相关。
⑥ MCP·工具类 —— 扩展跑不动
MCP（外部工具对接）和工具调用，有时会是Claude Code 本体正常，唯独周边的扩展失败。诀窍是把它与本体的错误切分开来考虑。先确认「拿掉扩展是否还复现」，原因的切分就会一下子推进。
症状：连不上 MCP 服务器／对接工具不在列表里·无反应。
原因：配置文件写错、服务器启动失败、路径或依赖缺失、认证信息不全。
对策：检查配置／单独启动服务器验证／先拿掉看本体能否单独工作来切分。
症状：工具调用失败／在调用结果的交接处卡住。
原因：工具定义或参数不一致、对话状态错位、对接方一时不稳。
对策：重整对话／临时禁用该工具来切分／确认对接方状态。
症状：PR（拉取请求）相关的状态检查报错。
原因：多与对接的 CI 或检查的设置·权限、外部服务端的状态有关。
对策：确认检查侧的设置·权限／重新运行／确认外部服务的状态。
🧩 扩展类要「拿掉来切分」。 MCP 连接的修法见「MCP 服务器连接错误的处理」，工具调用的毛病见「工具调用错误的处理」，PR 检查相关见「PR 状态检查错误的处理」。扩展功能本身的用法，会在第 6 章「用扩展功能」里讲。
卡住时的脱身法 —— 万能的 5 招
即便一时定不出原因，也有「该先试的万能一手」。很多错误，只要刷新状态、或减轻负载就消失了。上面的类别里对不上号时，就把这 5 招从上往下试。
关掉工具和终端再重开。一时的状态紊乱，光这一下大半就消失。该最先怀疑的一手。
长对话是不一致的温床。开新对话，或把历史摘要·整理（/compact 式的思路）以轻装上阵。对 ⑤ 有效。
别一次大块地请求，把任务拆成小步。太长·太重引起的错误，能从根上避开。
529/500 和拥堵靠时间解决。等几分钟再执行。也在状态页确认故障信息。对 ③④ 有效。
实在搞不懂，就把整条错误文原样丢给 AI 或搜索。对照本章的总汇文章，大多能对上已知套路。
🧯 不慌，才是最好的对策。 错误不是「坏了」的信号，而是「这里该改」的提示。认出类别，试上面 5 招，还不行就去看单篇文章。只要把这套流程练熟，红字就再也不可怕了。
- 错误先切成 6 类（安装·认证·连接·使用限制·上下文·MCP/工具）。靠一个关键词就能猜准。
- 各类别的症状→原因→对策几乎都是固定套路。529/500 等服务器端「等」，太长就「拆·整理」。
- 即便原因不明，也能靠万能 5 招（重启·重整对话·切小·稍等再试·把错误文原样丢过去）脱身大半。
- 具体步骤去看总汇文章和各单篇。上限管理在第 7 章、扩展在第 6 章深挖。
学会与错误相处，AI 编程就能一口气往前推进。接下来，轮到拓展 Claude Code 自身的能力了。下一章第 6 章「用扩展功能」，我们用 hooks、plugins、subagents、MCP，把搭档变得更强。