Skip to main content
使用本指南修复常见的 CC Safety Net 安装和行为问题。先运行 status 查看快速判定，再运行 doctor 查看完整报告。

​
先运行诊断

status 输出运行时判定（ready 或 degraded）、生效的保护和安全级别、策略路径，并为每个未解决的问题各列出一条。已禁用的 Claude Code 插件显示为第一个 Not active 项，而不是单独的判定。status 仅供参考，退出码始终为 0。
doctor 会检查每个受支持的智能体，包括 hook 集成、阻止功能自检、自定义规则、生效的模式标志、近期活动、系统版本和可用更新。它是唯一同时报告规则配置和 policy.json 的命令。各项检查的作用见 doctor 命令参考。 逐一处理下面的问题之前，请先通读输出，大多数问题在这里就能看出来。
degraded 表示某个配置来源被拒绝，改由安全的替代配置生效。它不表示命令会被阻止。无效配置绝不会拒绝普通工作。详情见配置恢复。

​
常见问题

如果本应被阻止的命令没有受到任何拦截就直接执行，说明 hook 没有为你的智能体正确注册。解决步骤：
  1. 运行 npx cc-safety-net doctor。它会检查每个受支持智能体的 hook 集成，并在发现配置错误时指出确切的配置路径。
  2. 重新运行对应智能体的安装命令。对于有效的托管安装，此操作是幂等的，并会修复缺失或禁用的托管项。如果安装程序报告配置或文件无法识别、是符号链接，或由其他程序管理，请按它给出的手动恢复提示处理，不要覆盖它。各智能体的完整命令表见安装。
  3. Amp Code：运行 amp plugins list，确认有 cc-safety-net (User Plugins) 行且状态为 active。状态不是 active 时，在 Amp 中运行 plugins: reload，或用 install --amp 重新安装。遗留在 ~/.config/amp/plugins/cc-safety-net.ts 的本地文件会遮蔽个人插件。install --amp 会删除托管副本，遇到非托管文件则失败并给出可操作的错误提示。Amp 在启动时读取插件，因此更改后请重启 Amp 或运行 plugins: reload。
  4. Antigravity CLI：检查 ~/.gemini/config/hooks.json 中是否有执行 npx -y cc-safety-net hook --agy-cli 的托管 PreToolUse 项。
  5. Claude Code：在 /plugin 中确认 cc-safety-net 已安装并启用。若不存在，运行 /plugin install cc-safety-net@cc-marketplace，再运行 /reload-plugins。
  6. Codex：运行 codex plugin list，确认 cc-safety-net@cc-marketplace 一行显示 installed, enabled。然后在 TUI 中运行 /hooks，选择 cc-safety-net PreToolUse hook，按 t 将其标记为受信任。未完成这一步时，hook 不会运行。
  7. Cursor：检查 ~/.cursor/hooks.json 是否有运行 npx -y cc-safety-net hook --cursor 的托管全局 preToolUse 项。
  8. Gemini CLI：运行 gemini extensions list，确认 https://github.com/kenryu42/gemini-safety-net 来源已安装并启用；User 和 Workspace 两个范围都要检查，设置了 Workspace 时以 Workspace 为准。使用 gemini extensions install https://github.com/kenryu42/gemini-safety-net 重新安装，然后开始新的 Gemini 会话。
  9. GitHub Copilot CLI：确认 /plugin 中已安装 cc-safety-net@cc-marketplace 插件，并在 ~/.copilot/settings.json 的 enabledPlugins 中启用它。对于 Copilot CLI 1.0.8+，请按以下优先顺序检查内联 hook 配置和 disableAllHooks：.github/copilot/settings.local.json、.github/copilot/settings.json、.claude/settings.local.json、.claude/settings.json、~/.copilot/settings.json、~/.copilot/config.json。首个定义 disableAllHooks 的文件决定结果：true 会禁用所有 hook，false 则阻止优先级更低的值生效。.claude 中的 hook 必须运行 cc-safety-net hook --copilot-cli 或 cc-safety-net hook -cp；普通 Claude Code hook 不会注册到 Copilot。~/.copilot/hooks/ 下的用户 hook 文件要求 Copilot CLI 0.0.422+。
  10. Grok Build：检查 ~/.grok/hooks/cc-safety-net.json（或 $GROK_HOME/hooks/cc-safety-net.json）中是否有运行 npx -y cc-safety-net hook --grok-build 的托管 PreToolUse 条目。如果缺失，请重新运行 npx -y cc-safety-net@latest install --grok-build。
  11. Hermes Agent：确认托管插件文件位于 $HERMES_HOME/plugins/cc-safety-net（未设置 HERMES_HOME 时为 ~/.hermes/plugins/cc-safety-net），并已用 hermes plugins enable cc-safety-net --no-allow-tool-override 启用插件。Hermes 只有在 config.yaml 中列出某个用户插件时才会加载它。然后重启 Hermes 让插件加载。doctor 只读取插件文件和 Hermes 配置，不会向运行中的 Hermes 查询插件是否真的已加载，因此任何更改之后都要重启并重新测试。
  12. Kimi Code：检查 ~/.kimi-code/config.toml（或 $KIMI_CODE_HOME/config.toml）中是否有在 PreToolUse Bash 上运行 npx -y cc-safety-net hook --kimi-code 的 [[hooks]] 块。如果缺失，请重新运行 npx -y cc-safety-net@latest install --kimi-code。
  13. OpenClaw：插件通过 OpenClaw 自己的 CLI 安装和启用。重新运行 npx -y cc-safety-net@latest install --openclaw 会运行 openclaw plugins install <plugin dir> --force 和 openclaw plugins enable cc-safety-net，然后确认插件已加载（详情由 openclaw plugins inspect cc-safety-net --runtime 显示）。随后重启 OpenClaw Gateway。若 openclaw.json 设置了 plugins.allow，其中也必须包含 cc-safety-net。doctor 只读取插件目录和 openclaw.json，不会向运行中的 Gateway 查询插件是否已加载，因此已停止的 Gateway 不会被报告为失败。
  14. OpenCode：如果已设置 XDG_CONFIG_HOME，请检查 $XDG_CONFIG_HOME/opencode/opencode.json（或 .jsonc）；否则检查 ~/.config/opencode/opencode.json（或 .jsonc）。确认 plugin[] 数组中包含 cc-safety-net。OpenCode 可能缓存旧版本。清除缓存的步骤见安装。
  15. Pi：确认 pi install npm:cc-safety-net 已完成，并已重启 Pi 让扩展加载。运行 npx cc-safety-net doctor 可直接探测 Pi。
  16. 做出任何更改后，都要重新加载或重启智能体会话。
