34 KiB
| read_when | sidebarTitle | summary | title | x-i18n | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Plugins | `openclaw plugins` の CLI リファレンス（list、install、marketplace、uninstall、enable/disable、doctor） | Plugin |
|
Gateway Plugin、フックパック、互換バンドルを管理します。
Pluginのインストール、有効化、トラブルシューティングのエンドユーザー向けガイド。 インストール、一覧表示、更新、アンインストール、公開のクイック例。 バンドル互換性モデル。 マニフェストフィールドと設定スキーマ。 Pluginインストールのセキュリティ強化。コマンド
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
低速なインストール、検査、アンインストール、またはレジストリ更新の調査では、
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 を指定してコマンドを実行します。トレースはフェーズごとの所要時間を
stderr に書き込み、JSON出力を解析可能なままにします。デバッグを参照してください。
ネイティブOpenClaw Pluginは、インラインJSON Schema（空でも configSchema）を含む openclaw.plugin.json を同梱する必要があります。互換バンドルは、代わりに独自のバンドルマニフェストを使用します。
plugins list は Format: openclaw または Format: bundle を表示します。詳細な一覧/info出力では、バンドルのサブタイプ（codex、claude、または cursor）と、検出されたバンドル機能も表示されます。
インストール
openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install <package> # npm by default
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install git:github.com/<owner>/<repo> # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force # overwrite existing install
openclaw plugins install <package> --pin # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # local path
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
plugins search は、インストール可能なPluginパッケージをClawHubに問い合わせ、
インストール可能なパッケージ名を出力します。検索対象はコードPluginとバンドルPluginのパッケージであり、
Skillsではありません。ClawHub Skillsには openclaw skills search を使用してください。
インストール中に設定が無効な場合、`plugins install` は通常フェイルクローズし、先に `openclaw doctor --fix` を実行するよう通知します。Gateway起動時およびホットリロード時には、無効なPlugin設定は他の無効な設定と同様にフェイルクローズします。`openclaw doctor --fix` は無効なPluginエントリを隔離できます。文書化されている唯一のインストール時例外は、`openclaw.install.allowInvalidConfigRecovery` に明示的にオプトインしたPlugin向けの限定的なバンドル済みPlugin復旧経路です。
すでにインストール済みのPlugin idに対して `plugins install` を実行すると、OpenClawは停止し、通常のアップグレードには `plugins update <id-or-npm-spec>` を、現在のインストールを別のソースから本当に上書きする場合には `plugins install <package> --force` を案内します。
このCLIフラグはPluginのインストール/更新フローに適用されます。GatewayバックのSkill依存関係インストールでは対応する `dangerouslyForceUnsafeInstall` リクエストオーバーライドを使用します。一方、`openclaw skills install` は別個のClawHub Skillダウンロード/インストールフローのままです。
ClawHubで公開したPluginがレジストリスキャンによってブロックされる場合は、[ClawHub](/ja-JP/tools/clawhub)の公開者向け手順を使用してください。
Npm specは**レジストリ専用**です（パッケージ名 + 任意の**正確なバージョン**または**dist-tag**）。Git/URL/file specおよびsemver範囲は拒否されます。依存関係のインストールは、シェルにグローバルnpmインストール設定がある場合でも、安全のため `--ignore-scripts` 付きでプロジェクトローカルに実行されます。
npm解決を明示したい場合は `npm:<package>` を使用してください。裸のパッケージspecも、ローンチ移行期間中はnpmから直接インストールされます。
裸のspecと `@latest` は安定版トラックに留まります。`2026.5.3-1` のようなOpenClawの日付付き修正版は、このチェックでは安定版リリースです。npmがそれらのいずれかをプレリリースに解決した場合、OpenClawは停止し、`@beta`/`@rc` のようなプレリリースタグ、または `@1.2.3-beta.4` のような正確なプレリリースバージョンで明示的にオプトインするよう求めます。
裸のインストールspecが公式Plugin id（たとえば `diffs`）と一致する場合、OpenClawはカタログエントリを直接インストールします。同じ名前のnpmパッケージをインストールするには、明示的なスコープ付きspec（たとえば `@scope/diffs`）を使用してください。
Gitインストールは一時ディレクトリにクローンし、指定されたrefがある場合はそれをチェックアウトしてから、通常のPluginディレクトリインストーラーを使用します。つまり、マニフェスト検証、危険コードスキャン、パッケージマネージャーのインストール作業、インストールレコードはnpmインストールと同じように動作します。記録されたgitインストールには、ソースURL/refと解決済みコミットが含まれるため、後で `openclaw plugins update` がソースを再解決できます。
gitからインストールした後、GatewayメソッドやCLIコマンドなどのランタイム登録を確認するには、`openclaw plugins inspect <id> --runtime --json` を使用します。Pluginが `api.registerCli` でCLIルートを登録した場合は、たとえば `openclaw demo-plugin ping` のように、そのコマンドをOpenClawルートCLI経由で直接実行します。
Claude marketplaceインストールもサポートされています。
ClawHubインストールは、明示的な clawhub:<package> ロケーターを使用します。
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
裸のnpmセーフなPlugin specは、ローンチ移行期間中はデフォルトでnpmからインストールされます。
openclaw plugins install openclaw-codex-app-server
npm専用解決を明示するには npm: を使用します。
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
OpenClawは、インストール前に公開されているPlugin API / 最小Gateway互換性を確認します。選択されたClawHubバージョンがClawPackアーティファクトを公開している場合、OpenClawはバージョン付きnpm-pack .tgz をダウンロードし、ClawHubダイジェストヘッダーとアーティファクトダイジェストを検証してから、通常のアーカイブ経路でインストールします。ClawPackメタデータのない古いClawHubバージョンは、引き続き従来のパッケージアーカイブ検証経路でインストールされます。記録されたインストールは、後の更新のために、ClawHubソースメタデータ、アーティファクト種別、npm integrity、npm shasum、tarball名、ClawPackダイジェスト情報を保持します。
バージョンなしのClawHubインストールは、openclaw plugins update が新しいClawHubリリースを追跡できるよう、バージョンなしの記録済みspecを保持します。clawhub:pkg@1.2.3 や clawhub:pkg@beta のような明示的なバージョンまたはタグセレクターは、そのセレクターに固定されたままです。
Marketplace省略記法
Claudeのローカルレジストリキャッシュ ~/.claude/plugins/known_marketplaces.json にmarketplace名が存在する場合は、plugin@marketplace 省略記法を使用します。
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
marketplaceソースを明示的に渡したい場合は、--marketplace を使用します。
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
ローカルパスとアーカイブについて、OpenClaw は次を自動検出します。
- ネイティブ OpenClaw Plugin（
openclaw.plugin.json） - Codex 互換バンドル（
.codex-plugin/plugin.json） - Claude 互換バンドル（
.claude-plugin/plugin.jsonまたはデフォルトの Claude コンポーネントレイアウト） - Cursor 互換バンドル（
.cursor-plugin/plugin.json）
一覧
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
plugins list --json には、package.json の dependencies と optionalDependencies から得た各 Plugin の dependencyStatus が含まれます。OpenClaw は、それらのパッケージ名が Plugin の通常の Node node_modules 参照パス上に存在するかを確認します。Plugin ランタイムコードのインポート、パッケージマネージャーの実行、欠落した依存関係の修復は行いません。
plugins search はリモートの ClawHub カタログ検索です。ローカル状態の検査、config の変更、パッケージのインストール、Plugin ランタイムコードの読み込みは行いません。検索結果には、ClawHub パッケージ名、ファミリー、チャネル、バージョン、概要、および openclaw plugins install clawhub:<package> のようなインストールヒントが含まれます。
パッケージ化された Docker イメージ内でバンドル Plugin を扱う場合は、Plugin ソースディレクトリを、対応するパッケージ済みソースパス（例: /app/extensions/synology-chat）の上に bind-mount します。OpenClaw は /app/dist/extensions/synology-chat より前に、そのマウントされたソースオーバーレイを検出します。単にコピーされたソースディレクトリは不活性なままなので、通常のパッケージ済みインストールは引き続きコンパイル済み dist を使います。
ランタイム hook のデバッグでは、次を使用します。
openclaw plugins inspect <id> --runtime --jsonは、モジュール読み込み検査パスから登録済み hook と診断を表示します。ランタイム検査は依存関係をインストールしません。レガシー依存関係状態の整理や、config で参照されている欠落したダウンロード可能 Plugin の復旧にはopenclaw doctor --fixを使います。openclaw gateway status --deep --require-rpcは、到達可能な Gateway、サービス/プロセスのヒント、config パス、RPC ヘルスを確認します。- 非バンドルの会話 hook（
llm_input、llm_output、before_agent_finalize、agent_end）にはplugins.entries.<id>.hooks.allowConversationAccess=trueが必要です。
ローカルディレクトリのコピーを避けるには --link を使います（plugins.load.paths に追加されます）。
openclaw plugins install -l ./my-plugin
npm インストールで --pin を使うと、デフォルト動作をピン留めなしのままにしつつ、解決された正確な spec（name@version）を管理対象 Plugin インデックスに保存できます。
Plugin インデックス
Plugin インストールメタデータは機械管理の状態であり、ユーザー config ではありません。インストールと更新は、アクティブな OpenClaw state ディレクトリ配下の plugins/installs.json に書き込みます。そのトップレベルの installRecords マップは、壊れた Plugin マニフェストや欠落した Plugin マニフェストのレコードを含む、インストールメタデータの永続的なソースです。plugins 配列は、マニフェストから派生したコールドレジストリキャッシュです。このファイルには編集禁止の警告が含まれ、openclaw plugins update、アンインストール、診断、コールド Plugin レジストリで使用されます。
OpenClaw が config 内に出荷済みのレガシー plugins.installs レコードを見つけると、それらを Plugin インデックスへ移動し、config キーを削除します。どちらかの書き込みが失敗した場合、インストールメタデータが失われないように config レコードは保持されます。
アンインストール
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
uninstall は、plugins.entries、永続化された Plugin インデックス、Plugin 許可/拒否リストエントリ、および該当する場合はリンクされた plugins.load.paths エントリから Plugin レコードを削除します。--keep-files が設定されていない限り、アンインストールは、OpenClaw の Plugin extensions ルート内にある追跡対象の管理インストールディレクトリも削除します。Active Memory Plugin の場合、メモリスロットは memory-core にリセットされます。
更新
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
更新は、管理対象 Plugin インデックス内の追跡対象 Plugin インストールと、hooks.internal.installs 内の追跡対象 hook-pack インストールに適用されます。
npm インストールでは、dist-tag または正確なバージョンを含む明示的な npm パッケージ spec を渡すこともできます。OpenClaw はそのパッケージ名を追跡対象の Plugin レコードに解決し直し、そのインストール済み Plugin を更新して、今後の id ベース更新用に新しい npm spec を記録します。
バージョンやタグなしで npm パッケージ名を渡した場合も、追跡対象の Plugin レコードに解決されます。Plugin が正確なバージョンにピン留めされており、レジストリのデフォルトリリースラインへ戻したい場合に使います。
保存された integrity ハッシュが存在し、取得したアーティファクトハッシュが変わった場合、OpenClaw はそれを npm アーティファクトドリフトとして扱います。対話型の `openclaw plugins update` コマンドは、期待されるハッシュと実際のハッシュを出力し、続行前に確認を求めます。非対話型の更新ヘルパーは、呼び出し元が明示的な継続ポリシーを指定しない限り fail closed します。
検査
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
Inspect は、デフォルトでは Plugin ランタイムをインポートせずに、ID、読み込み状態、ソース、マニフェスト機能、ポリシーフラグ、診断、インストールメタデータ、バンドル機能、および検出された MCP または LSP サーバーサポートを表示します。--runtime を追加すると、Plugin モジュールを読み込み、登録済み hook、tools、commands、services、gateway methods、HTTP routes を含めます。ランタイム検査は欠落している Plugin 依存関係を直接報告します。インストールと修復は openclaw plugins install、openclaw plugins update、openclaw doctor --fix に留まります。
Plugin 所有の CLI コマンドは、ルートの openclaw コマンドグループとしてインストールされます。inspect --runtime が cliCommands 配下にコマンドを表示したら、openclaw <command> ... として実行します。たとえば、demo-git を登録する Plugin は openclaw demo-git ping で検証できます。
各 Plugin は、ランタイムで実際に登録する内容に基づいて分類されます。
- plain-capability — 1 つの capability type（例: provider-only Plugin）
- hybrid-capability — 複数の capability type（例: text + speech + images）
- hook-only — hook のみで、capabilities や surfaces なし
- non-capability — tools/commands/services はあるが capabilities なし
capability モデルの詳細は Plugin 形状 を参照してください。
`--json` フラグは、スクリプト作成と監査に適した機械可読レポートを出力します。`inspect --all` は、shape、capability kinds、compatibility notices、bundle capabilities、hook summary 列を含む全体テーブルを表示します。`info` は `inspect` のエイリアスです。Doctor
openclaw plugins doctor
doctor は、Plugin 読み込みエラー、マニフェスト/検出診断、互換性通知を報告します。すべてクリーンな場合は No plugin issues detected. を出力します。
設定済み Plugin がディスク上に存在するものの、ローダーのパス安全性チェックでブロックされている場合、config バリデーションは Plugin エントリを保持し、present but blocked として報告します。plugins.entries.<id> や plugins.allow config を削除するのではなく、パス所有権や world-writable 権限など、直前の blocked-plugin 診断を修正してください。
register/activate export の欠落などのモジュール形状エラーでは、OPENCLAW_PLUGIN_LOAD_DEBUG=1 を指定して再実行すると、診断出力にコンパクトな export-shape サマリーが含まれます。
レジストリ
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json
ローカル Plugin レジストリは、インストール済み Plugin の ID、有効化、ソースメタデータ、コントリビューション所有権に関する OpenClaw の永続化されたコールド読み取りモデルです。通常の起動、プロバイダー所有者ルックアップ、チャネル設定分類、Plugin インベントリは、Plugin ランタイムモジュールをインポートせずにこれを読み取れます。
plugins registry を使用して、永続化されたレジストリが存在するか、最新か、古くなっているかを調べます。--refresh を使用すると、永続化された Plugin インデックス、設定ポリシー、マニフェスト/package メタデータから再構築できます。これは修復パスであり、ランタイム有効化パスではありません。
openclaw doctor --fix は、レジストリ周辺の managed npm ドリフトも修復します。managed Plugin npm ルート配下の孤立または復旧された @openclaw/* package が bundled Plugin をシャドーしている場合、doctor はその古い package を削除し、レジストリを再構築して、起動時に bundled マニフェストに対して検証されるようにします。
マーケットプレイス
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
マーケットプレイス一覧は、ローカルのマーケットプレイスパス、marketplace.json パス、owner/repo のような GitHub 短縮表記、GitHub リポジトリ URL、または git URL を受け付けます。--json は、解決済みのソースラベルに加えて、解析済みのマーケットプレイスマニフェストと Plugin エントリを出力します。