openclaw/docs/plugins/agent-tools.md

summary, read_when, title, sidebarTitle

summary	read_when	title	sidebarTitle
Register custom agent tools in a plugin with schemas, optional opt-in, and allowlists	You want to add a new agent tool in a plugin You need to make a tool opt-in via allowlists	Registering Tools in Plugins	Registering Tools

Registering Tools in Plugins

Plugins can register agent tools — typed functions that the LLM can call during agent runs. Tools can be required (always available) or optional (users opt in via allowlists).

See Building Plugins for the full plugin creation guide. This page focuses on the tool registration API.

Agent tools are configured under tools in the main config, or per‑agent under agents.list[].tools. The allowlist/denylist policy controls which tools the agent can call.

Basic tool

import { Type } from "@sinclair/typebox";

export default function (api) {
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({
      input: Type.String(),
    }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });
}

Optional tool (opt-in)

Optional tools are never auto‑enabled. Users must add them to an agent allowlist.

export default function (api) {
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a local workflow",
      parameters: {
        type: "object",
        properties: {
          pipeline: { type: "string" },
        },
        required: ["pipeline"],
      },
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

Enable optional tools in agents.list[].tools.allow (or global tools.allow):

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // specific tool name
            "workflow", // plugin id (enables all tools from that plugin)
            "group:plugins", // all plugin tools
          ],
        },
      },
    ],
  },
}

Other config knobs that affect tool availability:

• Allowlists that only name plugin tools are treated as plugin opt-ins; core tools remain enabled unless you also include core tools or groups in the allowlist.
• tools.profile / agents.list[].tools.profile (base allowlist)
• tools.byProvider / agents.list[].tools.byProvider (provider‑specific allow/deny)
• tools.sandbox.tools.* (sandbox tool policy when sandboxed)

Rules + tips

• Tool names must not clash with core tool names; conflicting tools are skipped.
• Plugin ids used in allowlists must not clash with core tool names.
• Prefer optional: true for tools that trigger side effects or require extra binaries/credentials.