如果不确定智能体使用哪种机制，请参阅集成架构。
正常的检查在 1 秒内完成。如果每条命令都要等上几秒，慢的是 cc-safety-net 包的解析，而不是分析本身。解决步骤：
  1. 确认你的智能体如何运行 hook。Claude Code 插件直接运行捆绑的副本，因此包解析不可能是原因。Antigravity CLI、Cursor、Grok Build、Hermes Agent 和 Kimi Code 的 hook 每条命令都运行 npx -y cc-safety-net，即使 npm 缓存健康，也会增加几百毫秒。
  2. 在智能体之外测量解析耗时：
    连续运行两三次。每次发布后的首次运行需要下载包，只会慢这一次；之后的运行应稳定在几百毫秒。
  3. 排除注册表延迟：
    如果加 --prefer-offline 很快而普通运行仍然很慢，说明 npx 在等待 npm 注册表响应。这是网络或代理问题，不是 CC Safety Net 的问题。
  4. 修复 npm 缓存：
    膨胀或损坏的缓存会拖慢每一次 npx 解析，包括已缓存的运行。npm cache verify 会对缓存做垃圾回收并修复。在促成本节的报告（issue #16）中，它回收了 5 GB 以上的空间，让 hook 恢复到 1 秒以内。
修复后重跑第 2 步的计时命令。之后的运行稳定在几百毫秒，就是经由 npx 的集成能达到的最快状态。
如果本应被阻止的命令却执行了，请按下面的清单逐项排查。多数情况是已记录的允许行为，或实际安全级别低于你的预期，而不是覆盖缺口。解决步骤：
  1. 运行 npx cc-safety-net explain "<the command>"，查看 CC Safety Net 对该命令的完整逐步分析。输出会列出检查过的规则和有效安全级别；如果某条规则存在但在当前级别未启用，规则激活行会说明这一点。
    真实跟踪不会自动变得可以安全分享。脱敏只覆盖可识别的凭证形式；命令文本、解析后的 token、包括主目录在内的绝对路径，以及策略文件路径都会原样保留。请用占位凭证复现，并在粘贴到任何地方之前先检查输出。
  2. 确认输出中的有效级别。standard 模式只提供尽力保护：它有意允许动态可执行文件名、通过替换拼接的命令结构、rm -rf "$target" 这类无法验证的递归删除目标，以及对内置敏感路径仅做元数据检查。如果命令可能来自提示注入或其他对抗性环境，请把级别提高到 strict 或 paranoid，它们对上述所有形式都会 fail closed。
  3. 检查命令是否属于明确允许的形式，例如当前工作目录内的 rm -rf 因为限定在项目范围内而默认允许。完整列表见被允许的命令。
  4. 运行 npx cc-safety-net status。degraded 判定表示某个规则来源已被丢弃，因此该来源贡献的拒绝规则不再生效。详情见配置恢复。
  5. 在同一份 status 输出中查找 Project policy 区块。项目的 .cc-safety-net/policy.json 削弱了用户策略时才会出现该区块，每个被削弱的字段占一行，例如 project policy lowers level: strict -> standard、project policy disables rule <id> 或 project policy adds destructive allow path: <path>。某条规则只在这个项目里不再触发、在别处照常触发，任何一行都可能是原因。状态行用 🔻 表示同一情况，doctor 则在 Project policy deltas: 下打印同样的行。
  6. 如果命令通过 CC Safety Net 不分析的代理运行，请用 npx -y cc-safety-net rule wrapper add <command> 注册它，让分析能穿过它看到真实的子命令。
  7. 如果需要在你的环境中阻止该命令，请运行 npx -y cc-safety-net rule init 创建自定义 rulebook，并向 .cc-safety-net/rules/project-rules/rulebook.json 添加规则。schema 见自定义规则。
  8. 如果以上都无法解释，那就是规则尚未阻止的一种命令形式，即覆盖缺口；按项目策略，这属于公开 bug。请提交 GitHub issue，说明命令形式，不要提供可直接粘贴的载荷。机密泄漏、预期目录外写入以及供应链或软件包完整性问题则走安全策略中的私密渠道。 附上第 1 步中经过审阅的 explain 跟踪，绝不要附上原始跟踪，也绝不要附上真实凭证。如果你遇到的是已记录的边界，已知限制会说明这一点，并指出改由哪一层来覆盖。
