Claude Code 故障排查

解决： 确保已安装 Git for Windows。如仍找不到，可用原生安装器代替——但 claude.ai 需要科学上网（如暂时没有条件，可到 B站或其他网络平台搜索 'Claude Code 国内安装' 或 'CC Switch 代装' 了解替代方案）。原生安装命令：在 PowerShell 运行 irm https://claude.ai/install.ps1 | iex

解决： 以管理员身份运行 PowerShell（右键 → 以管理员身份运行）。或先运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

解决： 先访问 brew.sh 安装 Homebrew（raw.githubusercontent.com 国内可能无法访问，可搜索{'Homebrew 国内镜像'}安装），或改用原生安装器（⚠️ 需科学上网）：curl -fsSL https://claude.ai/install.sh | bash

解决： 关闭终端重新打开。检查 PATH 环境变量。Windows 用户确认 Git Bash 已安装并在 PATH 中。

解决： 检查具体报错信息。英文提示通常可直接搜索到答案。如果无论如何都装不上，可尝试 CC Switch 代装 了解替代方案。

解决： 排查步骤：① 检查 API Key 完整无误；② 检查 DeepSeek 账户余额；③ 检查 ANTHROPIC_BASE_URL 正确（不要用 /v1 路径）；④ 浏览器访问 api.deepseek.com 确认可达；⑤ 确认 JSON 格式正确。

解决： ① 检查 JSON 格式（无多余逗号、引号匹配），可在终端运行 python -m json.tool ~/.claude/settings.json 自动校验；② 确认文件路径正确；③ 完全退出 Claude Code（包括后台进程）后重新启动。

解决： 在 settings.json 的 env 中添加 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1。这是 DeepSeek 端点的已知问题，2026 年 5 月起需要此配置。

解决： 在 settings.json 的 env 中添加 timeout: 600000（10 分钟）。可根据任务复杂度调整。

解决： ① 确认 CC Switch 版本 ≥ 3.15.0；② 检查 settings.json 中 ANTHROPIC_AUTH_TOKEN 为 PROXY_MANAGED；③ 完全退出 CC Switch（含系统托盘图标）后重新打开；④ CC Switch 开启时会覆盖 settings.json 手动配置，两者不要混用。

解决： 确认 settings.json 中设置了 CLAUDE_CODE_SUBAGENT_MODEL（如 deepseek-v4-flash[1m]）。子代理需要独立模型配置，缺少此项时并行任务会失败。

解决： 这是 Claude Code 的已知问题——backups 缓存（~/.claude/backups/）会劫持 MCP 配置的读取，优先级高于你手动编辑的 mcp.json。① 先用 claude mcp list 确认当前实际加载的配置——进程接收到的命令行参数就是实际生效的配置；② 如果与预期不符，检查 ~/.claude/backups/ 是否缓存了旧备份，删除过期的 backup 文件；③ 检查 ~/.claude.json（与项目同目录）中是否残留同名服务器的旧 mcpServers 条目——如有则同步修改或删除；④ 改完配置后完全退出 Claude Code（含后台进程）再重启。详见本站<a href='/articles/mcp-config-pitfall-guide' style={{ color: 'var(--color-accent)' }}>《MCP 配置避坑指南》</a>。

解决： 两种安装方式共享 settings.json 但权限模型不同。① VS Code 插件的终端权限受 VS Code 自身沙箱限制——某些系统级命令在插件中不可用；② 插件版的工作目录和 CLI 版可能不同——检查终端中的 pwd 确认路径；③ 插件版的 MCP 服务器进程由 VS Code 管理——如果 MCP 依赖特定环境变量，在 VS Code Settings 中配置而非系统级环境变量；④ 排查时先用 CLI 版测试——CLI 版环境更干净，能快速确定问题出在配置还是 VS Code 沙箱。

解决： 这是国内网络环境的普遍情况——Anthropic 相关域名在中国大陆无法直连。如果已有科学上网工具，可在终端设置代理（以 Clash 为例，端口通常是 7890）：export HTTPS_PROXY=http://127.0.0.1:7890 && export HTTP_PROXY=http://127.0.0.1:7890。如果还没有科学上网工具，可到 B站或其他网络平台搜索"科学上网"或"Claude Code 国内网络"了解可行的解决方案。日常使用推荐配置 DeepSeek 等国内模型（详见配置指南），配置后无需科学上网即可正常使用 Claude Code。

解决： DeepSeek API 国内通常可直连。设置 NO_PROXY 排除：export NO_PROXY=api.deepseek.com,localhost,127.0.0.1

解决： 需从 Anthropic 服务器下载约 2.5GB 的 Linux 环境文件，国内网络通常连不上。如不需要 Cowork 功能可忽略此消息。如需修复，可到 B站 或其他网络平台搜索 'Claude Desktop VM 文件' 查找热心用户分享的资源。

解决： ① 确保 CC Switch 版本 ≥ 3.15.0；② 检查 settings.json 存在且包含 ANTHROPIC_AUTH_TOKEN: PROXY_MANAGED；③ 完全退出 CC Switch（含托盘图标）后重新打开。

解决： ⚠️ 此问题暂无通用解决方案。尝试：① 完全退出 Claude Desktop（含托盘 + 任务管理器进程）；② 确保 CC Switch 版本 ≥ 3.15.0 且路由已开启；③ 重新打开 Claude Desktop；④ 如仍不行：完全卸载 → 重启电脑 → 重新安装。

解决： 三种方式：① 通过 Claude 页面提示操作；② 管理员 PowerShell 运行 Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All -NoRestart；③ 手动：控制面板 → 程序和功能 → 启用或关闭 Windows 功能 → 勾选「Hyper-V」和「虚拟机平台」→ 重启。

解决： 原因是国内网络无法从 Anthropic 服务器下载约 2.5GB 的 Linux 环境文件（解压后约 13GB）。如果不需要 Cowork 功能可忽略此消息。如需修复：① 启用 Hyper-V 和虚拟机平台；② 获取 VM 文件包（可到 B站 或其他网络平台搜索 'Claude Desktop Workspace 文件' 查找资源）；③ 放入 Claude 指定目录；④ 务必先重启电脑再打开 Claude Desktop。

解决： ① 设置 → 应用 → 应用和功能 → 搜索 Claude → 卸载；② 删除 %LOCALAPPDATA%\Claude 目录（如有残留）；③ 检查任务管理器确认无 Claude 进程；④ 重启电脑完成清理。

解决： 以管理员身份运行安装包（右键 → 以管理员身份运行）。注意：桌面版无法指定安装位置，默认安装到系统盘。