工具、后台会话与配置警告

措辞和版本要求以官方为准。

工具错误

来自 Claude 的内置工具。多数工具错误 Claude 会自己纠正；需要你改动时，才会在该条目的「怎么办」里说明要改什么。

• Agent would be spawned with zero tools：子智能体 tools 列表里的每一项都没能匹配到可用工具，所以 Claude Code 拒绝启动它（没有工具就无法行动）；消息按问题类型分组你的条目（无法识别的名称、会话里不存在的工具如未连接服务器的 MCP 工具、被后台子智能体丢弃的工具如 CronCreate 等）。按子智能体可用的工具逐项纠正；删掉会话里没有的工具；对后台子智能体丢弃的工具，要么删掉该条目，要么关闭 fork 模式并让 Claude 在前台运行该子智能体；直接删除 tools 字段而不是列出工具，就给子智能体所有它可用的工具；tools 列表只含 Agent 的情形见官方。
• File is covered by a Read deny rule：Edit 或 Write 工具被调用在一个匹配 Read deny 规则的路径上（包括在该路径创建新文件）；这两个工具改动的内容必须是 Claude 能读回的，所以 Claude Code 在任何文件访问之前拒绝调用（NotebookEdit 不受此限）。想让 Claude 能改该文件，就在 /permissions 或设置里移除或收窄 Read deny 规则；文件必须保持不动就保留规则，并为同一路径加一条 Edit deny 规则，把 NotebookEdit 工具也挡住。同类还有「Path cannot contain null bytes」：文件工具调用的路径或模式参数含 NUL 字节，文件系统和搜索工具无法接受。
• Memory index is over its read limit：Claude 写入自动记忆索引 MEMORY.md 后，它超过了读取上限之一（200 行或 25KB）。写入成功，但会话开始时只加载前 200 行或 25KB（先到者），超出的部分被丢弃。让 Claude 重写 MEMORY.md（每条目一行、细节挪进主题文件、合并或删掉陈旧条目），或自己精简索引（见「审计和编辑你的记忆」）。
• pkill pattern matches the Claude Code process：Bash 工具调用里的 pkill 命令用了会匹配 Claude Code 进程自己的模式（通常带 -f），所以 Claude Code 拒绝该命令而不是让它结束会话（它在运行 pkill 之前先用 pgrep 测试模式）。收窄模式使它只匹配想要的进程（例如目标二进制的完整路径而不是短子串）；要停止当前 shell 启动的进程，用 pkill -P $$ 加模式，把匹配限制在 shell 自己的子进程。同类还有「Failed to write to a teammate's inbox」：Claude Code 无法写队友在 ~/.claude/teams/{team-name}/inboxes/ 下的邮箱文件，收件人什么也没收到（创建或更新该文件失败时发生）。
• Message too large for cross-session delivery：Claude 发给你在本机另一个会话的跨会话消息太长，Claude Code 拒绝了，接收会话什么也没收到（拒绝显示在发送会话的工具结果里，而不是终端横幅）。让 Claude 总结消息，或把大块内容放进文件并发送文件路径，或把内容拆成几条较短的消息。（v2.1.235 之前 Claude Code 把过大的消息报告为已发送，接收会话未读就丢弃了。）
• Too many messages to this session just now：Claude 向你本机的某个会话快速连发了一批跨会话消息，达到了该会话收件箱接受的上限，Claude Code 拒绝下一次发送。通常无需处理：Claude 会把剩余内容合并成一条消息，或等一会儿再发；是你自己的提示引发的连发，就让 Claude 把剩下的合并成一条。（v2.1.236 之前这些发送被报告为已发送。）同类还有「Cross-session message was dropped at the recipient session's inbox」：Claude 发的跨会话消息被收件人会话的收件箱在对方 Claude 读到之前丢弃了。
• Refusing to send a cross-session message：Claude Code 在向你本机另一个会话写跨会话消息前，先检查目标会话的收件箱套接字就是消息所指的端点；检查失败时在发送会话里拒绝发送。通常无需处理：这些检查阻止消息到达不是它所指会话的端点，并且什么也没发出；同一会话反复出现 reply target is a symlink 时，查看是什么在该会话的套接字路径创建了链接（在它的 /status 的 Peer address 下）。同类还有「Refusing to read, write, or search a path」：Claude Code 先检查文件路径的权限规则，再在工具打开文件或开始搜索时再次确认解析；无法确认路径仍在原处时就拒绝。