内置规则在设计上偏保守。如果你需要的命令被阻止，可以有几种处理方式。解决步骤：
  1. 运行 npx cc-safety-net explain "<the command>"，弄清它为什么被阻止、匹配了哪条规则。
  2. 如果拒绝原因是 Command analysis exceeds CC Safety Net's derived-command work limit. Reduce nested or embedded command complexity and retry.，说明没有规则匹配：命令耗尽了分析器为派生命令设定的固定工作预算，这类命令包括 find -exec、xargs 或 parallel 内的 shell 单行命令、隐藏在包装器后的嵌入命令，以及类似的嵌套形式。该预算是编译时常量，任何配置都无法提高。请把命令拆成几条更简单的独立命令，然后重试。
  3. 如果拒绝原因是 CC Safety Net could not analyze the command because it exceeds safe analysis limits. Simplify or split the command and retry.，同样说明没有规则匹配：命令越过了固定的路径规范化预算或 shell 结构预算。触发它的命令，要么带有足以耗尽路径规范化预算的类路径 token，要么内联 shell 函数的次数超出投影的 256 个调用点上限，要么 heredoc body 的嵌套超过解析器允许的层数。该预算同样是编译时常量，任何配置都无法提高。请简化或拆分命令，然后重试。
  4. 如果拒绝原因是 CC Safety Net failed closed because command analysis failed unexpectedly. This is not caused by your command. Report it to the user.，说明分析遇到的是内部故障，而不是超出预算。改写命令解决不了问题，按原因所说直接报告即可。
  5. 如果拒绝原因是 CC Safety Net could not use the requested working directory because it does not exist, is inaccessible, is not a directory, or uses an unsupported path form. Use an existing accessible working directory. If the requested directory is missing, create it from an accessible location before retrying the command.，说明命令根本没有经过分析：这是 Amp Code 的 shell 调用，其 dir 无法解析。请改用已存在的目录，或从可访问的位置创建缺失的目录，然后重试。
  6. 如果拒绝原因是下面这段，说明智能体试图运行 cc-safety-net policy apply：
    应用提案会重写各道防护所依据的策略，因此这次阻止是有意为之，也没有任何开关可以解除。请自己在终端里运行 npx cc-safety-net policy apply <file>。policy check 仍然允许，智能体依旧可以向你展示该提案会改动什么。识别逻辑有意放宽匹配，因此同一条命令的 npx、bunx、pnpm dlx、npm exec 以及 bun/node 形式同样会被拦下。
  7. 根据情况考虑以下替代方案：
    • 在 linked worktree 中工作？ 在 policy.json 中启用 workflow.worktree_mode，或设置 CC_SAFETY_NET_WORKTREE=1。当命令已确认在 linked worktree 内运行时，此模式会放宽本地丢弃规则。linked worktree 本就设计为可丢弃的隔离工作区。
    • 需要更安全的变体？ 例如 git push --force-with-lease 是允许的，效果与 --force 相同，还多了一层安全检查；git clean -n（dry-run）也是允许的，可以先预览会删除哪些内容。
    • 确实需要这条命令？ 在智能体外手动运行。这始终是一个选项；阻止触发时，CC Safety Net 也会让智能体请你这样做。
