注册模式

api.registrationMode 如何报告插件的加载方式，以及每种模式期望插件注册哪些内容。属于插件入口点参考的一部分。

注册模式¶

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

在 "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 注册器和 provider/client SDK 引导仍属于 "full"。