SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Claude Code 插件是什么,安装和费用怎么算

了解 Claude Code 插件的组成、存放位置和安装方式:插件机制本身不收费,但其中技能、MCP 服务器和其他内容会消耗上下文 Token。

Claude Code 插件是什么

Claude Code 插件是一个组件目录,Claude Code 会将其作为一个整体加载和管理。主要组件包括技能、代理、钩子、MCP 服务器、LSP 服务器和后台监控程序。插件还可以包含命令、输出样式、主题、工作流,以及包含可执行文件的 bin/ 目录。安装插件会一次性添加其中的所有组件,并统一使用一个名称;禁用插件也会以同样的方式移除这些组件。

插件通常不会赋予代理原本不具备的能力。技能、代理、钩子和 MCP 服务器都可以手动写入 .claude/ 目录。例外包括用于代码智能的语言服务器和 mods;Claude Code 只能从插件加载这些组件。对于其他组件,插件只是打包层:它可以为这些组件进行版本管理,将它们交给十五个人使用,并在之后更新,而无需要求每个人复制文件。插件的核心作用就是这些。人们对插件的大多数困惑,都源于误以为插件是一种全新的能力。

.claude-plugin/plugin.json 中的可选清单用于命名插件,该名称会成为命名空间。名为 commit-commands 的插件中的技能可调用为 /commit-commands:commit。因此,两个插件可以分别提供名为 commit 的技能,而不会相互覆盖。插件代理在 @ 提及列表中也使用相同的作用域规则,例如 plugin-name:agent-name。

插件、技能、MCP 服务器或规则文件

这四个术语经常被当作相互竞争的选项使用。实际上并非如此,下面统一说明它们的边界。

  • 技能是 Claude 在任务需要时加载的一组指令。请参阅Agent Skill 的实际含义。
  • MCP 服务器是通过协议向代理公开工具的独立进程,通常是您自行运行的网络服务。
  • CLAUDE.md 这类规则文件属于项目上下文,会在会话开始时读取,并应用于所有内容。
  • 插件是由技能、代理、钩子、MCP 服务器或其他组件组成的目录,Claude Code 会将其作为一个单元安装和加载。插件可以选择提供清单文件,用于指定插件名称,并添加版本、描述及其他元数据。分发不属于插件本身:市场是独立的目录,用于列出插件及其获取位置。

因此,插件要回答的问题不是“代理能做什么”,而是“我如何将这些内容交付给团队,并在下个月更新”。如果您正在前三者之间进行选择,技能、MCP 服务器和规则文件的比较会详细介绍相关决策。如果您关注的是 MCP 部分,在 VPS 上运行自己的 MCP 服务器会介绍托管方式。

插件存放位置及其内容

大多数市场插件都会复制到 ~/.claude/plugins/cache 下的本地缓存中,每个已安装版本使用一个单独的目录。从本地路径添加的市场中,使用相对路径的插件会在原位置加载;处于链接模式的命令源插件会通过指向其源目录的链接加载。更新或卸载已复制的插件时,旧版本目录会标记为孤立目录,并在约两周后删除。因此,已经加载旧版本的会话可以继续运行,不会在任务中途失败。只有在至少保留一个插件安装记录时,清理任务才会运行;卸载最后一个插件后,孤立目录会一直保留,直到再次安装插件。

由于已复制插件的路径会在每次更新时变化,插件绝不能硬编码自身位置。插件中的钩子和 MCP 配置使用 ${CLAUDE_PLUGIN_ROOT},该变量会解析为当前安装目录。需要在更新后保留的状态应存放在 ${CLAUDE_PLUGIN_DATA} 中,该变量会解析为 ~/.claude/plugins/data/ 下的稳定目录。

对于已复制的插件,缓存中只会复制插件自身的目录;同一市场中位于其他位置的符号链接目标除外,这些目标会被复制到对应位置。读取插件根目录之外路径的脚本(例如 ../shared-utils)在使用本地路径开发时可以正常运行,但插件复制到缓存后会失败,因为这些文件根本没有被复制。以这种方式在 plugin.json 中声明的组件路径会更早失败:Claude Code 在开发期间也会拒绝任何超出插件根目录的组件路径,并显示 path escapes plugin directory 错误。

目录结构如下。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

只有 plugin.json 会放在 .claude-plugin/ 内。其他内容都位于插件根目录。将 skills/ 或 hooks/ 放入 .claude-plugin/ 是插件安装成功后完全不起作用的最常见原因:Claude Code 会在根目录查找这些目录,但找不到任何目录,因此会加载一个不包含组件的插件。

清单本身很小。

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0"
}

如何安装 Claude Code 插件

