Plugin

Plugin は、チャネル、モデルプロバイダー、エージェントハーネス、ツール、 Skills、音声、リアルタイム文字起こし、ボイス、メディア理解、生成、 Web フェッチ、Web 検索、その他のランタイム機能で OpenClaw を拡張します。

Plugin をインストールし、Gateway を再起動し、ランタイムがそれを読み込んだことを検証し、 一般的なセットアップ失敗を切り分ける場合は、このページを使用します。コマンドのみの 例については、Plugin を管理するを参照してください。バンドル済み、公式外部、 ソース専用 Plugin の完全な生成済みインベントリについては、 Plugin インベントリを参照してください。

要件

Plugin をインストールする前に、次を確認してください。

• openclaw CLI が利用可能な OpenClaw チェックアウトまたはインストール
• ClawHub、npm、git ホストなど、選択したソースへのネットワークアクセス
• その Plugin のセットアップドキュメントで指定されている、Plugin 固有の認証情報、設定キー、またはオペレーティングシステムのツール
• チャネルを提供する Gateway をリロードまたは再起動する権限

クイックスタート

openclaw plugins search "calendar"

# ClawHub から。openclaw plugins install clawhub:<package> # npm から。openclaw plugins install npm:<package> # git から。openclaw plugins install git:github.com/<owner>/<repo>@<ref> # ローカル開発チェックアウトから。openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

設定

インストール元を選ぶ

