Claude Code Mods 完整指南

一屏结论与版本基线

读完这一屏就能决定要不要继续往下看。

• 官方文档 来自 Anthropic 的文档、博客、发布说明或源码仓库,2026-10-02 打开核对过。
• 二手转述 出自第三方文章或账号,没有打开一手出处。
• 编辑推导 基于官方事实做的归纳或建议,不是官方说法。
• 待核实 这次没找到明确答案,不要当事实用。

事件和方法会随版本变化。官方的说法是:文档与类型声明文件不一致时,以你本机生成的 .claude-plugin/types/claude-code/index.d.ts 为准。本页所有 API 名称以 v2.1.287 文档为基线。

选型与运行环境

先确认 Mod 是不是对的工具,再确认它在你用的那个界面里能不能跑、能不能画。

四种扩展方式对比

表格较宽,可在表格区域内左右滑动。

注意第二行:settings hook 也能改工具调用的参数和结果、追加上下文,「旧 hook 只能拦截」的说法过头了。官方还补了一句:一个插件可以同时装下这四样。

只有 Mod 能做的事

选型顺序 编辑推导

1. 只是让 Claude 记住一套做法 → 写 Skill。
2. 要接外部系统(数据库、工单、API)→ MCP server。
3. 固定的命令或路径要放行或禁止 → 权限规则(如 Bash(npm test)),不用写代码。
4. 已有脚本,只做拦截、放行、记录 → settings hook。
5. 要画界面、要自定义命令、要按当时的状态动态改写事件 → Mod。

在哪里能跑、在哪里能画

「hook 是否执行」和「界面是否显示」是两件事,分开看。表格可左右滑动。

会画界面的 Mod 可以检查自己跑在哪个应用里,在画不出来的地方退回成 transcript 里的一行字或命令的文本回复。

安装前检查与停用方式

装一个第三方 Mod,相当于让一段别人的代码以你的身份常驻在 Claude Code 里。先知道它能碰什么,再知道怎么让它停下。

不运行代码,先看它会做什么

Mod 只能通过 mods API(代码里写作 $)触达文件、进程和网络,而且必须把每个调用写全,所以 Claude Code 能在安装前静态列出来:

命令与输出节选 · 官方 admin 页示例

claude plugin validate ./some-mod

  ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
  ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

hooks: 是它接收的事件,calls: 是它调用的方法。读写环境变量会多出 env reads: / env writes: 行。写法让这条命令读不出来的 Mod,Claude Code 会拒绝加载。

calls 行里要留意的调用 官方文档

hooks 行里要留意的事件 官方文档

• tool.call、prompt.submit:看得到每一次工具调用和每一条提示词,并且能改。
• tool.check:能在权限弹窗出现前批准或拒绝调用。
• session.append:能在对话每一行落盘前改写它。
• ui.render{component=AskUserQuestion}:能重画 Claude 向你提问的对话框。

安装前七项检查 编辑推导

下面每一条都由上文的官方事实推出,顺序是我排的。

1. 版本:claude --version 不低于 2.1.287,否则装了也不加载。
2. 拿到源码目录再跑 validate:看 hooks: 与 calls: 两行,和它自称的功能对不对得上。一个「只显示 token 用量」的 Mod 不该出现 $.process.run。
3. 有没有 tool.check:有的话,它能替你批准调用。个人环境没有内置守卫,连 deny 规则都可能被它推翻。
4. 有没有不调 next 就返回结果的 tool.call hook:这类 hook 会让非托管的 PreToolUse hook 不再运行,Claude 只看得到它给的结果。
5. 拦截类 hook 是否带 .catch:没有的话,它出错时就等于不存在。
6. 作者是否写明测试过的 Claude Code 版本:官方要求作者在 README 里写;事件和方法会随版本变。
7. 先想好怎么关:确认下面的停用方式在你的环境里可用,再装。

停用方式各自管到哪

安装、加载与首次验收

得到一个 Mod 有三条路:用内置的、装别人的、自己做。这一节讲前两条。

从 marketplace 安装

局部片段 · 在 Claude Code 提示符里

/plugin marketplace add your-org/my-mods
/plugin install token-weather@my-mods
/reload-plugins

局部片段 · 在 shell 里

claude plugin install token-weather@my-mods --scope user

在 shell 里安装后,已经开着的会话要执行 /reload-plugins,否则下次启动才加载。 官方文档

