它到底是什么

--plugin-dir 是一个**会话级（session-scoped）**的 CLI 启动 flag，用于从本地目录或 .zip 压缩包直接加载一个或多个插件，无需先安装到 marketplace。取值为路径（目录路径或 .zip 文件路径）。从 Claude Code v2.1.265 起，还支持指向一个"插件的文件夹"——即该路径下每个含有 .claude-plugin/plugin.json 清单的子目录，都会被当作独立插件分别加载。默认不传则不加载任何额外插件。

用法

claude --plugin-dir ./my-plugin

加载多个插件，重复传 flag:

claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b.zip

加载一个插件文件夹（要求 v2.1.265 及以上）：

claude --plugin-dir ./plugins-folder

等价的环境变量是 CLAUDE_CODE_PLUGIN_DIRS（要求 v2.1.280 及以上），用于在无法直接传 flag 的场景里列出多个插件的绝对路径；其中每条路径都会按 --plugin-dir 路径的方式加载，并且与 --plugin-dir 传入的插件是叠加关系，不是互相替代。project/local 级别的 settings 不能设置这个环境变量。

与其他 flag 的组合 / 互斥

• --plugin-url：用于从 URL 拉取 .zip 压缩包（例如 CI 构建产物），同样只对当前会话生效。
• 与已安装的 marketplace 插件同名时，--plugin-dir 加载的本地版本在本次会话中优先生效，便于在不卸载已装插件的情况下测试改动。
• 例外：如果该插件被 managed settings 强制启用或强制禁用，--plugin-dir 无法覆盖这个强制状态。

在 settings.json / env 的等价配置

运行约束 / 限制

经典使用场景

• 插件开发/调试：官方 quickstart 教程中，创建插件后就是用 claude --plugin-dir ./my-first-plugin 直接测试，不需要先发布或安装。
• 用 .zip 验证打包产物：确认压缩包本身能被正确加载，而不仅仅是解压后的目录结构可用。
• 同时加载多个协作插件：测试一个插件与它依赖的另一个插件组合在一起的效果。
• 配合 --plugin-url 做一次性验证：从 URL（例如 CI 构建产出）拉取 .zip 插件包，在会话中临时加载测试。

常见坑

• 改了插件文件却没生效：--plugin-dir 只在启动时读取一次，后续对文件的修改必须手动执行 /reload-plugins 才会应用；在没有交互式终端的会话里，插件 MCP server 的改动甚至要等到下一次会话才生效。
• 以为能越过团队强制策略：如果组织通过 managed settings 强制启用/禁用了某个同名插件，--plugin-dir 加载的本地版本不会生效，仍然遵循 managed settings 的结果。
• flag 放在子命令之后曾被静默忽略：根据 GitHub issue #73991，在 v2.1.200 之前，把 --plugin-dir 放在 agents 子命令之后会导致插件的 agents/skills 完全没被加载，且没有任何报错提示；v2.1.200 起该 flag 不论放在 agents 子命令前后都会被正确识别。

来源

• CLI reference - Claude Docs
• Create plugins - Claude Docs
• Issue #73991: claude agents --plugin-dir <dir> is documented but never warns about flag placement after agents