裸のパッケージ指定には特別な互換性動作があります。裸の名前がバンドル済み Plugin id と一致する場合、 OpenClaw はそのバンドル済みソースを使用します。公式外部 Plugin id と一致する場合、 OpenClaw は公式パッケージカタログを使用します。その他の通常の裸のパッケージ指定は、 ローンチ切り替え期間中は npm 経由でインストールされます。バンドル済み Plugin と一致する生の @openclaw/* パッケージ指定も、npm フォールバックの前にバンドルコピーへ解決されます。 イメージ所有のバンドルコピーではなく外部 npm パッケージを意図的に使用したい場合は、 npm:@openclaw/<plugin>@<version> を使用します。決定論的なソース選択が必要な場合は、 clawhub:、npm:、git:、または npm-pack: を使用してください。完全なコマンド契約については、 openclaw pluginsを参照してください。

npm インストールでは、ピン留めされていないパッケージ指定と @latest は、この OpenClaw ビルドとの互換性を示す最新の安定パッケージを選択します。npm の 現在の latest リリースがより新しい openclaw.compat.pluginApi または openclaw.install.minHostVersion を宣言している場合、OpenClaw は古い安定パッケージバージョンをスキャンし、 適合する最新のものをインストールします。正確なバージョンと @beta などの明示的なチャネルタグは、 選択されたパッケージに固定されたままとなり、互換性がない場合は失敗します。

オペレーターインストールポリシー

Plugin のインストールまたは更新を進める前に、信頼済みのローカルポリシーコマンドを実行するには security.installPolicy を設定します。ポリシーはメタデータとステージ済みソースパスを受け取り、 インストールを許可またはブロックできます。これは CLI と Gateway バックの Plugin インストール/更新パスを対象にします。Plugin の before_install フックは、 Plugin フックが読み込まれている OpenClaw プロセス内でのみ後から実行されるため、オペレーター所有のインストール判断には security.installPolicy を使用してください。非推奨の --dangerously-force-unsafe-install フラグは互換性のために受け付けられますが、 インストールポリシーや OpenClaw の組み込み Plugin 依存関係 denylist はバイパスしません。

Skills と Plugin の両方で使用される共有 security.installPolicy exec スキーマについては、Skills 設定 を参照してください。

Plugin ポリシーを設定する

一般的な Plugin 設定の形は次のとおりです。

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

主なポリシールール:

• plugins.enabled: false はすべての Plugin を無効化し、Plugin の検出/読み込み作業をスキップします。 これが有効な間、古い Plugin 参照は不活性です。古い id を削除したい場合は、 doctor cleanup を実行する前に Plugin を再度有効化してください。
• plugins.deny は allow と Plugin ごとの有効化より優先されます。
• plugins.allow は排他的な allowlist です。allowlist の外にある Plugin 所有ツールは、 tools.allow に "*" が含まれていても利用できません。
• plugins.entries.<id>.enabled: false は、その設定を保持したまま 1 つの Plugin を無効化します。
• plugins.load.paths は明示的なローカル Plugin ファイルまたはディレクトリを追加します。管理対象の plugins install ローカルパスは Plugin ディレクトリまたはアーカイブである必要があります。スタンドアロン Plugin ファイルには plugins.load.paths を使用してください。
• ワークスペース由来の Plugin はデフォルトで無効です。ローカルワークスペースコードを使用する前に、明示的に有効化するか allowlist に追加してください。
• バンドル済み Plugin は、設定で明示的に上書きされない限り、組み込みのデフォルトオン/デフォルトオフメタデータに従います。
• plugins.slots.<slot> は、メモリやコンテキストエンジンなどの排他的カテゴリに 1 つの Plugin を選択します。 スロット選択は明示的なアクティベーションとして数えられるため、選択された Plugin をそのスロットに対して強制的に有効化します。 そうでなければ opt-in になる場合でも読み込めます。plugins.deny と plugins.entries.<id>.enabled: false は引き続きブロックします。
• バンドル済み opt-in Plugin は、プロバイダー/モデル ref、チャネル設定、CLI バックエンド、エージェントハーネスランタイムなど、 自身が所有する面のいずれかを設定が指定している場合、自動アクティブ化できます。
• OpenAI ファミリー Codex ルーティングは、プロバイダーとランタイム Plugin の境界を分離したままにします。 レガシー Codex モデル ref は doctor によって修復されるレガシー設定であり、バンドル済みの codex Plugin は、正規の openai/* エージェント ref、明示的な agentRuntime.id: "codex"、およびレガシー codex/* ref の Codex app-server ランタイムを所有します。

plugins.allow が未設定で、非バンドル Plugin がワークスペースまたはグローバル Plugin ルートから自動検出される場合、 起動ログに plugins.allow is empty; discovered non-bundled plugins may auto-load: ... と表示されます。この警告には検出された Plugin id が含まれ、短いリストの場合は最小限の plugins.allow スニペットも含まれます。信頼済み Plugin を openclaw.json にコピーする前に、一覧表示された Plugin id を使って openclaw plugins list --enabled --verbose または openclaw plugins inspect <id> を実行してください。同じ信頼ピン留めの ガイダンスは、診断が Plugin が without install/load-path provenance で読み込まれたと示す場合にも適用されます。その Plugin id を inspect してから、 信頼済み id を plugins.allow にピン留めするか、信頼済みソースから再インストールして OpenClaw がインストール来歴を記録できるようにしてください。

設定検証で古い Plugin id、allowlist/ツールの不一致、またはレガシーなバンドル済み Plugin パスが報告された場合は、 openclaw doctor または openclaw doctor --fix を実行してください。

Plugin 形式を理解する

OpenClaw は 2 つの Plugin 形式を認識します。

どちらの形式も、openclaw plugins list、openclaw plugins inspect、 openclaw plugins enable、openclaw plugins disable に表示されます。バンドル互換性の境界については Plugin バンドルを、ネイティブ Plugin の作成については Plugin の構築を参照してください。

Plugin フック

Plugin はランタイムでフックを登録できますが、役割の異なる 2 つの API があります。

• ランタイムライフサイクルフックには、api.on(...) 経由の型付きフックを使用します。これは、 ミドルウェア、ポリシー、メッセージ書き換え、プロンプト形成、ツール制御に推奨される面です。
• フック で説明されている内部フックシステムに参加したい場合にのみ、 api.registerHook(...) を使用します。これは主に、大まかなコマンド/ライフサイクルの副作用と、 既存の HOOK スタイル自動化との互換性のためのものです。

簡単なルール:

• ハンドラーに優先度、マージセマンティクス、またはブロック/キャンセル動作が必要な場合は、 型付き Plugin フックを使用します。
• ハンドラーが command:new、command:reset、message:sent、 または類似の大まかなイベントに反応するだけなら、api.registerHook(...) で問題ありません。

Plugin 管理の内部フックは、openclaw hooks list に plugin:<id> として表示されます。openclaw hooks からそれらを有効化または無効化することはできません。 代わりに Plugin を有効化または無効化してください。

アクティブな Gateway を検証する

openclaw plugins list と単純な openclaw plugins inspect は、コールドな設定、 マニフェスト、レジストリ状態を読み取ります。すでに実行中の Gateway が同じ Plugin コードを インポートしていることは証明しません。

Plugin がインストール済みに見えるのに、ライブチャットのトラフィックで使われない場合:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

管理対象 Gateway は、Plugin ソースを変更する Plugin のインストール、更新、アンインストール後に 自動で再起動します。VPS またはコンテナインストールでは、手動再起動の対象が、ラッパーや スーパーバイザーだけではなく、チャンネルにサービスを提供している実際の openclaw gateway run 子プロセスであることを確認してください。

トラブルシューティング

古い Plugin 設定が、すでに検出できないチャンネル Plugin をまだ指定している場合、 Gateway 起動は、他のすべてのチャンネルをブロックする代わりに、その Plugin が裏付けるチャンネルをスキップします。 openclaw doctor --fix を実行して、古い Plugin とチャンネルのエントリを削除してください。 古い Plugin の証拠がない未知のチャンネルキーは引き続き検証に失敗するため、入力ミスは見えるままになります。

意図的なチャンネル置き換えでは、優先する Plugin は channelConfigs.<channel-id>.preferOver で、レガシーまたは低優先度の Plugin id を宣言する必要があります。両方の Plugin が明示的に有効化されている場合、OpenClaw はその要求を保持し、 1 つの所有者を黙って選ぶ代わりに、重複したチャンネルまたはツールの診断を報告します。

インストール済みパッケージが requires compiled runtime output for TypeScript entry ... と報告する場合、そのパッケージは OpenClaw がランタイムで必要とする JavaScript ファイルなしで 公開されています。公開者がコンパイル済み JavaScript を出荷した後に更新または再インストールするか、 それまでは Plugin を無効化/アンインストールしてください。

ブロックされた Plugin パス所有権

Plugin 診断に blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) と表示され、その後に設定検証で plugin present but blocked が続く場合、OpenClaw は Plugin ファイルの所有者が、それを読み込んでいるプロセスとは異なる Unix ユーザーであることを検出しています。 Plugin 設定はそのままにして、ファイルシステムの所有権を修正するか、状態ディレクトリを所有する同じユーザーとして OpenClaw を実行してください。

Docker インストールでは、公式イメージは node (uid 1000) として実行されるため、 ホストでバインドマウントされた OpenClaw 設定ディレクトリとワークスペースディレクトリは通常、 uid 1000 に所有されている必要があります:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

意図的に OpenClaw を root として実行している場合は、代わりに管理対象 Plugin ルートを root 所有権に修復してください:

sudo chown -R root:root /path/to/openclaw-config/npm

所有権を修正した後、openclaw doctor --fix または openclaw plugins registry --refresh を再実行し、永続化された Plugin レジストリが 修復済みファイルと一致するようにしてください。

遅い Plugin ツール設定

エージェントターンがツールの準備中に停止しているように見える場合は、トレースログを有効化し、 Plugin ツールファクトリのタイミング行を確認してください:

openclaw config set logging.level traceopenclaw logs --follow

次を探してください:

[trace:plugin-tools] factory timings ...

概要には、Plugin id、宣言されたツール名、結果の形、ツールが任意かどうかを含め、 合計ファクトリ時間と最も遅い Plugin ツールファクトリが一覧表示されます。 単一のファクトリが少なくとも 1s かかる場合、または Plugin ツールファクトリ準備の合計が少なくとも 5s かかる場合、 遅い行は警告に昇格されます。

OpenClaw は、同じ有効な要求コンテキストで繰り返し解決される成功した Plugin ツールファクトリ結果をキャッシュします。 キャッシュキーには、有効なランタイム設定、ワークスペース、エージェント/セッション id、サンドボックスポリシー、 ブラウザー設定、配信コンテキスト、要求者の ID、所有権状態が含まれるため、これらの信頼済みフィールドに依存する ファクトリは、コンテキストが変わると再実行されます。タイミングが高いままの場合、その Plugin はツール定義を返す前に 高コストな処理を行っている可能性があります。

1 つの Plugin がタイミングを支配している場合は、そのランタイム登録を調べてください:

openclaw plugins inspect <plugin-id> --runtime --json

その後、その Plugin を更新、再インストール、または無効化してください。Plugin 作者は、 高コストな依存関係の読み込みを、ツールファクトリ内で行うのではなく、ツール実行パスの背後へ移動する必要があります。

依存関係ルート、パッケージメタデータ検証、レジストリレコード、起動時の再読み込み動作、 レガシークリーンアップについては、Plugin 依存関係解決を参照してください。

関連

• Plugin を管理 - list、install、update、uninstall、publish のコマンド例
• openclaw plugins - 完全な CLI リファレンス
• Plugin インベントリ - 生成されたバンドル済みおよび外部 Plugin 一覧
• Plugin リファレンス - 生成された Plugin ごとのリファレンスページ
• コミュニティ Plugin - ClawHub 検出と docs PR ポリシー
• Plugin 依存関係解決 - インストールルート、レジストリレコード、ランタイム境界
• Plugin の構築 - ネイティブ Plugin 作成ガイド
• Plugin SDK 概要 - ランタイム登録、フック、API フィールド
• Plugin マニフェスト - マニフェストとパッケージメタデータ