无法验证的规则来源会被丢弃。命令会继续运行，但该来源的规则不再生效，运行时报告 degraded。在一切正常的会话里，这种失败可能悄无声息，因此每次更改规则配置和升级之后都应检查。其他所有已验证的范围和所有内置保护都会继续生效。每项失败及其回退见配置恢复。解决步骤：
  1. 运行 npx cc-safety-net status 查看判定，再运行 npx cc-safety-net doctor 查看完整原因；输出会指出被拒绝的来源和具体条件。
  2. 运行 npx -y cc-safety-net rule list，查看实际生效的来源和规则以及所有 issue 和 warning。然后运行 npx -y cc-safety-net rule verify 校验 rulebook 结构。
  3. 检查文件位置是否正确：
    • 用户范围：~/.cc-safety-net/rules/rule.json（由 rule init --global 创建）
    • 项目范围：项目根目录中的 .cc-safety-net/rules/rule.json
  4. 确认 rule.json 和 rulebook JSON 文件都是有效的 JSON。常见错误包括多余的尾随逗号和未加引号的 key。无法读取的 rule.json 会让整个范围被丢弃，其中的 transparent_wrappers 也一并失效。
  5. 确认 rule.json 包含 "version": 1，每个 rulebook.json 包含 "rulebook_version": 1。两者都是必填字段。
  6. 如果编辑 rulebook 后仍是旧行为，说明你编辑的不是该范围实际加载的文件。每个来源都从 <rules dir>/<rulebook name>/rulebook.json 加载，其中的名称取自 rule.json 中的来源条目；对该文件的修改一经保存，下一次工具调用就生效，没有任何发布步骤。运行 npx -y cc-safety-net rule list 查看每个范围实际加载了哪些来源和 rulebook 名称，再确认你编辑的文件位于该名称之下。同时确认 rule.json 的 overrides 没有关闭这条规则。已被其他来源占用的 rulebook 名称会连同一条警告被忽略，其规则根本不会加载。
  7. 如果以前使用旧的内联配置（.safety-net.json 或 ~/.cc-safety-net/config.json），运行 npx -y cc-safety-net rule migrate 转换为新布局。迁移之前，旧文件中的规则一直是无效的。
  8. 更改 rulebook 来源后，运行 npx -y cc-safety-net rule verify 重新校验。没有重建这一步。rule verify 会像防护一样重新加载每个范围，并给出准确的剩余诊断信息后失败，而不会报告虚假的成功。对于远程来源，npx -y cc-safety-net rule update 会重新拉取并覆盖已落盘的 rulebook.json，因此对该文件的本地修改会丢失。
