Plugin

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

このページでは、Plugin をインストールし、Gateway を再起動し、ランタイムが それを読み込んだことを確認し、一般的なセットアップ失敗に対処する方法を説明します。コマンドのみの例は Plugin を管理を参照してください。バンドル済み、公式外部、 ソース専用 Plugin の生成済みインベントリについては、 Plugin インベントリを参照してください。

要件

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

クイックスタート

openclaw plugins search "calendar"

# From ClawHub.openclaw plugins install clawhub:<package> # From npm.openclaw plugins install npm:<package> # From git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # From a local development checkout.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 に一致する裸の名前は そのバンドル済みソースを使用します。公式外部 Plugin id に一致する裸の名前は公式パッケージカタログを使用します。 それ以外の裸の仕様は、ローンチ切り替え中は 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 の before_install フックは後で実行され、Plugin フックが読み込まれた OpenClaw プロセス内でのみ実行されるため、 オペレーター所有のインストール判断には代わりに security.installPolicy を使用してください。 非推奨の --dangerously-force-unsafe-install フラグは互換性のために受け付けられますが、no-op です。 インストールポリシーや 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 参照は不活性のままです。古い 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 は、設定で明示的に上書きされない限り、 組み込みの default-on/default-off メタデータに従います。
• plugins.slots.<slot>（memory または contextEngine）は、排他的カテゴリに対して 1 つの Plugin を選択します。 スロット選択は明示的なアクティベーションとして数えられ、その Plugin が本来 opt-in であっても、 選択されたスロット用に強制的に有効化します。plugins.deny と plugins.entries.<id>.enabled: false は引き続きそれをブロックします。
• バンドル済み opt-in Plugin は、設定がその所有サーフェスのいずれかを指定した場合に自動アクティベートできます。 たとえば、provider/model ref、チャネル設定、CLI バックエンド、またはエージェントハーネスランタイムです。
• OpenAI ファミリーの Codex ルーティングは、プロバイダーとランタイム Plugin の境界を分離したままにします。 レガシー Codex model ref は doctor が修復するレガシー設定であり、バンドル済み codex Plugin は、 正規の openai/* agent ref、明示的な agentRuntime.id: "codex"、および レガシー codex/* ref 用の Codex app-server ランタイムを所有します。

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

設定検証が古い Plugin id、allowlist/tool の不一致、またはレガシーのバンドル済み 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 スタイル自動化との互換性のためのものです。

簡単なルール: ハンドラーが優先度、マージセマンティクス、またはブロック/キャンセル動作を必要とする場合は、 型付きフックを使用します。単に 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

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

トラブルシューティング

古い plugin config が、すでに検出できなくなったチャネル plugin をまだ指している場合、config 検証はそのチャネルキーをハードエラーではなく警告に降格するため、Gateway 起動は他のすべてのチャネルを引き続き提供できます。古い plugin とチャネルのエントリを削除するには openclaw doctor --fix を実行してください。古い plugin の証拠がない不明なチャネルキーは引き続き検証に失敗するため、入力ミスは見える状態のままになります。

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

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

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

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

Docker インストールでは、公式イメージは node (uid 1000) として実行されるため、ホストに bind mount された OpenClaw config と workspace ディレクトリは通常 uid 1000 が所有している必要があります。

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

意図的に OpenClaw を root として実行している場合は、managed plugin ルートを root 所有権に修復してください。

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

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

遅い plugin ツールセットアップ

agent ターンがツール準備中に停止しているように見える場合は、trace ログを有効化し、plugin tool factory のタイミング行を確認してください。

openclaw config set logging.level traceopenclaw logs --follow

次を探してください。

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

サマリーには、合計 factory 時間と最も遅い plugin tool factories が一覧表示され、plugin id、宣言された tool 名、結果の形、tool が optional かどうかが含まれます。単一の factory が 1 秒以上かかる場合、または plugin tool factory prep の合計が 5 秒以上かかる場合、遅い行は warnings に昇格されます。

OpenClaw は、同じ effective request context で繰り返し解決する場合、成功した plugin tool factory の結果をキャッシュします。キャッシュキーには、effective runtime config、workspace と agent id、sandbox policy、browser settings、delivery context、requester identity、ownership state が含まれるため、これらの trusted fields に依存する factories は context が変わると再実行されます。タイミングが高いままの場合、その plugin は tool definitions を返す前に高コストな処理を行っている可能性があります。

1 つの plugin がタイミングの大半を占める場合は、その runtime registrations を調べてください。

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

その後、その plugin を更新、再インストール、または無効化してください。Plugin authors は、tool factory の内部で行うのではなく、高コストな dependency loading を tool execution path の後ろに移す必要があります。

依存関係ルート、package metadata validation、registry records、startup reload behavior、legacy cleanup については、Plugin dependency resolution を参照してください。

関連

• Manage plugins - list、install、update、uninstall、publish のコマンド例
• openclaw plugins - 完全な CLI リファレンス
• Plugin inventory - 生成された bundled および external plugin 一覧
• Plugin reference - 生成された plugin ごとのリファレンスページ
• Community plugins - ClawHub discovery と docs PR policy
• Plugin dependency resolution - install roots、registry records、runtime boundaries
• Building plugins - native plugin authoring guide
• Plugin SDK overview - runtime registration、hooks、API fields
• Plugin manifest - manifest と package metadata