Anthropic 另有一个社区插件市场的只读镜像仓库 anthropics/claude-plugins-community,安装写法是 claude plugin install <插件名>@claude-community。README 称其中的插件经 claude.ai 提交、通过自动安全扫描并获批分发。 源码仓库 自动扫描不等于有人逐行审过代码,安装前七项检查照做。 编辑推导

不安装,只在一次会话里加载

局部片段

claude --plugin-dir ./first-mod

这样加载的目录会被监视,保存文件即热重载。开发时一直用这种方式,不要改已安装的副本(原因见分发一节)。

首次验收

1. 第一次打开的目录,先在交互会话里回答 trust 提示,否则任何 Mod 都不加载。
2. 运行 /plugin:顶部会有一行暗色文字,如 1 mod active · first-mod。这一行不含内置 Mod。
3. 用一下它声称的功能(命令、面板、信息带)。
4. 没反应时,带 --debug 重开会话,在调试日志里找这样的加载行:

调试日志示例 · 官方 troubleshoot 页

hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

先确认环境允许 Mod 加载

在一个不含 Mod 的目录里运行 claude plugin test,不需要会话。看它打印的消息:

组织设了 allowManagedModsOnly 的情况,这条命令不会报告。

内置条目一览 官方文档

官方表里有六个内置条目,其中 plugin-authoring 只有 skill、没有 Mod 代码,所以不宜说成「六个内置 Mod」。

写第一个 Mod

不需要 Node.js、打包器或构建步骤,Claude Code 直接加载 .js 和 .ts。下面是官方教程的 first-mod:数工具调用次数,显示在 spinner 旁,并加一个 /tally 命令。

三个文件

目录结构

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

完整示例 · first-mod/.claude-plugin/plugin.json

{
  "name": "first-mod",
  "version": "0.1.0",
  "description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",
  "author": { "name": "Your Name" }
}

完整示例 · first-mod/hooks/hooks.json(modules 只列一个路径,有它才算 Mod)

{
  "description": "The first-mod hooks module",
  "modules": ["./register.js"]
}

完整示例 · first-mod/hooks/register.js(官方教程代码,注释为中文转写) · v2.1.287 文档

// 计数器,下面几个 hook 共用
let calls = 0

// Mod 加载时 Claude Code 调用一次
export function register(on) {
  // 会话开始时(以及每次重载时)运行
  on('session.start', async ($, e, next) => {
    await $.command.register({
      name: 'tally',
      description: 'Show how many tool calls Claude has made',
    })
    return next(e)            // 观察:原样放行
  })

  // Claude 每次要用工具之前运行
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')   // 请求重画界面
    return next(e)            // 观察:原样放行
  })

  // 只有输入 /tally 时运行(第二个参数是 matcher)
  on('command.run', { command: 'tally' }, async () => {
    // 代答:不调 next,自己给结果
    return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
  })

  // 每次画 spinner 时运行
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // 改写:把带新 suffix 的事件副本交给 next
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

跑起来

局部片段

claude --plugin-dir ./first-mod          # 交互会话:spinner 显示 Thinking · tool calls: 2…
claude -p "/tally" --plugin-dir ./first-mod   # 非交互:输出 first-mod: Claude has made 0 tool calls since this mod loaded

第二条命令本身就说明:用 --plugin-dir 或安装方式加载的 Mod,在 claude -p 里 hook 照常执行。保存 register.js 后,transcript 会出现一行说明 first-mod 已重载并列出它的 hook;每次重载都会重新执行 register,所以 calls 归零。

这个计数记的是「经过这个 hook 的 tool.call 次数」,不是成功执行的工具数:hook 在调用被权限检查之前就加了一,被拒绝的调用也算在内。 编辑推导

三种处理方式

官方介绍里也用过「watch the event, change it, or take it over」的说法,所以把 Answer 译成「接管」不算错;文档里的正式名称是 Observe / Rewrite / Answer。

matcher:只处理一部分事件

局部片段 · 官方 events 页

on('tool.call', { tool: 'Bash' }, hook)             // 字符串:只匹配一个值
on('tool.call', { tool: ['Edit', 'Write'] }, hook)  // 数组:匹配其中任意一个
on('tool.call', { tool: /^mcp__github__/ }, hook)   // 正则:按模式匹配

事件名可用通配:'classic.*' 匹配所有 settings hook 事件;'*' 匹配除 telemetry 之外的所有事件。同一个事件、同一个 matcher 只能注册一次,无 matcher 地给 session.start 注册两次会导致模块加载失败。

