From 1a1e84d5ac8a77153d873147552ac0176c9b92bb Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 17 Apr 2026 04:47:49 +0000 Subject: [PATCH] chore(i18n): refresh ja-JP translations --- docs/ja-JP/concepts/qa-e2e-automation.md | 277 ++++--- docs/ja-JP/help/testing.md | 965 ++++++++++++----------- docs/ja-JP/plugins/sdk-migration.md | 515 ++++++------ docs/ja-JP/plugins/sdk-overview.md | 631 +++++++-------- docs/ja-JP/tools/thinking.md | 123 +-- 5 files changed, 1230 insertions(+), 1281 deletions(-) diff --git a/docs/ja-JP/concepts/qa-e2e-automation.md b/docs/ja-JP/concepts/qa-e2e-automation.md index d3969fc71..d42d80a06 100644 --- a/docs/ja-JP/concepts/qa-e2e-automation.md +++ b/docs/ja-JP/concepts/qa-e2e-automation.md @@ -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=` をリポジトリローカルのログファイルに設定します。 +このレーンは、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=` をリポジトリ内のログファイルに設定してください。 -実際のトランスポートを使う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 ` を使い、 -直列実行するには `--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 ` を使い、 +直列実行には `--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=` を使います。 +character evalシナリオは `SOUL.md` を通じてペルソナを設定し、 +その後、チャット、ワークスペースヘルプ、 +小さなファイルタスクのような通常のユーザーターンを実行するべきです。 +候補モデルには、評価中であることを知らせてはいけません。 +このコマンドは各完全トランスクリプトを保持し、 +基本的な実行統計を記録したうえで、 +judge modelに対して、fast modeかつ `xhigh` 推論で、 +自然さ、雰囲気、ユーモアによって実行結果を順位付けさせます。 +プロバイダーを比較するときは `--blind-judge-models` を使用してください: +judge promptは引き続きすべてのトランスクリプトと実行状態を受け取りますが、 +候補参照は `candidate-01` のような中立ラベルに置き換えられます。 +レポートはパース後に順位を実際の参照へマッピングし直します。 +候補実行はデフォルトで `high` thinking を使用し、 +それをサポートするOpenAIモデルでは `xhigh` を使用します。 +特定の候補を上書きするには、 +`--model provider/model,thinking=` をインラインで指定してください。 `--thinking ` は引き続きグローバルなフォールバックを設定し、 -従来の `--model-thinking ` 形式も +古い `--model-thinking ` 形式も 互換性のため維持されています。 -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) diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index 1805d07d2..7fa50c600 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - ローカルまたはCIでテストを実行する - - モデル/プロバイダーのバグに対するリグレッションテストを追加する + - モデル/プロバイダーのバグに対するリグレッションを追加する - Gateway + エージェントの動作をデバッグする -summary: 'テストキット: unit/e2e/liveスイート、Dockerランナー、および各テストがカバーする内容' -title: テスト中 +summary: テストキット：unit/e2e/liveスイート、Dockerランナー、および各テストがカバーする内容 +title: テスト x-i18n: - generated_at: "2026-04-16T21:51:17Z" + generated_at: "2026-04-17T04:44:00Z" model: gpt-5.4 provider: openai - source_hash: af2bc0e9b5e08ca3119806d355b517290f6078fda430109e7a0b153586215e34 + source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 source_path: help/testing.md workflow: 15 --- @@ -20,94 +20,96 @@ OpenClawには3つのVitestスイート（unit/integration、e2e、live）と、 このドキュメントは「どのようにテストするか」のガイドです。 -- 各スイートが何をカバーするか（そして意図的に何を _カバーしない_ か） -- 一般的なワークフロー（ローカル、push前、デバッグ）で実行するコマンド -- liveテストがどのように認証情報を検出し、モデル/プロバイダーを選択するか -- 実運用のモデル/プロバイダー問題に対するリグレッションを追加する方法 +- 各スイートが何をカバーするか（および意図的に何をカバーしないか） +- 一般的なワークフロー（ローカル、push前、デバッグ）でどのコマンドを実行するか +- liveテストがどのように認証情報を見つけ、モデル/プロバイダーを選択するか +- 実際のモデル/プロバイダーの問題に対するリグレッションをどのように追加するか ## クイックスタート -普段は次のとおりです。 +ほとんどの日は以下です。 -- フルゲート（push前に想定）: `pnpm build && pnpm check && pnpm test` +- フルゲート（push前に期待されるもの）: `pnpm build && pnpm check && pnpm test` - 余裕のあるマシンでの、より高速なローカル全スイート実行: `pnpm test:max` - 直接のVitest watchループ: `pnpm test:watch` -- 直接のファイル指定は、extension/channelのパスにも対応するようになりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 直接のファイル指定は、extension/channelパスもルーティングされるようになりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - 単一の失敗を反復修正しているときは、まず対象を絞った実行を優先してください。 -- DockerバックのQAサイト: `pnpm qa:lab:up` -- Linux VMバックのQAレーン: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- DockerベースのQAサイト: `pnpm qa:lab:up` +- Linux VMベースのQAレーン: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -テストに触れたとき、または追加の確信が欲しいとき: +テストに触れたとき、または追加の確信がほしいとき: - カバレッジゲート: `pnpm test:coverage` - E2Eスイート: `pnpm test:e2e` 実際のプロバイダー/モデルをデバッグするとき（実際の認証情報が必要）: -- liveスイート（モデル + Gatewayのツール/画像プローブ）: `pnpm test:live` -- 1つのliveファイルだけを静かに対象化: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- liveスイート（models + Gateway tool/image probes）: `pnpm test:live` +- 1つのliveファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` ヒント: 必要なのが1つの失敗ケースだけなら、以下で説明するallowlist環境変数を使ってliveテストを絞り込むことを優先してください。 -## QA専用ランナー +## QA固有のランナー これらのコマンドは、QA-lab相当の現実性が必要なときに、メインのテストスイートと並んで使います。 - `pnpm openclaw qa suite` - - リポジトリバックのQAシナリオをホスト上で直接実行します。 - - デフォルトでは、隔離されたGatewayワーカーを使って複数の選択シナリオを並列実行します。最大64ワーカーまたは選択シナリオ数までです。ワーカー数の調整には `--concurrency ` を使用し、従来の直列レーンにしたい場合は `--concurrency 1` を使用します。 + - リポジトリベースのQAシナリオをホスト上で直接実行します。 + - デフォルトで、分離されたGatewayワーカーを使って複数の選択シナリオを並列実行します。最大64ワーカー、または選択したシナリオ数までです。`--concurrency `でワーカー数を調整するか、従来の直列レーンには`--concurrency 1`を使ってください。 + - プロバイダーモード `live-frontier`、`mock-openai`、`aimock` をサポートします。`aimock` は、シナリオ認識型の `mock-openai` レーンを置き換えることなく、実験的なfixtureおよびプロトコルモックのカバレッジ向けに、ローカルのAIMockベースのプロバイダーサーバーを起動します。 - `pnpm openclaw qa suite --runner multipass` - - 同じQAスイートを一時的なMultipass Linux VM内で実行します。 - - ホスト上の `qa suite` と同じシナリオ選択の挙動を維持します。 + - 同じQAスイートを、使い捨てのMultipass Linux VM内で実行します。 + - ホスト上の `qa suite` と同じシナリオ選択動作を維持します。 - `qa suite` と同じプロバイダー/モデル選択フラグを再利用します。 - - live実行では、ゲスト向けに現実的な範囲で、サポート対象のQA認証入力を転送します: - envベースのプロバイダーキー、QA liveプロバイダー設定パス、存在する場合は `CODEX_HOME`。 - - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に置く必要があります。 - - 通常のQAレポート + サマリーに加え、Multipassログを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - live実行では、ゲストで実用的なサポート済みQA認証入力を転送します: 環境変数ベースのプロバイダーキー、QA liveプロバイダー設定パス、存在する場合は `CODEX_HOME`。 + - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に維持する必要があります。 + - 通常のQAレポートとサマリーに加え、Multipassログを `.artifacts/qa-e2e/...` 配下に書き込みます。 - `pnpm qa:lab:up` - - オペレーター型のQA作業向けに、DockerバックのQAサイトを起動します。 + - オペレーター型のQA作業向けに、DockerベースのQAサイトを起動します。 +- `pnpm openclaw qa aimock` + - 直接のプロトコルスモークテスト用に、ローカルのAIMockプロバイダーサーバーのみを起動します。 - `pnpm openclaw qa matrix` - - 使い捨てのDockerバックTuwunel homeserverに対して、Matrix live QAレーンを実行します。 - - このQAホストは現時点ではrepo/dev専用です。パッケージ化されたOpenClawインストールには `qa-lab` が含まれないため、`openclaw qa` は公開されません。 - - リポジトリチェックアウトでは、バンドル済みランナーを直接読み込みます。別途Pluginのインストール手順は不要です。 - - 一時的なMatrixユーザー3人（`driver`、`sut`、`observer`）と1つのプライベートルームを用意し、実際のMatrix PluginをSUTトランスポートとして使うQA Gateway子プロセスを起動します。 - - デフォルトでは、固定された安定版Tuwunelイメージ `ghcr.io/matrix-construct/tuwunel:v1.5.1` を使用します。別のイメージをテストしたい場合は `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` で上書きします。 - - Matrixはローカルで使い捨てユーザーを生成するため、共有のcredential-sourceフラグは公開しません。 - - Matrix QAレポート、サマリー、observed-eventsアーティファクト、結合されたstdout/stderr出力ログを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - 使い捨てのDockerベースTuwunelホームサーバーに対して、Matrix live QAレーンを実行します。 + - このQAホストは現時点ではrepo/dev専用です。パッケージ化されたOpenClawインストールには `qa-lab` は含まれないため、`openclaw qa` は公開されません。 + - リポジトリチェックアウトはバンドルされたランナーを直接読み込みます。別途Pluginインストール手順は不要です。 + - 3つの一時的なMatrixユーザー（`driver`、`sut`、`observer`）と1つのプライベートルームをプロビジョニングし、その後、実際のMatrix PluginをSUTトランスポートとして使うQA Gateway子プロセスを起動します。 + - デフォルトでは、固定された安定版Tuwunelイメージ `ghcr.io/matrix-construct/tuwunel:v1.5.1` を使います。別のイメージをテストする必要がある場合は `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` で上書きしてください。 + - Matrixは共有認証情報ソースフラグを公開しません。これは、このレーンが使い捨てユーザーをローカルでプロビジョニングするためです。 + - Matrix QAレポート、サマリー、observed-events artifact、結合されたstdout/stderr出力ログを `.artifacts/qa-e2e/...` 配下に書き込みます。 - `pnpm openclaw qa telegram` - - envのdriverおよびSUTボットトークンを使用し、実際のプライベートグループに対してTelegram live QAレーンを実行します。 - - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。group idは数値のTelegram chat idである必要があります。 - - 共有プール認証情報には `--credential-source convex` をサポートします。通常はenvモードを使用し、プールされたリースを使う場合は `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定してください。 - - 同じプライベートグループ内に2つの異なるボットが必要で、SUTボットはTelegram usernameを公開している必要があります。 - - 安定したボット間観測のため、両方のボットで `@BotFather` の Bot-to-Bot Communication Mode を有効にし、driverボットがグループ内のボット通信を観測できるようにしてください。 - - Telegram QAレポート、サマリー、observed-messagesアーティファクトを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - 環境変数から取得したdriverおよびSUT botトークンを使って、実際のプライベートグループに対してTelegram live QAレーンを実行します。 + - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。グループIDは数値のTelegram chat idでなければなりません。 + - 共有プール認証情報用に `--credential-source convex` をサポートします。デフォルトではenvモードを使い、プールされたリースを使うには `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定してください。 + - 同じプライベートグループ内に2つの異なるbotが必要で、SUT botはTelegram usernameを公開している必要があります。 + - 安定したbot間観測のために、`@BotFather` で両方のbotのBot-to-Bot Communication Modeを有効にし、driver botがグループ内のbotトラフィックを観測できることを確認してください。 + - Telegram QAレポート、サマリー、およびobserved-messages artifactを `.artifacts/qa-e2e/...` 配下に書き込みます。 -liveトランスポートレーンは、新しいトランスポートが逸脱しないよう、1つの標準契約を共有します。 +live transportレーンは、新しいtransportがずれないよう、1つの標準契約を共有します。 -`qa-channel` は引き続き広範な合成QAスイートであり、liveトランスポートのカバレッジマトリクスには含まれません。 +`qa-channel` は依然として広範な合成QAスイートであり、live transportカバレッジマトリクスには含まれません。 -| レーン | Canary | メンションゲーティング | Allowlist block | トップレベル返信 | 再起動後の再開 | スレッド追従 | スレッド分離 | リアクション観測 | ヘルプコマンド | -| ------ | ------ | ---------------------- | --------------- | ---------------- | -------------- | ------------ | ------------ | ---------------- | -------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| レーン | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | +| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Convex経由の共有Telegram認証情報（v1） -`openclaw qa telegram` で `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）が有効な場合、QA labはConvexバックのプールから排他的なリースを取得し、レーンの実行中はそのリースにHeartbeatを送り、終了時にリースを解放します。 +`openclaw qa telegram` で `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）を有効にすると、QA labはConvexベースのプールから排他的リースを取得し、レーンの実行中はそのリースにHeartbeatを送り続け、シャットダウン時にリースを解放します。 -参考用のConvexプロジェクト雛形: +参考用Convexプロジェクトスキャフォールド: - `qa/convex-credential-broker/` -必須の環境変数: +必要な環境変数: - `OPENCLAW_QA_CONVEX_SITE_URL`（例: `https://your-deployment.convex.site`） - 選択したロール用のシークレット1つ: - `maintainer` 用の `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` - `ci` 用の `OPENCLAW_QA_CONVEX_SECRET_CI` -- 認証ロールの選択: +- 認証情報ロール選択: - CLI: `--credential-role maintainer|ci` - - 環境変数のデフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（デフォルトは `maintainer`） + - 環境変数デフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（デフォルトは `maintainer`） 任意の環境変数: @@ -116,14 +118,14 @@ liveトランスポートレーンは、新しいトランスポートが逸脱 - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（デフォルト `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（デフォルト `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（デフォルト `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意のトレースid） -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` を設定すると、ローカル専用開発向けに loopback の `http://` Convex URL を許可します。 +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意のトレースID） +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` は、ローカル専用開発向けにloopbackの `http://` Convex URLを許可します。 -通常運用では、`OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使用してください。 +通常運用では `OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使う必要があります。 -メンテナー向け管理コマンド（プールの追加/削除/一覧）には、特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 +maintainer管理コマンド（プールの追加/削除/一覧表示）には、特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 -メンテナー向けCLIヘルパー: +maintainer向けCLIヘルパー: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -131,7 +133,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -スクリプトやCIユーティリティで機械可読な出力が必要な場合は `--json` を使ってください。 +スクリプトおよびCIユーティリティで機械可読な出力が必要な場合は `--json` を使ってください。 デフォルトのエンドポイント契約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: @@ -145,73 +147,73 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - リクエスト: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - 成功: `{ status: "ok" }`（または空の `2xx`） -- `POST /admin/add`（maintainer secret専用） +- `POST /admin/add`（maintainerシークレット専用） - リクエスト: `{ kind, actorId, payload, note?, status? }` - 成功: `{ status: "ok", credential }` -- `POST /admin/remove`（maintainer secret専用） +- `POST /admin/remove`（maintainerシークレット専用） - リクエスト: `{ credentialId, actorId }` - 成功: `{ status: "ok", changed, credential }` - - アクティブリースのガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（maintainer secret専用） + - アクティブリースガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list`（maintainerシークレット専用） - リクエスト: `{ kind?, status?, includePayload?, limit? }` - 成功: `{ status: "ok", credentials, count }` -Telegram種別のペイロード形状: +Telegram種別のpayload形状: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` は数値のTelegram chat id文字列である必要があります。 -- `admin/add` は `kind: "telegram"` に対してこの形状を検証し、不正なペイロードを拒否します。 +- `groupId` は数値のTelegram chat id文字列でなければなりません。 +- `admin/add` は `kind: "telegram"` に対してこの形状を検証し、不正なpayloadを拒否します。 ### QAにチャネルを追加する -Markdown QAシステムにチャネルを追加するには、必要なのは正確に2つだけです。 +markdown QAシステムにチャネルを追加するには、正確に2つのものが必要です。 -1. そのチャネル用のトランスポートアダプター -2. そのチャネル契約を検証するシナリオパック +1. そのチャネル用のtransport adapter +2. チャネル契約を実行するscenario pack -共有の `qa-lab` ホストでフローを管理できる場合は、新しいトップレベルQAコマンドルートを追加しないでください。 +共有の `qa-lab` ホストがフローを所有できる場合、新しいトップレベルQAコマンドルートを追加しないでください。 -`qa-lab` は共有ホスト機構を管理します: +`qa-lab` は共有ホストメカニクスを所有します。 - `openclaw qa` コマンドルート -- スイートの起動と終了 -- ワーカー並列度 -- アーティファクト書き込み +- スイートの起動と終了処理 +- ワーカー並行性 +- artifactの書き込み - レポート生成 - シナリオ実行 -- 旧 `qa-channel` シナリオ向けの互換エイリアス +- 古い `qa-channel` シナリオ向けの互換エイリアス -ランナーPluginはトランスポート契約を管理します: +Runner Pluginはtransport契約を所有します。 -- `openclaw qa ` を共有 `qa` ルート配下にどのようにマウントするか -- そのトランスポート向けにGatewayをどう設定するか -- 準備完了をどう確認するか -- 受信イベントをどう注入するか -- 送信メッセージをどう観測するか -- transcript と正規化済みトランスポート状態をどう公開するか -- トランスポートバックのアクションをどう実行するか -- トランスポート固有のリセットやクリーンアップをどう扱うか +- `openclaw qa ` が共有の `qa` ルート配下にどのようにマウントされるか +- そのtransport向けにGatewayがどのように設定されるか +- 準備完了をどのように確認するか +- inboundイベントをどのように注入するか +- outboundメッセージをどのように観測するか +- transcriptおよび正規化されたtransport状態をどのように公開するか +- transportベースのアクションをどのように実行するか +- transport固有のリセットまたはクリーンアップをどのように処理するか -新しいチャネルに求められる最小採用要件は次のとおりです。 +新しいチャネルの最低採用基準は以下です。 -1. 共有 `qa` ルートの管理者は `qa-lab` のままにする。 -2. 共有 `qa-lab` ホスト境界でトランスポートランナーを実装する。 -3. トランスポート固有の仕組みはランナーPluginまたはチャネルハーネス内に閉じ込める。 -4. 競合するルートコマンドを登録するのではなく、ランナーを `openclaw qa ` としてマウントする。 - ランナーPluginは `openclaw.plugin.json` に `qaRunners` を宣言し、`runtime-api.ts` から対応する `qaRunnerCliRegistrations` 配列をエクスポートする必要があります。 - `runtime-api.ts` は軽量に保ってください。遅延CLIおよびランナー実行は、別のエントリーポイントの背後に置く必要があります。 -5. `qa/scenarios/` 配下にMarkdownシナリオを作成または適応する。 +1. 共有 `qa` ルートの所有者は `qa-lab` のままにする。 +2. 共有 `qa-lab` ホストシーム上にtransport runnerを実装する。 +3. transport固有のメカニクスはrunner Pluginまたはチャネルharness内に保持する。 +4. 競合するルートコマンドを登録するのではなく、runnerを `openclaw qa ` としてマウントする。 + Runner Pluginは `openclaw.plugin.json` に `qaRunners` を宣言し、`runtime-api.ts` から一致する `qaRunnerCliRegistrations` 配列をエクスポートする必要があります。 + `runtime-api.ts` は軽量に保ってください。遅延CLIおよびrunner実行は、別のentrypointの背後に置く必要があります。 +5. `qa/scenarios/` 配下にmarkdownシナリオを作成または調整する。 6. 新しいシナリオには汎用シナリオヘルパーを使う。 -7. リポジトリが意図的な移行中でない限り、既存の互換エイリアスを維持する。 +7. リポジトリが意図的な移行を行っているのでない限り、既存の互換エイリアスを動作させ続ける。 判断ルールは厳格です。 - 振る舞いを `qa-lab` で一度だけ表現できるなら、`qa-lab` に置く。 -- 振る舞いが1つのチャネルトランスポートに依存するなら、そのランナーPluginまたはPluginハーネスに置く。 -- あるシナリオが複数チャネルで使える新しい機能を必要とするなら、`suite.ts` にチャネル固有の分岐を追加するのではなく、汎用ヘルパーを追加する。 -- 振る舞いが1つのトランスポートにしか意味を持たないなら、そのシナリオはトランスポート固有のままにし、そのことをシナリオ契約で明示する。 +- 振る舞いが1つのチャネルtransportに依存するなら、そのrunner PluginまたはPlugin harnessに保持する。 +- シナリオが複数のチャネルで使える新しい機能を必要とするなら、`suite.ts` にチャネル固有の分岐を追加するのではなく、汎用ヘルパーを追加する。 +- 振る舞いが1つのtransportにのみ意味を持つなら、そのシナリオはtransport固有のままにし、シナリオ契約内でそれを明示する。 -新しいシナリオで推奨される汎用ヘルパー名は次のとおりです。 +新しいシナリオ向けの推奨汎用ヘルパー名は以下です。 - `waitForTransportReady` - `waitForChannelReady` @@ -226,7 +228,7 @@ Markdown QAシステムにチャネルを追加するには、必要なのは正 - `formatTransportTranscript` - `resetTransport` -既存シナリオ向けに、互換エイリアスも引き続き利用できます。 +既存シナリオ向けには、以下を含む互換エイリアスが引き続き利用できます。 - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -234,98 +236,98 @@ Markdown QAシステムにチャネルを追加するには、必要なのは正 - `formatConversationTranscript` - `resetBus` -新しいチャネル作業では、汎用ヘルパー名を使うべきです。 -互換エイリアスは、一斉移行を避けるために存在しているのであって、新しいシナリオ作成のモデルではありません。 +新しいチャネル作業では、汎用ヘルパー名を使う必要があります。 +互換エイリアスは、一斉移行を避けるために存在するのであって、新しいシナリオ作成のモデルではありません。 -## テストスイート（どこで何が実行されるか） +## テストスイート（どこで何が動くか） -スイートは「現実性が増していくもの」（同時に不安定さ/コストも増える）として考えてください。 +スイートは「現実性が増す順」（そして不安定さ/コストも増す順）と考えてください: ### Unit / integration（デフォルト） - コマンド: `pnpm test` -- 設定: 既存のスコープ付きVitestプロジェクトに対する、10回の逐次シャード実行（`vitest.full-*.config.ts`） -- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下のcore/unitインベントリ、および `vitest.unit.config.ts` でカバーされる許可済みの `ui` Nodeテスト +- 設定: 既存のスコープ付きVitest projectに対する10個の逐次shard実行（`vitest.full-*.config.ts`） +- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下のcore/unitインベントリ、および `vitest.unit.config.ts` でカバーされる許可済みの `ui` nodeテスト - スコープ: - 純粋なunitテスト - - プロセス内integrationテスト（Gateway認証、ルーティング、ツール、パース、設定） + - プロセス内integrationテスト（Gateway auth、routing、tooling、parsing、config） - 既知のバグに対する決定論的なリグレッション -- 期待事項: +- 想定: - CIで実行される - 実際のキーは不要 - - 高速かつ安定しているべき -- プロジェクトに関する注記: - - 対象を絞らない `pnpm test` は、1つの巨大なネイティブルートプロジェクトプロセスの代わりに、11個の小さなシャード設定（`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`）を実行するようになりました。これにより、負荷の高いマシンでのピークRSSが削減され、auto-reply/extensionの処理が無関係なスイートを圧迫することを避けられます。 - - `pnpm test --watch` は依然としてネイティブルートの `vitest.config.ts` プロジェクトグラフを使用します。これは、マルチシャードのwatchループが現実的ではないためです。 - - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリ指定をまずスコープ付きレーンにルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` はフルルートプロジェクト起動のコストを払わずに済みます。 - - `pnpm test:changed` は、差分がルーティング可能なソース/テストファイルのみを対象にしている場合、変更されたgitパスを同じスコープ付きレーンへ展開します。設定/セットアップの編集は、引き続き広範なルートプロジェクト再実行にフォールバックします。 - - agents、commands、plugins、auto-replyヘルパー、`plugin-sdk` などの純粋なユーティリティ領域にあるimport負荷の軽いunitテストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンにルーティングされます。stateful/runtime-heavyなファイルは既存レーンのままです。 - - 選択された `plugin-sdk` および `commands` のヘルパーソースファイルも、changedモードの実行をこれらの軽量レーン内の明示的な隣接テストへマップするため、ヘルパー編集時にそのディレクトリ全体の重いスイートを再実行せずに済みます。 - - `auto-reply` には現在、3つの専用バケットがあります: トップレベルのコアヘルパー、トップレベルの `reply.*` integrationテスト、そして `src/auto-reply/reply/**` サブツリーです。これにより、最も重いreplyハーネスの処理が、軽量なstatus/chunk/tokenテストに影響しないようにしています。 -- 埋め込みランナーに関する注記: - - メッセージツール検出入力またはCompactionランタイムコンテキストを変更するときは、両方のレベルのカバレッジを維持してください。 - - 純粋なルーティング/正規化境界には、焦点を絞ったヘルパーリグレッションを追加してください。 - - 同時に、埋め込みランナーのintegrationスイートも健全に保ってください: + - 高速で安定しているべき +- projectに関する注記: + - 対象指定なしの `pnpm test` は、1つの巨大なネイティブルートprojectプロセスの代わりに、11個のより小さなshard設定（`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`）を実行するようになりました。これにより、負荷の高いマシンでのピークRSSを削減し、auto-reply/extension作業が無関係なスイートを圧迫するのを防ぎます。 + - `pnpm test --watch` は引き続きネイティブルートの `vitest.config.ts` project graphを使います。複数shardのwatchループは現実的でないためです。 + - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリ指定をまずスコープ付きレーン経由でルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` はフルルートproject起動のコストを回避できます。 + - `pnpm test:changed` は、変更差分がルーティング可能なsource/testファイルだけに触れている場合、変更されたgitパスを同じスコープ付きレーンに展開します。config/setup編集は引き続き広範なルートproject再実行にフォールバックします。 + - agents、commands、plugins、auto-reply helper、`plugin-sdk`、および同様の純粋なutility領域のimport軽量なunitテストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンを経由します。stateful/runtime-heavyなファイルは既存レーンに残ります。 + - 選択された `plugin-sdk` および `commands` helper sourceファイルも、changed-mode実行をそれらの軽量レーン内の明示的な隣接テストにマッピングするため、helper編集でそのディレクトリのフルheavyスイートを再実行せずに済みます。 + - `auto-reply` には現在、3つの専用バケットがあります: トップレベルのcore helper、トップレベルの `reply.*` integrationテスト、および `src/auto-reply/reply/**` サブツリーです。これにより、最も重いreply harness作業が、軽量なstatus/chunk/tokenテストに乗らないようにします。 +- embedded runnerに関する注記: + - メッセージtool discovery入力またはCompaction runtime contextを変更するときは、両方のレベルのカバレッジを維持してください。 + - 純粋なrouting/normalization境界に対する、焦点を絞ったhelperリグレッションを追加してください。 + - さらに、embedded runner integrationスイートも健全に保ってください: `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`、および `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - これらのスイートは、スコープ付きidとCompactionの挙動が実際の `run.ts` / `compact.ts` 経路を通じて流れ続けることを検証します。ヘルパー専用テストだけでは、これらのintegration経路の十分な代替にはなりません。 -- Poolに関する注記: - - ベースVitest設定は現在、デフォルトで `threads` を使用します。 - - 共有Vitest設定は `isolate: false` も固定し、ルートプロジェクト、e2e、live設定全体で非分離ランナーを使用します。 - - ルートUIレーンは `jsdom` セットアップとoptimizerを維持していますが、現在は共有の非分離ランナー上でも動作します。 - - 各 `pnpm test` シャードは、共有Vitest設定から同じ `threads` + `isolate: false` のデフォルトを継承します。 - - 共有の `scripts/run-vitest.mjs` ランチャーは、大規模なローカル実行時のV8コンパイル負荷を減らすため、Vitest子Nodeプロセスにデフォルトで `--no-maglev` も追加するようになりました。標準のV8挙動と比較したい場合は `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 -- 高速ローカル反復に関する注記: - - `pnpm test:changed` は、変更パスがより小さなスイートにきれいにマップされる場合、スコープ付きレーンを経由します。 - - `pnpm test:max` と `pnpm test:changed:max` も同じルーティング挙動を維持しつつ、より高いワーカー上限を使います。 - - ローカルのワーカー自動スケーリングは現在意図的に保守的で、ホストの負荷平均がすでに高いときにも抑制されるため、複数のVitest実行を同時に走らせた際の影響をデフォルトで減らします。 - - ベースVitest設定は、changedモードの再実行がテスト配線の変更時にも正しくなるよう、プロジェクト/設定ファイルを `forceRerunTriggers` としてマークします。 - - 設定は、サポートされるホスト上で `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効にしたままにします。直接プロファイリング用に明示的なキャッシュ場所を1つ指定したい場合は `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 -- パフォーマンスデバッグに関する注記: - - `pnpm test:perf:imports` は、Vitestのimport時間レポートとimport内訳出力を有効にします。 - - `pnpm test:perf:imports:changed` は、同じプロファイリング表示を `origin/main` 以降で変更されたファイルに絞り込みます。 -- `pnpm test:perf:changed:bench -- --ref ` は、そのコミット済み差分について、ルーティングされた `test:changed` とネイティブルートプロジェクト経路を比較し、wall timeとmacOSの最大RSSを表示します。 -- `pnpm test:perf:changed:bench -- --worktree` は、変更されたファイル一覧を `scripts/test-projects.mjs` とルートVitest設定に通すことで、現在の未コミットツリーをベンチマークします。 - - `pnpm test:perf:profile:main` は、Vitest/Viteの起動およびtransformオーバーヘッドに対するメインスレッドCPUプロファイルを書き出します。 - - `pnpm test:perf:profile:runner` は、ファイル並列実行を無効にしたunitスイート向けに、ランナーのCPU+heapプロファイルを書き出します。 + - これらのスイートは、スコープ付きidとCompactionの挙動が依然として実際の `run.ts` / `compact.ts` パスを通って流れることを検証します。helperのみのテストは、これらのintegrationパスの十分な代替にはなりません。 +- poolに関する注記: + - ベースのVitest設定は現在デフォルトで `threads` です。 + - 共有Vitest設定では、`isolate: false` も固定され、root projects、e2e、live設定全体で非分離runnerを使います。 + - ルートUIレーンはその `jsdom` setupとoptimizerを維持していますが、現在は共有の非分離runnerでも実行されます。 + - 各 `pnpm test` shardは、共有Vitest設定から同じ `threads` + `isolate: false` のデフォルトを継承します。 + - 共有の `scripts/run-vitest.mjs` launcherは現在、Vitestの子Nodeプロセスに対してデフォルトで `--no-maglev` も追加し、大規模なローカル実行中のV8 compile churnを減らします。標準のV8挙動と比較したい場合は `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 +- 高速なローカル反復に関する注記: + - `pnpm test:changed` は、変更パスがより小さなスイートにきれいにマップされるとき、スコープ付きレーン経由でルーティングします。 + - `pnpm test:max` と `pnpm test:changed:max` は同じルーティング挙動を維持しつつ、worker上限だけを高くします。 + - ローカルworkerの自動スケーリングは現在意図的に保守的で、ホストのload averageがすでに高い場合にもバックオフするため、複数の同時Vitest実行がデフォルトで与える悪影響を減らします。 + - ベースのVitest設定は、テスト配線が変わったときにchanged-mode再実行の正しさを保つため、projects/configファイルを `forceRerunTriggers` としてマークします。 + - この設定は、サポート対象ホストで `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効に保ちます。直接プロファイリング用に明示的なキャッシュ場所を1つ使いたい場合は `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 +- perf-debugに関する注記: + - `pnpm test:perf:imports` はVitestのimport-durationレポートとimport-breakdown出力を有効にします。 + - `pnpm test:perf:imports:changed` は、同じプロファイリング表示を `origin/main` 以降に変更されたファイルに限定します。 +- `pnpm test:perf:changed:bench -- --ref ` は、そのコミット済み差分に対するルーティング済み `test:changed` とネイティブルートprojectパスを比較し、wall timeとmacOS max RSSを表示します。 +- `pnpm test:perf:changed:bench -- --worktree` は、変更済みファイル一覧を `scripts/test-projects.mjs` とルートVitest設定経由でルーティングすることで、現在のdirty treeをベンチマークします。 + - `pnpm test:perf:profile:main` は、Vitest/Viteの起動とtransform overhead向けのmain-thread CPU profileを書き出します。 + - `pnpm test:perf:profile:runner` は、ファイル並列性を無効にしたunitスイート向けのrunner CPU+heap profileを書き出します。 ### E2E（Gatewayスモーク） - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` - ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts` -- ランタイムのデフォルト: - - リポジトリの他の部分に合わせて、Vitest `threads` と `isolate: false` を使用します。 - - 適応型ワーカーを使用します（CI: 最大2、ローカル: デフォルト1）。 - - コンソールI/Oのオーバーヘッドを減らすため、デフォルトでsilentモードで実行します。 +- ランタイムデフォルト: + - リポジトリの他の部分に合わせて、Vitest `threads` と `isolate: false` を使います。 + - 適応型workerを使います（CI: 最大2、ローカル: デフォルトで1）。 + - コンソールI/O overheadを減らすため、デフォルトでsilent modeで実行します。 - 便利な上書き: - - ワーカー数を強制するには `OPENCLAW_E2E_WORKERS=`（上限16）。 - - 詳細なコンソール出力を再有効化するには `OPENCLAW_E2E_VERBOSE=1`。 + - worker数を強制する `OPENCLAW_E2E_WORKERS=`（上限16） + - 詳細なコンソール出力を再度有効にする `OPENCLAW_E2E_VERBOSE=1` - スコープ: - - 複数インスタンスのGatewayエンドツーエンド挙動 - - WebSocket/HTTPサーフェス、Nodeペアリング、およびより重いネットワーキング -- 期待事項: - - CIで実行される（パイプラインで有効化されている場合） + - 複数インスタンスのGateway end-to-end挙動 + - WebSocket/HTTP surface、Node pairing、およびより重いネットワーキング +- 想定: + - CIで実行される（パイプラインで有効な場合） - 実際のキーは不要 - - unitテストより可動部分が多い（遅くなる可能性がある） + - unitテストより可動部分が多い（遅くなることがある） -### E2E: OpenShellバックエンドスモーク +### E2E: OpenShell backendスモーク - コマンド: `pnpm test:e2e:openshell` - ファイル: `test/openshell-sandbox.e2e.test.ts` - スコープ: - - Docker経由でホスト上に隔離されたOpenShell Gatewayを起動する + - Docker経由でホスト上に分離されたOpenShell Gatewayを起動する - 一時的なローカルDockerfileからsandboxを作成する - - 実際の `sandbox ssh-config` + SSH実行を通じて、OpenClawのOpenShellバックエンドを検証する - - sandbox fsブリッジを通じて、リモート正準ファイルシステム挙動を検証する -- 期待事項: - - 明示的に有効化した場合のみ。デフォルトの `pnpm test:e2e` 実行には含まれない - - ローカルの `openshell` CLI と動作するDockerデーモンが必要 - - 隔離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テスト用Gatewayとsandboxを破棄する + - 実際の `sandbox ssh-config` + SSH execを介してOpenClawのOpenShell backendを実行する + - sandbox fs bridgeを通じてremote-canonical filesystem挙動を検証する +- 想定: + - オプトイン専用。デフォルトの `pnpm test:e2e` 実行には含まれない + - ローカルの `openshell` CLIと動作するDocker daemonが必要 + - 分離された `HOME` / `XDG_CONFIG_HOME` を使い、その後テストGatewayとsandboxを破棄する - 便利な上書き: - - より広いe2eスイートを手動実行するときにこのテストを有効化するには `OPENCLAW_E2E_OPENSHELL=1` - - デフォルト以外のCLIバイナリまたはラッパースクリプトを指定するには `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` + - より広いe2eスイートを手動実行するときにテストを有効化する `OPENCLAW_E2E_OPENSHELL=1` + - デフォルト以外のCLI binaryまたはwrapper scriptを指す `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` ### Live（実際のプロバイダー + 実際のモデル） @@ -334,141 +336,141 @@ Markdown QAシステムにチャネルを追加するには、必要なのは正 - ファイル: `src/**/*.live.test.ts` - デフォルト: `pnpm test:live` により **有効**（`OPENCLAW_LIVE_TEST=1` を設定） - スコープ: - - 「このプロバイダー/モデルは、今日、実際の認証情報で本当に動くか？」 - - プロバイダーのフォーマット変更、ツール呼び出しの癖、認証問題、レート制限挙動を捕捉する -- 期待事項: - - 設計上、CI安定ではない（実ネットワーク、実際のプロバイダーポリシー、クォータ、障害） - - コストがかかる / レート制限を消費する - - 「すべて」を実行するより、対象を絞ったサブセット実行を推奨 -- live実行は、不足しているAPIキーを拾うために `~/.profile` を読み込みます。 -- デフォルトでは、live実行は依然として `HOME` を隔離し、設定/認証情報を一時的なテスト用homeにコピーするため、unitフィクスチャが実際の `~/.openclaw` を変更することはありません。 -- liveテストで意図的に実際のhomeディレクトリを使いたい場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 -- `pnpm test:live` は現在、より静かなモードがデフォルトです。`[live] ...` の進行出力は維持しますが、追加の `~/.profile` 通知を抑制し、Gatewayブートストラップログ/Bonjourの雑音をミュートします。完全な起動ログを再表示したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 -- APIキーのローテーション（プロバイダー別）: カンマ/セミコロン形式の `*_API_KEYS`、または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）を設定するか、live専用の上書きとして `OPENCLAW_LIVE_*_KEY` を使用します。テストはレート制限応答時にリトライします。 -- 進行/Heartbeat出力: - - liveスイートは現在、長時間のプロバイダー呼び出しが、Vitestのコンソールキャプチャが静かな場合でも動作中だと分かるよう、進行行をstderrに出力します。 - - `vitest.live.config.ts` はVitestのコンソール横取りを無効化しているため、プロバイダー/Gatewayの進行行はlive実行中に即座にストリーミングされます。 - - 直接モデルのHeartbeat調整には `OPENCLAW_LIVE_HEARTBEAT_MS` を使用します。 - - Gateway/プローブのHeartbeat調整には `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` を使用します。 + - 「このプロバイダー/モデルは、実際の認証情報で _今日_ 本当に動くか？」 + - プロバイダーのフォーマット変更、tool-callingの癖、authの問題、rate limit挙動を検出する +- 想定: + - 設計上CIで安定しない（実ネットワーク、実プロバイダーポリシー、quota、障害） + - コストがかかる / rate limitを消費する + - 「全部」よりも、絞り込んだサブセットを実行するのを優先する +- live実行は、欠けているAPIキーを取得するために `~/.profile` をsourceします。 +- デフォルトでは、live実行は依然として `HOME` を分離し、config/auth materialを一時テストホームにコピーします。これにより、unit fixtureが実際の `~/.openclaw` を変更できないようにします。 +- liveテストで実際のhomeディレクトリを意図的に使う必要がある場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 +- `pnpm test:live` は現在、より静かなモードがデフォルトです。`[live] ...` の進捗出力は維持しますが、追加の `~/.profile` 通知を抑制し、Gateway bootstrapログ/Bonjour chatterをミュートします。完全な起動ログを再び見たい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 +- APIキーのローテーション（プロバイダー固有）: カンマ/セミコロン形式の `*_API_KEYS` または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）を設定するか、live専用上書きとして `OPENCLAW_LIVE_*_KEY` を使ってください。テストはrate limit応答時に再試行します。 +- 進捗/Heartbeat出力: + - liveスイートは現在、長いプロバイダー呼び出しがVitestのコンソールキャプチャが静かなときでも活動中であることが見えるよう、進捗行をstderrに出力します。 + - `vitest.live.config.ts` はVitestのコンソールインターセプトを無効にしているため、プロバイダー/Gatewayの進捗行はlive実行中に即時ストリームされます。 + - 直接モデルのHeartbeatは `OPENCLAW_LIVE_HEARTBEAT_MS` で調整します。 + - Gateway/probeのHeartbeatは `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 ## どのスイートを実行すべきか？ この判断表を使ってください。 -- ロジック/テストを編集した: `pnpm test` を実行（大きく変更したなら `pnpm test:coverage` も） -- Gatewayのネットワーキング / WSプロトコル / ペアリングに触れた: `pnpm test:e2e` を追加 -- 「自分のボットが落ちている」/ プロバイダー固有の失敗 / ツール呼び出しをデバッグしている: 絞り込んだ `pnpm test:live` を実行 +- ロジック/テストを編集している: `pnpm test` を実行する（大きく変更した場合は `pnpm test:coverage` も） +- Gatewayネットワーキング / WS protocol / pairingに触れる: `pnpm test:e2e` を追加する +- 「botが落ちている」問題 / プロバイダー固有の失敗 / tool callingをデバッグしている: 絞り込んだ `pnpm test:live` を実行する -## Live: Android Node機能スイープ +## Live: Android Node capability sweep - テスト: `src/gateway/android-node.capabilities.live.test.ts` - スクリプト: `pnpm android:test:integration` -- 目的: 接続されたAndroid Nodeが**現在広告しているすべてのコマンド**を呼び出し、コマンド契約の挙動を検証すること。 +- 目標: 接続されたAndroid Nodeが現在公開している **すべてのコマンド** を呼び出し、コマンド契約の挙動を検証する。 - スコープ: - - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/起動/ペアリングを行いません）。 + - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/実行/pairingは行いません）。 - 選択されたAndroid Nodeに対する、コマンドごとのGateway `node.invoke` 検証。 -- 必須の事前セットアップ: - - AndroidアプリがすでにGatewayに接続され、ペアリングされていること。 - - アプリがフォアグラウンドに保たれていること。 - - 成功を期待する機能に対して、権限/キャプチャ同意が付与されていること。 +- 必要な事前セットアップ: + - AndroidアプリがすでにGatewayに接続済みで、pairing済みであること。 + - アプリが前面に維持されていること。 + - 成功を期待するcapabilityに対して、権限/キャプチャ同意が付与されていること。 - 任意のターゲット上書き: - - `OPENCLAW_ANDROID_NODE_ID` または `OPENCLAW_ANDROID_NODE_NAME` - - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD` + - `OPENCLAW_ANDROID_NODE_ID` または `OPENCLAW_ANDROID_NODE_NAME`。 + - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。 - Androidの完全なセットアップ詳細: [Android App](/ja-JP/platforms/android) -## Live: モデルスモーク（プロファイルキー） +## Live: modelスモーク（profileキー） -liveテストは、失敗を切り分けられるよう2層に分かれています。 +liveテストは、失敗を切り分けられるよう2つのレイヤーに分かれています。 -- 「直接モデル」は、与えられたキーでそのプロバイダー/モデルがそもそも応答できるかを示します。 -- 「Gatewayスモーク」は、そのモデルに対してGateway+エージェントの完全なパイプライン（セッション、履歴、ツール、sandboxポリシーなど）が機能することを示します。 +- 「Direct model」は、与えられたキーでそのプロバイダー/モデルが少なくとも応答できるかを示します。 +- 「Gateway smoke」は、そのモデルに対して完全なGateway+エージェントパイプラインが動作するか（sessions、history、tools、sandbox policyなど）を示します。 -### レイヤー1: 直接モデル完了（Gatewayなし） +### レイヤー1: Direct model completion（Gatewayなし） - テスト: `src/agents/models.profiles.live.test.ts` -- 目的: +- 目標: - 発見されたモデルを列挙する - - `getApiKeyForModel` を使用して、認証情報を持っているモデルを選択する - - モデルごとに小さな完了処理を実行する（必要に応じて対象を絞ったリグレッションも） + - `getApiKeyForModel` を使って、認証情報を持つモデルを選択する + - モデルごとに小さなcompletionを実行する（必要に応じて対象を絞ったリグレッションも） - 有効化方法: - `pnpm test:live`（またはVitestを直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） -- このスイートを実際に実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、これはmodernの別名）を設定します。そうでない場合、`pnpm test:live` をGatewayスモークに集中させるためにスキップされます。 +- このスイートを実際に実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、`modern` のエイリアス）を設定してください。そうしないと、`pnpm test:live` をGatewayスモークに集中させるためスキップされます - モデルの選択方法: - - modern allowlistを実行するには `OPENCLAW_LIVE_MODELS=modern`（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - - `OPENCLAW_LIVE_MODELS=all` はmodern allowlistの別名です + - `OPENCLAW_LIVE_MODELS=modern` でmodern allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）を実行 + - `OPENCLAW_LIVE_MODELS=all` はmodern allowlistのエイリアス - または `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（カンマ区切りallowlist） - - modern/allスイープは、デフォルトで厳選された高信号の上限を使用します。網羅的なmodernスイープには `OPENCLAW_LIVE_MAX_MODELS=0`、より小さい上限には正の数を設定します。 + - modern/all sweepはデフォルトで厳選された高シグナル上限を使います。網羅的なmodern sweepには `OPENCLAW_LIVE_MAX_MODELS=0`、より小さい上限には正の数を設定してください。 - プロバイダーの選択方法: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（カンマ区切りallowlist） - キーの取得元: - - デフォルト: プロファイルストアとenvフォールバック - - **プロファイルストアのみ** を強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` を設定 + - デフォルト: profile storeおよびenv fallback + - **profile store** のみを強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` を設定 - これが存在する理由: - - 「プロバイダーAPIが壊れている / キーが無効」と「Gatewayエージェントパイプラインが壊れている」を切り分ける - - 小さく隔離されたリグレッションを収容する（例: OpenAI Responses/Codex Responsesのreasoning replay + tool-callフロー） + - 「プロバイダーAPIが壊れている / キーが無効」であることと、「Gatewayエージェントパイプラインが壊れている」ことを分離する + - 小さく分離されたリグレッションを含める（例: OpenAI Responses/Codex Responsesのreasoning replay + tool-callフロー） ### レイヤー2: Gateway + devエージェントスモーク（`@openclaw` が実際に行うこと） - テスト: `src/gateway/gateway-models.profiles.live.test.ts` -- 目的: +- 目標: - プロセス内Gatewayを起動する - - `agent:dev:*` セッションを作成/patchする（実行ごとにモデル上書き） - - キー付きモデルを反復し、次を検証する: - - 「意味のある」応答（ツールなし） - - 実際のツール呼び出しが機能すること（readプローブ） - - 任意の追加ツールプローブ（exec+readプローブ） - - OpenAIのリグレッション経路（tool-call-only → follow-up）が引き続き機能すること -- プローブの詳細（失敗をすばやく説明できるように）: - - `read` プローブ: テストがワークスペースにnonceファイルを書き込み、エージェントにそれを `read` してnonceをそのまま返すよう求めます。 - - `exec+read` プローブ: テストがエージェントに対して `exec` で一時ファイルにnonceを書き込み、その後それを `read` で読み戻すよう求めます。 - - imageプローブ: テストが生成したPNG（cat + ランダム化コード）を添付し、モデルが `cat ` を返すことを期待します。 - - 実装参照: `src/gateway/gateway-models.profiles.live.test.ts` および `src/gateway/live-image-probe.ts` + - `agent:dev:*` sessionを作成/patchする（実行ごとのmodel override） + - キーを持つモデル群を反復し、以下を検証する: + - 「意味のある」応答（toolなし） + - 実際のtool呼び出しが動作すること（read probe） + - 任意の追加tool probe（exec+read probe） + - OpenAIのリグレッション経路（tool-call-only → follow-up）が引き続き動作すること +- probeの詳細（失敗をすばやく説明できるように）: + - `read` probe: テストはworkspaceにnonceファイルを書き込み、エージェントにそれを `read` してnonceを返答でそのまま返すよう求めます。 + - `exec+read` probe: テストはエージェントに `exec` でtempファイルへnonceを書かせ、その後それを `read` で読み戻させます。 + - image probe: テストは生成したPNG（猫 + ランダムコード）を添付し、モデルが `cat ` を返すことを期待します。 + - 実装参照: `src/gateway/gateway-models.profiles.live.test.ts` と `src/gateway/live-image-probe.ts`。 - 有効化方法: - `pnpm test:live`（またはVitestを直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） - モデルの選択方法: - デフォルト: modern allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` はmodern allowlistの別名です - - または `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（またはカンマ区切りリスト）を設定して絞り込む - - modern/allのGatewayスイープは、デフォルトで厳選された高信号の上限を使用します。網羅的なmodernスイープには `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`、より小さい上限には正の数を設定します。 + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` はmodern allowlistのエイリアス + - または `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（またはカンマ区切りリスト）で絞り込む + - modern/allのGateway sweepはデフォルトで厳選された高シグナル上限を使います。網羅的なmodern sweepには `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`、より小さな上限には正の数を設定してください。 - プロバイダーの選択方法（「OpenRouterを全部」は避ける）: - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（カンマ区切りallowlist） -- このliveテストではツール + imageプローブは常時有効です: - - `read` プローブ + `exec+read` プローブ（ツール負荷テスト） - - imageプローブは、モデルがimage入力サポートを公開している場合に実行されます - - フロー（概要）: - - テストが「CAT」+ ランダムコードの小さなPNGを生成します（`src/gateway/live-image-probe.ts`） - - これを `agent` の `attachments: [{ mimeType: "image/png", content: "" }]` 経由で送信します - - Gatewayが添付を `images[]` にパースします（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） - - 埋め込みエージェントがマルチモーダルなユーザーメッセージをモデルへ転送します - - 検証: 返信に `cat` + そのコードが含まれること（OCR許容: 軽微な誤りは許容） +- このliveテストではtool + image probeは常に有効です: + - `read` probe + `exec+read` probe（tool stress） + - image probeは、モデルがimage input supportを公開している場合に実行されます + - フロー（高レベル）: + - テストは「CAT」+ ランダムコードを含む小さなPNGを生成する（`src/gateway/live-image-probe.ts`） + - それを `agent` の `attachments: [{ mimeType: "image/png", content: "" }]` 経由で送信する + - Gatewayは添付を `images[]` に解析する（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） + - embeddedエージェントはmultimodal user messageをモデルへ転送する + - 検証: 返答に `cat` + そのコードが含まれること（OCR許容: 軽微な誤りは許容） -ヒント: 自分のマシンで何をテストできるか（および正確な `provider/model` id）を確認するには、次を実行してください。 +ヒント: 自分のマシンで何をテストできるか（および正確な `provider/model` id）を確認するには、以下を実行してください。 ```bash openclaw models list openclaw models list --json ``` -## Live: CLIバックエンドスモーク（Claude、Codex、Gemini、またはその他のローカルCLI） +## Live: CLI backendスモーク（Claude、Codex、Gemini、またはその他のローカルCLI） - テスト: `src/gateway/gateway-cli-backend.live.test.ts` -- 目的: デフォルト設定に触れずに、ローカルCLIバックエンドを使ってGateway + エージェントのパイプラインを検証する。 -- バックエンド固有のスモークデフォルトは、所有するextensionの `cli-backend.ts` 定義とともに置かれます。 +- 目標: デフォルトconfigに触れずに、ローカルCLI backendを使ってGateway + エージェントパイプラインを検証する。 +- backend固有のスモークデフォルトは、所有extensionの `cli-backend.ts` 定義にあります。 - 有効化: - `pnpm test:live`（またはVitestを直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） - `OPENCLAW_LIVE_CLI_BACKEND=1` - デフォルト: - - デフォルトのプロバイダー/モデル: `claude-cli/claude-sonnet-4-6` - - コマンド/引数/image挙動は、所有するCLIバックエンドPluginメタデータから取得されます。 + - デフォルトのprovider/model: `claude-cli/claude-sonnet-4-6` + - command/args/imageの挙動は、所有CLI backend Plugin metadataから取得されます。 - 上書き（任意）: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - 実際のimage添付を送信するには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`（パスはプロンプトへ注入されます） - - プロンプト注入の代わりにimageファイルパスをCLI引数として渡すには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` - - `IMAGE_ARG` が設定されている場合のimage引数の渡し方を制御するには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または `"list"`） - - 2ターン目を送ってresumeフローを検証するには `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` - - デフォルトのClaude Sonnet -> Opus同一セッション継続プローブを無効にするには `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択したモデルが切り替え先をサポートしている場合に強制有効化するには `1` を設定） + - 実際のimage attachmentを送るには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`（パスはpromptに注入されます）。 + - prompt注入の代わりにimage file pathをCLI argsとして渡すには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`。 + - `IMAGE_ARG` が設定されているときにimage argsの渡し方を制御するには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または `"list"`）。 + - 2回目のターンを送ってresumeフローを検証するには `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`。 + - デフォルトのClaude Sonnet -> Opus同一session継続probeを無効にするには `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択したmodelがswitch targetをサポートしているときに強制的に有効化するには `1` を設定）。 例: @@ -496,28 +498,28 @@ pnpm test:docker:live-cli-backend:gemini 注記: - Dockerランナーは `scripts/test-live-cli-backend-docker.sh` にあります。 -- これはリポジトリのDockerイメージ内で、非rootの `node` ユーザーとしてlive CLIバックエンドスモークを実行します。 -- 所有するextensionからCLIスモークメタデータを解決し、一致するLinux CLIパッケージ（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）を、キャッシュ可能で書き込み可能なprefix `OPENCLAW_DOCKER_CLI_TOOLS_DIR`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）にインストールします。 -- `pnpm test:docker:live-cli-backend:claude-subscription` には、`~/.claude/.credentials.json` と `claudeAiOauth.subscriptionType`、または `claude setup-token` の `CLAUDE_CODE_OAUTH_TOKEN` によるポータブルなClaude CodeサブスクリプションOAuthが必要です。まずDocker内で直接 `claude -p` を検証し、その後Anthropic APIキー環境変数を保持せずに2回のGateway CLIバックエンドターンを実行します。このsubscriptionレーンでは、Claudeが現在サードパーティアプリ利用を通常のsubscriptionプラン上限ではなく追加利用課金経由で処理するため、Claude MCP/ツールおよびimageプローブはデフォルトで無効になります。 -- live CLIバックエンドスモークは現在、Claude、Codex、Geminiに対して同じエンドツーエンドフローを検証します: テキストターン、image分類ターン、その後Gateway CLI経由で検証されるMCP `cron` ツール呼び出しです。 -- Claudeのデフォルトスモークでは、セッションをSonnetからOpusへpatchし、resumeしたセッションが以前のメモを引き続き覚えていることも検証します。 +- これはリポジトリのDocker image内で、非rootの `node` userとしてlive CLI-backendスモークを実行します。 +- 所有extensionからCLI smoke metadataを解決し、その後、一致するLinux CLI package（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）を、キャッシュ可能で書き込み可能なprefix `OPENCLAW_DOCKER_CLI_TOOLS_DIR`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）にインストールします。 +- `pnpm test:docker:live-cli-backend:claude-subscription` は、`~/.claude/.credentials.json` 内の `claudeAiOauth.subscriptionType`、または `claude setup-token` の `CLAUDE_CODE_OAUTH_TOKEN` を使ったポータブルなClaude Code subscription OAuthを必要とします。これはまずDocker内で直接 `claude -p` を検証し、その後Anthropic APIキー環境変数を保持せずに、2回のGateway CLI-backendターンを実行します。このsubscriptionレーンでは、Claudeが現在サードパーティapp利用を通常のsubscriptionプラン上限ではなく追加利用課金経由で扱うため、ClaudeのMCP/toolおよびimage probeはデフォルトで無効です。 +- live CLI-backendスモークは現在、Claude、Codex、Geminiに対して同じend-to-endフローを実行します: text turn、image classification turn、その後Gateway CLI経由で検証されるMCP `cron` tool call。 +- Claudeのデフォルトスモークは、sessionをSonnetからOpusへpatchし、再開したsessionが以前のメモをまだ覚えていることも検証します。 ## Live: ACP bindスモーク（`/acp spawn ... --bind here`） - テスト: `src/gateway/gateway-acp-bind.live.test.ts` -- 目的: live ACPエージェントを使って、実際のACP会話bindフローを検証すること: - - `/acp spawn --bind here` を送信 - - 合成のメッセージチャネル会話をその場でbind - - 同じ会話上で通常のfollow-upを送信 - - そのfollow-upがbind済みACPセッショントランスクリプトに入ることを確認 +- 目標: live ACPエージェントで実際のACP conversation-bindフローを検証する: + - `/acp spawn --bind here` を送る + - syntheticなmessage-channel conversationをその場でbindする + - 同じconversationで通常のfollow-upを送る + - そのfollow-upがbind済みACP session transcriptに到達することを検証する - 有効化: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - デフォルト: - Docker内のACPエージェント: `claude,codex,gemini` - - 直接の `pnpm test:live ...` 用ACPエージェント: `claude` - - 合成チャネル: Slack DM風の会話コンテキスト - - ACPバックエンド: `acpx` + - 直接 `pnpm test:live ...` 用のACPエージェント: `claude` + - synthetic channel: Slack DM風conversation context + - ACP backend: `acpx` - 上書き: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -525,8 +527,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - 注記: - - このレーンは、テストが外部配信を装わずにメッセージチャネルコンテキストを付与できるよう、管理者専用の合成originating-routeフィールド付きのGateway `chat.send` サーフェスを使います。 - - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、テストは埋め込みの `acpx` Plugin内蔵エージェントレジストリを、選択されたACPハーネスエージェント向けに使用します。 + - このレーンはGatewayの `chat.send` surfaceを使い、admin専用のsyntheticなoriginating-route fieldで、外部配信を装わずにmessage-channel contextを付与できるようにしています。 + - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、テストは選択したACP harness agentに対して、embedded `acpx` Pluginの組み込みagent registryを使います。 例: @@ -553,31 +555,30 @@ pnpm test:docker:live-acp-bind:gemini Dockerに関する注記: - Dockerランナーは `scripts/test-live-acp-bind-docker.sh` にあります。 -- デフォルトでは、サポートされるすべてのlive CLIエージェントに対してACP bindスモークを順番に実行します: `claude`、`codex`、`gemini`。 -- マトリクスを絞り込むには `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使用します。 -- これは `~/.profile` を読み込み、一致するCLI認証情報をコンテナへステージし、`acpx` を書き込み可能なnpm prefixにインストールし、不足している場合は要求されたlive CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）をインストールします。 -- Docker内では、ランナーは `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` を設定し、ソース済みprofileからのプロバイダーenv変数をacpxが子ハーネスCLIでも利用できるようにします。 +- デフォルトでは、サポートされているすべてのlive CLIエージェント `claude`、`codex`、`gemini` に対して順にACP bindスモークを実行します。 +- マトリクスを絞り込むには、`OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使ってください。 +- これは `~/.profile` をsourceし、一致するCLI auth materialをcontainerへステージし、`acpx` を書き込み可能なnpm prefixにインストールし、その後、必要なら要求されたlive CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）をインストールします。 +- Docker内では、runnerは `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` を設定し、sourceしたprofile由来のprovider env varsが子harness CLIからも利用できるようにします。 -## Live: Codex app-serverハーネススモーク +## Live: Codex app-server harnessスモーク -- 目的: Pluginが所有するCodexハーネスを、通常のGateway - `agent` メソッド経由で検証すること: - - バンドル済みの `codex` Pluginを読み込む +- 目標: 通常のGateway + `agent` methodを通じて、Plugin所有のCodex harnessを検証する: + - バンドルされた `codex` Pluginを読み込む - `OPENCLAW_AGENT_RUNTIME=codex` を選択する - - `codex/gpt-5.4` に最初のGateway agentターンを送る - - 同じOpenClawセッションに2ターン目を送り、app-server - スレッドがresumeできることを確認する - - 同じGatewayコマンド - 経路を通じて `/codex status` と `/codex models` を実行する + - `codex/gpt-5.4` に対して最初のGateway agent turnを送る + - 同じOpenClaw sessionに2回目のturnを送り、app-server threadがresumeできることを検証する + - 同じGateway command + path経由で `/codex status` と `/codex models` を実行する - テスト: `src/gateway/gateway-codex-harness.live.test.ts` - 有効化: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- デフォルトモデル: `codex/gpt-5.4` -- 任意のimageプローブ: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- 任意のMCP/ツールプローブ: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- デフォルトmodel: `codex/gpt-5.4` +- 任意のimage probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- 任意のMCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - このスモークは `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を設定するため、壊れたCodex - ハーネスがPIへのサイレントフォールバックによって通過することはありません。 -- 認証: シェル/profileからの `OPENAI_API_KEY`、および任意でコピーされる - `~/.codex/auth.json` と `~/.codex/config.toml` + harnessがPIへのサイレントfallbackで通過することはありません。 +- auth: shell/profileの `OPENAI_API_KEY` と、必要に応じてコピーされる + `~/.codex/auth.json` および `~/.codex/config.toml` ローカルレシピ: @@ -600,45 +601,47 @@ pnpm test:docker:live-codex-harness Dockerに関する注記: - Dockerランナーは `scripts/test-live-codex-harness-docker.sh` にあります。 -- これはマウントされた `~/.profile` を読み込み、`OPENAI_API_KEY` を渡し、Codex CLI認証ファイルが存在する場合はそれをコピーし、`@openai/codex` を書き込み可能なマウント済みnpm prefixにインストールし、ソースツリーをステージしたうえで、Codexハーネスliveテストのみを実行します。 -- DockerではimageおよびMCP/ツールプローブがデフォルトで有効です。より狭いデバッグ実行が必要な場合は +- これはマウントされた `~/.profile` をsourceし、`OPENAI_API_KEY` を渡し、Codex CLI + authファイルが存在する場合はそれをコピーし、`@openai/codex` を書き込み可能なマウント済みnpm + prefixにインストールし、source treeをステージした後、Codex-harness liveテストのみを実行します。 +- DockerではimageおよびMCP/tool probeがデフォルトで有効です。より狭いデバッグ実行が必要な場合は、 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` または `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` を設定してください。 -- Dockerでも `OPENCLAW_AGENT_HARNESS_FALLBACK=none` をエクスポートし、live - テスト設定と一致させます。これにより `openai-codex/*` やPIフォールバックがCodexハーネスの - リグレッションを隠すことはできません。 +- Dockerも `OPENCLAW_AGENT_HARNESS_FALLBACK=none` をエクスポートし、live + test設定と一致させるため、`openai-codex/*` やPI fallbackがCodex harness + regressionを隠すことはできません。 -### 推奨されるliveレシピ +### 推奨liveレシピ -狭く明示的なallowlistが最も高速で、最も不安定さが少なくなります。 +狭く明示的なallowlistが最も高速で不安定さも最小です。 -- 単一モデル、直接（Gatewayなし）: +- 単一model、direct（Gatewayなし）: - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- 単一モデル、Gatewayスモーク: +- 単一model、Gatewayスモーク: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 複数プロバイダーにまたがるツール呼び出し: +- 複数プロバイダーにまたがるtool calling: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Google重視（Gemini APIキー + Antigravity）: - - Gemini（APIキー）: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Google重視（Gemini API key + Antigravity）: + - Gemini（API key）: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity（OAuth）: `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` 注記: -- `google/...` はGemini APIを使用します（APIキー）。 -- `google-antigravity/...` はAntigravity OAuthブリッジを使用します（Cloud Code Assist風のエージェントエンドポイント）。 -- `google-gemini-cli/...` はあなたのマシン上のローカルGemini CLIを使用します（別個の認証 + ツール面での癖があります）。 +- `google/...` はGemini API（APIキー）を使います。 +- `google-antigravity/...` はAntigravity OAuth bridge（Cloud Code Assist風エージェントエンドポイント）を使います。 +- `google-gemini-cli/...` はあなたのマシン上のローカルGemini CLIを使います（別個のauth + toolingの癖があります）。 - Gemini APIとGemini CLIの違い: - - API: OpenClawがGoogleのホスト型Gemini APIをHTTP経由で呼び出します（APIキー / プロファイル認証）。ほとんどのユーザーが「Gemini」と言うとき、これを指します。 - - CLI: OpenClawがローカルの `gemini` バイナリをshell実行します。独自の認証があり、挙動も異なることがあります（ストリーミング/ツールサポート/バージョン差異）。 + - API: OpenClawはGoogleのホストされたGemini APIをHTTP経由で呼び出します（APIキー / profile auth）。これは、ほとんどのユーザーが「Gemini」と言うときに意味しているものです。 + - CLI: OpenClawはローカルの `gemini` binaryをshell outして使います。独自のauthを持ち、挙動も異なることがあります（streaming/tool support/version skew）。 -## Live: モデルマトリクス（何をカバーするか） +## Live: model matrix（何をカバーするか） -固定の「CIモデル一覧」はありません（liveはオプトイン）が、開発マシン上でキー付きで定期的にカバーすることを**推奨**するモデルは次のとおりです。 +固定の「CI model list」はありません（liveはオプトインです）が、キーを持つdevマシンで定期的にカバーすることを**推奨**するモデルは以下です。 -### Modernスモークセット（ツール呼び出し + image） +### Modernスモークセット（tool calling + image） これは、動作し続けることを期待する「一般的なモデル」実行です。 @@ -650,12 +653,12 @@ Dockerに関する注記: - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -ツール + image付きでGatewayスモークを実行: +tools + image付きでGatewayスモークを実行: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### ベースライン: ツール呼び出し（Read + 任意のExec） +### ベースライン: tool calling（Read + 任意のExec） -プロバイダーファミリーごとに少なくとも1つは選んでください。 +少なくとも各プロバイダーファミリーから1つ選んでください。 - OpenAI: `openai/gpt-5.4`（または `openai/gpt-5.4-mini`） - Anthropic: `anthropic/claude-opus-4-6`（または `anthropic/claude-sonnet-4-6`） @@ -663,44 +666,44 @@ Dockerに関する注記: - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -任意の追加カバレッジ（あるとよいもの）: +任意の追加カバレッジ（あると望ましい）: - xAI: `xai/grok-4`（または利用可能な最新） - Mistral: `mistral/`…（有効化されている「tools」対応モデルを1つ選ぶ） -- Cerebras: `cerebras/`…（アクセス権がある場合） -- LM Studio: `lmstudio/`…（ローカル。ツール呼び出しはAPIモードに依存） +- Cerebras: `cerebras/`…（アクセスできる場合） +- LM Studio: `lmstudio/`…（ローカル。tool callingはAPI modeに依存） -### Vision: image送信（添付 → マルチモーダルメッセージ） +### Vision: image送信（attachment → multimodal message） -imageプローブを検証するため、`OPENCLAW_LIVE_GATEWAY_MODELS` には少なくとも1つのimage対応モデル（Claude/Gemini/OpenAIのvision対応バリアントなど）を含めてください。 +image probeを実行するために、少なくとも1つのimage対応モデル（Claude/Gemini/OpenAIのvision対応バリアントなど）を `OPENCLAW_LIVE_GATEWAY_MODELS` に含めてください。 -### アグリゲーター / 代替Gateway +### Aggregator / 代替Gateway -キーが有効なら、次経由のテストもサポートしています。 +キーが有効なら、以下経由でのテストもサポートしています。 -- OpenRouter: `openrouter/...`（数百のモデル。ツール+image対応候補を探すには `openclaw models scan` を使用） -- OpenCode: Zen向けの `opencode/...` およびGo向けの `opencode-go/...`（認証は `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`） +- OpenRouter: `openrouter/...`（数百のモデル。tool+image対応候補を見つけるには `openclaw models scan` を使用） +- OpenCode: Zen向けの `opencode/...` と、Go向けの `opencode-go/...`（authは `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`） -liveマトリクスに含められるその他のプロバイダー（認証情報/設定がある場合）: +live matrixに含められるその他のプロバイダー（認証情報/configがある場合）: - 組み込み: `openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot` -- `models.providers` 経由（カスタムエンドポイント）: `minimax`（cloud/API）、および任意のOpenAI/Anthropic互換プロキシ（LM Studio、vLLM、LiteLLMなど） +- `models.providers` 経由（カスタムエンドポイント）: `minimax`（cloud/API）、およびOpenAI/Anthropic互換の任意のproxy（LM Studio、vLLM、LiteLLMなど） -ヒント: ドキュメント内で「すべてのモデル」をハードコードしようとしないでください。権威ある一覧は、あなたのマシンで `discoverModels(...)` が返すものと、利用可能なキー次第です。 +ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。権威ある一覧は、あなたのマシン上で `discoverModels(...)` が返すものと、利用可能なキーによって決まります。 ## 認証情報（絶対にコミットしない） -liveテストは、CLIと同じ方法で認証情報を検出します。実際上の意味は次のとおりです。 +liveテストは、CLIと同じ方法で認証情報を見つけます。実務上の意味は以下です。 - CLIが動くなら、liveテストも同じキーを見つけられるはずです。 -- liveテストが「認証情報なし」と言うなら、`openclaw models list` / モデル選択をデバッグするときと同じように調べてください。 +- liveテストが「認証情報なし」と言うなら、`openclaw models list` / model選択をデバッグするときと同じ方法でデバッグしてください。 -- エージェントごとの認証プロファイル: `~/.openclaw/agents//agent/auth-profiles.json`（liveテストで「profile keys」と言っているのはこれです） -- 設定: `~/.openclaw/openclaw.json`（または `OPENCLAW_CONFIG_PATH`） -- 旧stateディレクトリ: `~/.openclaw/credentials/`（存在する場合はステージされたlive homeにコピーされますが、メインのprofile-keyストアではありません） -- ローカルのlive実行では、デフォルトでアクティブ設定、エージェントごとの `auth-profiles.json`、旧 `credentials/`、およびサポートされる外部CLI認証ディレクトリを一時テストhomeへコピーします。ステージされたlive homeでは `workspace/` と `sandboxes/` はスキップされ、`agents.*.workspace` / `agentDir` パス上書きは削除されるため、プローブが実際のホストワークスペースに影響しません。 +- エージェントごとのauth profile: `~/.openclaw/agents//agent/auth-profiles.json`（liveテストで「profile keys」が意味するのはこれです） +- Config: `~/.openclaw/openclaw.json`（または `OPENCLAW_CONFIG_PATH`） +- レガシーstateディレクトリ: `~/.openclaw/credentials/`（存在する場合はステージされたlive homeにコピーされますが、メインのprofile-key storeではありません） +- ローカルのlive実行は、デフォルトでアクティブなconfig、エージェントごとの `auth-profiles.json` ファイル、レガシー `credentials/`、およびサポートされる外部CLI authディレクトリを一時的なテストhomeへコピーします。ステージされたlive homeでは `workspace/` と `sandboxes/` をスキップし、`agents.*.workspace` / `agentDir` のパス上書きも削除されるため、probeが実際のホストworkspaceに触れないようになっています。 -envキーに依存したい場合（たとえば `~/.profile` でexportしている場合）は、`source ~/.profile` の後でローカルテストを実行するか、以下のDockerランナーを使ってください（これらは `~/.profile` をコンテナへマウントできます）。 +envキー（たとえば `~/.profile` でexportしたもの）に依存したい場合は、`source ~/.profile` の後にローカルテストを実行するか、以下のDockerランナーを使ってください（これらは `~/.profile` をcontainer内にマウントできます）。 ## Deepgram live（音声文字起こし） @@ -711,277 +714,293 @@ envキーに依存したい場合（たとえば `~/.profile` でexportしてい - テスト: `src/agents/byteplus.live.test.ts` - 有効化: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- 任意のモデル上書き: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- 任意のmodel上書き: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## ComfyUI workflow media live - テスト: `extensions/comfy/comfy.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - スコープ: - - バンドル済みcomfyのimage、video、および `music_generate` 経路を検証する - - `models.providers.comfy.` が設定されていない場合は各機能をスキップする - - comfyのworkflow送信、ポーリング、ダウンロード、またはPlugin登録を変更した後に有用 + - バンドルされたcomfyのimage、video、および `music_generate` パスを実行する + - `models.providers.comfy.` が設定されていない限り、各capabilityをスキップする + - comfy workflow submission、polling、downloads、またはPlugin registrationを変更した後に有用 ## Image generation live - テスト: `src/image-generation/runtime.live.test.ts` - コマンド: `pnpm test:live src/image-generation/runtime.live.test.ts` -- ハーネス: `pnpm test:live:media image` +- Harness: `pnpm test:live:media image` - スコープ: - 登録されているすべてのimage-generation provider Pluginを列挙する - - プローブ前に、足りないprovider env変数をログインシェル（`~/.profile`）から読み込む - - デフォルトでは、保存済み認証プロファイルよりもlive/env APIキーを優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を隠しません - - 利用可能な認証/プロファイル/モデルがないプロバイダーはスキップする - - 共有ランタイム機能を通じて標準のimage-generationバリアントを実行する: + - probe前にログインshell（`~/.profile`）から不足しているprovider env varsを読み込む + - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠さない + - 使用可能なauth/profile/modelがないproviderはスキップする + - 共有runtime capabilityを通じて標準のimage-generationバリアントを実行する: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- 現在カバーされているバンドル済みプロバイダー: +- 現在カバーされているバンドルprovider: - `openai` - `google` - 任意の絞り込み: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- 任意の認証挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でプロファイルストア認証を強制し、envのみの上書きを無視する +- 任意のauth挙動: + - profile-store authを強制し、env-only上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` ## Music generation live - テスト: `extensions/music-generation-providers.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- ハーネス: `pnpm test:live:media music` +- Harness: `pnpm test:live:media music` - スコープ: - - 共有のバンドル済みmusic-generation provider経路を検証する + - 共有のバンドルされたmusic-generation providerパスを実行する - 現在はGoogleとMiniMaxをカバーする - - プローブ前に、ログインシェル（`~/.profile`）からprovider env変数を読み込む - - デフォルトでは、保存済み認証プロファイルよりもlive/env APIキーを優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を隠しません - - 利用可能な認証/プロファイル/モデルがないプロバイダーはスキップする - - 利用可能な場合、宣言された両方のランタイムモードを実行する: - - プロンプトのみ入力の `generate` - - プロバイダーが `capabilities.edit.enabled` を宣言している場合の `edit` + - probe前にログインshell（`~/.profile`）からprovider env varsを読み込む + - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠さない + - 使用可能なauth/profile/modelがないproviderはスキップする + - 利用可能な場合は、宣言された両方のruntime modeを実行する: + - promptのみ入力の `generate` + - providerが `capabilities.edit.enabled` を宣言している場合の `edit` - 現在の共有レーンカバレッジ: - `google`: `generate`、`edit` - `minimax`: `generate` - - `comfy`: 別のComfy liveファイルであり、この共有スイープではない + - `comfy`: この共有sweepではなく、別のComfy liveファイル - 任意の絞り込み: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- 任意の認証挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でプロファイルストア認証を強制し、envのみの上書きを無視する +- 任意のauth挙動: + - profile-store authを強制し、env-only上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` ## Video generation live - テスト: `extensions/video-generation-providers.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- ハーネス: `pnpm test:live:media video` +- Harness: `pnpm test:live:media video` - スコープ: - - 共有のバンドル済みvideo-generation provider経路を検証する - - デフォルトでは、リリース安全なスモーク経路を使用する: FAL以外のプロバイダー、プロバイダーごとに1件のtext-to-videoリクエスト、1秒のlobsterプロンプト、そして `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`（デフォルト `180000`）から取得されるプロバイダーごとの操作上限 - - FALは、プロバイダー側のキュー遅延がリリース時間を支配しうるため、デフォルトでスキップされます。明示的に実行するには `--video-providers fal` または `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` を渡してください - - プローブ前に、ログインシェル（`~/.profile`）からprovider env変数を読み込む - - デフォルトでは、保存済み認証プロファイルよりもlive/env APIキーを優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を隠しません - - 利用可能な認証/プロファイル/モデルがないプロバイダーはスキップする + - 共有のバンドルされたvideo-generation providerパスを実行する + - デフォルトでは、リリース安全なスモークパスを使います: FAL以外のprovider、providerごとに1回のtext-to-videoリクエスト、1秒のlobster prompt、そして `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`（デフォルト `180000`）によるproviderごとのoperation上限 + - provider側のqueue latencyがリリース時間を支配することがあるため、FALはデフォルトでスキップされます。明示的に実行するには `--video-providers fal` または `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` を渡してください + - probe前にログインshell（`~/.profile`）からprovider env varsを読み込む + - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠さない + - 使用可能なauth/profile/modelがないproviderはスキップする - デフォルトでは `generate` のみを実行する - - 利用可能な場合に宣言されたtransformモードも実行するには `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定する: - - プロバイダーが `capabilities.imageToVideo.enabled` を宣言しており、選択されたプロバイダー/モデルが共有スイープでバッファバックのローカルimage入力を受け付ける場合の `imageToVideo` - - プロバイダーが `capabilities.videoToVideo.enabled` を宣言しており、選択されたプロバイダー/モデルが共有スイープでバッファバックのローカルvideo入力を受け付ける場合の `videoToVideo` - - 現在、共有スイープで宣言はされているがスキップされる `imageToVideo` プロバイダー: - - バンドル済み `veo3` はtext専用で、バンドル済み `kling` はリモートimage URLを必要とするため、`vydra` - - プロバイダー固有のVydraカバレッジ: + - 利用可能な場合に宣言されたtransform modeも実行するには `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定: + - providerが `capabilities.imageToVideo.enabled` を宣言し、選択されたprovider/modelが共有sweep内でbuffer-backedなローカルimage入力を受け付ける場合の `imageToVideo` + - providerが `capabilities.videoToVideo.enabled` を宣言し、選択されたprovider/modelが共有sweep内でbuffer-backedなローカルvideo入力を受け付ける場合の `videoToVideo` + - 現在、共有sweepで宣言されているがスキップされる `imageToVideo` provider: + - `vydra`。バンドルされた `veo3` はtext-onlyで、バンドルされた `kling` はリモートimage URLを必要とするため + - provider固有のVydraカバレッジ: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - このファイルは `veo3` のtext-to-videoに加え、デフォルトでリモートimage URLフィクスチャを使う `kling` レーンを実行します + - このファイルは、`veo3` のtext-to-videoと、デフォルトでリモートimage URL fixtureを使う `kling` レーンを実行します - 現在の `videoToVideo` liveカバレッジ: - - 選択モデルが `runway/gen4_aleph` の場合のみ `runway` - - 現在、共有スイープで宣言はされているがスキップされる `videoToVideo` プロバイダー: - - これらの経路は現在リモートの `http(s)` / MP4参照URLを必要とするため、`alibaba`、`qwen`、`xai` - - 現在の共有Gemini/Veoレーンがローカルのバッファバック入力を使っており、その経路は共有スイープでは受け付けられないため、`google` - - 現在の共有レーンには組織固有のvideo inpaint/remixアクセス保証がないため、`openai` + - 選択されたmodelが `runway/gen4_aleph` の場合の `runway` のみ + - 現在、共有sweepで宣言されているがスキップされる `videoToVideo` provider: + - `alibaba`、`qwen`、`xai`。これらのパスは現在、リモートの `http(s)` / MP4 reference URLを必要とするため + - `google`。現在の共有Gemini/Veoレーンはローカルのbuffer-backed入力を使っており、そのパスは共有sweepでは受け付けられないため + - `openai`。現在の共有レーンではorg固有のvideo inpaint/remixアクセス保証がないため - 任意の絞り込み: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` で、FALを含むデフォルトスイープ内のすべてのプロバイダーを含める - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` で、積極的なスモーク実行向けに各プロバイダーの操作上限を短縮する -- 任意の認証挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でプロファイルストア認証を強制し、envのみの上書きを無視する + - デフォルトsweep内のFALを含むすべてのproviderを含めるには `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` + - 積極的なスモーク実行向けに各providerのoperation上限を下げるには `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` +- 任意のauth挙動: + - profile-store authを強制し、env-only上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## メディアliveハーネス +## Media live harness - コマンド: `pnpm test:live:media` - 目的: - - 共有のimage、music、videoのliveスイートを、リポジトリネイティブな1つのエントリーポイントから実行する - - `~/.profile` から不足しているprovider env変数を自動読み込みする - - デフォルトで、現在利用可能な認証を持つプロバイダーに各スイートを自動的に絞り込む - - `scripts/test-live.mjs` を再利用するため、Heartbeatとquietモードの挙動が一貫する + - 共有のimage、music、videoのliveスイートを、リポジトリネイティブな1つのentrypoint経由で実行する + - `~/.profile` から不足しているprovider env varsを自動で読み込む + - デフォルトでは、現在使用可能なauthを持つproviderに各スイートを自動で絞り込む + - `scripts/test-live.mjs` を再利用するため、Heartbeatおよびquiet-modeの挙動が一貫する - 例: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Dockerランナー（任意の「Linuxで動く」確認） +## Dockerランナー（任意の「Linuxで動く」チェック） -これらのDockerランナーは、2つのカテゴリに分かれます。 +これらのDockerランナーは、2つのバケットに分かれています: -- liveモデルランナー: `test:docker:live-models` と `test:docker:live-gateway` は、それぞれ対応するprofile-key liveファイルのみをリポジトリDockerイメージ内で実行します（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）。ローカルのconfigディレクトリとworkspaceをマウントし（マウントされていれば `~/.profile` も読み込みます）。対応するローカルエントリーポイントは `test:live:models-profiles` と `test:live:gateway-profiles` です。 -- Docker liveランナーは、完全なDockerスイープを現実的な時間で保つために、デフォルトでより小さいスモーク上限を使用します: - `test:docker:live-models` のデフォルトは `OPENCLAW_LIVE_MAX_MODELS=12`、そして - `test:docker:live-gateway` のデフォルトは `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 +- live-modelランナー: `test:docker:live-models` と `test:docker:live-gateway` は、それぞれ対応するprofile-key liveファイルのみをリポジトリDocker image内で実行します（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）。ローカルのconfigディレクトリとworkspaceをマウントし（マウントされていれば `~/.profile` もsourceします）。対応するローカルentrypointは `test:live:models-profiles` と `test:live:gateway-profiles` です。 +- Docker liveランナーは、完全なDocker sweepを現実的に保つため、デフォルトでより小さなスモーク上限を使います: + `test:docker:live-models` はデフォルトで `OPENCLAW_LIVE_MAX_MODELS=12`、 + `test:docker:live-gateway` はデフォルトで `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`、および - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` です。より大きな網羅的スキャンを明示的に行いたい場合は、これらのenv変数を上書きしてください。 -- `test:docker:all` は、まず `test:docker:live-build` でlive Dockerイメージを1回ビルドし、その後2つのlive Dockerレーンで再利用します。 -- コンテナスモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:plugins` は、1つ以上の実コンテナを起動し、より高レベルなintegration経路を検証します。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` を使います。より大きな網羅的スキャンを明示的に望む場合は、これらのenv varを上書きしてください。 +- `test:docker:all` は、まず `test:docker:live-build` 経由でlive Docker imageを1回だけbuildし、その後2つのlive Dockerレーンで再利用します。 +- containerスモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:plugins` は、1つ以上の実コンテナを起動し、より高レベルなintegration pathを検証します。 -liveモデルDockerランナーは、必要なCLI認証homeのみ（または実行が絞り込まれていない場合はサポートされるすべて）をbind-mountし、その後、外部CLI OAuthがホストの認証ストアを変更せずにトークンを更新できるよう、実行前にそれらをコンテナhomeへコピーします。 +live-model Dockerランナーは、必要なCLI auth homeのみ（または実行が絞り込まれていない場合はサポートされるものすべて）をbind-mountし、その後実行前にcontainer homeへコピーします。これにより、外部CLI OAuthがホストのauth storeを変更せずにトークンを更新できます。 -- 直接モデル: `pnpm test:docker:live-models`（スクリプト: `scripts/test-live-models-docker.sh`） +- Direct models: `pnpm test:docker:live-models`（スクリプト: `scripts/test-live-models-docker.sh`） - ACP bindスモーク: `pnpm test:docker:live-acp-bind`（スクリプト: `scripts/test-live-acp-bind-docker.sh`） -- CLIバックエンドスモーク: `pnpm test:docker:live-cli-backend`（スクリプト: `scripts/test-live-cli-backend-docker.sh`） -- Codex app-serverハーネススモーク: `pnpm test:docker:live-codex-harness`（スクリプト: `scripts/test-live-codex-harness-docker.sh`） +- CLI backendスモーク: `pnpm test:docker:live-cli-backend`（スクリプト: `scripts/test-live-cli-backend-docker.sh`） +- Codex app-server harnessスモーク: `pnpm test:docker:live-codex-harness`（スクリプト: `scripts/test-live-codex-harness-docker.sh`） - Gateway + devエージェント: `pnpm test:docker:live-gateway`（スクリプト: `scripts/test-live-gateway-models-docker.sh`） - Open WebUI liveスモーク: `pnpm test:docker:openwebui`（スクリプト: `scripts/e2e/openwebui-docker.sh`） -- オンボーディングウィザード（TTY、完全なscaffolding）: `pnpm test:docker:onboard`（スクリプト: `scripts/e2e/onboard-docker.sh`） -- Gatewayネットワーキング（2コンテナ、WS認証 + health）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） -- MCPチャネルブリッジ（seed済みGateway + stdioブリッジ + 生のClaude通知フレームスモーク）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） -- Plugins（インストールスモーク + `/plugin` エイリアス + Claudeバンドル再起動セマンティクス）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） +- オンボーディング ウィザード（TTY、完全なscaffolding）: `pnpm test:docker:onboard`（スクリプト: `scripts/e2e/onboard-docker.sh`） +- Gatewayネットワーキング（2つのcontainer、WS auth + health）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） +- MCP channel bridge（seed済みGateway + stdio bridge + 生のClaude notification-frameスモーク）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） +- Plugins（installスモーク + `/plugin` エイリアス + Claude-bundle restart semantics）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） -liveモデルDockerランナーは、現在のcheckoutも読み取り専用でbind-mountし、コンテナ内の一時workdirへステージします。これにより、ランタイムイメージをスリムに保ちながら、正確にあなたのローカルソース/設定に対してVitestを実行できます。 -このステージング手順では、`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの `.build` やGradle出力ディレクトリのような、大きなローカル専用キャッシュやアプリビルド出力をスキップするため、Docker live実行でマシン固有のアーティファクトのコピーに何分も費やすことがありません。 -また、コンテナ内で実際のTelegram/DiscordなどのチャネルワーカーをGateway liveプローブが起動しないように、`OPENCLAW_SKIP_CHANNELS=1` も設定します。 -`test:docker:live-models` は依然として `pnpm test:live` を実行するため、そのDockerレーンからGateway liveカバレッジを絞り込んだり除外したりしたい場合は、`OPENCLAW_LIVE_GATEWAY_*` も渡してください。 -`test:docker:openwebui` は、より高レベルな互換性スモークです。OpenAI互換HTTPエンドポイントを有効にしたOpenClaw Gatewayコンテナを起動し、そのGatewayに向けた固定版のOpen WebUIコンテナを起動し、Open WebUI経由でサインインし、`/api/models` が `openclaw/default` を公開していることを確認したうえで、Open WebUIの `/api/chat/completions` プロキシ経由で実際のチャットリクエストを送信します。 -初回実行は、DockerがOpen WebUIイメージをpullする必要があったり、Open WebUI自身のコールドスタートセットアップを完了する必要があるため、目に見えて遅くなることがあります。 -このレーンは使用可能なliveモデルキーを前提としており、Docker化された実行でそれを提供する主な方法は `OPENCLAW_PROFILE_FILE` -（デフォルトは `~/.profile`）です。 +live-model Dockerランナーは、現在のcheckoutも読み取り専用でbind-mountし、container内の一時workdirへステージします。これにより、runtime +imageをスリムに保ちながら、正確にあなたのローカルsource/configに対してVitestを実行できます。 +ステージング手順では、大きなローカル専用キャッシュやアプリbuild出力、たとえば +`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの `.build` や +Gradle出力ディレクトリをスキップするため、Docker live実行がマシン固有artifactのコピーに何分も費やすことはありません。 +また、container内で実際のTelegram/Discordなどのchannel workerを起動しないよう、 +`OPENCLAW_SKIP_CHANNELS=1` も設定します。 +`test:docker:live-models` は依然として `pnpm test:live` を実行するため、 +そのDockerレーンからGateway liveカバレッジを絞り込んだり除外したりする必要がある場合は、 +`OPENCLAW_LIVE_GATEWAY_*` も渡してください。 +`test:docker:openwebui` は、より高レベルな互換性スモークです。これは +OpenAI互換HTTPエンドポイントを有効にしたOpenClaw Gateway containerを起動し、 +そのGatewayに対して固定版のOpen WebUI containerを起動し、Open WebUI経由でサインインし、 +`/api/models` が `openclaw/default` を公開していることを検証し、その後 +Open WebUIの `/api/chat/completions` proxy経由で実際のchatリクエストを送信します。 +初回実行は、Dockerが +Open WebUI imageをpullする必要があったり、Open WebUI自身のcold-start setupを完了する必要があったりするため、目立って遅いことがあります。 +このレーンは使用可能なlive model keyを必要とし、Docker化された実行でそれを提供する主な方法は +`OPENCLAW_PROFILE_FILE`（デフォルトは `~/.profile`）です。 成功した実行では、`{ "ok": true, "model": -"openclaw/default", ... }` のような小さなJSONペイロードが出力されます。 -`test:docker:mcp-channels` は意図的に決定論的であり、実際のTelegram、Discord、またはiMessageアカウントは必要ありません。seed済みGateway -コンテナを起動し、`openclaw mcp serve` を起動する2つ目のコンテナを開始し、その後、実際のstdio MCPブリッジ上で、ルーティングされた会話検出、トランスクリプト読み取り、添付メタデータ、liveイベントキュー挙動、送信ルーティング、そしてClaude風のチャネル + -権限通知を検証します。通知チェックでは、生のstdio MCPフレームを直接検査するため、このスモークは、特定のクライアントSDKがたまたま表面化するものではなく、ブリッジが実際に出力するものを検証します。 +"openclaw/default", ... }` のような小さなJSON payloadが出力されます。 +`test:docker:mcp-channels` は意図的に決定論的であり、 +実際のTelegram、Discord、またはiMessageアカウントを必要としません。これはseed済みGateway +containerを起動し、`openclaw mcp serve` を起動する2つ目のcontainerを立ち上げ、その後 +ルーティングされたconversation discovery、transcript読み取り、attachment metadata、 +live event queue挙動、outbound送信ルーティング、およびClaude風のchannel + +permission通知を、実際のstdio MCP bridge上で検証します。通知チェックは +生のstdio MCP frameを直接検査するため、このスモークは特定のclient SDKがたまたまsurfaceするものではなく、 +bridgeが実際に発行するものを検証します。 -手動ACP平文スレッドスモーク（CIではない）: +手動ACP平文threadスモーク（CIではない）: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- このスクリプトはリグレッション/デバッグワークフロー用に維持してください。ACPスレッドルーティング検証で再び必要になる可能性があるため、削除しないでください。 +- このスクリプトはリグレッション/デバッグワークフロー用に維持してください。ACP thread routing検証のために再び必要になる可能性があるので、削除しないでください。 -便利なenv変数: +便利なenv var: - `OPENCLAW_CONFIG_DIR=...`（デフォルト: `~/.openclaw`）を `/home/node/.openclaw` にマウント - `OPENCLAW_WORKSPACE_DIR=...`（デフォルト: `~/.openclaw/workspace`）を `/home/node/.openclaw/workspace` にマウント -- `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`）を `/home/node/.profile` にマウントし、テスト実行前に読み込む -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` で、`OPENCLAW_PROFILE_FILE` から読み込まれたenv変数のみを検証し、一時的なconfig/workspaceディレクトリを使い、外部CLI認証マウントは使わない -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）を `/home/node/.npm-global` にマウントし、Docker内のCLIインストールキャッシュとして使う -- `$HOME` 配下の外部CLI認証ディレクトリ/ファイルは、`/host-auth...` 配下に読み取り専用でマウントされ、テスト開始前に `/home/node/...` へコピーされます +- `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`）を `/home/node/.profile` にマウントし、テスト実行前にsource +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` で、`OPENCLAW_PROFILE_FILE` からsourceしたenv varのみを検証し、一時的なconfig/workspaceディレクトリを使い、外部CLI authマウントは行わない +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）を `/home/node/.npm-global` にマウントし、Docker内のCLI installをキャッシュ +- `$HOME` 配下の外部CLI authディレクトリ/ファイルは、読み取り専用で `/host-auth...` 配下にマウントされ、その後テスト開始前に `/home/node/...` へコピーされる - デフォルトディレクトリ: `.minimax` - デフォルトファイル: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 絞り込まれたプロバイダー実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推測された必要なディレクトリ/ファイルのみをマウントします - - 手動で上書きするには `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストを使用します -- 実行を絞り込むには `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` -- コンテナ内でプロバイダーを絞り込むには `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` -- リビルド不要の再実行で既存の `openclaw:local-live` イメージを再利用するには `OPENCLAW_SKIP_DOCKER_BUILD=1` -- 認証情報がenvではなくプロファイルストアから来ることを保証するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -- Open WebUIスモークでGatewayが公開するモデルを選ぶには `OPENCLAW_OPENWEBUI_MODEL=...` -- Open WebUIスモークで使うnonce確認プロンプトを上書きするには `OPENCLAW_OPENWEBUI_PROMPT=...` -- 固定されたOpen WebUIイメージタグを上書きするには `OPENWEBUI_IMAGE=...` + - 絞り込まれたprovider実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推定された必要なディレクトリ/ファイルのみをマウントする + - 手動上書きは `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリスト +- 実行を絞り込む `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` +- container内でproviderをフィルタする `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` +- build不要の再実行で既存の `openclaw:local-live` imageを再利用する `OPENCLAW_SKIP_DOCKER_BUILD=1` +- 認証情報がprofile store由来であることを保証する `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`（envではない） +- Open WebUIスモークでGatewayが公開するmodelを選ぶ `OPENCLAW_OPENWEBUI_MODEL=...` +- Open WebUIスモークで使うnonceチェックpromptを上書きする `OPENCLAW_OPENWEBUI_PROMPT=...` +- 固定されたOpen WebUI image tagを上書きする `OPENWEBUI_IMAGE=...` -## ドキュメント健全性チェック +## Docsの健全性確認 -ドキュメントを編集した後は、ドキュメントチェックを実行してください: `pnpm check:docs`。 -ページ内見出しチェックも必要な場合は、完全なMintlifyアンカー検証を実行してください: `pnpm docs:check-links:anchors`。 +ドキュメント編集後はdocsチェックを実行してください: `pnpm check:docs`。 +ページ内見出しチェックも必要な場合は、完全なMintlify anchor検証を実行してください: `pnpm docs:check-links:anchors`。 -## オフラインリグレッション（CI安全） +## Offlineリグレッション（CI-safe） -これらは、実際のプロバイダーを使わない「実パイプライン」リグレッションです。 +これらは、実プロバイダーなしでの「実際のパイプライン」リグレッションです。 -- Gatewayツール呼び出し（OpenAIをモック、実際のGateway + エージェントループ）: `src/gateway/gateway.test.ts`（ケース: 「モックOpenAIツール呼び出しをGatewayエージェントループ経由でエンドツーエンド実行する」） -- Gatewayウィザード（WS `wizard.start`/`wizard.next`、設定 + 認証の強制書き込み）: `src/gateway/gateway.test.ts`（ケース: 「WS経由でウィザードを実行し、auth token設定を書き込む」） +- Gateway tool calling（mock OpenAI、実際のGateway + エージェントループ）: `src/gateway/gateway.test.ts`（ケース: 「runs a mock OpenAI tool call end-to-end via gateway agent loop」） +- Gatewayウィザード（WS `wizard.start`/`wizard.next`、config + auth enforcedを書き込む）: `src/gateway/gateway.test.ts`（ケース: 「runs wizard over ws and writes auth token config」） -## エージェント信頼性評価（Skills） +## エージェント信頼性eval（Skills） -すでにいくつかのCI安全なテストがあり、「エージェント信頼性評価」のように振る舞います。 +すでに、いくつかのCI-safeな、いわば「エージェント信頼性eval」のようなテストがあります。 -- 実際のGateway + エージェントループを通したモックツール呼び出し（`src/gateway/gateway.test.ts`）。 -- セッション配線と設定効果を検証するエンドツーエンドのウィザードフロー（`src/gateway/gateway.test.ts`）。 +- 実際のGateway + エージェントループを通じたmock tool-calling（`src/gateway/gateway.test.ts`）。 +- session配線とconfig効果を検証するend-to-endのウィザードフロー（`src/gateway/gateway.test.ts`）。 -Skillsに関してまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: +Skillsについてまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: -- **判断**: Skillsがプロンプトに列挙されたとき、エージェントは正しいSkillを選ぶか（または無関係なものを避けるか）？ -- **準拠**: エージェントは使用前に `SKILL.md` を読み、必要な手順/引数に従うか？ -- **ワークフロー契約**: ツール順序、セッション履歴の持ち越し、sandbox境界を検証するマルチターンシナリオ。 +- **意思決定:** prompt内にSkillsが列挙されているとき、エージェントは正しいskillを選ぶか（または無関係なものを避けるか）？ +- **準拠:** エージェントは使用前に `SKILL.md` を読み、必須の手順/引数に従うか？ +- **ワークフロー契約:** tool順序、session historyの引き継ぎ、sandbox boundaryを検証する複数ターンのシナリオ。 -将来の評価は、まず決定論的であるべきです。 +今後のevalは、まず決定論的であるべきです。 -- ツール呼び出し + 順序、Skillファイル読み取り、セッション配線を検証するために、モックプロバイダーを使うシナリオランナー。 -- Skillに焦点を当てた小さなシナリオスイート（使う vs 使わない、ゲーティング、プロンプトインジェクション）。 -- オプトインかつenvでゲートされた任意のlive評価は、CI安全スイートが整ってからにする。 +- mock providerを使ってtool call + 順序、skillファイル読み取り、session配線を検証するscenario runner。 +- skillに焦点を当てた小規模なシナリオスイート（使う/使わない、ゲーティング、prompt injection）。 +- CI-safeスイートが整ってからの、任意のlive eval（オプトイン、env gate付き）のみ。 -## 契約テスト（Pluginおよびチャネル形状） +## Contractテスト（Pluginおよびchannel shape） -契約テストは、登録されたすべてのPluginとチャネルがその -インターフェース契約に準拠していることを検証します。見つかったすべてのPluginを反復し、 -形状と挙動に関する一連の検証を実行します。デフォルトの `pnpm test` unitレーンは意図的に -これらの共有境界およびスモークファイルをスキップするため、共有チャネルまたはproviderサーフェスに触れた場合は、 -契約コマンドを明示的に実行してください。 +Contractテストは、登録されているすべてのPluginとchannelが +そのinterface contractに準拠していることを検証します。検出されたすべてのPluginを反復し、 +shapeと挙動の検証スイートを実行します。デフォルトの `pnpm test` unitレーンは意図的に +これらの共有seamおよびスモークファイルをスキップするため、共有channelまたはprovider surfaceに触れたときは +Contractコマンドを明示的に実行してください。 ### コマンド -- すべての契約: `pnpm test:contracts` -- チャネル契約のみ: `pnpm test:contracts:channels` -- provider契約のみ: `pnpm test:contracts:plugins` +- すべてのcontract: `pnpm test:contracts` +- channel contractのみ: `pnpm test:contracts:channels` +- provider contractのみ: `pnpm test:contracts:plugins` -### チャネル契約 +### channel contract `src/channels/plugins/contracts/*.contract.test.ts` にあります: -- **plugin** - 基本的なPlugin形状（id、name、capabilities） -- **setup** - セットアップウィザード契約 -- **session-binding** - セッションbind挙動 -- **outbound-payload** - メッセージペイロード構造 -- **inbound** - 受信メッセージ処理 -- **actions** - チャネルアクションハンドラー -- **threading** - スレッドID処理 -- **directory** - ディレクトリ/ロスターAPI -- **group-policy** - グループポリシーの強制 +- **plugin** - 基本的なPlugin shape（id、name、capabilities） +- **setup** - セットアップ ウィザード契約 +- **session-binding** - Session bindingの挙動 +- **outbound-payload** - メッセージpayload構造 +- **inbound** - inboundメッセージ処理 +- **actions** - channel action handler +- **threading** - thread ID処理 +- **directory** - directory/roster API +- **group-policy** - グループポリシーの適用 -### provider status契約 +### provider status contract `src/plugins/contracts/*.contract.test.ts` にあります。 -- **status** - チャネルstatusプローブ -- **registry** - Pluginレジストリ形状 +- **status** - channel status probe +- **registry** - Plugin registry shape -### provider契約 +### provider contract `src/plugins/contracts/*.contract.test.ts` にあります: -- **auth** - 認証フロー契約 -- **auth-choice** - 認証選択/選定 -- **catalog** - モデルcatalog API -- **discovery** - Plugin検出 -- **loader** - Plugin読み込み -- **runtime** - providerランタイム -- **shape** - Plugin形状/インターフェース -- **wizard** - セットアップウィザード +- **auth** - authフロー契約 +- **auth-choice** - authの選択/選定 +- **catalog** - model catalog API +- **discovery** - Plugin discovery +- **loader** - Plugin loading +- **runtime** - provider runtime +- **shape** - Plugin shape/interface +- **wizard** - セットアップ ウィザード ### 実行するタイミング -- plugin-sdkのエクスポートまたはsubpathを変更した後 -- チャネルまたはprovider Pluginを追加または変更した後 -- Plugin登録または検出をリファクタリングした後 +- plugin-sdkのexportまたはsubpathを変更した後 +- channelまたはprovider Pluginを追加または変更した後 +- Plugin registrationまたはdiscoveryをリファクタリングした後 -契約テストはCIで実行され、実際のAPIキーは必要ありません。 +ContractテストはCIで実行され、実際のAPIキーは不要です。 -## リグレッションの追加（ガイダンス） +## リグレッションを追加する（ガイダンス） -liveで見つかったprovider/modelの問題を修正したときは: +liveで見つかったprovider/modelの問題を修正するとき: -- 可能ならCI安全なリグレッションを追加する（providerをモック/スタブするか、正確なリクエスト形状変換をキャプチャする） -- 本質的にlive専用である場合（レート制限、認証ポリシーなど）は、liveテストを狭く保ち、env変数経由のオプトインにする -- バグを捕捉する最小のレイヤーを狙う: - - providerのリクエスト変換/replayバグ → 直接モデルテスト - - Gatewayセッション/履歴/ツールパイプラインのバグ → Gateway liveスモークまたはCI安全なGatewayモックテスト -- SecretRef走査ガードレール: - - `src/secrets/exec-secret-ref-id-parity.test.ts` は、レジストリメタデータ（`listSecretTargetRegistryEntries()`）からSecretRefクラスごとに1つのサンプル対象を導出し、その後、走査セグメントのexec idが拒否されることを検証します。 - - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef対象ファミリーを追加した場合は、そのテスト内の `classifyTargetClass` を更新してください。このテストは、未分類のtarget idに対して意図的に失敗するため、新しいクラスが黙ってスキップされることはありません。 +- 可能であればCI-safeなリグレッションを追加してください（providerのmock/stub、または正確なrequest-shape変換のキャプチャ） +- 本質的にlive-onlyな場合（rate limit、authポリシー）は、liveテストを狭く保ち、env var経由のオプトインにしてください +- バグを捕捉できる最小のレイヤーを狙うことを優先してください: + - provider request conversion/replayバグ → direct modelsテスト + - Gateway session/history/tool pipelineバグ → Gateway liveスモークまたはCI-safeなGateway mockテスト +- SecretRef traversal guardrail: + - `src/secrets/exec-secret-ref-id-parity.test.ts` は、registry metadata（`listSecretTargetRegistryEntries()`）からSecretRef classごとに1つのサンプルtargetを導出し、その後、traversal-segment exec idが拒否されることを検証します。 + - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef target familyを追加する場合は、そのテスト内の `classifyTargetClass` を更新してください。このテストは、未分類のtarget idに対して意図的に失敗するため、新しいclassが黙ってスキップされることはありません。 diff --git a/docs/ja-JP/plugins/sdk-migration.md b/docs/ja-JP/plugins/sdk-migration.md index f4c920919..fb17829ce 100644 --- a/docs/ja-JP/plugins/sdk-migration.md +++ b/docs/ja-JP/plugins/sdk-migration.md @@ -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も次のメジャーリリースで削除される前に移行する必要があります。 - この後方互換レイヤーは、将来のmajor releaseで削除されます。 - これらのsurfaceからまだimportしているpluginは、その時点で動作しなくなります。 + 後方互換レイヤーは将来のメジャーリリースで削除されます。これらの公開面からまだインポートしているpluginは、その時点で動作しなくなります。 -## なぜ変わったのか +## なぜ変更されたのか -古いアプローチはいくつかの問題を引き起こしていました。 +古いアプローチには問題がありました。 -- **起動が遅い** — 1つのhelperをimportするだけで、無関係なmoduleが数十個読み込まれていた -- **循環依存** — 広範な再エクスポートにより、import cycleが簡単に生まれていた -- **API surfaceが不明確** — どのexportが安定していて、どれが内部用なのか判別できなかった +- **起動が遅い** — 1つのヘルパーをインポートすると、無関係な数十個のモジュールまで読み込まれていました +- **循環依存** — 幅広い再エクスポートによって、インポートサイクルが簡単に発生していました +- **不明確なAPI公開面** — どのエクスポートが安定していて、どれが内部用なのかを判別する方法がありませんでした -モダンなPlugin SDKはこれを改善します。各import path（`openclaw/plugin-sdk/\`） -は、目的が明確で契約が文書化された、小さく自己完結したmoduleです。 +最新のPlugin SDKはこれを解決します。各インポートパス（`openclaw/plugin-sdk/\`）は、明確な目的と文書化された契約を持つ、小さく自己完結したモジュールです。 -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` に保持しています ## 移行方法 - - approval対応channel pluginは、現在ではnative approval動作を - `approvalCapability.nativeRuntime` と共有runtime-context registry経由で公開します。 + + 承認対応の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` を参照してください。 - - pluginが `openclaw/plugin-sdk/windows-spawn` を使用している場合、 - 解決できないWindows `.cmd`/`.bat` wrapperは、明示的に - `allowShellFallback: true` を渡さない限り、現在はfail closedします。 + + あなたの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` を設定せず、代わりにスローされるエラーを処理してください。 - - plugin内で、いずれかの非推奨surfaceからimportしている箇所を検索します。 + + あなたのplugin内で、いずれかの非推奨公開面からのインポートを検索してください。 ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -133,37 +100,37 @@ plugin workspace内では、provider所有のhelperはそのplugin自身の - - 古いsurfaceの各exportは、対応するモダンなimport pathにマッピングされています。 + + 古い公開面からの各エクスポートは、特定の最新インポートパスに対応しています。 ```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.*` | - + ```bash pnpm build pnpm test -- my-plugin/ @@ -183,212 +150,194 @@ plugin workspace内では、provider所有のhelperはそのplugin自身の -## Import pathリファレンス +## インポートパスリファレンス - - | Import path | 用途 | 主なexport | + + | 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` | テストユーティリティ | テストヘルパーとモック | -この表は、完全な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) — マニフェストスキーマリファレンス diff --git a/docs/ja-JP/plugins/sdk-overview.md b/docs/ja-JP/plugins/sdk-overview.md index 88f868da1..679d7343d 100644 --- a/docs/ja-JP/plugins/sdk-overview.md +++ b/docs/ja-JP/plugins/sdk-overview.md @@ -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の間にある型付きコントラクトです。このページは、**何をインポートするか**と**何を登録できるか**のリファレンスです。 - **ハウツーガイドを探していますか？** - - 最初の 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)を参照してください ## インポート規約 @@ -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` | - - | サブパス | 主なエクスポート | + + | 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 | - - | サブパス | 主なエクスポート | + + | 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 | - - | サブパス | 主なエクスポート | + + | 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 | - - | サブパス | 主なエクスポート | + + | 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` | - - | サブパス | 主なエクスポート | + + | 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` | - | サブパス | 主なエクスポート | + | 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 | - - | ファミリー | 現在のサブパス | 想定される用途 | + + | 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します | -## 登録 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.` と同じ shape を使います。 -- ユーザー設定が引き続き優先されます。OpenClaw は CLI 実行前に `agents.defaults.cliBackends.` を - plugin デフォルトの上にマージします。 -- マージ後に互換性のための書き換えが必要なバックエンドでは、 - `normalizeConfig` を使用してください - （たとえば古い flag shape の正規化など）。 +- backendの`id`は、`codex-cli/gpt-5`のようなmodel ref内のprovider prefixになります。 +- backendの`config`は、`agents.defaults.cliBackends.`と同じ形を使います。 +- ユーザーconfigが引き続き優先されます。OpenClawは、CLIを実行する前に、Plugin defaultの上に`agents.defaults.cliBackends.`をマージします。 +- マージ後に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` | `plugins.entries..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` | `plugins.entries..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（任意） ``` - 本番コード内で自分自身の plugin を `openclaw/plugin-sdk/` - 経由でインポートしてはいけません。内部インポートは `./api.ts` または - `./runtime-api.ts` を通してください。SDK パスは外部コントラクト専用です。 + 本番コードから`openclaw/plugin-sdk/`経由で自分自身のPluginを + インポートしてはいけません。内部インポートは`./api.ts`または + `./runtime-api.ts`を経由させてください。SDKパスは外部コントラクト専用です。 -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します - Extension の本番コードでも、`openclaw/plugin-sdk/` - のインポートは避けるべきです。helper が本当に共有対象であるなら、2 つの plugin を結合してしまう代わりに、 - `openclaw/plugin-sdk/speech`、`.../provider-model-shared`、または別の - capability 指向 surface のような中立な SDK サブパスに昇格させてください。 + extensionの本番コードでも、`openclaw/plugin-sdk/`の + インポートは避けるべきです。helperが本当に共有されるべきなら、 + 2つのPluginを結合させるのではなく、`openclaw/plugin-sdk/speech`、 + `.../provider-model-shared`、または別のcapability指向surfaceのような + 中立的なSDKサブパスに昇格させてください。 ## 関連 -- [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 diff --git a/docs/ja-JP/tools/thinking.md b/docs/ja-JP/tools/thinking.md index 086d652cd..f9169920f 100644 --- a/docs/ja-JP/tools/thinking.md +++ b/docs/ja-JP/tools/thinking.md @@ -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 `、`/think:`、または `/thinking `。 +- 任意の受信本文内で使えるインラインディレクティブ: `/t `、`/think:`、または `/thinking `。 - レベル（エイリアス）: `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["/"].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 エージェント）は、各ツール呼び出しを個別のメタデータ専用メッセージとして返します。利用可能な場合、` : `（パス/コマンド）の形式でプレフィックスが付きます。これらのツール要約は、各ツールの開始時にすぐ送信されます（別々のバブル）。ストリーミング 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 エージェント）は、各ツール呼び出しをそれぞれ独立したメタデータ専用メッセージとして返し、利用可能な場合は ` : `（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 ()` で、解決されたデフォルトはアクティブなセッションモデルから決まります: Anthropic/Bedrock 上の Claude 4.6 では `adaptive`、その他の推論対応モデルでは `low`、それ以外では `off` です。 -- ピッカーは provider 対応のままです: - - ほとんどの provider は `off | minimal | low | medium | high | adaptive` を表示します - - Z.AI はバイナリの `off | on` を表示します -- `/think:` も引き続き機能し、同じ保存済みセッションレベルを更新するため、チャットディレクティブとピッカーは同期されたままです。 +- Web チャットの thinking セレクターは、ページ読み込み時に受信セッションストア／設定に保存されているセッションレベルを反映します。 +- 別のレベルを選ぶと、`sessions.patch` を通じてセッションオーバーライドが即座に書き込まれます。次の送信までは待たず、1 回限りの `thinkingOnce` オーバーライドでもありません。 +- 最初のオプションは常に `Default ()` で、この解決済みデフォルトはアクティブなセッションモデルから決まります: 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:` も引き続き動作し、同じ保存済みセッションレベルを更新するため、チャットディレクティブとピッカーは同期されたままになります。