跳转至

故障排除

社区报告的当前 Claude Code 缺陷的变通方案，这些缺陷可能影响 ECC 用户。

这些是上游 Claude Code 的行为，而不是 ECC 缺陷。以下条目总结了在 Claude Code v2.1.79（macOS、大量使用钩子、启用 MCP 连接器）上收集的、经过生产环境验证的变通方案，见 issue #644。在上游修复落地之前，请把它们视为务实的临时措施。

针对未解决 Claude Code 缺陷的社区变通方案

在其他方面成功的钩子上出现错误的 “Hook Error” 标签

症状： 钩子运行成功，但 Claude Code 仍在转录中显示 Hook Error。

有帮助的做法：

  • 在钩子开始时消费 stdin（在 shell 钩子中使用 input=$(cat)），以便父进程不会看到未消费的管道。
  • 对于简单的允许/阻止钩子，将人类可读的诊断信息发送到 stderr，并保持 stdout 安静，除非你的钩子实现明确要求结构化 stdout。
  • 当子进程的 stderr 噪音不可操作时，将其重定向。
  • 使用正确的退出码：0 允许，2 阻止，其他非零退出被视为错误。

示例：

# Good: block with stderr message and exit 2
input=$(cat)
echo "[BLOCKED] Reason here" >&2
exit 2

使用 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 时压缩早于预期

症状： 降低 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 会导致压缩更早发生，而不是更晚。

有帮助的做法：

  • 在某些当前 Claude Code 构建中，较低的值可能会降低压缩阈值，而不是延长它。
  • 如果你想要更多工作空间，请移除 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE，并优先在逻辑任务边界处手动使用 /compact。
  • 使用 ECC 的 strategic-compact 指南，而不是强制设置更低的自动压缩阈值。

MCP 连接器看起来已连接，但在压缩后失败

症状： 即使连接器在 UI 中仍然看起来已认证，Gmail 或 Google Drive MCP 工具在压缩后也会失败。

有帮助的做法：

  • 在压缩后，将受影响的连接器关闭再重新打开。
  • 如果你的 Claude Code 构建支持，添加一个 PostCompact 提醒钩子，在压缩后提醒你重新检查连接器认证。
  • 将此视为认证状态恢复步骤，而不是永久修复。

钩子编辑不会热重载

症状： 对 settings.json 钩子的更改在会话重启之前不会生效。

有帮助的做法：

  • 更改钩子后，重启 Claude Code 会话。
  • 高级用户有时会围绕 kill -HUP $PPID 脚本化一个本地 /reload 命令，但 ECC 不提供该功能，因为它依赖 shell 且并非普遍可靠。

重复的 529 Overloaded 响应

症状： 在高钩子/工具/上下文压力下，Claude Code 开始失败。

有帮助的做法：

  • 如果你的设置支持，使用 ENABLE_TOOL_SEARCH=auto:5 降低工具定义压力。
  • 对于常规工作，降低 MAX_THINKING_TOKENS。
  • 如果你的设置暴露该选项，将子代理工作路由到更便宜的模型，例如 CLAUDE_CODE_SUBAGENT_MODEL=haiku。
  • 按项目禁用未使用的 MCP 服务器。
  • 在自然断点处手动压缩，而不是等待自动压缩。

ECC 仪表盘无法启动

症状： npm run dashboard 或 python3 ecc_dashboard.py 失败，通常伴随 ModuleNotFoundError: No module named 'tkinter'。

有帮助的做法：

  • GUI 仪表盘需要 Tkinter，许多 Python 安装会省略它：
  • Debian/Ubuntu: sudo apt-get install python3-tk
  • Fedora: sudo dnf install python3-tkinter
  • macOS (Homebrew): brew install python-tk
  • Windows: 重新运行 python.org 安装程序并启用 “tcl/tk and IDLE”
  • 或者使用浏览器仪表盘，它只需要 Node：npm run dashboard:web，然后打开打印的 localhost URL。
  • 两个命令都必须从 ECC 仓库的完整克隆（git clone https://github.com/affaan-m/ECC）中运行，而不是从 Claude Code 插件目录内部运行——插件安装不包含 package.json 脚本。

Anthropic Cyber Safeguards 阻止对你自己代码的安全审计

症状： 运行安全审查/审计（例如 ecc:security-reviewer）会因 API 错误而失败，错误引用使用政策和 “cyber-related safeguards”，即使你审计的是自己的代码库。

有帮助的做法：

  • 这是上游 Anthropic 模型级保障措施，不是 GateGuard，也不是 ECC 阻止。没有任何 ECC 配置可以绕过它。
  • 申请 Anthropic 的 Cyber Verification Program——错误信息中包含你账户的令牌化链接。获批账户可以解锁合法的安全工作流。
  • 在获批之前，防御性地构造提示：一开始就说明你拥有该代码，目标是修复（“审查我拥有的这个模块中的漏洞并提出修复方案”），将范围限制为一次一个模块，并避免利用生成措辞（“编写 PoC”、“构造 payload”）。
  • 优先使用以修复为导向的技能（security-review、security-scan），而不是进攻性框架，并自行运行静态工具（semgrep、bandit、npm audit），然后让模型解释结果。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC