MemoryLake
返回全部文章
Tutorial2026 年 11 月 16 日·11 分钟阅读

Claude Code Mods 能做什么?它们与 Hooks 和 Plugins 的区别、Mod 在会话间保留的内容,以及为什么 /clear 会重置其状态 (2026)

你安装了一个 Claude Code mod,它在转录文本旁边添加了一个面板:实时统计 Claude 处理的文件以及你在此过程中做出的决策。整个下午它都非常有用。然后你运行了 /clear 来重新开始,面板就变回空白了。第二天早上,同一个 mod 中的另一个计数器仍然记得昨天的总数。

这就是 Anthropic 文档中描述的 mod 状态工作方式。一个 mod 可以将数值存储在不同的位置,每个位置的持续时间不同。其中一个会在“用户运行 /clear、/resume 或 /branch”时重置。另一个则由你机器上的每个会话共享,并能跨天保存。

Mods 是自定义 Claude Code 的较新方式之一,它们可以实现其他选项无法做到的功能。本指南涵盖了什么是 mod 及其功能、mods 与 settings hooks、skills、plugins 和 MCP 服务器的区别、如何安装以及如何判断是否信任它、mods 在哪里运行、mod 在会话间保留的内容、如何关闭 mods,以及你的项目上下文应该存放在哪里。

什么是 mod

Anthropic 的文档以一个定义开始:“mod 是一个改变 Claude Code 外观和行为的 plugin。”

mod 即代码。“它由 JavaScript 或 TypeScript 事件处理器组成:当事件发生时(如工具调用、提交提示词或界面部分绘制),Claude Code 会调用其中一个处理器,处理器可以观察事件、修改事件或接管事件。”

文档将这些处理器称为 hooks,这可能会引起混淆,因为 Claude Code 已经有了你在设置文件中配置的 hooks。在 mod 页面上,Anthropic 将设置文件中的那种称为 settings hook。区别在于它们的运行位置:“mod 的处理器是运行在 Claude Code 内部的函数。”

一个小型 mod 由三个文件组成:一个 plugin 清单、一个指向代码的 hooks.json 以及一个注册处理器的代码文件。

mod 能做什么

由于 mod 运行在 Claude Code 内部,Anthropic 列出了它能做而 settings hooks、skills、状态栏和 MCP 服务器做不到的事情:

  • 绘制可交互界面, 例如转录文本旁的面板或提示词上方的横条,带有标签页、按钮和文本框。
  • 重绘 Claude Code 自身的界面, 例如工具调用的行、加载动画或 Claude 提问时的对话框。
  • 介入工具调用或请求, 例如在向你提问时挂起工具调用,或将请求发送给不同的模型。
  • 在命令上运行你自己的代码, 一个立即运行的 /command,无需 Claude 轮次,甚至在 Claude 工作时也能运行。
  • 在 hooks 之间共享数据, 这样一个 hook 可以记录内容,另一个 hook 可以显示它。

Claude Code 的一些自身功能也是作为 mods 构建的。内置列表包括 /diff,以及一个“将 AGENTS.md 加载为项目指令”的内置 mod。你可以在 /plugin 的 Installed 标签页中看到内置 mods,但“你无法更新或卸载内置 mod”。

mods 与 settings hooks、skills、plugins 及 MCP 服务器的区别

Plugins。 mod 与 plugin 并非独立的东西。它作为 plugin 从市场安装,一个 plugin 可以同时包含 mod 以及 skills、commands、agents 和 MCP 服务器。

Settings hooks。 settings hook 是 Claude Code 在生命周期事件中运行的 shell 命令、HTTP 请求或提示词。它可以允许、阻止或更改工具调用或提示词,并为 Claude 添加上下文,但它不能绘制任何东西。我们在关于 什么是 Claude Code hooks 的指南中介绍了 settings hooks 以及哪些可以添加上下文。

Skills。 skill 是一个包含 Claude 读取指令的 SKILL.md 文件。它改变的是 Claude 知道什么和做什么,而不是 Claude Code 的行为。

MCP 服务器。 MCP 服务器为 Claude 提供访问外部系统的工具。

Anthropic 的对比总结了何时选择 mod:当你想要一个面板、提示词上方的横条、自定义命令或重写事件时。如果 settings hook、skill 或 MCP 服务器已经能满足你的需求,文档建议在编写 mod 之前先对比它们。

安装 mod 并决定是否信任它

安装 mod 的方式与安装任何 plugin 相同:在会话中运行 /plugin install,后跟 plugin 名称、@ 符号和市场名称。如果你在会话打开时从 shell 安装,请运行 /reload-plugins 来加载它。

Anthropic 还在公共仓库中分享了示例 mods,例如一个在提示词上方绘制上下文窗口预测的 mod,以及一个挂起高风险 shell 命令并显示其更改内容的 mod。

