从一个小改装开始
Claude Code Mods 安装教程与故障排查.
按作者说明从市场安装 Claude Code Mod,或为单次会话加载官方示例。先检查版本,再确认模块是否加载;遇到安装后没反应、界面不显示等问题,可直接查看下方排障清单。
01 / 检查 Claude Code 版本
终端需使用 Claude Code 2.1.287 或更新版本,用下方 shell 命令检查。Claude Desktop 自带独立版本:在 Code 标签页的本地会话输入 /status,查看 Claude Code 一行是否为 2.1.286 或更新版本;过旧则更新 Desktop 应用。Mods 默认启用,当前版本无需早期试用的 function-hooks 标志。
claude --version还需要设置 function-hooks 环境变量吗?
Claude Code 2.1.287 及更新版本不需要。官方文档说明这些版本会忽略 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS,即使其值为 0。旧版应先更新,不要照搬早期试用标志。如果需要关闭 Mods,请使用文档规定的设置或会话参数。
02 / 选择有公开源码的 Mod
打开作者仓库,先读环境要求。本站英语目录区分有公开源码和安装说明的 Mod,以及尚未确认安装方式的演示。
Claude Code Mods 安全吗?先看它能访问什么
即使功能只是一个小面板,Mod 也可能拥有广泛访问能力。它在 Claude Code 进程内以你的用户权限运行,可接触文件、环境变量与设置,包括其中保存的密钥。选择可信作者,在加载前检查实际插件目录。
读懂校验输出的 hooks: 与 calls:
先取得作者文件,不要加载插件;对实际插件目录运行 claude plugin validate,可参考下方 Token Weather 示例。hooks: 列出它接收的事件,calls: 列出它调用的 Mods API 方法。例如:
$.fs.read / $.fs.write— 读写你的用户账户有权访问的文件。$.process.run / $.process.spawn— 以你的用户身份启动程序。$.http.fetch— 发送网络请求;判断用途是否与所需功能相符。$.model.complete— 调用模型,使用你的套餐额度或 API key。
官方管理文档还解释了密钥访问、提示词修改等能力。校验通过不是安全认证。本站建议:对照源码与 README 理解输出,记录所核对的版本或提交,在更新前检查变更。
Claude Code 的 Bash 沙箱能隔离 Mod 吗?
不能。官方概述说明 Mods 不受沙箱隔离,它启动的进程也在 Bash 沙箱之外运行。仅换到实验目录不会限制文件访问;界面看起来无害或目录标注“来源已核对”,都不能证明它受到隔离。
如何停用 Mod?
在 /plugin 的 Installed 标签页停用或卸载对应插件。若本次会话不想加载已安装 Mod,可用 claude --safe-mode 启动;它也会关闭其他自定义功能。内置 Mod 属于例外,需要单独停用,You Should Know 的操作见下方英语指南。
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-weather05 / 确认 Mod 已加载
在终端会话中打开 /plugin,查看标签下方颜色较淡的“mods active”一行。这里列出已加载的已安装 Mod,不包含内置 Mod。插件出现在 Installed 标签页里,并不能证明它的 Mod 代码已加载。
/reload-plugins
/pluginMod 界面会显示在哪里?
Mods 可以在终端、Claude Desktop 的 Code 标签页和 VS Code 扩展中绘制界面。能够获取 feature flags(功能开关)的会话要求扩展版本 2.1.299+;不获取功能开关的会话要求 2.1.304+,包括 Bedrock、Vertex、Foundry、LLM 网关和关闭遥测的会话。各界面支持的元素不同;无界面会话不显示 Mod UI。各 Mod 可能要求更严格,请以作者 README 为准。
Claude Code Mod 不生效?先按症状排查
先区分加载失败与显示问题:Mod 可能已经启用,但你当前使用的界面不支持绘制其 UI。
从外部终端安装后,当前会话没反应
在该会话中运行 /reload-plugins,再检查 /plugin。如果作者 README 还要求运行激活命令或填写配置,也要完成这些步骤。仅安装插件不一定会自动打开界面。
显示已加载,但 VS Code 中看不到面板
检查 VS Code 扩展版本:获取 feature flags(功能开关)的会话要求 2.1.299+;不获取功能开关的会话要求 2.1.304+,例如 Bedrock、Vertex、Foundry、网关或关闭遥测的会话。应更新扩展,无需为显示界面改变服务商或遥测设置。对照官方绘制位置、元素表与作者 README;宿主支持并不保证每个 Mod 都能显示。可用集成终端排查界面差异。无界面运行不绘制 UI;Desktop 的 WSL 会话不支持插件。
所有已安装 Mod 都无法加载
检查版本,以及启动会话时是否使用了 --safe-mode。个人设置或组织策略也可能阻止 Mod 模块,而插件的其他部分仍可使用。阅读拒绝原因;遇到托管限制应询问管理员,不要通过改策略绕过限制。
模块或钩子悄悄失败
用 claude --debug 启动诊断会话,在日志中搜索 Mod 名称。“not loaded”指向加载拒绝;“hook skipped”指向处理函数失败。2.1.304 还会在先运行的插件跳过你的钩子时,在会话记录中写出事件和该插件名称。先阅读具体原因,再决定是否修改代码或配置。
修改本地代码后,效果没有变化
已安装插件运行的是缓存版本。开发时用 --plugin-dir 指向工作副本,它会随本地编辑重新加载。如果提示“reload failed, the previous version stays loaded”,应先修复报告的错误:上次可用版本仍在运行,行为未变不代表修改已加载。2.1.304 修复了失败重载导致旧版工具和命令被移除的问题。编辑另一个仓库副本不会更新已安装版本。
不执行 Mod 代码,先检查本地文件
对实际插件目录运行 claude plugin validate,参考上方示例。它可以发现清单或模块问题,并在不执行 Mod 代码的情况下列出钩子和 API 调用。校验通过不代表运行兼容性或安全性已获确认。
官方 Mod 排障文档(英语) ↗选择一个小示例继续了解
Claude Code 2.1.300:Mods 新能力与升级说明(英语)→
You Should Know 内置 Mod:启用、停用与可用性(英语)→
Mods、Plugins、Skills、Hooks 与 MCP:如何选择(英语)→
想看上下文显示,可阅读 Token Weather 条目;想看氛围场景,可阅读 Claude Ambient 条目及其激活命令。两者界面行为不同,请对照作者要求判断自己的问题。下列案例页仍为英语。
本站的“来源审核”是什么意思?
本站核对原始来源和已发布的安装说明,但不会逐个执行 Mod。Mods 拥有你的机器权限,安装前应检查代码;claude plugin validate 可在不执行 Mod 代码的情况下列出钩子和 API 调用。
来源与核对范围
本清单整理的是文档描述的行为,并非本站安装实测结果。原始官方文档和各作者 README 是具体设置的依据。
2.1.304 发布说明:VS Code 显示支持与 Mod 重载修复(英语)
显示支持与重新加载诊断于 2026 年 10 月 20 日对照官方 2.1.304 发布说明及文档核对;安装前检查说明于 10 月 10 日核对。作者命令保留来源链接;本站没有执行采集到的 Mods。