后台会话错误

后台会话没有自己的交互终端，所以需要终端的命令表现不同。这些消息出现在后台会话的转录、附加它的终端、你派发它的会话或 shell 里，下面 worktree 守卫类条目则出现在任何隔离在 worktree 里或运行 worktree 隔离子智能体的会话里。

• Commands refused in a background session：打开交互对话框的命令在没有终端附加到后台会话时无法这么做：/install-github-app、/mcp 设置列表和 MCP 服务器菜单里的认证动作会用一条消息回应。从智能体视图附加到会话再运行命令；或用消息点名的形式，如 /mcp reconnect <name>、/mcp enable、/mcp disable，它们无需附加就能工作。
• Write or command blocked because the path cannot be safely resolved：Claude 用 worktree 隔离守卫无法解析为单一可验证位置的写法来指向文件或工作目录（守卫检查任何隔离在 worktree 里的会话的写入和命令工作目录，交互或后台都一样）。通常无需处理：完整消息作为工具错误交给 Claude，Claude 用消息里点名的直接路径重试；对被阻止的文件编辑，对话视图只显示简短的 Error editing file，完整消息在转录视图里（Ctrl+O 打开）；同一文件反复被阻止，多半是路径穿过一个目标含 .. 的已提交符号链接（如 docs/current -> ../README.md），让 Claude 直接编辑它指向的真实文件。
• Write or command blocked because the path names a network location：Claude 用指向不在你机器上的盘符、UNC 共享（\\server\share\file）或 /net 自动挂载路径的写法来指向文件或工作目录，而会话的检出在本地磁盘上。通常无需处理：Claude 按消息要求改用本地写法重试。
• Command blocked by the worktree isolation checks：Claude 在隔离于 worktree 的会话里运行了 Bash 或 Monitor 命令，被 Claude Code 拒绝，原因之一：命令把 git 指向主检出；或 Claude Code 无法从命令文本验证命令运行的 git 留在 worktree 内。通常无需处理：Claude 读消息并按最后一句的要求改写命令；你要的命令一直被拒时，把被标记的值写成字面量（把间接引用或替换换成它的值），并在 worktree 内把 git 作为独立的普通命令运行；想有意操作主检出，在会话之外的终端里自己运行该命令。
• This session has no saved transcript：你附加到一个已停止的后台会话，它是用 ← 或 /background 从另一个对话转到后台、并在首次响应完成之前停止的；首次响应完成前对话只存在于它被转出的那个会话里。你转出的那个对话完好，用 claude --resume 恢复或继续在其中工作；仍想让停止的会话重新开始，用消息里的 ID 运行 claude respawn <id>，或在智能体视图那一行按两次 Enter；会话其实完成过响应却在 v2.1.214 之前仍看到这条拒绝，可能是 ~/.claude/projects 里一个不可读的文件夹让转录扫描漏掉了已保存对话，更新到 v2.1.214 或更高。
• Terminal host process died：每个后台会话的终端在后台服务之下的宿主进程里运行，该进程在服务仍持有其连接时死了，会话无法到达（Linux 和 WSL 上后台服务会定期检查每个宿主进程）。在智能体视图里对失败的那一行按 Enter，会话在新的宿主进程上重启并恢复对话；或在 shell 里再次运行 claude attach <id>（会打印 terminal host died — restarting it on a fresh one… 并重新打开会话）；shell 命令行不能这样重启，要重新派发命令。（v2.1.247 之前死掉的宿主进程可能通过后台服务运行的所有存活检查，打开会话会一直显示 opening… · esc to cancel。）
• Session was stopped while the respawn was in flight：你打开了一个进程未运行的后台会话，Claude Code 重启它的过程中另一个 Claude Code 进程停掉了它（如另一个终端里的 claude stop），Claude Code 保持它停止。不是你停的，就在智能体视图再次打开那一行或运行 claude respawn <id> 重启；是你自己停的就不用做什么。同类还有「Session agent no longer available」：你恢复了一个运行自定义智能体（用 --agent 或 agent 设置启动）的会话，而 Claude Code 没找到该名称的智能体（先搜会话原始目录——若你信任该工作区——再搜你恢复所在的目录）。
• CLAUDE_CODE_PROCESS_WRAPPER launcher errors：设置了 CLAUDE_CODE_PROCESS_WRAPPER 而它的值不可用，Claude Code 拒绝启动受影响的进程，而不是不带启动器运行它；配置问题以变量名开头的消息报告。把变量设为以 exec "$@" 结尾的可执行文件的绝对路径（见启动器契约）；/status 在其 Self-exec 条目里显示解析后的启动命令，并在运行中的后台服务与之不符时警告，也可在 shell 里运行 claude daemon status；修好设置 env 块里的值后用 claude daemon stop --any 重启后台服务，让下次派发启动一个带包装的。
• EUNKNOWN when starting a background session：Windows 以一个没有标准名称的错误码拒绝启动某个程序，失败表现为 EUNKNOWN；常见触发是软件限制策略（如组策略或 AppLocker）阻止了要启动的程序。消息读作 Couldn't start the session 时升级到 v2.1.212 或更高（更早的版本也可以先在另一个终端运行 claude daemon run——它在终端前台运行后台服务，服务只在该终端开着时存在——再启动后台会话）；npm 安装正在替换二进制时，等它完成再启动；v2.1.212+ 仍出现且没有 npm 安装在运行，见官方说明。
• EACCES when starting a background session：Claude Code 无法运行它自己的二进制来启动承载后台会话的后台服务。npm 安装上这通常表示 npm install -g @anthropic-ai/claude-code 此刻正在替换该二进制（不管是你运行的还是自动更新）。等几秒再打开会话或重新派发（消息说 Claude Code 正在更新时，等更新完成后重试）；没有 npm 安装在运行而错误仍在，说明你的用户无法运行已安装的二进制，检查它及其目录的权限，或重新安装 Claude Code。
• Background service exited before it became reachable：Claude Code 作为后台服务启动的进程在接受连接之前退出，所以无法打开会话（服务在退出前打印了错误时，括号里的原因给出退出码或信号和第一行）。消息引用了一行就修好它点名的问题，再打开会话或重新派发（下次尝试会重新启动服务）；运行 claude daemon status 检查服务当前是否在运行。
• Working directory no longer exists when starting a background session：你启动后台会话的目录在会话启动期间被删除；Claude Code 不启动会话，消息点名缺失的目录（v2.1.257 之前会话看似启动，随后在智能体视图里显示为失败）。重建消息点名的目录，或从一个存在的目录派发，再试。
• Workspace not trusted when dispatching a background session：你在未信任的目录里启动或重启后台会话，而工作区信任对话框无法出现来询问你，Claude Code 不启动会话。在消息点名的目录里运行 claude 并接受信任对话框，再重新运行命令；主目录的消息就从主目录的终端运行命令让对话框能出现，或改从项目目录启动会话；could not be resolved on disk 的消息就重建该目录，或从存在的目录启动新会话。

