Pluginsの構築

pluginsは、新しい機能でOpenClawを拡張します: channels、model providers、 speech、realtime transcription、realtime voice、media understanding、image generation、video generation、web fetch、web search、agent tools、またはその任意の組み合わせです。 pluginをOpenClawリポジトリに追加する必要はありません。 ClawHub またはnpmに公開し、ユーザーは openclaw plugins install <package-name> でインストールできます。OpenClawはまずClawHubを試し、自動的にnpmへフォールバックします。

前提条件

Node >= 22 とパッケージマネージャー（npmまたはpnpm）
TypeScript（ESM）の基本知識
リポジトリ内pluginの場合: リポジトリをclone済みで、pnpm install を実行済み

どの種類のpluginか

Channel plugin

OpenClawをメッセージングプラットフォーム（Discord、IRCなど）に接続する

Provider plugin

model provider（LLM、proxy、またはカスタムendpoint）を追加する

Tool / hook plugin

agent tools、event hooks、またはservicesを登録する — 以下へ進む

channel pluginが任意であり、onboarding/setupの実行時にインストールされていない可能性がある場合は、 openclaw/plugin-sdk/channel-setup の createOptionalChannelSetupSurface(...) を使用してください。これにより、インストール要件を通知し、pluginがインストールされるまで実際の設定書き込みを安全に失敗させる setup adapter + ウィザードの組が生成されます。

クイックスタート: tool plugin

この手順では、agent toolを登録する最小限のpluginを作成します。channel pluginとprovider pluginには、上でリンクした専用ガイドがあります。

パッケージとmanifestを作成する

{
  "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"
    }
  }
}

すべてのpluginには、設定がなくてもmanifestが必要です。完全なスキーマは Manifest を参照してください。ClawHubの正規の公開スニペットは docs/snippets/plugin-publish/ にあります。

entry pointを書く

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

definePluginEntry はchannel以外のplugins向けです。channelsには defineChannelPluginEntry を使用します — Channel Plugins を参照してください。完全なentry pointオプションについては、Entry Points を参照してください。

テストして公開する

外部plugin: ClawHubで検証して公開し、その後インストールします:

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

OpenClawは、@myorg/openclaw-my-plugin のような bare package specに対しても、npmより先にClawHubを確認します。リポジトリ内plugin: バンドルされたplugin workspace tree配下に配置します — 自動的に検出されます。

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

Plugin capabilities

1つのpluginは、api オブジェクトを通じて任意の数のcapabilityを登録できます:

Capability	Registration method	詳細ガイド
Text inference (LLM)	`api.registerProvider(...)`	Provider Plugins
CLI inference backend	`api.registerCliBackend(...)`	CLI Backends
Channel / messaging	`api.registerChannel(...)`	Channel Plugins
Speech (TTS/STT)	`api.registerSpeechProvider(...)`	Provider Plugins
Realtime transcription	`api.registerRealtimeTranscriptionProvider(...)`	Provider Plugins
Realtime voice	`api.registerRealtimeVoiceProvider(...)`	Provider Plugins
Media understanding	`api.registerMediaUnderstandingProvider(...)`	Provider Plugins
Image generation	`api.registerImageGenerationProvider(...)`	Provider Plugins
Music generation	`api.registerMusicGenerationProvider(...)`	Provider Plugins
Video generation	`api.registerVideoGenerationProvider(...)`	Provider Plugins
Web fetch	`api.registerWebFetchProvider(...)`	Provider Plugins
Web search	`api.registerWebSearchProvider(...)`	Provider Plugins
Agent tools	`api.registerTool(...)`	以下
Custom commands	`api.registerCommand(...)`	Entry Points
Event hooks	`api.registerHook(...)`	Entry Points
HTTP routes	`api.registerHttpRoute(...)`	Internals
CLI subcommands	`api.registerCli(...)`	Entry Points

完全な登録APIについては、SDK Overview を参照してください。 pluginが独自のGateway RPCメソッドを登録する場合は、 plugin固有のprefixを維持してください。coreのadmin namespace（config.*、 exec.approvals.*、wizard.*、update.*）は予約されたままで、pluginがより狭いscopeを要求しても、常に operator.admin に解決されます。覚えておくべきhook guardのセマンティクス:

before_tool_call: { block: true } は終端であり、より低い優先度のhandlerを停止します。
before_tool_call: { block: false } は未決定として扱われます。
before_tool_call: { requireApproval: true } はagent実行を一時停止し、exec approval overlay、Telegramボタン、Discord interactions、または任意のchannel上の /approve コマンドを通じてユーザーに承認を求めます。
before_install: { block: true } は終端であり、より低い優先度のhandlerを停止します。
before_install: { block: false } は未決定として扱われます。
message_sending: { cancel: true } は終端であり、より低い優先度のhandlerを停止します。
message_sending: { cancel: false } は未決定として扱われます。

