Claude Mods 是 Claude Code 正在开发的新扩展机制，以 TypeScript 函数修改命令、工具调用、界面和安全策略。Anthropic 于 2026 年 9 月 9 日确认该名称，官方讨论已有 173 条评论。

该机制目前仍属 Early Access。官方表示计划在数周内发布，但接口可能随版本变化。

claude-mods-img1.png

Claude Mods、Function Hooks、Plugins 有什么关系

Claude Mod 是使用 Function Hooks 的 Claude Code 插件。Function Hooks 是底层实现机制，Mod 是面向用户的产品名称，Plugin 是承载清单、Hook 模块和代码的安装单元。

名称

负责什么

当前状态

Classic Hooks

在既定事件前后执行命令或脚本

已稳定提供

Function Hooks

以 TypeScript 函数拦截和改写引擎事件

Early Access

Claude Mods

使用 Function Hooks 构建的插件

计划数周内发布

Skills

向 Claude 提供任务说明、知识和流程

已稳定提供

MCP

把外部工具和数据源暴露给 Claude

已稳定提供

Mods 的价值不只是“再加一个命令”。传统 Hook 常通过退出码和标准输出影响流程；Function Hook 收到结构化事件，可以决定继续、改写、拒绝或观察调用，还能参与 UI 渲染。

Function Hook 的执行模型

每个 Mod 用一个 register(on, options) 入口注册事件处理函数，处理函数接收 ($, e, next) 三个参数：

  • $：由引擎提供的能力接口，例如文件、进程、界面、设置和会话操作。

  • e：当前事件的结构化数据。

  • next：把事件交给链中下一层处理器。

多个 Mod 按注册顺序组成类似 Express 或 Koa 的洋葱式中间件。先注册的处理器包住后注册的处理器，因此组织管理员可以把安全 Mod 放在最外层，先检查请求并最后检查结果。

export default function register(on) {
  on('tool.call', async ($, event, next) => {
    if (event.tool === 'Bash' && looksDangerous(event.input)) {
      return { deny: 'Command blocked by policy' }
    }

    const result = await next(event)
    return result
  })
}

这段代码只展示官方架构的处理形态，不是稳定 API 示例。字段名和返回结构必须以安装版本生成的类型声明为准。

Claude Mods 与传统 Hooks 的核心差异

Function Hooks 的主要变化是从“调用外部脚本”转向“参与引擎事件链”。官方提案允许 Hook 监听 MCP 与非 MCP 工具调用，并通过 $ 访问受控副作用。

对比项

Classic Hooks

Claude Mods / Function Hooks

输入

常见为环境变量、JSON 或命令参数

带类型的结构化事件

返回方式

退出码、标准输出

返回值、next(event) 或拒绝结果

组合方式

多个独立脚本

按注册顺序嵌套

UI 扩展

能力有限

可拦截渲染与交互事件

权限控制

依赖脚本和系统权限

副作用集中经过 $

开发体验

任意脚本语言

TypeScript 类型和 LSP 支持

当前如何启用 Claude Mods

截至 2026 年 9 月 15 日，Function Hooks 没有进入稳定通道。官方 Issue 公布的实验启用方式是：

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude

启用前先升级到支持该实验接口的 Claude Code 版本。官方更新提到 v267/v268 附近的测试接口，但没有承诺跨版本兼容，因此不要在生产环境依赖这些版本号。

要从官方源码试运行 diff Mod，可以在 Claude Code 仓库 checkout 中执行：

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 \
claude --plugin-dir mods/diff

进入一个包含未提交修改的 Git 仓库，再运行：

/diff

官方 README 说明，/diff 会在对话旁显示本次会话的未提交修改，并在 Claude 编辑文件、执行命令或完成一轮任务后刷新。

官方公开的三个内置 Mod

Anthropic 当前公开了 3 个内置 Mod 的源码，它们展示了 Mods 可以覆盖的三个方向。

diff：把代码差异面板做成插件

diff 注册 /diff 命令，读取 Git 工作区变化并渲染文件列表和 hunks。它会监听 session.start、command.run、tool.call、turn.complete、prompt.submit 和多种 UI 事件。

sec-default：保护企业管理策略

sec-default 位于组织策略链的外层，避免用户安装的插件改写托管 CLAUDE.md、Classic Hooks、设置和 MCP 白名单。它本身不增加策略，而是保持管理员原有策略的优先级。

telemetry：为其他 Mod 提供统计接口

