插件加载失败需按五步排查：一查路径与package.json规范；二配.clawdbotrc兼容模式；三白名单注入原生模块；四调试init生命周期并加超时保护；五优先使用@clawdbot/官方认证插件。
如果您已安装Clawdbot并尝试启用某项功能插件，但插件状态始终显示“loading failed”或控制台报错plugin not found、require is not defined、Cannot find module等提示，则很可能是插件路径未注册、依赖缺失或运行时上下文不兼容所致。以下是解决此问题的步骤：
一、验证插件文件完整性与加载路径
Clawdbot仅从预设目录自动扫描并加载插件，若插件文件放置位置错误或命名不规范，将被完全忽略。该机制不支持任意路径动态require，必须严格遵循约定路径结构。
1、打开终端，执行命令确认Clawdbot插件根目录：
clawdbot config get plugins.dir
2、进入该路径，检查是否存在目标插件子目录（如my-custom-action），且其内包含有效的package.json文件
3、确认package.json中必须包含以下两项字段：
"main": "index.js"
"clawdbot": {"type": "action" 或 "trigger" 或 "adapter"}
4、检查index.js是否导出默认函数（而非ESM default export语法），正确写法为：
module.exports = function(pluginContext) { ... }必须使用CommonJS module.exports，禁用import/export语法
二、修复Node.js运行时兼容性问题
Clawdbot CLI内嵌Node.js运行时（v22.x），但部分插件在开发时基于v18或v20编写，存在API弃用、全局对象缺失（如process.env.NODE_OPTIONS被强制清空）、或ES版本不匹配等问题，导致模块解析失败。
1、在插件根目录下创建.clawdbotrc文件
2、写入以下内容以显式声明兼容模式：
{
"nodeVersion": "22",
"esmSupport": false,
"disableStrictMode": true
}
3、重启Clawdbot服务：
clawdbot restart --force
4、查看插件加载日志：
clawdbot logs --plugin my-custom-action --follow
关键提示：所有插件代码必须在无Babel/TS编译环境下直接运行，禁止引用node_modules中未被Clawdbot白名单允许的包（如chalk、axios等）
三、手动注册缺失的原生依赖模块
部分插件需调用底层系统能力（如fs-extra、child_process、sqlite3），但Clawdbot默认沙箱禁用了非安全模块的动态加载。若日志中出现Error: Cannot find module 'fs-extra'或Module not found: child_process，则需主动注入白名单。
1、编辑Clawdbot主配置文件：
vim ~/.clawdbot/clawdbot.json
2、在顶层添加或修改plugins字段：
"plugins": {
"allowedModules": ["fs", "path", "os", "child_process", "crypto"]
}
3、保存后执行重载命令：
clawdbot config reload
4、重新安装插件依赖（仅限纯JS库，不支持二进制原生模块）：
cd ~/.clawdbot/plugins/my-custom-action && npm install fs-extra --no-save
注意：sqlite3、canvas、sharp等含C++扩展的模块无法在Clawdbot沙箱中加载，必须替换为纯JS替代方案（如better-sqlite3不可用，改用@libsql/client）
四、调试插件初始化生命周期异常
插件加载失败常发生在init()钩子执行阶段，例如异步资源预热超时、第三方API密钥未配置、或同步阻塞操作触发Node.js事件循环冻结。此时插件进程被静默终止，无堆栈输出。
1、在插件index.js顶部插入调试标记：
console.debug('[PLUGIN-INIT] Starting initialization...');
2、确保所有异步操作均包裹在try/catch中，并显式reject错误：
try { await fetch('https://api.example.com/health'); } catch (e) { throw new Error(`Health check failed: ${e.message}`); }
3、设置超时保护（避免无限等待）：
const controller = new AbortController();
setTimeout(() => controller.abort(), 8000);
await fetch(url, { signal: controller.signal });
4、启动带调试模式的Clawdbot：
clawdbot run --debug-plugins
必须确保插件init()函数返回Promise，且不抛出未捕获异常；任何未await的异步操作都将导致加载流程跳过后续步骤
五、替换为Clawdbot官方认证插件源
非官方维护的插件可能存在API签名变更、上下文对象字段废弃（如旧版pluginContext.app已更名为pluginContext.runtime）、或使用已被移除的内部方法（如context.invokeLegacyHandler）。此类插件即使能短暂加载，也会在后续调用中崩溃。
1、卸载当前插件：
clawdbot plugin remove my-custom-action
2、列出官方插件仓库中可用的适配版本：
clawdbot plugin search --official --filter qwen
3、安装经v1.8.2+运行时验证的版本：
clawdbot plugin add @clawdbot/action-qwen3 --version 1.2.0
4、验证插件元信息是否完整：
clawdbot plugin info @clawdbot/action-qwen3
官方插件包名必须以@clawdbot/开头，且版本号≥1.2.0才保证兼容Qwen3:32B模型调用链路