Wrapper 与 IDE 错误

来自替你启动 Claude Code 的程序（如 IDE 扩展或 Agent SDK 应用），而不是 Claude Code 本身。

• Claude Code process exited with code N：底层 claude 进程以非零码退出。退出码本身说明不了什么失败：真正的错误在进程自己的输出里（wrapper 捕获到时会附上，否则保存在它的日志里）。在 VS Code 里按错误旁边的 View output logs 链接查看底层失败；在 Agent SDK 应用里围绕你的消息循环捕获该错误（官方「CLI process exit」下列出了各 SDK 语言收到什么）；在同一项目的终端里运行 claude，失败通常会在那里带着真实错误消息复现，再到本页查找；在终端运行 claude doctor 检查安装和配置。另有「Could not locate the …」等启动器定位二进制失败的消息。

回退与会话保存警告

• Restored the code, but skipped N files / No files were restored：来自 /rewind 的代码恢复。前者是警告：Claude Code 跳过了某些路径，没有通过它们写入或删除（路径是、或变成了符号链接、硬链接或其他非普通文件；其目录自检查点以来变了；其备份无法被安全读取），被跳过的路径保持当前内容；后者是错误：什么也没恢复。（v2.1.216 之前 /rewind 会穿过被跟踪路径上的链接写入和删除，且不报告部分恢复。）
• Transcript writes are failing：Claude Code 在你工作时把转录保存到磁盘，对转录文件的写入失败了；消息带着底层错误码点名原因（如磁盘已满）；会话照常工作，警告只是说这个会话以后可能不出现在 --resume 里。修好错误码指出的条件：ENOSPC 释放磁盘空间，EDQUOT 调高或清理配额，EACCES、EPERM、EROFS 恢复对转录位置的写权限；警告在下一次成功写入时自行消失，无需重启；警告显示期间发送的消息，以后恢复会话时可能仍然缺失。
• Transcript saving is off because CLAUDE_CODE_SKIP_PROMPT_HISTORY is set：本会话启动时设置了 CLAUDE_CODE_SKIP_PROMPT_HISTORY，所以转录不保存、也不会出现在 --resume 里；这是该变量的预期效果，取消设置它即可恢复保存。

