插件 SDK 参考
插件 SDK DefineToolPlugin 帮助程序
参考插件 SDK 参考
仅添加代理工具的插件的入口助手。 插件入口点的部分参考。
导入： openclaw/plugin-sdk/tool-plugin
适用于只添加代理工具的插件。它保持源代码简洁，可从 TypeBox schema 推断 config 和工具参数类型，将普通返回值包装为 OpenClaw 工具结果格式，并暴露静态元数据， openclaw plugins build 会将其写入插件清单（contracts.tools、 configSchema）。
typescriptimport { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";import { Type } from "typebox"; export default defineToolPlugin({ id: "stock-quotes", name: "Stock Quotes", description: "Fetch stock quotes.", configSchema: Type.Object({ apiKey: Type.Optional(Type.String({ description: "API key." })), }), tools: (tool) => [ tool({ name: "quote", label: "Quote", description: "Fetch a quote.", parameters: Type.Object({ symbol: Type.String({ description: "Ticker symbol." }), }), 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 绝不会执行插件代码来推断缺失的清单数据。
依赖于输入的输出模式
现有的 outputSchema 字段通过版本化的 x-openclaw-input-discriminator JSON 架构注释支持特定于操作的代码模式结果。使用标准 TypeBox API 从相同的本地变体构造联合和映射：
typescriptconst variants = Object.entries({ list: Type.Object({ items: Type.Array(Type.String()) }), status: Type.Object({ ready: Type.Boolean() }),});const outputSchema = Type.Union( variants.map(([, schema]) => schema), { "x-openclaw-input-discriminator": { version: 1, inputProperty: "action", mapping: Object.fromEntries(variants.map(([value], index) => [value, index])), }, },);
将结果用作 defineToolPlugin 或 api.registerTool 中的 outputSchema。包括每个变体中的成功和非投掷失败结果。静态元数据保留注释。代码模式推断所选的返回类型；工具搜索验证实际和最初宣传的操作结果。缺失或广泛的选择器保留了健全的联盟。超出现有界限的引用模式和声明使用保守的伞式契约。有关版本、挂钩和验证行为，请参阅 输入相关输出。
