【Bug已解决】Claude Code freezes on startup / Hangs at initialization — Claude Code 启动冻结解决方案1. 问题描述运行claude命令后终端卡在初始化阶段长时间无响应$ claude # 光标闪烁但没有任何输出 # 等待 30 秒以上仍无响应 # CtrlC 可以中断 # 或卡在加载步骤 $ claude Loading configuration... # 卡在这里不动 # 或卡在 MCP 初始化 $ claude Initializing MCP servers... # 卡住不继续这个问题在以下场景中特别常见MCP Server 启动失败导致等待网络问题导致 API 连接超时settings.json 格式错误导致解析卡住磁盘 I/O 慢如网络挂载盘Node.js 内存不足导致 GC 卡顿多个 MCP Server 串行初始化慢2. 原因分析核心原理拆解claude 启动 → 加载配置 → 初始化 MCP → 连接 API ↓ 某个步骤卡住MCP/网络/配置/磁盘 ↓ 启动冻结原因分类表原因分类具体表现占比MCP Server 慢等待 MCP 启动约 40%网络超时API 连接慢约 25%配置解析settings.json 问题约 15%磁盘 I/O网络盘慢约 10%内存不足GC 卡顿约 5%会话加载大会话文件约 5%3. 解决方案方案一使用 --debug 诊断卡住位置最推荐# 步骤 1使用 debug 模式启动 claude --debug 21 | head -50 # 查看卡在哪个步骤 # 步骤 2如果卡在 MCP 初始化 claude --debug 21 | grep -i mcp # 步骤 3如果卡在 API 连接 claude --debug 21 | grep -i api\|connect\|fetch # 步骤 4根据卡住的位置针对性解决方案二禁用 MCP Server 启动# 步骤 1临时禁用所有 MCP claude --no-mcp # 步骤 2如果 --no-mcp 后启动正常 # 说明是 MCP Server 导致的冻结 # 步骤 3逐个排查 MCP Server claude mcp list # 逐个移除测试 claude mcp remove server_name claude # 测试启动 # 步骤 4找到问题 MCP 后 # 修复或替换该 MCP Server方案三检查网络连接# 步骤 1测试 API 连通性 curl -I https://api.anthropic.com --max-time 10 # 步骤 2如果 curl 也慢检查 DNS 解析 nslookup api.anthropic.com dig api.anthropic.com short # 步骤 3测试不同 DNS 服务器 curl --resolve api.anthropic.com:443:$(dig short api.anthropic.com 8.8.8.8) \ -I https://api.anthropic.com --max-time 10 # 步骤 4检查系统时间偏差TLS 握手依赖时间同步 date curl -sI https://api.anthropic.com | head -1 # 如果系统时间偏差超过 5 分钟TLS 握手会失败导致卡住方案四检查配置文件# 步骤 1验证 settings.json 格式 python3 -m json.tool ~/.claude/settings.json # 步骤 2如果格式错误修复 # 参考 C47 解决方案 # 步骤 3临时移除配置测试 mv ~/.claude/settings.json ~/.claude/settings.json.bak claude # 如果启动正常说明配置有问题 # 步骤 4逐步恢复配置项方案五检查磁盘和会话文件# 步骤 1检查磁盘空间 df -h ~ # 步骤 2检查会话文件大小 du -sh ~/.claude/sessions/ # 步骤 3如果会话文件过大 find ~/.claude/sessions/ -type f -size 50M -delete # 步骤 4如果磁盘满 # 清理空间 find ~/.claude/logs/ -type f -mtime 3 -delete方案六增加启动超时# 步骤 1设置更长的启动超时 export CLAUDE_STARTUP_TIMEOUT60000 # 60 秒启动超时 # 步骤 2永久设置 echo export CLAUDE_STARTUP_TIMEOUT60000 ~/.zshrc source ~/.zshrc # 步骤 3启动 claude4. 各方案对比总结方案适用场景推荐指数难度方案一--debug诊断⭐⭐⭐⭐⭐低方案二禁用 MCPMCP 问题⭐⭐⭐⭐⭐低方案三检查网络网络问题⭐⭐⭐⭐⭐低方案四检查配置配置问题⭐⭐⭐⭐低方案五磁盘/会话I/O 问题⭐⭐⭐⭐低方案六增加超时慢启动⭐⭐⭐低5. 常见问题 FAQ5.1 Claude Code 启动正常需要多久通常 2-5 秒。如果超过 10 秒说明有问题。5.2 MCP Server 为什么导致启动冻结Claude Code 启动时会初始化所有 MCP Server。如果某个 Server 启动慢或卡住整个启动被阻塞。5.3 --no-mcp 是什么跳过 MCP Server 初始化。如果--no-mcp后启动正常说明是 MCP 问题。5.4 如何找到导致冻结的 MCP Server逐个移除 MCP Server 测试claude mcp list # 列出所有 claude mcp remove server1 # 移除一个 claude # 测试 # 逐个测试找到问题 Server5.5 网络问题如何排查curl -I https://api.anthropic.com --max-time 10 # 如果超时说明网络有问题5.6 会话文件过大导致启动慢大会话文件50MB加载需要时间。清理旧会话find ~/.claude/sessions/ -type f -size 50M -delete5.7 settings.json 格式错误导致冻结JSON 解析可能卡住或抛异常。用python3 -m json.tool验证格式。5.8 Docker 中启动冻结Docker 容器可能缺少依赖或网络不通。使用docker run -it查看输出。5.9 企业服务器启动冻结企业服务器网络限制可能导致 API 连接超时。检查网络规则和 DNS 配置确保api.anthropic.com可解析且端口 443 出站未被拦截。5.10 排查清单速查表□ 1. claude --debug 查看卡住位置 □ 2. claude --no-mcp 测试是否 MCP 问题 □ 3. curl -I https://api.anthropic.com 测试网络 □ 4. python3 -m json.tool 验证 settings.json □ 5. mv settings.json 测试无配置启动 □ 6. df -h 检查磁盘空间 □ 7. du -sh ~/.claude/sessions/ 检查会话大小 □ 8. 清理 50M 的会话文件 □ 9. 设置 CLAUDE_STARTUP_TIMEOUT □ 10. 逐个移除 MCP Server 排查6. 总结根本原因启动冻结最常见原因是 MCP Server 启动慢40%和网络连接超时25%最佳实践使用claude --debug 21 | head -50诊断卡在哪个步骤针对性解决MCP 排查使用claude --no-mcp测试——如果启动正常说明是 MCP Server 问题逐个移除排查网络检查用curl -I https://api.anthropic.com --max-time 10测试 API 连通性排除网络问题最佳实践建议定期清理~/.claude/sessions/中超过 50MB 的大会话文件避免启动时加载缓慢故障排查流程图flowchart TD A[启动冻结] -- B[claude --debug 诊断] B -- C{卡在哪个步骤?} C --|MCP 初始化| D[claude --no-mcp 测试] C --|API 连接| E[curl 测试网络] C --|配置加载| F[验证 settings.json] C --|会话加载| G[检查会话文件] D -- H{--no-mcp 后正常?} H --|是| I[逐个移除 MCP 排查] H --|否| J[检查网络和配置] E -- K{curl 成功?} K --|否| L[修复 DNS/网络] K --|是| M[检查 API Key] F -- N{JSON 格式正确?} N --|否| O[修复 JSON] N --|是| P[移除配置测试] G -- Q{文件 50MB?} Q --|是| R[清理大会话文件] Q --|否| S[检查磁盘空间] I -- T[找到问题 MCP] L -- U[✅ 启动成功] M -- U O -- U P -- U R -- U S -- U T -- U
