diff --git a/docs/ja-JP/channels/matrix-push-rules.md b/docs/ja-JP/channels/matrix-push-rules.md new file mode 100644 index 000000000..0dd68f30f --- /dev/null +++ b/docs/ja-JP/channels/matrix-push-rules.md @@ -0,0 +1,157 @@ +--- +read_when: + - セルフホスト型SynapseまたはTuwunel向けにMatrixの静かなストリーミングを設定する方法 + - ユーザーは、すべてのプレビュー編集ではなく、完了したブロックでのみ通知を受け取りたいと考えています +summary: 静かな確定済みプレビュー編集に対する受信者ごとのMatrixプッシュルール +title: 静かなプレビューに対するMatrixプッシュルール +x-i18n: + generated_at: "2026-04-23T15:00:52Z" + model: gpt-5.4 + provider: openai + source_hash: dbfdf2552ca352858d4e8d03a2a0f5f3b420d33b01063c111c0335c0229f0534 + source_path: channels/matrix-push-rules.md + workflow: 15 +--- + +# 静かなプレビューに対するMatrixプッシュルール + +`channels.matrix.streaming` が `"quiet"` の場合、OpenClaw は単一のプレビューイベントをその場で編集し、確定した編集にカスタムのコンテンツフラグを付けます。Matrixクライアントが最終編集時にのみ通知するには、ユーザーごとのプッシュルールがそのフラグに一致する必要があります。このページは、Matrixをセルフホストしていて、受信者アカウントごとにそのルールをインストールしたい運用者向けです。 + +標準のMatrix通知動作だけが必要な場合は、`streaming: "partial"` を使うか、ストリーミングをオフのままにしてください。[Matrixチャネルの設定](/ja-JP/channels/matrix#streaming-previews)を参照してください。 + +## 前提条件 + +- recipient user = 通知を受け取る人 +- bot user = 返信を送信するOpenClaw Matrixアカウント +- 以下のAPI呼び出しでは recipient user のアクセストークンを使用する +- プッシュルール内の `sender` は bot user の完全なMXID に一致させる +- recipient アカウントには、すでに動作する pusher が存在している必要があります。静かなプレビュールールは、通常のMatrixプッシュ配信が正常に機能している場合にのみ動作します + +## 手順 + + + + +```json5 +{ + channels: { + matrix: { + streaming: "quiet", + }, + }, +} +``` + + + + + 可能であれば既存のクライアントセッショントークンを再利用してください。新しく発行するには、次を実行します。 + +```bash +curl -sS -X POST \ + "https://matrix.example.org/_matrix/client/v3/login" \ + -H "Content-Type: application/json" \ + --data '{ + "type": "m.login.password", + "identifier": { "type": "m.id.user", "user": "@alice:example.org" }, + "password": "REDACTED" + }' +``` + + + + + +```bash +curl -sS \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + "https://matrix.example.org/_matrix/client/v3/pushers" +``` + +pusher が返ってこない場合は、続行する前にこのアカウントの通常のMatrixプッシュ配信を修正してください。 + + + + + OpenClaw は、確定したテキストのみのプレビュー編集に `content["com.openclaw.finalized_preview"] = true` を付けます。このマーカーと bot MXID を送信者として一致させるルールをインストールしてください。 + +```bash +curl -sS -X PUT \ + "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + --data '{ + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.room.message" }, + { + "kind": "event_property_is", + "key": "content.m\\.relates_to.rel_type", + "value": "m.replace" + }, + { + "kind": "event_property_is", + "key": "content.com\\.openclaw\\.finalized_preview", + "value": true + }, + { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" } + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" }, + { "set_tweak": "highlight", "value": false } + ] + }' +``` + + 実行前に以下を置き換えてください。 + + - `https://matrix.example.org`: あなたのホームサーバーのベースURL + - `$USER_ACCESS_TOKEN`: recipient user のアクセストークン + - `openclaw-finalized-preview-botname`: 受信者ごと・bot ごとに一意な rule ID（パターン: `openclaw-finalized-preview-`） + - `@bot:example.org`: recipient ではなく、あなたのOpenClaw bot のMXID + + + + + +```bash +curl -sS \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" +``` + +その後、ストリーミング返信をテストしてください。quiet モードでは、ルームには静かな下書きプレビューが表示され、ブロックまたはターンの完了時に一度だけ通知されます。 + + + + +後でルールを削除するには、recipient のトークンを使って同じルールURL に対して `DELETE` してください。 + +## 複数botに関する注意 + +プッシュルールは `ruleId` によって識別されます。同じID に対して `PUT` を再実行すると、単一のルールが更新されます。同じ recipient に複数のOpenClaw bot が通知する場合は、送信者一致条件が異なる bot ごとに1つのルールを作成してください。 + +新しいユーザー定義の `override` ルールは、デフォルトの抑制ルールより前に挿入されるため、追加の順序パラメーターは不要です。このルールが影響するのは、その場で確定可能なテキストのみのプレビュー編集だけです。メディアのフォールバックや古いプレビューのフォールバックでは、通常のMatrix配信が使われます。 + +## ホームサーバーに関する注意 + + + + 特別な `homeserver.yaml` の変更は不要です。通常のMatrix通知がすでにこのユーザーに届いている場合、主な設定手順は受信者トークンと上記の `pushrules` 呼び出しです。 + + Synapse をリバースプロキシや workers の背後で運用している場合は、`/_matrix/client/.../pushrules/` が正しくSynapse に到達することを確認してください。プッシュ配信はメインプロセスまたは `synapse.app.pusher` / 設定済みの pusher workers によって処理されるため、それらが正常であることを確認してください。 + + + + + Synapse と同じフローで、確定済みプレビューマーカーのためのTuwunel固有設定は不要です。 + + ユーザーが別のデバイスでアクティブなときに通知が消える場合は、`suppress_push_when_active` が有効になっていないか確認してください。Tuwunel は 1.4.2（2025年9月）でこのオプションを追加しており、1つのデバイスがアクティブな間、他のデバイスへのプッシュを意図的に抑制することがあります。 + + + + +## 関連 + +- [Matrixチャネルの設定](/ja-JP/channels/matrix) +- [ストリーミングの概念](/ja-JP/concepts/streaming) diff --git a/docs/ja-JP/channels/matrix.md b/docs/ja-JP/channels/matrix.md index d3bae19c1..a6772f83b 100644 --- a/docs/ja-JP/channels/matrix.md +++ b/docs/ja-JP/channels/matrix.md @@ -1,32 +1,32 @@ --- read_when: - - OpenClawでMatrixをセットアップする。 - - MatrixのE2EEと検証を設定する。 -summary: Matrixのサポート状況、セットアップ、および設定例 + - OpenClaw で Matrix をセットアップする + - Matrix の E2EE と検証を設定する +summary: Matrix のサポート状況、セットアップ、および設定例 title: Matrix x-i18n: - generated_at: "2026-04-23T13:58:18Z" + generated_at: "2026-04-23T15:00:47Z" model: gpt-5.4 provider: openai - source_hash: 14873e9d65994138d26ad0bc1bf9bc6e00bea17f9306d592c757503d363de71a + source_hash: 2e9d4d656b47aca2dacb00e591378cb26631afc5b634074bc26e21741b418b47 source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrixは、OpenClawに同梱されているchannel Pluginです。 -公式の`matrix-js-sdk`を使用し、DM、ルーム、スレッド、メディア、リアクション、投票、位置情報、E2EEをサポートしています。 +Matrix は OpenClaw のバンドル済み channel plugin です。 +公式の `matrix-js-sdk` を使用し、DM、ルーム、スレッド、メディア、リアクション、投票、位置情報、E2EE をサポートします。 -## 同梱Plugin +## バンドル済み plugin -Matrixは現在のOpenClawリリースでは同梱Pluginとして提供されるため、通常の +Matrix は現在の OpenClaw リリースではバンドル済み plugin として提供されるため、通常の パッケージ版ビルドでは別途インストールは不要です。 -古いビルドまたはMatrixを含まないカスタムインストールを使用している場合は、 +古いビルドや、Matrix が除外されたカスタムインストールを使用している場合は、 手動でインストールしてください。 -npmからインストール: +npm からインストール: ```bash openclaw plugins install @openclaw/matrix @@ -38,20 +38,20 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./path/to/local/matrix-plugin ``` -Pluginの動作とインストールルールについては、[Plugins](/ja-JP/tools/plugin)を参照してください。 +plugin の動作とインストール規則については、[Plugins](/ja-JP/tools/plugin) を参照してください。 ## セットアップ -1. Matrix Pluginが利用可能であることを確認します。 - - 現在のパッケージ版OpenClawリリースには、すでに同梱されています。 - - 古いインストールやカスタムインストールでは、上記のコマンドで手動追加できます。 -2. ご利用のhomeserverでMatrixアカウントを作成します。 -3. `channels.matrix`を次のいずれかで設定します。 +1. Matrix plugin が利用可能であることを確認します。 + - 現在のパッケージ版 OpenClaw リリースには、すでにバンドルされています。 + - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 +2. homeserver 上で Matrix アカウントを作成します。 +3. `channels.matrix` を次のいずれかで設定します。 - `homeserver` + `accessToken`、または - - `homeserver` + `userId` + `password` -4. Gatewayを再起動します。 -5. ボットとのDMを開始するか、ルームに招待します。 - - 新しいMatrix招待が機能するのは、`channels.matrix.autoJoin`がそれを許可している場合のみです。 + - `homeserver` + `userId` + `password`。 +4. Gateway を再起動します。 +5. ボットとの DM を開始するか、ルームに招待します。 + - 新しい Matrix 招待は、`channels.matrix.autoJoin` がそれを許可している場合にのみ機能します。 対話式セットアップ手順: @@ -60,35 +60,35 @@ openclaw channels add openclaw configure --section channels ``` -Matrixウィザードでは次を確認します: +Matrix ウィザードでは次を尋ねます: - homeserver URL -- 認証方法: アクセストークンまたはパスワード -- ユーザーID（パスワード認証時のみ） +- 認証方式: アクセストークンまたはパスワード +- ユーザー ID（パスワード認証のみ） - 任意のデバイス名 -- E2EEを有効にするかどうか -- ルームアクセスと招待の自動参加を設定するかどうか +- E2EE を有効にするかどうか +- ルームアクセスと招待自動参加を設定するかどうか ウィザードの主な動作: -- Matrix認証env varsがすでに存在し、そのアカウントにまだ設定内の認証保存がない場合、ウィザードは認証をenv varsに保持するための環境変数ショートカットを提示します。 -- アカウント名はアカウントIDに正規化されます。たとえば、`Ops Bot` は `ops-bot` になります。 -- DM許可リストのエントリーは `@user:server` を直接受け付けます。表示名が機能するのは、ライブディレクトリ参照で厳密に1件一致した場合のみです。 -- ルーム許可リストのエントリーは、ルームIDとエイリアスを直接受け付けます。`!room:server` または `#alias:server` を推奨します。未解決の名前は実行時の許可リスト解決で無視されます。 -- 招待自動参加の許可リストモードでは、安定した招待先のみを使用してください: `!roomId:server`、`#alias:server`、または `*`。プレーンなルーム名は拒否されます。 +- Matrix 認証 env var がすでに存在し、そのアカウントの認証情報がまだ config に保存されていない場合、ウィザードは認証を env var に保持するための env ショートカットを提示します。 +- アカウント名はアカウント ID に正規化されます。たとえば、`Ops Bot` は `ops-bot` になります。 +- 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 { @@ -149,11 +149,11 @@ Matrixウィザードでは次を確認します: } ``` -Matrixはキャッシュされた認証情報を `~/.openclaw/credentials/matrix/` に保存します。 +Matrix はキャッシュ済み認証情報を `~/.openclaw/credentials/matrix/` に保存します。 デフォルトアカウントでは `credentials.json` を使用し、名前付きアカウントでは `credentials-.json` を使用します。 -そこにキャッシュ済み認証情報が存在する場合、現在の認証が設定に直接セットされていなくても、OpenClawはセットアップ、doctor、channel-status検出においてMatrixが設定済みであると見なします。 +そこにキャッシュ済み認証情報が存在する場合、現在の認証が config に直接設定されていなくても、OpenClaw はセットアップ、doctor、および channel-status 検出において Matrix を設定済みとして扱います。 -環境変数の対応名（設定キーが未設定のときに使用されます）: +環境変数の対応関係（config キーが設定されていない場合に使用されます）: - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -162,7 +162,7 @@ Matrixはキャッシュされた認証情報を `~/.openclaw/credentials/matrix - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -デフォルト以外のアカウントでは、アカウント単位のenv varsを使用します: +デフォルト以外のアカウントでは、アカウント単位の env var を使用します: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -176,21 +176,21 @@ Matrixはキャッシュされた認証情報を `~/.openclaw/credentials/matrix - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -正規化されたアカウントID `ops-bot` では、次を使用します: +正規化済みアカウント ID `ops-bot` では次を使用します: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrixは、アカウントID内の句読点をエスケープして、アカウント単位のenv varsが衝突しないようにします。 +Matrix はアカウント ID 内の句読点をエスケープして、アカウント単位の env var が衝突しないようにします。 たとえば、`-` は `_X2D_` になるため、`ops-prod` は `MATRIX_OPS_X2D_PROD_*` に対応します。 -対話式ウィザードが環境変数ショートカットを提示するのは、それらの認証env varsがすでに存在し、選択したアカウントにMatrix認証がまだ設定内保存されていない場合のみです。 +対話式ウィザードは、それらの認証 env var がすでに存在し、選択したアカウントに Matrix 認証がまだ config に保存されていない場合にのみ、env-var ショートカットを提示します。 -`MATRIX_HOMESERVER` はワークスペースの `.env` からは設定できません。詳しくは [Workspace `.env` files](/ja-JP/gateway/security) を参照してください。 +`MATRIX_HOMESERVER` は workspace の `.env` からは設定できません。詳細は [Workspace `.env` files](/ja-JP/gateway/security) を参照してください。 ## 設定例 -これは、DMペアリング、ルーム許可リスト、E2EE有効化を含む実用的なベースライン設定です: +これは、DM pairing、ルーム allowlist、E2EE を有効にした実用的なベースライン設定です: ```json5 { @@ -225,17 +225,17 @@ Matrixは、アカウントID内の句読点をエスケープして、アカウ } ``` -`autoJoin` は、DM形式の招待を含むすべてのMatrix招待に適用されます。OpenClawは -招待時点でそのルームがDMかグループかを確実には分類できないため、すべての招待はまず `autoJoin` -を通ります。`dm.policy` は、ボットが参加し、そのルームがDMとして分類された後に適用されます。 +`autoJoin` は、DM スタイルの招待を含むすべての Matrix 招待に適用されます。OpenClaw は +招待時点で招待されたルームを DM かグループか確実に分類できないため、すべての招待はまず `autoJoin` +を通過します。`dm.policy` は、ボットが参加してルームが DM と分類された後に適用されます。 ## ストリーミングプレビュー -Matrixの返信ストリーミングはオプトインです。 +Matrix の返信ストリーミングはオプトインです。 -OpenClawに単一のライブプレビュー返信を送信させ、 -モデルがテキストを生成している間はそのプレビューをその場で編集し、 -返信完了時にそれを確定させたい場合は、`channels.matrix.streaming` を `"partial"` に設定します: +OpenClaw に、単一のライブプレビュー +返信を送信し、モデルがテキストを生成している間はそのプレビューをその場で編集し、返信完了時に確定させたい場合は、 +`channels.matrix.streaming` を `"partial"` に設定します: ```json5 { @@ -247,186 +247,32 @@ OpenClawに単一のライブプレビュー返信を送信させ、 } ``` -- `streaming: "off"` がデフォルトです。OpenClawは最終返信を待って1回だけ送信します。 -- `streaming: "partial"` は、現在のassistant block用に通常のMatrixテキストメッセージとして1つの編集可能なプレビューメッセージを作成します。これにより、Matrixの従来の「プレビュー先行」通知動作が維持されるため、標準クライアントでは完成済みブロックではなく最初のストリーミングされたプレビューテキストで通知される場合があります。 -- `streaming: "quiet"` は、現在のassistant block用に1つの編集可能な静かなプレビュー通知を作成します。これは、確定済みプレビュー編集に対する受信者のpush rulesも設定する場合にのみ使用してください。 -- `blockStreaming: true` は、個別のMatrix進捗メッセージを有効にします。プレビューストリーミングが有効な場合、Matrixは現在のblockのライブ下書きを維持し、完了済みblockを個別メッセージとして保持します。 -- プレビューストリーミングがオンで `blockStreaming` がオフの場合、Matrixはライブ下書きをその場で編集し、blockまたはturnの完了時にその同じeventを確定します。 -- プレビューが1つのMatrix eventに収まらなくなった場合、OpenClawはプレビューストリーミングを停止し、通常の最終配信にフォールバックします。 -- メディア返信では、引き続き通常どおり添付ファイルを送信します。古いプレビューを安全に再利用できなくなった場合、OpenClawは最終メディア返信を送る前にそれをredactします。 -- プレビュー編集には追加のMatrix API呼び出しコストがかかります。最も保守的なレート制限動作を望む場合は、ストリーミングをオフのままにしてください。 +- `streaming: "off"` がデフォルトです。OpenClaw は最終返信を待ってから 1 回だけ送信します。 +- `streaming: "partial"` は、通常の Matrix テキストメッセージを使って、現在の assistant ブロック用の編集可能なプレビューメッセージを 1 件作成します。これにより、Matrix の従来の「プレビュー先行」通知動作が維持されるため、標準クライアントでは完成済みブロックではなく、最初にストリーミングされたプレビューテキストで通知されることがあります。 +- `streaming: "quiet"` は、現在の assistant ブロック用に編集可能な静かなプレビュー通知を 1 件作成します。これは、確定済みプレビュー編集用の受信者プッシュルールも設定する場合にのみ使用してください。 +- `blockStreaming: true` は個別の Matrix 進捗メッセージを有効にします。プレビュー ストリーミングが有効な場合、Matrix は現在のブロックのライブ下書きを保持し、完了済みブロックを別メッセージとして保持します。 +- プレビュー ストリーミングがオンで `blockStreaming` がオフの場合、Matrix はライブ下書きをその場で編集し、ブロックまたはターンの完了時にその同じイベントを確定します。 +- プレビューが 1 つの Matrix イベントに収まらなくなった場合、OpenClaw はプレビュー ストリーミングを停止し、通常の最終配信にフォールバックします。 +- メディア返信は引き続き通常どおり添付ファイルを送信します。古いプレビューを安全に再利用できなくなった場合、OpenClaw は最終メディア返信を送信する前にそれを redact します。 +- プレビュー編集は Matrix API 呼び出しを追加で消費します。最も保守的な rate-limit 動作を望む場合は、ストリーミングをオフのままにしてください。 -`blockStreaming` だけでは下書きプレビューは有効になりません。 -プレビュー編集には `streaming: "partial"` または `streaming: "quiet"` を使用し、そのうえで完了したassistant blockも個別の進捗メッセージとして見せたい場合にのみ `blockStreaming: true` を追加してください。 +`blockStreaming` 自体では下書きプレビューは有効になりません。 +プレビュー編集には `streaming: "partial"` または `streaming: "quiet"` を使用し、そのうえで完了済み assistant ブロックも個別の進捗メッセージとして表示したい場合にのみ `blockStreaming: true` を追加してください。 -カスタムpush rulesなしで標準のMatrix通知が必要な場合は、プレビュー先行動作には `streaming: "partial"` を使用し、最終のみの配信には `streaming` をオフのままにしてください。`streaming: "off"` の場合: +カスタムプッシュルールなしで標準の Matrix 通知が必要な場合は、プレビュー先行動作のために `streaming: "partial"` を使用するか、最終のみの配信のために `streaming` をオフのままにしてください。`streaming: "off"` の場合: -- `blockStreaming: true` は、完了した各blockを通常の通知対象Matrixメッセージとして送信します。 -- `blockStreaming: false` は、最終的に完了した返信のみを通常の通知対象Matrixメッセージとして送信します。 +- `blockStreaming: true` は、完了した各ブロックを通常の通知付き Matrix メッセージとして送信します。 +- `blockStreaming: false` は、最終的に完成した返信のみを通常の通知付き Matrix メッセージとして送信します。 -### 静かな確定済みプレビューのためのセルフホストpush rules +### 静かな確定済みプレビュー向けのセルフホスト push rules -独自のMatrixインフラを運用していて、blockまたは -最終返信が完了したときだけ静かなプレビューで通知したい場合は、`streaming: "quiet"` を設定し、確定済みプレビュー編集用のユーザー単位push ruleを追加します。 +静かなストリーミング（`streaming: "quiet"`）では、ブロックまたはターンが確定したときにのみ受信者へ通知されます。確定済みプレビューのマーカーに一致するユーザーごとの push rule が必要です。完全なセットアップ（受信者トークン、pusher チェック、ルールインストール、homeserver ごとの注意点）については、[静かなプレビュー向け Matrix push rules](/ja-JP/channels/matrix-push-rules) を参照してください。 -これは通常、homeserver全体の設定変更ではなく、受信者ユーザー側の設定です: +## ボット間ルーム -開始前の簡単な対応表: +デフォルトでは、他の設定済み OpenClaw Matrix アカウントからの Matrix メッセージは無視されます。 -- recipient user = 通知を受け取るべき人 -- bot user = 返信を送るOpenClaw Matrixアカウント -- 以下のAPI呼び出しではrecipient userのアクセストークンを使用します -- push ruleの `sender` はbot userの完全なMXIDに一致させます - -1. OpenClawを静かなプレビューを使うよう設定します: - -```json5 -{ - channels: { - matrix: { - streaming: "quiet", - }, - }, -} -``` - -2. recipientアカウントがすでに通常のMatrix push notificationsを受け取れていることを確認します。静かなプレビュー - ルールは、そのユーザーがすでに動作するpushers/devicesを持っている場合にのみ機能します。 - -3. recipient userのアクセストークンを取得します。 - - ボットのトークンではなく、受信ユーザーのトークンを使用してください。 - - 既存のクライアントセッショントークンを再利用するのが通常は最も簡単です。 - - 新しいトークンを発行する必要がある場合は、標準のMatrix Client-Server APIからログインできます: - -```bash -curl -sS -X POST \ - "https://matrix.example.org/_matrix/client/v3/login" \ - -H "Content-Type: application/json" \ - --data '{ - "type": "m.login.password", - "identifier": { - "type": "m.id.user", - "user": "@alice:example.org" - }, - "password": "REDACTED" - }' -``` - -4. recipientアカウントにすでにpushersがあることを確認します: - -```bash -curl -sS \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushers" -``` - -これでアクティブなpushers/devicesが返らない場合は、以下の -OpenClawルールを追加する前に、まず通常のMatrix通知を修正してください。 - -OpenClawは、確定済みのテキストのみのプレビュー編集に次を付与します: - -```json -{ - "com.openclaw.finalized_preview": true -} -``` - -5. これらの通知を受け取るべき各recipientアカウントに対してoverride push ruleを作成します: - -```bash -curl -sS -X PUT \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - --data '{ - "conditions": [ - { "kind": "event_match", "key": "type", "pattern": "m.room.message" }, - { - "kind": "event_property_is", - "key": "content.m\\.relates_to.rel_type", - "value": "m.replace" - }, - { - "kind": "event_property_is", - "key": "content.com\\.openclaw\\.finalized_preview", - "value": true - }, - { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" } - ], - "actions": [ - "notify", - { "set_tweak": "sound", "value": "default" }, - { "set_tweak": "highlight", "value": false } - ] - }' -``` - -コマンド実行前に次の値を置き換えてください: - -- `https://matrix.example.org`: あなたのhomeserverのベースURL -- `$USER_ACCESS_TOKEN`: 受信ユーザーのアクセストークン -- `openclaw-finalized-preview-botname`: この受信ユーザーに対するこのボット専用の一意なrule ID -- `@bot:example.org`: 受信ユーザーのMXIDではなく、あなたのOpenClaw Matrix botのMXID - -複数ボット構成で重要: - -- Push rulesは `ruleId` をキーにします。同じrule IDに対して `PUT` を再実行すると、その1つのruleが更新されます。 -- 1人の受信ユーザーが複数のOpenClaw Matrix botアカウントからの通知を受け取る必要がある場合は、各 `sender` 一致ごとに一意のrule IDを使って、botごとに1つのruleを作成してください。 -- 単純なパターンは `openclaw-finalized-preview-` です。たとえば `openclaw-finalized-preview-ops` や `openclaw-finalized-preview-support` です。 - -このruleはevent senderに対して評価されます: - -- 受信ユーザーのトークンで認証する -- `sender` をOpenClaw botのMXIDに一致させる - -6. ruleが存在することを確認します: - -```bash -curl -sS \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" -``` - -7. ストリーミング返信をテストします。quietモードでは、ルームには静かな下書きプレビューが表示され、最終的な - インプレース編集はblockまたはturnの完了時に1回通知されるはずです。 - -後でruleを削除する必要がある場合は、受信ユーザーのトークンを使って同じrule IDを削除します: - -```bash -curl -sS -X DELETE \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" -``` - -注記: - -- ruleはbotのものではなく、受信ユーザーのアクセストークンで作成してください。 -- 新しいユーザー定義 `override` rulesはデフォルトの抑制rulesより前に挿入されるため、追加の順序パラメーターは不要です。 -- これは、OpenClawが安全にインプレース確定できるテキストのみのプレビュー編集にのみ影響します。メディアフォールバックや古いプレビューフォールバックでは、引き続き通常のMatrix配信が使われます。 -- `GET /_matrix/client/v3/pushers` でpushersが表示されない場合、そのユーザーはまだこのアカウント/デバイスに対する動作するMatrix push配信を持っていません。 - -#### Synapse - -Synapseでは、通常は上記のセットアップだけで十分です: - -- 確定済みOpenClawプレビュー通知のために特別な `homeserver.yaml` の変更は不要です。 -- Synapseデプロイですでに通常のMatrix push notificationsが送信されている場合、主なセットアップ手順は上記のユーザートークン + `pushrules` 呼び出しです。 -- Synapseをリバースプロキシまたはworkerの背後で実行している場合は、`/_matrix/client/.../pushrules/` が正しくSynapseに到達することを確認してください。 -- Synapse workersを実行している場合は、pushersが健全であることを確認してください。push配信はメインプロセスまたは `synapse.app.pusher` / 設定済みのpusher workersによって処理されます。 - -#### Tuwunel - -Tuwunelでは、上記と同じセットアップフローとpush-rule API呼び出しを使用します: - -- 確定済みプレビューマーカー自体のために、Tuwunel固有の設定は不要です。 -- そのユーザーに対して通常のMatrix通知がすでに機能している場合、主なセットアップ手順は上記のユーザートークン + `pushrules` 呼び出しです。 -- ユーザーが別のデバイスでアクティブな間に通知が消えるように見える場合は、`suppress_push_when_active` が有効になっているか確認してください。Tuwunelは2025年9月12日のTuwunel 1.4.2でこのオプションを追加しており、1つのデバイスがアクティブな間、他のデバイスへのpushを意図的に抑制することがあります。 - -## Bot-to-botルーム - -デフォルトでは、他の設定済みOpenClaw MatrixアカウントからのMatrixメッセージは無視されます。 - -意図的にagent間のMatrix通信を許可したい場合は、`allowBots` を使用します: +意図的にエージェント間の Matrix トラフィックを許可したい場合は `allowBots` を使用します: ```json5 { @@ -443,19 +289,19 @@ Tuwunelでは、上記と同じセットアップフローとpush-rule API呼び } ``` -- `allowBots: true` は、許可されたルームとDMで、他の設定済みMatrix botアカウントからのメッセージを受け入れます。 -- `allowBots: "mentions"` は、ルームではそれらのメッセージがこのbotに明示的にメンションしている場合にのみ受け入れます。DMは引き続き許可されます。 -- `groups..allowBots` は、1つのルームに対してアカウントレベル設定を上書きします。 -- OpenClawは自己返信ループを避けるため、同じMatrix user IDからのメッセージは引き続き無視します。 -- Matrixはここでネイティブのbotフラグを公開していません。OpenClawは「bot-authored」を「このOpenClaw Gateway上の別の設定済みMatrixアカウントから送信されたもの」として扱います。 +- `allowBots: true` は、許可されたルームと DM において、他の設定済み Matrix ボットアカウントからのメッセージを受け入れます。 +- `allowBots: "mentions"` は、ルーム内でこのボットへの明示的なメンションがある場合にのみ、それらのメッセージを受け入れます。DM は引き続き許可されます。 +- `groups..allowBots` は、1 つのルームについてアカウントレベル設定を上書きします。 +- OpenClaw は自己返信ループを避けるため、同じ Matrix ユーザー ID からのメッセージは引き続き無視します。 +- Matrix はここでネイティブの bot フラグを公開していないため、OpenClaw は「bot によって送信された」を「この OpenClaw Gateway 上で設定された別の Matrix アカウントによって送信された」として扱います。 -共有ルームでbot-to-bot通信を有効にする場合は、厳格なルーム許可リストとメンション要件を使用してください。 +共有ルームでボット間トラフィックを有効にする場合は、厳格なルーム allowlist とメンション要件を使用してください。 ## 暗号化と検証 -暗号化された（E2EE）ルームでは、送信する画像eventは `thumbnail_file` を使用するため、画像プレビューは完全な添付ファイルと一緒に暗号化されます。暗号化されていないルームでは、引き続きプレーンな `thumbnail_url` を使用します。設定は不要で、PluginがE2EE状態を自動検出します。 +暗号化された（E2EE）ルームでは、送信画像イベントは `thumbnail_file` を使用するため、画像プレビューは完全な添付ファイルと一緒に暗号化されます。暗号化されていないルームでは、引き続きプレーンな `thumbnail_url` を使用します。設定は不要です。plugin が E2EE 状態を自動検出します。 -暗号化を有効化: +暗号化を有効にする: ```json5 { @@ -471,92 +317,22 @@ Tuwunelでは、上記と同じセットアップフローとpush-rule API呼び } ``` -検証状態を確認: +検証コマンド（すべて診断用の `--verbose` と機械可読出力用の `--json` を受け取ります）: -```bash -openclaw matrix verify status -``` +| コマンド | 目的 | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `openclaw matrix verify status` | cross-signing とデバイス検証の状態を確認する | +| `openclaw matrix verify status --include-recovery-key --json` | 保存済みの recovery key を含める | +| `openclaw matrix verify bootstrap` | cross-signing と検証を bootstrap する（下記参照） | +| `openclaw matrix verify bootstrap --force-reset-cross-signing` | 現在の cross-signing ID を破棄して新しいものを作成する | +| `openclaw matrix verify device ""` | recovery key を使ってこのデバイスを検証する | +| `openclaw matrix verify backup status` | room-key backup の健全性を確認する | +| `openclaw matrix verify backup restore` | サーバーバックアップから room keys を復元する | +| `openclaw matrix verify backup reset --yes` | 現在のバックアップを削除して新しいベースラインを作成する（secret storage を再作成する場合があります） | -詳細な状態表示（完全な診断情報）: - -```bash -openclaw matrix verify status --verbose -``` - -保存されたリカバリーキーを機械可読出力に含める: - -```bash -openclaw matrix verify status --include-recovery-key --json -``` - -クロス署名と検証状態をブートストラップ: - -```bash -openclaw matrix verify bootstrap -``` - -詳細なブートストラップ診断: - -```bash -openclaw matrix verify bootstrap --verbose -``` - -ブートストラップ前に新しいクロス署名IDのリセットを強制: - -```bash -openclaw matrix verify bootstrap --force-reset-cross-signing -``` - -リカバリーキーでこのデバイスを検証: - -```bash -openclaw matrix verify device "" -``` - -詳細なデバイス検証情報: - -```bash -openclaw matrix verify device "" --verbose -``` - -ルームキーbackupの健全性を確認: - -```bash -openclaw matrix verify backup status -``` - -詳細なbackup健全性診断: - -```bash -openclaw matrix verify backup status --verbose -``` - -サーバーbackupからルームキーを復元: - -```bash -openclaw matrix verify backup restore -``` - -詳細な復元診断: - -```bash -openclaw matrix verify backup restore --verbose -``` - -現在のサーバーbackupを削除し、新しいbackupベースラインを作成します。保存された -backupキーを正常に読み込めない場合、このリセットではシークレットストレージも再作成して、 -将来のコールドスタートで新しいbackupキーを読み込めるようにすることがあります: - -```bash -openclaw matrix verify backup reset --yes -``` - -すべての `verify` コマンドはデフォルトでは簡潔な出力（静かな内部SDKロギングを含む）で、詳細な診断は `--verbose` を付けた場合のみ表示します。 -スクリプトで使用する場合は、完全な機械可読出力のために `--json` を使ってください。 - -複数アカウント構成では、Matrix CLIコマンドは `--account ` を渡さない限り、暗黙のMatrixデフォルトアカウントを使用します。 -複数の名前付きアカウントを設定している場合は、まず `channels.matrix.defaultAccount` を設定してください。そうしないと、これらの暗黙的なCLI操作は停止して、明示的にアカウントを選ぶよう求めます。 -検証やデバイス操作を明示的に名前付きアカウントに向けたい場合は、`--account` を使用してください: +マルチアカウント構成では、Matrix CLI コマンドは `--account ` を渡さない限り、暗黙の Matrix デフォルトアカウントを使用します。 +複数の名前付きアカウントを設定している場合は、最初に `channels.matrix.defaultAccount` を設定してください。そうしないと、それらの暗黙的な CLI 操作は停止して、明示的にアカウントを選ぶよう求めます。 +検証またはデバイス操作の対象を明示的に名前付きアカウントにしたい場合は、常に `--account` を使用してください。 ```bash openclaw matrix verify status --account assistant @@ -564,42 +340,34 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -名前付きアカウントで暗号化が無効または利用できない場合、Matrixの警告と検証エラーはそのアカウントの設定キーを指します。たとえば `channels.matrix.accounts.assistant.encryption` です。 +暗号化が無効、または名前付きアカウントで利用できない場合、Matrix の警告と検証エラーはそのアカウントの config キーを指します。たとえば `channels.matrix.accounts.assistant.encryption` です。 -### 「verified」の意味 + + + OpenClaw は、あなた自身の cross-signing ID が署名した場合にのみ、デバイスを verified と見なします。`verify status --verbose` は 3 つの trust signal を表示します。 -OpenClawは、このMatrixデバイスが自分自身のクロス署名IDによって検証された場合にのみ、そのデバイスをverifiedとして扱います。 -実際には、`openclaw matrix verify status --verbose` は3つの信頼シグナルを表示します: + - `Locally trusted`: このクライアントでのみ信頼されている + - `Cross-signing verified`: SDK が cross-signing による検証を報告している + - `Signed by owner`: あなた自身の self-signing key によって署名されている -- `Locally trusted`: このデバイスは現在のクライアントでのみ信頼されています -- `Cross-signing verified`: SDKはこのデバイスがクロス署名を通じて検証済みであると報告しています -- `Signed by owner`: このデバイスは自分自身のself-signing keyで署名されています + `Verified by owner` は、cross-signing または owner-signing が存在する場合にのみ `yes` になります。ローカル信頼だけでは不十分です。 -`Verified by owner` が `yes` になるのは、クロス署名による検証またはowner署名が存在する場合のみです。 -ローカル信頼だけでは、OpenClawがそのデバイスを完全にverifiedとして扱うには不十分です。 + -### bootstrapが行うこと + + `verify bootstrap` は、暗号化アカウント向けの修復およびセットアップコマンドです。順に次を実行します。 -`openclaw matrix verify bootstrap` は、暗号化されたMatrixアカウントの修復およびセットアップ用コマンドです。 -次のすべてを順に行います: + - secret storage を bootstrap し、可能な場合は既存の recovery key を再利用する + - cross-signing を bootstrap し、不足している公開 cross-signing keys をアップロードする + - 現在のデバイスに印を付けて cross-sign する + - サーバー側の room-key backup がまだ存在しない場合は作成する -- 可能なら既存のリカバリーキーを再利用しながら、シークレットストレージをブートストラップする -- クロス署名をブートストラップし、不足している公開クロス署名キーをアップロードする -- 現在のデバイスに印を付けてクロス署名することを試みる -- まだ存在しない場合は、新しいサーバー側ルームキーbackupを作成する + homeserver が cross-signing keys のアップロードに UIA を要求する場合、OpenClaw はまず no-auth を試し、その後 `m.login.dummy`、さらに `m.login.password` を試します（`channels.matrix.password` が必要です）。`--force-reset-cross-signing` は、現在の ID を意図的に破棄する場合にのみ使用してください。 -homeserverがクロス署名キーのアップロードに対話型認証を必要とする場合、OpenClawはまず認証なしでアップロードを試し、その後 `m.login.dummy`、さらに `channels.matrix.password` が設定されている場合は `m.login.password` を使って試します。 + -現在のクロス署名IDを破棄して新しいものを作成したい場合にのみ、`--force-reset-cross-signing` を使用してください。 - -現在のルームキーbackupを意図的に破棄し、今後のメッセージ向けに新しい -backupベースラインを開始したい場合は、`openclaw matrix verify backup reset --yes` を使用してください。 -これは、回復不能な古い暗号化履歴が引き続き利用不能のままであることと、 -現在のbackupシークレットを安全に読み込めない場合にOpenClawがシークレットストレージを再作成する可能性があることを受け入れる場合にのみ行ってください。 - -### 新しいbackupベースライン - -将来の暗号化メッセージを機能させ続けつつ、回復不能な古い履歴の喪失を受け入れる場合は、次のコマンドを順に実行してください: + + 今後の暗号化メッセージを動作させ続けつつ、復元不能な古い履歴を失っても構わない場合: ```bash openclaw matrix verify backup reset --yes @@ -607,125 +375,98 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -名前付きMatrixアカウントを明示的に対象にしたい場合は、各コマンドに `--account ` を追加してください。 + 名前付きアカウントを対象にするには `--account ` を追加します。現在の backup secret を安全に読み込めない場合、これにより secret storage も再作成されることがあります。 -### 起動時の動作 + -`encryption: true` の場合、Matrixは `startupVerification` のデフォルトを `"if-unverified"` にします。 -起動時にこのデバイスがまだ未検証であれば、Matrixは別のMatrixクライアントでの自己検証を要求し、 -すでに保留中の要求がある間は重複要求をスキップし、再起動後の再試行前にローカルのクールダウンを適用します。 -デフォルトでは、要求の作成に成功した場合よりも、要求試行に失敗した場合の方が早く再試行されます。 -起動時の自動要求を無効にするには `startupVerification: "off"` を設定するか、再試行ウィンドウを短くまたは長くしたい場合は `startupVerificationCooldownHours` -を調整してください。 + + `encryption: true` の場合、`startupVerification` のデフォルトは `"if-unverified"` です。起動時に未検証デバイスは、別の Matrix クライアントでの自己検証を要求し、重複を避けつつクールダウンを適用します。`startupVerificationCooldownHours` で調整するか、`startupVerification: "off"` で無効化できます。 -起動時には、保守的なcrypto bootstrapパスも自動で実行されます。 -このパスは、まず現在のシークレットストレージとクロス署名IDの再利用を試み、明示的なbootstrap修復フローを実行しない限りクロス署名のリセットを避けます。 + 起動時には、現在の secret storage と cross-signing ID を再利用する保守的な crypto bootstrap パスも実行されます。bootstrap 状態が壊れている場合、OpenClaw は `channels.matrix.password` がなくても保護付き修復を試みます。homeserver が password UIA を要求する場合、起動時に警告をログ出力し、致命的エラーにはなりません。すでに owner-signed 済みのデバイスは保持されます。 -起動時にまだ壊れたbootstrap状態が見つかる場合、OpenClawは `channels.matrix.password` が設定されていなくても、保護された修復パスを試みることができます。 -homeserverがその修復にパスワードベースのUIAを必要とする場合、OpenClawは警告をログに記録し、botを中断するのではなく、起動を非致命的なまま維持します。 -現在のデバイスがすでにowner署名済みである場合、OpenClawはそのIDを自動的にリセットせず保持します。 + 完全なアップグレード手順については、[Matrix migration](/ja-JP/install/migrating-matrix) を参照してください。 -完全なアップグレードフロー、制限事項、復旧コマンド、一般的な移行メッセージについては、[Matrix migration](/ja-JP/install/migrating-matrix)を参照してください。 + -### 検証通知 + + Matrix は検証ライフサイクル通知を、厳格な DM 検証ルームへ `m.notice` メッセージとして投稿します。内容は request、ready（「Verify by emoji」の案内付き）、start/completion、および利用可能な場合の SAS（emoji/decimal）詳細です。 -Matrixは、検証ライフサイクル通知を厳格なDM検証ルームに `m.notice` メッセージとして直接投稿します。 -これには次が含まれます: + 別の Matrix クライアントからの受信リクエストは追跡され、自動承認されます。自己検証では、OpenClaw は emoji 検証が利用可能になると自動で SAS フローを開始し、自身の側を確認します。ただし、Matrix クライアント側で「They match」を比較して確認する必要があります。 -- 検証要求通知 -- 検証準備完了通知（明示的な「絵文字で検証」案内付き） -- 検証開始および完了通知 -- 利用可能な場合のSAS詳細（絵文字および10進数） + 検証システム通知は agent chat pipeline には転送されません。 -別のMatrixクライアントからの受信検証要求は、OpenClawによって追跡され、自動受諾されます。 -自己検証フローでは、絵文字検証が利用可能になるとOpenClawはSASフローも自動開始し、自身の側を確認します。 -別のMatrixユーザー/デバイスからの検証要求については、OpenClawは要求を自動受諾し、その後SASフローが通常どおり進むのを待ちます。 -検証を完了するには、引き続きMatrixクライアントで絵文字または10進数のSASを比較し、そこで「一致する」を確認する必要があります。 + -OpenClawは、自己開始の重複フローを無条件には自動受諾しません。自己検証要求がすでに保留中の場合、起動時には新しい要求の作成をスキップします。 - -検証プロトコル/システム通知はagentチャットパイプラインには転送されないため、`NO_REPLY` は生成されません。 - -### デバイス衛生 - -古いOpenClaw管理のMatrixデバイスがアカウントに蓄積し、暗号化ルームの信頼状態が把握しにくくなることがあります。 -次のコマンドで一覧表示します: + + OpenClaw 管理下の古いデバイスが蓄積することがあります。一覧表示と削除は次を使用します。 ```bash openclaw matrix devices list -``` - -古くなったOpenClaw管理デバイスを削除するには: - -```bash 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 は、IndexedDB shim として `fake-indexeddb` を使用する公式の `matrix-js-sdk` Rust crypto path を使用します。crypto state は `crypto-idb-snapshot.json` に永続化されます（制限されたファイル権限）。 -暗号化されたランタイム状態は、アカウントごと・ユーザーのトークンハッシュごとのルート配下、 -`~/.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`）が含まれます。 -トークンが変わってもアカウントIDが同じである場合、OpenClawはそのaccount/homeserver/userタプルに対して最適な既存ルートを再利用するため、以前のsync state、crypto state、thread bindings、 -およびstartup verification stateは引き続き見えるままです。 + 暗号化された実行時 state は `~/.openclaw/matrix/accounts//__//` 配下にあり、sync store、crypto store、recovery key、IDB snapshot、thread bindings、startup verification state を含みます。トークンが変わってもアカウント ID が同じ場合、OpenClaw は既存の最適な root を再利用するため、以前の state は引き続き参照できます。 + + + ## プロファイル管理 -選択したアカウントのMatrix self-profileを更新するには、次を実行します: +選択したアカウントの Matrix self-profile を更新するには、次を使用します。 ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -明示的に名前付きMatrixアカウントを対象にしたい場合は、`--account ` を追加してください。 +名前付き Matrix アカウントを明示的に対象にしたい場合は、`--account ` を追加します。 -Matrixは `mxc://` のavatar URLを直接受け付けます。`http://` または `https://` のavatar URLを渡した場合、OpenClawはまずそれをMatrixにアップロードし、解決された `mxc://` URLを `channels.matrix.avatarUrl`（または選択したアカウントのoverride）に書き戻します。 +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 conversation bindingsは引き続き `dm.sessionScope` より優先されるため、bind済みのルームとスレッドは選択された対象セッションを維持します。 -- `threadReplies: "off"` は、返信をトップレベルに維持し、受信したスレッド付きメッセージを親セッション上に維持します。 -- `threadReplies: "inbound"` は、受信メッセージがすでにそのスレッド内にある場合にのみ、そのスレッド内で返信します。 -- `threadReplies: "always"` は、ルーム返信をトリガーとなったメッセージをルートとするスレッド内に維持し、その会話を最初のトリガーメッセージから対応するthread-scoped session経由でルーティングします。 -- `dm.threadReplies` は、DMに対してのみトップレベル設定を上書きします。たとえば、ルームスレッドは分離したまま、DMはフラットに保てます。 -- 受信したスレッド付きメッセージには、追加のagentコンテキストとしてスレッドルートメッセージが含まれます。 -- Message-tool送信は、対象が同じルーム、または同じDM user targetである場合、明示的な `threadId` が指定されていなければ、現在のMatrixスレッドを自動継承します。 -- 同一セッションでのDM user target再利用は、現在のセッションメタデータが同じMatrixアカウント上の同じDM相手を証明している場合にのみ有効です。そうでない場合、OpenClawは通常のuser-scoped routingにフォールバックします。 -- OpenClawが、あるMatrix DMルームが同じ共有Matrix DM session上の別のDMルームと衝突していることを検出すると、thread bindingsが有効で `dm.sessionScope` のヒントがある場合、そのルームに1回限りの `m.notice` を `/focus` エスケープハッチ付きで投稿します。 -- Matrixではランタイムthread bindingsがサポートされます。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびスレッドにbindされた `/acp spawn` は、MatrixルームとDMで動作します。 -- トップレベルのMatrixルーム/DMでの `/focus` は、`threadBindings.spawnSubagentSessions=true` の場合、新しいMatrixスレッドを作成し、それを対象セッションにbindします。 -- 既存のMatrixスレッド内で `/focus` または `/acp spawn --thread here` を実行した場合は、代わりにその現在のスレッドをbindします。 +- `dm.sessionScope: "per-user"`（デフォルト）は Matrix DM ルーティングを送信者スコープで維持するため、同じ相手に解決される複数の DM ルームが 1 つのセッションを共有できます。 +- `dm.sessionScope: "per-room"` は、通常の DM 認証と allowlist チェックを使用しつつ、各 Matrix DM ルームを独自のセッションキーに分離します。 +- 明示的な Matrix conversation bindings は引き続き `dm.sessionScope` より優先されるため、bind 済みのルームとスレッドは選択された対象セッションを維持します。 +- `threadReplies: "off"` は返信をトップレベルに保ち、受信したスレッドメッセージを親セッション上に維持します。 +- `threadReplies: "inbound"` は、受信メッセージがすでにそのスレッド内にある場合にのみ、スレッド内で返信します。 +- `threadReplies: "always"` は、トリガーとなったメッセージをルートとするスレッド内にルーム返信を維持し、その会話を最初のトリガーメッセージから対応する thread-scoped session にルーティングします。 +- `dm.threadReplies` は、DM に対してのみトップレベル設定を上書きします。たとえば、ルームスレッドは分離したまま、DM はフラットに保てます。 +- 受信したスレッドメッセージには、追加の agent context としてスレッドルートメッセージが含まれます。 +- Message-tool 送信は、明示的な `threadId` が指定されていない限り、対象が同じルーム、または同じ DM ユーザー対象である場合、自動的に現在の Matrix スレッドを継承します。 +- 同一セッションの DM ユーザー対象再利用は、現在のセッション metadata が同じ Matrix アカウント上の同じ DM peer であることを証明する場合にのみ有効です。そうでない場合、OpenClaw は通常のユーザースコープルーティングにフォールバックします。 +- OpenClaw が、Matrix DM ルームが同じ共有 Matrix DM セッション上の別の DM ルームと衝突していることを検出した場合、thread bindings が有効で `dm.sessionScope` ヒントがあると、そのルームに `/focus` エスケープハッチ付きの一度限りの `m.notice` を投稿します。 +- 実行時 thread bindings は Matrix でサポートされています。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、および thread-bound `/acp spawn` は Matrix ルームと DM で動作します。 +- トップレベルの Matrix ルーム/DM での `/focus` は、`threadBindings.spawnSubagentSessions=true` のとき、新しい Matrix スレッドを作成し、それを対象セッションに bind します。 +- 既存の Matrix スレッド内で `/focus` または `/acp spawn --thread here` を実行すると、代わりにその現在のスレッドが bind されます。 -## ACP会話bindings +## ACP conversation bindings -Matrixルーム、DM、および既存のMatrixスレッドは、チャットの見た目を変えずに永続的なACP workspaceに変換できます。 +Matrix ルーム、DM、および既存の Matrix スレッドは、チャット surface を変更せずに永続的な ACP workspace にできます。 -高速なオペレーターフロー: +高速な operator フロー: -- 使い続けたいMatrix DM、ルーム、または既存スレッドの中で `/acp spawn codex --bind here` を実行します。 -- トップレベルのMatrix DMまたはルームでは、現在のDM/ルームがそのままチャット画面として維持され、以後のメッセージは生成されたACP sessionにルーティングされます。 -- 既存のMatrixスレッド内では、`--bind here` はその現在のスレッドをその場でbindします。 -- `/new` と `/reset` は、同じbind済みACP sessionをその場でリセットします。 -- `/acp close` はACP sessionを閉じてbindingを解除します。 +- 使い続けたい Matrix DM、ルーム、または既存スレッド内で `/acp spawn codex --bind here` を実行します。 +- トップレベルの Matrix DM またはルームでは、現在の DM/ルームがそのまま chat surface となり、以後のメッセージは生成された ACP セッションにルーティングされます。 +- 既存の Matrix スレッド内では、`--bind here` はその現在のスレッドをその場で bind します。 +- `/new` と `/reset` は、同じ bind 済み ACP セッションをその場でリセットします。 +- `/acp close` は ACP セッションを閉じて binding を削除します。 -注記: +注意: -- `--bind here` は子Matrixスレッドを作成しません。 -- `threadBindings.spawnAcpSessions` が必要なのは `/acp spawn --thread auto|here` の場合だけで、このときOpenClawは子Matrixスレッドを作成またはbindする必要があります。 +- `--bind here` は子 Matrix スレッドを作成しません。 +- `threadBindings.spawnAcpSessions` は `/acp spawn --thread auto|here` にのみ必要です。この場合、OpenClaw は子 Matrix スレッドを作成または bind する必要があります。 -### スレッドbinding設定 +### スレッド binding 設定 -Matrixは `session.threadBindings` からグローバルデフォルトを継承し、channelごとのoverrideもサポートします: +Matrix は `session.threadBindings` からグローバルデフォルトを継承し、channel ごとの override もサポートします。 - `threadBindings.enabled` - `threadBindings.idleHours` @@ -733,35 +474,35 @@ Matrixは `session.threadBindings` からグローバルデフォルトを継承 - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Matrixのスレッドbind付きspawnフラグはオプトインです: +Matrix の thread-bound spawn フラグはオプトインです。 -- トップレベルの `/focus` が新しいMatrixスレッドを作成してbindできるようにするには、`threadBindings.spawnSubagentSessions: true` を設定します。 -- `/acp spawn --thread auto|here` がACP sessionsをMatrixスレッドにbindできるようにするには、`threadBindings.spawnAcpSessions: true` を設定します。 +- トップレベルの `/focus` で新しい Matrix スレッドの作成と bind を許可するには、`threadBindings.spawnSubagentSessions: true` を設定します。 +- `/acp spawn --thread auto|here` が ACP セッションを Matrix スレッドに bind できるようにするには、`threadBindings.spawnAcpSessions: true` を設定します。 ## リアクション -Matrixは、送信リアクションアクション、受信リアクション通知、および受信ack reactionsをサポートしています。 +Matrix は、送信リアクションアクション、受信リアクション通知、および受信 ack リアクションをサポートします。 -- 送信リアクションtoolingは `channels["matrix"].actions.reactions` によって制御されます。 -- `react` は特定のMatrix eventにリアクションを追加します。 -- `reactions` は特定のMatrix eventの現在のリアクション要約を一覧表示します。 -- `emoji=""` は、そのevent上のbotアカウント自身のリアクションを削除します。 -- `remove: true` は、botアカウントの指定した絵文字リアクションのみを削除します。 +- 送信リアクション tooling は `channels["matrix"].actions.reactions` によって制御されます。 +- `react` は特定の Matrix event にリアクションを追加します。 +- `reactions` は特定の Matrix event に対する現在のリアクション要約を一覧表示します。 +- `emoji=""` は、その event 上の bot アカウント自身のリアクションを削除します。 +- `remove: true` は、bot アカウントから指定した emoji リアクションのみを削除します。 -Ack reactionsは、標準のOpenClaw解決順序を使用します: +Ack リアクションは、標準の OpenClaw 解決順序を使用します。 - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- agent identity絵文字フォールバック +- agent ID の emoji フォールバック -Ack reactionのスコープは次の順序で解決されます: +Ack リアクションスコープは次の順で解決されます。 - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -リアクション通知モードは次の順序で解決されます: +リアクション通知モードは次の順で解決されます。 - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` @@ -769,30 +510,30 @@ Ack reactionのスコープは次の順序で解決されます: 動作: -- `reactionNotifications: "own"` は、botが作成したMatrixメッセージを対象とする追加された `m.reaction` eventsを転送します。 -- `reactionNotifications: "off"` は、リアクションのsystem eventsを無効にします。 -- リアクション削除はsystem eventsとして合成されません。Matrixではそれらは独立した `m.reaction` 削除ではなくredactionsとして表現されるためです。 +- `reactionNotifications: "own"` は、bot が作成した Matrix メッセージを対象にした `m.reaction` event の追加を転送します。 +- `reactionNotifications: "off"` はリアクション system events を無効にします。 +- リアクション削除は、Matrix ではそれらが独立した `m.reaction` 削除ではなく redactions として扱われるため、system events には合成されません。 ## 履歴コンテキスト -- `channels.matrix.historyLimit` は、Matrixルームメッセージがagentをトリガーしたときに `InboundHistory` として含める最近のルームメッセージ数を制御します。`messages.groupChat.historyLimit` にフォールバックし、両方とも未設定の場合の実効デフォルトは `0` です。無効にするには `0` を設定します。 -- Matrixルーム履歴はルーム専用です。DMは引き続き通常のセッション履歴を使用します。 -- Matrixルーム履歴は保留中のみです。OpenClawはまだ返信をトリガーしていないルームメッセージをバッファし、メンションやその他のトリガーが来たときにそのウィンドウをスナップショットします。 -- 現在のトリガーメッセージは `InboundHistory` に含まれません。そのturnのメインの受信本文に残ります。 -- 同じMatrix eventの再試行では、より新しいルームメッセージへ前進してしまうことなく、元の履歴スナップショットを再利用します。 +- `channels.matrix.historyLimit` は、Matrix ルームメッセージが agent をトリガーしたときに `InboundHistory` として含める最近のルームメッセージ数を制御します。`messages.groupChat.historyLimit` にフォールバックし、両方とも未設定の場合の実効デフォルトは `0` です。無効にするには `0` を設定します。 +- Matrix ルーム履歴はルーム専用です。DM は引き続き通常のセッション履歴を使用します。 +- Matrix ルーム履歴は pending-only です。OpenClaw はまだ返信をトリガーしていないルームメッセージをバッファし、メンションやその他のトリガーが到着したときにそのウィンドウをスナップショットします。 +- 現在のトリガーメッセージは `InboundHistory` には含まれません。そのターンのメインの受信本文に残ります。 +- 同じ Matrix event の再試行では、新しいルームメッセージへずれていくのではなく、元の履歴スナップショットを再利用します。 ## コンテキスト可視性 -Matrixは、取得した返信テキスト、スレッドルート、保留中履歴などの補助的なルームコンテキストに対して、共有の `contextVisibility` 制御をサポートします。 +Matrix は、取得した返信テキスト、スレッドルート、pending history などの補足ルームコンテキストに対して、共有の `contextVisibility` 制御をサポートします。 -- `contextVisibility: "all"` がデフォルトです。補助コンテキストは受信したまま保持されます。 -- `contextVisibility: "allowlist"` は、アクティブなルーム/ユーザー許可リストチェックで許可された送信者に補助コンテキストを絞り込みます。 -- `contextVisibility: "allowlist_quote"` は `allowlist` と同様に動作しますが、1つの明示的な引用返信は保持します。 +- `contextVisibility: "all"` がデフォルトです。補足コンテキストは受信したまま保持されます。 +- `contextVisibility: "allowlist"` は、アクティブなルーム/ユーザー allowlist チェックで許可された送信者に、補足コンテキストを絞り込みます。 +- `contextVisibility: "allowlist_quote"` は `allowlist` と同様に動作しますが、1 件の明示的な引用返信は保持します。 -この設定は補助コンテキストの可視性に影響し、受信メッセージ自体が返信をトリガーできるかどうかには影響しません。 -トリガーの認可は引き続き `groupPolicy`、`groups`、`groupAllowFrom`、およびDM policy設定から行われます。 +この設定は補足コンテキストの可視性に影響するものであり、受信メッセージ自体が返信をトリガーできるかどうかには影響しません。 +トリガーの認可は引き続き `groupPolicy`、`groups`、`groupAllowFrom`、および DM policy 設定から決まります。 -## DMとルームのポリシー +## DM とルームポリシー ```json5 { @@ -815,78 +556,78 @@ Matrixは、取得した返信テキスト、スレッドルート、保留中 } ``` -メンション制限と許可リストの動作については、[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はライブDMではなく古いソロルームを指す古い `m.direct` マッピングを持ってしまうことがあります。相手に対する現在のマッピングを確認するには、次を実行します: +ダイレクトメッセージ state が同期ずれを起こすと、OpenClaw は、ライブ DM ではなく古い 1 対 1 ルームを指す stale な `m.direct` マッピングを持つことがあります。相手の現在のマッピングを確認するには、次を実行します。 ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -修復するには: +修復するには、次を実行します。 ```bash 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 approvals -Matrixは、Matrixアカウント用のネイティブapproval clientとして機能できます。ネイティブの -DM/channel routing knobsは、引き続きexec approval設定配下にあります: +Matrix は、Matrix アカウント向けのネイティブ承認クライアントとして動作できます。ネイティブの +DM/channel ルーティング設定は、引き続き exec approval config 配下にあります。 - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers`（任意。`channels.matrix.dm.allowFrom` にフォールバック） +- `channels.matrix.execApprovals.approvers`（任意。`channels.matrix.dm.allowFrom` にフォールバックします） - `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -承認者は `@owner:example.org` のようなMatrix user IDである必要があります。`enabled` が未設定または `"auto"` で、少なくとも1人の承認者を解決できる場合、Matrixはネイティブapprovalを自動有効化します。Exec approvalsはまず `execApprovals.approvers` を使用し、`channels.matrix.dm.allowFrom` にフォールバックできます。Plugin approvalsは `channels.matrix.dm.allowFrom` を通じて認可されます。Matrixをネイティブapproval clientとして明示的に無効にするには、`enabled: false` を設定してください。それ以外の場合、approval requestsは他の設定済みapproval routesまたはapproval fallback policyにフォールバックします。 +承認者は `@owner:example.org` のような Matrix ユーザー ID である必要があります。`enabled` が未設定または `"auto"` で、少なくとも 1 人の承認者を解決できる場合、Matrix はネイティブ承認を自動有効化します。Exec approvals は最初に `execApprovals.approvers` を使用し、`channels.matrix.dm.allowFrom` にフォールバックできます。Plugin approvals は `channels.matrix.dm.allowFrom` を通じて認可されます。Matrix をネイティブ承認クライアントとして明示的に無効化するには、`enabled: false` を設定します。それ以外の場合、承認リクエストは他の設定済み承認ルートまたは承認フォールバックポリシーにフォールバックします。 -Matrixネイティブルーティングは両方のapproval種別をサポートします: +Matrix のネイティブルーティングは、両方の承認種別をサポートします。 -- `channels.matrix.execApprovals.*` は、Matrix approval promptsのネイティブDM/channel fanoutモードを制御します。 -- Exec approvalsは、`execApprovals.approvers` または `channels.matrix.dm.allowFrom` からのexec approverセットを使用します。 -- Plugin approvalsは、`channels.matrix.dm.allowFrom` のMatrix DM許可リストを使用します。 -- Matrixのリアクションショートカットとメッセージ更新は、exec approvalsとplugin approvalsの両方に適用されます。 +- `channels.matrix.execApprovals.*` は、Matrix 承認プロンプトのネイティブ DM/channel ファンアウトモードを制御します。 +- Exec approvals は、`execApprovals.approvers` または `channels.matrix.dm.allowFrom` からの exec 承認者セットを使用します。 +- Plugin approvals は、`channels.matrix.dm.allowFrom` からの Matrix DM allowlist を使用します。 +- Matrix リアクションショートカットとメッセージ更新は、exec approvals と plugin approvals の両方に適用されます。 配信ルール: -- `target: "dm"` は、approval promptsを承認者DMへ送信します -- `target: "channel"` は、プロンプトを元のMatrixルームまたはDMへ送り返します -- `target: "both"` は、承認者DMと元のMatrixルームまたはDMの両方へ送信します +- `target: "dm"` は承認プロンプトを承認者 DM に送信します +- `target: "channel"` はプロンプトを元の Matrix ルームまたは DM に送り返します +- `target: "both"` は承認者 DM と元の Matrix ルームまたは DM の両方に送信します -Matrix approval promptsは、主要なapproval message上にリアクションショートカットを設定します: +Matrix 承認プロンプトは、主要な承認メッセージにリアクションショートカットを設定します。 -- `✅` = 今回のみ許可 +- `✅` = 1 回だけ許可 - `❌` = 拒否 -- `♾️` = 実効exec policyでその判断が許可されている場合は常に許可 +- `♾️` = 実効 exec policy でその判断が許可されている場合に常に許可 -承認者は、そのメッセージにリアクションするか、フォールバックのスラッシュコマンド `/approve allow-once`、`/approve allow-always`、または `/approve deny` を使えます。 +承認者はそのメッセージにリアクションするか、フォールバックのスラッシュコマンド `/approve allow-once`、`/approve allow-always`、または `/approve deny` を使用できます。 -承認または拒否できるのは、解決済みの承認者だけです。exec approvalsでは、channel配信にはコマンドテキストが含まれるため、`channel` または `both` は信頼できるルームでのみ有効にしてください。 +承認または拒否できるのは、解決済み承認者だけです。Exec approvals では channel 配信にコマンドテキストが含まれるため、`channel` または `both` は信頼できるルームでのみ有効にしてください。 -アカウントごとのoverride: +アカウント単位の override: - `channels.matrix.accounts..execApprovals` @@ -894,9 +635,9 @@ Matrix approval promptsは、主要なapproval message上にリアクション ## スラッシュコマンド -Matrixのスラッシュコマンド（たとえば `/new`、`/reset`、`/model`）はDMで直接動作します。ルームでは、OpenClawはボット自身のMatrixメンションを前置したスラッシュコマンドも認識するため、`@bot:server /new` はカスタムのメンション正規表現を必要とせずにコマンドパスをトリガーします。これにより、ユーザーがコマンド入力前にタブ補完でボットを指定したときにElementなどのクライアントが送信する、ルーム形式の `@mention /command` 投稿にもボットが反応し続けられます。 +Matrix のスラッシュコマンド（たとえば `/new`、`/reset`、`/model`）は DM で直接動作します。ルームでは、OpenClaw はボット自身の Matrix メンションが前置されたスラッシュコマンドも認識するため、`@bot:server /new` はカスタムメンション regex を必要とせずにコマンドパスをトリガーします。これにより、Element や類似クライアントで、ユーザーがコマンド入力前にボットをタブ補完したときに送信されるルーム形式の `@mention /command` 投稿にも、ボットが応答できるようになります。 -認可ルールは引き続き適用されます。コマンド送信者は、通常のメッセージと同様にDMまたはルームの許可リスト/ownerポリシーを満たす必要があります。 +認可ルールは引き続き適用されます。コマンド送信者は、通常メッセージと同様に DM またはルームの allowlist/owner policy を満たす必要があります。 ## マルチアカウント @@ -928,25 +669,25 @@ Matrixのスラッシュコマンド（たとえば `/new`、`/reset`、`/model` } ``` -トップレベルの `channels.matrix` の値は、アカウント側で上書きされない限り、名前付きアカウントのデフォルトとして機能します。 -継承されたルームエントリーを1つのMatrixアカウントに限定するには `groups..account` を使います。 -`account` を持たないエントリーはすべてのMatrixアカウント間で共有されたままとなり、`account: "default"` を持つエントリーも、デフォルトアカウントがトップレベルの `channels.matrix.*` に直接設定されている場合は引き続き機能します。 -共有された部分的な認証デフォルトだけでは、それ自体で別個の暗黙のデフォルトアカウントは作成されません。OpenClawがトップレベルの `default` アカウントを合成するのは、そのデフォルトに新しい認証情報（`homeserver` + `accessToken`、または `homeserver` + `userId` と `password`）がある場合のみです。名前付きアカウントは、後でキャッシュ済み認証情報が認証を満たす場合、`homeserver` + `userId` からでも引き続き検出可能です。 -Matrixにすでにちょうど1つの名前付きアカウントがある場合、または `defaultAccount` が既存の名前付きアカウントキーを指している場合、単一アカウントからマルチアカウントへの修復/セットアップ昇格では、新しい `accounts.default` エントリーを作る代わりにそのアカウントが保持されます。昇格されたアカウントに移動するのはMatrixの認証/bootstrapキーだけで、共有の配信ポリシーキーはトップレベルに残ります。 -暗黙的なルーティング、probe、CLI操作でOpenClawに特定の名前付きMatrixアカウントを優先させたい場合は、`defaultAccount` を設定してください。 -複数のMatrixアカウントが設定されていて、そのうち1つのアカウントidが `default` である場合、`defaultAccount` が未設定でもOpenClawはそのアカウントを暗黙的に使用します。 -複数の名前付きアカウントを設定する場合は、暗黙的なアカウント選択に依存する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 の auth/bootstrap キーだけであり、共有配信ポリシーキーはトップレベルに残ります。 +暗黙的ルーティング、プローブ、および CLI 操作で OpenClaw に 1 つの名前付き Matrix アカウントを優先させたい場合は、`defaultAccount` を設定してください。 +複数の Matrix アカウントが設定されていて、アカウント ID の 1 つが `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 -デフォルトでは、OpenClawはSSRF保護のため、プライベート/内部Matrix homeserverへの接続をブロックします。アカウントごとに -明示的にオプトインした場合のみ許可されます。 +デフォルトでは、OpenClaw は SSRF 保護のため、アカウントごとに +明示的にオプトインしない限り、プライベート/内部 Matrix homeserver をブロックします。 -homeserverがlocalhost、LAN/Tailscale IP、または内部ホスト名で動作している場合は、 -そのMatrixアカウントで `network.dangerouslyAllowPrivateNetwork` を有効にしてください: +homeserver が localhost、LAN/Tailscale IP、または内部ホスト名で動作している場合は、 +その Matrix アカウントに対して `network.dangerouslyAllowPrivateNetwork` を有効にしてください。 ```json5 { @@ -962,7 +703,7 @@ homeserverがlocalhost、LAN/Tailscale IP、または内部ホスト名で動作 } ``` -CLIセットアップ例: +CLI セットアップ例: ```bash openclaw matrix account add \ @@ -972,12 +713,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -このオプトインで許可されるのは、信頼されたプライベート/内部ターゲットのみです。`http://matrix.example.org:8008` のような -公開プレーンテキストhomeserverは引き続きブロックされます。可能な限り `https://` を使用してください。 +このオプトインは、信頼されたプライベート/内部ターゲットのみを許可します。 +`http://matrix.example.org:8008` のような公開プレーンテキスト homeserver は引き続きブロックされます。可能な限り `https://` を使用してください。 -## Matrixトラフィックのプロキシ +## Matrix トラフィックのプロキシ -Matrixデプロイで明示的な送信HTTP(S)プロキシが必要な場合は、`channels.matrix.proxy` を設定してください: +Matrix デプロイメントで明示的な送信 HTTP(S) プロキシが必要な場合は、`channels.matrix.proxy` を設定します。 ```json5 { @@ -991,86 +732,86 @@ Matrixデプロイで明示的な送信HTTP(S)プロキシが必要な場合は } ``` -名前付きアカウントは、`channels.matrix.accounts..proxy` でトップレベルのデフォルトを上書きできます。 -OpenClawは、ランタイムのMatrixトラフィックとアカウント状態probeの両方に同じプロキシ設定を使用します。 +名前付きアカウントは、`channels.matrix.accounts..proxy` でトップレベルのデフォルトを override できます。 +OpenClaw は、実行時の Matrix トラフィックとアカウントステータスプローブの両方で同じプロキシ設定を使用します。 ## ターゲット解決 -Matrixは、OpenClawがルームまたはユーザーターゲットを求めるあらゆる場所で、次のターゲット形式を受け付けます: +OpenClaw がルームまたはユーザーのターゲット指定を求める箇所では、Matrix は次のターゲット形式を受け付けます。 - ユーザー: `@user:server`、`user:@user:server`、または `matrix:user:@user:server` - ルーム: `!room:server`、`room:!room:server`、または `matrix:room:!room:server` - エイリアス: `#alias:server`、`channel:#alias:server`、または `matrix:channel:#alias:server` -ライブディレクトリ参照は、ログイン中のMatrixアカウントを使用します: +ライブディレクトリ検索は、ログイン済み Matrix アカウントを使用します。 -- ユーザー参照は、そのhomeserver上のMatrix user directoryに問い合わせます。 -- ルーム参照は、明示的なルームIDとエイリアスを直接受け付け、その後、そのアカウントの参加済みルーム名の検索にフォールバックします。 -- 参加済みルーム名の参照はベストエフォートです。ルーム名をIDまたはエイリアスに解決できない場合、ランタイムの許可リスト解決では無視されます。 +- ユーザー検索は、その homeserver 上の Matrix user directory を問い合わせます。 +- ルーム検索は、明示的なルーム ID とエイリアスを直接受け付け、その後そのアカウントで参加中のルーム名検索にフォールバックします。 +- 参加中ルーム名の検索はベストエフォートです。ルーム名を ID またはエイリアスに解決できない場合、実行時 allowlist 解決では無視されます。 ## 設定リファレンス -- `enabled`: channelを有効または無効にします。 -- `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` でトップレベルデフォルトを上書きできます。 -- `userId`: 完全なMatrix user ID。例: `@bot:example.org`。 -- `accessToken`: トークンベース認証用のアクセストークン。プレーンテキスト値とSecretRef値は、env/file/exec providers全体で `channels.matrix.accessToken` および `channels.matrix.accounts..accessToken` に対応しています。詳しくは [Secrets Management](/ja-JP/gateway/secrets) を参照してください。 -- `password`: パスワードベースログイン用パスワード。プレーンテキスト値とSecretRef値に対応しています。 -- `deviceId`: 明示的なMatrix device ID。 +- `enabled`: channel を有効または無効にします。 +- `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` でトップレベルのデフォルトを override できます。 +- `userId`: 完全な Matrix ユーザー ID。たとえば `@bot:example.org`。 +- `accessToken`: トークンベース認証用のアクセストークンです。平文値と SecretRef 値は、env/file/exec provider 全体で `channels.matrix.accessToken` および `channels.matrix.accounts..accessToken` に対応しています。[Secrets Management](/ja-JP/gateway/secrets) を参照してください。 +- `password`: パスワードベースログイン用のパスワードです。平文値と SecretRef 値に対応しています。 +- `deviceId`: 明示的な Matrix デバイス ID。 - `deviceName`: パスワードログイン用のデバイス表示名。 -- `avatarUrl`: プロファイル同期および `profile set` 更新用に保存されるself-avatar URL。 -- `initialSyncLimit`: 起動時syncで取得するeventの最大数。 -- `encryption`: E2EEを有効にします。 -- `allowlistOnly`: `true` の場合、`open` ルームポリシーを `allowlist` に引き上げ、`disabled` 以外のすべてのアクティブなDMポリシー（`pairing` と `open` を含む）を `allowlist` に強制します。`disabled` ポリシーには影響しません。 -- `allowBots`: 他の設定済みOpenClaw Matrixアカウントからのメッセージを許可します（`true` または `"mentions"`）。 +- `avatarUrl`: プロファイル同期と `profile set` 更新用に保存される self-avatar URL。 +- `initialSyncLimit`: 起動時 sync 中に取得するイベントの最大数。 +- `encryption`: E2EE を有効にします。 +- `allowlistOnly`: `true` の場合、`open` ルーム policy を `allowlist` に引き上げ、`disabled` 以外のすべてのアクティブな DM policy（`pairing` と `open` を含む）を `allowlist` に強制します。`disabled` policy には影響しません。 +- `allowBots`: 他の設定済み OpenClaw Matrix アカウントからのメッセージを許可します（`true` または `"mentions"`）。 - `groupPolicy`: `open`、`allowlist`、または `disabled`。 -- `contextVisibility`: 補助的なルームコンテキストの可視性モード（`all`、`allowlist`、`allowlist_quote`）。 -- `groupAllowFrom`: ルームトラフィック用のユーザーID許可リスト。完全なMatrix user IDが最も安全です。厳密なディレクトリ一致は、起動時およびmonitor実行中に許可リストが変更されたときに解決されます。未解決の名前は無視されます。 +- `contextVisibility`: 補足ルームコンテキストの可視性モード（`all`、`allowlist`、`allowlist_quote`）。 +- `groupAllowFrom`: ルームトラフィック用のユーザー ID allowlist。完全な Matrix ユーザー ID が最も安全です。完全一致のディレクトリ解決は起動時、および monitor 実行中に allowlist が変更されたときに行われます。未解決の名前は無視されます。 - `historyLimit`: グループ履歴コンテキストとして含めるルームメッセージの最大数。`messages.groupChat.historyLimit` にフォールバックし、両方とも未設定の場合の実効デフォルトは `0` です。無効にするには `0` を設定します。 - `replyToMode`: `off`、`first`、`all`、または `batched`。 -- `markdown`: 送信Matrixテキスト用の任意のMarkdownレンダリング設定。 -- `streaming`: `off`（デフォルト）、`"partial"`、`"quiet"`、`true`、または `false`。`"partial"` と `true` は、通常のMatrixテキストメッセージによるプレビュー先行の下書き更新を有効にします。`"quiet"` は、セルフホストpush-rule構成向けに通知しないプレビュー通知を使います。`false` は `"off"` と同等です。 -- `blockStreaming`: `true` は、下書きプレビューストリーミングが有効な間、完了したassistant blockごとに個別の進捗メッセージを有効にします。 +- `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されたセッションルーティングとライフサイクルに対するchannelごとのoverride。 -- `startupVerification`: 起動時の自動自己検証要求モード（`if-unverified`、`off`）。 -- `startupVerificationCooldownHours`: 自動起動時検証要求の再試行前クールダウン。 -- `textChunkLimit`: 送信メッセージの文字数ベースchunkサイズ（`chunkMode` が `length` の場合に適用）。 -- `chunkMode`: `length` は文字数でメッセージを分割し、`newline` は改行境界で分割します。 -- `responsePrefix`: このchannelのすべての送信返信の先頭に付ける任意の文字列。 -- `ackReaction`: このchannel/アカウント用の任意のack reaction override。 -- `ackReactionScope`: 任意のack reactionスコープoverride（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 +- `threadBindings`: thread-bound session ルーティングとライフサイクル用の channel 単位 override。 +- `startupVerification`: 起動時の自動自己検証リクエストモード（`if-unverified`、`off`）。 +- `startupVerificationCooldownHours`: 自動起動時検証リクエストを再試行するまでのクールダウン。 +- `textChunkLimit`: 文字数単位の送信メッセージ chunk サイズ（`chunkMode` が `length` の場合に適用）。 +- `chunkMode`: `length` は文字数でメッセージを分割し、`newline` は行境界で分割します。 +- `responsePrefix`: この channel のすべての送信返信の先頭に付ける任意の文字列。 +- `ackReaction`: この channel/account 用の任意の 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`: DMトラフィック用のユーザーID許可リスト。完全なMatrix user IDが最も安全です。厳密なディレクトリ一致は、起動時およびmonitor実行中に許可リストが変更されたときに解決されます。未解決の名前は無視されます。 -- `dm.sessionScope`: `per-user`（デフォルト）または `per-room`。相手が同じでも各Matrix DMルームで別々のコンテキストを維持したい場合は `per-room` を使用します。 -- `dm.threadReplies`: DM専用のスレッドポリシーoverride（`off`、`inbound`、`always`）。DMにおける返信配置とセッション分離の両方について、トップレベルの `threadReplies` 設定を上書きします。 -- `execApprovals`: Matrixネイティブのexec approval配信（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 -- `execApprovals.approvers`: exec requestを承認できるMatrix user ID。`dm.allowFrom` がすでに承認者を特定している場合は任意です。 +- `mediaMaxMb`: 送信時と受信メディア処理時のメディアサイズ上限（MB）。 +- `autoJoin`: 招待自動参加 policy（`always`、`allowlist`、`off`）。デフォルト: `off`。DM スタイルの招待を含むすべての Matrix 招待に適用されます。 +- `autoJoinAllowlist`: `autoJoin` が `allowlist` のときに許可されるルーム/エイリアス。エイリアスエントリは招待処理中にルーム ID に解決されます。OpenClaw は、招待されたルームが主張するエイリアス state を信用しません。 +- `dm`: DM policy ブロック（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 +- `dm.policy`: OpenClaw がルームに参加し、それを DM と分類した後の DM アクセスを制御します。招待を自動参加するかどうかは変更しません。 +- `dm.allowFrom`: DM トラフィック用のユーザー ID allowlist。完全な Matrix ユーザー ID が最も安全です。完全一致のディレクトリ解決は起動時、および monitor 実行中に allowlist が変更されたときに行われます。未解決の名前は無視されます。 +- `dm.sessionScope`: `per-user`（デフォルト）または `per-room`。相手が同じでも各 Matrix DM ルームで別々のコンテキストを維持したい場合は `per-room` を使用します。 +- `dm.threadReplies`: DM 専用のスレッド policy override（`off`、`inbound`、`always`）。DM における返信配置と session 分離の両方について、トップレベルの `threadReplies` 設定を override します。 +- `execApprovals`: Matrix ネイティブの exec approval 配信（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 +- `execApprovals.approvers`: exec リクエストを承認できる Matrix ユーザー ID。`dm.allowFrom` がすでに承認者を特定している場合は任意です。 - `execApprovals.target`: `dm | channel | both`（デフォルト: `dm`）。 -- `accounts`: 名前付きのアカウントごとのoverride。トップレベルの `channels.matrix` 値は、これらのエントリーのデフォルトとして機能します。 -- `groups`: ルームごとのポリシーマップ。ルームIDまたはエイリアスを推奨します。未解決のルーム名はランタイムで無視されます。セッション/グループIDは、解決後の安定したルームIDを使用します。 -- `groups..account`: マルチアカウント構成で、継承された1つのルームエントリーを特定のMatrixアカウントに制限します。 -- `groups..allowBots`: 設定済みbot送信者に対するルームレベルoverride（`true` または `"mentions"`）。 -- `groups..users`: ルームごとの送信者許可リスト。 -- `groups..tools`: ルームごとのtool許可/拒否override。 -- `groups..autoReply`: ルームレベルのメンション制限override。`true` はそのルームのメンション必須を無効化し、`false` は再び有効化します。 -- `groups..skills`: 任意のルームレベルskillフィルター。 -- `groups..systemPrompt`: 任意のルームレベルsystem promptスニペット。 -- `rooms`: `groups` のレガシーエイリアス。 -- `actions`: アクションごとのtool制御（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 +- `accounts`: 名前付きのアカウント単位 override。トップレベルの `channels.matrix` 値は、これらのエントリのデフォルトとして機能します。 +- `groups`: ルーム単位の policy map。ルーム ID またはエイリアスを推奨します。未解決のルーム名は実行時に無視されます。session/group ID は解決後の安定したルーム ID を使用します。 +- `groups..account`: マルチアカウント構成で、1 つの継承ルームエントリを特定の Matrix アカウントに限定します。 +- `groups..allowBots`: 設定済み bot 送信者に対するルームレベル override（`true` または `"mentions"`）。 +- `groups..users`: ルーム単位の送信者 allowlist。 +- `groups..tools`: ルーム単位の tools 許可/拒否 override。 +- `groups..autoReply`: ルームレベルのメンションゲート override。`true` はそのルームでメンション要件を無効にし、`false` は再び有効にします。 +- `groups..skills`: 任意のルームレベル skill filter。 +- `groups..systemPrompt`: 任意のルームレベル system prompt スニペット。 +- `rooms`: `groups` の従来エイリアス。 +- `actions`: アクション単位の tool 制御（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 ## 関連 -- [Channels Overview](/ja-JP/channels) — サポートされているすべてのchannel -- [Pairing](/ja-JP/channels/pairing) — DM認証とペアリングフロー -- [Groups](/ja-JP/channels/groups) — グループチャットの動作とメンション制限 -- [Channel Routing](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング +- [Channels Overview](/ja-JP/channels) — サポートされているすべての channel +- [Pairing](/ja-JP/channels/pairing) — DM 認証と pairing フロー +- [Groups](/ja-JP/channels/groups) — グループチャットの動作とメンションゲート +- [Channel Routing](/ja-JP/channels/channel-routing) — メッセージの session ルーティング - [Security](/ja-JP/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/ci.md b/docs/ja-JP/ci.md index 063db43ac..ecc48a489 100644 --- a/docs/ja-JP/ci.md +++ b/docs/ja-JP/ci.md @@ -1,107 +1,108 @@ --- read_when: - - CI ジョブが実行された、または実行されなかった理由を理解する必要がある - - 失敗している GitHub Actions チェックをデバッグしている -summary: CI ジョブグラフ、スコープゲート、および対応するローカルコマンド + - CI ジョブが実行された、または実行されなかった理由を把握する必要があります + - 失敗している GitHub Actions チェックをデバッグしています +summary: CI ジョブグラフ、スコープゲート、およびローカルコマンドの同等物 title: CI パイプライン x-i18n: - generated_at: "2026-04-23T14:00:04Z" + generated_at: "2026-04-23T15:00:49Z" model: gpt-5.4 provider: openai - source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f + source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d source_path: ci.md workflow: 15 --- # CI パイプライン -CI は `main` へのすべての push とすべての pull request で実行されます。スマートなスコープ判定を使用しており、変更が無関係な領域だけの場合は高コストのジョブをスキップします。 +CI は `main` へのすべての push とすべての pull request で実行されます。スマートスコープを使用しており、変更が無関係な領域だけに限られる場合は高コストなジョブをスキップします。 -QA Lab には、メインのスマートスコープワークフローの外側に専用の CI レーンがあります。 -`Parity gate` ワークフローは、一致する PR 変更時と manual dispatch で実行されます。これは -プライベートな QA ランタイムをビルドし、モックの GPT-5.4 と Opus 4.6 の +QA Lab には、メインのスマートスコープワークフローとは別に専用の CI レーンがあります。 +`Parity gate` ワークフローは、該当する PR の変更時と手動実行で走行し、 +非公開の QA ランタイムをビルドして、モックの GPT-5.4 および Opus 4.6 の agentic pack を比較します。`QA-Lab - All Lanes` ワークフローは、`main` で毎晩実行され、 -manual dispatch でも実行されます。これはモック parity gate、ライブ Matrix レーン、 -ライブ Telegram レーンを並列ジョブとして展開します。ライブジョブは `qa-live-shared` -environment を使用し、Telegram レーンは Convex leases を使用します。`OpenClaw Release -Checks` も、リリース承認前に同じ QA Lab レーンを実行します。 +手動実行でも走行します。これは、モック parity gate、ライブ Matrix レーン、 +ライブ Telegram レーンを並列ジョブとしてファンアウトします。ライブジョブは +`qa-live-shared` environment を使用し、Telegram レーンは Convex lease を使用します。 +`OpenClaw Release Checks` も、リリース承認前に同じ QA Lab レーンを実行します。 ## ジョブ概要 -| ジョブ | 目的 | 実行されるタイミング | -| ---------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | docs-only の変更、変更スコープ、変更された extensions を検出し、CI manifest をビルドする | draft ではない push と PR で常に実行 | -| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | draft ではない push と PR で常に実行 | -| `security-dependency-audit` | npm advisories に対する、依存関係不要の本番 lockfile 監査 | draft ではない push と PR で常に実行 | -| `security-fast` | 高速セキュリティジョブ用の必須 aggregate | draft ではない push と PR で常に実行 | -| `build-artifacts` | `dist/`、Control UI、built-artifact チェック、および再利用可能な下流 artifact のビルド | Node 関連の変更 | -| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速 Linux 正当性レーン | Node 関連の変更 | -| `checks-fast-contracts-channels` | 安定した aggregate check 結果を持つ、分割された channel contract チェック | Node 関連の変更 | -| `checks-node-extensions` | extension スイート全体にわたる bundled-plugin テストの完全 shard | Node 関連の変更 | -| `checks-node-core-test` | channel、bundled、contract、および extension レーンを除く、core Node テスト shard | Node 関連の変更 | -| `extension-fast` | 変更された bundled plugins のみに対する重点テスト | extension に変更がある pull request | -| `check` | 分割されたメインのローカル gate 相当: prod types、lint、guards、test types、および strict smoke | Node 関連の変更 | -| `check-additional` | architecture、boundary、extension-surface guards、package-boundary、および gateway-watch shard | Node 関連の変更 | -| `build-smoke` | built-CLI smoke テストと startup-memory smoke | Node 関連の変更 | -| `checks` | built-artifact channel テスト用 verifier と、push のみの Node 22 互換性 | Node 関連の変更 | -| `check-docs` | docs のフォーマット、lint、および broken-link チェック | docs が変更されたとき | -| `skills-python` | Python バックエンドの Skills 用 Ruff + pytest | Python-skill 関連の変更 | -| `checks-windows` | Windows 固有のテストレーン | Windows 関連の変更 | -| `macos-node` | 共有 built artifacts を使用する macOS TypeScript テストレーン | macOS 関連の変更 | -| `macos-swift` | macOS app 用の Swift lint、build、および tests | macOS 関連の変更 | -| `android` | 両フレーバー向けの Android unit tests と 1 つの debug APK ビルド | Android 関連の変更 | +| ジョブ | 目的 | 実行されるタイミング | +| ---------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | +| `preflight` | docs-only の変更、変更されたスコープ、変更された extension を検出し、CI manifest を構築する | draft ではないすべての push と PR | +| `security-scm-fast` | `zizmor` による秘密鍵検出と workflow 監査 | draft ではないすべての push と PR | +| `security-dependency-audit` | npm advisory に対する、依存関係不要の本番 lockfile 監査 | draft ではないすべての push と PR | +| `security-fast` | 高速なセキュリティジョブ用の必須 aggregate | draft ではないすべての push と PR | +| `build-artifacts` | `dist/`、Control UI、ビルド済み artifact チェック、および下流で再利用可能な artifact をビルドする | Node 関連の変更 | +| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速 Linux 正当性レーン | Node 関連の変更 | +| `checks-fast-contracts-channels` | 安定した aggregate チェック結果を持つ shard 化された channel contract チェック | Node 関連の変更 | +| `checks-node-extensions` | extension suite 全体に対する完全な bundled-plugin テスト shard | Node 関連の変更 | +| `checks-node-core-test` | channel、bundled、contract、extension レーンを除く、core Node テスト shard | Node 関連の変更 | +| `extension-fast` | 変更された bundled plugin のみを対象にした絞り込みテスト | extension に変更がある pull request | +| `check` | shard 化されたメインのローカルゲート相当: 本番型、lint、guard、テスト型、strict smoke | Node 関連の変更 | +| `check-additional` | architecture、boundary、extension-surface guard、package-boundary、および gateway-watch shard | Node 関連の変更 | +| `build-smoke` | ビルド済み CLI の smoke テストと起動時メモリ smoke | Node 関連の変更 | +| `checks` | ビルド済み artifact の channel テストに加え、push 時のみ Node 22 互換性を検証する verifier | Node 関連の変更 | +| `check-docs` | docs のフォーマット、lint、リンク切れチェック | docs が変更されたとき | +| `skills-python` | Python ベースの Skills に対する Ruff + pytest | Python Skills 関連の変更 | +| `checks-windows` | Windows 固有のテストレーン | Windows 関連の変更 | +| `macos-node` | 共有ビルド artifact を使う macOS TypeScript テストレーン | macOS 関連の変更 | +| `macos-swift` | macOS app 向けの Swift lint、ビルド、およびテスト | macOS 関連の変更 | +| `android` | 両 flavor の Android unit test と、1 つの debug APK ビルド | Android 関連の変更 | -## Fail-Fast 順序 +## Fail-Fast の順序 -ジョブは、高コストなものが実行される前に低コストなチェックで失敗するよう順序付けされています: +ジョブは、安価なチェックが高コストなジョブより先に失敗するように順序付けされています。 -1. `preflight` が、どのレーンをそもそも存在させるかを決定します。`docs-scope` と `changed-scope` ロジックは、このジョブ内のステップであり、独立したジョブではありません。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、および `skills-python` は、より重い artifact や platform matrix ジョブを待たずに素早く失敗します。 -3. `build-artifacts` は高速 Linux レーンと並行して動作するため、共有 build の準備ができしだい下流の利用者が開始できます。 -4. その後、より重い platform および runtime レーンが展開されます: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、PR 専用の `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、および `android`。 +1. `preflight` が、どのレーンをそもそも存在させるかを決定します。`docs-scope` と `changed-scope` のロジックは、このジョブ内の step であり、独立したジョブではありません。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、`skills-python` は、より重い artifact ジョブや platform matrix ジョブを待たずに素早く失敗します。 +3. `build-artifacts` は高速 Linux レーンと並行して実行されるため、下流の利用側は共有ビルドの準備ができ次第開始できます。 +4. その後、より重い platform および runtime レーンがファンアウトします: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、PR 専用の `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、`android`。 -スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` の unit tests でカバーされています。 -CI ワークフローの編集では Node CI グラフとワークフロー lint が検証されますが、それ自体では Windows、Android、または macOS のネイティブ build を強制しません。これらの platform レーンは platform ソース変更に対してのみスコープされます。 -Windows Node チェックは、Windows 固有の process/path wrapper、npm/pnpm/UI runner helper、package manager config、およびそのレーンを実行する CI ワークフロー表面にスコープされます。無関係なソース、Plugin、install-smoke、および test-only の変更は Linux Node レーンにとどまるため、通常の test shard ですでにカバーされている検証のために 16-vCPU の Windows worker を確保しません。 -別個の `install-smoke` ワークフローは、自身の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。より狭い changed-smoke シグナルから `run_install_smoke` を算出するため、Docker/install smoke は install、packaging、container 関連の変更、bundled extension の本番変更、および Docker smoke ジョブが対象とする core の Plugin/channel/gateway/Plugin SDK 表面で実行されます。test-only と docs-only の編集では Docker worker を確保しません。その QR package smoke は、BuildKit の pnpm store cache を維持しつつ Docker の `pnpm install` レイヤーを強制的に再実行するため、毎回依存関係を再ダウンロードせずにインストールを検証します。その gateway-network e2e は、ジョブ内で先にビルドした runtime image を再利用するため、別の Docker build を追加せずに実際の container-to-container WebSocket カバレッジを追加します。ローカルの `test:docker:all` は、1 つの共有 live-test image と 1 つの共有 `scripts/e2e/Dockerfile` built-app image を事前ビルドし、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` で live/E2E smoke レーンを並列実行します。デフォルト並列数 4 は `OPENCLAW_DOCKER_ALL_PARALLELISM` で調整できます。ローカル aggregate は、デフォルトで最初の失敗後に新しい pooled レーンのスケジューリングを停止し、各レーンには `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` で上書き可能な 120 分タイムアウトがあります。startup または provider に敏感なレーンは、並列プールの後に排他的に実行されます。再利用可能な live/E2E ワークフローは、Docker matrix の前に 1 つの SHA タグ付き GHCR Docker E2E image をビルドして push し、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` で matrix を実行することで、この共有 image パターンを反映しています。scheduled live/E2E ワークフローは、完全な release-path Docker スイートを毎日実行します。QR と installer の Docker テストは、それぞれ独自の install 重視 Dockerfile を維持します。別個の `docker-e2e-fast` ジョブは、120 秒のコマンドタイムアウトのもとで制限付き bundled-plugin Docker profile を実行します: setup-entry 依存関係修復と、synthetic bundled-loader failure isolation です。完全な bundled update/channel matrix は、実際の npm update と doctor repair パスを繰り返し実行するため、manual/full-suite のままです。 +スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` の unit test でカバーされています。 +CI workflow の編集では Node CI グラフと workflow linting が検証されますが、それ自体では Windows、Android、macOS のネイティブビルドは強制されません。これらの platform レーンは、引き続き platform のソース変更に対してのみスコープされます。 +Windows Node チェックは、Windows 固有の process/path wrapper、npm/pnpm/UI runner helper、package manager 設定、およびそのレーンを実行する CI workflow surface に対してスコープされます。無関係なソース、plugin、install-smoke、テスト専用の変更は Linux の Node レーンに留まるため、通常のテスト shard ですでにカバーされている範囲のために 16-vCPU の Windows worker を確保することはありません。 +別の `install-smoke` ワークフローは、独自の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。これは、より狭い changed-smoke シグナルから `run_install_smoke` を計算するため、Docker/install smoke は install、packaging、container 関連の変更、bundled extension の本番変更、および Docker smoke ジョブが実行する core plugin/channel/gateway/Plugin SDK surface で走行します。テスト専用および docs 専用の編集では Docker worker は確保されません。その QR package smoke は、BuildKit pnpm store cache を維持しながら Docker の `pnpm install` layer の再実行を強制するため、毎回依存関係を再ダウンロードせずにインストールを引き続き検証できます。その gateway-network e2e は、ジョブ内の前段でビルドされた runtime image を再利用するため、追加の Docker build を増やさずに実際の container-to-container WebSocket カバレッジを追加します。ローカルの `test:docker:all` は、共有の live-test image を 1 つと共有の `scripts/e2e/Dockerfile` built-app image を 1 つ事前ビルドし、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` で live/E2E smoke レーンを並列実行します。デフォルトの並列度 4 は `OPENCLAW_DOCKER_ALL_PARALLELISM` で調整できます。ローカル aggregate は、デフォルトでは最初の失敗後に新しい pooled レーンのスケジューリングを停止し、各レーンには 120 分の timeout があり、`OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` で上書きできます。起動や provider に敏感なレーンは、並列プールの後に排他的に実行されます。再利用可能な live/E2E workflow は、この共有 image パターンを踏襲し、Docker matrix の前に SHA タグ付きの GHCR Docker E2E image を 1 つビルドして push し、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` で matrix を実行します。定期実行される live/E2E workflow は、リリースパスの Docker suite 全体を毎日実行します。QR と installer の Docker テストは、それぞれ独自の install 重視 Dockerfile を維持します。別個の `docker-e2e-fast` ジョブは、120 秒のコマンド timeout の下で、境界を絞った bundled-plugin Docker profile を実行します: setup-entry の依存関係修復と synthetic な bundled-loader 障害の分離です。完全な bundled update/channel matrix は、実際の npm update と doctor repair の反復実行を行うため、手動実行または full-suite にのみ残されています。 -ローカルの changed-lane ロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。このローカル gate は、広い CI platform スコープよりも architecture boundary に対して厳格です。core の本番変更は core prod typecheck と core tests を実行し、core の test-only 変更は core test typecheck/tests のみを実行し、extension の本番変更は extension prod typecheck と extension tests を実行し、extension の test-only 変更は extension test typecheck/tests のみを実行します。公開 Plugin SDK または plugin-contract の変更は、extensions がそれらの core contract に依存するため、extension 検証まで拡張されます。リリースメタデータのみの version bump では、対象を絞った version/config/root-dependency チェックが実行されます。不明な root/config の変更は安全側に倒してすべてのレーンになります。 +ローカルの changed-lane ロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。このローカルゲートは、広い CI platform scope よりも architecture boundary に対して厳格です。core の本番変更では core の本番 typecheck と core テストを実行し、core のテスト専用変更では core のテスト typecheck/tests のみを実行し、extension の本番変更では extension の本番 typecheck と extension テストを実行し、extension のテスト専用変更では extension のテスト typecheck/tests のみを実行します。公開 Plugin SDK または plugin-contract の変更は、extension がそれらの core contract に依存しているため、extension 検証まで拡張されます。リリースメタデータ専用の version bump では、対象を絞った version/config/root-dependency チェックを実行します。未知の root/config 変更は、安全側に倒してすべてのレーンを実行します。 -push では、`checks` matrix に push 専用の `compat-node22` レーンが追加されます。pull request では、このレーンはスキップされ、matrix は通常の test/channel レーンに集中したままです。 +push では、`checks` matrix に push 専用の `compat-node22` レーンが追加されます。pull request では、このレーンはスキップされ、matrix は通常の test/channel レーンに集中したままになります。 -最も遅い Node テスト群は分割または均等化されており、各ジョブが小さく保たれます。channel contracts は registry と core カバレッジを合計 6 つの重み付き shard に分割し、bundled plugin テストは 6 つの extension worker にバランス配分され、auto-reply は 6 個の小さな worker ではなく 3 個のバランスされた worker として実行され、agentic gateway/plugin configs は built artifacts を待つ代わりに既存の source-only agentic Node ジョブに分散されます。広範な browser、QA、media、および miscellaneous plugin テストは、共有 plugin catch-all ではなく専用の Vitest config を使用します。広範な agents レーンは、単一の遅いテストファイルに支配されるのではなく import/スケジューリング支配型であるため、共有 Vitest の file-parallel scheduler を使用します。`runtime-config` は infra core-runtime shard とともに実行され、共有 runtime shard が最後尾を抱え込まないようにします。`check-additional` は package-boundary compile/canary 作業をまとめて保ち、runtime topology architecture を gateway watch カバレッジから分離します。boundary guard shard は、その小さく独立した guards を 1 つのジョブ内で並列実行します。Gateway watch、channel tests、および core support-boundary shard は、`dist/` と `dist-runtime/` がすでにビルドされた後に `build-artifacts` 内で並列実行され、古い check 名を軽量 verifier ジョブとして維持しつつ、追加の Blacksmith worker 2 台と 2 回目の artifact-consumer queue を回避します。 -Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party フレーバーには別個の source set や manifest はありませんが、その unit-test レーンは SMS/call-log BuildConfig フラグ付きでそのフレーバーをコンパイルしつつ、Android 関連の各 push で重複した debug APK packaging ジョブを避けます。 -`extension-fast` は PR 専用です。push 実行ではすでに完全な bundled plugin shard を実行しているためです。これにより、レビュー向けに changed-plugin フィードバックを維持しつつ、`main` で `checks-node-extensions` にすでに存在するカバレッジのために追加の Blacksmith worker を確保しません。 +最も遅い Node テストファミリーは、各ジョブを小さく保ちつつ runner の過剰確保を避けるため、分割またはバランス調整されています。channel contract は重み付きの 3 shard で実行され、bundled plugin テストは 6 つの extension worker に分散され、小規模な core unit レーンはペア化され、auto-reply は 6 つの極小 worker ではなくバランスされた 3 worker で実行され、agentic gateway/plugin config は built artifact を待つ代わりに既存の source-only agentic Node ジョブに分散されます。広範な browser、QA、media、およびその他の plugin テストは、共有 plugin catch-all ではなく専用の Vitest config を使用します。広範な agents レーンは、単一の遅いテストファイルに支配されるのではなく import/scheduling が支配的であるため、共有 Vitest の file-parallel scheduler を使用します。`runtime-config` は infra core-runtime shard とともに実行され、共有 runtime shard が最後尾を抱え込まないようにしています。`check-additional` は package-boundary の compile/canary 作業をまとめて維持し、runtime topology architecture を gateway watch coverage から分離しています。boundary guard shard は、小さく独立した guard を 1 つのジョブ内で並行実行します。Gateway watch、channel テスト、および core support-boundary shard は、`dist/` と `dist-runtime/` がすでにビルドされた後に `build-artifacts` 内で並行実行され、従来の check 名を軽量な verifier ジョブとして維持しつつ、追加の Blacksmith worker 2 台と 2 回目の artifact-consumer queue を避けています。 +Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party flavor には個別の source set や manifest はありませんが、その unit-test レーンでは SMS/call-log BuildConfig flag を使ってその flavor をコンパイルしつつ、Android 関連の push ごとに debug APK の packaging ジョブを重複実行することは避けています。 +`extension-fast` は PR 専用です。push 実行ではすでに完全な bundled plugin shard が実行されるためです。これにより、レビュー向けには変更された plugin のフィードバックを維持しつつ、`main` で `checks-node-extensions` にすでに含まれているカバレッジのために余分な Blacksmith worker を確保せずに済みます。 -GitHub は、同じ PR または `main` ref に新しい push が届いたとき、置き換えられたジョブを `cancelled` とマークすることがあります。同じ ref の最新実行も失敗している場合を除き、これは CI ノイズとして扱ってください。aggregate shard チェックは `!cancelled() && always()` を使用しているため、通常の shard failure は引き続き報告しますが、ワークフロー全体がすでに置き換えられている場合はキューに入りません。 -CI の concurrency key はバージョン付き（`CI-v7-*`）なので、古い queue group に残った GitHub 側の zombie が新しい main 実行を無期限にブロックすることはありません。 +同じ PR または `main` ref に新しい push が届いた場合、GitHub は置き換えられたジョブを `cancelled` とマークすることがあります。同じ ref に対する最新の実行も失敗していない限り、これは CI ノイズとして扱ってください。aggregate shard チェックは `!cancelled() && always()` を使用しているため、通常の shard failure は引き続き報告されますが、workflow 全体がすでに置き換えられた後にキューに入ることはありません。 +CI の concurrency key はバージョン付き（`CI-v7-*`）であるため、古い queue group に残った GitHub 側の zombie が、新しい `main` 実行を無期限にブロックすることはありません。 ## ランナー -| ランナー | ジョブ | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ubuntu-24.04` | `preflight`、高速セキュリティジョブと aggregate（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速 protocol/contract/bundled チェック、分割された channel contract チェック、lint を除く `check` shard、`check-additional` の shard と aggregate、Node テスト aggregate verifier、docs チェック、Python Skills、workflow-sanity、labeler、auto-response。install-smoke の preflight でも GitHub ホストの Ubuntu を使用するため、Blacksmith matrix をより早くキューに入れられます | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node テスト shard、bundled plugin テスト shard、`android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`。これは依然として CPU 感度が高く、8 vCPU では節約できた以上のコストがかかりました。install-smoke の Docker build では、32-vCPU のキュー時間が得られる節約以上のコストになりました | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`。fork では `macos-latest` にフォールバックします | -| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-swift`。fork では `macos-latest` にフォールバックします | +| ランナー | ジョブ | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`、高速セキュリティジョブとその aggregate（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速 protocol/contract/bundled チェック、shard 化された channel contract チェック、lint を除く `check` shard、`check-additional` の shard と aggregate、Node テスト aggregate verifier、docs チェック、Python Skills、workflow-sanity、labeler、auto-response；install-smoke の preflight も、Blacksmith matrix をより早くキューできるよう GitHub-hosted Ubuntu を使用します | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node テスト shard、bundled plugin テスト shard、`android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`。これは依然として CPU 依存性が高く、8 vCPU では節約できる以上にコストがかかりました；install-smoke の Docker build。こちらも 32-vCPU では節約できる以上にキュー時間のコストが大きくなりました | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`；fork では `macos-latest` にフォールバックします | +| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-swift`；fork では `macos-latest` にフォールバックします | -## 対応するローカルコマンド +## ローカルでの同等コマンド ```bash -pnpm changed:lanes # origin/main...HEAD に対するローカルの changed-lane classifier を確認 -pnpm check:changed # スマートなローカル gate: boundary レーンごとの changed typecheck/lint/tests -pnpm check # 高速ローカル gate: production tsgo + 分割 lint + 並列高速 guards +pnpm changed:lanes # origin/main...HEAD に対するローカル changed-lane classifier を確認 +pnpm check:changed # スマートなローカルゲート: boundary lane ごとの変更対象 typecheck/lint/tests +pnpm check # 高速なローカルゲート: 本番 tsgo + shard 化された lint + 並列の高速 guard pnpm check:test-types -pnpm check:timed # 同じ gate をステージごとの所要時間付きで実行 +pnpm check:timed # ステージごとの所要時間付きの同じゲート pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression -pnpm test # vitest tests +pnpm test # vitest テスト pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # docs format + lint + broken links -pnpm build # CI の artifact/build-smoke レーンが関係する場合は dist をビルド -node scripts/ci-run-timings.mjs # 実行時間、キュー時間、最も遅いジョブを要約 +pnpm check:docs # docs の format + lint + broken link +pnpm build # CI の artifact/build-smoke レーンが関係する場合に dist をビルド +node scripts/ci-run-timings.mjs # wall time、queue time、最も遅いジョブを要約 +node scripts/ci-run-timings.mjs --recent 10 # 最近成功した main の CI 実行を比較 ``` diff --git a/docs/ja-JP/gateway/authentication.md b/docs/ja-JP/gateway/authentication.md index 4eb14223f..7729f2714 100644 --- a/docs/ja-JP/gateway/authentication.md +++ b/docs/ja-JP/gateway/authentication.md @@ -1,14 +1,14 @@ --- read_when: - - モデル認証やOAuthの期限切れをデバッグしている - - 認証や認証情報ストレージをドキュメント化している -summary: 'モデル認証: OAuth、APIキー、Claude CLIの再利用、Anthropic setup-token' + - モデル認証またはOAuthの有効期限切れのデバッグ + - 認証または認証情報ストレージの文書化 +summary: 'モデル認証: OAuth、APIキー、Claude CLIの再利用、およびAnthropicのセットアップトークン' title: 認証 x-i18n: - generated_at: "2026-04-07T04:41:53Z" + generated_at: "2026-04-23T15:00:47Z" model: gpt-5.4 provider: openai - source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231 + source_hash: 37a7c20872b915d1d079f0578c933e43cbdb97eca1c60d8c4e6e5137ca83f8b2 source_path: gateway/authentication.md workflow: 15 --- @@ -16,36 +16,30 @@ x-i18n: # 認証（モデルプロバイダー） -このページでは**モデルプロバイダー**の認証（APIキー、OAuth、Claude CLIの再利用、Anthropic setup-token）を扱います。**Gateway接続**の認証（トークン、パスワード、trusted-proxy）については、[Configuration](/ja-JP/gateway/configuration) と [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照してください。 +このページでは、**モデルプロバイダー**の認証（APIキー、OAuth、Claude CLIの再利用、およびAnthropicのセットアップトークン）を扱います。**Gateway接続**の認証（トークン、パスワード、trusted-proxy）については、[Configuration](/ja-JP/gateway/configuration)および[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth)を参照してください。 -OpenClawはモデルプロバイダー向けにOAuthとAPIキーをサポートしています。常時稼働のGateway -ホストでは、通常はAPIキーが最も予測しやすい選択肢です。サブスクリプション/OAuth -フローも、プロバイダーのアカウントモデルに合う場合はサポートされています。 +OpenClawは、モデルプロバイダー向けにOAuthとAPIキーをサポートしています。常時稼働するGatewayホストでは、通常、APIキーが最も予測しやすい選択肢です。プロバイダーのアカウントモデルに合っていれば、サブスクリプション/OAuthフローもサポートされています。 -完全なOAuthフローとストレージ -レイアウトについては [/concepts/oauth](/ja-JP/concepts/oauth) を参照してください。 -SecretRefベースの認証（`env`/`file`/`exec` プロバイダー）については、[Secrets Management](/ja-JP/gateway/secrets) を参照してください。 -`models status --probe` で使用される認証情報の適格性/理由コードのルールについては、 -[Auth Credential Semantics](/ja-JP/auth-credential-semantics) を参照してください。 +OAuthフロー全体とストレージレイアウトについては、[/concepts/oauth](/ja-JP/concepts/oauth)を参照してください。 +SecretRefベースの認証（`env`/`file`/`exec`プロバイダー）については、[Secrets Management](/ja-JP/gateway/secrets)を参照してください。 +`models status --probe`で使用される認証情報の適格性/理由コードのルールについては、 +[Auth Credential Semantics](/ja-JP/auth-credential-semantics)を参照してください。 ## 推奨セットアップ（APIキー、任意のプロバイダー） -長時間稼働するGatewayを動かしている場合は、選択した -プロバイダーのAPIキーから始めてください。 -Anthropicについては特に、APIキー認証が依然として最も予測しやすいサーバー向け -セットアップですが、OpenClawはローカルのClaude CLIログインの再利用もサポートしています。 +長期間稼働するGatewayを運用している場合は、選択したプロバイダーのAPIキーから始めてください。 +Anthropicについては、APIキー認証が依然として最も予測しやすいサーバーセットアップですが、OpenClawはローカルのClaude CLIログインの再利用もサポートしています。 1. プロバイダーのコンソールでAPIキーを作成します。 -2. それを**Gatewayホスト**（`openclaw gateway` を実行しているマシン）に配置します。 +2. それを**Gatewayホスト**（`openclaw gateway`を実行しているマシン）に配置します。 ```bash export _API_KEY="..." openclaw models status ``` -3. Gatewayがsystemd/launchdの下で動作している場合は、デーモンが読み取れるように - `~/.openclaw/.env` にキーを置くことを推奨します。 +3. Gatewayがsystemd/launchdの下で動作している場合は、デーモンが読み取れるように、キーを`~/.openclaw/.env`に配置することを推奨します。 ```bash cat >> ~/.openclaw/.env <<'EOF' @@ -53,7 +47,7 @@ cat >> ~/.openclaw/.env <<'EOF' EOF ``` -その後、デーモンを再起動する（またはGatewayプロセスを再起動する）か、再確認します。 +その後、デーモンを再起動し（またはGatewayプロセスを再起動し）、再確認します。 ```bash openclaw models status @@ -63,33 +57,46 @@ openclaw doctor 環境変数を自分で管理したくない場合は、オンボーディングで デーモン用のAPIキーを保存できます: `openclaw onboard`。 -`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd における環境継承の詳細は [Help](/ja-JP/help) を参照してください。 +`env`の継承（`env.shellEnv`、 +`~/.openclaw/.env`、systemd/launchd）について詳しくは、[Help](/ja-JP/help)を参照してください。 -## Anthropic: Claude CLIとトークン互換性 +## Anthropic: Claude CLIとトークンの互換性 -Anthropic setup-token認証は、OpenClawで引き続きサポートされているトークン -経路として利用できます。その後、Anthropicの担当者から、OpenClaw方式のClaude CLI利用は -再び許可されていると案内されたため、Anthropicが新しいポリシーを公開しない限り、 -OpenClawはこの統合においてClaude CLIの再利用と `claude -p` の使用を認可済みとして扱います。ホスト上で -Claude CLIの再利用が利用できる場合、現在はこちらが推奨される経路です。 +Anthropicのセットアップトークン認証は、OpenClawでサポートされているトークン経路として引き続き利用可能です。その後、Anthropicのスタッフから、OpenClawスタイルのClaude CLI使用は再び許可されていると伝えられたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはこの統合においてClaude CLIの再利用と`claude -p`の使用を許可されたものとして扱います。ホストでClaude CLIの再利用が可能な場合、現在はそれが推奨経路です。 -長時間稼働するGatewayホストでは、Anthropic APIキーが依然として最も予測しやすい -セットアップです。同じホスト上の既存のClaudeログインを再利用したい場合は、オンボーディング/設定で -Anthropic Claude CLI経路を使用してください。 +長期間稼働するGatewayホストでは、Anthropic APIキーが依然として最も予測しやすいセットアップです。同じホスト上で既存のClaudeログインを再利用したい場合は、オンボーディング/設定でAnthropic Claude CLI経路を使用してください。 -手動トークン入力（任意のプロバイダー; `auth-profiles.json` に書き込み + 設定を更新）: +Claude CLI再利用の推奨ホストセットアップ: + +```bash +# Gatewayホストで実行 +claude auth login +claude auth status --text +openclaw models auth login --provider anthropic --method cli --set-default +``` + +これは2段階のセットアップです。 + +1. Gatewayホスト上でClaude Code自体をAnthropicにログインさせます。 +2. Anthropicモデルの選択をローカルの`claude-cli` + バックエンドに切り替え、対応するOpenClaw認証プロファイルを保存するようOpenClawに指示します。 + +`claude`が`PATH`上にない場合は、まずClaude Codeをインストールするか、 +`agents.defaults.cliBackends.claude-cli.command`を実際のバイナリパスに設定してください。 + +手動トークン入力（任意のプロバイダー; `auth-profiles.json`に書き込み + 設定を更新）: ```bash openclaw models auth paste-token --provider openrouter ``` -静的認証情報では認証プロファイル参照もサポートされています。 +静的な認証情報向けに認証プロファイル参照もサポートされています。 -- `api_key` 認証情報は `keyRef: { source, provider, id }` を使用できます -- `token` 認証情報は `tokenRef: { source, provider, id }` を使用できます -- OAuthモードのプロファイルはSecretRef認証情報をサポートしません。`auth.profiles..mode` が `"oauth"` に設定されている場合、そのプロファイルへのSecretRefベースの `keyRef`/`tokenRef` 入力は拒否されます。 +- `api_key`認証情報は`keyRef: { source, provider, id }`を使用できます +- `token`認証情報は`tokenRef: { source, provider, id }`を使用できます +- OAuthモードのプロファイルはSecretRef認証情報をサポートしません。`auth.profiles..mode`が`"oauth"`に設定されている場合、そのプロファイルに対するSecretRefベースの`keyRef`/`tokenRef`入力は拒否されます。 -自動化向けチェック（期限切れ/未設定で終了コード `1`、期限切れ間近で `2`）: +自動化向けチェック（期限切れ/未設定で終了コード`1`、期限が近い場合は`2`）: ```bash openclaw models status --check @@ -101,28 +108,28 @@ openclaw models status --check openclaw models status --probe ``` -注記: +注意: -- プローブ行は、認証プロファイル、環境認証情報、または `models.json` から来ることがあります。 -- 明示的な `auth.order.` で保存済みプロファイルが省かれている場合、プローブは - そのプロファイルを試す代わりに `excluded_by_auth_order` を報告します。 -- 認証が存在していても、そのプロバイダー向けにプローブ可能なモデル候補をOpenClawが解決できない場合、 - プローブは `status: no_model` を報告します。 -- レート制限のクールダウンはモデル単位である場合があります。ある - モデルでクールダウン中のプロファイルでも、同じプロバイダー上の別のモデルでは使用可能なことがあります。 +- プローブ行は、認証プロファイル、環境変数の認証情報、または`models.json`から取得される場合があります。 +- 明示的な`auth.order.`に保存済みプロファイルが含まれていない場合、 + プローブはそのプロファイルを試行せず、`excluded_by_auth_order`を + そのプロファイルに対して報告します。 +- 認証が存在しても、そのプロバイダーに対してプローブ可能なモデル候補をOpenClawが解決できない場合、 + プローブは`status: no_model`を報告します。 +- レート制限のクールダウンはモデル単位の場合があります。ある + モデルでクールダウン中のプロファイルでも、同じプロバイダー上の兄弟モデルでは引き続き使用可能な場合があります。 -任意の運用スクリプト（systemd/Termux）については、ここで説明しています: -[Auth monitoring scripts](/ja-JP/help/scripts#auth-monitoring-scripts) +オプションの運用スクリプト（systemd/Termux）については、こちらに記載されています: +[認証監視スクリプト](/ja-JP/help/scripts#auth-monitoring-scripts) ## Anthropicに関する注記 -Anthropicの `claude-cli` バックエンドは再びサポートされています。 +Anthropicの`claude-cli`バックエンドは再びサポートされています。 -- Anthropicの担当者は、このOpenClaw統合経路は再び許可されていると案内しました。 -- そのためOpenClawは、Anthropicが新しいポリシーを公開しない限り、 - Anthropicベースの実行におけるClaude CLIの再利用と `claude -p` の使用を認可済みとして扱います。 -- Anthropic APIキーは、長時間稼働するGateway - ホストと、明示的なサーバー側課金制御において、依然として最も予測しやすい選択肢です。 +- Anthropicのスタッフから、このOpenClaw統合経路は再び許可されていると伝えられました。 +- そのためOpenClawは、Anthropicが新しいポリシーを公開しない限り、Anthropicをバックエンドとする実行においてClaude CLIの再利用と`claude -p`の使用を許可されたものとして扱います。 +- Anthropic APIキーは、長期間稼働するGateway + ホストおよび明示的なサーバー側課金管理のための最も予測しやすい選択肢であり続けます。 ## モデル認証ステータスの確認 @@ -131,36 +138,35 @@ openclaw models status openclaw doctor ``` -## APIキーのローテーション動作（Gateway） +## APIキーのローテーション動作（gateway） -一部のプロバイダーは、API呼び出しがプロバイダーのレート制限に達した場合に、 -別のキーでリクエストを再試行することをサポートしています。 +一部のプロバイダーでは、API呼び出しがプロバイダーのレート制限に達した際に、別のキーでリクエストを再試行することをサポートしています。 -- 優先順位: - - `OPENCLAW_LIVE__KEY`（単一のオーバーライド） +- 優先順: + - `OPENCLAW_LIVE__KEY`（単一の上書き） - `_API_KEYS` - `_API_KEY` - `_API_KEY_*` -- Googleプロバイダーでは、追加のフォールバックとして `GOOGLE_API_KEY` も含まれます。 -- 同じキー一覧は使用前に重複排除されます。 -- OpenClawは、レート制限エラーの場合にのみ次のキーで再試行します（たとえば +- Googleプロバイダーでは、追加のフォールバックとして`GOOGLE_API_KEY`も含まれます。 +- 同じキーの一覧は、使用前に重複排除されます。 +- OpenClawは、レート制限エラーの場合にのみ次のキーで再試行します（例: `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、または `workers_ai ... quota limit exceeded`）。 -- レート制限以外のエラーでは、代替キーで再試行しません。 -- すべてのキーが失敗した場合は、最後の試行での最終エラーが返されます。 +- レート制限以外のエラーでは、代替キーによる再試行は行われません。 +- すべてのキーが失敗した場合は、最後の試行で発生した最終エラーが返されます。 ## 使用する認証情報の制御 -### セッションごと（チャットコマンド） +### セッション単位（チャットコマンド） -現在のセッションで特定のプロバイダー認証情報を固定するには、`/model @` を使用します（プロファイルIDの例: `anthropic:default`、`anthropic:work`）。 +現在のセッションで特定のプロバイダー認証情報を固定するには、`/model @`を使用します（プロファイルIDの例: `anthropic:default`、`anthropic:work`）。 -簡易ピッカーには `/model`（または `/model list`）を、完全表示には `/model status` を使用します（候補 + 次の認証プロファイル。設定されている場合はプロバイダーのエンドポイント詳細も表示）。 +コンパクトなピッカーには`/model`（または`/model list`）を使用します。完全な表示（候補 + 次の認証プロファイル、および設定されている場合はプロバイダーのエンドポイント詳細）には`/model status`を使用します。 -### エージェントごと（CLIオーバーライド） +### エージェント単位（CLI上書き） -エージェントに対する明示的な認証プロファイル順序のオーバーライドを設定します（そのエージェントの `auth-state.json` に保存されます）。 +エージェントに対する明示的な認証プロファイル順序の上書きを設定します（そのエージェントの`auth-state.json`に保存されます）。 ```bash openclaw models auth order get --provider anthropic @@ -168,25 +174,24 @@ openclaw models auth order set --provider anthropic anthropic:default openclaw models auth order clear --provider anthropic ``` -特定のエージェントを対象にするには `--agent ` を使用します。省略すると、設定されたデフォルトエージェントが使用されます。 -順序の問題をデバッグするときは、`openclaw models status --probe` により、省かれた -保存済みプロファイルは黙ってスキップされるのではなく `excluded_by_auth_order` として表示されます。 -クールダウンの問題をデバッグするときは、レート制限のクールダウンが -プロバイダープロファイル全体ではなく1つのモデルIDに結びついている可能性があることを覚えておいてください。 +特定のエージェントを対象にするには`--agent `を使用し、設定済みのデフォルトエージェントを使う場合は省略します。 +順序の問題をデバッグする際、`openclaw models status --probe`は省略された +保存済みプロファイルを黙ってスキップする代わりに`excluded_by_auth_order`として表示します。 +クールダウンの問題をデバッグする際は、レート制限のクールダウンが +プロバイダープロファイル全体ではなく、1つのモデルIDに結び付けられている場合があることを忘れないでください。 ## トラブルシューティング ### 「認証情報が見つかりません」 -Anthropicプロファイルがない場合は、 -**Gatewayホスト**にAnthropic APIキーを設定するか、Anthropic setup-token経路を設定してから、再確認してください。 +Anthropicプロファイルが存在しない場合は、 +**Gatewayホスト**上でAnthropic APIキーを設定するか、Anthropicのセットアップトークン経路を設定してから、再確認してください。 ```bash openclaw models status ``` -### トークンの有効期限切れ/期限切れ間近 +### トークンの有効期限が近い/期限切れ -どのプロファイルの期限が近いかを確認するには `openclaw models status` を実行します。Anthropicの -トークンプロファイルが存在しない、または期限切れの場合は、 -setup-tokenでその設定を更新するか、Anthropic APIキーへ移行してください。 +どのプロファイルの有効期限が近いかを確認するには、`openclaw models status`を実行します。Anthropicトークンプロファイルが存在しない、または期限切れの場合は、 +setup-tokenでそのセットアップを更新するか、Anthropic APIキーに移行してください。 diff --git a/docs/ja-JP/gateway/cli-backends.md b/docs/ja-JP/gateway/cli-backends.md index 78d720b32..1510263db 100644 --- a/docs/ja-JP/gateway/cli-backends.md +++ b/docs/ja-JP/gateway/cli-backends.md @@ -1,47 +1,41 @@ --- read_when: - - API provider が失敗したときの信頼できるフォールバックが必要な場合 - - Codex CLI やその他のローカル AI CLI を実行していて、それらを再利用したい場合 - - CLI バックエンドの tool アクセス向け MCP loopback ブリッジを理解したい場合 -summary: 'CLI バックエンド: 任意の MCP tool ブリッジを備えたローカル AI CLI フォールバック' -title: CLI バックエンド + - APIプロバイダーが失敗したときに、信頼できるフォールバックが必要です + - Codex CLIやその他のローカルAI CLIを実行していて、それらを再利用したい場合 + - CLIバックエンドのツールアクセスのためのMCP loopbackブリッジを理解したい場合 +summary: 'CLIバックエンド: オプションのMCPツールブリッジを備えたローカルAI CLIフォールバック' +title: CLIバックエンド x-i18n: - generated_at: "2026-04-23T14:03:42Z" + generated_at: "2026-04-23T15:00:48Z" model: gpt-5.4 provider: openai - source_hash: 475923b36e4580d3e4e57014ff2e6b89e9eb52c11b0a0ab1fc8241655b07836e + source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316 source_path: gateway/cli-backends.md workflow: 15 --- -# CLI バックエンド（フォールバックランタイム） +# CLIバックエンド（フォールバックランタイム） -OpenClaw は、API provider が停止している、レート制限されている、または一時的に不安定な場合に、**ローカル AI CLI** を **テキスト専用フォールバック** として実行できます。これは意図的に保守的な設計です: +OpenClawは、APIプロバイダーがダウンしている、レート制限されている、または一時的に不安定なときに、**テキストのみのフォールバック**として**ローカルAI CLI**を実行できます。これは意図的に保守的な設計です。 -- **OpenClaw tools は直接注入されません** が、`bundleMcp: true` を持つバックエンドは - loopback MCP ブリッジ経由で gateway tools を受け取れます。 -- 対応する CLI 向けの **JSONL ストリーミング**。 -- **セッションをサポート** しているため、追加入力でも一貫性が保たれます。 -- CLI が画像 path を受け付ける場合、**画像も引き渡せます**。 +- **OpenClawツールは直接注入されません**が、`bundleMcp: true` を持つバックエンドは、loopback MCPブリッジ経由でgatewayツールを受け取れます。 +- 対応するCLI向けの**JSONLストリーミング**。 +- **セッションをサポート**しているため、後続のターンでも一貫性が保たれます。 +- CLIが画像パスを受け付ける場合は、**画像をそのまま渡せます**。 -これはメイン経路というより **セーフティネット** として設計されています。外部 API に依存せず、 -「とにかく動く」テキスト応答が欲しいときに使ってください。 +これは、主要な経路というより**セーフティネット**として設計されています。外部APIに依存せずに「常に動作する」テキスト応答が必要なときに使ってください。 -ACP セッション制御、バックグラウンドタスク、 -thread/conversation バインディング、永続的な外部 coding セッションを備えた完全な harness runtime が必要なら、 -代わりに [ACP Agents](/ja-JP/tools/acp-agents) を使用してください。CLI バックエンドは ACP ではありません。 +ACPセッション制御、バックグラウンドタスク、スレッド/会話バインディング、永続的な外部コーディングセッションを備えた完全なハーネスランタイムが必要な場合は、代わりに [ACP Agents](/ja-JP/tools/acp-agents) を使ってください。CLIバックエンドはACPではありません。 ## 初心者向けクイックスタート -設定なしでも Codex CLI を使用できます（バンドルされた OpenAI plugin が -デフォルトのバックエンドを登録します）: +Codex CLIは**設定なしで**使えます（同梱のOpenAI Pluginがデフォルトのバックエンドを登録します）。 ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -gateway が launchd/systemd 配下で動作していて PATH が最小限の場合は、 -コマンド path だけを追加してください: +gatewayがlaunchd/systemd配下で動作していてPATHが最小限の場合は、コマンドパスだけを追加してください。 ```json5 { @@ -57,16 +51,13 @@ gateway が launchd/systemd 配下で動作していて PATH が最小限の場 } ``` -これだけです。CLI 自体に必要なものを除いて、キーも追加の認証設定も不要です。 +これだけです。CLI自体に必要なもの以外に、キーや追加の認証設定は不要です。 -バンドルされた CLI バックエンドを gateway host 上の**主要メッセージ provider** として使う場合、 -OpenClaw は、設定が model ref や -`agents.defaults.cliBackends` の下でそのバックエンドを明示的に参照していれば、 -所有している bundled plugin を自動的に読み込むようになりました。 +gatewayホスト上で、同梱のCLIバックエンドを**主要メッセージプロバイダー**として使う場合、設定でそのバックエンドをモデル参照、または `agents.defaults.cliBackends` 配下で明示的に参照すると、OpenClawはその所有元の同梱Pluginを自動読み込みするようになりました。 ## フォールバックとして使う -CLI バックエンドをフォールバック一覧に追加すると、主要モデルが失敗したときだけ実行されます: +CLIバックエンドをフォールバックリストに追加すると、主要モデルが失敗したときだけ実行されます。 ```json5 { @@ -87,20 +78,19 @@ CLI バックエンドをフォールバック一覧に追加すると、主要 注意: -- `agents.defaults.models`（許可リスト）を使う場合は、CLI バックエンドのモデルもそこに含める必要があります。 -- 主要 provider が失敗した場合（認証、レート制限、タイムアウト）、OpenClaw は - 次に CLI バックエンドを試します。 +- `agents.defaults.models`（許可リスト）を使う場合は、CLIバックエンドのモデルもそこに含める必要があります。 +- 主要プロバイダーが失敗した場合（認証、レート制限、タイムアウト）、OpenClawは次にCLIバックエンドを試します。 -## 設定の概要 +## 設定概要 -すべての CLI バックエンドは以下に配置されます: +すべてのCLIバックエンドは次の場所にあります。 ``` agents.defaults.cliBackends ``` -各エントリは **provider id**（例: `codex-cli`, `my-cli`）をキーにします。 -provider id は model ref の左側になります: +各エントリーは**provider id**（例: `codex-cli`, `my-cli`）でキー付けされます。 +provider idはモデル参照の左側になります。 ``` / @@ -130,7 +120,7 @@ provider id は model ref の左側になります: sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // Codex-style CLIs can point at a prompt file instead: + // CodexスタイルのCLIでは、代わりにプロンプトファイルを指定できます: // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -146,97 +136,75 @@ provider id は model ref の左側になります: ## 仕組み -1. provider 接頭辞（`codex-cli/...`）に基づいて **バックエンドを選択** します。 -2. 同じ OpenClaw prompt + workspace コンテキストを使って **system prompt を構築** します。 -3. 履歴の一貫性を保つため、CLI が対応していれば session id 付きで **CLI を実行** します。 - バンドルされた `claude-cli` バックエンドは、OpenClaw セッションごとに - Claude stdio process を維持し、追加入力を stream-json stdin 経由で送ります。 -4. 出力（JSON またはプレーンテキスト）を **解析** し、最終テキストを返します。 -5. バックエンドごとに session id を **永続化** し、追加入力で同じ CLI セッションを再利用します。 +1. providerプレフィックス（`codex-cli/...`）に基づいて**バックエンドを選択**します。 +2. 同じOpenClawプロンプトとワークスペースコンテキストを使って**システムプロンプトを構築**します。 +3. 履歴の一貫性を保つため、対応している場合はセッションid付きで**CLIを実行**します。 + 同梱の `claude-cli` バックエンドは、OpenClawセッションごとにClaude stdioプロセスを維持し、後続ターンをstream-json stdin経由で送信します。 +4. **出力を解析**し（JSONまたはプレーンテキスト）、最終テキストを返します。 +5. バックエンドごとに**セッションidを永続化**し、後続ターンで同じCLIセッションを再利用します。 -バンドルされた Anthropic `claude-cli` バックエンドは再びサポートされています。Anthropic のスタッフから、 -OpenClaw スタイルの Claude CLI 利用は再び許可されると伝えられたため、Anthropic が新しいポリシーを公開しない限り、 -OpenClaw はこの統合における `claude -p` 使用を許可済みとして扱います。 +同梱のAnthropic `claude-cli` バックエンドが再びサポートされました。Anthropicのスタッフから、OpenClawスタイルのClaude CLI利用は再び許可されていると案内されたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはこの連携における `claude -p` の使用を公認済みとして扱います。 -バンドルされた OpenAI `codex-cli` バックエンドは、OpenClaw の system prompt を -Codex の `model_instructions_file` 設定上書き（`-c -model_instructions_file="..."`）経由で渡します。Codex には Claude スタイルの -`--append-system-prompt` フラグがないため、OpenClaw は新しい Codex CLI セッションごとに -組み立てた prompt を一時ファイルへ書き出します。 +同梱のOpenAI `codex-cli` バックエンドは、Codexの `model_instructions_file` 設定オーバーライド（`-c model_instructions_file="..."`）を通して、OpenClawのシステムプロンプトを渡します。CodexはClaudeスタイルの `--append-system-prompt` フラグを公開していないため、OpenClawは新しいCodex CLIセッションごとに組み立てたプロンプトを一時ファイルに書き出します。 -バンドルされた Anthropic `claude-cli` バックエンドは、OpenClaw の Skills スナップショットを -2 つの方法で受け取ります。ひとつは追加された system prompt 内のコンパクトな OpenClaw Skills カタログ、 -もうひとつは `--plugin-dir` で渡される一時的な Claude Code plugin です。 -その plugin には、その agent/session に適格な Skills だけが含まれているため、Claude Code のネイティブな Skill -resolver には、OpenClaw が prompt 内で通知するのと同じフィルタ済みセットが見えます。 -Skill の env/API key 上書きは、実行時に引き続き OpenClaw が子プロセス環境へ適用します。 +同梱のAnthropic `claude-cli` バックエンドは、OpenClawのSkillsスナップショットを2つの方法で受け取ります。1つは追加されたシステムプロンプト内のコンパクトなOpenClaw Skillsカタログ、もう1つは `--plugin-dir` で渡される一時的なClaude Code Pluginです。このPluginにはそのagent/セッションで利用資格のあるSkillsのみが含まれるため、Claude Codeネイティブのskill resolverは、OpenClawがそれ以外ならプロンプト内で通知するのと同じフィルタ済みセットを認識します。Skillのenv/APIキー上書きは、実行時にOpenClawから子プロセス環境へ引き続き適用されます。 + +OpenClawが同梱の `claude-cli` バックエンドを使う前に、Claude Code自体が同じホスト上ですでにログイン済みである必要があります。 + +```bash +claude auth login +claude auth status --text +openclaw models auth login --provider anthropic --method cli --set-default +``` + +`claude` バイナリがすでに `PATH` 上にある場合を除き、`agents.defaults.cliBackends.claude-cli.command` を使ってください。 ## セッション -- CLI がセッションをサポートしている場合は、`sessionArg`（例: `--session-id`）または - `sessionArgs`（複数のフラグに `{sessionId}` を挿入する必要がある場合のプレースホルダー）を設定します。 -- CLI が異なるフラグを使う **resume サブコマンド** を持つ場合は、 - `resumeArgs`（resume 時に `args` を置き換える）と、必要に応じて - `resumeOutput`（JSON ではない resume 用）を設定します。 +- CLIがセッションをサポートする場合は、`sessionArg`（例: `--session-id`）または `sessionArgs`（複数のフラグにIDを挿入する必要がある場合のプレースホルダー `{sessionId}`）を設定します。 +- CLIが異なるフラグを持つ**resumeサブコマンド**を使う場合は、`resumeArgs`（再開時に `args` を置き換えます）を設定し、必要に応じて `resumeOutput`（非JSONのresume用）も設定します。 - `sessionMode`: - - `always`: 常に session id を送信します（保存済みがなければ新しい UUID）。 - - `existing`: 以前に保存された session id がある場合のみ送信します。 - - `none`: session id を送信しません。 -- `claude-cli` はデフォルトで `liveSession: "claude-stdio"`、`output: "jsonl"`、 - `input: "stdin"` を使うため、アクティブな間は追加入力でも生きている Claude process を再利用します。 - 現在は warm stdio がデフォルトであり、transport フィールドを省略したカスタム設定でも同様です。 - Gateway が再起動したり、アイドル中の process が終了した場合は、 - OpenClaw は保存済み Claude session id から再開します。保存済み session - id は、再開前に読み取り可能な既存 project transcript に対して検証されるため、 - 幽霊のようなバインディングは `--resume` 配下で黙って新しい Claude CLI セッションを始める代わりに - `reason=transcript-missing` でクリアされます。 -- 保存された CLI セッションは provider 所有の継続性です。暗黙の日次セッション - リセットでは切断されません。`/reset` と明示的な `session.reset` ポリシーでは切断されます。 + - `always`: 常にセッションidを送信します（保存済みがなければ新しいUUID）。 + - `existing`: 以前に保存されている場合のみセッションidを送信します。 + - `none`: セッションidを送信しません。 +- `claude-cli` は、`liveSession: "claude-stdio"`、`output: "jsonl"`、`input: "stdin"` をデフォルトとし、アクティブな間は後続ターンがライブClaudeプロセスを再利用します。現在は、トランスポートフィールドを省略したカスタム設定も含め、ウォームなstdioがデフォルトです。Gatewayが再起動するか、アイドル状態のプロセスが終了した場合、OpenClawは保存されたClaudeセッションidから再開します。保存されたセッションidは再開前に既存の読み取り可能なプロジェクトトランスクリプトに対して検証されるため、実体のないバインディングは `--resume` で新しいClaude CLIセッションを黙って開始する代わりに、`reason=transcript-missing` でクリアされます。 +- 保存されたCLIセッションはprovider所有の継続性です。暗黙の日次セッションリセットでは切断されませんが、`/reset` および明示的な `session.reset` ポリシーでは切断されます。 シリアライズに関する注意: - `serialize: true` は同じレーンの実行順序を維持します。 -- ほとんどの CLI は 1 つの provider レーンでシリアライズされます。 -- OpenClaw は、選択された auth identity が変わると、保存済み CLI セッションの再利用を破棄します。 - これには、auth profile id の変更、静的 API key、静的 token、 - または CLI が公開している場合は OAuth account identity の変更が含まれます。OAuth access - token と refresh token のローテーションでは、保存済み CLI セッションは切断されません。 - CLI が安定した OAuth account id を公開していない場合、OpenClaw はその CLI 側に resume 権限の強制を委ねます。 +- ほとんどのCLIは1つのproviderレーンでシリアライズされます。 +- 選択された認証IDが変わった場合、OpenClawは保存済みCLIセッションの再利用を破棄します。これには、auth profile idの変更、静的APIキー、静的トークン、またはCLIが公開している場合のOAuthアカウントIDの変更が含まれます。OAuthのアクセストークンとリフレッシュトークンのローテーションでは、保存済みCLIセッションは切断されません。CLIが安定したOAuthアカウントIDを公開しない場合、OpenClawはそのCLIにresume権限の強制を任せます。 ## 画像（パススルー） -CLI が画像 path を受け付ける場合は、`imageArg` を設定します: +CLIが画像パスを受け付ける場合は、`imageArg` を設定します。 ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw は base64 画像を一時ファイルへ書き出します。`imageArg` が設定されていれば、 -それらの path が CLI 引数として渡されます。`imageArg` がない場合、OpenClaw は -ファイル path を prompt に追記します（path injection）。これは、単なる path からローカルファイルを自動読み込みする -CLI には十分です。 +OpenClawはbase64画像を一時ファイルに書き出します。`imageArg` が設定されている場合、それらのパスはCLI引数として渡されます。`imageArg` がない場合、OpenClawはファイルパスをプロンプトに追記します（パス注入）。これは、プレーンなパスからローカルファイルを自動読み込みするCLIには十分です。 -## 入力 / 出力 +## 入出力 -- `output: "json"`（デフォルト）は JSON の解析を試み、text + session id を抽出します。 -- Gemini CLI の JSON 出力では、`usage` がないか空の場合、 - OpenClaw は返信テキストを `response` から、使用量を `stats` から読み取ります。 -- `output: "jsonl"` は JSONL ストリーム（たとえば Codex CLI `--json`）を解析し、最終 agent メッセージと - 存在する session 識別子を抽出します。 -- `output: "text"` は stdout を最終応答として扱います。 +- `output: "json"`（デフォルト）はJSONを解析し、テキストとセッションidの抽出を試みます。 +- Gemini CLIのJSON出力では、`usage` が存在しないか空の場合、OpenClawは返信テキストを `response` から、使用量を `stats` から読み取ります。 +- `output: "jsonl"` はJSONLストリーム（たとえばCodex CLIの `--json`）を解析し、存在する場合は最終agentメッセージとセッション識別子を抽出します。 +- `output: "text"` はstdoutを最終応答として扱います。 入力モード: -- `input: "arg"`（デフォルト）は prompt を最後の CLI 引数として渡します。 -- `input: "stdin"` は prompt を stdin 経由で送ります。 -- prompt が非常に長く、`maxPromptArgChars` が設定されている場合は stdin が使われます。 +- `input: "arg"`（デフォルト）は、プロンプトを最後のCLI引数として渡します。 +- `input: "stdin"` は、プロンプトをstdin経由で送信します。 +- プロンプトが非常に長く、`maxPromptArgChars` が設定されている場合は、stdinが使われます。 -## デフォルト（plugin 所有） +## デフォルト（Plugin所有） -バンドルされた OpenAI plugin は `codex-cli` 用のデフォルトも登録します: +同梱のOpenAI Pluginは、`codex-cli` 用のデフォルトも登録します。 - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -247,7 +215,7 @@ CLI には十分です。 - `imageArg: "--image"` - `sessionMode: "existing"` -バンドルされた Google plugin は `google-gemini-cli` 用のデフォルトも登録します: +同梱のGoogle Pluginは、`google-gemini-cli` 用のデフォルトも登録します。 - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -258,32 +226,27 @@ CLI には十分です。 - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -前提条件: ローカルの Gemini CLI がインストールされ、`PATH` 上で -`gemini` として利用可能である必要があります（`brew install gemini-cli` または -`npm install -g @google/gemini-cli`）。 +前提条件: ローカルのGemini CLIがインストールされ、`PATH` 上で `gemini` として利用可能である必要があります（`brew install gemini-cli` または `npm install -g @google/gemini-cli`）。 -Gemini CLI JSON に関する注意: +Gemini CLI JSONに関する注意: -- 返信テキストは JSON の `response` フィールドから読み取られます。 -- `usage` が存在しないか空の場合、使用量は `stats` にフォールバックします。 -- `stats.cached` は OpenClaw の `cacheRead` に正規化されます。 -- `stats.input` がない場合、OpenClaw は入力トークンを - `stats.input_tokens - stats.cached` から導出します。 +- 返信テキストはJSONの `response` フィールドから読み取られます。 +- 使用量は、`usage` が存在しない場合または空の場合に `stats` にフォールバックします。 +- `stats.cached` はOpenClawの `cacheRead` に正規化されます。 +- `stats.input` が存在しない場合、OpenClawは `stats.input_tokens - stats.cached` から入力トークンを導出します。 -必要な場合にのみ上書きしてください（よくあるのは絶対 `command` path です）。 +必要な場合のみ上書きしてください（一般的なのは絶対 `command` パスです）。 -## Plugin 所有のデフォルト +## Plugin所有のデフォルト -CLI バックエンドのデフォルトは、現在は plugin サーフェスの一部です: +CLIバックエンドのデフォルトは、現在ではPluginサーフェスの一部です。 -- Plugins は `api.registerCliBackend(...)` でそれらを登録します。 -- バックエンドの `id` が model ref における provider 接頭辞になります。 -- `agents.defaults.cliBackends.` 内のユーザー設定は、引き続き plugin デフォルトを上書きします。 -- バックエンド固有の設定クリーンアップは、任意の - `normalizeConfig` hook を通じて引き続き plugin 側が管理します。 +- Pluginは `api.registerCliBackend(...)` でそれらを登録します。 +- バックエンドの `id` はモデル参照のproviderプレフィックスになります。 +- `agents.defaults.cliBackends.` にあるユーザー設定は、引き続きPluginデフォルトを上書きします。 +- バックエンド固有の設定クリーンアップは、オプションの `normalizeConfig` フックを通じて引き続きPlugin所有のままです。 -小さな prompt/message 互換 shim が必要な plugin は、provider や CLI バックエンドを置き換えずに、 -双方向のテキスト変換を宣言できます: +小さなプロンプト/メッセージ互換性シムが必要なPluginは、providerやCLIバックエンドを置き換えずに双方向のテキスト変換を宣言できます。 ```typescript api.registerTextTransforms({ @@ -300,51 +263,41 @@ api.registerTextTransforms({ }); ``` -`input` は CLI に渡す system prompt と user prompt を書き換えます。`output` -は、OpenClaw が独自の control marker や channel 配信を処理する前に、 -ストリーミングされる assistant delta と解析済み最終テキストを書き換えます。 +`input` は、CLIに渡されるシステムプロンプトとユーザープロンプトを書き換えます。`output` は、OpenClawが自身の制御マーカー処理とチャネル配信を行う前に、ストリーミングされたassistant deltaと解析済みの最終テキストを書き換えます。 -Claude Code の stream-json 互換 JSONL を出力する CLI では、 -そのバックエンド設定に `jsonlDialect: "claude-stream-json"` を設定してください。 +Claude Code stream-json互換のJSONLを出力するCLIでは、そのバックエンド設定に `jsonlDialect: "claude-stream-json"` を設定してください。 -## Bundle MCP オーバーレイ +## Bundle MCPオーバーレイ -CLI バックエンドは **OpenClaw tool call を直接受け取りません** が、バックエンドは -`bundleMcp: true` で生成される MCP 設定オーバーレイに opt in できます。 +CLIバックエンドは**OpenClawツール呼び出しを直接受け取りません**が、バックエンドは `bundleMcp: true` で生成されるMCP設定オーバーレイにオプトインできます。 -現在の bundled の動作: +現在の同梱動作: -- `claude-cli`: 生成された strict MCP config file -- `codex-cli`: `mcp_servers` 用のインライン設定上書き -- `google-gemini-cli`: 生成された Gemini システム設定ファイル +- `claude-cli`: 生成されたstrict MCP設定ファイル +- `codex-cli`: `mcp_servers` 用のインライン設定オーバーライド +- `google-gemini-cli`: 生成されたGeminiシステム設定ファイル -bundle MCP が有効な場合、OpenClaw は次を行います: +bundle MCPが有効な場合、OpenClawは次を行います。 -- gateway tools を CLI process に公開する loopback HTTP MCP server を起動する -- セッションごとの token（`OPENCLAW_MCP_TOKEN`）でブリッジを認証する -- tool アクセスを現在の session、account、channel コンテキストに限定する -- 現在の workspace で有効な bundle-MCP server を読み込む -- それらを既存のバックエンド MCP config/settings 形状とマージする -- 所有 extension の統合モードを使って起動設定を書き換える +- CLIプロセスにgatewayツールを公開するloopback HTTP MCPサーバーを起動する +- セッションごとのトークン（`OPENCLAW_MCP_TOKEN`）でブリッジを認証する +- ツールアクセスを現在のセッション、アカウント、チャネルコンテキストにスコープする +- 現在のワークスペースに対して有効なbundle-MCPサーバーを読み込む +- それらを既存のバックエンドMCP設定/設定形状とマージする +- 所有元extensionのバックエンド所有統合モードを使って起動設定を書き換える -有効な MCP server がない場合でも、バックエンドが bundle MCP に opt in していれば、 -OpenClaw は strict config を注入するため、バックグラウンド実行は分離されたままです。 +MCPサーバーが1つも有効でない場合でも、バックエンドがbundle MCPにオプトインしていれば、バックグラウンド実行を分離した状態に保つために、OpenClawはstrict設定を引き続き注入します。 -## 制限 +## 制限事項 -- **OpenClaw tool call の直接呼び出しはありません。** OpenClaw は CLI バックエンドプロトコルに - tool call を直接注入しません。バックエンドが gateway tools を認識するのは、 - `bundleMcp: true` に opt in した場合のみです。 -- **ストリーミングはバックエンド依存です。** JSONL をストリーミングするバックエンドもあれば、 - 終了までバッファするものもあります。 -- **構造化出力** は CLI の JSON 形式に依存します。 -- **Codex CLI セッション** はテキスト出力経由で resume されるため（JSONL ではない）、 - 初回の `--json` 実行より構造化が弱くなります。それでも OpenClaw セッション自体は通常どおり動作します。 +- **OpenClawツール呼び出しの直接利用はできません。** OpenClawはCLIバックエンドプロトコルにツール呼び出しを注入しません。バックエンドが `bundleMcp: true` にオプトインした場合にのみ、gatewayツールを認識できます。 +- **ストリーミングはバックエンド依存です。** JSONLをストリーミングするバックエンドもあれば、終了までバッファするバックエンドもあります。 +- **構造化出力**はCLIのJSON形式に依存します。 +- **Codex CLIセッション**はテキスト出力経由で再開されます（JSONLではありません）。そのため、最初の `--json` 実行より構造化が弱くなります。それでもOpenClawセッション自体は通常どおり動作します。 ## トラブルシューティング -- **CLI が見つからない**: `command` にフル path を設定してください。 -- **model 名が間違っている**: `modelAliases` を使って `provider/model` → CLI model にマップしてください。 -- **セッション継続性がない**: `sessionArg` が設定されていて、`sessionMode` が - `none` でないことを確認してください（現在 Codex CLI は JSON 出力では resume できません）。 -- **画像が無視される**: `imageArg` を設定し（CLI が file path をサポートすることも確認してください）。 +- **CLIが見つからない**: `command` にフルパスを設定してください。 +- **モデル名が間違っている**: `modelAliases` を使って `provider/model` → CLIモデル をマッピングしてください。 +- **セッションの継続性がない**: `sessionArg` が設定されていて、`sessionMode` が `none` ではないことを確認してください（Codex CLIは現在、JSON出力で再開できません）。 +- **画像が無視される**: `imageArg` を設定し（あわせてCLIがファイルパスをサポートしていることを確認してください）。 diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index ff2908705..09cc91a9d 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -1,174 +1,148 @@ --- read_when: - - ローカルまたはCIでテストを実行する。 - - model/providerのバグに対するリグレッションテストを追加する。 - - Gateway + agentの動作をデバッグする。 -summary: 'テストキット: unit/e2e/liveスイート、Dockerランナー、および各テストが対象とする内容' -title: テスト + - ローカルまたは CI でのテストの実行 + - モデル/プロバイダーのバグに対する回帰テストの追加 + - Gateway + エージェントの動作のデバッグ +summary: 'テストキット: unit/e2e/live スイート、Docker ランナー、および各テストでカバーされる内容' +title: テスト中 x-i18n: - generated_at: "2026-04-23T14:04:34Z" + generated_at: "2026-04-23T15:00:49Z" model: gpt-5.4 provider: openai - source_hash: fe0e9bdea78cba7e512358d2e4d428da04a2071188e74af2d5419d2c85eafe15 + source_hash: fbec4996699577321116c94f60c01d205d7594ed41aca27c821f1c3d65a7dca3 source_path: help/testing.md workflow: 15 --- # テスト -OpenClawには、3つのVitestスイート（unit/integration、e2e、live）と、少数のDockerランナーがあります。 +OpenClaw には 3 つの Vitest スイート（unit/integration、e2e、live）と、小規模な Docker ランナー群があります。 -このドキュメントは「どのようにテストするか」のガイドです: +このドキュメントは「どのようにテストするか」のガイドです。 -- 各スイートが何を対象にしているか（そして意図的に何を対象外にしているか） -- 一般的なワークフロー（ローカル、push前、デバッグ）でどのコマンドを実行するか -- liveテストがどのように認証情報を見つけ、model/providerを選択するか -- 実際のmodel/provider問題に対するリグレッションをどのように追加するか +- 各スイートがカバーする内容（および意図的に _カバーしない_ 内容） +- 一般的なワークフロー（ローカル、push 前、デバッグ）で実行するコマンド +- live テストがどのように認証情報を検出し、モデル/プロバイダーを選択するか +- 実際のモデル/プロバイダーの問題に対する回帰テストの追加方法 ## クイックスタート -普段は: +普段は以下です。 -- 完全ゲート（push前に期待される）: `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- 余裕のあるマシンでの高速なローカル全スイート実行: `pnpm test:max` -- 直接のVitest watchループ: `pnpm test:watch` -- 直接のファイル指定は現在、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` +- フルゲート（push 前に想定）: `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- 余裕のあるマシンでの、より高速なローカル全スイート実行: `pnpm test:max` +- 直接の Vitest watch ループ: `pnpm test:watch` +- 直接ファイルを指定する実行では、拡張機能/チャネルのパスも対象になりました: `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` +- E2E スイート: `pnpm test:e2e` -実際のprovider/modelをデバッグするとき（実認証情報が必要）: +実際のプロバイダー/モデルをデバッグするとき（実際の認証情報が必要）: -- Liveスイート（models + gateway tool/image probes）: `pnpm test:live` -- 1つのliveファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live model sweep: `pnpm test:docker:live-models` - - CIカバレッジ: 毎日の `OpenClaw Scheduled Live And E2E Checks` と手動の - `OpenClaw Release Checks` は、どちらも `include_live_suites: true` を付けて - 再利用可能なlive/E2E workflowを呼び出します。これにはproviderごとに分割された - 個別のDocker live model matrix jobsが含まれます。 - - 対象を絞ったCI再実行には、`OpenClaw Live And E2E Checks (Reusable)` - を `include_live_suites: true` と `live_models_only: true` でdispatchしてください。 - - 高シグナルな新しいprovider secretsを追加するときは、`scripts/ci-hydrate-live-auth.sh` - と `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml`、およびその - scheduled/release呼び出し元にも追加してください。 -- Moonshot/Kimiのコストスモーク: `MOONSHOT_API_KEY` を設定したうえで、 - `openclaw models list --provider moonshot --json` を実行し、その後 - `moonshot/kimi-k2.6` に対して分離された - `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - を実行します。JSONがMoonshot/K2.6を報告し、 - assistant transcriptが正規化された `usage.cost` を保存していることを確認してください。 +- live スイート（モデル + Gateway のツール/画像プローブ）: `pnpm test:live` +- 単一の live ファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker live モデル一括実行: `pnpm test:docker:live-models` + - 選択された各モデルは、テキストターンに加えて、小さなファイル読み取り風のプローブも実行するようになりました。メタデータが `image` 入力を示すモデルでは、小さな画像ターンも実行します。プロバイダー障害を切り分ける際は、`OPENCLAW_LIVE_MODEL_FILE_PROBE=0` または `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` で追加プローブを無効化してください。 + - CI カバレッジ: 毎日の `OpenClaw Scheduled Live And E2E Checks` と手動の `OpenClaw Release Checks` は、どちらも `include_live_suites: true` を付けて再利用可能な live/E2E ワークフローを呼び出します。これには、プロバイダーごとに分割された個別の Docker live モデル matrix ジョブが含まれます。 + - CI の絞り込み再実行では、`include_live_suites: true` および `live_models_only: true` を付けて `OpenClaw Live And E2E Checks (Reusable)` を dispatch してください。 + - 新しい高シグナルのプロバイダー secret を追加する場合は、`scripts/ci-hydrate-live-auth.sh` と `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml`、およびその scheduled/release 呼び出し元にも追加してください。 +- Moonshot/Kimi のコストスモーク: `MOONSHOT_API_KEY` を設定した状態で、`openclaw models list --provider moonshot --json` を実行し、その後 `moonshot/kimi-k2.6` に対して分離した `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` を実行します。JSON が Moonshot/K2.6 を報告しており、アシスタントの transcript に正規化済みの `usage.cost` が保存されていることを確認してください。 -ヒント: 失敗ケースが1つだけ必要な場合は、以下で説明するallowlist env varsを使ってliveテストを絞ることを優先してください。 +ヒント: 失敗しているケースが 1 つだけ必要な場合は、以下で説明する allowlist 環境変数を使って live テストを絞り込むことを優先してください。 -## QA専用ランナー +## QA 専用ランナー -これらのコマンドは、QA-labレベルの現実性が必要なときに、メインのテストスイートと並んで使います: +これらのコマンドは、QA-lab の実環境性が必要なときに、メインのテストスイートと並んで使います。 -CIは専用workflowでQA Labを実行します。`Parity gate` は一致するPRと -手動dispatchでモックproviderを使って実行されます。`QA-Lab - All Lanes` は `main` に対して夜間実行され、 -手動dispatchでも、モックparity gate、live Matrixレーン、Convex管理のlive Telegramレーンを -並列ジョブとして実行します。`OpenClaw Release Checks` はリリース承認前に同じレーンを実行します。 +CI は専用ワークフローで QA Lab を実行します。`Parity gate` は一致する PR で、また手動 dispatch からモックプロバイダー付きで実行されます。`QA-Lab - All Lanes` は `main` に対して毎晩実行され、また手動 dispatch から、モック parity gate、live Matrix レーン、Convex 管理の live Telegram レーンを並列ジョブとして実行します。`OpenClaw Release Checks` は、リリース承認前に同じレーンを実行します。 - `pnpm openclaw qa suite` - - リポジトリバックのQAシナリオをホスト上で直接実行します。 - - デフォルトでは、分離された - gateway workersを使って、選択された複数のシナリオを並列実行します。`qa-channel` のデフォルト同時実行数は4です（選択されたシナリオ数の範囲内）。worker数を調整するには `--concurrency ` を使い、従来の直列レーンには `--concurrency 1` を使ってください。 - - いずれかのシナリオが失敗すると、非ゼロで終了します。失敗終了コードなしでartifactが欲しい場合は `--allow-failures` を使ってください。 - - `live-frontier`、`mock-openai`、`aimock` のprovider modesをサポートします。 - `aimock` は、シナリオ認識型の `mock-openai` レーンを置き換えるのではなく、実験的な - fixtureおよびprotocol-mockカバレッジのために、ローカルのAIMockバックprovider serverを起動します。 + - リポジトリベースの QA シナリオをホスト上で直接実行します。 + - デフォルトでは、分離された Gateway ワーカーで複数の選択シナリオを並列実行します。`qa-channel` のデフォルト同時実行数は 4 です（選択されたシナリオ数の範囲内）。ワーカー数を調整するには `--concurrency ` を使い、従来の直列レーンにするには `--concurrency 1` を使います。 + - いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしで成果物だけ必要な場合は `--allow-failures` を使ってください。 + - `live-frontier`、`mock-openai`、`aimock` のプロバイダーモードをサポートします。`aimock` は、ローカルの AIMock ベースプロバイダーサーバーを起動し、シナリオ対応の `mock-openai` レーンを置き換えることなく、実験的なフィクスチャおよびプロトコルモックのカバレッジに使えます。 - `pnpm openclaw qa suite --runner multipass` - - 同じQAスイートを使い捨てのMultipass Linux VM内で実行します。 + - 同じ QA スイートを使い捨ての Multipass Linux VM 内で実行します。 - ホスト上の `qa suite` と同じシナリオ選択動作を維持します。 - - `qa suite` と同じprovider/model選択フラグを再利用します。 - - Live実行では、guestにとって実用的なサポート済みQA認証入力が転送されます: - envベースのprovider keys、QA live provider config path、および存在する場合の `CODEX_HOME`。 - - output dirsは、guestがマウントされたworkspace経由で書き戻せるように、リポジトリルート配下に維持する必要があります。 - - 通常のQA report + summaryに加え、Multipass logsを - `.artifacts/qa-e2e/...` に書き込みます。 + - `qa suite` と同じプロバイダー/モデル選択フラグを再利用します。 + - live 実行では、ゲストで実用的なサポート対象の QA 認証入力を転送します: 環境変数ベースのプロバイダーキー、QA live プロバイダー設定パス、存在する場合の `CODEX_HOME`。 + - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に維持する必要があります。 + - 通常の QA レポート + サマリーに加え、Multipass ログを `.artifacts/qa-e2e/...` 配下に書き出します。 - `pnpm qa:lab:up` - - オペレーター形式のQA作業向けに、DockerバックのQAサイトを起動します。 + - オペレーター型の QA 作業向けに Docker ベースの QA サイトを起動します。 - `pnpm test:docker:npm-onboard-channel-agent` - - 現在のcheckoutからnpm tarballをビルドし、Docker内に - グローバルインストールし、非対話式のOpenAI API-keyオンボーディングを実行し、デフォルトでTelegramを設定し、Plugin有効化によって実行時依存関係がオンデマンドでインストールされることを確認し、doctorを実行し、モックされたOpenAI - endpointに対して1回のローカルagent turnを実行します。 - - 同じパッケージ済みインストールレーンをDiscordで実行するには、`OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使ってください。 + - 現在のチェックアウトから npm tarball をビルドし、Docker 内でグローバルインストールし、非対話の OpenAI API キーによるオンボーディングを実行し、デフォルトで Telegram を設定し、plugin の有効化で実行時依存関係がオンデマンドにインストールされることを確認し、doctor を実行し、モックされた OpenAI エンドポイントに対して 1 回のローカルエージェントターンを実行します。 + - 同じパッケージ済みインストールレーンを Discord で実行するには `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使ってください。 - `pnpm test:docker:bundled-channel-deps` - - 現在のOpenClawビルドをDocker内でpackしてインストールし、OpenAIを設定してGatewayを起動し、その後config編集で同梱channel/pluginsを有効化します。 - - セットアップ検出により未設定Pluginのランタイム依存関係が未インストールのまま維持されること、最初の設定済みGatewayまたはdoctor実行が各同梱Pluginのランタイム依存関係をオンデマンドでインストールすること、そして2回目の再起動ではすでに有効化された依存関係を再インストールしないことを確認します。 - - さらに、既知の古いnpmベースラインをインストールし、`openclaw update --tag ` を実行する前にTelegramを有効化し、候補版の - post-update doctorが、ハーネス側のpostinstall修復なしに、同梱channelランタイム依存関係を修復することを確認します。 + - 現在の OpenClaw ビルドを Docker で pack および install し、OpenAI が設定された状態で Gateway を起動し、その後、設定編集でバンドル済みチャネル/plugins を有効化します。 + - セットアップ検出によって未設定 plugin の実行時依存関係が存在しないままになり、最初に設定された Gateway または doctor 実行で各バンドル済み plugin の実行時依存関係がオンデマンドにインストールされ、2 回目の再起動ではすでに有効化済みの依存関係を再インストールしないことを確認します。 + - また、既知の古い npm ベースラインもインストールし、Telegram を有効化したうえで `openclaw update --tag ` を実行し、その候補版の更新後 doctor が、ハーネス側の postinstall 修復なしで、バンドル済みチャネルの実行時依存関係を修復することを確認します。 - `pnpm openclaw qa aimock` - - 直接のprotocolスモークテスト用に、ローカルAIMock provider serverのみを起動します。 + - ローカルの AIMock プロバイダーサーバーだけを起動し、直接的なプロトコルスモークテストを行います。 - `pnpm openclaw qa matrix` - - 使い捨てのDockerバックTuwunel homeserverに対して、Matrix live QAレーンを実行します。 - - このQA hostは現時点ではrepo/dev専用です。パッケージ版OpenClawインストールには - `qa-lab` が同梱されないため、`openclaw qa` は公開されません。 - - Repo checkoutでは、同梱runnerが直接ロードされ、別途Pluginインストール手順は不要です。 - - 3つの一時的なMatrix users（`driver`、`sut`、`observer`）と1つのプライベートルームを用意し、実際のMatrix PluginをSUT transportとして使うQA gateway childを起動します。 - - デフォルトでは固定された安定版Tuwunel image `ghcr.io/matrix-construct/tuwunel:v1.5.1` を使います。別のimageをテストする必要がある場合は `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` で上書きしてください。 - - Matrixは共有credential-source flagsを公開しません。これはこのレーンがローカルで使い捨てユーザーを用意するためです。 - - Matrix QA report、summary、observed-events artifact、および結合されたstdout/stderr output logを `.artifacts/qa-e2e/...` に書き込みます。 + - 使い捨ての Docker ベース Tuwunel homeserver に対して Matrix live QA レーンを実行します。 + - この QA ホストは現在 repo/dev 専用です。パッケージ化された OpenClaw インストールには `qa-lab` が含まれないため、`openclaw qa` は公開されません。 + - リポジトリチェックアウトでは、バンドル済みランナーを直接読み込むため、別途 plugin のインストール手順は不要です。 + - 一時的な Matrix ユーザー 3 人（`driver`、`sut`、`observer`）と 1 つのプライベートルームを用意し、その後、実際の Matrix plugin を SUT トランスポートとして使う QA Gateway 子プロセスを起動します。 + - デフォルトでは、固定された安定版 Tuwunel イメージ `ghcr.io/matrix-construct/tuwunel:v1.5.1` を使います。別のイメージをテストする必要がある場合は `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` で上書きしてください。 + - Matrix ではローカルで使い捨てユーザーを用意するため、共有 credential-source フラグは公開されません。 + - Matrix QA レポート、サマリー、observed-events 成果物、および結合された stdout/stderr 出力ログを `.artifacts/qa-e2e/...` 配下に書き出します。 - `pnpm openclaw qa telegram` - - envから受け取るdriverおよびSUT bot tokensを使って、実際のプライベートグループに対して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 modeを使い、プールされたleaseにオプトインするには `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定してください。 - - いずれかのシナリオが失敗すると、非ゼロで終了します。失敗終了コードなしでartifactが欲しい場合は `--allow-failures` を使ってください。 - - 同じプライベートグループ内に2つの異なるbotsが必要で、SUT botはTelegram usernameを公開している必要があります。 - - 安定したbot-to-bot観測のために、両方のbotsについて `@BotFather` でBot-to-Bot Communication Modeを有効にし、driver botがグループ内のbotトラフィックを観測できることを確認してください。 - - Telegram QA report、summary、およびobserved-messages artifactを `.artifacts/qa-e2e/...` に書き込みます。返信シナリオには、driver送信要求から観測されたSUT返信までのRTTが含まれます。 + - 環境変数から渡される driver および SUT ボットトークンを使って、実際のプライベートグループに対して Telegram live QA レーンを実行します。 + - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。グループ ID は数値の Telegram chat id である必要があります。 + - 共有プール認証情報には `--credential-source convex` をサポートします。通常は env モードを使い、プール lease を使うには `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定してください。 + - いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしで成果物だけ必要な場合は `--allow-failures` を使ってください。 + - 同じプライベートグループ内に 2 つの異なるボットが必要であり、SUT ボットは Telegram ユーザー名を公開している必要があります。 + - 安定した bot-to-bot 観測のために、両方のボットで `@BotFather` の Bot-to-Bot Communication Mode を有効にし、driver ボットがグループ内のボットトラフィックを観測できるようにしてください。 + - Telegram QA レポート、サマリー、および observed-messages 成果物を `.artifacts/qa-e2e/...` 配下に書き出します。返信シナリオには、driver の送信リクエストから観測された SUT の返信までの RTT が含まれます。 -Live transportレーンは、新しいtransportが逸脱しないよう、1つの標準契約を共有しています: +live トランスポートレーンは、新しいトランスポートでずれが生じないよう、1 つの標準契約を共有します。 -`qa-channel` は引き続き広範な合成QAスイートであり、live -transportカバレッジmatrixには含まれません。 +`qa-channel` は広範な合成 QA スイートのままであり、live トランスポートのカバレッジ matrix には含まれません。 -| レーン | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | +| レーン | Canary | メンションゲーティング | Allowlist ブロック | トップレベル返信 | 再起動後の再開 | スレッドのフォローアップ | スレッド分離 | リアクション観測 | ヘルプコマンド | | -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -### Convex経由の共有Telegram認証情報（v1） +### Convex を介した共有 Telegram 認証情報（v1） -`openclaw qa telegram` に対して `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）が有効な場合、 -QA labはConvexバックのプールから排他的leaseを取得し、 -レーン実行中はそのleaseにheartbeatを送り、終了時にleaseを解放します。 +`openclaw qa telegram` で `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）が有効な場合、QA lab は Convex ベースのプールから排他的 lease を取得し、レーン実行中はその lease に heartbeat を送り、終了時に lease を解放します。 -参照用のConvex project scaffold: +参考用 Convex プロジェクト scaffold: - `qa/convex-credential-broker/` -必須env vars: +必要な環境変数: - `OPENCLAW_QA_CONVEX_SITE_URL`（例: `https://your-deployment.convex.site`） -- 選択したroleに応じた1つのsecret: - - `maintainer` には `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` - - `ci` には `OPENCLAW_QA_CONVEX_SECRET_CI` -- Credential role selection: +- 選択したロール用の secret を 1 つ: + - `maintainer` 用の `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` + - `ci` 用の `OPENCLAW_QA_CONVEX_SECRET_CI` +- 認証情報ロールの選択: - CLI: `--credential-role maintainer|ci` - - Envデフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（CIではデフォルト `ci`、それ以外では `maintainer`） + - 環境変数のデフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（CI ではデフォルト `ci`、それ以外では `maintainer`） -任意のenv vars: +任意の環境変数: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS`（デフォルト `1200000`） - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS`（デフォルト `30000`） - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（デフォルト `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（デフォルト `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（デフォルト `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意のtrace id） -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` は、ローカル開発専用としてloopback `http://` Convex URLsを許可します。 +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意のトレース ID） +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` を設定すると、ローカル専用開発向けに loopback `http://` Convex URL を許可します。 -通常運用では `OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使うべきです。 +通常運用では `OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使う必要があります。 -メンテナー用の管理コマンド（pool add/remove/list）には、 -特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 +メンテナー用の管理コマンド（プール add/remove/list）には、特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 -メンテナー向けCLI helpers: +メンテナー向け CLI ヘルパー: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -176,87 +150,87 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -スクリプトやCI utilitiesで機械可読出力が必要な場合は `--json` を使ってください。 +スクリプトや CI ユーティリティで機械可読な出力が必要な場合は `--json` を使ってください。 -デフォルトendpoint契約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: +デフォルトのエンドポイント契約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: - `POST /acquire` - - Request: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - - Success: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` + - リクエスト: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` + - 成功: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - 枯渇/再試行可能: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - - Request: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - Success: `{ status: "ok" }`（または空の `2xx`） + - リクエスト: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` + - 成功: `{ status: "ok" }`（または空の `2xx`） - `POST /release` - - Request: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - - Success: `{ status: "ok" }`（または空の `2xx`） -- `POST /admin/add`（maintainer secretのみ） - - Request: `{ kind, actorId, payload, note?, status? }` - - Success: `{ status: "ok", credential }` -- `POST /admin/remove`（maintainer secretのみ） - - Request: `{ credentialId, actorId }` - - Success: `{ status: "ok", changed, credential }` - - Active lease guard: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（maintainer secretのみ） - - Request: `{ kind?, status?, includePayload?, limit? }` - - Success: `{ status: "ok", credentials, count }` + - リクエスト: `{ kind, ownerId, actorRole, credentialId, leaseToken }` + - 成功: `{ status: "ok" }`（または空の `2xx`） +- `POST /admin/add`（maintainer secret のみ） + - リクエスト: `{ kind, actorId, payload, note?, status? }` + - 成功: `{ status: "ok", credential }` +- `POST /admin/remove`（maintainer secret のみ） + - リクエスト: `{ credentialId, actorId }` + - 成功: `{ status: "ok", changed, credential }` + - アクティブ lease ガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list`（maintainer secret のみ） + - リクエスト: `{ kind?, status?, includePayload?, limit? }` + - 成功: `{ status: "ok", credentials, count }` -Telegram kindのpayload形式: +Telegram kind のペイロード形状: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` は数値のTelegram chat id文字列である必要があります。 -- `admin/add` は `kind: "telegram"` に対してこの形式を検証し、不正なpayloadを拒否します。 +- `groupId` は数値の Telegram chat id 文字列である必要があります。 +- `admin/add` は `kind: "telegram"` に対してこの形状を検証し、不正なペイロードを拒否します。 -### channelをQAに追加する +### QA へのチャネル追加 -Markdown QAシステムにchannelを追加するには、必要なのはちょうど2つだけです: +markdown QA システムにチャネルを追加するには、必要なものは正確に 2 つです。 -1. そのchannel用のtransport adapter -2. channel契約を実行するscenario pack +1. そのチャネル用のトランスポートアダプター。 +2. チャネル契約を検証するシナリオパック。 -共有の `qa-lab` hostがフローを所有できるなら、新しいトップレベルQAコマンドrootを追加してはいけません。 +共有 `qa-lab` ホストでフローを担える場合は、新しいトップレベル QA コマンドルートを追加しないでください。 -`qa-lab` は共有host mechanicsを所有します: +`qa-lab` は共有ホストの仕組みを担当します。 -- `openclaw qa` コマンドroot +- `openclaw qa` コマンドルート - スイートの起動と終了処理 -- worker concurrency -- artifact書き込み +- ワーカーの並行実行 +- 成果物の書き出し - レポート生成 -- scenario実行 -- 古い `qa-channel` scenarios用の互換エイリアス +- シナリオ実行 +- 古い `qa-channel` シナリオ向け互換エイリアス -Runner pluginsはtransport契約を所有します: +ランナー plugin はトランスポート契約を担当します。 -- `openclaw qa ` を共有の `qa` root配下にどのようにマウントするか -- そのtransport向けにGatewayをどのように設定するか -- readinessをどのように確認するか -- inbound eventsをどのように注入するか -- outbound messagesをどのように観測するか -- transcriptsと正規化されたtransport stateをどのように公開するか -- transportバックのactionsをどのように実行するか -- transport固有のリセットまたはクリーンアップをどのように扱うか +- `openclaw qa ` を共有 `qa` ルート配下にどのようにマウントするか +- そのトランスポート向けに Gateway をどのように設定するか +- 準備完了をどのように確認するか +- 受信イベントをどのように注入するか +- 送信メッセージをどのように観測するか +- transcript と正規化済みトランスポート状態をどのように公開するか +- トランスポートを使うアクションをどのように実行するか +- トランスポート固有のリセットまたはクリーンアップをどのように扱うか -新しいchannelの最小採用基準は次のとおりです: +新しいチャネルの最低採用基準は以下です。 -1. 共有の `qa` rootの所有者は `qa-lab` のままにする。 -2. transport runnerを共有の `qa-lab` host seam上に実装する。 -3. transport固有のmechanicsはrunner Pluginまたはchannel harness内に閉じ込める。 -4. 競合するrootコマンドを登録するのではなく、runnerを `openclaw qa ` としてマウントする。 - Runner pluginsは `openclaw.plugin.json` に `qaRunners` を宣言し、`runtime-api.ts` から対応する `qaRunnerCliRegistrations` 配列をexportする必要があります。 - `runtime-api.ts` は軽量に保ってください。遅延CLIおよびrunner実行は、別個のentrypointsの背後に置くべきです。 -5. テーマ別の `qa/scenarios/` ディレクトリ配下でmarkdown scenariosを作成または調整する。 -6. 新しいscenariosには汎用scenario helpersを使う。 -7. リポジトリが意図的な移行中でない限り、既存の互換エイリアスを動作させ続ける。 +1. 共有 `qa` ルートの所有者は `qa-lab` のままにする。 +2. 共有 `qa-lab` ホスト境界上にトランスポートランナーを実装する。 +3. トランスポート固有の仕組みはランナー plugin またはチャネルハーネス内に閉じ込める。 +4. 競合するルートコマンドを登録するのではなく、ランナーを `openclaw qa ` としてマウントする。 + ランナー plugin は `openclaw.plugin.json` で `qaRunners` を宣言し、`runtime-api.ts` から対応する `qaRunnerCliRegistrations` 配列を export する必要があります。 + `runtime-api.ts` は軽量に保ち、遅延 CLI とランナー実行は別々の entrypoint の背後に置いてください。 +5. テーマ別の `qa/scenarios/` ディレクトリ配下に markdown シナリオを作成または調整する。 +6. 新しいシナリオには汎用シナリオヘルパーを使う。 +7. リポジトリが意図的な移行を行っている場合を除き、既存の互換エイリアスを動作させ続ける。 -判断ルールは厳格です: +判断ルールは厳格です。 -- 動作を `qa-lab` で1回だけ表現できるなら、`qa-lab` に置く。 -- 動作が1つのchannel transportに依存するなら、そのrunner PluginまたはPlugin harnessに置く。 -- scenarioが複数channelで使える新しい能力を必要とするなら、`suite.ts` にchannel固有の分岐を入れるのではなく、汎用helperを追加する。 -- 動作が1つのtransportにしか意味を持たないなら、そのscenarioはtransport固有のままにし、それをscenario契約で明示する。 +- 振る舞いを `qa-lab` で 1 回だけ表現できるなら、`qa-lab` に置く。 +- 振る舞いが 1 つのチャネルトランスポートに依存するなら、そのランナー plugin または plugin ハーネスに置く。 +- シナリオが複数チャネルで使える新しい機能を必要とするなら、`suite.ts` にチャネル固有の分岐を追加するのではなく、汎用ヘルパーを追加する。 +- 振る舞いが 1 つのトランスポートでのみ意味を持つなら、そのシナリオはトランスポート固有のままにし、それをシナリオ契約で明示する。 -新しいscenariosに推奨される汎用helper名: +新しいシナリオ向けの推奨汎用ヘルパー名は以下です。 - `waitForTransportReady` - `waitForChannelReady` @@ -271,7 +245,7 @@ Runner pluginsはtransport契約を所有します: - `formatTransportTranscript` - `resetTransport` -既存scenarios向けの互換エイリアスは引き続き利用可能です。たとえば: +既存シナリオ向けの互換エイリアスも引き続き利用できます。対象には以下が含まれます。 - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -279,260 +253,259 @@ Runner pluginsはtransport契約を所有します: - `formatConversationTranscript` - `resetBus` -新しいchannel作業では、汎用helper名を使うべきです。 -互換エイリアスは、一斉移行を避けるために存在するのであって、新しいscenario作成のモデルではありません。 +新しいチャネル作業では汎用ヘルパー名を使ってください。 +互換エイリアスは、flag day 型の移行を避けるために存在しているのであって、新しいシナリオ作成の手本ではありません。 -## テストスイート（何がどこで実行されるか） +## テストスイート（どこで何が動くか） -スイートは「現実性が増していくもの」（そして不安定さ/コストも増すもの）として考えてください: +スイートは「現実性が増していくもの」（そして flakiness/コストも増していくもの）として考えてください。 ### Unit / integration（デフォルト） - コマンド: `pnpm test` -- 設定: 非対象指定実行では `vitest.full-*.config.ts` shardセットを使い、並列スケジューリングのためにmulti-project shardsをproject単位configへ展開することがあります -- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下のcore/unit inventories、および `vitest.unit.config.ts` で対象になっている許可済みの `ui` node tests -- スコープ: - - 純粋なunit tests - - プロセス内integration tests（gateway auth、routing、tooling、parsing、config） - - 既知のバグに対する決定的なリグレッション -- 期待事項: - - CIで実行される - - 実キーは不要 +- 設定: 対象未指定の実行では `vitest.full-*.config.ts` shard セットを使い、並列スケジューリングのためにマルチプロジェクト shard をプロジェクト単位の設定へ展開することがあります +- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下の core/unit インベントリと、`vitest.unit.config.ts` でカバーされる許可済みの `ui` Node テスト +- 範囲: + - 純粋な unit テスト + - プロセス内 integration テスト（Gateway 認証、ルーティング、ツール、パース、設定） + - 既知のバグに対する決定的な回帰テスト +- 想定: + - CI で実行される + - 実際のキーは不要 - 高速かつ安定しているべき -- Projectsに関する注記: - - 非対象指定の `pnpm test` は、1つの巨大なネイティブルートproject processの代わりに、12個の小さなshard configs（`core-unit-fast`、`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` は、multi-shard watchループが現実的でないため、引き続きネイティブルート `vitest.config.ts` project graphを使います。 - - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリ対象をまずscoped lanes経由にルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` では完全なルートproject起動コストを払わずに済みます。 - - `pnpm test:changed` は、差分がルーティング可能なsource/test filesだけに触れている場合、変更されたgit pathsを同じscoped lanesへ展開します。config/setup編集は引き続き広いroot-project再実行にフォールバックします。 - - `pnpm check:changed` は、狭い作業に対する通常のスマートローカルゲートです。差分をcore、core tests、extensions、extension tests、apps、docs、release metadata、toolingに分類し、一致するtypecheck/lint/test lanesを実行します。公開Plugin SDKおよびplugin-contractの変更には、extensionsがそれらのcore契約に依存しているため、extension validationも含まれます。release metadataだけのversion bumpは、最上位version field以外のpackage変更を拒否するガード付きで、フルスイートではなく対象を絞ったversion/config/root-dependency checksを実行します。 - - agents、commands、plugins、auto-reply helpers、`plugin-sdk`、および類似の純粋utility領域からのimport-lightなunit testsは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` laneへルーティングされます。状態を持つ/ランタイムが重いファイルは既存のlanesに留まります。 - - 選択された `plugin-sdk` および `commands` helper source filesも、changed-mode実行をそれらのlight lanesの明示的な隣接テストへマッピングするため、helper編集ではそのディレクトリ全体の重いスイートを再実行せずに済みます。 - - `auto-reply` は現在、3つの専用bucketを持ちます: トップレベルcore helpers、トップレベルの `reply.*` integration tests、そして `src/auto-reply/reply/**` サブツリーです。これにより、もっとも重いreply harness作業を安価なstatus/chunk/token testsから切り離せます。 -- Embedded runnerに関する注記: - - message-tool discovery inputsまたはCompaction runtime contextを変更する場合、 - 両レベルのカバレッジを維持してください。 - - 純粋なrouting/normalization境界には、対象を絞ったhelper regressionを追加してください。 - - さらに、embedded runner integration suitesも健全に保ってください: +- プロジェクトに関する注記: + - 対象未指定の `pnpm test` は、1 つの巨大なネイティブルートプロジェクトプロセスではなく、12 個の小さな shard 設定（`core-unit-fast`、`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/拡張機能の処理が無関係なスイートを圧迫するのを防ぎます。 + - `pnpm test --watch` は、マルチ shard の watch ループが現実的でないため、引き続きネイティブルートの `vitest.config.ts` プロジェクトグラフを使います。 + - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリ指定を先にスコープ付きレーンへ振り分けるため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` ではフルルートプロジェクト起動コストを払わずに済みます。 + - `pnpm test:changed` は、差分がルーティング可能なソース/テストファイルだけに触れている場合、変更された git パスを同じスコープ付きレーンに展開します。設定/セットアップの編集は、引き続き広いルートプロジェクト再実行にフォールバックします。 + - `pnpm check:changed` は、狭い範囲の作業に対する通常のスマートローカルゲートです。差分を core、core tests、extensions、extension tests、apps、docs、リリースメタデータ、tooling に分類し、対応する typecheck/lint/test レーンを実行します。公開 Plugin SDK と plugin-contract の変更には、拡張機能がそれらの core 契約に依存するため、拡張機能検証が含まれます。リリースメタデータのみのバージョン更新では、フルスイートではなく対象を絞った version/config/root-dependency チェックが実行され、トップレベルの version フィールド以外の package 変更を拒否するガードが入ります。 + - agents、commands、plugins、auto-reply ヘルパー、`plugin-sdk`、および同様の純粋なユーティリティ領域からの import が軽い unit テストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンを通ります。状態保持/ランタイム負荷の高いファイルは既存のレーンに残ります。 + - 一部の `plugin-sdk` および `commands` ヘルパーソースファイルでも、changed モード実行時に軽量レーン上の明示的な兄弟テストへマッピングするようになったため、ヘルパー編集でそのディレクトリ全体の重いスイートを再実行せずに済みます。 + - `auto-reply` には現在 3 つの専用バケットがあります: トップレベル core ヘルパー、トップレベルの `reply.*` integration テスト、および `src/auto-reply/reply/**` サブツリーです。これにより、最も重い reply ハーネス処理が軽量な status/chunk/token テストから切り離されます。 +- Embedded runner に関する注記: + - メッセージツール検出入力または Compaction ランタイムコンテキストを変更するときは、両レベルのカバレッジを維持してください。 + - 純粋なルーティング/正規化境界に対して、焦点を絞ったヘルパー回帰テストを追加してください。 + - さらに、embedded runner integration スイートも健全に保ってください: `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`、および `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - これらのスイートは、scoped idsとCompaction動作が実際の `run.ts` / `compact.ts` パスを通って流れ続けることを検証します。helper-only testsは、そのintegration pathsの十分な代替にはなりません。 -- Poolに関する注記: - - ベースVitest configのデフォルトは現在 `threads` です。 - - 共有Vitest configは `isolate: false` も固定しており、root projects、e2e、live configs全体で非分離runnerを使います。 - - ルートUI laneはその `jsdom` setupとoptimizerを維持しますが、現在は共有の非分離runner上でも動作します。 - - 各 `pnpm test` shardは、共有Vitest configから同じ `threads` + `isolate: false` デフォルトを継承します。 - - 共有の `scripts/run-vitest.mjs` launcherは、大規模ローカル実行中のV8 compile churnを減らすため、デフォルトでVitest child Node processesに `--no-maglev` も追加するようになりました。標準のV8動作と比較したい場合は `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 + - これらのスイートは、スコープ付き id と Compaction の挙動が実際の `run.ts` / `compact.ts` パスを通って流れ続けることを検証します。ヘルパーだけのテストは、これらの integration パスの十分な代替にはなりません。 +- プールに関する注記: + - ベースの Vitest 設定は現在デフォルトで `threads` です。 + - 共有 Vitest 設定では `isolate: false` も固定され、ルートプロジェクト、e2e、live 設定全体で非分離ランナーを使います。 + - ルート UI レーンは `jsdom` セットアップと optimizer を維持しますが、現在は共有の非分離ランナー上でも動作します。 + - 各 `pnpm test` shard は、共有 Vitest 設定から同じ `threads` + `isolate: false` デフォルトを継承します。 + - 共有の `scripts/run-vitest.mjs` ランチャーは現在、Vitest 子 Node プロセスに対してデフォルトで `--no-maglev` も追加し、大規模なローカル実行中の V8 コンパイルの揺れを減らします。標準の V8 挙動と比較したい場合は `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 - 高速ローカル反復に関する注記: - - `pnpm changed:lanes` は、差分がどのアーキテクチャlaneをトリガーするかを表示します。 - - pre-commit hookは、staged format/lintの後に `pnpm check:changed --staged` を実行するため、core専用のコミットでは、公開extension向け契約に触れない限りextension testコストを払いません。release metadata-only commitsは、対象を絞ったversion/config/root-dependency laneに留まります。 - - まったく同じstaged change setが、同等以上のゲートですでに検証済みなら、`scripts/committer --fast "" ` を使って、changed-scope hook再実行だけをスキップできます。staged format/lintは引き続き実行されます。handoffでは完了済みゲートを明記してください。これは、分離された不安定なhook failureを再実行してscoped proof付きで通過した後にも許容されます。 - - `pnpm test:changed` は、変更パスがきれいにより小さなスイートへマップされる場合、scoped lanesを経由します。 - - `pnpm test:max` と `pnpm test:changed:max` も同じルーティング動作を維持しつつ、worker上限だけが高くなります。 - - ローカルworker自動スケーリングは現在、意図的に保守的で、ホストのload averageがすでに高い場合にも抑制されるため、複数の同時Vitest実行による悪影響はデフォルトで少なくなります。 - - ベースVitest configはprojects/config filesを `forceRerunTriggers` としてマークするため、test wiringが変わったときでもchanged-mode再実行の正しさが保たれます。 - - configは、サポートされているhostsでは `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効なまま維持します。直接プロファイリング用に明示的なcache locationを1つ使いたい場合は `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 -- Perf-debugに関する注記: - - `pnpm test:perf:imports` はVitestのimport-duration reportingに加え、import-breakdown出力も有効にします。 - - `pnpm test:perf:imports:changed` は、`origin/main` 以降に変更されたファイルに対して同じprofiling viewをスコープします。 -- `pnpm test:perf:changed:bench -- --ref ` は、コミットされたその差分に対して、ルーティングされた `test:changed` とネイティブルートprojectパスを比較し、wall timeとmacOS max RSSを出力します。 -- `pnpm test:perf:changed:bench -- --worktree` は、現在のdirty treeを、変更ファイル一覧を `scripts/test-projects.mjs` とルートVitest config経由でルーティングしてベンチマークします。 - - `pnpm test:perf:profile:main` は、Vitest/Vite起動とtransform overhead用のmain-thread CPU profileを書き出します。 - - `pnpm test:perf:profile:runner` は、ファイル並列を無効にしたunit suite用のrunner CPU+heap profilesを書き出します。 + - `pnpm changed:lanes` は、差分がどのアーキテクチャレーンを引き起こすかを表示します。 + - pre-commit フックは staged の format/lint 後に `pnpm check:changed --staged` を実行するため、core のみのコミットは、公開された拡張機能向け契約に触れない限り拡張機能テストのコストを払いません。リリースメタデータのみのコミットは対象を絞った version/config/root-dependency レーンにとどまります。 + - まったく同じ staged 変更セットがすでに同等以上のゲートで検証済みであれば、`scripts/committer --fast "" ` を使って changed-scope フックの再実行だけをスキップできます。staged format/lint は引き続き実行されます。完了済みのゲートは handoff で明記してください。これは、分離された flaky なフック失敗を再実行し、スコープ付きの証拠で成功した場合にも許容されます。 + - `pnpm test:changed` は、変更されたパスが小さなスイートにきれいにマッピングされる場合、スコープ付きレーンを通ります。 + - `pnpm test:max` と `pnpm test:changed:max` は同じルーティング挙動を保ちつつ、より高いワーカー上限で動作します。 + - ローカルのワーカー自動スケーリングは現在意図的に保守的であり、ホストのロードアベレージがすでに高い場合にも抑制されるため、デフォルトで複数の同時 Vitest 実行による悪影響が減ります。 + - ベースの Vitest 設定では、テスト配線が変更されたときに changed モードの再実行が正しくなるよう、プロジェクト/設定ファイルを `forceRerunTriggers` としてマークしています。 + - この設定は、サポート対象ホストでは `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効のまま維持します。直接プロファイリング用に明示的な 1 つのキャッシュ場所を使いたい場合は `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 +- Perf-debug に関する注記: + - `pnpm test:perf:imports` は Vitest の import 所要時間レポートと import 内訳出力を有効にします。 + - `pnpm test:perf:imports:changed` は同じプロファイリング表示を `origin/main` 以降に変更されたファイルへスコープします。 +- `pnpm test:perf:changed:bench -- --ref ` は、そのコミット差分に対してルーティングされた `test:changed` とネイティブルートプロジェクト経路を比較し、wall time と macOS の最大 RSS を出力します。 +- `pnpm test:perf:changed:bench -- --worktree` は、変更済みファイル一覧を `scripts/test-projects.mjs` とルート Vitest 設定に通すことで、現在の未コミットツリーをベンチマークします。 + - `pnpm test:perf:profile:main` は、Vitest/Vite の起動と transform オーバーヘッドに対するメインスレッド CPU プロファイルを書き出します。 + - `pnpm test:perf:profile:runner` は、ファイル並列化を無効にした unit スイート向けに runner の CPU+heap プロファイルを書き出します。 -### Stability（gateway） +### Stability（Gateway） - コマンド: `pnpm test:stability:gateway` -- 設定: `vitest.gateway.config.ts`、1 workerに強制 -- スコープ: - - デフォルトでdiagnostics有効の実ループバックGatewayを起動 - - 診断event pathを通じて、合成gateway message、memory、およびlarge-payload churnを流し込む - - Gateway WS RPC経由で `diagnostics.stability` を照会 - - 診断stability bundle persistence helpersをカバー - - recorderが上限内に留まり、合成RSS samplesがpressure budget未満に収まり、sessionごとのqueue depthsがゼロまで戻ることを検証 -- 期待事項: - - CI-safeかつキー不要 - - stability-regression追跡用の狭いレーンであり、完全なGateway suiteの代替ではない +- 設定: `vitest.gateway.config.ts`、ワーカー 1 に固定 +- 範囲: + - デフォルトで diagnostics を有効にした実際の loopback Gateway を起動する + - 診断イベント経路を通じて、合成 Gateway メッセージ、メモリ、大きなペイロードの churn を流し込む + - Gateway WS RPC 経由で `diagnostics.stability` を問い合わせる + - 診断安定性バンドルの永続化ヘルパーをカバーする + - レコーダーが境界内に収まり、合成 RSS サンプルが圧力予算を下回り、セッションごとのキュー深度がゼロまで戻ることをアサートする +- 想定: + - CI で安全、キー不要 + - 安定性回帰の追跡用の狭いレーンであり、完全な Gateway スイートの代替ではない -### E2E（gateway smoke） +### E2E（Gateway スモーク） - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` -- ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`、および `extensions/` 配下の同梱Plugin E2E tests +- ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`、および `extensions/` 配下のバンドル済み plugin E2E テスト - ランタイムデフォルト: - - リポジトリの他と同様に、Vitest `threads` と `isolate: false` を使います。 - - 適応的workerを使います（CI: 最大2、ローカル: デフォルト1）。 - - console I/O overheadを減らすため、デフォルトでsilent modeで実行します。 -- 便利なoverride: - - worker数を強制するには `OPENCLAW_E2E_WORKERS=`（上限16）。 - - 詳細なconsole出力を再有効化するには `OPENCLAW_E2E_VERBOSE=1`。 -- スコープ: - - マルチインスタンスGatewayのend-to-end動作 - - WebSocket/HTTP surfaces、node pairing、およびより重いnetworking -- 期待事項: - - パイプラインで有効なときはCIで実行される - - 実キーは不要 - - unit testsより可動部が多い（遅くなることがある） + - リポジトリの他部分に合わせて、Vitest の `threads` と `isolate: false` を使います。 + - 適応型ワーカーを使います（CI: 最大 2、ローカル: デフォルト 1）。 + - コンソール I/O オーバーヘッドを減らすため、デフォルトで silent モードで実行します。 +- 便利な上書き: + - ワーカー数を強制する `OPENCLAW_E2E_WORKERS=`（上限 16）。 + - 詳細なコンソール出力を再有効化する `OPENCLAW_E2E_VERBOSE=1`。 +- 範囲: + - 複数インスタンス Gateway のエンドツーエンド挙動 + - WebSocket/HTTP サーフェス、Node ペアリング、より重いネットワーキング +- 想定: + - パイプラインで有効な場合は CI で実行される + - 実際のキーは不要 + - unit テストより可動部分が多い（遅くなることがある） -### E2E: OpenShell backend smoke +### E2E: OpenShell バックエンドスモーク - コマンド: `pnpm test:e2e:openshell` - ファイル: `extensions/openshell/src/backend.e2e.test.ts` -- スコープ: - - ホスト上でDocker経由の分離されたOpenShell Gatewayを起動 - - 一時的なローカルDockerfileからsandboxを作成 - - 実際の `sandbox ssh-config` + SSH execを通じて、OpenClawのOpenShell backendを実行 - - sandbox fs bridgeを通じて、remote-canonical filesystem動作を検証 -- 期待事項: - - オプトイン専用であり、デフォルトの `pnpm test:e2e` 実行には含まれない - - ローカルの `openshell` CLIと動作するDocker daemonが必要 - - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テストGatewayとsandboxを破棄する -- 便利なoverride: - - 広いe2eスイートを手動実行するときにこのテストを有効化するには `OPENCLAW_E2E_OPENSHELL=1` - - デフォルト以外のCLI binaryまたはwrapper scriptを指定するには `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` +- 範囲: + - Docker 経由でホスト上に分離された OpenShell Gateway を起動します + - 一時的なローカル Dockerfile から sandbox を作成します + - 実際の `sandbox ssh-config` + SSH exec を介して OpenClaw の OpenShell バックエンドを検証します + - sandbox fs bridge を通じて、リモート正規形のファイルシステム挙動を検証します +- 想定: + - 明示的に有効化した場合のみであり、デフォルトの `pnpm test:e2e` 実行には含まれません + - ローカルの `openshell` CLI と、動作する Docker デーモンが必要です + - 分離された `HOME` / `XDG_CONFIG_HOME` を使い、その後テスト Gateway と sandbox を破棄します +- 便利な上書き: + - 広い e2e スイートを手動実行するときにこのテストを有効にする `OPENCLAW_E2E_OPENSHELL=1` + - デフォルト以外の CLI バイナリまたはラッパースクリプトを指定する `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` -### Live（実provider + 実models） +### Live（実際のプロバイダー + 実際のモデル） - コマンド: `pnpm test:live` - 設定: `vitest.live.config.ts` -- ファイル: `src/**/*.live.test.ts`、`test/**/*.live.test.ts`、および `extensions/` 配下の同梱Plugin live tests -- デフォルト: `pnpm test:live` により**有効**（`OPENCLAW_LIVE_TEST=1` を設定） -- スコープ: - - 「このprovider/modelは、今日、実際の認証情報で本当に動くか?」 - - providerフォーマット変更、tool-callingの癖、auth問題、rate limit動作を検出 -- 期待事項: - - 設計上CI安定ではない（実ネットワーク、実providerポリシー、クォータ、障害） - - コストがかかる / rate limitsを消費する - - 「全部」ではなく、対象を絞ったsubset実行を優先する -- Live実行では、不足しているAPI keysを拾うために `~/.profile` をsourceします。 -- デフォルトでは、live実行は依然として `HOME` を分離し、config/auth materialを一時テストhomeへコピーするため、unit fixturesが実際の `~/.openclaw` を変更できません。 -- liveテストで意図的に実際のhome directoryを使う必要がある場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 -- `pnpm test:live` は現在、より静かなモードがデフォルトです。`[live] ...` の進捗出力は維持しますが、追加の `~/.profile` 通知を抑制し、gateway bootstrap logs/Bonjour chatterをミュートします。完全な起動ログが欲しい場合は `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ごとのoverrideとして `OPENCLAW_LIVE_*_KEY` を使えます。テストはrate limitレスポンス時に再試行します。 -- 進捗/heartbeat出力: - - Liveスイートは現在、stderrに進捗行を出力するため、Vitestのconsole captureが静かでも長いprovider呼び出しが動作中であることが見えます。 - - `vitest.live.config.ts` はVitestのconsole interceptionを無効にするため、provider/gatewayの進捗行はlive実行中に即座にストリームされます。 - - 直接modelのheartbeatは `OPENCLAW_LIVE_HEARTBEAT_MS` で調整します。 - - gateway/probe heartbeatは `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 +- ファイル: `src/**/*.live.test.ts`、`test/**/*.live.test.ts`、および `extensions/` 配下のバンドル済み plugin live テスト +- デフォルト: `pnpm test:live` により **有効**（`OPENCLAW_LIVE_TEST=1` を設定） +- 範囲: + - 「このプロバイダー/モデルは、今日、実際の認証情報で本当に動くか？」 + - プロバイダーのフォーマット変更、ツール呼び出しの癖、認証の問題、レート制限の挙動を検出する +- 想定: + - 設計上、CI で安定しない（実際のネットワーク、実際のプロバイダーポリシー、クォータ、障害） + - お金がかかる / レート制限を消費する + - 「全部」ではなく、対象を絞ったサブセットの実行を優先する +- live 実行では、足りない API キーを拾うために `~/.profile` を source します。 +- デフォルトでは、live 実行でも引き続き `HOME` を分離し、設定/認証情報を一時的なテスト home にコピーするため、unit フィクスチャが実際の `~/.openclaw` を変更することはありません。 +- live テストで意図的に実際の home ディレクトリを使う必要がある場合にのみ `OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 +- `pnpm test:live` は現在、より静かなモードがデフォルトです: `[live] ...` の進捗出力は維持しますが、追加の `~/.profile` 通知を抑制し、Gateway の bootstrap ログ/Bonjour の雑音をミュートします。完全な起動ログを戻したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 +- API キーのローテーション（プロバイダー別）: `*_API_KEYS` をカンマ/セミコロン形式で設定するか、`*_API_KEY_1`、`*_API_KEY_2` を使います（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）。または live 専用上書きとして `OPENCLAW_LIVE_*_KEY` を使います。テストはレート制限応答時に再試行します。 +- 進捗/Heartbeat 出力: + - live スイートは現在、長いプロバイダー呼び出しが、Vitest のコンソールキャプチャが静かな場合でも動作中だとわかるよう、進捗行を stderr に出力します。 + - `vitest.live.config.ts` は Vitest のコンソールインターセプトを無効にしているため、プロバイダー/Gateway の進捗行は live 実行中に即座にストリームされます。 + - 直接モデルの Heartbeat は `OPENCLAW_LIVE_HEARTBEAT_MS` で調整します。 + - Gateway/プローブの Heartbeat は `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 -## どのスイートを実行すべきか? +## どのスイートを実行すべきか？ -この判断表を使ってください: +以下の判断表を使ってください。 -- ロジック/テストを編集した: `pnpm test` を実行（大きく変更したなら `pnpm test:coverage` も） -- Gateway networking / WS protocol / pairingに触れた: `pnpm test:e2e` を追加 -- 「botが落ちている」/ provider固有の障害 / tool callingをデバッグしている: 対象を絞った `pnpm test:live` を実行 +- ロジック/テストを編集する: `pnpm test` を実行する（大きく変更した場合は `pnpm test:coverage` も） +- Gateway のネットワーキング / WS プロトコル / ペアリングに触れる: `pnpm test:e2e` も追加する +- 「ボットが落ちている」/ プロバイダー固有の障害 / ツール呼び出しをデバッグする: 対象を絞った `pnpm test:live` を実行する -## Live: Android Node capability sweep +## Live: Android Node 機能一括確認 - テスト: `src/gateway/android-node.capabilities.live.test.ts` - スクリプト: `pnpm android:test:integration` -- 目的: 接続されたAndroid Nodeが**現在公開しているすべてのコマンド**を呼び出し、コマンド契約動作を検証する。 -- スコープ: - - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/起動/ペアリングは行わない）。 - - 選択されたAndroid Nodeに対する、コマンドごとのgateway `node.invoke` 検証。 -- 必須の事前セットアップ: - - AndroidアプリがすでにGatewayへ接続 + ペアリングされていること。 - - アプリをforegroundに保つこと。 - - 通過させたいcapabilitiesに対する権限/キャプチャ同意が付与されていること。 -- 任意の対象override: - - `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) +- 目的: 接続された Android Node が現在公開している **すべてのコマンド** を呼び出し、コマンド契約の挙動をアサートすること。 +- 範囲: + - 事前条件つき/手動セットアップ（このスイートはアプリのインストール/起動/ペアリングは行いません）。 + - 選択した Android Node に対する、コマンド単位の Gateway `node.invoke` 検証。 +- 必要な事前セットアップ: + - Android アプリがすでに Gateway に接続済みかつペアリング済みであること。 + - アプリがフォアグラウンドのままであること。 + - 成功を期待する機能に対して、権限/キャプチャ同意が付与されていること。 +- 任意のターゲット上書き: + - `OPENCLAW_ANDROID_NODE_ID` または `OPENCLAW_ANDROID_NODE_NAME`。 + - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。 +- Android の完全なセットアップ詳細: [Android アプリ](/ja-JP/platforms/android) -## Live: model smoke（profile keys） +## Live: モデルスモーク（プロファイルキー） -Liveテストは、障害を切り分けられるよう、2層に分かれています: +live テストは、障害を切り分けられるよう 2 層に分かれています。 -- 「Direct model」は、そのprovider/modelが与えられたkeyでとにかく応答できるかを示します。 -- 「Gateway smoke」は、そのmodelに対してフルのgateway+agent pipelineが動作するか（sessions、history、tools、sandbox policyなど）を示します。 +- 「直接モデル」は、そのキーでプロバイダー/モデルがそもそも応答できるかを示します。 +- 「Gateway スモーク」は、そのモデルに対して完全な Gateway+エージェントパイプライン（セッション、履歴、ツール、sandbox ポリシーなど）が動作するかを示します。 -### レイヤー1: Direct model completion（gatewayなし） +### レイヤー 1: 直接モデル補完（Gateway なし） - テスト: `src/agents/models.profiles.live.test.ts` - 目的: - - 発見されたmodelsを列挙する - - `getApiKeyForModel` を使って、認証情報を持つmodelsを選ぶ - - modelごとに小さなcompletionを実行する（必要に応じて対象を絞ったリグレッションも） + - 検出されたモデルを列挙する + - `getApiKeyForModel` を使って、認証情報を持っているモデルを選択する + - モデルごとに小さな補完を実行する（必要に応じて対象回帰も） - 有効化方法: - - `pnpm test:live`（またはVitestを直接呼ぶ場合は `OPENCLAW_LIVE_TEST=1`） -- このスイートを実際に実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、modernのエイリアス）を設定します。そうしないと、`pnpm test:live` をgateway smokeに集中させるためスキップされます -- model選択方法: - - modern allowlistを実行するには `OPENCLAW_LIVE_MODELS=modern`（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - - `OPENCLAW_LIVE_MODELS=all` はmodern allowlistのエイリアス - - または `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（カンマ区切りallowlist） - - modern/all sweepは、デフォルトでは高シグナルな厳選上限数を使います。網羅的なmodern sweepには `OPENCLAW_LIVE_MAX_MODELS=0`、より小さい上限には正の数を設定します。 -- provider選択方法: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（カンマ区切りallowlist） -- keyの取得元: - - デフォルト: profile storeとenv fallbacks - - **profile storeのみ**を強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - `pnpm test:live`（または Vitest を直接呼ぶ場合は `OPENCLAW_LIVE_TEST=1`） +- このスイートを実際に実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、modern のエイリアス）を設定します。そうしないと `pnpm test:live` の焦点を Gateway スモークに保つためスキップされます +- モデル選択方法: + - モダン 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` はモダン allowlist のエイリアスです + - または `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（カンマ区切り allowlist） + - modern/all 一括実行はデフォルトで厳選された高シグナル上限を使います。網羅的なモダン一括実行には `OPENCLAW_LIVE_MAX_MODELS=0` を設定し、より小さい上限には正の数を設定してください。 +- プロバイダー選択方法: + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（カンマ区切り allowlist） +- キーの取得元: + - デフォルト: プロファイルストアと環境変数フォールバック + - **プロファイルストアのみ** を強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` を設定します - これが存在する理由: - - 「provider APIが壊れている / keyが無効」と「gateway agent pipelineが壊れている」を分離する - - 小さく分離されたリグレッションを収める（例: OpenAI Responses/Codex Responsesのreasoning replay + tool-call flows） + - 「プロバイダー API が壊れている / キーが無効」と「Gateway エージェントパイプラインが壊れている」を切り分ける + - 小さく分離された回帰を収める（例: OpenAI Responses/Codex Responses の推論リプレイ + ツール呼び出しフロー） -### レイヤー2: Gateway + dev agent smoke（`@openclaw` が実際に行うこと） +### レイヤー 2: Gateway + dev エージェントスモーク（`@openclaw` が実際に行うこと） - テスト: `src/gateway/gateway-models.profiles.live.test.ts` - 目的: - - プロセス内Gatewayを起動 - - `agent:dev:*` sessionを作成/patchする（実行ごとにmodel override） - - keyを持つmodelsを走査し、次を検証する: - - 「意味のある」応答（toolsなし） - - 実際のtool呼び出しが動作する（read probe） - - 任意の追加tool probes（exec+read probe） - - OpenAIリグレッションパス（tool-call-only → follow-up）が動作し続ける -- Probe詳細（障害をすぐ説明できるように）: - - `read` probe: テストはworkspaceに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` + - プロセス内 Gateway を起動する + - `agent:dev:*` セッションを作成/patch する（実行ごとにモデル上書き） + - キー付きモデルを反復し、以下をアサートする: + - 「意味のある」応答（ツールなし） + - 実際のツール呼び出しが動作する（read プローブ） + - 任意の追加ツールプローブ（exec+read プローブ） + - OpenAI の回帰パス（ツール呼び出しのみ → フォローアップ）が動作し続ける +- プローブ詳細（障害をすばやく説明できるように）: + - `read` プローブ: テストがワークスペースに nonce ファイルを書き込み、エージェントにそれを `read` して nonce をそのまま返すよう求めます。 + - `exec+read` プローブ: テストがエージェントに、一時ファイルへ nonce を `exec` で書き込み、その後それを `read` で読み戻すよう求めます。 + - image プローブ: テストが生成した PNG（猫 + ランダムコード）を添付し、モデルが `cat ` を返すことを期待します。 + - 実装参照: `src/gateway/gateway-models.profiles.live.test.ts` と `src/gateway/live-image-probe.ts`。 - 有効化方法: - - `pnpm test:live`（またはVitestを直接呼ぶ場合は `OPENCLAW_LIVE_TEST=1`） -- model選択方法: - - デフォルト: 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`、より小さい上限には正の数を設定します。 -- provider選択方法（「OpenRouter全部」を避ける）: - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（カンマ区切りallowlist） -- Tool + image probesはこのliveテストでは常時オン: - - `read` probe + `exec+read` probe（tool stress） - - modelがimage input対応を公開している場合、image probeが実行される - - フロー（高レベル）: - - テストは「CAT」+ ランダムコードを含む小さなPNGを生成する（`src/gateway/live-image-probe.ts`） - - `agent` に `attachments: [{ mimeType: "image/png", content: "" }]` として送信 - - Gatewayがattachmentsを `images[]` に解析する（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） - - Embedded agentがマルチモーダルのユーザーメッセージをmodelへ転送する - - 検証: 返信に `cat` + そのコードが含まれる（OCR許容: 軽微な誤りは許可） + - `pnpm test:live`（または Vitest を直接呼ぶ場合は `OPENCLAW_LIVE_TEST=1`） +- モデル選択方法: + - デフォルト: モダン allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` はモダン allowlist のエイリアスです + - または絞り込みのために `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（またはカンマ区切りリスト）を設定します + - modern/all Gateway 一括実行はデフォルトで厳選された高シグナル上限を使います。網羅的なモダン一括実行には `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` を設定し、より小さい上限には正の数を設定してください。 +- プロバイダー選択方法（「OpenRouter の全部」を避ける）: + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（カンマ区切り allowlist） +- この live テストではツール + 画像プローブは常時有効です: + - `read` プローブ + `exec+read` プローブ（ツール負荷テスト） + - image プローブは、モデルが画像入力サポートを公開している場合に実行されます + - フロー（概要）: + - テストが「CAT」+ ランダムコードの小さな PNG を生成します（`src/gateway/live-image-probe.ts`） + - それを `agent` の `attachments: [{ mimeType: "image/png", content: "" }]` 経由で送信します + - Gateway は添付ファイルを `images[]` にパースします（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） + - Embedded エージェントがマルチモーダルなユーザーメッセージをモデルへ転送します + - アサーション: 返信に `cat` + そのコードが含まれます（OCR 許容: 軽微なミスは許容） -ヒント: 自分のマシンで何をテストできるか（そして正確な `provider/model` ids）を見るには、次を実行してください: +ヒント: 自分のマシンで何をテストできるか（および正確な `provider/model` id）を確認するには、以下を実行してください。 ```bash openclaw models list openclaw models list --json ``` -## Live: CLI backend smoke（Claude、Codex、Gemini、またはその他のローカルCLIs） +## Live: CLI バックエンドスモーク（Claude、Codex、Gemini、またはその他のローカル CLI） - テスト: `src/gateway/gateway-cli-backend.live.test.ts` -- 目的: デフォルトconfigに触れずに、ローカルCLI backendを使ってGateway + agent pipelineを検証する。 -- Backend固有のsmoke defaultsは、所有extensionの `cli-backend.ts` 定義にあります。 +- 目的: デフォルト設定には触れずに、ローカル CLI バックエンドを使って Gateway + エージェントパイプラインを検証すること。 +- バックエンド固有のスモークデフォルトは、所有する拡張機能の `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から取得される -- Overrides（任意）: + - デフォルトのプロバイダー/モデル: `claude-cli/claude-sonnet-4-6` + - コマンド/引数/画像挙動は、所有する CLI バックエンド plugin メタデータから取得されます。 +- 上書き（任意）: - `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`（pathはpromptへ注入される） - - prompt注入の代わりにimage file pathsをCLI argsとして渡すには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` - - `IMAGE_ARG` が設定されているときにimage argsの渡し方を制御するには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または `"list"`） - - 2回目のturnを送りresume flowを検証するには `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` - - デフォルトのClaude Sonnet -> Opus同一session継続性probeを無効にするには `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択modelがswitch targetをサポートするときに強制オンするには `1`） + - 実際の画像添付を送る `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`（パスはプロンプトに注入されます）。 + - プロンプト注入の代わりに画像ファイルパスを CLI 引数として渡す `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`。 + - `IMAGE_ARG` が設定されているときに、画像引数の渡し方を制御する `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または `"list"`）。 + - 2 回目のターンを送り、resume フローを検証する `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`。 + - デフォルトの Claude Sonnet -> Opus 同一セッション継続性プローブを無効にする `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択したモデルが切り替え先をサポートしているときに強制有効化するには `1` を設定）。 例: @@ -542,13 +515,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Dockerレシピ: +Docker レシピ: ```bash pnpm test:docker:live-cli-backend ``` -単一provider用Dockerレシピ: +単一プロバイダー向け Docker レシピ: ```bash pnpm test:docker:live-cli-backend:claude @@ -559,30 +532,30 @@ pnpm test:docker:live-cli-backend:gemini 注記: -- Docker runnerは `scripts/test-live-cli-backend-docker.sh` にあります。 -- これはリポジトリDocker image内で、非rootの `node` ユーザーとしてlive CLI-backend smokeを実行します。 -- 所有extensionからCLI smoke metadataを解決し、その後、対応するLinux CLI package（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）を、`OPENCLAW_DOCKER_CLI_TOOLS_DIR`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）のキャッシュ可能で書き込み可能なprefixへインストールします。 -- `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 varsを保持せずに2回のGateway CLI-backend turnを実行します。このsubscriptionレーンでは、Claudeが現在サードパーティアプリ利用を通常のsubscription plan limitsではなく追加利用課金へルーティングするため、Claude MCP/toolおよびimage probesはデフォルトで無効です。 -- Live CLI-backend smokeは現在、Claude、Codex、Geminiに対して同じend-to-endフローを実行します: テキストturn、画像分類turn、その後gateway CLI経由で検証されるMCP `cron` tool call。 -- Claudeのデフォルトsmokeでは、sessionをSonnetからOpusへpatchし、再開されたsessionが以前のメモをまだ覚えていることも検証します。 +- Docker ランナーは `scripts/test-live-cli-backend-docker.sh` にあります。 +- これはリポジトリの Docker イメージ内で、非 root の `node` ユーザーとして live CLI バックエンドスモークを実行します。 +- 所有拡張機能から CLI スモークメタデータを解決し、その後、対応する Linux CLI パッケージ（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）を、`OPENCLAW_DOCKER_CLI_TOOLS_DIR`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）のキャッシュされた書き込み可能プレフィックスにインストールします。 +- `pnpm test:docker:live-cli-backend:claude-subscription` では、`~/.claude/.credentials.json` にある `claudeAiOauth.subscriptionType` 付きのポータブル Claude Code subscription OAuth、または `claude setup-token` の `CLAUDE_CODE_OAUTH_TOKEN` が必要です。まず Docker 内で直接 `claude -p` を検証し、その後 Anthropic API キー環境変数を保持せずに 2 回の Gateway CLI バックエンドターンを実行します。この subscription レーンでは、Claude が現在、通常の subscription プラン制限ではなく追加使用量課金経由でサードパーティアプリ使用を処理するため、Claude MCP/ツールおよび image プローブはデフォルトで無効化されます。 +- live CLI バックエンドスモークは現在、Claude、Codex、Gemini に対して同じエンドツーエンドフローを検証します: テキストターン、画像分類ターン、その後 Gateway CLI 経由で検証される MCP `cron` ツール呼び出し。 +- Claude のデフォルトスモークでは、セッションを Sonnet から Opus へ patch し、再開されたセッションが以前のメモを引き続き記憶していることも検証します。 -## Live: ACP bind smoke（`/acp spawn ... --bind here`） +## Live: ACP bind スモーク（`/acp spawn ... --bind here`） - テスト: `src/gateway/gateway-acp-bind.live.test.ts` -- 目的: live ACP agentを使って、実際のACP会話bindフローを検証する: - - `/acp spawn --bind here` を送信 - - 合成のmessage-channel会話をその場でbind - - 同じ会話上で通常のfollow-upを送信 - - そのfollow-upがbind済みACP session transcriptに到達することを検証 +- 目的: live ACP エージェントを使って、実際の ACP conversation-bind フローを検証すること: + - `/acp spawn --bind here` を送る + - 合成メッセージチャネル会話をその場で bind する + - 同じ会話上で通常のフォローアップを送る + - フォローアップが bind 済み ACP セッション transcript に入ることを検証する - 有効化: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - デフォルト: - - Docker内のACP agents: `claude,codex,gemini` - - 直接の `pnpm test:live ...` 用ACP agent: `claude` - - 合成channel: Slack DM形式の会話コンテキスト - - ACP backend: `acpx` -- Overrides: + - Docker 内の ACP エージェント: `claude,codex,gemini` + - 直接 `pnpm test:live ...` 用の ACP エージェント: `claude` + - 合成チャネル: Slack DM 風の会話コンテキスト + - ACP バックエンド: `acpx` +- 上書き: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` @@ -590,8 +563,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4` - 注記: - - このレーンは、admin専用の合成originating-route fields付きのgateway `chat.send` surfaceを使うため、外部配信を装わずにmessage-channelコンテキストをテストが付加できます。 - - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、テストは選択されたACP harness agentに対して、埋め込み `acpx` Pluginの組み込みagent registryを使います。 + - このレーンは、管理者専用の合成 originating-route フィールド付きの Gateway `chat.send` サーフェスを使うため、テストは外部配信を装わずにメッセージチャネルコンテキストを付与できます。 + - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、このテストは選択した ACP ハーネスエージェントに対して、組み込みの `acpx` plugin の内蔵エージェントレジストリを使います。 例: @@ -601,13 +574,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Dockerレシピ: +Docker レシピ: ```bash pnpm test:docker:live-acp-bind ``` -単一agent用Dockerレシピ: +単一エージェント向け Docker レシピ: ```bash pnpm test:docker:live-acp-bind:claude @@ -615,37 +588,31 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Docker注記: +Docker に関する注記: -- Docker runnerは `scripts/test-live-acp-bind-docker.sh` にあります。 -- デフォルトでは、サポートされるすべてのlive CLI agentsに対してACP bind smokeを順番に実行します: `claude`、`codex`、`gemini`。 -- matrixを絞るには `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使ってください。 -- これは `~/.profile` をsourceし、一致するCLI auth materialをcontainerへstageし、書き込み可能なnpm prefixへ `acpx` をインストールし、その後必要なら要求されたlive CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）をインストールします。 -- Docker内では、runnerは `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` を設定するため、acpxはsourceされたprofileからのprovider env varsを子harness CLIで利用可能なまま維持します。 +- Docker ランナーは `scripts/test-live-acp-bind-docker.sh` にあります。 +- デフォルトでは、サポートされているすべての live CLI エージェントに対して順番に ACP bind スモークを実行します: `claude`、`codex`、その後 `gemini`。 +- matrix を絞り込むには、`OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使ってください。 +- これは `~/.profile` を source し、一致する CLI 認証情報をコンテナに stage し、`acpx` を書き込み可能な npm プレフィックスにインストールし、その後、必要であれば要求された 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 のプロバイダー環境変数を子ハーネス CLI から引き続き利用できます。 -## Live: Codex app-server harness smoke +## Live: Codex app-server ハーネススモーク -- 目的: 通常のgateway - `agent` メソッドを通じて、Plugin管理のCodex harnessを検証する: - - 同梱の `codex` Pluginをロード - - `OPENCLAW_AGENT_RUNTIME=codex` を選択 - - `codex/gpt-5.4` に最初のgateway agent turnを送信 - - 同じOpenClaw sessionに2回目のturnを送信し、app-server - threadがresumeできることを検証 - - 同じgateway command - pathを通じて `/codex status` と `/codex models` を実行 - - 任意で、Guardianレビュー付きの昇格shell probesを2つ実行: 1つは承認されるべき無害な - コマンド、もう1つは拒否されてagentが再確認すべき偽のsecret upload +- 目的: 通常の Gateway `agent` メソッドを通じて、plugin が所有する Codex ハーネスを検証すること: + - バンドル済み `codex` plugin を読み込む + - `OPENCLAW_AGENT_RUNTIME=codex` を選択する + - `codex/gpt-5.4` に最初の Gateway エージェントターンを送る + - 同じ OpenClaw セッションに 2 回目のターンを送り、app-server スレッドが再開できることを検証する + - 同じ Gateway コマンド経路を通じて `/codex status` と `/codex models` を実行する + - 必要に応じて、Guardian レビュー付きの昇格シェルプローブを 2 つ実行する: 承認されるべき無害なコマンド 1 つと、拒否されてエージェントが再確認を求めるべき偽の secret upload 1 つ - テスト: `src/gateway/gateway-codex-harness.live.test.ts` - 有効化: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- デフォルトmodel: `codex/gpt-5.4` -- 任意のimage probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- 任意のMCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- 任意のGuardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- このsmokeは `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を設定するため、壊れたCodex - harnessがPIへ静かにフォールバックして通過することはありません。 -- Auth: shell/profileからの `OPENAI_API_KEY`、および任意でコピーされる - `~/.codex/auth.json` と `~/.codex/config.toml` +- デフォルトモデル: `codex/gpt-5.4` +- 任意の image プローブ: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- 任意の MCP/ツールプローブ: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- 任意の Guardian プローブ: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- このスモークでは `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を設定するため、壊れた Codex ハーネスが PI への無言フォールバックで通過することはありません。 +- 認証: シェル/profile の `OPENAI_API_KEY` に加え、存在する場合は `~/.codex/auth.json` と `~/.codex/config.toml` もコピーされます ローカルレシピ: @@ -659,75 +626,68 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Dockerレシピ: +Docker レシピ: ```bash source ~/.profile pnpm test:docker:live-codex-harness ``` -Docker注記: +Docker に関する注記: -- Docker runnerは `scripts/test-live-codex-harness-docker.sh` にあります。 -- これはマウントされた `~/.profile` をsourceし、`OPENAI_API_KEY` を渡し、存在する場合はCodex CLI - auth filesをコピーし、書き込み可能なマウント済みnpm - prefixへ `@openai/codex` をインストールし、source treeをstageし、その後Codex-harness live testだけを実行します。 -- Dockerでは、image、MCP/tool、Guardian probesがデフォルトで有効です。より狭いデバッグ実行が必要な場合は - `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`、 - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`、または - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` を設定してください。 -- Dockerでも、live - test configと一致する `OPENCLAW_AGENT_HARNESS_FALLBACK=none` がexportされるため、`openai-codex/*` やPIフォールバックがCodex harness - regressionを隠すことはできません。 +- Docker ランナーは `scripts/test-live-codex-harness-docker.sh` にあります。 +- これはマウントされた `~/.profile` を source し、`OPENAI_API_KEY` を渡し、存在する場合は Codex CLI 認証ファイルをコピーし、`@openai/codex` を書き込み可能なマウント済み npm プレフィックスにインストールし、ソースツリーを stage してから、Codex ハーネス live テストだけを実行します。 +- Docker では image、MCP/ツール、Guardian の各プローブがデフォルトで有効です。より狭いデバッグ実行が必要な場合は、`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`、`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`、または `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` を設定してください。 +- Docker でも live テスト設定に合わせて `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を export するため、`openai-codex/*` や PI へのフォールバックが Codex ハーネスの回帰を隠すことはありません。 -### 推奨liveレシピ +### 推奨 live レシピ -狭く明示的なallowlistsがもっとも高速で不安定さも少ないです: +狭く、明示的な allowlist が最も高速で、flaky も少なくなります。 -- 単一model、直接（gatewayなし）: +- 単一モデル、直接（Gateway なし）: - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- 単一model、gateway smoke: +- 単一モデル、Gateway スモーク: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 複数providerにまたがる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）: - - Gemini（API key）: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Google 集中（Gemini API キー + Antigravity）: + - Gemini（API キー）: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - 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を使います（別個のauth + toolingの癖があります）。 -- Gemini APIとGemini CLI: - - API: OpenClawはGoogleのホストされたGemini APIをHTTP経由で呼びます（API key / profile auth）。多くのユーザーが「Gemini」と言うときに意味するのはこれです。 - - CLI: OpenClawはローカルの `gemini` binaryをシェル実行します。独自のauthを持ち、動作が異なることがあります（streaming/tool対応/version差異）。 +- `google/...` は Gemini API（API キー）を使います。 +- `google-antigravity/...` は Antigravity OAuth ブリッジ（Cloud Code Assist 風のエージェントエンドポイント）を使います。 +- `google-gemini-cli/...` はマシン上のローカル Gemini CLI を使います（認証とツール挙動の癖は別です）。 +- Gemini API と Gemini CLI: + - API: OpenClaw は Google がホストする Gemini API を HTTP 経由で呼びます（API キー / プロファイル認証）。多くのユーザーが「Gemini」と言うとき、通常はこちらを指します。 + - CLI: OpenClaw はローカルの `gemini` バイナリをシェル経由で実行します。独自の認証を持ち、挙動も異なることがあります（ストリーミング/ツールサポート/バージョン差異）。 -## Live: model matrix（何をカバーするか） +## Live: モデル matrix（何をカバーするか） -固定の「CI model list」はありません（liveはオプトイン）が、これらはキーを持つ開発マシンで定期的にカバーすることを**推奨する**modelsです。 +固定の「CI モデル一覧」はありません（live はオプトインです）が、これらはキーを持つ開発マシン上で定期的にカバーすることを **推奨** するモデルです。 -### Modern smoke set（tool calling + image） +### モダンスモークセット（ツール呼び出し + 画像） -これは、動作し続けることを期待する「一般的なmodels」実行です: +これは、動作し続けることを期待する「一般的なモデル」実行です。 -- OpenAI（non-Codex）: `openai/gpt-5.4`（任意: `openai/gpt-5.4-mini`） +- OpenAI（非 Codex）: `openai/gpt-5.4`（任意: `openai/gpt-5.4-mini`） - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6`（または `anthropic/claude-sonnet-4-6`） -- Google（Gemini API）: `google/gemini-3.1-pro-preview` と `google/gemini-3-flash-preview`（古いGemini 2.x modelsは避ける） +- Google（Gemini API）: `google/gemini-3.1-pro-preview` と `google/gemini-3-flash-preview`（古い Gemini 2.x モデルは避ける） - Google（Antigravity）: `google-antigravity/claude-opus-4-6-thinking` と `google-antigravity/gemini-3-flash` - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -tools + image付きでgateway smokeを実行: +ツール + 画像付きで Gateway スモークを実行: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### ベースライン: tool calling（Read + 任意のExec） +### ベースライン: ツール呼び出し（Read + 任意の Exec） -provider familyごとに少なくとも1つは選んでください: +各プロバイダーファミリーから少なくとも 1 つ選んでください。 - OpenAI: `openai/gpt-5.4`（または `openai/gpt-5.4-mini`） - Anthropic: `anthropic/claude-opus-4-6`（または `anthropic/claude-sonnet-4-6`） @@ -735,44 +695,44 @@ provider familyごとに少なくとも1つは選んでください: - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -任意の追加カバレッジ（あると良い）: +任意の追加カバレッジ（あるとよい）: -- xAI: `xai/grok-4`（または最新利用可能版） -- Mistral: `mistral/`…（有効化している「tools」対応modelを1つ選ぶ） +- xAI: `xai/grok-4`（または利用可能な最新版） +- Mistral: `mistral/`…（有効化済みの「tools」対応モデルを 1 つ選ぶ） - Cerebras: `cerebras/`…（アクセス権がある場合） -- LM Studio: `lmstudio/`…（ローカル。tool callingはAPI modeに依存） +- LM Studio: `lmstudio/`…（ローカル; ツール呼び出しは API モードに依存） -### Vision: 画像送信（attachment → マルチモーダルメッセージ） +### Vision: 画像送信（添付ファイル → マルチモーダルメッセージ） -image probeを実行するために、少なくとも1つのimage対応modelを `OPENCLAW_LIVE_GATEWAY_MODELS` に含めてください（Claude/Gemini/OpenAIのvision対応variantsなど）。 +画像プローブを検証するために、少なくとも 1 つの画像対応モデルを `OPENCLAW_LIVE_GATEWAY_MODELS` に含めてください（Claude/Gemini/OpenAI の画像対応バリアントなど）。 -### Aggregators / 代替gateways +### Aggregators / 代替 Gateway -キーが有効なら、次経由のテストもサポートしています: +キーが有効なら、以下経由のテストもサポートしています。 -- OpenRouter: `openrouter/...`（数百のmodels。tool+image対応候補を探すには `openclaw models scan` を使ってください） -- OpenCode: Zen用の `opencode/...` とGo用の `opencode-go/...`（authは `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`） +- OpenRouter: `openrouter/...`（数百のモデル; `openclaw models scan` を使ってツール + 画像対応候補を見つけてください） +- OpenCode: Zen 向け `opencode/...` と Go 向け `opencode-go/...`（認証は `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`） -Live matrixに含められる他のproviders（認証情報/設定がある場合）: +認証情報/設定があれば、live matrix に追加できるその他のプロバイダー: - 組み込み: `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` 経由（カスタムendpoints）: `minimax`（cloud/API）、および任意のOpenAI/Anthropic互換proxy（LM Studio、vLLM、LiteLLMなど） +- `models.providers` 経由（カスタムエンドポイント）: `minimax`（クラウド/API）、および OpenAI/Anthropic 互換プロキシ全般（LM Studio、vLLM、LiteLLM など） -ヒント: ドキュメントに「全models」をハードコードしようとしないでください。権威ある一覧は、あなたのマシン上で `discoverModels(...)` が返すもの + 利用可能なkeysです。 +ヒント: ドキュメントで「全モデル」をハードコードしようとしないでください。正式な一覧は、あなたのマシンで `discoverModels(...)` が返すものと、利用可能なキーの組み合わせです。 ## 認証情報（絶対にコミットしない） -Liveテストは、CLIと同じ方法で認証情報を検出します。実務上の意味: +live テストは、CLI と同じ方法で認証情報を検出します。実際上の意味は以下です。 -- CLIが動くなら、liveテストも同じkeysを見つけるはずです。 -- liveテストが「認証情報なし」と言う場合、`openclaw models list` / model選択をデバッグするときと同じ方法で調べてください。 +- CLI が動くなら、live テストも同じキーを見つけられるはずです。 +- live テストが「認証情報なし」と言うなら、`openclaw models list` / モデル選択をデバッグするときと同じ方法で調査してください。 -- agentごとのauth profiles: `~/.openclaw/agents//agent/auth-profiles.json`（liveテストで「profile keys」と言うときの意味はこれです） -- Config: `~/.openclaw/openclaw.json`（または `OPENCLAW_CONFIG_PATH`） -- レガシーstate dir: `~/.openclaw/credentials/`（存在する場合はstaged live homeへコピーされるが、メインのprofile-key storeではない） -- Liveローカル実行では、アクティブconfig、agentごとの `auth-profiles.json` files、レガシー `credentials/`、およびサポートされる外部CLI auth dirsを、デフォルトで一時テストhomeへコピーします。staged live homesでは `workspace/` と `sandboxes/` はスキップされ、`agents.*.workspace` / `agentDir` path overridesは取り除かれるため、probesが実際のホストworkspaceに触れません。 +- エージェントごとの認証プロファイル: `~/.openclaw/agents//agent/auth-profiles.json`（live テストでいう「プロファイルキー」はこれを意味します） +- 設定: `~/.openclaw/openclaw.json`（または `OPENCLAW_CONFIG_PATH`） +- 旧 state ディレクトリ: `~/.openclaw/credentials/`（存在する場合は stage 済み live home にコピーされますが、メインのプロファイルキーストアではありません） +- ローカルの live 実行では、デフォルトでアクティブ設定、エージェントごとの `auth-profiles.json`、旧 `credentials/`、およびサポート対象の外部 CLI 認証ディレクトリを一時的なテスト home にコピーします。stage 済み live home では `workspace/` と `sandboxes/` はスキップされ、`agents.*.workspace` / `agentDir` のパス上書きは取り除かれるため、プローブが実際のホスト workspace に触れません。 -env keys（たとえば `~/.profile` でexportされたもの）に依存したい場合は、`source ~/.profile` の後にローカルテストを実行するか、以下のDocker runnersを使ってください（containerへ `~/.profile` をマウントできます）。 +環境変数キー（たとえば `~/.profile` で export したもの）に依存したい場合は、`source ~/.profile` の後にローカルテストを実行するか、以下の Docker ランナーを使ってください（コンテナ内に `~/.profile` をマウントできます）。 ## Deepgram live（音声文字起こし） @@ -783,33 +743,33 @@ env keys（たとえば `~/.profile` でexportされたもの）に依存した - テスト: `extensions/byteplus/live.test.ts` - 有効化: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` -- 任意のmodel override: `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` パスを実行 - - `models.providers.comfy.` が設定されていない場合は各capabilityをスキップ - - comfy workflow送信、polling、downloads、またはPlugin登録を変更した後に有用 +- 範囲: + - バンドル済み comfy の画像、動画、および `music_generate` パスを検証します + - `models.providers.comfy.` が設定されていない限り、各機能をスキップします + - comfy ワークフロー送信、ポーリング、ダウンロード、または plugin 登録を変更した後に有用です -## Image generation live +## 画像生成 live - テスト: `test/image-generation.runtime.live.test.ts` - コマンド: `pnpm test:live test/image-generation.runtime.live.test.ts` -- Harness: `pnpm test:live:media image` -- スコープ: - - 登録されているすべての画像生成provider Pluginを列挙 - - probe前に、欠けているprovider env varsをログインシェル（`~/.profile`）から読み込む - - デフォルトでは、保存済みauth profilesよりlive/env API keysを優先するため、`auth-profiles.json` にある古いテストkeysが実際のシェル認証情報を隠しません - - 使用可能なauth/profile/modelがないprovidersはスキップ - - 共有ランタイムcapabilityを通して、標準の画像生成variantsを実行: +- ハーネス: `pnpm test:live:media image` +- 範囲: + - 登録されているすべての画像生成プロバイダー plugin を列挙します + - プローブ前に、ログインシェル（`~/.profile`）から不足しているプロバイダー環境変数を読み込みます + - デフォルトでは、保存済み認証プロファイルよりも live/env API キーを優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 利用可能な認証/プロファイル/モデルがないプロバイダーはスキップします + - 共有 runtime capability を通じて標準の画像生成バリアントを実行します: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- 現在カバーされる同梱providers: +- 現在カバーされているバンドル済みプロバイダー: - `fal` - `google` - `minimax` @@ -820,285 +780,251 @@ env keys（たとえば `~/.profile` でexportされたもの）に依存した - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` -- 任意のauth動作: - - profile-store authを強制し、env-only overridesを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 任意の認証動作: + - プロファイルストア認証を強制し、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` -- Harness: `pnpm test:live:media music` -- スコープ: - - 共有された同梱music-generation providerパスを実行 - - 現在はGoogleとMiniMaxをカバー - - probe前にprovider env varsをログインシェル（`~/.profile`）から読み込む - - デフォルトでは、保存済みauth profilesよりlive/env API keysを優先するため、`auth-profiles.json` にある古いテストkeysが実際のシェル認証情報を隠しません - - 使用可能なauth/profile/modelがないprovidersはスキップ - - 利用可能な場合、宣言された両方のランタイムモードを実行: - - prompt-only入力による `generate` - - providerが `capabilities.edit.enabled` を宣言している場合の `edit` +- ハーネス: `pnpm test:live:media music` +- 範囲: + - 共有のバンドル済み音楽生成プロバイダーパスを検証します + - 現在は Google と MiniMax をカバーしています + - プローブ前に、ログインシェル（`~/.profile`）からプロバイダー環境変数を読み込みます + - デフォルトでは、保存済み認証プロファイルよりも live/env API キーを優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 利用可能な認証/プロファイル/モデルがないプロバイダーはスキップします + - 利用可能な場合は、宣言された両方の runtime モードを実行します: + - プロンプトのみ入力の `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+"` -- 任意のauth動作: - - profile-store authを強制し、env-only overridesを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 任意の認証動作: + - プロファイルストア認証を強制し、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` -- Harness: `pnpm test:live:media video` -- スコープ: - - 共有された同梱video-generation providerパスを実行 - - デフォルトではリリース安全なsmokeパスを使います: FAL以外のproviders、providerごとに1つのtext-to-video request、1秒のロブスターprompt、そして `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` によるproviderごとのoperation cap（デフォルト `180000`） - - provider側queueレイテンシがリリース時間を支配しうるため、FALはデフォルトでスキップされます。明示的に実行するには `--video-providers fal` または `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` を渡してください - - probe前にprovider env varsをログインシェル（`~/.profile`）から読み込む - - デフォルトでは、保存済みauth profilesよりlive/env API keysを優先するため、`auth-profiles.json` にある古いテストkeysが実際のシェル認証情報を隠しません - - 使用可能なauth/profile/modelがないprovidersはスキップ - - デフォルトでは `generate` のみを実行 - - 利用可能な場合に宣言済みtransform modesも実行するには `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定: - - providerが `capabilities.imageToVideo.enabled` を宣言しており、選択したprovider/modelが共有sweepでbuffer-backedのローカル画像入力を受け入れる場合の `imageToVideo` - - providerが `capabilities.videoToVideo.enabled` を宣言しており、選択したprovider/modelが共有sweepでbuffer-backedのローカル動画入力を受け入れる場合の `videoToVideo` - - 共有sweepで現在宣言済みだがスキップされる `imageToVideo` providers: - - `vydra`。同梱の `veo3` はtext-onlyであり、同梱の `kling` はリモート画像URLを必要とするため - - Provider固有のVydraカバレッジ: +- ハーネス: `pnpm test:live:media video` +- 範囲: + - 共有のバンドル済み動画生成プロバイダーパスを検証します + - デフォルトではリリース安全なスモークパスを使います: 非 FAL プロバイダー、各プロバイダーあたり 1 回の text-to-video リクエスト、1 秒のロブスタープロンプト、および `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 由来のプロバイダーごとの操作上限（デフォルト `180000`） + - FAL は、プロバイダー側キュー待ち時間がリリース時間を支配する可能性があるため、デフォルトでスキップされます。明示的に実行するには `--video-providers fal` または `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` を渡してください + - プローブ前に、ログインシェル（`~/.profile`）からプロバイダー環境変数を読み込みます + - デフォルトでは、保存済み認証プロファイルよりも live/env API キーを優先するため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 利用可能な認証/プロファイル/モデルがないプロバイダーはスキップします + - デフォルトでは `generate` のみを実行します + - 利用可能な場合に宣言済みの transform モードも実行するには `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定します: + - プロバイダーが `capabilities.imageToVideo.enabled` を宣言し、選択されたプロバイダー/モデルが共有一括実行でバッファベースのローカル画像入力を受け付ける場合の `imageToVideo` + - プロバイダーが `capabilities.videoToVideo.enabled` を宣言し、選択されたプロバイダー/モデルが共有一括実行でバッファベースのローカル動画入力を受け付ける場合の `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` - - このファイルはデフォルトで `veo3` text-to-videoに加え、リモート画像URL fixtureを使う `kling` レーンを実行します - - 現在の `videoToVideo` liveカバレッジ: - - 選択modelが `runway/gen4_aleph` のときのみ `runway` - - 共有sweepで現在宣言済みだがスキップされる `videoToVideo` providers: - - `alibaba`、`qwen`、`xai`。これらのパスは現在リモートの `http(s)` / MP4 reference URLsを必要とするため - - `google`。現在の共有Gemini/Veoレーンはローカルbuffer-backed入力を使っており、そのパスは共有sweepでは受け入れられないため - - `openai`。現在の共有レーンには、org固有のvideo inpaint/remix access保証がないため + - このファイルは `veo3` の text-to-video に加え、デフォルトでリモート画像 URL fixture を使う `kling` レーンを実行します + - 現在の `videoToVideo` live カバレッジ: + - 選択モデルが `runway/gen4_aleph` の場合のみ `runway` + - 現在、共有一括実行で宣言済みだがスキップされる `videoToVideo` プロバイダー: + - これらのパスが現在リモート `http(s)` / MP4 参照 URL を必要とするため `alibaba`、`qwen`、`xai` + - 現在の共有 Gemini/Veo レーンがローカルのバッファベース入力を使っており、そのパスが共有一括実行では受け付けられないため `google` + - 現在の共有レーンには org 固有の動画 inpaint/remix アクセス保証がないため `openai` - 任意の絞り込み: - `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"` - - デフォルトsweepにFALを含むすべてのproviderを含めるには `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` - - より攻撃的なsmoke runのため、各provider operation capを減らすには `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` -- 任意のauth動作: - - profile-store authを強制し、env-only overridesを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - デフォルト一括実行に FAL を含むすべてのプロバイダーを含める `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` + - 攻めたスモーク実行向けに各プロバイダーの操作上限を下げる `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` +- 任意の認証動作: + - プロファイルストア認証を強制し、env のみの上書きを無視する `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Media live harness +## メディア live ハーネス - コマンド: `pnpm test:live:media` - 目的: - - 共有されたimage、music、videoのlive suitesを、1つのrepo-native entrypoint経由で実行 - - 欠けているprovider env varsを `~/.profile` から自動読み込み - - デフォルトで、現在使用可能なauthを持つprovidersへ各suiteを自動的に絞り込む - - `scripts/test-live.mjs` を再利用するため、heartbeatとquiet-mode動作が一貫する + - 共有の画像、音楽、動画 live スイートを、リポジトリ標準の 1 つの entrypoint から実行します + - `~/.profile` から不足しているプロバイダー環境変数を自動で読み込みます + - デフォルトで、現在利用可能な認証を持つプロバイダーに各スイートを自動的に絞り込みます + - `scripts/test-live.mjs` を再利用するため、Heartbeat と quiet-mode の挙動が一貫します - 例: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker runners（任意の「Linuxでも動く」確認） +## Docker ランナー（任意の「Linux で動く」確認） -これらのDocker runnersは2つのカテゴリに分かれます: +これらの Docker ランナーは 2 つのバケットに分かれます。 -- Live-model runners: `test:docker:live-models` と `test:docker:live-gateway` は、それぞれ対応するprofile-key liveファイルだけをrepo Docker image内で実行します（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）。ローカルconfig dirとworkspaceをマウントし（マウントされていれば `~/.profile` もsource）、対応するローカルentrypointsは `test:live:models-profiles` と `test:live:gateway-profiles` です。 -- Docker live runnersは、完全なDocker sweepが現実的なままであるよう、デフォルトでより小さいsmoke capを使います: - `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 imageを1回ビルドし、その後それを2つのlive Docker lanesで再利用します。さらに、`test:docker:e2e-build` で共有の `scripts/e2e/Dockerfile` imageを1つビルドし、ビルド済みアプリを実行するE2E container smoke runnersで再利用します。 -- Container smoke runners: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update`、`test:docker:config-reload` は、1つ以上の実コンテナを起動し、より高レベルなintegration pathsを検証します。 +- live モデルランナー: `test:docker:live-models` と `test:docker:live-gateway` は、リポジトリ Docker イメージ内で対応するプロファイルキー live ファイルのみを実行します（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）。対応するローカル entrypoint は `test:live:models-profiles` と `test:live:gateway-profiles` です。 +- Docker live ランナーは、フル Docker 一括実行を現実的に保つため、より小さなスモーク上限をデフォルトにしています: + `test:docker:live-models` はデフォルトで `OPENCLAW_LIVE_MAX_MODELS=12`、`test:docker:live-gateway` はデフォルトで `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`、および `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` を使います。より大きな網羅的スキャンを明示的に望む場合は、それらの環境変数を上書きしてください。 +- `test:docker:all` は、まず `test:docker:live-build` 経由で live Docker イメージを 1 回ビルドし、その後 2 つの live Docker レーンで再利用します。また、`test:docker:e2e-build` 経由で共有の `scripts/e2e/Dockerfile` イメージを 1 回ビルドし、ビルド済みアプリを検証する E2E コンテナスモークランナーで再利用します。 +- コンテナスモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update`、および `test:docker:config-reload` は、1 つ以上の実コンテナを起動し、より高レベルの integration パスを検証します。 -Live-model Docker runnersは、必要なCLI auth homesだけをbind-mountし（または実行が絞られていない場合はサポートされるものすべてをbind-mountし）、その後実行前にそれらをcontainer homeへコピーするため、外部CLI OAuthはホストauth storeを変更せずにトークンを更新できます: +live モデル Docker ランナーは、必要な CLI 認証 home のみ（または実行が絞り込まれていない場合はサポート対象すべて）を bind mount し、その後、外部 CLI OAuth がホストの認証ストアを変更せずにトークン更新できるよう、実行前にコンテナ home にコピーします。 -- 直接models: `pnpm test:docker:live-models`（スクリプト: `scripts/test-live-models-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 smoke: `pnpm test:docker:openwebui`（スクリプト: `scripts/e2e/openwebui-docker.sh`） -- Onboarding wizard（TTY、完全scaffolding）: `pnpm test:docker:onboard`（スクリプト: `scripts/e2e/onboard-docker.sh`） -- Npm tarball onboarding/channel/agent smoke: `pnpm test:docker:npm-onboard-channel-agent` は、packしたOpenClaw tarballをDocker内にグローバルインストールし、env-ref onboarding + デフォルトでTelegram経由でOpenAIを設定し、Plugin有効化によってランタイム依存関係がオンデマンドでインストールされることを検証し、doctorを実行し、1回のモックOpenAI agent turnを実行します。事前ビルド済みtarballを再利用するには `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`、新しいローカルビルド後にホスト再ビルドをスキップするには `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`、channelを切り替えるには `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使ってください。 -- Gateway networking（2コンテナ、WS auth + health）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） -- OpenAI Responses web_search minimal reasoning regression: `pnpm test:docker:openai-web-search-minimal`（スクリプト: `scripts/e2e/openai-web-search-minimal-docker.sh`）は、モックOpenAI serverをGateway経由で実行し、`web_search` が `reasoning.effort` を `minimal` から `low` へ引き上げることを検証し、その後provider schema rejectを強制して生の詳細がGateway logsに現れることを確認します。 -- MCP channel bridge（seed済みGateway + stdio bridge + 生のClaude notification-frame smoke）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） -- Pi bundle MCP tools（実stdio MCP server + 埋め込みPi profile allow/deny smoke）: `pnpm test:docker:pi-bundle-mcp-tools`（スクリプト: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`） -- Cron/subagent MCP cleanup（実Gateway + stdio MCP child teardown after isolated Cron and one-shot subagent runs）: `pnpm test:docker:cron-mcp-cleanup`（スクリプト: `scripts/e2e/cron-mcp-cleanup-docker.sh`） -- Plugins（install smoke + `/plugin` alias + Claude-bundle restart semantics）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） -- Plugin update unchanged smoke: `pnpm test:docker:plugin-update`（スクリプト: `scripts/e2e/plugin-update-unchanged-docker.sh`） -- Config reload metadata smoke: `pnpm test:docker:config-reload`（スクリプト: `scripts/e2e/config-reload-source-docker.sh`） -- 同梱Pluginランタイム依存関係: `pnpm test:docker:bundled-channel-deps` は、デフォルトで小さなDocker runner imageをビルドし、OpenClawをホスト上で1回ビルドしてpackし、その後そのtarballを各Linux install scenarioへマウントします。imageを再利用するには `OPENCLAW_SKIP_DOCKER_BUILD=1`、新しいローカルビルド後のホスト再ビルドをスキップするには `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`、既存tarballを指すには `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` を使ってください。 -- 反復中に同梱Pluginランタイム依存関係を狭めるには、無関係なscenariosを無効にしてください。たとえば: +- 直接モデル: `pnpm test:docker:live-models`（スクリプト: `scripts/test-live-models-docker.sh`） +- ACP bind スモーク: `pnpm test:docker:live-acp-bind`（スクリプト: `scripts/test-live-acp-bind-docker.sh`） +- CLI バックエンドスモーク: `pnpm test:docker:live-cli-backend`（スクリプト: `scripts/test-live-cli-backend-docker.sh`） +- Codex app-server ハーネススモーク: `pnpm test:docker:live-codex-harness`（スクリプト: `scripts/test-live-codex-harness-docker.sh`） +- Gateway + dev エージェント: `pnpm test:docker:live-gateway`（スクリプト: `scripts/test-live-gateway-models-docker.sh`） +- Open WebUI live スモーク: `pnpm test:docker:openwebui`（スクリプト: `scripts/e2e/openwebui-docker.sh`） +- オンボーディングウィザード（TTY、完全スキャフォールディング）: `pnpm test:docker:onboard`（スクリプト: `scripts/e2e/onboard-docker.sh`） +- npm tarball のオンボーディング/チャネル/エージェントスモーク: `pnpm test:docker:npm-onboard-channel-agent` は、pack 済み OpenClaw tarball を Docker 内でグローバルインストールし、env-ref オンボーディング経由で OpenAI を設定し、デフォルトで Telegram も設定し、plugin を有効化すると実行時依存関係がオンデマンドでインストールされることを確認し、doctor を実行し、モックされた OpenAI エージェントターンを 1 回実行します。事前ビルド済み tarball を再利用するには `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`、新しいローカルビルド後にホスト再ビルドをスキップするには `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`、チャネルを切り替えるには `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使ってください。 +- Gateway ネットワーキング（2 コンテナ、WS 認証 + ヘルス）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） +- OpenAI Responses の `web_search` 最小推論回帰: `pnpm test:docker:openai-web-search-minimal`（スクリプト: `scripts/e2e/openai-web-search-minimal-docker.sh`）は、モックされた OpenAI サーバーを Gateway 経由で実行し、`web_search` が `reasoning.effort` を `minimal` から `low` に引き上げることを検証し、その後プロバイダー schema の reject を強制して、生の詳細が Gateway ログに現れることを確認します。 +- MCP チャネルブリッジ（シード済み Gateway + stdio bridge + 生の Claude notification-frame スモーク）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） +- Pi バンドル MCP ツール（実際の stdio MCP サーバー + embedded Pi profile の許可/拒否スモーク）: `pnpm test:docker:pi-bundle-mcp-tools`（スクリプト: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`） +- Cron/subagent MCP クリーンアップ（実際の Gateway + 分離された cron および one-shot subagent 実行後の stdio MCP 子プロセス終了処理）: `pnpm test:docker:cron-mcp-cleanup`（スクリプト: `scripts/e2e/cron-mcp-cleanup-docker.sh`） +- Plugins（インストールスモーク + `/plugin` エイリアス + Claude バンドル再起動セマンティクス）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） +- Plugin update unchanged スモーク: `pnpm test:docker:plugin-update`（スクリプト: `scripts/e2e/plugin-update-unchanged-docker.sh`） +- Config reload メタデータスモーク: `pnpm test:docker:config-reload`（スクリプト: `scripts/e2e/config-reload-source-docker.sh`） +- バンドル済み plugin 実行時依存関係: `pnpm test:docker:bundled-channel-deps` は、デフォルトで小さな Docker ランナーイメージをビルドし、ホスト上で OpenClaw を 1 回だけビルドおよび pack し、その tarball を各 Linux インストールシナリオにマウントします。イメージを再利用するには `OPENCLAW_SKIP_DOCKER_BUILD=1`、新しいローカルビルド後のホスト再ビルドをスキップするには `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`、既存 tarball を指定するには `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` を使ってください。 +- 反復中に無関係なシナリオを無効化して、バンドル済み plugin 実行時依存関係を狭く絞り込めます。たとえば: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps` -共有のbuilt-app imageを手動で事前ビルドして再利用するには: +共有のビルド済みアプリイメージを手動で事前ビルドして再利用するには: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -`OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` のようなsuite固有のimage overrideが設定されている場合は、そちらが引き続き優先されます。`OPENCLAW_SKIP_DOCKER_BUILD=1` がリモート共有imageを指している場合、scriptsはそれがまだローカルにないときにpullします。QRとinstallerのDocker testsは、共有built-app runtimeではなくpackage/install動作を検証するため、独自のDockerfilesを維持します。 +`OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` のようなスイート固有のイメージ上書きは、設定されている場合は引き続きそちらが優先されます。`OPENCLAW_SKIP_DOCKER_BUILD=1` がリモート共有イメージを指している場合、スクリプトはそれがまだローカルに存在しなければ pull します。QR と installer の Docker テストは、共有のビルド済みアプリ runtime ではなく package/install の挙動を検証するため、独自の Dockerfile を維持しています。 -Live-model Docker runnersは、現在のcheckoutも読み取り専用でbind-mountし、 -container内の一時workdirにstageします。これにより、runtime -imageをスリムに保ちながら、正確にあなたのローカルsource/configに対してVitestを実行できます。 -Stagingステップでは、大きなローカル専用cacheやアプリbuild outputs、たとえば -`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの `.build` や -Gradle output directories をスキップするため、Docker live実行が -マシン固有artifactのコピーに何分も費やすことがありません。 -また、container内で実際のTelegram/Discordなどのchannel workersを -gateway live probesが起動しないよう、`OPENCLAW_SKIP_CHANNELS=1` も設定します。 -`test:docker:live-models` は引き続き `pnpm test:live` を実行するため、 -そのDocker laneからgateway -live coverageを絞るまたは除外したい場合は、`OPENCLAW_LIVE_GATEWAY_*` も渡してください。 -`test:docker:openwebui` はより高レベルな互換smokeです。これは -OpenAI互換HTTP endpointsを有効にしたOpenClaw gateway containerを起動し、 -そのgatewayに対して固定版のOpen WebUI containerを起動し、Open WebUI経由でサインインし、 -`/api/models` が `openclaw/default` を公開していることを確認し、その後 -Open WebUIの `/api/chat/completions` proxy経由で実際のチャット要求を送信します。 -初回実行は、Dockerが -Open WebUI imageをpullする必要があったり、Open WebUI自体のcold-start setupが完了する必要があったりするため、目に見えて遅いことがあります。 -このレーンは使用可能なlive model keyを期待しており、Dockerized実行でそれを提供する主な方法は `OPENCLAW_PROFILE_FILE` -（デフォルト `~/.profile`）です。 -成功時には `{ "ok": true, "model": -"openclaw/default", ... }` のような小さなJSON payloadが出力されます。 -`test:docker:mcp-channels` は意図的に決定的であり、実際の -Telegram、Discord、またはiMessageアカウントを必要としません。これはseed済みGateway -containerを起動し、`openclaw mcp serve` を起動する2つ目のcontainerを開始し、その後 -ルーティングされた会話検出、transcript reads、attachment metadata、 -live event queue動作、outbound send routing、およびClaude形式のchannel + -permission notificationsを、実際のstdio MCP bridge上で検証します。notification確認は -生のstdio MCP framesを直接検査するため、このsmokeは特定のclient SDKがたまたま表面化するものではなく、bridgeが実際に出力するものを検証します。 -`test:docker:pi-bundle-mcp-tools` は決定的であり、live -model keyを必要としません。これはrepo Docker imageをビルドし、container内で実際のstdio MCP probe serverを起動し、 -そのserverを埋め込みPi bundle -MCP runtime経由で実体化し、toolを実行し、その後 `coding` と `messaging` が -`bundle-mcp` toolsを維持し、`minimal` と `tools.deny: ["bundle-mcp"]` がそれらを除外することを検証します。 -`test:docker:cron-mcp-cleanup` も決定的であり、live model -keyを必要としません。これは実際のstdio MCP probe server付きのseed済みGatewayを起動し、分離されたCron turnと `/subagents spawn` の単発child turnを実行し、その後各実行後に -MCP child processが終了することを検証します。 +live モデル Docker ランナーは、現在のチェックアウトを read-only で bind mount し、コンテナ内の一時 workdir に stage もします。これにより、runtime イメージをスリムに保ちながら、正確にあなたのローカルソース/設定に対して Vitest を実行できます。stage 手順では、`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの `.build` や Gradle 出力ディレクトリのような、大きなローカル専用キャッシュやアプリビルド出力をスキップするため、Docker live 実行でマシン固有の成果物コピーに何分も費やしません。 +また、これらは `OPENCLAW_SKIP_CHANNELS=1` も設定するため、Gateway の live プローブはコンテナ内で実際の Telegram/Discord などのチャネルワーカーを起動しません。 +`test:docker:live-models` は引き続き `pnpm test:live` を実行するため、その Docker レーンから Gateway live カバレッジを絞り込んだり除外したりしたい場合は、`OPENCLAW_LIVE_GATEWAY_*` も併せて渡してください。 +`test:docker:openwebui` は、より高レベルの互換性スモークです。OpenAI 互換 HTTP エンドポイントを有効にした OpenClaw Gateway コンテナを起動し、その Gateway に対して固定版の Open WebUI コンテナを起動し、Open WebUI 経由でサインインし、`/api/models` が `openclaw/default` を公開していることを確認し、その後、Open WebUI の `/api/chat/completions` プロキシ経由で実際のチャットリクエストを送信します。 +初回実行は、Docker が Open WebUI イメージを pull する必要があったり、Open WebUI 自身のコールドスタート設定を完了する必要があるため、目に見えて遅くなることがあります。 +このレーンは利用可能な live モデルキーを必要とし、Docker 化された実行でそれを提供する主な方法は `OPENCLAW_PROFILE_FILE`（デフォルト `~/.profile`）です。 +成功した実行では `{ "ok": true, "model": "openclaw/default", ... }` のような小さな JSON ペイロードが出力されます。 +`test:docker:mcp-channels` は意図的に決定的であり、実際の Telegram、Discord、または iMessage アカウントを必要としません。seed 済み Gateway コンテナを起動し、`openclaw mcp serve` を起動する 2 つ目のコンテナを開始し、その後、ルーティング済み会話検出、transcript 読み取り、添付メタデータ、live イベントキュー挙動、送信 send ルーティング、および実際の stdio MCP ブリッジ上の Claude 風チャネル + 権限通知を検証します。通知チェックは生の stdio MCP フレームを直接検査するため、このスモークは特定のクライアント SDK がたまたま表面化する内容ではなく、ブリッジが実際に送出するものを検証します。 +`test:docker:pi-bundle-mcp-tools` は決定的で、live モデルキーを必要としません。リポジトリ Docker イメージをビルドし、コンテナ内で実際の stdio MCP プローブサーバーを起動し、そのサーバーを embedded Pi bundle MCP runtime 経由で具現化し、ツールを実行し、その後 `coding` と `messaging` が `bundle-mcp` ツールを維持し、`minimal` と `tools.deny: ["bundle-mcp"]` がそれらを除外することを検証します。 +`test:docker:cron-mcp-cleanup` は決定的で、live モデルキーを必要としません。実際の stdio MCP プローブサーバー付きの seed 済み Gateway を起動し、分離された cron ターンと `/subagents spawn` の one-shot 子ターンを実行し、その後各実行後に MCP 子プロセスが終了することを検証します。 -手動ACP平文thread smoke（CIではない）: +手動 ACP plain-language thread スモーク（CI ではない）: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- このスクリプトはregression/debugワークフロー用に保持してください。ACP thread routing検証で再び必要になる可能性があるため、削除しないでください。 +- このスクリプトは回帰/デバッグワークフロー用に保持してください。ACP スレッドルーティング検証で再び必要になる可能性があるため、削除しないでください。 -便利なenv vars: +便利な環境変数: -- `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_PROFILE_ENV_ONLY=1` は、`OPENCLAW_PROFILE_FILE` からsourceされたenv varsのみを検証します。一時的なconfig/workspace dirsを使用し、外部CLI auth mountsは使いません -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）は、Docker内でのキャッシュされたCLI installs用に `/home/node/.npm-global` にマウントされます -- `$HOME` 配下の外部CLI auth dirs/filesは、`/host-auth...` 配下に読み取り専用でマウントされ、その後テスト開始前に `/home/node/...` へコピーされます - - デフォルトdirs: `.minimax` - - デフォルトfiles: `~/.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` から推定された必要なdirs/filesのみをマウントします - - `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストで手動overrideできます -- 実行を絞るには `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` -- container内でprovidersをフィルターするには `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` -- 再ビルド不要の再実行で既存の `openclaw:local-live` imageを再利用するには `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=...` +- `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_PROFILE_ENV_ONLY=1` で、`OPENCLAW_PROFILE_FILE` から source した環境変数のみを検証します。この場合、一時的な config/workspace ディレクトリを使い、外部 CLI 認証マウントは行いません +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）を `/home/node/.npm-global` にマウントし、Docker 内の CLI インストールをキャッシュ +- `$HOME` 配下の外部 CLI 認証ディレクトリ/ファイルは `/host-auth...` 配下に read-only でマウントされ、その後テスト開始前に `/home/node/...` にコピーされます + - デフォルトディレクトリ: `.minimax` + - デフォルトファイル: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` + - 絞り込まれたプロバイダー実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推論された必要なディレクトリ/ファイルのみをマウントします + - `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストで手動上書きできます +- 実行を絞り込む `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` +- コンテナ内でプロバイダーを絞り込む `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` +- 再ビルド不要の再実行で既存の `openclaw:local-live` イメージを再利用する `OPENCLAW_SKIP_DOCKER_BUILD=1` +- 認証情報がプロファイルストア由来であることを保証する `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`（env 由来ではない） +- Open WebUI スモーク向けに Gateway が公開するモデルを選ぶ `OPENCLAW_OPENWEBUI_MODEL=...` +- Open WebUI スモークで使う nonce チェックプロンプトを上書きする `OPENCLAW_OPENWEBUI_PROMPT=...` +- 固定版 Open WebUI イメージタグを上書きする `OPENWEBUI_IMAGE=...` -## ドキュメント健全性 +## ドキュメント健全性確認 -ドキュメント編集後はdocs checksを実行してください: `pnpm check:docs`。 -ページ内見出しチェックも必要な場合は、完全なMintlify anchor validationを実行してください: `pnpm docs:check-links:anchors`。 +ドキュメント編集後は docs チェックを実行してください: `pnpm check:docs`。 +ページ内見出しチェックも必要な場合は、完全な Mintlify アンカー検証を実行してください: `pnpm docs:check-links:anchors`。 -## オフラインリグレッション（CI-safe） +## オフライン回帰（CI 安全） -これらは、実providerなしの「実パイプライン」リグレッションです: +これらは、実際のプロバイダーなしで行う「実際のパイプライン」回帰です。 -- Gateway tool calling（モックOpenAI、実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強制）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） +- Gateway ツール呼び出し（モック OpenAI、実際の Gateway + エージェントループ）: `src/gateway/gateway.test.ts`（ケース: "runs a mock OpenAI tool call end-to-end via gateway agent loop"） +- Gateway ウィザード（WS `wizard.start`/`wizard.next`、設定 + 認証書き込みを強制）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） -## Agent信頼性evals（Skills） +## エージェント信頼性 evals（Skills） -CI-safeで「agent信頼性evals」のように振る舞うテストはいくつかすでにあります: +すでにいくつかの CI 安全なテストがあり、「エージェント信頼性 eval」のように振る舞います。 -- 実gateway + agent loopを通したモックtool-calling（`src/gateway/gateway.test.ts`）。 -- session wiringとconfig効果を検証するend-to-endウィザードフロー（`src/gateway/gateway.test.ts`）。 +- 実際の Gateway + エージェントループを通したモックツール呼び出し（`src/gateway/gateway.test.ts`）。 +- セッション配線と設定効果を検証するエンドツーエンドのウィザードフロー（`src/gateway/gateway.test.ts`）。 -Skillsについてまだ不足しているもの（[Skills](/ja-JP/tools/skills) 参照）: +Skills に関してまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: -- **Decisioning:** promptにskillsが列挙されたとき、agentは正しいskillを選ぶか（または無関係なものを避けるか）? -- **Compliance:** agentは使用前に `SKILL.md` を読み、必須手順/argsに従うか? -- **Workflow contracts:** tool順序、session historyの引き継ぎ、sandbox境界を検証するmulti-turn scenarios。 +- **Decisioning:** Skills がプロンプトに列挙されたとき、エージェントは正しい Skill を選ぶか（または無関係なものを避けるか）？ +- **Compliance:** エージェントは使用前に `SKILL.md` を読み、必須の手順/引数に従うか？ +- **Workflow contracts:** ツール順序、セッション履歴の引き継ぎ、sandbox 境界をアサートするマルチターンシナリオ。 -将来のevalsも、まずは決定的であるべきです: +今後の eval は、まず決定的であるべきです。 -- mock providersを使い、tool calls + 順序、skill file reads、session wiringを検証するscenario runner。 -- skillに焦点を当てた小さなsuite of scenarios（使うべきとき/避けるべきとき、gating、prompt injection）。 -- オプトイン・env-gatedのlive evalsは、CI-safeスイートが整った後のみ。 +- モックプロバイダーを使い、ツール呼び出し + 順序、Skill ファイル読み取り、セッション配線をアサートするシナリオランナー。 +- Skill に焦点を当てた小さなシナリオ群（使う/使わない、ゲーティング、プロンプトインジェクション）。 +- CI 安全スイートが整った後にのみ、任意の live eval（オプトイン、env gated）。 -## Contract tests（Pluginとchannelの形） +## 契約テスト（plugin およびチャネル形状） -Contract testsは、登録されたすべてのPluginとchannelが -インターフェース契約に適合していることを検証します。発見されたすべてのpluginsを走査し、 -形と動作に関する一連の検証を実行します。デフォルトの `pnpm test` unitレーンは、これらの共有seamおよびsmoke filesを意図的にスキップするため、共有channelまたはprovider surfaceに触れたときはcontractコマンドを明示的に実行してください。 +契約テストは、登録されているすべての plugin とチャネルが、そのインターフェース契約に適合していることを検証します。検出されたすべての plugin を反復し、形状と挙動に関する一連のアサーションを実行します。デフォルトの `pnpm test` unit レーンでは、これらの共有 seam とスモークファイルは意図的にスキップされるため、共有チャネルまたはプロバイダー surface に触れた場合は、契約コマンドを明示的に実行してください。 ### コマンド -- すべてのcontracts: `pnpm test:contracts` -- Channel contractsのみ: `pnpm test:contracts:channels` -- Provider contractsのみ: `pnpm test:contracts:plugins` +- すべての契約: `pnpm test:contracts` +- チャネル契約のみ: `pnpm test:contracts:channels` +- プロバイダー契約のみ: `pnpm test:contracts:plugins` -### Channel contracts +### チャネル契約 `src/channels/plugins/contracts/*.contract.test.ts` にあります: -- **plugin** - 基本的なPlugin形状（id、name、capabilities） +- **plugin** - 基本的な plugin 形状（id、name、capabilities） - **setup** - セットアップウィザード契約 -- **session-binding** - Session binding動作 -- **outbound-payload** - メッセージpayload構造 +- **session-binding** - セッション bind の挙動 +- **outbound-payload** - メッセージ payload 構造 - **inbound** - 受信メッセージ処理 -- **actions** - Channel action handlers -- **threading** - Thread ID処理 -- **directory** - Directory/roster API -- **group-policy** - グループポリシー強制 +- **actions** - チャネルアクションハンドラー +- **threading** - スレッド ID 処理 +- **directory** - ディレクトリ/roster API +- **group-policy** - グループポリシー適用 -### Provider status contracts +### プロバイダーステータス契約 `src/plugins/contracts/*.contract.test.ts` にあります。 -- **status** - Channel status probes -- **registry** - Plugin registry形状 +- **status** - チャネルステータスプローブ +- **registry** - plugin レジストリ形状 -### Provider contracts +### プロバイダー契約 `src/plugins/contracts/*.contract.test.ts` にあります: -- **auth** - Authフロー契約 -- **auth-choice** - Auth choice/selection -- **catalog** - Model catalog API -- **discovery** - Plugin discovery -- **loader** - Plugin loading -- **runtime** - Provider runtime -- **shape** - Plugin shape/interface +- **auth** - 認証フロー契約 +- **auth-choice** - 認証選択 +- **catalog** - モデルカタログ API +- **discovery** - plugin 検出 +- **loader** - plugin 読み込み +- **runtime** - プロバイダー runtime +- **shape** - plugin 形状/インターフェース - **wizard** - セットアップウィザード ### 実行すべきタイミング -- plugin-sdk exportsまたはsubpathsを変更した後 -- channelまたはprovider Pluginを追加または変更した後 -- Plugin registrationまたはdiscoveryをリファクタリングした後 +- plugin-sdk の export または subpath を変更した後 +- チャネルまたはプロバイダー plugin を追加または変更した後 +- plugin 登録または検出をリファクタリングした後 -Contract testsはCIで実行され、実際のAPI keysは必要ありません。 +契約テストは CI で実行され、実際の API キーは必要ありません。 -## リグレッション追加のガイダンス +## 回帰の追加（ガイダンス） -liveで見つかったprovider/model問題を修正したとき: +live で見つかったプロバイダー/モデルの問題を修正するとき: -- 可能ならCI-safeなリグレッションを追加してください（providerをmock/stubする、または正確なrequest-shape transformationを捕捉する） -- 本質的にlive-onlyな場合（rate limits、auth policies）は、liveテストを狭く保ち、env varsでオプトインにしてください -- バグを捕まえる最小レイヤーを狙うことを優先してください: - - provider request conversion/replay bug → 直接modelsテスト - - gateway session/history/tool pipeline bug → gateway live smokeまたはCI-safe gateway mock test -- SecretRef traversal guardrail: - - `src/secrets/exec-secret-ref-id-parity.test.ts` は、registry metadata（`listSecretTargetRegistryEntries()`）からSecretRef classごとに1つのサンプルtargetを導出し、その後 traversal-segment exec ids が拒否されることを検証します。 - - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef target familyを追加する場合は、そのテストの `classifyTargetClass` を更新してください。このテストは、未分類のtarget idsで意図的に失敗するため、新しいclassesが黙ってスキップされることはありません。 +- 可能なら CI 安全な回帰を追加してください（モック/スタブプロバイダー、または正確なリクエスト形状変換の捕捉） +- 本質的に live 専用なら（レート制限、認証ポリシー）、live テストは狭く保ち、env vars でオプトインにしてください +- バグを検出できる最小のレイヤーを狙うことを優先してください: + - プロバイダーのリクエスト変換/リプレイバグ → 直接モデルテスト + - Gateway セッション/履歴/ツールパイプラインのバグ → Gateway live スモークまたは CI 安全な Gateway モックテスト +- SecretRef traversal ガードレール: + - `src/secrets/exec-secret-ref-id-parity.test.ts` は、レジストリメタデータ（`listSecretTargetRegistryEntries()`）から SecretRef クラスごとに 1 つのサンプルターゲットを導出し、traversal-segment exec id が拒否されることをアサートします。 + - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef ターゲットファミリーを追加した場合は、そのテスト内の `classifyTargetClass` を更新してください。このテストは、未分類の target id に対して意図的に失敗するため、新しいクラスを黙ってスキップすることはできません。