如果你最近在Windows上折腾Claude Code，十有八九会撞见类似下面这行启动日志：

harness failed to load plugins web boot: 2 entries did not activate

我第一次看到这行字的时候，以为是下载的插件包坏了，直接把整个目录删掉重装了一遍，结果报错原封不动。后来花了一晚上把Claude Code的插件加载机制翻了个底朝天，才发现问题不在插件本身，而在我对"插件该长什么样、该放在哪、加载器怎么判断它能不能用"这件事的理解上。

这篇内容适合刚装好Claude Code、正被failed to load、did not activate这类问题折磨的人；也适合那些想从零写一个官方风格插件（plugin/skill），或者想用第三方兼容API把Claude Code跑起来的人。我会从插件加载器的工作原理讲起，再给出一条可以照着做的排查链路，最后聊聊我自己写Skills和接入兼容API时踩出来的经验。

1. 从"harness failed to load plugins"说起：插件加载器到底在加载什么

1.1 harness、plugin、entry：先记住这三层概念

报错里的harness不是一个插件名字，而是Claude Code的运行时外壳。它负责启动整个命令行工作区，扫描所有扩展点，把插件注册进可用列表。web boot表示这是在web/桌面启动阶段做的第一次扫描，它发生在一切UI起来之前，所以一旦这个阶段失败，你往往只能看到一行日志，没有任何交互式错误提示。

plugin指的是一个目录，也就是一个"打包单位"。在Claude Code的插件体系里，官方插件主要围绕"skills"来组织，一个plugin里通常包含多个skill目录，每个skill目录又对应一个独立的entry。如果你见过claude-plugins-official这类仓库名，它其实就是一套官方维护的插件集合，结构上完全符合下面要说的规范。

entry是这几个概念里最容易被忽略、却又最关键的一个。加载器在插件目录里扫描到的每个技能目录，都会成为一个entry，然后逐个去校验它是否满足激活条件。满足的记作activated，不满足的记作did not activate。所以那行报错的直接意思是：在web boot阶段加载器一共扫到了若干个entry，其中2个没有通过校验，被放弃了。

搞明白这层关系之后，你就不会再对着日志瞎猜了。

1.2 官方插件目录里躺着哪些文件

我一开始犯的错，是顺手把整个GitHub仓库clone进了插件目录，以为只要文件夹存在就行。实际上加载器扫描的是结构化目录，一个符合规范的插件大致长这样：

my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── review.py │ └── summarizer/ │ ├── SKILL.md │ └── reference/ │ └── template.md └── README.md

.claude-plugin/plugin.json是插件的身份证，里面至少有name、version、description这几个字段，加载器根据它来识别插件身份。skills/下的每个子目录放一份SKILL.md，这份markdown文件的开头是YAML frontmatter，里面写着name和description，正文就是告诉模型"这个技能什么时候用、怎么用、按什么步骤执行"。

我见过很多人下载插件后只复制了SKILL.md，丢掉了.claude-plugin，或者反过来——这两种情况都会导致entry被扫到，但校验不过，最终被计入did not activate。所以拿到任何插件，先看它是不是一个完整的目录结构，别只拖一个文件出来用。

1.3 加载器如何判定一个插件"激活成功"

根据我实际测试和翻loader日志的经验，激活判断基本是一个三关流程。

第一关是路径关：插件必须在受支持的插件目录内，且每个entry必须是一个独立目录，目录里必须存在SKILL.md。第二关是元数据关：SKILL.md的frontmatter必须是合法YAML，name字段存在且唯一，description字段不能为空。第三关是内容关：正文不能是空文件，如果frontmatter里引用了辅助脚本或附件路径，这些文件必须在插件目录内且真实存在。

任何一关不过，加载器都不会中途停下来报错，而是默默跳过这个entry，继续往下扫其他插件。这就是为什么你会看到"1 entry did not activate"甚至"2 entries did not activate"这种半好半坏的日志——它放弃了不合格的entries，但其余插件照常工作。