运行时处于 degraded 时，这些命令都可以照常运行。配置无法生效不会阻止这些操作。
degraded 表示某个候选配置被拒绝，改由安全的替代配置生效，例如被丢弃的规则来源、重复的 rulebook 名称，或回退到挽救值或保护性默认值的无效 policy.json。普通工作绝不会因此被拒绝。解决步骤：
  1. 运行 npx cc-safety-net doctor。config.runtime-degraded 这一项会给出完整原因，并指出被拒绝的文件和具体条件。
  2. 对于规则来源，请按原因给出的修复方式处理。config.runtime-degraded 的 fix hint 原文如下：
    rulebook 无效或名称不匹配时，原因以 fix that file 结尾；本地 rulebook 缺失时，以 create that file or remove that source from the rules config 结尾；远程 rulebook 缺失时，则以一句提示结尾，让你运行 cc-safety-net rule update 把该来源落盘。修复后运行 npx -y cc-safety-net rule verify 确认。
  3. 对于 policy.json，请手动修复文件，因为运行时绝不会重写它。被拒绝的部分会回退到保护性默认值，因此常见现象是拒绝比你配置的更多，而不是更少。不易察觉的例外是无效的 safety.level：它会回退到 standard，从而降低保护。
  4. 再次运行 npx cc-safety-net status，确认判定为 ready。
每种失败及其回退值见配置恢复。
任一范围内仍留有早期版本生成的 rule.lock 文件或 cache 目录时，doctor 会报告 info 级检查项 config.v2-leftovers，标题为 Rulebook lock and cache leftovers detected，详情中列出找到的路径。已经没有任何东西会读取这些文件。运行时直接加载各个 rulebook.json，因此该项只是提示信息。判定仍为 ready，配置的规则也照常全部生效。修复提示原文如下：
rule sync 已弃用，除了这项迁移之外什么也不做。它离线运行，把仍与所记录 digest 相符的缓存 rulebook 复制到其来源实际加载的实时文件位置，然后删除 lock 和缓存。其余输出，以及它拒绝运行的情形，见 rule sync。
状态行要求 ~/.claude/settings.json 中有 statusLine 项。若未显示，多半是该项缺失、格式有误，或指向了错误的运行时。解决步骤：
  1. 打开 ~/.claude/settings.json，确认存在 statusLine 项。它应采用以下一种形式：
  2. 此文件的更改会立即生效，无需重启 Claude Code。
  3. claude x 变体只兼容原生版 Claude Code。如果你通过 npm 安装 Claude Code，请改用 npx 或 bunx。
  4. 直接在终端里运行状态行命令，确认它会产生输出：
    如果此命令失败，Claude Code 中的状态行会为空。
  5. 状态行反映 ~/.claude/settings.json 中的 enabledPlugins["cc-safety-net@cc-marketplace"] 项。如果你把 CC Safety Net 作为手动 hook 运行，或用于其他智能体，那么即使保护正在生效，它也可能显示 ❌。各指示器的含义见状态行。
请保持 CC Safety Net 为最新版本，以获得最新的阻止规则和 bug 修复。更新每个已安装的集成：
update 会检测机器上已安装的集成（包括已禁用的），并逐个就地刷新。找不到对应智能体 CLI 的集成会报告为 skipped。@latest 标签很重要：不带标签的 cc-safety-net 可能从 npx 缓存中重新运行旧副本，而不是当前版本。在交互式安装程序中按 u 会执行同样的更新。Claude Code（插件市场）： 若想改为自动更新，请依次进入 /plugin → Marketplaces → cc-marketplace，启用 auto-update。本地安装请用包管理器更新。查看当前版本：

​
收集诊断并报告问题

如果按上面的步骤仍无法解决问题，请在提交报告前收集完整的诊断输出：
--json 会生成结构化输出，在一个快照中包含环境、已安装版本、hook 配置和自检结果。
分享 doctor 或 explain 输出前，请先检查内容。其中包含绝对文件系统路径，包括主目录、项目和目录名称以及配置路径。脱敏只覆盖可识别的凭证形式，因此请使用占位凭证复现问题，并在粘贴前通读输出。
覆盖缺口、误报、安装问题和文档问题等 bug 请提交到公开的 GitHub issue。机密泄漏、预期目录外写入以及供应链或软件包完整性问题应使用安全策略中的私密渠道。
最后修改于 2026年9月1日