插件入口点

​

包条目

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

• extensions 和 setupEntry 是源条目，用于工作区和 git 检出开发。
• runtimeExtensions 和 runtimeSetupEntry 优先用于已安装的 包：它们让 npm 包跳过运行时 TypeScript 编译。
• runtimeExtensions 在存在时，数组长度必须与 extensions 一致 （条目按位置配对）。runtimeSetupEntry 需要 setupEntry。
• 如果声明了 runtimeExtensions/runtimeSetupEntry 资源但它缺失， 安装/发现会因打包错误而失败；OpenClaw 不会静默回退到源代码。 源代码回退（见下文）仅在完全没有声明运行时条目时适用。
• 如果已安装的包只声明了一个 TypeScript 源条目，OpenClaw 会 查找匹配的构建后 dist/*.js（或 .mjs/.cjs）同级文件并使用它； 否则会回退到 TypeScript 源文件。
• 所有条目路径都必须保留在插件包目录内。运行时 条目和推断出的构建后 JS 同级文件不会使越界的 extensions 或 setupEntry 源路径变得有效。

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "股票报价",
  description: "获取股票报价。",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API 密钥。" })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "报价",
      description: "获取报价。",
      parameters: Type.Object({
        symbol: Type.String({ description: "股票代码。" }),
      }),
      outputSchema: Type.Object(
        {
          symbol: Type.String(),
          hasKey: Type.Boolean(),
        },
        { additionalProperties: false },
      ),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema 是可选的；省略它时会使用严格的空对象 schema （生成的清单仍会包含 configSchema）。
• execute 返回普通字符串或可序列化为 JSON 的值；该辅助函数会将其包装为文本工具结果，并将 details 设置为原始的（未转换为字符串的）返回值。
• outputSchema 可选地描述原始的 details 值，供代码模式和工具搜索使用。目录调用会在执行前拒绝无效 schema，并在返回前验证最终值。
• 对于自定义工具结果，openclaw/plugin-sdk/tool-results 导出 textResult 和 jsonResult。
• 工具名称是静态的，因此 openclaw plugins build 会从声明的工具中推导出 contracts.tools，无需手动重复名称。
• 运行时加载仍保持严格：已安装的插件仍需要 openclaw.plugin.json 和 package.json 中的 openclaw.extensions。OpenClaw 绝不会执行插件代码来推断缺失的清单数据。

​

definePluginEntry

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "我的插件",
  description: "简短摘要",
  register(api) {
    api.registerProvider({/* ... */});
    api.registerTool({/* ... */});
  },
});

• id 必须与 openclaw.plugin.json 清单中的值匹配。
• 外部会话目录使用 openclaw/plugin-sdk/session-catalog，并通过 api.registerSessionCatalog(...) 注册 SessionCatalogProvider。必需的提供程序字段为 id、label、list 和 read；可选钩子包括 resolveCreateSession、continueSession、checkUpstreamActivity、archive、 openTerminal 和 startTerminalSession。核心负责 sessions.catalog.* 网关方法；提供程序返回主机、会话、转录记录和终端计划的投影，而无需注册 RPC。列表提供程序应在每个主机完成处理时调用可选的 onHost(host) 回调；返回的主机数组仍必须作为最终的兼容性快照提供。 resolveCreateSession({ agentId }) 必须在 OpenClaw 宣布支持创建会话或调用 startTerminalSession 之前，返回一个从配置派生的模型/运行时目标。 使用 api.runtime.agent.resolveSessionCatalogCreateTarget(...) 应用主机的运行时和模型允许列表策略，而不是重复实现这些逻辑。 startTerminalSession({ agentId, cwd, initialMessage?, nodeId? }) 会创建一个全新的 CLI 终端计划。返回本地计划（kind: "local"、argv 和精确的 cwd，以及可选的 env、pathEnv 和 title），或配对节点计划（kind: "node"、nodeId、command、paramsJSON 和精确的 cwd）。sessions.catalog.startTerminal RPC 要求具备 operator.admin 权限，并启用 gateway.cliAgents.enabled 和 gateway.terminal.enabled。调用方负责提供 cwd；网关要求本地目录已存在且为绝对路径，拒绝发生变化的计划 cwd 或主机，并在打开 PTY 之前执行常规的代理沙箱、节点配对、截止时间和连接所有权检查。
• kind 已弃用：应改为在 openclaw.plugin.json 清单的 kind 字段中声明一个互斥插槽（"memory" 或 "context-engine"）。运行时入口中的 kind 仅作为旧版插件的兼容性回退保留。
• configSchema 可以是一个函数，以便延迟求值。OpenClaw 会在首次访问时解析并缓存 schema，因此开销较大的 schema 构建器只会运行一次。
• nodeHostCommands 描述符可以定义 isAvailable({ config, env })。返回 false 会从无头节点的网关声明中省略该命令及其能力。OpenClaw 会根据节点本地的启动配置对其进行评估；命令处理程序在调用时仍应验证可用性。

