Pluginの構築

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

前提条件

• Node >= 22 とパッケージマネージャー（npm または pnpm）
• TypeScript（ESM）に慣れていること
• リポジトリ内 Plugin の場合: リポジトリをクローンし、pnpm install を完了していること。ソースチェックアウトでの Plugin 開発は pnpm のみです。OpenClaw は extensions/* ワークスペースパッケージからバンドル済み Plugin を読み込むためです。

​

どの種類の Plugin ですか？

​

クイックスタート: ツール Plugin

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(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: `Got: ${params.input}` }] };
      },
    });
  },
});

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

pnpm test -- <bundled-plugin-root>/my-plugin/

​

Plugin 機能

• before_tool_call: { block: true } は終端であり、優先度の低いハンドラーを停止します。
• before_tool_call: { block: false } は判断なしとして扱われます。
• before_tool_call: { requireApproval: true } はエージェントの実行を一時停止し、exec 承認オーバーレイ、Telegram ボタン、Discord インタラクション、または任意のチャネルの /approve コマンドを介してユーザーに承認を求めます。
• before_install: { block: true } は終端であり、優先度の低いハンドラーを停止します。
• before_install: { block: false } は判断なしとして扱われます。
• message_sending: { cancel: true } は終端であり、優先度の低いハンドラーを停止します。
• message_sending: { cancel: false } は判断なしとして扱われます。
• message_received: 受信スレッド/トピックのルーティングが必要な場合は、型付きの threadId フィールドを優先してください。metadata はチャネル固有の追加情報用に保ってください。
• message_sending: チャネル固有のメタデータキーよりも、型付きの replyToId / threadId ルーティングフィールドを優先してください。

​

エージェントツールの登録

register(api) {
  // Required tool - always available
  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 - user must add to allowlist
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

{
  "contracts": {
    "tools": ["my_tool", "workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}

{
  tools: { allow: ["workflow_tool"] },
}

• ツール名はコアツールと衝突してはいけません（衝突したものはスキップされます）
• parameters の欠落を含む、不正な登録オブジェクトを持つツールは、エージェント実行を壊す代わりにスキップされ、Plugin 診断で報告されます
• 副作用や追加のバイナリ要件を持つツールには optional: true を使用してください
• ユーザーは Plugin ID を tools.allow に追加することで、その Plugin のすべてのツールを有効にできます

​

CLI コマンドの登録

register(api) {
  api.registerCli(
    ({ program }) => {
      const demo = program
        .command("demo-plugin")
        .description("Run demo plugin commands");

      demo
        .command("ping")
        .description("Check that the plugin CLI is executable")
        .action(() => {
          console.log("demo-plugin:pong");
        });
    },
    {
      descriptors: [
        {
          name: "demo-plugin",
          description: "Run demo plugin commands",
          hasSubcommands: true,
        },
      ],
    },
  );
}

openclaw plugins inspect demo-plugin --runtime --json
openclaw demo-plugin ping

​

インポート規約

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

• Anthropic: Claude ストリームラッパーと service_tier / ベータヘルパー
• OpenAI: プロバイダービルダー、デフォルトモデルヘルパー、リアルタイムプロバイダー
• OpenRouter: プロバイダービルダーとオンボーディング/設定ヘルパー

​

提出前チェックリスト

​

ベータリリーステスト

1. openclaw/openclaw の GitHub リリースタグを監視し、Watch > Releases で購読してください。ベータタグは v2026.3.N-beta.1 のような形式です。リリース告知を受け取るには、OpenClaw の公式 X アカウント @openclaw の通知をオンにすることもできます。
2. ベータタグが表示されたらすぐに、そのタグに対して Plugin をテストしてください。安定版までの猶予は通常、数時間だけです。
3. テスト後、plugin-forum Discord チャンネル内の自分の Plugin スレッドに、all good または壊れた内容を投稿してください。まだスレッドがない場合は作成してください。
4. 何かが壊れた場合は、Beta blocker: <plugin-name> - <summary> というタイトルの Issue を作成または更新し、beta-blocker ラベルを適用してください。スレッドに Issue リンクを載せてください。
5. fix(<plugin-id>): beta blocker - <summary> というタイトルで main への PR を開き、PR と Discord スレッドの両方で Issue をリンクしてください。コントリビューターは PR にラベルを付けられないため、タイトルがメンテナーと自動化に対する PR 側のシグナルになります。PR があるブロッカーはマージされます。PR がないブロッカーは、そのまま出荷される可能性があります。メンテナーはベータテスト中にこれらのスレッドを監視します。
6. 無言は問題なしを意味します。期間を逃した場合、修正はおそらく次のサイクルに入ります。

​

次のステップ

​

関連

• Plugin アーキテクチャ - 内部アーキテクチャの詳細解説
• SDK 概要 - Plugin SDK リファレンス
• マニフェスト - Plugin マニフェスト形式
• Channel Plugins - チャンネル Plugin の構築
• Provider Plugins - プロバイダー Plugin の構築