openclaw/docs/plugins/tool-plugins.md

---
summary: "Build simple typed agent tools with defineToolPlugin and openclaw plugins init/build/validate"
title: "Tool plugins"
sidebarTitle: "Tool Plugins"
read_when:
  - You want to build a simple OpenClaw plugin that only adds agent tools
  - You want to use defineToolPlugin instead of hand-writing plugin manifest metadata
  - You need to scaffold, generate, validate, test, or publish a tool-only plugin
---

Tool plugins add agent-callable tools to OpenClaw without adding a channel,
model provider, hook, service, or setup backend. Use `defineToolPlugin` when the
plugin owns a fixed list of tools and you want OpenClaw to generate the manifest
metadata that keeps those tools discoverable without loading runtime code.

The recommended flow is:

1. Scaffold a package with `openclaw plugins init`.
2. Write tools with `defineToolPlugin`.
3. Build JavaScript.
4. Generate `openclaw.plugin.json` and `package.json` metadata with
   `openclaw plugins build`.
5. Validate the generated metadata before publishing or installing.

For provider, channel, hook, service, or mixed-capability plugins, start with
[Building plugins](/plugins/building-plugins), [Channel Plugins](/plugins/sdk-channel-plugins),
or [Provider Plugins](/plugins/sdk-provider-plugins) instead.

## Requirements

- Node >= 22.
- TypeScript ESM package output.
- `typebox` for config and tool parameter schemas.
- `openclaw >=2026.5.17`, the first OpenClaw version that exports
  `openclaw/plugin-sdk/tool-plugin`.
- A package root that can ship `dist/`, `openclaw.plugin.json`, and
  `package.json`.

The generated plugin imports `typebox` at runtime, so keep `typebox` in
`dependencies`, not only `devDependencies`.

## Quickstart

Create a new plugin package:

```bash
openclaw plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm install
npm run plugin:build
npm run plugin:validate
npm test
```

The scaffold creates:

- `src/index.ts`: a `defineToolPlugin` entry with an `echo` tool.
- `src/index.test.ts`: a small metadata test.
- `tsconfig.json`: NodeNext TypeScript output to `dist/`.
- `package.json`: scripts, runtime dependencies, and
  `openclaw.extensions: ["./dist/index.js"]`.
- `openclaw.plugin.json`: generated manifest metadata for the initial tool.

Expected validation output:

```text
Plugin stock-quotes is valid.
```

## Write a tool

`defineToolPlugin` takes plugin identity, an optional config schema, and a
static list of tools. Parameter and config types are inferred from TypeBox
schemas.

```typescript
import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quote snapshots.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "Quote API key." })),
    baseUrl: Type.Optional(Type.String({ description: "Quote API base URL." })),
  }),
  tools: (tool) => [
    tool({
      name: "stock_quote",
      label: "Stock Quote",
      description: "Fetch a stock quote snapshot.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol, for example OPEN." }),
      }),
      async execute({ symbol }, config, context) {
        context.signal?.throwIfAborted();
        return {
          symbol: symbol.toUpperCase(),
          configured: Boolean(config.apiKey),
          baseUrl: config.baseUrl ?? "https://api.example.com",
        };
      },
    }),
  ],
});
```

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
format:

- Return a string when the model should see that exact text.
- Return a JSON-compatible value when you want the model to see formatted JSON
  and OpenClaw to keep the original value in `details`.

```typescript
tool({
  name: "echo_text",
  description: "Echo input text.",
  parameters: Type.Object({
    input: Type.String(),
  }),
  execute: ({ input }) => input,
});
```

```typescript
tool({
  name: "echo_json",
  description: "Echo input as structured JSON.",
  parameters: Type.Object({
    input: Type.String(),
  }),
  execute: ({ input }) => ({ input, length: input.length }),
});
```

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

`configSchema` is optional. If you omit it, OpenClaw uses a strict empty object
schema and the generated manifest still includes `configSchema`.

```typescript
export default defineToolPlugin({
  id: "no-config-tools",
  name: "No Config Tools",
  description: "Adds tools that do not need configuration.",
  tools: () => [],
});
```

When you include `configSchema`, the second `execute` argument is typed from the
schema:

```typescript
const configSchema = Type.Object({
  apiKey: Type.String(),
});

export default defineToolPlugin({
  id: "configured-tools",
  name: "Configured Tools",
  description: "Adds configured tools.",
  configSchema,
  tools: (tool) => [
    tool({
      name: "configured_ping",
      description: "Check whether configuration is available.",
      parameters: Type.Object({}),
      execute: (_params, config) => ({ hasKey: config.apiKey.length > 0 }),
    }),
  ],
});
```

OpenClaw reads plugin config from the plugin entry in the Gateway config. Do not
hard-code secrets in source or in docs examples. Use config, environment
variables, or SecretRefs according to the plugin's security model.

## Generated metadata