安装分为两步,第一步不会安装任何内容。您需要添加一个 marketplace,它是插件目录,然后从中安装单个插件。Anthropic 的官方 marketplace claude-plugins-official 会在您首次以交互方式启动 Claude Code 时自动为您注册,除非托管策略或 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL 阻止了该操作。其他 marketplace 需要您自行添加。

/plugin marketplace add anthropics/claude-plugins-official
/plugin install commit-commands@claude-plugins-official

marketplace 名称来自仓库中的目录文件,而不是仓库路径。因此,在输入安装命令前,请从 /plugin 的 Marketplaces 选项卡中读取 marketplace 名称。anthropics/claude-code 中旧的 claude-code-plugins marketplace 已弃用;新安装请使用 claude-plugins-official。该旧 marketplace 中已有的插件会从官方仓库更新,因此您无需仅为更换 marketplace 而重新安装 commit-commands。

安装完成后,请阅读摘要行。Plugin is now active. 表示组件已在当前会话中加载。Run /reload-plugins to apply. 表示安装期间未激活这些组件;面板会关闭,Claude Code 会代您执行重新加载。如果重新加载警告说它将重新读取对话,则插件会保持待处理状态,您需要将其重新运行为 /reload-plugins --force。然后确认插件确实存在:/plugin 会在 Installed 选项卡下显示该插件,输入 / 会将其技能列为 /plugin-name:skill-name,任何加载失败的内容都会显示在 Errors 选项卡下,并附带失败原因。

安装时需要选择作用域,作用域决定谁可以使用该插件。用户作用域仅适用于您本人,并且适用于每个项目。项目作用域会将插件写入仓库的 .claude/settings.json 中的 enabledPlugins,从而为所有克隆该仓库的用户启用插件。但插件不会自动下载到他们的机器上:每位协作者仍需在自己的机器上安装一次,例如使用 claude plugin install name@marketplace --scope project,除非其 marketplace 条目使用相对路径,或种子目录中已经包含该插件。本地作用域仅适用于您本人,并且仅限当前仓库。

对于脚本、Dockerfile,或任何无法使用交互式面板的会话,请改用 shell 形式。除非传入 --scope,否则它会安装到用户作用域。在尚未有人打开过交互式会话的机器上,官方 marketplace 尚未注册,因此请先添加它。

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install commit-commands@claude-plugins-official --scope project
claude plugin list

claude plugin install 会在会话外运行,因此已经打开的会话在您运行 /reload-plugins 或启动新会话之前不会看到新插件。

在这两种环境中,管理已有内容的方式相同。/plugin list 会列出已安装的内容,并接受 --enabled 或 --disabled。/plugin disable name@marketplace 会停用插件但不会删除它,/plugin enable 会重新启用插件,/plugin uninstall 会删除插件。斜杠命令形式会打开插件面板来应用更改,因此在脚本中应使用 claude plugin ... shell 等效命令。

要将 marketplace 提供给整个团队,请将其放入项目的 .claude/settings.json 中,或者运行一次 claude plugin marketplace add your-org/claude-plugins --scope project,然后提交它写入的文件。Claude Code 会在每位成员信任该仓库目录后,为其注册该 marketplace。

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

在构建自己的插件时,可以完全跳过 marketplace。claude --plugin-dir ./my-plugin 会为当前会话加载一个目录,/reload-plugins 会在不重启的情况下应用您的修改,claude plugin validate ./my-plugin 会在其他人使用前检查清单文件、技能和代理的 frontmatter,以及 hooks/hooks.json。共享插件也不要求使用 marketplace:您可以将目录发送给他人,或发送其 .zip,让对方使用 --plugin-dir 加载;但在您发送新副本之前,对方不会获得更新。

Claude Code 插件需要多少钱?

该机制免费。截至 2026 年 11 月,添加 marketplace、安装插件或保持插件启用都不收费。官方和社区 marketplace 都是公开的 git 仓库,插件本质上是一个文本文件目录。

插件消耗的是 token,而 token 才是订阅用量或 API 账单实际计量的单位。具体消耗哪一种额度,取决于您最初如何为该工具付费;Claude Code 各套餐的费用同时列出了订阅层级和按 token 计费的 API 价格。这些成本有 3 种来源,行为也各不相同。

