Claude Code Mods：安装、开发与热重载

Mods 能改什么？

Mod 把可执行的事件处理函数打包进 Claude Code 插件。按官方事件机制，函数可以记录动作、修改事件后继续执行，或直接返回结果。比如统计工具调用、调整发给模型的提示词，或者为某类动作提供自定义处理。

界面 API可以添加面板、按钮和输入框，也能修改工具调用行和等待动画。适合做任务看板、审查面板等功能。第一次开发建议先做计数器，确认运行方式后再增加复杂逻辑。

安装别人写好的 Mod

先在终端检查版本：

claude --version

按插件安装文档添加作者的 marketplace，再打开插件详情，检查它包含的组件，选择 local、project 或 user 安装范围。local 仅供你在当前仓库使用。下面是命令格式，两个名称都是占位符，必须换成作者提供的真实值：

/plugin install YOUR_MOD@YOUR_MARKETPLACE

看安装后的激活提示。如果你在外部终端安装，而 Claude Code 会话仍开着，在会话中运行 /reload-plugins 或重新开启会话。到 /plugin 的 Installed 页确认插件已启用；以后也可在那里禁用或卸载。

让 Claude Code 帮你写第一个 Mod

官方开发流程使用内置 /plugin-authoring Skill。你可以在交互会话中提出一个具体需求：

写一个 Mod，统计工具调用次数，增加 /tool-count 命令。
保留原有工具行为，验证代码，并解释注册了哪些钩子。

批准执行前先审查生成的文件。Claude Code 会询问是否允许本次会话热重载；允许后，修改会在当前轮次结束时加载。会话生成的 Mod 是临时文件，想长期保留就复制到自己的目录。保存到本地目录后，开发命令如下：

claude plugin validate ./my-mod
claude --plugin-dir ./my-mod

./my-mod 必须是已经存在的插件目录。通过 --plugin-dir 加载支持热重载；核对 API 名称时，优先使用当前安装版本生成的 TypeScript 类型声明。

先测试，再放进日常工作流

为计数器和命令结果添加测试，模拟工具调用并检查输出。官方测试工具可以触发事件、用 stub 提供响应，无须真实会话、登录或联网。在插件目录内运行：

claude plugin test

测试还应确认无关工具调用仍正常传递。模型和工具响应需要明确 stub；测试通过不等于真实 API 接入已经跑通。

哪些界面能显示 Mod？

选择依赖界面的 Mod 前，先看官方运行位置表。云端会话也不会自动继承你在本机安装的插件。

权限范围和排错方法

Mod 拥有当前用户账号的访问权限，能接触文件、环境变量中的密钥、进程和网络。Mods 没有沙箱隔离；Claude Code 的 Bash 沙箱不会隔离 Mod 启动的程序。组织管理文档解释了受管 guard 的边界，以及 Mod API 调用与普通工具权限之间的区别。

审查源码，并通过 validate 查看钩子和 API 调用。验证只检查结构，不是作者可信度认证。怀疑问题由扩展引起时，可以启动一次关闭已安装自定义项的会话：

claude --safe-mode

如果 Mod 没有反应，按官方排错文档检查加载状态、验证结果和 debug 日志。面板不出现可能是运行界面不支持；钩子出错也可能被跳过，所以安装完成后还要确认功能真的生效。

Mods、Skills、Hooks 和 MCP 怎么选？

重复使用的操作说明适合写成 Skill；已有脚本按事件执行适合 settings hook；外部系统工具适合 MCP。需要定制 Claude Code 运行逻辑或界面时，再考虑 Mod。一个插件可以同时包含这些组件。

本页专门讲 Claude Code，因为 Mod 运行时属于这个应用。若你要扩展聊天机器人，应使用 Hermes Skills 或 OpenClaw Skills 安装指南；Claude Code Mod 不能直接装入这两个框架。

Claude Code Mods 常见问题

相关教程

• Claude Code 中文介绍
• Hermes Agent 中文教程
• Hermes Skills 使用指南（英文）
• OpenClaw Skills 安装指南（英文）
• Claude Code Mods 英文指南