写完先过静态检查

命令与输出节选 · 官方 create 页

claude plugin validate ./first-mod

  ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}
  ❯ ./register.js calls: $.command.register, $.ui.invalidate

✔ Validation passed

想挂的事件没出现在 hooks: 行,Claude Code 就不会调用它,常见原因是事件名拼错,报错形如 "tool.calls" is not an event。为了让静态分析读得出来,要遵守这些写法规则: 官方文档

• 每个 mods API 调用写全:$.store.get('notes')。可以把 $ 传给同文件顶层声明的函数;不能把 $ 或它的命名空间赋给变量、解构,或用计算出来的名字取成员。const ui = $.ui 会报 $.ui is used as a value。
• on 的事件名必须是字符串字面量,不能用变量或循环。
• register 里不能再声明名为 on 的变量或参数。
• 只能用相对路径导入插件目录内的文件;唯一允许的裸导入是 claude-code。
• 不能用动态 import();每个文件都写成 ES module,不用 require。

类型声明:你这个版本的权威参考

从 --plugin-dir 目录加载或重载 Mod 时(Claude 代写的也一样),Claude Code 会在 Mod 目录的 .claude-plugin/types/ 下写入 .d.ts 文件:claude-code/index.d.ts(全部事件、方法和可画元素,每个方法带注释和示例)、claude-code-tools/index.d.ts(内置工具的输入输出)、claude-code-mcp/index.d.ts(已连接 MCP 工具的输入),以及一个 tsconfig.json。在线版本是仓库里的 mods/types/claude-code.d.ts,首行写着生成它的版本。

让 Claude 代写

Claude 靠内置 skill plugin-authoring 来写 Mod,可以让它自动加载,也可以自己输入 /plugin-authoring。流程如下: 官方文档

1. 描述需求,例如「做一个在输入框上方显示当前 git 分支的 mod」。Claude 把文件写进 ~/.claude/dev-mods/<会话ID>/<mod名>/。在 default 和 acceptEdits 模式下,~/.claude 是受保护路径,每个文件都要你批准。
2. 选择是否热重载。第一个文件保存时会问:选 Enable for this session,Mod 在本回合结束时加载,之后每个改动它的回合结束时重载;选 Not now 则暂不加载,文件保留,该会话下次启动时才加载。
3. 确认已加载:/plugin 的 Installed 页里能看到它,也能在那里关掉。
4. 试用并迭代:不满意就告诉 Claude 改什么。
5. 想留下就拷走:这样写出来的 Mod 只在创建它的会话里加载,会话的 mods 文件夹超过 cleanupPeriodDays 后会被删除。拷到自己的目录,再用 --plugin-dir 加载或放进 marketplace。

按任务扩展能力

想做某件事时,该挂哪个事件、调哪个方法。代码均取自官方 events 页,注释为中文转写。

拒绝某类工具调用

局部片段(放在 register 内)

on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
  if (/git push .*--force/.test(e.command)) {
    // 不调 next:命令不执行,也不出现权限弹窗
    return { deny: 'Force pushes are not allowed in this repository. Push to a new branch instead.' }
  }
  return next(e)   // 其他命令继续走权限检查,然后执行
})

tool.call 覆盖子 Agent 的调用和 MCP 工具。deny 的文字会作为工具结果交给 Claude,所以要写成 Claude 能照做的指令。想自己给结果而不跑工具,返回 { result: '...' };想重试,就再调一次 next(e)。

执行前先问用户

局部片段(据官方示例缩写,匹配规则只留了强制推送一种)

on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
  if (!/\bgit\s+push\b.*--force/.test(e.command)) return next(e)
  let answer = 'Refuse'            // 默认答案是拒绝
  try {
    // 工具调用停在这里,直到用户选一项
    answer = await $.ui.ask('Run this command? ' + e.command, ['Run it', 'Refuse'])
  } catch {
    // 用户关掉了提问,或这是没人可问的 claude -p
  }
  if (answer !== 'Run it') {
    return { deny: 'The user declined this command. Ask before trying a different approach.' }
  }
  return next(e)                   // 用户同意后,常规权限检查照样进行
})

$.ui.ask 用的是 Claude 向你提问的那个对话框,选项之后还会多出「输入其他答案」和 Chat about this 两行。等待时间放在 mods API 调用里不计入 10 秒限制;自己 await 的 promise 会计入,而超时的 hook 会被跳过,被按住的命令就会执行。

