diff --git a/docs/ja-JP/channels/matrix.md b/docs/ja-JP/channels/matrix.md index aeb0c255f..8ebf7fc3f 100644 --- a/docs/ja-JP/channels/matrix.md +++ b/docs/ja-JP/channels/matrix.md @@ -1,27 +1,27 @@ --- read_when: - - OpenClawでMatrixをセットアップする - - MatrixのE2EEと検証を設定する + - OpenClawでのMatrixのセットアップ + - MatrixのE2EEと検証の設定 summary: Matrixのサポート状況、セットアップ、設定例 title: Matrix x-i18n: - generated_at: "2026-04-09T01:30:27Z" + generated_at: "2026-04-15T04:43:33Z" model: gpt-5.4 provider: openai - source_hash: 28fc13c7620c1152200315ae69c94205da6de3180c53c814dd8ce03b5cb1758f + source_hash: 631f6fdcfebc23136c1a66b04851a25c047535d13cceba5650b8b421bc3afcf8 source_path: channels/matrix.md workflow: 15 --- # Matrix -MatrixはOpenClawに同梱されたチャネルプラグインです。 +MatrixはOpenClawのバンドル済みチャネルPluginです。 公式の`matrix-js-sdk`を使用し、DM、ルーム、スレッド、メディア、リアクション、投票、位置情報、E2EEをサポートします。 -## 同梱プラグイン +## バンドル済みPlugin -Matrixは現在のOpenClawリリースでは同梱プラグインとして提供されるため、通常の -パッケージ版ビルドでは別途インストールは不要です。 +Matrixは現在のOpenClawリリースではバンドル済みPluginとして提供されるため、通常の +パッケージ済みビルドでは別途インストールは不要です。 古いビルドまたはMatrixを含まないカスタムインストールを使用している場合は、 手動でインストールしてください。 @@ -38,57 +38,57 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./path/to/local/matrix-plugin ``` -プラグインの動作とインストールルールについては、[Plugins](/ja-JP/tools/plugin)を参照してください。 +Pluginの動作とインストールルールについては、[Plugins](/ja-JP/tools/plugin)を参照してください。 ## セットアップ -1. Matrixプラグインが利用可能であることを確認します。 - - 現在のパッケージ版OpenClawリリースには、すでに同梱されています。 +1. Matrix Pluginが利用可能であることを確認します。 + - 現在のパッケージ済みOpenClawリリースにはすでにバンドルされています。 - 古いインストールやカスタムインストールでは、上記のコマンドで手動追加できます。 -2. ご利用のhomeserverでMatrixアカウントを作成します。 -3. 次のいずれかで`channels.matrix`を設定します。 +2. homeserverでMatrixアカウントを作成します。 +3. `channels.matrix`を次のいずれかで設定します: - `homeserver` + `accessToken`、または - `homeserver` + `userId` + `password`。 4. Gatewayを再起動します。 5. ボットとのDMを開始するか、ルームに招待します。 - - 新しいMatrix招待は、`channels.matrix.autoJoin`で許可されている場合にのみ機能します。 + - 新規のMatrix招待は、`channels.matrix.autoJoin`で許可されている場合にのみ機能します。 -対話型セットアップの手順: +対話型セットアップのパス: ```bash openclaw channels add openclaw configure --section channels ``` -Matrixウィザードで尋ねられる内容: +Matrixウィザードが尋ねる項目: - homeserver URL -- 認証方式: access tokenまたはpassword -- user ID（password認証時のみ） +- 認証方法: access token または password +- ユーザーID（password認証のみ） - 任意のデバイス名 -- E2EEを有効にするかどうか -- ルームアクセスと招待の自動参加を設定するかどうか +- E2EEを有効にするか +- ルームアクセスと招待自動参加を設定するか ウィザードの主な動作: -- Matrix認証用の環境変数がすでに存在し、そのアカウントの認証情報がまだconfigに保存されていない場合、ウィザードは認証情報を環境変数に保持するための環境変数ショートカットを提案します。 +- Matrix認証env varがすでに存在し、そのアカウントの認証情報がまだconfigに保存されていない場合、ウィザードは認証をenv varに保持するためのenvショートカットを提示します。 - アカウント名はアカウントIDに正規化されます。たとえば、`Ops Bot`は`ops-bot`になります。 -- DMの許可リスト項目には`@user:server`を直接指定できます。表示名は、ライブディレクトリ検索で厳密に1件一致した場合にのみ機能します。 -- ルーム許可リスト項目にはルームIDとエイリアスを直接指定できます。`!room:server`または`#alias:server`を推奨します。未解決の名前は、許可リスト解決時にランタイムで無視されます。 -- 招待の自動参加を許可リストモードで使う場合は、安定した招待対象のみを使用してください: `!roomId:server`、`#alias:server`、または`*`。通常のルーム名は拒否されます。 +- DM allowlistエントリは`@user:server`をそのまま受け付けます。表示名は、ライブディレクトリ検索で完全一致が1件見つかった場合にのみ機能します。 +- ルームallowlistエントリは、ルームIDとエイリアスをそのまま受け付けます。`!room:server`または`#alias:server`を推奨します。未解決の名前はallowlist解決時に実行時に無視されます。 +- 招待自動参加のallowlistモードでは、安定した招待対象のみを使用してください: `!roomId:server`、`#alias:server`、または`*`。通常のルーム名は拒否されます。 - 保存前にルーム名を解決するには、`openclaw channels resolve --channel matrix "Project Room"`を使用します。 `channels.matrix.autoJoin`のデフォルトは`off`です。 -未設定のままにすると、ボットは招待されたルームや新しいDM形式の招待に参加しないため、手動で先に参加しない限り、新しいグループや招待DMには表示されません。 +未設定のままにすると、ボットは招待されたルームや新しいDM形式の招待に参加しないため、手動で先に参加しない限り、新しいグループや招待されたDMには表示されません。 -受け入れる招待を制限したい場合は、`autoJoin: "allowlist"`を`autoJoinAllowlist`と組み合わせて設定するか、すべての招待に参加させたい場合は`autoJoin: "always"`を設定してください。 +受け入れる招待を制限したい場合は、`autoJoin: "allowlist"`と`autoJoinAllowlist`を一緒に設定するか、すべての招待に参加させたい場合は`autoJoin: "always"`を設定してください。 -`allowlist`モードでは、`autoJoinAllowlist`には`!roomId:server`、`#alias:server`、または`*`のみ指定できます。 +`allowlist`モードでは、`autoJoinAllowlist`は`!roomId:server`、`#alias:server`、または`*`のみ受け付けます。 -許可リストの例: +allowlistの例: ```json5 { @@ -118,7 +118,7 @@ Matrixウィザードで尋ねられる内容: } ``` -最小構成のトークンベース設定: +最小構成のトークンベースセットアップ: ```json5 { @@ -133,7 +133,7 @@ Matrixウィザードで尋ねられる内容: } ``` -パスワードベース設定（ログイン後にトークンをキャッシュ）: +パスワードベースのセットアップ（ログイン後にトークンがキャッシュされます）: ```json5 { @@ -151,9 +151,9 @@ Matrixウィザードで尋ねられる内容: Matrixはキャッシュ済み認証情報を`~/.openclaw/credentials/matrix/`に保存します。 デフォルトアカウントは`credentials.json`を使用し、名前付きアカウントは`credentials-.json`を使用します。 -そこにキャッシュ済み認証情報が存在する場合、現在の認証情報がconfigに直接設定されていなくても、OpenClawはセットアップ、doctor、チャネル状態の検出でMatrixを設定済みとして扱います。 +そこにキャッシュ済み認証情報が存在する場合、現在の認証がconfigに直接設定されていなくても、OpenClawはセットアップ、doctor、チャネルステータス検出においてMatrixを設定済みとして扱います。 -環境変数の対応関係（configキーが設定されていない場合に使用）: +環境変数の対応（configキーが設定されていない場合に使用されます）: - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -162,7 +162,7 @@ Matrixはキャッシュ済み認証情報を`~/.openclaw/credentials/matrix/` - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -デフォルト以外のアカウントでは、アカウント単位の環境変数を使用します: +デフォルト以外のアカウントでは、アカウントスコープ付きenv varを使用します: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -181,14 +181,14 @@ Matrixはキャッシュ済み認証情報を`~/.openclaw/credentials/matrix/` - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -MatrixはアカウントID内の句読点をエスケープして、アカウント単位の環境変数が衝突しないようにします。 -たとえば、`-`は`_X2D_`になるため、`ops-prod`は`MATRIX_OPS_X2D_PROD_*`に対応します。 +MatrixはアカウントID内の句読点をエスケープして、スコープ付きenv varの衝突を防ぎます。 +たとえば、`-`は`_X2D_`になるため、`ops-prod`は`MATRIX_OPS_X2D_PROD_*`にマップされます。 -対話型ウィザードが環境変数ショートカットを提案するのは、それらの認証環境変数がすでに存在し、かつ選択したアカウントのMatrix認証情報がまだconfigに保存されていない場合のみです。 +対話型ウィザードがenv-varショートカットを提示するのは、それらの認証env varがすでに存在し、選択したアカウントにMatrix認証がまだconfigへ保存されていない場合のみです。 ## 設定例 -これは、DMペアリング、ルーム許可リスト、E2EE有効化を含む実用的なベースライン設定です: +これは、DM pairing、ルームallowlist、E2EE有効化を含む実用的なベースライン設定です: ```json5 { @@ -223,15 +223,15 @@ MatrixはアカウントID内の句読点をエスケープして、アカウン } ``` -`autoJoin`はDM形式の招待を含むすべてのMatrix招待に適用されます。OpenClawは招待時点で -招待されたルームをDMかグループかに確実に分類できないため、すべての招待は最初に`autoJoin`を通ります。 -`dm.policy`は、ボットが参加してルームがDMとして分類された後に適用されます。 +`autoJoin`はDM形式の招待を含むすべてのMatrix招待に適用されます。OpenClawは招待時点では +招待されたルームをDMかグループかとして確実に分類できないため、すべての招待は最初に`autoJoin`を通過します。 +`dm.policy`は、ボットが参加し、そのルームがDMとして分類された後に適用されます。 ## ストリーミングプレビュー Matrixの返信ストリーミングはオプトインです。 -OpenClawに単一のライブプレビュー返信を送信させ、モデルがテキスト生成中にそのプレビューをその場で編集し、 +OpenClawに単一のライブプレビュー返信を送信させ、モデルのテキスト生成中にそのプレビューをその場で編集し、 返信完了時に確定させたい場合は、`channels.matrix.streaming`を`"partial"`に設定します: ```json5 @@ -244,36 +244,36 @@ OpenClawに単一のライブプレビュー返信を送信させ、モデルが } ``` -- `streaming: "off"`がデフォルトです。OpenClawは最終返信を待ってから一度だけ送信します。 -- `streaming: "partial"`は、現在のassistantブロック用に編集可能な単一のプレビューメッセージを通常のMatrixテキストメッセージとして作成します。これにより、Matrixの従来の「最初のプレビュー優先」の通知動作が維持されるため、標準クライアントでは完成済みブロックではなく最初のストリーミングプレビューテキストで通知されることがあります。 -- `streaming: "quiet"`は、現在のassistantブロック用に編集可能な静かなプレビュー通知を1件作成します。これは、確定済みプレビュー編集に対する受信者のプッシュルールも設定する場合にのみ使用してください。 -- `blockStreaming: true`は、別個のMatrix進行状況メッセージを有効にします。プレビューのストリーミングが有効な場合、Matrixは現在のブロックのライブドラフトを維持し、完了済みブロックは別メッセージとして保持します。 -- プレビューのストリーミングが有効で`blockStreaming`がoffの場合、Matrixはライブドラフトをその場で編集し、ブロックまたはターンが完了した時点で同じイベントを確定します。 -- プレビューが1つのMatrixイベントに収まらなくなった場合、OpenClawはプレビューストリーミングを停止し、通常の最終配信にフォールバックします。 -- メディア返信は引き続き通常どおり添付ファイルを送信します。古いプレビューを安全に再利用できなくなった場合、OpenClawは最終的なメディア返信を送る前にそれをredactします。 -- プレビュー編集では追加のMatrix API呼び出しが発生します。最も保守的なレート制限動作を望む場合は、ストリーミングをoffのままにしてください。 +- `streaming: "off"`がデフォルトです。OpenClawは最終返信を待ってから1回だけ送信します。 +- `streaming: "partial"`は、現在のアシスタントブロック用に通常のMatrixテキストメッセージを使った編集可能なプレビューメッセージを1つ作成します。これによりMatrixの従来の「プレビュー先行」通知動作が維持されるため、標準クライアントでは完成したブロックではなく、最初のストリーミングプレビューテキストで通知されることがあります。 +- `streaming: "quiet"`は、現在のアシスタントブロック用に編集可能な静かなプレビュー通知を1つ作成します。これを使用するのは、確定したプレビュー編集に対する受信者のプッシュルールも設定する場合のみにしてください。 +- `blockStreaming: true`は、個別のMatrix進捗メッセージを有効にします。プレビューのストリーミングが有効な場合、Matrixは現在のブロックのライブ下書きを維持し、完了済みブロックを個別のメッセージとして保持します。 +- プレビューが有効で`blockStreaming`がoffの場合、Matrixはライブ下書きをその場で編集し、ブロックまたはターンの完了時にその同じイベントを確定します。 +- プレビューが1つのMatrixイベントに収まらなくなった場合、OpenClawはプレビューのストリーミングを停止し、通常の最終配信にフォールバックします。 +- メディア返信は引き続き通常どおり添付ファイルを送信します。古いプレビューを安全に再利用できなくなった場合、OpenClawは最終メディア返信を送る前にそのプレビューを削除します。 +- プレビュー編集には追加のMatrix API呼び出しコストがかかります。もっとも保守的なレート制限の挙動を望む場合は、ストリーミングをoffのままにしてください。 -`blockStreaming`自体ではドラフトプレビューは有効になりません。 -プレビュー編集には`streaming: "partial"`または`streaming: "quiet"`を使い、そのうえで完了済みassistantブロックも別個の進行状況メッセージとして表示したい場合にのみ`blockStreaming: true`を追加してください。 +`blockStreaming`自体では下書きプレビューは有効になりません。 +プレビュー編集には`streaming: "partial"`または`streaming: "quiet"`を使用し、完了したアシスタントブロックも個別の進捗メッセージとして表示したい場合にのみ`blockStreaming: true`を追加してください。 -カスタムプッシュルールなしで標準のMatrix通知が必要な場合は、プレビュー優先動作には`streaming: "partial"`を使用するか、最終返信のみの配信には`streaming`をoffのままにしてください。`streaming: "off"`の場合: +カスタムプッシュルールなしで標準のMatrix通知が必要な場合は、プレビュー先行の動作には`streaming: "partial"`を使用するか、最終配信のみでよければ`streaming`をoffのままにしてください。`streaming: "off"`では: -- `blockStreaming: true`は、各完了済みブロックを通常の通知付きMatrixメッセージとして送信します。 +- `blockStreaming: true`は、完了した各ブロックを通常の通知付きMatrixメッセージとして送信します。 - `blockStreaming: false`は、最終的に完成した返信のみを通常の通知付きMatrixメッセージとして送信します。 -### 自己ホスト型プッシュルールによる静かな確定済みプレビュー +### 静かな確定プレビュー向けのセルフホストpush rules 独自のMatrixインフラを運用していて、静かなプレビューでブロックまたは -最終返信が完了したときだけ通知したい場合は、`streaming: "quiet"`を設定し、確定済みプレビュー編集用のユーザー単位プッシュルールを追加します。 +最終返信の完了時のみ通知したい場合は、`streaming: "quiet"`を設定し、確定したプレビュー編集用のユーザーごとのpush ruleを追加します。 -これは通常、homeserver全体の設定変更ではなく受信ユーザー側の設定です: +これは通常、homeserver全体の設定変更ではなく、受信ユーザー側のセットアップです: -開始前の簡単な対応表: +始める前の簡単な対応表: -- recipient user = 通知を受け取るべきユーザー +- recipient user = 通知を受け取る人 - bot user = 返信を送信するOpenClaw Matrixアカウント -- 以下のAPI呼び出しにはrecipient userのaccess tokenを使用します -- プッシュルールの`sender`はbot userの完全なMXIDと一致させます +- 以下のAPI呼び出しでは受信ユーザーのaccess tokenを使用する +- push rule内の`sender`はbot userの完全なMXIDに一致させる 1. OpenClawで静かなプレビューを使用するよう設定します: @@ -287,13 +287,13 @@ OpenClawに単一のライブプレビュー返信を送信させ、モデルが } ``` -2. 受信者アカウントが、すでに通常のMatrixプッシュ通知を受け取れていることを確認します。静かなプレビュー - ルールは、そのユーザーに正常に動作するpusherやデバイスがすでにある場合にのみ機能します。 +2. 受信アカウントがすでに通常のMatrixプッシュ通知を受け取れることを確認します。静かなプレビュー + ルールが機能するのは、そのユーザーにすでに動作中のpusher/deviceがある場合のみです。 -3. recipient userのaccess tokenを取得します。 - - ボットのトークンではなく、受信側ユーザーのトークンを使用してください。 - - 既存のクライアントセッショントークンを再利用するのが通常は最も簡単です。 - - 新しいトークンを発行する必要がある場合は、標準のMatrix Client-Server APIでログインできます: +3. 受信ユーザーのaccess tokenを取得します。 + - ボットのトークンではなく、受信ユーザーのトークンを使用します。 + - 既存のクライアントセッショントークンを再利用するのが通常はもっとも簡単です。 + - 新しいトークンを発行する必要がある場合は、標準のMatrix Client-Server API経由でログインできます: ```bash curl -sS -X POST \ @@ -309,7 +309,7 @@ curl -sS -X POST \ }' ``` -4. recipient accountにすでにpusherがあることを確認します: +4. 受信アカウントにすでにpusherがあることを確認します: ```bash curl -sS \ @@ -317,10 +317,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -これでアクティブなpusherやデバイスが返らない場合は、以下の +ここで有効なpusher/deviceが返ってこない場合は、以下の OpenClawルールを追加する前に、まず通常のMatrix通知を修正してください。 -OpenClawは、確定済みのテキストのみプレビュー編集に次の印を付けます: +OpenClawは、確定したテキストのみのプレビュー編集に次の印を付けます: ```json { @@ -328,7 +328,7 @@ OpenClawは、確定済みのテキストのみプレビュー編集に次の印 } ``` -5. これらの通知を受け取る各recipient accountに対してoverrideプッシュルールを作成します: +5. これらの通知を受け取る各受信アカウントに対してoverride push ruleを作成します: ```bash curl -sS -X PUT \ @@ -360,21 +360,21 @@ curl -sS -X PUT \ コマンド実行前に次の値を置き換えてください: -- `https://matrix.example.org`: あなたのhomeserverのベースURL -- `$USER_ACCESS_TOKEN`: 受信側ユーザーのaccess token -- `openclaw-finalized-preview-botname`: この受信側ユーザーに対するこのボット用の一意なrule ID -- `@bot:example.org`: 受信側ユーザーのMXIDではなく、あなたのOpenClaw MatrixボットのMXID +- `https://matrix.example.org`: あなたのhomeserverベースURL +- `$USER_ACCESS_TOKEN`: 受信ユーザーのaccess token +- `openclaw-finalized-preview-botname`: この受信ユーザーに対するこのボット専用の一意なrule ID +- `@bot:example.org`: 受信ユーザーのMXIDではなく、OpenClaw MatrixボットのMXID -複数ボット構成での重要事項: +マルチボット構成で重要: -- プッシュルールは`ruleId`で識別されます。同じrule IDに対して`PUT`を再実行すると、その1つのルールが更新されます。 -- 1人の受信側ユーザーが複数のOpenClaw Matrixボットアカウントから通知を受ける必要がある場合は、送信者一致ごとに一意なrule IDでボットごとに1つのルールを作成してください。 -- 単純なパターンは`openclaw-finalized-preview-`です。たとえば`openclaw-finalized-preview-ops`や`openclaw-finalized-preview-support`です。 +- push ruleは`ruleId`で識別されます。同じrule IDに対して`PUT`を再実行すると、その1つのルールが更新されます。 +- 1人の受信ユーザーが複数のOpenClaw Matrixボットアカウントからの通知を受ける必要がある場合は、各`sender`一致ごとに一意のrule IDを持つルールをボットごとに1つ作成してください。 +- シンプルなパターンは`openclaw-finalized-preview-`です。たとえば、`openclaw-finalized-preview-ops`や`openclaw-finalized-preview-support`です。 このルールはイベント送信者に対して評価されます: -- 受信側ユーザーのトークンで認証する -- `sender`をOpenClawボットのMXIDと一致させる +- 受信ユーザーのトークンで認証する +- `sender`をOpenClawボットのMXIDに一致させる 6. ルールが存在することを確認します: @@ -384,10 +384,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. ストリーミング返信をテストします。quietモードでは、ルームには静かなドラフトプレビューが表示され、 - 最終的なその場編集でブロックまたはターン完了時に1回通知されるはずです。 +7. ストリーミング返信をテストします。quietモードでは、ルームには静かな下書きプレビューが表示され、 + ブロックまたはターンが完了すると最終的なインプレース編集で1回通知されるはずです。 -後でルールを削除する必要がある場合は、同じrule IDを受信側ユーザーのトークンで削除します: +後でルールを削除する必要がある場合は、受信ユーザーのトークンで同じrule IDを削除します: ```bash curl -sS -X DELETE \ @@ -397,31 +397,31 @@ curl -sS -X DELETE \ 注記: -- ルール作成には、ボットのトークンではなく受信側ユーザーのaccess tokenを使用してください。 -- 新しいユーザー定義`override`ルールはデフォルトの抑制ルールより前に挿入されるため、追加の順序パラメータは不要です。 -- これは、OpenClawが安全にその場で確定できるテキストのみのプレビュー編集にのみ影響します。メディアフォールバックや古いプレビューフォールバックは、引き続き通常のMatrix配信を使用します。 -- `GET /_matrix/client/v3/pushers`でpusherが表示されない場合、そのユーザーはまだそのアカウント/デバイスで正常に動作するMatrixプッシュ配信を利用できていません。 +- ルールはボットのaccess tokenではなく、受信ユーザーのaccess tokenで作成してください。 +- 新しいユーザー定義の`override`ルールはデフォルトの抑制ルールより前に挿入されるため、追加の順序パラメータは不要です。 +- これは、OpenClawが安全にその場で確定できるテキストのみのプレビュー編集にのみ影響します。メディアフォールバックと古いプレビューフォールバックでは、引き続き通常のMatrix配信が使われます。 +- `GET /_matrix/client/v3/pushers`でpusherが表示されない場合、そのユーザーはまだそのアカウント/デバイスで動作するMatrixプッシュ配信を持っていません。 #### Synapse Synapseでは、通常は上記のセットアップだけで十分です: -- 確定済みOpenClawプレビュー通知のために特別な`homeserver.yaml`変更は不要です。 -- Synapse環境ですでに通常のMatrixプッシュ通知が送れている場合、主なセットアップ手順は上記のユーザートークン + `pushrules`呼び出しです。 -- Synapseをリバースプロキシまたはworkerの背後で運用している場合は、`/_matrix/client/.../pushrules/`が正しくSynapseに届くことを確認してください。 -- Synapse workerを使用している場合は、pusherが正常であることを確認してください。プッシュ配信はメインプロセスまたは`synapse.app.pusher` / 設定されたpusher workerで処理されます。 +- 確定したOpenClawプレビュー通知のために特別な`homeserver.yaml`変更は不要です。 +- Synapseデプロイですでに通常のMatrixプッシュ通知が送信されている場合、主なセットアップ手順は上記のユーザートークン + `pushrules`呼び出しです。 +- Synapseをリバースプロキシまたはworkerの背後で動かしている場合は、`/_matrix/client/.../pushrules/`が正しくSynapseに到達することを確認してください。 +- Synapse workerを使用している場合は、pusherが正常であることを確認してください。プッシュ配信はメインプロセスまたは`synapse.app.pusher` / 設定されたpusher workerによって処理されます。 #### Tuwunel -Tuwunelでは、上記と同じセットアップ手順とpush-rule API呼び出しを使用します: +Tuwunelでは、上記と同じセットアップフローとpush-rule API呼び出しを使用します: -- 確定済みプレビューマーカー自体にTuwunel固有の設定は不要です。 -- そのユーザーで通常のMatrix通知がすでに機能している場合、主なセットアップ手順は上記のユーザートークン + `pushrules`呼び出しです。 -- ユーザーが別のデバイスでアクティブな間に通知が消えるように見える場合は、`suppress_push_when_active`が有効か確認してください。Tuwunelは2025年9月12日のTuwunel 1.4.2でこのオプションを追加しており、1つのデバイスがアクティブな間は他のデバイスへのプッシュを意図的に抑制することがあります。 +- 確定プレビューマーカー自体に対して、Tuwunel固有の設定は不要です。 +- そのユーザーに対して通常のMatrix通知がすでに機能している場合、主なセットアップ手順は上記のユーザートークン + `pushrules`呼び出しです。 +- ユーザーが別のデバイスでアクティブな間に通知が消えるように見える場合は、`suppress_push_when_active`が有効になっていないか確認してください。Tuwunelは2025年9月12日のTuwunel 1.4.2でこのオプションを追加しており、1つのデバイスがアクティブな間、他のデバイスへのプッシュを意図的に抑制することがあります。 ## ボット同士のルーム -デフォルトでは、他の設定済みOpenClaw MatrixアカウントからのMatrixメッセージは無視されます。 +デフォルトでは、設定済みの他のOpenClaw MatrixアカウントからのMatrixメッセージは無視されます。 エージェント間のMatrixトラフィックを意図的に許可したい場合は、`allowBots`を使用します: @@ -440,19 +440,19 @@ Tuwunelでは、上記と同じセットアップ手順とpush-rule API呼び出 } ``` -- `allowBots: true`は、許可されたルームとDMにおいて、他の設定済みMatrixボットアカウントからのメッセージを受け付けます。 -- `allowBots: "mentions"`は、ルームではそれらのメッセージがこのボットに明示的にメンションしている場合にのみ受け付けます。DMは引き続き許可されます。 +- `allowBots: true`は、許可されたルームとDMで、設定済みの他のMatrixボットアカウントからのメッセージを受け入れます。 +- `allowBots: "mentions"`は、ルーム内でそれらのメッセージがこのボットに明示的にメンションしている場合にのみ受け入れます。DMは引き続き許可されます。 - `groups..allowBots`は、1つのルームに対してアカウントレベル設定を上書きします。 -- OpenClawは、自己返信ループを避けるため、同じMatrix user IDからのメッセージは引き続き無視します。 -- Matrixはここでネイティブのボットフラグを提供しません。OpenClawは「ボットによる送信」を「このOpenClaw Gateway上で設定された別のMatrixアカウントから送信されたもの」として扱います。 +- OpenClawは自己返信ループを避けるため、同じMatrixユーザーIDからのメッセージは引き続き無視します。 +- Matrixはここでネイティブのボットフラグを公開していません。OpenClawは「ボット作成」とは「このOpenClaw Gateway上の別の設定済みMatrixアカウントによって送信されたもの」と見なします。 -共有ルームでボット間通信を有効にする場合は、厳格なルーム許可リストとメンション必須設定を使用してください。 +共有ルームでボット同士のトラフィックを有効にする場合は、厳格なルームallowlistとメンション必須設定を使用してください。 ## 暗号化と検証 -暗号化された（E2EE）ルームでは、送信画像イベントは`thumbnail_file`を使用するため、画像プレビューは完全な添付ファイルと一緒に暗号化されます。暗号化されていないルームでは引き続き通常の`thumbnail_url`を使用します。設定は不要です — プラグインがE2EE状態を自動検出します。 +暗号化された（E2EE）ルームでは、送信する画像イベントは`thumbnail_file`を使用するため、画像プレビューは完全な添付ファイルと一緒に暗号化されます。暗号化されていないルームでは、引き続き通常の`thumbnail_url`を使用します。設定は不要です — PluginがE2EE状態を自動検出します。 -暗号化を有効化: +暗号化を有効にする: ```json5 { @@ -468,43 +468,43 @@ Tuwunelでは、上記と同じセットアップ手順とpush-rule API呼び出 } ``` -検証状態を確認: +検証ステータスを確認する: ```bash openclaw matrix verify status ``` -詳細ステータス（完全な診断）: +詳細ステータス（完全な診断情報）: ```bash openclaw matrix verify status --verbose ``` -保存されているrecovery keyを機械可読出力に含める: +保存済みのrecovery keyを機械可読出力に含める: ```bash openclaw matrix verify status --include-recovery-key --json ``` -cross-signingと検証状態をブートストラップ: +cross-signingと検証状態をbootstrapする: ```bash openclaw matrix verify bootstrap ``` -詳細なブートストラップ診断: +詳細なbootstrap診断情報: ```bash openclaw matrix verify bootstrap --verbose ``` -ブートストラップ前に新しいcross-signing identityリセットを強制する: +bootstrap前に新しいcross-signing IDリセットを強制する: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -recovery keyでこのデバイスを検証: +recovery keyでこのデバイスを検証する: ```bash openclaw matrix verify device "" @@ -516,44 +516,44 @@ openclaw matrix verify device "" openclaw matrix verify device "" --verbose ``` -room-key backupの健全性を確認: +ルームキーbackupの健全性を確認する: ```bash openclaw matrix verify backup status ``` -詳細なbackup健全性診断: +詳細なbackup健全性診断情報: ```bash openclaw matrix verify backup status --verbose ``` -サーバーバックアップからroom keyを復元: +サーバーbackupからルームキーを復元する: ```bash openclaw matrix verify backup restore ``` -詳細な復元診断: +詳細な復元診断情報: ```bash openclaw matrix verify backup restore --verbose ``` -現在のサーバーバックアップを削除し、新しいバックアップベースラインを作成します。保存されている -backup keyを正常に読み込めない場合、このリセットではsecret storageも再作成され、 -将来のコールドスタートで新しいbackup keyを読み込めるようになります: +現在のサーバーbackupを削除し、新しいbackupベースラインを作成します。保存済みの +backup keyを正常に読み込めない場合、このリセットによってsecret storageも再作成され、 +将来のコールドスタートで新しいbackup keyを読み込めるようになることがあります: ```bash openclaw matrix verify backup reset --yes ``` -すべての`verify`コマンドはデフォルトで簡潔です（内部SDKログも静かに含む）し、詳細な診断は`--verbose`でのみ表示されます。 +すべての`verify`コマンドはデフォルトで簡潔です（quietな内部SDKロギングを含む）で、詳細な診断情報は`--verbose`を付けた場合のみ表示されます。 スクリプトで使用する場合は、完全な機械可読出力のために`--json`を使用してください。 -複数アカウント構成では、`--account `を渡さない限り、Matrix CLIコマンドは暗黙のMatrixデフォルトアカウントを使用します。 -複数の名前付きアカウントを設定している場合は、まず`channels.matrix.defaultAccount`を設定してください。設定しないと、そのような暗黙のCLI操作は停止して明示的なアカウント選択を求めます。 -検証またはデバイス操作を名前付きアカウントに明示的に向けたい場合は、常に`--account`を使用してください: +マルチアカウント構成では、Matrix CLIコマンドは`--account `を渡さない限り暗黙のMatrixデフォルトアカウントを使用します。 +複数の名前付きアカウントを設定する場合は、先に`channels.matrix.defaultAccount`を設定してください。設定しないと、それらの暗黙のCLI操作は停止して、どのアカウントを使うか明示的に選ぶよう求めます。 +検証またはデバイス操作を明示的に名前付きアカウントに向けたい場合は、常に`--account`を使用してください: ```bash openclaw matrix verify status --account assistant @@ -561,42 +561,42 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -名前付きアカウントで暗号化が無効または利用不可の場合、Matrixの警告と検証エラーは、そのアカウントのconfigキー、たとえば`channels.matrix.accounts.assistant.encryption`を指します。 +暗号化が無効または名前付きアカウントで利用不可の場合、Matrixの警告と検証エラーはそのアカウントのconfigキー、たとえば`channels.matrix.accounts.assistant.encryption`を指します。 -### 「verified」の意味 +### 「検証済み」の意味 -OpenClawは、このMatrixデバイスがあなた自身のcross-signing identityによって検証されている場合にのみ、verifiedとして扱います。 -実際には、`openclaw matrix verify status --verbose`は3つの信頼シグナルを公開します: +OpenClawは、このMatrixデバイスがあなた自身のcross-signing IDによって検証されている場合にのみ、このデバイスを検証済みとして扱います。 +実際には、`openclaw matrix verify status --verbose`は3つの信頼シグナルを表示します: - `Locally trusted`: このデバイスは現在のクライアントでのみ信頼されています -- `Cross-signing verified`: SDKがこのデバイスをcross-signing経由で検証済みとして報告しています -- `Signed by owner`: このデバイスはあなた自身のself-signing keyによって署名されています +- `Cross-signing verified`: SDKがこのデバイスをcross-signing経由で検証済みとして報告します +- `Signed by owner`: このデバイスはあなた自身のself-signing keyで署名されています -`Verified by owner`が`yes`になるのは、cross-signing検証またはowner署名が存在する場合のみです。 -ローカル信頼だけでは、OpenClawはそのデバイスを完全に検証済みとして扱いません。 +`Verified by owner`が`yes`になるのは、cross-signingによる検証またはowner-signingが存在する場合のみです。 +ローカル信頼だけでは、OpenClawはこのデバイスを完全に検証済みとは見なしません。 -### ブートストラップが行うこと +### bootstrapが行うこと -`openclaw matrix verify bootstrap`は、暗号化されたMatrixアカウント向けの修復およびセットアップコマンドです。 -これは次のすべてを順番に実行します: +`openclaw matrix verify bootstrap`は、暗号化されたMatrixアカウントの修復およびセットアップコマンドです。 +次のすべてを順に実行します: -- secret storageをブートストラップし、可能な場合は既存のrecovery keyを再利用する -- cross-signingをブートストラップし、不足している公開cross-signing keyをアップロードする -- 現在のデバイスをマークしてcross-signingすることを試みる -- サーバー側room-key backupがまだ存在しない場合は新しいものを作成する +- secret storageをbootstrapし、可能であれば既存のrecovery keyを再利用する +- cross-signingをbootstrapし、不足している公開cross-signing keyをアップロードする +- 現在のデバイスに印を付けてcross-signingすることを試みる +- まだ存在しない場合は、新しいサーバー側のルームキーbackupを作成する -homeserverがcross-signing keyのアップロードに対して対話的認証を要求する場合、OpenClawはまず認証なしでアップロードを試し、その後`m.login.dummy`、さらに`channels.matrix.password`が設定されている場合は`m.login.password`で試します。 +homeserverがcross-signing keyのアップロードに対して対話的認証を要求する場合、OpenClawはまず認証なしでアップロードを試行し、次に`m.login.dummy`で、`channels.matrix.password`が設定されている場合は`m.login.password`でも試行します。 -現在のcross-signing identityを破棄して新しいものを作成したい場合にのみ、`--force-reset-cross-signing`を使用してください。 +`--force-reset-cross-signing`は、現在のcross-signing IDを破棄して新しいものを作成したい場合にのみ使用してください。 -現在のroom-key backupを意図的に破棄して、今後のメッセージ用に新しい -backup baselineを開始したい場合は、`openclaw matrix verify backup reset --yes`を使用してください。 -これは、復旧不能な古い暗号化履歴が引き続き利用できないままになること、 -また現在のbackup secretを安全に読み込めない場合にOpenClawがsecret storageを再作成する可能性があることを受け入れる場合にのみ実行してください。 +現在のルームキーbackupを意図的に破棄し、今後のメッセージ用に新しい +backupベースラインを開始したい場合は、`openclaw matrix verify backup reset --yes`を使用してください。 +これは、回復不能な古い暗号化履歴が引き続き利用できないままであることと、 +現在のbackup secretを安全に読み込めない場合にOpenClawがsecret storageを再作成する可能性があることを受け入れる場合にのみ行ってください。 -### 新しいバックアップベースライン +### 新しいbackupベースライン -今後の暗号化メッセージを維持しつつ、復旧不能な古い履歴の喪失を受け入れる場合は、次のコマンドを順番に実行してください: +今後の暗号化メッセージを機能させ続けつつ、回復不能な古い履歴の喪失を受け入れる場合は、次のコマンドを順に実行してください: ```bash openclaw matrix verify backup reset --yes @@ -608,49 +608,49 @@ openclaw matrix verify status ### 起動時の動作 -`encryption: true`の場合、Matrixは`startupVerification`をデフォルトで`"if-unverified"`にします。 -起動時にこのデバイスがまだ未検証であれば、Matrixは別のMatrixクライアントでの自己検証を要求し、 -すでに保留中の要求がある場合は重複要求をスキップし、再起動後の再試行にはローカルのクールダウンを適用します。 -失敗した要求試行は、デフォルトでは要求作成成功後よりも早く再試行されます。 -自動起動時要求を無効にするには`startupVerification: "off"`を設定するか、再試行間隔を短くまたは長くしたい場合は`startupVerificationCooldownHours`を調整してください。 +`encryption: true`の場合、Matrixは`startupVerification`のデフォルトを`"if-unverified"`にします。 +起動時にこのデバイスがまだ未検証であれば、Matrixは別のMatrixクライアントで自己検証を要求し、 +すでに保留中の要求がある場合は重複要求をスキップし、再起動後の再試行前にローカルクールダウンを適用します。 +失敗した要求試行は、デフォルトでは要求作成の成功後よりも早く再試行されます。 +自動起動時要求を無効にするには`startupVerification: "off"`を設定するか、再試行ウィンドウを短くまたは長くしたい場合は`startupVerificationCooldownHours`を調整してください。 -起動時には、自動的に保守的なcrypto bootstrap処理も実行されます。 -この処理では、まず現在のsecret storageとcross-signing identityの再利用を試み、明示的なbootstrap修復フローを実行しない限りcross-signingをリセットしないようにします。 +起動時には、保守的なcrypto bootstrapパスも自動的に実行されます。 +このパスは、最初に現在のsecret storageとcross-signing IDの再利用を試み、明示的なbootstrap修復フローを実行しない限りcross-signingのリセットを避けます。 -起動時に壊れたbootstrap状態が検出され、かつ`channels.matrix.password`が設定されている場合、OpenClawはより厳格な修復経路を試みることがあります。 -現在のデバイスがすでにowner-signedである場合、OpenClawはそのidentityを自動でリセットせず保持します。 +起動時に壊れたbootstrap状態が見つかり、`channels.matrix.password`が設定されている場合、OpenClawはより厳格な修復パスを試みることがあります。 +現在のデバイスがすでにowner-signedである場合、OpenClawはそれを自動的にリセットせず、そのIDを保持します。 -完全なアップグレード手順、制限、復旧コマンド、一般的な移行メッセージについては、[Matrix migration](/ja-JP/install/migrating-matrix)を参照してください。 +完全なアップグレードフロー、制限、回復コマンド、一般的な移行メッセージについては、[Matrix migration](/ja-JP/install/migrating-matrix)を参照してください。 ### 検証通知 -Matrixは、検証ライフサイクル通知を厳格なDM検証ルームに`m.notice`メッセージとして直接投稿します。 +Matrixは、厳格なDM検証ルームに検証ライフサイクル通知を`m.notice`メッセージとして直接投稿します。 これには次が含まれます: -- 検証リクエスト通知 -- 検証準備完了通知（明示的な「絵文字で検証する」案内付き） +- 検証要求通知 +- 検証準備完了通知（明示的な「絵文字で検証」ガイダンス付き） - 検証開始および完了通知 -- 利用可能な場合はSAS詳細（絵文字および10進数） +- 利用可能な場合のSAS詳細（絵文字と10進数） -別のMatrixクライアントからの受信検証リクエストは、OpenClawが追跡して自動承認します。 -自己検証フローでは、絵文字検証が利用可能になるとOpenClawはSASフローも自動的に開始し、自身の側を確認します。 -別のMatrixユーザー/デバイスからの検証リクエストについては、OpenClawはリクエストを自動承認し、その後SASフローが通常どおり進行するのを待ちます。 +別のMatrixクライアントからの受信検証要求は、OpenClawによって追跡され自動承認されます。 +自己検証フローでは、OpenClawは絵文字検証が利用可能になるとSASフローも自動的に開始し、自身の側を確認します。 +別のMatrixユーザー/デバイスからの検証要求については、OpenClawは要求を自動承認し、その後SASフローが通常どおり進行するのを待ちます。 検証を完了するには、引き続きMatrixクライアントで絵文字または10進数のSASを比較し、そこで「一致する」を確認する必要があります。 -OpenClawは、自分自身が開始した重複フローを無条件に自動承認しません。起動時には、自己検証リクエストがすでに保留中の場合、新しいリクエストの作成をスキップします。 +OpenClawは、自己開始された重複フローを無条件に自動承認しません。自己検証要求がすでに保留中の場合、起動時に新しい要求の作成はスキップされます。 -検証プロトコル/システム通知はエージェントチャットパイプラインには転送されないため、`NO_REPLY`は発生しません。 +検証プロトコル/システム通知はエージェントチャットパイプラインには転送されないため、`NO_REPLY`は生成されません。 ### デバイス衛生 -OpenClawが管理する古いMatrixデバイスがアカウントに蓄積し、暗号化ルームの信頼関係が把握しにくくなることがあります。 -一覧表示するには: +古いOpenClaw管理のMatrixデバイスがアカウントに蓄積し、暗号化ルームの信頼性を把握しにくくなることがあります。 +次のコマンドで一覧表示します: ```bash openclaw matrix devices list ``` -古いOpenClaw管理デバイスを削除するには: +古くなったOpenClaw管理デバイスを削除するには: ```bash openclaw matrix devices prune-stale @@ -658,68 +658,68 @@ openclaw matrix devices prune-stale ### Crypto store -Matrix E2EEは、Node上で公式の`matrix-js-sdk` Rust cryptoパスを使用し、IndexedDB shimとして`fake-indexeddb`を使います。crypto状態はスナップショットファイル（`crypto-idb-snapshot.json`）に永続化され、起動時に復元されます。スナップショットファイルは、制限されたファイル権限で保存される機密ランタイム状態です。 +Matrix E2EEは、Node上で公式の`matrix-js-sdk` Rust cryptoパスを使用し、IndexedDB shimとして`fake-indexeddb`を使います。Crypto状態はスナップショットファイル（`crypto-idb-snapshot.json`）に永続化され、起動時に復元されます。スナップショットファイルは、制限されたファイル権限で保存される機密性の高いランタイム状態です。 -暗号化されたランタイム状態は、アカウント・ユーザー・トークンハッシュごとのルート配下で -`~/.openclaw/matrix/accounts//__//`に保存されます。 +暗号化されたランタイム状態は、アカウントごと・ユーザーのtoken-hashごとのルートの下に +`~/.openclaw/matrix/accounts//__//`として保存されます。 このディレクトリには、sync store（`bot-storage.json`）、crypto store（`crypto/`）、 -recovery keyファイル（`recovery-key.json`）、IndexedDBスナップショット（`crypto-idb-snapshot.json`）、 -thread bindings（`thread-bindings.json`）、およびstartup verification state（`startup-verification.json`）が含まれます。 -トークンが変わってもアカウントidentityが同じであれば、OpenClawはそのアカウント/homeserver/user組に対して最適な既存ルートを再利用するため、以前のsync state、crypto state、thread bindings、 -startup verification stateは引き続き見える状態のままです。 +recovery keyファイル（`recovery-key.json`）、IndexedDB snapshot（`crypto-idb-snapshot.json`）、 +thread binding（`thread-bindings.json`）、およびstartup verification state（`startup-verification.json`）が含まれます。 +トークンが変わってもアカウントIDが同じままであれば、OpenClawはそのアカウント/homeserver/user組み合わせに対して最適な既存ルートを再利用するため、以前のsync state、crypto state、thread binding、 +およびstartup verification stateは引き続き参照できます。 ## プロファイル管理 -選択したアカウントのMatrix self-profileを更新するには: +選択したアカウントのMatrixセルフプロファイルを更新するには、次を実行します: ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -名前付きアカウントを明示的に対象にしたい場合は、`--account `を追加してください。 +名前付きMatrixアカウントを明示的に対象にしたい場合は、`--account `を追加してください。 -Matrixは`mxc://`形式のavatar URLを直接受け付けます。`http://`または`https://`のavatar URLを渡すと、OpenClawはまずそれをMatrixにアップロードし、解決後の`mxc://` URLを`channels.matrix.avatarUrl`（または選択したアカウント上書き）に保存し直します。 +Matrixは`mxc://` avatar URLをそのまま受け付けます。`http://`または`https://`のavatar URLを渡した場合、OpenClawはまずそれをMatrixにアップロードし、解決された`mxc://` URLを`channels.matrix.avatarUrl`（または選択したアカウントのoverride）に保存します。 ## スレッド -Matrixは、自動返信とmessage-tool送信の両方でネイティブのMatrixスレッドをサポートします。 +Matrixは、自動返信とmessage-tool送信の両方についてネイティブのMatrixスレッドをサポートします。 -- `dm.sessionScope: "per-user"`（デフォルト）は、Matrix DMルーティングを送信者スコープのままにするため、同じ相手に解決される複数のDMルームが1つのセッションを共有できます。 -- `dm.sessionScope: "per-room"`は、通常のDM認証と許可リストチェックを引き続き使用しながら、各Matrix DMルームを独自のセッションキーに分離します。 -- 明示的なMatrix会話bindingは引き続き`dm.sessionScope`より優先されるため、bindingされたルームとスレッドは選択した対象セッションを維持します。 -- `threadReplies: "off"`は、返信をトップレベルのままにし、受信したスレッド付きメッセージも親セッション上に維持します。 -- `threadReplies: "inbound"`は、受信メッセージがすでにそのスレッド内にある場合にのみ、そのスレッド内で返信します。 -- `threadReplies: "always"`は、ルーム返信をトリガーメッセージをルートとするスレッド内に保持し、その会話を最初のトリガーメッセージに一致するスレッドスコープのセッション経由でルーティングします。 -- `dm.threadReplies`は、DMに対してのみトップレベル設定を上書きします。たとえば、ルームスレッドは分離したまま、DMはフラットに維持できます。 -- 受信したスレッド付きメッセージには、追加のagent contextとしてスレッドルートメッセージが含まれます。 -- message-tool送信は、明示的な`threadId`が指定されていない限り、対象が同じルーム、または同じDMユーザー対象であれば、現在のMatrixスレッドを自動継承します。 -- 同一セッションのDMユーザー対象再利用は、現在のセッションメタデータが同じMatrixアカウント上の同一DM相手を証明している場合にのみ有効です。それ以外では、OpenClawは通常のユーザースコープルーティングにフォールバックします。 -- OpenClawが、共有された同一Matrix DMセッション上であるMatrix DMルームが別のDMルームと衝突していることを検出した場合、thread bindingsが有効で、`dm.sessionScope`のヒントがあると、そのルームに一度だけ`/focus`エスケープハッチ付きの`m.notice`を投稿します。 -- Matrixではランタイムthread bindingsがサポートされています。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびスレッドにバインドされた`/acp spawn`は、MatrixルームとDMで機能します。 -- トップレベルのMatrixルーム/DMでの`/focus`は、`threadBindings.spawnSubagentSessions=true`のとき、新しいMatrixスレッドを作成して対象セッションにbindします。 +- `dm.sessionScope: "per-user"`（デフォルト）は、Matrix DMルーティングを送信者スコープのままにするため、同じ相手に解決される複数のDMルームで1つのセッションを共有できます。 +- `dm.sessionScope: "per-room"`は、通常のDM認証とallowlistチェックを使いながら、各Matrix DMルームを独自のセッションキーに分離します。 +- 明示的なMatrix会話bindingは引き続き`dm.sessionScope`より優先されるため、binding済みのルームとスレッドは選択された対象セッションを維持します。 +- `threadReplies: "off"`は、返信をトップレベルのままにし、受信したスレッドメッセージを親セッション上に維持します。 +- `threadReplies: "inbound"`は、受信メッセージがすでにそのスレッド内にあった場合にのみ、スレッド内で返信します。 +- `threadReplies: "always"`は、トリガーとなったメッセージをルートとするスレッド内にルーム返信を維持し、その会話を最初のトリガーメッセージから対応するスレッドスコープのセッション経由でルーティングします。 +- `dm.threadReplies`は、DMに対してのみトップレベル設定を上書きします。たとえば、ルームスレッドは分離したまま、DMはフラットに保てます。 +- 受信したスレッドメッセージには、追加のagentコンテキストとしてスレッドのルートメッセージが含まれます。 +- message-tool送信は、明示的な`threadId`が指定されていない限り、対象が同じルームまたは同じDMユーザー対象であれば、現在のMatrixスレッドを自動継承します。 +- 同一セッションのDMユーザー対象再利用が有効になるのは、現在のセッションmetadataによって、同じMatrixアカウント上の同じDM相手であることが証明される場合のみです。それ以外では、OpenClawは通常のユーザースコープルーティングにフォールバックします。 +- OpenClawが、同じ共有Matrix DMセッション上で1つのMatrix DMルームが別のDMルームと衝突していることを検出すると、thread bindingが有効で`dm.sessionScope`ヒントがある場合、そのルームに`/focus`の退避手段を含む1回限りの`m.notice`を投稿します。 +- Matrixではランタイムthread bindingがサポートされます。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびスレッドにbindingされた`/acp spawn`は、MatrixルームとDMで動作します。 +- トップレベルのMatrixルーム/DMでの`/focus`は、`threadBindings.spawnSubagentSessions=true`のとき、新しいMatrixスレッドを作成し、それを対象セッションにbindします。 - 既存のMatrixスレッド内で`/focus`または`/acp spawn --thread here`を実行すると、代わりにその現在のスレッドがbindされます。 -## ACP会話bindings +## ACP会話binding -Matrixルーム、DM、既存のMatrixスレッドは、チャット画面を変えることなく永続的なACPワークスペースにできます。 +Matrixルーム、DM、既存のMatrixスレッドは、チャットの表面を変えずに永続的なACP workspaceにできます。 -迅速なオペレーターフロー: +高速なオペレーターフロー: -- 引き続き使いたいMatrix DM、ルーム、または既存スレッド内で`/acp spawn codex --bind here`を実行します。 -- トップレベルのMatrix DMまたはルームでは、現在のDM/ルームがそのままチャット画面として使われ、今後のメッセージは生成されたACPセッションにルーティングされます。 +- 使い続けたいMatrix DM、ルーム、または既存スレッドの中で`/acp spawn codex --bind here`を実行します。 +- トップレベルのMatrix DMまたはルームでは、現在のDM/ルームがチャットの表面として維持され、以後のメッセージは生成されたACPセッションにルーティングされます。 - 既存のMatrixスレッド内では、`--bind here`がその現在のスレッドをその場でbindします。 -- `/new`と`/reset`は、同じbind済みACPセッションをその場でリセットします。 +- `/new`と`/reset`は、同じbinding済みACPセッションをその場でリセットします。 - `/acp close`はACPセッションを閉じてbindingを削除します。 注記: -- `--bind here`は子のMatrixスレッドを作成しません。 -- `threadBindings.spawnAcpSessions`は、OpenClawが子のMatrixスレッドを作成またはbindする必要がある`/acp spawn --thread auto|here`でのみ必要です。 +- `--bind here`は子Matrixスレッドを作成しません。 +- `threadBindings.spawnAcpSessions`が必要なのは、OpenClawが子Matrixスレッドを作成またはbindする必要がある`/acp spawn --thread auto|here`の場合のみです。 ### スレッドbinding設定 -Matrixは`session.threadBindings`からグローバルデフォルトを継承し、チャネル単位の上書きもサポートします: +Matrixは`session.threadBindings`からグローバルデフォルトを継承し、チャネルごとのoverrideもサポートします: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -727,35 +727,35 @@ Matrixは`session.threadBindings`からグローバルデフォルトを継承 - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Matrixのスレッドbindされたspawnフラグはオプトインです: +Matrixのスレッドbinding付きspawnフラグはオプトインです: - トップレベルの`/focus`で新しいMatrixスレッドを作成してbindできるようにするには、`threadBindings.spawnSubagentSessions: true`を設定します。 - `/acp spawn --thread auto|here`でACPセッションをMatrixスレッドにbindできるようにするには、`threadBindings.spawnAcpSessions: true`を設定します。 ## リアクション -Matrixは、送信リアクション操作、受信リアクション通知、受信ackリアクションをサポートします。 +Matrixは、送信リアクションアクション、受信リアクション通知、および受信ackリアクションをサポートします。 -- 送信リアクションツールは`channels["matrix"].actions.reactions`で制御されます。 -- `react`は特定のMatrixイベントにリアクションを追加します。 -- `reactions`は特定のMatrixイベントに対する現在のリアクション要約を一覧表示します。 +- 送信リアクションtoolingは`channels["matrix"].actions.reactions`で制御されます。 +- `react`は、特定のMatrixイベントにリアクションを追加します。 +- `reactions`は、特定のMatrixイベントに対する現在のリアクション要約を一覧表示します。 - `emoji=""`は、そのイベント上のボットアカウント自身のリアクションを削除します。 -- `remove: true`は、ボットアカウントの指定された絵文字リアクションのみを削除します。 +- `remove: true`は、ボットアカウントから指定した絵文字リアクションのみを削除します。 ackリアクションは標準のOpenClaw解決順序を使用します: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- agent identityの絵文字フォールバック +- agent identity emoji fallback -ackリアクションのスコープは次の順序で解決されます: +ackリアクションスコープは次の順で解決されます: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -リアクション通知モードは次の順序で解決されます: +リアクション通知モードは次の順で解決されます: - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` @@ -763,30 +763,30 @@ ackリアクションのスコープは次の順序で解決されます: 動作: -- `reactionNotifications: "own"`は、ボットが作成したMatrixメッセージを対象とする追加`m.reaction`イベントを転送します。 -- `reactionNotifications: "off"`は、リアクションシステムイベントを無効にします。 -- リアクション削除は、Matrixではそれらが独立した`m.reaction`削除ではなくredactionとして表現されるため、システムイベントには合成されません。 +- `reactionNotifications: "own"`は、ボット作成のMatrixメッセージを対象とする追加された`m.reaction`イベントを転送します。 +- `reactionNotifications: "off"`はリアクションシステムイベントを無効にします。 +- リアクション削除は、Matrixがそれらを独立した`m.reaction`削除ではなくredactionとして表現するため、システムイベントには合成されません。 ## 履歴コンテキスト -- `channels.matrix.historyLimit`は、Matrixルームメッセージがagentをトリガーしたときに`InboundHistory`として含める最近のルームメッセージ数を制御します。`messages.groupChat.historyLimit`にフォールバックし、両方とも未設定の場合の実効デフォルトは`0`です。無効にするには`0`を設定してください。 +- `channels.matrix.historyLimit`は、Matrixルームメッセージがagentをトリガーしたときに`InboundHistory`として含める最近のルームメッセージ数を制御します。`messages.groupChat.historyLimit`にフォールバックし、両方とも未設定の場合、実効デフォルトは`0`です。無効化するには`0`を設定してください。 - Matrixルーム履歴はルーム専用です。DMは通常のセッション履歴を引き続き使用します。 -- Matrixルーム履歴はpendingのみです。OpenClawはまだ返信をトリガーしていないルームメッセージをバッファし、メンションなどのトリガーが来た時点でそのウィンドウをスナップショットします。 -- 現在のトリガーメッセージは`InboundHistory`には含まれません。そのターンのメイン受信本文に残ります。 -- 同じMatrixイベントの再試行では、より新しいルームメッセージへずれていくのではなく、元の履歴スナップショットを再利用します。 +- Matrixルーム履歴は保留中のみです。OpenClawはまだ返信をトリガーしていないルームメッセージをバッファし、メンションや他のトリガーが来たときにそのウィンドウをスナップショットします。 +- 現在のトリガーメッセージは`InboundHistory`に含まれません。そのターンのメイン受信本文に残ります。 +- 同じMatrixイベントの再試行では、新しいルームメッセージへ前進してずれることなく、元の履歴スナップショットが再利用されます。 ## コンテキスト可視性 -Matrixは、取得した返信テキスト、スレッドルート、pending履歴などの補足ルームコンテキストに対して、共通の`contextVisibility`制御をサポートします。 +Matrixは、取得した返信テキスト、スレッドルート、保留中の履歴などの補助的なルームコンテキストに対する共有の`contextVisibility`制御をサポートします。 -- `contextVisibility: "all"`がデフォルトです。補足コンテキストは受信したまま保持されます。 -- `contextVisibility: "allowlist"`は、補足コンテキストを、アクティブなルーム/ユーザー許可リストチェックで許可された送信者に限定します。 -- `contextVisibility: "allowlist_quote"`は`allowlist`と同様に動作しますが、1つの明示的な引用返信は引き続き保持します。 +- `contextVisibility: "all"`がデフォルトです。補助コンテキストは受信したまま保持されます。 +- `contextVisibility: "allowlist"`は、アクティブなルーム/ユーザーallowlistチェックで許可された送信者に補助コンテキストを絞り込みます。 +- `contextVisibility: "allowlist_quote"`は`allowlist`と同様に動作しますが、1つの明示的な引用返信は保持します。 -この設定は、補足コンテキストの可視性に影響し、受信メッセージ自体が返信をトリガーできるかどうかには影響しません。 -トリガー認可は引き続き`groupPolicy`、`groups`、`groupAllowFrom`、およびDMポリシー設定によって決まります。 +この設定は補助コンテキストの可視性に影響し、受信メッセージ自体が返信をトリガーできるかどうかには影響しません。 +トリガーの認可は引き続き`groupPolicy`、`groups`、`groupAllowFrom`、およびDM policy設定から行われます。 -## DMとルームのポリシー +## DMとルームポリシー ```json5 { @@ -809,22 +809,22 @@ Matrixは、取得した返信テキスト、スレッドルート、pending履 } ``` -メンション制御と許可リストの動作については、[Groups](/ja-JP/channels/groups)を参照してください。 +メンション制御とallowlistの動作については、[Groups](/ja-JP/channels/groups)を参照してください。 -Matrix DMのペアリング例: +Matrix DMのpairing例: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -未承認のMatrixユーザーが承認前に何度もメッセージを送ってきた場合、OpenClawは同じ保留中のペアリングコードを再利用し、短いクールダウン後に新しいコードを発行する代わりにリマインダー返信を再送することがあります。 +未承認のMatrixユーザーが承認前に繰り返しメッセージを送ってきた場合、OpenClawは同じ保留中のpairing codeを再利用し、新しいコードを発行する代わりに、短いクールダウン後に再度リマインダー返信を送ることがあります。 -共通のDMペアリングフローとストレージレイアウトについては、[Pairing](/ja-JP/channels/pairing)を参照してください。 +共有のDM pairingフローと保存レイアウトについては、[Pairing](/ja-JP/channels/pairing)を参照してください。 -## 直接ルーム修復 +## ダイレクトルーム修復 -ダイレクトメッセージ状態が同期ずれすると、OpenClawは古いソロルームを指す古い`m.direct`マッピングを保持し、実際のDMを指さなくなることがあります。相手に対する現在のマッピングを調べるには: +ダイレクトメッセージ状態の同期が崩れると、OpenClawがライブDMではなく古い単独ルームを指す古い`m.direct`マッピングを保持してしまうことがあります。相手の現在のマッピングを確認するには、次を実行します: ```bash openclaw matrix direct inspect --user-id @alice:example.org @@ -836,18 +836,18 @@ openclaw matrix direct inspect --user-id @alice:example.org openclaw matrix direct repair --user-id @alice:example.org ``` -修復フローは次のように動作します: +修復フロー: -- すでに`m.direct`にマップされている厳格な1対1 DMを優先する -- それがなければ、そのユーザーとの現在参加中の厳格な1対1 DMにフォールバックする -- 正常なDMが存在しない場合は、新しいダイレクトルームを作成して`m.direct`を書き換える +- `m.direct`にすでにマッピングされている厳密な1:1 DMを優先する +- それがない場合、そのユーザーとの現在参加中の厳密な1:1 DMにフォールバックする +- 健全なDMが存在しない場合は、新しいダイレクトルームを作成して`m.direct`を書き換える -修復フローは古いルームを自動削除しません。正常なDMを選択してマッピングを更新するだけなので、新しいMatrix送信、検証通知、その他のダイレクトメッセージフローが再び正しいルームを対象にするようになります。 +修復フローは古いルームを自動削除しません。健全なDMを選び、新しいMatrix送信、検証通知、その他のダイレクトメッセージフローが再び正しいルームを対象にするよう、マッピングを更新するだけです。 ## Exec承認 Matrixは、Matrixアカウントのネイティブ承認クライアントとして機能できます。ネイティブの -DM/チャネルルーティングのノブは、引き続きexec承認設定の下にあります: +DM/チャネルルーティング設定は、引き続きexec approval configの下にあります: - `channels.matrix.execApprovals.enabled` - `channels.matrix.execApprovals.approvers`（任意。`channels.matrix.dm.allowFrom`にフォールバック） @@ -855,38 +855,38 @@ DM/チャネルルーティングのノブは、引き続きexec承認設定の - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -承認者は`@owner:example.org`のようなMatrix user IDである必要があります。Matrixは、`enabled`が未設定または`"auto"`で、少なくとも1人の承認者を解決できる場合にネイティブ承認を自動有効化します。Exec承認は最初に`execApprovals.approvers`を使用し、`channels.matrix.dm.allowFrom`にフォールバックできます。プラグイン承認は`channels.matrix.dm.allowFrom`経由で認可されます。Matrixをネイティブ承認クライアントとして明示的に無効化するには、`enabled: false`を設定してください。それ以外の場合、承認リクエストは他の設定済み承認経路または承認フォールバックポリシーにフォールバックします。 +承認者は`@owner:example.org`のようなMatrix user IDである必要があります。`enabled`が未設定または`"auto"`で、少なくとも1人の承認者を解決できる場合、Matrixはネイティブ承認を自動有効化します。Exec承認は最初に`execApprovals.approvers`を使用し、`channels.matrix.dm.allowFrom`にフォールバックできます。Plugin承認は`channels.matrix.dm.allowFrom`を通じて認可されます。Matrixをネイティブ承認クライアントとして明示的に無効化するには、`enabled: false`を設定してください。そうしない場合、承認要求は他の設定済み承認ルートまたは承認フォールバックポリシーにフォールバックします。 -Matrixのネイティブルーティングは両方の承認種別をサポートします: +Matrixネイティブルーティングは両方の承認種別をサポートします: -- `channels.matrix.execApprovals.*`は、Matrix承認プロンプトのネイティブDM/チャネルファンアウトモードを制御します。 -- Exec承認は、`execApprovals.approvers`または`channels.matrix.dm.allowFrom`から取得したexec承認者セットを使用します。 -- プラグイン承認は、`channels.matrix.dm.allowFrom`のMatrix DM許可リストを使用します。 -- Matrixのリアクションショートカットとメッセージ更新は、exec承認とプラグイン承認の両方に適用されます。 +- `channels.matrix.execApprovals.*`は、Matrix承認プロンプトのネイティブDM/チャネルfanoutモードを制御します。 +- Exec承認は、`execApprovals.approvers`または`channels.matrix.dm.allowFrom`からexec approver setを使用します。 +- Plugin承認は、`channels.matrix.dm.allowFrom`のMatrix DM allowlistを使用します。 +- Matrixリアクションショートカットとメッセージ更新は、exec承認とPlugin承認の両方に適用されます。 配信ルール: -- `target: "dm"`は承認プロンプトを承認者のDMに送信します -- `target: "channel"`はプロンプトを発信元のMatrixルームまたはDMに送り返します -- `target: "both"`は承認者のDMと発信元のMatrixルームまたはDMの両方に送信します +- `target: "dm"`は、承認プロンプトを承認者のDMに送信します +- `target: "channel"`は、プロンプトを発信元のMatrixルームまたはDMに送り返します +- `target: "both"`は、承認者のDMと発信元のMatrixルームまたはDMの両方に送信します -Matrix承認プロンプトは、主たる承認メッセージにリアクションショートカットを設定します: +Matrix承認プロンプトは、主要な承認メッセージにリアクションショートカットを設定します: - `✅` = 1回だけ許可 - `❌` = 拒否 -- `♾️` = 有効なexecポリシーでその判断が許可されている場合は常に許可 +- `♾️` = 実効exec policyでその決定が許可されている場合は常に許可 -承認者はそのメッセージにリアクションするか、フォールバックのスラッシュコマンド `/approve allow-once`、`/approve allow-always`、または`/approve deny`を使用できます。 +承認者はそのメッセージにリアクションするか、フォールバックのスラッシュコマンド`/approve allow-once`、`/approve allow-always`、または`/approve deny`を使用できます。 -許可または拒否できるのは、解決済みの承認者のみです。exec承認では、チャネル配信にコマンドテキストが含まれるため、`channel`または`both`は信頼できるルームでのみ有効にしてください。 +承認または拒否できるのは、解決済みの承認者だけです。Exec承認では、チャネル配信にコマンドテキストが含まれるため、`channel`または`both`は信頼されたルームでのみ有効にしてください。 -アカウント単位の上書き: +アカウントごとのoverride: - `channels.matrix.accounts..execApprovals` 関連ドキュメント: [Exec approvals](/ja-JP/tools/exec-approvals) -## 複数アカウント +## マルチアカウント ```json5 { @@ -916,21 +916,22 @@ Matrix承認プロンプトは、主たる承認メッセージにリアクシ } ``` -トップレベルの`channels.matrix`値は、アカウントが上書きしない限り、名前付きアカウントのデフォルトとして機能します。 -継承されたルーム項目は`groups..account`で1つのMatrixアカウントに絞り込めます。 -`account`なしの項目はすべてのMatrixアカウントで共有されたままで、`account: "default"`の項目はデフォルトアカウントがトップレベルの`channels.matrix.*`に直接設定されている場合でも引き続き機能します。 -共有認証デフォルトが部分的にあるだけでは、それ自体で別の暗黙のデフォルトアカウントは作成されません。OpenClawがトップレベルの`default`アカウントを合成するのは、そのデフォルトに新しい認証情報（`homeserver` + `accessToken`、または`homeserver` + `userId`と`password`）がある場合のみです。名前付きアカウントは、後でキャッシュ済み認証情報が認証条件を満たす場合、`homeserver` + `userId`だけでも引き続き検出可能なままにできます。 -Matrixにすでに名前付きアカウントがちょうど1つある場合、または`defaultAccount`が既存の名前付きアカウントキーを指している場合、単一アカウントから複数アカウントへの修復/セットアップ昇格では、新しい`accounts.default`項目を作成する代わりにそのアカウントが保持されます。昇格されたアカウントに移動するのはMatrix認証/bootstrapキーのみで、共有配信ポリシーキーはトップレベルに残ります。 -暗黙のルーティング、プローブ、CLI操作で1つの名前付きMatrixアカウントを優先したい場合は、`defaultAccount`を設定してください。 -複数の名前付きアカウントを設定している場合は、暗黙のアカウント選択に依存するCLIコマンドのために`defaultAccount`を設定するか、`--account `を渡してください。 -1つのコマンドだけでその暗黙の選択を上書きしたい場合は、`openclaw matrix verify ...`と`openclaw matrix devices ...`に`--account `を渡してください。 +トップレベルの`channels.matrix`の値は、アカウント側でoverrideされない限り、名前付きアカウントのデフォルトとして機能します。 +継承されたルームエントリは、`groups..account`で1つのMatrixアカウントにスコープできます。 +`account`のないエントリはすべてのMatrixアカウント間で共有されたままとなり、`account: "default"`を持つエントリは、デフォルトアカウントがトップレベルの`channels.matrix.*`に直接設定されている場合にも引き続き機能します。 +共有された部分的な認証デフォルトだけでは、それ自体で別個の暗黙のデフォルトアカウントは作成されません。OpenClawがトップレベルの`default`アカウントを合成するのは、そのデフォルトに新しい認証情報（`homeserver` + `accessToken`、または`homeserver` + `userId` + `password`）がある場合のみです。名前付きアカウントは、後でキャッシュ済み認証情報が認証要件を満たすなら、`homeserver` + `userId`から引き続き検出可能なままにできます。 +Matrixにすでにちょうど1つの名前付きアカウントがある場合、または`defaultAccount`が既存の名前付きアカウントキーを指している場合、単一アカウントからマルチアカウントへの修復/セットアップ昇格では、新しい`accounts.default`エントリを作成する代わりにそのアカウントが保持されます。昇格されたアカウントに移動するのはMatrix認証/bootstrapキーのみで、共有配信ポリシーキーはトップレベルに残ります。 +OpenClawに暗黙のルーティング、プローブ、CLI操作で1つの名前付きMatrixアカウントを優先させたい場合は、`defaultAccount`を設定してください。 +複数のMatrixアカウントが設定されていて、そのうち1つのアカウントIDが`default`である場合、`defaultAccount`が未設定でもOpenClawはそのアカウントを暗黙的に使用します。 +複数の名前付きアカウントを設定する場合は、暗黙のアカウント選択に依存するCLIコマンドのために`defaultAccount`を設定するか、`--account `を渡してください。 +1つのコマンドだけでその暗黙選択を上書きしたい場合は、`openclaw matrix verify ...`と`openclaw matrix devices ...`に`--account `を渡してください。 -共通の複数アカウントパターンについては、[Configuration reference](/ja-JP/gateway/configuration-reference#multi-account-all-channels)を参照してください。 +共有のマルチアカウントパターンについては、[Configuration reference](/ja-JP/gateway/configuration-reference#multi-account-all-channels)を参照してください。 -## プライベート/LAN homeserver +## Private/LAN homeserver -デフォルトでは、OpenClawはSSRF保護のため、プライベート/内部のMatrix homeserverを -アカウント単位で明示的にオプトインしない限りブロックします。 +デフォルトでは、OpenClawはSSRF保護のため、private/internal Matrix homeserverをブロックします。 +明示的にアカウントごとにオプトインした場合のみ許可されます。 homeserverがlocalhost、LAN/Tailscale IP、または内部ホスト名で動作している場合は、そのMatrixアカウントで `network.dangerouslyAllowPrivateNetwork`を有効にしてください: @@ -959,12 +960,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -このオプトインは、信頼できるプライベート/内部ターゲットのみを許可します。`http://matrix.example.org:8008`のような +このオプトインは、信頼されたprivate/internalターゲットのみを許可します。`http://matrix.example.org:8008`のような 公開クリアテキストhomeserverは引き続きブロックされます。可能な限り`https://`を推奨します。 ## Matrixトラフィックのプロキシ -Matrix環境で明示的な送信HTTP(S)プロキシが必要な場合は、`channels.matrix.proxy`を設定します: +Matrixデプロイで明示的な送信HTTP(S)プロキシが必要な場合は、`channels.matrix.proxy`を設定してください: ```json5 { @@ -978,12 +979,12 @@ Matrix環境で明示的な送信HTTP(S)プロキシが必要な場合は、`cha } ``` -名前付きアカウントは、`channels.matrix.accounts..proxy`でトップレベルのデフォルトを上書きできます。 -OpenClawは、ランタイムのMatrixトラフィックとアカウント状態プローブの両方に同じプロキシ設定を使用します。 +名前付きアカウントは、`channels.matrix.accounts..proxy`でトップレベルのデフォルトをoverrideできます。 +OpenClawは、ランタイムのMatrixトラフィックとアカウントステータスのプローブの両方で同じプロキシ設定を使用します。 ## ターゲット解決 -Matrixは、OpenClawがルームまたはユーザーターゲットを求めるあらゆる場所で、次のターゲット形式を受け付けます: +Matrixは、OpenClawがルームまたはユーザーのターゲットを求めるすべての場所で、次のターゲット形式を受け付けます: - ユーザー: `@user:server`、`user:@user:server`、または`matrix:user:@user:server` - ルーム: `!room:server`、`room:!room:server`、または`matrix:room:!room:server` @@ -991,73 +992,73 @@ Matrixは、OpenClawがルームまたはユーザーターゲットを求める ライブディレクトリ検索は、ログイン済みのMatrixアカウントを使用します: -- ユーザー検索は、そのhomeserverのMatrixユーザーディレクトリを問い合わせます。 -- ルーム検索は、明示的なルームIDとエイリアスを直接受け付け、その後そのアカウントで参加中のルーム名検索にフォールバックします。 -- 参加中ルーム名検索はベストエフォートです。ルーム名をIDまたはエイリアスに解決できない場合、ランタイム許可リスト解決で無視されます。 +- ユーザー検索は、そのhomeserver上のMatrixユーザーディレクトリに問い合わせます。 +- ルーム検索は、明示的なルームIDとエイリアスをそのまま受け付け、その後そのアカウントの参加済みルーム名の検索にフォールバックします。 +- 参加済みルーム名検索はベストエフォートです。ルーム名をIDまたはエイリアスに解決できない場合、ランタイムのallowlist解決で無視されます。 ## 設定リファレンス -- `enabled`: チャネルを有効化または無効化します。 -- `name`: アカウントの任意ラベルです。 -- `defaultAccount`: 複数のMatrixアカウントが設定されている場合の優先アカウントIDです。 +- `enabled`: チャネルを有効または無効にします。 +- `name`: アカウントの任意ラベル。 +- `defaultAccount`: 複数のMatrixアカウントが設定されている場合の優先アカウントID。 - `homeserver`: homeserver URL。例: `https://matrix.example.org`。 -- `network.dangerouslyAllowPrivateNetwork`: このMatrixアカウントがプライベート/内部homeserverに接続できるようにします。homeserverが`localhost`、LAN/Tailscale IP、または`matrix-synapse`のような内部ホストに解決される場合に有効化してください。 -- `proxy`: Matrixトラフィック用の任意のHTTP(S)プロキシURLです。名前付きアカウントは独自の`proxy`でトップレベルのデフォルトを上書きできます。 +- `network.dangerouslyAllowPrivateNetwork`: このMatrixアカウントがprivate/internal homeserverに接続できるようにします。homeserverが`localhost`、LAN/Tailscale IP、または`matrix-synapse`のような内部ホストに解決される場合に有効にしてください。 +- `proxy`: Matrixトラフィック用の任意のHTTP(S)プロキシURL。名前付きアカウントは独自の`proxy`でトップレベルのデフォルトをoverrideできます。 - `userId`: 完全なMatrix user ID。例: `@bot:example.org`。 -- `accessToken`: トークンベース認証用のaccess tokenです。平文値とSecretRef値の両方が、env/file/execプロバイダー全体で`channels.matrix.accessToken`および`channels.matrix.accounts..accessToken`に対応しています。[Secrets Management](/ja-JP/gateway/secrets)を参照してください。 -- `password`: パスワードベースログイン用のpasswordです。平文値とSecretRef値の両方がサポートされます。 -- `deviceId`: 明示的なMatrix device IDです。 -- `deviceName`: パスワードログイン用のデバイス表示名です。 -- `avatarUrl`: プロファイル同期と`profile set`更新用に保存されるself-avatar URLです。 -- `initialSyncLimit`: 起動時syncで取得するイベントの最大数です。 +- `accessToken`: トークンベース認証用のaccess token。プレーンテキスト値とSecretRef値は、env/file/exec provider全体で`channels.matrix.accessToken`および`channels.matrix.accounts..accessToken`に対してサポートされます。[Secrets Management](/ja-JP/gateway/secrets)を参照してください。 +- `password`: パスワードベースログイン用のpassword。プレーンテキスト値とSecretRef値がサポートされます。 +- `deviceId`: 明示的なMatrix device ID。 +- `deviceName`: パスワードログイン用のデバイス表示名。 +- `avatarUrl`: プロファイル同期および`profile set`更新用の保存済みself-avatar URL。 +- `initialSyncLimit`: 起動時sync中に取得されるイベントの最大数。 - `encryption`: E2EEを有効にします。 -- `allowlistOnly`: `true`の場合、`open`ルームポリシーを`allowlist`に昇格し、`disabled`以外のすべての有効なDMポリシー（`pairing`と`open`を含む）を`allowlist`に強制します。`disabled`ポリシーには影響しません。 +- `allowlistOnly`: `true`の場合、`open`ルームポリシーを`allowlist`に昇格し、`disabled`以外のすべてのアクティブなDM policy（`pairing`および`open`を含む）を`allowlist`に強制します。`disabled`ポリシーには影響しません。 - `allowBots`: 他の設定済みOpenClaw Matrixアカウントからのメッセージを許可します（`true`または`"mentions"`）。 - `groupPolicy`: `open`、`allowlist`、または`disabled`。 -- `contextVisibility`: 補足ルームコンテキストの可視性モード（`all`、`allowlist`、`allowlist_quote`）。 -- `groupAllowFrom`: ルームトラフィック用のuser ID許可リストです。項目は完全なMatrix user IDにしてください。未解決の名前はランタイムで無視されます。 -- `historyLimit`: グループ履歴コンテキストとして含めるルームメッセージの最大数です。`messages.groupChat.historyLimit`にフォールバックし、両方とも未設定の場合の実効デフォルトは`0`です。無効にするには`0`を設定してください。 +- `contextVisibility`: 補助的なルームコンテキストの可視性モード（`all`、`allowlist`、`allowlist_quote`）。 +- `groupAllowFrom`: ルームトラフィック用のallowlist user ID。エントリは完全なMatrix user IDにしてください。未解決の名前は実行時に無視されます。 +- `historyLimit`: グループ履歴コンテキストとして含めるルームメッセージの最大数。`messages.groupChat.historyLimit`にフォールバックし、両方とも未設定の場合、実効デフォルトは`0`です。無効化するには`0`を設定してください。 - `replyToMode`: `off`、`first`、`all`、または`batched`。 -- `markdown`: 送信Matrixテキスト用の任意のMarkdownレンダリング設定です。 -- `streaming`: `off`（デフォルト）、`"partial"`、`"quiet"`、`true`、または`false`。`"partial"`と`true`は、通常のMatrixテキストメッセージでプレビュー優先のドラフト更新を有効にします。`"quiet"`は、自己ホスト型プッシュルール構成向けの通知なしプレビュー通知を使用します。`false`は`"off"`と同等です。 -- `blockStreaming`: `true`で、ドラフトプレビューストリーミングが有効な間、完了したassistantブロックの別個の進行状況メッセージを有効にします。 +- `markdown`: 送信Matrixテキスト用の任意のMarkdownレンダリング設定。 +- `streaming`: `off`（デフォルト）、`"partial"`、`"quiet"`、`true`、または`false`。`"partial"`と`true`は、通常のMatrixテキストメッセージによるプレビュー先行の下書き更新を有効にします。`"quiet"`は、セルフホストのpush-ruleセットアップ向けに通知しないプレビューノーティスを使用します。`false`は`"off"`と同等です。 +- `blockStreaming`: `true`は、下書きプレビューのストリーミングが有効な間、完了したassistantブロックごとに個別の進捗メッセージを有効にします。 - `threadReplies`: `off`、`inbound`、または`always`。 -- `threadBindings`: スレッドにbindされたセッションルーティングとライフサイクルのチャネル単位上書きです。 -- `startupVerification`: 起動時の自動自己検証リクエストモード（`if-unverified`、`off`）。 -- `startupVerificationCooldownHours`: 自動起動時検証リクエストを再試行するまでのクールダウンです。 -- `textChunkLimit`: 送信メッセージの文字数単位チャンクサイズ（`chunkMode`が`length`のときに適用）。 -- `chunkMode`: `length`は文字数でメッセージを分割し、`newline`は改行境界で分割します。 -- `responsePrefix`: このチャネルのすべての送信返信の前に付加される任意の文字列です。 -- `ackReaction`: このチャネル/アカウント用の任意のackリアクション上書きです。 -- `ackReactionScope`: 任意のackリアクションスコープ上書き（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 +- `threadBindings`: スレッドにbindingされたセッションルーティングとライフサイクルに対するチャネルごとのoverride。 +- `startupVerification`: 起動時の自動自己検証要求モード（`if-unverified`、`off`）。 +- `startupVerificationCooldownHours`: 起動時の自動検証要求を再試行する前のクールダウン時間。 +- `textChunkLimit`: 送信メッセージの文字数ベースのチャンクサイズ（`chunkMode`が`length`の場合に適用）。 +- `chunkMode`: `length`はメッセージを文字数で分割し、`newline`は行境界で分割します。 +- `responsePrefix`: このチャネルのすべての送信返信の前に付加される任意の文字列。 +- `ackReaction`: このチャネル/アカウント用の任意のackリアクションoverride。 +- `ackReactionScope`: 任意のackリアクションスコープoverride（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 - `reactionNotifications`: 受信リアクション通知モード（`own`、`off`）。 -- `mediaMaxMb`: 送信と受信メディア処理用のメディアサイズ上限（MB）。 -- `autoJoin`: 招待自動参加ポリシー（`always`、`allowlist`、`off`）。デフォルト: `off`。DM形式の招待を含むすべてのMatrix招待に適用されます。 -- `autoJoinAllowlist`: `autoJoin`が`allowlist`のときに許可されるルーム/エイリアス。エイリアス項目は招待処理中にルームIDに解決されます。OpenClawは、招待されたルームが主張するエイリアス状態を信頼しません。 -- `dm`: DMポリシーブロック（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 -- `dm.policy`: OpenClawがルームに参加し、それをDMとして分類した後のDMアクセスを制御します。招待が自動参加されるかどうかは変更しません。 -- `dm.allowFrom`: ライブディレクトリ検索ですでに解決済みでない限り、項目は完全なMatrix user IDにしてください。 -- `dm.sessionScope`: `per-user`（デフォルト）または`per-room`。相手が同じでも各Matrix DMルームで別個のコンテキストを保持したい場合は`per-room`を使用します。 -- `dm.threadReplies`: DM専用のスレッドポリシー上書き（`off`、`inbound`、`always`）。これは、DMにおける返信配置とセッション分離の両方について、トップレベルの`threadReplies`設定を上書きします。 +- `mediaMaxMb`: 送信と受信メディア処理におけるメディアサイズ上限（MB）。 +- `autoJoin`: 招待への自動参加ポリシー（`always`、`allowlist`、`off`）。デフォルト: `off`。DM形式の招待を含むすべてのMatrix招待に適用されます。 +- `autoJoinAllowlist`: `autoJoin`が`allowlist`のときに許可されるルーム/エイリアス。エイリアスエントリは招待処理中にルームIDへ解決されます。OpenClawは、招待されたルームが主張するエイリアス状態を信頼しません。 +- `dm`: DM policyブロック（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 +- `dm.policy`: OpenClawがルームに参加し、それをDMとして分類した後のDMアクセスを制御します。招待に自動参加するかどうかは変更しません。 +- `dm.allowFrom`: ライブディレクトリ検索で解決済みでない限り、エントリは完全なMatrix user IDにしてください。 +- `dm.sessionScope`: `per-user`（デフォルト）または`per-room`。相手が同じでも各Matrix DMルームに別々のコンテキストを持たせたい場合は`per-room`を使用してください。 +- `dm.threadReplies`: DM専用のスレッドポリシーoverride（`off`、`inbound`、`always`）。DMにおける返信配置とセッション分離の両方について、トップレベルの`threadReplies`設定をoverrideします。 - `execApprovals`: Matrixネイティブのexec承認配信（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 -- `execApprovals.approvers`: execリクエストを承認できるMatrix user ID。`dm.allowFrom`ですでに承認者を特定できる場合は任意です。 +- `execApprovals.approvers`: exec要求を承認できるMatrix user ID。`dm.allowFrom`がすでに承認者を特定している場合は任意です。 - `execApprovals.target`: `dm | channel | both`（デフォルト: `dm`）。 -- `accounts`: 名前付きアカウント単位の上書き。トップレベルの`channels.matrix`値はこれらの項目のデフォルトとして機能します。 -- `groups`: ルーム単位のポリシーマップ。ルームIDまたはエイリアスを推奨します。未解決のルーム名はランタイムで無視されます。セッション/グループidentityは、解決後の安定したルームIDを使用します。 -- `groups..account`: 複数アカウント構成で、継承された1つのルーム項目を特定のMatrixアカウントに制限します。 -- `groups..allowBots`: 設定済みボット送信者用のルームレベル上書き（`true`または`"mentions"`）。 -- `groups..users`: ルーム単位の送信者許可リスト。 -- `groups..tools`: ルーム単位のツール許可/拒否上書き。 -- `groups..autoReply`: ルームレベルのメンション制御上書き。`true`でそのルームのメンション必須を無効にし、`false`で再び有効にします。 -- `groups..skills`: 任意のルームレベルSkillsフィルター。 +- `accounts`: 名前付きのアカウントごとのoverride。トップレベルの`channels.matrix`値はこれらのエントリのデフォルトとして機能します。 +- `groups`: ルームごとのポリシーマップ。ルームIDまたはエイリアスを推奨します。未解決のルーム名は実行時に無視されます。セッション/グループIDには、解決後の安定したルームIDが使用されます。 +- `groups..account`: マルチアカウント構成で、1つの継承ルームエントリを特定のMatrixアカウントに限定します。 +- `groups..allowBots`: 設定済みボット送信者に対するルームレベルoverride（`true`または`"mentions"`）。 +- `groups..users`: ルームごとの送信者allowlist。 +- `groups..tools`: ルームごとのtool許可/拒否override。 +- `groups..autoReply`: ルームレベルのメンション制御override。`true`はそのルームのメンション必須を無効にし、`false`は再び有効にします。 +- `groups..skills`: 任意のルームレベルskill filter。 - `groups..systemPrompt`: 任意のルームレベルsystem promptスニペット。 - `rooms`: `groups`のレガシーエイリアス。 -- `actions`: アクション単位のツール制御（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 +- `actions`: アクションごとのtool制御（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 ## 関連 - [Channels Overview](/ja-JP/channels) — サポートされているすべてのチャネル -- [Pairing](/ja-JP/channels/pairing) — DM認証とペアリングフロー +- [Pairing](/ja-JP/channels/pairing) — DM認証とpairingフロー - [Groups](/ja-JP/channels/groups) — グループチャットの動作とメンション制御 - [Channel Routing](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング - [Security](/ja-JP/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/concepts/dreaming.md b/docs/ja-JP/concepts/dreaming.md index 8dfa0ab2f..3ee46a4af 100644 --- a/docs/ja-JP/concepts/dreaming.md +++ b/docs/ja-JP/concepts/dreaming.md @@ -1,35 +1,34 @@ --- read_when: - - メモリ昇格を自動的に実行したい - - 各 dreaming フェーズの役割を理解したい - - '`MEMORY.md`を汚さずに統合を調整したい' -summary: Light、Deep、REMフェーズとDream Diaryを備えたバックグラウンドメモリ統合 + - メモリの昇格を自動的に実行したい場合 + - 各Dreamingフェーズが何をするのかを理解したい場合 + - MEMORY.mdを汚さずに統合を調整したい場合 +summary: 軽い、深い、REMの各フェーズに加え、Dream Diaryを備えたバックグラウンドメモリ統合 title: Dreaming（実験的） x-i18n: - generated_at: "2026-04-09T01:27:52Z" + generated_at: "2026-04-15T04:43:33Z" model: gpt-5.4 provider: openai - source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef + source_hash: 5882a5068f2eabe54ca9893184e5385330a432b921870c38626399ce11c31e25 source_path: concepts/dreaming.md workflow: 15 --- # Dreaming（実験的） -Dreamingは、`memory-core`のバックグラウンドメモリ統合システムです。 -これによりOpenClawは、プロセスを説明可能かつレビュー可能な状態に保ちながら、 -強い短期シグナルを永続的なメモリへ移動できます。 +Dreamingは、`memory-core` におけるバックグラウンドメモリ統合システムです。 +これにより、OpenClawは説明可能かつレビュー可能な形で、強い短期シグナルを永続的なメモリへ移すことができます。 Dreamingは**オプトイン**で、デフォルトでは無効です。 -## Dreamingが書き込む内容 +## Dreamingが書き込むもの Dreamingは2種類の出力を保持します。 -- `memory/.dreams/`内の**マシン状態**（リコールストア、フェーズシグナル、取り込みチェックポイント、ロック）。 -- `DREAMS.md`（または既存の`dreams.md`）内の**人が読める出力**と、`memory/dreaming//YYYY-MM-DD.md`配下の任意のフェーズレポートファイル。 +- `memory/.dreams/` 内の**マシン状態**（recall store、フェーズシグナル、取り込みチェックポイント、ロック）。 +- `DREAMS.md`（または既存の `dreams.md`）内の**人間が読める出力**と、`memory/dreaming//YYYY-MM-DD.md` 配下の任意のフェーズレポートファイル。 -長期メモリへの昇格は、引き続き`MEMORY.md`にのみ書き込まれます。 +長期プロモーションは引き続き `MEMORY.md` にのみ書き込みます。 ## フェーズモデル @@ -37,93 +36,85 @@ Dreamingは、協調して動作する3つのフェーズを使用します。 | フェーズ | 目的 | 永続的な書き込み | | ----- | ----------------------------------------- | ----------------- | -| Light | 最近の短期素材を整理して段階化する | いいえ | -| Deep | 永続化候補をスコアリングして昇格する | はい（`MEMORY.md`） | -| REM | テーマと繰り返し現れる考えを振り返る | いいえ | +| Light | 最近の短期マテリアルを分類してステージする | なし | +| Deep | 永続化候補をスコアリングして昇格する | あり（`MEMORY.md`） | +| REM | テーマと繰り返し現れるアイデアを振り返る | なし | -これらのフェーズは内部実装の詳細であり、ユーザーが別々に設定する -「モード」ではありません。 +これらのフェーズは内部実装の詳細であり、ユーザーが個別に設定する「モード」ではありません。 ### Lightフェーズ -Lightフェーズは、最近の日次メモリシグナルとリコールトレースを取り込み、 -重複を排除し、候補行を段階化します。 +Lightフェーズは、最近の日次メモリシグナルとrecallトレースを取り込み、それらを重複排除して候補行をステージします。 -- 利用可能な場合は、短期リコール状態、最近の日次メモリファイル、マスク済みセッショントランスクリプトから読み取ります。 -- ストレージにインライン出力が含まれる場合、管理された`## Light Sleep`ブロックを書き込みます。 -- 後続のDeepランキングのための強化シグナルを記録します。 -- `MEMORY.md`には決して書き込みません。 +- 利用可能な場合、短期recall状態、最近の日次メモリファイル、伏せ字化されたセッショントランスクリプトから読み取ります。 +- ストレージにインライン出力が含まれる場合、管理された `## Light Sleep` ブロックを書き込みます。 +- 後のDeepランキングのために強化シグナルを記録します。 +- `MEMORY.md` には決して書き込みません。 ### Deepフェーズ -Deepフェーズは、何を長期メモリにするかを決定します。 +Deepフェーズは、何が長期メモリになるかを決定します。 -- 重み付きスコアリングとしきい値ゲートを使って候補を順位付けします。 -- 通過には`minScore`、`minRecallCount`、`minUniqueQueries`が必要です。 -- 書き込む前にライブの日次ファイルからスニペットを再取得するため、古くなったスニペットや削除されたスニペットはスキップされます。 -- 昇格したエントリを`MEMORY.md`に追記します。 -- `DREAMS.md`に`## Deep Sleep`サマリーを書き込み、必要に応じて`memory/dreaming/deep/YYYY-MM-DD.md`にも書き込みます。 +- 重み付きスコアリングとしきい値ゲートを使って候補をランキングします。 +- `minScore`、`minRecallCount`、`minUniqueQueries` をすべて満たす必要があります。 +- 書き込み前にライブの日次ファイルからスニペットを再取得するため、古いスニペットや削除済みスニペットはスキップされます。 +- 昇格したエントリを `MEMORY.md` に追記します。 +- `DREAMS.md` に `## Deep Sleep` サマリーを書き込み、必要に応じて `memory/dreaming/deep/YYYY-MM-DD.md` にも書き込みます。 ### REMフェーズ REMフェーズは、パターンと内省的シグナルを抽出します。 -- 最近の短期トレースからテーマと内省のサマリーを構築します。 -- ストレージにインライン出力が含まれる場合、管理された`## REM Sleep`ブロックを書き込みます。 -- Deepランキングで使用されるREM強化シグナルを記録します。 -- `MEMORY.md`には決して書き込みません。 +- 最近の短期トレースからテーマと振り返りサマリーを構築します。 +- ストレージにインライン出力が含まれる場合、管理された `## REM Sleep` ブロックを書き込みます。 +- Deepランキングで使われるREM強化シグナルを記録します。 +- `MEMORY.md` には決して書き込みません。 ## セッショントランスクリプトの取り込み -Dreamingは、マスク済みセッショントランスクリプトをDreamingコーパスに取り込めます。 -トランスクリプトが利用可能な場合、それらは日次メモリシグナルやリコールトレースとともに -Lightフェーズに投入されます。個人的な内容や機微な内容は、取り込み前にマスクされます。 +Dreamingは、伏せ字化されたセッショントランスクリプトをDreamingコーパスに取り込むことができます。 +トランスクリプトが利用可能な場合、それらは日次メモリシグナルやrecallトレースとともにLightフェーズへ入力されます。個人的な内容や機微な内容は、取り込み前に伏せ字化されます。 ## Dream Diary -Dreamingはまた、`DREAMS.md`内に物語形式の**Dream Diary**を保持します。 -各フェーズに十分な素材がそろうと、`memory-core`はベストエフォートのバックグラウンド -subagentターン（デフォルトのランタイムモデルを使用）を実行し、短い日記エントリを追記します。 +Dreamingは、`DREAMS.md` に物語形式の**Dream Diary**も保持します。 +各フェーズに十分な材料がそろうと、`memory-core` はベストエフォートのバックグラウンドsubagentターン（デフォルトのランタイムモデルを使用）を実行し、短い日記エントリを追記します。 -この日記はDreams UIで人が読むためのものであり、昇格ソースではありません。 +この日記はDreams UIで人間が読むためのものであり、プロモーション元ではありません。 +Dreamingによって生成された日記やレポートの成果物は、短期プロモーションの対象外です。`MEMORY.md` へ昇格できるのは、根拠のあるメモリスニペットだけです。 -レビューや復旧作業のために、根拠付きの履歴バックフィルレーンもあります。 +レビューや復旧作業のために、根拠付きの履歴バックフィル経路もあります。 -- `memory rem-harness --path ... --grounded`は、過去の`YYYY-MM-DD.md`ノートから根拠付きの日記出力をプレビューします。 -- `memory rem-backfill --path ...`は、可逆な根拠付き日記エントリを`DREAMS.md`に書き込みます。 -- `memory rem-backfill --path ... --stage-short-term`は、根拠付きの永続候補を、通常のDeepフェーズがすでに使っている短期エビデンスストアと同じ場所に段階化します。 -- `memory rem-backfill --rollback`と`--rollback-short-term`は、通常の日記エントリやライブ短期リコールに触れずに、それらの段階化されたバックフィル成果物を削除します。 +- `memory rem-harness --path ... --grounded` は、過去の `YYYY-MM-DD.md` ノートから生成される根拠付き日記出力をプレビューします。 +- `memory rem-backfill --path ...` は、元に戻せる根拠付き日記エントリを `DREAMS.md` に書き込みます。 +- `memory rem-backfill --path ... --stage-short-term` は、通常のDeepフェーズがすでに使用しているのと同じ短期エビデンスストアに、根拠付きの永続候補をステージします。 +- `memory rem-backfill --rollback` と `--rollback-short-term` は、通常の日記エントリやライブの短期recallには触れずに、それらのステージ済みバックフィル成果物を削除します。 -Control UIは同じ日記バックフィル/リセットフローを公開しているため、根拠付き候補が -昇格に値するか判断する前に、Dreamsシーンで結果を確認できます。Sceneには独立した -groundedレーンも表示されるため、どの段階化済み短期エントリが履歴リプレイ由来か、 -どの昇格済みアイテムがgrounded主導だったかを確認でき、通常のライブ短期状態には -触れずにgrounded専用の段階化済みエントリだけを消去できます。 +Control UIは同じ日記バックフィル／リセットフローを提供しているため、根拠付き候補が昇格に値するかを判断する前に、Dreamsシーンで結果を確認できます。 +このシーンは独立したgroundedレーンも表示し、どのステージ済み短期エントリが履歴リプレイ由来か、どの昇格済みアイテムがgrounded主導だったかを確認でき、通常のライブ短期状態に触れずにgrounded専用のステージ済みエントリだけをクリアできます。 ## Deepランキングシグナル -Deepランキングは、6つの重み付きベースシグナルに加えてフェーズ強化を使用します。 +Deepランキングは、6つの重み付き基本シグナルとフェーズ強化を使用します。 | シグナル | 重み | 説明 | | ------------------- | ------ | ------------------------------------------------- | -| 頻度 | 0.24 | そのエントリが蓄積した短期シグナルの数 | -| 関連性 | 0.30 | そのエントリの平均取得品質 | -| クエリ多様性 | 0.15 | それが現れた個別のクエリ/日コンテキスト | -| 新しさ | 0.15 | 時間減衰付きの鮮度スコア | -| 統合 | 0.10 | 複数日にわたる再出現の強さ | -| 概念的豊かさ | 0.06 | スニペット/パス由来の概念タグ密度 | +| 頻度 | 0.24 | エントリが蓄積した短期シグナルの数 | +| 関連性 | 0.30 | エントリの平均取得品質 | +| クエリ多様性 | 0.15 | そのエントリが現れた異なるクエリ／日コンテキスト | +| 新しさ | 0.15 | 時間減衰を考慮した鮮度スコア | +| 統合 | 0.10 | 複数日にまたがる再出現の強さ | +| 概念的豊かさ | 0.06 | スニペット／パスから得られる概念タグ密度 | -LightフェーズとREMフェーズのヒットは、 -`memory/.dreams/phase-signals.json`から小さな時間減衰付きブーストを追加します。 +LightフェーズとREMフェーズのヒットは、`memory/.dreams/phase-signals.json` から小さな時間減衰付きブーストを追加します。 ## スケジューリング -有効にすると、`memory-core`は完全なDreamingスイープ用のcronジョブを1つ自動管理します。 -各スイープは順番にフェーズを実行します: light -> REM -> deep。 +有効にすると、`memory-core` は完全なDreamingスイープのためのCronジョブを1つ自動管理します。各スイープは、light -> REM -> deep の順にフェーズを実行します。 デフォルトの実行間隔の動作: -| 設定 | デフォルト | +| 設定 | デフォルト | | -------------------- | ----------- | | `dreaming.frequency` | `0 3 * * *` | @@ -178,7 +169,7 @@ Dreamingを有効にする: ## CLIワークフロー -プレビューまたは手動適用には、CLI昇格を使用します。 +プレビューまたは手動適用にはCLIプロモーションを使用します。 ```bash openclaw memory promote @@ -187,17 +178,16 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -手動の`memory promote`は、CLIフラグで上書きしない限り、 -デフォルトでDeepフェーズのしきい値を使用します。 +手動の `memory promote` は、CLIフラグで上書きしない限り、デフォルトでDeepフェーズのしきい値を使用します。 -特定の候補が昇格する理由、または昇格しない理由を説明する: +特定の候補が昇格する、または昇格しない理由を説明する: ```bash openclaw memory promote-explain "router vlan" openclaw memory promote-explain "router vlan" --json ``` -何も書き込まずに、REMの内省、候補となる真実、Deep昇格の出力をプレビューする: +何も書き込まずに、REMの振り返り、候補の事実、Deepプロモーション出力をプレビューする: ```bash openclaw memory rem-harness @@ -206,29 +196,27 @@ openclaw memory rem-harness --json ## 主なデフォルト値 -すべての設定は`plugins.entries.memory-core.config.dreaming`の下にあります。 +すべての設定は `plugins.entries.memory-core.config.dreaming` 配下にあります。 -| キー | デフォルト | +| キー | デフォルト | | ----------- | ----------- | | `enabled` | `false` | | `frequency` | `0 3 * * *` | -フェーズポリシー、しきい値、ストレージ動作は内部実装の詳細であり、 -ユーザー向け設定ではありません。 +フェーズポリシー、しきい値、ストレージ動作は内部実装の詳細であり、ユーザー向け設定ではありません。 -完全なキー一覧は[メモリ設定リファレンス](/ja-JP/reference/memory-config#dreaming-experimental) -を参照してください。 +完全なキー一覧は、[メモリ設定リファレンス](/ja-JP/reference/memory-config#dreaming-experimental) を参照してください。 ## Dreams UI 有効にすると、Gatewayの**Dreams**タブには次が表示されます。 - 現在のDreaming有効状態 -- フェーズレベルのステータスと管理対象スイープの有無 -- 短期、grounded、シグナル、本日昇格済みの件数 -- 次回スケジュール実行の時刻 -- 段階化された履歴リプレイエントリ用の独立したgrounded Sceneレーン -- `doctor.memory.dreamDiary`に支えられた、展開可能なDream Diaryリーダー +- フェーズレベルの状態と管理対象スイープの有無 +- 短期、grounded、シグナル、本日昇格済みの各件数 +- 次回の予定実行時刻 +- ステージ済みの履歴リプレイエントリ用の独立したgroundedシーンレーン +- `doctor.memory.dreamDiary` を基盤とする展開可能なDream Diaryリーダー ## 関連 diff --git a/docs/ja-JP/gateway/local-models.md b/docs/ja-JP/gateway/local-models.md index 6c97af072..5e3680545 100644 --- a/docs/ja-JP/gateway/local-models.md +++ b/docs/ja-JP/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - 自分のGPUマシンからモデルを提供したい場合 - - LM StudioまたはOpenAI互換プロキシを設定している場合 + - LM StudioまたはOpenAI互換プロキシを接続している場合 - 最も安全なローカルモデルのガイダンスが必要な場合 summary: OpenClawをローカルLLM（LM Studio、vLLM、LiteLLM、カスタムOpenAIエンドポイント）で実行する title: ローカルモデル x-i18n: - generated_at: "2026-04-14T13:04:22Z" + generated_at: "2026-04-15T04:43:32Z" model: gpt-5.4 provider: openai - source_hash: 1544c522357ba4b18dfa6d05ea8d60c7c6262281b53863d9aee7002464703ca7 + source_hash: 8778cc1c623a356ff3cf306c494c046887f9417a70ec71e659e4a8aae912a780 source_path: gateway/local-models.md workflow: 15 --- # ローカルモデル -ローカル運用は可能ですが、OpenClawは大きなコンテキストと強力なプロンプトインジェクション耐性を前提としています。小規模なカードではコンテキストが切り詰められ、安全性も低下します。目標は高く設定してください: **最大構成のMac Studioを2台以上、または同等のGPUリグ（約$30k以上）**。単一の**24 GB** GPUで動かせるのは、より軽いプロンプトに限られ、レイテンシも高くなります。実行可能な中で**最大 / フルサイズのモデルバリアント**を使ってください。強く量子化された、または「small」なチェックポイントは、プロンプトインジェクションのリスクを高めます（[Security](/ja-JP/gateway/security)を参照）。 +ローカルでも運用は可能ですが、OpenClawは大きなコンテキストと、プロンプトインジェクションに対する強力な防御を前提としています。小規模なGPUカードではコンテキストが切り詰められ、安全性も低下します。目安としては、**最大構成のMac Studio 2台以上、または同等のGPUリグ（約3万ドル以上）** を推奨します。**24 GB** のGPU 1枚でも、より軽いプロンプトで高いレイテンシを許容すれば動作します。実行できる範囲で **最大級 / フルサイズのモデルバリアント** を使ってください。強く量子化されたものや「small」チェックポイントは、プロンプトインジェクションのリスクを高めます（[Security](/ja-JP/gateway/security)を参照）。 -最も手間の少ないローカルセットアップを望むなら、[LM Studio](/ja-JP/providers/lmstudio)または[Ollama](/ja-JP/providers/ollama)から始めて、`openclaw onboard`を実行してください。このページは、より高性能なローカルスタックやカスタムのOpenAI互換ローカルサーバー向けの、方針を明確にしたガイドです。 +最も手間の少ないローカルセットアップを求めるなら、まずは [LM Studio](/ja-JP/providers/lmstudio) または [Ollama](/ja-JP/providers/ollama) と `openclaw onboard` から始めてください。このページは、より高性能なローカル構成や、カスタムのOpenAI互換ローカルサーバー向けの、方針を明確にしたガイドです。 ## 推奨: LM Studio + 大規模ローカルモデル（Responses API） -現時点で最適なローカルスタックです。LM Studioに大規模モデル（たとえばフルサイズのQwen、DeepSeek、Llamaビルド）を読み込み、ローカルサーバー（デフォルトは`http://127.0.0.1:1234`）を有効にし、推論を最終テキストから分離するためにResponses APIを使用します。 +現時点で最良のローカル構成です。LM Studioで大規模モデル（たとえば、フルサイズのQwen、DeepSeek、Llamaビルド）を読み込み、ローカルサーバー（デフォルトでは `http://127.0.0.1:1234`）を有効にし、Responses APIを使って推論を最終テキストから分離します。 ```json5 { @@ -62,15 +62,15 @@ x-i18n: **セットアップチェックリスト** - LM Studioをインストール: [https://lmstudio.ai](https://lmstudio.ai) -- LM Studioで、**利用可能な中で最大のモデルビルド**をダウンロードし（「small」や強い量子化バリアントは避ける）、サーバーを起動して、`http://127.0.0.1:1234/v1/models`に一覧表示されることを確認します。 -- `my-local-model`を、LM Studioに表示されている実際のモデルIDに置き換えます。 -- モデルは読み込んだままにしてください。コールドロードは起動レイテンシを増やします。 -- LM Studioのビルドに応じて`contextWindow`と`maxTokens`を調整します。 -- WhatsAppでは、最終テキストだけが送信されるよう、Responses APIを使ってください。 +- LM Studioで、利用可能な **最大のモデルビルド** をダウンロードし（「small」や強い量子化バリアントは避ける）、サーバーを起動して、`http://127.0.0.1:1234/v1/models` に表示されることを確認します。 +- `my-local-model` を、LM Studioに表示される実際のモデルIDに置き換えます。 +- モデルは読み込んだままにしてください。コールドロードは起動時のレイテンシを増やします。 +- LM Studioのビルドに合わせて `contextWindow` / `maxTokens` を調整します。 +- WhatsAppでは、最終テキストのみが送信されるよう、Responses APIを使ってください。 -ローカル運用時でもホスト型モデルは設定しておいてください。`models.mode: "merge"`を使えば、フォールバックを利用可能なままにできます。 +ローカル実行時でもホスト型モデルは設定したままにしておき、フォールバックを利用できるよう `models.mode: "merge"` を使ってください。 -### ハイブリッド構成: ホスト型をプライマリ、ローカルをフォールバック +### ハイブリッド構成: ホスト型を主、ローカルをフォールバック ```json5 { @@ -111,18 +111,18 @@ x-i18n: } ``` -### ローカル優先、ホスト型をセーフティネットにする構成 +### ローカル優先、ホスト型を安全網として利用 -プライマリとフォールバックの順序を入れ替えてください。`providers`ブロックと`models.mode: "merge"`はそのまま維持し、ローカルマシンが停止しているときにSonnetやOpusへフォールバックできるようにします。 +主とフォールバックの順序を入れ替えてください。providersブロックと `models.mode: "merge"` はそのままにしておけば、ローカルマシンが停止したときにSonnetやOpusへフォールバックできます。 ### リージョナルホスティング / データルーティング -- ホスト型のMiniMax/Kimi/GLMバリアントは、リージョン固定エンドポイント（例: USホスト）付きでOpenRouter上にも存在します。そこでリージョナルバリアントを選べば、`models.mode: "merge"`を使ったAnthropic/OpenAIフォールバックを維持しながら、トラフィックを選択した法域内にとどめられます。 -- ローカル専用は依然として最も強いプライバシー手段です。ホスト型のリージョナルルーティングは、プロバイダー機能が必要だがデータフローも制御したい場合の中間的な選択肢です。 +- ホスト型のMiniMax/Kimi/GLMバリアントは、地域固定エンドポイント（たとえば米国ホスト）付きでOpenRouter上にも存在します。そこでリージョナルバリアントを選べば、`models.mode: "merge"` によるAnthropic/OpenAIフォールバックを維持しつつ、トラフィックを希望する法域内にとどめられます。 +- ローカル専用が最も強いプライバシー経路です。ホスト型のリージョナルルーティングは、プロバイダー機能は必要だがデータフローも制御したい場合の中間案です。 ## その他のOpenAI互換ローカルプロキシ -vLLM、LiteLLM、OAI-proxy、またはカスタムGatewayでも、OpenAI形式の`/v1`エンドポイントを公開していれば動作します。上記のプロバイダーブロックを、利用するエンドポイントとモデルIDに置き換えてください。 +vLLM、LiteLLM、OAI-proxy、またはカスタムGatewayは、OpenAI形式の `/v1` エンドポイントを公開していれば利用できます。上のproviderブロックを、あなたのエンドポイントとモデルIDに置き換えてください。 ```json5 { @@ -150,26 +150,37 @@ vLLM、LiteLLM、OAI-proxy、またはカスタムGatewayでも、OpenAI形式 } ``` -ホスト型モデルをフォールバックとして引き続き使えるように、`models.mode: "merge"`を維持してください。 +ホスト型モデルをフォールバックとして使い続けられるよう、`models.mode: "merge"` は維持してください。 -ローカル / プロキシされた`/v1`バックエンドの動作に関する注意: +ローカル / プロキシ経由の `/v1` バックエンドに関する動作メモ: -- OpenClawはこれらを、ネイティブなOpenAIエンドポイントではなく、プロキシ型のOpenAI互換ルートとして扱います -- ここではOpenAIネイティブ専用のリクエスト整形は適用されません: `service_tier`、Responsesの`store`、OpenAI reasoning互換ペイロード整形、プロンプトキャッシュヒントは使われません -- 隠しOpenClaw属性ヘッダー（`originator`、`version`、`User-Agent`）は、これらのカスタムプロキシURLには挿入されません +- OpenClawはこれらを、ネイティブな + OpenAIエンドポイントではなく、プロキシ形式のOpenAI互換ルートとして扱います +- そのため、OpenAIネイティブ専用のリクエスト整形はここでは適用されません: `service_tier` なし、Responsesの `store` なし、OpenAI推論互換ペイロード整形なし、プロンプトキャッシュヒントなし +- 非表示のOpenClaw属性ヘッダー（`originator`、`version`、`User-Agent`） + は、これらのカスタムプロキシURLには注入されません -より厳格なOpenAI互換バックエンド向けの互換性に関する注意: +より厳格なOpenAI互換バックエンド向けの互換性メモ: -- 一部のサーバーは、Chat Completionsで構造化コンテンツパート配列ではなく、文字列の`messages[].content`しか受け付けません。そのようなエンドポイントでは、`models.providers..models[].compat.requiresStringContent: true`を設定してください。 -- 一部の小規模または厳格なローカルバックエンドは、特にツールスキーマが含まれる場合、OpenClawの完全なエージェントランタイム用プロンプト形状では不安定です。バックエンドが小さな直接`/v1/chat/completions`呼び出しでは動作しても、通常のOpenClawエージェントターンで失敗する場合は、まず`models.providers..models[].compat.supportsTools: false`を試してください。 -- それでも大きめのOpenClaw実行時にのみバックエンドが失敗する場合、残る問題は通常、OpenClawのトランスポート層ではなく、上流のモデル / サーバー容量またはバックエンドのバグです。 +- 一部のサーバーは、Chat Completionsで構造化されたcontent-part配列ではなく、文字列の `messages[].content` のみを受け付けます。そのようなエンドポイントでは、 + `models.providers..models[].compat.requiresStringContent: true` を設定してください。 +- より小規模または厳格なローカルバックエンドの中には、OpenClawの完全な + エージェントランタイムのプロンプト形式、とくにツールスキーマが含まれる場合に不安定になるものがあります。バックエンドが小さな直接の `/v1/chat/completions` 呼び出しでは動作するのに、通常の + OpenClawエージェントターンでは失敗する場合、まず + `agents.defaults.localModelMode: "lean"` を試して、`browser`、`cron`、`message` のような重量級のデフォルトツールを外してください。それでも失敗するなら、 + `models.providers..models[].compat.supportsTools: false` を試してください。 +- それでも大きめのOpenClaw実行時だけバックエンドが失敗する場合、残る問題は通常、 + OpenClawのトランスポート層ではなく、上流のモデル / サーバー容量、またはバックエンドのバグです。 ## トラブルシューティング -- Gatewayはプロキシに到達できますか？ `curl http://127.0.0.1:1234/v1/models` -- LM Studioのモデルがアンロードされていますか？ 再読み込みしてください。コールドスタートは「ハングしている」ように見える一般的な原因です。 -- 検出されたコンテキストウィンドウが**32k**未満の場合、OpenClawは警告を出し、**16k**未満ではブロックします。その事前チェックに引っかかった場合は、サーバー / モデルのコンテキスト上限を引き上げるか、より大きなモデルを選んでください。 -- コンテキストエラーですか？ `contextWindow`を下げるか、サーバー上限を引き上げてください。 -- OpenAI互換サーバーが`messages[].content ... expected a string`を返しますか？ そのモデルエントリーに`compat.requiresStringContent: true`を追加してください。 -- 小さな直接`/v1/chat/completions`呼び出しは動作するのに、`openclaw infer model run`がGemmaや他のローカルモデルで失敗しますか？ まず`compat.supportsTools: false`でツールスキーマを無効にしてから再テストしてください。それでも大きめのOpenClawプロンプトでのみサーバーがクラッシュする場合は、上流のサーバー / モデルの制限として扱ってください。 -- 安全性: ローカルモデルはプロバイダー側フィルターを通りません。プロンプトインジェクションの影響範囲を制限するため、エージェントは用途を絞り、Compactionを有効にしてください。 +- Gatewayはそのプロキシに到達できますか？ `curl http://127.0.0.1:1234/v1/models` +- LM Studioのモデルがアンロードされていませんか？ 再読み込みしてください。コールドスタートは「停止しているように見える」一般的な原因です。 +- OpenClawは、検出されたコンテキストウィンドウが **32k** 未満だと警告し、**16k** 未満だとブロックします。その事前チェックに引っかかった場合は、サーバー / モデルのコンテキスト制限を引き上げるか、より大きなモデルを選んでください。 +- コンテキストエラーが出ますか？ `contextWindow` を下げるか、サーバー側の制限を引き上げてください。 +- OpenAI互換サーバーが `messages[].content ... expected a string` を返しますか？ + そのモデルエントリに `compat.requiresStringContent: true` を追加してください。 +- 小さな直接の `/v1/chat/completions` 呼び出しは動くのに、`openclaw infer model run` + がGemmaなどのローカルモデルで失敗しますか？ まず + `compat.supportsTools: false` でツールスキーマを無効化してから再テストしてください。それでもより大きなOpenClawプロンプトでのみサーバーがクラッシュするなら、上流のサーバー / モデルの制限として扱ってください。 +- 安全性: ローカルモデルはプロバイダー側フィルターを通らないため、エージェントは狭い用途に絞り、Compactionを有効にして、プロンプトインジェクションの影響範囲を限定してください。 diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index dade81209..9b857f0ff 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - ローカルまたは CI でテストを実行する - - model/provider のバグに対するリグレッションを追加する - - Gateway + agent の動作をデバッグする -summary: テストキット：unit/e2e/live スイート、Docker ランナー、および各テストでカバーされる内容 -title: テスト中 + - モデル/プロバイダーのバグに対するリグレッションテストを追加する + - Gateway + エージェントの動作をデバッグする +summary: 'テストキット: unit/e2e/live スイート、Docker ランナー、および各テストがカバーする内容' +title: テスト x-i18n: - generated_at: "2026-04-13T04:46:50Z" + generated_at: "2026-04-15T04:43:37Z" model: gpt-5.4 provider: openai - source_hash: 3db91b4bc36f626cd014958ec66b08b9cecd9faaa20a5746cd3a49ad4b0b1c38 + source_hash: fbf647a5cf13b5861a3ba0cb367dc816c57f0e9c60d3cd6320da193bfadf5609 source_path: help/testing.md workflow: 15 --- @@ -22,68 +22,70 @@ OpenClaw には 3 つの Vitest スイート（unit/integration、e2e、live） - 各スイートが何をカバーするか（そして意図的に _何をカバーしないか_） - 一般的なワークフロー（ローカル、push 前、デバッグ）でどのコマンドを実行するか -- live テストがどのように認証情報を検出し、モデル/プロバイダーを選択するか -- 実際の model/provider の問題に対するリグレッションをどのように追加するか +- live テストがどのように認証情報を見つけ、モデル/プロバイダーを選択するか +- 実際のモデル/プロバイダー問題に対するリグレッションテストを追加する方法 ## クイックスタート -たいていの日は: +たいていの日は次で十分です。 -- フルゲート（push 前に想定）: `pnpm build && pnpm check && pnpm test` -- 余裕のあるマシンでの、より高速なローカルフルスイート実行: `pnpm test:max` +- フルゲート（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` -テストに触れたときや、さらに確信が欲しいとき: +テストに手を入れたときや、追加の確信が欲しいときは次を使います。 - カバレッジゲート: `pnpm test:coverage` - E2E スイート: `pnpm test:e2e` -実際の provider/model をデバッグするとき（実際の認証情報が必要）: +実際のプロバイダー/モデルをデバッグするとき（実際の認証情報が必要）: -- live スイート（models + Gateway の tool/image プローブ）: `pnpm test:live` -- 単一の 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 テストを絞り込むことを優先してください。 +ヒント: 必要なのが 1 つの失敗ケースだけなら、以下で説明する allowlist 環境変数で live テストを絞り込むことを優先してください。 -## QA 固有のランナー +## QA 固有ランナー -これらのコマンドは、QA-lab レベルの現実性が必要なときに、メインのテストスイートの横に位置づけられます。 +これらのコマンドは、QA-lab の現実性が必要なときに、メインのテストスイートと並んで使います。 - `pnpm openclaw qa suite` - リポジトリベースの QA シナリオをホスト上で直接実行します。 - - デフォルトでは、分離された Gateway ワーカーを使って複数の選択シナリオを並列実行し、最大 64 ワーカーまたは選択シナリオ数まで使用します。`--concurrency ` でワーカー数を調整するか、以前の直列レーンには `--concurrency 1` を使用してください。 + - デフォルトでは、分離された Gateway ワーカーを使って、選択した複数のシナリオを並列実行します。最大 64 ワーカー、または選択されたシナリオ数までです。`--concurrency ` でワーカー数を調整するか、以前の直列レーンとして `--concurrency 1` を使用します。 - `pnpm openclaw qa suite --runner multipass` - - 同じ QA スイートを使い捨ての Multipass Linux VM 内で実行します。 + - 同じ QA スイートを、一時的な Multipass Linux VM 内で実行します。 - ホスト上の `qa suite` と同じシナリオ選択動作を維持します。 - - `qa suite` と同じ provider/model 選択フラグを再利用します。 - - live 実行では、ゲストで実用的なサポート済み QA 認証入力を転送します: - env ベースの provider key、QA live provider config path、存在する場合の `CODEX_HOME`。 - - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に置く必要があります。 + - `qa suite` と同じプロバイダー/モデル選択フラグを再利用します。 + - live 実行では、ゲストで実用的な、サポート対象の QA 認証入力を転送します: + 環境変数ベースのプロバイダーキー、QA live provider config パス、存在する場合は `CODEX_HOME`。 + - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるように、リポジトリルート配下にとどめる必要があります。 - 通常の QA レポート + サマリーに加えて、Multipass ログを `.artifacts/qa-e2e/...` 配下に書き込みます。 - `pnpm qa:lab:up` - - オペレーター風の QA 作業のために、Docker ベースの QA サイトを起動します。 + - オペレーター型の QA 作業向けに Docker ベースの QA サイトを起動します。 - `pnpm openclaw qa matrix` - - 使い捨ての Docker ベース Tuwunel homeserver に対して、Matrix live QA レーンを実行します。 - - 一時的な Matrix ユーザー 3 人（`driver`、`sut`、`observer`）と 1 つのプライベートルームをプロビジョニングし、その後、実際の Matrix Plugin を SUT トランスポートとして使う QA Gateway 子プロセスを起動します。 - - デフォルトでは、固定された stable な Tuwunel イメージ `ghcr.io/matrix-construct/tuwunel:v1.5.1` を使用します。別のイメージをテストする必要がある場合は、`OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` で上書きしてください。 - - Matrix は現在、レーンが使い捨てユーザーをローカルでプロビジョニングするため、`--credential-source env` のみをサポートします。 + - Matrix live QA レーンを、一時的な Docker ベースの Tuwunel homeserver に対して実行します。 + - この QA ホストは現在 repo/dev 専用です。パッケージ化された OpenClaw インストールには `qa-lab` が同梱されないため、`openclaw qa` は公開されません。 + - リポジトリチェックアウトでは、同梱ランナーを直接読み込みます。別途 plugin のインストール手順は不要です。 + - 3 つの一時 Matrix ユーザー（`driver`、`sut`、`observer`）と 1 つのプライベートルームをプロビジョニングし、その後、実際の Matrix Plugin を SUT transport として使う QA Gateway 子プロセスを起動します。 + - デフォルトでは、固定された安定版 Tuwunel イメージ `ghcr.io/matrix-construct/tuwunel:v1.5.1` を使用します。別のイメージをテストする必要がある場合は、`OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` で上書きしてください。 + - Matrix では、ローカルで一時ユーザーをプロビジョニングするため、共有 credential-source フラグは公開されていません。 - Matrix QA レポート、サマリー、および observed-events artifact を `.artifacts/qa-e2e/...` 配下に書き込みます。 - `pnpm openclaw qa telegram` - env の driver および SUT bot token を使って、実際のプライベートグループに対して 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 つの異なる bot が必要で、SUT bot は Telegram username を公開している必要があります。 - - 安定した bot-to-bot 観測のために、両方の bot で `@BotFather` の Bot-to-Bot Communication Mode を有効化し、driver bot がグループ内の bot トラフィックを観測できるようにしてください。 + - 共有プール認証情報用に `--credential-source convex` をサポートします。デフォルトでは env モードを使い、プールされたリースを使う場合は `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定してください。 + - 同じプライベートグループにいる 2 つの異なる bot が必要で、SUT bot は Telegram username を公開している必要があります。 + - bot 間観測を安定させるには、両方の bot で `@BotFather` の Bot-to-Bot Communication Mode を有効にし、driver bot がグループ内 bot トラフィックを観測できるようにしてください。 - Telegram QA レポート、サマリー、および observed-messages artifact を `.artifacts/qa-e2e/...` 配下に書き込みます。 -live transport レーンは、新しい transport がずれないように、1 つの標準契約を共有します。 +live transport レーンは、新しい transport が逸脱しないよう、1 つの標準コントラクトを共有します。 -`qa-channel` は引き続き広範な synthetic QA スイートであり、live -transport カバレッジマトリクスには含まれません。 +`qa-channel` は引き続き広範な合成 QA スイートであり、live +transport カバレッジマトリクスの一部ではありません。 | Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | | -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | @@ -92,21 +94,21 @@ transport カバレッジマトリクスには含まれません。 ### 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 project scaffold: +参照用 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` -- 認証ロール選択: +- 選択したロール用のシークレット 1 つ: + - `maintainer` 用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` + - `ci` 用 `OPENCLAW_QA_CONVEX_SECRET_CI` +- 認証情報ロールの選択: - CLI: `--credential-role maintainer|ci` - - env デフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（デフォルトは `maintainer`） + - 環境変数のデフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（デフォルトは `maintainer`） 任意の環境変数: @@ -118,12 +120,12 @@ transport カバレッジマトリクスには含まれません。 - `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意の trace 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 の管理コマンド（プール add/remove/list）には、 +特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 -管理者向け CLI ヘルパー: +maintainer 向け CLI ヘルパー: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -131,9 +133,9 @@ 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`）: +デフォルトのエンドポイントコントラクト（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: - `POST /acquire` - リクエスト: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -151,62 +153,67 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove`（maintainer secret のみ） - リクエスト: `{ credentialId, actorId }` - 成功: `{ status: "ok", changed, credential }` - - アクティブなリースのガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - アクティブリースガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list`（maintainer secret のみ） - リクエスト: `{ kind?, status?, includePayload?, limit? }` - 成功: `{ status: "ok", credentials, count }` -Telegram kind の payload 形状: +Telegram kind の payload 形式: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` は数値の Telegram chat id 文字列である必要があります。 -- `admin/add` は `kind: "telegram"` に対してこの形状を検証し、不正な payload を拒否します。 +- `admin/add` は `kind: "telegram"` に対してこの形式を検証し、不正な payload を拒否します。 -### QA に channel を追加する +### QA にチャネルを追加する -markdown QA システムに channel を追加するには、必要なのは正確に 2 つだけです。 +markdown QA システムにチャネルを追加するには、厳密に 2 つのものが必要です。 -1. その channel 用の transport adapter -2. channel 契約を実行する scenario pack +1. そのチャネル用の transport adapter。 +2. チャネルコントラクトを実行する scenario pack。 -共有の `qa-lab` ランナーがフローを担える場合は、channel 固有の QA ランナーを追加しないでください。 +共有 `qa-lab` ホストでフローを扱える場合、新しい最上位 QA コマンドルートを追加してはいけません。 -`qa-lab` は共有メカニクスを担います: +`qa-lab` は共有ホスト機構を担当します。 -- スイートの起動と終了処理 -- ワーカー並列実行 -- artifact の書き込み +- `openclaw qa` コマンドルート +- スイートの起動と終了 +- ワーカー並行性 +- artifact 書き込み - レポート生成 - シナリオ実行 -- 古い `qa-channel` シナリオ向けの互換エイリアス +- 旧 `qa-channel` シナリオ向け互換エイリアス -channel adapter は transport 契約を担います: +runner plugin は transport コントラクトを担当します。 -- その transport に対して Gateway がどのように設定されるか -- readiness をどのように確認するか -- inbound event をどのように注入するか -- outbound message をどのように観測するか -- transcript と正規化済み transport state をどのように公開するか -- transport ベースの action をどのように実行するか -- transport 固有の reset や cleanup をどのように処理するか +- どのように `openclaw qa ` を共有 `qa` ルートの下にマウントするか +- その transport 向けに Gateway をどう設定するか +- readiness をどう確認するか +- inbound event をどう注入するか +- outbound message をどう観測するか +- transcript と正規化された transport state をどう公開するか +- transport ベースのアクションをどう実行するか +- transport 固有のリセットやクリーンアップをどう扱うか -新しい channel を採用する最小条件は次のとおりです。 +新しいチャネルに求められる最小限の採用基準は次のとおりです。 -1. 共有 `qa-lab` seam 上に transport adapter を実装する。 -2. transport registry に adapter を登録する。 -3. transport 固有のメカニクスは adapter または channel harness の中に閉じ込める。 -4. `qa/scenarios/` 配下で markdown シナリオを作成または適応する。 -5. 新しいシナリオには汎用 scenario helper を使う。 -6. リポジトリが意図的な移行を行っているのでない限り、既存の互換エイリアスを動作させ続ける。 +1. 共有 `qa` ルートの所有者は `qa-lab` のままにする。 +2. transport runner を共有 `qa-lab` ホストシーム上に実装する。 +3. transport 固有の仕組みは runner plugin または channel harness 内に保持する。 +4. 競合するルートコマンドを登録するのではなく、runner を `openclaw qa ` としてマウントする。 + runner plugin は `openclaw.plugin.json` で `qaRunners` を宣言し、`runtime-api.ts` から一致する `qaRunnerCliRegistrations` 配列を export する必要があります。 + `runtime-api.ts` は軽量に保ってください。遅延 CLI および runner 実行は、別の entrypoint の背後に置く必要があります。 +5. `qa/scenarios/` 配下で markdown シナリオを作成または適応する。 +6. 新しいシナリオには汎用シナリオヘルパーを使う。 +7. リポジトリが意図的な移行を行っている場合を除き、既存の互換エイリアスは動作し続けるようにする。 判断ルールは厳格です。 -- 振る舞いを `qa-lab` に 1 回だけ表現できるなら、`qa-lab` に置いてください。 -- 振る舞いが 1 つの channel transport に依存するなら、その adapter または plugin harness に置いてください。 -- シナリオが複数の channel で使える新しい capability を必要とするなら、`suite.ts` に channel 固有の分岐を追加するのではなく、汎用 helper を追加してください。 -- 振る舞いが 1 つの transport にしか意味を持たないなら、そのシナリオを transport 固有に保ち、そのことを scenario 契約内で明示してください。 +- 振る舞いを `qa-lab` で一度だけ表現できるなら、`qa-lab` に置く。 +- 振る舞いが 1 つのチャネル transport に依存するなら、その runner plugin または plugin harness に保持する。 +- あるシナリオが複数チャネルで使える新しい機能を必要とするなら、`suite.ts` にチャネル固有の分岐を入れるのではなく、汎用ヘルパーを追加する。 +- ある振る舞いが 1 つの transport にしか意味を持たないなら、そのシナリオは transport 固有のままにし、scenario contract でそれを明示する。 -新しいシナリオ向けの推奨される汎用 helper 名は次のとおりです。 +新しいシナリオ向けの、推奨される汎用ヘルパー名は次のとおりです。 - `waitForTransportReady` - `waitForChannelReady` @@ -221,7 +228,7 @@ channel adapter は transport 契約を担います: - `formatTransportTranscript` - `resetTransport` -既存シナリオ向けには、次の互換エイリアスも引き続き利用できます。 +既存シナリオ向けの互換エイリアスも引き続き利用可能です。以下を含みます。 - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -229,217 +236,214 @@ channel adapter は transport 契約を担います: - `formatConversationTranscript` - `resetBus` -新しい channel の作業では、汎用 helper 名を使用してください。 -互換エイリアスはフラグデー移行を避けるために存在するものであり、 -新しいシナリオ作成のモデルではありません。 +新しいチャネル作業では、汎用ヘルパー名を使うべきです。 +互換エイリアスは、フラグデー移行を避けるために存在しているのであって、 +新しいシナリオ作成の手本ではありません。 -## テストスイート（どこで何が実行されるか） +## テストスイート（何がどこで動くか） -これらのスイートは「現実性が増していくもの」（そして flaky さ/コストも増すもの）として考えてください。 +スイートは「現実性が増す」（そして不安定さ/コストも増す）ものとして考えてください。 ### Unit / integration（デフォルト） - コマンド: `pnpm test` -- 設定: 既存のスコープ付き Vitest project に対する 10 個の順次 shard 実行（`vitest.full-*.config.ts`） -- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下の core/unit inventory と、`vitest.unit.config.ts` でカバーされる許可済みの `ui` node テスト +- 設定: 既存のスコープ付き Vitest project に対する 10 回の逐次シャード実行（`vitest.full-*.config.ts`） +- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下の core/unit インベントリ、および `vitest.unit.config.ts` がカバーする許可済みの `ui` node テスト - スコープ: - 純粋な unit テスト - - プロセス内 integration テスト（Gateway 認証、ルーティング、tooling、パース、config） - - 既知のバグに対する決定論的なリグレッション + - インプロセス統合テスト（Gateway auth、routing、tooling、parsing、config） + - 既知のバグに対する決定的なリグレッション - 期待値: - CI で実行される - 実際のキーは不要 - 高速かつ安定しているべき -- Projects 注記: - - 対象未指定の `pnpm test` は、1 つの巨大な native root-project プロセスではなく、11 個の小さな shard config（`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` は、マルチ shard の watch ループが現実的ではないため、引き続き native root の `vitest.config.ts` project graph を使用します。 - - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリ指定をまずスコープ付きレーンにルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` では root project 全体の起動コストを支払わずに済みます。 - - `pnpm test:changed` は、差分がルーティング可能な source/test ファイルだけに触れている場合、変更された git パスを同じスコープ付きレーンに展開します。config/setup の編集は、引き続き広い root-project 再実行にフォールバックします。 - - agents、commands、plugins、auto-reply helper、`plugin-sdk`、および類似の純粋なユーティリティ領域からの import-light な unit テストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンにルーティングされます。stateful/runtime-heavy なファイルは既存のレーンに残ります。 - - 選択された `plugin-sdk` および `commands` の helper source ファイルは、changed モードの実行をそれらの light レーンにある明示的な sibling テストにもマップするため、helper 編集時にそのディレクトリの重いフルスイートを再実行せずに済みます。 - - `auto-reply` には現在、3 つの専用バケットがあります: トップレベルの core helper、トップレベルの `reply.*` integration テスト、そして `src/auto-reply/reply/**` サブツリーです。これにより、最も重い reply harness の処理を、軽量な status/chunk/token テストから切り離せます。 -- Embedded runner 注記: - - message-tool の discovery 入力または Compaction の runtime context を変更する場合は、 - 両方のレベルのカバレッジを維持してください。 - - 純粋な routing/normalization 境界向けの、焦点を絞った helper リグレッションを追加してください。 - - あわせて、embedded runner の integration スイートも健全に保ってください: +- Projects に関する注記: + - 対象を絞らない `pnpm test` は、1 つの巨大なネイティブルート project プロセスではなく、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` の project graph を使用します。複数シャードの 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` は、変更された git パスがルーティング可能な source/test ファイルだけに触れている場合、それらを同じスコープ付きレーンに展開します。config/setup の編集は引き続き広範なルート project 再実行にフォールバックします。 + - agents、commands、plugins、auto-reply helpers、`plugin-sdk`、および同様の純粋なユーティリティ領域にある import が軽い unit テストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンを通ります。stateful/runtime-heavy なファイルは既存レーンに残ります。 + - 選択された `plugin-sdk` および `commands` helper ソースファイルも、変更モード実行をこれらの軽量レーン内の明示的な兄弟テストにマップするようになったため、helper の編集でそのディレクトリの重い全スイートを再実行せずに済みます。 + - `auto-reply` には現在、3 つの専用バケットがあります: 最上位 core helpers、最上位 `reply.*` 統合テスト、`src/auto-reply/reply/**` サブツリー。これにより、最も重い reply harness 作業を安価な status/chunk/token テストから切り離せます。 +- Embedded runner に関する注記: + - message-tool 検出入力または Compaction runtime context を変更する場合は、両レベルのカバレッジを維持してください。 + - 純粋な routing/normalization 境界には、焦点を絞った helper リグレッションを追加してください。 + - あわせて、embedded runner 統合スイートも健全に保ってください: `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`。 - - これらのスイートは、scoped id と Compaction の挙動が - 実際の `run.ts` / `compact.ts` パスを通って流れ続けることを検証します。helper のみのテストは、 - これらの integration パスの十分な代替にはなりません。 -- Pool 注記: - - ベースの Vitest config は現在デフォルトで `threads` を使用します。 - - 共有 Vitest config は `isolate: false` も固定し、root project、e2e、live config 全体で非分離ランナーを使用します。 - - root UI レーンは `jsdom` の setup と optimizer を維持しますが、現在は共有の非分離ランナー上でも動作します。 - - 各 `pnpm test` shard は、共有 Vitest config から同じ `threads` + `isolate: false` のデフォルトを継承します。 - - 共有の `scripts/run-vitest.mjs` ランチャーは現在、Vitest 子 Node プロセスに対してデフォルトで `--no-maglev` も追加し、大きなローカル実行中の V8 コンパイルのチャーンを減らします。標準の V8 挙動と比較したい場合は、`OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 -- Fast-local iteration 注記: - - `pnpm test:changed` は、変更されたパスがより小さいスイートにきれいにマップされる場合、スコープ付きレーンを経由します。 - - `pnpm test:max` と `pnpm test:changed:max` は同じルーティング動作を保ちつつ、worker cap だけを高くします。 - - ローカル worker の自動スケーリングは現在意図的に保守的で、ホストの load average がすでに高い場合にも抑制されるため、複数の並行 Vitest 実行がデフォルトで与えるダメージが小さくなります。 - - ベース Vitest config は project/config ファイルを `forceRerunTriggers` としてマークしており、テスト配線が変わったときにも changed モードの再実行が正しく保たれます。 - - config は、サポートされるホスト上で `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 ` は、そのコミット済み diff に対してルーティングされた `test:changed` を native root-project パスと比較し、wall time と macOS の max RSS を出力します。 -- `pnpm test:perf:changed:bench -- --worktree` は、変更済みファイル一覧を `scripts/test-projects.mjs` と root Vitest config にルーティングすることで、現在の dirty tree をベンチマークします。 - - `pnpm test:perf:profile:main` は、Vitest/Vite の起動と transform オーバーヘッドに対する main-thread CPU profile を書き込みます。 - - `pnpm test:perf:profile:runner` は、ファイル並列化を無効にした unit スイートに対する runner CPU+heap profile を書き込みます。 + - これらのスイートは、scoped id と Compaction の振る舞いが実際の `run.ts` / `compact.ts` パスを通って流れ続けることを検証します。helper のみのテストは、これらの統合パスの十分な代替にはなりません。 +- Pool に関する注記: + - ベース Vitest config は現在デフォルトで `threads` です。 + - 共有 Vitest config は `isolate: false` も固定し、root projects、e2e、live configs 全体で非分離 runner を使います。 + - ルート UI レーンは `jsdom` setup と optimizer を維持していますが、現在は共有の非分離 runner 上でも動作します。 + - 各 `pnpm test` シャードは、共有 Vitest config から同じ `threads` + `isolate: false` のデフォルトを継承します。 + - 共有の `scripts/run-vitest.mjs` ランチャーは、大規模なローカル実行時の V8 コンパイル負荷を減らすため、Vitest 子 Node プロセスにデフォルトで `--no-maglev` も追加するようになりました。標準の V8 挙動と比較したい場合は、`OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 +- Fast-local iteration に関する注記: + - `pnpm test:changed` は、変更パスがより小さなスイートにきれいにマップされる場合、スコープ付きレーンを通ります。 + - `pnpm test:max` と `pnpm test:changed:max` も同じルーティング動作を維持しつつ、worker 上限だけを高くします。 + - ローカル worker の自動スケーリングは現在意図的に保守的で、ホストのロードアベレージがすでに高い場合にも抑制されるため、複数の同時 Vitest 実行がデフォルトで与える影響を小さくします。 + - ベース Vitest config は、テスト配線が変わったときにも changed-mode の再実行が正しくなるよう、projects/config ファイルを `forceRerunTriggers` としてマークします。 + - config は、サポート対象ホストでは `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効に保ちます。直接プロファイリング用に明示的なキャッシュ場所を 1 つ使いたい場合は、`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 +- Perf-debug に関する注記: + - `pnpm test:perf:imports` は、Vitest の import 所要時間レポートと import 内訳出力を有効にします。 + - `pnpm test:perf:imports:changed` は、同じプロファイリング表示を `origin/main` 以降で変更されたファイルに限定します。 +- `pnpm test:perf:changed:bench -- --ref ` は、ルーティングされた `test:changed` を、そのコミット済み diff に対するネイティブルート project パスと比較し、wall time と macOS の最大 RSS を出力します。 +- `pnpm test:perf:changed:bench -- --worktree` は、変更ファイル一覧を `scripts/test-projects.mjs` とルート Vitest config に通すことで、現在の dirty tree をベンチマークします。 + - `pnpm test:perf:profile:main` は、Vitest/Vite の起動と transform オーバーヘッドに対するメインスレッド CPU プロファイルを書き出します。 + - `pnpm test:perf:profile:runner` は、ファイル並列性を無効にした unit スイートの runner CPU+heap プロファイルを書き出します。 ### E2E（Gateway スモーク） - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` - ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts` -- ランタイムのデフォルト: - - リポジトリの他の部分に合わせて、Vitest の `threads` と `isolate: false` を使用します。 +- ランタイムデフォルト: + - リポジトリの他の部分に合わせて、Vitest `threads` と `isolate: false` を使用します。 - 適応型 worker を使用します（CI: 最大 2、ローカル: デフォルトで 1）。 - - console I/O オーバーヘッドを減らすため、デフォルトで silent mode で実行します。 + - コンソール I/O オーバーヘッドを減らすため、デフォルトではサイレントモードで実行します。 - 便利な上書き: - - worker 数を強制するには `OPENCLAW_E2E_WORKERS=`（上限 16）。 - - 詳細な console 出力を再有効化するには `OPENCLAW_E2E_VERBOSE=1`。 + - worker 数を強制するには `OPENCLAW_E2E_WORKERS=`（上限 16） + - 詳細なコンソール出力を再有効化するには `OPENCLAW_E2E_VERBOSE=1` - スコープ: - - 複数インスタンスの Gateway end-to-end 挙動 - - WebSocket/HTTP surface、Node pairing、およびより重いネットワーキング + - 複数インスタンスの Gateway エンドツーエンド動作 + - WebSocket/HTTP サーフェス、Node ペアリング、およびより重いネットワーク処理 - 期待値: - - （パイプラインで有効な場合）CI で実行される + - （パイプラインで有効な場合は）CI で実行される - 実際のキーは不要 - - unit テストより可動部分が多い（遅くなる可能性がある） + - unit テストより可動部分が多い（遅くなることがある） -### E2E: OpenShell backend スモーク +### E2E: OpenShell バックエンドスモーク - コマンド: `pnpm test:e2e:openshell` - ファイル: `test/openshell-sandbox.e2e.test.ts` - スコープ: - Docker 経由でホスト上に分離された OpenShell Gateway を起動する - 一時的なローカル Dockerfile から sandbox を作成する - - 実際の `sandbox ssh-config` + SSH exec を通じて OpenClaw の OpenShell backend を実行する - - sandbox fs bridge を通じて remote-canonical filesystem の挙動を検証する + - 実際の `sandbox ssh-config` + SSH exec 経由で OpenClaw の OpenShell バックエンドを実行する + - sandbox fs bridge を通じて remote-canonical filesystem の動作を検証する - 期待値: - オプトインのみ。デフォルトの `pnpm test:e2e` 実行には含まれない - ローカルの `openshell` CLI と動作する Docker daemon が必要 - - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テスト用 Gateway と sandbox を破棄する + - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テスト Gateway と sandbox を破棄する - 便利な上書き: - - より広い e2e スイートを手動実行するときにこのテストを有効にするには `OPENCLAW_E2E_OPENSHELL=1` - - デフォルト以外の CLI バイナリまたは wrapper script を指すには `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` + - 広範な e2e スイートを手動実行するときにこのテストを有効化するには `OPENCLAW_E2E_OPENSHELL=1` + - デフォルト以外の CLI バイナリまたはラッパースクリプトを指すには `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` -### Live（実プロバイダー + 実モデル） +### Live（実際のプロバイダー + 実際のモデル） - コマンド: `pnpm test:live` - 設定: `vitest.live.config.ts` - ファイル: `src/**/*.live.test.ts` - デフォルト: `pnpm test:live` により **有効**（`OPENCLAW_LIVE_TEST=1` を設定） - スコープ: - - 「この provider/model は、実際の認証情報で _今日_ 実際に動くか？」 - - provider のフォーマット変更、tool-calling の癖、認証の問題、rate limit の挙動を捕捉する + - 「このプロバイダー/モデルは、今日、実際の認証情報で本当に動作するか？」 + - プロバイダーフォーマット変更、tool-calling の癖、auth 問題、rate limit の挙動を検出する - 期待値: - - 設計上 CI で安定しない（実ネットワーク、実プロバイダーポリシー、クォータ、障害） - - コストがかかる / rate limit を使用する - - 「全部」ではなく、対象を絞ったサブセットの実行を優先する -- live 実行は、足りない API key を拾うために `~/.profile` を source します。 -- デフォルトでは、live 実行は引き続き `HOME` を分離し、config/auth material を一時テスト用ホームにコピーするため、unit fixture が実際の `~/.openclaw` を変更することはありません。 -- live テストで意図的に実際の home directory を使いたい場合のみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 -- `pnpm test:live` は現在、より静かなモードがデフォルトです。`[live] ...` の進捗出力は維持しますが、追加の `~/.profile` 通知を抑制し、Gateway bootstrap ログ/Bonjour の雑音をミュートします。完全な起動ログを再表示したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 -- API key のローテーション（provider 固有）: カンマ/セミコロン形式の `*_API_KEYS` または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）、あるいは live ごとの上書き `OPENCLAW_LIVE_*_KEY` を設定してください。テストは rate limit 応答時に再試行します。 -- Progress/heartbeat 出力: - - live スイートは現在、長い provider 呼び出しが、Vitest の console capture が静かなときでも目に見えて動作中であるよう、進捗行を stderr に出力します。 - - `vitest.live.config.ts` は Vitest の console interception を無効にし、provider/Gateway の進捗行が live 実行中に即座にストリームされるようにします。 - - direct-model の heartbeat は `OPENCLAW_LIVE_HEARTBEAT_MS` で調整します。 - - Gateway/probe の heartbeat は `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 + - 設計上、CI で安定しない（実ネットワーク、実プロバイダーポリシー、quota、障害） + - コストがかかる / rate limit を消費する + - 「全部」ではなく、絞り込んだサブセットを実行するのを優先する +- live 実行では、不足している API キーを拾うために `~/.profile` を source します。 +- デフォルトでは、live 実行でも `HOME` を分離し、config/auth 情報を一時的なテスト home にコピーするため、unit fixture が実際の `~/.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` を設定してください。テストは 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 protocol / pairing に触れた: `pnpm test:e2e` を追加する -- 「bot が落ちている」/ provider 固有の障害 / tool calling をデバッグしている: 対象を絞った `pnpm test:live` を実行する +- ロジック/テストを編集した: `pnpm test` を実行する（多く変更した場合は `pnpm test:coverage` も） +- Gateway ネットワーク / WS protocol / pairing に触れた: `pnpm test:e2e` を追加する +- 「bot が落ちている」問題 / プロバイダー固有の障害 / tool calling をデバッグしている: 絞り込んだ `pnpm test:live` を実行する ## 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 Node に対する、コマンドごとの Gateway `node.invoke` 検証。 - 必要な事前セットアップ: - - Android アプリがすでに接続され、Gateway と pair 済みであること。 - - アプリが foreground に維持されていること。 - - 合格を期待する capability に対して、権限/キャプチャ同意が付与されていること。 -- 任意のターゲット上書き: + - Android アプリがすでに接続済みかつ Gateway とペアリング済みであること。 + - アプリをフォアグラウンドに維持すること。 + - 成功を期待する capability に必要な permissions/capture consent が許可されていること。 +- 任意の対象上書き: - `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: model スモーク（profile key） +## Live: model smoke（profile keys） -live テストは、障害を切り分けられるように 2 層に分かれています。 +live テストは、失敗を切り分けられるように 2 層に分かれています。 -- 「Direct model」は、与えられたキーで provider/model がそもそも応答できるかを教えてくれます。 -- 「Gateway smoke」は、その model に対して Gateway+agent の完全なパイプライン（session、history、tools、sandbox policy など）が動作するかを教えてくれます。 +- 「Direct model」は、指定されたキーでそのプロバイダー/モデルが少なくとも応答できることを教えてくれます。 +- 「Gateway smoke」は、そのモデルに対して完全な gateway+agent パイプラインが動作することを教えてくれます（sessions、history、tools、sandbox policy など）。 -### レイヤー 1: 直接 model completion（Gateway なし） +### レイヤー 1: Direct model completion（Gateway なし） - テスト: `src/agents/models.profiles.live.test.ts` -- 目的: +- 目標: - 検出されたモデルを列挙する - `getApiKeyForModel` を使って、認証情報を持っているモデルを選択する - モデルごとに小さな completion を実行する（必要に応じて対象を絞ったリグレッションも） -- 有効化方法: - - `pnpm test:live`（または Vitest を直接起動する場合は `OPENCLAW_LIVE_TEST=1`） -- このスイートを実際に実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、modern のエイリアス）を設定してください。そうしないと、`pnpm test:live` を Gateway smoke に集中させるためにスキップされます -- モデルの選び方: - - 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 のエイリアス +- 有効化する方法: + - `pnpm test:live`（または Vitest を直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） +- このスイートを実際に実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、modern の別名）を設定してください。そうしないと、`pnpm test:live` を Gateway smoke に集中させるためにスキップされます +- モデルの選択方法: + - `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 sweep はデフォルトで、厳選された高シグナル上限を使用します。網羅的な modern sweep には `OPENCLAW_LIVE_MAX_MODELS=0`、より小さい上限には正の数を設定してください。 -- プロバイダーの選び方: + - modern/all スイープはデフォルトで厳選された高シグナル上限を使います。網羅的な modern スイープには `OPENCLAW_LIVE_MAX_MODELS=0` を、より小さい上限には正の数を設定してください。 +- プロバイダーの選択方法: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（カンマ区切り allowlist） - キーの取得元: - - デフォルト: profile store と env fallback - - **profile store のみ** を強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - デフォルト: profile store と env フォールバック + - **profile store** のみを強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` を設定する - これが存在する理由: - - 「provider API が壊れている / キーが無効」なのか、「Gateway agent パイプラインが壊れている」なのかを切り分ける - - 小さく分離されたリグレッションを収める（例: OpenAI Responses/Codex Responses の reasoning replay + tool-call フロー） + - 「プロバイダー API が壊れている / キーが無効である」と「Gateway agent パイプラインが壊れている」を切り分けるため + - 小さく分離されたリグレッションを収容するため（例: OpenAI Responses/Codex Responses の reasoning replay + tool-call フロー） -### レイヤー 2: Gateway + dev agent スモーク（`"@openclaw"` が実際に行うこと） +### レイヤー 2: Gateway + dev agent smoke（`"@openclaw"` が実際に行うこと） - テスト: `src/gateway/gateway-models.profiles.live.test.ts` -- 目的: - - プロセス内 Gateway を起動する - - `agent:dev:*` session を作成/patch する（実行ごとの model override） +- 目標: + - インプロセス Gateway を起動する + - `agent:dev:*` セッションを作成/patch する（実行ごとに model override） - キー付きモデルを反復し、次を検証する: - - 「意味のある」応答（tools なし） - - 実際の tool invocation が動作する（read probe） - - 任意の追加 tool probe（exec+read probe） + - 「意味のある」応答（ツールなし） + - 実際のツール呼び出しが動作する（read probe） + - 任意の追加ツール probe（exec+read probe） - OpenAI のリグレッションパス（tool-call-only → follow-up）が動作し続ける -- Probe の詳細（障害をすばやく説明できるように）: - - `read` probe: テストはワークスペース内に nonce ファイルを書き込み、agent にそれを `read` して nonce をそのまま返すよう依頼します。 - - `exec+read` probe: テストは agent に `exec` で一時ファイルへ nonce を書き込み、その後それを `read` で読み戻すよう依頼します。 - - image probe: テストは生成した PNG（cat + ランダム化されたコード）を添付し、model が `cat ` を返すことを期待します。 - - 実装参照: `src/gateway/gateway-models.profiles.live.test.ts` および `src/gateway/live-image-probe.ts`。 -- 有効化方法: - - `pnpm test:live`（または Vitest を直接起動する場合は `OPENCLAW_LIVE_TEST=1`） -- モデルの選び方: +- Probe の詳細（失敗をすぐ説明できるように）: + - `read` probe: テストはワークスペースに nonce ファイルを書き込み、エージェントにそれを `read` して nonce を返答で復唱するよう求めます。 + - `exec+read` probe: テストはエージェントに `exec` で temp ファイルへ nonce を書かせ、その後それを `read` で読み返させます。 + - image probe: テストは生成した PNG（cat + ランダム化コード）を添付し、モデルが `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 sweep はデフォルトで厳選された高シグナル上限を使用します。網羅的な modern sweep には `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`、より小さい上限には正の数を設定してください。 -- プロバイダーの選び方（「OpenRouter を全部」は避ける）: + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` は modern allowlist の別名 + - または `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（またはカンマ区切りリスト）を設定して絞り込む + - modern/all Gateway スイープはデフォルトで厳選された高シグナル上限を使います。網羅的な modern スイープには `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` を、より小さい上限には正の数を設定してください。 +- プロバイダーの選択方法（「OpenRouter 全部」を避ける）: - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（カンマ区切り allowlist） - この live テストでは tool + image probe は常に有効です: - - `read` probe + `exec+read` probe（tool ストレス） - - image probe は、model が image input のサポートを広告している場合に実行されます + - `read` probe + `exec+read` probe（ツール負荷テスト） + - image probe は、モデルが image input サポートを公開している場合に実行されます - フロー（高レベル）: - - テストは「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 agent は multimodal な user message を model に転送します - - アサーション: reply に `cat` + そのコードが含まれること（OCR 許容: 小さな誤りは許可） + - テストは「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 agent は multimodal な user message をモデルへ転送します + - 検証: 返信に `cat` + そのコードが含まれること（OCR 許容: 小さな誤りは許可） ヒント: 自分のマシンで何をテストできるか（および正確な `provider/model` id）を確認するには、次を実行してください。 @@ -448,28 +452,27 @@ openclaw models list openclaw models list --json ``` -## Live: CLI backend スモーク（Claude、Codex、Gemini、またはその他のローカル CLI） +## Live: CLI backend smoke（Claude、Codex、Gemini、またはその他のローカル CLI） - テスト: `src/gateway/gateway-cli-backend.live.test.ts` -- 目的: デフォルト config に触れずに、ローカル CLI backend を使って Gateway + agent パイプラインを検証する。 -- backend 固有の smoke デフォルトは、所有 extension の `cli-backend.ts` 定義にあります。 +- 目標: デフォルト設定に触れずに、ローカル CLI backend を使って Gateway + agent パイプラインを検証する。 +- backend 固有の smoke デフォルトは、所有する extension の `cli-backend.ts` 定義内にあります。 - 有効化: - - `pnpm test:live`（または Vitest を直接起動する場合は `OPENCLAW_LIVE_TEST=1`） + - `pnpm test:live`（または Vitest を直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） - `OPENCLAW_LIVE_CLI_BACKEND=1` - デフォルト: - - デフォルトの provider/model: `claude-cli/claude-sonnet-4-6` - - command/args/image の挙動は、所有 CLI backend Plugin metadata から取得されます。 + - デフォルト 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 attachment を送るには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`（パスは prompt に注入されます）。 - - prompt 注入ではなく CLI 引数として image file path を渡すには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`。 + - prompt 注入の代わりに image file path を CLI 引数として渡すには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`。 - `IMAGE_ARG` が設定されているときに image 引数の渡し方を制御するには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または `"list"`）。 - - 2 回目の turn を送って 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`）。 - -例: + - 2 回目のターンを送って resume フローを検証するには `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`。 + - デフォルトの Claude Sonnet -> Opus 同一セッション継続性 probe を無効にするには `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択したモデルが switch target をサポートしているときに強制有効化するには `1`）。 +- 例: ```bash OPENCLAW_LIVE_CLI_BACKEND=1 \ @@ -483,7 +486,7 @@ Docker レシピ: pnpm test:docker:live-cli-backend ``` -単一プロバイダーの Docker レシピ: +単一プロバイダー Docker レシピ: ```bash pnpm test:docker:live-cli-backend:claude @@ -495,27 +498,27 @@ pnpm test:docker:live-cli-backend:gemini 注記: - Docker ランナーは `scripts/test-live-cli-backend-docker.sh` にあります。 -- これは、リポジトリ Docker イメージ内で live CLI-backend スモークを非 root の `node` ユーザーとして実行します。 -- 所有 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` のいずれかによる portable な Claude Code subscription OAuth が必要です。これはまず Docker 内で直接の `claude -p` を確認し、その後 Anthropic API-key env vars を保持せずに 2 回の Gateway CLI-backend turn を実行します。この subscription レーンでは、Claude が現在サードパーティアプリ利用を通常の subscription plan 上限ではなく追加利用課金にルーティングするため、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 のデフォルト smoke では、session を Sonnet から Opus に patch し、resume した session が以前のメモを引き続き覚えていることも検証します。 +- これは、リポジトリ Docker イメージ内で live CLI-backend smoke を非 root の `node` ユーザーとして実行します。 +- 所有する extension から CLI smoke metadata を解決し、その後、一致する 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 subscription OAuth が必要です。最初に Docker 内で直接 `claude -p` を証明し、その後 Anthropic API-key env var を保持せずに 2 回の Gateway CLI-backend ターンを実行します。この subscription レーンでは、Claude が現在サードパーティアプリ使用を通常の subscription plan 制限ではなく追加使用量課金にルーティングしているため、Claude MCP/tool と image probe をデフォルトで無効にします。 +- live CLI-backend smoke は現在、Claude、Codex、Gemini に対して同じ end-to-end フローを実行します: テキストターン、画像分類ターン、その後 Gateway CLI 経由で検証される MCP `cron` ツール呼び出し。 +- Claude のデフォルト smoke では、セッションを Sonnet から Opus に patch し、再開されたセッションが以前のメモを引き続き記憶していることも検証します。 -## Live: ACP bind スモーク（`/acp spawn ... --bind here`） +## Live: ACP bind smoke（`/acp spawn ... --bind here`） - テスト: `src/gateway/gateway-acp-bind.live.test.ts` -- 目的: live ACP agent を使って、実際の ACP conversation-bind フローを検証する: +- 目標: live ACP agent を使って実際の ACP 会話 bind フローを検証すること: - `/acp spawn --bind here` を送信する - - synthetic な message-channel conversation をその場で bind する - - 同じ conversation 上で通常の follow-up を送信する - - follow-up が bind 済み ACP session transcript に到達することを検証する + - 合成 message-channel 会話をその場で bind する + - その同じ会話で通常の follow-up を送信する + - follow-up が bind 済み ACP セッショントランスクリプトに届くことを確認する - 有効化: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - デフォルト: - Docker 内の ACP agent: `claude,codex,gemini` - - 直接の `pnpm test:live ...` 用 ACP agent: `claude` - - synthetic channel: Slack DM スタイルの conversation context + - 直接 `pnpm test:live ...` 用の ACP agent: `claude` + - 合成チャネル: Slack DM 風の会話コンテキスト - ACP backend: `acpx` - 上書き: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -524,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@'` - 注記: - - このレーンは、admin 専用の synthetic な originating-route フィールド付きで Gateway の `chat.send` surface を使用するため、テストは外部配信を装わずに message-channel context を付与できます。 - - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、テストは選択された ACP harness agent に対して、埋め込み `acpx` Plugin の組み込み agent registry を使用します。 + - このレーンは、admin 専用の合成 originating-route フィールドを持つ Gateway `chat.send` サーフェスを使うため、外部配送を装わずに message-channel context をテストへ付与できます。 + - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、このテストは選択した ACP harness agent に対して組み込みの `acpx` plugin の内蔵 agent registry を使用します。 例: @@ -541,7 +544,7 @@ Docker レシピ: pnpm test:docker:live-acp-bind ``` -単一 agent の Docker レシピ: +単一 agent Docker レシピ: ```bash pnpm test:docker:live-acp-bind:claude @@ -549,34 +552,34 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Docker 注記: +Docker に関する注記: - Docker ランナーは `scripts/test-live-acp-bind-docker.sh` にあります。 -- デフォルトでは、サポートされるすべての live CLI agent に対して ACP bind スモークを順番に実行します: `claude`、`codex`、`gemini`。 -- マトリクスを絞り込むには `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使用してください。 -- これは `~/.profile` を source し、一致する CLI auth material をコンテナ内にステージし、書き込み可能な npm prefix に `acpx` をインストールし、その後要求された live CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）がなければインストールします。 -- Docker 内では、ランナーは `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` を設定するため、acpx は source 済み profile から利用可能な provider env vars を子 harness CLI に保持できます。 +- デフォルトでは、サポートされるすべての live CLI agent に対して ACP bind smoke を順番に実行します: `claude`、`codex`、`gemini`。 +- マトリクスを絞り込むには `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使用します。 +- これは `~/.profile` を source し、一致する CLI auth 情報をコンテナへステージし、`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` を設定するため、acpx は source 済み profile の provider env var を子 harness CLI で利用可能なまま維持します。 -## Live: Codex app-server harness スモーク +## Live: Codex app-server harness smoke -- 目的: 通常の Gateway - `agent` メソッドを通じて、Plugin 所有の Codex harness を検証する: - - バンドルされた `codex` Plugin を読み込む +- 目標: plugin 所有の Codex harness を通常の Gateway + `agent` メソッド経由で検証すること: + - 同梱の `codex` plugin を読み込む - `OPENCLAW_AGENT_RUNTIME=codex` を選択する - - `codex/gpt-5.4` に最初の Gateway agent turn を送信する - - 同じ OpenClaw session に 2 回目の turn を送信し、app-server + - `codex/gpt-5.4` に最初の Gateway agent ターンを送る + - 同じ OpenClaw セッションに 2 回目のターンを送り、app-server thread が resume できることを検証する - 同じ Gateway command - パスを通じて `/codex status` と `/codex models` を実行する + パス経由で `/codex status` と `/codex models` を実行する - テスト: `src/gateway/gateway-codex-harness.live.test.ts` - 有効化: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- デフォルト model: `codex/gpt-5.4` +- デフォルトモデル: `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 - harness が PI へのサイレントフォールバックによって通過することはできません。 -- 認証: シェル/profile からの `OPENAI_API_KEY` と、任意でコピーされる - `~/.codex/auth.json` および `~/.codex/config.toml` +- この smoke は `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を設定するため、壊れた Codex + harness が PI に黙ってフォールバックして通過することはできません。 +- auth: シェル/profile 由来の `OPENAI_API_KEY`、および任意でコピーされた + `~/.codex/auth.json` と `~/.codex/config.toml` ローカルレシピ: @@ -596,50 +599,50 @@ source ~/.profile pnpm test:docker:live-codex-harness ``` -Docker 注記: +Docker に関する注記: - Docker ランナーは `scripts/test-live-codex-harness-docker.sh` にあります。 -- これはマウントされた `~/.profile` を source し、`OPENAI_API_KEY` を渡し、存在する場合は Codex CLI - auth ファイルをコピーし、書き込み可能なマウント済み npm - prefix に `@openai/codex` をインストールし、source tree をステージした後、Codex-harness live テストのみを実行します。 -- Docker では image および MCP/tool probe がデフォルトで有効です。より狭いデバッグ実行が必要な場合は +- これはマウントされた `~/.profile` を source し、`OPENAI_API_KEY` を渡し、Codex CLI + auth ファイルが存在すればコピーし、`@openai/codex` を書き込み可能なマウント済み npm + prefix にインストールし、ソースツリーをステージし、その後 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` を export し、live - テスト設定と一致させることで、`openai-codex/*` や PI へのフォールバックが Codex harness - のリグレッションを隠せないようにします。 +- Docker も `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を export し、live + テスト設定と一致させるため、`openai-codex/*` や PI fallback で Codex harness + のリグレッションが隠れることはありません。 ### 推奨される live レシピ -狭く明示的な allowlist が最も高速で、最も flaky になりにくいです。 +狭く明示的な allowlist が最も高速で、最も不安定さが少なくなります。 -- 単一 model、direct（Gateway なし）: +- 単一モデル、direct（Gateway なし）: - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- 単一 model、Gateway スモーク: +- 単一モデル、Gateway smoke: - `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 key + Antigravity）: +- 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 key）を使用します。 -- `google-antigravity/...` は Antigravity OAuth bridge（Cloud Code Assist スタイルの agent endpoint）を使用します。 -- `google-gemini-cli/...` はあなたのマシン上のローカル Gemini CLI を使用します（認証と tooling の癖は別です）。 +- `google/...` は Gemini API を使います（API key）。 +- `google-antigravity/...` は Antigravity OAuth bridge を使います（Cloud Code Assist 風の agent endpoint）。 +- `google-gemini-cli/...` はあなたのマシン上のローカル Gemini CLI を使います（別の auth + tooling の癖があります）。 - Gemini API と Gemini CLI の違い: - - API: OpenClaw は Google がホストする Gemini API を HTTP 経由で呼び出します（API key / profile auth）。これはほとんどのユーザーが「Gemini」と言うときに意味しているものです。 - - CLI: OpenClaw はローカルの `gemini` バイナリをシェル実行します。これは独自の認証を持ち、挙動も異なる場合があります（streaming/tool サポート/バージョンずれ）。 + - API: OpenClaw は Google のホストされた Gemini API を HTTP 経由で呼び出します（API key / profile auth）。ほとんどのユーザーが「Gemini」と言うとき、これを指します。 + - CLI: OpenClaw はローカルの `gemini` バイナリをシェル実行します。独自の auth があり、挙動も異なる場合があります（streaming/tool サポート/version のずれ）。 -## Live: model マトリクス（何をカバーするか） +## Live: model matrix（何をカバーするか） -固定の「CI model list」はありません（live はオプトイン）ですが、キーを持つ開発マシンで定期的にカバーすることが**推奨**されるモデルは次のとおりです。 +固定の「CI model list」はありません（live はオプトイン）が、キーがある開発マシンで定期的にカバーすることを **推奨** するモデルは以下です。 -### Modern スモークセット（tool calling + image） +### Modern smoke set（tool calling + image） これは、動作し続けることを期待する「一般的なモデル」実行です。 @@ -651,12 +654,12 @@ Docker 注記: - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -tools + image 付きで Gateway スモークを実行: +ツール + image 付きで Gateway smoke を実行: `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` ### ベースライン: tool calling（Read + 任意の Exec） -provider ファミリーごとに少なくとも 1 つは選んでください。 +少なくとも各プロバイダーファミリーから 1 つ選んでください。 - OpenAI: `openai/gpt-5.4`（または `openai/gpt-5.4-mini`） - Anthropic: `anthropic/claude-opus-4-6`（または `anthropic/claude-sonnet-4-6`） @@ -664,44 +667,44 @@ provider ファミリーごとに少なくとも 1 つは選んでください - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -任意の追加カバレッジ（あると望ましい）: +任意の追加カバレッジ（あると良いもの）: -- xAI: `xai/grok-4`（または利用可能な最新） +- xAI: `xai/grok-4`（または利用可能な最新版） - Mistral: `mistral/`…（有効化されている「tools」対応モデルを 1 つ選ぶ） - Cerebras: `cerebras/`…（アクセス権がある場合） -- LM Studio: `lmstudio/`…（ローカル。tool calling は API mode に依存） +- LM Studio: `lmstudio/`…（ローカル。tool calling は API モードに依存） -### Vision: image 送信（attachment → multimodal message） +### Vision: image send（attachment → multimodal message） -image probe を実行するため、少なくとも 1 つは image 対応 model（Claude/Gemini/OpenAI の vision 対応 variant など）を `OPENCLAW_LIVE_GATEWAY_MODELS` に含めてください。 +少なくとも 1 つの image 対応モデル（Claude/Gemini/OpenAI の vision 対応バリアントなど）を `OPENCLAW_LIVE_GATEWAY_MODELS` に含めて、image probe を実行してください。 -### Aggregator / 代替 Gateway +### Aggregators / 代替 Gateway -キーが有効なら、以下を通じたテストもサポートしています。 +キーが有効なら、以下経由のテストもサポートしています。 -- OpenRouter: `openrouter/...`（何百ものモデル。tool+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 マトリクスに含められる他の provider（認証情報/config がある場合）: +認証情報/config がある場合、live matrix に含められる追加プロバイダー: -- Built-in: `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` 経由（カスタム endpoint）: `minimax`（cloud/API）、および任意の OpenAI/Anthropic 互換 proxy（LM Studio、vLLM、LiteLLM など） +- 組み込み: `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` 経由（カスタム endpoint）: `minimax`（cloud/API）、および OpenAI/Anthropic 互換 proxy（LM Studio、vLLM、LiteLLM など） -ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。権威ある一覧は、あなたのマシン上で `discoverModels(...)` が返すものと、利用可能なキーがあるものです。 +ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。権威あるリストは、あなたのマシンで `discoverModels(...)` が返すもの + 利用可能なキーがあるものです。 -## 認証情報（絶対にコミットしない） +## 認証情報（絶対に commit しないこと） -live テストは、CLI と同じ方法で認証情報を検出します。実際上の意味は次のとおりです。 +live テストは、CLI と同じ方法で認証情報を見つけます。実際上の意味は次のとおりです。 - CLI が動作するなら、live テストも同じキーを見つけられるはずです。 -- live テストが「認証情報なし」と言うなら、`openclaw models list` / model 選択をデバッグするときと同じ方法でデバッグしてください。 +- live テストが「認証情報なし」と言うなら、`openclaw models list` / model 選択をデバッグするのと同じ方法でデバッグしてください。 -- agent ごとの認証 profile: `~/.openclaw/agents//agent/auth-profiles.json`（live テストで「profile keys」と言うときはこれを指します） +- エージェントごとの auth profile: `~/.openclaw/agents//agent/auth-profiles.json`（live テストで「profile keys」と言うとき、これを意味します） - Config: `~/.openclaw/openclaw.json`（または `OPENCLAW_CONFIG_PATH`） -- legacy state dir: `~/.openclaw/credentials/`（存在する場合はステージされた live home にコピーされますが、メインの profile-key ストアではありません） -- ローカルの live 実行では、デフォルトでアクティブな config、agent ごとの `auth-profiles.json` ファイル、legacy `credentials/`、およびサポートされる外部 CLI 認証ディレクトリを一時テスト用ホームにコピーします。ステージされた live home では `workspace/` と `sandboxes/` をスキップし、`agents.*.workspace` / `agentDir` のパス上書きは除去されるため、probe が実際のホストワークスペースに触れません。 +- 旧 state ディレクトリ: `~/.openclaw/credentials/`（存在する場合は staged live home にコピーされますが、メインの profile-key store ではありません） +- live のローカル実行では、デフォルトでアクティブ config、エージェントごとの `auth-profiles.json` ファイル、旧 `credentials/`、およびサポートされる外部 CLI auth ディレクトリを一時的なテスト home にコピーします。staged live home では `workspace/` と `sandboxes/` をスキップし、`agents.*.workspace` / `agentDir` のパス上書きも除去されるため、probe が実際のホスト workspace に触れません。 -env key に依存したい場合（例: `~/.profile` で export されているもの）は、ローカルテストの前に `source ~/.profile` を実行するか、以下の Docker ランナーを使用してください（`~/.profile` をコンテナにマウントできます）。 +env キー（たとえば `~/.profile` で export されたもの）に依存したい場合は、`source ~/.profile` の後でローカルテストを実行するか、以下の Docker ランナーを使用してください（`~/.profile` をコンテナにマウントできます）。 ## Deepgram live（音声文字起こし） @@ -712,105 +715,109 @@ env key に依存したい場合（例: `~/.profile` で export されている - テスト: `src/agents/byteplus.live.test.ts` - 有効化: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- 任意の model 上書き: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- 任意のモデル上書き: `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` パスを実行する + - 同梱 comfy image、video、および `music_generate` パスを実行する - `models.providers.comfy.` が設定されていない限り、各 capability をスキップする - - comfy workflow の送信、polling、download、または Plugin 登録を変更した後に有用 + - comfy workflow submission、polling、downloads、または Plugin registration を変更した後に有用 -## Image generation live +## 画像生成 live - テスト: `src/image-generation/runtime.live.test.ts` - コマンド: `pnpm test:live src/image-generation/runtime.live.test.ts` - ハーネス: `pnpm test:live:media image` - スコープ: - - 登録されているすべての image-generation provider Plugin を列挙する - - probing 前に、足りない provider env vars をログインシェル（`~/.profile`）から読み込む - - デフォルトでは、保存済み auth profile よりも live/env API key を優先して使うため、`auth-profiles.json` 内の古いテスト用キーが実際のシェル認証情報を覆い隠さない - - 使用可能な auth/profile/model がない provider はスキップする - - 共有ランタイム capability を通じて、標準の image-generation variant を実行する: + - 登録されたすべての画像生成 provider plugin を列挙する + - probe 前に、ログインシェル（`~/.profile`）から不足している provider env var を読み込む + - デフォルトでは保存済み auth profile より live/env API key を優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を隠すことがない + - 使用可能な auth/profile/model がないプロバイダーはスキップする + - 共有 runtime capability を通じて標準の画像生成バリアントを実行する: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- 現在カバーされている bundled 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"` -- 任意の認証挙動: - - env-only の上書きを無視し、profile-store 認証を強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 任意の auth 動作: + - profile-store auth を強制し、env のみの上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Music generation live +## 音楽生成 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` - スコープ: - - 共有 bundled music-generation provider パスを実行する + - 共有の同梱 music-generation provider パスを実行する - 現在は Google と MiniMax をカバーする - - probing 前に、provider env vars をログインシェル（`~/.profile`）から読み込む - - デフォルトでは、保存済み auth profile よりも live/env API key を優先して使うため、`auth-profiles.json` 内の古いテスト用キーが実際のシェル認証情報を覆い隠さない - - 使用可能な auth/profile/model がない provider はスキップする - - 利用可能な場合は、宣言された両方のランタイム mode を実行する: - - prompt-only 入力による `generate` - - provider が `capabilities.edit.enabled` を宣言している場合の `edit` - - 現在の共有レーンでのカバレッジ: + - probe 前にログインシェル（`~/.profile`）から provider env var を読み込む + - デフォルトでは保存済み auth profile より live/env API key を優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を隠すことがない + - 使用可能な auth/profile/model がないプロバイダーはスキップする + - 利用可能な場合は、宣言された両方の runtime mode を実行する: + - prompt のみ入力の `generate` + - プロバイダーが `capabilities.edit.enabled` を宣言している場合の `edit` + - 現在の共有レーンカバレッジ: - `google`: `generate`、`edit` - `minimax`: `generate` - - `comfy`: 別の Comfy live ファイルであり、この共有 sweep ではない + - `comfy`: この共有スイープではなく、別の Comfy live ファイル - 任意の絞り込み: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- 任意の認証挙動: - - env-only の上書きを無視し、profile-store 認証を強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 任意の auth 動作: + - profile-store auth を強制し、env のみの上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Video generation live +## 動画生成 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` - スコープ: - - 共有 bundled video-generation provider パスを実行する - - probing 前に、provider env vars をログインシェル（`~/.profile`）から読み込む - - デフォルトでは、保存済み auth profile よりも live/env API key を優先して使うため、`auth-profiles.json` 内の古いテスト用キーが実際のシェル認証情報を覆い隠さない - - 使用可能な auth/profile/model がない provider はスキップする - - 利用可能な場合は、宣言された両方のランタイム mode を実行する: - - prompt-only 入力による `generate` - - 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`。bundled の `veo3` は text-only で、bundled の `kling` はリモート image URL を必要とするため - - provider 固有の Vydra カバレッジ: + - 共有の同梱 video-generation provider パスを実行する + - デフォルトではリリース安全な smoke パスを使う: FAL 以外のプロバイダー、プロバイダーごとに 1 回の text-to-video リクエスト、1 秒の lobster prompt、および `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`（デフォルト `180000`）によるプロバイダーごとの操作上限 + - FAL は、プロバイダー側キュー待ち時間がリリース時間を支配しうるため、デフォルトでスキップされます。明示的に実行するには `--video-providers fal` または `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` を渡してください + - probe 前にログインシェル（`~/.profile`）から provider env var を読み込む + - デフォルトでは保存済み auth profile より live/env API key を優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を隠すことがない + - 使用可能な auth/profile/model がないプロバイダーはスキップする + - デフォルトでは `generate` のみ実行する + - 利用可能な場合に宣言された transform mode も実行するには `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定する: + - プロバイダーが `capabilities.imageToVideo.enabled` を宣言し、選択されたプロバイダー/モデルが共有スイープ内で buffer-backed ローカル画像入力を受け付ける場合の `imageToVideo` + - プロバイダーが `capabilities.videoToVideo.enabled` を宣言し、選択されたプロバイダー/モデルが共有スイープ内で buffer-backed ローカル動画入力を受け付ける場合の `videoToVideo` + - 共有スイープで現在宣言済みだがスキップされる `imageToVideo` プロバイダー: + - 同梱 `veo3` は text-only で、同梱 `kling` はリモート画像 URL を必要とするため `vydra` + - プロバイダー固有の Vydra カバレッジ: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - このファイルは、デフォルトでリモート image URL fixture を使う `kling` レーンに加え、`veo3` の text-to-video を実行する + - このファイルは、デフォルトでリモート画像 URL fixture を使う `kling` レーンに加え、`veo3` の text-to-video を実行します - 現在の `videoToVideo` live カバレッジ: - - 選択された model が `runway/gen4_aleph` の場合のみ `runway` - - 共有 sweep で現在宣言済みだがスキップされる `videoToVideo` provider: - - `alibaba`、`qwen`、`xai`。これらのパスは現在、リモート `http(s)` / MP4 参照 URL を必要とするため - - `google`。現在の共有 Gemini/Veo レーンはローカルの buffer-backed 入力を使用しており、そのパスは共有 sweep では受け付けられないため - - `openai`。現在の共有レーンには org 固有の video inpaint/remix アクセス保証がないため + - 選択モデルが `runway/gen4_aleph` の場合のみ `runway` + - 共有スイープで現在宣言済みだがスキップされる `videoToVideo` プロバイダー: + - `alibaba`、`qwen`、`xai` は現在 `http(s)` / MP4 のリモート参照 URL を必要とするため + - `google` は、現在の共有 Gemini/Veo レーンがローカル buffer-backed 入力を使っており、そのパスは共有スイープで受け付けられないため + - `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"` -- 任意の認証挙動: - - env-only の上書きを無視し、profile-store 認証を強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - デフォルトスイープに含まれる FAL を含むすべてのプロバイダーを対象にするには `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` + - 攻めた smoke 実行のために各プロバイダーの操作上限を下げるには `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` +- 任意の auth 動作: + - profile-store auth を強制し、env のみの上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Media live ハーネス +## メディア live ハーネス - コマンド: `pnpm test:live:media` - 目的: - - 共有の image、music、video live スイートを、リポジトリ標準の 1 つの entrypoint から実行する - - `~/.profile` から足りない provider env vars を自動読み込みする - - デフォルトで、現在使用可能な auth を持つ provider に各スイートを自動で絞り込む - - `scripts/test-live.mjs` を再利用するため、heartbeat と quiet-mode の挙動が一貫する + - 共有の image、music、video live スイートを、リポジトリ標準の 1 つの entrypoint で実行する + - `~/.profile` から不足している provider env var を自動で読み込む + - デフォルトで、現在使用可能な auth を持つプロバイダーに各スイートを自動で絞り込む + - `scripts/test-live.mjs` を再利用するため、Heartbeat と quiet-mode の挙動が一貫する - 例: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -819,184 +826,186 @@ env key に依存したい場合（例: `~/.profile` で export されている ## Docker ランナー（任意の「Linux でも動く」チェック） -これらの Docker ランナーは 2 つのカテゴリに分かれます: +これらの Docker ランナーは 2 つのカテゴリに分かれます。 - Live-model ランナー: `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 dir と workspace をマウントし（マウントされていれば `~/.profile` も source します）。対応するローカル entrypoint は `test:live:models-profiles` と `test:live:gateway-profiles` です。 -- Docker live ランナーは、フル Docker sweep を現実的に保つため、デフォルトでより小さいスモーク上限を使います: +- Docker live ランナーは、Docker での全体スイープを現実的に保つため、デフォルトでより小さな smoke 上限を使います: `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 vars を上書きしてください。 -- `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 イメージを一度ビルドし、その後 2 つの live Docker レーンでそれを再利用します。 +- コンテナ smoke ランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels`、および `test:docker:plugins` は、1 つ以上の実コンテナを起動し、より高レベルの統合パスを検証します。 -live-model Docker ランナーはまた、必要な CLI 認証ホームだけを bind-mount し（実行が絞り込まれていない場合はサポートされるものをすべて）、実行前にそれらをコンテナ home にコピーします。これにより、外部 CLI OAuth がホストの認証ストアを変更せずにトークンを更新できます。 +live-model Docker ランナーは、必要な CLI auth home のみ（実行が絞り込まれていない場合はサポート対象すべて）を bind mount し、実行前にそれらをコンテナ home へコピーするため、外部 CLI OAuth がホスト auth store を変更せずにトークンを更新できます。 - 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 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`） +- ACP bind smoke: `pnpm test:docker:live-acp-bind`（スクリプト: `scripts/test-live-acp-bind-docker.sh`） +- CLI backend smoke: `pnpm test:docker:live-cli-backend`（スクリプト: `scripts/test-live-cli-backend-docker.sh`） +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness`（スクリプト: `scripts/test-live-codex-harness-docker.sh`） - Gateway + dev agent: `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 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 の再起動セマンティクス）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） +- Open WebUI live smoke: `pnpm test:docker:openwebui`（スクリプト: `scripts/e2e/openwebui-docker.sh`） +- オンボーディングウィザード（TTY、完全なスキャフォールディング）: `pnpm test:docker:onboard`（スクリプト: `scripts/e2e/onboard-docker.sh`） +- Gateway networking（2 コンテナ、WS auth + health）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） +- MCP channel bridge（seeded Gateway + stdio bridge + 生の Claude notification-frame smoke）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） +- Plugins（install smoke + `/plugin` alias + Claude-bundle restart semantics）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） -live-model Docker ランナーはまた、現在の checkout を読み取り専用で bind-mount し、 -コンテナ内の一時 workdir にステージします。これにより、runtime -イメージをスリムに保ちつつ、正確にあなたのローカル source/config に対して Vitest を実行できます。 -ステージング手順では、大きなローカル専用キャッシュやアプリ build 出力、 -たとえば `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの `.build` や -Gradle 出力ディレクトリなどをスキップするため、Docker live 実行が -マシン固有 artifact のコピーに何分も費やすことはありません。 -また、これらは `OPENCLAW_SKIP_CHANNELS=1` を設定するため、 -コンテナ内で Gateway live probe が実際の Telegram/Discord などの channel worker を起動しません。 -`test:docker:live-models` は依然として `pnpm test:live` を実行するため、 +live-model Docker ランナーは、現在の checkout も読み取り専用で bind mount し、 +コンテナ内の一時 workdir にステージします。これにより、ランタイム +イメージをスリムに保ちながら、正確にあなたのローカル source/config に対して +Vitest を実行できます。 +ステージング手順では、大きなローカル専用キャッシュやアプリ build 出力、たとえば +`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの `.build` や +Gradle 出力ディレクトリをスキップするため、Docker live 実行がマシン固有の +artifact をコピーするのに何分も費やすことはありません。 +また、`OPENCLAW_SKIP_CHANNELS=1` も設定するため、Gateway live probe が +コンテナ内で実際の Telegram/Discord などのチャネルワーカーを起動しません。 +`test:docker:live-models` は引き続き `pnpm test:live` を実行するため、 その Docker レーンから Gateway -live カバレッジを絞り込むまたは除外したい場合は、`OPENCLAW_LIVE_GATEWAY_*` も渡してください。 -`test:docker:openwebui` は、より高レベルな互換性スモークです。これは -OpenAI 互換 HTTP endpoint を有効にした OpenClaw Gateway コンテナを起動し、 -その Gateway に向けて固定版の Open WebUI コンテナを起動し、Open WebUI 経由でサインインし、 +live カバレッジを絞り込む、または除外する必要がある場合は `OPENCLAW_LIVE_GATEWAY_*` も +渡してください。 +`test:docker:openwebui` は、より高レベルの互換性 smoke です。これにより +OpenAI 互換 HTTP endpoint を有効化した OpenClaw Gateway コンテナを起動し、 +その Gateway に対して固定版 Open WebUI コンテナを起動し、Open WebUI 経由でサインインし、 `/api/models` が `openclaw/default` を公開していることを確認し、その後 -Open WebUI の `/api/chat/completions` proxy を通じて実際の chat request を送信します。 -初回実行は、Docker が -Open WebUI イメージを pull する必要があったり、Open WebUI 自身のコールドスタート設定が完了する必要があるため、目に見えて遅くなることがあります。 -このレーンは、使用可能な live model key を想定しており、`OPENCLAW_PROFILE_FILE` -（デフォルトでは `~/.profile`）が Docker 化された実行でそれを提供する主な方法です。 -成功した実行では `{ "ok": true, "model": -"openclaw/default", ... }` のような小さな JSON payload が出力されます。 -`test:docker:mcp-channels` は意図的に決定論的であり、実際の -Telegram、Discord、または iMessage アカウントを必要としません。これは seed 済み Gateway -コンテナを起動し、`openclaw mcp serve` を起動する 2 つ目のコンテナを開始し、その後 -ルーティングされた conversation discovery、transcript 読み取り、attachment metadata、 -live event queue の挙動、outbound send routing、そして Claude スタイルの channel + -permission notification を、実際の stdio MCP bridge 上で検証します。notification チェックは -生の stdio MCP frame を直接検査するため、このスモークは、特定の client SDK がたまたま表面化するものではなく、 -bridge が実際に出力する内容を検証します。 +Open WebUI の `/api/chat/completions` proxy 経由で実際の chat request を送信します。 +初回実行は、Docker が Open WebUI イメージを pull する必要がある場合や、 +Open WebUI 自身が cold-start setup を完了する必要がある場合があるため、目に見えて遅くなることがあります。 +このレーンは使用可能な live model key を期待しており、Docker 化された実行で +それを提供する主な方法は `OPENCLAW_PROFILE_FILE` +（デフォルトは `~/.profile`）です。 +成功時の実行では、`{ "ok": true, "model": +"openclaw/default", ... }` のような小さな JSON payload を出力します。 +`test:docker:mcp-channels` は意図的に決定的であり、実際の +Telegram、Discord、または iMessage アカウントは不要です。これにより seed 済み Gateway +コンテナを起動し、`openclaw mcp serve` を spawn する 2 つ目のコンテナを起動し、 +その後、ルーティングされた会話検出、トランスクリプト読み取り、添付 metadata、 +live event queue の挙動、outbound send routing、および Claude 風の channel + +permission 通知を、実際の stdio MCP bridge 上で検証します。通知チェックは +生の stdio MCP frame を直接検査するため、この smoke は +特定の client SDK がたまたま表面化するものではなく、bridge が実際に出力するものを検証します。 -手動 ACP plain-language thread スモーク（CI ではない）: +手動 ACP 平文 thread smoke（CI ではない）: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- このスクリプトはリグレッション/デバッグのワークフロー用に維持してください。ACP thread routing の検証のために再度必要になる可能性があるので、削除しないでください。 +- このスクリプトはリグレッション/デバッグワークフロー用に保持してください。ACP thread routing 検証で再度必要になる可能性があるため、削除しないでください。 -便利な env vars: +便利な 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` にマウントされ、テスト実行前に source されます -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）は Docker 内でキャッシュされた CLI install 用に `/home/node/.npm-global` にマウントされます -- `$HOME` 配下の外部 CLI 認証 dir/file は、`/host-auth...` 配下に読み取り専用でマウントされ、テスト開始前に `/home/node/...` へコピーされます - - デフォルト dir: `.minimax` - - デフォルト file: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 絞り込まれた provider 実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推測された必要な dir/file のみをマウントします - - 手動で上書きするには `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストを使用してください +- `OPENCLAW_CONFIG_DIR=...`（デフォルト: `~/.openclaw`）を `/home/node/.openclaw` にマウント +- `OPENCLAW_WORKSPACE_DIR=...`（デフォルト: `~/.openclaw/workspace`）を `/home/node/.openclaw/workspace` にマウント +- `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`）を `/home/node/.profile` にマウントし、テスト実行前に source +- `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=...` -- コンテナ内の provider をフィルタするには `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` -- 再ビルド不要の再実行で既存の `openclaw:local-live` イメージを再利用するには `OPENCLAW_SKIP_DOCKER_BUILD=1` -- 認証情報が env ではなく profile store 由来であることを保証するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -- Open WebUI スモーク用に Gateway が公開する model を選ぶには `OPENCLAW_OPENWEBUI_MODEL=...` -- Open WebUI スモークで使用する nonce-check prompt を上書きするには `OPENCLAW_OPENWEBUI_PROMPT=...` -- 固定された Open WebUI image tag を上書きするには `OPENWEBUI_IMAGE=...` +- コンテナ内のプロバイダーをフィルタするには `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` +- 再ビルドが不要な再実行で既存の `openclaw:local-live` イメージを再利用するには `OPENCLAW_SKIP_DOCKER_BUILD=1` +- 認証情報が profile store 由来であることを保証するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`（env ではない） +- Open WebUI smoke 用に Gateway が公開する model を選ぶには `OPENCLAW_OPENWEBUI_MODEL=...` +- Open WebUI smoke が使う nonce-check prompt を上書きするには `OPENCLAW_OPENWEBUI_PROMPT=...` +- 固定版 Open WebUI image tag を上書きするには `OPENWEBUI_IMAGE=...` ## ドキュメントの健全性確認 ドキュメント編集後は docs チェックを実行してください: `pnpm check:docs`。 -インページ見出しチェックも必要な場合は、完全な Mintlify アンカー検証を実行してください: `pnpm docs:check-links:anchors`。 +ページ内見出しチェックも必要な場合は、完全な Mintlify anchor 検証を実行してください: `pnpm docs:check-links:anchors`。 ## オフラインリグレッション（CI 安全） -これらは、実 provider なしでの「実際のパイプライン」リグレッションです。 +これらは実際のプロバイダーを使わない「実パイプライン」リグレッションです。 -- Gateway tool calling（mock OpenAI、実際の Gateway + agent ループ）: `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"） +- Gateway tool calling（OpenAI は mock、Gateway + agent loop は実物）: `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」） -## agent 信頼性 evals（Skills） +## エージェント信頼性 eval（Skills） -すでに、次のような「agent 信頼性 evals」のように振る舞う CI 安全なテストがいくつかあります。 +すでに、いくつかの CI 安全なテストが「エージェント信頼性 eval」のように機能しています。 -- 実際の Gateway + agent ループを通る mock tool-calling（`src/gateway/gateway.test.ts`）。 -- session wiring と config 効果を検証する end-to-end の ウィザード フロー（`src/gateway/gateway.test.ts`）。 +- 実際の Gateway + agent loop を通した mock tool-calling（`src/gateway/gateway.test.ts`）。 +- セッション配線と config の影響を検証する end-to-end なウィザードフロー（`src/gateway/gateway.test.ts`）。 Skills 向けにまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: -- **Decisioning:** prompt に Skills が列挙されているとき、agent は正しい skill を選ぶか（または無関係なものを避けるか）？ -- **Compliance:** agent は使用前に `SKILL.md` を読み、必要な手順/引数に従うか？ -- **Workflow contracts:** tool の順序、session history の持ち越し、sandbox 境界を検証する multi-turn シナリオ。 +- **Decisioning:** prompt に Skills が列挙されているとき、エージェントは正しい Skill を選ぶか（または無関係なものを避けるか）？ +- **Compliance:** エージェントは使用前に `SKILL.md` を読み、必須の手順/引数に従うか？ +- **Workflow contracts:** ツール順序、セッション履歴の持ち越し、sandbox 境界を検証する複数ターンのシナリオ。 -将来の evals は、まず決定論的であるべきです。 +将来の eval は、まず決定的であるべきです。 -- tool call + 順序、skill file の読み取り、session wiring を検証するために mock provider を使う scenario runner。 -- skill に焦点を当てた小規模スイート（使う vs 使わない、gating、prompt injection）。 -- オプトインで env-gated な live evals は、CI 安全なスイートが整ってからにする。 +- mock provider を使って、tool call + 順序、Skill ファイルの読み取り、セッション配線を検証する scenario runner。 +- 小規模な Skill 特化シナリオスイート（使う vs 使わない、gating、prompt injection）。 +- CI 安全なスイートが整った後でのみ、任意の live eval（オプトイン、env でゲート）。 -## Contract テスト（Plugin と channel の形状） +## コントラクトテスト（plugin と channel の形状） -Contract テストは、登録されているすべての Plugin と channel がその -interface contract に準拠していることを検証します。これらは検出されたすべての Plugin を反復し、 -形状と挙動に関する一連のアサーションを実行します。デフォルトの `pnpm test` unit レーンは、 -これらの共有 seam および smoke ファイルを意図的にスキップします。共有 channel または provider の surface に触れた場合は、 -contract コマンドを明示的に実行してください。 +コントラクトテストは、登録されたすべての plugin と channel がその +インターフェースコントラクトに準拠していることを検証します。これらは検出されたすべての plugin を反復し、 +形状と挙動に関する一連の検証を実行します。デフォルトの `pnpm test` unit レーンは、 +これらの共有シームおよび smoke ファイルを意図的にスキップします。共有 channel または +provider サーフェスに触れた場合は、コントラクトコマンドを明示的に実行してください。 ### コマンド -- すべての contract: `pnpm test:contracts` -- channel contract のみ: `pnpm test:contracts:channels` -- provider contract のみ: `pnpm test:contracts:plugins` +- すべてのコントラクト: `pnpm test:contracts` +- channel コントラクトのみ: `pnpm test:contracts:channels` +- provider コントラクトのみ: `pnpm test:contracts:plugins` -### Channel contract +### Channel コントラクト `src/channels/plugins/contracts/*.contract.test.ts` にあります: - **plugin** - 基本的な Plugin 形状（id、name、capabilities） -- **setup** - セットアップ ウィザード 契約 -- **session-binding** - session binding の挙動 -- **outbound-payload** - message payload 構造 -- **inbound** - inbound message 処理 +- **setup** - セットアップウィザードコントラクト +- **session-binding** - セッション bind の挙動 +- **outbound-payload** - メッセージ payload 構造 +- **inbound** - inbound メッセージ処理 - **actions** - channel action handler - **threading** - thread ID 処理 - **directory** - directory/roster API -- **group-policy** - group policy 強制 +- **group-policy** - グループポリシー強制 -### Provider status contract +### Provider status コントラクト `src/plugins/contracts/*.contract.test.ts` にあります。 - **status** - channel status probe - **registry** - Plugin registry 形状 -### Provider contract +### Provider コントラクト `src/plugins/contracts/*.contract.test.ts` にあります: -- **auth** - 認証フロー契約 -- **auth-choice** - 認証選択 +- **auth** - auth フローコントラクト +- **auth-choice** - auth choice/selection - **catalog** - model catalog API - **discovery** - Plugin discovery - **loader** - Plugin loading - **runtime** - provider runtime -- **shape** - Plugin 形状/interface -- **wizard** - セットアップ ウィザード +- **shape** - Plugin 形状/インターフェース +- **wizard** - セットアップウィザード ### 実行するタイミング -- plugin-sdk の export または subpath を変更した後 +- plugin-sdk export または subpath を変更した後 - channel または provider Plugin を追加または変更した後 -- Plugin 登録または discovery をリファクタした後 +- Plugin 登録または discovery をリファクタリングした後 -Contract テストは CI で実行され、実際の API key は不要です。 +コントラクトテストは CI で実行され、実際の API key は不要です。 -## リグレッションを追加する（ガイダンス） +## リグレッション追加のガイダンス -live で見つかった provider/model の問題を修正するとき: +live で見つかった provider/model の問題を修正するときは: -- 可能なら CI 安全なリグレッションを追加する（mock/stub provider、または正確な request-shape 変換をキャプチャする） -- 本質的に live 専用なら（rate limit、認証ポリシーなど）、live テストは狭く保ち、env vars 経由のオプトインにする -- バグを捕まえられる最小のレイヤーを狙うことを優先する: +- 可能なら CI 安全なリグレッションを追加する（provider を mock/stub する、または正確な request-shape 変換をキャプチャする） +- 本質的に live 専用（rate limit、auth policy）なら、live テストを狭く保ち、env var 経由でオプトインにする +- バグを捕まえられる最小の層を狙うことを優先する: - provider の request conversion/replay バグ → direct models テスト - - Gateway の session/history/tool パイプラインバグ → Gateway live スモーク、または CI 安全な Gateway mock テスト -- SecretRef トラバーサルのガードレール: - - `src/secrets/exec-secret-ref-id-parity.test.ts` は、registry metadata（`listSecretTargetRegistryEntries()`）から SecretRef クラスごとに 1 つのサンプル target を導出し、トラバーサルセグメントの exec id が拒否されることを検証します。 - - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef target ファミリーを追加する場合は、そのテスト内の `classifyTargetClass` を更新してください。このテストは未分類の target id に対して意図的に失敗するため、新しいクラスが黙ってスキップされることを防ぎます。 + - Gateway の session/history/tool pipeline バグ → Gateway live smoke または CI 安全な Gateway mock テスト +- SecretRef 走査ガードレール: + - `src/secrets/exec-secret-ref-id-parity.test.ts` は、registry metadata（`listSecretTargetRegistryEntries()`）から各 SecretRef クラスごとに 1 つのサンプル target を導出し、その後 traversal-segment exec id が拒否されることを検証します。 + - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef target family を追加した場合は、そのテスト内の `classifyTargetClass` を更新してください。このテストは、未分類の target id で意図的に失敗するため、新しいクラスが黙ってスキップされることはありません。 diff --git a/docs/ja-JP/plugins/architecture.md b/docs/ja-JP/plugins/architecture.md index 3793d7458..fe9d8daa3 100644 --- a/docs/ja-JP/plugins/architecture.md +++ b/docs/ja-JP/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - ネイティブなOpenClaw Plugin を構築またはデバッグしている場合 - - Plugin のケイパビリティモデルや所有境界を理解したい場合 - - Plugin のロードパイプラインやレジストリに取り組んでいる場合 - - プロバイダのランタイムフックやチャネル Plugin を実装している場合 + - ネイティブな OpenClaw Plugin のビルドまたはデバッグ + - Plugin の機能モデルや所有権の境界を理解すること + - Plugin のロードパイプラインまたはレジストリに取り組むこと + - プロバイダーのランタイムフックやチャネル Plugin を実装すること sidebarTitle: Internals -summary: 'Plugin の内部: ケイパビリティモデル、所有権、コントラクト、ロードパイプライン、ランタイムヘルパー' +summary: 'Plugin の内部: 機能モデル、所有権、コントラクト、ロードパイプライン、ランタイムヘルパー' title: Plugin の内部 x-i18n: - generated_at: "2026-04-12T23:28:39Z" + generated_at: "2026-04-15T04:43:36Z" model: gpt-5.4 provider: openai - source_hash: 37361c1e9d2da57c77358396f19dfc7f749708b66ff68f1bf737d051b5d7675d + source_hash: f86798b5d2b0ad82d2397a52a6c21ed37fe6eee1dd3d124a9e4150c4f630b841 source_path: plugins/architecture.md workflow: 15 --- @@ -19,22 +19,21 @@ x-i18n: # Plugin の内部 - これは**詳細なアーキテクチャリファレンス**です。実践的なガイドについては、以下を参照してください: - - [Plugin のインストールと使用](/ja-JP/tools/plugin) — ユーザーガイド + これは**詳細なアーキテクチャリファレンス**です。実践的なガイドについては、以下を参照してください。 + - [Install and use plugins](/ja-JP/tools/plugin) — ユーザーガイド - [はじめに](/ja-JP/plugins/building-plugins) — 最初の Plugin チュートリアル - - [チャネル Plugin](/ja-JP/plugins/sdk-channel-plugins) — メッセージングチャネルを構築する - - [プロバイダ Plugin](/ja-JP/plugins/sdk-provider-plugins) — モデルプロバイダを構築する - - [SDK 概要](/ja-JP/plugins/sdk-overview) — インポートマップと登録 API + - [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) — メッセージングチャネルを構築する + - [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — モデルプロバイダーを構築する + - [SDK Overview](/ja-JP/plugins/sdk-overview) — インポートマップと登録 API -このページでは、OpenClaw Plugin システムの内部アーキテクチャを扱います。 +このページでは、OpenClaw の Plugin システムの内部アーキテクチャを扱います。 -## 公開ケイパビリティモデル +## 公開されている機能モデル -ケイパビリティは、OpenClaw 内における公開された**ネイティブ Plugin**モデルです。すべての -ネイティブ OpenClaw Plugin は、1つ以上のケイパビリティタイプに対して登録します: +Capabilities は、OpenClaw 内の公開された**ネイティブ Plugin**モデルです。すべてのネイティブ OpenClaw Plugin は、1 つ以上の capability type に対して登録されます。 -| Capability | 登録方法 | 例の Plugin | +| Capability | Registration method | Example plugins | | ---------------------- | ------------------------------------------------ | ------------------------------------ | | テキスト推論 | `api.registerProvider(...)` | `openai`, `anthropic` | | CLI 推論バックエンド | `api.registerCliBackend(...)` | `openai`, `anthropic` | @@ -49,137 +48,104 @@ x-i18n: | Web 検索 | `api.registerWebSearchProvider(...)` | `google` | | チャネル / メッセージング | `api.registerChannel(...)` | `msteams`, `matrix` | -ケイパビリティを1つも登録せず、フック、ツール、サービスを提供する -Plugin は、**レガシーな hook-only** Plugin です。このパターンは現在も完全にサポートされています。 +capability を 1 つも登録せず、hooks、tools、または services を提供する Plugin は、**レガシーな hook-only** Plugin です。このパターンも現在は完全にサポートされています。 -### 外部互換性に関する方針 +### 外部互換性の方針 -ケイパビリティモデルはすでにコアに導入されており、現在はバンドルされた/ネイティブな Plugin -で使われていますが、外部 Plugin 互換性については、「エクスポートされているのだから固定されている」 -よりも厳格な基準が依然として必要です。 +capability model はすでに core に導入されており、現在 bundled/native plugins で使用されていますが、外部 Plugin の互換性には、単に「export されているから凍結済み」というよりも厳密な基準が必要です。 現在のガイダンス: -- **既存の外部 Plugin:** フックベースの統合を動作し続けるようにする。これを - 互換性の基準線として扱う -- **新しいバンドル/ネイティブ Plugin:** ベンダー固有の直接到達や新しい hook-only 設計ではなく、 - 明示的なケイパビリティ登録を優先する -- **ケイパビリティ登録を採用する外部 Plugin:** 許可されるが、ドキュメントで明示的に安定した - コントラクトと示されない限り、ケイパビリティ固有のヘルパーサーフェスは進化中とみなす +- **既存の外部 Plugin:** hook ベースの統合が動作し続けるようにする。これを互換性の基準とみなす +- **新しい bundled/native plugins:** ベンダー固有の内部依存や新しい hook-only 設計よりも、明示的な capability registration を優先する +- **capability registration を採用する外部 Plugin:** 使用は可能だが、docs でその contract が stable と明示されていない限り、capability 固有の helper surface は進化中のものとして扱う -実践的なルール: +実用上のルール: -- ケイパビリティ登録 API は意図された方向性である -- 移行期間中、レガシーフックは外部 Plugin にとって最も破壊のない安全な経路であり続ける -- エクスポートされたヘルパーのサブパスはすべて同等ではない。偶発的なヘルパーエクスポートではなく、 - 文書化された狭いコントラクトを優先する +- capability registration APIs は意図された方向性である +- レガシー hooks は、移行期間中の外部 Plugin にとって最も破壊的変更の少ない安全な経路のままである +- export された helper subpath はすべて同等ではない。偶発的な helper export ではなく、文書化された狭い contract を優先する ### Plugin の形態 -OpenClaw は、読み込まれた各 Plugin を、実際の登録動作に基づいて形態分類します -（静的メタデータだけではありません）: +OpenClaw は、読み込まれた各 Plugin を、静的メタデータだけでなく実際の登録動作に基づいて形態分類します。 -- **plain-capability** -- ちょうど1種類のケイパビリティだけを登録する（たとえば - `mistral` のような provider-only Plugin） -- **hybrid-capability** -- 複数のケイパビリティタイプを登録する（たとえば - `openai` はテキスト推論、音声、メディア理解、画像 - 生成を所有する） -- **hook-only** -- フックのみを登録し（型付きまたはカスタム）、ケイパビリティ、 - ツール、コマンド、サービスは登録しない -- **non-capability** -- ツール、コマンド、サービス、またはルートを登録するが、 - ケイパビリティは登録しない +- **plain-capability** -- capability type をちょうど 1 つ登録する（たとえば `mistral` のような provider-only plugin） +- **hybrid-capability** -- 複数の capability type を登録する（たとえば `openai` は text inference、speech、media understanding、image generation を担う） +- **hook-only** -- hooks（typed または custom）のみを登録し、capabilities、tools、commands、services は登録しない +- **non-capability** -- tools、commands、services、または routes を登録するが、capabilities は登録しない -`openclaw plugins inspect ` を使うと、Plugin の形態とケイパビリティの -内訳を確認できます。詳細は [CLI リファレンス](/cli/plugins#inspect) を参照してください。 +Plugin の形態と capability の内訳は、`openclaw plugins inspect ` で確認できます。詳細は [CLI reference](/cli/plugins#inspect) を参照してください。 -### レガシーフック +### レガシー hooks -`before_agent_start` フックは、hook-only Plugin のための互換性経路として引き続きサポートされます。 -現実のレガシー Plugin は今もこれに依存しています。 +`before_agent_start` hook は、hook-only plugins のための互換性経路として引き続きサポートされています。現実のレガシー Plugin は依然としてこれに依存しています。 方向性: -- 動作し続けるようにする +- 動作し続けるように保つ - レガシーとして文書化する -- モデル/プロバイダのオーバーライド作業には `before_model_resolve` を優先する -- プロンプト変更作業には `before_prompt_build` を優先する -- 実際の利用が減少し、フィクスチャカバレッジで移行の安全性が証明されてから初めて削除する +- model/provider の上書き処理には `before_model_resolve` を優先する +- prompt の変更処理には `before_prompt_build` を優先する +- 実運用での使用が減り、fixture coverage によって安全な移行が証明されるまで削除しない ### 互換性シグナル -`openclaw doctor` または `openclaw plugins inspect ` を実行すると、 -次のいずれかのラベルが表示されることがあります: +`openclaw doctor` または `openclaw plugins inspect ` を実行すると、次のラベルのいずれかが表示されることがあります。 -| Signal | 意味 | +| Signal | Meaning | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | 設定は正常にパースされ、Plugin も解決される | -| **compatibility advisory** | Plugin がサポートされているが古いパターンを使っている（例: `hook-only`） | -| **legacy warning** | Plugin が `before_agent_start` を使っており、これは非推奨 | -| **hard error** | 設定が不正、または Plugin の読み込みに失敗した | +| **config valid** | Config が正常に解析され、plugins が解決される | +| **compatibility advisory** | Plugin がサポートされているが古いパターン（例: `hook-only`）を使用している | +| **legacy warning** | Plugin が `before_agent_start` を使用しており、これは非推奨である | +| **hard error** | Config が無効であるか、plugin のロードに失敗した | -`hook-only` も `before_agent_start` も、現時点ではあなたの Plugin を壊しません -- -`hook-only` は助言であり、`before_agent_start` は警告を出すだけです。これらの -シグナルは `openclaw status --all` と `openclaw plugins doctor` にも表示されます。 +`hook-only` も `before_agent_start` も、現時点であなたの Plugin を壊すことはありません。`hook-only` は advisory であり、`before_agent_start` は警告を出すだけです。これらのシグナルは `openclaw status --all` と `openclaw plugins doctor` にも表示されます。 ## アーキテクチャ概要 -OpenClaw の Plugin システムは4つのレイヤーを持ちます: +OpenClaw の Plugin システムには 4 つの層があります。 -1. **マニフェスト + ディスカバリ** - OpenClaw は、設定されたパス、ワークスペースルート、 - グローバル拡張ルート、およびバンドルされた拡張から候補 Plugin を見つけます。 - ディスカバリでは、まずネイティブの `openclaw.plugin.json` マニフェストと - サポートされるバンドルマニフェストを読み取ります。 -2. **有効化 + バリデーション** - コアは、発見された Plugin が有効、無効、ブロック済み、または - memory のような排他的スロットに選択されているかどうかを判断します。 -3. **ランタイム読み込み** - ネイティブ OpenClaw Plugin は jiti を通じてプロセス内で読み込まれ、 - 中央レジストリにケイパビリティを登録します。互換性のあるバンドルは - ランタイムコードをインポートせずにレジストリレコードへ正規化されます。 -4. **サーフェス消費** - OpenClaw の残りの部分は、レジストリを読み取ってツール、チャネル、プロバイダ - 設定、フック、HTTP ルート、CLI コマンド、サービスを公開します。 +1. **Manifest + discovery** + OpenClaw は、設定されたパス、workspace roots、global extension roots、bundled extensions から候補 Plugin を見つけます。discovery では、ネイティブの `openclaw.plugin.json` manifests と、サポートされる bundle manifests を最初に読み取ります。 +2. **Enablement + validation** + Core は、発見された Plugin が有効、無効、ブロック済み、または memory のような排他的スロットに選択されているかを判断します。 +3. **Runtime loading** + ネイティブ OpenClaw plugins は jiti 経由でプロセス内に読み込まれ、capabilities を中央レジストリに登録します。互換性のある bundles は、ランタイムコードを import せずに registry records に正規化されます。 +4. **Surface consumption** + OpenClaw の残りの部分は registry を読み取り、tools、channels、provider setup、hooks、HTTP routes、CLI commands、services を公開します。 -特に Plugin CLI については、ルートコマンドのディスカバリは2段階に分かれています: +特に plugin CLI では、root command discovery は 2 段階に分かれています。 -- パース時メタデータは `registerCli(..., { descriptors: [...] })` から取得される -- 実際の Plugin CLI モジュールは遅延読み込みのままにでき、最初の呼び出し時に登録される +- parse-time metadata は `registerCli(..., { descriptors: [...] })` から取得される +- 実際の plugin CLI module は lazy のままにでき、最初の呼び出し時に登録される -これにより、Plugin 所有の CLI コードを Plugin 内に保ちながらも、OpenClaw は -パース前にルートコマンド名を確保できます。 +これにより、plugin が所有する CLI code を plugin 内に保ちつつ、OpenClaw は parsing 前に root command 名を予約できます。 -重要な設計上の境界: +重要な設計境界は次のとおりです。 -- ディスカバリ + 設定バリデーションは、Plugin コードを実行せずに - **manifest/schema メタデータ**から動作できるべきである -- ネイティブのランタイム動作は、Plugin モジュールの `register(api)` パスから来る +- discovery + config validation は、Plugin code を実行せずに **manifest/schema metadata** から動作するべきである +- ネイティブな runtime behavior は plugin module の `register(api)` path から得られる -この分離により、OpenClaw は、完全なランタイムが有効になる前に、 -設定を検証し、不足/無効な Plugin を説明し、UI/schema のヒントを構築できます。 +この分離により、OpenClaw は完全な runtime が有効になる前に、config の検証、欠落または無効な plugins の説明、UI/schema hints の構築を行えます。 -### チャネル Plugin と共有 message ツール +### Channel Plugins と共有 `message` tool -チャネル Plugin は、通常のチャットアクションのために別個の send/edit/react ツールを -登録する必要はありません。OpenClaw はコアに1つの共有 `message` ツールを保持し、 -チャネル Plugin はその背後にあるチャネル固有のディスカバリと実行を所有します。 +Channel plugins は、通常のチャット操作のために別個の send/edit/react tool を登録する必要はありません。OpenClaw は core に 1 つの共有 `message` tool を保持し、channel plugins はその背後にあるチャネル固有の discovery と execution を担います。 -現在の境界は次のとおりです: +現在の境界は次のとおりです。 -- コアは共有 `message` ツールホスト、プロンプト配線、セッション/スレッドの - 台帳管理、および実行ディスパッチを所有する -- チャネル Plugin はスコープ付きアクションディスカバリ、ケイパビリティディスカバリ、 - およびチャネル固有のスキーマ断片を所有する -- チャネル Plugin は、会話 ID がどのようにスレッド ID をエンコードするか、 - または親会話から継承するかといった、プロバイダ固有のセッション会話文法を所有する -- チャネル Plugin は、そのアクションアダプタを通じて最終アクションを実行する +- core は共有 `message` tool host、prompt wiring、session/thread bookkeeping、execution dispatch を担う +- channel plugins はスコープ付き action discovery、capability discovery、およびチャネル固有の schema fragments を担う +- channel plugins は、会話 ID が thread ID をどのようにエンコードするか、または親会話からどのように継承するかといった、プロバイダー固有の session conversation grammar を担う +- channel plugins は action adapter を通じて最終 action を実行する -チャネル Plugin に対する SDK サーフェスは -`ChannelMessageActionAdapter.describeMessageTool(...)` です。この統合されたディスカバリ -呼び出しにより、Plugin は可視アクション、ケイパビリティ、およびスキーマへの貢献を -まとめて返せるため、それらの要素がばらばらになりません。 +channel plugins に対する SDK surface は `ChannelMessageActionAdapter.describeMessageTool(...)` です。この統一された discovery call により、Plugin は表示される actions、capabilities、schema contributions をまとめて返せるため、それらの要素がずれないようにできます。 -コアはそのディスカバリ手順にランタイムスコープを渡します。重要なフィールドには次が含まれます: +チャネル固有の message-tool param がローカルパスやリモート media URL のような media source を含む場合、Plugin は `describeMessageTool(...)` から `mediaSourceParams` も返すべきです。Core はこの明示的なリストを使って、plugin が所有する param 名をハードコードすることなく、sandbox path normalization と outbound media-access hints を適用します。 +そこではチャネル全体の単一のフラットリストではなく、action 単位の map を優先してください。そうしないと、profile 専用の media param が `send` のような無関係な action でも正規化されてしまいます。 + +Core は runtime scope をその discovery step に渡します。重要な fields には次が含まれます。 - `accountId` - `currentChannelId` @@ -188,126 +154,88 @@ OpenClaw の Plugin システムは4つのレイヤーを持ちます: - `sessionKey` - `sessionId` - `agentId` -- 信頼された受信 `requesterSenderId` +- 信頼された受信元の `requesterSenderId` -これはコンテキスト依存の Plugin にとって重要です。チャネルは、アクティブなアカウント、 -現在のルーム/スレッド/メッセージ、または信頼された要求者 ID に基づいて、 -コアの `message` ツールにチャネル固有の分岐をハードコードすることなく、 -メッセージアクションを隠したり公開したりできます。 +これはコンテキスト依存の plugins にとって重要です。チャネルは、core `message` tool にチャネル固有の分岐をハードコードすることなく、アクティブな account、現在の room/thread/message、または信頼された requester identity に基づいて message actions を隠したり公開したりできます。 -このため、embedded-runner のルーティング変更も依然として Plugin 側の作業です。ランナーは、 -現在のチャット/セッション ID を Plugin ディスカバリ境界へ転送し、 -共有 `message` ツールが現在のターンに適したチャネル所有のサーフェスを -公開できるようにする責任を持ちます。 +これが、embedded-runner の routing 変更が依然として plugin の作業である理由です。runner は、共有 `message` tool が現在の turn に対して適切なチャネル所有の surface を公開できるように、現在の chat/session identity を plugin discovery boundary に転送する責任を負います。 -チャネル所有の実行ヘルパーについては、バンドルされた Plugin は実行ランタイムを -自分たちの拡張モジュール内に保持すべきです。コアはもはや Discord、 -Slack、Telegram、WhatsApp の message-action ランタイムを `src/agents/tools` 配下で所有しません。 -別個の `plugin-sdk/*-action-runtime` サブパスは公開しておらず、バンドルされた -Plugin は自分たちのローカルなランタイムコードを、拡張所有モジュールから -直接インポートすべきです。 +channel が所有する execution helpers については、bundled plugins は execution runtime を自分たちの extension modules 内に保持すべきです。Core はもはや `src/agents/tools` 配下の Discord、Slack、Telegram、WhatsApp の message-action runtimes を所有していません。 +また、別個の `plugin-sdk/*-action-runtime` subpath も公開しておらず、bundled plugins は自分たちが所有する extension modules からローカルの runtime code を直接 import するべきです。 -同じ境界は、一般にプロバイダ名付き SDK シームにも適用されます。コアは Slack、 -Discord、Signal、WhatsApp、または類似拡張向けのチャネル固有 convenience barrel を -インポートすべきではありません。コアがある動作を必要とする場合は、バンドルされた -Plugin 自身の `api.ts` / `runtime-api.ts` barrel を利用するか、必要性を共有 SDK の -狭い汎用ケイパビリティへ昇格させてください。 +同じ境界は、一般に provider 名付き SDK seams にも適用されます。core は Slack、Discord、Signal、WhatsApp、または類似の extensions 向けのチャネル固有 convenience barrel を import すべきではありません。core がある behavior を必要とする場合は、bundled plugin 自身の `api.ts` / `runtime-api.ts` barrel を利用するか、その必要性を共有 SDK の狭い汎用 capability に昇格させてください。 -poll については、特に2つの実行経路があります: +polls については、特に 2 つの execution path があります。 -- `outbound.sendPoll` は、共通の poll モデルに適合するチャネル向けの共有ベースライン -- `actions.handleAction("poll")` は、チャネル固有の poll セマンティクスや追加の - poll パラメータ向けの推奨経路 +- `outbound.sendPoll` は共通の poll model に適合するチャネル向けの共有ベースラインである +- `actions.handleAction("poll")` はチャネル固有の poll semantics や追加の poll parameters に対する推奨経路である -コアは現在、Plugin 側の poll ディスパッチがアクションを拒否した後まで共有 poll パースを -遅延させています。これにより、Plugin 所有の poll ハンドラは、汎用 poll パーサに先に -ブロックされることなく、チャネル固有の poll フィールドを受け入れられます。 +Core は現在、plugin の poll dispatch が action を拒否した後まで共有 poll parsing を遅延させています。これにより、plugin が所有する poll handlers は、先に汎用 poll parser に妨げられることなく、チャネル固有の poll fields を受け取れます。 -完全な起動シーケンスについては、[ロードパイプライン](#load-pipeline) を参照してください。 +完全な起動シーケンスについては、[Load pipeline](#load-pipeline) を参照してください。 -## ケイパビリティ所有モデル +## Capability ownership model -OpenClaw は、ネイティブ Plugin を、無関係な統合の寄せ集めではなく、 -**企業**または**機能**の所有境界として扱います。 +OpenClaw は、ネイティブ Plugin を、無関係な統合の寄せ集めではなく、**会社**または**機能**の所有境界として扱います。 -これは次を意味します: +つまり、次のことを意味します。 -- 企業 Plugin は、通常、その企業に属する OpenClaw 向けのサーフェス全体を所有すべきである -- 機能 Plugin は、通常、自らが導入する機能サーフェス全体を所有すべきである -- チャネルは、プロバイダの動作を場当たり的に再実装するのではなく、 - 共有コアケイパビリティを利用すべきである +- 会社 Plugin は通常、その会社に関する OpenClaw 向けの surface をすべて所有するべきである +- 機能 Plugin は通常、自身が導入する完全な機能 surface を所有するべきである +- channels は、provider behavior を場当たり的に再実装するのではなく、共有 core capabilities を利用するべきである 例: -- バンドルされた `openai` Plugin は、OpenAI モデルプロバイダ動作と、OpenAI の - 音声 + リアルタイム音声 + メディア理解 + 画像生成動作を所有する -- バンドルされた `elevenlabs` Plugin は、ElevenLabs の音声動作を所有する -- バンドルされた `microsoft` Plugin は、Microsoft の音声動作を所有する -- バンドルされた `google` Plugin は、Google モデルプロバイダ動作に加えて、 - Google のメディア理解 + 画像生成 + Web 検索動作を所有する -- バンドルされた `firecrawl` Plugin は、Firecrawl の Web 取得動作を所有する -- バンドルされた `minimax`、`mistral`、`moonshot`、`zai` Plugin は、 - それぞれのメディア理解バックエンドを所有する -- バンドルされた `qwen` Plugin は、Qwen テキストプロバイダ動作に加えて、 - メディア理解および動画生成動作を所有する -- `voice-call` Plugin は機能 Plugin です。通話トランスポート、ツール、 - CLI、ルート、および Twilio メディアストリームブリッジを所有しますが、 - ベンダー Plugin を直接インポートする代わりに、共有の音声、 - リアルタイム文字起こし、およびリアルタイム音声ケイパビリティを利用します +- bundled の `openai` Plugin は、OpenAI の model-provider behavior と、OpenAI の speech + realtime-voice + media-understanding + image-generation behavior を所有する +- bundled の `elevenlabs` Plugin は、ElevenLabs の speech behavior を所有する +- bundled の `microsoft` Plugin は、Microsoft の speech behavior を所有する +- bundled の `google` Plugin は、Google の model-provider behavior と、Google の media-understanding + image-generation + web-search behavior を所有する +- bundled の `firecrawl` Plugin は、Firecrawl の web-fetch behavior を所有する +- bundled の `minimax`、`mistral`、`moonshot`、`zai` Plugins は、それぞれの media-understanding backend を所有する +- bundled の `qwen` Plugin は、Qwen の text-provider behavior と、media-understanding および video-generation behavior を所有する +- `voice-call` Plugin は機能 Plugin である。call transport、tools、CLI、routes、Twilio media-stream bridging を所有するが、vendor plugins を直接 import する代わりに、共有の speech と realtime-transcription および realtime-voice capabilities を利用する -意図された最終状態は次のとおりです: +意図されている最終状態は次のとおりです。 -- OpenAI は、テキストモデル、音声、画像、将来の - 動画にまたがっていても、1つの Plugin に存在する -- 別のベンダーも、自身のサーフェス領域に対して同じことができる -- チャネルは、どのベンダー Plugin がそのプロバイダを所有しているかを気にしない。コアが公開する - 共有ケイパビリティコントラクトを利用する +- OpenAI は、text models、speech、images、将来の video にまたがる場合でも、1 つの Plugin に存在する +- 別の vendor も、自身の surface area に対して同じことができる +- channels は、どの vendor plugin が provider を所有しているかを気にせず、core が公開する共有 capability contract を利用する -これが重要な区別です: +これが重要な区別です。 -- **plugin** = 所有境界 -- **capability** = 複数の Plugin が実装または利用できるコアコントラクト +- **plugin** = 所有権の境界 +- **capability** = 複数の plugins が実装または利用できる core contract -したがって、OpenClaw が動画のような新しい領域を追加する場合、最初の問いは -「どのプロバイダが動画処理をハードコードすべきか」ではありません。最初の問いは「コアの -動画ケイパビリティコントラクトとは何か」です。そのコントラクトが存在すれば、 -ベンダー Plugin はそれに対して登録でき、チャネル/機能 Plugin はそれを利用できます。 +したがって、OpenClaw が video のような新しい domain を追加する場合、最初の問いは「どの provider が video handling をハードコードすべきか？」ではありません。最初の問いは「core の video capability contract は何か？」です。その contract が存在すれば、vendor plugins はそれに対して登録でき、channel/feature plugins はそれを利用できます。 -そのケイパビリティがまだ存在しない場合、通常は次のように進めるのが正しい動きです: +その capability がまだ存在しない場合、通常取るべき対応は次のとおりです。 -1. コアで不足しているケイパビリティを定義する -2. それを型付きで Plugin API/ランタイムから公開する -3. そのケイパビリティに対してチャネル/機能を接続する -4. ベンダー Plugin に実装を登録させる +1. core で不足している capability を定義する +2. それを型付きで plugin API/runtime を通じて公開する +3. channels/features をその capability に対して接続する +4. vendor plugins に実装を登録させる -これにより、所有権を明示したまま、単一ベンダーや単発の Plugin 固有コードパスに依存する -コア動作を避けられます。 +これにより、所有権を明示したまま、単一 vendor や一回限りの plugin 固有 code path に依存する core behavior を避けられます。 -### ケイパビリティのレイヤリング +### Capability layering -コードをどこに置くべきか判断するときは、次のメンタルモデルを使ってください: +コードをどこに置くべきかを判断する際には、次のメンタルモデルを使ってください。 -- **コアケイパビリティ層**: 共有のオーケストレーション、ポリシー、フォールバック、設定 - マージルール、配信セマンティクス、型付きコントラクト -- **ベンダー Plugin 層**: ベンダー固有 API、認証、モデルカタログ、音声 - 合成、画像生成、将来の動画バックエンド、使用量エンドポイント -- **チャネル/機能 Plugin 層**: Slack/Discord/voice-call などの統合で、 - コアケイパビリティを利用し、それをあるサーフェスとして提示する +- **core capability layer**: 共有の orchestration、policy、fallback、config merge rules、delivery semantics、型付き contracts +- **vendor plugin layer**: vendor 固有の APIs、auth、model catalogs、speech synthesis、image generation、将来の video backends、usage endpoints +- **channel/feature plugin layer**: core capabilities を利用し、それを surface 上に提示する Slack/Discord/voice-call などの統合 -たとえば、TTS は次の形に従います: +たとえば、TTS は次の形になります。 -- コアは返信時 TTS のポリシー、フォールバック順序、設定、チャネル配信を所有する -- `openai`、`elevenlabs`、`microsoft` は合成実装を所有する -- `voice-call` は電話向け TTS ランタイムヘルパーを利用する +- core は reply-time の TTS policy、fallback order、prefs、channel delivery を所有する +- `openai`、`elevenlabs`、`microsoft` は synthesis implementations を所有する +- `voice-call` は telephony TTS runtime helper を利用する -将来のケイパビリティについても、同じパターンを優先すべきです。 +将来の capabilities に対しても、同じパターンを優先すべきです。 -### 複数ケイパビリティを持つ企業 Plugin の例 +### 複数 capability を持つ company Plugin の例 -企業 Plugin は、外から見たときに一貫性があるべきです。OpenClaw に、モデル、音声、 -リアルタイム文字起こし、リアルタイム音声、メディア理解、画像生成、 -動画生成、Web 取得、Web 検索の共有コントラクトがあるなら、 -ベンダーは自身のサーフェスを1か所でまとめて所有できます: +company Plugin は、外側から見て一貫性があるように感じられるべきです。OpenClaw に models、speech、realtime transcription、realtime voice、media understanding、image generation、video generation、web fetch、web search の共有 contracts があるなら、vendor はそれらすべての surface を 1 か所で所有できます。 ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -361,243 +289,187 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -重要なのは、正確なヘルパー名ではありません。形が重要です: +重要なのは、helper 名が正確に何であるかではありません。重要なのは形です。 -- 1つの Plugin がそのベンダーサーフェスを所有する -- それでもコアはケイパビリティコントラクトを所有する -- チャネルと機能 Plugin は、ベンダーコードではなく `api.runtime.*` ヘルパーを利用する -- コントラクトテストで、その Plugin が自身が所有すると主張するケイパビリティを - 登録したことを検証できる +- 1 つの Plugin が vendor surface を所有する +- それでも core は capability contracts を所有する +- channels と feature plugins は vendor code ではなく `api.runtime.*` helpers を利用する +- contract tests は、その Plugin が所有すると主張する capabilities を登録したことを検証できる -### ケイパビリティの例: 動画理解 +### Capability の例: video understanding -OpenClaw はすでに、画像/音声/動画理解を1つの共有 -ケイパビリティとして扱っています。そこでも同じ所有モデルが適用されます: +OpenClaw はすでに image/audio/video understanding を 1 つの共有 capability として扱っています。そこでも同じ所有モデルが適用されます。 -1. コアが media-understanding コントラクトを定義する -2. ベンダー Plugin が、必要に応じて `describeImage`、`transcribeAudio`、および - `describeVideo` を登録する -3. チャネルと機能 Plugin は、ベンダーコードへ直接接続するのではなく、 - 共有コア動作を利用する +1. core が media-understanding contract を定義する +2. vendor plugins が、該当する場合は `describeImage`、`transcribeAudio`、`describeVideo` を登録する +3. channels と feature plugins は、vendor code に直接接続する代わりに、共有された core behavior を利用する -これにより、あるプロバイダの動画に関する前提をコアへ焼き付けずに済みます。Plugin が -ベンダーサーフェスを所有し、コアがケイパビリティコントラクトとフォールバック動作を -所有します。 +これにより、ある provider の video に関する前提を core に埋め込むことを避けられます。Plugin は vendor surface を所有し、core は capability contract と fallback behavior を所有します。 -動画生成もすでに同じ流れを使っています。コアが型付き -ケイパビリティコントラクトとランタイムヘルパーを所有し、ベンダー Plugin が -`api.registerVideoGenerationProvider(...)` 実装をそれに対して登録します。 +video generation もすでに同じ流れを使っています。core が型付き capability contract と runtime helper を所有し、vendor plugins はそれに対して `api.registerVideoGenerationProvider(...)` の実装を登録します。 -具体的なロールアウト用チェックリストが必要ですか? 参照: -[Capability Cookbook](/ja-JP/plugins/architecture)。 +具体的な rollout checklist が必要ですか。 [Capability Cookbook](/ja-JP/plugins/architecture) を参照してください。 ## コントラクトと強制 -Plugin API サーフェスは、意図的に型付きかつ `OpenClawPluginApi` に -集約されています。このコントラクトが、サポートされる登録ポイントと、 -Plugin が依存してよいランタイムヘルパーを定義します。 +plugin API surface は、意図的に `OpenClawPluginApi` に集約され、型付けされています。この contract は、サポートされる registration points と、Plugin が依存してよい runtime helpers を定義します。 これが重要な理由: -- Plugin 作者は、1つの安定した内部標準を得られる -- コアは、2つの Plugin が同じ - provider id を登録するような重複所有を拒否できる -- 起動時に、不正な登録に対して実行可能な診断を表示できる -- コントラクトテストで、バンドルされた Plugin の所有権を強制し、静かなドリフトを防げる +- Plugin 作成者は、安定した単一の内部標準を得られる +- core は、2 つの plugins が同じ provider id を登録するような重複した所有を拒否できる +- 起動時に、不正な registration に対して実用的な diagnostics を表示できる +- contract tests により、bundled-plugin の所有権を強制し、静かな drift を防げる -強制には2つのレイヤーがあります: +強制には 2 つの層があります。 -1. **ランタイム登録の強制** - Plugin レジストリは、Plugin の読み込み時に登録内容を検証します。例: - 重複した provider id、重複した speech provider id、不正な - 登録は、未定義動作ではなく Plugin 診断を生成します。 -2. **コントラクトテスト** - バンドルされた Plugin は、テスト実行中にコントラクトレジストリへ取り込まれるため、 - OpenClaw は所有権を明示的に検証できます。現在これは、モデル - プロバイダ、speech プロバイダ、Web 検索プロバイダ、およびバンドル登録の - 所有権に使われています。 +1. **runtime registration enforcement** + plugin registry は、plugins のロード時に registrations を検証します。例: 重複した provider ids、重複した speech provider ids、不正な registrations は、未定義動作ではなく plugin diagnostics を生成します。 +2. **contract tests** + bundled plugins は、テスト実行中に contract registries に記録されるため、OpenClaw は所有権を明示的に検証できます。現在、これは model providers、speech providers、web search providers、bundled registration ownership に使用されています。 -実際の効果として、OpenClaw は、どの Plugin がどの -サーフェスを所有しているかをあらかじめ把握できます。これにより、所有権が暗黙ではなく -宣言され、型付けされ、テスト可能であるため、コアとチャネルはシームレスに構成できます。 +実際の効果として、OpenClaw は、どの Plugin がどの surface を所有しているかを事前に把握できます。これにより、所有権が暗黙的ではなく、宣言され、型付けされ、テスト可能であるため、core と channels をシームレスに組み合わせられます。 ### コントラクトに含めるべきもの -良い Plugin コントラクトは次の特徴を持ちます: +良い plugin contracts は次の性質を持ちます。 - 型付き - 小さい -- ケイパビリティ固有 -- コアが所有する -- 複数の Plugin で再利用できる -- ベンダー知識なしでチャネル/機能が利用できる +- capability 固有 +- core が所有する +- 複数の plugins で再利用できる +- vendor の知識なしに channels/features から利用できる -悪い Plugin コントラクトは次のようなものです: +悪い plugin contracts は次のようなものです。 -- コア内に隠されたベンダー固有ポリシー -- レジストリを迂回する単発の Plugin 用抜け道 -- ベンダー実装へ直接到達するチャネルコード -- `OpenClawPluginApi` や - `api.runtime` の一部ではない、その場しのぎのランタイムオブジェクト +- core に隠された vendor 固有の policy +- registry を迂回する、一回限りの plugin 用 escape hatch +- vendor implementation に直接到達する channel code +- `OpenClawPluginApi` や `api.runtime` の一部ではない ad hoc な runtime objects -迷ったら、抽象度を1段引き上げてください。まずケイパビリティを定義し、その後で -Plugin がそこへ接続できるようにします。 +迷ったら、抽象化のレベルを上げてください。まず capability を定義し、その後で plugins がそこに接続できるようにします。 ## 実行モデル -ネイティブ OpenClaw Plugin は、Gateway と**同一プロセス内**で実行されます。サンドボックス化は -されていません。読み込まれたネイティブ Plugin は、コアコードと同じ -プロセスレベルの信頼境界を持ちます。 +ネイティブ OpenClaw plugins は、Gateway と**同一プロセス内**で実行されます。sandbox 化はされていません。ロードされたネイティブ Plugin は、core code と同じプロセスレベルの信頼境界を持ちます。 -含意: +影響: -- ネイティブ Plugin は、ツール、ネットワークハンドラ、フック、サービスを登録できる -- ネイティブ Plugin のバグで gateway がクラッシュしたり不安定化したりする可能性がある -- 悪意あるネイティブ Plugin は、OpenClaw プロセス内での任意コード実行と等価である +- ネイティブ Plugin は tools、network handlers、hooks、services を登録できる +- ネイティブ Plugin のバグは gateway をクラッシュさせたり不安定化させたりできる +- 悪意あるネイティブ Plugin は、OpenClaw process 内での任意コード実行と同等である -互換バンドルは、OpenClaw が現在それらを -メタデータ/コンテンツパックとして扱っているため、デフォルトではより安全です。現行リリースでは、これは主に -バンドルされた Skills を意味します。 +互換 bundles は、OpenClaw が現在それらを metadata/content packs として扱うため、デフォルトではより安全です。現在のリリースでは、それは主に bundled skills を意味します。 -バンドルされていない Plugin には、allowlist と明示的な install/load パスを使用してください。ワークスペース -Plugin は本番デフォルトではなく、開発時コードとして扱ってください。 +bundled ではない plugins には、allowlists と明示的な install/load paths を使用してください。workspace plugins は本番デフォルトではなく、開発時の code として扱ってください。 -バンドルされたワークスペース package 名では、Plugin id を npm 名に -固定してください。デフォルトは `@openclaw/`、またはその package が意図的により狭い -Plugin ロールを公開する場合に限り、承認済みの型付き接尾辞 -`-provider`、`-plugin`、`-speech`、`-sandbox`、`-media-understanding` を使います。 +bundled workspace package names では、plugin id を npm name に固定してください。デフォルトは `@openclaw/`、または package が意図的により狭い plugin role を公開する場合は `-provider`、`-plugin`、`-speech`、`-sandbox`、`-media-understanding` のような承認済み typed suffix を使います。 -重要な信頼上の注意: +重要な信頼に関する注意: -- `plugins.allow` が信頼するのは**plugin id**であり、ソースの来歴ではありません。 -- バンドルされた Plugin と同じ id を持つワークスペース Plugin は、そのワークスペース Plugin が - 有効化/allowlist されている場合、意図的にバンドル版をシャドーします。 -- これは正常であり、ローカル開発、パッチテスト、hotfix に有用です。 +- `plugins.allow` が信頼するのは**plugin ids**であり、ソースの provenance ではない。 +- bundled plugin と同じ id を持つ workspace plugin は、その workspace plugin が enabled/allowlisted されると、意図的に bundled copy を shadow する。 +- これは正常であり、ローカル開発、patch testing、hotfixes に有用である。 -## エクスポート境界 +## Export boundary -OpenClaw がエクスポートするのは、実装上の convenience ではなくケイパビリティです。 +OpenClaw は implementation convenience ではなく、capabilities を export します。 -ケイパビリティ登録は公開のままにし、非コントラクトのヘルパーエクスポートは削減してください: +capability registration は public のままにし、非 contract の helper exports は削減してください。 -- バンドル Plugin 固有のヘルパーサブパス -- 公開 API を意図していないランタイム配管サブパス -- ベンダー固有の convenience ヘルパー -- 実装詳細である setup/onboarding ヘルパー +- bundled-plugin 固有の helper subpaths +- public API を意図していない runtime plumbing subpaths +- vendor 固有の convenience helpers +- 実装詳細である setup/onboarding helpers -一部のバンドル Plugin ヘルパーサブパスは、互換性とバンドル Plugin 保守のために、 -生成された SDK エクスポートマップにまだ残っています。現在の例には -`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 -`plugin-sdk/zalo-setup`、およびいくつかの `plugin-sdk/matrix*` シームが含まれます。これらは、 -新しいサードパーティ Plugin に推奨される SDK パターンではなく、予約された実装詳細エクスポートとして -扱ってください。 +bundled-plugin の一部 helper subpaths は、互換性と bundled-plugin メンテナンスのために、生成された SDK export map にまだ残っています。現在の例には `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`、およびいくつかの `plugin-sdk/matrix*` seams が含まれます。これらは、新しいサードパーティ plugins 向けの推奨 SDK パターンではなく、予約された実装詳細 export として扱ってください。 -## ロードパイプライン +## Load pipeline -起動時、OpenClaw はおおむね次の処理を行います: +起動時に、OpenClaw はおおむね次のことを行います。 -1. 候補 Plugin ルートを発見する -2. ネイティブまたは互換バンドルのマニフェストと package メタデータを読む -3. 安全でない候補を拒否する -4. Plugin 設定（`plugins.enabled`、`allow`、`deny`、`entries`、 - `slots`、`load.paths`）を正規化する -5. 各候補の有効化可否を決定する -6. 有効なネイティブモジュールを jiti 経由で読み込む -7. ネイティブの `register(api)`（またはレガシーエイリアスである `activate(api)`）フックを呼び出し、登録内容を Plugin レジストリへ収集する -8. そのレジストリをコマンド/ランタイムサーフェスに公開する +1. 候補 plugin roots を検出する +2. ネイティブまたは互換 bundle の manifests と package metadata を読み取る +3. 安全でない candidates を拒否する +4. plugin config（`plugins.enabled`、`allow`、`deny`、`entries`、`slots`、`load.paths`）を正規化する +5. 各 candidate の enablement を決定する +6. 有効なネイティブ modules を jiti 経由で読み込む +7. ネイティブの `register(api)`（またはレガシーな別名である `activate(api)`）hooks を呼び出し、registrations を plugin registry に収集する +8. commands/runtime surfaces に registry を公開する -`activate` は `register` のレガシーエイリアスです — ローダーは存在する方（`def.register ?? def.activate`）を解決し、同じタイミングで呼び出します。すべてのバンドル Plugin は `register` を使っています。新しい Plugin では `register` を優先してください。 +`activate` は `register` のレガシーな別名です。loader は存在する方（`def.register ?? def.activate`）を解決して同じタイミングで呼び出します。bundled plugins はすべて `register` を使用しています。新しい plugins では `register` を優先してください。 -安全ゲートは、ランタイム実行**前**に行われます。エントリが Plugin ルート外へ -エスケープする場合、パスが world-writable の場合、またはバンドルされていない Plugin について -パス所有権が不審に見える場合、その候補はブロックされます。 +安全ゲートは、runtime execution の**前**に発生します。entry が plugin root の外に出ている場合、path が world-writable の場合、または bundled ではない plugins に対して path ownership が疑わしい場合、candidates はブロックされます。 -### マニフェストファーストの動作 +### Manifest-first behavior -マニフェストは、コントロールプレーンの信頼できる情報源です。OpenClaw はこれを使って次を行います: +manifest は control-plane の source of truth です。OpenClaw はそれを次の目的に使います。 -- Plugin を識別する -- 宣言されたチャネル/Skills/設定スキーマまたはバンドルケイパビリティを発見する +- plugin を識別する +- 宣言された channels/skills/config schema または bundle capabilities を検出する - `plugins.entries..config` を検証する -- Control UI のラベル/プレースホルダを補強する -- install/catalog メタデータを表示する -- Plugin ランタイムを読み込まずに、軽量な activation と setup 記述子を保持する +- Control UI の labels/placeholders を補強する +- install/catalog metadata を表示する +- plugin runtime を読み込まずに、軽量な activation と setup descriptors を保持する -ネイティブ Plugin では、ランタイムモジュールがデータプレーン部分です。そこではフック、ツール、コマンド、 -またはプロバイダフローのような実際の動作が登録されます。 +ネイティブ plugins では、runtime module が data-plane 部分です。そこでは hooks、tools、commands、provider flows などの実際の behavior を登録します。 -オプションのマニフェスト `activation` および `setup` ブロックは、コントロールプレーンに留まります。 -これらは activation 計画と setup ディスカバリのためのメタデータ専用記述子であり、 -ランタイム登録、`register(...)`、または `setupEntry` を置き換えるものではありません。 -最初のライブ activation コンシューマは現在、マニフェストの command、channel、provider ヒントを使って、 -より広いレジストリ実体化の前に Plugin ロードを絞り込みます: +任意の manifest `activation` および `setup` blocks は control plane に留まります。これらは activation planning と setup discovery のための metadata-only descriptors であり、runtime registration、`register(...)`、または `setupEntry` を置き換えるものではありません。 +最初の live activation consumers では、manifest の command、channel、provider hints を使って、より広い registry materialization の前に plugin loading を絞り込むようになっています。 -- CLI ロードは、要求された主要コマンドを所有する Plugin に絞り込まれる -- チャネル setup/Plugin 解決は、要求された - channel id を所有する Plugin に絞り込まれる -- 明示的なプロバイダ setup/ランタイム解決は、要求された - provider id を所有する Plugin に絞り込まれる +- CLI loading は、要求された primary command を所有する plugins に絞り込まれる +- channel setup/plugin resolution は、要求された channel id を所有する plugins に絞り込まれる +- 明示的な provider setup/runtime resolution は、要求された provider id を所有する plugins に絞り込まれる -setup ディスカバリは現在、まず `setup.providers` や -`setup.cliBackends` のような descriptor 所有 id を優先して候補 Plugin を絞り込み、その後で -なお setup 時ランタイムフックを必要とする Plugin に対して `setup-api` へフォールバックします。複数の -発見済み Plugin が同じ正規化済み setup provider または CLI backend -id を主張する場合、setup 参照はディスカバリ順序に依存せず、その曖昧な所有者を拒否します。 +setup discovery は、setup-time runtime hooks がまだ必要な plugins に対して `setup-api` にフォールバックする前に、`setup.providers` や `setup.cliBackends` のような descriptor-owned ids を優先して候補 Plugin を絞り込むようになりました。発見された複数の plugins が同じ正規化済み setup provider または CLI backend id を主張した場合、setup lookup は discovery order に依存せず、その曖昧な owner を拒否します。 -### ローダーがキャッシュするもの +### loader がキャッシュするもの -OpenClaw は、短期間のプロセス内キャッシュを次の対象に対して保持します: +OpenClaw は、短期間の in-process cache を次の対象に対して保持します。 -- ディスカバリ結果 -- マニフェストレジストリデータ -- 読み込まれた Plugin レジストリ +- discovery results +- manifest registry data +- loaded plugin registries -これらのキャッシュは、突発的な起動や繰り返しコマンドのオーバーヘッドを減らします。これらは -永続化ではなく、短命なパフォーマンスキャッシュとして考えると安全です。 +これらの caches は、突発的な startup や繰り返し実行される command のオーバーヘッドを減らします。これらは永続化ではなく、短命な performance cache と考えるのが適切です。 -パフォーマンス上の注意: +パフォーマンスに関する注意: -- `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` または - `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` を設定すると、これらのキャッシュを無効化できます。 -- キャッシュウィンドウは `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` と - `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` で調整します。 +- これらの caches を無効にするには、`OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` または `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` を設定します。 +- cache window は `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` と `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` で調整します。 ## レジストリモデル -読み込まれた Plugin は、ランダムなコアのグローバル状態を直接変更しません。代わりに、 -中央の Plugin レジストリへ登録します。 +ロードされた plugins は、無作為な core globals を直接変更しません。中央の plugin registry に登録します。 -レジストリが追跡するもの: +registry は次を追跡します。 -- Plugin レコード（識別情報、ソース、オリジン、ステータス、診断） -- ツール -- レガシーフックと型付きフック -- チャネル -- プロバイダ -- Gateway RPC ハンドラ -- HTTP ルート -- CLI レジストラ -- バックグラウンドサービス -- Plugin 所有のコマンド +- plugin records（identity、source、origin、status、diagnostics） +- tools +- legacy hooks と typed hooks +- channels +- providers +- Gateway RPC handlers +- HTTP routes +- CLI registrars +- background services +- plugin が所有する commands -その後、コア機能は Plugin モジュールへ直接話しかける代わりに、そのレジストリから読み取ります。 -これにより、読み込み方向は一方向に保たれます: +その後、core features は plugin modules と直接やり取りする代わりに、その registry を読み取ります。これにより、ロードは一方向に保たれます。 -- Plugin モジュール -> レジストリ登録 -- コアランタイム -> レジストリ利用 +- plugin module -> registry registration +- core runtime -> registry consumption -この分離は保守性にとって重要です。これは、ほとんどのコアサーフェスが必要とする統合点が -「レジストリを読むこと」1つで済み、「すべての Plugin モジュールを特別扱いすること」では -ないことを意味します。 +この分離は保守性にとって重要です。つまり、ほとんどの core surface が必要とする統合ポイントは 1 つだけ、「registry を読む」であり、「すべての plugin module を個別扱いする」ではありません。 -## 会話バインディングコールバック +## Conversation binding callbacks -会話をバインドする Plugin は、承認が解決されたときに反応できます。 +conversation を bind する plugins は、承認が解決されたときに反応できます。 -バインド要求が承認または拒否された後にコールバックを受け取るには、 -`api.onConversationBindingResolved(...)` を使用します: +bind request が承認または拒否された後に callback を受け取るには、`api.onConversationBindingResolved(...)` を使用します。 ```ts export default { @@ -605,144 +477,117 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // A binding now exists for this plugin + conversation. + // この plugin + conversation に対する binding が存在するようになった。 console.log(event.binding?.conversationId); return; } - // The request was denied; clear any local pending state. + // リクエストは拒否された。ローカルの保留状態をすべてクリアする。 console.log(event.request.conversation.conversationId); }); }, }; ``` -コールバックのペイロードフィールド: +callback payload fields: - `status`: `"approved"` または `"denied"` - `decision`: `"allow-once"`、`"allow-always"`、または `"deny"` -- `binding`: 承認済み要求に対して解決されたバインディング -- `request`: 元の要求サマリ、detach ヒント、sender id、および - 会話メタデータ +- `binding`: 承認された requests に対する解決済み binding +- `request`: 元の request summary、detach hint、sender id、conversation metadata -このコールバックは通知専用です。これは会話をバインドできる主体を変更せず、 -コアの承認処理が完了した後に実行されます。 +この callback は通知専用です。誰が conversation を bind できるかを変更するものではなく、core の approval handling が完了した後に実行されます。 -## プロバイダランタイムフック +## プロバイダーのランタイムフック -プロバイダ Plugin には現在2つのレイヤーがあります: +provider plugins には現在 2 つの層があります。 -- マニフェストメタデータ: ランタイム読み込み前に軽量なプロバイダ env 認証参照を行うための `providerAuthEnvVars`、 - 認証を共有するプロバイダバリアント向けの `providerAuthAliases`、 - ランタイム読み込み前に軽量なチャネル env/setup 参照を行うための `channelEnvVars`、 - さらに、ランタイム読み込み前に軽量なオンボーディング/認証選択ラベルと - CLI フラグメタデータを扱うための `providerAuthChoices` -- 設定時フック: `catalog` / レガシーな `discovery` と `applyConfigDefaults` -- ランタイムフック: `normalizeModelId`、`normalizeTransport`、 - `normalizeConfig`、 - `applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、 - `resolveSyntheticAuth`、`resolveExternalAuthProfiles`、 - `shouldDeferSyntheticProfileAuth`、 - `resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、 - `contributeResolvedModelCompat`、`capabilities`、 - `normalizeToolSchemas`、`inspectToolSchemas`、 - `resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、 - `wrapStreamFn`、`resolveTransportTurnState`、 - `resolveWebSocketSessionPolicy`、`formatApiKey`、`refreshOAuth`、 - `buildAuthDoctorHint`、`matchesContextOverflowError`、 - `classifyFailoverReason`、`isCacheTtlEligible`、 - `buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、 - `isBinaryThinking`、`supportsXHighThinking`、 - `resolveDefaultThinkingLevel`、`isModernModelRef`、`prepareRuntimeAuth`、 - `resolveUsageAuth`、`fetchUsageSnapshot`、`createEmbeddingProvider`、 - `buildReplayPolicy`、 - `sanitizeReplayHistory`、`validateReplayTurns`、`onModelSelected` +- manifest metadata: runtime load 前に軽量な provider env-auth lookup を行うための `providerAuthEnvVars`、auth を共有する provider variants のための `providerAuthAliases`、runtime load 前に軽量な channel env/setup lookup を行うための `channelEnvVars`、さらに runtime load 前に軽量な onboarding/auth-choice labels と CLI flag metadata を提供するための `providerAuthChoices` +- config-time hooks: `catalog` / レガシーな `discovery`、および `applyConfigDefaults` +- runtime hooks: `normalizeModelId`, `normalizeTransport`, + `normalizeConfig`, + `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, + `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, + `shouldDeferSyntheticProfileAuth`, + `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, + `contributeResolvedModelCompat`, `capabilities`, + `normalizeToolSchemas`, `inspectToolSchemas`, + `resolveReasoningOutputMode`, `prepareExtraParams`, `createStreamFn`, + `wrapStreamFn`, `resolveTransportTurnState`, + `resolveWebSocketSessionPolicy`, `formatApiKey`, `refreshOAuth`, + `buildAuthDoctorHint`, `matchesContextOverflowError`, + `classifyFailoverReason`, `isCacheTtlEligible`, + `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, + `isBinaryThinking`, `supportsXHighThinking`, + `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, + `resolveUsageAuth`, `fetchUsageSnapshot`, `createEmbeddingProvider`, + `buildReplayPolicy`, + `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw は依然として汎用エージェントループ、フェイルオーバー、トランスクリプト処理、および -ツールポリシーを所有します。これらのフックは、プロバイダ固有の振る舞いを拡張するためのサーフェスであり、 -推論トランスポート全体をカスタム実装しなくても済みます。 +OpenClaw は、依然として汎用的な agent loop、failover、transcript handling、tool policy を所有します。これらの hooks は、完全なカスタム inference transport を必要とせずに provider 固有の behavior を実装するための extension surface です。 -プロバイダが env ベースの認証情報を持ち、汎用の auth/status/model-picker 経路から -Plugin ランタイムを読み込まずに見える必要がある場合は、マニフェスト `providerAuthEnvVars` を使います。 -ある provider id が別の provider id の env vars、auth profiles、 -設定ベース認証、および API キーオンボーディング選択を再利用すべき場合は、 -マニフェスト `providerAuthAliases` を使います。オンボーディング/認証選択の -CLI サーフェスが、そのプロバイダの選択 id、グループラベル、および単純な -単一フラグ認証配線を、プロバイダランタイムを読み込まずに知る必要がある場合は、 -マニフェスト `providerAuthChoices` を使います。プロバイダランタイムの -`envVars` は、オンボーディングラベルや OAuth の -client-id/client-secret セットアップ変数のような、オペレーター向けヒント用に保持してください。 +provider が env ベースの credentials を持っており、汎用的な auth/status/model-picker paths が plugin runtime を読み込まずにそれを認識すべき場合は、manifest の `providerAuthEnvVars` を使用します。1 つの provider id が別の provider id の env vars、auth profiles、config-backed auth、API-key onboarding choice を再利用すべき場合は、manifest の `providerAuthAliases` を使用します。onboarding/auth-choice CLI surfaces が provider runtime を読み込まずに、その provider の choice id、group labels、単純な one-flag auth wiring を認識すべき場合は、manifest の `providerAuthChoices` を使用します。provider runtime の `envVars` は、onboarding labels や OAuth client-id/client-secret setup vars のような operator 向けヒントに使い続けてください。 -チャネルに env 駆動の認証または setup があり、汎用 shell-env フォールバック、 -config/status チェック、または setup プロンプトから、チャネルランタイムを読み込まずに -見える必要がある場合は、マニフェスト `channelEnvVars` を使います。 +channel に env 駆動の auth または setup があり、汎用的な shell-env fallback、config/status checks、setup prompts が channel runtime を読み込まずにそれを認識すべき場合は、manifest の `channelEnvVars` を使用します。 -### フック順序と使い分け +### Hook の順序と使い方 -モデル/プロバイダ Plugin では、OpenClaw はおおむね次の順序でフックを呼び出します。 +model/provider plugins に対して、OpenClaw は hooks をおおよそ次の順序で呼び出します。 「When to use」列は、素早く判断するためのガイドです。 -| # | Hook | 役割 | 使うべきタイミング | +| # | Hook | 役割 | 使用する場面 | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | `models.json` 生成中に、プロバイダ設定を `models.providers` へ公開する | プロバイダがカタログまたは base URL のデフォルトを所有している場合 | -| 2 | `applyConfigDefaults` | 設定の具体化中に、プロバイダ所有のグローバル設定デフォルトを適用する | デフォルトが認証モード、env、またはプロバイダのモデルファミリのセマンティクスに依存する場合 | -| -- | _(built-in model lookup)_ | OpenClaw はまず通常のレジストリ/カタログ経路を試す | _(Plugin フックではない)_ | -| 3 | `normalizeModelId` | 参照前に、レガシーまたはプレビューの model-id エイリアスを正規化する | 正規のモデル解決の前に、プロバイダがエイリアス整理を所有している場合 | -| 4 | `normalizeTransport` | 汎用的なモデル組み立ての前に、プロバイダファミリの `api` / `baseUrl` を正規化する | 同じトランスポートファミリ内のカスタム provider id に対するトランスポート整理を、プロバイダが所有している場合 | -| 5 | `normalizeConfig` | ランタイム/プロバイダ解決前に `models.providers.` を正規化する | Plugin とともに置くべき設定整理がプロバイダに必要な場合。バンドルされた Google ファミリのヘルパーは、サポートされる Google 設定エントリも補完する | -| 6 | `applyNativeStreamingUsageCompat` | 設定プロバイダにネイティブ streaming-usage 互換リライトを適用する | プロバイダに、エンドポイント駆動の native streaming usage メタデータ修正が必要な場合 | -| 7 | `resolveConfigApiKey` | ランタイム認証読み込み前に、設定プロバイダ向けの env-marker 認証を解決する | プロバイダ所有の env-marker API キー解決がある場合。`amazon-bedrock` には、ここに組み込みの AWS env-marker リゾルバもある | -| 8 | `resolveSyntheticAuth` | 平文を永続化せずに、ローカル/セルフホスト型または設定ベースの認証を公開する | プロバイダが synthetic/local な資格情報マーカーで動作できる場合 | -| 9 | `resolveExternalAuthProfiles` | プロバイダ所有の外部認証プロファイルをオーバーレイする。デフォルトの `persistence` は CLI/アプリ所有資格情報向けに `runtime-only` | コピーしたリフレッシュトークンを永続化せずに、プロバイダが外部認証資格情報を再利用する場合 | -| 10 | `shouldDeferSyntheticProfileAuth` | 保存済みの synthetic プロファイルプレースホルダを env/config ベース認証より後順位に下げる | プロバイダが、優先されるべきでない synthetic プレースホルダプロファイルを保存する場合 | -| 11 | `resolveDynamicModel` | まだローカルレジストリにないプロバイダ所有 model id に対して同期フォールバックを行う | プロバイダが任意の上流 model id を受け入れる場合 | -| 12 | `prepareDynamicModel` | 非同期ウォームアップを行い、その後 `resolveDynamicModel` を再度実行する | 未知の id を解決する前に、プロバイダがネットワークメタデータを必要とする場合 | -| 13 | `normalizeResolvedModel` | embedded runner が解決済みモデルを使う前の最終リライト | プロバイダがトランスポートのリライトを必要とするが、なおコアのトランスポートを使う場合 | -| 14 | `contributeResolvedModelCompat` | 別の互換トランスポートの背後にあるベンダーモデル向けの互換フラグを提供する | プロバイダを引き継がずに、プロバイダがプロキシトランスポート上の自前モデルを認識する場合 | -| 15 | `capabilities` | 共有コアロジックで使われる、プロバイダ所有の transcript/tooling メタデータ | プロバイダに transcript/プロバイダファミリ固有の癖がある場合 | -| 16 | `normalizeToolSchemas` | embedded runner が見る前に、ツールスキーマを正規化する | プロバイダにトランスポートファミリのスキーマ整理が必要な場合 | -| 17 | `inspectToolSchemas` | 正規化後に、プロバイダ所有のスキーマ診断を公開する | コアへプロバイダ固有ルールを教え込まずに、プロバイダがキーワード警告を出したい場合 | -| 18 | `resolveReasoningOutputMode` | ネイティブまたはタグ付きの reasoning-output コントラクトを選択する | プロバイダがネイティブフィールドではなく、タグ付きの reasoning/final 出力を必要とする場合 | -| 19 | `prepareExtraParams` | 汎用ストリームオプションラッパーの前に、リクエストパラメータを正規化する | プロバイダにデフォルトのリクエストパラメータ、またはプロバイダごとのパラメータ整理が必要な場合 | -| 20 | `createStreamFn` | 通常のストリーム経路を完全に置き換え、カスタムトランスポートを使う | プロバイダがラッパーだけではなく、カスタムの wire protocol を必要とする場合 | -| 21 | `wrapStreamFn` | 汎用ラッパー適用後にストリームをラップする | プロバイダに、カスタムトランスポートなしでリクエストヘッダー/ボディ/モデル互換ラッパーが必要な場合 | -| 22 | `resolveTransportTurnState` | ネイティブなターン単位トランスポートヘッダーまたはメタデータを付加する | 汎用トランスポートでプロバイダネイティブなターン識別情報を送信したい場合 | -| 23 | `resolveWebSocketSessionPolicy` | ネイティブ WebSocket ヘッダーまたはセッションクールダウンポリシーを付加する | 汎用 WS トランスポートで、プロバイダがセッションヘッダーやフォールバックポリシーを調整したい場合 | -| 24 | `formatApiKey` | auth-profile フォーマッタ: 保存済みプロファイルをランタイムの `apiKey` 文字列へ変換する | プロバイダが追加の認証メタデータを保存し、カスタムのランタイムトークン形式を必要とする場合 | -| 25 | `refreshOAuth` | カスタムのリフレッシュエンドポイントまたはリフレッシュ失敗ポリシー向けの OAuth リフレッシュ上書き | プロバイダが共有の `pi-ai` リフレッシャーに適合しない場合 | -| 26 | `buildAuthDoctorHint` | OAuth リフレッシュ失敗時に追記される修復ヒント | リフレッシュ失敗後に、プロバイダ所有の認証修復ガイダンスが必要な場合 | -| 27 | `matchesContextOverflowError` | プロバイダ所有のコンテキストウィンドウ超過エラーマッチャ | 汎用ヒューリスティックでは拾えない生の超過エラーを、プロバイダが持っている場合 | -| 28 | `classifyFailoverReason` | プロバイダ所有のフェイルオーバー理由分類 | 生の API/トランスポートエラーを、プロバイダがレート制限/過負荷などへ分類できる場合 | -| 29 | `isCacheTtlEligible` | プロキシ/バックホール型プロバイダ向けのプロンプトキャッシュポリシー | プロバイダにプロキシ固有のキャッシュ TTL ゲーティングが必要な場合 | -| 30 | `buildMissingAuthMessage` | 汎用 missing-auth リカバリメッセージの代替 | プロバイダ固有の missing-auth リカバリヒントが必要な場合 | -| 31 | `suppressBuiltInModel` | 古い上流モデルの抑制と、オプションのユーザー向けエラーヒント | 古い上流行を非表示にする、またはベンダーヒントに置き換える必要がある場合 | -| 32 | `augmentModelCatalog` | discovery 後に synthetic/final なカタログ行を追加する | `models list` や picker に、synthetic な forward-compat 行をプロバイダが必要とする場合 | -| 33 | `isBinaryThinking` | binary-thinking プロバイダ向けの on/off 推論トグル | プロバイダが on/off の二値 thinking だけを公開する場合 | -| 34 | `supportsXHighThinking` | 選択されたモデル向けの `xhigh` 推論サポート | プロバイダがモデルの一部サブセットにのみ `xhigh` を提供したい場合 | -| 35 | `resolveDefaultThinkingLevel` | 特定のモデルファミリ向けのデフォルト `/think` レベル | モデルファミリに対するデフォルト `/think` ポリシーを、プロバイダが所有する場合 | -| 36 | `isModernModelRef` | ライブプロファイルフィルタおよびスモーク選択向けの modern-model マッチャ | ライブ/スモーク用の優先モデルマッチングを、プロバイダが所有する場合 | -| 37 | `prepareRuntimeAuth` | 推論直前に、設定済み資格情報を実際のランタイムトークン/キーへ交換する | プロバイダがトークン交換または短命なリクエスト資格情報を必要とする場合 | -| 38 | `resolveUsageAuth` | `/usage` および関連するステータスサーフェス向けの使用量/課金資格情報を解決する | プロバイダに、カスタムの使用量/クォータトークン解析、または異なる使用量資格情報が必要な場合 | -| 39 | `fetchUsageSnapshot` | 認証解決後に、プロバイダ固有の使用量/クォータスナップショットを取得して正規化する | プロバイダに、プロバイダ固有の使用量エンドポイントまたはペイロードパーサが必要な場合 | -| 40 | `createEmbeddingProvider` | memory/search 向けの、プロバイダ所有の埋め込みアダプタを構築する | memory の埋め込み動作がプロバイダ Plugin に属する場合 | -| 41 | `buildReplayPolicy` | そのプロバイダ向けの transcript 処理を制御するリプレイポリシーを返す | プロバイダにカスタム transcript ポリシー（たとえば thinking ブロックの除去）が必要な場合 | -| 42 | `sanitizeReplayHistory` | 汎用 transcript クリーンアップ後に、リプレイ履歴を書き換える | 共有 Compaction ヘルパーを超える、プロバイダ固有のリプレイ書き換えが必要な場合 | -| 43 | `validateReplayTurns` | embedded runner の前に、最終的なリプレイターン検証または整形を行う | プロバイダのトランスポートが、汎用サニタイズ後により厳密なターン検証を必要とする場合 | -| 44 | `onModelSelected` | モデルがアクティブになったときに、プロバイダ所有の選択後副作用を実行する | モデルが有効化されたときに、プロバイダがテレメトリまたはプロバイダ所有状態を必要とする場合 | +| 1 | `catalog` | `models.json` 生成時に、provider config を `models.providers` に公開する | Provider が catalog または base URL defaults を所有している | +| 2 | `applyConfigDefaults` | config materialization 中に、provider が所有するグローバル config defaults を適用する | defaults が auth mode、env、または provider の model-family semantics に依存する | +| -- | _(built-in model lookup)_ | OpenClaw は最初に通常の registry/catalog path を試す | _(plugin hook ではない)_ | +| 3 | `normalizeModelId` | lookup 前に、レガシーまたは preview の model-id aliases を正規化する | Provider が canonical model resolution 前の alias cleanup を所有している | +| 4 | `normalizeTransport` | 汎用的な model assembly の前に、provider-family の `api` / `baseUrl` を正規化する | 同じ transport family 内の custom provider ids に対する transport cleanup を Provider が所有している | +| 5 | `normalizeConfig` | runtime/provider resolution 前に、`models.providers.` を正規化する | plugin とともに管理されるべき config cleanup が Provider に必要な場合。bundled の Google-family helpers は、サポート対象の Google config entries の後方支援も行う | +| 6 | `applyNativeStreamingUsageCompat` | config providers に対して native streaming-usage compat rewrites を適用する | endpoint 主導の native streaming usage metadata fixes が Provider に必要な場合 | +| 7 | `resolveConfigApiKey` | runtime auth load 前に、config providers の env-marker auth を解決する | Provider が provider 所有の env-marker API-key resolution を持つ場合。`amazon-bedrock` にはここに built-in の AWS env-marker resolver もある | +| 8 | `resolveSyntheticAuth` | 平文を永続化せずに、local/self-hosted または config-backed auth を表面化する | Provider が synthetic/local credential marker で動作できる場合 | +| 9 | `resolveExternalAuthProfiles` | provider が所有する external auth profiles を overlay する。デフォルトの `persistence` は CLI/app 所有 credentials に対して `runtime-only` | copied refresh tokens を永続化せずに external auth credentials を Provider が再利用する場合 | +| 10 | `shouldDeferSyntheticProfileAuth` | 保存済みの synthetic profile placeholders を env/config-backed auth より後順位にする | precedence を取るべきでない synthetic placeholder profiles を Provider が保存している場合 | +| 11 | `resolveDynamicModel` | まだローカル registry にない provider 所有の model ids に対する同期 fallback | Provider が任意の upstream model ids を受け付ける場合 | +| 12 | `prepareDynamicModel` | 非同期 warm-up を行い、その後 `resolveDynamicModel` を再実行する | unknown ids を解決する前に network metadata が Provider に必要な場合 | +| 13 | `normalizeResolvedModel` | embedded runner が resolved model を使う前の最終 rewrite | Provider が transport rewrites を必要とするが、core transport は引き続き使う場合 | +| 14 | `contributeResolvedModelCompat` | 別の compatible transport の背後にある vendor models の compat flags を提供する | provider を引き継がずに proxy transports 上で自分の models を認識したい場合 | +| 15 | `capabilities` | 共有 core logic で使われる、provider 所有の transcript/tooling metadata | transcript/provider-family の quirks が Provider に必要な場合 | +| 16 | `normalizeToolSchemas` | embedded runner が見る前に tool schemas を正規化する | transport-family の schema cleanup が Provider に必要な場合 | +| 17 | `inspectToolSchemas` | 正規化後に provider 所有の schema diagnostics を表面化する | core に provider 固有ルールを教え込まずに keyword warnings を出したい場合 | +| 18 | `resolveReasoningOutputMode` | native と tagged の reasoning-output contract を選択する | native fields ではなく tagged reasoning/final output が Provider に必要な場合 | +| 19 | `prepareExtraParams` | 汎用的な stream option wrappers の前に request params を正規化する | default request params または provider ごとの param cleanup が Provider に必要な場合 | +| 20 | `createStreamFn` | 通常の stream path を custom transport で完全に置き換える | wrapper だけではなく、custom wire protocol が Provider に必要な場合 | +| 21 | `wrapStreamFn` | 汎用 wrappers が適用された後に stream wrapper を適用する | custom transport なしで request headers/body/model compat wrappers が Provider に必要な場合 | +| 22 | `resolveTransportTurnState` | ネイティブなターンごとの transport headers または metadata を付加する | 汎用 transports が provider ネイティブの turn identity を送信するようにしたい場合 | +| 23 | `resolveWebSocketSessionPolicy` | ネイティブな WebSocket headers または session cool-down policy を付加する | 汎用 WS transports で session headers や fallback policy を Provider が調整したい場合 | +| 24 | `formatApiKey` | auth-profile formatter: 保存された profile を runtime の `apiKey` string に変換する | 追加の auth metadata を Provider が保存しており、custom runtime token shape が必要な場合 | +| 25 | `refreshOAuth` | custom refresh endpoints または refresh-failure policy のための OAuth refresh override | Provider が共有の `pi-ai` refreshers に適合しない場合 | +| 26 | `buildAuthDoctorHint` | OAuth refresh が失敗したときに追加される repair hint | refresh failure 後に provider 所有の auth repair guidance が必要な場合 | +| 27 | `matchesContextOverflowError` | provider 所有の context-window overflow matcher | 汎用 heuristics では見逃す raw overflow errors を Provider が持つ場合 | +| 28 | `classifyFailoverReason` | provider 所有の failover reason classification | raw API/transport errors を rate-limit/overload などに Provider がマッピングできる場合 | +| 29 | `isCacheTtlEligible` | proxy/backhaul providers 向けの prompt-cache policy | proxy 固有の cache TTL gating が Provider に必要な場合 | +| 30 | `buildMissingAuthMessage` | 汎用の missing-auth recovery message の置き換え | provider 固有の missing-auth recovery hint が必要な場合 | +| 31 | `suppressBuiltInModel` | 古くなった upstream model の抑制と、必要に応じた user-facing error hint | 古い upstream rows を隠したり、vendor hint に置き換えたりする必要がある場合 | +| 32 | `augmentModelCatalog` | discovery 後に synthetic/final catalog rows を追加する | `models list` や pickers に synthetic な forward-compat rows が Provider に必要な場合 | +| 33 | `isBinaryThinking` | binary-thinking providers 向けの on/off reasoning toggle | Provider が binary な thinking on/off のみを公開する場合 | +| 34 | `supportsXHighThinking` | 選択された models に対する `xhigh` reasoning support | 一部の models にだけ `xhigh` を適用したい場合 | +| 35 | `resolveDefaultThinkingLevel` | 特定の model family に対するデフォルトの `/think` level | model family に対するデフォルトの `/think` policy を Provider が所有している場合 | +| 36 | `isModernModelRef` | live profile filters と smoke selection のための modern-model matcher | live/smoke の preferred-model matching を Provider が所有している場合 | +| 37 | `prepareRuntimeAuth` | 推論直前に、設定済み credential を実際の runtime token/key に交換する | token exchange または短命な request credential が Provider に必要な場合 | +| 38 | `resolveUsageAuth` | `/usage` および関連する status surfaces 向けの usage/billing credentials を解決する | custom な usage/quota token parsing、または別の usage credential が Provider に必要な場合 | +| 39 | `fetchUsageSnapshot` | auth 解決後に、provider 固有の usage/quota snapshots を取得して正規化する | provider 固有の usage endpoint または payload parser が Provider に必要な場合 | +| 40 | `createEmbeddingProvider` | memory/search 向けの provider 所有 embedding adapter を構築する | memory embedding behavior が provider plugin とともに管理されるべき場合 | +| 41 | `buildReplayPolicy` | provider の transcript handling を制御する replay policy を返す | Provider に custom transcript policy（たとえば thinking-block stripping）が必要な場合 | +| 42 | `sanitizeReplayHistory` | 汎用 transcript cleanup の後で replay history を書き換える | 共有 Compaction helpers を超えた provider 固有の replay rewrites が Provider に必要な場合 | +| 43 | `validateReplayTurns` | embedded runner の前に、replay turns の最終 validation または整形を行う | 汎用 sanitation の後に、provider transport がより厳密な turn validation を必要とする場合 | +| 44 | `onModelSelected` | model がアクティブになったときに provider 所有の post-selection side effects を実行する | model がアクティブになったときに telemetry または provider 所有 state が必要な場合 | -`normalizeModelId`、`normalizeTransport`、`normalizeConfig` は、まず -一致したプロバイダ Plugin を確認し、その後、実際に model id または transport/config を変更する -フック対応プロバイダ Plugin が見つかるまで、他のプロバイダ Plugin へ順にフォールスルーします。 -これにより、呼び出し側がどのバンドル Plugin がそのリライトを所有しているかを知らなくても、 -alias/互換プロバイダ shim が動作し続けます。サポートされている -Google ファミリの設定エントリをどのプロバイダフックもリライトしない場合でも、 -バンドルされた Google 設定ノーマライザがその互換性クリーンアップを適用します。 +`normalizeModelId`、`normalizeTransport`、`normalizeConfig` は、まず一致した provider plugin を確認し、その後、実際に model id または transport/config を変更するものが現れるまで、他の hook 対応 provider plugins へとフォールスルーします。これにより、caller がどの bundled plugin がその rewrite を所有しているかを知る必要なく、alias/compat provider shims を動作させ続けられます。どの provider hook もサポート対象の Google-family config entry を書き換えない場合でも、bundled の Google config normalizer はその互換性 cleanup を引き続き適用します。 -プロバイダが完全にカスタムな wire protocol やカスタムのリクエスト実行器を必要とする場合、 -それは別種の拡張です。これらのフックは、なお OpenClaw の通常の推論ループ上で動作する -プロバイダ挙動のためのものです。 +provider が完全にカスタムな wire protocol またはカスタム request executor を必要とする場合、それは別の種類の extension です。これらの hooks は、OpenClaw の通常の inference loop 上で引き続き動作する provider behavior のためのものです。 -### プロバイダの例 +### Provider の例 ```ts api.registerProvider({ @@ -798,117 +643,29 @@ api.registerProvider({ ### 組み込みの例 -- Anthropic は `resolveDynamicModel`、`capabilities`、`buildAuthDoctorHint`、 - `resolveUsageAuth`、`fetchUsageSnapshot`、`isCacheTtlEligible`、 - `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、 - `wrapStreamFn` を使います。これは、Claude 4.6 の forward-compat、 - プロバイダファミリのヒント、認証修復ガイダンス、使用量エンドポイント統合、 - プロンプトキャッシュ適格性、認証対応の設定デフォルト、Claude の - デフォルト/適応 thinking ポリシー、およびベータヘッダー、`/fast` / `serviceTier`、 - `context1m` 向けの Anthropic 固有のストリーム整形を所有しているためです。 -- Anthropic の Claude 固有ストリームヘルパーは、現時点ではバンドルされた Plugin 自身の - 公開 `api.ts` / `contract-api.ts` シームに留まっています。その package サーフェスは、 - 汎用 SDK を1つのプロバイダのベータヘッダールール向けに広げる代わりに、 - `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`、およびより低レベルの - Anthropic ラッパービルダをエクスポートします。 -- OpenAI は `resolveDynamicModel`、`normalizeResolvedModel`、 - `capabilities`、さらに `buildMissingAuthMessage`、`suppressBuiltInModel`、 - `augmentModelCatalog`、`supportsXHighThinking`、`isModernModelRef` - を使います。これは GPT-5.4 の forward-compat、直接の OpenAI - `openai-completions` -> `openai-responses` 正規化、Codex 認識の認証 - ヒント、Spark 抑制、synthetic な OpenAI リスト行、および GPT-5 の thinking / - ライブモデルポリシーを所有しているためです。また、`openai-responses-defaults` ストリームファミリは、 - attribution ヘッダー、`/fast`/`serviceTier`、テキスト冗長度、ネイティブ Codex Web 検索、 - reasoning-compat ペイロード整形、および Responses のコンテキスト管理向けの - 共有ネイティブ OpenAI Responses ラッパーを所有します。 -- OpenRouter は `catalog`、`resolveDynamicModel`、 - `prepareDynamicModel` を使います。これは、そのプロバイダがパススルー型であり、 - OpenClaw の静的カタログ更新前に新しい - model id を公開する可能性があるためです。また、 - `capabilities`、`wrapStreamFn`、`isCacheTtlEligible` も使い、 - プロバイダ固有のリクエストヘッダー、ルーティングメタデータ、reasoning パッチ、 - プロンプトキャッシュポリシーをコアの外に保ちます。そのリプレイポリシーは - `passthrough-gemini` ファミリから来ており、`openrouter-thinking` ストリームファミリは - プロキシ reasoning 注入と未サポートモデル / `auto` スキップを所有します。 -- GitHub Copilot は `catalog`、`auth`、`resolveDynamicModel`、 - `capabilities`、さらに `prepareRuntimeAuth` と `fetchUsageSnapshot` を使います。これは、 - プロバイダ所有のデバイスログイン、モデルフォールバック動作、Claude の transcript - の癖、GitHub トークン -> Copilot トークン交換、およびプロバイダ所有の使用量エンドポイントを必要とするためです。 -- OpenAI Codex は `catalog`、`resolveDynamicModel`、 - `normalizeResolvedModel`、`refreshOAuth`、`augmentModelCatalog`、 - さらに `prepareExtraParams`、`resolveUsageAuth`、`fetchUsageSnapshot` を使います。これは、 - 依然としてコアの OpenAI トランスポート上で動作しつつも、その transport/base URL - 正規化、OAuth リフレッシュフォールバックポリシー、デフォルトトランスポート選択、 - synthetic な Codex カタログ行、および ChatGPT 使用量エンドポイント統合を所有しているためです。 - これは直接の OpenAI と同じ `openai-responses-defaults` ストリームファミリを共有します。 -- Google AI Studio と Gemini CLI OAuth は `resolveDynamicModel`、 - `buildReplayPolicy`、`sanitizeReplayHistory`、 - `resolveReasoningOutputMode`、`wrapStreamFn`、`isModernModelRef` を使います。これは、 - `google-gemini` リプレイファミリが Gemini 3.1 の forward-compat フォールバック、 - ネイティブ Gemini リプレイ検証、bootstrap リプレイサニテーション、タグ付き - reasoning-output モード、および modern-model マッチングを所有し、 - `google-thinking` ストリームファミリが Gemini thinking ペイロード正規化を所有するためです。 - Gemini CLI OAuth はさらに、トークン整形、トークン解析、およびクォータ - エンドポイント接続のために `formatApiKey`、`resolveUsageAuth`、`fetchUsageSnapshot` も使います。 -- Anthropic Vertex は、 - `anthropic-by-model` リプレイファミリを通じて `buildReplayPolicy` を使います。これにより、 - Claude 固有のリプレイクリーンアップが、すべての `anthropic-messages` トランスポートではなく - Claude id にスコープされます。 -- Amazon Bedrock は `buildReplayPolicy`、`matchesContextOverflowError`、 - `classifyFailoverReason`、`resolveDefaultThinkingLevel` を使います。これは、 - Anthropic-on-Bedrock トラフィック向けに Bedrock 固有の - throttle/not-ready/context-overflow エラー分類を所有しているためです。そのリプレイポリシーは - 依然として同じ Claude 専用 `anthropic-by-model` ガードを共有します。 -- OpenRouter、Kilocode、Opencode、Opencode Go は `buildReplayPolicy` - を `passthrough-gemini` リプレイファミリ経由で使います。これは、それらが Gemini - モデルを OpenAI 互換トランスポート経由でプロキシしており、ネイティブ Gemini リプレイ検証や - bootstrap リライトなしで、Gemini の thought-signature サニテーションを必要とするためです。 -- MiniMax は、 - `hybrid-anthropic-openai` リプレイファミリ経由で `buildReplayPolicy` を使います。これは、 - 1つのプロバイダが Anthropic-message と OpenAI 互換の両方のセマンティクスを所有しているためです。 - これにより、Anthropic 側では Claude 専用の thinking ブロック削除を維持しつつ、 - reasoning 出力モードをネイティブへ戻し、`minimax-fast-mode` ストリームファミリは - 共有ストリーム経路で fast-mode モデルリライトを所有します。 -- Moonshot は `catalog` と `wrapStreamFn` を使います。これは、依然として共有 - OpenAI トランスポートを使いながら、プロバイダ所有の thinking ペイロード正規化を必要とするためです。 - `moonshot-thinking` ストリームファミリは、設定と `/think` 状態を - そのネイティブな binary thinking ペイロードへマッピングします。 -- Kilocode は `catalog`、`capabilities`、`wrapStreamFn`、 - `isCacheTtlEligible` を使います。これは、プロバイダ所有のリクエストヘッダー、 - reasoning ペイロード正規化、Gemini transcript ヒント、および Anthropic - cache-TTL ゲーティングを必要とするためです。`kilocode-thinking` ストリームファミリは、 - `kilo/auto` や、明示的な reasoning ペイロードをサポートしない他のプロキシ model id を - スキップしつつ、Kilo thinking 注入を共有プロキシストリーム経路上に保持します。 -- Z.AI は `resolveDynamicModel`、`prepareExtraParams`、`wrapStreamFn`、 - `isCacheTtlEligible`、`isBinaryThinking`、`isModernModelRef`、 - `resolveUsageAuth`、`fetchUsageSnapshot` を使います。これは、GLM-5 フォールバック、 - `tool_stream` のデフォルト、binary thinking UX、modern-model マッチング、 - および使用量認証とクォータ取得の両方を所有しているためです。`tool-stream-default-on` ストリームファミリは、 - デフォルトで有効な `tool_stream` ラッパーを、プロバイダごとの手書き glue から切り離して保ちます。 -- xAI は `normalizeResolvedModel`、`normalizeTransport`、 - `contributeResolvedModelCompat`、`prepareExtraParams`、`wrapStreamFn`、 - `resolveSyntheticAuth`、`resolveDynamicModel`、`isModernModelRef` - を使います。これは、ネイティブ xAI Responses トランスポート正規化、Grok fast-mode - エイリアスリライト、デフォルトの `tool_stream`、strict-tool / reasoning-payload - 整理、Plugin 所有ツール向けのフォールバック認証再利用、forward-compat な Grok - モデル解決、および xAI の tool-schema - プロファイル、未サポートのスキーマキーワード、ネイティブ `web_search`、HTML エンティティ化された - tool-call 引数デコードのようなプロバイダ所有の互換パッチを所有しているためです。 -- Mistral、OpenCode Zen、OpenCode Go は、 - transcript/tooling の癖をコアの外に保つために `capabilities` のみを使います。 -- `byteplus`、`cloudflare-ai-gateway`、 - `huggingface`、`kimi-coding`、`nvidia`、`qianfan`、 - `synthetic`、`together`、`venice`、`vercel-ai-gateway`、`volcengine` のような - catalog-only のバンドルプロバイダは、`catalog` のみを使います。 -- Qwen は、テキストプロバイダ向けの `catalog` と、そのマルチモーダルサーフェス向けの - 共有 media-understanding および video-generation 登録を使います。 -- MiniMax と Xiaomi は、推論自体は共有トランスポート経由で動作するにもかかわらず、 - `/usage` の動作が Plugin 所有であるため、`catalog` と使用量フックを使います。 +- Anthropic は `resolveDynamicModel`、`capabilities`、`buildAuthDoctorHint`、`resolveUsageAuth`、`fetchUsageSnapshot`、`isCacheTtlEligible`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`wrapStreamFn` を使用します。これは、Claude 4.6 の forward-compat、provider-family hints、auth repair guidance、usage endpoint integration、prompt-cache eligibility、auth-aware な config defaults、Claude の default/adaptive thinking policy、および beta headers、`/fast` / `serviceTier`、`context1m` のための Anthropic 固有の stream shaping を所有しているためです。 +- Anthropic の Claude 固有 stream helpers は、今のところ bundled plugin 自身の public `api.ts` / `contract-api.ts` seam に置かれています。その package surface は、generic SDK を 1 つの provider の beta-header rules 向けに広げる代わりに、`wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`、およびより低レベルな Anthropic wrapper builders を export します。 +- OpenAI は `resolveDynamicModel`、`normalizeResolvedModel`、`capabilities` に加えて、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`supportsXHighThinking`、`isModernModelRef` を使用します。これは、GPT-5.4 の forward-compat、直接の OpenAI `openai-completions` -> `openai-responses` の normalization、Codex-aware な auth hints、Spark suppression、synthetic な OpenAI list rows、GPT-5 の thinking / live-model policy を所有しているためです。また、`openai-responses-defaults` stream family は、attribution headers、`/fast`/`serviceTier`、text verbosity、native Codex web search、reasoning-compat payload shaping、Responses context management のための共有 native OpenAI Responses wrappers を所有します。 +- OpenRouter は `catalog` に加えて `resolveDynamicModel` と `prepareDynamicModel` を使用します。これは、その provider がパススルーであり、OpenClaw の静的 catalog が更新される前に新しい model ids を公開する可能性があるためです。また、provider 固有の request headers、routing metadata、reasoning patches、prompt-cache policy を core の外に保つために、`capabilities`、`wrapStreamFn`、`isCacheTtlEligible` も使用します。その replay policy は `passthrough-gemini` family に由来し、`openrouter-thinking` stream family は proxy reasoning injection と unsupported-model / `auto` のスキップを所有します。 +- GitHub Copilot は `catalog`、`auth`、`resolveDynamicModel`、`capabilities` に加えて `prepareRuntimeAuth` と `fetchUsageSnapshot` を使用します。これは、provider 所有の device login、model fallback behavior、Claude transcript quirks、GitHub token -> Copilot token exchange、provider 所有の usage endpoint が必要だからです。 +- OpenAI Codex は `catalog`、`resolveDynamicModel`、`normalizeResolvedModel`、`refreshOAuth`、`augmentModelCatalog` に加えて `prepareExtraParams`、`resolveUsageAuth`、`fetchUsageSnapshot` を使用します。これは、依然として core の OpenAI transports 上で動作する一方で、自身の transport/base URL normalization、OAuth refresh fallback policy、default transport choice、synthetic な Codex catalog rows、ChatGPT usage endpoint integration を所有しているためです。direct OpenAI と同じ `openai-responses-defaults` stream family を共有します。 +- Google AI Studio と Gemini CLI OAuth は `resolveDynamicModel`、`buildReplayPolicy`、`sanitizeReplayHistory`、`resolveReasoningOutputMode`、`wrapStreamFn`、`isModernModelRef` を使用します。これは、`google-gemini` replay family が Gemini 3.1 の forward-compat fallback、native Gemini replay validation、bootstrap replay sanitation、tagged reasoning-output mode、modern-model matching を所有し、`google-thinking` stream family が Gemini thinking payload normalization を所有しているためです。Gemini CLI OAuth はさらに、token formatting、token parsing、quota endpoint wiring のために `formatApiKey`、`resolveUsageAuth`、`fetchUsageSnapshot` も使用します。 +- Anthropic Vertex は `anthropic-by-model` replay family を通じて `buildReplayPolicy` を使用するため、Claude 固有の replay cleanup はすべての `anthropic-messages` transport ではなく Claude ids に限定されたままになります。 +- Amazon Bedrock は `buildReplayPolicy`、`matchesContextOverflowError`、`classifyFailoverReason`、`resolveDefaultThinkingLevel` を使用します。これは、Anthropic-on-Bedrock traffic 向けの Bedrock 固有の throttle/not-ready/context-overflow error classification を所有しているためです。その replay policy は引き続き同じ Claude 専用の `anthropic-by-model` guard を共有します。 +- OpenRouter、Kilocode、Opencode、Opencode Go は、`passthrough-gemini` replay family を通じて `buildReplayPolicy` を使用します。これは、Gemini models を OpenAI 互換 transports 経由で proxy しており、native Gemini replay validation や bootstrap rewrites なしで Gemini thought-signature sanitation が必要なためです。 +- MiniMax は `hybrid-anthropic-openai` replay family を通じて `buildReplayPolicy` を使用します。これは、1 つの provider が Anthropic-message と OpenAI-compatible の両方の semantics を所有するためです。Anthropic 側では Claude 専用の thinking-block dropping を維持しつつ、reasoning output mode は native に戻し、`minimax-fast-mode` stream family は共有 stream path 上で fast-mode の model rewrites を所有します。 +- Moonshot は `catalog` と `wrapStreamFn` を使用します。これは、依然として共有 OpenAI transport を使用しつつ、provider 所有の thinking payload normalization が必要だからです。`moonshot-thinking` stream family は config と `/think` state を native の binary thinking payload にマッピングします。 +- Kilocode は `catalog`、`capabilities`、`wrapStreamFn`、`isCacheTtlEligible` を使用します。これは、provider 所有の request headers、reasoning payload normalization、Gemini transcript hints、Anthropic cache-TTL gating が必要だからです。`kilocode-thinking` stream family は共有 proxy stream path 上で Kilo thinking injection を保持しつつ、明示的な reasoning payloads をサポートしない `kilo/auto` やその他の proxy model ids はスキップします。 +- Z.AI は `resolveDynamicModel`、`prepareExtraParams`、`wrapStreamFn`、`isCacheTtlEligible`、`isBinaryThinking`、`isModernModelRef`、`resolveUsageAuth`、`fetchUsageSnapshot` を使用します。これは、GLM-5 fallback、`tool_stream` defaults、binary thinking UX、modern-model matching、usage auth と quota fetching の両方を所有しているためです。`tool-stream-default-on` stream family は、デフォルト有効の `tool_stream` wrapper を provider ごとの手書き glue から切り離して保持します。 +- xAI は `normalizeResolvedModel`、`normalizeTransport`、`contributeResolvedModelCompat`、`prepareExtraParams`、`wrapStreamFn`、`resolveSyntheticAuth`、`resolveDynamicModel`、`isModernModelRef` を使用します。これは、native xAI Responses transport normalization、Grok fast-mode alias rewrites、デフォルトの `tool_stream`、strict-tool / reasoning-payload cleanup、plugin 所有 tools のための fallback auth reuse、forward-compat な Grok model resolution、および xAI tool-schema profile、unsupported schema keywords、native `web_search`、HTML-entity な tool-call argument decoding のような provider 所有 compat patches を所有しているためです。 +- Mistral、OpenCode Zen、OpenCode Go は、transcript/tooling quirks を core の外に保つために `capabilities` のみを使用します。 +- `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、`qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway`、`volcengine` のような catalog-only の bundled providers は、`catalog` のみを使用します。 +- Qwen は、text provider 向けの `catalog` と、その multimodal surfaces 向けの共有 media-understanding および video-generation registrations を使用します。 +- MiniMax と Xiaomi は `catalog` に加えて usage hooks を使用します。これは、推論自体は共有 transports を通じて実行される一方で、その `/usage` behavior は plugin 所有だからです。 ## ランタイムヘルパー -Plugin は、`api.runtime` を通じて選択されたコアヘルパーへアクセスできます。TTS の場合: +plugins は、`api.runtime` を通じて選択された core helpers にアクセスできます。TTS の場合は次のとおりです。 ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -927,16 +684,16 @@ const voices = await api.runtime.tts.listVoices({ }); ``` -注記: +注意: -- `textToSpeech` は、ファイル/voice-note サーフェス向けの通常のコア TTS 出力ペイロードを返します。 -- コアの `messages.tts` 設定とプロバイダ選択を使います。 -- PCM 音声バッファ + サンプルレートを返します。Plugin 側でプロバイダ向けにリサンプリング/エンコードする必要があります。 -- `listVoices` はプロバイダごとに任意です。ベンダー所有の voice picker や setup フローに使ってください。 -- 音声一覧には、ロケール、性別、パーソナリティタグなどの、より豊富なメタデータを含めることができ、プロバイダ認識型 picker に使えます。 -- 現時点で電話対応しているのは OpenAI と ElevenLabs です。Microsoft は未対応です。 +- `textToSpeech` は、file/voice-note surfaces 向けの通常の core TTS output payload を返します。 +- core の `messages.tts` configuration と provider selection を使用します。 +- PCM audio buffer + sample rate を返します。plugins 側で providers 向けに resample/encode する必要があります。 +- `listVoices` は provider ごとに optional です。vendor 所有の voice pickers や setup flows に使用してください。 +- voice listings には、provider-aware な pickers 向けに locale、gender、personality tags のような、より豊富な metadata を含められます。 +- 現在 telephony をサポートしているのは OpenAI と ElevenLabs です。Microsoft はサポートしていません。 -Plugin は `api.registerSpeechProvider(...)` で speech プロバイダも登録できます。 +plugins は `api.registerSpeechProvider(...)` を通じて speech providers を登録することもできます。 ```ts api.registerSpeechProvider({ @@ -954,17 +711,14 @@ api.registerSpeechProvider({ }); ``` -注記: +注意: -- TTS ポリシー、フォールバック、返信配信はコアに維持してください。 -- ベンダー所有の合成動作には speech プロバイダを使ってください。 -- レガシーな Microsoft の `edge` 入力は `microsoft` プロバイダ id に正規化されます。 -- 推奨される所有モデルは企業志向です。OpenClaw がそうした - ケイパビリティコントラクトを追加していくにつれ、1つのベンダー Plugin が - テキスト、音声、画像、将来のメディアプロバイダを所有できます。 +- TTS policy、fallback、reply delivery は core に残してください。 +- vendor 所有の synthesis behavior には speech providers を使用してください。 +- レガシーな Microsoft の `edge` input は `microsoft` provider id に正規化されます。 +- 推奨される所有モデルは会社単位です。OpenClaw がこれらの capability contracts を追加していく中で、1 つの vendor plugin が text、speech、image、将来の media providers を所有できます。 -画像/音声/動画理解については、Plugin は汎用 key/value bag ではなく、 -1つの型付き media-understanding プロバイダを登録します: +image/audio/video understanding については、plugins は generic な key/value bag ではなく、1 つの型付き media-understanding provider を登録します。 ```ts api.registerMediaUnderstandingProvider({ @@ -976,18 +730,17 @@ api.registerMediaUnderstandingProvider({ }); ``` -注記: +注意: -- オーケストレーション、フォールバック、設定、チャネル配線はコアに維持する -- ベンダーの振る舞いはプロバイダ Plugin に維持する -- 加算的な拡張は型付きのまま維持する: 新しい任意メソッド、新しい任意の - 結果フィールド、新しい任意ケイパビリティ -- 動画生成もすでに同じパターンに従っています: - - コアがケイパビリティコントラクトとランタイムヘルパーを所有する - - ベンダー Plugin が `api.registerVideoGenerationProvider(...)` を登録する - - 機能/チャネル Plugin が `api.runtime.videoGeneration.*` を利用する +- orchestration、fallback、config、channel wiring は core に保持してください。 +- vendor behavior は provider plugin に保持してください。 +- 加算的な拡張は型付きのままにしてください。新しい optional methods、新しい optional result fields、新しい optional capabilities。 +- video generation もすでに同じパターンに従っています。 + - core が capability contract と runtime helper を所有する + - vendor plugins が `api.registerVideoGenerationProvider(...)` を登録する + - feature/channel plugins が `api.runtime.videoGeneration.*` を利用する -media-understanding のランタイムヘルパーでは、Plugin は次のように呼び出せます: +media-understanding の runtime helpers については、plugins は次のように呼び出せます。 ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -1002,27 +755,25 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -音声文字起こしについては、Plugin は media-understanding ランタイム -または古い STT エイリアスのどちらかを使用できます: +audio transcription については、plugins は media-understanding runtime または古い STT alias のいずれかを使用できます。 ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Optional when MIME cannot be inferred reliably: + // MIME を確実に推測できない場合は optional: mime: "audio/ogg", }); ``` -注記: +注意: -- `api.runtime.mediaUnderstanding.*` は、 - 画像/音声/動画理解のための推奨される共有サーフェスです。 -- コアの media-understanding 音声設定（`tools.media.audio`）とプロバイダのフォールバック順序を使います。 -- 文字起こし出力が生成されない場合（たとえば入力がスキップ/未サポートの場合）は `{ text: undefined }` を返します。 -- `api.runtime.stt.transcribeAudioFile(...)` は互換性エイリアスとして残っています。 +- `api.runtime.mediaUnderstanding.*` は、image/audio/video understanding のための推奨される共有 surface です。 +- core の media-understanding audio configuration（`tools.media.audio`）と provider fallback order を使用します。 +- transcription output が生成されない場合（たとえば skipped/unsupported input）には `{ text: undefined }` を返します。 +- `api.runtime.stt.transcribeAudioFile(...)` は互換性 alias として残っています。 -Plugin は `api.runtime.subagent` を通じてバックグラウンドのサブエージェント実行も開始できます: +plugins は `api.runtime.subagent` を通じてバックグラウンドの subagent run を開始することもできます。 ```ts const result = await api.runtime.subagent.run({ @@ -1034,16 +785,15 @@ const result = await api.runtime.subagent.run({ }); ``` -注記: +注意: -- `provider` と `model` は、セッションに永続化される変更ではなく、実行ごとのオーバーライドです。 -- OpenClaw は、信頼された呼び出し元に対してのみ、それらのオーバーライドフィールドを尊重します。 -- Plugin 所有のフォールバック実行では、オペレーターが `plugins.entries..subagent.allowModelOverride: true` で明示的にオプトインする必要があります。 -- 信頼された Plugin を特定の正規 `provider/model` ターゲットに制限するには `plugins.entries..subagent.allowedModels` を使い、任意のターゲットを明示的に許可するには `"*"` を使います。 -- 信頼されていない Plugin のサブエージェント実行も動作しますが、オーバーライド要求は黙ってフォールバックされるのではなく拒否されます。 +- `provider` と `model` は永続的な session 変更ではなく、run ごとの optional overrides です。 +- OpenClaw は、信頼された caller に対してのみそれらの override fields を適用します。 +- plugin 所有の fallback runs では、operator が `plugins.entries..subagent.allowModelOverride: true` で opt in する必要があります。 +- 信頼された plugins を特定の canonical `provider/model` targets に制限するには `plugins.entries..subagent.allowedModels` を、任意の target を明示的に許可するには `"*"` を使用します。 +- 信頼されていない plugin の subagent runs も引き続き動作しますが、override requests は黙ってフォールバックされるのではなく拒否されます。 -Web 検索については、Plugin はエージェントツール配線へ直接到達する代わりに、 -共有ランタイムヘルパーを利用できます: +web search については、plugins は agent tool wiring に直接入り込む代わりに、共有 runtime helper を利用できます。 ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1059,14 +809,13 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugin は `api.registerWebSearchProvider(...)` を通じて -Web 検索プロバイダも登録できます。 +plugins は `api.registerWebSearchProvider(...)` を通じて web-search providers を登録することもできます。 -注記: +注意: -- プロバイダ選択、資格情報解決、共有リクエストセマンティクスはコアに維持してください。 -- ベンダー固有の検索トランスポートには Web 検索プロバイダを使ってください。 -- `api.runtime.webSearch.*` は、エージェントツールラッパーに依存せずに検索動作を必要とする機能/チャネル Plugin 向けの推奨共有サーフェスです。 +- provider selection、credential resolution、共有 request semantics は core に保持してください。 +- vendor 固有の search transports には web-search providers を使用してください。 +- `api.runtime.webSearch.*` は、agent tool wrapper に依存せず search behavior を必要とする feature/channel plugins のための推奨される共有 surface です。 ### `api.runtime.imageGeneration` @@ -1081,12 +830,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: 設定された画像生成プロバイダチェーンを使って画像を生成します。 -- `listProviders(...)`: 利用可能な画像生成プロバイダとそのケイパビリティを一覧表示します。 +- `generate(...)`: 設定された image-generation provider chain を使用して画像を生成します。 +- `listProviders(...)`: 利用可能な image-generation providers とその capabilities を一覧表示します。 -## Gateway HTTP ルート +## Gateway HTTP routes -Plugin は `api.registerHttpRoute(...)` で HTTP エンドポイントを公開できます。 +plugins は `api.registerHttpRoute(...)` で HTTP endpoints を公開できます。 ```ts api.registerHttpRoute({ @@ -1101,38 +850,35 @@ api.registerHttpRoute({ }); ``` -ルートフィールド: +route fields: -- `path`: gateway HTTP サーバー配下のルートパス。 -- `auth`: 必須。通常の gateway 認証を要求するには `"gateway"` を使い、Plugin 管理の認証/Webhook 検証には `"plugin"` を使います。 -- `match`: 任意。`"exact"`（デフォルト）または `"prefix"`。 -- `replaceExisting`: 任意。同じ Plugin が自分自身の既存ルート登録を置き換えることを許可します。 -- `handler`: ルートがリクエストを処理した場合は `true` を返します。 +- `path`: gateway HTTP server 配下の route path。 +- `auth`: 必須。通常の gateway auth を要求するには `"gateway"` を、plugin 管理の auth/webhook verification には `"plugin"` を使用します。 +- `match`: optional。`"exact"`（デフォルト）または `"prefix"`。 +- `replaceExisting`: optional。同じ Plugin が自身の既存 route registration を置き換えることを許可します。 +- `handler`: route が request を処理した場合は `true` を返します。 -注記: +注意: -- `api.registerHttpHandler(...)` は削除されており、Plugin 読み込みエラーの原因になります。代わりに `api.registerHttpRoute(...)` を使ってください。 -- Plugin ルートでは `auth` を明示的に宣言する必要があります。 -- 正確に同じ `path + match` の競合は、`replaceExisting: true` でない限り拒否され、ある Plugin が別の Plugin のルートを置き換えることはできません。 -- `auth` レベルが異なる重複ルートは拒否されます。`exact`/`prefix` のフォールスルーチェーンは同じ auth レベルの中だけに保ってください。 -- `auth: "plugin"` ルートは、オペレーターのランタイムスコープを自動では受け取り**ません**。これは、特権的な Gateway ヘルパー呼び出しではなく、Plugin 管理の Webhook/署名検証用です。 -- `auth: "gateway"` ルートは Gateway リクエストのランタイムスコープ内で実行されますが、そのスコープは意図的に保守的です: - - 共有シークレット bearer 認証（`gateway.auth.mode = "token"` / `"password"`）では、呼び出し元が `x-openclaw-scopes` を送っても、plugin-route のランタイムスコープは `operator.write` に固定されます - - 信頼された ID 付き HTTP モード（たとえば `trusted-proxy` や、プライベート ingress 上の `gateway.auth.mode = "none"`）では、`x-openclaw-scopes` ヘッダーが明示的に存在する場合にのみそれを尊重します - - それらの ID 付き plugin-route リクエストで `x-openclaw-scopes` が存在しない場合、ランタイムスコープは `operator.write` にフォールバックします -- 実践的なルール: gateway-auth の Plugin ルートを暗黙の管理者サーフェスだと想定しないでください。ルートに管理者専用動作が必要なら、ID 付き認証モードを要求し、明示的な `x-openclaw-scopes` ヘッダーコントラクトを文書化してください。 +- `api.registerHttpHandler(...)` は削除されており、plugin-load error を引き起こします。代わりに `api.registerHttpRoute(...)` を使用してください。 +- Plugin routes は `auth` を明示的に宣言する必要があります。 +- 完全に同一の `path + match` の競合は、`replaceExisting: true` でない限り拒否され、ある Plugin が別の Plugin の route を置き換えることはできません。 +- `auth` level が異なる重複 routes は拒否されます。`exact`/`prefix` の fallthrough chain は同じ auth level のみで維持してください。 +- `auth: "plugin"` routes は、operator runtime scopes を自動では受け取り**ません**。これらは plugin 管理の webhooks/signature verification のためのものであり、特権付き Gateway helper calls のためのものではありません。 +- `auth: "gateway"` routes は Gateway request runtime scope 内で実行されますが、その scope は意図的に保守的です。 + - shared-secret bearer auth（`gateway.auth.mode = "token"` / `"password"`）では、caller が `x-openclaw-scopes` を送信しても、plugin-route runtime scopes は `operator.write` に固定されます + - 信頼された identity-bearing HTTP modes（たとえば `trusted-proxy` または private ingress 上の `gateway.auth.mode = "none"`）では、`x-openclaw-scopes` header が明示的に存在する場合にのみそれを尊重します + - そのような identity-bearing plugin-route requests で `x-openclaw-scopes` が存在しない場合、runtime scope は `operator.write` にフォールバックします +- 実用上のルール: gateway-auth の plugin route が暗黙の admin surface だと想定しないでください。route が admin-only behavior を必要とする場合は、identity-bearing auth mode を要求し、明示的な `x-openclaw-scopes` header contract を文書化してください。 -## Plugin SDK インポートパス +## Plugin SDK import paths -Plugin を作成するときは、一枚岩の `openclaw/plugin-sdk` インポートではなく -SDK サブパスを使ってください: +plugins を作成する際は、巨大な `openclaw/plugin-sdk` import ではなく SDK subpaths を使用してください。 -- Plugin 登録プリミティブには `openclaw/plugin-sdk/plugin-entry`。 -- 汎用の共有 Plugin 向けコントラクトには `openclaw/plugin-sdk/core`。 -- ルート `openclaw.json` Zod スキーマ - エクスポート（`OpenClawSchema`）には `openclaw/plugin-sdk/config-schema`。 -- 共有 setup/auth/reply/Webhook - 配線には、`openclaw/plugin-sdk/channel-setup`、 +- plugin registration primitives には `openclaw/plugin-sdk/plugin-entry`。 +- 汎用の共有 plugin-facing contract には `openclaw/plugin-sdk/core`。 +- ルート `openclaw.json` Zod schema export（`OpenClawSchema`）には `openclaw/plugin-sdk/config-schema`。 +- 共有の setup/auth/reply/webhook wiring には、`openclaw/plugin-sdk/channel-setup`、 `openclaw/plugin-sdk/setup-runtime`、 `openclaw/plugin-sdk/setup-adapter-runtime`、 `openclaw/plugin-sdk/setup-tools`、 @@ -1143,21 +889,14 @@ SDK サブパスを使ってください: `openclaw/plugin-sdk/channel-lifecycle`、 `openclaw/plugin-sdk/channel-reply-pipeline`、 `openclaw/plugin-sdk/command-auth`、 - `openclaw/plugin-sdk/secret-input`、および - `openclaw/plugin-sdk/webhook-ingress` のような安定したチャネルプリミティブを使います。 - `channel-inbound` は、debounce、mention マッチング、 - 受信 mention-policy ヘルパー、envelope フォーマット、および受信 envelope - コンテキストヘルパーの共有ホームです。 - `channel-setup` は狭い optional-install setup シームです。 - `setup-runtime` は、`setupEntry` / - 遅延起動で使われるランタイム安全な setup サーフェスであり、 - import-safe な setup patch adapter を含みます。 - `setup-adapter-runtime` は env 認識の account-setup adapter シームです。 - `setup-tools` は小さな CLI/archive/docs ヘルパーシーム（`formatCliCommand`、 - `detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、 - `CONFIG_DIR`）です。 -- 共有ランタイム/設定ヘルパーには、 - `openclaw/plugin-sdk/channel-config-helpers`、 + `openclaw/plugin-sdk/secret-input`、 + `openclaw/plugin-sdk/webhook-ingress` のような stable な channel primitives。 + `channel-inbound` は debounce、mention matching、受信 mention-policy helpers、envelope formatting、受信 envelope context helpers のための共有ホームです。 + `channel-setup` は狭い optional-install setup seam です。 + `setup-runtime` は、`setupEntry` / deferred startup で使われる runtime-safe な setup surface であり、import-safe な setup patch adapters を含みます。 + `setup-adapter-runtime` は env-aware な account-setup adapter seam です。 + `setup-tools` は小さな CLI/archive/docs helper seam（`formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR`）です。 +- 共有の runtime/config helpers には、`openclaw/plugin-sdk/channel-config-helpers`、 `openclaw/plugin-sdk/allow-from`、 `openclaw/plugin-sdk/channel-config-schema`、 `openclaw/plugin-sdk/telegram-command-config`、 @@ -1174,194 +913,154 @@ SDK サブパスを使ってください: `openclaw/plugin-sdk/routing`、 `openclaw/plugin-sdk/status-helpers`、 `openclaw/plugin-sdk/text-runtime`、 - `openclaw/plugin-sdk/runtime-store`、および - `openclaw/plugin-sdk/directory-runtime` のようなドメインサブパスを使います。 - `telegram-command-config` は、Telegram カスタム - コマンドの正規化/検証のための狭い公開シームであり、バンドルされた - Telegram コントラクトサーフェスが一時的に利用できない場合でも引き続き利用可能です。 - `text-runtime` は共有の text/markdown/logging シームであり、 - assistant-visible-text の除去、markdown のレンダリング/チャンク化ヘルパー、redaction - ヘルパー、directive-tag ヘルパー、安全なテキストユーティリティを含みます。 -- 承認固有のチャネルシームでは、Plugin 上の1つの `approvalCapability` - コントラクトを優先すべきです。そうすればコアは、承認の auth、配信、レンダリング、 - ネイティブルーティング、遅延ネイティブハンドラ動作を、無関係な Plugin フィールドへ承認動作を混在させる代わりに、 - その1つのケイパビリティを通じて読み取れます。 -- `openclaw/plugin-sdk/channel-runtime` は非推奨であり、古い Plugin 向けの - 互換 shim としてのみ残っています。新しいコードでは、代わりにより狭い - 汎用プリミティブをインポートすべきであり、リポジトリコードでもこの - shim への新規インポートを追加すべきではありません。 -- バンドル拡張の内部実装は非公開のままです。外部 Plugin は - `openclaw/plugin-sdk/*` サブパスのみを使うべきです。OpenClaw のコア/テストコードは、 - `index.js`、`api.js`、 - `runtime-api.js`、`setup-entry.js`、`login-qr-api.js` のような狭くスコープされたファイルなど、 - Plugin package ルート配下のリポジトリ公開エントリポイントを使えます。 - コアや別の拡張から、Plugin package の `src/*` を決してインポートしないでください。 -- リポジトリエントリポイントの分割: - `/api.js` はヘルパー/型の barrel、 - `/runtime-api.js` はランタイム専用の barrel、 - `/index.js` はバンドルされた Plugin エントリ、 - `/setup-entry.js` は setup Plugin エントリです。 -- 現在のバンドルプロバイダの例: - - Anthropic は、`wrapAnthropicProviderStream`、ベータヘッダーヘルパー、 - `service_tier` 解析のような Claude ストリームヘルパーに `api.js` / `contract-api.js` を使います。 - - OpenAI は、プロバイダビルダー、デフォルトモデルヘルパー、リアルタイム - プロバイダビルダーに `api.js` を使います。 - - OpenRouter は、プロバイダビルダーに加えてオンボーディング/設定 - ヘルパーに `api.js` を使い、`register.runtime.js` は依然としてリポジトリ内利用向けに - 汎用 `plugin-sdk/provider-stream` ヘルパーを再エクスポートできます。 -- ファサード読み込みされる公開エントリポイントは、存在する場合はアクティブなランタイム設定スナップショットを優先し、 - OpenClaw がまだランタイムスナップショットを提供していない場合は、ディスク上の解決済み設定ファイルにフォールバックします。 -- 汎用の共有プリミティブは、引き続き推奨される公開 SDK コントラクトです。 - ただし、バンドルされたチャネルブランド付きヘルパーシームの小規模な予約済み互換セットは - 依然として存在します。これらは、新しいサードパーティのインポート先ではなく、 - バンドル保守/互換性用のシームとして扱ってください。新しいクロスチャネルコントラクトは、 - 引き続き汎用 `plugin-sdk/*` サブパスまたは Plugin ローカルの `api.js` / - `runtime-api.js` barrel に置くべきです。 + `openclaw/plugin-sdk/runtime-store`、 + `openclaw/plugin-sdk/directory-runtime` のような domain subpaths。 + `telegram-command-config` は Telegram custom command の normalization/validation のための狭い public seam であり、bundled Telegram contract surface が一時的に利用できない場合でも利用可能なままです。 + `text-runtime` は、assistant-visible-text stripping、markdown render/chunking helpers、redaction helpers、directive-tag helpers、safe-text utilities を含む、共有の text/markdown/logging seam です。 +- approval 固有の channel seams では、plugin 上の 1 つの `approvalCapability` contract を優先してください。その後 core は、その 1 つの capability を通じて approval auth、delivery、render、native-routing、lazy native-handler behavior を読み取ります。approval behavior を無関係な plugin fields に混ぜ込まないでください。 +- `openclaw/plugin-sdk/channel-runtime` は非推奨で、古い plugins 向けの互換性 shim としてのみ残されています。新しい code ではより狭い汎用 primitives を import すべきであり、repo code でも shim への新しい import を追加すべきではありません。 +- bundled extension internals は private のままです。外部 plugins は `openclaw/plugin-sdk/*` subpaths のみを使用するべきです。OpenClaw の core/test code は、plugin package root 配下の `index.js`、`api.js`、`runtime-api.js`、`setup-entry.js`、`login-qr-api.js` のような狭く限定された files など、repo の public entry points を使用できます。core からも別の extension からも、plugin package の `src/*` を import してはいけません。 +- repo entry point の分割: + `/api.js` は helper/types barrel、 + `/runtime-api.js` は runtime-only barrel、 + `/index.js` は bundled plugin entry、 + `/setup-entry.js` は setup plugin entry です。 +- 現在の bundled provider の例: + - Anthropic は `wrapAnthropicProviderStream`、beta-header helpers、`service_tier` parsing のような Claude stream helpers のために `api.js` / `contract-api.js` を使用します。 + - OpenAI は provider builders、default-model helpers、realtime provider builders のために `api.js` を使用します。 + - OpenRouter は provider builder と onboarding/config helpers のために `api.js` を使用し、一方で `register.runtime.js` は repo ローカル用途のために汎用的な `plugin-sdk/provider-stream` helpers を再 export できます。 +- facade-loaded public entry points は、利用可能な場合はアクティブな runtime config snapshot を優先し、その後 OpenClaw がまだ runtime snapshot を提供していない場合には disk 上で解決された config file にフォールバックします。 +- 汎用の共有 primitives は、依然として推奨される public SDK contract です。bundled channel ブランド付き helper seams の小さな予約済み互換性セットはまだ存在します。これらは bundled-maintenance/compatibility seams として扱い、新しいサードパーティ import targets として扱わないでください。新しい cross-channel contracts は、引き続き汎用的な `plugin-sdk/*` subpaths または plugin ローカルの `api.js` / `runtime-api.js` barrels に配置するべきです。 -互換性に関する注記: +互換性に関する注意: -- 新しいコードではルートの `openclaw/plugin-sdk` barrel を避けてください。 -- まずは狭く安定したプリミティブを優先してください。新しい - setup/pairing/reply/ +- 新しい code では、ルートの `openclaw/plugin-sdk` barrel は避けてください。 +- まずは狭く安定した primitives を優先してください。新しい setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool サブパスが、新しい - バンドル Plugin と外部 Plugin 作業向けの意図されたコントラクトです。 - ターゲットのパース/マッチングは `openclaw/plugin-sdk/channel-targets` に置くべきです。 - message action ゲートと reaction message-id ヘルパーは - `openclaw/plugin-sdk/channel-actions` に置くべきです。 -- バンドル拡張固有の helper barrel は、デフォルトでは安定していません。ある - ヘルパーがバンドル拡張だけに必要なら、それを - `openclaw/plugin-sdk/` に昇格させるのではなく、 - その拡張のローカルな `api.js` または `runtime-api.js` シームの背後に置いてください。 -- 新しい共有 helper シームは、チャネル名付きではなく汎用であるべきです。共有ターゲット - パースは `openclaw/plugin-sdk/channel-targets` に置くべきであり、チャネル固有の - 内部実装は所有する Plugin のローカル `api.js` または `runtime-api.js` - シームの背後に留めてください。 + allowlist/status/message-tool subpaths は、新しい bundled および外部 Plugin 作業に対する意図された contract です。 + target の parsing/matching は `openclaw/plugin-sdk/channel-targets` に属します。 + message action gates と reaction message-id helpers は + `openclaw/plugin-sdk/channel-actions` に属します。 +- bundled extension 固有の helper barrels は、デフォルトでは stable ではありません。 + helper が bundled extension だけに必要な場合は、それを + `openclaw/plugin-sdk/` に昇格させるのではなく、その extension の + ローカルな `api.js` または `runtime-api.js` seam の背後に置いてください。 +- 新しい共有 helper seams は、channel ブランド付きではなく汎用であるべきです。共有 target + parsing は `openclaw/plugin-sdk/channel-targets` に属し、channel 固有の + internals は所有する Plugin のローカルな `api.js` または `runtime-api.js` + seam の背後に残すべきです。 - `image-generation`、 - `media-understanding`、`speech` のようなケイパビリティ固有サブパスは、 - 現在バンドル/ネイティブ Plugin がそれらを使っているため存在します。それらが存在すること自体は、 - エクスポートされたすべてのヘルパーが長期的に固定された外部コントラクトであることを意味しません。 + `media-understanding`、`speech` のような capability 固有 subpaths は、現在 + bundled/native plugins がそれらを使っているため存在しています。これらが存在すること自体は、export されたすべての helper が + 長期的に凍結された外部 contract であることを意味しません。 -## Message ツールスキーマ +## Message tool schemas -Plugin は、チャネル固有の `describeMessageTool(...)` スキーマへの寄与を -所有すべきです。プロバイダ固有のフィールドは、共有コアではなく Plugin 内に置いてください。 +plugins は、channel 固有の `describeMessageTool(...)` schema +contributions を所有するべきです。provider 固有 fields は共有 core ではなく、Plugin に保持してください。 -共有で移植可能なスキーマ断片には、 -`openclaw/plugin-sdk/channel-actions` からエクスポートされる汎用ヘルパーを再利用してください: +共有可能な portable schema fragments については、 +`openclaw/plugin-sdk/channel-actions` から export される汎用 helpers を再利用してください。 -- ボタングリッド形式のペイロードには `createMessageToolButtonsSchema()` -- 構造化カード形式のペイロードには `createMessageToolCardSchema()` +- button-grid スタイルの payloads には `createMessageToolButtonsSchema()` +- 構造化された card payloads には `createMessageToolCardSchema()` -あるスキーマ形状が1つのプロバイダにしか意味を持たない場合は、それを共有 SDK に昇格させるのではなく、 -その Plugin 自身のソース内で定義してください。 +ある schema shape が 1 つの provider にしか意味を持たないなら、共有 SDK に昇格させるのではなく、その Plugin 自身の source に定義してください。 -## チャネルターゲット解決 +## Channel target resolution -チャネル Plugin は、チャネル固有のターゲットセマンティクスを所有すべきです。共有 -outbound ホストは汎用のままにし、プロバイダルールには messaging adapter サーフェスを使ってください: +channel plugins は、channel 固有の target semantics を所有するべきです。共有 outbound host は汎用のままに保ち、provider rules には messaging adapter surface を使ってください。 -- `messaging.inferTargetChatType({ to })` は、正規化されたターゲットを - ディレクトリ参照前に `direct`、`group`、`channel` のどれとして扱うべきかを判断します。 -- `messaging.targetResolver.looksLikeId(raw, normalized)` は、ある入力を - ディレクトリ検索ではなく id らしい解決へ直接進めるべきかどうかをコアへ伝えます。 +- `messaging.inferTargetChatType({ to })` は、正規化済み target を + directory lookup 前に `direct`、`group`、`channel` のどれとして扱うべきかを決定する +- `messaging.targetResolver.looksLikeId(raw, normalized)` は、directory search の代わりに入力をそのまま id-like resolution に進めるべきかを core に伝える - `messaging.targetResolver.resolveTarget(...)` は、正規化後または - ディレクトリミス後に、コアが最終的なプロバイダ所有解決を必要とするときの Plugin 側フォールバックです。 -- `messaging.resolveOutboundSessionRoute(...)` は、ターゲット解決後のプロバイダ固有 - セッションルート構築を所有します。 + directory miss 後に、core が最終的な provider 所有 resolution を必要とする場合の plugin fallback である +- `messaging.resolveOutboundSessionRoute(...)` は、target 解決後の + provider 固有 session route construction を所有する -推奨される分割: +推奨される分担: -- ピア/グループ検索前に行うべきカテゴリ判断には `inferTargetChatType` を使う -- 「これを明示的/ネイティブなターゲット id として扱う」判定には `looksLikeId` を使う -- `resolveTarget` は、広範なディレクトリ検索ではなく、プロバイダ固有の正規化フォールバックに使う -- chat id、thread id、JID、handle、room id のようなプロバイダネイティブ id は、 - 汎用 SDK フィールドではなく、`target` 値またはプロバイダ固有パラメータ内に保持する +- peers/groups の検索前に行うべきカテゴリ判断には `inferTargetChatType` を使う +- 「これを明示的/ネイティブな target id として扱う」チェックには `looksLikeId` を使う +- provider 固有の normalization fallback には `resolveTarget` を使い、広範な directory search には使わない +- chat ids、thread ids、JIDs、handles、room ids のような provider ネイティブ ids は、汎用 SDK fields ではなく `target` values または provider 固有 params の中に保持する -## 設定ベースのディレクトリ +## Config-backed directories -設定からディレクトリエントリを導出する Plugin は、そのロジックを Plugin 内に保持し、 -`openclaw/plugin-sdk/directory-runtime` の共有ヘルパーを再利用すべきです。 +config から directory entries を導出する plugins は、そのロジックを Plugin 内に保持し、 +`openclaw/plugin-sdk/directory-runtime` の共有 helpers を再利用するべきです。 -これは、チャネルが次のような設定ベースのピア/グループを必要とするときに使います: +これは、channel が次のような config-backed peers/groups を必要とする場合に使用します。 -- allowlist 駆動の DM ピア -- 設定済みのチャネル/グループマップ -- アカウント単位の静的ディレクトリフォールバック +- allowlist に基づく DM peers +- 設定済みの channel/group maps +- account-scoped の静的 directory fallbacks -`directory-runtime` の共有ヘルパーは、汎用操作のみを扱います: +`directory-runtime` の共有 helpers は、汎用操作のみを扱います。 -- クエリフィルタリング -- 上限適用 -- 重複除去/正規化ヘルパー +- query filtering +- limit application +- deduping/normalization helpers - `ChannelDirectoryEntry[]` の構築 -チャネル固有のアカウント検査と id 正規化は、Plugin 実装内に留めてください。 +channel 固有の account inspection と id normalization は、Plugin 実装内に残すべきです。 -## プロバイダカタログ +## Provider catalogs -プロバイダ Plugin は、 -`registerProvider({ catalog: { run(...) { ... } } })` を使って推論用モデルカタログを定義できます。 +provider plugins は、 +`registerProvider({ catalog: { run(...) { ... } } })` を使って、推論用の model catalogs を定義できます。 -`catalog.run(...)` は、OpenClaw が -`models.providers` に書き込むのと同じ形を返します: +`catalog.run(...)` は、OpenClaw が `models.providers` に書き込むのと同じ shape を返します。 -- 1つのプロバイダエントリに対しては `{ provider }` -- 複数のプロバイダエントリに対しては `{ providers }` +- 1 つの provider entry に対しては `{ provider }` +- 複数の provider entries に対しては `{ providers }` -Plugin がプロバイダ固有の model id、base URL -デフォルト、または認証ゲート付きモデルメタデータを所有する場合は、`catalog` を使ってください。 +provider 固有の model ids、base URL defaults、または auth-gated model metadata を Plugin が所有する場合は `catalog` を使ってください。 -`catalog.order` は、Plugin のカタログが OpenClaw の -組み込み暗黙プロバイダに対していつマージされるかを制御します: +`catalog.order` は、OpenClaw の built-in implicit providers に対して Plugin の catalog がいつ merge されるかを制御します。 -- `simple`: プレーンな API キーまたは env 駆動プロバイダ -- `profile`: auth profile が存在するときに現れるプロバイダ -- `paired`: 複数の関連プロバイダエントリを合成するプロバイダ -- `late`: 他の暗黙プロバイダの後の最終パス +- `simple`: 単純な API-key または env 駆動 providers +- `profile`: auth profiles が存在すると現れる providers +- `paired`: 複数の関連 provider entries を合成する providers +- `late`: 他の implicit providers の後の最後のパス -後から来たプロバイダがキー競合時に勝つため、Plugin は同じ provider id を持つ -組み込みプロバイダエントリを意図的に上書きできます。 +後の providers がキー衝突時に勝つため、plugins は同じ provider id を持つ built-in provider entry を意図的に上書きできます。 互換性: -- `discovery` はレガシーエイリアスとして引き続き動作します -- `catalog` と `discovery` の両方が登録されている場合、OpenClaw は `catalog` を使います +- `discovery` はレガシーな別名として引き続き機能する +- `catalog` と `discovery` の両方が登録されている場合、OpenClaw は `catalog` を使用する -## 読み取り専用のチャネル検査 +## 読み取り専用の channel inspection -Plugin がチャネルを登録する場合は、`resolveAccount(...)` とあわせて +Plugin が channel を登録する場合は、`resolveAccount(...)` とあわせて `plugin.config.inspectAccount(cfg, accountId)` の実装を優先してください。 理由: -- `resolveAccount(...)` はランタイム経路です。資格情報が - 完全に具体化されている前提でよく、必要なシークレットが不足していれば即座に失敗して構いません。 +- `resolveAccount(...)` は runtime path です。credentials が完全に materialize されていることを前提にしてよく、必要な secrets が欠けている場合は即座に失敗して構いません。 - `openclaw status`、`openclaw status --all`、 `openclaw channels status`、`openclaw channels resolve`、および doctor/config - 修復フローのような読み取り専用コマンド経路では、設定を説明するだけのために - ランタイム資格情報を具体化する必要があるべきではありません。 + repair flows のような読み取り専用 command paths は、設定を説明するだけのために runtime credentials を materialize する必要があるべきではありません。 -推奨される `inspectAccount(...)` の動作: +推奨される `inspectAccount(...)` の振る舞い: -- 説明的なアカウント状態のみを返す。 -- `enabled` と `configured` を維持する。 -- 関連する場合は、資格情報のソース/ステータスフィールドを含める。たとえば: - - `tokenSource`、`tokenStatus` - - `botTokenSource`、`botTokenStatus` - - `appTokenSource`、`appTokenStatus` - - `signingSecretSource`、`signingSecretStatus` -- 読み取り専用の利用可否を報告するだけなら、生のトークン値を返す必要はありません。 - ステータス系コマンドには `tokenStatus: "available"`（および対応するソースフィールド）を返せば十分です。 -- 資格情報が SecretRef 経由で設定されているが、現在のコマンド経路では利用できない場合は - `configured_unavailable` を使います。 +- 説明的な account state のみを返す +- `enabled` と `configured` を保持する +- 関連する場合は、次のような credential source/status fields を含める + - `tokenSource`, `tokenStatus` + - `botTokenSource`, `botTokenStatus` + - `appTokenSource`, `appTokenStatus` + - `signingSecretSource`, `signingSecretStatus` +- 読み取り専用の可用性を報告するためだけに raw token values を返す必要はありません。status-style commands には `tokenStatus: "available"`（および対応する source field）を返せば十分です。 +- credential が SecretRef 経由で設定されているが、現在の command path では利用できない場合は `configured_unavailable` を使う -これにより、読み取り専用コマンドは、クラッシュしたり、アカウントを未設定と誤報したりする代わりに、 -「設定済みだがこのコマンド経路では利用不可」と報告できます。 +これにより、読み取り専用 commands は、クラッシュしたり account を未設定だと誤報したりする代わりに、「設定済みだがこの command path では利用できない」と報告できます。 -## Package pack +## Package packs -Plugin ディレクトリには、`openclaw.extensions` を持つ `package.json` を含められます: +Plugin directory には、`openclaw.extensions` を含む `package.json` を置けます。 ```json { @@ -1373,64 +1072,51 @@ Plugin ディレクトリには、`openclaw.extensions` を持つ `package.json` } ``` -各エントリは1つの Plugin になります。pack が複数の拡張を列挙している場合、Plugin id は -`name/` になります。 +各 entry は 1 つの Plugin になります。pack に複数の extensions が列挙されている場合、plugin id は `name/` になります。 -Plugin が npm 依存関係をインポートする場合は、そのディレクトリ内に -`node_modules` が利用できるようインストールしてください（`npm install` / `pnpm install`）。 +Plugin が npm deps を import する場合は、その directory でそれらを install して +`node_modules` を利用可能にしてください（`npm install` / `pnpm install`）。 -セキュリティガードレール: すべての `openclaw.extensions` エントリは、symlink 解決後も -Plugin ディレクトリ内に留まっている必要があります。package ディレクトリ外へ -エスケープするエントリは拒否されます。 +セキュリティのガードレール: すべての `openclaw.extensions` entry は、symlink 解決後も Plugin +directory 内に留まらなければなりません。package directory から外に出る entries は拒否されます。 -セキュリティ上の注意: `openclaw plugins install` は Plugin 依存関係を -`npm install --omit=dev --ignore-scripts` でインストールします（ライフサイクルスクリプトなし、本番時に dev dependencies なし）。Plugin の依存関係 -ツリーは「pure JS/TS」に保ち、`postinstall` ビルドを必要とする package は避けてください。 +セキュリティに関する注意: `openclaw plugins install` は、plugin dependencies を +`npm install --omit=dev --ignore-scripts` で install します（lifecycle scripts なし、runtime での dev dependencies なし）。plugin dependency +trees は「pure JS/TS」に保ち、`postinstall` builds を必要とする packages は避けてください。 -任意: `openclaw.setupEntry` は軽量な setup 専用モジュールを指せます。 -OpenClaw が無効なチャネル Plugin の setup サーフェスを必要とする場合、または -チャネル Plugin が有効でもまだ未設定の場合、完全な Plugin エントリの代わりに `setupEntry` -を読み込みます。これにより、メイン Plugin エントリがツール、フック、または他のランタイム専用 -コードも配線している場合でも、起動と setup を軽量に保てます。 +任意: `openclaw.setupEntry` は軽量な setup 専用 module を指せます。 +OpenClaw が無効な channel plugin 用の setup surfaces を必要とする場合、または +channel plugin が有効でも未設定である場合には、完全な plugin entry の代わりに `setupEntry` +を読み込みます。これにより、main plugin entry が tools、hooks、その他の runtime-only +code も配線している場合に、startup と setup を軽く保てます。 任意: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -を使うと、チャネルがすでに設定済みであっても、gateway の -listen 前起動フェーズ中にチャネル Plugin を同じ `setupEntry` 経路へオプトインできます。 +を指定すると、gateway の pre-listen startup phase 中、channel がすでに設定済みであっても、channel plugin は同じ `setupEntry` path を使うようにできます。 -これは、gateway が listen を開始する前に存在していなければならない起動サーフェスを -`setupEntry` が完全にカバーしている場合にのみ使ってください。実際には、setup entry が -起動時に依存するすべてのチャネル所有ケイパビリティを登録する必要があります。たとえば: +これは、`setupEntry` が gateway が listen を開始する前に存在しなければならない startup surface を完全にカバーしている場合にのみ使用してください。実際には、setup entry は startup が依存する channel 所有 capabilities をすべて登録する必要があります。たとえば: -- チャネル登録そのもの -- gateway が listen を開始する前に利用可能でなければならない HTTP ルート -- 同じ時間帯に存在していなければならない Gateway メソッド、ツール、またはサービス +- channel registration 自体 +- gateway が listen を開始する前に利用可能でなければならない HTTP routes +- その同じウィンドウ中に存在しなければならない gateway methods、tools、services -完全なエントリが依然として何らかの必須起動ケイパビリティを所有している場合は、 -このフラグを有効にしないでください。デフォルト動作のままにして、 -OpenClaw に起動中に完全なエントリを読み込ませてください。 +full entry が依然として必要な startup capability を所有しているなら、この flag を有効にしてはいけません。デフォルト動作のままにし、OpenClaw に startup 中に full entry を読み込ませてください。 -バンドルされたチャネルは、完全なチャネルランタイムが読み込まれる前にコアが参照できる、 -setup 専用のコントラクトサーフェスヘルパーも公開できます。現在の setup -昇格サーフェスは次のとおりです: +bundled channels は、full channel runtime が読み込まれる前に core が参照できる setup-only contract-surface helpers を公開することもできます。現在の setup +promotion surface は次のとおりです。 - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -コアは、完全な Plugin エントリを読み込まずに、レガシーな単一アカウントチャネル設定を -`channels..accounts.*` へ昇格する必要があるときにそのサーフェスを使います。 -Matrix は現在のバンドル例です。名前付きアカウントがすでに存在する場合、 -認証/bootstrap キーだけを名前付き昇格アカウントへ移し、 -常に `accounts.default` を作るのではなく、設定済みの非標準なデフォルトアカウントキーを保持できます。 +core は、full plugin entry を読み込まずにレガシーな single-account channel +config を `channels..accounts.*` に昇格させる必要があるときに、その surface を使います。 +Matrix は現在の bundled の例です。named accounts がすでに存在する場合は auth/bootstrap keys のみを named な promoted account に移動し、常に `accounts.default` を作成するのではなく、設定済みの非 canonical な default-account key を保持できます。 -これらの setup patch adapter により、バンドルされたコントラクトサーフェスのディスカバリは遅延されたままです。 -import 時間は軽く保たれ、昇格サーフェスはモジュール import 時に -バンドルチャネルの起動へ再突入する代わりに、最初に使われたときだけ読み込まれます。 +これらの setup patch adapters は、bundled contract-surface discovery を lazy に保ちます。import 時間は軽いままで、promotion surface は module import 時に bundled channel startup に再突入する代わりに、最初の使用時にのみ読み込まれます。 -それらの起動サーフェスに Gateway RPC メソッドが含まれる場合は、 -Plugin 固有の接頭辞に保ってください。コアの管理名前空間（`config.*`、 -`exec.approvals.*`、`wizard.*`、`update.*`）は予約済みであり、Plugin がより狭いスコープを要求しても、 -常に `operator.admin` に解決されます。 +それらの startup surfaces に Gateway RPC methods が含まれる場合は、 +plugin 固有の prefix を付けてください。core admin namespaces（`config.*`、 +`exec.approvals.*`、`wizard.*`、`update.*`）は予約済みであり、Plugin がより狭い scope を要求しても常に `operator.admin` に解決されます。 例: @@ -1447,10 +1133,9 @@ Plugin 固有の接頭辞に保ってください。コアの管理名前空間 } ``` -### チャネルカタログメタデータ +### Channel catalog metadata -チャネル Plugin は `openclaw.channel` を通じて setup/ディスカバリ用メタデータを、 -`openclaw.install` を通じて install ヒントを公開できます。これにより、コアのカタログはデータフリーに保たれます。 +channel plugins は、`openclaw.channel` を通じて setup/discovery metadata を、`openclaw.install` を通じて install hints を公開できます。これにより core catalog をデータフリーに保てます。 例: @@ -1465,7 +1150,7 @@ Plugin 固有の接頭辞に保ってください。コアの管理名前空間 "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Nextcloud Talk Webhook bot によるセルフホスト型チャット。", + "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1478,41 +1163,36 @@ Plugin 固有の接頭辞に保ってください。コアの管理名前空間 } ``` -最小例以外で有用な `openclaw.channel` フィールド: +最小例以外で有用な `openclaw.channel` fields: -- `detailLabel`: より豊かなカタログ/ステータスサーフェス向けの二次ラベル -- `docsLabel`: ドキュメントリンク用のリンクテキストを上書き -- `preferOver`: このカタログエントリが優先順位で上回るべき、低優先度の Plugin/チャネル id -- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`: 選択サーフェス上の文言制御 -- `markdownCapable`: outbound フォーマット判断のために、そのチャネルを markdown 対応として示す -- `exposure.configured`: `false` に設定すると、設定済みチャネル一覧サーフェスからそのチャネルを隠す -- `exposure.setup`: `false` に設定すると、対話型 setup/configure picker からそのチャネルを隠す -- `exposure.docs`: ドキュメントナビゲーションサーフェス上で、そのチャネルを internal/private として示す -- `showConfigured` / `showInSetup`: 互換性のためにレガシーエイリアスも受け付けるが、`exposure` を優先する -- `quickstartAllowFrom`: 標準クイックスタート `allowFrom` フローへそのチャネルをオプトインする -- `forceAccountBinding`: アカウントが1つしかなくても明示的なアカウントバインディングを要求する -- `preferSessionLookupForAnnounceTarget`: announce ターゲット解決時にセッション参照を優先する +- `detailLabel`: より豊かな catalog/status surfaces のための二次ラベル +- `docsLabel`: docs link のリンクテキストを上書きする +- `preferOver`: この catalog entry が上位に出るべき低優先度の plugin/channel ids +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: selection-surface の copy controls +- `markdownCapable`: outbound formatting の判断用に、その channel が markdown 対応であることを示す +- `exposure.configured`: `false` に設定すると、その channel を configured-channel listing surfaces から隠す +- `exposure.setup`: `false` に設定すると、その channel を interactive setup/configure pickers から隠す +- `exposure.docs`: docs navigation surfaces 用に、その channel を internal/private としてマークする +- `showConfigured` / `showInSetup`: レガシーな別名も互換性のため引き続き受け付けるが、`exposure` を優先する +- `quickstartAllowFrom`: その channel を標準のクイックスタート `allowFrom` flow に opt in する +- `forceAccountBinding`: account が 1 つしかない場合でも明示的な account binding を要求する +- `preferSessionLookupForAnnounceTarget`: announce targets の解決時に session lookup を優先する -OpenClaw は **外部チャネルカタログ**（たとえば MPM -レジストリエクスポート）もマージできます。次のいずれかに JSON ファイルを配置してください: +OpenClaw は**外部 channel catalogs**（たとえば MPM +registry export）を merge することもできます。次のいずれかの場所に JSON file を置いてください。 - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -または、`OPENCLAW_PLUGIN_CATALOG_PATHS`（または `OPENCLAW_MPM_CATALOG_PATHS`）で、 -1つ以上の JSON ファイルを指定してください（カンマ/セミコロン/`PATH` 区切り）。 -各ファイルには `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }` を含める必要があります。パーサは `"entries"` キーのレガシーエイリアスとして `"packages"` または `"plugins"` も受け付けます。 +または、`OPENCLAW_PLUGIN_CATALOG_PATHS`（または `OPENCLAW_MPM_CATALOG_PATHS`）で、1 つ以上の JSON files を指定してください（comma/semicolon/`PATH` 区切り）。各 file には `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }` を含める必要があります。parser は `"entries"` key のレガシーな別名として `"packages"` または `"plugins"` も受け付けます。 -## コンテキストエンジン Plugin +## Context engine plugins -コンテキストエンジン Plugin は、取り込み、組み立て、 -Compaction のためのセッションコンテキストオーケストレーションを所有します。Plugin から -`api.registerContextEngine(id, factory)` で登録し、アクティブなエンジンは -`plugins.slots.contextEngine` で選択します。 +Context engine plugins は、ingest、assembly、Compaction に関する session context orchestration を所有します。Plugin から `api.registerContextEngine(id, factory)` で登録し、`plugins.slots.contextEngine` でアクティブな engine を選択します。 -これは、Plugin が単に memory 検索やフックを追加するだけではなく、デフォルトのコンテキスト -パイプラインを置き換えたり拡張したりする必要がある場合に使います。 +これは、memory search や hooks を追加するだけではなく、デフォルトの context +pipeline を置き換えたり拡張したりする必要がある場合に使用します。 ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1540,8 +1220,8 @@ export default function (api) { } ``` -エンジンが compaction アルゴリズムを**所有しない**場合でも、`compact()` は -実装したままにし、明示的に委譲してください: +engine が Compaction algorithm を所有**しない**場合でも、`compact()` +は実装したまま、明示的に委譲してください。 ```ts import { @@ -1576,51 +1256,46 @@ export default function (api) { } ``` -## 新しいケイパビリティの追加 +## 新しい capability の追加 -Plugin が現在の API に当てはまらない振る舞いを必要とする場合は、非公開の直接到達で -Plugin システムを迂回しないでください。不足しているケイパビリティを追加してください。 +Plugin が現在の API に合わない behavior を必要とする場合、private な内部依存で +plugin system を迂回しないでください。不足している capability を追加してください。 推奨される手順: -1. コアコントラクトを定義する - コアが所有すべき共有動作を決めます: ポリシー、フォールバック、設定マージ、 - ライフサイクル、チャネル向けセマンティクス、ランタイムヘルパー形状。 -2. 型付きの Plugin 登録/ランタイムサーフェスを追加する - 最小限で有用な型付きケイパビリティサーフェスで `OpenClawPluginApi` や - `api.runtime` を拡張します。 -3. コア + チャネル/機能コンシューマを接続する - チャネルと機能 Plugin は、新しいケイパビリティをコア経由で利用すべきであり、 - ベンダー実装を直接インポートすべきではありません。 -4. ベンダー実装を登録する - その後、ベンダー Plugin がそのケイパビリティに対してバックエンドを登録します。 -5. コントラクトカバレッジを追加する - 所有権と登録形状が時間とともに明示的に保たれるよう、テストを追加します。 +1. core contract を定義する + core が所有すべき共有 behavior を決めます。policy、fallback、config merge、 + lifecycle、channel-facing semantics、runtime helper shape を含みます。 +2. 型付きの plugin registration/runtime surfaces を追加する + `OpenClawPluginApi` および/または `api.runtime` を、最小限で有用な + 型付き capability surface で拡張します。 +3. core + channel/feature consumers を接続する + channels と feature plugins は、新しい capability を core を通じて利用するべきであり、vendor implementation を直接 import してはいけません。 +4. vendor implementations を登録する + その後、vendor plugins がその capability に対して backends を登録します。 +5. contract coverage を追加する + ownership と registration shape が時間とともに明示的なままであるよう、tests を追加します。 -これが、OpenClaw が1つの -プロバイダの世界観にハードコードされることなく、意見を持ち続ける方法です。具体的な -ファイルチェックリストと実例については [Capability Cookbook](/ja-JP/plugins/architecture) +これが、OpenClaw が意見を持ちながらも、1 つの provider の worldview にハードコードされない理由です。具体的な file checklist と worked example については、[Capability Cookbook](/ja-JP/plugins/architecture) を参照してください。 -### ケイパビリティのチェックリスト +### Capability checklist -新しいケイパビリティを追加するとき、実装は通常これらの -サーフェスをまとめて触るべきです: +新しい capability を追加するとき、実装では通常、次の surfaces をまとめて変更する必要があります。 -- `src//types.ts` のコアコントラクト型 -- `src//runtime.ts` のコアランナー/ランタイムヘルパー -- `src/plugins/types.ts` の Plugin API 登録サーフェス -- `src/plugins/registry.ts` の Plugin レジストリ配線 -- 機能/チャネル - Plugin がそれを使う必要がある場合の `src/plugins/runtime/*` の Plugin ランタイム公開 -- `src/test-utils/plugin-registration.ts` の capture/test ヘルパー -- `src/plugins/contracts/registry.ts` の所有権/コントラクトアサーション -- `docs/` のオペレーター/Plugin ドキュメント +- `src//types.ts` の core contract types +- `src//runtime.ts` の core runner/runtime helper +- `src/plugins/types.ts` の plugin API registration surface +- `src/plugins/registry.ts` の plugin registry wiring +- feature/channel + plugins がそれを利用する必要がある場合の `src/plugins/runtime/*` における plugin runtime exposure +- `src/test-utils/plugin-registration.ts` の capture/test helpers +- `src/plugins/contracts/registry.ts` の ownership/contract assertions +- `docs/` の operator/plugin docs -これらのサーフェスのいずれかが欠けている場合、それは通常、そのケイパビリティが -まだ完全には統合されていない兆候です。 +これらの surfaces のいずれかが欠けている場合、それは通常、その capability がまだ完全には統合されていない兆候です。 -### ケイパビリティテンプレート +### Capability template 最小パターン: @@ -1648,15 +1323,15 @@ const clip = await api.runtime.videoGeneration.generate({ }); ``` -コントラクトテストパターン: +contract test パターン: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -これにより、ルールはシンプルに保たれます: +これにより、ルールは単純に保たれます。 -- コアがケイパビリティコントラクト + オーケストレーションを所有する -- ベンダー Plugin がベンダー実装を所有する -- 機能/チャネル Plugin がランタイムヘルパーを利用する -- コントラクトテストが所有権を明示的に保つ +- core が capability contract + orchestration を所有する +- vendor plugins が vendor implementations を所有する +- feature/channel plugins が runtime helpers を利用する +- contract tests が ownership を明示的に保つ diff --git a/docs/ja-JP/plugins/manifest.md b/docs/ja-JP/plugins/manifest.md index 16bf2ce10..1ccabfd7f 100644 --- a/docs/ja-JP/plugins/manifest.md +++ b/docs/ja-JP/plugins/manifest.md @@ -1,66 +1,66 @@ --- read_when: - - OpenClaw Plugin を構築している場合 - - Plugin の設定スキーマを提供する必要がある場合、または Plugin の検証エラーをデバッグする必要がある場合 -summary: Plugin マニフェスト + JSON スキーマ要件（厳格な設定検証） -title: Plugin マニフェスト + - あなたはOpenClawのPluginを構築しています + - Pluginの設定スキーマを提供するか、Pluginの検証エラーをデバッグする必要があります +summary: Pluginマニフェスト + JSONスキーマ要件（厳格な設定検証） +title: Pluginマニフェスト x-i18n: - generated_at: "2026-04-12T23:28:55Z" + generated_at: "2026-04-15T04:43:35Z" model: gpt-5.4 provider: openai - source_hash: 93b57c7373e4ccd521b10945346db67991543bd2bed4cc8b6641e1f215b48579 + source_hash: ba2183bfa8802871e4ef33a0ebea290606e8351e9e83e25ee72456addb768730 source_path: plugins/manifest.md workflow: 15 --- -# Plugin マニフェスト（`openclaw.plugin.json`） +# Pluginマニフェスト（`openclaw.plugin.json`） -このページは、**ネイティブ OpenClaw Plugin マニフェスト**のみを対象としています。 +このページは、**ネイティブなOpenClaw Pluginマニフェスト**のみを対象としています。 -互換バンドルレイアウトについては、[Plugin bundles](/ja-JP/plugins/bundles) を参照してください。 +互換性のあるバンドルレイアウトについては、[Plugin bundles](/ja-JP/plugins/bundles)を参照してください。 互換バンドル形式では、異なるマニフェストファイルを使用します。 -- Codex バンドル: `.codex-plugin/plugin.json` -- Claude バンドル: `.claude-plugin/plugin.json` またはマニフェストなしのデフォルト Claude コンポーネントレイアウト -- Cursor バンドル: `.cursor-plugin/plugin.json` +- Codexバンドル: `.codex-plugin/plugin.json` +- Claudeバンドル: `.claude-plugin/plugin.json` またはマニフェストなしのデフォルトClaudeコンポーネントレイアウト +- Cursorバンドル: `.cursor-plugin/plugin.json` -OpenClaw はそれらのバンドルレイアウトも自動検出しますが、ここで説明する `openclaw.plugin.json` スキーマに対しては検証されません。 +OpenClawはこれらのバンドルレイアウトも自動検出しますが、ここで説明する`openclaw.plugin.json`スキーマに対しては検証されません。 -互換バンドルについては、OpenClaw は現在、バンドルメタデータに加えて、宣言された skill ルート、Claude コマンドルート、Claude バンドルの `settings.json` デフォルト、Claude バンドルの LSP デフォルト、および、そのレイアウトが OpenClaw ランタイムの期待に一致する場合の対応 hook pack を読み取ります。 +互換バンドルについて、OpenClawは現在、レイアウトがOpenClawランタイムの期待に一致する場合、バンドルメタデータに加えて、宣言されたskillルート、Claudeコマンドルート、Claudeバンドルの`settings.json`デフォルト値、ClaudeバンドルのLSPデフォルト値、対応するフックパックを読み取ります。 -すべてのネイティブ OpenClaw Plugin は、**plugin ルート**に `openclaw.plugin.json` ファイルを必ず含める必要があります。OpenClaw はこのマニフェストを使用して、**plugin コードを実行せずに**設定を検証します。マニフェストが存在しない、または無効な場合は plugin エラーとして扱われ、設定検証をブロックします。 +すべてのネイティブOpenClaw Pluginは、**pluginルート**に`openclaw.plugin.json`ファイルを**必ず**含める必要があります。OpenClawはこのマニフェストを使って、**Pluginコードを実行せずに**設定を検証します。マニフェストが存在しない、または無効な場合はPluginエラーとして扱われ、設定の検証はブロックされます。 -完全な plugin システムガイドについては、[Plugins](/ja-JP/tools/plugin) を参照してください。 -ネイティブ capability モデルと現在の外部互換性ガイダンスについては、 -[Capability model](/ja-JP/plugins/architecture#public-capability-model) を参照してください。 +完全なPluginシステムガイドについては、[Plugins](/ja-JP/tools/plugin)を参照してください。 +ネイティブのケーパビリティモデルと現在の外部互換性ガイダンスについては、[Capability model](/ja-JP/plugins/architecture#public-capability-model)を参照してください。 ## このファイルの役割 -`openclaw.plugin.json` は、OpenClaw が plugin コードを読み込む前に読むメタデータです。 +`openclaw.plugin.json`は、OpenClawがあなたのPluginコードを読み込む前に読み取るメタデータです。 用途: -- plugin の識別情報 -- 設定検証 -- plugin ランタイムを起動しなくても利用できる認証およびオンボーディングのメタデータ -- ランタイム読み込み前にコントロールプレーンの各サーフェスが確認できる軽量なアクティベーションヒント -- ランタイム読み込み前にセットアップ/オンボーディングの各サーフェスが確認できる軽量なセットアップ記述子 -- plugin ランタイム読み込み前に解決されるべきエイリアスおよび自動有効化メタデータ -- plugin ランタイム読み込み前に plugin を自動アクティベートすべきモデルファミリー所有権の簡略メタデータ -- バンドル互換配線およびコントラクト網羅に使用される静的 capability 所有スナップショット -- ランタイムを読み込まずにカタログおよび検証サーフェスへマージされるべきチャネル固有の設定メタデータ -- 設定 UI ヒント +- Pluginの識別情報 +- 設定の検証 +- Pluginランタイムを起動せずに利用可能であるべき認証およびオンボーディングのメタデータ +- コントロールプレーンのサーフェスがランタイム読み込み前に確認できる、低コストなアクティベーションヒント +- セットアップ/オンボーディングのサーフェスがランタイム読み込み前に確認できる、低コストなセットアップ記述子 +- Pluginランタイム読み込み前に解決されるべきエイリアスおよび自動有効化メタデータ +- Pluginランタイム読み込み前にPluginを自動アクティベートすべきモデルファミリー所有権の短縮メタデータ +- バンドル互換配線とコントラクトカバレッジに使われる静的なケーパビリティ所有権スナップショット +- 共有`openclaw qa`ホストがPluginランタイム読み込み前に確認できる、低コストなQAランナーメタデータ +- ランタイムを読み込まずにカタログおよび検証サーフェスにマージされるべき、チャネル固有の設定メタデータ +- 設定UIのヒント 用途ではないもの: - ランタイム動作の登録 -- コードのエントリーポイント宣言 -- npm install メタデータ +- コードのエントリーポイントの宣言 +- npmインストールメタデータ -これらは plugin コードと `package.json` に属します。 +これらはPluginコードおよび`package.json`に属します。 -## 最小例 +## 最小の例 ```json { @@ -73,7 +73,7 @@ OpenClaw はそれらのバンドルレイアウトも自動検出しますが } ``` -## リッチな例 +## 詳細な例 ```json { @@ -129,62 +129,63 @@ OpenClaw はそれらのバンドルレイアウトも自動検出しますが } ``` -## 最上位フィールドのリファレンス +## トップレベルフィールドのリファレンス -| フィールド | 必須 | 型 | 意味 | -| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | はい | `string` | 正式な plugin ID。これは `plugins.entries.` で使用される ID です。 | -| `configSchema` | はい | `object` | この plugin の設定に対するインライン JSON Schema。 | -| `enabledByDefault` | いいえ | `true` | バンドルされた plugin をデフォルトで有効としてマークします。省略するか、`true` 以外の値を設定すると、その plugin はデフォルトで無効のままになります。 | -| `legacyPluginIds` | いいえ | `string[]` | この正式な plugin ID に正規化されるレガシー ID。 | -| `autoEnableWhenConfiguredProviders` | いいえ | `string[]` | 認証、設定、またはモデル参照でそれらが言及されたときに、この plugin を自動有効化すべき provider ID。 | -| `kind` | いいえ | `"memory"` \| `"context-engine"` | `plugins.slots.*` で使用される排他的な plugin 種別を宣言します。 | -| `channels` | いいえ | `string[]` | この plugin が所有するチャネル ID。検出と設定検証に使用されます。 | -| `providers` | いいえ | `string[]` | この plugin が所有する provider ID。 | -| `modelSupport` | いいえ | `object` | ランタイム前に plugin を自動ロードするために使用される、マニフェスト所有のモデルファミリー簡略メタデータ。 | -| `cliBackends` | いいえ | `string[]` | この plugin が所有する CLI 推論バックエンド ID。明示的な設定参照からの起動時自動アクティベーションに使用されます。 | -| `commandAliases` | いいえ | `object[]` | ランタイム読み込み前に plugin を認識した設定および CLI 診断を生成すべき、この plugin が所有するコマンド名。 | -| `providerAuthEnvVars` | いいえ | `Record` | OpenClaw が plugin コードを読み込まずに確認できる、軽量な provider 認証用環境変数メタデータ。 | -| `providerAuthAliases` | いいえ | `Record` | 認証検索のために別の provider ID を再利用すべき provider ID。たとえば、ベース provider の API キーと認証プロファイルを共有する coding provider などです。 | -| `channelEnvVars` | いいえ | `Record` | OpenClaw が plugin コードを読み込まずに確認できる、軽量なチャネル環境変数メタデータ。env 駆動のチャネルセットアップや、汎用の起動/設定ヘルパーが参照すべき認証サーフェスに使用します。 | -| `providerAuthChoices` | いいえ | `object[]` | オンボーディングピッカー、優先 provider 解決、単純な CLI フラグ配線のための軽量な認証選択メタデータ。 | -| `activation` | いいえ | `object` | provider、command、channel、route、および capability トリガー読み込みのための軽量なアクティベーションヒント。メタデータのみであり、実際の動作は引き続き plugin ランタイムが所有します。 | -| `setup` | いいえ | `object` | 検出およびセットアップの各サーフェスが plugin ランタイムを読み込まずに確認できる、軽量なセットアップ/オンボーディング記述子。 | -| `contracts` | いいえ | `object` | speech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search、およびツール所有権のための静的なバンドル capability スナップショット。 | -| `channelConfigs` | いいえ | `Record` | ランタイム読み込み前に検出および検証サーフェスへマージされる、マニフェスト所有のチャネル設定メタデータ。 | -| `skills` | いいえ | `string[]` | plugin ルートからの相対パスで指定する、読み込む Skills ディレクトリ。 | -| `name` | いいえ | `string` | 人が読むための plugin 名。 | -| `description` | いいえ | `string` | plugin サーフェスに表示される短い要約。 | -| `version` | いいえ | `string` | 情報表示用の plugin バージョン。 | -| `uiHints` | いいえ | `Record` | 設定フィールド用の UI ラベル、プレースホルダー、および機密性ヒント。 | +| フィールド | 必須 | 型 | 意味 | +| ------------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | はい | `string` | 正規のPlugin idです。このidは`plugins.entries.`で使用されます。 | +| `configSchema` | はい | `object` | このPlugin設定用のインラインJSON Schemaです。 | +| `enabledByDefault` | いいえ | `true` | バンドルされたPluginをデフォルトで有効としてマークします。デフォルトで無効のままにするには、省略するか、`true`以外の値を設定します。 | +| `legacyPluginIds` | いいえ | `string[]` | この正規Plugin idに正規化されるレガシーidです。 | +| `autoEnableWhenConfiguredProviders` | いいえ | `string[]` | 認証、設定、またはモデル参照で言及されたときに、このPluginを自動有効化すべきprovider idです。 | +| `kind` | いいえ | `"memory"` \| `"context-engine"` | `plugins.slots.*`で使用される排他的なPlugin種別を宣言します。 | +| `channels` | いいえ | `string[]` | このPluginが所有するchannel idです。検出と設定検証に使用されます。 | +| `providers` | いいえ | `string[]` | このPluginが所有するprovider idです。 | +| `modelSupport` | いいえ | `object` | ランタイム前にPluginを自動ロードするために使われる、マニフェスト所有の短縮モデルファミリーメタデータです。 | +| `cliBackends` | いいえ | `string[]` | このPluginが所有するCLI推論バックエンドidです。明示的な設定参照からの起動時自動アクティベーションに使用されます。 | +| `commandAliases` | いいえ | `object[]` | ランタイム読み込み前に、Pluginを認識した設定およびCLI診断を生成すべき、このPluginが所有するコマンド名です。 | +| `providerAuthEnvVars` | いいえ | `Record` | OpenClawがPluginコードを読み込まずに確認できる、低コストなprovider認証環境変数メタデータです。 | +| `providerAuthAliases` | いいえ | `Record` | 認証ルックアップに別のprovider idを再利用すべきprovider idです。たとえば、ベースproviderのAPIキーと認証プロファイルを共有するcoding providerなどです。 | +| `channelEnvVars` | いいえ | `Record` | OpenClawがPluginコードを読み込まずに確認できる、低コストなchannel環境変数メタデータです。環境変数駆動のchannelセットアップや、汎用の起動/設定ヘルパーが認識すべき認証サーフェスにはこれを使用してください。 | +| `providerAuthChoices` | いいえ | `object[]` | オンボーディングピッカー、優先provider解決、単純なCLIフラグ配線のための、低コストな認証選択メタデータです。 | +| `activation` | いいえ | `object` | provider、command、channel、route、およびケーパビリティトリガーによる読み込みのための、低コストなアクティベーションヒントです。メタデータのみであり、実際の動作は引き続きPluginランタイムが所有します。 | +| `setup` | いいえ | `object` | 検出およびセットアップのサーフェスがPluginランタイムを読み込まずに確認できる、低コストなセットアップ/オンボーディング記述子です。 | +| `qaRunners` | いいえ | `object[]` | 共有`openclaw qa`ホストがPluginランタイム読み込み前に使用する、低コストなQAランナー記述子です。 | +| `contracts` | いいえ | `object` | speech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search、およびツール所有権のための静的なバンドル済みケーパビリティスナップショットです。 | +| `channelConfigs` | いいえ | `Record` | ランタイム読み込み前に検出および検証サーフェスへマージされる、マニフェスト所有のchannel設定メタデータです。 | +| `skills` | いいえ | `string[]` | pluginルートからの相対パスで指定する、読み込むSkillsディレクトリです。 | +| `name` | いいえ | `string` | 人が読めるPlugin名です。 | +| `description` | いいえ | `string` | Pluginサーフェスに表示される短い要約です。 | +| `version` | いいえ | `string` | 情報用のPluginバージョンです。 | +| `uiHints` | いいえ | `Record` | 設定フィールド用のUIラベル、プレースホルダー、および機密性ヒントです。 | -## `providerAuthChoices` リファレンス +## `providerAuthChoices`リファレンス -各 `providerAuthChoices` エントリは、1 つのオンボーディングまたは認証の選択肢を記述します。 -OpenClaw は provider ランタイムを読み込む前にこれを読み取ります。 +各`providerAuthChoices`エントリは、1つのオンボーディングまたは認証の選択肢を記述します。 +OpenClawはこれをproviderランタイムが読み込まれる前に読み取ります。 -| フィールド | 必須 | 型 | 意味 | -| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | はい | `string` | この選択肢が属する provider ID。 | -| `method` | はい | `string` | ディスパッチ先の認証方式 ID。 | -| `choiceId` | はい | `string` | オンボーディングおよび CLI フローで使用される安定した認証選択肢 ID。 | -| `choiceLabel` | いいえ | `string` | ユーザー向けラベル。省略した場合、OpenClaw は `choiceId` にフォールバックします。 | -| `choiceHint` | いいえ | `string` | ピッカー用の短い補助テキスト。 | -| `assistantPriority` | いいえ | `number` | アシスタント主導のインタラクティブピッカーでは、値が小さいほど先に並びます。 | -| `assistantVisibility` | いいえ | `"visible"` \| `"manual-only"` | アシスタントのピッカーではこの選択肢を非表示にしつつ、手動 CLI 選択は引き続き許可します。 | -| `deprecatedChoiceIds` | いいえ | `string[]` | ユーザーをこの置き換え先の選択肢にリダイレクトすべきレガシー選択肢 ID。 | -| `groupId` | いいえ | `string` | 関連する選択肢をグループ化するための任意のグループ ID。 | -| `groupLabel` | いいえ | `string` | そのグループのユーザー向けラベル。 | -| `groupHint` | いいえ | `string` | グループ用の短い補助テキスト。 | -| `optionKey` | いいえ | `string` | 単一フラグの単純な認証フロー用の内部オプションキー。 | -| `cliFlag` | いいえ | `string` | `--openrouter-api-key` のような CLI フラグ名。 | -| `cliOption` | いいえ | `string` | `--openrouter-api-key ` のような完全な CLI オプション形式。 | -| `cliDescription` | いいえ | `string` | CLI ヘルプで使用される説明。 | -| `onboardingScopes` | いいえ | `Array<"text-inference" \| "image-generation">` | この選択肢をどのオンボーディングサーフェスに表示するか。省略した場合、デフォルトは `["text-inference"]` です。 | +| フィールド | 必須 | 型 | 意味 | +| --------------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `provider` | はい | `string` | この選択肢が属するprovider idです。 | +| `method` | はい | `string` | ディスパッチ先の認証メソッドidです。 | +| `choiceId` | はい | `string` | オンボーディングおよびCLIフローで使われる、安定した認証選択肢idです。 | +| `choiceLabel` | いいえ | `string` | ユーザー向けラベルです。省略した場合、OpenClawは`choiceId`にフォールバックします。 | +| `choiceHint` | いいえ | `string` | ピッカー用の短い補助テキストです。 | +| `assistantPriority` | いいえ | `number` | 値が小さいほど、assistant主導のインタラクティブピッカーで先に並びます。 | +| `assistantVisibility` | いいえ | `"visible"` \| `"manual-only"` | assistantピッカーではこの選択肢を非表示にしつつ、手動CLI選択は引き続き許可します。 | +| `deprecatedChoiceIds` | いいえ | `string[]` | この置き換え選択肢へユーザーをリダイレクトすべき、レガシーな選択肢idです。 | +| `groupId` | いいえ | `string` | 関連する選択肢をグループ化するための任意のグループidです。 | +| `groupLabel` | いいえ | `string` | そのグループのユーザー向けラベルです。 | +| `groupHint` | いいえ | `string` | そのグループ用の短い補助テキストです。 | +| `optionKey` | いいえ | `string` | 単一フラグの単純な認証フロー用の内部オプションキーです。 | +| `cliFlag` | いいえ | `string` | `--openrouter-api-key`のようなCLIフラグ名です。 | +| `cliOption` | いいえ | `string` | `--openrouter-api-key `のような完全なCLIオプション形式です。 | +| `cliDescription` | いいえ | `string` | CLIヘルプで使われる説明です。 | +| `onboardingScopes` | いいえ | `Array<"text-inference" \| "image-generation">` | この選択肢を表示すべきオンボーディングサーフェスです。省略した場合、デフォルトは`["text-inference"]`です。 | -## `commandAliases` リファレンス +## `commandAliases`リファレンス -`commandAliases` は、ユーザーが誤って `plugins.allow` に入れたり、ルート CLI コマンドとして実行しようとしたりする可能性がある、plugin 所有のランタイムコマンド名がある場合に使用します。OpenClaw は、このメタデータを使用して、plugin ランタイムコードを import せずに診断を行います。 +Pluginが、ユーザーが誤って`plugins.allow`に入れたり、ルートCLIコマンドとして実行しようとしたりする可能性があるランタイムコマンド名を所有している場合は、`commandAliases`を使用します。OpenClawはこのメタデータを、Pluginランタイムコードをインポートせずに診断のために使用します。 ```json { @@ -198,18 +199,37 @@ OpenClaw は provider ランタイムを読み込む前にこれを読み取り } ``` -| フィールド | 必須 | 型 | 意味 | -| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | -| `name` | はい | `string` | この plugin に属するコマンド名。 | -| `kind` | いいえ | `"runtime-slash"` | このエイリアスを、ルート CLI コマンドではなくチャットのスラッシュコマンドとしてマークします。 | -| `cliCommand` | いいえ | `string` | 存在する場合、CLI 操作向けに提案する関連ルート CLI コマンド。 | +| フィールド | 必須 | 型 | 意味 | +| ------------ | -------- | ----------------- | ----------------------------------------------------------------------------- | +| `name` | はい | `string` | このPluginに属するコマンド名です。 | +| `kind` | いいえ | `"runtime-slash"` | このエイリアスを、ルートCLIコマンドではなくチャットのスラッシュコマンドとして示します。 | +| `cliCommand` | いいえ | `string` | 存在する場合、CLI操作向けに提案する関連ルートCLIコマンドです。 | -## `activation` リファレンス +## `activation`リファレンス -`activation` は、その plugin を後でアクティベートすべきコントロールプレーンイベントを低コストで宣言できる場合に使用します。 +Pluginが、どのコントロールプレーンイベントによって後でアクティベートされるべきかを低コストで宣言できる場合は、`activation`を使用します。 -このブロックはメタデータのみです。ランタイム動作を登録するものではなく、`register(...)`、`setupEntry`、その他のランタイム/plugin エントリーポイントを置き換えるものでもありません。 -現在のコンシューマーはこれを、より広い plugin 読み込みの前の絞り込みヒントとして使用しているため、アクティベーションメタデータが欠けていても、通常は性能面のコストが発生するだけです。レガシーなマニフェスト所有権フォールバックがまだ存在する間は、正しさは変わらないはずです。 +## `qaRunners`リファレンス + +Pluginが共有`openclaw qa`ルート配下に1つ以上のトランスポートランナーを追加する場合は、`qaRunners`を使用します。このメタデータは低コストかつ静的に保ってください。実際のCLI登録は、`qaRunnerCliRegistrations`をエクスポートする軽量な`runtime-api.ts`サーフェスを通じて、引き続きPluginランタイムが所有します。 + +```json +{ + "qaRunners": [ + { + "commandName": "matrix", + "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" + } + ] +} +``` + +| フィールド | 必須 | 型 | 意味 | +| ------------- | -------- | -------- | ----------------------------------------------------------------------------- | +| `commandName` | はい | `string` | `openclaw qa`配下にマウントされるサブコマンドです。たとえば`matrix`です。 | +| `description` | いいえ | `string` | 共有ホストがスタブコマンドを必要とする場合に使われるフォールバックのヘルプテキストです。 | + +このブロックはメタデータのみです。ランタイム動作を登録するものではなく、`register(...)`、`setupEntry`、その他のランタイム/Pluginエントリーポイントを置き換えるものでもありません。現在のコンシューマーはこれを、より広いPlugin読み込み前の絞り込みヒントとして使っているため、`activation`メタデータが欠けていても通常は性能コストが増えるだけです。レガシーなマニフェスト所有権フォールバックがまだ存在する限り、正しさは変わらないはずです。 ```json { @@ -223,27 +243,23 @@ OpenClaw は provider ランタイムを読み込む前にこれを読み取り } ``` -| フィールド | 必須 | 型 | 意味 | -| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- | -| `onProviders` | いいえ | `string[]` | 要求されたときにこの plugin をアクティベートすべき provider ID。 | -| `onCommands` | いいえ | `string[]` | この plugin をアクティベートすべきコマンド ID。 | -| `onChannels` | いいえ | `string[]` | この plugin をアクティベートすべきチャネル ID。 | -| `onRoutes` | いいえ | `string[]` | この plugin をアクティベートすべき route 種別。 | -| `onCapabilities` | いいえ | `Array<"provider" \| "channel" \| "tool" \| "hook">` | コントロールプレーンのアクティベーション計画で使用される大まかな capability ヒント。 | +| フィールド | 必須 | 型 | 意味 | +| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------ | +| `onProviders` | いいえ | `string[]` | リクエスト時にこのPluginをアクティベートすべきprovider idです。 | +| `onCommands` | いいえ | `string[]` | このPluginをアクティベートすべきcommand idです。 | +| `onChannels` | いいえ | `string[]` | このPluginをアクティベートすべきchannel idです。 | +| `onRoutes` | いいえ | `string[]` | このPluginをアクティベートすべきroute種別です。 | +| `onCapabilities` | いいえ | `Array<"provider" \| "channel" \| "tool" \| "hook">` | コントロールプレーンのアクティベーション計画で使われる広範なケーパビリティヒントです。 | 現在のライブコンシューマー: -- コマンドトリガーの CLI 計画は、レガシーな - `commandAliases[].cliCommand` または `commandAliases[].name` にフォールバックします -- チャネルトリガーの setup/channel 計画は、明示的なチャネルアクティベーションメタデータがない場合、レガシーな `channels[]` - 所有権にフォールバックします -- provider トリガーの setup/runtime 計画は、明示的な provider - アクティベーションメタデータがない場合、レガシーな - `providers[]` および最上位の `cliBackends[]` 所有権にフォールバックします +- コマンドトリガーのCLI計画は、レガシーな`commandAliases[].cliCommand`または`commandAliases[].name`にフォールバックします +- チャネルトリガーのセットアップ/チャネル計画は、明示的なチャネルアクティベーションメタデータがない場合、レガシーな`channels[]`所有権にフォールバックします +- providerトリガーのセットアップ/ランタイム計画は、明示的なproviderアクティベーションメタデータがない場合、レガシーな`providers[]`およびトップレベル`cliBackends[]`所有権にフォールバックします -## `setup` リファレンス +## `setup`リファレンス -`setup` は、セットアップおよびオンボーディングの各サーフェスが、ランタイム読み込み前に低コストな plugin 所有メタデータを必要とする場合に使用します。 +ランタイム読み込み前に、セットアップおよびオンボーディングのサーフェスがPlugin所有の低コストなメタデータを必要とする場合は、`setup`を使用します。 ```json { @@ -262,32 +278,32 @@ OpenClaw は provider ランタイムを読み込む前にこれを読み取り } ``` -最上位の `cliBackends` は引き続き有効で、CLI 推論バックエンドを記述し続けます。`setup.cliBackends` は、メタデータのみを維持すべきコントロールプレーン/セットアップフロー向けの、セットアップ固有の記述子サーフェスです。 +トップレベルの`cliBackends`は引き続き有効で、CLI推論バックエンドを記述し続けます。`setup.cliBackends`は、メタデータのみを維持すべきコントロールプレーン/セットアップフロー向けの、セットアップ固有の記述子サーフェスです。 -存在する場合、`setup.providers` と `setup.cliBackends` は、セットアップ検出のための優先される記述子優先のルックアップサーフェスです。記述子が候補 plugin の絞り込みだけを行い、セットアップにさらに豊富なセットアップ時ランタイムフックが必要な場合は、`requiresRuntime: true` を設定し、フォールバック実行パスとして `setup-api` を維持してください。 +`setup.providers`および`setup.cliBackends`が存在する場合、これらはセットアップ検出における優先的な記述子ファーストのルックアップサーフェスになります。記述子が候補Pluginを絞り込むだけで、セットアップ時にさらに豊富なランタイムフックが必要な場合は、`requiresRuntime: true`を設定し、フォールバック実行パスとして`setup-api`を維持してください。 -セットアップのルックアップでは plugin 所有の `setup-api` コードを実行できるため、正規化された `setup.providers[].id` と `setup.cliBackends[]` の値は、検出された plugin 全体で一意である必要があります。所有権が曖昧な場合は、検出順で勝者を選ぶのではなく、クローズドに失敗します。 +セットアップのルックアップはPlugin所有の`setup-api`コードを実行できるため、正規化された`setup.providers[].id`および`setup.cliBackends[]`の値は、検出されたPlugin全体で一意でなければなりません。所有権が曖昧な場合は、検出順で勝者を選ぶのではなく、クローズドに失敗します。 -### `setup.providers` リファレンス +### `setup.providers`リファレンス -| フィールド | 必須 | 型 | 意味 | -| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ | -| `id` | はい | `string` | セットアップまたはオンボーディング中に公開される provider ID。正規化された ID はグローバルに一意に保ってください。 | -| `authMethods` | いいえ | `string[]` | 完全なランタイムを読み込まずにこの provider がサポートするセットアップ/認証方式 ID。 | -| `envVars` | いいえ | `string[]` | plugin ランタイム読み込み前に汎用の setup/status サーフェスが確認できる環境変数。 | +| フィールド | 必須 | 型 | 意味 | +| ------------- | -------- | ---------- | -------------------------------------------------------------------------------------- | +| `id` | はい | `string` | セットアップまたはオンボーディング中に公開されるprovider idです。正規化されたidはグローバルに一意に保ってください。 | +| `authMethods` | いいえ | `string[]` | フルランタイムを読み込まずにこのproviderがサポートするセットアップ/認証メソッドidです。 | +| `envVars` | いいえ | `string[]` | 汎用のセットアップ/ステータスサーフェスがPluginランタイム読み込み前に確認できる環境変数です。 | -### `setup` フィールド +### `setup`フィールド -| フィールド | 必須 | 型 | 意味 | -| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `providers` | いいえ | `object[]` | セットアップおよびオンボーディング中に公開される provider セットアップ記述子。 | -| `cliBackends` | いいえ | `string[]` | 記述子優先のセットアップルックアップで使用されるセットアップ時バックエンド ID。正規化された ID はグローバルに一意に保ってください。 | -| `configMigrations` | いいえ | `string[]` | この plugin の setup サーフェスが所有する設定マイグレーション ID。 | -| `requiresRuntime` | いいえ | `boolean` | 記述子ルックアップ後も setup に `setup-api` の実行が必要かどうか。 | +| フィールド | 必須 | 型 | 意味 | +| ------------------ | -------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `providers` | いいえ | `object[]` | セットアップおよびオンボーディング中に公開されるproviderセットアップ記述子です。 | +| `cliBackends` | いいえ | `string[]` | 記述子ファーストのセットアップルックアップで使われるセットアップ時バックエンドidです。正規化されたidはグローバルに一意に保ってください。 | +| `configMigrations` | いいえ | `string[]` | このPluginのセットアップサーフェスが所有する設定移行idです。 | +| `requiresRuntime` | いいえ | `boolean` | 記述子ルックアップ後もセットアップに`setup-api`の実行が必要かどうかです。 | -## `uiHints` リファレンス +## `uiHints`リファレンス -`uiHints` は、設定フィールド名から小さなレンダリングヒントへのマップです。 +`uiHints`は、設定フィールド名から小さなレンダリングヒントへのマップです。 ```json { @@ -304,18 +320,18 @@ OpenClaw は provider ランタイムを読み込む前にこれを読み取り 各フィールドヒントには次を含めることができます。 -| フィールド | 型 | 意味 | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | ユーザー向けのフィールドラベル。 | -| `help` | `string` | 短い補助テキスト。 | -| `tags` | `string[]` | 任意の UI タグ。 | -| `advanced` | `boolean` | このフィールドを高度な項目としてマークします。 | -| `sensitive` | `boolean` | このフィールドをシークレットまたは機密情報としてマークします。 | -| `placeholder` | `string` | フォーム入力用のプレースホルダーテキスト。 | +| フィールド | 型 | 意味 | +| ------------- | ---------- | -------------------------------------- | +| `label` | `string` | ユーザー向けのフィールドラベルです。 | +| `help` | `string` | 短い補助テキストです。 | +| `tags` | `string[]` | 任意のUIタグです。 | +| `advanced` | `boolean` | このフィールドを高度な項目として示します。 | +| `sensitive` | `boolean` | このフィールドを秘密情報または機密情報として示します。 | +| `placeholder` | `string` | フォーム入力用のプレースホルダーテキストです。 | -## `contracts` リファレンス +## `contracts`リファレンス -`contracts` は、OpenClaw が plugin ランタイムを import せずに読み取れる、静的な capability 所有メタデータにのみ使用してください。 +OpenClawがPluginランタイムをインポートせずに読み取れる、静的なケーパビリティ所有権メタデータにのみ`contracts`を使用してください。 ```json { @@ -335,21 +351,21 @@ OpenClaw は provider ランタイムを読み込む前にこれを読み取り 各リストは任意です。 -| フィールド | 型 | 意味 | -| -------------------------------- | ---------- | -------------------------------------------------------------- | -| `speechProviders` | `string[]` | この plugin が所有する speech provider ID。 | -| `realtimeTranscriptionProviders` | `string[]` | この plugin が所有する realtime-transcription provider ID。 | -| `realtimeVoiceProviders` | `string[]` | この plugin が所有する realtime-voice provider ID。 | -| `mediaUnderstandingProviders` | `string[]` | この plugin が所有する media-understanding provider ID。 | -| `imageGenerationProviders` | `string[]` | この plugin が所有する image-generation provider ID。 | -| `videoGenerationProviders` | `string[]` | この plugin が所有する video-generation provider ID。 | -| `webFetchProviders` | `string[]` | この plugin が所有する web-fetch provider ID。 | -| `webSearchProviders` | `string[]` | この plugin が所有する web-search provider ID。 | -| `tools` | `string[]` | バンドルされたコントラクトチェック用にこの plugin が所有するエージェントツール名。 | +| フィールド | 型 | 意味 | +| -------------------------------- | ---------- | ---------------------------------------------------------- | +| `speechProviders` | `string[]` | このPluginが所有するspeech provider idです。 | +| `realtimeTranscriptionProviders` | `string[]` | このPluginが所有するrealtime-transcription provider idです。 | +| `realtimeVoiceProviders` | `string[]` | このPluginが所有するrealtime-voice provider idです。 | +| `mediaUnderstandingProviders` | `string[]` | このPluginが所有するmedia-understanding provider idです。 | +| `imageGenerationProviders` | `string[]` | このPluginが所有するimage-generation provider idです。 | +| `videoGenerationProviders` | `string[]` | このPluginが所有するvideo-generation provider idです。 | +| `webFetchProviders` | `string[]` | このPluginが所有するweb-fetch provider idです。 | +| `webSearchProviders` | `string[]` | このPluginが所有するweb-search provider idです。 | +| `tools` | `string[]` | バンドルされたコントラクトチェックのためにこのPluginが所有するagentツール名です。 | -## `channelConfigs` リファレンス +## `channelConfigs`リファレンス -`channelConfigs` は、チャネル Plugin がランタイム読み込み前に低コストな設定メタデータを必要とする場合に使用します。 +channel Pluginが、ランタイム読み込み前に低コストな設定メタデータを必要とする場合は、`channelConfigs`を使用します。 ```json { @@ -376,19 +392,19 @@ OpenClaw は provider ランタイムを読み込む前にこれを読み取り } ``` -各チャネルエントリには次を含めることができます。 +各channelエントリには次を含めることができます。 -| フィールド | 型 | 意味 | -| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | -| `schema` | `object` | `channels.` 用の JSON Schema。宣言された各チャネル設定エントリで必須です。 | -| `uiHints` | `Record` | そのチャネル設定セクション用の任意の UI ラベル/プレースホルダー/機密性ヒント。 | -| `label` | `string` | ランタイムメタデータの準備ができていない場合に、ピッカーおよび inspect サーフェスへマージされるチャネルラベル。 | -| `description` | `string` | inspect および catalog サーフェス向けの短いチャネル説明。 | -| `preferOver` | `string[]` | 選択サーフェスでこのチャネルが優先されるべき、レガシーまたは低優先度の plugin ID。 | +| フィールド | 型 | 意味 | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | +| `schema` | `object` | `channels.`用のJSON Schemaです。宣言された各channel設定エントリで必須です。 | +| `uiHints` | `Record` | そのchannel設定セクション用の任意のUIラベル/プレースホルダー/機密性ヒントです。 | +| `label` | `string` | ランタイムメタデータの準備ができていないときに、ピッカーおよびinspectサーフェスにマージされるchannelラベルです。 | +| `description` | `string` | inspectおよびカタログサーフェス向けの短いchannel説明です。 | +| `preferOver` | `string[]` | 選択サーフェスでこのchannelが優先されるべき、レガシーまたは低優先度のplugin idです。 | -## `modelSupport` リファレンス +## `modelSupport`リファレンス -`modelSupport` は、OpenClaw が `gpt-5.4` や `claude-sonnet-4.6` のような短縮モデル ID から、plugin ランタイム読み込み前に provider Plugin を推測すべき場合に使用します。 +Pluginランタイム読み込み前に、OpenClawが`gpt-5.4`や`claude-sonnet-4.6`のような短縮モデルidからあなたのprovider Pluginを推論すべき場合は、`modelSupport`を使用します。 ```json { @@ -399,74 +415,60 @@ OpenClaw は provider ランタイムを読み込む前にこれを読み取り } ``` -OpenClaw は次の優先順位を適用します。 +OpenClawは次の優先順位を適用します。 -- 明示的な `provider/model` 参照は、所有する `providers` マニフェストメタデータを使用します -- `modelPatterns` は `modelPrefixes` より優先されます -- 1 つの非バンドル plugin と 1 つのバンドル plugin の両方が一致する場合、非バンドル plugin が優先されます -- 残る曖昧さは、ユーザーまたは設定が provider を指定するまで無視されます +- 明示的な`provider/model`参照では、所有する`providers`マニフェストメタデータが使われます +- `modelPatterns`は`modelPrefixes`より優先されます +- バンドルされていないPluginとバンドルされたPluginの両方が一致する場合は、バンドルされていないPluginが優先されます +- 残る曖昧さは、ユーザーまたは設定がproviderを指定するまで無視されます フィールド: -| フィールド | 型 | 意味 | -| --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 短縮モデル ID に対して `startsWith` で一致させるプレフィックス。 | -| `modelPatterns` | `string[]` | プロファイル接尾辞を除去した後の短縮モデル ID に対して一致させる正規表現ソース。 | +| フィールド | 型 | 意味 | +| --------------- | ---------- | ------------------------------------------------------------------------------------ | +| `modelPrefixes` | `string[]` | 短縮モデルidに対して`startsWith`で一致させるプレフィックスです。 | +| `modelPatterns` | `string[]` | プロファイル接尾辞を除去した後の短縮モデルidに対して一致させる正規表現ソースです。 | -レガシーな最上位 capability キーは非推奨です。`openclaw doctor --fix` を使用して -`speechProviders`、`realtimeTranscriptionProviders`、 -`realtimeVoiceProviders`、`mediaUnderstandingProviders`、 -`imageGenerationProviders`、`videoGenerationProviders`、 -`webFetchProviders`、および `webSearchProviders` を `contracts` 配下へ移動してください。通常の -マニフェスト読み込みでは、これらの最上位フィールドを capability -所有権として扱わなくなっています。 +レガシーなトップレベルのケーパビリティキーは非推奨です。`openclaw doctor --fix`を使用して、`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`を`contracts`配下へ移動してください。通常のマニフェスト読み込みでは、これらのトップレベルフィールドはもはやケーパビリティ所有権として扱われません。 -## マニフェストと `package.json` の違い +## マニフェストと`package.json`の違い -この 2 つのファイルは異なる役割を持ちます。 +この2つのファイルは異なる役割を持ちます。 -| ファイル | 用途 | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | plugin コード実行前に存在している必要がある、検出、設定検証、認証選択メタデータ、および UI ヒント | -| `package.json` | npm メタデータ、依存関係のインストール、およびエントリーポイント、インストール制御、セットアップ、または catalog メタデータに使用される `openclaw` ブロック | +| ファイル | 用途 | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.plugin.json` | 検出、設定検証、認証選択メタデータ、およびPluginコード実行前に存在している必要があるUIヒント | +| `package.json` | npmメタデータ、依存関係のインストール、およびエントリーポイント、インストールゲーティング、セットアップ、またはカタログメタデータに使われる`openclaw`ブロック | -どこにどのメタデータを置くべきか迷った場合は、次のルールを使ってください。 +どこに置くべきメタデータか迷った場合は、次のルールを使ってください。 -- OpenClaw が plugin コードの読み込み前に知っている必要があるなら、`openclaw.plugin.json` に置きます -- パッケージング、エントリーファイル、または npm install の動作に関するものなら、`package.json` に置きます +- OpenClawがPluginコードを読み込む前に知っておく必要がある場合は、`openclaw.plugin.json`に置きます +- パッケージング、エントリーファイル、またはnpmインストール動作に関するものであれば、`package.json`に置きます -### 検出に影響する `package.json` フィールド +### 検出に影響する`package.json`フィールド -一部のランタイム前 plugin メタデータは、意図的に `openclaw.plugin.json` ではなく `package.json` の -`openclaw` ブロックに置かれます。 +一部のランタイム前Pluginメタデータは、`openclaw.plugin.json`ではなく、意図的に`package.json`の`openclaw`ブロック配下に置かれています。 重要な例: -| フィールド | 意味 | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | ネイティブ Plugin エントリーポイントを宣言します。 | -| `openclaw.setupEntry` | オンボーディングおよび遅延チャネル起動時に使用される、軽量なセットアップ専用エントリーポイント。 | -| `openclaw.channel` | ラベル、ドキュメントパス、エイリアス、選択時の文言などの軽量なチャネル catalog メタデータ。 | -| `openclaw.channel.configuredState` | 完全なチャネルランタイムを読み込まずに「env のみのセットアップがすでに存在するか?」に答えられる、軽量な configured-state チェッカーメタデータ。 | -| `openclaw.channel.persistedAuthState` | 完全なチャネルランタイムを読み込まずに「すでに何かにサインインしているか?」に答えられる、軽量な persisted-auth チェッカーメタデータ。 | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | バンドルされた Plugin および外部公開された Plugin のインストール/更新ヒント。 | -| `openclaw.install.defaultChoice` | 複数のインストール元が利用可能な場合の優先インストールパス。 | -| `openclaw.install.minHostVersion` | `>=2026.3.22` のような semver 下限を使う、サポートされる最小 OpenClaw ホストバージョン。 | -| `openclaw.install.allowInvalidConfigRecovery` | 設定が無効な場合に、限定的なバンドル Plugin の再インストール回復パスを許可します。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 起動中に完全なチャネル Plugin の前に、セットアップ専用チャネルサーフェスを読み込めるようにします。 | +| フィールド | 意味 | +| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | ネイティブPluginエントリーポイントを宣言します。 | +| `openclaw.setupEntry` | オンボーディングおよび遅延チャネル起動時に使われる、軽量なセットアップ専用エントリーポイントです。 | +| `openclaw.channel` | ラベル、ドキュメントパス、エイリアス、選択コピーのような低コストなchannelカタログメタデータです。 | +| `openclaw.channel.configuredState` | フルchannelランタイムを読み込まずに「環境変数のみのセットアップがすでに存在するか」を判定できる、軽量なconfigured-stateチェッカーメタデータです。 | +| `openclaw.channel.persistedAuthState` | フルchannelランタイムを読み込まずに「すでに何かサインイン済みか」を判定できる、軽量な永続化認証チェッカーメタデータです。 | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | バンドル済みPluginおよび外部公開Plugin向けのインストール/更新ヒントです。 | +| `openclaw.install.defaultChoice` | 複数のインストール元が利用可能な場合の優先インストールパスです。 | +| `openclaw.install.minHostVersion` | `>=2026.3.22`のようなsemver下限で表される、サポートされる最小OpenClawホストバージョンです。 | +| `openclaw.install.allowInvalidConfigRecovery` | 設定が無効な場合に、限定されたバンドル済みPlugin再インストール回復パスを許可します。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 起動時に、フルchannel Pluginより先にセットアップ専用channelサーフェスを読み込めるようにします。 | -`openclaw.install.minHostVersion` は、インストール時およびマニフェスト -レジストリ読み込み時に適用されます。無効な値は拒否され、有効だがより新しい値は -古いホストではその plugin をスキップします。 +`openclaw.install.minHostVersion`は、インストール時およびマニフェストレジストリ読み込み時に適用されます。無効な値は拒否されます。有効ではあるがより新しい値の場合、古いホストではそのPluginはスキップされます。 -`openclaw.install.allowInvalidConfigRecovery` は意図的に限定的です。 -任意の壊れた設定をインストール可能にするものではありません。現在は、特定の古いバンドル Plugin -アップグレード失敗、たとえばバンドル Plugin パスの欠落や、その同じバンドル Plugin に対する古い -`channels.` エントリなどから、インストールフローが回復できるようにするだけです。 -無関係な設定エラーは引き続きインストールをブロックし、オペレーターを -`openclaw doctor --fix` に誘導します。 +`openclaw.install.allowInvalidConfigRecovery`は意図的に限定的です。任意の壊れた設定をインストール可能にするものではありません。現在は、特定の古いバンドル済みPluginアップグレード失敗、たとえば欠落したバンドル済みPluginパスや、同じバンドル済みPluginに対する古い`channels.`エントリなどから、インストールフローが回復することだけを許可します。無関係な設定エラーは引き続きインストールをブロックし、オペレーターを`openclaw doctor --fix`へ案内します。 -`openclaw.channel.persistedAuthState` は、小さなチェッカーモジュール用のパッケージメタデータです。 +`openclaw.channel.persistedAuthState`は、小さなチェッカーモジュールのためのパッケージメタデータです。 ```json { @@ -482,9 +484,9 @@ OpenClaw は次の優先順位を適用します。 } ``` -これは、セットアップ、doctor、または configured-state フローが、完全なチャネル Plugin を読み込む前に、低コストな yes/no の認証プローブを必要とする場合に使用します。対象の export は、永続化された状態のみを読む小さな関数にしてください。完全なチャネルランタイム barrel を経由させないでください。 +セットアップ、doctor、またはconfigured-stateフローが、フルchannel Plugin読み込み前に低コストなyes/no認証プローブを必要とする場合に使用します。対象のエクスポートは、永続化された状態のみを読み取る小さな関数であるべきです。フルchannelランタイムbarrelを経由させないでください。 -`openclaw.channel.configuredState` も、低コストな env のみの configured チェック用に同じ形式に従います。 +`openclaw.channel.configuredState`も、低コストな環境変数のみのconfiguredチェック向けに同じ形を取ります。 ```json { @@ -500,62 +502,41 @@ OpenClaw は次の優先順位を適用します。 } ``` -チャネルが env やその他の小さな非ランタイム入力から configured-state に答えられる場合に使用します。チェックに完全な設定解決または実際のチャネルランタイムが必要な場合は、そのロジックを代わりに plugin `config.hasConfiguredState` hook に置いてください。 +channelが、環境変数またはその他の小さな非ランタイム入力からconfigured-stateを判定できる場合に使用します。チェックに完全な設定解決または実際のchannelランタイムが必要な場合は、代わりにそのロジックをPluginの`config.hasConfiguredState`フックに置いてください。 -## JSON Schema の要件 +## JSON Schema要件 -- **すべての Plugin は JSON Schema を必ず含める必要があります**。設定を受け付けない場合でも同様です。 -- 空のスキーマでも問題ありません（例: `{ "type": "object", "additionalProperties": false }`）。 +- **すべてのPluginはJSON Schemaを必ず含める必要があります**。設定を受け付けない場合でも同様です。 +- 空のスキーマでも許可されます（例: `{ "type": "object", "additionalProperties": false }`）。 - スキーマはランタイム時ではなく、設定の読み取り/書き込み時に検証されます。 -## 検証の動作 +## 検証動作 -- 不明な `channels.*` キーは、チャネル ID が - plugin マニフェストで宣言されていない限り、**エラー**です。 -- `plugins.entries.`、`plugins.allow`、`plugins.deny`、および `plugins.slots.*` - は、**検出可能な** plugin ID を参照する必要があります。不明な ID は **エラー**です。 -- plugin がインストールされていても、マニフェストまたはスキーマが壊れている、あるいは存在しない場合、 - 検証は失敗し、Doctor は plugin エラーを報告します。 -- plugin 設定が存在していても、その plugin が**無効**の場合、設定は保持され、 - Doctor + ログに **警告** が表示されます。 +- 不明な`channels.*`キーは、channel idがPluginマニフェストで宣言されていない限り、**エラー**です。 +- `plugins.entries.`、`plugins.allow`、`plugins.deny`、および`plugins.slots.*`は、**検出可能な**Plugin idを参照していなければなりません。不明なidは**エラー**です。 +- Pluginがインストールされていても、マニフェストまたはスキーマが壊れているか存在しない場合、検証は失敗し、DoctorがそのPluginエラーを報告します。 +- Plugin設定が存在しても、Pluginが**無効**な場合、設定は保持され、Doctor + ログに**警告**が表示されます。 -完全な `plugins.*` スキーマについては、[設定リファレンス](/ja-JP/gateway/configuration) を参照してください。 +完全な`plugins.*`スキーマについては、[Configuration reference](/ja-JP/gateway/configuration)を参照してください。 -## 注意 +## 注記 -- マニフェストは、ローカルファイルシステムからの読み込みを含め、**ネイティブ OpenClaw Plugin では必須**です。 -- ランタイムは引き続き plugin モジュールを別途読み込みます。マニフェストは - 検出 + 検証専用です。 -- ネイティブマニフェストは JSON5 で解析されるため、最終的な値がオブジェクトである限り、 - コメント、末尾のカンマ、クォートなしキーを使用できます。 -- マニフェストローダーが読み取るのは、文書化されたマニフェストフィールドだけです。ここに - カスタムの最上位キーを追加するのは避けてください。 -- `providerAuthEnvVars` は、認証プローブ、env マーカー検証、および同様の provider 認証サーフェス向けの - 低コストなメタデータパスです。これらは env 名を確認するだけのために plugin - ランタイムを起動すべきではありません。 -- `providerAuthAliases` は、コアにその関係をハードコードすることなく、provider バリアントが別の provider の認証 - env vars、認証プロファイル、設定ベースの認証、および API キーのオンボーディング選択肢を - 再利用できるようにします。 -- `channelEnvVars` は、shell-env フォールバック、セットアップ - プロンプト、および同様のチャネルサーフェス向けの低コストなメタデータパスです。これらは env 名を確認するだけのために plugin - ランタイムを起動すべきではありません。 -- `providerAuthChoices` は、認証選択肢ピッカー、 - `--auth-choice` 解決、優先 provider マッピング、および単純なオンボーディング - CLI フラグ登録を、provider ランタイム読み込み前に行うための低コストなメタデータパスです。provider コードを必要とするランタイム - ウィザードのメタデータについては、 - [Provider runtime hooks](/ja-JP/plugins/architecture#provider-runtime-hooks) を参照してください。 -- 排他的な plugin 種別は `plugins.slots.*` を通じて選択されます。 - - `kind: "memory"` は `plugins.slots.memory` で選択されます。 - - `kind: "context-engine"` は `plugins.slots.contextEngine` - で選択されます（デフォルト: 組み込みの `legacy`）。 -- `channels`、`providers`、`cliBackends`、および `skills` は、 - plugin がそれらを必要としない場合は省略できます。 -- plugin がネイティブモジュールに依存する場合は、ビルド手順と、 - 必要なパッケージマネージャーの許可リスト要件（たとえば pnpm の `allow-build-scripts` - や `pnpm rebuild `）を文書化してください。 +- マニフェストは、ローカルファイルシステムからの読み込みを含め、**ネイティブなOpenClaw Pluginでは必須**です。 +- ランタイムは引き続きPluginモジュールを別途読み込みます。マニフェストは検出と検証専用です。 +- ネイティブマニフェストはJSON5で解析されるため、最終的な値が引き続きオブジェクトである限り、コメント、末尾カンマ、クォートなしキーが受け入れられます。 +- マニフェストローダーが読み取るのは文書化されたマニフェストフィールドのみです。ここにカスタムのトップレベルキーを追加するのは避けてください。 +- `providerAuthEnvVars`は、認証プローブ、環境変数マーカー検証、および環境変数名を確認するためだけにPluginランタイムを起動すべきでない類似のprovider認証サーフェス向けの、低コストなメタデータパスです。 +- `providerAuthAliases`により、providerバリアントは、その関係をcoreにハードコードすることなく、別のproviderの認証環境変数、認証プロファイル、設定ベースの認証、APIキーのオンボーディング選択肢を再利用できます。 +- `channelEnvVars`は、シェル環境変数フォールバック、セットアッププロンプト、および環境変数名を確認するためだけにPluginランタイムを起動すべきでない類似のchannelサーフェス向けの、低コストなメタデータパスです。 +- `providerAuthChoices`は、認証選択肢ピッカー、`--auth-choice`解決、優先providerマッピング、およびproviderランタイム読み込み前の単純なオンボーディングCLIフラグ登録向けの、低コストなメタデータパスです。providerコードを必要とするランタイムのウィザードメタデータについては、[Provider runtime hooks](/ja-JP/plugins/architecture#provider-runtime-hooks)を参照してください。 +- 排他的なPlugin種別は`plugins.slots.*`を通じて選択されます。 + - `kind: "memory"`は`plugins.slots.memory`で選択されます。 + - `kind: "context-engine"`は`plugins.slots.contextEngine`で選択されます（デフォルト: 組み込みの`legacy`）。 +- `channels`、`providers`、`cliBackends`、`skills`は、Pluginがそれらを必要としない場合は省略できます。 +- Pluginがネイティブモジュールに依存している場合は、ビルド手順と、必要なパッケージマネージャーの許可リスト要件（たとえばpnpmの`allow-build-scripts`、`pnpm rebuild `）を文書化してください。 ## 関連 -- [Building Plugins](/ja-JP/plugins/building-plugins) — Plugin のはじめに +- [Building Plugins](/ja-JP/plugins/building-plugins) — Pluginのはじめに - [Plugin Architecture](/ja-JP/plugins/architecture) — 内部アーキテクチャ -- [SDK Overview](/ja-JP/plugins/sdk-overview) — Plugin SDK リファレンス +- [SDK Overview](/ja-JP/plugins/sdk-overview) — Plugin SDKリファレンス diff --git a/docs/ja-JP/plugins/sdk-channel-plugins.md b/docs/ja-JP/plugins/sdk-channel-plugins.md index e33e933c3..ef0c7d725 100644 --- a/docs/ja-JP/plugins/sdk-channel-plugins.md +++ b/docs/ja-JP/plugins/sdk-channel-plugins.md @@ -1,82 +1,92 @@ --- read_when: - - 新しいメッセージングチャンネルプラグインを構築している場合 - - OpenClawをメッセージングプラットフォームに接続したい場合 - - ChannelPluginアダプターサーフェスを理解する必要がある場合 + - 新しいメッセージングチャネルPluginを構築しています + - OpenClawをメッセージングプラットフォームに接続したいと考えています + - ChannelPluginアダプターの公開インターフェースを理解する必要があります sidebarTitle: Channel Plugins -summary: OpenClaw向けメッセージングチャンネルプラグインを構築するためのステップバイステップガイド -title: チャンネルプラグインの構築 +summary: OpenClaw向けメッセージングチャネルPluginを構築するためのステップバイステップガイド +title: チャネルPluginの構築 x-i18n: - generated_at: "2026-04-11T02:46:50Z" + generated_at: "2026-04-15T04:43:33Z" model: gpt-5.4 provider: openai - source_hash: 8a026e924f9ae8a3ddd46287674443bcfccb0247be504261522b078e1f440aef + source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65 source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# チャンネルプラグインの構築 +# チャネルPluginの構築 -このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャンネルプラグインの構築方法を説明します。最後には、DMセキュリティ、pairing、返信スレッド化、アウトバウンドメッセージングを備えた動作するチャンネルが完成します。 +このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャネルPluginの構築方法を説明します。最後には、DMセキュリティ、ペアリング、返信スレッド化、送信メッセージングを備えた動作するチャネルが完成します。 - まだOpenClawプラグインを一度も構築したことがない場合は、まず基本的なパッケージ構造とmanifest設定について[はじめに](/ja-JP/plugins/building-plugins)を読んでください。 + OpenClaw Pluginをまだ一度も構築したことがない場合は、基本的なパッケージ + 構造とマニフェスト設定について最初に + [はじめに](/ja-JP/plugins/building-plugins)を読んでください。 -## チャンネルプラグインの仕組み +## チャネルPluginの仕組み -チャンネルプラグインには、独自のsend/edit/reactツールは不要です。OpenClawはコア内で1つの共有`message`ツールを維持します。プラグインが担当するのは次の領域です。 +チャネルPluginには独自の送信・編集・リアクション用ツールは不要です。OpenClawはコアで1つの共有`message`ツールを維持します。Pluginが担当するのは次の項目です。 - **設定** — アカウント解決とセットアップウィザード -- **セキュリティ** — DMポリシーとallowlist -- **Pairing** — DM承認フロー -- **セッショングラマー** — プロバイダー固有の会話IDを、ベースチャット、スレッドID、親フォールバックへどう対応付けるか -- **アウトバウンド** — テキスト、メディア、pollをプラットフォームへ送信 +- **セキュリティ** — DMポリシーと許可リスト +- **ペアリング** — DM承認フロー +- **セッショングラマー** — プロバイダー固有の会話idをベースチャット、スレッドid、親フォールバックにどう対応付けるか +- **送信** — テキスト、メディア、投票をプラットフォームに送信すること - **スレッド化** — 返信をどうスレッド化するか -コアは、共有messageツール、プロンプト配線、外側のsession-key形状、汎用的な`:thread:`管理、およびディスパッチを担当します。 +コアは共有messageツール、プロンプト配線、外側のセッションキー形状、汎用的な`:thread:`管理、およびディスパッチを担当します。 -プラットフォームが会話IDの中に追加のscopeを保持する場合、その解析はプラグイン内で`messaging.resolveSessionConversation(...)`を使って維持してください。これは、`rawId`をベース会話ID、任意のスレッドID、明示的な`baseConversationId`、および任意の`parentConversationCandidates`に対応付けるための正式なフックです。`parentConversationCandidates`を返す場合は、最も狭い親から最も広い/ベース会話の順に並べてください。 +チャネルでメディアソースを運ぶmessage-toolパラメータを追加する場合は、それらの +パラメータ名を`describeMessageTool(...).mediaSourceParams`を通じて公開してください。コアはその明示的な一覧をサンドボックスパス正規化と送信メディアアクセスポリシーに使用するため、Plugin側でプロバイダー固有のアバター、添付ファイル、カバー画像パラメータに対して共有コアの特別扱いは不要です。 +可能であれば、`{ "set-profile": ["avatarUrl", "avatarPath"] }`のようなアクションキー付きマップを返してください。そうすることで、無関係なアクションが別アクションのメディア引数を継承しません。意図的に公開されるすべてのアクションで共有するパラメータであれば、フラットな配列でも引き続き使用できます。 -同じ解析をチャンネルレジストリ起動前に必要とする同梱プラグインは、一致する`resolveSessionConversation(...)`エクスポートを持つトップレベルの`session-key-api.ts`ファイルも公開できます。コアは、ランタイムプラグインレジストリがまだ利用できないときにのみ、このbootstrap安全なサーフェスを使用します。 +プラットフォームが会話id内に追加のスコープを格納する場合は、その解析を +`messaging.resolveSessionConversation(...)`でPlugin内に保持してください。これは、`rawId`をベース会話id、任意のスレッドid、明示的な`baseConversationId`、および任意の`parentConversationCandidates`に対応付けるための正規のフックです。 +`parentConversationCandidates`を返す場合は、最も狭い親から最も広い親/ベース会話の順に並べてください。 -`messaging.resolveParentConversationCandidates(...)`は、プラグインが汎用/raw IDの上に親フォールバックだけを必要とする場合の、レガシー互換フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず`resolveSessionConversation(...).parentConversationCandidates`を使い、その正式なフックで省略された場合にのみ`resolveParentConversationCandidates(...)`へフォールバックします。 +チャネルレジストリの起動前に同じ解析が必要な同梱Pluginでは、対応する +`resolveSessionConversation(...)`エクスポートを持つトップレベルの`session-key-api.ts`ファイルも公開できます。コアは、実行時Pluginレジストリがまだ利用できない場合にのみ、このブートストラップ安全な公開インターフェースを使用します。 -## 承認とチャンネルcapability +`messaging.resolveParentConversationCandidates(...)`は、Pluginが汎用/raw idに加えて親フォールバックのみを必要とする場合の、従来の互換性フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず +`resolveSessionConversation(...).parentConversationCandidates`を使用し、その正規フックがそれらを省略した場合にのみ`resolveParentConversationCandidates(...)`へフォールバックします。 -ほとんどのチャンネルプラグインでは、承認専用コードは不要です。 +## 承認とチャネル機能 -- コアは、同一チャット内の`/approve`、共有承認ボタンpayload、および汎用フォールバック配信を担当します。 -- チャンネルに承認固有の動作が必要な場合は、チャンネルプラグイン上の1つの`approvalCapability`オブジェクトを優先してください。 -- `ChannelPlugin.approvals`は削除されました。承認配信/native/render/authの情報は`approvalCapability`に置いてください。 -- `plugin.auth`はlogin/logout専用です。コアはそのオブジェクトから承認authフックをもう読みません。 -- `approvalCapability.authorizeActorAction`と`approvalCapability.getActionAvailabilityState`が正式な承認authの接合面です。 -- 同一チャット内の承認auth可用性には`approvalCapability.getActionAvailabilityState`を使用してください。 -- チャンネルがnative exec承認を公開する場合、開始元サーフェス/native client状態が同一チャット承認authと異なるときは`approvalCapability.getExecInitiatingSurfaceState`を使用してください。コアはこのexec専用フックを使って`enabled`と`disabled`を区別し、開始元チャンネルがnative exec承認をサポートしているかを判断し、native clientフォールバック案内にそのチャンネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)`は一般的なケースでこれを補完します。 -- 重複するローカル承認プロンプトの非表示や、配信前のtyping indicator送信のようなチャンネル固有のpayloadライフサイクル動作には、`outbound.shouldSuppressLocalPayloadPrompt`または`outbound.beforeDeliverPayload`を使用してください。 -- `approvalCapability.delivery`は、native承認ルーティングまたはフォールバック抑制にのみ使用してください。 -- `approvalCapability.nativeRuntime`は、チャンネル所有のnative承認情報に使用してください。ホットなチャンネルエントリポイントでは、`createLazyChannelApprovalNativeRuntimeAdapter(...)`で遅延化してください。これにより、コアが承認ライフサイクルを組み立てられる一方で、必要に応じてランタイムモジュールをオンデマンドでimportできます。 -- `approvalCapability.render`は、チャンネルが共有レンダラーではなく本当にカスタム承認payloadを必要とする場合にのみ使用してください。 -- チャンネルが無効時の返信で、native exec承認を有効化するために必要な正確な設定ノブを説明したい場合は`approvalCapability.describeExecApprovalSetup`を使用してください。このフックは`{ channel, channelLabel, accountId }`を受け取ります。名前付きアカウントのあるチャンネルは、トップレベルのデフォルトではなく、`channels..accounts..execApprovals.*`のようなアカウントスコープのパスを描画するべきです。 -- チャンネルが既存設定から安定したowner風のDM IDを推測できるなら、承認固有のコアロジックを追加せずに同一チャット内の`/approve`を制限するために、`openclaw/plugin-sdk/approval-runtime`の`createResolvedApproverActionAuthAdapter`を使用してください。 -- チャンネルにnative承認配信が必要な場合、チャンネルコードはターゲット正規化とトランスポート/プレゼンテーション情報に集中させてください。`openclaw/plugin-sdk/approval-runtime`の`createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability`を使用してください。チャンネル固有の情報は、理想的には`createChannelApprovalNativeRuntimeAdapter(...)`または`createLazyChannelApprovalNativeRuntimeAdapter(...)`を通じて`approvalCapability.nativeRuntime`の背後に置いてください。これにより、コアはハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、有効期限、Gatewayサブスクリプション、別経路通知を担当できます。`nativeRuntime`はいくつかのより小さい接合面に分割されています: -- `availability` — アカウントが設定されているか、およびリクエストを処理すべきかどうか -- `presentation` — 共有承認view modelを保留中/解決済み/期限切れのnative payloadまたは最終アクションに対応付ける -- `transport` — ターゲットを準備し、native承認メッセージを送信/更新/削除する -- `interactions` — nativeボタンまたはreaction向けの任意のbind/unbind/clear-actionフック +ほとんどのチャネルPluginでは、承認固有のコードは不要です。 + +- コアは同一チャット内の`/approve`、共有承認ボタンのペイロード、および汎用フォールバック配信を担当します。 +- チャネルで承認固有の動作が必要な場合は、チャネルPlugin上に1つの`approvalCapability`オブジェクトを置くことを推奨します。 +- `ChannelPlugin.approvals`は削除されました。承認の配信/ネイティブ/レンダリング/認証に関する情報は`approvalCapability`に置いてください。 +- `plugin.auth`はlogin/logout専用です。コアはそのオブジェクトから承認認証フックを読み取らなくなりました。 +- `approvalCapability.authorizeActorAction`と`approvalCapability.getActionAvailabilityState`が正規の承認認証インターフェースです。 +- 同一チャット内の承認認証の可用性には`approvalCapability.getActionAvailabilityState`を使用してください。 +- チャネルがネイティブexec承認を公開する場合、開始サーフェス/ネイティブクライアント状態が同一チャット内承認認証と異なるときは、`approvalCapability.getExecInitiatingSurfaceState`を使用してください。コアはこのexec固有のフックを使用して`enabled`と`disabled`を区別し、開始チャネルがネイティブexec承認をサポートしているかを判断し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)`は一般的なケースに対してこれを補います。 +- 重複するローカル承認プロンプトの非表示や、配信前の入力中インジケーター送信のような、チャネル固有のペイロードライフサイクル動作には、`outbound.shouldSuppressLocalPayloadPrompt`または`outbound.beforeDeliverPayload`を使用してください。 +- `approvalCapability.delivery`は、ネイティブ承認ルーティングまたはフォールバック抑制にのみ使用してください。 +- チャネル所有のネイティブ承認情報には`approvalCapability.nativeRuntime`を使用してください。`createLazyChannelApprovalNativeRuntimeAdapter(...)`を使って、ホットなチャネルエントリーポイントではこれを遅延ロードにしてください。これにより、コアは承認ライフサイクルを組み立てつつ、必要時に実行時モジュールをimportできます。 +- 共有レンダラーではなく、チャネルが本当に独自の承認ペイロードを必要とする場合にのみ`approvalCapability.render`を使用してください。 +- チャネルが、無効時パスの返信でネイティブexec承認を有効化するために必要な正確な設定項目を説明したい場合は、`approvalCapability.describeExecApprovalSetup`を使用してください。このフックは`{ channel, channelLabel, accountId }`を受け取ります。名前付きアカウントのチャネルでは、トップレベルのデフォルトではなく、`channels..accounts..execApprovals.*`のようなアカウントスコープのパスを表示してください。 +- 既存設定から安定した所有者相当のDMアイデンティティを推測できるチャネルでは、承認固有のコアロジックを追加せずに同一チャット内の`/approve`を制限するため、`openclaw/plugin-sdk/approval-runtime`の`createResolvedApproverActionAuthAdapter`を使用してください。 +- チャネルにネイティブ承認配信が必要な場合、チャネルコードはターゲット正規化とトランスポート/プレゼンテーション情報に集中させてください。`openclaw/plugin-sdk/approval-runtime`の`createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability`を使用してください。チャネル固有の情報は`approvalCapability.nativeRuntime`の背後に置き、理想的には`createChannelApprovalNativeRuntimeAdapter(...)`または`createLazyChannelApprovalNativeRuntimeAdapter(...)`を通してください。これにより、コアはハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、有効期限、Gatewayサブスクリプション、別経路通知を担当できます。`nativeRuntime`はいくつかの小さなインターフェースに分割されています。 +- `availability` — アカウントが設定済みか、およびリクエストを処理すべきかどうか +- `presentation` — 共有承認ビューモデルを、保留/解決済み/期限切れのネイティブペイロードまたは最終アクションにマッピングする +- `transport` — ターゲットを準備し、ネイティブ承認メッセージを送信/更新/削除する +- `interactions` — ネイティブボタンやリアクション向けの任意のbind/unbind/clear-actionフック - `observe` — 任意の配信診断フック -- チャンネルがclient、token、Bolt app、webhook receiverのようなランタイム所有オブジェクトを必要とする場合は、`openclaw/plugin-sdk/channel-runtime-context`を通じて登録してください。汎用runtime-contextレジストリにより、コアは承認固有のラッパー接着コードを追加せずに、チャンネル起動状態からcapability駆動ハンドラーをbootstrapできます。 -- capability駆動の接合面だけではまだ表現力が足りない場合にのみ、より低レベルな`createChannelApprovalHandler`または`createChannelNativeApprovalRuntime`を使用してください。 -- native承認チャンネルは、`accountId`と`approvalKind`の両方をそれらのヘルパー経由でルーティングする必要があります。`accountId`はマルチアカウント承認ポリシーを正しいボットアカウントにスコープし、`approvalKind`はコアにハードコードされた分岐なしで、execとプラグイン承認の動作をチャンネルから利用可能に保ちます。 -- コアは現在、承認の再ルーティング通知も担当します。チャンネルプラグインは、`createChannelNativeApprovalRuntime`から独自の「承認はDM/別チャンネルへ送られました」フォローアップメッセージを送るべきではありません。代わりに、共有承認capabilityヘルパーを通じて正確なorigin + approver-DMルーティングを公開し、開始元チャットへ通知を返す前にコアが実際の配信を集約できるようにしてください。 -- 配信された承認IDの種類をエンドツーエンドで維持してください。native clientは、チャンネルローカル状態からexecかプラグインかの承認ルーティングを推測したり書き換えたりしてはいけません。 -- 異なる承認種別は、意図的に異なるnativeサーフェスを公開できます。 +- チャネルにclient、token、Boltアプリ、Webhookレシーバーのような実行時所有オブジェクトが必要な場合は、`openclaw/plugin-sdk/channel-runtime-context`を通じて登録してください。汎用runtime-contextレジストリにより、コアは承認固有のラッパーを追加せずに、チャネル起動状態から機能駆動ハンドラーをブートストラップできます。 +- capability駆動インターフェースでまだ十分に表現できない場合にのみ、より低レベルの`createChannelApprovalHandler`または`createChannelNativeApprovalRuntime`を使用してください。 +- ネイティブ承認チャネルでは、これらのヘルパーを通じて`accountId`と`approvalKind`の両方をルーティングする必要があります。`accountId`はマルチアカウント承認ポリシーを正しいボットアカウントにスコープし、`approvalKind`はコアでハードコードされた分岐なしにexecとplugin承認の動作をチャネルで利用可能にします。 +- コアは承認の再ルーティング通知も担当するようになりました。チャネルPluginは、`createChannelNativeApprovalRuntime`から独自の「承認はDM/別チャネルに送られました」という追跡メッセージを送信すべきではありません。代わりに、共有承認capabilityヘルパーを通じて正確なoriginとapprover-DMルーティングを公開し、開始チャットに通知を投稿する前にコアが実際の配信を集約するようにしてください。 +- 配信された承認idの種類をエンドツーエンドで保持してください。ネイティブクライアントは、チャネルローカルの状態からexecとplugin承認のルーティングを推測または書き換えるべきではありません。 +- 異なる承認種類で、意図的に異なるネイティブサーフェスを公開してもかまいません。 現在の同梱例: - - Slackは、exec IDとプラグインIDの両方に対してnative承認ルーティングを利用可能なままにします。 - - Matrixは、exec承認とプラグイン承認で同じnative DM/チャンネルルーティングとreaction UXを維持しつつ、承認種別ごとにauthを異ならせることができます。 -- `createApproverRestrictedNativeApprovalAdapter`は互換ラッパーとして依然存在しますが、新しいコードではcapability builderを優先し、プラグイン上に`approvalCapability`を公開してください。 + - Slackは、exec idとplugin idの両方でネイティブ承認ルーティングを利用可能にしています。 + - Matrixは、exec承認とplugin承認で同じネイティブDM/チャネルルーティングとリアクションUXを維持しつつ、承認種類による認証の違いも許可しています。 +- `createApproverRestrictedNativeApprovalAdapter`は互換性ラッパーとしてまだ存在しますが、新しいコードではcapability builderを推奨し、Plugin上で`approvalCapability`を公開してください。 -ホットなチャンネルエントリポイントでは、そのファミリーの一部だけが必要な場合、より狭いランタイムsubpathを優先してください。 +ホットなチャネルエントリーポイントでは、そのファミリーのうち1つの部分だけが必要な場合、より狭いruntimeサブパスを優先してください。 - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -88,77 +98,91 @@ x-i18n: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -同様に、より広い包括サーフェスが不要な場合は、`openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/reply-runtime`、`openclaw/plugin-sdk/reply-dispatch-runtime`、`openclaw/plugin-sdk/reply-reference`、`openclaw/plugin-sdk/reply-chunking`を優先してください。 +同様に、より広い包括的な公開インターフェースが不要な場合は、 +`openclaw/plugin-sdk/setup-runtime`、 +`openclaw/plugin-sdk/setup-adapter-runtime`、 +`openclaw/plugin-sdk/reply-runtime`、 +`openclaw/plugin-sdk/reply-dispatch-runtime`、 +`openclaw/plugin-sdk/reply-reference`、および +`openclaw/plugin-sdk/reply-chunking` +を優先してください。 -セットアップについては特に: +セットアップに関しては特に次のとおりです。 -- `openclaw/plugin-sdk/setup-runtime`は、ランタイム安全なセットアップヘルパーを扱います: - import安全なセットアップpatchアダプター（`createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`）、lookup-note出力、`promptResolvedAllowFrom`、`splitSetupEntries`、および委譲セットアップproxy builder -- `openclaw/plugin-sdk/setup-adapter-runtime`は、`createEnvPatchedAccountSetupAdapter`向けの狭いenv対応アダプター接合面です -- `openclaw/plugin-sdk/channel-setup`は、optional-installセットアップbuilderといくつかのセットアップ安全プリミティブを扱います: - `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、 +- `openclaw/plugin-sdk/setup-runtime`はruntime-safeなセットアップヘルパーを提供します: + import-safeなセットアップパッチアダプター（`createPatchedAccountSetupAdapter`, + `createEnvPatchedAccountSetupAdapter`, + `createSetupInputPresenceValidator`）、lookup-note出力、 + `promptResolvedAllowFrom`、`splitSetupEntries`、および委譲された + setup-proxy builder +- `openclaw/plugin-sdk/setup-adapter-runtime`は、`createEnvPatchedAccountSetupAdapter`向けの狭いenv-aware adapterインターフェースです +- `openclaw/plugin-sdk/channel-setup`は、オプションインストール用セットアップbuilderと、いくつかのセットアップ安全なプリミティブを提供します: + `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -チャンネルがenv駆動のセットアップやauthをサポートし、ランタイムがロードされる前に汎用の起動/設定フローがそれらのenv名を知る必要がある場合は、プラグインmanifestで`channelEnvVars`として宣言してください。チャンネルランタイムの`envVars`またはローカル定数は、operator向けコピー専用にしてください。 -`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、および`splitSetupEntries` +チャネルがenv駆動のセットアップまたは認証をサポートし、汎用の起動/設定フローでruntimeロード前にそれらのenv名を把握する必要がある場合は、Pluginマニフェストで`channelEnvVars`として宣言してください。チャネルruntimeの`envVars`やローカル定数は、オペレーター向け文言専用にとどめてください。 +`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, +`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, および +`splitSetupEntries` -- `moveSingleAccountChannelSectionToDefaultAccount(...)`のような、より重い共有セットアップ/設定ヘルパーも必要な場合にのみ、より広い`openclaw/plugin-sdk/setup`接合面を使用してください +- より重い共有セットアップ/設定ヘルパー、たとえば + `moveSingleAccountChannelSectionToDefaultAccount(...)` + も必要な場合にのみ、より広い`openclaw/plugin-sdk/setup`インターフェースを使用してください -チャンネルがセットアップサーフェス内で「まずこのプラグインをインストールしてください」と案内するだけでよい場合は、`createOptionalChannelSetupSurface(...)`を優先してください。生成されるadapter/wizardは、設定書き込みと最終化でfail closedし、検証・最終化・docsリンクのコピー全体で同じインストール必須メッセージを再利用します。 +チャネルがセットアップ画面で「まずこのPluginをインストールしてください」と案内したいだけなら、`createOptionalChannelSetupSurface(...)`を優先してください。生成されるadapter/wizardは設定書き込みと最終化でfail closedし、検証、最終化、ドキュメントリンク文言で同じインストール必須メッセージを再利用します。 -その他のホットなチャンネルパスでも、より広いレガシーサーフェスより狭いヘルパーを優先してください。 +そのほかのホットなチャネルパスでも、より広い従来の公開インターフェースより狭いヘルパーを優先してください。 -- `openclaw/plugin-sdk/account-core`、 - `openclaw/plugin-sdk/account-id`、 - `openclaw/plugin-sdk/account-resolution`、および - `openclaw/plugin-sdk/account-helpers`は、マルチアカウント設定と - デフォルトアカウントフォールバック向け -- `openclaw/plugin-sdk/inbound-envelope`と - `openclaw/plugin-sdk/inbound-reply-dispatch`は、インバウンドのルート/envelopeと - record-and-dispatch配線向け -- `openclaw/plugin-sdk/messaging-targets`は、ターゲット解析/照合向け -- `openclaw/plugin-sdk/outbound-media`と - `openclaw/plugin-sdk/outbound-runtime`は、メディア読み込みと - アウトバウンドID/送信delegate向け -- `openclaw/plugin-sdk/thread-bindings-runtime`は、スレッドbindingライフサイクル - とadapter登録向け -- `openclaw/plugin-sdk/agent-media-payload`は、レガシーのagent/media - payloadフィールドレイアウトがまだ必要な場合のみ -- `openclaw/plugin-sdk/telegram-command-config`は、Telegramカスタムコマンド - 正規化、重複/競合検証、およびフォールバック安定なコマンド - 設定契約向け +- `openclaw/plugin-sdk/account-core`, + `openclaw/plugin-sdk/account-id`, + `openclaw/plugin-sdk/account-resolution`, および + `openclaw/plugin-sdk/account-helpers` は、マルチアカウント設定と + デフォルトアカウントへのフォールバック用です +- `openclaw/plugin-sdk/inbound-envelope` および + `openclaw/plugin-sdk/inbound-reply-dispatch` は、受信route/envelopeと + record-and-dispatch配線用です +- `openclaw/plugin-sdk/messaging-targets` はターゲット解析/照合用です +- `openclaw/plugin-sdk/outbound-media` および + `openclaw/plugin-sdk/outbound-runtime` は、メディア読み込みと送信 + identity/send delegate用です +- `openclaw/plugin-sdk/thread-bindings-runtime` は、スレッドbindingライフサイクル + とadapter登録用です +- `openclaw/plugin-sdk/agent-media-payload` は、従来のagent/media + ペイロードフィールド配置がまだ必要な場合にのみ使用してください +- `openclaw/plugin-sdk/telegram-command-config` は、Telegramカスタムコマンドの + 正規化、重複/競合検証、およびフォールバック安定なコマンド設定コントラクト用です -認証専用チャンネルは通常、デフォルトパスで十分です。コアが承認を処理し、プラグインはアウトバウンド/auth capabilityを公開するだけです。Matrix、Slack、Telegram、およびカスタムチャットトランスポートのようなnative承認チャンネルは、独自に承認ライフサイクルを実装するのではなく、共有nativeヘルパーを使用してください。 +認証専用チャネルは通常、デフォルトの経路で十分です。コアが承認を処理し、Pluginは送信/認証capabilityを公開するだけで済みます。Matrix、Slack、Telegram、カスタムチャットトランスポートのようなネイティブ承認チャネルは、独自の承認ライフサイクルを実装するのではなく、共有のネイティブヘルパーを使用してください。 -## インバウンドメンションポリシー +## 受信メンションポリシー -インバウンドメンション処理は、次の2層に分けて維持してください。 +受信メンション処理は、次の2層に分けたままにしてください。 -- プラグイン所有の証拠収集 +- Plugin所有の証拠収集 - 共有ポリシー評価 共有レイヤーには`openclaw/plugin-sdk/channel-inbound`を使用してください。 -プラグインローカルロジックに適しているもの: +Pluginローカルロジックに適しているもの: -- botへの返信検出 -- bot引用の検出 +- botへの返信の検出 +- botを引用したメッセージの検出 - スレッド参加チェック -- service/systemメッセージの除外 -- bot参加を証明するために必要なプラットフォームネイティブキャッシュ +- サービス/システムメッセージの除外 +- botの参加を証明するために必要なプラットフォームネイティブキャッシュ 共有ヘルパーに適しているもの: - `requireMention` - 明示的メンション結果 -- 暗黙的メンションallowlist +- 暗黙的メンション許可リスト - コマンドバイパス - 最終的なスキップ判定 推奨フロー: -1. ローカルなメンション事実を計算します。 -2. その事実を`resolveInboundMentionDecision({ facts, policy })`に渡します。 -3. インバウンドゲートで`decision.effectiveWasMentioned`、`decision.shouldBypassMention`、`decision.shouldSkip`を使用します。 +1. ローカルのメンション情報を計算します。 +2. その情報を`resolveInboundMentionDecision({ facts, policy })`に渡します。 +3. 受信ゲートで`decision.effectiveWasMentioned`、`decision.shouldBypassMention`、`decision.shouldSkip`を使用します。 ```typescript import { @@ -197,7 +221,7 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions`は、すでにランタイム注入に依存している同梱チャンネルプラグイン向けに、同じ共有メンションヘルパーを公開します。 +`api.runtime.channel.mentions`は、すでにruntime injectionに依存している同梱チャネルPlugin向けに、同じ共有メンションヘルパーを公開します。 - `buildMentionRegexes` - `matchesMentionPatterns` @@ -205,14 +229,18 @@ if (decision.shouldSkip) return; - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -古い`resolveMentionGating*`ヘルパーは、`openclaw/plugin-sdk/channel-inbound`上に互換エクスポートとしてのみ残っています。新しいコードでは`resolveInboundMentionDecision({ facts, policy })`を使用してください。 +古い`resolveMentionGating*`ヘルパーは、 +`openclaw/plugin-sdk/channel-inbound`上に互換性エクスポートとしてのみ残されています。新しいコードでは +`resolveInboundMentionDecision({ facts, policy })`を使用してください。 ## ウォークスルー - - 標準的なプラグインファイルを作成します。`package.json`内の`channel`フィールドが、これをチャンネルプラグインにします。完全なパッケージメタデータサーフェスについては、[Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel)を参照してください。 + + 標準的なPluginファイルを作成します。`package.json`の`channel`フィールドが、 + これをチャネルPluginにします。完全なパッケージメタデータの公開インターフェースについては、 + [Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel)を参照してください。 ```json package.json @@ -261,8 +289,9 @@ if (decision.shouldSkip) return; - - `ChannelPlugin`インターフェースには、多くの省略可能なアダプターサーフェスがあります。最小構成の`id`と`setup`から始め、必要に応じてアダプターを追加してください。 + + `ChannelPlugin`インターフェースには、多くの任意のアダプター公開インターフェースがあります。まずは + 最小構成である`id`と`setup`から始め、必要に応じてアダプターを追加してください。 `src/channel.ts`を作成します: @@ -272,7 +301,7 @@ if (decision.shouldSkip) return; createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // あなたのプラットフォームAPIクライアント + import { acmeChatApi } from "./client.js"; // your platform API client type ResolvedAccount = { accountId: string | null; @@ -313,7 +342,7 @@ if (decision.shouldSkip) return; }, }), - // DMセキュリティ: botにメッセージを送れる相手 + // DM security: who can message the bot security: { dm: { channelKey: "acme-chat", @@ -323,21 +352,21 @@ if (decision.shouldSkip) return; }, }, - // Pairing: 新しいDM連絡先向け承認フロー + // Pairing: approval flow for new DM contacts pairing: { text: { idLabel: "Acme Chat username", - message: "本人確認のため、このコードを送信してください:", + message: "Send this code to verify your identity:", notify: async ({ target, code }) => { await acmeChatApi.sendDm(target, `Pairing code: ${code}`); }, }, }, - // スレッド化: 返信の配信方法 + // Threading: how replies are delivered threading: { topLevelReplyToMode: "reply" }, - // アウトバウンド: プラットフォームへメッセージを送信 + // Outbound: send messages to the platform outbound: { attachedResults: { sendText: async (params) => { @@ -357,22 +386,24 @@ if (decision.shouldSkip) return; }); ``` - - 低レベルのアダプターインターフェースを手動で実装する代わりに、宣言的なオプションを渡すと、builderがそれらを組み合わせます。 + + 低レベルのアダプターインターフェースを手動で実装する代わりに、 + 宣言的なオプションを渡すと、builderがそれらを組み合わせます。 - | オプション | 配線されるもの | + | Option | 配線されるもの | | --- | --- | | `security.dm` | 設定フィールドからのスコープ付きDMセキュリティリゾルバー | - | `pairing.text` | コード交換付きのテキストベースDM pairingフロー | + | `pairing.text` | コード交換を伴うテキストベースのDMペアリングフロー | | `threading` | reply-to-modeリゾルバー（固定、アカウントスコープ、またはカスタム） | - | `outbound.attachedResults` | 結果メタデータ（メッセージID）を返す送信関数 | + | `outbound.attachedResults` | 結果メタデータ（message ID）を返す送信関数 | - 完全に制御したい場合は、宣言的オプションの代わりに生のアダプターオブジェクトを渡すこともできます。 + 完全な制御が必要な場合は、宣言的オプションの代わりに + 生のアダプターオブジェクトを渡すこともできます。 - + `index.ts`を作成します: ```typescript index.ts @@ -408,13 +439,19 @@ if (decision.shouldSkip) return; }); ``` - チャンネル所有のCLI descriptorは`registerCliMetadata(...)`に置いてください。これにより、OpenClawは完全なチャンネルランタイムを有効化せずにルートヘルプへそれらを表示でき、通常の完全ロードでも実際のコマンド登録向けに同じdescriptorを取得できます。`registerFull(...)`はランタイム専用の処理に維持してください。 - `registerFull(...)`がGateway RPCメソッドを登録する場合は、プラグイン固有の接頭辞を使用してください。コア管理者名前空間（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は予約済みで、常に`operator.admin`に解決されます。 - `defineChannelPluginEntry`は、登録モードの分割を自動で処理します。すべてのオプションについては[Entry Points](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry)を参照してください。 + チャネル所有のCLI descriptorは`registerCliMetadata(...)`に置いてください。これにより、OpenClawは完全なチャネルruntimeを有効化せずに + ルートヘルプでそれらを表示でき、通常の完全ロードでも実際のコマンド登録のために + 同じdescriptorを取得できます。`registerFull(...)`はruntime専用の処理に残してください。 + `registerFull(...)`がGateway RPCメソッドを登録する場合は、 + Plugin固有のprefixを使用してください。コア管理namespace（`config.*`、 + `exec.approvals.*`, `wizard.*`, `update.*`）は予約されたままで、 + 常に`operator.admin`に解決されます。 + `defineChannelPluginEntry`は登録モードの分岐を自動的に処理します。すべての + オプションについては[Entry Points](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry)を参照してください。 - + オンボーディング中の軽量ロード用に`setup-entry.ts`を作成します: ```typescript setup-entry.ts @@ -424,24 +461,28 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClawは、チャンネルが無効または未設定のとき、完全なエントリの代わりにこれをロードします。これにより、セットアップフロー中に重いランタイムコードを引き込まずに済みます。詳細は[Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry)を参照してください。 + OpenClawは、チャネルが無効または未設定のとき、完全なentryの代わりにこれをロードします。 + これにより、セットアップフロー中に重いruntimeコードを読み込まずに済みます。 + 詳細は[Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry)を参照してください。 - - プラグインは、プラットフォームからメッセージを受信し、それをOpenClawへ転送する必要があります。一般的なパターンは、リクエストを検証し、チャンネルのインバウンドハンドラーを通じてディスパッチするWebhookです。 + + Pluginはプラットフォームからメッセージを受信し、それを + OpenClawに転送する必要があります。典型的なパターンは、リクエストを検証し、 + チャネルの受信ハンドラーを通してディスパッチするWebhookです。 ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // プラグイン管理認証（署名検証は自分で行う） + auth: "plugin", // plugin-managed auth (verify signatures yourself) handler: async (req, res) => { const event = parseWebhookPayload(req); - // あなたのインバウンドハンドラーがメッセージをOpenClawへディスパッチします。 - // 正確な配線はプラットフォームSDKに依存します — - // 実例は、同梱のMicrosoft TeamsまたはGoogle Chatプラグインパッケージを参照してください。 + // Your inbound handler dispatches the message to OpenClaw. + // The exact wiring depends on your platform SDK — + // see a real example in the bundled Microsoft Teams or Google Chat plugin package. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -453,21 +494,24 @@ if (decision.shouldSkip) return; ``` - インバウンドメッセージ処理はチャンネル固有です。各チャンネルプラグインが独自のインバウンドパイプラインを所有します。実際のパターンについては、同梱チャンネルプラグイン（たとえばMicrosoft TeamsまたはGoogle Chatプラグインパッケージ）を確認してください。 + 受信メッセージ処理はチャネル固有です。各チャネルPluginは + 独自の受信パイプラインを所有します。実際のパターンについては、 + 同梱チャネルPlugin + （たとえばMicrosoft TeamsまたはGoogle ChatのPluginパッケージ）を参照してください。 -`src/channel.test.ts`に同居テストを書きます: +`src/channel.test.ts`に同じ場所のテストを書きます: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; import { acmeChatPlugin } from "./channel.js"; describe("acme-chat plugin", () => { - it("設定からアカウントを解決する", () => { + it("resolves account from config", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -477,7 +521,7 @@ if (decision.shouldSkip) return; expect(account.token).toBe("test-token"); }); - it("secretを実体化せずにアカウントを検査する", () => { + it("inspects account without materializing secrets", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -486,7 +530,7 @@ if (decision.shouldSkip) return; expect(result.tokenStatus).toBe("available"); }); - it("設定不足を報告する", () => { + it("reports missing config", () => { const cfg = { channels: {} } as any; const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined); expect(result.configured).toBe(false); @@ -505,19 +549,19 @@ if (decision.shouldSkip) return; ## ファイル構成 -```text +``` /acme-chat/ ├── package.json # openclaw.channelメタデータ -├── openclaw.plugin.json # 設定スキーマを含むmanifest +├── openclaw.plugin.json # 設定スキーマを含むマニフェスト ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # 公開エクスポート（任意） -├── runtime-api.ts # 内部ランタイムエクスポート（任意） +├── runtime-api.ts # 内部runtimeエクスポート（任意） └── src/ ├── channel.ts # createChatChannelPlugin経由のChannelPlugin ├── channel.test.ts # テスト ├── client.ts # プラットフォームAPIクライアント - └── runtime.ts # ランタイムストア（必要な場合） + └── runtime.ts # runtimeストア（必要な場合） ``` ## 高度なトピック @@ -527,23 +571,27 @@ if (decision.shouldSkip) return; 固定、アカウントスコープ、またはカスタムの返信モード - describeMessageToolとアクションディスカバリー + describeMessageToolとアクション検出 - inferTargetChatType、looksLikeId、resolveTarget + inferTargetChatType, looksLikeId, resolveTarget - + api.runtime経由のTTS、STT、メディア、subagent -一部の同梱ヘルパー接合面は、同梱プラグインの保守と互換性のために引き続き存在します。これらは新しいチャンネルプラグイン向けの推奨パターンではありません。その同梱プラグインファミリーを直接保守しているのでない限り、共通SDKサーフェスの汎用channel/setup/reply/runtime subpathを優先してください。 +一部の同梱ヘルパーインターフェースは、同梱Pluginのメンテナンスと +互換性のためにまだ存在します。これらは新しいチャネルPluginに推奨される +パターンではありません。その同梱Pluginファミリーを直接メンテナンスしている場合を除き、 +共通SDK公開インターフェースの汎用channel/setup/reply/runtimeサブパスを +優先してください。 ## 次のステップ -- [プロバイダープラグイン](/ja-JP/plugins/sdk-provider-plugins) — プラグインがモデルも提供する場合 -- [SDK概要](/ja-JP/plugins/sdk-overview) — 完全なsubpath importリファレンス -- [SDKテスト](/ja-JP/plugins/sdk-testing) — テストユーティリティと契約テスト -- [プラグインmanifest](/ja-JP/plugins/manifest) — 完全なmanifestスキーマ +- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — Pluginがモデルも提供する場合 +- [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全なサブパスimportリファレンス +- [SDK Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティとコントラクトテスト +- [Plugin Manifest](/ja-JP/plugins/manifest) — 完全なマニフェストスキーマ diff --git a/docs/ja-JP/reference/RELEASING.md b/docs/ja-JP/reference/RELEASING.md index 64441cdd9..4e457214e 100644 --- a/docs/ja-JP/reference/RELEASING.md +++ b/docs/ja-JP/reference/RELEASING.md @@ -1,184 +1,188 @@ --- read_when: - - 公開リリースチャネルの定義を探す - - バージョン命名とリリース頻度を探す + - 公開リリースチャネルの定義を探しています + - バージョン命名とリリース頻度を探しています summary: 公開リリースチャネル、バージョン命名、およびリリース頻度 title: リリースポリシー x-i18n: - generated_at: "2026-04-14T04:43:21Z" + generated_at: "2026-04-15T04:43:33Z" model: gpt-5.4 provider: openai - source_hash: 3eaf9f1786b8c9fd4f5a9c657b623cb69d1a485958e1a9b8f108511839b63587 + source_hash: 88724307269ab783a9fbf8a0540fea198d8a3add68457f4e64d5707114fa518c source_path: reference/RELEASING.md workflow: 15 --- # リリースポリシー -OpenClaw には 3 つの公開リリースレーンがあります。 +OpenClaw には3つの公開リリースレーンがあります。 -- stable: タグ付きリリースで、デフォルトでは npm の `beta` に公開され、明示的に要求された場合は npm の `latest` に公開されます -- beta: npm の `beta` に公開されるプレリリースタグ +- stable: デフォルトでは npm `beta` に公開されるタグ付きリリース、明示的に要求された場合は npm `latest` に公開 +- beta: npm `beta` に公開されるプレリリースタグ - dev: `main` の移動する先頭 ## バージョン命名 -- stable リリースのバージョン: `YYYY.M.D` +- stable リリースバージョン: `YYYY.M.D` - Git タグ: `vYYYY.M.D` -- stable 修正リリースのバージョン: `YYYY.M.D-N` +- stable 修正版リリースバージョン: `YYYY.M.D-N` - Git タグ: `vYYYY.M.D-N` -- beta プレリリースのバージョン: `YYYY.M.D-beta.N` +- beta プレリリースバージョン: `YYYY.M.D-beta.N` - Git タグ: `vYYYY.M.D-beta.N` -- 月や日はゼロ埋めしないでください -- `latest` は現在昇格済みの stable npm リリースを意味します -- `beta` は現在の beta インストール対象を意味します -- stable および stable 修正リリースはデフォルトで npm の `beta` に公開されます。リリース運用者は明示的に `latest` を対象にすることも、検証済みの beta ビルドを後で昇格させることもできます -- すべての OpenClaw リリースでは、npm パッケージと macOS アプリが一緒に出荷されます +- 月や日はゼロ埋めしない +- `latest` は現在昇格済みの stable npm リリースを意味する +- `beta` は現在の beta インストール対象を意味する +- stable および stable 修正版リリースはデフォルトで npm `beta` に公開される。リリースオペレーターは明示的に `latest` を指定することも、検証済みの beta ビルドを後で昇格させることもできる +- すべての OpenClaw リリースは npm パッケージと macOS アプリを同時に出荷する ## リリース頻度 -- リリースは beta-first で進みます -- stable は最新の beta が検証された後にのみ続きます -- 詳細なリリース手順、承認、認証情報、復旧メモは - maintainer 限定です +- リリースはまず beta として進む +- stable は最新の beta が検証された後にのみ続く +- 詳細なリリース手順、承認、認証情報、および復旧メモは + maintainer 専用 ## リリース事前確認 -- pack - 検証ステップで期待される `dist/*` のリリース成果物と Control UI バンドルが存在するように、`pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行してください -- すべてのタグ付きリリースの前に `pnpm release:check` を実行してください -- リリースチェックは現在、別個の手動ワークフローで実行されます: +- pack 検証ステップに必要な + `dist/*` リリース成果物と Control UI バンドルが存在するよう、 + `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行する +- すべてのタグ付きリリースの前に `pnpm release:check` を実行する +- リリースチェックは現在、別の手動ワークフローで実行される: `OpenClaw Release Checks` -- この分離は意図的なものです。実際の npm リリース経路を短く、 - 決定的で、成果物重視のものに保ちながら、低速なライブチェックは - 独自のレーンに分離し、公開を停滞またはブロックしないようにします -- リリースチェックは `main` のワークフロー ref からディスパッチする必要があります。これにより、 - ワークフローロジックとシークレットが正規のものに保たれます +- クロス OS のインストールおよびアップグレード実行時検証は、プライベートな呼び出し元ワークフロー + `openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml` + からディスパッチされ、再利用可能な公開ワークフロー + `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` + を呼び出す +- この分離は意図的なもの: 実際の npm リリース経路は短く、 + 決定的で、成果物重視のままにし、より遅いライブチェックは独自の + レーンに残して、公開を遅延またはブロックしないようにする +- リリースチェックは `main` ワークフロー ref からディスパッチしなければならず、これにより + ワークフローロジックとシークレットを正準のまま保つ - そのワークフローは、既存のリリースタグまたは現在の完全な - 40 文字の `main` コミット SHA のいずれかを受け付けます -- コミット SHA モードでは、現在の `origin/main` HEAD のみを受け付けます。古いリリースコミットには - リリースタグを使用してください -- `OpenClaw NPM Release` の検証専用事前確認でも、プッシュ済みタグを必要とせずに現在の完全な 40 文字の `main` コミット SHA を受け付けます -- その SHA パスは検証専用であり、実際の公開に昇格することはできません -- SHA モードでは、ワークフローはパッケージメタデータチェックのためにのみ `v` を合成します。実際の公開には依然として実際のリリースタグが必要です -- 両方のワークフローは、実際の公開および昇格経路を GitHub-hosted - ランナー上に維持しつつ、変更を伴わない検証経路ではより大きな - Blacksmith Linux ランナーを使用できます + 40文字の `main` コミット SHA のいずれかを受け付ける +- コミット SHA モードでは、現在の `origin/main` HEAD のみを受け付ける。 + それより古いリリースコミットにはリリースタグを使う +- `OpenClaw NPM Release` の検証専用事前確認でも、プッシュ済みタグを必要とせずに + 現在の完全な 40 文字の `main` コミット SHA を受け付ける +- その SHA 経路は検証専用であり、実際の公開に昇格させることはできない +- SHA モードでは、ワークフローはパッケージメタデータ確認のためにのみ + `v` を合成する。実際の公開には依然として実際のリリースタグが必要 +- 両ワークフローとも、実際の公開および昇格経路は GitHub-hosted + ランナー上に維持し、非破壊の検証経路ではより大きい + Blacksmith Linux ランナーを使用できる - そのワークフローは `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - を、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方のワークフローシークレットを使用して実行します -- npm リリース事前確認は、別個のリリースチェックレーンを待たなくなりました + を `OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方のワークフローシークレットを使って実行する +- npm リリース事前確認は、もはや別レーンのリリースチェックを待たない - 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - （または対応する beta/修正タグ）を実行してください + （または対応する beta/修正版タグ）を実行する - npm 公開後、公開されたレジストリの - インストール経路を新しい一時プレフィックスで検証するために、 + インストール経路を新しい一時プレフィックスで検証するために `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - （または対応する beta/修正バージョン）を実行してください -- maintainer 向けリリース自動化は現在、事前確認してから昇格する方式を使用します: - - 実際の npm 公開は、成功した npm `preflight_run_id` に合格している必要があります - - stable npm リリースのデフォルトは `beta` です - - stable npm 公開は、ワークフロー入力で明示的に `latest` を対象にできます - - `beta` から `latest` への stable npm 昇格は、信頼済みの `OpenClaw NPM Release` ワークフロー上で明示的な手動モードとして引き続き利用できます - - 直接の stable 公開では、すでに公開済みの stable バージョンに `latest` と `beta` の両方を向ける明示的な dist-tag 同期モードも実行できます - - これらの dist-tag モードでも、npm の `dist-tag` 管理は信頼済み公開とは別であるため、`npm-release` 環境内の有効な `NPM_TOKEN` が引き続き必要です - - 公開の `macOS Release` は検証専用です - - 実際の private mac 公開は、成功した private mac の - `preflight_run_id` と `validate_run_id` に合格している必要があります - - 実際の公開経路では、準備済み成果物を再ビルドせずに昇格させます -- `YYYY.M.D-N` のような stable 修正リリースでは、公開後検証ツールは - `YYYY.M.D` から `YYYY.M.D-N` への同じ一時プレフィックスのアップグレード経路も確認するため、 - リリース修正によって古いグローバルインストールが元の stable ペイロードのまま - 気づかれず残ることはありません -- npm リリース事前確認は、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` ペイロードの両方が含まれていない限り fail closed になるため、 - 空のブラウザダッシュボードを再び出荷することはありません -- `pnpm test:install:smoke` は候補アップデート tarball の npm pack `unpackedSize` 予算も適用するため、 - インストーラー E2E で公開経路の前に pack の意図しない肥大化を検出できます + （または対応する beta/修正版バージョン）を実行する +- maintainer のリリース自動化は現在、事前確認してから昇格する方式を使用する: + - 実際の npm 公開は、成功した npm `preflight_run_id` を通過しなければならない + - stable npm リリースはデフォルトで `beta` + - stable npm 公開はワークフロー入力により明示的に `latest` を対象にできる + - トークンベースの npm dist-tag 変更は現在 + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + にあり、セキュリティのためそうなっている。これは `npm dist-tag add` が依然として `NPM_TOKEN` を必要とし、一方で + 公開リポジトリは OIDC のみの公開を維持するため + - 公開 `macOS Release` は検証専用 + - 実際のプライベート mac 公開は、成功したプライベート mac の + `preflight_run_id` と `validate_run_id` を通過しなければならない + - 実際の公開経路は、成果物を再度ビルドする代わりに、準備済み成果物を昇格させる +- `YYYY.M.D-N` のような stable 修正版リリースでは、公開後検証ツールは + 同じ一時プレフィックスでの `YYYY.M.D` から `YYYY.M.D-N` へのアップグレード経路も確認する。 + これにより、リリース修正が古いグローバルインストールを + ベース stable ペイロードのまま静かに残すことを防ぐ +- npm リリース事前確認は、tarball に `dist/control-ui/index.html` と + 空でない `dist/control-ui/assets/` ペイロードの両方が含まれていない限り、 + フェイルクローズする。これにより、空のブラウザダッシュボードを再び出荷しないようにする +- `pnpm test:install:smoke` も候補アップデート tarball の npm pack `unpackedSize` 予算を強制するため、 + インストーラー E2E はリリース公開経路の前に偶発的な pack 膨張を捕捉する - リリース作業で CI 計画、拡張タイミングマニフェスト、または - 拡張テストマトリクスに触れた場合は、承認前に `.github/workflows/ci.yml` から planner が所有する - `checks-node-extensions` ワークフローマトリクス出力を再生成して確認してください。これによりリリースノートが古い CI レイアウトを説明することを防げます -- stable macOS リリースの準備完了には、アップデーター関連の面も含まれます: - - GitHub リリースには、パッケージ化された `.zip`、`.dmg`、および `.dSYM.zip` が含まれている必要があります - - `main` 上の `appcast.xml` は、公開後に新しい stable zip を指している必要があります - - パッケージ化されたアプリは、デバッグ以外の bundle id、空でない Sparkle feed - URL、およびそのリリースバージョンに対する正規の Sparkle build floor 以上の `CFBundleVersion` を維持する必要があります + 拡張テストマトリクスに触れた場合は、承認前に `.github/workflows/ci.yml` の + planner 管理下にある `checks-node-extensions` ワークフローマトリクス出力を再生成して確認する。 + これにより、リリースノートが古い CI レイアウトを記述しないようにする +- stable macOS リリース準備完了には、アップデーター関連のサーフェスも含まれる: + - GitHub リリースには、パッケージ化された `.zip`、`.dmg`、および `.dSYM.zip` + が最終的に含まれていなければならない + - `main` 上の `appcast.xml` は、公開後に新しい stable zip を指していなければならない + - パッケージ化されたアプリは、非デバッグの bundle id、空でない Sparkle feed + URL、およびそのリリースバージョンの正準 Sparkle build floor 以上の + `CFBundleVersion` を維持しなければならない ## NPM ワークフロー入力 -`OpenClaw NPM Release` は、以下の運用者制御入力を受け付けます。 +`OpenClaw NPM Release` は、以下のオペレーター制御入力を受け付ける: -- `tag`: 必須のリリースタグ。例: `v2026.4.2`、`v2026.4.2-1`、または - `v2026.4.2-beta.1`。`preflight_only=true` の場合は、検証専用事前確認のために現在の完全な - 40 文字の `main` コミット SHA も使用できます -- `preflight_only`: 検証/ビルド/パッケージのみの場合は `true`、実際の公開経路の場合は `false` -- `preflight_run_id`: 実際の公開経路では必須です。これにより、ワークフローは成功した事前確認実行から準備済み tarball を再利用します -- `npm_dist_tag`: 公開経路の npm 対象タグ。デフォルトは `beta` -- `promote_beta_to_latest`: 公開をスキップし、すでに公開済みの - stable `beta` ビルドを `latest` に移動する場合は `true` -- `sync_stable_dist_tags`: 公開をスキップし、すでに公開済みの stable バージョンに `latest` と - `beta` の両方を向ける場合は `true` +- `tag`: `v2026.4.2`、`v2026.4.2-1`、または + `v2026.4.2-beta.1` のような必須リリースタグ。`preflight_only=true` の場合、 + 検証専用事前確認のために現在の完全な + 40文字の `main` コミット SHA も指定できる +- `preflight_only`: 検証/ビルド/パッケージのみなら `true`、実際の + 公開経路なら `false` +- `preflight_run_id`: 実際の公開経路で必須。これによりワークフローは成功した事前確認実行から + 準備済み tarball を再利用する +- `npm_dist_tag`: 公開経路用の npm 対象タグ。デフォルトは `beta` -`OpenClaw Release Checks` は、以下の運用者制御入力を受け付けます。 +`OpenClaw Release Checks` は、以下のオペレーター制御入力を受け付ける: -- `ref`: 検証する既存のリリースタグ、または現在の完全な 40 文字の `main` コミット +- `ref`: 既存のリリースタグ、または検証対象の現在の完全な 40 文字の `main` コミット SHA ルール: -- stable および修正タグは `beta` または `latest` のどちらにも公開できます -- beta プレリリースタグは `beta` にのみ公開できます -- 完全なコミット SHA 入力は `preflight_only=true` の場合にのみ許可されます -- リリースチェックのコミット SHA モードでも、現在の `origin/main` HEAD が必要です -- 実際の公開経路では、事前確認時に使用したものと同じ `npm_dist_tag` を使用する必要があります。 - ワークフローは公開を続行する前にそのメタデータを検証します -- 昇格モードでは、stable または修正タグ、`preflight_only=false`、 - 空の `preflight_run_id`、および `npm_dist_tag=beta` を使用する必要があります -- dist-tag 同期モードでは、stable または修正タグ、 - `preflight_only=false`、空の `preflight_run_id`、`npm_dist_tag=latest`、 - および `promote_beta_to_latest=false` を使用する必要があります -- 昇格モードおよび dist-tag 同期モードでも、有効な `NPM_TOKEN` が必要です。これは - `npm dist-tag add` に通常の npm 認証が依然として必要であり、信頼済み公開は - パッケージ公開経路のみをカバーするためです +- stable および修正版タグは `beta` または `latest` のいずれにも公開できる +- beta プレリリースタグは `beta` にのみ公開できる +- 完全なコミット SHA 入力は `preflight_only=true` の場合にのみ許可される +- リリースチェックのコミット SHA モードでも、現在の `origin/main` HEAD が必要 +- 実際の公開経路では、事前確認時に使用したものと同じ `npm_dist_tag` を使用しなければならない。 + ワークフローは公開継続前にそのメタデータを検証する -## stable npm リリース手順 +## stable npm リリースシーケンス -stable npm リリースを行うときは、次の手順に従います。 +stable npm リリースを作成するとき: -1. `preflight_only=true` で `OpenClaw NPM Release` を実行します - - タグがまだ存在しない場合は、 - 事前確認ワークフローの検証専用ドライランとして現在の完全な `main` コミット SHA を使用できます -2. 通常の beta-first フローでは `npm_dist_tag=beta` を選択し、 - 意図的に stable を直接公開したい場合にのみ `latest` を選択します +1. `preflight_only=true` で `OpenClaw NPM Release` を実行する + - タグがまだ存在しない場合は、事前確認ワークフローの検証専用ドライランのために + 現在の完全な `main` コミット SHA を使用できる +2. 通常の beta-first フローでは `npm_dist_tag=beta` を選択し、意図的に直接 stable 公開したい場合にのみ `latest` を選択する 3. ライブ prompt cache カバレッジが必要な場合は、同じタグまたは - 現在の完全な `main` コミット SHA を指定して `OpenClaw Release Checks` を別途実行します - - これは意図的な分離です。これにより、長時間実行または不安定なチェックを公開ワークフローに再結合することなく、 - ライブカバレッジを利用可能なまま維持できます -4. 成功した `preflight_run_id` を保存します + 現在の完全な `main` コミット SHA を使って `OpenClaw Release Checks` を別途実行する + - これは意図的な分離であり、公開ワークフローに長時間実行または不安定なチェックを + 再結合せずに、ライブカバレッジを利用可能なままにするため +4. 成功した `preflight_run_id` を保存する 5. `preflight_only=false`、同じ - `tag`、同じ `npm_dist_tag`、および保存した `preflight_run_id` を指定して、再度 `OpenClaw NPM Release` を実行します -6. リリースが `beta` に公開された場合は、その - 公開済みビルドを `latest` に移動したいタイミングで、同じ stable `tag`、 - `promote_beta_to_latest=true`、`preflight_only=false`、 - 空の `preflight_run_id`、および `npm_dist_tag=beta` を指定して後で `OpenClaw NPM Release` を実行します -7. リリースが意図的に `latest` に直接公開され、`beta` - も同じ stable ビルドを指すべき場合は、同じ - stable `tag`、`sync_stable_dist_tags=true`、`promote_beta_to_latest=false`、 - `preflight_only=false`、空の `preflight_run_id`、および `npm_dist_tag=latest` を指定して `OpenClaw NPM Release` を実行します + `tag`、同じ `npm_dist_tag`、保存した `preflight_run_id` で `OpenClaw NPM Release` を再度実行する +6. リリースが `beta` に着地した場合は、プライベートな + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + ワークフローを使って、その stable バージョンを `beta` から `latest` に昇格させる +7. リリースを意図的に直接 `latest` に公開し、`beta` も + ただちに同じ stable ビルドに追従させたい場合は、同じプライベート + ワークフローを使って両方の dist-tag を stable バージョンに向けるか、スケジュールされた + 自己修復同期によって後で `beta` を移動させる -昇格モードおよび dist-tag 同期モードでも、`npm-release` -環境の承認と、そのワークフロー実行からアクセス可能な有効な `NPM_TOKEN` が引き続き必要です。 +dist-tag の変更がプライベートリポジトリにあるのは、依然として +`NPM_TOKEN` が必要である一方、公開リポジトリは OIDC のみの公開を維持するため、 +セキュリティ上の理由による。 これにより、直接公開経路と beta-first 昇格経路の両方が -文書化され、運用者に見える形で維持されます。 +文書化され、オペレーターから見える状態に保たれる。 ## 公開リファレンス - [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml) - [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml) +- [`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-cross-os-release-checks-reusable.yml) - [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts) - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -maintainer は、実際のランブックについて +maintainer は実際のランブックについて、 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -にある private のリリースドキュメントを使用します。 +にあるプライベートなリリースドキュメントを使用する。 diff --git a/docs/ja-JP/reference/secretref-credential-surface.md b/docs/ja-JP/reference/secretref-credential-surface.md index d33f89a5e..d84486767 100644 --- a/docs/ja-JP/reference/secretref-credential-surface.md +++ b/docs/ja-JP/reference/secretref-credential-surface.md @@ -1,31 +1,31 @@ --- read_when: - - SecretRef認証情報カバレッジを検証する場合 - - 認証情報が `secrets configure` または `secrets apply` の対象かどうかを監査する場合 - - 認証情報がサポート対象外サーフェスである理由を検証する場合 -summary: 正規のサポート対象および非サポート対象のSecretRef認証情報サーフェス + - SecretRef認証情報のカバレッジを確認する + - 認証情報が `secrets configure` または `secrets apply` の対象かどうかを監査する + - 認証情報がサポート対象外のサーフェスにある理由を確認する +summary: SecretRef認証情報サーフェスの正式なサポート対象と非サポート対象 title: SecretRef認証情報サーフェス x-i18n: - generated_at: "2026-04-07T04:46:04Z" + generated_at: "2026-04-15T04:44:08Z" model: gpt-5.4 provider: openai - source_hash: 211f4b504c5808f7790683066fc2c8b700c705c598f220a264daf971b81cc593 + source_hash: dd0b9c379236b17a72f552d6360b8b5a2269009e019c138c6bb50f4f7328ddaf source_path: reference/secretref-credential-surface.md workflow: 15 --- # SecretRef認証情報サーフェス -このページでは、正規のSecretRef認証情報サーフェスを定義します。 +このページでは、正式なSecretRef認証情報サーフェスを定義します。 スコープの意図: -- 対象内: OpenClawが発行またはローテーションしない、厳密にユーザー提供の認証情報。 -- 対象外: ランタイムで発行またはローテーションされる認証情報、OAuthリフレッシュ情報、セッション類似アーティファクト。 +- 対象: OpenClawが発行またはローテーションしない、厳密にユーザー提供の認証情報。 +- 対象外: ランタイム時に発行される、またはローテーションされる認証情報、OAuthリフレッシュ用データ、およびセッションに類するアーティファクト。 -## サポートされる認証情報 +## サポート対象の認証情報 -### `openclaw.json` 対象（`secrets configure` + `secrets apply` + `secrets audit`） +### `openclaw.json` の対象（`secrets configure` + `secrets apply` + `secrets audit`） [//]: # "secretref-supported-list-start" @@ -49,6 +49,7 @@ x-i18n: - `messages.tts.providers.*.apiKey` - `tools.web.fetch.firecrawl.apiKey` - `plugins.entries.brave.config.webSearch.apiKey` +- `plugins.entries.exa.config.webSearch.apiKey` - `plugins.entries.google.config.webSearch.apiKey` - `plugins.entries.xai.config.webSearch.apiKey` - `plugins.entries.moonshot.config.webSearch.apiKey` @@ -107,10 +108,10 @@ x-i18n: - `channels.zalo.webhookSecret` - `channels.zalo.accounts.*.botToken` - `channels.zalo.accounts.*.webhookSecret` -- `channels.googlechat.serviceAccount` は兄弟 `serviceAccountRef` 経由（互換性例外） -- `channels.googlechat.accounts.*.serviceAccount` は兄弟 `serviceAccountRef` 経由（互換性例外） +- `channels.googlechat.serviceAccount` は兄弟 `serviceAccountRef` 経由（互換性のための例外） +- `channels.googlechat.accounts.*.serviceAccount` は兄弟 `serviceAccountRef` 経由（互換性のための例外） -### `auth-profiles.json` 対象（`secrets configure` + `secrets apply` + `secrets audit`） +### `auth-profiles.json` の対象（`secrets configure` + `secrets apply` + `secrets audit`） - `profiles.*.keyRef`（`type: "api_key"`; `auth.profiles..mode = "oauth"` の場合は非サポート） - `profiles.*.tokenRef`（`type: "token"`; `auth.profiles..mode = "oauth"` の場合は非サポート） @@ -119,21 +120,21 @@ x-i18n: 注記: -- Auth-profile plan対象には `agentId` が必要です。 -- Planエントリは `profiles.*.key` / `profiles.*.token` を対象にし、兄弟ref（`keyRef` / `tokenRef`）を書き込みます。 -- Auth-profile ref はランタイム解決および監査カバレッジに含まれます。 -- OAuthポリシーガード: `auth.profiles..mode = "oauth"` は、そのプロファイルに対するSecretRef入力と組み合わせることはできません。このポリシーに違反した場合、起動/リロードおよびauth-profile解決は即座に失敗します。 -- SecretRef管理のモデルプロバイダーでは、生成される `agents/*/agent/models.json` エントリは、`apiKey`/headerサーフェスに対して秘密値の代わりに非シークレットのマーカーを永続化します（解決済みのシークレット値は保存しません）。 -- マーカー永続化はソースを正として行われます: OpenClawは、解決済みランタイムシークレット値からではなく、アクティブなソース設定スナップショット（解決前）からマーカーを書き込みます。 -- Web検索について: - - 明示的プロバイダーモード（`tools.web.search.provider` が設定されている）では、選択されたプロバイダーキーのみがアクティブです。 - - 自動モード（`tools.web.search.provider` が未設定）では、優先順位で解決される最初のプロバイダーキーのみがアクティブです。 - - 自動モードでは、非選択のプロバイダーrefは選択されるまで非アクティブとして扱われます。 - - レガシーな `tools.web.search.*` プロバイダーパスは互換期間中は引き続き解決されますが、正規のSecretRefサーフェスは `plugins.entries..config.webSearch.*` です。 +- Auth-profileのplan対象には `agentId` が必要です。 +- Planエントリは `profiles.*.key` / `profiles.*.token` を対象とし、兄弟ref（`keyRef` / `tokenRef`）を書き込みます。 +- Auth-profileのrefは、ランタイム解決および監査カバレッジに含まれます。 +- OAuthポリシーガード: `auth.profiles..mode = "oauth"` は、そのprofileに対するSecretRef入力と組み合わせることはできません。このポリシーに違反すると、起動/リロードおよびauth-profile解決は即座に失敗します。 +- SecretRef管理対象のモデルproviderでは、生成される `agents/*/agent/models.json` エントリに、`apiKey`/headerサーフェス用の非シークレットマーカー（解決済みのシークレット値ではない）が永続化されます。 +- マーカーの永続化はソースを正とします: OpenClawは、解決済みランタイムシークレット値からではなく、アクティブなソース設定スナップショット（解決前）からマーカーを書き込みます。 +- web searchについて: + - 明示的providerモード（`tools.web.search.provider` が設定されている）では、選択されたproviderキーのみが有効です。 + - 自動モード（`tools.web.search.provider` が未設定）では、優先順位に従って解決される最初のproviderキーのみが有効です。 + - 自動モードでは、未選択のprovider refは選択されるまで非アクティブとして扱われます。 + - レガシーな `tools.web.search.*` providerパスも互換性ウィンドウ中は引き続き解決されますが、正式なSecretRefサーフェスは `plugins.entries..config.webSearch.*` です。 -## サポートされない認証情報 +## サポート対象外の認証情報 -対象外の認証情報には次が含まれます: +対象外の認証情報には、以下が含まれます: [//]: # "secretref-unsupported-list-start" @@ -149,6 +150,6 @@ x-i18n: [//]: # "secretref-unsupported-list-end" -理由: +根拠: -- これらの認証情報は、発行される、ローテーションされる、セッションを保持する、またはOAuthの永続クラスに属しており、読み取り専用の外部SecretRef解決には適合しません。 +- これらの認証情報は、発行される、ローテーションされる、セッション性を持つ、またはOAuthの永続クラスに属しており、読み取り専用の外部SecretRef解決には適しません。 diff --git a/docs/ja-JP/start/showcase.md b/docs/ja-JP/start/showcase.md index c171bcecd..93f831de8 100644 --- a/docs/ja-JP/start/showcase.md +++ b/docs/ja-JP/start/showcase.md @@ -1,427 +1,479 @@ --- +description: Real-world OpenClaw projects from the community read_when: - - 実際のOpenClaw活用例を探しているとき - - コミュニティプロジェクトのハイライトを更新しているとき -summary: OpenClawを活用したコミュニティ製プロジェクトと連携 + - 実際のOpenClawの使用例を探している場合 + - コミュニティプロジェクトのハイライトを更新したい場合 +summary: OpenClawを活用したコミュニティ製プロジェクトと統合機能 title: ショーケース x-i18n: - generated_at: "2026-04-05T12:58:14Z" + generated_at: "2026-04-15T04:44:10Z" model: gpt-5.4 provider: openai - source_hash: 2917e9a476ef527ddb3e51c610bbafbd145e705c9cc29f191639fb63d238ef70 + source_hash: 797d0b85c9eca920240c79d870eb9636216714f3eba871c5ebd0f7f40cf7bbf1 source_path: start/showcase.md workflow: 15 --- + + # ショーケース -コミュニティによる実際のプロジェクトです。OpenClawで人々が何を作っているのかをご覧ください。 +
+

チャット、ターミナル、ブラウザー、そしてリビングルームで構築

+

+ OpenClawプロジェクトはおもちゃのデモではありません。すでに使っているチャネルから、PRレビューのループ、モバイルアプリ、ホームオートメーション、音声システム、devtools、メモリ負荷の高いワークフローが実際に出荷されています。 +

+ +
+
+ チャットネイティブな構築 + Telegram、WhatsApp、Discord、Beeper、Webチャット、そしてターミナル中心のワークフロー。 +
+
+ 実用的な自動化 + APIを待たずに、予約、買い物、サポート、レポート作成、ブラウザー操作を実現。 +
+
+ ローカル + 現実世界 + プリンター、掃除機、カメラ、健康データ、ホームシステム、個人ナレッジベース。 +
+
+
-**掲載されたいですか？** [Discordの #self-promotion](https://discord.gg/clawd) であなたのプロジェクトを共有するか、[Xで @openclaw をタグ付け](https://x.com/openclaw)してください。 +**掲載されたいですか？** あなたのプロジェクトを [Discordの#self-promotion](https://discord.gg/clawd) で共有するか、[Xで@openclawをタグ付け](https://x.com/openclaw)してください。 -## 🎥 動くOpenClaw - -VelvetSharkによる完全セットアップ解説（28分）。 - -
-