这种设计很务实，坏处是错误信息藏得很深。理解这层机制之后，后面的排查就完全有方向了。

2. 先把地基打好：Claude Code的环境准备与最小Skills跑通

2.1 Windows环境里最先拦路的三块砖

大量和插件相关的求助帖，其实连Claude Code本体都没跑起来，问题发生在插件之前。第一块砖是Windows提示"workspace requires the virtual machine platform"。Claude Code在Windows上依赖WSL2或者Windows的虚拟机监控程序平台，解决办法不是降级也不是换工具，而是到"启用或关闭Windows功能"里勾选"适用于Linux的Windows子系统"和"虚拟机平台"，重启后装WSL2，然后在WSL2环境里安装Claude Code。这一步折腾完，后面会少掉一半的诡异问题。

第二块砖是执行claude命令时报"无法将claude项识别为cmdlet、函数、脚本文件或可运行程序的名称"。绝大多数情况是npm全局bin目录没进PATH。安装后用npm prefix -g看一下全局包的安装根目录，把对应的bin路径加到用户环境变量PATH里，然后重开一个终端就好了。如果还不行，看一下安装时有没有报权限错误，很多Windows上的权限问题Windows Installer是帮不了你的，手动装一遍反而干净。

第三块砖是Windows记事本默认的UTF-8 with BOM，这个坑我放在第3章细讲。它是"插件表面看起来完全没问题，但加载器就是不认"的头号元凶。

2.2 手写一个最小Skill，让加载器跑通

环境就绪之后，不要急着塞插件，先手动放一个最小Skill，验证加载器是健康的。这是我自己一直保留的"对照组"习惯。

mkdir -p ~/.claude/plugins/my-first-plugin/skills/hello-skill vim ~/.claude/plugins/my-first-plugin/skills/hello-skill/SKILL.md

SKILL.md里只要三行元数据和一句正文：

--- name: hello-skill description: 当用户需要演示或测试插件加载时使用。回答"插件是否正常"时简述此文件的位置。 --- 这是一个用于验证插件加载的最小技能。正常运行时会出现在可调用技能列表中。

启动Claude Code后，如果日志里出现类似loaded plugin my-first-plugin、activated skill hello-skill的字样，说明加载链路已经通了。之后再复制其他复杂插件进来，出问题时就能第一时间判断是插件自身的问题，而不是环境问题。如果你主要用VS Code，安装完CLI后装官方扩展即可，插件扫描和报错路径跟命令行是一致的，排查思路完全通用。

2.3 插件放在哪里：全局目录、项目目录与CLAUDE_CONFIG_DIR

插件放错位置，加载器当然扫不到。全局来说，配置根目录默认是~/.claude（Windows下通常是C:\Users\用户名\.claude），插件放在~/.claude/plugins/下面。项目级插件则放在项目根目录的.claude/plugins/下，加载器会同时扫描两个位置，项目级优先级更高。

还有一个环境变量CLAUDE_CONFIG_DIR，它可以整体改变配置根目录的位置。很多配置工具或安装方式会把CLAUDE_CONFIG_DIR指到AppData或者config目录下的某个隐藏位置，这时候你往~/.claude里放插件就是白放。

所以排查的第一步永远是先确认配置根目录在哪：

echo $CLAUDE_CONFIG_DIR

这个命令输出的路径才是插件真正的"家"。

3. "2 entries did not activate"排查链路：从现象到根因的完整流程

3.1 先复现现场，再决定要不要动配置

拿到报错的第一件事不是改文件，而是确认它是稳定复现的，还是一闪而过的。重开几次Claude Code，如果每次都出现相同数量的N entries did not activate，说明有固定插件坏了；如果偶发，优先怀疑网络、目录同步或缓存。

然后做隔离测试。把所有第三方插件临时挪出插件目录，只保留自己写的最小Skill，启动确认加载器彻底没报错。这一步的意义在于把"环境问题"和"插件问题"分开：环境有问题，再好的插件也加载不出来；环境没问题，报错就是某个具体插件引起的，逐个加回来就能找到真凶。