OpenClaw discovers installed plugins from cold metadata. It must be able to read
the plugin manifest before importing plugin runtime code. `defineToolPlugin`
therefore exposes static metadata, and `openclaw plugins build` writes that
metadata into the package.

Run the generator after changing plugin id, name, description, config schema,
activation, or tool names:

```bash
npm run build
openclaw plugins build --entry ./dist/index.js
```

For a one-tool plugin, the generated manifest looks like this:

```json
{
  "id": "stock-quotes",
  "name": "Stock Quotes",
  "description": "Fetch stock quote snapshots.",
  "version": "0.1.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  },
  "activation": {
    "onStartup": true
  },
  "contracts": {
    "tools": ["stock_quote"]
  }
}
```

`contracts.tools` is the important discovery contract. It tells OpenClaw which
plugin owns each tool without loading every installed plugin runtime. If the
manifest is stale, the tool may be missing from discovery or the wrong plugin
may be blamed for a registration error.

## Package metadata

For the simple tool-plugin workflow, `openclaw plugins build` aligns
`package.json` to the selected single runtime entry:

```json
{
  "type": "module",
  "files": ["dist", "openclaw.plugin.json", "README.md"],
  "dependencies": {
    "typebox": "^1.1.38"
  },
  "peerDependencies": {
    "openclaw": ">=2026.5.17"
  },
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}
```

Use built JavaScript such as `./dist/index.js` for installed packages. Source
entries are useful in workspace development, but published packages should not
depend on TypeScript runtime loading.

## Validate in CI

Use `plugins build --check` to fail CI when generated metadata is stale without
rewriting files:

```bash
npm run build
openclaw plugins build --entry ./dist/index.js --check
openclaw plugins validate --entry ./dist/index.js
npm test
```

`plugins validate` checks that:

- `openclaw.plugin.json` exists and passes the normal manifest loader.
- The current entry exports `defineToolPlugin` metadata.
- Generated manifest fields match the entry metadata.
- `contracts.tools` matches the declared tool names.
- `package.json` points `openclaw.extensions` at the selected runtime entry.

## Install and inspect locally

From a separate OpenClaw checkout or installed CLI, install the package path:

```bash
openclaw plugins install ./stock-quotes
openclaw plugins inspect stock-quotes --runtime
```

For a packaged smoke, pack first and install the tarball:

```bash
npm pack
openclaw plugins install npm-pack:./openclaw-plugin-stock-quotes-0.1.0.tgz
openclaw plugins inspect stock-quotes --runtime --json
```

After installation, start or restart the Gateway and ask the agent to use the
tool. If you are debugging tool visibility, inspect the plugin runtime and the
effective tool catalog before changing the code.

## Publish

Publish through ClawHub when the package is ready:

```bash
clawhub package publish your-org/stock-quotes --dry-run
clawhub package publish your-org/stock-quotes
```

Install with an explicit ClawHub locator:

```bash
openclaw plugins install clawhub:your-org/stock-quotes
```

Bare npm package specs remain supported during the launch cutover, but ClawHub
is the preferred discovery and distribution surface for OpenClaw plugins.

## Troubleshooting

### `plugin entry not found: ./dist/index.js`

The selected entry file does not exist. Run `npm run build`, then rerun
`openclaw plugins build --entry ./dist/index.js` or
`openclaw plugins validate --entry ./dist/index.js`.

### `plugin entry does not expose defineToolPlugin metadata`

The entry did not export a value created by `defineToolPlugin`. Check that the
module default export is the `defineToolPlugin(...)` result, or pass the correct
entry with `--entry`.

### `openclaw.plugin.json generated metadata is stale`

The manifest no longer matches the entry metadata. Run:

```bash
npm run build
openclaw plugins build --entry ./dist/index.js
```

Commit both `openclaw.plugin.json` and `package.json` changes.

### `package.json openclaw.extensions must include ./dist/index.js`

The package metadata points at a different runtime entry. Run
`openclaw plugins build --entry ./dist/index.js` so the generator aligns the
package metadata with the entry you intend to ship.

### `Cannot find package 'typebox'`

The built plugin imports `typebox` at runtime. Keep `typebox` in
`dependencies`, reinstall package dependencies, rebuild, and rerun validation.

### Tool does not appear after install

Check these in order:

1. `openclaw plugins inspect <plugin-id> --runtime`
2. `openclaw plugins validate --root <plugin-root> --entry ./dist/index.js`
3. `openclaw.plugin.json` has `contracts.tools` with the expected tool names.
4. `package.json` has `openclaw.extensions: ["./dist/index.js"]`.
5. The Gateway was restarted or reloaded after installing the plugin.

## See also

- [Building plugins](/plugins/building-plugins)
- [Plugin entry points](/plugins/sdk-entrypoints)
- [Plugin SDK subpaths](/plugins/sdk-subpaths)
- [Plugin manifest](/plugins/manifest)
- [Plugins CLI](/cli/plugins)
- [ClawHub publishing](/clawhub/publishing)