找出为什么 mod 不起作用
当 mod 不起作用时，两项检查可以找到原因：Claude Code 从 mod 文件读取的内容，以及它在跳过某些内容时写入的行。对于第一项，在您的 shell 中运行claude plugin validate，使用 mod 的目录，如 claude plugin validate ./first-mod。它可以捕获拼写错误的事件、错误的清单和 Claude Code 无法读取的模块，而无需启动会话。
当模块未加载、hook 被跳过或另一个 mod 拒绝您的 mod 时，Claude Code 会写入一行，其中命名您的 mod。您读取该行的位置取决于会话：
- 热重新加载插件目录的会话：成绩单中的暗行。这是您使用
--plugin-dir启动的交互式会话，或者是您为 Claude 编写的 mod 启用热重新加载 的会话。 - 任何其他交互式会话，例如运行您从市场安装的 mod 的会话：调试日志 仅。要获取一个，请使用
claude --debug启动会话。 - 带有
--plugin-dir的claude -p运行：stderr，采用默认文本输出格式。另一个 mod 的拒绝仅进入调试日志。
检查 mod 是否可以加载
要检查您的设置是否允许 mod 加载，而无需安装一个，请在您的 shell 中从不包含 mod 的目录运行claude plugin test。您不需要会话。它打印的消息告诉您状态：
组织还可以设置
allowManagedModsOnly 以仅允许其自己的 mod，此命令不会报告。在这种情况下，您安装的 mod 不会加载，消息会说明原因。
mod 不加载
mod 添加的任何内容都不会出现：没有命令、没有绘图，也没有行为改变。您的版本早于 2.1.287
claude --version 打印的版本早于 2.1.287。您的版本早于 mod 默认启用的时期。
更新 Claude Code。
mods active 行不命名 mod
mod 添加的任何内容都不会出现，/plugin 中的 mods active 行 不命名它。hooks 模块未加载。当 Claude Code 拒绝它时，调试日志有一行以 hooks module、mod 的名称和 not loaded: 开头，如 hooks module first-mod@inline not loaded: disableAllHooks in managed settings，用于使用 --plugin-dir 加载的 mod。
读取冒号后的原因。拒绝消息 部分列出了每一个。如果日志中没有这样的行，请逐一处理此组中的其他条目。
claude -p 运行打印 hooks module not loaded
该行以 mod 的名称开头并进入 stderr。hooks 模块被拒绝。非交互式运行没有成绩单，因此消息进入 stderr。
读取冒号后的原因。拒绝消息 部分列出了每一个。
拒绝消息
这些消息中的每一个都遵循调试日志中的hooks module、mod 的名称和 not loaded:。
来自内置保护的消息
在具有托管设置的机器上，或对于使用 Team 或 Enterprise 计划登录的用户，内置保护 可以拒绝 mod 或其答案之一。每条消息都命名您的组织管理员设置以更改规则的选项。validate 通过且不列出 hooks 行
hooks/hooks.json 没有 modules 键，或键拼写错误。
添加 "modules": ["./register.js"]。
hooks module did not load
该行以 mod 的名称开头，然后是 hooks module did not load: 和一个原因，当问题在您的代码中时，它给出文件和行。Claude Code 无法加载模块，例如因为其顶级代码抛出了异常。
修复原因命名的错误。
options do not fit plugin.json userConfig
该行以 mod 的名称开头，然后是 hooks module did not load: options do not fit plugin.json userConfig: 和一个原因。选项不适合其 userConfig 字段，例如高于字段 max 的数字，或必需字段没有值。
设置或更改值。该行的末尾命名其在 settings.json 中的 pluginConfigs 条目。
没有 mod 在您首次打开的目录中加载
您还没有回答该目录的信任提示。 使用claude 在该目录中启动交互式会话，并接受它打开的信任提示。
没有已安装的插件加载
您使用--safe-mode 启动了 Claude Code。
启动时不使用该标志。
hook 被跳过或 mod 被卸载
mod 已加载，然后 Claude Code 跳过了其中一个 hooks 或卸载了它。hook skipped
该行命名 mod 和事件，然后说 hook skipped: 和一个原因，如 first-mod: tool.call hook skipped: threw Error: boom。hook 抛出了异常、运行超过了其 10 秒时间限制，或返回了错误形状的结果。该行对每个事件和失败类型出现一次，直到 mod 重新加载。
修复错误。调试日志对每次出现都有一行。
it crashed the hooks worker
该行以 mod 的名称开头，如 first-mod was unloaded: it crashed the hooks worker。已安装的 mod 共享一个工作线程。工作线程停止响应或崩溃，Claude Code 将其追踪到此 mod 并卸载了它。阻止线程的 hook（例如永不等待的循环）是一个原因。
修复 hook。
mods that run in the hooks worker are off for this session
该行读取 hooks: mods that run in the hooks worker are off for this session: it crashed 3 times。工作线程停止了三次，Claude Code 无法将停止追踪到一个 mod，因此它卸载了每个不是内置的 mod，包括您的组织安装的 mod。此行在每个交互式会话中到达成绩单。
运行 /reload-plugins 以再次加载它们。
工具调用被拒绝
mod 已加载，其 hooks 运行，它接触的工具调用被拒绝。a hook changed this call's input after the model wrote it
在自动模式下，被拒绝的工具调用给出此原因。hook 在 服务器端分类器 审查后更改了工具调用的输入，因此该审查不涵盖将运行的内容。hook 可以是 mod 的 tool.call 或 turn.step hook，或 PreToolUse 设置 hook。消息不说明是哪一个。
消息告诉 Claude 再次发出记录的调用。如果也被拒绝，hook 每次都更改输入，因此关闭 mod 或 hook，或离开自动模式并自己批准调用。
关于您的设置中的拒绝规则的消息
tried to lift a deny rule in your settings 和 the deny rules in your settings could not be checked for this call, so it is refused 都来自内置保护。
在 来自内置保护的消息 中查找它们。
绘图不出现或不响应
mod 已加载，其窗格、带或控件的行为不符合您的预期。窗格或带为空或显示 Claude Code 的常规内容
您的 hook 返回的 树 未验证。使用--plugin-dir，成绩单说 ui.render (Pane) refused: 带有原因，如 first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own。调试日志有 a hook returned a tree that does not validate 带有相同的原因。
读取该行上的原因。常见原因是元素不接受的 prop 和应用没有的元素。
$.ui.open 运行且没有窗格出现
调用不是来自用户做的事情，终端宽度小于 144 列。
从命令或按钮打开窗格，或检查调用的 isPlaced 结果。请参阅 在正确的时间打开窗格。
热键不起作用
您的窗格没有键盘焦点。 按 Ctrl+X 然后 Tab，或单击窗格。使用focus: true 从命令打开它。
绘图在终端中有效，在桌面应用中无效
该网站或元素在那里不可用。 检查 渲染网站 和 元素 表。编辑或值丢失
mod 运行，您所做的更改或它保留的值不存在。您的编辑不生效
您正在编辑您安装的插件。Claude Code 运行已安装版本的缓存副本。 使用指向您的工作副本的--plugin-dir 进行开发，如 claude --plugin-dir ./first-mod，它在您保存时重新加载。
模块重新加载时值重置
模块级变量在每次重新加载时重新初始化。 将值保留在$.state 或 $.store 中。
值在 /clear、/resume 或 /branch 后重置
值重置，或保存的值被其默认值替换。这些命令中的每一个都将 $.state 重置为其默认值，session.start 不再触发。
在 classic.SessionStart hook 中再次加载保存的值。
阅读调试日志
调试日志对 Claude Code 加载或拒绝的每个模块、每个失败的 hook 以及它拒绝的每个结果都有一行，因此当成绩单显示无内容时，这是查看的地方。要写入一个，在您的 shell 中使用--debug 启动 Claude Code，或使用 --debug-file <path> 选择它的位置：
--plugin-dir 加载的 mod 出现在其名称后跟 @inline 下：
$.ui.log，带有第二个参数，如 $.ui.log('message', { to: 'debug' })。没有第二个参数，$.ui.log 会在成绩单中添加一条暗行。
当您编辑使用 --plugin-dir 加载的 mod 时，成绩单为每次重新加载显示一行，命名 mod 并列出其 hooks。如果保存破坏了模块，该行说 reload failed, the previous version stays loaded: 带有原因，最后一个工作版本继续运行。