我在实际排错中经常遇到的情况是：用户只看到了2 entries did not activate，但完全不确定是哪个插件坏了。隔离测试一做，两个坏入口和两个插件目录立刻对应上，排查范围从"整个插件体系"缩小到"某个目录里的某个文件"。

3.2 检查编码、嵌套与元数据：三个高频原因

当你锁定到某个插件目录后，最高频的三类原因，我按出现概率排一下：

第一是编码问题，Windows上尤其致命。用记事本另存过的SKILL.md会带上BOM头，YAML解析器不认识这个字节序标记，frontmatter直接解析失败。同样的问题也会出现在plugin.json上。检查方式是用VS Code打开文件，看右下角编码是不是UTF-8（不带BOM），如果不是，另存为UTF-8无BOM格式即可。

第二是目录嵌套过深。GitHub上很多插件仓库根目录带着README和LICENSE，你clone下来整个目录一丢，实际有效的skills目录被套在了repo名/xxx/skills这种深层路径里。加载器扫描不到SKILL.md，自然判定为没激活。修复办法是把仓库里的插件内容一层层扒出来，确保插件目录和.claude-plugin、skills平级，再把多余的外层目录删掉。

第三是元数据字段写错。SKILL.md的frontmatter里name字段不能带空格，最好用短横线；description过短（比如只有"a useful skill"这种废话）也会在部分版本里直接不激活。

我把排查思路整理成了一张表，方便你对照：

3.3 用Debug日志拿到真正的失败原因

前三关都过了还是没激活，说明有隐藏条件。这时候要让加载器把失败原因吐出来。由于不同版本的调试环境变量不完全一样，我的通用做法是查一下跟plugin加载相关的日志开关。比如尝试在启动时设置一个插件加载器的日志环境变量：

CLAUDE_CODE_PLUGIN_LOADER_LOG=1 claude

在Windows PowerShell下则先设置环境变量再启动：

$env:CLAUDE_CODE_PLUGIN_LOADER_LOG="1"; claude

开启调试输出后，加载器通常会给每个entry一个更明确的失败理由，类似"frontmatter missing required field description"或者"path not found: scripts/foo.py"。看到这一行，问题基本就水落石出了。调试完成后务必要把变量取消掉，否则日志会一直非常啰嗦，影响正常使用。

有一个容易被忽略的细节：调试日志里打印的路径和你以为的路径经常不一样。我遇到过读者发日志给我，里面写的是C:\Users\administrator\appdata\local\...，但他一直以为配置在~/.claude下面。这时候要追一下CLAUDE_CONFIG_DIR环境变量的值，多半是某个工具把它改了。

3.4 修复完成不等于结束，验证一个闭环

改完文件后不要立刻觉得已经搞定。我每次都会做一次完整的验证闭环：

1. 确认调试日志里这个entry不再出现在did not activate列表里。
2. 确认它出现在activated列表里。
3. 在实际对话中触发一次该技能，确认模型能通过description主动命中。

前两步只代表加载器接受了这个skill，第三步才代表它真正可用。很多修完插件的人，最后发现加载日志是绿的，但对话里怎么都调不出这个技能，问题往往就出在description写得含糊，模型压根不知道什么时候该用它。从这个角度看，排错到最后拼的其实是元数据质量，而不只是加载器本身。

4. 不满足于"能加载"：自定义Skill与兼容API接入

4.1 写Skill的黄金法则：让模型在需要时想起它

自己造Skill的流程门槛不高，真正难的是"让模型在合适的场景主动调用它"。注意，模型不是根据文件名来选技能的，而是把你技能列表里的description和当前用户问题做语义匹配，所以description就是第一生产力。

我写过一个做前端代码审查的skill，一开始description写的是"代码审查工具"，结果模型很少主动调用。后来改成下面这种写法，命中率明显上来了：

