"source": "Plugin SDK",

"target": "插件 SDK"

},

{

"source": "Tool plugins",

"target": "工具插件"

},

{

"source": "Plugin SDK subpaths",

"target": "插件 SDK 子路径"

},

{

"source": "Plugins CLI",

"target": "插件 CLI"

},

{

"source": "Plugins",

"target": "插件"

Tools are typed functions the LLM can call. They can be required (always

available) or optional (user opt-in):

For simple plugins that only own a fixed set of tools, prefer

[`defineToolPlugin`](/plugins/tool-plugins). It generates manifest metadata and

keeps `contracts.tools` aligned. Use the lower-level `api.registerTool(...)`

surface when the plugin also owns channels, providers, hooks, services,

commands, or fully dynamic tool registration.

```typescript

register(api) {

// Required tool - always available

### Tools and commands

Use [`defineToolPlugin`](/plugins/tool-plugins) for simple tool-only plugins

with fixed tool names. Use `api.registerTool(...)` directly for mixed plugins

or fully dynamic tool registration.

| Method | What it registers |

| ------------------------------- | --------------------------------------------- |

| `api.registerTool(tool, opts?)` | Agent tool (required or `{ optional: true }`) |

Tool names are the stable API. Pick names that are unique, lowercase, and

specific enough to avoid collisions with core tools or other plugins.

## Optional and factory tools

Set `optional: true` when users should explicitly allowlist the tool before it

is sent to a model:

```typescript

tool({

name: "workflow_run",

description: "Run an external workflow.",

parameters: Type.Object({ goal: Type.String() }),

optional: true,

execute: ({ goal }) => ({ queued: true, goal }),

});

```

`openclaw plugins build` writes the matching `toolMetadata.<tool>.optional`

manifest entry, so OpenClaw can discover the tool without loading plugin

runtime code.

Use `factory` when a tool needs the runtime tool context before it can be

created. The factory keeps metadata static while letting the tool opt out for a

specific run, inspect sandbox state, or bind runtime helpers.

```typescript

tool({

name: "local_workflow",

description: "Run a local workflow outside sandboxed sessions.",

parameters: Type.Object({ goal: Type.String() }),

optional: true,

factory({ api, toolContext }) {

if (toolContext.sandboxed) {

return null;

}

return createLocalWorkflowTool(api);

},

});

```

Factories are still for fixed tool names. Use `definePluginEntry` directly when

the plugin computes tool names dynamically or combines tools with hooks,

services, providers, commands, or other runtime surfaces.

## Return values

`defineToolPlugin` wraps plain return values into the OpenClaw tool-result

});

```

Use `definePluginEntry` instead of `defineToolPlugin` when you need to return a

custom `AgentToolResult`, stream custom progress semantics, register dynamic

tools, or combine tools with hooks, services, providers, commands, or other

advanced surfaces.

Use a factory tool when you need to return a custom `AgentToolResult` or reuse

an existing `api.registerTool` implementation. Use `definePluginEntry` instead

of `defineToolPlugin` when you need fully dynamic tools or mixed plugin

capabilities.

## Configuration

import { definePluginEntry, type AnyAgentTool, type OpenClawPluginApi } from "./api.js";

import { createLlmTaskTool } from "./src/llm-task-tool.js";

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

import { Type } from "typebox";

import type { AnyAgentTool } from "./api.js";

import { createLlmTaskTool, llmTaskToolDefinition } from "./src/llm-task-tool.js";

export default definePluginEntry({

export default defineToolPlugin({

id: "llm-task",

name: "LLM Task",

description: "Optional tool for structured subtask execution",

register(api: OpenClawPluginApi) {

api.registerTool(createLlmTaskTool(api) as unknown as AnyAgentTool, { optional: true });

},

description: "Generic JSON-only LLM tool for structured tasks callable from workflows.",

configSchema: Type.Object(

{

defaultProvider: Type.Optional(Type.String()),

defaultModel: Type.Optional(Type.String()),

defaultAuthProfileId: Type.Optional(Type.String()),

allowedModels: Type.Optional(

Type.Array(Type.String(), {

description: "Allowlist of provider/model keys like openai-codex/gpt-5.2.",

}),

),

maxTokens: Type.Optional(Type.Number()),

timeoutMs: Type.Optional(Type.Number()),

},

{ additionalProperties: false },

),

tools: (tool) => [

tool({

...llmTaskToolDefinition,

optional: true,

factory: ({ api }) => createLlmTaskTool(api) as unknown as AnyAgentTool,

}),

],

});

type ThinkingPolicy = ReturnType<OpenClawPluginApi["runtime"]["agent"]["resolveThinkingPolicy"]>;

export const llmTaskToolDefinition = {

name: "llm-task",

label: "LLM Task",

description:

"Run a generic JSON-only LLM task and return schema-validated JSON. Designed for orchestration from Lobster workflows via openclaw.invoke.",

parameters: Type.Object({

prompt: Type.String({ description: "Task instruction for the LLM." }),

input: Type.Optional(Type.Unknown({ description: "Optional input payload for the task." })),

schema: Type.Optional(

Type.Unknown({ description: "Optional JSON Schema to validate the returned JSON." }),

),

provider: Type.Optional(

Type.String({ description: "Provider override (e.g. openai-codex, anthropic)." }),

),

model: Type.Optional(Type.String({ description: "Model id override." })),

thinking: Type.Optional(Type.String({ description: "Thinking level override." })),

authProfileId: Type.Optional(Type.String({ description: "Auth profile override." })),

temperature: Type.Optional(Type.Number({ description: "Best-effort temperature override." })),

maxTokens: Type.Optional(Type.Number({ description: "Best-effort maxTokens override." })),

timeoutMs: Type.Optional(Type.Number({ description: "Timeout for the LLM run." })),

}),

};

function formatThinkingPolicy(policy: ThinkingPolicy): string {

return policy.levels.map((level) => level.label).join(", ");

}

export function createLlmTaskTool(api: OpenClawPluginApi) {

return {

name: "llm-task",

label: "LLM Task",

description:

"Run a generic JSON-only LLM task and return schema-validated JSON. Designed for orchestration from Lobster workflows via openclaw.invoke.",

parameters: Type.Object({

prompt: Type.String({ description: "Task instruction for the LLM." }),

input: Type.Optional(Type.Unknown({ description: "Optional input payload for the task." })),

schema: Type.Optional(

Type.Unknown({ description: "Optional JSON Schema to validate the returned JSON." }),

),

provider: Type.Optional(

Type.String({ description: "Provider override (e.g. openai-codex, anthropic)." }),

),

model: Type.Optional(Type.String({ description: "Model id override." })),

thinking: Type.Optional(Type.String({ description: "Thinking level override." })),

authProfileId: Type.Optional(Type.String({ description: "Auth profile override." })),

temperature: Type.Optional(Type.Number({ description: "Best-effort temperature override." })),

maxTokens: Type.Optional(Type.Number({ description: "Best-effort maxTokens override." })),

timeoutMs: Type.Optional(Type.Number({ description: "Timeout for the LLM run." })),

}),

...llmTaskToolDefinition,

async execute(_id: string, params: LlmTaskParams) {

const prompt = typeof params.prompt === "string" ? params.prompt : "";

return metadata;

}

function createOptionalDemoMetadata() {

const entry = defineToolPlugin({

id: "optional-demo-tools",

name: "Optional Demo Tools",

description: "Optional demo tool plugin.",

tools: (tool) => [

tool({

name: "demo_optional_echo",

description: "Echo input.",

parameters: Type.Object({ input: Type.String() }),

optional: true,

execute: ({ input }) => ({ input }),

}),

],

});

const metadata = getToolPluginMetadata(entry);

if (!metadata) {

throw new Error("missing metadata");

}

return metadata;

}

describe("plugin authoring commands", () => {

it("generates manifest metadata from defineToolPlugin metadata", () => {

const metadata = createDemoMetadata();

});

});

it("generates optional tool metadata for optional tool plugins", () => {

const metadata = createOptionalDemoMetadata();

expect(buildToolPluginManifest({ metadata, packageManifest: { version: "1.2.3" } })).toEqual({

id: "optional-demo-tools",

name: "Optional Demo Tools",

description: "Optional demo tool plugin.",

version: "1.2.3",

configSchema: {

type: "object",

additionalProperties: false,

properties: {},

},

activation: { onStartup: true },

contracts: { tools: ["demo_optional_echo"] },

toolMetadata: {

demo_optional_echo: { optional: true },

},

});

});

it("aligns package metadata with the selected runtime extension entry", () => {

expect(

buildToolPluginPackageManifest({

metadata: ToolPluginMetadata;

packageManifest: JsonObject;

}): JsonObject {

const optionalTools = params.metadata.tools.filter((tool) => tool.optional);

return {

id: params.metadata.id,

name: params.metadata.name,

contracts: {

tools: params.metadata.tools.map((tool) => tool.name),

},

...(optionalTools.length > 0

? {

toolMetadata: Object.fromEntries(

optionalTools.map((tool) => [tool.name, { optional: true }]),

),

}

: {}),

};

}

});

});

it("passes optional tools through to runtime registration and metadata", () => {

const entry = defineToolPlugin({

id: "optional-tools",

name: "Optional Tools",

description: "Optional tool demo.",

tools: (tool) => [

tool({

name: "optional_echo",

description: "Echo input.",

parameters: Type.Object({ input: Type.String() }),

optional: true,

execute: ({ input }) => input,

}),

],

});

const captured = createCapturedPluginRegistration({ id: "optional-tools" });

const registerTool = vi.fn();

captured.api.registerTool = registerTool as typeof captured.api.registerTool;

entry.register(captured.api);

expect(registerTool).toHaveBeenCalledWith(expect.objectContaining({ name: "optional_echo" }), {

optional: true,

});

expect(getToolPluginMetadata(entry)?.tools).toMatchObject([

{ name: "optional_echo", optional: true },

]);

});

it("supports context factories while keeping static tool metadata", () => {

const entry = defineToolPlugin({

id: "factory-tools",

name: "Factory Tools",

description: "Factory tool demo.",

configSchema: Type.Object({ prefix: Type.String() }),

tools: (tool) => [

tool({

name: "factory_echo",

label: "Factory Echo",

description: "Echo input.",

parameters: Type.Object({ input: Type.String() }),

optional: true,

factory({ config, toolContext }) {

if (toolContext.sandboxed) {

return null;

}

return {

name: "factory_echo",

label: "Factory Echo",

description: "Echo input.",

parameters: Type.Object({ input: Type.String() }),

async execute(_toolCallId: string, params: { input?: unknown }) {

const input = typeof params.input === "string" ? params.input : "";

return {

content: [

{

type: "text",

text: `${config.prefix}:${input}`,

},

],

details: undefined,

};

},

};

},

}),

],

});

const captured = createCapturedPluginRegistration({ id: "factory-tools" });

captured.api.pluginConfig = { prefix: "ctx" };

const registerTool = vi.fn();

captured.api.registerTool = registerTool as typeof captured.api.registerTool;

entry.register(captured.api);

expect(registerTool).toHaveBeenCalledWith(expect.any(Function), {

name: "factory_echo",

optional: true,

});

expect(getToolPluginMetadata(entry)?.tools).toMatchObject([

{

name: "factory_echo",

label: "Factory Echo",

optional: true,

},

]);

const factory = registerTool.mock.calls[0]?.[0] as (ctx: { sandboxed?: boolean }) => unknown;

expect(factory({ sandboxed: true })).toBeNull();

expect(factory({ sandboxed: false })).toMatchObject({ name: "factory_echo" });

});

it("defaults author config to a strict empty object schema", () => {

const entry = defineToolPlugin({

id: "empty-config",