OpenClawプラグインでAgent Toolsを自作する方法

LLMに特定の動作をさせたいとき、標準の機能だけでは足りないことがあります。ローカルのファイルを操作したり、特定の API と連携させたりするには、開発者がツールを定義して LLM に「道具」として渡してあげる必要があります。

しかし、すべてのツールを常に有効にしていると、LLMが混乱したり、意図しない動作を招いたりすることもあります。必要なときに、必要なツールだけを安全に使えるように設定するのが理想的です。OpenClaw のプラグイン機能を使えば、こうしたツールの管理がとてもスムーズになります。

必要なもの

• OpenClaw の実行環境
• TypeScript または JavaScript の基礎知識

クイックスタート

OpenClaw のプラグインでは、LLM が実行できる agent tools（JSON‑schema 関数）を登録できます。ツールには、常に利用可能な「必須ツール」と、設定したときだけ有効になる「オプションツール」の 2 種類があります。

1. 基本的なツールの登録

まずは、シンプルなツールを作成してみましょう。以下の例では、入力をそのままテキストとして返す my_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 }] };
    },
  });
}

2. オプションツールの登録

副作用がある処理や、特定の環境でのみ使いたいツールは optional: true を指定するのがおすすめです。この設定をしたツールは、明示的に許可リスト（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 },
  );
}

3. ツールの有効化

オプションツールを使うには、設定ファイルの agents.list[].tools.allow（またはグローバルの tools.allow）に記述します。

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // 特定のツール名
            "workflow", // プラグインID（そのプラグインの全ツールを許可）
            "group:plugins", // すべてのプラグインツールを許可
          ],
        },
      },
    ],
  },
}

ツールを管理する際は、以下の設定も活用してください。

• tools.profile / agents.list[].tools.profile: ベースとなる許可リスト
• tools.byProvider: プロバイダーごとの許可・拒否設定

トラブルシューティング

ツールがうまく動作しない場合は、以下の 2 点を確認してください。

• 名前の競合: ツール名が OpenClaw のコアツールの名前と重なっていると、そのツールはスキップされます。
• プラグイン ID の重複: 許可リストで使用するプラグイン ID も、コアツールの名前と重ならないようにしてください。

副作用が発生するツールや、外部のバイナリ・認証情報を必要とするツールの場合は、optional: true を設定して明示的にオプトインする形をとるのがベストプラクティスです。

AI Setup Assistant

次のステップ

• Plugin API reference
• Agent configuration guide