How to Build and Register Agent Tools in OpenClaw

I often find that the biggest hurdle in building AI agents is getting them to actually interact with the real world. You have an LLM that can think, but it lacks the specific “hands” it needs to execute tasks in your unique environment. It is frustrating when you have a local script or a specific API ready to go, but no clear way to let the agent use it.

In OpenClaw, we solve this by registering agent tools through plugins. These are essentially JSON-schema functions that the LLM can call during a run.

What You’ll Need

• An OpenClaw plugin environment.
• @sinclair/typebox library (for schema definition).

Quick Start

You can register tools that are either available by default or opt-in only. I recommend using the api.registerTool method within your plugin’s default export.

1. Create a Basic Tool

This is the simplest way to get a tool up and running. This tool will be available to your agents based on your global or agent-specific tool configuration.

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 }] };
    },
  });
}

2. Create an Optional Tool

If your tool has side effects—like writing files or hitting external APIs—I suggest making it optional. Optional tools are never enabled automatically; you have to explicitly allow them in your config.

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 },
  );
}

3. Enable the Tool in Config

To use that optional tool, you need to update your agents.json5 or main configuration file. You can allow a specific tool name, an entire plugin, or a group of plugins.

{
  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
          ],
        },
      },
    ],
  },
}

Troubleshooting

• Tool is not showing up: Check for name clashes. If your tool name matches a core tool name, OpenClaw skips it. Also, verify that your plugin ID does not clash with core tool names.
• Optional tool is inactive: Remember that optional: true tools require an explicit entry in the allow list. If your allowlist only contains plugin tools, core tools stay enabled, but your specific optional tool needs to be named or included via a group.
• Sandbox restrictions: If you are running in a sandbox, check tools.sandbox.tools.* to see if your tool policy is being restricted.
• Provider issues: Sometimes availability changes based on the LLM provider. Check tools.byProvider if a specific model isn’t seeing your tool.

If you hit a wall while setting this up, you can get help from the AI Setup Assistant.

What’s Next

• Plugin Configuration
• Agent Settings