Auto-Claude Troubleshooting 是 Auto-Claude 的综合调试指南，面向需要排查安装、构建、智能体运行等环节故障的使用者。
用途 当出现安装失败、构建失败、智能体报错或需要诊断异常时使用本指南。它按问题类型组织排查步骤，先做快速诊断，再深入到具体故障分支。
快速诊断 先检查系统要求：Python 版本（需 3.12+）、Node.js 版本（需 24+）、Claude Code CLI（claude --version）以及 Git 版本。随后验证安装：进入 apps/backend，激活虚拟环境（source .venv/bin/activate 或 .venv\Scripts\activate），检查 Python 版本，测试导入 python -c "from core.client import create_client; print('OK')"，并用 pip list | grep claude-agent-sdk 确认依赖。再检查配置：读取 .env 中的环境变量、查看 OAuth token（echo $CLAUDE_CODE_OAUTH_TOKEN | head -c 20）、运行 claude --version。
常见问题分类 安装问题：例如 Python 版本过旧（如 3.9.7），修复方式包括用 brew、apt 或 winget 安装 Python 3.12，并用 python3.12 -m venv .venv 重建虚拟环境后安装依赖；Windows 上 node-gyp rebuild failed 需安装 Visual Studio Build Tools 的“Desktop development with C++”；权限被拒时可用 sudo 安装或重新配置 npm 前缀。
认证问题：OAuth token 无效时用 claude setup-token 重新生成并写入 apps/backend/.env；token 未设置时手动 export 或写入 .env；订阅相关报错需在 https://claude.ai/upgrade 确认 Pro 或 Max 订阅有效。
构建失败：Spec 未找到时用 python run.py --list 列出可用 spec，检查 .auto-claude/specs/ 目录，或先用 python spec_runner.py --interactive 创建；智能体超时可用 API_TIMEOUT_MS=600000 或写入 .env 延长；构建卡住时查看 build-progress.txt，检查并删除 PAUSE 文件，或写入 HUMAN_INPUT.md 提供人工输入；安全钩子拒绝时可查看 .auto-claude-security.json 并在 security.py 的允许列表中添加命令。
工作区问题：worktree 已存在时用 git worktree remove（可加 --force）并 git worktree prune；分支已存在时用 git branch -D 删除；合并冲突时进入 worktree 手动执行 git merge main --no-commit，解决后 git add 与 git commit 完成合并。
内存系统问题：Graphiti 初始化失败时检查 .env 中的 GRAPHITI 开关与提供方凭据（OpenAI 或 Ollama 的连通性测试命令）；嵌入维度不匹配时删除 ~/.auto-claude/memories/embeddings 后重新索引；数据库损坏时备份并重置 ~/.auto-claude/memories，再用 python query_memory.py 生成新库。
QA 问题：QA 循环不结束时查看 qa_report.md，可用 --skip-qa 临时跳过或用 MAX_QA_ITERATIONS 限制迭代；QA Fixer 未修复时查看 QA_FIX_REQUEST.md，并通过 HUMAN_INPUT.md 补充人工指引。
调试与恢复 调试模式支持分级日志：DEBUG=true 配合 DEBUG_LEVEL=1/2/3，可用 DEBUG_LOG_FILE 输出到文件，并用 tail -f 或 tee 结合 grep 检索错误。恢复流程包括对某个 spec 的完整重置（删除 spec 目录、worktree 与分支后重建），用 python spec_runner.py --continue 001-feature 从检查点继续，以及通过 PAUSE 文件配合 worktree 内手动提交实现人工干预。
性能与求助 性能方面可通过 AUTO_BUILD_MODEL 切换模型、减少思考 token、SKIP_RESEARCH_PHASE 跳过研究阶段、MAX_CONTEXT_FILES 降低上下文、使用更小的嵌入模型（如 OLLAMA_EMBEDDING_MODEL=all-minilm）等方式优化；遇到速率限制可等待重试或更换 ANTHROPIC_BASE_URL。求助时可收集系统信息、Auto-Claude 版本与日志尾部内容，并提供了 Discord、GitHub Issues 与 Discussions 渠道，报告 bug 建议附带操作系统、Python 与 Node 版本、复现步骤、错误信息与相关日志。
相关技能 另见 auto-claude-setup（安装指南）、auto-claude-cli（CLI 参考）、auto-claude-optimization（性能调优）。
限制 本资料未提供支持平台范围的完整清单、各项命令在不同系统上的差异细节以及除上述渠道外的官方支持条款，相关事实暂未提供。