持续上下文成本。 每个启用的插件都会将其 skill、agent 和 Claude 可自主调用的 command 的名称与说明加入上下文。无论这些组件是否运行,每一轮会话都会重新读取这部分内容。并非所有组件都会消耗 token:hook 由 harness 运行,不会加入模型上下文。安装前,/plugin 详细视图中的 Will install 部分会列出即将添加的 command、skill、agent、hook、MCP 和 LSP server。对于 Anthropic 官方 marketplace 中的插件,只要您通过 marketplace 名称打开插件,或从 Marketplaces 选项卡打开,而不是从 Discover 列表打开,该视图还会显示包含 Every turn 和 When invoked 估算值的 Context cost 部分。请同时查看这两部分。来自您自己的 marketplace 或第三方 marketplace 的插件没有 Context cost 部分,但您无需手动估算:在 shell 中运行 claude plugin details name,即可输出任意已加载插件的 Always-on token 数量和按组件划分的明细,包括通过 --plugin-dir 传入的插件。因此,您可以先克隆仓库,再运行 claude --plugin-dir ./that-plugin plugin details that-plugin,然后决定是否安装。该数值不包括 MCP server。捆绑 MCP server 的插件通常最占用上下文,因为 tool definition 较大;不过,在支持 MCP tool search 的模型上,这些 definition 会延迟到需要调用工具时才加载。在启用插件的会话中运行 /context,然后查看 MCP tools 行,了解它们增加了多少内容。

调用成本。 运行插件的 skill 时,其指令会追加到对话中,因此只有使用 skill 时才会为 skill 正文付费。不过,正文并不是主要成本;skill 要求 agent 执行的操作可能很昂贵:unlazy skill 的 Depth Tree 方法几乎将所有 token 都花在它强制 agent 执行的额外处理轮次上,而不是花在您安装的文件上。agent 则有所不同。subagent 会使用自己的 system prompt 和自己的缓存运行独立对话,并且开始时没有缓存命中。因此,工作流会创建 agent 的插件,其成本会显著高于上下文估算值所显示的成本。

缓存成本。 在会话中途启用或禁用插件,可能会导致下一次请求重新处理整个对话。Skill、command、agent、hook、monitor 和 theme 都不会触发这种情况:它们添加的内容会追加到现有历史记录之后,因此下一次请求只需为新内容付费,之前的内容仍从缓存中读取。例外是提供 MCP server 的插件,以及代码智能插件;后者的 language server 会向 Claude 提供 LSP 工具。对于 MCP,具体情况取决于 tool search:如果工具被延迟加载,缓存会保留;如果工具被加载到 prompt prefix 中,下一次请求就会将整个对话作为未缓存输入重新读取。这正是 /reload-plugins 会在 MCP 工具或 LSP 工具的变更可能破坏缓存时发出警告并拒绝执行的原因,除非您传入 --force。

您可以直接监控这些数据,而不是凭猜测判断。每个 API 响应都会报告 cache_read_input_tokens 和 cache_creation_input_tokens;配置一个显示实时 token 用量的自定义 statusline后,您可以随时看到这两个值。健康的会话通常读取的内容远多于创建的内容。如果创建量在连续多个回合中都很高,说明 prefix 中的某些内容每回合都在变化。要了解上下文窗口中正在填充哪些内容,请参阅如何管理 Claude Code 上下文窗口和这些 token 计数的实际含义。

有一项维护工作可以降低成本。Installed 选项卡会将至少 14 天和 10 个会话未使用的 marketplace 插件归入 Not used recently 标题下,详细视图中会显示 Last used 行。该标题不包括 managed 插件和 seed-directory 插件,也不包括带有 theme、output style、monitor 或 workflow 的插件;LSP server 在提供诊断信息或响应代码导航请求时,才算被使用。配置 strictKnownMarketplaces 后,标题和 Last used: 行都不会显示。这些插件仍会在每个会话中增加启动时间和上下文成本。请禁用或卸载它们。更省钱的做法是在安装前进行筛选:Matt Pocock 的哪些 skill 值得安装分析了一个包含 27 个 skill 的集合,并区分了单人开发者真正需要的少数 skill,以及只有团队环境才能发挥价值的 skill。

插件以您的权限运行

Anthropic 的官方文档对此说明得很明确:您安装的插件可以在本机上以您的用户权限执行任意代码。这并非假设情形。插件的钩子会在会话事件中运行 shell 命令,包括工具调用前后。插件启用期间,其 bin/ 目录会加入 Bash 工具的 PATH。插件的 stdio MCP 服务器是由插件启动的进程,mod 则会在 Claude Code 本身内部运行 JavaScript。钩子、监控器、服务器进程和 mod 进程都在 Claude Code 沙箱之外运行;但 Claude Code 发起的工具调用仍受其权限规则约束。

在笔记本电脑上,这种风险受桌面用户可访问范围的限制。在服务器上通常不是这样。运行代理的账户通常持有 SSH 密钥、部署令牌、云 CLI 会话,并可访问 Docker socket。因此,“以您的用户身份执行任意代码”实际上就意味着可以控制整台机器。如果 Claude Code 运行在 VPS 上,请先阅读如何在 VPS 上安全运行 Claude Code,再安装任何内容;如果要安装与外部服务通信的插件,请先阅读如何让代理无法访问凭据。其他代理框架在同一台租用的服务器上也会遇到相同限制。因此,值得安装的 DeepSeek Harness 插件主要是消费上限、工具权限规则和注入扫描,而不是新增功能。

