diff --git a/docs/ja-JP/automation/tasks.md b/docs/ja-JP/automation/tasks.md index 08ab8e3bf..5a98f0768 100644 --- a/docs/ja-JP/automation/tasks.md +++ b/docs/ja-JP/automation/tasks.md @@ -1,52 +1,51 @@ --- read_when: - - 進行中または最近完了したバックグラウンド作業の確認 + - 進行中または最近完了したバックグラウンド作業を確認する - デタッチされたエージェント実行の配信失敗をデバッグする - - バックグラウンド実行がセッション、Cron、Heartbeat とどのように関係するかを理解する + - バックグラウンド実行がセッション、Cron、Heartbeat とどう関係するかを理解する sidebarTitle: Background tasks summary: ACP 実行、サブエージェント、分離された Cron ジョブ、CLI 操作のバックグラウンドタスク追跡 title: バックグラウンドタスク x-i18n: - generated_at: "2026-04-30T16:28:03Z" + generated_at: "2026-05-01T05:00:32Z" model: gpt-5.5 provider: openai - source_hash: 999653c9360323d5135e33193c76458cba8c288227de46a6217f1ccbed2a6d34 + source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4 source_path: automation/tasks.md workflow: 16 --- -スケジューリングを探している場合は、適切な仕組みを選ぶために[自動化とタスク](/ja-JP/automation)を参照してください。このページはバックグラウンド作業のアクティビティ台帳であり、スケジューラではありません。 +スケジュール設定を探していますか？適切な仕組みを選ぶには、[自動化とタスク](/ja-JP/automation)を参照してください。このページはバックグラウンド作業のアクティビティ台帳であり、スケジューラーではありません。 -バックグラウンドタスクは、**メインの会話セッションの外側**で実行される作業を追跡します。ACP実行、サブエージェントの起動、分離されたCronジョブ実行、CLIから開始された操作が含まれます。 +バックグラウンドタスクは、**メインの会話セッションの外部**で実行される作業を追跡します: ACP 実行、サブエージェントの起動、分離された cron ジョブ実行、CLI から開始された操作です。 -タスクは、セッション、Cronジョブ、Heartbeatを置き換えるものではありません。切り離された作業で何が起きたか、いつ起きたか、成功したかどうかを記録する**アクティビティ台帳**です。 +タスクはセッション、cron ジョブ、Heartbeat を置き換えるものではありません。タスクは、どの分離作業がいつ発生し、成功したかどうかを記録する**アクティビティ台帳**です。 -すべてのエージェント実行がタスクを作成するわけではありません。Heartbeatターンと通常の対話型チャットは作成しません。すべてのCron実行、ACP起動、サブエージェント起動、CLIエージェントコマンドは作成します。 +すべてのエージェント実行がタスクを作成するわけではありません。Heartbeat ターンと通常の対話型チャットは作成しません。すべての cron 実行、ACP 起動、サブエージェント起動、CLI エージェントコマンドは作成します。 -## 要点 +## 要約 -- タスクはスケジューラではなく**記録**です。CronとHeartbeatが作業を_いつ_実行するかを決め、タスクは_何が起きたか_を追跡します。 -- ACP、サブエージェント、すべてのCronジョブ、CLI操作はタスクを作成します。Heartbeatターンは作成しません。 -- 各タスクは `queued → running → terminal`（succeeded、failed、timed_out、cancelled、lost）を遷移します。 -- Cronタスクは、Cronランタイムがまだジョブを所有している間はライブのままです。 - インメモリのランタイム状態が失われている場合、タスクメンテナンスはまず永続化されたCron実行履歴を確認してから、タスクをlostとしてマークします。 -- 完了はプッシュ駆動です。切り離された作業は、完了時に直接通知するか、 - リクエスト元セッション/Heartbeatを起こすことができるため、ステータスのポーリングループは - 通常は適切な形ではありません。 -- 分離されたCron実行とサブエージェント完了は、最終的なクリーンアップ記録の前に、子セッションで追跡されているブラウザタブ/プロセスをベストエフォートでクリーンアップします。 -- 分離されたCron配信は、子孫サブエージェント作業がまだ完了処理中の場合、古くなった途中の親返信を抑制し、配信前に子孫の最終出力が届いた場合はそれを優先します。 -- 完了通知はチャンネルへ直接配信されるか、次のHeartbeatに向けてキューに入れられます。 -- `openclaw tasks list` はすべてのタスクを表示します。`openclaw tasks audit` は問題を表示します。 -- terminalレコードは7日間保持され、その後自動的に削除されます。 +- タスクはスケジューラーではなく**レコード**です。cron と Heartbeat は作業を_いつ_実行するかを決め、タスクは_何が起きたか_を追跡します。 +- ACP、サブエージェント、すべての cron ジョブ、CLI 操作はタスクを作成します。Heartbeat ターンは作成しません。 +- 各タスクは `queued → running → terminal`（succeeded、failed、timed_out、cancelled、または lost）を進みます。 +- cron タスクは、cron ランタイムがまだジョブを所有している間はライブのままです。 + メモリ内のランタイム状態がなくなった場合、タスクのメンテナンスはタスクを lost としてマークする前に、まず永続化された cron + 実行履歴を確認します。 +- 完了はプッシュ駆動です: 分離された作業は完了時に直接通知するか、リクエスターのセッション/Heartbeat を起こせるため、ステータスのポーリングループは通常適切な形ではありません。 +- 分離された cron 実行とサブエージェント完了は、最終クリーンアップの帳簿処理の前に、子セッションで追跡されているブラウザータブ/プロセスをベストエフォートでクリーンアップします。 +- 分離された cron 配信は、子孫サブエージェントの作業がまだ排出中の間は古くなった暫定的な親返信を抑制し、配信前に子孫の最終出力が届いた場合はそれを優先します。 +- 完了通知はチャンネルに直接配信されるか、次の Heartbeat 用にキューに入れられます。 +- `openclaw tasks list` はすべてのタスクを表示します。`openclaw tasks audit` は問題を表面化します。 +- 終端レコードは 7 日間保持され、その後自動的に削除されます。 ## クイックスタート - + ```bash # List all tasks (newest first) openclaw tasks list @@ -57,7 +56,7 @@ x-i18n: ``` - + ```bash # Show details for a specific task (by ID, run ID, or session key) openclaw tasks show @@ -84,7 +83,7 @@ x-i18n: ``` - + ```bash # Inspect TaskFlow state openclaw tasks flow list @@ -96,26 +95,26 @@ x-i18n: ## タスクを作成するもの -| ソース | ランタイム種別 | タスクレコードが作成されるタイミング | デフォルト通知ポリシー | +| ソース | ランタイムタイプ | タスクレコードが作成されるタイミング | デフォルト通知ポリシー | | ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| ACPバックグラウンド実行 | `acp` | 子ACPセッションの起動 | `done_only` | -| サブエージェントのオーケストレーション | `subagent` | `sessions_spawn` によるサブエージェントの起動 | `done_only` | -| Cronジョブ（全種別） | `cron` | すべてのCron実行（メインセッションと分離実行） | `silent` | -| CLI操作 | `cli` | Gateway経由で実行される `openclaw agent` コマンド | `silent` | -| エージェントメディアジョブ | `cli` | セッションに紐づく `video_generate` 実行 | `silent` | +| ACP バックグラウンド実行 | `acp` | 子 ACP セッションを起動する時 | `done_only` | +| サブエージェントのオーケストレーション | `subagent` | `sessions_spawn` 経由でサブエージェントを起動する時 | `done_only` | +| cron ジョブ（全タイプ） | `cron` | すべての cron 実行（メインセッションおよび分離） | `silent` | +| CLI 操作 | `cli` | Gateway を通じて実行される `openclaw agent` コマンド | `silent` | +| エージェントメディアジョブ | `cli` | セッション backed の `music_generate`/`video_generate` 実行 | `silent` | - - メインセッションのCronタスクは、デフォルトで `silent` 通知ポリシーを使用します。追跡用のレコードは作成しますが、通知は生成しません。分離されたCronタスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より見えやすくなります。 + + メインセッションの cron タスクは、デフォルトで `silent` 通知ポリシーを使用します。追跡用のレコードは作成しますが、通知は生成しません。分離された cron タスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より見えやすくなります。 - セッションに紐づく `video_generate` 実行も `silent` 通知ポリシーを使用します。タスクレコードは引き続き作成しますが、完了は内部wakeとして元のエージェントセッションに戻されるため、エージェントがフォローアップメッセージを書き、完成した動画を自分で添付できます。`tools.media.asyncCompletion.directSend` を有効にすると、非同期の `music_generate` と `video_generate` の完了は、リクエスト元セッションのwake経路へフォールバックする前に、まずチャンネルへの直接配信を試みます。 + セッション backed の `music_generate` と `video_generate` 実行も `silent` 通知ポリシーを使用します。それでもタスクレコードは作成されますが、完了は内部 wake として元のエージェントセッションに戻され、エージェントがフォローアップメッセージを書き、完成したメディアを自分で添付できるようにします。`tools.media.asyncCompletion.directSend` を有効にすると、非同期の `video_generate` 完了はまず直接チャンネル配信を試せます。非同期の `music_generate` 完了はリクエスターセッションの wake パスに留まります。 - - セッションに紐づく `video_generate` タスクがまだアクティブな間、このツールはガードレールとしても機能します。同じセッションで `video_generate` を繰り返し呼び出すと、2つ目の同時生成を開始する代わりに、アクティブなタスクのステータスを返します。エージェント側から明示的に進捗/ステータスを取得したい場合は、`action: "status"` を使用してください。 + + セッション backed の `video_generate` タスクがまだアクティブな間、このツールはガードレールとしても機能します。同じセッションで `video_generate` が繰り返し呼び出されると、2 つ目の同時生成を開始する代わりに、アクティブなタスクのステータスを返します。エージェント側から明示的に進行状況/ステータスを参照したい場合は `action: "status"` を使用してください。 - - Heartbeatターン — メインセッション。[Heartbeat](/ja-JP/gateway/heartbeat)を参照 + - Heartbeat ターン（メインセッション）。[Heartbeat](/ja-JP/gateway/heartbeat)を参照 - 通常の対話型チャットターン - 直接の `/command` 応答 @@ -136,64 +135,63 @@ stateDiagram-v2 running --> lost : session gone > 5 min ``` -| ステータス | 意味 | +| ステータス | 意味 | | ----------- | -------------------------------------------------------------------------- | -| `queued` | 作成済みで、エージェントの開始を待機中 | -| `running` | エージェントターンがアクティブに実行中 | -| `succeeded` | 正常に完了 | -| `failed` | エラーで完了 | -| `timed_out` | 設定されたタイムアウトを超過 | -| `cancelled` | `openclaw tasks cancel` によりオペレーターが停止 | -| `lost` | 5分間の猶予期間後に、ランタイムが信頼できる裏付け状態を失った | +| `queued` | 作成済みで、エージェントの開始を待っています | +| `running` | エージェントターンがアクティブに実行中です | +| `succeeded` | 正常に完了しました | +| `failed` | エラーで完了しました | +| `timed_out` | 構成されたタイムアウトを超過しました | +| `cancelled` | オペレーターが `openclaw tasks cancel` で停止しました | +| `lost` | ランタイムが 5 分間の猶予期間後に、信頼できる裏付け状態を失いました | -遷移は自動的に発生します。関連するエージェント実行が終了すると、タスクステータスがそれに合わせて更新されます。 +遷移は自動的に発生します。関連付けられたエージェント実行が終了すると、タスクステータスはそれに合わせて更新されます。 -エージェント実行の完了は、アクティブなタスクレコードに対する信頼できる情報源です。成功した切り離し実行は `succeeded` として最終化され、通常の実行エラーは `failed` として最終化され、タイムアウトまたは中止の結果は `timed_out` として最終化されます。オペレーターがすでにタスクをキャンセルしている場合、またはランタイムが `failed`、`timed_out`、`lost` などより強いterminal状態をすでに記録している場合、後から成功シグナルが来ても、そのterminalステータスは弱められません。 +エージェント実行の完了は、アクティブなタスクレコードに対して信頼できる情報源です。成功した分離実行は `succeeded` として確定し、通常の実行エラーは `failed` として確定し、タイムアウトまたは中止の結果は `timed_out` として確定します。オペレーターがすでにタスクをキャンセルしている場合、またはランタイムが `failed`、`timed_out`、`lost` など、より強い終端状態をすでに記録している場合、後から成功シグナルが来てもその終端ステータスは引き下げられません。 -`lost` はランタイムを考慮します。 +`lost` はランタイムを考慮します: -- ACPタスク: 裏付けとなるACP子セッションメタデータが消えた。 -- サブエージェントタスク: 裏付けとなる子セッションがターゲットエージェントストアから消えた。 -- Cronタスク: Cronランタイムがジョブをアクティブとして追跡しなくなり、永続化された - Cron実行履歴にもその実行のterminal結果がない。オフラインCLI - 監査は、自身の空のインプロセスCronランタイム状態を権威として扱いません。 -- CLIタスク: 分離された子セッションタスクは子セッションを使用します。チャットに紐づく - CLIタスクは代わりにライブ実行コンテキストを使用するため、残存する - チャンネル/グループ/ダイレクトのセッション行がそれらを生存状態に保つことはありません。Gatewayに紐づく - `openclaw agent` 実行も実行結果から最終化されるため、完了済み実行が - スイーパーによって `lost` とマークされるまでアクティブのまま残ることはありません。 +- ACP タスク: 裏付けとなる ACP 子セッションのメタデータが消えました。 +- サブエージェントタスク: 裏付けとなる子セッションがターゲットエージェントストアから消えました。 +- cron タスク: cron ランタイムがそのジョブをアクティブとして追跡しなくなり、永続化された + cron 実行履歴にもその実行の終端結果が示されていません。オフライン CLI + 監査は、自身の空のインプロセス cron ランタイム状態を権威として扱いません。 +- CLI タスク: 分離された子セッションタスクは子セッションを使用します。チャット backed の + CLI タスクは代わりにライブ実行コンテキストを使用するため、残存する + チャンネル/グループ/ダイレクトセッション行がそれらを生存状態に保つことはありません。Gateway backed の + `openclaw agent` 実行も実行結果から確定されるため、完了済みの実行がスイーパーにより `lost` とマークされるまでアクティブなまま残ることはありません。 ## 配信と通知 -タスクがterminal状態に到達すると、OpenClawが通知します。配信経路は2つあります。 +タスクが終端状態に達すると、OpenClaw が通知します。配信パスは 2 つあります: -**直接配信** — タスクにチャンネルターゲット（`requesterOrigin`）がある場合、完了メッセージはそのチャンネル（Telegram、Discord、Slackなど）へ直接送られます。サブエージェント完了では、OpenClawは利用可能な場合に紐づいたスレッド/トピックのルーティングも保持し、直接配信を諦める前に、リクエスト元セッションに保存された経路（`lastChannel` / `lastTo` / `lastAccountId`）から不足している `to` / account を補完できます。 +**直接配信** — タスクにチャンネルターゲット（`requesterOrigin`）がある場合、完了メッセージはそのチャンネル（Telegram、Discord、Slack など）に直接送られます。サブエージェント完了では、OpenClaw は利用可能な場合に紐付いたスレッド/トピックのルーティングも保持し、直接配信を諦める前に、リクエスターセッションに保存されたルート（`lastChannel` / `lastTo` / `lastAccountId`）から欠けている `to` / アカウントを補完できます。 -**セッションキュー配信** — 直接配信が失敗するかoriginが設定されていない場合、更新はリクエスト元のセッションにシステムイベントとしてキューに入れられ、次のHeartbeatで表示されます。 +**セッションキュー配信** — 直接配信が失敗した場合、または origin が設定されていない場合、更新はリクエスターのセッション内のシステムイベントとしてキューに入れられ、次の Heartbeat で表面化します。 -タスク完了は即時のHeartbeat wakeをトリガーするため、結果をすぐに確認できます。次にスケジュールされたHeartbeat tickを待つ必要はありません。 +タスク完了は即時の Heartbeat wake をトリガーするため、結果をすばやく確認できます。次のスケジュール済み Heartbeat tick を待つ必要はありません。 -つまり、通常のワークフローはプッシュベースです。切り離された作業を一度開始し、その後は完了時にランタイムがwakeまたは通知するのに任せます。デバッグ、介入、明示的な監査が必要な場合にのみタスク状態をポーリングしてください。 +つまり、通常のワークフローはプッシュベースです。分離された作業を一度開始したら、完了時にランタイムが wake または通知するのを待ちます。デバッグ、介入、明示的な監査が必要な場合にのみタスク状態をポーリングしてください。 ### 通知ポリシー -各タスクについて、どの程度通知を受け取るかを制御します。 +各タスクについて、どの程度通知を受けるかを制御します: -| ポリシー | 配信される内容 | +| ポリシー | 配信される内容 | | --------------------- | ----------------------------------------------------------------------- | -| `done_only`（デフォルト） | terminal状態（succeeded、failedなど）のみ — **これがデフォルトです** | -| `state_changes` | すべての状態遷移と進捗更新 | -| `silent` | 何もなし | +| `done_only`（デフォルト） | 終端状態（succeeded、failed など）のみ — **これがデフォルトです** | +| `state_changes` | すべての状態遷移と進行状況更新 | +| `silent` | 何も配信されません | -タスクの実行中にポリシーを変更します。 +タスクの実行中にポリシーを変更します: ```bash openclaw tasks notify state_changes ``` -## CLIリファレンス +## CLI リファレンス @@ -201,7 +199,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - 出力列: Task ID、Kind、Status、Delivery、Run ID、Child Session、Summary。 + 出力列: タスク ID、種類、ステータス、配信、実行 ID、子セッション、要約。 @@ -209,7 +207,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - lookupトークンには、タスクID、実行ID、セッションキーを指定できます。タイミング、配信状態、エラー、terminalサマリーを含む完全なレコードを表示します。 + 参照トークンには、タスク ID、実行 ID、またはセッションキーを指定できます。タイミング、配信状態、エラー、終端要約を含む完全なレコードを表示します。 @@ -217,7 +215,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - ACPタスクとサブエージェントタスクでは、これは子セッションを終了します。CLIで追跡されるタスクでは、キャンセルはタスクレジストリに記録されます（別個の子ランタイムハンドルはありません）。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。 + ACP とサブエージェントタスクでは、これにより子セッションが終了されます。CLI で追跡されるタスクでは、キャンセルはタスクレジストリに記録されます（別個の子ランタイムハンドルはありません）。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。 @@ -230,40 +228,40 @@ openclaw tasks notify state_changes openclaw tasks audit [--json] ``` - 運用上の問題を表示します。問題が検出された場合、検出結果は `openclaw status` にも表示されます。 + 運用上の問題を表面化します。問題が検出された場合、検出結果は `openclaw status` にも表示されます。 - | 検出事項 | 重要度 | トリガー | + | 検出項目 | 重大度 | トリガー | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | | `stale_queued` | warn | 10 分を超えてキューに入っている | | `stale_running` | error | 30 分を超えて実行中 | - | `lost` | warn/error | ランタイムに裏付けられたタスク所有権が消失した。保持された lost タスクは `cleanupAfter` までは警告になり、その後エラーになる | + | `lost` | warn/error | ランタイムに裏付けられたタスク所有権が消失した。保持中の lost タスクは `cleanupAfter` まで警告になり、その後エラーになる | | `delivery_failed` | warn | 配信に失敗し、通知ポリシーが `silent` ではない | - | `missing_cleanup` | warn | クリーンアップタイムスタンプがない終端タスク | - | `inconsistent_timestamps` | warn | タイムライン違反（たとえば開始前に終了している） | + | `missing_cleanup` | warn | クリーンアップタイムスタンプがない終端タスク | + | `inconsistent_timestamps` | warn | タイムライン違反（たとえば開始前に終了している） | - + ```bash openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` - これを使用して、タスクと Task Flow 状態の照合、クリーンアップのタイムスタンプ付与、プルーニングをプレビューまたは適用します。 + タスクと Task Flow 状態の照合、クリーンアップのスタンプ付け、枝刈りをプレビューまたは適用するために使います。 - 照合はランタイムを考慮します。 + 照合はランタイムを認識します。 - ACP/サブエージェントタスクは、裏付けとなる子セッションを確認します。 - - 子セッションに再起動リカバリの tombstone があるサブエージェントタスクは、リカバリ可能な裏付けセッションとして扱われるのではなく lost とマークされます。 - - Cron タスクは、cron ランタイムがまだジョブを所有しているかどうかを確認し、その後 `lost` にフォールバックする前に、永続化された cron 実行ログ/ジョブ状態から終端ステータスを復元します。メモリ内の cron アクティブジョブセットについて権威を持つのは Gateway プロセスだけです。オフライン CLI 監査は永続履歴を使用しますが、そのローカル Set が空であることだけを理由に cron タスクを lost とマークしません。 - - チャットに裏付けられた CLI タスクは、チャットセッション行だけでなく、所有するライブ実行コンテキストを確認します。 + - 子セッションに再起動復旧の墓標があるサブエージェントタスクは、復旧可能な裏付けセッションとして扱われるのではなく、lost としてマークされます。 + - Cron タスクは、cron ランタイムがまだジョブを所有しているかを確認し、その後 `lost` にフォールバックする前に、永続化された cron 実行ログ/ジョブ状態から終端ステータスを復旧します。メモリ内の cron アクティブジョブセットについて権威を持つのは Gateway プロセスだけです。オフライン CLI 監査は永続履歴を使いますが、そのローカル Set が空であるという理由だけで cron タスクを lost にしません。 + - チャットに裏付けられた CLI タスクは、チャットセッション行だけでなく、所有しているライブ実行コンテキストを確認します。 - 完了クリーンアップもランタイムを考慮します。 + 完了時のクリーンアップもランタイムを認識します。 - - サブエージェント完了では、通知クリーンアップを続ける前に、子セッションで追跡されているブラウザータブ/プロセスをベストエフォートで閉じます。 - - 分離 cron 完了では、実行が完全に終了する前に、cron セッションで追跡されているブラウザータブ/プロセスをベストエフォートで閉じます。 - - 分離 cron 配信は、必要に応じて子孫サブエージェントのフォローアップを待ち、古い親の確認応答テキストを通知する代わりに抑制します。 - - サブエージェント完了配信は、最新の表示可能なアシスタントテキストを優先します。それが空の場合は、サニタイズされた最新の tool/toolResult テキストにフォールバックし、タイムアウトのみのツール呼び出し実行は短い部分進捗サマリーに折りたたまれることがあります。終端失敗実行は、キャプチャされた返信テキストを再生せずに失敗ステータスを通知します。 - - クリーンアップ失敗は、実際のタスク結果を隠しません。 + - サブエージェントの完了では、通知クリーンアップが続行する前に、子セッションの追跡対象ブラウザータブ/プロセスをベストエフォートで閉じます。 + - 分離 cron の完了では、実行が完全に終了する前に、cron セッションの追跡対象ブラウザータブ/プロセスをベストエフォートで閉じます。 + - 分離 cron の配信は、必要に応じて子孫サブエージェントのフォローアップを待機し、古くなった親の確認応答テキストを通知する代わりに抑制します。 + - サブエージェントの完了配信では、最新の表示可能な assistant テキストが優先されます。それが空の場合は、サニタイズ済みの最新 tool/toolResult テキストにフォールバックし、タイムアウトのみのツール呼び出し実行は短い部分進捗サマリーにまとめられることがあります。終端失敗実行では、キャプチャされた返信テキストを再生せずに失敗ステータスを通知します。 + - クリーンアップ失敗は、実際のタスク結果を覆い隠しません。 @@ -273,97 +271,97 @@ openclaw tasks notify state_changes openclaw tasks flow cancel ``` - 個々のバックグラウンドタスクレコードではなく、オーケストレーションしている Task Flow を確認したい場合に使用します。 + 個別のバックグラウンドタスクレコードではなく、それらをオーケストレーションする Task Flow に関心がある場合に使います。 ## チャットタスクボード（`/tasks`） -任意のチャットセッションで `/tasks` を使用すると、そのセッションにリンクされたバックグラウンドタスクを確認できます。ボードには、アクティブなタスクと最近完了したタスクが、ランタイム、ステータス、タイミング、進捗またはエラー詳細とともに表示されます。 +任意のチャットセッションで `/tasks` を使うと、そのセッションにリンクされたバックグラウンドタスクを確認できます。ボードには、アクティブなタスクと最近完了したタスクが、ランタイム、ステータス、タイミング、進捗またはエラー詳細とともに表示されます。 -現在のセッションに表示可能なリンク済みタスクがない場合、`/tasks` はエージェントローカルのタスク数にフォールバックするため、他セッションの詳細を漏らさずに概要を把握できます。 +現在のセッションに表示可能なリンク済みタスクがない場合、`/tasks` はエージェントローカルのタスク数にフォールバックするため、他セッションの詳細を漏らさずに概要を確認できます。 -完全なオペレーター台帳には CLI を使用します: `openclaw tasks list`。 +完全なオペレーター台帳には CLI を使います: `openclaw tasks list`。 -## ステータス統合（タスク圧力） +## ステータス統合（タスク負荷） -`openclaw status` には、一目でわかるタスクサマリーが含まれます。 +`openclaw status` には、ひと目で分かるタスクサマリーが含まれます。 ``` Tasks: 3 queued · 2 running · 1 issues ``` -サマリーは次を報告します。 +サマリーには次が報告されます。 - **active** — `queued` + `running` の数 - **failures** — `failed` + `timed_out` + `lost` の数 -- **byRuntime** — `acp`、`subagent`、`cron`、`cli` ごとの内訳 +- **byRuntime** — `acp`、`subagent`、`cron`、`cli` 別の内訳 -`/status` と `session_status` ツールはいずれも、クリーンアップを考慮したタスクスナップショットを使用します。アクティブなタスクが優先され、古い完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは今重要な内容に集中できます。 +`/status` と `session_status` ツールはいずれも、クリーンアップを認識したタスクスナップショットを使います。アクティブなタスクが優先され、古くなった完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは現在重要なものに集中できます。 ## ストレージとメンテナンス ### タスクの保存場所 -タスクレコードは、SQLite で次の場所に永続化されます。 +タスクレコードは次の SQLite に永続化されます。 ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -レジストリは Gateway 起動時にメモリへ読み込まれ、再起動後も耐久性を保つために書き込みを SQLite に同期します。 -Gateway は、SQLite のデフォルトの自動チェックポイントしきい値に加え、定期的およびシャットダウン時の `TRUNCATE` チェックポイントを使用して、SQLite write-ahead log を一定範囲に保ちます。 +レジストリは Gateway 起動時にメモリへ読み込まれ、再起動をまたいだ耐久性のために書き込みを SQLite に同期します。 +Gateway は、SQLite のデフォルト自動チェックポイントしきい値に加えて、定期的およびシャットダウン時の `TRUNCATE` チェックポイントを使うことで、SQLite の先行書き込みログを一定範囲に保ちます。 ### 自動メンテナンス -sweeper は **60 秒** ごとに実行され、4 つの処理を行います。 +スイーパーは **60 秒** ごとに実行され、4 つのことを処理します。 - アクティブなタスクに、まだ権威あるランタイムの裏付けがあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使用し、cron タスクはアクティブジョブ所有権を使用し、チャットに裏付けられた CLI タスクは所有する実行コンテキストを使用します。その裏付け状態が 5 分を超えて消失している場合、タスクは `lost` とマークされます。 + アクティブなタスクに、まだ権威あるランタイムの裏付けがあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使い、cron タスクはアクティブジョブの所有権を使い、チャットに裏付けられた CLI タスクは所有している実行コンテキストを使います。その裏付け状態が 5 分を超えて失われている場合、タスクは `lost` としてマークされます。 - 終端または孤立した親所有のワンショット ACP セッションを閉じ、アクティブな会話バインディングが残っていない場合にのみ、古い終端または孤立した永続 ACP セッションを閉じます。 + 終端または孤立した親所有のワンショット ACP セッションを閉じ、アクティブな会話バインディングが残っていない場合にのみ、古くなった終端または孤立した永続 ACP セッションを閉じます。 - - 終端タスクに `cleanupAfter` タイムスタンプを設定します（endedAt + 7 日）。保持期間中、lost タスクは監査で警告として表示されます。`cleanupAfter` が期限切れになった後、またはクリーンアップメタデータが欠落している場合はエラーになります。 + + 終端タスクに `cleanupAfter` タイムスタンプを設定します（endedAt + 7 日）。保持期間中、lost タスクは監査で引き続き警告として表示されます。`cleanupAfter` が期限切れになった後、またはクリーンアップメタデータが欠落している場合は、エラーになります。 - + `cleanupAfter` 日付を過ぎたレコードを削除します。 -**保持期間:** 終端タスクレコードは **7 日間** 保持され、その後自動的にプルーニングされます。設定は不要です。 +**保持:** 終端タスクレコードは **7 日間** 保持され、その後自動的に枝刈りされます。設定は不要です。 ## タスクと他システムの関係 - [Task Flow](/ja-JP/automation/taskflow) は、バックグラウンドタスクの上位にあるフローオーケストレーションレイヤーです。1 つのフローは、そのライフタイム中に managed または mirrored 同期モードを使用して複数のタスクを調整する場合があります。個々のタスクレコードを調べるには `openclaw tasks` を使用し、オーケストレーションしているフローを調べるには `openclaw tasks flow` を使用します。 + [Task Flow](/ja-JP/automation/taskflow) は、バックグラウンドタスクの上位にあるフローオーケストレーション層です。1 つのフローは、そのライフタイムを通じて、管理同期モードまたはミラー同期モードを使って複数のタスクを調整できます。個別のタスクレコードを調べるには `openclaw tasks` を使い、オーケストレーションしているフローを調べるには `openclaw tasks flow` を使います。 詳細は [Task Flow](/ja-JP/automation/taskflow) を参照してください。 - cron ジョブ**定義**は `~/.openclaw/cron/jobs.json` にあり、ランタイム実行状態はその横の `~/.openclaw/cron/jobs-state.json` にあります。**すべての** cron 実行は、メインセッションと分離実行の両方でタスクレコードを作成します。メインセッション cron タスクは、通知を生成せずに追跡できるよう、通知ポリシーのデフォルトが `silent` です。 + cron ジョブの**定義**は `~/.openclaw/cron/jobs.json` にあり、ランタイム実行状態はその隣の `~/.openclaw/cron/jobs-state.json` にあります。cron 実行は**すべて**タスクレコードを作成します。メインセッションと分離セッションの両方です。メインセッションの cron タスクはデフォルトで `silent` 通知ポリシーになっているため、通知を生成せずに追跡されます。 [Cron ジョブ](/ja-JP/automation/cron-jobs) を参照してください。 - Heartbeat 実行はメインセッションのターンであり、タスクレコードを作成しません。タスクが完了すると、結果をすぐに確認できるよう Heartbeat のウェイクをトリガーできます。 + Heartbeat の実行はメインセッションのターンです。タスクレコードは作成しません。タスクが完了すると、結果をすぐに確認できるように Heartbeat ウェイクをトリガーできます。 [Heartbeat](/ja-JP/gateway/heartbeat) を参照してください。 - タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（開始した人）を参照する場合があります。セッションは会話コンテキストであり、タスクはその上にあるアクティビティ追跡です。 + タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（それを開始した人）を参照することがあります。セッションは会話コンテキストであり、タスクはその上にあるアクティビティ追跡です。 - タスクの `runId` は、作業を実行しているエージェント実行にリンクします。エージェントのライフサイクルイベント（開始、終了、エラー）は、タスクステータスを自動的に更新します。ライフサイクルを手動で管理する必要はありません。 + タスクの `runId` は、作業を行っているエージェント実行にリンクします。エージェントのライフサイクルイベント（開始、終了、エラー）はタスクステータスを自動的に更新するため、ライフサイクルを手動で管理する必要はありません。 @@ -372,5 +370,5 @@ sweeper は **60 秒** ごとに実行され、4 つの処理を行います。 - [自動化とタスク](/ja-JP/automation) — すべての自動化メカニズムの概要 - [CLI: タスク](/ja-JP/cli/tasks) — CLI コマンドリファレンス - [Heartbeat](/ja-JP/gateway/heartbeat) — 定期的なメインセッションターン -- [Scheduled Tasks](/ja-JP/automation/cron-jobs) — バックグラウンド作業のスケジューリング -- [Task Flow](/ja-JP/automation/taskflow) — タスクの上位にあるフローオーケストレーション +- [スケジュール済みタスク](/ja-JP/automation/cron-jobs) — バックグラウンド作業のスケジューリング +- [Task Flow](/ja-JP/automation/taskflow) — タスク上位のフローオーケストレーション diff --git a/docs/ja-JP/channels/groups.md b/docs/ja-JP/channels/groups.md index cf3ac9dd8..cee68eca3 100644 --- a/docs/ja-JP/channels/groups.md +++ b/docs/ja-JP/channels/groups.md @@ -1,38 +1,38 @@ --- read_when: - - グループチャットの動作またはメンションゲーティングの変更 + - グループチャットの挙動またはメンション制御を変更する sidebarTitle: Groups -summary: 各サーフェスにおけるグループチャットの動作 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) +summary: 各サーフェスでのグループチャットの挙動 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) title: グループ x-i18n: - generated_at: "2026-04-30T16:27:42Z" + generated_at: "2026-05-01T05:00:19Z" model: gpt-5.5 provider: openai - source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e + source_hash: a8580f98ab03c89770688102da776627d8ce18b7bd34c4a687009fd4aabb6213 source_path: channels/groups.md workflow: 16 --- OpenClaw は、Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo の各サーフェスでグループチャットを一貫して扱います。 -## 初心者向け概要（2 分） +## 初心者向けイントロ（2 分） -OpenClaw は自分のメッセージングアカウント上に「存在」します。別個の WhatsApp ボットユーザーはありません。**あなた** がグループにいる場合、OpenClaw はそのグループを認識し、そこで応答できます。 +OpenClaw は自分のメッセージングアカウント上に「存在」します。別の WhatsApp bot ユーザーはありません。**あなた**がグループにいる場合、OpenClaw はそのグループを認識し、そこで応答できます。 デフォルトの動作: -- グループは制限されます（`groupPolicy: "allowlist"`）。 -- 明示的にメンションゲートを無効化しない限り、返信にはメンションが必要です。 -- グループ/チャンネルでの通常の最終返信は、デフォルトでは非公開です。ルームに表示される出力には `message` ツールを使用します。 +- グループは制限されています（`groupPolicy: "allowlist"`）。 +- メンションゲートを明示的に無効にしない限り、返信にはメンションが必要です。 +- グループ/チャンネル内の通常の最終返信は、デフォルトで非公開です。ルームに表示される出力には `message` ツールを使います。 -つまり、許可リストに含まれる送信者は、OpenClaw にメンションすることで OpenClaw をトリガーできます。 +つまり、許可リストに登録された送信者は、OpenClaw にメンションすることで OpenClaw をトリガーできます。 **要約** -- **DM アクセス** は `*.allowFrom` で制御されます。 -- **グループアクセス** は `*.groupPolicy` + 許可リスト（`*.groups`、`*.groupAllowFrom`）で制御されます。 -- **返信のトリガー** はメンションゲート（`requireMention`、`/activation`）で制御されます。 +- **DM アクセス**は `*.allowFrom` で制御されます。 +- **グループアクセス**は `*.groupPolicy` + 許可リスト（`*.groups`、`*.groupAllowFrom`）で制御されます。 +- **返信のトリガー**はメンションゲート（`requireMention`、`/activation`）で制御されます。 @@ -45,18 +45,21 @@ requireMention? yes -> mentioned? no -> store for context only otherwise -> reply ``` -## 表示される返信 +## 表示返信 グループ/チャンネルルームでは、OpenClaw のデフォルトは `messages.groupChat.visibleReplies: "message_tool"` です。 -つまり、エージェントはそのターンを引き続き処理し、メモリ/セッション状態を更新できますが、通常の最終回答はルームに自動投稿されません。表示される形で発言するには、エージェントは `message(action=send)` を使用します。 +これは、エージェントがターンを処理し、メモリ/セッション状態を更新できる一方で、通常の最終回答は自動的にはルームに投稿されないことを意味します。表示される形で発言するには、エージェントは `message(action=send)` を使います。 -直接チャットやその他のソースターンで同じツール専用の表示返信動作をグローバルに適用するには、`messages.visibleReplies: "message_tool"` を使用します。`messages.groupChat.visibleReplies` は、グループ/チャンネルルーム向けのより具体的なオーバーライドのままです。 +アクティブなツールポリシーの下でメッセージツールを利用できない場合、OpenClaw は応答を黙って抑制するのではなく、自動の表示返信にフォールバックします。 +`openclaw doctor` はこの不一致について警告します。 -これは、ほとんどの潜伏モードのターンでモデルに `NO_REPLY` と答えさせる古いパターンを置き換えます。ツール専用モードでは、表示上何もしないとは、単に message ツールを呼び出さないことを意味します。 +ダイレクトチャットやその他のソースターンに対して同じツールのみの表示返信動作をグローバルに適用するには、`messages.visibleReplies: "message_tool"` を使います。`messages.groupChat.visibleReplies` は、グループ/チャンネルルーム向けのより具体的なオーバーライドとして残ります。 -ツール専用モードでエージェントが作業している間も、入力中インジケーターは送信されます。これらのターンでは、エージェントが message ツールを呼び出すかどうかを決める前に通常のアシスタントメッセージテキストが存在しない可能性があるため、デフォルトのグループ入力中モードは "message" から "instant" にアップグレードされます。明示的な入力中モード設定がある場合は、引き続きそちらが優先されます。 +これは、ほとんどの待機モードのターンでモデルに `NO_REPLY` と回答させる古いパターンを置き換えます。ツールのみモードでは、表示されることを何もしないとは、単にメッセージツールを呼び出さないことを意味します。 -グループ/チャンネルルームで従来の自動最終返信に戻すには: +エージェントがツールのみモードで作業している間も、入力中インジケーターは送信されます。これらのターンでは、エージェントがメッセージツールを呼び出すかどうかを決める前に通常のアシスタントメッセージ本文が存在しない場合があるため、デフォルトのグループ入力モードは "message" から "instant" にアップグレードされます。明示的な入力モード設定は引き続き優先されます。 + +グループ/チャンネルルームで従来の自動最終返信を復元するには: ```json5 { @@ -68,9 +71,9 @@ otherwise -> reply } ``` -ファイルが保存されると、Gateway は `messages` 設定をホットリロードします。デプロイでファイル監視または設定リロードが無効になっている場合のみ再起動してください。 +Gateway は、ファイル保存後に `messages` 設定をホットリロードします。デプロイでファイル監視または設定リロードが無効になっている場合にのみ再起動してください。 -すべてのソースチャットで、表示される出力を message ツール経由にするには: +すべてのソースチャットで、表示出力をメッセージツール経由にする必要がある場合: ```json5 { @@ -80,70 +83,70 @@ otherwise -> reply } ``` -ネイティブスラッシュコマンド（Discord、Telegram、およびネイティブコマンド対応のその他のサーフェス）は `visibleReplies: "message_tool"` をバイパスし、チャンネルネイティブのコマンド UI が期待する応答を得られるように、常に表示される形で返信します。これは検証済みのネイティブコマンドターンにのみ適用されます。テキストとして入力された `/...` コマンドや通常のチャットターンは、引き続き設定済みのグループデフォルトに従います。 +ネイティブスラッシュコマンド（Discord、Telegram、およびネイティブコマンド対応のその他のサーフェス）は `visibleReplies: "message_tool"` をバイパスし、チャンネルネイティブのコマンド UI が期待する応答を受け取れるように常に表示返信します。これは検証済みのネイティブコマンドターンにのみ適用されます。テキスト入力された `/...` コマンドと通常のチャットターンは、引き続き設定済みのグループデフォルトに従います。 ## コンテキストの可視性と許可リスト -グループの安全性には 2 つの異なる制御が関係します。 +グループの安全性には、2 つの異なる制御が関わります。 -- **トリガー承認**: 誰がエージェントをトリガーできるか（`groupPolicy`、`groups`、`groupAllowFrom`、チャンネル固有の許可リスト）。 -- **コンテキストの可視性**: どの補足コンテキストをモデルに注入するか（返信テキスト、引用、スレッド履歴、転送メタデータ）。 +- **トリガー認可**: エージェントをトリガーできる人（`groupPolicy`、`groups`、`groupAllowFrom`、チャンネル固有の許可リスト）。 +- **コンテキストの可視性**: モデルに注入される補足コンテキスト（返信テキスト、引用、スレッド履歴、転送メタデータ）。 -デフォルトでは、OpenClaw は通常のチャット動作を優先し、受信したコンテキストをほぼそのまま保持します。つまり、許可リストは主に誰がアクションをトリガーできるかを決めるものであり、引用や履歴スニペットすべてに対する普遍的な編集境界ではありません。 +デフォルトでは、OpenClaw は通常のチャット動作を優先し、コンテキストをほぼ受信したまま保持します。つまり、許可リストは主に、すべての引用や履歴スニペットに対する普遍的な墨消し境界ではなく、誰がアクションをトリガーできるかを決定します。 - - 一部のチャンネルでは、特定の経路で補足コンテキストに対して送信者ベースのフィルタリングをすでに適用しています（例: Slack スレッドのシード、Matrix の返信/スレッド検索）。 - - 他のチャンネルでは、引用/返信/転送コンテキストを受信したまま渡します。 + - 一部のチャンネルでは、特定のパスで補足コンテキストに対して送信者ベースのフィルタリングをすでに適用しています（たとえば Slack のスレッドシード、Matrix の返信/スレッド検索）。 + - 他のチャンネルでは、引用/返信/転送コンテキストを受信したまま渡しています。 - - - `contextVisibility: "all"`（デフォルト）は、現在の受信どおりの動作を維持します。 + + - `contextVisibility: "all"`（デフォルト）は、現在の受信時のままの動作を維持します。 - `contextVisibility: "allowlist"` は、補足コンテキストを許可リスト内の送信者にフィルタリングします。 - - `contextVisibility: "allowlist_quote"` は `allowlist` に、明示的な引用/返信の例外を 1 つ加えたものです。 + - `contextVisibility: "allowlist_quote"` は `allowlist` に加えて、明示的な引用/返信の例外を 1 つ許可します。 - この強化モデルがチャンネル全体で一貫して実装されるまでは、サーフェスごとの差異があるものとして扱ってください。 + この強化モデルがチャンネル全体で一貫して実装されるまでは、サーフェスごとの差異があることを想定してください。 ![グループメッセージフロー](/images/groups-flow.svg) -やりたいこと... +目的別の設定: | 目的 | 設定する内容 | | -------------------------------------------- | ---------------------------------------------------------- | -| すべてのグループを許可するが @メンション時のみ返信する | `groups: { "*": { requireMention: true } }` | -| すべてのグループ返信を無効化する | `groupPolicy: "disabled"` | +| すべてのグループを許可し、@メンション時のみ返信する | `groups: { "*": { requireMention: true } }` | +| すべてのグループ返信を無効にする | `groupPolicy: "disabled"` | | 特定のグループのみ | `groups: { "": { ... } }`（`"*"` キーなし） | -| グループで自分だけがトリガーできる | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` | +| グループであなただけがトリガーできる | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` | ## セッションキー -- グループセッションは `agent:::group:` セッションキーを使用します（ルーム/チャンネルは `agent:::channel:` を使用します）。 -- Telegram のフォーラムトピックでは、各トピックが独自のセッションを持つように、グループ ID に `:topic:` を追加します。 -- 直接チャットはメインセッションを使用します（設定されている場合は送信者ごとのセッション）。 +- グループセッションは `agent:::group:` セッションキーを使います（ルーム/チャンネルは `agent:::channel:` を使います）。 +- Telegram フォーラムトピックは、各トピックが独自のセッションを持つように、グループ ID に `:topic:` を追加します。 +- ダイレクトチャットはメインセッション（または設定されている場合は送信者ごと）を使います。 - Heartbeat はグループセッションではスキップされます。 ## パターン: 個人 DM + 公開グループ（単一エージェント） -はい。「個人」トラフィックが **DM** で、「公開」トラフィックが **グループ** なら、この構成はうまく機能します。 +はい。「個人」トラフィックが **DM** で、「公開」トラフィックが **グループ** であれば、これはうまく機能します。 -理由: 単一エージェントモードでは、DM は通常 **メイン** セッションキー（`agent:main:main`）に入り、グループは常に **非メイン** セッションキー（`agent:main::group:`）を使用します。`mode: "non-main"` でサンドボックス化を有効にすると、それらのグループセッションは設定済みのサンドボックスバックエンドで実行され、メインの DM セッションはホスト上に残ります。バックエンドを選択しない場合、Docker がデフォルトです。 +理由: 単一エージェントモードでは、DM は通常 **メイン** セッションキー（`agent:main:main`）に入り、グループは常に **非メイン** セッションキー（`agent:main::group:`）を使います。`mode: "non-main"` でサンドボックス化を有効にすると、それらのグループセッションは設定済みのサンドボックスバックエンドで実行され、メインの DM セッションはホスト上に残ります。バックエンドを選択しない場合、Docker がデフォルトのバックエンドです。 -これにより、1 つのエージェント「頭脳」（共有ワークスペース + メモリ）で、2 つの実行姿勢を持てます。 +これにより、1 つのエージェントの「頭脳」（共有ワークスペース + メモリ）を持ちながら、2 つの実行姿勢を取れます。 -- **DM**: 完全なツール（ホスト） +- **DM**: フルツール（ホスト） - **グループ**: サンドボックス + 制限付きツール -本当に分離されたワークスペース/ペルソナ（「個人」と「公開」が絶対に混ざってはいけない）が必要な場合は、2 つ目のエージェント + バインディングを使用してください。[マルチエージェントルーティング](/ja-JP/concepts/multi-agent)を参照してください。 +本当に分離されたワークスペース/ペルソナ（「個人」と「公開」が決して混ざらない必要がある）を必要とする場合は、2 つ目のエージェント + バインディングを使います。[マルチエージェントルーティング](/ja-JP/concepts/multi-agent)を参照してください。 - + ```json5 { agents: { @@ -167,8 +170,8 @@ otherwise -> reply } ``` - - 「ホストアクセスなし」ではなく「グループはフォルダー X だけを見られる」ようにしたい場合は、`workspaceAccess: "none"` を維持し、許可リストに含めたパスだけをサンドボックスにマウントします。 + + 「ホストアクセスなし」ではなく「グループはフォルダー X だけ見える」ようにしたい場合は、`workspaceAccess: "none"` のままにして、許可リストに登録したパスだけをサンドボックスにマウントします。 ```json5 { @@ -201,12 +204,12 @@ otherwise -> reply ## 表示ラベル -- UI ラベルは、利用可能な場合 `displayName` を使用し、`:` としてフォーマットされます。 -- `#room` はルーム/チャンネル用に予約されています。グループチャットは `g-` を使用します（小文字、スペース -> `-`、`#@+._-` を保持）。 +- UI ラベルは、利用可能な場合は `displayName` を使い、`:` としてフォーマットされます。 +- `#room` はルーム/チャンネル用に予約されています。グループチャットは `g-` を使います（小文字、スペース -> `-`、`#@+._-` は保持）。 ## グループポリシー -チャンネルごとに、グループ/ルームメッセージの処理方法を制御します。 +チャンネルごとにグループ/ルームメッセージの処理方法を制御します。 ```json5 { @@ -261,40 +264,40 @@ otherwise -> reply - - `groupPolicy` はメンションゲート（@メンションを要求するもの）とは別です。 - - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: `groupAllowFrom` を使用します（フォールバック: 明示的な `allowFrom`）。 - - Signal: `groupAllowFrom` は、受信 Signal グループ ID または送信者の電話番号/UUID のどちらにも一致できます。 - - DM ペアリング承認（`*-allowFrom` ストアエントリ）は DM アクセスにのみ適用されます。グループ送信者の承認は、グループ許可リストで明示的に行われます。 - - Discord: 許可リストは `channels.discord.guilds..channels` を使用します。 - - Slack: 許可リストは `channels.slack.channels` を使用します。 - - Matrix: 許可リストは `channels.matrix.groups` を使用します。ルーム ID またはエイリアスを推奨します。参加済みルーム名の検索はベストエフォートで、解決できない名前はランタイムで無視されます。送信者を制限するには `channels.matrix.groupAllowFrom` を使用します。ルームごとの `users` 許可リストもサポートされています。 - - グループ DM は別に制御されます（`channels.discord.dm.*`、`channels.slack.dm.*`）。 - - Telegram の許可リストは、ユーザー ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）またはユーザー名（`"@alice"` または `"alice"`）に一致できます。プレフィックスは大文字小文字を区別しません。 + - `groupPolicy` は、メンションゲート（@メンションを必要とするもの）とは別です。 + - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: `groupAllowFrom` を使います（フォールバック: 明示的な `allowFrom`）。 + - Signal: `groupAllowFrom` は、受信した Signal グループ ID または送信者の電話番号/UUID のどちらにも一致できます。 + - DM ペアリング承認（`*-allowFrom` ストアエントリ）は DM アクセスにのみ適用されます。グループ送信者の認可は、グループ許可リストに対して明示的なままです。 + - Discord: 許可リストは `channels.discord.guilds..channels` を使います。 + - Slack: 許可リストは `channels.slack.channels` を使います。 + - Matrix: 許可リストは `channels.matrix.groups` を使います。ルーム ID またはエイリアスを推奨します。参加済みルーム名の検索はベストエフォートであり、解決できない名前は実行時に無視されます。送信者を制限するには `channels.matrix.groupAllowFrom` を使います。ルームごとの `users` 許可リストもサポートされています。 + - グループ DM は別途制御されます（`channels.discord.dm.*`、`channels.slack.dm.*`）。 + - Telegram の許可リストは、ユーザー ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）またはユーザー名（`"@alice"` または `"alice"`）に一致できます。プレフィックスは大文字と小文字を区別しません。 - デフォルトは `groupPolicy: "allowlist"` です。グループ許可リストが空の場合、グループメッセージはブロックされます。 - - ランタイム安全性: プロバイダーブロックが完全に存在しない場合（`channels.` がない場合）、グループポリシーは `channels.defaults.groupPolicy` を継承するのではなく、フェイルクローズモード（通常は `allowlist`）にフォールバックします。 + - 実行時の安全性: provider ブロックが完全に存在しない場合（`channels.` がない場合）、グループポリシーは `channels.defaults.groupPolicy` を継承するのではなく、フェイルクローズモード（通常は `allowlist`）にフォールバックします。 -簡単なメンタルモデル（グループメッセージの評価順序）: +簡単なメンタルモデル（グループメッセージの評価順）: - `groupPolicy`（open/disabled/allowlist）。 + `groupPolicy` (open/disabled/allowlist)。 - グループ許可リスト（`*.groups`、`*.groupAllowFrom`、チャンネル固有の許可リスト）。 + グループ許可リスト (`*.groups`、`*.groupAllowFrom`、チャンネル固有の許可リスト)。 - - メンションゲート（`requireMention`、`/activation`）。 + + メンションゲーティング (`requireMention`、`/activation`)。 -## メンションゲート（デフォルト） +## メンションゲーティング (デフォルト) -グループメッセージは、グループごとに上書きされない限りメンションを必要とします。デフォルトは各サブシステムの `*.groups."*"` 配下にあります。 +グループメッセージは、グループごとに上書きされていない限りメンションが必要です。デフォルトは各サブシステムの `*.groups."*"` の下にあります。 -ボットメッセージへの返信は、チャンネルが返信メタデータに対応している場合、暗黙的なメンションとして扱われます。ボットメッセージの引用も、引用メタデータを公開するチャンネルでは暗黙的なメンションとして扱われる場合があります。現在の組み込みケースには、Telegram、WhatsApp、Slack、Discord、Microsoft Teams、ZaloUser が含まれます。 +ボットメッセージへの返信は、チャンネルが返信メタデータをサポートしている場合、暗黙的なメンションとして扱われます。ボットメッセージの引用も、引用メタデータを公開するチャンネルでは暗黙的なメンションとして扱われる場合があります。現在の組み込みケースには Telegram、WhatsApp、Slack、Discord、Microsoft Teams、ZaloUser が含まれます。 ```json5 { @@ -334,44 +337,44 @@ otherwise -> reply - - `mentionPatterns` は大文字小文字を区別しない安全な正規表現パターンです。無効なパターンと安全でないネストした反復形式は無視されます。 + - `mentionPatterns` は大文字小文字を区別しない安全な正規表現パターンです。不正なパターンや安全でない入れ子の繰り返し形式は無視されます。 - 明示的なメンションを提供するサーフェスは引き続き通過します。パターンはフォールバックです。 - - エージェントごとのオーバーライド: `agents.list[].groupChat.mentionPatterns`（複数のエージェントがグループを共有する場合に便利です）。 - - メンションゲーティングは、メンション検出が可能な場合（ネイティブメンションまたは `mentionPatterns` が設定されている場合）にのみ適用されます。 - - グループまたは送信者を許可リストに入れても、メンションゲーティングは無効になりません。すべてのメッセージでトリガーする必要がある場合は、そのグループの `requireMention` を `false` に設定します。 - - グループチャットのプロンプトコンテキストは、解決済みのサイレント返信指示を毎ターン保持します。ワークスペースファイルで `NO_REPLY` の仕組みを重複させるべきではありません。 - - サイレント返信が許可されているグループでは、クリーンな空のモデルターンまたは推論のみのモデルターンは、`NO_REPLY` と同等のサイレントとして扱われます。ダイレクトチャットでは、ダイレクトのサイレント返信が明示的に許可されている場合のみ同じ扱いになります。それ以外の場合、空の返信は失敗したエージェントターンのままです。 - - Discord のデフォルトは `channels.discord.guilds."*"` にあります（ギルド/チャンネルごとにオーバーライド可能）。 - - グループ履歴コンテキストはチャンネルをまたいで一貫してラップされ、**保留中のみ**です（メンションゲーティングによってスキップされたメッセージ）。グローバルデフォルトには `messages.groupChat.historyLimit` を使用し、オーバーライドには `channels..historyLimit`（または `channels..accounts.*.historyLimit`）を使用します。無効にするには `0` を設定します。 + - エージェントごとの上書き: `agents.list[].groupChat.mentionPatterns` (複数のエージェントがグループを共有する場合に便利です)。 + - メンションゲーティングは、メンション検出が可能な場合 (ネイティブメンション、または `mentionPatterns` が設定されている場合) にのみ適用されます。 + - グループまたは送信者を許可リストに追加しても、メンションゲーティングは無効になりません。すべてのメッセージでトリガーする必要がある場合は、そのグループの `requireMention` を `false` に設定してください。 + - グループチャットのプロンプトコンテキストは、各ターンで解決済みのサイレント返信指示を持ちます。ワークスペースファイルで `NO_REPLY` の仕組みを重複させないでください。 + - サイレント返信が許可されているグループでは、クリーンな空のモデルターンまたは推論のみのモデルターンは、`NO_REPLY` と同等のサイレントとして扱われます。ダイレクトチャットでも、ダイレクトのサイレント返信が明示的に許可されている場合にのみ同じ扱いになります。それ以外の場合、空の返信は失敗したエージェントターンのままです。 + - Discord のデフォルトは `channels.discord.guilds."*"` にあります (ギルド/チャンネルごとに上書き可能)。 + - グループ履歴コンテキストはチャンネル全体で一律にラップされ、**保留中のみ** です (メンションゲーティングによりスキップされたメッセージ)。グローバルデフォルトには `messages.groupChat.historyLimit` を使用し、上書きには `channels..historyLimit` (または `channels..accounts.*.historyLimit`) を使用します。無効にするには `0` を設定します。 -## グループ/チャンネルのツール制限（任意） +## グループ/チャンネルのツール制限 (任意) -一部のチャンネル設定では、**特定のグループ/ルーム/チャンネル内**で利用できるツールを制限できます。 +一部のチャンネル設定では、**特定のグループ/ルーム/チャンネル内** で利用できるツールを制限できます。 -- `tools`: グループ全体でツールを許可/拒否します。 -- `toolsBySender`: グループ内の送信者ごとのオーバーライドです。明示的なキープレフィックスを使用します: `id:`、`e164:`、`username:`、`name:`、および `"*"` ワイルドカード。従来のプレフィックスなしキーも引き続き受け付けられ、`id:` としてのみ照合されます。 +- `tools`: グループ全体のツールを許可/拒否します。 +- `toolsBySender`: グループ内の送信者ごとの上書きです。明示的なキープレフィックスを使用します: `id:`、`e164:`、`username:`、`name:`、および `"*"` ワイルドカード。従来のプレフィックスなしキーも引き続き受け付けられ、`id:` としてのみ照合されます。 -解決順序（最も具体的なものが優先されます）: +解決順序 (最も具体的なものが優先): - グループ/チャンネルの `toolsBySender` の一致。 + グループ/チャンネルの `toolsBySender` 照合。 グループ/チャンネルの `tools`。 - デフォルト（`"*"`）の `toolsBySender` の一致。 + デフォルト (`"*"`) の `toolsBySender` 照合。 - デフォルト（`"*"`）の `tools`。 + デフォルト (`"*"`) の `tools`。 -例（Telegram）: +例 (Telegram): ```json5 { @@ -392,18 +395,18 @@ otherwise -> reply ``` -グループ/チャンネルのツール制限は、グローバル/エージェントのツールポリシーに追加して適用されます（拒否は引き続き優先されます）。一部のチャンネルでは、ルーム/チャンネルに異なるネストを使用します（例: Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 +グループ/チャンネルのツール制限は、グローバル/エージェントのツールポリシーに加えて適用されます (拒否は引き続き優先されます)。一部のチャンネルでは、ルーム/チャンネルに異なるネストを使用します (例: Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`)。 ## グループ許可リスト -`channels.whatsapp.groups`、`channels.telegram.groups`、または `channels.imessage.groups` が設定されている場合、キーはグループ許可リストとして機能します。デフォルトのメンション動作を設定しつつすべてのグループを許可するには、`"*"` を使用します。 +`channels.whatsapp.groups`、`channels.telegram.groups`、または `channels.imessage.groups` が設定されている場合、キーはグループ許可リストとして機能します。デフォルトのメンション動作を設定しながらすべてのグループを許可するには、`"*"` を使用します。 -よくある混同: DM ペアリング承認はグループ認可と同じではありません。DM ペアリングに対応するチャンネルでは、ペアリングストアが解除するのは DM のみです。グループコマンドには、`groupAllowFrom` やそのチャンネルのドキュメント化された設定フォールバックなど、設定許可リストによる明示的なグループ送信者認可が引き続き必要です。 +よくある混同: DM ペアリング承認はグループ認可と同じではありません。DM ペアリングをサポートするチャンネルでは、ペアリングストアが解除するのは DM のみです。グループコマンドには、`groupAllowFrom` やそのチャンネルで文書化された設定フォールバックなど、設定許可リストによる明示的なグループ送信者認可が引き続き必要です。 -一般的な意図（コピー/貼り付け）: +一般的な目的 (コピー/貼り付け): @@ -413,7 +416,7 @@ otherwise -> reply } ``` - + ```json5 { channels: { @@ -438,7 +441,7 @@ otherwise -> reply } ``` - + ```json5 { channels: { @@ -453,44 +456,44 @@ otherwise -> reply -## 有効化（所有者のみ） +## 有効化 (オーナーのみ) -グループ所有者は、グループごとの有効化を切り替えられます。 +グループオーナーは、グループごとの有効化を切り替えられます。 - `/activation mention` - `/activation always` -所有者は `channels.whatsapp.allowFrom`（未設定の場合はボット自身の E.164）によって決定されます。コマンドは単独のメッセージとして送信します。他のサーフェスは現在 `/activation` を無視します。 +オーナーは `channels.whatsapp.allowFrom` (未設定の場合はボット自身の E.164) によって決定されます。コマンドは単独のメッセージとして送信してください。現在、他のサーフェスは `/activation` を無視します。 ## コンテキストフィールド グループの受信ペイロードは次を設定します。 - `ChatType=group` -- `GroupSubject`（既知の場合） -- `GroupMembers`（既知の場合） -- `WasMentioned`（メンションゲーティング結果） +- `GroupSubject` (既知の場合) +- `GroupMembers` (既知の場合) +- `WasMentioned` (メンションゲーティングの結果) - Telegram フォーラムトピックには `MessageThreadId` と `IsForum` も含まれます。 チャンネル固有のメモ: -- BlueBubbles は、`GroupMembers` を設定する前に、名前のない macOS グループ参加者をローカルの連絡先データベースから任意で補強できます。これはデフォルトでオフであり、通常のグループゲーティングに通過した後にのみ実行されます。 +- BlueBubbles は、`GroupMembers` に入力する前に、名前のない macOS グループ参加者をローカルの連絡先データベースから任意で補強できます。これはデフォルトではオフで、通常のグループゲーティングが通過した後にのみ実行されます。 -エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループの導入が含まれます。これにより、モデルに対して、人間のように応答すること、Markdown テーブルを避けること、空行を最小限にして通常のチャット間隔に従うこと、リテラルの `\n` シーケンスを入力しないことを思い出させます。チャンネル由来のグループ名と参加者ラベルは、インラインのシステム指示ではなく、フェンス付きの信頼されていないメタデータとしてレンダリングされます。 +エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループのイントロが含まれます。これはモデルに、人間のように応答し、Markdown テーブルを避け、空行を最小限にして通常のチャットの間隔に従い、リテラルの `\n` シーケンスを入力しないよう促します。チャンネル由来のグループ名と参加者ラベルは、インラインのシステム指示ではなく、フェンス付きの信頼されていないメタデータとしてレンダリングされます。 ## iMessage の詳細 -- ルーティングまたは許可リスト登録には `chat_id:` を優先します。 +- ルーティングまたは許可リスト追加では `chat_id:` を優先してください。 - チャット一覧: `imsg chats --limit 20`。 - グループ返信は常に同じ `chat_id` に戻ります。 ## WhatsApp システムプロンプト -グループとダイレクトのプロンプト解決、ワイルドカード動作、アカウントオーバーライドのセマンティクスを含む、標準的な WhatsApp システムプロンプトルールについては [WhatsApp](/ja-JP/channels/whatsapp#system-prompts) を参照してください。 +グループおよびダイレクトプロンプトの解決、ワイルドカード動作、アカウント上書きセマンティクスを含む、正規の WhatsApp システムプロンプトルールについては [WhatsApp](/ja-JP/channels/whatsapp#system-prompts) を参照してください。 ## WhatsApp の詳細 -WhatsApp のみの動作（履歴注入、メンション処理の詳細）については、[グループメッセージ](/ja-JP/channels/group-messages) を参照してください。 +WhatsApp のみの動作 (履歴注入、メンション処理の詳細) については [グループメッセージ](/ja-JP/channels/group-messages) を参照してください。 ## 関連 diff --git a/docs/ja-JP/ci.md b/docs/ja-JP/ci.md index 99053493a..e334c5c7a 100644 --- a/docs/ja-JP/ci.md +++ b/docs/ja-JP/ci.md @@ -1,75 +1,75 @@ --- read_when: - - CI ジョブが実行された理由、または実行されなかった理由を理解する必要がある + - CI ジョブが実行された理由、または実行されなかった理由を把握する必要がある - 失敗している GitHub Actions チェックをデバッグしています - リリース検証の実行または再実行を調整しています -summary: CI ジョブグラフ、スコープゲート、リリース包括、ローカルコマンド相当 +summary: CI ジョブグラフ、スコープゲート、リリース包括項目、およびローカルコマンド相当 title: CI パイプライン x-i18n: - generated_at: "2026-04-30T18:38:38Z" + generated_at: "2026-05-01T05:00:31Z" model: gpt-5.5 provider: openai - source_hash: a24afc27606ac7f4e9ead89acdd319bffa23336610f8a6cd8b576ea1a5b233dd + source_hash: aea06f9f336f9a478a284473b5c5f38730b87837b1acb0390161bf2c455f6c41 source_path: ci.md workflow: 16 --- -OpenClaw CI は `main` への各プッシュとすべてのプルリクエストで実行されます。`preflight` ジョブは差分を分類し、関係のない領域だけが変更された場合は高コストなレーンを無効にします。手動の `workflow_dispatch` 実行は、意図的にスマートスコープをバイパスし、リリース候補と広範な検証のためにグラフ全体へ展開します。Android レーンは `include_android` を通じてオプトインのままです。リリース専用の Plugin カバレッジは別の [`Plugin Prerelease`](#plugin-prerelease) ワークフローにあり、[`Full Release Validation`](#full-release-validation) または明示的な手動ディスパッチからのみ実行されます。 +OpenClaw CI は `main` へのすべての push とすべての pull request で実行されます。`preflight` ジョブは diff を分類し、関係のない領域だけが変更された場合は高コストなレーンを無効にします。手動の `workflow_dispatch` 実行は意図的にスマートスコープをバイパスし、リリース候補と広範な検証のためにグラフ全体へ展開します。Android レーンは `include_android` によるオプトインのままです。リリース専用の Plugin カバレッジは別の [`Plugin Prerelease`](#plugin-prerelease) ワークフローにあり、[`Full Release Validation`](#full-release-validation) または明示的な手動ディスパッチからのみ実行されます。 ## パイプライン概要 -| ジョブ | 目的 | 実行タイミング | -| -------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------- | -| `preflight` | docs のみの変更、変更スコープ、変更された拡張、CI マニフェストの構築を検出 | 非ドラフトのプッシュと PR で常時 | -| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | 非ドラフトのプッシュと PR で常時 | -| `security-dependency-audit` | npm アドバイザリに対する、依存関係なしの本番ロックファイル監査 | 非ドラフトのプッシュと PR で常時 | -| `security-fast` | 高速セキュリティジョブの必須集約 | 非ドラフトのプッシュと PR で常時 | -| `check-dependencies` | 本番 Knip の依存関係のみのパスと、未使用ファイル許可リストガード | Node 関連の変更 | -| `build-artifacts` | `dist/`、Control UI、ビルド済み成果物チェック、再利用可能な下流成果物をビルド | Node 関連の変更 | -| `checks-fast-core` | バンドル/Plugin 契約/プロトコルチェックなどの高速 Linux 正当性レーン | Node 関連の変更 | -| `checks-fast-contracts-channels` | 安定した集約チェック結果を持つ、シャード化されたチャンネル契約チェック | Node 関連の変更 | -| `checks-node-core-test` | チャンネル、バンドル、契約、拡張レーンを除く Core Node テストシャード | Node 関連の変更 | -| `check` | 本番型、lint、ガード、テスト型、厳格な smoke の、シャード化された主要ローカルゲート相当 | Node 関連の変更 | -| `check-additional` | アーキテクチャ、境界、拡張サーフェスガード、パッケージ境界、gateway-watch シャード | Node 関連の変更 | -| `build-smoke` | ビルド済み CLI の smoke テストと起動時メモリ smoke | Node 関連の変更 | -| `checks` | ビルド済み成果物チャンネルテストの検証 | Node 関連の変更 | -| `checks-node-compat-node22` | Node 22 互換性ビルドと smoke レーン | リリース用の手動 CI ディスパッチ | -| `check-docs` | Docs のフォーマット、lint、壊れたリンクのチェック | Docs が変更された場合 | -| `skills-python` | Python バックの Skills 用 Ruff + pytest | Python Skills 関連の変更 | -| `checks-windows` | Windows 固有のプロセス/パステストと、共有ランタイム import specifier の回帰 | Windows 関連の変更 | -| `macos-node` | 共有ビルド済み成果物を使う macOS TypeScript テストレーン | macOS 関連の変更 | -| `macos-swift` | macOS アプリの Swift lint、ビルド、テスト | macOS 関連の変更 | -| `android` | 両方のフレーバーの Android ユニットテストと、1 つの debug APK ビルド | Android 関連の変更 | -| `test-performance-agent` | 信頼済みアクティビティ後の日次 Codex 低速テスト最適化 | Main CI 成功または手動ディスパッチ | +| ジョブ | 目的 | 実行タイミング | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | +| `preflight` | docs のみの変更、変更されたスコープ、変更された extensions を検出し、CI マニフェストを構築する | draft でない push と PR では常に | +| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | draft でない push と PR では常に | +| `security-dependency-audit` | npm advisories に対する、依存関係なしの本番 lockfile 監査 | draft でない push と PR では常に | +| `security-fast` | 高速セキュリティジョブの必須集約 | draft でない push と PR では常に | +| `check-dependencies` | 本番 Knip 依存関係のみのパスと未使用ファイル許可リストガード | Node 関連の変更 | +| `build-artifacts` | `dist/`、Control UI、ビルド済みアーティファクトチェック、再利用可能な下流アーティファクトをビルド | Node 関連の変更 | +| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速 Linux 正当性レーン | Node 関連の変更 | +| `checks-fast-contracts-channels` | 安定した集約チェック結果を伴う、シャード化されたチャンネル契約チェック | Node 関連の変更 | +| `checks-node-core-test` | channel、bundled、contract、extension レーンを除く Core Node テストシャード | Node 関連の変更 | +| `check` | シャード化されたメインのローカルゲート相当: 本番型、lint、ガード、テスト型、厳格な smoke | Node 関連の変更 | +| `check-additional` | アーキテクチャ、境界、extension サーフェスガード、package-boundary、gateway-watch シャード | Node 関連の変更 | +| `build-smoke` | ビルド済み CLI smoke テストと起動メモリ smoke | Node 関連の変更 | +| `checks` | ビルド済みアーティファクトのチャンネルテスト用検証 | Node 関連の変更 | +| `checks-node-compat-node22` | Node 22 互換性ビルドと smoke レーン | リリース用の手動 CI ディスパッチ | +| `check-docs` | docs のフォーマット、lint、リンク切れチェック | docs が変更された場合 | +| `skills-python` | Python バックの Skills 向け Ruff + pytest | Python skill 関連の変更 | +| `checks-windows` | Windows 固有の process/path テストと共有ランタイム import specifier 回帰 | Windows 関連の変更 | +| `macos-node` | 共有ビルド済みアーティファクトを使う macOS TypeScript テストレーン | macOS 関連の変更 | +| `macos-swift` | macOS アプリ向け Swift lint、ビルド、テスト | macOS 関連の変更 | +| `android` | 両方の flavor の Android unit test と 1 つの debug APK ビルド | Android 関連の変更 | +| `test-performance-agent` | 信頼済みアクティビティ後の日次 Codex 低速テスト最適化 | main CI 成功または手動ディスパッチ | ## フェイルファスト順序 1. `preflight` は、どのレーンがそもそも存在するかを決定します。`docs-scope` と `changed-scope` のロジックはこのジョブ内のステップであり、独立したジョブではありません。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、`skills-python` は、より重い成果物ジョブやプラットフォームマトリックスジョブを待たずにすばやく失敗します。 -3. `build-artifacts` は高速 Linux レーンと重なって実行されるため、共有ビルドの準備ができ次第、下流のコンシューマーを開始できます。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、`skills-python` は、より重いアーティファクトとプラットフォームのマトリックスジョブを待たずにすばやく失敗します。 +3. `build-artifacts` は高速 Linux レーンと重なって実行されるため、共有ビルドの準備ができ次第、下流の利用側が開始できます。 4. その後、より重いプラットフォームとランタイムのレーンが展開されます: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、`android`。 -同じ PR または `main` ref に新しいプッシュが入ると、GitHub は置き換えられたジョブを `cancelled` としてマークすることがあります。同じ ref の最新実行も失敗していない限り、これは CI ノイズとして扱ってください。集約シャードチェックは `!cancelled() && always()` を使用するため、通常のシャード失敗は引き続き報告しますが、ワークフロー全体がすでに置き換えられた後にはキューに入りません。自動 CI の concurrency キーはバージョン付き (`CI-v7-*`) なので、古いキューグループ内の GitHub 側ゾンビが新しい main 実行を無期限にブロックすることはありません。手動のフルスイート実行は `CI-manual-v1-*` を使用し、進行中の実行をキャンセルしません。 +同じ PR または `main` ref に新しい push が入ると、GitHub は置き換えられたジョブを `cancelled` としてマークする場合があります。同じ ref の最新実行も失敗していない限り、これは CI ノイズとして扱います。集約シャードチェックは `!cancelled() && always()` を使うため、通常のシャード失敗は引き続き報告しますが、ワークフロー全体がすでに置き換えられた後にはキューに入りません。自動 CI concurrency key はバージョン付き (`CI-v7-*`) なので、古いキューグループに残った GitHub 側のゾンビが新しい main 実行を無期限にブロックすることはありません。手動フルスイート実行は `CI-manual-v1-*` を使い、進行中の実行をキャンセルしません。 ## スコープとルーティング -スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` のユニットテストでカバーされています。手動ディスパッチは changed-scope 検出をスキップし、すべてのスコープ対象領域が変更されたかのように preflight マニフェストを動作させます。 +スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` の unit test でカバーされています。手動ディスパッチは changed-scope 検出をスキップし、すべてのスコープ領域が変更されたかのように preflight マニフェストを動作させます。 -- **CI ワークフロー編集** は Node CI グラフとワークフロー lint を検証しますが、それだけで Windows、Android、macOS ネイティブビルドを強制することはありません。これらのプラットフォームレーンは、プラットフォームソースの変更にスコープされたままです。 -- **CI ルーティングのみの編集、選択された低コストな core-test fixture 編集、狭い Plugin 契約ヘルパー/テストルーティング編集** は、高速な Node のみのマニフェストパスを使用します: `preflight`、セキュリティ、単一の `checks-fast-core` タスクです。そのパスは、変更が高速タスクが直接実行するルーティングまたはヘルパーサーフェスに限定される場合、ビルド成果物、Node 22 互換性、チャンネル契約、完全な Core シャード、バンドル Plugin シャード、追加ガードマトリックスをスキップします。 -- **Windows Node チェック** は、Windows 固有のプロセス/パスラッパー、npm/pnpm/UI runner ヘルパー、パッケージマネージャー設定、そのレーンを実行する CI ワークフローサーフェスにスコープされます。関係のないソース、Plugin、install-smoke、テストのみの変更は Linux Node レーンに残ります。 +- **CI workflow edits** は Node CI グラフとワークフロー lint を検証しますが、それ自体では Windows、Android、macOS のネイティブビルドを強制しません。これらのプラットフォームレーンはプラットフォームソース変更にスコープされたままです。 +- **CI routing-only edits, selected cheap core-test fixture edits, and narrow plugin contract helper/test-routing edits** は、高速な Node のみのマニフェストパスを使います: `preflight`、security、単一の `checks-fast-core` タスクです。このパスは、変更がその高速タスクで直接実行されるルーティングまたは helper サーフェスに限定される場合、ビルドアーティファクト、Node 22 互換性、チャンネル契約、完全な core シャード、bundled-plugin シャード、追加ガードマトリックスをスキップします。 +- **Windows Node checks** は、Windows 固有の process/path wrapper、npm/pnpm/UI runner helper、package manager config、そのレーンを実行する CI workflow サーフェスにスコープされます。無関係なソース、Plugin、install-smoke、test-only の変更は Linux Node レーンに残ります。 -最も遅い Node テストファミリーは、各ジョブを小さく保ちつつ runner を過剰予約しないように分割またはバランス調整されています。チャンネル契約は 3 つの重み付きシャードとして実行され、小さな Core ユニットレーンはペアにされ、auto-reply は 4 つのバランス済みワーカーとして実行されます（reply サブツリーは agent-runner、dispatch、commands/state-routing シャードに分割されます）。また、agentic Gateway/Plugin 設定は、ビルド済み成果物を待つ代わりに、既存のソースのみの agentic Node ジョブ全体に分散されます。広範なブラウザー、QA、メディア、その他の Plugin テストは、共有 Plugin キャッチオールではなく専用の Vitest 設定を使用します。include-pattern シャードは CI シャード名を使ってタイミングエントリを記録するため、`.artifacts/vitest-shard-timings.json` は設定全体とフィルター済みシャードを区別できます。`check-additional` はパッケージ境界の compile/canary 作業をまとめ、runtime topology アーキテクチャを gateway watch カバレッジから分離します。boundary guard シャードは、小さな独立ガードを 1 つのジョブ内で同時に実行します。Gateway watch、チャンネルテスト、Core support-boundary シャードは、`dist/` と `dist-runtime/` がすでにビルドされた後に `build-artifacts` 内で同時に実行されます。 +最も遅い Node テストファミリーは、各ジョブが小さく保たれ、runner を過剰に確保しないように分割またはバランス調整されています。チャンネル契約は 3 つの重み付きシャードとして実行され、小さな core unit レーンはペア化され、auto-reply は 4 つのバランスされた worker として実行されます（reply サブツリーは agent-runner、dispatch、commands/state-routing シャードに分割）。agentic gateway/plugin config は、ビルド済みアーティファクトを待つ代わりに、既存の source-only agentic Node ジョブ全体に分散されます。広範な browser、QA、media、その他の Plugin テストは、共有 Plugin catch-all ではなく専用の Vitest config を使います。include-pattern シャードは CI シャード名を使ってタイミングエントリを記録するため、`.artifacts/vitest-shard-timings.json` は config 全体とフィルター済みシャードを区別できます。`check-additional` は package-boundary の compile/canary 作業をまとめ、runtime topology アーキテクチャを gateway watch カバレッジから分離します。boundary guard シャードは、小さな独立ガードを 1 つのジョブ内で並行実行します。Gateway watch、チャンネルテスト、core support-boundary シャードは、`dist/` と `dist-runtime/` がすでにビルドされた後に `build-artifacts` 内で並行実行されます。 -Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party フレーバーには個別の source set や manifest はありません。そのユニットテストレーンは、SMS/call-log BuildConfig フラグ付きでフレーバーを引き続きコンパイルしつつ、Android 関連の各プッシュで重複した debug APK packaging ジョブを避けます。 +Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party flavor には個別の source set や manifest はありません。その unit-test レーンは SMS/call-log BuildConfig フラグ付きで flavor を引き続きコンパイルしつつ、Android 関連の各 push で重複した debug APK packaging ジョブを避けます。 -`check-dependencies` シャードは `pnpm deadcode:dependencies`（最新の Knip バージョンに固定された本番 Knip の依存関係のみのパスで、`dlx` インストールでは pnpm の最小リリース経過期間が無効）と `pnpm deadcode:unused-files` を実行します。後者は Knip の本番未使用ファイル検出結果を `scripts/deadcode-unused-files.allowlist.mjs` と比較します。未使用ファイルガードは、PR が新しい未レビューの未使用ファイルを追加した場合、または古い許可リストエントリを残した場合に失敗します。一方で、Knip が静的に解決できない意図的な dynamic Plugin、生成物、ビルド、live-test、package bridge サーフェスは保持します。 +`check-dependencies` シャードは `pnpm deadcode:dependencies`（最新の Knip バージョンに固定された本番 Knip 依存関係のみのパスで、`dlx` install では pnpm の minimum release age を無効化）と `pnpm deadcode:unused-files` を実行します。後者は Knip の本番未使用ファイル検出結果を `scripts/deadcode-unused-files.allowlist.mjs` と比較します。unused-file guard は、意図的な動的 Plugin、生成物、ビルド、live-test、package bridge サーフェスなど Knip が静的に解決できないものを保持しながら、PR が新しい未レビューの未使用ファイルを追加した場合や古い許可リストエントリを残した場合に失敗します。 ## 手動ディスパッチ -手動 CI ディスパッチは通常の CI と同じジョブグラフを実行しますが、Android 以外のすべてのスコープ対象レーンを強制的に有効にします: Linux Node シャード、バンドル Plugin シャード、チャンネル契約、Node 22 互換性、`check`、`check-additional`、build smoke、docs チェック、Python Skills、Windows、macOS、Control UI i18n です。スタンドアロンの手動 CI ディスパッチは `include_android=true` の場合のみ Android を実行します。フルリリースの包括ワークフローは `include_android=true` を渡して Android を有効にします。Plugin prerelease static checks、リリース専用の `agentic-plugins` シャード、完全な extension batch sweep、Plugin prerelease Docker レーンは CI から除外されます。Docker prerelease スイートは、`Full Release Validation` が release-validation gate を有効にして別の `Plugin Prerelease` ワークフローをディスパッチした場合にのみ実行されます。 +手動 CI ディスパッチは通常の CI と同じジョブグラフを実行しますが、Android 以外のすべてのスコープ付きレーンを強制的に有効にします: Linux Node シャード、bundled-plugin シャード、チャンネル契約、Node 22 互換性、`check`、`check-additional`、build smoke、docs チェック、Python Skills、Windows、macOS、Control UI i18n です。スタンドアロンの手動 CI ディスパッチは `include_android=true` の場合にのみ Android を実行します。フルリリースの umbrella は `include_android=true` を渡して Android を有効にします。Plugin prerelease static チェック、リリース専用の `agentic-plugins` シャード、完全な extension batch sweep、Plugin prerelease Docker レーンは CI から除外されます。Docker prerelease スイートは、`Full Release Validation` が release-validation gate を有効にして別の `Plugin Prerelease` ワークフローをディスパッチした場合にのみ実行されます。 -手動実行は一意の concurrency group を使用するため、リリース候補のフルスイートが、同じ ref 上の別のプッシュや PR 実行によってキャンセルされることはありません。任意の `target_ref` 入力により、信頼済みの呼び出し元は、選択されたディスパッチ ref のワークフローファイルを使いながら、ブランチ、タグ、または完全なコミット SHA に対してそのグラフを実行できます。 +手動実行は一意の concurrency group を使うため、リリース候補のフルスイートが同じ ref 上の別の push や PR 実行によってキャンセルされることはありません。任意の `target_ref` 入力により、信頼済みの呼び出し元は、選択された dispatch ref のワークフローファイルを使いながら、ブランチ、タグ、または完全な commit SHA に対してそのグラフを実行できます。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -77,17 +77,17 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## Runners +## ランナー | ランナー | ジョブ | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`、高速セキュリティジョブと集約（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速プロトコル/コントラクト/バンドル済みチェック、シャード化されたチャンネルコントラクトチェック、lint を除く `check` シャード、`check-additional` シャードと集約、Node テスト集約検証、ドキュメントチェック、Python Skills、workflow-sanity、labeler、auto-response。install-smoke preflight も GitHub ホストの Ubuntu を使うため、Blacksmith マトリクスはより早くキューに入れられる | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、低負荷の Plugin シャード、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types`、`check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node テストシャード、バンドル済み Plugin テストシャード、`android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（CPU 依存が強く、8 vCPU は節約分よりコストが大きかった）。install-smoke Docker ビルド（32 vCPU は節約分よりキュー時間のコストが大きかった） | +| `ubuntu-24.04` | `preflight`、高速セキュリティジョブと集約（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速プロトコル/契約/同梱チェック、シャード化されたチャンネル契約チェック、lint を除く `check` シャード、`check-additional` シャードと集約、Node テスト集約ベリファイア、ドキュメントチェック、Python Skills、workflow-sanity、labeler、auto-response。install-smoke の preflight も GitHub ホストの Ubuntu を使うため、Blacksmith マトリックスはより早くキューに入れられる | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、軽量な Plugin シャード、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types`、`check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node テストシャード、同梱 Plugin テストシャード、`android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（8 vCPU は節約できた分よりもコストが大きいほど CPU 依存が強い）。install-smoke Docker ビルド（32-vCPU は節約できた分よりもキュー時間のコストが大きい） | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` では `macos-node`。フォークでは `macos-latest` にフォールバックする | -| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` では `macos-swift`。フォークでは `macos-latest` にフォールバックする | +| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`。フォークでは `macos-latest` にフォールバックする | +| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-swift`。フォークでは `macos-latest` にフォールバックする | ## ローカルでの同等コマンド @@ -117,19 +117,31 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac ## 完全リリース検証 -`Full Release Validation` は、「リリース前にすべてを実行する」ための手動の包括ワークフローです。ブランチ、タグ、または完全なコミット SHA を受け取り、そのターゲットで手動の `CI` ワークフローをディスパッチし、リリース専用の Plugin/パッケージ/静的/Docker 検証のために `Plugin Prerelease` をディスパッチし、install smoke、package acceptance、Docker リリースパススイート、live/E2E、OpenWebUI、QA Lab parity、Matrix、Telegram レーンのために `OpenClaw Release Checks` をディスパッチします。公開済みパッケージ仕様が指定された場合は、公開後の `NPM Telegram Beta E2E` ワークフローも実行できます。 +`Full Release Validation` は、「リリース前にすべてを実行する」ための手動包括ワークフローです。ブランチ、タグ、または完全なコミット SHA を受け取り、その対象で手動 `CI` ワークフローをディスパッチし、リリース専用の Plugin/パッケージ/静的/Docker 証明用に `Plugin Prerelease` をディスパッチし、インストールスモーク、パッケージ受け入れ、Docker リリースパススイート、live/E2E、OpenWebUI、QA Lab パリティ、Matrix、Telegram レーン用に `OpenClaw Release Checks` をディスパッチします。公開済みパッケージ仕様が指定された場合は、公開後の `NPM Telegram Beta E2E` ワークフローも実行できます。 -`release_profile` は、リリースチェックへ渡す live/provider の範囲を制御します。 +ステージマトリックス、正確なワークフロージョブ名、プロファイルの違い、成果物、 +および絞り込んだ再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation) +を参照してください。 -- `minimum` は最速の OpenAI/core リリースクリティカルレーンを維持します。 +`release_profile` は、リリースチェックに渡される live/provider の範囲を制御します。 +手動リリースワークフローのデフォルトは `stable` です。広範な勧告用 provider/media マトリックスを +意図的に実行したい場合にのみ `full` を使ってください。 + +- `minimum` は最速の OpenAI/core リリース重要レーンに絞ります。 - `stable` は安定版 provider/backend セットを追加します。 -- `full` は広範な advisory provider/media マトリクスを実行します。 +- `full` は広範な勧告用 provider/media マトリックスを実行します。 -包括ワークフローはディスパッチされた子実行 ID を記録し、最後の `Verify full validation` ジョブが現在の子実行の結果を再チェックし、各子実行の最遅ジョブテーブルを追記します。子ワークフローを再実行して成功した場合は、包括結果とタイミング要約を更新するために親の検証ジョブだけを再実行してください。 +包括ワークフローはディスパッチした子 run ID を記録し、最後の `Verify full validation` ジョブが現在の子 run の結論を再チェックし、各子 run の最も遅いジョブの表を追記します。子ワークフローを再実行して green になった場合は、包括結果とタイミング要約を更新するため、親のベリファイアジョブだけを再実行してください。 -復旧用に、`Full Release Validation` と `OpenClaw Release Checks` はどちらも `rerun_group` を受け付けます。リリース候補には `all`、通常の完全な CI 子だけには `ci`、すべてのリリース子には `release-checks`、より狭いグループには包括ワークフロー上で `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、または `npm-telegram` を使います。これにより、集中修正後の失敗したリリースボックスの再実行を限定できます。 +復旧用に、`Full Release Validation` と `OpenClaw Release Checks` はどちらも `rerun_group` を受け取ります。リリース候補には `all`、通常の完全 CI 子だけには `ci`、Plugin prerelease 子だけには `plugin-prerelease`、すべてのリリース子には `release-checks`、またはより狭いグループとして、包括ワークフロー上で `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` を使います。これにより、絞り込んだ修正後に、失敗したリリースボックスの再実行範囲を限定できます。 -`OpenClaw Release Checks` は、信頼されたワークフロー ref を使って選択された ref を一度だけ `release-package-under-test` tarball に解決し、そのアーティファクトを live/E2E リリースパス Docker ワークフローと package acceptance シャードの両方へ渡します。これにより、リリースボックス全体でパッケージのバイト列が一貫し、複数の子ジョブで同じ候補を再パックすることを避けられます。 +`OpenClaw Release Checks` は、信頼されたワークフロー ref を使って選択された ref を一度だけ `release-package-under-test` tarball に解決し、その成果物を live/E2E リリースパス Docker ワークフローとパッケージ受け入れシャードの両方に渡します。これにより、リリースボックス間でパッケージのバイト列が一貫し、複数の子ジョブで同じ候補を再パッケージすることを避けられます。 + +`ref=main` かつ `rerun_group=all` の重複した `Full Release Validation` run は、 +古い包括ワークフローを置き換えます。親モニターは親がキャンセルされたとき、すでに +ディスパッチ済みの子ワークフローをすべてキャンセルするため、新しい main 検証が +古い 2 時間の release-check run の後ろで待機することはありません。リリースブランチ/タグの +検証と絞り込んだ再実行グループでは `cancel-in-progress: false` を維持します。 ## Live と E2E シャード @@ -137,7 +149,7 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac - `native-live-src-agents` - `native-live-src-gateway-core` -- provider でフィルターされた `native-live-src-gateway-profiles` ジョブ +- provider でフィルタされた `native-live-src-gateway-profiles` ジョブ - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -145,57 +157,57 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- 分割されたメディア audio/video シャードと、provider でフィルターされた music シャード +- 分割されたメディア audio/video シャードと provider でフィルタされた music シャード -これにより、同じファイルカバレッジを保ちながら、遅い live provider の失敗を再実行および診断しやすくなります。集約用の `native-live-extensions-o-z`、`native-live-extensions-media`、`native-live-extensions-media-music` シャード名は、手動の単発再実行でも引き続き有効です。 +これにより、同じファイルカバレッジを維持しながら、遅い live provider の失敗を再実行して診断しやすくなります。集約 `native-live-extensions-o-z`、`native-live-extensions-media`、`native-live-extensions-media-music` のシャード名は、手動の一括再実行でも引き続き有効です。 -ネイティブ live media シャードは、`Live Media Runner Image` ワークフローでビルドされる `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 内で実行されます。このイメージには `ffmpeg` と `ffprobe` が事前インストールされています。media ジョブはセットアップ前にバイナリを検証するだけです。Docker バックの live スイートは通常の Blacksmith ランナー上に維持してください。コンテナジョブはネストされた Docker テストを起動する場所として不適切です。 +ネイティブ live media シャードは、`Live Media Runner Image` ワークフローでビルドされる `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 内で実行されます。このイメージには `ffmpeg` と `ffprobe` が事前インストールされています。media ジョブはセットアップ前にバイナリを検証するだけです。Docker ベースの live スイートは通常の Blacksmith ランナー上に維持してください。コンテナジョブはネストされた Docker テストを起動する場所として適していません。 -Docker バックの live model/backend シャードは、選択されたコミットごとに別の共有 `ghcr.io/openclaw/openclaw-live-test:` イメージを使います。live リリースワークフローはそのイメージを一度だけビルドしてプッシュし、その後 Docker live model、Gateway、CLI backend、ACP bind、Codex harness シャードは `OPENCLAW_SKIP_DOCKER_BUILD=1` で実行されます。これらのシャードがフルソース Docker ターゲットを個別に再ビルドする場合、そのリリース実行は設定ミスであり、重複イメージビルドで実時間を浪費します。 +Docker ベースの live model/backend シャードは、選択されたコミットごとに別の共有 `ghcr.io/openclaw/openclaw-live-test:` イメージを使います。live リリースワークフローはそのイメージを一度だけビルドしてプッシュし、その後 Docker live model、provider シャード化 Gateway、CLI backend、ACP bind、Codex harness シャードが `OPENCLAW_SKIP_DOCKER_BUILD=1` で実行されます。Gateway Docker シャードは、スタックしたコンテナやクリーンアップ経路がリリースチェック予算全体を消費せずに速く失敗するよう、ワークフロージョブタイムアウトより短い明示的なスクリプトレベルの `timeout` 上限を持ちます。これらのシャードが完全なソース Docker ターゲットを個別に再ビルドする場合、そのリリース run は設定ミスであり、重複イメージビルドに実時間を浪費します。 ## パッケージ受け入れ -「このインストール可能な OpenClaw パッケージは製品として動作するか」という問いには `Package Acceptance` を使います。これは通常の CI とは異なります。通常の CI はソースツリーを検証しますが、package acceptance はインストールまたは更新後にユーザーが実行するものと同じ Docker E2E ハーネスを通して、単一の tarball を検証します。 +「このインストール可能な OpenClaw パッケージは製品として機能するか」という問いには、`Package Acceptance` を使います。これは通常の CI とは異なります。通常の CI はソースツリーを検証しますが、パッケージ受け入れは、インストールまたは更新後にユーザーが実行するものと同じ Docker E2E harness を通じて単一の tarball を検証します。 ### ジョブ -1. `resolve_package` は `workflow_ref` をチェックアウトし、1 つのパッケージ候補を解決し、`.artifacts/docker-e2e-package/openclaw-current.tgz` を書き込み、`.artifacts/docker-e2e-package/package-candidate.json` を書き込み、両方を `package-under-test` アーティファクトとしてアップロードし、GitHub ステップ要約にソース、ワークフロー ref、パッケージ ref、バージョン、SHA-256、プロファイルを出力します。 -2. `docker_acceptance` は、`ref=workflow_ref` と `package_artifact_name=package-under-test` で `openclaw-live-and-e2e-checks-reusable.yml` を呼び出します。再利用可能ワークフローはそのアーティファクトをダウンロードし、tarball インベントリを検証し、必要に応じて package-digest Docker イメージを準備し、ワークフローチェックアウトをパックする代わりにそのパッケージに対して選択された Docker レーンを実行します。プロファイルが複数の対象 `docker_lanes` を選択する場合、再利用可能ワークフローはパッケージと共有イメージを一度だけ準備し、その後それらのレーンを一意のアーティファクトを持つ並列の対象 Docker ジョブとして展開します。 -3. `package_telegram` は任意で `NPM Telegram Beta E2E` を呼び出します。`telegram_mode` が `none` でなく、Package Acceptance が解決したものがある場合は同じ `package-under-test` アーティファクトをインストールします。スタンドアロンの Telegram ディスパッチは、公開済み npm 仕様を引き続きインストールできます。 +1. `resolve_package` は `workflow_ref` をチェックアウトし、1 つのパッケージ候補を解決し、`.artifacts/docker-e2e-package/openclaw-current.tgz` を書き込み、`.artifacts/docker-e2e-package/package-candidate.json` を書き込み、両方を `package-under-test` アーティファクトとしてアップロードし、GitHub ステップサマリーにソース、ワークフロー ref、パッケージ ref、バージョン、SHA-256、プロファイルを出力します。 +2. `docker_acceptance` は `ref=workflow_ref` と `package_artifact_name=package-under-test` で `openclaw-live-and-e2e-checks-reusable.yml` を呼び出します。再利用可能ワークフローはそのアーティファクトをダウンロードし、tarball インベントリを検証し、必要に応じて package-digest Docker イメージを準備し、ワークフローのチェックアウトをパックする代わりに、そのパッケージに対して選択された Docker レーンを実行します。プロファイルが複数の対象 `docker_lanes` を選択する場合、再利用可能ワークフローはパッケージと共有イメージを一度だけ準備し、それらのレーンを一意のアーティファクトを持つ並列の対象 Docker ジョブとしてファンアウトします。 +3. `package_telegram` は任意で `NPM Telegram Beta E2E` を呼び出します。これは `telegram_mode` が `none` でない場合に実行され、Package Acceptance がパッケージを解決した場合は同じ `package-under-test` アーティファクトをインストールします。スタンドアロンの Telegram ディスパッチでは、公開済み npm spec を引き続きインストールできます。 4. `summary` は、パッケージ解決、Docker acceptance、または任意の Telegram レーンが失敗した場合にワークフローを失敗させます。 ### 候補ソース -- `source=npm` は `openclaw@beta`、`openclaw@latest`、または `openclaw@2026.4.27-beta.2` のような正確な OpenClaw リリースバージョンのみを受け付けます。公開済みの beta/stable 受け入れにこれを使用します。 -- `source=ref` は、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパックします。リゾルバーは OpenClaw のブランチ/タグを取得し、選択したコミットがリポジトリのブランチ履歴またはリリースタグから到達可能であることを検証し、切り離されたワークツリーに依存関係をインストールして、`scripts/package-openclaw-for-docker.mjs` でパックします。 -- `source=url` は HTTPS の `.tgz` をダウンロードします。`package_sha256` が必須です。 -- `source=artifact` は `artifact_run_id` と `artifact_name` から 1 つの `.tgz` をダウンロードします。`package_sha256` は任意ですが、外部共有アーティファクトには指定するべきです。 +- `source=npm` は `openclaw@beta`、`openclaw@latest`、または `openclaw@2026.4.27-beta.2` のような正確な OpenClaw リリースバージョンのみを受け付けます。公開済み beta/stable acceptance にこれを使用します。 +- `source=ref` は信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパックします。リゾルバーは OpenClaw ブランチ/タグをフェッチし、選択されたコミットがリポジトリのブランチ履歴またはリリースタグから到達可能であることを検証し、デタッチされたワークツリーで依存関係をインストールし、`scripts/package-openclaw-for-docker.mjs` でパックします。 +- `source=url` は HTTPS の `.tgz` をダウンロードします。`package_sha256` は必須です。 +- `source=artifact` は `artifact_run_id` と `artifact_name` から 1 つの `.tgz` をダウンロードします。`package_sha256` は任意ですが、外部共有アーティファクトでは指定するべきです。 -`workflow_ref` と `package_ref` は分けておきます。`workflow_ref` はテストを実行する信頼済みのワークフロー/ハーネスコードです。`package_ref` は `source=ref` のときにパックされるソースコミットです。これにより、現在のテストハーネスは古いワークフローロジックを実行せずに、古い信頼済みソースコミットを検証できます。 +`workflow_ref` と `package_ref` は分けておきます。`workflow_ref` はテストを実行する信頼済みのワークフロー/ハーネスコードです。`package_ref` は `source=ref` の場合にパックされるソースコミットです。これにより、現在のテストハーネスで、古いワークフローロジックを実行せずに、古い信頼済みソースコミットを検証できます。 ### スイートプロファイル - `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload` -- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update` +- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update` - `product` — `package` に加えて `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` - `full` — OpenWebUI を含む完全な Docker リリースパスチャンク -- `custom` — 正確な `docker_lanes`。`suite_profile=custom` のとき必須 +- `custom` — 正確な `docker_lanes`。`suite_profile=custom` の場合に必須 -`package` プロファイルはオフライン Plugin カバレッジを使用するため、公開済みパッケージの検証はライブ ClawHub の可用性に左右されません。任意の Telegram レーンは `NPM Telegram Beta E2E` の `package-under-test` アーティファクトを再利用し、公開済み npm 仕様パスはスタンドアロンのディスパッチ用に保持されます。 +`package` プロファイルはオフライン Plugin カバレッジを使用するため、公開済みパッケージ検証はライブの ClawHub 可用性に左右されません。任意の Telegram レーンは `NPM Telegram Beta E2E` で `package-under-test` アーティファクトを再利用し、公開済み npm spec パスはスタンドアロンディスパッチ用に保持されます。 -リリースチェックは、`source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'`、`telegram_mode=mock-openai` で Package Acceptance を呼び出します。リリースパス Docker チャンクは重複する package/update/plugin レーンをカバーします。Package Acceptance は、同じ解決済みパッケージ tarball に対して、アーティファクトネイティブの bundled-channel 互換性、オフライン Plugin、Telegram の証明を保持します。Cross-OS リリースチェックは引き続き OS 固有のオンボーディング、インストーラー、プラットフォーム挙動をカバーします。package/update の製品検証は Package Acceptance から始めるべきです。Windows の packaged レーンと installer fresh レーンは、インストール済みパッケージが生の絶対 Windows パスから browser-control オーバーライドをインポートできることも検証します。OpenAI cross-OS agent-turn smoke は、設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` をデフォルトとし、そうでない場合は `openai/gpt-5.4-mini` を使用するため、インストールと Gateway の証明は高速かつ決定的に保たれます。 +リリースチェックは、`source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'`、`telegram_mode=mock-openai` で Package Acceptance を呼び出します。リリースパス Docker チャンクは、重複する package/update/plugin レーンをカバーします。Package Acceptance は、同じ解決済みパッケージ tarball に対して、アーティファクトネイティブな bundled-channel 互換性、オフライン Plugin、Telegram の証明を保持します。Cross-OS リリースチェックは引き続き OS 固有のオンボーディング、インストーラー、プラットフォーム動作をカバーします。package/update のプロダクト検証は Package Acceptance から始めるべきです。`published-upgrade-survivor` Docker レーンは、1 回の実行につき 1 つの公開済みパッケージベースラインを検証します。Package Acceptance では、解決済みの `package-under-test` tarball が常に候補であり、`published_upgrade_survivor_baseline` が公開済みベースラインを選択します。既定値は `openclaw@latest` です。失敗レーンの再実行コマンドはそのベースラインを保持します。ローカル実行では、`OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` を `openclaw@2026.4.15` のような正確なパッケージに設定できます。公開済みレーンは、焼き込み済みの `openclaw config set` コマンドレシピでベースラインを構成し、その後レシピ手順を `summary.json` に記録します。より広範な以前のバージョンのカバレッジでは、正確な `published_upgrade_survivor_baseline` 値ごとに Package Acceptance をシャードするべきです。Windows の packaged レーンと installer fresh レーンは、インストール済みパッケージが raw の絶対 Windows パスから browser-control override をインポートできることも検証します。OpenAI cross-OS agent-turn smoke は、`OPENCLAW_CROSS_OS_OPENAI_MODEL` が設定されている場合はそれを既定で使用し、それ以外の場合は `openai/gpt-5.4-mini` を使用するため、インストールと Gateway の証明は高速かつ決定的なままです。 ### レガシー互換性ウィンドウ -Package Acceptance には、すでに公開済みのパッケージ向けに範囲を限定したレガシー互換性ウィンドウがあります。`2026.4.25` までのパッケージ（`2026.4.25-beta.*` を含む）は、互換性パスを使用できます。 +Package Acceptance には、すでに公開済みのパッケージ向けに範囲を限定したレガシー互換性ウィンドウがあります。`2026.4.25-beta.*` を含む `2026.4.25` までのパッケージは、互換性パスを使用できます。 -- `dist/postinstall-inventory.json` 内の既知の private QA エントリは、tarball から省略されたファイルを指す場合があります。 +- `dist/postinstall-inventory.json` の既知の private QA エントリは、tarball から省略されたファイルを指している場合があります。 - パッケージがそのフラグを公開していない場合、`doctor-switch` は `gateway install --wrapper` 永続化サブケースをスキップする場合があります。 -- `update-channel-switch` は、tarball 由来の偽 git fixture から欠落している `pnpm.patchedDependencies` を刈り込む場合があり、永続化された `update.channel` の欠落をログに記録する場合があります。 -- Plugin smoke はレガシーの install-record 位置を読み取る場合があり、または marketplace install-record 永続化の欠落を許容する場合があります。 -- `plugin-update` は、install record と no-reinstall 挙動が変更されないことを引き続き要求しながら、設定メタデータ移行を許容する場合があります。 +- `update-channel-switch` は、tarball 由来の fake git fixture から欠落している `pnpm.patchedDependencies` を刈り込む場合があり、永続化された `update.channel` の欠落をログ出力する場合があります。 +- Plugin smoke はレガシーの install-record 場所を読む場合があり、または marketplace install-record 永続化の欠落を許容する場合があります。 +- `plugin-update` は、install record と no-reinstall 動作が変わらないことを引き続き要求しつつ、config メタデータ移行を許容する場合があります。 -公開済みの `2026.4.26` パッケージは、すでに出荷済みのローカルビルドメタデータスタンプファイルについて警告する場合もあります。それ以降のパッケージは最新の契約を満たす必要があります。同じ条件は警告やスキップではなく失敗になります。 +公開済みの `2026.4.26` パッケージでは、すでに出荷済みだったローカルビルドメタデータスタンプファイルについても警告する場合があります。それ以降のパッケージは最新の契約を満たす必要があります。同じ条件は、警告またはスキップではなく失敗になります。 ### 例 @@ -238,152 +250,152 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -失敗した package acceptance 実行をデバッグするときは、`resolve_package` サマリーから開始して、パッケージソース、バージョン、SHA-256 を確認します。次に `docker_acceptance` 子実行とその Docker アーティファクト（`.artifacts/docker-tests/**/summary.json`、`failures.json`、レーンログ、フェーズタイミング、再実行コマンド）を調査します。完全なリリース検証を再実行するのではなく、失敗した package プロファイルまたは正確な Docker レーンを再実行することを優先します。 +失敗した package acceptance 実行をデバッグする場合は、まず `resolve_package` サマリーでパッケージソース、バージョン、SHA-256 を確認します。次に、`docker_acceptance` 子実行とその Docker アーティファクトを調べます: `.artifacts/docker-tests/**/summary.json`、`failures.json`、レーンログ、フェーズタイミング、再実行コマンド。完全なリリース検証を再実行するのではなく、失敗したパッケージプロファイルまたは正確な Docker レーンを再実行することを優先します。 ## インストール smoke 別個の `Install Smoke` ワークフローは、独自の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。smoke カバレッジを `run_fast_install_smoke` と `run_full_install_smoke` に分割します。 -- **高速パス** は、Docker/package サーフェス、バンドル済み Plugin パッケージ/マニフェスト変更、または Docker smoke ジョブが実行する core plugin/channel/gateway/Plugin SDK サーフェスに触れるプルリクエストで実行されます。ソースのみのバンドル済み Plugin 変更、テストのみの編集、docs のみの編集では Docker ワーカーは予約されません。高速パスはルート Dockerfile イメージを一度ビルドし、CLI をチェックし、agents delete shared-workspace CLI smoke を実行し、コンテナ gateway-network e2e を実行し、バンドル済み extension ビルド引数を検証し、240 秒の集約コマンドタイムアウト（各シナリオの Docker 実行は別途上限あり）内で、範囲を限定した bundled-plugin Docker プロファイルを実行します。 -- **フルパス** は、夜間スケジュール実行、手動ディスパッチ、workflow-call リリースチェック、および installer/package/Docker サーフェスに本当に触れるプルリクエスト向けに、QR package install と installer Docker/update カバレッジを保持します。フルモードでは、install-smoke は target-SHA GHCR ルート Dockerfile smoke イメージを 1 つ準備または再利用し、QR package install、ルート Dockerfile/Gateway smoke、installer/update smoke、高速 bundled-plugin Docker E2E を別々のジョブとして実行するため、installer 作業はルートイメージ smoke の後ろで待機しません。 +- **高速パス** は、Docker/package サーフェス、バンドル済み Plugin package/manifest の変更、または Docker smoke ジョブが実行する core plugin/channel/gateway/Plugin SDK サーフェスに触れるプルリクエストで実行されます。ソースのみのバンドル済み Plugin 変更、テストのみの編集、docs のみの編集は Docker worker を予約しません。高速パスはルート Dockerfile イメージを一度ビルドし、CLI をチェックし、agents delete shared-workspace CLI smoke を実行し、container gateway-network e2e を実行し、バンドル済み拡張機能の build arg を検証し、240 秒の集約コマンドタイムアウト内で範囲限定の bundled-plugin Docker プロファイルを実行します（各シナリオの Docker 実行は別個に上限設定されます）。 +- **フルパス** は、nightly scheduled 実行、手動ディスパッチ、workflow-call リリースチェック、および installer/package/Docker サーフェスに実際に触れるプルリクエスト向けに、QR package install と installer Docker/update カバレッジを保持します。full モードでは、install-smoke は 1 つの target-SHA GHCR ルート Dockerfile smoke イメージを準備または再利用し、その後 QR package install、ルート Dockerfile/Gateway smoke、installer/update smoke、高速 bundled-plugin Docker E2E を別々のジョブとして実行するため、installer 作業がルートイメージ smoke の後ろで待つことはありません。 -`main` へのプッシュ（マージコミットを含む）はフルパスを強制しません。変更スコープロジックがプッシュでフルカバレッジを要求する場合、ワークフローは高速 Docker smoke を維持し、フル install smoke は夜間またはリリース検証に任せます。 +`main` push（マージコミットを含む）はフルパスを強制しません。変更スコープロジックが push でフルカバレッジを要求する場合でも、ワークフローは高速 Docker smoke を維持し、フル install smoke は nightly またはリリース検証に任せます。 -遅い Bun global install image-provider smoke は、`run_bun_global_install_smoke` で別途ゲートされます。夜間スケジュールとリリースチェックワークフローから実行され、手動の `Install Smoke` ディスパッチはこれを opt in できますが、プルリクエストと `main` へのプッシュでは実行されません。QR と installer Docker テストは、それぞれ独自のインストール重視 Dockerfile を維持します。 +低速な Bun global install image-provider smoke は、`run_bun_global_install_smoke` によって別個にゲートされます。これは nightly schedule とリリースチェックワークフローから実行され、手動の `Install Smoke` ディスパッチでは opt in できますが、プルリクエストと `main` push では実行されません。QR と installer Docker テストは、それぞれ独自のインストール向け Dockerfile を維持します。 ## ローカル Docker E2E -`pnpm test:docker:all` は共有ライブテストイメージを 1 つ事前ビルドし、OpenClaw を npm tarball として一度パックし、2 つの共有 `scripts/e2e/Dockerfile` イメージをビルドします。 +`pnpm test:docker:all` は、1 つの共有 live-test イメージを事前ビルドし、OpenClaw を npm tarball として一度パックし、2 つの共有 `scripts/e2e/Dockerfile` イメージをビルドします。 -- installer/update/plugin-dependency レーン用の最小 Node/Git ランナー。 -- 通常の機能レーン用に、同じ tarball を `/app` にインストールする機能イメージ。 +- installer/update/plugin-dependency レーン用の素の Node/Git runner。 +- 通常の機能レーン用に、同じ tarball を `/app` にインストールする functional イメージ。 -Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーロジックは `scripts/lib/docker-e2e-plan.mjs` にあり、ランナーは選択されたプランのみを実行します。スケジューラーは `OPENCLAW_DOCKER_E2E_BARE_IMAGE` と `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` を使用してレーンごとにイメージを選択し、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` でレーンを実行します。 +Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーロジックは `scripts/lib/docker-e2e-plan.mjs` にあり、ランナーは選択されたプランのみを実行します。スケジューラーは `OPENCLAW_DOCKER_E2E_BARE_IMAGE` と `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` でレーンごとにイメージを選択し、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` でレーンを実行します。 ### 調整項目 -| 変数 | デフォルト | 目的 | -| -------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 通常レーン用のメインプールのスロット数。 | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | provider-sensitive tail-pool のスロット数。 | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | provider がスロットリングしないようにする同時ライブレーン上限。 | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 同時 npm install レーン上限。 | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 同時 multi-service レーン上限。 | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Docker daemon の create storm を避けるためのレーン開始間隔。間隔なしにするには `0` を設定。 | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | レーンごとのフォールバックタイムアウト（120 分）。選択された live/tail レーンはより厳しい上限を使用します。 | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` はレーンを実行せずにスケジューラープランを出力します。 | -| `OPENCLAW_DOCKER_ALL_LANES` | unset | カンマ区切りの正確なレーンリスト。cleanup smoke をスキップし、agent が 1 つの失敗レーンを再現できるようにします。 | +| 変数 | 既定値 | 目的 | +| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 通常レーン用のメインプールスロット数。 | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | provider-sensitive tail-pool スロット数。 | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | provider がスロットリングしないようにする同時 live レーン上限。 | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 同時 npm install レーン上限。 | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 同時 multi-service レーン上限。 | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Docker daemon create storm を避けるためのレーン開始間隔。stagger なしにするには `0` を設定。 | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | レーンごとのフォールバックタイムアウト（120 分）。選択された live/tail レーンはより厳しい上限を使用します。 | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | 未設定 | `1` はレーンを実行せずにスケジューラープランを出力します。 | +| `OPENCLAW_DOCKER_ALL_LANES` | 未設定 | カンマ区切りの正確なレーンリスト。agents が 1 つの失敗レーンを再現できるよう cleanup smoke をスキップします。 | -有効上限より重いレーンでも、空のプールから開始でき、その後容量を解放するまで単独で実行されます。ローカル集約は Docker を preflight し、古い OpenClaw E2E コンテナを削除し、アクティブレーン状態を出力し、最長優先の順序付けのためにレーンタイミングを永続化し、デフォルトでは最初の失敗後に新しいプール済みレーンのスケジュールを停止します。 +有効な上限より重いレーンでも、空のプールからなら開始でき、その後は容量を解放するまで単独で実行されます。ローカル集約は Docker を事前チェックし、古い OpenClaw E2E コンテナを削除し、アクティブなレーンの状態を出力し、最長優先の順序付けのためにレーンのタイミングを永続化し、既定では最初の失敗後に新しいプール済みレーンのスケジュールを停止します。 -### 再利用可能な live/E2E ワークフロー +### 再利用可能なライブ/E2Eワークフロー -再利用可能な live/E2E ワークフローは、必要な package、image kind、live image、lane、credential カバレッジを `scripts/test-docker-all.mjs --plan-json` に問い合わせます。その後 `scripts/docker-e2e.mjs` がそのプランを GitHub outputs とサマリーに変換します。`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw をパックするか、現在の実行の package artifact をダウンロードするか、`package_artifact_run_id` から package artifact をダウンロードします。tarball inventory を検証し、プランが package-installed レーンを必要とする場合は Blacksmith の Docker layer cache を通じて package-digest-tagged bare/functional GHCR Docker E2E イメージをビルドしてプッシュし、再ビルドの代わりに、指定された `docker_e2e_bare_image`/`docker_e2e_functional_image` 入力または既存の package-digest イメージを再利用します。Docker イメージの pull は、1 試行あたり 180 秒の範囲限定タイムアウトで再試行されるため、停止した registry/cache stream が CI クリティカルパスの大半を消費する代わりに、素早く再試行されます。 +再利用可能なライブ/E2Eワークフローは、どのパッケージ、イメージ種別、ライブイメージ、レーン、認証情報カバレッジが必要かを `scripts/test-docker-all.mjs --plan-json` に問い合わせます。その後、`scripts/docker-e2e.mjs` がその計画を GitHub の出力とサマリーに変換します。これは、`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw をパッケージ化するか、現在の実行のパッケージアーティファクトをダウンロードするか、`package_artifact_run_id` からパッケージアーティファクトをダウンロードします。さらに、tarball のインベントリを検証し、計画がパッケージインストール済みレーンを必要とする場合は Blacksmith の Docker レイヤーキャッシュを通じてパッケージダイジェスト付きタグの bare/functional GHCR Docker E2E イメージをビルドしてプッシュし、再ビルドの代わりに指定された `docker_e2e_bare_image`/`docker_e2e_functional_image` 入力または既存のパッケージダイジェストイメージを再利用します。Docker イメージの pull は、試行ごとに上限付きの 180 秒タイムアウトで再試行されるため、停止した registry/cache ストリームが CI のクリティカルパスの大半を消費する代わりにすばやく再試行されます。 -### リリースパスチャンク +### リリースパスのチャンク -リリース Docker カバレッジは、`OPENCLAW_SKIP_DOCKER_BUILD=1` を指定した小さなチャンク化ジョブを実行するため、各チャンクは必要な image kind だけを pull し、同じ重み付きスケジューラーを通じて複数のレーンを実行します。 +リリース Docker カバレッジは、`OPENCLAW_SKIP_DOCKER_BUILD=1` を使ってより小さなチャンク化されたジョブを実行するため、各チャンクは必要なイメージ種別だけを pull し、同じ重み付きスケジューラを通じて複数のレーンを実行します。 - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | bundled-channels` -現在のリリース Docker チャンクは、`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a` から `plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b`、および `bundled-channels-contracts` です。集約 `bundled-channels` チャンクは手動のワンショット再実行用に引き続き利用でき、`plugins-runtime-core`、`plugins-runtime`、および `plugins-integrations` は集約 plugin/runtime エイリアスのままです。`install-e2e` レーンエイリアスは、両方のプロバイダーインストーラーレーン向けの集約手動再実行エイリアスのままです。`bundled-channels` チャンクは、直列のオールインワン `bundled-channel-deps` レーンではなく、分割された `bundled-channel-*` と `bundled-channel-update-*` レーンを実行します。 +現在のリリース Docker チャンクは、`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a` から `plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b`、`bundled-channels-contracts` です。集約 `bundled-channels` チャンクは手動の単発再実行用として引き続き利用でき、`plugins-runtime-core`、`plugins-runtime`、`plugins-integrations` も集約 Plugin/runtime エイリアスとして残ります。`install-e2e` レーンエイリアスは、両方のプロバイダーインストーラーレーン向けの集約手動再実行エイリアスとして残ります。`bundled-channels` チャンクは、直列の一体型 `bundled-channel-deps` レーンではなく、分割された `bundled-channel-*` および `bundled-channel-update-*` レーンを実行します。 -OpenWebUI は、完全なリリースパスカバレッジが要求する場合に `plugins-runtime-services` に組み込まれ、OpenWebUI のみのディスパッチに限ってスタンドアロンの `openwebui` チャンクを保持します。バンドルチャンネル更新レーンは、一時的な npm ネットワーク障害に対して 1 回再試行します。 +OpenWebUI は、完全なリリースパスカバレッジが要求する場合は `plugins-runtime-services` に組み込まれ、OpenWebUI のみの dispatch 向けにだけ単独の `openwebui` チャンクを保持します。バンドル済みチャンネル更新レーンは、一時的な npm ネットワーク障害に対して 1 回再試行します。 -各チャンクは、レーンログ、タイミング、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、低速レーンテーブル、およびレーンごとの再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。ワークフローの `docker_lanes` 入力は、チャンクジョブの代わりに、準備済みイメージに対して選択されたレーンを実行します。これにより、失敗したレーンのデバッグを 1 つの対象 Docker ジョブに限定し、その実行用のパッケージアーティファクトを準備、ダウンロード、または再利用できます。選択されたレーンがライブ Docker レーンの場合、対象ジョブはその再実行用にライブテストイメージをローカルでビルドします。生成されるレーンごとの GitHub 再実行コマンドには、それらの値が存在する場合、`package_artifact_run_id`、`package_artifact_name`、および準備済みイメージ入力が含まれるため、失敗したレーンは失敗した実行から正確なパッケージとイメージを再利用できます。 +各チャンクは、レーンログ、タイミング、`summary.json`、`failures.json`、フェーズタイミング、スケジューラ計画 JSON、低速レーンの表、レーンごとの再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。ワークフローの `docker_lanes` 入力は、チャンクジョブの代わりに選択されたレーンを準備済みイメージに対して実行します。これにより、失敗したレーンのデバッグは対象を絞った 1 つの Docker ジョブに限定され、その実行用のパッケージアーティファクトを準備、ダウンロード、または再利用します。選択されたレーンがライブ Docker レーンの場合、対象ジョブはその再実行のためにライブテストイメージをローカルでビルドします。生成されるレーンごとの GitHub 再実行コマンドには、値が存在する場合に `package_artifact_run_id`、`package_artifact_name`、準備済みイメージ入力が含まれるため、失敗したレーンは失敗した実行とまったく同じパッケージとイメージを再利用できます。 ```bash -pnpm test:docker:rerun # Docker artifacts and print combined/per-lane targeted rerun commands +pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # slow-lane and phase critical-path summaries ``` -スケジュールされたライブ/E2E ワークフローは、完全なリリースパス Docker スイートを毎日実行します。 +スケジュールされたライブ/E2Eワークフローは、完全なリリースパス Docker スイートを毎日実行します。 ## Plugin プレリリース -`Plugin Prerelease` は、より高コストな製品/パッケージカバレッジであるため、`Full Release Validation` または明示的なオペレーターによってディスパッチされる別ワークフローです。通常のプルリクエスト、`main` プッシュ、および単独の手動 CI ディスパッチでは、このスイートはオフのままです。これは、バンドル plugin テストを 8 つの拡張ワーカーに分散します。これらの拡張シャードジョブは、グループごとに 1 つの Vitest ワーカーとより大きな Node ヒープを使い、一度に最大 2 つの plugin 設定グループを実行するため、インポート負荷の高い plugin バッチが余分な CI ジョブを作成しません。 +`Plugin Prerelease` はより高コストな製品/パッケージカバレッジであるため、`Full Release Validation` または明示的なオペレーターによって dispatch される別ワークフローです。通常の pull request、`main` push、単独の手動 CI dispatch では、このスイートは無効のままです。これは、バンドル済み Plugin テストを 8 つの extension ワーカーに分散します。これらの extension shard ジョブは、グループごとに 1 つの Vitest ワーカーとより大きな Node heap を使い、同時に最大 2 つの Plugin config グループを実行するため、import の重い Plugin バッチが追加の CI ジョブを作成しません。リリース専用の Docker プレリリースパスは、1 から 3 分のジョブのために多数の runner を予約しないよう、対象 Docker レーンを小さなグループでバッチ化します。 -## QA ラボ +## QA Lab -QA ラボには、メインのスマートスコープワークフローの外に専用の CI レーンがあります。 +QA Lab には、メインのスマートスコープワークフローの外に専用の CI レーンがあります。 -- `Parity gate` ワークフローは、一致する PR 変更と手動ディスパッチで実行されます。プライベート QA ランタイムをビルドし、モック GPT-5.5 と Opus 4.6 のエージェントパックを比較します。 -- `QA-Lab - All Lanes` ワークフローは、`main` で毎晩、および手動ディスパッチで実行されます。モックパリティゲート、ライブ Matrix レーン、ライブ Telegram レーンと Discord レーンを並列ジョブとしてファンアウトします。ライブジョブは `qa-live-shared` 環境を使用し、Telegram/Discord は Convex リースを使用します。 +- `Parity gate` ワークフローは、一致する PR 変更と手動 dispatch で実行されます。プライベート QA runtime をビルドし、mock GPT-5.5 と Opus 4.6 の agentic pack を比較します。 +- `QA-Lab - All Lanes` ワークフローは、`main` で毎晩および手動 dispatch で実行されます。mock parity gate、live Matrix レーン、live Telegram および Discord レーンを並列ジョブとしてファンアウトします。live ジョブは `qa-live-shared` environment を使用し、Telegram/Discord は Convex lease を使用します。 -リリースチェックは、決定論的モックプロバイダーとモック認定モデル（`mock-openai/gpt-5.5` と `mock-openai/gpt-5.5-alt`）で Matrix と Telegram のライブトランスポートレーンを実行するため、チャンネル契約はライブモデルのレイテンシと通常の provider-plugin 起動から分離されます。ライブトランスポート Gateway はメモリ検索を無効にします。QA パリティがメモリ動作を別途カバーするためです。プロバイダー接続性は、別のライブモデル、ネイティブプロバイダー、および Docker プロバイダースイートでカバーされます。 +リリースチェックは、決定的な mock provider と mock-qualified model（`mock-openai/gpt-5.5` および `mock-openai/gpt-5.5-alt`）を使って Matrix と Telegram の live transport レーンを実行するため、チャンネル契約は live model のレイテンシや通常の provider-plugin startup から分離されます。live transport gateway は memory search を無効化します。QA parity が memory behavior を別途カバーしているためです。provider connectivity は、別個の live model、native provider、Docker provider の各スイートでカバーされます。 -Matrix は、スケジュールゲートとリリースゲートで `--profile fast` を使用し、チェックアウトされた CLI が対応している場合にのみ `--fail-fast` を追加します。CLI のデフォルトと手動ワークフロー入力は `all` のままです。手動の `matrix_profile=all` ディスパッチは、常に完全な Matrix カバレッジを `transport`、`media`、`e2ee-smoke`、`e2ee-deep`、および `e2ee-cli` ジョブにシャードします。 +Matrix はスケジュールおよびリリースゲートで `--profile fast` を使用し、チェックアウトされた CLI が対応している場合にのみ `--fail-fast` を追加します。CLI の既定値と手動ワークフロー入力は `all` のままです。手動の `matrix_profile=all` dispatch は、常に完全な Matrix カバレッジを `transport`、`media`、`e2ee-smoke`、`e2ee-deep`、`e2ee-cli` ジョブに shard します。 -`OpenClaw Release Checks` は、リリース承認前にリリースクリティカルな QA ラボレーンも実行します。その QA パリティゲートは、候補パックとベースラインパックを並列レーンジョブとして実行し、その後、最終的なパリティ比較用に小さなレポートジョブへ両方のアーティファクトをダウンロードします。 +`OpenClaw Release Checks` は、リリース承認前にリリースで重要な QA Lab レーンも実行します。その QA parity gate は候補 pack と baseline pack を並列レーンジョブとして実行し、その後、最終的な parity 比較のために小さなレポートジョブへ両方のアーティファクトをダウンロードします。 -変更が実際に QA ランタイム、モデルパックパリティ、またはパリティワークフローが所有するサーフェスに触れる場合を除き、PR ランディングパスを `Parity gate` の背後に置かないでください。通常のチャンネル、設定、ドキュメント、または単体テスト修正では、これを任意のシグナルとして扱い、スコープ付き CI/チェックの証拠に従ってください。 +変更が実際に QA runtime、model-pack parity、または parity ワークフローが所有する surface に触れる場合を除き、PR の landing path を `Parity gate` の背後に置かないでください。通常のチャンネル、config、docs、または unit-test 修正では、これは任意のシグナルとして扱い、スコープされた CI/check evidence に従ってください。 ## CodeQL -`CodeQL` ワークフローは、完全なリポジトリスイープではなく、意図的に絞り込まれた初回パスのセキュリティスキャナーです。毎日、手動、および非ドラフトのプルリクエストガード実行では、Actions ワークフローコードに加え、最もリスクの高い JavaScript/TypeScript サーフェスを、high/critical の `security-severity` にフィルタリングされた高信頼度のセキュリティクエリでスキャンします。 +`CodeQL` ワークフローは意図的に狭い初回パスのセキュリティスキャナーであり、リポジトリ全体の sweep ではありません。毎日、手動、非 draft pull request の guard 実行では、Actions workflow code に加え、最もリスクの高い JavaScript/TypeScript surface を、高/critical の `security-severity` に絞った高信頼度のセキュリティクエリでスキャンします。 -プルリクエストガードは軽量に保たれます。`.github/actions`、`.github/codeql`、`.github/workflows`、`packages`、または `src` 配下の変更に対してのみ開始され、スケジュールされたワークフローと同じ高信頼度セキュリティマトリクスを実行します。Android と macOS の CodeQL は PR デフォルトから外れています。 +pull request guard は軽量に保たれています。`.github/actions`、`.github/codeql`、`.github/workflows`、`packages`、または `src` 配下の変更でのみ開始され、スケジュールワークフローと同じ高信頼度セキュリティマトリクスを実行します。Android と macOS の CodeQL は PR 既定値には含まれません。 ### セキュリティカテゴリ -| カテゴリ | サーフェス | +| カテゴリ | Surface | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | 認証、シークレット、サンドボックス、Cron、および Gateway ベースライン | -| `/codeql-security-high/channel-runtime-boundary` | コアチャンネル実装契約に加え、チャンネル plugin ランタイム、Gateway、Plugin SDK、シークレット、監査タッチポイント | -| `/codeql-security-high/network-ssrf-boundary` | コア SSRF、IP 解析、ネットワークガード、web-fetch、および Plugin SDK SSRF ポリシーサーフェス | -| `/codeql-security-high/mcp-process-tool-boundary` | MCP サーバー、プロセス実行ヘルパー、アウトバウンド配信、およびエージェントツール実行ゲート | -| `/codeql-security-high/plugin-trust-boundary` | Plugin インストール、ローダー、マニフェスト、レジストリ、runtime-dependency ステージング、source-loading、および Plugin SDK パッケージ契約の信頼サーフェス | +| `/codeql-security-high/core-auth-secrets` | Auth、secrets、sandbox、cron、gateway baseline | +| `/codeql-security-high/channel-runtime-boundary` | Core channel implementation contracts に加え、channel Plugin runtime、gateway、Plugin SDK、secrets、audit touchpoints | +| `/codeql-security-high/network-ssrf-boundary` | Core SSRF、IP parsing、network guard、web-fetch、Plugin SDK SSRF policy surfaces | +| `/codeql-security-high/mcp-process-tool-boundary` | MCP servers、process execution helpers、outbound delivery、agent tool-execution gates | +| `/codeql-security-high/plugin-trust-boundary` | Plugin install、loader、manifest、registry、runtime-dependency staging、source-loading、Plugin SDK package contract trust surfaces | -### プラットフォーム固有のセキュリティシャード +### プラットフォーム固有のセキュリティ shard -- `CodeQL Android Critical Security` — スケジュールされた Android セキュリティシャード。ワークフロー健全性が許容する最小の Blacksmith Linux ランナー上で、CodeQL 用に Android アプリを手動でビルドします。`/codeql-critical-security/android` 配下にアップロードします。 -- `CodeQL macOS Critical Security` — 週次/手動の macOS セキュリティシャード。Blacksmith macOS 上で CodeQL 用に macOS アプリを手動でビルドし、依存関係ビルド結果をアップロード済み SARIF からフィルタリングし、`/codeql-critical-security/macos` 配下にアップロードします。クリーンな場合でも macOS ビルドがランタイムを支配するため、日次デフォルトの外に保持されています。 +- `CodeQL Android Critical Security` — スケジュールされた Android セキュリティ shard。workflow sanity が受け入れる最小の Blacksmith Linux runner 上で、CodeQL 用に Android app を手動でビルドします。`/codeql-critical-security/android` 配下にアップロードします。 +- `CodeQL macOS Critical Security` — 週次/手動の macOS セキュリティ shard。Blacksmith macOS 上で CodeQL 用に macOS app を手動でビルドし、アップロードされる SARIF から依存関係のビルド結果を除外し、`/codeql-critical-security/macos` 配下にアップロードします。クリーンな場合でも macOS build が runtime を支配するため、日次の既定値の外に置かれています。 -### 重大品質カテゴリ +### Critical Quality カテゴリ -`CodeQL Critical Quality` は、対応する非セキュリティシャードです。これは、より小さな Blacksmith Linux ランナー上で、狭い高価値サーフェスに対し、エラー重大度の非セキュリティ JavaScript/TypeScript 品質クエリのみを実行します。そのプルリクエストガードは、スケジュールされたプロファイルよりも意図的に小さくなっています。非ドラフト PR では、エージェントコマンド/モデル/ツール実行および返信ディスパッチコード、設定スキーマ/マイグレーション/IO コード、認証/シークレット/サンドボックス/セキュリティコード、コアチャンネルおよびバンドルチャンネル plugin ランタイム、Gateway protocol/server-method、メモリランタイム/SDK グルー、MCP/プロセス/アウトバウンド配信、プロバイダーランタイム/モデルカタログ、セッション診断/配信キュー、plugin ローダー、Plugin SDK/package-contract、または Plugin SDK 返信ランタイムの変更に対して、一致する `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract`、および `plugin-sdk-reply-runtime` シャードのみを実行します。CodeQL 設定と品質ワークフローの変更では、12 個すべての PR 品質シャードを実行します。 +`CodeQL Critical Quality` は対応する非セキュリティ shard です。これは、より小さな Blacksmith Linux runner 上で、狭い高価値 surface に対して error-severity の非セキュリティ JavaScript/TypeScript quality query だけを実行します。その pull request guard はスケジュールプロファイルより意図的に小さくなっています。非 draft PR は、agent command/model/tool execution と reply dispatch code、config schema/migration/IO code、auth/secrets/sandbox/security code、core channel とバンドル済み channel Plugin runtime、gateway protocol/server-method、memory runtime/SDK glue、MCP/process/outbound delivery、provider runtime/model catalog、session diagnostics/delivery queues、Plugin loader、Plugin SDK/package-contract、または Plugin SDK reply runtime の変更に対して、対応する `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract`、`plugin-sdk-reply-runtime` shard のみを実行します。CodeQL config と quality workflow の変更は、12 個すべての PR quality shard を実行します。 -手動ディスパッチは以下を受け付けます。 +手動 dispatch は次を受け付けます。 ``` profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -狭いプロファイルは、1 つの品質シャードを単独で実行するための教育/反復フックです。 +狭いプロファイルは、1 つの quality shard を単独で実行するための教育/反復用フックです。 | カテゴリ | サーフェス | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | 認証、シークレット、サンドボックス、Cron、Gateway のセキュリティ境界コード | -| `/codeql-critical-quality/config-boundary` | 設定スキーマ、移行、正規化、IO 契約 | -| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway プロトコルスキーマとサーバーメソッド契約 | -| `/codeql-critical-quality/channel-runtime-boundary` | コアチャネルとバンドルされたチャネル Plugin の実装契約 | -| `/codeql-critical-quality/agent-runtime-boundary` | コマンド実行、モデル/プロバイダーのディスパッチ、自動返信ディスパッチとキュー、ACP コントロールプレーンランタイム契約 | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP サーバーとツールブリッジ、プロセス監視ヘルパー、送信配信契約 | +| `/codeql-critical-quality/core-auth-secrets` | 認証、シークレット、サンドボックス、cron、Gateway のセキュリティ境界コード | +| `/codeql-critical-quality/config-boundary` | 設定スキーマ、移行、正規化、IO コントラクト | +| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway プロトコルスキーマとサーバーメソッドコントラクト | +| `/codeql-critical-quality/channel-runtime-boundary` | コアチャネルとバンドル済みチャネル Plugin 実装コントラクト | +| `/codeql-critical-quality/agent-runtime-boundary` | コマンド実行、モデル/プロバイダーディスパッチ、自動返信ディスパッチとキュー、ACP コントロールプレーンランタイムコントラクト | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP サーバーとツールブリッジ、プロセス監視ヘルパー、アウトバウンド配信コントラクト | | `/codeql-critical-quality/memory-runtime-boundary` | メモリホスト SDK、メモリランタイムファサード、メモリ Plugin SDK エイリアス、メモリランタイム有効化グルー、メモリ doctor コマンド | -| `/codeql-critical-quality/session-diagnostics-boundary` | 返信キュー内部、セッション配信キュー、送信セッションのバインディング/配信ヘルパー、診断イベント/ログバンドルサーフェス、セッション doctor CLI 契約 | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin SDK の受信返信ディスパッチ、返信ペイロード/チャンク化/ランタイムヘルパー、チャネル返信オプション、配信キュー、セッション/スレッドのバインディングヘルパー | -| `/codeql-critical-quality/provider-runtime-boundary` | モデルカタログ正規化、プロバイダー認証と検出、プロバイダーランタイム登録、プロバイダーのデフォルト/カタログ、web/search/fetch/embedding レジストリ | -| `/codeql-critical-quality/ui-control-plane` | コントロール UI ブートストラップ、ローカル永続化、Gateway コントロールフロー、タスクコントロールプレーンランタイム契約 | -| `/codeql-critical-quality/web-media-runtime-boundary` | コア web fetch/search、メディア IO、メディア理解、画像生成、メディア生成ランタイム契約 | -| `/codeql-critical-quality/plugin-boundary` | ローダー、レジストリ、公開サーフェス、Plugin SDK エントリポイント契約 | -| `/codeql-critical-quality/plugin-sdk-package-contract` | 公開パッケージ側の Plugin SDK ソースと Plugin パッケージ契約ヘルパー | +| `/codeql-critical-quality/session-diagnostics-boundary` | 返信キュー内部、セッション配信キュー、アウトバウンドセッションバインディング/配信ヘルパー、診断イベント/ログバンドルサーフェス、セッション doctor CLI コントラクト | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin SDK インバウンド返信ディスパッチ、返信ペイロード/チャンク化/ランタイムヘルパー、チャネル返信オプション、配信キュー、セッション/スレッドバインディングヘルパー | +| `/codeql-critical-quality/provider-runtime-boundary` | モデルカタログ正規化、プロバイダー認証と検出、プロバイダーランタイム登録、プロバイダーデフォルト/カタログ、web/search/fetch/embedding レジストリ | +| `/codeql-critical-quality/ui-control-plane` | コントロール UI ブートストラップ、ローカル永続化、Gateway コントロールフロー、タスクコントロールプレーンランタイムコントラクト | +| `/codeql-critical-quality/web-media-runtime-boundary` | コア web fetch/search、メディア IO、メディア理解、画像生成、メディア生成ランタイムコントラクト | +| `/codeql-critical-quality/plugin-boundary` | ローダー、レジストリ、公開サーフェス、Plugin SDK エントリポイントコントラクト | +| `/codeql-critical-quality/plugin-sdk-package-contract` | 公開パッケージ側の Plugin SDK ソースと Plugin パッケージコントラクトヘルパー | -品質はセキュリティとは分離されたままにすることで、品質の検出結果をスケジュール、測定、無効化、拡張してもセキュリティシグナルを不明瞭にしない。Swift、Python、バンドル Plugin の CodeQL 拡張は、狭いプロファイルのランタイムとシグナルが安定してから、スコープ指定またはシャード化されたフォローアップ作業としてのみ戻すべきである。 +品質をセキュリティから分離しておくことで、品質の検出結果を、セキュリティシグナルを不明瞭にせずにスケジュール、測定、無効化、拡張できます。Swift、Python、バンドル済み Plugin の CodeQL 拡張は、狭いプロファイルのランタイムとシグナルが安定してから、スコープ化またはシャーディングされたフォローアップ作業としてのみ追加し直すべきです。 ## メンテナンスワークフロー ### Docs Agent -`Docs Agent` ワークフローは、最近取り込まれた変更に既存ドキュメントを合わせ続けるための、イベント駆動型 Codex メンテナンスレーンである。純粋なスケジュールはない。`main` への bot 以外の push CI 実行が成功するとトリガーでき、手動ディスパッチでも直接実行できる。ワークフロー実行による呼び出しは、`main` が先に進んでいる場合、またはスキップされていない別の Docs Agent 実行が過去 1 時間以内に作成されている場合はスキップする。実行時には、スキップされていない直前の Docs Agent ソース SHA から現在の `main` までのコミット範囲をレビューするため、1 時間に 1 回の実行で、前回の docs パス以降に蓄積されたすべての main 変更をカバーできる。 +`Docs Agent` ワークフローは、最近取り込まれた変更と既存ドキュメントの整合性を保つための、イベント駆動の Codex メンテナンスレーンです。純粋なスケジュールはありません。`main` への bot 以外の push CI 実行が成功するとトリガーされ、手動ディスパッチでも直接実行できます。ワークフロー実行による呼び出しは、`main` が先に進んでいる場合、またはスキップされていない別の Docs Agent 実行が直近 1 時間以内に作成されている場合はスキップされます。実行時には、前回スキップされなかった Docs Agent ソース SHA から現在の `main` までのコミット範囲をレビューするため、1 時間ごとの 1 回の実行で、前回のドキュメント確認以降に蓄積されたすべての main 変更をカバーできます。 ### Test Performance Agent -`Test Performance Agent` ワークフローは、遅いテスト向けのイベント駆動型 Codex メンテナンスレーンである。純粋なスケジュールはない。`main` への bot 以外の push CI 実行が成功するとトリガーできるが、別のワークフロー実行による呼び出しがその UTC 日にすでに実行済みまたは実行中の場合はスキップする。手動ディスパッチは、その日次アクティビティゲートを迂回する。このレーンは、フルスイートのグループ化された Vitest パフォーマンスレポートを作成し、Codex には広範なリファクタリングではなく、カバレッジを維持する小さなテストパフォーマンス修正だけを行わせ、その後フルスイートレポートを再実行して、合格ベースラインテスト数を減らす変更を拒否する。ベースラインに失敗テストがある場合、Codex は明らかな失敗だけを修正でき、エージェント後のフルスイートレポートは、何かがコミットされる前に合格しなければならない。bot push が取り込まれる前に `main` が進んだ場合、このレーンは検証済みパッチをリベースし、`pnpm check:changed` を再実行して push を再試行する。競合する古いパッチはスキップされる。Codex アクションが docs agent と同じ drop-sudo の安全姿勢を維持できるよう、GitHub ホストの Ubuntu を使用する。 +`Test Performance Agent` ワークフローは、遅いテスト向けのイベント駆動の Codex メンテナンスレーンです。純粋なスケジュールはありません。`main` への bot 以外の push CI 実行が成功するとトリガーされますが、その UTC 日に別のワークフロー実行呼び出しがすでに実行済みまたは実行中の場合はスキップされます。手動ディスパッチは、その日次アクティビティゲートを迂回します。このレーンはフルスイートのグループ化された Vitest パフォーマンスレポートを作成し、Codex には広範なリファクタリングではなく、カバレッジを維持する小さなテストパフォーマンス修正だけを行わせます。その後、フルスイートレポートを再実行し、合格ベースラインテスト数を減らす変更を拒否します。ベースラインに失敗テストがある場合、Codex は明白な失敗のみ修正でき、エージェント後のフルスイートレポートはコミット前に合格しなければなりません。bot push が取り込まれる前に `main` が進んだ場合、このレーンは検証済みパッチをリベースし、`pnpm check:changed` を再実行して、push を再試行します。競合する古いパッチはスキップされます。Docs Agent と同じ drop-sudo 安全姿勢を Codex アクションが維持できるよう、GitHub ホストの Ubuntu を使用します。 ### マージ後の重複 PR -`Duplicate PRs After Merge` ワークフローは、取り込み後の重複クリーンアップ向けの手動メンテナーワークフローである。デフォルトは dry-run で、`apply=true` の場合にのみ明示的に列挙された PR をクローズする。GitHub を変更する前に、取り込まれた PR がマージ済みであり、各重複が共有の参照 issue または重複する変更ハンクを持つことを検証する。 +`Duplicate PRs After Merge` ワークフローは、取り込み後の重複クリーンアップ用の手動メンテナーワークフローです。デフォルトは dry-run で、`apply=true` の場合に明示的に列挙された PR のみを閉じます。GitHub を変更する前に、取り込まれた PR がマージ済みであり、各重複に共有された参照 Issue または重複する変更 hunk があることを検証します。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -394,25 +406,25 @@ gh workflow run duplicate-after-merge.yml \ ## ローカルチェックゲートと変更ルーティング -ローカルの変更レーンロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行される。このローカルチェックゲートは、広範な CI プラットフォームスコープよりもアーキテクチャ境界について厳格である。 +ローカル変更レーンロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。このローカルチェックゲートは、広範な CI プラットフォームスコープよりもアーキテクチャ境界について厳格です。 -- コア本番変更は、コア本番とコアテストの typecheck に加えてコア lint/guard を実行する。 -- コアのテストのみの変更は、コアテストの typecheck に加えてコア lint のみを実行する。 -- extension 本番変更は、extension 本番と extension テストの typecheck に加えて extension lint を実行する。 -- extension のテストのみの変更は、extension テストの typecheck に加えて extension lint を実行する。 -- 公開 Plugin SDK または Plugin 契約の変更は、extension がそれらのコア契約に依存しているため、extension typecheck へ拡張される（Vitest extension sweep は明示的なテスト作業のまま）。 -- リリースメタデータのみのバージョン更新は、対象を絞ったバージョン/設定/ルート依存関係チェックを実行する。 -- 不明なルート/設定変更は、安全側に倒してすべてのチェックレーンへ送る。 +- コア本番変更は、コア本番とコアテストの型チェックに加えてコア lint/guard を実行します。 +- コアのテストのみの変更は、コアテストの型チェックに加えてコア lint のみを実行します。 +- 拡張機能本番変更は、拡張機能本番と拡張機能テストの型チェックに加えて拡張機能 lint を実行します。 +- 拡張機能のテストのみの変更は、拡張機能テストの型チェックに加えて拡張機能 lint を実行します。 +- 公開 Plugin SDK または Plugin コントラクトの変更は、拡張機能がそれらのコアコントラクトに依存するため、拡張機能の型チェックまで拡張されます（Vitest 拡張機能スイープは明示的なテスト作業のままです）。 +- リリースメタデータのみのバージョン更新は、対象を絞ったバージョン/設定/ルート依存関係チェックを実行します。 +- 不明なルート/設定変更は、安全側に倒してすべてのチェックレーンを実行します。 -ローカルの変更テストルーティングは `scripts/test-projects.test-support.mjs` にあり、意図的に `check:changed` より軽量である。直接のテスト編集はそのテスト自体を実行し、ソース編集は明示的なマッピング、次に兄弟テストとインポートグラフ依存先を優先する。共有グループルーム配信設定は明示的なマッピングの一つである。グループの可視返信設定、ソース返信配信モード、またはメッセージツールのシステムプロンプトへの変更は、コア返信テストに加えて Discord と Slack の配信リグレッションを通るため、共有デフォルト変更は最初の PR push の前に失敗する。変更がハーネス全体に及ぶほど広範で、安価なマッピング済みセットが信頼できるプロキシではない場合にのみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用する。 +ローカルの変更テストルーティングは `scripts/test-projects.test-support.mjs` にあり、意図的に `check:changed` より低コストです。直接のテスト編集はそれ自体を実行し、ソース編集は明示的なマッピングを優先し、その後に sibling テストと import-graph 依存先を使います。共有グループルーム配信設定は、明示的なマッピングの 1 つです。グループの可視返信設定、ソース返信配信モード、またはメッセージツールシステムプロンプトへの変更は、コア返信テストに加えて Discord と Slack の配信回帰を通るため、共有デフォルトの変更は最初の PR push の前に失敗します。安価なマッピング済みセットが信頼できるプロキシにならないほど変更がハーネス全体に及ぶ場合のみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 ## Testbox 検証 -Testbox はリポジトリルートから実行し、広範な証明には新しくウォームアップした box を優先する。再利用された、期限切れになった、または予想外に大きな同期を報告したばかりの box で遅いゲートに時間を使う前に、まず box 内で `pnpm testbox:sanity` を実行する。 +Testbox はリポジトリルートから実行し、広範な証明には新しく warmed した box を優先してください。再利用された、期限切れになった、または予想外に大きな同期を報告したばかりの box で遅いゲートに時間を使う前に、まず box 内で `pnpm testbox:sanity` を実行してください。 -sanity check は、`pnpm-lock.yaml` などの必須ルートファイルが消えている場合、または `git status --short` が少なくとも 200 個の追跡済み削除を示す場合に早期失敗する。これは通常、リモート同期状態が PR の信頼できるコピーではないことを意味する。製品テスト失敗をデバッグするのではなく、その box を停止して新しいものをウォームアップする。意図的な大量削除 PR では、その sanity run に `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` を設定する。 +sanity check は、`pnpm-lock.yaml` などの必須ルートファイルが消えている場合、または `git status --short` が 200 件以上の tracked deletion を示す場合に即座に失敗します。これは通常、リモート同期状態が PR の信頼できるコピーではないことを意味します。製品テストの失敗をデバッグするのではなく、その box を停止して新しいものを warm してください。意図的な大規模削除 PR の場合は、その sanity 実行に `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` を設定してください。 -`pnpm testbox:run` は、sync フェーズに 5 分を超えて留まり、同期後の出力がないローカル Blacksmith CLI 呼び出しも終了する。その guard を無効化するには `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` を設定し、通常より大きなローカル diff にはより大きなミリ秒値を使用する。 +`pnpm testbox:run` は、同期後出力がないまま同期フェーズに 5 分を超えて留まるローカル Blacksmith CLI 呼び出しも終了します。その guard を無効化するには `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` を設定するか、通常より大きなローカル差分にはより大きいミリ秒値を使用してください。 ## 関連 diff --git a/docs/ja-JP/cli/models.md b/docs/ja-JP/cli/models.md index ffe75e59f..c0c7ba107 100644 --- a/docs/ja-JP/cli/models.md +++ b/docs/ja-JP/cli/models.md @@ -1,29 +1,29 @@ --- read_when: - - デフォルトモデルを変更したい、またはプロバイダーの認証ステータスを確認したい場合 + - デフォルトモデルを変更したい、またはプロバイダーの認証ステータスを確認したい - 利用可能なモデル/プロバイダーをスキャンし、認証プロファイルをデバッグしたい summary: '`openclaw models` の CLI リファレンス（status/list/set/scan、エイリアス、フォールバック、認証）' title: モデル x-i18n: - generated_at: "2026-04-30T05:05:30Z" + generated_at: "2026-05-01T05:00:28Z" model: gpt-5.5 provider: openai - source_hash: 95e2361989b583f7f52947dad1faaaba44dc6a5f58719cc2e83c13fce7c33adc + source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1 source_path: cli/models.md workflow: 16 --- # `openclaw models` -モデルの検出、スキャン、設定 (デフォルトモデル、フォールバック、認証プロファイル)。 +モデル検出、スキャン、設定（デフォルトモデル、フォールバック、認証プロファイル）。 関連: -- プロバイダー + モデル: [モデル](/ja-JP/providers/models) -- モデル選択の概念 + `/models` スラッシュコマンド: [モデルの概念](/ja-JP/concepts/models) -- プロバイダー認証のセットアップ: [はじめに](/ja-JP/start/getting-started) +- プロバイダーとモデル: [モデル](/ja-JP/providers/models) +- モデル選択の概念と `/models` スラッシュコマンド: [モデルの概念](/ja-JP/concepts/models) +- プロバイダー認証の設定: [はじめに](/ja-JP/start/getting-started) -## 一般的なコマンド +## 共通コマンド ```bash openclaw models status @@ -32,76 +32,80 @@ openclaw models set openclaw models scan ``` -`openclaw models status` は、解決済みのデフォルト/フォールバックと認証の概要を表示します。 -プロバイダー使用状況のスナップショットが利用できる場合、OAuth/APIキーのステータスセクションには -プロバイダー使用期間とクォータスナップショットが含まれます。 +`openclaw models status` は、解決済みのデフォルト/フォールバックに加えて認証の概要を表示します。 +プロバイダー使用状況のスナップショットが利用可能な場合、OAuth/APIキーのステータスセクションには +プロバイダーの使用期間とクォータのスナップショットが含まれます。 現在の使用期間プロバイダー: Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi、z.ai。使用状況の認証は、利用可能な場合はプロバイダー固有のフックから取得されます。 -それ以外の場合、OpenClaw は認証プロファイル、環境変数、または設定から一致する OAuth/APIキー -資格情報へフォールバックします。 -`--json` 出力では、`auth.providers` は環境変数/設定/ストアを考慮したプロバイダー +それ以外の場合、OpenClaw は認証プロファイル、環境、または設定内の一致する OAuth/APIキー +認証情報にフォールバックします。 +`--json` 出力では、`auth.providers` は環境/設定/ストアを認識するプロバイダー 概要であり、`auth.oauth` は認証ストアのプロファイル健全性のみです。 -各設定済みプロバイダープロファイルに対してライブ認証プローブを実行するには、`--probe` を追加します。 -プローブは実際のリクエストです (トークンを消費し、レート制限を引き起こす可能性があります)。 -設定済みエージェントのモデル/認証状態を調べるには、`--agent ` を使用します。省略した場合、 -コマンドは、設定されていれば `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` を使用し、それ以外の場合は +設定済みの各プロバイダープロファイルに対してライブ認証プローブを実行するには、`--probe` を追加します。 +プローブは実際のリクエストです（トークンを消費し、レート制限を発生させる可能性があります）。 +設定済みエージェントのモデル/認証状態を検査するには、`--agent ` を使用します。省略した場合、 +コマンドは `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` が設定されていればそれを使用し、そうでなければ 設定済みのデフォルトエージェントを使用します。 -プローブ行は、認証プロファイル、環境変数資格情報、または `models.json` から取得されることがあります。 +プローブ行は、認証プロファイル、環境認証情報、または `models.json` から取得される場合があります。 -注: +注記: - `models set ` は `provider/model` またはエイリアスを受け付けます。 - `models list` は読み取り専用です。設定、認証プロファイル、既存のカタログ 状態、プロバイダー所有のカタログ行を読み取りますが、 `models.json` は書き換えません。 -- `Auth` 列はプロバイダーレベルで読み取り専用です。これはローカルの - 認証プロファイルメタデータ、環境変数マーカー、設定済みプロバイダーキー、ローカルプロバイダー - マーカー、AWS Bedrock の環境変数/プロファイルマーカー、Plugin の合成認証メタデータから計算されます。 +- `Auth` 列はプロバイダーレベルで読み取り専用です。ローカルの + 認証プロファイルメタデータ、環境マーカー、設定済みプロバイダーキー、ローカルプロバイダー + マーカー、AWS Bedrock 環境/プロファイルマーカー、Plugin の合成認証メタデータから計算されます。 プロバイダーランタイムの読み込み、キーチェーンシークレットの読み取り、プロバイダー - API の呼び出し、モデル単位の正確な実行準備状況の証明は行いません。 + API の呼び出し、またはモデル単位の正確な実行準備状況の証明は行いません。 - `models list --all --provider ` は、そのプロバイダーでまだ認証していない場合でも、 - Plugin マニフェストまたはバンドルされたプロバイダーカタログメタデータからの、プロバイダー所有の静的カタログ - 行を含めることがあります。それらの行は、一致する認証が設定されるまで + Plugin マニフェストまたはバンドルされたプロバイダーカタログメタデータから、プロバイダー所有の静的カタログ + 行を含めることができます。それらの行は、一致する認証が設定されるまで 利用不可として表示されます。 -- 広範な `models list --all` は、プロバイダーランタイム補助フックを読み込まずに、 - マニフェストカタログ行をレジストリ行より優先してマージします。プロバイダーでフィルタリングされたマニフェスト - 高速パスは、`static` とマークされたプロバイダーのみを使用します。`refreshable` とマークされたプロバイダーは - レジストリ/キャッシュベースのままで、マニフェスト行を補助として追加します。一方、 +- `models list` は、プロバイダーカタログ + 検出が遅い間も制御プレーンの応答性を保ちます。デフォルトビューと設定済みビューは、短い待機後に設定済みまたは + 合成モデル行へフォールバックし、検出は + バックグラウンドで完了させます。正確な完全検出済みカタログが必要で、 + プロバイダー検出を待てる場合は `--all` を使用します。 +- 広範な `models list --all` は、プロバイダーランタイム補足フックを読み込まずに、マニフェストカタログ行をレジストリ行の上にマージします。 + プロバイダーで絞り込まれたマニフェスト高速パスは、`static` とマークされたプロバイダーのみを使用します。`refreshable` とマークされたプロバイダーは + レジストリ/キャッシュベースのままで、マニフェスト行を補足として追加します。一方、 `runtime` とマークされたプロバイダーはレジストリ/ランタイム検出のままです。 -- `models list` は、ネイティブのモデルメタデータとランタイム上限を区別して保持します。テーブル - 出力では、有効なランタイム上限がネイティブのコンテキストウィンドウと異なる場合、 - `Ctx` は `contextTokens/contextWindow` を表示します。プロバイダーがその上限を公開する場合、JSON 行には `contextTokens` +- `models list` は、ネイティブモデルメタデータとランタイム上限を区別して保持します。表 + 出力では、有効なランタイム + 上限がネイティブのコンテキストウィンドウと異なる場合、`Ctx` は `contextTokens/contextWindow` を表示します。プロバイダーがその上限を公開している場合、JSON 行には `contextTokens` が含まれます。 - `models list --provider ` は、`moonshot` や - `openai-codex` などのプロバイダー ID でフィルタリングします。`Moonshot AI` など、 - 対話型プロバイダー選択での表示ラベルは受け付けません。 -- モデル参照は **最初の** `/` で分割して解析されます。モデル ID に `/` が含まれる場合 (OpenRouter 形式)、プロバイダープレフィックスを含めます (例: `openrouter/moonshotai/kimi-k2`)。 + `openai-codex` などのプロバイダー ID でフィルターします。`Moonshot AI` など、対話型プロバイダー + ピッカーの表示ラベルは受け付けません。 +- モデル参照は **最初の** `/` で分割して解析されます。モデル ID に `/` が含まれる場合（OpenRouter 形式）、プロバイダープレフィックスを含めます（例: `openrouter/moonshotai/kimi-k2`）。 - プロバイダーを省略すると、OpenClaw はまず入力をエイリアスとして解決し、次に その正確なモデル ID に対する一意の設定済みプロバイダー一致として解決し、その後でのみ 非推奨警告付きで設定済みのデフォルトプロバイダーへフォールバックします。 - そのプロバイダーが設定済みのデフォルトモデルをもう公開していない場合、OpenClaw は - 古い削除済みプロバイダーのデフォルトを表示するのではなく、最初の設定済みプロバイダー/モデルへ + そのプロバイダーが設定済みのデフォルトモデルを公開しなくなった場合、OpenClaw は + 古い削除済みプロバイダーのデフォルトを表面化する代わりに、最初の設定済みプロバイダー/モデルへ フォールバックします。 -- `models status` は、認証出力で非シークレットのプレースホルダー (たとえば `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`) について、シークレットとしてマスクする代わりに `marker()` を表示することがあります。 +- `models status` は、シークレットではないプレースホルダー（たとえば `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`）について、シークレットとしてマスクする代わりに、認証出力に `marker()` を表示する場合があります。 ### モデルスキャン `models scan` は OpenRouter の公開 `:free` カタログを読み取り、フォールバック用途の -候補をランク付けします。カタログ自体は公開されているため、メタデータのみのスキャンには +候補をランク付けします。カタログ自体は公開されているため、メタデータのみのスキャンでは OpenRouter キーは不要です。 デフォルトでは、OpenClaw はライブモデル呼び出しでツールと画像のサポートをプローブしようとします。 OpenRouter キーが設定されていない場合、コマンドはメタデータのみの -出力へフォールバックし、`:free` モデルでもプローブと推論には `OPENROUTER_API_KEY` が必要であることを説明します。 +出力にフォールバックし、`:free` モデルでもプローブと推論には `OPENROUTER_API_KEY` が必要であることを説明します。 オプション: -- `--no-probe` (メタデータのみ。設定/シークレットの検索なし) +- `--no-probe`（メタデータのみ。設定/シークレットの検索なし） - `--min-params ` - `--max-age-days ` - `--provider ` - `--max-candidates ` -- `--timeout ` (カタログリクエストと各プローブのタイムアウト) +- `--timeout `（カタログリクエストと各プローブのタイムアウト） - `--concurrency ` - `--yes` - `--no-input` @@ -118,17 +122,17 @@ OpenRouter キーが設定されていない場合、コマンドはメタデー - `--json` - `--plain` -- `--check` (終了コード 1=期限切れ/不足、2=期限間近) -- `--probe` (設定済み認証プロファイルのライブプローブ) -- `--probe-provider ` (1つのプロバイダーをプローブ) -- `--probe-profile ` (繰り返しまたはカンマ区切りのプロファイル ID) +- `--check`（終了コード 1=期限切れ/欠落、2=期限間近） +- `--probe`（設定済み認証プロファイルのライブプローブ） +- `--probe-provider `（1つのプロバイダーをプローブ） +- `--probe-profile `（繰り返し指定またはカンマ区切りのプロファイル ID） - `--probe-timeout ` - `--probe-concurrency ` - `--probe-max-tokens ` -- `--agent ` (設定済みエージェント ID。`OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` を上書き) +- `--agent `（設定済みエージェント ID。`OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` を上書き） -`--json` は stdout を JSON ペイロード専用に保持します。認証プロファイル、プロバイダー、 -起動時診断は stderr に送られるため、スクリプトは stdout を `jq` などのツールへ直接 +`--json` は stdout を JSON ペイロード専用に保ちます。認証プロファイル、プロバイダー、 +起動診断は stderr に送られるため、スクリプトは stdout を `jq` などのツールへ直接 パイプできます。 プローブステータスの分類: @@ -145,14 +149,14 @@ OpenRouter キーが設定されていない場合、コマンドはメタデー 想定されるプローブ詳細/理由コードのケース: - `excluded_by_auth_order`: 保存済みプロファイルは存在しますが、明示的な - `auth.order.` がそれを省略したため、プローブは試行する代わりに + `auth.order.` がそれを省略しているため、プローブは試行する代わりに 除外を報告します。 - `missing_credential`、`invalid_expires`、`expired`、`unresolved_ref`: - プロファイルは存在しますが、適格でないか解決できません。 -- `no_model`: プロバイダー認証は存在しますが、OpenClaw はそのプロバイダーに対してプローブ可能な + プロファイルは存在しますが、対象外または解決不能です。 +- `no_model`: プロバイダー認証は存在しますが、OpenClaw はそのプロバイダー用のプローブ可能な モデル候補を解決できませんでした。 -## エイリアス + フォールバック +## エイリアスとフォールバック ```bash openclaw models aliases list @@ -168,13 +172,14 @@ openclaw models auth setup-token --provider openclaw models auth paste-token ``` -`models auth add` は対話型の認証ヘルパーです。選択したプロバイダーに応じて、 -プロバイダー認証フロー (OAuth/APIキー) を起動するか、手動のトークン貼り付けへ案内します。 +`models auth add` は対話型の認証ヘルパーです。選択した +プロバイダーに応じて、プロバイダー認証フロー（OAuth/APIキー）を起動するか、手動トークン貼り付けへ案内します。 -`models auth login` はプロバイダー Plugin の認証フロー (OAuth/APIキー) を実行します。 -インストールされているプロバイダーを確認するには、`openclaw plugins list` を使用します。 -特定の設定済みエージェントストアへ認証結果を書き込むには、`openclaw models auth --agent ` を使用します。 -親の `--agent` フラグは、`add`、`login`、`setup-token`、`paste-token`、`login-github-copilot` によって尊重されます。 +`models auth login` は、プロバイダー Plugin の認証フロー（OAuth/APIキー）を実行します。 +インストールされているプロバイダーを確認するには `openclaw plugins list` を使用します。 +認証結果を特定の設定済みエージェントストアに書き込むには、`openclaw models auth --agent ` を使用します。 +親の `--agent` フラグは、 +`add`、`login`、`setup-token`、`paste-token`、`login-github-copilot` で有効です。 例: @@ -182,18 +187,18 @@ openclaw models auth paste-token openclaw models auth login --provider openai-codex --set-default ``` -注: +注記: -- `setup-token` と `paste-token` は、トークン認証メソッドを公開するプロバイダー向けの +- `setup-token` と `paste-token` は、トークン認証方式を公開するプロバイダー向けの 汎用トークンコマンドのままです。 - `setup-token` には対話型 TTY が必要で、プロバイダーのトークン認証 - メソッドを実行します (プロバイダーが公開している場合は、そのプロバイダーの `setup-token` メソッドがデフォルト)。 + 方式を実行します（プロバイダーが公開している場合は、デフォルトでそのプロバイダーの `setup-token` 方式になります）。 - `paste-token` は、別の場所または自動化から生成されたトークン文字列を受け付けます。 -- `paste-token` は `--provider` を必要とし、トークン値をプロンプトで求め、 +- `paste-token` には `--provider` が必要で、トークン値の入力を求め、 `--profile-id` を渡さない限り、デフォルトのプロファイル ID `:manual` に書き込みます。 - `paste-token --expires-in ` は、`365d` や `12h` などの 相対期間から絶対トークン有効期限を保存します。 -- Anthropic 注: Anthropic スタッフは、OpenClaw 形式の Claude CLI 使用が再び許可されていると伝えたため、Anthropic が新しいポリシーを公開しない限り、OpenClaw はこの統合における Claude CLI の再利用と `claude -p` 使用を認可済みとして扱います。 +- Anthropic の注記: Anthropic スタッフは、OpenClaw 形式の Claude CLI 使用が再び許可されたと伝えているため、Anthropic が新しいポリシーを公開しない限り、OpenClaw はこの連携において Claude CLI の再利用と `claude -p` の使用を認可済みとして扱います。 - Anthropic の `setup-token` / `paste-token` は、サポートされる OpenClaw トークンパスとして引き続き利用できますが、OpenClaw は現在、利用可能な場合は Claude CLI の再利用と `claude -p` を優先します。 ## 関連 diff --git a/docs/ja-JP/cli/voicecall.md b/docs/ja-JP/cli/voicecall.md index 176f09a25..61d9c8fda 100644 --- a/docs/ja-JP/cli/voicecall.md +++ b/docs/ja-JP/cli/voicecall.md @@ -1,31 +1,32 @@ --- read_when: - - voice-call Plugin を使用していて、CLI のエントリポイントを知りたい場合 - - '`voicecall setup|smoke|call|continue|dtmf|status|tail|expose` のクイック例を見たい場合' -summary: '`openclaw voicecall` の CLI リファレンス（voice-call Plugin のコマンド画面）' -title: Voicecall + - voice-call プラグインを使用していて、CLI エントリポイントが必要な場合 + - '`voicecall setup|smoke|call|continue|dtmf|status|tail|expose` の簡単な例が必要です' +summary: '`openclaw voicecall` の CLI リファレンス（音声通話 Plugin のコマンドサーフェス）' +title: 音声通話 x-i18n: - generated_at: "2026-04-25T13:44:56Z" - model: gpt-5.4 + generated_at: "2026-05-01T05:00:28Z" + model: gpt-5.5 provider: openai - source_hash: 7c8b83ef75f792920024a67b0dee1b07aff9f55486de1149266c6d94854ca0fe + source_hash: 4090858a58b7defaff955a370c8cb0ff025ef68061e68a6c69a637de24707c0b source_path: cli/voicecall.md - workflow: 15 + workflow: 16 --- # `openclaw voicecall` -`voicecall` は Plugin 提供のコマンドです。voice-call Plugin がインストールされ、有効化されている場合にのみ表示されます。 +`voicecall` はPluginが提供するコマンドです。音声通話Pluginがインストールされ、有効化されている場合にのみ表示されます。 -主なドキュメント: +主要ドキュメント: -- voice-call Plugin: [Voice Call](/ja-JP/plugins/voice-call) +- 音声通話Plugin: [音声通話](/ja-JP/plugins/voice-call) -## よく使うコマンド +## 一般的なコマンド ```bash openclaw voicecall setup openclaw voicecall smoke +openclaw voicecall status --json openclaw voicecall status --call-id openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify openclaw voicecall continue --call-id --message "Any questions?" @@ -33,22 +34,29 @@ openclaw voicecall dtmf --call-id --digits "ww123456#" openclaw voicecall end --call-id ``` -`setup` はデフォルトで人間が読みやすい準備状況チェックを表示します。スクリプトでは `--json` を使用してください: +`setup` はデフォルトで人間が読める形式の準備状況チェックを出力します。 +スクリプト向けには `--json` を使用します: ```bash openclaw voicecall setup --json ``` -外部プロバイダー（`twilio`、`telnyx`、`plivo`）では、setup は `publicUrl`、トンネル、または Tailscale 公開からパブリックな Webhook URL を解決する必要があります。loopback/private の serve フォールバックは、キャリアから到達できないため拒否されます。 +`status` はデフォルトでアクティブな通話をJSONとして出力します。1件の通話を調べるには +`--call-id ` を渡します。 -`smoke` は同じ準備状況チェックを実行します。`--to` と `--yes` の両方が指定されていない限り、実際の電話は発信しません: +外部プロバイダー (`twilio`, `telnyx`, `plivo`) では、セットアップ時に `publicUrl`、トンネル、または Tailscale の公開から公開 +Webhook URLを解決できる必要があります。通信事業者が到達できないため、local loopback/プライベートの +配信フォールバックは拒否されます。 + +`smoke` は同じ準備状況チェックを実行します。`--to` と `--yes` の両方が存在しない限り、 +実際の電話発信は行いません: ```bash -openclaw voicecall smoke --to "+15555550123" # ドライラン -openclaw voicecall smoke --to "+15555550123" --yes # 実際の通知コール +openclaw voicecall smoke --to "+15555550123" # dry run +openclaw voicecall smoke --to "+15555550123" --yes # live notify call ``` -## Webhook の公開（Tailscale） +## Webhookの公開 (Tailscale) ```bash openclaw voicecall expose --mode serve @@ -56,9 +64,9 @@ openclaw voicecall expose --mode funnel openclaw voicecall expose --mode off ``` -セキュリティに関する注記: Webhook エンドポイントは、信頼できるネットワークにのみ公開してください。可能な場合は Tailscale Funnel より Tailscale Serve を優先してください。 +セキュリティ注記: Webhookエンドポイントは、信頼するネットワークにのみ公開してください。可能な場合は Funnel より Tailscale Serve を優先してください。 -## 関連 +## 関連項目 -- [CLI reference](/ja-JP/cli) -- [Voice call plugin](/ja-JP/plugins/voice-call) +- [CLIリファレンス](/ja-JP/cli) +- [音声通話Plugin](/ja-JP/plugins/voice-call) diff --git a/docs/ja-JP/concepts/commitments.md b/docs/ja-JP/concepts/commitments.md index 7b945f7f0..9ec74e4ae 100644 --- a/docs/ja-JP/concepts/commitments.md +++ b/docs/ja-JP/concepts/commitments.md @@ -1,38 +1,38 @@ --- read_when: - OpenClaw に自然なフォローアップを記憶させたい場合 - - 推論されたチェックインがリマインダーとどう異なるかを理解したい場合 - - フォローアップの約束事項を確認または却下したい + - 推定されたチェックインがリマインダーとどう異なるかを理解したい場合 + - フォローアップのコミットメントを確認または却下したい場合 sidebarTitle: Commitments -summary: 正確なリマインダーではないチェックイン向けの推論されたフォローアップメモリ +summary: 厳密なリマインダーではないチェックイン向けの推定フォローアップメモリ title: 推定されたコミットメント x-i18n: - generated_at: "2026-04-30T05:07:21Z" + generated_at: "2026-05-01T05:00:31Z" model: gpt-5.5 provider: openai - source_hash: 3f51af0ac2c9841258fbeeb8f2f98dba6f438b8e0c9433f601a0504d6ef27111 + source_hash: 78841d87fe749aa5b04a967218396df1c1a7884c5767b09215c96aee34fa2014 source_path: concepts/commitments.md workflow: 16 --- -コミットメントは短期間だけ残るフォローアップ記憶です。有効にすると、OpenClaw は -会話が将来の確認機会を生んだことに気づき、あとでそれを持ち出すように -覚えておけます。 +コミットメントは短期間だけ保持されるフォローアップ用メモリです。有効にすると、OpenClaw は +会話から将来のチェックイン機会が生まれたことに気づき、あとで再び取り上げるように +記憶できます。 例: -- 明日の面接について話す。OpenClaw はその後に確認することがあります。 -- 疲れ切っていると言う。OpenClaw はあとで眠れたか尋ねることがあります。 -- 何かが変わったあとでフォローアップするとエージェントが言う。OpenClaw はその - 未完了のループを追跡することがあります。 +- 明日の面接について言及した場合。OpenClaw はその後に確認することがあります。 +- 疲れ切っていると言った場合。OpenClaw はあとで眠れたかどうか尋ねることがあります。 +- エージェントが、何かが変わったあとでフォローアップすると言った場合。OpenClaw はその未完了ループを + 追跡することがあります。 コミットメントは `MEMORY.md` のような永続的な事実ではなく、正確な -リマインダーでもありません。記憶と自動化の中間にあります。OpenClaw は -会話に紐づく義務を記憶し、期限が来たら heartbeat がそれを届けます。 +リマインダーでもありません。メモリと自動化の中間に位置します。OpenClaw は +会話に紐づいた義務を記憶し、期限が来ると heartbeat がそれを届けます。 ## コミットメントを有効にする -コミットメントはデフォルトでオフです。config で有効にします: +コミットメントはデフォルトでオフです。config で有効にします。 ```bash openclaw config set commitments.enabled true @@ -50,60 +50,64 @@ openclaw config set commitments.maxPerDay 3 } ``` -`commitments.maxPerDay` は、推測されたフォローアップをローリング 1 日あたり -エージェントセッションごとにいくつ届けられるかを制限します。デフォルトは `3` です。 +`commitments.maxPerDay` は、ローリング方式の 1 日内でエージェントセッションごとに届けられる +推論されたフォローアップの数を制限します。デフォルトは `3` です。 ## 仕組み -エージェントの返信後、OpenClaw は別のコンテキストで隠れたバックグラウンド抽出パスを -実行することがあります。そのパスは、推測されたフォローアップコミットメントだけを探します。 -表示される会話には書き込まず、抽出について推論するようメインエージェントに -求めることもありません。 +エージェントの返信後、OpenClaw は別コンテキストで非表示のバックグラウンド抽出パスを実行することがあります。 +このパスは、推論されたフォローアップコミットメントだけを探します。 +表示中の会話には書き込まず、メインのエージェントに抽出について +推論させることもありません。 -高信頼度の候補が見つかると、OpenClaw は次の情報を含むコミットメントを保存します: +高信頼度の候補が見つかると、OpenClaw は次の情報を持つコミットメントを保存します。 -- エージェント id +- エージェント ID - セッションキー - 元のチャネルと配信先 - 期限ウィンドウ -- 短い推奨の確認 -- heartbeat が送信するかどうかを判断するために十分なソースコンテキスト +- 短いチェックイン案 +- 送信するかどうかを heartbeat が判断するための、指示ではないメタデータ 配信は heartbeat を通じて行われます。コミットメントの期限が来ると、heartbeat は -同じエージェントとチャネルスコープの heartbeat ターンにそのコミットメントを追加します。 -モデルは自然な確認を 1 つ送信するか、`HEARTBEAT_OK` と返信して却下できます。 +同じエージェントおよびチャネルスコープの heartbeat ターンにコミットメントを追加します。 +モデルは自然なチェックインを 1 件送信するか、`HEARTBEAT_OK` と返信して破棄できます。 +heartbeat が `target: "none"` で設定されている場合、期限が来たコミットメントは +内部に残り、外部チェックインは送信されません。コミットメント配信プロンプトは +元の会話テキストを再生せず、期限が来たコミットメントの heartbeat ターンは +OpenClaw ツールなしで実行されます。 -OpenClaw は、推測されたコミットメントを書き込んだ直後に配信することはありません。 -期限時刻は、コミットメント作成後の少なくとも 1 heartbeat 間隔後に制限されるため、 -フォローアップが推測されたその瞬間にそのまま返ってくることはありません。 +OpenClaw は、推論されたコミットメントを書き込んだ直後に配信することはありません。 +期限時刻は、コミットメント作成後少なくとも 1 回分の heartbeat 間隔以降に制限されます。 +そのため、フォローアップが推論されたその瞬間にそのまま返ってくることはありません。 ## スコープ -コミットメントは、作成された正確なエージェントとチャネルコンテキストにスコープされます。 -Discord であるエージェントと会話中に推測されたフォローアップが、別のエージェント、 -別のチャネル、または無関係なセッションによって配信されることはありません。 +コミットメントは、作成された正確なエージェントおよびチャネルコンテキストにスコープされます。 +Discord であるエージェントと話している間に推論されたフォローアップは、 +別のエージェント、別のチャネル、または無関係なセッションからは配信されません。 -このスコープは機能の一部です。自然な確認は、グローバルなリマインダーシステムではなく、 +このスコープは機能の一部です。自然なチェックインは、グローバルなリマインダーシステムのようではなく、 同じ会話が続いているように感じられるべきです。 ## コミットメントとリマインダー -| 必要なこと | 使用するもの | -| ----------------------------------------------- | ------------------------------------------- | -| 「午後 3 時にリマインドして」 | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) | -| 「20 分後に通知して」 | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) | -| 「このレポートを平日毎日実行して」 | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) | -| 「明日面接がある」 | コミットメント | -| 「一晩中起きていた」 | コミットメント | -| 「この未完了スレッドに回答しなかったらフォローアップして」 | コミットメント | +| 必要なこと | 使用するもの | +| ----------------------------------------------- | ---------------------------------------- | +| "Remind me at 3 PM" | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) | +| "Ping me in 20 minutes" | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) | +| "Run this report every weekday" | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) | +| "I have an interview tomorrow" | コミットメント | +| "I was up all night" | コミットメント | +| "Follow up if I do not answer this open thread" | コミットメント | -ユーザーからの明確なリクエストは、すでにスケジューラーパスの対象です。コミットメントは -推測されたフォローアップ専用です。つまり、ユーザーがリマインダーを依頼していなくても、 -会話から将来の有用な確認が明確に生まれた場面のためのものです。 +ユーザーの明示的な依頼は、すでにスケジューラーの経路に属します。コミットメントは +推論されたフォローアップ専用です。つまり、ユーザーがリマインダーを依頼していなくても、 +会話の中で将来の有用なチェックインが明確に生まれた場面です。 ## コミットメントを管理する -保存されたコミットメントを確認してクリアするには CLI を使用します: +保存されたコミットメントの確認と消去には CLI を使用します。 ```bash openclaw commitments @@ -117,13 +121,12 @@ openclaw commitments dismiss cm_abc123 ## プライバシーとコスト -コミットメント抽出は LLM パスを使用するため、有効にすると対象となるターンの後に -バックグラウンドのモデル使用量が追加されます。このパスはユーザーに表示される -会話からは隠されていますが、フォローアップが存在するかどうかを判断するために必要な -直近のやり取りを読み取ることがあります。 +コミットメント抽出は LLM パスを使用するため、有効にすると対象ターンの後にバックグラウンドのモデル +使用量が追加されます。このパスはユーザーに表示される会話からは隠されていますが、 +フォローアップが存在するかどうかを判断するために必要な直近のやり取りを読み取ることがあります。 -保存されたコミットメントはローカルの OpenClaw 状態です。これは運用上の記憶であり、 -長期記憶ではありません。この機能を無効にするには、次を実行します: +保存されたコミットメントはローカルの OpenClaw 状態です。これは運用上のメモリであり、 +長期メモリではありません。この機能は次のコマンドで無効にできます。 ```bash openclaw config set commitments.enabled false @@ -134,17 +137,17 @@ openclaw config set commitments.enabled false 期待したフォローアップが表示されない場合: - `commitments.enabled` が `true` であることを確認します。 -- 保留中、却下済み、スヌーズ済み、または期限切れのレコードがないか +- 保留中、破棄済み、スヌーズ中、または期限切れのレコードについて `openclaw commitments --all` を確認します。 -- エージェントの heartbeat が実行中であることを確認します。 +- エージェントで heartbeat が実行されていることを確認します。 - そのエージェントセッションで `commitments.maxPerDay` にすでに達していないか確認します。 -- 明確なリマインダーはコミットメント抽出ではスキップされ、代わりに +- 明示的なリマインダーはコミットメント抽出ではスキップされ、代わりに [スケジュール済みタスク](/ja-JP/automation/cron-jobs) に表示されるべきであることを覚えておいてください。 ## 関連 -- [記憶の概要](/ja-JP/concepts/memory) -- [Active memory](/ja-JP/concepts/active-memory) +- [メモリ概要](/ja-JP/concepts/memory) +- [Active Memory](/ja-JP/concepts/active-memory) - [Heartbeat](/ja-JP/gateway/heartbeat) - [スケジュール済みタスク](/ja-JP/automation/cron-jobs) - [`openclaw commitments`](/ja-JP/cli/commitments) diff --git a/docs/ja-JP/concepts/openclaw-sdk.md b/docs/ja-JP/concepts/openclaw-sdk.md index d8ecc7314..fdfd4be6e 100644 --- a/docs/ja-JP/concepts/openclaw-sdk.md +++ b/docs/ja-JP/concepts/openclaw-sdk.md @@ -1,21 +1,21 @@ --- read_when: - - OpenClaw と通信する外部アプリ、スクリプト、ダッシュボード、CI ジョブ、または IDE 拡張機能を構築している場合 - - App SDKとPlugin SDKのどちらを選ぶか - - Gateway エージェントの実行、セッション、イベント、承認、モデル、またはツールと統合している + - OpenClaw と通信する外部アプリ、スクリプト、ダッシュボード、CIジョブ、またはIDE拡張機能を構築している + - App SDKとPlugin SDKのどちらを選ぶべきかを検討している + - Gateway のエージェント実行、セッション、イベント、承認、モデル、またはツールと連携する場合 sidebarTitle: App SDK -summary: 外部アプリ、スクリプト、ダッシュボード、CIジョブ、IDE拡張機能向けの公開 OpenClaw アプリ SDK +summary: 外部アプリ、スクリプト、ダッシュボード、CIジョブ、IDE拡張機能向けの公開 OpenClaw App SDK title: OpenClaw アプリ SDK x-i18n: - generated_at: "2026-04-30T05:09:17Z" + generated_at: "2026-05-01T05:00:28Z" model: gpt-5.5 provider: openai - source_hash: 9c46454d172a25d329a796461982dc4307d3720a28df777eda8605996505e38c + source_hash: e531e985ca82026b230b03f8df5ab908d66e2b608e09c46af2ec060b9def0c24 source_path: concepts/openclaw-sdk.md workflow: 16 --- -**OpenClaw App SDK** は、OpenClaw プロセスの外部にあるアプリ向けの公開クライアント API です。スクリプト、ダッシュボード、CI ジョブ、IDE 拡張、またはその他の外部アプリが Gateway へ接続し、エージェント実行を開始し、イベントをストリーミングし、結果を待機し、作業をキャンセルし、Gateway リソースを調べる場合は `@openclaw/sdk` を使用します。 +**OpenClaw App SDK** は、OpenClaw プロセス外のアプリ向けの公開クライアント API です。スクリプト、ダッシュボード、CI ジョブ、IDE 拡張機能、またはその他の外部アプリが Gateway に接続し、エージェント実行を開始し、イベントをストリームし、結果を待機し、作業をキャンセルし、Gateway リソースを調査する場合は `@openclaw/sdk` を使用します。 App SDK は [Plugin SDK](/ja-JP/plugins/sdk-overview) とは異なります。 @@ -23,38 +23,40 @@ x-i18n: `openclaw/plugin-sdk/*` は、OpenClaw 内で実行され、プロバイダー、チャネル、ツール、フック、または信頼済みランタイムを登録する Plugin 専用です。 -## 現在同梱されているもの +## 現在提供されているもの -`@openclaw/sdk` には次が含まれます。 +`@openclaw/sdk` には次が含まれています。 -| サーフェス | 状態 | 役割 | -| ------------------------- | ---------- | ---------------------------------------------------------------------------- | -| `OpenClaw` | 利用可能 | メインのクライアントエントリーポイント。トランスポート、接続、リクエスト、イベントを所有します。 | -| `GatewayClientTransport` | 利用可能 | Gateway クライアントに支えられた WebSocket トランスポート。 | -| `oc.agents` | 利用可能 | エージェントハンドルの一覧表示、作成、更新、削除、取得を行います。 | -| `Agent.run()` | 利用可能 | Gateway の `agent` 実行を開始し、`Run` を返します。 | -| `oc.runs` | 利用可能 | 実行の作成、取得、待機、キャンセル、ストリーミングを行います。 | -| `Run.events()` | 利用可能 | 高速な実行向けのリプレイ付きで、実行単位の正規化済みイベントをストリーミングします。 | -| `Run.wait()` | 利用可能 | `agent.wait` を呼び出し、安定した `RunResult` を返します。 | -| `Run.cancel()` | 利用可能 | 実行 ID により `sessions.abort` を呼び出し、利用可能な場合はセッションキーも使います。 | -| `oc.sessions` | 利用可能 | セッションハンドルの作成、解決、送信、パッチ適用、圧縮、取得を行います。 | -| `Session.send()` | 利用可能 | `sessions.send` を呼び出し、`Run` を返します。 | -| `oc.models` | 利用可能 | `models.list` と現在の `models.authStatus` 状態 RPC を呼び出します。 | -| `oc.tools` | 一部対応 | ツールカタログと有効なツールを一覧表示します。直接のツール呼び出しは未接続です。 | -| `oc.approvals` | 利用可能 | Gateway の承認 RPC を通じて exec 承認の一覧表示と解決を行います。 | -| `oc.rawEvents()` | 利用可能 | 高度な利用者向けに生の Gateway イベントを公開します。 | -| `normalizeGatewayEvent()` | 利用可能 | 生の Gateway イベントを安定した SDK イベント形状へ変換します。 | +| サーフェス | 状態 | 機能 | +| ------------------------- | ------- | ---------------------------------------------------------------------------- | +| `OpenClaw` | 準備完了 | メインのクライアントエントリポイント。トランスポート、接続、リクエスト、イベントを所有します。 | +| `GatewayClientTransport` | 準備完了 | Gateway クライアントを基盤にした WebSocket トランスポート。 | +| `oc.agents` | 準備完了 | エージェントハンドルの一覧表示、作成、更新、削除、取得を行います。 | +| `Agent.run()` | 準備完了 | Gateway `agent` 実行を開始し、`Run` を返します。 | +| `oc.runs` | 準備完了 | 実行の作成、取得、待機、キャンセル、ストリームを行います。 | +| `Run.events()` | 準備完了 | 高速な実行向けのリプレイ付きで、実行ごとに正規化されたイベントをストリームします。 | +| `Run.wait()` | 準備完了 | `agent.wait` を呼び出し、安定した `RunResult` を返します。 | +| `Run.cancel()` | 準備完了 | 実行 ID により `sessions.abort` を呼び出し、利用可能な場合はセッションキーも使います。 | +| `oc.sessions` | 準備完了 | セッションハンドルの作成、解決、送信、パッチ、Compaction、取得を行います。 | +| `Session.send()` | 準備完了 | `sessions.send` を呼び出し、`Run` を返します。 | +| `oc.models` | 準備完了 | `models.list` と現在の `models.authStatus` ステータス RPC を呼び出します。 | +| `oc.tools` | 一部対応 | ツールカタログと有効なツールを一覧表示します。直接のツール呼び出しは接続されていません。 | +| `oc.artifacts` | 準備完了 | Gateway トランスクリプトアーティファクトの一覧表示、取得、ダウンロードを行います。 | +| `oc.approvals` | 準備完了 | Gateway 承認 RPC を通じて exec 承認を一覧表示および解決します。 | +| `oc.rawEvents()` | 準備完了 | 高度なコンシューマー向けに生の Gateway イベントを公開します。 | +| `normalizeGatewayEvent()` | 準備完了 | 生の Gateway イベントを安定した SDK イベント形状に変換します。 | -SDK は、これらのサーフェスで使われる中核型もエクスポートします。 +SDK は、これらのサーフェスで使用される中核型もエクスポートします。 `AgentRunParams`、`RunResult`、`RunStatus`、`OpenClawEvent`、 `OpenClawEventType`、`GatewayEvent`、`OpenClawTransport`、 `GatewayRequestOptions`、`SessionCreateParams`、`SessionSendParams`、 -`RuntimeSelection`、`EnvironmentSelection`、`WorkspaceSelection`、 -`ApprovalMode`、および関連する結果型です。 +`ArtifactSummary`、`ArtifactQuery`、`ArtifactsListResult`、 +`ArtifactsGetResult`、`ArtifactsDownloadResult`、`RuntimeSelection`、 +`EnvironmentSelection`、`WorkspaceSelection`、`ApprovalMode`、および関連する結果型です。 -## Gateway への接続 +## Gateway に接続する -明示的な Gateway URL でクライアントを作成するか、テストや埋め込みアプリランタイム向けにカスタムトランスポートを注入します。 +明示的な Gateway URL でクライアントを作成するか、テストや組み込みアプリランタイム向けにカスタムトランスポートを注入します。 ```typescript import { OpenClaw } from "@openclaw/sdk"; @@ -68,7 +70,7 @@ const oc = new OpenClaw({ await oc.connect(); ``` -`new OpenClaw({ gateway: "ws://..." })` は `url` と同等です。コンストラクターは `gateway: "auto"` オプションを受け付けますが、自動 Gateway 検出はまだ独立した SDK 機能ではありません。アプリが Gateway を検出する方法をすでに把握していない場合は `url` を渡してください。 +`new OpenClaw({ gateway: "ws://..." })` は `url` と同等です。`gateway: "auto"` オプションはコンストラクターで受け付けられますが、自動 Gateway 検出はまだ独立した SDK 機能ではありません。アプリが Gateway の検出方法をまだ知らない場合は `url` を渡してください。 テストでは、`OpenClawTransport` を実装するオブジェクトを渡します。 @@ -83,7 +85,7 @@ const oc = new OpenClaw({ }); ``` -## エージェントの実行 +## エージェントを実行する アプリがエージェントハンドルを必要とする場合は `oc.agents.get(id)` を使用し、その後 `agent.run()` を呼び出します。 @@ -108,13 +110,13 @@ const result = await run.wait({ timeoutMs: 120_000 }); console.log(result.status); ``` -`openai/gpt-5.5` のようなプロバイダー修飾モデル参照は、Gateway の `provider` と `model` のオーバーライドに分割されます。SDK 内の `timeoutMs` はミリ秒のままで、`agent` RPC 向けに Gateway のタイムアウト秒数へ変換されます。 +`openai/gpt-5.5` のようなプロバイダー修飾付きモデル参照は、Gateway の `provider` と `model` のオーバーライドに分割されます。`timeoutMs` は SDK 内ではミリ秒のままで、`agent` RPC 向けに Gateway のタイムアウト秒数へ変換されます。 -`run.wait()` は Gateway の `agent.wait` RPC を使用します。実行がまだアクティブな間に待機期限が切れた場合、実行自体がタイムアウトしたように見せかけるのではなく、`status: "accepted"` を返します。ランタイムのタイムアウト、中止された実行、キャンセルされた実行は、`timed_out` または `cancelled` に正規化されます。 +`run.wait()` は Gateway の `agent.wait` RPC を使用します。実行がまだアクティブな間に待機期限が切れた場合、実行自体がタイムアウトしたかのように装うのではなく、`status: "accepted"` を返します。ランタイムのタイムアウト、中止された実行、キャンセルされた実行は、`timed_out` または `cancelled` に正規化されます。 -## セッションの作成と再利用 +## セッションを作成して再利用する -アプリが永続的なトランスクリプト状態を必要とする場合は、セッションを使用します。 +アプリが永続的なトランスクリプト状態を必要とする場合はセッションを使用します。 ```typescript const session = await oc.sessions.create({ @@ -126,7 +128,7 @@ const run = await session.send("Prepare release notes from the current diff."); await run.wait(); ``` -`Session.send()` は `sessions.send` を呼び出し、`Run` を返します。セッションハンドルは次にも対応しています。 +`Session.send()` は `sessions.send` を呼び出し、`Run` を返します。セッションハンドルは次もサポートします。 ```typescript await session.abort(run.id); @@ -134,9 +136,9 @@ await session.patch({ label: "renamed-session" }); await session.compact({ maxLines: 200 }); ``` -## イベントのストリーミング +## イベントをストリームする -SDK は、生の Gateway イベントを安定した `OpenClawEvent` エンベロープへ正規化します。 +SDK は生の Gateway イベントを安定した `OpenClawEvent` エンベロープに正規化します。 ```typescript type OpenClawEvent = { @@ -156,30 +158,30 @@ type OpenClawEvent = { 一般的なイベント型は次のとおりです。 -| イベント型 | 元の Gateway イベント | +| イベント型 | ソース Gateway イベント | | --------------------- | ------------------------------------------- | -| `run.started` | `agent` ライフサイクル開始 | -| `run.completed` | `agent` ライフサイクル終了 | -| `run.failed` | `agent` ライフサイクルエラー | -| `run.cancelled` | 中止/キャンセルされたライフサイクル終了 | -| `run.timed_out` | タイムアウトのライフサイクル終了 | -| `assistant.delta` | アシスタントのストリーミング差分 | -| `assistant.message` | アシスタントメッセージ | -| `thinking.delta` | 思考またはプランのストリーム | -| `tool.call.started` | ツール/項目/コマンドの開始 | -| `tool.call.delta` | ツール/項目/コマンドの更新 | -| `tool.call.completed` | ツール/項目/コマンドの完了 | -| `tool.call.failed` | ツール/項目/コマンドの失敗またはブロック状態 | -| `approval.requested` | exec または Plugin 承認リクエスト | -| `approval.resolved` | exec または Plugin 承認の解決 | -| `session.created` | `sessions.changed` の作成 | -| `session.updated` | `sessions.changed` の更新 | -| `session.compacted` | `sessions.changed` の圧縮 | -| `task.updated` | タスク更新イベント | -| `artifact.updated` | パッチストリームイベント | +| `run.started` | `agent` ライフサイクル開始 | +| `run.completed` | `agent` ライフサイクル終了 | +| `run.failed` | `agent` ライフサイクルエラー | +| `run.cancelled` | 中止またはキャンセルされたライフサイクル終了 | +| `run.timed_out` | タイムアウトによるライフサイクル終了 | +| `assistant.delta` | アシスタントのストリーミング差分 | +| `assistant.message` | アシスタントメッセージ | +| `thinking.delta` | 思考またはプランのストリーム | +| `tool.call.started` | ツール、項目、コマンドの開始 | +| `tool.call.delta` | ツール、項目、コマンドの更新 | +| `tool.call.completed` | ツール、項目、コマンドの完了 | +| `tool.call.failed` | ツール、項目、コマンドの失敗またはブロック状態 | +| `approval.requested` | exec または Plugin 承認リクエスト | +| `approval.resolved` | exec または Plugin 承認の解決 | +| `session.created` | `sessions.changed` 作成 | +| `session.updated` | `sessions.changed` 更新 | +| `session.compacted` | `sessions.changed` Compaction | +| `task.updated` | タスク更新イベント | +| `artifact.updated` | パッチストリームイベント | | `raw` | まだ安定した SDK マッピングがない任意のイベント | -`Run.events()` はイベントを 1 つの実行 ID に絞り込み、高速な実行向けに、すでに確認済みのイベントをリプレイします。つまり、記載されている次のフローは安全です。 +`Run.events()` はイベントを 1 つの実行 ID に絞り込み、高速な実行のために既に確認済みのイベントをリプレイします。つまり、ドキュメント化された次のフローは安全です。 ```typescript const run = await agent.run("Summarize the latest session."); @@ -193,7 +195,7 @@ for await (const event of run.events()) { アプリ全体のストリームには `oc.events()` を使用します。生の Gateway フレームには `oc.rawEvents()` を使用します。 -## モデル、ツール、承認 +## モデル、ツール、アーティファクト、承認 モデルヘルパーは現在の Gateway メソッドに対応します。 @@ -209,6 +211,19 @@ await oc.tools.list(); await oc.tools.effective({ sessionKey: "main" }); ``` +アーティファクトヘルパーは、セッション、実行、またはタスクコンテキスト向けの Gateway アーティファクト投影を公開します。各呼び出しには、明示的な `sessionKey`、`runId`、または `taskId` スコープのいずれか 1 つが必要です。 + +```typescript +const { artifacts } = await oc.artifacts.list({ sessionKey: "main" }); +const first = artifacts[0]; + +if (first) { + const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" }); + const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" }); + console.log(download.encoding, download.url); +} +``` + 承認ヘルパーは exec 承認 RPC を使用します。 ```typescript @@ -216,9 +231,9 @@ const approvals = await oc.approvals.list(); await oc.approvals.respond("approval-id", { decision: "approve" }); ``` -## 現時点で明示的に非対応 +## 現在明示的にサポートされていないもの -SDK には目指すプロダクトモデルの名前が含まれていますが、Gateway RPC が存在するかのように黙って振る舞うことはありません。現在、次の呼び出しは明示的な非対応エラーを投げます。 +SDK には今後目指すプロダクトモデル用の名前が含まれていますが、Gateway RPC が存在するかのように暗黙的に装うことはありません。現在、これらの呼び出しは明示的な未サポートエラーをスローします。 ```typescript await oc.tasks.list(); @@ -227,26 +242,22 @@ await oc.tasks.cancel("task-id"); await oc.tools.invoke("tool-name", {}); -await oc.artifacts.list(); -await oc.artifacts.get("artifact-id"); -await oc.artifacts.download("artifact-id"); - await oc.environments.list(); await oc.environments.create({}); await oc.environments.status("environment-id"); await oc.environments.delete("environment-id"); ``` -実行単位の `workspace`、`runtime`、`environment`、`approvals` フィールドは将来の形状として型付けされていますが、現在の Gateway は `agent` RPC でこれらのオーバーライドをサポートしていません。呼び出し元がこれらを渡した場合、SDK は実行を送信する前に例外を投げます。これにより、デフォルトのワークスペース、ランタイム、環境、または承認の挙動で作業が誤って実行されることを防ぎます。 +実行ごとの `workspace`、`runtime`、`environment`、`approvals` フィールドは将来の形状として型付けされていますが、現在の Gateway は `agent` RPC でこれらのオーバーライドをサポートしていません。呼び出し元がそれらを渡した場合、作業がデフォルトのワークスペース、ランタイム、環境、または承認動作で誤って実行されないよう、SDK は実行を送信する前にスローします。 -## App SDK と Plugin SDK の違い +## App SDK と Plugin SDK コードが OpenClaw の外部にある場合は App SDK を使用します。 - エージェント実行を開始または監視する Node スクリプト - Gateway を呼び出す CI ジョブ - ダッシュボードと管理パネル -- IDE 拡張 +- IDE 拡張機能 - チャネル Plugin になる必要がない外部ブリッジ - 偽または実際の Gateway トランスポートを使う統合テスト @@ -258,7 +269,7 @@ await oc.environments.delete("environment-id"); - エージェントハーネス Plugin - 信頼済みランタイムヘルパー -App SDK コードは `@openclaw/sdk` からインポートする必要があります。Plugin コードは、ドキュメント化された `openclaw/plugin-sdk/*` サブパスからインポートする必要があります。この 2 つの契約を混在させないでください。 +App SDK コードは `@openclaw/sdk` からインポートする必要があります。Plugin コードは、ドキュメント化された `openclaw/plugin-sdk/*` サブパスからインポートする必要があります。この 2 つのコントラクトを混在させないでください。 ## 関連ドキュメント @@ -269,4 +280,4 @@ App SDK コードは `@openclaw/sdk` からインポートする必要があり - [セッション](/ja-JP/concepts/session) - [バックグラウンドタスク](/ja-JP/automation/tasks) - [ACP エージェント](/ja-JP/tools/acp-agents) -- [Plugin SDK 概要](/ja-JP/plugins/sdk-overview) +- [Plugin SDK の概要](/ja-JP/plugins/sdk-overview) diff --git a/docs/ja-JP/gateway/config-channels.md b/docs/ja-JP/gateway/config-channels.md index 8e20a77db..67c9e78d4 100644 --- a/docs/ja-JP/gateway/config-channels.md +++ b/docs/ja-JP/gateway/config-channels.md @@ -1,24 +1,24 @@ --- read_when: - - チャンネルPluginの設定（認証、アクセス制御、複数アカウント） + - チャネル Plugin の設定（認証、アクセス制御、マルチアカウント） - チャネルごとの設定キーのトラブルシューティング - - DMポリシー、グループポリシー、またはメンションゲーティングの監査 + - DM ポリシー、グループポリシー、またはメンションゲーティングの監査 summary: 'チャネル設定: Slack、Discord、Telegram、WhatsApp、Matrix、iMessage などにわたるアクセス制御、ペアリング、チャネルごとのキー' title: 設定 — チャンネル x-i18n: - generated_at: "2026-04-30T16:28:52Z" + generated_at: "2026-05-01T05:00:30Z" model: gpt-5.5 provider: openai - source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915 + source_hash: ce1571d51e026182d49b935780a986780a90b05afc0acca027b2541b80a1aac2 source_path: gateway/config-channels.md workflow: 16 --- `channels.*` 配下のチャンネル別設定キー。DM とグループアクセス、 -マルチアカウント構成、メンション制御、Slack、Discord、 -Telegram、WhatsApp、Matrix、iMessage、およびその他の同梱チャンネル Plugin のチャンネル別キーを扱います。 +複数アカウント構成、メンションゲート、Slack、Discord、 +Telegram、WhatsApp、Matrix、iMessage、その他の同梱チャンネル Plugin 用のチャンネル別キーを扱います。 -エージェント、ツール、Gateway ランタイム、およびその他のトップレベルキーについては、 +エージェント、ツール、Gateway ランタイム、その他のトップレベルキーについては、 [設定リファレンス](/ja-JP/gateway/configuration-reference)を参照してください。 ## チャンネル @@ -29,28 +29,28 @@ Telegram、WhatsApp、Matrix、iMessage、およびその他の同梱チャン すべてのチャンネルは DM ポリシーとグループポリシーに対応しています。 -| DM ポリシー | 挙動 | +| DM ポリシー | 動作 | | ------------------- | --------------------------------------------------------------- | -| `pairing` (デフォルト) | 未知の送信者は一度限りのペアリングコードを受け取り、所有者の承認が必要 | -| `allowlist` | `allowFrom` 内（またはペアリング済みの許可ストア内）の送信者のみ | +| `pairing` (default) | 未知の送信者には一度限りのペアリングコードが届き、所有者の承認が必要 | +| `allowlist` | `allowFrom` 内（またはペアリング済み許可ストア内）の送信者のみ | | `open` | すべての受信 DM を許可（`allowFrom: ["*"]` が必要） | | `disabled` | すべての受信 DM を無視 | -| グループポリシー | 挙動 | +| グループポリシー | 動作 | | --------------------- | ------------------------------------------------------ | -| `allowlist` (デフォルト) | 設定済みの許可リストに一致するグループのみ | -| `open` | グループ許可リストをバイパス（メンション制御は引き続き適用） | -| `disabled` | すべてのグループ/ルームメッセージをブロック | +| `allowlist` (default) | 設定された許可リストに一致するグループのみ | +| `open` | グループ許可リストをバイパス（メンションゲートは引き続き適用） | +| `disabled` | すべてのグループ/ルームメッセージをブロック | `channels.defaults.groupPolicy` は、プロバイダーの `groupPolicy` が未設定の場合のデフォルトを設定します。 -ペアリングコードは 1 時間後に期限切れになります。保留中の DM ペアリングリクエストは **チャンネルごとに 3 件**に制限されます。 -プロバイダーブロックが完全に存在しない場合（`channels.` がない場合）、ランタイムのグループポリシーは起動時の警告付きで `allowlist`（フェイルクローズ）にフォールバックします。 +ペアリングコードは 1 時間後に期限切れになります。保留中の DM ペアリング要求は **チャンネルごとに 3 件** に制限されます。 +プロバイダーブロック全体が存在しない場合（`channels.` がない場合）、ランタイムのグループポリシーは起動時の警告付きで `allowlist`（fail-closed）にフォールバックします。 ### チャンネルモデルの上書き -`channels.modelByChannel` を使用して、特定のチャンネル ID をモデルに固定します。値には `provider/model` または設定済みのモデルエイリアスを指定できます。チャンネルマッピングは、セッションにモデルの上書きがまだない場合（たとえば `/model` で設定された場合）に適用されます。 +`channels.modelByChannel` を使用して、特定のチャンネル ID をモデルに固定します。値には `provider/model` または設定済みのモデルエイリアスを指定できます。チャンネルマッピングは、セッションに既存のモデル上書き（例: `/model` で設定）がない場合に適用されます。 ```json5 { @@ -71,9 +71,9 @@ Telegram、WhatsApp、Matrix、iMessage、およびその他の同梱チャン } ``` -### チャンネルのデフォルトと Heartbeat +### チャンネルデフォルトと Heartbeat -プロバイダー間で共有するグループポリシーと Heartbeat の挙動には `channels.defaults` を使用します。 +プロバイダー間で共有されるグループポリシーと Heartbeat の動作には、`channels.defaults` を使用します。 ```json5 { @@ -91,11 +91,11 @@ Telegram、WhatsApp、Matrix、iMessage、およびその他の同梱チャン } ``` -- `channels.defaults.groupPolicy`: プロバイダーレベルの `groupPolicy` が未設定の場合のフォールバック用グループポリシー。 -- `channels.defaults.contextVisibility`: すべてのチャンネルに対する補足コンテキスト表示モードのデフォルト。値: `all`（デフォルト、引用/スレッド/履歴コンテキストをすべて含める）、`allowlist`（許可リストに含まれる送信者からのコンテキストのみ含める）、`allowlist_quote`（allowlist と同じだが、明示的な引用/返信コンテキストは保持する）。チャンネル別の上書き: `channels..contextVisibility`。 +- `channels.defaults.groupPolicy`: プロバイダーレベルの `groupPolicy` が未設定の場合のフォールバックグループポリシー。 +- `channels.defaults.contextVisibility`: すべてのチャンネルのデフォルト補足コンテキスト表示モード。値: `all`（デフォルト、すべての引用/スレッド/履歴コンテキストを含める）、`allowlist`（許可リスト内の送信者からのコンテキストのみを含める）、`allowlist_quote`（allowlist と同じだが、明示的な引用/返信コンテキストは保持）。チャンネル別上書き: `channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`: Heartbeat 出力に正常なチャンネルステータスを含める。 - `channels.defaults.heartbeat.showAlerts`: Heartbeat 出力に劣化/エラーステータスを含める。 -- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケータースタイルの Heartbeat 出力を描画する。 +- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケーター形式の Heartbeat 出力を描画する。 ### WhatsApp @@ -139,7 +139,7 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し } ``` - + ```json5 { @@ -157,9 +157,9 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し } ``` -- 送信コマンドは、存在する場合はアカウント `default` にデフォルトで送られます。存在しない場合は、設定済みアカウント ID の先頭（ソート済み）が使われます。 +- 送信コマンドは、存在する場合はアカウント `default` をデフォルトにします。それ以外の場合は、設定済みアカウント ID のうち最初のもの（ソート後）を使用します。 - 任意の `channels.whatsapp.defaultAccount` は、設定済みアカウント ID と一致する場合に、そのフォールバックのデフォルトアカウント選択を上書きします。 -- 従来の単一アカウント Baileys 認証ディレクトリは、`openclaw doctor` によって `whatsapp/default` へ移行されます。 +- レガシーの単一アカウント Baileys 認証ディレクトリは、`openclaw doctor` によって `whatsapp/default` に移行されます。 - アカウント別の上書き: `channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -219,13 +219,13 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し } ``` -- Bot トークン: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。シンボリックリンクは拒否）、デフォルトアカウントのフォールバックとして `TELEGRAM_BOT_TOKEN` を使用します。 -- `apiRoot` は Telegram Bot API のルートのみです。`https://api.telegram.org/bot` ではなく、`https://api.telegram.org` または自己ホスト/プロキシのルートを使用してください。`openclaw doctor --fix` は、誤って末尾に付いた `/bot` サフィックスを削除します。 -- 任意の `channels.telegram.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- マルチアカウント構成（2 つ以上のアカウント ID）では、フォールバックルーティングを避けるために明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定してください。これがない、または無効な場合、`openclaw doctor` が警告します。 +- ボットトークン: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。シンボリックリンクは拒否）。デフォルトアカウントのフォールバックとして `TELEGRAM_BOT_TOKEN` を使用します。 +- `apiRoot` は Telegram Bot API のルートのみです。`https://api.telegram.org/bot` ではなく、`https://api.telegram.org` または自前ホスト/プロキシのルートを使用してください。`openclaw doctor --fix` は、誤って付いた末尾の `/bot` サフィックスを削除します。 +- 任意の `channels.telegram.defaultAccount` は、設定済みアカウント ID と一致する場合に、デフォルトアカウント選択を上書きします。 +- 複数アカウント構成（2 個以上のアカウント ID）では、フォールバックルーティングを避けるために明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定します。これがない、または無効な場合、`openclaw doctor` が警告します。 - `configWrites: false` は、Telegram 起点の設定書き込み（スーパーグループ ID 移行、`/config set|unset`）をブロックします。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、フォーラムトピック用の永続的な ACP バインディングを設定します（`match.peer.id` では正規形式の `chatId:topic:topicId` を使用）。フィールドの意味は [ACP エージェント](/ja-JP/tools/acp-agents#channel-specific-settings)で共有されています。 -- Telegram ストリームプレビューは `sendMessage` + `editMessageText` を使用します（ダイレクトチャットとグループチャットで動作）。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、フォーラムトピック用の永続 ACP バインディングを設定します（`match.peer.id` では正規形式の `chatId:topic:topicId` を使用）。フィールドの意味は [ACP エージェント](/ja-JP/tools/acp-agents#channel-specific-settings)で共有されています。 +- Telegram ストリームプレビューは `sendMessage` + `editMessageText` を使用します（ダイレクトチャットとグループチャットで動作します）。 - リトライポリシー: [リトライポリシー](/ja-JP/concepts/retry)を参照してください。 ### Discord @@ -329,33 +329,33 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し ``` - トークン: `channels.discord.token`。デフォルトアカウントのフォールバックとして `DISCORD_BOT_TOKEN` を使用します。 -- 明示的な Discord `token` を提供する直接の送信呼び出しは、その呼び出しにそのトークンを使用します。アカウントの再試行/ポリシー設定は、引き続きアクティブなランタイムスナップショット内で選択されたアカウントから取得されます。 -- 任意の `channels.discord.defaultAccount` は、構成済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- 配信ターゲットには `user:` (DM) または `channel:` (ギルドチャンネル) を使用します。裸の数値 ID は拒否されます。 -- ギルドスラッグは小文字で、空白は `-` に置換されます。チャンネルキーにはスラッグ化された名前を使用します (`#` なし)。ギルド ID を推奨します。 -- ボットが作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効化します。ボットにメンションしているボットメッセージのみを受け付けるには `allowBots: "mentions"` を使用します (自身のメッセージは引き続きフィルターされます)。 -- `channels.discord.guilds..ignoreOtherMentions` (およびチャンネル上書き) は、ボットではなく別のユーザーまたはロールにメンションしているメッセージを破棄します (@everyone/@here を除く)。 +- 明示的な Discord `token` を指定する直接アウトバウンド呼び出しは、その呼び出しにそのトークンを使用します。アカウントの再試行/ポリシー設定は、引き続きアクティブなランタイムスナップショットで選択されたアカウントから取得されます。 +- 任意の `channels.discord.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウントの選択を上書きします。 +- 配信先には `user:` (DM) または `channel:` (ギルドチャンネル) を使用します。裸の数値 ID は拒否されます。 +- ギルドスラッグは小文字で、空白は `-` に置換されます。チャンネルキーはスラッグ化された名前 (`#` なし) を使用します。ギルド ID を推奨します。 +- ボットが作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効になります。ボットにメンションするボットメッセージだけを受け付けるには `allowBots: "mentions"` を使用します (自身のメッセージは引き続きフィルタされます)。 +- `channels.discord.guilds..ignoreOtherMentions` (およびチャンネル上書き) は、別のユーザーまたはロールにメンションしているがボットにはメンションしていないメッセージを破棄します (@everyone/@here を除く)。 - `maxLinesPerMessage` (デフォルト 17) は、2000 文字未満でも縦に長いメッセージを分割します。 -- `channels.discord.threadBindings` は Discord のスレッドバインド型ルーティングを制御します。 - - `enabled`: スレッドバインド型セッション機能 (`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインドされた配信/ルーティング) に対する Discord 上書き - - `idleHours`: 非アクティブ時の自動アンフォーカスまでの時間 (時間単位) に対する Discord 上書き (`0` で無効) - - `maxAgeHours`: ハード最大有効期間 (時間単位) に対する Discord 上書き (`0` で無効) - - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` の自動スレッド作成/バインド用のオプトインスイッチ -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、チャンネルとスレッド用の永続 ACP バインディングを構成します (`match.peer.id` にはチャンネル/スレッド ID を使用)。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) で共有されています。 -- `channels.discord.ui.components.accentColor` は、Discord components v2 コンテナのアクセントカラーを設定します。 -- `channels.discord.voice` は、Discord ボイスチャンネル会話と、任意の自動参加 + LLM + TTS 上書きを有効化します。 +- `channels.discord.threadBindings` は Discord のスレッドバインド型ルーティングを制御します: + - `enabled`: スレッドバインド型セッション機能 (`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインドされた配信/ルーティング) の Discord 上書き + - `idleHours`: 非アクティブ時の自動フォーカス解除の Discord 上書き (時間単位、`0` で無効) + - `maxAgeHours`: ハード最大期間の Discord 上書き (時間単位、`0` で無効) + - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` による自動スレッド作成/バインドのオプトインスイッチ +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、チャンネルとスレッド用の永続的な ACP バインディングを設定します (`match.peer.id` にはチャンネル/スレッド ID を使用します)。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) で共有されています。 +- `channels.discord.ui.components.accentColor` は Discord コンポーネント v2 コンテナのアクセントカラーを設定します。 +- `channels.discord.voice` は Discord ボイスチャンネル会話と、任意の自動参加 + LLM + TTS 上書きを有効にします。 - `channels.discord.voice.model` は、Discord ボイスチャンネル応答に使用する LLM モデルを任意で上書きします。 - `channels.discord.voice.daveEncryption` と `channels.discord.voice.decryptionFailureTolerance` は、`@discordjs/voice` の DAVE オプションにそのまま渡されます (デフォルトは `true` と `24`)。 -- OpenClaw はさらに、復号失敗が繰り返された後にボイスセッションを退出/再参加することで、ボイス受信の回復を試みます。 +- OpenClaw はさらに、復号失敗が繰り返された後にボイスセッションから退出/再参加することで、ボイス受信の復旧を試みます。 - `channels.discord.streaming` は正規のストリームモードキーです。レガシーの `streamMode` と真偽値の `streaming` 値は自動移行されます。 -- `channels.discord.autoPresence` はランタイム可用性をボットプレゼンスにマップし (healthy => online, degraded => idle, exhausted => dnd)、任意のステータステキスト上書きを許可します。 -- `channels.discord.dangerouslyAllowNameMatching` は、可変の名前/タグ照合を再有効化します (緊急互換モード)。 +- `channels.discord.autoPresence` はランタイムの可用性をボットプレゼンスに対応付け (healthy => online、degraded => idle、exhausted => dnd)、任意のステータステキスト上書きを許可します。 +- `channels.discord.dangerouslyAllowNameMatching` は、可変の名前/タグ照合を再度有効にします (緊急互換モード)。 - `channels.discord.execApprovals`: Discord ネイティブの exec 承認配信と承認者認可。 - - `enabled`: `true`、`false`、または `"auto"` (デフォルト)。自動モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効化されます。 + - `enabled`: `true`、`false`、または `"auto"` (デフォルト)。自動モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効になります。 - `approvers`: exec リクエストの承認を許可された Discord ユーザー ID。省略時は `commands.ownerAllowFrom` にフォールバックします。 - `agentFilter`: 任意のエージェント ID 許可リスト。すべてのエージェントの承認を転送するには省略します。 - `sessionFilter`: 任意のセッションキーパターン (部分文字列または正規表現)。 - - `target`: 承認プロンプトの送信先。`"dm"` (デフォルト) は承認者 DM に送信し、`"channel"` は発信元チャンネルに送信し、`"both"` は両方に送信します。ターゲットに `"channel"` が含まれる場合、ボタンは解決済みの承認者のみが使用できます。 + - `target`: 承認プロンプトの送信先。`"dm"` (デフォルト) は承認者の DM に送信し、`"channel"` は発信元チャンネルに送信し、`"both"` は両方に送信します。target に `"channel"` が含まれる場合、ボタンは解決済みの承認者のみ使用できます。 - `cleanupAfterResolve`: `true` の場合、承認、拒否、またはタイムアウト後に承認 DM を削除します。 **リアクション通知モード:** `off` (なし)、`own` (ボットのメッセージ、デフォルト)、`all` (すべてのメッセージ)、`allowlist` (すべてのメッセージで `guilds..users` から)。 @@ -392,8 +392,8 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し - サービスアカウント JSON: インライン (`serviceAccount`) またはファイルベース (`serviceAccountFile`)。 - サービスアカウント SecretRef もサポートされています (`serviceAccountRef`)。 - 環境変数フォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 配信ターゲットには `spaces/` または `users/` を使用します。 -- `channels.googlechat.dangerouslyAllowNameMatching` は、可変のメールプリンシパル照合を再有効化します (緊急互換モード)。 +- 配信先には `spaces/` または `users/` を使用します。 +- `channels.googlechat.dangerouslyAllowNameMatching` は、可変のメールプリンシパル照合を再度有効にします (緊急互換モード)。 ### Slack @@ -465,35 +465,35 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し } ``` -- **Socket mode** には `botToken` と `appToken` の両方が必要です (デフォルトアカウントの環境変数フォールバックには `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`)。 -- **HTTP mode** には `botToken` と `signingSecret` (ルートまたはアカウントごと) が必要です。 -- `socketMode` は、Slack SDK Socket Mode トランスポート調整を公開 Bolt receiver API にそのまま渡します。ping/pong タイムアウトまたは古い websocket 動作を調査する場合にのみ使用してください。 -- `botToken`、`appToken`、`signingSecret`、`userToken` はプレーンテキスト文字列または SecretRef オブジェクトを受け付けます。 -- Slack アカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、および HTTP mode の `signingSecretStatus` など、認証情報ごとのソース/ステータスフィールドを公開します。`configured_unavailable` は、アカウントが SecretRef 経由で構成されているものの、現在のコマンド/ランタイムパスでシークレット値を解決できなかったことを意味します。 -- `configWrites: false` は、Slack から開始される構成書き込みをブロックします。 -- 任意の `channels.slack.defaultAccount` は、構成済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 +- **ソケットモード** には `botToken` と `appToken` の両方が必要です (デフォルトアカウントの環境変数フォールバックは `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`)。 +- **HTTP モード** には `botToken` と `signingSecret` (ルートまたはアカウントごと) が必要です。 +- `socketMode` は Slack SDK のソケットモードトランスポート調整を公開 Bolt レシーバー API にそのまま渡します。ping/pong タイムアウトや古い websocket 挙動を調査する場合にのみ使用します。 +- `botToken`、`appToken`、`signingSecret`、`userToken` は、平文文字列または SecretRef オブジェクトを受け付けます。 +- Slack アカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、および HTTP モードでは `signingSecretStatus` など、認証情報ごとのソース/ステータスフィールドを公開します。`configured_unavailable` は、そのアカウントが SecretRef で設定されているものの、現在のコマンド/ランタイムパスでシークレット値を解決できなかったことを意味します。 +- `configWrites: false` は Slack 起点の設定書き込みをブロックします。 +- 任意の `channels.slack.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウントの選択を上書きします。 - `channels.slack.streaming.mode` は正規の Slack ストリームモードキーです。`channels.slack.streaming.nativeTransport` は Slack のネイティブストリーミングトランスポートを制御します。レガシーの `streamMode`、真偽値の `streaming`、および `nativeStreaming` 値は自動移行されます。 -- 配信ターゲットには `user:` (DM) または `channel:` を使用します。 +- 配信先には `user:` (DM) または `channel:` を使用します。 **リアクション通知モード:** `off`、`own` (デフォルト)、`all`、`allowlist` (`reactionAllowlist` から)。 -**スレッドセッション分離:** `thread.historyScope` はスレッドごと (デフォルト) またはチャンネル全体で共有です。`thread.inheritParent` は親チャンネルのトランスクリプトを新しいスレッドにコピーします。 +**スレッドセッション分離:** `thread.historyScope` はスレッドごと (デフォルト) またはチャンネル全体で共有されます。`thread.inheritParent` は親チャンネルのトランスクリプトを新しいスレッドにコピーします。 -- Slack ネイティブストリーミングと Slack アシスタント風の「is typing...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベル DM はデフォルトでスレッド外のままなので、スレッド形式のプレビューではなく `typingReaction` または通常配信を使用します。 -- `typingReaction` は、返信の実行中に受信 Slack メッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` のような Slack 絵文字ショートコードを使用してください。 -- `channels.slack.execApprovals`: Slack ネイティブの exec 承認配信と承認者認可。Discord と同じスキーマです: `enabled` (`true`/`false`/`"auto"`)、`approvers` (Slack ユーザー ID)、`agentFilter`、`sessionFilter`、および `target` (`"dm"`、`"channel"`、または `"both"`)。 +- Slack ネイティブストリーミングと Slack アシスタント風の「入力中...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベルの DM はデフォルトでスレッド外のままなので、スレッド風プレビューの代わりに `typingReaction` または通常の配信を使用します。 +- `typingReaction` は、返信の実行中に受信 Slack メッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` などの Slack 絵文字ショートコードを使用します。 +- `channels.slack.execApprovals`: Slack ネイティブの exec 承認配信と承認者認可。Discord と同じスキーマです: `enabled` (`true`/`false`/`"auto"`)、`approvers` (Slack ユーザー ID)、`agentFilter`、`sessionFilter`、`target` (`"dm"`、`"channel"`、または `"both"`)。 -| アクショングループ | デフォルト | 注記 | +| アクショングループ | デフォルト | 注記 | | ------------ | ------- | ---------------------- | | reactions | 有効 | リアクション + リアクション一覧 | -| messages | 有効 | 読み取り/送信/編集/削除 | -| pins | 有効 | ピン留め/ピン解除/一覧 | -| memberInfo | 有効 | メンバー情報 | -| emojiList | 有効 | カスタム絵文字一覧 | +| messages | 有効 | 読み取り/送信/編集/削除 | +| pins | 有効 | ピン留め/ピン解除/一覧 | +| memberInfo | 有効 | メンバー情報 | +| emojiList | 有効 | カスタム絵文字一覧 | ### Mattermost -Mattermost は現在の OpenClaw リリースではバンドルされた Plugin として提供されています。古いビルドまたはカスタムビルドでは、`openclaw plugins install @openclaw/mattermost` で現在の npm パッケージをインストールできます。npm が OpenClaw 所有のパッケージを非推奨として報告する場合は、新しい npm パッケージが公開されるまで、バンドルされた Plugin またはローカルチェックアウトを使用してください。 +Mattermost は現在の OpenClaw リリースではバンドル Plugin として同梱されています。古いビルドやカスタムビルドでは、`openclaw plugins install @openclaw/mattermost` で現在の npm パッケージをインストールできます。npm が OpenClaw 所有のパッケージを非推奨として報告する場合は、新しい npm パッケージが公開されるまで、バンドル Plugin またはローカルチェックアウトを使用してください。 ```json5 { @@ -527,14 +527,14 @@ Mattermost は現在の OpenClaw リリースではバンドルされた Plugin Mattermost ネイティブコマンドが有効な場合: -- `commands.callbackPath` はフル URL ではなく、パス (例: `/api/channels/mattermost/command`) でなければなりません。 -- `commands.callbackUrl` は OpenClaw Gateway エンドポイントに解決され、Mattermost サーバーから到達可能でなければなりません。 -- ネイティブスラッシュコールバックは、スラッシュコマンド登録中に Mattermost から返されるコマンドごとのトークンで認証されます。登録に失敗した場合、または有効化されたコマンドがない場合、OpenClaw は `Unauthorized: invalid command token.` でコールバックを拒否します。 -- private/tailnet/internal コールバックホストでは、Mattermost が `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含めることを要求する場合があります。フル URL ではなく、ホスト/ドメイン値を使用してください。 -- `channels.mattermost.configWrites`: Mattermost から開始される構成書き込みを許可または拒否します。 +- `commands.callbackPath` は完全な URL ではなく、パス (例: `/api/channels/mattermost/command`) である必要があります。 +- `commands.callbackUrl` は OpenClaw Gateway エンドポイントに解決され、Mattermost サーバーから到達可能である必要があります。 +- ネイティブスラッシュコールバックは、スラッシュコマンド登録中に Mattermost が返すコマンドごとのトークンで認証されます。登録に失敗した場合、または有効化されたコマンドがない場合、OpenClaw は `Unauthorized: invalid command token.` でコールバックを拒否します。 +- プライベート/tailnet/内部コールバックホストでは、Mattermost が `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含めることを要求する場合があります。完全な URL ではなく、ホスト/ドメイン値を使用してください。 +- `channels.mattermost.configWrites`: Mattermost 起点の設定書き込みを許可または拒否します。 - `channels.mattermost.requireMention`: チャンネルで返信する前に `@mention` を要求します。 -- `channels.mattermost.groups..requireMention`: チャンネルごとのメンションゲート上書き (デフォルトには `"*"` )。 -- 任意の `channels.mattermost.defaultAccount` は、構成済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 +- `channels.mattermost.groups..requireMention`: チャンネルごとのメンションゲート上書き (デフォルトは `"*"`)。 +- 任意の `channels.mattermost.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウントの選択を上書きします。 ### Signal @@ -555,15 +555,15 @@ Mattermost ネイティブコマンドが有効な場合: } ``` -**リアクション通知モード:** `off`、`own` (デフォルト)、`all`、`allowlist` (`reactionAllowlist` から)。 +**リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 - `channels.signal.account`: チャンネル起動を特定の Signal アカウント ID に固定します。 -- `channels.signal.configWrites`: Signal から開始された設定の書き込みを許可または拒否します。 +- `channels.signal.configWrites`: Signal から開始される設定書き込みを許可または拒否します。 - 任意の `channels.signal.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトのアカウント選択を上書きします。 ### BlueBubbles -BlueBubbles は推奨される iMessage 経路です (Plugin ベースで、`channels.bluebubbles` の下で設定します)。 +BlueBubbles は推奨される iMessage 経路です（Plugin が支え、`channels.bluebubbles` 配下で設定されます）。 ```json5 { @@ -578,14 +578,14 @@ BlueBubbles は推奨される iMessage 経路です (Plugin ベースで、`cha } ``` -- ここで扱うコアキーのパス: `channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 +- ここで扱うコアキーパス: `channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 - 任意の `channels.bluebubbles.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトのアカウント選択を上書きします。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続的な ACP セッションにバインドできます。`match.peer.id` では BlueBubbles ハンドルまたはターゲット文字列 (`chat_id:*`、`chat_guid:*`、`chat_identifier:*`) を使用します。共有フィールドのセマンティクス: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続 ACP セッションにバインドできます。`match.peer.id` では BlueBubbles ハンドルまたはターゲット文字列（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共有フィールドのセマンティクス: [ACP エージェント](/ja-JP/tools/acp-agents#channel-specific-settings)。 - 完全な BlueBubbles チャンネル設定は [BlueBubbles](/ja-JP/channels/bluebubbles) に記載されています。 ### iMessage -OpenClaw は `imsg rpc` (stdio 上の JSON-RPC) を起動します。デーモンやポートは不要です。 +OpenClaw は `imsg rpc`（stdio 経由の JSON-RPC）を起動します。デーモンやポートは不要です。 ```json5 { @@ -612,12 +612,12 @@ OpenClaw は `imsg rpc` (stdio 上の JSON-RPC) を起動します。デーモ - 任意の `channels.imessage.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトのアカウント選択を上書きします。 - Messages DB へのフルディスクアクセスが必要です。 -- `chat_id:` ターゲットを推奨します。チャットの一覧表示には `imsg chats --limit 20` を使用します。 -- `cliPath` は SSH ラッパーを指すことができます。SCP による添付ファイル取得には `remoteHost` (`host` または `user@host`) を設定します。 -- `attachmentRoots` と `remoteAttachmentRoots` は受信添付ファイルのパスを制限します (デフォルト: `/Users/*/Library/Messages/Attachments`)。 -- SCP は厳格なホストキー確認を使用するため、リレーホストのキーがすでに `~/.ssh/known_hosts` に存在することを確認してください。 -- `channels.imessage.configWrites`: iMessage から開始された設定の書き込みを許可または拒否します。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続的な ACP セッションにバインドできます。`match.peer.id` では正規化済みハンドルまたは明示的なチャットターゲット (`chat_id:*`、`chat_guid:*`、`chat_identifier:*`) を使用します。共有フィールドのセマンティクス: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 +- `chat_id:` ターゲットを優先します。チャット一覧を表示するには `imsg chats --limit 20` を使用します。 +- `cliPath` は SSH ラッパーを指すことができます。SCP による添付ファイル取得には `remoteHost`（`host` または `user@host`）を設定します。 +- `attachmentRoots` と `remoteAttachmentRoots` は受信添付ファイルのパスを制限します（デフォルト: `/Users/*/Library/Messages/Attachments`）。 +- SCP は厳密なホストキー検証を使用するため、リレーホストキーがすでに `~/.ssh/known_hosts` に存在することを確認してください。 +- `channels.imessage.configWrites`: iMessage から開始される設定書き込みを許可または拒否します。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続 ACP セッションにバインドできます。正規化済みハンドルまたは明示的なチャットターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を `match.peer.id` で使用します。共有フィールドのセマンティクス: [ACP エージェント](/ja-JP/tools/acp-agents#channel-specific-settings)。 @@ -630,7 +630,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix は Plugin ベースで、`channels.matrix` の下で設定します。 +Matrix は Plugin が支え、`channels.matrix` 配下で設定されます。 ```json5 { @@ -661,24 +661,24 @@ Matrix は Plugin ベースで、`channels.matrix` の下で設定します。 ``` - トークン認証は `accessToken` を使用します。パスワード認証は `userId` + `password` を使用します。 -- `channels.matrix.proxy` は Matrix の HTTP トラフィックを明示的な HTTP(S) プロキシ経由でルーティングします。名前付きアカウントでは `channels.matrix.accounts..proxy` で上書きできます。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` はプライベート/内部 homeserver を許可します。`proxy` とこのネットワークのオプトインは独立した制御です。 -- `channels.matrix.defaultAccount` は、マルチアカウント設定で優先アカウントを選択します。 -- `channels.matrix.autoJoin` のデフォルトは `off` なので、招待されたルームと新しい DM 形式の招待は、`autoJoinAllowlist` を指定して `autoJoin: "allowlist"` を設定するか、`autoJoin: "always"` を設定するまで無視されます。 +- `channels.matrix.proxy` は Matrix HTTP トラフィックを明示的な HTTP(S) プロキシ経由でルーティングします。名前付きアカウントは `channels.matrix.accounts..proxy` で上書きできます。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` はプライベート/内部ホームサーバーを許可します。`proxy` とこのネットワークオプトインは独立した制御です。 +- `channels.matrix.defaultAccount` は、複数アカウント構成で優先アカウントを選択します。 +- `channels.matrix.autoJoin` のデフォルトは `off` です。そのため、招待されたルームや新しい DM 風の招待は、`autoJoinAllowlist` 付きで `autoJoin: "allowlist"` を設定するか `autoJoin: "always"` を設定するまで無視されます。 - `channels.matrix.execApprovals`: Matrix ネイティブの exec 承認配信と承認者認可。 - - `enabled`: `true`、`false`、または `"auto"` (デフォルト)。auto モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効になります。 - - `approvers`: exec リクエストの承認を許可された Matrix ユーザー ID (例: `@owner:example.org`)。 + - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。自動モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効になります。 + - `approvers`: exec リクエストの承認を許可された Matrix ユーザー ID（例: `@owner:example.org`）。 - `agentFilter`: 任意のエージェント ID 許可リスト。省略すると、すべてのエージェントの承認を転送します。 - - `sessionFilter`: 任意のセッションキーパターン (部分文字列または正規表現)。 - - `target`: 承認プロンプトの送信先。`"dm"` (デフォルト)、`"channel"` (送信元ルーム)、または `"both"`。 - - アカウント単位の上書き: `channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` は、Matrix DM をセッションにグループ化する方法を制御します。`per-user` (デフォルト) はルーティングされたピアごとに共有し、`per-room` は各 DM ルームを分離します。 -- Matrix のステータスプローブとライブディレクトリ検索は、ランタイムトラフィックと同じプロキシポリシーを使用します。 -- 完全な Matrix 設定、ターゲット指定ルール、セットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 + - `sessionFilter`: 任意のセッションキーパターン（部分文字列または正規表現）。 + - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）、`"channel"`（発信元ルーム）、または `"both"`。 + - アカウントごとの上書き: `channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` は Matrix DM をセッションにグループ化する方法を制御します。`per-user`（デフォルト）はルーティングされた相手ごとに共有し、`per-room` は各 DM ルームを分離します。 +- Matrix ステータスプローブとライブディレクトリ検索は、ランタイムトラフィックと同じプロキシポリシーを使用します。 +- 完全な Matrix 設定、ターゲティングルール、セットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 ### Microsoft Teams -Microsoft Teams は Plugin ベースで、`channels.msteams` の下で設定します。 +Microsoft Teams は Plugin が支え、`channels.msteams` 配下で設定されます。 ```json5 { @@ -693,12 +693,12 @@ Microsoft Teams は Plugin ベースで、`channels.msteams` の下で設定し } ``` -- ここで扱うコアキーのパス: `channels.msteams`、`channels.msteams.configWrites`。 -- 完全な Teams 設定 (認証情報、Webhook、DM/グループポリシー、チーム単位/チャンネル単位の上書き) は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 +- ここで扱うコアキーパス: `channels.msteams`、`channels.msteams.configWrites`。 +- 完全な Teams 設定（資格情報、Webhook、DM/グループポリシー、チーム別/チャンネル別の上書き）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 ### IRC -IRC は Plugin ベースで、`channels.irc` の下で設定します。 +IRC は Plugin が支え、`channels.irc` 配下で設定されます。 ```json5 { @@ -719,13 +719,13 @@ IRC は Plugin ベースで、`channels.irc` の下で設定します。 } ``` -- ここで扱うコアキーのパス: `channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 +- ここで扱うコアキーパス: `channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 - 任意の `channels.irc.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトのアカウント選択を上書きします。 -- 完全な IRC チャンネル設定 (ホスト/ポート/TLS/チャンネル/許可リスト/メンションゲート) は [IRC](/ja-JP/channels/irc) に記載されています。 +- 完全な IRC チャンネル設定（ホスト/ポート/TLS/チャンネル/許可リスト/メンションゲート）は [IRC](/ja-JP/channels/irc) に記載されています。 -### マルチアカウント (すべてのチャンネル) +### 複数アカウント（すべてのチャンネル） -チャンネルごとに複数のアカウントを実行します (各アカウントは独自の `accountId` を持ちます)。 +チャンネルごとに複数のアカウントを実行します（それぞれ独自の `accountId` を持ちます）。 ```json5 { @@ -746,32 +746,34 @@ IRC は Plugin ベースで、`channels.irc` の下で設定します。 } ``` -- `accountId` が省略された場合は `default` が使用されます (CLI + ルーティング)。 +- `accountId` が省略された場合は `default` が使用されます（CLI + ルーティング）。 - 環境変数トークンは **デフォルト** アカウントにのみ適用されます。 -- ベースチャンネル設定は、アカウント単位で上書きされない限り、すべてのアカウントに適用されます。 -- 各アカウントを別のエージェントにルーティングするには `bindings[].match.accountId` を使用します。 -- 単一アカウントのトップレベルチャンネル設定のまま `openclaw channels add` (またはチャンネルのオンボーディング) で非デフォルトアカウントを追加した場合、OpenClaw はまず、アカウントスコープのトップレベル単一アカウント値をそのチャンネルのアカウントマップに昇格させ、元のアカウントが引き続き動作するようにします。ほとんどのチャンネルではそれらを `channels..accounts.default` に移動します。Matrix では、代わりに既存の一致する名前付き/デフォルトターゲットを保持できます。 -- 既存のチャンネルのみのバインディング (`accountId` なし) はデフォルトアカウントとの照合を継続します。アカウントスコープのバインディングは引き続き任意です。 -- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値を、そのチャンネルで選択された昇格先アカウントへ移動することで混在形状を修復します。ほとんどのチャンネルでは `accounts.default` を使用します。Matrix では、代わりに既存の一致する名前付き/デフォルトターゲットを保持できます。 +- ベースチャンネル設定は、アカウントごとに上書きされない限りすべてのアカウントに適用されます。 +- 各アカウントを別のエージェントへルーティングするには `bindings[].match.accountId` を使用します。 +- 単一アカウントのトップレベルチャンネル設定のまま `openclaw channels add`（またはチャンネルオンボーディング）で非デフォルトアカウントを追加すると、OpenClaw はまずアカウントスコープのトップレベル単一アカウント値をチャンネルのアカウントマップへ昇格し、元のアカウントが動作し続けるようにします。ほとんどのチャンネルではそれらを `channels..accounts.default` に移動します。Matrix では既存の一致する名前付き/デフォルトターゲットを保持できる場合があります。 +- 既存のチャンネルのみのバインディング（`accountId` なし）は、引き続きデフォルトアカウントに一致します。アカウントスコープのバインディングは引き続き任意です。 +- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値をそのチャンネルで選ばれた昇格先アカウントへ移動することで混在形状を修復します。ほとんどのチャンネルは `accounts.default` を使用します。Matrix では既存の一致する名前付き/デフォルトターゲットを保持できる場合があります。 ### その他の Plugin チャンネル -多くの Plugin チャンネルは `channels.` として設定され、専用のチャンネルページに記載されています (例: Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch)。 +多くの Plugin チャンネルは `channels.` として設定され、それぞれ専用のチャンネルページに記載されています（例: Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 完全なチャンネルインデックスを参照してください: [チャンネル](/ja-JP/channels)。 ### グループチャットのメンションゲート -グループメッセージのデフォルトは **メンション必須** (メタデータメンションまたは安全な正規表現パターン) です。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。 +グループメッセージのデフォルトは **メンション必須**（メタデータメンションまたは安全な正規表現パターン）です。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。 -表示される返信は別に制御されます。グループ/チャンネルルームのデフォルトは `messages.groupChat.visibleReplies: "message_tool"` です。OpenClaw は引き続きターンを処理しますが、通常の最終返信は非公開のままで、ルームに表示される出力には `message(action=send)` が必要です。通常の返信をルームに投稿する従来の挙動が必要な場合にのみ `"automatic"` を設定します。同じツールのみの表示返信の挙動を直接チャットにも適用するには、`messages.visibleReplies: "message_tool"` を設定します。 +表示返信は別に制御されます。グループ/チャンネルルームのデフォルトは `messages.groupChat.visibleReplies: "message_tool"` です。OpenClaw は引き続きターンを処理しますが、通常の最終返信はプライベートのままで、ルームに表示される出力には `message(action=send)` が必要です。通常の返信をルームへ投稿する従来の動作が必要な場合にのみ `"automatic"` を設定してください。同じツールのみの表示返信動作を直接チャットにも適用するには、`messages.visibleReplies: "message_tool"` を設定します。 -Gateway は、ファイル保存後に `messages` 設定をホットリロードします。デプロイでファイル監視または設定リロードが無効化されている場合にのみ再起動してください。 +アクティブなツールポリシーの下でメッセージツールが利用できない場合、OpenClaw はレスポンスを黙って抑制するのではなく、自動表示返信にフォールバックします。`openclaw doctor` はこの不一致について警告します。 -**メンションタイプ:** +Gateway はファイル保存後に `messages` 設定をホットリロードします。デプロイでファイル監視または設定リロードが無効な場合にのみ再起動してください。 -- **メタデータメンション**: ネイティブプラットフォームの @メンション。WhatsApp のセルフチャットモードでは無視されます。 -- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` 内の安全な正規表現パターン。無効なパターンと安全でない入れ子の繰り返しは無視されます。 -- メンションゲートは、検出が可能な場合 (ネイティブメンションまたは少なくとも 1 つのパターン) にのみ適用されます。 +**メンションの種類:** + +- **メタデータメンション**: ネイティブプラットフォームの @ メンション。WhatsApp のセルフチャットモードでは無視されます。 +- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` の安全な正規表現パターン。無効なパターンと安全でないネストした繰り返しは無視されます。 +- メンションゲートは、検出が可能な場合（ネイティブメンションまたは少なくとも 1 つのパターンがある場合）にのみ強制されます。 ```json5 { @@ -788,9 +790,9 @@ Gateway は、ファイル保存後に `messages` 設定をホットリロード } ``` -`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。チャンネルは `channels..historyLimit` (またはアカウント単位) で上書きできます。無効化するには `0` を設定します。 +`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。チャンネルは `channels..historyLimit`（またはアカウントごと）で上書きできます。無効にするには `0` を設定します。 -`messages.visibleReplies` はグローバルなソースターンのデフォルトです。`messages.groupChat.visibleReplies` は、グループ/チャンネルのソースターンでこれを上書きします。チャンネル許可リストとメンションゲートは、ターンを処理するかどうかを引き続き決定します。 +`messages.visibleReplies` はグローバルなソースターンのデフォルトです。`messages.groupChat.visibleReplies` はグループ/チャンネルのソースターンについてそれを上書きします。チャンネル許可リストとメンションゲートは、ターンを処理するかどうかを引き続き決定します。 #### DM 履歴制限 @@ -807,13 +809,13 @@ Gateway は、ファイル保存後に `messages` 設定をホットリロード } ``` -解決順序: DM 単位の上書き → プロバイダーのデフォルト → 制限なし (すべて保持)。 +解決順序: DM ごとの上書き → プロバイダーデフォルト → 制限なし（すべて保持）。 対応: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### セルフチャットモード -セルフチャットモードを有効にするには、自分の電話番号を `allowFrom` に含めます (ネイティブ @メンションを無視し、テキストパターンにのみ応答します)。 +セルフチャットモードを有効にするには、自分の番号を `allowFrom` に含めます（ネイティブ @ メンションは無視し、テキストパターンにのみ応答します）。 ```json5 { @@ -834,7 +836,7 @@ Gateway は、ファイル保存後に `messages` 設定をホットリロード } ``` -### コマンド (チャットコマンド処理) +### コマンド（チャットコマンド処理） ```json5 { @@ -864,25 +866,25 @@ Gateway は、ファイル保存後に `messages` 設定をホットリロード - このブロックはコマンドサーフェスを設定します。現在の組み込み + バンドル済みコマンドカタログについては、[スラッシュコマンド](/ja-JP/tools/slash-commands)を参照してください。 -- このページは**設定キーのリファレンス**であり、完全なコマンドカタログではありません。QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、デバイスペアリング `/pair`、メモリ `/dreaming`、電話操作 `/phone`、Talk `/voice` など、チャンネル/Plugin 所有のコマンドは、それぞれのチャンネル/Plugin ページおよび[スラッシュコマンド](/ja-JP/tools/slash-commands)に記載されています。 -- テキストコマンドは、先頭に `/` が付いた**単独の**メッセージである必要があります。 +- このページは**設定キーリファレンス**であり、完全なコマンドカタログではありません。QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、デバイスペアリング `/pair`、メモリ `/dreaming`、電話制御 `/phone`、Talk `/voice` などのチャンネル/Plugin 所有コマンドは、それぞれのチャンネル/Plugin ページと [スラッシュコマンド](/ja-JP/tools/slash-commands)に記載されています。 +- テキストコマンドは、先頭に `/` を付けた**単独の**メッセージである必要があります。 - `native: "auto"` は Discord/Telegram のネイティブコマンドを有効にし、Slack は無効のままにします。 - `nativeSkills: "auto"` は Discord/Telegram のネイティブ Skills コマンドを有効にし、Slack は無効のままにします。 -- チャンネルごとの上書き: `channels.discord.commands.native`（bool または `"auto"`）。`false` は以前に登録されたコマンドを消去します。 -- `channels..commands.nativeSkills` でチャンネルごとのネイティブ Skills 登録を上書きします。 -- `channels.telegram.customCommands` は追加の Telegram bot メニューエントリを追加します。 -- `bash: true` はホストシェル向けの `! ` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.` に含まれていることが必要です。 -- `config: true` は `/config`（`openclaw.json` の読み書き）を有効にします。Gateway `chat.send` クライアントでは、永続的な `/config set|unset` の書き込みにも `operator.admin` が必要です。読み取り専用の `/config show` は、通常の書き込みスコープを持つ operator クライアントでも引き続き利用できます。 -- `mcp: true` は、`mcp.servers` 配下の OpenClaw 管理 MCP サーバー設定向けに `/mcp` を有効にします。 -- `plugins: true` は、Plugin の検出、インストール、有効化/無効化の制御向けに `/plugins` を有効にします。 -- `channels..configWrites` はチャンネルごとの設定変更を制御します（デフォルト: true）。 -- 複数アカウントのチャンネルでは、`channels..accounts..configWrites` も、そのアカウントを対象にする書き込みを制御します（例: `/allowlist --config --account ` または `/config set channels..accounts....`）。 -- `restart: false` は `/restart` と Gateway 再起動ツールのアクションを無効にします。デフォルト: `true`。 -- `ownerAllowFrom` は、所有者専用のコマンド/ツール向けの明示的な所有者 allowlist です。`allowFrom` とは別です。 +- チャンネルごとの上書き: `channels.discord.commands.native` (bool または `"auto"`)。`false` は以前に登録されたコマンドを消去します。 +- チャンネルごとのネイティブ Skills 登録は `channels..commands.nativeSkills` で上書きします。 +- `channels.telegram.customCommands` は追加の Telegram ボットメニュー項目を追加します。 +- `bash: true` はホストシェル用の `! ` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.` に含まれていることが必要です。 +- `config: true` は `/config` (`openclaw.json` の読み書き) を有効にします。Gateway `chat.send` クライアントでは、永続的な `/config set|unset` 書き込みには `operator.admin` も必要です。読み取り専用の `/config show` は通常の書き込みスコープ付き operator クライアントでも引き続き利用できます。 +- `mcp: true` は `mcp.servers` 配下の OpenClaw 管理 MCP サーバー設定用の `/mcp` を有効にします。 +- `plugins: true` は Plugin の検出、インストール、有効化/無効化コントロール用の `/plugins` を有効にします。 +- `channels..configWrites` はチャンネルごとの設定変更を制御します (デフォルト: true)。 +- マルチアカウントチャンネルでは、`channels..accounts..configWrites` も、そのアカウントを対象にした書き込みを制御します (例: `/allowlist --config --account ` または `/config set channels..accounts....`)。 +- `restart: false` は `/restart` と Gateway 再起動ツールアクションを無効にします。デフォルト: `true`。 +- `ownerAllowFrom` は所有者専用コマンド/ツールの明示的な所有者許可リストです。`allowFrom` とは別です。 - `ownerDisplay: "hash"` はシステムプロンプト内の所有者 ID をハッシュ化します。ハッシュ化を制御するには `ownerDisplaySecret` を設定します。 -- `allowFrom` はプロバイダーごとの設定です。設定されている場合、それが**唯一の**認可ソースになります（チャンネルの allowlist/ペアリングと `useAccessGroups` は無視されます）。 -- `useAccessGroups: false` は、`allowFrom` が設定されていない場合に、コマンドがアクセスグループポリシーをバイパスすることを許可します。 -- コマンドドキュメントの対応表: +- `allowFrom` はプロバイダーごとです。設定されている場合、これは**唯一の**認可ソースになります (チャンネル許可リスト/ペアリングと `useAccessGroups` は無視されます)。 +- `useAccessGroups: false` は、`allowFrom` が設定されていない場合に、コマンドがアクセスグループポリシーをバイパスできるようにします。 +- コマンドドキュメントマップ: - 組み込み + バンドル済みカタログ: [スラッシュコマンド](/ja-JP/tools/slash-commands) - チャンネル固有のコマンドサーフェス: [チャンネル](/ja-JP/channels) - QQ Bot コマンド: [QQ Bot](/ja-JP/channels/qqbot) diff --git a/docs/ja-JP/gateway/config-tools.md b/docs/ja-JP/gateway/config-tools.md index fbbe70300..e42217cd9 100644 --- a/docs/ja-JP/gateway/config-tools.md +++ b/docs/ja-JP/gateway/config-tools.md @@ -4,27 +4,27 @@ read_when: - カスタムプロバイダーの登録またはベース URL の上書き - OpenAI 互換のセルフホスト型エンドポイントの設定 sidebarTitle: Tools and custom providers -summary: ツール設定（ポリシー、実験的な切り替え、プロバイダー支援ツール）とカスタムプロバイダー/base-URL 設定 +summary: ツール設定（ポリシー、実験的なトグル、プロバイダー基盤のツール）とカスタムプロバイダー/ベース URL のセットアップ title: 設定 — ツールとカスタムプロバイダー x-i18n: - generated_at: "2026-04-30T05:11:44Z" + generated_at: "2026-05-01T05:01:12Z" model: gpt-5.5 provider: openai - source_hash: 1790c92ecaf822c837326d8e22e9d72cc44e5d4cc0bcc00c154ba5160975002a + source_hash: 97e6bd8c762f6f7a9985b99ec016dde22c8ea8adc925778b11c2ae5103b887a8 source_path: gateway/config-tools.md workflow: 16 --- -`tools.*` 設定キーとカスタムプロバイダー / base-URL 設定。エージェント、チャネル、その他のトップレベル設定キーについては、[設定リファレンス](/ja-JP/gateway/configuration-reference)を参照してください。 +`tools.*` 設定キーとカスタムプロバイダー / ベース URL 設定。エージェント、チャネル、その他のトップレベル設定キーについては、[設定リファレンス](/ja-JP/gateway/configuration-reference)を参照してください。 ## ツール ### ツールプロファイル -`tools.profile` は `tools.allow`/`tools.deny` の前に基本 allowlist を設定します。 +`tools.profile` は、`tools.allow`/`tools.deny` の前にベース許可リストを設定します。 -ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトを `tools.profile: "coding"` にします (既存の明示的なプロファイルは保持されます)。 +ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトが `tools.profile: "coding"` になります（既存の明示的なプロファイルは保持されます）。 | プロファイル | 含まれるもの | @@ -32,13 +32,13 @@ x-i18n: | `minimal` | `session_status` のみ | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | 制限なし (未設定と同じ) | +| `full` | 制限なし（未設定と同じ） | ### ツールグループ | グループ | ツール | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` は `exec` のエイリアスとして受け入れられます) | +| `group:runtime` | `exec`, `process`, `code_execution`（`bash` は `exec` のエイリアスとして受け付けられます） | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | @@ -49,11 +49,11 @@ x-i18n: | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | すべての組み込みツール (プロバイダー Plugin を除く) | +| `group:openclaw` | すべての組み込みツール（プロバイダー Plugin は除く） | ### `tools.allow` / `tools.deny` -グローバルなツールの許可/拒否ポリシー (拒否が優先)。大文字と小文字を区別せず、`*` ワイルドカードをサポートします。Docker サンドボックスがオフの場合でも適用されます。 +グローバルなツール許可/拒否ポリシー（拒否が優先）。大文字小文字を区別せず、`*` ワイルドカードをサポートします。Docker サンドボックスがオフでも適用されます。 ```json5 { @@ -63,7 +63,7 @@ x-i18n: ### `tools.byProvider` -特定のプロバイダーまたはモデルのツールをさらに制限します。順序: 基本プロファイル → プロバイダープロファイル → allow/deny。 +特定のプロバイダーまたはモデル向けにツールをさらに制限します。順序: ベースプロファイル → プロバイダープロファイル → 許可/拒否。 ```json5 { @@ -95,9 +95,9 @@ x-i18n: } ``` -- エージェントごとのオーバーライド (`agents.list[].tools.elevated`) は、さらに制限することしかできません。 +- エージェントごとの上書き（`agents.list[].tools.elevated`）では、さらに制限することしかできません。 - `/elevated on|off|ask|full` はセッションごとに状態を保存します。インラインディレクティブは単一メッセージに適用されます。 -- 昇格 `exec` はサンドボックスをバイパスし、設定済みのエスケープパスを使用します (デフォルトは `gateway`、または exec ターゲットが `node` の場合は `node`)。 +- 昇格 `exec` はサンドボックス化をバイパスし、設定されたエスケープパスを使用します（デフォルトは `gateway`、または exec ターゲットが `node` の場合は `node`）。 ### `tools.exec` @@ -121,7 +121,7 @@ x-i18n: ### `tools.loopDetection` -ツールループの安全チェックは**デフォルトで無効**です。検出を有効にするには `enabled: true` を設定してください。設定は `tools.loopDetection` でグローバルに定義でき、`agents.list[].tools.loopDetection` でエージェントごとにオーバーライドできます。 +ツールループの安全チェックは**デフォルトで無効**です。検出を有効にするには `enabled: true` を設定します。設定は `tools.loopDetection` でグローバルに定義でき、`agents.list[].tools.loopDetection` でエージェントごとに上書きできます。 ```json5 { @@ -146,22 +146,22 @@ x-i18n: ループ分析のために保持されるツール呼び出し履歴の最大数。 - 警告のための、進捗なしの繰り返しパターンしきい値。 + 警告対象となる、進捗のない繰り返しパターンのしきい値。 重大なループをブロックするための、より高い繰り返ししきい値。 - 進捗なしの実行に対する強制停止しきい値。 + 進捗のない実行をハード停止するしきい値。 同じツール/同じ引数の呼び出しが繰り返された場合に警告します。 - 既知のポーリングツール (`process.poll`, `command_status` など) で警告/ブロックします。 + 既知のポーリングツール（`process.poll`、`command_status` など）で警告/ブロックします。 - 進捗なしのペアが交互に現れるパターンで警告/ブロックします。 + 進捗のないペアが交互に繰り返されるパターンで警告/ブロックします。 @@ -200,7 +200,7 @@ x-i18n: ### `tools.media` -受信メディア理解（画像/音声/動画）を設定します。 +受信メディア理解（画像/音声/動画）を構成します。 ```json5 { @@ -208,7 +208,7 @@ x-i18n: media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // opt-in: send finished async video directly to the channel }, audio: { enabled: true, @@ -238,30 +238,30 @@ x-i18n: ``` - - **プロバイダーエントリ**（`type: "provider"` または省略）: + + **プロバイダーエントリー**（`type: "provider"` または省略）: - - `provider`: API プロバイダー ID（`openai`、`anthropic`、`google`/`gemini`、`groq` など） - - `model`: モデル ID のオーバーライド + - `provider`: APIプロバイダーID（`openai`、`anthropic`、`google`/`gemini`、`groq` など） + - `model`: モデルIDの上書き - `profile` / `preferredProfile`: `auth-profiles.json` プロファイルの選択 - **CLI エントリ**（`type: "cli"`）: + **CLIエントリー**（`type: "cli"`）: - `command`: 実行する実行可能ファイル - `args`: テンプレート化された引数（`{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` などをサポート。`openclaw doctor --fix` は非推奨の `{input}` プレースホルダーを `{{MediaPath}}` に移行します） **共通フィールド:** - - `capabilities`: 任意のリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → image、`google` → image+audio+video、`groq` → audio。 - - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリごとのオーバーライド。 - - `tools.media.image.timeoutSeconds` と対応する画像モデルの `timeoutSeconds` エントリは、エージェントが明示的な `image` ツールを呼び出す場合にも適用されます。 - - 失敗時は次のエントリにフォールバックします。 + - `capabilities`: 任意のリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → 画像、`google` → 画像+音声+動画、`groq` → 音声。 + - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリーごとの上書き。 + - `tools.media.image.timeoutSeconds` と対応する画像モデルの `timeoutSeconds` エントリーは、エージェントが明示的な `image` ツールを呼び出す場合にも適用されます。 + - 失敗すると次のエントリーにフォールバックします。 プロバイダー認証は標準の順序に従います: `auth-profiles.json` → 環境変数 → `models.providers.*.apiKey`。 **非同期完了フィールド:** - - `asyncCompletion.directSend`: `true` の場合、完了した非同期 `music_generate` と `video_generate` タスクは、まずチャンネルへの直接配信を試みます。デフォルト: `false`（従来のリクエスターセッション wake/model-delivery パス）。 + - `asyncCompletion.directSend`: `true` の場合、直接完了配信をサポートする完了済みの非同期メディアタスクは、まずチャンネルへの直接配信を試みます。デフォルト: `false`（リクエスターセッションのウェイク/モデル配信パス）。現在これは非同期 `video_generate` に適用されます。非同期 `music_generate` の完了は、これが有効な場合でもリクエスターセッション経由のままです。 @@ -281,9 +281,9 @@ x-i18n: ### `tools.sessions` -セッションツール（`sessions_list`、`sessions_history`、`sessions_send`）で対象にできるセッションを制御します。 +セッションツール（`sessions_list`、`sessions_history`、`sessions_send`）でターゲットにできるセッションを制御します。 -デフォルト: `tree`（現在のセッション + そこから生成されたセッション、サブエージェントなど）。 +デフォルト: `tree`（現在のセッション + サブエージェントなど、それによって生成されたセッション）。 ```json5 { @@ -297,12 +297,12 @@ x-i18n: ``` - + - `self`: 現在のセッションキーのみ。 - - `tree`: 現在のセッション + 現在のセッションから生成されたセッション（サブエージェント）。 - - `agent`: 現在のエージェント ID に属する任意のセッション（同じエージェント ID の下で送信者ごとのセッションを実行している場合、他のユーザーを含むことがあります）。 - - `all`: 任意のセッション。エージェント間のターゲット指定には、引き続き `tools.agentToAgent` が必要です。 - - サンドボックスの制限: 現在のセッションがサンドボックス化され、`agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` であっても可視性は強制的に `tree` になります。 + - `tree`: 現在のセッション + 現在のセッションによって生成されたセッション（サブエージェント）。 + - `agent`: 現在のエージェントIDに属する任意のセッション（同じエージェントIDの下で送信者ごとのセッションを実行している場合、他のユーザーを含むことがあります）。 + - `all`: 任意のセッション。エージェント間のターゲット指定には引き続き `tools.agentToAgent` が必要です。 + - サンドボックスによる制限: 現在のセッションがサンドボックス化され、`agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` であっても可視性は `tree` に強制されます。 @@ -328,13 +328,13 @@ x-i18n: ``` - - - 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACP ランタイムでは拒否されます。 + + - 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACPランタイムは添付ファイルを拒否します。 - ファイルは子ワークスペースの `.openclaw/attachments//` に `.manifest.json` とともに実体化されます。 - - 添付ファイルの内容は、トランスクリプト永続化から自動的にリダクションされます。 - - Base64 入力は、厳密なアルファベット/パディングチェックとデコード前のサイズガードで検証されます。 - - ファイル権限は、ディレクトリが `0700`、ファイルが `0600` です。 - - クリーンアップは `cleanup` ポリシーに従います。`delete` は常に添付ファイルを削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 + - 添付ファイルの内容は、トランスクリプト永続化から自動的に編集されます。 + - Base64入力は、厳格なアルファベット/パディングチェックとデコード前サイズガードで検証されます。 + - ファイル権限はディレクトリが `0700`、ファイルが `0600` です。 + - クリーンアップは `cleanup` ポリシーに従います。`delete` は常に添付ファイルを削除し、`keep` は `retainOnSessionKeep: true` の場合のみ保持します。 @@ -343,7 +343,7 @@ x-i18n: ### `tools.experimental` -実験的な組み込みツールフラグ。strict-agentic GPT-5 の自動有効化ルールが適用されない限り、デフォルトではオフです。 +実験的な組み込みツールフラグ。strict-agentic GPT-5 の自動有効化ルールが適用される場合を除き、デフォルトではオフです。 ```json5 { @@ -355,9 +355,9 @@ x-i18n: } ``` -- `planTool`: 重要な複数ステップ作業の追跡用に、構造化された `update_plan` ツールを有効にします。 -- 既定値: OpenAI または OpenAI Codex GPT-5 ファミリーの実行で、`agents.defaults.embeddedPi.executionContract`（またはエージェントごとの上書き）が `"strict-agentic"` に設定されていない限り `false` です。その範囲外でツールを強制的に有効にするには `true` を設定し、strict-agentic GPT-5 実行でも無効のままにするには `false` を設定します。 -- 有効にすると、システムプロンプトには使用ガイダンスも追加されるため、モデルは実質的な作業にのみこれを使用し、`in_progress` のステップを最大 1 つに保ちます。 +- `planTool`: 重要な複数ステップの作業を追跡するための構造化された `update_plan` ツールを有効にします。 +- 既定値: OpenAI または OpenAI Codex の GPT-5 ファミリー実行で `agents.defaults.embeddedPi.executionContract`（またはエージェントごとの上書き）が `"strict-agentic"` に設定されていない限り、`false` です。その範囲外でツールを強制的に有効にするには `true` を設定し、strict-agentic GPT-5 実行でも無効のままにするには `false` を設定します。 +- 有効にすると、システムプロンプトにも使用ガイダンスが追加され、モデルは実質的な作業にのみこのツールを使い、`in_progress` のステップを最大 1 つに保ちます。 ### `agents.defaults.subagents` @@ -377,16 +377,16 @@ x-i18n: } ``` -- `model`: 生成されたサブエージェントの既定モデル。省略すると、サブエージェントは呼び出し元のモデルを継承します。 -- `allowAgents`: 要求元エージェントが独自の `subagents.allowAgents` を設定していない場合の、`sessions_spawn` の対象エージェント ID の既定許可リスト（`["*"]` = 任意、既定値: 同じエージェントのみ）。 -- `runTimeoutSeconds`: ツール呼び出しで `runTimeoutSeconds` が省略された場合の、`sessions_spawn` の既定タイムアウト（秒）。`0` はタイムアウトなしを意味します。 +- `model`: 生成されるサブエージェントの既定モデル。省略すると、サブエージェントは呼び出し元のモデルを継承します。 +- `allowAgents`: リクエスト元エージェントが自身の `subagents.allowAgents` を設定していない場合に `sessions_spawn` で使う対象エージェント ID の既定許可リスト（`["*"]` = 任意、既定値: 同じエージェントのみ）。 +- `runTimeoutSeconds`: ツール呼び出しで `runTimeoutSeconds` が省略された場合に `sessions_spawn` で使う既定のタイムアウト（秒）。`0` はタイムアウトなしを意味します。 - サブエージェントごとのツールポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## カスタムプロバイダーとベース URL -OpenClaw は組み込みのモデルカタログを使用します。カスタムプロバイダーは、config の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加します。 +OpenClaw は組み込みのモデルカタログを使用します。カスタムプロバイダーは、設定内の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加します。 ```json5 { @@ -416,19 +416,19 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ ``` - + - カスタム認証が必要な場合は、`authHeader: true` + `headers` を使用します。 - - エージェント config ルートは `OPENCLAW_AGENT_DIR`（または従来の環境変数エイリアス `PI_CODING_AGENT_DIR`）で上書きします。 + - エージェント設定ルートは `OPENCLAW_AGENT_DIR`（または従来の環境変数エイリアス `PI_CODING_AGENT_DIR`）で上書きします。 - 一致するプロバイダー ID のマージ優先順位: - 空でないエージェント `models.json` の `baseUrl` 値が優先されます。 - - 空でないエージェント `apiKey` 値は、そのプロバイダーが現在の config/auth-profile コンテキストで SecretRef 管理されていない場合にのみ優先されます。 - - SecretRef 管理のプロバイダー `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（env 参照の場合は `ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。 - - SecretRef 管理のプロバイダーヘッダー値は、ソースマーカー（env 参照の場合は `secretref-env:ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。 - - 空または欠落しているエージェント `apiKey`/`baseUrl` は、config の `models.providers` にフォールバックします。 - - 一致するモデルの `contextWindow`/`maxTokens` は、明示的な config 値と暗黙のカタログ値のうち高い方を使用します。 + - 空でないエージェント `apiKey` 値は、そのプロバイダーが現在の設定/認証プロファイルコンテキストで SecretRef 管理されていない場合のみ優先されます。 + - SecretRef 管理のプロバイダー `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（環境変数参照では `ENV_VAR_NAME`、ファイル/exec 参照では `secretref-managed`）から更新されます。 + - SecretRef 管理のプロバイダーヘッダー値は、ソースマーカー（環境変数参照では `secretref-env:ENV_VAR_NAME`、ファイル/exec 参照では `secretref-managed`）から更新されます。 + - 空または欠落しているエージェント `apiKey`/`baseUrl` は、設定内の `models.providers` にフォールバックします。 + - 一致するモデルの `contextWindow`/`maxTokens` は、明示的な設定値と暗黙のカタログ値のうち高い方を使用します。 - 一致するモデルの `contextTokens` は、存在する場合は明示的なランタイム上限を保持します。ネイティブモデルメタデータを変更せずに有効コンテキストを制限するために使用します。 - - config で `models.json` を完全に書き換えたい場合は、`models.mode: "replace"` を使用します。 - - マーカーの永続化はソースを正とします。マーカーは、解決済みランタイムシークレット値ではなく、アクティブなソース config スナップショット（解決前）から書き込まれます。 + - 設定で `models.json` を完全に書き換えたい場合は、`models.mode: "replace"` を使用します。 + - マーカーの永続化はソースを権威とします。マーカーは、解決済みランタイムシークレット値ではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。 @@ -436,64 +436,64 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ ### プロバイダーフィールドの詳細 - + - `models.mode`: プロバイダーカタログの動作（`merge` または `replace`）。 - `models.providers`: プロバイダー ID をキーにしたカスタムプロバイダーマップ。 - - 安全な編集: 追加更新には、`openclaw config set models.providers. '' --strict-json --merge` または `openclaw config set models.providers..models '' --strict-json --merge` を使用します。`config set` は、`--replace` を渡さない限り破壊的な置換を拒否します。 + - 安全な編集: 追加更新には `openclaw config set models.providers. '' --strict-json --merge` または `openclaw config set models.providers..models '' --strict-json --merge` を使用します。`config set` は、`--replace` を渡さない限り破壊的な置換を拒否します。 - - - `models.providers.*.api`: リクエストアダプター（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。MLX、vLLM、SGLang、およびほとんどの OpenAI 互換ローカルサーバーのようなセルフホストの `/v1/chat/completions` バックエンドでは、`openai-completions` を使用します。`baseUrl` があり `api` がないカスタムプロバイダーは、既定で `openai-completions` になります。バックエンドが `/v1/responses` をサポートする場合にのみ `openai-responses` を設定します。 - - `models.providers.*.apiKey`: プロバイダー資格情報（SecretRef/env 置換を推奨）。 + + - `models.providers.*.api`: リクエストアダプター（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。MLX、vLLM、SGLang、および多くの OpenAI 互換ローカルサーバーなど、セルフホストの `/v1/chat/completions` バックエンドでは、`openai-completions` を使用します。`baseUrl` があり `api` がないカスタムプロバイダーは、既定で `openai-completions` になります。バックエンドが `/v1/responses` をサポートしている場合のみ `openai-responses` を設定します。 + - `models.providers.*.apiKey`: プロバイダー資格情報（SecretRef/環境変数置換を推奨）。 - `models.providers.*.auth`: 認証戦略（`api-key`、`token`、`oauth`、`aws-sdk`）。 - - `models.providers.*.contextWindow`: モデルエントリが `contextWindow` を設定していない場合の、このプロバイダー配下のモデルに対する既定のネイティブコンテキストウィンドウ。 - - `models.providers.*.contextTokens`: モデルエントリが `contextTokens` を設定していない場合の、このプロバイダー配下のモデルに対する既定の有効ランタイムコンテキスト上限。 - - `models.providers.*.maxTokens`: モデルエントリが `maxTokens` を設定していない場合の、このプロバイダー配下のモデルに対する既定の出力トークン上限。 - - `models.providers.*.timeoutSeconds`: 接続、ヘッダー、本文、およびリクエスト全体の中止処理を含む、プロバイダーごとの任意のモデル HTTP リクエストタイムアウト（秒）。 - - `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` の場合、リクエストに `options.num_ctx` を注入します（既定値: `true`）。 - - `models.providers.*.authHeader`: 必要な場合に、資格情報の転送を `Authorization` ヘッダーに強制します。 - - `models.providers.*.baseUrl`: 上流 API ベース URL。 - - `models.providers.*.headers`: プロキシ/テナントルーティング用の追加静的ヘッダー。 + - `models.providers.*.contextWindow`: モデルエントリで `contextWindow` が設定されていない場合に、このプロバイダー配下のモデルに使う既定のネイティブコンテキストウィンドウ。 + - `models.providers.*.contextTokens`: モデルエントリで `contextTokens` が設定されていない場合に、このプロバイダー配下のモデルに使う既定の有効ランタイムコンテキスト上限。 + - `models.providers.*.maxTokens`: モデルエントリで `maxTokens` が設定されていない場合に、このプロバイダー配下のモデルに使う既定の出力トークン上限。 + - `models.providers.*.timeoutSeconds`: 接続、ヘッダー、本文、リクエスト全体の中断処理を含む、プロバイダーごとの任意のモデル HTTP リクエストタイムアウト（秒）。 + - `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` で、リクエストに `options.num_ctx` を注入します（既定値: `true`）。 + - `models.providers.*.authHeader`: 必要な場合に、資格情報の送信を `Authorization` ヘッダーで強制します。 + - `models.providers.*.baseUrl`: アップストリーム API ベース URL。 + - `models.providers.*.headers`: プロキシ/テナントルーティング用の追加の静的ヘッダー。 - - `models.providers.*.request`: モデルプロバイダー HTTP リクエストの転送上書き。 + + `models.providers.*.request`: モデルプロバイダー HTTP リクエストのトランスポート上書き。 - - `request.headers`: 追加ヘッダー（プロバイダー既定値とマージされます）。値は SecretRef を受け付けます。 - - `request.auth`: 認証戦略の上書き。モード: `"provider-default"`（プロバイダーの組み込み認証を使用）、`"authorization-bearer"`（`token` と使用）、`"header"`（`headerName`、`value`、任意の `prefix` と使用）。 - - `request.proxy`: HTTP プロキシの上書き。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` env 変数を使用）、`"explicit-proxy"`（`url` と使用）。どちらのモードも任意の `tls` サブオブジェクトを受け付けます。 - - `request.tls`: 直接接続用の TLS 上書き。フィールド: `ca`、`cert`、`key`、`passphrase`（すべて SecretRef を受け付けます）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`: `true` の場合、DNS がプライベート、CGNAT、または類似の範囲に解決されるときでも、プロバイダー HTTP fetch ガード経由で `baseUrl` への HTTPS を許可します（信頼済みのセルフホスト OpenAI 互換エンドポイントに対するオペレーターのオプトイン）。`localhost`、`127.0.0.1`、`[::1]` などの local loopback モデルプロバイダーストリーム URL は、これが明示的に `false` に設定されていない限り自動的に許可されます。LAN、tailnet、およびプライベート DNS ホストは引き続きオプトインが必要です。WebSocket はヘッダー/TLS に同じ `request` を使用しますが、その fetch SSRF ゲートは使用しません。既定値は `false` です。 + - `request.headers`: 追加ヘッダー（プロバイダー既定値とマージされます）。値には SecretRef を指定できます。 + - `request.auth`: 認証戦略の上書き。モード: `"provider-default"`（プロバイダーの組み込み認証を使用）、`"authorization-bearer"`（`token` を使用）、`"header"`（`headerName`、`value`、任意の `prefix` を使用）。 + - `request.proxy`: HTTP プロキシの上書き。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` 環境変数を使用）、`"explicit-proxy"`（`url` を使用）。どちらのモードも任意の `tls` サブオブジェクトを受け付けます。 + - `request.tls`: 直接接続の TLS 上書き。フィールド: `ca`、`cert`、`key`、`passphrase`（すべて SecretRef を受け付けます）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`: `true` の場合、DNS がプライベート、CGNAT、または類似の範囲に解決される場合でも、プロバイダー HTTP fetch ガードを介して `baseUrl` への HTTPS を許可します（信頼されたセルフホスト OpenAI 互換エンドポイント向けのオペレーターによるオプトイン）。`localhost`、`127.0.0.1`、`[::1]` などのループバックモデルプロバイダーストリーム URL は、これが明示的に `false` に設定されていない限り自動的に許可されます。LAN、tailnet、プライベート DNS ホストには引き続きオプトインが必要です。WebSocket はヘッダー/TLS に同じ `request` を使用しますが、その fetch SSRF ゲートは使用しません。既定値は `false` です。 - + - `models.providers.*.models`: 明示的なプロバイダーモデルカタログエントリ。 - - `models.providers.*.models.*.input`: モデル入力モダリティ。テキストのみのモデルには `["text"]` を、ネイティブ画像/ビジョンモデルには `["text", "image"]` を使用します。画像添付は、選択されたモデルが画像対応としてマークされている場合にのみエージェントターンに注入されます。 - - `models.providers.*.models.*.contextWindow`: ネイティブモデルコンテキストウィンドウメタデータ。このモデルについて、プロバイダーレベルの `contextWindow` を上書きします。 - - `models.providers.*.models.*.contextTokens`: 任意のランタイムコンテキスト上限。このモデルについて、プロバイダーレベルの `contextTokens` を上書きします。モデルのネイティブ `contextWindow` よりも小さい有効コンテキスト予算にしたい場合に使用します。`openclaw models list` は、値が異なる場合に両方の値を表示します。 - - `models.providers.*.models.*.compat.supportsDeveloperRole`: 任意の互換性ヒント。空でない非ネイティブ `baseUrl`（ホストが `api.openai.com` ではない）を使用する `api: "openai-completions"` の場合、OpenClaw は実行時にこれを `false` に強制します。空または省略された `baseUrl` は、既定の OpenAI 動作を保持します。 - - `models.providers.*.models.*.compat.requiresStringContent`: 文字列のみの OpenAI 互換チャットエンドポイント向けの任意の互換性ヒント。`true` の場合、OpenClaw はリクエスト送信前に純粋なテキストの `messages[].content` 配列をプレーン文字列に平坦化します。 + - `models.providers.*.models.*.input`: モデル入力モダリティ。テキスト専用モデルには `["text"]` を使用し、ネイティブ画像/ビジョンモデルには `["text", "image"]` を使用します。画像添付は、選択されたモデルが画像対応としてマークされている場合にのみエージェントターンに注入されます。 + - `models.providers.*.models.*.contextWindow`: ネイティブモデルのコンテキストウィンドウメタデータ。これはそのモデルのプロバイダーレベルの `contextWindow` を上書きします。 + - `models.providers.*.models.*.contextTokens`: 任意のランタイムコンテキスト上限。これはプロバイダーレベルの `contextTokens` を上書きします。モデルのネイティブ `contextWindow` より小さい有効コンテキスト予算が必要な場合に使用します。`openclaw models list` は、両方の値が異なる場合に両方を表示します。 + - `models.providers.*.models.*.compat.supportsDeveloperRole`: 任意の互換性ヒント。空でない非ネイティブ `baseUrl`（ホストが `api.openai.com` ではない）を持つ `api: "openai-completions"` では、OpenClaw はランタイムでこれを `false` に強制します。空または省略された `baseUrl` は、既定の OpenAI 動作を維持します。 + - `models.providers.*.models.*.compat.requiresStringContent`: 文字列専用の OpenAI 互換チャットエンドポイント向けの任意の互換性ヒント。`true` の場合、OpenClaw は純粋なテキストの `messages[].content` 配列を、リクエスト送信前にプレーン文字列へ平坦化します。 - + - `plugins.entries.amazon-bedrock.config.discovery`: Bedrock 自動検出設定のルート。 - - `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙的な検出のオン/オフを切り替えます。 - - `plugins.entries.amazon-bedrock.config.discovery.region`: 検出用の AWS リージョン。 - - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象を絞った検出用の任意のプロバイダー ID フィルター。 + - `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙の検出をオン/オフにします。 + - `plugins.entries.amazon-bedrock.config.discovery.region`: 検出に使う AWS リージョン。 + - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象を絞った検出に使う任意のプロバイダー ID フィルター。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: 検出更新のポーリング間隔。 - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出されたモデルのフォールバックコンテキストウィンドウ。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出されたモデルのフォールバック最大出力トークン。 + - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出されたモデルのフォールバック最大出力トークン数。 -対話型のカスタムプロバイダーオンボーディングは、GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V、GLM-4V などの一般的なビジョンモデル ID について画像入力を推定し、既知のテキストのみファミリーでは追加の質問をスキップします。不明なモデル ID では、引き続き画像サポートについて確認します。非対話型オンボーディングは同じ推定を使用します。画像対応メタデータを強制するには `--custom-image-input` を、テキストのみメタデータを強制するには `--custom-text-input` を渡します。 +インタラクティブなカスタムプロバイダーオンボーディングは、GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V、GLM-4V などの一般的なビジョンモデル ID について画像入力を推論し、既知のテキスト専用ファミリーでは追加の質問をスキップします。不明なモデル ID では、引き続き画像サポートを確認します。非インタラクティブなオンボーディングでも同じ推論を使用します。画像対応メタデータを強制するには `--custom-image-input` を渡し、テキスト専用メタデータを強制するには `--custom-text-input` を渡します。 ### プロバイダー例 - - バンドルされている `cerebras` プロバイダー Plugin は、`openclaw onboard --auth-choice cerebras-api-key` でこれを構成できます。既定値を上書きする場合にのみ、明示的なプロバイダー config を使用します。 + + バンドルされた `cerebras` プロバイダー Plugin は、`openclaw onboard --auth-choice cerebras-api-key` でこれを設定できます。既定値を上書きする場合のみ、明示的なプロバイダー設定を使用します。 ```json5 { @@ -547,7 +547,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ - [ローカルモデル](/ja-JP/gateway/local-models)を参照してください。要約: 本格的なハードウェア上で LM Studio Responses API 経由の大規模なローカルモデルを実行し、フォールバック用にホスト型モデルをマージしたままにします。 + [ローカルモデル](/ja-JP/gateway/local-models)を参照してください。要約: 本格的なハードウェア上で、LM Studio Responses API 経由で大規模なローカルモデルを実行します。フォールバック用にホスト型モデルもマージしたままにしてください。 ```json5 @@ -584,7 +584,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ } ``` - `MINIMAX_API_KEY` を設定します。ショートカット: `openclaw onboard --auth-choice minimax-global-api` または `openclaw onboard --auth-choice minimax-cn-api`。モデルカタログのデフォルトは M2.7 のみです。Anthropic 互換のストリーミングパスでは、`thinking` を明示的に自分で設定しない限り、OpenClaw はデフォルトで MiniMax の thinking を無効にします。`/fast on` または `params.fastMode: true` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。 + `MINIMAX_API_KEY` を設定します。ショートカット: `openclaw onboard --auth-choice minimax-global-api` または `openclaw onboard --auth-choice minimax-cn-api`。モデルカタログのデフォルトは M2.7 のみです。Anthropic 互換ストリーミングパスでは、自分で `thinking` を明示的に設定しない限り、OpenClaw はデフォルトで MiniMax の思考を無効にします。`/fast on` または `params.fastMode: true` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。 @@ -623,7 +623,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ 中国エンドポイントの場合: `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn`。 - ネイティブの Moonshot エンドポイントは、共有の `openai-completions` トランスポート上でストリーミング使用量の互換性を通知し、OpenClaw は組み込み provider id だけではなく、エンドポイント機能に基づいてそれを判定します。 + ネイティブの Moonshot エンドポイントは、共有 `openai-completions` トランスポート上でストリーミング使用量の互換性を通知し、OpenClaw は組み込みプロバイダー ID だけではなくエンドポイント機能に基づいてそれを判定します。 @@ -638,7 +638,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ } ``` - `OPENCODE_API_KEY` (または `OPENCODE_ZEN_API_KEY`) を設定します。Zen カタログには `opencode/...` refs を、Go カタログには `opencode-go/...` refs を使用します。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。 + `OPENCODE_API_KEY` (または `OPENCODE_ZEN_API_KEY`) を設定します。Zen カタログには `opencode/...` 参照を、Go カタログには `opencode-go/...` 参照を使用します。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。 @@ -675,7 +675,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ } ``` - ベース URL では `/v1` を省略する必要があります (Anthropic クライアントが付加します)。ショートカット: `openclaw onboard --auth-choice synthetic-api-key`。 + ベース URL では `/v1` を省略してください (Anthropic クライアントが追加します)。ショートカット: `openclaw onboard --auth-choice synthetic-api-key`。 @@ -690,11 +690,11 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ } ``` - `ZAI_API_KEY` を設定します。`z.ai/*` と `z-ai/*` はエイリアスとして受け入れられます。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 + `ZAI_API_KEY` を設定します。`z.ai/*` と `z-ai/*` は別名として受け付けられます。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 - 汎用エンドポイント: `https://api.z.ai/api/paas/v4` - コーディングエンドポイント (デフォルト): `https://api.z.ai/api/coding/paas/v4` - - 汎用エンドポイントの場合は、ベース URL のオーバーライドを含むカスタム provider を定義します。 + - 汎用エンドポイントの場合は、ベース URL の上書きを持つカスタムプロバイダーを定義します。 @@ -703,7 +703,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ ## 関連 -- [設定 — agents](/ja-JP/gateway/config-agents) -- [設定 — channels](/ja-JP/gateway/config-channels) +- [設定 — エージェント](/ja-JP/gateway/config-agents) +- [設定 — チャンネル](/ja-JP/gateway/config-channels) - [設定リファレンス](/ja-JP/gateway/configuration-reference) — その他のトップレベルキー -- [ツールとplugins](/ja-JP/tools) +- [ツールと plugins](/ja-JP/tools) diff --git a/docs/ja-JP/gateway/doctor.md b/docs/ja-JP/gateway/doctor.md index 73220f708..2829a3c73 100644 --- a/docs/ja-JP/gateway/doctor.md +++ b/docs/ja-JP/gateway/doctor.md @@ -3,18 +3,18 @@ read_when: - doctor マイグレーションの追加または変更 - 破壊的な設定変更の導入 sidebarTitle: Doctor -summary: 'doctor コマンド: ヘルスチェック、設定の移行、修復手順' +summary: 'Doctor コマンド: ヘルスチェック、設定移行、修復手順' title: 診断 x-i18n: - generated_at: "2026-04-30T16:28:59Z" + generated_at: "2026-05-01T05:01:21Z" model: gpt-5.5 provider: openai - source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e + source_hash: 52183eaf6024eface20089f9d11143ef1e952d2488eee766dc154512f5d3c6b4 source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor`はOpenClawの修復 + 移行ツールです。古い設定/状態を修正し、健全性をチェックし、実行可能な修復手順を提供します。 +`openclaw doctor` は OpenClaw の修復 + 移行ツールです。古い設定/状態を修正し、正常性を確認し、実行可能な修復手順を提示します。 ## クイックスタート @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - プロンプトを表示せずにデフォルトを受け入れます（該当する場合は再起動/サービス/サンドボックス修復手順も含む）。 + プロンプトを表示せずにデフォルトを受け入れます（該当する場合は再起動/サービス/サンドボックス修復手順を含む）。 @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - プロンプトを表示せずに推奨される修復を適用します（安全な場合は修復 + 再起動）。 + プロンプトを表示せずに推奨修復を適用します（安全な場合は修復 + 再起動）。 @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - 強力な修復も適用します（カスタム supervisor 設定を上書きします）。 + 積極的な修復も適用します（カスタム supervisor 設定を上書きします）。 @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - プロンプトなしで実行し、安全な移行のみを適用します（設定の正規化 + ディスク上の状態移動）。人による確認が必要な再起動/サービス/サンドボックス操作はスキップします。レガシー状態の移行は、検出されると自動的に実行されます。 + プロンプトなしで実行し、安全な移行のみを適用します（設定の正規化 + ディスク上の状態移動）。人間の確認が必要な再起動/サービス/サンドボックス操作はスキップします。レガシー状態の移行は検出時に自動実行されます。 @@ -62,12 +62,12 @@ openclaw doctor openclaw doctor --deep ``` - 追加のGatewayインストール（launchd/systemd/schtasks）についてシステムサービスをスキャンします。 + 追加の gateway インストールについてシステムサービスをスキャンします（launchd/systemd/schtasks）。 -書き込む前に変更を確認したい場合は、まず設定ファイルを開いてください。 +書き込む前に変更を確認したい場合は、まず設定ファイルを開きます。 ```bash cat ~/.openclaw/openclaw.json @@ -76,112 +76,117 @@ cat ~/.openclaw/openclaw.json ## 実行内容（概要） - - - gitインストール向けの任意の事前更新（対話時のみ）。 - - UIプロトコル鮮度チェック（プロトコルスキーマが新しい場合にControl UIを再ビルド）。 - - 健全性チェック + 再起動プロンプト。 - - Skillsステータス概要（対象/欠落/ブロック）とPluginステータス。 + + - git インストール向けの任意の事前更新（対話モードのみ）。 + - UI プロトコル鮮度チェック（プロトコルスキーマが新しい場合に Control UI を再ビルド）。 + - 正常性チェック + 再起動プロンプト。 + - Skills ステータス概要（対象/不足/ブロック中）と plugin ステータス。 - レガシー値の設定正規化。 - - レガシーのフラットな`talk.*`フィールドから`talk.provider` + `talk.providers.`へのTalk設定移行。 - - レガシーChrome拡張機能設定とChrome MCP準備状況のブラウザー移行チェック。 - - OpenCodeプロバイダー上書き警告（`models.providers.opencode` / `models.providers.opencode-go`）。 - - Codex OAuthシャドーイング警告（`models.providers.openai-codex`）。 - - OpenAI Codex OAuthプロファイル向けOAuth TLS前提条件チェック。 - - レガシーのディスク上状態移行（セッション/エージェントディレクトリ/WhatsApp認証）。 - - レガシーPluginマニフェスト契約キー移行（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。 - - レガシーCronストア移行（`jobId`、`schedule.cron`、トップレベルの配信/ペイロードフィールド、ペイロード`provider`、単純な`notify: true` webhookフォールバックジョブ）。 - - レガシーエージェントランタイムポリシーを`agents.defaults.agentRuntime`と`agents.list[].agentRuntime`へ移行。 - - Pluginが有効な場合は古いPlugin設定をクリーンアップします。`plugins.enabled=false`の場合、古いPlugin参照は不活性な封じ込め設定として扱われ、保持されます。 + - レガシーのフラットな `talk.*` フィールドから `talk.provider` + `talk.providers.` への Talk 設定移行。 + - レガシー Chrome 拡張機能設定と Chrome MCP 準備状態のブラウザー移行チェック。 + - OpenCode プロバイダー上書きの警告（`models.providers.opencode` / `models.providers.opencode-go`）。 + - Codex OAuth シャドーイングの警告（`models.providers.openai-codex`）。 + - OpenAI Codex OAuth プロファイル向け OAuth TLS 前提条件チェック。 + - `plugins.allow` が制限的だが、ツールポリシーがまだワイルドカードまたは plugin 所有ツールを要求している場合の Plugin/ツール許可リスト警告。 + - レガシーのディスク上状態移行（セッション/エージェントディレクトリ/WhatsApp 認証）。 + - レガシー plugin マニフェスト契約キー移行（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。 + - レガシー cron ストア移行（`jobId`, `schedule.cron`, トップレベルの delivery/payload フィールド、payload `provider`, 単純な `notify: true` webhook フォールバックジョブ）。 + - レガシーエージェントランタイムポリシーを `agents.defaults.agentRuntime` と `agents.list[].agentRuntime` へ移行。 + - plugins が有効な場合の古い plugin 設定のクリーンアップ。`plugins.enabled=false` の場合、古い plugin 参照は不活性な封じ込め設定として扱われ、保持されます。 - セッションロックファイルの検査と古いロックのクリーンアップ。 - - 影響を受けた2026.4.24ビルドによって作成された重複プロンプト書き換えブランチに対するセッショントランスクリプト修復。 - - 行き詰まったサブエージェントの再起動リカバリ墓標検出。古い中断済みリカバリフラグをクリアして、起動時に子を再起動中断として扱い続けないようにする`--fix`サポート付き。 - - 状態整合性と権限チェック（セッション、トランスクリプト、状態ディレクトリ）。 + - 影響を受けた 2026.4.24 ビルドによって作成された重複プロンプト書き換えブランチのセッショントランスクリプト修復。 + - 行き詰まったサブエージェントの再起動リカバリ tombstone 検出。古い中止済みリカバリフラグをクリアして、起動時に子を再起動中止済みとして扱い続けないようにするための `--fix` サポート付き。 + - 状態の整合性と権限チェック（セッション、トランスクリプト、状態ディレクトリ）。 - ローカル実行時の設定ファイル権限チェック（chmod 600）。 - - モデル認証の健全性: OAuth期限切れをチェックし、期限が近いトークンを更新でき、認証プロファイルのクールダウン/無効状態を報告します。 + - モデル認証の正常性: OAuth 有効期限を確認し、期限が近いトークンを更新でき、auth-profile のクールダウン/無効状態を報告します。 - 追加ワークスペースディレクトリ検出（`~/openclaw`）。 - サンドボックスが有効な場合のサンドボックスイメージ修復。 - - レガシーサービス移行と追加Gateway検出。 - - Matrixチャネルのレガシー状態移行（`--fix` / `--repair`モード）。 - - Gatewayランタイムチェック（サービスはインストール済みだが実行中ではない、キャッシュ済みlaunchdラベル）。 - - チャネルステータス警告（実行中のGatewayからプローブ）。 - - supervisor設定監査（launchd/systemd/schtasks）と任意の修復。 - - インストールまたは更新中にシェルの`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`値を取り込んだGatewayサービス向けの埋め込みプロキシ環境クリーンアップ。 - - Gatewayランタイムのベストプラクティスチェック（Node vs Bun、バージョンマネージャーパス）。 - - Gatewayポート衝突診断（デフォルト`18789`）。 + - レガシーサービス移行と追加 gateway 検出。 + - Matrix チャンネルのレガシー状態移行（`--fix` / `--repair` モード）。 + - Gateway ランタイムチェック（サービスがインストール済みだが実行されていない、キャッシュ済み launchd ラベル）。 + - チャンネルステータス警告（実行中の gateway からプローブ）。 + - 任意修復付き supervisor 設定監査（launchd/systemd/schtasks）。 + - インストールまたは更新時にシェルの `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 値を取り込んだ gateway サービス向けの埋め込みプロキシ環境クリーンアップ。 + - Gateway ランタイムのベストプラクティスチェック（Node と Bun、バージョンマネージャーパス）。 + - Gateway ポート衝突診断（デフォルト `18789`）。 - - オープンDMポリシーに関するセキュリティ警告。 - - ローカルトークンモード向けGateway認証チェック（トークンソースが存在しない場合はトークン生成を提案します。SecretRefトークン設定は上書きしません）。 - - デバイスペアリング問題の検出（保留中の初回ペアリクエスト、保留中のロール/スコープアップグレード、古いローカルデバイストークンキャッシュのずれ、ペアリング済みレコードの認証ずれ）。 + - オープン DM ポリシーのセキュリティ警告。 + - ローカルトークンモード向け Gateway 認証チェック（トークンソースがない場合にトークン生成を提示します。トークン SecretRef 設定は上書きしません）。 + - デバイスペアリング問題の検出（保留中の初回ペアリングリクエスト、保留中のロール/スコープアップグレード、古いローカルデバイストークンキャッシュのずれ、ペアリング済みレコードの認証ずれ）。 - - Linuxでのsystemd lingerチェック。 - - ワークスペースブートストラップファイルサイズチェック（コンテキストファイルの切り詰め/上限接近警告）。 + - Linux での systemd linger チェック。 + - ワークスペース bootstrap ファイルサイズチェック（コンテキストファイルの切り詰め/上限接近の警告）。 - シェル補完ステータスチェックと自動インストール/アップグレード。 - - メモリ検索埋め込みプロバイダー準備状況チェック（ローカルモデル、リモートAPIキー、またはQMDバイナリ）。 - - ソースインストールチェック（pnpmワークスペース不一致、UIアセット欠落、tsxバイナリ欠落）。 + - メモリ検索埋め込みプロバイダー準備状態チェック（ローカルモデル、リモート API キー、または QMD バイナリ）。 + - ソースインストールチェック（pnpm ワークスペース不一致、不足 UI アセット、不足 tsx バイナリ）。 - 更新済み設定 + ウィザードメタデータを書き込みます。 -## Dreams UIのバックフィルとリセット +## Dreams UI バックフィルとリセット -Control UIのDreamsシーンには、グラウンデッドDreamingワークフロー向けに**バックフィル**、**リセット**、**グラウンデッドをクリア**アクションが含まれています。これらのアクションはGatewayのdoctor形式RPCメソッドを使用しますが、`openclaw doctor` CLIの修復/移行の一部では**ありません**。 +Control UI の Dreams シーンには、grounded dreaming ワークフロー向けの **Backfill**、**Reset**、**Clear Grounded** アクションがあります。これらのアクションは gateway の doctor 形式の RPC メソッドを使いますが、`openclaw doctor` CLI の修復/移行の一部では**ありません**。 実行内容: -- **バックフィル**は、アクティブワークスペース内の履歴`memory/YYYY-MM-DD.md`ファイルをスキャンし、グラウンデッドREM日記パスを実行し、可逆バックフィルエントリを`DREAMS.md`に書き込みます。 -- **リセット**は、`DREAMS.md`からマークされたバックフィル日記エントリのみを削除します。 -- **グラウンデッドをクリア**は、履歴リプレイから来ていて、まだライブリコールや日次サポートが蓄積されていない、ステージ済みのグラウンデッド限定短期エントリのみを削除します。 +- **Backfill** はアクティブワークスペース内の過去の `memory/YYYY-MM-DD.md` ファイルをスキャンし、grounded REM diary パスを実行し、可逆的なバックフィルエントリを `DREAMS.md` に書き込みます。 +- **Reset** は `DREAMS.md` から、マークされたバックフィル diary エントリのみを削除します。 +- **Clear Grounded** は、履歴リプレイから来て、まだライブ recall や日次サポートを蓄積していない、ステージ済みの grounded-only 短期エントリのみを削除します。 -それ自体では**実行しない**こと: +それ自体では実行**しない**こと: -- `MEMORY.md`を編集しません -- 完全なdoctor移行を実行しません -- 先にステージ済みCLIパスを明示的に実行しない限り、グラウンデッド候補をライブ短期昇格ストアへ自動的にステージしません +- `MEMORY.md` を編集しません +- 完全な doctor 移行を実行しません +- ステージ済み CLI パスを明示的に先に実行しない限り、grounded 候補をライブ短期プロモーションストアへ自動的にステージしません -グラウンデッド履歴リプレイを通常のディープ昇格レーンに反映したい場合は、代わりにCLIフローを使用してください。 +grounded 履歴リプレイを通常の deep promotion レーンに影響させたい場合は、代わりに CLI フローを使います。 ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -これにより、`DREAMS.md`をレビュー面として維持しながら、グラウンデッドで永続的な候補を短期Dreamingストアにステージします。 +これにより、`DREAMS.md` をレビュー面として維持しながら、grounded durable 候補を短期 dreaming ストアへステージします。 -## 詳細な挙動と根拠 +## 詳細な動作と根拠 - - これがgit checkoutでdoctorが対話的に実行されている場合、doctorを実行する前に更新（fetch/rebase/build）を提案します。 + + これが git checkout であり doctor が対話的に実行されている場合、doctor 実行前に更新（fetch/rebase/build）を提示します。 - 設定にレガシー値の形（たとえばチャネル固有の上書きがない`messages.ackReaction`）が含まれている場合、doctorはそれらを現在のスキーマへ正規化します。 + 設定にレガシー値の形（たとえばチャンネル固有の上書きがない `messages.ackReaction`）が含まれている場合、doctor はそれらを現在のスキーマへ正規化します。 - これにはレガシーTalkフラットフィールドが含まれます。現在の公開Talk設定は`talk.provider` + `talk.providers.`です。Doctorは古い`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey`の形をプロバイダーマップへ書き換えます。 + これにはレガシー Talk フラットフィールドが含まれます。現在の公開 Talk 設定は `talk.provider` + `talk.providers.` です。Doctor は古い `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形式をプロバイダーマップへ書き換えます。 + + Doctor はまた、`plugins.allow` が空でなく、ツールポリシーが + ワイルドカードまたは plugin 所有ツールエントリを使う場合に警告します。`tools.allow: ["*"]` は実際にロードされる plugins のツールだけに一致します。 + 排他的な plugin 許可リストをバイパスするものではありません。 - 設定に非推奨キーが含まれている場合、他のコマンドは実行を拒否し、`openclaw doctor`の実行を求めます。 + 設定に非推奨キーが含まれている場合、他のコマンドは実行を拒否し、`openclaw doctor` の実行を求めます。 - Doctorは次を行います。 + Doctor は次を行います。 - - 検出されたレガシーキーを説明します。 + - 見つかったレガシーキーを説明します。 - 適用した移行を表示します。 - - 更新済みスキーマで`~/.openclaw/openclaw.json`を書き換えます。 + - 更新済みスキーマで `~/.openclaw/openclaw.json` を書き換えます。 - Gatewayもレガシー設定形式を検出すると起動時にdoctor移行を自動実行するため、古い設定は手動介入なしで修復されます。Cronジョブストアの移行は`openclaw doctor --fix`で処理されます。 + Gateway も起動時にレガシー設定形式を検出すると doctor 移行を自動実行するため、古い設定は手動介入なしで修復されます。Cron ジョブストア移行は `openclaw doctor --fix` によって処理されます。 現在の移行: @@ -190,88 +195,88 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `routing.queue` → `messages.queue` - - `routing.bindings` → トップレベルの`bindings` + - `routing.bindings` → トップレベルの `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - - レガシー`talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` + - レガシー `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - - `messages.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `messages.tts.providers.` - - `messages.tts.provider: "edge"`および`messages.tts.providers.edge` → `messages.tts.provider: "microsoft"`および`messages.tts.providers.microsoft` - - `channels.discord.voice.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.voice.tts.providers.` - - `channels.discord.accounts..voice.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.accounts..voice.tts.providers.` - - `plugins.entries.voice-call.config.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `plugins.entries.voice-call.config.tts.providers.` - - `plugins.entries.voice-call.config.tts.provider: "edge"`および`plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"`および`providers.microsoft` + - `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` + - `messages.tts.provider: "edge"` と `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` と `messages.tts.providers.microsoft` + - `channels.discord.voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.` + - `channels.discord.accounts..voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts..voice.tts.providers.` + - `plugins.entries.voice-call.config.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.` + - `plugins.entries.voice-call.config.tts.provider: "edge"` と `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` と `providers.microsoft` - `plugins.entries.voice-call.config.provider: "log"` → `"mock"` - `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber` - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - 名前付き`accounts`があるものの、単一アカウントのトップレベルチャネル値が残っているチャネルでは、それらのアカウントスコープ値を、そのチャネルに対して選択された昇格先アカウントへ移動します（ほとんどのチャネルでは`accounts.default`。Matrixは既存の一致する名前付き/デフォルトターゲットを保持できます） + - 名前付き `accounts` がありながら、単一アカウント用のトップレベルチャネル値が残っているチャネルでは、そのアカウントスコープの値をそのチャネル用に選ばれた昇格済みアカウントへ移動する（ほとんどのチャネルでは `accounts.default`。Matrix は既存の一致する名前付き/デフォルトターゲットを維持できる） - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents） - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - `agents.defaults.llm`を削除。低速なプロバイダー/モデルのタイムアウトには`models.providers..timeoutSeconds`を使用します + - `agents.defaults.llm` を削除する。遅いプロバイダー/モデルのタイムアウトには `models.providers..timeoutSeconds` を使う - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - `browser.relayBindHost`を削除（レガシー拡張機能リレー設定） - - レガシー`models.providers.*.api: "openai"` → `"openai-completions"`（Gateway起動時も、`api`が将来または未知のenum値に設定されているプロバイダーは、閉じて失敗するのではなくスキップします） + - `browser.relayBindHost` を削除する（レガシー拡張リレー設定） + - レガシー `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 起動時は、`api` が将来の enum 値または不明な enum 値に設定されたプロバイダーについても、フェイルクローズせずにスキップする） - Doctor警告には、マルチアカウントチャネル向けのアカウントデフォルトガイダンスも含まれます。 + Doctor の警告には、複数アカウントチャネル向けのアカウントデフォルトのガイダンスも含まれる。 - - 2 つ以上の `channels..accounts` エントリが `channels..defaultAccount` または `accounts.default` なしで設定されている場合、doctor はフォールバックルーティングが予期しないアカウントを選ぶ可能性があると警告します。 - - `channels..defaultAccount` が不明なアカウント ID に設定されている場合、doctor は警告し、設定済みのアカウント ID を一覧表示します。 + - 2 つ以上の `channels..accounts` エントリが `channels..defaultAccount` または `accounts.default` なしで設定されている場合、フォールバックルーティングが予期しないアカウントを選ぶ可能性があると doctor が警告する。 + - `channels..defaultAccount` が不明なアカウント ID に設定されている場合、doctor が警告し、設定済みのアカウント ID を一覧表示する。 - `models.providers.opencode`、`opencode-zen`、または `opencode-go` を手動で追加している場合、`@mariozechner/pi-ai` の組み込み OpenCode カタログをオーバーライドします。その結果、モデルが誤った API に強制されたり、コストがゼロになったりすることがあります。doctor は警告を出すため、そのオーバーライドを削除して、モデルごとの API ルーティングとコストを復元できます。 + `models.providers.opencode`、`opencode-zen`、または `opencode-go` を手動で追加している場合、`@mariozechner/pi-ai` の組み込み OpenCode カタログをオーバーライドします。その結果、モデルが誤った API に割り当てられたり、コストがゼロになったりすることがあります。doctor は、オーバーライドを削除してモデルごとの API ルーティングとコストを復元できるように警告します。 - - ブラウザー設定が削除済みの Chrome 拡張機能パスをまだ指している場合、doctor は現在のホストローカル Chrome MCP アタッチモデルに正規化します。 + + ブラウザー設定が削除済みの Chrome 拡張パスをまだ指している場合、doctor は現在のホストローカル Chrome MCP アタッチモデルへ正規化します。 - - `browser.profiles.*.driver: "extension"` は `"existing-session"` になります - - `browser.relayBindHost` は削除されます + - `browser.profiles.*.driver: "extension"` は `"existing-session"` になる + - `browser.relayBindHost` は削除される - `defaultProfile: "user"` または設定済みの `existing-session` プロファイルを使用している場合、doctor はホストローカル Chrome MCP パスも監査します。 + doctor は、`defaultProfile: "user"` または設定済みの `existing-session` プロファイルを使う場合、ホストローカル Chrome MCP パスも監査します。 - - デフォルトの自動接続プロファイルについて、同じホストに Google Chrome がインストールされているか確認します - - 検出された Chrome バージョンを確認し、Chrome 144 未満の場合は警告します - - ブラウザーの検査ページでリモートデバッグを有効にするよう通知します（例: `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`、または `edge://inspect/#remote-debugging`） + - デフォルトの自動接続プロファイルについて、同じホストに Google Chrome がインストールされているかを確認する + - 検出された Chrome バージョンを確認し、Chrome 144 未満の場合に警告する + - ブラウザーの検査ページでリモートデバッグを有効にするよう通知する（例: `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`、または `edge://inspect/#remote-debugging`） - doctor は Chrome 側の設定を有効にすることはできません。ホストローカル Chrome MCP には引き続き次が必要です。 + doctor は Chrome 側の設定を有効化できません。ホストローカル Chrome MCP には引き続き以下が必要です。 - - Gateway/Node ホスト上の Chromium ベースのブラウザー 144 以降 - - ブラウザーがローカルで実行されていること - - そのブラウザーでリモートデバッグが有効になっていること - - ブラウザー内の最初のアタッチ同意プロンプトを承認すること + - gateway/node ホスト上の Chromium ベースブラウザー 144+ + - ブラウザーがローカルで実行中であること + - そのブラウザーでリモートデバッグが有効であること + - ブラウザーで最初のアタッチ同意プロンプトを承認すること - ここでの準備状況は、ローカルアタッチの前提条件のみに関するものです。Existing-session は現在の Chrome MCP ルート制限を維持します。`responsebody`、PDF エクスポート、ダウンロードのインターセプト、バッチアクションなどの高度なルートには、引き続きマネージドブラウザーまたは生の CDP プロファイルが必要です。 + ここでの準備状況はローカルアタッチの前提条件だけを対象とします。Existing-session は現在の Chrome MCP ルート制限を維持します。`responsebody`、PDF エクスポート、ダウンロードインターセプト、バッチアクションなどの高度なルートには、引き続き管理ブラウザーまたは raw CDP プロファイルが必要です。 - このチェックは Docker、sandbox、remote-browser、またはその他のヘッドレスフローには**適用されません**。それらは引き続き生の CDP を使用します。 + このチェックは Docker、sandbox、remote-browser、またはその他のヘッドレスフローには**適用されません**。それらは引き続き raw CDP を使用します。 - OpenAI Codex OAuth プロファイルが設定されている場合、doctor は OpenAI 認可エンドポイントをプローブし、ローカルの Node/OpenSSL TLS スタックが証明書チェーンを検証できることを確認します。プローブが証明書エラー（例: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、期限切れ証明書、または自己署名証明書）で失敗した場合、doctor はプラットフォーム別の修正ガイダンスを出力します。macOS で Homebrew Node を使用している場合、通常の修正は `brew postinstall ca-certificates` です。`--deep` では、Gateway が正常な場合でもプローブが実行されます。 + OpenAI Codex OAuth プロファイルが設定されている場合、doctor は OpenAI 認可エンドポイントを検査し、ローカルの Node/OpenSSL TLS スタックが証明書チェーンを検証できるかを確認します。検査が証明書エラー（例: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、期限切れ証明書、自己署名証明書）で失敗した場合、doctor はプラットフォーム固有の修正ガイダンスを出力します。Homebrew Node を使っている macOS では、通常の修正は `brew postinstall ca-certificates` です。`--deep` では、Gateway が正常な場合でも検査が実行されます。 - 以前に `models.providers.openai-codex` の下へレガシー OpenAI トランスポート設定を追加していた場合、新しいリリースが自動的に使用する組み込み Codex OAuth プロバイダーパスをそれらが覆い隠すことがあります。doctor は Codex OAuth と並んでそれらの古いトランスポート設定を検出すると警告するため、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を取り戻せます。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しません。 + 以前にレガシー OpenAI トランスポート設定を `models.providers.openai-codex` の下に追加していた場合、それらは新しいリリースが自動的に使う組み込み Codex OAuth プロバイダーパスをシャドーすることがあります。doctor は、Codex OAuth と並んでそれらの古いトランスポート設定を検出すると警告し、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を取り戻せるようにします。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しません。 - バンドルされた Codex Plugin が有効な場合、doctor は `openai-codex/*` のプライマリモデル参照がまだデフォルトの PI ランナー経由で解決されるかどうかも確認します。この組み合わせは、PI 経由で Codex OAuth/サブスクリプション認証を使いたい場合には有効ですが、ネイティブ Codex アプリサーバーハーネスと混同しやすいものです。doctor は警告し、明示的なアプリサーバー形式を示します: `openai/*` と `agentRuntime.id: "codex"`、または `OPENCLAW_AGENT_RUNTIME=codex`。 + バンドルされた Codex Plugin が有効な場合、doctor は `openai-codex/*` のプライマリモデル参照がまだデフォルトの PI ランナー経由で解決されるかどうかも確認します。この組み合わせは PI 経由で Codex OAuth/サブスクリプション認証を使いたい場合には有効ですが、ネイティブ Codex アプリサーバーハーネスと混同しやすいものです。doctor は警告し、明示的なアプリサーバー形状として `openai/*` と `agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を示します。 - doctor はこれを自動修復しません。どちらのルートも有効だからです。 + 両方のルートが有効であるため、doctor はこれを自動修復しません。 - - `openai-codex/*` + PI は「通常の OpenClaw ランナー経由で Codex OAuth/サブスクリプション認証を使う」ことを意味します。 - - `openai/*` + `runtime: "codex"` は「埋め込みターンをネイティブ Codex アプリサーバー経由で実行する」ことを意味します。 - - `/codex ...` は「チャットからネイティブ Codex 会話を制御またはバインドする」ことを意味します。 - - `/acp ...` または `runtime: "acp"` は「外部 ACP/acpx アダプターを使用する」ことを意味します。 + - `openai-codex/*` + PI は「通常の OpenClaw ランナー経由で Codex OAuth/サブスクリプション認証を使う」という意味です。 + - `openai/*` + `runtime: "codex"` は「埋め込みターンをネイティブ Codex アプリサーバー経由で実行する」という意味です。 + - `/codex ...` は「チャットからネイティブ Codex 会話を制御またはバインドする」という意味です。 + - `/acp ...` または `runtime: "acp"` は「外部 ACP/acpx アダプターを使う」という意味です。 - 警告が表示された場合は、意図したルートを選び、設定を手動で編集してください。PI Codex OAuth が意図したものである場合は、警告をそのままにしてください。 + 警告が表示された場合は、意図したルートを選び、設定を手動で編集してください。PI Codex OAuth が意図したものなら、警告はそのままにします。 - + doctor は古いオンディスクレイアウトを現在の構造へ移行できます。 - - セッションストアとトランスクリプト: + - セッションストア + トランスクリプト: - `~/.openclaw/sessions/` から `~/.openclaw/agents//sessions/` へ - エージェントディレクトリ: - `~/.openclaw/agent/` から `~/.openclaw/agents//agent/` へ @@ -279,16 +284,16 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - レガシー `~/.openclaw/credentials/*.json` から（`oauth.json` を除く） - `~/.openclaw/credentials/whatsapp//...` へ（デフォルトアカウント ID: `default`） - これらの移行はベストエフォートで冪等です。doctor はレガシーフォルダーをバックアップとして残す場合、警告を出します。Gateway/CLI も起動時にレガシーのセッションとエージェントディレクトリを自動移行するため、手動で doctor を実行しなくても、履歴/認証/モデルはエージェントごとのパスに配置されます。WhatsApp 認証は意図的に `openclaw doctor` 経由でのみ移行されます。Talk プロバイダー/プロバイダーマップの正規化は現在、構造的等価性で比較するため、キー順序のみの差分では `doctor --fix` の無操作変更が繰り返し発生しなくなりました。 + これらの移行はベストエフォートで冪等です。doctor は、バックアップとしてレガシーフォルダーを残す場合に警告を出します。Gateway/CLI も起動時にレガシーセッションとエージェントディレクトリを自動移行するため、手動で doctor を実行しなくても履歴/認証/モデルはエージェントごとのパスに配置されます。WhatsApp 認証は意図的に `openclaw doctor` 経由でのみ移行されます。Talk プロバイダー/プロバイダーマップの正規化は構造的等価性で比較するようになったため、キー順序だけの差分では、繰り返しの no-op `doctor --fix` 変更が発生しなくなりました。 - - doctor は、非推奨のトップレベル機能キー（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）がないか、インストール済み Plugin マニフェストをすべてスキャンします。見つかった場合、それらを `contracts` オブジェクトへ移動し、マニフェストファイルをインプレースで書き換えることを提案します。この移行は冪等です。`contracts` キーに同じ値がすでにある場合、データを重複させずにレガシーキーが削除されます。 + + doctor は、非推奨のトップレベル機能キー（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）について、インストール済みのすべての Plugin マニフェストをスキャンします。見つかった場合、それらを `contracts` オブジェクトへ移動し、マニフェストファイルをその場で書き換えることを提案します。この移行は冪等です。`contracts` キーにすでに同じ値がある場合、データを重複させずにレガシーキーが削除されます。 - - doctor は Cron ジョブストア（デフォルトでは `~/.openclaw/cron/jobs.json`、またはオーバーライド時は `cron.store`）について、スケジューラーが互換性のためにまだ受け入れる古いジョブ形状も確認します。 + + doctor は、互換性のためスケジューラーがまだ受け入れる古いジョブ形状について、Cron ジョブストア（デフォルトでは `~/.openclaw/cron/jobs.json`、オーバーライドされている場合は `cron.store`）も確認します。 - 現在の Cron クリーンアップには次が含まれます。 + 現在の Cron クリーンアップには以下が含まれます。 - `jobId` → `id` - `schedule.cron` → `schedule.expr` @@ -297,189 +302,189 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - ペイロードの `provider` 配信エイリアス → 明示的な `delivery.channel` - 単純なレガシー `notify: true` Webhook フォールバックジョブ → `delivery.to=cron.webhook` を伴う明示的な `delivery.mode="webhook"` - doctor は、動作を変更せずに実行できる場合にのみ `notify: true` ジョブを自動移行します。ジョブがレガシー通知フォールバックと既存の非 Webhook 配信モードを組み合わせている場合、doctor は警告し、そのジョブを手動レビュー用に残します。 + doctor は、動作を変えずに実行できる場合にのみ `notify: true` ジョブを自動移行します。ジョブがレガシー通知フォールバックと既存の非 Webhook 配信モードを組み合わせている場合、doctor は警告し、そのジョブを手動レビュー用に残します。 - doctor は、各エージェントセッションディレクトリで古い書き込みロックファイル、つまりセッションが異常終了したときに残されたファイルをスキャンします。見つかった各ロックファイルについて、パス、PID、PID がまだ生存しているか、ロックの経過時間、古いと見なされるか（死んだ PID または 30 分超）を報告します。`--fix` / `--repair` モードでは古いロックファイルを自動的に削除します。それ以外の場合は注記を表示し、`--fix` で再実行するよう指示します。 + doctor は、古い書き込みロックファイル、つまりセッションが異常終了したときに残されたファイルについて、すべてのエージェントセッションディレクトリをスキャンします。見つかった各ロックファイルについて、パス、PID、その PID がまだ生存しているか、ロックの経過時間、古いと見なされるかどうか（終了済み PID または 30 分超）を報告します。`--fix` / `--repair` モードでは、古いロックファイルを自動的に削除します。それ以外の場合は注記を出力し、`--fix` を付けて再実行するよう指示します。 - doctor は、2026.4.24 のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形状がないか、エージェントセッション JSONL ファイルをスキャンします。これは、OpenClaw 内部ランタイムコンテキストを持つ放棄されたユーザーターンと、同じ可視ユーザープロンプトを含むアクティブな兄弟がある形状です。`--fix` / `--repair` モードでは、doctor は影響を受けた各ファイルを元ファイルの隣にバックアップし、Gateway 履歴とメモリーリーダーが重複ターンを見なくなるよう、トランスクリプトをアクティブブランチへ書き換えます。 + doctor は、2026.4.24 のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形状について、エージェントセッション JSONL ファイルをスキャンします。その形状は、OpenClaw 内部ランタイムコンテキストを持つ放棄されたユーザーターンと、同じ表示ユーザープロンプトを含むアクティブな兄弟から成ります。`--fix` / `--repair` モードでは、doctor は影響を受けた各ファイルを元ファイルの隣にバックアップし、トランスクリプトをアクティブブランチへ書き換えることで、Gateway 履歴とメモリーリーダーが重複ターンを見ないようにします。 - - 状態ディレクトリは運用上の中枢です。これが消えると、セッション、認証情報、ログ、設定を失います（別の場所にバックアップがない限り）。 + + 状態ディレクトリは運用上の中枢です。これが消えると、セッション、認証情報、ログ、設定を失います（ほかにバックアップがある場合を除く）。 - doctor は次を確認します。 + doctor は以下を確認します。 - - **状態ディレクトリの欠落**: 破滅的な状態喪失について警告し、ディレクトリの再作成を促し、失われたデータは復旧できないことを通知します。 - - **状態ディレクトリの権限**: 書き込み可能性を検証します。権限の修復を提案します（所有者/グループの不一致が検出された場合は `chown` ヒントを出します）。 - - **macOS のクラウド同期状態ディレクトリ**: 状態が iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）または `~/Library/CloudStorage/...` の下に解決される場合に警告します。同期バックアップ付きパスは I/O が遅くなり、ロック/同期競合を引き起こす可能性があるためです。 - - **Linux の SD または eMMC 状態ディレクトリ**: 状態が `mmcblk*` マウントソースへ解決される場合に警告します。SD または eMMC バックのランダム I/O は、セッションと認証情報の書き込み時に遅く、摩耗が早くなる可能性があるためです。 - - **セッションディレクトリの欠落**: 履歴を永続化し、`ENOENT` クラッシュを避けるため、`sessions/` とセッションストアディレクトリが必要です。 - - **トランスクリプトの不一致**: 最近のセッションエントリにトランスクリプトファイルが欠落している場合に警告します。 - - **メインセッション「1 行 JSONL」**: メイントランスクリプトが 1 行だけの場合にフラグを立てます（履歴が蓄積されていません）。 - - **複数の状態ディレクトリ**: ホームディレクトリ間に複数の `~/.openclaw` フォルダーが存在する場合、または `OPENCLAW_STATE_DIR` が別の場所を指している場合に警告します（履歴がインストール間で分割される可能性があります）。 - - **リモートモードのリマインダー**: `gateway.mode=remote` の場合、doctor はリモートホストで実行するよう通知します（状態はそこにあります）。 - - **設定ファイルの権限**: `~/.openclaw/openclaw.json` がグループ/全員に読み取り可能な場合に警告し、`600` へ厳格化することを提案します。 + - **状態ディレクトリがない**: 壊滅的な状態データの喪失について警告し、ディレクトリの再作成を促し、不足しているデータは復元できないことを通知します。 + - **状態ディレクトリの権限**: 書き込み可能かを検証します。権限の修復を提案します（所有者/グループの不一致が検出された場合は `chown` のヒントも出力します）。 + - **macOS のクラウド同期された状態ディレクトリ**: 状態が iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）または `~/Library/CloudStorage/...` の下に解決される場合に警告します。同期対象のパスでは I/O が遅くなり、ロック/同期の競合が発生する可能性があるためです。 + - **Linux の SD または eMMC 状態ディレクトリ**: 状態が `mmcblk*` マウントソースに解決される場合に警告します。SD または eMMC ベースのランダム I/O は、セッションや認証情報の書き込み時に遅く、消耗が速くなる可能性があるためです。 + - **セッションディレクトリがない**: 履歴を永続化し、`ENOENT` クラッシュを避けるには、`sessions/` とセッションストアディレクトリが必要です。 + - **トランスクリプトの不一致**: 最近のセッションエントリに対応するトランスクリプトファイルがない場合に警告します。 + - **メインセッション「1 行 JSONL」**: メインのトランスクリプトが 1 行しかない場合にフラグを立てます（履歴が蓄積されていません）。 + - **複数の状態ディレクトリ**: 複数の `~/.openclaw` フォルダがホームディレクトリ間に存在する場合、または `OPENCLAW_STATE_DIR` が別の場所を指している場合に警告します（履歴がインストール間で分断される可能性があります）。 + - **リモートモードのリマインダー**: `gateway.mode=remote` の場合、doctor はリモートホスト上で実行するよう通知します（状態はそこにあります）。 + - **設定ファイルの権限**: `~/.openclaw/openclaw.json` がグループ/全員に読み取り可能な場合に警告し、`600` に厳格化することを提案します。 - - doctor は認証ストア内の OAuth プロファイルを検査し、トークンが期限切れ間近または期限切れの場合に警告し、安全な場合は更新できます。Anthropic OAuth/トークンプロファイルが古い場合、Anthropic API キーまたは Anthropic セットアップトークンパスを提案します。更新プロンプトは対話的に実行している場合（TTY）にのみ表示されます。`--non-interactive` は更新の試行をスキップします。 + + Doctor は認証ストア内の OAuth プロファイルを検査し、トークンが期限切れ間近または期限切れの場合に警告し、安全な場合は更新できます。Anthropic OAuth/トークンプロファイルが古い場合は、Anthropic API キーまたは Anthropic セットアップトークンの経路を提案します。更新プロンプトは対話的に実行している場合（TTY）にのみ表示されます。`--non-interactive` では更新の試行をスキップします。 - OAuth 更新が恒久的に失敗した場合（例: `refresh_token_reused`、`invalid_grant`、またはプロバイダーが再サインインを求める場合）、doctor は再認証が必要であることを報告し、実行すべき正確な `openclaw models auth login --provider ...` コマンドを出力します。 + OAuth 更新が恒久的に失敗した場合（たとえば `refresh_token_reused`、`invalid_grant`、またはプロバイダーが再サインインを求めている場合）、doctor は再認証が必要であることを報告し、実行すべき正確な `openclaw models auth login --provider ...` コマンドを表示します。 - doctor は、次の理由により一時的に利用できない認証プロファイルも報告します。 + Doctor は、次の理由で一時的に使用できない認証プロファイルも報告します。 - 短いクールダウン（レート制限/タイムアウト/認証失敗） - より長い無効化（請求/クレジット失敗） - - `hooks.gmail.model` が設定されている場合、doctor はモデル参照をカタログおよび許可リストと照合して検証し、解決できない、または許可されていない場合に警告します。 + + `hooks.gmail.model` が設定されている場合、doctor はモデル参照をカタログおよび許可リストに照らして検証し、解決できない場合や許可されていない場合に警告します。 - - サンドボックスが有効な場合、doctor は Docker イメージを確認し、現在のイメージが見つからない場合は、ビルドするかレガシー名へ切り替えることを提案します。 + + サンドボックス化が有効な場合、doctor は Docker イメージを確認し、現在のイメージがない場合はビルドまたはレガシー名への切り替えを提案します。 - - Doctor は、現在の設定でアクティブなバンドル済みプラグイン、またはバンドル済みマニフェストのデフォルトで有効になっているバンドル済みプラグインについてのみ、ランタイム依存関係を検証します。例として、`plugins.entries.discord.enabled: true`、レガシーの `channels.discord.enabled: true`、設定済みの `models.providers.*` / エージェントモデル参照、またはプロバイダー所有権のないデフォルト有効のバンドル済みプラグインがあります。不足しているものがある場合、doctor はパッケージを報告し、`openclaw doctor --fix` / `openclaw doctor --repair` モードでそれらをインストールします。外部プラグインは引き続き `openclaw plugins install` / `openclaw plugins update` を使用します。doctor は任意のプラグインパスに対して依存関係をインストールしません。 + + Doctor は、現在の設定でアクティブなバンドル済み Plugin、またはバンドル済みマニフェストのデフォルトで有効化される Plugin についてのみランタイム依存関係を検証します。たとえば、`plugins.entries.discord.enabled: true`、レガシーの `channels.discord.enabled: true`、設定済みの `models.providers.*` / エージェントモデル参照、またはプロバイダー所有権のないデフォルト有効のバンドル済み Plugin です。不足がある場合、doctor はパッケージを報告し、`openclaw doctor --fix` / `openclaw doctor --repair` モードでインストールします。外部 Plugin は引き続き `openclaw plugins install` / `openclaw plugins update` を使用します。doctor は任意の Plugin パスの依存関係をインストールしません。 - doctor の修復中、バンドル済みランタイム依存関係の npm インストールは、TTY セッションではスピナー進捗を、パイプまたはヘッドレス出力では定期的な行単位の進捗を報告します。Gateway とローカル CLI は、バンドル済みプラグインをインポートする前に、必要に応じてアクティブなバンドル済みプラグインのランタイム依存関係も修復できます。これらのインストールはプラグインランタイムのインストールルートにスコープされ、スクリプトを無効化して実行され、パッケージロックを書き込まず、インストールルートのロックで保護されるため、同時実行される CLI または Gateway の起動が同じ `node_modules` ツリーを同時に変更することはありません。 + doctor の修復中、バンドル済みランタイム依存関係の npm インストールは、TTY セッションではスピナー進捗を、パイプ/ヘッドレス出力では定期的な行進捗を報告します。Gateway とローカル CLI も、バンドル済み Plugin をインポートする前に、アクティブなバンドル済み Plugin のランタイム依存関係を必要に応じて修復できます。これらのインストールは Plugin ランタイムインストールルートに限定され、スクリプトを無効化して実行され、パッケージロックを書き込まず、インストールルートロックで保護されるため、同時に開始された CLI や Gateway が同じ `node_modules` ツリーを同時に変更することはありません。 - - Doctor はレガシーの gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して現在の gateway ポートを使用する OpenClaw サービスをインストールすることを提案します。また、追加の gateway 風サービスをスキャンして、クリーンアップのヒントを出力することもできます。プロファイル名付きの OpenClaw gateway サービスは第一級のものとみなされ、「extra」としてフラグされません。 + + Doctor はレガシー Gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して現在の Gateway ポートを使用する OpenClaw サービスをインストールすることを提案します。追加の Gateway 風サービスをスキャンしてクリーンアップのヒントを表示することもできます。プロファイル名付きの OpenClaw Gateway サービスは第一級のものと見なされ、「余分」としてフラグ付けされません。 - Linux では、ユーザーレベルの gateway サービスが存在しない一方で、システムレベルの OpenClaw gateway サービスが存在する場合、doctor は 2 つ目のユーザーレベルサービスを自動的にはインストールしません。`openclaw gateway status --deep` または `openclaw doctor --deep` で確認してから、重複を削除するか、システムのスーパーバイザーが gateway ライフサイクルを所有している場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定してください。 + Linux では、ユーザーレベルの Gateway サービスがない一方でシステムレベルの OpenClaw Gateway サービスが存在する場合、doctor は 2 つ目のユーザーレベルサービスを自動ではインストールしません。`openclaw gateway status --deep` または `openclaw doctor --deep` で調査し、重複を削除するか、システム supervisor が Gateway ライフサイクルを所有している場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定してください。 - Matrix チャネルアカウントに保留中または対応可能なレガシー状態移行がある場合、doctor は（`--fix` / `--repair` モードで）移行前スナップショットを作成し、その後ベストエフォートの移行手順を実行します。レガシー Matrix 状態移行とレガシー暗号化状態の準備です。どちらの手順も致命的ではありません。エラーはログに記録され、起動は継続します。読み取り専用モード（`--fix` なしの `openclaw doctor`）では、このチェックは完全にスキップされます。 + Matrix チャネルアカウントに保留中または対応可能なレガシー状態移行がある場合、doctor は（`--fix` / `--repair` モードで）移行前スナップショットを作成し、その後ベストエフォートの移行手順を実行します。レガシー Matrix 状態移行と、レガシー暗号化状態の準備です。どちらの手順も致命的ではありません。エラーはログに記録され、起動は続行します。読み取り専用モード（`--fix` なしの `openclaw doctor`）では、このチェックは完全にスキップされます。 - - Doctor は通常のヘルスパスの一部として、デバイスペアリング状態を検査するようになりました。 + + Doctor は通常の健全性チェックの一部として、デバイスペアリング状態を検査するようになりました。 報告内容: - - 保留中の初回ペアリング要求 + - 保留中の初回ペアリングリクエスト - すでにペアリング済みのデバイスに対する保留中のロールアップグレード - すでにペアリング済みのデバイスに対する保留中のスコープアップグレード - - デバイス ID はまだ一致しているが、デバイス ID 情報が承認済みレコードと一致しなくなった場合の公開鍵不一致修復 + - デバイス ID はまだ一致しているが、デバイス ID 情報が承認済みレコードと一致しなくなった公開鍵不一致の修復 - 承認済みロールのアクティブなトークンがないペアリング済みレコード - - スコープが承認済みペアリングベースラインの外へずれたペアリング済みトークン - - gateway 側のトークンローテーションより古い、または古いスコープメタデータを持つ、現在のマシン用のローカルキャッシュ済みデバイストークンエントリ + - 承認済みペアリングベースラインの外へスコープがずれたペアリング済みトークン + - Gateway 側のトークンローテーションより古い、または古いスコープメタデータを持つ、現在のマシンのローカルキャッシュ済みデバイストークンエントリ - Doctor はペアリング要求を自動承認したり、デバイストークンを自動ローテーションしたりしません。代わりに正確な次の手順を出力します。 + Doctor はペアリングリクエストを自動承認したり、デバイストークンを自動ローテーションしたりしません。代わりに正確な次の手順を表示します。 - - `openclaw devices list` で保留中の要求を確認する - - `openclaw devices approve ` で正確な要求を承認する + - `openclaw devices list` で保留中のリクエストを調査する + - `openclaw devices approve ` で正確なリクエストを承認する - `openclaw devices rotate --device --role ` で新しいトークンをローテーションする - `openclaw devices remove ` で古いレコードを削除して再承認する - これにより、よくある「すでにペアリング済みなのに、まだペアリングが必要と表示される」穴が塞がれます。doctor は初回ペアリング、保留中のロール/スコープアップグレード、古いトークン/デバイス ID 情報のずれを区別するようになりました。 + これにより、よくある「すでにペアリング済みなのにまだペアリングが必要と表示される」問題が解消されます。doctor は初回ペアリングを、保留中のロール/スコープアップグレードや、古いトークン/デバイス ID 情報のドリフトと区別するようになりました。 - Doctor は、プロバイダーが許可リストなしで DM に開放されている場合、またはポリシーが危険な方法で設定されている場合に警告を出します。 + Doctor は、プロバイダーが許可リストなしで DM に開かれている場合、またはポリシーが危険な方法で設定されている場合に警告を出力します。 - systemd ユーザーサービスとして実行している場合、doctor はログアウト後も gateway が稼働し続けるよう lingering が有効であることを確認します。 + systemd ユーザーサービスとして実行している場合、doctor はログアウト後も Gateway が稼働し続けるよう linger が有効になっていることを確認します。 - - Doctor はデフォルトエージェントのワークスペース状態の概要を出力します。 + + Doctor はデフォルトエージェントのワークスペース状態の概要を表示します。 - - **Skills 状態**: 対象、要件不足、許可リストでブロックされた Skills の数。 - - **レガシーワークスペースディレクトリ**: `~/openclaw` またはその他のレガシーワークスペースディレクトリが現在のワークスペースと並んで存在する場合に警告します。 - - **プラグイン状態**: 有効/無効/エラーのプラグイン数を数えます。エラーがある場合はプラグイン ID を列挙します。バンドルプラグインの機能を報告します。 - - **プラグイン互換性警告**: 現在のランタイムとの互換性の問題があるプラグインにフラグを付けます。 - - **プラグイン診断**: プラグインレジストリがロード時に出力した警告またはエラーを表示します。 + - **Skills 状態**: 対象、要件不足、許可リストでブロックされた Skills の数を数えます。 + - **レガシーワークスペースディレクトリ**: `~/openclaw` または他のレガシーワークスペースディレクトリが現在のワークスペースと並んで存在する場合に警告します。 + - **Plugin 状態**: 有効/無効/エラーの Plugin 数を数えます。エラーがある場合は Plugin ID を一覧表示します。バンドル Plugin の機能を報告します。 + - **Plugin 互換性警告**: 現在のランタイムと互換性の問題がある Plugin にフラグを立てます。 + - **Plugin 診断**: Plugin レジストリがロード時に出力した警告やエラーを表示します。 - Doctor は、ワークスペースのブートストラップファイル（例: `AGENTS.md`、`CLAUDE.md`、またはその他の注入済みコンテキストファイル）が、設定された文字数予算に近い、または超過していないかを確認します。ファイルごとの生の文字数と注入済み文字数、切り詰め率、切り詰め原因（`max/file` または `max/total`）、および合計注入文字数を合計予算に対する割合として報告します。ファイルが切り詰められている、または上限に近い場合、doctor は `agents.defaults.bootstrapMaxChars` と `agents.defaults.bootstrapTotalMaxChars` を調整するためのヒントを出力します。 + Doctor は、ワークスペースのブートストラップファイル（たとえば `AGENTS.md`、`CLAUDE.md`、またはその他の挿入済みコンテキストファイル）が、設定済みの文字数予算に近いか超過しているかを確認します。ファイルごとの raw と挿入後の文字数、切り詰め率、切り詰め原因（`max/file` または `max/total`）、および合計挿入文字数が総予算に占める割合を報告します。ファイルが切り詰められている、または上限に近い場合、doctor は `agents.defaults.bootstrapMaxChars` と `agents.defaults.bootstrapTotalMaxChars` の調整に関するヒントを表示します。 - - `openclaw doctor --fix` が見つからないチャネルプラグインを削除する場合、そのプラグインを参照していたぶら下がったチャネルスコープ設定も削除します。`channels.` エントリ、チャネル名を指定した heartbeat ターゲット、および `agents.*.models["/*"]` オーバーライドです。これにより、チャネルランタイムがなくなっているのに設定が gateway にそれへのバインドを求め続ける Gateway ブートループを防ぎます。 + + `openclaw doctor --fix` が不足しているチャネル Plugin を削除する場合、その Plugin を参照していたぶら下がりのチャネルスコープ設定も削除します。`channels.` エントリ、そのチャネル名を指定していた Heartbeat ターゲット、`agents.*.models["/*"]` オーバーライドです。これにより、チャネルランタイムがなくなっているのに設定が Gateway にバインドを求め続ける Gateway ブートループを防ぎます。 Doctor は、現在のシェル（zsh、bash、fish、または PowerShell）にタブ補完がインストールされているかを確認します。 - - シェルプロファイルが低速な動的補完パターン（`source <(openclaw completion ...)`）を使用している場合、doctor はそれをより高速なキャッシュ済みファイルのバリアントへアップグレードします。 - - 補完がプロファイルに設定されているがキャッシュファイルがない場合、doctor はキャッシュを自動的に再生成します。 - - 補完がまったく設定されていない場合、doctor はインストールを促します（インタラクティブモードのみ。`--non-interactive` ではスキップ）。 + - シェルプロファイルが遅い動的補完パターン（`source <(openclaw completion ...)`）を使用している場合、doctor はより高速なキャッシュファイル方式にアップグレードします。 + - 補完がプロファイルで設定されているがキャッシュファイルがない場合、doctor はキャッシュを自動で再生成します。 + - 補完がまったく設定されていない場合、doctor はインストールを促します（対話モードのみ。`--non-interactive` ではスキップされます）。 - キャッシュを手動で再生成するには、`openclaw completion --write-state` を実行してください。 + キャッシュを手動で再生成するには `openclaw completion --write-state` を実行してください。 - Doctor はローカル gateway トークン認証の準備状態を確認します。 + Doctor はローカル Gateway トークン認証の準備状態を確認します。 - トークンモードでトークンが必要で、トークンソースが存在しない場合、doctor は生成を提案します。 - - `gateway.auth.token` が SecretRef 管理だが利用できない場合、doctor は警告し、平文で上書きしません。 + - `gateway.auth.token` が SecretRef 管理で利用できない場合、doctor は警告し、平文で上書きしません。 - `openclaw doctor --generate-gateway-token` は、トークン SecretRef が設定されていない場合にのみ生成を強制します。 - 一部の修復フローでは、ランタイムのフェイルファスト動作を弱めずに、設定済みの認証情報を検査する必要があります。 + 一部の修復フローでは、ランタイムの fail-fast 動作を弱めずに設定済み認証情報を検査する必要があります。 - - `openclaw doctor --fix` は、対象を絞った設定修復に、ステータス系コマンドと同じ読み取り専用 SecretRef サマリーモデルを使用するようになりました。 - - 例: Telegram の `allowFrom` / `groupAllowFrom` `@username` 修復は、利用可能な場合、設定済みのボット認証情報を使用しようとします。 - - Telegram ボットトークンが SecretRef 経由で設定されているが、現在のコマンドパスで利用できない場合、doctor はその認証情報が設定済みだが利用不可であることを報告し、クラッシュしたりトークンがないと誤報告したりする代わりに自動解決をスキップします。 + - `openclaw doctor --fix` は、対象を絞った設定修復に、status 系コマンドと同じ読み取り専用 SecretRef サマリーモデルを使用するようになりました。 + - 例: Telegram の `allowFrom` / `groupAllowFrom` `@username` 修復は、利用可能な場合に設定済み bot 認証情報の使用を試みます。 + - Telegram bot トークンが SecretRef 経由で設定されているが、現在のコマンド経路で利用できない場合、doctor はその認証情報が設定済みだが利用不可であることを報告し、クラッシュしたりトークンがないと誤報告したりする代わりに自動解決をスキップします。 - - Doctor はヘルスチェックを実行し、gateway が異常に見える場合は再起動を提案します。 + + Doctor は健全性チェックを実行し、Gateway が不健全に見える場合は再起動を提案します。 - Doctor は、設定済みのメモリ検索埋め込みプロバイダーがデフォルトエージェントに対して準備できているかを確認します。動作は設定されたバックエンドとプロバイダーによって異なります。 + Doctor は、設定済みのメモリ検索埋め込みプロバイダーがデフォルトエージェントで使用可能かどうかを確認します。動作は、設定されたバックエンドとプロバイダーによって異なります。 - - **QMD バックエンド**: `qmd` バイナリが利用可能で起動可能かをプローブします。そうでない場合は、npm パッケージと手動バイナリパスのオプションを含む修正ガイダンスを出力します。 + - **QMD バックエンド**: `qmd` バイナリが利用可能で起動可能かどうかをプローブします。そうでない場合、npm パッケージや手動バイナリパスの選択肢を含む修正ガイダンスを表示します。 - **明示的なローカルプロバイダー**: ローカルモデルファイル、または認識済みのリモート/ダウンロード可能なモデル URL を確認します。不足している場合は、リモートプロバイダーへの切り替えを提案します。 - - **明示的なリモートプロバイダー**（`openai`、`voyage` など）: API キーが環境または認証ストアに存在することを検証します。不足している場合は、実行可能な修正ヒントを出力します。 - - **自動プロバイダー**: まずローカルモデルの可用性を確認し、その後、自動選択順に各リモートプロバイダーを試します。 + - **明示的なリモートプロバイダー**（`openai`、`voyage` など）: API キーが環境または認証ストアに存在することを検証します。不足している場合は、実行可能な修正ヒントを表示します。 + - **自動プロバイダー**: まずローカルモデルの可用性を確認し、その後、自動選択順で各リモートプロバイダーを試します。 - キャッシュ済み gateway プローブ結果が利用可能な場合（チェック時点で gateway が正常だった場合）、doctor はその結果を CLI から見える設定と相互参照し、差異があれば通知します。doctor はデフォルトパスで新しい埋め込み ping を開始しません。ライブのプロバイダーチェックが必要な場合は、詳細なメモリ状態コマンドを使用してください。 + キャッシュされた Gateway プローブ結果が利用可能な場合（チェック時点で Gateway が正常だった場合）、doctor はその結果を CLI から見える設定と照合し、不一致があれば記録します。Doctor はデフォルトパスでは新しい埋め込み ping を開始しません。ライブのプロバイダーチェックが必要な場合は、deep memory status コマンドを使用します。 - 実行時の埋め込み準備状態を検証するには、`openclaw memory status --deep` を使用してください。 + 実行時の埋め込み準備状態を確認するには `openclaw memory status --deep` を使用します。 - - gateway が正常な場合、doctor はチャネル状態プローブを実行し、推奨される修正とともに警告を報告します。 + + Gateway が正常な場合、doctor はチャンネルステータスプローブを実行し、推奨される修正とともに警告を報告します。 - - Doctor は、インストール済みのスーパーバイザー設定（launchd/systemd/schtasks）について、欠落または古くなったデフォルト（例: systemd の network-online 依存関係と再起動遅延）を確認します。不一致を見つけた場合、更新を推奨し、サービスファイル/タスクを現在のデフォルトに書き換えることができます。 + + Doctor はインストール済みの supervisor 設定（launchd/systemd/schtasks）に、欠落または古いデフォルト（例: systemd の network-online 依存関係や再起動遅延）がないか確認します。不一致が見つかった場合は更新を推奨し、サービスファイル/タスクを現在のデフォルトに書き換えることができます。 - 注: + 注記: - - `openclaw doctor` はスーパーバイザー設定を書き換える前に確認します。 + - `openclaw doctor` は supervisor 設定を書き換える前に確認を求めます。 - `openclaw doctor --yes` はデフォルトの修復プロンプトを承認します。 - `openclaw doctor --repair` はプロンプトなしで推奨修正を適用します。 - - `openclaw doctor --repair --force` はカスタムのスーパーバイザー設定を上書きします。 - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` は Gateway サービスのライフサイクルについて doctor を読み取り専用のままにします。サービスの健全性は引き続き報告し、サービス以外の修復も実行しますが、外部スーパーバイザーがそのライフサイクルを所有しているため、サービスのインストール/開始/再起動/ブートストラップ、スーパーバイザー設定の書き換え、レガシーサービスのクリーンアップはスキップします。 - - Linux では、一致する systemd Gateway ユニットがアクティブな間、doctor はコマンド/エントリポイントのメタデータを書き換えません。また、重複サービスのスキャン中に非アクティブで非レガシーの追加 Gateway 風ユニットを無視するため、関連サービスファイルによってクリーンアップのノイズが発生しません。 - - トークン認証にトークンが必要で、`gateway.auth.token` が SecretRef 管理の場合、doctor のサービスインストール/修復は SecretRef を検証しますが、解決済みの平文トークン値をスーパーバイザーサービス環境メタデータには永続化しません。 - - Doctor は、古い LaunchAgent、systemd、または Windows Scheduled Task のインストールがインラインで埋め込んだ、管理対象の `.env`/SecretRef ベースのサービス環境値を検出し、それらの値がスーパーバイザー定義ではなくランタイムソースから読み込まれるようにサービスメタデータを書き換えます。 - - Doctor は、`gateway.port` の変更後もサービスコマンドが古い `--port` に固定されている場合に検出し、サービスメタデータを現在のポートに書き換えます。 - - トークン認証にトークンが必要で、設定済みのトークン SecretRef が解決されていない場合、doctor は実行可能なガイダンスを示してインストール/修復パスをブロックします。 - - `gateway.auth.token` と `gateway.auth.password` の両方が設定され、`gateway.auth.mode` が未設定の場合、doctor はモードが明示的に設定されるまでインストール/修復をブロックします。 - - Linux のユーザー systemd ユニットでは、doctor のトークンドリフトチェックは、サービス認証メタデータを比較するときに `Environment=` と `EnvironmentFile=` の両方のソースを含むようになりました。 + - `openclaw doctor --repair --force` はカスタム supervisor 設定を上書きします。 + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` は Gateway サービスライフサイクルについて doctor を読み取り専用にします。サービスの健全性を引き続き報告し、サービス以外の修復も実行しますが、外部 supervisor がそのライフサイクルを所有しているため、サービスのインストール/開始/再起動/bootstrap、supervisor 設定の書き換え、レガシーサービスのクリーンアップはスキップします。 + - Linux では、対応する systemd Gateway ユニットがアクティブな間、doctor はコマンド/エントリポイントのメタデータを書き換えません。また、重複サービスのスキャン中は、非アクティブな非レガシーの追加 Gateway 風ユニットを無視するため、付随するサービスファイルがクリーンアップのノイズを生みません。 + - トークン認証にトークンが必要で、`gateway.auth.token` が SecretRef 管理の場合、doctor のサービスインストール/修復は SecretRef を検証しますが、解決済みの平文トークン値を supervisor サービス環境メタデータには永続化しません。 + - Doctor は、古い LaunchAgent、systemd、または Windows Scheduled Task のインストールがインラインに埋め込んだ、管理対象の `.env`/SecretRef ベースのサービス環境値を検出し、それらの値が supervisor 定義ではなく実行時ソースから読み込まれるようにサービスメタデータを書き換えます。 + - Doctor は、`gateway.port` の変更後もサービスコマンドが古い `--port` を固定している場合に検出し、サービスメタデータを現在のポートに書き換えます。 + - トークン認証にトークンが必要で、設定されたトークン SecretRef が解決されていない場合、doctor は実行可能な案内とともにインストール/修復パスをブロックします。 + - `gateway.auth.token` と `gateway.auth.password` の両方が設定され、`gateway.auth.mode` が未設定の場合、doctor は mode が明示的に設定されるまでインストール/修復をブロックします。 + - Linux user-systemd ユニットでは、doctor のトークンドリフトチェックは、サービス認証メタデータの比較時に `Environment=` と `EnvironmentFile=` の両方のソースを含むようになりました。 - Doctor のサービス修復は、設定がより新しいバージョンによって最後に書き込まれている場合、古い OpenClaw バイナリから Gateway サービスを書き換えたり、停止したり、再起動したりすることを拒否します。[Gateway トラブルシューティング](/ja-JP/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)を参照してください。 - - `openclaw gateway install --force` を使えば、いつでも完全な書き換えを強制できます。 + - `openclaw gateway install --force` を使用すれば、いつでも完全な書き換えを強制できます。 - Doctor はサービスランタイム（PID、直近の終了ステータス）を検査し、サービスがインストールされているのに実際には実行されていない場合に警告します。また、Gateway ポート（デフォルトは `18789`）でポート競合がないか確認し、考えられる原因（Gateway がすでに実行中、SSH トンネル）を報告します。 + Doctor はサービスランタイム（PID、最後の終了ステータス）を検査し、サービスがインストールされているのに実際には実行されていない場合に警告します。また、Gateway ポート（デフォルト `18789`）のポート衝突を確認し、考えられる原因（Gateway がすでに実行中、SSH トンネル）を報告します。 - Doctor は、Gateway サービスが Bun またはバージョン管理された Node パス（`nvm`、`fnm`、`volta`、`asdf` など）で実行されている場合に警告します。WhatsApp + Telegram チャネルには Node が必要であり、バージョンマネージャーのパスは、サービスがシェル初期化を読み込まないため、アップグレード後に壊れる可能性があります。Doctor は、利用可能な場合はシステムの Node インストール（Homebrew/apt/choco）へ移行するよう提案します。 + Doctor は、Gateway サービスが Bun またはバージョン管理された Node パス（`nvm`、`fnm`、`volta`、`asdf` など）で実行されている場合に警告します。WhatsApp + Telegram チャンネルには Node が必要であり、バージョンマネージャーのパスは、サービスがシェル初期化を読み込まないため、アップグレード後に壊れる可能性があります。Doctor は、利用可能な場合にシステムの Node インストール（Homebrew/apt/choco）への移行を提案します。 - 新規インストールまたは修復されたサービスは、明示的な環境ルート（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）と安定したユーザー bin ディレクトリを保持しますが、推測されたバージョンマネージャーのフォールバックディレクトリは、そのディレクトリがディスク上に存在する場合にのみサービス PATH に書き込まれます。これにより、生成されたスーパーバイザー PATH が、後で doctor が実行する同じ最小 PATH 監査と整合します。 + 新しくインストールまたは修復されたサービスは、明示的な環境ルート（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）と安定したユーザー bin ディレクトリを保持しますが、推測されたバージョンマネージャーのフォールバックディレクトリは、それらのディレクトリがディスク上に存在する場合にのみサービス PATH に書き込まれます。これにより、生成された supervisor PATH は、doctor が後で実行する同じ最小 PATH 監査と整合します。 Doctor は設定変更を永続化し、doctor 実行を記録するためにウィザードメタデータをスタンプします。 - Doctor は、ワークスペースメモリシステムがない場合に提案し、ワークスペースがまだ git 管理下にない場合はバックアップのヒントを出力します。 + Doctor は、不足している場合にワークスペースメモリシステムを提案し、ワークスペースがまだ git 管理下にない場合はバックアップのヒントを表示します。 ワークスペース構造と git バックアップ（プライベート GitHub または GitLab を推奨）の完全なガイドについては、[/concepts/agent-workspace](/ja-JP/concepts/agent-workspace) を参照してください。 @@ -488,5 +493,5 @@ openclaw memory rem-backfill --path ./memory --stage-short-term ## 関連 -- [Gateway ランブック](/ja-JP/gateway) +- [Gateway runbook](/ja-JP/gateway) - [Gateway トラブルシューティング](/ja-JP/gateway/troubleshooting) diff --git a/docs/ja-JP/gateway/protocol.md b/docs/ja-JP/gateway/protocol.md index cc02b0c7c..57bd0e94e 100644 --- a/docs/ja-JP/gateway/protocol.md +++ b/docs/ja-JP/gateway/protocol.md @@ -1,26 +1,26 @@ --- read_when: - Gateway WS クライアントの実装または更新 - - プロトコルの不一致や接続失敗のデバッグ - - プロトコルスキーマ/モデルの再生成 -summary: 'Gateway WebSocketプロトコル: ハンドシェイク、フレーム、バージョン管理' + - プロトコルの不一致または接続失敗のデバッグ + - プロトコルのスキーマ/モデルを再生成する +summary: 'Gateway WebSocket プロトコル: ハンドシェイク、フレーム、バージョン管理' title: Gateway プロトコル x-i18n: - generated_at: "2026-04-30T05:15:25Z" + generated_at: "2026-05-01T05:01:24Z" model: gpt-5.5 provider: openai - source_hash: c0d922e9b4b778c333873e551498b905461f30f944e809555b45669ae2f5c404 + source_hash: a6da9ce755b941789ae6b9e866247c8bebb86e9a1530fb8cb258fb0650b24b8a source_path: gateway/protocol.md workflow: 16 --- -Gateway WS プロトコルは、OpenClaw の**単一のコントロールプレーン + ノードトランスポート**です。すべてのクライアント（CLI、Web UI、macOS アプリ、iOS/Android ノード、ヘッドレスノード）は WebSocket 経由で接続し、ハンドシェイク時に自身の**ロール** + **スコープ**を宣言します。 +OpenClaw における Gateway WS プロトコルは、**単一のコントロールプレーン + ノードトランスポート**です。すべてのクライアント（CLI、Web UI、macOS アプリ、iOS/Android ノード、ヘッドレスノード）は WebSocket 経由で接続し、ハンドシェイク時に自身の **role** + **scope** を宣言します。 ## トランスポート - WebSocket、JSON ペイロードを持つテキストフレーム。 -- 最初のフレームは**必ず** `connect` リクエストでなければなりません。 -- 接続前フレームは 64 KiB に制限されます。ハンドシェイクが成功した後、クライアントは `hello-ok.policy.maxPayload` と `hello-ok.policy.maxBufferedBytes` の制限に従う必要があります。診断が有効な場合、過大な受信フレームと遅い送信バッファーは、gateway が対象フレームを閉じるか破棄する前に `payload.large` イベントを発行します。これらのイベントは、サイズ、制限、サーフェス、安全な理由コードを保持します。メッセージ本文、添付ファイルの内容、生フレーム本文、トークン、Cookie、秘密値は保持しません。 +- 最初のフレームは **必ず** `connect` リクエストでなければなりません。 +- 接続前フレームは 64 KiB に制限されます。ハンドシェイクが成功した後、クライアントは `hello-ok.policy.maxPayload` と `hello-ok.policy.maxBufferedBytes` の制限に従う必要があります。診断が有効な場合、サイズ超過の受信フレームと低速な送信バッファーは、Gateway が対象フレームを閉じるか破棄する前に `payload.large` イベントを発行します。これらのイベントは、サイズ、制限、サーフェス、安全な理由コードを保持します。メッセージ本文、添付内容、生フレーム本文、トークン、Cookie、シークレット値は保持しません。 ## ハンドシェイク（connect） @@ -95,9 +95,9 @@ Gateway → クライアント: } ``` -Gateway がまだ起動サイドカーの完了処理中の場合、`connect` リクエストは、`details.reason` が `"startup-sidecars"` に設定され、`retryAfterMs` を含む、再試行可能な `UNAVAILABLE` エラーを返すことがあります。クライアントは、その応答を最終的なハンドシェイク失敗として表面化させるのではなく、全体の接続予算内で再試行する必要があります。 +Gateway がまだ起動サイドカーを完了中の場合、`connect` リクエストは `details.reason` が `"startup-sidecars"` に設定され、`retryAfterMs` を持つ再試行可能な `UNAVAILABLE` エラーを返すことがあります。クライアントは、その応答を最終的なハンドシェイク失敗として表示するのではなく、全体の接続予算内で再試行する必要があります。 -`server`、`features`、`snapshot`、`policy` はすべてスキーマ（`src/gateway/protocol/schema/frames.ts`）で必須です。`auth` も必須で、ネゴシエートされたロール/スコープを報告します。`canvasHostUrl` は任意です。 +`server`、`features`、`snapshot`、`policy` はすべてスキーマ（`src/gateway/protocol/schema/frames.ts`）で必須です。`auth` も必須で、ネゴシエートされた role/scopes を報告します。`canvasHostUrl` は任意です。 デバイストークンが発行されない場合、`hello-ok.auth` はトークンフィールドなしでネゴシエートされた権限を報告します。 @@ -110,7 +110,7 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect` } ``` -信頼された同一プロセスのバックエンドクライアント（`client.id: "gateway-client"`、`client.mode: "backend"`）は、共有 gateway トークン/パスワードで認証する場合、直接ループバック接続で `device` を省略できます。この経路は内部コントロールプレーン RPC 用に予約されており、古い CLI/デバイスペアリングのベースラインが、サブエージェントセッション更新などのローカルバックエンド作業をブロックしないようにします。リモートクライアント、ブラウザーオリジンのクライアント、ノードクライアント、および明示的なデバイストークン/デバイス ID クライアントは、引き続き通常のペアリングとスコープアップグレードのチェックを使用します。 +信頼済みの同一プロセスバックエンドクライアント（`client.id: "gateway-client"`、`client.mode: "backend"`）は、共有 Gateway トークン/パスワードで認証する場合、直接 local loopback 接続で `device` を省略できます。この経路は内部コントロールプレーン RPC 用に予約されており、古い CLI/デバイスペアリング基準値がサブエージェントセッション更新などのローカルバックエンド作業をブロックしないようにします。リモートクライアント、ブラウザーオリジンクライアント、ノードクライアント、明示的なデバイストークン/デバイス ID クライアントは、引き続き通常のペアリングとスコープアップグレードチェックを使用します。 デバイストークンが発行される場合、`hello-ok` には次も含まれます。 @@ -124,7 +124,7 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect` } ``` -信頼されたブートストラップ引き渡し中、`hello-ok.auth` には `deviceTokens` に追加の境界付きロールエントリが含まれる場合もあります。 +信頼済みブートストラップの引き渡し中、`hello-ok.auth` には `deviceTokens` 内の追加の制限付き role エントリも含まれることがあります。 ```json { @@ -143,9 +143,9 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect` } ``` -組み込みのノード/オペレーターブートストラップフローでは、プライマリノードトークンは `scopes: []` のままで、引き渡されたオペレータートークンはブートストラップオペレーターの許可リスト（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）に境界付けられたままです。ブートストラップスコープチェックはロールプレフィックス付きのままです。operator エントリは operator リクエストのみを満たし、operator 以外のロールは引き続き自身のロールプレフィックス配下のスコープを必要とします。 +組み込みのノード/operator ブートストラップフローでは、プライマリノードトークンは `scopes: []` のままで、引き渡された operator トークンはブートストラップ operator 許可リスト（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）に制限されたままです。ブートストラップスコープチェックは role 接頭辞付きのままです。operator エントリは operator リクエストのみを満たし、operator 以外の role は引き続き自身の role 接頭辞配下のスコープを必要とします。 -### ノード例 +### Node の例 ```json { @@ -186,11 +186,11 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect` - **レスポンス**: `{type:"res", id, ok, payload|error}` - **イベント**: `{type:"event", event, payload, seq?, stateVersion?}` -副作用のあるメソッドには**冪等性キー**が必要です（スキーマを参照）。 +副作用のあるメソッドには **冪等性キー** が必要です（スキーマを参照）。 -## ロール + スコープ +## role + scope -### ロール +### role - `operator` = コントロールプレーンクライアント（CLI/UI/自動化）。 - `node` = 機能ホスト（camera/screen/canvas/system.run）。 @@ -208,36 +208,35 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect` `includeSecrets: true` を指定した `talk.config` には `operator.talk.secrets`（または `operator.admin`）が必要です。 -Plugin 登録の gateway RPC メソッドは独自の operator スコープを要求できますが、予約済みのコア管理プレフィックス（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は常に `operator.admin` に解決されます。 +Plugin に登録された Gateway RPC メソッドは独自の operator スコープを要求できますが、予約済みのコア管理接頭辞（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は常に `operator.admin` に解決されます。 -メソッドスコープは最初のゲートにすぎません。`chat.send` を通じて到達する一部のスラッシュコマンドでは、その上により厳格なコマンドレベルのチェックが適用されます。たとえば、永続的な `/config set` と `/config unset` の書き込みには `operator.admin` が必要です。 +メソッドスコープは最初のゲートにすぎません。`chat.send` 経由で到達する一部のスラッシュコマンドは、さらに厳格なコマンドレベルのチェックを適用します。たとえば、永続的な `/config set` と `/config unset` の書き込みには `operator.admin` が必要です。 `node.pair.approve` には、基本メソッドスコープに加えて、承認時の追加スコープチェックもあります。 - コマンドなしリクエスト: `operator.pairing` - exec 以外のノードコマンドを含むリクエスト: `operator.pairing` + `operator.write` -- `system.run`、`system.run.prepare`、または `system.which` を含むリクエスト: - `operator.pairing` + `operator.admin` +- `system.run`、`system.run.prepare`、または `system.which` を含むリクエスト: `operator.pairing` + `operator.admin` ### caps/commands/permissions（node） ノードは接続時に機能要求を宣言します。 - `caps`: 高レベルの機能カテゴリ。 -- `commands`: invoke のコマンド許可リスト。 -- `permissions`: 詳細な切り替え（例: `screen.record`、`camera.capture`）。 +- `commands`: invoke 用のコマンド許可リスト。 +- `permissions`: きめ細かなトグル（例: `screen.record`、`camera.capture`）。 -Gateway はこれらを**要求**として扱い、サーバー側の許可リストを強制します。 +Gateway はこれらを **要求** として扱い、サーバー側の許可リストを適用します。 ## プレゼンス - `system-presence` はデバイス ID をキーにしたエントリを返します。 - プレゼンスエントリには `deviceId`、`roles`、`scopes` が含まれるため、UI は同じデバイスが **operator** と **node** の両方として接続している場合でも、デバイスごとに 1 行で表示できます。 -- `node.list` には任意の `lastSeenAtMs` と `lastSeenReason` フィールドが含まれます。接続中のノードは、現在の接続時刻を理由 `connect` とともに `lastSeenAtMs` として報告します。ペアリング済みノードは、信頼されたノードイベントがペアリングメタデータを更新したときに、永続的なバックグラウンドプレゼンスも報告できます。 +- `node.list` には任意の `lastSeenAtMs` と `lastSeenReason` フィールドが含まれます。接続中のノードは現在の接続時刻を `lastSeenAtMs` として、理由 `connect` とともに報告します。ペアリング済みノードは、信頼済みノードイベントがペアリングメタデータを更新したときに、永続的なバックグラウンドプレゼンスも報告できます。 -### ノードバックグラウンド生存イベント +### ノードのバックグラウンド生存イベント -ノードは `event: "node.presence.alive"` を指定して `node.event` を呼び出し、ペアリング済みノードがバックグラウンドウェイク中に生存していたことを、接続済みとしてマークせずに記録できます。 +ノードは `event: "node.presence.alive"` を指定して `node.event` を呼び出し、ペアリング済みノードがバックグラウンドウェイク中に生存していたことを、接続済みにせずに記録できます。 ```json { @@ -246,9 +245,9 @@ Gateway はこれらを**要求**として扱い、サーバー側の許可リ } ``` -`trigger` は閉じた列挙型です: `background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual`、または `connect`。未知のトリガー文字列は、永続化前に gateway によって `background` に正規化されます。このイベントは認証済みノードデバイスセッションでのみ永続化されます。デバイスなし、または未ペアリングのセッションは `handled: false` を返します。 +`trigger` は閉じた enum です: `background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual`、または `connect`。未知のトリガー文字列は、永続化の前に Gateway によって `background` に正規化されます。このイベントは、認証済みのノードデバイスセッションに対してのみ永続的です。デバイスなしまたは未ペアリングのセッションは `handled: false` を返します。 -成功した gateway は構造化された結果を返します。 +成功した Gateway は構造化された結果を返します。 ```json { @@ -259,212 +258,215 @@ Gateway はこれらを**要求**として扱い、サーバー側の許可リ } ``` -古い gateway は `node.event` に対してまだ `{ "ok": true }` を返す場合があります。クライアントはそれを、永続的なプレゼンス永続化ではなく、承認済み RPC として扱う必要があります。 +古い Gateway は `node.event` に対して引き続き `{ "ok": true }` を返すことがあります。クライアントはこれを、永続的なプレゼンス保存ではなく、確認済みの RPC として扱う必要があります。 ## ブロードキャストイベントのスコープ設定 -サーバーからプッシュされる WebSocket ブロードキャストイベントはスコープでゲートされるため、ペアリングスコープまたはノード専用セッションがセッション内容を受動的に受け取ることはありません。 +サーバーからプッシュされる WebSocket ブロードキャストイベントはスコープでゲートされるため、ペアリングスコープ付きセッションやノード専用セッションがセッション内容を受動的に受信することはありません。 -- **チャット、エージェント、ツール結果フレーム**（ストリーミングされた `agent` イベントとツール呼び出し結果を含む）には、少なくとも `operator.read` が必要です。`operator.read` を持たないセッションは、これらのフレームを完全にスキップします。 -- **Plugin 定義の `plugin.*` ブロードキャスト**は、Plugin が登録した方法に応じて `operator.write` または `operator.admin` にゲートされます。 -- **ステータスおよびトランスポートイベント**（`heartbeat`、`presence`、`tick`、接続/切断ライフサイクルなど）は、すべての認証済みセッションがトランスポートの健全性を観測できるように、制限なしのままです。 -- **未知のブロードキャストイベントファミリー**は、登録済みハンドラーが明示的に緩和しない限り、デフォルトでスコープゲートされます（フェイルクローズ）。 +- **チャット、エージェント、ツール結果フレーム**（ストリーミングされた `agent` イベントとツール呼び出し結果を含む）には少なくとも `operator.read` が必要です。`operator.read` を持たないセッションは、これらのフレームを完全にスキップします。 +- **Plugin 定義の `plugin.*` ブロードキャスト** は、Plugin が登録した方法に応じて `operator.write` または `operator.admin` にゲートされます。 +- **ステータスおよびトランスポートイベント**（`heartbeat`、`presence`、`tick`、接続/切断ライフサイクルなど）は、すべての認証済みセッションでトランスポートの健全性を観測可能に保つため、制限されません。 +- **未知のブロードキャストイベントファミリー** は、登録済みハンドラーが明示的に緩和しない限り、デフォルトでスコープゲートされます（フェイルクローズ）。 -各クライアント接続はクライアントごとの独自のシーケンス番号を保持するため、異なるクライアントがイベントストリームの異なるスコープフィルター済みサブセットを見る場合でも、ブロードキャストはそのソケット上で単調な順序を維持します。 +各クライアント接続は独自のクライアントごとのシーケンス番号を保持するため、異なるクライアントがイベントストリームの異なるスコープフィルター済みサブセットを見る場合でも、ブロードキャストはそのソケット上で単調な順序を維持します。 ## 一般的な RPC メソッドファミリー -公開 WS サーフェスは、上記のハンドシェイク/認証例よりも広範です。これは生成されたダンプではありません。`hello-ok.features.methods` は、`src/gateway/server-methods-list.ts` と読み込まれた Plugin/チャネルメソッドエクスポートから構築される保守的な検出リストです。`src/gateway/server-methods/*.ts` の完全な列挙ではなく、機能検出として扱ってください。 +公開 WS サーフェスは、上記のハンドシェイク/認証例よりも広範です。これは生成されたダンプではありません。`hello-ok.features.methods` は、`src/gateway/server-methods-list.ts` と読み込まれた Plugin/チャンネルメソッドエクスポートから構築される保守的な検出リストです。これは機能検出として扱い、`src/gateway/server-methods/*.ts` の完全な列挙とは見なさないでください。 - - `health` はキャッシュ済み、または新たにプローブされた gateway ヘルススナップショットを返します。 - - `diagnostics.stability` は、最近の境界付き診断安定性レコーダーを返します。イベント名、件数、バイトサイズ、メモリ読み取り値、キュー/セッション状態、チャネル/Plugin 名、セッション ID などの運用メタデータを保持します。チャットテキスト、webhook 本文、ツール出力、生のリクエスト本文またはレスポンス本文、トークン、Cookie、秘密値は保持しません。operator read スコープが必要です。 - - `status` は `/status` スタイルの gateway サマリーを返します。機密フィールドは admin スコープの operator クライアントにのみ含まれます。 - - `gateway.identity.get` は、リレーおよびペアリングフローで使用される gateway デバイス ID を返します。 + - `health` は、キャッシュ済みまたは新たにプローブされた Gateway ヘルススナップショットを返します。 + - `diagnostics.stability` は、最近の制限付き診断安定性レコーダーを返します。イベント名、カウント、バイトサイズ、メモリ読み取り値、キュー/セッション状態、チャンネル/Plugin 名、セッション ID などの運用メタデータを保持します。チャットテキスト、Webhook 本文、ツール出力、生のリクエストまたはレスポンス本文、トークン、Cookie、シークレット値は保持しません。operator read スコープが必要です。 + - `status` は `/status` 形式の Gateway サマリーを返します。機微なフィールドは、管理者スコープ付きの operator クライアントにのみ含まれます。 + - `gateway.identity.get` は、リレーおよびペアリングフローで使用される Gateway デバイス ID を返します。 - `system-presence` は、接続中の operator/node デバイスの現在のプレゼンススナップショットを返します。 - `system-event` はシステムイベントを追加し、プレゼンスコンテキストを更新/ブロードキャストできます。 - - `last-heartbeat` は最新の永続化された Heartbeat イベントを返します。 - - `set-heartbeats` は gateway 上の Heartbeat 処理を切り替えます。 + - `last-heartbeat` は、最新の永続化された Heartbeat イベントを返します。 + - `set-heartbeats` は、Gateway 上の Heartbeat 処理を切り替えます。 - - - `models.list` は、ランタイムで許可されたモデルカタログを返します。ピッカー向けサイズの構成済みモデル（まず `agents.defaults.models`、次に `models.providers.*.models`）には `{ "view": "configured" }` を渡し、完全なカタログには `{ "view": "all" }` を渡します。 - - `usage.status` は、プロバイダーの使用状況ウィンドウ/残りクォータの概要を返します。 - - `usage.cost` は、日付範囲に対する集計済みコスト使用状況の概要を返します。 - - `doctor.memory.status` は、アクティブなデフォルトエージェントワークスペースのベクトルメモリ / キャッシュ済み埋め込みの準備状態を返します。呼び出し元がライブ埋め込みプロバイダーへの ping を明示的に要求する場合のみ、`{ "probe": true }` または `{ "deep": true }` を渡します。 - - `doctor.memory.remHarness` は、リモート制御プレーンのクライアント向けに、範囲制限された読み取り専用の REM ハーネスプレビューを返します。ワークスペースパス、メモリスニペット、レンダリング済みの根拠付きマークダウン、深いプロモーション候補を含むことがあるため、呼び出し元には `operator.read` が必要です。 - - `sessions.usage` は、セッションごとの使用状況の概要を返します。 - - `sessions.usage.timeseries` は、1つのセッションの時系列使用状況を返します。 - - `sessions.usage.logs` は、1つのセッションの使用状況ログエントリを返します。 + + - `models.list` は、ランタイムで許可されているモデルカタログを返します。ピッカーに適したサイズの設定済みモデル（まず `agents.defaults.models`、次に `models.providers.*.models`）には `{ "view": "configured" }` を渡し、完全なカタログには `{ "view": "all" }` を渡します。 + - `usage.status` は、プロバイダーの使用量ウィンドウと残りクォータの要約を返します。 + - `usage.cost` は、日付範囲に対する集計済みコスト使用量の要約を返します。 + - `doctor.memory.status` は、アクティブなデフォルトエージェントワークスペースのベクトルメモリ / キャッシュ済み埋め込みの準備状況を返します。呼び出し元がライブ埋め込みプロバイダーへの ping を明示的に求める場合にのみ、`{ "probe": true }` または `{ "deep": true }` を渡します。 + - `doctor.memory.remHarness` は、リモート制御プレーンのクライアント向けに、範囲が制限された読み取り専用の REM ハーネスプレビューを返します。ワークスペースパス、メモリスニペット、レンダリング済みの根拠付き Markdown、深い昇格候補を含められるため、呼び出し元には `operator.read` が必要です。 + - `sessions.usage` は、セッションごとの使用量要約を返します。 + - `sessions.usage.timeseries` は、1 つのセッションの時系列使用量を返します。 + - `sessions.usage.logs` は、1 つのセッションの使用量ログエントリを返します。 - - `channels.status` は、組み込み + バンドル済みチャネル/Plugin のステータス概要を返します。 - - `channels.logout` は、チャネルがログアウトをサポートしている場合に、特定のチャネル/アカウントをログアウトします。 - - `web.login.start` は、現在の QR 対応 Web チャネルプロバイダーの QR/Web ログインフローを開始します。 - - `web.login.wait` は、その QR/Web ログインフローの完了を待機し、成功時にチャネルを開始します。 - - `push.test` は、登録済み iOS ノードにテスト APNs プッシュを送信します。 + - `channels.status` は、組み込み + バンドル済みチャネル / plugin のステータス要約を返します。 + - `channels.logout` は、チャネルがログアウトをサポートしている場合に、特定のチャネル / アカウントからログアウトします。 + - `web.login.start` は、現在の QR 対応 Web チャネルプロバイダーに対する QR / Web ログインフローを開始します。 + - `web.login.wait` は、その QR / Web ログインフローの完了を待機し、成功時にチャネルを開始します。 + - `push.test` は、登録済み iOS ノードにテスト用 APNs プッシュを送信します。 - `voicewake.get` は、保存済みのウェイクワードトリガーを返します。 - `voicewake.set` は、ウェイクワードトリガーを更新し、変更をブロードキャストします。 - - `send` は、チャットランナー外でチャネル/アカウント/スレッドを対象に送信するための、直接アウトバウンド配信 RPC です。 - - `logs.tail` は、カーソル/リミットと最大バイト数の制御を備えた、構成済み Gateway ファイルログの末尾を返します。 + - `send` は、チャットランナーの外部でチャネル / アカウント / スレッドを対象に送信するための、直接アウトバウンド配信 RPC です。 + - `logs.tail` は、カーソル / 制限と最大バイト数の制御付きで、設定済み Gateway ファイルログの末尾を返します。 - + - `talk.config` は、有効な Talk 設定ペイロードを返します。`includeSecrets` には `operator.talk.secrets`（または `operator.admin`）が必要です。 - - `talk.mode` は、WebChat/Control UI クライアント向けに現在の Talk モード状態を設定/ブロードキャストします。 + - `talk.mode` は、WebChat / Control UI クライアント向けに現在の Talk モード状態を設定 / ブロードキャストします。 - `talk.speak` は、アクティブな Talk 音声プロバイダーを通じて音声を合成します。 - - `tts.status` は、TTS の有効状態、アクティブなプロバイダー、フォールバックプロバイダー、プロバイダー設定状態を返します。 - - `tts.providers` は、表示可能な TTS プロバイダーインベントリを返します。 + - `tts.status` は、TTS の有効状態、アクティブプロバイダー、フォールバックプロバイダー、プロバイダー設定状態を返します。 + - `tts.providers` は、表示可能な TTS プロバイダーのインベントリを返します。 - `tts.enable` と `tts.disable` は、TTS 設定状態を切り替えます。 - `tts.setProvider` は、優先 TTS プロバイダーを更新します。 - - `tts.convert` は、1回限りのテキスト読み上げ変換を実行します。 + - `tts.convert` は、単発のテキスト読み上げ変換を実行します。 - - `secrets.reload` は、アクティブな SecretRefs を再解決し、完全に成功した場合のみランタイムのシークレット状態を差し替えます。 - - `secrets.resolve` は、特定のコマンド/ターゲットセットに対するコマンド対象のシークレット割り当てを解決します。 + - `secrets.reload` は、アクティブな SecretRefs を再解決し、完全に成功した場合にのみランタイムのシークレット状態を差し替えます。 + - `secrets.resolve` は、特定のコマンド / ターゲットセットに対するコマンド対象のシークレット割り当てを解決します。 - `config.get` は、現在の設定スナップショットとハッシュを返します。 - `config.set` は、検証済みの設定ペイロードを書き込みます。 - `config.patch` は、部分的な設定更新をマージします。 - `config.apply` は、完全な設定ペイロードを検証して置き換えます。 - - `config.schema` は、Control UI と CLI ツールが使用するライブ設定スキーマペイロードを返します。スキーマ、`uiHints`、バージョン、生成メタデータに加えて、ランタイムが読み込める場合は Plugin + チャネルのスキーマメタデータも含みます。このスキーマには、UI で使用される同じラベルとヘルプテキストから派生したフィールドの `title` / `description` メタデータが含まれます。対応するフィールドドキュメントが存在する場合は、ネストされたオブジェクト、ワイルドカード、配列項目、`anyOf` / `oneOf` / `allOf` の合成ブランチも含まれます。 - - `config.schema.lookup` は、1つの設定パスに対するパススコープのルックアップペイロードを返します。正規化されたパス、浅いスキーマノード、一致したヒント + `hintPath`、UI/CLI のドリルダウン向けの直接の子要素概要を含みます。ルックアップスキーマノードは、ユーザー向けドキュメントと共通の検証フィールド（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数値/文字列/配列/オブジェクトの境界、および `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` などのフラグ）を保持します。子要素概要は、`key`、正規化された `path`、`type`、`required`、`hasChildren`、および一致した `hint` / `hintPath` を公開します。 - - `update.run` は、Gateway 更新フローを実行し、更新自体が成功した場合のみ再起動をスケジュールします。 - - `update.status` は、利用可能な場合は再起動後に稼働中のバージョンを含め、最新のキャッシュ済み更新再起動センチネルを返します。 + - `config.schema` は、Control UI と CLI ツールで使用されるライブ設定スキーマペイロードを返します。これには、スキーマ、`uiHints`、バージョン、生成メタデータが含まれ、ランタイムが読み込める場合は plugin + チャネルスキーマメタデータも含まれます。スキーマには、UI で使用される同じラベルとヘルプテキストから派生したフィールド `title` / `description` メタデータが含まれ、対応するフィールドドキュメントが存在する場合は、ネストされたオブジェクト、ワイルドカード、配列項目、`anyOf` / `oneOf` / `allOf` の合成分岐も含まれます。 + - `config.schema.lookup` は、1 つの設定パスに対してパススコープの検索ペイロードを返します。正規化されたパス、浅いスキーマノード、一致したヒント + `hintPath`、UI / CLI の掘り下げ用の直下の子要約が含まれます。検索スキーマノードは、ユーザー向けドキュメントと一般的な検証フィールド（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数値 / 文字列 / 配列 / オブジェクトの境界、`additionalProperties`、`deprecated`、`readOnly`、`writeOnly` などのフラグ）を保持します。子要約は、`key`、正規化済みの `path`、`type`、`required`、`hasChildren` に加え、一致した `hint` / `hintPath` を公開します。 + - `update.run` は Gateway 更新フローを実行し、更新自体が成功した場合にのみ再起動をスケジュールします。 + - `update.status` は、利用可能な場合は再起動後に実行中のバージョンを含め、最新のキャッシュ済み更新再起動センチネルを返します。 - `wizard.start`、`wizard.next`、`wizard.status`、`wizard.cancel` は、オンボーディングウィザードを WS RPC 経由で公開します。 - - `agents.list` は、有効なモデルとランタイムメタデータを含む、構成済みエージェントエントリを返します。 - - `agents.create`、`agents.update`、`agents.delete` は、エージェントレコードとワークスペースの配線を管理します。 + - `agents.list` は、有効なモデルとランタイムメタデータを含む、設定済みエージェントエントリを返します。 + - `agents.create`、`agents.update`、`agents.delete` は、エージェントレコードとワークスペースの結線を管理します。 - `agents.files.list`、`agents.files.get`、`agents.files.set` は、エージェント向けに公開されるブートストラップワークスペースファイルを管理します。 + - `artifacts.list`、`artifacts.get`、`artifacts.download` は、明示的な `sessionKey`、`runId`、または `taskId` スコープに対して、トランスクリプト由来のアーティファクト要約とダウンロードを公開します。実行クエリとタスククエリは、所有するセッションをサーバー側で解決し、一致する来歴を持つトランスクリプトメディアのみを返します。安全でない URL ソースやローカル URL ソースは、サーバー側で取得せず、サポートされていないダウンロードを返します。 - `agent.identity.get` は、エージェントまたはセッションに対する有効なアシスタント ID を返します。 - - `agent.wait` は、実行の終了を待機し、利用可能な場合は終了時のスナップショットを返します。 + - `agent.wait` は、実行の完了を待機し、利用可能な場合は終端スナップショットを返します。 - - `sessions.list` は、現在のセッションインデックスを返します。エージェントランタイムバックエンドが構成されている場合は、各行の `agentRuntime` メタデータも含みます。 + - `sessions.list` は、エージェントランタイムバックエンドが設定されている場合、行ごとの `agentRuntime` メタデータを含む現在のセッションインデックスを返します。 - `sessions.subscribe` と `sessions.unsubscribe` は、現在の WS クライアントに対するセッション変更イベント購読を切り替えます。 - - `sessions.messages.subscribe` と `sessions.messages.unsubscribe` は、1つのセッションに対するトランスクリプト/メッセージイベント購読を切り替えます。 - - `sessions.preview` は、特定のセッションキーに対する範囲制限されたトランスクリプトプレビューを返します。 + - `sessions.messages.subscribe` と `sessions.messages.unsubscribe` は、1 つのセッションに対するトランスクリプト / メッセージイベント購読を切り替えます。 + - `sessions.preview` は、特定のセッションキーに対して範囲が制限されたトランスクリプトプレビューを返します。 - `sessions.resolve` は、セッションターゲットを解決または正規化します。 - `sessions.create` は、新しいセッションエントリを作成します。 - `sessions.send` は、既存のセッションにメッセージを送信します。 - - `sessions.steer` は、アクティブなセッション向けの中断して誘導するバリアントです。 - - `sessions.abort` は、セッションのアクティブな作業を中止します。呼び出し元は `key` と任意の `runId` を渡すか、Gateway がセッションへ解決できるアクティブな実行については `runId` のみを渡すことができます。 - - `sessions.patch` は、セッションのメタデータ/オーバーライドを更新し、解決済みの正規モデルと有効な `agentRuntime` を報告します。 - - `sessions.reset`、`sessions.delete`、`sessions.compact` は、セッションのメンテナンスを実行します。 - - `sessions.get` は、保存済みの完全なセッション行を返します。 - - チャット実行では引き続き `chat.history`、`chat.send`、`chat.abort`、`chat.inject` を使用します。`chat.history` は UI クライアント向けに表示正規化されます。インラインディレクティブタグは表示テキストから取り除かれ、プレーンテキストのツール呼び出し XML ペイロード（`...`、`...`、`...`、`...`、切り詰められたツール呼び出しブロックを含む）と漏れた ASCII/全角のモデル制御トークンは取り除かれ、正確に `NO_REPLY` / `no_reply` であるような純粋なサイレントトークンのアシスタント行は省略され、過大な行はプレースホルダーで置き換えられることがあります。 + - `sessions.steer` は、アクティブなセッション向けの割り込みおよび誘導バリアントです。 + - `sessions.abort` は、セッションのアクティブな作業を中止します。呼び出し元は `key` と任意の `runId` を渡すか、Gateway がセッションへ解決できるアクティブな実行については `runId` のみを渡せます。 + - `sessions.patch` は、セッションのメタデータ / オーバーライドを更新し、解決済みの正規モデルと有効な `agentRuntime` を報告します。 + - `sessions.reset`、`sessions.delete`、`sessions.compact` は、セッションメンテナンスを実行します。 + - `sessions.get` は、保存済みセッション行全体を返します。 + - チャット実行では引き続き `chat.history`、`chat.send`、`chat.abort`、`chat.inject` を使用します。`chat.history` は UI クライアント向けに表示正規化されています。インラインディレクティブタグは表示テキストから取り除かれ、プレーンテキストのツール呼び出し XML ペイロード（`...`、`...`、`...`、`...`、切り詰められたツール呼び出しブロックを含む）と漏出した ASCII / 全角のモデル制御トークンは取り除かれ、正確に `NO_REPLY` / `no_reply` のような純粋なサイレントトークンのアシスタント行は省略され、過大な行はプレースホルダーに置き換えられる場合があります。 - `device.pair.list` は、保留中および承認済みのペアリング済みデバイスを返します。 - `device.pair.approve`、`device.pair.reject`、`device.pair.remove` は、デバイスペアリングレコードを管理します。 - - `device.token.rotate` は、承認済みロールと呼び出し元のスコープ境界内で、ペアリング済みデバイストークンをローテーションします。 - - `device.token.revoke` は、承認済みロールと呼び出し元のスコープ境界内で、ペアリング済みデバイストークンを取り消します。 + - `device.token.rotate` は、承認済みロールと呼び出し元スコープの境界内で、ペアリング済みデバイストークンをローテーションします。 + - `device.token.revoke` は、承認済みロールと呼び出し元スコープの境界内で、ペアリング済みデバイストークンを失効させます。 - `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.remove`、`node.pair.verify` は、ノードペアリングとブートストラップ検証を扱います。 - - `node.list` と `node.describe` は、既知/接続済みノードの状態を返します。 + - `node.list` と `node.describe` は、既知 / 接続済みノードの状態を返します。 - `node.rename` は、ペアリング済みノードのラベルを更新します。 - `node.invoke` は、接続済みノードにコマンドを転送します。 - `node.invoke.result` は、呼び出しリクエストの結果を返します。 - - `node.event` は、ノード起点のイベントを Gateway に戻します。 + - `node.event` は、ノード発信のイベントを Gateway に戻します。 - `node.canvas.capability.refresh` は、スコープ付きキャンバス機能トークンを更新します。 - `node.pending.pull` と `node.pending.ack` は、接続済みノードのキュー API です。 - - `node.pending.enqueue` と `node.pending.drain` は、オフライン/切断済みノード向けの永続的な保留中作業を管理します。 + - `node.pending.enqueue` と `node.pending.drain` は、オフライン / 切断済みノード向けの永続的な保留作業を管理します。 - - `exec.approval.request`、`exec.approval.get`、`exec.approval.list`、`exec.approval.resolve` は、1回限りの exec 承認リクエストと、保留中の承認の検索/再生を扱います。 - - `exec.approval.waitDecision` は、1つの保留中 exec 承認を待機し、最終決定（またはタイムアウト時は `null`）を返します。 - - `exec.approvals.get` と `exec.approvals.set` は、Gateway exec 承認ポリシースナップショットを管理します。 - - `exec.approvals.node.get` と `exec.approvals.node.set` は、ノードリレーコマンドを介してノードローカル exec 承認ポリシーを管理します。 - - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision`、`plugin.approval.resolve` は、Plugin 定義の承認フローを扱います。 + - `exec.approval.request`、`exec.approval.get`、`exec.approval.list`、`exec.approval.resolve` は、単発の exec 承認リクエストと、保留中の承認検索 / 再生を扱います。 + - `exec.approval.waitDecision` は、保留中の exec 承認を 1 件待機し、最終判断（またはタイムアウト時は `null`）を返します。 + - `exec.approvals.get` と `exec.approvals.set` は、Gateway の exec 承認ポリシースナップショットを管理します。 + - `exec.approvals.node.get` と `exec.approvals.node.set` は、ノードリレーコマンド経由でノードローカルの exec 承認ポリシーを管理します。 + - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision`、`plugin.approval.resolve` は、plugin 定義の承認フローを扱います。 - - 自動化: `wake` は、即時または次回 Heartbeat のウェイクテキスト挿入をスケジュールします。`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` は、スケジュール済み作業を管理します。 + - 自動化: `wake` は即時または次回 Heartbeat のウェイクテキスト注入をスケジュールします。`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` はスケジュール済み作業を管理します。 - Skills とツール: `commands.list`、`skills.*`、`tools.catalog`、`tools.effective`。 -### 共通イベントファミリー +### 一般的なイベントファミリー -- `chat`: `chat.inject` などの UI チャット更新、およびその他のトランスクリプト専用チャットイベント。 -- `session.message` と `session.tool`: 購読済みセッションのトランスクリプト/イベントストリーム更新。 +- `chat`: `chat.inject` などの UI チャット更新、およびその他のトランスクリプト専用チャット + イベント。 +- `session.message` と `session.tool`: 購読済みセッションに対するトランスクリプト / イベントストリーム更新。 - `sessions.changed`: セッションインデックスまたはメタデータが変更されました。 -- `presence`: システムプレゼンススナップショット更新。 +- `presence`: システムプレゼンスのスナップショット更新。 - `tick`: 定期的な keepalive / 生存確認イベント。 - `health`: Gateway ヘルススナップショット更新。 - `heartbeat`: Heartbeat イベントストリーム更新。 -- `cron`: Cron 実行/ジョブ変更イベント。 +- `cron`: Cron 実行 / ジョブ変更イベント。 - `shutdown`: Gateway シャットダウン通知。 - `node.pair.requested` / `node.pair.resolved`: ノードペアリングのライフサイクル。 - `node.invoke.request`: ノード呼び出しリクエストのブロードキャスト。 - `device.pair.requested` / `device.pair.resolved`: ペアリング済みデバイスのライフサイクル。 - `voicewake.changed`: ウェイクワードトリガー設定が変更されました。 -- `exec.approval.requested` / `exec.approval.resolved`: exec 承認のライフサイクル。 -- `plugin.approval.requested` / `plugin.approval.resolved`: Plugin 承認のライフサイクル。 +- `exec.approval.requested` / `exec.approval.resolved`: exec 承認 + ライフサイクル。 +- `plugin.approval.requested` / `plugin.approval.resolved`: plugin 承認 + ライフサイクル。 ### ノードヘルパーメソッド -- ノードは、自動許可チェック向けに現在の Skills 実行可能ファイル一覧を取得するため、`skills.bins` を呼び出すことができます。 +- ノードは、自動許可チェック用の現在のスキル実行ファイル一覧を取得するために、`skills.bins` を呼び出せます。 ### オペレーターヘルパーメソッド -- オペレーターは `commands.list`（`operator.read`）を呼び出して、エージェントのランタイム +- オペレーターは `commands.list` (`operator.read`) を呼び出して、エージェントのランタイム コマンドインベントリを取得できます。 - `agentId` は任意です。デフォルトのエージェントワークスペースを読み取るには省略します。 - - `scope` は、主 `name` が対象にするサーフェスを制御します。 - - `text` は、先頭の `/` を除いた主テキストコマンドトークンを返します + - `scope` は、主要な `name` がどのサーフェスを対象にするかを制御します。 + - `text` は、先頭の `/` を含まない主要なテキストコマンドトークンを返します - `native` とデフォルトの `both` パスは、利用可能な場合にプロバイダー対応のネイティブ名を返します - `textAliases` は `/model` や `/m` などの正確なスラッシュエイリアスを保持します。 - `nativeName` は、存在する場合にプロバイダー対応のネイティブコマンド名を保持します。 - `provider` は任意で、ネイティブ命名とネイティブ Plugin - コマンドの利用可否にのみ影響します。 + コマンドの可用性にのみ影響します。 - `includeArgs=false` は、シリアライズされた引数メタデータをレスポンスから省略します。 -- オペレーターは `tools.catalog`（`operator.read`）を呼び出して、エージェントのランタイムツールカタログを取得できます。レスポンスには、グループ化されたツールと来歴メタデータが含まれます。 +- オペレーターは `tools.catalog` (`operator.read`) を呼び出して、エージェントのランタイムツールカタログを取得できます。レスポンスには、グループ化されたツールと来歴メタデータが含まれます。 - `source`: `core` または `plugin` - `pluginId`: `source="plugin"` の場合の Plugin 所有者 - `optional`: Plugin ツールが任意かどうか -- オペレーターは `tools.effective`（`operator.read`）を呼び出して、セッションでランタイム上有効なツール +- オペレーターは `tools.effective` (`operator.read`) を呼び出して、セッションでランタイム上有効なツール インベントリを取得できます。 - `sessionKey` は必須です。 - - Gateway は、呼び出し元から提供された認証または配信コンテキストを受け入れる代わりに、セッションから信頼済みランタイムコンテキストをサーバー側で導出します。 + - Gateway は、呼び出し元が指定した認証または配信コンテキストを受け入れるのではなく、セッションサーバー側から信頼済みランタイムコンテキストを導出します。 - レスポンスはセッションスコープであり、コア、Plugin、チャネルツールを含め、アクティブな会話が現時点で使用できるものを反映します。 -- オペレーターは `skills.status`（`operator.read`）を呼び出して、エージェントで表示可能な +- オペレーターは `skills.status` (`operator.read`) を呼び出して、エージェントに表示される スキルインベントリを取得できます。 - `agentId` は任意です。デフォルトのエージェントワークスペースを読み取るには省略します。 - レスポンスには、適格性、不足している要件、設定チェック、および 生のシークレット値を公開しないサニタイズ済みインストールオプションが含まれます。 -- オペレーターは ClawHub の検出メタデータ用に `skills.search` と `skills.detail`（`operator.read`）を呼び出せます。 -- オペレーターは `skills.install`（`operator.admin`）を 2 つのモードで呼び出せます。 - - ClawHub モード: `{ source: "clawhub", slug, version?, force? }` は、 - デフォルトのエージェントワークスペースの `skills/` ディレクトリにスキルフォルダーをインストールします。 +- オペレーターは ClawHub 探索メタデータのために `skills.search` と `skills.detail` (`operator.read`) を呼び出せます。 +- オペレーターは `skills.install` (`operator.admin`) を 2 つのモードで呼び出せます。 + - ClawHub モード: `{ source: "clawhub", slug, version?, force? }` は、スキルフォルダーをデフォルトエージェントワークスペースの `skills/` ディレクトリにインストールします。 - Gateway インストーラーモード: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` は、Gateway ホスト上で宣言済みの `metadata.openclaw.install` アクションを実行します。 -- オペレーターは `skills.update`（`operator.admin`）を 2 つのモードで呼び出せます。 - - ClawHub モードは、デフォルトのエージェントワークスペース内で、追跡対象の 1 つの slug または追跡対象のすべての ClawHub インストールを更新します。 +- オペレーターは `skills.update` (`operator.admin`) を 2 つのモードで呼び出せます。 + - ClawHub モードは、デフォルトエージェントワークスペース内の追跡対象 slug 1 件、または追跡対象のすべての ClawHub インストールを更新します。 - 設定モードは、`enabled`、`apiKey`、`env` などの `skills.entries.` 値にパッチを適用します。 ### `models.list` ビュー @@ -472,142 +474,136 @@ Gateway はこれらを**要求**として扱い、サーバー側の許可リ `models.list` は任意の `view` パラメーターを受け付けます。 - 省略または `"default"`: 現在のランタイム動作です。`agents.defaults.models` が設定されている場合、レスポンスは許可されたカタログになります。それ以外の場合、レスポンスは完全な Gateway カタログになります。 -- `"configured"`: ピッカー向けサイズの動作です。`agents.defaults.models` が設定されている場合は、引き続きそれが優先されます。それ以外の場合、レスポンスは明示的な `models.providers.*.models` エントリを使用し、設定済みモデル行が存在しない場合にのみ完全なカタログへフォールバックします。 -- `"all"`: 完全な Gateway カタログで、`agents.defaults.models` をバイパスします。通常のモデルピッカーではなく、診断および検出 UI に使用してください。 +- `"configured"`: ピッカー向けのサイズの動作です。`agents.defaults.models` が設定されている場合は、引き続きそれが優先されます。それ以外の場合、レスポンスは明示的な `models.providers.*.models` エントリを使用し、設定済みモデル行が存在しない場合にのみ完全なカタログへフォールバックします。 +- `"all"`: 完全な Gateway カタログで、`agents.defaults.models` をバイパスします。通常のモデルピッカーではなく、診断と探索 UI に使用します。 -## 実行承認 +## Exec 承認 -- exec リクエストが承認を必要とする場合、Gateway は `exec.approval.requested` をブロードキャストします。 -- オペレータークライアントは `exec.approval.resolve`（`operator.approvals` スコープが必要）を呼び出して解決します。 +- exec リクエストに承認が必要な場合、Gateway は `exec.approval.requested` をブロードキャストします。 +- オペレータークライアントは `exec.approval.resolve` を呼び出して解決します（`operator.approvals` スコープが必要）。 - `host=node` の場合、`exec.approval.request` には `systemRunPlan`（正規の `argv`/`cwd`/`rawCommand`/セッションメタデータ）を含める必要があります。`systemRunPlan` がないリクエストは拒否されます。 -- 承認後、転送された `node.invoke system.run` 呼び出しは、その正規の - `systemRunPlan` を信頼できるコマンド/cwd/セッションコンテキストとして再利用します。 -- 呼び出し元が prepare と最終的な承認済み `system.run` 転送の間に `command`、`rawCommand`、`cwd`、`agentId`、または - `sessionKey` を変更した場合、Gateway は変更されたペイロードを信頼せず、実行を拒否します。 +- 承認後、転送される `node.invoke system.run` 呼び出しは、その正規の + `systemRunPlan` を権威あるコマンド/cwd/セッションコンテキストとして再利用します。 +- 呼び出し元が準備から最終承認済み `system.run` 転送までの間に `command`、`rawCommand`、`cwd`、`agentId`、または + `sessionKey` を変更した場合、Gateway は変更後のペイロードを信頼せず、その実行を拒否します。 ## エージェント配信フォールバック - `agent` リクエストには、アウトバウンド配信を要求するために `deliver=true` を含めることができます。 -- `bestEffortDeliver=false` は厳格な動作を維持します。解決できない配信先または内部専用の配信先は `INVALID_REQUEST` を返します。 -- `bestEffortDeliver=true` は、外部へ配信可能なルートを解決できない場合（たとえば内部/webchat セッションや曖昧なマルチチャネル設定）、セッションのみの実行へのフォールバックを許可します。 +- `bestEffortDeliver=false` は厳格な動作を維持します。解決できない、または内部専用の配信先は `INVALID_REQUEST` を返します。 +- `bestEffortDeliver=true` は、外部に配信可能なルートを解決できない場合（例: 内部/webchat セッションや曖昧な複数チャネル設定）、セッションのみの実行へのフォールバックを許可します。 ## バージョニング - `PROTOCOL_VERSION` は `src/gateway/protocol/schema/protocol-schemas.ts` にあります。 - クライアントは `minProtocol` + `maxProtocol` を送信し、サーバーは不一致を拒否します。 -- スキーマ + モデルは TypeBox 定義から生成されます。 +- スキーマとモデルは TypeBox 定義から生成されます。 - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` ### クライアント定数 -`src/gateway/client.ts` のリファレンスクライアントは、これらのデフォルトを使用します。値は -protocol v3 全体で安定しており、サードパーティクライアントの想定ベースラインです。 +`src/gateway/client.ts` の参照クライアントはこれらのデフォルトを使用します。値は +プロトコル v3 全体で安定しており、サードパーティクライアントに期待される基準です。 | 定数 | デフォルト | ソース | | ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | -| リクエストタイムアウト（RPC ごと） | `30_000` ms | `src/gateway/client.ts`（`requestTimeoutMs`） | -| 事前認証 / 接続チャレンジタイムアウト | `15_000` ms | `src/gateway/handshake-timeouts.ts`（config/env でサーバー/クライアントの組み合わせ予算を引き上げ可能） | -| 初回再接続バックオフ | `1_000` ms | `src/gateway/client.ts`（`backoffMs`） | -| 最大再接続バックオフ | `30_000` ms | `src/gateway/client.ts`（`scheduleReconnect`） | -| デバイストークン close 後の高速リトライ上限 | `250` ms | `src/gateway/client.ts` | +| リクエストタイムアウト（RPC ごと） | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | +| 事前認証 / 接続チャレンジタイムアウト | `15_000` ms | `src/gateway/handshake-timeouts.ts`（config/env で対応するサーバー/クライアントの予算を増やせます） | +| 初期再接続バックオフ | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | +| 最大再接続バックオフ | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | +| デバイストークンクローズ後の高速リトライ上限 | `250` ms | `src/gateway/client.ts` | | `terminate()` 前の強制停止猶予 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | -| `stopAndWait()` デフォルトタイムアウト | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | +| `stopAndWait()` デフォルトタイムアウト | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | | デフォルト tick 間隔（`hello-ok` 前） | `30_000` ms | `src/gateway/client.ts` | -| tick タイムアウト close | 無通信が `tickIntervalMs * 2` を超えると code `4000` | `src/gateway/client.ts` | -| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024`（25 MB） | `src/gateway/server-constants.ts` | +| tick タイムアウトクローズ | 無音が `tickIntervalMs * 2` を超えた場合は code `4000` | `src/gateway/client.ts` | +| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | -サーバーは有効な `policy.tickIntervalMs`、`policy.maxPayload`、 -`policy.maxBufferedBytes` を `hello-ok` で通知します。クライアントは -ハンドシェイク前のデフォルトではなく、それらの値に従う必要があります。 +サーバーは実効 `policy.tickIntervalMs`、`policy.maxPayload`、および `policy.maxBufferedBytes` を `hello-ok` で通知します。クライアントは、ハンドシェイク前のデフォルトではなく、これらの値に従うべきです。 ## 認証 -- 共有シークレット Gateway 認証は、設定済みの認証モードに応じて `connect.params.auth.token` または +- 共有シークレット Gateway 認証は、設定済み認証モードに応じて `connect.params.auth.token` または `connect.params.auth.password` を使用します。 -- Tailscale Serve - （`gateway.auth.allowTailscale: true`）や非ループバックの - `gateway.auth.mode: "trusted-proxy"` など、アイデンティティを持つモードは、 - `connect.params.auth.*` ではなくリクエストヘッダーから接続認証チェックを満たします。 -- プライベート入口の `gateway.auth.mode: "none"` は、共有シークレット接続認証を - 完全にスキップします。このモードを公開/信頼できない入口で公開しないでください。 -- ペアリング後、Gateway は接続ロール + スコープに限定された **デバイストークン** を発行します。これは `hello-ok.auth.deviceToken` で返され、クライアントが今後の接続用に永続化する必要があります。 -- クライアントは、接続に成功するたびに主 `hello-ok.auth.deviceToken` を永続化する必要があります。 -- その **保存済み** デバイストークンで再接続する場合は、そのトークンに対して保存された承認済みスコープセットも再利用する必要があります。これにより、すでに付与された read/probe/status アクセスが維持され、再接続がより狭い暗黙の admin のみのスコープへ静かに縮小されることを避けられます。 +- Tailscale Serve (`gateway.auth.allowTailscale: true`) や non-loopback + `gateway.auth.mode: "trusted-proxy"` などの ID を持つモードは、`connect.params.auth.*` ではなく + リクエストヘッダーから接続認証チェックを満たします。 +- プライベートイングレスの `gateway.auth.mode: "none"` は、共有シークレット接続認証を完全にスキップします。このモードを公開または信頼されていないイングレスに公開しないでください。 +- ペアリング後、Gateway は接続ロール + スコープに限定された **デバイストークン** を発行します。これは `hello-ok.auth.deviceToken` で返され、今後の接続のためにクライアントが永続化すべきです。 +- クライアントは、接続が成功するたびに主要な `hello-ok.auth.deviceToken` を永続化すべきです。 +- その **保存済み** デバイストークンで再接続する場合、そのトークンに対して保存済みの承認済みスコープセットも再利用すべきです。これにより、すでに許可された読み取り/プローブ/ステータスアクセスが保持され、再接続が暗黙の管理者専用スコープへ密かに狭まることを避けられます。 - クライアント側の接続認証組み立て（`src/gateway/client.ts` の `selectConnectAuth`）: - - `auth.password` は独立しており、設定されている場合は常に転送されます。 - - `auth.token` は優先順位に従って設定されます。最初に明示的な共有トークン、次に明示的な `deviceToken`、次に保存済みのデバイスごとのトークン（`deviceId` + `role` をキーにする）です。 - - `auth.bootstrapToken` は、上記のいずれも `auth.token` を解決しなかった場合にのみ送信されます。共有トークンまたは解決済みデバイストークンはこれを抑制します。 - - ワンショットの `AUTH_TOKEN_MISMATCH` リトライで、保存済みデバイストークンを自動昇格する処理は、**信頼済みエンドポイントのみ** に制限されます。 - つまり、ループバック、またはピン留めされた `tlsFingerprint` を持つ `wss://` です。ピン留めのない公開 `wss://` - は該当しません。 -- 追加の `hello-ok.auth.deviceTokens` エントリは、ブートストラップの引き渡しトークンです。 - `wss://` やループバック/local ペアリングなど、信頼済みトランスポート上でブートストラップ認証を使用した接続の場合にのみ永続化してください。 -- クライアントが **明示的な** `deviceToken` または明示的な `scopes` を提供した場合、 - 呼び出し元が要求したそのスコープセットが引き続き信頼できる値になります。キャッシュ済みスコープは、クライアントが保存済みのデバイスごとのトークンを再利用している場合にのみ再利用されます。 + - `auth.password` は直交しており、設定されている場合は常に転送されます。 + - `auth.token` は優先順位に従って設定されます。まず明示的な共有トークン、次に明示的な `deviceToken`、最後に保存済みのデバイス単位トークン（`deviceId` + `role` をキーにする）です。 + - `auth.bootstrapToken` は、上記のいずれも `auth.token` を解決しなかった場合にのみ送信されます。共有トークンまたは解決済みデバイストークンがある場合は抑制されます。 + - 一度限りの `AUTH_TOKEN_MISMATCH` リトライで保存済みデバイストークンを自動昇格する処理は、**信頼済みエンドポイントのみ** に制限されます — + loopback、または固定された `tlsFingerprint` を持つ `wss://` です。ピン留めのない公開 `wss://` は該当しません。 +- 追加の `hello-ok.auth.deviceTokens` エントリはブートストラップ引き渡しトークンです。 + `wss://` や loopback/local ペアリングなどの信頼済みトランスポートでブートストラップ認証を使用して接続した場合にのみ永続化します。 +- クライアントが **明示的な** `deviceToken` または明示的な `scopes` を指定した場合、その呼び出し元が要求したスコープセットが引き続き権威を持ちます。キャッシュ済みスコープは、クライアントが保存済みのデバイス単位トークンを再利用している場合にのみ再利用されます。 - デバイストークンは `device.token.rotate` と `device.token.revoke`（`operator.pairing` スコープが必要）でローテーション/失効できます。 -- `device.token.rotate` はローテーションメタデータを返します。置換用ベアラートークンは、そのデバイストークンですでに認証されている同一デバイスの呼び出しに対してのみエコーするため、トークンのみのクライアントは再接続前に置換トークンを永続化できます。共有/admin ローテーションではベアラートークンはエコーされません。 -- トークンの発行、ローテーション、失効は、そのデバイスのペアリングエントリに記録された承認済みロールセットに限定されます。トークン変更によって、ペアリング承認で付与されていないデバイスロールへ拡張したり、それを対象にしたりすることはできません。 -- ペアリング済みデバイストークンセッションでは、呼び出し元が `operator.admin` も持つ場合を除き、デバイス管理は自己スコープです。非 admin 呼び出し元は **自分自身の** デバイスエントリのみを削除/失効/ローテーションできます。 -- `device.token.rotate` と `device.token.revoke` は、対象オペレータートークンのスコープセットを、呼び出し元の現在のセッションスコープとも照合します。非 admin 呼び出し元は、自分がすでに保持しているものより広いオペレータートークンをローテーションまたは失効できません。 -- 認証失敗には、`error.details.code` と復旧ヒントが含まれます。 +- `device.token.rotate` はローテーションメタデータを返します。置換後の bearer token をエコーするのは、そのデバイストークンですでに認証されている同一デバイス呼び出しの場合のみです。そのため、トークンのみのクライアントは再接続前に置換トークンを永続化できます。共有/管理者ローテーションでは bearer token はエコーされません。 +- トークンの発行、ローテーション、失効は、そのデバイスのペアリングエントリに記録された承認済みロールセットの範囲内に留まります。トークン変更によって、ペアリング承認で許可されていないデバイスロールへ拡張したり対象化したりすることはできません。 +- ペアリング済みデバイストークンセッションでは、呼び出し元が `operator.admin` も持っていない限り、デバイス管理は自身のスコープに限定されます。非管理者の呼び出し元は **自分自身の** デバイスエントリのみを削除/失効/ローテーションできます。 +- `device.token.rotate` と `device.token.revoke` は、対象オペレータートークンのスコープセットも呼び出し元の現在のセッションスコープと照合します。非管理者の呼び出し元は、自分がすでに保持しているより広いオペレータートークンをローテーションまたは失効できません。 +- 認証失敗には、`error.details.code` と回復ヒントが含まれます。 - `error.details.canRetryWithDeviceToken`（boolean） - - `error.details.recommendedNextStep`（`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`） + - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - `AUTH_TOKEN_MISMATCH` に対するクライアント動作: - - 信頼済みクライアントは、キャッシュ済みのデバイスごとのトークンで、制限された 1 回のリトライを試行できます。 - - そのリトライが失敗した場合、クライアントは自動再接続ループを停止し、オペレーターの対応ガイダンスを表示する必要があります。 + - 信頼済みクライアントは、キャッシュ済みデバイス単位トークンで 1 回だけ範囲を限定したリトライを試行できます。 + - そのリトライが失敗した場合、クライアントは自動再接続ループを停止し、オペレーター向けの対応ガイダンスを表示すべきです。 ## デバイス ID + ペアリング -- Node には、キーペアのフィンガープリントから導出された安定したデバイス ID（`device.id`）を含める必要がある。 -- Gateway はデバイス + ロールごとにトークンを発行する。 -- local 自動承認が有効でない限り、新しいデバイス ID にはペアリング承認が必要。 -- ペアリングの自動承認は、直接の local loopback 接続を中心にしている。 -- OpenClaw には、信頼済み共有シークレットのヘルパーフロー向けに、限定的なバックエンド/コンテナ内 self-connect パスもある。 -- 同一ホストの tailnet または LAN 接続も、ペアリングでは引き続きリモートとして扱われ、承認が必要。 -- WS クライアントは通常、`connect` 時に `device` identity を含める（operator + node）。デバイスなしの operator 例外は、明示的な trust パスのみ。 - - localhost 専用の安全でない HTTP 互換性のための `gateway.controlUi.allowInsecureAuth=true`。 - - 成功した `gateway.auth.mode: "trusted-proxy"` operator Control UI 認証。 - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（緊急回避、重大なセキュリティ低下）。 - - 共有 gateway トークン/パスワードで認証された、direct-loopback の `gateway-client` バックエンド RPC。 -- すべての接続は、サーバーから提供された `connect.challenge` nonce に署名する必要がある。 +- Node には、キーペアのフィンガープリントから派生した安定したデバイス ID（`device.id`）を含める必要があります。 +- Gateway はデバイス + ロールごとにトークンを発行します。 +- local auto-approval が有効でない限り、新しいデバイス ID にはペアリング承認が必要です。 +- ペアリングの自動承認は、直接の local loopback 接続を中心にしています。 +- OpenClaw には、信頼済み共有シークレットのヘルパーフロー向けに、限定的なバックエンド/コンテナローカルの自己接続パスもあります。 +- 同一ホストの tailnet または LAN 接続も、ペアリングでは引き続きリモートとして扱われ、承認が必要です。 +- WS クライアントは通常、`connect` 時に `device` ID を含めます（オペレーター + node）。デバイスなしオペレーターの例外は、明示的な信頼パスのみです: + - localhost 限定の安全でない HTTP 互換性のための `gateway.controlUi.allowInsecureAuth=true`。 + - 成功した `gateway.auth.mode: "trusted-proxy"` のオペレーター Control UI 認証。 + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（緊急回避用、重大なセキュリティ低下）。 + - 共有 Gateway トークン/パスワードで認証された、直接 loopback の `gateway-client` バックエンド RPC。 +- すべての接続は、サーバーが提供する `connect.challenge` nonce に署名する必要があります。 ### デバイス認証移行診断 -pre-challenge 署名動作をまだ使用しているレガシークライアントでは、`connect` は安定した `error.details.reason` とともに、`error.details.code` に `DEVICE_AUTH_*` 詳細コードを返すようになった。 +チャレンジ前署名の挙動をまだ使用しているレガシークライアントでは、`connect` は安定した `error.details.reason` とともに、`error.details.code` に `DEVICE_AUTH_*` 詳細コードを返すようになりました。 一般的な移行失敗: -| メッセージ | details.code | details.reason | 意味 | +| メッセージ | details.code | details.reason | 意味 | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | クライアントが `device.nonce` を省略した（または空で送信した）。 | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | クライアントが古い/誤った nonce で署名した。 | -| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 署名ペイロードが v2 ペイロードと一致しない。 | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 署名済みタイムスタンプが許容 skew の範囲外。 | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | クライアントが `device.nonce` を省略した（または空を送信した）。 | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | クライアントが古い/誤った nonce で署名した。 | +| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 署名ペイロードが v2 ペイロードと一致しない。 | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 署名済みタイムスタンプが許容スキューの範囲外です。 | | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` が公開鍵フィンガープリントと一致しない。 | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公開鍵の形式/正規化に失敗した。 | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公開鍵の形式/正規化に失敗した。 | 移行先: -- 常に `connect.challenge` を待つ。 -- サーバー nonce を含む v2 ペイロードに署名する。 -- 同じ nonce を `connect.params.device.nonce` で送信する。 -- 推奨される署名ペイロードは `v3`。これは device/client/role/scopes/token/nonce フィールドに加えて、`platform` と `deviceFamily` を束縛する。 -- レガシー `v2` 署名は互換性のため引き続き受け入れられるが、再接続時のコマンドポリシーは paired-device メタデータのピン留めによって引き続き制御される。 +- 必ず `connect.challenge` を待ちます。 +- サーバー nonce を含む v2 ペイロードに署名します。 +- 同じ nonce を `connect.params.device.nonce` で送信します。 +- 推奨される署名ペイロードは `v3` で、device/client/role/scopes/token/nonce フィールドに加えて `platform` と `deviceFamily` を束縛します。 +- レガシー `v2` 署名は互換性のため引き続き受け入れられますが、ペアリング済みデバイスのメタデータ pinning が、再接続時のコマンドポリシーを引き続き制御します。 -## TLS + ピン留め +## TLS + pinning -- TLS は WS 接続でサポートされる。 -- クライアントは必要に応じて gateway 証明書フィンガープリントをピン留めできる（`gateway.tls` config に加えて、`gateway.remote.tlsFingerprint` または CLI `--tls-fingerprint` を参照）。 +- WS 接続では TLS がサポートされています。 +- クライアントは任意で Gateway 証明書フィンガープリントを pinning できます（`gateway.tls` 設定と `gateway.remote.tlsFingerprint`、または CLI `--tls-fingerprint` を参照）。 ## スコープ -このプロトコルは **完全な gateway API**（status、channels、models、chat、agent、sessions、nodes、approvals など）を公開する。正確なサーフェスは `src/gateway/protocol/schema.ts` の TypeBox schemas で定義される。 +このプロトコルは、**完全な Gateway API**（ステータス、チャネル、モデル、チャット、エージェント、セッション、ノード、承認など）を公開します。正確なサーフェスは、`src/gateway/protocol/schema.ts` の TypeBox スキーマで定義されています。 ## 関連 -- [Bridge protocol](/ja-JP/gateway/bridge-protocol) -- [Gateway runbook](/ja-JP/gateway) +- [ブリッジプロトコル](/ja-JP/gateway/bridge-protocol) +- [Gateway ランブック](/ja-JP/gateway) diff --git a/docs/ja-JP/gateway/troubleshooting.md b/docs/ja-JP/gateway/troubleshooting.md index 8fdeeca20..35306309e 100644 --- a/docs/ja-JP/gateway/troubleshooting.md +++ b/docs/ja-JP/gateway/troubleshooting.md @@ -1,24 +1,24 @@ --- read_when: - トラブルシューティングハブから、より詳しい診断のためにここへ案内されました - - 正確なコマンドを含む、安定した症状ベースのランブックセクションが必要です + - 正確なコマンドを含む、症状別の安定したランブックセクションが必要です sidebarTitle: Troubleshooting summary: Gateway、チャンネル、自動化、ノード、ブラウザー向けの詳細なトラブルシューティングランブック title: トラブルシューティング x-i18n: - generated_at: "2026-04-30T05:16:29Z" + generated_at: "2026-05-01T05:01:23Z" model: gpt-5.5 provider: openai - source_hash: 48735a68daa92678867a9cafb3ceeb37063bb91dee8c4c94e185f74eb0296fcb + source_hash: a808dcfd8527b041f629cff24308550f961e9eeb4d7d4ce6f1ce84dff6bbef89 source_path: gateway/troubleshooting.md workflow: 16 --- -このページは詳細なランブックです。先に高速なトリアージフローを確認したい場合は、[/help/troubleshooting](/ja-JP/help/troubleshooting) から始めてください。 +このページは詳細なランブックです。まず高速なトリアージフローを確認したい場合は、[/help/troubleshooting](/ja-JP/help/troubleshooting) から始めてください。 -## コマンドの手順 +## コマンドの順序 -最初に、次の順序で実行します。 +まず、次の順序で実行します。 ```bash openclaw status @@ -31,14 +31,14 @@ openclaw channels status --probe 正常時に期待されるシグナル: - `openclaw gateway status` に `Runtime: running`、`Connectivity probe: ok`、および `Capability: ...` 行が表示される。 -- `openclaw doctor` がブロック要因となる設定/サービスの問題を報告しない。 -- `openclaw channels status --probe` がアカウントごとのライブ転送ステータスと、対応している場合は `works` や `audit ok` などのプローブ/監査結果を表示する。 +- `openclaw doctor` が、ブロック要因となる設定/サービスの問題を報告しない。 +- `openclaw channels status --probe` に、アカウントごとのライブのトランスポート状態と、対応している場合は `works` や `audit ok` などのプローブ/監査結果が表示される。 -## 分裂したインストールと新しい設定ガード +## スプリットブレインインストールと新しい設定ガード -更新後に Gateway サービスが予期せず停止する場合、またはログに、ある `openclaw` バイナリが最後に `openclaw.json` を書き込んだバージョンより古いことが示される場合に使用します。 +更新後に Gateway サービスが予期せず停止する場合、またはログに、ある `openclaw` バイナリが最後に `openclaw.json` を書き込んだバージョンより古いことが示されている場合に使用します。 -OpenClaw は設定の書き込みに `meta.lastTouchedVersion` を記録します。読み取り専用コマンドは、より新しい OpenClaw によって書き込まれた設定を引き続き検査できますが、プロセスとサービスの変更は古いバイナリからの継続を拒否します。ブロックされる操作には、Gateway サービスの開始、停止、再起動、アンインストール、強制サービス再インストール、サービスモードでの Gateway 起動、`gateway --force` のポートクリーンアップが含まれます。 +OpenClaw は設定の書き込みに `meta.lastTouchedVersion` をスタンプします。読み取り専用コマンドは、新しい OpenClaw が書き込んだ設定を引き続き検査できますが、プロセスとサービスの変更は古いバイナリからの続行を拒否します。ブロックされる操作には、Gateway サービスの起動、停止、再起動、アンインストール、強制サービス再インストール、サービスモードでの Gateway 起動、`gateway --force` によるポートクリーンアップが含まれます。 ```bash which openclaw @@ -49,10 +49,10 @@ openclaw config get meta.lastTouchedVersion - `openclaw` がより新しいインストールを解決するように `PATH` を修正し、その後アクションを再実行します。 + `PATH` を修正して、`openclaw` が新しいインストール先を解決するようにしてから、操作を再実行します。 - より新しいインストールから、意図した Gateway サービスを再インストールします。 + 新しいインストール先から意図した Gateway サービスを再インストールします。 ```bash openclaw gateway install --force @@ -61,15 +61,15 @@ openclaw config get meta.lastTouchedVersion - 古い `openclaw` バイナリをまだ指している、古いシステムパッケージまたは古いラッパーエントリを削除します。 + 古い `openclaw` バイナリをまだ指している古いシステムパッケージまたはラッパーのエントリを削除します。 -意図的なダウングレードまたは緊急復旧の場合にのみ、単一のコマンドに対して `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` を設定してください。通常運用では未設定のままにします。 +意図的なダウングレードまたは緊急復旧の場合のみ、その単一のコマンドに `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` を設定してください。通常運用では未設定のままにします。 -## 長いコンテキストには Anthropic 429 の追加使用量が必要 +## 長いコンテキストには Anthropic 429 追加使用量が必要 ログ/エラーに `HTTP 429: rate_limit_error: Extra usage is required for long context requests` が含まれる場合に使用します。 @@ -79,23 +79,23 @@ openclaw models status openclaw config get agents.defaults.models ``` -確認する内容: +確認すること: - 選択された Anthropic Opus/Sonnet モデルに `params.context1m: true` がある。 - 現在の Anthropic 認証情報が長いコンテキストの使用対象ではない。 -- リクエストが、1M ベータパスを必要とする長いセッション/モデル実行でのみ失敗する。 +- 失敗するのは、1M ベータパスを必要とする長いセッション/モデル実行のみ。 修正オプション: - そのモデルの `context1m` を無効にして、通常のコンテキストウィンドウへフォールバックします。 + そのモデルの `context1m` を無効にして、通常のコンテキストウィンドウにフォールバックします。 - 長いコンテキストリクエストの対象となる Anthropic 認証情報を使用するか、Anthropic API キーに切り替えます。 + 長いコンテキスト要求の対象となる Anthropic 認証情報を使用するか、Anthropic API キーに切り替えます。 - Anthropic の長いコンテキストリクエストが拒否されても実行が継続するように、フォールバックモデルを設定します。 + Anthropic の長いコンテキスト要求が拒否された場合でも実行が継続されるように、フォールバックモデルを設定します。 @@ -122,29 +122,29 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -確認する内容: +確認すること: - 小さな直接呼び出しは成功するが、OpenClaw の実行は大きなプロンプトでのみ失敗する - 同じ素のモデル ID で直接 `/v1/chat/completions` - が動作しているにもかかわらず、`model_not_found` または 404 エラーが発生する -- `messages[].content` が文字列を期待しているというバックエンドエラー -- OpenAI 互換ローカルバックエンドで、断続的に `incomplete turn detected ... stopReason=stop payloads=0` 警告が出る + は動作するにもかかわらず、`model_not_found` または 404 エラーが発生する +- `messages[].content` が文字列を想定しているというバックエンドエラー +- OpenAI 互換のローカルバックエンドで断続的に発生する `incomplete turn detected ... stopReason=stop payloads=0` 警告 - より大きなプロンプトトークン数または完全なエージェントランタイムプロンプトでのみ発生するバックエンドクラッシュ - - ローカル MLX/vLLM スタイルのサーバーで `model_not_found` → `baseUrl` に `/v1` が含まれること、`/v1/chat/completions` バックエンドでは `api` が `"openai-completions"` であること、`models.providers..models[].id` が素のプロバイダー内 ID であることを確認します。選択時は一度だけプロバイダープレフィックス付きで指定します。例: `mlx/mlx-community/Qwen3-30B-A3B-6bit`; カタログエントリは `mlx-community/Qwen3-30B-A3B-6bit` のままにします。 - - `messages[...].content: invalid type: sequence, expected a string` → バックエンドが構造化された Chat Completions コンテンツパーツを拒否しています。修正: `models.providers..models[].compat.requiresStringContent: true` を設定します。 - - `incomplete turn detected ... stopReason=stop payloads=0` → バックエンドは Chat Completions リクエストを完了しましたが、そのターンにユーザーが見えるアシスタントテキストを返していません。OpenClaw は再生しても安全な空の OpenAI 互換ターンを一度だけ再試行します。継続的な失敗は通常、バックエンドが空/非テキストのコンテンツを出力しているか、最終回答テキストを抑制していることを意味します。 - - 小さな直接リクエストは成功するが、OpenClaw エージェント実行がバックエンド/モデルのクラッシュで失敗する（例: 一部の `inferrs` ビルド上の Gemma）→ OpenClaw の転送はおそらくすでに正しいです。バックエンドが、より大きなエージェントランタイムプロンプト形状で失敗しています。 - - ツールを無効化すると失敗は減るが消えない → ツールスキーマは負荷の一部でしたが、残る問題は依然として上流モデル/サーバーの容量またはバックエンドのバグです。 + - ローカルの MLX/vLLM スタイルのサーバーで `model_not_found` → `baseUrl` に `/v1` が含まれていること、`/v1/chat/completions` バックエンドでは `api` が `"openai-completions"` であること、`models.providers..models[].id` が素のプロバイダーローカル ID であることを確認してください。たとえば `mlx/mlx-community/Qwen3-30B-A3B-6bit` のように、プロバイダープレフィックスを一度付けて選択します。カタログエントリは `mlx-community/Qwen3-30B-A3B-6bit` のままにします。 + - `messages[...].content: invalid type: sequence, expected a string` → バックエンドが構造化された Chat Completions のコンテンツパーツを拒否しています。修正: `models.providers..models[].compat.requiresStringContent: true` を設定します。 + - `incomplete turn detected ... stopReason=stop payloads=0` → バックエンドは Chat Completions 要求を完了しましたが、そのターンでユーザーに表示されるアシスタントテキストを返していません。OpenClaw は、再生しても安全な空の OpenAI 互換ターンを 1 回再試行します。失敗が継続する場合、通常はバックエンドが空/非テキストのコンテンツを出力しているか、最終回答テキストを抑制していることを意味します。 + - 小さな直接要求は成功するが、OpenClaw エージェント実行がバックエンド/モデルのクラッシュで失敗する（たとえば一部の `inferrs` ビルド上の Gemma）→ OpenClaw のトランスポートはすでに正しい可能性が高く、バックエンドが大きなエージェントランタイムプロンプト形状で失敗しています。 + - ツールを無効にすると失敗は減るが、消えない → ツールスキーマは負荷の一部でしたが、残る問題は依然として上流のモデル/サーバー容量、またはバックエンドのバグです。 1. 文字列のみの Chat Completions バックエンドには `compat.requiresStringContent: true` を設定します。 - 2. OpenClaw のツールスキーマサーフェスを確実に処理できないモデル/バックエンドには `compat.supportsTools: false` を設定します。 - 3. 可能な範囲でプロンプト負荷を下げます: より小さいワークスペースブートストラップ、より短いセッション履歴、より軽いローカルモデル、またはより強力な長いコンテキスト対応を持つバックエンド。 - 4. 小さな直接リクエストは通り続ける一方で OpenClaw エージェントターンがバックエンド内部でまだクラッシュする場合は、上流サーバー/モデルの制限として扱い、受け入れられたペイロード形状とともにそこで再現報告を提出します。 + 2. OpenClaw のツールスキーマサーフェスを安定して処理できないモデル/バックエンドには `compat.supportsTools: false` を設定します。 + 3. 可能な範囲でプロンプト負荷を下げます。小さめのワークスペースブートストラップ、短いセッション履歴、軽量なローカルモデル、またはより強い長いコンテキスト対応を持つバックエンドを使用します。 + 4. 小さな直接要求が通り続ける一方で OpenClaw エージェントターンがバックエンド内でまだクラッシュする場合は、上流のサーバー/モデルの制限として扱い、受け入れられたペイロード形状とともに再現手順をそちらに報告します。 @@ -166,16 +166,16 @@ openclaw config get channels openclaw logs --follow ``` -確認する内容: +確認すること: - DM 送信者のペアリングが保留中。 -- グループメンションのゲート制御（`requireMention`、`mentionPatterns`）。 +- グループメンションゲーティング（`requireMention`、`mentionPatterns`）。 - チャンネル/グループの許可リスト不一致。 一般的なシグネチャ: - `drop guild message (mention required` → メンションされるまでグループメッセージは無視されます。 -- `pairing request` → 送信者の承認が必要です。 +- `pairing request` → 送信者には承認が必要です。 - `blocked` / `allowlist` → 送信者/チャンネルがポリシーによってフィルタリングされました。 関連: @@ -186,7 +186,7 @@ openclaw logs --follow ## ダッシュボード制御 UI の接続性 -ダッシュボード/制御 UI が接続しない場合は、URL、認証モード、セキュアコンテキストの前提を検証します。 +ダッシュボード/制御 UI が接続しない場合は、URL、認証モード、およびセキュアコンテキストの前提を検証します。 ```bash openclaw gateway status @@ -196,42 +196,42 @@ openclaw doctor openclaw gateway status --json ``` -確認する内容: +確認すること: - 正しいプローブ URL とダッシュボード URL。 -- クライアントと Gateway の間の認証モード/トークン不一致。 +- クライアントと Gateway の間で認証モード/トークンが不一致。 - デバイス ID が必要な場所で HTTP を使用している。 - `device identity required` → 非セキュアコンテキスト、またはデバイス認証の欠落。 - - `origin not allowed` → ブラウザーの `Origin` が `gateway.controlUi.allowedOrigins` に含まれていません（または明示的な許可リストなしで非ループバックブラウザーオリジンから接続しています）。 + - `origin not allowed` → ブラウザーの `Origin` が `gateway.controlUi.allowedOrigins` に含まれていません（または、明示的な許可リストなしで非ループバックのブラウザーオリジンから接続しています）。 - `device nonce required` / `device nonce mismatch` → クライアントがチャレンジベースのデバイス認証フロー（`connect.challenge` + `device.nonce`）を完了していません。 - `device signature invalid` / `device signature expired` → クライアントが現在のハンドシェイクに対して誤ったペイロード（または古いタイムスタンプ）に署名しました。 - - `AUTH_TOKEN_MISMATCH` かつ `canRetryWithDeviceToken=true` → クライアントはキャッシュ済みデバイストークンで信頼済みリトライを一度実行できます。 - - そのキャッシュトークンリトライでは、ペアリング済みデバイストークンとともに保存されたキャッシュ済みスコープセットを再利用します。明示的な `deviceToken` / 明示的な `scopes` 呼び出し元は、代わりに要求したスコープセットを保持します。 - - そのリトライパスの外では、接続認証の優先順位は、明示的な共有トークン/パスワード、次に明示的な `deviceToken`、次に保存済みデバイストークン、最後にブートストラップトークンです。 - - 非同期 Tailscale Serve Control UI パスでは、同じ `{scope, ip}` に対する失敗試行は、リミッターが失敗を記録する前に直列化されます。そのため、同じクライアントからの不正な同時リトライが 2 つある場合、2 つの単純な不一致ではなく、2 回目の試行で `retry later` が表面化することがあります。 - - ブラウザーオリジンのループバッククライアントから `too many failed authentication attempts (retry later)` → 同じ正規化済み `Origin` からの失敗が繰り返され、一時的にロックアウトされています。別の localhost オリジンは別バケットを使用します。 - - そのリトライ後も `unauthorized` が繰り返される → 共有トークン/デバイストークンのずれです。必要に応じてトークン設定を更新し、デバイストークンを再承認/ローテーションします。 - - `gateway connect failed:` → ホスト/ポート/URL ターゲットが誤っています。 + - `AUTH_TOKEN_MISMATCH` かつ `canRetryWithDeviceToken=true` → クライアントはキャッシュ済みデバイストークンで信頼済みリトライを 1 回実行できます。 + - そのキャッシュ済みトークンでのリトライは、ペアリング済みデバイストークンとともに保存されたキャッシュ済みスコープセットを再利用します。明示的な `deviceToken` / 明示的な `scopes` の呼び出し元は、代わりに要求したスコープセットを維持します。 + - そのリトライパス以外では、接続認証の優先順位は、明示的な共有トークン/パスワード、明示的な `deviceToken`、保存済みデバイストークン、ブートストラップトークンの順です。 + - 非同期 Tailscale Serve Control UI パスでは、同じ `{scope, ip}` の失敗試行は、リミッターが失敗を記録する前にシリアル化されます。そのため、同じクライアントからの 2 つの不正な同時リトライでは、2 つの単純な不一致ではなく、2 回目の試行で `retry later` が表面化することがあります。 + - ブラウザーオリジンのループバッククライアントから `too many failed authentication attempts (retry later)` → 同じ正規化済み `Origin` からの繰り返し失敗が一時的にロックアウトされています。別の localhost オリジンは別のバケットを使用します。 + - そのリトライ後も `unauthorized` が繰り返される → 共有トークン/デバイストークンのドリフトです。トークン設定を更新し、必要に応じてデバイストークンを再承認/ローテーションしてください。 + - `gateway connect failed:` → ホスト/ポート/URL ターゲットが間違っています。 ### 認証詳細コードのクイックマップ -失敗した `connect` レスポンスの `error.details.code` を使用して、次のアクションを選択します。 +失敗した `connect` レスポンスの `error.details.code` を使用して、次の操作を選択します。 -| 詳細コード | 意味 | 推奨される対応 | +| 詳細コード | 意味 | 推奨アクション | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | クライアントが必要な共有トークンを送信しませんでした。 | クライアントにトークンを貼り付けるか設定して、再試行します。ダッシュボードのパスの場合: `openclaw config get gateway.auth.token` を実行してから、Control UI 設定に貼り付けます。 | -| `AUTH_TOKEN_MISMATCH` | 共有トークンが Gateway 認証トークンと一致しませんでした。 | `canRetryWithDeviceToken=true` の場合は、信頼済みの再試行を 1 回許可します。キャッシュされたトークンでの再試行では、保存済みの承認済みスコープを再利用します。明示的な `deviceToken` / `scopes` 呼び出し元は要求したスコープを保持します。それでも失敗する場合は、[トークンドリフト復旧チェックリスト](/ja-JP/cli/devices#token-drift-recovery-checklist)を実行します。 | -| `AUTH_DEVICE_TOKEN_MISMATCH` | キャッシュされたデバイスごとのトークンが古いか、取り消されています。 | [デバイス CLI](/ja-JP/cli/devices) を使ってデバイストークンをローテーションまたは再承認してから、再接続します。 | -| `PAIRING_REQUIRED` | デバイス ID の承認が必要です。`error.details.reason` で `not-paired`、`scope-upgrade`、`role-upgrade`、または `metadata-upgrade` を確認し、存在する場合は `requestId` / `remediationHint` を使用します。 | 保留中のリクエストを承認します: `openclaw devices list` の後に `openclaw devices approve ` を実行します。スコープ/ロールのアップグレードでは、要求されたアクセスを確認した後に同じフローを使用します。 | +| `AUTH_TOKEN_MISSING` | クライアントが必須の共有トークンを送信しませんでした。 | クライアントにトークンを貼り付けるか設定して、再試行します。ダッシュボード経路の場合: `openclaw config get gateway.auth.token` を実行してから Control UI 設定に貼り付けます。 | +| `AUTH_TOKEN_MISMATCH` | 共有トークンが Gateway 認証トークンと一致しませんでした。 | `canRetryWithDeviceToken=true` の場合は、信頼済みの再試行を 1 回許可します。キャッシュ済みトークンによる再試行では、保存済みの承認済みスコープを再利用します。明示的な `deviceToken` / `scopes` 呼び出し元は、要求したスコープを維持します。それでも失敗する場合は、[トークンドリフト復旧チェックリスト](/ja-JP/cli/devices#token-drift-recovery-checklist)を実行します。 | +| `AUTH_DEVICE_TOKEN_MISMATCH` | キャッシュ済みのデバイス単位トークンが古いか、取り消されています。 | [devices CLI](/ja-JP/cli/devices) を使ってデバイストークンをローテートまたは再承認し、その後再接続します。 | +| `PAIRING_REQUIRED` | デバイス ID の承認が必要です。`error.details.reason` で `not-paired`、`scope-upgrade`、`role-upgrade`、または `metadata-upgrade` を確認し、存在する場合は `requestId` / `remediationHint` を使います。 | 保留中のリクエストを承認します: `openclaw devices list` の後に `openclaw devices approve ` を実行します。スコープ/ロールのアップグレードも、要求されたアクセスを確認した後に同じフローを使います。 | -共有 Gateway トークン/パスワードで認証される直接 loopback バックエンド RPC は、CLI のペアリング済みデバイススコープのベースラインに依存すべきではありません。サブエージェントやその他の内部呼び出しがまだ `scope-upgrade` で失敗する場合は、呼び出し元が `client.id: "gateway-client"` と `client.mode: "backend"` を使用しており、明示的な `deviceIdentity` やデバイストークンを強制していないことを確認してください。 +共有 Gateway トークン/パスワードで認証された直接 loopback バックエンド RPC は、CLI のペアリング済みデバイスのスコープベースラインに依存すべきではありません。サブエージェントやその他の内部呼び出しがまだ `scope-upgrade` で失敗する場合は、呼び出し元が `client.id: "gateway-client"` と `client.mode: "backend"` を使っており、明示的な `deviceIdentity` やデバイストークンを強制していないことを確認します。 デバイス認証 v2 の移行チェック: @@ -242,24 +242,24 @@ openclaw doctor openclaw gateway status ``` -ログに nonce/署名エラーが表示される場合は、接続元クライアントを更新して検証します。 +ログに nonce/署名エラーが表示される場合は、接続元クライアントを更新して検証します: - - クライアントは Gateway が発行した `connect.challenge` を待ちます。 + + クライアントは Gateway が発行する `connect.challenge` を待機します。 - - クライアントはチャレンジにバインドされたペイロードに署名します。 + + クライアントはチャレンジに紐づいたペイロードに署名します。 - - クライアントは同じチャレンジ nonce を使用して `connect.params.device.nonce` を送信します。 + + クライアントは同じチャレンジ nonce を使って `connect.params.device.nonce` を送信します。 `openclaw devices rotate` / `revoke` / `remove` が予期せず拒否される場合: -- ペアリング済みデバイストークンのセッションは、呼び出し元が `operator.admin` も持っていない限り、**自身の**デバイスしか管理できません -- `openclaw devices rotate --scope ...` は、呼び出し元セッションがすでに保持しているオペレータースコープのみ要求できます +- ペアリング済みデバイストークンのセッションは、呼び出し元が `operator.admin` も持っていない限り、**自身の** デバイスしか管理できません +- `openclaw devices rotate --scope ...` は、呼び出し元セッションがすでに保持している operator スコープのみを要求できます 関連: @@ -271,7 +271,7 @@ openclaw gateway status ## Gateway サービスが実行されていない -サービスはインストールされているが、プロセスが起動したままにならない場合に使用します。 +サービスはインストール済みだが、プロセスが起動し続けない場合に使います。 ```bash openclaw gateway status @@ -281,22 +281,22 @@ openclaw doctor openclaw gateway status --deep # also scan system-level services ``` -確認する項目: +確認すること: - `Runtime: stopped` と終了ヒント。 - サービス構成の不一致 (`Config (cli)` と `Config (service)`)。 - ポート/リスナーの競合。 -- `--deep` が使用されている場合の追加の launchd/systemd/schtasks インストール。 +- `--deep` を使った場合の余分な launchd/systemd/schtasks インストール。 - `Other gateway-like services detected (best effort)` のクリーンアップヒント。 - - - `Gateway start blocked: set gateway.mode=local` または `existing config is missing gateway.mode` → ローカル Gateway モードが有効になっていないか、構成ファイルが上書きされて `gateway.mode` が失われています。修正: 構成で `gateway.mode="local"` を設定するか、`openclaw onboard --mode local` / `openclaw setup` を再実行して、想定されるローカルモード構成を再スタンプします。Podman 経由で OpenClaw を実行している場合、デフォルトの構成パスは `~/.openclaw/openclaw.json` です。 - - `refusing to bind gateway ... without auth` → 有効な Gateway 認証パス (トークン/パスワード、または構成済みの場合は信頼済みプロキシ) なしで非 loopback にバインドしようとしています。 + + - `Gateway start blocked: set gateway.mode=local` または `existing config is missing gateway.mode` → local Gateway モードが有効ではない、または構成ファイルが上書きされて `gateway.mode` が失われています。修正: 構成で `gateway.mode="local"` を設定するか、`openclaw onboard --mode local` / `openclaw setup` を再実行して、想定される local モード構成を再スタンプします。Podman 経由で OpenClaw を実行している場合、デフォルトの構成パスは `~/.openclaw/openclaw.json` です。 + - `refusing to bind gateway ... without auth` → 有効な Gateway 認証経路 (トークン/パスワード、または構成済みの場合は信頼済みプロキシ) なしで非 loopback にバインドしようとしています。 - `another gateway instance is already listening` / `EADDRINUSE` → ポート競合です。 - - `Other gateway-like services detected (best effort)` → 古い、または並行する launchd/systemd/schtasks ユニットが存在します。ほとんどのセットアップでは、1 台のマシンにつき 1 つの Gateway にするべきです。複数必要な場合は、ポート + 構成/状態/ワークスペースを分離してください。[/gateway#multiple-gateways-same-host](/ja-JP/gateway#multiple-gateways-same-host) を参照してください。 - - doctor からの `System-level OpenClaw gateway service detected` → ユーザーレベルのサービスがない一方で、systemd システムユニットが存在します。doctor にユーザーサービスをインストールさせる前に重複を削除または無効化するか、システムユニットが意図したスーパーバイザーである場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。 - - `Gateway service port does not match current gateway config` → インストール済みのスーパーバイザーがまだ古い `--port` を固定しています。`openclaw doctor --fix` または `openclaw gateway install --force` を実行してから、Gateway サービスを再起動します。 + - `Other gateway-like services detected (best effort)` → 古い、または並列の launchd/systemd/schtasks ユニットが存在します。ほとんどのセットアップでは、1 台のマシンにつき 1 つの Gateway にするべきです。複数必要な場合は、ポート + 構成/状態/ワークスペースを分離してください。[/gateway#multiple-gateways-same-host](/ja-JP/gateway#multiple-gateways-same-host) を参照してください。 + - doctor の `System-level OpenClaw gateway service detected` → ユーザーレベルサービスがない一方で systemd システムユニットが存在します。doctor にユーザーサービスのインストールを許可する前に重複を削除または無効化するか、システムユニットが意図したスーパーバイザーである場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。 + - `Gateway service port does not match current gateway config` → インストール済みスーパーバイザーがまだ古い `--port` を固定しています。`openclaw doctor --fix` または `openclaw gateway install --force` を実行してから、Gateway サービスを再起動します。 @@ -307,9 +307,9 @@ openclaw gateway status --deep # also scan system-level services - [構成](/ja-JP/gateway/configuration) - [Doctor](/ja-JP/gateway/doctor) -## Gateway が最後に正常だった構成を復元した +## Gateway が最後の正常な構成を復元した -Gateway は起動するものの、ログで `openclaw.json` を復元したと表示される場合に使用します。 +Gateway は起動するが、ログに `openclaw.json` を復元したと表示される場合に使います。 ```bash openclaw logs --follow @@ -318,24 +318,24 @@ openclaw config validate openclaw doctor ``` -確認する項目: +確認すること: - `Config auto-restored from last-known-good` - `gateway: invalid config was restored from last-known-good backup` - `config reload restored last-known-good config after invalid-config` -- アクティブな構成の横にある、タイムスタンプ付きの `openclaw.json.clobbered.*` ファイル +- アクティブな構成の隣にある、タイムスタンプ付きの `openclaw.json.clobbered.*` ファイル - `Config recovery warning` で始まるメインエージェントのシステムイベント - - 拒否された構成は、起動中またはホットリロード中の検証に通りませんでした。 - - OpenClaw は拒否されたペイロードを `.clobbered.*` として保持しました。 - - アクティブな構成は、最後に検証された last-known-good コピーから復元されました。 - - 次のメインエージェントターンには、拒否された構成を無条件に書き直さないよう警告されます。 - - すべての検証問題が `plugins.entries....` の下にある場合、OpenClaw はファイル全体を復元しません。Plugin ローカルの失敗は明示されたまま、無関係なユーザー設定はアクティブな構成に残ります。 + - 拒否された構成は、起動中またはホットリロード中に検証に合格しませんでした。 + - OpenClaw は拒否されたペイロードを `.clobbered.*` として保存しました。 + - アクティブな構成は、最後に検証済みの last-known-good コピーから復元されました。 + - 次のメインエージェントターンでは、拒否された構成を盲目的に書き直さないよう警告されます。 + - すべての検証問題が `plugins.entries....` の下にあった場合、OpenClaw はファイル全体を復元しません。Plugin ローカルの失敗は明確に残り、無関係なユーザー設定はアクティブな構成に残ります。 - + ```bash CONFIG="$(openclaw config file)" ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head @@ -344,18 +344,19 @@ openclaw doctor openclaw doctor ``` - - - `.clobbered.*` が存在する → 外部からの直接編集、または起動時の読み取りが復元されました。 - - `.rejected.*` が存在する → OpenClaw 所有の構成書き込みが、コミット前にスキーマまたは clobber チェックに失敗しました。 - - `Config write rejected:` → 書き込みが必要な形状を落とそうとした、ファイルを急激に縮小しようとした、または無効な構成を永続化しようとしました。 - - `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good`、または `size-drop-vs-last-good:*` → 現在のファイルが、last-known-good バックアップと比較してフィールドまたはサイズを失っていたため、起動時に clobber されたものとして扱われました。 - - `Config last-known-good promotion skipped` → 候補に `***` などの秘匿済みシークレットプレースホルダーが含まれていました。 + + - `.clobbered.*` が存在する → 外部からの直接編集または起動時読み取りが復元されました。 + - `.rejected.*` が存在する → OpenClaw が所有する構成書き込みが、コミット前にスキーマまたは上書きチェックで失敗しました。 + - `Config write rejected:` → 書き込みが必須の形を落とす、ファイルを急激に縮小する、または無効な構成を永続化しようとしました。 + - `Rejected validation details:` → 復旧ログまたはメインエージェント通知に、復元の原因となったスキーマパスが含まれます。例: `agents.defaults.execution` または `gateway.auth.password.source`。 + - `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good`、または `size-drop-vs-last-good:*` → 現在のファイルが last-known-good バックアップと比較してフィールドまたはサイズを失っていたため、起動時に上書きされたものとして扱われました。 + - `Config last-known-good promotion skipped` → 候補に `***` などの墨消し済みシークレットプレースホルダーが含まれていました。 - 1. 復元されたアクティブ構成が正しければ、そのまま保持します。 + 1. 復元されたアクティブな構成が正しい場合は、そのまま維持します。 2. `.clobbered.*` または `.rejected.*` から意図したキーだけをコピーし、`openclaw config set` または `config.patch` で適用します。 - 3. 再起動する前に `openclaw config validate` を実行します。 + 3. 再起動前に `openclaw config validate` を実行します。 4. 手作業で編集する場合は、変更したい部分オブジェクトだけではなく、完全な JSON5 構成を保持します。 @@ -364,12 +365,12 @@ openclaw doctor - [Config](/ja-JP/cli/config) - [構成: ホットリロード](/ja-JP/gateway/configuration#config-hot-reload) -- [構成: 厳密な検証](/ja-JP/gateway/configuration#strict-validation) +- [構成: 厳格な検証](/ja-JP/gateway/configuration#strict-validation) - [Doctor](/ja-JP/gateway/doctor) -## Gateway プローブ警告 +## Gateway probe の警告 -`openclaw gateway probe` が何かに到達するものの、警告ブロックも出力する場合に使用します。 +`openclaw gateway probe` が何かに到達するものの、警告ブロックも表示する場合に使います。 ```bash openclaw gateway probe @@ -377,19 +378,19 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -確認する項目: +確認すること: -- JSON 出力内の `warnings[].code` と `primaryTargetId`。 -- 警告が SSH フォールバック、複数 Gateway、スコープ不足、または未解決の認証参照に関するものかどうか。 +- JSON 出力の `warnings[].code` と `primaryTargetId`。 +- 警告が SSH フォールバック、複数の Gateway、不足スコープ、未解決の認証参照のいずれに関するものか。 -一般的なシグネチャ: +一般的な兆候: -- `SSH tunnel failed to start; falling back to direct probes.` → SSH セットアップに失敗しましたが、コマンドは構成済み/loopback ターゲットへの直接プローブを試行しました。 -- `multiple reachable gateways detected` → 複数のターゲットが応答しました。通常、これは意図的な複数 Gateway セットアップ、または古い/重複したリスナーを意味します。 -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 接続は成功しましたが、詳細 RPC はスコープで制限されています。デバイス ID をペアリングするか、`operator.read` を持つ認証情報を使用してください。 -- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 接続は成功しましたが、完全な診断 RPC セットがタイムアウトまたは失敗しました。これは診断機能が低下した到達可能な Gateway として扱い、`--json` 出力の `connect.ok` と `connect.rpcOk` を比較してください。 -- `Capability: pairing-pending` または `gateway closed (1008): pairing required` → Gateway は応答しましたが、このクライアントは通常のオペレーターアクセスの前に、まだペアリング/承認が必要です。 -- 未解決の `gateway.auth.*` / `gateway.remote.*` SecretRef 警告テキスト → 失敗したターゲットについて、このコマンドパスで認証素材を利用できませんでした。 +- `SSH tunnel failed to start; falling back to direct probes.` → SSH セットアップに失敗しましたが、コマンドは引き続き構成済み/loopback の直接ターゲットを試しました。 +- `multiple reachable gateways detected` → 複数のターゲットが応答しました。通常これは、意図的なマルチ Gateway セットアップ、または古い/重複したリスナーを意味します。 +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 接続は成功しましたが、詳細 RPC はスコープによって制限されています。デバイス ID をペアリングするか、`operator.read` を持つ認証情報を使ってください。 +- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 接続は成功しましたが、完全な診断 RPC セットがタイムアウトまたは失敗しました。これは診断が劣化した到達可能な Gateway として扱い、`--json` 出力の `connect.ok` と `connect.rpcOk` を比較します。 +- `Capability: pairing-pending` または `gateway closed (1008): pairing required` → Gateway は応答しましたが、このクライアントは通常の operator アクセスの前にまだペアリング/承認が必要です。 +- 未解決の `gateway.auth.*` / `gateway.remote.*` SecretRef 警告テキスト → 失敗したターゲットに対して、このコマンド経路では認証素材を利用できませんでした。 関連: @@ -399,7 +400,7 @@ openclaw gateway probe --ssh user@gateway-host ## チャネルは接続済みだが、メッセージが流れない -チャネル状態が接続済みでもメッセージフローが停止している場合は、ポリシー、権限、チャネル固有の配信ルールに注目します。 +チャネル状態が接続済みだがメッセージフローが停止している場合は、ポリシー、権限、チャネル固有の配信ルールに注目します。 ```bash openclaw channels status --probe @@ -409,28 +410,28 @@ openclaw logs --follow openclaw config get channels ``` -確認する項目: +確認すること: -- DM ポリシー (`pairing`、`allowlist`、`open`、`disabled`)。 -- グループ許可リストとメンション要件。 -- 不足しているチャネル API 権限/スコープ。 +- DM ポリシー（`pairing`、`allowlist`、`open`、`disabled`）。 +- グループの許可リストとメンション要件。 +- チャネル API 権限/スコープの不足。 -一般的なシグネチャ: +一般的な兆候: -- `mention required` → グループメンションポリシーによりメッセージは無視されます。 +- `mention required` → グループのメンションポリシーによりメッセージが無視されました。 - `pairing` / 承認待ちのトレース → 送信者が承認されていません。 -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → チャンネルの認証/権限の問題です。 +- `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → チャネル認証/権限の問題です。 関連: -- [チャンネルのトラブルシューティング](/ja-JP/channels/troubleshooting) +- [チャネルのトラブルシューティング](/ja-JP/channels/troubleshooting) - [Discord](/ja-JP/channels/discord) - [Telegram](/ja-JP/channels/telegram) - [WhatsApp](/ja-JP/channels/whatsapp) ## Cron と Heartbeat の配信 -Cron または Heartbeat が実行されなかった、または配信されなかった場合は、まずスケジューラの状態を確認し、その後で配信先を確認します。 +Cron または Heartbeat が実行されなかった、または配信されなかった場合は、まずスケジューラーの状態を確認し、その後に配信先を確認します。 ```bash openclaw cron status @@ -440,21 +441,21 @@ openclaw system heartbeat last openclaw logs --follow ``` -確認する内容: +確認すること: -- Cron が有効で、次回の起床時刻が存在すること。 -- ジョブ実行履歴のステータス (`ok`, `skipped`, `error`)。 -- Heartbeat のスキップ理由 (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`)。 +- Cron が有効で、次回の起動が存在する。 +- ジョブ実行履歴の状態（`ok`、`skipped`、`error`）。 +- Heartbeat のスキップ理由（`quiet-hours`、`requests-in-flight`、`cron-in-progress`、`lanes-busy`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 - - - `cron: scheduler disabled; jobs will not run automatically` → cron が無効です。 - - `cron: timer tick failed` → スケジューラの tick に失敗しました。ファイル/ログ/ランタイムエラーを確認してください。 - - `heartbeat skipped` で `reason=quiet-hours` → アクティブ時間帯の範囲外です。 - - `heartbeat skipped` で `reason=empty-heartbeat-file` → `HEARTBEAT.md` は存在しますが、空行または Markdown 見出ししか含まれていないため、OpenClaw はモデル呼び出しをスキップします。 - - `heartbeat skipped` で `reason=no-tasks-due` → `HEARTBEAT.md` に `tasks:` ブロックがありますが、この tick で期限に達したタスクがありません。 + + - `cron: scheduler disabled; jobs will not run automatically` → Cron が無効です。 + - `cron: timer tick failed` → スケジューラーの tick に失敗しました。ファイル/ログ/ランタイムエラーを確認してください。 + - `heartbeat skipped` と `reason=quiet-hours` → アクティブ時間帯の範囲外です。 + - `heartbeat skipped` と `reason=empty-heartbeat-file` → `HEARTBEAT.md` は存在しますが、空行または Markdown 見出ししか含まれていないため、OpenClaw はモデル呼び出しをスキップします。 + - `heartbeat skipped` と `reason=no-tasks-due` → `HEARTBEAT.md` に `tasks:` ブロックが含まれていますが、この tick で期限を迎えるタスクがありません。 - `heartbeat: unknown accountId` → Heartbeat 配信先のアカウント ID が無効です。 - - `heartbeat skipped` で `reason=dm-blocked` → `agents.defaults.heartbeat.directPolicy` (またはエージェントごとの上書き) が `block` に設定されている間に、Heartbeat の送信先が DM 形式の送信先として解決されました。 + - `heartbeat skipped` と `reason=dm-blocked` → `agents.defaults.heartbeat.directPolicy`（またはエージェントごとの上書き）が `block` に設定されている間に、Heartbeat の対象が DM 形式の宛先に解決されました。 @@ -465,9 +466,9 @@ openclaw logs --follow - [スケジュール済みタスク](/ja-JP/automation/cron-jobs) - [スケジュール済みタスク: トラブルシューティング](/ja-JP/automation/cron-jobs#troubleshooting) -## Node はペアリング済みだが、ツールが失敗する +## Node はペアリング済みだがツールが失敗する -Node がペアリング済みでもツールが失敗する場合は、フォアグラウンド、権限、承認状態を切り分けます。 +Node がペアリング済みでもツールが失敗する場合は、フォアグラウンド、権限、承認の状態を切り分けます。 ```bash openclaw nodes status @@ -477,22 +478,22 @@ openclaw logs --follow openclaw status ``` -確認する内容: +確認すること: -- Node がオンラインで、期待される機能を持っていること。 -- カメラ/マイク/位置情報/画面に対する OS 権限の付与。 -- 実行承認と allowlist の状態。 +- Node がオンラインで、期待される機能を備えている。 +- カメラ/マイク/位置情報/画面の OS 権限付与。 +- exec 承認と許可リストの状態。 -一般的なシグネチャ: +一般的な兆候: -- `NODE_BACKGROUND_UNAVAILABLE` → node アプリをフォアグラウンドにする必要があります。 +- `NODE_BACKGROUND_UNAVAILABLE` → Node アプリをフォアグラウンドにする必要があります。 - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → OS 権限が不足しています。 -- `SYSTEM_RUN_DENIED: approval required` → 実行承認が保留中です。 -- `SYSTEM_RUN_DENIED: allowlist miss` → コマンドが allowlist によってブロックされています。 +- `SYSTEM_RUN_DENIED: approval required` → exec 承認が保留中です。 +- `SYSTEM_RUN_DENIED: allowlist miss` → コマンドが許可リストによりブロックされました。 関連: -- [実行承認](/ja-JP/tools/exec-approvals) +- [Exec 承認](/ja-JP/tools/exec-approvals) - [Node のトラブルシューティング](/ja-JP/nodes/troubleshooting) - [Node](/ja-JP/nodes/index) @@ -508,56 +509,56 @@ openclaw logs --follow openclaw doctor ``` -確認する内容: +確認すること: -- `plugins.allow` が設定されており、`browser` を含んでいるか。 -- 有効なブラウザ実行ファイルのパス。 -- CDP プロファイルに到達できるか。 -- `existing-session` / `user` プロファイル用のローカル Chrome が利用可能か。 +- `plugins.allow` が設定され、`browser` を含んでいるか。 +- 有効なブラウザ実行ファイルパス。 +- CDP プロファイルへの到達性。 +- `existing-session` / `user` プロファイル向けのローカル Chrome の可用性。 - - - `unknown command "browser"` または `unknown command 'browser'` → バンドルされたブラウザ Plugin が `plugins.allow` によって除外されています。 - - `browser.enabled=true` なのにブラウザツールが見つからない/利用できない → `plugins.allow` が `browser` を除外しているため、Plugin が読み込まれていません。 + + - `unknown command "browser"` または `unknown command 'browser'` → 同梱のブラウザ Plugin が `plugins.allow` により除外されています。 + - `browser.enabled=true` の間にブラウザツールが欠落/利用不可 → `plugins.allow` が `browser` を除外しているため、Plugin が読み込まれていません。 - `Failed to start Chrome CDP on port` → ブラウザプロセスの起動に失敗しました。 - `browser.executablePath not found` → 設定されたパスが無効です。 - - `browser.cdpUrl must be http(s) or ws(s)` → 設定された CDP URL が `file:` や `ftp:` などのサポートされないスキームを使用しています。 - - `browser.cdpUrl has invalid port` → 設定された CDP URL のポートが不正、または範囲外です。 - - `Playwright is not available in this gateway build; '' is unsupported.` → 現在の gateway インストールには、バンドルされたブラウザ Plugin の `playwright-core` ランタイム依存関係がありません。`openclaw doctor --fix` を実行し、その後 Gateway を再起動してください。ARIA スナップショットと基本的なページスクリーンショットは引き続き動作しますが、ナビゲーション、AI スナップショット、CSS セレクタ要素スクリーンショット、PDF エクスポートは利用できないままです。 + - `browser.cdpUrl must be http(s) or ws(s)` → 設定された CDP URL が `file:` や `ftp:` などの未対応スキームを使用しています。 + - `browser.cdpUrl has invalid port` → 設定された CDP URL のポートが不正または範囲外です。 + - `Playwright is not available in this gateway build; '' is unsupported.` → 現在の Gateway インストールには、同梱ブラウザ Plugin の `playwright-core` ランタイム依存関係がありません。`openclaw doctor --fix` を実行してから Gateway を再起動してください。ARIA スナップショットと基本的なページスクリーンショットは引き続き動作する場合がありますが、ナビゲーション、AI スナップショット、CSS セレクター要素スクリーンショット、PDF エクスポートは利用できません。 - - - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session は、選択されたブラウザデータディレクトリにまだ接続できませんでした。ブラウザの inspect ページを開き、リモートデバッグを有効にし、ブラウザを開いたままにして、最初の接続プロンプトを承認してから再試行してください。サインイン状態が不要な場合は、管理対象の `openclaw` プロファイルを優先してください。 - - `No Chrome tabs found for profile="user"` → Chrome MCP 接続プロファイルに、開いているローカル Chrome タブがありません。 + + - `Could not find DevToolsActivePort for chrome` → Chrome MCP の existing-session が、選択されたブラウザデータディレクトリにまだアタッチできませんでした。ブラウザの inspect ページを開き、リモートデバッグを有効にし、ブラウザを開いたままにして、最初のアタッチプロンプトを承認してから再試行してください。サインイン状態が不要な場合は、管理対象の `openclaw` プロファイルを優先してください。 + - `No Chrome tabs found for profile="user"` → Chrome MCP のアタッチプロファイルに、開いているローカル Chrome タブがありません。 - `Remote CDP for profile "" is not reachable` → 設定されたリモート CDP エンドポイントに Gateway ホストから到達できません。 - - `Browser attachOnly is enabled ... not reachable` または `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only プロファイルに到達可能なターゲットがない、または HTTP エンドポイントは応答したものの CDP WebSocket を開けませんでした。 + - `Browser attachOnly is enabled ... not reachable` または `Browser attachOnly is enabled and CDP websocket ... is not reachable` → アタッチ専用プロファイルに到達可能なターゲットがないか、HTTP エンドポイントは応答したものの CDP WebSocket を開けませんでした。 - - - `fullPage is not supported for element screenshots` → スクリーンショットリクエストで `--full-page` と `--ref` または `--element` が混在しています。 - - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` のスクリーンショット呼び出しでは、CSS の `--element` ではなく、ページキャプチャまたはスナップショットの `--ref` を使用する必要があります。 - - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP のアップロードフックには、CSS セレクタではなくスナップショット ref が必要です。 - - `existing-session file uploads currently support one file at a time.` → Chrome MCP プロファイルでは、1 回の呼び出しにつき 1 ファイルを送信してください。 - - `existing-session dialog handling does not support timeoutMs.` → Chrome MCP プロファイルのダイアログフックはタイムアウトの上書きをサポートしていません。 - - `existing-session type does not support timeoutMs overrides.` → `profile="user"` / Chrome MCP existing-session プロファイルで `act:type` を使う場合は `timeoutMs` を省略してください。カスタムタイムアウトが必要な場合は、管理対象/CDP ブラウザプロファイルを使用してください。 - - `existing-session evaluate does not support timeoutMs overrides.` → `profile="user"` / Chrome MCP existing-session プロファイルで `act:evaluate` を使う場合は `timeoutMs` を省略してください。カスタムタイムアウトが必要な場合は、管理対象/CDP ブラウザプロファイルを使用してください。 - - `response body is not supported for existing-session profiles yet.` → `responsebody` には、まだ管理対象ブラウザまたは raw CDP プロファイルが必要です。 - - attach-only またはリモート CDP プロファイルでの古い viewport / dark-mode / locale / offline 上書き → Gateway 全体を再起動せずにアクティブな制御セッションを閉じ、Playwright/CDP エミュレーション状態を解放するには、`openclaw browser stop --browser-profile ` を実行します。 + + - `fullPage is not supported for element screenshots` → スクリーンショット要求で `--full-page` と `--ref` または `--element` が混在しています。 + - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` のスクリーンショット呼び出しでは、CSS `--element` ではなく、ページキャプチャまたはスナップショットの `--ref` を使用する必要があります。 + - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP のアップロードフックには、CSS セレクターではなくスナップショット ref が必要です。 + - `existing-session file uploads currently support one file at a time.` → Chrome MCP プロファイルでは、1 回の呼び出しにつき 1 ファイルをアップロードしてください。 + - `existing-session dialog handling does not support timeoutMs.` → Chrome MCP プロファイル上のダイアログフックはタイムアウトの上書きをサポートしていません。 + - `existing-session type does not support timeoutMs overrides.` → `profile="user"` / Chrome MCP existing-session プロファイルの `act:type` では `timeoutMs` を省略するか、カスタムタイムアウトが必要な場合は管理対象/CDP ブラウザプロファイルを使用してください。 + - `existing-session evaluate does not support timeoutMs overrides.` → `profile="user"` / Chrome MCP existing-session プロファイルの `act:evaluate` では `timeoutMs` を省略するか、カスタムタイムアウトが必要な場合は管理対象/CDP ブラウザプロファイルを使用してください。 + - `response body is not supported for existing-session profiles yet.` → `responsebody` にはまだ管理対象ブラウザまたは raw CDP プロファイルが必要です。 + - アタッチ専用またはリモート CDP プロファイルで viewport / dark-mode / locale / offline の上書きが古い → Gateway 全体を再起動せずに、`openclaw browser stop --browser-profile ` を実行してアクティブな制御セッションを閉じ、Playwright/CDP エミュレーション状態を解放してください。 関連: -- [ブラウザ (OpenClaw 管理)](/ja-JP/tools/browser) +- [ブラウザ（OpenClaw 管理）](/ja-JP/tools/browser) - [ブラウザのトラブルシューティング](/ja-JP/tools/browser-linux-troubleshooting) -## アップグレード後に突然何かが壊れた場合 +## アップグレード後に何かが突然壊れた場合 -アップグレード後の破損の多くは、設定のドリフト、またはより厳格なデフォルトが現在適用されていることが原因です。 +アップグレード後の破損の多くは、設定のドリフト、または現在はより厳格なデフォルトが適用されていることが原因です。 - + ```bash openclaw gateway status openclaw config get gateway.mode @@ -565,18 +566,18 @@ openclaw doctor openclaw config get gateway.auth.mode ``` - 確認する内容: + 確認すること: - - `gateway.mode=remote` の場合、ローカルサービスに問題がなくても CLI 呼び出しがリモートを対象にしている可能性があります。 - - 明示的な `--url` 呼び出しは、保存済み資格情報にフォールバックしません。 + - `gateway.mode=remote` の場合、ローカルサービスは正常でも CLI 呼び出しがリモートを対象にしている可能性があります。 + - 明示的な `--url` 呼び出しは、保存済みの認証情報にフォールバックしません。 - 一般的なシグネチャ: + 一般的な兆候: - `gateway connect failed:` → URL ターゲットが誤っています。 - `unauthorized` → エンドポイントには到達できますが、認証が誤っています。 - + ```bash openclaw config get gateway.bind openclaw config get gateway.auth.mode @@ -585,18 +586,18 @@ openclaw doctor openclaw logs --follow ``` - 確認する内容: + 確認すること: - - 非ループバックバインド (`lan`, `tailnet`, `custom`) には、有効な Gateway 認証パスが必要です。共有トークン/パスワード認証、または正しく設定された非ループバックの `trusted-proxy` デプロイです。 - - `gateway.token` のような古いキーは `gateway.auth.token` の代わりにはなりません。 + - 非ループバックバインド（`lan`、`tailnet`、`custom`）には、有効な Gateway 認証パスが必要です。共有トークン/パスワード認証、または正しく設定された非ループバックの `trusted-proxy` デプロイです。 + - `gateway.token` のような古いキーは `gateway.auth.token` を置き換えません。 - 一般的なシグネチャ: + 一般的な兆候: - `refusing to bind gateway ... without auth` → 有効な Gateway 認証パスなしの非ループバックバインドです。 - - ランタイムは実行中なのに `Connectivity probe: failed` → Gateway は生きていますが、現在の認証/URL ではアクセスできません。 + - ランタイムが実行中なのに `Connectivity probe: failed` → Gateway は稼働していますが、現在の認証/URL ではアクセスできません。 - + ```bash openclaw devices list openclaw pairing list --channel [--account ] @@ -604,12 +605,12 @@ openclaw doctor openclaw doctor ``` - 確認する内容: + 確認すること: - - ダッシュボード/Node の保留中のデバイス承認。 - - ポリシーまたは ID 変更後の保留中の DM ペアリング承認。 + - ダッシュボード/Node の保留中デバイス承認。 + - ポリシーまたは ID 変更後の保留中 DM ペアリング承認。 - 一般的なシグネチャ: + 一般的な兆候: - `device identity required` → デバイス認証が満たされていません。 - `pairing required` → 送信者/デバイスを承認する必要があります。 @@ -617,7 +618,7 @@ openclaw doctor -確認後もサービス設定とランタイムがまだ一致しない場合は、同じプロファイル/状態ディレクトリからサービスメタデータを再インストールしてください。 +確認後もサービス設定とランタイムが一致しない場合は、同じプロファイル/状態ディレクトリからサービスメタデータを再インストールします。 ```bash openclaw gateway install --force @@ -627,8 +628,8 @@ openclaw gateway restart 関連: - [認証](/ja-JP/gateway/authentication) -- [バックグラウンド実行とプロセスツール](/ja-JP/gateway/background-process) -- [Gateway 所有のペアリング](/ja-JP/gateway/pairing) +- [バックグラウンド exec とプロセスツール](/ja-JP/gateway/background-process) +- [Gateway 管理のペアリング](/ja-JP/gateway/pairing) ## 関連 diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index 00227d52b..eaa7e5218 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -2,191 +2,199 @@ read_when: - ローカルまたはCIでテストを実行する - モデル/プロバイダーのバグに対する回帰テストの追加 - - Gateway + エージェント動作のデバッグ -summary: 'テストキット: ユニット/e2e/live スイート、Docker ランナー、および各テストの対象範囲' + - Gateway とエージェントの挙動のデバッグ +summary: 'テストキット: ユニット/e2e/live スイート、Docker ランナー、および各テストが対象とする内容' title: テスト x-i18n: - generated_at: "2026-04-30T18:38:43Z" + generated_at: "2026-05-01T05:01:50Z" model: gpt-5.5 provider: openai - source_hash: 470a96c6b47c2708950d05adc4a4efba5fe290f0675a131e2888d2d0032d5953 + source_hash: 3c28e45c483169f528483f7a27265d89c34f3865eb56b51407639b566e117162 source_path: help/testing.md workflow: 16 --- -OpenClaw には 3 つの Vitest スイート (ユニット/統合、e2e、ライブ) と少数の Docker ランナーがあります。このドキュメントは「テスト方法」のガイドです。 +OpenClaw には 3 つの Vitest スイート（unit/integration、e2e、live）と少数の Docker ランナーがあります。このドキュメントは「テスト方法」のガイドです。 -- 各スイートが対象にするもの (および意図的に対象にし_ない_もの)。 -- 一般的なワークフロー (ローカル、プッシュ前、デバッグ) で実行するコマンド。 -- ライブテストが認証情報を検出し、モデル/プロバイダーを選択する方法。 -- 実際のモデル/プロバイダー問題に対するリグレッションを追加する方法。 +- 各スイートがカバーする内容（および意図的にカバーしない内容）。 +- 一般的なワークフロー（local、pre-push、debugging）で実行するコマンド。 +- live テストが認証情報を検出し、モデル/プロバイダーを選択する方法。 +- 実際のモデル/プロバイダー問題のリグレッションを追加する方法。 -**QA スタック (qa-lab、qa-channel、ライブトランスポートレーン)** は別途文書化されています。 +**QA スタック（qa-lab、qa-channel、live transport lanes）**は別途ドキュメント化されています。 - [QA 概要](/ja-JP/concepts/qa-e2e-automation) — アーキテクチャ、コマンド面、シナリオ作成。 - [Matrix QA](/ja-JP/concepts/qa-matrix) — `pnpm openclaw qa matrix` のリファレンス。 -- [QA チャネル](/ja-JP/channels/qa-channel) — リポジトリに裏付けられたシナリオで使う合成トランスポート Plugin。 +- [QA channel](/ja-JP/channels/qa-channel) — リポジトリ裏付けのシナリオで使われる合成トランスポート Plugin。 -このページでは、通常のテストスイートと Docker/Parallels ランナーの実行を扱います。下の QA 固有のランナーセクション ([QA 固有のランナー](#qa-specific-runners)) には具体的な `qa` 呼び出しを列挙し、上記のリファレンスを参照しています。 +このページでは、通常のテストスイートと Docker/Parallels ランナーの実行を扱います。下の QA 固有のランナーセクション（[QA 固有のランナー](#qa-specific-runners)）には具体的な `qa` 呼び出しを列挙し、上記のリファレンスへ戻るリンクを示しています。 ## クイックスタート -ほとんどの日: +普段は: -- フルゲート (プッシュ前に想定): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- 余裕のあるマシンでの高速なローカルフルスイート実行: `pnpm test:max` -- 直接の Vitest ウォッチループ: `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` +- フルゲート（push 前に期待される）: `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- 余裕のあるマシンでの高速な local フルスイート実行: `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` -テストを変更した場合、または追加の確信が必要な場合: +テストに触れたときや追加の確信が欲しいとき: - カバレッジゲート: `pnpm test:coverage` - E2E スイート: `pnpm test:e2e` -実際のプロバイダー/モデルをデバッグする場合 (実際の認証情報が必要): +実際のプロバイダー/モデルをデバッグするとき（実際の認証情報が必要）: -- ライブスイート (モデル + Gateway ツール/画像プローブ): `pnpm test:live` -- 1 つのライブファイルだけを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker ライブモデルスイープ: `pnpm test:docker:live-models` - - 選択された各モデルは、テキストターンに加えて小さなファイル読み取り風プローブを実行します。 - メタデータが `image` 入力を通知しているモデルでは、小さな画像ターンも実行します。 - プロバイダー失敗を切り分ける場合は、`OPENCLAW_LIVE_MODEL_FILE_PROBE=0` または +- Live スイート（モデル + gateway tool/image プローブ）: `pnpm test:live` +- 1 つの live ファイルを静かに対象化: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker live モデルスイープ: `pnpm test:docker:live-models` + - 選択された各モデルは、テキストターンに加えて小さな file-read 風プローブを実行します。 + メタデータが `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` で再利用可能なライブ/E2E ワークフローを呼び出し、 - プロバイダーごとにシャードされた個別の Docker ライブモデルマトリックスジョブを含みます。 + - CI カバレッジ: 日次の `OpenClaw Scheduled Live And E2E Checks` と手動の + `OpenClaw Release Checks` はどちらも、再利用可能な live/E2E ワークフローを + `include_live_suites: true` で呼び出します。これには、プロバイダー別にシャードされた + 個別の Docker live モデルマトリクスジョブが含まれます。 - 集中的な CI 再実行では、`include_live_suites: true` と `live_models_only: true` を指定して - `OpenClaw Live And E2E Checks (Reusable)` をディスパッチしてください。 + `OpenClaw Live And E2E Checks (Reusable)` を dispatch します。 - 新しい高シグナルのプロバイダーシークレットは `scripts/ci-hydrate-live-auth.sh` に加え、 `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` とその - スケジュール/リリース呼び出し元にも追加してください。 -- ネイティブ Codex バインドチャットスモーク: `pnpm test:docker:live-codex-bind` - - Codex アプリサーバーパスに対して Docker ライブレーンを実行し、`/codex bind` で合成 Slack DM をバインドし、 - `/codex fast` と `/codex permissions` を実行したうえで、通常の返信と画像添付が - ACP ではなくネイティブ Plugin バインディングを通ってルーティングされることを検証します。 -- Codex アプリサーバーハーネススモーク: `pnpm test:docker:live-codex-harness` - - Plugin 所有の Codex アプリサーバーハーネスを通じて Gateway エージェントターンを実行し、 - `/codex status` と `/codex models` を検証します。デフォルトでは画像、cron MCP、サブエージェント、Guardian プローブも実行します。他の Codex - アプリサーバー失敗を切り分ける場合は、`OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` でサブエージェントプローブを無効にしてください。サブエージェントに絞ったチェックでは、他のプローブを無効にしてください: + scheduled/release 呼び出し元にも追加してください。 +- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` + - Codex app-server パスに対して Docker live レーンを実行し、合成 + Slack DM を `/codex bind` でバインドし、`/codex fast` と + `/codex permissions` を実行した後、通常の返信と画像添付が + ACP ではなくネイティブ Plugin バインディング経由でルーティングされることを検証します。 +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` + - Plugin 所有の Codex app-server ハーネス経由で gateway agent ターンを実行し、 + `/codex status` と `/codex models` を検証し、デフォルトでは画像、 + cron MCP、sub-agent、Guardian プローブを実行します。他の Codex + app-server 障害を切り分けるときは、 + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` で sub-agent プローブを無効にしてください。 + 集中的な sub-agent チェックでは、他のプローブを無効にします: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`。 - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` が設定されていない限り、これはサブエージェントプローブ後に終了します。 -- Crestodian レスキューコマンドスモーク: `pnpm test:live:crestodian-rescue-channel` - - メッセージチャネルのレスキューコマンド面に対する任意参加の念押しチェックです。 + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` が設定されていない限り、 + sub-agent プローブ後に終了します。 +- Crestodian rescue command smoke: `pnpm test:live:crestodian-rescue-channel` + - メッセージチャネルの rescue command 面に対するオプトインの念押しチェックです。 `/crestodian status` を実行し、永続的なモデル変更をキューに入れ、 - `/crestodian yes` に返信し、監査/設定書き込みパスを検証します。 -- Crestodian プランナー Docker スモーク: `pnpm test:docker:crestodian-planner` - - `PATH` 上に偽の Claude CLI を置いた設定なしのコンテナで Crestodian を実行し、 - ファジープランナーのフォールバックが、監査済みの型付き設定書き込みに変換されることを検証します。 -- Crestodian 初回実行 Docker スモーク: `pnpm test:docker:crestodian-first-run` - - 空の OpenClaw 状態ディレクトリから開始し、素の `openclaw` を - Crestodian にルーティングし、セットアップ/モデル/エージェント/Discord Plugin + SecretRef 書き込みを適用し、 - 設定を検証し、監査エントリを検証します。同じ Ring 0 セットアップパスは + `/crestodian yes` に返信し、audit/config 書き込みパスを検証します。 +- Crestodian planner Docker smoke: `pnpm test:docker:crestodian-planner` + - `PATH` 上に偽の Claude CLI を置いた設定なしコンテナで Crestodian を実行し、 + fuzzy planner fallback が audit 済みの typed config 書き込みに変換されることを検証します。 +- Crestodian first-run Docker smoke: `pnpm test:docker:crestodian-first-run` + - 空の OpenClaw state dir から開始し、裸の `openclaw` を + Crestodian にルーティングし、setup/model/agent/Discord Plugin + SecretRef 書き込みを適用し、 + config を検証し、audit entries を検証します。同じ Ring 0 setup パスは QA Lab でも `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` によってカバーされています。 -- Moonshot/Kimi コストスモーク: `MOONSHOT_API_KEY` を設定した状態で - `openclaw models list --provider moonshot --json` を実行し、次に分離された +- Moonshot/Kimi cost smoke: `MOONSHOT_API_KEY` を設定して、 + `openclaw models list --provider moonshot --json` を実行し、その後、分離された `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` を `moonshot/kimi-k2.6` に対して実行します。JSON が Moonshot/K2.6 を報告し、 - アシスタントのトランスクリプトに正規化された `usage.cost` が保存されることを検証します。 + assistant transcript が正規化された `usage.cost` を保存することを検証します。 -失敗ケースが 1 つだけ必要な場合は、下記の allowlist 環境変数でライブテストを絞り込むことを優先してください。 +失敗ケースが 1 つだけ必要な場合は、下記の allowlist env vars で live テストを絞り込むことを優先してください。 ## QA 固有のランナー -QA-lab のリアリティが必要な場合、これらのコマンドはメインのテストスイートの横に位置します。 +QA-lab の実環境らしさが必要なとき、これらのコマンドはメインのテストスイートの横にあります。 -CI は専用ワークフローで QA Lab を実行します。`Parity gate` は該当する PR と、 -モックプロバイダーを使った手動ディスパッチで実行されます。`QA-Lab - All Lanes` は -`main` 上で毎晩実行され、手動ディスパッチではモックパリティゲート、ライブ Matrix レーン、 -Convex 管理のライブ Telegram レーン、Convex 管理のライブ Discord レーンを -並列ジョブとして実行します。スケジュールされた QA とリリースチェックは Matrix に `--profile fast` を -明示的に渡しますが、Matrix CLI と手動ワークフロー入力のデフォルトは引き続き -`all` です。手動ディスパッチでは `all` を `transport`、`media`、`e2ee-smoke`、 -`e2ee-deep`、`e2ee-cli` ジョブにシャードできます。`OpenClaw Release Checks` はリリース承認前に -パリティと高速 Matrix および Telegram レーンを実行し、リリーストランスポートチェックには -`mock-openai/gpt-5.5` を使用するため、決定論的なままで通常のプロバイダー Plugin 起動を回避します。 -これらのライブトランスポート Gateway ではメモリ検索を無効にしています。メモリ動作は QA パリティスイートで引き続きカバーされます。 +CI は専用ワークフローで QA Lab を実行します。`Parity gate` は一致する PR と、 +mock providers を使った手動 dispatch から実行されます。`QA-Lab - All Lanes` は +`main` で毎晩実行され、手動 dispatch からは mock parity gate、live Matrix lane、 +Convex 管理の live Telegram lane、Convex 管理の live Discord lane を並列ジョブとして実行します。 +Scheduled QA と release checks は Matrix `--profile fast` を明示的に渡しますが、 +Matrix CLI と手動ワークフロー入力のデフォルトは `all` のままです。手動 dispatch では +`all` を `transport`、`media`、`e2ee-smoke`、`e2ee-deep`、`e2ee-cli` ジョブにシャードできます。 +`OpenClaw Release Checks` は release approval 前に parity と fast Matrix および Telegram lane を実行し、 +release transport checks では `mock-openai/gpt-5.5` を使うため、決定的なままで、 +通常の provider-plugin startup を避けられます。これらの live transport gateways は +memory search を無効にします。memory 動作は QA parity suites で引き続きカバーされます。 -フルリリースのライブメディアシャードは -`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` を使用します。これにはすでに -`ffmpeg` と `ffprobe` が含まれています。Docker ライブモデル/バックエンドシャードは、選択された -コミットごとに一度だけビルドされる共有 -`ghcr.io/openclaw/openclaw-live-test:` イメージを使用し、各シャード内で再ビルドする代わりに -`OPENCLAW_SKIP_DOCKER_BUILD=1` でそれを pull します。 +Full release live media shards は +`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` を使います。これにはすでに +`ffmpeg` と `ffprobe` が含まれています。Docker live model/backend shards は、選択された +commit ごとに一度だけビルドされる共有の +`ghcr.io/openclaw/openclaw-live-test:` イメージを使い、各 shard 内で再ビルドする代わりに +`OPENCLAW_SKIP_DOCKER_BUILD=1` で pull します。 - `pnpm openclaw qa suite` - - リポジトリに裏付けられた QA シナリオをホスト上で直接実行します。 - - 選択された複数のシナリオを、分離された Gateway ワーカーでデフォルト並列実行します。 - `qa-channel` のデフォルト同時実行数は 4 です (選択されたシナリオ数が上限)。 - ワーカー数を調整するには `--concurrency ` を使用し、以前のシリアルレーンには - `--concurrency 1` を使用してください。 - - いずれかのシナリオが失敗するとゼロ以外で終了します。失敗終了コードなしで - アーティファクトが必要な場合は `--allow-failures` を使用してください。 - - プロバイダーモード `live-frontier`、`mock-openai`、`aimock` をサポートします。 - `aimock` は、シナリオを認識する `mock-openai` レーンを置き換えずに、 - 実験的なフィクスチャとプロトコルモックのカバレッジのためにローカル AIMock ベースのプロバイダーサーバーを起動します。 + - リポジトリ裏付けの QA シナリオをホスト上で直接実行します。 + - 選択された複数のシナリオを、分離された gateway worker によりデフォルトで並列実行します。 + `qa-channel` のデフォルト concurrency は 4（選択されたシナリオ数で上限）です。 + worker 数を調整するには `--concurrency ` を使い、従来の serial lane には + `--concurrency 1` を使います。 + - いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしで artifacts が欲しい場合は + `--allow-failures` を使います。 + - provider modes `live-frontier`、`mock-openai`、`aimock` をサポートします。 + `aimock` は、scenario-aware な `mock-openai` lane を置き換えずに、実験的な + fixture と protocol-mock カバレッジのための local AIMock-backed provider server を起動します。 - `pnpm test:gateway:cpu-scenarios` - - Gateway 起動ベンチに加えて、小さなモック QA Lab シナリオパック - (`channel-chat-baseline`、`memory-failure-fallback`、 - `gateway-restart-inflight-run`) を実行し、結合された CPU 観測サマリーを - `.artifacts/gateway-cpu-scenarios/` に書き込みます。 - - デフォルトでは持続的な高 CPU 観測のみをフラグします (`--cpu-core-warn` - と `--hot-wall-warn-ms`)。そのため、短い起動バーストは、数分続く Gateway 高負荷リグレッションのようには見えず、 - メトリクスとして記録されます。 - - ビルド済みの `dist` アーティファクトを使用します。チェックアウトに新しいランタイム出力がまだない場合は、 - 先にビルドを実行してください。 + - gateway startup bench と小さな mock QA Lab scenario pack + （`channel-chat-baseline`、`memory-failure-fallback`、 + `gateway-restart-inflight-run`）を実行し、統合された CPU observation + summary を `.artifacts/gateway-cpu-scenarios/` 配下に書き込みます。 + - デフォルトでは継続的な hot CPU observations のみをフラグします（`--cpu-core-warn` + と `--hot-wall-warn-ms`）。そのため、短い startup bursts は、数分にわたる + gateway peg regression のように見せずにメトリクスとして記録されます。 + - ビルド済みの `dist` artifacts を使います。checkout に新しい runtime output がまだない場合は、 + 先に build を実行してください。 - `pnpm openclaw qa suite --runner multipass` - - 使い捨ての Multipass Linux VM 内で同じ QA スイートを実行します。 - - ホスト上の `qa suite` と同じシナリオ選択動作を保ちます。 - - `qa suite` と同じプロバイダー/モデル選択フラグを再利用します。 - - ライブ実行では、ゲストで実用的な対応済み QA 認証入力を転送します: - 環境変数ベースのプロバイダーキー、QA ライブプロバイダー設定パス、および存在する場合は `CODEX_HOME`。 - - 出力ディレクトリはリポジトリルート配下に置く必要があります。これにより、ゲストがマウントされたワークスペース経由で書き戻せます。 - - 通常の QA レポート + サマリーに加えて Multipass ログを + - 同じ QA suite を破棄可能な Multipass Linux VM 内で実行します。 + - ホスト上の `qa suite` と同じ scenario-selection 動作を維持します。 + - `qa suite` と同じ provider/model selection flags を再利用します。 + - Live runs は、guest にとって実用的なサポート済み QA auth inputs を転送します: + env-based provider keys、QA live provider config path、存在する場合は `CODEX_HOME`。 + - output dirs は repo root 配下に置く必要があります。これにより guest が mounted workspace 経由で書き戻せます。 + - 通常の QA report + summary に加え、Multipass logs を `.artifacts/qa-e2e/...` 配下に書き込みます。 - `pnpm qa:lab:up` - - オペレーター風の QA 作業向けに Docker ベースの QA サイトを起動します。 + - operator-style QA 作業のために Docker 裏付けの QA サイトを起動します。 - `pnpm test:docker:npm-onboard-channel-agent` - - 現在のチェックアウトから npm tarball をビルドし、Docker 内でグローバルインストールし、 - 非対話型の OpenAI API キーオンボーディングを実行し、デフォルトで Telegram を設定し、 - Plugin の有効化が必要に応じてランタイム依存関係をインストールすることを検証し、 - doctor を実行し、モックされた OpenAI エンドポイントに対して 1 回のローカルエージェントターンを実行します。 - - Discord で同じパッケージインストールレーンを実行するには `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使用してください。 + - 現在の checkout から npm tarball をビルドし、Docker 内でグローバルインストールし、 + 非対話の OpenAI API-key オンボーディングを実行し、デフォルトで Telegram を設定し、 + Plugin の有効化により runtime dependencies がオンデマンドでインストールされることを検証し、 + doctor を実行し、mocked OpenAI endpoint に対して 1 回の local agent turn を実行します。 + - Discord で同じ packaged-install lane を実行するには `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使います。 - `pnpm test:docker:session-runtime-context` - - 埋め込みランタイムコンテキストトランスクリプト向けの、決定論的なビルド済みアプリ Docker スモークを実行します。 - 非表示の OpenClaw ランタイムコンテキストが、表示されるユーザーターンに漏れるのではなく、 - 非表示のカスタムメッセージとして永続化されることを検証します。その後、影響を受けた壊れたセッション JSONL をシードし、 - `openclaw doctor --fix` がバックアップ付きでアクティブブランチへ書き換えることを検証します。 + - embedded runtime context transcripts のための決定的な built-app Docker smoke を実行します。 + hidden OpenClaw runtime context が、表示される user turn に漏れず、 + non-display custom message として永続化されることを検証し、その後、影響を受ける壊れた session JSONL を seed し、 + `openclaw doctor --fix` が backup 付きで active branch に書き換えることを検証します。 - `pnpm test:docker:npm-telegram-live` - - Docker 内に OpenClaw パッケージ候補をインストールし、インストール済みパッケージの - オンボーディングを実行し、インストール済み CLI を通じて Telegram を設定したうえで、 - そのインストール済みパッケージを SUT Gateway としてライブ Telegram QA レーンを再利用します。 + - Docker 内に OpenClaw package candidate をインストールし、installed-package オンボーディングを実行し、 + installed CLI 経由で Telegram を設定した後、その installed package を SUT Gateway として + live Telegram QA lane を再利用します。 - デフォルトは `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` です。 - レジストリからインストールする代わりに解決済みローカル tarball をテストするには、 + registry からインストールする代わりに解決済みの local tarball をテストするには、 `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` または - `OPENCLAW_CURRENT_PACKAGE_TGZ` を設定してください。 - - `pnpm openclaw qa telegram` と同じ Telegram 環境認証情報または Convex 認証情報ソースを使用します。 - CI/リリース自動化では、`OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` に加えて - `OPENCLAW_QA_CONVEX_SITE_URL` とロールシークレットを設定してください。CI に - `OPENCLAW_QA_CONVEX_SITE_URL` と Convex ロールシークレットが存在する場合、 - Docker ラッパーは Convex を自動的に選択します。 - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` は、このレーンに限り共有の + `OPENCLAW_CURRENT_PACKAGE_TGZ` を設定します。 + - `pnpm openclaw qa telegram` と同じ Telegram env credentials または Convex credential source を使います。 + CI/release automation では、`OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` に加えて + `OPENCLAW_QA_CONVEX_SITE_URL` と role secret を設定します。CI に + `OPENCLAW_QA_CONVEX_SITE_URL` と Convex role secret が存在する場合、 + Docker wrapper は Convex を自動選択します。 + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` は、この lane に限って共有の `OPENCLAW_QA_CREDENTIAL_ROLE` を上書きします。 - - GitHub Actions では、このレーンを手動メンテナーワークフロー - `NPM Telegram Beta E2E` として公開しています。マージ時には実行されません。このワークフローは - `qa-live-shared` 環境と Convex CI 認証情報リースを使用します。 -- GitHub Actions では、候補パッケージ 1 つに対するサイドラン製品証明用に `Package Acceptance` も公開しています。 - 信頼済み ref、公開 npm spec、SHA-256 付き HTTPS tarball URL、または別実行の tarball アーティファクトを受け取り、 - 正規化された `openclaw-current.tgz` を `package-under-test` としてアップロードし、その後既存の Docker E2E スケジューラーを - smoke、package、product、full、または custom レーンプロファイルで実行します。同じ `package-under-test` アーティファクトに対して - Telegram QA ワークフローを実行するには、`telegram_mode=mock-openai` または `live-frontier` を設定してください。 - - 最新ベータ製品証明: + - GitHub Actions はこの lane を手動 maintainer workflow + `NPM Telegram Beta E2E` として公開しています。merge 時には実行されません。この workflow は + `qa-live-shared` environment と Convex CI credential leases を使います。 +- GitHub Actions は、1 つの candidate package に対する side-run product proof として + `Package Acceptance` も公開しています。trusted ref、published npm spec、 + SHA-256 付き HTTPS tarball URL、または別 run の tarball artifact を受け取り、 + 正規化された `openclaw-current.tgz` を `package-under-test` として upload した後、 + smoke、package、product、full、custom lane profiles で既存の Docker E2E scheduler を実行します。 + 同じ `package-under-test` artifact に対して Telegram QA workflow を実行するには、 + `telegram_mode=mock-openai` または `live-frontier` を設定します。 + - 最新 beta product proof: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -196,7 +204,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- 正確な tarball URL 証明にはダイジェストが必要です: +- 正確な tarball URL proof には digest が必要です: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -217,72 +225,72 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:bundled-channel-deps` - - 現在の OpenClaw ビルドを Docker 内でパックしてインストールし、OpenAI を設定した状態で Gateway を起動してから、設定の編集により同梱チャネル/Plugin を有効化します。 - - セットアップ検出により、未設定 Plugin のランタイム依存関係が存在しないままになること、最初に設定された Gateway または doctor 実行が各同梱 Plugin のランタイム依存関係を必要時にインストールすること、2 回目の再起動ではすでに有効化済みの依存関係を再インストールしないことを検証します。 - - 既知の古い npm ベースラインもインストールし、`openclaw update --tag ` を実行する前に Telegram を有効化し、候補版の更新後 doctor が、ハーネス側の postinstall 修復なしで同梱チャネルのランタイム依存関係を修復することを検証します。 + - 現在の OpenClaw ビルドを Docker 内でパックしてインストールし、OpenAI を設定した Gateway を起動してから、設定編集によって同梱チャネル/Plugin を有効にします。 + - セットアップ検出によって、未設定 Plugin のランタイム依存関係が存在しないこと、最初に設定された Gateway または doctor 実行が各同梱 Plugin のランタイム依存関係をオンデマンドでインストールすること、2 回目の再起動ではすでに有効化された依存関係を再インストールしないことを検証します。 + - また、既知の古い npm ベースラインをインストールし、`openclaw update --tag ` を実行する前に Telegram を有効化し、候補版の更新後 doctor がハーネス側の postinstall 修復なしで同梱チャネルのランタイム依存関係を修復することを検証します。 - `pnpm test:parallels:npm-update` - - Parallels ゲスト全体で、ネイティブのパッケージ済みインストール更新スモークを実行します。選択された各プラットフォームは、まず要求されたベースラインパッケージをインストールし、その後同じゲスト内でインストール済みの `openclaw update` コマンドを実行して、インストール済みバージョン、更新ステータス、Gateway の準備完了状態、ローカルエージェントの 1 ターンを検証します。 - - 1 つのゲストで反復する場合は、`--platform macos`、`--platform windows`、または `--platform linux` を使用します。サマリーアーティファクトのパスとレーンごとのステータスには `--json` を使用します。 - - OpenAI レーンは、既定でライブエージェントターン証明に `openai/gpt-5.5` を使用します。別の OpenAI モデルを意図的に検証する場合は、`--model ` を渡すか、`OPENCLAW_PARALLELS_OPENAI_MODEL` を設定します。 - - Parallels の転送停止がテスト時間枠の残りを消費しないよう、長時間のローカル実行はホストのタイムアウトでラップします。 + - Parallels ゲスト全体で、ネイティブのパッケージ版インストール更新 smoke を実行します。選択された各プラットフォームは、まず要求されたベースラインパッケージをインストールし、次に同じゲスト内でインストール済みの `openclaw update` コマンドを実行して、インストール済みバージョン、更新ステータス、Gateway の準備完了状態、および 1 回のローカルエージェントターンを検証します。 + - 1 つのゲストで反復作業する間は、`--platform macos`、`--platform windows`、または `--platform linux` を使用します。サマリーアーティファクトのパスとレーンごとのステータスには `--json` を使用します。 + - OpenAI レーンは、デフォルトでライブエージェントターン証明に `openai/gpt-5.5` を使用します。別の OpenAI モデルを意図的に検証する場合は、`--model ` を渡すか、`OPENCLAW_PARALLELS_OPENAI_MODEL` を設定します。 + - Parallels 転送の停止が残りのテスト時間を消費しないよう、長時間のローカル実行はホストのタイムアウトでラップします。 ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - スクリプトは、ネストされたレーンログを `/tmp/openclaw-parallels-npm-update.*` 配下に書き込みます。外側のラッパーが停止していると判断する前に、`windows-update.log`、`macos-update.log`、または `linux-update.log` を確認してください。 - - Windows 更新では、コールドゲスト上の更新後 doctor/ランタイム依存関係修復に 10 分から 15 分かかる場合があります。ネストされた npm デバッグログが進んでいれば、まだ正常です。 - - この集約ラッパーを、個別の Parallels macOS、Windows、または Linux スモークレーンと並行して実行しないでください。これらは VM 状態を共有し、スナップショット復元、パッケージ配信、またはゲスト Gateway 状態で衝突する可能性があります。 - - 更新後証明は通常の同梱 Plugin サーフェスを実行します。音声、画像生成、メディア理解などの機能ファサードは、エージェントターン自体が単純なテキスト応答のみを確認する場合でも、同梱ランタイム API 経由で読み込まれるためです。 + - スクリプトは、ネストされたレーンログを `/tmp/openclaw-parallels-npm-update.*` 配下に書き込みます。外側のラッパーがハングしていると判断する前に、`windows-update.log`、`macos-update.log`、または `linux-update.log` を確認してください。 + - Windows 更新は、冷えたゲスト上では更新後 doctor/ランタイム依存関係修復に 10 分から 15 分かかることがあります。ネストされた npm デバッグログが進んでいる場合、それでも正常です。 + - この集約ラッパーを、個別の Parallels macOS、Windows、または Linux smoke レーンと並行して実行しないでください。これらは VM 状態を共有しており、スナップショット復元、パッケージ配信、またはゲスト Gateway 状態で衝突する可能性があります。 + - 更新後証明では通常の同梱 Plugin サーフェスを実行します。これは、音声、画像生成、メディア理解などのケイパビリティファサードが、エージェントターン自体では単純なテキスト応答だけを確認する場合でも、同梱ランタイム API を通じて読み込まれるためです。 - `pnpm openclaw qa aimock` - - 直接のプロトコルスモークテスト用に、ローカル AIMock プロバイダーサーバーのみを起動します。 + - 直接プロトコル smoke テスト用に、ローカル AIMock プロバイダーサーバーのみを起動します。 - `pnpm openclaw qa matrix` - - 使い捨ての Docker バックエンド付き Tuwunel homeserver に対して Matrix ライブ QA レーンを実行します。ソースチェックアウトのみです。パッケージ済みインストールには `qa-lab` は同梱されません。 + - 使い捨ての Docker 裏付け Tuwunel homeserver に対して Matrix ライブ QA レーンを実行します。ソースチェックアウト専用です。パッケージ版インストールには `qa-lab` は含まれません。 - 完全な CLI、プロファイル/シナリオカタログ、環境変数、アーティファクトレイアウト: [Matrix QA](/ja-JP/concepts/qa-matrix)。 - `pnpm openclaw qa telegram` - - 環境変数のドライバーおよび SUT bot トークンを使用して、実在のプライベートグループに対して Telegram ライブ QA レーンを実行します。 + - 環境変数のドライバーおよび SUT bot トークンを使用し、実際の非公開グループに対して Telegram ライブ QA レーンを実行します。 - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、および `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。グループ ID は数値の Telegram チャット ID である必要があります。 - - 共有プール認証情報には `--credential-source convex` をサポートします。既定では env モードを使用するか、プールされたリースを有効にするには `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定します。 - - いずれかのシナリオが失敗すると、非ゼロで終了します。失敗終了コードなしでアーティファクトが必要な場合は、`--allow-failures` を使用します。 - - 同じプライベートグループ内に 2 つの異なる bot が必要で、SUT bot は Telegram ユーザー名を公開している必要があります。 - - 安定した bot 間観測のため、両方の bot で `@BotFather` の Bot-to-Bot Communication Mode を有効化し、ドライバー bot がグループの bot トラフィックを観測できるようにしてください。 - - `.artifacts/qa-e2e/...` 配下に Telegram QA レポート、サマリー、観測済みメッセージアーティファクトを書き込みます。返信シナリオには、ドライバーの送信要求から観測された SUT 返信までの RTT が含まれます。 + - 共有プール済み認証情報には `--credential-source convex` をサポートします。デフォルトでは env モードを使用し、プール済みリースを選択するには `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定します。 + - いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしでアーティファクトが必要な場合は `--allow-failures` を使用します。 + - 同じ非公開グループ内に 2 つの異なる bot が必要で、SUT bot は Telegram ユーザー名を公開している必要があります。 + - 安定した bot 間観測のため、両方の bot で `@BotFather` の Bot-to-Bot Communication Mode を有効にし、ドライバー bot がグループ bot トラフィックを観測できるようにします。 + - Telegram QA レポート、サマリー、および観測メッセージアーティファクトを `.artifacts/qa-e2e/...` 配下に書き込みます。返信シナリオには、ドライバーの送信リクエストから観測された SUT 返信までの RTT が含まれます。 -ライブ転送レーンは、新しい転送がずれないように 1 つの標準契約を共有します。レーンごとのカバレッジマトリックスは [QA 概要 → ライブ転送カバレッジ](/ja-JP/concepts/qa-e2e-automation#live-transport-coverage) にあります。`qa-channel` は広範な合成スイートであり、このマトリックスには含まれません。 +ライブ転送レーンは、新しい転送が逸脱しないように 1 つの標準契約を共有します。レーンごとのカバレッジマトリクスは [QA 概要 → ライブ転送カバレッジ](/ja-JP/concepts/qa-e2e-automation#live-transport-coverage) にあります。`qa-channel` は広範な合成スイートであり、このマトリクスの一部ではありません。 ### Convex 経由の共有 Telegram 認証情報 (v1) -`openclaw qa telegram` で `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）が有効な場合、QA lab は Convex バックエンドのプールから排他的リースを取得し、レーンの実行中はそのリースに Heartbeat を送信し、シャットダウン時にリースを解放します。 +`openclaw qa telegram` で `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）が有効な場合、QA lab は Convex 裏付けプールから排他的リースを取得し、レーンの実行中にそのリースへ Heartbeat し、シャットダウン時にリースを解放します。 参照用 Convex プロジェクトスキャフォールド: - `qa/convex-credential-broker/` -必須の環境変数: +必須環境変数: - `OPENCLAW_QA_CONVEX_SITE_URL`（例: `https://your-deployment.convex.site`） - 選択されたロール用のシークレット 1 つ: - `maintainer` 用の `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` - `ci` 用の `OPENCLAW_QA_CONVEX_SECRET_CI` -- 認証情報ロールの選択: +- 認証情報ロール選択: - CLI: `--credential-role maintainer|ci` - - 環境変数の既定値: `OPENCLAW_QA_CREDENTIAL_ROLE`（CI では既定で `ci`、それ以外では `maintainer`） + - 環境変数デフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（CI ではデフォルトで `ci`、それ以外では `maintainer`） 任意の環境変数: -- `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_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`（任意のトレース ID） - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` は、ローカル専用開発向けに loopback `http://` Convex URL を許可します。 -通常運用では、`OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使用する必要があります。 +通常運用では、`OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使用してください。 -メンテナー管理コマンド（プールの追加/削除/一覧表示）には、具体的に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 +メンテナー管理コマンド（プールの追加/削除/一覧）には、特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 メンテナー向け CLI ヘルパー: @@ -293,14 +301,14 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -ライブ実行の前に `doctor` を使用して、シークレット値を出力せずに、Convex サイト URL、ブローカーシークレット、エンドポイントプレフィックス、HTTP タイムアウト、管理/一覧到達性を確認します。スクリプトや CI ユーティリティで機械可読な出力が必要な場合は、`--json` を使用します。 +ライブ実行の前に `doctor` を使用して、シークレット値を出力せずに Convex サイト URL、ブローカーシークレット、エンドポイントプレフィックス、HTTP タイムアウト、および admin/list 到達性を確認します。スクリプトおよび CI ユーティリティで機械可読出力が必要な場合は `--json` を使用します。 -既定のエンドポイント契約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: +デフォルトエンドポイント契約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: - `POST /acquire` - リクエスト: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - 成功: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - 枯渇/再試行可能: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - 枯渇/リトライ可能: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - リクエスト: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - 成功: `{ status: "ok" }`（または空の `2xx`） @@ -318,98 +326,129 @@ pnpm openclaw qa credentials remove --credential-id - リクエスト: `{ kind?, status?, includePayload?, limit? }` - 成功: `{ status: "ok", credentials, count }` -Telegram 種別のペイロード形状: +Telegram kind のペイロード形状: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` は数値の Telegram チャット ID 文字列である必要があります。 -- `admin/add` は `kind: "telegram"` についてこの形状を検証し、不正な形式のペイロードを拒否します。 +- `admin/add` は `kind: "telegram"` に対してこの形状を検証し、不正なペイロードを拒否します。 ### QA へのチャネル追加 -新しいチャネルアダプターのアーキテクチャとシナリオヘルパー名は、[QA 概要 → チャネルの追加](/ja-JP/concepts/qa-e2e-automation#adding-a-channel) にあります。最小要件: 共有 `qa-lab` ホストシーム上で転送ランナーを実装し、Plugin マニフェストで `qaRunners` を宣言し、`openclaw qa ` としてマウントし、`qa/scenarios/` 配下にシナリオを作成します。 +新しいチャネルアダプターのアーキテクチャおよびシナリオヘルパー名は、[QA 概要 → チャネルの追加](/ja-JP/concepts/qa-e2e-automation#adding-a-channel) にあります。最小要件は、共有 `qa-lab` ホストシーム上に転送ランナーを実装し、Plugin マニフェストで `qaRunners` を宣言し、`openclaw qa ` としてマウントし、`qa/scenarios/` 配下にシナリオを作成することです。 ## テストスイート（どこで何が実行されるか） -スイートは「リアリズムの増加」（および不安定さ/コストの増加）として考えてください。 +スイートは「リアリズムが増していく」（同時に不安定さ/コストも増す）ものとして考えてください。 -### ユニット / 統合（既定） +### ユニット / 統合（デフォルト） - コマンド: `pnpm test` -- 設定: ターゲット指定なしの実行は `vitest.full-*.config.ts` シャードセットを使用し、並列スケジューリングのためにマルチプロジェクトシャードをプロジェクトごとの設定へ展開する場合があります -- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、および `test/**/*.test.ts` 配下の core/ユニットインベントリ。UI ユニットテストは専用の `unit-ui` シャードで実行されます +- 設定: ターゲット指定なしの実行では `vitest.full-*.config.ts` シャードセットを使用し、並列スケジューリングのためにマルチプロジェクトシャードをプロジェクトごとの設定に展開する場合があります +- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、および `test/**/*.test.ts` 配下の core/unit インベントリ。UI ユニットテストは専用の `unit-ui` シャードで実行されます - スコープ: - 純粋なユニットテスト - - インプロセス統合テスト（Gateway 認証、ルーティング、ツール処理、解析、設定） - - 既知のバグに対する決定的な回帰テスト + - インプロセス統合テスト（Gateway 認証、ルーティング、ツール、解析、設定） + - 既知バグの決定的リグレッション - 期待事項: - CI で実行される - 実キーは不要 - 高速かつ安定しているべき - - リゾルバーおよび公開サーフェスローダーテストは、実際の同梱 Plugin ソース API ではなく、生成された小さな Plugin フィクスチャで広範な `api.js` および `runtime-api.js` フォールバック動作を証明する必要があります。実際の Plugin API 読み込みは、Plugin 所有の契約/統合スイートに属します。 + - リゾルバーおよび公開サーフェスローダーのテストは、実際の同梱 Plugin ソース API ではなく、生成された小さな Plugin フィクスチャを使って、広範な `api.js` および `runtime-api.js` フォールバック動作を証明する必要があります。実際の Plugin API 読み込みは、Plugin 所有の契約/統合スイートに属します。 - + - - ターゲット未指定の `pnpm test` は、1 つの巨大なネイティブルートプロジェクトプロセスではなく、12 個の小さなシャード設定（`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` は引き続きネイティブルートの `vitest.config.ts` プロジェクトグラフを使用します。マルチシャードの watch ループは実用的ではないためです。 - - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリターゲットをまずスコープ付きレーンにルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` はルートプロジェクト全体の起動コストを支払わずに済みます。 - - `pnpm test:changed` は、変更された git パスをデフォルトで低コストなスコープ付きレーンに展開します。直接のテスト編集、兄弟 `*.test.ts` ファイル、明示的なソースマッピング、ローカル import グラフの依存先が対象です。Config/setup/package の編集では、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を明示的に使用しない限り、テストを広範囲には実行しません。 - - `pnpm check:changed` は、狭い作業向けの通常のスマートなローカルチェックゲートです。diff を core、core tests、extensions、extension tests、apps、docs、release metadata、live Docker tooling、tooling に分類し、対応する typecheck、lint、guard コマンドを実行します。Vitest テストは実行しません。テストの証明には `pnpm test:changed` または明示的な `pnpm test ` を呼び出してください。release metadata のみのバージョンバンプでは、対象を絞った version/config/root-dependency チェックを実行し、トップレベルの version フィールド以外の package 変更を拒否する guard が付きます。 - - Live Docker ACP ハーネスの編集では、live Docker auth スクリプトのシェル構文と live Docker scheduler の dry-run という集中チェックを実行します。`package.json` の変更が含まれるのは、diff が `scripts["test:docker:live-*"]` に限定される場合のみです。dependency、export、version、その他 package surface の編集では引き続きより広範な guard を使用します。 - - agents、commands、plugins、auto-reply helpers、`plugin-sdk`、および同様の純粋な utility 領域の import が軽い単体テストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンにルーティングされます。stateful/runtime-heavy なファイルは既存のレーンに残ります。 - - 選択された `plugin-sdk` と `commands` の helper ソースファイルも、changed-mode の実行をこれらの軽いレーンの明示的な兄弟テストにマッピングするため、helper の編集でそのディレクトリの重いスイート全体を再実行せずに済みます。 - - `auto-reply` には、トップレベルの core helpers、トップレベルの `reply.*` integration tests、`src/auto-reply/reply/**` サブツリー向けの専用バケットがあります。CI ではさらに reply サブツリーを agent-runner、dispatch、commands/state-routing のシャードに分割し、1 つの import-heavy なバケットが Node の末尾全体を占有しないようにします。 - - 通常の PR/main CI は、extension batch sweep と release-only の `agentic-plugins` シャードを意図的にスキップします。Full Release Validation は、リリース候補に対して plugin/extension-heavy なこれらのスイート用に別個の `Plugin Prerelease` 子ワークフローを dispatch します。 + - ターゲット指定なしの `pnpm test` は、巨大な単一のネイティブルートプロジェクトプロセスの代わりに、12 個の小さなシャード設定（`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` は引き続きネイティブルートの `vitest.config.ts` プロジェクトグラフを使用します。複数シャードの watch ループは実用的ではないためです。 + - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリターゲットをまずスコープ付きレーンにルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` はルートプロジェクト全体の起動コストを払わずに済みます。 + - `pnpm test:changed` は、変更された git パスをデフォルトで低コストなスコープ付きレーンに展開します。対象は、直接のテスト編集、兄弟 `*.test.ts` ファイル、明示的なソースマッピング、ローカル import グラフの依存先です。設定/セットアップ/パッケージの編集では、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を明示的に使わない限り、テストを広範囲には実行しません。 + - `pnpm check:changed` は、狭い作業向けの通常のスマートなローカルチェックゲートです。diff を core、core tests、extensions、extension tests、apps、docs、release metadata、live Docker tooling、tooling に分類し、対応する typecheck、lint、guard コマンドを実行します。Vitest テストは実行しません。テストの証明には `pnpm test:changed` または明示的な `pnpm test ` を呼び出してください。release metadata のみのバージョンバンプでは、対象を絞った version/config/root-dependency チェックを実行し、最上位の version フィールド以外の package 変更を拒否する guard を適用します。 + - Live Docker ACP ハーネスの編集では、live Docker 認証スクリプトのシェル構文と live Docker スケジューラの dry-run という絞り込まれたチェックを実行します。`package.json` の変更は、diff が `scripts["test:docker:live-*"]` に限定されている場合のみ含まれます。dependency、export、version、その他の package サーフェス編集では、引き続きより広い guard を使用します。 + - agents、commands、plugins、auto-reply helpers、`plugin-sdk`、および同種の純粋な utility 領域からの import-light unit tests は、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンにルーティングされます。stateful/runtime-heavy ファイルは既存のレーンに残ります。 + - 選択された `plugin-sdk` と `commands` の helper source files も、changed-mode の実行をそれらの軽量レーン内の明示的な兄弟テストへマッピングするため、helper の編集でそのディレクトリ全体の重いスイートを再実行せずに済みます。 + - `auto-reply` には、トップレベルの core helpers、トップレベルの `reply.*` integration tests、`src/auto-reply/reply/**` サブツリー用の専用バケットがあります。CI ではさらに reply サブツリーを agent-runner、dispatch、commands/state-routing シャードに分割し、import-heavy な 1 つのバケットが Node の末尾全体を占有しないようにしています。 + - 通常の PR/main CI では、extension batch sweep と release 専用の `agentic-plugins` シャードを意図的にスキップします。Full Release Validation は、release candidate 向けに plugin/extension-heavy なそれらのスイート用の別個の `Plugin Prerelease` 子ワークフローを dispatch します。 - + - - message-tool discovery inputs または Compaction runtime context を変更する場合は、両方のレベルのカバレッジを維持してください。 - - 純粋な routing と normalization の境界には、焦点を絞った helper 回帰テストを追加してください。 - - 組み込みランナーの integration suite を健全に保ってください: - `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, および + - message-tool discovery input または compaction runtime + context を変更するときは、両方のカバレッジレベルを維持してください。 + - 純粋な routing と normalization + 境界には、焦点を絞った helper regression を追加してください。 + - embedded runner integration suites を正常な状態に保ってください: + `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`、および `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - これらのスイートは、スコープ付き id と Compaction の挙動が実際の `run.ts` / `compact.ts` パスを通って引き続き流れることを検証します。helper-only テストは、これらの integration パスの十分な代替にはなりません。 + - これらのスイートは、スコープ付き id と compaction の挙動が実際の + `run.ts` / `compact.ts` パスを通って流れ続けることを検証します。helper のみのテストは、 + それらの integration パスの十分な代替にはなりません。 - + - - ベースの Vitest config はデフォルトで `threads` を使用します。 - - 共有 Vitest config は `isolate: false` を固定し、ルートプロジェクト、e2e、live configs 全体で非 isolated runner を使用します。 - - ルート UI レーンは `jsdom` setup と optimizer を維持しますが、共有の非 isolated runner 上でも実行されます。 - - 各 `pnpm test` シャードは、共有 Vitest config から同じ `threads` + `isolate: false` のデフォルトを継承します。 - - `scripts/run-vitest.mjs` は、大規模なローカル実行中の V8 compile churn を減らすため、デフォルトで Vitest 子 Node プロセスに `--no-maglev` を追加します。 + - ベース Vitest 設定のデフォルトは `threads` です。 + - 共有 Vitest 設定は `isolate: false` を固定し、root projects、e2e、live configs 全体で + non-isolated runner を使用します。 + - root UI レーンは `jsdom` セットアップと optimizer を維持しますが、 + 共有の non-isolated runner でも実行されます。 + - 各 `pnpm test` シャードは、共有 Vitest 設定から同じ `threads` + `isolate: false` + のデフォルトを継承します。 + - `scripts/run-vitest.mjs` は、大規模なローカル実行中の V8 compile churn を減らすため、 + デフォルトで Vitest 子 Node プロセスに `--no-maglev` を追加します。 標準の V8 挙動と比較するには `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 - + - - `pnpm changed:lanes` は、diff がどの architectural lanes をトリガーするかを表示します。 - - pre-commit hook は formatting のみです。整形済みファイルを再 stage し、lint、typecheck、tests は実行しません。 - - handoff または push の前にスマートなローカルチェックゲートが必要な場合は、`pnpm check:changed` を明示的に実行してください。 - - `pnpm test:changed` はデフォルトで低コストなスコープ付きレーンを経由します。agent が harness、config、package、または contract の編集に本当に広範な Vitest カバレッジが必要だと判断した場合のみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 - - `pnpm test:max` と `pnpm test:changed:max` は同じルーティング挙動を維持し、worker cap だけを高くします。 - - ローカル worker の自動スケーリングは意図的に保守的で、host load average がすでに高い場合は抑制されるため、複数の同時 Vitest 実行による影響はデフォルトで小さくなります。 - - ベース Vitest config は projects/config files を `forceRerunTriggers` としてマークするため、test wiring が変更された場合でも changed-mode reruns は正確に保たれます。 - - config はサポート対象 host で `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効に保ちます。直接 profiling 用に明示的な cache location を 1 つ使いたい場合は、`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 + - `pnpm changed:lanes` は diff がどの architectural lanes をトリガーするかを表示します。 + - pre-commit hook は formatting のみです。format されたファイルを再 stage し、 + lint、typecheck、tests は実行しません。 + - handoff または push の前にスマートなローカルチェックゲートが必要な場合は、 + `pnpm check:changed` を明示的に実行してください。 + - `pnpm test:changed` はデフォルトで低コストなスコープ付きレーンを通ります。 + agent が harness、config、package、または contract の編集により本当に広範な + Vitest カバレッジが必要だと判断した場合のみ、 + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 + - `pnpm test:max` と `pnpm test:changed:max` は同じ routing + 挙動を維持し、worker cap だけが高くなります。 + - ローカル worker の自動スケーリングは意図的に保守的で、host load average がすでに高い場合は後退するため、複数の同時 + Vitest 実行による影響はデフォルトで抑えられます。 + - ベース Vitest 設定は projects/config files を + `forceRerunTriggers` としてマークするため、test + wiring が変更されたときも changed-mode rerun は正確なままです。 + - 設定は、サポートされているホストで `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効なままにします。 + 直接 profiling 用に 1 つの明示的な cache location が必要な場合は、 + `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 - - `pnpm test:perf:imports` は、Vitest import-duration reporting と import-breakdown output を有効にします。 - - `pnpm test:perf:imports:changed` は、同じ profiling view を `origin/main` 以降に変更されたファイルにスコープします。 - - shard timing data は `.artifacts/vitest-shard-timings.json` に書き込まれます。 - whole-config runs は config path を key として使用します。include-pattern CI shards は shard name を追加するため、filtered shards を個別に追跡できます。 - - 1 つの hot test がまだ startup imports にほとんどの時間を費やす場合は、heavy dependencies を狭いローカル `*.runtime.ts` seam の背後に置き、runtime helpers を `vi.mock(...)` に渡すためだけに deep-import するのではなく、その seam を直接 mock してください。 - - `pnpm test:perf:changed:bench -- --ref ` は、ルーティングされた `test:changed` を、そのコミット済み diff に対するネイティブルートプロジェクトパスと比較し、wall time と macOS max RSS を出力します。 - - `pnpm test:perf:changed:bench -- --worktree` は、changed file list を `scripts/test-projects.mjs` とルート Vitest config にルーティングして、現在の dirty tree を benchmark します。 - - `pnpm test:perf:profile:main` は、Vitest/Vite startup と transform overhead 用の main-thread CPU profile を書き込みます。 - - `pnpm test:perf:profile:runner` は、file parallelism を無効化した unit suite 用の runner CPU+heap profiles を書き込みます。 + - `pnpm test:perf:imports` は、Vitest の import-duration reporting と + import-breakdown output を有効にします。 + - `pnpm test:perf:imports:changed` は、同じ profiling view を + `origin/main` 以降に変更されたファイルへスコープします。 + - シャード timing data は `.artifacts/vitest-shard-timings.json` に書き込まれます。 + Whole-config runs は config path を key として使用します。include-pattern CI + shards は shard 名を追加するため、filtered shards を個別に追跡できます。 + - 1 つの hot test が依然として startup imports に大半の時間を費やしている場合は、 + 重い dependency を狭いローカル `*.runtime.ts` seam の背後に置き、 + runtime helpers を `vi.mock(...)` に通すためだけに deep-import するのではなく、 + その seam を直接 mock してください。 + - `pnpm test:perf:changed:bench -- --ref ` は、routing された + `test:changed` を、その committed + diff の native root-project path と比較し、wall time と macOS max RSS を出力します。 + - `pnpm test:perf:changed:bench -- --worktree` は、現在の + dirty tree を、変更ファイル一覧を + `scripts/test-projects.mjs` と root Vitest config に通して routing することで benchmark します。 + - `pnpm test:perf:profile:main` は、 + Vitest/Vite startup と transform overhead 用の main-thread CPU profile を書き込みます。 + - `pnpm test:perf:profile:runner` は、 + file parallelism を無効にした unit suite 用の runner CPU+heap profiles を書き込みます。 @@ -419,73 +458,73 @@ Telegram 種別のペイロード形状: - コマンド: `pnpm test:stability:gateway` - 設定: `vitest.gateway.config.ts`、1 worker に強制 - スコープ: - - diagnostics をデフォルトで有効にした実際の loopback Gateway を起動 - - diagnostic event path を通じて synthetic gateway message、memory、large-payload churn を駆動 - - Gateway WS RPC 経由で `diagnostics.stability` を照会 - - diagnostic stability bundle persistence helpers をカバー - - recorder が bounded のままであること、synthetic RSS samples が pressure budget 未満に保たれること、per-session queue depths がゼロに戻ることを assert -- 期待事項: + - diagnostics をデフォルトで有効にした実際の loopback Gateway を起動します + - synthetic gateway message、memory、large-payload churn を diagnostic event path 経由で駆動します + - Gateway WS RPC 経由で `diagnostics.stability` を query します + - diagnostic stability bundle persistence helpers をカバーします + - recorder が bounded のままであること、synthetic RSS samples が pressure budget 未満に収まること、per-session queue depths が 0 に戻ることを assert します +- 期待値: - CI-safe かつ keyless - - stability-regression の follow-up 向けの狭いレーンであり、Gateway suite 全体の代替ではありません + - stability-regression follow-up 用の狭いレーンであり、Gateway suite 全体の代替ではありません ### E2E（gateway smoke） - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` - ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`、および `extensions/` 配下の bundled-plugin E2E tests -- 実行時デフォルト: - - リポジトリの他の部分と同様に、`isolate: false` で Vitest `threads` を使用します。 - - adaptive workers を使用します（CI: 最大 2、local: デフォルトで 1）。 +- runtime defaults: + - repo の残りと一致するように、Vitest `threads` を `isolate: false` で使用します。 + - adaptive workers を使用します（CI: 最大 2、local: デフォルト 1）。 - console I/O overhead を減らすため、デフォルトで silent mode で実行します。 -- 便利な上書き: +- 便利な override: - worker count を強制するには `OPENCLAW_E2E_WORKERS=`（上限 16）。 - - verbose console output を再有効化するには `OPENCLAW_E2E_VERBOSE=1`。 + - verbose console output を再度有効にするには `OPENCLAW_E2E_VERBOSE=1`。 - スコープ: - multi-instance gateway end-to-end behavior - WebSocket/HTTP surfaces、node pairing、より重い networking -- 期待事項: +- 期待値: - CI で実行されます（pipeline で有効な場合） - - 実際の keys は不要 - - unit tests より moving parts が多い（遅くなる場合があります） + - 実際の key は不要です + - unit tests より moving parts が多くなります（遅くなる場合があります） ### E2E: OpenShell backend smoke - コマンド: `pnpm test:e2e:openshell` - ファイル: `extensions/openshell/src/backend.e2e.test.ts` - スコープ: - - Docker 経由で host 上に isolated OpenShell gateway を起動 - - 一時的なローカル Dockerfile から sandbox を作成 - - 実際の `sandbox ssh-config` + SSH exec を介して OpenClaw の OpenShell backend を exercise - - sandbox fs bridge 経由で remote-canonical filesystem behavior を検証 -- 期待事項: - - Opt-in のみ。デフォルトの `pnpm test:e2e` 実行の一部ではありません + - Docker 経由で host 上に isolated OpenShell gateway を起動します + - 一時的なローカル Dockerfile から sandbox を作成します + - 実際の `sandbox ssh-config` + SSH exec を介して OpenClaw の OpenShell backend を exercise します + - sandbox fs bridge 経由で remote-canonical filesystem behavior を検証します +- 期待値: + - opt-in のみです。デフォルトの `pnpm test:e2e` 実行には含まれません - ローカルの `openshell` CLI と動作する Docker daemon が必要です - isolated `HOME` / `XDG_CONFIG_HOME` を使用し、その後 test gateway と sandbox を破棄します -- 便利な上書き: - - broader e2e suite を手動で実行するときに test を有効化するには `OPENCLAW_E2E_OPENSHELL=1` - - 非デフォルトの CLI binary または wrapper script を指定するには `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` +- 便利な override: + - broader e2e suite を手動で実行するときに test を有効にするには `OPENCLAW_E2E_OPENSHELL=1` + - non-default CLI binary または wrapper script を指すには `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` -### Live（実際の providers + 実際の models） +### Live（real providers + real models） - コマンド: `pnpm test:live` - 設定: `vitest.live.config.ts` - ファイル: `src/**/*.live.test.ts`、`test/**/*.live.test.ts`、および `extensions/` 配下の bundled-plugin live tests -- デフォルト: `pnpm test:live` により **有効**（`OPENCLAW_LIVE_TEST=1` を設定） +- デフォルト: `pnpm test:live` により **enabled**（`OPENCLAW_LIVE_TEST=1` を設定） - スコープ: - - 「この provider/model は、実際の creds で _今日_ 本当に動くか？」 - - provider format changes、tool-calling quirks、auth issues、rate limit behavior を検出 -- 期待事項: - - 設計上 CI-stable ではありません（実際の networks、実際の provider policies、quotas、outages） - - 費用がかかる / rate limits を使用します - - 「everything」ではなく、絞り込んだ subsets の実行を推奨 -- Live runs は `~/.profile` を source して不足している API keys を取得します。 -- デフォルトでは、live runs は引き続き `HOME` を isolate し、config/auth material を一時 test home にコピーするため、unit fixtures が実際の `~/.openclaw` を mutate することはありません。 + - 「この provider/model は、実際の creds で _today_ 本当に動作するか」 + - provider format changes、tool-calling quirks、auth issues、rate limit behavior を検出します +- 期待値: + - 設計上 CI-stable ではありません（real networks、real provider policies、quotas、outages） + - お金がかかる / rate limits を使用します + - 「everything」ではなく、絞り込んだ subset の実行を優先してください +- live runs は `~/.profile` を source して、不足している API keys を取得します。 +- デフォルトでは、live runs でも `HOME` を isolate し、config/auth material を temp test home にコピーするため、unit fixtures が実際の `~/.openclaw` を変更できません。 - live tests で実際の home directory を使う必要が意図的にある場合のみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 -- `pnpm test:live` は現在、デフォルトでより静かなモードです。`[live] ...` progress output は維持しますが、追加の `~/.profile` notice を抑制し、gateway bootstrap logs/Bonjour chatter を mute します。完全な startup logs を戻したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 -- API key rotation（provider-specific）: `*_API_KEYS` を comma/semicolon format で設定するか、`*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）を設定します。または `OPENCLAW_LIVE_*_KEY` による per-live override を使用します。tests は rate limit responses で retry します。 -- Progress/Heartbeat output: - - Live suites は stderr に progress lines を出力するようになったため、Vitest console capture が静かな場合でも長い provider calls が visibly active であることが分かります。 - - `vitest.live.config.ts` は Vitest console interception を無効にし、provider/gateway progress lines が live runs 中に即座に stream されるようにします。 +- `pnpm test:live` は現在、より静かな mode がデフォルトです。`[live] ...` progress output は維持しますが、追加の `~/.profile` notice を抑制し、gateway bootstrap logs/Bonjour chatter を mute します。startup logs 全体を戻したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 +- API key rotation（provider-specific）: comma/semicolon format の `*_API_KEYS`、または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）を設定するか、`OPENCLAW_LIVE_*_KEY` による per-live override を使用してください。tests は rate limit responses で retry します。 +- Progress/heartbeat output: + - Live suites は stderr に progress lines を出力するようになったため、Vitest console capture が quiet の場合でも、長い provider calls が visibly active になります。 + - `vitest.live.config.ts` は Vitest console interception を無効にするため、provider/gateway progress lines は live runs 中に即座に stream されます。 - direct-model heartbeats は `OPENCLAW_LIVE_HEARTBEAT_MS` で調整します。 - gateway/probe heartbeats は `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 @@ -493,112 +532,117 @@ Telegram 種別のペイロード形状: この decision table を使用してください: -- 編集ロジック/テスト: `pnpm test` を実行（多くを変更した場合は `pnpm test:coverage` も実行） -- Gateway ネットワーク / WS プロトコル / ペアリングに触れる場合: `pnpm test:e2e` を追加 -- 「my bot is down」のデバッグ / プロバイダー固有の失敗 / ツール呼び出し: 絞り込んだ `pnpm test:live` を実行 +- 編集ロジック/テスト: `pnpm test` を実行します（多く変更した場合は `pnpm test:coverage` も） +- Gateway ネットワーク / WS プロトコル / ペアリングに触れる場合: `pnpm test:e2e` を追加します +- 「自分のボットが落ちている」/ プロバイダー固有の失敗 / ツール呼び出しをデバッグする場合: 絞り込んだ `pnpm test:live` を実行します ## ライブ（ネットワークに触れる）テスト -ライブモデルマトリクス、CLI バックエンドのスモーク、ACP スモーク、Codex アプリサーバーハーネス、およびすべてのメディアプロバイダーのライブテスト（Deepgram、BytePlus、ComfyUI、画像、音楽、動画、メディアハーネス）と、ライブ実行の認証情報処理については、[テスト — ライブスイート](/ja-JP/help/testing-live) を参照してください。 +ライブモデルマトリクス、CLI バックエンドのスモーク、ACP のスモーク、Codex app-server +ハーネス、すべてのメディアプロバイダーのライブテスト（Deepgram、BytePlus、ComfyUI、画像、 +音楽、動画、メディアハーネス）およびライブ実行用の認証情報処理については、 +[テスト — ライブスイート](/ja-JP/help/testing-live) を参照してください。 ## Docker ランナー（任意の「Linux で動作する」チェック） これらの Docker ランナーは 2 つのバケットに分かれます。 -- ライブモデルランナー: `test:docker:live-models` と `test:docker:live-gateway` は、リポジトリの Docker イメージ内で対応するプロファイルキーのライブファイル（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）のみを実行し、ローカル設定ディレクトリとワークスペースをマウントします（マウントされている場合は `~/.profile` も読み込みます）。対応するローカルエントリーポイントは `test:live:models-profiles` と `test:live:gateway-profiles` です。 -- Docker ライブランナーは、Docker 全体スイープを現実的に保つため、デフォルトで小さめのスモーク上限を使います: - `test:docker:live-models` はデフォルトで `OPENCLAW_LIVE_MAX_MODELS=12`、 - `test:docker:live-gateway` はデフォルトで `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 +- ライブモデルランナー: `test:docker:live-models` と `test:docker:live-gateway` は、リポジトリの Docker イメージ内で一致する profile-key のライブファイル（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）だけを実行し、ローカルの設定ディレクトリとワークスペースをマウントします（マウントされている場合は `~/.profile` も読み込みます）。対応するローカルエントリポイントは `test:live:models-profiles` と `test:live:gateway-profiles` です。 +- Docker ライブランナーは、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` 経由でライブ Docker イメージを一度だけビルドし、`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw を npm tarball として一度だけパックしてから、2 つの `scripts/e2e/Dockerfile` イメージをビルド/再利用します。ベア画像は、インストール/更新/Plugin 依存関係レーン用の Node/Git ランナーのみです。これらのレーンは事前ビルド済み tarball をマウントします。機能イメージは、ビルド済みアプリ機能レーン用に同じ tarball を `/app` にインストールします。Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーのロジックは `scripts/lib/docker-e2e-plan.mjs` にあります。`scripts/test-docker-all.mjs` は選択されたプランを実行します。集約処理は重み付きローカルスケジューラーを使います。`OPENCLAW_DOCKER_ALL_PARALLELISM` はプロセススロットを制御し、リソース上限により重いライブ、npm インストール、マルチサービスのレーンが同時にすべて開始されないようにします。単一のレーンが有効な上限より重い場合でも、プールが空ならスケジューラーはそれを開始でき、その後、再び容量が利用可能になるまで単独で実行し続けます。デフォルトは 10 スロット、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`、`OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` です。Docker ホストにさらに余裕がある場合に限り、`OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` または `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` を調整してください。ランナーはデフォルトで Docker プリフライトを実行し、古い OpenClaw E2E コンテナを削除し、30 秒ごとにステータスを表示し、成功したレーンの所要時間を `.artifacts/docker-tests/lane-timings.json` に保存し、以降の実行ではその所要時間を使って長いレーンを先に開始します。Docker をビルドまたは実行せずに重み付きレーンマニフェストを表示するには `OPENCLAW_DOCKER_ALL_DRY_RUN=1` を使い、選択レーン、パッケージ/イメージ要件、認証情報の CI プランを表示するには `node scripts/test-docker-all.mjs --plan-json` を使います。 -- `Package Acceptance` は、「このインストール可能な tarball は製品として動作するか」を確認する GitHub ネイティブのパッケージゲートです。`source=npm`、`source=ref`、`source=url`、または `source=artifact` から候補パッケージを 1 つ解決し、それを `package-under-test` としてアップロードしてから、選択された ref を再パックするのではなく、その正確な tarball に対して再利用可能な Docker E2E レーンを実行します。`workflow_ref` は信頼済みワークフロー/ハーネススクリプトを選択し、`package_ref` は `source=ref` のときにパックするソースコミット/ブランチ/タグを選択します。これにより、現在の受け入れロジックで過去の信頼済みコミットを検証できます。プロファイルは範囲の広さで並んでいます。`smoke` は高速なインストール/チャンネル/エージェントに Gateway/設定を加えたもの、`package` はパッケージ/更新/Plugin 契約に、キーなしのアップグレード生存フィクスチャと、ほとんどの Parallels パッケージ/更新カバレッジに対するデフォルトのネイティブ代替を加えたもの、`product` は MCP チャンネル、Cron/サブエージェントのクリーンアップ、OpenAI ウェブ検索、OpenWebUI を追加したもの、`full` は OpenWebUI 付きでリリースパスの Docker チャンクを実行するものです。リリース検証では、リリースパスの Docker チャンクが重複するパッケージ/更新/Plugin レーンをすでにカバーしているため、カスタムパッケージ差分（`bundled-channel-deps-compat plugins-offline`）と Telegram パッケージ QA を実行します。アーティファクトから生成されるターゲット付き GitHub Docker 再実行コマンドには、利用可能な場合、以前のパッケージアーティファクトと準備済みイメージ入力が含まれるため、失敗したレーンはパッケージとイメージの再ビルドを避けられます。 -- ビルドおよびリリースチェックは、tsdown の後に `scripts/check-cli-bootstrap-imports.mjs` を実行します。このガードは `dist/entry.js` と `dist/cli/run-main.js` から静的なビルド済みグラフをたどり、コマンドディスパッチ前の起動処理で Commander、プロンプト UI、undici、ログ出力などのパッケージ依存関係がインポートされている場合に失敗します。また、バンドルされた Gateway 実行チャンクを予算内に保ち、既知のコールド Gateway パスの静的インポートを拒否します。パッケージ済み CLI スモークは、ルートヘルプ、オンボードヘルプ、doctor ヘルプ、ステータス、設定スキーマ、モデル一覧コマンドもカバーします。 -- Package Acceptance のレガシー互換性は `2026.4.25`（`2026.4.25-beta.*` を含む）までに制限されています。この期限までは、ハーネスは出荷済みパッケージのメタデータ欠落のみを許容します。省略された private QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャ内の欠落したパッチファイル、永続化されていない `update.channel`、レガシー Plugin インストール記録の場所、マーケットプレイスのインストール記録永続化の欠落、および `plugins update` 中の設定メタデータ移行です。`2026.4.25` より後のパッケージでは、これらのパスは厳格な失敗になります。 -- コンテナスモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:update-channel-switch`、`test:docker:upgrade-survivor`、`test:docker:session-runtime-context`、`test:docker:agents-delete-shared-workspace`、`test:docker:gateway-network`、`test:docker:browser-cdp-snapshot`、`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 つ以上の実コンテナを起動し、より高レベルの統合パスを検証します。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` です。より大きい網羅的なスキャンを明示的に + 実行したい場合は、これらの環境変数を上書きしてください。 +- `test:docker:all` は `test:docker:live-build` でライブ Docker イメージを一度だけビルドし、`scripts/package-openclaw-for-docker.mjs` を通して OpenClaw を npm tarball として一度だけパックし、その後 2 つの `scripts/e2e/Dockerfile` イメージをビルド/再利用します。ベアなイメージは、インストール/更新/Plugin 依存関係レーン用の Node/Git ランナーだけです。これらのレーンは事前ビルド済みの tarball をマウントします。機能イメージは、ビルド済みアプリ機能レーン用に同じ tarball を `/app` にインストールします。Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーのロジックは `scripts/lib/docker-e2e-plan.mjs` にあります。`scripts/test-docker-all.mjs` が選択されたプランを実行します。集約では重み付きローカルスケジューラーを使います。`OPENCLAW_DOCKER_ALL_PARALLELISM` はプロセススロットを制御し、リソース上限は重いライブ、npm インストール、複数サービスのレーンが同時にすべて開始されないようにします。単一のレーンが有効な上限より重い場合でも、プールが空であればスケジューラーはそれを開始でき、その後キャパシティが再び利用可能になるまで単独で実行し続けます。デフォルトは 10 スロット、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`、`OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` です。Docker ホストに余力がある場合だけ、`OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` または `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` を調整してください。ランナーはデフォルトで Docker の事前チェックを実行し、古い OpenClaw E2E コンテナーを削除し、30 秒ごとにステータスを出力し、成功したレーンの所要時間を `.artifacts/docker-tests/lane-timings.json` に保存し、以後の実行ではその所要時間を使って長いレーンを先に開始します。Docker をビルドまたは実行せずに重み付きレーンマニフェストを出力するには `OPENCLAW_DOCKER_ALL_DRY_RUN=1` を使い、選択されたレーン、パッケージ/イメージ要件、認証情報の CI プランを出力するには `node scripts/test-docker-all.mjs --plan-json` を使います。 +- `Package Acceptance` は「このインストール可能な tarball はプロダクトとして動作するか」を確認する GitHub ネイティブのパッケージゲートです。`source=npm`、`source=ref`、`source=url`、または `source=artifact` から候補パッケージを 1 つ解決し、それを `package-under-test` としてアップロードし、選択された ref を再パックする代わりに、その正確な tarball に対して再利用可能な Docker E2E レーンを実行します。`workflow_ref` は信頼済みのワークフロー/ハーネススクリプトを選択し、`package_ref` は `source=ref` のときにパックするソースコミット/ブランチ/タグを選択します。これにより、現在の受け入れロジックで古い信頼済みコミットを検証できます。プロファイルは範囲の広さ順に並んでいます。`smoke` はクイックなインストール/チャンネル/エージェントに加えて Gateway/設定、`package` はパッケージ/更新/Plugin コントラクトに加えてキーレスな upgrade-survivor フィクスチャ、公開ベースラインの upgrade survivor レーン、およびほとんどの Parallels パッケージ/更新カバレッジのデフォルトのネイティブ代替、`product` は MCP チャンネル、cron/サブエージェントのクリーンアップ、OpenAI web search、OpenWebUI を追加し、`full` は OpenWebUI 付きのリリースパス Docker チャンクを実行します。`published-upgrade-survivor` では、Package Acceptance は常に `package-under-test` を候補として、`published_upgrade_survivor_baseline` を公開ベースラインとして使い、デフォルトは `openclaw@latest` です。より広いカバレッジは、正確なベースライン値で複数の実行をディスパッチしてシャーディングします。公開レーンは、組み込みの `openclaw config set` コマンドレシピでベースラインを設定し、その後レーン概要にレシピ手順を記録します。リリース検証では、リリースパス Docker チャンクが重複するパッケージ/更新/Plugin レーンをすでにカバーしているため、カスタムパッケージデルタ（`bundled-channel-deps-compat plugins-offline`）に加えて Telegram パッケージ QA を実行します。アーティファクトから生成されたターゲット指定の GitHub Docker 再実行コマンドには、以前のパッケージアーティファクト、準備済みイメージ入力、および利用可能な場合は公開 upgrade-survivor ベースラインが含まれるため、失敗したレーンはパッケージとイメージの再ビルドを避けられます。 +- ビルドおよびリリースチェックは、tsdown の後に `scripts/check-cli-bootstrap-imports.mjs` を実行します。このガードは `dist/entry.js` と `dist/cli/run-main.js` から静的なビルド済みグラフをたどり、コマンドディスパッチ前の起動処理が Commander、プロンプト UI、undici、ログ出力などのパッケージ依存関係をコマンドディスパッチ前にインポートしている場合は失敗します。また、バンドルされた Gateway 実行チャンクを予算内に保ち、既知のコールド Gateway パスの静的インポートを拒否します。パッケージ化された CLI スモークは、ルートヘルプ、オンボーディングヘルプ、doctor ヘルプ、ステータス、設定スキーマ、モデル一覧コマンドもカバーします。 +- Package Acceptance のレガシー互換性は `2026.4.25`（`2026.4.25-beta.*` を含む）までに制限されています。そのカットオフまでは、ハーネスは出荷済みパッケージのメタデータ不足だけを許容します。省略された非公開 QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャに含まれないパッチファイル、永続化されていない `update.channel`、レガシーな Plugin インストール記録の場所、マーケットプレイスのインストール記録永続化の欠落、および `plugins update` 中の設定メタデータ移行です。`2026.4.25` より後のパッケージでは、これらのパスは厳密な失敗になります。 +- コンテナースモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:update-channel-switch`、`test:docker:upgrade-survivor`、`test:docker:published-upgrade-survivor`、`test:docker:session-runtime-context`、`test:docker:agents-delete-shared-workspace`、`test:docker:gateway-network`、`test:docker:browser-cdp-snapshot`、`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 つ以上の実コンテナーを起動し、より高レベルの統合パスを検証します。 -ライブモデル Docker ランナーは、必要な CLI 認証ホームのみ（または実行が絞り込まれていない場合は対応するすべて）もバインドマウントし、実行前にコンテナホームへコピーします。これにより、外部 CLI の OAuth はホストの認証ストアを変更せずにトークンを更新できます。 +ライブモデル Docker ランナーは、必要な CLI 認証ホームだけ（または実行が絞り込まれていない場合はサポートされるすべての認証ホーム）も bind-mount し、実行前にそれらをコンテナーホームにコピーします。これにより、外部 CLI OAuth はホストの認証ストアを変更せずにトークンを更新できます。 - 直接モデル: `pnpm test:docker:live-models` (スクリプト: `scripts/test-live-models-docker.sh`) -- ACP バインドスモーク: `pnpm test:docker:live-acp-bind` (スクリプト: `scripts/test-live-acp-bind-docker.sh`; デフォルトで Claude、Codex、Gemini を対象にし、`pnpm test:docker:live-acp-bind:droid` と `pnpm test:docker:live-acp-bind:opencode` による Droid/OpenCode の厳密なカバレッジも含む) -- CLI バックエンドスモーク: `pnpm test:docker:live-cli-backend` (スクリプト: `scripts/test-live-cli-backend-docker.sh`) -- Codex アプリサーバーハーネススモーク: `pnpm test:docker:live-codex-harness` (スクリプト: `scripts/test-live-codex-harness-docker.sh`) +- ACP バインド smoke: `pnpm test:docker:live-acp-bind` (スクリプト: `scripts/test-live-acp-bind-docker.sh`; 既定で Claude、Codex、Gemini を対象にし、`pnpm test:docker:live-acp-bind:droid` と `pnpm test:docker:live-acp-bind:opencode` で Droid/OpenCode の厳密なカバレッジを提供) +- CLI バックエンド smoke: `pnpm test:docker:live-cli-backend` (スクリプト: `scripts/test-live-cli-backend-docker.sh`) +- Codex アプリサーバーハーネス smoke: `pnpm test:docker:live-codex-harness` (スクリプト: `scripts/test-live-codex-harness-docker.sh`) - Gateway + 開発エージェント: `pnpm test:docker:live-gateway` (スクリプト: `scripts/test-live-gateway-models-docker.sh`) -- オブザーバビリティスモーク: `pnpm qa:otel:smoke` は非公開 QA ソースチェックアウトレーンです。npm tarball には QA Lab が含まれないため、意図的にパッケージ Docker リリースレーンには含めていません。 -- Open WebUI ライブスモーク: `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` は、パック済みの OpenClaw tarball を Docker 内でグローバルインストールし、env-ref オンボーディングとデフォルトの Telegram を通じて OpenAI を設定し、doctor 修復で Plugin のランタイム依存関係が有効化されたことを検証し、モックした OpenAI エージェントターンを 1 回実行します。事前ビルド済み tarball は `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` で再利用でき、ホスト側の再ビルドは `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` でスキップでき、チャンネルは `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` で切り替えられます。 -- 更新チャンネル切り替えスモーク: `pnpm test:docker:update-channel-switch` は、パック済みの OpenClaw tarball を Docker 内でグローバルインストールし、パッケージ `stable` から git `dev` へ切り替え、永続化されたチャンネルと Plugin 更新後の動作を検証し、その後パッケージ `stable` に戻して更新ステータスを確認します。 -- アップグレード生存スモーク: `pnpm test:docker:upgrade-survivor` は、エージェント、チャンネル設定、Plugin 許可リスト、古い Plugin ランタイム依存関係の状態、既存のワークスペース/セッションファイルを含む汚れた旧ユーザーフィクスチャの上に、パック済みの OpenClaw tarball をインストールします。ライブプロバイダーやチャンネルキーなしでパッケージ更新と非対話 doctor を実行し、その後 local loopback Gateway を起動して、設定/状態の保持と起動/ステータスの予算を確認します。 -- セッションランタイムコンテキストスモーク: `pnpm test:docker:session-runtime-context` は、非表示ランタイムコンテキストのトランスクリプト永続化と、影響を受けた重複プロンプト書き換えブランチに対する doctor 修復を検証します。 -- Bun グローバルインストールスモーク: `bash scripts/e2e/bun-global-install-smoke.sh` は現在のツリーをパックし、隔離されたホームで `bun install -g` によりインストールし、`openclaw infer image providers --json` がハングせずに同梱画像プロバイダーを返すことを検証します。事前ビルド済み tarball は `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` で再利用でき、ホスト側のビルドは `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` でスキップでき、ビルド済み Docker イメージから `dist/` をコピーするには `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` を使用します。 -- インストーラー Docker スモーク: `bash scripts/test-install-sh-docker.sh` は、root、update、direct-npm の各コンテナー間で 1 つの npm キャッシュを共有します。更新スモークは、候補 tarball へアップグレードする前の stable ベースラインとして、デフォルトで npm `latest` を使用します。ローカルでは `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` で、GitHub では Install Smoke ワークフローの `update_baseline_version` 入力で上書きできます。非 root インストーラーチェックは隔離された npm キャッシュを保持するため、root 所有のキャッシュエントリがユーザーローカルのインストール動作を覆い隠すことはありません。ローカル再実行間で root/update/direct-npm キャッシュを再利用するには、`OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` を設定します。 -- Install Smoke CI は `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` により、重複する direct-npm グローバル更新をスキップします。直接の `npm install -g` カバレッジが必要な場合は、その env なしでスクリプトをローカル実行します。 -- エージェント共有ワークスペース削除 CLI スモーク: `pnpm test:docker:agents-delete-shared-workspace` (スクリプト: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) はデフォルトでルート Dockerfile イメージをビルドし、隔離されたコンテナーホーム内で 1 つのワークスペースを持つ 2 つのエージェントをシードし、`agents delete --json` を実行し、有効な JSON とワークスペース保持動作を検証します。インストールスモークイメージを再利用するには、`OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` を使用します。 -- Gateway ネットワーク (2 コンテナー、WS 認証 + ヘルス): `pnpm test:docker:gateway-network` (スクリプト: `scripts/e2e/gateway-network-docker.sh`) -- ブラウザー CDP スナップショットスモーク: `pnpm test:docker:browser-cdp-snapshot` (スクリプト: `scripts/e2e/browser-cdp-snapshot-docker.sh`) は、ソース E2E イメージと Chromium レイヤーをビルドし、生の CDP で Chromium を起動し、`browser doctor --deep` を実行し、CDP ロールスナップショットがリンク URL、カーソルで昇格されたクリック可能要素、iframe 参照、フレームメタデータをカバーすることを検証します。 -- 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` に引き上げることを検証し、その後プロバイダースキーマの拒否を強制して、生の詳細が Gateway ログに現れることを確認します。 -- MCP チャンネルブリッジ (シード済み Gateway + stdio ブリッジ + 生の Claude 通知フレームスモーク): `pnpm test:docker:mcp-channels` (スクリプト: `scripts/e2e/mcp-channels-docker.sh`) -- Pi バンドル MCP ツール (実 stdio MCP サーバー + 埋め込み Pi プロファイル許可/拒否スモーク): `pnpm test:docker:pi-bundle-mcp-tools` (スクリプト: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Cron/サブエージェント MCP クリーンアップ (実 Gateway + 隔離 cron と 1 回限りのサブエージェント実行後の stdio MCP 子プロセスの破棄): `pnpm test:docker:cron-mcp-cleanup` (スクリプト: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugin群 (インストールスモーク、ClawHub kitchen-sink インストール/アンインストール、マーケットプレイス更新、Claude バンドルの有効化/検査): `pnpm test:docker:plugins` (スクリプト: `scripts/e2e/plugins-docker.sh`) - ClawHub ブロックをスキップするには `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` を設定し、デフォルトの kitchen-sink パッケージ/ランタイムペアを上書きするには `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` と `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` を使用します。`OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` がない場合、テストは hermetic なローカル ClawHub フィクスチャサーバーを使用します。 -- Plugin 更新変更なしスモーク: `pnpm test:docker:plugin-update` (スクリプト: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- 設定リロードメタデータスモーク: `pnpm test:docker:config-reload` (スクリプト: `scripts/e2e/config-reload-source-docker.sh`) -- 同梱 Plugin ランタイム依存関係: `pnpm test:docker:bundled-channel-deps` は、デフォルトで小さな Docker ランナーイメージをビルドし、ホスト上で OpenClaw を一度ビルドしてパックし、その tarball を各 Linux インストールシナリオにマウントします。イメージを再利用するには `OPENCLAW_SKIP_DOCKER_BUILD=1` を使用し、新しいローカルビルド後にホスト側の再ビルドをスキップするには `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` を使用し、既存の tarball を指すには `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` を使用します。完全な Docker 集約とリリースパスの bundled-channel チャンクは、この tarball を一度事前パックし、その後 Telegram、Discord、Slack、Feishu、memory-lancedb、ACPX の個別更新レーンを含む独立レーンへ同梱チャンネルチェックを分割します。リリースチャンクは、チャンネルスモーク、更新ターゲット、セットアップ/ランタイム契約を `bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b`、`bundled-channels-contracts` に分割します。集約 `bundled-channels` チャンクは手動再実行用に引き続き利用できます。リリースワークフローは、プロバイダーインストーラーチャンクと同梱 Plugin のインストール/アンインストールチャンクも分割します。従来の `package-update`、`plugins-runtime`、`plugins-integrations` チャンクは、手動再実行用の集約エイリアスとして残ります。同梱レーンを直接実行する際にチャンネルマトリクスを絞るには `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` を使用し、更新シナリオを絞るには `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` を使用します。シナリオごとの Docker 実行はデフォルトで `OPENCLAW_BUNDLED_CHANNEL_DOCKER_RUN_TIMEOUT=900s` です。複数ターゲット更新シナリオはデフォルトで `OPENCLAW_BUNDLED_CHANNEL_UPDATE_DOCKER_RUN_TIMEOUT=2400s` です。このレーンは、`channels..enabled=false` と `plugins.entries..enabled=false` が doctor/ランタイム依存関係修復を抑制することも検証します。 -- 反復作業中に無関係なシナリオを無効化して、同梱 Plugin ランタイム依存関係を絞ります。例: +- 可観測性 smoke: `pnpm qa:otel:smoke` はプライベートな QA ソースチェックアウトレーンです。npm tarball では QA Lab が省かれるため、意図的にパッケージ Docker リリースレーンには含めていません。 +- Open WebUI live smoke: `pnpm test:docker:openwebui` (スクリプト: `scripts/e2e/openwebui-docker.sh`) +- オンボーディング ウィザード (TTY、完全なスキャフォールディング): `pnpm test:docker:onboard` (スクリプト: `scripts/e2e/onboard-docker.sh`) +- Npm tarball オンボーディング/channel/agent smoke: `pnpm test:docker:npm-onboard-channel-agent` は、パック済みの OpenClaw tarball を Docker 内でグローバルにインストールし、env-ref オンボーディングで OpenAI を構成し、既定で Telegram も構成し、doctor 修復によって Plugin ランタイム依存関係が有効化されたことを検証し、モックされた OpenAI agent ターンを 1 回実行します。事前ビルド済み tarball を `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` で再利用するか、`OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` でホスト側の再ビルドをスキップするか、`OPENCLAW_NPM_ONBOARD_CHANNEL=discord` で channel を切り替えます。 +- 更新 channel 切り替え smoke: `pnpm test:docker:update-channel-switch` は、パック済みの OpenClaw tarball を Docker 内でグローバルにインストールし、パッケージ `stable` から git `dev` へ切り替え、永続化された channel と Plugin の更新後の動作を検証し、その後パッケージ `stable` に戻して更新ステータスを確認します。 +- アップグレード生存 smoke: `pnpm test:docker:upgrade-survivor` は、agent、channel 設定、Plugin allowlist、古い Plugin runtime-deps 状態、既存の workspace/session ファイルを持つ、汚れた old-user fixture の上にパック済みの OpenClaw tarball をインストールします。live provider や channel keys なしでパッケージ更新と非対話型 doctor を実行し、その後 loopback Gateway を起動して、設定/状態の保持と起動/ステータスの予算を確認します。 +- 公開済みアップグレード生存 smoke: `pnpm test:docker:published-upgrade-survivor` は既定で `openclaw@latest` をインストールし、現実的な既存ユーザーファイルを seed し、焼き込み済み command recipe でそのベースラインを構成し、結果の設定を検証し、その公開済みインストールを候補 tarball へ更新し、非対話型 doctor を実行し、`.artifacts/upgrade-survivor/summary.json` を書き込み、その後 loopback Gateway を起動して、構成済み intent、状態の保持、起動、ステータスの予算を確認します。`OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` でベースラインを上書きします。Package Acceptance は同じ値を `published_upgrade_survivor_baseline` として公開します。 +- Session ランタイムコンテキスト smoke: `pnpm test:docker:session-runtime-context` は、隠しランタイムコンテキストの transcript 永続化と、影響を受ける重複 prompt-rewrite ブランチの doctor 修復を検証します。 +- Bun グローバルインストール smoke: `bash scripts/e2e/bun-global-install-smoke.sh` は現在のツリーをパックし、隔離された home 内で `bun install -g` によりインストールし、`openclaw infer image providers --json` がハングせずにバンドル済み image provider を返すことを検証します。事前ビルド済み tarball を `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` で再利用するか、`OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` でホストビルドをスキップするか、`OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` でビルド済み Docker image から `dist/` をコピーします。 +- インストーラー Docker smoke: `bash scripts/test-install-sh-docker.sh` は、root、update、direct-npm の各 container 間で 1 つの npm cache を共有します。Update smoke は、候補 tarball にアップグレードする前の stable ベースラインとして、既定で npm `latest` を使います。ローカルでは `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` で、GitHub では Install Smoke workflow の `update_baseline_version` 入力で上書きします。非 root インストーラーチェックは隔離された npm cache を保持するため、root 所有の cache entry が user-local install の挙動を隠しません。ローカル再実行間で root/update/direct-npm cache を再利用するには `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` を設定します。 +- Install Smoke CI は `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` で重複する direct-npm グローバル更新をスキップします。直接の `npm install -g` カバレッジが必要な場合は、その env なしでローカルにスクリプトを実行します。 +- Agents delete shared workspace CLI smoke: `pnpm test:docker:agents-delete-shared-workspace` (スクリプト: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) は既定でルート Dockerfile image をビルドし、隔離された container home に 1 つの workspace を持つ 2 つの agent を seed し、`agents delete --json` を実行し、有効な JSON と workspace 保持の挙動を検証します。`OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` で install-smoke image を再利用します。 +- Gateway networking (2 つの container、WS auth + health): `pnpm test:docker:gateway-network` (スクリプト: `scripts/e2e/gateway-network-docker.sh`) +- Browser CDP snapshot smoke: `pnpm test:docker:browser-cdp-snapshot` (スクリプト: `scripts/e2e/browser-cdp-snapshot-docker.sh`) はソース E2E image と Chromium layer をビルドし、raw CDP で Chromium を起動し、`browser doctor --deep` を実行し、CDP role snapshot が link URL、cursor-promoted clickable、iframe ref、frame metadata をカバーすることを検証します。 +- OpenAI Responses web_search minimal reasoning 回帰: `pnpm test:docker:openai-web-search-minimal` (スクリプト: `scripts/e2e/openai-web-search-minimal-docker.sh`) は、Gateway 経由でモック OpenAI server を実行し、`web_search` が `reasoning.effort` を `minimal` から `low` へ引き上げることを検証し、その後 provider schema reject を強制して、生の detail が Gateway log に現れることを確認します。 +- MCP channel bridge (seed 済み Gateway + stdio bridge + raw 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 + 隔離 cron と one-shot subagent 実行後の stdio MCP child teardown): `pnpm test:docker:cron-mcp-cleanup` (スクリプト: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (install smoke、ClawHub kitchen-sink install/uninstall、marketplace update、Claude-bundle enable/inspect): `pnpm test:docker:plugins` (スクリプト: `scripts/e2e/plugins-docker.sh`) + ClawHub ブロックをスキップするには `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` を設定するか、既定の kitchen-sink package/runtime pair を `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` と `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` で上書きします。`OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` がない場合、テストは hermetic なローカル ClawHub fixture server を使います。 +- 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 runtime deps: `pnpm test:docker:bundled-channel-deps` は既定で小さな Docker runner image をビルドし、ホスト上で OpenClaw を 1 回ビルドしてパックし、その tarball を各 Linux install scenario に mount します。`OPENCLAW_SKIP_DOCKER_BUILD=1` で image を再利用し、新しいローカルビルド後に `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` でホスト側の再ビルドをスキップするか、`OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` で既存の tarball を指定します。完全な Docker aggregate と release-path bundled-channel chunk はこの tarball を 1 回だけ事前パックし、その後 Telegram、Discord、Slack、Feishu、memory-lancedb、ACPX 向けの個別 update lane を含め、バンドル済み channel チェックを独立した lane に shard します。Release chunk は channel smoke、update target、setup/runtime contract を `bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b`、`bundled-channels-contracts` に分割します。aggregate の `bundled-channels` chunk は手動再実行用として引き続き利用できます。Release workflow は provider installer chunk とバンドル済み Plugin install/uninstall chunk も分割します。従来の `package-update`、`plugins-runtime`、`plugins-integrations` chunk は手動再実行用の aggregate alias として残ります。バンドル済み lane を直接実行する際に channel matrix を絞るには `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` を使い、update scenario を絞るには `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` を使います。scenario ごとの Docker 実行は既定で `OPENCLAW_BUNDLED_CHANNEL_DOCKER_RUN_TIMEOUT=900s` です。multi-target update scenario は既定で `OPENCLAW_BUNDLED_CHANNEL_UPDATE_DOCKER_RUN_TIMEOUT=2400s` です。この lane は、`channels..enabled=false` と `plugins.entries..enabled=false` が doctor/runtime-dependency repair を抑止することも検証します。 +- 反復中は、たとえば次のように無関係な scenario を無効化して、バンドル済み Plugin runtime deps を絞り込みます: `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`. -共有機能イメージを手動で事前ビルドして再利用するには: +共有 functional image を手動で事前ビルドして再利用するには: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -`OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` のようなスイート固有のイメージ上書きは、設定されている場合は引き続き優先されます。`OPENCLAW_SKIP_DOCKER_BUILD=1` がリモート共有イメージを指している場合、スクリプトはそれがローカルにまだ存在しなければ pull します。QR とインストーラー Docker テストは、共有ビルド済みアプリランタイムではなくパッケージ/インストール動作を検証するため、独自の Dockerfile を保持します。 +`OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` などの suite 固有の image override は、設定されている場合は引き続き優先されます。`OPENCLAW_SKIP_DOCKER_BUILD=1` が remote shared image を指している場合、まだローカルに存在しなければスクリプトが pull します。QR と installer の Docker テストは、共有 built-app runtime ではなく package/install の挙動を検証するため、独自の Dockerfile を保持します。 -ライブモデル Docker ランナーは、現在のチェックアウトも読み取り専用でバインドマウントし、 -コンテナ内の一時作業ディレクトリへステージングします。これによりランタイム -イメージをスリムに保ちながら、正確なローカルソース/設定に対して Vitest を実行できます。 -ステージング手順では、Docker ライブ実行がマシン固有の成果物のコピーに -何分も費やさないよう、`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、アプリローカルの `.build`、 -Gradle 出力ディレクトリなどの大きなローカル専用キャッシュとアプリのビルド出力をスキップします。 -`OPENCLAW_SKIP_CHANNELS=1` も設定されるため、Gateway ライブプローブは -コンテナ内で実際の Telegram/Discord などのチャネルワーカーを起動しません。 -`test:docker:live-models` は引き続き `pnpm test:live` を実行するため、 -その Docker レーンから Gateway ライブカバレッジを絞り込む、または除外する必要がある場合は +ライブモデルの Docker ランナーは、現在のチェックアウトも読み取り専用で bind mount し、 +コンテナ内の一時作業ディレクトリへステージします。これにより、ランタイム +イメージをスリムに保ちながら、正確なローカルのソース/設定に対して Vitest を実行できます。 +ステージング手順では、`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、アプリローカルの `.build` や +Gradle 出力ディレクトリなど、大きなローカル専用キャッシュやアプリのビルド出力をスキップするため、 +Docker ライブ実行がマシン固有の成果物のコピーに何分も費やすことはありません。 +また、`OPENCLAW_SKIP_CHANNELS=1` も設定するため、Gateway のライブプローブが +コンテナ内で実際の Telegram/Discord などのチャネルワーカーを開始することはありません。 +`test:docker:live-models` は引き続き `pnpm test:live` を実行するため、その Docker レーンから +Gateway ライブカバレッジを絞り込んだり除外したりする必要がある場合は、 `OPENCLAW_LIVE_GATEWAY_*` も渡してください。 -`test:docker:openwebui` は、より上位の互換性スモークテストです。OpenAI 互換 HTTP エンドポイントを有効にした -OpenClaw Gateway コンテナを起動し、その Gateway に向けて固定された Open WebUI コンテナを起動し、 -Open WebUI 経由でサインインし、`/api/models` が `openclaw/default` を公開していることを検証したうえで、 +`test:docker:openwebui` は、より高レベルな互換性 smoke です。OpenAI 互換の HTTP エンドポイントを有効にした +OpenClaw Gateway コンテナを起動し、その Gateway に対して固定された Open WebUI コンテナを起動し、 +Open WebUI 経由でサインインし、`/api/models` が `openclaw/default` を公開していることを検証してから、 Open WebUI の `/api/chat/completions` プロキシ経由で実際のチャットリクエストを送信します。 -初回実行は目に見えて遅くなることがあります。Docker が -Open WebUI イメージを pull する必要があり、Open WebUI が自身のコールドスタートセットアップを完了する必要があるためです。 -このレーンでは利用可能なライブモデルキーが必要で、`OPENCLAW_PROFILE_FILE` -（デフォルトは `~/.profile`）が Docker 化実行でそれを提供する主な方法です。 +初回実行は、Docker が Open WebUI イメージを pull する必要があったり、Open WebUI が自身のコールドスタート設定を完了する必要があったりするため、 +目に見えて遅くなることがあります。 +このレーンは使用可能なライブモデルキーを想定しており、Docker 化された実行でそれを提供する主な方法は +`OPENCLAW_PROFILE_FILE`（デフォルトは `~/.profile`）です。 成功した実行では、`{ "ok": true, "model": "openclaw/default", ... }` のような小さな JSON ペイロードが出力されます。 `test:docker:mcp-channels` は意図的に決定的であり、実際の -Telegram、Discord、iMessage アカウントは不要です。シード済み Gateway -コンテナを起動し、`openclaw mcp serve` を生成する 2 つ目のコンテナを起動したうえで、 -ルーティングされた会話の検出、トランスクリプト読み取り、添付ファイルメタデータ、 -ライブイベントキューの挙動、アウトバウンド送信ルーティング、実際の stdio MCP ブリッジ越しの Claude スタイルのチャネル + -権限通知を検証します。通知チェックは -raw stdio MCP フレームを直接検査するため、このスモークテストは -特定のクライアント SDK がたまたま表に出す内容だけでなく、ブリッジが実際に出力する内容を検証します。 -`test:docker:pi-bundle-mcp-tools` は決定的で、ライブ -モデルキーは不要です。リポジトリの Docker イメージをビルドし、コンテナ内で実際の stdio MCP プローブサーバーを起動し、 -埋め込み Pi バンドル MCP ランタイムを通じてそのサーバーを実体化し、 -ツールを実行したうえで、`coding` と `messaging` が -`bundle-mcp` ツールを保持し、`minimal` と `tools.deny: ["bundle-mcp"]` がそれらをフィルターすることを検証します。 -`test:docker:cron-mcp-cleanup` は決定的で、ライブモデル -キーは不要です。実際の stdio MCP プローブサーバーを持つシード済み Gateway を起動し、 -隔離された Cron ターンと `/subagents spawn` のワンショット子ターンを実行したうえで、 +Telegram、Discord、iMessage アカウントを必要としません。seed 済みの Gateway +コンテナを起動し、`openclaw mcp serve` を spawn する 2 つ目のコンテナを起動してから、 +ルーティングされた会話の検出、トランスクリプト読み取り、添付ファイルのメタデータ、 +ライブイベントキューの動作、アウトバウンド送信ルーティング、実際の stdio MCP ブリッジ越しの Claude 形式のチャネル + +権限通知を検証します。通知チェックは生の stdio MCP フレームを直接検査するため、 +smoke は特定のクライアント SDK がたまたま表面化する内容だけでなく、 +ブリッジが実際に emit する内容を検証します。 +`test:docker:pi-bundle-mcp-tools` は決定的であり、ライブモデルキーを必要としません。 +リポジトリの Docker イメージをビルドし、コンテナ内で実際の stdio MCP プローブサーバーを起動し、 +埋め込み Pi バンドル MCP ランタイムを通じてそのサーバーを具現化し、 +ツールを実行してから、`minimal` と `tools.deny: ["bundle-mcp"]` がそれらをフィルターする一方で、 +`coding` と `messaging` が `bundle-mcp` ツールを保持することを検証します。 +`test:docker:cron-mcp-cleanup` は決定的であり、ライブモデルキーを必要としません。 +実際の stdio MCP プローブサーバーを備えた seed 済み Gateway を起動し、 +分離された Cron ターンと `/subagents spawn` の 1 回限りの子ターンを実行してから、 各実行後に MCP 子プロセスが終了することを検証します。 -手動 ACP 自然言語スレッドスモーク（CI 対象外）: +手動 ACP 平易言語スレッド smoke（CI ではない）: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` - このスクリプトは回帰/デバッグワークフロー用に残してください。ACP スレッドルーティング検証で再び必要になる可能性があるため、削除しないでください。 @@ -608,59 +652,58 @@ raw stdio MCP フレームを直接検査するため、このスモークテス - `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 された環境変数だけを検証します。一時設定/ワークスペースディレクトリを使い、外部 CLI 認証マウントは使いません -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）は、Docker 内のキャッシュ済み CLI インストール用に `/home/node/.npm-global` にマウントされます -- `$HOME` 配下の外部 CLI 認証ディレクトリ/ファイルは `/host-auth...` 配下に読み取り専用でマウントされ、その後テスト開始前に `/home/node/...` へコピーされます - - デフォルトディレクトリ: `.minimax` - - デフォルトファイル: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 絞り込んだプロバイダー実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推定される必要なディレクトリ/ファイルのみをマウントします - - `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストで手動上書きします -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` で実行を絞り込みます -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` でコンテナ内のプロバイダーをフィルターします -- `OPENCLAW_SKIP_DOCKER_BUILD=1` で、リビルドが不要な再実行に既存の `openclaw:local-live` イメージを再利用します -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` で、認証情報が環境変数ではなくプロフィールストアから来ることを保証します -- `OPENCLAW_OPENWEBUI_MODEL=...` で、Open WebUI スモークテスト用に Gateway が公開するモデルを選択します -- `OPENCLAW_OPENWEBUI_PROMPT=...` で、Open WebUI スモークテストが使う nonce チェックプロンプトを上書きします -- `OPENWEBUI_IMAGE=...` で、固定された Open WebUI イメージタグを上書きします +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` は、一時的な設定/ワークスペースディレクトリを使用し、外部 CLI auth マウントなしで、`OPENCLAW_PROFILE_FILE` から source された環境変数のみを検証します +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）は Docker 内のキャッシュ済み CLI インストール用に `/home/node/.npm-global` にマウントされます +- `$HOME` 配下の外部 CLI auth ディレクトリ/ファイルは `/host-auth...` 配下に読み取り専用でマウントされ、テスト開始前に `/home/node/...` へコピーされます + - デフォルトのディレクトリ: `.minimax` + - デフォルトのファイル: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` + - 絞り込まれたプロバイダー実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推論された必要なディレクトリ/ファイルのみをマウントします + - `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストで手動上書きできます +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` は実行を絞り込みます +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` はコンテナ内のプロバイダーをフィルターします +- `OPENCLAW_SKIP_DOCKER_BUILD=1` は、再ビルドが不要な再実行で既存の `openclaw:local-live` イメージを再利用します +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` は、認証情報が環境変数ではなく profile store から取得されることを保証します +- `OPENCLAW_OPENWEBUI_MODEL=...` は、Open WebUI smoke 用に Gateway が公開するモデルを選択します +- `OPENCLAW_OPENWEBUI_PROMPT=...` は、Open WebUI smoke で使用される nonce チェックプロンプトを上書きします +- `OPENWEBUI_IMAGE=...` は、固定された Open WebUI イメージタグを上書きします -## ドキュメント健全性 +## Docs 健全性 -ドキュメント編集後はドキュメントチェックを実行します: `pnpm check:docs`. -ページ内見出しチェックも必要な場合は、Mintlify の完全なアンカー検証を実行します: `pnpm docs:check-links:anchors`. +ドキュメント編集後に docs チェックを実行します: `pnpm check:docs`。 +ページ内見出しチェックも必要な場合は、完全な Mintlify アンカー検証を実行します: `pnpm docs:check-links:anchors`。 -## オフライン回帰（CI で安全に実行可能） +## オフライン回帰（CI セーフ） -これらは実プロバイダーを使わない「実パイプライン」回帰テストです: +これらは実プロバイダーなしの「実パイプライン」回帰です: -- Gateway ツール呼び出し（モック OpenAI、実際の Gateway + エージェントループ）: `src/gateway/gateway.test.ts`（ケース: 「Gateway エージェントループを介して、モック OpenAI ツール呼び出しをエンドツーエンドで実行する」） -- Gateway ウィザード（WS `wizard.start`/`wizard.next`、設定を書き込み + 認証を強制）: `src/gateway/gateway.test.ts`（ケース: 「ws 経由でウィザードを実行し、認証トークン設定を書き込む」） +- 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`、設定書き込み + auth 適用）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） -## エージェント信頼性評価（Skills） +## エージェント信頼性 eval（Skills） -すでに「エージェント信頼性評価」のように振る舞う CI で安全に実行できるテストがいくつかあります: +「エージェント信頼性 eval」のように動作する CI セーフなテストは、すでにいくつかあります: -- 実際の Gateway + エージェントループを通したモックツール呼び出し（`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) を参照）: -- **判断:** プロンプトに Skills が一覧されている場合、エージェントは適切なスキルを選ぶ（または無関係なものを避ける）か？ -- **準拠:** エージェントは使用前に `SKILL.md` を読み、必須手順/引数に従うか？ -- **ワークフロー契約:** ツール順序、セッション履歴の引き継ぎ、サンドボックス境界をアサートする複数ターンのシナリオ。 +- **意思決定:** Skills がプロンプトに列挙されたとき、エージェントは適切な skill を選ぶ（または無関係なものを避ける）か？ +- **準拠:** エージェントは使用前に `SKILL.md` を読み、必要な手順/引数に従うか？ +- **ワークフロー契約:** ツール順序、セッション履歴の引き継ぎ、サンドボックス境界を assert するマルチターンシナリオ。 -今後の評価では、まず決定的であることを優先してください: +将来の eval は、まず決定的であるべきです: -- モックプロバイダーを使ってツール呼び出し + 順序、スキルファイル読み取り、セッション配線をアサートするシナリオランナー。 -- Skills に焦点を当てた小さなシナリオスイート（使用と回避、ゲーティング、プロンプトインジェクション）。 -- CI で安全に実行できるスイートが整ってからのみ、任意のライブ評価（オプトイン、環境変数でゲート）。 +- モックプロバイダーを使ってツール呼び出し + 順序、skill ファイル読み取り、セッション配線を assert するシナリオランナー。 +- skill に焦点を当てた小さなシナリオスイート（使用 vs 回避、ゲーティング、プロンプトインジェクション）。 +- CI セーフなスイートが整った後に限り、任意のライブ eval（opt-in、env-gated）。 ## 契約テスト（Plugin とチャネル形状） -契約テストは、登録済みのすべての Plugin とチャネルがそれぞれの -インターフェイス契約に準拠していることを検証します。発見されたすべての Plugin を反復し、 -形状と挙動のアサーションスイートを実行します。デフォルトの `pnpm test` ユニットレーンは -これらの共有境界ファイルとスモークファイルを意図的にスキップします。共有チャネルまたはプロバイダーサーフェスを触る場合は、 -契約コマンドを明示的に実行してください。 +契約テストは、登録済みのすべての Plugin とチャネルがその +インターフェイス契約に準拠していることを検証します。検出されたすべての Plugin を反復し、 +形状と動作の assert スイートを実行します。デフォルトの `pnpm test` unit レーンは、これらの共有 seam と smoke ファイルを意図的に +スキップします。共有チャネルまたはプロバイダー surface に触れる場合は、契約コマンドを明示的に実行してください。 ### コマンド @@ -672,56 +715,56 @@ Skills でまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参 `src/channels/plugins/contracts/*.contract.test.ts` にあります: -- **Plugin** - 基本的な Plugin 形状（id、name、capabilities） -- **セットアップ** - セットアップウィザード契約 -- **セッションバインディング** - セッションバインディングの挙動 -- **アウトバウンドペイロード** - メッセージペイロード構造 -- **インバウンド** - インバウンドメッセージ処理 -- **アクション** - チャネルアクションハンドラー -- **スレッド化** - スレッド ID 処理 -- **ディレクトリ** - ディレクトリ/名簿 API -- **グループポリシー** - グループポリシーの強制 +- **plugin** - 基本的な Plugin 形状（id、name、capabilities） +- **setup** - セットアップウィザード契約 +- **session-binding** - セッションバインディング動作 +- **outbound-payload** - メッセージペイロード構造 +- **inbound** - インバウンドメッセージ処理 +- **actions** - チャネルアクションハンドラー +- **threading** - スレッド ID 処理 +- **directory** - ディレクトリ/roster API +- **group-policy** - グループポリシー適用 ### プロバイダーステータス契約 `src/plugins/contracts/*.contract.test.ts` にあります。 -- **ステータス** - チャネルステータスプローブ -- **レジストリ** - Plugin レジストリ形状 +- **status** - チャネルステータスプローブ +- **registry** - Plugin レジストリ形状 ### プロバイダー契約 `src/plugins/contracts/*.contract.test.ts` にあります: -- **認証** - 認証フロー契約 -- **認証選択** - 認証の選択/選定 -- **カタログ** - モデルカタログ API -- **検出** - Plugin 検出 -- **ローダー** - Plugin 読み込み -- **ランタイム** - プロバイダーランタイム -- **形状** - Plugin 形状/インターフェイス -- **ウィザード** - セットアップウィザード +- **auth** - auth フロー契約 +- **auth-choice** - auth choice/selection +- **catalog** - モデルカタログ API +- **discovery** - Plugin 検出 +- **loader** - Plugin 読み込み +- **runtime** - プロバイダーランタイム +- **shape** - Plugin 形状/インターフェイス +- **wizard** - セットアップウィザード -### 実行するタイミング +### 実行タイミング -- plugin-sdk のエクスポートまたはサブパスを変更した後 +- plugin-sdk の export または subpath を変更した後 - チャネルまたはプロバイダー Plugin を追加または変更した後 - Plugin 登録または検出をリファクタリングした後 契約テストは CI で実行され、実際の API キーは不要です。 -## 回帰テストの追加（ガイダンス） +## 回帰の追加（ガイダンス） -ライブで発見されたプロバイダー/モデル問題を修正する場合: +ライブで発見されたプロバイダー/モデルの問題を修正する場合: -- 可能であれば CI で安全に実行できる回帰テストを追加します（モック/スタブプロバイダー、または正確なリクエスト形状変換の捕捉） -- 本質的にライブ専用（レート制限、認証ポリシー）の場合は、ライブテストを狭く保ち、環境変数によるオプトインにします -- バグを捕捉する最小レイヤーを狙うことを優先します: - - プロバイダーリクエスト変換/リプレイのバグ → 直接のモデルテスト - - Gateway セッション/履歴/ツールパイプラインのバグ → Gateway ライブスモークまたは CI で安全に実行できる Gateway モックテスト -- SecretRef トラバーサルガードレール: - - `src/secrets/exec-secret-ref-id-parity.test.ts` は、レジストリメタデータ（`listSecretTargetRegistryEntries()`）から SecretRef クラスごとにサンプル対象を 1 つ導出し、その後トラバーサルセグメントの exec ID が拒否されることをアサートします。 - - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef ターゲットファミリーを追加する場合は、そのテストの `classifyTargetClass` を更新してください。このテストは未分類のターゲット ID で意図的に失敗するため、新しいクラスが静かにスキップされることはありません。 +- 可能であれば CI セーフな回帰を追加します（モック/スタブプロバイダー、または正確なリクエスト形状変換を capture） +- 本質的にライブ専用の場合（レート制限、auth ポリシー）は、ライブテストを狭く保ち、環境変数で opt-in にします +- バグを捕捉する最小の層を対象にすることを優先します: + - プロバイダーリクエスト変換/replay バグ → 直接の models テスト + - Gateway セッション/履歴/ツールパイプラインバグ → Gateway ライブ smoke または CI セーフな Gateway モックテスト +- SecretRef traversal guardrail: + - `src/secrets/exec-secret-ref-id-parity.test.ts` は、レジストリメタデータ（`listSecretTargetRegistryEntries()`）から SecretRef クラスごとにサンプリングされたターゲットを 1 つ導出し、traversal-segment exec id が拒否されることを assert します。 + - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef ターゲットファミリーを追加する場合は、そのテストの `classifyTargetClass` を更新してください。このテストは、分類されていないターゲット ID で意図的に失敗するため、新しいクラスが静かにスキップされることはありません。 ## 関連 diff --git a/docs/ja-JP/plugins/codex-harness.md b/docs/ja-JP/plugins/codex-harness.md index 0fb0408e4..1e5179679 100644 --- a/docs/ja-JP/plugins/codex-harness.md +++ b/docs/ja-JP/plugins/codex-harness.md @@ -1,135 +1,28 @@ --- read_when: - - バンドルされている Codex アプリサーバーハーネスを使用したい場合 - - Codex ハーネス設定の例が必要です - - Codex のみのデプロイで、PI にフォールバックするのではなく失敗させたい場合 -summary: バンドルされた Codex app-server ハーネスを通じて OpenClaw の埋め込みエージェントターンを実行する + - 同梱の Codex app-server ハーネスを使用したい場合 + - Codex ハーネス設定例が必要です + - Codex のみのデプロイでは、PI にフォールバックするのではなく失敗するようにしたい +summary: 同梱の Codex app-server ハーネスを介して OpenClaw の組み込みエージェントターンを実行する title: Codex ハーネス x-i18n: - generated_at: "2026-04-30T20:05:45Z" + generated_at: "2026-05-01T05:02:10Z" model: gpt-5.5 provider: openai - source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f + source_hash: 740e8fa9e6f4a737dfd250fe26b85865a7f7e40839b41e879e9224a45cbe8d72 source_path: plugins/codex-harness.md workflow: 16 --- -同梱の `codex` Plugin により、OpenClaw は組み込みの PI ハーネスではなく Codex app-server を通じて埋め込みエージェントターンを実行できます。 +バンドルされた `codex` Plugin により、OpenClaw は組み込み PI ハーネスの代わりに Codex app-server を通じて埋め込みエージェントターンを実行できます。 -低レベルのエージェントセッション、つまりモデル検出、ネイティブスレッドの再開、ネイティブ Compaction、app-server 実行を Codex に所有させたい場合に使用します。OpenClaw は引き続き、チャットチャネル、セッションファイル、モデル選択、ツール、承認、メディア配信、表示されるトランスクリプトミラーを所有します。 +低レベルのエージェントセッションを Codex に所有させたい場合に使います。モデル検出、ネイティブスレッドの再開、ネイティブ Compaction、app-server 実行が対象です。OpenClaw は引き続き、チャットチャネル、セッションファイル、モデル選択、ツール、承認、メディア配信、表示されるトランスクリプトのミラーを所有します。 -全体像を把握したい場合は、[エージェントランタイム](/ja-JP/concepts/agent-runtimes) から始めてください。短く言えば、`openai/gpt-5.5` はモデル参照、`codex` はランタイムであり、Telegram、Discord、Slack、または別のチャネルが通信サーフェスのままです。 +方向性を把握したい場合は、[エージェントランタイム](/ja-JP/concepts/agent-runtimes) から始めてください。短く言うと、`openai/gpt-5.5` がモデル参照、`codex` がランタイムであり、Telegram、Discord、Slack、または別のチャネルが通信面のままです。 -## この Plugin が変更すること +## クイック設定 -同梱の `codex` Plugin は、複数の独立した機能を提供します。 - -| 機能 | 使い方 | 何をするか | -| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| ネイティブ組み込みランタイム | `agentRuntime.id: "codex"` | Codex app-server を通じて OpenClaw の埋め込みエージェントターンを実行します。 | -| ネイティブチャット制御コマンド | `/codex bind`, `/codex resume`, `/codex steer`, ... | メッセージング会話から Codex app-server スレッドをバインドおよび制御します。 | -| Codex app-server プロバイダー/カタログ | `codex` 内部、ハーネス経由で公開 | ランタイムが app-server モデルを検出および検証できるようにします。 | -| Codex メディア理解パス | `codex/*` 画像モデル互換パス | 対応する画像理解モデル向けに境界付きの Codex app-server ターンを実行します。 | -| ネイティブフックリレー | Codex ネイティブイベント周辺の Plugin フック | 対応する Codex ネイティブのツール/完了イベントを OpenClaw が監視/ブロックできるようにします。 | - -この Plugin を有効にすると、これらの機能が利用可能になります。次のことは**行いません**。 - -- すべての OpenAI モデルで Codex を使い始める -- `openai-codex/*` モデル参照をネイティブランタイムに変換する -- ACP/acpx をデフォルトの Codex パスにする -- すでに PI ランタイムを記録した既存セッションをホットスイッチする -- OpenClaw のチャネル配信、セッションファイル、認証プロファイル保存、またはメッセージルーティングを置き換える - -同じ Plugin は、ネイティブの `/codex` チャット制御コマンドサーフェスも所有します。Plugin が有効で、ユーザーがチャットから Codex スレッドのバインド、再開、ステアリング、停止、または調査を求めた場合、エージェントは ACP よりも `/codex ...` を優先するべきです。ユーザーが ACP/acpx を求めている場合、または ACP Codex アダプターをテストしている場合、ACP は明示的なフォールバックのままです。 - -ネイティブ Codex ターンでは、OpenClaw Plugin フックが公開互換レイヤーとして維持されます。これらはプロセス内の OpenClaw フックであり、Codex の `hooks.json` コマンドフックではありません。 - -- `before_prompt_build` -- `before_compaction`, `after_compaction` -- `llm_input`, `llm_output` -- `before_tool_call`, `after_tool_call` -- `before_message_write`（ミラーされたトランスクリプトレコード用） -- Codex `Stop` リレーを通じた `before_agent_finalize` -- `agent_end` - -Plugin は、ランタイム中立のツール結果ミドルウェアも登録でき、OpenClaw がツールを実行した後、結果が Codex に返される前に OpenClaw の動的ツール結果を書き換えられます。これは公開 `tool_result_persist` Plugin フックとは別のものです。このフックは、OpenClaw が所有するトランスクリプトのツール結果書き込みを変換します。 - -Plugin フックのセマンティクス自体については、[Plugin フック](/ja-JP/plugins/hooks) と [Plugin ガード動作](/ja-JP/tools/plugin) を参照してください。 - -ハーネスはデフォルトで無効です。新しい設定では、OpenAI モデル参照を `openai/gpt-*` として正規のまま維持し、ネイティブ app-server 実行が必要な場合は `agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を明示的に強制するべきです。レガシーの `codex/*` モデル参照は互換性のために引き続きハーネスを自動選択しますが、ランタイムに裏付けられたレガシープロバイダープレフィックスは通常のモデル/プロバイダー選択肢として表示されません。 - -`codex` Plugin が有効でも、プライマリモデルがまだ `openai-codex/*` の場合、`openclaw doctor` は経路を変更せずに警告します。これは意図的なものです。`openai-codex/*` は PI Codex OAuth/サブスクリプションパスのままであり、ネイティブ app-server 実行は明示的なランタイム選択のままです。 - -## ルートマップ - -設定を変更する前に、この表を使用してください。 - -| 望ましい動作 | モデル参照 | ランタイム設定 | Plugin 要件 | 期待されるステータスラベル | -| --------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | -| 通常の OpenClaw ランナー経由の OpenAI API | `openai/gpt-*` | 省略、または `runtime: "pi"` | OpenAI プロバイダー | `Runtime: OpenClaw Pi Default` | -| PI 経由の Codex OAuth/サブスクリプション | `openai-codex/gpt-*` | 省略、または `runtime: "pi"` | OpenAI Codex OAuth プロバイダー | `Runtime: OpenClaw Pi Default` | -| ネイティブ Codex app-server 組み込みターン | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` | -| 保守的な自動モードでの混在プロバイダー | プロバイダー固有の参照 | `agentRuntime.id: "auto"` | 任意の Plugin ランタイム | 選択されたランタイムに依存 | -| 明示的な Codex ACP アダプターセッション | ACP プロンプト/モデルに依存 | `sessions_spawn` with `runtime: "acp"` | 正常な `acpx` バックエンド | ACP タスク/セッションステータス | - -重要な分離は、プロバイダーとランタイムの違いです。 - -- `openai-codex/*` は「PI はどのプロバイダー/認証経路を使用するべきか？」に答えます -- `agentRuntime.id: "codex"` は「この埋め込みターンをどのループで実行するべきか？」に答えます -- `/codex ...` は「このチャットはどのネイティブ Codex 会話をバインドまたは制御するべきか？」に答えます -- ACP は「acpx はどの外部ハーネスプロセスを起動するべきか？」に答えます - -## 適切なモデルプレフィックスを選ぶ - -OpenAI ファミリーのルートはプレフィックス固有です。PI 経由の Codex OAuth が必要な場合は `openai-codex/*` を使用し、直接の OpenAI API アクセスが必要な場合、またはネイティブ Codex app-server ハーネスを強制する場合は `openai/*` を使用します。 - -| モデル参照 | ランタイムパス | 使用する場合 | -| --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | OpenClaw/PI 配管経由の OpenAI プロバイダー | `OPENAI_API_KEY` による現在の直接 OpenAI Platform API アクセスが必要な場合。 | -| `openai-codex/gpt-5.5` | OpenClaw/PI 経由の OpenAI Codex OAuth | デフォルトの PI ランナーで ChatGPT/Codex サブスクリプション認証が必要な場合。 | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server ハーネス | 埋め込みエージェントターンでネイティブ Codex app-server 実行が必要な場合。 | - -GPT-5.5 は現在 OpenClaw ではサブスクリプション/OAuth のみです。PI OAuth には `openai-codex/gpt-5.5` を使用し、Codex app-server ハーネスには `openai/gpt-5.5` を使用してください。OpenAI が公開 API で GPT-5.5 を有効にすると、`openai/gpt-5.5` の直接 API キーアクセスがサポートされます。 - -レガシーの `codex/gpt-*` 参照は、互換エイリアスとして引き続き受け入れられます。Doctor の互換移行は、レガシーのプライマリランタイム参照を正規モデル参照に書き換え、ランタイムポリシーを別に記録します。一方で、フォールバック専用のレガシー参照は、ランタイムがエージェントコンテナ全体に対して設定されるため変更されません。新しい PI Codex OAuth 設定では `openai-codex/gpt-*` を使用し、新しいネイティブ app-server ハーネス設定では `openai/gpt-*` と `agentRuntime.id: "codex"` を組み合わせて使用してください。 - -`agents.defaults.imageModel` も同じプレフィックス分離に従います。画像理解を OpenAI Codex OAuth プロバイダーパス経由で実行する必要がある場合は `openai-codex/gpt-*` を使用してください。画像理解を境界付きの Codex app-server ターン経由で実行する必要がある場合は `codex/gpt-*` を使用してください。Codex app-server モデルは画像入力サポートを公開している必要があります。テキスト専用の Codex モデルは、メディアターンが開始する前に失敗します。 - -現在のセッションで有効なハーネスを確認するには `/status` を使用してください。選択が予想外の場合は、`agents/harness` サブシステムのデバッグログを有効にし、Gateway の構造化された `agent harness selected` レコードを調べてください。これには、選択されたハーネス ID、選択理由、ランタイム/フォールバックポリシー、および `auto` モードでは各 Plugin 候補のサポート結果が含まれます。 - -### doctor 警告の意味 - -`openclaw doctor` は、次のすべてが真の場合に警告します。 - -- 同梱の `codex` Plugin が有効、または許可されている -- エージェントのプライマリモデルが `openai-codex/*` -- そのエージェントの有効なランタイムが `codex` ではない - -この警告が存在するのは、ユーザーがしばしば「Codex Plugin が有効」であれば「ネイティブ Codex app-server ランタイム」も意味すると期待するためです。OpenClaw はその飛躍を行いません。この警告の意味は次のとおりです。 - -- PI 経由の ChatGPT/Codex OAuth を意図していた場合、**変更は不要です**。 -- ネイティブ app-server 実行を意図していた場合は、モデルを `openai/` に変更し、`agentRuntime.id: "codex"` を設定してください。 -- セッションランタイムピンは固定されるため、ランタイム変更後も既存セッションには `/new` または `/reset` が必要です。 - -ハーネス選択はライブセッション制御ではありません。埋め込みターンが実行されると、OpenClaw は選択されたハーネス ID をそのセッションに記録し、同じセッション ID の後続ターンでもそれを使用し続けます。将来のセッションで別のハーネスを使いたい場合は、`agentRuntime` 設定または `OPENCLAW_AGENT_RUNTIME` を変更してください。既存の会話を PI と Codex の間で切り替える前には、`/new` または `/reset` を使用して新しいセッションを開始してください。これにより、1 つのトランスクリプトを互換性のない 2 つのネイティブセッションシステムで再生することを避けられます。 - -ハーネスピン導入前に作成されたレガシーセッションは、トランスクリプト履歴があると PI ピン済みとして扱われます。設定を変更した後、その会話を Codex に参加させるには `/new` または `/reset` を使用してください。 - -`/status` は有効なモデルランタイムを表示します。デフォルトの PI ハーネスは `Runtime: OpenClaw Pi Default` と表示され、Codex app-server ハーネスは `Runtime: OpenAI Codex` と表示されます。 - -## 要件 - -- 同梱の `codex` Plugin が利用可能な OpenClaw。 -- Codex app-server `0.125.0` 以降。同梱 Plugin はデフォルトで互換性のある Codex app-server バイナリを管理するため、`PATH` 上のローカル `codex` コマンドは通常のハーネス起動に影響しません。 -- app-server プロセス、または OpenClaw の Codex 認証ブリッジで利用可能な Codex 認証。ローカルの app-server 起動は、各エージェント用の OpenClaw 管理 Codex ホームと分離された子 `HOME` を使用するため、デフォルトでは個人の `~/.codex` アカウント、Skills、Plugin、設定、スレッド状態、またはネイティブ `$HOME/.agents/skills` を読み取りません。 - -Plugin は、古い、またはバージョンなしの app-server ハンドシェイクをブロックします。これにより、OpenClaw はテスト済みのプロトコルサーフェス上に維持されます。 - -ライブおよび Docker スモークテストでは、認証は通常 Codex CLI アカウント、または OpenClaw の `openai-codex` 認証プロファイルから取得されます。ローカル stdio app-server 起動では、アカウントが存在しない場合に `CODEX_API_KEY` / `OPENAI_API_KEY` にフォールバックすることもできます。 - -## 最小設定 - -`openai/gpt-5.5` を使用し、同梱 Plugin を有効にして、`codex` ハーネスを強制します。 +GPT エージェントターンに Codex ハーネスを使うには、モデル参照を `openai/gpt-*` として正規のままにし、バンドルされた `codex` Plugin を有効にして、`agentRuntime.id: "codex"` を設定します。 ```json5 { @@ -145,13 +38,14 @@ Plugin は、古い、またはバージョンなしの app-server ハンドシ model: "openai/gpt-5.5", agentRuntime: { id: "codex", + fallback: "none", }, }, }, } ``` -設定で `plugins.allow` を使用している場合は、そこにも `codex` を含めてください。 +設定で `plugins.allow` を使っている場合は、そこにも `codex` を含めてください。 ```json5 { @@ -166,17 +60,124 @@ Plugin は、古い、またはバージョンなしの app-server ハンドシ } ``` -`agents.defaults.model` またはエージェントモデルを `codex/` に設定するレガシー設定では、引き続き同梱の `codex` Plugin が自動的に有効になります。新しい設定では、上記の明示的な `agentRuntime` エントリと組み合わせて `openai/` を使用することを推奨します。 +このパスでは `openai-codex/gpt-*` を使わないでください。ランタイムを別途強制しない限り、これは通常の PI ランナーを通じた Codex OAuth を選択します。設定変更は新規またはリセットされたセッションに適用されます。既存セッションは記録済みのランタイムを保持します。 -## Codex を他のモデルと併用する +## この Plugin が変更する内容 -同じエージェントが Codex と非 Codex プロバイダーモデルの間を自由に切り替える必要がある場合は、`agentRuntime.id: "codex"` をグローバルに設定しないでください。強制されたランタイムは、そのエージェントまたはセッションのすべての埋め込みターンに適用されます。そのランタイムが強制されている状態で Anthropic モデルを選択すると、OpenClaw は引き続き Codex ハーネスを試行し、そのターンを PI 経由で黙ってルーティングするのではなく、クローズドに失敗します。 +バンドルされた `codex` Plugin は、複数の独立した機能を提供します。 + +| 機能 | 使い方 | 内容 | +| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | +| ネイティブ埋め込みランタイム | `agentRuntime.id: "codex"` | OpenClaw の埋め込みエージェントターンを Codex app-server 経由で実行します。 | +| ネイティブチャット制御コマンド | `/codex bind`, `/codex resume`, `/codex steer`, ... | メッセージング会話から Codex app-server スレッドをバインドして制御します。 | +| Codex app-server プロバイダー/カタログ | `codex` 内部、ハーネス経由で公開 | ランタイムが app-server モデルを検出して検証できるようにします。 | +| Codex メディア理解パス | `codex/*` 画像モデル互換パス | 対応する画像理解モデル向けに、境界付き Codex app-server ターンを実行します。 | +| ネイティブフックリレー | Codex ネイティブイベント周辺の Plugin フック | OpenClaw が対応する Codex ネイティブのツール/終了イベントを観測またはブロックできるようにします。 | + +Plugin を有効にすると、これらの機能が利用可能になります。これは次のことを**しません**。 + +- すべての OpenAI モデルで Codex を使い始める +- `openai-codex/*` モデル参照をネイティブランタイムに変換する +- ACP/acpx をデフォルトの Codex パスにする +- すでに PI ランタイムを記録した既存セッションをホットスイッチする +- OpenClaw のチャネル配信、セッションファイル、認証プロファイル保存、メッセージルーティングを置き換える + +同じ Plugin は、ネイティブな `/codex` チャット制御コマンド面も所有します。Plugin が有効で、ユーザーがチャットから Codex スレッドのバインド、再開、誘導、停止、または検査を求めた場合、エージェントは ACP よりも `/codex ...` を優先するべきです。ユーザーが ACP/acpx を求めた場合、または ACP Codex アダプターをテストしている場合、ACP は明示的なフォールバックのままです。 + +ネイティブ Codex ターンは、公開互換レイヤーとして OpenClaw Plugin フックを保持します。これらはインプロセスの OpenClaw フックであり、Codex `hooks.json` コマンドフックではありません。 + +- `before_prompt_build` +- `before_compaction`, `after_compaction` +- `llm_input`, `llm_output` +- `before_tool_call`, `after_tool_call` +- `before_message_write`（ミラーされたトランスクリプトレコード用） +- Codex `Stop` リレーを通じた `before_agent_finalize` +- `agent_end` + +Plugin は、ランタイム非依存のツール結果ミドルウェアも登録できます。これは、OpenClaw がツールを実行した後、結果が Codex に返される前に、OpenClaw の動的ツール結果を書き換えるためのものです。これは、OpenClaw が所有するトランスクリプトのツール結果書き込みを変換する公開 `tool_result_persist` Plugin フックとは別です。 + +Plugin フック自体のセマンティクスについては、[Plugin フック](/ja-JP/plugins/hooks) と [Plugin ガード動作](/ja-JP/tools/plugin) を参照してください。 + +ハーネスはデフォルトで無効です。新しい設定では、OpenAI モデル参照を `openai/gpt-*` として正規のままにし、ネイティブ app-server 実行が必要な場合に `agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を明示的に強制するべきです。互換性のため、レガシー `codex/*` モデル参照は引き続きハーネスを自動選択しますが、ランタイムに支えられたレガシープロバイダープレフィックスは通常のモデル/プロバイダー選択肢としては表示されません。 + +`codex` Plugin が有効でも、プライマリモデルがまだ `openai-codex/*` の場合、`openclaw doctor` はルートを変更せずに警告します。これは意図的です。`openai-codex/*` は PI Codex OAuth/サブスクリプションパスのままであり、ネイティブ app-server 実行は明示的なランタイム選択のままです。 + +## ルートマップ + +設定を変更する前にこの表を使ってください。 + +| 望ましい動作 | モデル参照 | ランタイム設定 | Plugin 要件 | 期待されるステータスラベル | +| ------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | +| 通常の OpenClaw ランナー経由の OpenAI API | `openai/gpt-*` | 省略、または `runtime: "pi"` | OpenAI プロバイダー | `Runtime: OpenClaw Pi Default` | +| PI 経由の Codex OAuth/サブスクリプション | `openai-codex/gpt-*` | 省略、または `runtime: "pi"` | OpenAI Codex OAuth プロバイダー | `Runtime: OpenClaw Pi Default` | +| ネイティブ Codex app-server 埋め込みターン | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` | +| 保守的な自動モードでの混在プロバイダー | プロバイダー固有の参照 | `agentRuntime.id: "auto"` | 任意の Plugin ランタイム | 選択されたランタイムに依存 | +| 明示的な Codex ACP アダプターセッション | ACP プロンプト/モデルに依存 | `runtime: "acp"` 付きの `sessions_spawn` | 正常な `acpx` バックエンド | ACP タスク/セッションステータス | + +重要な分岐は、プロバイダーとランタイムの違いです。 + +- `openai-codex/*` は「PI はどのプロバイダー/認証ルートを使うべきか？」に答えます +- `agentRuntime.id: "codex"` は「この埋め込みターンをどのループで実行するべきか？」に答えます +- `/codex ...` は「このチャットはどのネイティブ Codex 会話にバインドまたは制御するべきか？」に答えます +- ACP は「acpx はどの外部ハーネスプロセスを起動するべきか？」に答えます + +## 適切なモデルプレフィックスを選ぶ + +OpenAI 系ルートはプレフィックス固有です。PI 経由で Codex OAuth を使いたい場合は `openai-codex/*` を使い、直接 OpenAI API アクセスが必要な場合、またはネイティブ Codex app-server ハーネスを強制している場合は `openai/*` を使います。 + +| モデル参照 | ランタイムパス | 使う場合 | +| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | OpenClaw/PI 配管経由の OpenAI プロバイダー | `OPENAI_API_KEY` による現在の直接 OpenAI Platform API アクセスが必要な場合。 | +| `openai-codex/gpt-5.5` | OpenClaw/PI 経由の OpenAI Codex OAuth | デフォルトの PI ランナーで ChatGPT/Codex サブスクリプション認証を使いたい場合。 | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server ハーネス | 埋め込みエージェントターンにネイティブ Codex app-server 実行が必要な場合。 | + +GPT-5.5 は現在、OpenClaw ではサブスクリプション/OAuth のみです。PI OAuth には `openai-codex/gpt-5.5` を使うか、Codex app-server ハーネスとともに `openai/gpt-5.5` を使ってください。OpenAI が公開 API で GPT-5.5 を有効にすると、`openai/gpt-5.5` への直接 API キーアクセスがサポートされます。 + +レガシー `codex/gpt-*` 参照は互換エイリアスとして引き続き受け付けられます。doctor 互換性移行は、レガシーのプライマリランタイム参照を正規モデル参照に書き換え、ランタイムポリシーを別途記録します。一方、フォールバック専用のレガシー参照は、ランタイムがエージェントコンテナ全体に対して設定されるため、変更されません。新しい PI Codex OAuth 設定では `openai-codex/gpt-*` を使うべきです。新しいネイティブ app-server ハーネス設定では、`openai/gpt-*` に加えて `agentRuntime.id: "codex"` を使うべきです。 + +`agents.defaults.imageModel` も同じプレフィックス分岐に従います。画像理解を OpenAI Codex OAuth プロバイダーパス経由で実行する場合は `openai-codex/gpt-*` を使います。画像理解を境界付き Codex app-server ターン経由で実行する場合は `codex/gpt-*` を使います。Codex app-server モデルは画像入力対応を広告している必要があります。テキスト専用 Codex モデルは、メディアターンが始まる前に失敗します。 + +現在のセッションで有効なハーネスを確認するには `/status` を使います。選択が予想外の場合は、`agents/harness` サブシステムのデバッグログを有効にし、Gateway の構造化された `agent harness selected` レコードを確認してください。これには、選択されたハーネス ID、選択理由、ランタイム/フォールバックポリシー、および `auto` モードでは各 Plugin 候補のサポート結果が含まれます。 + +### doctor 警告の意味 + +`openclaw doctor` は、次のすべてが真の場合に警告します。 + +- バンドルされた `codex` Plugin が有効または許可されている +- エージェントのプライマリモデルが `openai-codex/*` である +- そのエージェントの有効ランタイムが `codex` ではない + +この警告が存在するのは、ユーザーが「Codex Plugin 有効」は「ネイティブ Codex app-server ランタイム」を意味すると期待しがちだからです。OpenClaw はその飛躍を行いません。この警告の意味は次のとおりです。 + +- PI 経由の ChatGPT/Codex OAuth を意図していた場合、**変更は不要です**。 +- ネイティブ app-server 実行を意図していた場合は、モデルを `openai/` に変更し、`agentRuntime.id: "codex"` を設定してください。 +- ランタイム変更後も、既存セッションには `/new` または `/reset` が必要です。セッションランタイムのピン留めは固定的だからです。 + +ハーネス選択はライブセッション制御ではありません。埋め込みターンが実行されると、OpenClaw は選択されたハーネス ID をそのセッションに記録し、同じセッション ID 内の後続ターンでも使い続けます。将来のセッションで別のハーネスを使いたい場合は、`agentRuntime` 設定または `OPENCLAW_AGENT_RUNTIME` を変更してください。既存の会話を PI と Codex の間で切り替える前に、`/new` または `/reset` を使って新しいセッションを開始してください。これにより、1 つのトランスクリプトを互換性のない 2 つのネイティブセッションシステムに通すことを避けられます。 + +ハーネスのピン留め以前に作成されたレガシーセッションは、トランスクリプト履歴がある時点で PI にピン留めされたものとして扱われます。設定変更後にその会話を Codex に移行するには、`/new` または `/reset` を使ってください。 + +`/status` は有効なモデルランタイムを表示します。デフォルトの PI ハーネスは `Runtime: OpenClaw Pi Default` と表示され、Codex app-server ハーネスは `Runtime: OpenAI Codex` と表示されます。 + +## 要件 + +- バンドルされた `codex` Plugin が利用可能な OpenClaw。 +- Codex app-server `0.125.0` 以降。バンドルされた Plugin はデフォルトで互換性のある Codex app-server バイナリを管理するため、`PATH` 上のローカル `codex` コマンドは通常のハーネス起動に影響しません。 +- app-server プロセス、または OpenClaw の Codex 認証ブリッジから Codex 認証を利用できること。ローカル app-server 起動では、各エージェントごとに OpenClaw 管理の Codex ホームと分離された子 `HOME` を使うため、デフォルトでは個人の `~/.codex` アカウント、Skills、Plugin、設定、スレッド状態、またはネイティブ `$HOME/.agents/skills` を読み取りません。 + +Plugin は、古いまたはバージョン未指定の app-server ハンドシェイクをブロックします。これにより、OpenClaw はテスト済みのプロトコル面に留まります。 + +ライブおよび Docker スモークテストでは、認証は通常 Codex CLI アカウント、または OpenClaw の `openai-codex` 認証プロファイルから取得されます。ローカル stdio app-server 起動では、アカウントが存在しない場合に `CODEX_API_KEY` / `OPENAI_API_KEY` にフォールバックすることもできます。 + +## Codex を他のモデルと並べて追加する + +同じエージェントが Codex と Codex 以外のプロバイダーモデルを自由に切り替える必要がある場合は、`agentRuntime.id: "codex"` をグローバルに設定しないでください。強制されたランタイムは、そのエージェントまたはセッションのすべての埋め込みターンに適用されます。そのランタイムが強制されている状態で Anthropic モデルを選択すると、OpenClaw はそれでも Codex ハーネスを試行し、そのターンを黙って PI 経由にルーティングするのではなく、失敗として閉じます。 代わりに、次のいずれかの形を使用してください。 -- `agentRuntime.id: "codex"` を設定した専用エージェントに Codex を置く。 -- 通常の混在プロバイダー利用では、デフォルトエージェントを `agentRuntime.id: "auto"` と PI フォールバックのままにする。 -- レガシーの `codex/*` 参照は互換性のためだけに使用する。新しい設定では、`openai/*` と明示的な Codex ランタイムポリシーを優先する。 +- Codex を `agentRuntime.id: "codex"` の専用エージェントに配置します。 +- 通常の混在プロバイダー利用では、デフォルトエージェントを `agentRuntime.id: "auto"` と PI フォールバックのままにします。 +- レガシーの `codex/*` 参照は互換性のためだけに使用します。新しい設定では、`openai/*` に加えて明示的な Codex ランタイムポリシーを優先してください。 たとえば、これはデフォルトエージェントを通常の自動選択のままにし、別の Codex エージェントを追加します。 @@ -219,29 +220,29 @@ Plugin は、古い、またはバージョンなしの app-server ハンドシ - デフォルトの `main` エージェントは、通常のプロバイダーパスと PI 互換フォールバックを使用します。 - `codex` エージェントは Codex app-server ハーネスを使用します。 -- `codex` エージェントで Codex が見つからない、またはサポートされていない場合、そのターンは PI を静かに使うのではなく失敗します。 +- `codex` エージェントで Codex が存在しないかサポートされていない場合、そのターンは静かに PI を使用するのではなく失敗します。 ## エージェントコマンドのルーティング -エージェントは「Codex」という単語だけではなく、意図に基づいてユーザーリクエストをルーティングする必要があります。 +エージェントは、単語「Codex」だけではなく、意図に基づいてユーザーリクエストをルーティングする必要があります。 -| ユーザーの依頼... | エージェントが使用すべきもの... | +| ユーザーの依頼... | エージェントが使用すべきもの... | | -------------------------------------------------------- | ------------------------------------------------ | -| 「このチャットを Codex にバインドして」 | `/codex bind` | -| 「Codex スレッド `` をここで再開して」 | `/codex resume ` | -| 「Codex スレッドを表示して」 | `/codex threads` | -| 「問題のある Codex 実行についてサポートレポートを提出して」 | `/diagnostics [note]` | -| 「この添付スレッドについてのみ Codex フィードバックを送信して」 | `/codex diagnostics [note]` | -| 「このエージェントのランタイムとして Codex を使用して」 | `agentRuntime.id` への設定変更 | -| 「通常の OpenClaw で自分の ChatGPT/Codex サブスクリプションを使って」 | `openai-codex/*` モデル参照 | -| 「ACP/acpx 経由で Codex を実行して」 | ACP `sessions_spawn({ runtime: "acp", ... })` | -| 「スレッド内で Claude Code/Gemini/OpenCode/Cursor を開始して」 | `/codex` やネイティブサブエージェントではなく ACP/acpx | +| 「このチャットを Codex にバインドして」 | `/codex bind` | +| 「Codex スレッド `` をここで再開して」 | `/codex resume ` | +| 「Codex スレッドを表示して」 | `/codex threads` | +| 「問題のある Codex 実行のサポートレポートを提出して」 | `/diagnostics [note]` | +| 「この添付スレッドについてだけ Codex フィードバックを送信して」 | `/codex diagnostics [note]` | +| 「このエージェントのランタイムに Codex を使用して」 | `agentRuntime.id` への設定変更 | +| 「通常の OpenClaw で自分の ChatGPT/Codex サブスクリプションを使用して」 | `openai-codex/*` モデル参照 | +| 「ACP/acpx 経由で Codex を実行して」 | ACP `sessions_spawn({ runtime: "acp", ... })` | +| 「Claude Code/Gemini/OpenCode/Cursor をスレッドで開始して」 | ACP/acpx。`/codex` でもネイティブサブエージェントでもありません | -OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれたランタイムバックエンドに支えられている場合にのみ、エージェントへ ACP spawn ガイダンスを提示します。ACP が利用できない場合、システムプロンプトと Plugin Skills はエージェントに ACP ルーティングを教えるべきではありません。 +OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれたランタイムバックエンドに支えられている場合にのみ、ACP 生成ガイダンスをエージェントに提示します。ACP が利用できない場合、システムプロンプトと Plugin Skills は、ACP ルーティングについてエージェントに教えるべきではありません。 ## Codex 専用デプロイ -すべての埋め込みエージェントターンが Codex を使用することを証明する必要がある場合は、Codex ハーネスを強制します。明示的な Plugin ランタイムはデフォルトで PI フォールバックなしになるため、`fallback: "none"` は任意ですが、ドキュメントとして有用なことがよくあります。 +すべての埋め込みエージェントターンが Codex を使用することを証明する必要がある場合は、Codex ハーネスを強制します。明示的な Plugin ランタイムはデフォルトで PI フォールバックなしになるため、`fallback: "none"` は任意ですが、ドキュメントとして役立つことがよくあります。 ```json5 { @@ -263,11 +264,11 @@ OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app-server が古すぎる、または app-server を起動できない場合に早期に失敗します。ハーネス選択が見つからない場合に PI で処理させたいことを意図している場合にのみ、`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` を設定してください。 +Codex が強制されている場合、Codex Plugin が無効、app-server が古すぎる、または app-server を起動できないと、OpenClaw は早期に失敗します。ハーネス選択ができない場合に PI に処理させたい意図がある場合にのみ、`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` を設定してください。 ## エージェントごとの Codex -デフォルトエージェントは通常の自動選択を維持したまま、1 つのエージェントを Codex 専用にできます。 +デフォルトエージェントは通常の自動選択を維持しながら、1 つのエージェントだけを Codex 専用にできます。 ```json5 { @@ -298,11 +299,11 @@ Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app } ``` -エージェントとモデルの切り替えには通常のセッションコマンドを使用します。`/new` は新しい OpenClaw セッションを作成し、Codex ハーネスは必要に応じてサイドカー app-server スレッドを作成または再開します。`/reset` はそのスレッドの OpenClaw セッションバインディングをクリアし、次のターンで現在の設定からハーネスを再解決できるようにします。 +エージェントとモデルを切り替えるには、通常のセッションコマンドを使用します。`/new` は新しい OpenClaw セッションを作成し、Codex ハーネスは必要に応じてサイドカーの app-server スレッドを作成または再開します。`/reset` はそのスレッドの OpenClaw セッションバインドをクリアし、次のターンで現在の設定からハーネスを再解決できるようにします。 ## モデル検出 -デフォルトでは、Codex Plugin は利用可能なモデルを app-server に問い合わせます。検出に失敗するかタイムアウトした場合、次のバンドル済みフォールバックカタログを使用します。 +デフォルトでは、Codex Plugin は利用可能なモデルを app-server に問い合わせます。検出が失敗するかタイムアウトした場合、次のバンドル済みフォールバックカタログを使用します。 - GPT-5.5 - GPT-5.4 mini @@ -328,7 +329,7 @@ Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app } ``` -起動時に Codex のプローブを避け、フォールバックカタログに固定したい場合は検出を無効にします。 +起動時に Codex へのプローブを避け、フォールバックカタログに固定したい場合は、検出を無効にします。 ```json5 { @@ -347,7 +348,7 @@ Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app } ``` -## app-server の接続とポリシー +## app-server 接続とポリシー デフォルトでは、Plugin は OpenClaw の管理対象 Codex バイナリをローカルで次のように起動します。 @@ -355,9 +356,9 @@ Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app codex app-server --listen stdio:// ``` -管理対象バイナリは、バンドル済み Plugin ランタイム依存関係として宣言され、残りの `codex` Plugin 依存関係とともにステージングされます。これにより、app-server のバージョンは、ローカルにインストールされている別の Codex CLI ではなく、バンドル済み Plugin に紐付けられます。別の実行可能ファイルを意図的に実行したい場合にのみ、`appServer.command` を設定してください。 +管理対象バイナリは、バンドル済み Plugin ランタイム依存関係として宣言され、残りの `codex` Plugin 依存関係とともにステージングされます。これにより、app-server のバージョンは、ローカルにたまたまインストールされている別の Codex CLI ではなく、バンドル済み Plugin に結び付けられます。別の実行ファイルを意図的に実行したい場合にのみ、`appServer.command` を設定してください。 -デフォルトでは、OpenClaw はローカル Codex ハーネスセッションを YOLO モードで開始します。`approvalPolicy: "never"`、`approvalsReviewer: "user"`、および `sandbox: "danger-full-access"` です。これは自律的な Heartbeat に使用される、信頼されたローカルオペレーターの姿勢です。Codex は、応答する人がいないネイティブ承認プロンプトで停止せずに、シェルとネットワークツールを使用できます。 +デフォルトでは、OpenClaw はローカルの Codex ハーネスセッションを YOLO モードで開始します。`approvalPolicy: "never"`、`approvalsReviewer: "user"`、`sandbox: "danger-full-access"` です。これは自律 Heartbeat に使用される信頼済みローカルオペレーターの姿勢です。Codex は、応答する人がいないネイティブ承認プロンプトで停止せずに、シェルとネットワークツールを使用できます。 Codex のガーディアンレビュー付き承認を有効にするには、`appServer.mode: "guardian"` を設定します。 @@ -380,9 +381,9 @@ Codex のガーディアンレビュー付き承認を有効にするには、`a } ``` -Guardian モードは Codex のネイティブ自動レビュー承認パスを使用します。Codex が sandbox を離れる、ワークスペース外に書き込む、またはネットワークアクセスなどの権限を追加するよう求める場合、Codex はその承認リクエストを人間のプロンプトではなくネイティブレビュアーへルーティングします。レビュアーは Codex のリスクフレームワークを適用し、特定のリクエストを承認または拒否します。YOLO モードより多くのガードレールが欲しいが、無人エージェントを進行させる必要がある場合は Guardian を使用してください。 +Guardian モードは、Codex のネイティブな自動レビュー承認パスを使用します。Codex がサンドボックスを離れる、ワークスペース外に書き込む、またはネットワークアクセスなどの権限を追加するよう求める場合、Codex はその承認リクエストを人間のプロンプトではなくネイティブレビュー担当にルーティングします。レビュー担当は Codex のリスクフレームワークを適用し、特定のリクエストを承認または拒否します。YOLO モードより多くのガードレールが必要だが、無人エージェントにも進捗が必要な場合は Guardian を使用してください。 -`guardian` プリセットは、`approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"`、および `sandbox: "workspace-write"` に展開されます。個々のポリシーフィールドは引き続き `mode` を上書きするため、高度なデプロイではプリセットと明示的な選択を組み合わせることができます。古い `guardian_subagent` レビュアー値は互換エイリアスとして引き続き受け付けられますが、新しい設定では `auto_review` を使用する必要があります。 +`guardian` プリセットは、`approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"`、`sandbox: "workspace-write"` に展開されます。個別のポリシーフィールドは引き続き `mode` を上書きするため、高度なデプロイではプリセットと明示的な選択を混在できます。以前の `guardian_subagent` レビュー担当値は互換エイリアスとして引き続き受け入れられますが、新しい設定では `auto_review` を使用してください。 すでに実行中の app-server には、WebSocket トランスポートを使用します。 @@ -406,25 +407,24 @@ Guardian モードは Codex のネイティブ自動レビュー承認パスを } ``` -Stdio app-server の起動はデフォルトで OpenClaw のプロセス環境を継承しますが、OpenClaw は Codex app-server アカウントブリッジを所有し、`CODEX_HOME` と `HOME` の両方を、そのエージェントの OpenClaw 状態配下にあるエージェントごとのディレクトリに設定します。Codex 独自の skill ローダーは `$CODEX_HOME/skills` と `$HOME/.agents/skills` を読み取るため、ローカル app-server 起動では両方の値が分離されます。これにより、Codex ネイティブの Skills、Plugin、設定、アカウント、スレッド状態は、オペレーター個人の Codex CLI ホームから漏れ込むのではなく、OpenClaw エージェントにスコープされます。 +Stdio app-server の起動は、デフォルトで OpenClaw のプロセス環境を継承しますが、OpenClaw は Codex app-server アカウントブリッジを所有し、`CODEX_HOME` と `HOME` の両方を、そのエージェントの OpenClaw 状態配下にあるエージェントごとのディレクトリに設定します。Codex 独自の Skills ローダーは `$CODEX_HOME/skills` と `$HOME/.agents/skills` を読み取るため、ローカル app-server 起動では両方の値が分離されます。これにより、Codex ネイティブの Skills、plugins、設定、アカウント、スレッド状態は、オペレーター個人の Codex CLI ホームから漏れ込むのではなく、OpenClaw エージェントにスコープされます。 -OpenClaw Plugin と OpenClaw skill スナップショットは、引き続き OpenClaw 独自の Plugin レジストリと skill ローダーを通ります。個人の Codex CLI アセットは通りません。OpenClaw エージェントの一部にすべき有用な Codex CLI Skills や Plugin がある場合は、明示的に棚卸ししてください。 +OpenClaw plugins と OpenClaw Skills スナップショットは、引き続き OpenClaw 独自の Plugin レジストリと Skills ローダーを通じて流れます。個人の Codex CLI アセットは流れません。OpenClaw エージェントの一部にすべき有用な Codex CLI Skills または plugins がある場合は、明示的にインベントリしてください。 ```bash openclaw migrate codex --dry-run openclaw migrate apply codex --yes ``` -Codex 移行プロバイダーは Skills を現在の OpenClaw エージェントワークスペースへコピーします。Codex ネイティブの Plugin、フック、設定ファイルは、コマンドを実行したり、MCP サーバーを公開したり、資格情報を含んだりする可能性があるため、自動的に有効化されるのではなく、手動レビュー用に報告またはアーカイブされます。 +Codex 移行プロバイダーは、Skills を現在の OpenClaw エージェントワークスペースにコピーします。Codex ネイティブ plugins、フック、設定ファイルは、コマンドを実行したり、MCP サーバーを公開したり、資格情報を保持したりする可能性があるため、自動的に有効化されるのではなく、手動レビュー用に報告またはアーカイブされます。 認証は次の順序で選択されます。 -1. エージェント用の明示的な OpenClaw Codex 認証プロファイル。 -2. そのエージェントの Codex ホーム内にある app-server の既存アカウント。 -3. ローカル stdio app-server 起動のみで、app-server アカウントが存在せず OpenAI 認証が引き続き必要な場合、`CODEX_API_KEY`、次に - `OPENAI_API_KEY`。 +1. そのエージェントの明示的な OpenClaw Codex 認証プロファイル。 +2. そのエージェントの Codex ホームにある app-server の既存アカウント。 +3. ローカル stdio app-server 起動の場合のみ、app-server アカウントが存在せず、OpenAI 認証がまだ必要な場合は、`CODEX_API_KEY`、次に `OPENAI_API_KEY`。 -OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロファイルを検出すると、spawn される Codex 子プロセスから `CODEX_API_KEY` と `OPENAI_API_KEY` を削除します。これにより、Gateway レベルの API キーを埋め込みや直接の OpenAI モデルで利用可能にしたまま、ネイティブ Codex app-server ターンが誤って API 経由で課金されることを防ぎます。明示的な Codex API キープロファイルとローカル stdio 環境キーのフォールバックは、継承された子プロセス環境ではなく app-server ログインを使用します。WebSocket app-server 接続は Gateway 環境 API キーフォールバックを受け取りません。明示的な認証プロファイルまたはリモート app-server 独自のアカウントを使用してください。 +OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロファイルを検出すると、生成される Codex 子プロセスから `CODEX_API_KEY` と `OPENAI_API_KEY` を削除します。これにより、Gateway レベルの API キーは埋め込みや直接の OpenAI モデルに利用可能なまま、ネイティブ Codex app-server ターンが誤って API 経由で課金されることを防ぎます。明示的な Codex API キープロファイルとローカル stdio 環境キーのフォールバックは、継承された子プロセス環境ではなく app-server ログインを使用します。WebSocket app-server 接続は Gateway 環境 API キーフォールバックを受け取りません。明示的な認証プロファイルまたはリモート app-server 独自のアカウントを使用してください。 デプロイで追加の環境分離が必要な場合は、それらの変数を `appServer.clearEnv` に追加します。 @@ -445,40 +445,31 @@ OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロフ } ``` -`appServer.clearEnv` は spawn された Codex app-server 子プロセスにのみ影響します。 +`appServer.clearEnv` は、生成された Codex app-server 子プロセスにのみ影響します。 -サポートされている `appServer` フィールド: +サポートされる `appServer` フィールド: -| フィールド | デフォルト | 意味 | -| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` は Codex を起動します。`"websocket"` は `url` に接続します。 | -| `command` | 管理対象の Codex バイナリ | stdio トランスポート用の実行ファイル。管理対象バイナリを使う場合は未設定のままにします。明示的に上書きする場合にのみ設定してください。 | -| `args` | `["app-server", "--listen", "stdio://"]` | stdio トランスポート用の引数。 | -| `url` | 未設定 | WebSocket app-server URL。 | -| `authToken` | 未設定 | WebSocket トランスポート用の Bearer トークン。 | -| `headers` | `{}` | 追加の WebSocket ヘッダー。 | -| `clearEnv` | `[]` | OpenClaw が継承環境を構築したあと、起動された stdio app-server プロセスから削除される追加の環境変数名。`CODEX_HOME` と `HOME` は、ローカル起動時の OpenClaw のエージェントごとの Codex 分離用に予約されています。 | -| `requestTimeoutMs` | `60000` | app-server コントロールプレーン呼び出しのタイムアウト。 | -| `mode` | `"yolo"` | YOLO または guardian レビュー付き実行のプリセット。 | -| `approvalPolicy` | `"never"` | スレッドの開始、再開、ターンに送信されるネイティブ Codex 承認ポリシー。 | -| `sandbox` | `"danger-full-access"` | スレッドの開始、再開に送信されるネイティブ Codex サンドボックスモード。 | -| `approvalsReviewer` | `"user"` | Codex にネイティブ承認プロンプトをレビューさせるには `"auto_review"` を使います。`guardian_subagent` は従来のエイリアスとして残っています。 | -| `serviceTier` | 未設定 | 任意の Codex app-server サービスティア: `"fast"`、`"flex"`、または `null`。無効な従来の値は無視されます。 | +| フィールド | デフォルト | 意味 | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` は Codex を起動し、`"websocket"` は `url` に接続します。 | +| `command` | 管理対象の Codex バイナリ | stdio トランスポート用の実行ファイルです。管理対象バイナリを使う場合は未設定のままにし、明示的に上書きする場合にのみ設定します。 | +| `args` | `["app-server", "--listen", "stdio://"]` | stdio トランスポート用の引数です。 | +| `url` | 未設定 | WebSocket app-server URL です。 | +| `authToken` | 未設定 | WebSocket トランスポート用の Bearer トークンです。 | +| `headers` | `{}` | 追加の WebSocket ヘッダーです。 | +| `clearEnv` | `[]` | OpenClaw が継承環境を構築した後、起動された stdio app-server プロセスから削除される追加の環境変数名です。`CODEX_HOME` と `HOME` は、ローカル起動時の OpenClaw のエージェントごとの Codex 分離用に予約されています。 | +| `requestTimeoutMs` | `60000` | app-server コントロールプレーン呼び出しのタイムアウトです。 | +| `mode` | `"yolo"` | YOLO または guardian レビュー付き実行のプリセットです。 | +| `approvalPolicy` | `"never"` | thread start/resume/turn に送信されるネイティブ Codex 承認ポリシーです。 | +| `sandbox` | `"danger-full-access"` | thread start/resume に送信されるネイティブ Codex サンドボックスモードです。 | +| `approvalsReviewer` | `"user"` | Codex にネイティブ承認プロンプトをレビューさせるには `"auto_review"` を使います。`guardian_subagent` は従来のエイリアスのままです。 | +| `serviceTier` | 未設定 | 任意の Codex app-server サービスティアです: `"fast"`、`"flex"`、または `null`。無効な従来値は無視されます。 | -OpenClaw が所有する動的ツール呼び出しは、`appServer.requestTimeoutMs` とは -独立して制限されます。各 Codex `item/tool/call` リクエストは、30 秒以内に -OpenClaw のレスポンスを受け取る必要があります。タイムアウト時、OpenClaw は対応している場合にツール -シグナルを中止し、失敗した動的ツールレスポンスを Codex に返すため、 -セッションを `processing` のまま残す代わりにターンを続行できます。 +OpenClaw 所有の動的ツール呼び出しは、`appServer.requestTimeoutMs` とは独立して制限されます。各 Codex `item/tool/call` リクエストは、30 秒以内に OpenClaw の応答を受け取る必要があります。タイムアウト時、OpenClaw はサポートされている場合はツールシグナルを中止し、失敗した動的ツール応答を Codex に返すため、セッションを `processing` のまま残す代わりにターンを継続できます。 -OpenClaw が Codex のターンスコープ app-server リクエストに応答したあと、ハーネスは -Codex がネイティブターンを `turn/completed` で完了することも期待します。その -応答後に app-server が 60 秒間無応答になった場合、OpenClaw はベストエフォートで -Codex ターンに割り込み、診断タイムアウトを記録し、 -OpenClaw セッションレーンを解放して、後続のチャットメッセージが古い -ネイティブターンの背後にキューされないようにします。 +OpenClaw が Codex のターンスコープ app-server リクエストに応答した後、ハーネスは Codex がネイティブターンを `turn/completed` で終了することも期待します。その応答後に app-server が 60 秒間沈黙した場合、OpenClaw はベストエフォートで Codex ターンを中断し、診断タイムアウトを記録し、OpenClaw セッションレーンを解放して、後続のチャットメッセージが古いネイティブターンの後ろにキューされないようにします。 -ローカルテストでは環境による上書きが引き続き利用できます。 +ローカルテストでは環境オーバーライドを引き続き利用できます。 - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -486,29 +477,18 @@ OpenClaw セッションレーンを解放して、後続のチャットメッ - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` は、`appServer.command` が未設定の場合に -管理対象バイナリをバイパスします。 +`OPENCLAW_CODEX_APP_SERVER_BIN` は、`appServer.command` が未設定の場合に管理対象バイナリをバイパスします。 -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` は削除されました。代わりに -`plugins.entries.codex.config.appServer.mode: "guardian"` を使うか、 -一回限りのローカルテストでは `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` を使います。繰り返し可能なデプロイでは、 -Codex ハーネス設定の他の部分と同じレビュー済みファイルに Plugin の動作を保持できるため、 -設定を使うことが推奨されます。 +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` は削除されました。代わりに `plugins.entries.codex.config.appServer.mode: "guardian"` を使うか、1 回限りのローカルテストには `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` を使ってください。再現可能なデプロイでは、Plugin の動作が Codex ハーネス設定の残り部分と同じレビュー対象ファイルに保たれるため、設定を使うことを推奨します。 ## コンピューター使用 -Computer Use は専用のセットアップガイドで扱います: -[Codex Computer Use](/ja-JP/plugins/codex-computer-use)。 +コンピューター使用は専用のセットアップガイドで説明しています: +[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use)。 -短く言えば、OpenClaw はデスクトップ制御アプリをベンダー提供せず、デスクトップ操作も -自ら実行しません。OpenClaw は Codex app-server を準備し、 -`computer-use` MCP サーバーが利用可能であることを検証してから、Codex モードのターン中に -ネイティブ MCP ツール呼び出しを Codex に処理させます。 +要約すると、OpenClaw はデスクトップ制御アプリをベンダー化せず、デスクトップ操作自体も実行しません。Codex app-server を準備し、`computer-use` MCP サーバーが利用可能であることを確認してから、Codex モードのターン中に Codex がネイティブ MCP ツール呼び出しを処理できるようにします。 -Codex marketplace フロー外で TryCua ドライバーに直接アクセスするには、 -`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` で -`cua-driver mcp` を登録します。Codex が所有する Computer Use と直接 MCP 登録の違いについては、 -[Codex Computer Use](/ja-JP/plugins/codex-computer-use) を参照してください。 +Codex マーケットプレイスフローの外で TryCua ドライバーへ直接アクセスするには、`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` で `cua-driver mcp` を登録します。Codex 所有のコンピューター使用と直接 MCP 登録の違いについては、[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use)を参照してください。 最小設定: @@ -538,28 +518,18 @@ Codex marketplace フロー外で TryCua ドライバーに直接アクセスす } ``` -セットアップはコマンド面から確認またはインストールできます。 +セットアップはコマンドサーフェスから確認またはインストールできます。 - `/codex computer-use status` - `/codex computer-use install` - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -Computer Use は macOS 固有で、Codex MCP サーバーがアプリを制御できるようになる前に -ローカル OS 権限が必要になる場合があります。`computerUse.enabled` が true で MCP -サーバーが利用できない場合、Codex モードのターンは、ネイティブ Computer Use ツールなしで -黙って実行されるのではなく、スレッド開始前に失敗します。marketplace の選択肢、 -リモートカタログの制限、ステータス理由、トラブルシューティングについては -[Codex Computer Use](/ja-JP/plugins/codex-computer-use) を参照してください。 +コンピューター使用は macOS 固有であり、Codex MCP サーバーがアプリを制御できるようになる前に、ローカル OS 権限が必要になる場合があります。`computerUse.enabled` が true で MCP サーバーが利用できない場合、Codex モードのターンは、ネイティブのコンピューター使用ツールなしで密かに実行されるのではなく、スレッド開始前に失敗します。マーケットプレイスの選択肢、リモートカタログの制限、ステータス理由、トラブルシューティングについては、[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use)を参照してください。 -`computerUse.autoInstall` が true の場合、Codex がまだローカル marketplace を検出していなければ、 -OpenClaw は -`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` から標準の -バンドル済み Codex Desktop marketplace を登録できます。ランタイムまたは Computer Use 設定を変更したあとは、 -既存のセッションが古い PI または Codex スレッドバインディングを保持しないように、 -`/new` または `/reset` を使います。 +`computerUse.autoInstall` が true の場合、Codex がまだローカルマーケットプレイスを検出していなければ、OpenClaw は `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` から標準のバンドル版 Codex Desktop マーケットプレイスを登録できます。ランタイムまたはコンピューター使用設定を変更した後は、既存セッションが古い PI または Codex スレッドバインディングを保持しないように、`/new` または `/reset` を使ってください。 -## 一般的なレシピ +## よく使うレシピ デフォルトの stdio トランスポートを使うローカル Codex: @@ -575,7 +545,7 @@ OpenClaw は } ``` -Codex 専用ハーネス検証: +Codex のみのハーネス検証: ```json5 { @@ -619,7 +589,7 @@ guardian レビュー付き Codex 承認: } ``` -明示的なヘッダーを持つリモート app-server: +明示的なヘッダーを使うリモート app-server: ```json5 { @@ -642,58 +612,45 @@ guardian レビュー付き Codex 承認: } ``` -モデル切り替えは OpenClaw が制御したままです。OpenClaw セッションが -既存の Codex スレッドにアタッチされている場合、次のターンは現在選択されている -OpenAI モデル、プロバイダー、承認ポリシー、サンドボックス、サービスティアを -app-server に再送信します。`openai/gpt-5.5` から `openai/gpt-5.2` に切り替えると、 -スレッドバインディングは保持されますが、新しく選択されたモデルで続行するよう Codex に要求します。 +モデル切り替えは OpenClaw 側で制御されます。OpenClaw セッションが既存の Codex スレッドにアタッチされている場合、次のターンで現在選択されている OpenAI モデル、プロバイダー、承認ポリシー、サンドボックス、サービスティアが再度 app-server に送信されます。`openai/gpt-5.5` から `openai/gpt-5.2` に切り替えると、スレッドバインディングは維持されますが、新しく選択されたモデルで続行するよう Codex に要求します。 ## Codex コマンド -バンドルされた Plugin は、`/codex` を承認済みスラッシュコマンドとして登録します。これは -汎用であり、OpenClaw テキストコマンドに対応する任意のチャンネルで動作します。 +バンドルされた Plugin は、認可済みスラッシュコマンドとして `/codex` を登録します。これは汎用であり、OpenClaw テキストコマンドをサポートする任意のチャンネルで動作します。 一般的な形式: -- `/codex status` は、ライブ app-server 接続性、モデル、アカウント、レート制限、MCP サーバー、Skills を表示します。 +- `/codex status` は、ライブ app-server 接続、モデル、アカウント、レート制限、MCP サーバー、Skills を表示します。 - `/codex models` は、ライブ Codex app-server モデルを一覧表示します。 - `/codex threads [filter]` は、最近の Codex スレッドを一覧表示します。 - `/codex resume ` は、現在の OpenClaw セッションを既存の Codex スレッドにアタッチします。 -- `/codex compact` は、アタッチされたスレッドを compact するよう Codex app-server に依頼します。 -- `/codex review` は、アタッチされたスレッドの Codex ネイティブレビューを開始します。 +- `/codex compact` は、アタッチされたスレッドをコンパクト化するよう Codex app-server に要求します。 +- `/codex review` は、アタッチされたスレッドに対して Codex ネイティブレビューを開始します。 - `/codex diagnostics [note]` は、アタッチされたスレッドの Codex 診断フィードバックを送信する前に確認します。 -- `/codex computer-use status` は、設定済みの Computer Use Plugin と MCP サーバーを確認します。 -- `/codex computer-use install` は、設定済みの Computer Use Plugin をインストールし、MCP サーバーをリロードします。 +- `/codex computer-use status` は、設定済みのコンピューター使用 Plugin と MCP サーバーを確認します。 +- `/codex computer-use install` は、設定済みのコンピューター使用 Plugin をインストールし、MCP サーバーを再読み込みします。 - `/codex account` は、アカウントとレート制限のステータスを表示します。 - `/codex mcp` は、Codex app-server MCP サーバーのステータスを一覧表示します。 -- `/codex skills` は、Codex app-server skills を一覧表示します。 +- `/codex skills` は、Codex app-server の Skills を一覧表示します。 ### 一般的なデバッグワークフロー -Codex ベースのエージェントが Telegram、Discord、Slack、 -または別のチャンネルで予想外の動作をした場合は、問題が発生した会話から開始します。 +Codex バックエンドのエージェントが Telegram、Discord、Slack、または別のチャンネルで予期しない動作をした場合は、問題が発生した会話から始めます。 -1. 見た内容を説明する `/diagnostics bad tool choice after image upload` または別の短いメモを実行します。 -2. 診断リクエストを一度承認します。この承認によりローカル Gateway - 診断 zip が作成され、セッションが Codex ハーネスを使用しているため、 - 関連する Codex フィードバックバンドルも OpenAI サーバーに送信されます。 -3. 完了した診断返信をバグレポートまたはサポートスレッドにコピーします。 - そこには、ローカルバンドルパス、プライバシー概要、OpenClaw セッション ID、 - Codex スレッド ID、および各 Codex スレッドの `Inspect locally` 行が含まれます。 -4. 自分で実行をデバッグしたい場合は、表示された `Inspect locally` - コマンドをターミナルで実行します。これは `codex resume ` のような形で、 - ネイティブ Codex スレッドを開くため、会話を調査したり、ローカルで続行したり、 - Codex が特定のツールや計画を選んだ理由を Codex に尋ねたりできます。 +1. `/diagnostics bad tool choice after image upload`、または見た内容を説明する別の短いメモを実行します。 +2. 診断リクエストを一度承認します。この承認により、ローカル Gateway 診断 zip が作成され、セッションが Codex ハーネスを使用しているため、関連する Codex フィードバックバンドルも OpenAI サーバーに送信されます。 +3. 完了した診断返信をバグレポートまたはサポートスレッドにコピーします。これには、ローカルバンドルパス、プライバシー概要、OpenClaw セッション ID、Codex スレッド ID、および各 Codex スレッドの `Inspect locally` 行が含まれます。 +4. 実行を自分でデバッグしたい場合は、表示された `Inspect locally` コマンドをターミナルで実行します。これは `codex resume ` のような形式で、ネイティブ Codex スレッドを開くため、会話を調査したり、ローカルで続行したり、特定のツールや計画を選んだ理由を Codex に尋ねたりできます。 -`/codex diagnostics [note]` は、OpenClaw Gateway 診断バンドル全体なしで、現在アタッチされているスレッドの Codex フィードバックアップロードだけを明示的に必要とする場合にのみ使用します。ほとんどのサポートレポートでは、`/diagnostics [note]` のほうが適切な開始点です。これは、ローカル Gateway の状態と Codex スレッド ID を 1 つの返信で結び付けるためです。完全なプライバシーモデルとグループチャットの動作については、[診断エクスポート](/ja-JP/gateway/diagnostics)を参照してください。 +`/codex diagnostics [note]` は、完全な OpenClaw Gateway 診断バンドルではなく、現在添付されているスレッドの Codex フィードバックアップロードだけが特に必要な場合にのみ使用します。ほとんどのサポート報告では、`/diagnostics [note]` の方が出発点として適しています。これは、ローカル Gateway の状態と Codex スレッド ID を 1 つの返信で結び付けるためです。完全なプライバシーモデルとグループチャットでの動作については、[診断エクスポート](/ja-JP/gateway/diagnostics)を参照してください。 -Core OpenClaw は、一般的な Gateway 診断コマンドとして、オーナー専用の `/diagnostics [note]` も公開しています。その承認プロンプトには機微データに関する前文が表示され、[診断エクスポート](/ja-JP/gateway/diagnostics)へのリンクがあり、毎回、明示的な exec 承認を通じて `openclaw gateway diagnostics export --json` を要求します。allow-all ルールで診断を承認しないでください。承認後、OpenClaw はローカルバンドルパスとマニフェスト概要を含む貼り付け可能なレポートを送信します。アクティブな OpenClaw セッションが Codex ハーネスを使用している場合、同じ承認により、関連する Codex フィードバックバンドルを OpenAI サーバーへ送信することも許可されます。承認プロンプトには Codex フィードバックが送信されることが記載されますが、承認前に Codex セッション ID やスレッド ID は表示されません。 +Core OpenClaw は、一般的な Gateway 診断コマンドとして、所有者専用の `/diagnostics [note]` も公開しています。その承認プロンプトには、機密データに関する前置きが表示され、[診断エクスポート](/ja-JP/gateway/diagnostics)へのリンクが示され、毎回明示的な exec 承認を通じて `openclaw gateway diagnostics export --json` を要求します。allow-all ルールで診断を承認しないでください。承認後、OpenClaw はローカルバンドルのパスとマニフェストの概要を含む、貼り付け可能なレポートを送信します。アクティブな OpenClaw セッションが Codex ハーネスを使用している場合、その同じ承認により、関連する Codex フィードバックバンドルを OpenAI サーバーへ送信することも許可されます。承認プロンプトには Codex フィードバックが送信されることが示されますが、承認前に Codex セッション ID やスレッド ID は列挙されません。 -グループチャットでオーナーが `/diagnostics` を呼び出した場合、OpenClaw は共有チャンネルをクリーンに保ちます。グループには短い通知だけが届き、診断の前文、承認プロンプト、Codex セッション/スレッド ID はプライベート承認ルートを通じてオーナーに送信されます。プライベートなオーナールートがない場合、OpenClaw はグループでの要求を拒否し、DM から実行するようオーナーに求めます。 +グループチャットで所有者が `/diagnostics` を呼び出した場合、OpenClaw は共有チャンネルをクリーンに保ちます。グループには短い通知だけが届き、診断の前置き、承認プロンプト、Codex セッション ID/スレッド ID は、非公開の承認ルートを通じて所有者に送信されます。非公開の所有者ルートがない場合、OpenClaw はグループからの要求を拒否し、所有者に DM から実行するよう求めます。 -承認された Codex アップロードは、Codex app-server の `feedback/upload` を呼び出し、一覧に含まれる各スレッドと、利用可能な場合は生成された Codex サブスレッドのログを含めるよう app-server に要求します。アップロードは Codex の通常のフィードバック経路を通じて OpenAI サーバーへ送信されます。その app-server で Codex フィードバックが無効になっている場合、コマンドは app-server エラーを返します。完了した診断返信には、送信されたスレッドについて、チャンネル、OpenClaw セッション ID、Codex スレッド ID、ローカルの `codex resume ` コマンドが一覧表示されます。承認を拒否または無視した場合、OpenClaw はそれらの Codex ID を出力しません。このアップロードは、ローカル Gateway 診断エクスポートの代替ではありません。 +承認された Codex アップロードは Codex app-server の `feedback/upload` を呼び出し、利用可能な場合は、列挙された各スレッドと生成された Codex サブスレッドのログを含めるよう app-server に要求します。アップロードは Codex の通常のフィードバック経路を通じて OpenAI サーバーへ送信されます。その app-server で Codex フィードバックが無効になっている場合、コマンドは app-server エラーを返します。完了した診断返信には、送信されたスレッドについて、チャンネル、OpenClaw セッション ID、Codex スレッド ID、およびローカルの `codex resume ` コマンドが列挙されます。承認を拒否または無視した場合、OpenClaw はそれらの Codex ID を出力しません。このアップロードは、ローカル Gateway 診断エクスポートを置き換えるものではありません。 -`/codex resume` は、通常のターンでハーネスが使用するものと同じサイドカー束縛ファイルを書き込みます。次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw モデルを app-server に渡し、拡張履歴を有効に保ちます。 +`/codex resume` は、ハーネスが通常のターンで使用するものと同じサイドカーのバインディングファイルを書き込みます。次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw モデルを app-server に渡し、拡張履歴を有効なままにします。 ### CLI から Codex スレッドを調査する @@ -703,96 +660,96 @@ Core OpenClaw は、一般的な Gateway 診断コマンドとして、オーナ codex resume ``` -チャンネル会話でバグに気付き、問題のある Codex セッションを調査したい場合、ローカルで続行したい場合、または特定のツールや推論の選択をした理由を Codex に尋ねたい場合に使用します。通常、最も簡単な手順は、先に `/diagnostics [note]` を実行することです。承認後、完了したレポートには各 Codex スレッドが一覧表示され、たとえば `codex resume ` のような `Inspect locally` コマンドが出力されます。そのコマンドをそのままターミナルにコピーできます。 +チャンネルの会話でバグに気付き、問題のある Codex セッションを調査したり、ローカルで続行したり、特定のツールまたは推論の選択をした理由を Codex に尋ねたりしたい場合に、これを使用します。通常、最も簡単な手順は、まず `/diagnostics [note]` を実行することです。承認後、完了したレポートには各 Codex スレッドが列挙され、たとえば `codex resume ` のような `Inspect locally` コマンドが出力されます。そのコマンドを直接ターミナルにコピーできます。 -現在のチャットについては `/codex binding` から、最近の Codex app-server スレッドについては `/codex threads [filter]` からスレッド ID を取得し、シェルで同じ `codex resume` コマンドを実行することもできます。 +現在のチャットについては `/codex binding` から、最近の Codex app-server スレッドについては `/codex threads [filter]` からスレッド ID を取得し、同じ `codex resume` コマンドをシェルで実行することもできます。 -このコマンドサーフェスには Codex app-server `0.125.0` 以降が必要です。将来の app-server またはカスタム app-server がその JSON-RPC メソッドを公開していない場合、個々の制御メソッドは `unsupported by this Codex app-server` と報告されます。 +このコマンドサーフェスには Codex app-server `0.125.0` 以降が必要です。将来の app-server またはカスタム app-server がその JSON-RPC メソッドを公開していない場合、個々の制御メソッドは `unsupported by this Codex app-server` として報告されます。 ## フック境界 Codex ハーネスには 3 つのフック層があります。 -| 層 | オーナー | 目的 | +| レイヤー | 所有者 | 目的 | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw Plugin フック | OpenClaw | PI と Codex ハーネス全体での製品/Plugin 互換性。 | -| Codex app-server 拡張ミドルウェア | OpenClaw バンドル Plugin | OpenClaw 動的ツール周辺のターンごとのアダプター動作。 | +| OpenClaw Plugin フック | OpenClaw | PI と Codex ハーネス全体での製品/Plugin 互換性。 | +| Codex app-server 拡張ミドルウェア | OpenClaw 同梱 Plugin | OpenClaw 動的ツール周辺のターンごとのアダプター動作。 | | Codex ネイティブフック | Codex | Codex 設定からの低レベル Codex ライフサイクルとネイティブツールポリシー。 | -OpenClaw は、OpenClaw Plugin の動作をルーティングするために、プロジェクトまたはグローバルの Codex `hooks.json` ファイルを使用しません。サポートされるネイティブツールと権限ブリッジについて、OpenClaw は `PreToolUse`、`PostToolUse`、`PermissionRequest`、`Stop` 用に、スレッドごとの Codex 設定を注入します。`SessionStart` や `UserPromptSubmit` などの他の Codex フックは Codex レベルの制御のままです。これらは v1 契約では OpenClaw Plugin フックとして公開されません。 +OpenClaw は、OpenClaw Plugin の動作をルーティングするために、プロジェクトまたはグローバルの Codex `hooks.json` ファイルを使用しません。サポートされているネイティブツールと権限ブリッジについて、OpenClaw は `PreToolUse`、`PostToolUse`、`PermissionRequest`、`Stop` 用のスレッドごとの Codex 設定を注入します。`SessionStart` や `UserPromptSubmit` などの他の Codex フックは Codex レベルの制御のままであり、v1 コントラクトでは OpenClaw Plugin フックとして公開されません。 -OpenClaw 動的ツールでは、Codex が呼び出しを要求した後に OpenClaw がツールを実行するため、OpenClaw は自分が所有する Plugin とミドルウェアの動作をハーネスアダプター内で発火します。Codex ネイティブツールでは、Codex が正規のツールレコードを所有します。OpenClaw は選択されたイベントをミラーできますが、Codex が app-server またはネイティブフックコールバックを通じてその操作を公開しない限り、ネイティブ Codex スレッドを書き換えることはできません。 +OpenClaw 動的ツールの場合、Codex が呼び出しを要求した後に OpenClaw がツールを実行するため、OpenClaw はハーネスアダプター内で、自身が所有する Plugin とミドルウェアの動作を発火します。Codex ネイティブツールの場合、Codex が正規のツールレコードを所有します。OpenClaw は選択されたイベントをミラーできますが、Codex が app-server またはネイティブフックコールバックを通じてその操作を公開しない限り、ネイティブ Codex スレッドを書き換えることはできません。 -Compaction と LLM ライフサイクル投影は、ネイティブ Codex フックコマンドではなく、Codex app-server 通知と OpenClaw アダプター状態から得られます。OpenClaw の `before_compaction`、`after_compaction`、`llm_input`、`llm_output` イベントはアダプターレベルの観測であり、Codex の内部リクエストや Compaction ペイロードをバイト単位で取得したものではありません。 +Compaction と LLM ライフサイクルの投影は、ネイティブ Codex フックコマンドではなく、Codex app-server 通知と OpenClaw アダプター状態から来ます。OpenClaw の `before_compaction`、`after_compaction`、`llm_input`、`llm_output` イベントはアダプターレベルの観測であり、Codex の内部リクエストや Compaction ペイロードをバイト単位で取得したものではありません。 -Codex ネイティブの `hook/started` および `hook/completed` app-server 通知は、軌跡とデバッグ用に `codex_app_server.hook` エージェントイベントとして投影されます。これらは OpenClaw Plugin フックを呼び出しません。 +Codex ネイティブの `hook/started` および `hook/completed` app-server 通知は、軌跡とデバッグのために `codex_app_server.hook` エージェントイベントとして投影されます。これらは OpenClaw Plugin フックを呼び出しません。 -## V1 サポート契約 +## V1 サポートコントラクト -Codex モードは、下層のモデル呼び出しだけが異なる PI ではありません。Codex はネイティブモデルループのより多くを所有し、OpenClaw はその境界に合わせて Plugin とセッションのサーフェスを適応させます。 +Codex モードは、内部のモデル呼び出しを変えた PI ではありません。Codex はネイティブモデルループのより多くを所有し、OpenClaw はその境界に合わせて Plugin とセッションのサーフェスを適応させます。 -Codex runtime v1 でサポートされるもの: +Codex ランタイム v1 でサポートされるもの: -| サーフェス | サポート | 理由 | +| サーフェス | サポート | 理由 | | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Codex 経由の OpenAI モデルループ | サポート | Codex app-server が OpenAI ターン、ネイティブスレッド再開、ネイティブツール継続を所有します。 | -| OpenClaw チャンネルルーティングと配信 | サポート | Telegram、Discord、Slack、WhatsApp、iMessage、その他のチャンネルはモデル runtime の外側に残ります。 | -| OpenClaw 動的ツール | サポート | Codex は OpenClaw にこれらのツールの実行を依頼するため、OpenClaw は実行経路内に残ります。 | -| プロンプトとコンテキスト Plugin | サポート | OpenClaw はプロンプトオーバーレイを構築し、スレッドの開始または再開前にコンテキストを Codex ターンへ投影します。 | -| コンテキストエンジンライフサイクル | サポート | Codex ターンでは、組み立て、取り込みまたはターン後メンテナンス、コンテキストエンジン Compaction 調整が実行されます。 | -| 動的ツールフック | サポート | `before_tool_call`、`after_tool_call`、ツール結果ミドルウェアは、OpenClaw 所有の動的ツールの周辺で実行されます。 | -| ライフサイクルフック | アダプター観測としてサポート | `llm_input`、`llm_output`、`agent_end`、`before_compaction`、`after_compaction` は、正直な Codex モードペイロードで発火します。 | -| 最終回答修正ゲート | ネイティブフックリレーを通じてサポート | Codex `Stop` は `before_agent_finalize` にリレーされます。`revise` は最終化前にもう 1 回のモデルパスを Codex に要求します。 | -| ネイティブシェル、パッチ、MCP のブロックまたは観測 | ネイティブフックリレーを通じてサポート | Codex `PreToolUse` と `PostToolUse` は、Codex app-server `0.125.0` 以降での MCP ペイロードを含め、確定済みのネイティブツールサーフェスに対してリレーされます。ブロックはサポートされますが、引数の書き換えはサポートされません。 | -| ネイティブ権限ポリシー | ネイティブフックリレーを通じてサポート | Codex `PermissionRequest` は、runtime が公開している場合、OpenClaw ポリシーを通じてルーティングできます。OpenClaw が決定を返さない場合、Codex は通常の guardian またはユーザー承認経路を通じて続行します。 | -| App-server 軌跡キャプチャ | サポート | OpenClaw は app-server に送信したリクエストと、受信した app-server 通知を記録します。 | +| Codex を通じた OpenAI モデルループ | サポート | Codex app-server が OpenAI ターン、ネイティブスレッド再開、ネイティブツール継続を所有するため。 | +| OpenClaw チャンネルルーティングと配信 | サポート | Telegram、Discord、Slack、WhatsApp、iMessage、その他のチャンネルはモデルランタイムの外側に留まるため。 | +| OpenClaw 動的ツール | サポート | Codex が OpenClaw にこれらのツールの実行を要求するため、OpenClaw は実行経路に留まるため。 | +| プロンプトとコンテキスト Plugin | サポート | OpenClaw が、スレッドを開始または再開する前に、プロンプトオーバーレイを構築し、コンテキストを Codex ターンへ投影するため。 | +| コンテキストエンジンのライフサイクル | サポート | Codex ターンに対して、組み立て、取り込みまたはターン後メンテナンス、コンテキストエンジンの Compaction 調整が実行されるため。 | +| 動的ツールフック | サポート | `before_tool_call`、`after_tool_call`、およびツール結果ミドルウェアが、OpenClaw 所有の動的ツールの周辺で実行されるため。 | +| ライフサイクルフック | アダプター観測としてサポート | `llm_input`、`llm_output`、`agent_end`、`before_compaction`、`after_compaction` は、正確な Codex モードペイロードで発火するため。 | +| 最終回答の修正ゲート | ネイティブフックリレーを通じてサポート | Codex `Stop` は `before_agent_finalize` にリレーされ、`revise` は最終化前にもう 1 回のモデルパスを Codex に要求するため。 | +| ネイティブ shell、patch、MCP のブロックまたは観測 | ネイティブフックリレーを通じてサポート | Codex `PreToolUse` と `PostToolUse` は、Codex app-server `0.125.0` 以降の MCP ペイロードを含む、コミット済みのネイティブツールサーフェスに対してリレーされるため。ブロックはサポートされますが、引数の書き換えはサポートされません。 | +| ネイティブ権限ポリシー | ネイティブフックリレーを通じてサポート | ランタイムが公開している場合、Codex `PermissionRequest` は OpenClaw ポリシーを通じてルーティングできます。OpenClaw が決定を返さない場合、Codex は通常の guardian またはユーザー承認経路を通じて続行します。 | +| App-server 軌跡キャプチャ | サポート | OpenClaw は app-server に送信したリクエストと、受信した app-server 通知を記録するため。 | -Codex runtime v1 でサポートされないもの: +Codex ランタイム v1 でサポートされないもの: -| サーフェス | V1 境界 | 将来のパス | +| サーフェス | V1 境界 | 今後のパス | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| ネイティブツール引数の変更 | Codex ネイティブのツール前フックはブロックできるが、OpenClaw は Codex ネイティブのツール引数を書き換えない。 | 置換用ツール入力には Codex のフック/スキーマサポートが必要。 | -| 編集可能な Codex ネイティブのトランスクリプト履歴 | Codex が正規のネイティブスレッド履歴を所有する。OpenClaw はミラーを所有し、将来のコンテキストを投影できるが、サポートされていない内部状態を変更すべきではない。 | ネイティブスレッドの手術が必要な場合は、明示的な Codex app-server API を追加する。 | -| Codex ネイティブツールレコード向けの `tool_result_persist` | そのフックは OpenClaw が所有するトランスクリプト書き込みを変換するものであり、Codex ネイティブのツールレコードを変換するものではない。 | 変換済みレコードをミラーできる可能性はあるが、正規の書き換えには Codex のサポートが必要。 | -| リッチなネイティブ Compaction メタデータ | OpenClaw は Compaction の開始と完了を観測するが、安定した保持/破棄リスト、トークン差分、または要約ペイロードは受け取らない。 | よりリッチな Codex Compaction イベントが必要。 | -| Compaction 介入 | 現在の OpenClaw Compaction フックは Codex モードでは通知レベル。 | Plugin がネイティブ Compaction を拒否または書き換える必要がある場合は、Codex の Compaction 前後フックを追加する。 | -| バイト単位で同一のモデル API リクエストキャプチャ | OpenClaw は app-server のリクエストと通知をキャプチャできるが、Codex コアは最終的な OpenAI API リクエストを内部で構築する。 | Codex のモデルリクエストトレースイベントまたはデバッグ API が必要。 | +| ネイティブツール引数の変更 | Codex のネイティブなツール実行前フックはブロックできますが、OpenClaw は Codex ネイティブツール引数を書き換えません。 | 置換後のツール入力には、Codex のフック/スキーマサポートが必要です。 | +| 編集可能な Codex ネイティブ transcript 履歴 | Codex は正規のネイティブスレッド履歴を所有します。OpenClaw はミラーを所有し、将来のコンテキストを投影できますが、未サポートの内部状態を変更すべきではありません。 | ネイティブスレッドの直接編集が必要な場合は、明示的な Codex app-server API を追加します。 | +| Codex ネイティブツールレコード用の `tool_result_persist` | そのフックは OpenClaw が所有する transcript 書き込みを変換するもので、Codex ネイティブツールレコードは変換しません。 | 変換済みレコードをミラーすることはできますが、正規の書き換えには Codex のサポートが必要です。 | +| リッチなネイティブ Compaction メタデータ | OpenClaw は Compaction の開始と完了を監視しますが、安定した保持/破棄リスト、トークン差分、要約ペイロードは受け取りません。 | よりリッチな Codex Compaction イベントが必要です。 | +| Compaction 介入 | 現在の OpenClaw Compaction フックは、Codex モードでは通知レベルです。 | Plugin がネイティブ Compaction の拒否や書き換えを必要とする場合は、Codex の Compaction 前後フックを追加します。 | +| バイト単位で一致するモデル API リクエストの捕捉 | OpenClaw は app-server のリクエストと通知を捕捉できますが、Codex core は最終的な OpenAI API リクエストを内部で構築します。 | Codex のモデルリクエスト追跡イベントまたはデバッグ API が必要です。 | ## ツール、メディア、Compaction -Codex ハーネスは、低レベルの組み込みエージェント実行器のみを変更する。 +Codex ハーネスが変更するのは、低レベルの組み込みエージェント実行器だけです。 -OpenClaw は引き続きツールリストを構築し、ハーネスから動的ツール結果を受け取る。テキスト、画像、動画、音楽、TTS、承認、メッセージングツールの出力は、通常の OpenClaw 配信パスを通り続ける。 +OpenClaw は引き続きツールリストを構築し、ハーネスから動的ツール結果を受け取ります。テキスト、画像、動画、音楽、TTS、承認、メッセージングツール出力は、通常の OpenClaw 配信パスを通り続けます。 -ネイティブフックリレーは意図的に汎用的だが、v1 のサポート契約は OpenClaw がテストする Codex ネイティブのツールと権限のパスに限定される。Codex ランタイムでは、これに shell、patch、MCP の `PreToolUse`、`PostToolUse`、`PermissionRequest` ペイロードが含まれる。ランタイム契約で名前が示されるまでは、将来のすべての Codex フックイベントが OpenClaw Plugin サーフェスであると想定しないこと。 +ネイティブフックリレーは意図的に汎用的ですが、v1 のサポート契約は OpenClaw がテストする Codex ネイティブのツールおよび権限パスに限定されます。Codex ランタイムでは、それに shell、patch、MCP の `PreToolUse`、`PostToolUse`、`PermissionRequest` ペイロードが含まれます。ランタイム契約が名前を挙げるまでは、将来のすべての Codex フックイベントが OpenClaw Plugin サーフェスであると仮定しないでください。 -`PermissionRequest` について、OpenClaw はポリシーが判断した場合にのみ明示的な許可または拒否の決定を返す。決定なしの結果は許可ではない。Codex はそれをフック決定なしとして扱い、独自のガーディアンまたはユーザー承認パスへフォールスルーする。 +`PermissionRequest` では、OpenClaw はポリシーが判断した場合にのみ、明示的な許可または拒否の決定を返します。決定なしの結果は許可ではありません。Codex はそれをフック判断なしとして扱い、自身のガーディアンまたはユーザー承認パスにフォールスルーします。 -Codex MCP ツール承認の elicitation は、Codex が `_meta.codex_approval_kind` を `"mcp_tool_call"` としてマークした場合、OpenClaw の Plugin 承認フローを通じてルーティングされる。Codex の `request_user_input` プロンプトは元のチャットへ送り返され、次にキューされたフォローアップメッセージは、追加コンテキストとしてステアリングされる代わりに、そのネイティブサーバーリクエストに回答する。他の MCP elicitation リクエストは引き続き fail closed する。 +Codex MCP ツール承認の要求は、Codex が `_meta.codex_approval_kind` を `"mcp_tool_call"` としてマークした場合、OpenClaw の Plugin 承認フローを通してルーティングされます。Codex の `request_user_input` プロンプトは発信元チャットに送り返され、次にキューに入ったフォローアップメッセージは、追加コンテキストとして誘導されるのではなく、そのネイティブサーバーリクエストに回答します。その他の MCP 要求リクエストは引き続き安全側に失敗します。 -アクティブ実行キューステアリングは Codex app-server の `turn/steer` に対応する。デフォルトの `messages.queue.mode: "steer"` では、OpenClaw は設定された静音ウィンドウの間、キューされたチャットメッセージをまとめ、到着順に 1 つの `turn/steer` リクエストとして送信する。レガシーの `queue` モードは個別の `turn/steer` リクエストを送信する。Codex レビューと手動 Compaction ターンは同一ターンのステアリングを拒否する場合があり、その場合 OpenClaw は選択されたモードでフォールバックが許可されているときにフォローアップキューを使用する。[ステアリングキュー](/ja-JP/concepts/queue-steering)を参照。 +アクティブ実行キューの誘導は、Codex app-server の `turn/steer` に対応します。デフォルトの `messages.queue.mode: "steer"` では、OpenClaw は設定済みの静穏ウィンドウ中にキュー化されたチャットメッセージをまとめ、到着順に 1 つの `turn/steer` リクエストとして送信します。レガシーの `queue` モードでは、個別の `turn/steer` リクエストを送信します。Codex のレビューターンと手動 Compaction ターンは同一ターンの誘導を拒否することがあり、その場合、選択されたモードでフォールバックが許可されていれば OpenClaw はフォローアップキューを使用します。[誘導キュー](/ja-JP/concepts/queue-steering)を参照してください。 -選択したモデルが Codex ハーネスを使用する場合、ネイティブスレッド Compaction は Codex app-server に委任される。OpenClaw はチャンネル履歴、検索、`/new`、`/reset`、および将来のモデルまたはハーネス切り替えのためにトランスクリプトミラーを保持する。ミラーには、ユーザープロンプト、最終アシスタントテキスト、および app-server が出力する場合の軽量な Codex 推論または計画レコードが含まれる。現在、OpenClaw はネイティブ Compaction の開始と完了シグナルのみを記録する。Codex が Compaction 後に保持したエントリーについて、人間が読める Compaction 要約や監査可能なリストはまだ公開していない。 +選択されたモデルが Codex ハーネスを使用する場合、ネイティブスレッド Compaction は Codex app-server に委任されます。OpenClaw はチャンネル履歴、検索、`/new`、`/reset`、将来のモデルまたはハーネス切り替えのために transcript ミラーを保持します。このミラーには、ユーザープロンプト、最終アシスタントテキスト、app-server が発行した場合の軽量な Codex 推論または計画レコードが含まれます。現時点では、OpenClaw はネイティブ Compaction の開始および完了シグナルのみを記録します。人間が読める Compaction 要約や、Compaction 後に Codex が保持したエントリの監査可能なリストはまだ公開していません。 -Codex が正規のネイティブスレッドを所有するため、`tool_result_persist` は現在、Codex ネイティブのツール結果レコードを書き換えない。これは OpenClaw が所有するセッショントランスクリプトのツール結果を OpenClaw が書き込む場合にのみ適用される。 +Codex が正規のネイティブスレッドを所有するため、`tool_result_persist` は現在 Codex ネイティブツール結果レコードを書き換えません。これは OpenClaw が所有するセッション transcript のツール結果を OpenClaw が書き込む場合にのみ適用されます。 -メディア生成に PI は不要。画像、動画、音楽、PDF、TTS、メディア理解は、`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel`、`messages.tts` など、対応するプロバイダー/モデル設定を引き続き使用する。 +メディア生成に PI は必要ありません。画像、動画、音楽、PDF、TTS、メディア理解は、`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel`、`messages.tts` などの対応するプロバイダー/モデル設定を引き続き使用します。 ## トラブルシューティング -**Codex が通常の `/model` プロバイダーとして表示されない:** 新しい設定では想定どおり。`agentRuntime.id: "codex"` を指定した `openai/gpt-*` モデル（またはレガシーの `codex/*` ref）を選択し、`plugins.entries.codex.enabled` を有効にし、`plugins.allow` が `codex` を除外していないか確認する。 +**Codex が通常の `/model` プロバイダーとして表示されない:** 新しい設定では想定どおりです。`agentRuntime.id: "codex"` を指定した `openai/gpt-*` モデル（またはレガシーの `codex/*` 参照）を選択し、`plugins.entries.codex.enabled` を有効にして、`plugins.allow` が `codex` を除外していないか確認してください。 -**OpenClaw が Codex ではなく PI を使用する:** `agentRuntime.id: "auto"` は、Codex ハーネスが実行を要求しない場合、互換性バックエンドとして引き続き PI を使用できる。テスト中に Codex 選択を強制するには `agentRuntime.id: "codex"` を設定する。強制された Codex ランタイムは、`agentRuntime.fallback: "pi"` を明示的に設定しない限り、PI へフォールバックせず失敗するようになった。Codex app-server が選択されると、その失敗は追加のフォールバック設定なしで直接表面化する。 +**OpenClaw が Codex ではなく PI を使用する:** `agentRuntime.id: "auto"` は、どの Codex ハーネスも実行を引き受けない場合、互換性バックエンドとして引き続き PI を使用できます。テスト中に Codex の選択を強制するには、`agentRuntime.id: "codex"` を設定します。強制された Codex ランタイムは、`agentRuntime.fallback: "pi"` を明示的に設定しない限り、PI にフォールバックせず失敗するようになりました。Codex app-server が選択されると、その失敗は追加のフォールバック設定なしで直接表面化します。 -**app-server が拒否される:** app-server ハンドシェイクがバージョン `0.125.0` 以降を報告するように Codex をアップグレードする。同一バージョンのプレリリースや、`0.125.0-alpha.2` または `0.125.0+custom` のようなビルドサフィックス付きバージョンは拒否される。OpenClaw がテストする安定版のプロトコル下限が `0.125.0` だからである。 +**app-server が拒否される:** Codex をアップグレードして、app-server ハンドシェイクがバージョン `0.125.0` 以降を報告するようにしてください。`0.125.0-alpha.2` や `0.125.0+custom` などの同一バージョンのプレリリースやビルドサフィックス付きバージョンは、安定版 `0.125.0` のプロトコル下限が OpenClaw のテスト対象であるため拒否されます。 -**モデル検出が遅い:** `plugins.entries.codex.config.discovery.timeoutMs` を下げるか、検出を無効にする。 +**モデル検出が遅い:** `plugins.entries.codex.config.discovery.timeoutMs` を下げるか、検出を無効にしてください。 -**WebSocket トランスポートが即座に失敗する:** `appServer.url`、`authToken`、およびリモート app-server が同じ Codex app-server プロトコルバージョンを話していることを確認する。 +**WebSocket トランスポートが即座に失敗する:** `appServer.url`、`authToken`、リモート app-server が同じ Codex app-server プロトコルバージョンを話していることを確認してください。 -**Codex 以外のモデルが PI を使用する:** そのエージェントに対して `agentRuntime.id: "codex"` を強制した場合、またはレガシーの `codex/*` ref を選択した場合を除き、これは想定どおり。通常の `openai/gpt-*` とその他のプロバイダー ref は、`auto` モードでは通常のプロバイダーパスに留まる。`agentRuntime.id: "codex"` を強制する場合、そのエージェントのすべての組み込みターンは Codex がサポートする OpenAI モデルでなければならない。 +**非 Codex モデルが PI を使用する:** そのエージェントに `agentRuntime.id: "codex"` を強制しているか、レガシーの `codex/*` 参照を選択している場合を除き、これは想定どおりです。通常の `openai/gpt-*` とその他のプロバイダー参照は、`auto` モードでは通常のプロバイダーパスに留まります。`agentRuntime.id: "codex"` を強制する場合、そのエージェントのすべての組み込みターンは Codex 対応の OpenAI モデルである必要があります。 -**Computer Use はインストールされているがツールが実行されない:** 新しいセッションから `/codex computer-use status` を確認する。ツールが `Native hook relay unavailable` を報告する場合は `/new` または `/reset` を使用する。継続する場合は、古いネイティブフック登録をクリアするために Gateway を再起動する。`computer-use.list_apps` がタイムアウトする場合は、Codex Computer Use または Codex Desktop を再起動して再試行する。 +**Computer Use はインストールされているがツールが実行されない:** 新しいセッションから `/codex computer-use status` を確認してください。ツールが `Native hook relay unavailable` を報告する場合は、`/new` または `/reset` を使用してください。それでも続く場合は、Gateway を再起動して古いネイティブフック登録をクリアしてください。`computer-use.list_apps` がタイムアウトする場合は、Codex Computer Use または Codex Desktop を再起動して再試行してください。 ## 関連 diff --git a/docs/ja-JP/plugins/google-meet.md b/docs/ja-JP/plugins/google-meet.md index 7835c8ae6..53d58b7af 100644 --- a/docs/ja-JP/plugins/google-meet.md +++ b/docs/ja-JP/plugins/google-meet.md @@ -1,31 +1,31 @@ --- read_when: - OpenClaw エージェントを Google Meet 通話に参加させたい - - OpenClawエージェントに新しい Google Meet の通話を作成させたい - - Google Meet トランスポートとして Chrome、Chrome ノード、または Twilio を設定しています -summary: 'Google Meet Plugin: Chrome または Twilio 経由で明示的な Meet URL に参加し、リアルタイム音声のデフォルトを使用' -title: Google Meet Plugin + - OpenClaw エージェントに新しい Google Meet 通話を作成させたい + - Chrome、Chrome ノード、または Twilio を Google Meet のトランスポートとして設定しています +summary: 'Google Meet Plugin: 明示的な Meet URL に Chrome または Twilio 経由で参加し、リアルタイム音声のデフォルトを使用' +title: Google Meet プラグイン x-i18n: - generated_at: "2026-04-30T05:25:17Z" + generated_at: "2026-05-01T05:02:53Z" model: gpt-5.5 provider: openai - source_hash: 7b989c872fee0dca31680f67559cd26b715303f7c6f4eeda51fc63889bb0383c + source_hash: 7eb6e48964d9592562fad1cebeadd765f2a2bcea9bfe887153e65438bfeaa617 source_path: plugins/google-meet.md workflow: 16 --- -Google Meet 参加者サポート for OpenClaw は、設計上明示的な Plugin です: +OpenClaw の Google Meet 参加者サポート — この Plugin は設計上明示的です: - 明示的な `https://meet.google.com/...` URL にのみ参加します。 - Google Meet API を通じて新しい Meet スペースを作成し、返された URL に参加できます。 -- `realtime` 音声がデフォルトモードです。 -- Realtime 音声は、より深い推論やツールが必要なときに、完全な OpenClaw エージェントへコールバックできます。 -- エージェントは `mode` で参加動作を選択します。ライブで聞く/話し返すには `realtime` を使用し、リアルタイム音声ブリッジなしでブラウザに参加/制御するには `transcribe` を使用します。 -- 認証は個人の Google OAuth、またはすでにサインイン済みの Chrome プロファイルから始まります。 +- `realtime` 音声がデフォルトのモードです。 +- より深い推論やツールが必要な場合、リアルタイム音声は完全な OpenClaw エージェントにコールバックできます。 +- エージェントは `mode` で参加動作を選択します。ライブの聞き取り/応答には `realtime` を使い、リアルタイム音声ブリッジなしでブラウザーへ参加/制御するには `transcribe` を使います。 +- 認証は個人の Google OAuth、またはすでにログイン済みの Chrome プロファイルとして開始します。 - 自動の同意アナウンスはありません。 - デフォルトの Chrome 音声バックエンドは `BlackHole 2ch` です。 -- Chrome はローカルまたはペアリング済みノードホストで実行できます。 -- Twilio はダイヤルイン番号に加え、任意の PIN または DTMF シーケンスを受け付けます。 +- Chrome はローカルでも、ペアリング済みのノードホスト上でも実行できます。 +- Twilio はダイヤルイン番号に加えて任意の PIN または DTMF シーケンスを受け付けます。 - CLI コマンドは `googlemeet` です。`meet` は、より広範なエージェントの電話会議ワークフロー用に予約されています。 ## クイックスタート @@ -52,7 +52,7 @@ system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Plugin を有効化します: +Plugin を有効にします: ```json5 { @@ -73,21 +73,21 @@ Plugin を有効化します: openclaw googlemeet setup ``` -セットアップ出力は、エージェントが読めてモードを意識したものになるよう意図されています。Chrome プロファイル、ノード固定、そしてリアルタイム Chrome 参加の場合は BlackHole/SoX 音声ブリッジと遅延リアルタイムイントロチェックを報告します。観察のみの参加では、同じトランスポートを `--mode transcribe` で確認します。このモードはブリッジ経由で聞いたり話したりしないため、リアルタイム音声の前提条件をスキップします: +セットアップ出力は、エージェントが読み取れる形式で、モードを認識することを意図しています。Chrome プロファイル、ノード固定、リアルタイム Chrome 参加の場合は BlackHole/SoX 音声ブリッジと遅延リアルタイムイントロのチェックを報告します。監視のみの参加では、同じトランスポートを `--mode transcribe` で確認します。このモードはブリッジを通じて聞いたり話したりしないため、リアルタイム音声の前提条件をスキップします: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` -Twilio 委任が設定されている場合、セットアップは `voice-call` Plugin と Twilio 認証情報の準備状況も報告します。エージェントに参加を依頼する前に、`ok: false` のチェックはすべて、確認対象のトランスポートとモードに対するブロッカーとして扱ってください。スクリプトまたは機械可読出力には `openclaw googlemeet setup --json` を使用します。エージェントが試行する前に特定のトランスポートを事前確認するには、`--transport chrome`、`--transport chrome-node`、または `--transport twilio` を使用します。 +Twilio 委任が設定されている場合、セットアップは `voice-call` Plugin と Twilio 認証情報の準備状況も報告します。エージェントに参加を依頼する前に、`ok: false` のチェックは、チェック対象のトランスポートとモードに対するブロッカーとして扱ってください。スクリプトまたは機械可読出力には `openclaw googlemeet setup --json` を使います。エージェントが試行する前に特定のトランスポートを事前確認するには、`--transport chrome`、`--transport chrome-node`、または `--transport twilio` を使います。 -ミーティングに参加します: +会議に参加します: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -または、`google_meet` ツール経由でエージェントに参加させます: +または、エージェントに `google_meet` ツール経由で参加させます: ```json { @@ -98,13 +98,13 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij } ``` -新しいミーティングを作成して参加します: +新しい会議を作成して参加します: ```bash openclaw googlemeet create --transport chrome-node --mode realtime ``` -参加せずに URL のみを作成します: +参加せずに URL だけを作成します: ```bash openclaw googlemeet create --no-join @@ -112,12 +112,11 @@ openclaw googlemeet create --no-join `googlemeet create` には 2 つの経路があります: -- API 作成: Google Meet OAuth 認証情報が設定されている場合に使用されます。これは最も決定的な経路であり、ブラウザ UI の状態に依存しません。 -- ブラウザフォールバック: OAuth 認証情報がない場合に使用されます。OpenClaw は固定された Chrome ノードを使用し、`https://meet.google.com/new` を開き、Google が実際のミーティングコード URL にリダイレクトするのを待ってから、その URL を返します。この経路では、ノード上の OpenClaw Chrome プロファイルがすでに Google にサインインしている必要があります。 - ブラウザ自動化は Meet 自身の初回マイクプロンプトを処理します。そのプロンプトは Google ログイン失敗として扱われません。 - 参加フローと作成フローは、新しいタブを開く前に既存の Meet タブの再利用も試みます。照合では `authuser` などの無害な URL クエリ文字列を無視するため、エージェントの再試行では、2 つ目の Chrome タブを作成する代わりに、すでに開いているミーティングにフォーカスされるはずです。 +- API 作成: Google Meet OAuth 認証情報が設定されている場合に使われます。これは最も決定的な経路で、ブラウザー UI の状態に依存しません。 +- ブラウザーフォールバック: OAuth 認証情報がない場合に使われます。OpenClaw は固定された Chrome ノードを使い、`https://meet.google.com/new` を開き、Google が実際の会議コード URL にリダイレクトするのを待ってから、その URL を返します。この経路では、ノード上の OpenClaw Chrome プロファイルがすでに Google にログインしている必要があります。ブラウザー自動化は Meet 独自の初回マイクプロンプトを処理します。そのプロンプトは Google ログイン失敗として扱われません。 + 参加フローと作成フローでは、新しいタブを開く前に既存の Meet タブの再利用も試みます。照合では `authuser` などの無害な URL クエリ文字列を無視するため、エージェントの再試行では 2 つ目の Chrome タブを作成するのではなく、すでに開いている会議にフォーカスするはずです。 -コマンド/ツール出力には `source` フィールド（`api` または `browser`）が含まれるため、エージェントはどの経路が使用されたかを説明できます。`create` はデフォルトで新しいミーティングに参加し、`joined: true` と参加セッションを返します。URL の発行だけを行うには、CLI で `create --no-join` を使用するか、ツールに `"join": false` を渡します。 +コマンド/ツール出力には `source` フィールド（`api` または `browser`）が含まれるため、エージェントはどの経路が使われたかを説明できます。`create` はデフォルトで新しい会議に参加し、`joined: true` と参加セッションを返します。URL だけを発行するには、CLI で `create --no-join` を使うか、ツールに `"join": false` を渡します。 または、エージェントに「Google Meet を作成し、リアルタイム音声で参加して、リンクを送って」と伝えます。エージェントは `action: "create"` で `google_meet` を呼び出し、返された `meetingUri` を共有する必要があります。 @@ -129,21 +128,21 @@ openclaw googlemeet create --no-join } ``` -観察のみ/ブラウザ制御の参加では、`"mode": "transcribe"` を設定します。これは双方向リアルタイムモデルブリッジを開始せず、BlackHole や SoX を必要とせず、ミーティングに話しかけません。このモードでの Chrome 参加は、OpenClaw のマイク/カメラ権限付与も避け、Meet の **Use microphone** 経路も避けます。Meet が音声選択の中間画面を表示した場合、自動化はマイクなしの経路を試し、それ以外の場合はローカルマイクを開く代わりに手動操作を報告します。 +監視のみ/ブラウザー制御の参加では、`"mode": "transcribe"` を設定します。これは双方向リアルタイムモデルブリッジを開始せず、BlackHole や SoX を必要とせず、会議内で応答しません。このモードでの Chrome 参加では、OpenClaw のマイク/カメラ権限付与も避け、Meet の **マイクを使用** 経路も避けます。Meet が音声選択の中間画面を表示した場合、自動化はマイクなしの経路を試し、それ以外の場合はローカルマイクを開くのではなく手動操作を報告します。 -リアルタイムセッション中、`google_meet` のステータスには、`inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最後の入力/出力タイムスタンプ、バイトカウンター、ブリッジのクローズ状態など、ブラウザと音声ブリッジの健全性が含まれます。安全な Meet ページプロンプトが表示された場合、ブラウザ自動化は可能な範囲で処理します。ログイン、ホスト承認、ブラウザ/OS 権限プロンプトは、エージェントが中継するための理由とメッセージ付きの手動操作として報告されます。管理対象の Chrome セッションは、ブラウザ健全性が `inCall: true` を報告した後にのみイントロまたはテストフレーズを出力します。それ以外の場合、ステータスは `speechReady: false` を報告し、エージェントがミーティングで話したふりをする代わりに発話試行はブロックされます。 +リアルタイムセッション中、`google_meet` のステータスには、`inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最終入出力タイムスタンプ、バイトカウンター、ブリッジのクローズ状態など、ブラウザーと音声ブリッジのヘルスが含まれます。安全な Meet ページプロンプトが表示された場合、ブラウザー自動化は可能なときにそれを処理します。ログイン、ホスト承認、ブラウザー/OS 権限プロンプトは、エージェントが中継するための理由とメッセージ付きで手動操作として報告されます。管理対象の Chrome セッションは、ブラウザーのヘルスが `inCall: true` を報告した後にのみイントロまたはテストフレーズを発します。そうでない場合、ステータスは `speechReady: false` を報告し、エージェントが会議で話したふりをするのではなく、発話の試行はブロックされます。 -ローカル Chrome 参加は、サインイン済みの OpenClaw ブラウザプロファイル経由で行われます。Realtime モードでは、OpenClaw が使用するマイク/スピーカー経路に `BlackHole 2ch` が必要です。クリーンな双方向音声には、別々の仮想デバイスまたは Loopback 風のグラフを使用してください。最初のスモークテストには単一の BlackHole デバイスで十分ですが、エコーが発生する可能性があります。 +ローカル Chrome は、ログイン済みの OpenClaw ブラウザープロファイルを通じて参加します。リアルタイムモードには、OpenClaw が使うマイク/スピーカー経路として `BlackHole 2ch` が必要です。クリーンな双方向音声には、別々の仮想デバイスまたは Loopback スタイルのグラフを使います。単一の BlackHole デバイスでも最初のスモークテストには十分ですが、エコーする可能性があります。 ### ローカル Gateway + Parallels Chrome -VM に Chrome を所有させるだけなら、macOS VM 内に完全な OpenClaw Gateway やモデル API キーは必要ありません。Gateway とエージェントをローカルで実行し、VM でノードホストを実行します。VM 上でバンドルされた Plugin を一度有効化し、ノードが Chrome コマンドを広告するようにします: +VM に Chrome を所有させるだけなら、macOS VM 内に完全な OpenClaw Gateway やモデル API キーは必要ありません。Gateway とエージェントはローカルで実行し、VM 内でノードホストを実行します。ノードが Chrome コマンドを公開するよう、VM 上で同梱 Plugin を一度有効にします: どこで何を実行するか: - Gateway ホスト: OpenClaw Gateway、エージェントワークスペース、モデル/API キー、リアルタイムプロバイダー、Google Meet Plugin 設定。 -- Parallels macOS VM: OpenClaw CLI/ノードホスト、Google Chrome、SoX、BlackHole 2ch、Google にサインイン済みの Chrome プロファイル。 -- VM で不要なもの: Gateway サービス、エージェント設定、OpenAI/GPT キー、モデルプロバイダー設定。 +- Parallels macOS VM: OpenClaw CLI/ノードホスト、Google Chrome、SoX、BlackHole 2ch、Google にログイン済みの Chrome プロファイル。 +- VM 内で不要なもの: Gateway サービス、エージェント設定、OpenAI/GPT キー、モデルプロバイダー設定。 VM の依存関係をインストールします: @@ -164,7 +163,7 @@ system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -VM に OpenClaw をインストールまたは更新し、その後、そこでバンドルされた Plugin を有効化します: +VM に OpenClaw をインストールまたは更新し、その後、同梱 Plugin をそこで有効にします: ```bash openclaw plugins enable google-meet @@ -176,14 +175,14 @@ VM でノードホストを開始します: openclaw node run --host --port 18789 --display-name parallels-macos ``` -`` が LAN IP で、TLS を使用していない場合、その信頼済みプライベートネットワークにオプトインしない限り、ノードは平文 WebSocket を拒否します: +`` が LAN IP で、TLS を使っていない場合、その信頼済みプライベートネットワークに明示的に同意しない限り、ノードは平文 WebSocket を拒否します: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -ノードを LaunchAgent としてインストールするときも同じ環境変数を使用します: +ノードを LaunchAgent としてインストールする場合も、同じ環境変数を使います: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -191,7 +190,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` はプロセス環境であり、`openclaw.json` 設定ではありません。`openclaw node install` は、それがインストールコマンドに存在する場合、LaunchAgent 環境に保存します。 +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` はプロセス環境であり、`openclaw.json` 設定ではありません。`openclaw node install` は、インストールコマンド上に存在する場合、それを LaunchAgent 環境に保存します。 Gateway ホストからノードを承認します: @@ -200,7 +199,7 @@ openclaw devices list openclaw devices approve ``` -Gateway がノードを認識し、そのノードが `googlemeet.chrome` とブラウザ機能/`browser.proxy` の両方を広告していることを確認します: +Gateway がノードを認識し、そのノードが `googlemeet.chrome` とブラウザー機能/`browser.proxy` の両方を公開していることを確認します: ```bash openclaw nodes status @@ -242,90 +241,88 @@ Gateway ホストで Meet をそのノード経由にルーティングします openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -または、`transport: "chrome-node"` で `google_meet` ツールを使用するようエージェントに依頼します。 +または、エージェントに `transport: "chrome-node"` で `google_meet` ツールを使うよう依頼します。 -セッションを作成または再利用し、既知のフレーズを発話し、セッション健全性を出力するワンコマンドのスモークテストには、次を使用します: +セッションを作成または再利用し、既知のフレーズを話し、セッションヘルスを出力する 1 コマンドのスモークテスト: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -リアルタイム参加中、OpenClaw のブラウザ自動化はゲスト名を入力し、参加/参加をリクエストをクリックし、そのプロンプトが表示された場合は Meet の初回「Use microphone」選択を受け入れます。観察のみの参加またはブラウザのみのミーティング作成中は、利用可能な場合、同じプロンプトをマイクなしで先に進みます。ブラウザプロファイルがサインインしていない、Meet がホスト承認を待っている、リアルタイム参加のために Chrome がマイク/カメラ権限を必要としている、または Meet が自動化で解決できないプロンプトで止まっている場合、参加/test-speech の結果は `manualActionRequired: true` を `manualActionReason` と `manualActionMessage` とともに報告します。エージェントは参加の再試行を停止し、その正確なメッセージと現在の `browserUrl`/`browserTitle` を報告し、手動ブラウザ操作が完了した後にのみ再試行する必要があります。 +リアルタイム参加中、OpenClaw のブラウザー自動化はゲスト名を入力し、参加/参加をリクエストをクリックし、Meet の初回「マイクを使用」選択肢が表示された場合はそれを受け入れます。監視のみの参加またはブラウザーのみの会議作成中は、利用可能であれば、同じプロンプトをマイクなしで進みます。ブラウザープロファイルがログインしていない、Meet がホスト承認を待っている、Chrome がリアルタイム参加のためにマイク/カメラ権限を必要としている、または Meet が自動化で解決できないプロンプトで止まっている場合、参加/test-speech 結果は `manualActionRequired: true` を `manualActionReason` と `manualActionMessage` 付きで報告します。エージェントは参加の再試行を停止し、その正確なメッセージと現在の `browserUrl`/`browserTitle` を報告し、手動のブラウザー操作が完了した後にのみ再試行する必要があります。 -`chromeNode.node` が省略されている場合、OpenClaw は、接続済みノードのうち `googlemeet.chrome` とブラウザ制御の両方を広告するものがちょうど 1 つの場合にのみ自動選択します。複数の対応ノードが接続されている場合は、`chromeNode.node` をノード ID、表示名、またはリモート IP に設定します。 +`chromeNode.node` を省略した場合、OpenClaw は、接続済みノードのうち `googlemeet.chrome` とブラウザー制御の両方を公開しているものが 1 つだけのときに限り、自動選択します。対応可能なノードが複数接続されている場合は、`chromeNode.node` にノード ID、表示名、またはリモート IP を設定します。 一般的な失敗チェック: -- `Configured Google Meet node ... is not usable: offline`: ピン留めされたノードは +- `Configured Google Meet node ... is not usable: offline`: 固定されたノードは Gateway に認識されていますが利用できません。エージェントはそのノードを - 利用可能な Chrome ホストとしてではなく診断状態として扱い、ユーザーが求めていない限り - 別のトランスポートへフォールバックせず、セットアップのブロッカーを報告する必要があります。 -- `No connected Google Meet-capable node`: VM 内で `openclaw node run` を開始し、 - ペアリングを承認し、VM 内で `openclaw plugins enable google-meet` と - `openclaw plugins enable browser` が実行済みであることを確認します。また、 + 利用可能な Chrome ホストではなく診断状態として扱い、ユーザーがそれを求めた場合を除き、 + 別のトランスポートへフォールバックするのではなくセットアップのブロッカーを報告する必要があります。 +- `No connected Google Meet-capable node`: VM で `openclaw node run` を開始し、 + ペアリングを承認して、VM で `openclaw plugins enable google-meet` と + `openclaw plugins enable browser` が実行済みであることを確認します。さらに、 Gateway ホストが `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` で両方のノードコマンドを許可していることも確認します。 -- `BlackHole 2ch audio device not found`: チェック対象のホストに `blackhole-2ch` をインストールし、 - local Chrome 音声を使う前に再起動します。 +- `BlackHole 2ch audio device not found`: 確認対象のホストに `blackhole-2ch` をインストールし、 + ローカル Chrome 音声を使う前に再起動します。 - `BlackHole 2ch audio device not found on the node`: VM に `blackhole-2ch` をインストールし、 VM を再起動します。 -- Chrome は開くが参加できない場合: VM 内のブラウザープロファイルにサインインするか、 +- Chrome は開くが参加できない: VM 内のブラウザープロファイルでログインするか、 ゲスト参加用に `chrome.guestName` を設定したままにします。ゲストの自動参加は、 - ノードのブラウザープロキシ経由で OpenClaw のブラウザー自動化を使います。ノードのブラウザー - config が目的のプロファイルを指していることを確認してください。たとえば + ノードブラウザープロキシ経由で OpenClaw のブラウザー自動操作を使用します。ノードブラウザー設定が目的のプロファイルを指していることを確認してください。たとえば `browser.defaultProfile: "user"` または名前付きの既存セッションプロファイルです。 -- Meet タブが重複する場合: `chrome.reuseExistingTab: true` を有効のままにします。OpenClaw は - 新しいタブを開く前に同じ Meet URL の既存タブをアクティブにし、ブラウザーによる会議作成でも - 別のタブを開く前に進行中の `https://meet.google.com/new` +- Meet タブが重複する: `chrome.reuseExistingTab: true` を有効にしたままにします。OpenClaw は + 新しいタブを開く前に同じ Meet URL の既存タブをアクティブ化し、 + ブラウザーでの会議作成では、別のタブを開く前に進行中の `https://meet.google.com/new` または Google アカウントのプロンプトタブを再利用します。 -- 音声がない場合: Meet で、マイクとスピーカーを OpenClaw が使用する仮想オーディオデバイスの - パスにルーティングします。クリーンな双方向音声には、別々の仮想デバイスまたは Loopback 形式の - ルーティングを使用します。 +- 音声がない: Meet で、マイクとスピーカーの音声を OpenClaw が使用する仮想音声デバイス + パスにルーティングします。クリーンな双方向音声には、別々の仮想デバイスまたは Loopback 形式のルーティングを使用します。 ## インストールメモ -Chrome realtime のデフォルトは、2 つの外部ツールを使用します。 +Chrome リアルタイムのデフォルトでは、2 つの外部ツールを使用します。 -- `sox`: コマンドライン音声ユーティリティ。Plugin はデフォルトの 24 kHz PCM16 音声ブリッジに - 明示的な CoreAudio デバイスコマンドを使用します。 -- `blackhole-2ch`: macOS 仮想オーディオドライバー。Chrome/Meet がルーティングできる - `BlackHole 2ch` オーディオデバイスを作成します。 +- `sox`: コマンドライン音声ユーティリティ。Plugin は、デフォルトの 24 kHz PCM16 音声ブリッジに明示的な CoreAudio + デバイスコマンドを使用します。 +- `blackhole-2ch`: macOS 仮想音声ドライバー。Chrome/Meet がルーティングできる `BlackHole 2ch` + 音声デバイスを作成します。 -OpenClaw はどちらのパッケージもバンドルまたは再配布しません。docs では、ユーザーに -Homebrew 経由でホスト依存関係としてインストールするよう案内しています。SoX のライセンスは -`LGPL-2.0-only AND GPL-2.0-only` です。BlackHole は GPL-3.0 です。BlackHole を -OpenClaw と一緒にバンドルするインストーラーやアプライアンスを構築する場合は、BlackHole の -アップストリームのライセンス条件を確認するか、Existential Audio から別ライセンスを取得してください。 +OpenClaw はどちらのパッケージもバンドルまたは再配布しません。ドキュメントでは、 +ユーザーに Homebrew 経由でホスト依存関係としてインストールするよう案内しています。SoX は +`LGPL-2.0-only AND GPL-2.0-only` としてライセンスされ、BlackHole は GPL-3.0 です。BlackHole を OpenClaw と一緒にバンドルする +インストーラーまたはアプライアンスを構築する場合は、BlackHole の +アップストリームライセンス条件を確認するか、Existential Audio から別途ライセンスを取得してください。 ## トランスポート ### Chrome -Chrome トランスポートは、OpenClaw のブラウザー制御を通じて Meet URL を開き、サインイン済みの -OpenClaw ブラウザープロファイルとして参加します。macOS では、Plugin は起動前に -`BlackHole 2ch` を確認します。構成されている場合は、Chrome を開く前に音声ブリッジの -ヘルスコマンドと起動コマンドも実行します。Chrome/音声が Gateway ホスト上にある場合は -`chrome` を使用し、Chrome/音声が Parallels macOS VM などのペアリング済みノード上にある場合は -`chrome-node` を使用します。local Chrome の場合は `browser.defaultProfile` で -プロファイルを選択します。`chrome.browserProfile` は `chrome-node` ホストに渡されます。 +Chrome トランスポートは、OpenClaw ブラウザー制御を通じて Meet URL を開き、 +ログイン済みの OpenClaw ブラウザープロファイルとして参加します。macOS では、Plugin が起動前に +`BlackHole 2ch` を確認します。設定されている場合は、Chrome を開く前に音声ブリッジ +ヘルスコマンドと起動コマンドも実行します。Chrome/音声が Gateway ホスト上にある場合は `chrome` を使い、 +Chrome/音声が Parallels macOS VM などのペアリング済みノード上にある場合は `chrome-node` を使います。ローカル Chrome では、 +`browser.defaultProfile` でプロファイルを選択します。`chrome.browserProfile` は +`chrome-node` ホストに渡されます。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Chrome のマイクとスピーカー音声を local OpenClaw 音声ブリッジにルーティングします。 +Chrome のマイクとスピーカー音声をローカル OpenClaw 音声ブリッジにルーティングします。 `BlackHole 2ch` がインストールされていない場合、音声パスなしで黙って参加するのではなく、 -参加はセットアップエラーで失敗します。 +セットアップエラーで参加に失敗します。 ### Twilio Twilio トランスポートは、Voice Call Plugin に委譲される厳密なダイヤルプランです。 -電話番号を探すために Meet ページを解析しません。 +電話番号を探すために Meet ページを解析することはありません。 -Chrome 参加を利用できない場合、または電話ダイヤルインのフォールバックが必要な場合に使用します。 -Google Meet は会議の電話ダイヤルイン番号と PIN を公開している必要があります。OpenClaw は -Meet ページからそれらを検出しません。 +Chrome 参加が利用できない場合、または電話ダイヤルインのフォールバックが必要な場合に使用します。 +Google Meet は会議用の電話ダイヤルイン番号と PIN を公開している必要があります。 +OpenClaw は Meet ページからそれらを検出しません。 Voice Call Plugin は Chrome ノードではなく Gateway ホストで有効にします。 @@ -352,8 +349,8 @@ Voice Call Plugin は Chrome ノードではなく Gateway ホストで有効に } ``` -Twilio 認証情報は環境または config から提供します。環境変数を使うと、シークレットを -`openclaw.json` に入れずに済みます。 +Twilio 認証情報は環境変数または config で指定します。環境変数を使うと +シークレットを `openclaw.json` の外に保てます。 ```bash export TWILIO_ACCOUNT_SID=AC... @@ -361,10 +358,10 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -`voice-call` を有効にした後、Gateway を再起動またはリロードします。Plugin config の変更は、 -リロードされるまで、すでに実行中の Gateway プロセスには反映されません。 +`voice-call` を有効にした後、Gateway を再起動または再読み込みします。Plugin config の変更は、 +再読み込みされるまで、すでに実行中の Gateway プロセスには反映されません。 -次に検証します。 +次に確認します。 ```bash openclaw config validate @@ -382,7 +379,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -会議にカスタムシーケンスが必要な場合は、`--dtmf-sequence` を使用します。 +会議にカスタムシーケンスが必要な場合は `--dtmf-sequence` を使用します。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -391,20 +388,19 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -## OAuth と事前確認 +## OAuth とプリフライト -OAuth は、`googlemeet create` がブラウザー自動化にフォールバックできるため、 -Meet リンクの作成には任意です。公式 API による作成、スペース解決、または Meet Media API の -事前確認を行いたい場合に OAuth を構成します。 +`googlemeet create` はブラウザー自動操作へフォールバックできるため、Meet リンク作成に OAuth は任意です。 +公式 API による作成、スペース解決、または Meet Media API のプリフライトチェックが必要な場合に OAuth を設定します。 Google Meet API アクセスはユーザー OAuth を使用します。Google Cloud OAuth クライアントを作成し、 -必要なスコープをリクエストし、Google アカウントを認可してから、結果のリフレッシュトークンを -Google Meet Plugin config に保存するか、`OPENCLAW_GOOGLE_MEET_*` 環境変数を提供します。 +必要なスコープを要求し、Google アカウントを承認してから、生成されたリフレッシュトークンを +Google Meet Plugin config に保存するか、`OPENCLAW_GOOGLE_MEET_*` 環境変数を指定します。 -OAuth は Chrome 参加パスを置き換えません。Chrome と Chrome-node トランスポートは、 -ブラウザー参加を使う場合、引き続きサインイン済みの Chrome プロファイル、BlackHole/SoX、 -および接続済みノードを通じて参加します。OAuth は公式 Google Meet API パス専用です。 -会議スペースの作成、スペースの解決、Meet Media API の事前確認を行います。 +OAuth は Chrome 参加パスを置き換えません。Chrome および Chrome-node トランスポートは、 +ブラウザー参加を使う場合も、ログイン済み Chrome プロファイル、BlackHole/SoX、 +接続済みノードを通じて参加します。OAuth は公式 Google Meet API パス専用です。 +会議スペースの作成、スペース解決、Meet Media API プリフライトチェックを行います。 ### Google 認証情報を作成する @@ -412,16 +408,16 @@ Google Cloud Console で: 1. Google Cloud プロジェクトを作成または選択します。 2. そのプロジェクトで **Google Meet REST API** を有効にします。 -3. OAuth 同意画面を構成します。 - - **Internal** は Google Workspace 組織では最も簡単です。 - - **External** は個人/テスト構成で機能します。アプリが Testing の間は、 - アプリを認可する各 Google アカウントをテストユーザーとして追加します。 +3. OAuth 同意画面を設定します。 + - Google Workspace 組織では **Internal** が最も簡単です。 + - 個人/テスト環境では **External** が使えます。アプリが Testing の間は、 + アプリを承認する各 Google アカウントをテストユーザーとして追加します。 4. OpenClaw が要求するスコープを追加します。 - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` 5. OAuth クライアント ID を作成します。 - - アプリケーションタイプ: **Web application**。 + - アプリケーションの種類: **Web application**。 - 承認済みリダイレクト URI: ```text @@ -432,22 +428,22 @@ Google Cloud Console で: `meetings.space.created` は Google Meet `spaces.create` に必要です。 `meetings.space.readonly` により、OpenClaw は Meet URL/コードをスペースに解決できます。 -`meetings.conference.media.readonly` は Meet Media API の事前確認とメディア作業用です。 -実際の Media API 利用には、Google が Developer Preview への登録を要求する場合があります。 +`meetings.conference.media.readonly` は Meet Media API プリフライトとメディア作業用です。 +実際の Media API 使用には、Google が Developer Preview 登録を要求する場合があります。 ブラウザーベースの Chrome 参加だけが必要な場合は、OAuth を完全に省略してください。 ### リフレッシュトークンを発行する -`oauth.clientId` と必要に応じて `oauth.clientSecret` を構成するか、環境変数として渡してから、 -次を実行します。 +`oauth.clientId` と、必要に応じて `oauth.clientSecret` を設定するか、 +環境変数として渡してから、次を実行します。 ```bash openclaw googlemeet auth login --json ``` このコマンドは、リフレッシュトークンを含む `oauth` config ブロックを出力します。PKCE、 -`http://localhost:8085/oauth2callback` の localhost コールバック、および `--manual` による -手動コピー/貼り付けフローを使用します。 +`http://localhost:8085/oauth2callback` の localhost コールバック、 +および `--manual` による手動コピー/貼り付けフローを使用します。 例: @@ -457,7 +453,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -ブラウザーが local コールバックに到達できない場合は、手動モードを使用します。 +ブラウザーがローカルコールバックに到達できない場合は手動モードを使用します。 ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -501,48 +497,47 @@ JSON 出力には次が含まれます。 } ``` -リフレッシュトークンを config に入れたくない場合は、環境変数を優先します。config と環境値の -両方が存在する場合、Plugin はまず config を解決し、その後で環境フォールバックを使用します。 +リフレッシュトークンを config に入れたくない場合は、環境変数を優先してください。 +config と環境変数の両方に値が存在する場合、Plugin は最初に config を解決し、 +その後に環境変数へフォールバックします。 -OAuth 同意には、Meet スペース作成、Meet スペースの読み取りアクセス、Meet 会議メディアの -読み取りアクセスが含まれます。会議作成サポートが存在する前に認証していた場合は、 -`openclaw googlemeet auth login --json` を再実行し、リフレッシュトークンに -`meetings.space.created` スコープを持たせてください。 +OAuth 同意には、Meet スペース作成、Meet スペース読み取りアクセス、Meet +カンファレンスメディア読み取りアクセスが含まれます。会議作成サポートが存在する前に認証していた場合は、 +リフレッシュトークンが `meetings.space.created` スコープを持つように +`openclaw googlemeet auth login --json` を再実行してください。 -### doctor で OAuth を検証する +### doctor で OAuth を確認する -高速でシークレットを出力しないヘルスチェックが必要な場合は、OAuth doctor を実行します。 +高速でシークレットを含まないヘルスチェックが必要な場合は、OAuth doctor を実行します。 ```bash openclaw googlemeet doctor --oauth --json ``` -これは Chrome ランタイムを読み込まず、接続済みの Chrome ノードも必要としません。 -OAuth config が存在することと、リフレッシュトークンがアクセストークンを発行できることを -確認します。JSON レポートには、`ok`、`configured`、`tokenSource`、`expiresAt`、チェックメッセージなどの -ステータスフィールドのみが含まれます。アクセストークン、リフレッシュトークン、クライアントシークレットは -出力されません。 +これは Chrome ランタイムを読み込まず、接続済み Chrome ノードも必要としません。 +OAuth config が存在すること、およびリフレッシュトークンがアクセストークンを発行できることを確認します。 +JSON レポートには `ok`、`configured`、`tokenSource`、`expiresAt`、 +チェックメッセージなどのステータスフィールドのみが含まれます。アクセストークン、リフレッシュトークン、 +クライアントシークレットは出力しません。 一般的な結果: -| チェック | 意味 | -| -------------------- | --------------------------------------------------------------------------------------- | -| `oauth-config` | `oauth.clientId` と `oauth.refreshToken`、またはキャッシュ済みアクセストークンが存在します。 | -| `oauth-token` | キャッシュ済みアクセストークンがまだ有効、またはリフレッシュトークンが新しいアクセストークンを発行しました。 | -| `meet-spaces-get` | 任意の `--meeting` チェックが既存の Meet スペースを解決しました。 | -| `meet-spaces-create` | 任意の `--create-space` チェックが新しい Meet スペースを作成しました。 | +| チェック | 意味 | +| -------------------- | ---------------------------------------------------------------------------------------------- | +| `oauth-config` | `oauth.clientId` と `oauth.refreshToken`、またはキャッシュ済みアクセストークンが存在します。 | +| `oauth-token` | キャッシュ済みアクセストークンがまだ有効であるか、リフレッシュトークンが新しいアクセストークンを発行しました。 | +| `meet-spaces-get` | 任意の `--meeting` チェックが既存の Meet スペースを解決しました。 | +| `meet-spaces-create` | 任意の `--create-space` チェックが新しい Meet スペースを作成しました。 | -Google Meet API の有効化と `spaces.create` スコープも証明するには、副作用のある作成チェックを -実行します。 +Google Meet API の有効化と `spaces.create` スコープも証明するには、副作用のある作成チェックを実行します。 ```bash openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` は使い捨ての Meet URL を作成します。Google Cloud プロジェクトで Meet API が -有効であることと、認可済みアカウントに `meetings.space.created` スコープがあることを -確認する必要がある場合に使用します。 +`--create-space` は使い捨ての Meet URL を作成します。Google Cloud プロジェクトで Meet API が有効であり、 +承認済みアカウントが `meetings.space.created` スコープを持つことを確認する必要がある場合に使用します。 既存の会議スペースへの読み取りアクセスを証明するには: @@ -551,15 +546,14 @@ openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hi openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` と `resolve-space` は、認可済み Google アカウントがアクセスできる -既存スペースへの読み取りアクセスを証明します。これらのチェックからの `403` は通常、 -Google Meet REST API が無効、同意済みリフレッシュトークンに必要なスコープがない、または -Google アカウントがその Meet スペースにアクセスできないことを意味します。リフレッシュトークンの -エラーは、`openclaw googlemeet auth login --json` を再実行して新しい `oauth` ブロックを -保存する必要があることを意味します。 +`doctor --oauth --meeting` と `resolve-space` は、承認済み Google アカウントがアクセスできる既存スペースへの読み取りアクセスを証明します。これらのチェックからの `403` は通常、 +Google Meet REST API が無効である、同意済みリフレッシュトークンに必要なスコープがない、 +または Google アカウントがその Meet スペースにアクセスできないことを意味します。リフレッシュトークンエラーは、 +`openclaw googlemeet auth login +--json` を再実行し、新しい `oauth` ブロックを保存する必要があることを意味します。 -ブラウザーフォールバックには OAuth 認証情報は不要です。このモードでは、Google 認証は -OpenClaw config からではなく、選択されたノード上のサインイン済み Chrome プロファイルから取得されます。 +ブラウザーフォールバックには OAuth 認証情報は不要です。このモードでは、Google +認証は OpenClaw config ではなく、選択されたノード上のログイン済み Chrome プロファイルから取得されます。 次の環境変数はフォールバックとして受け付けられます: @@ -572,19 +566,19 @@ OpenClaw config からではなく、選択されたノード上のサインイ - `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` または `GOOGLE_MEET_DEFAULT_MEETING` - `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` または `GOOGLE_MEET_PREVIEW_ACK` -Meet の URL、コード、または `spaces/{id}` を `spaces.get` で解決します。 +Meet URL、コード、または `spaces/{id}` を `spaces.get` で解決します: ```bash openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -メディア処理の前にプリフライトを実行します。 +メディア作業の前にプリフライトを実行します: ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -Meet が会議レコードを作成した後に、会議アーティファクトと出席状況を一覧表示します。 +Meet が会議レコードを作成した後で、ミーティングのアーティファクトと出席状況を一覧表示します: ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij @@ -592,9 +586,9 @@ openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export ``` -`--meeting` を指定すると、`artifacts` と `attendance` はデフォルトで最新の会議レコードを使用します。その会議の保持されているすべてのレコードが必要な場合は、`--all-conference-records` を渡します。 +`--meeting` を指定すると、`artifacts` と `attendance` はデフォルトで最新の会議レコードを使用します。そのミーティングで保持されているすべてのレコードが必要な場合は、`--all-conference-records` を渡します。 -Calendar 参照では、Meet アーティファクトを読む前に Google Calendar から会議 URL を解決できます。 +Calendar 参照では、Meet アーティファクトを読み取る前に Google Calendar からミーティング URL を解決できます: ```bash openclaw googlemeet latest --today @@ -603,9 +597,9 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` は、Google Meet リンクを含む Calendar イベントを今日の `primary` カレンダーから検索します。イベントテキストの一致を検索するには `--event ` を、プライマリ以外のカレンダーには `--calendar ` を使用します。Calendar 参照には、Calendar events readonly スコープを含む新しい OAuth ログインが必要です。`calendar-events` は一致する Meet イベントをプレビューし、`latest`、`artifacts`、`attendance`、または `export` が選択するイベントをマークします。 +`--today` は、Google Meet リンクを含む Calendar イベントを今日の `primary` カレンダーから検索します。一致するイベントテキストを検索するには `--event ` を使用し、非プライマリ Calendar には `--calendar ` を使用します。Calendar 参照には、Calendar events 読み取り専用スコープを含む新しい OAuth ログインが必要です。`calendar-events` は一致する Meet イベントをプレビューし、`latest`、`artifacts`、`attendance`、または `export` が選択するイベントに印を付けます。 -会議レコード ID が既にわかっている場合は、直接指定します。 +会議レコード ID がすでに分かっている場合は、直接指定します: ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -613,7 +607,7 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -読みやすいレポートを書き出します。 +読みやすいレポートを書き出します: ```bash openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 \ @@ -628,11 +622,11 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ --include-doc-bodies --dry-run ``` -`artifacts` は、Google がその会議について公開している場合、会議レコードのメタデータに加えて、参加者、録画、文字起こし、構造化された文字起こしエントリ、スマートノートのリソースメタデータを返します。大規模な会議でエントリ参照をスキップするには、`--no-transcript-entries` を使用します。`attendance` は参加者を participant-session 行に展開し、初回/最終確認時刻、合計セッション時間、遅刻/早退フラグ、ログイン済みユーザーまたは表示名でマージされた重複参加者リソースを含めます。生の参加者リソースを分けたままにするには `--no-merge-duplicates` を、遅刻検出を調整するには `--late-after-minutes` を、早退検出を調整するには `--early-before-minutes` を渡します。 +Google がミーティングについて公開している場合、`artifacts` は会議レコードのメタデータに加えて、参加者、録画、文字起こし、構造化された文字起こしエントリ、スマートノートのリソースメタデータを返します。大規模なミーティングでエントリ参照をスキップするには `--no-transcript-entries` を使用します。`attendance` は参加者を参加者セッション行に展開し、初回/最終確認時刻、合計セッション時間、遅刻/早退フラグ、ログイン済みユーザーまたは表示名でマージされた重複参加者リソースを含めます。生の参加者リソースを分離したままにするには `--no-merge-duplicates` を渡し、遅刻検出を調整するには `--late-after-minutes`、早退検出を調整するには `--early-before-minutes` を渡します。 -`export` は、`summary.md`、`attendance.csv`、`transcript.md`、`artifacts.json`、`attendance.json`、`manifest.json` を含むフォルダーを書き出します。`manifest.json` には、選択された入力、エクスポートオプション、会議レコード、出力ファイル、件数、トークンソース、使用された場合の Calendar イベント、部分的な取得警告が記録されます。フォルダーの横に移植可能なアーカイブも書き出すには、`--zip` を渡します。リンクされた文字起こしとスマートノートの Google Docs テキストを Google Drive `files.export` 経由でエクスポートするには、`--include-doc-bodies` を渡します。これには Drive Meet readonly スコープを含む新しい OAuth ログインが必要です。`--include-doc-bodies` なしでは、エクスポートには Meet メタデータと構造化された文字起こしエントリのみが含まれます。スマートノート一覧、文字起こしエントリ、Drive ドキュメント本文エラーなど、Google が部分的なアーティファクト失敗を返した場合、エクスポート全体を失敗させる代わりに、概要とマニフェストに警告が保持されます。`--dry-run` を使用すると、同じアーティファクト/出席データを取得し、フォルダーや ZIP を作成せずにマニフェスト JSON を出力します。これは、大きなエクスポートを書き出す前や、エージェントが件数、選択されたレコード、警告だけを必要とする場合に便利です。 +`export` は、`summary.md`、`attendance.csv`、`transcript.md`、`artifacts.json`、`attendance.json`、`manifest.json` を含むフォルダーを書き出します。`manifest.json` には、選択された入力、エクスポートオプション、会議レコード、出力ファイル、件数、トークンソース、使用された場合の Calendar イベント、および部分取得の警告が記録されます。フォルダーの横に持ち運び可能なアーカイブも書き出すには、`--zip` を渡します。リンクされた文字起こしとスマートノートの Google Docs テキストを Google Drive `files.export` 経由でエクスポートするには、`--include-doc-bodies` を渡します。これには、Drive Meet 読み取り専用スコープを含む新しい OAuth ログインが必要です。`--include-doc-bodies` がない場合、エクスポートには Meet メタデータと構造化された文字起こしエントリのみが含まれます。Google がスマートノート一覧、文字起こしエントリ、Drive ドキュメント本文エラーなどの部分的なアーティファクト失敗を返した場合、エクスポート全体を失敗させる代わりに、概要とマニフェストに警告が保持されます。`--dry-run` を使用すると、同じアーティファクト/出席状況データを取得し、フォルダーや ZIP を作成せずにマニフェスト JSON を出力します。これは、大規模なエクスポートを書き出す前や、エージェントが件数、選択されたレコード、警告だけを必要とする場合に便利です。 -エージェントは `google_meet` ツールから同じバンドルを作成することもできます。 +エージェントは `google_meet` ツール経由でも同じバンドルを作成できます: ```json { @@ -644,9 +638,9 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ } ``` -エクスポートマニフェストのみを返し、ファイル書き込みをスキップするには、`"dryRun": true` を設定します。 +エクスポートマニフェストのみを返し、ファイル書き込みをスキップするには `"dryRun": true` を設定します。 -実際に保持されている会議に対して、保護付きライブスモークを実行します。 +実際に保持されたミーティングに対して、ガード付きライブスモークを実行します: ```bash OPENCLAW_LIVE_TEST=1 \ @@ -656,8 +650,8 @@ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ライブスモーク環境: -- `OPENCLAW_LIVE_TEST=1` は保護付きライブテストを有効にします。 -- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` は、保持されている Meet URL、コード、または +- `OPENCLAW_LIVE_TEST=1` はガード付きライブテストを有効にします。 +- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` は、保持された Meet URL、コード、または `spaces/{id}` を指します。 - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` または `GOOGLE_MEET_CLIENT_ID` は OAuth クライアント ID を提供します。 @@ -667,15 +661,20 @@ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN`、および `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` は、`OPENCLAW_` プレフィックスなしの同じフォールバック名を使用します。 -基本のアーティファクト/出席ライブスモークには、`https://www.googleapis.com/auth/meetings.space.readonly` と `https://www.googleapis.com/auth/meetings.conference.media.readonly` が必要です。Calendar 参照には `https://www.googleapis.com/auth/calendar.events.readonly` が必要です。Drive ドキュメント本文のエクスポートには `https://www.googleapis.com/auth/drive.meet.readonly` が必要です。 +基本のアーティファクト/出席状況ライブスモークには、 +`https://www.googleapis.com/auth/meetings.space.readonly` と +`https://www.googleapis.com/auth/meetings.conference.media.readonly` が必要です。Calendar +参照には `https://www.googleapis.com/auth/calendar.events.readonly` が必要です。Drive +ドキュメント本文のエクスポートには +`https://www.googleapis.com/auth/drive.meet.readonly` が必要です。 -新しい Meet スペースを作成します。 +新しい Meet スペースを作成します: ```bash openclaw googlemeet create ``` -このコマンドは、新しい `meeting uri`、ソース、参加セッションを出力します。OAuth 認証情報がある場合は、公式 Google Meet API を使用します。OAuth 認証情報がない場合は、ピン留めされた Chrome ノードのログイン済みブラウザプロファイルをフォールバックとして使用します。エージェントは `action: "create"` を指定して `google_meet` ツールを使用し、作成と参加を 1 ステップで実行できます。URL の作成だけを行う場合は、`"join": false` を渡します。 +このコマンドは、新しい `meeting uri`、ソース、参加セッションを出力します。OAuth 認証情報がある場合は、公式の Google Meet API を使用します。OAuth 認証情報がない場合は、ピン留めされた Chrome ノードのログイン済みブラウザプロファイルをフォールバックとして使用します。エージェントは `action: "create"` を指定して `google_meet` ツールを使用し、1 ステップで作成と参加を行えます。URL のみを作成するには、`"join": false` を渡します。 ブラウザフォールバックからの JSON 出力例: @@ -697,7 +696,7 @@ openclaw googlemeet create } ``` -ブラウザフォールバックが URL を作成する前に Google ログインまたは Meet 権限のブロッカーに遭遇した場合、Gateway メソッドは失敗レスポンスを返し、`google_meet` ツールはプレーン文字列ではなく構造化された詳細を返します。 +ブラウザフォールバックが URL を作成できる前に Google ログインまたは Meet 権限ブロッカーに遭遇した場合、Gateway メソッドは失敗レスポンスを返し、`google_meet` ツールは単純な文字列ではなく構造化された詳細を返します: ```json { @@ -715,7 +714,7 @@ openclaw googlemeet create } ``` -エージェントが `manualActionRequired: true` を見た場合は、`manualActionMessage` にブラウザのノード/タブコンテキストを添えて報告し、オペレーターがブラウザ手順を完了するまで新しい Meet タブを開くのを停止する必要があります。 +エージェントが `manualActionRequired: true` を見た場合は、`manualActionMessage` とブラウザのノード/タブコンテキストを報告し、オペレーターがブラウザ手順を完了するまで新しい Meet タブを開くのを停止する必要があります。 API 作成からの JSON 出力例: @@ -738,13 +737,13 @@ API 作成からの JSON 出力例: } ``` -Meet を作成すると、デフォルトで参加します。Chrome または Chrome-node トランスポートは、ブラウザ経由で参加するために、ログイン済みの Google Chrome プロファイルを引き続き必要とします。プロファイルがログアウトしている場合、OpenClaw は `manualActionRequired: true` またはブラウザフォールバックエラーを報告し、再試行する前に Google ログインを完了するようオペレーターに求めます。 +Meet の作成ではデフォルトで参加も行います。Chrome または Chrome-node トランスポートでブラウザから参加するには、引き続きログイン済みの Google Chrome プロファイルが必要です。プロファイルがログアウトしている場合、OpenClaw は `manualActionRequired: true` またはブラウザフォールバックエラーを報告し、再試行する前にオペレーターに Google ログインの完了を求めます。 -Cloud プロジェクト、OAuth プリンシパル、会議参加者が Meet media APIs の Google Workspace Developer Preview Program に登録されていることを確認した後にのみ、`preview.enrollmentAcknowledged: true` を設定します。 +Cloud プロジェクト、OAuth プリンシパル、ミーティング参加者が Meet media APIs 向け Google Workspace Developer Preview Program に登録されていることを確認した後にのみ、`preview.enrollmentAcknowledged: true` を設定します。 ## 設定 -共通の Chrome リアルタイムパスに必要なのは、有効化された Plugin、BlackHole、SoX、バックエンドのリアルタイム音声プロバイダーキーだけです。OpenAI がデフォルトです。Google Gemini Live を使用するには、`realtime.provider: "google"` を設定します。 +一般的な Chrome リアルタイムパスに必要なのは、有効化された Plugin、BlackHole、SoX、バックエンドのリアルタイム音声プロバイダーキーだけです。OpenAI がデフォルトです。Google Gemini Live を使用するには `realtime.provider: "google"` を設定します: ```bash brew install blackhole-2ch sox @@ -753,7 +752,7 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -Plugin 設定を `plugins.entries.google-meet.config` の下に設定します。 +Plugin 設定を `plugins.entries.google-meet.config` 配下で設定します: ```json5 { @@ -774,20 +773,20 @@ Plugin 設定を `plugins.entries.google-meet.config` の下に設定します - `defaultMode: "realtime"` - `chromeNode.node`: `chrome-node` 用の任意のノード ID/名前/IP - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`: ログアウト状態の Meet ゲスト画面で使用される名前 -- `chrome.autoJoin: true`: `chrome-node` 上の OpenClaw ブラウザ自動化を通じて、ベストエフォートでゲスト名を入力し、今すぐ参加をクリックします -- `chrome.reuseExistingTab: true`: 重複を開く代わりに、既存の Meet タブをアクティブ化します -- `chrome.waitForInCallMs: 20000`: リアルタイムのイントロがトリガーされる前に、Meet タブが通話中を報告するのを待ちます -- `chrome.audioFormat: "pcm16-24khz"`: コマンドペアの音声形式。まだ電話音声を出力するレガシー/カスタムのコマンドペアでのみ `"g711-ulaw-8khz"` を使用します。 -- `chrome.audioInputCommand`: CoreAudio `BlackHole 2ch` から読み取り、`chrome.audioFormat` の音声を書き出す SoX コマンド -- `chrome.audioOutputCommand`: `chrome.audioFormat` の音声を読み取り、CoreAudio `BlackHole 2ch` に書き込む SoX コマンド +- `chrome.guestName: "OpenClaw Agent"`: ログアウト状態の Meet ゲスト画面で使用する名前 +- `chrome.autoJoin: true`: `chrome-node` 上の OpenClaw ブラウザ自動化による、ベストエフォートのゲスト名入力と「今すぐ参加」クリック +- `chrome.reuseExistingTab: true`: 重複して開く代わりに既存の Meet タブをアクティブ化 +- `chrome.waitForInCallMs: 20000`: リアルタイムのイントロがトリガーされる前に、Meet タブが通話中と報告するまで待機 +- `chrome.audioFormat: "pcm16-24khz"`: コマンドペア音声形式。電話音声をまだ出力するレガシー/カスタムのコマンドペアにのみ `"g711-ulaw-8khz"` を使用します。 +- `chrome.audioInputCommand`: CoreAudio `BlackHole 2ch` から読み取り、`chrome.audioFormat` で音声を書き出す SoX コマンド +- `chrome.audioOutputCommand`: `chrome.audioFormat` で音声を読み取り、CoreAudio `BlackHole 2ch` に書き込む SoX コマンド - `realtime.provider: "openai"` - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`: より深い回答には `openclaw_agent_consult` を使う、短い音声応答 -- `realtime.introMessage`: リアルタイムブリッジ接続時の短い音声準備確認。無音で参加するには `""` に設定します +- `realtime.instructions`: 短い音声応答。より深い回答には `openclaw_agent_consult` を使用 +- `realtime.introMessage`: リアルタイムブリッジ接続時の短い音声準備確認。無音で参加するには `""` に設定 - `realtime.agentId`: `openclaw_agent_consult` 用の任意の OpenClaw エージェント ID。デフォルトは `main` -任意の上書き: +任意の上書き設定: ```json5 { @@ -834,11 +833,11 @@ Twilio 専用設定: } ``` -`voiceCall.enabled` のデフォルトは `true` です。Twilio トランスポートでは、実際の PSTN 通話と DTMF を Voice Call Plugin に委譲します。`voice-call` が有効でない場合でも、Google Meet はダイヤルプランを検証して記録できますが、Twilio 通話を発信することはできません。 +`voiceCall.enabled` のデフォルトは `true` です。Twilio トランスポートでは、実際の PSTN 通話と DTMF を Voice Call Plugin に委任します。`voice-call` が有効でない場合でも、Google Meet はダイヤルプランの検証と記録を実行できますが、Twilio 通話を発信することはできません。 ## ツール -エージェントは `google_meet` ツールを使用できます。 +エージェントは `google_meet` ツールを使用できます: ```json { @@ -849,18 +848,18 @@ Twilio 専用設定: } ``` -Chrome が Gateway ホストで実行されている場合は `transport: "chrome"` を使用します。Chrome が Parallels VM などのペアリング済みノードで実行されている場合は `transport: "chrome-node"` を使用します。どちらの場合もリアルタイムモデルと `openclaw_agent_consult` は Gateway ホストで実行されるため、モデルの認証情報はそこに保持されます。 +Chrome が Gateway ホストで実行されている場合は `transport: "chrome"` を使用します。Chrome が Parallels VM などのペアリング済みノードで実行されている場合は `transport: "chrome-node"` を使用します。どちらの場合も、リアルタイムモデルと `openclaw_agent_consult` は Gateway ホストで実行されるため、モデルの認証情報はそこに保持されます。 -アクティブなセッションの一覧表示やセッション ID の確認には `action: "status"` を使用します。リアルタイムエージェントにすぐ発話させるには、`sessionId` と `message` とともに `action: "speak"` を使用します。セッションの作成または再利用、既知のフレーズのトリガー、Chrome ホストが報告できる場合の `inCall` ヘルスの返却には `action: "test_speech"` を使用します。`test_speech` は常に `mode: "realtime"` を強制し、`mode: "transcribe"` で実行するよう求められると失敗します。これは、監視専用セッションは意図的に音声を出力できないためです。その `speechOutputVerified` 結果は、このテスト呼び出し中にリアルタイム音声出力バイトが増加したかどうかに基づくため、古い音声がある再利用セッションは新しい発話チェックの成功としては数えられません。セッションを終了済みとしてマークするには `action: "leave"` を使用します。 +アクティブなセッションを一覧表示するか、セッション ID を調べるには `action: "status"` を使用します。リアルタイムエージェントにただちに発話させるには、`sessionId` と `message` を指定して `action: "speak"` を使用します。セッションを作成または再利用し、既知のフレーズをトリガーし、Chrome ホストが報告できる場合に `inCall` の健全性を返すには `action: "test_speech"` を使用します。`test_speech` は常に `mode: "realtime"` を強制し、`mode: "transcribe"` で実行するよう要求された場合は失敗します。これは、観察専用セッションが意図的に音声を出力できないためです。その `speechOutputVerified` の結果は、このテスト呼び出し中にリアルタイム音声出力バイトが増加したかどうかに基づくため、古い音声を持つ再利用セッションは新しい発話チェックの成功として扱われません。セッションを終了済みにマークするには `action: "leave"` を使用します。 -`status` には、利用可能な場合 Chrome ヘルスが含まれます。 +利用可能な場合、`status` には Chrome の健全性が含まれます。 - `inCall`: Chrome が Meet 通話内にいるように見える - `micMuted`: ベストエフォートの Meet マイク状態 -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: 発話が機能する前に、ブラウザプロファイルで手動ログイン、Meet ホストによる入室許可、権限、またはブラウザ制御の修復が必要 +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: 発話が機能する前に、ブラウザープロファイルで手動ログイン、Meet ホストによる参加許可、権限付与、またはブラウザー制御の修復が必要 - `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: 管理対象 Chrome の発話が現在許可されているかどうか。`speechReady: false` は、OpenClaw がイントロ/テストフレーズを音声ブリッジへ送信しなかったことを意味します。 - `providerConnected` / `realtimeReady`: リアルタイム音声ブリッジの状態 -- `lastInputAt` / `lastOutputAt`: ブリッジから最後に受信、またはブリッジへ最後に送信された音声 +- `lastInputAt` / `lastOutputAt`: ブリッジから最後に受信した、またはブリッジへ送信した音声 ```json { @@ -870,29 +869,29 @@ Chrome が Gateway ホストで実行されている場合は `transport: "chrom } ``` -## リアルタイムエージェントへの相談 +## リアルタイムエージェント相談 -Chrome リアルタイムモードは、ライブ音声ループ向けに最適化されています。リアルタイム音声プロバイダーは会議音声を聞き、設定された音声ブリッジを通して発話します。リアルタイムモデルがより深い推論、現在の情報、または通常の OpenClaw ツールを必要とする場合、`openclaw_agent_consult` を呼び出せます。 +Chrome のリアルタイムモードは、ライブ音声ループ向けに最適化されています。リアルタイム音声プロバイダーは会議音声を聞き取り、設定済みの音声ブリッジを通じて発話します。リアルタイムモデルがより深い推論、最新情報、または通常の OpenClaw ツールを必要とする場合、`openclaw_agent_consult` を呼び出せます。 -相談ツールは、最近の会議文字起こしコンテキストとともに通常の OpenClaw エージェントを裏側で実行し、リアルタイム音声セッションに簡潔な発話用回答を返します。その後、音声モデルはその回答を会議内で発話できます。これは Voice Call と同じ共有リアルタイム相談ツールを使用します。 +相談ツールは、最近の会議トランスクリプトのコンテキストを使って通常の OpenClaw エージェントを裏側で実行し、リアルタイム音声セッションへ簡潔な発話用回答を返します。その後、音声モデルはその回答を会議内で発話できます。これは Voice Call と同じ共有リアルタイム相談ツールを使用します。 -デフォルトでは、相談は `main` エージェントに対して実行されます。Meet レーンが専用の OpenClaw エージェントワークスペース、モデルデフォルト、ツールポリシー、メモリ、セッション履歴を参照する必要がある場合は、`realtime.agentId` を設定します。 +デフォルトでは、相談は `main` エージェントに対して実行されます。Meet レーンが専用の OpenClaw エージェントワークスペース、モデルデフォルト、ツールポリシー、メモリ、セッション履歴に相談する必要がある場合は、`realtime.agentId` を設定します。 `realtime.toolPolicy` は相談実行を制御します。 - `safe-read-only`: 相談ツールを公開し、通常のエージェントを `read`、`web_search`、`web_fetch`、`x_search`、`memory_search`、`memory_get` に制限します。 -- `owner`: 相談ツールを公開し、通常のエージェントに通常のエージェントツールポリシーの使用を許可します。 +- `owner`: 相談ツールを公開し、通常のエージェントに通常のエージェントツールポリシーを使用させます。 - `none`: リアルタイム音声モデルに相談ツールを公開しません。 -相談セッションキーは Meet セッションごとにスコープされるため、同じ会議中のフォローアップ相談呼び出しは以前の相談コンテキストを再利用できます。 +相談セッションキーは Meet セッションごとにスコープされるため、同じ会議中の後続の相談呼び出しで以前の相談コンテキストを再利用できます。 -Chrome が通話に完全に参加した後に発話による準備完了チェックを強制するには: +Chrome が通話に完全に参加した後で、発話による準備完了チェックを強制するには: ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -参加から発話までの完全なスモークには: +完全な参加および発話のスモークには: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -902,7 +901,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## ライブテストチェックリスト -会議を無人エージェントに渡す前に、この手順を使用します。 +会議を無人エージェントに引き渡す前に、この手順を使用します。 ```bash openclaw googlemeet setup @@ -912,15 +911,15 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: Google Meet speech test complete." ``` -想定される Chrome-node 状態: +期待される Chrome-node 状態: -- `googlemeet setup` がすべて緑。 -- Chrome-node がデフォルトトランスポートであるか、ノードが固定されている場合、`googlemeet setup` に `chrome-node-connected` が含まれる。 -- `nodes status` で選択されたノードが接続済みと表示される。 -- 選択されたノードが `googlemeet.chrome` と `browser.proxy` の両方を通知している。 -- Meet タブが通話に参加し、`test-speech` が `inCall: true` の Chrome ヘルスを返す。 +- `googlemeet setup` はすべて緑です。 +- Chrome-node がデフォルトトランスポートであるか、ノードが固定されている場合、`googlemeet setup` に `chrome-node-connected` が含まれます。 +- `nodes status` は選択されたノードが接続済みであることを示します。 +- 選択されたノードは `googlemeet.chrome` と `browser.proxy` の両方を広告します。 +- Meet タブが通話に参加し、`test-speech` が `inCall: true` を含む Chrome 健全性を返します。 -Parallels macOS VM などのリモート Chrome ホストでは、Gateway または VM を更新した後の最短の安全なチェックは次のとおりです。 +Parallels macOS VM などのリモート Chrome ホストの場合、これは Gateway または VM の更新後に行う最短の安全なチェックです。 ```bash openclaw googlemeet setup @@ -931,9 +930,9 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -これにより、エージェントが実際の会議タブを開く前に、Gateway Plugin が読み込まれていること、VM ノードが現在のトークンで接続されていること、Meet 音声ブリッジが利用可能であることを証明できます。 +これにより、エージェントが実際の会議タブを開く前に、Gateway Plugin が読み込まれていること、VM ノードが現在のトークンで接続されていること、Meet 音声ブリッジが利用可能であることが証明されます。 -Twilio スモークには、電話ダイヤルイン情報を公開する会議を使用します。 +Twilio スモークには、電話ダイヤルイン詳細を公開している会議を使用します。 ```bash openclaw googlemeet setup @@ -943,12 +942,12 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -想定される Twilio 状態: +期待される Twilio 状態: -- `googlemeet setup` に緑の `twilio-voice-call-plugin` と `twilio-voice-call-credentials` チェックが含まれる。 -- Gateway の再読み込み後、CLI で `voicecall` が利用可能。 -- 返されたセッションに `transport: "twilio"` と `twilio.voiceCallId` がある。 -- `googlemeet leave ` が委譲された音声通話を切断する。 +- `googlemeet setup` に緑の `twilio-voice-call-plugin` と `twilio-voice-call-credentials` チェックが含まれます。 +- Gateway の再読み込み後、CLI で `voicecall` が利用できます。 +- 返されたセッションには `transport: "twilio"` と `twilio.voiceCallId` があります。 +- `googlemeet leave ` は委任された音声通話を切断します。 ## トラブルシューティング @@ -961,11 +960,11 @@ openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -`plugins.entries.google-meet` を編集した直後の場合は、Gateway を再起動または再読み込みしてください。実行中のエージェントには、現在の Gateway プロセスによって登録された Plugin ツールだけが見えます。 +`plugins.entries.google-meet` を編集したばかりの場合は、Gateway を再起動または再読み込みします。実行中のエージェントは、現在の Gateway プロセスによって登録された Plugin ツールだけを認識します。 -### 接続済みの Google Meet 対応ノードがない +### Google Meet 対応ノードが接続されていない -ノードホストで実行します。 +ノードホストで次を実行します。 ```bash openclaw plugins enable google-meet @@ -974,7 +973,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Gateway ホストでノードを承認し、コマンドを確認します。 +Gateway ホストで、ノードを承認し、コマンドを検証します。 ```bash openclaw devices list @@ -982,7 +981,7 @@ openclaw devices approve openclaw nodes status ``` -ノードは接続済みで、`googlemeet.chrome` と `browser.proxy` を一覧表示する必要があります。Gateway 設定はそれらのノードコマンドを許可している必要があります。 +ノードは接続済みで、`googlemeet.chrome` と `browser.proxy` を列挙している必要があります。Gateway 設定では、これらのノードコマンドを許可している必要があります。 ```json5 { @@ -1005,37 +1004,37 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -その後、ノードサービスを再読み込みして再実行します。 +その後、ノードサービスを再読み込みし、再実行します。 ```bash openclaw googlemeet setup openclaw nodes status --connected ``` -### ブラウザは開くがエージェントが参加できない +### ブラウザーは開くがエージェントが参加できない -`googlemeet test-speech` を実行し、返された Chrome ヘルスを確認します。`manualActionRequired: true` が報告された場合は、`manualActionMessage` をオペレーターに表示し、ブラウザ操作が完了するまで再試行を停止します。 +`googlemeet test-speech` を実行し、返された Chrome 健全性を確認します。`manualActionRequired: true` が報告された場合は、`manualActionMessage` をオペレーターに表示し、ブラウザー操作が完了するまで再試行を停止します。 一般的な手動操作: - Chrome プロファイルにサインインする。 -- Meet ホストアカウントからゲストを入室許可する。 -- Chrome のネイティブ権限プロンプトが表示されたら、Chrome のマイク/カメラ権限を付与する。 -- 停止した Meet 権限ダイアログを閉じるか修復する。 +- Meet ホストアカウントからゲストを許可する。 +- Chrome のネイティブ権限プロンプトが表示されたときに、Chrome のマイク/カメラ権限を付与する。 +- 停滞している Meet 権限ダイアログを閉じるか修復する。 -Meet に「Do you want people to hear you in the meeting?」と表示されるだけで「サインインしていない」と報告しないでください。これは Meet の音声選択インタースティシャルです。OpenClaw は利用可能な場合、ブラウザ自動化を通じて **Use microphone** をクリックし、実際の会議状態を待ち続けます。作成専用のブラウザフォールバックでは、URL の作成にリアルタイム音声パスが不要なため、OpenClaw が **Continue without microphone** をクリックする場合があります。 +Meet に「Do you want people to hear you in the meeting?」と表示されているだけで「サインインしていない」と報告しないでください。これは Meet の音声選択インタースティシャルです。OpenClaw は利用可能な場合、ブラウザー自動化を通じて **Use microphone** をクリックし、実際の会議状態を待ち続けます。作成専用のブラウザーフォールバックでは、URL の作成にリアルタイム音声パスが不要なため、OpenClaw が **Continue without microphone** をクリックする場合があります。 ### 会議の作成に失敗する -`googlemeet create` は、OAuth 認証情報が設定されている場合、まず Google Meet API の `spaces.create` エンドポイントを使用します。OAuth 認証情報がない場合は、固定された Chrome ノードブラウザにフォールバックします。確認事項: +`googlemeet create` は、OAuth 認証情報が設定されている場合、まず Google Meet API の `spaces.create` エンドポイントを使用します。OAuth 認証情報がない場合は、固定された Chrome ノードブラウザーにフォールバックします。次を確認します。 - API 作成の場合: `oauth.clientId` と `oauth.refreshToken` が設定されている、または一致する `OPENCLAW_GOOGLE_MEET_*` 環境変数が存在する。 -- API 作成の場合: 更新トークンが、作成サポート追加後に発行されている。古いトークンには `meetings.space.created` スコープがない場合があります。`openclaw googlemeet auth login --json` を再実行し、Plugin 設定を更新してください。 -- ブラウザフォールバックの場合: `defaultTransport: "chrome-node"` で、`chromeNode.node` が `browser.proxy` と `googlemeet.chrome` を持つ接続済みノードを指している。 -- ブラウザフォールバックの場合: そのノード上の OpenClaw Chrome プロファイルが Google にサインインしており、`https://meet.google.com/new` を開ける。 -- ブラウザフォールバックの場合: 再試行では、新しいタブを開く前に既存の `https://meet.google.com/new` または Google アカウントプロンプトタブを再利用する。エージェントがタイムアウトした場合は、別の Meet タブを手動で開くのではなく、ツール呼び出しを再試行してください。 -- ブラウザフォールバックの場合: ツールが `manualActionRequired: true` を返す場合は、返された `browser.nodeId`、`browser.targetId`、`browserUrl`、`manualActionMessage` を使用してオペレーターを案内する。その操作が完了するまでループで再試行しないでください。 -- ブラウザフォールバックの場合: Meet に「Do you want people to hear you in the meeting?」と表示されたら、タブを開いたままにします。OpenClaw はブラウザ自動化を通じて **Use microphone**、または作成専用フォールバックでは **Continue without microphone** をクリックし、生成された Meet URL の待機を続ける必要があります。それができない場合、エラーは `google-login-required` ではなく `meet-audio-choice-required` に言及する必要があります。 +- API 作成の場合: リフレッシュトークンは作成サポートが追加された後に発行されている。古いトークンには `meetings.space.created` スコープがない場合があります。`openclaw googlemeet auth login --json` を再実行し、Plugin 設定を更新します。 +- ブラウザーフォールバックの場合: `defaultTransport: "chrome-node"` と `chromeNode.node` が、`browser.proxy` と `googlemeet.chrome` を持つ接続済みノードを指している。 +- ブラウザーフォールバックの場合: そのノード上の OpenClaw Chrome プロファイルが Google にサインインしており、`https://meet.google.com/new` を開ける。 +- ブラウザーフォールバックの場合: 再試行では、新しいタブを開く前に既存の `https://meet.google.com/new` または Google アカウントプロンプトタブを再利用する。エージェントがタイムアウトした場合は、別の Meet タブを手動で開くのではなく、ツール呼び出しを再試行します。 +- ブラウザーフォールバックの場合: ツールが `manualActionRequired: true` を返した場合は、返された `browser.nodeId`、`browser.targetId`、`browserUrl`、`manualActionMessage` を使用してオペレーターを案内します。その操作が完了するまでループで再試行しないでください。 +- ブラウザーフォールバックの場合: Meet に「Do you want people to hear you in the meeting?」と表示されたら、タブを開いたままにします。OpenClaw はブラウザー自動化を通じて **Use microphone**、または作成専用フォールバックでは **Continue without microphone** をクリックし、生成された Meet URL を待ち続ける必要があります。それができない場合、エラーは `google-login-required` ではなく `meet-audio-choice-required` に言及する必要があります。 ### エージェントは参加するが話さない @@ -1046,32 +1045,33 @@ openclaw googlemeet setup openclaw googlemeet doctor ``` -聞き取り/応答には `mode: "realtime"` を使用します。`mode: "transcribe"` は意図的に双方向のリアルタイム音声ブリッジを開始しません。`googlemeet test-speech` は常にリアルタイムパスをチェックし、その呼び出しでブリッジ出力バイトが観測されたかどうかを報告します。`speechOutputVerified` が false で `speechOutputTimedOut` が true の場合、リアルタイムプロバイダーは発話を受け付けた可能性がありますが、OpenClaw は Chrome 音声ブリッジに到達する新しい出力バイトを確認できませんでした。 +聞き取り/返答には `mode: "realtime"` を使用します。`mode: "transcribe"` は意図的に双方向のリアルタイム音声ブリッジを開始しません。`googlemeet test-speech` は常にリアルタイムパスをチェックし、その呼び出しでブリッジ出力バイトが観測されたかどうかを報告します。`speechOutputVerified` が false で、`speechOutputTimedOut` が true の場合、リアルタイムプロバイダーは発話を受け付けたものの、OpenClaw は新しい出力バイトが Chrome 音声ブリッジに到達するのを確認できなかった可能性があります。 -次も確認してください。 +次も確認します。 -- Gateway ホストで `OPENAI_API_KEY` や `GEMINI_API_KEY` などのリアルタイムプロバイダーキーが利用可能。 +- Gateway ホストで `OPENAI_API_KEY` や `GEMINI_API_KEY` などのリアルタイムプロバイダーキーが利用可能である。 - Chrome ホストで `BlackHole 2ch` が表示されている。 - Chrome ホストに `sox` が存在する。 -- Meet のマイクとスピーカーが OpenClaw で使用される仮想音声パスを通してルーティングされている。 +- Meet のマイクとスピーカーが、OpenClaw が使用する仮想音声パスを経由してルーティングされている。 -`googlemeet doctor [session-id]` は、セッション、ノード、通話内状態、手動操作理由、リアルタイムプロバイダー接続、`realtimeReady`、音声入出力アクティビティ、最後の音声タイムスタンプ、バイトカウンター、ブラウザ URL を出力します。生の JSON が必要な場合は `googlemeet status [session-id]` を使用します。トークンを公開せずに Google Meet OAuth 更新を確認する必要がある場合は `googlemeet doctor --oauth` を使用し、Google Meet API の証明も必要な場合は `--meeting` または `--create-space` を追加します。 +`googlemeet doctor [session-id]` は、セッション、ノード、通話中状態、手動操作理由、リアルタイムプロバイダー接続、`realtimeReady`、音声入力/出力アクティビティ、最終音声タイムスタンプ、バイトカウンター、ブラウザー URL を出力します。生の JSON が必要な場合は `googlemeet status [session-id] --json` を使用します。トークンを公開せずに Google Meet OAuth 更新を検証する必要がある場合は `googlemeet doctor --oauth` を使用します。Google Meet API の証明も必要な場合は、`--meeting` または `--create-space` を追加します。 -エージェントがタイムアウトし、Meet タブがすでに開いていることを確認できる場合は、別のタブを開かずにそのタブを検査します。 +エージェントがタイムアウトし、Meet タブがすでに開いていることを確認できる場合は、別のタブを開かずにそのタブを調べます。 ```bash openclaw googlemeet recover-tab openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` -同等のツールアクションは `recover_current_tab` です。選択されたトランスポートの既存 Meet タブにフォーカスし、検査します。`chrome` では Gateway 経由のローカルブラウザ制御を使用し、`chrome-node` では設定された Chrome ノードを使用します。新しいタブを開いたり、新しいセッションを作成したりはしません。ログイン、入室許可、権限、音声選択状態など、現在のブロッカーを報告します。CLI コマンドは設定された Gateway と通信するため、Gateway が実行中である必要があります。`chrome-node` では、Chrome ノードも接続されている必要があります。 +同等のツールアクションは `recover_current_tab` です。選択されたトランスポートの既存の Meet タブにフォーカスし、検査します。`chrome` では Gateway を通じたローカルブラウザー制御を使用し、`chrome-node` では設定済みの Chrome ノードを使用します。新しいタブを開いたり、新しいセッションを作成したりしません。ログイン、参加許可、権限、音声選択状態など、現在のブロッカーを報告します。CLI コマンドは設定済みの Gateway と通信するため、Gateway が実行中である必要があります。`chrome-node` では Chrome ノードも接続済みである必要があります。 ### Twilio セットアップチェックが失敗する -`voice-call` が許可されていないか、有効化されていない場合、`twilio-voice-call-plugin` は失敗します。 -`plugins.allow` に追加し、`plugins.entries.voice-call` を有効化して、Gateway をリロードしてください。 +`twilio-voice-call-plugin` は `voice-call` が許可されていない、または有効になっていない場合に失敗します。 +`plugins.allow` に追加し、`plugins.entries.voice-call` を有効にして、Gateway を再読み込みします。 -Twilio バックエンドにアカウント SID、認証トークン、または発信者番号がない場合、`twilio-voice-call-credentials` は失敗します。Gateway ホストでこれらを設定してください。 +`twilio-voice-call-credentials` は、Twilio バックエンドにアカウント +SID、認証トークン、または発信者番号がない場合に失敗します。Gateway ホストでこれらを設定してください。 ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1079,7 +1079,7 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -その後、Gateway を再起動またはリロードして、次を実行します。 +次に Gateway を再起動または再読み込みして、以下を実行します。 ```bash openclaw googlemeet setup @@ -1087,21 +1087,21 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` はデフォルトでは準備状態の確認のみです。特定の番号でドライランするには: +`voicecall smoke` はデフォルトでは準備状態の確認のみです。特定の番号でドライランするには、次を実行します。 ```bash openclaw voicecall smoke --to "+15555550123" ``` -ライブのアウトバウンド通知通話を意図的に発信したい場合にのみ、`--yes` を追加してください。 +意図的にライブのアウトバウンド通知通話を発信したい場合にのみ、`--yes` を追加してください。 ```bash openclaw voicecall smoke --to "+15555550123" --yes ``` -### Twilio 通話が開始するがミーティングに参加しない +### Twilio 通話は開始されるが、会議に参加しない -Meet イベントが電話ダイヤルインの詳細を公開していることを確認してください。正確なダイヤルイン番号と PIN、またはカスタム DTMF シーケンスを渡します。 +Meet イベントが電話ダイヤルインの詳細を公開していることを確認します。正確なダイヤルイン番号と PIN、またはカスタム DTMF シーケンスを渡します。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1110,23 +1110,23 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -プロバイダーが PIN の入力前に一時停止を必要とする場合は、`--dtmf-sequence` で先頭の `w` またはカンマを使用してください。 +PIN を入力する前にプロバイダー側で一時停止が必要な場合は、`--dtmf-sequence` で先頭の `w` またはカンマを使用します。 -## 注記 +## 注意事項 -Google Meet の公式メディア API は受信指向であるため、Meet 通話で話すには引き続き参加者経路が必要です。この Plugin はその境界を明確に保ちます。Chrome はブラウザー参加とローカル音声ルーティングを処理し、Twilio は電話ダイヤルイン参加を処理します。 +Google Meet の公式メディア API は受信向けのため、Meet 通話に話しかけるには引き続き参加者パスが必要です。この Plugin はその境界を見える状態に保ちます。Chrome はブラウザー参加とローカル音声ルーティングを処理し、Twilio は電話ダイヤルイン参加を処理します。 -Chrome リアルタイムモードには、`BlackHole 2ch` に加えて次のいずれかが必要です。 +Chrome リアルタイムモードには `BlackHole 2ch` に加えて、次のいずれかが必要です。 -- `chrome.audioInputCommand` と `chrome.audioOutputCommand`: OpenClaw がリアルタイムモデルブリッジを所有し、`chrome.audioFormat` の音声をこれらのコマンドと選択されたリアルタイム音声プロバイダーの間でパイプします。デフォルトの Chrome 経路は 24 kHz PCM16 です。8 kHz G.711 mu-law はレガシーコマンドペア向けに引き続き利用できます。 -- `chrome.audioBridgeCommand`: 外部ブリッジコマンドがローカル音声経路全体を所有し、そのデーモンを開始または検証した後に終了する必要があります。 +- `chrome.audioInputCommand` と `chrome.audioOutputCommand`: OpenClaw がリアルタイムモデルブリッジを所有し、これらのコマンドと選択されたリアルタイム音声プロバイダーの間で `chrome.audioFormat` の音声をパイプします。デフォルトの Chrome パスは 24 kHz PCM16 です。8 kHz G.711 mu-law はレガシーコマンドペア向けに引き続き利用できます。 +- `chrome.audioBridgeCommand`: 外部ブリッジコマンドがローカル音声パス全体を所有し、デーモンを起動または検証した後に終了する必要があります。 -クリーンな双方向音声のために、Meet の出力と Meet のマイクを別々の仮想デバイス、または Loopback スタイルの仮想デバイスグラフにルーティングしてください。単一の共有 BlackHole デバイスでは、他の参加者の音声が通話にエコーで戻る可能性があります。 +クリーンな双方向音声のために、Meet 出力と Meet マイクを別々の仮想デバイス、または Loopback 形式の仮想デバイスグラフ経由でルーティングしてください。単一の共有 BlackHole デバイスでは、他の参加者の音声が通話にエコーバックされる可能性があります。 -`googlemeet speak` は Chrome セッションのアクティブなリアルタイム音声ブリッジを起動します。`googlemeet leave` はそのブリッジを停止します。Voice Call Plugin 経由で委任された Twilio セッションでは、`leave` は基盤となる音声通話も切断します。 +`googlemeet speak` は Chrome セッションのアクティブなリアルタイム音声ブリッジをトリガーします。`googlemeet leave` はそのブリッジを停止します。Voice Call Plugin 経由で委任された Twilio セッションでは、`leave` は基盤となる音声通話も切断します。 ## 関連 -- [音声通話 Plugin](/ja-JP/plugins/voice-call) -- [トークモード](/ja-JP/nodes/talk) -- [Plugin の構築](/ja-JP/plugins/building-plugins) +- [音声通話Plugin](/ja-JP/plugins/voice-call) +- [通話モード](/ja-JP/nodes/talk) +- [Pluginの構築](/ja-JP/plugins/building-plugins) diff --git a/docs/ja-JP/reference/RELEASING.md b/docs/ja-JP/reference/RELEASING.md index f336c5611..e00586500 100644 --- a/docs/ja-JP/reference/RELEASING.md +++ b/docs/ja-JP/reference/RELEASING.md @@ -1,124 +1,229 @@ --- read_when: - - 公開リリースチャンネルの定義を探しています + - 公開リリースチャネル定義を検索しています - リリース検証またはパッケージ受け入れの実行 - - バージョンの命名規則とリリース周期を探す -summary: リリースレーン、運用者チェックリスト、検証ボックス、バージョン命名規則、ケイデンス + - バージョン命名規則とリリース周期を確認中 +summary: リリースレーン、オペレーター用チェックリスト、検証ボックス、バージョン命名、周期 title: リリースポリシー x-i18n: - generated_at: "2026-04-30T05:33:04Z" + generated_at: "2026-05-01T05:03:13Z" model: gpt-5.5 provider: openai - source_hash: 54dc9ad7918ac95ec535a0404bbcbc04461a2b977151db0c2039b91e7e69c15c + source_hash: dfe579099a9580e2d0400cd0b24f26d3fa3ee917899423604ebc13aa2519b4ee source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw には3つの公開リリースレーンがあります。 +OpenClaw には 3 つの公開リリースレーンがあります。 -- 安定版: デフォルトでは npm `beta` に公開され、明示的に要求された場合は npm `latest` に公開されるタグ付きリリース -- ベータ: npm `beta` に公開されるプレリリースタグ -- 開発版: `main` の移動する先頭 +- stable: 既定では npm `beta` に公開され、明示的に要求された場合は npm `latest` に公開されるタグ付きリリース +- beta: npm `beta` に公開されるプレリリースタグ +- dev: `main` の移動する先頭 ## バージョン命名 -- 安定版リリースバージョン: `YYYY.M.D` +- stable リリースバージョン: `YYYY.M.D` - Git タグ: `vYYYY.M.D` -- 安定版修正リリースバージョン: `YYYY.M.D-N` +- stable 修正リリースバージョン: `YYYY.M.D-N` - Git タグ: `vYYYY.M.D-N` -- ベータプレリリースバージョン: `YYYY.M.D-beta.N` +- beta プレリリースバージョン: `YYYY.M.D-beta.N` - Git タグ: `vYYYY.M.D-beta.N` -- 月または日にゼロ埋めはしない -- `latest` は現在昇格済みの安定版 npm リリースを意味する -- `beta` は現在のベータインストール対象を意味する -- 安定版および安定版修正リリースはデフォルトで npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みのベータビルドを後から昇格することもできる -- すべての安定版 OpenClaw リリースでは、npm パッケージと macOS アプリを一緒に出荷する。 - ベータリリースでは通常、まず npm/パッケージ経路を検証して公開し、mac アプリのビルド/署名/公証は明示的に要求されない限り安定版向けに保持する +- 月または日をゼロ埋めしない +- `latest` は現在昇格済みの stable npm リリースを意味する +- `beta` は現在の beta インストール対象を意味する +- stable および stable 修正リリースは既定で npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みの beta ビルドを後で昇格することもできる +- すべての stable OpenClaw リリースは npm パッケージと macOS アプリを一緒に出荷する。 + beta リリースでは通常、npm/パッケージ経路の検証と公開を先に行い、 + mac アプリのビルド/署名/公証は明示的に要求されない限り stable 用に予約される -## リリース頻度 +## リリースサイクル -- リリースはベータ優先で進む -- 安定版は最新のベータが検証された後にのみ続く -- メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを切るため、リリース検証と修正が `main` 上の新規開発を妨げない -- ベータタグがプッシュまたは公開済みで修正が必要な場合、メンテナーは古いベータタグを削除または再作成する代わりに、次の `-beta.N` タグを切る -- 詳細なリリース手順、承認、認証情報、復旧メモはメンテナー専用 +- リリースは beta 優先で進む +- stable は最新の beta が検証された後にのみ続く +- メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを切る。 + これにより、リリース検証と修正が `main` での新規開発をブロックしない +- beta タグがプッシュまたは公開済みで修正が必要な場合、メンテナーは古い beta タグを削除または再作成するのではなく、 + 次の `-beta.N` タグを切る +- 詳細なリリース手順、承認、認証情報、復旧メモは + メンテナー専用 ## リリース担当者チェックリスト -このチェックリストは、リリースフローの公開部分を示します。非公開の認証情報、署名、公証、dist-tag 復旧、緊急ロールバックの詳細は、メンテナー専用のリリースランブックに保持されます。 +このチェックリストはリリースフローの公開上の形を示します。非公開の認証情報、 +署名、公証、dist-tag 復旧、緊急ロールバックの詳細は +メンテナー専用のリリースランブックに保持します。 -1. 現在の `main` から開始する: 最新を pull し、対象コミットがプッシュ済みであることを確認し、現在の `main` CI がそこからブランチを切れる程度に green であることを確認する。 -2. 実際のコミット履歴から `/changelog` で最上部の `CHANGELOG.md` セクションを書き換え、エントリをユーザー向けに保ち、コミットしてプッシュし、ブランチを切る前にもう一度 rebase/pull する。 -3. `src/plugins/compat/registry.ts` と `src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性記録をレビューする。アップグレード経路が引き続きカバーされる場合にのみ期限切れの互換性を削除するか、意図的に持ち越す理由を記録する。 -4. 現在の `main` から `release/YYYY.M.D` を作成する。通常のリリース作業を `main` で直接行わない。 -5. 意図したタグに必要なすべてのバージョン箇所を更新し、その後ローカルの決定的なプリフライトを実行する: +1. 現在の `main` から開始する: 最新を pull し、対象コミットがプッシュ済みであることを確認し、 + 現在の `main` CI がブランチ作成に十分な程度に成功していることを確認する。 +2. 実際のコミット履歴から最上位の `CHANGELOG.md` セクションを + `/changelog` で書き直し、エントリをユーザー向けに保ち、コミットしてプッシュし、 + ブランチ作成前にもう一度 rebase/pull する。 +3. `src/plugins/compat/registry.ts` と + `src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性記録を確認する。期限切れの + 互換性はアップグレード経路が引き続きカバーされている場合にのみ削除し、そうでなければ + 意図的に保持している理由を記録する。 +4. 現在の `main` から `release/YYYY.M.D` を作成する。通常のリリース作業を + `main` で直接行わない。 +5. 予定しているタグに必要なすべてのバージョン箇所を更新し、その後 + ローカルの決定的プリフライトを実行する: `pnpm check:test-types`, `pnpm check:architecture`, - `pnpm build && pnpm ui:build`, `pnpm release:check`。 -6. `OpenClaw NPM Release` を `preflight_only=true` で実行する。タグが存在する前は、検証専用プリフライトのために40文字の完全なリリースブランチ SHA を使用できる。成功した `preflight_run_id` を保存する。 -7. リリースブランチ、タグ、または完全なコミット SHA に対して `Full Release Validation` ですべてのプレリリーステストを開始する。これは4つの大きなリリーステストボックス、つまり Vitest、Docker、QA Lab、Package の単一の手動エントリポイントです。 -8. 検証が失敗した場合は、リリースブランチ上で修正し、その修正を証明する最小の失敗ファイル、レーン、ワークフロージョブ、パッケージプロファイル、プロバイダー、またはモデル許可リストを再実行する。変更面によって以前の証拠が古くなる場合にのみ、完全な包括ワークフローを再実行する。 -9. ベータでは、`vYYYY.M.D-beta.N` をタグ付けし、npm dist-tag `beta` で公開し、その後公開済みの `openclaw@YYYY.M.D-beta.N` または `openclaw@beta` パッケージに対して公開後パッケージ受け入れを実行する。プッシュ済みまたは公開済みのベータに修正が必要な場合は、次の `-beta.N` を切る。古いベータを削除または書き換えない。 -10. 安定版では、検証済みのベータまたはリリース候補に必要な検証証拠がある場合にのみ続行する。安定版 npm 公開では、成功したプリフライトアーティファクトを `preflight_run_id` 経由で再利用する。安定版 macOS リリース準備には、パッケージ化された `.zip`、`.dmg`、`.dSYM.zip`、および `main` 上の更新済み `appcast.xml` も必要です。 -11. 公開後、npm 公開後検証ツール、公開後のチャンネル証明が必要な場合は任意のスタンドアロン公開済み npm Telegram E2E、必要に応じた dist-tag 昇格、完全に一致する `CHANGELOG.md` セクションからの GitHub リリース/プレリリースノート、およびリリース告知手順を実行する。 + `pnpm build && pnpm ui:build`, および `pnpm release:check`。 +6. `preflight_only=true` で `OpenClaw NPM Release` を実行する。タグが存在する前は、 + 検証専用プリフライトに完全な 40 文字のリリースブランチ SHA を使用できる。 + 成功した `preflight_run_id` を保存する。 +7. リリースブランチ、タグ、または完全なコミット SHA に対して + `Full Release Validation` ですべてのプレリリーステストを開始する。これは + 4 つの大きなリリーステストボックスである Vitest、Docker、QA Lab、Package の + 1 つの手動エントリポイントである。 +8. 検証が失敗した場合はリリースブランチで修正し、修正を証明する最小の失敗した + ファイル、レーン、ワークフロージョブ、パッケージプロファイル、プロバイダー、またはモデル許可リストを再実行する。 + 変更面によって既存の証拠が古くなる場合にのみ、全体のアンブレラを再実行する。 +9. beta の場合は `vYYYY.M.D-beta.N` をタグ付けし、npm dist-tag `beta` で公開してから、 + 公開済みの `openclaw@YYYY.M.D-beta.N` または `openclaw@beta` パッケージに対して + 公開後のパッケージ受け入れを実行する。プッシュ済みまたは公開済みの beta に修正が必要な場合は、 + 次の `-beta.N` を切る。古い beta を削除または書き換えない。 +10. stable の場合は、検証済みの beta またはリリース候補に必要な検証証拠がある場合にのみ続行する。 + stable npm 公開では、成功したプリフライト成果物を + `preflight_run_id` 経由で再利用する。stable macOS リリースの準備完了には、 + パッケージ化された `.zip`、`.dmg`、`.dSYM.zip`、および `main` 上の更新済み + `appcast.xml` も必要である。 +11. 公開後、npm 公開後検証ツール、公開後のチャンネル証拠が必要な場合の任意のスタンドアロン + 公開済み npm Telegram E2E、必要に応じた dist-tag 昇格、 + 完全に一致する `CHANGELOG.md` セクションからの GitHub リリース/プレリリースノート、 + およびリリース告知手順を実行する。 ## リリースプリフライト -- リリース事前検証の前に `pnpm check:test-types` を実行し、テストの TypeScript がより高速なローカル `pnpm check` ゲートの外でもカバーされるようにする -- リリース事前検証の前に `pnpm check:architecture` を実行し、より広範なインポートサイクルとアーキテクチャ境界のチェックがより高速なローカルゲートの外でもグリーンになるようにする -- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行し、パック検証ステップ用の想定される `dist/*` リリース成果物と Control UI バンドルが存在するようにする -- リリース承認の前に手動の `Full Release Validation` ワークフローを実行し、すべてのリリース前テストボックスを 1 つのエントリポイントから開始する。これはブランチ、タグ、または完全なコミット SHA を受け取り、手動の `CI` をディスパッチし、インストールスモーク、パッケージ受け入れ、Docker リリースパススイート、ライブ/E2E、OpenWebUI、QA Lab パリティ、Matrix、Telegram レーン用の `OpenClaw Release Checks` をディスパッチする。パッケージが公開済みで、公開後の Telegram E2E も実行する必要がある場合にのみ `npm_telegram_package_spec` を指定する。Telegram E2E を強制せずに、非公開の証拠レポートで検証が公開済み npm パッケージと一致することを証明する必要がある場合は `evidence_package_spec` を指定する。例: +- リリースのプリフライト前に `pnpm check:test-types` を実行し、テスト TypeScript が高速なローカル `pnpm check` ゲートの外でも + 対象に含まれるようにする +- リリースのプリフライト前に `pnpm check:architecture` を実行し、より広範なインポート + サイクルとアーキテクチャ境界チェックが高速なローカルゲートの外でもグリーンになるようにする +- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行し、想定される + `dist/*` リリース成果物と Control UI バンドルがパック + 検証ステップ用に存在するようにする +- リリース承認前に手動 `Full Release Validation` ワークフローを実行し、すべてのリリース前テストボックスを 1 つのエントリポイントから + 開始する。これはブランチ、 + タグ、または完全なコミット SHA を受け取り、手動 `CI` をディスパッチし、インストールスモーク、パッケージ受け入れ、Docker + リリースパススイート、ライブ/E2E、OpenWebUI、QA Lab パリティ、Matrix、Telegram + レーン用に `OpenClaw Release Checks` をディスパッチする。パッケージが + 公開済みで、公開後の Telegram E2E も実行する必要がある場合にのみ `npm_telegram_package_spec` を指定する。プライベート証跡レポートで、Telegram E2E を強制せずに + 検証が公開済み npm パッケージと一致することを証明する必要がある場合は + `evidence_package_spec` を指定する。 + 例: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- リリース作業を継続しながらパッケージ候補のサイドチャネル証拠が必要な場合は、手動の `Package Acceptance` ワークフローを実行する。`openclaw@beta`、`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使う。現在の `workflow_ref` ハーネスで信頼済みの `package_ref` ブランチ/タグ/SHA をパックするには `source=ref` を使う。必須の SHA-256 を伴う HTTPS tarball には `source=url` を使う。または、別の GitHub Actions 実行でアップロードされた tarball には `source=artifact` を使う。このワークフローは候補を `package-under-test` に解決し、その tarball に対して Docker E2E リリーススケジューラを再利用し、同じ tarball に対して `telegram_mode=mock-openai` または `telegram_mode=live-frontier` で Telegram QA を実行できる。 - 例: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai` - 共通プロファイル: - - `smoke`: インストール/チャネル/エージェント、Gateway ネットワーク、設定リロードのレーン +- リリース作業を続けながらパッケージ候補のサイドチャネル証跡が必要な場合は、手動 `Package Acceptance` ワークフローを実行する。`openclaw@beta`、 + `openclaw@latest`、または正確なリリースバージョンには `source=npm` を使用する。現在の + `workflow_ref` ハーネスで信頼済みの `package_ref` ブランチ/タグ/SHA をパックするには `source=ref` + を使用する。必須の SHA-256 付き HTTPS tarball には `source=url` を使用する。または、別の GitHub + Actions 実行でアップロードされた tarball には `source=artifact` を使用する。このワークフローは候補を + `package-under-test` に解決し、その tarball に対して Docker E2E リリーススケジューラを再利用し、 + 同じ tarball に対して `telegram_mode=mock-openai` または `telegram_mode=live-frontier` で + Telegram QA を実行できる。選択された Docker レーンに + `published-upgrade-survivor` が含まれる場合、パッケージ成果物が候補になり、`published_upgrade_survivor_baseline` が + 公開済みベースラインを選択する。 + 例: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` + 一般的なプロファイル: + - `smoke`: インストール/チャネル/エージェント、Gateway ネットワーク、構成リロードの各レーン - `package`: OpenWebUI またはライブ ClawHub を含まない、成果物ネイティブのパッケージ/更新/Plugin レーン - - `product`: パッケージプロファイルに加えて、MCP チャネル、cron/サブエージェントのクリーンアップ、OpenAI Web 検索、OpenWebUI - - `full`: OpenWebUI を含む Docker リリースパスチャンク + - `product`: パッケージプロファイルに加え、MCP チャネル、cron/サブエージェントのクリーンアップ、 + OpenAI Web 検索、OpenWebUI + - `full`: OpenWebUI を含む Docker リリースパスのチャンク - `custom`: 集中的な再実行用の正確な `docker_lanes` 選択 -- リリース候補に対して通常の CI の完全なカバレッジだけが必要な場合は、手動の `CI` ワークフローを直接実行する。手動 CI ディスパッチは変更範囲のスコープをバイパスし、Linux Node シャード、バンドル済み Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Android、Control UI i18n レーンを強制する。 +- リリース候補について通常の完全な CI カバレッジだけが必要な場合は、手動 `CI` ワークフローを直接実行する。手動 CI ディスパッチは変更スコープを + バイパスし、Linux Node シャード、同梱 Plugin シャード、チャネル + 契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、 + ドキュメントチェック、Python Skills、Windows、macOS、Android、Control UI i18n + レーンを強制する。 例: `gh workflow run ci.yml --ref release/YYYY.M.D` -- リリーステレメトリを検証するときは `pnpm qa:otel:smoke` を実行する。これはローカル OTLP/HTTP レシーバーを通じて QA-lab を実行し、Opik、Langfuse、または別の外部コレクターを必要とせずに、エクスポートされたトレーススパン名、境界付き属性、コンテンツ/識別子のリダクションを検証する。 -- すべてのタグ付きリリースの前に `pnpm release:check` を実行する +- リリーステレメトリを検証する場合は `pnpm qa:otel:smoke` を実行する。これは + ローカル OTLP/HTTP レシーバーを通じて QA-lab を実行し、Opik、Langfuse、その他の外部コレクターを + 必要とせずに、エクスポートされたトレース + スパン名、制限付き属性、コンテンツ/識別子のリダクションを検証する。 +- すべてのタグ付きリリース前に `pnpm release:check` を実行する - リリースチェックは現在、別の手動ワークフローで実行される: `OpenClaw Release Checks` -- `OpenClaw Release Checks` は、リリース承認の前に QA Lab モックパリティゲートに加え、高速なライブ Matrix プロファイルと Telegram QA レーンも実行する。ライブレーンは `qa-live-shared` 環境を使う。Telegram は Convex CI の資格情報リースも使う。完全な Matrix トランスポート、メディア、E2EE インベントリを並列で確認したい場合は、`matrix_profile=all` と `matrix_shards=true` で手動の `QA-Lab - All Lanes` ワークフローを実行する。 -- クロス OS インストールおよびアップグレードのランタイム検証は、再利用可能ワークフロー `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す公開 `OpenClaw Release Checks` と `Full Release Validation` の一部である -- この分割は意図的なもの。実際の npm リリースパスを短く、決定的で、成果物中心に保ちつつ、遅いライブチェックは独自のレーンに置き、公開を停滞またはブロックしないようにする -- シークレットを伴うリリースチェックは、ワークフローのロジックとシークレットが制御された状態に保たれるように、`Full Release Validation` 経由、または `main`/release ワークフロー ref からディスパッチする必要がある -- `OpenClaw Release Checks` は、解決されたコミットが OpenClaw ブランチまたはリリースタグから到達可能である限り、ブランチ、タグ、または完全なコミット SHA を受け取る -- `OpenClaw NPM Release` の検証専用事前検証は、プッシュ済みタグを必要とせずに、現在の完全な 40 文字のワークフローブランチコミット SHA も受け取る -- その SHA パスは検証専用であり、実際の公開に昇格することはできない -- SHA モードでは、ワークフローはパッケージメタデータチェックのためだけに `v` を合成する。実際の公開には引き続き実際のリリースタグが必要である -- どちらのワークフローも、実際の公開と昇格のパスは GitHub ホストランナー上に保ち、変更を伴わない検証パスではより大きな Blacksmith Linux ランナーを使用できる -- そのワークフローは、`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` を `OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方のワークフローシークレットを使って実行する -- npm リリース事前検証は、別のリリースチェックレーンを待たなくなった -- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（または対応する beta/修正版タグ）を実行する -- npm 公開後、`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（または対応する beta/修正版バージョン）を実行し、新しい一時プレフィックスで公開済みレジストリのインストールパスを検証する -- beta 公開後、共有リース済み Telegram 資格情報プールを使って、公開済み npm パッケージに対するインストール済みパッケージのオンボーディング、Telegram セットアップ、実際の Telegram E2E を検証するために、`OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` を実行する。ローカルのメンテナーによる一回限りの実行では、Convex 変数を省略し、3 つの `OPENCLAW_QA_TELEGRAM_*` 環境資格情報を直接渡してもよい。 -- メンテナーは、GitHub Actions から手動の `NPM Telegram Beta E2E` ワークフロー経由で同じ公開後チェックを実行できる。これは意図的に手動専用であり、すべてのマージで実行されるわけではない。 -- メンテナーのリリース自動化は現在、事前検証後に昇格する方式を使う: +- `OpenClaw Release Checks` はリリース承認前に、QA Lab モックパリティゲートに加えて高速な + ライブ Matrix プロファイルと Telegram QA レーンも実行する。ライブ + レーンは `qa-live-shared` 環境を使用し、Telegram は Convex CI + 認証情報リースも使用する。Matrix の + トランスポート、メディア、E2EE インベントリ全体を並列で実行したい場合は、`matrix_profile=all` と `matrix_shards=true` で手動 `QA-Lab - All Lanes` ワークフローを実行する。 +- クロス OS インストールとアップグレードのランタイム検証は、公開 + `OpenClaw Release Checks` と `Full Release Validation` の一部であり、再利用可能ワークフロー + `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す +- この分割は意図的なもの: 実際の npm リリースパスを短く、 + 決定的で、成果物に集中したものに保ちつつ、時間のかかるライブチェックは独自のレーンに置き、 + 公開を停滞またはブロックしないようにするため +- シークレットを含むリリースチェックは `Full Release +Validation` を通じて、または `main`/release ワークフロー ref からディスパッチし、ワークフローロジックと + シークレットを制御された状態に保つ必要がある +- `OpenClaw Release Checks` は、解決されたコミットが OpenClaw ブランチまたはリリースタグから到達可能である限り、 + ブランチ、タグ、または完全なコミット SHA を受け付ける +- `OpenClaw NPM Release` の検証専用プリフライトも、プッシュ済みタグを要求せずに、現在の + 完全な 40 文字のワークフローブランチコミット SHA を受け付ける +- その SHA パスは検証専用であり、実際の公開に昇格できない +- SHA モードでは、ワークフローはパッケージメタデータチェックのためだけに `v` を + 合成する。実際の公開には引き続き実際のリリースタグが必要 +- 両方のワークフローは実際の公開と昇格パスを GitHub ホストランナー上に保ちつつ、 + 非変更の検証パスでは、より大きな Blacksmith Linux ランナーを使用できる +- そのワークフローは + `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` + を、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方のワークフローシークレットを使って実行する +- npm リリースプリフライトは、別個のリリースチェックレーンを待たなくなった +- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` + (または対応するベータ/修正版タグ) を実行する +- npm 公開後に + `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` + (または対応するベータ/修正版バージョン) を実行し、新しい一時プレフィックスで公開済みレジストリの + インストールパスを検証する +- ベータ公開後に `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` + を実行し、共有リース済み Telegram 認証情報 + プールを使って、公開済み npm パッケージに対するインストール済みパッケージのオンボーディング、Telegram セットアップ、実際の Telegram E2E + を検証する。ローカルメンテナーの単発実行では Convex 変数を省略し、3 つの + `OPENCLAW_QA_TELEGRAM_*` env 認証情報を直接渡してもよい。 +- メンテナーは、手動 `NPM Telegram Beta E2E` ワークフローを使って、GitHub Actions から同じ公開後チェックを実行できる。これは意図的に手動専用であり、 + すべてのマージで実行されるわけではない。 +- メンテナー向けリリース自動化は現在、プリフライト後に昇格する方式を使用する: - 実際の npm 公開は、成功した npm `preflight_run_id` に合格している必要がある - - 実際の npm 公開は、成功した事前検証実行と同じ `main` または `release/YYYY.M.D` ブランチからディスパッチされている必要がある - - stable npm リリースのデフォルトは `beta` - - stable npm 公開は、ワークフロー入力で明示的に `latest` を対象にできる - - トークンベースの npm dist-tag 変更は現在、セキュリティのため `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` に置かれている。これは、公開リポジトリが OIDC のみの公開を維持する一方で、`npm dist-tag add` にはまだ `NPM_TOKEN` が必要なためである - - 公開 `macOS Release` は検証専用である - - 実際の非公開 mac 公開は、成功した非公開 mac の `preflight_run_id` と `validate_run_id` に合格している必要がある - - 実際の公開パスは、準備済み成果物を再ビルドせずに昇格する -- `YYYY.M.D-N` のような stable 修正版リリースでは、公開後検証ツールは同じ一時プレフィックスのアップグレードパスも `YYYY.M.D` から `YYYY.M.D-N` へ確認し、リリース修正版が古いグローバルインストールをベース stable ペイロードのまま静かに残さないようにする -- npm リリース事前検証は、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` ペイロードの両方が含まれていない限り、フェイルクローズする。これにより、空のブラウザダッシュボードを再び出荷しないようにする -- 公開後検証では、公開済みレジストリのインストールに、ルートの `dist/*` レイアウト配下で空でないバンドル済み Plugin ランタイム依存関係が含まれていることも確認する。バンドル済み Plugin 依存関係ペイロードが欠落または空のまま出荷されたリリースは、公開後検証に失敗し、`latest` に昇格できない。 -- `pnpm test:install:smoke` は、候補更新 tarball に対して npm パックの `unpackedSize` 予算も強制するため、インストーラー e2e はリリース公開パスの前に偶発的なパック肥大化を検出する -- リリース作業で CI 計画、Plugin タイミングマニフェスト、または Plugin テストマトリックスに触れた場合は、承認前に `.github/workflows/plugin-prerelease.yml` からプランナー所有の `plugin-prerelease-extension-shard` マトリックス出力を再生成してレビューし、リリースノートが古い CI レイアウトを説明しないようにする -- stable macOS リリース準備には、アップデーターのサーフェスも含まれる: - - GitHub リリースには、パッケージ化された `.zip`、`.dmg`、`.dSYM.zip` が最終的に含まれている必要がある - - `main` 上の `appcast.xml` は、公開後に新しい stable zip を指している必要がある - - パッケージ化されたアプリは、非デバッグのバンドル ID、空でない Sparkle フィード URL、そのリリースバージョンの正規 Sparkle ビルド下限以上の `CFBundleVersion` を維持している必要がある + - 実際の npm 公開は、成功したプリフライト実行と同じ `main` または + `release/YYYY.M.D` ブランチからディスパッチされている必要がある + - 安定版 npm リリースのデフォルトは `beta` + - 安定版 npm 公開は、ワークフロー入力で明示的に `latest` を対象にできる + - トークンベースの npm dist-tag 変更は現在、セキュリティのため + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` にある。これは、公開リポジトリが OIDC のみの公開を維持する一方で、 + `npm dist-tag add` には引き続き `NPM_TOKEN` が必要なため + - 公開 `macOS Release` は検証専用である。タグがリリースブランチにのみ存在するが + ワークフローが `main` からディスパッチされる場合は、 + `public_release_branch=release/YYYY.M.D` を設定する + - 実際のプライベート Mac 公開は、成功したプライベート Mac + `preflight_run_id` と `validate_run_id` に合格している必要がある + - 実際の公開パスは、成果物を再ビルドするのではなく、準備済み成果物を昇格する +- `YYYY.M.D-N` のような安定版修正リリースでは、公開後検証ツールが + `YYYY.M.D` から `YYYY.M.D-N` への同じ一時プレフィックスアップグレードパスもチェックし、 + リリース修正が古いグローバルインストールをベース安定版ペイロードのままに + 気づかず残さないようにする +- npm リリースプリフライトは、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` ペイロードの両方が含まれていない限り + クローズドに失敗する。これにより、空のブラウザダッシュボードを再び出荷しない +- 公開後検証では、公開済みレジストリインストールに、ルート `dist/*` + レイアウト配下の空でない同梱 Plugin ランタイム依存関係が含まれることも確認する。同梱 Plugin + 依存関係ペイロードが欠落または空のまま出荷されるリリースは公開後検証ツールに失敗し、 + `latest` に昇格できない。 +- `pnpm test:install:smoke` は、候補更新 tarball に対して npm pack の `unpackedSize` 予算も適用するため、 + インストーラー e2e がリリース公開パスの前に偶発的なパック肥大を検出する +- リリース作業が CI 計画、Plugin タイミングマニフェスト、または + Plugin テストマトリックスに触れた場合は、承認前に + `.github/workflows/plugin-prerelease.yml` からプランナー所有の `plugin-prerelease-extension-shard` マトリックス出力を再生成してレビューし、リリースノートが + 古い CI レイアウトを説明しないようにする +- 安定版 macOS リリースの準備状況には、アップデーター関連の面も含まれる: + - GitHub リリースには、パッケージ済みの `.zip`、`.dmg`、`.dSYM.zip` が最終的に含まれている必要がある + - 公開後、`main` 上の `appcast.xml` は新しい安定版 zip を指している必要がある + - パッケージ済みアプリは、非デバッグのバンドル ID、空でない Sparkle フィード + URL、そのリリースバージョンの正規 Sparkle ビルド下限以上の `CFBundleVersion` を維持する必要がある ## リリーステストボックス -`Full Release Validation` は、オペレーターがすべてのリリース前テストを 1 つのエントリポイントから開始する方法である。信頼済みの `main` ワークフロー ref から実行し、リリースブランチ、タグ、または完全なコミット SHA を `ref` として渡す: +`Full Release Validation` は、オペレーターが 1 つのエントリポイントからすべてのリリース前テストを +開始する方法である。信頼済みの `main` ワークフロー ref から実行し、リリース +ブランチ、タグ、または完全なコミット SHA を `ref` として渡す: ```bash gh workflow run full-release-validation.yml \ @@ -126,23 +231,44 @@ gh workflow run full-release-validation.yml \ -f ref=release/YYYY.M.D \ -f provider=openai \ -f mode=both \ - -f release_profile=full \ + -f release_profile=stable \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -このワークフローはターゲット ref を解決し、`target_ref=` で手動の `CI` をディスパッチし、`OpenClaw Release Checks` をディスパッチし、`npm_telegram_package_spec` が設定されている場合は、任意でスタンドアロンの公開後 Telegram E2E をディスパッチする。その後、`OpenClaw Release Checks` は、インストールスモーク、クロス OS リリースチェック、ライブ/E2E Docker リリースパスカバレッジ、Telegram パッケージ QA を伴う Package Acceptance、QA Lab パリティ、ライブ Matrix、ライブ Telegram にファンアウトする。完全な実行が許容されるのは、`Full Release Validation` サマリーで `normal_ci` と `release_checks` が成功しており、任意の `npm_telegram` 子が成功しているか意図的にスキップされている場合のみである。最終検証サマリーには各子実行の最遅ジョブ表が含まれるため、リリースマネージャーはログをダウンロードせずに現在のクリティカルパスを確認できる。 -子ワークフローは、ターゲット `ref` が古いリリースブランチまたはタグを指している場合でも、`Full Release Validation` を実行する信頼済み ref、通常は `--ref main` からディスパッチされる。別個の Full Release Validation ワークフロー ref 入力は存在しない。ワークフロー実行 ref を選ぶことで、信頼済みハーネスを選択する。 +このワークフローは対象 ref を解決し、`target_ref=` で手動 `CI` をディスパッチし、 +`OpenClaw Release Checks` をディスパッチし、 +`npm_telegram_package_spec` が設定されている場合は任意でスタンドアロンの公開後 Telegram E2E をディスパッチする。その後、`OpenClaw Release Checks` は +インストールスモーク、クロス OS リリースチェック、ライブ/E2E Docker リリースパスカバレッジ、 +Telegram パッケージ QA を含む Package Acceptance、QA Lab パリティ、ライブ Matrix、ライブ Telegram に展開する。フル実行が受け入れられるのは、`Full Release Validation` +サマリーで `normal_ci` と `release_checks` が成功しており、任意の +`npm_telegram` 子が成功しているか意図的にスキップされている場合のみである。最終 +検証サマリーには各子実行の最遅ジョブ表が含まれるため、リリース +マネージャーはログをダウンロードせずに現在のクリティカルパスを確認できる。 +完全なステージマトリックス、正確なワークフロージョブ名、安定版とフルプロファイルの +違い、成果物、集中的な再実行ハンドルについては、[フルリリース検証](/ja-JP/reference/full-release-validation) を参照。 +子ワークフローは、`Full Release +Validation` を実行する信頼済み ref、通常は `--ref main` からディスパッチされる。これは対象 `ref` が +古いリリースブランチまたはタグを指す場合でも同じである。Full Release Validation 専用の +ワークフロー ref 入力はない。信頼済みハーネスはワークフロー実行 ref を選択して指定する。 -ライブ/プロバイダーの広さを選択するには `release_profile` を使う: +ライブ/プロバイダーの範囲を選択するには `release_profile` を使用する: -- `minimum`: 最速のリリースクリティカルな OpenAI/core ライブおよび Docker パス -- `stable`: リリース承認用に minimum に stable プロバイダー/バックエンドカバレッジを追加 +- `minimum`: 最速のリリース重要 OpenAI/core ライブおよび Docker パス +- `stable`: リリース承認用に minimum に安定版プロバイダー/バックエンドカバレッジを追加 - `full`: stable に広範なアドバイザリプロバイダー/メディアカバレッジを追加 -`OpenClaw Release Checks` は、信頼済みワークフロー ref を使ってターゲット ref を一度 `release-package-under-test` として解決し、リリースパス Docker チェックと Package Acceptance の両方でその成果物を再利用する。これにより、パッケージ向けのすべてのボックスが同じバイト列を使い、パッケージの再ビルドを繰り返さずに済む。 -クロス OS OpenAI インストールスモークは、repo/org 変数が設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` を使い、それ以外の場合は `openai/gpt-5.4-mini` を使う。このレーンは、最も遅いデフォルトモデルのベンチマークではなく、パッケージインストール、オンボーディング、Gateway 起動、1 回のライブエージェントターンを証明するためである。より広範なライブプロバイダーマトリックスが、モデル固有のカバレッジの場である。 +`OpenClaw Release Checks` は、信頼済みワークフロー ref を使用して対象 +ref を `release-package-under-test` として一度だけ解決し、そのアーティファクトを +release-path Docker チェックと Package Acceptance の両方で再利用します。これにより、 +パッケージ向けのすべてのボックスが同じバイト列を使い、パッケージビルドの繰り返しを避けられます。 +cross-OS OpenAI install smoke は、repo/org 変数が設定されている場合は +`OPENCLAW_CROSS_OS_OPENAI_MODEL` を使用し、そうでない場合は `openai/gpt-5.4-mini` +を使用します。このレーンは、最も遅いデフォルトモデルのベンチマークではなく、 +パッケージインストール、オンボーディング、Gateway 起動、1 回の live agent ターンを +証明するためのものだからです。より広範な live provider matrix が、モデル固有の +カバレッジの場所として残ります。 -リリース段階に応じて、これらのバリアントを使う: +リリース段階に応じて、これらのバリアントを使用します。 ```bash # Validate an unpublished release candidate branch. @@ -171,22 +297,37 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -焦点を絞った修正後の最初の再実行として、包括的な全体ワークフローを使用しないでください。1 つのボックスが失敗した場合は、次の証明には失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデルプロバイダー、または QA レーンを使用します。修正が共有リリースオーケストレーションを変更した場合、または以前の全ボックス証拠が古くなった場合にのみ、包括的な全体ワークフローを再実行してください。包括的な全体ワークフローの最終検証では、記録された子ワークフロー実行 ID が再チェックされるため、子ワークフローの再実行が成功した後は、失敗した親ジョブ `Verify full validation` だけを再実行します。 +焦点を絞った修正後の最初の再実行として、フル umbrella を使用しないでください。1 つのボックスが +失敗した場合は、次の証明に、失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデル +provider、または QA レーンを使用します。修正によって共有リリースオーケストレーションが変更された場合、または +以前の全ボックス証拠が古くなった場合にのみ、フル umbrella を再度実行します。umbrella の最終 verifier は、記録された子ワークフロー実行 +ID を再チェックするため、子ワークフローを正常に再実行した後は、失敗した +`Verify full validation` 親ジョブだけを再実行します。 -範囲を限定したリカバリーでは、包括的な全体ワークフローに `rerun_group` を渡します。`all` は実際のリリース候補実行、`ci` は通常の CI 子だけを実行し、`plugin-prerelease` はリリース専用 Plugin 子だけを実行し、`release-checks` はすべてのリリースボックスを実行します。より狭いリリースグループは、スタンドアロンのパッケージ Telegram レーンが指定されている場合、`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` です。 +範囲を限定した復旧には、umbrella に `rerun_group` を渡します。`all` は実際の +リリース候補実行、`ci` は通常の CI 子だけを実行し、`plugin-prerelease` +はリリース専用 Plugin 子だけを実行し、`release-checks` はすべてのリリース +ボックスを実行します。より狭いリリースグループは、単独のパッケージ Telegram レーンが指定されている場合の +`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、および `npm-telegram` です。 ### Vitest -Vitest ボックスは手動の `CI` 子ワークフローです。手動 CI は意図的に変更範囲による絞り込みを回避し、リリース候補に対して通常のテストグラフを強制します。対象は Linux Node シャード、バンドル済み Plugin シャード、チャンネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Android、Control UI i18n です。 +Vitest ボックスは手動の `CI` 子ワークフローです。手動 CI は意図的に +changed スコープをバイパスし、リリース候補に対して通常のテストグラフを強制します: +Linux Node シャード、バンドル済み Plugin シャード、チャネル契約、Node 22 +互換性、`check`、`check-additional`、build smoke、docs checks、Python +Skills、Windows、macOS、Android、および Control UI i18n。 -このボックスは、「ソースツリーが通常の完全なテストスイートに合格したか」に答えるために使用します。これはリリースパスのプロダクト検証とは同じではありません。保持する証拠: +このボックスは「ソースツリーが通常のフルテストスイートを通過したか」に答えるために使用します。 +release-path の製品検証とは同じではありません。保持する証拠: -- ディスパッチされた `CI` 実行 URL を示す `Full Release Validation` サマリー -- 正確なターゲット SHA で成功した `CI` 実行 +- dispatch された `CI` 実行 URL を示す `Full Release Validation` サマリー +- 正確な対象 SHA で green になった `CI` 実行 - 回帰を調査するときの CI ジョブからの失敗または遅いシャード名 - 実行にパフォーマンス分析が必要な場合の `.artifacts/vitest-shard-timings.json` などの Vitest タイミングアーティファクト -リリースに決定的な通常 CI が必要だが、Docker、QA Lab、ライブ、クロス OS、またはパッケージボックスが不要な場合にのみ、手動 CI を直接実行します。 +リリースに決定論的な通常 CI が必要で、Docker、QA Lab、live、cross-OS、またはパッケージボックスが不要な場合にのみ、 +手動 CI を直接実行します。 ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -194,50 +335,102 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker ボックスは `OpenClaw Release Checks` の中の `openclaw-live-and-e2e-checks-reusable.yml` と、リリースモードの `install-smoke` ワークフローにあります。これはソースレベルのテストだけでなく、パッケージ化された Docker 環境を通じてリリース候補を検証します。 +Docker ボックスは、`openclaw-live-and-e2e-checks-reusable.yml` を通じた +`OpenClaw Release Checks` と、release-mode の +`install-smoke` ワークフローにあります。ソースレベルのテストだけでなく、パッケージ化された +Docker 環境を通じてリリース候補を検証します。 -リリース Docker カバレッジには次が含まれます。 +リリース Docker カバレッジには以下が含まれます。 -- 低速な Bun グローバルインストールスモークを有効にした完全なインストールスモーク -- ターゲット SHA ごとのルート Dockerfile スモークイメージ準備/再利用。QR、ルート/Gateway、インストーラー/Bun スモークジョブは個別の install-smoke シャードとして実行 +- 遅い Bun グローバルインストール smoke を有効にした full install smoke +- 対象 SHA ごとの root Dockerfile smoke イメージ準備/再利用。QR、 + root/gateway、installer/Bun smoke ジョブは個別の install-smoke + シャードとして実行 - リポジトリ E2E レーン -- リリースパス Docker チャンク: `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b`、`bundled-channels-contracts` +- release-path Docker チャンク: `core`、`package-update-openai`、 + `package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、 + `plugins-runtime-services`、 + `plugins-runtime-install-a`、`plugins-runtime-install-b`、 + `plugins-runtime-install-c`、`plugins-runtime-install-d`、 + `plugins-runtime-install-e`、`plugins-runtime-install-f`、 + `plugins-runtime-install-g`、`plugins-runtime-install-h`、 + `bundled-channels-core`、`bundled-channels-update-a`、 + `bundled-channels-update-discord`、`bundled-channels-update-b`、および + `bundled-channels-contracts` - 要求された場合の `plugins-runtime-services` チャンク内の OpenWebUI カバレッジ -- バンドル済みチャンネル依存レーンを、1 つの大きなバンドル済みチャンネルジョブではなく、channel-smoke、update-target、setup/runtime 契約チャンクに分割 -- 分割されたバンドル済み Plugin インストール/アンインストールレーン `bundled-plugin-install-uninstall-0` から `bundled-plugin-install-uninstall-23` -- リリースチェックにライブスイートが含まれる場合のライブ/E2E プロバイダースイートと Docker ライブモデルカバレッジ +- 1 つの大きな bundled-channel ジョブではなく、channel-smoke、update-target、 + setup/runtime contract チャンクに分割された bundled-channel 依存関係レーン +- `bundled-plugin-install-uninstall-0` から + `bundled-plugin-install-uninstall-23` までの、分割されたバンドル済み Plugin install/uninstall レーン +- リリースチェックに live スイートが含まれる場合の live/E2E provider スイートと Docker live model カバレッジ -再実行の前に Docker アーティファクトを使用してください。リリースパスのスケジューラーは `.artifacts/docker-tests/` をアップロードし、そこにはレーンログ、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、再実行コマンドが含まれます。焦点を絞ったリカバリーでは、すべてのリリースチャンクを再実行するのではなく、再利用可能なライブ/E2E ワークフローで `docker_lanes=` を使用します。生成される再実行コマンドには、利用可能な場合、以前の `package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、失敗したレーンは同じ tarball と GHCR イメージを再利用できます。 +再実行する前に Docker アーティファクトを使用してください。release-path scheduler は +`.artifacts/docker-tests/` をアップロードし、レーンログ、`summary.json`、`failures.json`、 +フェーズタイミング、scheduler plan JSON、および再実行コマンドを含めます。焦点を絞った復旧には、 +すべてのリリースチャンクを再実行する代わりに、再利用可能な live/E2E ワークフローで +`docker_lanes=` を使用します。生成された再実行コマンドには、利用可能な場合、以前の +`package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、 +失敗したレーンは同じ tarball と GHCR イメージを再利用できます。 ### QA Lab -QA Lab ボックスも `OpenClaw Release Checks` の一部です。これはエージェント的な振る舞いとチャンネルレベルのリリースゲートであり、Vitest や Docker パッケージ機構とは別です。 +QA Lab ボックスも `OpenClaw Release Checks` の一部です。これは agentic +behavior とチャネルレベルのリリースゲートであり、Vitest や Docker +パッケージ機構とは別のものです。 -リリース QA Lab カバレッジには次が含まれます。 +リリース QA Lab カバレッジには以下が含まれます。 -- エージェント的パリティパックを使用して OpenAI 候補レーンを Opus 4.6 ベースラインと比較するモックパリティゲート -- `qa-live-shared` 環境を使用する高速ライブ Matrix QA プロファイル -- Convex CI 認証情報リースを使用するライブ Telegram QA レーン -- リリーステレメトリーに明示的なローカル証明が必要な場合の `pnpm qa:otel:smoke` +- agentic parity pack を使用して OpenAI 候補レーンを Opus 4.6 + ベースラインと比較する mock parity gate +- `qa-live-shared` 環境を使用する高速 live Matrix QA プロファイル +- Convex CI credential lease を使用する live Telegram QA レーン +- リリース telemetry に明示的なローカル証明が必要な場合の `pnpm qa:otel:smoke` -このボックスは、「リリースが QA シナリオとライブチャンネルフローで正しく動作するか」に答えるために使用します。リリースを承認するときは、パリティ、Matrix、Telegram レーンのアーティファクト URL を保持してください。完全な Matrix カバレッジは、デフォルトのリリースクリティカルレーンではなく、手動のシャード化された QA-Lab 実行として引き続き利用できます。 +このボックスは「リリースが QA シナリオと live チャネルフローで正しく動作するか」に答えるために使用します。 +リリースを承認するときは、parity、Matrix、Telegram レーンのアーティファクト URL を保持してください。 +Full Matrix カバレッジは、デフォルトの release-critical レーンではなく、手動の sharded QA-Lab 実行として引き続き利用できます。 ### パッケージ -パッケージボックスはインストール可能なプロダクトのゲートです。これは `Package Acceptance` とリゾルバー `scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。リゾルバーは候補を Docker E2E で消費される `package-under-test` tarball に正規化し、パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、ワークフローハーネス ref をパッケージソース ref から分離して保持します。 +Package ボックスは、インストール可能な製品のゲートです。これは +`Package Acceptance` と resolver +`scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。resolver は候補を +Docker E2E が消費する `package-under-test` tarball に正規化し、 +パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、 +ワークフローハーネス ref をパッケージソース ref から分離します。 サポートされる候補ソース: -- `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な OpenClaw リリースバージョン -- `source=ref`: 選択された `workflow_ref` ハーネスで、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパックする -- `source=url`: 必須の `package_sha256` を指定して HTTPS `.tgz` をダウンロードする +- `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な OpenClaw リリース + バージョン +- `source=ref`: 選択した `workflow_ref` ハーネスで、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA + を pack する +- `source=url`: 必須の `package_sha256` を伴う HTTPS `.tgz` をダウンロードする - `source=artifact`: 別の GitHub Actions 実行によってアップロードされた `.tgz` を再利用する -`OpenClaw Release Checks` は、`source=ref`、`package_ref=`、`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline`、`telegram_mode=mock-openai` で Package Acceptance を実行します。リリースパス Docker チャンクは、重複するインストール、更新、Plugin 更新レーンをカバーします。Package Acceptance は、同じ解決済み tarball に対して、アーティファクトネイティブなバンドル済みチャンネル互換性、オフライン Plugin フィクスチャ、Telegram パッケージ QA を維持します。これは、以前は Parallels が必要だったパッケージ/更新カバレッジの大部分に対する GitHub ネイティブな置き換えです。クロス OS リリースチェックは OS 固有のオンボーディング、インストーラー、プラットフォーム挙動に引き続き重要ですが、パッケージ/更新のプロダクト検証では Package Acceptance を優先してください。 +`OpenClaw Release Checks` は、`source=ref`、 +`package_ref=`、`suite_profile=custom`、 +`docker_lanes=bundled-channel-deps-compat plugins-offline`、および +`telegram_mode=mock-openai` で Package Acceptance を実行します。release-path Docker チャンクは、 +重複する install、update、および plugin-update レーンをカバーします。Package Acceptance は、 +artifact-native の bundled-channel compat、offline plugin fixtures、および Telegram +package QA を、同じ解決済み tarball に対して保持します。これは、以前は +Parallels が必要だった package/update カバレッジの大半に対する GitHub-native の +置き換えです。cross-OS release checks は OS 固有のオンボーディング、 +installer、および platform behavior について引き続き重要ですが、package/update の製品検証では +Package Acceptance を優先するべきです。 -レガシー package-acceptance の許容は意図的に期限付きです。`2026.4.25` までのパッケージは、すでに npm に公開済みのメタデータギャップに対して互換性パスを使用できます。対象は tarball に含まれない非公開 QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャ内の欠落パッチファイル、欠落した永続化 `update.channel`、レガシー Plugin インストール記録の場所、欠落したマーケットプレイスインストール記録の永続化、`plugins update` 中の設定メタデータ移行です。公開済みの `2026.4.26` パッケージは、すでに出荷されたローカルビルドメタデータスタンプファイルについて警告しても構いません。それ以降のパッケージは、現代のパッケージ契約を満たす必要があります。同じギャップはリリース検証で失敗します。 +レガシー package-acceptance の緩和は、意図的に期限付きです。 +`2026.4.25` までのパッケージは、すでに npm に公開されたメタデータギャップについて互換性パスを使用できます: +tarball に含まれない private QA inventory entries、欠落した +`gateway install --wrapper`、tarball 由来の git +fixture に含まれない patch files、欠落した永続化 `update.channel`、レガシー Plugin install-record +locations、欠落した marketplace install-record persistence、および `plugins update` 中の config metadata +migration。公開済みの `2026.4.26` パッケージでは、すでに出荷された local build metadata stamp files について +警告が出る場合があります。それ以降のパッケージは、現代のパッケージ契約を満たす必要があります。同じギャップはリリース +検証で失敗します。 -リリースの問いが実際にインストール可能なパッケージに関するものである場合は、より広い Package Acceptance プロファイルを使用します。 +リリースの質問が実際のインストール可能パッケージに関する場合は、より広範な Package Acceptance プロファイルを使用します。 ```bash gh workflow run package-acceptance.yml \ @@ -245,62 +438,85 @@ gh workflow run package-acceptance.yml \ -f workflow_ref=main \ -f source=npm \ -f package_spec=openclaw@beta \ - -f suite_profile=product + -f suite_profile=product \ + -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` 一般的なパッケージプロファイル: -- `smoke`: 簡易パッケージインストール/チャンネル/エージェント、Gateway ネットワーク、設定リロードレーン -- `package`: ライブ ClawHub なしのインストール/更新/Plugin パッケージ契約。これはリリースチェックのデフォルト -- `product`: `package` に加えて MCP チャンネル、cron/subagent クリーンアップ、OpenAI web search、OpenWebUI -- `full`: OpenWebUI を含む Docker リリースパスチャンク +- `smoke`: 簡易パッケージ install/channel/agent、gateway network、および config + reload レーン +- `package`: live ClawHub なしの install/update/plugin package contracts。これは release-check + のデフォルトです +- `product`: `package` に MCP channels、cron/subagent cleanup、OpenAI web + search、および OpenWebUI を加えたもの +- `full`: OpenWebUI 付きの Docker release-path チャンク - `custom`: 焦点を絞った再実行用の正確な `docker_lanes` リスト -パッケージ候補 Telegram 証明では、Package Acceptance で `telegram_mode=mock-openai` または `telegram_mode=live-frontier` を有効にします。このワークフローは解決済みの `package-under-test` tarball を Telegram レーンに渡します。スタンドアロン Telegram ワークフローは、公開後チェック用に公開済み npm spec を引き続き受け付けます。 +package-candidate Telegram 証明には、Package Acceptance で `telegram_mode=mock-openai` または +`telegram_mode=live-frontier` を有効にします。ワークフローは、解決済みの +`package-under-test` tarball を Telegram レーンに渡します。単独の +Telegram ワークフローは、公開後チェック用に公開済み npm spec を引き続き受け付けます。 ## NPM ワークフロー入力 -`OpenClaw NPM Release` は、次のオペレーター制御入力を受け付けます。 +`OpenClaw NPM Release` は、以下の operator-controlled inputs を受け付けます。 -- `tag`: `v2026.4.2`、`v2026.4.2-1`、`v2026.4.2-beta.1` などの必須リリースタグ。`preflight_only=true` の場合は、検証専用プリフライトのために、現在の完全な 40 文字のワークフローブランチコミット SHA も使用できます -- `preflight_only`: 検証/ビルド/パッケージのみの場合は `true`、実際の公開パスの場合は `false` -- `preflight_run_id`: 実際の公開パスで必須。ワークフローが成功したプリフライト実行から準備済み tarball を再利用するために使用します -- `npm_dist_tag`: 公開パスの npm ターゲットタグ。デフォルトは `beta` +- `tag`: 必須のリリースタグ。例: `v2026.4.2`、`v2026.4.2-1`、または + `v2026.4.2-beta.1`。`preflight_only=true` の場合は、validation-only preflight 用に現在の + 完全な 40 文字の workflow-branch commit SHA も使用できます +- `preflight_only`: validation/build/package のみの場合は `true`、実際の publish path の場合は `false` +- `preflight_run_id`: 実際の publish path で必須。これにより、ワークフローは成功した preflight run から + 準備済み tarball を再利用します +- `npm_dist_tag`: publish path の npm target tag。デフォルトは `beta` -`OpenClaw Release Checks` は、次のオペレーター制御入力を受け付けます。 +`OpenClaw Release Checks` は、以下の operator-controlled inputs を受け付けます。 -- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを含むチェックでは、解決されたコミットが OpenClaw ブランチまたはリリースタグから到達可能である必要があります。 +- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを持つチェックでは、 + 解決されたコミットが OpenClaw ブランチまたは + リリースタグから到達可能である必要があります。 ルール: -- stable タグと correction タグは `beta` または `latest` のいずれにも公開できます -- Beta プレリリースタグは `beta` にのみ公開できます -- `OpenClaw NPM Release` では、完全なコミット SHA 入力は `preflight_only=true` の場合にのみ許可されます -- `OpenClaw Release Checks` と `Full Release Validation` は常に検証専用です -- 実際の公開パスでは、プリフライト中に使用したものと同じ `npm_dist_tag` を使用する必要があります。ワークフローは、公開前にそのメタデータが継続していることを検証します +- stable タグと correction タグは、`beta` または `latest` のどちらにも公開できます +- Beta prerelease タグは `beta` にのみ公開できます +- `OpenClaw NPM Release` では、完全なコミット SHA 入力は + `preflight_only=true` の場合にのみ許可されます +- `OpenClaw Release Checks` と `Full Release Validation` は常に + validation-only です +- 実際の publish path は、preflight 中に使用したものと同じ `npm_dist_tag` を使用する必要があります。 + ワークフローは、publish が続行される前にそのメタデータを検証します -## Stable npm リリース手順 +## stable npm リリース手順 stable npm リリースを切る場合: -1. `preflight_only=true` で `OpenClaw NPM Release` を実行します - - タグが存在する前は、プリフライトワークフローの検証専用ドライランとして、現在の完全なワークフローブランチコミット SHA を使用できます -2. 通常の beta-first フローでは `npm_dist_tag=beta` を選択し、意図的に直接 stable 公開を行いたい場合にのみ `latest` を選択します -3. 1 つの手動ワークフローから通常 CI に加えてライブプロンプトキャッシュ、Docker、QA Lab、Matrix、Telegram カバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全なコミット SHA で `Full Release Validation` を実行します -4. 意図的に決定的な通常テストグラフだけが必要な場合は、代わりにリリース ref で手動の `CI` ワークフローを実行します -5. 成功した `preflight_run_id` を保存します -6. 同じ `tag`、同じ `npm_dist_tag`、保存した `preflight_run_id` を指定して、`preflight_only=false` で `OpenClaw NPM Release` を再度実行します -7. リリースが `beta` に着地した場合は、非公開の `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` ワークフローを使用して、その stable バージョンを `beta` から `latest` に昇格します -8. リリースが意図的に `latest` に直接公開され、`beta` もすぐに同じ stable ビルドを追従すべき場合は、同じ非公開ワークフローを使用して両方の dist-tag を stable バージョンに向けるか、そのスケジュールされた自己修復同期によって後で `beta` が移動するようにします +1. `preflight_only=true` で `OpenClaw NPM Release` を実行する + - タグが存在する前は、preflight ワークフローの検証専用ドライランに、 + 現在の完全なワークフローブランチのコミット SHA を使用できる +2. 通常の beta-first フローでは `npm_dist_tag=beta` を選び、意図的に直接 stable 公開したい場合にのみ + `latest` を選ぶ +3. 1 つの手動ワークフローから通常の CI に加えて live prompt cache、Docker、QA Lab、 + Matrix、Telegram のカバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全な + コミット SHA で `Full Release Validation` を実行する +4. 決定的な通常のテストグラフだけが意図的に必要な場合は、代わりにリリース ref で + 手動の `CI` ワークフローを実行する +5. 成功した `preflight_run_id` を保存する +6. `preflight_only=false`、同じ + `tag`、同じ `npm_dist_tag`、保存した `preflight_run_id` で `OpenClaw NPM Release` を再度実行する +7. リリースが `beta` に landed した場合は、private の + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + ワークフローを使用して、その stable バージョンを `beta` から `latest` に昇格する +8. リリースが意図的に `latest` へ直接公開され、`beta` も同じ stable build をすぐに追従すべき場合は、 + 同じ private ワークフローを使用して両方の dist-tag が stable バージョンを指すようにするか、スケジュールされた + 自己修復同期で後から `beta` を移動させる -dist-tag の変更は、引き続き `NPM_TOKEN` が必要なため、セキュリティ上の理由で非公開リポジトリにあります。一方、公開リポジトリは OIDC のみの公開を維持します。 +dist-tag の変更は、引き続き `NPM_TOKEN` が必要なためセキュリティ上 private repo にあり、 +public repo は OIDC のみの公開を維持する。 -これにより、直接公開パスと beta-first 昇格パスの両方が文書化され、オペレーターに見える状態になります。 +これにより、直接公開パスと beta-first 昇格パスの両方が文書化され、operator から見える状態になる。 -メンテナーがローカルの npm 認証にフォールバックする必要がある場合は、1Password -CLI (`op`) コマンドは専用の tmux セッション内でのみ実行してください。メインエージェントシェルから `op` -を直接呼び出さないでください。tmux 内に閉じ込めることで、プロンプト、 -アラート、OTP 処理が観測可能になり、ホストアラートの繰り返しを防げます。 +maintainer が local npm authentication にフォールバックする必要がある場合は、1Password CLI (`op`) コマンドを必ず専用の tmux セッション内でのみ実行する。main agent shell から `op` を直接呼び出してはならない。tmux 内に保つことで、プロンプト、アラート、OTP 処理を観測可能にし、繰り返し発生するホストアラートを防げる。 ## 公開リファレンス @@ -314,10 +530,10 @@ CLI (`op`) コマンドは専用の tmux セッション内でのみ実行して - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -メンテナーは実際のランブックとして、非公開のリリースドキュメント +maintainer は、実際の runbook には private release docs の [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -を使用します。 +を使用する。 ## 関連 -- [リリースチャンネル](/ja-JP/install/development-channels) +- [リリースチャネル](/ja-JP/install/development-channels) diff --git a/docs/ja-JP/reference/full-release-validation.md b/docs/ja-JP/reference/full-release-validation.md new file mode 100644 index 000000000..2287914f4 --- /dev/null +++ b/docs/ja-JP/reference/full-release-validation.md @@ -0,0 +1,147 @@ +--- +read_when: + - 完全リリース検証の実行または再実行 + - stable と full のリリース検証プロファイルの比較 + - リリース検証ステージの失敗をデバッグする +summary: 完全なリリース検証のステージ、子ワークフロー、リリースプロファイル、再実行ハンドル、証跡 +title: 完全なリリース検証 +x-i18n: + generated_at: "2026-05-01T05:03:22Z" + model: gpt-5.5 + provider: openai + source_hash: dcbfafd744437c160c09a9c508a639781549193669b300e5249023f9f5dd4afe + source_path: reference/full-release-validation.md + workflow: 16 +--- + +`Full Release Validation` はリリースの包括ワークフローです。プレリリースの検証のための単一の手動エントリーポイントですが、ほとんどの処理は子ワークフローで行われるため、失敗したボックスはリリース全体を最初からやり直さずに再実行できます。 + +通常は `main` のような信頼できるワークフロー ref から実行し、リリースブランチ、タグ、または完全なコミット SHA を `ref` として渡します。 + +```bash +gh workflow run full-release-validation.yml \ + --ref main \ + -f ref=release/YYYY.M.D \ + -f provider=openai \ + -f mode=both \ + -f release_profile=stable +``` + +子ワークフローは、ハーネスには信頼できるワークフロー ref を使用し、テスト対象の候補には入力 `ref` を使用します。これにより、古いリリースブランチやタグを検証する場合でも、新しい検証ロジックを利用できます。 + +## トップレベルステージ + +| ステージ | 詳細 | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ターゲット解決 | **ジョブ:** `Resolve target ref`
**子ワークフロー:** なし
**証明内容:** リリースブランチ、タグ、または完全なコミット SHA を解決し、選択された入力を記録します。
**再実行:** これが失敗した場合は包括ワークフローを再実行します。 | +| Vitest と通常 CI | **ジョブ:** `Run normal full CI`
**子ワークフロー:** `CI`
**証明内容:** Linux Node レーン、バンドル済み Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Control UI i18n、包括ワークフロー経由の Android を含む、ターゲット ref に対する手動のフル CI グラフ。
**再実行:** `rerun_group=ci`。 | +| Plugin プレリリース | **ジョブ:** `Run plugin prerelease validation`
**子ワークフロー:** `Plugin Prerelease`
**証明内容:** リリース専用の Plugin 静的チェック、エージェント型 Plugin カバレッジ、完全な拡張バッチシャード、Plugin プレリリース Docker レーン。
**再実行:** `rerun_group=plugin-prerelease`。 | +| リリースチェック | **ジョブ:** `Run release/live/Docker/QA validation`
**子ワークフロー:** `OpenClaw Release Checks`
**証明内容:** インストールスモーク、クロス OS パッケージチェック、live/E2E スイート、Docker リリースパスチャンク、Package Acceptance、QA Lab パリティ、live Matrix、live Telegram。
**再実行:** `rerun_group=release-checks` またはより狭い release-checks ハンドル。 | +| 公開後 Telegram | **ジョブ:** `Run post-publish Telegram E2E`
**子ワークフロー:** `NPM Telegram Beta E2E`
**証明内容:** `npm_telegram_package_spec` が設定されている場合の、任意の公開済みパッケージ Telegram 検証。
**再実行:** `rerun_group=npm-telegram`。 | +| 包括ワークフロー検証 | **ジョブ:** `Verify full validation`
**子ワークフロー:** なし
**証明内容:** 記録された子実行の結論を再チェックし、子ワークフローから最も遅いジョブの表を追記します。
**再実行:** 失敗した子を再実行してグリーンにした後、このジョブのみを再実行します。 | + +`ref=main` かつ `rerun_group=all` の場合、新しい包括ワークフローが古いものを置き換えます。親がキャンセルされると、そのモニターはすでにディスパッチした子ワークフローをすべてキャンセルします。リリースブランチとタグの検証実行は、デフォルトでは互いにキャンセルしません。 + +## リリースチェックのステージ + +`OpenClaw Release Checks` は最大の子ワークフローです。ターゲットを一度解決し、パッケージまたは Docker 向けステージで必要な場合に共有の `release-package-under-test` アーティファクトを準備します。 + +| ステージ | 詳細 | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| リリースターゲット | **ジョブ:** `Resolve target ref`
**バッキングワークフロー:** なし
**テスト:** 選択された ref、任意の期待 SHA、プロファイル、再実行グループ、絞り込まれた live スイートフィルター。
**再実行:** `rerun_group=release-checks`。 | +| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`
**バッキングワークフロー:** なし
**テスト:** 候補 tarball を 1 つパックまたは解決し、下流のパッケージ向けチェック用に `release-package-under-test` をアップロードします。
**再実行:** 影響を受けるパッケージ、クロス OS、または live/E2E グループ。 | +| インストールスモーク | **ジョブ:** `Run install smoke`
**バッキングワークフロー:** `Install Smoke`
**テスト:** ルート Dockerfile スモークイメージ再利用、QR パッケージインストール、ルートと Gateway の Docker スモーク、インストーラー Docker テスト、Bun グローバルインストールの image-provider スモーク、高速なバンドル済み Plugin Docker E2E を含む完全なインストールパス。
**再実行:** `rerun_group=install-smoke`。 | +| クロス OS | **ジョブ:** `cross_os_release_checks`
**バッキングワークフロー:** `OpenClaw Cross-OS Release Checks (Reusable)`
**テスト:** 選択されたプロバイダーとモードについて、候補 tarball とベースラインパッケージを使用した Linux、Windows、macOS 上の新規インストールおよびアップグレードレーン。
**再実行:** `rerun_group=cross-os`。 | +| リポジトリと live E2E | **ジョブ:** `Run repo/live E2E validation`
**バッキングワークフロー:** `OpenClaw Live And E2E Checks (Reusable)`
**テスト:** リポジトリ E2E、live キャッシュ、OpenAI websocket ストリーミング、ネイティブ live プロバイダーと Plugin シャード、`release_profile` によって選択される Docker ベースの live モデル/バックエンド/Gateway ハーネス。
**再実行:** `rerun_group=live-e2e`、任意で `live_suite_filter` を指定。 | +| Docker リリースパス | **ジョブ:** `Run Docker release-path validation`
**バッキングワークフロー:** `OpenClaw Live And E2E Checks (Reusable)`
**テスト:** 共有パッケージアーティファクトに対するリリースパス Docker チャンク。
**再実行:** `rerun_group=live-e2e`。 | +| Package Acceptance | **ジョブ:** `Run package acceptance`
**バッキングワークフロー:** `Package Acceptance`
**テスト:** アーティファクトネイティブのバンドル済みチャネル依存関係互換性、オフライン Plugin パッケージフィクスチャ、同じ tarball に対する mock-OpenAI Telegram パッケージ受け入れ。
**再実行:** `rerun_group=package`。 | +| QA パリティ | **ジョブ:** `Run QA Lab parity lane` および `Run QA Lab parity report`
**バッキングワークフロー:** 直接ジョブ
**テスト:** 候補とベースラインのエージェント型パリティパック、その後のパリティレポート。
**再実行:** `rerun_group=qa-parity` または `rerun_group=qa`。 | +| QA live Matrix | **ジョブ:** `Run QA Lab live Matrix lane`
**バッキングワークフロー:** 直接ジョブ
**テスト:** `qa-live-shared` 環境での高速 live Matrix QA プロファイル。
**再実行:** `rerun_group=qa-live` または `rerun_group=qa`。 | +| QA live Telegram | **ジョブ:** `Run QA Lab live Telegram lane`
**バッキングワークフロー:** 直接ジョブ
**テスト:** Convex CI 認証情報リースを使った live Telegram QA。
**再実行:** `rerun_group=qa-live` または `rerun_group=qa`。 | +| リリース検証 | **ジョブ:** `Verify release checks`
**バッキングワークフロー:** なし
**テスト:** 選択された再実行グループに必要なリリースチェックジョブ。
**再実行:** 絞り込まれた子ジョブが通過した後に再実行します。 | + +## Docker リリースパスチャンク + +Docker リリースパスステージは、`live_suite_filter` が空の場合にこれらのチャンクを実行します。 + +| チャンク | カバレッジ | +| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| `core` | Core Docker リリースパスのスモークレーン。 | +| `package-update-openai` | OpenAI パッケージのインストールと更新動作。 | +| `package-update-anthropic` | Anthropic パッケージのインストールと更新動作。 | +| `package-update-core` | プロバイダー中立のパッケージと更新動作。 | +| `plugins-runtime-plugins` | Plugin 動作を実行する Plugin ランタイムレーン。 | +| `plugins-runtime-services` | サービスベースの Plugin ランタイムレーン。要求された場合は OpenWebUI を含みます。 | +| `plugins-runtime-install-a` から `plugins-runtime-install-h` | 並列リリース検証のために分割された Plugin インストール/ランタイムバッチ。 | +| `bundled-channels-core` | バンドル済みチャネルの Docker 動作。 | +| `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` | バンドル済みチャネルの更新動作。 | +| `bundled-channels-contracts` | Docker リリースパス内のバンドル済みチャネル契約チェック。 | + +再利用可能なライブ/E2E ワークフローで、失敗した Docker レーンが 1 つだけの場合は、対象を絞った `docker_lanes=` を使用します。リリース成果物には、利用可能な場合、パッケージ成果物とイメージ再利用入力を含むレーンごとの再実行コマンドが含まれます。 + +## リリースプロファイル + +`release_profile` は、リリースチェック内のライブ/プロバイダーの範囲のみを制御します。通常のフル CI、Plugin Prerelease、インストールスモーク、パッケージ受け入れ、QA Lab、または Docker リリースパスのチャンクは削除しません。 + +| プロファイル | 想定用途 | 含まれるライブ/プロバイダーのカバレッジ | +| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `minimum` | 最速のリリースクリティカルなスモーク。 | OpenAI/コアのライブパス、OpenAI 向け Docker ライブモデル、ネイティブ Gateway コア、ネイティブ OpenAI Gateway プロファイル、ネイティブ OpenAI plugin、および Docker ライブ Gateway OpenAI。 | +| `stable` | デフォルトのリリース承認プロファイル。 | `minimum` に加えて、Anthropic、Google、MiniMax、バックエンド、ネイティブライブテストハーネス、Docker ライブ CLI バックエンド、Docker ACP バインド、Docker Codex ハーネス、および OpenCode Go スモークシャード。 | +| `full` | 広範な助言的スイープ。 | `stable` に加えて、助言的プロバイダー、plugin ライブシャード、およびメディアライブシャード。 | + +## `full` のみの追加項目 + +これらのスイートは `stable` ではスキップされ、`full` に含まれます。 + +| 領域 | `full` のみのカバレッジ | +| -------------------------------- | ------------------------------------------------------------------------------- | +| Docker ライブモデル | OpenCode Go、OpenRouter、xAI、Z.ai、および Fireworks。 | +| Docker ライブ Gateway | DeepSeek、Fireworks、OpenCode Go、OpenRouter、xAI、および Z.ai の助言的シャード。 | +| ネイティブ Gateway プロバイダープロファイル | Fireworks、DeepSeek、完全な OpenCode Go モデルシャード、OpenRouter、xAI、および Z.ai。 | +| ネイティブ plugin ライブシャード | Plugins A-K、L-N、O-Z other、Moonshot、および xAI。 | +| ネイティブメディアライブシャード | Audio、Google music、MiniMax music、および video groups A-D。 | + +`stable` には `native-live-src-gateway-profiles-opencode-go-smoke` が含まれます。`full` は代わりに、より広範な OpenCode Go モデルシャードを使用します。 + +## 対象を絞った再実行 + +関連しないリリースボックスの繰り返しを避けるには、`rerun_group` を使用します。 + +| ハンドル | 範囲 | +| ------------------- | ------------------------------------------------- | +| `all` | すべての Full Release Validation ステージ。 | +| `ci` | 手動フル CI 子のみ。 | +| `plugin-prerelease` | Plugin Prerelease 子のみ。 | +| `release-checks` | すべての OpenClaw Release Checks ステージ。 | +| `install-smoke` | リリースチェックまでの Install Smoke。 | +| `cross-os` | Cross-OS リリースチェック。 | +| `live-e2e` | リポジトリ/ライブ E2E および Docker リリースパス検証。 | +| `package` | Package Acceptance。 | +| `qa` | QA パリティと QA ライブレーン。 | +| `qa-parity` | QA パリティレーンとレポートのみ。 | +| `qa-live` | QA ライブ Matrix と Telegram のみ。 | +| `npm-telegram` | 公開後の任意の Telegram E2E のみ。 | + +1 つのライブスイートが失敗した場合は、`rerun_group=live-e2e` とともに `live_suite_filter` を使用します。有効なフィルター ID は再利用可能なライブ/E2E ワークフローで定義されており、`docker-live-models`、`live-gateway-docker`、`live-gateway-anthropic-docker`、`live-gateway-google-docker`、`live-gateway-minimax-docker`、`live-gateway-advisory-docker`、`live-cli-backend-docker`、`live-acp-bind-docker`、および `live-codex-harness-docker` が含まれます。 + +## 保持する証跡 + +リリースレベルの索引として `Full Release Validation` のサマリーを保持します。これは子 run ID にリンクし、最も遅いジョブの表を含みます。失敗時は、まず子ワークフローを確認し、その後で上記の最小の一致するハンドルを再実行します。 + +有用な成果物: + +- `OpenClaw Release Checks` からの `release-package-under-test` +- `.artifacts/docker-tests/` 以下の Docker リリースパス成果物 +- Package Acceptance の `package-under-test` と Docker 受け入れ成果物 +- 各 OS とスイートの Cross-OS リリースチェック成果物 +- QA パリティ、Matrix、および Telegram の成果物 + +## ワークフローファイル + +- `.github/workflows/full-release-validation.yml` +- `.github/workflows/openclaw-release-checks.yml` +- `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` +- `.github/workflows/plugin-prerelease.yml` +- `.github/workflows/install-smoke.yml` +- `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- `.github/workflows/package-acceptance.yml` diff --git a/docs/ja-JP/reference/test.md b/docs/ja-JP/reference/test.md index 9795f9778..3a4bf8a03 100644 --- a/docs/ja-JP/reference/test.md +++ b/docs/ja-JP/reference/test.md @@ -1,59 +1,60 @@ --- read_when: - テストの実行または修正 -summary: ローカルでテストを実行する方法（vitest）と force/coverage モードを使うタイミング +summary: ローカルでテストを実行する方法 (vitest) と、force/coverage モードを使うタイミング title: テスト x-i18n: - generated_at: "2026-04-30T18:38:26Z" + generated_at: "2026-05-01T05:03:12Z" model: gpt-5.5 provider: openai - source_hash: 131f2bad3b2806d28394213cec38d632d106ddbf8ff04d06345ab8046fb8bcf2 + source_hash: 4d50f77fdb8dcf7153c59d1bd9f3d61d745ba17ea846eb0610d0f064ad0d1761 source_path: reference/test.md workflow: 16 --- -- 完全なテストキット（スイート、ライブ、Docker）: [テスト](/ja-JP/help/testing) +- 包括的なテストキット (スイート、ライブ、Docker): [テスト](/ja-JP/help/testing) -- `pnpm test:force`: デフォルトの制御ポートを保持している残存 Gateway プロセスを強制終了し、隔離された Gateway ポートで Vitest スイート全体を実行して、サーバーテストが実行中のインスタンスと衝突しないようにします。以前の Gateway 実行でポート 18789 が占有されたままになった場合に使用します。 -- `pnpm test:coverage`: V8 カバレッジでユニットスイートを実行します（`vitest.unit.config.ts` 経由）。これは読み込まれたファイルのユニットカバレッジゲートであり、リポジトリ全体の全ファイルカバレッジではありません。しきい値は lines/functions/statements が 70%、branches が 55% です。`coverage.all` が false のため、このゲートは、すべての分割レーンのソースファイルを未カバーとして扱うのではなく、ユニットカバレッジスイートに読み込まれたファイルを測定します。 +- `pnpm test:force`: 既定の制御ポートを保持している残留 Gateway プロセスを強制終了し、隔離された Gateway ポートで Vitest スイート全体を実行するため、サーバーテストが実行中のインスタンスと衝突しません。以前の Gateway 実行によってポート 18789 が使用中のまま残った場合に使用します。 +- `pnpm test:coverage`: V8 カバレッジ付きでユニットスイートを実行します（`vitest.unit.config.ts` 経由）。これは読み込まれたファイルのユニットカバレッジゲートであり、リポジトリ全体の全ファイルカバレッジではありません。しきい値は行/関数/ステートメントが 70%、ブランチが 55% です。`coverage.all` が false のため、このゲートはすべての分割レーンのソースファイルを未カバーとして扱うのではなく、ユニットカバレッジスイートによって読み込まれたファイルを測定します。 - `pnpm test:coverage:changed`: `origin/main` 以降に変更されたファイルのみを対象にユニットカバレッジを実行します。 -- `pnpm test:changed`: 低コストなスマート変更テスト実行です。直接編集されたテスト、隣接する `*.test.ts` ファイル、明示的なソースマッピング、ローカル import グラフから精密なターゲットを実行します。広範な config/package 変更は、精密なテストにマップされない限りスキップされます。 -- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: 明示的な広範囲の変更テスト実行です。テストハーネス/config/package の編集で、Vitest のより広い changed-test 挙動にフォールバックすべき場合に使用します。 -- `pnpm changed:lanes`: `origin/main` との差分によってトリガーされるアーキテクチャレーンを表示します。 -- `pnpm check:changed`: `origin/main` との差分に対してスマート変更チェックゲートを実行します。影響を受けるアーキテクチャレーンの typecheck、lint、guard コマンドを実行しますが、Vitest テストは実行しません。テストの証明には `pnpm test:changed` または明示的な `pnpm test ` を使用します。 -- `pnpm test`: 明示的なファイル/ディレクトリターゲットをスコープ付き Vitest レーンへルーティングします。ターゲットなしの実行では固定シャードグループを使用し、ローカル並列実行のためにリーフ config へ展開します。extension グループは、巨大な 1 つのルートプロジェクトプロセスではなく、常に extension ごとのシャード config に展開されます。 -- テストラッパーの実行は、短い `[test] passed|failed|skipped ... in ...` サマリーで終わります。Vitest 自身の duration 行はシャードごとの詳細として残ります。 -- 共有 OpenClaw テスト状態: テストが隔離された `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、config fixture、workspace、agent dir、auth-profile store を必要とする場合は、Vitest から `src/test-utils/openclaw-test-state.ts` を使用します。 -- プロセス E2E ヘルパー: Vitest のプロセスレベル E2E テストで、実行中の Gateway、CLI env、ログキャプチャ、クリーンアップを 1 か所で必要とする場合は `test/helpers/openclaw-test-instance.ts` を使用します。 -- Docker/Bash E2E ヘルパー: `scripts/lib/docker-e2e-image.sh` を source するレーンは、`docker_e2e_test_state_shell_b64