在安装之前,请认真对待警告。“mod 是以你的权限运行的代码。”文档列出了 mod 加载后可以访问的内容,包括你的文件、环境变量、设置文件以及你的会话:“你发送的每个提示词和 Claude 进行的每个工具调用”。

而且:“Mods 没有沙箱保护。”如果你开启了沙箱,它会隔离 Claude 运行的 Bash 命令,但 mod 启动的进程运行在沙箱之外。

当然也有限制。“mod 可以重新设计 Claude Code 的大部分界面,但不能修改权限提示。”Anthropic 还描述了一个内置防御机制,加载后默认会阻止用户 mod 批准那些你的规则或 hooks 会阻止的工具调用。

要在安装前查看 mod 的功能,请在其文件夹上运行 claude plugin validate。输出会列出该 mod 处理的事件以及它请求 Claude Code 执行的操作。

mods 在哪里运行

Mods 可以在 Claude Code CLI、Claude Desktop 应用的 Code 标签页以及 VS Code 扩展中工作。Anthropic 的表格补充了一些边缘情况:

  • claude -p 和 Agent SDK: hooks 会运行,但不会绘制任何内容。
  • 远程控制 (Remote Control): hooks 在你机器上的会话中运行,绘图出现在该终端中。
  • 云端会话: 访问云端会话的 plugin 的 hooks 会运行,但不会绘制内容。
  • Desktop 应用中的 WSL 会话: mods 不会运行,因为那里不支持 plugins。

具有绘图功能的 mod 可以检查其运行环境,并回退到转录文本中的一行文字或命令的文本回复。

mod 在会话间保留的内容

这是在你依赖 mod 之前值得理解的部分。Anthropic 的文档指出:“mod 存储数值的位置决定了该数值的持续时间:直到模块重新加载、直到会话结束,或从一个会话延续到下一个会话。”

共有三个位置:

模块级变量 (Module-level variable)。 持续到模块重新加载,在开发期间,每次保存文件都会发生。Anthropic 将这些描述为可能会丢失的数值。

$.state。 持续到“会话结束,或用户运行 /clear、/resume 或 /branch”。它适用于绘图所依赖的、应该在模块重新加载后存活的数值。这就是开头例子中面板在 /clear 后变白的原因。

$.store。 持续到 mod 删除该值,或者直到没有会话在 cleanupPeriodDays 周期内读取或写入该 store。Anthropic 将其描述为“机器上每个会话共享的键值存储”。它以 JSON 文件形式保存在 ~/.claude/plugins/store/ 下的 plugin 专属目录中,文档列出了设置、历史记录以及“用户期望下次能找到的任何内容”作为其用途。

因此,记得昨天总数的计数器是在 $.store 中。而重置的面板是从 $.state 绘图的。

一个构建良好的 mod 会桥接这两者。Anthropic 指出,如果 mod 在会话开始时将保存的值从 $.store 复制到 $.state,那么在 /clear、/resume 或 /branch 之后必须再次复制,因为这些命令会重置 $.state,且会话启动 hook 不会再次触发。如果 mod 的显示在数据不该重置时重置了,那就是作者需要检查的地方。

由此产生两个实际要点:mod 的 store 位于你的机器上,由该机器上的会话共享,因此它与你的团队成员或其他电脑看到的内容不同。而且,如果没有人触碰它,它将遵循 Claude Code 在其他地方使用的相同保留期限。

如何关闭 mods

“Mods 默认开启。”要停止它们,Anthropic 列出了三个级别:

  • 单个 mod: 在 /plugin 的 Installed 标签页中禁用或卸载其 plugin。
  • 单个会话的所有已安装 mod: 使用 --safe-mode 启动 Claude Code,这也会禁用你的其他自定义设置。
  • 所有会话的所有已安装 mod: 在 ~/.claude/settings.json 中将 disableAllHooks 设置为 true。你的 settings hooks 和自定义状态栏也会停止。

内置 mods 则不同:“停止已安装 mods 的设置和标志(如 disableAllHooks、--bare 和 --safe-mode)不会停止内置 mods。”组织也可以通过托管设置限制加载哪些 mods。

人们最常遇到的误区

期望 mod 的面板在 /clear 后存活。 $.state 在 /clear、/resume 和 /branch 时会重置。

期望在另一台机器上看到 mod 的数据。 $.store 由保存它的机器上的会话共享。

不经检查就安装。 运行 claude plugin validate 查看 mod 的具体行为。

认为沙箱覆盖了 mods。 Mods 不在沙箱中运行。

使用 mod 存储项目知识。 mod 改变的是 Claude Code 的行为;项目知识应该放在指令文件中。

解决方案:将 mods 用于行为,将上下文存在别处

第 1 步:安装前检查 mod 的功能

在其文件夹上运行 claude plugin validate 并阅读它列出的事件和调用。

第 2 步:了解每个数值的存放位置

如果你编写 mod,请将必须在 /clear 后存活的数值放入 $.store,并在重置后将它们重新加载到 $.state 中。