确实存在一些防护措施,了解其范围很有帮助。项目范围插件来自仓库,而不是来自您本人,因此只有在您信任该工作区后才会加载;但其中的 MCP 服务器仍需逐个批准,后台监控器则完全不会加载。插件提供的代理不能声明钩子、MCP 服务器或权限模式。将市场插件复制到缓存时,指向市场目录之外的符号链接会被跳过,因此复制的插件无法通过这些链接加载主机上的任意文件。

这些措施都不能替代对所安装内容的审查。检查 Will install 列表,优先选择可以打开并阅读源代码的插件,将团队使用的插件保存在您控制的市场仓库中,并对您自行编写的内容运行 claude plugin validate。您审查过的内容之后也可能发生变化:Anthropic 官方市场默认启用自动更新,但 knowledge-work-plugins 和 first-party-plugins 除外;通过源添加的第三方市场默认禁用自动更新。启用自动更新时,Claude Code 会在后台更新插件文件。

FAQ

Claude Code 插件是否需要额外付费?

不需要。插件系统、添加 marketplace 或安装插件都不收费。费用来自 token 使用量,和其他上下文一样计入您的套餐费用或 API 支出。插件会在每轮对话中增加固定上下文;调用其中的 skill 或 agent 时,还会增加更多上下文。如果插件提供 MCP server,且其工具会加载到 prompt 前缀中,还可能强制产生一次昂贵的未缓存轮次。对于 Anthropic 官方 marketplace 中的插件,安装前可在 /plugin 详细视图中查看 Context cost 估算值;对于其他插件,安装或使用 --plugin-dir 加载后,claude plugin details name 会输出其始终占用的 token 成本。

插件和 skill 有什么区别?

skill 是一个独立的指令单元。插件是一个软件包,可以包含 skill、agent、hook、MCP server、LSP server 和 monitor,并具有名称,通常还有版本,也通常有用于安装它的 marketplace;但它也可以作为文件夹或 .zip 共享,由用户使用 --plugin-dir 加载。如果 skill 只供您和当前项目使用,请在 .claude/ 中编写独立 skill。像 促使 agent 采用可行的最小改动的 Ponytail 这样的单一用途 skill 就是最清晰的例子:它只有一个文件和一条规则,直到团队也需要使用它为止。如果其他人也需要使用它,并且需要持续更新,就应将其转换为插件。插件中的 skill 使用命名空间,因此插件内的 skill 以 /plugin-name:skill-name 调用,而不是 /skill-name。

我的插件已安装,但其中的 skill 没有显示。哪里出了问题?

先检查安装摘要。如果其中显示 Run /reload-plugins to apply.,Claude Code 会在面板关闭时执行重新加载;如果重新加载提示将重新读取对话,请将其重新运行并使用 /reload-plugins --force。如果插件已加载但没有显示内容,请打开 /plugin 并查看 Errors 选项卡。最常见的结构错误是将 skills/、agents/ 或 hooks/ 放在 .claude-plugin/ 中,因为 Claude Code 不会在那里查找它们。请记住,插件中的 skill 使用命名空间,因此输入 / 时应查找 /plugin-name:skill-name。如果这是其他人的插件,并且加载时没有报错,请在 Installed 选项卡中打开其详细信息窗格:如果插件在那里没有列出任何 skill,就表示它没有可提供的 skill。如果 Errors 选项卡显示插件未缓存,说明其安装目录缺失。请从 shell 使用 claude plugin install name@marketplace 重新安装,然后运行 /reload-plugins。

可以不使用交互式面板安装插件吗?

可以。使用 shell 命令 claude plugin install name@marketplace。除非传入 --scope project 或 --scope local,否则它会安装到用户作用域。该命令可用于脚本、镜像和无法使用 /plugin 面板的非交互式环境。由于它在会话外运行,已经打开的会话需要执行 /reload-plugins,插件才会生效。在没有交互式终端的会话中,插件 MCP server 的更改会在下一个会话中生效。

从 GitHub 上找到的 marketplace 安装插件安全吗?

请按照以当前用户身份运行该仓库安装脚本的方式对待它,因为两者的行为基本相近。插件可以通过 hook 运行 shell 命令,向 Bash 工具的 PATH 添加可执行文件,并启动 MCP server,且这些操作都使用您当前用户的权限。Anthropic 不控制或验证第三方插件的内容。请从可读取和审查的来源安装,并在确认前查看 Will install 列表。在服务器上应比在笔记本电脑上更加严格,因为服务器上的账户通常持有值得窃取的密钥和 token。

这篇文章对您有帮助吗?