Claude Code 插件是什么？安装位置与真实成本

Claude Code 插件是什么

Claude Code 插件是一个组件目录，Claude Code 会将其中的组件作为一个整体加载和管理。这些组件包括技能、代理、钩子、MCP 服务器、LSP 服务器和后台监控器。安装插件会一次性添加其全部组件，并统一使用一个名称；禁用插件也会以同样的方式移除这些组件。

插件不会赋予代理原本不具备的能力。插件中的每个组件，都可以手动写入 .claude/ 目录。插件只是打包层：用于为这些组件进行版本管理，将它们交给十五个人，并在之后更新，而无需让每个人手动复制文件。插件的作用就是这些。人们对插件的大多数困惑，都源于误以为插件是一种新的能力类型。

.claude-plugin/plugin.json 中的可选清单文件用于定义插件名称，该名称会成为命名空间。名为 commit-commands 的插件中的技能，其调用名称为 /commit-commands:commit。因此，两个插件可以各自发布名为 commit 的技能，二者不会相互覆盖。插件代理在 @-mention 列表中也使用相同的作用域规则，例如 plugin-name:agent-name。

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

这四个词经常被当作相互竞争的选项使用。实际上并非如此，有必要在此明确它们之间的边界。

• 技能是 Claude 在任务需要时加载的一组指令。请参阅Agent Skill 的实际含义。
• MCP 服务器是一个独立进程，通过协议向代理公开工具，通常是由您自行运行的网络服务。
• 规则文件（例如 CLAUDE.md）是项目上下文，在会话开始时读取，并应用于所有内容。
• 插件是一个容器，可将技能、代理、钩子和 MCP 服务器定义集中在一起，同时包含版本号和分发渠道。

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

插件存放位置及其内部结构

从 marketplace 安装的插件会复制到 ~/.claude/plugins/cache 中的本地缓存，而不是从克隆位置直接运行。每个已安装版本都有自己的目录。更新或卸载插件时，旧版本目录会被标记为孤立目录，并在约两周后删除。因此，已经加载旧版本的会话可以继续运行，不会在任务中途失败。

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

缓存中只会复制插件自身的目录。这会导致一个容易在后期遇到的问题。指向插件根目录之外路径的配置（例如 ../shared-utils）在使用本地路径开发时可以正常工作，但安装后会失效，因为这些文件从未被复制。

目录结构如下。

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 会在根目录中查找这些目录，但找不到任何目录，于是加载一个不包含组件的插件。

manifest 本身很小。

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

如何安装 Claude Code 插件

安装分为两步，第一步不会安装任何插件。您需要先添加一个 marketplace（插件目录），然后从中安装单个插件。首次以交互方式启动 Claude Code 时，Anthropic 官方 marketplace claude-plugins-official 会自动为您注册。其他 marketplace 需要手动添加。

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

请注意，仓库是 anthropics/claude-code，而 marketplace 名称是 claude-code-plugins。该名称来自仓库中的目录文件，而不是仓库路径。因此，在输入安装命令前，请从 /plugin 的 Marketplaces 选项卡读取 marketplace 名称。

安装完成后，查看摘要行。Plugin is now active. 表示组件已在当前会话中加载。Run /reload-plugins to activate. 表示组件尚未加载，您需要运行该命令。如果 /reload-plugins 警告重新读取对话内容，请改为以 /reload-plugins --force 的形式重新运行。然后确认插件确实已安装：/plugin 会在 Installed 选项卡下显示插件，/help 会在 Custom commands 下列出其技能，任何加载失败的内容都会显示在 Errors 选项卡下，并附带失败原因。

安装时需要选择作用域，作用域决定哪些用户可以使用插件。User 作用域仅适用于您本人，并在每个项目中生效。Project 作用域会将插件写入仓库的 .claude/settings.json 中的 enabledPlugins，因此克隆该仓库的所有用户都会收到使用提示。Local 作用域仅适用于您本人，且只在当前仓库中生效。

对于脚本、Dockerfile，或无法使用交互式面板的会话，请改用 shell 形式。除非传入 --scope，否则它会安装到 User 作用域。

claude plugin install commit-commands@claude-code-plugins --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。成员信任该仓库目录后，系统会提示他们安装该 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 会检查清单、技能和 agent 的 frontmatter，以及 hooks/hooks.json，然后其他用户才能使用该插件。

Claude Code 插件的成本是多少？

机制本身是免费的。截至 2026 年 8 月，添加市场、安装插件或保持插件启用均不收费。官方市场和社区市场都是公开的 git 仓库，插件则是一个文本文件目录。

插件消耗的是 token，而 token 才是订阅用量或 API 账单实际计量的内容。具体消耗哪一种，取决于您最初采用哪种方式支付工具费用；各套餐的 Claude Code 费用同时列出了订阅层级和按 token 计费的 API 价格。这些成本通过 3 种不同方式产生，行为也各不相同。

常驻上下文成本。 插件提供的内容会进入您的上下文，并在会话的每一轮重新读取。安装前，/plugin 详情视图会显示以 token 计的 Context cost 估算值，以及 Will install 区域，其中列出即将添加的 commands、skills、agents、hooks，以及 MCP 和 LSP servers。请同时查看这两项。本地市场或自定义市场中的插件可能不提供这些数据，此时您需要手动估算。捆绑 MCP server 的插件通常最占用上下文，因为工具定义很长。不过，对于支持 MCP tool search 的模型，这些定义会延迟到需要调用工具时才加载。