--- name: frontend-review description: 对React/TypeScript前端代码做静态审查，检查组件拆分是否合理、副作用是否收敛、命名是否一致。适合在用户要求"review代码""看看这段React写得怎么样"或提交PR之前调用。 --- 执行步骤： 1. 先定位当前工作区内的前端源码文件。 2. 按组件拆分、逻辑副作用、命名一致性三个维度逐项检查。 3. 输出分级问题列表，优先级从高到低排列。

在description里塞入触发短语（"review代码"、"看看这段React写得怎么样"），并写明使用边界（只处理React/TypeScript场景），模型的选择就会稳定很多。正文部分则要把执行步骤写清楚，哪怕简单，也比一段空泛的"你来负责审查代码"强得多。

4.2 Provider配置与base_url：400错误的真正来源

插件体系之外，另一个被问爆的问题是接入第三方兼容API。你想用DeepSeek或者其他兼容服务跑Claude Code，本质上不是改插件，而是配置Provider。最常见的做法是通过环境变量把API请求转向兼容端点，设置ANTHROPIC_BASE_URL指向你用的服务地址，ANTHROPIC_AUTH_TOKEN填API Key，然后再单独指定模型名。

如果你是通过配置文件里的provider字段来指定，最常见的报错就是：

api error: 400 配置错误: claude provider 缺少 base_url 配置

这个错误的实质是：Provider名虽然是claude，但你的接入并不是官方默认的请求地址，必须通过base_url显式告诉客户端往哪儿发。很多配置切换工具在切到claude这一档时，只填了模型名和Key，没有补base_url，于是请求就被发到了默认地址，服务端自然回一个400。

修复方式很简单，在对应配置的provider节点补上base_url，或者干脆改用环境变量注入方式，二选一。关键是理解：provider: claude只是一个标识，真正决定流量去向的是base_url和token这两个字段。

4.3 一套配置多端切换的思路

我现在不太用全局改环境变量的方式来切Provider，而是把不同Provider的配置拆成独立文件，放在~/.claude下面，平时用配置切换工具管理。这样做的好处是插件目录、skills、settings都能各自保持独立，不会出现"切到DeepSeek之后插件全没了"之类的问题。

像CCSwitch这类配置工具，核心思路也就是把上面的环境变量和配置文件做成可切换的预设，你每次切换时它帮你改ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN而已。理解了这套底层逻辑，不管用什么工具都不会再被网上的教程绕晕。

5. 我实际用下来的踩坑清单与调试心得

5.1 两个最有价值的调试习惯

第一个习惯：任何时候怀疑插件加载问题，先建一个最小可用skill作为对照组。这个习惯帮我省了无数时间。别人发我插件报错，我先把对方的插件目录全挪走，放上自己的hello-skill，如果它正常激活，问题就出在那批插件上；如果它也不激活，那是环境或目录配置的问题。对照组在手，排查就不再是玄学。

第二个习惯：记住YAML frontmatter里不要出现Tab缩进、不要用中文标点、不要留多余空行。这几个老生常谈的规则能解决80%的did not activate。我本地还留了一个小脚本，用来批量检查插件目录里的SKILL.md和plugin.json是否存在BOM、frontmatter能否被解析、name字段是否符合命名规则。第一次写有点费时间，但之后每次排查都能用。

5.2 插件数量的选择与维护节奏

插件不是越多越好。每多一个skill，模型在对话时就要多处理一段候选描述，技能越多，选择反而越不稳定。加载器扫描的entry也更多，总会有插件因为各种原因没激活，给日志和排查增加噪音。

我现在只保留三类：日常开发用的代码审查、文档生成、以及跟当前项目绑定的专用技能。其余的一律不进全局插件目录，有需要放到项目级目录里按需加载。GitHub上有源源不断的新插件，合理的做法是"想清楚再装、装完立刻验证"，而不是一次拉十个进来，让日志满屏飘红。

最后分享一个我自己的习惯：每次升级Claude Code之后，我会主动清空一次插件目录里的缓存并重新验证全部插件。插件加载这件事，环境和版本因素往往大于插件本身的代码质量。理解了这一点，你再看到harness failed to load plugins这类报错时，就会把它当作一道有明确步骤的题来解，而不是纯随机事件了。