openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh ja-JP translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-17 04:47:49 +00:00
parent eca2006d9d
commit 1a1e84d5ac
5 changed files with 1230 additions and 1281 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

277
docs/ja-JP/concepts/qa-e2e-automation.md
View File

@ -1,53 +1,52 @@
---
read_when:
- qa-labまたはqa-channelの拡張
- リポジトリ連携のQAシナリオの追加
- Gatewayダッシュボードを中心とした、より高い現実性を備えたQA自動化の構築
summary: qa-lab、qa-channel、シード済みシナリオ、およびプロトコルレポートのための非公開QA自動化の構成
- リポジトリ連動のQAシナリオを追加する
- Gatewayダッシュボードを中心に、より高い現実性のQA自動化を構築する
summary: qa-lab、qa-channel、シード済みシナリオ、プロトコルレポート向けの非公開QA自動化の構成
title: QA E2E自動化
x-i18n:
generated_at: "2026-04-16T21:51:19Z"
generated_at: "2026-04-17T04:43:57Z"
model: gpt-5.4
provider: openai
source_hash: 7deefda1c90a0d2e21e2155ffd8b585fb999e7416bdbaf0ff57eb33ccc063afc
source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# QA E2E自動化
非公開QAスタックは、単一のユニットテストよりも現実的で、
チャネルの形に近い方法でOpenClawを検証することを目的としています。
非公開のQAスタックは、単一のユニットテストよりも現実的で、
チャネルに近い形でOpenClawを検証することを目的としています。
現在の構成要素:
- `extensions/qa-channel`: DM、チャネル、スレッド、
リアクション、編集、削除の各面を備えた合成メッセージチャネル。
リアクション、編集、削除の操作面を備えた合成メッセージチャネル。
- `extensions/qa-lab`: トランスクリプトの観察、
受信メッセージの注入、Markdownレポートのエクスポートのための
受信メッセージの注入、Markdownレポートのエクスポートを行うための
デバッガUIとQAバス。
- `qa/`: キックオフタスクとベースラインQA
シナリオのための、リポジトリ連携のシードアセット。
シナリオのための、リポジトリ連動のシードアセット。
現在のQAオペレーターフローは、2ペインのQAサイトです:
- 左: エージェントを表示するGatewayダッシュボード（Control UI）。
- 右: Slack風のトランスクリプトとシナリオプランを表示するQA Lab。
- 右: Slack風のトランスクリプトとシナリオ計画を表示するQA Lab。
実行するには:
実行方法:
```bash
pnpm qa:lab:up
```
これによりQAサイトがビルドされ、Dockerベースのgatewayレーンが起動し、
QA Labページが公開されます。そこでは、オペレーターまたは自動化ループが
エージェントにQAミッションを与え、実際のチャネル動作を観察し、
何が機能したか、失敗したか、あるいはブロックされたままだったかを
記録できます。
オペレーターまたは自動化ループがエージェントにQAミッションを与え、
実際のチャネル動作を観察し、何が機能し、何が失敗し、
何がブロックされたままだったかを記録できるQA Labページが公開されます。
Dockerイメージを毎回再ビルドせずに、より高速にQA Lab UIを反復開発するには、
バインドマウントされたQA Labバンドルでスタックを起動します:
Dockerイメージを毎回再ビルドせずにQA Lab UIをより高速に反復するには、
QA Labバンドルをバインドマウントしてスタックを起動します:
```bash
pnpm openclaw qa docker-build-image
@ -56,29 +55,28 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` は、Dockerサービスを事前ビルド済みイメージ上で維持し、
`qa:lab:up:fast` は、Dockerサービスを事前ビルド済みイメージ上で維持しつつ、
`extensions/qa-lab/web/dist` を `qa-lab` コンテナにバインドマウントします。
`qa:lab:watch` は変更時にそのバンドルを再ビルドし、QA Labの
アセットハッシュが変わるとブラウザが自動リロードされます。
`qa:lab:watch` は変更時にそのバンドルを再ビルドし、
QA Labアセットのハッシュが変わるとブラウザは自動リロードされます。
実際のトランスポートを使うMatrixスモークレーンを実行するには、次を実行します:
実際のトランスポートを使うMatrixスモークレーンを実行するには、次を使用します:
```bash
pnpm openclaw qa matrix
```
このレーンは、Docker内に使い捨てのTuwunel homeserverを用意し、
一時的なドライバー、SUT、オブザーバーのユーザーを登録し、
1つのプライベートルームを作成した後、QA gateway child内で
実際のMatrix Pluginを実行します。ライブトランスポートレーンは、
対象トランスポートに限定されたchild configを維持するため、
child config内で `qa-channel` なしにMatrixが実行されます。
構造化されたレポートアーティファクトと、結合されたstdout/stderrログを、
選択したMatrix QA出力ディレクトリに書き込みます。
外側の `scripts/run-node.mjs` のビルド/ランチャー出力も記録するには、
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` をリポジトリローカルのログファイルに設定します。
このレーンは、Docker内に使い捨てのTuwunelホームサーバーを用意し、
一時的なdriver、SUT、observerユーザーを登録し、1つのプライベートルームを作成してから、
QA gateway child内で実際のMatrix Pluginを実行します。ライブトランスポートレーンは、
child configをテスト対象のトランスポートに限定した状態に保つため、
Matrixはchild config内で`qa-channel`なしで動作します。
構造化レポートアーティファクトと、stdout/stderrを結合したログは、
選択したMatrix QA出力ディレクトリに書き込まれます。
外側の `scripts/run-node.mjs` のビルド/ランチャー出力も取得するには、
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` をリポジトリ内のログファイルに設定してください。
実際のトランスポートを使うTelegramスモークレーンを実行するには、次を実行します:
実際のトランスポートを使うTelegramスモークレーンを実行するには、次を使用します:
```bash
pnpm openclaw qa telegram
@ -86,121 +84,141 @@ pnpm openclaw qa telegram
このレーンは、使い捨てサーバーを用意する代わりに、
1つの実在するプライベートTelegramグループを対象にします。
これには `OPENCLAW_QA_TELEGRAM_GROUP_ID`、
必要なのは `OPENCLAW_QA_TELEGRAM_GROUP_ID`、
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要であり、
さらに同じプライベートグループ内に2つの異なるボットが必要です。
SUTボットにはTelegramユーザー名が必要であり、
ボット間観測は、両方のボットで `@BotFather` の
Bot-to-Bot Communication Mode が有効になっていると最適に機能します。
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`、
および同じプライベートグループ内にある2つの異なるボットです。
SUTボットにはTelegramユーザー名が必要で、
ボット間観察は、両方のボットで `@BotFather` の
Bot-to-Bot Communication Mode を有効にしていると最も良好に動作します。
ライブトランスポートレーンは現在、各レーンが独自のシナリオリスト形状を
作るのではなく、より小さな1つの共通契約を共有します:
ライブトランスポートレーンは現在、それぞれが独自のシナリオリスト形状を考案するのではなく、
より小さな1つの共通契約を共有します:
`qa-channel` は、引き続き幅広い合成プロダクト動作スイートであり、
`qa-channel` は引き続き幅広い合成プロダクト動作スイートであり、
ライブトランスポートのカバレッジマトリクスには含まれません。
| レーン | Canary | メンションゲーティング | 許可リストブロック | トップレベル返信 | 再起動後の復帰 | スレッド追従 | スレッド分離 | リアクション観測 | helpコマンド |
| レーン | Canary | メンションゲーティング | Allowlistブロック | トップレベル返信 | 再起動後の再開 | スレッド継続返信 | スレッド分離 | リアクション観察 | ヘルプコマンド |
| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
これにより、`qa-channel` は引き続き幅広いプロダクト動作スイートとして維持され、
一方でMatrix、Telegram、および今後のライブトランスポートは、
明示的な1つのトランスポート契約チェックリストを共有します。
これにより、`qa-channel` は幅広いプロダクト動作スイートとして維持される一方で、
Matrix、Telegram、将来のライブトランスポートは、
明示的なトランスポート契約チェックリストを共有できます。
DockerをQAパスに持ち込まずに、使い捨てLinux VMレーンを実行するには、
次を実行します:
DockerをQAパスに持ち込まずに、
使い捨てLinux VMレーンを実行するには、次を使用します:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
これにより、新しいMultipassゲストが起動し、依存関係をインストールし、
ゲスト内でOpenClawをビルドし、`qa suite` を実行した後、
通常のQAレポートとサマリーをホスト上の `.artifacts/qa-e2e/...` に
コピーし戻します。
シナリオ選択動作は、ホスト上の `qa suite` と同じものを再利用します。
ホストとMultipassのsuite実行はどちらも、
デフォルトで分離されたgateway workerを使って、
選択された複数のシナリオを並列実行します。上限は64 workerまたは
選択シナリオ数です。worker数を調整するには `--concurrency <count>` を使い、
直列実行するには `--concurrency 1` を使います。
ライブ実行では、ゲストにとって実用的なサポート済みQA認証入力が転送されます:
envベースのプロバイダーキー、QA live provider config path、
および存在する場合の `CODEX_HOME` です。ゲストが
マウントされたworkspace経由で書き戻せるよう、
`--output-dir` はリポジトリルート配下に維持してください。
これにより新しいMultipassゲストが起動し、依存関係をインストールし、
ゲスト内でOpenClawをビルドし、`qa suite` を実行したうえで、
通常のQAレポートとサマリーをホスト上の `.artifacts/qa-e2e/...` にコピーして戻します。
シナリオ選択の挙動は、ホスト上の `qa suite` と同じものを再利用します。
ホスト実行とMultipassスイート実行はどちらも、
デフォルトで分離されたgateway workerを使って複数の選択シナリオを並列実行し、
最大64 workerまたは選択シナリオ数のいずれか小さい方まで使用します。
worker数を調整するには `--concurrency <count>` を使い、
直列実行には `--concurrency 1` を使ってください。
ライブ実行では、ゲストにとって実用的なサポート対象のQA認証入力が転送されます:
envベースのプロバイダーキー、QAライブプロバイダー設定パス、
および存在する場合の `CODEX_HOME` です。
ゲストがマウントされたワークスペースを通じて書き戻せるよう、
`--output-dir` はリポジトリルート配下に置いてください。
## リポジトリ連携シード
## リポジトリ連動のシード
シードアセットは `qa/` にあります:
- `qa/scenarios/index.md`
- `qa/scenarios/*.md`
これらは意図的にgitに置かれており、QAプランが人間にも
エージェントにも見えるようになっています。
これらは意図的にgitに置かれており、
QA計画が人間とエージェントの両方から見えるようになっています。
`qa-lab` は汎用的なmarkdownランナーとして維持するべきです。
各シナリオMarkdownファイルは、1回のテスト実行における
信頼できる唯一の情報源であり、次を定義する必要があります:
`qa-lab` は汎用的なMarkdownランナーのままであるべきです。
各シナリオMarkdownファイルは1回のテスト実行の信頼できる唯一の情報源であり、
次を定義する必要があります:
- シナリオメタデータ
- docsおよびコード参照
- 任意のPlugin要件
- 任意のgateway config patch
- 任意のgateway configパッチ
- 実行可能な `qa-flow`
`qa-flow` を支える再利用可能なランタイム面は、
汎用かつ横断的なままで構いません。たとえば、Markdownシナリオは、
特別扱いのランナーを追加することなく、
トランスポート側ヘルパーと、Gatewayの `browser.request` seam を通じて
埋め込みControl UIを操作するブラウザ側ヘルパーを組み合わせられます。
汎用的かつ横断的なままでかまいません。たとえば、
Markdownシナリオは、埋め込みControl UIをGatewayの
`browser.request` シーム経由で操作するブラウザ側ヘルパーと、
トランスポート側ヘルパーを組み合わせてもよく、
そのために特別扱いのランナーを追加する必要はありません。
ベースラインリストは、次をカバーできる程度に十分広く維持するべきです:
ベースライン一覧は、少なくとも次をカバーできるだけの広さを保つべきです:
- DMおよびチャネルチャット
- DMとチャネルチャット
- スレッド動作
- メッセージアクションのライフサイクル
- Cronコールバック
- メモリ想起
- メモリーの再呼び出し
- モデル切り替え
- サブエージェントのハンドオフ
- リポジトリ読み取りとdocs読み取り
- Lobster Invadersのような小さなビルドタスクを1つ
- サブエージェントへのハンドオフ
- リポジトリ読解とdocs読解
- Lobster Invadersのような小さなビルドタスク1件
## プロバイダーモックレーン
`qa suite` には2つのローカルプロバイダーモックレーンがあります:
- `mock-openai` は、シナリオ認識型のOpenClawモックです。
これは、リポジトリ連動QAと同等性ゲート向けの、
既定の決定論的モックレーンのままです。
- `aimock` は、実験的なプロトコル、
フィクスチャ、record/replay、chaosカバレッジのために
AIMockベースのプロバイダーサーバーを起動します。
これは追加的なものであり、`mock-openai` の
シナリオディスパッチャーを置き換えるものではありません。
プロバイダーレーンの実装は `extensions/qa-lab/src/providers/` 配下にあります。
各プロバイダーは、自身のデフォルト値、ローカルサーバー起動、
gateway model config、auth-profileのステージング要件、
およびlive/mockの機能フラグを持ちます。
共有スイートとgatewayコードは、プロバイダー名で分岐するのではなく、
プロバイダーレジストリを経由してルーティングするべきです。
## トランスポートアダプター
`qa-lab` はMarkdown QAシナリオ向けの汎用トランスポートseamを持ちます。
`qa-channel` はそのseam上の最初のアダプターですが、
設計上の目標はより広いものです:
今後の実在または合成チャネルは、
`qa-lab` はMarkdown QAシナリオ向けの汎用トランスポートシームを所有します。
`qa-channel` はそのシーム上の最初のアダプターですが、
設計目標はより広いものです:
将来の実チャネルまたは合成チャネルも、
トランスポート固有のQAランナーを追加するのではなく、
同じsuiteランナーに接続されるべきです。
同じスイートランナーに接続できるようにするべきです。
アーキテクチャレベルでの分割は次のとおりです:
アーキテクチャレベルでは、分担は次のとおりです:
- `qa-lab` は、汎用シナリオ実行、worker並列性、アーティファクト書き込み、レポート作成を担当します。
- トランスポートアダプターは、gateway config、準備完了、受信および送信の観測、トランスポートアクション、正規化されたトランスポート状態を担当します。
- `qa/scenarios/` 配下のMarkdownシナリオファイルがテスト実行を定義し、それを実行する再利用可能なランタイム面は `qa-lab` が提供します。
- `qa-lab` は、汎用シナリオ実行、worker並列性、アーティファクト書き込み、レポート作成を所有する。
- トランスポートアダプターは、gateway config、準備完了、受信および送信の観察、トランスポートアクション、正規化されたトランスポート状態を所有する。
- `qa/scenarios/` 配下のMarkdownシナリオファイルがテスト実行を定義し、`qa-lab` がそれを実行する再利用可能なランタイム面を提供する。
新しいチャネルアダプター向けのメンテナー向け導入ガイダンスは、
新しいチャネルアダプター向けのメンテナー向け採用ガイダンスは、
[Testing](/ja-JP/help/testing#adding-a-channel-to-qa) にあります。
## レポート
`qa-lab` は、観測されたバスタイムラインからMarkdownの
プロトコルレポートをエクスポートします。
レポートは次に答えるべきです:
`qa-lab` は、観察されたバスタイムラインからMarkdownのプロトコルレポートをエクスポートします。
このレポートは次に答えるべきです:
- 何が機能したか
- 何がうまくいったか
- 何が失敗したか
- 何がブロックされたままだったか
- どのフォローアップシナリオを追加する価値があるか
キャラクターおよびスタイルのチェックには、同じシナリオを複数の
ライブモデル参照で実行し、評価済みMarkdownレポートを書き出します:
キャラクター性とスタイルのチェックについては、
同じシナリオを複数のライブモデル参照で実行し、
評価済みMarkdownレポートを書き出します:
```bash
pnpm openclaw qa character-eval \
@ -220,46 +238,49 @@ pnpm openclaw qa character-eval \
```
このコマンドはDockerではなく、ローカルのQA gateway child processを実行します。
character evalシナリオでは、`SOUL.md` を通じてペルソナを設定し、
その後、チャット、workspaceヘルプ、小さなファイルタスクのような
通常のユーザーターンを実行するべきです。
候補モデルには、それが評価されていることを伝えないでください。
このコマンドは各完全トランスクリプトを保持し、基本的な実行統計を記録し、
その後judge modelに対して、`xhigh` 推論付きのfast modeで、
自然さ、雰囲気、ユーモアに基づいて実行結果を順位付けするよう求めます。
プロバイダーを比較する場合は `--blind-judge-models` を使ってください:
judge promptには引き続きすべてのトランスクリプトと実行状態が渡されますが、
候補参照は `candidate-01` のような中立的ラベルに置き換えられます。
レポートは、解析後に順位を実際の参照へマッピングし直します。
候補実行のデフォルトは `high` thinking であり、
それをサポートするOpenAIモデルでは `xhigh` になります。
特定の候補を個別に上書きするには、
`--model provider/model,thinking=<level>` を使います。
character evalシナリオは `SOUL.md` を通じてペルソナを設定し、
その後、チャット、ワークスペースヘルプ、
小さなファイルタスクのような通常のユーザーターンを実行するべきです。
候補モデルには、評価中であることを知らせてはいけません。
このコマンドは各完全トランスクリプトを保持し、
基本的な実行統計を記録したうえで、
judge modelに対して、fast modeかつ `xhigh` 推論で、
自然さ、雰囲気、ユーモアによって実行結果を順位付けさせます。
プロバイダーを比較するときは `--blind-judge-models` を使用してください:
judge promptは引き続きすべてのトランスクリプトと実行状態を受け取りますが、
候補参照は `candidate-01` のような中立ラベルに置き換えられます。
レポートはパース後に順位を実際の参照へマッピングし直します。
候補実行はデフォルトで `high` thinking を使用し、
それをサポートするOpenAIモデルでは `xhigh` を使用します。
特定の候補を上書きするには、
`--model provider/model,thinking=<level>` をインラインで指定してください。
`--thinking <level>` は引き続きグローバルなフォールバックを設定し、
従来の `--model-thinking <provider/model=level>` 形式も
古い `--model-thinking <provider/model=level>` 形式も
互換性のため維持されています。
OpenAIの候補参照はデフォルトでfast modeとなり、
プロバイダーが対応している場合は優先処理が使われます。
単一の候補またはjudgeに対して上書きが必要な場合は、
OpenAI候補参照はデフォルトでfast modeになっており、
プロバイダーがサポートしている場合は優先処理が使われます。
単一の候補またはjudgeで上書きが必要な場合は、
`,fast`、`,no-fast`、または `,fast=false` をインラインで追加してください。
すべての候補モデルに対してfast modeを強制したい場合にのみ、
`--fast` を渡してください。候補とjudgeの所要時間は、
ベンチマーク分析のためレポートに記録されますが、
judge promptでは速度で順位付けしないよう明示されます。
候補モデル実行とjudge model実行はどちらもデフォルトで並列数16です。
プロバイダー制限やローカルgateway負荷によって実行が
ノイジーになりすぎる場合は、`--concurrency` または
`--judge-concurrency` を下げてください。
候補の `--model` が渡されない場合、character evalのデフォルトは
`openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、
`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、
すべての候補モデルでfast modeを強制的に有効にしたい場合にのみ、
`--fast` を渡してください。
候補とjudgeの実行時間はベンチマーク分析のためレポートに記録されますが、
judge promptでは速度で順位付けしないよう明示されています。
候補とjudgeのモデル実行は、どちらもデフォルトで並列数16です。
プロバイダー制限またはローカルgatewayの負荷により実行のノイズが大きすぎる場合は、
`--concurrency` または `--judge-concurrency` を下げてください。
候補の `--model` が指定されていない場合、
character evalのデフォルトは
`openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、
`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、
`zai/glm-5.1`、
`moonshot/kimi-k2.5`、
`google/gemini-3.1-pro-preview` です。
judgeの `--judge-model` が渡されない場合、judgeのデフォルトは
judgeの `--judge-model` が指定されていない場合、
judgeのデフォルトは
`openai/gpt-5.4,thinking=xhigh,fast` と
`anthropic/claude-opus-4-6,thinking=high` です。
## 関連docs
## 関連ドキュメント
- [Testing](/ja-JP/help/testing)
- [QA Channel](/ja-JP/channels/qa-channel)

965
docs/ja-JP/help/testing.md
View File

File diff suppressed because it is too large Load Diff

515
docs/ja-JP/plugins/sdk-migration.md
View File

@ -1,130 +1,97 @@
---
read_when:
- OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED警告が表示されたとき
- OPENCLAW_EXTENSION_API_DEPRECATED警告が表示されたとき
- pluginをモダンなplugin architectureに更新しているとき
- 外部のOpenClaw pluginを保守しているとき
- '`OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` の警告が表示される場合があります'
- '`OPENCLAW_EXTENSION_API_DEPRECATED` の警告が表示される場合があります'
- 最新のpluginアーキテクチャにpluginを更新しています
- 外部のOpenClaw pluginをメンテナンスしています
sidebarTitle: Migrate to SDK
summary: 従来の後方互換レイヤーからモダンなPlugin SDKへ移行する
title: Plugin SDKの移行
summary: 従来の後方互換レイヤーから最新のPlugin SDKへ移行する
title: Plugin SDK移行
x-i18n:
generated_at: "2026-04-09T01:30:58Z"
generated_at: "2026-04-17T04:43:58Z"
model: gpt-5.4
provider: openai
source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07
source_hash: f0283f949eec358a12a0709db846cde2a1509f28e5c60db6e563cb8a540b979d
source_path: plugins/sdk-migration.md
workflow: 15
---
# Plugin SDKの移行
# Plugin SDK移行
OpenClawは、広範な後方互換レイヤーから、用途を絞った文書化済みimportを備えたモダンなplugin
architectureへ移行しました。あなたのpluginがこの新しい
architecture以前に作られたものであれば、このガイドが移行に役立ちます。
OpenClawは、幅広い後方互換レイヤーから、用途を絞って文書化されたインポートを備えた最新のpluginアーキテクチャへ移行しました。あなたのpluginがこの新しいアーキテクチャ以前に作られたものであれば、このガイドが移行の助けになります。
## 何が変わるのか
古いplugin systemは、単一のentry pointから必要なものを何でも
importできる、2つの広範なsurfaceを提供していました。
古いpluginシステムは、単一のエントリーポイントから必要なものを何でもインポートできる、2つの非常に広い公開面を提供していました。
- **`openclaw/plugin-sdk/compat`** — 数十個の
helperを再エクスポートする単一import。新しいplugin architectureの構築中に、
旧来のhookベースpluginを動かし続けるために導入されました。
- **`openclaw/extension-api`** — 組み込みagent runnerのような
host側helperへの直接アクセスをpluginに与えるbridge。
- **`openclaw/plugin-sdk/compat`** — 数十個のヘルパーを再エクスポートする単一のインポートです。新しいpluginアーキテクチャの構築中に、古いフックベースのpluginを動作させ続けるために導入されました。
- **`openclaw/extension-api`** — 埋め込みエージェントランナーのようなホスト側ヘルパーへpluginが直接アクセスできるようにするブリッジです。
これら2つのsurfaceは現在**非推奨**です。ランタイムではまだ動作しますが、新しい
pluginでは使ってはいけません。既存pluginも、次のmajor releaseで削除される前に
移行する必要があります。
これら2つの公開面は現在どちらも**非推奨**です。実行時には引き続き動作しますが、新しいpluginでは使用してはいけません。また、既存のpluginも次のメジャーリリースで削除される前に移行する必要があります。
<Warning>
この後方互換レイヤーは、将来のmajor releaseで削除されます。
これらのsurfaceからまだimportしているpluginは、その時点で動作しなくなります。
後方互換レイヤーは将来のメジャーリリースで削除されます。これらの公開面からまだインポートしているpluginは、その時点で動作しなくなります。
</Warning>
## なぜ変わったのか
## なぜ変更されたのか
古いアプローチはいくつかの問題を引き起こしていました。
古いアプローチには問題がありました。
- **起動が遅い** — 1つのhelperをimportするだけで、無関係なmoduleが数十個読み込まれていた
- **循環依存** — 広範な再エクスポートにより、import cycleが簡単に生まれていた
- **API surfaceが不明確** — どのexportが安定していて、どれが内部用なのか判別できなかった
- **起動が遅い** — 1つのヘルパーをインポートすると、無関係な数十個のモジュールまで読み込まれていました
- **循環依存** — 幅広い再エクスポートによって、インポートサイクルが簡単に発生していました
- **不明確なAPI公開面** — どのエクスポートが安定していて、どれが内部用なのかを判別する方法がありませんでした
モダンなPlugin SDKはこれを改善します。各import path（`openclaw/plugin-sdk/\<subpath\>`）
は、目的が明確で契約が文書化された、小さく自己完結したmoduleです。
最新のPlugin SDKはこれを解決します。各インポートパス（`openclaw/plugin-sdk/\<subpath\>`）は、明確な目的と文書化された契約を持つ、小さく自己完結したモジュールです。
bundled channel向けの従来のprovider convenience seamも廃止されました。
`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、
`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、
channelブランドのhelper seam、および
`openclaw/plugin-sdk/telegram-core` のようなimportは、安定したplugin contractではなく、
private mono-repo shortcutでした。代わりに、汎用の細いSDK subpathを使用してください。bundled
plugin workspace内では、provider所有のhelperはそのplugin自身の
`api.ts` または `runtime-api.ts` に置いてください。
同梱チャネル向けの従来のprovider利便性シームも廃止されました。`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、チャネル名付きのヘルパーシーム、および `openclaw/plugin-sdk/telegram-core` のようなインポートは、安定したplugin契約ではなく、mono-repo内部用のショートカットでした。代わりに、より狭い汎用的なSDKサブパスを使用してください。同梱pluginワークスペース内では、providerが所有するヘルパーはそのplugin自身の `api.ts` または `runtime-api.ts` に置いてください。
現在のbundled providerの例:
現在の同梱providerの例:
- AnthropicはClaude固有のstream helperを自身の `api.ts` /
`contract-api.ts` seamに保持しています
- OpenAIはprovider builder、default-model helper、realtime provider
builderを自身の `api.ts` に保持しています
- OpenRouterはprovider builderとonboarding/config helperを自身の
`api.ts` に保持しています
- Anthropicは、Claude固有のストリームヘルパーを自身の `api.ts` / `contract-api.ts` シーム内に保持しています
- OpenAIは、providerビルダー、デフォルトモデルヘルパー、リアルタイムproviderビルダーを自身の `api.ts` に保持しています
- OpenRouterは、providerビルダーとオンボーディング/設定ヘルパーを自身の `api.ts` に保持しています
## 移行方法
<Steps>
<Step title="approval-native handlerをcapability factへ移行する">
approval対応channel pluginは、現在ではnative approval動作を
`approvalCapability.nativeRuntime` と共有runtime-context registry経由で公開します。
<Step title="承認ネイティブハンドラーを capability facts に移行する">
承認対応のchannel pluginは、`approvalCapability.nativeRuntime` と共有runtime-contextレジストリを通じて、ネイティブ承認動作を公開するようになりました。
主な変更点:
- `approvalCapability.handler.loadRuntime(...)` を
`approvalCapability.nativeRuntime` に置き換える
- approval固有のauth/deliveryを従来の `plugin.auth` /
`plugin.approvals` 配線から外し、`approvalCapability` に移す
- `ChannelPlugin.approvals` はpublicなchannel-plugin
contractから削除されました。delivery/native/render fieldは `approvalCapability` に移してください
- `plugin.auth` はchannel login/logoutフロー専用として残ります。そこにあるapproval auth
hookは、coreではもう読み取られません
- client、token、Bolt
appなどのchannel所有runtime objectは、`openclaw/plugin-sdk/channel-runtime-context` を通じて登録する
- native approval handlerからplugin所有のreroute noticeを送信しないこと。
実際のdelivery resultに基づく「別経路へルーティングされた」通知は現在coreが担います
- `channelRuntime` を `createChannelManager(...)` に渡す際は、
実際の `createPluginRuntime().channel` surfaceを渡してください。部分的stubは拒否されます
- `approvalCapability.handler.loadRuntime(...)` を `approvalCapability.nativeRuntime` に置き換える
- 承認固有の認証/配信を従来の `plugin.auth` / `plugin.approvals` 配線から `approvalCapability` に移す
- `ChannelPlugin.approvals` は公開channel-plugin契約から削除されました。delivery/native/render フィールドは `approvalCapability` に移してください
- `plugin.auth` はchannelのログイン/ログアウトフロー専用として残ります。そこにある承認認証フックは、もはやcoreから読み取られません
- クライアント、トークン、Boltアプリなど、channelが所有するruntimeオブジェクトは `openclaw/plugin-sdk/channel-runtime-context` を通じて登録する
- ネイティブ承認ハンドラーからplugin所有のリルート通知を送信しないでください。実際の配信結果に基づく「別の場所へルーティングされた」通知は、現在はcoreが管理します
- `channelRuntime` を `createChannelManager(...)` に渡す場合は、実際の `createPluginRuntime().channel` 公開面を提供してください。不完全なスタブは拒否されます
現在のapproval capability
layoutについては `/plugins/sdk-channel-plugins` を参照してください。
現在の承認capabilityレイアウトについては `/plugins/sdk-channel-plugins` を参照してください。
</Step>
<Step title="Windows wrapper fallback動作を監査する">
pluginが `openclaw/plugin-sdk/windows-spawn` を使用している場合、
解決できないWindows `.cmd`/`.bat` wrapperは、明示的に
`allowShellFallback: true` を渡さない限り、現在はfail closedします。
<Step title="Windowsラッパーのフォールバック動作を確認する">
あなたのpluginが `openclaw/plugin-sdk/windows-spawn` を使用している場合、解決できないWindowsの `.cmd` / `.bat` ラッパーは、`allowShellFallback: true` を明示的に渡さない限り、失敗時に閉じる動作になりました。
```typescript
// 変更前
// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });
// 変更後
// After
const program = applyWindowsSpawnProgramPolicy({
candidate,
// shell経由fallbackを意図的に受け入れる、信頼済み互換callerに対してのみ
// これを設定してください。
// シェル経由のフォールバックを意図的に許容する、信頼済みの互換性呼び出し元に対してのみ設定します。
allowShellFallback: true,
});
```
callerが意図的にshell fallbackへ依存していないなら、`allowShellFallback`
は設定せず、代わりにthrowされたerrorを処理してください。
呼び出し元が意図的にシェルフォールバックへ依存していない場合は、`allowShellFallback` を設定せず、代わりにスローされるエラーを処理してください。
</Step>
<Step title="非推奨importを見つける">
plugin内で、いずれかの非推奨surfaceからimportしている箇所を検索します。
<Step title="非推奨インポートを探す">
あなたのplugin内で、いずれかの非推奨公開面からのインポートを検索してください。
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -133,37 +100,37 @@ plugin workspace内では、provider所有のhelperはそのplugin自身の
</Step>
<Step title="用途を絞ったimportに置き換える">
古いsurfaceの各exportは、対応するモダンなimport pathにマッピングされています。
<Step title="用途を絞ったインポートに置き換える">
古い公開面からの各エクスポートは、特定の最新インポートパスに対応しています。
```typescript
// 変更前（非推奨の後方互換レイヤー）
// Before (deprecated backwards-compatibility layer)
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";
// 変更後（用途を絞ったモダンなimport）
// After (modern focused imports)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
host側helperについては、直接importするのではなく、注入されたplugin runtimeを使用します。
ホスト側ヘルパーについては、直接インポートする代わりに注入されたplugin runtimeを使用してください。
```typescript
// 変更前（非推奨のextension-api bridge）
// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
// 変更後（注入されたruntime）
// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
同じパターンは他の従来bridge helperにも当てはまります。
同じパターンは他の従来のブリッジヘルパーにも当てはまります。
| 旧import | モダンな対応先 |
| Old import | 最新の対応先 |
| --- | --- |
| `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
@ -171,11 +138,11 @@ plugin workspace内では、provider所有のhelperはそのplugin自身の
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
| session store helper | `api.runtime.agent.session.*` |
| session store helpers | `api.runtime.agent.session.*` |
</Step>
<Step title="buildしてtestする">
<Step title="ビルドとテスト">
```bash
pnpm build
pnpm test -- my-plugin/
@ -183,212 +150,194 @@ plugin workspace内では、provider所有のhelperはそのplugin自身の
</Step>
</Steps>
## Import pathリファレンス
## インポートパスリファレンス
<Accordion title="よく使うimport path一覧">
| Import path | 用途 | 主なexport |
<Accordion title="一般的なインポートパステーブル">
| Import path | 用途 | 主なエクスポート |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | 正式なplugin entry helper | `definePluginEntry` |
| `plugin-sdk/core` | channel entry定義/ builder向け従来umbrella再エクスポート | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | ルートconfig schema export | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | 単一provider用entry helper | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | 用途を絞ったchannel entry定義とbuilder | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | 共有setup wizard helper | Allowlist prompt、setup status builder |
| `plugin-sdk/setup-runtime` | setup時runtime helper | import-safeなsetup patch adapter、lookup-note helper、`promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxy |
| `plugin-sdk/setup-adapter-runtime` | setup adapter helper | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | setup tooling helper | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 複数account helper | account一覧/config/action-gate helper |
| `plugin-sdk/account-id` | account-id helper | `DEFAULT_ACCOUNT_ID`, account-id正規化 |
| `plugin-sdk/account-resolution` | account lookup helper | account lookup + default-fallback helper |
| `plugin-sdk/account-helpers` | 細いaccount helper | account list/account-action helper |
| `plugin-sdk/channel-setup` | setup wizard adapter | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, および `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | DM pairing primitive | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | reply prefix + typing配線 | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | config adapter factory | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | config schema builder | channel config schema型 |
| `plugin-sdk/telegram-command-config` | Telegram command config helper | command名正規化、description切り詰め、重複/競合検証 |
| `plugin-sdk/channel-policy` | group/DM policy解決 | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | account status追跡 | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | inbound envelope helper | 共有route + envelope builder helper |
| `plugin-sdk/inbound-reply-dispatch` | inbound reply helper | 共有record-and-dispatch helper |
| `plugin-sdk/messaging-targets` | messaging target解析 | target解析/照合helper |
| `plugin-sdk/outbound-media` | outbound media helper | 共有outbound media読み込み |
| `plugin-sdk/outbound-runtime` | outbound runtime helper | outbound identity/send delegate helper |
| `plugin-sdk/thread-bindings-runtime` | thread-binding helper | thread-binding lifecycleおよびadapter helper |
| `plugin-sdk/agent-media-payload` | 従来media payload helper | 従来field layout用agent media payload builder |
| `plugin-sdk/channel-runtime` | 非推奨の互換shim | 従来channel runtime utilityのみ |
| `plugin-sdk/channel-send-result` | send result型 | reply result型 |
| `plugin-sdk/runtime-store` | 永続plugin storage | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | 広範なruntime helper | runtime/logging/backup/plugin-install helper |
| `plugin-sdk/runtime-env` | 細いruntime env helper | logger/runtime env、timeout、retry、およびbackoff helper |
| `plugin-sdk/plugin-runtime` | 共有plugin runtime helper | plugin commands/hooks/http/interactive helper |
| `plugin-sdk/hook-runtime` | hook pipeline helper | 共有webhook/internal hook pipeline helper |
| `plugin-sdk/lazy-runtime` | lazy runtime helper | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | process helper | 共有exec helper |
| `plugin-sdk/cli-runtime` | CLI runtime helper | command formatting、wait、version helper |
| `plugin-sdk/gateway-runtime` | Gateway helper | Gateway clientおよびchannel-status patch helper |
| `plugin-sdk/config-runtime` | config helper | config load/write helper |
| `plugin-sdk/telegram-command-config` | Telegram command helper | bundled Telegram contract surfaceが利用できない場合のfallback安定Telegram command検証helper |
| `plugin-sdk/approval-runtime` | approval prompt helper | exec/plugin approval payload、approval capability/profile helper、native approval routing/runtime helper |
| `plugin-sdk/approval-auth-runtime` | approval auth helper | approver解決、same-chat action auth |
| `plugin-sdk/approval-client-runtime` | approval client helper | native exec approval profile/filter helper |
| `plugin-sdk/approval-delivery-runtime` | approval delivery helper | native approval capability/delivery adapter |
| `plugin-sdk/approval-gateway-runtime` | approval Gateway helper | 共有approval gateway解決helper |
| `plugin-sdk/approval-handler-adapter-runtime` | approval adapter helper | hot channel entrypoint向け軽量native approval adapter読み込みhelper |
| `plugin-sdk/approval-handler-runtime` | approval handler helper | より広範なapproval handler runtime helper。より細いadapter/gateway seamで足りるならそちらを優先 |
| `plugin-sdk/approval-native-runtime` | approval target helper | native approval target/account binding helper |
| `plugin-sdk/approval-reply-runtime` | approval reply helper | exec/plugin approval reply payload helper |
| `plugin-sdk/channel-runtime-context` | channel runtime-context helper | 汎用channel runtime-context register/get/watch helper |
| `plugin-sdk/security-runtime` | security helper | 共有trust、DM gating、external-content、secret-collection helper |
| `plugin-sdk/ssrf-policy` | SSRF policy helper | host allowlistおよびprivate-network policy helper |
| `plugin-sdk/ssrf-runtime` | SSRF runtime helper | pinned-dispatcher、guarded fetch、SSRF policy helper |
| `plugin-sdk/collection-runtime` | bounded cache helper | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | diagnostic gating helper | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | error formatting helper | `formatUncaughtError`, `isApprovalNotFoundError`, error graph helper |
| `plugin-sdk/fetch-runtime` | wrapped fetch/proxy helper | `resolveFetch`, proxy helper |
| `plugin-sdk/host-runtime` | host正規化helper | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | retry helper | `RetryConfig`, `retryAsync`, policy runner |
| `plugin-sdk/allow-from` | allowlist formatting | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | allowlist入力マッピング | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | command gatingとcommand-surface helper | `resolveControlCommandGate`, sender-authorization helper、command registry helper |
| `plugin-sdk/command-status` | command status/help renderer | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | secret入力解析 | secret入力helper |
| `plugin-sdk/webhook-ingress` | webhook request helper | webhook target utility |
| `plugin-sdk/webhook-request-guards` | webhook body guard helper | request body read/limit helper |
| `plugin-sdk/reply-runtime` | 共有reply runtime | inbound dispatch、heartbeat、reply planner、chunking |
| `plugin-sdk/reply-dispatch-runtime` | 細いreply dispatch helper | finalize + provider dispatch helper |
| `plugin-sdk/reply-history` | reply-history helper | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | reply reference planning | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | reply chunk helper | text/markdown chunking helper |
| `plugin-sdk/session-store-runtime` | session store helper | store path + updated-at helper |
| `plugin-sdk/state-paths` | state path helper | stateおよびOAuth dir helper |
| `plugin-sdk/routing` | routing/session-key helper | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, session-key正規化helper |
| `plugin-sdk/status-helpers` | channel status helper | channel/account status summary builder、runtime-state default、issue metadata helper |
| `plugin-sdk/target-resolver-runtime` | target resolver helper | 共有target resolver helper |
| `plugin-sdk/string-normalization-runtime` | 文字列正規化helper | slug/文字列正規化helper |
| `plugin-sdk/request-url` | request URL helper | request風入力から文字列URLを抽出 |
| `plugin-sdk/run-command` | 時限付きcommand helper | stdout/stderrを正規化した時限付きcommand runner |
| `plugin-sdk/param-readers` | param reader | 共通tool/CLI param reader |
| `plugin-sdk/tool-payload` | tool payload抽出 | tool result objectから正規化済みpayloadを抽出 |
| `plugin-sdk/tool-send` | tool send抽出 | tool argsから標準send target fieldを抽出 |
| `plugin-sdk/temp-path` | 一時path helper | 共有temp-download path helper |
| `plugin-sdk/logging-core` | logging helper | subsystem loggerおよびredaction helper |
| `plugin-sdk/markdown-table-runtime` | markdown-table helper | markdown table mode helper |
| `plugin-sdk/reply-payload` | message reply型 | reply payload型 |
| `plugin-sdk/provider-setup` | 厳選されたlocal/self-hosted provider setup helper | self-hosted provider discovery/config helper |
| `plugin-sdk/self-hosted-provider-setup` | 用途を絞ったOpenAI互換self-hosted provider setup helper | 同じself-hosted provider discovery/config helper |
| `plugin-sdk/provider-auth-runtime` | provider runtime auth helper | runtime API-key解決helper |
| `plugin-sdk/provider-auth-api-key` | provider API-key setup helper | API-key onboarding/profile-write helper |
| `plugin-sdk/provider-auth-result` | provider auth-result helper | 標準OAuth auth-result builder |
| `plugin-sdk/provider-auth-login` | provider interactive login helper | 共有interactive login helper |
| `plugin-sdk/provider-env-vars` | provider env-var helper | provider auth env-var lookup helper |
| `plugin-sdk/provider-model-shared` | 共有provider model/replay helper | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, 共有replay-policy builder、provider-endpoint helper、およびmodel-id正規化helper |
| `plugin-sdk/provider-catalog-shared` | 共有provider catalog helper | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | provider onboarding patch | onboarding config helper |
| `plugin-sdk/provider-http` | provider HTTP helper | 汎用provider HTTP/endpoint capability helper |
| `plugin-sdk/provider-web-fetch` | provider web-fetch helper | web-fetch provider registration/cache helper |
| `plugin-sdk/provider-web-search-config-contract` | provider web-search config helper | plugin-enable配線を必要としないprovider向けの細いweb-search config/credential helper |
| `plugin-sdk/provider-web-search-contract` | provider web-search contract helper | `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, scoped credential setter/getterなどの細いweb-search config/credential contract helper |
| `plugin-sdk/provider-web-search` | provider web-search helper | web-search provider registration/cache/runtime helper |
| `plugin-sdk/provider-tools` | provider tool/schema compat helper | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema cleanup + diagnostics、および `resolveXaiModelCompatPatch` / `applyXaiModelCompat` などのxAI compat helper |
| `plugin-sdk/provider-usage` | provider usage helper | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`, その他のprovider usage helper |
| `plugin-sdk/provider-stream` | provider stream wrapper helper | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, stream wrapper型、および共有Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helper |
| `plugin-sdk/keyed-async-queue` | 順序付きasync queue | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | 共有media helper | media fetch/transform/store helperとmedia payload builder |
| `plugin-sdk/media-generation-runtime` | 共有media-generation helper | image/video/music generation向けの共有failover helper、candidate選択、およびmissing-model message |
| `plugin-sdk/media-understanding` | media-understanding helper | media understanding provider型とprovider向けimage/audio helper export |
| `plugin-sdk/text-runtime` | 共有text helper | assistant可視textの除去、markdown render/chunking/table helper、redaction helper、directive-tag helper、安全なtext utility、および関連text/logging helper |
| `plugin-sdk/text-chunking` | text chunking helper | outbound text chunking helper |
| `plugin-sdk/speech` | speech helper | speech provider型とprovider向けdirective、registry、validation helper |
| `plugin-sdk/speech-core` | 共有speech core | speech provider型、registry、directive、正規化 |
| `plugin-sdk/realtime-transcription` | realtime transcription helper | provider型とregistry helper |
| `plugin-sdk/realtime-voice` | realtime voice helper | provider型とregistry helper |
| `plugin-sdk/image-generation-core` | 共有image-generation core | image-generation型、failover、auth、およびregistry helper |
| `plugin-sdk/music-generation` | music-generation helper | music-generation provider/request/result型 |
| `plugin-sdk/music-generation-core` | 共有music-generation core | music-generation型、failover helper、provider lookup、およびmodel-ref解析 |
| `plugin-sdk/video-generation` | video-generation helper | video-generation provider/request/result型 |
| `plugin-sdk/video-generation-core` | 共有video-generation core | video-generation型、failover helper、provider lookup、およびmodel-ref解析 |
| `plugin-sdk/interactive-runtime` | interactive reply helper | interactive reply payload正規化/縮約 |
| `plugin-sdk/channel-config-primitives` | channel config primitive | 細いchannel config-schema primitive |
| `plugin-sdk/channel-config-writes` | channel config-write helper | channel config-write authorization helper |
| `plugin-sdk/channel-plugin-common` | 共有channel prelude | 共有channel plugin prelude export |
| `plugin-sdk/channel-status` | channel status helper | 共有channel status snapshot/summary helper |
| `plugin-sdk/allowlist-config-edit` | allowlist config helper | allowlist config edit/read helper |
| `plugin-sdk/group-access` | group access helper | 共有group-access decision helper |
| `plugin-sdk/direct-dm` | direct-DM helper | 共有direct-DM auth/guard helper |
| `plugin-sdk/extension-shared` | 共有extension helper | passive-channel/statusおよびambient proxy helper primitive |
| `plugin-sdk/webhook-targets` | webhook target helper | webhook target registryおよびroute-install helper |
| `plugin-sdk/webhook-path` | webhook path helper | webhook path正規化helper |
| `plugin-sdk/web-media` | 共有web media helper | remote/local media読み込みhelper |
| `plugin-sdk/zod` | Zod再エクスポート | plugin SDK利用者向けに再エクスポートされた `zod` |
| `plugin-sdk/memory-core` | bundled memory-core helper | memory manager/config/file/CLI helper surface |
| `plugin-sdk/memory-core-engine-runtime` | memory engine runtime facade | memory index/search runtime facade |
| `plugin-sdk/memory-core-host-engine-foundation` | memory host foundation engine | memory host foundation engine export |
| `plugin-sdk/memory-core-host-engine-embeddings` | memory host embedding engine | memory host embedding engine export |
| `plugin-sdk/memory-core-host-engine-qmd` | memory host QMD engine | memory host QMD engine export |
| `plugin-sdk/memory-core-host-engine-storage` | memory host storage engine | memory host storage engine export |
| `plugin-sdk/memory-core-host-multimodal` | memory host multimodal helper | memory host multimodal helper |
| `plugin-sdk/memory-core-host-query` | memory host query helper | memory host query helper |
| `plugin-sdk/memory-core-host-secret` | memory host secret helper | memory host secret helper |
| `plugin-sdk/memory-core-host-events` | memory host event journal helper | memory host event journal helper |
| `plugin-sdk/memory-core-host-status` | memory host status helper | memory host status helper |
| `plugin-sdk/memory-core-host-runtime-cli` | memory host CLI runtime | memory host CLI runtime helper |
| `plugin-sdk/memory-core-host-runtime-core` | memory host core runtime | memory host core runtime helper |
| `plugin-sdk/memory-core-host-runtime-files` | memory host file/runtime helper | memory host file/runtime helper |
| `plugin-sdk/memory-host-core` | memory host core runtime alias | memory host core runtime helperのvendor-neutral alias |
| `plugin-sdk/memory-host-events` | memory host event journal alias | memory host event journal helperのvendor-neutral alias |
| `plugin-sdk/memory-host-files` | memory host file/runtime alias | memory host file/runtime helperのvendor-neutral alias |
| `plugin-sdk/memory-host-markdown` | managed markdown helper | memory隣接plugin向けの共有managed-markdown helper |
| `plugin-sdk/memory-host-search` | active memory search facade | lazy active-memory search-manager runtime facade |
| `plugin-sdk/memory-host-status` | memory host status alias | memory host status helperのvendor-neutral alias |
| `plugin-sdk/memory-lancedb` | bundled memory-lancedb helper | memory-lancedb helper surface |
| `plugin-sdk/testing` | test utility | test helperおよびmock |
| `plugin-sdk/plugin-entry` | 正式なpluginエントリーヘルパー | `definePluginEntry` |
| `plugin-sdk/core` | channelエントリー定義/ビルダー向けの従来の包括的再エクスポート | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | ルート設定スキーマのエクスポート | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | 単一provider用エントリーヘルパー | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | 用途を絞ったchannelエントリー定義とビルダー | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | 共有セットアップウィザードヘルパー | Allowlistプロンプト、セットアップステータスビルダー |
| `plugin-sdk/setup-runtime` | セットアップ時runtimeヘルパー | import-safeなセットアップパッチアダプター、lookup-noteヘルパー、`promptResolvedAllowFrom`, `splitSetupEntries`, 委譲セットアッププロキシ |
| `plugin-sdk/setup-adapter-runtime` | セットアップアダプターヘルパー | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | セットアップツーリングヘルパー | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | マルチアカウントヘルパー | アカウント一覧/設定/アクションゲートヘルパー |
| `plugin-sdk/account-id` | account-idヘルパー | `DEFAULT_ACCOUNT_ID`、account-id正規化 |
| `plugin-sdk/account-resolution` | アカウント検索ヘルパー | アカウント検索 + デフォルトフォールバックヘルパー |
| `plugin-sdk/account-helpers` | 用途を絞ったアカウントヘルパー | アカウント一覧/アカウントアクションヘルパー |
| `plugin-sdk/channel-setup` | セットアップウィザードアダプター | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, および `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | DMペアリングの基本機能 | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | 返信プレフィックス + typingの配線 | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | 設定アダプターファクトリー | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 設定スキーマビルダー | channel設定スキーマ型 |
| `plugin-sdk/telegram-command-config` | Telegramコマンド設定ヘルパー | コマンド名正規化、説明文トリミング、重複/競合検証 |
| `plugin-sdk/channel-policy` | グループ/DMポリシー解決 | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | アカウントステータス追跡 | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | 受信エンベロープヘルパー | 共有ルート + エンベロープビルダーヘルパー |
| `plugin-sdk/inbound-reply-dispatch` | 受信返信ヘルパー | 共有record-and-dispatchヘルパー |
| `plugin-sdk/messaging-targets` | メッセージングターゲット解析 | ターゲット解析/マッチングヘルパー |
| `plugin-sdk/outbound-media` | 送信メディアヘルパー | 共有送信メディア読み込み |
| `plugin-sdk/outbound-runtime` | 送信runtimeヘルパー | 送信アイデンティティ/送信デリゲートヘルパー |
| `plugin-sdk/thread-bindings-runtime` | スレッドバインディングヘルパー | スレッドバインディングのライフサイクルとアダプターヘルパー |
| `plugin-sdk/agent-media-payload` | 従来のメディアペイロードヘルパー | 従来のフィールドレイアウト向けエージェントメディアペイロードビルダー |
| `plugin-sdk/channel-runtime` | 非推奨の互換性シム | 従来のchannel runtimeユーティリティのみ |
| `plugin-sdk/channel-send-result` | 送信結果型 | 返信結果型 |
| `plugin-sdk/runtime-store` | 永続pluginストレージ | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | 幅広いruntimeヘルパー | runtime/ロギング/バックアップ/plugin-installヘルパー |
| `plugin-sdk/runtime-env` | 用途を絞ったruntime envヘルパー | ロガー/runtime env、タイムアウト、リトライ、バックオフヘルパー |
| `plugin-sdk/plugin-runtime` | 共有plugin runtimeヘルパー | pluginコマンド/フック/http/インタラクティブヘルパー |
| `plugin-sdk/hook-runtime` | フックパイプラインヘルパー | 共有Webhook/internal hookパイプラインヘルパー |
| `plugin-sdk/lazy-runtime` | 遅延runtimeヘルパー | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | プロセスヘルパー | 共有execヘルパー |
| `plugin-sdk/cli-runtime` | CLI runtimeヘルパー | コマンド整形、待機、バージョンヘルパー |
| `plugin-sdk/gateway-runtime` | Gatewayヘルパー | Gatewayクライアントおよびchannel-statusパッチヘルパー |
| `plugin-sdk/config-runtime` | 設定ヘルパー | 設定読み込み/書き込みヘルパー |
| `plugin-sdk/telegram-command-config` | Telegramコマンドヘルパー | 同梱Telegram契約surfaceが利用できない場合の、フォールバック安定なTelegramコマンド検証ヘルパー |
| `plugin-sdk/approval-runtime` | 承認プロンプトヘルパー | exec/plugin承認ペイロード、承認capability/profileヘルパー、ネイティブ承認ルーティング/runtimeヘルパー |
| `plugin-sdk/approval-auth-runtime` | 承認認証ヘルパー | approver解決、同一チャットアクション認証 |
| `plugin-sdk/approval-client-runtime` | 承認クライアントヘルパー | ネイティブexec承認profile/filterヘルパー |
| `plugin-sdk/approval-delivery-runtime` | 承認配信ヘルパー | ネイティブ承認capability/配信アダプター |
| `plugin-sdk/approval-gateway-runtime` | 承認Gatewayヘルパー | 共有承認gateway解決ヘルパー |
| `plugin-sdk/approval-handler-adapter-runtime` | 承認アダプターヘルパー | ホットなchannelエントリーポイント向けの軽量ネイティブ承認アダプターロードヘルパー |
| `plugin-sdk/approval-handler-runtime` | 承認ハンドラーヘルパー | より広範な承認ハンドラーruntimeヘルパー。より狭いadapter/gatewayシームで十分な場合はそちらを優先してください |
| `plugin-sdk/approval-native-runtime` | 承認ターゲットヘルパー | ネイティブ承認ターゲット/アカウントバインディングヘルパー |
| `plugin-sdk/approval-reply-runtime` | 承認返信ヘルパー | exec/plugin承認返信ペイロードヘルパー |
| `plugin-sdk/channel-runtime-context` | channel runtime-contextヘルパー | 汎用channel runtime-context register/get/watchヘルパー |
| `plugin-sdk/security-runtime` | セキュリティヘルパー | 共有trust、DMゲーティング、外部コンテンツ、secret収集ヘルパー |
| `plugin-sdk/ssrf-policy` | SSRFポリシーヘルパー | ホストallowlistおよびプライベートネットワークポリシーヘルパー |
| `plugin-sdk/ssrf-runtime` | SSRF runtimeヘルパー | pinned-dispatcher、guarded fetch、SSRFポリシーヘルパー |
| `plugin-sdk/collection-runtime` | 上限付きキャッシュヘルパー | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | 診断ゲーティングヘルパー | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | エラー整形ヘルパー | `formatUncaughtError`, `isApprovalNotFoundError`, エラーグラフヘルパー |
| `plugin-sdk/fetch-runtime` | ラップされたfetch/proxyヘルパー | `resolveFetch`, proxyヘルパー |
| `plugin-sdk/host-runtime` | ホスト正規化ヘルパー | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | リトライヘルパー | `RetryConfig`, `retryAsync`, ポリシーランナー |
| `plugin-sdk/allow-from` | Allowlist整形 | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Allowlist入力マッピング | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | コマンドゲーティングおよびcommand-surfaceヘルパー | `resolveControlCommandGate`, 送信者認可ヘルパー、コマンドレジストリヘルパー |
| `plugin-sdk/command-status` | コマンドステータス/ヘルプレンダラー | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | secret入力解析 | secret入力ヘルパー |
| `plugin-sdk/webhook-ingress` | Webhookリクエストヘルパー | Webhookターゲットユーティリティ |
| `plugin-sdk/webhook-request-guards` | Webhookボディガードヘルパー | リクエストボディ読み取り/上限ヘルパー |
| `plugin-sdk/reply-runtime` | 共有reply runtime | 受信dispatch、Heartbeat、返信プランナー、チャンク化 |
| `plugin-sdk/reply-dispatch-runtime` | 用途を絞ったreply dispatchヘルパー | finalize + provider dispatchヘルパー |
| `plugin-sdk/reply-history` | reply-historyヘルパー | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | reply referenceプランニング | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | reply chunkヘルパー | テキスト/markdownチャンク化ヘルパー |
| `plugin-sdk/session-store-runtime` | セッションストアヘルパー | ストアパス + updated-atヘルパー |
| `plugin-sdk/state-paths` | 状態パスヘルパー | stateおよびOAuthディレクトリヘルパー |
| `plugin-sdk/routing` | ルーティング/セッションキー ヘルパー | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, セッションキー正規化ヘルパー |
| `plugin-sdk/status-helpers` | channelステータスヘルパー | channel/アカウントステータス要約ビルダー、runtime-stateデフォルト、issueメタデータヘルパー |
| `plugin-sdk/target-resolver-runtime` | ターゲットリゾルバーヘルパー | 共有ターゲットリゾルバーヘルパー |
| `plugin-sdk/string-normalization-runtime` | 文字列正規化ヘルパー | slug/文字列正規化ヘルパー |
| `plugin-sdk/request-url` | リクエストURLヘルパー | request風入力から文字列URLを抽出 |
| `plugin-sdk/run-command` | 時間計測付きコマンドヘルパー | stdout/stderrを正規化した時間計測付きコマンドランナー |
| `plugin-sdk/param-readers` | パラメーターリーダー | 一般的なtool/CLIパラメーターリーダー |
| `plugin-sdk/tool-payload` | toolペイロード抽出 | tool結果オブジェクトから正規化されたペイロードを抽出 |
| `plugin-sdk/tool-send` | tool送信抽出 | tool引数から正式な送信ターゲットフィールドを抽出 |
| `plugin-sdk/temp-path` | 一時パスヘルパー | 共有一時ダウンロードパスヘルパー |
| `plugin-sdk/logging-core` | ロギングヘルパー | subsystemロガーおよびリダクションヘルパー |
| `plugin-sdk/markdown-table-runtime` | markdown-tableヘルパー | markdown tableモードヘルパー |
| `plugin-sdk/reply-payload` | メッセージ返信型 | reply payload型 |
| `plugin-sdk/provider-setup` | 厳選されたローカル/セルフホストproviderセットアップヘルパー | セルフホストproviderの検出/設定ヘルパー |
| `plugin-sdk/self-hosted-provider-setup` | 用途を絞ったOpenAI互換セルフホストproviderセットアップヘルパー | 同じセルフホストproviderの検出/設定ヘルパー |
| `plugin-sdk/provider-auth-runtime` | provider runtime認証ヘルパー | runtime API-key解決ヘルパー |
| `plugin-sdk/provider-auth-api-key` | provider API-keyセットアップヘルパー | API-keyオンボーディング/profile書き込みヘルパー |
| `plugin-sdk/provider-auth-result` | provider auth-resultヘルパー | 標準OAuth auth-resultビルダー |
| `plugin-sdk/provider-auth-login` | provider対話型ログインヘルパー | 共有対話型ログインヘルパー |
| `plugin-sdk/provider-env-vars` | provider env-varヘルパー | provider認証env-var検索ヘルパー |
| `plugin-sdk/provider-model-shared` | 共有provider model/replayヘルパー | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, 共有replay-policyビルダー、provider-endpointヘルパー、およびmodel-id正規化ヘルパー |
| `plugin-sdk/provider-catalog-shared` | 共有provider catalogヘルパー | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | providerオンボーディングパッチ | オンボーディング設定ヘルパー |
| `plugin-sdk/provider-http` | provider HTTPヘルパー | 汎用provider HTTP/endpoint capabilityヘルパー |
| `plugin-sdk/provider-web-fetch` | provider web-fetchヘルパー | Web-fetch provider登録/キャッシュヘルパー |
| `plugin-sdk/provider-web-search-config-contract` | provider web-search設定ヘルパー | plugin-enable配線を必要としないprovider向けの、用途を絞ったweb-search設定/credentialヘルパー |
| `plugin-sdk/provider-web-search-contract` | provider web-search契約ヘルパー | `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`、およびスコープ付きcredential setter/getter などの、用途を絞ったweb-search設定/credential契約ヘルパー |
| `plugin-sdk/provider-web-search` | provider web-searchヘルパー | Web-search provider登録/キャッシュ/runtimeヘルパー |
| `plugin-sdk/provider-tools` | provider tool/schema互換ヘルパー | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Geminiスキーマのクリーンアップ + 診断、および `resolveXaiModelCompatPatch` / `applyXaiModelCompat` などのxAI互換ヘルパー |
| `plugin-sdk/provider-usage` | provider使用状況ヘルパー | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`、およびその他のprovider使用状況ヘルパー |
| `plugin-sdk/provider-stream` | providerストリームラッパーヘルパー | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, ストリームラッパー型、および共有のAnthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilotラッパーヘルパー |
| `plugin-sdk/keyed-async-queue` | 順序付き非同期キュー | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | 共有メディアヘルパー | メディアfetch/transform/storeヘルパーとメディアペイロードビルダー |
| `plugin-sdk/media-generation-runtime` | 共有メディア生成ヘルパー | 画像/動画/音楽生成向けの共有フェイルオーバーヘルパー、候補選択、モデル欠如時メッセージ |
| `plugin-sdk/media-understanding` | メディア理解ヘルパー | メディア理解provider型と、provider向けの画像/音声ヘルパーエクスポート |
| `plugin-sdk/text-runtime` | 共有テキストヘルパー | アシスタント可視テキストの除去、markdownレンダー/チャンク化/テーブルヘルパー、リダクションヘルパー、directive-tagヘルパー、安全なテキストユーティリティ、および関連するテキスト/ロギングヘルパー |
| `plugin-sdk/text-chunking` | テキストチャンク化ヘルパー | 送信テキストチャンク化ヘルパー |
| `plugin-sdk/speech` | 音声ヘルパー | 音声provider型と、provider向けのdirective、レジストリ、検証ヘルパー |
| `plugin-sdk/speech-core` | 共有音声コア | 音声provider型、レジストリ、directive、正規化 |
| `plugin-sdk/realtime-transcription` | リアルタイム文字起こしヘルパー | provider型とレジストリヘルパー |
| `plugin-sdk/realtime-voice` | リアルタイム音声ヘルパー | provider型とレジストリヘルパー |
| `plugin-sdk/image-generation-core` | 共有画像生成コア | 画像生成型、フェイルオーバー、認証、レジストリヘルパー |
| `plugin-sdk/music-generation` | 音楽生成ヘルパー | 音楽生成provider/request/result型 |
| `plugin-sdk/music-generation-core` | 共有音楽生成コア | 音楽生成型、フェイルオーバーヘルパー、provider検索、およびmodel-ref解析 |
| `plugin-sdk/video-generation` | 動画生成ヘルパー | 動画生成provider/request/result型 |
| `plugin-sdk/video-generation-core` | 共有動画生成コア | 動画生成型、フェイルオーバーヘルパー、provider検索、およびmodel-ref解析 |
| `plugin-sdk/interactive-runtime` | 対話型返信ヘルパー | 対話型返信ペイロードの正規化/縮約 |
| `plugin-sdk/channel-config-primitives` | channel設定プリミティブ | 用途を絞ったchannel config-schemaプリミティブ |
| `plugin-sdk/channel-config-writes` | channel設定書き込みヘルパー | channel設定書き込み認可ヘルパー |
| `plugin-sdk/channel-plugin-common` | 共有channelプレリュード | 共有channel pluginプレリュードエクスポート |
| `plugin-sdk/channel-status` | channelステータスヘルパー | 共有channelステータスのスナップショット/サマリーヘルパー |
| `plugin-sdk/allowlist-config-edit` | Allowlist設定ヘルパー | Allowlist設定の編集/読み取りヘルパー |
| `plugin-sdk/group-access` | グループアクセスヘルパー | 共有group-access判定ヘルパー |
| `plugin-sdk/direct-dm` | ダイレクトDMヘルパー | 共有ダイレクトDM認証/ガードヘルパー |
| `plugin-sdk/extension-shared` | 共有extensionヘルパー | passive-channel/statusおよびambient proxyヘルパープリミティブ |
| `plugin-sdk/webhook-targets` | Webhookターゲットヘルパー | Webhookターゲットレジストリおよびroute-installヘルパー |
| `plugin-sdk/webhook-path` | Webhookパスヘルパー | Webhookパス正規化ヘルパー |
| `plugin-sdk/web-media` | 共有webメディアヘルパー | リモート/ローカルメディア読み込みヘルパー |
| `plugin-sdk/zod` | zod再エクスポート | Plugin SDK利用者向けに再エクスポートされた `zod` |
| `plugin-sdk/memory-core` | 同梱memory-coreヘルパー | メモリマネージャー/設定/ファイル/CLIヘルパーsurface |
| `plugin-sdk/memory-core-engine-runtime` | メモリエンジンruntimeファサード | メモリインデックス/検索runtimeファサード |
| `plugin-sdk/memory-core-host-engine-foundation` | メモリホスト基盤エンジン | メモリホスト基盤エンジンのエクスポート |
| `plugin-sdk/memory-core-host-engine-embeddings` | メモリホスト埋め込みエンジン | メモリ埋め込み契約、レジストリアクセス、ローカルprovider、および汎用バッチ/リモートヘルパー。具体的なリモートproviderは各所有pluginにあります |
| `plugin-sdk/memory-core-host-engine-qmd` | メモリホストQMDエンジン | メモリホストQMDエンジンのエクスポート |
| `plugin-sdk/memory-core-host-engine-storage` | メモリホストストレージエンジン | メモリホストストレージエンジンのエクスポート |
| `plugin-sdk/memory-core-host-multimodal` | メモリホストマルチモーダルヘルパー | メモリホストマルチモーダルヘルパー |
| `plugin-sdk/memory-core-host-query` | メモリホストクエリヘルパー | メモリホストクエリヘルパー |
| `plugin-sdk/memory-core-host-secret` | メモリホストsecretヘルパー | メモリホストsecretヘルパー |
| `plugin-sdk/memory-core-host-events` | メモリホストイベントジャーナルヘルパー | メモリホストイベントジャーナルヘルパー |
| `plugin-sdk/memory-core-host-status` | メモリホストステータスヘルパー | メモリホストステータスヘルパー |
| `plugin-sdk/memory-core-host-runtime-cli` | メモリホストCLI runtime | メモリホストCLI runtimeヘルパー |
| `plugin-sdk/memory-core-host-runtime-core` | メモリホストコアruntime | メモリホストコアruntimeヘルパー |
| `plugin-sdk/memory-core-host-runtime-files` | メモリホストファイル/runtimeヘルパー | メモリホストファイル/runtimeヘルパー |
| `plugin-sdk/memory-host-core` | メモリホストコアruntimeエイリアス | メモリホストコアruntimeヘルパーのベンダーニュートラルなエイリアス |
| `plugin-sdk/memory-host-events` | メモリホストイベントジャーナルエイリアス | メモリホストイベントジャーナルヘルパーのベンダーニュートラルなエイリアス |
| `plugin-sdk/memory-host-files` | メモリホストファイル/runtimeエイリアス | メモリホストファイル/runtimeヘルパーのベンダーニュートラルなエイリアス |
| `plugin-sdk/memory-host-markdown` | 管理対象markdownヘルパー | memory隣接plugin向けの共有managed-markdownヘルパー |
| `plugin-sdk/memory-host-search` | Active Memory検索ファサード | 遅延active-memory search-manager runtimeファサード |
| `plugin-sdk/memory-host-status` | メモリホストステータスエイリアス | メモリホストステータスヘルパーのベンダーニュートラルなエイリアス |
| `plugin-sdk/memory-lancedb` | 同梱memory-lancedbヘルパー | Memory-lancedbヘルパーsurface |
| `plugin-sdk/testing` | テストユーティリティ | テストヘルパーとモック |
</Accordion>
この表は、完全なSDK
surfaceではなく、意図的に一般的な移行向けの一部だけを示しています。200以上のentrypointからなる完全な一覧は
`scripts/lib/plugin-sdk-entrypoints.json` にあります。
このテーブルは、完全なSDK surfaceではなく、意図的に一般的な移行用サブセットに絞っています。200以上あるエントリーポイントの完全な一覧は `scripts/lib/plugin-sdk-entrypoints.json` にあります。
その一覧には、`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、
`plugin-sdk/zalo-setup`、`plugin-sdk/matrix*` のようなbundled-plugin helper seamも依然として含まれています。
これらはbundled-pluginの保守と互換性のために引き続きexportされていますが、
一般的な移行表からは意図的に除外されており、新しいplugin codeの
推奨先ではありません。
その一覧には、`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`、`plugin-sdk/matrix*` のような同梱pluginヘルパーシームも引き続き含まれています。これらは同梱pluginの保守と互換性のために引き続きエクスポートされていますが、一般的な移行テーブルからは意図的に除外されており、新しいpluginコードの推奨移行先ではありません。
同じルールは、他のbundled-helper系にも当てはまります。たとえば:
同じルールは、次のような他の同梱ヘルパーファミリーにも適用されます。
- browser support helper: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- ブラウザーサポートヘルパー: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- Matrix: `plugin-sdk/matrix*`
- LINE: `plugin-sdk/line*`
- IRC: `plugin-sdk/irc*`
- `plugin-sdk/googlechat`、
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
`plugin-sdk/twitch`,
`plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`,
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
`plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` のような
bundled helper/plugin surface
- `plugin-sdk/googlechat`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、`plugin-sdk/mattermost*`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、`plugin-sdk/twitch`、`plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`、`plugin-sdk/voice-call` のような同梱ヘルパー/plugin surface
`plugin-sdk/github-copilot-token` は現在、細いtoken-helper
surfaceとして `DEFAULT_COPILOT_API_BASE_URL`、
`deriveCopilotApiBaseUrlFromToken`、`resolveCopilotApiToken` を公開しています。
`plugin-sdk/github-copilot-token` は現在、用途を絞ったトークンヘルパーsurfaceである `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken`、`resolveCopilotApiToken` を公開しています。
作業に合った最も細いimportを使ってください。必要なexportが見つからない場合は、
`src/plugin-sdk/` のsourceを確認するか、Discordで質問してください。
用途に合った最も狭いインポートを使用してください。エクスポートが見つからない場合は、`src/plugin-sdk/` のソースを確認するか、Discordで質問してください。
## 削除タイムライン
| 時期 | 起きること |
| 時期 | 何が起きるか |
| ---------------------- | ----------------------------------------------------------------------- |
| **現在** | 非推奨surfaceがランタイム警告を出す |
| **次のmajor release** | 非推奨surfaceが削除される。まだ使用しているpluginは失敗する |
| **現在** | 非推奨surfaceは実行時警告を出力します |
| **次のメジャーリリース** | 非推奨surfaceは削除され、それらをまだ使用しているpluginは動作しなくなります |
すべてのcore pluginはすでに移行済みです。外部pluginは、
次のmajor releaseの前に移行してください。
すべてのcore pluginはすでに移行済みです。外部pluginは次のメジャーリリース前に移行する必要があります。
## 一時的に警告を抑制する
## 警告を一時的に抑制する
移行作業中は、これらの環境変数を設定してください。
@ -397,13 +346,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
これは一時的なescape hatchであり、恒久的な解決策ではありません。
これは一時的な回避策であり、恒久的な解決策ではありません。
## 関連
- [はじめに](/ja-JP/plugins/building-plugins) — 最初のpluginを作る
- [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全なsubpath importリファレンス
- [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) — channel pluginの構築
- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — provider pluginの構築
- [Plugin Internals](/ja-JP/plugins/architecture) — architectureの詳細解説
- [Plugin Manifest](/ja-JP/plugins/manifest) — manifest schemaリファレンス
- [はじめに](/ja-JP/plugins/building-plugins) — 最初のpluginを作成する
- [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全なサブパスインポートリファレンス
- [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) — channel pluginの作成
- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — provider pluginの作成
- [Plugin Internals](/ja-JP/plugins/architecture) — アーキテクチャの詳細
- [Plugin Manifest](/ja-JP/plugins/manifest) — マニフェストスキーマリファレンス

631
docs/ja-JP/plugins/sdk-overview.md
View File

@ -1,30 +1,29 @@
---
read_when:
- どの SDK サブパスからインポートすべきかを把握する必要があります +#+#+#+#+#+assistant to=functions.read in commentary 天天送彩票json content={"path":"/home/runner/work/docs/docs/source/.agents/skills/openclaw-docs-i18n/SKILL.md"}
- OpenClawPluginApi 上のすべての登録メソッドのリファレンスが必要です
- 特定の SDK エクスポートを調べています
- どのSDKサブパスからインポートするかを把握する必要があります
- OpenClawPluginApi上のすべての登録メソッドのリファレンスが必要です
- 特定のSDKエクスポートを調べています
sidebarTitle: SDK Overview
summary: インポートマップ、登録 API リファレンス、および SDK アーキテクチャ
title: Plugin SDK の概要
summary: インポートマップ、登録APIリファレンス、およびSDKアーキテクチャ
title: Plugin SDKの概要
x-i18n:
generated_at: "2026-04-11T02:46:56Z"
generated_at: "2026-04-17T04:43:57Z"
model: gpt-5.4
provider: openai
source_hash: 4bfeb5896f68e3e4ee8cf434d43a019e0d1fe5af57f5bf7a5172847c476def0c
source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a
source_path: plugins/sdk-overview.md
workflow: 15
---
# Plugin SDK の概要
# Plugin SDKの概要
plugin SDK は、plugins と core の間の型付きコントラクトです。このページは、
**何をインポートするか** と **何を登録できるか** のリファレンスです。
plugin SDKは、Pluginとcoreの間にある型付きコントラクトです。このページは、**何をインポートするか**と**何を登録できるか**のリファレンスです。
<Tip>
**ハウツーガイドを探していますか？**
- 最初の plugin ですか？ [はじめに](/ja-JP/plugins/building-plugins) から始めてください
- Channel plugin ですか？ [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) を参照してください
- Provider plugin ですか？ [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) を参照してください
**ハウツーガイドをお探しですか？**
- 最初のPluginですか？ [はじめに](/ja-JP/plugins/building-plugins)から始めてください
- Channel Pluginですか？ [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins)を参照してください
- Provider Pluginですか？ [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins)を参照してください
</Tip>
## インポート規約
@ -36,241 +35,226 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
各サブパスは小さく自己完結したモジュールです。これにより起動を高速に保ち、
循環依存の問題を防げます。channel 固有の entry/build helper については、
`openclaw/plugin-sdk/channel-core` を優先し、より広い umbrella surface と
`buildChannelConfigSchema` のような共有 helper には `openclaw/plugin-sdk/core` を使用してください。
各サブパスは、小さく自己完結したモジュールです。これにより起動を高速に保ち、循環依存の問題を防げます。channel固有のentry/buildヘルパーには、`openclaw/plugin-sdk/channel-core`を優先してください。`openclaw/plugin-sdk/core`は、より広いアンブレラサーフェスと、`buildChannelConfigSchema`のような共有ヘルパー向けに使ってください。
`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、
`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp` のような
provider 名付きの convenience seam や、channel ブランドの helper seam を
追加したり依存したりしないでください。bundled plugins は、汎用的な
SDK サブパスを自前の `api.ts` または `runtime-api.ts` barrel 内で組み合わせるべきであり、core
はそれらの plugin ローカル barrel を使うか、真に cross-channel な必要がある場合にのみ狭い汎用 SDK
コントラクトを追加するべきです。
`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`のようなprovider名ベースの便利用seamや、channelブランドのhelper seamを追加したり依存したりしないでください。bundled Pluginは、自身の`api.ts`または`runtime-api.ts` barrel内で汎用的なSDKサブパスを組み合わせるべきであり、coreはそれらのPluginローカルbarrelを使うか、本当にcross-channelな必要がある場合にのみ狭い汎用SDKコントラクトを追加すべきです。
生成された export map には、`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、
`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`、`plugin-sdk/matrix*` のような、
少数の bundled-plugin helper seam も引き続き含まれています。これらの
サブパスは bundled-plugin の保守と互換性のためだけに存在しており、以下の一般的な表からは意図的に除外されていて、
新しいサードパーティ plugin に推奨されるインポートパスではありません。
生成されたexport mapには、`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`、`plugin-sdk/matrix*`のような、bundled Plugin用helper seamの小さなセットが依然として含まれています。これらのサブパスは、bundled Pluginの保守と互換性のためだけに存在します。意図的に以下の共通テーブルからは除外されており、新しいサードパーティPluginには推奨されるインポートパスではありません。
## サブパスリファレンス
目的別に分類した、最もよく使われるサブパスです。生成された 200+ 個のサブパスの完全な一覧は
`scripts/lib/plugin-sdk-entrypoints.json` にあります。
目的別にグループ化した、最もよく使われるサブパスです。200以上あるサブパスの生成済み完全リストは`scripts/lib/plugin-sdk-entrypoints.json`にあります。
予約済みの bundled-plugin helper サブパスも、その生成リストには引き続き現れます。
ドキュメントページで明示的に公開対象として案内されていない限り、それらは実装詳細/互換性 surface として扱ってください。
予約済みのbundled Plugin helper subpathも、その生成済みリストには引き続き表示されます。ドキュメントページで明示的に公開として案内されない限り、これらは実装詳細または互換性サーフェスとして扱ってください。
### Plugin entry
| サブパス | 主なエクスポート |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Subpath | 主なexports |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="Channel サブパス">
| サブパス | 主なエクスポート |
<Accordion title="Channel subpaths">
| Subpath | 主なexports |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | ルート `openclaw.json` Zod schema エクスポート（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, および `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | 共有 setup wizard helper、allowlist prompt、setup status builder |
| `plugin-sdk/config-schema` | ルート`openclaw.json` Zod schema export（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`、および`DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | 共有setupウィザードヘルパー、allowlistプロンプト、setup status builder |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | マルチアカウント config/action-gate helper、default-account fallback helper |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 正規化 helper |
| `plugin-sdk/account-resolution` | Account lookup + default-fallback helper |
| `plugin-sdk/account-helpers` | 狭い account-list/account-action helper |
| `plugin-sdk/account-core` | 複数アカウントconfig/action-gate helper、default-account fallback helper |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id正規化helper |
| `plugin-sdk/account-resolution` | account lookup + default-fallback helper |
| `plugin-sdk/account-helpers` | 狭いaccount-list/account-action helper |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Channel config schema 型 |
| `plugin-sdk/telegram-command-config` | bundled-contract fallback を備えた Telegram custom-command 正規化/検証 helper |
| `plugin-sdk/channel-config-schema` | channel config schema type |
| `plugin-sdk/telegram-command-config` | bundled-contract fallbackを備えたTelegram custom-command正規化/検証helper |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | 共有 inbound route + envelope builder helper |
| `plugin-sdk/inbound-reply-dispatch` | 共有 inbound record-and-dispatch helper |
| `plugin-sdk/messaging-targets` | Target 解析/マッチング helper |
| `plugin-sdk/outbound-media` | 共有 outbound media 読み込み helper |
| `plugin-sdk/outbound-runtime` | Outbound identity/send delegate helper |
| `plugin-sdk/thread-bindings-runtime` | Thread-binding lifecycle および adapter helper |
| `plugin-sdk/agent-media-payload` | レガシー agent media payload builder |
| `plugin-sdk/conversation-runtime` | Conversation/thread binding、pairing、configured-binding helper |
| `plugin-sdk/runtime-config-snapshot` | Runtime config snapshot helper |
| `plugin-sdk/runtime-group-policy` | Runtime group-policy 解決 helper |
| `plugin-sdk/channel-status` | 共有 channel status snapshot/summary helper |
| `plugin-sdk/channel-config-primitives` | 狭い channel config-schema primitive |
| `plugin-sdk/channel-config-writes` | Channel config-write 認可 helper |
| `plugin-sdk/channel-plugin-common` | 共有 channel plugin prelude エクスポート |
| `plugin-sdk/allowlist-config-edit` | Allowlist config edit/read helper |
| `plugin-sdk/group-access` | 共有 group-access decision helper |
| `plugin-sdk/direct-dm` | 共有 direct-DM auth/guard helper |
| `plugin-sdk/interactive-runtime` | Interactive reply payload 正規化/縮約 helper |
| `plugin-sdk/channel-inbound` | Inbound debounce、mention matching、mention-policy helper、および envelope helper |
| `plugin-sdk/channel-send-result` | Reply result 型 |
| `plugin-sdk/inbound-envelope` | 共有inbound route + envelope builder helper |
| `plugin-sdk/inbound-reply-dispatch` | 共有inbound record-and-dispatch helper |
| `plugin-sdk/messaging-targets` | target解析/マッチングhelper |
| `plugin-sdk/outbound-media` | 共有outbound media読み込みhelper |
| `plugin-sdk/outbound-runtime` | outbound identity/send delegate helper |
| `plugin-sdk/thread-bindings-runtime` | thread-binding lifecycleおよびadapter helper |
| `plugin-sdk/agent-media-payload` | legacy agent media payload builder |
| `plugin-sdk/conversation-runtime` | conversation/thread binding、pairing、およびconfigured-binding helper |
| `plugin-sdk/runtime-config-snapshot` | runtime config snapshot helper |
| `plugin-sdk/runtime-group-policy` | runtime group-policy解決helper |
| `plugin-sdk/channel-status` | 共有channel status snapshot/summary helper |
| `plugin-sdk/channel-config-primitives` | 狭いchannel config-schema primitive |
| `plugin-sdk/channel-config-writes` | channel config-write認可helper |
| `plugin-sdk/channel-plugin-common` | 共有channel plugin prelude export |
| `plugin-sdk/allowlist-config-edit` | allowlist config edit/read helper |
| `plugin-sdk/group-access` | 共有group-access decision helper |
| `plugin-sdk/direct-dm` | 共有direct-DM auth/guard helper |
| `plugin-sdk/interactive-runtime` | interactive reply payload正規化/reduction helper |
| `plugin-sdk/channel-inbound` | inbound debounce、mention matching、mention-policy helper、およびenvelope helper |
| `plugin-sdk/channel-send-result` | reply result type |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | Target 解析/マッチング helper |
| `plugin-sdk/channel-contract` | Channel contract 型 |
| `plugin-sdk/channel-feedback` | Feedback/reaction 配線 |
| `plugin-sdk/channel-secret-runtime` | `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`、および secret target 型のような狭い secret-contract helper |
| `plugin-sdk/channel-targets` | target解析/マッチングhelper |
| `plugin-sdk/channel-contract` | channel contract type |
| `plugin-sdk/channel-feedback` | feedback/reaction wiring |
| `plugin-sdk/channel-secret-runtime` | `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`、およびsecret target typeのような狭いsecret-contract helper |
</Accordion>
<Accordion title="Provider サブパス">
| サブパス | 主なエクスポート |
<Accordion title="Provider subpaths">
| Subpath | 主なexports |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 厳選されたローカル/セルフホスト provider setup helper |
| `plugin-sdk/self-hosted-provider-setup` | OpenAI 互換セルフホスト provider 向けの特化した setup helper |
| `plugin-sdk/cli-backend` | CLI backend デフォルト + watchdog 定数 |
| `plugin-sdk/provider-auth-runtime` | provider plugins 向け runtime API-key 解決 helper |
| `plugin-sdk/provider-auth-api-key` | `upsertApiKeyProfile` のような API-key オンボーディング/profile-write helper |
| `plugin-sdk/provider-auth-result` | 標準 OAuth auth-result builder |
| `plugin-sdk/provider-auth-login` | provider plugins 向け共有対話型 login helper |
| `plugin-sdk/provider-setup` | 厳選されたlocal/self-hosted provider setup helper |
| `plugin-sdk/self-hosted-provider-setup` | OpenAI互換のself-hosted provider setupに特化したhelper |
| `plugin-sdk/cli-backend` | CLI backend default + watchdog定数 |
| `plugin-sdk/provider-auth-runtime` | Provider Plugin向けruntime API key解決helper |
| `plugin-sdk/provider-auth-api-key` | `upsertApiKeyProfile`などのAPI keyオンボーディング/profile-write helper |
| `plugin-sdk/provider-auth-result` | 標準OAuth auth-result builder |
| `plugin-sdk/provider-auth-login` | Provider Plugin向け共有interactive login helper |
| `plugin-sdk/provider-env-vars` | provider auth env-var lookup helper |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共有 replay-policy builder、provider-endpoint helper、および `normalizeNativeXaiModelId` のような model-id 正規化 helper |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共有replay-policy builder、provider-endpoint helper、および`normalizeNativeXaiModelId`のようなmodel-id正規化helper |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 汎用 provider HTTP/endpoint capability helper |
| `plugin-sdk/provider-web-fetch-contract` | `enablePluginInConfig` や `WebFetchProviderPlugin` のような、狭い web-fetch config/selection contract helper |
| `plugin-sdk/provider-web-fetch` | Web-fetch provider registration/cache helper |
| `plugin-sdk/provider-web-search-config-contract` | plugin-enable 配線を必要としない providers 向けの、狭い web-search config/credential helper |
| `plugin-sdk/provider-web-search-contract` | `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`、およびスコープ付き credential setter/getter のような、狭い web-search config/credential contract helper |
| `plugin-sdk/provider-web-search` | Web-search provider registration/cache/runtime helper |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema cleanup + diagnostics、および `resolveXaiModelCompatPatch` / `applyXaiModelCompat` のような xAI compat helper |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` など |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、stream wrapper 型、および共有 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helper |
| `plugin-sdk/provider-onboard` | オンボーディング config patch helper |
| `plugin-sdk/global-singleton` | プロセスローカル singleton/map/cache helper |
| `plugin-sdk/provider-http` | 汎用provider HTTP/endpoint capability helper |
| `plugin-sdk/provider-web-fetch-contract` | `enablePluginInConfig`や`WebFetchProviderPlugin`などの狭いweb-fetch config/selection contract helper |
| `plugin-sdk/provider-web-fetch` | web-fetch provider registration/cache helper |
| `plugin-sdk/provider-web-search-config-contract` | Plugin有効化wiringを必要としないprovider向けの狭いweb-search config/credential helper |
| `plugin-sdk/provider-web-search-contract` | `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`、およびスコープ付きcredential setter/getterなどの狭いweb-search config/credential contract helper |
| `plugin-sdk/provider-web-search` | web-search provider registration/cache/runtime helper |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema cleanup + diagnostics、および`resolveXaiModelCompatPatch` / `applyXaiModelCompat`のようなxAI互換helper |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage`など |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、stream wrapper type、および共有Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helper |
| `plugin-sdk/provider-onboard` | オンボーディングconfig patch helper |
| `plugin-sdk/global-singleton` | process-local singleton/map/cache helper |
</Accordion>
<Accordion title="認証とセキュリティのサブパス">
| サブパス | 主なエクスポート |
<Accordion title="認証およびセキュリティのサブパス">
| Subpath | 主なexports |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、command registry helper、sender-authorization helper |
| `plugin-sdk/command-status` | `buildCommandsMessagePaginated` や `buildHelpMessage` のような command/help message builder |
| `plugin-sdk/approval-auth-runtime` | approver 解決と same-chat action-auth helper |
| `plugin-sdk/approval-client-runtime` | ネイティブ exec approval profile/filter helper |
| `plugin-sdk/approval-delivery-runtime` | ネイティブ approval capability/delivery adapter |
| `plugin-sdk/approval-gateway-runtime` | 共有 approval gateway-resolution helper |
| `plugin-sdk/approval-handler-adapter-runtime` | ホットな channel entrypoint 向けの軽量なネイティブ approval adapter 読み込み helper |
| `plugin-sdk/approval-handler-runtime` | より広い approval handler runtime helper。より狭い adapter/gateway seam で足りる場合はそちらを優先してください |
| `plugin-sdk/approval-native-runtime` | ネイティブ approval target + account-binding helper |
| `plugin-sdk/command-status` | `buildCommandsMessagePaginated`や`buildHelpMessage`などのcommand/help message builder |
| `plugin-sdk/approval-auth-runtime` | approver解決およびsame-chat action-auth helper |
| `plugin-sdk/approval-client-runtime` | native exec approval profile/filter helper |
| `plugin-sdk/approval-delivery-runtime` | native approval capability/delivery adapter |
| `plugin-sdk/approval-gateway-runtime` | 共有approval gateway-resolution helper |
| `plugin-sdk/approval-handler-adapter-runtime` | ホットなchannel entrypoint向けの軽量native approval adapter読み込みhelper |
| `plugin-sdk/approval-handler-runtime` | より広範なapproval handler runtime helper。より狭いadapter/gateway seamで十分な場合はそちらを優先してください |
| `plugin-sdk/approval-native-runtime` | native approval target + account-binding helper |
| `plugin-sdk/approval-reply-runtime` | exec/plugin approval reply payload helper |
| `plugin-sdk/command-auth-native` | ネイティブ command auth + ネイティブ session-target helper |
| `plugin-sdk/command-detection` | 共有 command 検出 helper |
| `plugin-sdk/command-surface` | command-body 正規化と command-surface helper |
| `plugin-sdk/command-auth-native` | native command auth + native session-target helper |
| `plugin-sdk/command-detection` | 共有command detection helper |
| `plugin-sdk/command-surface` | command-body正規化およびcommand-surface helper |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | channel/plugin の secret surface 向けの狭い secret-contract 収集 helper |
| `plugin-sdk/secret-ref-runtime` | secret-contract/config parsing 向けの狭い `coerceSecretRef` と SecretRef 型 helper |
| `plugin-sdk/security-runtime` | 共有 trust、DM gating、external-content、secret-collection helper |
| `plugin-sdk/ssrf-policy` | host allowlist と private-network SSRF policy helper |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRF ガード付き fetch、および SSRF policy helper |
| `plugin-sdk/secret-input` | secret input 解析 helper |
| `plugin-sdk/webhook-ingress` | webhook request/target helper |
| `plugin-sdk/channel-secret-runtime` | channel/plugin secret surface向けの狭いsecret-contract collection helper |
| `plugin-sdk/secret-ref-runtime` | secret-contract/config parsing向けの狭い`coerceSecretRef`およびSecretRef型付けhelper |
| `plugin-sdk/security-runtime` | 共有trust、DM gating、external-content、およびsecret-collection helper |
| `plugin-sdk/ssrf-policy` | host allowlistおよびprivate-network SSRF policy helper |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRF-guarded fetch、およびSSRF policy helper |
| `plugin-sdk/secret-input` | secret input parsing helper |
| `plugin-sdk/webhook-ingress` | Webhook request/target helper |
| `plugin-sdk/webhook-request-guards` | request body size/timeout helper |
</Accordion>
<Accordion title="Runtime とストレージのサブパス">
| サブパス | 主なエクスポート |
<Accordion title="ランタイムおよびストレージのサブパス">
| Subpath | 主なexports |
| --- | --- |
| `plugin-sdk/runtime` | 幅広い runtime/logging/backup/plugin-install helper |
| `plugin-sdk/runtime-env` | 狭い runtime env、logger、timeout、retry、backoff helper |
| `plugin-sdk/channel-runtime-context` | 汎用 channel runtime-context の登録および lookup helper |
| `plugin-sdk/runtime` | 広範なruntime/logging/backup/plugin-install helper |
| `plugin-sdk/runtime-env` | 狭いruntime env、logger、timeout、retry、およびbackoff helper |
| `plugin-sdk/channel-runtime-context` | 汎用channel runtime-context登録およびlookup helper |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共有 plugin command/hook/http/interactive helper |
| `plugin-sdk/hook-runtime` | 共有 webhook/internal hook pipeline helper |
| `plugin-sdk/lazy-runtime` | `createLazyRuntimeModule`、`createLazyRuntimeMethod`、`createLazyRuntimeSurface` などの lazy runtime import/binding helper |
| `plugin-sdk/plugin-runtime` | 共有plugin command/hook/http/interactive helper |
| `plugin-sdk/hook-runtime` | 共有Webhook/internal hook pipeline helper |
| `plugin-sdk/lazy-runtime` | `createLazyRuntimeModule`、`createLazyRuntimeMethod`、`createLazyRuntimeSurface`などのlazy runtime import/binding helper |
| `plugin-sdk/process-runtime` | process exec helper |
| `plugin-sdk/cli-runtime` | CLI format、wait、version helper |
| `plugin-sdk/gateway-runtime` | Gateway client と channel-status patch helper |
| `plugin-sdk/config-runtime` | Config load/write helper |
| `plugin-sdk/telegram-command-config` | bundled Telegram contract surface が利用できない場合でも使える、Telegram command-name/description の正規化と duplicate/conflict チェック |
| `plugin-sdk/cli-runtime` | CLI formatting、wait、およびversion helper |
| `plugin-sdk/gateway-runtime` | Gateway clientおよびchannel-status patch helper |
| `plugin-sdk/config-runtime` | config load/write helper |
| `plugin-sdk/telegram-command-config` | bundled Telegram contract surfaceが利用できない場合でも使える、Telegram command-name/description正規化およびduplicate/conflict check |
| `plugin-sdk/approval-runtime` | exec/plugin approval helper、approval-capability builder、auth/profile helper、native routing/runtime helper |
| `plugin-sdk/reply-runtime` | 共有 inbound/reply runtime helper、chunking、dispatch、heartbeat、reply planner |
| `plugin-sdk/reply-dispatch-runtime` | 狭い reply dispatch/finalize helper |
| `plugin-sdk/reply-history` | `buildHistoryContext`、`recordPendingHistoryEntry`、`clearHistoryEntriesIfEnabled` のような、共有の短期間 reply-history helper |
| `plugin-sdk/reply-runtime` | 共有inbound/reply runtime helper、chunking、dispatch、Heartbeat、reply planner |
| `plugin-sdk/reply-dispatch-runtime` | 狭いreply dispatch/finalize helper |
| `plugin-sdk/reply-history` | `buildHistoryContext`、`recordPendingHistoryEntry`、`clearHistoryEntriesIfEnabled`などの共有short-window reply-history helper |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 狭い text/markdown chunking helper |
| `plugin-sdk/reply-chunking` | 狭いtext/markdown chunking helper |
| `plugin-sdk/session-store-runtime` | session store path + updated-at helper |
| `plugin-sdk/state-paths` | state/OAuth dir path helper |
| `plugin-sdk/routing` | `resolveAgentRoute`、`buildAgentSessionKey`、`resolveDefaultAgentBoundAccountId` などの route/session-key/account binding helper |
| `plugin-sdk/status-helpers` | 共有 channel/account status summary helper、runtime-state デフォルト、および issue metadata helper |
| `plugin-sdk/target-resolver-runtime` | 共有 target resolver helper |
| `plugin-sdk/string-normalization-runtime` | slug/string 正規化 helper |
| `plugin-sdk/request-url` | fetch/request 風の入力から文字列 URL を抽出する |
| `plugin-sdk/run-command` | stdout/stderr 結果を正規化したタイム付き command runner |
| `plugin-sdk/param-readers` | 共通 tool/CLI param reader |
| `plugin-sdk/tool-payload` | tool result object から正規化された payload を抽出する |
| `plugin-sdk/tool-send` | tool args から正規の send target フィールドを抽出する |
| `plugin-sdk/temp-path` | 共有 temp-download path helper |
| `plugin-sdk/logging-core` | subsystem logger と redaction helper |
| `plugin-sdk/routing` | `resolveAgentRoute`、`buildAgentSessionKey`、`resolveDefaultAgentBoundAccountId`などのroute/session-key/account binding helper |
| `plugin-sdk/status-helpers` | 共有channel/account status summary helper、runtime-state default、およびissue metadata helper |
| `plugin-sdk/target-resolver-runtime` | 共有target resolver helper |
| `plugin-sdk/string-normalization-runtime` | slug/string正規化helper |
| `plugin-sdk/request-url` | fetch/requestライクな入力から文字列URLを抽出 |
| `plugin-sdk/run-command` | 正規化されたstdout/stderr結果を返すtimed command runner |
| `plugin-sdk/param-readers` | 共通tool/CLI param reader |
| `plugin-sdk/tool-payload` | tool result objectから正規化済みpayloadを抽出 |
| `plugin-sdk/tool-send` | tool argsからcanonical send target fieldを抽出 |
| `plugin-sdk/temp-path` | 共有temp-download path helper |
| `plugin-sdk/logging-core` | subsystem loggerおよびredaction helper |
| `plugin-sdk/markdown-table-runtime` | Markdown table mode helper |
| `plugin-sdk/json-store` | 小さな JSON state の read/write helper |
| `plugin-sdk/file-lock` | 再入可能 file-lock helper |
| `plugin-sdk/persistent-dedupe` | ディスクベースの dedupe cache helper |
| `plugin-sdk/acp-runtime` | ACP runtime/session と reply-dispatch helper |
| `plugin-sdk/agent-config-primitives` | 狭い agent runtime config-schema primitive |
| `plugin-sdk/boolean-param` | 緩い boolean param reader |
| `plugin-sdk/dangerous-name-runtime` | dangerous-name matching 解決 helper |
| `plugin-sdk/device-bootstrap` | device bootstrap と pairing token helper |
| `plugin-sdk/extension-shared` | 共有 passive-channel、status、および ambient proxy helper primitive |
| `plugin-sdk/json-store` | 小さなJSON state read/write helper |
| `plugin-sdk/file-lock` | 再入可能なfile-lock helper |
| `plugin-sdk/persistent-dedupe` | disk-backed dedupe cache helper |
| `plugin-sdk/acp-runtime` | ACP runtime/sessionおよびreply-dispatch helper |
| `plugin-sdk/agent-config-primitives` | 狭いagent runtime config-schema primitive |
| `plugin-sdk/boolean-param` | 緩いboolean param reader |
| `plugin-sdk/dangerous-name-runtime` | dangerous-name matching解決helper |
| `plugin-sdk/device-bootstrap` | device bootstrapおよびpairing token helper |
| `plugin-sdk/extension-shared` | 共有passive-channel、status、およびambient proxy helper primitive |
| `plugin-sdk/models-provider-runtime` | `/models` command/provider reply helper |
| `plugin-sdk/skill-commands-runtime` | skill command listing helper |
| `plugin-sdk/native-command-registry` | ネイティブ command registry/build/serialize helper |
| `plugin-sdk/agent-harness` | 低レベル agent harness 向けの実験的 trusted-plugin surface: harness 型、active-run の steer/abort helper、OpenClaw tool bridge helper、および attempt result utility |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 検出 helper |
| `plugin-sdk/infra-runtime` | system event/heartbeat helper |
| `plugin-sdk/collection-runtime` | 小さな上限制 cache helper |
| `plugin-sdk/diagnostic-runtime` | diagnostic flag と event helper |
| `plugin-sdk/error-runtime` | error graph、format、共有 error classification helper、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | wrapped fetch、proxy、および pinned lookup helper |
| `plugin-sdk/host-runtime` | hostname と SCP host 正規化 helper |
| `plugin-sdk/retry-runtime` | retry config と retry runner helper |
| `plugin-sdk/skill-commands-runtime` | Skills command listing helper |
| `plugin-sdk/native-command-registry` | native command registry/build/serialize helper |
| `plugin-sdk/agent-harness` | 低レベルagent harness向けの実験的trusted-plugin surface: harness type、active-run steer/abort helper、OpenClaw tool bridge helper、およびattempt result utility |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint detection helper |
| `plugin-sdk/infra-runtime` | system event/Heartbeat helper |
| `plugin-sdk/collection-runtime` | 小さなbounded cache helper |
| `plugin-sdk/diagnostic-runtime` | diagnostic flagおよびevent helper |
| `plugin-sdk/error-runtime` | error graph、formatting、共有error classification helper、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | wrapped fetch、proxy、およびpinned lookup helper |
| `plugin-sdk/host-runtime` | hostnameおよびSCP host正規化helper |
| `plugin-sdk/retry-runtime` | retry configおよびretry runner helper |
| `plugin-sdk/agent-runtime` | agent dir/identity/workspace helper |
| `plugin-sdk/directory-runtime` | config ベースの directory query/dedup |
| `plugin-sdk/directory-runtime` | config-backed directory query/dedup |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Capability とテストのサブパス">
| サブパス | 主なエクスポート |
<Accordion title="Capabilityおよびテストのサブパス">
| Subpath | 主なexports |
| --- | --- |
| `plugin-sdk/media-runtime` | 共有 media fetch/transform/store helper と media payload builder |
| `plugin-sdk/media-generation-runtime` | 共有 media-generation failover helper、candidate selection、および missing-model messaging |
| `plugin-sdk/media-understanding` | media understanding provider 型と provider 向け image/audio helper エクスポート |
| `plugin-sdk/text-runtime` | assistant-visible-text の除去、markdown render/chunking/table helper、redaction helper、directive-tag helper、安全な text utility などの共有 text/markdown/logging helper |
| `plugin-sdk/media-runtime` | media payload builderに加え、共有media fetch/transform/store helper |
| `plugin-sdk/media-generation-runtime` | 共有media-generation failover helper、candidate selection、およびmissing-model messaging |
| `plugin-sdk/media-understanding` | media understanding provider typeおよびprovider向けimage/audio helper export |
| `plugin-sdk/text-runtime` | assistant-visible-text stripping、markdown render/chunking/table helper、redaction helper、directive-tag helper、安全なtext utilityなどの共有text/markdown/logging helper |
| `plugin-sdk/text-chunking` | outbound text chunking helper |
| `plugin-sdk/speech` | speech provider 型と provider 向け directive、registry、validation helper |
| `plugin-sdk/speech-core` | 共有 speech provider 型、registry、directive、および正規化 helper |
| `plugin-sdk/realtime-transcription` | realtime transcription provider 型と registry helper |
| `plugin-sdk/realtime-voice` | realtime voice provider 型と registry helper |
| `plugin-sdk/image-generation` | image generation provider 型 |
| `plugin-sdk/image-generation-core` | 共有 image-generation 型、failover、auth、および registry helper |
| `plugin-sdk/music-generation` | music generation provider/request/result 型 |
| `plugin-sdk/music-generation-core` | 共有 music-generation 型、failover helper、provider lookup、および model-ref parsing |
| `plugin-sdk/video-generation` | video generation provider/request/result 型 |
| `plugin-sdk/video-generation-core` | 共有 video-generation 型、failover helper、provider lookup、および model-ref parsing |
| `plugin-sdk/webhook-targets` | webhook target registry と route-install helper |
| `plugin-sdk/webhook-path` | webhook path 正規化 helper |
| `plugin-sdk/web-media` | 共有 remote/local media 読み込み helper |
| `plugin-sdk/zod` | plugin SDK 利用者向けに再エクスポートされた `zod` |
| `plugin-sdk/speech` | speech provider typeおよびprovider向けdirective、registry、validation helper |
| `plugin-sdk/speech-core` | 共有speech provider type、registry、directive、および正規化helper |
| `plugin-sdk/realtime-transcription` | realtime transcription provider typeおよびregistry helper |
| `plugin-sdk/realtime-voice` | realtime voice provider typeおよびregistry helper |
| `plugin-sdk/image-generation` | image generation provider type |
| `plugin-sdk/image-generation-core` | 共有image-generation type、failover、auth、およびregistry helper |
| `plugin-sdk/music-generation` | music generation provider/request/result type |
| `plugin-sdk/music-generation-core` | 共有music-generation type、failover helper、provider lookup、およびmodel-ref parsing |
| `plugin-sdk/video-generation` | video generation provider/request/result type |
| `plugin-sdk/video-generation-core` | 共有video-generation type、failover helper、provider lookup、およびmodel-ref parsing |
| `plugin-sdk/webhook-targets` | Webhook target registryおよびroute-install helper |
| `plugin-sdk/webhook-path` | Webhook path正規化helper |
| `plugin-sdk/web-media` | 共有remote/local media読み込みhelper |
| `plugin-sdk/zod` | Plugin SDK利用者向けにre-exportされた`zod` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="メモリのサブパス">
| サブパス | 主なエクスポート |
| Subpath | 主なexports |
| --- | --- |
| `plugin-sdk/memory-core` | manager/config/file/CLI helper 向け bundled memory-core helper surface |
| `plugin-sdk/memory-core` | manager/config/file/CLI helper向けのbundled memory-core helper surface |
| `plugin-sdk/memory-core-engine-runtime` | memory index/search runtime facade |
| `plugin-sdk/memory-core-host-engine-foundation` | memory host foundation engine エクスポート |
| `plugin-sdk/memory-core-host-engine-embeddings` | memory host embedding engine エクスポート |
| `plugin-sdk/memory-core-host-engine-qmd` | memory host QMD engine エクスポート |
| `plugin-sdk/memory-core-host-engine-storage` | memory host storage engine エクスポート |
| `plugin-sdk/memory-core-host-engine-foundation` | memory host foundation engine export |
| `plugin-sdk/memory-core-host-engine-embeddings` | memory host embedding contract、registry access、local provider、および汎用batch/remote helper |
| `plugin-sdk/memory-core-host-engine-qmd` | memory host QMD engine export |
| `plugin-sdk/memory-core-host-engine-storage` | memory host storage engine export |
| `plugin-sdk/memory-core-host-multimodal` | memory host multimodal helper |
| `plugin-sdk/memory-core-host-query` | memory host query helper |
| `plugin-sdk/memory-core-host-secret` | memory host secret helper |
@ -279,85 +263,79 @@ SDK サブパスを自前の `api.ts` または `runtime-api.ts` barrel 内で
| `plugin-sdk/memory-core-host-runtime-cli` | memory host CLI runtime helper |
| `plugin-sdk/memory-core-host-runtime-core` | memory host core runtime helper |
| `plugin-sdk/memory-core-host-runtime-files` | memory host file/runtime helper |
| `plugin-sdk/memory-host-core` | memory host core runtime helper の vendor-neutral alias |
| `plugin-sdk/memory-host-events` | memory host event journal helper の vendor-neutral alias |
| `plugin-sdk/memory-host-files` | memory host file/runtime helper の vendor-neutral alias |
| `plugin-sdk/memory-host-markdown` | memory 隣接 plugin 向けの共有 managed-markdown helper |
| `plugin-sdk/memory-host-search` | search-manager access 用の active memory runtime facade |
| `plugin-sdk/memory-host-status` | memory host status helper の vendor-neutral alias |
| `plugin-sdk/memory-host-core` | memory host core runtime helperのvendor-neutral alias |
| `plugin-sdk/memory-host-events` | memory host event journal helperのvendor-neutral alias |
| `plugin-sdk/memory-host-files` | memory host file/runtime helperのvendor-neutral alias |
| `plugin-sdk/memory-host-markdown` | memory隣接Plugin向けの共有managed-markdown helper |
| `plugin-sdk/memory-host-search` | search-manager access向けのActive Memory runtime facade |
| `plugin-sdk/memory-host-status` | memory host status helperのvendor-neutral alias |
| `plugin-sdk/memory-lancedb` | bundled memory-lancedb helper surface |
</Accordion>
<Accordion title="予約済み bundled-helper サブパス">
| ファミリー | 現在のサブパス | 想定される用途 |
<Accordion title="予約済みbundled-helperサブパス">
| Family | 現在のサブパス | 想定用途 |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser plugin サポート helper（`browser-support` は互換性 barrel のまま） |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser Pluginサポートhelper（`browser-support`は互換性barrelのままです） |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | bundled Matrix helper/runtime surface |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE helper/runtime surface |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled IRC helper surface |
| Channel 固有 helper | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled channel 互換性/helper seam |
| Auth/plugin 固有 helper | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled feature/plugin helper seam。`plugin-sdk/github-copilot-token` は現在 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken`、`resolveCopilotApiToken` をエクスポートします |
| channel固有helper | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled channel互換性/helper seam |
| 認証/Plugin固有helper | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled feature/Plugin helper seam。`plugin-sdk/github-copilot-token`は現在`DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken`、`resolveCopilotApiToken`をexportします |
</Accordion>
</AccordionGroup>
## 登録 API
## 登録API
`register(api)` コールバックは、以下のメソッドを持つ `OpenClawPluginApi` オブジェクトを受け取ります。
`register(api)`コールバックは、次のメソッドを持つ`OpenClawPluginApi`オブジェクトを受け取ります。
### Capability の登録
### Capability登録
| メソッド | 登録するもの |
| ------------------------------------------------ | -------------------------------- |
| `api.registerProvider(...)` | テキスト推論（LLM） |
| `api.registerAgentHarness(...)` | 実験的な低レベル agent executor |
| `api.registerCliBackend(...)` | ローカル CLI 推論バックエンド |
| `api.registerChannel(...)` | メッセージング channel |
| `api.registerSpeechProvider(...)` | Text-to-speech / STT synthesis |
| `api.registerRealtimeTranscriptionProvider(...)` | ストリーミング realtime transcription |
| `api.registerRealtimeVoiceProvider(...)` | 双方向 realtime voice セッション |
| `api.registerMediaUnderstandingProvider(...)` | 画像/音声/動画解析 |
| `api.registerImageGenerationProvider(...)` | 画像生成 |
| `api.registerMusicGenerationProvider(...)` | 音楽生成 |
| `api.registerVideoGenerationProvider(...)` | 動画生成 |
| `api.registerWebFetchProvider(...)` | Web fetch / scrape provider |
| `api.registerWebSearchProvider(...)` | Web search |
| Method | 登録するもの |
| ------------------------------------------------ | ----------------------------------- |
| `api.registerProvider(...)` | テキスト推論（LLM） |
| `api.registerAgentHarness(...)` | 実験的な低レベルagent executor |
| `api.registerCliBackend(...)` | ローカルCLI推論backend |
| `api.registerChannel(...)` | メッセージングchannel |
| `api.registerSpeechProvider(...)` | text-to-speech / STT synthesis |
| `api.registerRealtimeTranscriptionProvider(...)` | ストリーミングリアルタイム文字起こし |
| `api.registerRealtimeVoiceProvider(...)` | 双方向リアルタイム音声セッション |
| `api.registerMediaUnderstandingProvider(...)` | 画像/音声/動画解析 |
| `api.registerImageGenerationProvider(...)` | 画像生成 |
| `api.registerMusicGenerationProvider(...)` | 音楽生成 |
| `api.registerVideoGenerationProvider(...)` | 動画生成 |
| `api.registerWebFetchProvider(...)` | Web fetch / scrape provider |
| `api.registerWebSearchProvider(...)` | Web検索 |
### Tools と commands
### Toolsとcommands
| メソッド | 登録するもの |
| ------------------------------- | --------------------------------------- |
| `api.registerTool(tool, opts?)` | agent tool（必須、または `{ optional: true }`） |
| `api.registerCommand(def)` | カスタム command（LLM をバイパス） |
| Method | 登録するもの |
| ------------------------------- | ------------------------------------------- |
| `api.registerTool(tool, opts?)` | agent tool（必須または`{ optional: true }`） |
| `api.registerCommand(def)` | カスタムcommand（LLMをバイパス） |
### インフラストラクチャ
| メソッド | 登録するもの |
| ---------------------------------------------- | --------------------------- |
| `api.registerHook(events, handler, opts?)` | イベント hook |
| `api.registerHttpRoute(params)` | Gateway HTTP エンドポイント |
| `api.registerGatewayMethod(name, handler)` | Gateway RPC メソッド |
| `api.registerCli(registrar, opts?)` | CLI サブコマンド |
| `api.registerService(service)` | バックグラウンド service |
| `api.registerInteractiveHandler(registration)` | interactive handler |
| `api.registerMemoryPromptSupplement(builder)` | 加算的な memory 隣接 prompt セクション |
| `api.registerMemoryCorpusSupplement(adapter)` | 加算的な memory search/read corpus |
| Method | 登録するもの |
| ---------------------------------------------- | ------------------------------------- |
| `api.registerHook(events, handler, opts?)` | イベントhook |
| `api.registerHttpRoute(params)` | Gateway HTTP endpoint |
| `api.registerGatewayMethod(name, handler)` | Gateway RPC method |
| `api.registerCli(registrar, opts?)` | CLIサブコマンド |
| `api.registerService(service)` | バックグラウンドサービス |
| `api.registerInteractiveHandler(registration)` | interactive handler |
| `api.registerMemoryPromptSupplement(builder)` | 加算的なmemory隣接prompt section |
| `api.registerMemoryCorpusSupplement(adapter)` | 加算的なmemory search/read corpus |
予約済みの core 管理 namespace（`config.*`、`exec.approvals.*`、`wizard.*`、
`update.*`）は、plugin がより狭い gateway method scope を割り当てようとしても、
常に `operator.admin` のままです。
plugin 所有のメソッドには、plugin 固有の prefix を優先してください。
予約済みのcore admin namespace（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は、Pluginがより狭いGateway method scopeを割り当てようとしても、常に`operator.admin`のままです。Plugin所有のmethodには、Plugin固有のprefixを優先してください。
### CLI 登録メタデータ
### CLI登録メタデータ
`api.registerCli(registrar, opts?)` は、2 種類のトップレベルメタデータを受け付けます。
`api.registerCli(registrar, opts?)`は、2種類のトップレベルメタデータを受け取ります。
- `commands`: registrar が所有する明示的な command ルート
- `descriptors`: ルート CLI ヘルプ、
ルーティング、および lazy plugin CLI 登録のために parse 時に使われる command descriptor
- `commands`: registrarが所有する明示的なcommand root
- `descriptors`: ルートCLI help、routing、およびlazy Plugin CLI登録に使われるparse-time command descriptor
plugin command を通常のルート CLI パスで lazy-loaded のままにしたい場合は、
その registrar が公開するすべてのトップレベル command ルートをカバーする `descriptors`
を指定してください。
Plugin commandを通常のルートCLIパスでlazy-loadedのままにしたい場合は、そのregistrarが公開するすべてのトップレベルcommand rootをカバーする`descriptors`を指定してください。
```typescript
api.registerCli(
@ -369,7 +347,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "Matrix アカウント、検証、デバイス、および profile 状態を管理する",
description: "Matrixアカウント、認証、デバイス、およびprofile stateを管理する",
hasSubcommands: true,
},
],
@ -377,134 +355,113 @@ api.registerCli(
);
```
lazy なルート CLI 登録が不要な場合にのみ、`commands` 単独を使用してください。
この eager 互換パスも引き続きサポートされていますが、parse 時 lazy loading 用の
descriptor ベースの placeholder はインストールされません。
`commands`単体を使うのは、lazyなルートCLI登録が不要な場合だけにしてください。そのeager互換パスは引き続きサポートされていますが、parse-time lazy loadingのためのdescriptor-backed placeholderはインストールされません。
### CLI バックエンド登録
### CLI backend登録
`api.registerCliBackend(...)` により、plugin は `codex-cli` のようなローカル
AI CLI バックエンドのデフォルト設定を所有できます。
`api.registerCliBackend(...)`を使うと、Pluginが`codex-cli`のようなローカルAI CLI backendのdefault configを所有できます。
- バックエンドの `id` は、`codex-cli/gpt-5` のような model ref における provider prefix になります。
- バックエンド `config` は、`agents.defaults.cliBackends.<id>` と同じ shape を使います。
- ユーザー設定が引き続き優先されます。OpenClaw は CLI 実行前に `agents.defaults.cliBackends.<id>` を
plugin デフォルトの上にマージします。
- マージ後に互換性のための書き換えが必要なバックエンドでは、
`normalizeConfig` を使用してください
（たとえば古い flag shape の正規化など）。
- backendの`id`は、`codex-cli/gpt-5`のようなmodel ref内のprovider prefixになります。
- backendの`config`は、`agents.defaults.cliBackends.<id>`と同じ形を使います。
- ユーザーconfigが引き続き優先されます。OpenClawは、CLIを実行する前に、Plugin defaultの上に`agents.defaults.cliBackends.<id>`をマージします。
- マージ後にbackendが互換性書き換えを必要とする場合（たとえば古いflag形状の正規化など）は、`normalizeConfig`を使ってください。
### 排他的スロット
| メソッド | 登録するもの |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | コンテキストエンジン（一度に 1 つだけアクティブ）。`assemble()` コールバックは `availableTools` と `citationsMode` を受け取り、エンジンが prompt 追加内容を調整できるようにします。 |
| `api.registerMemoryCapability(capability)` | 統一メモリ capability |
| `api.registerMemoryPromptSection(builder)` | メモリ prompt セクション builder |
| `api.registerMemoryFlushPlan(resolver)` | メモリ flush plan resolver |
| `api.registerMemoryRuntime(runtime)` | メモリ runtime adapter |
| Method | 登録するもの |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Context engine（一度に1つだけ有効）。`assemble()`コールバックは`availableTools`と`citationsMode`を受け取るため、engineはそれに合わせてprompt追加を調整できます。 |
| `api.registerMemoryCapability(capability)` | 統一memory capability |
| `api.registerMemoryPromptSection(builder)` | memory prompt section builder |
| `api.registerMemoryFlushPlan(resolver)` | memory flush plan resolver |
| `api.registerMemoryRuntime(runtime)` | memory runtime adapter |
### メモリ embedding adapter
### Memory embedding adapter
| メソッド | 登録するもの |
| ---------------------------------------------- | ------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | アクティブな plugin 用のメモリ embedding adapter |
| Method | 登録するもの |
| ---------------------------------------------- | -------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | アクティブなPlugin向けmemory embedding adapter |
- `registerMemoryCapability` は、推奨される排他的 memory-plugin API です。
- `registerMemoryCapability` は `publicArtifacts.listArtifacts(...)` も公開でき、
companion plugins が特定の
memory plugin の private layout に入り込むのではなく、
`openclaw/plugin-sdk/memory-host-core` を通じてエクスポートされた memory artifacts を利用できるようにします。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan`、および
`registerMemoryRuntime` は、レガシー互換の排他的 memory-plugin API です。
- `registerMemoryEmbeddingProvider` により、アクティブな memory plugin は
1 つ以上の embedding adapter id（例: `openai`、`gemini`、または plugin 定義のカスタム id）を登録できます。
- `agents.defaults.memorySearch.provider` や
`agents.defaults.memorySearch.fallback` のようなユーザー設定は、
それらの登録済み adapter id に対して解決されます。
- `registerMemoryCapability`は、推奨される排他的memory-Plugin APIです。
- `registerMemoryCapability`は、companion Pluginが特定のmemory Pluginのprivate layoutに入り込む代わりに、`openclaw/plugin-sdk/memory-host-core`を通じてexportされたmemory artifactを利用できるよう、`publicArtifacts.listArtifacts(...)`を公開することもできます。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan`、および`registerMemoryRuntime`は、legacy互換の排他的memory-Plugin APIです。
- `registerMemoryEmbeddingProvider`を使うと、アクティブmemory Pluginは1つ以上のembedding adapter id（たとえば`openai`、`gemini`、またはPlugin定義のカスタムid）を登録できます。
- `agents.defaults.memorySearch.provider`や`agents.defaults.memorySearch.fallback`のようなユーザーconfigは、それらの登録済みadapter idに対して解決されます。
### イベントとライフサイクル
| メソッド | 役割 |
| -------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | 型付きライフサイクル hook |
| `api.onConversationBindingResolved(handler)` | 会話バインディング callback |
| Method | 動作内容 |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | 型付きライフサイクルhook |
| `api.onConversationBindingResolved(handler)` | conversation bindingコールバック |
### Hook 判定セマンティクス
### Hook決定セマンティクス
- `before_tool_call`: `{ block: true }` を返すと終端です。いずれかの handler がこれを設定すると、優先度の低い handler はスキップされます。
- `before_tool_call`: `{ block: false }` を返しても判定なしとして扱われます（`block` を省略した場合と同じ）であり、上書きではありません。
- `before_install`: `{ block: true }` を返すと終端です。いずれかの handler がこれを設定すると、優先度の低い handler はスキップされます。
- `before_install`: `{ block: false }` を返しても判定なしとして扱われます（`block` を省略した場合と同じ）であり、上書きではありません。
- `reply_dispatch`: `{ handled: true, ... }` を返すと終端です。いずれかの handler が dispatch を引き受けると、優先度の低い handler とデフォルトの model dispatch パスはスキップされます。
- `message_sending`: `{ cancel: true }` を返すと終端です。いずれかの handler がこれを設定すると、優先度の低い handler はスキップされます。
- `message_sending`: `{ cancel: false }` を返しても判定なしとして扱われます（`cancel` を省略した場合と同じ）であり、上書きではありません。
- `before_tool_call`: `{ block: true }`を返すと終端です。いずれかのhandlerがこれを設定すると、より低い優先度のhandlerはスキップされます。
- `before_tool_call`: `{ block: false }`を返しても決定なしとして扱われます（`block`を省略した場合と同じ）であり、オーバーライドではありません。
- `before_install`: `{ block: true }`を返すと終端です。いずれかのhandlerがこれを設定すると、より低い優先度のhandlerはスキップされます。
- `before_install`: `{ block: false }`を返しても決定なしとして扱われます（`block`を省略した場合と同じ）であり、オーバーライドではありません。
- `reply_dispatch`: `{ handled: true, ... }`を返すと終端です。いずれかのhandlerがdispatchを引き受けると、より低い優先度のhandlerとデフォルトのmodel dispatch pathはスキップされます。
- `message_sending`: `{ cancel: true }`を返すと終端です。いずれかのhandlerがこれを設定すると、より低い優先度のhandlerはスキップされます。
- `message_sending`: `{ cancel: false }`を返しても決定なしとして扱われます（`cancel`を省略した場合と同じ）であり、オーバーライドではありません。
### API オブジェクトのフィールド
### APIオブジェクトのフィールド
| フィールド | 型 | 説明 |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Plugin id |
| `api.name` | `string` | 表示名 |
| `api.version` | `string?` | Plugin version（任意） |
| `api.description` | `string?` | Plugin の説明（任意） |
| `api.source` | `string` | Plugin のソースパス |
| `api.rootDir` | `string?` | Plugin のルートディレクトリ（任意） |
| `api.config` | `OpenClawConfig` | 現在の config スナップショット（利用可能な場合は、アクティブなインメモリ runtime スナップショット） |
| `api.pluginConfig` | `Record<string, unknown>` | `plugins.entries.<id>.config` からの plugin 固有 config |
| `api.runtime` | `PluginRuntime` | [Runtime helpers](/ja-JP/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | スコープ付き logger（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 現在の load mode。`"setup-runtime"` は軽量な full-entry 起動前/セットアップ用ウィンドウです |
| `api.resolvePath(input)` | `(string) => string` | plugin root を基準にパスを解決する |
| Field | Type | 説明 |
| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Plugin id |
| `api.name` | `string` | 表示名 |
| `api.version` | `string?` | Pluginバージョン（任意） |
| `api.description` | `string?` | Pluginの説明（任意） |
| `api.source` | `string` | Pluginソースパス |
| `api.rootDir` | `string?` | Pluginルートディレクトリ（任意） |
| `api.config` | `OpenClawConfig` | 現在のconfigスナップショット（利用可能な場合は、アクティブなインメモリruntimeスナップショット） |
| `api.pluginConfig` | `Record<string, unknown>` | `plugins.entries.<id>.config`からのPlugin固有config |
| `api.runtime` | `PluginRuntime` | [ランタイムヘルパー](/ja-JP/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | スコープ付きlogger（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 現在のload mode。`"setup-runtime"`は、軽量なfull-entry前のstartup/setupウィンドウです |
| `api.resolvePath(input)` | `(string) => string` | Pluginルートからの相対パスを解決 |
## 内部モジュール規約
plugin 内では、内部インポートにローカル barrel ファイルを使用してください。
Plugin内では、内部インポートにローカルbarrelファイルを使用してください。
```
my-plugin/
api.ts # 外部利用者向けの公開エクスポート
runtime-api.ts # 内部専用の runtime エクスポート
api.ts # 外部利用者向けの公開export
runtime-api.ts # 内部専用runtime export
index.ts # Plugin entry point
setup-entry.ts # 軽量な setup 専用 entry（任意）
setup-entry.ts # 軽量なsetup専用entry（任意）
```
<Warning>
本番コード内で自分自身の plugin を `openclaw/plugin-sdk/<your-plugin>`
経由でインポートしてはいけません。内部インポートは `./api.ts` または
`./runtime-api.ts` を通してください。SDK パスは外部コントラクト専用です。
本番コードから`openclaw/plugin-sdk/<your-plugin>`経由で自分自身のPluginを
インポートしてはいけません。内部インポートは`./api.ts`または
`./runtime-api.ts`を経由させてください。SDKパスは外部コントラクト専用です。
</Warning>
Facade-loaded bundled plugin の公開 surface（`api.ts`、`runtime-api.ts`、
`index.ts`、`setup-entry.ts`、および同様の公開 entry ファイル）は、OpenClaw がすでに動作中であれば
アクティブな runtime config スナップショットを優先して使用するようになりました。
まだ runtime スナップショットが存在しない場合は、ディスク上で解決された config file にフォールバックします。
facade読み込みされたbundled Pluginの公開surface（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts`、および同様の公開entryファイル）は、OpenClawがすでに実行中であれば、現在はアクティブなruntime configスナップショットを優先します。まだruntimeスナップショットが存在しない場合は、ディスク上で解決されたconfigファイルにフォールバックします。
Provider plugins は、helper が意図的に provider 固有であり、まだ汎用 SDK
サブパスに属さない場合、狭い plugin ローカル contract barrel を公開することもできます。現在の bundled の例:
Anthropic provider は、Anthropic beta-header や `service_tier` ロジックを
汎用 `plugin-sdk/*` コントラクトに昇格させる代わりに、自身の公開 `api.ts` / `contract-api.ts` seam に Claude
stream helper を保持しています。
Provider Pluginは、helperが意図的にprovider固有で、まだ汎用SDKサブパスに属していない場合、狭いPluginローカルのcontract barrelを公開することもできます。現在のbundled例として、Anthropic providerは、Anthropic beta-headerや`service_tier`ロジックを汎用`plugin-sdk/*`コントラクトに昇格させる代わりに、Claude stream helperを自身の公開`api.ts` / `contract-api.ts` seamに保持しています。
その他の現在の bundled の例:
その他の現在のbundled例:
- `@openclaw/openai-provider`: `api.ts` は provider builder、
default-model helper、および realtime provider builder をエクスポートします
- `@openclaw/openrouter-provider`: `api.ts` は provider builder に加えて
onboarding/config helper をエクスポートします
- `@openclaw/openai-provider`: `api.ts`はprovider builder、default-model helper、およびrealtime provider builderをexportします
- `@openclaw/openrouter-provider`: `api.ts`はprovider builderに加えて、オンボーディング/config helperをexportします
<Warning>
Extension の本番コードでも、`openclaw/plugin-sdk/<other-plugin>`
のインポートは避けるべきです。helper が本当に共有対象であるなら、2 つの plugin を結合してしまう代わりに、
`openclaw/plugin-sdk/speech`、`.../provider-model-shared`、または別の
capability 指向 surface のような中立な SDK サブパスに昇格させてください。
extensionの本番コードでも、`openclaw/plugin-sdk/<other-plugin>`の
インポートは避けるべきです。helperが本当に共有されるべきなら、
2つのPluginを結合させるのではなく、`openclaw/plugin-sdk/speech`、
`.../provider-model-shared`、または別のcapability指向surfaceのような
中立的なSDKサブパスに昇格させてください。
</Warning>
## 関連
- [Entry Points](/ja-JP/plugins/sdk-entrypoints) — `definePluginEntry` と `defineChannelPluginEntry` のオプション
- [Runtime Helpers](/ja-JP/plugins/sdk-runtime) — `api.runtime` 名前空間の完全なリファレンス
- [Setup and Config](/ja-JP/plugins/sdk-setup) — パッケージ化、マニフェスト、config schema
- [Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティと lint ルール
- [SDK Migration](/ja-JP/plugins/sdk-migration) — 非推奨 surface からの移行
- [Plugin Internals](/ja-JP/plugins/architecture) — 詳細なアーキテクチャと capability モデル
- [Entry Points](/ja-JP/plugins/sdk-entrypoints) — `definePluginEntry`および`defineChannelPluginEntry`のオプション
- [ランタイムヘルパー](/ja-JP/plugins/sdk-runtime) — 完全な`api.runtime`名前空間リファレンス
- [Setup and Config](/ja-JP/plugins/sdk-setup) — パッケージング、manifest、config schema
- [Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティとlintルール
- [SDK Migration](/ja-JP/plugins/sdk-migration) — 非推奨surfaceからの移行
- [Plugin Internals](/ja-JP/plugins/architecture) — 詳細なアーキテクチャとcapability model

123
docs/ja-JP/tools/thinking.md
View File

@ -1,102 +1,104 @@
---
read_when:
- 思考、fast モード、または verbose ディレクティブの解析やデフォルトを調整する場合
summary: '`/think`、`/fast`、`/verbose`、`/trace`、および推論可視性のためのディレクティブ構文'
- 思考、fast-mode、または verbose ディレクティブの解析やデフォルトの調整
summary: '`/think`、`/fast`、`/verbose`、`/trace` のディレクティブ構文と推論の可視性'
title: 思考レベル
x-i18n:
generated_at: "2026-04-12T23:34:31Z"
generated_at: "2026-04-17T04:43:55Z"
model: gpt-5.4
provider: openai
source_hash: 4f3b1341281f07ba4e9061e3355845dca234be04cc0d358594312beeb7676e68
source_hash: 1cb44a7bf75546e5a8c3204e12f3297221449b881161d173dea4983da3921649
source_path: tools/thinking.md
workflow: 15
---
# 思考レベル（`/think` ディレクティブ）
## できること
## 機能
- 任意の受信本文で使えるインラインディレクティブ: `/t <level>`、`/think:<level>`、または `/thinking <level>`。
- 任意の受信本文内で使えるインラインディレクティブ: `/t <level>`、`/think:<level>`、または `/thinking <level>`。
- レベル（エイリアス）: `off | minimal | low | medium | high | xhigh | adaptive`
- minimal → 「think」
- low → 「think hard」
- medium → 「think harder」
- high → 「ultrathink」（最大予算）
- xhigh → 「ultrathink+」（GPT-5.2 + Codex モデルのみ）
- adaptive → provider が管理する適応型推論予算（Anthropic Claude 4.6 モデルファミリーでサポート）
- `x-high`、`x_high`、`extra-high`、`extra high`、`extra_high` は `xhigh` にマップされます。
- `highest`、`max` は `high` にマップされます。
- provider に関する注意:
- Anthropic Claude 4.6 モデルは、明示的な thinking レベルが設定されていない場合、デフォルトで `adaptive` になります。
- Anthropic 互換ストリーミング経路上の MiniMax（`minimax/*`）は、モデル params またはリクエスト params で明示的に thinking を設定しない限り、デフォルトで `thinking: { type: "disabled" }` になります。これにより、MiniMax のネイティブではない Anthropic ストリーム形式から `reasoning_content` delta が漏れるのを防ぎます。
- Z.AI（`zai/*`）はバイナリ thinking（`on`/`off`）のみをサポートします。`off` 以外のレベルはすべて `on` として扱われます（`low` にマップ）。
- Moonshot（`moonshot/*`）は `/think off` を `thinking: { type: "disabled" }` に、`off` 以外の任意のレベルを `thinking: { type: "enabled" }` にマップします。thinking が有効な場合、Moonshot は `tool_choice` として `auto|none` のみを受け付けます。OpenClaw は互換性のない値を `auto` に正規化します。
- xhigh → 「ultrathink+」（GPT-5.2 + Codex モデルと Anthropic Claude Opus 4.7 effort）
- adaptive → プロバイダー管理の適応的思考（Anthropic Claude 4.6 と Opus 4.7 でサポート）
- `x-high`、`x_high`、`extra-high`、`extra high`、`extra_high` は `xhigh` にマッピングされます。
- `highest`、`max` は `high` にマッピングされます。
- プロバイダーに関する注意:
- Anthropic Claude 4.6 モデルは、明示的な思考レベルが設定されていない場合、デフォルトで `adaptive` になります。
- Anthropic Claude Opus 4.7 は adaptive thinking をデフォルトにしません。その API effort のデフォルトは、思考レベルを明示的に設定しない限りプロバイダー側で管理されます。
- Anthropic Claude Opus 4.7 では、`/think xhigh` は adaptive thinking と `output_config.effort: "xhigh"` にマッピングされます。これは `/think` が思考ディレクティブであり、`xhigh` が Opus 4.7 の effort 設定だからです。
- Anthropic 互換ストリーミングパス上の MiniMax（`minimax/*`）は、モデル params または request params で thinking を明示的に設定しない限り、デフォルトで `thinking: { type: "disabled" }` になります。これにより、MiniMax の非ネイティブな Anthropic ストリーム形式から `reasoning_content` のデルタが漏れるのを防ぎます。
- Z.AI（`zai/*`）は二値の thinking（`on`/`off`）のみをサポートします。`off` 以外のレベルはすべて `on` として扱われます（`low` にマッピング）。
- Moonshot（`moonshot/*`）は `/think off` を `thinking: { type: "disabled" }` に、`off` 以外のレベルを `thinking: { type: "enabled" }` にマッピングします。thinking が有効な場合、Moonshot は `tool_choice` として `auto|none` しか受け付けないため、OpenClaw は非互換の値を `auto` に正規化します。
## 解決順序
1. メッセージ上のインラインディレクティブ（そのメッセージにのみ適用）。
2. セッションオーバーライド（ディレクティブのみのメッセージを送って設定）。
3. エージェントごとのデフォルト（設定の `agents.list[].thinkingDefault`）。
4. グローバルデフォルト（設定の `agents.defaults.thinkingDefault`）。
5. フォールバック: Anthropic Claude 4.6 モデルは `adaptive`、その他の推論対応モデルは `low`、それ以外は `off`。
2. セッションオーバーライド（ディレクティブのみのメッセージを送ることで設定）。
3. エージェントごとのデフォルト（設定内の `agents.list[].thinkingDefault`）。
4. グローバルデフォルト（設定内の `agents.defaults.thinkingDefault`）。
5. フォールバック: Anthropic Claude 4.6 モデルでは `adaptive`、Anthropic Claude Opus 4.7 では明示設定がない限り `off`、その他の reasoning 対応モデルでは `low`、それ以外では `off`。
## セッションデフォルトを設定する
## セッションのデフォルトを設定する
- **ディレクティブだけ**のメッセージを送ります（空白は可）。例: `/think:medium` または `/t high`。
- これは現在のセッションに固定されます（デフォルトでは送信者ごと）。`/think:off` またはセッションのアイドルリセットで解除されます。
- 確認返信が送られます（`Thinking level set to high.` / `Thinking disabled.`）。レベルが無効な場合（例: `/thinking big`）、コマンドはヒント付きで拒否され、セッション状態は変更されません。
- 現在の thinking レベルを確認するには、引数なしで `/think`（または `/think:`）を送ります。
- **ディレクティブだけ**のメッセージを送信します（空白は可）。例: `/think:medium` または `/t high`。
- これは現在のセッションに保持されます（デフォルトでは送信者単位）。`/think:off` またはセッションのアイドルリセットで解除されます。
- 確認の返信が送られます（`Thinking level set to high.` / `Thinking disabled.`）。レベルが無効な場合（例: `/thinking big`）、コマンドは拒否され、ヒントが返され、セッション状態は変更されません。
- 引数なしで `/think`（または `/think:`）を送ると、現在の思考レベルを確認できます。
## エージェントごとの適用
- **Embedded Pi**: 解決されたレベルは、プロセス内の Pi エージェントランタイムに渡されます。
## Fast モード（`/fast`）
## Fast mode（`/fast`）
- レベル: `on|off`。
- ディレクティブのみのメッセージは、セッションの fast モードオーバーライドを切り替え、`Fast mode enabled.` / `Fast mode disabled.` と返信します。
- 現在有効な fast モード状態を確認するには、モードなしで `/fast`（または `/fast status`）を送ります。
- OpenClaw は、次の順序で fast モードを解決します:
1. インライン/ディレクティブのみの `/fast on|off`
- ディレクティブのみのメッセージでセッションの fast-mode オーバーライドを切り替え、`Fast mode enabled.` / `Fast mode disabled.` と返信します。
- モード指定なしで `/fast`（または `/fast status`）を送ると、現在有効な fast-mode 状態を確認できます。
- OpenClaw は fast mode を次の順序で解決します:
1. インライン／ディレクティブのみの `/fast on|off`
2. セッションオーバーライド
3. エージェントごとのデフォルト（`agents.list[].fastModeDefault`）
4. モデルごとの設定: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. フォールバック: `off`
- `openai/*` では、fast モードは対応する Responses リクエストで `service_tier=priority` を送信することで、OpenAI の優先処理にマップされます。
- `openai-codex/*` では、fast モードは Codex Responses でも同じ `service_tier=priority` フラグを送信します。OpenClaw は、両方の認証経路で 1 つの共有 `/fast` トグルを維持します。
- `api.anthropic.com` に送信される OAuth 認証済みトラフィックを含む直接の公開 `anthropic/*` リクエストでは、fast モードは Anthropic の service tier にマップされます: `/fast on` は `service_tier=auto` を設定し、`/fast off` は `service_tier=standard_only` を設定します。
- Anthropic 互換経路上の `minimax/*` では、`/fast on`（または `params.fastMode: true`）は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。
- 明示的な Anthropic `serviceTier` / `service_tier` モデル params は、両方が設定されている場合、fast モードのデフォルトを上書きします。OpenClaw は、Anthropic 以外のプロキシ base URL に対しては引き続き Anthropic の service-tier 注入をスキップします。
- `openai/*` では、fast mode はサポートされる Responses リクエストで `service_tier=priority` を送信することで OpenAI の priority processing にマッピングされます。
- `openai-codex/*` では、fast mode は Codex Responses に同じ `service_tier=priority` フラグを送信します。OpenClaw は両方の認証パスで 1 つの共有 `/fast` トグルを維持します。
- `api.anthropic.com` に送信される OAuth 認証トラフィックを含む直接の公開 `anthropic/*` リクエストでは、fast mode は Anthropic の service tiers にマッピングされます: `/fast on` は `service_tier=auto`、`/fast off` は `service_tier=standard_only` を設定します。
- Anthropic 互換パス上の `minimax/*` では、`/fast on`（または `params.fastMode: true`）は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。
- 明示的な Anthropic `serviceTier` / `service_tier` モデル params は、両方が設定されている場合、fast-mode のデフォルトより優先されます。OpenClaw は引き続き、Anthropic 以外のプロキシ base URL には Anthropic service-tier の注入を行いません。
## Verbose ディレクティブ（`/verbose` または `/v`）
- レベル: `on`（最小） | `full` | `off`（デフォルト）。
- ディレクティブのみのメッセージは、セッション verbose を切り替え、`Verbose logging enabled.` / `Verbose logging disabled.` と返信します。無効なレベルは、状態を変更せずにヒントを返します。
- `/verbose off` は明示的なセッションオーバーライドを保存します。Sessions UI で `inherit` を選ぶと解除できます。
- インラインディレクティブはそのメッセージにのみ影響し、それ以外はセッション/グローバルデフォルトが適用されます。
- 現在の verbose レベルを確認するには、引数なしで `/verbose`（または `/verbose:`）を送ります。
- verbose が有効な場合、構造化ツール結果を出力するエージェント（Pi、その他の JSON エージェント）は、各ツール呼び出しを個別のメタデータ専用メッセージとして返します。利用可能な場合、`<emoji> <tool-name>: <arg>`（パス/コマンド）の形式でプレフィックスが付きます。これらのツール要約は、各ツールの開始時にすぐ送信されます（別々のバブル）。ストリーミング delta としては送信されません。
- ツール失敗の要約は通常モードでも表示されたままですが、生のエラー詳細サフィックスは verbose が `on` または `full` の場合にのみ表示されます。
- verbose が `full` の場合、ツール出力も完了後に転送されます（別バブル、長さは安全な範囲に切り詰め）。実行中に `/verbose on|full|off` を切り替えた場合、後続のツールバブルは新しい設定に従います。
- レベル: `on`（最小）| `full` | `off`（デフォルト）。
- ディレクティブのみのメッセージでセッション verbose を切り替え、`Verbose logging enabled.` / `Verbose logging disabled.` と返信します。無効なレベルでは、状態を変更せずにヒントを返します。
- `/verbose off` は明示的なセッションオーバーライドとして保存されます。Sessions UI で `inherit` を選ぶと解除できます。
- インラインディレクティブはそのメッセージにのみ影響します。それ以外では、セッション／グローバルのデフォルトが適用されます。
- 引数なしで `/verbose`（または `/verbose:`）を送ると、現在の verbose レベルを確認できます。
- verbose が on の場合、構造化されたツール結果を出力するエージェント（Pi、その他の JSON エージェント）は、各ツール呼び出しをそれぞれ独立したメタデータ専用メッセージとして返し、利用可能な場合は `<emoji> <tool-name>: <arg>`（path/command）を接頭辞として付けます。これらのツール要約は、各ツールの開始時に送信されます（ストリーミングデルタではなく、別バブル）。
- ツール失敗の要約は通常モードでも表示されますが、生のエラー詳細の接尾辞は verbose が `on` または `full` の場合にのみ表示されます。
- verbose が `full` の場合、ツール出力も完了後に転送されます（別バブル、安全な長さに切り詰め）。実行中に `/verbose on|full|off` を切り替えると、その後のツールバブルには新しい設定が反映されます。
## Plugin trace ディレクティブ（`/trace`）
- レベル: `on` | `off`（デフォルト）。
- ディレクティブのみのメッセージは、セッションの Plugin trace 出力を切り替え、`Plugin trace enabled.` / `Plugin trace disabled.` と返信します。
- インラインディレクティブはそのメッセージにのみ影響し、それ以外はセッション/グローバルデフォルトが適用されます。
- 現在の trace レベルを確認するには、引数なしで `/trace`（または `/trace:`）を送ります。
- `/trace` は `/verbose` より狭い範囲です。Active Memory のデバッグサマリーのような、Plugin 所有の trace/debug 行だけを公開します。
- trace 行は `/status` に表示されることがあり、通常のアシスタント返信の後続診断メッセージとして現れることもあります。
- ディレクティブのみのメッセージでセッションの plugin trace 出力を切り替え、`Plugin trace enabled.` / `Plugin trace disabled.` と返信します。
- インラインディレクティブはそのメッセージにのみ影響します。それ以外では、セッション／グローバルのデフォルトが適用されます。
- 引数なしで `/trace`（または `/trace:`）を送ると、現在の trace レベルを確認できます。
- `/trace` は `/verbose` よりも限定的で、Active Memory のデバッグ要約のような plugin 所有の trace/debug 行だけを公開します。
- trace 行は `/status` に表示されることもあり、通常のアシスタント返信の後に続く診断メッセージとして現れることもあります。
## 推論の可視性（`/reasoning`）
- レベル: `on|off|stream`。
- ディレクティブのみのメッセージは、返信で thinking ブロックを表示するかどうかを切り替えます。
- 有効にすると、推論は `Reasoning:` で始まる**別メッセージ**として送信されます。
- `stream`（Telegram のみ）: 返信生成中に Telegram のドラフトバブルへ推論をストリーミングし、その後、推論なしの最終回答を送信します。
- ディレクティブのみのメッセージで、返信内に thinking ブロックを表示するかどうかを切り替えます。
- 有効にすると、推論は `Reasoning:` を接頭辞とする**別メッセージ**として送信されます。
- `stream`（Telegram のみ）: 返信生成中に Telegram の下書きバブルへ推論をストリーミングし、その後、推論を含まない最終回答を送信します。
- エイリアス: `/reason`。
- 現在の reasoning レベルを確認するには、引数なしで `/reasoning`（または `/reasoning:`）を送ります。
- 解決順序: インラインディレクティブ、セッションオーバーライド、エージェントごとのデフォルト（`agents.list[].reasoningDefault`）、フォールバック（`off`）。
- 引数なしで `/reasoning`（または `/reasoning:`）を送ると、現在の推論レベルを確認できます。
- 解決順序: インラインディレクティブ、次にセッションオーバーライド、次にエージェントごとのデフォルト（`agents.list[].reasoningDefault`）、最後にフォールバック（`off`）。
## 関連
@ -105,14 +107,15 @@ x-i18n:
## Heartbeat
- Heartbeat プローブ本文は、設定された heartbeat プロンプトです（デフォルト: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。heartbeat メッセージ内のインラインディレクティブは通常どおり適用されます（ただし、heartbeat からセッションデフォルトを変更するのは避けてください）。
- Heartbeat 配信はデフォルトで最終ペイロードのみです。利用可能な場合に別の `Reasoning:` メッセージも送信するには、`agents.defaults.heartbeat.includeReasoning: true` またはエージェントごとの `agents.list[].heartbeat.includeReasoning: true` を設定してください。
- Heartbeat 配信はデフォルトで最終ペイロードのみです。別個の `Reasoning:` メッセージも送信するには（利用可能な場合）、`agents.defaults.heartbeat.includeReasoning: true` またはエージェントごとの `agents.list[].heartbeat.includeReasoning: true` を設定します。
## Web チャット UI
- Web チャットの thinking セレクターは、ページ読み込み時に受信セッションストア/設定から、そのセッションに保存されたレベルを反映します。
- 別のレベルを選ぶと、`sessions.patch` を通じてセッションオーバーライドが即座に書き込まれます。次の送信までは待たず、単発の `thinkingOnce` オーバーライドでもありません。
- 最初のオプションは常に `Default (<resolved level>)` で、解決されたデフォルトはアクティブなセッションモデルから決まります: Anthropic/Bedrock 上の Claude 4.6 では `adaptive`、その他の推論対応モデルでは `low`、それ以外では `off` です。
- ピッカーは provider 対応のままです:
- ほとんどの provider は `off | minimal | low | medium | high | adaptive` を表示します
- Z.AI はバイナリの `off | on` を表示します
- `/think:<level>` も引き続き機能し、同じ保存済みセッションレベルを更新するため、チャットディレクティブとピッカーは同期されたままです。
- Web チャットの thinking セレクターは、ページ読み込み時に受信セッションストア／設定に保存されているセッションレベルを反映します。
- 別のレベルを選ぶと、`sessions.patch` を通じてセッションオーバーライドが即座に書き込まれます。次の送信までは待たず、1 回限りの `thinkingOnce` オーバーライドでもありません。
- 最初のオプションは常に `Default (<resolved level>)` で、この解決済みデフォルトはアクティブなセッションモデルから決まります: Anthropic 上の Claude 4.6 では `adaptive`、設定がない限り Anthropic Claude Opus 4.7 では `off`、その他の reasoning 対応モデルでは `low`、それ以外では `off`。
- ピッカーはプロバイダーを認識したままです:
- ほとんどのプロバイダーでは `off | minimal | low | medium | high | adaptive` を表示
- Anthropic Claude Opus 4.7 では `off | minimal | low | medium | high | xhigh | adaptive` を表示
- Z.AI では二値の `off | on` を表示
- `/think:<level>` も引き続き動作し、同じ保存済みセッションレベルを更新するため、チャットディレクティブとピッカーは同期されたままになります。