配置警告

Claude Code 把这些消息大多写到 stderr 而不是对话里，且大多在启动时；个别出现在别处（调试日志、对话视图里的启动通知，或请求时的未识别模型诊断行）时条目里会注明。

• Claude Code exited after an unrecoverable interface error：终端界面遇到无法恢复的错误而退出（两种渲染器都可能；第二句只在全屏渲染器启动时出错才出现）。重新启动 Claude Code（可用 --continue 之类拿回对话）。
• Workspace has not been trusted：Claude Code 在项目的 .claude/settings.json 或 .claude/settings.local.json 里发现 permissions.allow 规则或 permissions.additionalDirectories 条目却没有应用，因为项目设置里的 allow 规则需要工作区信任。在该目录运行 claude 并接受信任对话框；非交互 -p 模式不显示对话框，用消息打印的确切 projects 键在 ~/.claude.json 里设置 hasTrustDialogAccepted 条目；消息点名 .claude/settings.local.json 且你在 git 仓库之外或主目录启动 Claude Code 时，更新到 v2.1.200 或更高（v2.1.196 到 v2.1.199 会把你自己的 .claude/settings.local.json 当作仓库提供的；v2.1.207 及以上，在 git 仓库之外且你没有信任该文件夹时，光更新还不够，要用第一步，因为判断文件夹不在仓库里要运行 git，而 Claude Code 只在你接受信任对话框之后才做这项检查）。
• Working directory is a network path：Claude Code 不把网络路径添加为工作目录：查找网络路径可能联系它点名的主机，Windows 上这种联系可能把你的凭证发给该主机，所以拒绝该路径而不去查找。Windows 上把共享映射到盘符（如 net use Z: \\server\share），启动时用 claude --add-dir Z:\ 传入；macOS 或 Linux 把共享挂载到本地路径并添加那个路径；路径在 permissions.additionalDirectories 里就从列出它的设置文件里删掉。（v2.1.257 之前接受可达的网络路径作为工作目录。）另有「Remote managed settings failed to load」：你的会话有资格使用服务端托管设置，但加载失败。
• headersHelper not run：Claude Code 只用静态 headers 连接了某 MCP 服务器，跳过了它的 headersHelper，因为 helper 是 shell 命令而该文件夹没有已保存的信任（手动在 ~/.claude.json 里设置了条目，或接受了该文件夹的信任对话框，文件夹才获得已保存信任）。在消息点名的文件夹运行 claude、接受信任对话框，再运行你的 -p 或 SDK 命令；或用消息打印的确切 projects 键自己设置 ~/.claude.json 里的 hasTrustDialogAccepted 条目；在主目录启动的会话要改在你信任的项目目录里工作（在主目录接受信任对话框时，Claude Code 只在当前会话里保持该信任）。相关的「Malformed Tool(content) rule」：你某个设置里的权限规则格式不正确。
• Is not matched by file permission checks：Claude Code 在设置文件、托管设置或 --allowedTools、--disallowedTools、--settings 标志值里发现带路径的 Write、NotebookEdit、MultiEdit 或 Glob 权限规则，而它按 Read 和 Edit 来检查文件权限。把 Write(path)、NotebookEdit(path) 和旧的 MultiEdit(path) 规则换成 Edit(path)（Edit 规则覆盖所有文件编辑工具）；把 Glob(path) 规则换成 Read(path)（--allowedTools 里 Claude Code 接受 Glob 规则而不警告）；在括号里点名的来源处修这条规则（设置文件路径，或 --allowed-tools/--disallowed-tools 标志本身；磁盘上不存在的 claude-settings-<id>.json 路径代表内联的 --settings 值）。
• Has a wildcard before the rest of the command：Claude Code 发现某条 Bash allow 规则里的 * 出现在后面决定是哪条命令的词之前，如 Bash(git * main) 或 Bash(git -C * status *)，这样的规则可能匹配得比你想的宽。把子命令之前的 * 换成你想要的确切值：Bash(git checkout main) 代替 Bash(git * main)；把每个 * 放到子命令之后：Bash(git status *) 代替 Bash(git -C * status *)，为想允许的每个子命令各写一条规则；在警告括号里点名的来源处修复。
• Stale sandbox mask files left by a killed session：claude doctor 在诊断里打印这条警告，/status 也列出同一行；出现在启用了沙箱且开启文件系统隔离的 Linux 和 WSL2 上：沙箱命令运行期间，沙箱对一个不存在的文件持有写拒绝（占位文件），会话被杀时这些占位文件可能被遗留下来。退出该项目里运行的其他 Claude Code 会话，用 rm 逐个删掉列出的文件（警告最多点名三个并统计其余，删完后重跑 claude doctor 直到警告消失；别的会话沙箱仍在使用的占位文件是那个会话写保护的有效组成部分）；你用「Yes, and don't ask again」保存的权限选择没生效，就在删掉占位文件后重新保存。（v2.1.257 之前 claude doctor 不标记这种情况。）

