从一个小改装开始

Claude Code Mods 安装教程与故障排查.

按作者说明从市场安装 Claude Code Mod，或为单次会话加载官方示例。先检查版本，再确认模块是否加载；遇到安装后没反应、界面不显示等问题，可直接查看下方排障清单。

01 / 检查 Claude Code 版本

官方文档要求 Claude Code 2.1.287 或更高版本，这些版本默认启用 Mods。早期教程要求手动开启 function hooks 的步骤已不再适用于这些版本。

终端 / 安装命令

claude --version

还需要设置 function-hooks 环境变量吗？

Claude Code 2.1.287 及更新版本不需要。官方文档说明这些版本会忽略 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS，即使其值为 0。旧版应先更新，不要照搬早期试用标志。如果需要关闭 Mods，请使用文档规定的设置或会话参数。

02 / 选择有公开源码的 Mod

打开作者仓库，先读环境要求。本站英语目录区分有公开源码和安装说明的 Mod，以及尚未确认安装方式的演示。

03 / 添加市场并安装插件

市场名和插件名必须按作者说明填写。例如 Claude Ambient 的作者提供了以下终端命令：

终端 / 安装命令

claude plugin marketplace add barisdemirhan/claude-ambient
claude plugin install ambient@claude-ambient

其 README 接着要求重启 Claude Code，并在会话中运行 /ambient. 查看作者完整说明（英语） ↗

如果已有会话打开，而你从外部终端安装或更新插件，官方文档说明可在该会话中运行 /reload-plugins 来加载新插件。

04 / 为单次会话加载官方示例

Token Weather 是显示上下文用量的小示例。克隆官方 playground，检查插件文件，再为单次会话加载它：

终端 / 安装命令

git clone https://github.com/anthropics/claude-code-playground.git
cd claude-code-playground/claude-code/mods
claude plugin validate ./token-weather
claude --plugin-dir ./token-weather

查看 Token Weather 的设置与限制（英语） ↗

05 / 确认 Mod 已加载

在终端会话中打开 /plugin，查看标签下方颜色较淡的“mods active”一行。这里列出已加载的已安装 Mod，不包含内置 Mod。插件出现在 Installed 标签页里，并不能证明它的 Mod 代码已加载。

CLAUDE CODE / 交互会话

/reload-plugins
/plugin

Mod 界面会显示在哪里？

Mods 可以在终端和 Claude Desktop 的 Code 标签页绘制界面。VS Code 聊天面板与无界面会话不显示 Mod UI。各 Mod 可能有更严格的要求，请以其 README 为准。

Claude Code Mod 不生效？先按症状排查

先区分加载失败与显示问题：Mod 可能已经启用，但你当前使用的界面不支持绘制其 UI。

从外部终端安装后，当前会话没反应

在该会话中运行 /reload-plugins，再检查 /plugin。如果作者 README 还要求运行激活命令或填写配置，也要完成这些步骤。仅安装插件不一定会自动打开界面。

显示已加载，但 VS Code 中看不到面板

尝试 Claude Code 终端，也可以使用编辑器的集成终端。VS Code 聊天面板与无界面运行不绘制 Mod UI。Claude Desktop 的 Code 标签页支持显示，但 Desktop 的 WSL 会话不支持插件，且部分界面元素仅在终端可用。

所有已安装 Mod 都无法加载

检查版本，以及启动会话时是否使用了 --safe-mode。个人设置或组织策略也可能阻止 Mod 模块，而插件的其他部分仍可使用。阅读拒绝原因；遇到托管限制应询问管理员，不要通过改策略绕过限制。

模块或钩子悄悄失败

用 claude --debug 启动诊断会话，复现问题后在调试日志中搜索 Mod 名称。包含“not loaded”的行指向加载拒绝；“hook skipped”指向处理函数失败。结合官方排障文档查看具体原因。

修改本地代码后，效果没有变化

已安装插件运行的是缓存版本。开发时用 --plugin-dir 指向你修改的工作副本，该会话会重新加载本地改动。编辑另一个仓库副本不会改变已安装版本。

不执行 Mod 代码，先检查本地文件

对实际插件目录运行 claude plugin validate，参考上方示例。它可以发现清单或模块问题，并在不执行 Mod 代码的情况下列出钩子和 API 调用。校验通过不代表运行兼容性或安全性已获确认。

官方 Mod 排障文档（英语） ↗

选择一个小示例继续了解

想看上下文显示，可阅读 Token Weather 条目；想看氛围场景，可阅读 Claude Ambient 条目及其激活命令。两者界面行为不同，请对照作者要求判断自己的问题。下列案例页仍为英语。

Token Weather（英语） · Claude Ambient（英语）

本站的“来源审核”是什么意思？

本站核对原始来源和已发布的安装说明，但不会逐个执行 Mod。Mods 拥有你的机器权限，安装前应检查代码；claude plugin validate 可在不执行 Mod 代码的情况下列出钩子和 API 调用。

官方 Mods 文档（英语） ↗

来源与核对范围

本清单整理的是文档描述的行为，并非本站安装实测结果。原始官方文档和各作者 README 是具体设置的依据。

中文指南于 2026 年 10 月 4 日根据官方文档及所链接的作者说明核对。命令是来源文档中的示例，本站未执行采集到的 Mod。