工具与命令

代理可见工具、自定义命令、节点宿主命令和小部件展示器的注册器。属于 插件 SDK 概览 的一部分。

工具和命令¶

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

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

显式小部件展示器声明唯一的模型可见目标，例如 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 提示表面使用，以保持兼容性。

Node-host commands run on the connected node host, not inside the Gateway process. If agentTool is present, the node publishes a descriptor after a successful Gateway connect; the Gateway exposes it to agent runs only while that node is connected and only if the descriptor's command is in the node's approved command surface. Set agentTool.defaultPlatforms to opt a non-dangerous command into the default node command allowlist; otherwise require explicit gateway.nodes.commands.allow or a node-invoke policy. agentTool.name must be provider-safe: start with a letter, use only letters, digits, underscores, or hyphens, and stay within 64 characters. MCP-backed node tools can set agentTool.mcp metadata so catalog and tool-search surfaces can show the remote MCP server/tool identity, but execution still goes through the advertised node command.

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

Node-host commands must provide hasActiveWork(): boolean to allow automatic node updates. Read already-owned state synchronously and return false only when background processes, retained streams, and their cleanup have settled. Commands whose work finishes within handle(...) can declare hasActiveWork: () => false; the node host separately tracks in-flight invocations. createSessionCatalogNodeHostBindings forwards its hasActiveWork option to each generated command.

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

An absent hook, a thrown error, or any result other than false defers activation. This preserves work owned by older plugins that predate the idle hook. The query also runs for unavailable commands because availability can change while work is still retained. Keep teardown in the command's existing lifecycle, such as onDisconnect, and report idle only after that work settles. onDisconnect alone does not establish idleness. Update older plugins to add the hook or use openclaw update and an operator-controlled node restart.

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