回复质量似乎低于平时

回答比预期弱却没有错误提示时，原因通常是对话状态而不是模型本身。Claude Code 不会悄悄更换模型版本，但在这些情况下可能切到回退模型：配置的 --fallback-model 在可用性错误后接管（只限该回合，转录里有通知）；Bedrock 或 Agent Platform 的启动检查发现默认模型不可用、或账号在会话中途失去访问；Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5、Opus 5 的自动模型回退把会话移到被标记类别的回退模型（转录里有通知）。先检查：模型选择——/model 确认是你期望的模型（之前的 /model 选择或 ANTHROPIC_MODEL 环境变量可能让你在用更小的模型）；努力等级——/effort 查看当前推理级别，疑难调试或设计工作调高（默认值因模型而异）；上下文压力——/context 看窗口多满，接近上限就在自然断点 /compact 或 /clear 重新开始；陈旧指令——庞大或过时的 CLAUDE.md 和 MCP 工具定义占用上下文并会带偏回复，/doctor 体检会标记过大的记忆文件和未使用的扩展，/context 显示 MCP 工具的 token 用量。回复出错时回退通常比用回复纠正更有效：按两次 Esc 或运行 /rewind 退回到坏回合之前，再用更具体的说法重写提示——在对话里纠正会把错误的尝试留在上下文里，可能让后面的回答被它锚定。检查之后质量仍不对，运行 /feedback 描述你期望的和实际得到的；这样提交的反馈包含对话转录，是让 Anthropic 调查的最快办法。

上报错误

本页没有覆盖的组件的错误，见相应指南：MCP 服务器连接或认证失败见 MCP；Hook 脚本失败或阻止了工具见调试 Hook；安装期间的权限拒绝或文件系统错误见安装与登录故障排查。错误没有列在这里、或建议的办法没用时：在 Claude Code 里运行 /feedback，把转录和描述发给 Anthropic（该命令还会提议打开预填的 GitHub issue）；发送给 Anthropic 需要认证，在 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 等第三方服务商上、或没有配置 Anthropic 凭证时，/feedback 不可用，改用官方 GitHub 仓库提 issue。