openclaw plugin typescript automation

OpenClawプラグイン開発入門：独自ツールを追加する方法

2026年07月03日 · 約 2 分で読めます

OpenClawに独自ツールを追加する最小構成のプラグイン開発手順を解説します。TypeScriptでの実装からビルド、検証、ローカルインストールまでを紹介します。

OpenClawのツールプラグインを使うと、外部APIとの連携や社内処理など、エージェントが呼び出せる独自機能を追加できます。本記事では、入力文字列を返す最小のツールを実装します。

結論：OpenClawのプラグイン開発は、ツールを1つだけ実装し、ビルドと検証を通してから段階的に拡張するのが最短です。

Background

OpenClawのプラグインは、コア本体を変更せずに機能を拡張する仕組みです。ツールプラグインでは、型付きのパラメーターを受け取って処理を実行する機能をエージェントへ提供できます。

以下の環境を前提とします。

  • Node.js 22以降
  • OpenClaw 2026.5.17以降
  • npmが利用できる環境
  • TypeScriptとES Modulesの基礎知識

ツール名はモデルが利用する安定したAPIになります。既存ツールとの衝突を避けるため、小文字のスネークケースで具体的な名前を付けます。

Step-by-step

  1. プラグインを作成する

openclaw plugins initで雛形を生成し、依存パッケージをインストールします。

1
2
3
4
5

# プラグインの雛形を生成
openclaw plugins init text-utilities --name "Text Utilities"

cd text-utilities
npm install

生成されたsrc/index.ts、package.json、tsconfig.jsonを基に実装を進めます。

  1. 独自ツールを実装する

src/index.tsを次の内容に置き換えます。この例では、文字列を受け取り、大文字へ変換して返すtext_uppercaseツールを定義します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

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

export default defineToolPlugin({
  id: "text-utilities",
  name: "Text Utilities",
  description: "Provides simple text-processing tools.",

  tools: (tool) => [
    tool({
      name: "text_uppercase",
      label: "Uppercase Text",
      description: "Converts the supplied text to uppercase.",

      parameters: Type.Object({
        text: Type.String({
          description: "Text to convert to uppercase.",
          minLength: 1,
        }),
      }),

      execute: ({ text }) => ({
        original: text,
        uppercase: text.toUpperCase(),
      }),
    }),
  ],
});

parametersにはTypeBoxのスキーマを指定します。これにより、OpenClawはツールを実行する前に入力値を検証できます。

戻り値には文字列またはJSON互換の値を使用できます。この例のようなオブジェクトを返すと、モデルが扱いやすい構造化データになります。

  1. ビルドしてメタデータを更新する

TypeScriptをJavaScriptへビルドした後、プラグインのマニフェストを更新します。

1
2
3
4
5

# dist/index.jsを生成
npm run build

# 実装からopenclaw.plugin.jsonなどを生成・更新
openclaw plugins build --entry ./dist/index.js

ツール名やプラグインID、設定スキーマを変更した場合も、必ず両方のコマンドを再実行します。生成されるopenclaw.plugin.jsonのcontracts.toolsには、text_uppercaseが含まれます。

  1. プラグインを検証する

インストール前に、実装と生成済みメタデータの整合性を確認します。

1
2

openclaw plugins validate --entry ./dist/index.js
npm test

CIでは、生成済みメタデータが古くないことも検査できます。

1
2
3
4

npm run build
openclaw plugins build --entry ./dist/index.js --check
openclaw plugins validate --entry ./dist/index.js
npm test
  1. ローカル環境へインストールする

プラグインの親ディレクトリへ移動し、ローカルパスを指定してインストールします。

1
2
3
4

cd ..

openclaw plugins install ./text-utilities
openclaw plugins inspect text-utilities --runtime --json

インストール後はGatewayを再起動または再読み込みします。その後、エージェントへ「text_uppercaseを使ってOpenClaw Pluginを大文字にして」と依頼し、ツールが呼び出されることを確認します。

開発中に変更を即座に反映したい場合は、コピーではなくリンクとしてインストールできます。

1

openclaw plugins install --link ./text-utilities

Common pitfalls

  • ツールが一覧に表示されない
    openclaw plugins inspect text-utilities --runtimeでロード状態を確認します。あわせて、openclaw.plugin.jsonのcontracts.toolsにtext_uppercaseが含まれているか確認してください。

  • マニフェストが実装と一致しない
    ツール名やスキーマを変更した後は、npm run buildとopenclaw plugins build --entry ./dist/index.jsを再実行します。CIでは--checkを付け、古いメタデータを検出します。

  • dist/index.jsが見つからない
    インストール前にnpm run buildを実行します。package.jsonのopenclaw.extensionsが./dist/index.jsを指していることも確認してください。

  • typeboxを読み込めない
    typeboxは実行時にも必要です。devDependenciesではなくdependenciesに含め、npm install後に再ビルドします。

  • 変更後も古い動作が続く
    ビルドとメタデータ更新を行ったうえで、Gatewayを再起動または再読み込みします。通常インストールで更新が反映されない場合は、再インストールするか開発用の--linkを利用します。

  • 外部処理を無条件で実行してしまう
    ファイル変更や外部APIへの書き込みを行うツールは、入力検証とタイムアウトを実装し、必要に応じてオプショナルツールとして明示的な許可対象にします。APIキーなどの秘密情報はソースコードへ直接記述しないでください。

Summary

OpenClawへ独自ツールを追加する基本手順は、雛形の生成、ツールの実装、ビルド、メタデータの更新、検証、ローカルインストールです。

まずは副作用のないツールを1つ実装し、実行結果とログを確認してください。動作が安定してから設定値、外部API連携、認証、エラー処理を追加すると、問題の切り分けが容易になります。

タグ: openclaw plugin typescript automation