telemetry 在引擎创建阶段加入 $.telemetry，供内置插件记录有限的结构化事件。官方说明它只在 Claude Code 自身分析功能启用时工作；设置 DO_NOT_TRACK、DISABLE_TELEMETRY 或使用第三方 Provider 时不会发送。

内置 Mod

代表能力

普通用户是否应独立安装

diff

命令、Git、UI、会话上下文

可在 Early Access 中试运行

sec-default

组织策略和插件分层

否，由 CLI 按策略加载

telemetry

扩展 $ 接口

否，仅用于特定内部构建

claude-mods-img2.png

一个 Mod 的目录结构

官方内置 Mod 的目录至少包含插件清单、Hooks 配置和 TypeScript 模块。外部开发者应以当前版本的示例为模板，不要只复制单个 .ts 文件。

my-mod/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   └── register.ts
├── tests/
│   └── register.test.ts
└── types/

Claude Code 会生成供插件引用的类型声明。官方示例通过 import type ... from 'claude-code' 获得事件与测试类型，并使用下面的命令检查所有 Mod：

tsc -p mods/tsconfig.json
claude plugin test mods/diff

测试环境提供引擎自己的 $ 和插件的 on。开发者可以模拟时钟、环境变量、存储和进程返回值，验证 Mod 是否正确继续、改写或拒绝事件。

Mods 最值得关注的四个应用场景

结构化拦截危险工具调用

Function Hook 可以读取工具名和结构化参数，比在 Bash 字符串上做正则匹配更可靠。社区反馈中特别提到 git -C、heredoc 和 eval 等命令可能绕过简单字符串规则。

在模型看到结果前清理敏感信息

Mod 可以在工具结果进入模型上下文前做脱敏，例如替换日志中的密钥、邮箱或客户标识。由于它涉及上下文改写，还必须让模型知道内容已被替换，避免后续推理基于错误文件状态。

扩展 Claude Code 的界面

Function Hooks 能监听 ui.press 和渲染事件，因此插件可以增加按钮、面板或包装已有组件。官方 diff Mod 已展示终端和桌面端共享交互事件的方向。

建立完整审计链

通配事件 Hook 可以观察插件通过 $ 发起的调用，适合记录谁调用了什么能力、是否被拒绝以及返回结果。企业仍需自行定义日志保留、脱敏和访问规则。

权限模型比扩展能力更重要

Claude Mods 把文件、网络、进程和 UI 等副作用集中到 $，管理员可以移除下层插件可用的能力。官方维护者表示，目标不是默认禁止所有插件，而是让管理员可以审计、白名单或拒绝这些能力。

安装第三方 Mod 前至少检查：

  1. 插件监听了哪些事件。

  2. 它调用了 $ 上的哪些能力。

  3. 是否读取文件、环境变量或会话凭证。

  4. 是否向外部地址发送数据。

  5. 管理员策略是否位于插件链外层。

模型 API 与 Mod 扩展应分层配置

Claude Mods 扩展的是 Agent Harness，模型 API 决定推理服务来源，两者应分别管理。

七牛云 Token Plan（DeepSeek-V4、Kimi-K3、GLM-5.3、MiniMax-M3 等 15 款国产模型，¥2,999/月起，单 API Key 切换，兼容 OpenAI 格式，https://api.qnaigc.com/v1）

它适合独立的 OpenAI-compatible 客户端或服务。

它并不等于 Claude Mods，也不能替代 Claude Code 对 Provider 的正式支持。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ['QINIU_TOKEN_PLAN_KEY'],
    base_url='https://api.qnaigc.com/v1',
)

response = client.chat.completions.create(
    model='deepseek-v4-xxx',  # 上线前替换为控制台中的有效模型 ID
    messages=[{'role': 'user', 'content': '审查这段插件逻辑的权限边界'}],
)
print(response.choices[0].message.content)

现在是否值得使用 Claude Mods

适合试用的人包括 Claude Code 插件作者、重度 Hook 用户和需要集中权限控制的企业团队。普通用户可以先关注官方 diff 示例，不必立即迁移现有 Hooks。

当前最大的限制有三个：接口可能无预告变化、Mods 尚未列入官方 Marketplace、实验开关不代表生产支持。应把测试限制在独立仓库和非敏感数据中，并保留现有 Classic Hooks 作为回退方案。

据 Anthropic 的 Claude Mods 官方讨论和内置 Mods 源码说明，Claude Mods 已确定产品名称、核心事件模型和首批三个内置实现。

截至 2026 年 9 月 15 日，该功能仍处于 Early Access。本文属于高时效内容，建议在正式发布或 Marketplace 上线后立即复核启用命令、事件类型和安装流程。