按当时的状态决定权限

局部片段

on('tool.check', { tool: 'Bash' }, async ($, e, next) => {
  // 权限规则和 settings hook 已经得出的决定:'allow'、'ask' 或 'deny'
  const decided = await next(e)
  if (!e.input.command.includes('git push')) return decided
  const branch = await $.process.run(['git', 'branch', '--show-current'])
  if (branch.stdout.trim() !== 'main') return decided
  // reason 是写给 Claude 的指令:改从 main 以外的分支推送
  return { decision: 'deny', reason: 'Push from a branch other than main' }
})

这段代码只在当前分支是 main 时拒绝;reason 保留官方原文,它是一句祈使句,意思是「请从 main 以外的分支推送」。官方自己的提醒:这个 hook 只是匹配命令文本,应把它当成给 Claude 的提醒;要对所有人禁止推 main,去 Git 托管平台上保护分支。

改写或补充提示词

其余 Claude 会读到的内容由别的事件管:prompt.section(系统提示词的每一段)、prompt.context(随第一条消息发送的上下文)、skill.prompt(skill 的正文)。这些 hook 产出的文字如果每次请求都变,会让 prompt cache 失效。

跟踪回合、读用量、换模型

局部片段 · turn.step 是流式事件,hook 要写成异步生成器

on('turn.step', async function* ($, e, next) {
  const result = yield* next(e)    // 发出请求,边流边转发,拿到最终结果
  if (result.usage) {
    $.ui.log('cache read ' + result.usage.cache_read_input_tokens + ' · wrote ' + result.usage.cache_creation_input_tokens)
  }
  return result
})

一个带工具调用的回合有多次请求,每次都触发 turn.step,子 Agent 的请求也算(看 e.agentId)。把某次请求发给别的模型:next({ ...e, model });也可以不调模型直接代答。turn.complete 里返回 { text: '...' } 会在回答下方显示一行。

其他常见任务

官方教程的三个示例 Mod 官方博客

多 Mod 组合与权限裁决

同一个事件上的所有 hook 串成一条中间件链。谁在外层、谁的决定是终局,决定了你的守卫到底有没有用。

洋葱链:四层顺序

事件由外向内传,结果由内向外回。最外层的 Mod 最先看到事件、最后看到结果,并决定里面的要不要运行;靠后的 Mod 无法阻止靠前的 Mod 看到事件。 官方文档

一次工具调用的裁决时序

1. Claude 发出工具调用。
2. 托管设置里的 PreToolUse hook 先跑。 终止分支:这里的 block 是终局,任何 Mod 都看不到这次调用。Mod 之后改写了调用的话,托管 hook 会对改写后的调用再跑一遍。
3. 各 Mod 的 tool.call hook 按四层顺序运行。 终止分支:任何一个 hook 不调 next 就返回 { deny } 或 { result },后面的 Mod、非托管 PreToolUse hook、权限检查和工具本身都不再运行,也不出现权限弹窗。
4. 最后一个 Mod 调了 next,进入 Claude Code 自身行为:其他 settings 文件和插件 hooks/hooks.json 里的 PreToolUse hook 运行,权限规则给出 allow、ask 或 deny。
5. tool.check 链运行,next(e) 拿到上一步的决定,hook 可以原样返回,也可以换成另一个决定。
6. 按最终决定处理:allow 直接执行;ask 弹出权限框(Mod 改不了它的样子);deny 把理由交给 Claude。auto 模式下,Mod 批准的调用不再经过分类器。
7. 工具执行,结果沿 tool.call 链由内向外返回,每个 await next(e) 的 hook 都能看到并改写结果。

Mod 的 tool.check 能推翻什么 官方文档

auto 模式下改写输入会被拒

auto 模式里,如果 hook 在分类器审过之后又改了工具调用的输入,调用会被拒,理由是 a hook changed this call's input after the model wrote it。改输入的可能是 Mod 的 tool.call、turn.step hook,也可能是 PreToolUse settings hook,消息不会说是哪一个。 官方文档

写守卫类 Mod 的七条注意