/approve コマンドは、境界付きフォールバックでexec approvalとplugin approvalの両方を処理します。exec approval idが見つからない場合、 OpenClawは同じidでplugin approvalを再試行します。plugin approval forwardingは設定の approvals.plugin で個別に構成できます。カスタムapproval処理で同じ境界付きフォールバックケースを検出する必要がある場合は、 approval-expiry文字列を手動で照合するのではなく、openclaw/plugin-sdk/error-runtime の isApprovalNotFoundError を使用してください。詳細は SDK Overview hook decision semantics を参照してください。

Agent toolsの登録

toolsは、LLMが呼び出せる型付き関数です。必須（常に利用可能）または任意（ユーザーのオプトイン）が可能です:

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

ユーザーは設定で任意toolsを有効にします:

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

tool名はcore toolsと衝突してはいけません（衝突したものはスキップされます）
副作用があるtoolsや追加バイナリが必要なtoolsには optional: true を使用してください
ユーザーは tools.allow にplugin idを追加することで、そのpluginのすべてのtoolsを有効にできます

Import規約

必ず、焦点の絞られた openclaw/plugin-sdk/<subpath> パスからimportしてください:

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";

完全なsubpathリファレンスは SDK Overview を参照してください。 plugin内部では、内部importにローカルbarrelファイル（api.ts、runtime-api.ts）を使用してください — SDK path経由で自分自身のpluginをimportしてはいけません。 provider pluginsでは、その継ぎ目が本当に汎用的でない限り、provider固有のhelperはそれらのpackage-root barrelsに置いてください。現在のバンドル例:

Anthropic: Claude stream wrappers と service_tier / beta helpers
OpenAI: provider builders、default-model helpers、realtime providers
OpenRouter: provider builder と onboarding/config helpers

helperが1つのバンドルprovider package内でしか有用でない場合は、それを openclaw/plugin-sdk/* に昇格させるのではなく、その package-root seam上に維持してください。一部の生成済み openclaw/plugin-sdk/<bundled-id> helper seamsは、バンドルpluginの保守と互換性のためにまだ存在しています。たとえば plugin-sdk/feishu-setup や plugin-sdk/zalo-setup です。これらは、新しいサードパーティpluginのデフォルトパターンではなく、予約されたsurfaceとして扱ってください。

提出前チェックリスト

package.json に正しい openclaw メタデータがある

openclaw.plugin.json manifestが存在し、有効である

entry pointが defineChannelPluginEntry または definePluginEntry を使用している

すべてのimportが焦点の絞られた plugin-sdk/<subpath> パスを使用している

内部importが、SDK self-importではなくローカルmoduleを使用している

テストが通る（pnpm test -- <bundled-plugin-root>/my-plugin/）

pnpm check が通る（リポジトリ内plugins）

Beta Release Testing

openclaw/openclaw のGitHub release tagを監視し、Watch > Releases から購読してください。beta tagは v2026.3.N-beta.1 のような形式です。release告知のために、OpenClaw公式Xアカウント @openclaw の通知を有効にすることもできます。
beta tagが出たら、できるだけ早くpluginをそのtagに対してテストしてください。stableまでの時間は通常わずか数時間です。
テスト後、plugin-forum Discord channel内の自分のpluginスレッドに、all good または何が壊れたかを投稿してください。まだスレッドがない場合は作成してください。
何か壊れた場合は、Beta blocker: <plugin-name> - <summary> というタイトルでissueを作成または更新し、beta-blocker labelを付けてください。issueリンクをスレッドに貼ってください。
main に対して fix(<plugin-id>): beta blocker - <summary> というタイトルのPRを開き、PRとDiscordスレッドの両方でissueをリンクしてください。contributorはPRにlabelを付けられないため、titleがmaintainerとautomation向けのPR側シグナルになります。PRのあるblockerはマージされますが、ないものはそのまま出荷される可能性があります。maintainerはbeta testing中にこれらのスレッドを監視しています。
無言はグリーンを意味します。期間を逃した場合、修正はおそらく次のサイクルで反映されます。

次のステップ

Channel Plugins

メッセージングchannel pluginを構築する

Provider Plugins

model provider pluginを構築する

SDK Overview

import mapと登録APIのリファレンス

Runtime Helpers

api.runtime 経由のTTS、search、subagent

Testing

テストユーティリティとパターン

Plugin Manifest

完全なmanifestスキーマリファレンス

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Pluginsの構築

Pluginsの構築

前提条件

どの種類のpluginか

Channel plugin

Provider plugin

Tool / hook plugin

クイックスタート: tool plugin

Plugin capabilities

Agent toolsの登録

Import規約

提出前チェックリスト

Beta Release Testing

次のステップ

Channel Plugins

Provider Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

関連

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Pluginsの構築

​前提条件

​どの種類のpluginか

Channel plugin

Provider plugin

Tool / hook plugin

​クイックスタート: tool plugin

​Plugin capabilities

​Agent toolsの登録

​Import規約

​提出前チェックリスト

​Beta Release Testing

​次のステップ

Channel Plugins

Provider Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

​関連

Pluginsの構築

前提条件

どの種類のpluginか

クイックスタート: tool plugin

Plugin capabilities

Agent toolsの登録

Import規約

提出前チェックリスト

Beta Release Testing

次のステップ

関連