OpenClaw 插件系统:如何打造全能私人助理 –OpenClaw源码深度系列第2期

export typeChannelPlugin<ResolvedAccount = any>={  id: ChannelId;    meta: ChannelMeta;    capabilities: ChannelCapabilities;    onboarding?: ChannelOnboardingAdapter;// 引导用户配置接入    config: ChannelConfigAdapter;// 账号/凭证管理    pairing?: ChannelPairingAdapter;// 用户 ID 映射与白名单    outbound?: ChannelOutboundAdapter;// 发送消息    gateway?: ChannelGatewayAdapter;// 入站监听（startAccount）    threading?: ChannelThreadingAdapter;// 线程上下文    streaming?: ChannelStreamingAdapter;// 流式合并策略    status?: ChannelStatusAdapter;// 健康检查    actions?: ChannelMessageActionAdapter;// 编辑/撤回/反应等    directory?: ChannelDirectoryAdapter;// 联系人/群组目录  // ... 还有十几个可选适配器};

register(api){  api.registerService(voiceCallService);// 后台常驻服务    api.registerTool(voiceCallTool);// Agent 可调用工具    api.registerGatewayMethod("voicecall.initiate", handler);// 外部 RPC 方法    api.registerCli(registerVoiceCallCli);// CLI 命令}

const createApi =(record, params): OpenClawPluginApi =>({  registerTool:(tool, opts)=>registerTool(record, tool, opts),  registerHook:(events, handler)=>registerHook(record, events, handler,...),  registerHttpRoute:(params)=>registerHttpRoute(record, params),  registerChannel:(registration)=>registerChannel(record, registration),  registerGatewayMethod:(method, handler)=>registerGatewayMethod(record, method, handler),  registerCli:(registrar, opts)=>registerCli(record, registrar, opts),  registerService:(service)=>registerService(record, service),  registerCommand:(command)=>registerCommand(record, command),  registerProvider:(provider)=>registerProvider(record, provider),  on:(hookName, handler)=>registerTypedHook(record, hookName, handler, opts),});

exporttypePluginRegistry={  tools:           PluginToolRegistration[];    hooks:           PluginHookRegistration[];    channels:        PluginChannelRegistration[];    services:        PluginServiceRegistration[];    httpRoutes:      PluginHttpRouteRegistration[];    gatewayHandlers: GatewayRequestHandlers;    cliRegistrars:   PluginCliRegistration[];    commands:        PluginCommandRegistration[];    diagnostics:     PluginDiagnostic[];};

// 1. config 指定路径（最高优先级，适合临时覆盖/本地开发）for(const extraPath of params.extraPaths ??[]){  discoverFromPath({ rawPath: extraPath, origin:"config",...});}// 2. 工作区插件（适合团队协作/版本控制）discoverInDirectory({ dir: path.join(workspaceRoot,".openclaw","extensions"), origin:"workspace",...});// 3. 全局插件（用户个人安装）discoverInDirectory({ dir: path.join(resolveConfigDir(),"extensions"), origin:"global",...});// 4. 内置插件（最低优先级）discoverInDirectory({ dir: bundledDir, origin:"bundled",...});

// 1. 全局总开关if(!config.enabled)return{ enabled:false, reason:"plugins disabled"};// 2. 黑名单拦截if(config.deny.includes(id))return{ enabled:false, reason:"blocked by denylist"};// 3. 白名单过滤（设置了白名单则只加载名单内的）if(config.allow.length >0&&!config.allow.includes(id))return{ enabled:false, reason:"not in allowlist"};// 4. Memory slot 优先匹配if(config.slots.memory === id)return{ enabled:true};// 5. 单插件级别开关const entry = config.entries[id];if(entry?.enabled ===true)return{ enabled:true};if(entry?.enabled ===false)return{ enabled:false, reason:"disabled in config"};// 6. bundled 插件默认禁用（除非在默认启用白名单里）if(origin ==="bundled"&&!BUNDLED_ENABLED_BY_DEFAULT.has(id))return{ enabled:false, reason:"bundled (disabled by default)"};// 7. 其他情况：默认启用return{ enabled:true};

export functionresolveMemorySlotDecision({ id, kind, slot, selectedId }){  if(kind !=="memory")return{ enabled:true};  if(slot ===null)return{ enabled:false, reason:"memory slot disabled"};  if(typeof slot ==="string")return slot === id  ?{ enabled:true, selected:true}  :{ enabled:false, reason:`memory slot set to "${slot}"`};// 无显式 slot：先到先得  if(selectedId && selectedId !== id)return{ enabled:false, reason:`memory slot already filled by "${selectedId}"`};  return{ enabled:true, selected:true};}

const jiti =createJiti(import.meta.url,{  interopDefault:true,// 自动展开 { default: ... } 包装，兼容 CJS/ESM 混用    extensions:[".ts",".tsx",".mts",".cts",".js",".mjs",".cjs",".json"],  ...(pluginSdkAlias  ?{ alias:{"openclaw/plugin-sdk": pluginSdkAlias }}:{}),});

const preferDist = process.env.VITEST|| process.env.NODE_ENV==="test"|| isDistRuntime;for(let i =0; i <6; i++){  const srcCandidate  = path.join(cursor,"src","plugin-sdk","index.ts");  const distCandidate = path.join(cursor,"dist","plugin-sdk","index.js");  const ordered = preferDist ?[distCandidate, srcCandidate]:[srcCandidate, distCandidate];  for(const candidate of ordered){    if(fs.existsSync(candidate))return candidate;  }      cursor = path.dirname(cursor);}

function resolvePluginModuleExport(moduleExport){  const resolved = moduleExport?.default ?? moduleExport;  // 裸函数 → 直接视为 register  if(typeof resolved ==="function")return{ register: resolved };  // 对象 → 取 register，兼容旧字段名 activate  if(resolved &&typeof resolved ==="object"){    const register = resolved.register ?? resolved.activate;    return{ definition: resolved, register };  }  return{};}

// loader 里的检查逻辑const id =typeof raw.id ==="string"? raw.id.trim():"";if(!id)return{ ok:false, error:"plugin manifest requires id"};const configSchema =isRecord(raw.configSchema) ? raw.configSchema :null;if(!configSchema)return{ ok:false, error:"plugin manifest requires configSchema"};

const result =register(api);if(result &&typeof result.then ==="function"){  registry.diagnostics.push({    level:"warn",        pluginId: record.id,        message:"plugin register returned a promise; async registration is ignored",  });}

{  "name":"@you/daily-digest",  "version":"0.1.0",  "openclaw":{    "extensions":["index.ts"]  },  "dependencies":{}}

{  "id":"daily-digest",  "configSchema":{    "type":"object",    "required":["channelId","accountId","target"],    "properties":{      "channelId":{        "type":"string",        "description":"目标渠道 ID（如 slack / telegram）"      },      "accountId":{        "type":"string",        "description":"用于发送的账号 ID"      },      "target":{        "type":"string",        "description":"发送目标（频道/用户 ID）"      },      "cronHour":{        "type":"number",        "default":9,        "description":"触发小时（本地时区）"      }    },    "additionalProperties":false  }}

import type{ OpenClawPluginApi } from "openclaw/plugin-sdk";export default function register(api: OpenClawPluginApi){  const cfg = api.pluginConfig as{      channelId:string;          accountId:string;          target:string;          cronHour?:number;};  // 后台定时服务（Push 场景的正确归宿）  api.registerService({      id:"daily-digest.scheduler",      async start ({ abortSignal }){        while(!abortSignal.aborted){          const now =newDate();          const triggerHour = cfg.cronHour ??9;          const msUntilTrigger =getMsUntilHour(now, triggerHour);          await sleep(msUntilTrigger, abortSignal);          if(abortSignal.aborted) break;          // 拉取数据（可对接 MCP 工具 / 内部 API / Gmail API）          const[agenda, emails]=awaitPromise.all([fetchTodayAgenda(),fetchImportantEmails(),]);          const summary =formatBrief(agenda, emails);          // 用 runtime 的渠道发送能力投递消息          await api.runtime.channel.reply.dispatchReplyFromConfig({              channelId: cfg.channelId,                        accountId: cfg.accountId,                        target: cfg.target,                        text: summary,           });        }      },});   // 可选：让 Agent 也能主动触发（Pull 场景）     api.registerTool({      name:"daily_digest.send_now",          description:"立即生成并发送今日摘要",          inputSchema:{ type:"object", properties:{},       additionalProperties:false},      handler:async()=>{        const[agenda, emails]= await Promise.all([fetchTodayAgenda(),fetchImportantEmails()]);        return{ summary:formatBrief(agenda, emails)};      },    });      api.logger.info(`daily-digest registered (trigger: ${cfg.cronHour ??9}:00)`);}