跳转至

注册模式

api.registrationMode 如何报告插件的加载方式,以及每种 模式期望插件注册什么。它是 插件入口点 参考的一部分。

注册模式

api.registrationMode 会告诉你的插件它是如何加载的:

模式 触发时机 运行时 需要注册的内容
"full" 正常网关启动 实时 所有内容
"discovery" 只读能力发现 实时 通道注册、静态 CLI 描述符和非活动提供程序;跳过套接字、工作进程、客户端和服务
"tool-discovery" 作用域加载,用于列出或运行特定插件的工具 实时 仅注册能力/工具;不激活通道
"setup-only" 已禁用/未配置通道 不可用 仅通道注册
"setup-runtime" 运行时可用的设置流程 实时 通道注册,以及设置期间所需的轻量级运行时
"cli-metadata" 根帮助 / CLI 元数据捕获 不可用 仅 CLI 描述符

在 "cli-metadata" 和 "setup-only" 模式下,访问运行时能力会抛出指明插件和模式的错误。请将运行时访问延迟到 register() 之外,或在清单的 cliCommands 中声明根命令,以便在不执行插件的情况下收集 CLI 元数据。

defineChannelPluginEntry 会自动处理这种拆分。如果你直接对通道使用 definePluginEntry,请自行检查模式,并记住 "tool-discovery" 会跳过通道注册:

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  if (api.registrationMode === "tool-discovery") {
    // Register capability-only surfaces (providers/tools), no channel.
    return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

长生命周期服务可以通过其服务上下文发出小型失效或生命周期事件:

api.registerService({
  id: "index-events",
  start(ctx) {
    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });
  },
});

OpenClaw 将其命名空间化为 plugin.<plugin-id>.changed。事件名称为一个小写段,负载必须是有限大小的 JSON,且作用域必须为 operator.read、operator.write 或 operator.admin。发射器仅存在于服务生命周期内,并在停止或启动失败后被撤销。优先使用版本或失效负载,而不是完整记录,以便授权客户端通过插件的作用域 Gateway 方法重新读取规范状态。

发现模式会构建一个非激活的注册表快照。它仍可能 评估插件入口和通道插件对象,以便 OpenClaw 可以 注册通道能力和静态 CLI 描述符。请将发现中的模块 评估视为可信但轻量级:顶层不要有网络客户端、 子进程、监听器、数据库连接、后台工作进程、 凭据读取或其他实时运行时副作用。

将 "setup-runtime" 视为一个窗口,在此窗口中,仅用于设置的启动界面必须 存在,而无需重新进入完整的捆绑通道运行时。适合的场景包括 通道注册、设置安全的 HTTP 路由、设置安全的网关方法, 以及委托的设置辅助函数。重量级后台服务、CLI 注册器和 提供程序/客户端 SDK 引导仍应属于 "full"。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw