跳转至

CLI 与发现

本地 Gateway 发现、插件自有 CLI 命令和本地 AI CLI 后端的注册器。属于 Plugin SDK 概述 的一部分。

Gateway 发现注册

api.registerGatewayDiscoveryService(...) 允许插件在本地发现传输(如 mDNS/Bonjour)上通告活动的 Gateway。当启用本地发现时,OpenClaw 会在 Gateway 启动期间调用该服务,传递当前 Gateway 端口和非机密 TXT 提示数据,并在 Gateway 关闭期间调用返回的 stop 处理器。

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    // startMyAdvertiser is your plugin's own mDNS/Bonjour helper, not an SDK export.
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

Gateway 发现插件不得将通告的 TXT 值视为机密或认证信息。发现仅作为路由提示;Gateway 认证和 TLS 固定仍然掌握信任。

CLI 注册元数据

可执行 CLI 拥有为帮助和命令元数据获取的未缓存插件注册表,以及通过 openclaw/plugin-sdk/provider-catalog-runtime 在注册、操作或清理期间借用的提供者回调。它会在调用的实际工作完成后释放这些资源,即使清理警告已经报告超时。强制进程退出仍可能中断异步释放。调用方拥有的程序和 Gateway 启动不会仅因调用 CLI 辅助函数而成为可执行 CLI 的所有者;请参阅保留的 SDK 契约。

api.registerCli(registrar, opts?) 接受两种命令元数据:

  • commands:注册器拥有的显式命令名称
  • descriptors:用于 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符
  • parentPath:嵌套命令组的可选父命令路径,例如 ["nodes"]

对于配对节点功能,建议使用 api.registerNodeCliFeature(registrar, opts?)。它是 api.registerCli(..., { parentPath: ["nodes"] }) 的轻量包装器,使 openclaw nodes canvas 等命令成为显式的插件自有节点功能。

当插件自有的节点命令需要相同的 Gateway 标志、调用封装、终端呈现和授权提示时,请复用核心节点 CLI 所有者:

import {
  buildNodeInvokeParams,
  getNodesTheme,
  nodesCallOpts,
  runNodesCommand,
} from "openclaw/plugin-sdk/node-cli-runtime";

如果你希望插件命令在常规根 CLI 路径中保持延迟加载,请提供覆盖该注册器暴露的每个顶级命令根的 descriptors。

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

当命令为 JSON、JSONL 或其他机器可读格式保留 stdout 而不只是依赖字面 --json 标志时,根描述符还可以声明 machineOutput({ argv, stdoutIsTTY })。OpenClaw 会在插件激活之前评估此解析器,以便启动诊断可以路由到 stderr。解析器必须是同步、纯且低依赖的:只检查提供的原始 argv 和 stdout TTY 状态。在轻量级 CLI 元数据和完整注册中复用相同的解析器,使发现和执行保持一致。当解析器需要命令路径令牌时,从 openclaw/plugin-sdk/cli-argv 使用 getRootOptionAwareCommandPath;它接受命令根之前或之后的受支持根选项。machineOutput 是根元数据;嵌套描述符不能使用它,因为它们的所属根在它们可见之前必须已经激活。

嵌套命令将解析后的父命令作为 program 接收:

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Present hosted widgets on a paired Mac",
        hasSubcommands: true,
      },
    ],
  },
);

仅在你不需要延迟根 CLI 注册时才单独使用 commands。该急切兼容路径仍然受支持,但它不会为解析时延迟加载安装描述符支持的占位符。

注册器接收原生 Commander 对象。在注册器内部注册的回调会保留插件实例,供后续操作、钩子、解析、帮助和事件使用。使用 program.addCommand 添加的预配置命令树也会将其回调转移到添加者实例。注册前已附加到宿主的命令仍然归调用方所有;命令身份以及以函数为值的参数或选项数据不会改变。重新加载或禁用会拒绝新的回调调用,同时已接受的异步操作会继续完成。

CLI 后端注册

api.registerCliBackend(...) 允许插件拥有本地 AI CLI 后端(如 claude-cli 或 my-cli)的默认配置。

  • 后端 id 成为模型引用(如 my-cli/gpt-5)中的提供者前缀。
  • 后端 config 是权威的命令适配器:argv、环境、解析器、会话、镜像和可靠性行为都存在于插件代码中。
  • 用户通过模型引用或模型作用域的 agentRuntime.id 选择后端;openclaw.json 不会重写适配器。
  • 当注册的静态字段需要运行时感知的规范化处理时,使用 normalizeConfig。
  • 使用 resolveExecutionArgs 进行属于 CLI 方言的请求作用域 argv 重写,例如将 OpenClaw 思考级别映射到原生 effort 标志。该钩子接收 ctx.executionMode;使用 "side-question" 为临时 /btw 调用添加后端原生的隔离标志。如果这些标志能可靠地禁用原本始终开启的 CLI 的原生工具,也请声明 sideQuestionToolMode: "disabled"。
  • 使用 prepareExecution 处理后端自有的启动环境或临时认证/配置桥接。其 ctx.contextTokenBudget 是为本次运行选择的有效 token 限制,因此原生压缩后端可以在没有提供者特定核心分支的情况下对齐自己的阈值。其可选的 ctx.thinkingLevel 是实际生效的 off、minimal、low、medium、high、xhigh、adaptive 或 max 选择,适用于通过启动环境或分阶段配置应用该级别的后端。当后端暂存必须扩展捆绑的 MCP 设置时,它还会接收核心准备的 ctx.env。
  • 能够为特定运行禁用所有原生工具的后端可以声明 nativeToolMode: "selectable"。受限调用会传递精确的 ctx.toolAvailability.native 列表以及规范的 ctx.toolAvailability.openClaw 名称。声明 toolAvailabilityEnforcement: "execution-args" 并在最终的 fresh/resume argv 中执行该契约,或者声明 "prepare-execution",在分阶段策略中执行该契约,并返回 toolAvailabilityEnforced: true。OpenClaw 会为运行时上限(如 cron toolsAllow)禁用原生工具,并在声明的执行路径不完整时默认安全关闭。

有关端到端编写指南,请参阅 CLI 后端插件。

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