调用成本。 运行插件的 skill 时，其指令会追加到对话中，因此只有使用该 skill 时，才会为 skill 正文付费。不过，正文只占较小部分，skill 要求 agent 执行的操作不一定如此：unlazy skill 的 Depth Tree 方法的大部分 token 都消耗在它强制 agent 执行的额外处理轮次上，而不是消耗在您安装的文件上。agent 则有所不同。subagent 会使用自己的 system prompt 和自己的缓存运行独立对话，开始时没有任何缓存命中。因此，工作流会生成 agents 的插件，其成本可能显著高于上下文估算值。

缓存成本。 在会话中途启用或禁用插件，可能导致下一次请求重新处理完整对话。Skills、commands、agents、hooks、LSP servers、monitors 和 themes 都不会这样做：它们添加的内容会追加到现有历史之后，因此下一次请求只需为新增内容付费，之前的内容仍从缓存读取。例外是提供 MCP server 的插件。如果其工具由 tool search 延迟加载，缓存会保留。如果工具加载到 prompt 前缀中，下一次请求就会将整个对话作为未缓存输入重新读取。这正是 /reload-plugins 发出警告并在您传入 --force 之前拒绝执行的原因。

您可以直接观察这些成本，而不必猜测。每个 API 响应都会报告 cache_read_input_tokens 和 cache_creation_input_tokens，而显示实时 token 用量的自定义 statusline会将两者同时展示出来。健康的会话通常读取的内容远多于生成的内容。如果生成量在连续多轮中都很高，说明前缀中的某些内容在每一轮发生变化。要了解哪些内容正在填充上下文窗口，请参阅如何管理 Claude Code 上下文窗口和这些 token 计数的实际含义。

有一项维护工作通常很快就能抵消成本。Installed 选项卡会将至少两周未使用的插件归入 Not used recently 标题下，并在详情视图中显示 Last used 行。这些插件仍会在每个会话中增加启动时间并占用上下文。请禁用或卸载它们。

插件以您的权限运行

Anthropic 的官方文档对此说明得很明确：插件和市场是高度信任的组件，可以使用您的用户权限在本机执行任意代码。这不是假设性风险。插件的钩子会在会话事件触发时运行 shell 命令，包括工具调用前后。启用插件后，其 bin/ 目录会加入 Bash 工具的 PATH。插件启动的 MCP 服务器本身就是由插件启动的进程。这里没有任何机制将这些操作与您的用户帐户隔离。

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

确实存在一些防护措施，了解其范围很有帮助。项目范围插件来自代码仓库，而不是由您提供，因此只有在您信任该工作区后才会加载；其 MCP 服务器仍需逐个批准；其 LSP 服务器会等待该信任确认；其后台监视器则完全不会加载。插件提供的代理不得声明钩子、MCP 服务器或权限模式。市场插件会被复制到缓存中；对于指向市场目录外部的符号链接，会跳过处理，因此插件无法引入任意主机文件。

这些措施都不能替代对所安装内容的审查。检查 Will install 列表，优先选择您可以打开并阅读源代码的插件，将团队使用的插件放在您控制的市场代码仓库中，并对您自行编写的任何内容运行 claude plugin validate。

FAQ

Claude Code 插件需要额外付费吗？

不需要。插件系统、添加 marketplace 以及安装插件都不收费。费用来自 token 使用量，计入您的套餐额度或 API 支出，与其他上下文一样。插件会在每轮对话中加入固定上下文；调用其中的 skill 或 agent 时，还会加入更多上下文。如果插件提供 MCP server，且其工具会加载到提示词前缀中，还可能强制产生一次昂贵的未缓存请求。安装前，/plugin 详细视图会显示 Context cost 估算值。

插件和 skill 有什么区别？

skill 是一个独立的指令单元。插件是一个软件包，可以包含 skill、agent、hook、MCP server、LSP server 和 monitor，并具有名称、版本以及用于安装它的 marketplace。如果某个 skill 只供您和当前项目使用，请在 .claude/ 中编写独立 skill。像 Ponytail 这样促使 agent 采用可行的最小改动 这样的单一用途 skill 就是最典型的例子：它起初只是一个包含一条规则的文件，直到团队也需要使用它。其他人需要使用该 skill，且它需要持续更新时，应将其转换为插件。插件中的 skill 使用命名空间，因此调用插件内的 skill 时应使用 /plugin-name:skill-name，而不是 /skill-name。

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

先检查安装摘要。如果摘要显示 Run /reload-plugins to activate.，说明组件尚未加载；如果重新加载时警告会重新读取对话，请使用 /reload-plugins --force 重新执行。组件已加载但没有显示内容时，打开 /plugin，然后查看 Errors 选项卡。最常见的结构错误是将 skills/、agents/ 或 hooks/ 放在 .claude-plugin/ 中，因为 Claude Code 不会在那里查找它们。请记住，插件中的 skill 使用命名空间，因此您应在 /help 的 Custom commands 选项卡中查找 /plugin-name:skill-name。最后可以执行 rm -rf ~/.claude/plugins/cache，重启后重新安装。

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

可以。使用 shell 命令 claude plugin install name@marketplace。除非传入 --scope project 或 --scope local，否则该命令会将插件安装到用户作用域。它可用于脚本、镜像和非交互环境；这些环境中可能没有 /plugin 面板。由于该命令在会话外运行，已打开的会话需要执行 /reload-plugins 后插件才会生效。

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

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