​

defineChannelPluginEntry

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "我的通道",
  description: "简短摘要",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
  registerCapabilities(api) {
    api.registerTranscriptSourceProvider(/* ... */);
  },
});

• setRuntime 在除 "cli-metadata" 和 "tool-discovery" 之外的所有模式下运行。在此处保存运行时引用，通常通过 createPluginRuntimeStore 完成。
• registerCliMetadata 在 "cli-metadata"、"discovery" 和 "full" 模式下运行。将其作为通道自有 CLI 描述符的规范注册位置，以便根帮助保持非激活状态、发现快照包含静态命令元数据，并使常规 CLI 注册与完整插件加载保持兼容。
• registerFull 仅在 "full" 和 "tool-discovery" 模式下运行。对于 "tool-discovery"，它会替代通道注册：OpenClaw 会完全跳过 registerChannel/setRuntime，而是调用完整运行时回调，随后调用能力回调。将工具注册放在 registerFull 中，将能力提供者放在 registerCapabilities 中。
• registerCapabilities 在 "discovery"、"full" 和 "tool-discovery" 模式下运行。在此处注册不产生副作用的已声明提供者，以便只读能力发现可以找到它们，而不会启动套接字、客户端、工作线程或服务。
• 发现注册不会激活，但并非不导入：OpenClaw 可能会计算受信任的插件入口和通道插件模块，以构建快照。确保顶层导入没有副作用，并将套接字、客户端、工作线程和服务置于仅 "full" 模式的路径之后。
• 与 definePluginEntry 一样，configSchema 可以是延迟工厂；OpenClaw 会在首次访问时缓存解析后的 schema。

• 对于希望延迟加载、但又不想从根 CLI 解析树中消失的插件自有根 CLI 命令，使用 api.registerCli(..., { descriptors: [...] })。描述符名称必须匹配字母、数字、连字符和下划线，并且以字母或数字开头；OpenClaw 会拒绝其他形式，并在渲染帮助信息前移除描述中的终端控制序列。应覆盖注册器暴露的每个顶层命令根。单独使用 commands 仍会走即时加载兼容路径。
• 根描述符可以为 JSON、JSONL 或其他不会仅因 --json 而选中的机器可读 stdout 模式定义同步、纯函数式的 machineOutput({ argv, stdoutIsTTY }) 解析器。使用 openclaw/plugin-sdk/cli-argv 中的 getRootOptionAwareCommandPath 解析命令令牌。将解析器放在轻量级 CLI 元数据中，并与完整注册共享。嵌套描述符不提供此字段。
• 对于成对节点的功能命令，使用 api.registerNodeCliFeature(...)，使其归入 openclaw nodes 下（等价于 registerCli(registrar, { parentPath: ["nodes"], ... })）。
• 对于其他嵌套插件命令，添加 parentPath，并在传递给注册器的 program 对象上注册命令；OpenClaw 会在调用插件前将其解析为父命令。
• 对于通道插件，从 registerCliMetadata 注册 CLI 描述符，并让 registerFull 专注于仅运行时相关的工作。
• 如果 registerFull 还注册网关 RPC 方法，请将其置于插件专用前缀下。保留的核心管理命名空间（config.*、 exec.approvals.*、wizard.*、update.*）始终会强制使用 operator.admin。

​

defineSetupPluginEntry

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* 仅限设置的安全路由 */
      },
    });
  },
});

​

注册模式

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") {
    // 仅注册能力可见面（providers/tools），不注册频道。
    return;
  }

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

  // 仅运行时的重型注册
  api.registerService(/* ... */);
}

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

​

插件形态

​

相关内容

• SDK 概览 - 注册 API 和子路径参考
• 运行时辅助工具 - api.runtime 和 createPluginRuntimeStore
• 设置与配置 - 清单和设置入口加载
• 频道插件 - 构建 ChannelPlugin 对象
• 提供商插件 - 提供商注册和钩子函数。