第 3 步:将项目知识保留在指令文件中

规范和结构属于 CLAUDE.md 或 AGENTS.md,它们会作为项目指令加载。

第 4 步:记录你在会话中学到的内容

mod 的面板可以跟踪进度,但其背后的决策应该记录在比会话和机器更持久的地方。

在 MemoryLake 中设置

mod 是查看会话中发生了什么的有效方式。但该会话中的决策和教训(例如哪种方法奏效或为什么某个文件是禁区)需要一个不会在 /clear 时重置且不绑定到单台机器的归宿。

MemoryLake 是此类项目上下文(如决策、规范和经验教训)的记忆层,它保存在一个由你维护的地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。

你用自己的语言亲自编写条目。不会从你的 mods、它们的 $.state 或 $.store、你的 plugins、你的设置文件、你的会话或任何供应商的存储中读取、写入或删除任何内容。Mods 及其状态按照 Anthropic 描述的方式运行。

第 1 步:创建 API 密钥

登录并在控制面板生成密钥。像对待其他凭据一样,不要将其放入 plugin 和 mod 代码中。

MemoryLake 控制台显示 API 密钥屏幕,在此创建并复制新密钥以供 agent 使用
MemoryLake 控制台显示 API 密钥屏幕,在此创建并复制新密钥以供 agent 使用

第 2 步:上传你的第一批记忆

从你在解决方案第 4 步中写下的内容开始:近期会话的决策、你依赖的规范以及你不想重复学习的教训。每条记录一个决策。

MemoryLake 工作区显示已上传的首批文档,列出了每个变为可搜索记忆的文件
MemoryLake 工作区显示已上传的首批文档,列出了每个变为可搜索记忆的文件

第 3 步:连接你的 AI 和 agents

连接 Claude Code 和你使用的其他助手。新会话或另一台机器都可以调用相同的条目。

MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和 agent 框架
MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和 agent 框架

这在实践中改变了什么

第一个区别是 /clear 不再让你损失上下文。mod 的显示可以重置,而决策仍然被记录在案。

第二个区别是便携性。你学到的东西不再绑定到单台机器的存储中。

第三个区别是更清晰的分工。Mods 处理 Claude Code 的行为方式,而你的项目上下文则统一存放在一个地方。

Claude Code mods 的最佳实践

将 mods 视为代码。 它们以你的权限运行且没有沙箱保护。

安装前验证。 claude plugin validate 会列出 mod 的功能。

Shell 安装后重新加载。 在打开的会话中运行 /reload-plugins。

了解三种生命周期。 变量、$.state 和 $.store 各自的持续时间不同。

预见 /clear 带来的重置。 $.state 会恢复到其默认值。

使用 --safe-mode 进行故障排除。 它会为单个会话禁用已安装的 mods。

不要将上下文存在 mods 中。 使用指令文件和你维护的记忆。

结论

Claude Code mod 是一个由 JavaScript 或 TypeScript 处理器组成的 plugin,运行在 Claude Code 内部。它可以绘制面板和横条、重绘部分界面、介入工具调用和请求,并添加命令,这些是 settings hooks、skills 和 MCP 服务器无法做到的。它还以你的权限运行且没有沙箱保护,因此在安装前请务必验证。

mod 保留的内容取决于它存储数值的位置。模块变量持续到重新加载,$.state 持续到会话结束或你运行 /clear、/resume 或 /branch,而 $.store 则跨机器上的会话持久存在,直到 mod 删除它或因超过保留期而未使用。对于必须比这些更持久的上下文,请将其记录在你维护的地方。

常见问题

什么是 Claude Code mod?

一个由 JavaScript 或 TypeScript 事件处理器组成的 plugin,Claude Code 会在事件发生时调用它。Anthropic 表示 mod 会改变 Claude Code 的外观和行为。

mods 与 Claude Code hooks 有什么不同?

Settings hooks 从设置文件运行 shell 命令、HTTP 请求或提示词。mod 的处理器是运行在 Claude Code 内部的函数,并且还可以在界面中绘图。

为什么我的 mod 在 /clear 后重置了?

$.state 仅持续到会话结束或你运行 /clear、/resume 或 /branch。

mods 会在会话之间记住任何内容吗?

是的,如果它们使用 $.store。这是一个由机器上每个会话共享的键值存储,保存在 ~/.claude/plugins/store/ 下。

mods 安全吗?

mod 以你的权限运行且没有沙箱保护。仅安装来自你信任的作者和市场的 mods,并使用 claude plugin validate 进行检查。

如何关闭所有 mods?

在单个会话中使用 --safe-mode 启动,或在 ~/.claude/settings.json 中将 disableAllHooks 设置为 true。内置 mods 不会被这些操作停止。

mods 在哪里工作?

在 Claude Code CLI、Claude Desktop 应用的 Code 标签页以及 VS Code 扩展中。在 claude -p 和云端会话中,hooks 会运行但不会绘制内容。