Claude Code 常见报错怎么解：安装、登录与运行故障对照
Claude Code 是运行在终端里的智能编程工具，可执行代码任务、解释代码并处理 Git 工作流；本文按安装、登录、网络和运行时报错逐项排查。2026 年 10 月 27—28 日，Claude Code 官方错误参考页面持续补充安装、登录和运行时错误，因此现在适合把常见报错整理成可直接执行的排查路径。
先确认环境：报错发生前做 3 项检查
Claude Code 的错误分为安装阶段、登录阶段和运行时三类。先确认当前环境，避免把安装问题误当成模型或账号问题。
-
确认系统能启动 Claude Code。在项目目录执行：
claude能出现交互界面，说明命令已经安装并能启动；如果终端提示找不到命令，先按下面的安装部分处理。
-
确认当前目录和权限。执行
pwd，确认终端位于准备让 Claude Code 读取的项目根目录；如果要修改文件，还要确保当前账号对目标目录有写权限。 -
确认账号和网络状态。打开 Claude Code 官方文档入口：https://code.claude.com/docs/en/overview。如果使用 API、Anthropic Console 或 Amazon Bedrock，还要确认对应账号已经启用 Claude API，并且环境变量指向正确的服务地址。
如果程序能启动但无法发起请求，优先看“登录、网络与权限”部分；不要先改项目代码。
安装与启动：先排除 command not found 和安装失败
官方仓库目前明确标注：通过 npm 安装已经弃用，推荐使用系统安装脚本或 Homebrew；Windows 推荐使用 PowerShell 安装脚本，也可以使用 WinGet。仓库 README 给出的命令如下：
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
# Homebrew（macOS / Linux）
brew install --cask claude-code
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows WinGet
winget install Anthropic.ClaudeCode安装完成后，重新打开终端，进入项目目录并执行：
cd /你的项目目录
claude如果之前使用过 npm，官方仓库把 npm 方式标记为 NPM (Deprecated)，建议不要继续围绕旧的全局 npm 包排查。重新安装推荐方式前，可以先卸载旧版本：
npm uninstall -g @anthropic-ai/claude-code卸载后再次执行 claude；仍然无法启动时，打开终端设置，把 Claude Code 安装脚本加入 PATH，然后重启终端。Windows 用户还要确认 PowerShell 执行策略没有阻止安装脚本运行；官方仓库的 Windows 推荐入口是 irm https://claude.ai/install.ps1 | iex，不要把它改写成未核实的参数组合。
登录与网络：区分额度、认证和主机限制
运行时最容易被误判的是“请求失败”。Claude Code 调用 Claude API 时，底层 API 错误通常会映射成 CLI 中的错误消息；官方错误参考页面列出了这些运行时错误。安装错误，例如 command not found 或设置期间的 TLS 失败，则应转到安装与登录排查文档，而不是反复清空会话。
Credit balance is too low
这个报错表示账户余额不足。打开 Claude Code 正在使用的 Anthropic 账户或所用云平台的账单页面，充值或切换到有可用额度的账号，然后重新执行原请求。若使用企业、云端会话或定时任务，还要确认实际扣费的主体就是当前登录主体。
设置期间出现 Unable to connect to Anthropic services
这类消息通常表示 Claude Code 在设置阶段无法连接 Anthropic 服务。先检查网络代理是否能访问 Anthropic 服务，再检查当前 shell 中的代理变量是否仍然有效。修改代理后，重新启动终端和 Claude Code；不要只在已经运行的会话里重试，因为启动时读取的环境变量可能没有更新。
如果使用 Amazon Bedrock，问题可能不在 Claude Code 本机，而是 AWS 账户没有调用指定模型的权限。官方错误参考说明：如果每次重试都返回相同消息，应确认标准 Bedrock 模型的 IAM 策略允许调用该模型；如果是 Mantle 模型 ID，则需要联系 AWS 账户团队确认权限。
403 且带有 x-deny-reason: host_not_allowed
这个错误出现在云端会话或云端定时任务中，表示请求所访问的主机被服务拒绝。不要把它当成普通网络超时反复重试；检查云端任务或会话配置中的主机地址，改成服务允许访问的目标后，再重新启动任务。官方错误参考没有提供一个可以随意替换的通配地址，因此这里不应猜测具体域名。
运行时故障：清会话、查调试日志、识别工具调用限制
Context limit reached · /clear to continue
这表示当前会话上下文已经达到上限，错误消息已经给出恢复命令。直接执行：
/clear/clear 是 Claude Code 内置命令，用于开始一个没有旧上下文的新会话。执行后重新描述任务；如果任务依赖之前读取的文件内容，重新提供文件路径或必要的代码片段，不要假设新会话自动保留旧上下文。
Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details
这个报错表示自动模式无法完成安全检查，因此暂时阻止了操作。官方给出的可执行处理是：
claude --debug然后在调试模式下重复原操作，查看日志中的具体原因。若日志显示安全检查因早期对话内容而被单独阻止，错误消息本身会说明：这不是对当前操作不安全的判断。此时可以继续执行其他任务；官方建议不要直接反复重试被阻止的操作。
Request too large
请求内容过大时，先缩小请求范围：只提供必要的文件、减少一次提交的文件数量，或把大型任务拆成更小的步骤，再重新执行。不要把超大文件完整粘贴到提示词中；这类请求失败与余额不足不是同一类问题，前者需要减少输入，后者需要增加额度。
Image was too large
图片超过允许大小，应先缩小图片或改用尺寸更小的版本，再重新提交。官方错误参考把图片大小限制列为独立错误，因此换模型、重开会话通常不是第一处理方式。
工具与命令报错：先看它是否真的执行了命令
No shell command in <name> was run, because the <tool> tool does not accept one of them
这条消息说明某个工具调用包含了不被该工具接受的 shell 命令，因此命令没有运行。处理方法是检查该工具的参数格式，只传它实际接受的字段；如果任务本来需要执行命令，改用支持执行 shell 的入口，不要把命令文本硬塞进不接受命令的工具参数中。
Unknown command: /<name>
如果 Claude Code 不认识某个斜杠命令，输入它不会自动变成可用命令。先检查拼写和当前版本支持的命令列表，再改用已确认存在的命令。错误消息可能给出 Did you mean 建议，但建议本身仍需要和当前命令列表核对；不要把任意相似名称当成官方命令。
server_tool_use.name: Input should be on every turn of a resumed session
这表示恢复会话时，服务端工具调用缺少每轮都需要的 name 输入。官方错误参考给出的处理方向是开始新会话：
/new新会话会放弃当前恢复状态，但不会删除本地项目文件。重新发起任务并提供必要上下文即可。
报错对照：先判断故障属于哪一层
| 看到的现象 | 先执行 | 进一步判断 |
|---|---|---|
终端找不到 claude |
重新打开终端并执行 claude |
仍未出现则按官方推荐方式重装 |
Unable to connect to Anthropic services |
检查网络、代理和 Anthropic 服务访问 | 仍失败时检查云端账号权限 |
Credit balance is too low |
检查当前账号余额 | 充值或切换有额度的账号 |
Context limit reached · /clear to continue |
执行 /clear |
重新提供必要上下文 |
Auto mode could not evaluate this action... |
执行 claude --debug 并重复操作 |
从调试日志确认被阻止原因 |
Request too large |
减少文件范围、拆分任务 | 再次提交较小请求 |
Image was too large |
缩小图片后重新提交 | 检查上传结果 |
Unknown command: /<name> |
核对命令拼写和版本 | 使用官方确认存在的命令 |
怎么算排查成功：看这三个可观察结果
第一，命令行中能正常进入 Claude Code 交互界面，而不是停留在 shell 报错。第二，登录后执行一个只读的小任务，例如让它读取当前目录下的单个文本文件；文件能正常返回，说明启动、账号和网络路径基本可用。第三，如果之前遇到上下文超限，执行 /clear 后新会话可以开始；如果遇到自动模式阻止，执行 claude --debug 后能看到对应日志，并且日志能解释本次失败原因。
不要把“窗口打开成功”当成全部成功。Claude Code 的运行时错误可能出现在 CLI、桌面应用和云端会话中；这些入口包装同一个 Claude Code CLI，因此修复命令仍应回到 CLI 中验证。提交 Bug 时，可在 Claude Code 会话中执行：
/bug官方仓库也提供 GitHub Issue 入口：https://github.com/anthropics/claude-code/issues。反馈时附上错误原文、运行入口、执行过的恢复命令和 claude --debug 日志，但不要贴入 API 密钥、访问令牌或项目私密代码。
延伸入口：按报错类型继续查
安装方式、卸载步骤和安装故障看官方仓库 README：https://github.com/anthropics/claude-code。运行时错误对照官方中文错误参考：https://code.claude.com/docs/zh-CN/errors#1。需要查看英文版错误条目时，使用同一文档站点的错误参考页；涉及云端会话、定时任务或某个使用入口的专用故障，则继续查看对应入口的故障排除说明。GitHub 仓库中的 CHANGELOG.md 可用于核对版本变化，提交问题时则使用仓库的 Issue 页面；这两个入口分别对应版本记录和问题反馈，不应混为一谈。
参考来源
- Error reference – Claude Code Docs（英文权威版）：本文各条报错与恢复步骤的官方出处。
- anthropics/claude-code 官方仓库：安装命令、版本与 Issue 检索。
- Claude 登录页：登录与账号状态核对入口。
（原参考为 zh-CN 重复条与 zh-TW 版，按来源纪律统一为英文权威版并补齐独立域名。）
评论区
登录后可评论。