1. 固定的命令或路径用权限规则,不写代码。tool.check 留给「取决于当时状态」的判断。 官方文档
2. 文本匹配只是提醒。官方示例自己就说明它会漏掉 git push -f 这样的写法。真正的边界放在 Git 托管平台的分支保护、托管设置这类 Mod 之外的地方。 官方文档
3. 加 .catch 让它失败时拒绝,否则 hook 一出错就被跳过。
4. 等用户决定时,等待放在 $.ui.ask 里,并把默认答案设成拒绝。
5. deny 文案写给 Claude 看:说清不能做什么、该改做什么。
6. 知道自己在链上的位置:排在你前面的 Mod 代答后,你的 hook 根本不运行。 编辑推导
7. 守卫可能不在场:--safe-mode、worker 崩溃三次、Anthropic 远程关闭、hook 被跳过,都会让它消失。.catch 只保护那一个 hook,不是系统级保证。 编辑推导

状态、预算与失败恢复

三层状态,寿命各不相同

所以「跨重载存数据」用 $.state 就够;「跨会话存数据」才需要 $.store。两者不要混为一谈。

10 秒预算怎么算

另外:.catch 处理函数只有 1 秒;所有 session.end hook 合计 1.5 秒;$.process.run 默认 30 秒、最长 10 分钟。 官方文档

hook 失败之后发生什么

没有 .catch 的 hook 抛错、超时或返回形状不对时,取决于它是否已经调过 next:

会话不会因此中断,只留一行记录,如 my-mod: tool.call hook skipped: threw Error: boom。要注意「放行」的准确含义:是这个失败的 hook 不参与了,其余 Mod、权限规则、settings hook 仍按原样运行。

局部片段 · 让拦截类 hook 失败时拒绝(guard 是你的 hook 函数)

on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {
  // next.error.kind 是 'throw' 或 'timeout'
  return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }
})

worker 崩溃

所有已安装的 Mod 共用一个 worker 线程。 官方文档

• 能定位到是哪个 Mod 卡死或弄崩了 worker(比如一个从不 await 的循环):只卸载那一个,记录为 first-mod was unloaded: it crashed the hooks worker。
• worker 停了三次又定位不到:卸载所有非内置 Mod,包括组织安装的,记录为 hooks: mods that run in the hooks worker are off for this session: it crashed 3 times。执行 /reload-plugins 恢复。

测试、保留与分发

自动化测试

claude plugin test 在 shell 里运行,不需要会话、登录或网络。测试文件以 .test.ts 结尾,放在插件目录内任意位置,从 claude-code/testing 导入测试工具。有测试失败时退出码为 1,可以接进 CI。

完整示例 · first-mod/tests/first-mod.test.ts(官方代码,注释为中文转写)

import { expect, test } from 'claude-code/testing'

test('/tally reports the tool calls the mod has seen', async ($, on) => {
  // 替 Claude Code 回答每次工具调用,所以不会真的跑工具
  on('tool.call', () => ({ result: 'ok' }))

  // 触发两次工具调用,Mod 的 tool.call hook 会计数
  await $.tool.call({ tool: 'Bash', command: 'ls' })
  await $.tool.call({ tool: 'Read', file_path: 'README.md' })

  // 运行 /tally,检查 hook 返回的文字
  const answer = await $.command.run({ command: 'tally', args: '' })
  expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')
})

写测试时最容易踩的规则: 官方文档

• 测试里的 $ 站在 Claude Code 的位置上,不是 hook 拿到的那个 mods API;on 用来注册 stub,替 Claude Code 作答。
• 所有 stub 必须在第一次调用 $ 之前注册。
• session.start 不会自动触发。hook 依赖它做的准备时,要先手动触发,并给 command.register 之类的调用配上 stub。
• mods API 调用的 stub 返回 { value: ... };事件的 stub 返回该事件自己的结果形状,如 { result: 'ok' }。让调用失败用 { deny: '原因' }。
• 定时器用 mock.clock(on) 拨时间;存储和环境变量有 mock.store、mock.env。
• 界面用 $.ui.mount 画出某个渲染位,再用 press、input、select、find 操作和断言。它只检查 hook 返回的树是否合法,不检查实际画出来的样子,新布局还得进真实会话看一眼。

分发

• Mod 就是插件:在 manifest 里写版本,别人用 /plugin 命令安装和更新;要给别人用就放进 marketplace。
• 插件名不能像 Anthropic 官方的名字,例如以 claude- 开头的名字过不了 claude plugin validate。
• 在 README 里写明测试过的 Claude Code 版本。
• 已安装的插件按版本缓存。直接改已安装副本不会生效,要提高版本号重新安装。开发始终对着 --plugin-dir 的工作目录。

