跳转至

工具与命令

用于代理可见工具、自定义命令、节点主机命令和 widget 展示器的注册器。属于 Plugin SDK 概述 的一部分。

工具和命令

对于仅包含工具且工具名称固定的简单插件,请使用 defineToolPlugin。对于混合插件或完全动态的工具注册,请直接使用 api.registerTool(...)。

当 OpenClaw 在受管理操作中调用带有 AbortSignal 的插件工具时,取消回调会保留执行中插件的运行时上下文和原始取消原因。该工具可以在已启动的 SDK 工作完成之前返回结果;这些工作仍归其所有,直到其清理流程完成。插件或操作关闭后,取消清理不会授权新的调用。请返回或加入你的工具在 SDK 管理操作之外启动的后台工作。没有受管理操作的直接编程调用者继续拥有其信号和工作生命周期。

方法 注册内容
api.registerTool(tool, opts?) 代理工具(必需或 { optional: true })
api.registerCommand(def) 自定义命令(绕过 LLM)
api.registerNodeHostCommand(command) 由 openclaw node run 处理的命令;可选的 agentTool 元数据可在节点连接期间将其暴露为代理可见工具
api.registerWidgetPresenter(presenter) 核心 show_widget 工具背后的显式或当前频道目标

显式 widget 展示器声明一个唯一的模型可见目标,例如 node_panel。当前频道展示器使用 target: "current_channel",提供基于可信交付事实的同步 match(context) 谓词,并声明支持的源类型和交付限制。多个传输展示器可以共存,但只有恰好一个匹配时,核心才会选择隐式路由。

核心验证规范化的 show_widget 模式,组合有界 HTML 文档,并将不可变的 HTML 以及可选的托管 URL 传递给 present(...)。展示器返回通用消息回执或节点回执。预期的可用性和展示失败使用封闭的错误结果而不是抛出异常;核心仅对实际的 inline-widgets 客户端进行内联回退,否则会呈现失败。

Computer Use 提供程序使用来自 openclaw/plugin-sdk/computer-use 的 registerComputerUseProvider(api, provider)。它在提供程序保持其驱动程序、帧、可用性和执行生命周期为本地状态的同时,只注册一次共享的 screen.snapshot/computer.act 节点主机封装。其可选的 prepare(context) 钩子在节点首次能力声明之前完成原生启动,而不会开启 Computer Use 执行。

当代理需要简短且由命令拥有的路由提示时,插件命令可以设置 agentPromptGuidance。让该文本只描述命令本身;不要向核心提示构建器添加提供程序或插件特定的策略。

接收到 senderIsOwner 的命令在被接纳为所有者时,还会收到主机的可选 assertOwnerCurrent 回调。在等待准备之前捕获该回调,并将其传递给变更所有者的当前权限检查。布尔型所有者快照不会在关联配置文件被降级、取消关联或重新分配后授权后续写入。该回调绑定到原始身份和命令调用;在处理器返回后保留它无法启动新的工作。已接受的操作仍会完成其结算和清理。普通的授权读取命令和显式 Gateway 范围检查保留其现有行为。

命令还可以为已解析的无参数调用声明一个有界的客户端展示操作:

api.registerCommand({
  name: "pair",
  description: "Pair a device",
  clientPresentation: {
    when: "no-arguments",
    action: { kind: "device-pairing" },
  },
  handler: async () => ({ text: "ok" }),
});

操作联合是封闭的,并且有意不接受路由、回调、URL 或任意客户端数据。支持的客户端仅在其能够完成操作时才处理该操作;否则命令遵循其正常的远程路径。此元数据表达的是展示意图,而非授权:Gateway 对客户端流程执行的每个 RPC 仍然具有权威性。

指导条目可以是遗留字符串(应用于每个提示面),也可以是结构化条目:

api.registerCommand({
  name: "demo_cmd",
  description: "Demo command",
  agentPromptGuidance: [
    "Global command hint.",
    { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
  ],
  handler: async () => ({ text: "ok" }),
});

结构化的 surfaces 可包含 openclaw_main、codex_app_server、cli_backend、acp_backend 或 subagent。pi_main 仍然是 openclaw_main 的已弃用别名;兼容性注册表已于 2026-07-25 将其弃用,removeAfter 日期为 2026-10-01(请参阅移除时间线)。对于有意覆盖所有表面的指导,请省略 surfaces。不要传递空的 surfaces 数组;它会被拒绝,这样意外的范围丢失就不会变成全局提示文本。

原生 Codex app-server 开发者指令比其他提示面更严格:只有明确限定到 codex_app_server 的指导才会被提升到那个更高优先级的通道。为了兼容性,遗留字符串指导和无范围限定的结构化指导仍然可用于非 Codex 提示面。

节点主机命令运行在已连接的节点主机上,而不是 Gateway 进程内部。如果存在 agentTool,节点会在成功连接 Gateway 后发布一个描述符;Gateway 仅在该节点已连接且描述符的 command 位于该节点已批准的命令面内时,才将其暴露给 agent 运行。设置 agentTool.defaultPlatforms 可将非危险命令加入默认节点命令允许列表;否则需要显式配置 gateway.nodes.commands.allow 或 node-invoke 策略。agentTool.name 必须对 provider 安全:以字母开头,仅使用字母、数字、下划线或连字符,并且不超过 64 个字符。基于 MCP 的节点工具可以设置 agentTool.mcp 元数据,以便目录和工具搜索界面显示远程 MCP 服务器/工具身份,但执行仍通过已通告的节点命令进行。

节点主机命令必须提供 hasActiveWork(): boolean,以允许自动节点更新。同步读取已拥有的状态,并且仅当后台进程、保留的流及其清理均已稳定时返回 false。工作可在 handle(...) 内完成的命令可以声明 hasActiveWork: () => false;节点主机会单独跟踪进行中的调用。 createSessionCatalogNodeHostBindings 会将其 hasActiveWork 选项转发给每个生成的命令。

缺失的钩子、抛出的错误,或除 false 以外的任何结果都会延迟激活。这会保留由早于空闲钩子的旧插件拥有的工作。该查询也会针对不可用的命令运行,因为在工作仍被保留期间,可用性可能会变化。将拆除保留在命令的现有生命周期中,例如 onDisconnect,并且仅在该工作稳定后才报告空闲。仅 onDisconnect 并不能确立空闲状态。更新旧插件以添加该钩子,或使用 openclaw update 以及由操作员控制的节点重启。

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