症状驱动的排错

Mod 的模块或 hook 出错时会被跳过、会话照常继续,所以「坏了」和「没反应」看起来一样。先做两个检查,再按症状找。

Mod 根本没加载

拒绝加载的消息

加载了,但 hook 被跳过或 Mod 被卸载

工具调用被拒

界面不出现或没反应

改动或数值丢了

读调试日志

局部片段

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
tail -f ./mod-debug.log | grep first-mod      # 另开一个终端

想往调试日志里写自己的行:$.ui.log('message', { to: 'debug' })。

参考区

可折叠的速查表,以 v2.1.287 文档为基线。精确字段以本机类型声明文件为准。

hook 函数与 next 的附属成员

• 入口:export function register(on, options);注册:on(event, matcher?, hook),返回值可接 .catch(handler);hook 形如 async ($, e, next) => ...。
• next.signal、next.origin(含 plugin、tier)、next.budget(含 ms、remainingMs)。
• next.to(e, tier):仅 prepend / append 层的 Mod 可用。
• next.error、next.called:仅在 .catch 处理函数里有。

事件族

工具

tool.call、tool.check、tool.describe

提示词与 Claude 读到的内容

prompt.submit、prompt.fill、prompt.suggest、prompt.edit、prompt.compose、prompt.section、prompt.context、prompt.attachment、skill.prompt、attribution.text

命令与配置

command.run、command.describe、config.set、config.describe

回合

turn.start、turn.step(异步生成器,可换模型)、turn.complete

会话

session.start、session.end、session.compact、session.receive、session.send、session.append、session.attach、session.detach、session.measure

子 Agent

agent.offer、agent.spawn

界面

ui.render、ui.resolve、ui.press、ui.input、ui.select、ui.focus、ui.scroll、ui.close、ui.message

其他 Mod 与引擎

plugin.register、engine.create

遥测

telemetry.log、telemetry.mark。'*' 不含它们,要按名字或 'telemetry.*' 挂。

settings hook 事件

classic.<事件名>,如 classic.Stop、classic.SessionStart;通配 'classic.*'。

每个 mods API 调用

方法名去掉 $. 就是事件名,如 fs.write。组织的策略 Mod 可以据此记录或拒绝其他 Mod 的调用。

$ 的 21 个命名空间

下面的分组是为了方便查找做的编辑归类,不是官方分类。 编辑推导

界面与交互

ui、command、prompt、audio

对话与 Agent

turn、session、agent、tool、mcp

模型

model(complete、fork、classify)

系统

fs、process、http、env、clock

状态与配置

state、store、config、settings

插件与遥测

plugin、telemetry

hooks module 的运行环境是受限的:没有 Node API、没有 setTimeout、没有自带的网络和文件访问,一切经由 $。这是运行环境的形态,不是安全沙箱。

渲染位与元素

渲染位

Pane、AbovePrompt、UserMessage、AssistantMessage、ToolUse、ToolResult、ToolGroup、CommandOutput、AskUserQuestion、Spinner、SessionMode、PromptHint

仅终端的渲染位

ToolProgress、TurnDuration、InfoNotice

元素

Box、Text、Button、Link、Code、Markdown、Input、Select、Client

平台专属元素

仅桌面:Svg。仅终端:Raster、Image。

权限弹窗不是渲染位,Mod 改不了。输入框本身不是「完全不能碰」:有 prompt.fill、prompt.suggest 事件,也有 Input 元素可画自己的输入框。

限制速查

时间

hook 自身 10 秒;.catch 1 秒;session.end 合计 1.5 秒;$.process.run 默认 30 秒、最长 10 分钟;单个测试默认 5 秒、toast 默认显示 4 秒,两者都可用 timeoutMs 改。

大小

$.fs 单文件 4 MiB;$.store 合计 4 MiB JSON;会话消息取最新 4096 条;$.model.complete 的 maxTokens 默认 1024。

频率

重画每秒 10 次;可见的面板和信息带每秒 30 次。

终端宽度

自动打开面板需要至少 144 列;用户自己打开过一次之后是 110 列。这是终端列数,和本页的网页断点无关。

命名

命令、工具、子 Agent 类型和面板的名称不超过 64 个字符,只能用字母、数字、_ 和 -。这条不针对插件名。

组织管控设置

allowManagedModsOnly

内置守卫的选项,写在托管设置的 pluginConfigs["cc-plugin-sec-default@builtin"].options 下。用户自带的 Mod(安装的、--plugin-dir 的、Claude 代写的)都不加载;他们的 settings hook、状态栏、/goal 不受影响。

allowModsToOverrideDenyRules

内置守卫的选项。不设时 deny 规则压过用户的 Mod;设为 true 后用户的 Mod 可以批准 deny 规则拒绝的调用。

allowManagedHooksOnly

范围更大:只有组织的 Mod 和内置 Mod 加载,同时挡掉用户自己设置文件里的 hook。

disableAllHooks

范围最大:写在托管设置里时,停掉所有已安装插件的 Mod(含组织自己的)和所有 settings hook,托管的 PreToolUse hook 也不再拦截;自定义状态栏和 /goal 一起停。

disableSideloadFlags

启动时拒绝 --plugin-dir、--plugin-url,并阻止 Claude 代写的 Mod 加载;同时拒绝 --agents 和 --mcp-config。

prependPlugins / appendPlugins

决定组织 Mod 在链上的位置。设了 prependPlugins 就要把 sec-default@builtin 也列进去,否则守卫不加载。只从托管设置读取;仓库的设置文件无效。

什么算「组织的 Mod」

三个条件同时满足:托管的 enabledPlugins 启用了它;托管设置把它的 marketplace 指到本机一个绝对路径的目录;marketplace 用相对路径列出它(就地加载)。从 GitHub、git、URL、npm 拷进缓存的插件一律算用户的。

守卫保护的内容

用户的 Mod 改不了:托管 hook 收到和决定的内容、系统提示词、托管的 CLAUDE.md 等指令、任何 Mod 读到的设置、托管 MCP server 的工具与描述。除此之外不加限制。守卫读不到托管设置时会拒绝所有用户 Mod。

策略 Mod

放在 prependPlugins 的 Mod 可以挂 plugin.register:每个 Mod 加载前都会把 validate 那份清单(e.uses.calls、e.tier)交给它,返回 { refuse: '理由' } 即可拒绝加载。这个检查同样要加 .catch,否则出错时放行。

环境变量与其他设置名:CLAUDE_CODE_PLUGIN_DIRS、CLAUDE_CODE_PLUGIN_DIR_WATCH、pluginConfigs。具体取值见官方 reference 页的 Settings and environment variables 一节。

命令速查

• claude plugin validate <目录>(可加 --strict、--json):静态检查并列出 hooks 与 calls。
• claude plugin test [目录]:跑测试;在无 Mod 的目录里可用来判断 Mod 能否加载。
• claude --plugin-dir <目录>(可重复):本次会话加载,保存即重载。
• /reload-plugins:重新加载插件。
• /plugin:查看、启用、停用;显示 mods active 行。
• claude --debug、claude --debug-file <路径>:写调试日志。
• claude --safe-mode:不加载已安装的 Mod 和其他自定义项。

更正记录、时间线与来源

这次研究的起点是一篇流传较广的中文解读(公众号文章的 AI 摘要笔记)。下面逐条对照官方资料。每条标两个维度:依据的来源类型,和结论状态。

更正记录

仍未解决的问题 待核实

下面这些在这次打开的官方页面里没有找到明确答案,不要当成事实使用:

• 卸载一个 Mod 后,它在 $.store 里的数据是否立即清除。
• 已安装 Mod 的版本锁定与回滚的推荐做法(组织侧有 update policy,个人侧未查)。
• 同一层里互不依赖的多个用户 Mod,先后顺序由什么决定。
• hook 是否可能并发重入,next.signal 在链上如何传播。
• marketplace 上的插件是否有签名校验。

时间线

• 2026-09-03GitHub issue #91870 提出提案。 源码仓库
• 2026-09-09提案更名为 Claude Mods。 源码仓库
• 2026-10-01v2.1.287 发布,changelog 写道「Added Claude Mods: plugins may now modify deeper behavior」;同版加入内置条目 You should know。官方博客与入门教程同日发布。 发布说明
• 2026-10-02本页核验官方资料;v2.1.287 仍是最新版本。

来源清单

这份资料是怎么做的

事实部分全部来自 2026-10-02 实际打开的官方页面;代码示例取自官方文档,只把注释转写成中文,个别做了缩写并已注明。标「编辑推导」的内容是基于官方事实做的归纳,标「二手转述」「待核实」的没有一手出处。全文没有在真实会话里跑过任何一个 Mod。