diff --git a/docs/ja-JP/automation/tasks.md b/docs/ja-JP/automation/tasks.md index 5a98f0768..0042661b5 100644 --- a/docs/ja-JP/automation/tasks.md +++ b/docs/ja-JP/automation/tasks.md @@ -2,43 +2,43 @@ read_when: - 進行中または最近完了したバックグラウンド作業を確認する - デタッチされたエージェント実行の配信失敗をデバッグする - - バックグラウンド実行がセッション、Cron、Heartbeat とどう関係するかを理解する + - バックグラウンド実行とセッション、Cron、Heartbeat の関係を理解する sidebarTitle: Background tasks -summary: ACP 実行、サブエージェント、分離された Cron ジョブ、CLI 操作のバックグラウンドタスク追跡 +summary: ACP 実行、サブエージェント、隔離された Cron ジョブ、CLI 操作のバックグラウンドタスク追跡 title: バックグラウンドタスク x-i18n: - generated_at: "2026-05-01T05:00:32Z" + generated_at: "2026-05-05T01:44:24Z" model: gpt-5.5 provider: openai - source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4 + source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991 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 エージェントコマンドは作成します。 -## 要約 +## TL;DR -- タスクはスケジューラーではなく**レコード**です。cron と Heartbeat は作業を_いつ_実行するかを決め、タスクは_何が起きたか_を追跡します。 -- ACP、サブエージェント、すべての cron ジョブ、CLI 操作はタスクを作成します。Heartbeat ターンは作成しません。 -- 各タスクは `queued → running → terminal`（succeeded、failed、timed_out、cancelled、または lost）を進みます。 -- cron タスクは、cron ランタイムがまだジョブを所有している間はライブのままです。 - メモリ内のランタイム状態がなくなった場合、タスクのメンテナンスはタスクを lost としてマークする前に、まず永続化された cron - 実行履歴を確認します。 -- 完了はプッシュ駆動です: 分離された作業は完了時に直接通知するか、リクエスターのセッション/Heartbeat を起こせるため、ステータスのポーリングループは通常適切な形ではありません。 -- 分離された cron 実行とサブエージェント完了は、最終クリーンアップの帳簿処理の前に、子セッションで追跡されているブラウザータブ/プロセスをベストエフォートでクリーンアップします。 -- 分離された cron 配信は、子孫サブエージェントの作業がまだ排出中の間は古くなった暫定的な親返信を抑制し、配信前に子孫の最終出力が届いた場合はそれを優先します。 -- 完了通知はチャンネルに直接配信されるか、次の Heartbeat 用にキューに入れられます。 +- タスクはスケジューラーではなく**記録**です。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 日間保持され、その後自動的に削除されます。 @@ -56,7 +56,7 @@ x-i18n: ``` - + ```bash # Show details for a specific task (by ID, run ID, or session key) openclaw tasks show @@ -83,7 +83,7 @@ x-i18n: ``` - + ```bash # Inspect TaskFlow state openclaw tasks flow list @@ -95,33 +95,33 @@ x-i18n: ## タスクを作成するもの -| ソース | ランタイムタイプ | タスクレコードが作成されるタイミング | デフォルト通知ポリシー | +| ソース | ランタイム種別 | タスクレコードが作成されるタイミング | デフォルトの通知ポリシー | | ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| 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` | +| ACP バックグラウンド実行 | `acp` | 子 ACP セッションを起動する | `done_only` | +| サブエージェントオーケストレーション | `subagent` | `sessions_spawn` でサブエージェントを起動する | `done_only` | +| Cron ジョブ (すべての種別) | `cron` | すべての Cron 実行 (メインセッションと分離実行) | `silent` | +| CLI 操作 | `cli` | Gateway 経由で実行される `openclaw agent` コマンド | `silent` | +| エージェントメディアジョブ | `cli` | セッションに支えられた `music_generate`/`video_generate` 実行 | `silent` | - - メインセッションの cron タスクは、デフォルトで `silent` 通知ポリシーを使用します。追跡用のレコードは作成しますが、通知は生成しません。分離された cron タスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より見えやすくなります。 + + メインセッションの Cron タスクはデフォルトで `silent` 通知ポリシーを使用します。追跡用のレコードは作成しますが、通知は生成しません。分離された Cron タスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より見えやすくなります。 - セッション backed の `music_generate` と `video_generate` 実行も `silent` 通知ポリシーを使用します。それでもタスクレコードは作成されますが、完了は内部 wake として元のエージェントセッションに戻され、エージェントがフォローアップメッセージを書き、完成したメディアを自分で添付できるようにします。`tools.media.asyncCompletion.directSend` を有効にすると、非同期の `video_generate` 完了はまず直接チャンネル配信を試せます。非同期の `music_generate` 完了はリクエスターセッションの wake パスに留まります。 + セッションに支えられた `music_generate` と `video_generate` 実行も `silent` 通知ポリシーを使用します。それでもタスクレコードは作成されますが、完了は内部 wake として元のエージェントセッションに戻されるため、エージェントがフォローアップメッセージを書き、完成したメディアを自分で添付できます。グループ/チャネルの完了は通常の可視返信ポリシーに従うため、ソース配信が必要な場合、エージェントはメッセージツールを使用します。 - セッション backed の `video_generate` タスクがまだアクティブな間、このツールはガードレールとしても機能します。同じセッションで `video_generate` が繰り返し呼び出されると、2 つ目の同時生成を開始する代わりに、アクティブなタスクのステータスを返します。エージェント側から明示的に進行状況/ステータスを参照したい場合は `action: "status"` を使用してください。 + セッションに支えられた `video_generate` タスクがまだアクティブな間、そのツールはガードレールとしても機能します。同じセッション内で繰り返された `video_generate` 呼び出しは、2 つ目の同時生成を開始する代わりに、アクティブなタスクステータスを返します。エージェント側から明示的な進捗/ステータス検索が必要な場合は、`action: "status"` を使用してください。 - - Heartbeat ターン（メインセッション）。[Heartbeat](/ja-JP/gateway/heartbeat)を参照 + - Heartbeat ターン — メインセッション。[Heartbeat](/ja-JP/gateway/heartbeat)を参照 - 通常の対話型チャットターン - 直接の `/command` 応答 -## タスクのライフサイクル +## タスクライフサイクル ```mermaid stateDiagram-v2 @@ -135,57 +135,57 @@ 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` など、より強い終端状態をすでに記録している場合、後から成功シグナルが来てもその終端ステータスは引き下げられません。 +エージェント実行の完了は、アクティブなタスクレコードに対して権威があります。成功した切り離し実行は `succeeded` として確定し、通常の実行エラーは `failed` として確定し、タイムアウトまたは中止の結果は `timed_out` として確定します。オペレーターがすでにタスクをキャンセルしている場合、またはランタイムがすでに `failed`、`timed_out`、`lost` などのより強い終端状態を記録している場合、後からの成功シグナルがその終端ステータスを格下げすることはありません。 -`lost` はランタイムを考慮します: +`lost` はランタイムを認識します: -- ACP タスク: 裏付けとなる ACP 子セッションのメタデータが消えました。 +- ACP タスク: 裏付けとなる ACP 子セッションメタデータが消えました。 - サブエージェントタスク: 裏付けとなる子セッションがターゲットエージェントストアから消えました。 -- cron タスク: cron ランタイムがそのジョブをアクティブとして追跡しなくなり、永続化された - cron 実行履歴にもその実行の終端結果が示されていません。オフライン CLI - 監査は、自身の空のインプロセス cron ランタイム状態を権威として扱いません。 -- CLI タスク: 分離された子セッションタスクは子セッションを使用します。チャット backed の +- Cron タスク: Cron ランタイムがそのジョブをアクティブとして追跡しなくなり、永続化された + Cron 実行履歴にもその実行の終端結果が表示されません。オフライン CLI + 監査は、自身の空のインプロセス Cron ランタイム状態を権威として扱いません。 +- CLI タスク: 分離された子セッションタスクは子セッションを使用します。チャットに支えられた CLI タスクは代わりにライブ実行コンテキストを使用するため、残存する - チャンネル/グループ/ダイレクトセッション行がそれらを生存状態に保つことはありません。Gateway backed の - `openclaw agent` 実行も実行結果から確定されるため、完了済みの実行がスイーパーにより `lost` とマークされるまでアクティブなまま残ることはありません。 + チャネル/グループ/ダイレクトセッション行がそれらを生存状態に保つことはありません。Gateway に支えられた + `openclaw agent` 実行も実行結果から確定するため、完了した実行がスイーパーに `lost` とマークされるまでアクティブのまま残ることはありません。 ## 配信と通知 -タスクが終端状態に達すると、OpenClaw が通知します。配信パスは 2 つあります: +タスクが終端状態に達すると、OpenClaw が通知します。配信経路は 2 つあります: -**直接配信** — タスクにチャンネルターゲット（`requesterOrigin`）がある場合、完了メッセージはそのチャンネル（Telegram、Discord、Slack など）に直接送られます。サブエージェント完了では、OpenClaw は利用可能な場合に紐付いたスレッド/トピックのルーティングも保持し、直接配信を諦める前に、リクエスターセッションに保存されたルート（`lastChannel` / `lastTo` / `lastAccountId`）から欠けている `to` / アカウントを補完できます。 +**直接配信** — タスクにチャネルターゲット (`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`（デフォルト） | 終端状態（succeeded、failed など）のみ — **これがデフォルトです** | -| `state_changes` | すべての状態遷移と進行状況更新 | -| `silent` | 何も配信されません | +| `done_only` (デフォルト) | 終端状態 (succeeded、failed など) のみ — **これがデフォルトです** | +| `state_changes` | すべての状態遷移と進捗更新 | +| `silent` | 何も配信しない | -タスクの実行中にポリシーを変更します: +タスク実行中にポリシーを変更します: ```bash openclaw tasks notify state_changes @@ -199,7 +199,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - 出力列: タスク ID、種類、ステータス、配信、実行 ID、子セッション、要約。 + 出力列: タスク ID、種類、ステータス、配信、実行 ID、子セッション、概要。 @@ -207,7 +207,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - 参照トークンには、タスク ID、実行 ID、またはセッションキーを指定できます。タイミング、配信状態、エラー、終端要約を含む完全なレコードを表示します。 + 検索トークンには、タスク ID、実行 ID、またはセッションキーを指定できます。タイミング、配信状態、エラー、終端概要を含む完全なレコードを表示します。 @@ -215,7 +215,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - ACP とサブエージェントタスクでは、これにより子セッションが終了されます。CLI で追跡されるタスクでは、キャンセルはタスクレジストリに記録されます（別個の子ランタイムハンドルはありません）。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。 + ACP とサブエージェントタスクでは、これは子セッションを終了します。CLI 追跡タスクでは、キャンセルはタスクレジストリに記録されます (個別の子ランタイムハンドルはありません)。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。 @@ -228,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` まで警告になり、その後エラーになる | + | `stale_queued` | warn | 10分を超えてキューに入っている | + | `stale_running` | error | 30分を超えて実行中 | + | `lost` | warn/error | ランタイムに裏付けられたタスク所有権が消失した。保持中の lost タスクは `cleanupAfter` までは警告、その後はエラーになる | | `delivery_failed` | warn | 配信に失敗し、通知ポリシーが `silent` ではない | - | `missing_cleanup` | warn | クリーンアップタイムスタンプがない終端タスク | + | `missing_cleanup` | warn | クリーンアップタイムスタンプのない終端タスク | | `inconsistent_timestamps` | warn | タイムライン違反（たとえば開始前に終了している） | - + ```bash openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` - タスクと Task Flow 状態の照合、クリーンアップのスタンプ付け、枝刈りをプレビューまたは適用するために使います。 + これを使って、タスクと Task Flow 状態の照合、クリーンアップスタンプ付け、枝刈りをプレビューまたは適用します。 照合はランタイムを認識します。 - ACP/サブエージェントタスクは、裏付けとなる子セッションを確認します。 - - 子セッションに再起動復旧の墓標があるサブエージェントタスクは、復旧可能な裏付けセッションとして扱われるのではなく、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 の配信は、必要に応じて子孫サブエージェントのフォローアップを待機し、古くなった親の確認応答テキストを通知する代わりに抑制します。 - - サブエージェントの完了配信では、最新の表示可能な assistant テキストが優先されます。それが空の場合は、サニタイズ済みの最新 tool/toolResult テキストにフォールバックし、タイムアウトのみのツール呼び出し実行は短い部分進捗サマリーにまとめられることがあります。終端失敗実行では、キャプチャされた返信テキストを再生せずに失敗ステータスを通知します。 - - クリーンアップ失敗は、実際のタスク結果を覆い隠しません。 + - サブエージェント完了では、通知クリーンアップを続行する前に、子セッションで追跡されているブラウザータブ/プロセスをベストエフォートで閉じます。 + - 分離 cron 完了では、実行が完全に終了する前に、cron セッションで追跡されているブラウザータブ/プロセスをベストエフォートで閉じます。 + - 分離 cron 配信は、必要に応じて子孫サブエージェントのフォローアップを待ち、古い親確認テキストを通知する代わりに抑制します。 + - サブエージェント完了配信は、最新の表示可能なアシスタントテキストを優先します。それが空の場合は、サニタイズされた最新の tool/toolResult テキストにフォールバックし、タイムアウトのみのツール呼び出し実行は短い部分進捗サマリーに折りたたまれることがあります。終端の失敗実行は、取得された返信テキストを再生せずに失敗ステータスを通知します。 + - クリーンアップ失敗が実際のタスク結果を隠すことはありません。 @@ -271,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` 別の内訳 -`/status` と `session_status` ツールはいずれも、クリーンアップを認識したタスクスナップショットを使います。アクティブなタスクが優先され、古くなった完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは現在重要なものに集中できます。 +`/status` と `session_status` ツールはどちらも、クリーンアップを認識するタスクスナップショットを使用します。アクティブなタスクが優先され、古い完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは現在重要なことに集中できます。 ## ストレージとメンテナンス ### タスクの保存場所 -タスクレコードは次の SQLite に永続化されます。 +タスクレコードは SQLite の次の場所に永続化されます。 ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` レジストリは Gateway 起動時にメモリへ読み込まれ、再起動をまたいだ耐久性のために書き込みを SQLite に同期します。 -Gateway は、SQLite のデフォルト自動チェックポイントしきい値に加えて、定期的およびシャットダウン時の `TRUNCATE` チェックポイントを使うことで、SQLite の先行書き込みログを一定範囲に保ちます。 +Gateway は、SQLite のデフォルトの自動チェックポイントしきい値に加え、定期的およびシャットダウン時の `TRUNCATE` チェックポイントを使って、SQLite の先行書き込みログを制限します。 ### 自動メンテナンス -スイーパーは **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 つのフローは、そのライフタイムを通じて、管理同期モードまたはミラー同期モードを使って複数のタスクを調整できます。個別のタスクレコードを調べるには `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` は、作業を行うエージェント実行にリンクします。エージェントのライフサイクルイベント（開始、終了、エラー）はタスクステータスを自動的に更新します。ライフサイクルを手動で管理する必要はありません。 @@ -370,5 +370,5 @@ Gateway は、SQLite のデフォルト自動チェックポイントしきい - [自動化とタスク](/ja-JP/automation) — すべての自動化メカニズムの概要 - [CLI: タスク](/ja-JP/cli/tasks) — CLI コマンドリファレンス - [Heartbeat](/ja-JP/gateway/heartbeat) — 定期的なメインセッションターン -- [スケジュール済みタスク](/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/slack.md b/docs/ja-JP/channels/slack.md index 649f70b1e..ca250c25d 100644 --- a/docs/ja-JP/channels/slack.md +++ b/docs/ja-JP/channels/slack.md @@ -1,18 +1,18 @@ --- read_when: - - Slack の設定、または Slack のソケット/HTTP モードのデバッグ + - Slack の設定または Slack ソケット/HTTP モードのデバッグ summary: Slack のセットアップと実行時の動作（ソケットモード + HTTP リクエスト URL） title: Slack x-i18n: - generated_at: "2026-05-04T07:02:57Z" + generated_at: "2026-05-05T01:44:08Z" model: gpt-5.5 provider: openai - source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 + source_hash: 9a8e1cbfd3d99bfc24d79b56ee762d1ab399402391b241ff40698249b0828008 source_path: channels/slack.md workflow: 16 --- -DM とチャンネル向けに Slack アプリ連携経由で本番運用可能です。デフォルトのモードは Socket Mode です。HTTP Request URLs もサポートされています。 +Slack アプリ連携により、DM とチャンネルで本番運用可能です。デフォルトのモードは Socket Mode です。HTTP Request URL もサポートされています。 @@ -26,24 +26,181 @@ DM とチャンネル向けに Slack アプリ連携経由で本番運用可能 +## Socket Mode または HTTP Request URL の選択 + +どちらのトランスポートも本番運用可能で、メッセージング、スラッシュコマンド、App Home、インタラクティブ機能について機能同等です。機能ではなく、デプロイ形態で選択してください。 + +| 懸念事項 | Socket Mode (デフォルト) | HTTP Request URL | +| ---------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | +| 公開 Gateway URL | 不要 | 必須 (DNS、TLS、リバースプロキシまたはトンネル) | +| アウトバウンドネットワーク | `wss-primary.slack.com` へのアウトバウンド WSS に到達できる必要があります | アウトバウンド WS なし。インバウンド HTTPS のみ | +| 必要なトークン | Bot token (`xoxb-...`) + `connections:write` 付き App-Level Token (`xapp-...`) | Bot token (`xoxb-...`) + Signing Secret | +| 開発用ノートPC / ファイアウォール背後 | そのまま動作します | 公開トンネル (ngrok、Cloudflare Tunnel、Tailscale Funnel) またはステージング Gateway が必要 | +| 水平スケーリング | アプリ、ホストごとに Socket Mode セッションは 1 つ。複数の Gateway には個別の Slack アプリが必要 | ステートレスな POST ハンドラー。複数の Gateway レプリカがロードバランサー背後で 1 つのアプリを共有できます | +| 1 つの Gateway で複数アカウント | サポートされています。各アカウントが自身の WS を開きます | サポートされています。登録が衝突しないよう、各アカウントに一意の `webhookPath` (デフォルトは `/slack/events`) が必要 | +| スラッシュコマンドのトランスポート | WS 接続経由で配信されます。`slash_commands[].url` は無視されます | Slack が `slash_commands[].url` に POST します。コマンドをディスパッチするにはこのフィールドが必須です | +| リクエスト署名 | 使用されません (認証は App-Level Token) | Slack がすべてのリクエストに署名します。OpenClaw は `signingSecret` で検証します | +| 接続切断時の復旧 | Slack SDK が自動再接続します。gateway の pong タイムアウトのトランスポート調整が適用されます | 切断される永続接続はありません。リトライは Slack からのリクエストごとに行われます | + + + 単一 Gateway ホスト、開発用ノートPC、`*.slack.com` へのアウトバウンド到達はできるがインバウンド HTTPS を受けられないオンプレミスネットワークでは、**Socket Mode を選択**してください。 + +ロードバランサー背後で複数の Gateway レプリカを実行する場合、アウトバウンド WSS がブロックされているがインバウンド HTTPS が許可されている場合、または既にリバースプロキシで Slack Webhook を終端している場合は、**HTTP Request URL を選択**してください。 + + ## クイックセットアップ - - Slack アプリ設定で **[Create New App](https://api.slack.com/apps/new)** ボタンを押します。 + + [api.slack.com/apps](https://api.slack.com/apps/new) を開き、**Create New App** → **From a manifest** → ワークスペースを選択 → 以下のマニフェストのいずれかを貼り付け → **Next** → **Create** の順に進みます。 - - **from a manifest** を選択し、アプリ用のワークスペースを選択します - - 下の [マニフェスト例](#manifest-and-scope-checklist) を貼り付け、作成に進みます - - `connections:write` を指定して **App-Level Token** (`xapp-...`) を生成します - - アプリをインストールし、表示された **Bot Token** (`xoxb-...`) をコピーします + + +```json 推奨 +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + +```json 最小構成 +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + } + } +} +``` + + + + + **推奨** は、同梱されている Slack plugin の全機能セットに対応します: App Home、スラッシュコマンド、ファイル、リアクション、ピン、グループ DM、絵文字/ユーザーグループの読み取り。ワークスペースポリシーでスコープが制限される場合は、**最小構成** を選択してください。DM、チャンネル/グループ履歴、メンション、スラッシュコマンドは対象ですが、ファイル、リアクション、ピン、グループ DM (`mpim:*`)、`emoji:read`、`usergroups:read` は含まれません。スコープごとの根拠と、追加のスラッシュコマンドなどの追加オプションについては、[マニフェストとスコープのチェックリスト](#manifest-and-scope-checklist) を参照してください。 + + + Slack がアプリを作成したら: + + - **Basic Information → App-Level Tokens → Generate Token and Scopes**: `connections:write` を追加し、保存して、`xapp-...` の値をコピーします。 + - **Install App → Install to Workspace**: `xoxb-...` Bot User OAuth Token をコピーします。 - + - 推奨の SecretRef 設定: + 推奨される SecretRef 設定: ```bash export SLACK_APP_TOKEN=xapp-... @@ -64,7 +221,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - env フォールバック (デフォルトアカウントのみ): + 環境変数フォールバック (デフォルトアカウントのみ): ```bash SLACK_APP_TOKEN=xapp-... @@ -73,7 +230,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,21 +241,172 @@ openclaw gateway - + - - Slack アプリ設定で **[Create New App](https://api.slack.com/apps/new)** ボタンを押します。 + + [api.slack.com/apps](https://api.slack.com/apps/new) を開き、**Create New App** → **From a manifest** → ワークスペースを選択 → 以下のマニフェストのいずれかを貼り付け → `https://gateway-host.example.com/slack/events` を公開 Gateway URL に置き換え → **Next** → **Create** の順に進みます。 - - **from a manifest** を選択し、アプリ用のワークスペースを選択します - - [マニフェスト例](#manifest-and-scope-checklist) を貼り付け、作成前に URL を更新します - - リクエスト検証用の **Signing Secret** を保存します - - アプリをインストールし、表示された **Bot Token** (`xoxb-...`) をコピーします + + +```json 推奨 +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + +```json 最小構成 +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + + + + + **推奨** は同梱 Slack plugin の全機能セットに一致します。**最小構成** は制限の厳しいワークスペース向けに、ファイル、リアクション、ピン、グループ DM (`mpim:*`)、`emoji:read`、`usergroups:read` を除外します。スコープごとの根拠は [マニフェストとスコープのチェックリスト](#manifest-and-scope-checklist) を参照してください。 + + + + 3 つの URL フィールド (`slash_commands[].url`、`event_subscriptions.request_url`、`interactivity.request_url` / `message_menu_options_url`) はすべて同じ OpenClaw エンドポイントを指します。Slack のマニフェストスキーマではそれぞれ別名が必要ですが、OpenClaw はペイロード種別でルーティングするため、単一の `webhookPath` (デフォルトは `/slack/events`) で十分です。`slash_commands[].url` のないスラッシュコマンドは、HTTP モードでは通知なく no-op になります。 + + + Slack がアプリを作成した後: + + - **Basic Information → App Credentials**: リクエスト検証用の **Signing Secret** をコピーします。 + - **Install App → Install to Workspace**: `xoxb-...` Bot User OAuth Token をコピーします。 - 推奨の SecretRef 設定: + 推奨される SecretRef 設定: ```bash export SLACK_BOT_TOKEN=xoxb-... @@ -121,9 +429,9 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - 複数アカウントの HTTP には一意の webhook パスを使用する + 複数アカウントの HTTP には一意の Webhook パスを使用する - 登録が衝突しないように、各アカウントに個別の `webhookPath` (デフォルト `/slack/events`) を指定します。 + 登録が衝突しないように、各アカウントに個別の `webhookPath` (デフォルトは `/slack/events`) を指定します。 @@ -140,9 +448,9 @@ openclaw gateway -## Socket Mode トランスポート調整 +## Socket Mode トランスポートのチューニング -OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアントの pong タイムアウトを 15 秒に設定します。ワークスペースまたはホスト固有の調整が必要な場合にのみ、トランスポート設定を上書きしてください。 +OpenClaw は、Socket Mode ではデフォルトで Slack SDK クライアントの pong タイムアウトを 15 秒に設定します。ワークスペースまたはホスト固有のチューニングが必要な場合にのみ、トランスポート設定を上書きしてください: ```json5 { @@ -159,11 +467,11 @@ OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアント } ``` -これは、Slack websocket の pong/server-ping タイムアウトをログに記録する Socket Mode ワークスペース、または既知のイベントループ枯渇があるホストでのみ使用してください。`clientPingTimeout` は SDK がクライアント ping を送信した後の pong 待機時間です。`serverPingTimeout` は Slack サーバー ping の待機時間です。アプリメッセージとイベントは、トランスポートの生存性シグナルではなく、アプリケーション状態のままです。 +これは、Slack websocket の pong/server-ping タイムアウトをログに記録する Socket Mode ワークスペース、またはイベントループの枯渇が既知のホストで実行する場合にのみ使用してください。`clientPingTimeout` は SDK がクライアント ping を送信した後の pong 待機時間です。`serverPingTimeout` は Slack サーバー ping の待機時間です。アプリメッセージとイベントはアプリケーション状態であり、トランスポートの生存性シグナルではありません。 ## マニフェストとスコープのチェックリスト -基本の Slack アプリマニフェストは Socket Mode と HTTP Request URLs で同じです。異なるのは `settings` ブロック (およびスラッシュコマンドの `url`) だけです。 +基本の Slack アプリマニフェストは、Socket Mode と HTTP Request URLs で同じです。異なるのは `settings` ブロック (およびスラッシュコマンドの `url`) のみです。 基本マニフェスト (Socket Mode デフォルト): @@ -240,7 +548,7 @@ OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアント } ``` -**HTTP Request URLs モード** では、`settings` を HTTP バリアントに置き換え、各スラッシュコマンドに `url` を追加します。公開 URL が必要です。 +**HTTP Request URLs モード** では、`settings` を HTTP 版に置き換え、各スラッシュコマンドに `url` を追加します。公開 URL が必要です: ```json { @@ -286,17 +594,17 @@ OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアント 上記のデフォルトを拡張する別の機能を公開します。 -デフォルトのマニフェストでは、Slack App Home の **Home** タブが有効になり、`app_home_opened` をサブスクライブします。ワークスペースメンバーが Home タブを開くと、OpenClaw は `views.publish` で安全なデフォルトの Home ビューを公開します。会話ペイロードや非公開設定は含まれません。**Messages** タブは Slack DM 用に有効なままです。 +デフォルトのマニフェストでは、Slack App Home の **Home** タブを有効にし、`app_home_opened` をサブスクライブします。ワークスペースメンバーが Home タブを開くと、OpenClaw は `views.publish` で安全なデフォルトの Home ビューを公開します。会話ペイロードやプライベート設定は含まれません。**Messages** タブは Slack DM 用に引き続き有効です。 - ニュアンスのある単一の設定済みコマンドの代わりに、複数の [ネイティブスラッシュコマンド](#commands-and-slash-behavior) を使用できます。 + 単一の設定済みコマンドの代わりに、複数の [ネイティブスラッシュコマンド](#commands-and-slash-behavior) を細かな違いを踏まえて使用できます: - - `/status` コマンドは予約されているため、`/status` の代わりに `/agentstatus` を使用します。 - - 一度に利用可能にできるスラッシュコマンドは 25 個以下です。 + - `/status` コマンドは予約済みのため、`/status` の代わりに `/agentstatus` を使用します。 + - 一度に利用可能にできるスラッシュコマンドは 25 個までです。 - 既存の `features.slash_commands` セクションを、[利用可能なコマンド](/ja-JP/tools/slash-commands#command-list) のサブセットに置き換えます。 + 既存の `features.slash_commands` セクションを、[利用可能なコマンド](/ja-JP/tools/slash-commands#command-list) のサブセットに置き換えます: @@ -423,7 +731,7 @@ OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアント - 上の Socket Mode と同じ `slash_commands` リストを使用し、すべてのエントリに `"url": "https://gateway-host.example.com/slack/events"` を追加します。例: + 上記の Socket Mode と同じ `slash_commands` リストを使用し、すべてのエントリに `"url": "https://gateway-host.example.com/slack/events"` を追加します。例: ```json { @@ -443,14 +751,14 @@ OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアント } ``` - リスト内のすべてのコマンドでその `url` 値を繰り返します。 + リスト内のすべてのコマンドで、その `url` 値を繰り返します。 - - 送信メッセージでデフォルトの Slack アプリ ID ではなく、アクティブなエージェント ID（カスタムユーザー名とアイコン）を使いたい場合は、`chat:write.customize` bot スコープを追加します。 + + 送信メッセージでデフォルトの Slack アプリ ID ではなく、アクティブなエージェント ID（カスタムユーザー名とアイコン）を使いたい場合は、`chat:write.customize` ボットスコープを追加します。 絵文字アイコンを使う場合、Slack は `:emoji_name:` 構文を想定します。 @@ -477,30 +785,30 @@ OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアント 文字列または SecretRef オブジェクトを受け付けます。 - 設定内のトークンは env フォールバックを上書きします。 - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env フォールバックはデフォルトアカウントにのみ適用されます。 -- `userToken`（`xoxp-...`）は設定専用（env フォールバックなし）で、デフォルトでは読み取り専用動作（`userTokenReadOnly: true`）です。 +- `userToken`（`xoxp-...`）は設定専用（env フォールバックなし）で、デフォルトでは読み取り専用の動作（`userTokenReadOnly: true`）になります。 ステータススナップショットの動作: -- Slack アカウント検査は、認証情報ごとの `*Source` および `*Status` +- Slack アカウント検査は、認証情報ごとの `*Source` と `*Status` フィールド（`botToken`、`appToken`、`signingSecret`、`userToken`）を追跡します。 - ステータスは `available`、`configured_unavailable`、または `missing` です。 - `configured_unavailable` は、アカウントが SecretRef - または別の非インラインのシークレットソースを通じて設定されているものの、現在のコマンド/runtime パスでは + または別の非インラインのシークレットソースを通じて設定されているものの、現在のコマンド/ランタイムパスでは 実際の値を解決できなかったことを意味します。 -- HTTP モードでは `signingSecretStatus` が含まれます。Socket Mode では - 必須のペアは `botTokenStatus` + `appTokenStatus` です。 +- HTTP モードでは `signingSecretStatus` が含まれます。Socket Mode では、 + 必須の組み合わせは `botTokenStatus` + `appTokenStatus` です。 -actions/directory の読み取りでは、設定されている場合に user token が優先されることがあります。書き込みでは bot token が引き続き優先されます。user-token 書き込みは、`userTokenReadOnly: false` で bot token が利用できない場合にのみ許可されます。 +アクション/ディレクトリ読み取りでは、設定されている場合にユーザートークンを優先できます。書き込みでは、ボットトークンが引き続き優先されます。ユーザートークンによる書き込みは、`userTokenReadOnly: false` で、かつボットトークンが利用できない場合にのみ許可されます。 ## アクションとゲート Slack アクションは `channels.slack.actions.*` で制御されます。 -現在の Slack ツールで利用可能なアクショングループ: +現在の Slack ツールで利用できるアクショングループ: -| グループ | デフォルト | +| グループ | デフォルト | | ---------- | ------- | | messages | 有効 | | reactions | 有効 | @@ -508,7 +816,7 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 | memberInfo | 有効 | | emojiList | 有効 | -現在の Slack メッセージアクションには、`send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info`、`emoji-list` があります。`download-file` はインバウンドファイルプレースホルダーに表示される Slack ファイル ID を受け付け、画像の場合は画像プレビューを、それ以外のファイルタイプの場合はローカルファイルメタデータを返します。 +現在の Slack メッセージアクションには、`send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info`、`emoji-list` が含まれます。`download-file` は受信ファイルプレースホルダーに表示される Slack ファイル ID を受け付け、画像の場合は画像プレビューを返し、その他のファイルタイプの場合はローカルファイルメタデータを返します。 ## アクセス制御とルーティング @@ -523,45 +831,45 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 DM フラグ: - - `dm.enabled`（デフォルトは true） + - `dm.enabled`（デフォルト true） - `channels.slack.allowFrom` - `dm.allowFrom`（レガシー） - `dm.groupEnabled`（グループ DM のデフォルトは false） - `dm.groupChannels`（任意の MPIM 許可リスト） - マルチアカウントの優先順位: + 複数アカウントの優先順位: - `channels.slack.accounts.default.allowFrom` は `default` アカウントにのみ適用されます。 - 名前付きアカウントは、自身の `allowFrom` が未設定の場合に `channels.slack.allowFrom` を継承します。 - 名前付きアカウントは `channels.slack.accounts.default.allowFrom` を継承しません。 - レガシーの `channels.slack.dm.policy` と `channels.slack.dm.allowFrom` は互換性のため引き続き読み取られます。`openclaw doctor --fix` は、アクセスを変更せずに実行できる場合、それらを `dmPolicy` と `allowFrom` に移行します。 + レガシーの `channels.slack.dm.policy` と `channels.slack.dm.allowFrom` は互換性のために引き続き読み取られます。`openclaw doctor --fix` は、アクセスを変更せずに実行できる場合、それらを `dmPolicy` と `allowFrom` に移行します。 DM でのペアリングには `openclaw pairing approve slack ` を使います。 - `channels.slack.groupPolicy` はチャンネルの処理を制御します。 + `channels.slack.groupPolicy` はチャンネル処理を制御します。 - `open` - `allowlist` - `disabled` - チャンネル許可リストは `channels.slack.channels` の下にあり、設定キーとして**安定した Slack チャンネル ID**（例: `C12345678`）を使う必要があります。 + チャンネル許可リストは `channels.slack.channels` 配下にあり、設定キーとして**安定した Slack チャンネル ID**（例: `C12345678`）を使う必要があります。 - Runtime 注記: `channels.slack` が完全に存在しない場合（env のみのセットアップ）、runtime は `groupPolicy="allowlist"` にフォールバックし、警告をログに記録します（`channels.defaults.groupPolicy` が設定されている場合でも）。 + ランタイム上の注意: `channels.slack` が完全に存在しない場合（env のみのセットアップ）、ランタイムは `groupPolicy="allowlist"` にフォールバックし、警告をログに記録します（`channels.defaults.groupPolicy` が設定されている場合でも同様です）。 名前/ID 解決: - - チャンネル許可リストのエントリと DM 許可リストのエントリは、トークンアクセスで可能な場合、起動時に解決されます - - 解決できないチャンネル名エントリは設定されたまま保持されますが、デフォルトではルーティングで無視されます - - インバウンド認可とチャンネルルーティングはデフォルトで ID 優先です。直接のユーザー名/slug マッチングには `channels.slack.dangerouslyAllowNameMatching: true` が必要です + - チャンネル許可リスト項目と DM 許可リスト項目は、トークンアクセスで許可される場合、起動時に解決されます + - 解決されなかったチャンネル名の項目は設定どおり保持されますが、デフォルトではルーティングで無視されます + - 受信認可とチャンネルルーティングはデフォルトで ID 優先です。直接のユーザー名/slug マッチングには `channels.slack.dangerouslyAllowNameMatching: true` が必要です - 名前ベースのキー（`#channel-name` または `channel-name`）は `groupPolicy: "allowlist"` では一致しません。チャンネル検索はデフォルトで ID 優先のため、名前ベースのキーでは正常にルーティングされることはなく、そのチャンネル内のすべてのメッセージは静かにブロックされます。これは、ルーティングにチャンネルキーが不要で、名前ベースのキーが機能しているように見える `groupPolicy: "open"` とは異なります。 + 名前ベースのキー（`#channel-name` または `channel-name`）は `groupPolicy: "allowlist"` では**一致しません**。チャンネル検索はデフォルトで ID 優先のため、名前ベースのキーでは正常にルーティングされることはなく、そのチャンネル内のすべてのメッセージが暗黙にブロックされます。これは `groupPolicy: "open"` とは異なります。`groupPolicy: "open"` ではルーティングにチャンネルキーは不要で、名前ベースのキーが動作しているように見えます。 - 常に Slack チャンネル ID をキーとして使ってください。見つけるには、Slack でチャンネルを右クリック → **リンクをコピー** — URL の末尾に ID（`C...`）が表示されます。 + キーには常に Slack チャンネル ID を使ってください。見つけるには、Slack でチャンネルを右クリック → **リンクをコピー** — URL の末尾に ID（`C...`）が表示されます。 正しい例: @@ -578,7 +886,7 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 } ``` - 誤り（`groupPolicy: "allowlist"` の下で暗黙的にブロックされます）: + 誤り（`groupPolicy: "allowlist"` では黙ってブロックされる）: ```json5 { @@ -597,43 +905,43 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 - チャンネルメッセージはデフォルトでメンションによって制限されます。 + チャンネルメッセージはデフォルトでメンションゲートされます。 - メンションのソース: + メンション元: - 明示的なアプリメンション（`<@botId>`） - - ボットユーザーがそのユーザーグループのメンバーである場合の Slack ユーザーグループメンション（``）。`usergroups:read` が必要です + - ボットユーザーがそのユーザーグループのメンバーである場合の Slack ユーザーグループメンション（``）。`usergroups:read` が必要 - メンション正規表現パターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは `messages.groupChat.mentionPatterns`） - - ボットへの返信スレッドの暗黙的な動作（`thread.requireExplicitMention` が `true` の場合は無効） + - 暗黙的なボットへの返信スレッド動作（`thread.requireExplicitMention` が `true` の場合は無効） チャンネルごとの制御（`channels.slack.channels.`。名前は起動時の解決または `dangerouslyAllowNameMatching` 経由のみ）: - `requireMention` - - `users`（allowlist） + - `users`（許可リスト） - `allowBots` - `skills` - `systemPrompt` - - `tools`、`toolsBySender` - - `toolsBySender` のキー形式: `id:`、`e164:`、`username:`、`name:`、または `"*"` ワイルドカード - （レガシーのプレフィックスなしキーは引き続き `id:` のみにマップされます） + - `tools`, `toolsBySender` + - `toolsBySender` キー形式: `id:`, `e164:`, `username:`, `name:`, または `"*"` ワイルドカード + （レガシーの接頭辞なしキーは引き続き `id:` のみにマップされる） - `allowBots` はチャンネルとプライベートチャンネルでは保守的です。ボットが作成したルームメッセージは、送信元ボットがそのルームの `users` allowlist に明示的に列挙されている場合、または `channels.slack.allowFrom` からの明示的な Slack オーナー ID が少なくとも 1 つ現在ルームメンバーである場合にのみ受け付けられます。ワイルドカードと表示名のオーナーエントリは、オーナーの存在条件を満たしません。オーナーの存在確認には Slack `conversations.members` を使用します。アプリにルーム種別に対応する読み取りスコープ（パブリックチャンネルは `channels:read`、プライベートチャンネルは `groups:read`）があることを確認してください。メンバー検索に失敗した場合、OpenClaw はボットが作成したルームメッセージを破棄します。 + `allowBots` はチャンネルとプライベートチャンネルでは保守的です。ボットが作成したルームメッセージは、送信元ボットがそのルームの `users` 許可リストに明示的に列挙されている場合、または `channels.slack.allowFrom` の明示的な Slack オーナー ID が少なくとも 1 つ現在ルームメンバーである場合にのみ受け入れられます。ワイルドカードと表示名のオーナーエントリは、オーナー存在を満たしません。オーナー存在には Slack `conversations.members` が使われます。アプリにルーム種別に対応する読み取りスコープ（公開チャンネルは `channels:read`、プライベートチャンネルは `groups:read`）があることを確認してください。メンバー検索に失敗した場合、OpenClaw はボットが作成したルームメッセージを破棄します。 ## スレッド、セッション、返信タグ -- DM は `direct` として、チャンネルは `channel` として、MPIM は `group` としてルーティングされます。 -- Slack ルートバインディングは、生のピア ID に加えて `channel:C12345678`、`user:U12345678`、`<@U12345678>` などの Slack ターゲット形式を受け付けます。 +- DM は `direct` としてルーティングされ、チャンネルは `channel` として、MPIM は `group` としてルーティングされます。 +- Slack ルートバインディングは、生のピア ID に加えて、`channel:C12345678`、`user:U12345678`、`<@U12345678>` などの Slack ターゲット形式を受け入れます。 - デフォルトの `session.dmScope=main` では、Slack DM はエージェントのメインセッションに集約されます。 - チャンネルセッション: `agent::slack:channel:`。 -- スレッド返信では、該当する場合にスレッドセッション接尾辞（`:thread:`）を作成できます。 -- `channels.slack.thread.historyScope` のデフォルトは `thread` です。`thread.inheritParent` のデフォルトは `false` です。 -- `channels.slack.thread.initialHistoryLimit` は、新しいスレッドセッションの開始時に取得される既存スレッドメッセージ数を制御します（デフォルトは `20`。無効にするには `0` を設定）。 -- `channels.slack.thread.requireExplicitMention`（デフォルト `false`）: `true` の場合、暗黙的なスレッドメンションを抑制し、ボットがすでにスレッドに参加していても、スレッド内の明示的な `@bot` メンションにのみボットが応答します。これがない場合、ボットが参加したスレッド内の返信は `requireMention` の制限をバイパスします。 +- 該当する場合、スレッド返信はスレッドセッションサフィックス（`:thread:`）を作成できます。 +- `channels.slack.thread.historyScope` のデフォルトは `thread`、`thread.inheritParent` のデフォルトは `false` です。 +- `channels.slack.thread.initialHistoryLimit` は、新しいスレッドセッションの開始時に取得する既存スレッドメッセージ数を制御します（デフォルトは `20`。無効にするには `0` を設定）。 +- `channels.slack.thread.requireExplicitMention`（デフォルト `false`）: `true` の場合、暗黙的なスレッドメンションを抑制し、ボットがすでにスレッドに参加していても、スレッド内の明示的な `@bot` メンションにのみ応答します。これがない場合、ボットが参加したスレッド内の返信は `requireMention` ゲートをバイパスします。 -返信スレッドの制御: +返信スレッド制御: - `channels.slack.replyToMode`: `off|first|all|batched`（デフォルト `off`） - `channels.slack.replyToModeByChatType`: `direct|group|channel` ごと @@ -645,37 +953,37 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 - `[[reply_to:]]` -`replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含む Slack の**すべての**返信スレッド化を無効にします。これは、明示的なタグが `"off"` モードでも引き続き尊重される Telegram とは異なります。Slack スレッドはチャンネルからメッセージを非表示にしますが、Telegram の返信はインラインで表示されたままです。 +`replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含む Slack の**すべて**の返信スレッド化を無効にします。これは、`"off"` モードでも明示的なタグが引き続き尊重される Telegram とは異なります。Slack スレッドはメッセージをチャンネルから隠しますが、Telegram の返信はインラインで表示されたままです。 ## Ack リアクション -`ackReaction` は、OpenClaw が受信メッセージを処理している間に確認用絵文字を送信します。 +`ackReaction` は、OpenClaw が受信メッセージを処理している間、確認絵文字を送信します。 解決順序: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- エージェント ID 絵文字フォールバック（`agents.list[].identity.emoji`、なければ「👀」） +- エージェント ID 絵文字フォールバック（`agents.list[].identity.emoji`、それ以外は "👀"） -注: +メモ: -- Slack はショートコード（例: `"eyes"`）を想定しています。 -- Slack アカウントまたはグローバルでリアクションを無効にするには `""` を使用します。 +- Slack はショートコード（例: `"eyes"`）を想定します。 +- Slack アカウントまたはグローバルでリアクションを無効にするには `""` を使います。 ## テキストストリーミング -`channels.slack.streaming` はライブプレビューの動作を制御します: +`channels.slack.streaming` はライブプレビュー動作を制御します: - `off`: ライブプレビューストリーミングを無効にします。 -- `partial`（デフォルト）: プレビューテキストを最新の部分出力で置き換えます。 -- `block`: 分割されたプレビュー更新を追加します。 -- `progress`: 生成中は進行状況テキストを表示し、その後で最終テキストを送信します。 -- `streaming.preview.toolProgress`: 下書きプレビューが有効な場合、ツール/進行状況の更新を同じ編集済みプレビューメッセージにルーティングします（デフォルト: `true`）。個別のツール/進行状況メッセージを保持するには `false` に設定します。 -- `streaming.preview.commandText` / `streaming.progress.commandText`: 生のコマンド/実行テキストを隠しつつ、コンパクトなツール進行状況行を保持するには `status` に設定します（デフォルト: `raw`）。 +- `partial`（デフォルト）: プレビューテキストを最新の部分出力に置き換えます。 +- `block`: チャンク化されたプレビュー更新を追加します。 +- `progress`: 生成中に進捗ステータステキストを表示し、その後に最終テキストを送信します。 +- `streaming.preview.toolProgress`: ドラフトプレビューがアクティブな場合、ツール/進捗更新を同じ編集済みプレビューメッセージにルーティングします（デフォルト: `true`）。個別のツール/進捗メッセージを維持するには `false` を設定します。 +- `streaming.preview.commandText` / `streaming.progress.commandText`: 生のコマンド/exec テキストを隠しながらコンパクトなツール進捗行を維持するには `status` に設定します（デフォルト: `raw`）。 -コンパクトな進行状況行を保持しながら、生のコマンド/実行テキストを非表示にします: +コンパクトな進捗行を維持しながら、生のコマンド/exec テキストを隠す: ```json { @@ -696,13 +1004,13 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 `channels.slack.streaming.nativeTransport` は、`channels.slack.streaming.mode` が `partial` の場合の Slack ネイティブテキストストリーミングを制御します（デフォルト: `true`）。 - ネイティブテキストストリーミングと Slack アシスタントスレッドステータスを表示するには、返信スレッドが利用可能である必要があります。スレッド選択は引き続き `replyToMode` に従います。 -- ネイティブストリーミングを利用できない場合、または返信スレッドが存在しない場合でも、チャンネル、グループチャット、トップレベル DM ルートは通常の下書きプレビューを使用できます。 -- トップレベルの Slack DM はデフォルトでスレッド外に留まるため、Slack のスレッド形式のネイティブストリーム/ステータスプレビューは表示されません。代わりに OpenClaw が DM に下書きプレビューを投稿して編集します。 -- メディアと非テキストペイロードは通常配信にフォールバックします。 -- メディア/エラーの最終結果は保留中のプレビュー編集をキャンセルします。対象となるテキスト/ブロックの最終結果は、プレビューをその場で編集できる場合にのみフラッシュされます。 -- 返信途中でストリーミングが失敗した場合、OpenClaw は残りのペイロードを通常配信にフォールバックします。 +- チャンネル、グループチャット、トップレベル DM ルートは、ネイティブストリーミングが利用できない場合や返信スレッドが存在しない場合でも、通常のドラフトプレビューを引き続き使用できます。 +- トップレベルの Slack DM はデフォルトでスレッド外のままになるため、Slack のスレッド形式のネイティブストリーム/ステータスプレビューは表示されません。代わりに OpenClaw が DM にドラフトプレビューを投稿して編集します。 +- メディアと非テキストペイロードは通常の配信にフォールバックします。 +- メディア/エラーの最終出力は保留中のプレビュー編集をキャンセルします。対象となるテキスト/block の最終出力は、プレビューをその場で編集できる場合にのみフラッシュされます。 +- ストリーミングが返信の途中で失敗した場合、OpenClaw は残りのペイロードについて通常の配信にフォールバックします。 -Slack ネイティブテキストストリーミングの代わりに下書きプレビューを使用します: +Slack ネイティブテキストストリーミングの代わりにドラフトプレビューを使う: ```json5 { @@ -721,56 +1029,56 @@ Slack ネイティブテキストストリーミングの代わりに下書き - `channels.slack.streamMode`（`replace | status_final | append`）は `channels.slack.streaming.mode` に自動移行されます。 - boolean `channels.slack.streaming` は `channels.slack.streaming.mode` と `channels.slack.streaming.nativeTransport` に自動移行されます。 -- レガシーの `channels.slack.nativeStreaming` は `channels.slack.streaming.nativeTransport` に自動移行されます。 +- レガシー `channels.slack.nativeStreaming` は `channels.slack.streaming.nativeTransport` に自動移行されます。 -## タイピングリアクションのフォールバック +## 入力中リアクションフォールバック -`typingReaction` は、OpenClaw が返信を処理している間、受信した Slack メッセージに一時的なリアクションを追加し、実行が完了するとそれを削除します。これはデフォルトの「is typing...」ステータスインジケーターを使うスレッド返信以外で最も役立ちます。 +`typingReaction` は、OpenClaw が返信を処理している間、受信した Slack メッセージに一時的なリアクションを追加し、実行が完了すると削除します。これは、デフォルトの「入力中...」ステータスインジケーターを使うスレッド返信以外で特に有用です。 解決順序: - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` -注記: +注意: -- Slack はショートコードを想定します（例: `"hourglass_flowing_sand"`）。 -- リアクションはベストエフォートであり、返信または失敗パスの完了後に自動的なクリーンアップが試行されます。 +- Slack はショートコードを想定しています（例: `"hourglass_flowing_sand"`）。 +- リアクションはベストエフォートで、返信または失敗パスの完了後にクリーンアップが自動的に試行されます。 ## メディア、チャンク化、配信 - - Slack ファイル添付は、Slack がホストするプライベート URL（トークン認証付きリクエストフロー）からダウンロードされ、取得が成功しサイズ制限が許す場合にメディアストアへ書き込まれます。ファイルプレースホルダーには Slack の `fileId` が含まれるため、エージェントは `download-file` で元のファイルを取得できます。 + + Slack ファイル添付は、Slack がホストするプライベート URL（トークン認証済みリクエストフロー）からダウンロードされ、取得に成功しサイズ制限が許す場合にメディアストアへ書き込まれます。ファイルプレースホルダーには Slack の `fileId` が含まれるため、エージェントは `download-file` で元のファイルを取得できます。 - ダウンロードには、制限付きのアイドルタイムアウトと合計タイムアウトが使われます。Slack ファイル取得が停止または失敗した場合、OpenClaw はメッセージの処理を継続し、ファイルプレースホルダーにフォールバックします。 + ダウンロードには、制限付きのアイドルタイムアウトと合計タイムアウトが使われます。Slack ファイルの取得が停止または失敗した場合でも、OpenClaw はメッセージ処理を続行し、ファイルプレースホルダーへフォールバックします。 - ランタイムの受信サイズ上限は、`channels.slack.mediaMaxMb` で上書きされない限り、デフォルトで `20MB` です。 + 実行時の受信サイズ上限は、`channels.slack.mediaMaxMb` で上書きされない限り、デフォルトで `20MB` です。 - - - テキストチャンクは `channels.slack.textChunkLimit`（デフォルト 4000）を使います + + - テキストチャンクは `channels.slack.textChunkLimit` を使います（デフォルト 4000） - `channels.slack.chunkMode="newline"` は段落優先の分割を有効にします - ファイル送信は Slack アップロード API を使い、スレッド返信（`thread_ts`）を含めることができます - - 送信メディア上限は、設定されている場合は `channels.slack.mediaMaxMb` に従います。それ以外の場合、チャンネル送信はメディアパイプラインの MIME 種別デフォルトを使います + - 送信メディア上限は、設定されている場合は `channels.slack.mediaMaxMb` に従います。それ以外の場合、チャネル送信はメディアパイプラインの MIME 種別デフォルトを使います - - 推奨される明示的な送信先: + + 推奨される明示的なターゲット: - DM には `user:` - - チャンネルには `channel:` + - チャネルには `channel:` - テキスト/ブロックのみの Slack DM はユーザー ID に直接投稿できます。ファイルアップロードとスレッド送信では、具体的な会話 ID が必要なため、まず Slack conversation API で DM を開きます。 + テキスト/ブロックのみの Slack DM はユーザー ID に直接投稿できます。ファイルアップロードとスレッド送信では具体的な会話 ID が必要なため、まず Slack conversation API で DM を開きます。 -## コマンドとスラッシュの動作 +## コマンドとスラッシュ動作 -スラッシュコマンドは、Slack では単一の設定済みコマンドまたは複数のネイティブコマンドとして表示されます。コマンドのデフォルトを変更するには、`channels.slack.slashCommand` を設定します: +スラッシュコマンドは、単一の設定済みコマンドまたは複数のネイティブコマンドとして Slack に表示されます。コマンドのデフォルトを変更するには `channels.slack.slashCommand` を設定します: - `enabled: false` - `name: "openclaw"` @@ -781,32 +1089,32 @@ Slack ネイティブテキストストリーミングの代わりに下書き /openclaw /help ``` -ネイティブコマンドには Slack アプリで [追加のマニフェスト設定](#additional-manifest-settings) が必要で、代わりに `channels.slack.commands.native: true` またはグローバル設定の `commands.native: true` で有効にします。 +ネイティブコマンドには Slack アプリで[追加のマニフェスト設定](#additional-manifest-settings)が必要で、代わりに `channels.slack.commands.native: true`、またはグローバル設定の `commands.native: true` で有効にします。 -- Slack ではネイティブコマンドの自動モードは **オフ** であるため、`commands.native: "auto"` は Slack ネイティブコマンドを有効にしません。 +- Slack ではネイティブコマンドの自動モードは**オフ**のため、`commands.native: "auto"` では Slack ネイティブコマンドは有効になりません。 ```txt /help ``` -ネイティブ引数メニューは、選択されたオプション値をディスパッチする前に確認モーダルを表示する適応型レンダリング戦略を使います: +ネイティブ引数メニューは、選択されたオプション値をディスパッチする前に確認モーダルを表示する適応的なレンダリング戦略を使います: - 最大 5 個のオプション: ボタンブロック - 6〜100 個のオプション: 静的選択メニュー -- 100 個を超えるオプション: インタラクティビティオプションハンドラーが利用可能な場合、非同期オプションフィルタリング付きの外部選択 +- 100 個を超えるオプション: インタラクティビティのオプションハンドラーが利用可能な場合、非同期オプションフィルタリング付きの外部選択 - Slack の制限超過: エンコードされたオプション値はボタンにフォールバックします ```txt /think ``` -スラッシュセッションは `agent::slack:slash:` のような分離キーを使い、`CommandTargetSessionKey` を使って対象会話セッションへコマンド実行を引き続きルーティングします。 +スラッシュセッションは `agent::slack:slash:` のような分離キーを使い、`CommandTargetSessionKey` を使ってコマンド実行を対象の会話セッションへ引き続きルーティングします。 ## インタラクティブ返信 -Slack はエージェント作成のインタラクティブな返信コントロールをレンダリングできますが、この機能はデフォルトで無効です。 +Slack はエージェントが作成したインタラクティブ返信コントロールをレンダリングできますが、この機能はデフォルトで無効です。 -グローバルに有効にします: +グローバルに有効化します: ```json5 { @@ -820,7 +1128,7 @@ Slack はエージェント作成のインタラクティブな返信コント } ``` -または、1 つの Slack アカウントだけで有効にします: +または、1 つの Slack アカウントに対してのみ有効化します: ```json5 { @@ -838,29 +1146,29 @@ Slack はエージェント作成のインタラクティブな返信コント } ``` -有効にすると、エージェントは Slack 専用の返信ディレクティブを出力できます: +有効な場合、エージェントは Slack 専用の返信ディレクティブを出力できます: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -これらのディレクティブは Slack Block Kit にコンパイルされ、クリックまたは選択を既存の Slack interaction イベントパス経由でルーティングします。 +これらのディレクティブは Slack Block Kit にコンパイルされ、クリックまたは選択を既存の Slack インタラクションイベントパス経由で戻します。 -注記: +注意: -- これは Slack 固有の UI です。他のチャンネルは Slack Block Kit ディレクティブを独自のボタンシステムに変換しません。 +- これは Slack 固有の UI です。他のチャネルは Slack Block Kit ディレクティブを独自のボタンシステムに変換しません。 - インタラクティブコールバック値は、エージェントが作成した生の値ではなく、OpenClaw が生成した不透明トークンです。 -- 生成されたインタラクティブブロックが Slack Block Kit の制限を超える場合、OpenClaw は無効な blocks ペイロードを送信する代わりに、元のテキスト返信にフォールバックします。 +- 生成されたインタラクティブブロックが Slack Block Kit の制限を超える場合、OpenClaw は無効なブロックペイロードを送信する代わりに、元のテキスト返信へフォールバックします。 ## Slack での Exec 承認 -Slack は、Web UI やターミナルへのフォールバックの代わりに、インタラクティブボタンとインタラクションを備えたネイティブ承認クライアントとして動作できます。 +Slack は Web UI やターミナルへフォールバックする代わりに、インタラクティブボタンとインタラクションを備えたネイティブ承認クライアントとして動作できます。 -- Exec 承認はネイティブ DM/チャンネルルーティングに `channels.slack.execApprovals.*` を使います。 -- Plugin 承認は、リクエストがすでに Slack に届いていて承認 ID 種別が `plugin:` の場合、同じ Slack ネイティブボタン画面を通じて引き続き解決できます。 +- Exec 承認はネイティブ DM/チャネルルーティングに `channels.slack.execApprovals.*` を使います。 +- Plugin 承認は、リクエストがすでに Slack に届いており承認 ID 種別が `plugin:` の場合、同じ Slack ネイティブボタン面から解決できます。 - 承認者の認可は引き続き強制されます。承認者として識別されたユーザーだけが、Slack 経由でリクエストを承認または拒否できます。 -これは他のチャンネルと同じ共有承認ボタン画面を使います。Slack アプリ設定で `interactivity` が有効な場合、承認プロンプトは会話内に直接 Block Kit ボタンとしてレンダリングされます。 -それらのボタンが存在する場合、それらが主要な承認 UX です。OpenClaw は、ツール結果がチャット承認は利用できない、または手動承認が唯一の経路だと示す場合に限り、手動の `/approve` コマンドを含めるべきです。 +これは他のチャネルと同じ共有承認ボタン面を使います。Slack アプリ設定で `interactivity` が有効になっている場合、承認プロンプトは会話内に直接 Block Kit ボタンとしてレンダリングされます。 +これらのボタンが存在する場合、それらが主要な承認 UX です。OpenClaw は、ツール結果がチャット承認を利用できない、または手動承認が唯一のパスであると示す場合にのみ、手動の `/approve` コマンドを含めるべきです。 設定パス: @@ -869,8 +1177,8 @@ Slack は、Web UI やターミナルへのフォールバックの代わりに - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） - `agentFilter`, `sessionFilter` -Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人の承認者が解決される場合、ネイティブ Exec 承認を自動的に有効にします。Slack をネイティブ承認クライアントとして明示的に無効にするには `enabled: false` を設定します。 -承認者が解決される場合にネイティブ承認を強制的にオンにするには、`enabled: true` を設定します。 +Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人の承認者が解決される場合、ネイティブ Exec 承認を自動的に有効化します。Slack をネイティブ承認クライアントとして明示的に無効化するには `enabled: false` を設定します。 +承認者が解決される場合にネイティブ承認を強制的にオンにするには `enabled: true` を設定します。 明示的な Slack Exec 承認設定がない場合のデフォルト動作: @@ -882,7 +1190,7 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人 } ``` -明示的な Slack ネイティブ設定が必要なのは、承認者を上書きする、フィルターを追加する、または発信元チャットへの配信を選択する場合だけです: +明示的な Slack ネイティブ設定が必要なのは、承認者を上書きする、フィルターを追加する、または発信元チャット配信にオプトインする場合だけです: ```json5 { @@ -898,33 +1206,33 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人 } ``` -共有 `approvals.exec` 転送は別物です。Exec 承認プロンプトを他のチャットまたは明示的な帯域外ターゲットにもルーティングする必要がある場合にだけ使ってください。共有 `approvals.plugin` 転送も別物です。Slack ネイティブボタンは、それらのリクエストがすでに Slack に届いている場合、Plugin 承認を引き続き解決できます。 +共有 `approvals.exec` 転送は別物です。Exec 承認プロンプトを他のチャットまたは明示的な帯域外ターゲットにもルーティングする必要がある場合にのみ使ってください。共有 `approvals.plugin` 転送も別物です。これらのリクエストがすでに Slack に届いている場合、Slack ネイティブボタンは引き続き Plugin 承認を解決できます。 -同じチャットでの `/approve` も、すでにコマンドをサポートする Slack チャンネルと DM で機能します。承認転送モデル全体については [Exec 承認](/ja-JP/tools/exec-approvals) を参照してください。 +同じチャットの `/approve` も、すでにコマンドをサポートしている Slack チャネルと DM で機能します。承認転送モデル全体については、[Exec 承認](/ja-JP/tools/exec-approvals)を参照してください。 -## イベントと運用時の動作 +## イベントと運用動作 - メッセージの編集/削除はシステムイベントにマッピングされます。 -- スレッドブロードキャスト（「Also send to channel」スレッド返信）は通常のユーザーメッセージとして処理されます。 -- リアクションの追加/削除イベントはシステムイベントにマッピングされます。 -- メンバーの参加/退出、チャンネルの作成/名前変更、ピンの追加/削除イベントはシステムイベントにマッピングされます。 -- `configWrites` が有効な場合、`channel_id_changed` はチャンネル設定キーを移行できます。 -- チャンネルのトピック/目的メタデータは信頼できないコンテキストとして扱われ、ルーティングコンテキストに注入されることがあります。 -- スレッド開始メッセージと初期スレッド履歴コンテキストのシードは、該当する場合、設定された送信者許可リストでフィルタリングされます。 +- スレッドブロードキャスト（「チャネルにも送信」スレッド返信）は通常のユーザーメッセージとして処理されます。 +- リアクション追加/削除イベントはシステムイベントにマッピングされます。 +- メンバー参加/退出、チャネル作成/名前変更、ピン追加/削除イベントはシステムイベントにマッピングされます。 +- `configWrites` が有効な場合、`channel_id_changed` はチャネル設定キーを移行できます。 +- チャネルのトピック/目的メタデータは信頼されないコンテキストとして扱われ、ルーティングコンテキストに注入されることがあります。 +- スレッド開始メッセージと初期スレッド履歴コンテキストのシードは、該当する場合、設定済み送信者許可リストでフィルタリングされます。 - ブロックアクションとモーダルインタラクションは、豊富なペイロードフィールドを持つ構造化された `Slack interaction: ...` システムイベントを出力します: - ブロックアクション: 選択値、ラベル、ピッカー値、`workflow_*` メタデータ - - ルーティングされたチャンネルメタデータとフォーム入力を含むモーダル `view_submission` および `view_closed` イベント + - モーダル `view_submission` と `view_closed` イベント。ルーティング済みチャネルメタデータとフォーム入力を含みます ## 設定リファレンス -主なリファレンス: [設定リファレンス - Slack](/ja-JP/gateway/config-channels#slack)。 +主要リファレンス: [設定リファレンス - Slack](/ja-JP/gateway/config-channels#slack)。 - + - モード/認証: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - DM アクセス: `dm.enabled`, `dmPolicy`, `allowFrom`（レガシー: `dm.policy`, `dm.allowFrom`）, `dm.groupEnabled`, `dm.groupChannels` -- 互換性トグル: `dangerouslyAllowNameMatching`（緊急回避用。必要な場合を除きオフのままにする） -- チャンネルアクセス: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` +- 互換性トグル: `dangerouslyAllowNameMatching`（緊急時用。必要な場合を除きオフのままにしてください） +- チャネルアクセス: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - スレッド/履歴: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - 配信: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - 運用/機能: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -934,15 +1242,15 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人 ## トラブルシューティング - + 次の順に確認してください: - `groupPolicy` - - チャンネル許可リスト（`channels.slack.channels`）— **キーはチャンネル ID**（`C12345678`）である必要があり、名前（`#channel-name`）ではありません。チャンネルルーティングはデフォルトで ID 優先のため、`groupPolicy: "allowlist"` では名前ベースのキーは静かに失敗します。ID を見つけるには、Slack でチャンネルを右クリック → **Copy link** — URL 末尾の `C...` 値がチャンネル ID です。 + - チャネル許可リスト（`channels.slack.channels`）— **キーはチャネル ID である必要があります**（`C12345678`）。名前（`#channel-name`）ではありません。チャネルルーティングはデフォルトで ID 優先のため、名前ベースのキーは `groupPolicy: "allowlist"` で静かに失敗します。ID を見つけるには、Slack でチャネルを右クリック → **リンクをコピー** — URL 末尾の `C...` 値がチャネル ID です。 - `requireMention` - - チャンネルごとの `users` 許可リスト + - チャネルごとの `users` 許可リスト - 便利なコマンド: + 有用なコマンド: ```bash openclaw channels status --probe @@ -952,13 +1260,13 @@ openclaw doctor - + 確認してください: - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`（またはレガシー `channels.slack.dm.policy`） - ペアリング承認 / 許可リストエントリ - - Slack Assistant DM イベント: `drop message_changed` に言及する詳細ログは、通常、メッセージメタデータ内に復元可能な人間の送信者がない編集済み Assistant スレッドイベントを Slack が送信したことを意味します + - Slack Assistant DM イベント: `drop message_changed` に言及する詳細ログは、通常、Slack がメッセージメタデータ内に復元可能な人間の送信者がない編集済み Assistant スレッドイベントを送信したことを意味します ```bash openclaw pairing list slack @@ -966,101 +1274,101 @@ openclaw pairing list slack - + Slack アプリ設定で bot + app トークンと Socket Mode の有効化を検証してください。 `openclaw channels status --probe --json` が `botTokenStatus` または - `appTokenStatus: "configured_unavailable"` を示す場合、その Slack アカウントは - 設定されていますが、現在のランタイムが SecretRef に基づく値を解決できませんでした。 + `appTokenStatus: "configured_unavailable"` を表示する場合、その Slack アカウントは + 設定されていますが、現在のランタイムは SecretRef に裏付けられた値を解決できませんでした。 - + 検証してください: - - signing secret + - 署名シークレット - Webhook パス - Slack Request URL（Events + Interactivity + Slash Commands） - - HTTP アカウントごとに一意な `webhookPath` + - HTTP アカウントごとに一意の `webhookPath` - アカウントスナップショットに `signingSecretStatus: "configured_unavailable"` が表示される場合、その HTTP アカウントは設定されていますが、現在のランタイムが SecretRef に基づく signing secret を解決できませんでした。 + アカウントスナップショットに `signingSecretStatus: "configured_unavailable"` が表示される場合、その HTTP アカウントは設定されていますが、現在のランタイムは SecretRef に裏付けられた署名シークレットを解決できませんでした。 - - 意図していたものを確認してください: + + どちらを意図していたか確認してください: - - Slack に登録された一致するスラッシュコマンドを使うネイティブコマンドモード（`channels.slack.commands.native: true`） + - Slack に登録された一致するスラッシュコマンドを伴うネイティブコマンドモード（`channels.slack.commands.native: true`） - または単一スラッシュコマンドモード（`channels.slack.slashCommand.enabled: true`） - `commands.useAccessGroups` とチャンネル/ユーザー許可リストも確認してください。 + `commands.useAccessGroups` とチャネル/ユーザー許可リストも確認してください。 -## 添付ファイルの vision リファレンス +## 添付ファイルのビジョンリファレンス -Slack ファイルのダウンロードが成功しサイズ制限が許す場合、Slack はダウンロード済みメディアをエージェントターンに添付できます。画像ファイルはメディア理解パスを通すか、vision 対応の返信モデルへ直接渡すことができます。他のファイルは画像入力として扱われるのではなく、ダウンロード可能なファイルコンテキストとして保持されます。 +Slack ファイルのダウンロードに成功し、サイズ制限が許す場合、Slack はダウンロード済みメディアをエージェントターンに添付できます。画像ファイルはメディア理解パスを通じて渡すことも、ビジョン対応の返信モデルに直接渡すこともできます。その他のファイルは画像入力として扱われるのではなく、ダウンロード可能なファイルコンテキストとして保持されます。 ### サポートされるメディアタイプ -| メディアタイプ | ソース | 現在の動作 | 注記 | +| メディア種別 | ソース | 現在の動作 | 注記 | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| JPEG / PNG / GIF / WebP 画像 | Slack ファイル URL | ダウンロードされ、ビジョン対応の処理向けにターンへ添付されます | ファイルごとの上限: `channels.slack.mediaMaxMb`（デフォルト 20 MB） | -| PDF ファイル | Slack ファイル URL | ダウンロードされ、`download-file` や `pdf` などのツール向けのファイルコンテキストとして公開されます | Slack インバウンドは PDF を画像ビジョン入力へ自動変換しません | -| その他のファイル | Slack ファイル URL | 可能な場合はダウンロードされ、ファイルコンテキストとして公開されます | バイナリファイルは画像入力として扱われません | -| スレッド返信 | スレッド開始ファイル | 返信に直接メディアがない場合、ルートメッセージのファイルをコンテキストとしてハイドレートできます | ファイルのみの開始メッセージは添付プレースホルダーを使用します | -| 複数画像メッセージ | 複数の Slack ファイル | 各ファイルは独立して評価されます | Slack 処理はメッセージごとに最大 8 ファイルまでに制限されます | +| JPEG / PNG / GIF / WebP 画像 | Slack ファイル URL | ダウンロードされ、vision 対応の処理のためにターンに添付されます | ファイルごとの上限: `channels.slack.mediaMaxMb` (デフォルト 20 MB) | +| PDF ファイル | Slack ファイル URL | ダウンロードされ、`download-file` や `pdf` などのツール向けにファイルコンテキストとして公開されます | Slack のインバウンドは PDF を画像 vision 入力へ自動変換しません | +| その他のファイル | Slack ファイル URL | 可能な場合はダウンロードされ、ファイルコンテキストとして公開されます | バイナリファイルは画像入力として扱われません | +| スレッド返信 | スレッド開始メッセージのファイル | 返信に直接メディアがない場合、ルートメッセージのファイルをコンテキストとして取り込めます | ファイルのみの開始メッセージは添付プレースホルダーを使用します | +| 複数画像メッセージ | 複数の Slack ファイル | 各ファイルは個別に評価されます | Slack の処理はメッセージごとに最大 8 ファイルに制限されます | ### インバウンドパイプライン -ファイル添付を含む Slack メッセージが届いた場合: +ファイル添付付きの Slack メッセージが到着した場合: -1. OpenClaw は bot トークン（`xoxb-...`）を使用して、Slack のプライベート URL からファイルをダウンロードします。 +1. OpenClaw は bot トークン (`xoxb-...`) を使用して Slack のプライベート URL からファイルをダウンロードします。 2. 成功すると、ファイルはメディアストアに書き込まれます。 -3. ダウンロードされたメディアパスとコンテンツタイプがインバウンドコンテキストに追加されます。 -4. 画像対応のモデル/ツールパスは、そのコンテキストの画像添付を使用できます。 -5. 画像以外のファイルは、それらを処理できるツール向けに、ファイルメタデータまたはメディア参照として引き続き利用できます。 +3. ダウンロード済みメディアのパスとコンテンツタイプがインバウンドコンテキストに追加されます。 +4. 画像対応モデル/ツールのパスは、そのコンテキストから画像添付を使用できます。 +5. 画像以外のファイルは、それらを扱えるツール向けのファイルメタデータまたはメディア参照として引き続き利用できます。 ### スレッドルート添付の継承 -メッセージがスレッド内に届いた場合（`thread_ts` 親を持つ場合）: +メッセージがスレッド内に到着した場合 (`thread_ts` の親を持つ場合): -- 返信自体に直接メディアがなく、含まれているルートメッセージにファイルがある場合、Slack はルートファイルをスレッド開始コンテキストとしてハイドレートできます。 -- 直接の返信添付は、ルートメッセージ添付より優先されます。 -- ファイルのみでテキストのないルートメッセージは、フォールバックがそのファイルを引き続き含められるように、添付プレースホルダーで表されます。 +- 返信自体に直接メディアがなく、含まれるルートメッセージにファイルがある場合、Slack はルートファイルをスレッド開始メッセージのコンテキストとして取り込めます。 +- 直接の返信添付は、ルートメッセージの添付より優先されます。 +- ファイルのみでテキストがないルートメッセージは添付プレースホルダーで表されるため、フォールバックでもそのファイルを含められます。 ### 複数添付の処理 1 つの Slack メッセージに複数のファイル添付が含まれる場合: -- 各添付はメディアパイプラインを通じて独立して処理されます。 -- ダウンロードされたメディア参照は、メッセージコンテキストに集約されます。 -- 処理順序は、イベントペイロード内の Slack のファイル順序に従います。 -- 1 つの添付のダウンロード失敗は、他の添付をブロックしません。 +- 各添付はメディアパイプラインを通じて個別に処理されます。 +- ダウンロード済みメディア参照はメッセージコンテキストに集約されます。 +- 処理順序はイベントペイロード内の Slack のファイル順に従います。 +- 1 つの添付のダウンロードに失敗しても、他の添付はブロックされません。 ### サイズ、ダウンロード、モデルの制限 -- **サイズ上限**: デフォルトはファイルごとに 20 MB。`channels.slack.mediaMaxMb` で設定できます。 -- **ダウンロード失敗**: Slack が配信できないファイル、期限切れ URL、アクセス不能なファイル、サイズ超過ファイル、Slack の認証/ログイン HTML レスポンスは、未対応形式として報告されるのではなくスキップされます。 -- **ビジョンモデル**: 画像分析は、アクティブな返信モデルがビジョンをサポートする場合はそれを使用し、それ以外の場合は `agents.defaults.imageModel` に設定された画像モデルを使用します。 +- **サイズ上限**: デフォルトはファイルごとに 20 MB です。`channels.slack.mediaMaxMb` で設定できます。 +- **ダウンロード失敗**: Slack が配信できないファイル、期限切れ URL、アクセスできないファイル、サイズ超過ファイル、Slack 認証/ログイン HTML レスポンスは、未対応形式として報告されるのではなくスキップされます。 +- **Vision モデル**: 画像分析は、vision をサポートしている場合はアクティブな返信モデルを使用し、そうでない場合は `agents.defaults.imageModel` で設定された画像モデルを使用します。 ### 既知の制限 -| シナリオ | 現在の動作 | 回避策 | +| シナリオ | 現在の動作 | 回避策 | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| 期限切れの Slack ファイル URL | ファイルはスキップされ、エラーは表示されません | Slack でファイルを再アップロードします | -| ビジョンモデルが設定されていない | 画像添付はメディア参照として保存されますが、画像として分析されません | `agents.defaults.imageModel` を設定するか、ビジョン対応の返信モデルを使用します | -| 非常に大きい画像（デフォルトでは 20 MB 超） | サイズ上限によりスキップされます | Slack が許可する場合は `channels.slack.mediaMaxMb` を増やします | -| 転送/共有された添付 | テキストと Slack ホストの画像/ファイルメディアはベストエフォートです | OpenClaw スレッドで直接再共有します | -| PDF 添付 | ファイル/メディアコンテキストとして保存され、画像ビジョン経由では自動的にルーティングされません | ファイルメタデータには `download-file` を使用し、PDF 分析には `pdf` ツールを使用します | +| 期限切れの Slack ファイル URL | ファイルはスキップされ、エラーは表示されません | Slack でファイルを再アップロードします | +| Vision モデルが設定されていない | 画像添付はメディア参照として保存されますが、画像として分析されません | `agents.defaults.imageModel` を設定するか、vision 対応の返信モデルを使用します | +| 非常に大きい画像 (デフォルトでは 20 MB 超) | サイズ上限によりスキップされます | Slack が許可する場合は `channels.slack.mediaMaxMb` を増やします | +| 転送/共有された添付 | テキストおよび Slack ホストの画像/ファイルメディアはベストエフォートです | OpenClaw スレッドで直接再共有します | +| PDF 添付 | ファイル/メディアコンテキストとして保存され、画像 vision 経由に自動ルーティングされません | ファイルメタデータには `download-file` を使用し、PDF 分析には `pdf` ツールを使用します | ### 関連ドキュメント - [メディア理解パイプライン](/ja-JP/nodes/media-understanding) - [PDF ツール](/ja-JP/tools/pdf) -- エピック: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 添付ビジョンの有効化 -- 回帰テスト: [#51353](https://github.com/openclaw/openclaw/issues/51353) +- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 添付の vision 有効化 +- リグレッションテスト: [#51353](https://github.com/openclaw/openclaw/issues/51353) - ライブ検証: [#51354](https://github.com/openclaw/openclaw/issues/51354) ## 関連 @@ -1070,16 +1378,16 @@ Slack ファイルのダウンロードが成功しサイズ制限が許す場 Slack ユーザーを Gateway にペアリングします。 - チャネルとグループ DM の動作。 + チャンネルとグループ DM の動作。 - - インバウンドメッセージをエージェントへルーティングします。 + + インバウンドメッセージをエージェントにルーティングします。 脅威モデルと堅牢化。 - - 設定レイアウトと優先順位。 + + 構成レイアウトと優先順位。 コマンドカタログと動作。 diff --git a/docs/ja-JP/ci.md b/docs/ja-JP/ci.md index 0ea1a9582..526710e97 100644 --- a/docs/ja-JP/ci.md +++ b/docs/ja-JP/ci.md @@ -1,94 +1,94 @@ --- read_when: - - CI ジョブが実行された、または実行されなかった理由を理解する必要がある + - CI ジョブが実行された理由、または実行されなかった理由を理解する必要があります - 失敗している GitHub Actions チェックをデバッグしています - リリース検証の実行または再実行を調整しています - - ClawSweeper のディスパッチまたは GitHub アクティビティ転送を変更しています -summary: CI ジョブグラフ、スコープゲート、リリース包括、対応するローカルコマンド + - ClawSweeper のディスパッチまたは GitHub アクティビティ転送を変更する場合 +summary: CI ジョブグラフ、スコープゲート、リリース包括ジョブ、同等のローカルコマンド title: CI パイプライン x-i18n: - generated_at: "2026-05-04T04:58:42Z" + generated_at: "2026-05-05T01:44:33Z" model: gpt-5.5 provider: openai - source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d + source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66 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` ジョブは差分を分類し、無関係な領域だけが変更された場合は高コストなレーンをオフにします。手動の `workflow_dispatch` 実行は意図的にスマートスコーピングをバイパスし、リリース候補と広範な検証のためにグラフ全体へ展開します。Android レーンは `include_android` によるオプトインのままです。リリース専用の Plugin カバレッジは別個の [`Plugin プレリリース`](#plugin-prerelease) ワークフローにあり、[`完全リリース検証`](#full-release-validation) または明示的な手動 dispatch からのみ実行されます。 ## パイプライン概要 -| ジョブ | 目的 | 実行タイミング | +| ジョブ | 目的 | 実行されるタイミング | | -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | docs-only 変更、変更スコープ、変更された拡張、CI マニフェストのビルドを検出する | 非ドラフトのプッシュと PR では常に | -| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | 非ドラフトのプッシュと PR では常に | -| `security-dependency-audit` | npm アドバイザリに対する依存関係不要の本番 lockfile 監査 | 非ドラフトのプッシュと PR では常に | -| `security-fast` | 高速セキュリティジョブの必須集約 | 非ドラフトのプッシュと PR では常に | -| `check-dependencies` | 本番 Knip の依存関係のみのパスと未使用ファイル allowlist ガード | 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` | チャンネル、バンドル、契約、拡張レーンを除く 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` | ドキュメントのフォーマット、lint、壊れたリンクのチェック | ドキュメント変更 | -| `skills-python` | Python backed skills 向けの Ruff + pytest | Python skill 関連の変更 | -| `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 成功または手動ディスパッチ | -| `openclaw-performance` | mock-provider、deep-profile、GPT 5.4 live レーンを含む日次/オンデマンド Kova ランタイムパフォーマンスレポート | スケジュールおよび手動ディスパッチ | +| `preflight` | docs のみの変更、変更スコープ、変更された extension を検出し、CI マニフェストを構築します | 非ドラフトの push と PR では常時 | +| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | 非ドラフトの push と PR では常時 | +| `security-dependency-audit` | npm advisory に対する依存関係不要の本番 lockfile 監査 | 非ドラフトの push と PR では常時 | +| `security-fast` | 高速セキュリティジョブの必須集約 | 非ドラフトの push と PR では常時 | +| `check-dependencies` | 本番 Knip の依存関係専用パスと未使用ファイル allowlist ガード | Node 関連の変更 | +| `build-artifacts` | `dist/`、Control UI、ビルド済みアーティファクトチェック、再利用可能な下流アーティファクトをビルドします | Node 関連の変更 | +| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速 Linux 正当性レーン | Node 関連の変更 | +| `checks-fast-contracts-channels` | 安定した集約チェック結果を持つシャーディングされたチャネル contract チェック | Node 関連の変更 | +| `checks-node-core-test` | channel、bundled、contract、extension レーンを除く Core Node テストシャード | Node 関連の変更 | +| `check` | シャーディングされたメインのローカルゲート相当: 本番型、lint、ガード、テスト型、strict smoke | Node 関連の変更 | +| `check-additional` | アーキテクチャ、シャーディングされた boundary/prompt drift、extension ガード、package boundary、gateway watch | Node 関連の変更 | +| `build-smoke` | ビルド済み CLI smoke テストと起動時メモリ smoke | Node 関連の変更 | +| `checks` | ビルド済みアーティファクトのチャネルテスト用 verifier | Node 関連の変更 | +| `checks-node-compat-node22` | Node 22 互換性ビルドと smoke レーン | リリース用の手動 CI dispatch | +| `check-docs` | Docs のフォーマット、lint、壊れたリンクのチェック | Docs が変更された場合 | +| `skills-python` | Python ベースの Skills 用 Ruff + pytest | Python Skill 関連の変更 | +| `checks-windows` | Windows 固有のプロセス/パステストと共有 runtime 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 成功または手動 dispatch | +| `openclaw-performance` | mock-provider、deep-profile、GPT 5.4 live レーンを含む日次/オンデマンド Kova runtime パフォーマンスレポート | スケジュール実行と手動 dispatch | -## フェイルファスト順序 +## Fail-fast の順序 -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 レーンと重なって実行されるため、共有ビルドの準備ができ次第、下流の利用側が開始できます。 -4. その後、より重いプラットフォームおよびランタイムレーンが展開されます: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、`android`。 +1. `preflight` が、どのレーンがそもそも存在するかを決定します。`docs-scope` と `changed-scope` のロジックは、このジョブ内のステップであり、独立したジョブではありません。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、`skills-python` は、より重いアーティファクトジョブやプラットフォーム matrix ジョブを待たずにすばやく失敗します。 +3. `build-artifacts` は高速 Linux レーンと重なるため、共有ビルドの準備ができ次第、下流の consumer を開始できます。 +4. その後、より重いプラットフォームおよび runtime レーンが展開されます: `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 key はバージョン付き (`CI-v7-*`) なので、古いキューグループにある GitHub 側のゾンビが新しい main 実行を無期限にブロックすることはありません。手動のフルスイート実行は `CI-manual-v1-*` を使用し、進行中の実行をキャンセルしません。 +同じ PR または `main` ref に新しい push が入ると、GitHub は置き換えられたジョブを `cancelled` としてマークする場合があります。同じ ref の最新実行も失敗していない限り、それは CI ノイズとして扱います。集約シャードチェックは `!cancelled() && always()` を使用するため、通常のシャード失敗は引き続き報告しますが、ワークフロー全体がすでに置き換えられた後にはキューに入りません。自動 CI concurrency key はバージョン付き (`CI-v7-*`) なので、古い queue group にある GitHub 側の zombie が新しい main 実行を無期限にブロックすることはありません。手動の full-suite 実行は `CI-manual-v1-*` を使用し、進行中の実行を cancel しません。 ## スコープとルーティング -スコープロジックは `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 でカバーされています。手動 dispatch は changed-scope 検出をスキップし、preflight マニフェストをすべての scoped area が変更されたかのように動作させます。 -- **CI ワークフロー編集** は Node CI グラフとワークフロー lint を検証しますが、それ自体では Windows、Android、macOS ネイティブビルドを強制しません。これらのプラットフォームレーンはプラットフォームソース変更にスコープされたままです。 -- **CI ルーティングのみの編集、選択された安価な core-test fixture 編集、狭い plugin contract helper/test-routing 編集** は高速な Node のみのマニフェストパスを使用します: `preflight`、security、単一の `checks-fast-core` タスクです。このパスは、変更が高速タスクが直接実行するルーティングまたは helper surface に限定されている場合、ビルドアーティファクト、Node 22 互換性、チャンネル契約、完全な core シャード、bundled-plugin シャード、追加ガードマトリックスをスキップします。 -- **Windows Node チェック** は、Windows 固有のプロセス/パスラッパー、npm/pnpm/UI runner helper、パッケージマネージャ設定、そのレーンを実行する CI ワークフロー surface にスコープされます。無関係なソース、Plugin、install-smoke、テストのみの変更は Linux Node レーンに留まります。 +- **CI ワークフロー編集** は Node CI グラフとワークフロー linting を検証しますが、それだけで Windows、Android、macOS native build を強制することはありません。これらのプラットフォームレーンはプラットフォーム source の変更に scoped されたままです。 +- **CI routing のみの編集、選択された安価な core-test fixture 編集、狭い Plugin contract helper/test-routing 編集** は、高速な Node のみのマニフェストパスを使用します: `preflight`、security、単一の `checks-fast-core` task。このパスは、変更が高速 task が直接 exercise する routing または helper surface に限定される場合、build artifacts、Node 22 compatibility、channel contracts、full core shards、bundled-plugin shards、additional guard matrices をスキップします。 +- **Windows Node チェック** は、Windows 固有の process/path wrapper、npm/pnpm/UI runner helper、package manager config、そのレーンを実行する CI workflow surface に scoped されます。無関係な source、Plugin、install-smoke、test-only の変更は Linux Node レーンのままです。 -最も遅い Node テストファミリーは、各ジョブが小さく保たれ、ランナーを過剰に予約しないよう分割またはバランス調整されています。チャンネル契約は 3 つの重み付きシャードとして実行され、core unit fast/support レーンは別々に実行され、core runtime infra は state と process/config シャードに分割され、auto-reply はバランス調整された worker として実行されます（reply subtree は agent-runner、dispatch、commands/state-routing シャードに分割）。agentic gateway/server config はビルド済みアーティファクトを待つ代わりに chat/auth/model/http-plugin/runtime/startup レーンに分割されます。広範な browser、QA、media、その他の Plugin テストは共有 Plugin catch-all ではなく専用の Vitest config を使用します。include-pattern シャードは CI シャード名を使用してタイミングエントリを記録するため、`.artifacts/vitest-shard-timings.json` は config 全体とフィルター済みシャードを区別できます。`check-additional` は package-boundary compile/canary 作業をまとめ、ランタイムトポロジーアーキテクチャを gateway watch カバレッジから分離します。境界ガードリストは 4 つのマトリックスシャードにストライプされ、各シャードは選択された独立ガードを並行実行し、`pnpm prompt:snapshots:check` を含む各チェックのタイミングを出力します。これにより、Codex ランタイムの happy-path プロンプトドリフトはそれを引き起こした PR に固定されます。Gateway watch、チャンネルテスト、core support-boundary シャードは、`dist/` と `dist-runtime/` がすでにビルドされた後、`build-artifacts` 内で並行実行されます。 +最も遅い Node テストファミリーは分割またはバランス調整され、各ジョブが runner を過剰に予約せず小さく保たれます。channel contracts は 3 つの weighted shard として実行され、core unit fast/support レーンは別々に実行され、core runtime infra は state shard と process/config shard に分割され、auto-reply は balanced worker として実行されます（reply subtree は agent-runner、dispatch、commands/state-routing shard に分割）。また、agentic gateway/server config は、built artifacts を待つ代わりに chat/auth/model/http-plugin/runtime/startup レーンに分割されます。広範な browser、QA、media、miscellaneous Plugin テストは、共有 Plugin catch-all ではなく専用の Vitest config を使用します。include-pattern shard は CI shard 名を使用して timing entry を記録するため、`.artifacts/vitest-shard-timings.json` は config 全体と filtered shard を区別できます。`check-additional` は package-boundary compile/canary work をまとめ、runtime topology architecture を gateway watch coverage から分離します。boundary guard list は 4 つの matrix shard に stripe され、各 shard は選択された独立 guard を並行実行し、`pnpm prompt:snapshots:check` を含むチェックごとの timing を出力します。これにより、Codex runtime happy-path prompt drift はそれを引き起こした PR に固定されます。Gateway watch、channel tests、core support-boundary shard は、`dist/` と `dist-runtime/` がすでにビルドされた後、`build-artifacts` 内で並行実行されます。 -Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party フレーバーには独立した source set や manifest はありません。その unit-test レーンは 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 flags 付きで flavor を引き続きコンパイルしつつ、Android 関連の push ごとに debug APK packaging job を重複して実行することを避けます。 -`check-dependencies` シャードは `pnpm deadcode:dependencies`（最新の Knip バージョンに固定された本番 Knip の依存関係のみのパスで、`dlx` インストール時は pnpm の minimum release age が無効）と `pnpm deadcode:unused-files` を実行します。後者は Knip の本番未使用ファイル検出結果を `scripts/deadcode-unused-files.allowlist.mjs` と比較します。unused-file ガードは、PR が新しい未レビューの未使用ファイルを追加した場合や古い allowlist エントリを残した場合に失敗します。一方で、Knip が静的に解決できない意図的な dynamic Plugin、generated、build、live-test、package bridge surface は維持します。 +`check-dependencies` shard は `pnpm deadcode:dependencies`（最新の Knip version に固定され、`dlx` install では pnpm の minimum release age が無効化された、本番 Knip の依存関係専用パス）と `pnpm deadcode:unused-files` を実行します。後者は Knip の本番 unused-file finding を `scripts/deadcode-unused-files.allowlist.mjs` と比較します。unused-file guard は、PR が新しい未レビューの未使用ファイルを追加した場合や stale な allowlist entry を残した場合に失敗します。一方で、Knip が静的に解決できない意図的な dynamic Plugin、generated、build、live-test、package bridge surface は保持します。 ## ClawSweeper アクティビティ転送 -`.github/workflows/clawsweeper-dispatch.yml` は、OpenClaw リポジトリアクティビティを ClawSweeper に渡すターゲット側ブリッジです。信頼されていないプルリクエストコードの checkout や実行は行いません。このワークフローは `CLAWSWEEPER_APP_PRIVATE_KEY` から GitHub App token を作成し、compact な `repository_dispatch` payload を `openclaw/clawsweeper` にディスパッチします。 +`.github/workflows/clawsweeper-dispatch.yml` は、OpenClaw repository activity から ClawSweeper への target-side bridge です。信頼されていない pull request code を checkout したり実行したりしません。このワークフローは `CLAWSWEEPER_APP_PRIVATE_KEY` から GitHub App token を作成し、compact な `repository_dispatch` payload を `openclaw/clawsweeper` に dispatch します。 このワークフローには 4 つのレーンがあります。 -- `clawsweeper_item` は正確な issue および pull request review request 用。 -- `clawsweeper_comment` は issue comment 内の明示的な ClawSweeper コマンド用。 -- `clawsweeper_commit_review` は `main` プッシュ上の commit-level review request 用。 -- `github_activity` は ClawSweeper agent が調査する可能性がある一般的な GitHub アクティビティ用。 +- 正確な issue と pull request review request 用の `clawsweeper_item`; +- issue comment 内の明示的な ClawSweeper command 用の `clawsweeper_comment`; +- `main` push 上の commit-level review request 用の `clawsweeper_commit_review`; +- ClawSweeper agent が inspect できる一般的な GitHub activity 用の `github_activity`。 -`github_activity` レーンは正規化されたメタデータのみを転送します: event type、action、actor、repository、item number、URL、title、state、および存在する場合は comment または review の短い excerpt です。意図的に Webhook 本文全体の転送は避けています。`openclaw/clawsweeper` 側の受信ワークフローは `.github/workflows/github-activity.yml` で、正規化されたイベントを ClawSweeper agent 用の OpenClaw Gateway hook に投稿します。 +`github_activity` レーンは normalized metadata のみを転送します: event type、action、actor、repository、item number、URL、title、state、および comment または review が存在する場合の short excerpt。意図的に webhook body 全体の転送は避けています。`openclaw/clawsweeper` 側の受信ワークフローは `.github/workflows/github-activity.yml` で、normalized event を ClawSweeper agent 用の OpenClaw Gateway hook に投稿します。 -一般的なアクティビティは観察であり、デフォルト配信ではありません。ClawSweeper agent はプロンプト内で Discord ターゲットを受け取り、そのイベントが意外で、対応可能で、リスクがあり、または運用上有用な場合にのみ `#clawsweeper` に投稿すべきです。通常の open、edit、bot churn、重複 Webhook ノイズ、通常の review traffic は `NO_REPLY` になるべきです。 +一般的なアクティビティは観測であり、デフォルト配信ではありません。ClawSweeper agent は prompt 内で Discord target を受け取り、event が意外、actionable、risky、または operationally useful な場合にのみ `#clawsweeper` に投稿するべきです。通常の open、edit、bot churn、duplicate webhook noise、normal review traffic は `NO_REPLY` になるべきです。 -この経路全体で、GitHub の title、comment、body、review text、branch name、commit message は信頼されていないデータとして扱ってください。これらは要約とトリアージの入力であり、ワークフローや agent runtime への指示ではありません。 +GitHub title、comment、body、review text、branch name、commit message は、この経路全体で信頼されていないデータとして扱います。これらは summarization と triage の入力であり、workflow や agent runtime への instruction ではありません。 -## 手動ディスパッチ +## 手動 dispatch -手動 CI ディスパッチは通常の CI と同じジョブグラフを実行しますが、Android 以外のスコープ付きレーンをすべて強制的に有効にします: Linux Node シャード、バンドル済み Plugin シャード、チャンネルコントラクト、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、docs チェック、Python Skills、Windows、macOS、Control UI i18n。スタンドアロンの手動 CI ディスパッチは、`include_android=true` の場合のみ Android を実行します。完全リリースの包括ワークフローは `include_android=true` を渡すことで Android を有効にします。Plugin プレリリース静的チェック、リリース専用の `agentic-plugins` シャード、完全な extension バッチスイープ、Plugin プレリリース Docker レーンは CI から除外されます。Docker プレリリーススイートは、`Full Release Validation` がリリース検証ゲートを有効にして別個の `Plugin Prerelease` ワークフローをディスパッチした場合にのみ実行されます。 +手動 CI ディスパッチは通常の CI と同じジョブグラフを実行しますが、Android 以外のすべてのスコープ付きレーンを強制的に有効にします。対象は Linux Node シャード、バンドル Plugin シャード、チャンネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Control UI i18n です。スタンドアロンの手動 CI ディスパッチは `include_android=true` の場合のみ Android だけを実行します。完全リリースの包括ワークフローは `include_android=true` を渡して Android を有効にします。Plugin プリリリース静的チェック、リリース専用の `agentic-plugins` シャード、拡張機能の完全バッチスイープ、Plugin プリリリース Docker レーンは CI から除外されます。Docker プリリリーススイートは、`Full Release Validation` がリリース検証ゲートを有効にして別の `Plugin Prerelease` ワークフローをディスパッチした場合にのみ実行されます。 -手動実行は一意の同時実行グループを使うため、リリース候補のフルスイートが同じ ref 上の別の push または PR 実行によってキャンセルされることはありません。任意の `target_ref` 入力を使うと、信頼済みの呼び出し元が、選択されたディスパッチ ref のワークフローファイルを使いながら、そのグラフをブランチ、タグ、または完全な commit SHA に対して実行できます。 +手動実行では一意の並行実行グループを使うため、リリース候補のフルスイートが、同じ ref 上の別の push や PR 実行によってキャンセルされることはありません。任意の `target_ref` 入力により、信頼された呼び出し元は、選択したディスパッチ ref のワークフローファイルを使いながら、そのグラフをブランチ、タグ、または完全なコミット SHA に対して実行できます。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -100,15 +100,15 @@ gh workflow run full-release-validation.yml --ref main -f ref= | ランナー | ジョブ | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`、高速セキュリティジョブと集約（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速プロトコル/コントラクト/バンドル済みチェック、シャード化されたチャンネルコントラクトチェック、lint 以外の `check` シャード、`check-additional` シャードと集約、Node テスト集約検証、docs チェック、Python Skills、workflow-sanity、labeler、auto-response。install-smoke preflight も GitHub ホストの Ubuntu を使うため、Blacksmith マトリックスをより早くキューに入れられます | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、軽量な extension シャード、`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`、低負荷の拡張機能シャード、`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 ではキュー時間のコストが節約分を上回ったため） | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`。fork は `macos-latest` にフォールバックします | -| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-swift`。fork は `macos-latest` にフォールバックします | +| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`。fork では `macos-latest` にフォールバックします | +| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-swift`。fork では `macos-latest` にフォールバックします | -## ローカルでの相当コマンド +## ローカルでの同等コマンド ```bash pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD @@ -135,9 +135,9 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md ``` -## OpenClaw Performance +## OpenClaw パフォーマンス -`OpenClaw Performance` は製品/ランタイムのパフォーマンスワークフローです。`main` で毎日実行され、手動でもディスパッチできます: +`OpenClaw Performance` は製品/ランタイムのパフォーマンスワークフローです。`main` で毎日実行され、手動でもディスパッチできます。 ```bash gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3 @@ -145,25 +145,25 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3 ``` -手動ディスパッチは通常、ワークフロー ref をベンチマークします。リリースタグまたは別のブランチを現在のワークフロー実装でベンチマークするには、`target_ref` を設定します。公開されるレポートパスと latest ポインターはテスト対象の ref でキー付けされ、各 `index.md` にはテスト対象の ref/SHA、ワークフロー ref/SHA、Kova ref、プロファイル、レーン認証モード、モデル、繰り返し回数、シナリオフィルターが記録されます。 +手動ディスパッチは通常、ワークフロー ref をベンチマークします。リリースタグや別のブランチを現在のワークフロー実装でベンチマークするには、`target_ref` を設定します。公開されるレポートパスと latest ポインターはテスト対象 ref をキーにし、各 `index.md` には、テスト対象 ref/SHA、ワークフロー ref/SHA、Kova ref、プロファイル、レーン認証モード、モデル、繰り返し回数、シナリオフィルターが記録されます。 -このワークフローは固定されたリリースから OCM を、`openclaw/Kova` から固定された `kova_ref` 入力の Kova をインストールし、その後 3 つのレーンを実行します: +このワークフローは、固定されたリリースから OCM を、`openclaw/Kova` から固定された `kova_ref` 入力の Kova をインストールし、次の 3 つのレーンを実行します。 -- `mock-provider`: 決定論的な偽の OpenAI 互換認証を持つローカルビルドのランタイムに対する Kova 診断シナリオ。 -- `mock-deep-profile`: startup、Gateway、agent-turn ホットスポットの CPU/heap/trace プロファイリング。 +- `mock-provider`: 決定的な偽の OpenAI 互換認証を使うローカルビルドランタイムに対する Kova 診断シナリオ。 +- `mock-deep-profile`: 起動、Gateway、エージェントターンのホットスポットに対する CPU/ヒープ/トレースのプロファイリング。 - `live-gpt54`: 実際の OpenAI `openai/gpt-5.4` エージェントターン。`OPENAI_API_KEY` が利用できない場合はスキップされます。 -mock-provider レーンは Kova パスの後に OpenClaw ネイティブのソースプローブも実行します: デフォルト、hook、50-Plugin 起動ケースでの Gateway 起動タイミングとメモリ、mock-OpenAI `channel-chat-baseline` hello ループの反復、起動済み Gateway に対する CLI 起動コマンド。ソースプローブの Markdown サマリーはレポートバンドル内の `source/index.md` にあり、未加工 JSON がその横に置かれます。 +mock-provider レーンは、Kova パスの後に OpenClaw ネイティブのソースプローブも実行します。デフォルト、フック、50 Plugin 起動ケースでの Gateway 起動時間とメモリ、mock-OpenAI `channel-chat-baseline` hello ループの反復実行、起動済み Gateway に対する CLI 起動コマンドです。ソースプローブの Markdown サマリーはレポートバンドル内の `source/index.md` にあり、その横に生の JSON が置かれます。 -すべてのレーンは GitHub アーティファクトをアップロードします。`CLAWGRIT_REPORTS_TOKEN` が設定されている場合、ワークフローは `report.json`、`report.md`、バンドル、`index.md`、ソースプローブアーティファクトも `openclaw-performance//-//` 配下の `openclaw/clawgrit-reports` にコミットします。現在のテスト対象 ref ポインターは `openclaw-performance//latest-.json` として書き込まれます。 +すべてのレーンは GitHub アーティファクトをアップロードします。`CLAWGRIT_REPORTS_TOKEN` が構成されている場合、ワークフローは `report.json`、`report.md`、バンドル、`index.md`、ソースプローブアーティファクトも `openclaw/clawgrit-reports` の `openclaw-performance//-//` 配下にコミットします。現在のテスト対象 ref ポインターは `openclaw-performance//latest-.json` として書き込まれます。 ## 完全リリース検証 -`Full Release Validation` は「リリース前にすべてを実行する」ための手動包括ワークフローです。ブランチ、タグ、または完全な commit SHA を受け取り、そのターゲットで手動 `CI` ワークフローをディスパッチし、リリース専用の Plugin/パッケージ/静的/Docker 証明のために `Plugin Prerelease` をディスパッチし、install smoke、package acceptance、Docker リリースパススイート、live/E2E、OpenWebUI、QA Lab parity、Matrix、Telegram レーンのために `OpenClaw Release Checks` をディスパッチします。`rerun_group=all` と `release_profile=full` の場合、release checks の `release-package-under-test` アーティファクトに対して `NPM Telegram Beta E2E` も実行します。公開後は `npm_telegram_package_spec` を渡して、公開済み npm パッケージに対して同じ Telegram パッケージレーンを再実行します。 +`Full Release Validation` は「リリース前にすべてを実行する」ための手動の包括ワークフローです。ブランチ、タグ、または完全なコミット SHA を受け取り、そのターゲットで手動 `CI` ワークフローをディスパッチし、リリース専用の Plugin/パッケージ/静的/Docker 証明のために `Plugin Prerelease` をディスパッチし、install smoke、package acceptance、クロス OS パッケージチェック、QA Lab parity、Matrix、Telegram レーンのために `OpenClaw Release Checks` をディスパッチします。安定版/デフォルト実行では、網羅的なライブ/E2E と Docker リリースパスのカバレッジは `run_release_soak=true` の背後に置かれます。`release_profile=full` はその soak カバレッジを強制的に有効にし、広範なアドバイザリ検証を広範なまま維持します。`rerun_group=all` と `release_profile=full` の場合、release checks の `release-package-under-test` アーティファクトに対して `NPM Telegram Beta E2E` も実行します。公開後は、`npm_telegram_package_spec` を渡すことで、公開済み npm パッケージに対して同じ Telegram パッケージレーンを再実行できます。 -ステージマトリックス、正確なワークフロージョブ名、プロファイルの違い、アーティファクト、対象を絞った再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation) を参照してください。 +ステージマトリクス、正確なワークフロージョブ名、プロファイルの違い、アーティファクト、対象を絞った再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation)を参照してください。 -`OpenClaw Release Publish` は、変更を加える手動リリースワークフローです。リリースタグが存在し、OpenClaw npm preflight が成功した後に、`release/YYYY.M.D` または `main` からディスパッチします。これは `pnpm plugins:sync:check` を検証し、公開可能なすべての Plugin パッケージに対して `Plugin NPM Release` をディスパッチし、同じリリース SHA に対して `Plugin ClawHub Release` をディスパッチし、その後でのみ保存された `preflight_run_id` を使って `OpenClaw NPM Release` をディスパッチします。 +`OpenClaw Release Publish` は、変更を伴う手動リリースワークフローです。リリースタグが存在し、OpenClaw npm preflight が成功した後に、`release/YYYY.M.D` または `main` からディスパッチします。`pnpm plugins:sync:check` を検証し、公開可能なすべての Plugin パッケージに対して `Plugin NPM Release` をディスパッチし、同じリリース SHA に対して `Plugin ClawHub Release` をディスパッチし、その後にのみ保存済みの `preflight_run_id` を使って `OpenClaw NPM Release` をディスパッチします。 ```bash gh workflow run openclaw-release-publish.yml \ @@ -173,31 +173,31 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -動きの速いブランチ上で固定 commit 証明を得るには、`gh workflow run ... --ref main -f ref=` ではなくヘルパーを使います: +移り変わりの速いブランチ上で固定コミットの証明を行う場合は、`gh workflow run ... --ref main -f ref=` の代わりにヘルパーを使います。 ```bash pnpm ci:full-release --sha ``` -GitHub ワークフローディスパッチ ref はブランチまたはタグである必要があり、生の commit SHA ではいけません。このヘルパーはターゲット SHA に一時的な `release-ci/-...` ブランチを push し、その固定 ref から `Full Release Validation` をディスパッチし、すべての子ワークフローの `headSha` がターゲットと一致することを検証し、実行が完了したら一時ブランチを削除します。包括検証器は、いずれかの子ワークフローが異なる SHA で実行された場合にも失敗します。 +GitHub ワークフローディスパッチ ref はブランチまたはタグである必要があり、生のコミット SHA は使えません。このヘルパーは、ターゲット SHA に一時的な `release-ci/-...` ブランチを push し、その固定 ref から `Full Release Validation` をディスパッチし、すべての子ワークフローの `headSha` がターゲットと一致することを検証し、実行完了時に一時ブランチを削除します。包括検証も、いずれかの子ワークフローが異なる SHA で実行された場合は失敗します。 -`release_profile` は、リリースチェックに渡すライブ/プロバイダーの範囲を制御します。手動リリースワークフローのデフォルトは `stable` です。広範な助言的プロバイダー/メディアマトリクスを意図的に使いたい場合にのみ `full` を使用してください。 +`release_profile` は、リリースチェックに渡されるライブ/プロバイダーの範囲を制御します。手動リリースワークフローのデフォルトは `stable` です。広範な参考プロバイダー/メディアマトリクスを意図的に実行したい場合にのみ `full` を使用します。`run_release_soak` は、安定版/デフォルトのリリースチェックで、網羅的なライブ/E2E と Docker リリースパスのソークを実行するかどうかを制御します。`full` はソークを強制的に有効にします。 -- `minimum` は、最速の OpenAI/コアのリリースクリティカルなレーンに絞ります。 +- `minimum` は、最速の OpenAI/コアのリリースクリティカルなレーンだけを保持します。 - `stable` は、安定版のプロバイダー/バックエンドセットを追加します。 -- `full` は、広範な助言的プロバイダー/メディアマトリクスを実行します。 +- `full` は、広範な参考プロバイダー/メディアマトリクスを実行します。 -アンブレラはディスパッチした子実行 ID を記録し、最後の `Verify full validation` ジョブは現在の子実行の結論を再確認し、各子実行の最も遅いジョブの表を追記します。子ワークフローを再実行して成功した場合は、親検証ジョブだけを再実行して、アンブレラの結果とタイミング要約を更新してください。 +アンブレラはディスパッチされた子実行 ID を記録し、最後の `Verify full validation` ジョブは現在の子実行の結論を再確認し、各子実行の最も遅いジョブの表を追記します。子ワークフローを再実行して成功した場合は、親の検証ジョブだけを再実行して、アンブレラの結果とタイミング要約を更新します。 -復旧用に、`Full Release Validation` と `OpenClaw Release Checks` はどちらも `rerun_group` を受け付けます。リリース候補には `all`、通常の完全 CI 子だけには `ci`、Plugin プレリリース子だけには `plugin-prerelease`、すべてのリリース子には `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 プレリリース子だけには `plugin-prerelease`、すべてのリリース子には `release-checks`、またはアンブレラ上のより狭いグループとして `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` を使用します。これにより、焦点を絞った修正後に、失敗したリリースボックスの再実行を限定できます。1 つのクロス OS レーンだけが失敗した場合は、たとえば `windows/packaged-upgrade` のように、`rerun_group=cross-os` と `cross_os_suite_filter` を組み合わせます。長いクロス OS コマンドは Heartbeat 行を出力し、パッケージ化アップグレードの要約にはフェーズごとのタイミングが含まれます。QA リリースチェックレーンは参考扱いのため、QA のみの失敗は警告されますが、リリースチェック検証はブロックしません。 -`OpenClaw Release Checks` は、信頼済みワークフロー参照を使って選択された参照を一度だけ `release-package-under-test` tarball に解決し、そのアーティファクトをライブ/E2E リリースパスの Docker ワークフローとパッケージ受け入れシャードの両方に渡します。これにより、リリースボックス間でパッケージのバイト列が一貫し、複数の子ジョブで同じ候補を再パックすることを避けられます。 +`OpenClaw Release Checks` は、信頼されたワークフロー参照を使用して、選択された参照を一度だけ `release-package-under-test` tarball に解決し、その成果物をクロス OS チェックと Package Acceptance に渡します。さらに、ソークカバレッジを実行する場合は、ライブ/E2E リリースパス Docker ワークフローにも渡します。これにより、リリースボックス間でパッケージのバイト列が一貫し、同じ候補を複数の子ジョブで再パッケージ化することを避けられます。 -`ref=main` かつ `rerun_group=all` の重複した `Full Release Validation` 実行は、古いアンブレラを置き換えます。親モニターは、親がキャンセルされたときに、すでにディスパッチした子ワークフローをすべてキャンセルするため、新しい main 検証が古い 2 時間のリリースチェック実行の後ろで待機し続けることはありません。リリースブランチ/タグ検証と絞り込んだ再実行グループは `cancel-in-progress: false` を維持します。 +`ref=main` かつ `rerun_group=all` の重複した `Full Release Validation` 実行は、古いアンブレラを置き換えます。親モニターは、親がキャンセルされたときに、すでにディスパッチ済みの子ワークフローをキャンセルします。そのため、新しい main 検証が、古い 2 時間のリリースチェック実行の後ろで待機することはありません。リリースブランチ/タグ検証と焦点を絞った再実行グループでは、`cancel-in-progress: false` を維持します。 ## ライブと E2E シャード -リリースのライブ/E2E 子は、広範なネイティブ `pnpm test:live` カバレッジを維持しますが、1 つの直列ジョブではなく、`scripts/test-live-shard.mjs` を通じて名前付きシャードとして実行します。 +リリースのライブ/E2E 子は、広範なネイティブ `pnpm test:live` カバレッジを維持しますが、1 つのシリアルジョブではなく、`scripts/test-live-shard.mjs` を通じて名前付きシャードとして実行します。 - `native-live-src-agents` - `native-live-src-gateway-core` @@ -211,57 +211,57 @@ GitHub ワークフローディスパッチ ref はブランチまたはタグ - `native-live-extensions-xai` - 分割されたメディア音声/動画シャードと、プロバイダーでフィルターされた音楽シャード -これにより、同じファイルカバレッジを維持しながら、遅いライブプロバイダーの失敗を再実行し、診断しやすくします。集約用の `native-live-extensions-o-z`、`native-live-extensions-media`、`native-live-extensions-media-music` シャード名は、手動の一回限りの再実行でも引き続き有効です。 +これにより、同じファイルカバレッジを保ちながら、遅いライブプロバイダーの失敗を再実行および診断しやすくなります。集約された `native-live-extensions-o-z`、`native-live-extensions-media`、`native-live-extensions-media-music` シャード名は、手動の一回限りの再実行でも引き続き有効です。 -ネイティブライブメディアシャードは、`Live Media Runner Image` ワークフローでビルドされる `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` で実行されます。このイメージには `ffmpeg` と `ffprobe` が事前インストールされています。メディアジョブはセットアップ前にバイナリを検証するだけです。Docker バックのライブスイートは通常の Blacksmith ランナー上に維持してください。コンテナジョブは、ネストされた Docker テストを起動する場所としては不適切です。 +ネイティブのライブメディアシャードは、`Live Media Runner Image` ワークフローでビルドされる `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` で実行されます。このイメージには `ffmpeg` と `ffprobe` が事前インストールされています。メディアジョブはセットアップ前にバイナリを確認するだけです。Docker ベースのライブスイートは通常の Blacksmith ランナー上に維持してください。コンテナジョブは、ネストした Docker テストを起動する場所として適していません。 -Docker バックのライブモデル/バックエンドシャードは、選択されたコミットごとに別個の共有 `ghcr.io/openclaw/openclaw-live-test:` イメージを使用します。ライブリリースワークフローはそのイメージを一度だけビルドしてプッシュし、その後 Docker ライブモデル、プロバイダー分割 Gateway、CLI バックエンド、ACP バインド、Codex ハーネスの各シャードが `OPENCLAW_SKIP_DOCKER_BUILD=1` で実行されます。Gateway Docker シャードには、ワークフロージョブのタイムアウトより短い明示的なスクリプトレベルの `timeout` 上限があり、停止したコンテナやクリーンアップパスがリリースチェック予算全体を消費せず、早く失敗するようにしています。これらのシャードが完全なソース Docker ターゲットを個別に再ビルドしている場合、そのリリース実行は誤設定されており、重複したイメージビルドで実時間を浪費します。 +Docker ベースのライブモデル/バックエンドシャードは、選択されたコミットごとに別の共有 `ghcr.io/openclaw/openclaw-live-test:` イメージを使用します。ライブリリースワークフローは、そのイメージを一度ビルドしてプッシュし、その後 Docker ライブモデル、プロバイダーで分割された Gateway、CLI バックエンド、ACP バインド、Codex ハーネスの各シャードが `OPENCLAW_SKIP_DOCKER_BUILD=1` で実行されます。Gateway Docker シャードには、ワークフロージョブのタイムアウトより短い明示的なスクリプトレベルの `timeout` 上限が設定されているため、コンテナやクリーンアップパスが停止しても、リリースチェックの予算全体を消費せずに素早く失敗します。これらのシャードがフルソース Docker ターゲットを個別に再ビルドする場合、そのリリース実行は設定ミスであり、重複イメージビルドに実時間を浪費します。 -## パッケージ受け入れ +## Package Acceptance -「このインストール可能な OpenClaw パッケージは製品として動作するか」という問いには、`Package Acceptance` を使用します。これは通常の CI とは異なります。通常の CI はソースツリーを検証しますが、パッケージ受け入れは、ユーザーがインストールまたは更新後に実行するものと同じ Docker E2E ハーネスを通じて、単一の tarball を検証します。 +「このインストール可能な OpenClaw パッケージは製品として動作するか」という問いには、`Package Acceptance` を使用します。これは通常の CI とは異なります。通常の CI はソースツリーを検証しますが、Package Acceptance は、インストールまたは更新後にユーザーが実行するものと同じ Docker E2E ハーネスを通じて、単一の 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 ステップ要約にソース、ワークフロー参照、パッケージ参照、バージョン、SHA-256、プロファイルを出力します。 -2. `docker_acceptance` は、`ref=workflow_ref` と `package_artifact_name=package-under-test` で `openclaw-live-and-e2e-checks-reusable.yml` を呼び出します。再利用可能ワークフローはそのアーティファクトをダウンロードし、tarball インベントリを検証し、必要に応じてパッケージダイジェスト Docker イメージを準備し、ワークフローチェックアウトをパックする代わりに、そのパッケージに対して選択された Docker レーンを実行します。プロファイルが複数の対象 `docker_lanes` を選択する場合、再利用可能ワークフローはパッケージと共有イメージを一度だけ準備し、それらのレーンを一意のアーティファクトを持つ並列の対象 Docker ジョブとしてファンアウトします。 -3. `package_telegram` は任意で `NPM Telegram Beta E2E` を呼び出します。これは `telegram_mode` が `none` ではない場合に実行され、Package Acceptance がパッケージを解決した場合は同じ `package-under-test` アーティファクトをインストールします。スタンドアロンの Telegram ディスパッチでは、公開済み npm spec を引き続きインストールできます。 +1. `resolve_package` は `workflow_ref` をチェックアウトし、1 つのパッケージ候補を解決し、`.artifacts/docker-e2e-package/openclaw-current.tgz` を書き込み、`.artifacts/docker-e2e-package/package-candidate.json` を書き込み、両方を `package-under-test` 成果物としてアップロードし、ソース、ワークフロー参照、パッケージ参照、バージョン、SHA-256、プロファイルを GitHub ステップ要約に出力します。 +2. `docker_acceptance` は、`ref=workflow_ref` と `package_artifact_name=package-under-test` で `openclaw-live-and-e2e-checks-reusable.yml` を呼び出します。再利用可能ワークフローはその成果物をダウンロードし、tarball インベントリを検証し、必要に応じてパッケージダイジェスト 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 受け入れ、または任意の Telegram レーンが失敗した場合にワークフローを失敗させます。 ### 候補ソース -- `source=npm` は、`openclaw@beta`、`openclaw@latest`、または `openclaw@2026.4.27-beta.2` のような正確な OpenClaw リリースバージョンのみを受け付けます。公開済みプレリリース/安定版の受け入れに使用します。 -- `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 リリースバージョンだけを受け付けます。公開済みプレリリース/安定版の受け入れに使用します。 +- `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`、`published-upgrade-survivor`、`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` のときに必須です +- `full` — OpenWebUI を含むフル Docker リリースパスチャンク +- `custom` — 正確な `docker_lanes`。`suite_profile=custom` の場合に必須 -`package` プロファイルはオフライン Plugin カバレッジを使用するため、公開済みパッケージの検証はライブ ClawHub の可用性に依存しません。任意の Telegram レーンは `NPM Telegram Beta E2E` で `package-under-test` アーティファクトを再利用し、公開済み npm spec パスはスタンドアロンディスパッチ用に維持されます。 +`package` プロファイルはオフライン Plugin カバレッジを使用するため、公開済みパッケージ検証がライブ ClawHub の可用性に左右されません。任意の Telegram レーンは、`NPM Telegram Beta E2E` で `package-under-test` 成果物を再利用します。公開済み npm spec パスは単独ディスパッチ用に維持されます。 -ローカルコマンド、Docker レーン、Package Acceptance 入力、リリースデフォルト、失敗トリアージを含む、専用の更新および Plugin テストポリシーについては、[更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins) を参照してください。 +専用の更新および Plugin テストポリシーには、ローカルコマンド、Docker レーン、Package Acceptance 入力、リリースデフォルト、失敗時のトリアージが含まれます。詳細は [更新とPluginのテスト](/ja-JP/help/testing-updates-plugins) を参照してください。 -リリースチェックは、準備済みリリースパッケージアーティファクト、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues`、`telegram_mode=mock-openai` とともに、`source=artifact` で Package Acceptance を呼び出します。これにより、パッケージ移行、更新、古い Plugin 依存関係のクリーンアップ、設定済み Plugin インストール修復、オフライン Plugin、Plugin 更新、Telegram の証明を、同じ解決済みパッケージ tarball 上に維持できます。Full Release Validation または OpenClaw Release Checks で `package_acceptance_package_spec` を設定すると、SHA からビルドされたアーティファクトの代わりに、出荷済み npm パッケージに対して同じマトリクスを実行できます。クロス OS リリースチェックは引き続き、OS 固有のオンボーディング、インストーラー、プラットフォーム動作をカバーします。パッケージ/更新の製品検証は Package Acceptance から開始するべきです。`published-upgrade-survivor` Docker レーンは、実行ごとに 1 つの公開済みパッケージベースラインを検証します。Package Acceptance では、解決済みの `package-under-test` tarball が常に候補であり、`published_upgrade_survivor_baseline` はフォールバックの公開済みベースラインを選択し、デフォルトは `openclaw@latest` です。失敗レーンの再実行コマンドはそのベースラインを保持します。`published_upgrade_survivor_baselines=all-since-2026.4.23` を設定すると、Full Release CI が `2026.4.23` から `latest` までのすべての安定版 npm リリースに拡張されます。`release-history` は、古い日付前アンカーを使った手動のより広いサンプリング用に引き続き利用できます。`published_upgrade_survivor_scenarios=reported-issues` を設定すると、同じベースラインが、Feishu 設定、保持されたブートストラップ/persona ファイル、設定済み OpenClaw Plugin インストール、チルダログパス、古いレガシー Plugin 依存関係ルートに関する issue 形状のフィクスチャ全体に拡張されます。別個の `Update Migration` ワークフローは、通常の Full Release CI の範囲ではなく、公開済み更新クリーンアップを網羅的に確認する問いに対して、`all-since-2026.4.23` と `plugin-deps-cleanup` を指定した `update-migration` Docker レーンを使用します。ローカル集約実行では、`OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` で正確なパッケージ spec を渡すことも、`OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` で `openclaw@2026.4.15` のような単一レーンを維持することも、`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` でシナリオマトリクスを設定することもできます。公開済みレーンは、焼き込み済みの `openclaw config set` コマンドレシピでベースラインを設定し、レシピ手順を `summary.json` に記録し、Gateway 起動後に `/healthz`、`/readyz`、および RPC ステータスをプローブします。Windows パッケージ済みレーンとインストーラー新規レーンも、インストール済みパッケージが生の絶対 Windows パスからブラウザー制御オーバーライドをインポートできることを検証します。OpenAI クロス OS エージェントターン smoke は、設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL`、それ以外の場合は `openai/gpt-5.4` をデフォルトにします。これにより、インストールと Gateway の証明を GPT-5 テストモデル上に維持しつつ、GPT-4.x デフォルトを避けられます。 +リリースチェックは、準備済みのリリースパッケージ成果物、`source=artifact`、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`telegram_mode=mock-openai` で Package Acceptance を呼び出します。これにより、パッケージ移行、更新、古い Plugin 依存関係のクリーンアップ、設定済み Plugin インストール修復、オフライン Plugin、Plugin 更新、Telegram の証明が、同じ解決済みパッケージ tarball 上で行われます。SHA からビルドされた成果物ではなく、出荷済み npm パッケージに対して同じマトリクスを実行するには、Full Release Validation または OpenClaw Release Checks で `package_acceptance_package_spec` を設定します。クロス OS リリースチェックは引き続き、OS 固有のオンボーディング、インストーラー、プラットフォーム動作をカバーします。パッケージ/更新の製品検証は Package Acceptance から始めるべきです。`published-upgrade-survivor` Docker レーンは、ブロッキングリリースパスで実行ごとに 1 つの公開済みパッケージベースラインを検証します。Package Acceptance では、解決された `package-under-test` tarball が常に候補であり、`published_upgrade_survivor_baseline` はフォールバックの公開済みベースラインを選択します。デフォルトは `openclaw@latest` です。失敗したレーンの再実行コマンドはそのベースラインを保持します。`run_release_soak=true` または `release_profile=full` の Full Release Validation は、`published_upgrade_survivor_baselines=all-since-2026.4.23` と `published_upgrade_survivor_scenarios=reported-issues` を設定し、`2026.4.23` から `latest` までのすべての安定版 npm リリースと、Feishu 設定、保持されたブートストラップ/persona ファイル、設定済み OpenClaw Plugin インストール、チルダログパス、古いレガシー Plugin 依存関係ルートに関する issue 形式のフィクスチャまで拡張します。別の `Update Migration` ワークフローは、通常の Full Release CI の広さではなく、公開済み更新クリーンアップを網羅的に確認することが目的の場合に、`all-since-2026.4.23` と `plugin-deps-cleanup` を伴う `update-migration` Docker レーンを使用します。ローカルの集約実行では、`OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` で正確なパッケージ spec を渡すことも、`openclaw@2026.4.15` のような `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` で単一レーンを維持することも、シナリオマトリクス用に `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` を設定することもできます。公開済みレーンは、組み込みの `openclaw config set` コマンドレシピでベースラインを設定し、レシピ手順を `summary.json` に記録し、Gateway 起動後に `/healthz`、`/readyz`、および RPC ステータスをプローブします。Windows のパッケージ化レーンとインストーラーの新規インストールレーンは、インストール済みパッケージが生の絶対 Windows パスから browser-control オーバーライドをインポートできることも検証します。OpenAI クロス OS エージェントターンスモークは、設定されている場合はデフォルトで `OPENCLAW_CROSS_OS_OPENAI_MODEL` を使用し、そうでない場合は `openai/gpt-5.4` を使用します。そのため、インストールと Gateway の証明は GPT-5 テストモデル上に維持され、GPT-4.x デフォルトを避けられます。 ### レガシー互換性ウィンドウ -Package Acceptance には、すでに公開済みのパッケージ向けに範囲を限定したレガシー互換性ウィンドウがあります。`2026.4.25-beta.*` を含む `2026.4.25` までのパッケージでは、互換性パスを使用できます。 +Package Acceptance には、すでに公開済みのパッケージに対する範囲限定のレガシー互換性ウィンドウがあります。`2026.4.25` までのパッケージ（`2026.4.25-beta.*` を含む）は、互換性パスを使用できます。 -- `dist/postinstall-inventory.json` 内の既知の非公開 QA エントリは、tarball から省略されたファイルを指していてもかまいません。 -- パッケージがそのフラグを公開していない場合、`doctor-switch` は `gateway install --wrapper` 永続化サブケースをスキップできます。 -- `update-channel-switch` は、tarball 由来の偽 git フィクスチャから欠落している `pnpm.patchedDependencies` を取り除いてもよく、永続化された `update.channel` の欠落をログに出してもかまいません。 -- Plugin smoke は、レガシーインストール記録の場所を読み取ったり、マーケットプレイスインストール記録の永続化欠落を許容したりできます。 -- `plugin-update` は、インストール記録と再インストールなしの動作が変わらないことを引き続き要求しつつ、設定メタデータ移行を許可できます。 +- `dist/postinstall-inventory.json` 内の既知の非公開 QA エントリは、tarball から省略されたファイルを指す場合があります。 +- パッケージがそのフラグを公開していない場合、`doctor-switch` は `gateway install --wrapper` 永続化サブケースをスキップする場合があります。 +- `update-channel-switch` は、tarball 由来の偽 git フィクスチャから存在しない `pnpm.patchedDependencies` を削除する場合があり、永続化された `update.channel` が存在しないことをログに記録する場合があります。 +- Plugin スモークは、レガシーのインストール記録場所を読む場合や、マーケットプレイスのインストール記録永続化がないことを許容する場合があります。 +- `plugin-update` は、インストール記録と再インストールなしの動作が変わらないことを引き続き要求しつつ、設定メタデータ移行を許可する場合があります。 -公開済みの `2026.4.26` パッケージでも、すでに出荷済みのローカルビルドメタデータスタンプファイルについて警告を出してもかまいません。それ以降のパッケージは現代的な契約を満たす必要があります。同じ条件は、警告やスキップではなく失敗になります。 +公開済みの `2026.4.26` パッケージでも、すでに出荷済みのローカルビルドメタデータスタンプファイルについて警告する場合があります。それ以降のパッケージは現代の契約を満たす必要があります。同じ条件は、警告やスキップではなく失敗になります。 ### 例 @@ -304,60 +304,60 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -失敗したパッケージ受け入れ実行をデバッグするときは、まず `resolve_package` サマリーでパッケージソース、バージョン、SHA-256 を確認します。次に `docker_acceptance` 子実行とその Docker アーティファクトを調べます: `.artifacts/docker-tests/**/summary.json`、`failures.json`、レーンログ、フェーズタイミング、再実行コマンド。完全なリリース検証を再実行するのではなく、失敗したパッケージプロファイルまたは正確な Docker レーンを再実行することを優先してください。 +失敗したパッケージ受け入れ実行をデバッグするときは、`resolve_package` サマリーから始めて、パッケージソース、バージョン、SHA-256 を確認します。次に `docker_acceptance` 子実行とその Docker アーティファクトを調べます: `.artifacts/docker-tests/**/summary.json`、`failures.json`、レーンログ、フェーズタイミング、再実行コマンド。完全なリリース検証を再実行するのではなく、失敗したパッケージプロファイルまたは正確な Docker レーンを再実行することを優先します。 ## インストールスモーク -別個の `Install Smoke` ワークフローは、独自の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。スモークカバレッジを `run_fast_install_smoke` と `run_full_install_smoke` に分割します。 +別の `Install Smoke` ワークフローは、独自の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。スモークカバレッジを `run_fast_install_smoke` と `run_full_install_smoke` に分割します。 -- **高速パス** は、Docker/パッケージ面、バンドル済み Plugin パッケージ/マニフェスト変更、または Docker スモークジョブが実行するコア Plugin/チャネル/Gateway/Plugin SDK 面に触れるプルリクエストで実行されます。ソースのみのバンドル済み Plugin 変更、テストのみの編集、ドキュメントのみの編集は Docker ワーカーを予約しません。高速パスはルート Dockerfile イメージを一度ビルドし、CLI をチェックし、agents delete 共有ワークスペース CLI スモークを実行し、コンテナ gateway-network e2e を実行し、バンドル済み拡張機能のビルド引数を検証し、240 秒の集約コマンドタイムアウト内で境界付きバンドル済み Plugin Docker プロファイルを実行します（各シナリオの Docker 実行は個別に上限設定されます）。 -- **完全パス** は、毎晩のスケジュール実行、手動ディスパッチ、workflow-call リリースチェック、そしてインストーラー/パッケージ/Docker 面に実際に触れるプルリクエスト向けに、QR パッケージインストールとインストーラー Docker/更新カバレッジを保持します。完全モードでは、install-smoke はターゲット SHA の GHCR ルート Dockerfile スモークイメージを 1 つ準備または再利用し、その後 QR パッケージインストール、ルート Dockerfile/Gateway スモーク、インストーラー/更新スモーク、高速バンドル済み Plugin Docker E2E を別々のジョブとして実行するため、インストーラー作業がルートイメージスモークの後ろで待つことはありません。 +- **高速パス** は、Docker/パッケージサーフェス、バンドル済みPluginパッケージ/マニフェスト変更、または Docker スモークジョブが実行するコアPlugin/チャネル/Gateway/Plugin SDK サーフェスに触れるプルリクエストで実行されます。ソースのみのバンドル済みPlugin変更、テストのみの編集、docsのみの編集では Docker ワーカーを予約しません。高速パスはルート Dockerfile イメージを一度ビルドし、CLI をチェックし、agents delete 共有ワークスペース CLI スモークを実行し、コンテナ gateway-network e2e を実行し、バンドル済み拡張機能のビルド引数を検証し、240 秒の集約コマンドタイムアウト内で境界付きのバンドル済みPlugin Docker プロファイルを実行します（各シナリオの Docker 実行は個別に上限設定されます）。 +- **フルパス** は、夜間スケジュール実行、手動ディスパッチ、workflow-call リリースチェック、およびインストーラー/パッケージ/Docker サーフェスに実際に触れるプルリクエスト向けに、QR パッケージインストールとインストーラー Docker/update カバレッジを維持します。フルモードでは、install-smoke は 1 つのターゲット SHA GHCR ルート Dockerfile スモークイメージを準備または再利用し、その後 QR パッケージインストール、ルート Dockerfile/Gateway スモーク、インストーラー/update スモーク、高速バンドル済みPlugin Docker E2E を別々のジョブとして実行するため、インストーラー作業がルートイメージスモークの後ろで待つことはありません。 -`main` へのプッシュ（マージコミットを含む）は完全パスを強制しません。変更スコープロジックがプッシュで完全カバレッジを要求する場合、ワークフローは高速 Docker スモークを維持し、完全インストールスモークは nightly またはリリース検証に任せます。 +`main` へのプッシュ（マージコミットを含む）はフルパスを強制しません。変更スコープロジックがプッシュでフルカバレッジを要求する場合、ワークフローは高速 Docker スモークを維持し、フルインストールスモークは夜間またはリリース検証に残します。 -遅い Bun グローバルインストール image-provider スモークは `run_bun_global_install_smoke` によって別途ゲートされます。これは nightly スケジュールとリリースチェックワークフローから実行され、手動の `Install Smoke` ディスパッチでも任意で有効にできますが、プルリクエストと `main` プッシュでは実行されません。QR とインストーラー Docker テストは、それぞれインストールに焦点を当てた Dockerfile を保持します。 +遅い Bun グローバルインストール image-provider スモークは、`run_bun_global_install_smoke` によって別途ゲートされます。これは夜間スケジュールとリリースチェックワークフローから実行され、手動の `Install Smoke` ディスパッチではオプトインできますが、プルリクエストと `main` プッシュでは実行されません。QR とインストーラー Docker テストは、それぞれインストールに特化した Dockerfile を維持します。 ## ローカル Docker E2E -`pnpm test:docker:all` は共有 live-test イメージを 1 つ事前ビルドし、OpenClaw を npm tarball として一度パックし、共有の `scripts/e2e/Dockerfile` イメージを 2 つビルドします。 +`pnpm test:docker:all` は、共有ライブテストイメージを 1 つ事前ビルドし、OpenClaw を npm tarball として一度パックし、2 つの共有 `scripts/e2e/Dockerfile` イメージをビルドします。 -- インストーラー/更新/Plugin 依存関係レーン用の素の Node/Git ランナー。 -- 通常の機能レーン用に同じ tarball を `/app` にインストールする機能イメージ。 +- インストーラー/update/plugin-dependency レーン向けの素の Node/Git runner。 +- 通常の機能レーン向けに、同じ tarball を `/app` にインストールする機能イメージ。 -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` にあり、runner は選択されたプランのみを実行します。スケジューラーは `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 | プロバイダーに敏感なテールプールのスロット数。 | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | プロバイダーがスロットリングしないようにする同時 live レーン上限。 | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 同時 npm install レーン上限。 | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 通常レーン用メインプールのスロット数。 | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | プロバイダー影響を受けやすいテールプールのスロット数。 | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | プロバイダーがスロットリングしないようにする同時ライブレーン上限。 | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 同時 npm インストールレーン上限。 | | `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 同時マルチサービスレーン上限。 | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Docker デーモンの create 集中を避けるためのレーン開始間隔。間隔なしにするには `0` を設定します。 | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | レーンごとのフォールバックタイムアウト（120 分）。選択された live/tail レーンはより厳しい上限を使用します。 | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Docker デーモンの作成ストームを避けるためのレーン開始間隔。間隔なしにするには `0` を設定。 | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | レーンごとのフォールバックタイムアウト（120 分）。選択された live/tail レーンはより厳しい上限を使用。 | | `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` はレーンを実行せずにスケジューラープランを出力します。 | -| `OPENCLAW_DOCKER_ALL_LANES` | unset | カンマ区切りの正確なレーンリスト。エージェントが失敗した 1 つのレーンを再現できるよう、クリーンアップスモークをスキップします。 | +| `OPENCLAW_DOCKER_ALL_LANES` | unset | カンマ区切りの正確なレーンリスト。クリーンアップスモークをスキップし、agents が 1 つの失敗レーンを再現できるようにします。 | -実効上限より重いレーンでも、空のプールから開始でき、その後キャパシティを解放するまで単独で実行されます。ローカル集約は Docker を事前チェックし、古い OpenClaw E2E コンテナを削除し、アクティブレーン状態を出力し、最長優先の順序付け用にレーンタイミングを永続化し、デフォルトでは最初の失敗後に新しいプール済みレーンのスケジュールを停止します。 +有効上限より重いレーンでも、空のプールから開始でき、その後は容量を解放するまで単独で実行されます。ローカル集約は Docker を事前チェックし、古い OpenClaw E2E コンテナを削除し、アクティブレーン状態を出力し、最長優先順序のためにレーンタイミングを保存し、デフォルトでは最初の失敗後に新しいプール済みレーンのスケジューリングを停止します。 ### 再利用可能な live/E2E ワークフロー -再利用可能な live/E2E ワークフローは、必要なパッケージ、イメージ種別、live イメージ、レーン、認証情報カバレッジを `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 秒の境界付きタイムアウトでリトライされるため、停止したレジストリ/キャッシュストリームが CI クリティカルパスの大半を消費するのではなく、すばやくリトライされます。 +再利用可能な live/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 秒の境界付きタイムアウトでリトライされるため、停止したレジストリ/キャッシュストリームが CI クリティカルパスの大半を消費するのではなく、すばやくリトライされます。 -### リリースパスチャンク +### リリースパスのチャンク -リリース Docker カバレッジは `OPENCLAW_SKIP_DOCKER_BUILD=1` を使って小さなチャンク化ジョブで実行されるため、各チャンクは必要なイメージ種別のみを 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` -現在のリリース 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` です。`plugins-runtime-core`、`plugins-runtime`、`plugins-integrations` は集約 Plugin/runtime エイリアスのままです。`install-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-h` までです。`plugins-runtime-core`、`plugins-runtime`、`plugins-integrations` は集約Plugin/runtime エイリアスのままです。`install-e2e` レーンエイリアスは、両方のプロバイダーインストーラーレーン向けの集約手動再実行エイリアスのままです。 -OpenWebUI は完全な release-path カバレッジが要求する場合に `plugins-runtime-services` に折り込まれ、OpenWebUI のみのディスパッチ向けにだけスタンドアロンの `openwebui` チャンクを保持します。バンドル済みチャネル更新レーンは、一時的な npm ネットワーク失敗に対して一度リトライします。 +フル release-path カバレッジが要求した場合、OpenWebUI は `plugins-runtime-services` に含まれ、OpenWebUI のみのディスパッチ向けにだけスタンドアロンの `openwebui` チャンクを維持します。バンドル済みチャネル update レーンは、一時的な npm ネットワーク障害に対して一度リトライします。 -各チャンクは、レーンログ、タイミング、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、低速レーン表、レーンごとの再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。ワークフローの `docker_lanes` 入力は、チャンクジョブの代わりに準備済みイメージに対して選択したレーンを実行します。これにより、失敗レーンのデバッグは対象を絞った 1 つの Docker ジョブに限定され、その実行用にパッケージアーティファクトを準備、ダウンロード、または再利用します。選択したレーンが live Docker レーンの場合、対象ジョブはその再実行用に live-test イメージをローカルでビルドします。生成されるレーンごとの GitHub 再実行コマンドには、それらの値が存在する場合、`package_artifact_run_id`、`package_artifact_name`、準備済みイメージ入力が含まれるため、失敗したレーンは失敗した実行の正確なパッケージとイメージを再利用できます。 +各チャンクは、レーンログ、タイミング、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、遅いレーンのテーブル、レーンごとの再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。ワークフローの `docker_lanes` 入力は、チャンクジョブの代わりに準備済みイメージに対して選択されたレーンを実行します。これにより、失敗レーンのデバッグは 1 つの対象 Docker ジョブに限定され、その実行用のパッケージアーティファクトを準備、ダウンロード、または再利用します。選択されたレーンが live Docker レーンの場合、対象ジョブはその再実行用にライブテストイメージをローカルでビルドします。生成されるレーンごとの GitHub 再実行コマンドには、それらの値が存在する場合、`package_artifact_run_id`、`package_artifact_name`、準備済みイメージ入力が含まれるため、失敗したレーンは失敗した実行から正確なパッケージとイメージを再利用できます。 ```bash pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands @@ -368,46 +368,46 @@ pnpm test:docker:timings # slow-lane and phase critical-path summari ## Plugin プレリリース -`Plugin Prerelease` はより高コストな製品/パッケージカバレッジであるため、`Full Release Validation` または明示的なオペレーターによってディスパッチされる別個のワークフローです。通常のプルリクエスト、`main` プッシュ、スタンドアロンの手動 CI ディスパッチでは、そのスイートはオフのままです。これはバンドル済み Plugin テストを 8 つの拡張機能ワーカーに分散します。それらの拡張機能シャードジョブは、一度に最大 2 つの Plugin 設定グループを実行し、各グループにつき Vitest ワーカー 1 つとより大きな Node ヒープを使用するため、import が重い Plugin バッチが追加の CI ジョブを作成しません。リリース専用 Docker プレリリースパスは、1〜3 分のジョブのために多数のランナーを予約しないよう、対象 Docker レーンを小さなグループにまとめます。 +`Plugin Prerelease` はより高コストな製品/パッケージカバレッジであるため、`Full Release Validation` または明示的なオペレーターによってディスパッチされる別のワークフローです。通常のプルリクエスト、`main` プッシュ、スタンドアロンの手動 CI ディスパッチでは、そのスイートはオフのままです。これはバンドル済みPluginテストを 8 つの拡張機能ワーカーに分散します。これらの拡張機能シャードジョブは、グループごとに 1 つの Vitest ワーカーとより大きな Node ヒープを使って、最大 2 つのPlugin設定グループを同時に実行するため、import の重いPluginバッチが追加の CI ジョブを作成しません。リリース専用の Docker プレリリースパスは、1〜3 分のジョブのために何十もの runner を予約しないように、対象 Docker レーンを小さなグループでバッチ処理します。 -## QA Lab +## QA ラボ -QA Lab には、メインのスマートスコープワークフローの外側に専用の CI レーンがあります。エージェント的パリティは、スタンドアロンの PR ワークフローではなく、広範な QA とリリースハーネスの下にネストされています。パリティを広範な検証実行に載せる必要がある場合は、`rerun_group=qa-parity` を指定して `Full Release Validation` を使用します。 +QA ラボには、メインのスマートスコープワークフローの外に専用の CI レーンがあります。Agentic parity は広範な QA とリリースハーネスの下にネストされており、スタンドアロンの PR ワークフローではありません。parity を広範な検証実行に載せる必要がある場合は、`rerun_group=qa-parity` を指定して `Full Release Validation` を使用します。 -- `QA-Lab - All Lanes` ワークフローは nightly に `main` 上で、および手動ディスパッチで実行されます。これは mock parity レーン、live Matrix レーン、live Telegram と Discord レーンを並列ジョブとして展開します。live ジョブは `qa-live-shared` 環境を使用し、Telegram/Discord は Convex leases を使用します。 +- `QA-Lab - All Lanes` ワークフローは、`main` で夜間および手動ディスパッチ時に実行されます。mock parity レーン、live Matrix レーン、live Telegram および Discord レーンを並列ジョブとしてファンアウトします。live ジョブは `qa-live-shared` 環境を使用し、Telegram/Discord は Convex lease を使用します。 -リリースチェックは、決定的な mock プロバイダーと mock 修飾モデル（`mock-openai/gpt-5.5` と `mock-openai/gpt-5.5-alt`）を使って Matrix と Telegram の live transport レーンを実行するため、チャネル契約は live モデルのレイテンシと通常のプロバイダー Plugin 起動から分離されます。QA パリティがメモリ動作を別途カバーするため、live transport Gateway はメモリ検索を無効にします。プロバイダー接続性は、別個の live モデル、ネイティブプロバイダー、Docker プロバイダースイートによってカバーされます。 +リリースチェックは、決定論的な mock プロバイダーと mock-qualified モデル（`mock-openai/gpt-5.5` と `mock-openai/gpt-5.5-alt`）で Matrix と Telegram live transport レーンを実行するため、チャネル契約は live モデルのレイテンシや通常の provider-plugin 起動から分離されます。live transport gateway は、QA parity がメモリ動作を別途カバーするため、メモリ検索を無効にします。プロバイダー接続性は、別の 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` ディスパッチは、常に完全な Matrix カバレッジを `transport`、`media`、`e2ee-smoke`、`e2ee-deep`、`e2ee-cli` ジョブにシャードします。 -`OpenClaw Release Checks` はリリース承認前にリリースクリティカルな QA Lab レーンも実行します。その QA パリティゲートは候補パックとベースラインパックを並列レーンジョブとして実行し、その後最終的なパリティ比較のために両方のアーティファクトを小さなレポートジョブへダウンロードします。 +`OpenClaw Release Checks` はリリース承認前にリリースクリティカルな QA ラボレーンも実行します。その QA parity ゲートは candidate と baseline のパックを並列レーンジョブとして実行し、その後最終 parity 比較用の小さなレポートジョブに両方のアーティファクトをダウンロードします。 -通常の PR では、パリティを必須ステータスとして扱うのではなく、スコープ化された CI/チェック証拠に従ってください。 +通常の PR では、parity を必須ステータスとして扱うのではなく、スコープされた CI/check 証拠に従います。 ## CodeQL -`CodeQL` ワークフローは、リポジトリ全体のスイープではなく、意図的に絞り込んだ初回パスのセキュリティスキャナーです。毎日、手動、およびドラフトでないプルリクエストのガード実行では、Actions ワークフローコードに加えて、高リスクの JavaScript/TypeScript サーフェスを、高/重大の `security-severity` に絞り込んだ高信頼度のセキュリティクエリでスキャンします。 +`CodeQL` ワークフローは、リポジトリ全体のスイープではなく、意図的に範囲を絞った初回パスのセキュリティスキャナーです。毎日、手動、およびドラフトでないプルリクエストのガード実行では、Actions ワークフローコードに加え、最もリスクの高い JavaScript/TypeScript サーフェスを、高/重大の `security-severity` にフィルターされた高信頼度のセキュリティクエリでスキャンします。 -プルリクエストガードは軽量に保たれます。`.github/actions`、`.github/codeql`、`.github/workflows`、`packages`、または `src` 配下の変更でのみ開始し、スケジュール済みワークフローと同じ高信頼度のセキュリティマトリックスを実行します。Android と macOS の CodeQL は、PR のデフォルトには含めません。 +プルリクエストガードは軽量に保たれます。`.github/actions`、`.github/codeql`、`.github/workflows`、`packages`、または `src` 配下の変更に対してのみ開始され、スケジュールされたワークフローと同じ高信頼度セキュリティマトリックスを実行します。Android と macOS の CodeQL は PR のデフォルトから除外されています。 ### セキュリティカテゴリ | カテゴリ | サーフェス | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `/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 フェッチ、Plugin SDK の SSRF ポリシーサーフェス | -| `/codeql-security-high/mcp-process-tool-boundary` | MCP サーバー、プロセス実行ヘルパー、アウトバウンド配信、エージェントのツール実行ゲート | -| `/codeql-security-high/plugin-trust-boundary` | Plugin インストール、ローダー、マニフェスト、レジストリ、パッケージマネージャーのインストール、ソース読み込み、Plugin SDK パッケージ契約の信頼サーフェス | +| `/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 インストール、ローダー、マニフェスト、レジストリ、パッケージマネージャーインストール、ソース読み込み、および Plugin SDK パッケージコントラクトの信頼サーフェス | ### プラットフォーム固有のセキュリティシャード -- `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 セキュリティシャード。ワークフロー健全性で許容される最小の Blacksmith Linux ランナー上で、CodeQL 用に Android アプリを手動でビルドします。`/codeql-critical-security/android` 配下にアップロードします。 +- `CodeQL macOS Critical Security` — 週次/手動の macOS セキュリティシャード。Blacksmith macOS 上で CodeQL 用に macOS アプリを手動でビルドし、依存関係ビルド結果をアップロード対象の SARIF から除外して、`/codeql-critical-security/macos` 配下にアップロードします。クリーンな場合でも macOS ビルドが実行時間を支配するため、毎日のデフォルトからは除外されています。 ### 重大品質カテゴリ -`CodeQL Critical Quality` は、対応する非セキュリティシャードです。小さめの Blacksmith Linux ランナー上で、狭い高価値サーフェスに対して、エラー重大度のみの非セキュリティ JavaScript/TypeScript 品質クエリを実行します。このプルリクエストガードは、スケジュール済みプロファイルより意図的に小さくしています。ドラフトでない PR では、エージェントのコマンド/モデル/ツール実行と返信ディスパッチコード、設定スキーマ/マイグレーション/IO コード、認証/シークレット/サンドボックス/セキュリティコード、コアチャネルとバンドル済みチャネル Plugin ランタイム、Gateway プロトコル/サーバーメソッド、メモリランタイム/SDK 接着部、MCP/プロセス/アウトバウンド配信、プロバイダーランタイム/モデルカタログ、セッション診断/配信キュー、Plugin ローダー、Plugin SDK/パッケージ契約、または 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` は対応する非セキュリティシャードです。小さめの Blacksmith Linux ランナー上で、範囲を絞った高価値サーフェスに対し、エラー重大度のみの非セキュリティ JavaScript/TypeScript 品質クエリを実行します。そのプルリクエストガードはスケジュールプロファイルより意図的に小さくなっています。ドラフトでない PR では、エージェントのコマンド/モデル/ツール実行と返信ディスパッチコード、設定スキーマ/移行/IO コード、認証/シークレット/サンドボックス/セキュリティコード、コアチャンネルと同梱チャンネル Plugin ランタイム、gateway プロトコル/サーバーメソッド、メモリランタイム/SDK 接着部、MCP/プロセス/アウトバウンド配信、プロバイダーランタイム/モデルカタログ、セッション診断/配信キュー、Plugin ローダー、Plugin SDK/パッケージコントラクト、または 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 品質シャードを実行します。 手動ディスパッチは次を受け付けます。 @@ -415,40 +415,40 @@ Matrix はスケジュール済みゲートとリリースゲートで `--profil 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 つの品質シャードを単独で実行するための学習/反復用フックです。 | カテゴリ | サーフェス | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/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/検索/フェッチ/埋め込みレジストリ | -| `/codeql-critical-quality/ui-control-plane` | Control UI ブートストラップ、ローカル永続化、Gateway 制御フロー、タスクコントロールプレーンのランタイム契約 | -| `/codeql-critical-quality/web-media-runtime-boundary` | コア Web フェッチ/検索、メディア IO、メディア理解、画像生成、メディア生成ランタイム契約 | -| `/codeql-critical-quality/plugin-boundary` | ローダー、レジストリ、公開サーフェス、Plugin SDK エントリーポイント契約 | -| `/codeql-critical-quality/plugin-sdk-package-contract` | 公開パッケージ側の Plugin SDK ソースと Plugin パッケージ契約ヘルパー | +| `/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 パッケージコントラクトヘルパー | -品質はセキュリティと分離したままにします。これにより、品質の検出結果を、セキュリティシグナルを不明瞭にすることなく、スケジュール、測定、無効化、または拡張できます。Swift、Python、バンドル済み Plugin の CodeQL 拡張は、狭いプロファイルの実行時間とシグナルが安定した後でのみ、スコープ指定またはシャード化されたフォローアップ作業として戻すべきです。 +品質はセキュリティとは分離されています。これにより、品質の検出結果をスケジュール、測定、無効化、または拡張しても、セキュリティシグナルが不明瞭になりません。Swift、Python、および同梱 Plugin の CodeQL 拡張は、狭いプロファイルの実行時間とシグナルが安定してから、範囲指定またはシャード化されたフォローアップ作業としてのみ追加し直すべきです。 ## メンテナンスワークフロー -### Docs Agent +### ドキュメントエージェント -`Docs Agent` ワークフローは、最近取り込まれた変更に既存ドキュメントを合わせ続けるための、イベント駆動の Codex メンテナンスレーンです。純粋なスケジュールはありません。`main` への bot 以外の push CI 実行が成功するとトリガーでき、手動ディスパッチでも直接実行できます。ワークフロー実行による呼び出しは、`main` がすでに進んでいる場合、または過去 1 時間以内にスキップされていない別の Docs Agent 実行が作成されている場合はスキップします。実行時には、前回のスキップされていない Docs Agent ソース SHA から現在の `main` までのコミット範囲をレビューするため、1 時間ごとの 1 回の実行で、前回のドキュメントパス以降に蓄積したすべての 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 を再試行します。競合する古いパッチはスキップされます。Codex アクションがドキュメントエージェントと同じ drop-sudo 安全姿勢を維持できるよう、GitHub ホストの Ubuntu を使用します。 ### マージ後の重複 PR -`Duplicate PRs After Merge` ワークフローは、取り込み後の重複クリーンアップのための手動メンテナーワークフローです。デフォルトはドライランで、`apply=true` の場合にのみ明示的に列挙された PR を閉じます。GitHub を変更する前に、取り込まれた PR がマージ済みであること、および各重複 PR に共有された参照 Issue があるか、変更された hunk が重なっていることを検証します。 +`Duplicate PRs After Merge` ワークフローは、land 後の重複クリーンアップ用の手動メンテナーワークフローです。デフォルトは dry-run で、`apply=true` の場合にのみ明示的に列挙された PR を閉じます。GitHub を変更する前に、land 済み PR がマージ済みであること、および各重複に共有された参照 Issue または重複する変更ハンクのどちらかがあることを検証します。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -459,35 +459,35 @@ gh workflow run duplicate-after-merge.yml \ ## ローカルチェックゲートと変更ルーティング -ローカルの変更レーンロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。このローカルチェックゲートは、広範な CI プラットフォームスコープよりもアーキテクチャ境界に厳格です。 +ローカルの changed-lane ロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。そのローカルチェックゲートは、広範な CI プラットフォームスコープよりもアーキテクチャ境界に厳格です。 -- コア本番変更は、コア本番とコアテストの型チェックに加え、コア lint/ガードを実行します。 -- コアのテストのみの変更は、コアテストの型チェックに加え、コア lint のみを実行します。 -- 拡張の本番変更は、拡張本番と拡張テストの型チェックに加え、拡張 lint を実行します。 -- 拡張のテストのみの変更は、拡張テストの型チェックに加え、拡張 lint を実行します。 -- 公開 Plugin SDK または Plugin 契約の変更は、拡張がそれらのコア契約に依存するため、拡張の型チェックへ拡張されます（Vitest 拡張スイープは明示的なテスト作業のままです）。 -- リリースメタデータのみのバージョンバンプは、対象を絞ったバージョン/設定/ルート依存関係チェックを実行します。 -- 不明なルート/設定変更は、安全側に倒してすべてのチェックレーンを実行します。 +- コア本番変更では、コア本番とコアテストの型チェックに加え、コア lint/guards を実行します。 +- コアのテストのみの変更では、コアテストの型チェックに加え、コア lint のみを実行します。 +- 拡張機能本番変更では、拡張機能本番と拡張機能テストの型チェックに加え、拡張機能 lint を実行します。 +- 拡張機能のテストのみの変更では、拡張機能テストの型チェックに加え、拡張機能 lint を実行します。 +- 公開 Plugin SDK または Plugin コントラクトの変更では、拡張機能がそれらのコアコントラクトに依存しているため、拡張機能の型チェックまで拡張されます（Vitest 拡張機能スイープは明示的なテスト作業のままです）。 +- リリースメタデータのみのバージョンバンプでは、対象を絞ったバージョン/設定/ルート依存関係チェックを実行します。 +- 不明なルート/設定変更は、安全側に倒してすべてのチェックレーンに失敗します。 -ローカルの変更テストルーティングは `scripts/test-projects.test-support.mjs` にあり、意図的に `check:changed` より安価です。直接のテスト編集はそのテスト自体を実行し、ソース編集は明示的なマッピングを優先し、その後に兄弟テストとインポートグラフ上の依存先を使います。共有グループルーム配信設定は明示的なマッピングの 1 つです。グループの表示返信設定、ソース返信配信モード、または message-tool システムプロンプトへの変更は、コア返信テストに加え、Discord と Slack の配信回帰を経由します。これにより、共有デフォルトの変更は最初の PR push の前に失敗します。変更がハーネス全体に及ぶほど広く、安価なマップ済みセットを信頼できる代理と見なせない場合にのみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 +ローカルの changed-test ルーティングは `scripts/test-projects.test-support.mjs` にあり、意図的に `check:changed` より低コストです。直接のテスト編集はそのテスト自体を実行し、ソース編集は明示的なマッピング、次に兄弟テストと import グラフ依存先を優先します。共有グループルーム配信設定は明示的なマッピングの 1 つです。グループの visible-reply 設定、ソース返信配信モード、または message-tool システムプロンプトへの変更は、コア返信テストに加えて Discord と Slack の配信回帰を経由するため、共有デフォルト変更は最初の PR push 前に失敗します。変更がハーネス全体に及ぶほど広く、低コストにマッピングされた集合が信頼できる代替にならない場合にのみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 ## Testbox 検証 -広範な証明には、リポジトリルートから Testbox を実行し、新しくウォーム済みのボックスを優先します。再利用された、期限切れになった、または予想外に大きな同期を報告したばかりのボックスで遅いゲートに時間を使う前に、まずボックス内で `pnpm testbox:sanity` を実行してください。 +リポジトリルートから Testbox を実行し、広範な検証には新しくウォームアップしたボックスを優先する。再利用された、期限切れになった、または想定外に大きな同期を報告したボックスで遅いゲートを使う前に、まずそのボックス内で `pnpm testbox:sanity` を実行する。 -サニティチェックは、`pnpm-lock.yaml` などの必須ルートファイルが消えた場合、または `git status --short` が 200 件以上の追跡済み削除を示す場合にすばやく失敗します。これは通常、リモート同期状態が PR の信頼できるコピーではないことを意味します。製品テストの失敗をデバッグするのではなく、そのボックスを停止して新しいボックスをウォームしてください。意図的な大量削除 PR では、そのサニティ実行に `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` を設定します。 +健全性チェックは、`pnpm-lock.yaml` など必須のルートファイルが消えた場合、または `git status --short` が少なくとも 200 件の追跡済み削除を示す場合に高速に失敗する。これは通常、リモート同期状態が PR の信頼できるコピーではないことを意味するため、プロダクトテストの失敗をデバッグするのではなく、そのボックスを停止して新しいものをウォームアップする。意図的な大量削除 PR では、その健全性実行に `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` を設定する。 -`pnpm testbox:run` は、同期後の出力がないまま同期フェーズに 5 分を超えて留まるローカル Blacksmith CLI 呼び出しも終了します。そのガードを無効にするには `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` を設定し、異常に大きなローカル差分にはより大きなミリ秒値を使用してください。 +`pnpm testbox:run` は、同期後の出力がないまま同期フェーズに 5 分を超えて留まるローカル Blacksmith CLI 呼び出しも終了する。このガードを無効化するには `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` を設定し、通常より大きいローカル差分にはより大きいミリ秒値を使う。 -Crabbox は、メンテナーの Linux 証明向けにリポジトリが所有するリモートボックスラッパーです。チェックがローカル編集ループには広すぎる場合、CI との同等性が重要な場合、または証明にシークレット、Docker、パッケージレーン、再利用可能なボックス、リモートログが必要な場合に使用します。通常の OpenClaw バックエンドは `blacksmith-testbox` です。所有 AWS/Hetzner 容量は、Blacksmith の障害、クォータ問題、または明示的な所有容量テストのためのフォールバックです。 +Crabbox は、メンテナーの Linux 検証用にリポジトリが所有するリモートボックスラッパーである。チェックがローカル編集ループには広すぎる場合、CI との同等性が重要な場合、または検証にシークレット、Docker、パッケージレーン、再利用可能なボックス、リモートログが必要な場合に使用する。通常の OpenClaw バックエンドは `blacksmith-testbox` であり、所有する AWS/Hetzner 容量は Blacksmith の障害、クォータ問題、または明示的な所有容量テストのフォールバックである。 -初回実行の前に、リポジトリルートからラッパーを確認します。 +初回実行の前に、リポジトリルートからラッパーを確認する。 ```bash pnpm crabbox:run -- --help | sed -n '1,120p' ``` -リポジトリラッパーは、`blacksmith-testbox` を通知しない古い Crabbox バイナリを拒否します。`.crabbox.yaml` に所有クラウドのデフォルトがあっても、プロバイダーは明示的に渡してください。 +リポジトリラッパーは、`blacksmith-testbox` を公開していない古い Crabbox バイナリを拒否する。`.crabbox.yaml` に所有クラウドのデフォルトがあっても、プロバイダーを明示的に渡す。 変更ゲート: @@ -504,7 +504,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" ``` -絞り込んだテストの再実行: +対象を絞ったテスト再実行: ```bash pnpm crabbox:run -- --provider blacksmith-testbox \ @@ -534,21 +534,21 @@ pnpm crabbox:run -- --provider blacksmith-testbox \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test" ``` -最終 JSON サマリーを読んでください。有用なフィールドは `provider`、`leaseId`、`syncDelegated`、`exitCode`、`commandMs`、`totalMs` です。Blacksmith をバックエンドにした単発の Crabbox 実行では、Testbox は自動的に停止するはずです。実行が中断された、またはクリーンアップが不明確な場合は、稼働中のボックスを調べ、自分が作成したボックスだけを停止してください。 +最終 JSON サマリーを読む。有用なフィールドは `provider`、`leaseId`、`syncDelegated`、`exitCode`、`commandMs`、`totalMs` である。1 回限りの Blacksmith ベースの Crabbox 実行は Testbox を自動的に停止するはずである。実行が中断された場合、またはクリーンアップが不明な場合は、稼働中のボックスを調べ、自分が作成したボックスだけを停止する。 ```bash blacksmith testbox list blacksmith testbox stop --id ``` -同じハイドレート済みボックスで複数のコマンドを意図的に実行する必要がある場合にのみ、再利用を使います。 +同じハイドレート済みボックスで複数のコマンドが意図的に必要な場合にのみ、再利用を使う。 ```bash pnpm crabbox:run -- --provider blacksmith-testbox --id --no-sync --timing-json --shell -- "pnpm test " pnpm crabbox:stop -- ``` -Crabbox が壊れている層で、Blacksmith 自体は動作している場合は、狭いフォールバックとして直接 Blacksmith を使用します。 +Crabbox 層が壊れているが Blacksmith 自体は動作する場合は、限定的なフォールバックとして直接 Blacksmith を使う。 ```bash blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 @@ -556,7 +556,7 @@ blacksmith testbox run --id "env CI=1 NODE_OPTIONS=--max-old-space-size blacksmith testbox stop --id ``` -Blacksmith がダウンしている、クォータ制限がある、必要な環境がない、または所有容量そのものが明示的な目的である場合にのみ、所有 Crabbox 容量へエスカレーションします。 +Blacksmith が停止している、クォータ制限がある、必要な環境が欠けている、または所有容量自体が明示的な目的である場合にのみ、所有 Crabbox 容量へエスカレーションする。 ```bash pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m @@ -565,9 +565,9 @@ pnpm crabbox:run -- --id --timing-json --shell -- "env NODE_OPT pnpm crabbox:stop -- ``` -`.crabbox.yaml` は、所有クラウドレーンのプロバイダー、同期、GitHub Actions ハイドレーションのデフォルトを管理します。ローカル `.git` は除外されるため、ハイドレートされた Actions チェックアウトは、メンテナーのローカルリモートやオブジェクトストアを同期するのではなく、独自のリモート Git メタデータを保持します。また、転送されるべきでないローカル実行時/ビルド成果物も除外されます。`.github/workflows/crabbox-hydrate.yml` は、チェックアウト、Node/pnpm セットアップ、`origin/main` フェッチ、および所有クラウドの `crabbox run --id ` コマンド向けの非シークレット環境の引き渡しを管理します。 +`.crabbox.yaml` は、所有クラウドレーンのプロバイダー、同期、GitHub Actions ハイドレーションのデフォルトを所有する。これはローカルの `.git` を除外するため、ハイドレートされた Actions チェックアウトはメンテナーローカルのリモートとオブジェクトストアを同期する代わりに、自身のリモート Git メタデータを保持する。また、転送してはならないローカルのランタイム/ビルド成果物も除外する。`.github/workflows/crabbox-hydrate.yml` は、所有クラウドの `crabbox run --id ` コマンドに対するチェックアウト、Node/pnpm セットアップ、`origin/main` フェッチ、非シークレット環境の引き渡しを所有する。 ## 関連 - [インストール概要](/ja-JP/install) -- [開発チャネル](/ja-JP/install/development-channels) +- [開発チャンネル](/ja-JP/install/development-channels) diff --git a/docs/ja-JP/cli/dashboard.md b/docs/ja-JP/cli/dashboard.md index eabf87fd2..c6a47307b 100644 --- a/docs/ja-JP/cli/dashboard.md +++ b/docs/ja-JP/cli/dashboard.md @@ -1,33 +1,37 @@ --- read_when: - - 現在のトークンで Control UI を開きたい場合 - - ブラウザを起動せずに URL を表示したい場合 -summary: '`openclaw dashboard` の CLI リファレンス（Control UI を開く）' + - 現在のトークンを使ってコントロール UI を開きたい + - ブラウザーを起動せずに URL を出力したい場合 +summary: '`openclaw dashboard`（コントロールUIを開く）のCLIリファレンス' title: ダッシュボード x-i18n: - generated_at: "2026-04-25T13:44:04Z" - model: gpt-5.4 + generated_at: "2026-05-05T01:44:19Z" + model: gpt-5.5 provider: openai - source_hash: ce485388465fb93551be8ccf0aa01ea52e4feb949ef0d48c96b4f8ea65a6551c + source_hash: 51b3326b3884013ebcf570b417e66efe62ea89dcdedb5ab3173f39fb021de89f source_path: cli/dashboard.md - workflow: 15 + workflow: 16 --- # `openclaw dashboard` -現在の認証を使って Control UI を開きます。 +現在の認証を使用して Control UI を開きます。 ```bash openclaw dashboard openclaw dashboard --no-open ``` -注意: +注記: -- `dashboard` は、可能であれば設定済みの `gateway.auth.token` SecretRef を解決します。 -- `dashboard` は `gateway.tls.enabled` に従います: TLS が有効な gateway は `https://` の Control UI URL を表示/起動し、`wss://` で接続します。 -- SecretRef 管理のトークン（解決済み・未解決を問わず）では、外部 secret がターミナル出力、クリップボード履歴、またはブラウザ起動引数に露出しないよう、`dashboard` はトークンを含まない URL を表示/コピー/起動します。 -- `gateway.auth.token` が SecretRef 管理だがこのコマンド経路で未解決の場合、このコマンドは無効なトークンプレースホルダーを埋め込む代わりに、トークンを含まない URL と明示的な対処ガイダンスを表示します。 +- `dashboard` は、可能な場合に設定済みの `gateway.auth.token` SecretRefs を解決します。 +- `dashboard` は `gateway.tls.enabled` に従います。TLS が有効な Gateway は + `https://` Control UI URL を表示/開き、`wss://` 経由で接続します。 +- トークン認証されたダッシュボード URL のクリップボード/ブラウザー配信に失敗した場合、 + `dashboard` は安全な手動認証ヒントをログに記録し、トークン値を出力せずに + `OPENCLAW_GATEWAY_TOKEN`、`gateway.auth.token`、フラグメントキー `token` を示します。 +- SecretRef で管理されたトークン（解決済みまたは未解決）の場合、`dashboard` はターミナル出力、クリップボード履歴、ブラウザー起動引数で外部シークレットを公開しないように、トークン化されていない URL を表示/コピー/開きます。 +- `gateway.auth.token` が SecretRef で管理されているものの、このコマンドパスで未解決の場合、コマンドは無効なトークンプレースホルダーを埋め込む代わりに、トークン化されていない URL と明示的な修復手順を表示します。 ## 関連 diff --git a/docs/ja-JP/cli/doctor.md b/docs/ja-JP/cli/doctor.md index abc3b9379..8877d07a8 100644 --- a/docs/ja-JP/cli/doctor.md +++ b/docs/ja-JP/cli/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - 接続や認証の問題があり、ガイド付きの修正を利用したい場合 - - 更新後に健全性チェックをしたい場合 -summary: '`openclaw doctor` の CLI リファレンス (ヘルスチェック + ガイド付き修復)' + - 接続/認証の問題があり、ガイド付きの修正を利用したい + - 更新後にサニティチェックしたい場合 +summary: '`openclaw doctor` の CLI リファレンス（ヘルスチェック + ガイド付き修復）' title: 診断 x-i18n: - generated_at: "2026-05-04T02:22:48Z" + generated_at: "2026-05-05T01:44:18Z" model: gpt-5.5 provider: openai - source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905 + source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` -Gateway とチャンネルのヘルスチェック + クイック修復。 +Gateway とチャネルのヘルスチェック + クイック修正。 関連: @@ -34,45 +34,45 @@ openclaw doctor --generate-gateway-token ## オプション -- `--no-workspace-suggestions`: ワークスペースのメモリ/検索候補を無効にする +- `--no-workspace-suggestions`: ワークスペースメモリ/検索の提案を無効化する - `--yes`: プロンプトなしでデフォルトを受け入れる -- `--repair`: プロンプトなしで推奨される非サービス修復を適用する。Gateway サービスのインストールと書き換えには、引き続き対話的な確認または明示的な Gateway コマンドが必要 -- `--fix`: `--repair` の別名 -- `--force`: 必要に応じてカスタムサービス設定の上書きを含む、強力な修復を適用する -- `--non-interactive`: プロンプトなしで実行する。安全な移行と非サービス修復のみ +- `--repair`: プロンプトなしで推奨される非サービス修復を適用する。Gateway サービスのインストールと再書き込みには、引き続き対話的な確認または明示的な Gateway コマンドが必要 +- `--fix`: `--repair` のエイリアス +- `--force`: 必要に応じてカスタムサービス設定を上書きするなど、積極的な修復を適用する +- `--non-interactive`: プロンプトなしで実行する。安全なマイグレーションと非サービス修復のみ - `--generate-gateway-token`: Gateway トークンを生成して設定する -- `--deep`: 追加の Gateway インストールがないかシステムサービスをスキャンする +- `--deep`: 追加の Gateway インストールをシステムサービスでスキャンする 注記: -- 対話的プロンプト（keychain/OAuth 修正など）は、stdin が TTY で、かつ `--non-interactive` が設定されて**いない**場合にのみ実行されます。ヘッドレス実行（cron、Telegram、ターミナルなし）ではプロンプトはスキップされます。 -- パフォーマンス: 非対話型の `doctor` 実行では、ヘッドレスのヘルスチェックを高速に保つため、積極的な Plugin 読み込みをスキップします。対話型セッションでは、チェックで Plugin の寄与が必要な場合、引き続き Plugin を完全に読み込みます。 -- `--fix`（`--repair` の別名）はバックアップを `~/.openclaw/openclaw.json.bak` に書き込み、不明な設定キーを削除して、各削除を一覧表示します。 -- `doctor --fix --non-interactive` は、Gateway サービス定義の欠落または古さを報告しますが、更新修復モード以外ではインストールや書き換えは行いません。サービスがない場合は `openclaw gateway install` を実行し、ランチャーを意図的に置き換えたい場合は `openclaw gateway install --force` を実行します。 +- 対話的プロンプト（keychain/OAuth 修正など）は、stdin が TTY であり、かつ `--non-interactive` が設定されて**いない**場合にのみ実行されます。ヘッドレス実行（cron、Telegram、端末なし）ではプロンプトをスキップします。 +- パフォーマンス: 非対話的な `doctor` 実行では、ヘッドレスのヘルスチェックを高速に保つため、積極的な Plugin 読み込みをスキップします。対話的セッションでは、チェックが Plugin の寄与を必要とする場合、引き続き Plugin を完全に読み込みます。 +- `--fix`（`--repair` のエイリアス）は `~/.openclaw/openclaw.json.bak` にバックアップを書き込み、不明な設定キーを削除して、各削除を一覧表示します。 +- `doctor --fix --non-interactive` は、欠落または古い Gateway サービス定義を報告しますが、更新修復モード以外ではそれらをインストールまたは再書き込みしません。サービスが欠落している場合は `openclaw gateway install` を実行し、ランチャーを意図的に置き換えたい場合は `openclaw gateway install --force` を実行してください。 - 状態整合性チェックは、sessions ディレクトリ内の孤立した transcript ファイルを検出するようになりました。それらを `.deleted.` としてアーカイブするには対話的な確認が必要です。`--fix`、`--yes`、ヘッドレス実行ではそのまま残します。 -- Doctor は `~/.openclaw/cron/jobs.json`（または `cron.store`）もスキャンして、レガシーな Cron ジョブ形状を検出し、スケジューラが実行時に自動正規化する前にその場で書き換えることができます。 -- Linux では、ユーザーの crontab がまだレガシーな `~/.openclaw/bin/ensure-whatsapp.sh` を実行している場合、doctor が警告します。このスクリプトは保守されておらず、cron に systemd ユーザーバス環境がない場合に誤った WhatsApp Gateway 障害をログに記録する可能性があります。 -- Doctor は、古い OpenClaw バージョンで作成されたレガシー Plugin 依存関係のステージング状態をクリーンアップします。また、レジストリで解決できる場合は、設定済みで欠落しているダウンロード可能 Plugin も修復します。2026.5.2 の doctor パスでは、そのリリース用に設定を変更済みとしてマークする前に、古い設定ですでに使用されているダウンロード可能 Plugin を自動的にインストールします。ダウンロードに失敗した場合、doctor はインストールエラーを報告し、次回の修復試行のために設定済み Plugin エントリを保持します。 -- Doctor は、Plugin 検出が正常な場合に、欠落している Plugin ID を `plugins.allow`/`plugins.entries` から削除し、対応する不要なチャンネル設定、Heartbeat ターゲット、チャンネルモデル上書きも削除して、古い Plugin 設定を修復します。 -- Doctor は、影響を受ける `plugins.entries.` エントリを無効化し、その無効な `config` ペイロードを削除することで、無効な Plugin 設定を隔離します。Gateway 起動時はすでに、その不正な Plugin だけをスキップするため、他の Plugin とチャンネルは実行を継続できます。 -- 別のスーパーバイザーが Gateway ライフサイクルを所有している場合は、`OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。Doctor は引き続き Gateway/サービスのヘルスを報告し、非サービス修復を適用しますが、サービスのインストール/開始/再起動/ブートストラップとレガシーサービスのクリーンアップはスキップします。 -- Linux では、doctor は非アクティブな追加の Gateway 風 systemd ユニットを無視し、修復中に実行中の systemd Gateway サービスのコマンド/エントリポイントメタデータを書き換えません。アクティブなランチャーを意図的に置き換えたい場合は、先にサービスを停止するか、`openclaw gateway install --force` を使用します。 -- Doctor は、レガシーなフラット Talk 設定（`talk.voiceId`、`talk.modelId` など）を `talk.provider` + `talk.providers.` に自動移行します。 -- `doctor --fix` の繰り返し実行では、差分がオブジェクトキー順序だけの場合、Talk 正規化の報告/適用を行わなくなりました。 -- Doctor にはメモリ検索の準備状況チェックが含まれ、埋め込み認証情報が欠落している場合に `openclaw configure --section model` を推奨できます。 -- Doctor は、コマンド所有者が設定されていない場合に警告します。コマンド所有者とは、所有者専用コマンドの実行と危険な操作の承認を許可された人間のオペレーターアカウントです。DM ペアリングは誰かが bot と会話できるようにするだけです。最初の所有者ブートストラップが存在する前に送信者を承認していた場合は、`commands.ownerAllowFrom` を明示的に設定してください。 -- Doctor は、Codex モードのエージェントが設定され、オペレーターの Codex ホームに個人用 Codex CLI アセットが存在する場合に警告します。ローカルの Codex app-server 起動では、エージェントごとに分離されたホームが使用されるため、意図的に昇格すべきアセットを棚卸しするには `openclaw migrate codex --dry-run` を使用してください。 -- Doctor は、デフォルトエージェントに許可された Skills が、bin、環境変数、設定、OS 要件の不足により現在の実行環境で利用できない場合に警告します。`doctor --fix` は、それらの利用できない Skills を `skills.entries..enabled=false` で無効化できます。Skills を有効なままにしたい場合は、代わりに不足している要件をインストール/設定してください。 -- サンドボックスモードが有効だが Docker が利用できない場合、doctor は修復方法（`install Docker` または `openclaw config set agents.defaults.sandbox.mode off`）を含む高シグナルな警告を報告します。 -- レガシーなサンドボックスレジストリファイル（`~/.openclaw/sandbox/containers.json` または `~/.openclaw/sandbox/browsers.json`）が存在する場合、doctor はそれらを報告します。`openclaw doctor --fix` は、有効なエントリをシャード化されたレジストリディレクトリに移行し、無効なレガシーファイルを隔離します。 -- `gateway.auth.token`/`gateway.auth.password` が SecretRef 管理で、現在のコマンドパスで利用できない場合、doctor は読み取り専用の警告を報告し、プレーンテキストのフォールバック認証情報を書き込みません。 -- 修復パスでチャンネル SecretRef 検査が失敗した場合、doctor は早期終了せずに続行し、警告を報告します。 -- 状態ディレクトリ移行後、doctor プロセスから `TELEGRAM_BOT_TOKEN` または `DISCORD_BOT_TOKEN` が利用できず、有効化されたデフォルトの Telegram または Discord アカウントが環境変数フォールバックに依存している場合、doctor は警告します。 -- Telegram `allowFrom` ユーザー名の自動解決（`doctor --fix`）には、現在のコマンドパスで解決可能な Telegram トークンが必要です。トークン検査を利用できない場合、doctor は警告を報告し、そのパスでは自動解決をスキップします。 +- Doctor は、レガシー Cron ジョブ形状について `~/.openclaw/cron/jobs.json`（または `cron.store`）もスキャンし、スケジューラーが実行時に自動正規化する前に、その場で再書き込みできます。 +- Linux では、ユーザーの crontab がまだレガシーの `~/.openclaw/bin/ensure-whatsapp.sh` を実行している場合、doctor が警告します。このスクリプトはもう保守されておらず、cron に systemd ユーザーバス環境がない場合に WhatsApp Gateway の誤った停止をログ出力する可能性があります。 +- Doctor は、古い OpenClaw バージョンで作成されたレガシー Plugin 依存関係ステージング状態をクリーンアップします。また、`plugins.entries`、設定済みチャネル、設定済みプロバイダー/検索設定、または設定済みエージェントランタイムなど、設定から参照されている欠落したダウンロード可能 Plugin も修復します。パッケージ更新中、doctor はパッケージの入れ替えが完了するまでパッケージマネージャー Plugin 修復をスキップします。設定済み Plugin がまだ復旧を必要とする場合は、その後で `openclaw doctor --fix` を再実行してください。ダウンロードが失敗した場合、doctor はインストールエラーを報告し、次回の修復試行のために設定済み Plugin エントリを保持します。 +- Doctor は、Plugin 検出が健全な場合、欠落した Plugin id を `plugins.allow`/`plugins.entries` から削除し、対応する宙づりのチャネル設定、Heartbeat ターゲット、チャネルモデル上書きも削除することで、古い Plugin 設定を修復します。 +- Doctor は、影響を受けた `plugins.entries.` エントリを無効化し、その無効な `config` ペイロードを削除することで、無効な Plugin 設定を隔離します。Gateway 起動時にはすでに、その不正な Plugin のみをスキップするため、他の Plugin とチャネルは実行を継続できます。 +- 別のスーパーバイザーが Gateway ライフサイクルを所有している場合は、`OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定してください。Doctor は引き続き Gateway/サービスの健全性を報告し、非サービス修復を適用しますが、サービスのインストール/起動/再起動/ブートストラップ、およびレガシーサービスのクリーンアップをスキップします。 +- Linux では、doctor は非アクティブな追加の Gateway 風 systemd ユニットを無視し、修復中に実行中の systemd Gateway サービスのコマンド/エントリポイントメタデータを書き換えません。アクティブなランチャーを意図的に置き換えたい場合は、まずサービスを停止するか、`openclaw gateway install --force` を使用してください。 +- Doctor は、レガシーのフラットな Talk 設定（`talk.voiceId`、`talk.modelId` など）を `talk.provider` + `talk.providers.` に自動マイグレーションします。 +- `doctor --fix` の繰り返し実行は、差分がオブジェクトキー順序のみの場合、Talk 正規化を報告/適用しなくなりました。 +- Doctor にはメモリ検索の準備状況チェックが含まれ、embedding 認証情報が欠落している場合は `openclaw configure --section model` を推奨できます。 +- Doctor は、コマンド所有者が設定されていない場合に警告します。コマンド所有者とは、所有者専用コマンドの実行と危険な操作の承認を許可された人間のオペレーターアカウントです。DM ペアリングはボットと会話できるようにするだけです。最初の所有者ブートストラップが存在する前に送信者を承認した場合は、`commands.ownerAllowFrom` を明示的に設定してください。 +- Doctor は、Codex モードのエージェントが設定され、オペレーターの Codex home に個人用 Codex CLI アセットが存在する場合に警告します。ローカル Codex app-server 起動では、エージェントごとに分離された home を使用するため、意図的に昇格すべきアセットを棚卸しするには `openclaw migrate codex --dry-run` を使用してください。 +- Doctor は、デフォルトエージェントに許可された skills が、bin、env vars、config、または OS 要件の欠落により現在のランタイム環境で利用できない場合に警告します。`doctor --fix` は、それらの利用不可 skills を `skills.entries..enabled=false` で無効化できます。skill をアクティブなままにしたい場合は、代わりに欠落している要件をインストール/設定してください。 +- sandbox モードが有効だが Docker を利用できない場合、doctor は修復方法（`install Docker` または `openclaw config set agents.defaults.sandbox.mode off`）を含む高シグナルな警告を報告します。 +- レガシー sandbox レジストリファイル（`~/.openclaw/sandbox/containers.json` または `~/.openclaw/sandbox/browsers.json`）が存在する場合、doctor はそれらを報告します。`openclaw doctor --fix` は、有効なエントリをシャード化されたレジストリディレクトリへマイグレーションし、無効なレガシーファイルを隔離します。 +- `gateway.auth.token`/`gateway.auth.password` が SecretRef 管理であり、現在のコマンドパスで利用できない場合、doctor は読み取り専用の警告を報告し、平文のフォールバック認証情報を書き込みません。 +- 修正パスでチャネル SecretRef 検査が失敗した場合、doctor は早期終了せずに続行し、警告を報告します。 +- 状態ディレクトリのマイグレーション後、有効化されたデフォルトの Telegram または Discord アカウントが env フォールバックに依存していて、`TELEGRAM_BOT_TOKEN` または `DISCORD_BOT_TOKEN` を doctor プロセスが利用できない場合、doctor は警告します。 +- Telegram `allowFrom` ユーザー名の自動解決（`doctor --fix`）には、現在のコマンドパスで解決可能な Telegram トークンが必要です。トークン検査を利用できない場合、doctor は警告を報告し、そのパスでの自動解決をスキップします。 -## macOS: `launchctl` 環境上書き +## macOS: `launchctl` env 上書き -以前に `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（または `...PASSWORD`）を実行していた場合、その値が設定ファイルを上書きし、永続的な「unauthorized」エラーの原因になることがあります。 +以前に `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（または `...PASSWORD`）を実行した場合、その値が設定ファイルを上書きし、永続的な「unauthorized」エラーを引き起こす可能性があります。 ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN diff --git a/docs/ja-JP/cli/gateway.md b/docs/ja-JP/cli/gateway.md index a58d0fcb2..12e714e8c 100644 --- a/docs/ja-JP/cli/gateway.md +++ b/docs/ja-JP/cli/gateway.md @@ -1,28 +1,28 @@ --- read_when: - - CLI から Gateway を実行する（開発環境またはサーバー） - - Gateway の認証、バインドモード、接続性のデバッグ - - Bonjour による Gateway の検出 (ローカル + 広域 DNS-SD) + - CLI から Gateway を実行する (開発またはサーバー) + - Gateway 認証、バインドモード、接続性のデバッグ + - Bonjour による Gateway の検出 (ローカル + ワイドエリア DNS-SD) sidebarTitle: Gateway summary: OpenClaw Gateway CLI (`openclaw gateway`) — Gatewayを実行、照会、検出する title: Gateway x-i18n: - generated_at: "2026-05-04T18:23:38Z" + generated_at: "2026-05-05T01:44:19Z" model: gpt-5.5 provider: openai - source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d + source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038 source_path: cli/gateway.md workflow: 16 --- -Gateway は OpenClaw の WebSocket サーバー（channels、nodes、sessions、hooks）です。このページのサブコマンドは `openclaw gateway …` の下にあります。 +Gateway は OpenClaw の WebSocket サーバーです（チャネル、ノード、セッション、フック）。このページのサブコマンドは `openclaw gateway …` 配下にあります。 - ローカル mDNS + 広域 DNS-SD のセットアップ。 + ローカル mDNS + 広域 DNS-SD の設定。 - OpenClaw が Gateway を通知し、見つける方法。 + OpenClaw が Gateway を告知し、見つける仕組み。 トップレベルの Gateway 設定キー。 @@ -31,7 +31,7 @@ Gateway は OpenClaw の WebSocket サーバー（channels、nodes、sessions、 ## Gateway を実行する -ローカル Gateway プロセスを実行します。 +ローカル Gateway プロセスを実行します: ```bash openclaw gateway @@ -46,11 +46,11 @@ openclaw gateway run - デフォルトでは、`~/.openclaw/openclaw.json` で `gateway.mode=local` が設定されていない限り、Gateway は起動を拒否します。アドホック/開発用の実行には `--allow-unconfigured` を使用します。 - - `openclaw onboard --mode local` と `openclaw setup` は `gateway.mode=local` を書き込む想定です。ファイルが存在するのに `gateway.mode` がない場合は、local モードを暗黙に仮定するのではなく、壊れたか上書きされた設定として扱い、修復してください。 - - ファイルが存在し、`gateway.mode` がない場合、Gateway はそれを疑わしい設定破損として扱い、代わりに「local を推測する」ことを拒否します。 + - `openclaw onboard --mode local` と `openclaw setup` は `gateway.mode=local` を書き込むことが想定されています。ファイルは存在するが `gateway.mode` がない場合は、ローカルモードを暗黙に仮定するのではなく、壊れた、または上書きされた設定として扱い、修復します。 + - ファイルが存在し、`gateway.mode` がない場合、Gateway はそれを疑わしい設定破損として扱い、ユーザーのために「ローカルだと推測」することを拒否します。 - 認証なしでループバックを超えてバインドすることはブロックされます（安全ガードレール）。 - - `SIGUSR1` は、許可されている場合にプロセス内再起動をトリガーします（`commands.restart` はデフォルトで有効です。手動再起動をブロックするには `commands.restart: false` を設定しますが、gateway ツール/設定の apply/update は引き続き許可されます）。 - - `SIGINT`/`SIGTERM` ハンドラーは gateway プロセスを停止しますが、カスタム端末状態は復元しません。CLI を TUI または raw-mode 入力でラップする場合は、終了前に端末を復元してください。 + - `SIGUSR1` は、許可されている場合にプロセス内再起動をトリガーします（`commands.restart` はデフォルトで有効です。手動再起動をブロックするには `commands.restart: false` を設定します。ただし、Gateway ツール/設定の適用/更新は引き続き許可されます）。 + - `SIGINT`/`SIGTERM` ハンドラーは Gateway プロセスを停止しますが、カスタム端末状態は復元しません。CLI を TUI や raw モード入力でラップしている場合は、終了前に端末を復元してください。 @@ -58,58 +58,58 @@ openclaw gateway run ### オプション - WebSocket ポート（デフォルトは設定/env から取得され、通常は `18789`）。 + WebSocket ポート（デフォルトは設定/環境変数から取得され、通常は `18789`）。 - リスナーバインドモード。 + リスナーのバインドモード。 - 認証モードのオーバーライド。 + 認証モードの上書き。 - トークンのオーバーライド（プロセスに `OPENCLAW_GATEWAY_TOKEN` も設定します）。 + トークンの上書き（プロセスに `OPENCLAW_GATEWAY_TOKEN` も設定します）。 - パスワードのオーバーライド。 + パスワードの上書き。 - ファイルから gateway パスワードを読み取ります。 + Gateway パスワードをファイルから読み取ります。 - Gateway を Tailscale 経由で公開します。 + Tailscale 経由で Gateway を公開します。 シャットダウン時に Tailscale serve/funnel 設定をリセットします。 - 設定内に `gateway.mode=local` がなくても gateway の起動を許可します。アドホック/開発用ブートストラップのために起動ガードをバイパスするだけで、設定ファイルの書き込みや修復は行いません。 + 設定内に `gateway.mode=local` がなくても Gateway の起動を許可します。アドホック/開発用ブートストラップのためだけに起動ガードをバイパスします。設定ファイルの書き込みや修復は行いません。 - 見つからない場合は開発用設定 + ワークスペースを作成します（BOOTSTRAP.md をスキップします）。 + 存在しない場合に開発用設定 + ワークスペースを作成します（BOOTSTRAP.md をスキップします）。 - 開発用設定 + 認証情報 + セッション + ワークスペースをリセットします（`--dev` が必要）。 + 開発用設定 + 資格情報 + セッション + ワークスペースをリセットします（`--dev` が必要）。 - 起動前に、選択したポート上の既存リスナーを強制終了します。 + 起動前に、選択されたポート上の既存リスナーをすべて終了します。 詳細ログ。 - コンソールには CLI バックエンドログのみを表示します（stdout/stderr も有効化します）。 + コンソールには CLI バックエンドログのみを表示します（stdout/stderr も有効にします）。 - Websocket ログスタイル。 + WebSocket ログの形式。 `--ws-log compact` のエイリアス。 - 生のモデルストリームイベントを jsonl にログ記録します。 + 生のモデルストリームイベントを jsonl に記録します。 - 生ストリーム jsonl パス。 + 生ストリーム jsonl のパス。 ## Gateway を再起動する @@ -120,17 +120,17 @@ openclaw gateway restart --safe openclaw gateway restart --force ``` -`openclaw gateway restart --safe` は、再起動前に実行中の Gateway へアクティブな OpenClaw 作業のプリフライトを依頼します。キューに入った操作、返信配信、埋め込み実行、またはタスク実行がアクティブな場合、Gateway はブロッカーを報告し、重複する安全な再起動リクエストを統合し、アクティブな作業が流れ切った後に再起動します。プレーンな `restart` は、互換性のため既存のサービスマネージャー動作を維持します。即時オーバーライドパスを明示的に使いたい場合にのみ `--force` を使用してください。 +`openclaw gateway restart --safe` は、再起動前に実行中の Gateway にアクティブな OpenClaw 作業の事前確認を要求します。キュー済み操作、返信配信、埋め込み実行、またはタスク実行がアクティブな場合、Gateway はブロッカーを報告し、重複する安全な再起動リクエストをまとめ、アクティブな作業がなくなったら再起動します。通常の `restart` は互換性のため、既存のサービスマネージャー動作を維持します。即時上書きパスを明示的に使いたい場合にのみ `--force` を使用してください。 -インラインの `--password` はローカルのプロセス一覧に露出する可能性があります。`--password-file`、env、または SecretRef で裏付けられた `gateway.auth.password` を優先してください。 +インラインの `--password` は、ローカルプロセス一覧に露出する可能性があります。`--password-file`、環境変数、または SecretRef に基づく `gateway.auth.password` を優先してください。 ### 起動プロファイリング -- `OPENCLAW_GATEWAY_STARTUP_TRACE=1` を設定すると、Gateway 起動時のフェーズタイミングをログ記録します。フェーズごとの `eventLoopMax` 遅延と、installed-index、manifest registry、startup planning、owner-map 作業の Plugin ルックアップテーブルタイミングを含みます。 -- `OPENCLAW_DIAGNOSTICS=timeline` と `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` を設定すると、外部 QA ハーネス向けにベストエフォートの JSONL 起動診断タイムラインを書き込みます。設定内の `diagnostics.flags: ["timeline"]` でもフラグを有効化できますが、パスは引き続き env から提供されます。イベントループサンプルを含めるには `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` を追加します。 -- `pnpm test:startup:gateway -- --runs 5 --warmup 1` を実行して Gateway 起動をベンチマークします。このベンチマークは、最初のプロセス出力、`/healthz`、`/readyz`、起動トレースタイミング、イベントループ遅延、Plugin ルックアップテーブルタイミングの詳細を記録します。 +- `OPENCLAW_GATEWAY_STARTUP_TRACE=1` を設定すると、Gateway 起動中のフェーズ時間がログに記録されます。これには、フェーズごとの `eventLoopMax` 遅延と、インストール済みインデックス、マニフェストレジストリ、起動計画、owner-map 処理に関する Plugin ルックアップテーブルの時間が含まれます。 +- `OPENCLAW_DIAGNOSTICS=timeline` と `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` を設定すると、外部 QA ハーネス向けにベストエフォートの JSONL 起動診断タイムラインを書き込みます。設定内の `diagnostics.flags: ["timeline"]` でフラグを有効にすることもできますが、パスは引き続き環境変数から指定します。イベントループサンプルを含めるには `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` を追加します。 +- `pnpm test:startup:gateway -- --runs 5 --warmup 1` を実行して Gateway 起動をベンチマークします。ベンチマークは、最初のプロセス出力、`/healthz`、`/readyz`、起動トレースの時間、イベントループ遅延、Plugin ルックアップテーブル時間の詳細を記録します。 ## 実行中の Gateway に問い合わせる @@ -138,23 +138,23 @@ openclaw gateway restart --force - - デフォルト: 人間が読める形式（TTY では色付き）。 + - デフォルト: 人間が読みやすい形式（TTY では色付き）。 - `--json`: 機械可読 JSON（スタイル/スピナーなし）。 - - `--no-color`（または `NO_COLOR=1`）: 人間向けレイアウトを維持したまま ANSI を無効化します。 + - `--no-color`（または `NO_COLOR=1`）: 人間向けレイアウトを維持しながら ANSI を無効化します。 - + - `--url `: Gateway WebSocket URL。 - `--token `: Gateway トークン。 - `--password `: Gateway パスワード。 - - `--timeout `: タイムアウト/予算（コマンドにより異なります）。 + - `--timeout `: タイムアウト/予算（コマンドごとに異なります）。 - `--expect-final`: 「final」レスポンスを待ちます（エージェント呼び出し）。 -`--url` を設定すると、CLI は設定または環境認証情報にフォールバックしません。`--token` または `--password` を明示的に渡してください。明示的な認証情報がない場合はエラーです。 +`--url` を設定すると、CLI は設定や環境変数の資格情報にフォールバックしません。`--token` または `--password` を明示的に渡してください。明示的な資格情報がない場合はエラーです。 ### `gateway health` @@ -163,11 +163,11 @@ openclaw gateway restart --force openclaw gateway health --url ws://127.0.0.1:18789 ``` -HTTP `/healthz` エンドポイントは liveness probe です。サーバーが HTTP に応答できるようになると返ります。HTTP `/readyz` エンドポイントはより厳密で、起動時の Plugin サイドカー、チャンネル、または設定済み hooks がまだ安定化中の間は赤のままです。ローカルまたは認証済みの詳細な readiness レスポンスには、イベントループ遅延、イベントループ使用率、CPU コア比率、`degraded` フラグを含む `eventLoop` 診断ブロックが含まれます。 +HTTP `/healthz` エンドポイントは liveness プローブです。サーバーが HTTP に応答できるようになると返ります。HTTP `/readyz` エンドポイントはより厳密で、起動時の Plugin サイドカー、チャネル、または設定済みフックがまだ安定していない間は赤のままです。ローカルまたは認証済みの詳細 readiness レスポンスには、イベントループ遅延、イベントループ使用率、CPU コア比率、`degraded` フラグを含む `eventLoop` 診断ブロックが含まれます。 ### `gateway usage-cost` -セッションログから usage-cost サマリーを取得します。 +セッションログから使用コストの概要を取得します。 ```bash openclaw gateway usage-cost @@ -195,32 +195,32 @@ openclaw gateway stability --json 含める最近のイベントの最大数（最大 `1000`）。 - `payload.large` や `diagnostic.memory.pressure` などの診断イベントタイプでフィルターします。 + `payload.large` や `diagnostic.memory.pressure` など、診断イベントタイプで絞り込みます。 診断シーケンス番号より後のイベントのみを含めます。 - 実行中の Gateway を呼び出す代わりに、永続化された stability bundle を読み取ります。状態ディレクトリ下の最新 bundle には `--bundle latest`（または単に `--bundle`）を使用するか、bundle JSON パスを直接渡します。 + 実行中の Gateway を呼び出す代わりに、永続化された安定性バンドルを読み取ります。状態ディレクトリ配下の最新バンドルには `--bundle latest`（または単に `--bundle`）を使用するか、バンドル JSON パスを直接渡します。 - stability 詳細を出力する代わりに、共有可能なサポート診断 zip を書き込みます。 + 安定性の詳細を出力する代わりに、共有可能なサポート診断 zip を書き込みます。 `--export` の出力パス。 - - - レコードは運用メタデータを保持します。イベント名、件数、バイトサイズ、メモリ測定値、キュー/セッション状態、チャンネル/Plugin 名、編集済みセッションサマリーなどです。チャットテキスト、webhook 本文、ツール出力、生のリクエストまたはレスポンス本文、トークン、Cookie、秘密値、ホスト名、生のセッション ID は保持しません。レコーダー全体を無効にするには `diagnostics.enabled: false` を設定します。 - - 致命的な Gateway 終了、シャットダウンタイムアウト、再起動時の起動失敗では、レコーダーにイベントがある場合、OpenClaw は同じ診断スナップショットを `~/.openclaw/logs/stability/openclaw-stability-*.json` に書き込みます。最新 bundle は `openclaw gateway stability --bundle latest` で調査します。`--limit`、`--type`、`--since-seq` も bundle 出力に適用されます。 + + - レコードは運用メタデータを保持します。イベント名、件数、バイトサイズ、メモリ読み取り値、キュー/セッション状態、チャネル/Plugin 名、編集済みのセッション概要です。チャットテキスト、Webhook 本文、ツール出力、生のリクエスト本文またはレスポンス本文、トークン、Cookie、シークレット値、ホスト名、生のセッション ID は保持しません。レコーダーを完全に無効化するには `diagnostics.enabled: false` を設定します。 + - 致命的な Gateway 終了、シャットダウンタイムアウト、再起動時の起動失敗では、レコーダーにイベントがある場合、OpenClaw は同じ診断スナップショットを `~/.openclaw/logs/stability/openclaw-stability-*.json` に書き込みます。最新バンドルは `openclaw gateway stability --bundle latest` で確認できます。`--limit`、`--type`、`--since-seq` もバンドル出力に適用されます。 ### `gateway diagnostics export` -バグ報告に添付することを目的としたローカル診断 zip を書き込みます。プライバシーモデルと bundle の内容については、[診断エクスポート](/ja-JP/gateway/diagnostics) を参照してください。 +バグレポートに添付するために設計されたローカル診断 zip を書き込みます。プライバシーモデルとバンドル内容については、[診断エクスポート](/ja-JP/gateway/diagnostics) を参照してください。 ```bash openclaw gateway diagnostics export @@ -229,40 +229,40 @@ openclaw gateway diagnostics export --json ``` - 出力 zip パス。デフォルトでは状態ディレクトリ下のサポートエクスポートです。 + 出力 zip パス。デフォルトでは、状態ディレクトリ配下のサポートエクスポートです。 含めるサニタイズ済みログ行の最大数。 - 調査するログバイトの最大数。 + 検査するログバイト数の最大値。 - health スナップショット用の Gateway WebSocket URL。 + ヘルススナップショット用の Gateway WebSocket URL。 - health スナップショット用の Gateway トークン。 + ヘルススナップショット用の Gateway トークン。 - health スナップショット用の Gateway パスワード。 + ヘルススナップショット用の Gateway パスワード。 - status/health スナップショットのタイムアウト。 + ステータス/ヘルススナップショットのタイムアウト。 - 永続化された stability bundle の検索をスキップします。 + 永続化された安定性バンドルの検索をスキップします。 - 書き込まれたパス、サイズ、manifest を JSON として出力します。 + 書き込まれたパス、サイズ、マニフェストを JSON として出力します。 -エクスポートには、manifest、Markdown サマリー、設定の形状、サニタイズ済み設定詳細、サニタイズ済みログサマリー、サニタイズ済み Gateway status/health スナップショット、存在する場合は最新の stability bundle が含まれます。 +エクスポートには、マニフェスト、Markdown 概要、設定の形状、サニタイズ済み設定詳細、サニタイズ済みログ概要、サニタイズ済み Gateway ステータス/ヘルススナップショット、存在する場合は最新の安定性バンドルが含まれます。 -共有されることを想定しています。デバッグに役立つ運用詳細を保持します。たとえば、安全な OpenClaw ログフィールド、サブシステム名、ステータスコード、期間、設定済みモード、ポート、Plugin ID、provider ID、非秘密の機能設定、編集済み運用ログメッセージなどです。チャットテキスト、webhook 本文、ツール出力、認証情報、Cookie、アカウント/メッセージ識別子、プロンプト/指示テキスト、ホスト名、秘密値は省略または編集されます。LogTape 形式のメッセージがユーザー/チャット/ツールのペイロードテキストのように見える場合、エクスポートはメッセージが省略されたこととそのバイト数のみを保持します。 +これは共有を前提としています。安全な OpenClaw ログフィールド、サブシステム名、ステータスコード、期間、設定済みモード、ポート、Plugin ID、プロバイダー ID、非シークレットの機能設定、編集済みの運用ログメッセージなど、デバッグに役立つ運用詳細を保持します。チャットテキスト、Webhook 本文、ツール出力、資格情報、Cookie、アカウント/メッセージ識別子、プロンプト/指示テキスト、ホスト名、シークレット値は省略または編集します。LogTape 形式のメッセージがユーザー/チャット/ツールのペイロードテキストのように見える場合、エクスポートはメッセージが省略されたこととそのバイト数のみを保持します。 ### `gateway status` -`gateway status` は、Gateway サービス（launchd/systemd/schtasks）に加えて、接続性/認証機能の任意の probe を表示します。 +`gateway status` は Gateway サービス（launchd/systemd/schtasks）に加え、接続性/認証機能の任意のプローブを表示します。 ```bash openclaw gateway status @@ -271,7 +271,7 @@ openclaw gateway status --require-rpc ``` - 明示的なプローブ対象を追加します。設定済みのリモート + localhost も引き続きプローブされます。 + 明示的なプローブ対象を追加します。設定済みのリモートと localhost も引き続きプローブされます。 プローブ用のトークン認証。 @@ -283,32 +283,32 @@ openclaw gateway status --require-rpc プローブのタイムアウト。 - 接続プローブをスキップします（サービスのみの表示）。 + 接続性プローブをスキップします（サービスのみの表示）。 システムレベルのサービスもスキャンします。 - デフォルトの接続プローブを読み取りプローブにアップグレードし、その読み取りプローブが失敗した場合はゼロ以外で終了します。`--no-probe` と組み合わせることはできません。 + 既定の接続性プローブを読み取りプローブに昇格し、その読み取りプローブが失敗した場合はゼロ以外で終了します。`--no-probe` と組み合わせることはできません。 - - ローカル CLI 設定が存在しない、または無効な場合でも、`gateway status` は診断用に引き続き利用できます。 - - デフォルトの `gateway status` は、サービス状態、WebSocket 接続、ハンドシェイク時に見える認証機能を証明します。読み取り/書き込み/管理操作は証明しません。 - - 診断プローブは初回デバイス認証に対して非変更です。既存のキャッシュ済みデバイストークンがある場合は再利用しますが、ステータス確認だけのために新しい CLI デバイス ID や読み取り専用デバイスペアリングレコードを作成しません。 - - `gateway status` は、可能な場合にプローブ認証用として設定済み認証 SecretRefs を解決します。 - - このコマンドパスで必須の認証 SecretRef が未解決の場合、プローブの接続/認証が失敗すると `gateway status --json` は `rpc.authWarning` を報告します。`--token`/`--password` を明示的に渡すか、先にシークレットソースを解決してください。 - - プローブが成功した場合、未解決の認証参照警告は誤検知を避けるため抑制されます。 - - リスニング中のサービスだけでは不十分で、読み取りスコープの RPC 呼び出しも正常である必要があるスクリプトや自動化では、`--require-rpc` を使用してください。 - - `--deep` は追加の launchd/systemd/schtasks インストールをベストエフォートでスキャンします。複数の Gateway らしきサービスが検出されると、人間向け出力はクリーンアップのヒントを表示し、ほとんどのセットアップではマシンごとに 1 つの Gateway を実行すべきだと警告します。 - - 人間向け出力には、解決済みのファイルログパスに加えて、プロファイルや状態ディレクトリのずれを診断しやすくするための CLI 対サービスの設定パス/妥当性スナップショットが含まれます。 + - ローカル CLI 設定が存在しない、または無効な場合でも、`gateway status` は診断用に引き続き使用できます。 + - 既定の `gateway status` は、サービス状態、WebSocket 接続、ハンドシェイク時に見える認証機能を証明します。読み取り/書き込み/管理操作は証明しません。 + - 診断プローブは、初回デバイス認証に対して非変更です。既存のキャッシュ済みデバイストークンがある場合はそれを再利用しますが、ステータス確認のためだけに新しい CLI デバイス ID や読み取り専用デバイスペアリングレコードを作成することはありません。 + - `gateway status` は、可能な場合、プローブ認証用に設定済みの認証 SecretRef を解決します。 + - このコマンドパスで必須の認証 SecretRef が未解決の場合、プローブの接続性/認証が失敗すると `gateway status --json` は `rpc.authWarning` を報告します。`--token`/`--password` を明示的に渡すか、先にシークレットソースを解決してください。 + - プローブが成功した場合、誤検知を避けるため未解決の auth-ref 警告は抑制されます。 + - リスニングサービスだけでは不十分で、読み取りスコープの RPC 呼び出しも正常である必要があるスクリプトや自動化では、`--require-rpc` を使用します。 + - `--deep` は、追加の launchd/systemd/schtasks インストールをベストエフォートでスキャンします。複数の Gateway らしきサービスが検出された場合、人間向け出力はクリーンアップのヒントを出力し、ほとんどのセットアップでは 1 台のマシンにつき 1 つの Gateway を実行すべきだと警告します。 + - 人間向け出力には、プロファイルや状態ディレクトリのずれを診断しやすくするため、解決済みのファイルログパスに加えて CLI とサービスの設定パス/有効性のスナップショットが含まれます。 - - Linux systemd インストールでは、サービス認証のずれチェックはユニットから `Environment=` と `EnvironmentFile=` の両方の値を読み取ります（`%h`、引用符付きパス、複数ファイル、任意指定の `-` ファイルを含む）。 - - ずれチェックは、マージされたランタイム環境（サービスコマンド環境が先、次にプロセス環境フォールバック）を使用して `gateway.auth.token` SecretRefs を解決します。 - - トークン認証が実質的に有効でない場合（明示的な `gateway.auth.mode` が `password`/`none`/`trusted-proxy`、または mode が未設定でパスワードが優先される可能性があり、勝てるトークン候補がない場合）、トークンずれチェックは設定トークンの解決をスキップします。 + - Linux systemd インストールでは、サービス認証ずれチェックがユニットから `Environment=` と `EnvironmentFile=` の両方の値を読み取ります（`%h`、引用符付きパス、複数ファイル、省略可能な `-` ファイルを含む）。 + - ずれチェックは、マージされたランタイム環境（先にサービスコマンド環境、次にプロセス環境フォールバック）を使用して `gateway.auth.token` SecretRef を解決します。 + - トークン認証が実質的に有効でない場合（明示的な `gateway.auth.mode` が `password`/`none`/`trusted-proxy`、またはモード未設定でパスワードが優先され、勝てるトークン候補がない場合）、トークンずれチェックは設定トークンの解決をスキップします。 @@ -317,17 +317,17 @@ openclaw gateway status --require-rpc `gateway probe` は「すべてをデバッグする」コマンドです。常に次をプローブします。 -- 設定済みのリモート Gateway（設定されている場合）と +- 設定済みのリモート Gateway（設定されている場合）、および - localhost（ループバック）。**リモートが設定されている場合でも**対象です。 -`--url` を渡すと、その明示的な対象が両方の前に追加されます。人間向け出力では対象に次のラベルが付きます。 +`--url` を渡すと、その明示的な対象が両方より前に追加されます。人間向け出力では対象に次のラベルが付きます。 - `URL (explicit)` - `Remote (configured)` または `Remote (configured, inactive)` - `Local loopback` -複数の Gateway に到達できる場合、それらをすべて表示します。分離されたプロファイル/ポート（例: レスキューボット）を使用する場合、複数 Gateway はサポートされますが、ほとんどのインストールでは引き続き単一の Gateway を実行します。 +複数の Gateway に到達できる場合は、それらすべてを出力します。分離されたプロファイル/ポート（例: レスキューボット）を使用する場合、複数の Gateway はサポートされますが、ほとんどのインストールでは単一の Gateway を実行します。 ```bash @@ -340,48 +340,48 @@ openclaw gateway probe --json - `Reachable: yes` は、少なくとも 1 つの対象が WebSocket 接続を受け入れたことを意味します。 - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` は、プローブが認証について証明できた内容を報告します。到達可能性とは別です。 - `Read probe: ok` は、読み取りスコープの詳細 RPC 呼び出し（`health`/`status`/`system-presence`/`config.get`）も成功したことを意味します。 - - `Read probe: limited - missing scope: operator.read` は、接続は成功したが読み取りスコープ RPC が制限されていることを意味します。これは完全な失敗ではなく、**低下した**到達可能性として報告されます。 - - `Connect: ok` の後の `Read probe: failed` は、Gateway が WebSocket 接続を受け入れたものの、後続の読み取り診断がタイムアウトまたは失敗したことを意味します。これも到達不能な Gateway ではなく、**低下した**到達可能性です。 - - `gateway status` と同様に、probe は既存のキャッシュ済みデバイス認証を再利用しますが、初回デバイス ID やペアリング状態は作成しません。 - - 終了コードがゼロ以外になるのは、プローブされた対象に 1 つも到達できない場合だけです。 + - `Read probe: limited - missing scope: operator.read` は、接続は成功したが、読み取りスコープ RPC が制限されていることを意味します。これは完全な失敗ではなく、**劣化した**到達可能性として報告されます。 + - `Connect: ok` の後の `Read probe: failed` は、Gateway が WebSocket 接続を受け入れたものの、後続の読み取り診断がタイムアウトまたは失敗したことを意味します。これも到達不能な Gateway ではなく、**劣化した**到達可能性です。 + - `gateway status` と同様に、プローブは既存のキャッシュ済みデバイス認証を再利用しますが、初回デバイス ID やペアリング状態は作成しません。 + - プローブされた対象に到達可能なものが 1 つもない場合にのみ、終了コードはゼロ以外になります。 トップレベル: - - `ok`: 少なくとも 1 つの対象に到達できます。 - - `degraded`: 少なくとも 1 つの対象が接続を受け入れたものの、完全な詳細 RPC 診断を完了しませんでした。 + - `ok`: 少なくとも 1 つの対象に到達可能です。 + - `degraded`: 少なくとも 1 つの対象が接続を受け入れましたが、完全な詳細 RPC 診断を完了しませんでした。 - `capability`: 到達可能な対象全体で確認された最良の機能（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope`、または `unknown`）。 - - `primaryTargetId`: アクティブな勝者として扱う最良の対象。順序は、明示的 URL、SSH トンネル、設定済みリモート、local loopback です。 - - `warnings[]`: `code`、`message`、任意の `targetIds` を含むベストエフォートの警告レコード。 + - `primaryTargetId`: アクティブな勝者として扱う最良の対象。優先順は、明示的な URL、SSH トンネル、設定済みリモート、local loopback です。 + - `warnings[]`: `code`、`message`、および省略可能な `targetIds` を含むベストエフォートの警告レコード。 - `network`: 現在の設定とホストネットワークから派生した local loopback/tailnet URL ヒント。 - - `discovery.timeoutMs` と `discovery.count`: このプローブ実行で使用された実際の検出予算/結果数。 + - `discovery.timeoutMs` と `discovery.count`: このプローブパスで使用された実際の検出予算/結果数。 対象ごと（`targets[].connect`）: - - `ok`: 接続 + 低下分類後の到達可能性。 + - `ok`: 接続後の到達可能性と劣化分類。 - `rpcOk`: 完全な詳細 RPC の成功。 - - `scopeLimited`: 必要な operator スコープが不足したため詳細 RPC が失敗しました。 + - `scopeLimited`: operator スコープ不足により詳細 RPC が失敗しました。 対象ごと（`targets[].auth`）: - `role`: 利用可能な場合、`hello-ok` で報告された認証ロール。 - - `scopes`: 利用可能な場合、`hello-ok` で報告された付与スコープ。 - - `capability`: その対象について表面化された認証機能分類。 + - `scopes`: 利用可能な場合、`hello-ok` で報告された付与済みスコープ。 + - `capability`: その対象に対して表面化された認証機能の分類。 - `ssh_tunnel_failed`: SSH トンネルのセットアップに失敗しました。コマンドは直接プローブにフォールバックしました。 - - `multiple_gateways`: 複数の対象に到達できました。レスキューボットのように分離されたプロファイルを意図的に実行している場合を除き、これは通常とは異なります。 - - `auth_secretref_unresolved`: 失敗した対象に対して、設定済み認証 SecretRef を解決できませんでした。 - - `probe_scope_limited`: WebSocket 接続は成功しましたが、読み取りプローブは `operator.read` の不足により制限されました。 + - `multiple_gateways`: 複数の対象に到達可能でした。レスキューボットなど、分離されたプロファイルを意図的に実行している場合を除き、これは通常ではありません。 + - `auth_secretref_unresolved`: 設定済みの認証 SecretRef を失敗した対象向けに解決できませんでした。 + - `probe_scope_limited`: WebSocket 接続は成功しましたが、`operator.read` が不足していたため読み取りプローブが制限されました。 -#### SSH 経由のリモート（Mac アプリ同等） +#### SSH 経由のリモート（Mac アプリとの同等性） -macOS アプリの「Remote over SSH」モードはローカルポートフォワードを使用するため、リモート Gateway（ループバックのみにバインドされている場合があります）が `ws://127.0.0.1:` で到達可能になります。 +macOS アプリの「Remote over SSH」モードはローカルポート転送を使用するため、リモート Gateway（ループバックのみにバインドされている場合があります）に `ws://127.0.0.1:` で到達できるようになります。 CLI での同等操作: @@ -390,16 +390,16 @@ openclaw gateway probe --ssh user@gateway-host ``` - `user@host` または `user@host:port`（port のデフォルトは `22`）。 + `user@host` または `user@host:port`（ポートの既定値は `22`）。 ID ファイル。 - 解決済み検出エンドポイント（`local.` に設定済みワイドエリアドメインを加えたもの、存在する場合）から、最初に検出された Gateway ホストを SSH 対象として選択します。TXT のみのヒントは無視されます。 + 解決済みの検出エンドポイント（`local.` に加え、設定済みの広域ドメインがあればそれも）から、最初に検出された Gateway ホストを SSH 対象として選択します。TXT のみのヒントは無視されます。 -設定（任意、デフォルトとして使用）: +設定（省略可能、既定値として使用）: - `gateway.remote.sshTarget` - `gateway.remote.sshIdentity` @@ -429,10 +429,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' タイムアウト予算。 - 主に、最終ペイロードの前に中間イベントをストリームするエージェント形式の RPC 用です。 + 主に、最終ペイロードの前に中間イベントをストリーミングするエージェント形式の RPC 向けです。 - 機械可読な JSON 出力。 + 機械可読の JSON 出力。 @@ -449,9 +449,9 @@ openclaw gateway restart openclaw gateway uninstall ``` -### ラッパーを使用してインストールする +### ラッパー付きでインストールする -管理対象サービスを別の実行ファイル経由で起動する必要がある場合は、`--wrapper` を使用します。たとえば、シークレットマネージャーのシムや実行ユーザーヘルパーです。ラッパーは通常の Gateway 引数を受け取り、最終的にそれらの引数で `openclaw` または Node を exec する責任があります。 +管理対象サービスを別の実行可能ファイル経由で起動する必要がある場合は、`--wrapper` を使用します。たとえば、シークレットマネージャーの shim や run-as ヘルパーです。ラッパーは通常の Gateway 引数を受け取り、最終的にそれらの引数で `openclaw` または Node を exec する責任を持ちます。 ```bash cat > ~/.local/bin/openclaw-doppler <<'EOF' @@ -465,7 +465,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force openclaw gateway restart ``` -環境経由でラッパーを設定することもできます。`gateway install` はパスが実行可能ファイルであることを検証し、ラッパーをサービスの `ProgramArguments` に書き込み、後の強制再インストール、更新、doctor 修復のためにサービス環境へ `OPENCLAW_WRAPPER` を永続化します。 +環境からラッパーを設定することもできます。`gateway install` は、そのパスが実行可能ファイルであることを検証し、ラッパーをサービスの `ProgramArguments` に書き込み、後の強制再インストール、更新、doctor 修復のためにサービス環境へ `OPENCLAW_WRAPPER` を永続化します。 ```bash OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force @@ -481,25 +481,26 @@ openclaw gateway restart - - `gateway status`: `--url`、`--token`、`--password`、`--timeout`、`--no-probe`、`--require-rpc`、`--deep`、`--json` - - `gateway install`: `--port`、`--runtime `、`--token`、`--wrapper `、`--force`、`--json` - - `gateway restart`: `--force`、`--wait `、`--json` + - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json` + - `gateway install`: `--port`, `--runtime `, `--token`, `--wrapper `, `--force`, `--json` + - `gateway restart`: `--safe`, `--force`, `--wait `, `--json` - `gateway uninstall|start|stop`: `--json` - - - 管理対象サービスを再起動するには `gateway restart` を使用します。再起動の代替として `gateway stop` と `gateway start` を連鎖させないでください。macOS では、`gateway stop` は停止前に LaunchAgent を意図的に無効化します。 + + - 管理対象サービスを再起動するには `gateway restart` を使用します。再起動の代替として `gateway stop` と `gateway start` を連結しないでください。macOS では、`gateway stop` は停止前に LaunchAgent を意図的に無効化します。 + - `gateway restart --safe` は、実行中の Gateway にアクティブな OpenClaw 作業のプリフライトを依頼し、返信配信、埋め込み実行、タスク実行がドレインされるまで再起動を延期します。`--safe` は `--force` または `--wait` と組み合わせることはできません。 - `gateway restart --wait 30s` は、その再起動について設定済みの再起動ドレイン予算を上書きします。単位なしの数値はミリ秒です。`s`、`m`、`h` などの単位を使用できます。`--wait 0` は無期限に待機します。 - - `gateway restart --force` はアクティブ作業のドレインをスキップし、すぐに再起動します。operator が一覧表示されたタスクブロッカーをすでに確認し、Gateway を今すぐ戻したい場合に使用します。 - - ライフサイクルコマンドはスクリプト用に `--json` を受け入れます。 + - `gateway restart --force` はアクティブ作業のドレインをスキップし、即座に再起動します。オペレーターが一覧表示されたタスクブロッカーをすでに確認し、今すぐ Gateway を戻したい場合に使用します。 + - ライフサイクルコマンドはスクリプト用に `--json` を受け付けます。 - - - トークン認証がトークンを必要とし、`gateway.auth.token` が SecretRef 管理の場合、`gateway install` は SecretRef が解決可能であることを検証しますが、解決済みトークンをサービス環境メタデータには永続化しません。 - - トークン認証がトークンを必要とし、設定済みトークン SecretRef が未解決の場合、フォールバックの平文を永続化するのではなく、インストールは閉じた状態で失敗します。 - - `gateway run` のパスワード認証では、インラインの `--password` より `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`、または SecretRef で裏付けられた `gateway.auth.password` を優先してください。 - - 推論された認証モードでは、シェルのみの `OPENCLAW_GATEWAY_PASSWORD` はインストール時のトークン要件を緩和しません。管理対象サービスをインストールする場合は、永続的な設定（`gateway.auth.password` または設定 `env`）を使用してください。 - - `gateway.auth.token` と `gateway.auth.password` の両方が設定され、`gateway.auth.mode` が未設定の場合、mode が明示的に設定されるまでインストールはブロックされます。 + + - トークン認証でトークンが必要で、`gateway.auth.token` が SecretRef 管理の場合、`gateway install` は SecretRef が解決可能であることを検証しますが、解決済みトークンをサービス環境メタデータには永続化しません。 + - トークン認証でトークンが必要で、設定されたトークンの SecretRef が未解決の場合、インストールはフォールバックの平文を永続化せずにフェイルクローズします。 + - `gateway run` のパスワード認証では、インラインの `--password` よりも `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`、または SecretRef で裏付けられた `gateway.auth.password` を優先してください。 + - 推論された認証モードでは、シェル限定の `OPENCLAW_GATEWAY_PASSWORD` によってインストール時のトークン要件は緩和されません。管理対象サービスをインストールするときは、永続的な設定（`gateway.auth.password` または設定の `env`）を使用してください。 + - `gateway.auth.token` と `gateway.auth.password` の両方が設定され、`gateway.auth.mode` が未設定の場合、モードが明示的に設定されるまでインストールはブロックされます。 @@ -508,20 +509,20 @@ openclaw gateway restart `gateway discover` は Gateway ビーコン（`_openclaw-gw._tcp`）をスキャンします。 -- マルチキャスト DNS-SD: `local.` -- ユニキャスト DNS-SD (Wide-Area Bonjour): ドメインを選択し (例: `openclaw.internal.`)、スプリット DNS + DNS サーバーを設定します。詳しくは [Bonjour](/ja-JP/gateway/bonjour) を参照してください。 +- Multicast DNS-SD: `local.` +- Unicast DNS-SD（Wide-Area Bonjour）: ドメイン（例: `openclaw.internal.`）を選択し、分割 DNS + DNS サーバーを設定します。[Bonjour](/ja-JP/gateway/bonjour) を参照してください。 -Bonjour 検出が有効 (デフォルト) な Gateway のみがビーコンをアドバタイズします。 +Bonjour 検出が有効（デフォルト）な Gateway だけがビーコンをアドバタイズします。 -Wide-Area 検出レコードには次が含まれます (TXT): +Wide-Area 検出レコードには以下が含まれます（TXT）: -- `role` (Gateway ロールのヒント) -- `transport` (トランスポートのヒント、例: `gateway`) -- `gatewayPort` (WebSocket ポート、通常は `18789`) -- `sshPort` (任意。存在しない場合、クライアントは SSH ターゲットのデフォルトを `22` にします) -- `tailnetDns` (MagicDNS ホスト名、利用可能な場合) -- `gatewayTls` / `gatewayTlsSha256` (TLS 有効 + 証明書フィンガープリント) -- `cliPath` (Wide-Area ゾーンに書き込まれるリモートインストールのヒント) +- `role`（Gateway ロールのヒント） +- `transport`（トランスポートのヒント、例: `gateway`） +- `gatewayPort`（WebSocket ポート、通常は `18789`） +- `sshPort`（任意。存在しない場合、クライアントは SSH ターゲットのデフォルトを `22` にします） +- `tailnetDns`（MagicDNS ホスト名、利用可能な場合） +- `gatewayTls` / `gatewayTlsSha256`（TLS 有効 + 証明書フィンガープリント） +- `cliPath`（wide-area ゾーンに書き込まれるリモートインストールのヒント） ### `gateway discover` @@ -530,10 +531,10 @@ openclaw gateway discover ``` - コマンドごとのタイムアウト (ブラウズ/解決)。 + コマンドごとのタイムアウト（参照/解決）。 - 機械可読の出力 (スタイルやスピナーも無効化します)。 + 機械可読な出力（スタイル設定/スピナーも無効化します）。 例: @@ -544,9 +545,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- CLI は `local.` に加えて、有効化されている場合は設定済みの Wide-Area ドメインをスキャンします。 -- JSON 出力の `wsUrl` は、`lanHost` や `tailnetDns` などの TXT のみのヒントではなく、解決されたサービスエンドポイントから導出されます。 -- `local.` mDNS では、`sshPort` と `cliPath` は `discovery.mdns.mode` が `full` の場合にのみブロードキャストされます。Wide-Area DNS-SD では引き続き `cliPath` が書き込まれます。そこでも `sshPort` は任意のままです。 +- CLI は `local.` に加えて、有効化されている場合は設定された wide-area ドメインもスキャンします。 +- JSON 出力の `wsUrl` は、`lanHost` や `tailnetDns` のような TXT のみのヒントではなく、解決済みのサービスエンドポイントから導出されます。 +- `local.` mDNS では、`sshPort` と `cliPath` は `discovery.mdns.mode` が `full` の場合にのみブロードキャストされます。Wide-area DNS-SD でも `cliPath` は書き込まれますが、`sshPort` はそこでも任意のままです。 diff --git a/docs/ja-JP/cli/plugins.md b/docs/ja-JP/cli/plugins.md index 7b8d81acd..b81f3b827 100644 --- a/docs/ja-JP/cli/plugins.md +++ b/docs/ja-JP/cli/plugins.md @@ -1,36 +1,36 @@ --- read_when: - - Gateway plugins または互換バンドルをインストールまたは管理したい場合 - - Pluginの読み込み失敗をデバッグしたい場合 + - Gateway Plugin または互換バンドルをインストールまたは管理したい + - Plugin の読み込み失敗をデバッグしたい場合 sidebarTitle: Plugins summary: '`openclaw plugins` の CLI リファレンス（list、install、marketplace、uninstall、enable/disable、doctor）' title: Plugin x-i18n: - generated_at: "2026-05-04T09:37:13Z" + generated_at: "2026-05-05T01:44:23Z" model: gpt-5.5 provider: openai - source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4 + source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a source_path: cli/plugins.md workflow: 16 --- -Gateway プラグイン、フックパック、互換バンドルを管理します。 +Gateway Plugin、フックパック、互換バンドルを管理します。 - - プラグインのインストール、有効化、トラブルシューティングに関するエンドユーザー向けガイド。 + + Pluginのインストール、有効化、トラブルシューティングのエンドユーザー向けガイド。 - - インストール、一覧表示、更新、アンインストール、公開の簡単な例。 + + インストール、一覧表示、更新、アンインストール、公開のクイック例。 - + バンドル互換性モデル。 - + マニフェストフィールドと設定スキーマ。 - プラグインインストールのセキュリティ強化。 + Pluginインストールのセキュリティ強化。 @@ -63,15 +63,15 @@ openclaw plugins marketplace list --json ``` 低速なインストール、検査、アンインストール、またはレジストリ更新の調査では、 -`OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` を付けてコマンドを実行します。トレースはフェーズごとのタイミングを -stderr に書き込み、JSON 出力を解析可能なまま保ちます。[デバッグ](/ja-JP/help/debugging#plugin-lifecycle-trace)を参照してください。 +`OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` を指定してコマンドを実行します。トレースはフェーズごとの所要時間を +stderr に書き込み、JSON出力を解析可能なままにします。[デバッグ](/ja-JP/help/debugging#plugin-lifecycle-trace)を参照してください。 -バンドル済みプラグインは OpenClaw に同梱されています。一部はデフォルトで有効です（たとえば、バンドル済みモデルプロバイダー、バンドル済み音声プロバイダー、バンドル済みブラウザプラグイン）。それ以外は `plugins enable` が必要です。 +バンドル済みPluginはOpenClawに同梱されています。一部はデフォルトで有効です（たとえば、バンドル済みモデルプロバイダー、バンドル済み音声プロバイダー、バンドル済みブラウザーPlugin）。それ以外は `plugins enable` が必要です。 -ネイティブ OpenClaw プラグインは、インライン JSON スキーマ（空であっても `configSchema`）を含む `openclaw.plugin.json` を同梱する必要があります。互換バンドルは代わりに独自のバンドルマニフェストを使用します。 +ネイティブOpenClaw Pluginは、インラインJSON Schema（空でも `configSchema`）を含む `openclaw.plugin.json` を同梱する必要があります。互換バンドルは、代わりに独自のバンドルマニフェストを使用します。 -`plugins list` は `Format: openclaw` または `Format: bundle` を表示します。詳細な一覧/情報出力には、バンドルのサブタイプ（`codex`、`claude`、または `cursor`）と、検出されたバンドル機能も表示されます。 +`plugins list` は `Format: openclaw` または `Format: bundle` を表示します。詳細な一覧/info出力では、バンドルのサブタイプ（`codex`、`claude`、または `cursor`）と、検出されたバンドル機能も表示されます。 ### インストール @@ -93,105 +93,108 @@ openclaw plugins install --marketplace https://github.com// -接頭辞なしのパッケージ名は、ローンチ切り替え期間中はデフォルトで npm からインストールされます。ClawHub には `clawhub:` を使用してください。プラグインのインストールはコードの実行と同じように扱ってください。ピン留めされたバージョンを優先してください。 +裸のパッケージ名は、ローンチ移行期間中はデフォルトでnpmからインストールされます。ClawHubには `clawhub:` を使用してください。Pluginのインストールは、コードを実行するものとして扱ってください。固定バージョンを推奨します。 -`plugins search` は ClawHub に対してインストール可能なプラグインパッケージを問い合わせ、インストール可能なパッケージ名を出力します。検索対象はコードプラグインとバンドルプラグインのパッケージであり、Skills ではありません。ClawHub Skills には `openclaw skills search` を使用してください。 +`plugins search` は、インストール可能なPluginパッケージをClawHubに問い合わせ、 +インストール可能なパッケージ名を出力します。検索対象はコードPluginとバンドルPluginのパッケージであり、 +Skillsではありません。ClawHub Skillsには `openclaw skills search` を使用してください。 -ClawHub は、ほとんどのプラグインにとって主要な配布および発見の場です。npm -は引き続き、サポートされるフォールバックおよび直接インストール経路です。OpenClaw 所有の -`@openclaw/*` プラグインパッケージは npm で再び公開されています。現在の一覧は +ClawHubは、ほとんどのPluginにおける主要な配布および発見サーフェスです。Npmは +サポート対象のフォールバックおよび直接インストール経路として残ります。OpenClaw所有の +`@openclaw/*` Pluginパッケージはnpmで再び公開されています。現在の一覧は [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) または -[プラグインインベントリ](/ja-JP/plugins/plugin-inventory)を参照してください。安定版のインストールでは `latest` を使用します。 -ベータチャンネルのインストールと更新では、そのタグが利用可能な場合は npm の `beta` dist-tag を優先し、その後 `latest` にフォールバックします。 +[Pluginインベントリ](/ja-JP/plugins/plugin-inventory)を参照してください。安定版インストールは `latest` を使用します。 +ベータチャンネルのインストールと更新では、そのタグが利用可能な場合はnpmの `beta` dist-tagを優先し、 +その後 `latest` にフォールバックします。 - - `plugins` セクションが単一ファイルの `$include` を基にしている場合、`plugins install/update/enable/disable/uninstall` はそのインクルード先ファイルに書き込み、`openclaw.json` は変更しません。ルートのインクルード、インクルード配列、兄弟オーバーライドを伴うインクルードは、平坦化される代わりに安全側に失敗します。サポートされる形については、[設定インクルード](/ja-JP/gateway/configuration)を参照してください。 + + `plugins` セクションが単一ファイルの `$include` によって裏付けられている場合、`plugins install/update/enable/disable/uninstall` はそのinclude先ファイルに書き込み、`openclaw.json` は変更しません。ルートinclude、include配列、兄弟オーバーライドを伴うincludeは、平坦化せずにフェイルクローズします。サポートされる形については、[設定include](/ja-JP/gateway/configuration)を参照してください。 - インストール中に設定が無効な場合、`plugins install` は通常安全側に失敗し、まず `openclaw doctor --fix` を実行するよう指示します。Gateway 起動時およびホットリロード時には、無効なプラグイン設定は他の無効な設定と同様に安全側に失敗します。`openclaw doctor --fix` は無効なプラグインエントリーを隔離できます。インストール時の例外として文書化されているのは、`openclaw.install.allowInvalidConfigRecovery` に明示的にオプトインしたプラグイン向けの、限定的なバンドル済みプラグイン回復パスだけです。 + インストール中に設定が無効な場合、`plugins install` は通常フェイルクローズし、先に `openclaw doctor --fix` を実行するよう通知します。Gateway起動時およびホットリロード時には、無効なPlugin設定は他の無効な設定と同様にフェイルクローズします。`openclaw doctor --fix` は無効なPluginエントリを隔離できます。文書化されている唯一のインストール時例外は、`openclaw.install.allowInvalidConfigRecovery` に明示的にオプトインしたPlugin向けの限定的なバンドル済みPlugin復旧経路です。 - - `--force` は既存のインストール先を再利用し、すでにインストールされているプラグインまたはフックパックをその場で上書きします。同じ id を新しいローカルパス、アーカイブ、ClawHub パッケージ、または npm アーティファクトから意図的に再インストールするときに使用します。すでに追跡されている npm プラグインの通常のアップグレードには、`openclaw plugins update ` を優先してください。 + + `--force` は既存のインストール先を再利用し、すでにインストール済みのPluginまたはフックパックをその場で上書きします。同じidを新しいローカルパス、アーカイブ、ClawHubパッケージ、またはnpmアーティファクトから意図的に再インストールする場合に使用します。すでに追跡されているnpm Pluginの通常のアップグレードには、`openclaw plugins update ` を推奨します。 - すでにインストール済みのプラグイン id に対して `plugins install` を実行すると、OpenClaw は停止し、通常のアップグレードには `plugins update ` を案内し、現在のインストールを別のソースから本当に上書きしたい場合には `plugins install --force` を案内します。 + すでにインストール済みのPlugin idに対して `plugins install` を実行すると、OpenClawは停止し、通常のアップグレードには `plugins update ` を、現在のインストールを別のソースから本当に上書きする場合には `plugins install --force` を案内します。 - - `--pin` は npm インストールのみに適用されます。`git:` インストールではサポートされていません。ソースをピン留めしたい場合は、`git:github.com/acme/plugin@v1.2.3` のような明示的な git 参照を使用してください。`--marketplace` でもサポートされていません。マーケットプレイスインストールでは、npm 指定ではなくマーケットプレイスソースメタデータを永続化するためです。 + + `--pin` はnpmインストールにのみ適用されます。`git:` インストールではサポートされません。固定ソースが必要な場合は、`git:github.com/acme/plugin@v1.2.3` のような明示的なgit refを使用してください。`--marketplace` でもサポートされません。marketplaceインストールはnpm specではなく、marketplaceソースメタデータを保持するためです。 - `--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーによる誤検知に対する非常時用オプションです。組み込みスキャナーが `critical` の検出結果を報告した場合でもインストールを続行できますが、プラグインの `before_install` フックポリシーブロックは**バイパスせず**、スキャン失敗も**バイパスしません**。 + `--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーの誤検知に対する非常用オプションです。組み込みスキャナーが `critical` 所見を報告した場合でもインストールの継続を許可しますが、Pluginの `before_install` フックポリシーブロックはバイパス**せず**、スキャン失敗もバイパス**しません**。 - この CLI フラグはプラグインのインストール/更新フローに適用されます。Gateway が背後で行う Skills の依存関係インストールでは対応する `dangerouslyForceUnsafeInstall` リクエストオーバーライドを使用し、`openclaw skills install` は引き続き別個の ClawHub Skills ダウンロード/インストールフローです。 + このCLIフラグはPluginのインストール/更新フローに適用されます。GatewayバックのSkill依存関係インストールでは対応する `dangerouslyForceUnsafeInstall` リクエストオーバーライドを使用します。一方、`openclaw skills install` は別個のClawHub Skillダウンロード/インストールフローのままです。 - ClawHub で公開したプラグインがレジストリスキャンによってブロックされた場合は、[ClawHub](/ja-JP/tools/clawhub)の公開者向け手順を使用してください。 + ClawHubで公開したPluginがレジストリスキャンによってブロックされる場合は、[ClawHub](/ja-JP/tools/clawhub)の公開者向け手順を使用してください。 - - `plugins install` は、`package.json` で `openclaw.hooks` を公開するフックパックのインストール窓口でもあります。フィルタリングされたフックの表示とフックごとの有効化には `openclaw hooks` を使用し、パッケージインストールには使用しません。 + + `plugins install` は、`package.json` で `openclaw.hooks` を公開するフックパックのインストールサーフェスでもあります。パッケージのインストールではなく、フィルター済みのフック可視性とフックごとの有効化には `openclaw hooks` を使用してください。 - npm の指定は**レジストリのみ**です（パッケージ名 + 任意の**正確なバージョン**または**dist-tag**）。Git/URL/file 指定と semver 範囲は拒否されます。依存関係のインストールは、安全のためプロジェクトローカルで `--ignore-scripts` 付きで実行されます。シェルにグローバル npm インストール設定がある場合でも同様です。 + Npm specは**レジストリ専用**です（パッケージ名 + 任意の**正確なバージョン**または**dist-tag**）。Git/URL/file specおよびsemver範囲は拒否されます。依存関係のインストールは、シェルにグローバルnpmインストール設定がある場合でも、安全のため `--ignore-scripts` 付きでプロジェクトローカルに実行されます。 - npm の解決を明示したい場合は `npm:` を使用します。接頭辞なしのパッケージ指定も、ローンチ切り替え期間中は npm から直接インストールされます。 + npm解決を明示したい場合は `npm:` を使用してください。裸のパッケージspecも、ローンチ移行期間中はnpmから直接インストールされます。 - 接頭辞なしの指定と `@latest` は安定版トラックに留まります。`2026.5.3-1` のような OpenClaw の日付スタンプ付き修正版バージョンは、このチェックでは安定版リリースです。npm がそれらのいずれかをプレリリースに解決した場合、OpenClaw は停止し、`@beta`/`@rc` のようなプレリリースタグ、または `@1.2.3-beta.4` のような正確なプレリリースバージョンで明示的にオプトインするよう求めます。 + 裸のspecと `@latest` は安定版トラックに留まります。`2026.5.3-1` のようなOpenClawの日付付き修正版は、このチェックでは安定版リリースです。npmがそれらのいずれかをプレリリースに解決した場合、OpenClawは停止し、`@beta`/`@rc` のようなプレリリースタグ、または `@1.2.3-beta.4` のような正確なプレリリースバージョンで明示的にオプトインするよう求めます。 - 接頭辞なしのインストール指定が公式プラグイン id（たとえば `diffs`）と一致する場合、OpenClaw はカタログエントリーを直接インストールします。同じ名前の npm パッケージをインストールするには、明示的なスコープ付き指定（たとえば `@scope/diffs`）を使用してください。 + 裸のインストールspecが公式Plugin id（たとえば `diffs`）と一致する場合、OpenClawはカタログエントリを直接インストールします。同じ名前のnpmパッケージをインストールするには、明示的なスコープ付きspec（たとえば `@scope/diffs`）を使用してください。 - - git リポジトリから直接インストールするには `git:` を使用します。サポートされる形式には、`git:github.com/owner/repo`、`git:owner/repo`、完全な `https://`、`ssh://`、`git://`、`file://`、および `git@host:owner/repo.git` のクローン URL が含まれます。インストール前にブランチ、タグ、またはコミットをチェックアウトするには、`@` または `#` を追加します。 + + gitリポジトリから直接インストールするには `git:` を使用します。サポートされる形式には、`git:github.com/owner/repo`、`git:owner/repo`、完全な `https://`、`ssh://`、`git://`、`file://`、および `git@host:owner/repo.git` クローンURLが含まれます。インストール前にブランチ、タグ、またはコミットをチェックアウトするには、`@` または `#` を追加します。 - Git インストールでは一時ディレクトリにクローンし、要求された参照がある場合はそれをチェックアウトしてから、通常のプラグインディレクトリインストーラーを使用します。つまり、マニフェスト検証、危険コードスキャン、パッケージマネージャーによるインストール処理、インストール記録は npm インストールと同様に動作します。記録された git インストールには、ソース URL/参照に加えて解決済みコミットが含まれるため、`openclaw plugins update` は後でソースを再解決できます。 + Gitインストールは一時ディレクトリにクローンし、指定されたrefがある場合はそれをチェックアウトしてから、通常のPluginディレクトリインストーラーを使用します。つまり、マニフェスト検証、危険コードスキャン、パッケージマネージャーのインストール作業、インストールレコードはnpmインストールと同じように動作します。記録されたgitインストールには、ソースURL/refと解決済みコミットが含まれるため、後で `openclaw plugins update` がソースを再解決できます。 - git からインストールした後は、`openclaw plugins inspect --runtime --json` を使用して、gateway メソッドや CLI コマンドなどのランタイム登録を検証します。プラグインが `api.registerCli` で CLI ルートを登録した場合は、そのコマンドを OpenClaw ルート CLI から直接実行します。たとえば `openclaw demo-plugin ping` です。 + gitからインストールした後、GatewayメソッドやCLIコマンドなどのランタイム登録を確認するには、`openclaw plugins inspect --runtime --json` を使用します。Pluginが `api.registerCli` でCLIルートを登録した場合は、たとえば `openclaw demo-plugin ping` のように、そのコマンドをOpenClawルートCLI経由で直接実行します。 - サポートされるアーカイブ: `.zip`、`.tgz`、`.tar.gz`、`.tar`。ネイティブ OpenClaw プラグインアーカイブには、展開されたプラグインルートに有効な `openclaw.plugin.json` が含まれている必要があります。`package.json` だけを含むアーカイブは、OpenClaw がインストール記録を書き込む前に拒否されます。 + サポートされるアーカイブ: `.zip`、`.tgz`、`.tar.gz`、`.tar`。ネイティブOpenClaw Pluginアーカイブには、展開後のPluginルートに有効な `openclaw.plugin.json` が含まれている必要があります。`package.json` だけを含むアーカイブは、OpenClawがインストールレコードを書き込む前に拒否されます。 - Claude マーケットプレイスのインストールもサポートされています。 + Claude marketplaceインストールもサポートされています。 -ClawHub インストールでは、明示的な `clawhub:` ロケーターを使用します。 +ClawHubインストールは、明示的な `clawhub:` ロケーターを使用します。 ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -接頭辞なしの npm 対応プラグイン指定は、ローンチ切り替え期間中はデフォルトで npm からインストールされます。 +裸のnpmセーフなPlugin specは、ローンチ移行期間中はデフォルトでnpmからインストールされます。 ```bash openclaw plugins install openclaw-codex-app-server ``` -npm のみの解決を明示するには `npm:` を使用します。 +npm専用解決を明示するには `npm:` を使用します。 ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw は、インストール前に公表されているプラグイン API / 最小 Gateway 互換性を確認します。選択された ClawHub バージョンが ClawPack アーティファクトを公開している場合、OpenClaw はバージョン付き npm-pack `.tgz` をダウンロードし、ClawHub ダイジェストヘッダーとアーティファクトダイジェストを検証してから、通常のアーカイブパスでインストールします。ClawPack メタデータのない古い ClawHub バージョンは、従来のパッケージアーカイブ検証パスで引き続きインストールされます。記録されたインストールは、後続の更新のために ClawHub ソースメタデータ、アーティファクト種別、npm integrity、npm shasum、tarball 名、ClawPack ダイジェスト情報を保持します。 -バージョン指定なしの ClawHub インストールは、バージョン指定なしの記録済み指定を保持するため、`openclaw plugins update` は新しい ClawHub リリースを追跡できます。`clawhub:pkg@1.2.3` や `clawhub:pkg@beta` のような明示的なバージョンまたはタグセレクターは、そのセレクターにピン留めされたままです。 +OpenClawは、インストール前に公開されているPlugin API / 最小Gateway互換性を確認します。選択されたClawHubバージョンがClawPackアーティファクトを公開している場合、OpenClawはバージョン付きnpm-pack `.tgz` をダウンロードし、ClawHubダイジェストヘッダーとアーティファクトダイジェストを検証してから、通常のアーカイブ経路でインストールします。ClawPackメタデータのない古いClawHubバージョンは、引き続き従来のパッケージアーカイブ検証経路でインストールされます。記録されたインストールは、後の更新のために、ClawHubソースメタデータ、アーティファクト種別、npm integrity、npm shasum、tarball名、ClawPackダイジェスト情報を保持します。 +バージョンなしのClawHubインストールは、`openclaw plugins update` が新しいClawHubリリースを追跡できるよう、バージョンなしの記録済みspecを保持します。`clawhub:pkg@1.2.3` や `clawhub:pkg@beta` のような明示的なバージョンまたはタグセレクターは、そのセレクターに固定されたままです。 -#### マーケットプレイスの省略記法 +#### Marketplace省略記法 -マーケットプレイス名が Claude のローカルレジストリキャッシュ `~/.claude/plugins/known_marketplaces.json` に存在する場合は、`plugin@marketplace` 省略記法を使用します。 +Claudeのローカルレジストリキャッシュ `~/.claude/plugins/known_marketplaces.json` にmarketplace名が存在する場合は、`plugin@marketplace` 省略記法を使用します。 ```bash openclaw plugins marketplace list openclaw plugins install @ ``` -マーケットプレイスソースを明示的に渡したい場合は `--marketplace` を使用します。 +marketplaceソースを明示的に渡したい場合は、`--marketplace` を使用します。 ```bash openclaw plugins install --marketplace @@ -203,26 +206,26 @@ openclaw plugins install --marketplace ./my-marketplace - `~/.claude/plugins/known_marketplaces.json` にある Claude の既知マーケットプレイス名 - - ローカルマーケットプレイスルートまたは `marketplace.json` パス - - `owner/repo` などの GitHub リポジトリ省略表記 - - `https://github.com/owner/repo` などの GitHub リポジトリ URL + - ローカルマーケットプレイスのルート、または `marketplace.json` パス + - `owner/repo` のような GitHub リポジトリ短縮形 + - `https://github.com/owner/repo` のような GitHub リポジトリ URL - git URL - GitHub または git から読み込まれるリモートマーケットプレイスでは、plugin エントリはクローンされたマーケットプレイスリポジトリ内に留まる必要があります。OpenClaw はそのリポジトリからの相対パスソースを受け入れ、リモートマニフェスト内の HTTP(S)、絶対パス、git、GitHub、およびその他の非パス plugin ソースを拒否します。 + GitHub または git から読み込まれるリモートマーケットプレイスでは、Plugin エントリはクローンされたマーケットプレイスリポジトリ内に留まる必要があります。OpenClaw はそのリポジトリからの相対パスソースを受け入れ、リモートマニフェスト内の HTTP(S)、絶対パス、git、GitHub、その他の非パス Plugin ソースを拒否します。 ローカルパスとアーカイブについて、OpenClaw は次を自動検出します。 -- ネイティブ OpenClaw plugins（`openclaw.plugin.json`） +- ネイティブ OpenClaw Plugin（`openclaw.plugin.json`） - Codex 互換バンドル（`.codex-plugin/plugin.json`） - Claude 互換バンドル（`.claude-plugin/plugin.json` またはデフォルトの Claude コンポーネントレイアウト） - Cursor 互換バンドル（`.cursor-plugin/plugin.json`） -互換バンドルは通常の plugin ルートにインストールされ、同じ list/info/enable/disable フローに参加します。現時点では、バンドル Skills、Claude コマンド Skills、Claude `settings.json` デフォルト、Claude `.lsp.json` / マニフェスト宣言の `lspServers` デフォルト、Cursor コマンド Skills、互換 Codex フックディレクトリがサポートされています。検出されたその他のバンドル機能は diagnostics/info に表示されますが、まだランタイム実行には接続されていません。 +互換バンドルは通常の Plugin ルートにインストールされ、同じ一覧/情報/有効化/無効化フローに参加します。現在、バンドル Skills、Claude コマンド Skills、Claude `settings.json` デフォルト、Claude `.lsp.json` / マニフェスト宣言の `lspServers` デフォルト、Cursor コマンド Skills、互換 Codex hook ディレクトリがサポートされています。その他の検出済みバンドル機能は診断/情報に表示されますが、まだランタイム実行には接続されていません。 ### 一覧 @@ -238,30 +241,30 @@ openclaw plugins search --json ``` - 有効化された plugins のみを表示します。 + 有効化されている Plugin のみを表示します。 - テーブル表示から、ソース/出所/バージョン/有効化メタデータを含む plugin ごとの詳細行に切り替えます。 + テーブル表示から、ソース/出所/バージョン/アクティベーションメタデータを含む Plugin ごとの詳細行に切り替えます。 - 機械可読のインベントリに加えて、レジストリ diagnostics とパッケージ依存関係のインストール状態を出力します。 + 機械可読のインベントリに加えて、レジストリ診断とパッケージ依存関係のインストール状態を出力します。 -`plugins list` はまず永続化されたローカル plugin レジストリを読み込み、レジストリがないか無効な場合はマニフェストのみから派生したフォールバックを使います。plugin がインストール済み、有効化済み、コールドスタート計画で可視かどうかを確認するのに便利ですが、すでに実行中の Gateway プロセスに対するライブランタイムプローブではありません。plugin コード、有効化、フックポリシー、または `plugins.load.paths` を変更した後は、新しい `register(api)` コードやフックの実行を期待する前に、そのチャンネルを提供する Gateway を再起動してください。リモート/コンテナデプロイでは、ラッパープロセスだけでなく、実際の `openclaw gateway run` 子プロセスを再起動していることを確認してください。 +`plugins list` はまず永続化されたローカル Plugin レジストリを読み取り、レジストリがないか無効な場合はマニフェストのみから派生したフォールバックを使います。Plugin がインストール済み、有効化済み、かつコールドスタート計画から見えるかを確認するのに役立ちますが、すでに実行中の Gateway プロセスに対するライブランタイムプローブではありません。Plugin コード、有効化状態、hook ポリシー、または `plugins.load.paths` を変更した後は、新しい `register(api)` コードや hook の実行を期待する前に、そのチャネルを提供している Gateway を再起動してください。リモート/コンテナデプロイでは、ラッパープロセスだけでなく、実際の `openclaw gateway run` 子プロセスを再起動していることを確認してください。 -`plugins list --json` には、`package.json` の `dependencies` と `optionalDependencies` から各 plugin の `dependencyStatus` が含まれます。OpenClaw は、それらのパッケージ名が plugin の通常の Node `node_modules` ルックアップパス上に存在するかを確認します。plugin ランタイムコードのインポート、パッケージマネージャーの実行、欠落依存関係の修復は行いません。 +`plugins list --json` には、`package.json` の `dependencies` と `optionalDependencies` から得た各 Plugin の `dependencyStatus` が含まれます。OpenClaw は、それらのパッケージ名が Plugin の通常の Node `node_modules` 参照パス上に存在するかを確認します。Plugin ランタイムコードのインポート、パッケージマネージャーの実行、欠落した依存関係の修復は行いません。 -`plugins search` はリモート ClawHub カタログ検索です。ローカル状態の検査、設定の変更、パッケージのインストール、plugin ランタイムコードの読み込みは行いません。検索結果には、ClawHub パッケージ名、ファミリー、チャンネル、バージョン、概要、および `openclaw plugins install clawhub:` などのインストールヒントが含まれます。 +`plugins search` はリモートの ClawHub カタログ検索です。ローカル状態の検査、config の変更、パッケージのインストール、Plugin ランタイムコードの読み込みは行いません。検索結果には、ClawHub パッケージ名、ファミリー、チャネル、バージョン、概要、および `openclaw plugins install clawhub:` のようなインストールヒントが含まれます。 -パッケージ化された Docker イメージ内でバンドル plugin 作業を行うには、plugin ソースディレクトリを、`/app/extensions/synology-chat` などの対応するパッケージ済みソースパスに bind-mount します。OpenClaw は `/app/dist/extensions/synology-chat` より前に、そのマウントされたソースオーバーレイを検出します。単にコピーされたソースディレクトリは無効なままなので、通常のパッケージ済みインストールでは引き続きコンパイル済み dist が使用されます。 +パッケージ化された Docker イメージ内でバンドル Plugin を扱う場合は、Plugin ソースディレクトリを、対応するパッケージ済みソースパス（例: `/app/extensions/synology-chat`）の上に bind-mount します。OpenClaw は `/app/dist/extensions/synology-chat` より前に、そのマウントされたソースオーバーレイを検出します。単にコピーされたソースディレクトリは不活性なままなので、通常のパッケージ済みインストールは引き続きコンパイル済み dist を使います。 -ランタイムフックのデバッグには次を使います。 +ランタイム hook のデバッグでは、次を使用します。 -- `openclaw plugins inspect --runtime --json` は、モジュール読み込み検査パスから登録済みフックと diagnostics を表示します。ランタイム検査が依存関係をインストールすることはありません。レガシー依存関係状態をクリーンアップするか、欠落している設定済みダウンロード可能 plugins をインストールするには、`openclaw doctor --fix` を使ってください。 -- `openclaw gateway status --deep --require-rpc` は、到達可能な Gateway、サービス/プロセスヒント、設定パス、RPC ヘルスを確認します。 -- 非バンドルの会話フック（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）には `plugins.entries..hooks.allowConversationAccess=true` が必要です。 +- `openclaw plugins inspect --runtime --json` は、モジュール読み込み検査パスから登録済み hook と診断を表示します。ランタイム検査は依存関係をインストールしません。レガシー依存関係状態の整理や、config で参照されている欠落したダウンロード可能 Plugin の復旧には `openclaw doctor --fix` を使います。 +- `openclaw gateway status --deep --require-rpc` は、到達可能な Gateway、サービス/プロセスのヒント、config パス、RPC ヘルスを確認します。 +- 非バンドルの会話 hook（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）には `plugins.entries..hooks.allowConversationAccess=true` が必要です。 ローカルディレクトリのコピーを避けるには `--link` を使います（`plugins.load.paths` に追加されます）。 @@ -270,16 +273,16 @@ openclaw plugins install -l ./my-plugin ``` -リンクされたインストールは管理対象インストール先にコピーする代わりにソースパスを再利用するため、`--force` は `--link` と併用できません。 +リンクインストールは管理対象のインストール先へコピーする代わりにソースパスを再利用するため、`--force` は `--link` と併用できません。 -npm インストールで `--pin` を使うと、デフォルト動作はピン留めなしのまま、解決された正確な spec（`name@version`）を管理対象 plugin インデックスに保存します。 +npm インストールで `--pin` を使うと、デフォルト動作をピン留めなしのままにしつつ、解決された正確な spec（`name@version`）を管理対象 Plugin インデックスに保存できます。 ### Plugin インデックス -Plugin インストールメタデータは、ユーザー設定ではなく機械管理状態です。インストールと更新は、それをアクティブな OpenClaw 状態ディレクトリ配下の `plugins/installs.json` に書き込みます。最上位の `installRecords` マップは、壊れた plugin マニフェストや欠落した plugin マニフェストのレコードを含む、インストールメタデータの永続的なソースです。`plugins` 配列は、マニフェスト由来のコールドレジストリキャッシュです。このファイルには編集禁止の警告が含まれ、`openclaw plugins update`、アンインストール、diagnostics、コールド plugin レジストリで使用されます。 +Plugin インストールメタデータは機械管理の状態であり、ユーザー config ではありません。インストールと更新は、アクティブな OpenClaw state ディレクトリ配下の `plugins/installs.json` に書き込みます。そのトップレベルの `installRecords` マップは、壊れた Plugin マニフェストや欠落した Plugin マニフェストのレコードを含む、インストールメタデータの永続的なソースです。`plugins` 配列は、マニフェストから派生したコールドレジストリキャッシュです。このファイルには編集禁止の警告が含まれ、`openclaw plugins update`、アンインストール、診断、コールド Plugin レジストリで使用されます。 -OpenClaw が設定内の出荷済みレガシー `plugins.installs` レコードを見つけると、それらを plugin インデックスへ移動し、設定キーを削除します。どちらかの書き込みに失敗した場合、インストールメタデータが失われないよう、設定レコードは保持されます。 +OpenClaw が config 内に出荷済みのレガシー `plugins.installs` レコードを見つけると、それらを Plugin インデックスへ移動し、config キーを削除します。どちらかの書き込みが失敗した場合、インストールメタデータが失われないように config レコードは保持されます。 ### アンインストール @@ -289,10 +292,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` は、`plugins.entries`、永続化された plugin インデックス、plugin 許可/拒否リストエントリ、および該当する場合はリンクされた `plugins.load.paths` エントリから plugin レコードを削除します。`--keep-files` が設定されていない限り、アンインストールは、追跡対象の管理対象インストールディレクトリが OpenClaw の plugin extensions ルート内にある場合、そのディレクトリも削除します。active memory plugins では、メモリスロットが `memory-core` にリセットされます。 +`uninstall` は、`plugins.entries`、永続化された Plugin インデックス、Plugin 許可/拒否リストエントリ、および該当する場合はリンクされた `plugins.load.paths` エントリから Plugin レコードを削除します。`--keep-files` が設定されていない限り、アンインストールは、OpenClaw の Plugin extensions ルート内にある追跡対象の管理インストールディレクトリも削除します。Active Memory Plugin の場合、メモリスロットは `memory-core` にリセットされます。 -`--keep-config` は `--keep-files` の非推奨エイリアスとしてサポートされています。 +`--keep-config` は、非推奨の `--keep-files` エイリアスとしてサポートされています。 ### 更新 @@ -305,29 +308,29 @@ openclaw plugins update @openclaw/voice-call openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -更新は、管理対象 plugin インデックス内の追跡対象 plugin インストールと、`hooks.internal.installs` 内の追跡対象 hook-pack インストールに適用されます。 +更新は、管理対象 Plugin インデックス内の追跡対象 Plugin インストールと、`hooks.internal.installs` 内の追跡対象 hook-pack インストールに適用されます。 - - plugin id を渡すと、OpenClaw はその plugin に記録されたインストール spec を再利用します。つまり、以前に保存された `@beta` などの dist-tags や正確にピン留めされたバージョンは、以後の `update ` 実行でも引き続き使用されます。 + + Plugin id を渡すと、OpenClaw はその Plugin に記録されているインストール spec を再利用します。つまり、以前に保存された `@beta` のような dist-tag や正確にピン留めされたバージョンは、後続の `update ` 実行でも引き続き使用されます。 - npm インストールでは、dist-tag または正確なバージョンを含む明示的な npm パッケージ spec を渡すこともできます。OpenClaw はそのパッケージ名を追跡対象 plugin レコードに解決し、そのインストール済み plugin を更新して、将来の id ベース更新用に新しい npm spec を記録します。 + npm インストールでは、dist-tag または正確なバージョンを含む明示的な npm パッケージ spec を渡すこともできます。OpenClaw はそのパッケージ名を追跡対象の Plugin レコードに解決し直し、そのインストール済み Plugin を更新して、今後の id ベース更新用に新しい npm spec を記録します。 - バージョンやタグなしで npm パッケージ名を渡した場合も、追跡対象 plugin レコードに解決されます。plugin が正確なバージョンにピン留めされていて、レジストリのデフォルトリリースラインに戻したい場合にこれを使います。 + バージョンやタグなしで npm パッケージ名を渡した場合も、追跡対象の Plugin レコードに解決されます。Plugin が正確なバージョンにピン留めされており、レジストリのデフォルトリリースラインへ戻したい場合に使います。 - - `openclaw plugins update` は、新しい spec を渡さない限り、追跡対象の plugin spec を再利用します。`openclaw update` はさらに、アクティブな OpenClaw 更新チャンネルを認識します。ベータチャンネルでは、デフォルトラインの npm および ClawHub plugin レコードは最初に `@beta` を試し、plugin ベータリリースが存在しない場合は記録済みの default/latest spec にフォールバックします。正確なバージョンと明示的なタグは、そのセレクタにピン留めされたままです。 + + `openclaw plugins update` は、新しい spec を渡さない限り、追跡対象の Plugin spec を再利用します。`openclaw update` はさらに、アクティブな OpenClaw 更新チャネルを認識します。ベータチャネルでは、デフォルトラインの npm および ClawHub Plugin レコードはまず `@beta` を試し、Plugin のベータリリースが存在しない場合は、記録済みのデフォルト/latest spec にフォールバックします。正確なバージョンと明示的なタグは、そのセレクターにピン留めされたままです。 - ライブ npm 更新の前に、OpenClaw はインストール済みパッケージバージョンを npm レジストリメタデータと照合します。インストール済みバージョンと記録済みアーティファクト ID がすでに解決済みターゲットと一致している場合、ダウンロード、再インストール、`openclaw.json` の書き換えを行わずに更新はスキップされます。 + ライブ npm 更新の前に、OpenClaw はインストール済みパッケージバージョンを npm レジストリメタデータと照合します。インストール済みバージョンと記録済みアーティファクト ID が解決済みターゲットとすでに一致している場合、ダウンロード、再インストール、`openclaw.json` の再書き込みを行わずに更新はスキップされます。 - 保存済みの integrity ハッシュが存在し、取得したアーティファクトハッシュが変わった場合、OpenClaw はそれを npm アーティファクトドリフトとして扱います。対話型の `openclaw plugins update` コマンドは、期待されるハッシュと実際のハッシュを表示し、続行前に確認を求めます。非対話型の更新ヘルパーは、呼び出し元が明示的な継続ポリシーを指定しない限り、安全側で失敗します。 + 保存された integrity ハッシュが存在し、取得したアーティファクトハッシュが変わった場合、OpenClaw はそれを npm アーティファクトドリフトとして扱います。対話型の `openclaw plugins update` コマンドは、期待されるハッシュと実際のハッシュを出力し、続行前に確認を求めます。非対話型の更新ヘルパーは、呼び出し元が明示的な継続ポリシーを指定しない限り fail closed します。 - `--dangerously-force-unsafe-install` は、plugin 更新中に組み込みの危険コードスキャンが誤検出した場合の非常用オーバーライドとして、`plugins update` でも利用できます。ただし、plugin の `before_install` ポリシーブロックやスキャン失敗によるブロックは引き続きバイパスされず、plugin 更新にのみ適用され、hook-pack 更新には適用されません。 + `--dangerously-force-unsafe-install` は、Plugin 更新中に組み込みの dangerous-code スキャンで偽陽性が出た場合の緊急用オーバーライドとして、`plugins update` でも利用できます。ただし、Plugin の `before_install` ポリシーブロックやスキャン失敗によるブロックは引き続き回避せず、hook-pack 更新ではなく Plugin 更新にのみ適用されます。 @@ -339,21 +342,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -Inspect は、デフォルトでは plugin ランタイムをインポートせずに、ID、読み込み状態、ソース、マニフェスト機能、ポリシーフラグ、diagnostics、インストールメタデータ、バンドル機能、検出された MCP または LSP サーバーサポートを表示します。`--runtime` を追加すると、plugin モジュールを読み込み、登録済みフック、ツール、コマンド、サービス、gateway メソッド、HTTP ルートを含めます。ランタイム検査は欠落している plugin 依存関係を直接報告します。インストールと修復は `openclaw plugins install`、`openclaw plugins update`、`openclaw doctor --fix` に残ります。 +Inspect は、デフォルトでは Plugin ランタイムをインポートせずに、ID、読み込み状態、ソース、マニフェスト機能、ポリシーフラグ、診断、インストールメタデータ、バンドル機能、および検出された MCP または LSP サーバーサポートを表示します。`--runtime` を追加すると、Plugin モジュールを読み込み、登録済み hook、tools、commands、services、gateway methods、HTTP routes を含めます。ランタイム検査は欠落している Plugin 依存関係を直接報告します。インストールと修復は `openclaw plugins install`、`openclaw plugins update`、`openclaw doctor --fix` に留まります。 -Plugin 所有の CLI コマンドは、ルート `openclaw` コマンドグループとしてインストールされます。`inspect --runtime` が `cliCommands` の下にコマンドを表示した後は、`openclaw ...` として実行します。たとえば、`demo-git` を登録する plugin は `openclaw demo-git ping` で検証できます。 +Plugin 所有の CLI コマンドは、ルートの `openclaw` コマンドグループとしてインストールされます。`inspect --runtime` が `cliCommands` 配下にコマンドを表示したら、`openclaw ...` として実行します。たとえば、`demo-git` を登録する Plugin は `openclaw demo-git ping` で検証できます。 -各 plugin は、ランタイムで実際に登録する内容によって分類されます。 +各 Plugin は、ランタイムで実際に登録する内容に基づいて分類されます。 -- **plain-capability** — 1 種類の機能タイプ（例: provider 専用 plugin） -- **hybrid-capability** — 複数の機能タイプ（例: テキスト + 音声 + 画像） -- **hook-only** — フックのみ、機能やサーフェスなし -- **non-capability** — ツール/コマンド/サービスはあるが機能なし +- **plain-capability** — 1 つの capability type（例: provider-only Plugin） +- **hybrid-capability** — 複数の capability type（例: text + speech + images） +- **hook-only** — hook のみで、capabilities や surfaces なし +- **non-capability** — tools/commands/services はあるが capabilities なし -機能モデルの詳細は [Plugin の形態](/ja-JP/plugins/architecture#plugin-shapes) を参照してください。 +capability モデルの詳細は [Plugin 形状](/ja-JP/plugins/architecture#plugin-shapes) を参照してください。 -`--json` フラグは、スクリプトや監査に適した機械可読レポートを出力します。`inspect --all` は、形態、機能の種類、互換性通知、バンドル機能、フック概要の列を含む全体テーブルを表示します。`info` は `inspect` のエイリアスです。 +`--json` フラグは、スクリプト作成と監査に適した機械可読レポートを出力します。`inspect --all` は、shape、capability kinds、compatibility notices、bundle capabilities、hook summary 列を含む全体テーブルを表示します。`info` は `inspect` のエイリアスです。 ### Doctor @@ -362,11 +365,11 @@ Plugin 所有の CLI コマンドは、ルート `openclaw` コマンドグル openclaw plugins doctor ``` -`doctor` は、plugin 読み込みエラー、マニフェスト/検出 diagnostics、互換性通知を報告します。すべて問題がない場合は `No plugin issues detected.` と表示します。 +`doctor` は、Plugin 読み込みエラー、マニフェスト/検出診断、互換性通知を報告します。すべてクリーンな場合は `No plugin issues detected.` を出力します。 -設定済みの plugin がディスク上に存在するものの、ローダーのパス安全性チェックでブロックされている場合、設定検証は plugin エントリを保持し、`present but blocked` として報告します。`plugins.entries.` や `plugins.allow` 設定を削除するのではなく、パス所有権や world-writable 権限など、先行するブロック済み plugin diagnostics を修正してください。 +設定済み Plugin がディスク上に存在するものの、ローダーのパス安全性チェックでブロックされている場合、config バリデーションは Plugin エントリを保持し、`present but blocked` として報告します。`plugins.entries.` や `plugins.allow` config を削除するのではなく、パス所有権や world-writable 権限など、直前の blocked-plugin 診断を修正してください。 -`register`/`activate` エクスポートの欠落などのモジュール形状の失敗では、`OPENCLAW_PLUGIN_LOAD_DEBUG=1` を指定して再実行すると、diagnostic 出力にコンパクトなエクスポート形状の概要が含まれます。 +`register`/`activate` export の欠落などのモジュール形状エラーでは、`OPENCLAW_PLUGIN_LOAD_DEBUG=1` を指定して再実行すると、診断出力にコンパクトな export-shape サマリーが含まれます。 ### レジストリ @@ -376,27 +379,27 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -ローカル plugin レジストリは、インストール済み plugin の ID、有効化、ソースメタデータ、貢献所有権に関する OpenClaw の永続化されたコールド読み取りモデルです。通常の起動、provider 所有者検索、チャンネルセットアップ分類、plugin インベントリは、plugin ランタイムモジュールをインポートせずにこれを読み取れます。 +ローカル Plugin レジストリは、インストール済み Plugin の ID、有効化、ソースメタデータ、コントリビューション所有権に関する OpenClaw の永続化されたコールド読み取りモデルです。通常の起動、プロバイダー所有者ルックアップ、チャネル設定分類、Plugin インベントリは、Plugin ランタイムモジュールをインポートせずにこれを読み取れます。 -`plugins registry` を使用して、永続化されたレジストリが存在するか、最新か、古いかを確認します。`--refresh` を使用すると、永続化された Plugin インデックス、設定ポリシー、manifest/package メタデータから再構築できます。これは修復パスであり、ランタイム有効化パスではありません。 +`plugins registry` を使用して、永続化されたレジストリが存在するか、最新か、古くなっているかを調べます。`--refresh` を使用すると、永続化された Plugin インデックス、設定ポリシー、マニフェスト/package メタデータから再構築できます。これは修復パスであり、ランタイム有効化パスではありません。 -`openclaw doctor --fix` は、レジストリ周辺の管理対象 npm のずれも修復します。管理対象 Plugin npm ルート配下の孤立または復旧された `@openclaw/*` パッケージが同梱 Plugin を隠している場合、doctor はその古いパッケージを削除し、レジストリを再構築して、起動時に同梱 manifest に対して検証されるようにします。 +`openclaw doctor --fix` は、レジストリ周辺の managed npm ドリフトも修復します。managed Plugin npm ルート配下の孤立または復旧された `@openclaw/*` package が bundled Plugin をシャドーしている場合、doctor はその古い package を削除し、レジストリを再構築して、起動時に bundled マニフェストに対して検証されるようにします。 -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` は、レジストリ読み取り失敗時の非推奨の非常用互換スイッチです。`plugins registry --refresh` または `openclaw doctor --fix` を優先してください。この env フォールバックは、移行の展開中に緊急で起動を復旧する場合にのみ使用します。 +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` は、レジストリ読み取り失敗時の非推奨の緊急互換性スイッチです。`plugins registry --refresh` または `openclaw doctor --fix` を優先してください。この env フォールバックは、移行の展開中に緊急で起動を復旧する場合にのみ使用します。 -### Marketplace +### マーケットプレイス ```bash openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Marketplace list は、ローカル Marketplace パス、`marketplace.json` パス、`owner/repo` のような GitHub 省略形、GitHub repo URL、または git URL を受け付けます。`--json` は、解決済みのソースラベルに加えて、解析済みの Marketplace manifest と Plugin エントリを出力します。 +マーケットプレイス一覧は、ローカルのマーケットプレイスパス、`marketplace.json` パス、`owner/repo` のような GitHub 短縮表記、GitHub リポジトリ URL、または git URL を受け付けます。`--json` は、解決済みのソースラベルに加えて、解析済みのマーケットプレイスマニフェストと Plugin エントリを出力します。 ## 関連 - [Plugin の構築](/ja-JP/plugins/building-plugins) - [CLI リファレンス](/ja-JP/cli) -- [Community Plugin](/ja-JP/plugins/community) +- [コミュニティ Plugin](/ja-JP/plugins/community) diff --git a/docs/ja-JP/cli/sessions.md b/docs/ja-JP/cli/sessions.md index dbaa47c78..e354cda62 100644 --- a/docs/ja-JP/cli/sessions.md +++ b/docs/ja-JP/cli/sessions.md @@ -1,13 +1,13 @@ --- read_when: - - 保存済みセッションを一覧表示し、最近のアクティビティを確認したい -summary: '`openclaw sessions` の CLI リファレンス（保存済みセッションの一覧表示 + 使用方法）' + - 保存済みセッションを一覧表示し、最近のアクティビティを確認したい場合 +summary: '`openclaw sessions` の CLI リファレンス（保存済みセッション一覧 + 使用方法）' title: セッション x-i18n: - generated_at: "2026-05-04T07:02:53Z" + generated_at: "2026-05-05T01:44:10Z" model: gpt-5.5 provider: openai - source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e + source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7 source_path: cli/sessions.md workflow: 16 --- @@ -16,37 +16,49 @@ x-i18n: 保存済みの会話セッションを一覧表示します。 -セッション一覧は、チャンネルやプロバイダーの稼働状況チェックではありません。セッションストアから永続化された会話行を表示します。静かな Discord、Slack、Telegram、またはその他のチャンネルは、新しいセッション行を作成しなくても、メッセージが処理されるまで正常に再接続できます。ライブのチャンネル接続性が必要な場合は、`openclaw channels status --probe`、`openclaw status --deep`、または `openclaw health --verbose` を使用してください。 +セッション一覧は channel/provider の生存確認ではありません。セッションストアに永続化された +会話行を表示します。静かな Discord、Slack、Telegram、または +その他のチャンネルは、メッセージが処理されて新しいセッション行が作成されるまでの間も、 +正常に再接続できます。ライブのチャンネル接続性が必要な場合は +`openclaw channels status --probe`、`openclaw status --deep`、または +`openclaw health --verbose` を使用してください。 -Gateway の `sessions.list` レスポンスはデフォルトで制限されているため、大規模で長期間存続するストアが Gateway のイベントループを占有することはありません。別の結果ウィンドウが必要な場合は、RPC クライアントから明示的に正の `limit` を渡してください。呼び出し元がさらに行が存在することを示す必要がある場合、レスポンスには `totalCount`、`limitApplied`、`hasMore` が含まれます。 +`openclaw sessions` と Gateway `sessions.list` のレスポンスは、長期間存続する大規模なストアが CLI プロセスや Gateway +イベントループを占有しないように、デフォルトで上限が設定されています。CLI はデフォルトで最新の 100 セッションを返します。より小さい/大きい範囲にするには +`--limit ` を渡し、意図的にストア全体が必要な場合は `--limit all` を渡してください。JSON レスポンスには、呼び出し元がさらに行が存在することを示す必要がある場合に備えて、`totalCount`、`limitApplied`、および +`hasMore` が含まれます。 ```bash openclaw sessions openclaw sessions --agent work openclaw sessions --all-agents openclaw sessions --active 120 +openclaw sessions --limit 25 openclaw sessions --verbose openclaw sessions --json ``` -スコープ選択: +スコープの選択: -- デフォルト: 設定済みのデフォルトエージェントストア +- default: 設定済みのデフォルトエージェントストア - `--verbose`: 詳細ログ -- `--agent `: 設定済みエージェントストア 1 つ -- `--all-agents`: 設定済みのすべてのエージェントストアを集約 -- `--store `: 明示的なストアパス（`--agent` または `--all-agents` と組み合わせることはできません） +- `--agent `: 1 つの設定済みエージェントストア +- `--all-agents`: すべての設定済みエージェントストアを集約 +- `--store `: 明示的なストアパス（`--agent` または `--all-agents` とは併用不可） +- `--limit `: 出力する最大行数（デフォルトは `100`; `all` は完全な出力に戻します） -保存済みセッションの軌跡バンドルをエクスポートします: +保存済みセッションの trajectory バンドルをエクスポートします: ```bash openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace . openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json ``` -これは、所有者が実行リクエストを承認した後に `/export-trajectory` スラッシュコマンドで使用されるコマンドパスです。出力ディレクトリは常に、選択されたワークスペース配下の `.openclaw/trajectory-exports/` 内に解決されます。 +これは、所有者が exec リクエストを承認した後に `/export-trajectory` スラッシュコマンドで使用されるコマンドパスです。出力ディレクトリは常に、選択したワークスペース配下の +`.openclaw/trajectory-exports/` 内に解決されます。 -`openclaw sessions --all-agents` は設定済みエージェントストアを読み取ります。Gateway と ACP のセッション検出はより広範です。デフォルトの `agents/` ルートまたはテンプレート化された `session.store` ルート配下で見つかった、ディスク上にのみ存在するストアも含まれます。検出されたストアは、エージェントルート内の通常の `sessions.json` ファイルに解決される必要があります。シンボリックリンクとルート外のパスはスキップされます。 +`openclaw sessions --all-agents` は設定済みエージェントストアを読み取ります。Gateway と ACP +のセッション検出はより広範で、デフォルトの `agents/` ルートまたはテンプレート化された `session.store` ルート配下で見つかったディスク上のみのストアも含まれます。検出されたストアは、エージェントルート内の通常の `sessions.json` ファイルに解決される必要があります。シンボリックリンクとルート外パスはスキップされます。 JSON の例: @@ -61,6 +73,9 @@ JSON の例: ], "allAgents": true, "count": 2, + "totalCount": 2, + "limitApplied": 100, + "hasMore": false, "activeMinutes": null, "sessions": [ { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" }, @@ -69,9 +84,9 @@ JSON の例: } ``` -## クリーンアップ保守 +## クリーンアップメンテナンス -次の書き込みサイクルを待たずに、今すぐ保守を実行します: +次の書き込みサイクルを待たずに、今すぐメンテナンスを実行します: ```bash openclaw sessions cleanup --dry-run @@ -84,19 +99,20 @@ openclaw sessions cleanup --json `openclaw sessions cleanup` は設定の `session.maintenance` 設定を使用します: -- スコープの注記: `openclaw sessions cleanup` は、セッションストア、トランスクリプト、軌跡サイドカーを保守します。cron 実行ログ（`cron/runs/.jsonl`）は削除しません。これは [Cron 設定](/ja-JP/automation/cron-jobs#configuration) の `cron.runLog.maxBytes` と `cron.runLog.keepLines` によって管理され、[Cron 保守](/ja-JP/automation/cron-jobs#maintenance) で説明されています。 +- スコープに関する注記: `openclaw sessions cleanup` はセッションストア、トランスクリプト、および trajectory サイドカーをメンテナンスします。これは cron 実行ログ（`cron/runs/.jsonl`）を削除しません。cron 実行ログは [Cron 設定](/ja-JP/automation/cron-jobs#configuration) の `cron.runLog.maxBytes` と `cron.runLog.keepLines` で管理され、[Cron メンテナンス](/ja-JP/automation/cron-jobs#maintenance) で説明されています。 -- `--dry-run`: 書き込みを行わずに、削除または上限制限されるエントリ数をプレビューします。 - - テキストモードでは、dry-run はセッションごとのアクションテーブル（`Action`、`Key`、`Age`、`Model`、`Flags`）を出力するため、保持されるものと削除されるものを確認できます。 -- `--enforce`: `session.maintenance.mode` が `warn` の場合でも保守を適用します。 -- `--fix-missing`: トランスクリプトファイルが見つからないエントリを、通常ならまだ経過時間や件数の条件から外れない場合でも削除します。 -- `--active-key `: 特定のアクティブキーをディスク容量予算による退避から保護します。グループセッションやスレッド単位のチャットセッションなど、永続的な外部会話ポインターも、経過時間、件数、ディスク容量予算による保守で保持されます。 -- `--agent `: 設定済みエージェントストア 1 つに対してクリーンアップを実行します。 -- `--all-agents`: 設定済みのすべてのエージェントストアに対してクリーンアップを実行します。 +- `--dry-run`: 書き込まずに、いくつのエントリが削除/上限適用されるかをプレビューします。 + - テキストモードでは、dry-run はセッションごとのアクション表（`Action`、`Key`、`Age`、`Model`、`Flags`）を出力するため、何が保持され、何が削除されるかを確認できます。 +- `--enforce`: `session.maintenance.mode` が `warn` の場合でもメンテナンスを適用します。 +- `--fix-missing`: トランスクリプトファイルが欠落しているエントリを、通常はまだ経過時間/件数の対象外であっても削除します。 +- `--active-key `: 特定のアクティブキーをディスク予算による退避から保護します。グループセッションやスレッドスコープのチャットセッションなど、永続的な外部会話ポインターも、経過時間/件数/ディスク予算メンテナンスで保持されます。 +- `--agent `: 1 つの設定済みエージェントストアに対してクリーンアップを実行します。 +- `--all-agents`: すべての設定済みエージェントストアに対してクリーンアップを実行します。 - `--store `: 特定の `sessions.json` ファイルに対して実行します。 - `--json`: JSON サマリーを出力します。`--all-agents` を指定した場合、出力にはストアごとのサマリーが含まれます。 -Gateway に到達できる場合、設定済みエージェントストアに対する dry-run ではないクリーンアップは Gateway 経由で送信されるため、ランタイムトラフィックと同じセッションストアライターを共有します。ストアファイルを明示的にオフライン修復するには `--store ` を使用してください。 +Gateway に到達できる場合、設定済みエージェントストアの非 dry-run クリーンアップは +Gateway 経由で送信されるため、ランタイムトラフィックと同じセッションストアライターを共有します。ストアファイルの明示的なオフライン修復には `--store ` を使用してください。 `openclaw sessions cleanup --all-agents --dry-run --json`: diff --git a/docs/ja-JP/cli/update.md b/docs/ja-JP/cli/update.md index 541e10853..f01ab9ff0 100644 --- a/docs/ja-JP/cli/update.md +++ b/docs/ja-JP/cli/update.md @@ -1,27 +1,27 @@ --- read_when: - ソースチェックアウトを安全に更新したい場合 - - '`openclaw update` の出力またはオプションをデバッグしている' + - '`openclaw update` の出力またはオプションをデバッグしています' - '`--update` の省略記法の動作を理解する必要があります' -summary: '`openclaw update` の CLI リファレンス（比較的安全なソース更新 + Gateway の自動再起動）' +summary: '`openclaw update` の CLI リファレンス (比較的安全なソース更新 + Gateway の自動再起動)' title: 更新 x-i18n: - generated_at: "2026-05-03T21:29:52Z" + generated_at: "2026-05-05T01:44:58Z" model: gpt-5.5 provider: openai - source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8 + source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f source_path: cli/update.md workflow: 16 --- # `openclaw update` -OpenClaw を安全に更新し、stable/beta/dev チャンネルを切り替えます。 +OpenClaw を安全に更新し、stable/beta/dev チャネルを切り替えます。 -**npm/pnpm/bun** でインストールした場合（グローバルインストール、git メタデータなし）、 -更新は [更新](/ja-JP/install/updating) のパッケージマネージャーフローで行われます。 +**npm/pnpm/bun** でインストールした場合（グローバルインストールで、git メタデータなし）、 +更新は [Updating](/ja-JP/install/updating) のパッケージマネージャーフローで行われます。 -## 使い方 +## 使用方法 ```bash openclaw update @@ -40,16 +40,16 @@ openclaw --update ## オプション -- `--no-restart`: 更新が成功した後に Gateway サービスを再起動しません。Gateway を再起動するパッケージマネージャー更新では、コマンドが成功する前に、再起動されたサービスが期待される更新後バージョンを報告することを確認します。 -- `--channel `: 更新チャンネルを設定します（git + npm。設定に永続化されます）。 -- `--tag `: この更新でのみパッケージターゲットを上書きします。パッケージインストールでは、`main` は `github:openclaw/openclaw#main` に対応します。 -- `--dry-run`: 設定の書き込み、インストール、plugins の同期、再起動を行わずに、予定されている更新アクション（チャンネル/タグ/ターゲット/再起動フロー）をプレビューします。 -- `--json`: 機械可読な `UpdateRunResult` JSON を出力します。更新後の plugin 同期中に npm plugin アーティファクトのドリフトが検出された場合は +- `--no-restart`: 更新が成功した後、Gateway サービスの再起動をスキップします。Gateway を再起動するパッケージマネージャー更新では、コマンドが成功する前に、再起動されたサービスが期待される更新後バージョンを報告することを確認します。 +- `--channel `: 更新チャネルを設定します（git + npm。設定に永続化されます）。 +- `--tag `: この更新に限り、パッケージターゲットを上書きします。パッケージインストールでは、`main` は `github:openclaw/openclaw#main` にマップされます。 +- `--dry-run`: 設定の書き込み、インストール、Plugin の同期、再起動を行わずに、予定されている更新アクション（チャネル/タグ/ターゲット/再起動フロー）をプレビューします。 +- `--json`: 機械可読な `UpdateRunResult` JSON を出力します。更新後の Plugin 同期中に npm Plugin アーティファクトのドリフトが検出された場合は、 `postUpdate.plugins.integrityDrifts` も含まれます。 - `--timeout `: ステップごとのタイムアウト（デフォルトは 1800 秒）。 -- `--yes`: 確認プロンプトをスキップします（例: ダウングレード確認）。 +- `--yes`: 確認プロンプトをスキップします（たとえばダウングレード確認）。 -`openclaw update` には `--verbose` フラグはありません。予定されているチャンネル/タグ/インストール/再起動アクションをプレビューするには `--dry-run`、機械可読な結果には `--json`、チャンネルと利用可否の詳細だけが必要な場合は `openclaw update status --json` を使用します。更新前後の Gateway ログをデバッグしている場合、コンソールの詳細度とファイルログレベルは別です。Gateway の `--verbose` は端末/WebSocket 出力に影響しますが、ファイルログには設定で `logging.level: "debug"` または `"trace"` が必要です。[Gateway ロギング](/ja-JP/gateway/logging) を参照してください。 +`openclaw update` には `--verbose` フラグはありません。予定されているチャネル/タグ/インストール/再起動アクションをプレビューするには `--dry-run` を、機械可読な結果には `--json` を、チャネルと利用可能状況の詳細だけが必要な場合は `openclaw update status --json` を使用してください。更新の前後で Gateway ログをデバッグしている場合、コンソールの詳細度とファイルログレベルは別です。Gateway の `--verbose` はターミナル/WebSocket 出力に影響しますが、ファイルログには設定で `logging.level: "debug"` または `"trace"` が必要です。[Gateway logging](/ja-JP/gateway/logging) を参照してください。 古いバージョンでは設定が壊れる可能性があるため、ダウングレードには確認が必要です。 @@ -57,7 +57,7 @@ openclaw --update ## `update status` -有効な更新チャンネルと git タグ/ブランチ/SHA（ソースチェックアウトの場合）、および更新の利用可否を表示します。 +アクティブな更新チャネルと git タグ/ブランチ/SHA（ソースチェックアウトの場合）、および更新の利用可能状況を表示します。 ```bash openclaw update status @@ -72,7 +72,7 @@ openclaw update status --timeout 10 ## `update wizard` -更新チャンネルを選択し、更新後に Gateway を再起動するかどうかを確認する対話フローです（デフォルトでは再起動します）。git チェックアウトなしで `dev` を選択した場合は、作成を提案します。 +更新チャネルを選択し、更新後に Gateway を再起動するかどうかを確認する対話型フローです（デフォルトでは再起動します）。git チェックアウトなしで `dev` を選択すると、作成を提案します。 オプション: @@ -80,21 +80,21 @@ openclaw update status --timeout 10 ## 実行内容 -チャンネルを明示的に切り替えると（`--channel ...`）、OpenClaw はインストール方法もそろえます。 +チャネルを明示的に切り替えると（`--channel ...`）、OpenClaw はインストール方法も整合させます。 -- `dev` → git チェックアウトがあることを確認し（デフォルト: `~/openclaw`、`OPENCLAW_GIT_DIR` で上書き可能）、それを更新し、そのチェックアウトからグローバル CLI をインストールします。 -- `stable` → `latest` を使って npm からインストールします。 -- `beta` → npm dist-tag `beta` を優先しますが、beta が存在しない、または現在の stable リリースより古い場合は `latest` にフォールバックします。 +- `dev` → git チェックアウトを確保し（デフォルト: `~/openclaw`、`OPENCLAW_GIT_DIR` で上書き）、それを更新して、そのチェックアウトからグローバル CLI をインストールします。 +- `stable` → `latest` を使用して npm からインストールします。 +- `beta` → npm dist-tag `beta` を優先しますが、beta が存在しないか現在の安定版リリースより古い場合は `latest` にフォールバックします。 -Gateway コアの自動更新機能（設定で有効な場合）は、実行中の Gateway リクエストハンドラーの外で CLI 更新パスを起動します。コントロールプレーンの `update.run` パッケージマネージャー更新では、パッケージ差し替え後に遅延なし、クールダウンなしの更新再起動を強制します。これは、古い Gateway プロセスが、新しいパッケージで削除されたファイルを指すメモリ内チャンクをまだ持っている可能性があるためです。 +Gateway コアの自動更新機能（設定で有効な場合）は、稼働中の Gateway リクエストハンドラーの外で CLI 更新パスを起動します。コントロールプレーンの `update.run` パッケージマネージャー更新では、パッケージ差し替え後に、遅延なし、クールダウンなしの更新再起動を強制します。これは、古い Gateway プロセスが、新しいパッケージで削除されたファイルを指すインメモリチャンクをまだ保持している可能性があるためです。 -パッケージマネージャーインストールでは、`openclaw update` はパッケージマネージャーを呼び出す前にターゲットパッケージバージョンを解決します。npm グローバルインストールではステージングインストールを使用します。OpenClaw は新しいパッケージを一時的な npm prefix にインストールし、そこでパッケージ化された `dist` インベントリを検証してから、そのクリーンなパッケージツリーを実際のグローバル prefix に差し替えます。検証に失敗した場合、更新後の doctor、plugin 同期、再起動処理は疑わしいツリーから実行されません。インストール済みバージョンがすでにターゲットと一致している場合でも、コマンドはグローバルパッケージインストールを更新し、その後 plugin 同期、コアコマンド補完の更新、再起動処理を実行します。これにより、パッケージ化されたサイドカーとチャンネル所有の plugin レコードを、インストール済みの OpenClaw ビルドとそろえたまま、完全な plugin コマンド補完の再ビルドは明示的な `openclaw completion --write-state` 実行に委ねます。 +パッケージマネージャーインストールでは、`openclaw update` はパッケージマネージャーを呼び出す前にターゲットパッケージバージョンを解決します。npm グローバルインストールでは段階的インストールを使用します。OpenClaw は新しいパッケージを一時的な npm prefix にインストールし、そこでパッケージ化された `dist` インベントリを検証してから、そのクリーンなパッケージツリーを実際のグローバル prefix に差し替えます。検証に失敗した場合、更新後の doctor、Plugin 同期、再起動作業は疑わしいツリーから実行されません。インストール済みバージョンがすでにターゲットと一致している場合でも、コマンドはグローバルパッケージインストールを更新し、その後に Plugin 同期、コアコマンド補完の更新、再起動作業を実行します。これにより、パッケージ化されたサイドカーとチャネル所有の Plugin レコードをインストール済みの OpenClaw ビルドと整合させつつ、完全な Plugin コマンド補完の再構築は明示的な `openclaw completion --write-state` 実行に任せます。 -ローカルの管理対象 Gateway サービスがインストールされ、再起動が有効な場合、パッケージマネージャー更新は、パッケージツリーを置き換える前に実行中のサービスを停止します。その後、更新されたインストールからサービスメタデータを更新し、サービスを再起動し、成功を報告する前に、再起動された Gateway が期待されるバージョンを報告することを確認します。macOS では、更新後チェックにより、有効なプロファイルの LaunchAgent が読み込まれて実行中であり、設定済みの loopback ポートが正常であることも確認されます。plist がインストールされているが launchd がそれを監視していない場合、OpenClaw は LaunchAgent を自動的に再ブートストラップし、その後ヘルス/バージョン/チャンネル準備完了チェックを再実行します。新規ブートストラップでは RunAtLoad ジョブを直接読み込むため、更新リカバリーは新しく起動した Gateway に対してすぐに `kickstart -k` を実行しません。それでも Gateway が正常にならない場合、コマンドはゼロ以外で終了し、再起動ログパスに加えて、明示的な再起動、再インストール、パッケージロールバック手順を出力します。`--no-restart` を指定した場合、パッケージ置換は引き続き実行されますが、管理対象サービスは停止または再起動されないため、手動で再起動するまで、実行中の Gateway は古いコードを使い続ける可能性があります。 +ローカル管理の Gateway サービスがインストールされていて再起動が有効な場合、パッケージマネージャー更新はパッケージツリーを置き換える前に実行中のサービスを停止し、更新後のインストールからサービスメタデータを更新し、サービスを再起動して、再起動された Gateway が期待されるバージョンを報告することを確認してから成功を報告します。macOS では、更新後チェックにより、アクティブプロファイルの LaunchAgent が読み込み済み/実行中であり、設定されたループバックポートが正常であることも確認します。plist がインストールされているものの launchd が監視していない場合、OpenClaw は LaunchAgent を自動的に再ブートストラップし、その後にヘルス/バージョン/チャネルの準備状況チェックを再実行します。新規ブートストラップでは RunAtLoad ジョブを直接読み込むため、更新リカバリは新しく生成された Gateway に対してすぐに `kickstart -k` を実行しません。それでも Gateway が正常にならない場合、コマンドは非ゼロで終了し、再起動ログのパスに加えて、明示的な再起動、再インストール、パッケージロールバック手順を出力します。`--no-restart` を指定すると、パッケージ置換は実行されますが、管理サービスは停止または再起動されないため、手動で再起動するまで実行中の Gateway は古いコードを保持する可能性があります。 ## Git チェックアウトフロー -### チャンネル選択 +### チャネル選択 - `stable`: 最新の非 beta タグをチェックアウトし、その後ビルドと doctor を実行します。 - `beta`: 最新の `-beta` タグを優先しますが、beta が存在しないか古い場合は最新の stable タグにフォールバックします。 @@ -103,56 +103,56 @@ Gateway コアの自動更新機能（設定で有効な場合）は、実行中 ### 更新ステップ - + 未コミットの変更がないことが必要です。 - - 選択したチャンネル（タグまたはブランチ）に切り替えます。 + + 選択したチャネル（タグまたはブランチ）に切り替えます。 - + dev のみ。 - 一時ワークツリーで lint と TypeScript ビルドを実行します。先端が失敗した場合は、最大 10 コミットさかのぼって最新のクリーンビルドを探します。 + 一時 worktree で lint と TypeScript ビルドを実行します。先端が失敗した場合、最大 10 コミット遡って、正常にビルドできる最新のコミットを探します。 選択したコミットに rebase します（dev のみ）。 - リポジトリのパッケージマネージャーを使用します。pnpm チェックアウトの場合、アップデーターは pnpm ワークスペース内で `npm run build` を実行する代わりに、必要に応じて `pnpm` をブートストラップします（まず `corepack`、次に一時的な `npm install pnpm@10` フォールバック）。 + リポジトリのパッケージマネージャーを使用します。pnpm チェックアウトでは、updater は pnpm workspace 内で `npm run build` を実行するのではなく、必要に応じて `pnpm` をブートストラップします（まず `corepack`、次に一時的な `npm install pnpm@10` フォールバック）。 - Gateway と Control UI をビルドします。 + gateway と Control UI をビルドします。 - `openclaw doctor` が最後の安全更新チェックとして実行されます。 + 最後の安全な更新チェックとして `openclaw doctor` を実行します。 - - plugins を有効なチャンネルに同期します。dev は同梱 plugins を使用し、stable と beta は npm を使用します。追跡対象の plugin インストールを更新します。 + + Plugin をアクティブなチャネルに同期します。dev はバンドル Plugin を使用し、stable と beta は npm を使用します。追跡対象の Plugin インストールを更新します。 -beta 更新チャンネルでは、デフォルト/latest 系に従う追跡対象の npm および ClawHub plugin インストールは、まず plugin の `@beta` リリースを試します。plugin に beta リリースがない場合、OpenClaw は記録済みのデフォルト/latest spec にフォールバックします。正確なバージョンと明示的なタグは書き換えられません。 +beta 更新チャネルでは、default/latest ラインに従う追跡対象の npm および ClawHub Plugin インストールは、まず Plugin の `@beta` リリースを試します。Plugin に beta リリースがない場合、OpenClaw は記録された default/latest spec にフォールバックします。npm Plugin では、beta パッケージが存在してもインストール検証に失敗した場合にも OpenClaw はフォールバックします。正確なバージョンと明示的なタグは書き換えられません。 -正確に固定された npm plugin 更新が、保存済みインストールレコードと integrity が異なるアーティファクトに解決された場合、`openclaw update` はその plugin アーティファクト更新をインストールせずに中止します。新しいアーティファクトを信頼できることを確認した後でのみ、plugin を明示的に再インストールまたは更新してください。 +正確にピン留めされた npm Plugin 更新が、保存済みインストールレコードと整合性が異なるアーティファクトに解決された場合、`openclaw update` はその Plugin アーティファクト更新をインストールせずに中止します。新しいアーティファクトを信頼できることを確認した後でのみ、Plugin を明示的に再インストールまたは更新してください。 -更新後の plugin 同期に失敗すると、更新結果は失敗となり、再起動の後続処理は停止します。plugin のインストールまたは更新エラーを修正してから、`openclaw update` を再実行してください。 +更新後の Plugin 同期に失敗すると、更新結果は失敗となり、その後の再起動作業は停止します。Plugin のインストールまたは更新エラーを修正してから、`openclaw update` を再実行してください。 -更新された Gateway が起動するとき、plugin 読み込みは検証のみです。起動時にパッケージマネージャーを実行したり、依存関係ツリーを変更したりしません。パッケージマネージャーの `update.run` 再起動は、パッケージツリーが差し替えられた後、通常のアイドル遅延と再起動クールダウンをバイパスするため、古いプロセスが削除済みチャンクを遅延読み込みし続けることはできません。 +更新後の Gateway が起動するとき、Plugin 読み込みは検証のみです。起動時にパッケージマネージャーを実行したり、依存関係ツリーを変更したりすることはありません。パッケージマネージャーの `update.run` 再起動は、パッケージツリーの差し替え後に通常のアイドル遅延と再起動クールダウンをバイパスするため、古いプロセスが削除済みチャンクを遅延読み込みし続けることはできません。 -pnpm ブートストラップがそれでも失敗する場合、アップデーターはチェックアウト内で `npm run build` を試すのではなく、パッケージマネージャー固有のエラーで早期停止します。 +pnpm ブートストラップがそれでも失敗する場合、updater はチェックアウト内で `npm run build` を試すのではなく、パッケージマネージャー固有のエラーで早期に停止します。 ## `--update` 省略形 -`openclaw --update` は `openclaw update` に書き換えられます（シェルやランチャースクリプトに便利です）。 +`openclaw --update` は `openclaw update` に書き換えられます（shell やランチャースクリプトで便利です）。 ## 関連 -- `openclaw doctor`（git チェックアウトでは先に update を実行するよう提案します） -- [開発チャンネル](/ja-JP/install/development-channels) -- [更新](/ja-JP/install/updating) +- `openclaw doctor`（git チェックアウトでは先に更新を実行するよう提案します） +- [開発チャネル](/ja-JP/install/development-channels) +- [Updating](/ja-JP/install/updating) - [CLI リファレンス](/ja-JP/cli) diff --git a/docs/ja-JP/concepts/models.md b/docs/ja-JP/concepts/models.md index 081fb156d..635250a49 100644 --- a/docs/ja-JP/concepts/models.md +++ b/docs/ja-JP/concepts/models.md @@ -1,22 +1,22 @@ --- read_when: - - models CLI の追加または変更（models list/set/scan/aliases/fallbacks） - - モデルのフォールバック動作または選択 UX の変更 - - モデルスキャンプローブの更新（ツール/画像） + - models CLI（models list/set/scan/aliases/fallbacks）の追加または変更 + - モデルのフォールバック動作または選択時のユーザー体験の変更 + - モデルスキャンプローブの更新 (tools/images) sidebarTitle: Models CLI -summary: 'モデル CLI: 一覧表示、設定、エイリアス、フォールバック、スキャン、ステータス' +summary: 'Models CLI: list、set、aliases、fallbacks、scan、status' title: モデル CLI x-i18n: - generated_at: "2026-05-02T20:45:53Z" + generated_at: "2026-05-05T01:45:04Z" model: gpt-5.5 provider: openai - source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f + source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f source_path: concepts/models.md workflow: 16 --- - + 認証プロファイルのローテーション、クールダウン、それらがフォールバックとどう相互作用するか。 @@ -30,7 +30,7 @@ x-i18n: -モデル参照はプロバイダーとモデルを選択します。通常、低レベルのエージェントランタイムは選択しません。たとえば、`openai/gpt-5.5` は、`agents.defaults.agentRuntime.id` に応じて、通常の OpenAI プロバイダーパス経由でも、Codex アプリサーバーランタイム経由でも実行できます。Codex ランタイムモードでは、`openai/gpt-*` 参照は API キー課金を意味しません。認証は Codex アカウントまたは `openai-codex` 認証プロファイルから取得できます。[エージェントランタイム](/ja-JP/concepts/agent-runtimes)を参照してください。 +モデル参照はプロバイダーとモデルを選択します。通常、低レベルのエージェントランタイムは選択しません。たとえば、`openai/gpt-5.5` は `agents.defaults.agentRuntime.id` に応じて、通常の OpenAI プロバイダーパス経由でも、Codex app-server ランタイム経由でも実行できます。Codex ランタイムモードでは、`openai/gpt-*` 参照は API キー課金を意味しません。認証は Codex アカウントまたは `openai-codex` 認証プロファイルから取得できます。[エージェントランタイム](/ja-JP/concepts/agent-runtimes)を参照してください。 ## モデル選択の仕組み @@ -38,75 +38,75 @@ OpenClaw は次の順序でモデルを選択します。 - `agents.defaults.model.primary`（または `agents.defaults.model`）。 + `agents.defaults.model.primary` (または `agents.defaults.model`)。 - `agents.defaults.model.fallbacks`（順序どおり）。 + `agents.defaults.model.fallbacks` (順番どおり)。 - 認証フェイルオーバーは、次のモデルへ移る前にプロバイダー内で発生します。 + 次のモデルへ移る前に、プロバイダー内で認証フェイルオーバーが発生します。 - - `agents.defaults.models` は、OpenClaw が使用できるモデルの許可リスト/カタログです（エイリアスを含む）。 - - `agents.defaults.imageModel` は、プライマリモデルが画像を受け付けられない場合**にのみ**使用されます。 - - `agents.defaults.pdfModel` は `pdf` ツールで使用されます。省略した場合、ツールは `agents.defaults.imageModel` にフォールバックし、その後、解決済みのセッション/デフォルトモデルにフォールバックします。 - - `agents.defaults.imageGenerationModel` は共有の画像生成機能で使用されます。省略した場合でも、`image_generate` は認証に裏付けられたプロバイダーのデフォルトを推測できます。まず現在のデフォルトプロバイダーを試し、次に残りの登録済み画像生成プロバイダーをプロバイダー ID 順で試します。特定のプロバイダー/モデルを設定する場合は、そのプロバイダーの認証/API キーも設定してください。 - - `agents.defaults.musicGenerationModel` は共有の音楽生成機能で使用されます。省略した場合でも、`music_generate` は認証に裏付けられたプロバイダーのデフォルトを推測できます。まず現在のデフォルトプロバイダーを試し、次に残りの登録済み音楽生成プロバイダーをプロバイダー ID 順で試します。特定のプロバイダー/モデルを設定する場合は、そのプロバイダーの認証/API キーも設定してください。 - - `agents.defaults.videoGenerationModel` は共有の動画生成機能で使用されます。省略した場合でも、`video_generate` は認証に裏付けられたプロバイダーのデフォルトを推測できます。まず現在のデフォルトプロバイダーを試し、次に残りの登録済み動画生成プロバイダーをプロバイダー ID 順で試します。特定のプロバイダー/モデルを設定する場合は、そのプロバイダーの認証/API キーも設定してください。 - - エージェントごとのデフォルトは、`agents.list[].model` とバインディングにより `agents.defaults.model` を上書きできます（[マルチエージェントルーティング](/ja-JP/concepts/multi-agent)を参照）。 + - `agents.defaults.models` は、OpenClaw が使用できるモデルの許可リスト/カタログ (エイリアスを含む) です。 + - `agents.defaults.imageModel` は、プライマリモデルが画像を受け付けられない**場合にのみ**使用されます。 + - `agents.defaults.pdfModel` は `pdf` ツールで使用されます。省略すると、ツールは `agents.defaults.imageModel`、次に解決済みのセッション/デフォルトモデルへフォールバックします。 + - `agents.defaults.imageGenerationModel` は共有の画像生成機能で使用されます。省略すると、`image_generate` は認証に裏付けられたプロバイダーのデフォルトを引き続き推論できます。現在のデフォルトプロバイダーを最初に試し、次に残りの登録済み画像生成プロバイダーをプロバイダー ID 順に試します。特定のプロバイダー/モデルを設定する場合は、そのプロバイダーの認証/API キーも設定してください。 + - `agents.defaults.musicGenerationModel` は共有の音楽生成機能で使用されます。省略すると、`music_generate` は認証に裏付けられたプロバイダーのデフォルトを引き続き推論できます。現在のデフォルトプロバイダーを最初に試し、次に残りの登録済み音楽生成プロバイダーをプロバイダー ID 順に試します。特定のプロバイダー/モデルを設定する場合は、そのプロバイダーの認証/API キーも設定してください。 + - `agents.defaults.videoGenerationModel` は共有の動画生成機能で使用されます。省略すると、`video_generate` は認証に裏付けられたプロバイダーのデフォルトを引き続き推論できます。現在のデフォルトプロバイダーを最初に試し、次に残りの登録済み動画生成プロバイダーをプロバイダー ID 順に試します。特定のプロバイダー/モデルを設定する場合は、そのプロバイダーの認証/API キーも設定してください。 + - エージェントごとのデフォルトは、`agents.list[].model` とバインディングによって `agents.defaults.model` を上書きできます ([マルチエージェントルーティング](/ja-JP/concepts/multi-agent)を参照)。 ## 選択元とフォールバック動作 -同じ `provider/model` でも、どこから来たかによって意味が変わる場合があります。 +同じ `provider/model` でも、どこから来たかによって意味が異なる場合があります。 -- 設定済みデフォルト（`agents.defaults.model.primary` とエージェント固有のプライマリ）は通常の開始点であり、`agents.defaults.model.fallbacks` を使用します。 -- 自動フォールバック選択は一時的な復旧状態です。`modelOverrideSource: "auto"` とともに保存されるため、後続のターンでは、既知の不良プライマリを最初に試すことなくフォールバックチェーンを使い続けられます。 +- 設定済みのデフォルト (`agents.defaults.model.primary` とエージェント固有のプライマリ) は通常の開始点であり、`agents.defaults.model.fallbacks` を使用します。 +- 自動フォールバック選択は一時的な復旧状態です。`modelOverrideSource: "auto"` とともに保存されるため、後続のターンでは、既知の問題があるプライマリを最初に試さずにフォールバックチェーンを使い続けられます。 - ユーザーセッション選択は厳密です。`/model`、モデルピッカー、`session_status(model=...)`、`sessions.patch` は `modelOverrideSource: "user"` を保存します。その選択されたプロバイダー/モデルに到達できない場合、OpenClaw は別の設定済みモデルへフォールスルーせず、見える形で失敗します。 -- Cron の `--model` / ペイロード `model` はジョブごとのプライマリです。ジョブが明示的なペイロード `fallbacks` を指定しない限り、設定済みフォールバックを引き続き使用します（厳密な cron 実行には `fallbacks: []` を使用します）。 -- CLI のデフォルトモデルと許可リストのピッカーは、組み込みカタログ全体を読み込む代わりに明示的な `models.providers.*.models` を一覧表示することで、`models.mode: "replace"` を尊重します。 -- コントロール UI のモデルピッカーは、Gateway に設定済みモデルビューを問い合わせます。存在する場合は `agents.defaults.models`、そうでない場合は明示的な `models.providers.*.models` と利用可能な認証を持つプロバイダーです。完全な組み込みカタログは、`view: "all"` を指定した `models.list` や `openclaw models list --all` など、明示的な参照ビュー用に予約されています。 +- Cron `--model` / ペイロード `model` はジョブごとのプライマリです。ジョブが明示的なペイロード `fallbacks` を指定しない限り、設定済みフォールバックを引き続き使用します (厳格な cron 実行には `fallbacks: []` を使用します)。 +- CLI のデフォルトモデルと許可リストのピッカーは、完全な組み込みカタログを読み込む代わりに明示的な `models.providers.*.models` を一覧表示することで、`models.mode: "replace"` を尊重します。 +- コントロール UI のモデルピッカーは、Gateway に設定済みモデルビューを要求します。存在する場合は `agents.defaults.models`、それ以外は明示的な `models.providers.*.models` と使用可能な認証を持つプロバイダーです。完全な組み込みカタログは、`models.list` の `view: "all"` や `openclaw models list --all` などの明示的なブラウズビュー用に予約されています。 -## 簡単なモデルポリシー +## 簡易モデルポリシー -- プライマリには、利用可能な最新世代の最も強力なモデルを設定します。 -- コスト/レイテンシに敏感なタスクやリスクの低いチャットにはフォールバックを使用します。 -- ツール有効エージェントや信頼できない入力では、古い/弱いモデル階層を避けてください。 +- プライマリには、利用可能な最も強力な最新世代モデルを設定してください。 +- コスト/レイテンシーに敏感なタスクや重要度の低いチャットにはフォールバックを使用してください。 +- ツールが有効なエージェントや信頼できない入力では、古い/弱いモデル階層を避けてください。 -## オンボーディング（推奨） +## オンボーディング (推奨) -設定を手動編集したくない場合は、オンボーディングを実行します。 +設定を手作業で編集したくない場合は、オンボーディングを実行します。 ```bash openclaw onboard ``` -これは、**OpenAI Code（Codex）サブスクリプション**（OAuth）や **Anthropic**（API キーまたは Claude CLI）を含む一般的なプロバイダー向けに、モデルと認証をセットアップできます。 +一般的なプロバイダー向けにモデルと認証をセットアップできます。これには **OpenAI Code (Codex) サブスクリプション** (OAuth) と **Anthropic** (API キーまたは Claude CLI) が含まれます。 -## 設定キー（概要） +## 設定キー (概要) - `agents.defaults.model.primary` と `agents.defaults.model.fallbacks` - `agents.defaults.imageModel.primary` と `agents.defaults.imageModel.fallbacks` - `agents.defaults.pdfModel.primary` と `agents.defaults.pdfModel.fallbacks` - `agents.defaults.imageGenerationModel.primary` と `agents.defaults.imageGenerationModel.fallbacks` - `agents.defaults.videoGenerationModel.primary` と `agents.defaults.videoGenerationModel.fallbacks` -- `agents.defaults.models`（許可リスト + エイリアス + プロバイダーパラメーター） -- `models.providers`（`models.json` に書き込まれるカスタムプロバイダー） +- `agents.defaults.models` (許可リスト + エイリアス + プロバイダーパラメーター) +- `models.providers` (`models.json` に書き込まれるカスタムプロバイダー) モデル参照は小文字に正規化されます。`z.ai/*` のようなプロバイダーエイリアスは `zai/*` に正規化されます。 -プロバイダー設定例（OpenCode を含む）は [OpenCode](/ja-JP/providers/opencode) にあります。 +プロバイダー設定例 (OpenCode を含む) は [OpenCode](/ja-JP/providers/opencode) にあります。 ### 安全な許可リスト編集 -`agents.defaults.models` を手動で更新する場合は、追加書き込みを使用します。 +手動で `agents.defaults.models` を更新するときは、追加型の書き込みを使用してください。 ```bash openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge @@ -114,36 +114,39 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json - `openclaw config set` は、モデル/プロバイダーマップを意図しない上書きから保護します。`agents.defaults.models`、`models.providers`、または `models.providers..models` へのプレーンオブジェクト代入は、既存のエントリを削除する場合は拒否されます。追加変更には `--merge` を使用し、指定した値を完全なターゲット値にする場合にのみ `--replace` を使用してください。 + `openclaw config set` は、モデル/プロバイダーのマップを偶発的な上書きから保護します。`agents.defaults.models`、`models.providers`、または `models.providers..models` へのプレーンなオブジェクト割り当ては、既存のエントリを削除することになる場合に拒否されます。追加変更には `--merge` を使用してください。指定した値を完全なターゲット値にする場合にのみ `--replace` を使用してください。 - 対話型プロバイダーセットアップと `openclaw configure --section model` も、プロバイダースコープの選択を既存の許可リストにマージするため、Codex、Ollama、または別のプロバイダーを追加しても、関係のないモデルエントリは削除されません。Configure は、プロバイダー認証が再適用されるときに既存の `agents.defaults.model.primary` を保持します。`openclaw models auth login --provider --set-default` や `openclaw models set ` などの明示的なデフォルト設定コマンドは、引き続き `agents.defaults.model.primary` を置き換えます。 + 対話型プロバイダーセットアップと `openclaw configure --section model` も、プロバイダー単位の選択を既存の許可リストにマージします。そのため、Codex、Ollama、または別のプロバイダーを追加しても、無関係なモデルエントリは削除されません。プロバイダー認証を再適用するとき、Configure は既存の `agents.defaults.model.primary` を保持します。`openclaw models auth login --provider --set-default` や `openclaw models set ` のような明示的なデフォルト設定コマンドは、引き続き `agents.defaults.model.primary` を置き換えます。 -## 「モデルは許可されていません」（そして返信が止まる理由） +## 「モデルは許可されていません」(返信が止まる理由) -`agents.defaults.models` が設定されている場合、それは `/model` とセッション上書き用の**許可リスト**になります。ユーザーがその許可リストにないモデルを選択すると、OpenClaw は次を返します。 +`agents.defaults.models` が設定されている場合、それは `/model` とセッション上書きの**許可リスト**になります。ユーザーがその許可リストにないモデルを選択すると、OpenClaw は次を返します。 ``` -Model "provider/model" is not allowed. Use /model to list available models. +Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. +Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` -これは通常の返信が生成される**前に**発生するため、メッセージは「応答しなかった」ように感じられる場合があります。修正するには、次のいずれかを行います。 +これは通常の返信が生成される**前に**発生するため、メッセージが「応答しなかった」ように感じられる場合があります。修正するには、次のいずれかを行います。 - モデルを `agents.defaults.models` に追加する、または -- 許可リストをクリアする（`agents.defaults.models` を削除する）、または -- `/model list` からモデルを選ぶ。 +- 許可リストをクリアする (`agents.defaults.models` を削除する)、または +- `/model list` からモデルを選択する。 -ローカル/GGUF モデルでは、許可リストに完全なプロバイダー接頭辞付き参照を保存します。 -たとえば `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`、または -`openclaw models list --provider ` に表示される正確な -プロバイダー/モデルです。許可リストが有効な場合、素のローカルファイル名や表示名だけでは不十分です。 +拒否されたコマンドに `/model openai/gpt-5.5 --runtime codex` のようなランタイム上書きが含まれていた場合は、まず許可リストを修正し、その後で同じ `/model ... --runtime ...` コマンドを再試行してください。ネイティブ Codex 実行では、選択されたモデルは引き続き `openai/gpt-5.5` です。`codex` ランタイムはハーネスを選択し、Codex 認証を別途使用します。 -許可リスト設定の例: +ローカル/GGUF モデルでは、プロバイダープレフィックス付きの完全な参照を許可リストに保存してください。 +たとえば `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`、または +`openclaw models list --provider ` に表示される正確な provider/model です。 +許可リストが有効な場合、裸のローカルファイル名や表示名だけでは不十分です。 + +許可リスト設定例: ```json5 { @@ -157,7 +160,7 @@ Model "provider/model" is not allowed. Use /model to list available models. } ``` -## チャットでモデルを切り替える（`/model`） +## チャットでモデルを切り替える (`/model`) 再起動せずに、現在のセッションのモデルを切り替えられます。 @@ -171,33 +174,33 @@ Model "provider/model" is not allowed. Use /model to list available models. - - `/model`（および `/model list`）は、コンパクトな番号付きピッカーです（モデルファミリー + 利用可能なプロバイダー）。 - - Discord では、`/model` と `/models` が、プロバイダーとモデルのドロップダウンに加えて送信ステップを備えた対話型ピッカーを開きます。 + - `/model` (および `/model list`) は、コンパクトな番号付きピッカー (モデルファミリー + 利用可能なプロバイダー) です。 + - Discord では、`/model` と `/models` は、プロバイダーとモデルのドロップダウンに加えて Submit ステップを持つ対話型ピッカーを開きます。 - Telegram では、`/models` ピッカーの選択はセッションスコープです。`openclaw.json` 内のエージェントの永続的なデフォルトは変更しません。 - - `/models add` は非推奨で、現在はチャットからモデルを登録する代わりに非推奨メッセージを返します。 + - `/models add` は非推奨になり、チャットからモデルを登録する代わりに非推奨メッセージを返すようになりました。 - `/model <#>` はそのピッカーから選択します。 - `/model` は新しいセッション選択を即座に永続化します。 - - エージェントがアイドル状態の場合、次の実行はすぐに新しいモデルを使用します。 - - 実行がすでにアクティブな場合、OpenClaw はライブ切り替えを保留中としてマークし、クリーンな再試行ポイントでのみ新しいモデルへ再起動します。 - - ツールのアクティビティまたは返信出力がすでに開始している場合、保留中の切り替えは、後の再試行機会または次のユーザーターンまでキューに残る場合があります。 - - ユーザーが選択した `/model` 参照は、そのセッションでは厳密です。選択されたプロバイダー/モデルに到達できない場合、`agents.defaults.model.fallbacks` から静かに回答するのではなく、返信は見える形で失敗します。これは、引き続きフォールバックチェーンを使用できる設定済みデフォルトや cron ジョブのプライマリとは異なります。 - - `/model status` は詳細ビューです（認証候補、および設定されている場合はプロバイダーエンドポイントの `baseUrl` + `api` モード）。 + - エージェントがアイドル状態の場合、次の実行は新しいモデルをすぐに使用します。 + - 実行がすでにアクティブな場合、OpenClaw はライブ切り替えを保留としてマークし、クリーンな再試行ポイントでのみ新しいモデルへ再起動します。 + - ツールアクティビティまたは返信出力がすでに開始している場合、保留中の切り替えは後の再試行機会または次のユーザーターンまでキューに残ることがあります。 + - ユーザーが選択した `/model` 参照は、そのセッションでは厳密です。選択されたプロバイダー/モデルに到達できない場合、返信は `agents.defaults.model.fallbacks` から黙って応答するのではなく、見える形で失敗します。これは設定済みデフォルトや cron ジョブのプライマリとは異なり、それらは引き続きフォールバックチェーンを使用できます。 + - `/model status` は詳細ビューです (認証候補、および設定されている場合はプロバイダーエンドポイント `baseUrl` + `api` モード)。 - - モデル参照は、**最初の** `/` で分割して解析されます。`/model ` を入力するときは `provider/model` を使用します。 - - モデル ID 自体に `/` が含まれる場合（OpenRouter 形式）、プロバイダー接頭辞を含める必要があります（例: `/model openrouter/moonshotai/kimi-k2`）。 - - プロバイダーを省略した場合、OpenClaw は次の順序で入力を解決します。 + - モデル参照は、**最初**の `/` で分割して解析されます。`/model ` を入力するときは `provider/model` を使用してください。 + - モデル ID 自体に `/` が含まれる場合 (OpenRouter 形式)、プロバイダープレフィックスを含める必要があります (例: `/model openrouter/moonshotai/kimi-k2`)。 + - プロバイダーを省略すると、OpenClaw は次の順序で入力を解決します。 1. エイリアス一致 - 2. その正確な接頭辞なしモデル ID に対する、一意の設定済みプロバイダー一致 - 3. 設定済みデフォルトプロバイダーへの非推奨フォールバック — そのプロバイダーが設定済みデフォルトモデルを公開しなくなっている場合、OpenClaw は古い削除済みプロバイダーのデフォルトを表示しないよう、代わりに最初の設定済みプロバイダー/モデルへフォールバックします。 + 2. その正確なプレフィックスなしモデル ID に対する、一意の設定済みプロバイダー一致 + 3. 設定済みデフォルトプロバイダーへの非推奨フォールバック。そのプロバイダーが設定済みデフォルトモデルをもう公開していない場合、OpenClaw は古くなった削除済みプロバイダーのデフォルトを表面化させないように、代わりに最初の設定済みプロバイダー/モデルへフォールバックします。 -完全なコマンド動作/設定: [スラッシュコマンド](/ja-JP/tools/slash-commands)。 +コマンドの完全な動作/設定: [スラッシュコマンド](/ja-JP/tools/slash-commands)。 ## CLI コマンド @@ -222,14 +225,14 @@ openclaw models image-fallbacks remove openclaw models image-fallbacks clear ``` -`openclaw models`（サブコマンドなし）は `models status` のショートカットです。 +`openclaw models` (サブコマンドなし) は `models status` のショートカットです。 ### `models list` デフォルトでは、設定済み/認証利用可能なモデルを表示します。便利なフラグ: - 完全なカタログ。認証が設定される前の同梱プロバイダー所有の静的カタログ行を含むため、検出専用ビューで、一致するプロバイダー認証情報を追加するまで利用できないモデルを表示できます。 + 完全なカタログ。認証が設定される前の、同梱プロバイダー所有の静的カタログ行も含まれるため、検出専用ビューで、一致するプロバイダー認証情報を追加するまで利用できないモデルを表示できます。 ローカルプロバイダーのみ。 @@ -238,7 +241,7 @@ openclaw models image-fallbacks clear プロバイダー ID でフィルターします。例: `moonshot`。対話型ピッカーの表示ラベルは受け付けません。 - 1行に1モデル。 + 1 行に 1 つのモデル。 機械可読出力。 @@ -246,13 +249,13 @@ openclaw models image-fallbacks clear ### `models status` -解決済みのプライマリモデル、フォールバック、画像モデル、設定済みプロバイダーの認証概要を表示します。また、認証ストアで見つかったプロファイルの OAuth 有効期限ステータスも表示します（デフォルトでは24時間以内に警告）。`--plain` は解決済みのプライマリモデルのみを出力します。 +解決済みのプライマリモデル、フォールバック、画像モデル、設定済みプロバイダーの認証概要を表示します。また、認証ストア内で見つかったプロファイルの OAuth 有効期限ステータスも表示します（デフォルトでは 24 時間以内に警告）。`--plain` は解決済みのプライマリモデルのみを出力します。 - OAuth ステータスは常に表示されます（`--json` 出力にも含まれます）。設定済みプロバイダーに認証情報がない場合、`models status` は **認証不足** セクションを出力します。 - - JSON には `auth.oauth`（警告期間 + プロファイル）と `auth.providers`（env に基づく認証情報を含む、プロバイダーごとの有効な認証）が含まれます。`auth.oauth` は認証ストアのプロファイル健全性のみです。env のみのプロバイダーはそこには表示されません。 - - 自動化には `--check` を使用します（不足/期限切れの場合は終了コード `1`、期限切れ間近の場合は `2`）。 + - JSON には `auth.oauth`（警告ウィンドウ + プロファイル）と `auth.providers`（env による認証情報を含む、プロバイダーごとの有効な認証）が含まれます。`auth.oauth` は認証ストアのプロファイル健全性のみです。env のみのプロバイダーはそこには表示されません。 + - 自動化には `--check` を使用します（不足/期限切れの場合は終了 `1`、期限切れ間近の場合は `2`）。 - ライブ認証チェックには `--probe` を使用します。プローブ行は認証プロファイル、env 認証情報、または `models.json` から取得できます。 - 明示的な `auth.order.` が保存済みプロファイルを省略している場合、プローブは試行せずに `excluded_by_auth_order` を報告します。認証は存在するものの、そのプロバイダーでプローブ可能なモデルを解決できない場合、プローブは `status: no_model` を報告します。 @@ -260,7 +263,7 @@ openclaw models image-fallbacks clear -認証の選択はプロバイダー/アカウントに依存します。常時稼働の Gateway ホストでは、通常 API キーが最も予測しやすい方法です。Claude CLI の再利用と既存の Anthropic OAuth/トークンプロファイルもサポートされています。 +認証の選択はプロバイダー/アカウントに依存します。常時稼働の Gateway ホストでは、通常 API キーが最も予測可能です。Claude CLI の再利用と既存の Anthropic OAuth/token プロファイルもサポートされています。 例（Claude CLI）: @@ -272,7 +275,7 @@ openclaw models status ## スキャン（OpenRouter 無料モデル） -`openclaw models scan` は OpenRouter の **無料モデルカタログ** を検査し、任意でモデルのツールおよび画像サポートをプローブできます。 +`openclaw models scan` は OpenRouter の **無料モデルカタログ** を検査し、必要に応じてツールと画像サポートについてモデルをプローブできます。 ライブプローブをスキップします（メタデータのみ）。 @@ -297,10 +300,10 @@ openclaw models status -OpenRouter の `/models` カタログは公開されているため、メタデータのみのスキャンではキーなしで無料候補を一覧できます。プローブと推論には引き続き OpenRouter API キー（認証プロファイルまたは `OPENROUTER_API_KEY` から）が必要です。キーが利用できない場合、`openclaw models scan` はメタデータのみの出力にフォールバックし、設定は変更しません。メタデータのみのモードを明示的に要求するには `--no-probe` を使用します。 +OpenRouter の `/models` カタログは公開されているため、メタデータのみのスキャンではキーなしで無料候補を一覧表示できます。プローブと推論には引き続き OpenRouter API キー（認証プロファイルまたは `OPENROUTER_API_KEY` から）が必要です。キーを利用できない場合、`openclaw models scan` はメタデータのみの出力にフォールバックし、設定は変更しません。メタデータのみモードを明示的に要求するには `--no-probe` を使用します。 -スキャン結果は次の順でランク付けされます。 +スキャン結果は次の順でランク付けされます: 1. 画像サポート 2. ツールレイテンシ @@ -310,32 +313,32 @@ OpenRouter の `/models` カタログは公開されているため、メタデ 入力: - OpenRouter `/models` リスト（フィルター `:free`） -- ライブプローブには、認証プロファイルまたは `OPENROUTER_API_KEY` からの OpenRouter API キーが必要です（[環境変数](/ja-JP/help/environment) を参照） -- 任意のフィルター: `--max-age-days`、`--min-params`、`--provider`、`--max-candidates` -- リクエスト/プローブ制御: `--timeout`、`--concurrency` +- ライブプローブには、認証プロファイルまたは `OPENROUTER_API_KEY` からの OpenRouter API キーが必要です（[環境変数](/ja-JP/help/environment)を参照） +- 任意のフィルター: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates` +- リクエスト/プローブ制御: `--timeout`, `--concurrency` -ライブプローブが TTY で実行される場合、フォールバックを対話的に選択できます。非対話モードでは、デフォルトを受け入れるために `--yes` を渡します。メタデータのみの結果は情報提供用です。`--set-default` と `--set-image` にはライブプローブが必要です。これにより、OpenClaw が使用不能なキーなしの OpenRouter モデルを設定しないようにします。 +TTY でライブプローブを実行すると、フォールバックを対話的に選択できます。非対話モードでは、デフォルトを受け入れるために `--yes` を渡します。メタデータのみの結果は情報提供用です。OpenClaw が使用できないキーなしの OpenRouter モデルを設定しないように、`--set-default` と `--set-image` にはライブプローブが必要です。 ## モデルレジストリ（`models.json`） -`models.providers` のカスタムプロバイダーは、エージェントディレクトリ配下の `models.json`（デフォルトは `~/.openclaw/agents//agent/models.json`）に書き込まれます。このファイルは、`models.mode` が `replace` に設定されていない限りデフォルトでマージされます。 +`models.providers` のカスタムプロバイダーは、エージェントディレクトリ配下の `models.json`（デフォルト `~/.openclaw/agents//agent/models.json`）に書き込まれます。このファイルは、`models.mode` が `replace` に設定されていない限り、デフォルトでマージされます。 一致するプロバイダー ID に対するマージモードの優先順位: - エージェントの `models.json` にすでに存在する空でない `baseUrl` が優先されます。 - - エージェントの `models.json` 内の空でない `apiKey` は、そのプロバイダーが現在の設定/認証プロファイルコンテキストで SecretRef 管理ではない場合にのみ優先されます。 - - SecretRef 管理のプロバイダー `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（env 参照の場合は `ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。 - - SecretRef 管理のプロバイダーヘッダー値は、ソースマーカー（env 参照の場合は `secretref-env:ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。 + - エージェントの `models.json` にある空でない `apiKey` は、そのプロバイダーが現在の設定/認証プロファイルコンテキストで SecretRef 管理ではない場合のみ優先されます。 + - SecretRef 管理のプロバイダー `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（env refs は `ENV_VAR_NAME`、file/exec refs は `secretref-managed`）から更新されます。 + - SecretRef 管理のプロバイダーヘッダー値は、ソースマーカー（env refs は `secretref-env:ENV_VAR_NAME`、file/exec refs は `secretref-managed`）から更新されます。 - 空または欠落しているエージェントの `apiKey`/`baseUrl` は、設定の `models.providers` にフォールバックします。 - - その他のプロバイダーフィールドは、設定と正規化済みカタログデータから更新されます。 + - その他のプロバイダーフィールドは、設定と正規化されたカタログデータから更新されます。 -マーカーの永続化ではソースが権威です。OpenClaw は、解決済みランタイムシークレット値ではなく、アクティブなソース設定スナップショット（解決前）からマーカーを書き込みます。これは、`openclaw agent` のようなコマンド駆動パスを含め、OpenClaw が `models.json` を再生成するたびに適用されます。 +マーカーの永続化ではソースが権威です。OpenClaw は解決済みのランタイムシークレット値ではなく、アクティブなソース設定スナップショット（解決前）からマーカーを書き込みます。これは、`openclaw agent` のようなコマンド駆動の経路を含め、OpenClaw が `models.json` を再生成するたびに適用されます。 ## 関連 diff --git a/docs/ja-JP/concepts/qa-e2e-automation.md b/docs/ja-JP/concepts/qa-e2e-automation.md index 350fc9681..01ea5dcbc 100644 --- a/docs/ja-JP/concepts/qa-e2e-automation.md +++ b/docs/ja-JP/concepts/qa-e2e-automation.md @@ -3,65 +3,66 @@ read_when: - QA スタックがどのように連携するかを理解する - qa-lab、qa-channel、またはトランスポートアダプターの拡張 - リポジトリに基づく QA シナリオの追加 - - Gateway ダッシュボードを対象にした、より実環境に近い QA 自動化の構築 -summary: 'QA スタックの概要: qa-lab、qa-channel、リポジトリベースのシナリオ、ライブトランスポートレーン、トランスポートアダプター、レポート作成。' + - Gateway ダッシュボードを対象に、より実運用に近い QA 自動化を構築する +summary: 'QA スタックの概要: qa-lab、qa-channel、リポジトリに基づくシナリオ、ライブトランスポートレーン、トランスポートアダプター、レポート。' title: QA の概要 x-i18n: - generated_at: "2026-05-04T04:58:46Z" + generated_at: "2026-05-05T01:45:16Z" model: gpt-5.5 provider: openai - source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29 + source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96 source_path: concepts/qa-e2e-automation.md workflow: 16 --- -プライベート QA スタックは、単一のユニットテストで可能な範囲よりも現実に近い、チャンネルに沿った形で OpenClaw を実行することを目的としています。 +プライベート QA スタックは、単一のユニットテストよりも現実に近い、 +チャンネルの形に沿った方法で OpenClaw を実行するためのものです。 現在の構成要素: - `extensions/qa-channel`: DM、チャンネル、スレッド、 リアクション、編集、削除のサーフェスを持つ合成メッセージチャンネル。 - `extensions/qa-lab`: トランスクリプトの観察、 - インバウンドメッセージの注入、Markdown レポートのエクスポートを行うデバッガー UI と QA バス。 -- `extensions/qa-matrix`、将来のランナー Plugin: 子 QA Gateway 内で - 実際のチャンネルを駆動するライブトランスポートアダプター。 + 受信メッセージの注入、Markdown レポートのエクスポートを行うデバッガー UI と QA バス。 +- `extensions/qa-matrix`、将来のランナーPlugin: 子 QA Gateway 内で + 実チャンネルを駆動するライブトランスポートアダプター。 - `qa/`: キックオフタスクとベースライン QA シナリオ用のリポジトリ管理シードアセット。 -- [Mantis](/ja-JP/concepts/mantis): 実トランスポート、ブラウザのスクリーンショット、 - VM の状態、PR 証拠が必要なバグに対する事前および事後のライブ検証。 +- [Mantis](/ja-JP/concepts/mantis): 実トランスポート、ブラウザスクリーンショット、VM 状態、PR 証跡が + 必要なバグの修正前後ライブ検証。 ## コマンドサーフェス -すべての QA フローは `pnpm openclaw qa ` の下で実行されます。多くには `pnpm qa:*` -スクリプトエイリアスがあります。どちらの形式もサポートされています。 +すべての QA フローは `pnpm openclaw qa ` の下で実行されます。多くは `pnpm qa:*` +スクリプトエイリアスを持ち、どちらの形式もサポートされています。 -| コマンド | 目的 | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `qa run` | バンドルされた QA セルフチェック。Markdown レポートを書き出します。 | -| `qa suite` | QA Gateway レーンに対してリポジトリ管理シナリオを実行します。エイリアス: 使い捨て Linux VM 用の `pnpm openclaw qa suite --runner multipass`。 | -| `qa coverage` | Markdown のシナリオカバレッジ目録を出力します（機械出力には `--json`）。 | -| `qa parity-report` | 2 つの `qa-suite-summary.json` ファイルを比較し、エージェント的パリティレポートを書き出します。 | -| `qa character-eval` | 複数のライブモデルにわたってキャラクター QA シナリオを実行し、判定付きレポートを生成します。[レポート](#reporting)を参照してください。 | -| `qa manual` | 選択したプロバイダー/モデルレーンに対して単発のプロンプトを実行します。 | +| コマンド | 目的 | +| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `qa run` | バンドルされた QA 自己チェック。Markdown レポートを書き込みます。 | +| `qa suite` | リポジトリ管理シナリオを QA Gateway レーンに対して実行します。エイリアス: 使い捨て Linux VM 用の `pnpm openclaw qa suite --runner multipass`。 | +| `qa coverage` | Markdown のシナリオカバレッジインベントリを出力します（機械出力には `--json`）。 | +| `qa parity-report` | 2 つの `qa-suite-summary.json` ファイルを比較し、エージェントによるパリティレポートを書き込みます。 | +| `qa character-eval` | 複数のライブモデルに対してキャラクター QA シナリオを実行し、判定付きレポートを作成します。[レポート](#reporting)を参照してください。 | +| `qa manual` | 選択されたプロバイダー/モデルレーンに対して単発プロンプトを実行します。 | | `qa ui` | QA デバッガー UI とローカル QA バスを起動します（エイリアス: `pnpm qa:lab:ui`）。 | -| `qa docker-build-image` | 事前構築済み QA Docker イメージをビルドします。 | -| `qa docker-scaffold` | QA ダッシュボード + Gateway レーン用の docker-compose スキャフォールドを書き出します。 | -| `qa up` | QA サイトをビルドし、Docker ベースのスタックを起動して URL を出力します（エイリアス: `pnpm qa:lab:up`。`:fast` バリアントは `--use-prebuilt-image --bind-ui-dist --skip-ui-build` を追加）。 | -| `qa aimock` | AIMock プロバイダーサーバーのみを起動します。 | -| `qa mock-openai` | シナリオ認識型の `mock-openai` プロバイダーサーバーのみを起動します。 | -| `qa credentials doctor` / `add` / `list` / `remove` | 共有 Convex 認証情報プールを管理します。 | -| `qa matrix` | 使い捨て Tuwunel ホームサーバーに対するライブトランスポートレーン。[Matrix QA](/ja-JP/concepts/qa-matrix)を参照してください。 | -| `qa telegram` | 実際のプライベート Telegram グループに対するライブトランスポートレーン。 | -| `qa discord` | 実際のプライベート Discord ギルドチャンネルに対するライブトランスポートレーン。 | -| `qa slack` | 実際のプライベート Slack チャンネルに対するライブトランスポートレーン。 | -| `qa mantis` | ライブトランスポートバグの事前および事後検証ランナー。Discord ステータスリアクション証拠、Crabbox デスクトップ/ブラウザスモーク、Slack-in-VNC スモークを含みます。[Mantis](/ja-JP/concepts/mantis)を参照してください。 | +| `qa docker-build-image` | 事前作成済み QA Docker イメージをビルドします。 | +| `qa docker-scaffold` | QA ダッシュボード + Gateway レーン用の docker-compose スキャフォールドを書き込みます。 | +| `qa up` | QA サイトをビルドし、Docker ベースのスタックを起動して、URL を出力します（エイリアス: `pnpm qa:lab:up`; `:fast` バリアントは `--use-prebuilt-image --bind-ui-dist --skip-ui-build` を追加）。 | +| `qa aimock` | AIMock プロバイダーサーバーのみを起動します。 | +| `qa mock-openai` | シナリオ対応の `mock-openai` プロバイダーサーバーのみを起動します。 | +| `qa credentials doctor` / `add` / `list` / `remove` | 共有 Convex 認証情報プールを管理します。 | +| `qa matrix` | 使い捨て Tuwunel ホームサーバーに対するライブトランスポートレーンです。[Matrix QA](/ja-JP/concepts/qa-matrix)を参照してください。 | +| `qa telegram` | 実際のプライベート Telegram グループに対するライブトランスポートレーンです。 | +| `qa discord` | 実際のプライベート Discord ギルドチャンネルに対するライブトランスポートレーンです。 | +| `qa slack` | 実際のプライベート Slack チャンネルに対するライブトランスポートレーンです。 | +| `qa mantis` | Discord ステータスリアクション証跡、Crabbox デスクトップ/ブラウザスモーク、Slack-in-VNC スモークを含む、ライブトランスポートバグの修正前後検証ランナーです。[Mantis](/ja-JP/concepts/mantis)を参照してください。 | ## オペレーターフロー -現在の QA オペレーターフローは、2 ペインの QA サイトです。 +現在の QA オペレーターフローは 2 ペインの QA サイトです。 - 左: エージェントを含む Gateway ダッシュボード（Control UI）。 -- 右: Slack 風のトランスクリプトとシナリオ計画を表示する QA Lab。 +- 右: Slack風のトランスクリプトとシナリオ計画を表示する QA Lab。 次で実行します。 @@ -69,12 +70,12 @@ x-i18n: pnpm qa:lab:up ``` -これにより QA サイトがビルドされ、Docker ベースの Gateway レーンが起動し、 -QA Lab ページが公開されます。そこでオペレーターまたは自動化ループは、エージェントに QA -ミッションを与え、実際のチャンネル動作を観察し、動作したこと、失敗したこと、または -ブロックされたままのことを記録できます。 +これは QA サイトをビルドし、Docker ベースの Gateway レーンを起動して、 +オペレーターまたは自動化ループがエージェントに QA +ミッションを与え、実チャンネルの動作を観察し、成功したこと、失敗したこと、 +またはブロックされたままのことを記録できる QA Lab ページを公開します。 -毎回 Docker イメージを再ビルドせずに QA Lab UI をより高速に反復するには、 +毎回 Docker イメージをリビルドせずに QA Lab UI をすばやく反復するには、 バインドマウントされた QA Lab バンドルでスタックを起動します。 ```bash @@ -84,9 +85,9 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` は Docker サービスを事前構築済みイメージ上で維持し、 -`extensions/qa-lab/web/dist` を `qa-lab` コンテナーにバインドマウントします。`qa:lab:watch` -は変更時にそのバンドルを再ビルドし、QA Lab +`qa:lab:up:fast` は Docker サービスを事前ビルド済みイメージ上に維持し、 +`extensions/qa-lab/web/dist` を `qa-lab` コンテナにバインドマウントします。`qa:lab:watch` +は変更時にそのバンドルをリビルドし、QA Lab アセットハッシュが変わるとブラウザが自動リロードします。 ローカル OpenTelemetry トレーススモークには、次を実行します。 @@ -96,28 +97,29 @@ pnpm qa:otel:smoke ``` このスクリプトはローカル OTLP/HTTP トレースレシーバーを起動し、 -`diagnostics-otel` Plugin を有効にして `otel-trace-smoke` QA シナリオを実行した後、 -エクスポートされた protobuf span をデコードして、リリース上重要な形を検証します: +`diagnostics-otel` Plugin を有効にして +`otel-trace-smoke` QA シナリオを実行した後、 +エクスポートされた protobuf スパンをデコードし、リリース上重要な形を検証します。 `openclaw.run`、`openclaw.harness.run`、`openclaw.model.call`、 `openclaw.context.assembled`、`openclaw.message.delivery` が存在する必要があります。 -モデル呼び出しは成功したターンで `StreamAbandoned` をエクスポートしてはなりません。生の診断 ID と -`openclaw.content.*` 属性はトレースに含めない必要があります。QA スイートアーティファクトの横に -`otel-smoke-summary.json` を書き出します。 +成功したターンでモデル呼び出しが `StreamAbandoned` をエクスポートしてはいけません。生の診断 ID と +`openclaw.content.*` 属性はトレースから除外されている必要があります。QA スイート成果物の隣に +`otel-smoke-summary.json` を書き込みます。 Observability QA はソースチェックアウト専用のままです。npm tarball は意図的に -QA Lab を省略しているため、パッケージ Docker リリースレーンでは `qa` コマンドを実行しません。 -診断インストルメンテーションを変更するときは、ビルド済みソースチェックアウトから +QA Lab を除外しているため、パッケージ Docker リリースレーンでは `qa` コマンドを実行しません。 +診断インストルメンテーションを変更する場合は、ビルド済みソースチェックアウトから `pnpm qa:otel:smoke` を使用してください。 -トランスポート実体ありの Matrix スモークレーンには、次を実行します。 +実トランスポート Matrix スモークレーンには、次を実行します。 ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -このレーンの完全な CLI リファレンス、プロファイル/シナリオカタログ、env vars、アーティファクトレイアウトは [Matrix QA](/ja-JP/concepts/qa-matrix) にあります。概略: Docker 内に使い捨て Tuwunel ホームサーバーをプロビジョニングし、一時的なドライバー/SUT/オブザーバーユーザーを登録し、そのトランスポートにスコープされた子 QA Gateway 内で実際の Matrix Plugin を実行し（`qa-channel` は使用しません）、その後 Markdown レポート、JSON サマリー、観測イベントアーティファクト、結合出力ログを `.artifacts/qa-e2e/matrix-/` 配下に書き出します。 +このレーンの完全な CLI リファレンス、プロファイル/シナリオカタログ、環境変数、成果物レイアウトは [Matrix QA](/ja-JP/concepts/qa-matrix) にあります。概要: Docker 内に使い捨て Tuwunel ホームサーバーをプロビジョニングし、一時的なドライバー/SUT/オブザーバーユーザーを登録し、そのトランスポートにスコープされた子 QA Gateway 内で実際の Matrix Plugin を実行し（`qa-channel` なし）、Markdown レポート、JSON サマリー、観測イベント成果物、結合出力ログを `.artifacts/qa-e2e/matrix-/` の下に書き込みます。 -トランスポート実体ありの Telegram、Discord、Slack スモークレーンには、次を実行します。 +実トランスポート Telegram、Discord、Slack スモークレーンには、次を実行します。 ```bash pnpm openclaw qa telegram @@ -125,7 +127,7 @@ pnpm openclaw qa discord pnpm openclaw qa slack ``` -これらは 2 つのボット（ドライバー + SUT）を持つ既存の実チャンネルを対象にします。必要な env vars、シナリオ一覧、出力アーティファクト、Convex 認証情報プールは、下の [Telegram、Discord、Slack QA リファレンス](#telegram-discord-and-slack-qa-reference)に記載されています。 +これらは 2 つのボット（ドライバー + SUT）を持つ既存の実チャンネルを対象にします。必要な環境変数、シナリオ一覧、出力成果物、Convex 認証情報プールは、下の [Telegram、Discord、Slack QA リファレンス](#telegram-discord-and-slack-qa-reference)に記載されています。 VNC レスキュー付きの完全な Slack デスクトップ VM 実行には、次を実行します。 @@ -137,12 +139,12 @@ pnpm openclaw qa mantis slack-desktop-smoke \ ``` このコマンドは Crabbox デスクトップ/ブラウザマシンをリースし、VM 内で Slack ライブレーンを実行し、 -VNC ブラウザで Slack Web を開き、デスクトップをキャプチャし、 -`slack-qa/` と `slack-desktop-smoke.png` を Mantis アーティファクト -ディレクトリにコピーします。VNC 経由で Slack Web に手動ログインした後、 -`--lease-id ` を再利用してください。`--gateway-setup` を指定すると、Mantis は永続的な OpenClaw Slack -Gateway を VM 内のポート `38973` で起動したままにします。指定しない場合、コマンドは通常の -ボット対ボット Slack QA レーンを実行し、アーティファクトキャプチャ後に終了します。 +VNC ブラウザで Slack Web を開き、デスクトップをキャプチャして、 +`slack-qa/` と `slack-desktop-smoke.png` を Mantis 成果物ディレクトリへコピーします。 +VNC 経由で Slack Web に手動ログインした後、`--lease-id ` を再利用してください。 +`--gateway-setup` を指定すると、Mantis は永続的な OpenClaw Slack +Gateway を VM 内のポート `38973` で実行したままにします。指定しない場合、コマンドは +通常のボット間 Slack QA レーンを実行し、成果物キャプチャ後に終了します。 プールされたライブ認証情報を使用する前に、次を実行します。 @@ -150,65 +152,56 @@ Gateway を VM 内のポート `38973` で起動したままにします。指 pnpm openclaw qa credentials doctor ``` -doctor は Convex ブローカー env を確認し、エンドポイント設定を検証し、メンテナーシークレットが存在する場合は admin/list の到達性を検証します。シークレットについては設定済み/欠落の状態のみを報告します。 +doctor は Convex ブローカー環境をチェックし、エンドポイント設定を検証し、メンテナーシークレットが存在する場合は admin/list 到達性を確認します。シークレットについては set/missing 状態のみを報告します。 ## ライブトランスポートカバレッジ -ライブトランスポートレーンは、それぞれが独自のシナリオ一覧形式を発明するのではなく、1 つの契約を共有します。`qa-channel` は広範な合成プロダクト動作スイートであり、ライブトランスポートカバレッジマトリクスの一部ではありません。 +ライブトランスポートレーンは、それぞれが独自のシナリオリスト形状を作るのではなく、1 つの契約を共有します。`qa-channel` は広範な合成プロダクト動作スイートであり、ライブトランスポートカバレッジマトリックスの一部ではありません。 -| レーン | Canary | メンションゲーティング | ボット対ボット | Allowlist ブロック | トップレベル返信 | 再起動再開 | スレッドフォローアップ | スレッド分離 | リアクション観察 | ヘルプコマンド | ネイティブコマンド登録 | -| -------- | ------ | ---------------------- | -------------- | ------------------ | ---------------- | ---------- | ---------------------- | ------------ | ---------------- | -------------- | ---------------------- | -| Matrix | x | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | x | | | | | | | x | | -| Discord | x | x | x | | | | | | | | x | -| Slack | x | x | x | | | | | | | | | +| レーン | Canary | メンションゲート | ボット間 | Allowlist ブロック | トップレベル返信 | 再起動再開 | スレッドフォローアップ | スレッド分離 | リアクション観察 | ヘルプコマンド | ネイティブコマンド登録 | +| -------- | ------ | ---------------- | -------- | ------------------ | ---------------- | ---------- | ---------------------- | ------------ | ------------------ | -------------- | ------------------------ | +| Matrix | x | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | x | | | | | | | x | | +| Discord | x | x | x | | | | | | | | x | +| Slack | x | x | x | | | | | | | | | -これにより、`qa-channel` は広範なプロダクト動作スイートとして維持される一方、Matrix、 -Telegram、将来のライブトランスポートは 1 つの明示的なトランスポート契約 +これにより、`qa-channel` は広範なプロダクト動作スイートとして維持される一方で、 +Matrix、Telegram、将来のライブトランスポートは 1 つの明示的なトランスポート契約 チェックリストを共有します。 -Docker を QA パスに持ち込まずに使い捨て Linux VM レーンを実行するには、次を実行します。 +QA パスに Docker を持ち込まない使い捨て Linux VM レーンには、次を実行します。 ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -これは新しい Multipass ゲストを起動し、依存関係をインストールし、ゲスト内で OpenClaw -をビルドし、`qa suite` を実行してから、通常の QA レポートと -サマリーをホスト上の `.artifacts/qa-e2e/...` にコピーします。 +これにより新しい Multipass ゲストが起動し、依存関係がインストールされ、ゲスト内で OpenClaw がビルドされ、`qa suite` が実行された後、通常の QA レポートとサマリーがホスト上の `.artifacts/qa-e2e/...` にコピーされます。 ホスト上の `qa suite` と同じシナリオ選択動作を再利用します。 -ホストと Multipass のスイート実行は、既定では分離された Gateway ワーカーで -選択された複数のシナリオを並列実行します。`qa-channel` の既定の並行数は -4 で、選択されたシナリオ数が上限です。ワーカー数を調整するには -`--concurrency ` を使用し、シリアル実行には `--concurrency 1` を使用します。 -いずれかのシナリオが失敗すると、このコマンドは非ゼロで終了します。失敗終了コードなしで -成果物が必要な場合は `--allow-failures` を使用します。 -ライブ実行では、ゲストで実用的なサポート対象の QA 認証入力が転送されます: -env ベースのプロバイダーキー、QA ライブプロバイダー設定パス、および -存在する場合は `CODEX_HOME`。ゲストがマウントされたワークスペース経由で -書き戻せるように、`--output-dir` はリポジトリルート配下に置いてください。 +ホストと Multipass のスイート実行では、デフォルトで、選択された複数のシナリオを分離された Gateway ワーカーで並列実行します。`qa-channel` のデフォルト並行数は 4 で、選択されたシナリオ数が上限です。ワーカー数を調整するには `--concurrency ` を使用し、シリアル実行には `--concurrency 1` を使用します。 +いずれかのシナリオが失敗すると、このコマンドは非ゼロで終了します。失敗終了コードなしでアーティファクトが必要な場合は `--allow-failures` を使用します。 +ライブ実行では、ゲストで実用的なサポート対象の QA 認証入力が転送されます。env ベースのプロバイダーキー、QA ライブプロバイダー設定パス、存在する場合は `CODEX_HOME` です。ゲストがマウントされたワークスペース経由で書き戻せるように、`--output-dir` はリポジトリルート配下に置いてください。 -## Telegram、Discord、Slack の QA リファレンス +## Telegram、Discord、Slack QA リファレンス -Matrix には、シナリオ数と Docker ベースのホームサーバープロビジョニングがあるため、[専用ページ](/ja-JP/concepts/qa-matrix)があります。Telegram、Discord、Slack はより小規模で、それぞれ少数のシナリオ、プロファイルシステムなし、既存の実チャンネルに対する実行なので、それらのリファレンスはここにあります。 +Matrix はシナリオ数が多く、Docker ベースの homeserver プロビジョニングがあるため、[専用ページ](/ja-JP/concepts/qa-matrix)があります。Telegram、Discord、Slack はより小規模で、それぞれ少数のシナリオのみ、プロファイルシステムなし、既存の実チャンネルを対象とするため、リファレンスはここにあります。 ### 共有 CLI フラグ -これらのレーンは `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` 経由で登録され、同じフラグを受け付けます: +これらのレーンは `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` を通じて登録され、同じフラグを受け付けます。 -| フラグ | 既定値 | 説明 | +| フラグ | デフォルト | 説明 | | ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | このシナリオだけを実行します。繰り返し指定できます。 | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | レポート、サマリー、観測メッセージ、および出力ログの書き込み先です。相対パスは `--repo-root` を基準に解決されます。 | -| `--repo-root ` | `process.cwd()` | 中立的な cwd から呼び出す場合のリポジトリルートです。 | -| `--sut-account ` | `sut` | QA Gateway 設定内の一時アカウント id です。 | -| `--provider-mode ` | `live-frontier` | `mock-openai` または `live-frontier` です（レガシーの `live-openai` も引き続き動作します）。 | -| `--model ` / `--alt-model ` | プロバイダーの既定値 | プライマリ/代替モデル ref です。 | -| `--fast` | オフ | サポートされる場合のプロバイダー高速モードです。 | -| `--credential-source ` | `env` | [Convex 認証情報プール](#convex-credential-pool)を参照してください。 | -| `--credential-role ` | CI では `ci`、それ以外では `maintainer` | `--credential-source convex` の場合に使用されるロールです。 | +| `--scenario ` | — | このシナリオのみを実行します。繰り返し指定できます。 | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | レポート、サマリー、観測メッセージ、出力ログの書き込み先です。相対パスは `--repo-root` を基準に解決されます。 | +| `--repo-root ` | `process.cwd()` | 中立的な cwd から呼び出す場合のリポジトリルートです。 | +| `--sut-account ` | `sut` | QA Gateway 設定内の一時アカウント id です。 | +| `--provider-mode ` | `live-frontier` | `mock-openai` または `live-frontier`（レガシーの `live-openai` も引き続き動作します）。 | +| `--model ` / `--alt-model ` | プロバイダーのデフォルト | プライマリ/代替モデル参照です。 | +| `--fast` | オフ | サポートされている場合のプロバイダー高速モードです。 | +| `--credential-source ` | `env` | [Convex 認証情報プール](#convex-credential-pool)を参照してください。 | +| `--credential-role ` | CI では `ci`、それ以外では `maintainer` | `--credential-source convex` の場合に使用されるロールです。 | -各レーンは、いずれかのシナリオが失敗すると非ゼロで終了します。`--allow-failures` は失敗終了コードを設定せずに成果物を書き込みます。 +各レーンはいずれかのシナリオが失敗すると非ゼロで終了します。`--allow-failures` は失敗終了コードを設定せずにアーティファクトを書き込みます。 ### Telegram QA @@ -216,7 +209,7 @@ Matrix には、シナリオ数と Docker ベースのホームサーバープ pnpm openclaw qa telegram ``` -2 つの異なる bot（ドライバー + SUT）を持つ、1 つの実際のプライベート Telegram グループを対象にします。SUT bot には Telegram ユーザー名が必要です。bot 間の観測は、両方の bot で `@BotFather` の **Bot-to-Bot Communication Mode** が有効になっている場合に最もよく機能します。 +2 つの異なる bot（ドライバー + SUT）を持つ、1 つの実プライベート Telegram グループを対象にします。SUT bot には Telegram ユーザー名が必要です。bot 間の観測は、両方の bot で `@BotFather` の **Bot-to-Bot Communication Mode** が有効な場合に最もよく動作します。 `--credential-source env` の場合に必要な env: @@ -226,7 +219,7 @@ pnpm openclaw qa telegram 任意: -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` は、観測メッセージ成果物内のメッセージ本文を保持します（既定ではマスク）。 +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` は観測メッセージアーティファクトにメッセージ本文を保持します（デフォルトではリダクトされます）。 シナリオ（`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`）: @@ -239,11 +232,11 @@ pnpm openclaw qa telegram - `telegram-whoami-command` - `telegram-context-command` -出力成果物: +出力アーティファクト: - `telegram-qa-report.md` - `telegram-qa-summary.json` — canary から始まる返信ごとの RTT（ドライバー送信 → 観測された SUT 返信）を含みます。 -- `telegram-qa-observed-messages.json` — `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` でない限り、本文はマスクされます。 +- `telegram-qa-observed-messages.json` — `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` でない限り本文はリダクトされます。 ### Discord QA @@ -251,7 +244,7 @@ pnpm openclaw qa telegram pnpm openclaw qa discord ``` -2 つの bot を持つ、1 つの実際のプライベート Discord ギルドチャンネルを対象にします: ハーネスで制御されるドライバー bot と、同梱の Discord Plugin 経由で子 OpenClaw Gateway により起動される SUT bot です。チャンネルメンション処理、SUT bot が Discord にネイティブの `/help` コマンドを登録済みであること、およびオプトインの Mantis 証拠シナリオを検証します。 +2 つの bot を持つ、1 つの実プライベート Discord guild チャンネルを対象にします。ハーネスが制御するドライバー bot と、バンドルされた Discord Plugin を通じて子 OpenClaw Gateway によって起動される SUT bot です。チャンネルメンション処理、SUT bot が Discord にネイティブ `/help` コマンドを登録していること、オプトインの Mantis 証拠シナリオを検証します。 `--credential-source env` の場合に必要な env: @@ -259,20 +252,20 @@ pnpm openclaw qa discord - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — Discord が返す SUT bot ユーザー id と一致する必要があります（一致しない場合、このレーンは早期に失敗します）。 +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — Discord が返す SUT bot ユーザー id と一致している必要があります（一致しない場合、レーンは即座に失敗します）。 任意: -- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` は、観測メッセージ成果物内のメッセージ本文を保持します。 +- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` は観測メッセージアーティファクトにメッセージ本文を保持します。 シナリオ（`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`）: - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — オプトインの Mantis シナリオです。SUT を常時オン、ツールのみのギルド返信に切り替え、`messages.statusReactions.enabled=true` を設定してから、REST リアクションタイムラインと HTML/PNG ビジュアル成果物をキャプチャするため、単独で実行されます。 +- `discord-status-reactions-tool-only` — オプトインの Mantis シナリオです。SUT を常時オン、ツールのみの guild 返信に切り替え、`messages.statusReactions.enabled=true` を指定したうえで、REST リアクションタイムラインと HTML/PNG ビジュアルアーティファクトをキャプチャするため、単独で実行されます。 -Mantis ステータスリアクションシナリオを明示的に実行します: +Mantis ステータスリアクションシナリオを明示的に実行します。 ```bash pnpm openclaw qa discord \ @@ -283,12 +276,12 @@ pnpm openclaw qa discord \ --fast ``` -出力成果物: +出力アーティファクト: - `discord-qa-report.md` - `discord-qa-summary.json` -- `discord-qa-observed-messages.json` — `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` でない限り、本文はマスクされます。 -- ステータスリアクションシナリオを実行した場合は `discord-qa-reaction-timelines.json` と `discord-status-reactions-tool-only-timeline.png`。 +- `discord-qa-observed-messages.json` — `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` でない限り本文はリダクトされます。 +- ステータスリアクションシナリオが実行された場合は、`discord-qa-reaction-timelines.json` と `discord-status-reactions-tool-only-timeline.png`。 ### Slack QA @@ -296,7 +289,7 @@ pnpm openclaw qa discord \ pnpm openclaw qa slack ``` -2 つの異なる bot を持つ、1 つの実際のプライベート Slack チャンネルを対象にします: ハーネスで制御されるドライバー bot と、同梱の Slack Plugin 経由で子 OpenClaw Gateway により起動される SUT bot です。 +2 つの異なる bot を持つ、1 つの実プライベート Slack チャンネルを対象にします。ハーネスが制御するドライバー bot と、バンドルされた Slack Plugin を通じて子 OpenClaw Gateway によって起動される SUT bot です。 `--credential-source env` の場合に必要な env: @@ -307,142 +300,304 @@ pnpm openclaw qa slack 任意: -- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` は、観測メッセージ成果物内のメッセージ本文を保持します。 +- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` は観測メッセージアーティファクトにメッセージ本文を保持します。 シナリオ（`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`）: - `slack-canary` - `slack-mention-gating` -出力成果物: +出力アーティファクト: - `slack-qa-report.md` - `slack-qa-summary.json` -- `slack-qa-observed-messages.json` — `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` でない限り、本文はマスクされます。 +- `slack-qa-observed-messages.json` — `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` でない限り本文はリダクトされます。 + +#### Slack ワークスペースのセットアップ + +このレーンには、1 つのワークスペース内に 2 つの異なる Slack app と、両方の bot がメンバーになっているチャンネルが必要です。 + +- `channelId` — 両方の bot が招待されているチャンネルの `Cxxxxxxxxxx` id です。専用チャンネルを使用してください。このレーンは実行のたびに投稿します。 +- `driverBotToken` — **Driver** app の bot token（`xoxb-...`）です。 +- `sutBotToken` — **SUT** app の bot token（`xoxb-...`）です。bot ユーザー id が異なるように、ドライバーとは別の Slack app である必要があります。 +- `sutAppToken` — `connections:write` を持つ SUT app の app-level token（`xapp-...`）です。SUT app がイベントを受信できるように Socket Mode で使用されます。 + +本番ワークスペースを再利用するより、QA 専用の Slack ワークスペースを推奨します。 + +以下の SUT マニフェストは、バンドルされた Slack Plugin の本番インストール（`extensions/slack/src/setup-shared.ts:10`）を反映しています。ユーザーから見える本番チャンネルセットアップについては、[Slack チャンネルのクイックセットアップ](/ja-JP/channels/slack#quick-setup)を参照してください。QA Driver/SUT ペアは、レーンが 1 つのワークスペース内で 2 つの異なる bot ユーザー id を必要とするため、意図的に分離されています。 + +**1. Driver app を作成する** + +[api.slack.com/apps](https://api.slack.com/apps) に移動し、_Create New App_ → _From a manifest_ → QA ワークスペースを選択、以下のマニフェストを貼り付け、_Install to Workspace_ を実行します。 + +```json +{ + "display_information": { + "name": "OpenClaw QA Driver", + "description": "Test driver bot for OpenClaw QA Slack live lane" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw QA Driver", + "always_online": true + } + }, + "oauth_config": { + "scopes": { + "bot": ["chat:write", "channels:history", "groups:history", "users:read"] + } + }, + "settings": { + "socket_mode_enabled": false + } +} +``` + +_Bot User OAuth Token_（`xoxb-...`）をコピーします。これが `driverBotToken` になります。ドライバーはメッセージを投稿し、自身を識別するだけでよいため、イベントも Socket Mode も不要です。 + +**2. SUT app を作成する** + +同じワークスペースで _Create New App → From a manifest_ を繰り返します。スコープセットは、バンドルされた Slack Plugin の本番インストール（`extensions/slack/src/setup-shared.ts:10`）を反映しています。 + +```json +{ + "display_information": { + "name": "OpenClaw QA SUT", + "description": "OpenClaw QA SUT connector for OpenClaw" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw QA SUT", + "always_online": true + }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + } + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + +Slack が app を作成した後、その設定ページで 2 つの作業を行います。 + +- _Install to Workspace_ → _Bot User OAuth Token_ をコピー → これが `sutBotToken` になります。 +- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → スコープ `connections:write` を追加 → 保存 → `xapp-...` の値をコピー → これが `sutAppToken` になります。 + +各トークンで `auth.test` を呼び出して、2 つのボットが別々のユーザー ID を持つことを確認します。ランタイムはユーザー ID でドライバーと SUT を区別します。両方に 1 つのアプリを再利用すると、mention-gating は即座に失敗します。 + +**3. チャンネルを作成する** + +QA ワークスペースでチャンネル（例: `#openclaw-qa`）を作成し、チャンネル内から両方のボットを招待します。 + +``` +/invite @OpenClaw QA Driver +/invite @OpenClaw QA SUT +``` + +_チャンネル情報 → 概要 → チャンネル ID_ から `Cxxxxxxxxxx` ID をコピーします。これが `channelId` になります。パブリックチャンネルで問題ありません。プライベートチャンネルを使う場合でも、両方のアプリはすでに `groups:history` を持っているため、ハーネスの履歴読み取りは引き続き成功します。 + +**4. 認証情報を登録する** + +選択肢は 2 つあります。単一マシンのデバッグには env vars を使います（4 つの `OPENCLAW_QA_SLACK_*` 変数を設定し、`--credential-source env` を渡します）。または、CI と他のメンテナーがリースできるように共有 Convex プールにシードします。 + +Convex プールでは、4 つのフィールドを JSON ファイルに書き込みます。 + +```json +{ + "channelId": "Cxxxxxxxxxx", + "driverBotToken": "xoxb-...", + "sutBotToken": "xoxb-...", + "sutAppToken": "xapp-..." +} +``` + +シェルで `OPENCLAW_QA_CONVEX_SITE_URL` と `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` を export した状態で、登録して確認します。 + +```bash +pnpm openclaw qa credentials add \ + --kind slack \ + --payload-file slack-creds.json \ + --note "QA Slack pool seed" + +pnpm openclaw qa credentials list --kind slack --status all --json +``` + +`count: 1`、`status: "active"`、`lease` フィールドなし、となることを期待します。 + +**5. エンドツーエンドで確認する** + +ブローカー経由で両方のボットが相互に会話できることを確認するため、レーンをローカルで実行します。 + +```bash +pnpm openclaw qa slack \ + --credential-source convex \ + --credential-role maintainer \ + --output-dir .artifacts/qa-e2e/slack-local +``` + +正常な実行は 30 秒を大きく下回る時間で完了し、`slack-qa-report.md` では `slack-canary` と `slack-mention-gating` の両方がステータス `pass` になります。レーンが約 90 秒ハングして `Convex credential pool exhausted for kind "slack"` で終了する場合、プールが空か、すべての行がリース中です。`qa credentials list --kind slack --status all --json` でどちらかを確認できます。 ### Convex 認証情報プール -Telegram、Discord、Slack のレーンは、上記の env vars を読む代わりに、共有 Convex プールから認証情報をリースできます。`--credential-source convex` を渡します（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定します）。QA Lab は排他的リースを取得し、実行中は Heartbeat を送信し、シャットダウン時に解放します。プール kind は `"telegram"`、`"discord"`、`"slack"` です。 +Telegram、Discord、Slack レーンは、上記の env vars を読み取る代わりに共有 Convex プールから認証情報をリースできます。`--credential-source convex` を渡すか、`OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定します。QA Lab は排他的リースを取得し、実行中は Heartbeat を送り、シャットダウン時に解放します。プールの種類は `"telegram"`、`"discord"`、`"slack"` です。 -ブローカーが `admin/add` で検証するペイロード形状: +`admin/add` でブローカーが検証するペイロード形状: -- Telegram（`kind: "telegram"`）: `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` は数値の chat-id 文字列である必要があります。 -- Discord（`kind: "discord"`）: `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`。 +- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` は数値チャット ID 文字列である必要があります。 +- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`。 +- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` は `^[A-Z][A-Z0-9]+$`（`Cxxxxxxxxxx` のような Slack ID）に一致する必要があります。アプリとスコープのプロビジョニングについては、[Slack ワークスペースの設定](#setting-up-the-slack-workspace)を参照してください。 -運用 env vars と Convex ブローカーエンドポイント契約は、[テスト → Convex 経由の共有 Telegram 認証情報](/ja-JP/help/testing#shared-telegram-credentials-via-convex-v1)にあります（このセクション名は Discord サポートより前のものです。ブローカーのセマンティクスは両方の kind で同一です）。 +運用用 env vars と Convex ブローカーエンドポイント契約は、[Testing → Convex 経由の共有 Telegram 認証情報](/ja-JP/help/testing#shared-telegram-credentials-via-convex-v1)にあります（セクション名は Discord 対応前のものですが、ブローカーのセマンティクスは両方の種類で同一です）。 -## リポジトリベースのシード +## リポジトリ backed seeds -シードアセットは `qa/` にあります: +シードアセットは `qa/` にあります。 - `qa/scenarios/index.md` - `qa/scenarios//*.md` -これらは意図的に git に置かれているため、QA 計画は人間と -エージェントの両方から見えます。 +これらは意図的に git に入れてあり、QA プランが人間とエージェントの両方に見えるようにしています。 -`qa-lab` は汎用の Markdown ランナーのままにする必要があります。各シナリオ Markdown ファイルは -1 回のテスト実行の信頼できる情報源であり、次を定義する必要があります: +`qa-lab` は汎用 Markdown ランナーのままにするべきです。各シナリオ Markdown ファイルは、1 つのテスト実行の信頼できる情報源であり、次を定義するべきです。 - シナリオメタデータ -- 任意のカテゴリ、機能、レーン、リスクメタデータ +- 任意の category、capability、lane、risk メタデータ - docs と code refs - 任意の Plugin 要件 -- 任意の Gateway 設定パッチ +- 任意の Gateway config patch - 実行可能な `qa-flow` -`qa-flow` を支える再利用可能なランタイムサーフェスは、汎用的で -横断的なままにできます。たとえば、Markdown シナリオはトランスポート側 -ヘルパーとブラウザー側ヘルパーを組み合わせ、専用ランナーを追加せずに -Gateway の `browser.request` シーム経由で埋め込み Control UI を操作できます。 +`qa-flow` を支える再利用可能なランタイム surface は、汎用かつ横断的なままで構いません。たとえば Markdown シナリオは、特別なケースのランナーを追加せずに、Gateway `browser.request` seam 経由で埋め込み Control UI を操作するブラウザー側ヘルパーと、transport 側ヘルパーを組み合わせることができます。 -シナリオファイルは、ソースツリーフォルダーではなく製品機能ごとに -グループ化する必要があります。ファイルを移動してもシナリオ ID は安定させ、実装の追跡可能性には -`docsRefs` と `codeRefs` を使用してください。 +シナリオファイルは、ソースツリーフォルダーではなく、プロダクト capability ごとにグループ化するべきです。ファイルを移動してもシナリオ ID は安定させてください。実装の traceability には `docsRefs` と `codeRefs` を使います。 -ベースラインリストは、次をカバーできる程度に広く保つ必要があります: +ベースラインリストは、次をカバーするのに十分な広さを保つべきです。 - DM とチャンネルチャット - スレッド動作 - メッセージアクションのライフサイクル -- Cron コールバック -- メモリリコール +- cron コールバック +- メモリ recall - モデル切り替え -- サブエージェントの引き継ぎ +- サブエージェント handoff - リポジトリ読み取りと docs 読み取り - Lobster Invaders のような小さなビルドタスク 1 つ -## プロバイダーモックレーン +## Provider mock レーン -`qa suite` には 2 つのローカルプロバイダーモックレーンがあります: +`qa suite` には 2 つのローカル provider mock レーンがあります。 -- `mock-openai` はシナリオ対応の OpenClaw モックです。これは、リポジトリベースの QA とパリティゲートの既定の - 決定論的モックレーンのままです。 -- `aimock` は、実験的なプロトコル、 - fixture、record/replay、chaos カバレッジのために AIMock ベースのプロバイダーサーバーを起動します。これは追加的なものであり、 - `mock-openai` シナリオディスパッチャーを置き換えるものではありません。 +- `mock-openai` は、シナリオを認識する OpenClaw mock です。リポジトリ backed QA と parity gate のデフォルト決定的 mock レーンのままです。 +- `aimock` は、実験的なプロトコル、fixture、record/replay、chaos coverage のために AIMock backed provider server を起動します。これは追加的なものであり、`mock-openai` シナリオ dispatcher を置き換えるものではありません。 -プロバイダーレーンの実装は `extensions/qa-lab/src/providers/` 配下にあります。 -各プロバイダーは、自身の既定値、ローカルサーバー起動、Gateway モデル設定、 -auth-profile ステージング要件、およびライブ/モック機能フラグを所有します。共有スイートと -Gateway コードは、プロバイダー名で分岐するのではなく、プロバイダーレジストリ経由でルーティングする必要があります。 +provider レーンの実装は `extensions/qa-lab/src/providers/` 配下にあります。各 provider は、自身のデフォルト、ローカルサーバー起動、Gateway モデル config、auth-profile staging needs、live/mock capability flags を所有します。共有 suite と Gateway コードは、provider 名で分岐するのではなく provider registry 経由でルーティングするべきです。 -## トランスポートアダプター +## Transport アダプター -`qa-lab` は、Markdown QA シナリオ用の汎用トランスポートシームを所有します。`qa-channel` はそのシーム上の最初のアダプターですが、設計上の対象はより広範です。将来の実チャンネルまたは合成チャンネルは、トランスポート固有の QA ランナーを追加するのではなく、同じスイートランナーに接続する必要があります。 +`qa-lab` は Markdown QA シナリオ向けの汎用 transport seam を所有します。`qa-channel` はその seam 上の最初のアダプターですが、設計対象はさらに広いものです。将来の実在または合成チャンネルは、transport 固有の QA ランナーを追加するのではなく、同じ suite runner に接続するべきです。 -アーキテクチャレベルでは、分割は次のとおりです: +アーキテクチャレベルでの分割は次のとおりです。 -- `qa-lab` は、汎用シナリオ実行、ワーカー並行性、成果物書き込み、レポートを所有します。 -- トランスポートアダプターは、Gateway 設定、準備完了状態、受信および送信の観測、トランスポートアクション、正規化されたトランスポート状態を所有します。 -- `qa/scenarios/` 配下の Markdown シナリオファイルがテスト実行を定義し、`qa-lab` はそれらを実行する再利用可能なランタイムサーフェスを提供します。 +- `qa-lab` は、汎用シナリオ実行、ワーカー concurrency、アーティファクト書き込み、レポートを所有します。 +- transport アダプターは、Gateway config、readiness、inbound と outbound の observation、transport actions、正規化された transport state を所有します。 +- `qa/scenarios/` 配下の Markdown シナリオファイルがテスト実行を定義し、`qa-lab` がそれらを実行する再利用可能なランタイム surface を提供します。 -### チャンネルの追加 +### チャンネルを追加する -Markdown QA システムにチャンネルを追加するには、正確に 2 つのものが必要です: +Markdown QA システムにチャンネルを追加するには、正確に 2 つのものが必要です。 -1. そのチャンネル用のトランスポートアダプター。 -2. チャンネル契約を実行するシナリオパック。 +1. そのチャンネルの transport アダプター。 +2. そのチャンネル契約を exercise するシナリオパック。 -共有 `qa-lab` ホストがフローを所有できる場合、新しいトップレベル QA コマンドルートを追加しないでください。 +共有 `qa-lab` ホストがフローを所有できる場合は、新しいトップレベル QA コマンド root を追加しないでください。 -`qa-lab` は共有ホストの仕組みを所有します。 +`qa-lab` は共有ホスト mechanics を所有します。 -- `openclaw qa` コマンドルート -- スイートの起動と終了処理 -- ワーカーの並行実行 -- アーティファクトの書き込み +- `openclaw qa` コマンド root +- suite startup と teardown +- ワーカー concurrency +- アーティファクト書き込み - レポート生成 - シナリオ実行 -- 古い `qa-channel` シナリオ向けの互換エイリアス +- 古い `qa-channel` シナリオ向けの compatibility aliases -ランナー Plugin はトランスポート契約を所有します。 +Runner plugins は transport contract を所有します。 -- 共有 `qa` ルートの下に `openclaw qa ` をマウントする方法 -- そのトランスポート向けに Gateway を構成する方法 -- 準備完了を確認する方法 -- インバウンドイベントを注入する方法 -- アウトバウンドメッセージを観測する方法 -- トランスクリプトと正規化されたトランスポート状態を公開する方法 -- トランスポートに裏付けられたアクションを実行する方法 -- トランスポート固有のリセットまたはクリーンアップを処理する方法 +- 共有 `qa` root の下に `openclaw qa ` をどう mount するか +- その transport 向けに Gateway をどう設定するか +- readiness をどう確認するか +- inbound events をどう inject するか +- outbound messages をどう observe するか +- transcripts と正規化された transport state をどう公開するか +- transport backed actions をどう実行するか +- transport 固有の reset や cleanup をどう扱うか -新しいチャネルの最小採用基準: +新しいチャンネルの最小採用基準: -1. 共有 `qa` ルートの所有者は `qa-lab` のままにします。 -2. 共有 `qa-lab` ホストシーム上にトランスポートランナーを実装します。 -3. トランスポート固有の仕組みはランナー Plugin またはチャネルハーネス内に保持します。 -4. 競合するルートコマンドを登録するのではなく、ランナーを `openclaw qa ` としてマウントします。ランナー Plugin は `openclaw.plugin.json` で `qaRunners` を宣言し、`runtime-api.ts` から一致する `qaRunnerCliRegistrations` 配列をエクスポートする必要があります。`runtime-api.ts` は軽量に保ち、遅延 CLI とランナー実行は別のエントリポイントの背後に置きます。 -5. テーマ別の `qa/scenarios/` ディレクトリ配下で Markdown シナリオを作成または適用します。 -6. 新しいシナリオには汎用シナリオヘルパーを使用します。 -7. リポジトリが意図的な移行を行っているのでない限り、既存の互換エイリアスを機能させ続けます。 +1. 共有 `qa` root の所有者として `qa-lab` を維持する。 +2. 共有 `qa-lab` ホスト seam 上に transport runner を実装する。 +3. transport 固有の mechanics は runner plugin または channel harness 内に保つ。 +4. 競合する root command を登録するのではなく、runner を `openclaw qa ` として mount する。Runner plugins は `openclaw.plugin.json` で `qaRunners` を宣言し、`runtime-api.ts` から対応する `qaRunnerCliRegistrations` 配列を export するべきです。`runtime-api.ts` は軽く保ち、lazy CLI と runner execution は別 entrypoint の背後に置くべきです。 +5. テーマ別の `qa/scenarios/` ディレクトリ配下で Markdown シナリオを作成または適応する。 +6. 新しいシナリオには汎用シナリオヘルパーを使う。 +7. リポジトリが意図的な移行を行っている場合を除き、既存の compatibility aliases を動作させ続ける。 判断ルールは厳格です。 -- 振る舞いを `qa-lab` で一度だけ表現できるなら、`qa-lab` に置きます。 -- 振る舞いが 1 つのチャネルトランスポートに依存するなら、そのランナー Plugin または Plugin ハーネス内に保持します。 -- 複数のチャネルで使える新しい機能がシナリオに必要なら、`suite.ts` にチャネル固有の分岐を追加するのではなく、汎用ヘルパーを追加します。 -- ある振る舞いが 1 つのトランスポートでしか意味を持たないなら、シナリオをトランスポート固有のままにし、それをシナリオ契約で明示します。 +- 動作を `qa-lab` で一度だけ表現できる場合は、`qa-lab` に置きます。 +- 動作が 1 つのチャンネル transport に依存する場合は、その runner plugin または plugin harness に保ちます。 +- あるシナリオが複数のチャンネルで使える新しい capability を必要とする場合は、`suite.ts` にチャンネル固有の分岐を追加するのではなく、汎用ヘルパーを追加します。 +- ある動作が 1 つの transport にのみ意味を持つ場合は、そのシナリオを transport 固有に保ち、シナリオ契約内でそれを明示します。 ### シナリオヘルパー名 @@ -461,21 +616,21 @@ Markdown QA システムにチャンネルを追加するには、正確に 2 - `formatTransportTranscript` - `resetTransport` -既存のシナリオでは互換エイリアス（`waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus`）も引き続き利用できますが、新しいシナリオの作成では汎用名を使う必要があります。これらのエイリアスは、一斉移行を避けるために存在するものであり、今後のモデルではありません。 +既存シナリオ向けには compatibility aliases も引き続き利用できます — `waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus` — ただし、新しいシナリオ作成では汎用名を使うべきです。これらの alias は flag-day migration を避けるためのものであり、今後のモデルではありません。 ## レポート -`qa-lab` は、観測されたバスのタイムラインから Markdown プロトコルレポートをエクスポートします。 -レポートは次の問いに答える必要があります。 +`qa-lab` は、観測された bus timeline から Markdown プロトコルレポートを export します。 +レポートは次に答えるべきです。 -- 何が機能したか +- 何が動作したか - 何が失敗したか - 何がブロックされたままだったか -- どのフォローアップシナリオを追加する価値があるか +- 追加する価値のある follow-up シナリオは何か -利用可能なシナリオの一覧（フォローアップ作業の規模見積もりや新しいトランスポートの配線に役立ちます）を確認するには、`pnpm openclaw qa coverage` を実行します（機械可読出力には `--json` を追加します）。 +利用可能なシナリオの inventory については、follow-up 作業の見積もりや新しい transport の wiring に役立つため、`pnpm openclaw qa coverage` を実行します（machine-readable output には `--json` を追加します）。 -文字とスタイルのチェックでは、同じシナリオを複数のライブモデル refs で実行し、判定済みの Markdown レポートを書き込みます。 +character と style checks では、同じシナリオを複数の live model refs で実行し、judge された Markdown レポートを書き込みます。 ```bash pnpm openclaw qa character-eval \ @@ -494,16 +649,23 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -このコマンドは Docker ではなく、ローカル QA Gateway の子プロセスを実行します。キャラクター評価シナリオでは `SOUL.md` を通じてペルソナを設定し、その後チャット、ワークスペース支援、小さなファイルタスクなどの通常のユーザーターンを実行する必要があります。候補モデルには、評価されていることを伝えるべきではありません。このコマンドは各完全トランスクリプトを保持し、基本的な実行統計を記録したうえで、対応している場合は `xhigh` 推論を使った高速モードで判定モデルに依頼し、自然さ、雰囲気、ユーモアで実行結果をランク付けします。プロバイダーを比較するときは `--blind-judge-models` を使用します。判定プロンプトには引き続きすべてのトランスクリプトと実行ステータスが渡されますが、候補 refs は `candidate-01` のような中立ラベルに置き換えられます。レポートは解析後にランキングを実際の refs に対応付けます。 -候補実行はデフォルトで `high` の思考レベルを使い、GPT-5.5 では `medium`、それをサポートする古い OpenAI 評価 refs では `xhigh` を使います。特定の候補を上書きするには `--model provider/model,thinking=` をインラインで指定します。`--thinking ` は引き続きグローバルフォールバックを設定し、古い `--model-thinking ` 形式は互換性のために維持されています。 -OpenAI 候補 refs はデフォルトで高速モードになり、プロバイダーが対応している場合は優先処理が使用されます。単一の候補または判定モデルで上書きが必要な場合は、`,fast`、`,no-fast`、または `,fast=false` をインラインで追加します。すべての候補モデルで高速モードを強制的にオンにしたい場合にのみ、`--fast` を渡します。候補と判定の所要時間はベンチマーク分析のためにレポートへ記録されますが、判定プロンプトでは速度でランク付けしないよう明示されています。 -候補モデルと判定モデルの実行はいずれもデフォルトで並行数 16 です。プロバイダーの制限やローカル Gateway の負荷により実行がノイズの多いものになる場合は、`--concurrency` または `--judge-concurrency` を下げてください。 -候補 `--model` が渡されない場合、キャラクター評価はデフォルトで `openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、`moonshot/kimi-k2.5`、および `google/gemini-3.1-pro-preview` になります。 -`--judge-model` が渡されない場合、判定モデルはデフォルトで `openai/gpt-5.5,thinking=xhigh,fast` と `anthropic/claude-opus-4-6,thinking=high` になります。 +このコマンドは Docker ではなく、ローカル QA Gateway 子プロセスを実行します。キャラクター評価シナリオでは、`SOUL.md` を通じてペルソナを設定してから、チャット、ワークスペース支援、小さなファイルタスクなどの通常のユーザーターンを実行する必要があります。候補モデルには、評価されていることを伝えないでください。このコマンドは各完全トランスクリプトを保持し、基本的な実行統計を記録してから、サポートされている場合は `xhigh` 推論を使った高速モードで判定モデルに実行を自然さ、雰囲気、ユーモアでランク付けするよう依頼します。 +プロバイダーを比較する場合は `--blind-judge-models` を使用します。判定プロンプトには引き続きすべてのトランスクリプトと実行ステータスが渡されますが、候補参照は `candidate-01` などの中立ラベルに置き換えられます。レポートは解析後にランキングを実際の参照へ対応付けます。 +候補実行のデフォルトは `high` 思考で、GPT-5.5 では `medium`、それをサポートする古い OpenAI 評価参照では `xhigh` です。特定の候補をインラインで上書きするには `--model provider/model,thinking=` を使用します。`--thinking ` は引き続きグローバルなフォールバックを設定し、古い `--model-thinking ` 形式は互換性のために保持されています。 +OpenAI 候補参照のデフォルトは高速モードで、プロバイダーがサポートする場合は優先処理が使用されます。単一の候補または判定に上書きが必要な場合は、インラインで `,fast`、`,no-fast`、または `,fast=false` を追加します。すべての候補モデルで高速モードを強制的に有効にしたい場合にのみ `--fast` を渡します。候補と判定の所要時間はベンチマーク分析のためにレポートに記録されますが、判定プロンプトでは速度でランク付けしないよう明示されています。 +候補モデル実行と判定モデル実行の同時実行数はいずれもデフォルトで 16 です。プロバイダー制限やローカル Gateway の負荷によって実行のノイズが大きすぎる場合は、`--concurrency` または `--judge-concurrency` を下げてください。 +候補の `--model` が渡されていない場合、キャラクター評価のデフォルトは +`openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、 +`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、 +`moonshot/kimi-k2.5`、および +`google/gemini-3.1-pro-preview` です。 +`--judge-model` が渡されていない場合、判定モデルのデフォルトは +`openai/gpt-5.5,thinking=xhigh,fast` と +`anthropic/claude-opus-4-6,thinking=high` です。 ## 関連ドキュメント -- [Matrix QA](/ja-JP/concepts/qa-matrix) -- [QA Channel](/ja-JP/channels/qa-channel) +- [マトリックス QA](/ja-JP/concepts/qa-matrix) +- [QA チャンネル](/ja-JP/channels/qa-channel) - [テスト](/ja-JP/help/testing) - [ダッシュボード](/ja-JP/web/dashboard) diff --git a/docs/ja-JP/gateway/config-tools.md b/docs/ja-JP/gateway/config-tools.md index 9e0984879..8e7b66e08 100644 --- a/docs/ja-JP/gateway/config-tools.md +++ b/docs/ja-JP/gateway/config-tools.md @@ -2,15 +2,15 @@ read_when: - '`tools.*` ポリシー、許可リスト、または実験的機能の設定' - カスタムプロバイダーの登録またはベース URL の上書き - - OpenAI 互換のセルフホスト型エンドポイントの設定 + - OpenAI 互換のセルフホストエンドポイントのセットアップ sidebarTitle: Tools and custom providers -summary: ツール設定（ポリシー、実験的な切り替え、プロバイダー支援ツール）とカスタムプロバイダー/base-URL 設定 +summary: ツール設定（ポリシー、実験的トグル、プロバイダー支援ツール）とカスタムプロバイダー/base-URL のセットアップ title: 設定 — ツールとカスタムプロバイダー x-i18n: - generated_at: "2026-05-03T21:31:52Z" + generated_at: "2026-05-05T01:45:49Z" model: gpt-5.5 provider: openai - source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da + source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883 source_path: gateway/config-tools.md workflow: 16 --- @@ -21,24 +21,24 @@ x-i18n: ### ツールプロファイル -`tools.profile` は `tools.allow`/`tools.deny` の前にベースの許可リストを設定します。 +`tools.profile` は、`tools.allow`/`tools.deny` の前にベースの許可リストを設定します。 -ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトが `tools.profile: "coding"` になります（既存の明示的なプロファイルは保持されます）。 +ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトを `tools.profile: "coding"` にします（既存の明示的なプロファイルは保持されます）。 -| プロファイル | 含まれるもの | +| プロファイル | 含まれるもの | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `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` | すべての組み込みツール（プロバイダープラグインを除く） | +| `group:openclaw` | すべての組み込みツール（プロバイダー Plugin は除く） | ### `tools.allow` / `tools.deny` -グローバルなツール許可 / 拒否ポリシー（拒否が優先）。大文字と小文字を区別せず、`*` ワイルドカードをサポートします。Docker サンドボックスがオフの場合でも適用されます。 +グローバルなツールの許可/拒否ポリシー（拒否が優先）。大文字小文字を区別せず、`*` ワイルドカードに対応します。Docker サンドボックスがオフの場合でも適用されます。 ```json5 { @@ -61,7 +61,7 @@ x-i18n: } ``` -`write` と `apply_patch` は別々のツール ID です。`allow: ["write"]` は互換性のあるモデルで `apply_patch` も有効にしますが、`deny: ["write"]` は `apply_patch` を拒否しません。すべてのファイル変更をブロックするには、`group:fs` を拒否するか、変更を行う各ツールを明示的に列挙します。 +`write` と `apply_patch` は別々のツール ID です。`allow: ["write"]` は互換性のあるモデルで `apply_patch` も有効にしますが、`deny: ["write"]` は `apply_patch` を拒否しません。すべてのファイル変更をブロックするには、`group:fs` を拒否するか、変更を行う各ツールを明示的に列挙してください。 ```json5 { @@ -71,7 +71,7 @@ x-i18n: ### `tools.byProvider` -特定のプロバイダーまたはモデルのツールをさらに制限します。順序: ベースプロファイル → プロバイダープロファイル → 許可 / 拒否。 +特定のプロバイダーまたはモデルに対してツールをさらに制限します。順序: ベースプロファイル → プロバイダープロファイル → 許可/拒否。 ```json5 { @@ -87,7 +87,7 @@ x-i18n: ### `tools.elevated` -サンドボックス外での昇格された exec アクセスを制御します。 +サンドボックス外の elevated exec アクセスを制御します。 ```json5 { @@ -104,8 +104,8 @@ x-i18n: ``` - エージェントごとのオーバーライド（`agents.list[].tools.elevated`）は、さらに制限することしかできません。 -- `/elevated on|off|ask|full` はセッションごとに状態を保存します。インラインディレクティブは単一のメッセージに適用されます。 -- 昇格された `exec` はサンドボックス化をバイパスし、設定されたエスケープパス（デフォルトは `gateway`、exec ターゲットが `node` の場合は `node`）を使用します。 +- `/elevated on|off|ask|full` はセッションごとに状態を保存します。インラインディレクティブは単一メッセージに適用されます。 +- elevated `exec` はサンドボックスをバイパスし、設定されたエスケープパスを使用します（デフォルトは `gateway`、または exec ターゲットが `node` の場合は `node`）。 ### `tools.exec` @@ -129,7 +129,7 @@ x-i18n: ### `tools.loopDetection` -ツールループの安全性チェックは**デフォルトで無効**です。検出を有効化するには `enabled: true` を設定します。設定は `tools.loopDetection` でグローバルに定義でき、`agents.list[].tools.loopDetection` でエージェントごとにオーバーライドできます。 +ツールループの安全性チェックは**デフォルトで無効**です。検出を有効にするには `enabled: true` を設定します。設定は `tools.loopDetection` でグローバルに定義でき、`agents.list[].tools.loopDetection` でエージェントごとにオーバーライドできます。 ```json5 { @@ -154,22 +154,22 @@ x-i18n: ループ分析のために保持されるツール呼び出し履歴の最大数。 - 警告の対象となる、進行のない繰り返しパターンのしきい値。 + 警告のための、進捗のない繰り返しパターンのしきい値。 重大なループをブロックするための、より高い繰り返ししきい値。 - 進行のない実行をハード停止するしきい値。 + 進捗のない実行に対する強制停止しきい値。 - 同じツール / 同じ引数の呼び出しが繰り返された場合に警告します。 + 同じツール/同じ引数の呼び出しが繰り返された場合に警告します。 - 既知のポーリングツール（`process.poll`、`command_status` など）で警告 / ブロックします。 + 既知のポーリングツール（`process.poll`、`command_status` など）で警告/ブロックします。 - 進行のないペアパターンが交互に繰り返される場合に警告 / ブロックします。 + 進捗のないペアが交互に繰り返されるパターンで警告/ブロックします。 @@ -216,7 +216,7 @@ x-i18n: media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async video directly to the channel + directSend: false, // deprecated: completions stay agent-mediated }, audio: { enabled: true, @@ -246,14 +246,14 @@ x-i18n: ``` - - **プロバイダー項目**（`type: "provider"` または省略）: + + **プロバイダーエントリ**（`type: "provider"` または省略）: - - `provider`: API プロバイダー id（`openai`、`anthropic`、`google`/`gemini`、`groq` など） - - `model`: モデル id の上書き - - `profile` / `preferredProfile`: `auth-profiles.json` のプロファイル選択 + - `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}}` に移行します） @@ -261,15 +261,15 @@ x-i18n: **共通フィールド:** - `capabilities`: 任意のリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → 画像、`google` → 画像+音声+動画、`groq` → 音声。 - - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: 項目ごとの上書き。 - - `tools.media.image.timeoutSeconds` と一致する画像モデルの `timeoutSeconds` 項目は、エージェントが明示的な `image` ツールを呼び出した場合にも適用されます。 - - 失敗した場合は次の項目にフォールバックします。 + - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリごとのオーバーライド。 + - `tools.media.image.timeoutSeconds` と対応する画像モデルの `timeoutSeconds` エントリは、エージェントが明示的な `image` ツールを呼び出す場合にも適用されます。 + - 失敗した場合は次のエントリにフォールバックします。 プロバイダー認証は標準の順序に従います: `auth-profiles.json` → 環境変数 → `models.providers.*.apiKey`。 **非同期完了フィールド:** - - `asyncCompletion.directSend`: `true` の場合、直接の完了配信をサポートする完了済みの非同期メディアタスクは、まず直接チャンネル配信を試みます。デフォルト: `false`（要求元セッションの wake/モデル配信パス）。現在、これは非同期 `video_generate` に適用されます。非同期 `music_generate` の完了は、これが有効な場合でも要求元セッション経由のままです。 + - `asyncCompletion.directSend`: 非推奨の互換性フラグ。完了した非同期メディアタスクはリクエスターセッション経由のままになり、エージェントが結果を受け取り、ユーザーへの伝え方を決定し、ソース配信で必要な場合はメッセージツールを使用します。 @@ -291,7 +291,7 @@ x-i18n: セッションツール（`sessions_list`、`sessions_history`、`sessions_send`）の対象にできるセッションを制御します。 -デフォルト: `tree`（現在のセッション + それによって生成されたセッション、サブエージェントなど）。 +デフォルト: `tree`（現在のセッション + サブエージェントなど、そのセッションから生成されたセッション）。 ```json5 { @@ -307,10 +307,10 @@ 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` になります。 @@ -336,11 +336,11 @@ x-i18n: ``` - - - 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACP runtime は添付ファイルを拒否します。 + + - 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACP ランタイムはそれらを拒否します。 - ファイルは子ワークスペース内の `.openclaw/attachments//` に `.manifest.json` とともに実体化されます。 - 添付ファイルの内容は、トランスクリプトの永続化から自動的に秘匿されます。 - - Base64 入力は、厳密なアルファベット/パディング検査と、デコード前のサイズガードで検証されます。 + - Base64 入力は、厳密なアルファベット/パディングチェックとデコード前のサイズガードで検証されます。 - ファイル権限は、ディレクトリが `0700`、ファイルが `0600` です。 - クリーンアップは `cleanup` ポリシーに従います。`delete` は常に添付ファイルを削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 @@ -363,9 +363,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` @@ -385,8 +385,8 @@ x-i18n: } ``` -- `model`: 生成されたサブエージェントのデフォルトモデルです。省略した場合、サブエージェントは呼び出し元のモデルを継承します。 -- `allowAgents`: リクエスト元エージェントが独自の `subagents.allowAgents` を設定していない場合の、`sessions_spawn` の対象エージェント ID のデフォルト許可リストです（`["*"]` = 任意、デフォルト: 同じエージェントのみ）。 +- `model`: 生成されるサブエージェントのデフォルトモデルです。省略した場合、サブエージェントは呼び出し元のモデルを継承します。 +- `allowAgents`: リクエスト元エージェントが独自の `subagents.allowAgents` を設定していない場合に、`sessions_spawn` の対象エージェント ID に使われるデフォルトの許可リストです（`["*"]` = 任意、デフォルト: 同じエージェントのみ）。 - `runTimeoutSeconds`: ツール呼び出しで `runTimeoutSeconds` が省略された場合の、`sessions_spawn` のデフォルトタイムアウト（秒）です。`0` はタイムアウトなしを意味します。 - サブエージェントごとのツールポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 @@ -394,7 +394,7 @@ x-i18n: ## カスタムプロバイダーとベース URL -OpenClaw は組み込みモデルカタログを使用します。設定内の `models.providers`、または `~/.openclaw/agents//agent/models.json` でカスタムプロバイダーを追加します。 +OpenClaw は組み込みのモデルカタログを使用します。カスタムプロバイダーは、設定内の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加します。 ```json5 { @@ -425,18 +425,18 @@ OpenClaw は組み込みモデルカタログを使用します。設定内の ` - - カスタム認証の必要がある場合は、`authHeader: true` + `headers` を使用します。 - - エージェント設定ルートは `OPENCLAW_AGENT_DIR`（またはレガシー環境変数エイリアスの `PI_CODING_AGENT_DIR`）で上書きします。 + - カスタム認証が必要な場合は、`authHeader: true` + `headers` を使用します。 + - エージェント設定ルートは `OPENCLAW_AGENT_DIR`（またはレガシー環境変数エイリアスの `PI_CODING_AGENT_DIR`）でオーバーライドします。 - 一致するプロバイダー ID のマージ優先順位: - - 空でないエージェント `models.json` の `baseUrl` 値が優先されます。 - - 空でないエージェント `apiKey` 値は、そのプロバイダーが現在の設定/認証プロファイルコンテキストで SecretRef 管理ではない場合にのみ優先されます。 - - SecretRef 管理のプロバイダー `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（env 参照の場合は `ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。 - - SecretRef 管理のプロバイダーヘッダー値は、ソースマーカー（env 参照の場合は `secretref-env:ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。 - - エージェント `apiKey`/`baseUrl` が空または欠落している場合は、設定内の `models.providers` にフォールバックします。 - - 一致するモデルの `contextWindow`/`maxTokens` は、明示的な設定値と暗黙のカタログ値のうち高い値を使用します。 - - 一致するモデルの `contextTokens` は、存在する場合は明示的なランタイム上限を保持します。ネイティブモデルメタデータを変更せずに有効なコンテキストを制限するために使用します。 + - 空でないエージェントの `models.json` の `baseUrl` 値が優先されます。 + - 空でないエージェントの `apiKey` 値は、そのプロバイダーが現在の設定/認証プロファイルコンテキストで SecretRef 管理されていない場合にのみ優先されます。 + - SecretRef 管理のプロバイダー `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（環境変数参照の場合は `ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。 + - SecretRef 管理のプロバイダーヘッダー値は、ソースマーカー（環境変数参照の場合は `secretref-env:ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。 + - 空または欠落したエージェントの `apiKey`/`baseUrl` は、設定内の `models.providers` にフォールバックします。 + - 一致するモデルの `contextWindow`/`maxTokens` は、明示的な設定値と暗黙のカタログ値のうち高い方を使用します。 + - 一致するモデルの `contextTokens` は、存在する場合は明示的なランタイム上限を保持します。ネイティブモデルメタデータを変更せずに有効コンテキストを制限するために使用します。 - 設定で `models.json` を完全に書き換えたい場合は、`models.mode: "replace"` を使用します。 - - マーカーの永続化はソースを正とします。マーカーは解決済みのランタイムシークレット値ではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。 + - マーカーの永続化はソースを正とします。マーカーは、解決済みランタイムシークレット値からではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。 @@ -445,63 +445,63 @@ 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` を渡さない限り破壊的な置換を拒否します。 + - `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` を渡さない限り破壊的な置換を拒否します。 - - `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.*.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.*.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.*.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.*.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` 環境変数を使用）、`"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` です。 + - `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` の場合、プロバイダー HTTP fetch ガード経由で、DNS がプライベート、CGNAT、または類似の範囲に解決されるときでも `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.refreshInterval`: 検出更新のポーリング間隔です。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出されたモデルに使うフォールバックのコンテキストウィンドウです。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出されたモデルに使うフォールバックの最大出力トークン数です。 + + - `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.refreshInterval`: ディスカバリー更新のポーリング間隔です。 + - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出されたモデル向けのフォールバックコンテキストウィンドウです。 + - `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` provider plugin は、`openclaw onboard --auth-choice cerebras-api-key` 経由でこれを設定できます。デフォルトを上書きする場合にのみ、明示的なプロバイダー設定を使用します。 + バンドルされている `cerebras` プロバイダー Plugin は、`openclaw onboard --auth-choice cerebras-api-key` 経由でこれを設定できます。明示的なプロバイダー設定は、デフォルトをオーバーライドする場合にのみ使用します。 ```json5 { @@ -535,10 +535,10 @@ OpenClaw は組み込みモデルカタログを使用します。設定内の ` } ``` - Cerebras には `cerebras/zai-glm-4.7` を使用し、Z.AI 直結には `zai/glm-4.7` を使用します。 + Cerebras には `cerebras/zai-glm-4.7` を使用し、Z.AI 直接には `zai/glm-4.7` を使用します。 - + ```json5 { env: { KIMI_API_KEY: "sk-..." }, @@ -551,13 +551,13 @@ OpenClaw は組み込みモデルカタログを使用します。設定内の ` } ``` - Anthropic互換の組み込みプロバイダーです。ショートカット: `openclaw onboard --auth-choice kimi-code-api-key`。 + Anthropic 互換の組み込みプロバイダーです。ショートカット: `openclaw onboard --auth-choice kimi-code-api-key`。 - - [Local Models](/ja-JP/gateway/local-models) を参照してください。要約: 本格的なハードウェア上で、LM Studio Responses API 経由で大規模ローカルモデルを実行し、フォールバック用にホスト型モデルもマージしたままにします。 + + [ローカルモデル](/ja-JP/gateway/local-models)を参照してください。要約: 本格的なハードウェア上で LM Studio Responses API 経由の大規模ローカルモデルを実行し、フォールバック用にホスト型モデルをマージしたままにします。 - + ```json5 { agents: { @@ -592,7 +592,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 の thinking を無効にします。`/fast on` または `params.fastMode: true` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。 @@ -631,7 +631,7 @@ OpenClaw は組み込みモデルカタログを使用します。設定内の ` 中国エンドポイントの場合: `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn`。 - ネイティブの Moonshot エンドポイントは、共有の `openai-completions` トランスポート上でストリーミング使用状況の互換性を通知します。OpenClaw は、組み込みプロバイダー ID だけではなく、エンドポイント機能に基づいてそれを判断します。 + ネイティブ Moonshot エンドポイントは、共有 `openai-completions` トランスポート上でのストリーミング使用量互換性を公開し、OpenClaw は組み込みプロバイダー ID だけでなくエンドポイント機能に基づいてそれを判定します。 @@ -646,10 +646,10 @@ OpenClaw は組み込みモデルカタログを使用します。設定内の ` } ``` - `OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`）を設定します。Zen カタログには `opencode/...` 参照を、Go カタログには `opencode-go/...` 参照を使用します。ショートカット: `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`。 - + ```json5 { env: { SYNTHETIC_API_KEY: "sk-..." }, @@ -683,10 +683,10 @@ OpenClaw は組み込みモデルカタログを使用します。設定内の ` } ``` - ベース URL では `/v1` を省略してください（Anthropic クライアントが追加します）。ショートカット: `openclaw onboard --auth-choice synthetic-api-key`。 + ベース URL では `/v1` を省略する必要があります (Anthropic クライアントが付加します)。ショートカット: `openclaw onboard --auth-choice synthetic-api-key`。 - + ```json5 { agents: { @@ -698,11 +698,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 のオーバーライドを持つカスタムプロバイダーを定義します。 + - コーディングエンドポイント (デフォルト): `https://api.z.ai/api/coding/paas/v4` + - 汎用エンドポイントの場合は、ベース URL の上書きを持つカスタムプロバイダーを定義します。 diff --git a/docs/ja-JP/gateway/configuration-reference.md b/docs/ja-JP/gateway/configuration-reference.md index 5de52dbe1..591930ebf 100644 --- a/docs/ja-JP/gateway/configuration-reference.md +++ b/docs/ja-JP/gateway/configuration-reference.md @@ -1,64 +1,64 @@ --- read_when: - - フィールド単位の設定の意味またはデフォルト値を正確に把握する必要がある場合 - - チャネル、モデル、Gateway、またはツールの設定ブロックを検証している場合 -summary: OpenClaw のコアキー、デフォルト値、および専用サブシステムリファレンスへのリンクに関する Gateway 設定リファレンス + - 正確なフィールド単位の設定セマンティクスまたはデフォルト値が必要な場合 + - チャネル、モデル、Gateway、またはツールの設定ブロックを検証しています +summary: OpenClaw のコアキー、デフォルト、および専用サブシステムリファレンスへのリンクに関する Gateway 設定リファレンス title: 設定リファレンス x-i18n: - generated_at: "2026-05-03T21:31:58Z" + generated_at: "2026-05-05T01:45:52Z" model: gpt-5.5 provider: openai - source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9 + source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684 source_path: gateway/configuration-reference.md workflow: 16 --- -コア設定リファレンス: `~/.openclaw/openclaw.json`。タスク指向の概要については、[設定](/ja-JP/gateway/configuration)を参照してください。 +OpenClaw の主要設定 `~/.openclaw/openclaw.json` のリファレンス。タスク指向の概要については、[設定](/ja-JP/gateway/configuration)を参照してください。 -OpenClaw の主要な設定サーフェスを扱い、サブシステムにより詳細な独自リファレンスがある場合はリンクします。チャンネルおよび Plugin 所有のコマンドカタログと、深いメモリ/QMD 調整項目は、このページではなく個別のページにあります。 +OpenClaw の主要な設定サーフェスを扱い、サブシステムに独自の詳細リファレンスがある場合はそこへリンクします。チャンネルおよび Plugin が所有するコマンドカタログや、メモリ/QMD の詳細なノブは、このページではなく個別ページにあります。 -コード上の真実: +コード上の正: -- `openclaw config schema` は、検証と Control UI に使われるライブ JSON Schema を出力します。利用可能な場合は、バンドル/Plugin/チャンネルのメタデータがマージされます -- `config.schema.lookup` は、ドリルダウンツール向けにパススコープのスキーマノードを1つ返します +- `openclaw config schema` は、検証と Control UI に使用される現在の JSON Schema を出力し、利用可能な場合はバンドル済み/Plugin/チャンネルのメタデータもマージします +- `config.schema.lookup` は、ドリルダウンツール用にパススコープのスキーマノードを 1 つ返します - `pnpm config:docs:check` / `pnpm config:docs:gen` は、現在のスキーマサーフェスに対して設定ドキュメントのベースラインハッシュを検証します -エージェントの参照パス: 編集前に、正確なフィールドレベルのドキュメントと制約を確認するには `gateway` ツールアクション `config.schema.lookup` を使用してください。タスク指向のガイダンスには [設定](/ja-JP/gateway/configuration) を、このページはより広いフィールドマップ、デフォルト、サブシステムリファレンスへのリンクに使用してください。 +エージェント検索パス: 編集前に、正確なフィールドレベルのドキュメントと制約を確認するには、`gateway` ツールアクション `config.schema.lookup` を使用します。タスク指向のガイダンスには[設定](/ja-JP/gateway/configuration)を使用し、より広いフィールドマップ、デフォルト、サブシステムリファレンスへのリンクにはこのページを使用します。 専用の詳細リファレンス: -- `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`、および `plugins.entries.memory-core.config.dreaming` 配下の dreaming 設定については [メモリ設定リファレンス](/ja-JP/reference/memory-config) -- 現在の組み込み + バンドル済みコマンドカタログについては [スラッシュコマンド](/ja-JP/tools/slash-commands) -- チャンネル固有のコマンドサーフェスについては、所有元のチャンネル/Plugin ページ +- `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`、および `plugins.entries.memory-core.config.dreaming` 配下の dreaming 設定については、[メモリ設定リファレンス](/ja-JP/reference/memory-config) +- 現在の組み込み + バンドル済みコマンドカタログについては、[スラッシュコマンド](/ja-JP/tools/slash-commands) +- チャンネル固有のコマンドサーフェスについては、所有するチャンネル/Plugin ページ -設定形式は **JSON5** です（コメント + 末尾カンマが許可されます）。すべてのフィールドは省略可能です — 省略時、OpenClaw は安全なデフォルトを使用します。 +設定形式は **JSON5** です（コメント + 末尾カンマが許可されます）。すべてのフィールドは任意です。省略された場合、OpenClaw は安全なデフォルトを使用します。 --- ## チャンネル -チャンネルごとの設定キーは専用ページに移動しました — Slack、Discord、Telegram、WhatsApp、Matrix、iMessage、その他のバンドルチャンネル（認証、アクセス制御、複数アカウント、メンション制御）を含む `channels.*` については [設定 — チャンネル](/ja-JP/gateway/config-channels) を参照してください。 +チャンネルごとの設定キーは専用ページへ移動しました。Slack、Discord、Telegram、WhatsApp、Matrix、iMessage、およびその他のバンドル済みチャンネル（認証、アクセス制御、マルチアカウント、メンションゲート）を含む `channels.*` については、[設定 — チャンネル](/ja-JP/gateway/config-channels)を参照してください。 ## エージェントデフォルト、マルチエージェント、セッション、メッセージ -専用ページに移動しました — 以下については [設定 — エージェント](/ja-JP/gateway/config-agents) を参照してください。 +専用ページへ移動しました。以下については、[設定 — エージェント](/ja-JP/gateway/config-agents)を参照してください。 -- `agents.defaults.*`（ワークスペース、モデル、thinking、Heartbeat、メモリ、メディア、Skills、サンドボックス） +- `agents.defaults.*`（ワークスペース、モデル、thinking、heartbeat、メモリ、メディア、Skills、サンドボックス） - `multiAgent.*`（マルチエージェントのルーティングとバインディング） -- `session.*`（セッションライフサイクル、Compaction、枝刈り） +- `session.*`（セッションライフサイクル、Compaction、プルーニング） - `messages.*`（メッセージ配信、TTS、Markdown レンダリング） - `talk.*`（Talk モード） - - `talk.speechLocale`: iOS/macOS 上の Talk 音声認識用の任意の BCP 47 ロケール ID - - `talk.silenceTimeoutMs`: 未設定の場合、Talk はトランスクリプトを送信する前にプラットフォーム既定の一時停止ウィンドウを保持します（`macOS と Android では 700 ms、iOS では 900 ms`） + - `talk.speechLocale`: iOS/macOS の Talk 音声認識用の任意の BCP 47 ロケール ID + - `talk.silenceTimeoutMs`: 未設定の場合、Talk はトランスクリプト送信前の一時停止ウィンドウにプラットフォーム既定値を維持します（`macOS と Android では 700 ms、iOS では 900 ms`） ## ツールとカスタムプロバイダー -ツールポリシー、実験的トグル、プロバイダーに基づくツール設定、カスタムプロバイダー / ベース URL 設定は専用ページに移動しました — [設定 — ツールとカスタムプロバイダー](/ja-JP/gateway/config-tools) を参照してください。 +ツールポリシー、実験的トグル、プロバイダー支援ツール設定、およびカスタムプロバイダー / ベース URL セットアップは専用ページへ移動しました。[設定 — ツールとカスタムプロバイダー](/ja-JP/gateway/config-tools)を参照してください。 ## モデル -プロバイダー定義、モデル許可リスト、カスタムプロバイダー設定は [設定 — ツールとカスタムプロバイダー](/ja-JP/gateway/config-tools#custom-providers-and-base-urls) にあります。 -`models` ルートはグローバルなモデルカタログ動作も所有します。 +プロバイダー定義、モデル許可リスト、カスタムプロバイダーセットアップは、[設定 — ツールとカスタムプロバイダー](/ja-JP/gateway/config-tools#custom-providers-and-base-urls)にあります。 +`models` ルートは、グローバルなモデルカタログ動作も所有します。 ```json5 { @@ -71,11 +71,11 @@ OpenClaw の主要な設定サーフェスを扱い、サブシステムによ - `models.mode`: プロバイダーカタログの動作（`merge` または `replace`）。 - `models.providers`: プロバイダー ID をキーとするカスタムプロバイダーマップ。 -- `models.pricing.enabled`: サイドカーとチャンネルが Gateway ready パスに到達した後に開始する、バックグラウンドの料金ブートストラップを制御します。`false` の場合、Gateway は OpenRouter と LiteLLM の料金カタログ取得をスキップします。設定済みの `models.providers.*.models[].cost` 値は、ローカルのコスト見積もりでは引き続き機能します。 +- `models.pricing.enabled`: サイドカーとチャンネルが Gateway ready パスに到達した後に開始されるバックグラウンド料金ブートストラップを制御します。`false` の場合、Gateway は OpenRouter と LiteLLM の料金カタログ取得をスキップします。設定済みの `models.providers.*.models[].cost` 値は、ローカルのコスト見積もりでは引き続き機能します。 ## MCP -OpenClaw 管理の MCP サーバー定義は `mcp.servers` 配下にあり、組み込み Pi やその他のランタイムアダプターで使用されます。`openclaw mcp list`、`show`、`set`、`unset` コマンドは、設定編集時にターゲットサーバーへ接続せずにこのブロックを管理します。 +OpenClaw 管理の MCP サーバー定義は `mcp.servers` 配下にあり、組み込み Pi およびその他のランタイムアダプターによって使用されます。`openclaw mcp list`、`show`、`set`、`unset` コマンドは、設定編集時に対象サーバーへ接続せずにこのブロックを管理します。 ```json5 { @@ -100,14 +100,13 @@ OpenClaw 管理の MCP サーバー定義は `mcp.servers` 配下にあり、組 ``` - `mcp.servers`: 設定済み MCP ツールを公開するランタイム向けの、名前付き stdio またはリモート MCP サーバー定義。 - リモートエントリは `transport: "streamable-http"` または `transport: "sse"` を使用します。 - `type: "http"` は CLI ネイティブのエイリアスで、`openclaw mcp set` と `openclaw doctor --fix` により正規の `transport` フィールドへ正規化されます。 + リモートエントリは `transport: "streamable-http"` または `transport: "sse"` を使用します。`type: "http"` は CLI ネイティブのエイリアスで、`openclaw mcp set` と `openclaw doctor --fix` が正規の `transport` フィールドへ正規化します。 - `mcp.sessionIdleTtlMs`: セッションスコープのバンドル済み MCP ランタイムのアイドル TTL。 - 単発の組み込み実行は実行終了時のクリーンアップを要求します。この TTL は、長時間存続するセッションと将来の呼び出し元のためのバックストップです。 -- `mcp.*` 配下の変更は、キャッシュ済みのセッション MCP ランタイムを破棄することでホット適用されます。 - 次のツール検出/使用時に、新しい設定からそれらが再作成されるため、削除された `mcp.servers` エントリはアイドル TTL を待たずに即座に回収されます。 + ワンショットの組み込み実行は実行終了時のクリーンアップを要求します。この TTL は長時間存続するセッションと将来の呼び出し元のためのバックストップです。 +- `mcp.*` 配下の変更は、キャッシュされたセッション MCP ランタイムを破棄することでホット適用されます。 + 次のツール探索/使用時に新しい設定から再作成されるため、削除された `mcp.servers` エントリはアイドル TTL を待たずに即座に回収されます。 -ランタイム動作については [MCP](/ja-JP/cli/mcp#openclaw-as-an-mcp-client-registry) と [CLI バックエンド](/ja-JP/gateway/cli-backends#bundle-mcp-overlays) を参照してください。 +ランタイム動作については、[MCP](/ja-JP/cli/mcp#openclaw-as-an-mcp-client-registry) と [CLI バックエンド](/ja-JP/gateway/cli-backends#bundle-mcp-overlays)を参照してください。 ## Skills @@ -134,22 +133,23 @@ OpenClaw 管理の MCP サーバー定義は `mcp.servers` 配下にあり、組 } ``` -- `allowBundled`: バンドル済み Skills のみを対象にした任意の許可リスト（管理/ワークスペース Skills には影響しません）。 +- `allowBundled`: バンドル済み Skills のみに対する任意の許可リスト（管理対象/ワークスペース Skills には影響しません）。 - `load.extraDirs`: 追加の共有 Skill ルート（最も低い優先度）。 - `install.preferBrew`: true の場合、`brew` が利用可能なら他のインストーラー種別へフォールバックする前に Homebrew インストーラーを優先します。 - `install.nodeManager`: `metadata.openclaw.install` 仕様の Node インストーラー設定（`npm` | `pnpm` | `yarn` | `bun`）。 - `entries..enabled: false` は、バンドル済み/インストール済みであっても Skill を無効化します。 -- `entries..apiKey`: プライマリ環境変数を宣言する Skills 向けの便利フィールド（平文文字列または SecretRef オブジェクト）。 +- `entries..apiKey`: プライマリ環境変数を宣言する Skills のための便宜項目（平文文字列または SecretRef オブジェクト）。 --- -## Plugins +## Plugin ```json5 { plugins: { enabled: true, allow: ["voice-call"], + bundledDiscovery: "allowlist", deny: [], load: { paths: ["~/Projects/oss/voice-call-plugin"], @@ -168,53 +168,54 @@ OpenClaw 管理の MCP サーバー定義は `mcp.servers` 配下にあり、組 ``` - `~/.openclaw/extensions`、`/.openclaw/extensions`、および `plugins.load.paths` から読み込まれます。 -- 検出では、ネイティブ OpenClaw Plugins に加えて、互換性のある Codex バンドルと Claude バンドル（manifest のない Claude 既定レイアウトのバンドルを含む）を受け入れます。 -- **設定変更には Gateway の再起動が必要です。** -- `allow`: 任意の許可リスト（列挙された Plugins のみ読み込み）。`deny` が優先されます。 -- `plugins.entries..apiKey`: Plugin レベルの API キー便利フィールド（Plugin が対応している場合）。 +- 探索は、ネイティブ OpenClaw Plugin に加えて、互換性のある Codex バンドルと Claude バンドル（マニフェストなしの Claude 既定レイアウトバンドルを含む）を受け入れます。 +- **設定変更には gateway の再起動が必要です。** +- `allow`: 任意の許可リスト（一覧にある Plugin のみ読み込まれます）。`deny` が優先します。 +- `bundledDiscovery`: 新規設定では既定で `"allowlist"` になるため、空でない `plugins.allow` は、web-search ランタイムプロバイダーを含むバンドル済みプロバイダー Plugin も制御します。Doctor は、既存のバンドル済みプロバイダー動作を明示的にオプトインするまで保持するために、移行されたレガシー許可リスト設定へ `"compat"` を書き込みます。 +- `plugins.entries..apiKey`: Plugin レベルの API キー便宜フィールド（Plugin がサポートする場合）。 - `plugins.entries..env`: Plugin スコープの環境変数マップ。 -- `plugins.entries..hooks.allowPromptInjection`: `false` の場合、コアは `before_prompt_build` をブロックし、レガシー `before_agent_start` からプロンプトを変更するフィールドを無視します。ただし、レガシーの `modelOverride` と `providerOverride` は保持します。ネイティブ Plugin フックと、対応するバンドル提供フックディレクトリに適用されます。 -- `plugins.entries..hooks.allowConversationAccess`: `true` の場合、信頼済みの非バンドル Plugins は、`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end` などの型付きフックから生の会話内容を読み取れます。 -- `plugins.entries..subagent.allowModelOverride`: この Plugin がバックグラウンド subagent 実行ごとに `provider` と `model` のオーバーライドを要求することを明示的に信頼します。 -- `plugins.entries..subagent.allowedModels`: 信頼済み subagent オーバーライド向けの、正規 `provider/model` ターゲットの任意の許可リスト。任意のモデルを許可することを意図している場合のみ `"*"` を使用してください。 +- `plugins.entries..hooks.allowPromptInjection`: `false` の場合、core は `before_prompt_build` をブロックし、レガシー `before_agent_start` からプロンプトを変更するフィールドを無視します。一方でレガシー `modelOverride` と `providerOverride` は保持します。ネイティブ Plugin hooks と、サポートされるバンドル提供 hook ディレクトリに適用されます。 +- `plugins.entries..hooks.allowConversationAccess`: `true` の場合、信頼された非バンドル Plugin は、`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end` などの型付き hooks から生の会話内容を読み取れます。 +- `plugins.entries..subagent.allowModelOverride`: この Plugin が、バックグラウンドサブエージェント実行ごとに `provider` と `model` のオーバーライドを要求することを明示的に信頼します。 +- `plugins.entries..subagent.allowedModels`: 信頼されたサブエージェントオーバーライドのための、正規 `provider/model` ターゲットの任意の許可リスト。任意のモデルを許可する意図がある場合にのみ `"*"` を使用してください。 - `plugins.entries..config`: Plugin 定義の設定オブジェクト（利用可能な場合はネイティブ OpenClaw Plugin スキーマで検証されます）。 -- チャンネル Plugin のアカウント/ランタイム設定は `channels.` 配下にあり、中央の OpenClaw オプションレジストリではなく、所有元 Plugin の manifest `channelConfigs` メタデータで説明されるべきです。 +- チャンネル Plugin のアカウント/ランタイム設定は `channels.` 配下にあり、中央の OpenClaw オプションレジストリではなく、所有する Plugin のマニフェスト `channelConfigs` メタデータで記述されるべきです。 - `plugins.entries.firecrawl.config.webFetch`: Firecrawl web-fetch プロバイダー設定。 - `apiKey`: Firecrawl API キー（SecretRef を受け入れます）。`plugins.entries.firecrawl.config.webSearch.apiKey`、レガシー `tools.web.fetch.firecrawl.apiKey`、または `FIRECRAWL_API_KEY` 環境変数へフォールバックします。 - - `baseUrl`: Firecrawl API ベース URL（デフォルト: `https://api.firecrawl.dev`。セルフホストのオーバーライドはプライベート/内部エンドポイントを対象にする必要があります）。 - - `onlyMainContent`: ページからメインコンテンツのみを抽出します（デフォルト: `true`）。 - - `maxAgeMs`: 最大キャッシュ期間（ミリ秒）（デフォルト: `172800000` / 2 日）。 - - `timeoutSeconds`: スクレイプ要求のタイムアウト（秒）（デフォルト: `60`）。 + - `baseUrl`: Firecrawl API ベース URL（既定: `https://api.firecrawl.dev`。セルフホストのオーバーライドはプライベート/内部エンドポイントを対象にする必要があります）。 + - `onlyMainContent`: ページから主要コンテンツのみを抽出します（既定: `true`）。 + - `maxAgeMs`: 最大キャッシュ期間（ミリ秒）（既定: `172800000` / 2 日）。 + - `timeoutSeconds`: スクレイプリクエストのタイムアウト（秒）（既定: `60`）。 - `plugins.entries.xai.config.xSearch`: xAI X Search（Grok web search）設定。 - `enabled`: X Search プロバイダーを有効化します。 - `model`: 検索に使用する Grok モデル（例: `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`: メモリ Dreaming 設定。フェーズとしきい値については [Dreaming](/ja-JP/concepts/dreaming) を参照してください。 - - `enabled`: Dreaming のマスタースイッチ（デフォルト `false`）。 - - `frequency`: 各フル Dreaming スイープの cron 周期（既定では `"0 3 * * *"`）。 - - `model`: 任意の Dream Diary subagent モデルオーバーライド。`plugins.entries.memory-core.subagent.allowModelOverride: true` が必要です。ターゲットを制限するには `allowedModels` と組み合わせます。モデル利用不可エラーはセッション既定モデルで1回再試行します。信頼または許可リストの失敗は静かにフォールバックしません。 +- `plugins.entries.memory-core.config.dreaming`: メモリ dreaming 設定。フェーズとしきい値については [Dreaming](/ja-JP/concepts/dreaming) を参照してください。 + - `enabled`: dreaming のマスタースイッチ（既定 `false`）。 + - `frequency`: 各フル dreaming sweep の Cron 間隔（既定では `"0 3 * * *"`）。 + - `model`: 任意の Dream Diary サブエージェントモデルオーバーライド。`plugins.entries.memory-core.subagent.allowModelOverride: true` が必要です。ターゲットを制限するには `allowedModels` と組み合わせます。モデル利用不可エラーはセッション既定モデルで 1 回再試行されます。信頼または許可リストの失敗は暗黙にフォールバックしません。 - フェーズポリシーとしきい値は実装詳細です（ユーザー向け設定キーではありません）。 -- 完全なメモリ設定は [メモリ設定リファレンス](/ja-JP/reference/memory-config) にあります。 +- 完全なメモリ設定は[メモリ設定リファレンス](/ja-JP/reference/memory-config)にあります。 - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 有効化された Claude バンドル Plugins は、`settings.json` から組み込み Pi デフォルトも提供できます。OpenClaw はそれらを、生の OpenClaw 設定パッチではなく、サニタイズ済みのエージェント設定として適用します。 -- `plugins.slots.memory`: アクティブなメモリ Plugin ID を選択するか、メモリ Plugins を無効化するには `"none"` を指定します。 -- `plugins.slots.contextEngine`: アクティブなコンテキストエンジン Plugin ID を選択します。別のエンジンをインストールして選択しない限り、デフォルトは `"legacy"` です。 +- 有効化された Claude バンドル Plugin は、`settings.json` から組み込み Pi デフォルトを提供することもできます。OpenClaw はそれらを生の OpenClaw 設定パッチとしてではなく、サニタイズ済みのエージェント設定として適用します。 +- `plugins.slots.memory`: アクティブなメモリ Plugin ID、またはメモリ Plugin を無効化する `"none"` を選択します。 +- `plugins.slots.contextEngine`: アクティブなコンテキストエンジン Plugin ID を選択します。別のエンジンをインストールして選択しない限り、既定は `"legacy"` です。 -[Plugins](/ja-JP/tools/plugin) を参照してください。 +[Plugin](/ja-JP/tools/plugin)を参照してください。 --- ## コミットメント -`commitments` は推測されたフォローアップメモリを制御します。OpenClaw は会話ターンからチェックインを検出し、Heartbeat 実行を通じて配信できます。 +`commitments` は推論されたフォローアップメモリを制御します。OpenClaw は会話ターンからチェックインを検出し、heartbeat 実行を通じてそれらを配信できます。 -- `commitments.enabled`: 推測されたフォローアップコミットメントの隠し LLM 抽出、保存、Heartbeat 配信を有効化します。デフォルト: `false`。 -- `commitments.maxPerDay`: ローリング日単位で、エージェントセッションごとに配信される推測フォローアップコミットメントの最大数。デフォルト: `3`。 +- `commitments.enabled`: 推論されたフォローアップコミットメントのための隠し LLM 抽出、保存、heartbeat 配信を有効化します。既定: `false`。 +- `commitments.maxPerDay`: ローリング日単位で、エージェントセッションごとに配信される推論済みフォローアップコミットメントの最大数。既定: `3`。 -[推測されたコミットメント](/ja-JP/concepts/commitments) を参照してください。 +[推論されたコミットメント](/ja-JP/concepts/commitments)を参照してください。 --- @@ -265,26 +266,26 @@ OpenClaw 管理の MCP サーバー定義は `mcp.servers` 配下にあり、組 ``` - `evaluateEnabled: false` は `act:evaluate` と `wait --fn` を無効にします。 -- `tabCleanup` は、アイドル時間の経過後、またはセッションが上限を超えたときに、追跡対象のプライマリエージェントタブを回収します。個別のクリーンアップモードを無効にするには、`idleMinutes: 0` または `maxTabsPerSession: 0` を設定します。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定の場合は無効なので、ブラウザーナビゲーションは既定で厳格なままです。 -- プライベートネットワークのブラウザーナビゲーションを意図的に信頼する場合にのみ、`ssrfPolicy.dangerouslyAllowPrivateNetwork: true` を設定します。 -- 厳格モードでは、リモート CDP プロファイルエンドポイント（`profiles.*.cdpUrl`）は、到達性/検出チェック中に同じプライベートネットワークブロックの対象になります。 +- `tabCleanup` は、アイドル時間後またはセッションが上限を超えたときに、追跡中のプライマリエージェントのタブを回収します。個別のクリーンアップモードを無効にするには、`idleMinutes: 0` または `maxTabsPerSession: 0` を設定します。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定時には無効になるため、ブラウザーナビゲーションはデフォルトで厳格なままです。 +- プライベートネットワークのブラウザーナビゲーションを意図的に信頼する場合にのみ、`ssrfPolicy.dangerouslyAllowPrivateNetwork: true` を設定してください。 +- 厳格モードでは、リモート CDP プロファイルエンドポイント (`profiles.*.cdpUrl`) は、到達性/検出チェック中に同じプライベートネットワークブロックの対象になります。 - `ssrfPolicy.allowPrivateNetwork` はレガシーエイリアスとして引き続きサポートされます。 -- 厳格モードでは、明示的な例外に `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使用します。 -- リモートプロファイルはアタッチ専用です（開始/停止/リセットは無効）。 -- `profiles.*.cdpUrl` は `http://`、`https://`、`ws://`、`wss://` を受け付けます。OpenClaw に `/json/version` を検出させたい場合は HTTP(S) を使用し、プロバイダーが直接の DevTools WebSocket URL を提供する場合は WS(S) を使用します。 -- `remoteCdpTimeoutMs` と `remoteCdpHandshakeTimeoutMs` は、リモートおよび `attachOnly` CDP の到達性とタブを開くリクエストに適用されます。管理対象のループバックプロファイルはローカル CDP の既定値を維持します。 -- 外部で管理されている CDP サービスがループバック経由で到達可能な場合、そのプロファイルに `attachOnly: true` を設定します。そうしないと、OpenClaw はループバックポートをローカル管理対象ブラウザープロファイルとして扱い、ローカルポート所有権エラーを報告する場合があります。 -- `existing-session` プロファイルは CDP ではなく Chrome MCP を使用し、選択したホストまたは接続済みブラウザーノードを通じてアタッチできます。 -- `existing-session` プロファイルでは、Brave や Edge などの特定の Chromium ベースブラウザープロファイルを対象にするために `userDataDir` を設定できます。 -- `existing-session` プロファイルは現在の Chrome MCP ルート制限を維持します。CSS セレクターターゲティングの代わりに snapshot/ref 駆動のアクション、1 ファイルアップロードフック、ダイアログタイムアウト上書きなし、`wait --load networkidle` なし、さらに `responsebody`、PDF エクスポート、ダウンロードインターセプト、バッチアクションなしです。 -- ローカル管理対象の `openclaw` プロファイルは `cdpPort` と `cdpUrl` を自動割り当てします。`cdpUrl` を明示的に設定するのはリモート CDP の場合のみです。 -- ローカル管理対象プロファイルでは、そのプロファイルについてグローバルな `browser.executablePath` を上書きするために `executablePath` を設定できます。これを使うと、あるプロファイルを Chrome で、別のプロファイルを Brave で実行できます。 -- ローカル管理対象プロファイルは、プロセス開始後の Chrome CDP HTTP 検出に `browser.localLaunchTimeoutMs` を使用し、起動後の CDP WebSocket 準備完了に `browser.localCdpReadyTimeoutMs` を使用します。Chrome は正常に起動するが準備完了チェックが起動処理と競合する遅いホストでは、これらを引き上げます。どちらの値も `120000` ms 以下の正の整数である必要があります。無効な設定値は拒否されます。 -- 自動検出順序: Chromium ベースの場合は既定ブラウザー → Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 厳格モードでは、明示的な例外には `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使用します。 +- リモートプロファイルはアタッチ専用です (開始/停止/リセットは無効)。 +- `profiles.*.cdpUrl` は `http://`、`https://`、`ws://`、`wss://` を受け付けます。OpenClaw に `/json/version` を検出させたい場合は HTTP(S) を使用します。プロバイダーが直接の DevTools WebSocket URL を提供する場合は WS(S) を使用します。 +- `remoteCdpTimeoutMs` と `remoteCdpHandshakeTimeoutMs` は、リモートおよび `attachOnly` CDP の到達性に加え、タブを開くリクエストに適用されます。管理対象の loopback プロファイルはローカル CDP のデフォルトを維持します。 +- 外部管理の CDP サービスに loopback 経由で到達できる場合は、そのプロファイルの `attachOnly: true` を設定します。それ以外の場合、OpenClaw は loopback ポートをローカル管理ブラウザープロファイルとして扱い、ローカルポートの所有権エラーを報告することがあります。 +- `existing-session` プロファイルは CDP の代わりに Chrome MCP を使用し、選択されたホストまたは接続済みブラウザーノード経由でアタッチできます。 +- `existing-session` プロファイルは、Brave や Edge などの特定の Chromium ベースのブラウザープロファイルを対象にするために `userDataDir` を設定できます。 +- `existing-session` プロファイルは現在の Chrome MCP ルート制限を維持します。CSS セレクター指定ではなく snapshot/ref 駆動のアクション、1 ファイルのアップロードフック、ダイアログタイムアウト上書きなし、`wait --load networkidle` なし、さらに `responsebody`、PDF エクスポート、ダウンロードインターセプト、バッチアクションなしです。 +- ローカル管理の `openclaw` プロファイルは `cdpPort` と `cdpUrl` を自動割り当てします。リモート CDP の場合のみ `cdpUrl` を明示的に設定します。 +- ローカル管理プロファイルは、そのプロファイルのグローバルな `browser.executablePath` を上書きするために `executablePath` を設定できます。これを使用すると、1 つのプロファイルを Chrome で、別のプロファイルを Brave で実行できます。 +- ローカル管理プロファイルは、プロセス開始後の Chrome CDP HTTP 検出に `browser.localLaunchTimeoutMs` を使用し、起動後の CDP websocket 準備完了に `browser.localCdpReadyTimeoutMs` を使用します。Chrome は正常に起動するものの、準備完了チェックが起動と競合する低速なホストでは、これらを引き上げてください。両方の値は `120000` ms までの正の整数である必要があります。無効な設定値は拒否されます。 +- 自動検出順: Chromium ベースの場合はデフォルトブラウザー → Chrome → Brave → Edge → Chromium → Chrome Canary。 - `browser.executablePath` と `browser.profiles..executablePath` はどちらも、Chromium 起動前に OS のホームディレクトリとして `~` と `~/...` を受け付けます。`existing-session` プロファイルのプロファイルごとの `userDataDir` もチルダ展開されます。 -- 制御サービス: ループバックのみ（ポートは `gateway.port` から派生、既定は `18791`）。 -- `extraArgs` は、ローカル Chromium 起動に追加の起動フラグを付加します（例: `--disable-gpu`、ウィンドウサイズ指定、デバッグフラグ）。 +- コントロールサービス: loopback のみ (`gateway.port` から派生するポート、デフォルトは `18791`)。 +- `extraArgs` は、ローカル Chromium 起動に追加の起動フラグを付加します (例: `--disable-gpu`、ウィンドウサイズ、デバッグフラグ)。 --- @@ -302,8 +303,8 @@ OpenClaw 管理の MCP サーバー定義は `mcp.servers` 配下にあり、組 } ``` -- `seamColor`: ネイティブアプリ UI クロームのアクセントカラー（Talk Mode の吹き出しの色合いなど）。 -- `assistant`: Control UI の識別情報の上書き。アクティブなエージェント識別情報にフォールバックします。 +- `seamColor`: ネイティブアプリ UI クロームのアクセントカラー (Talk Mode の吹き出しの色合いなど)。 +- `assistant`: Control UI の ID 上書き。アクティブなエージェント ID にフォールバックします。 --- @@ -381,73 +382,73 @@ OpenClaw 管理の MCP サーバー定義は `mcp.servers` 配下にあり、組 -- `mode`: `local`（Gateway を実行）または `remote`（リモート Gateway に接続）。`local` でない限り、Gateway は起動を拒否します。 -- `port`: WS + HTTP 用の単一の多重化ポート。優先順位: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 -- `bind`: `auto`、`loopback`（デフォルト）、`lan`（`0.0.0.0`）、`tailnet`（Tailscale IP のみ）、または `custom`。 -- **レガシー bind エイリアス**: ホストエイリアス（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）ではなく、`gateway.bind` では bind モード値（`auto`、`loopback`、`lan`、`tailnet`、`custom`）を使用してください。 -- **Docker 注記**: デフォルトの `loopback` bind はコンテナ内の `127.0.0.1` でリッスンします。Docker ブリッジネットワーク（`-p 18789:18789`）ではトラフィックが `eth0` に到着するため、Gateway に到達できません。`--network host` を使用するか、すべてのインターフェイスでリッスンするために `bind: "lan"`（または `customBindHost: "0.0.0.0"` と併せて `bind: "custom"`）を設定してください。 -- **認証**: デフォルトで必須です。非 loopback bind には Gateway 認証が必要です。実際には、共有トークン/パスワード、または `gateway.auth.mode: "trusted-proxy"` を持つ ID 対応リバースプロキシを意味します。オンボーディングウィザードはデフォルトでトークンを生成します。 -- `gateway.auth.token` と `gateway.auth.password` の両方が設定されている場合（SecretRefs を含む）、`gateway.auth.mode` を明示的に `token` または `password` に設定してください。両方が設定されていて mode が未設定の場合、起動およびサービスのインストール/修復フローは失敗します。 -- `gateway.auth.mode: "none"`: 明示的な認証なしモード。信頼済みの local loopback セットアップでのみ使用してください。これは意図的にオンボーディングプロンプトでは提示されません。 -- `gateway.auth.mode: "trusted-proxy"`: ブラウザー/ユーザー認証を ID 対応リバースプロキシに委任し、`gateway.trustedProxies` からの ID ヘッダーを信頼します（[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth)を参照）。このモードはデフォルトで **非 loopback** のプロキシソースを想定します。同一ホストの loopback リバースプロキシには、明示的な `gateway.auth.trustedProxy.allowLoopback = true` が必要です。内部の同一ホスト呼び出し元は、ローカル直接フォールバックとして `gateway.auth.password` を使用できます。`gateway.auth.token` は trusted-proxy モードとは引き続き相互排他的です。 -- `gateway.auth.allowTailscale`: `true` の場合、Tailscale Serve ID ヘッダーで Control UI/WebSocket 認証を満たせます（`tailscale whois` で検証）。HTTP API エンドポイントはその Tailscale ヘッダー認証を使用せず、代わりに Gateway の通常の HTTP 認証モードに従います。このトークンなしフローは、Gateway ホストが信頼されていることを前提とします。`tailscale.mode = "serve"` の場合、デフォルトは `true` です。 -- `gateway.auth.rateLimit`: 任意の認証失敗リミッター。クライアント IP ごと、および認証スコープごと（shared-secret と device-token は個別に追跡）に適用されます。ブロックされた試行は `429` + `Retry-After` を返します。 - - 非同期 Tailscale Serve Control UI パスでは、同じ `{scope, clientIp}` の失敗試行は失敗書き込みの前に直列化されます。そのため、同じクライアントからの同時の不正な試行は、両方が単なる不一致として競合して通過するのではなく、2 回目のリクエストでリミッターに引っかかることがあります。 - - `gateway.auth.rateLimit.exemptLoopback` のデフォルトは `true` です。テストセットアップや厳格なプロキシデプロイなどで localhost トラフィックも意図的にレート制限したい場合は、`false` に設定してください。 -- ブラウザー由来の WS 認証試行は、loopback 免除を無効にした状態で常にスロットリングされます（ブラウザーベースの localhost 総当たり攻撃に対する多層防御）。 -- loopback では、これらのブラウザー由来のロックアウトは正規化された `Origin` - 値ごとに分離されるため、ある localhost origin からの繰り返し失敗が別の origin を - 自動的にロックアウトすることはありません。 -- `tailscale.mode`: `serve`（tailnet のみ、loopback bind）または `funnel`（公開、認証が必要）。 -- `controlUi.allowedOrigins`: Gateway WebSocket 接続用の明示的なブラウザー origin 許可リスト。非 loopback origin からブラウザークライアントが想定される場合に必須です。 -- `controlUi.chatMessageMaxWidth`: グループ化された Control UI チャットメッセージの任意の最大幅。`960px`、`82%`、`min(1280px, 82%)`、`calc(100% - 2rem)` など、制約付き CSS 幅値を受け付けます。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host ヘッダー origin ポリシーに意図的に依存するデプロイで、Host ヘッダー origin フォールバックを有効にする危険なモード。 -- `remote.transport`: `ssh`（デフォルト）または `direct`（ws/wss）。`direct` の場合、`remote.url` は `ws://` または `wss://` でなければなりません。 +- `mode`: `local` (gatewayを実行) または `remote` (リモートgatewayへ接続)。Gatewayは`local`でない限り起動を拒否します。 +- `port`: WS + HTTP用の単一多重化ポート。優先順位: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `bind`: `auto`、`loopback` (デフォルト)、`lan` (`0.0.0.0`)、`tailnet` (Tailscale IPのみ)、または`custom`。 +- **レガシーbindエイリアス**: ホストエイリアス (`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`) ではなく、`gateway.bind`ではbindモード値 (`auto`、`loopback`、`lan`、`tailnet`、`custom`) を使用します。 +- **Dockerに関する注意**: デフォルトの`loopback` bindはコンテナ内の`127.0.0.1`で待ち受けます。Dockerブリッジネットワーク (`-p 18789:18789`) では、トラフィックは`eth0`に到着するため、gatewayに到達できません。`--network host`を使用するか、すべてのインターフェイスで待ち受けるために`bind: "lan"` (または`customBindHost: "0.0.0.0"`を指定した`bind: "custom"`) を設定します。 +- **認証**: デフォルトで必須です。非loopback bindにはgateway認証が必要です。実際には、共有トークン/パスワード、または`gateway.auth.mode: "trusted-proxy"`を使うID認識リバースプロキシを意味します。オンボーディング ウィザードはデフォルトでトークンを生成します。 +- `gateway.auth.token`と`gateway.auth.password`の両方が設定されている場合 (SecretRefを含む)、`gateway.auth.mode`を明示的に`token`または`password`に設定します。両方が設定されていてmodeが未設定の場合、起動およびサービスのインストール/修復フローは失敗します。 +- `gateway.auth.mode: "none"`: 明示的な認証なしモードです。信頼済みのlocal loopbackセットアップにのみ使用します。これは意図的にオンボーディングプロンプトでは提示されません。 +- `gateway.auth.mode: "trusted-proxy"`: ブラウザ/ユーザー認証をID認識リバースプロキシに委任し、`gateway.trustedProxies`からのIDヘッダーを信頼します ([Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth)を参照)。このモードはデフォルトで**非loopback**プロキシソースを想定します。同一ホストのloopbackリバースプロキシには、明示的な`gateway.auth.trustedProxy.allowLoopback = true`が必要です。内部の同一ホスト呼び出し元は、ローカル直接フォールバックとして`gateway.auth.password`を使用できます。`gateway.auth.token`はtrusted-proxyモードと引き続き相互排他的です。 +- `gateway.auth.allowTailscale`: `true`の場合、Tailscale ServeのIDヘッダーでControl UI/WebSocket認証を満たせます (`tailscale whois`で検証)。HTTP APIエンドポイントはそのTailscaleヘッダー認証を**使用しません**。代わりにgatewayの通常のHTTP認証モードに従います。このトークンなしフローは、gatewayホストが信頼されていることを前提とします。`tailscale.mode = "serve"`の場合、デフォルトは`true`です。 +- `gateway.auth.rateLimit`: 任意の認証失敗リミッター。クライアントIPごと、および認証スコープごとに適用されます (shared-secretとdevice-tokenは独立して追跡されます)。ブロックされた試行は`429` + `Retry-After`を返します。 + - 非同期Tailscale Serve Control UIパスでは、同じ`{scope, clientIp}`の失敗試行は失敗書き込み前に直列化されます。そのため、同じクライアントからの同時不正試行は、単なる不一致として両方が競合して通過するのではなく、2番目のリクエストでリミッターを発動することがあります。 + - `gateway.auth.rateLimit.exemptLoopback`のデフォルトは`true`です。localhostトラフィックも意図的にレート制限したい場合 (テストセットアップや厳格なプロキシデプロイなど) は`false`に設定します。 +- ブラウザoriginのWS認証試行は、loopback免除を無効にして常にスロットルされます (ブラウザベースのlocalhostブルートフォースに対する多層防御)。 +- loopbackでは、これらのブラウザoriginロックアウトは正規化された`Origin` + 値ごとに分離されるため、あるlocalhost originからの繰り返し失敗が、 + 別のoriginを自動的にロックアウトすることはありません。 +- `tailscale.mode`: `serve` (tailnetのみ、loopback bind) または`funnel` (公開、認証が必要)。 +- `controlUi.allowedOrigins`: Gateway WebSocket接続用の明示的なブラウザorigin許可リスト。非loopback originからブラウザクライアントが想定される場合に必須です。 +- `controlUi.chatMessageMaxWidth`: グループ化されたControl UIチャットメッセージの任意の最大幅。`960px`、`82%`、`min(1280px, 82%)`、`calc(100% - 2rem)`などの制約付きCSS幅値を受け付けます。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Hostヘッダーoriginポリシーに意図的に依存するデプロイのために、Hostヘッダーoriginフォールバックを有効にする危険なモードです。 +- `remote.transport`: `ssh` (デフォルト) または`direct` (ws/wss)。`direct`の場合、`remote.url`は`ws://`または`wss://`である必要があります。 - `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: 信頼済みプライベートネットワーク - IP への平文 `ws://` を許可する、クライアント側プロセス環境の - 緊急時オーバーライド。平文のデフォルトは引き続き loopback のみです。対応する `openclaw.json` - は存在せず、 - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` などのブラウザーのプライベートネットワーク設定は Gateway - WebSocket クライアントに影響しません。 -- `gateway.remote.token` / `.password` はリモートクライアントの認証情報フィールドです。それ自体では Gateway 認証を設定しません。 -- `gateway.push.apns.relay.baseUrl`: 公式/TestFlight iOS ビルドがリレーバック登録を Gateway に公開した後に使用する、外部 APNs リレーのベース HTTPS URL。この URL は iOS ビルドにコンパイルされたリレー URL と一致している必要があります。 -- `gateway.push.apns.relay.timeoutMs`: Gateway からリレーへの送信タイムアウト（ミリ秒）。デフォルトは `10000` です。 -- リレーバック登録は特定の Gateway ID に委任されます。ペアリングされた iOS アプリは `gateway.identity.get` を取得し、その ID をリレー登録に含め、登録スコープの送信許可を Gateway に転送します。別の Gateway は、その保存済み登録を再利用できません。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 上記リレー設定の一時的な環境変数オーバーライド。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTP リレー URL 用の開発専用エスケープハッチ。本番リレー URL は HTTPS のままにしてください。 -- `gateway.handshakeTimeoutMs`: 認証前 Gateway WebSocket ハンドシェイクタイムアウト（ミリ秒）。デフォルト: `15000`。`OPENCLAW_HANDSHAKE_TIMEOUT_MS` が設定されている場合は優先されます。ローカルクライアントが接続できる一方で起動ウォームアップがまだ落ち着いていない、高負荷または低電力ホストではこれを増やしてください。 -- `gateway.channelHealthCheckMinutes`: チャネルヘルスモニター間隔（分）。ヘルスモニター再起動をグローバルに無効化するには `0` を設定します。デフォルト: `5`。 -- `gateway.channelStaleEventThresholdMinutes`: stale socket しきい値（分）。これは `gateway.channelHealthCheckMinutes` 以上にしてください。デフォルト: `30`。 -- `gateway.channelMaxRestartsPerHour`: ローリング 1 時間でのチャネル/アカウントごとのヘルスモニター再起動の最大数。デフォルト: `10`。 -- `channels..healthMonitor.enabled`: グローバルモニターを有効にしたまま、チャネルごとにヘルスモニター再起動をオプトアウトします。 -- `channels..accounts..healthMonitor.enabled`: 複数アカウントチャネル向けのアカウントごとのオーバーライド。設定されている場合、チャネルレベルのオーバーライドより優先されます。 -- ローカル Gateway 呼び出しパスは、`gateway.auth.*` が未設定の場合にのみ `gateway.remote.*` をフォールバックとして使用できます。 -- `gateway.auth.token` / `gateway.auth.password` が SecretRef 経由で明示的に設定され、解決されない場合、解決はフェイルクローズします（リモートフォールバックによる隠蔽なし）。 -- `trustedProxies`: TLS を終端する、または forwarded-client ヘッダーを注入するリバースプロキシ IP。自分が管理するプロキシのみを列挙してください。loopback エントリは、同一ホストのプロキシ/ローカル検出セットアップ（例: Tailscale Serve またはローカルリバースプロキシ）では引き続き有効ですが、loopback リクエストを `gateway.auth.mode: "trusted-proxy"` の対象にするものではありません。 -- `allowRealIpFallback`: `true` の場合、`X-Forwarded-For` がないときに Gateway は `X-Real-IP` を受け入れます。フェイルクローズ動作のため、デフォルトは `false` です。 -- `gateway.nodes.pairing.autoApproveCidrs`: 要求スコープなしの初回ノードデバイスペアリングを自動承認するための任意の CIDR/IP 許可リスト。未設定の場合は無効です。これは operator/browser/Control UI/WebChat ペアリングを自動承認せず、role、scope、metadata、public-key のアップグレードも自動承認しません。 -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: ペアリングおよびプラットフォーム許可リスト評価後の、宣言済みノードコマンドに対するグローバルな許可/拒否調整。`camera.snap`、`camera.clip`、`screen.record` などの危険なノードコマンドを有効にするには `allowCommands` を使用してください。`denyCommands` は、プラットフォームのデフォルトや明示的な許可に含まれる場合でもコマンドを除外します。ノードが宣言済みコマンドリストを変更した後は、そのデバイスペアリングを拒否して再承認し、Gateway が更新されたコマンドスナップショットを保存するようにしてください。 -- `gateway.tools.deny`: HTTP `POST /tools/invoke` でブロックする追加ツール名（デフォルト拒否リストを拡張）。 -- `gateway.tools.allow`: デフォルトの HTTP 拒否リストからツール名を削除します。 + IPへの平文`ws://`を許可する、クライアント側プロセス環境の + 緊急オーバーライドです。平文のデフォルトは引き続きloopbackのみです。対応する`openclaw.json` + 設定はなく、`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`のような + ブラウザのプライベートネットワーク設定はGateway + WebSocketクライアントに影響しません。 +- `gateway.remote.token` / `.password`はリモートクライアントの認証情報フィールドです。それ自体でgateway認証を設定するものではありません。 +- `gateway.push.apns.relay.baseUrl`: 公式/TestFlight iOSビルドがリレー対応登録をgatewayへ公開した後に使用する、外部APNsリレーのベースHTTPS URL。このURLはiOSビルドにコンパイルされたリレーURLと一致する必要があります。 +- `gateway.push.apns.relay.timeoutMs`: gatewayからリレーへの送信タイムアウト (ミリ秒)。デフォルトは`10000`です。 +- リレー対応登録は特定のgateway IDに委任されます。ペアリング済みiOSアプリは`gateway.identity.get`を取得し、そのIDをリレー登録に含め、登録スコープの送信許可をgatewayへ転送します。別のgatewayは、その保存済み登録を再利用できません。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 上記リレー設定用の一時的なenvオーバーライド。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTPリレーURL用の開発専用回避手段。本番リレーURLはHTTPSのままにしてください。 +- `gateway.handshakeTimeoutMs`: 認証前Gateway WebSocketハンドシェイクタイムアウト (ミリ秒)。デフォルト: `15000`。`OPENCLAW_HANDSHAKE_TIMEOUT_MS`が設定されている場合は優先されます。負荷が高いホストや低性能ホストで、起動ウォームアップがまだ安定しきっていない間にローカルクライアントが接続できる場合は、この値を増やします。 +- `gateway.channelHealthCheckMinutes`: チャンネルヘルスモニター間隔 (分)。ヘルスモニターによる再起動をグローバルに無効化するには`0`を設定します。デフォルト: `5`。 +- `gateway.channelStaleEventThresholdMinutes`: 古いソケットとみなすしきい値 (分)。これは`gateway.channelHealthCheckMinutes`以上に保ちます。デフォルト: `30`。 +- `gateway.channelMaxRestartsPerHour`: ローリング1時間内のチャンネル/アカウントごとのヘルスモニター最大再起動回数。デフォルト: `10`。 +- `channels..healthMonitor.enabled`: グローバルモニターは有効にしたまま、チャンネルごとにヘルスモニター再起動を無効化する設定。 +- `channels..accounts..healthMonitor.enabled`: マルチアカウントチャンネルのアカウントごとのオーバーライド。設定されている場合、チャンネルレベルのオーバーライドより優先されます。 +- ローカルgateway呼び出しパスは、`gateway.auth.*`が未設定の場合にのみ`gateway.remote.*`をフォールバックとして使用できます。 +- `gateway.auth.token` / `gateway.auth.password`がSecretRef経由で明示的に設定され、解決できない場合、解決はフェイルクローズします (リモートフォールバックによるマスクはありません)。 +- `trustedProxies`: TLSを終端する、または転送元クライアントヘッダーを注入するリバースプロキシIP。自分が管理するプロキシのみを列挙してください。loopbackエントリは、同一ホストのプロキシ/ローカル検出セットアップ (例: Tailscale Serveやローカルリバースプロキシ) では引き続き有効ですが、loopbackリクエストを`gateway.auth.mode: "trusted-proxy"`の対象にするものでは**ありません**。 +- `allowRealIpFallback`: `true`の場合、`X-Forwarded-For`がないときにgatewayは`X-Real-IP`を受け付けます。フェイルクローズ動作のため、デフォルトは`false`です。 +- `gateway.nodes.pairing.autoApproveCidrs`: 要求スコープがない初回ノードデバイスペアリングを自動承認するための任意のCIDR/IP許可リスト。未設定の場合は無効です。これはoperator/browser/Control UI/WebChatペアリングを自動承認せず、role、scope、metadata、public-keyのアップグレードも自動承認しません。 +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: ペアリングとプラットフォーム許可リスト評価の後に、宣言されたノードコマンドに対して適用されるグローバルな許可/拒否制御。`camera.snap`、`camera.clip`、`screen.record`のような危険なノードコマンドを明示的に有効化するには`allowCommands`を使用します。`denyCommands`は、プラットフォームのデフォルトや明示的な許可に含まれる場合でもコマンドを削除します。ノードが宣言済みコマンドリストを変更した後は、そのデバイスペアリングを拒否して再承認し、gatewayに更新済みコマンドスナップショットを保存させます。 +- `gateway.tools.deny`: HTTP `POST /tools/invoke`でブロックされる追加ツール名 (デフォルトの拒否リストを拡張)。 +- `gateway.tools.allow`: デフォルトHTTP拒否リストからツール名を削除します。 -### OpenAI 互換エンドポイント +### OpenAI互換エンドポイント -- Chat Completions: デフォルトでは無効です。`gateway.http.endpoints.chatCompletions.enabled: true` で有効化します。 +- Chat Completions: デフォルトでは無効です。`gateway.http.endpoints.chatCompletions.enabled: true`で有効化します。 - Responses API: `gateway.http.endpoints.responses.enabled`。 -- Responses URL 入力の強化: +- Responses URL入力の強化: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空の許可リストは未設定として扱われます。URL 取得を無効化するには `gateway.http.endpoints.responses.files.allowUrl=false` - および/または `gateway.http.endpoints.responses.images.allowUrl=false` を使用してください。 -- 任意のレスポンス強化ヘッダー: - - `gateway.http.securityHeaders.strictTransportSecurity`（管理している HTTPS origin にのみ設定してください。[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts)を参照） + 空の許可リストは未設定として扱われます。URL取得を無効化するには`gateway.http.endpoints.responses.files.allowUrl=false` + および/または`gateway.http.endpoints.responses.images.allowUrl=false`を使用します。 +- 任意のresponse強化ヘッダー: + - `gateway.http.securityHeaders.strictTransportSecurity` (管理しているHTTPS originにのみ設定します。[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts)を参照) -### マルチインスタンス分離 +### 複数インスタンスの分離 -一意のポートと state dir を使って、1 つのホストで複数の Gateway を実行します。 +一意のポートとstate dirで、1つのホスト上に複数のgatewayを実行します: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -455,9 +456,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -便利なフラグ: `--dev`（`~/.openclaw-dev` + ポート `19001` を使用）、`--profile `（`~/.openclaw-` を使用）。 +便利なフラグ: `--dev` (`~/.openclaw-dev` + ポート`19001`を使用)、`--profile ` (`~/.openclaw-`を使用)。 -[複数 Gateway](/ja-JP/gateway/multiple-gateways)を参照してください。 +[Multiple Gateways](/ja-JP/gateway/multiple-gateways)を参照してください。 ### `gateway.tls` @@ -475,11 +476,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: Gateway リスナーでの TLS 終端（HTTPS/WSS）を有効にします（デフォルト: `false`）。 -- `autoGenerate`: 明示的なファイルが設定されていない場合に、ローカル自己署名証明書/鍵ペアを自動生成します。ローカル/開発用途のみ。 -- `certPath`: TLS 証明書ファイルへのファイルシステムパス。 -- `keyPath`: TLS 秘密鍵ファイルへのファイルシステムパス。権限を制限してください。 -- `caPath`: クライアント検証またはカスタム信頼チェーン用の任意の CA バンドルパス。 +- `enabled`: gatewayリスナー (HTTPS/WSS) でTLS終端を有効にします (デフォルト: `false`)。 +- `autoGenerate`: 明示的なファイルが設定されていない場合に、ローカルの自己署名cert/keyペアを自動生成します。ローカル/開発用途のみです。 +- `certPath`: TLS証明書ファイルへのファイルシステムパス。 +- `keyPath`: TLS秘密鍵ファイルへのファイルシステムパス。権限を制限してください。 +- `caPath`: クライアント検証またはカスタム信頼チェーン用の任意のCAバンドルパス。 ### `gateway.reload` @@ -495,17 +496,17 @@ openclaw gateway --port 19001 } ``` -- `mode`: 実行時に設定編集を適用する方法を制御します。 +- `mode`: 実行時にconfig編集を適用する方法を制御します。 - `"off"`: ライブ編集を無視します。変更には明示的な再起動が必要です。 - - `"restart"`: 設定変更時に常に Gateway プロセスを再起動します。 + - `"restart"`: config変更時に常にgatewayプロセスを再起動します。 - `"hot"`: 再起動せずにプロセス内で変更を適用します。 - - `"hybrid"`（デフォルト）: まずホットリロードを試行し、必要な場合は再起動にフォールバックします。 -- `debounceMs`: 設定変更が適用される前のデバウンス期間（ms、非負整数）。 -- `deferralTimeoutMs`: 再起動を強制する前に進行中の操作を待つ任意の最大時間（ms）。デフォルトの有界待機（`300000`）を使用するには省略します。無期限に待機し、まだ保留中である旨の警告を定期的にログ出力するには `0` を設定します。 + - `"hybrid"` (デフォルト): まずhot reloadを試し、必要な場合はrestartへフォールバックします。 +- `debounceMs`: config変更を適用する前のデバウンス期間 (ms、非負整数)。 +- `deferralTimeoutMs`: 再起動を強制する前に進行中の操作を待つ任意の最大時間 (ms)。省略するとデフォルトの上限付き待機 (`300000`) を使用します。無期限に待機し、定期的に未完了警告をログするには`0`を設定します。 --- -## フック +## Hooks ```json5 { @@ -539,21 +540,21 @@ openclaw gateway --port 19001 ``` 認証: `Authorization: Bearer ` または `x-openclaw-token: `。 -クエリ文字列のhookトークンは拒否されます。 +クエリ文字列のフックトークンは拒否されます。 -検証と安全性に関するメモ: +検証と安全性に関する注意: - `hooks.enabled=true` には空でない `hooks.token` が必要です。 -- `hooks.token` は `gateway.auth.token` と**異なる**必要があります。Gatewayトークンの再利用は拒否されます。 -- `hooks.path` を `/` にすることはできません。`/hooks` などの専用サブパスを使用してください。 +- `hooks.token` は `gateway.auth.token` と**別の値**である必要があります。Gateway トークンの再利用は拒否されます。 +- `hooks.path` に `/` は使えません。`/hooks` のような専用サブパスを使用してください。 - `hooks.allowRequestSessionKey=true` の場合は、`hooks.allowedSessionKeyPrefixes` を制限してください（例: `["hook:"]`）。 -- マッピングまたはプリセットがテンプレート化された `sessionKey` を使用する場合は、`hooks.allowedSessionKeyPrefixes` と `hooks.allowRequestSessionKey=true` を設定してください。静的マッピングキーではそのオプトインは不要です。 +- マッピングまたはプリセットがテンプレート化された `sessionKey` を使用する場合は、`hooks.allowedSessionKeyPrefixes` と `hooks.allowRequestSessionKey=true` を設定してください。静的なマッピングキーにはこのオプトインは不要です。 **エンドポイント:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - リクエストペイロードの `sessionKey` は、`hooks.allowRequestSessionKey=true` の場合にのみ受け入れられます（デフォルト: `false`）。 + - リクエストペイロードの `sessionKey` は、`hooks.allowRequestSessionKey=true` の場合のみ受け付けられます（デフォルト: `false`）。 - `POST /hooks/` → `hooks.mappings` によって解決されます - テンプレートでレンダリングされたマッピングの `sessionKey` 値は外部から提供されたものとして扱われ、同様に `hooks.allowRequestSessionKey=true` が必要です。 @@ -562,24 +563,24 @@ openclaw gateway --port 19001 - `match.path` は `/hooks` の後のサブパスに一致します（例: `/hooks/gmail` → `gmail`）。 - `match.source` は汎用パスのペイロードフィールドに一致します。 - `{{messages[0].subject}}` のようなテンプレートはペイロードから読み取ります。 -- `transform` はhookアクションを返す JS/TS モジュールを指すことができます。 - - `transform.module` は相対パスである必要があり、`hooks.transformsDir` 内に留まります（絶対パスとトラバーサルは拒否されます）。 - - `hooks.transformsDir` は `~/.openclaw/hooks/transforms` の下に置いてください。ワークスペースのSkillディレクトリは拒否されます。`openclaw doctor` がこのパスを無効として報告する場合は、変換モジュールをhooks変換ディレクトリに移動するか、`hooks.transformsDir` を削除してください。 -- `agentId` は特定のエージェントにルーティングします。不明な ID はデフォルトにフォールバックします。 +- `transform` はフックアクションを返す JS/TS モジュールを指すことができます。 + - `transform.module` は相対パスである必要があり、`hooks.transformsDir` 内にとどまります（絶対パスとトラバーサルは拒否されます）。 + - `hooks.transformsDir` は `~/.openclaw/hooks/transforms` の配下に置いてください。ワークスペースの skill ディレクトリは拒否されます。`openclaw doctor` がこのパスを無効として報告する場合は、transform モジュールを hooks transforms ディレクトリへ移動するか、`hooks.transformsDir` を削除してください。 +- `agentId` は特定のエージェントへルーティングします。不明な ID はデフォルトへフォールバックします。 - `allowedAgentIds`: 明示的なルーティングを制限します（`*` または省略 = すべて許可、`[]` = すべて拒否）。 -- `defaultSessionKey`: 明示的な `sessionKey` なしでhookエージェントを実行するための任意の固定セッションキーです。 -- `allowRequestSessionKey`: `/hooks/agent` の呼び出し元とテンプレート駆動のマッピングセッションキーが `sessionKey` を設定できるようにします（デフォルト: `false`）。 -- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（リクエスト + マッピング）に対する任意のプレフィックス許可リストです。例: `["hook:"]`。いずれかのマッピングまたはプリセットがテンプレート化された `sessionKey` を使用する場合は必須になります。 -- `deliver: true` は最終返信をチャンネルに送信します。`channel` のデフォルトは `last` です。 -- `model` はこのhook実行の LLM を上書きします（モデルカタログが設定されている場合は許可されている必要があります）。 +- `defaultSessionKey`: 明示的な `sessionKey` なしで実行されるフックエージェント用の任意の固定セッションキーです。 +- `allowRequestSessionKey`: `/hooks/agent` の呼び出し元とテンプレート駆動のマッピングセッションキーに `sessionKey` の設定を許可します（デフォルト: `false`）。 +- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（リクエスト + マッピング）用の任意のプレフィックス許可リストです。例: `["hook:"]`。いずれかのマッピングまたはプリセットがテンプレート化された `sessionKey` を使用する場合は必須になります。 +- `deliver: true` は最終返信をチャンネルへ送信します。`channel` のデフォルトは `last` です。 +- `model` はこのフック実行の LLM を上書きします（モデルカタログが設定されている場合は許可されている必要があります）。 -### Gmail連携 +### Gmail 統合 -- 組み込みのGmailプリセットは `sessionKey: "hook:gmail:{{messages[0].id}}"` を使用します。 -- そのメッセージ単位のルーティングを維持する場合は、`hooks.allowRequestSessionKey: true` を設定し、`hooks.allowedSessionKeyPrefixes` をGmail名前空間に一致するよう制限してください。例: `["hook:", "hook:gmail:"]`。 -- `hooks.allowRequestSessionKey: false` が必要な場合は、テンプレート化されたデフォルトではなく、静的な `sessionKey` でプリセットを上書きしてください。 +- 組み込み Gmail プリセットは `sessionKey: "hook:gmail:{{messages[0].id}}"` を使用します。 +- そのメッセージごとのルーティングを維持する場合は、`hooks.allowRequestSessionKey: true` を設定し、`hooks.allowedSessionKeyPrefixes` を Gmail 名前空間に一致するよう制限してください。例: `["hook:", "hook:gmail:"]`。 +- `hooks.allowRequestSessionKey: false` が必要な場合は、テンプレート化されたデフォルトの代わりに静的な `sessionKey` でプリセットを上書きしてください。 ```json5 { @@ -602,12 +603,12 @@ openclaw gateway --port 19001 } ``` -- 設定されている場合、Gatewayは起動時に `gog gmail watch serve` を自動起動します。無効にするには `OPENCLAW_SKIP_GMAIL_WATCHER=1` を設定してください。 -- Gatewayと並行して別の `gog gmail watch serve` を実行しないでください。 +- Gateway は設定済みの場合、起動時に `gog gmail watch serve` を自動起動します。無効にするには `OPENCLAW_SKIP_GMAIL_WATCHER=1` を設定してください。 +- Gateway と並行して別の `gog gmail watch serve` を実行しないでください。 --- -## キャンバスホスト +## Canvas ホスト ```json5 { @@ -619,24 +620,24 @@ openclaw gateway --port 19001 } ``` -- エージェントが編集可能な HTML/CSS/JS と A2UI を、Gatewayポート配下の HTTP で提供します: +- エージェントが編集可能な HTML/CSS/JS と A2UI を、Gateway ポート配下の HTTP で提供します: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - ローカル専用: `gateway.bind: "loopback"`（デフォルト）を維持してください。 -- 非ループバックのバインド: キャンバスルートには、他のGateway HTTPサーフェスと同様にGateway認証（トークン/パスワード/信頼済みプロキシ）が必要です。 -- Node WebView は通常、認証ヘッダーを送信しません。ノードがペアリングされ接続された後、Gatewayはキャンバス/A2UIアクセス用のノードスコープ付きケイパビリティURLを通知します。 -- ケイパビリティURLはアクティブなノードWSセッションに紐づき、短時間で期限切れになります。IPベースのフォールバックは使用されません。 -- 提供されるHTMLにライブリロードクライアントを注入します。 +- 非ループバックの bind: canvas ルートには、他の Gateway HTTP サーフェスと同じく Gateway 認証（トークン/パスワード/trusted-proxy）が必要です。 +- Node WebView は通常、認証ヘッダーを送信しません。ノードがペアリングされ接続された後、Gateway は canvas/A2UI アクセス用にノードスコープの capability URL を通知します。 +- capability URL はアクティブなノード WS セッションに紐付き、短時間で期限切れになります。IP ベースのフォールバックは使用されません。 +- 提供される HTML にライブリロードクライアントを注入します。 - 空の場合はスターター `index.html` を自動作成します。 - A2UI も `/__openclaw__/a2ui/` で提供します。 -- 変更にはGatewayの再起動が必要です。 -- 大きなディレクトリまたは `EMFILE` エラーではライブリロードを無効にしてください。 +- 変更には Gateway の再起動が必要です。 +- 大きなディレクトリや `EMFILE` エラーではライブリロードを無効にしてください。 --- -## 探索 +## 検出 -### mDNS（Bonjour） +### mDNS (Bonjour) ```json5 { @@ -648,13 +649,13 @@ openclaw gateway --port 19001 } ``` -- `minimal`（バンドルされた `bonjour` Plugin が有効な場合のデフォルト）: TXTレコードから `cliPath` + `sshPort` を省略します。 -- `full`: `cliPath` + `sshPort` を含めます。LANマルチキャスト広告には、引き続きバンドルされた `bonjour` Plugin が有効である必要があります。 -- `off`: Pluginの有効化状態を変更せずにLANマルチキャスト広告を抑制します。 -- バンドルされた `bonjour` Plugin はmacOSホストでは自動起動し、Linux、Windows、コンテナ化されたGatewayデプロイではオプトインです。 -- ホスト名は、有効なDNSラベルである場合はシステムホスト名がデフォルトになり、そうでない場合は `openclaw` にフォールバックします。`OPENCLAW_MDNS_HOSTNAME` で上書きできます。 +- `minimal`（バンドルされた `bonjour` plugin が有効な場合のデフォルト）: TXT レコードから `cliPath` + `sshPort` を省略します。 +- `full`: `cliPath` + `sshPort` を含めます。LAN マルチキャスト広告には、引き続きバンドルされた `bonjour` plugin が有効である必要があります。 +- `off`: plugin の有効化状態を変更せずに LAN マルチキャスト広告を抑止します。 +- バンドルされた `bonjour` plugin は macOS ホストで自動起動し、Linux、Windows、コンテナ化された Gateway デプロイではオプトインです。 +- ホスト名は、有効な DNS ラベルである場合はシステムホスト名がデフォルトになり、そうでない場合は `openclaw` にフォールバックします。`OPENCLAW_MDNS_HOSTNAME` で上書きできます。 -### 広域（DNS-SD） +### 広域 (DNS-SD) ```json5 { @@ -664,7 +665,7 @@ openclaw gateway --port 19001 } ``` -ユニキャストDNS-SDゾーンを `~/.openclaw/dns/` の下に書き込みます。クロスネットワーク探索には、DNSサーバー（CoreDNS推奨）+ TailscaleスプリットDNSと組み合わせてください。 +`~/.openclaw/dns/` 配下にユニキャスト DNS-SD ゾーンを書き込みます。ネットワークをまたいだ検出には、DNS サーバー（CoreDNS 推奨）+ Tailscale split DNS と組み合わせてください。 セットアップ: `openclaw dns setup --apply`。 @@ -672,7 +673,7 @@ openclaw gateway --port 19001 ## 環境 -### `env` (インライン環境変数) +### `env`（インライン環境変数） ```json5 { @@ -690,13 +691,13 @@ openclaw gateway --port 19001 ``` - インライン環境変数は、プロセス環境にそのキーがない場合にのみ適用されます。 -- `.env` ファイル: CWD の `.env` + `~/.openclaw/.env` (どちらも既存の変数を上書きしません)。 -- `shellEnv`: ログインシェルプロファイルから不足している想定キーをインポートします。 +- `.env` ファイル: CWD の `.env` + `~/.openclaw/.env`（どちらも既存の変数を上書きしません）。 +- `shellEnv`: ログインシェルのプロファイルから、不足している想定キーをインポートします。 - 完全な優先順位については [環境](/ja-JP/help/environment) を参照してください。 ### 環境変数の置換 -任意の設定文字列で `${VAR_NAME}` を使って環境変数を参照します。 +任意の設定文字列内で `${VAR_NAME}` を使って環境変数を参照します。 ```json5 { @@ -706,8 +707,8 @@ openclaw gateway --port 19001 } ``` -- 一致するのは大文字の名前のみです: `[A-Z_][A-Z0-9_]*`。 -- 不足または空の変数があると、設定読み込み時にエラーが発生します。 +- 一致するのは大文字名のみです: `[A-Z_][A-Z0-9_]*`。 +- 欠落している、または空の変数は、設定の読み込み時にエラーを発生させます。 - リテラルの `${VAR}` には `$${VAR}` でエスケープします。 - `$include` と組み合わせて動作します。 @@ -715,11 +716,11 @@ openclaw gateway --port 19001 ## シークレット -シークレット参照は追加的です。平文の値も引き続き機能します。 +シークレット参照は追加的です。プレーンテキスト値も引き続き機能します。 ### `SecretRef` -1つのオブジェクト形状を使用します。 +1 つのオブジェクト形状を使用します。 ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -729,15 +730,15 @@ openclaw gateway --port 19001 - `provider` パターン: `^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` の id パターン: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` の id: 絶対 JSON ポインター (例: `"/providers/openai/apiKey"`) +- `source: "file"` の id: 絶対 JSON ポインター（例: `"/providers/openai/apiKey"`） - `source: "exec"` の id パターン: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` の id に、スラッシュ区切りパスセグメントの `.` または `..` を含めることはできません (例: `a/../b` は拒否されます) +- `source: "exec"` の id には、スラッシュで区切られたパスセグメントとして `.` または `..` を含めてはいけません（例: `a/../b` は拒否されます） ### サポートされる認証情報サーフェス -- 正規マトリクス: [SecretRef 認証情報サーフェス](/ja-JP/reference/secretref-credential-surface) -- `secrets apply` は、サポートされる `openclaw.json` の認証情報パスを対象にします。 -- `auth-profiles.json` の参照は、ランタイム解決と監査カバレッジに含まれます。 +- 正規マトリックス: [SecretRef 認証情報サーフェス](/ja-JP/reference/secretref-credential-surface) +- `secrets apply` はサポートされている `openclaw.json` 認証情報パスを対象にします。 +- `auth-profiles.json` の参照は、ランタイム解決と監査範囲に含まれます。 ### シークレットプロバイダー設定 @@ -767,16 +768,16 @@ openclaw gateway --port 19001 } ``` -メモ: +注記: -- `file` プロバイダーは `mode: "json"` と `mode: "singleValue"` をサポートします (singleValue モードでは `id` は `"value"` である必要があります)。 -- Windows ACL 検証が利用できない場合、file および exec プロバイダーのパスはフェイルクローズします。検証できない信頼済みパスに対してのみ `allowInsecurePath: true` を設定してください。 -- `exec` プロバイダーには絶対 `command` パスが必要で、stdin/stdout 上のプロトコルペイロードを使用します。 -- デフォルトでは、シンボリックリンクのコマンドパスは拒否されます。解決されたターゲットパスを検証しつつシンボリックリンクパスを許可するには、`allowSymlinkCommand: true` を設定してください。 -- `trustedDirs` が設定されている場合、信頼済みディレクトリのチェックは解決されたターゲットパスに適用されます。 -- `exec` の子環境はデフォルトで最小限です。必要な変数は `passEnv` で明示的に渡してください。 -- シークレット参照はアクティベーション時にインメモリスナップショットへ解決され、その後リクエストパスはスナップショットのみを読み取ります。 -- アクティブサーフェスのフィルタリングはアクティベーション中に適用されます。有効なサーフェス上の未解決の参照は起動/再読み込みを失敗させ、非アクティブなサーフェスは診断付きでスキップされます。 +- `file` プロバイダーは `mode: "json"` と `mode: "singleValue"` をサポートします（singleValue モードでは `id` は `"value"` でなければなりません）。 +- Windows ACL 検証を利用できない場合、file および exec プロバイダーのパスはフェイルクローズします。検証できない信頼済みパスに対してのみ `allowInsecurePath: true` を設定してください。 +- `exec` プロバイダーは絶対 `command` パスを必要とし、stdin/stdout 上のプロトコルペイロードを使用します。 +- デフォルトでは、シンボリックリンクのコマンドパスは拒否されます。解決先のターゲットパスを検証しながらシンボリックリンクパスを許可するには、`allowSymlinkCommand: true` を設定します。 +- `trustedDirs` が設定されている場合、信頼済みディレクトリのチェックは解決先のターゲットパスに適用されます。 +- `exec` 子環境はデフォルトで最小限です。必要な変数は `passEnv` で明示的に渡してください。 +- シークレット参照はアクティベーション時にメモリ内スナップショットへ解決され、その後リクエストパスはスナップショットのみを読み取ります。 +- アクティブサーフェスのフィルタリングはアクティベーション中に適用されます。有効なサーフェス上の未解決参照は起動/再読み込みを失敗させますが、非アクティブなサーフェスは診断付きでスキップされます。 --- @@ -799,11 +800,11 @@ openclaw gateway --port 19001 ``` - エージェントごとのプロファイルは `/auth-profiles.json` に保存されます。 -- `auth-profiles.json` は、静的認証情報モード向けに値レベルの参照 (`api_key` には `keyRef`、`token` には `tokenRef`) をサポートします。 -- `{ "provider": { "apiKey": "..." } }` のような従来のフラットな `auth-profiles.json` マップはランタイム形式ではありません。`openclaw doctor --fix` は、それらを `.legacy-flat.*.bak` バックアップ付きの正規 `provider:default` API キープロファイルに書き換えます。 -- OAuth モードのプロファイル (`auth.profiles..mode = "oauth"`) は、SecretRef を基盤にした認証プロファイル認証情報をサポートしません。 -- 静的ランタイム認証情報は、解決済みのインメモリスナップショットから取得されます。従来の静的 `auth.json` エントリは検出時に削除されます。 -- 従来の OAuth は `~/.openclaw/credentials/oauth.json` からインポートされます。 +- `auth-profiles.json` は、静的な認証情報モードに対して値レベルの参照（`api_key` の `keyRef`、`token` の `tokenRef`）をサポートします。 +- `{ "provider": { "apiKey": "..." } }` のようなレガシーのフラットな `auth-profiles.json` マップはランタイム形式ではありません。`openclaw doctor --fix` は、`.legacy-flat.*.bak` バックアップ付きで、それらを正規の `provider:default` API キープロファイルに書き換えます。 +- OAuth モードのプロファイル（`auth.profiles..mode = "oauth"`）は、SecretRef に基づく認証プロファイル認証情報をサポートしません。 +- 静的ランタイム認証情報は、メモリ内の解決済みスナップショットから取得されます。レガシーの静的 `auth.json` エントリは、検出時に削除されます。 +- レガシー OAuth は `~/.openclaw/credentials/oauth.json` からインポートされます。 - [OAuth](/ja-JP/concepts/oauth) を参照してください。 - シークレットのランタイム動作と `audit/configure/apply` ツール: [シークレット管理](/ja-JP/gateway/secrets)。 @@ -827,25 +828,22 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`: プロファイルが真の - billing/insufficient-credit エラーで失敗した場合の、時間単位の基本バックオフ（デフォルト: `5`）。明示的な請求関連テキストは - `401`/`403` 応答でもここに入ることがありますが、プロバイダー固有のテキスト - マッチャーは、それを所有するプロバイダーにスコープされたままです（たとえば OpenRouter - `Key limit exceeded`）。再試行可能な HTTP `402` の使用枠、または - organization/workspace の支出上限メッセージは、代わりに `rate_limit` パスに - とどまります。 -- `billingBackoffHoursByProvider`: 請求バックオフ時間の、プロバイダーごとの任意の上書き。 -- `billingMaxHours`: 請求バックオフの指数的な増加に対する時間単位の上限（デフォルト: `24`）。 -- `authPermanentBackoffMinutes`: 高信頼度の `auth_permanent` 失敗に対する、分単位の基本バックオフ（デフォルト: `10`）。 -- `authPermanentMaxMinutes`: `auth_permanent` バックオフ増加の分単位の上限（デフォルト: `60`）。 -- `failureWindowHours`: バックオフカウンターに使用される、時間単位のローリングウィンドウ（デフォルト: `24`）。 -- `overloadedProfileRotations`: モデルフォールバックに切り替える前に、過負荷エラーに対して行う同一プロバイダー内の認証プロファイルローテーションの最大数（デフォルト: `1`）。`ModelNotReadyException` などのプロバイダー混雑形状はここに入ります。 -- `overloadedBackoffMs`: 過負荷のプロバイダー/プロファイルローテーションを再試行する前の固定遅延（デフォルト: `0`）。 -- `rateLimitedProfileRotations`: モデルフォールバックに切り替える前に、レート制限エラーに対して行う同一プロバイダー内の認証プロファイルローテーションの最大数（デフォルト: `1`）。そのレート制限バケットには、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` などのプロバイダー由来のテキストが含まれます。 +- `billingBackoffHours`: 実際の + billing/insufficient-credit エラーによりプロファイルが失敗したときの、時間単位の基本バックオフ (デフォルト: `5`)。明示的な請求関連テキストは、`401`/`403` 応答でもここに分類されることがありますが、プロバイダー固有のテキストマッチャーは、それを所有するプロバイダーのスコープに留まります (たとえば OpenRouter の + `Key limit exceeded`)。再試行可能な HTTP `402` の使用ウィンドウまたは + 組織/ワークスペースの利用上限メッセージは、代わりに `rate_limit` パスに留まります。 +- `billingBackoffHoursByProvider`: プロバイダーごとの請求バックオフ時間を上書きする任意設定。 +- `billingMaxHours`: 請求バックオフの指数的増加に対する時間単位の上限 (デフォルト: `24`)。 +- `authPermanentBackoffMinutes`: 信頼度の高い `auth_permanent` 失敗に対する分単位の基本バックオフ (デフォルト: `10`)。 +- `authPermanentMaxMinutes`: `auth_permanent` バックオフ増加に対する分単位の上限 (デフォルト: `60`)。 +- `failureWindowHours`: バックオフカウンターに使用される時間単位のローリングウィンドウ (デフォルト: `24`)。 +- `overloadedProfileRotations`: モデルフォールバックに切り替える前に許可される、過負荷エラーに対する同一プロバイダー内の auth-profile ローテーション最大回数 (デフォルト: `1`)。`ModelNotReadyException` などのプロバイダー混雑形状はここに分類されます。 +- `overloadedBackoffMs`: 過負荷のプロバイダー/プロファイルローテーションを再試行する前の固定遅延 (デフォルト: `0`)。 +- `rateLimitedProfileRotations`: モデルフォールバックに切り替える前に許可される、レート制限エラーに対する同一プロバイダー内の auth-profile ローテーション最大回数 (デフォルト: `1`)。このレート制限バケットには、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` などのプロバイダー形式のテキストが含まれます。 --- -## ログ記録 +## ロギング ```json5 { @@ -862,9 +860,9 @@ openclaw gateway --port 19001 - デフォルトのログファイル: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 安定したパスにするには `logging.file` を設定します。 -- `consoleLevel` は `--verbose` 時に `debug` に引き上げられます。 -- `maxFileBytes`: ローテーション前のアクティブなログファイルの最大サイズ（バイト単位、正の整数、デフォルト: `104857600` = 100 MB）。OpenClaw はアクティブファイルの横に、番号付きアーカイブを最大 5 個保持します。 -- `redactSensitive` / `redactPatterns`: コンソール出力、ファイルログ、OTLP ログレコード、永続化されたセッショントランスクリプトテキストに対するベストエフォートのマスク処理。`redactSensitive: "off"` は、この一般的なログ/トランスクリプトポリシーのみを無効にします。UI/ツール/診断の安全面では、送出前に引き続きシークレットを編集します。 +- `--verbose` の場合、`consoleLevel` は `debug` に引き上げられます。 +- `maxFileBytes`: ローテーション前のアクティブログファイルの最大サイズ (バイト単位、正の整数、デフォルト: `104857600` = 100 MB)。OpenClaw はアクティブファイルの横に番号付きアーカイブを最大 5 件保持します。 +- `redactSensitive` / `redactPatterns`: コンソール出力、ファイルログ、OTLP ログレコード、永続化されたセッショントランスクリプトテキストに対するベストエフォートのマスキング。`redactSensitive: "off"` はこの一般的なログ/トランスクリプトポリシーのみを無効化します。UI/ツール/診断の安全性サーフェスでは、送出前に引き続きシークレットが秘匿されます。 --- @@ -912,25 +910,25 @@ openclaw gateway --port 19001 } ``` -- `enabled`: インストルメンテーション出力のマスタートグル（デフォルト: `true`）。 -- `flags`: 対象を絞ったログ出力を有効にするフラグ文字列の配列（`"telegram.*"` や `"*"` などのワイルドカードをサポート）。 -- `stuckSessionWarnMs`: 長時間実行中の処理セッションを `session.long_running`、`session.stalled`、または `session.stuck` と分類するための、進捗なし経過時間のしきい値（ms 単位）。返信、ツール、ステータス、ブロック、ACP 進捗によりタイマーはリセットされます。繰り返される `session.stuck` 診断は、変化がない間バックオフします。 -- `otel.enabled`: OpenTelemetry エクスポートパイプラインを有効にします（デフォルト: `false`）。完全な設定、シグナルカタログ、プライバシーモデルについては、[OpenTelemetry エクスポート](/ja-JP/gateway/opentelemetry)を参照してください。 +- `enabled`: インストルメンテーション出力のマスタートグル (デフォルト: `true`)。 +- `flags`: 対象を絞ったログ出力を有効にするフラグ文字列の配列 (`"telegram.*"` や `"*"` などのワイルドカードをサポート)。 +- `stuckSessionWarnMs`: 長時間実行中の処理セッションを `session.long_running`、`session.stalled`、または `session.stuck` として分類するための、進行なし経過時間のしきい値 (ms)。返信、ツール、ステータス、ブロック、ACP の進行はタイマーをリセットします。繰り返し発生する `session.stuck` 診断は、未変更の間バックオフします。 +- `otel.enabled`: OpenTelemetry エクスポートパイプラインを有効にします (デフォルト: `false`)。完全な設定、シグナルカタログ、プライバシーモデルについては、[OpenTelemetry エクスポート](/ja-JP/gateway/opentelemetry)を参照してください。 - `otel.endpoint`: OTel エクスポート用のコレクター URL。 - `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: 任意のシグナル固有 OTLP エンドポイント。設定すると、そのシグナルについてのみ `otel.endpoint` を上書きします。 -- `otel.protocol`: `"http/protobuf"`（デフォルト）または `"grpc"`。 +- `otel.protocol`: `"http/protobuf"` (デフォルト) または `"grpc"`。 - `otel.headers`: OTel エクスポートリクエストとともに送信される追加の HTTP/gRPC メタデータヘッダー。 - `otel.serviceName`: リソース属性のサービス名。 - `otel.traces` / `otel.metrics` / `otel.logs`: トレース、メトリクス、またはログのエクスポートを有効にします。 -- `otel.sampleRate`: トレースサンプリング率 `0`–`1`。 -- `otel.flushIntervalMs`: 定期的なテレメトリフラッシュ間隔（ms 単位）。 -- `otel.captureContent`: OTEL span 属性への未加工コンテンツキャプチャをオプトインします。デフォルトはオフです。ブール値 `true` は、システム以外のメッセージ/ツールコンテンツをキャプチャします。オブジェクト形式では、`inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs`、`systemPrompt` を明示的に有効にできます。 -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: 最新の実験的 GenAI span プロバイダー属性用の環境トグル。デフォルトでは、互換性のため span は従来の `gen_ai.system` 属性を保持します。GenAI メトリクスは境界付きのセマンティック属性を使用します。 -- `OPENCLAW_OTEL_PRELOADED=1`: グローバル OpenTelemetry SDK をすでに登録しているホスト用の環境トグル。これにより OpenClaw は、診断リスナーをアクティブに保ったまま、Plugin 所有の SDK 起動/シャットダウンをスキップします。 +- `otel.sampleRate`: トレースサンプリングレート `0`〜`1`。 +- `otel.flushIntervalMs`: 定期的なテレメトリフラッシュ間隔 (ms)。 +- `otel.captureContent`: OTEL span 属性への生コンテンツ取得をオプトインします。デフォルトはオフです。ブール値 `true` は非システムのメッセージ/ツールコンテンツを取得します。オブジェクト形式では、`inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs`、`systemPrompt` を明示的に有効にできます。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: 最新の実験的 GenAI span プロバイダー属性のための環境トグル。デフォルトでは、互換性のため span は従来の `gen_ai.system` 属性を保持します。GenAI メトリクスは境界付きセマンティック属性を使用します。 +- `OPENCLAW_OTEL_PRELOADED=1`: グローバル OpenTelemetry SDK をすでに登録しているホストのための環境トグル。OpenClaw は診断リスナーを有効に保ったまま、Plugin 所有の SDK 起動/シャットダウンをスキップします。 - `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`、`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: 対応する設定キーが未設定の場合に使用される、シグナル固有のエンドポイント環境変数。 -- `cacheTrace.enabled`: 埋め込み実行用にキャッシュトレーススナップショットをログ出力します（デフォルト: `false`）。 -- `cacheTrace.filePath`: キャッシュトレース JSONL の出力パス（デフォルト: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: キャッシュトレース出力に含める内容を制御します（すべてデフォルト: `true`）。 +- `cacheTrace.enabled`: 埋め込み実行用のキャッシュトレーススナップショットをログに記録します (デフォルト: `false`)。 +- `cacheTrace.filePath`: キャッシュトレース JSONL の出力パス (デフォルト: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`)。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: キャッシュトレース出力に含める内容を制御します (すべてのデフォルト: `true`)。 --- @@ -952,12 +950,12 @@ openclaw gateway --port 19001 } ``` -- `channel`: npm/git インストール用のリリースチャンネル — `"stable"`、`"beta"`、または `"dev"`。 -- `checkOnStart`: Gateway 起動時に npm 更新を確認します（デフォルト: `true`）。 -- `auto.enabled`: パッケージインストールのバックグラウンド自動更新を有効にします（デフォルト: `false`）。 -- `auto.stableDelayHours`: stable チャンネルで自動適用する前の最小遅延時間（時間単位、デフォルト: `6`、最大: `168`）。 -- `auto.stableJitterHours`: stable チャンネルのロールアウトを分散する追加ウィンドウ（時間単位、デフォルト: `12`、最大: `168`）。 -- `auto.betaCheckIntervalHours`: beta チャンネルの確認を実行する頻度（時間単位、デフォルト: `1`、最大: `24`）。 +- `channel`: npm/git インストールのリリースチャンネル — `"stable"`、`"beta"`、または `"dev"`。 +- `checkOnStart`: Gateway 起動時に npm 更新を確認します (デフォルト: `true`)。 +- `auto.enabled`: パッケージインストールのバックグラウンド自動更新を有効にします (デフォルト: `false`)。 +- `auto.stableDelayHours`: stable チャンネルの自動適用前の最小遅延時間 (デフォルト: `6`、最大: `168`)。 +- `auto.stableJitterHours`: stable チャンネルのロールアウトを分散する追加ウィンドウ時間 (デフォルト: `12`、最大: `168`)。 +- `auto.betaCheckIntervalHours`: beta チャンネルの確認を実行する頻度 (時間単位、デフォルト: `1`、最大: `24`)。 --- @@ -990,23 +988,23 @@ openclaw gateway --port 19001 } ``` -- `enabled`: グローバルな ACP 機能ゲート（デフォルト: `true`。ACP dispatch と spawn の操作要素を隠すには `false` に設定）。 -- `dispatch.enabled`: ACP セッションターン dispatch の独立ゲート（デフォルト: `true`）。ACP コマンドを利用可能にしたまま実行をブロックするには `false` に設定します。 -- `backend`: デフォルトの ACP ランタイムバックエンド ID（登録済み ACP ランタイム Plugin と一致している必要があります）。 - 先にバックエンド Plugin をインストールし、`plugins.allow` が設定されている場合は、バックエンド Plugin ID（例: `acpx`）を含めてください。含めないと ACP バックエンドは読み込まれません。 -- `defaultAgent`: spawn が明示的なターゲットを指定しない場合の、フォールバック ACP ターゲットエージェント ID。 -- `allowedAgents`: ACP ランタイムセッションに許可されるエージェント ID の許可リスト。空の場合、追加の制限はありません。 +- `enabled`: グローバル ACP 機能ゲート (デフォルト: `true`、ACP dispatch と spawn affordance を非表示にするには `false` を設定)。 +- `dispatch.enabled`: ACP セッションターン dispatch の独立したゲート (デフォルト: `true`)。ACP コマンドを利用可能なまま実行をブロックするには `false` を設定します。 +- `backend`: デフォルトの ACP ランタイムバックエンド id (登録済み ACP ランタイム Plugin と一致する必要があります)。 + 先にバックエンド Plugin をインストールし、`plugins.allow` が設定されている場合は、バックエンド Plugin id (たとえば `acpx`) を含めてください。含めない場合、ACP バックエンドは読み込まれません。 +- `defaultAgent`: spawn が明示的なターゲットを指定しない場合の、フォールバック ACP ターゲット agent id。 +- `allowedAgents`: ACP ランタイムセッションで許可される agent id の許可リスト。空の場合は追加の制限なしを意味します。 - `maxConcurrentSessions`: 同時にアクティブにできる ACP セッションの最大数。 -- `stream.coalesceIdleMs`: ストリームテキストのアイドルフラッシュウィンドウ（ms 単位）。 -- `stream.maxChunkChars`: ストリームブロック投影を分割する前の最大チャンクサイズ。 -- `stream.repeatSuppression`: ターンごとに繰り返されるステータス/ツール行を抑制します（デフォルト: `true`）。 +- `stream.coalesceIdleMs`: ストリーミングテキストのアイドル時フラッシュウィンドウ (ms)。 +- `stream.maxChunkChars`: ストリーミングブロック投影を分割する前の最大チャンクサイズ。 +- `stream.repeatSuppression`: ターンごとの繰り返しステータス/ツール行を抑制します (デフォルト: `true`)。 - `stream.deliveryMode`: `"live"` は逐次ストリーミングし、`"final_only"` はターン終端イベントまでバッファします。 -- `stream.hiddenBoundarySeparator`: 非表示ツールイベントの後に表示テキストが続く場合の区切り文字（デフォルト: `"paragraph"`）。 -- `stream.maxOutputChars`: ACP ターンごとに投影されるアシスタント出力文字数の最大値。 +- `stream.hiddenBoundarySeparator`: 非表示ツールイベント後の可視テキスト前に置く区切り (デフォルト: `"paragraph"`)。 +- `stream.maxOutputChars`: ACP ターンごとに投影される assistant 出力文字数の最大値。 - `stream.maxSessionUpdateChars`: 投影される ACP ステータス/更新行の最大文字数。 -- `stream.tagVisibility`: ストリームイベントに対する、タグ名からブール値の可視性上書きへのレコード。 -- `runtime.ttlMinutes`: ACP セッションワーカーがクリーンアップ対象になるまでのアイドル TTL（分単位）。 -- `runtime.installCommand`: ACP ランタイム環境をブートストラップするときに実行する任意のインストールコマンド。 +- `stream.tagVisibility`: ストリーミングイベントに対するタグ名からブール値の可視性上書きへのレコード。 +- `runtime.ttlMinutes`: ACP セッションワーカーがクリーンアップ対象になるまでのアイドル TTL (分単位)。 +- `runtime.installCommand`: ACP ランタイム環境のブートストラップ時に実行する任意のインストールコマンド。 --- @@ -1022,17 +1020,17 @@ openclaw gateway --port 19001 } ``` -- `cli.banner.taglineMode` はバナータグラインのスタイルを制御します: - - `"random"`（デフォルト）: ローテーションするユーモア/季節のタグライン。 - - `"default"`: 固定の中立的なタグライン（`All your chats, one OpenClaw.`）。 - - `"off"`: タグラインテキストなし（バナータイトル/バージョンは引き続き表示）。 -- タグラインだけでなくバナー全体を非表示にするには、環境変数 `OPENCLAW_HIDE_BANNER=1` を設定します。 +- `cli.banner.taglineMode` はバナーのタグラインスタイルを制御します: + - `"random"` (デフォルト): 面白い/季節的なタグラインをローテーションします。 + - `"default"`: 固定の中立的なタグライン (`All your chats, one OpenClaw.`)。 + - `"off"`: タグラインテキストなし (バナーのタイトル/バージョンは引き続き表示されます)。 +- バナー全体を非表示にするには (タグラインだけではなく)、環境変数 `OPENCLAW_HIDE_BANNER=1` を設定します。 --- ## ウィザード -CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doctor`）によって書き込まれるメタデータ: +CLI のガイド付きセットアップフロー (`onboard`、`configure`、`doctor`) によって書き込まれるメタデータ: ```json5 { @@ -1048,15 +1046,15 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct --- -## ID +## アイデンティティ -[エージェントデフォルト](/ja-JP/gateway/config-agents#agent-defaults)の `agents.list` ID フィールドを参照してください。 +[Agent デフォルト](/ja-JP/gateway/config-agents#agent-defaults)の下にある `agents.list` identity フィールドを参照してください。 --- -## ブリッジ（レガシー、削除済み） +## ブリッジ (レガシー、削除済み) -現在のビルドには TCP ブリッジは含まれなくなりました。Node は Gateway WebSocket 経由で接続します。`bridge.*` キーは設定スキーマの一部ではなくなりました（削除されるまで検証は失敗します。`openclaw doctor --fix` で不明なキーを取り除けます）。 +現在のビルドには TCP ブリッジは含まれていません。Node は Gateway WebSocket 経由で接続します。`bridge.*` キーは設定スキーマの一部ではなくなりました (削除されるまで検証は失敗します。`openclaw doctor --fix` で未知のキーを取り除けます)。 @@ -1096,11 +1094,11 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct } ``` -- `sessionRetention`: 完了した分離 cron 実行セッションを `sessions.json` から削除する前に保持する期間。削除済み cron トランスクリプトのアーカイブのクリーンアップも制御します。デフォルト: `24h`。無効にするには `false` に設定します。 -- `runLog.maxBytes`: プルーニング前の実行ログファイル（`cron/runs/.jsonl`）ごとの最大サイズ。デフォルト: `2_000_000` バイト。 -- `runLog.keepLines`: 実行ログのプルーニングがトリガーされたときに保持される最新行数。デフォルト: `2000`。 -- `webhookToken`: cron Webhook POST 配信（`delivery.mode = "webhook"`）に使用される bearer token。省略した場合、認証ヘッダーは送信されません。 -- `webhook`: 非推奨のレガシーフォールバック Webhook URL（http/https）。まだ `notify: true` を持つ保存済みジョブにのみ使用されます。 +- `sessionRetention`: 完了した分離 Cron 実行セッションを `sessions.json` から刈り込むまで保持する期間。削除済み Cron トランスクリプトのアーカイブのクリーンアップも制御します。デフォルト: `24h`。無効化するには `false` を設定します。 +- `runLog.maxBytes`: 刈り込み前の実行ログファイル (`cron/runs/.jsonl`) ごとの最大サイズ。デフォルト: `2_000_000` バイト。 +- `runLog.keepLines`: 実行ログの刈り込みがトリガーされたときに保持される最新行数。デフォルト: `2000`。 +- `webhookToken`: Cron Webhook POST 配信 (`delivery.mode = "webhook"`) に使用される bearer token。省略した場合、auth ヘッダーは送信されません。 +- `webhook`: まだ `notify: true` を持つ保存済みジョブにのみ使用される、非推奨のレガシーフォールバック Webhook URL (http/https)。 ### `cron.retry` @@ -1116,11 +1114,11 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct } ``` -- `maxAttempts`: 一時的なエラーで単発ジョブを再試行する最大回数 (デフォルト: `3`; 範囲: `0`–`10`)。 -- `backoffMs`: 各再試行のバックオフ遅延を ms で指定する配列 (デフォルト: `[30000, 60000, 300000]`; 1–10 個のエントリ)。 +- `maxAttempts`: 一時的なエラーでの単発ジョブに対する最大再試行回数（デフォルト: `3`、範囲: `0`–`10`）。 +- `backoffMs`: 各再試行に対するバックオフ遅延の配列（ミリ秒）（デフォルト: `[30000, 60000, 300000]`、1～10個のエントリ）。 - `retryOn`: 再試行をトリガーするエラー種別 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略すると、すべての一時的な種別を再試行します。 -単発の cron ジョブにのみ適用されます。繰り返しジョブでは別の失敗処理を使用します。 +単発のcronジョブにのみ適用されます。繰り返しジョブは別の失敗処理を使用します。 ### `cron.failureAlert` @@ -1139,12 +1137,12 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct } ``` -- `enabled`: cron ジョブの失敗アラートを有効にします (デフォルト: `false`)。 -- `after`: アラートを発火するまでの連続失敗回数 (正の整数、最小: `1`)。 -- `cooldownMs`: 同じジョブでアラートを繰り返す間隔の最小ミリ秒数 (非負整数)。 -- `includeSkipped`: 連続してスキップされた実行をアラートしきい値にカウントします (デフォルト: `false`)。スキップされた実行は別個に追跡され、実行エラーのバックオフには影響しません。 -- `mode`: 配信モード — `"announce"` はチャンネルメッセージで送信します。`"webhook"` は設定済みの Webhook に投稿します。 -- `accountId`: アラート配信のスコープにする任意のアカウントまたはチャンネル ID。 +- `enabled`: cronジョブの失敗アラートを有効にします（デフォルト: `false`）。 +- `after`: アラートが発火するまでの連続失敗回数（正の整数、最小: `1`）。 +- `cooldownMs`: 同じジョブに対する繰り返しアラート間の最小ミリ秒数（非負の整数）。 +- `includeSkipped`: 連続してスキップされた実行をアラートしきい値にカウントします（デフォルト: `false`）。スキップされた実行は別途追跡され、実行エラーのバックオフには影響しません。 +- `mode`: 配信モード — `"announce"` はチャンネルメッセージで送信します。`"webhook"` は設定されたWebhookに投稿します。 +- `accountId`: アラート配信のスコープを絞るための任意のアカウントまたはチャンネルID。 ### `cron.failureDestination` @@ -1161,49 +1159,49 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct } ``` -- すべてのジョブにまたがる cron 失敗通知のデフォルト宛先。 -- `mode`: `"announce"` または `"webhook"`。十分なターゲットデータが存在する場合は、デフォルトで `"announce"` になります。 -- `channel`: announce 配信用のチャンネル上書き。`"last"` は最後に確認された配信チャンネルを再利用します。 -- `to`: 明示的な announce ターゲットまたは Webhook URL。webhook モードでは必須です。 -- `accountId`: 配信用の任意のアカウント上書き。 +- すべてのジョブに対するcron失敗通知のデフォルト宛先です。 +- `mode`: `"announce"` または `"webhook"`。十分なターゲットデータがある場合はデフォルトで `"announce"` になります。 +- `channel`: announce配信のチャンネル上書きです。`"last"` は最後に確認された配信チャンネルを再利用します。 +- `to`: 明示的なannounceターゲットまたはWebhook URLです。Webhookモードでは必須です。 +- `accountId`: 配信用の任意のアカウント上書きです。 - ジョブごとの `delivery.failureDestination` は、このグローバルデフォルトを上書きします。 -- グローバルにもジョブごとにも失敗宛先が設定されていない場合、すでに `announce` で配信しているジョブは、失敗時にそのプライマリ announce ターゲットへフォールバックします。 +- グローバルまたはジョブごとの失敗宛先がどちらも設定されていない場合、すでに `announce` で配信しているジョブは、失敗時にそのプライマリannounceターゲットへフォールバックします。 - `delivery.failureDestination` は、ジョブのプライマリ `delivery.mode` が `"webhook"` でない限り、`sessionTarget="isolated"` ジョブでのみサポートされます。 -[Cron ジョブ](/ja-JP/automation/cron-jobs)を参照してください。分離された cron 実行は[バックグラウンドタスク](/ja-JP/automation/tasks)として追跡されます。 +[Cronジョブ](/ja-JP/automation/cron-jobs)を参照してください。分離されたcron実行は[バックグラウンドタスク](/ja-JP/automation/tasks)として追跡されます。 --- -## メディアモデルテンプレート変数 +## メディアモデルのテンプレート変数 -Template placeholders は `tools.media.models[].args` で展開されます: +`tools.media.models[].args` で展開されるテンプレートプレースホルダー: -| Variable | Description | +| 変数 | 説明 | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | 受信メッセージ本文全体 | -| `{{RawBody}}` | 生の本文 (履歴/送信者ラッパーなし) | -| `{{BodyStripped}}` | グループメンションを除去した本文 | -| `{{From}}` | 送信者識別子 | -| `{{To}}` | 宛先識別子 | -| `{{MessageSid}}` | チャネルメッセージ ID | -| `{{SessionId}}` | 現在のセッション UUID | -| `{{IsNewSession}}` | 新しいセッションが作成された場合は `"true"` | -| `{{MediaUrl}}` | 受信メディアの疑似 URL | -| `{{MediaPath}}` | ローカルメディアパス | -| `{{MediaType}}` | メディア種別 (image/audio/document/…) | -| `{{Transcript}}` | 音声の文字起こし | -| `{{Prompt}}` | CLI エントリ用に解決されたメディアプロンプト | -| `{{MaxChars}}` | CLI エントリ用に解決された最大出力文字数 | -| `{{ChatType}}` | `"direct"` または `"group"` | -| `{{GroupSubject}}` | グループ件名 (ベストエフォート) | -| `{{GroupMembers}}` | グループメンバーのプレビュー (ベストエフォート) | -| `{{SenderName}}` | 送信者の表示名 (ベストエフォート) | -| `{{SenderE164}}` | 送信者の電話番号 (ベストエフォート) | -| `{{Provider}}` | プロバイダーのヒント (whatsapp, telegram, discord など) | +| `{{Body}}` | 受信メッセージ本文全体 | +| `{{RawBody}}` | 生の本文（履歴/送信者ラッパーなし） | +| `{{BodyStripped}}` | グループメンションを除去した本文 | +| `{{From}}` | 送信者識別子 | +| `{{To}}` | 宛先識別子 | +| `{{MessageSid}}` | チャンネルメッセージID | +| `{{SessionId}}` | 現在のセッションUUID | +| `{{IsNewSession}}` | 新しいセッションが作成された場合は `"true"` | +| `{{MediaUrl}}` | 受信メディアの擬似URL | +| `{{MediaPath}}` | ローカルメディアパス | +| `{{MediaType}}` | メディア種別（image/audio/document/…） | +| `{{Transcript}}` | 音声トランスクリプト | +| `{{Prompt}}` | CLIエントリ用に解決されたメディアプロンプト | +| `{{MaxChars}}` | CLIエントリ用に解決された最大出力文字数 | +| `{{ChatType}}` | `"direct"` または `"group"` | +| `{{GroupSubject}}` | グループ件名（ベストエフォート） | +| `{{GroupMembers}}` | グループメンバーのプレビュー（ベストエフォート） | +| `{{SenderName}}` | 送信者の表示名（ベストエフォート） | +| `{{SenderE164}}` | 送信者の電話番号（ベストエフォート） | +| `{{Provider}}` | プロバイダーヒント（whatsapp、telegram、discordなど） | --- -## 設定のインクルード (`$include`) +## 設定インクルード（`$include`） 設定を複数のファイルに分割します: @@ -1221,13 +1219,13 @@ Template placeholders は `tools.media.models[].args` で展開されます: **マージ動作:** - 単一ファイル: 含んでいるオブジェクトを置き換えます。 -- ファイル配列: 順番にディープマージされます (後のものが前のものを上書きします)。 -- 兄弟キー: インクルード後にマージされます (インクルードされた値を上書きします)。 -- ネストしたインクルード: 最大 10 階層までです。 -- パス: インクルード元ファイルからの相対パスとして解決されますが、トップレベル設定ディレクトリ (`openclaw.json` の `dirname`) の内側に留まる必要があります。絶対パス/`../` 形式は、その境界内に解決される場合にのみ許可されます。 -- OpenClaw 所有の書き込みで、単一ファイルインクルードに裏付けられた 1 つのトップレベルセクションだけを変更するものは、そのインクルード先ファイルへ書き込まれます。たとえば、`plugins install` は `plugins: { $include: "./plugins.json5" }` を `plugins.json5` 内で更新し、`openclaw.json` は変更しません。 -- ルートインクルード、インクルード配列、兄弟上書きを持つインクルードは、OpenClaw 所有の書き込みでは読み取り専用です。そのような書き込みは、設定をフラット化する代わりに安全側に失敗します。 -- エラー: 欠落ファイル、解析エラー、循環インクルードに対して明確なメッセージを表示します。 +- ファイルの配列: 順番に深くマージされます（後のものが前のものを上書きします）。 +- 兄弟キー: インクルード後にマージされます（インクルードされた値を上書きします）。 +- ネストされたインクルード: 最大10階層まで。 +- パス: インクルード元ファイルからの相対パスとして解決されますが、最上位の設定ディレクトリ（`openclaw.json` の `dirname`）内にとどまる必要があります。絶対パス/`../` 形式は、その境界内に解決される場合にのみ許可されます。 +- 1つのトップレベルセクションのみを変更し、そのセクションが単一ファイルのインクルードに裏付けられているOpenClaw所有の書き込みは、そのインクルード先ファイルへ書き込みます。たとえば、`plugins install` は `plugins: { $include: "./plugins.json5" }` を `plugins.json5` 内で更新し、`openclaw.json` はそのままにします。 +- ルートインクルード、インクルード配列、兄弟上書きを持つインクルードは、OpenClaw所有の書き込みでは読み取り専用です。これらの書き込みは、設定を平坦化するのではなくフェイルクローズします。 +- エラー: ファイルが見つからない場合、解析エラー、循環インクルードに対して明確なメッセージを表示します。 --- diff --git a/docs/ja-JP/gateway/diagnostics.md b/docs/ja-JP/gateway/diagnostics.md index 60e6e892d..d3a3381ab 100644 --- a/docs/ja-JP/gateway/diagnostics.md +++ b/docs/ja-JP/gateway/diagnostics.md @@ -1,22 +1,22 @@ --- read_when: - - バグ報告またはサポート依頼の準備 - - Gateway のクラッシュ、再起動、メモリ圧迫、または過大なペイロードのデバッグ - - 記録またはマスクされる診断データを確認する -summary: バグレポート用の共有可能な Gateway 診断バンドルを作成する + - バグレポートまたはサポート依頼の準備 + - Gateway のクラッシュ、再起動、メモリ負荷、または過大なペイロードのデバッグ + - どの診断データが記録またはマスクされるかを確認する +summary: バグ報告用に共有可能な Gateway 診断バンドルを作成する title: 診断情報のエクスポート x-i18n: - generated_at: "2026-05-03T21:32:15Z" + generated_at: "2026-05-05T01:46:05Z" model: gpt-5.5 provider: openai - source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b + source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382 source_path: gateway/diagnostics.md workflow: 16 --- -OpenClaw は、バグ報告用のローカル診断 zip を作成できます。これには、サニタイズ済みの Gateway ステータス、ヘルス、ログ、設定の形状、最近のペイロードなしの安定性イベントがまとめられます。 +OpenClaw は、バグ報告用のローカル診断 zip を作成できます。これには、サニタイズされた Gateway のステータス、ヘルス、ログ、設定の形状、最近のペイロードを含まない安定性イベントがまとめられます。 -診断バンドルは、確認するまでシークレットと同じように扱ってください。ペイロードや認証情報を省略または秘匿するように設計されていますが、それでもローカル Gateway ログとホストレベルのランタイム状態を要約します。 +診断バンドルは、レビューするまで秘密情報のように扱ってください。ペイロードや認証情報を省略または墨消しするよう設計されていますが、それでもローカル Gateway ログとホストレベルのランタイム状態の概要を含みます。 ## クイックスタート @@ -30,7 +30,7 @@ openclaw gateway diagnostics export openclaw gateway diagnostics export --output openclaw-diagnostics.zip ``` -自動化する場合: +自動化には: ```bash openclaw gateway diagnostics export --json @@ -38,57 +38,59 @@ openclaw gateway diagnostics export --json ## チャットコマンド -オーナーはチャットで `/diagnostics [note]` を使い、ローカル Gateway エクスポートを要求できます。実際の会話でバグが発生し、サポート向けにコピー＆ペースト可能なレポートを 1 つ用意したい場合に使います。 +所有者はチャットで `/diagnostics [note]` を使い、ローカル Gateway のエクスポートを要求できます。実際の会話でバグが発生し、サポート向けにコピー＆ペースト可能なレポートを 1 つ用意したい場合に使います。 1. 問題に気づいた会話で `/diagnostics` を送信します。役立つ場合は、たとえば `/diagnostics bad tool choice` のように短いメモを追加します。 -2. OpenClaw は診断の前文を送信し、明示的な exec 承認を 1 回求めます。この承認により `openclaw gateway diagnostics export --json` が実行されます。allow-all ルールで診断を承認しないでください。 -3. 承認後、OpenClaw はローカルバンドルのパス、マニフェスト概要、プライバシーメモ、関連するセッション ID を含む、貼り付け可能なレポートを返します。 +2. OpenClaw は診断の前置きを送信し、明示的な exec 承認を 1 回求めます。この承認により `openclaw gateway diagnostics export --json` が実行されます。allow-all ルールで診断を承認しないでください。 +3. 承認後、OpenClaw はローカルバンドルパス、マニフェスト概要、プライバシーに関する注記、関連するセッション ID を含む、貼り付け可能なレポートで返信します。 -グループチャットでもオーナーは `/diagnostics` を実行できますが、OpenClaw は診断の詳細を共有チャットには投稿しません。前文、承認プロンプト、Gateway エクスポート結果、Codex セッション/スレッドの内訳は、プライベート承認経路を通じてオーナーに送信されます。グループには、診断フローが非公開で送信されたという短い通知だけが届きます。OpenClaw がオーナーへのプライベート経路を見つけられない場合、コマンドは安全側に失敗し、DM から実行するようオーナーに求めます。 +グループチャットでは、所有者は引き続き `/diagnostics` を実行できますが、OpenClaw は診断の詳細を共有チャットに投稿しません。前置き、承認プロンプト、Gateway エクスポート結果、Codex セッション/スレッドの内訳を、プライベート承認経路を通じて所有者に送信します。グループには、診断フローが非公開で送信されたという短い通知だけが届きます。OpenClaw が所有者へのプライベート経路を見つけられない場合、コマンドは安全側に失敗し、DM から実行するよう所有者に求めます。 -アクティブな OpenClaw セッションがネイティブ OpenAI Codex ハーネスを使用している場合、同じ exec 承認により、OpenClaw が把握している Codex ランタイムスレッドの OpenAI フィードバックアップロードも対象になります。そのアップロードはローカル Gateway zip とは別で、Codex ハーネスセッションの場合にのみ表示されます。承認前に、プロンプトは診断を承認すると Codex フィードバックも送信されることを説明しますが、Codex セッション ID やスレッド ID は列挙しません。承認後、チャット返信には、OpenAI サーバーに送信されたスレッドのチャンネル、OpenClaw セッション ID、Codex スレッド ID、ローカル再開コマンドが一覧表示されます。承認を拒否または無視した場合、OpenClaw はエクスポートを実行せず、Codex フィードバックを送信せず、Codex ID も出力しません。 +アクティブな OpenClaw セッションがネイティブ OpenAI Codex ハーネスを使用している場合、同じ exec 承認は、OpenClaw が把握している Codex ランタイムスレッドの OpenAI フィードバックアップロードも対象にします。このアップロードはローカル Gateway zip とは別であり、Codex ハーネスセッションでのみ表示されます。承認前に、プロンプトは診断を承認すると Codex フィードバックも送信されることを説明しますが、Codex セッション ID やスレッド ID は一覧表示しません。承認後、チャット返信には、OpenAI サーバーへ送信されたスレッドのチャンネル、OpenClaw セッション ID、Codex スレッド ID、ローカル再開コマンドが一覧表示されます。承認を拒否または無視した場合、OpenClaw はエクスポートを実行せず、Codex フィードバックを送信せず、Codex ID も表示しません。 -これにより、一般的な Codex デバッグループは短くなります。Telegram、Discord、または別のチャンネルで不適切な動作に気づいたら、`/diagnostics` を実行し、1 回承認し、レポートをサポートと共有してから、ネイティブ Codex スレッドを自分で調べたい場合は、出力された `codex resume ` コマンドをローカルで実行します。その調査ワークフローについては、[Codex ハーネス](/ja-JP/plugins/codex-harness#inspect-a-codex-thread-from-the-cli)を参照してください。 +これにより、一般的な Codex デバッグループは短くなります。Telegram、Discord、または別のチャンネルで問題のある動作に気づき、`/diagnostics` を実行し、1 回承認し、レポートをサポートと共有し、ネイティブ Codex スレッドを自分で確認したい場合は、出力された `codex resume ` コマンドをローカルで実行します。その確認ワークフローについては、[Codex ハーネス](/ja-JP/plugins/codex-harness#inspect-a-codex-thread-from-the-cli)を参照してください。 -## エクスポートに含まれる内容 +## エクスポートに含まれるもの -zip には以下が含まれます。 +zip には次が含まれます。 - `summary.md`: サポート向けの人間が読める概要。 - `diagnostics.json`: 設定、ログ、ステータス、ヘルス、安定性データの機械可読な概要。 -- `manifest.json`: エクスポートのメタデータとファイル一覧。 -- サニタイズ済みの設定の形状と、シークレットではない設定の詳細。 -- サニタイズ済みのログ概要と、最近の秘匿済みログ行。 -- ベストエフォートの Gateway ステータスとヘルスのスナップショット。 -- `stability/latest.json`: 利用可能な場合、最新の永続化済み安定性バンドル。 +- `manifest.json`: エクスポートメタデータとファイル一覧。 +- サニタイズされた設定の形状と、秘密情報ではない設定詳細。 +- サニタイズされたログ概要と、最近の墨消し済みログ行。 +- ベストエフォートの Gateway ステータスおよびヘルススナップショット。 +- `stability/latest.json`: 利用可能な場合、永続化された最新の安定性バンドル。 -Gateway が異常な状態でも、エクスポートは役立ちます。Gateway がステータスやヘルスリクエストに応答できない場合でも、利用可能であればローカルログ、設定の形状、最新の安定性バンドルが収集されます。 +Gateway が正常でない場合でも、エクスポートは有用です。Gateway がステータスやヘルスリクエストに応答できない場合でも、ローカルログ、設定の形状、最新の安定性バンドルは、利用可能であれば収集されます。 ## プライバシーモデル -診断は共有できるように設計されています。エクスポートには、次のようなデバッグに役立つ運用データが保持されます。 +診断は共有できるように設計されています。エクスポートには、デバッグに役立つ運用データが保持されます。例: -- サブシステム名、plugin ID、プロバイダー ID、チャンネル ID、設定済みモード -- ステータスコード、所要時間、バイト数、キュー状態、メモリ読み取り値 -- サニタイズ済みのログメタデータと、秘匿済みの運用メッセージ -- 設定の形状と、シークレットではない機能設定 +- サブシステム名、Plugin ID、プロバイダー ID、チャンネル ID、設定済みモード +- ステータスコード、期間、バイト数、キュー状態、メモリ読み取り値 +- サニタイズされたログメタデータと、墨消しされた運用メッセージ +- 設定の形状と、秘密情報ではない機能設定 -エクスポートでは、以下が省略または秘匿されます。 +エクスポートでは、次が省略または墨消しされます。 -- チャット本文、プロンプト、指示、webhook 本文、ツール出力 -- 認証情報、API キー、トークン、Cookie、シークレット値 +- チャットテキスト、プロンプト、指示、Webhook 本文、ツール出力 +- 認証情報、API キー、トークン、Cookie、秘密値 - 生のリクエスト本文またはレスポンス本文 - アカウント ID、メッセージ ID、生のセッション ID、ホスト名、ローカルユーザー名 -ログメッセージがユーザー、チャット、プロンプト、またはツールのペイロードテキストのように見える場合、エクスポートにはメッセージが省略されたこととバイト数だけが保持されます。 +ログメッセージがユーザー、チャット、プロンプト、またはツールのペイロードテキストのように見える場合、エクスポートにはメッセージが省略されたこととバイト数のみが保持されます。 ## 安定性レコーダー -Gateway は、診断が有効な場合、デフォルトで境界付きのペイロードなし安定性ストリームを記録します。これはコンテンツではなく、運用上の事実のためのものです。 +Gateway は、診断が有効な場合、デフォルトで境界付きのペイロードを含まない安定性ストリームを記録します。これは運用上の事実のためのものであり、コンテンツのためのものではありません。 -同じ診断 Heartbeat は、Gateway は稼働し続けているが Node.js イベントループまたは CPU が飽和しているように見える場合に、稼働状態サンプルを記録します。これらの `diagnostic.liveness.warning` イベントには、イベントループ遅延、イベントループ使用率、CPU コア比率、アクティブ/待機中/キュー内のセッション数が含まれます。アイドルサンプルは `info` レベルのテレメトリに残ります。稼働状態サンプルは、作業が待機中またはキュー内の場合、またはアクティブな作業が継続的なイベントループ遅延と重なる場合にのみ Gateway 警告になります。それ以外は正常なバックグラウンド作業中の一時的な最大遅延スパイクは、デバッグログに残ります。それ自体で Gateway を再起動することはありません。 +同じ診断 Heartbeat は、Gateway が稼働し続けている一方で Node.js イベントループまたは CPU が飽和しているように見える場合に、liveness サンプルを記録します。これらの `diagnostic.liveness.warning` イベントには、イベントループ遅延、イベントループ使用率、CPU コア比率、アクティブ/待機中/キュー内のセッション数、既知の場合は現在の起動/ランタイムフェーズ、最近のフェーズ期間、境界付きのアクティブ/キュー内作業ラベルが含まれます。アイドルサンプルは `info` レベルのテレメトリに残ります。liveness サンプルは、作業が待機中またはキュー内にある場合、またはアクティブな作業が継続的なイベントループ遅延と重なる場合にのみ Gateway 警告になります。それ以外は正常なバックグラウンド作業中の一時的な最大遅延スパイクは、デバッグログに残ります。それ自体で Gateway を再起動することはありません。 -ライブレコーダーを調べるには: +起動フェーズも、ウォールクロック時間と CPU タイミングを含む `diagnostic.phase.completed` イベントを発行します。停止した embedded-run 診断は、最後のブリッジ進行状況が生のレスポンス項目やレスポンス完了イベントなどの終端に見えたにもかかわらず、Gateway がまだ埋め込み実行をアクティブと見なしている場合に `terminalProgressStale=true` を設定します。 + +ライブレコーダーを確認します。 ```bash openclaw gateway stability @@ -96,19 +98,19 @@ openclaw gateway stability --type payload.large openclaw gateway stability --json ``` -致命的終了、シャットダウンタイムアウト、または再起動時の起動失敗後に、最新の永続化済み安定性バンドルを調べるには: +致命的終了、シャットダウンタイムアウト、または再起動時の起動失敗の後、永続化された最新の安定性バンドルを確認します。 ```bash openclaw gateway stability --bundle latest ``` -最新の永続化済みバンドルから診断 zip を作成するには: +永続化された最新バンドルから診断 zip を作成します。 ```bash openclaw gateway stability --bundle latest --export ``` -永続化済みバンドルは、イベントが存在する場合 `~/.openclaw/logs/stability/` の下に保存されます。 +イベントが存在する場合、永続化バンドルは `~/.openclaw/logs/stability/` 配下にあります。 ## 便利なオプション @@ -121,17 +123,17 @@ openclaw gateway diagnostics export \ - `--output `: 特定の zip パスに書き込みます。 - `--log-lines `: 含めるサニタイズ済みログ行の最大数。 -- `--log-bytes `: 調べるログバイトの最大数。 -- `--url `: ステータスとヘルスのスナップショット用の Gateway WebSocket URL。 -- `--token `: ステータスとヘルスのスナップショット用の Gateway トークン。 -- `--password `: ステータスとヘルスのスナップショット用の Gateway パスワード。 -- `--timeout `: ステータスとヘルスのスナップショットのタイムアウト。 -- `--no-stability-bundle`: 永続化済み安定性バンドルの検索をスキップします。 +- `--log-bytes `: 検査するログバイトの最大数。 +- `--url `: ステータスおよびヘルススナップショット用の Gateway WebSocket URL。 +- `--token `: ステータスおよびヘルススナップショット用の Gateway トークン。 +- `--password `: ステータスおよびヘルススナップショット用の Gateway パスワード。 +- `--timeout `: ステータスおよびヘルススナップショットのタイムアウト。 +- `--no-stability-bundle`: 永続化された安定性バンドルの検索をスキップします。 - `--json`: 機械可読なエクスポートメタデータを出力します。 -## 診断を無効にする +## 診断を無効化する -診断はデフォルトで有効です。安定性レコーダーと診断イベント収集を無効にするには: +診断はデフォルトで有効です。安定性レコーダーと診断イベント収集を無効化するには: ```json5 { @@ -141,12 +143,12 @@ openclaw gateway diagnostics export \ } ``` -診断を無効にすると、バグ報告の詳細度が下がります。通常の Gateway ログには影響しません。 +診断を無効化すると、バグ報告の詳細が少なくなります。通常の Gateway ロギングには影響しません。 ## 関連 - [ヘルスチェック](/ja-JP/gateway/health) - [Gateway CLI](/ja-JP/cli/gateway#gateway-diagnostics-export) - [Gateway プロトコル](/ja-JP/gateway/protocol#system-and-identity) -- [ログ記録](/ja-JP/logging) +- [ロギング](/ja-JP/logging) - [OpenTelemetry エクスポート](/ja-JP/gateway/opentelemetry) — 診断をコレクターへストリーミングするための別フロー diff --git a/docs/ja-JP/gateway/doctor.md b/docs/ja-JP/gateway/doctor.md index 6402ec5b6..c6b864ca7 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-05-04T09:37:05Z" + generated_at: "2026-05-05T01:46:26Z" model: gpt-5.5 provider: openai - source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798 + source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` は OpenClaw の修復 + 移行ツールです。古い設定や状態を修正し、ヘルスチェックを実行し、実行可能な修復手順を提示します。 +`openclaw doctor` は OpenClaw の修復 + 移行ツールです。古い config/state を修正し、健全性をチェックし、実行可能な修復手順を提示します。 ## クイックスタート @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### ヘッドレスと自動化モード +### ヘッドレスモードと自動化モード @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - プロンプトを表示せずにデフォルトを受け入れます（該当する場合は再起動、サービス、サンドボックスの修復手順も含む）。 + プロンプトなしで既定値を受け入れます（該当する場合は restart/service/sandbox の修復手順を含む）。 @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - プロンプトを表示せずに推奨される修復を適用します（安全な場合は修復 + 再起動）。 + プロンプトなしで推奨修復を適用します（安全な場合は修復 + 再起動）。 @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - 積極的な修復も適用します（カスタム supervisor 設定を上書きします）。 + 強力な修復も適用します（カスタム supervisor config を上書きします）。 @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - プロンプトなしで実行し、安全な移行（設定の正規化 + ディスク上の状態移動）のみを適用します。人間の確認が必要な再起動、サービス、サンドボックスの操作はスキップします。レガシー状態の移行は、検出されると自動的に実行されます。 + プロンプトなしで実行し、安全な移行のみを適用します（config の正規化 + ディスク上の state 移動）。人間の確認が必要な restart/service/sandbox アクションはスキップします。レガシー state 移行は検出時に自動実行されます。 @@ -62,133 +62,130 @@ openclaw doctor openclaw doctor --deep ``` - 追加の Gateway インストール（launchd/systemd/schtasks）についてシステムサービスをスキャンします。 + 追加の Gateway インストール（launchd/systemd/schtasks）を system services でスキャンします。 -書き込む前に変更を確認したい場合は、まず設定ファイルを開いてください。 +書き込む前に変更を確認したい場合は、先に config ファイルを開きます。 ```bash cat ~/.openclaw/openclaw.json ``` -## 実行内容（概要） +## 実行内容（要約） - + - git インストール向けの任意の事前更新（対話時のみ）。 - - UI プロトコルの鮮度チェック（プロトコルスキーマのほうが新しい場合、Control UI を再ビルドします）。 - - ヘルスチェック + 再起動プロンプト。 - - Skills ステータス概要（対象/不足/ブロック）と plugin ステータス。 + - UI プロトコルの鮮度チェック（プロトコルスキーマが新しい場合に Control UI を再ビルド）。 + - 健全性チェック + 再起動プロンプト。 + - Skills ステータス要約（eligible/missing/blocked）と 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 フォールバックジョブ）。 - - レガシーエージェント runtime-policy から `agents.defaults.agentRuntime` と `agents.list[].agentRuntime` への移行。 - - plugin が有効な場合の古い plugin 設定のクリーンアップ。`plugins.enabled=false` の場合、古い plugin 参照は不活性な封じ込め設定として扱われ、保持されます。 + + - レガシー値の config 正規化。 + - レガシーのフラットな `talk.*` フィールドから `talk.provider` + `talk.providers.` への Talk config 移行。 + - レガシー Chrome 拡張機能 config と Chrome MCP 準備状況のブラウザー移行チェック。 + - OpenCode provider override 警告（`models.providers.opencode` / `models.providers.opencode-go`）。 + - Codex OAuth shadowing 警告（`models.providers.openai-codex`）。 + - OpenAI Codex OAuth プロファイル向け OAuth TLS 前提条件チェック。 + - `plugins.allow` は制限的だが tool policy がまだワイルドカードまたは Plugin 所有ツールを要求している場合の Plugin/tool allowlist 警告。 + - レガシーのディスク上 state 移行（sessions/agent dir/WhatsApp auth）。 + - レガシー Plugin manifest contract キー移行（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。 + - レガシー cron store 移行（`jobId`, `schedule.cron`, トップレベルの delivery/payload フィールド、payload `provider`, 単純な `notify: true` webhook fallback jobs）。 + - レガシー agent runtime-policy の `agents.defaults.agentRuntime` と `agents.list[].agentRuntime` への移行。 + - Plugin が有効な場合の古い Plugin config のクリーンアップ。`plugins.enabled=false` の場合、古い Plugin 参照は不活性な containment config として扱われ、保持されます。 - - - セッションロックファイルの検査と古いロックのクリーンアップ。 - - 影響を受けた 2026.4.24 ビルドで作成された重複プロンプト書き換えブランチに対するセッショントランスクリプト修復。 - - 行き詰まったサブエージェントの再起動リカバリー tombstone 検出。古い中止済みリカバリーフラグをクリアして、起動時に子を再起動中止済みとして扱い続けないようにする `--fix` サポート付き。 - - 状態の整合性と権限チェック（セッション、トランスクリプト、状態ディレクトリ）。 - - ローカル実行時の設定ファイル権限チェック（chmod 600）。 - - モデル認証ヘルス: OAuth 有効期限を確認し、期限が近いトークンを更新でき、認証プロファイルのクールダウン/無効状態を報告します。 - - 追加ワークスペースディレクトリの検出（`~/openclaw`）。 + + - Session lock file の検査と古いロックのクリーンアップ。 + - 影響を受けた 2026.4.24 ビルドによって作成された重複 prompt-rewrite branch の session transcript 修復。 + - 詰まった subagent restart-recovery tombstone の検出。startup が child を restart-aborted として扱い続けないよう、古い aborted recovery flag を消去する `--fix` をサポート。 + - State の整合性と権限チェック（sessions、transcripts、state dir）。 + - ローカル実行時の config ファイル権限チェック（chmod 600）。 + - Model auth の健全性: OAuth 期限切れをチェックし、期限が近い token を更新でき、auth-profile の cooldown/disabled state を報告します。 + - 余分な workspace dir の検出（`~/openclaw`）。 - - - サンドボックス化が有効な場合のサンドボックスイメージ修復。 - - レガシーサービス移行と追加 Gateway 検出。 - - Matrix チャンネルのレガシー状態移行（`--fix` / `--repair` モード）。 - - Gateway ランタイムチェック（サービスはインストール済みだが実行されていない、キャッシュ済み launchd ラベル）。 - - チャンネルステータス警告（実行中の gateway からプローブ）。 - - supervisor 設定監査（launchd/systemd/schtasks）と任意の修復。 - - インストールまたは更新中にシェルの `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 値を取り込んだ gateway サービス向けの埋め込みプロキシ環境クリーンアップ。 - - Gateway ランタイムのベストプラクティスチェック（Node と Bun、バージョンマネージャーパス）。 - - Gateway ポート衝突診断（デフォルト `18789`）。 + + - sandboxing が有効な場合の sandbox image 修復。 + - レガシー service 移行と追加 Gateway 検出。 + - Matrix channel のレガシー state 移行（`--fix` / `--repair` モード）。 + - Gateway runtime チェック（service がインストール済みだが実行されていない、cached launchd label）。 + - Channel ステータス警告（実行中の gateway から probe）。 + - 任意修復付き supervisor config audit（launchd/systemd/schtasks）。 + - インストールまたは更新中に shell の `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 値を取り込んだ Gateway services 向けの embedded proxy environment クリーンアップ。 + - Gateway runtime ベストプラクティスチェック（Node と Bun、version-manager paths）。 + - Gateway port collision 診断（既定 `18789`）。 - - - オープン DM ポリシーに関するセキュリティ警告。 - - ローカルトークンモードの Gateway 認証チェック（トークンソースが存在しない場合にトークン生成を提案します。トークン SecretRef 設定は上書きしません）。 - - デバイスペアリングの問題検出（保留中の初回ペアリングリクエスト、保留中のロール/スコープアップグレード、古いローカル device-token キャッシュのドリフト、ペアリング済みレコードの認証ドリフト）。 + + - open DM policies のセキュリティ警告。 + - local token mode の Gateway auth チェック（token source が存在しない場合に token 生成を提案。token SecretRef config は上書きしません）。 + - Device pairing トラブル検出（保留中の初回 pair requests、保留中の role/scope upgrades、古い local device-token cache drift、paired-record auth drift）。 - + - Linux での systemd linger チェック。 - - ワークスペースブートストラップファイルサイズチェック（コンテキストファイルの切り捨て/上限付近の警告）。 - - デフォルトエージェントの Skills 準備状態チェック。不足しているバイナリ、環境、設定、または OS 要件がある許可済み Skills を報告し、`--fix` で利用不可の Skills を `skills.entries` で無効化できます。 - - シェル補完ステータスチェックと自動インストール/アップグレード。 - - メモリ検索埋め込みプロバイダーの準備状態チェック（ローカルモデル、リモート API キー、または QMD バイナリ）。 - - ソースインストールチェック（pnpm ワークスペース不一致、UI アセット不足、tsx バイナリ不足）。 - - 更新済み設定 + ウィザードメタデータを書き込みます。 + - Workspace bootstrap file size チェック（context files の切り詰め/上限付近警告）。 + - 既定 agent の Skills 準備状況チェック。bin、env、config、または OS 要件が不足している許可済み Skills を報告し、`--fix` で `skills.entries` 内の利用不能 Skills を無効化できます。 + - Shell completion ステータスチェックと自動インストール/アップグレード。 + - Memory search embedding provider 準備状況チェック（local model、remote API key、または QMD binary）。 + - Source install チェック（pnpm workspace mismatch、missing UI assets、missing tsx binary）。 + - 更新済み config + ウィザード metadata を書き込みます。 -## Dreams UI バックフィルとリセット +## Dreams UI backfill と reset -Control UI の Dreams シーンには、grounded dreaming ワークフロー向けの **Backfill**、**Reset**、**Clear Grounded** アクションが含まれます。これらのアクションは gateway の doctor スタイルの RPC メソッドを使用しますが、`openclaw doctor` CLI の修復/移行の一部では**ありません**。 +Control UI の Dreams scene には、grounded dreaming workflow 向けの **Backfill**、**Reset**、**Clear Grounded** アクションがあります。これらのアクションは gateway doctor 形式の RPC methods を使いますが、`openclaw doctor` CLI repair/migration の一部では**ありません**。 実行内容: -- **Backfill** は、アクティブなワークスペース内の過去の `memory/YYYY-MM-DD.md` ファイルをスキャンし、grounded REM 日記パスを実行し、可逆的なバックフィルエントリを `DREAMS.md` に書き込みます。 -- **Reset** は、`DREAMS.md` からマークされたバックフィル日記エントリだけを削除します。 -- **Clear Grounded** は、過去の再生から来ていて、まだライブ recall や日次サポートが蓄積されていない、ステージ済みの grounded 専用短期エントリだけを削除します。 +- **Backfill** は active workspace 内の過去の `memory/YYYY-MM-DD.md` ファイルをスキャンし、grounded REM diary pass を実行して、可逆的な backfill entries を `DREAMS.md` に書き込みます。 +- **Reset** は `DREAMS.md` から、それらのマーク済み backfill diary entries のみを削除します。 +- **Clear Grounded** は、historical replay から来た staged grounded-only short-term entries のうち、まだ live recall や daily support が蓄積されていないものだけを削除します。 それ自体では**実行しない**こと: - `MEMORY.md` は編集しません -- doctor 移行全体は実行しません -- ステージ済み CLI パスを明示的に先に実行しない限り、grounded 候補をライブ短期昇格ストアへ自動的にステージしません +- full doctor migrations は実行しません +- staged CLI path を先に明示的に実行しない限り、grounded candidates を live short-term promotion store に自動 stage しません -grounded の過去再生を通常の deep promotion lane に影響させたい場合は、代わりに CLI フローを使用してください。 +grounded historical replay を通常の deep promotion lane に影響させたい場合は、代わりに CLI フローを使います。 ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -これにより、`DREAMS.md` をレビュー面として保持しながら、grounded の永続候補を短期 dreaming ストアへステージします。 +これにより、`DREAMS.md` を review surface として維持しながら、grounded durable candidates を short-term dreaming store に stage します。 ## 詳細な挙動と根拠 - これが git チェックアウトで doctor が対話的に実行されている場合、doctor の実行前に更新（fetch/rebase/build）を提案します。 + これが git checkout で doctor が対話的に実行されている場合、doctor 実行前に更新（fetch/rebase/build）を提案します。 - - 設定にレガシー値の形状（たとえばチャンネル固有の上書きがない `messages.ackReaction`）が含まれる場合、doctor はそれらを現在のスキーマへ正規化します。 + + config にレガシー値の形（たとえば channel-specific override なしの `messages.ackReaction`）が含まれている場合、doctor はそれらを現在のスキーマへ正規化します。 - これにはレガシー Talk のフラットフィールドが含まれます。現在の公開 Talk 設定は `talk.provider` + `talk.providers.` です。Doctor は古い `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` の形状をプロバイダーマップへ書き換えます。 + これにはレガシー Talk のフラットフィールドも含まれます。現在の公開 Talk config は `talk.provider` + `talk.providers.` です。Doctor は古い `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` の形を provider map に書き換えます。 - また doctor は、`plugins.allow` が空でなく、ツールポリシーが - ワイルドカードまたは plugin 所有ツールエントリを使用している場合に警告します。`tools.allow: ["*"]` は実際にロードされた plugin - からのツールにのみ一致します。排他的な plugin - 許可リストをバイパスするものではありません。 + Doctor は、`plugins.allow` が空でなく tool policy がワイルドカードまたは Plugin 所有ツールエントリを使う場合にも警告します。`tools.allow: ["*"]` は、実際に読み込まれる Plugin のツールにのみ一致します。排他的な Plugin allowlist をバイパスするものではありません。Doctor は、移行されたレガシー allowlist config に対して `plugins.bundledDiscovery: "compat"` を書き込み、既存の bundled provider behavior を維持したうえで、より厳格な `"allowlist"` 設定を案内します。 - - 設定に非推奨キーが含まれる場合、他のコマンドは実行を拒否し、`openclaw doctor` の実行を求めます。 + + config に非推奨キーが含まれている場合、他のコマンドは実行を拒否し、`openclaw doctor` の実行を求めます。 - Doctor は次を実行します。 + Doctor は次を行います。 - 見つかったレガシーキーを説明します。 - 適用した移行を表示します。 - 更新済みスキーマで `~/.openclaw/openclaw.json` を書き換えます。 - Gateway も起動時にレガシー設定形式を検出すると doctor 移行を自動実行するため、古い設定は手動介入なしで修復されます。Cron ジョブストア移行は `openclaw doctor --fix` によって処理されます。 + Gateway もレガシー config 形式を検出すると startup 時に doctor migrations を自動実行するため、古い config は手動介入なしで修復されます。Cron job store migrations は `openclaw doctor --fix` によって処理されます。 現在の移行: @@ -196,7 +193,8 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention` - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - - 可視返信ポリシーが欠けている構成済みチャンネル設定 → `messages.groupChat.visibleReplies: "message_tool"` + - `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention` + - 可視返信ポリシーがない設定済みチャネルの設定 → `messages.groupChat.visibleReplies: "message_tool"` - `routing.queue` → `messages.queue` - `routing.bindings` → トップレベルの `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` @@ -214,70 +212,76 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `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.*` → `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 値または未知の enum 値に設定されたプロバイダーも、閉じて失敗するのではなくスキップする） + - `browser.relayBindHost`（レガシー拡張リレー設定）を削除します + - レガシー `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 起動時には、`api` が将来の enum 値や不明な enum 値に設定されているプロバイダーも、フェイルクローズせずにスキップします） - 診断の警告には、複数アカウントチャンネル向けのアカウントデフォルトのガイダンスも含まれる。 + doctor の警告には、マルチアカウントチャネル向けのアカウントデフォルトのガイダンスも含まれます。 - - 2つ以上の `channels..accounts` エントリが、`channels..defaultAccount` または `accounts.default` なしで構成されている場合、診断はフォールバックルーティングが想定外のアカウントを選ぶ可能性があると警告する。 - - `channels..defaultAccount` が未知のアカウント ID に設定されている場合、診断は警告し、構成済みアカウント 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 に強制されたり、コストがゼロになったりする可能性がある。診断は、オーバーライドを削除してモデルごとの API ルーティングとコストを復元できるよう警告する。 + + `models.providers.opencode`、`opencode-zen`、または `opencode-go` を手動で追加している場合、`@mariozechner/pi-ai` の組み込み OpenCode カタログがオーバーライドされます。これにより、モデルが誤った API に割り当てられたり、コストがゼロになったりする可能性があります。doctor は、オーバーライドを削除してモデルごとの API ルーティングとコストを復元できるよう警告します。 - - ブラウザー設定がまだ削除済み Chrome 拡張パスを指している場合、診断はそれを現在のホストローカル 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` プロファイルを使用している場合、ホストローカル 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 未満の場合に警告します + - ブラウザーの inspect ページでリモートデバッグを有効にするよう通知します（例: `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`、または `edge://inspect/#remote-debugging`） - 診断は Chrome 側の設定を有効化できない。ホストローカル Chrome MCP には引き続き次が必要になる。 + doctor が Chrome 側の設定を有効にすることはできません。ホストローカル Chrome MCP には引き続き次が必要です。 - - gateway/node ホスト上の Chromium ベースブラウザー 144+ - - ブラウザーがローカルで実行中であること - - そのブラウザーでリモートデバッグが有効であること + - Gateway/node ホスト上の Chromium ベースブラウザー 144+ + - ローカルで実行中のブラウザー + - そのブラウザーで有効化されたリモートデバッグ - ブラウザーで最初のアタッチ同意プロンプトを承認すること - ここでの準備状況は、ローカルアタッチの前提条件のみを対象とする。Existing-session は現在の Chrome MCP ルート制限を維持する。`responsebody`、PDF エクスポート、ダウンロード傍受、バッチアクションなどの高度なルートには、引き続き管理ブラウザーまたは raw CDP プロファイルが必要になる。 + ここでの準備状況は、ローカルアタッチの前提条件のみを対象とします。Existing-session は現在の Chrome MCP ルート制限を維持します。`responsebody`、PDF エクスポート、ダウンロードインターセプト、バッチアクションのような高度なルートには、引き続き管理ブラウザーまたは raw CDP プロファイルが必要です。 - このチェックは、Docker、サンドボックス、リモートブラウザー、その他のヘッドレスフローには**適用されない**。それらは引き続き raw CDP を使用する。 + このチェックは Docker、sandbox、remote-browser、その他のヘッドレスフローには**適用されません**。それらは引き続き raw CDP を使用します。 - - OpenAI Codex OAuth プロファイルが構成されている場合、診断は OpenAI 認可エンドポイントをプローブして、ローカルの Node/OpenSSL TLS スタックが証明書チェーンを検証できることを確認する。プローブが証明書エラー（例: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、期限切れ証明書、自己署名証明書）で失敗した場合、診断はプラットフォーム固有の修正ガイダンスを出力する。Homebrew Node を使用する macOS では、通常の修正は `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 プロバイダーパスを隠す可能性がある。診断は、Codex OAuth と並んでそれらの古いトランスポート設定を検出した場合に警告し、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を取り戻せるようにする。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しない。 + + 以前にレガシー OpenAI トランスポート設定を `models.providers.openai-codex` の下に追加していた場合、それらが新しいリリースで自動的に使用される組み込み Codex OAuth プロバイダーパスをシャドーする可能性があります。doctor は、Codex OAuth と並んでそれらの古いトランスポート設定を見つけると警告し、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を取り戻せるようにします。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しません。 - - バンドルされた Codex Plugin が有効な場合、診断は `openai-codex/*` プライマリモデル参照がまだデフォルトの PI ランナー経由で解決されるかどうかも確認する。この組み合わせは、PI 経由で Codex OAuth/サブスクリプション認証を使用したい場合には有効だが、ネイティブ Codex アプリサーバーハーネスと混同しやすい。診断は警告し、明示的なアプリサーバー形状を示す: `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 はこれを自動修復しません。 - - `openai-codex/*` + PI は「通常の OpenClaw ランナー経由で Codex OAuth/サブスクリプション認証を使用する」という意味。 - - `openai/*` + `agentRuntime.id: "codex"` は「埋め込みターンをネイティブ Codex アプリサーバー経由で実行する」という意味。 - - `/codex ...` は「チャットからネイティブ Codex 会話を制御またはバインドする」という意味。 - - `/acp ...` または `runtime: "acp"` は「外部 ACP/acpx アダプターを使用する」という意味。 + - `openai-codex/*` + PI は「通常の OpenClaw ランナー経由で Codex OAuth/サブスクリプション認証を使用する」という意味です。 + - `openai/*` + `agentRuntime.id: "codex"` は「埋め込みターンをネイティブ Codex アプリサーバー経由で実行する」という意味です。 + - `/codex ...` は「チャットからネイティブ Codex 会話を制御またはバインドする」という意味です。 + - `/acp ...` または `runtime: "acp"` は「外部 ACP/acpx アダプターを使用する」という意味です。 - 警告が表示された場合は、意図したルートを選び、設定を手動で編集する。PI Codex OAuth が意図的である場合は、警告をそのまま維持する。 + 警告が表示された場合は、意図したルートを選び、設定を手動で編集してください。PI Codex OAuth が意図した構成である場合は、警告をそのままにします。 - - 診断は古いオンディスクレイアウトを現在の構造へ移行できる。 + + doctor は、設定済みのデフォルト/フォールバックモデルまたはランタイムを Codex のような Plugin 所有ルートから移動した後に、古くなった自動作成ルート状態がないかアクティブセッションストアもスキャンします。 + + `openclaw doctor --fix` は、所有ルートが設定されなくなった場合に、`modelOverrideSource: "auto"` モデルピン、ランタイムモデルメタデータ、固定ハーネス ID、CLI セッションバインディング、自動 auth-profile オーバーライドなど、自動作成された古い状態をクリアできます。明示的なユーザー選択またはレガシーセッションのモデル選択は手動レビュー対象として報告され、そのまま残されます。そのルートをもう意図していない場合は、`/model ...`、`/new` で切り替えるか、セッションをリセットしてください。 + + + + doctor は、古いディスク上レイアウトを現在の構造へ移行できます。 - セッションストア + トランスクリプト: - `~/.openclaw/sessions/` から `~/.openclaw/agents//sessions/` へ @@ -287,209 +291,209 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - レガシー `~/.openclaw/credentials/*.json` から（`oauth.json` を除く） - `~/.openclaw/credentials/whatsapp//...` へ（デフォルトアカウント ID: `default`） - これらの移行はベストエフォートで冪等である。診断は、バックアップとしてレガシーフォルダーを残す場合に警告を出す。Gateway/CLI も起動時にレガシーセッションとエージェントディレクトリを自動移行するため、履歴/認証/モデルは手動の診断実行なしでエージェントごとのパスに配置される。WhatsApp 認証は意図的に `openclaw doctor` 経由でのみ移行される。Talk プロバイダー/プロバイダーマップ正規化は現在、構造的等価性で比較するため、キー順序のみの差分が、何もしない `doctor --fix` 変更を繰り返し発生させることはなくなった。 + これらの移行はベストエフォートで冪等です。doctor は、レガシーフォルダーをバックアップとして残した場合に警告を出します。Gateway/CLI も起動時にレガシーのセッション + エージェントディレクトリを自動移行するため、履歴/認証/モデルは手動で doctor を実行しなくてもエージェントごとのパスに配置されます。WhatsApp 認証は意図的に `openclaw doctor` 経由でのみ移行されます。Talk プロバイダー/プロバイダーマップの正規化は現在、構造的等価性で比較するため、キー順序だけの差分によって `doctor --fix` の no-op 変更が繰り返し発生することはなくなりました。 - - 診断は、インストール済みのすべての Plugin マニフェストをスキャンし、非推奨のトップレベル機能キー（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）を探す。見つかった場合、それらを `contracts` オブジェクトへ移動し、マニフェストファイルをその場で書き換えることを提案する。この移行は冪等である。`contracts` キーにすでに同じ値がある場合、データを重複させずにレガシーキーが削除される。 + + doctor は、インストール済みのすべての Plugin マニフェストをスキャンし、非推奨のトップレベル capability キー（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）を探します。見つかった場合、それらを `contracts` オブジェクトへ移動し、マニフェストファイルをその場で書き換えることを提案します。この移行は冪等です。`contracts` キーにすでに同じ値がある場合、データを重複させずにレガシーキーが削除されます。 - - 診断は、Cron ジョブストア（デフォルトでは `~/.openclaw/cron/jobs.json`、またはオーバーライドされている場合は `cron.store`）についても、スケジューラーが互換性のために引き続き受け入れる古いジョブ形状を確認する。 + + doctor は、cron ジョブストア（デフォルトでは `~/.openclaw/cron/jobs.json`、またはオーバーライドされている場合は `cron.store`）について、スケジューラーが互換性のためにまだ受け付ける古いジョブ形状も確認します。 - 現在の Cron クリーンアップには次が含まれる。 + 現在の cron クリーンアップには次が含まれます。 - `jobId` → `id` - `schedule.cron` → `schedule.expr` - トップレベルのペイロードフィールド（`message`、`model`、`thinking`、...）→ `payload` - トップレベルの配信フィールド（`deliver`、`channel`、`to`、`provider`、...）→ `delivery` - - ペイロード `provider` の配信エイリアス → 明示的な `delivery.channel` - - 単純なレガシー `notify: true` Webhook フォールバックジョブ → `delivery.to=cron.webhook` を伴う明示的な `delivery.mode="webhook"` + - ペイロードの `provider` 配信エイリアス → 明示的な `delivery.channel` + - 単純なレガシー `notify: true` webhook フォールバックジョブ → `delivery.to=cron.webhook` を伴う明示的な `delivery.mode="webhook"` - 診断は、動作を変更せずに実行できる場合にのみ `notify: true` ジョブを自動移行する。ジョブがレガシー通知フォールバックと既存の非 Webhook 配信モードを組み合わせている場合、診断は警告し、そのジョブを手動レビュー用に残す。 + doctor は、動作を変えずに実行できる場合にのみ `notify: true` ジョブを自動移行します。ジョブがレガシー通知フォールバックと既存の非 webhook 配信モードを組み合わせている場合、doctor は警告し、そのジョブを手動レビュー用に残します。 - Linux では、ユーザーの crontab がまだレガシー `~/.openclaw/bin/ensure-whatsapp.sh` を呼び出している場合にも診断が警告する。そのホストローカルスクリプトは現在の OpenClaw では保守されておらず、cron が systemd ユーザーバスに到達できない場合に、誤った `Gateway inactive` メッセージを `~/.openclaw/logs/whatsapp-health.log` へ書き込む可能性がある。古い crontab エントリは `crontab -e` で削除する。現在のヘルスチェックには `openclaw channels status --probe`、`openclaw doctor`、`openclaw gateway status` を使用する。 + Linux では、ユーザーの crontab がまだレガシーの `~/.openclaw/bin/ensure-whatsapp.sh` を呼び出している場合にも doctor が警告します。このホストローカルのスクリプトは現在の OpenClaw では保守されておらず、cron が systemd ユーザーバスに到達できない場合に、誤った `Gateway inactive` メッセージを `~/.openclaw/logs/whatsapp-health.log` に書き込むことがあります。古い crontab エントリは `crontab -e` で削除してください。現在のヘルスチェックには `openclaw channels status --probe`、`openclaw doctor`、`openclaw gateway status` を使用してください。 - 診断機能は、すべてのエージェントセッションディレクトリで古い書き込みロックファイルをスキャンします。これは、セッションが異常終了したときに残されたファイルです。見つかった各ロックファイルについて、パス、PID、その PID がまだ生存しているかどうか、ロックの経過時間、古いと見なされるかどうか（停止した PID または 30 分超）を報告します。`--fix` / `--repair` モードでは、古いロックファイルを自動的に削除します。それ以外の場合は注記を表示し、`--fix` を付けて再実行するよう案内します。 + Doctor は、古い書き込みロックファイル（セッションが異常終了したときに残されたファイル）を各エージェントセッションディレクトリでスキャンします。見つかった各ロックファイルについて、パス、PID、PID がまだ生存しているかどうか、ロックの経過時間、古いと見なされるかどうか（停止した PID または 30 分超）を報告します。`--fix` / `--repair` モードでは、古いロックファイルを自動的に削除します。それ以外の場合は注記を出力し、`--fix` 付きで再実行するよう指示します。 - 診断機能は、2026.4.24 のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形状について、エージェントセッション JSONL ファイルをスキャンします。これは、OpenClaw 内部ランタイムコンテキストを含む放棄されたユーザーターンと、同じ表示ユーザープロンプトを含むアクティブな兄弟ブランチです。`--fix` / `--repair` モードでは、診断機能は影響を受ける各ファイルを元のファイルの隣にバックアップし、トランスクリプトをアクティブなブランチに書き換えるため、gateway 履歴とメモリリーダーに重複ターンが見えなくなります。 + Doctor は、2026.4.24 のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形状について、エージェントセッションの JSONL ファイルをスキャンします。これは、OpenClaw 内部ランタイムコンテキストを含む放棄されたユーザーターンと、同じ可視ユーザープロンプトを含むアクティブな兄弟が存在する状態です。`--fix` / `--repair` モードでは、doctor は影響を受ける各ファイルを元ファイルの隣にバックアップし、Gateway 履歴とメモリリーダーが重複ターンを見なくなるよう、トランスクリプトをアクティブなブランチへ書き換えます。 - - 状態ディレクトリは運用上の中枢です。これが消えると、別の場所にバックアップがない限り、セッション、認証情報、ログ、設定を失います。 + + 状態ディレクトリは運用上の中枢です。これが消えると、（別の場所にバックアップがない限り）セッション、認証情報、ログ、設定が失われます。 - 診断機能が確認する内容: + 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` の場合、診断機能はリモートホストで実行するよう通知します（状態はそこにあります）。 - - **設定ファイルの権限**: `~/.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` へ制限することを提案します。 - 診断機能は認証ストア内の OAuth プロファイルを検査し、トークンが期限切れ間近または期限切れの場合に警告し、安全な場合は更新できます。Anthropic OAuth/トークンプロファイルが古い場合は、Anthropic API キーまたは Anthropic セットアップトークンの経路を提案します。更新プロンプトは対話的に実行している場合（TTY）にのみ表示されます。`--non-interactive` では更新の試行をスキップします。 + Doctor は認証ストア内の OAuth プロファイルを検査し、トークンの期限が近い/期限切れの場合に警告し、安全な場合は更新できます。Anthropic の OAuth/トークンプロファイルが古い場合、Anthropic API キーまたは Anthropic setup-token パスを提案します。更新プロンプトは対話的に実行している場合（TTY）のみ表示されます。`--non-interactive` では更新の試行をスキップします。 - OAuth 更新が恒久的に失敗した場合（たとえば `refresh_token_reused`、`invalid_grant`、またはプロバイダーが再サインインを求める場合）、診断機能は再認証が必要であることを報告し、実行すべき正確な `openclaw models auth login --provider ...` コマンドを出力します。 + OAuth 更新が恒久的に失敗した場合（たとえば `refresh_token_reused`、`invalid_grant`、またはプロバイダーから再サインインを求められた場合）、doctor は再認証が必要であることを報告し、実行すべき正確な `openclaw models auth login --provider ...` コマンドを出力します。 - 診断機能は、次の理由により一時的に使用できない認証プロファイルも報告します: + Doctor は、次の理由で一時的に使用できない認証プロファイルも報告します。 - 短いクールダウン（レート制限/タイムアウト/認証失敗） - - 長い無効化（請求/クレジット失敗） + - より長い無効化（請求/クレジットの失敗） - `hooks.gmail.model` が設定されている場合、診断機能はモデル参照をカタログおよび許可リストと照合して検証し、解決できない、または許可されていない場合に警告します。 + `hooks.gmail.model` が設定されている場合、doctor はモデル参照をカタログと許可リストに照らして検証し、解決できない場合や許可されていない場合に警告します。 - サンドボックス化が有効な場合、診断機能は Docker イメージを確認し、現在のイメージがない場合はビルドするかレガシー名へ切り替えることを提案します。 + サンドボックスが有効な場合、doctor は Docker イメージをチェックし、現在のイメージが欠落している場合はビルドするかレガシー名へ切り替えることを提案します。 - 診断機能は、`openclaw doctor --fix` / `openclaw doctor --repair` モードで、レガシーな OpenClaw 生成 Plugin 依存関係ステージング状態を削除します。対象には、古い生成済み依存関係ルート、旧インストールステージディレクトリ、以前のバンドル済み Plugin 依存関係修復コードによるパッケージローカルの残骸、現在のバンドル済みマニフェストを隠してしまう可能性がある、孤立または復旧された管理対象 npm コピーのバンドル済み `@openclaw/*` plugins が含まれます。 + Doctor は、`openclaw doctor --fix` / `openclaw doctor --repair` モードで、レガシーの OpenClaw 生成 Plugin 依存関係ステージング状態を削除します。これには、古い生成済み依存関係ルート、古いインストールステージディレクトリ、以前のバンドル済み Plugin 依存関係修復コードによるパッケージローカルの残骸、現在のバンドル済みマニフェストを隠してしまう可能性がある、孤立または復元された管理対象 npm コピーのバンドル済み `@openclaw/*` Plugin が含まれます。 - 設定がダウンロード可能な plugins を参照しているものの、ローカル Plugin レジストリで見つからない場合、診断機能はそれらを再インストールすることもできます。2026.5.2 のバンドル済み Plugin 外部化では、診断機能は既存の設定ですでに使用されているダウンロード可能な plugins を自動的にインストールし、その後 `meta.lastTouchedVersion` によって、そのリリース処理を 1 回だけ実行します。Gateway 起動と設定再読み込みはパッケージマネージャーを実行しません。Plugin インストールは明示的な診断/インストール/更新作業のままです。 + Doctor は、設定で参照されているがローカル Plugin レジストリで見つからない、欠落したダウンロード可能 Plugin も再インストールできます。例には、実体のある `plugins.entries`、設定済みのチャンネル/プロバイダー/検索設定、設定済みのエージェントランタイムが含まれます。パッケージ更新中、doctor はコアパッケージの入れ替え中にパッケージマネージャーによる Plugin 修復を実行しません。設定済み Plugin の復旧がまだ必要な場合は、更新後に `openclaw doctor --fix` を再度実行してください。Gateway 起動と設定リロードはパッケージマネージャーを実行しません。Plugin のインストールは明示的な doctor/install/update 作業のままです。 - - 診断機能はレガシー Gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して現在の Gateway ポートを使う OpenClaw サービスをインストールすることを提案します。追加の Gateway 風サービスをスキャンし、クリーンアップのヒントを出力することもできます。プロファイル名付きの OpenClaw Gateway サービスは第一級のものと見なされ、「追加」としてフラグ付けされません。 + + Doctor はレガシー Gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して現在の Gateway ポートを使用する OpenClaw サービスをインストールすることを提案します。追加の Gateway 風サービスをスキャンし、クリーンアップヒントを出力することもできます。プロファイル名付きの OpenClaw Gateway サービスは第一級のものと見なされ、「extra」として検出されません。 - Linux では、ユーザーレベルの Gateway サービスが欠落しているが、システムレベルの OpenClaw Gateway サービスが存在する場合、診断機能は 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` で確認し、重複を削除するか、システムスーパーバイザーが Gateway ライフサイクルを所有している場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定してください。 - - Matrix チャンネルアカウントに保留中または対処可能なレガシー状態移行がある場合、診断機能は（`--fix` / `--repair` モードで）移行前スナップショットを作成し、その後ベストエフォートの移行手順を実行します。レガシー Matrix 状態移行と、レガシー暗号化状態の準備です。どちらの手順も致命的ではなく、エラーはログに記録され、起動は続行されます。読み取り専用モード（`--fix` なしの `openclaw doctor`）では、このチェックは完全にスキップされます。 + + Matrix チャンネルアカウントに保留中または対応可能なレガシー状態移行がある場合、doctor は（`--fix` / `--repair` モードで）移行前スナップショットを作成してから、ベストエフォートの移行手順を実行します。レガシー Matrix 状態移行とレガシー暗号化状態の準備です。どちらの手順も致命的ではありません。エラーはログに記録され、起動は継続します。読み取り専用モード（`--fix` なしの `openclaw doctor`）では、このチェックは完全にスキップされます。 - - 診断機能は通常の健全性チェックの一部として、デバイスペアリング状態を検査するようになりました。 + + Doctor は通常のヘルスパスの一部として、デバイスペアリング状態も検査するようになりました。 報告内容: - - 保留中の初回ペアリングリクエスト - - すでにペアリング済みのデバイスに対する保留中のロール昇格 - - すでにペアリング済みのデバイスに対する保留中のスコープ昇格 + - 初回ペアリングリクエストの保留 + - すでにペアリング済みのデバイスに対するロールアップグレードの保留 + - すでにペアリング済みのデバイスに対するスコープアップグレードの保留 - デバイス ID はまだ一致しているが、デバイス ID 情報が承認済みレコードと一致しなくなった公開鍵不一致の修復 - - 承認済みロールの有効なトークンが欠落しているペアリング済みレコード - - スコープが承認済みペアリング基準から外れたペアリング済みトークン - - 現在のマシン用のローカルキャッシュ済みデバイストークンエントリのうち、Gateway 側のトークンローテーションより古いもの、または古いスコープメタデータを持つもの + - 承認済みロールのアクティブなトークンが欠落しているペアリング済みレコード + - スコープが承認済みペアリングベースラインの外へドリフトしたペアリング済みトークン + - Gateway 側のトークンローテーションより前の、または古いスコープメタデータを持つ、現在のマシン用のローカルキャッシュ済みデバイストークンエントリ - 診断機能はペアリングリクエストの自動承認やデバイストークンの自動ローテーションを行いません。代わりに正確な次の手順を出力します: + Doctor はペアリングリクエストの自動承認やデバイストークンの自動ローテーションは行いません。代わりに正確な次の手順を出力します。 - `openclaw devices list` で保留中のリクエストを確認する - `openclaw devices approve ` で正確なリクエストを承認する - `openclaw devices rotate --device --role ` で新しいトークンをローテーションする - `openclaw devices remove ` で古いレコードを削除して再承認する - これにより、よくある「すでにペアリング済みなのに、まだペアリングが必要になる」穴を塞ぎます。診断機能は、初回ペアリング、保留中のロール/スコープ昇格、古いトークン/デバイス ID 情報のずれを区別するようになりました。 + これにより、一般的な「すでにペアリング済みなのに、まだペアリングが必要と表示される」穴が塞がれます。doctor は、初回ペアリング、保留中のロール/スコープアップグレード、古いトークン/デバイス ID 情報のドリフトを区別するようになりました。 - プロバイダーが許可リストなしで DM に開放されている場合、またはポリシーが危険な方法で設定されている場合、診断機能は警告を出力します。 + Doctor は、プロバイダーが許可リストなしで DM に開かれている場合、またはポリシーが危険な方法で設定されている場合に警告を出します。 - systemd ユーザーサービスとして実行している場合、診断機能はログアウト後も gateway が稼働し続けるよう lingering が有効であることを確認します。 + systemd ユーザーサービスとして実行している場合、doctor はログアウト後も Gateway が稼働し続けるよう linger が有効であることを確認します。 - - 診断機能は、デフォルトエージェントのワークスペース状態の概要を出力します: + + Doctor はデフォルトエージェントのワークスペース状態の概要を出力します。 - - **Skills 状態**: 対象、要件欠落、許可リストでブロックされた Skills の数を数えます。 - - **レガシーワークスペースディレクトリ**: `~/openclaw` またはその他のレガシーワークスペースディレクトリが現在のワークスペースと並んで存在する場合に警告します。 - - **Plugin 状態**: 有効/無効/エラーの plugins を数えます。エラーがある場合は Plugin ID を一覧表示します。バンドル Plugin の機能を報告します。 - - **Plugin 互換性警告**: 現在のランタイムとの互換性問題がある plugins にフラグを立てます。 - - **Plugin 診断**: Plugin レジストリが読み込み時に出力した警告またはエラーを表示します。 + - **Skills の状態**: 適格、要件欠落、許可リストでブロックされた Skills の数を数えます。 + - **レガシーワークスペースディレクトリ**: `~/openclaw` または他のレガシーワークスペースディレクトリが現在のワークスペースと並んで存在する場合に警告します。 + - **Plugin の状態**: 有効/無効/エラーの Plugin 数を数え、エラーがある場合は Plugin ID を一覧表示し、バンドル Plugin の機能を報告します。 + - **Plugin 互換性警告**: 現在のランタイムとの互換性問題がある Plugin を検出します。 + - **Plugin 診断**: Plugin レジストリから出力された読み込み時の警告やエラーを表示します。 - 診断機能は、ワークスペースのブートストラップファイル（たとえば `AGENTS.md`、`CLAUDE.md`、その他の注入コンテキストファイル）が設定済みの文字数予算に近い、または超えていないかを確認します。ファイルごとの生の文字数と注入後の文字数、切り詰め率、切り詰め原因（`max/file` または `max/total`）、合計注入文字数が合計予算に占める割合を報告します。ファイルが切り詰められている、または制限に近い場合、診断機能は `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` が欠落しているチャンネル Plugin を削除すると、その Plugin を参照していたぶら下がったチャンネルスコープ設定も削除します。`channels.` エントリ、チャンネル名を指定していた Heartbeat ターゲット、`agents.*.models["/*"]` オーバーライドです。これにより、チャンネルランタイムはなくなっているのに、設定が gateway にそれへのバインドを求め続ける Gateway 起動ループを防ぎます。 + `openclaw doctor --fix` が欠落したチャンネル Plugin を削除する場合、その Plugin を参照していたぶら下がったチャンネルスコープ設定も削除します。つまり、`channels.` エントリ、そのチャンネル名を指定した Heartbeat ターゲット、`agents.*.models["/*"]` オーバーライドです。これにより、チャンネルランタイムが消えているのに設定が Gateway にバインドを求め続ける Gateway ブートループを防ぎます。 - 診断機能は、現在のシェル（zsh、bash、fish、または PowerShell）にタブ補完がインストールされているかを確認します: + Doctor は、現在のシェル（zsh、bash、fish、PowerShell）にタブ補完がインストールされているかどうかをチェックします。 - - シェルプロファイルが低速な動的補完パターン（`source <(openclaw completion ...)`）を使っている場合、診断機能は高速なキャッシュファイル方式へアップグレードします。 - - 補完がプロファイルに設定されているがキャッシュファイルがない場合、診断機能はキャッシュを自動的に再生成します。 - - 補完がまったく設定されていない場合、診断機能はインストールを促します（対話モードのみ。`--non-interactive` ではスキップ）。 + - シェルプロファイルが低速な動的補完パターン（`source <(openclaw completion ...)`）を使用している場合、doctor はより高速なキャッシュファイル方式へアップグレードします。 + - 補完がプロファイルに設定されているがキャッシュファイルが欠落している場合、doctor はキャッシュを自動的に再生成します。 + - 補完がまったく設定されていない場合、doctor はインストールを促します（対話モードのみ。`--non-interactive` ではスキップ）。 - キャッシュを手動で再生成するには `openclaw completion --write-state` を実行します。 + キャッシュを手動で再生成するには `openclaw completion --write-state` を実行してください。 - 診断機能はローカル Gateway トークン認証の準備状態を確認します。 + Doctor はローカル Gateway トークン認証の準備状態をチェックします。 - - トークンモードでトークンが必要だがトークンソースが存在しない場合、診断機能は生成を提案します。 - - `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 経由で設定されているものの、現在のコマンドパスで利用できない場合、診断機能は認証情報が設定済みだが利用不可であると報告し、クラッシュしたり、トークンが欠落していると誤報告したりせずに自動解決をスキップします。 + - `openclaw doctor --fix` は、対象を絞った設定修復で、status 系コマンドと同じ読み取り専用 SecretRef サマリーモデルを使うようになりました。 + - 例: Telegram の `allowFrom` / `groupAllowFrom` の `@username` 修復は、利用可能な場合は設定済み bot 認証情報の使用を試みます。 + - Telegram bot token が SecretRef 経由で設定されているものの、現在のコマンドパスで利用できない場合、doctor は認証情報が設定済みだが利用不可であることを報告し、クラッシュしたり token が欠落していると誤報告したりせずに自動解決をスキップします。 - Doctor はヘルスチェックを実行し、Gateway が正常でないように見える場合は再起動を提案します。 + doctor はヘルスチェックを実行し、Gateway が正常でないように見える場合は再起動を提案します。 - - Doctor は、設定されたメモリ検索の埋め込みプロバイダーがデフォルトのエージェントで準備できているかを確認します。動作は設定されたバックエンドとプロバイダーによって異なります。 + + doctor は、設定済みのメモリ検索 embedding provider がデフォルトエージェントで準備できているかを確認します。動作は設定済みのバックエンドと provider によって異なります。 - - **QMD バックエンド**: `qmd` バイナリが利用可能で起動できるかを検査します。できない場合は、npm パッケージと手動バイナリパスのオプションを含む修正ガイダンスを出力します。 - - **明示的なローカルプロバイダー**: ローカルモデルファイル、または認識済みのリモート/ダウンロード可能なモデル URL を確認します。見つからない場合は、リモートプロバイダーへの切り替えを提案します。 - - **明示的なリモートプロバイダー**（`openai`、`voyage` など）: API キーが環境または認証ストアに存在することを検証します。見つからない場合は、実行可能な修正ヒントを出力します。 - - **自動プロバイダー**: まずローカルモデルの可用性を確認し、その後、自動選択順で各リモートプロバイダーを試します。 + - **QMD バックエンド**: `qmd` バイナリが利用可能で起動できるかをプローブします。できない場合は、npm package と手動バイナリパスの選択肢を含む修正ガイダンスを出力します。 + - **明示的なローカル provider**: ローカルモデルファイル、または認識済みのリモート/ダウンロード可能なモデル URL を確認します。見つからない場合は、リモート provider への切り替えを提案します。 + - **明示的なリモート provider** (`openai`, `voyage` など): API key が環境または auth store に存在することを検証します。欠落している場合は、実行可能な修正ヒントを出力します。 + - **自動 provider**: まずローカルモデルの可用性を確認し、その後 auto-selection order で各リモート provider を試します。 - キャッシュされた Gateway 検査結果が利用可能な場合（チェック時点で Gateway が正常だった場合）、doctor はその結果を CLI から見える設定と照合し、不一致があれば記録します。Doctor はデフォルトのパスでは新しい埋め込み ping を開始しません。ライブのプロバイダーチェックが必要な場合は、詳細メモリステータスコマンドを使用してください。 + キャッシュされた Gateway probe 結果が利用可能な場合（確認時点で Gateway が正常だった場合）、doctor はその結果を CLI から見える設定と照合し、差異があれば通知します。doctor はデフォルトパスで新しい embedding ping を開始しません。live provider check が必要な場合は、deep memory status コマンドを使ってください。 - 実行時に埋め込みの準備状態を検証するには、`openclaw memory status --deep` を使用してください。 + 実行時の embedding 準備状況を検証するには、`openclaw memory status --deep` を使います。 - - Gateway が正常な場合、doctor はチャンネルステータス検査を実行し、推奨修正とともに警告を報告します。 + + Gateway が正常な場合、doctor はチャネルステータス probe を実行し、推奨修正とともに警告を報告します。 - Doctor は、インストール済みのスーパーバイザー設定（launchd/systemd/schtasks）に欠落または古いデフォルト（例: systemd の network-online 依存関係と再起動遅延）がないか確認します。不一致を見つけると、更新を推奨し、サービスファイル/タスクを現在のデフォルトに書き換えることができます。 + doctor は、インストール済みのスーパーバイザー設定（launchd/systemd/schtasks）に欠落したデフォルトや古いデフォルトがないかを確認します（例: systemd network-online 依存関係と restart delay）。不一致を見つけると、更新を推奨し、service file/task を現在のデフォルトに書き換えることができます。 - 注: + 注記: - - `openclaw doctor` はスーパーバイザー設定を書き換える前に確認を求めます。 + - `openclaw doctor` はスーパーバイザー設定を書き換える前に確認します。 - `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=` の両方のソースを含むようになりました。 - - Doctor のサービス修復は、設定がより新しいバージョンによって最後に書き込まれている場合、古い OpenClaw バイナリから Gateway サービスを書き換えたり、停止したり、再起動したりすることを拒否します。[Gateway トラブルシューティング](/ja-JP/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)を参照してください。 - - `openclaw gateway install --force` でいつでも完全な書き換えを強制できます。 + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` は、Gateway service lifecycle について doctor を読み取り専用に保ちます。service health の報告と non-service repairs は引き続き実行しますが、外部スーパーバイザーがその lifecycle を所有しているため、service install/start/restart/bootstrap、スーパーバイザー設定の書き換え、legacy service cleanup はスキップします。 + - Linux では、一致する systemd Gateway unit がアクティブな間、doctor は command/entrypoint metadata を書き換えません。また duplicate-service scan 中は、非アクティブな non-legacy の追加 gateway-like units を無視するため、companion service files が cleanup noise を作りません。 + - token auth が token を必要とし、`gateway.auth.token` が SecretRef 管理の場合、doctor service install/repair は SecretRef を検証しますが、解決済みの平文 token 値をスーパーバイザーサービス環境メタデータに永続化しません。 + - doctor は、古い LaunchAgent、systemd、または Windows Scheduled Task のインストールが inline に埋め込んだ、managed `.env`/SecretRef-backed service environment values を検出し、それらの値がスーパーバイザー定義ではなく runtime source から読み込まれるように service metadata を書き換えます。 + - doctor は、`gateway.port` の変更後も service command が古い `--port` を固定している場合に検出し、service metadata を現在の port に書き換えます。 + - token auth が token を必要とし、設定済み token SecretRef が未解決の場合、doctor は実行可能なガイダンスとともに install/repair path をブロックします。 + - `gateway.auth.token` と `gateway.auth.password` の両方が設定され、`gateway.auth.mode` が未設定の場合、doctor は mode が明示的に設定されるまで install/repair をブロックします。 + - Linux user-systemd units では、doctor token drift checks は service auth metadata を比較するときに `Environment=` と `EnvironmentFile=` の両方のソースを含むようになりました。 + - doctor service repairs は、設定がより新しいバージョンで最後に書き込まれていた場合、古い OpenClaw バイナリの Gateway service の書き換え、停止、または再起動を拒否します。[Gateway troubleshooting](/ja-JP/gateway/troubleshooting#split-brain-installs-and-newer-config-guard) を参照してください。 + - `openclaw gateway install --force` により、いつでも完全な書き換えを強制できます。 - Doctor はサービスランタイム（PID、最後の終了ステータス）を検査し、サービスがインストール済みだが実際には実行されていない場合に警告します。また、Gateway ポート（デフォルトは `18789`）でのポート衝突を確認し、考えられる原因（Gateway がすでに実行中、SSH トンネル）を報告します。 + doctor は service runtime（PID、last exit status）を検査し、service がインストールされているものの実際には実行されていない場合に警告します。また Gateway port（デフォルト `18789`）での port collisions を確認し、可能性の高い原因（Gateway がすでに実行中、SSH tunnel）を報告します。 - Gateway サービスが Bun またはバージョン管理された Node パス（`nvm`、`fnm`、`volta`、`asdf` など）で実行されている場合、doctor は警告します。WhatsApp + Telegram チャンネルには Node が必要であり、サービスはシェル初期化を読み込まないため、バージョンマネージャーのパスはアップグレード後に壊れる可能性があります。Doctor は、利用可能な場合はシステムの Node インストール（Homebrew/apt/choco）への移行を提案します。 + Gateway service が Bun または version-managed Node path（`nvm`, `fnm`, `volta`, `asdf` など）で実行されている場合、doctor は警告します。WhatsApp + Telegram channels には Node が必要で、version-manager paths は service が shell init を読み込まないため、アップグレード後に壊れる可能性があります。doctor は利用可能な場合、system Node install（Homebrew/apt/choco）への移行を提案します。 - 新しくインストールまたは修復された macOS LaunchAgent は、対話型シェルの PATH をコピーする代わりに、標準的なシステム PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`）を使用するため、Volta、asdf、fnm、pnpm、その他のバージョンマネージャーディレクトリが、Node 子プロセスの解決先を変更することはありません。Linux サービスは引き続き明示的な環境ルート（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）と安定したユーザー bin ディレクトリを保持しますが、推測されたバージョンマネージャーのフォールバックディレクトリは、それらのディレクトリがディスク上に存在する場合にのみサービス PATH に書き込まれます。 + 新しくインストールまたは修復された macOS LaunchAgents は、interactive shell PATH をコピーする代わりに、canonical system PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`）を使うため、Volta、asdf、fnm、pnpm、その他の version-manager directories が、どの Node child processes が解決されるかを変えることはありません。Linux services は引き続き明示的な environment roots（`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`）と stable user-bin directories を保持しますが、推測された version-manager fallback directories は、それらのディレクトリがディスク上に存在する場合にのみ service PATH に書き込まれます。 - - Doctor は設定変更を永続化し、doctor 実行を記録するためにウィザードメタデータを刻印します。 + + doctor は設定変更を永続化し、doctor run を記録するためにウィザードメタデータを刻印します。 - Doctor は、ワークスペースメモリシステムがない場合に提案し、ワークスペースがまだ git 配下にない場合はバックアップのヒントを出力します。 + doctor は、ワークスペースメモリシステムがない場合に提案し、ワークスペースがまだ git 管理下にない場合はバックアップのヒントを出力します。 ワークスペース構造と git バックアップ（非公開 GitHub または GitLab を推奨）の完全なガイドについては、[/concepts/agent-workspace](/ja-JP/concepts/agent-workspace) を参照してください。 @@ -498,5 +502,5 @@ openclaw memory rem-backfill --path ./memory --stage-short-term ## 関連 -- [Gateway ランブック](/ja-JP/gateway) -- [Gateway トラブルシューティング](/ja-JP/gateway/troubleshooting) +- [Gateway runbook](/ja-JP/gateway) +- [Gateway troubleshooting](/ja-JP/gateway/troubleshooting) diff --git a/docs/ja-JP/gateway/logging.md b/docs/ja-JP/gateway/logging.md index a32a85b51..4bd107dc9 100644 --- a/docs/ja-JP/gateway/logging.md +++ b/docs/ja-JP/gateway/logging.md @@ -1,14 +1,14 @@ --- read_when: - ログ出力や形式の変更 - - CLI または Gateway の出力のデバッグ -summary: ログ記録サーフェス、ファイルログ、WS ログスタイル、コンソール書式設定 -title: Gateway ロギング + - CLI または Gateway 出力のデバッグ +summary: ログ記録サーフェス、ファイルログ、WS ログスタイル、コンソールの書式設定 +title: Gateway のロギング x-i18n: - generated_at: "2026-05-02T04:55:44Z" + generated_at: "2026-05-05T01:46:53Z" model: gpt-5.5 provider: openai - source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13 + source_hash: d49ca112d3cc4ec76ecfc8b14d16dae64f74ca1f761fdb2b7bb470f73b66a246 source_path: gateway/logging.md workflow: 16 --- @@ -20,81 +20,79 @@ x-i18n: OpenClaw には 2 つのログ「サーフェス」があります。 - **コンソール出力**（ターミナル / Debug UI に表示されるもの）。 -- **ファイルログ**（JSON 行）。Gateway ロガーによって書き込まれます。 +- Gateway ロガーによって書き込まれる **ファイルログ**（JSON lines）。 + +起動時に、Gateway は解決済みのデフォルトエージェントモデルを、新しいセッションに影響するモードのデフォルトとともにログに記録します。例: + +```text +agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on) +``` + +`thinking` はデフォルトエージェント、モデルパラメータ、またはグローバルエージェントデフォルトから取得されます。未設定の場合、起動時の要約には `medium` と表示されます。`fast` はデフォルトエージェントまたはモデルの `fastMode` パラメータから取得されます。 ## ファイルベースのロガー -- デフォルトのローテーションログファイルは `/tmp/openclaw/` 配下です（1 日 1 ファイル）: `openclaw-YYYY-MM-DD.log` - - 日付には Gateway ホストのローカルタイムゾーンが使われます。 -- アクティブなログファイルは `logging.maxFileBytes`（デフォルト: 100 MB）でローテーションし、 - 最大 5 個の番号付きアーカイブを保持しながら、新しいアクティブファイルへの書き込みを続けます。 -- ログファイルのパスとレベルは `~/.openclaw/openclaw.json` で設定できます: +- デフォルトのローテーションログファイルは `/tmp/openclaw/` 配下にあります（1 日 1 ファイル）: `openclaw-YYYY-MM-DD.log` + - 日付には Gateway ホストのローカルタイムゾーンが使用されます。 +- アクティブなログファイルは `logging.maxFileBytes`（デフォルト: 100 MB）でローテーションされ、最大 5 つの番号付きアーカイブを保持しつつ、新しいアクティブファイルへの書き込みを続けます。 +- ログファイルのパスとレベルは `~/.openclaw/openclaw.json` で設定できます。 - `logging.file` - `logging.level` -ファイル形式は 1 行に 1 つの JSON オブジェクトです。 +ファイル形式は 1 行につき 1 つの JSON オブジェクトです。 -Control UI の Logs タブは Gateway 経由でこのファイルを追尾します（`logs.tail`）。 -CLI でも同じことができます: +Control UI の Logs タブは、Gateway（`logs.tail`）経由でこのファイルを tail します。 +CLI でも同じことができます。 ```bash openclaw logs --follow ``` -**詳細出力とログレベル** +**詳細表示とログレベル** - **ファイルログ**は `logging.level` のみによって制御されます。 -- `--verbose` は **コンソールの詳細度**（および WS ログスタイル）にのみ影響し、ファイルログレベルを - 引き上げることは**ありません**。 -- 詳細出力限定の情報をファイルログに記録するには、`logging.level` を `debug` または - `trace` に設定します。 -- トレースロギングには、Plugin ツールファクトリの準備など、選択された高頻度パスに関する診断用タイミングサマリーも含まれます。 - [/tools/plugin#slow-plugin-tool-setup](/ja-JP/tools/plugin#slow-plugin-tool-setup) を参照してください。 +- `--verbose` は **コンソールの詳細度**（および WS ログスタイル）にのみ影響します。**ファイルログレベルを上げるものではありません**。 +- 詳細表示専用の内容をファイルログに取得するには、`logging.level` を `debug` または `trace` に設定します。 +- Trace ロギングには、Plugin ツールファクトリ準備など、一部のホットパスの診断用タイミング要約も含まれます。[/tools/plugin#slow-plugin-tool-setup](/ja-JP/tools/plugin#slow-plugin-tool-setup) を参照してください。 ## コンソールキャプチャ -CLI は `console.log/info/warn/error/debug/trace` をキャプチャしてファイルログに書き込み、 -同時に stdout/stderr への出力も継続します。 +CLI は `console.log/info/warn/error/debug/trace` をキャプチャしてファイルログに書き込みつつ、stdout/stderr への出力も継続します。 -コンソールの詳細度は次で個別に調整できます: +コンソールの詳細度は、以下で個別に調整できます。 -- `logging.consoleLevel`（デフォルト `info`） +- `logging.consoleLevel`（デフォルトは `info`） - `logging.consoleStyle`（`pretty` | `compact` | `json`） ## リダクション -OpenClaw は、ログやトランスクリプト出力がプロセスの外へ出る前に、機密トークンをマスクできます。 -このロギングリダクションポリシーは、コンソール、ファイルログ、OTLP ログレコード、セッショントランスクリプトテキストの各シンクに適用されるため、一致するシークレット値は JSONL 行やメッセージがディスクに書き込まれる前にマスクされます。 +OpenClaw は、ログまたはトランスクリプト出力がプロセスを離れる前に、機密トークンをマスクできます。このロギングリダクションポリシーは、コンソール、ファイルログ、OTLP ログレコード、セッショントランスクリプトテキストのシンクに適用されるため、一致するシークレット値は JSONL 行やメッセージがディスクへ書き込まれる前にマスクされます。 - `logging.redactSensitive`: `off` | `tools`（デフォルト: `tools`） - `logging.redactPatterns`: 正規表現文字列の配列（デフォルトを上書き） - - 生の正規表現文字列（自動で `gi`）、またはカスタムフラグが必要な場合は `/pattern/flags` を使います。 - - 一致箇所は、長さが 18 以上の場合は先頭 6 文字 + 末尾 4 文字を残してマスクされ、それ以外は `***` になります。 - - デフォルトでは、一般的なキー代入、CLI フラグ、JSON フィールド、Bearer ヘッダー、PEM ブロック、よく使われるトークンプレフィックス、カード番号、CVC/CVV、共有決済トークン、決済クレデンシャルなどの決済クレデンシャルフィールド名を対象にします。 + - 生の正規表現文字列（自動で `gi`）を使用するか、カスタムフラグが必要な場合は `/pattern/flags` を使用します。 + - 一致箇所は、最初の 6 文字 + 最後の 4 文字を保持してマスクされます（長さ >= 18）。それ以外は `***` になります。 + - デフォルトでは、一般的なキー代入、CLI フラグ、JSON フィールド、Bearer ヘッダー、PEM ブロック、よく使われるトークンプレフィックス、カード番号、CVC/CVV、共有決済トークン、決済認証情報などの決済認証情報フィールド名をカバーします。 一部の安全境界では、`logging.redactSensitive` に関係なく常にリダクションされます。 -これには、Control UI のツール呼び出しイベント、`sessions_history` ツール出力、 -診断サポートエクスポート、プロバイダーエラー観測、exec 承認コマンド表示、 -Gateway WebSocket プロトコルログが含まれます。これらのサーフェスでは追加パターンとして -`logging.redactPatterns` を引き続き使用できますが、`redactSensitive: "off"` にしても -生のシークレットは出力されません。 +これには、Control UI のツール呼び出しイベント、`sessions_history` ツール出力、診断サポートエクスポート、プロバイダーエラー観測、exec 承認コマンド表示、Gateway WebSocket プロトコルログが含まれます。これらのサーフェスでは追加パターンとして `logging.redactPatterns` が引き続き使用される場合がありますが、`redactSensitive: "off"` にしても未加工のシークレットが出力されることはありません。 ## Gateway WebSocket ログ -Gateway は WebSocket プロトコルログを 2 つのモードで出力します: +Gateway は WebSocket プロトコルログを 2 つのモードで出力します。 -- **通常モード（`--verbose` なし）**: 「注目すべき」RPC 結果のみが出力されます: +- **通常モード（`--verbose` なし）**: 「重要」な RPC 結果のみが出力されます。 - エラー（`ok=false`） - - 遅い呼び出し（デフォルトのしきい値: `>= 50ms`） - - 解析エラー + - 遅い呼び出し（デフォルトしきい値: `>= 50ms`） + - パースエラー - **詳細モード（`--verbose`）**: すべての WS リクエスト/レスポンストラフィックを出力します。 ### WS ログスタイル -`openclaw gateway` は Gateway ごとのスタイル切り替えをサポートしています: +`openclaw gateway` は Gateway ごとのスタイル切り替えをサポートします。 -- `--ws-log auto`（デフォルト）: 通常モードは最適化され、詳細モードではコンパクトな出力を使います -- `--ws-log compact`: 詳細モード時にコンパクトな出力（ペアのリクエスト/レスポンス） +- `--ws-log auto`（デフォルト）: 通常モードは最適化され、詳細モードでは compact 出力を使用します +- `--ws-log compact`: 詳細モード時に compact 出力（ペアになったリクエスト/レスポンス） - `--ws-log full`: 詳細モード時にフレームごとの完全な出力 - `--compact`: `--ws-log compact` のエイリアス @@ -111,24 +109,24 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## コンソール形式（サブシステムロギング） +## コンソール整形（サブシステムロギング） コンソールフォーマッターは **TTY 対応**で、一貫したプレフィックス付きの行を出力します。 -サブシステムロガーにより、出力はまとまりがありスキャンしやすくなります。 +サブシステムロガーにより、出力はグループ化され、スキャンしやすく保たれます。 動作: - すべての行に **サブシステムプレフィックス**（例: `[gateway]`、`[canvas]`、`[tailscale]`） - **サブシステムカラー**（サブシステムごとに安定）とレベルカラー -- **出力先が TTY、または環境がリッチターミナルに見える場合にカラー表示**（`TERM`/`COLORTERM`/`TERM_PROGRAM`）、`NO_COLOR` を尊重 -- **短縮されたサブシステムプレフィックス**: 先頭の `gateway/` + `channels/` を削除し、最後の 2 セグメントを保持（例: `whatsapp/outbound`） +- **出力先が TTY、または環境がリッチなターミナルに見える場合にカラー表示**（`TERM`/`COLORTERM`/`TERM_PROGRAM`）。`NO_COLOR` を尊重します +- **短縮されたサブシステムプレフィックス**: 先頭の `gateway/` + `channels/` を削除し、最後の 2 セグメントを保持します（例: `whatsapp/outbound`） - **サブシステム別のサブロガー**（自動プレフィックス + 構造化フィールド `{ subsystem }`） -- QR/UX 出力向けの **`logRaw()`**（プレフィックスなし、形式設定なし） +- QR/UX 出力用の **`logRaw()`**（プレフィックスなし、整形なし） - **コンソールスタイル**（例: `pretty | compact | json`） -- **コンソールログレベル**はファイルログレベルとは別です（`logging.level` が `debug`/`trace` に設定されている場合、ファイルには完全な詳細が保持されます） -- **WhatsApp メッセージ本文**は `debug` でログに記録されます（表示するには `--verbose` を使います） +- ファイルログレベルとは別の **コンソールログレベル**（`logging.level` が `debug`/`trace` に設定されている場合、ファイルには完全な詳細が保持されます） +- **WhatsApp メッセージ本文**は `debug` でログに記録されます（表示するには `--verbose` を使用） -これにより、既存のファイルログを安定させたまま、対話的な出力をスキャンしやすくできます。 +これにより、既存のファイルログを安定させたまま、対話型出力をスキャンしやすくできます。 ## 関連 diff --git a/docs/ja-JP/help/debugging.md b/docs/ja-JP/help/debugging.md index 18ae9fea2..8a0aef24e 100644 --- a/docs/ja-JP/help/debugging.md +++ b/docs/ja-JP/help/debugging.md @@ -1,26 +1,26 @@ --- read_when: - - 推論の漏えいがないか、生のモデル出力を調査する必要があります - - 反復開発中に Gateway をウォッチモードで実行したい場合 - - 再現可能なデバッグワークフローが必要です -summary: 'デバッグツール: ウォッチモード、生のモデルストリーム、推論内容の漏えいのトレース' + - 推論の漏えいがないか、未加工のモデル出力を確認する必要があります + - イテレーション中に Gateway を watch モードで実行したい + - 繰り返し使えるデバッグワークフローが必要です +summary: 'デバッグツール: ウォッチモード、生のモデルストリーム、推論漏えいの追跡' title: デバッグ x-i18n: - generated_at: "2026-05-03T21:34:19Z" + generated_at: "2026-05-05T01:46:59Z" model: gpt-5.5 provider: openai - source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc + source_hash: 9d86bd9b5dd08615d3c283f3fcb2a885f5134fa7e1cdece86b6a796d08a659ec source_path: help/debugging.md workflow: 16 --- -ストリーミング出力のデバッグヘルパー。特に、プロバイダーが推論を通常のテキストに混ぜる場合に役立ちます。 +ストリーミング出力をデバッグするためのヘルパー。特に、プロバイダーが推論を通常のテキストに混在させる場合に有用です。 ## ランタイムデバッグオーバーライド -チャットで `/debug` を使用して、**ランタイム専用**の設定オーバーライドを設定します（メモリ上のみ、ディスクには保存されません）。 -`/debug` はデフォルトで無効です。`commands.debug: true` で有効にします。 -これは、`openclaw.json` を編集せずに分かりにくい設定を切り替える必要がある場合に便利です。 +チャットで `/debug` を使用すると、**ランタイム専用** の設定オーバーライド（メモリ上のみ、ディスクには保存されません）を設定できます。 +`/debug` はデフォルトで無効です。`commands.debug: true` で有効にしてください。 +`openclaw.json` を編集せずに、わかりにくい設定を切り替える必要がある場合に便利です。 例: @@ -35,7 +35,7 @@ x-i18n: ## セッショントレース出力 -完全な詳細モードを有効にせず、1 つのセッションで Plugin が所有するトレース/デバッグ行を確認したい場合は、`/trace` を使用します。 +完全な verbose モードを有効にせずに、1つのセッションで Plugin 所有のトレース/デバッグ行を確認したい場合は `/trace` を使用します。 例: @@ -45,13 +45,12 @@ x-i18n: /trace off ``` -Active Memory のデバッグ要約などの Plugin 診断には `/trace` を使用します。 -通常の詳細なステータス/ツール出力には引き続き `/verbose` を使用し、ランタイム専用の設定オーバーライドには引き続き -`/debug` を使用します。 +Active Memory のデバッグ要約など、Plugin 診断には `/trace` を使用します。 +通常の verbose ステータス/ツール出力には引き続き `/verbose` を使用し、ランタイム専用の設定オーバーライドには引き続き `/debug` を使用してください。 ## Plugin ライフサイクルトレース -Plugin ライフサイクルコマンドが遅く感じられ、Plugin メタデータ、検出、レジストリ、ランタイムミラー、設定変更、更新作業について組み込みのフェーズ分解が必要な場合は、`OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` を使用します。このトレースはオプトインで、stderr に書き込まれるため、JSON コマンド出力は解析可能なままです。 +Plugin ライフサイクルコマンドが遅く感じられ、Plugin メタデータ、検出、レジストリ、ランタイムミラー、設定変更、更新作業について組み込みのフェーズ内訳が必要な場合は、`OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` を使用します。トレースはオプトインで stderr に書き込まれるため、JSON コマンド出力は引き続き解析可能です。 例: @@ -67,9 +66,8 @@ OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force [plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed" ``` -CPU プロファイラーに手を伸ばす前に、Plugin ライフサイクルの調査にはこれを使用します。 -コマンドをソースチェックアウトから実行している場合は、`pnpm build` の後に `node dist/entry.js ...` でビルド済みランタイムを測定することを推奨します。`pnpm openclaw ...` -ではソースランナーのオーバーヘッドも測定されます。 +CPU プロファイラーに頼る前に、Plugin ライフサイクル調査にはこれを使用してください。 +コマンドをソースチェックアウトから実行している場合は、`pnpm build` 後に `node dist/entry.js ...` でビルド済みランタイムを測定することを優先してください。`pnpm openclaw ...` ではソースランナーのオーバーヘッドも測定されます。 ## CLI 起動とコマンドプロファイリング @@ -81,27 +79,33 @@ pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3 pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu ``` -通常のソースランナー経由で一回限りのプロファイリングを行うには、 -`OPENCLAW_RUN_NODE_CPU_PROF_DIR` を設定します。 +通常のソースランナー経由で単発のプロファイリングを行うには、`OPENCLAW_RUN_NODE_CPU_PROF_DIR` を設定します。 ```bash OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status ``` -ソースランナーは Node CPU プロファイルフラグを追加し、コマンドの -`.cpuprofile` を書き込みます。コマンドコードに一時的な計測を追加する前にこれを使用します。 +ソースランナーは Node CPU プロファイルフラグを追加し、コマンド用の `.cpuprofile` を書き込みます。コマンドコードに一時的な計測を追加する前に、これを使用してください。 -## Gateway ウォッチモード +同期的なファイルシステム処理やモジュールローダー処理のように見える起動停止には、ソースランナー経由で Node の sync I/O トレースフラグを追加します。 -高速な反復作業には、ファイルウォッチャーの下で Gateway を実行します。 +```bash +OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force +``` + +`pnpm gateway:watch` は、監視対象の Gateway 子プロセスに対してこのフラグをデフォルトで有効にします。 +watch モードで Node sync I/O トレース出力を抑制するには、`OPENCLAW_TRACE_SYNC_IO=0` を設定します。 + +## Gateway watch モード + +高速な反復作業には、ファイルウォッチャーの下で gateway を実行します。 ```bash pnpm gateway:watch ``` -デフォルトでは、`openclaw-gateway-watch-main` という名前の tmux セッション（または -`openclaw-gateway-watch-dev-19001` のようなプロファイル/ポート固有のバリアント）を開始または再起動し、対話型ターミナルから自動的にアタッチします。 -非対話型シェル、CI、エージェントの exec 呼び出しはデタッチされたままになり、代わりにアタッチ手順を出力します。必要な場合は手動でアタッチします。 +デフォルトでは、`openclaw-gateway-watch-main` という名前の tmux セッション（または `openclaw-gateway-watch-dev-19001` のようなプロファイル/ポート固有のバリアント）を開始または再起動し、インタラクティブ端末から自動アタッチします。 +非インタラクティブシェル、CI、エージェント exec 呼び出しはデタッチされたままになり、代わりにアタッチ手順を出力します。必要に応じて手動でアタッチしてください。 ```bash tmux attach -t openclaw-gateway-watch-main @@ -127,50 +131,47 @@ tmux 管理を維持したまま自動アタッチを無効にします。 OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch ``` -起動時/ランタイムのホットスポットをデバッグするときは、監視中の Gateway CPU 時間をプロファイルします。 +起動時やランタイムのホットスポットをデバッグするときは、監視対象 Gateway の CPU 時間をプロファイルします。 ```bash pnpm gateway:watch --benchmark ``` -ウォッチラッパーは Gateway を呼び出す前に `--benchmark` を消費し、Gateway 子プロセスの終了ごとに 1 つの V8 `.cpuprofile` を -`.artifacts/gateway-watch-profiles/` の下に書き込みます。現在のプロファイルをフラッシュするには、監視中の Gateway を停止または再起動し、その後 Chrome DevTools または Speedscope で開きます。 +watch ラッパーは Gateway を呼び出す前に `--benchmark` を消費し、Gateway 子プロセスの終了ごとに V8 `.cpuprofile` を1つ `.artifacts/gateway-watch-profiles/` 配下に書き込みます。現在のプロファイルをフラッシュするには、監視対象 gateway を停止または再起動し、その後 Chrome DevTools または Speedscope で開きます。 ```bash npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile ``` プロファイルを別の場所に置きたい場合は `--benchmark-dir ` を使用します。 -ベンチマーク対象の子プロセスでデフォルトの `--force` ポートクリーンアップをスキップし、Gateway ポートがすでに使用中の場合にすぐ失敗させたい場合は、`--benchmark-no-force` を使用します。 +ベンチマーク対象の子プロセスでデフォルトの `--force` ポートクリーンアップをスキップし、Gateway ポートがすでに使用中の場合に即座に失敗させたい場合は、`--benchmark-no-force` を使用します。 +ベンチマークモードでは、sync-I/O トレースの大量出力はデフォルトで抑制されます。CPU プロファイルと Node sync-I/O スタックトレースの両方を明示的に必要とする場合は、`--benchmark` とともに `OPENCLAW_TRACE_SYNC_IO=1` を設定します。ベンチマークモードでは、それらのトレースブロックはベンチマークディレクトリ配下の `gateway-watch-output.log` に書き込まれ、ターミナルペインからはフィルタリングされます。通常の Gateway ログは引き続き表示されます。 -tmux ラッパーは、`OPENCLAW_PROFILE`、`OPENCLAW_CONFIG_PATH`、`OPENCLAW_STATE_DIR`、 -`OPENCLAW_GATEWAY_PORT`、`OPENCLAW_SKIP_CHANNELS` などの一般的な非シークレットのランタイムセレクターをペインに引き継ぎます。プロバイダー資格情報は通常のプロファイル/設定に置くか、一回限りの一時的なシークレットには生のフォアグラウンドモードを使用します。 -監視中の Gateway が起動中に終了した場合、ウォッチャーは -`openclaw doctor --fix --non-interactive` を 1 回実行し、Gateway 子プロセスを再起動します。 -開発専用の修復パスを使わずに元の起動失敗を確認したい場合は、`OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` を使用します。 -管理対象の tmux ペインでは、読みやすさのために色付きの Gateway ログもデフォルトになります。ANSI 出力を無効にするには、`pnpm gateway:watch` の開始時に `FORCE_COLOR=0` を設定します。 +tmux ラッパーは、`OPENCLAW_PROFILE`、`OPENCLAW_CONFIG_PATH`、`OPENCLAW_STATE_DIR`、`OPENCLAW_GATEWAY_PORT`、`OPENCLAW_SKIP_CHANNELS` など、一般的な非シークレットのランタイムセレクターをペインに引き継ぎます。 +プロバイダー認証情報は通常のプロファイル/設定に入れるか、単発の一時シークレットには生のフォアグラウンドモードを使用してください。 +監視対象 Gateway が起動中に終了した場合、ウォッチャーは `openclaw doctor --fix --non-interactive` を一度実行してから Gateway 子プロセスを再起動します。 +開発専用の修復パスなしで元の起動失敗を確認したい場合は、`OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` を使用します。 +管理対象の tmux ペインでは、読みやすさのために色付き Gateway ログもデフォルトで有効です。ANSI 出力を無効にするには、`pnpm gateway:watch` の起動時に `FORCE_COLOR=0` を設定します。 -ウォッチャーは、`src/` 配下のビルド関連ファイル、拡張機能のソースファイル、拡張機能の `package.json` と `openclaw.plugin.json` メタデータ、`tsconfig.json`、 -`package.json`、`tsdown.config.ts` で再起動します。拡張機能メタデータの変更では、`tsdown` のリビルドを強制せずに Gateway を再起動します。ソースと設定の変更では、引き続き先に `dist` をリビルドします。 +ウォッチャーは、`src/` 配下のビルド関連ファイル、extension ソースファイル、extension の `package.json` と `openclaw.plugin.json` メタデータ、`tsconfig.json`、`package.json`、`tsdown.config.ts` で再起動します。extension メタデータの変更では、`tsdown` の再ビルドを強制せずに gateway が再起動されます。ソースと設定の変更では、引き続き先に `dist` が再ビルドされます。 -Gateway CLI フラグは `gateway:watch` の後に追加すると、各再起動時にそのまま渡されます。同じウォッチコマンドを再実行すると、名前付きの tmux ペインが再生成されます。また、生のウォッチャーは単一ウォッチャーロックを維持するため、重複したウォッチャー親プロセスは積み上がらずに置き換えられます。 +gateway CLI フラグは `gateway:watch` の後に追加すると、各再起動時にそのまま渡されます。同じ watch コマンドを再実行すると、名前付き tmux ペインが再生成されます。また、生のウォッチャーは単一ウォッチャーロックを維持するため、重複するウォッチャー親プロセスが積み上がるのではなく置き換えられます。 -## 開発プロファイル + 開発 Gateway（--dev） +## 開発プロファイル + 開発 gateway（--dev） -状態を分離し、デバッグ用の安全で使い捨て可能なセットアップを起動するには、開発プロファイルを使用します。 -`--dev` フラグは**2 種類**あります。 +デバッグ用に状態を分離し、安全で使い捨て可能なセットアップを起動するには、開発プロファイルを使用します。`--dev` フラグは**2つ**あります。 -- **グローバル `--dev`（プロファイル）:** 状態を `~/.openclaw-dev` の下に分離し、Gateway ポートをデフォルトで `19001` にします（派生ポートもそれに合わせて移動します）。 -- **`gateway --dev`: Gateway に、存在しない場合はデフォルト設定 + ワークスペースを自動作成するよう指示します**（そして BOOTSTRAP.md をスキップします）。 +- **グローバル `--dev`（プロファイル）:** 状態を `~/.openclaw-dev` 配下に分離し、gateway ポートをデフォルトで `19001` にします（派生ポートもそれに合わせてずれます）。 +- **`gateway --dev`: 設定 + ワークスペースがない場合に Gateway にデフォルトを自動作成させます**（BOOTSTRAP.md はスキップします）。 -推奨フロー（開発プロファイル + 開発ブートストラップ）: +推奨フロー（開発プロファイル + 開発 bootstrap）: ```bash pnpm gateway:dev OPENCLAW_PROFILE=dev openclaw tui ``` -グローバルインストールがまだない場合は、`pnpm openclaw ...` 経由で CLI を実行します。 +まだグローバルインストールがない場合は、`pnpm openclaw ...` 経由で CLI を実行します。 これが行うこと: @@ -178,16 +179,16 @@ OPENCLAW_PROFILE=dev openclaw tui - `OPENCLAW_PROFILE=dev` - `OPENCLAW_STATE_DIR=~/.openclaw-dev` - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json` - - `OPENCLAW_GATEWAY_PORT=19001`（ブラウザー/canvas もそれに応じて移動） + - `OPENCLAW_GATEWAY_PORT=19001`（ブラウザー/canvas もそれに応じてずれます） -2. **開発ブートストラップ**（`gateway --dev`） +2. **開発 bootstrap**（`gateway --dev`） - 存在しない場合は最小設定を書き込みます（`gateway.mode=local`、loopback にバインド）。 - `agent.workspace` を開発ワークスペースに設定します。 - `agent.skipBootstrap=true` を設定します（BOOTSTRAP.md なし）。 - 存在しない場合はワークスペースファイルをシードします: - `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`. - - デフォルトのアイデンティティ: **C3‑PO**（プロトコルドロイド）。 - - 開発モードではチャネルプロバイダーをスキップします（`OPENCLAW_SKIP_CHANNELS=1`）。 + `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`。 + - デフォルト identity: **C3‑PO**（プロトコルドロイド）。 + - 開発モードではチャンネルプロバイダーをスキップします（`OPENCLAW_SKIP_CHANNELS=1`）。 リセットフロー（新規開始）: @@ -196,7 +197,7 @@ pnpm gateway:dev:reset ``` -`--dev` は**グローバル**プロファイルフラグであり、一部のランナーに消費されます。明示的に指定する必要がある場合は、env var 形式を使用します。 +`--dev` は**グローバル**プロファイルフラグであり、一部のランナーに消費されます。明示的に指定する必要がある場合は、環境変数形式を使用してください。 ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset @@ -204,11 +205,10 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset -`--reset` は設定、資格情報、セッション、開発ワークスペースを消去し（`rm` ではなく -`trash` を使用）、デフォルトの開発セットアップを再作成します。 +`--reset` は設定、認証情報、セッション、開発ワークスペースを消去し（`rm` ではなく `trash` を使用）、その後デフォルトの開発セットアップを再作成します。 -非開発 Gateway がすでに実行中の場合（launchd または systemd）、先に停止します。 +非開発 gateway がすでに実行中の場合（launchd または systemd）、先に停止してください。 ```bash openclaw gateway stop @@ -218,8 +218,8 @@ openclaw gateway stop ## 生ストリームログ（OpenClaw） -OpenClaw は、フィルタリング/整形の前に**生のアシスタントストリーム**をログに記録できます。 -これは、推論がプレーンテキストのデルタとして届いているのか（または別個の思考ブロックとして届いているのか）を確認する最良の方法です。 +OpenClaw は、フィルタリング/整形の前に **生の assistant ストリーム** をログに記録できます。 +これは、推論がプレーンテキスト delta として到着しているのか（または別個の thinking ブロックとして到着しているのか）を確認する最良の方法です。 CLI 経由で有効にします。 @@ -233,7 +233,7 @@ pnpm gateway:watch --raw-stream pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl ``` -同等の env var: +同等の環境変数: ```bash OPENCLAW_RAW_STREAM=1 @@ -246,7 +246,7 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl ## 生チャンクログ（pi-mono） -ブロックに解析される前の**生の OpenAI 互換チャンク**を取得するために、pi-mono は別のロガーを公開しています。 +ブロックに解析される前の **生の OpenAI 互換チャンク** をキャプチャするために、pi-mono は別のロガーを公開しています。 ```bash PI_RAW_STREAM=1 @@ -262,14 +262,13 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl `~/.pi-mono/logs/raw-openai-completions.jsonl` -> 注: これは、pi-mono の -> `openai-completions` プロバイダーを使用するプロセスによってのみ出力されます。 +> 注: これは pi-mono の `openai-completions` プロバイダーを使用するプロセスによってのみ出力されます。 ## 安全上の注意 -- 生ストリームログには、完全なプロンプト、ツール出力、ユーザーデータが含まれることがあります。 +- 生ストリームログには、完全なプロンプト、ツール出力、ユーザーデータが含まれる可能性があります。 - ログはローカルに保持し、デバッグ後に削除してください。 -- ログを共有する場合は、先にシークレットと PII を除去してください。 +- ログを共有する場合は、先にシークレットと PII を削除してください。 ## 関連 diff --git a/docs/ja-JP/help/faq-models.md b/docs/ja-JP/help/faq-models.md index 1364ac756..906f73457 100644 --- a/docs/ja-JP/help/faq-models.md +++ b/docs/ja-JP/help/faq-models.md @@ -2,68 +2,68 @@ read_when: - モデルの選択または切り替え、エイリアスの設定 - モデルフェイルオーバーのデバッグ / 「すべてのモデルが失敗しました」 - - 認証プロファイルとその管理方法を理解する + - 認証プロファイルの理解と管理方法 sidebarTitle: Models FAQ -summary: 'FAQ: モデルのデフォルト、選択、エイリアス、切り替え、フェイルオーバー、認証プロファイル' +summary: 'よくある質問: モデルのデフォルト、選択、エイリアス、切り替え、フェイルオーバー、認証プロファイル' title: 'FAQ: モデルと認証' x-i18n: - generated_at: "2026-05-02T04:57:38Z" + generated_at: "2026-05-05T01:46:56Z" model: gpt-5.5 provider: openai - source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884 + source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54 source_path: help/faq-models.md workflow: 16 --- - モデルおよび認証プロファイルの Q&A。セットアップ、セッション、Gateway、チャンネル、トラブルシューティングについては、メインの [FAQ](/ja-JP/help/faq) を参照してください。 + Model と auth-profile の Q&A。セットアップ、セッション、Gateway、チャンネル、トラブルシューティングについては、メインの [FAQ](/ja-JP/help/faq) を参照してください。 ## モデル: デフォルト、選択、エイリアス、切り替え - + OpenClaw のデフォルトモデルは、次の値として設定したものです。 ``` agents.defaults.model.primary ``` - モデルは `provider/model` として参照されます（例: `openai/gpt-5.5` または `openai-codex/gpt-5.5`）。プロバイダーを省略すると、OpenClaw はまずエイリアスを試し、次にその正確なモデル ID に一致する一意の設定済みプロバイダーを探し、その後にのみ非推奨の互換パスとして設定済みのデフォルトプロバイダーへフォールバックします。そのプロバイダーが設定済みのデフォルトモデルを公開しなくなっている場合、OpenClaw は古い削除済みプロバイダーのデフォルトを表示する代わりに、最初に設定されたプロバイダー/モデルへフォールバックします。それでも `provider/model` を**明示的に**設定する必要があります。 + モデルは `provider/model` として参照されます（例: `openai/gpt-5.5` または `openai-codex/gpt-5.5`）。プロバイダーを省略すると、OpenClaw はまずエイリアスを試し、次にその正確なモデル ID に一致する一意の設定済みプロバイダーを試し、その後でのみ、非推奨の互換パスとして設定済みのデフォルトプロバイダーにフォールバックします。そのプロバイダーが設定済みのデフォルトモデルをもう公開していない場合、OpenClaw は古い削除済みプロバイダーのデフォルトを表示する代わりに、最初に設定されたプロバイダー/モデルへフォールバックします。それでも `provider/model` は**明示的に**設定してください。 - - **推奨デフォルト:** 使用しているプロバイダースタックで利用可能な最強の最新世代モデルを使用してください。 - **ツールを有効にしたエージェント、または信頼できない入力を扱うエージェント:** コストよりもモデルの性能を優先してください。 - **日常的/低リスクのチャット:** より安価なフォールバックモデルを使用し、エージェントのロールでルーティングしてください。 + + **推奨デフォルト:** 利用しているプロバイダースタックで使える最も強力な最新世代モデルを使用してください。 + **ツール対応または信頼できない入力を扱うエージェント:** コストよりモデルの強さを優先してください。 + **日常的/低リスクのチャット:** 安価なフォールバックモデルを使い、エージェントの役割でルーティングしてください。 - MiniMax には独自のドキュメントがあります: [MiniMax](/ja-JP/providers/minimax) および + MiniMax には独自のドキュメントがあります: [MiniMax](/ja-JP/providers/minimax) と [ローカルモデル](/ja-JP/gateway/local-models)。 - 目安: 高リスクの作業には**手の届く範囲で最良のモデル**を使用し、日常的なチャットや要約にはより安価な - モデルを使用してください。エージェントごとにモデルをルーティングし、サブエージェントを使用して + 目安: 高リスクの作業には**予算内で使える最良のモデル**を使用し、日常的なチャットや要約には安価な + モデルを使用してください。エージェントごとにモデルをルーティングでき、サブエージェントを使って 長いタスクを並列化できます（各サブエージェントはトークンを消費します）。[モデル](/ja-JP/concepts/models) と [サブエージェント](/ja-JP/tools/subagents) を参照してください。 - 強い警告: 弱いモデルや過度に量子化されたモデルは、プロンプトインジェクションや - 安全でない動作に対してより脆弱です。[セキュリティ](/ja-JP/gateway/security) を参照してください。 + 強い警告: 弱いモデルや過度に量子化されたモデルは、プロンプト + インジェクションや安全でない動作に対してより脆弱です。[セキュリティ](/ja-JP/gateway/security) を参照してください。 - 追加の背景情報: [モデル](/ja-JP/concepts/models)。 + さらに詳しく: [モデル](/ja-JP/concepts/models)。 - **モデルコマンド**を使用するか、**モデル**フィールドだけを編集してください。設定全体の置き換えは避けてください。 + **モデルコマンド**を使うか、**model** フィールドだけを編集してください。設定全体の置き換えは避けてください。 安全な選択肢: - - チャット内の `/model`（素早い、セッション単位） + - チャット内の `/model`（素早く、セッションごと） - `openclaw models set ...`（モデル設定だけを更新） - `openclaw configure --section model`（対話式） - - `~/.openclaw/openclaw.json` 内の `agents.defaults.model` を編集 + - `~/.openclaw/openclaw.json` の `agents.defaults.model` を編集 設定全体を置き換える意図がない限り、部分オブジェクトで `config.apply` を使うのは避けてください。 - RPC 編集では、まず `config.schema.lookup` で調べ、`config.patch` を優先してください。lookup ペイロードは、正規化されたパス、浅いスキーマドキュメント/制約、直下の子要素の要約を提供します。 - 部分更新用です。 + RPC 編集では、まず `config.schema.lookup` で調べ、`config.patch` を優先してください。lookup ペイロードは、正規化されたパス、浅いスキーマドキュメント/制約、直接の子要素の概要を提供します。 + 部分更新に使用します。 設定を上書きしてしまった場合は、バックアップから復元するか、`openclaw doctor` を再実行して修復してください。 ドキュメント: [モデル](/ja-JP/concepts/models)、[設定](/ja-JP/cli/configure)、[Config](/ja-JP/cli/config)、[Doctor](/ja-JP/gateway/doctor)。 @@ -71,24 +71,24 @@ x-i18n: - はい。Ollama はローカルモデルを使う最も簡単な方法です。 + はい。ローカルモデルには Ollama が最も簡単な方法です。 - 最短のセットアップ: + 最短セットアップ: - 1. `https://ollama.com/download` から Ollama をインストールする - 2. `ollama pull gemma4` などのローカルモデルを取得する - 3. クラウドモデルも使いたい場合は、`ollama signin` を実行する - 4. `openclaw onboard` を実行し、`Ollama` を選択する - 5. `Local` または `Cloud + Local` を選択する + 1. `https://ollama.com/download` から Ollama をインストールします + 2. `ollama pull gemma4` などのローカルモデルを取得します + 3. クラウドモデルも使いたい場合は、`ollama signin` を実行します + 4. `openclaw onboard` を実行し、`Ollama` を選択します + 5. `Local` または `Cloud + Local` を選びます - 注: + メモ: - - `Cloud + Local` では、クラウドモデルに加えてローカルの Ollama モデルも利用できます - - `kimi-k2.5:cloud` などのクラウドモデルはローカルでの取得を必要としません - - 手動で切り替える場合は、`openclaw models list` と `openclaw models set ollama/` を使用してください + - `Cloud + Local` では、クラウドモデルに加えてローカルの Ollama モデルを利用できます + - `kimi-k2.5:cloud` などのクラウドモデルはローカル取得を必要としません + - 手動で切り替えるには、`openclaw models list` と `openclaw models set ollama/` を使用します - セキュリティ上の注意: 小さいモデルや大きく量子化されたモデルは、プロンプト - インジェクションに対してより脆弱です。ツールを使用できるボットには**大規模モデル**を強く推奨します。 + セキュリティメモ: 小さいモデルや大きく量子化されたモデルは、プロンプト + インジェクションに対してより脆弱です。ツールを使用できるボットには、**大規模モデル**を強く推奨します。 それでも小さいモデルを使いたい場合は、サンドボックス化と厳格なツール許可リストを有効にしてください。 ドキュメント: [Ollama](/ja-JP/providers/ollama)、[ローカルモデル](/ja-JP/gateway/local-models)、 @@ -98,9 +98,9 @@ x-i18n: - - これらのデプロイは異なる場合があり、時間とともに変わる可能性があります。固定のプロバイダー推奨はありません。 - - 各 Gateway の現在のランタイム設定を `openclaw models status` で確認してください。 - - セキュリティに敏感なエージェントやツールを有効にしたエージェントには、利用可能な最強の最新世代モデルを使用してください。 + - これらのデプロイは異なる場合があり、時間とともに変更されることがあります。固定のプロバイダー推奨はありません。 + - 各 Gateway で `openclaw models status` を使い、現在のランタイム設定を確認してください。 + - セキュリティ上重要なエージェントやツール対応エージェントには、利用可能な最も強力な最新世代モデルを使用してください。 @@ -117,7 +117,7 @@ x-i18n: /model gemini-flash-lite ``` - これらは組み込みのエイリアスです。カスタムエイリアスは `agents.defaults.models` で追加できます。 + これらは組み込みエイリアスです。カスタムエイリアスは `agents.defaults.models` で追加できます。 利用可能なモデルは `/model`、`/model list`、または `/model status` で一覧表示できます。 @@ -127,46 +127,46 @@ x-i18n: /model 3 ``` - プロバイダーに対して特定の認証プロファイルを強制することもできます（セッション単位）。 + プロバイダーに対して特定の auth profile を強制することもできます（セッションごと）。 ``` /model opus@anthropic:default /model opus@anthropic:work ``` - ヒント: `/model status` は、どのエージェントがアクティブか、どの `auth-profiles.json` ファイルが使われているか、次に試される認証プロファイルを表示します。 + ヒント: `/model status` は、どのエージェントがアクティブか、どの `auth-profiles.json` ファイルが使われているか、次にどの auth profile が試されるかを表示します。 利用可能な場合は、設定済みのプロバイダーエンドポイント（`baseUrl`）と API モード（`api`）も表示します。 **@profile で設定したプロファイルの固定を解除するには？** - `@profile` サフィックスを付けずに `/model` を再実行してください。 + `@profile` サフィックス**なしで** `/model` を再実行します。 ``` /model anthropic/claude-opus-4-6 ``` - デフォルトに戻したい場合は、`/model` から選ぶ（または `/model ` を送信する）してください。 - どの認証プロファイルがアクティブかを確認するには `/model status` を使用してください。 + デフォルトに戻したい場合は、`/model` から選ぶか（または `/model ` を送信します）。 + どの auth profile がアクティブか確認するには、`/model status` を使用してください。 - はい。モデル選択とランタイム選択は別々に扱ってください。 + はい。モデルの選択とランタイムの選択は分けて考えてください。 - - **ネイティブ Codex コーディングエージェント:** `agents.defaults.model.primary` を `openai/gpt-5.5` に、`agents.defaults.agentRuntime.id` を `"codex"` に設定します。ChatGPT/Codex サブスクリプション認証を使いたい場合は、`openclaw models auth login --provider openai-codex` でサインインしてください。 - - **PI 経由の直接 OpenAI API タスク:** Codex ランタイムの上書きなしで `/model openai/gpt-5.5` を使用し、`OPENAI_API_KEY` を設定します。 - - **PI 経由の Codex OAuth:** 通常の PI ランナーで Codex OAuth を意図的に使いたい場合にのみ、`/model openai-codex/gpt-5.5` を使用します。 - - **サブエージェント:** コーディングタスクを、独自のモデルと `agentRuntime` デフォルトを持つ Codex 専用エージェントへルーティングします。 + - **ネイティブ Codex コーディングエージェント:** `agents.defaults.model.primary` を `openai/gpt-5.5` に、`agents.defaults.agentRuntime.id` を `"codex"` に設定します。ChatGPT/Codex サブスクリプション認証を使いたい場合は、`openclaw models auth login --provider openai-codex` でサインインします。 + - **PI 経由の直接 OpenAI API タスク:** Codex ランタイムのオーバーライドなしで `/model openai/gpt-5.5` を使い、`OPENAI_API_KEY` を設定します。 + - **PI 経由の Codex OAuth:** 通常の PI ランナーを Codex OAuth と一緒に意図的に使いたい場合にのみ、`/model openai-codex/gpt-5.5` を使用します。 + - **サブエージェント:** コーディングタスクを、独自のモデルと `agentRuntime` デフォルトを持つ Codex 専用エージェントにルーティングします。 [モデル](/ja-JP/concepts/models) と [スラッシュコマンド](/ja-JP/tools/slash-commands) を参照してください。 - セッションの切り替え、または設定デフォルトのいずれかを使用します。 + セッショントグルまたは設定デフォルトのどちらかを使用します。 - - **セッション単位:** セッションが `openai/gpt-5.5` または `openai-codex/gpt-5.5` を使用している間に `/fast on` を送信します。 - - **モデル単位のデフォルト:** `agents.defaults.models["openai/gpt-5.5"].params.fastMode` または `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` を `true` に設定します。 + - **セッションごと:** セッションが `openai/gpt-5.5` または `openai-codex/gpt-5.5` を使用している間に `/fast on` を送信します。 + - **モデルごとのデフォルト:** `agents.defaults.models["openai/gpt-5.5"].params.fastMode` または `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` を `true` に設定します。 例: @@ -186,58 +186,60 @@ x-i18n: } ``` - OpenAI では、高速モードは対応するネイティブ Responses リクエスト上の `service_tier = "priority"` に対応します。セッションの `/fast` 上書きは設定デフォルトより優先されます。 + OpenAI では、高速モードはサポートされるネイティブ Responses リクエストの `service_tier = "priority"` に対応します。セッションの `/fast` オーバーライドは設定デフォルトより優先されます。 - [思考と高速モード](/ja-JP/tools/thinking) および [OpenAI 高速モード](/ja-JP/providers/openai#fast-mode) を参照してください。 + [Thinking と高速モード](/ja-JP/tools/thinking) と [OpenAI 高速モード](/ja-JP/providers/openai#fast-mode) を参照してください。 - `agents.defaults.models` が設定されている場合、それは `/model` とあらゆる - セッション上書きの**許可リスト**になります。そのリストにないモデルを選択すると、次が返されます。 + `agents.defaults.models` が設定されている場合、それは `/model` とすべての + セッションオーバーライドの**許可リスト**になります。そのリストにないモデルを選ぶと、次が返されます。 ``` - Model "provider/model" is not allowed. Use /model to list available models. + Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. + Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` - このエラーは通常の返信の**代わりに**返されます。修正: そのモデルを - `agents.defaults.models` に追加する、許可リストを削除する、または `/model list` からモデルを選択してください。 + このエラーは通常の返信の**代わりに**返されます。修正: モデルを + `agents.defaults.models` に追加する、許可リストを削除する、または `/model list` からモデルを選びます。 + コマンドに `--runtime codex` も含まれていた場合は、先にモデルを追加してから、同じ + `/model provider/model --runtime codex` コマンドを再試行してください。 - これは、**プロバイダーが設定されていない**（MiniMax プロバイダー設定または認証 - プロファイルが見つからなかった）ため、モデルを解決できないことを意味します。 + これは、**プロバイダーが設定されていない**（MiniMax プロバイダー設定または auth + profile が見つからない）ため、モデルを解決できないことを意味します。 修正チェックリスト: - 1. 現行の OpenClaw リリースにアップグレードする（またはソースの `main` から実行する）してから、Gateway を再起動する。 - 2. MiniMax が設定されている（ウィザードまたは JSON）こと、または MiniMax 認証が - env/認証プロファイルに存在し、一致するプロバイダーを注入できることを確認する - （`minimax` には `MINIMAX_API_KEY`、`minimax-portal` には `MINIMAX_OAUTH_TOKEN` または保存済みの MiniMax + 1. 最新の OpenClaw リリースへアップグレードする（またはソースの `main` から実行する）し、Gateway を再起動します。 + 2. MiniMax が設定されていること（ウィザードまたは JSON）、または MiniMax 認証が + env/auth profiles に存在し、一致するプロバイダーを注入できることを確認します + （`minimax` には `MINIMAX_API_KEY`、`minimax-portal` には `MINIMAX_OAUTH_TOKEN` または保存済み MiniMax OAuth）。 - 3. 認証パスに対応する正確なモデル ID（大文字小文字を区別）を使用する: + 3. 認証パスに対して正確なモデル ID（大文字小文字を区別）を使用します: API キー - セットアップでは `minimax/MiniMax-M2.7` または `minimax/MiniMax-M2.7-highspeed`、OAuth セットアップでは - `minimax-portal/MiniMax-M2.7` / + セットアップには `minimax/MiniMax-M2.7` または `minimax/MiniMax-M2.7-highspeed`、OAuth セットアップには `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`。 - 4. 次を実行する: + 4. 次を実行します。 ```bash openclaw models list ``` - そして一覧から選択する（またはチャット内で `/model list`）。 + そして一覧から選びます（またはチャット内で `/model list`）。 [MiniMax](/ja-JP/providers/minimax) と [モデル](/ja-JP/concepts/models) を参照してください。 - - はい。**MiniMax をデフォルト**として使用し、必要に応じて**セッション単位**でモデルを切り替えてください。 + + はい。**MiniMax をデフォルト**として使い、必要に応じて**セッションごと**にモデルを切り替えます。 フォールバックは「難しいタスク」用ではなく**エラー**用なので、`/model` または別のエージェントを使用してください。 - **選択肢 A: セッション単位で切り替える** + **オプション A: セッションごとに切り替える** ```json5 { @@ -254,24 +256,24 @@ x-i18n: } ``` - 次に: + その後: ``` /model gpt ``` - **選択肢 B: エージェントを分ける** + **オプション B: エージェントを分ける** - エージェント A のデフォルト: MiniMax - エージェント B のデフォルト: OpenAI - - エージェントでルーティングする、または `/agent` を使用して切り替える + - エージェントでルーティングするか、`/agent` で切り替えます ドキュメント: [モデル](/ja-JP/concepts/models)、[マルチエージェントルーティング](/ja-JP/concepts/multi-agent)、[MiniMax](/ja-JP/providers/minimax)、[OpenAI](/ja-JP/providers/openai)。 - はい。OpenClaw にはいくつかのデフォルト短縮名が同梱されています（モデルが `agents.defaults.models` に存在する場合にのみ適用されます）。 + はい。OpenClaw にはいくつかのデフォルト省略名が含まれています（モデルが `agents.defaults.models` に存在する場合にのみ適用されます）。 - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -282,12 +284,12 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - 同じ名前で独自のエイリアスを設定した場合は、その値が優先されます。 + 同じ名前で独自のエイリアスを設定した場合は、あなたの値が優先されます。 - エイリアスは `agents.defaults.models..alias` から来ます。例: + エイリアスは `agents.defaults.models..alias` から取得されます。例: ```json5 { @@ -309,7 +311,7 @@ x-i18n: - OpenRouter（トークン単位課金、多数のモデル）: + OpenRouter（トークン従量課金、多数のモデル）: ```json5 { @@ -323,7 +325,7 @@ x-i18n: } ``` - Z.AI（GLM モデル）: + Z.AI (GLMモデル): ```json5 { @@ -339,9 +341,9 @@ x-i18n: プロバイダー/モデルを参照しているのに必要なプロバイダーキーがない場合、ランタイム認証エラーが発生します（例: `No API key found for provider "zai"`）。 - **新しいエージェントを追加した後にプロバイダーの API キーが見つからない** + **新しいエージェントを追加した後にプロバイダーのAPIキーが見つからない** - これは通常、**新しいエージェント**の認証ストアが空であることを意味します。認証はエージェントごとに管理され、次に保存されます。 + これは通常、**新しいエージェント**の認証ストアが空であることを意味します。認証はエージェントごとで、次の場所に保存されます。 ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -350,10 +352,10 @@ x-i18n: 修正方法: - `openclaw agents add ` を実行し、ウィザード中に認証を設定します。 - - または、メインエージェントの認証ストアから、新しいエージェントの認証ストアへ、移植可能な静的 `api_key` / `token` プロファイルだけをコピーします。 - - OAuth プロファイルでは、新しいエージェントが独自のアカウントを必要とする場合、そのエージェントからサインインします。それ以外の場合、OpenClaw はリフレッシュトークンを複製せずにデフォルト/メインエージェントを参照できます。 + - または、メインエージェントの認証ストアから新しいエージェントの認証ストアへ、移植可能な静的 `api_key` / `token` プロファイルだけをコピーします。 + - OAuthプロファイルの場合、そのエージェント固有のアカウントが必要なときは新しいエージェントからサインインします。それ以外の場合、OpenClaw はリフレッシュトークンを複製せずにデフォルト/メインエージェントを読み取りに行けます。 - エージェント間で `agentDir` を再利用**しないでください**。認証/セッションの衝突が発生します。 + 複数のエージェントで `agentDir` を再利用しないでください。認証/セッションの衝突を引き起こします。 @@ -361,116 +363,147 @@ x-i18n: ## モデルのフェイルオーバーと「All models failed」 - - フェイルオーバーは 2 段階で発生します。 + + フェイルオーバーは2段階で発生します。 1. 同じプロバイダー内での**認証プロファイルのローテーション**。 2. `agents.defaults.model.fallbacks` 内の次のモデルへの**モデルフォールバック**。 失敗したプロファイルにはクールダウン（指数バックオフ）が適用されるため、プロバイダーがレート制限中または一時的に失敗している場合でも、OpenClaw は応答を続けられます。 - レート制限バケットには、単純な `429` レスポンス以外も含まれます。OpenClaw は、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted`、および定期的な使用量ウィンドウ制限（`weekly/monthly limit reached`）のようなメッセージも、フェイルオーバー対象のレート制限として扱います。 + レート制限バケットには、単純な `429` 応答以外も含まれます。OpenClaw は + `Too many concurrent requests`、 + `ThrottlingException`、`concurrency limit reached`、 + `workers_ai ... quota limit exceeded`、`resource exhausted`、および定期的な + 使用量ウィンドウの制限（`weekly/monthly limit reached`）のようなメッセージも、フェイルオーバーに値する + レート制限として扱います。 - 課金に見えるレスポンスの一部は `402` ではなく、一部の HTTP `402` レスポンスもその一時的なバケットに残ります。プロバイダーが `401` または `403` で明示的な課金テキストを返す場合、OpenClaw はそれを課金レーンに保持できますが、プロバイダー固有のテキストマッチャーは、それを所有するプロバイダーのスコープに留まります（たとえば OpenRouter の `Key limit exceeded`）。一方、`402` メッセージがリトライ可能な使用量ウィンドウや組織/ワークスペースの支出上限（`daily limit reached, resets tomorrow`、`organization spending limit exceeded`）に見える場合、OpenClaw はそれを長期の課金無効化ではなく `rate_limit` として扱います。 + 課金に見える応答の一部は `402` ではなく、一部のHTTP `402` + 応答もその一時的なバケットに留まります。プロバイダーが `401` または `403` で + 明示的な課金テキストを返す場合でも、OpenClaw はそれを + 課金レーンに保持できますが、プロバイダー固有のテキストマッチャーは、それを所有する + プロバイダーの範囲に留まります（たとえば OpenRouter `Key limit exceeded`）。一方で `402` + メッセージが再試行可能な使用量ウィンドウ、または + 組織/ワークスペースの利用額制限（`daily limit reached, resets tomorrow`、 + `organization spending limit exceeded`）のように見える場合、OpenClaw はそれを + 長期の課金無効化ではなく、`rate_limit` として扱います。 - コンテキストオーバーフローエラーは異なります。`request_too_large`、`input exceeds the maximum number of tokens`、`input token count exceeds the maximum number of input tokens`、`input is too long for the model`、または `ollama error: context length exceeded` のようなシグネチャは、モデルフォールバックを進めるのではなく、Compaction/リトライパスに留まります。 + コンテキストオーバーフローエラーは別です。 + `request_too_large`、`input exceeds the maximum number of tokens`、 + `input token count exceeds the maximum number of input tokens`、 + `input is too long for the model`、または `ollama error: context length + exceeded` のようなシグネチャは、モデル + フォールバックへ進まず、Compaction/再試行パスに留まります。 - 汎用的なサーバーエラーテキストは、「unknown/error を含むものなら何でも」よりも意図的に狭く扱われます。OpenClaw は、Anthropic の裸の `An unknown error occurred`、OpenRouter の裸の `Provider returned error`、`Unhandled stop reason: error` のような停止理由エラー、一時的なサーバーテキスト（`internal server error`、`unknown error, 520`、`upstream error`、`backend error`）を含む JSON `api_error` ペイロード、`ModelNotReadyException` のようなプロバイダー混雑エラーなど、プロバイダースコープの一時的な形を、プロバイダーコンテキストが一致する場合にフェイルオーバー対象のタイムアウト/過負荷シグナルとして扱います。 - `LLM request failed with an unknown error.` のような汎用的な内部フォールバックテキストは保守的に扱われ、それ単体ではモデルフォールバックをトリガーしません。 + 汎用サーバーエラーテキストは、「unknown/error が含まれるものなら何でも」より意図的に狭くしています。OpenClaw は、Anthropic の素の `An unknown error occurred`、OpenRouter の素の + `Provider returned error`、`Unhandled stop reason: + error` のような停止理由エラー、一時的なサーバーテキストを含むJSON `api_error` ペイロード + （`internal server error`、`unknown error, 520`、`upstream error`、`backend + error`）、および `ModelNotReadyException` のようなプロバイダー混雑エラーを、 + プロバイダーコンテキストが一致する場合にフェイルオーバーに値するタイムアウト/過負荷シグナルとして + 扱います。 + `LLM request failed with an unknown + error.` のような汎用内部フォールバックテキストは保守的に扱われ、それ単体ではモデルフォールバックをトリガーしません。 - - これは、システムが認証プロファイル ID `anthropic:default` を使用しようとしたものの、想定される認証ストア内でその認証情報を見つけられなかったことを意味します。 + + これは、システムが認証プロファイルID `anthropic:default` を使用しようとしたものの、想定される認証ストア内でその認証情報を見つけられなかったことを意味します。 **修正チェックリスト:** - - **認証プロファイルの保存場所を確認する**（新しいパスとレガシーパス） + - **認証プロファイルの保存場所を確認する**（新旧のパス） - 現行: `~/.openclaw/agents//agent/auth-profiles.json` - - レガシー: `~/.openclaw/agent/*`（`openclaw doctor` により移行） + - レガシー: `~/.openclaw/agent/*`（`openclaw doctor` によって移行） - **環境変数が Gateway に読み込まれていることを確認する** - - シェルで `ANTHROPIC_API_KEY` を設定していても、Gateway を systemd/launchd 経由で実行している場合、それを継承しないことがあります。`~/.openclaw/.env` に入れるか、`env.shellEnv` を有効にしてください。 + - シェルで `ANTHROPIC_API_KEY` を設定していても、systemd/launchd 経由で Gateway を実行している場合、それを継承しない可能性があります。`~/.openclaw/.env` に入れるか、`env.shellEnv` を有効にしてください。 - **正しいエージェントを編集していることを確認する** - - マルチエージェント構成では、複数の `auth-profiles.json` ファイルが存在することがあります。 - - **モデル/認証ステータスを健全性確認する** + - マルチエージェント構成では、複数の `auth-profiles.json` ファイルが存在する場合があります。 + - **モデル/認証ステータスをサニティチェックする** - `openclaw models status` を使用して、設定済みモデルとプロバイダーが認証済みかどうかを確認します。 **「No credentials found for profile anthropic」の修正チェックリスト** - これは、実行が Anthropic 認証プロファイルに固定されているものの、Gateway がその認証ストア内でそれを見つけられないことを意味します。 + これは、実行がAnthropic認証プロファイルに固定されているものの、Gateway が + その認証ストア内でそれを見つけられないことを意味します。 - - **Claude CLI を使用する** - - Gateway ホストで `openclaw models auth login --provider anthropic --method cli --set-default` を実行します。 - - **代わりに API キーを使用したい場合** - - **Gateway ホスト**上の `~/.openclaw/.env` に `ANTHROPIC_API_KEY` を入れます。 - - 存在しないプロファイルを強制する固定順序をクリアします。 + - **Claude CLIを使用する** + - Gatewayホストで `openclaw models auth login --provider anthropic --method cli --set-default` を実行します。 + - **代わりにAPIキーを使用したい場合** + - **Gatewayホスト**上の `~/.openclaw/.env` に `ANTHROPIC_API_KEY` を入れます。 + - 欠落したプロファイルを強制する固定順序をすべてクリアします。 ```bash openclaw models auth order clear --provider anthropic ``` - - **Gateway ホスト上でコマンドを実行していることを確認する** - - リモートモードでは、認証プロファイルはノートパソコンではなく Gateway マシン上にあります。 + - **Gatewayホスト上でコマンドを実行していることを確認する** + - リモートモードでは、認証プロファイルはノートPCではなくGatewayマシン上に存在します。 - - モデル設定にフォールバックとして Google Gemini が含まれている（または Gemini の省略形に切り替えた）場合、OpenClaw はモデルフォールバック中にそれを試します。Google の認証情報を設定していない場合、`No API key found for provider "google"` が表示されます。 + + モデル設定にフォールバックとして Google Gemini が含まれている場合（またはGeminiの省略表記に切り替えた場合）、OpenClaw はモデルフォールバック中にそれを試します。Google認証情報を設定していない場合、`No API key found for provider "google"` が表示されます。 - 修正: Google 認証を提供するか、フォールバックがそこへルーティングされないように、`agents.defaults.model.fallbacks` / エイリアス内の Google モデルを削除または回避してください。 + 修正: Google認証を提供するか、フォールバックがそこへルーティングされないように `agents.defaults.model.fallbacks` / エイリアスからGoogleモデルを削除または回避します。 - **LLM リクエストが拒否されました: thinking シグネチャが必要です（Google Antigravity）** + **LLMリクエストが拒否されました: thinking signature required（Google Antigravity）** - 原因: セッション履歴に**シグネチャのない thinking ブロック**が含まれています（多くの場合、中断/部分的なストリームが原因）。Google Antigravity は thinking ブロックにシグネチャを要求します。 + 原因: セッション履歴に**署名のないthinkingブロック**が含まれています（多くの場合、 + 中断/部分的なストリームが原因）。Google Antigravity はthinkingブロックに署名を要求します。 - 修正: OpenClaw は現在、Google Antigravity Claude 向けに署名なしの thinking ブロックを取り除きます。それでも表示される場合は、**新しいセッション**を開始するか、そのエージェントで `/thinking off` を設定してください。 + 修正: OpenClaw は現在、Google Antigravity Claude の未署名thinkingブロックを取り除きます。それでも表示される場合は、**新しいセッション**を開始するか、そのエージェントで `/thinking off` を設定してください。 ## 認証プロファイル: 概要と管理方法 -関連: [/concepts/oauth](/ja-JP/concepts/oauth)（OAuth フロー、トークン保存、マルチアカウントパターン） +関連: [/concepts/oauth](/ja-JP/concepts/oauth)（OAuthフロー、トークン保存、マルチアカウントパターン） - - 認証プロファイルとは、プロバイダーに紐づけられた名前付きの認証情報レコード（OAuth または API キー）です。プロファイルは次にあります。 + + 認証プロファイルは、プロバイダーに紐づけられた名前付きの認証情報レコード（OAuthまたはAPIキー）です。プロファイルは次の場所にあります。 ``` ~/.openclaw/agents//agent/auth-profiles.json ``` - - - - OpenClaw は次のような、プロバイダー接頭辞付きの ID を使用します。 - - - `anthropic:default`（メール ID が存在しない場合によく使われます） - - OAuth ID 用の `anthropic:` - - 選択したカスタム ID（例: `anthropic:work`） + シークレットを出力せずに保存済みプロファイルを調べるには、`openclaw models auth list` を実行します（必要に応じて `--provider ` または `--json`）。詳細は [Models CLI](/ja-JP/cli/models#openclaw-models-auth-list) を参照してください。 - - はい。設定では、プロファイルの任意メタデータと、プロバイダーごとの順序（`auth.order.`）をサポートしています。これはシークレットを保存しません。ID をプロバイダー/モードに対応付け、ローテーション順序を設定します。 + + OpenClaw は次のような、プロバイダー接頭辞付きIDを使用します。 - OpenClaw は、プロファイルが短い**クールダウン**（レート制限/タイムアウト/認証失敗）またはより長い**無効化**状態（課金/クレジット不足）にある場合、一時的にスキップすることがあります。これを確認するには、`openclaw models status --json` を実行して `auth.unusableProfiles` を確認します。調整: `auth.cooldowns.billingBackoffHours*`。 + - `anthropic:default`（メールIDがない場合によく使われます） + - OAuth ID用の `anthropic:` + - 選択したカスタムID（例: `anthropic:work`） - レート制限クールダウンはモデルスコープにできます。あるモデルでクールダウン中のプロファイルでも、同じプロバイダー上の兄弟モデルでは引き続き使用可能なことがあります。一方、課金/無効化ウィンドウは引き続きプロファイル全体をブロックします。 + - CLI を使用して、**エージェントごと**の順序オーバーライド（そのエージェントの `auth-state.json` に保存）も設定できます。 + + はい。設定では、プロファイルの任意メタデータと、プロバイダーごとの順序（`auth.order.`）をサポートしています。これはシークレットを保存しません。IDをプロバイダー/モードにマッピングし、ローテーション順序を設定します。 + + OpenClaw は、プロファイルが短い**クールダウン**（レート制限/タイムアウト/認証失敗）または長い**無効化**状態（課金/クレジット不足）にある場合、一時的にそのプロファイルをスキップすることがあります。これを確認するには、`openclaw models status --json` を実行して `auth.unusableProfiles` を確認します。調整: `auth.cooldowns.billingBackoffHours*`。 + + レート制限のクールダウンはモデル単位にできます。あるモデルでクールダウン中のプロファイルでも、 + 同じプロバイダー上の兄弟モデルには引き続き使用できる場合があります。 + 一方、課金/無効化ウィンドウはプロファイル全体を引き続きブロックします。 + + CLIから、**エージェントごとの**順序オーバーライド（そのエージェントの `auth-state.json` に保存）も設定できます。 ```bash - # 設定済みのデフォルトエージェントが既定（--agent は省略） + # Defaults to the configured default agent (omit --agent) openclaw models auth order get --provider anthropic - # ローテーションを単一のプロファイルに固定（これだけを試行） + # Lock rotation to a single profile (only try this one) openclaw models auth order set --provider anthropic anthropic:default - # または明示的な順序を設定（プロバイダー内フォールバック） + # Or set an explicit order (fallback within provider) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # オーバーライドをクリア（config auth.order / ラウンドロビンにフォールバック） + # Clear override (fall back to config auth.order / round-robin) openclaw models auth order clear --provider anthropic ``` @@ -486,24 +519,26 @@ x-i18n: openclaw models status --probe ``` - 保存済みプロファイルが明示的な順序から省略されている場合、プローブは黙って試す代わりに、そのプロファイルについて `excluded_by_auth_order` を報告します。 + 保存済みプロファイルが明示的な順序から省略されている場合、probeは + それを暗黙に試すのではなく、そのプロファイルに対して + `excluded_by_auth_order` を報告します。 - + OpenClaw は両方をサポートしています。 - - **OAuth** は、多くの場合サブスクリプションアクセスを活用します（該当する場合）。 - - **API キー**は従量課金を使用します。 + - **OAuth** は、多くの場合（該当する場合）サブスクリプションアクセスを利用します。 + - **APIキー** はトークン従量課金を使用します。 - ウィザードは、Anthropic Claude CLI、OpenAI Codex OAuth、および API キーを明示的にサポートしています。 + ウィザードは Anthropic Claude CLI、OpenAI Codex OAuth、APIキーを明示的にサポートしています。 ## 関連 -- [FAQ](/ja-JP/help/faq) — メイン FAQ +- [FAQ](/ja-JP/help/faq) — メインFAQ - [FAQ — クイックスタートと初回実行セットアップ](/ja-JP/help/faq-first-run) - [モデル選択](/ja-JP/concepts/model-providers) - [モデルフェイルオーバー](/ja-JP/concepts/model-failover) diff --git a/docs/ja-JP/help/testing-updates-plugins.md b/docs/ja-JP/help/testing-updates-plugins.md index a43cf9573..7a6d0e026 100644 --- a/docs/ja-JP/help/testing-updates-plugins.md +++ b/docs/ja-JP/help/testing-updates-plugins.md @@ -1,51 +1,48 @@ --- read_when: - - OpenClaw の更新、doctor、パッケージ受け入れ、または Plugin インストールの動作を変更する + - OpenClaw の更新、doctor、package acceptance、または Plugin インストールの挙動を変更する - リリース候補の準備または承認 - - パッケージ更新、Plugin依存関係のクリーンアップ、またはPluginインストールの回帰のデバッグ + - パッケージ更新、Plugin 依存関係のクリーンアップ、または Plugin インストールのリグレッションのデバッグ sidebarTitle: Update and plugin tests summary: OpenClaw が更新パス、パッケージ移行、Plugin のインストール/更新動作を検証する方法 -title: 'テスト: 更新とプラグイン' +title: 'テスト: 更新とPlugin' x-i18n: - generated_at: "2026-05-03T21:35:00Z" + generated_at: "2026-05-05T01:47:38Z" model: gpt-5.5 provider: openai - source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd + source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286 source_path: help/testing-updates-plugins.md workflow: 16 --- -これは、更新とPlugin検証専用のチェックリストです。目的は -単純です。インストール可能なパッケージが実際のユーザー状態を更新でき、`doctor` を通じて古い -レガシー状態を修復でき、さらにサポートされているソースから -Pluginをインストール、読み込み、更新、アンインストールできることを証明します。 +これは更新と Plugin 検証専用のチェックリストです。目的は単純です。 +インストール可能なパッケージが実際のユーザー状態を更新でき、`doctor` を通じて古い +レガシー状態を修復でき、サポートされているソースから Plugin を引き続きインストール、 +読み込み、更新、アンインストールできることを証明します。 -より広範なテストランナーの一覧については、[テスト](/ja-JP/help/testing)を参照してください。ライブプロバイダーの -キーとネットワークに触れるスイートについては、[ライブテスト](/ja-JP/help/testing-live)を参照してください。 +より広範なテストランナーの対応表については、[テスト](/ja-JP/help/testing) を参照してください。ライブプロバイダーの +キーやネットワークに触れるスイートについては、[ライブテスト](/ja-JP/help/testing-live) を参照してください。 ## 保護するもの -更新テストとPluginテストは、次の契約を保護します。 +更新と Plugin のテストは、次の契約を保護します。 -- パッケージtarballが完全で、有効な `dist/postinstall-inventory.json` を持ち、 +- パッケージ tarball が完全で、有効な `dist/postinstall-inventory.json` を持ち、 展開されていないリポジトリファイルに依存しないこと。 -- ユーザーが、公開済みの古いパッケージから候補パッケージへ、 - 設定、エージェント、セッション、ワークスペース、Plugin許可リスト、または - チャンネル設定を失わずに移行できること。 -- `openclaw doctor --fix --non-interactive` がレガシーのクリーンアップと修復 - パスを担うこと。起動時に、古いPlugin状態のための隠れた互換性移行を - 増やすべきではありません。 -- Pluginのインストールが、ローカルディレクトリ、gitリポジトリ、npmパッケージ、および - ClawHubレジストリパスから動作すること。 -- Pluginのnpm依存関係が管理対象のnpmルートにインストールされ、信頼前に - スキャンされ、アンインストール時にnpm経由で削除されるため、hoistされた依存関係が - 残らないこと。 -- 何も変更されていない場合、Plugin更新が安定していること。インストール記録、解決済み - ソース、インストール済み依存関係レイアウト、有効状態がそのまま保たれること。 +- ユーザーが古い公開済みパッケージから候補パッケージへ移行しても、設定、エージェント、 + セッション、ワークスペース、Plugin allowlist、またはチャンネル設定を失わないこと。 +- `openclaw doctor --fix --non-interactive` がレガシーのクリーンアップと修復パスを所有すること。 + 起動時に、古い Plugin 状態のための隠れた互換性マイグレーションを増やしてはなりません。 +- Plugin のインストールが、ローカルディレクトリ、git リポジトリ、npm パッケージ、 + ClawHub レジストリパスから機能すること。 +- Plugin の npm 依存関係が管理対象の npm ルートにインストールされ、信頼前にスキャンされ、 + アンインストール時に npm 経由で削除されることで、巻き上げられた依存関係が残らないこと。 +- 何も変更されていない場合の Plugin 更新が安定していること。インストールレコード、解決済みソース、 + インストール済み依存関係レイアウト、有効状態が維持されます。 ## 開発中のローカル証明 -狭い範囲から始めます。 +狭い範囲から開始します。 ```bash pnpm changed:lanes --json @@ -53,31 +50,30 @@ pnpm check:changed pnpm test:changed ``` -Pluginのインストール、アンインストール、依存関係、またはパッケージインベントリの変更では、編集した境界をカバーする -焦点を絞ったテストも実行します。 +Plugin のインストール、アンインストール、依存関係、またはパッケージインベントリの変更では、 +編集した継ぎ目をカバーする焦点を絞ったテストも実行します。 ```bash pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts ``` -パッケージDockerレーンがtarballを使用する前に、パッケージ成果物を証明します。 +パッケージ Docker レーンが tarball を消費する前に、パッケージ成果物を証明します。 ```bash pnpm release:check ``` -`release:check` は、設定/docs/APIドリフトチェックを実行し、パッケージdist -インベントリを書き込み、`npm pack --dry-run` を実行し、パックされた禁止ファイルを拒否し、 -tarballを一時プレフィックスへインストールし、postinstallを実行し、同梱チャンネルの +`release:check` は設定、ドキュメント、API のドリフトチェックを実行し、パッケージ dist +インベントリを書き込み、`npm pack --dry-run` を実行し、禁止された梱包済みファイルを拒否し、 +一時 prefix に tarball をインストールし、postinstall を実行し、バンドルされたチャンネル エントリポイントをスモークします。 -## Dockerレーン +## Docker レーン -Dockerレーンはプロダクトレベルの証明です。Linuxコンテナ内で実際の -パッケージをインストールまたは更新し、CLIコマンド、 -Gateway起動、HTTPプローブ、RPCステータス、ファイルシステム状態を通じて挙動を検証します。 +Docker レーンは製品レベルの証明です。Linux コンテナ内で実際のパッケージをインストールまたは更新し、 +CLI コマンド、Gateway 起動、HTTP プローブ、RPC 状態、ファイルシステム状態を通じて挙動を検証します。 -反復中は焦点を絞ったレーンを使用します。 +反復中は焦点を絞ったレーンを使います。 ```bash pnpm test:docker:plugins @@ -90,34 +86,29 @@ pnpm test:docker:update-migration 重要なレーン: -- `test:docker:plugins` は、Pluginインストールのスモーク、ローカルフォルダーインストール、 - ローカルフォルダー更新のスキップ挙動、事前インストール済み - 依存関係を持つローカルフォルダー、`file:` パッケージインストール、CLI実行を伴うgitインストール、git - moving-ref更新、hoistされた推移的依存関係を伴うnpmレジストリインストール、 - npm更新のno-op、ローカルClawHubフィクスチャのインストールと更新 - no-op、マーケットプレイス更新挙動、Claudeバンドルの有効化/検査を検証します。 - ClawHubブロックをhermetic/オフラインに保つには、`OPENCLAW_PLUGINS_E2E_CLAWHUB=0` を設定します。 -- `test:docker:plugin-lifecycle-matrix` は、素のコンテナに候補パッケージをインストールし、 - npm Pluginをインストール、検査、無効化、有効化、 - 明示的アップグレード、明示的ダウングレード、Pluginコード削除後のアンインストールまで実行します。 - 各フェーズのRSSとCPUメトリクスを記録します。 -- `test:docker:plugin-update` は、変更のないインストール済みPluginが - `openclaw plugins update` 中に再インストールされたり、インストールメタデータを失ったりしないことを検証します。 -- `test:docker:upgrade-survivor` は、汚れた古いユーザーフィクスチャの上に候補tarballをインストールし、 - パッケージ更新と非対話型doctorを実行してから、 - loopback Gatewayを起動し、状態保持を確認します。 +- `test:docker:plugins` は、Plugin インストールのスモーク、ローカルフォルダーインストール、 + ローカルフォルダー更新のスキップ挙動、事前インストール済み依存関係を持つローカルフォルダー、 + `file:` パッケージインストール、CLI 実行を伴う git インストール、git の移動参照更新、 + 巻き上げられた推移的依存関係を持つ npm レジストリインストール、npm 更新の no-op、 + ローカル ClawHub fixture のインストールと更新 no-op、マーケットプレイス更新挙動、 + Claude バンドルの有効化と検査を検証します。ClawHub ブロックを hermetic/offline に保つには + `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` を設定します。 +- `test:docker:plugin-lifecycle-matrix` は、ベアコンテナに候補パッケージをインストールし、 + npm Plugin をインストール、検査、無効化、有効化、明示的アップグレード、明示的ダウングレード、 + および Plugin コード削除後のアンインストールまで実行します。各フェーズの RSS と CPU メトリクスを記録します。 +- `test:docker:plugin-update` は、未変更のインストール済み Plugin が + `openclaw plugins update` 中に再インストールされたりインストールメタデータを失ったりしないことを検証します。 +- `test:docker:upgrade-survivor` は、汚れた古いユーザー fixture の上に候補 tarball をインストールし、 + パッケージ更新と非対話 doctor を実行してから、loopback Gateway を起動し、状態保存を確認します。 - `test:docker:published-upgrade-survivor` は、まず公開済みベースラインをインストールし、 - 焼き込み済みの `openclaw config set` レシピを通じて設定し、候補tarballへ更新し、 - doctorを実行し、レガシークリーンアップを確認し、Gatewayを起動して、 - `/healthz`、`/readyz`、RPCステータスをプローブします。 -- `test:docker:update-migration` は、クリーンアップが多い公開済み更新レーンです。 - 設定済みのDiscord/Telegram風ユーザー状態から開始し、設定済みPlugin依存関係が - materializeする機会を持てるようにベースライン - doctorを実行し、設定済みのパッケージ化PluginのレガシーPlugin依存関係の残骸をシードし、 - 候補tarballへ更新し、更新後doctorがレガシーの - 依存関係ルートを削除することを要求します。 + baked された `openclaw config set` レシピで設定し、候補 tarball に更新し、doctor を実行し、 + レガシークリーンアップを確認し、Gateway を起動し、`/healthz`、`/readyz`、RPC 状態をプローブします。 +- `test:docker:update-migration` は、クリーンアップが重い公開済み更新レーンです。 + 設定済みの Discord/Telegram 形式のユーザー状態から開始し、設定済み Plugin 依存関係が具現化する機会を得るように + ベースライン doctor を実行し、設定済みのパッケージ化 Plugin のレガシー Plugin 依存関係の残骸をシードし、 + 候補 tarball に更新し、更新後の doctor がレガシー依存関係ルートを削除することを必須にします。 -便利な公開済みアップグレードsurvivorバリアント: +便利な公開済みアップグレードサバイバーのバリアント: ```bash OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \ @@ -129,15 +120,15 @@ OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \ pnpm test:docker:published-upgrade-survivor ``` -利用可能なシナリオは、`base`、`feishu-channel`、`bootstrap-persona`、 -`plugin-deps-cleanup`、`configured-plugin-installs`、`tilde-log-path`、および -`versioned-runtime-deps` です。集約実行では、 -`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` が、設定済みPluginインストール移行を含む、 -報告済みissue形状のすべてのシナリオに展開されます。 +利用可能なシナリオは `base`、`feishu-channel`、`bootstrap-persona`、 +`plugin-deps-cleanup`、`configured-plugin-installs`、 +`stale-source-plugin-shadow`、`tilde-log-path`、`versioned-runtime-deps` です。集約実行では、 +`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` が、設定済み Plugin インストールマイグレーションを含む、 +報告済み issue 形状のすべてのシナリオに展開されます。 -完全な更新移行は、Full Release CIから意図的に分離されています。リリースの問いが「2026.4.23以降のすべての -公開済み安定版リリースがこの候補へ更新でき、 -Plugin依存関係の残骸をクリーンアップできるか」である場合は、手動の `Update Migration` ワークフローを使用します。 +完全な更新マイグレーションは、意図的に Full Release CI から分離されています。リリース上の問いが +「2026.4.23 以降のすべての公開済み stable リリースがこの候補へ更新でき、Plugin 依存関係の残骸をクリーンアップできるか」 +である場合は、手動の `Update Migration` ワークフローを使います。 ```bash gh workflow run update-migration.yml \ @@ -150,33 +141,29 @@ gh workflow run update-migration.yml \ ## Package Acceptance -Package AcceptanceはGitHubネイティブのパッケージゲートです。1つの候補 -パッケージを `package-under-test` tarballへ解決し、バージョンとSHA-256を記録してから、 -その厳密なtarballに対して再利用可能なDocker E2Eレーンを実行します。ワークフローハーネス -refはパッケージソースrefと分離されているため、現在のテストロジックで -古い信頼済みリリースを検証できます。 +Package Acceptance は GitHub ネイティブなパッケージゲートです。1 つの候補パッケージを +`package-under-test` tarball に解決し、バージョンと SHA-256 を記録してから、 +その正確な tarball に対して再利用可能な Docker E2E レーンを実行します。ワークフローハーネスの +ref はパッケージソース ref とは別なので、現在のテストロジックで古い信頼済みリリースを検証できます。 候補ソース: -- `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な - 公開済みバージョンを検証します。 -- `source=ref`: 選択された現在の - ハーネスで、信頼済みブランチ、タグ、またはコミットをパックします。 -- `source=url`: 必須の `package_sha256` を伴うHTTPS tarballを検証します。 -- `source=artifact`: 別のActions実行でアップロードされたtarballを再利用します。 +- `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な公開済みバージョンを検証します。 +- `source=ref`: 選択した現在のハーネスで、信頼済みブランチ、タグ、またはコミットを pack します。 +- `source=url`: 必須の `package_sha256` を指定して HTTPS tarball を検証します。 +- `source=artifact`: 別の Actions 実行でアップロードされた tarball を再利用します。 -Full Release Validationは、解決済みリリースSHAからビルドされた -`source=artifact` をデフォルトで使用します。公開後の証明では、 -同じアップグレードマトリクスが出荷済みnpmパッケージを対象にするように、 -`package_acceptance_package_spec=openclaw@YYYY.M.D` を渡します。 +Full Release Validation は、解決済みリリース SHA から構築された `source=artifact` をデフォルトで使います。 +公開後の証明では、代わりに `package_acceptance_package_spec=openclaw@YYYY.M.D` を渡し、 +同じアップグレードマトリックスが出荷済み npm パッケージを対象にするようにします。 -リリースチェックは、パッケージ/更新/PluginセットでPackage Acceptanceを呼び出します。 +リリースチェックは、パッケージ、更新、Plugin のセットで Package Acceptance を呼び出します。 ```text doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update ``` -次も渡します。 +また、次も渡します。 ```text published_upgrade_survivor_baselines=all-since-2026.4.23 @@ -184,17 +171,16 @@ published_upgrade_survivor_scenarios=reported-issues telegram_mode=mock-openai ``` -これにより、パッケージ移行、更新チャンネル切り替え、古いPlugin依存関係 -クリーンアップ、オフラインPluginカバレッジ、Plugin更新挙動、Telegramパッケージ -QAが、同じ解決済み成果物上に保たれます。 +これにより、パッケージマイグレーション、更新チャンネル切り替え、古い Plugin 依存関係のクリーンアップ、 +offline Plugin カバレッジ、Plugin 更新挙動、Telegram パッケージ QA が、同じ解決済み成果物上に保たれます。 -`all-since-2026.4.23` はFull Release CIのアップグレードサンプルです。`2026.4.23` から `latest` までの、npmで公開されたすべての安定版リリースです。公開済み -更新移行の網羅的なカバレッジでは、Full Release CIではなく、別個のUpdate -Migrationワークフローで `all-since-2026.4.23` を使用します。レガシーの事前日付 -アンカーも必要な場合の手動のより広いサンプリング用として、`release-history` は引き続き -利用可能です。 +`all-since-2026.4.23` は Full Release CI のアップグレードサンプルです。 +`2026.4.23` から `latest` までのすべての stable な npm 公開済みリリースを含みます。 +公開済み更新マイグレーションを網羅的にカバーするには、Full Release CI ではなく、別個の Update +Migration ワークフローで `all-since-2026.4.23` を使います。レガシーの事前日付アンカーも含めて +より広く手動サンプリングしたい場合には、`release-history` も引き続き利用できます。 -リリース前に候補を検証する場合は、パッケージプロファイルを手動で実行します。 +リリース前に候補を検証するときは、パッケージプロファイルを手動で実行します。 ```bash gh workflow run package-acceptance.yml \ @@ -208,71 +194,60 @@ gh workflow run package-acceptance.yml \ -f telegram_mode=mock-openai ``` -リリースの問いにMCPチャンネル、cron/subagentクリーンアップ、OpenAI web search、またはOpenWebUIが含まれる場合は、 -`suite_profile=product` を使用します。完全なDockerリリースパスカバレッジが必要な場合にのみ、 -`suite_profile=full` を使用します。 +リリース上の問いに MCP チャンネル、cron/subagent クリーンアップ、OpenAI web search、または OpenWebUI が含まれる場合は +`suite_profile=product` を使います。完全な Docker リリースパスカバレッジが必要な場合にのみ +`suite_profile=full` を使います。 ## リリースのデフォルト リリース候補では、デフォルトの証明スタックは次のとおりです。 -1. ソースレベルの回帰に対する `pnpm check:changed` と `pnpm test:changed`。 -2. パッケージ成果物の整合性に対する `pnpm release:check`。 -3. インストール/更新/Plugin契約に対するPackage Acceptance `package` プロファイルまたはリリースチェックのカスタムパッケージ - レーン。 -4. OS固有のインストーラー、オンボーディング、プラットフォーム - 挙動に対するクロスOSリリースチェック。 -5. 変更された面がプロバイダーまたはホスト型サービス - 挙動に触れる場合のみライブスイート。 +1. ソースレベルの回帰には `pnpm check:changed` と `pnpm test:changed`。 +2. パッケージ成果物の整合性には `pnpm release:check`。 +3. インストール、更新、Plugin 契約には Package Acceptance の `package` プロファイル、またはリリースチェックのカスタムパッケージレーン。 +4. OS 固有のインストーラー、オンボーディング、プラットフォーム挙動には Cross-OS release checks。 +5. 変更された面がプロバイダーまたはホスト型サービスの挙動に触れる場合のみ、ライブスイート。 -メンテナーのマシンでは、明示的にローカル証明を行っている場合を除き、 -広範なゲートとDocker/パッケージのプロダクト証明はTestboxで実行するべきです。 +メンテナーのマシンでは、明示的にローカル証明を行う場合を除き、広範なゲートと Docker/パッケージ製品証明は +Testbox で実行する必要があります。 ## レガシー互換性 -互換性の寛容さは狭く、期限付きです。 +互換性の緩和は狭く、期限付きです。 -- `2026.4.25-beta.*` を含む `2026.4.25` までのパッケージは、 - Package Acceptanceで、すでに出荷済みのパッケージメタデータのギャップを許容する場合があります。 -- 公開済みの `2026.4.26` パッケージは、すでに出荷済みのローカルビルドメタデータstamp - ファイルについて警告する場合があります。 -- それ以降のパッケージは、現代的な契約を満たす必要があります。同じギャップは - 警告やスキップではなく失敗になります。 +- `2026.4.25` までのパッケージ（`2026.4.25-beta.*` を含む）は、Package Acceptance で + すでに出荷済みのパッケージメタデータの欠落を許容する場合があります。 +- 公開済みの `2026.4.26` パッケージは、すでに出荷済みのローカルビルドメタデータスタンプファイルについて + 警告する場合があります。 +- それ以降のパッケージは、現代的な契約を満たす必要があります。同じ欠落は、警告やスキップではなく失敗になります。 -これらの古い形状に対して、新しい起動時移行を追加しないでください。doctor -修復を追加または拡張し、それを `upgrade-survivor` または `published-upgrade-survivor` で証明します。 +これらの古い形状に対して新しい起動時マイグレーションを追加しないでください。doctor 修復を追加または拡張し、 +`upgrade-survivor` または `published-upgrade-survivor` で証明します。 ## カバレッジの追加 -更新またはPluginの挙動を変更する場合は、正しい理由で失敗できる -最も低いレイヤーにカバレッジを追加します。 +更新または Plugin 挙動を変更する場合は、適切な理由で失敗し得る最も低い層にカバレッジを追加します。 -- 純粋なパスまたはメタデータロジック: ソースの隣のユニットテスト。 -- パッケージインベントリまたはパックされたファイルの挙動: `package-dist-inventory` またはtarball - チェッカーテスト。 -- CLIインストール/更新挙動: Dockerレーンのアサーションまたはフィクスチャ。 -- 公開済みリリースの移行挙動: `published-upgrade-survivor` シナリオ。 -- レジストリ/パッケージソースの挙動: `test:docker:plugins` フィクスチャまたはClawHub - フィクスチャサーバー。 -- 依存関係レイアウトまたはクリーンアップ挙動: ランタイム実行と - ファイルシステム境界の両方をアサートします。npm依存関係は管理対象npm - ルート配下にhoistされる場合があるため、テストではパッケージローカルの - `node_modules` ツリーを仮定するのではなく、ルートがスキャン/クリーンアップされることを証明するべきです。 +- 純粋なパスまたはメタデータロジック: ソースの隣にある単体テスト。 +- パッケージインベントリまたは梱包済みファイルの挙動: `package-dist-inventory` または tarball チェッカーテスト。 +- CLI インストール/更新挙動: Docker レーンのアサーションまたは fixture。 +- 公開済みリリースのマイグレーション挙動: `published-upgrade-survivor` シナリオ。 +- レジストリ/パッケージソースの挙動: `test:docker:plugins` fixture または ClawHub fixture サーバー。 +- 依存関係レイアウトまたはクリーンアップ挙動: ランタイム実行とファイルシステム境界の両方をアサートします。 + npm 依存関係は管理対象の npm ルート配下に巻き上げられる場合があるため、テストでは + パッケージローカルの `node_modules` ツリーを仮定するのではなく、そのルートがスキャン/クリーンアップされることを証明する必要があります。 -新しいDockerフィクスチャはデフォルトでhermeticに保ちます。テストの目的がライブレジストリ挙動でない限り、 -ローカルフィクスチャレジストリと偽パッケージを使用します。 +新しい Docker fixture はデフォルトで hermetic に保ちます。テストの目的がライブレジストリ挙動でない限り、 +ローカル fixture レジストリと fake パッケージを使います。 ## 失敗のトリアージ -成果物の同一性から始めます。 +成果物 ID から開始します。 -- Package Acceptance `resolve_package` サマリー: ソース、バージョン、SHA-256、および - 成果物名。 -- Docker成果物: `.artifacts/docker-tests/**/summary.json`、 +- Package Acceptance の `resolve_package` サマリー: ソース、バージョン、SHA-256、成果物名。 +- Docker 成果物: `.artifacts/docker-tests/**/summary.json`、 `failures.json`、レーンログ、再実行コマンド。 -- アップグレードsurvivorサマリー: `.artifacts/upgrade-survivor/summary.json`。 - ベースラインバージョン、候補バージョン、シナリオ、フェーズタイミング、 - レシピ手順を含みます。 +- アップグレードサバイバーサマリー: `.artifacts/upgrade-survivor/summary.json`。 + ベースラインバージョン、候補バージョン、シナリオ、フェーズタイミング、レシピ手順を含みます。 -リリース全体の傘を再実行するよりも、同じパッケージ成果物で失敗した厳密なレーンを -再実行することを優先します。 +リリース全体の傘を再実行するよりも、同じパッケージ成果物で失敗した正確なレーンを再実行することを優先します。 diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index 3af13a362..b3006ee1a 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -2,167 +2,166 @@ read_when: - ローカルまたは CI でテストを実行する - モデル/プロバイダーのバグに対する回帰テストの追加 - - Gateway とエージェントの挙動のデバッグ -summary: 'テストキット: 単体/e2e/ライブスイート、Docker ランナー、および各テストの対象範囲' + - Gateway + エージェントの挙動のデバッグ +summary: 'テストキット: unit/e2e/live スイート、Docker ランナー、各テストの対象範囲' title: テスト x-i18n: - generated_at: "2026-05-04T07:03:10Z" + generated_at: "2026-05-05T01:47:48Z" model: gpt-5.5 provider: openai - source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 + source_hash: 8d051bf6a01f6caf7755ad1d7107f21ae2d440b55a65bb7f18ee4a81f5f0e3b2 source_path: help/testing.md workflow: 16 --- -OpenClaw には3つの Vitest スイート (unit/integration、e2e、live) と少数の Docker ランナーがあります。このドキュメントは「テスト方法」のガイドです。 +OpenClaw には 3 つの Vitest スイート（unit/integration、e2e、live）と、小規模な Docker ランナー群があります。このドキュメントは「どのようにテストするか」のガイドです。 -- 各スイートがカバーするもの (および意図的にカバーしないもの)。 -- 一般的なワークフロー (ローカル、プッシュ前、デバッグ) で実行するコマンド。 +- 各スイートが何を対象にするか（そして意図的に何を対象にしないか）。 +- 一般的なワークフロー（ローカル、push 前、デバッグ）で実行するコマンド。 - 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 channel](/ja-JP/channels/qa-channel) — リポジトリに支えられたシナリオで使用される合成トランスポートプラグイン。 +- [QA channel](/ja-JP/channels/qa-channel) — リポジトリに基づくシナリオで使用される合成トランスポート Plugin。 -このページでは、通常のテストスイートと Docker/Parallels ランナーの実行について説明します。以下の QA 固有ランナーセクション ([QA-specific runners](#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` +- フルゲート（push 前に期待されるもの）: `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- 余裕のあるマシンでの高速なローカル全スイート実行: `pnpm test:max` - 直接の Vitest watch ループ: `pnpm test:watch` -- 直接のファイル指定は extension/channel パスにもルーティングされるようになりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 単一の失敗を反復調査しているときは、まず対象を絞った実行を優先してください。 +- 直接のファイル指定は、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` +- Linux VM ベースの QA lane: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -テストに触れる場合や、追加の確信が欲しい場合: +テストに触れた場合、または追加の確信がほしい場合: - カバレッジゲート: `pnpm test:coverage` - E2E スイート: `pnpm test:e2e` -実際のプロバイダー/モデルをデバッグする場合 (実際の認証情報が必要): +実際のプロバイダー/モデルをデバッグする場合（実際の認証情報が必要）: -- live スイート (モデル + Gateway ツール/画像プローブ): `pnpm test:live` -- 1つの live ファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- ランタイム性能レポート: 実際の `openai/gpt-5.4` エージェントターンには `live_gpt54=true`、Kova の CPU/ヒープ/トレースアーティファクトには `deep_profile=true` を指定して `OpenClaw Performance` をディスパッチします。毎日のスケジュール実行は、`CLAWGRIT_REPORTS_TOKEN` が設定されている場合、mock-provider、deep-profile、GPT 5.4 レーンのアーティファクトを `openclaw/clawgrit-reports` に公開します。mock-provider レポートには、ソースレベルの Gateway 起動、メモリ、プラグイン負荷、反復 fake-model hello-loop、CLI 起動時間の数値も含まれます。 -- Docker live モデルスイープ: `pnpm test:docker:live-models` - - 選択された各モデルは、テキストターンに加えて小さなファイル読み取り形式のプローブを実行します。メタデータが `image` 入力を示しているモデルでは、小さな画像ターンも実行します。プロバイダーの失敗を切り分ける場合は、`OPENCLAW_LIVE_MODEL_FILE_PROBE=0` または `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` で追加プローブを無効化します。 - - CI カバレッジ: 毎日の `OpenClaw Scheduled Live And E2E Checks` と手動の `OpenClaw Release Checks` はどちらも、`include_live_suites: true` を指定して再利用可能な live/E2E ワークフローを呼び出します。これには、プロバイダーごとにシャードされた個別の Docker live モデルマトリックスジョブが含まれます。 - - 集中的な CI 再実行では、`include_live_suites: true` と `live_models_only: true` を指定して `OpenClaw Live And E2E Checks (Reusable)` をディスパッチします。 - - 新しい高シグナルのプロバイダーシークレットは、`scripts/ci-hydrate-live-auth.sh`、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml`、およびそのスケジュール/リリース呼び出し元に追加します。 -- ネイティブ Codex バインドチャットスモーク: `pnpm test:docker:live-codex-bind` - - Docker live レーンを Codex app-server パスに対して実行し、合成 Slack DM を `/codex bind` でバインドし、`/codex fast` と `/codex permissions` を実行したうえで、通常の返信と画像添付が ACP ではなくネイティブプラグインバインディング経由でルーティングされることを検証します。 -- Codex app-server ハーネススモーク: `pnpm test:docker:live-codex-harness` - - プラグイン所有の Codex app-server ハーネスを通じて Gateway エージェントターンを実行し、`/codex status` と `/codex models` を検証し、デフォルトで画像、cron MCP、サブエージェント、Guardian プローブを実行します。他の Codex app-server の失敗を切り分ける場合は、`OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` でサブエージェントプローブを無効化します。集中的なサブエージェント確認では、他のプローブを無効化します: `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` - - メッセージチャネルレスキューコマンドサーフェスのオプトインの念入りな確認です。`/crestodian status` を実行し、永続的なモデル変更をキューに入れ、`/crestodian yes` に返信し、監査/設定書き込みパスを検証します。 -- Crestodian プランナー Docker スモーク: `pnpm test:docker:crestodian-planner` - - `PATH` 上に偽の Claude CLI がある設定なしコンテナーで Crestodian を実行し、fuzzy プランナーフォールバックが監査付きの型付き設定書き込みに変換されることを検証します。 -- Crestodian 初回実行 Docker スモーク: `pnpm test:docker:crestodian-first-run` - - 空の OpenClaw 状態ディレクトリから開始し、素の `openclaw` を Crestodian にルーティングし、setup/model/agent/Discord プラグイン + SecretRef 書き込みを適用し、設定を検証し、監査エントリを確認します。同じ Ring 0 セットアップパスは、QA Lab でも `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` によってカバーされています。 -- Moonshot/Kimi コストスモーク: `MOONSHOT_API_KEY` を設定した状態で、`openclaw models list --provider moonshot --json` を実行し、次に `moonshot/kimi-k2.6` に対して分離された `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` を実行します。JSON が Moonshot/K2.6 を報告し、アシスタントトランスクリプトが正規化された `usage.cost` を保存していることを確認します。 +- live スイート（モデル + Gateway ツール/画像プローブ）: `pnpm test:live` +- 1 つの live ファイルを静かに対象化: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- ランタイムパフォーマンスレポート: 実際の `openai/gpt-5.4` agent turn には + `live_gpt54=true`、Kova の CPU/heap/trace アーティファクトには + `deep_profile=true` を付けて `OpenClaw Performance` を dispatch します。`CLAWGRIT_REPORTS_TOKEN` が設定されている場合、日次のスケジュール実行は mock-provider、deep-profile、GPT 5.4 lane のアーティファクトを + `openclaw/clawgrit-reports` に公開します。mock-provider レポートには、ソースレベルの Gateway 起動、メモリ、Plugin 圧力、繰り返しの fake-model hello-loop、CLI 起動の数値も含まれます。 +- Docker live model sweep: `pnpm test:docker:live-models` + - 選択された各モデルは、text turn に加えて小さなファイル読み取り風プローブを実行します。 + メタデータが `image` 入力を示すモデルは、小さな画像 turn も実行します。 + プロバイダーの失敗を切り分ける場合は、`OPENCLAW_LIVE_MODEL_FILE_PROBE=0` または + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` で追加プローブを無効にします。 + - CI カバレッジ: 日次の `OpenClaw Scheduled Live And E2E Checks` と手動の + `OpenClaw Release Checks` はどちらも、`include_live_suites: true` を指定して再利用可能な live/E2E workflow を呼び出します。これにはプロバイダー別に shard された個別の Docker live model matrix job が含まれます。 + - 集中的な CI 再実行には、`include_live_suites: true` と `live_models_only: true` を指定して + `OpenClaw Live And E2E Checks (Reusable)` を dispatch します。 + - 高シグナルな新しいプロバイダー secret は、`scripts/ci-hydrate-live-auth.sh` と + `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml`、およびそのスケジュール/リリース呼び出し元に追加します。 +- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` + - Codex app-server パスに対して Docker live lane を実行し、`/codex bind` で合成 + Slack DM を bind し、`/codex fast` と + `/codex permissions` を実行してから、通常の返信と画像添付が ACP ではなく native Plugin binding 経由でルーティングされることを検証します。 +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` + - Plugin 所有の Codex app-server harness 経由で Gateway agent turn を実行し、 + `/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` が設定されていない限り、これは sub-agent プローブの後に終了します。 +- Crestodian rescue command smoke: `pnpm test:live:crestodian-rescue-channel` + - message-channel の救援コマンドサーフェスに対する opt-in の念押しチェックです。 + `/crestodian status` を実行し、永続的なモデル変更をキューに入れ、 + `/crestodian yes` に返信し、audit/config 書き込みパスを検証します。 +- Crestodian planner Docker smoke: `pnpm test:docker:crestodian-planner` + - config なしのコンテナ内で、`PATH` 上の fake Claude CLI とともに Crestodian を実行し、fuzzy planner fallback が監査済みの型付き config 書き込みに変換されることを検証します。 +- Crestodian first-run Docker smoke: `pnpm test:docker:crestodian-first-run` + - 空の OpenClaw state dir から開始し、bare `openclaw` を + Crestodian にルーティングし、setup/model/agent/Discord Plugin + SecretRef 書き込みを適用し、config を検証し、audit entry を確認します。同じ Ring 0 setup パスは QA Lab でも + `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` によりカバーされています。 +- Moonshot/Kimi cost smoke: `MOONSHOT_API_KEY` を設定した状態で + `openclaw models list --provider moonshot --json` を実行し、その後 + `moonshot/kimi-k2.6` に対して分離された + `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` + を実行します。JSON が Moonshot/K2.6 を報告し、assistant transcript が正規化された `usage.cost` を保存することを検証します。 -失敗しているケースが1つだけ必要な場合は、以下で説明する allowlist 環境変数で live テストを絞り込むことを優先してください。 +失敗ケースが 1 つだけ必要な場合は、下記の allowlist env vars で live テストを絞り込むことを優先してください。 -## QA 固有ランナー +## QA 専用ランナー -QA-lab の現実性が必要な場合、これらのコマンドはメインのテストスイートの横に位置します。 +QA-lab の実環境感が必要な場合、これらのコマンドはメインのテストスイートの横にあります。 -CI は専用ワークフローで QA Lab を実行します。エージェント的パリティは `QA-Lab - All Lanes` とリリース検証の下にネストされており、単独の PR ワークフローではありません。広範な検証には、`rerun_group=qa-parity` または release-checks QA グループを指定した `Full Release Validation` を使用してください。`QA-Lab - All Lanes` は `main` で毎晩実行され、手動ディスパッチからは mock parity レーン、live Matrix レーン、Convex 管理の live Telegram レーン、Convex 管理の live 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` を使用するため、決定的であり、通常のプロバイダープラグイン起動を避けられます。これらの live トランスポート Gateway はメモリ検索を無効化します。メモリ動作は QA パリティスイートで引き続きカバーされます。 +CI は専用 workflow で QA Lab を実行します。Agentic parity はスタンドアロンの PR workflow ではなく、 +`QA-Lab - All Lanes` とリリース検証の下にネストされています。 +広範な検証では、`rerun_group=qa-parity` または release-checks QA group を指定した `Full Release Validation` を使用します。stable/default release checks では、網羅的な live/Docker soak は `run_release_soak=true` の背後に維持されます。`full` profile では soak が強制的に有効になります。`QA-Lab - All Lanes` は `main` で nightly に実行され、手動 dispatch からは mock parity lane、live Matrix lane、Convex 管理の live Telegram lane、Convex 管理の live Discord lane が並列 job として実行されます。Scheduled QA と release checks は Matrix に +`--profile fast` を明示的に渡しますが、Matrix CLI と手動 workflow input のデフォルトは `all` のままです。手動 dispatch では、`all` を `transport`、 +`media`、`e2ee-smoke`、`e2ee-deep`、`e2ee-cli` job に shard できます。`OpenClaw Release +Checks` は、リリース承認前に parity と fast Matrix および Telegram lanes を実行します。release transport checks には `mock-openai/gpt-5.5` を使用するため、決定的になり、通常の provider-plugin 起動を避けられます。これらの live transport +gateways はメモリ検索を無効にしています。メモリ挙動は QA parity +suites で引き続きカバーされます。 -完全リリースの live media シャードは `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` を使用します。これにはすでに `ffmpeg` と `ffprobe` が含まれています。Docker live モデル/バックエンドシャードは、選択されたコミットごとに一度だけビルドされる共有の `ghcr.io/openclaw/openclaw-live-test:` イメージを使用し、各シャード内で再ビルドする代わりに `OPENCLAW_SKIP_DOCKER_BUILD=1` でそれを pull します。 +フルリリースの live media shard は +`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` を使用します。これにはすでに +`ffmpeg` と `ffprobe` が含まれています。Docker live model/backend shard は、選択された commit ごとに一度だけビルドされる共有 +`ghcr.io/openclaw/openclaw-live-test:` image を使用し、各 shard 内で再ビルドする代わりに +`OPENCLAW_SKIP_DOCKER_BUILD=1` で pull します。 - `pnpm openclaw qa suite` - - リポジトリに裏付けられた QA シナリオをホスト上で直接実行します。 + - リポジトリに基づく QA シナリオをホスト上で直接実行します。 - デフォルトでは、選択された複数のシナリオを、分離された - Gateway ワーカーで並列実行します。`qa-channel` のデフォルト並列数は 4 です - （選択されたシナリオ数が上限）。ワーカー数を調整するには `--concurrency ` を、 - 以前のシリアルレーンを使うには `--concurrency 1` を使用します。 - - いずれかのシナリオが失敗するとゼロ以外で終了します。失敗の終了コードなしで - アーティファクトが必要な場合は `--allow-failures` を使用します。 - - プロバイダーモード `live-frontier`、`mock-openai`、`aimock` をサポートします。 - `aimock` は、シナリオ対応の `mock-openai` レーンを置き換えずに、実験的な - フィクスチャとプロトコルモックのカバレッジ用に、ローカルの AIMock ベースの - プロバイダーサーバーを起動します。 + Gateway ワーカーで並列実行します。`qa-channel` のデフォルト同時実行数は 4 です（選択されたシナリオ数で上限が決まります）。ワーカー数を調整するには `--concurrency ` を使用し、以前の直列レーンには `--concurrency 1` を使用します。 + - いずれかのシナリオが失敗すると、ゼロ以外で終了します。失敗終了コードなしでアーティファクトが必要な場合は `--allow-failures` を使用します。 + - provider モード `live-frontier`、`mock-openai`、`aimock` をサポートします。 + `aimock` は、シナリオ対応の `mock-openai` レーンを置き換えずに、実験的なフィクスチャとプロトコルモックのカバレッジ用に、ローカルの AIMock ベース provider サーバーを起動します。 +- `pnpm test:plugins:kitchen-sink-live` + - QA Lab 経由でライブ OpenAI Kitchen Sink Plugin ガントレットを実行します。外部 Kitchen Sink パッケージをインストールし、Plugin SDK サーフェスのインベントリを検証し、`/healthz` と `/readyz` をプローブし、Gateway CPU/RSS の証拠を記録し、ライブ OpenAI ターンを実行して、敵対的診断をチェックします。 + `OPENAI_API_KEY` などのライブ OpenAI 認証が必要です。ハイドレート済みの Testbox セッションでは、`openclaw-testbox-env` ヘルパーが存在する場合、Testbox ライブ認証プロファイルを自動的に読み込みます。 - `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 起動ベンチに加えて、小さなモック 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` アーティファクトを使用します。チェックアウトに新しいランタイム出力がまだない場合は、先にビルドを実行してください。 - `pnpm openclaw qa suite --runner multipass` - 同じ QA スイートを使い捨ての Multipass Linux VM 内で実行します。 - ホスト上の `qa suite` と同じシナリオ選択動作を維持します。 - - `qa suite` と同じプロバイダー/モデル選択フラグを再利用します。 - - ライブ実行では、ゲストで実用的なサポート対象の QA 認証入力を転送します。 - env ベースのプロバイダーキー、QA ライブプロバイダー設定パス、および存在する場合の - `CODEX_HOME` です。 - - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるように、 - リポジトリルート配下に置く必要があります。 - - 通常の QA レポートとサマリーに加え、Multipass ログを + - `qa suite` と同じ provider/モデル選択フラグを再利用します。 + - ライブ実行では、ゲストで実用的なサポート対象 QA 認証入力を転送します: + env ベースの provider キー、QA ライブ provider 設定パス、および存在する場合の `CODEX_HOME`。 + - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるように、リポジトリルート配下に留める必要があります。 + - 通常の QA レポートとサマリーに加えて、Multipass ログを `.artifacts/qa-e2e/...` 配下に書き込みます。 - `pnpm qa:lab:up` - オペレーター形式の 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` を使用します。 + - 現在のチェックアウトから npm tarball をビルドし、Docker 内にグローバルインストールし、非対話型の OpenAI API キーオンボーディングを実行し、デフォルトで Telegram を設定し、パッケージ化された Plugin ランタイムが起動時の依存関係修復なしで読み込まれることを検証し、doctor を実行して、モックされた OpenAI エンドポイントに対してローカルエージェントターンを 1 回実行します。 + - 同じパッケージ化インストールレーンを Discord で実行するには、`OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使用します。 - `pnpm test:docker:session-runtime-context` - - 埋め込みランタイムコンテキストトランスクリプト用に、決定的なビルド済みアプリの - Docker スモークを実行します。非表示の OpenClaw ランタイムコンテキストが、 - 表示されるユーザーターンに漏れず、非表示カスタムメッセージとして永続化されることを検証し、 - その後、影響を受ける壊れたセッション JSONL を投入して、 - `openclaw doctor --fix` がバックアップ付きでアクティブブランチへ書き換えることを検証します。 + - 埋め込みランタイムコンテキスト transcript 用の決定的なビルド済みアプリ Docker smoke を実行します。非表示の OpenClaw ランタイムコンテキストが、表示されるユーザーターンへ漏れず、非表示のカスタムメッセージとして永続化されることを検証します。その後、影響を受ける壊れたセッション JSONL を投入し、`openclaw doctor --fix` がバックアップ付きでアクティブブランチへ書き換えることを検証します。 - `pnpm test:docker:npm-telegram-live` - - OpenClaw パッケージ候補を Docker にインストールし、インストール済みパッケージの - オンボーディングを実行し、インストール済み CLI 経由で Telegram を設定し、 - その後、そのインストール済みパッケージを SUT Gateway として使ってライブ Telegram QA レーンを再利用します。 - - デフォルトは `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` です。 - レジストリからインストールする代わりに、解決済みのローカル tarball をテストするには - `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` または - `OPENCLAW_CURRENT_PACKAGE_TGZ` を設定します。 - - `pnpm openclaw qa telegram` と同じ Telegram env 認証情報、または Convex - 認証情報ソースを使用します。CI/リリース自動化では、 - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` に加えて - `OPENCLAW_QA_CONVEX_SITE_URL` とロールシークレットを設定します。CI に - `OPENCLAW_QA_CONVEX_SITE_URL` と Convex ロールシークレットがある場合、 - Docker ラッパーは Convex を自動選択します。 - - ラッパーは、Docker のビルド/インストール作業の前に、ホスト上で Telegram または - Convex 認証情報 env を検証します。認証情報前のセットアップを意図的にデバッグする場合にのみ - `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` を設定します。 - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` は、このレーンだけで共有の + - Docker 内に OpenClaw パッケージ候補をインストールし、インストール済みパッケージのオンボーディングを実行し、インストール済み CLI 経由で Telegram を設定し、そのインストール済みパッケージを SUT Gateway としてライブ Telegram QA レーンで再利用します。 + - デフォルトは `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` です。レジストリからインストールする代わりに解決済みのローカル tarball をテストするには、`OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` または `OPENCLAW_CURRENT_PACKAGE_TGZ` を設定します。 + - `pnpm openclaw qa telegram` と同じ Telegram env 認証情報または Convex 認証情報ソースを使用します。CI/リリース自動化では、`OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` に加えて `OPENCLAW_QA_CONVEX_SITE_URL` とロールシークレットを設定します。CI に `OPENCLAW_QA_CONVEX_SITE_URL` と Convex ロールシークレットが存在する場合、Docker ラッパーは Convex を自動選択します。 + - ラッパーは、Docker のビルド/インストール作業前に、ホスト上の Telegram または Convex 認証情報 env を検証します。事前認証情報セットアップを意図的にデバッグする場合にのみ、`OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` を設定します。 + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` は、このレーンだけに対して共有の `OPENCLAW_QA_CREDENTIAL_ROLE` を上書きします。 - - GitHub Actions はこのレーンを手動メンテナー向けワークフロー + - 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 は、1 つの候補パッケージに対するサイドラン製品証明として `Package Acceptance` も公開します。信頼済み ref、公開済み npm spec、SHA-256 付き HTTPS tarball URL、または別の実行からの tarball アーティファクトを受け取り、正規化された `openclaw-current.tgz` を `package-under-test` としてアップロードし、その後、smoke、package、product、full、または custom のレーンプロファイルで既存の Docker E2E スケジューラーを実行します。同じ `package-under-test` アーティファクトに対して Telegram QA ワークフローを実行するには、`telegram_mode=mock-openai` または `live-frontier` を設定します。 + - 最新 beta 製品証明: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -193,68 +192,45 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - 現在の OpenClaw ビルドを Docker 内でパックしてインストールし、OpenAI が設定された状態で - Gateway を起動し、その後、設定編集によりバンドル済みチャネル/Plugin を有効化します。 - - セットアップ検出で未設定のダウンロード可能 Plugin が存在しないままであること、 - 最初に設定された doctor 修復で不足している各ダウンロード可能 Plugin が明示的にインストールされること、 - 2 回目の再起動で非表示の依存関係修復が実行されないことを検証します。 - - また、既知の古い npm ベースラインをインストールし、 - `openclaw update --tag ` の実行前に Telegram を有効化し、候補の - 更新後 doctor がハーネス側の postinstall 修復なしでレガシー Plugin 依存関係の残骸を - クリーンアップすることを検証します。 + - 現在の OpenClaw ビルドを Docker 内でパックしてインストールし、OpenAI を設定した Gateway を起動し、その後、設定編集によって同梱チャネル/Plugin を有効化します。 + - セットアップ検出によって未設定のダウンロード可能 Plugin が存在しないままになること、最初に設定された doctor 修復が不足している各ダウンロード可能 Plugin を明示的にインストールすること、2 回目の再起動では隠れた依存関係修復が実行されないことを検証します。 + - 既知の古い npm ベースラインもインストールし、`openclaw update --tag ` を実行する前に Telegram を有効化し、候補の更新後 doctor が、ハーネス側の postinstall 修復なしでレガシー Plugin 依存関係の残骸を消去することを検証します。 - `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 readiness、およびローカルエージェントターン 1 回を検証します。 + - 1 つのゲストで反復作業する場合は、`--platform macos`、`--platform windows`、または `--platform linux` を使用します。サマリーアーティファクトパスとレーンごとのステータスには `--json` を使用します。 + - OpenAI レーンは、デフォルトでライブエージェントターン証明に `openai/gpt-5.5` を使用します。別の OpenAI モデルを意図的に検証する場合は、`--model ` を渡すか、`OPENCLAW_PARALLELS_OPENAI_MODEL` を設定します。 + - Parallels トランスポートの停止が残りのテスト時間を消費しないように、長いローカル実行はホスト timeout でラップします: ```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 サーフェスを実行します。これは、エージェントターン自体が単純なテキスト応答だけをチェックする場合でも、speech、image generation、media understanding などの capability facade が同梱ランタイム API 経由で読み込まれるためです。 - `pnpm openclaw qa aimock` - - 直接のプロトコルスモークテスト用に、ローカル AIMock プロバイダーサーバーだけを起動します。 + - 直接のプロトコル smoke テスト用に、ローカル AIMock provider サーバーだけを起動します。 - `pnpm openclaw qa matrix` - - 使い捨ての Docker ベース Tuwunel ホームサーバーに対して Matrix ライブ QA レーンを実行します。ソースチェックアウトのみです。パッケージ化インストールには `qa-lab` は含まれません。 + - 使い捨ての Docker ベース Tuwunel homeserver に対して Matrix ライブ QA レーンを実行します。ソースチェックアウト専用です。パッケージ化インストールには `qa-lab` は含まれません。 - 完全な CLI、プロファイル/シナリオカタログ、env vars、アーティファクトレイアウト: [Matrix QA](/ja-JP/concepts/qa-matrix)。 - `pnpm openclaw qa telegram` - - env のドライバーと SUT ボットトークンを使用して、実際の非公開グループに対して 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 つの異なるボットが必要で、SUT ボットは Telegram ユーザー名を公開している必要があります。 - - 安定したボット間観測のために、両方のボットで `@BotFather` の Bot-to-Bot Communication Mode を有効化し、ドライバーボットがグループのボットトラフィックを観測できるようにしてください。 - - Telegram QA レポート、サマリー、観測メッセージアーティファクトを `.artifacts/qa-e2e/...` 配下に書き込みます。返信シナリオには、ドライバー送信要求から観測された SUT 返信までの RTT が含まれます。 + - env のドライバーおよび 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` を使用します。 + - 同じプライベートグループ内に、SUT bot が Telegram username を公開している 2 つの異なる bot が必要です。 + - bot 間の安定した観測のために、両方の bot で `@BotFather` の Bot-to-Bot Communication Mode を有効化し、ドライバー bot がグループ内 bot トラフィックを観測できるようにしてください。 + - Telegram QA レポート、サマリー、および observed-messages アーティファクトを `.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） +### 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 プロジェクトスキャフォールド: @@ -263,12 +239,12 @@ QA lab は Convex ベースのプールから排他的リースを取得し、 必須 env vars: - `OPENCLAW_QA_CONVEX_SITE_URL`（例: `https://your-deployment.convex.site`） -- 選択されたロール用のシークレット 1 つ: +- 選択したロール用のシークレット 1 つ: - `maintainer` 用の `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` - `ci` 用の `OPENCLAW_QA_CONVEX_SECRET_CI` -- 認証情報ロール選択: +- 認証情報ロールの選択: - CLI: `--credential-role maintainer|ci` - - Env デフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（CI ではデフォルト `ci`、それ以外では `maintainer`） + - env デフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（CI ではデフォルトで `ci`、それ以外では `maintainer`） 任意の env vars: @@ -277,13 +253,13 @@ QA lab は Convex ベースのプールから排他的リースを取得し、 - `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_CREDENTIAL_OWNER_ID`（任意の trace id） - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` は、ローカル専用開発向けに loopback `http://` Convex URL を許可します。 -通常運用では、`OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使用する必要があります。 +`OPENCLAW_QA_CONVEX_SITE_URL` は通常運用では `https://` を使用する必要があります。 -メンテナー管理コマンド（プールの追加/削除/一覧）には、 -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が明示的に必要です。 +メンテナーの管理コマンド (pool add/remove/list) には、特に +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 メンテナー向け CLI ヘルパー: @@ -294,9 +270,12 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Use `doctor` は、ライブ実行の前に Convex サイト URL、ブローカーシークレット、エンドポイントプレフィックス、HTTP タイムアウト、admin/list 到達性を、シークレット値を出力せずに確認するために使用します。スクリプトや CI ユーティリティで機械可読な出力が必要な場合は `--json` を使用します。 +live 実行の前に `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 }` @@ -304,18 +283,18 @@ Use `doctor` は、ライブ実行の前に Convex サイト URL、ブローカ - 枯渇/再試行可能: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - リクエスト: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - 成功: `{ status: "ok" }`（または空の `2xx`） + - 成功: `{ status: "ok" }` (または空の `2xx`) - `POST /release` - リクエスト: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - - 成功: `{ status: "ok" }`（または空の `2xx`） -- `POST /admin/add`（メンテナーシークレットのみ） + - 成功: `{ status: "ok" }` (または空の `2xx`) +- `POST /admin/add` (メンテナーシークレットのみ) - リクエスト: `{ kind, actorId, payload, note?, status? }` - 成功: `{ status: "ok", credential }` -- `POST /admin/remove`（メンテナーシークレットのみ） +- `POST /admin/remove` (メンテナーシークレットのみ) - リクエスト: `{ credentialId, actorId }` - 成功: `{ status: "ok", changed, credential }` - - アクティブリースガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（メンテナーシークレットのみ） + - アクティブなリースガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (メンテナーシークレットのみ) - リクエスト: `{ kind?, status?, includePayload?, limit? }` - 成功: `{ status: "ok", credentials, count }` @@ -327,233 +306,263 @@ 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` シャードセットを使用し、並列スケジューリングのためにマルチプロジェクトシャードをプロジェクトごとの設定に展開する場合があります +- 設定: ターゲット指定なしの実行では `vitest.full-*.config.ts` シャードセットを使用し、並列スケジューリングのためにマルチプロジェクトシャードをプロジェクトごとの設定へ展開する場合があります - ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下のコア/ユニットインベントリ。UI ユニットテストは専用の `unit-ui` シャードで実行されます -- 範囲: +- スコープ: - 純粋なユニットテスト - - インプロセス統合テスト（Gateway 認証、ルーティング、ツール、解析、設定） + - プロセス内統合テスト (gateway 認証、ルーティング、ツール、解析、設定) - 既知のバグに対する決定的な回帰テスト - 期待値: - - CI で実行される - - 実キーは不要 - - 高速かつ安定しているべき - - リゾルバーと公開サーフェスのローダーテストは、実際の同梱 Plugin ソース API ではなく、生成された小さな Plugin フィクスチャを使って、広範な `api.js` と `runtime-api.js` のフォールバック動作を証明する必要があります。実 Plugin API のロードは、Plugin 所有の契約/統合スイートに属します。 + - CI で実行されます + - 実際のキーは不要です + - 高速で安定しているべきです + - リゾルバーと公開サーフェスローダーのテストは、実際の同梱 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/Plugin 作業が無関係なスイートを飢餓状態にすることを避けます。 + - ターゲット指定なしの `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` ファイル、明示的なソースマッピング、ローカルインポートグラフ依存先が対象です。設定/セットアップ/パッケージの編集では、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を明示的に使用しない限り、テストは広範囲に実行されません。 - - `pnpm check:changed` は、狭い作業に対する通常のスマートローカルチェックゲートです。差分をコア、コアテスト、Plugin、Plugin テスト、アプリ、ドキュメント、リリースメタデータ、ライブ Docker ツール、ツール類に分類し、対応する型チェック、lint、ガードコマンドを実行します。Vitest テストは実行しません。テスト証明には `pnpm test:changed` または明示的な `pnpm test ` を呼び出してください。リリースメタデータのみのバージョン更新では、対象を絞ったバージョン/設定/ルート依存関係チェックが実行され、トップレベルのバージョンフィールド以外のパッケージ変更を拒否するガードがあります。 - - ライブ Docker ACP ハーネスの編集では、焦点を絞ったチェックが実行されます。ライブ Docker 認証スクリプトのシェル構文と、ライブ Docker スケジューラーのドライランです。`package.json` の変更は、差分が `scripts["test:docker:live-*"]` に限定される場合のみ含まれます。依存関係、export、バージョン、その他のパッケージサーフェス編集では、引き続きより広範なガードが使用されます。 - - エージェント、コマンド、Plugin、auto-reply ヘルパー、`plugin-sdk`、類似の純粋なユーティリティ領域のインポート軽量なユニットテストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンを通ります。ステートフル/ランタイム負荷の高いファイルは既存のレーンに残ります。 - - 選択された `plugin-sdk` と `commands` のヘルパーソースファイルも、変更モード実行をこれらの軽量レーン内の明示的な兄弟テストにマップするため、ヘルパー編集でそのディレクトリの重いスイート全体を再実行せずに済みます。 - - `auto-reply` には、トップレベルのコアヘルパー、トップレベルの `reply.*` 統合テスト、`src/auto-reply/reply/**` サブツリー用の専用バケットがあります。CI ではさらに reply サブツリーを agent-runner、dispatch、commands/state-routing シャードに分割し、インポート負荷の高い 1 つのバケットが Node の末尾全体を占有しないようにします。 - - 通常の PR/main CI は、意図的に Plugin バッチスイープとリリース専用の `agentic-plugins` シャードをスキップします。Full Release Validation は、リリース候補に対して Plugin/Plugin 負荷の高いこれらのスイートを実行する別個の `Plugin Prerelease` 子ワークフローをディスパッチします。 + - `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` ファイル、明示的なソースマッピング、ローカルインポートグラフの依存先です。設定/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 ` を呼び出してください。リリースメタデータのみのバージョンバンプでは、ターゲットを絞った version/config/root-dependency チェックを実行し、トップレベルの version フィールド以外の package 変更を拒否するガードがあります。 + - live Docker ACP ハーネスの編集では、焦点を絞ったチェックを実行します: live Docker 認証スクリプトのシェル構文と、live Docker スケジューラーの dry-run です。`package.json` の変更は、diff が `scripts["test:docker:live-*"]` に限定される場合にのみ含まれます。依存関係、export、version、その他の package サーフェス編集は引き続きより広範なガードを使用します。 + - agents、commands、plugins、auto-reply ヘルパー、`plugin-sdk`、および類似の純粋なユーティリティ領域からの import-light なユニットテストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンにルーティングされます。ステートフル/ランタイムが重いファイルは既存のレーンに残ります。 + - 選択された `plugin-sdk` と `commands` のヘルパーソースファイルも、changed-mode の実行をこれらの軽量レーン内の明示的な兄弟テストにマッピングするため、ヘルパー編集ではそのディレクトリの重いスイート全体を再実行せずに済みます。 + - `auto-reply` には、トップレベルのコアヘルパー、トップレベルの `reply.*` 統合テスト、`src/auto-reply/reply/**` サブツリー用の専用バケットがあります。CI ではさらに reply サブツリーを agent-runner、dispatch、commands/state-routing シャードに分割するため、import が重い 1 つのバケットが Node テール全体を占有しません。 + - 通常の PR/main CI は、extension バッチスイープとリリース専用の `agentic-plugins` シャードを意図的にスキップします。Full Release Validation は、リリース候補に対して、これらの Plugin/extension が重いスイート用の別個の `Plugin Prerelease` 子ワークフローをディスパッチします。 - + - - message-tool 探索入力または Compaction ランタイムコンテキストを変更する場合は、両方のレベルのカバレッジを維持してください。 - - 純粋なルーティング境界と正規化境界には、焦点を絞ったヘルパー回帰テストを追加してください。 - - 埋め込みランナー統合スイートを健全に保ってください: - `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, and - `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - これらのスイートは、スコープ付き ID と Compaction 動作が実際の `run.ts` / `compact.ts` パスを通って流れ続けることを検証します。ヘルパーのみのテストは、これらの統合パスの十分な代替にはなりません。 + - メッセージツール探索入力または Compaction ランタイム + コンテキストを変更する場合は、両方のレベルのカバレッジを維持してください。 + - 純粋なルーティングと正規化境界のために、焦点を絞ったヘルパー回帰テストを追加します。 + - 組み込みランナー統合スイートを健全に保ってください: + `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` パスを通って流れ続けることを検証します。ヘルパーのみのテストは、 + これらの統合パスの十分な代替にはなりません。 - ベース Vitest 設定のデフォルトは `threads` です。 - - 共有 Vitest 設定は `isolate: false` を固定し、ルートプロジェクト、e2e、ライブ設定全体で非分離ランナーを使用します。 - - ルート UI レーンは独自の `jsdom` セットアップと optimizer を維持しますが、共有の非分離ランナー上でも実行されます。 - - 各 `pnpm test` シャードは、共有 Vitest 設定から同じ `threads` + `isolate: false` デフォルトを継承します。 - - `scripts/run-vitest.mjs` は、大きなローカル実行中の V8 コンパイル churn を減らすため、デフォルトで Vitest 子 Node プロセスに `--no-maglev` を追加します。標準の V8 動作と比較するには `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 + - 共有 Vitest 設定は `isolate: false` を固定し、ルートプロジェクト、e2e、live 設定全体で + 非分離ランナーを使用します。 + - ルート UI レーンは `jsdom` setup と optimizer を維持しますが、共有の非分離ランナーでも実行されます。 + - 各 `pnpm test` シャードは、共有 Vitest 設定から同じ `threads` + `isolate: false` + デフォルトを継承します。 + - `scripts/run-vitest.mjs` は、大規模なローカル実行中の V8 コンパイル churn を減らすために、 + デフォルトで Vitest 子 Node プロセスに `--no-maglev` を追加します。 + 標準の V8 動作と比較するには `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定します。 - - `pnpm changed:lanes` は、差分がどのアーキテクチャレーンをトリガーするかを表示します。 - - pre-commit hook はフォーマットのみです。フォーマット済みファイルを再ステージし、lint、型チェック、テストは実行しません。 - - スマートローカルチェックゲートが必要な場合は、引き渡しまたは push の前に `pnpm check:changed` を明示的に実行してください。 - - `pnpm test:changed` はデフォルトで低コストのスコープ付きレーンを通ります。エージェントがハーネス、設定、パッケージ、契約の編集に本当に広範な Vitest カバレッジが必要だと判断した場合のみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 - - `pnpm test:max` と `pnpm test:changed:max` は同じルーティング動作を維持し、worker 上限だけを高くします。 - - ローカル worker の自動スケーリングは意図的に保守的で、ホストのロードアベレージがすでに高い場合は後退するため、複数の同時 Vitest 実行による影響はデフォルトで小さくなります。 - - ベース Vitest 設定は、テスト配線が変更されたときに変更モードの再実行が正しく保たれるよう、プロジェクト/設定ファイルを `forceRerunTriggers` としてマークします。 - - 設定は、サポートされるホストで `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効に保ちます。直接プロファイリング用に明示的なキャッシュ場所を 1 つ指定したい場合は、`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 + - `pnpm changed:lanes` は、diff がどのアーキテクチャレーンをトリガーするかを示します。 + - pre-commit フックは formatting のみです。フォーマット済みファイルを再ステージし、 + lint、typecheck、テストは実行しません。 + - ハンドオフまたは push 前にスマートローカルチェックゲートが必要な場合は、 + `pnpm check:changed` を明示的に実行してください。 + - `pnpm test:changed` はデフォルトで低コストなスコープ付きレーンを経由します。agent が + ハーネス、設定、package、またはコントラクト編集により広範な Vitest カバレッジが本当に必要だと + 判断した場合にのみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 + - `pnpm test:max` と `pnpm test:changed:max` は同じルーティング動作を維持し、 + ワーカー上限だけを高くします。 + - ローカルワーカーの自動スケーリングは意図的に保守的で、ホストの load average がすでに高い場合は + 後退するため、複数の同時 Vitest 実行による影響はデフォルトで抑えられます。 + - ベース Vitest 設定は、プロジェクト/設定ファイルを `forceRerunTriggers` としてマークするため、 + テスト配線が変更されたときも changed-mode の再実行は正しく保たれます。 + - 設定は対応ホストで `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効に保ちます。直接プロファイリング用に + 明示的なキャッシュ場所を 1 つ使いたい場合は、`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 - - `pnpm test:perf:imports` は、Vitest のインポート時間レポートと import-breakdown 出力を有効にします。 - - `pnpm test:perf:imports:changed` は、同じプロファイリングビューを `origin/main` 以降に変更されたファイルへスコープします。 - - シャードのタイミングデータは `.artifacts/vitest-shard-timings.json` に書き込まれます。設定全体の実行では設定パスをキーとして使用します。include-pattern CI シャードでは、フィルター済みシャードを個別に追跡できるようにシャード名を追加します。 - - 1 つのホットテストが依然として起動時インポートに時間の大半を費やす場合は、重い依存関係を狭いローカル `*.runtime.ts` シームの背後に置き、単に `vi.mock(...)` に渡すためにランタイムヘルパーをディープインポートするのではなく、そのシームを直接 mock してください。 - - `pnpm test:perf:changed:bench -- --ref ` は、コミット済み差分に対するルーティング済み `test:changed` とネイティブルートプロジェクトパスを比較し、ウォールタイムと macOS 最大 RSS を出力します。 - - `pnpm test:perf:changed:bench -- --worktree` は、変更されたファイルリストを `scripts/test-projects.mjs` とルート Vitest 設定に通すことで、現在の dirty tree をベンチマークします。 - - `pnpm test:perf:profile:main` は、Vitest/Vite の起動と変換オーバーヘッドのためのメインスレッド CPU プロファイルを書き込みます。 - - `pnpm test:perf:profile:runner` は、ファイル並列性を無効にしたユニットスイートの runner CPU+heap プロファイルを書き込みます。 + - `pnpm test:perf:imports` は、Vitest の import-duration レポートと + import-breakdown 出力を有効にします。 + - `pnpm test:perf:imports:changed` は、同じプロファイリングビューを + `origin/main` 以降に変更されたファイルへスコープします。 + - シャードのタイミングデータは `.artifacts/vitest-shard-timings.json` に書き込まれます。 + config 全体の実行では config パスをキーとして使用します。include-pattern CI + シャードはシャード名を追加するため、フィルター済みシャードを別々に追跡できます。 + - 1 つのホットなテストがまだ時間の大半を起動時の import に費やしている場合は、 + 重い依存関係を狭いローカル `*.runtime.ts` シームの背後に置き、 + runtime ヘルパーを `vi.mock(...)` に渡すためだけに deep-import するのではなく、 + そのシームを直接モックしてください。 + - `pnpm test:perf:changed:bench -- --ref ` は、ルーティングされた + `test:changed` を、そのコミット済み diff に対するネイティブルートプロジェクトパスと比較し、 + wall time と macOS max RSS を出力します。 + - `pnpm test:perf:changed:bench -- --worktree` は、変更されたファイル一覧を + `scripts/test-projects.mjs` とルート Vitest 設定にルーティングして、現在の + dirty tree をベンチマークします。 + - `pnpm test:perf:profile:main` は、Vitest/Vite 起動と transform オーバーヘッドのための + main-thread CPU プロファイルを書き込みます。 + - `pnpm test:perf:profile:runner` は、ファイル並列処理を無効にした unit スイート用の + runner CPU+heap プロファイルを書き込みます。 -### 安定性（Gateway） +### 安定性 (gateway) - コマンド: `pnpm test:stability:gateway` -- 設定: `vitest.gateway.config.ts`、1 worker に強制 -- 範囲: - - 診断をデフォルトで有効にした実際の loopback Gateway を開始します - - 合成 Gateway メッセージ、メモリ、大容量ペイロード churn を診断イベントパス経由で駆動します +- 設定: `vitest.gateway.config.ts`、1 ワーカーに強制 +- スコープ: + - 診断をデフォルトで有効にした実際の local loopback Gateway を開始します + - synthetic gateway メッセージ、メモリ、大きなペイロードの churn を診断イベントパスへ流します - Gateway WS RPC 経由で `diagnostics.stability` を問い合わせます - - 診断安定性バンドルの永続化ヘルパーをカバーします - - レコーダーが上限内に収まり続けること、合成 RSS サンプルがプレッシャーバジェット未満に留まること、セッションごとのキュー深度がゼロに戻って drain されることをアサートします + - 診断安定性バンドル永続化ヘルパーをカバーします + - recorder が境界内に保たれ、synthetic RSS サンプルが pressure budget 未満に収まり、セッションごとのキュー深度がゼロへ戻ることをアサートします - 期待値: - CI セーフでキー不要 - - 安定性回帰フォローアップ用の狭いレーンであり、Gateway スイート全体の代替ではありません + - 安定性回帰のフォローアップ向けの狭いレーンであり、完全な Gateway スイートの代替ではありません -### E2E（Gateway スモーク） +### E2E (gateway smoke) - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` -- ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`、および `extensions/` 配下のバンドルPlugin E2E テスト +- ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`、および `extensions/` 配下のバンドル Plugin E2E テスト - ランタイムのデフォルト: - - リポジトリの他の部分と同様に、`isolate: false` で Vitest `threads` を使用する。 - - 適応型ワーカーを使用する（CI: 最大 2、ローカル: デフォルトで 1）。 - - コンソール I/O オーバーヘッドを減らすため、デフォルトではサイレントモードで実行する。 -- 便利なオーバーライド: - - `OPENCLAW_E2E_WORKERS=` でワーカー数を強制する（上限 16）。 - - `OPENCLAW_E2E_VERBOSE=1` で詳細なコンソール出力を再有効化する。 -- スコープ: - - 複数インスタンス Gateway のエンドツーエンド動作 - - WebSocket/HTTP サーフェス、ノードペアリング、およびより重いネットワーク処理 + - リポジトリの他の部分と同じく、`isolate: false` で Vitest `threads` を使用します。 + - 適応型ワーカーを使用します（CI: 最大 2、ローカル: デフォルトで 1）。 + - コンソール I/O のオーバーヘッドを減らすため、デフォルトではサイレントモードで実行します。 +- 便利な上書き: + - `OPENCLAW_E2E_WORKERS=` でワーカー数を強制します（上限 16）。 + - `OPENCLAW_E2E_VERBOSE=1` で詳細なコンソール出力を再度有効化します。 +- 範囲: + - 複数インスタンスの Gateway のエンドツーエンド動作 + - WebSocket/HTTP サーフェス、Node ペアリング、より重いネットワーク処理 - 期待事項: - - CI で実行される（パイプラインで有効化されている場合） - - 実際のキーは不要 - - 単体テストより可動部分が多い（遅くなることがある） + - CI で実行されます（パイプラインで有効な場合） + - 実際のキーは不要です + - ユニットテストより可動部分が多いです（遅くなる場合があります） ### E2E: OpenShell バックエンドスモーク - コマンド: `pnpm test:e2e:openshell` - ファイル: `extensions/openshell/src/backend.e2e.test.ts` -- スコープ: - - Docker 経由でホスト上に分離された OpenShell Gateway を起動する - - 一時ローカル Dockerfile からサンドボックスを作成する - - 実際の `sandbox ssh-config` + SSH exec を通じて OpenClaw の OpenShell バックエンドを実行する - - サンドボックス fs ブリッジを通じてリモート正規ファイルシステム動作を検証する +- 範囲: + - Docker 経由でホスト上に分離された OpenShell Gateway を起動します + - 一時的なローカル Dockerfile からサンドボックスを作成します + - 実際の `sandbox ssh-config` + SSH 実行を通じて OpenClaw の OpenShell バックエンドを実行します + - サンドボックス fs ブリッジを通じて、リモート正規のファイルシステム動作を検証します - 期待事項: - - オプトインのみ。デフォルトの `pnpm test:e2e` 実行には含まれない - - ローカルの `openshell` CLI と動作する Docker デーモンが必要 - - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テスト Gateway とサンドボックスを破棄する -- 便利なオーバーライド: - - `OPENCLAW_E2E_OPENSHELL=1` で、より広い e2e スイートを手動実行するときにテストを有効化する - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` で、デフォルト以外の CLI バイナリまたはラッパースクリプトを指定する + - オプトインのみ。デフォルトの `pnpm test:e2e` 実行には含まれません + - ローカルの `openshell` CLI と、動作する Docker デーモンが必要です + - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テスト Gateway とサンドボックスを破棄します +- 便利な上書き: + - `OPENCLAW_E2E_OPENSHELL=1` で、より広い e2e スイートを手動実行するときにテストを有効化します + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` で、デフォルト以外の CLI バイナリまたはラッパースクリプトを指定します -### Live（実プロバイダー + 実モデル） +### ライブ（実際のプロバイダー + 実際のモデル） - コマンド: `pnpm test:live` - 設定: `vitest.live.config.ts` -- ファイル: `src/**/*.live.test.ts`、`test/**/*.live.test.ts`、および `extensions/` 配下のバンドルPlugin live テスト +- ファイル: `src/**/*.live.test.ts`、`test/**/*.live.test.ts`、および `extensions/` 配下のバンドル Plugin ライブテスト - デフォルト: `pnpm test:live` により **有効**（`OPENCLAW_LIVE_TEST=1` を設定） -- スコープ: - - 「このプロバイダー/モデルは実際の認証情報で_今日_本当に動作するか？」 - - プロバイダーの形式変更、ツール呼び出しの癖、認証の問題、レート制限の動作を検出する +- 範囲: + - 「このプロバイダー/モデルは、実際の認証情報で _今日_ 本当に動作するか？」 + - プロバイダーの形式変更、ツール呼び出しの癖、認証の問題、レート制限の動作を検出します - 期待事項: - - 設計上 CI 安定ではない（実ネットワーク、実プロバイダーポリシー、クォータ、障害） - - 費用がかかる / レート制限を消費する - - 「すべて」ではなく絞り込んだサブセットの実行を推奨 -- Live 実行は、不足している API キーを取得するために `~/.profile` を source する。 -- デフォルトでは、live 実行でも `HOME` を分離し、設定/認証素材を一時テストホームへコピーするため、単体テストのフィクスチャが実際の `~/.openclaw` を変更することはない。 -- live テストで実際のホームディレクトリを使用する必要が意図的にある場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定する。 -- `pnpm test:live` は現在、より静かなモードをデフォルトにしている。`[live] ...` 進捗出力は維持するが、追加の `~/.profile` 通知を抑制し、Gateway ブートストラップログ/Bonjour の雑音をミュートする。完全な起動ログを戻したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定する。 -- API キーローテーション（プロバイダー固有）: カンマ/セミコロン形式の `*_API_KEYS`、または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）、もしくは `OPENCLAW_LIVE_*_KEY` による live ごとのオーバーライドを設定する。テストはレート制限応答時にリトライする。 -- 進捗/Heartbeat 出力: - - Live スイートは現在、長いプロバイダー呼び出しが Vitest のコンソールキャプチャで静かな場合でも目に見えて動作中と分かるように、進捗行を stderr に出力する。 - - `vitest.live.config.ts` は Vitest のコンソールインターセプトを無効化するため、live 実行中にプロバイダー/Gateway の進捗行がすぐにストリームされる。 - - 直接モデル Heartbeat は `OPENCLAW_LIVE_HEARTBEAT_MS` で調整する。 - - Gateway/プローブ Heartbeat は `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整する。 + - 設計上、CI で安定するものではありません（実ネットワーク、実プロバイダーポリシー、クォータ、障害） + - 費用が発生する / レート制限を消費します + - 「すべて」ではなく、絞り込んだサブセットの実行を推奨します +- ライブ実行では、不足している API キーを取得するために `~/.profile` を読み込みます。 +- デフォルトでは、ライブ実行でも `HOME` を分離し、設定/認証素材を一時的なテストホームへコピーするため、ユニットフィクスチャが実際の `~/.openclaw` を変更することはありません。 +- ライブテストで実際のホームディレクトリを使う必要があると意図している場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 +- `pnpm test:live` は現在、より静かなモードをデフォルトにしています。`[live] ...` の進行状況出力は維持しますが、追加の `~/.profile` 通知を抑制し、Gateway ブートストラップログ/Bonjour の雑音をミュートします。完全な起動ログを戻したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 +- API キーローテーション（プロバイダー固有）: カンマ/セミコロン形式の `*_API_KEYS` または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）を設定するか、`OPENCLAW_LIVE_*_KEY` でライブごとの上書きを指定します。テストはレート制限レスポンス時に再試行します。 +- 進行状況/Heartbeat 出力: + - ライブスイートは stderr に進行状況行を出力するようになったため、Vitest のコンソールキャプチャが静かな場合でも、時間のかかるプロバイダー呼び出しが動作中であることを視認できます。 + - `vitest.live.config.ts` は Vitest のコンソール割り込みを無効化するため、ライブ実行中にプロバイダー/Gateway の進行状況行が即座にストリームされます。 + - 直接モデルの Heartbeat は `OPENCLAW_LIVE_HEARTBEAT_MS` で調整します。 + - Gateway/プローブの Heartbeat は `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 ## どのスイートを実行すべきか？ -この判断表を使用する: +この判断表を使用してください: -- ロジック/テストを編集している場合: `pnpm test` を実行する（多く変更した場合は `pnpm test:coverage` も） -- Gateway ネットワーク / WS プロトコル / ペアリングに触れている場合: `pnpm test:e2e` を追加する -- 「自分の bot が落ちている」/ プロバイダー固有の失敗 / ツール呼び出しをデバッグしている場合: 絞り込んだ `pnpm test:live` を実行する +- ロジック/テストを編集している: `pnpm test` を実行します（多く変更した場合は `pnpm test:coverage` も実行） +- Gateway ネットワーク / WS プロトコル / ペアリングに触れている: `pnpm test:e2e` を追加します +- 「ボットが落ちている」/ プロバイダー固有の失敗 / ツール呼び出しをデバッグしている: 絞り込んだ `pnpm test:live` を実行します -## Live（ネットワークに触れる）テスト +## ライブ（ネットワークに触れる）テスト -live モデルマトリクス、CLI バックエンドスモーク、ACP スモーク、Codex app-server -ハーネス、およびすべてのメディアプロバイダー live テスト（Deepgram、BytePlus、ComfyUI、画像、 -音楽、動画、メディアハーネス）と、live 実行の認証情報処理については、 -[Live スイートのテスト](/ja-JP/help/testing-live) を参照してください。専用の更新および +ライブモデルマトリクス、CLI バックエンドスモーク、ACP スモーク、Codex app-server +ハーネス、およびすべてのメディアプロバイダーライブテスト（Deepgram、BytePlus、ComfyUI、画像、 +音楽、動画、メディアハーネス）、さらにライブ実行の認証情報処理については、 +[ライブスイートのテスト](/ja-JP/help/testing-live) を参照してください。専用の更新および Plugin 検証チェックリストについては、 -[更新とPluginのテスト](/ja-JP/help/testing-updates-plugins) を参照してください。 +[更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins) を参照してください。 -## Docker ランナー（任意の「Linux で動作する」確認） +## Docker ランナー（任意の「Linux で動作する」チェック） -これらの Docker ランナーは 2 つのグループに分かれる: +これらの Docker ランナーは 2 つのバケットに分かれます: -- live モデルランナー: `test:docker:live-models` と `test:docker:live-gateway` は、リポジトリの Docker イメージ内で対応する profile-key live ファイル（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）のみを実行し、ローカルの設定ディレクトリとワークスペースをマウントする（マウントされている場合は `~/.profile` も source する）。対応するローカルエントリポイントは `test:live:models-profiles` と `test:live:gateway-profiles`。 -- Docker live ランナーは、フル Docker スイープを現実的に保つため、デフォルトでより小さいスモーク上限を使用する: - `test:docker:live-models` はデフォルトで `OPENCLAW_LIVE_MAX_MODELS=12`、 +- ライブモデルランナー: `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`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`、および - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` を使用する。より大きな網羅的スキャンを明示的に - 望む場合は、これらの環境変数をオーバーライドする。 -- `test:docker:all` は `test:docker:live-build` 経由で live Docker イメージを一度だけビルドし、`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw を npm tarball として一度だけパックし、その後 2 つの `scripts/e2e/Dockerfile` イメージをビルド/再利用する。bare イメージは install/update/plugin-dependency レーン用の Node/Git ランナーのみであり、これらのレーンは事前ビルド済み tarball をマウントする。functional イメージは同じ tarball を `/app` にインストールし、ビルド済みアプリ機能レーンに使用する。Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーロジックは `scripts/lib/docker-e2e-plan.mjs` にあり、`scripts/test-docker-all.mjs` が選択されたプランを実行する。集約は重み付きローカルスケジューラーを使用する。`OPENCLAW_DOCKER_ALL_PARALLELISM` はプロセススロットを制御し、リソース上限は重い live、npm-install、複数サービスレーンがすべて同時に開始しないようにする。単一レーンがアクティブな上限より重い場合でも、プールが空ならスケジューラーはそれを開始でき、その後キャパシティが再び利用可能になるまで単独で実行し続ける。デフォルトは 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 レーンを実行する。プロファイルは範囲の広さ順に `smoke`、`package`、`product`、`full`。パッケージ/更新/Plugin 契約、公開済みアップグレードのサバイバーマトリクス、リリースデフォルト、失敗トリアージについては、[更新とPluginのテスト](/ja-JP/help/testing-updates-plugins) を参照。 -- ビルドとリリース確認は tsdown 後に `scripts/check-cli-bootstrap-imports.mjs` を実行する。このガードは `dist/entry.js` と `dist/cli/run-main.js` から静的なビルド済みグラフをたどり、コマンドディスパッチ前の起動前インポートが Commander、プロンプト UI、undici、logging などのパッケージ依存関係をインポートしている場合に失敗する。また、バンドルされた Gateway 実行チャンクを予算内に保ち、既知のコールド Gateway パスの静的インポートを拒否する。パッケージ化された CLI スモークは、root help、onboard help、doctor help、status、config schema、および model-list コマンドもカバーする。 -- Package Acceptance のレガシー互換性は `2026.4.25`（`2026.4.25-beta.*` を含む）までに制限される。その期限までは、ハーネスは出荷済みパッケージのメタデータギャップのみを許容する。省略された private QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 派生 git フィクスチャ内の欠落したパッチファイル、欠落した永続化済み `update.channel`、レガシー Plugin インストールレコードの場所、欠落した marketplace インストールレコード永続化、および `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:plugin-lifecycle-matrix`、および `test:docker:config-reload` は、1 つ以上の実コンテナーを起動し、より高レベルの統合パスを検証する。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` を使用します。より大きな網羅的スキャンを明示的に行いたい場合は、これらの env var を上書きしてください。 +- `test:docker:all` は `test:docker:live-build` 経由でライブ Docker イメージを一度ビルドし、`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw を npm tarball として一度パックし、その後 2 つの `scripts/e2e/Dockerfile` イメージをビルド/再利用します。ベア画像は install/update/plugin-dependency レーン用の 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-install、複数サービスのレーンが一斉に開始されないようにします。単一レーンがアクティブな上限より重い場合でも、プールが空ならスケジューラはそれを開始でき、その後容量が再び利用可能になるまで単独で実行し続けます。デフォルトは 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 レーンを実行します。プロファイルは範囲の広さ順に並びます: `smoke`、`package`、`product`、`full`。パッケージ/更新/Plugin 契約、公開済みアップグレード生存マトリクス、リリースデフォルト、失敗トリアージについては、[更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins) を参照してください。 +- ビルドおよびリリースチェックは、tsdown 後に `scripts/check-cli-bootstrap-imports.mjs` を実行します。このガードは `dist/entry.js` と `dist/cli/run-main.js` から静的なビルド済みグラフをたどり、コマンドディスパッチ前のプリディスパッチ起動処理で Commander、プロンプト UI、undici、ロギングなどのパッケージ依存関係をインポートしている場合に失敗します。また、バンドルされた Gateway 実行チャンクを予算内に保ち、既知のコールド Gateway パスの静的インポートを拒否します。パッケージ化された CLI スモークは、ルートヘルプ、オンボードヘルプ、doctor ヘルプ、status、config schema、model-list コマンドもカバーします。 +- Package Acceptance のレガシー互換性は `2026.4.25`（`2026.4.25-beta.*` を含む）までに制限されています。その期限までは、ハーネスは出荷済みパッケージのメタデータ不足のみを許容します。省略された private QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャ内の欠落したパッチファイル、永続化されていない `update.channel`、レガシー Plugin インストール記録場所、欠落した marketplace インストール記録永続化、および `plugins update` 中の config メタデータ移行です。`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:plugin-lifecycle-matrix`、および `test:docker:config-reload` は、1 つ以上の実コンテナを起動し、より高レベルの統合パスを検証します。 -live モデル Docker ランナーは、必要な CLI 認証ホームのみ（または実行が絞り込まれていない場合は対応するすべてのもの）も bind mount し、その後、外部 CLI OAuth がホストの認証ストアを変更せずにトークンを更新できるように、実行前にそれらをコンテナーホームへコピーする: +ライブモデル Docker ランナーは、必要な CLI 認証ホームのみ（または実行が絞り込まれていない場合はサポートされているすべて）もバインドマウントし、その後実行前にコンテナホームへコピーするため、外部 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 の厳密なカバレッジを含む) +- 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 app-server ハーネススモーク: `pnpm test:docker:live-codex-harness` (スクリプト: `scripts/test-live-codex-harness-docker.sh`) +- Codex アプリサーバーハーネススモーク: `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 リリースレーンには含めていない。 +- オブザーバビリティスモーク: `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 を実行し、モックされた 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 allowlist、古い Plugin 依存関係状態、既存のワークスペース/セッションファイルを含む、汚れた旧ユーザーフィクスチャの上に、パック済みの OpenClaw tarball をインストールする。ライブプロバイダーやチャネルキーなしでパッケージ更新と非対話型 doctor を実行し、その後 loopback Gateway を起動して、設定/状態の保持と起動/ステータスのバジェットを確認する。 -- 公開済みアップグレード生存スモーク: `pnpm test:docker:published-upgrade-survivor` はデフォルトで `openclaw@latest` をインストールし、現実的な既存ユーザーファイルをシードし、組み込みのコマンドレシピでそのベースラインを設定し、結果の設定を検証し、その公開済みインストールを候補 tarball に更新し、非対話型 doctor を実行し、`.artifacts/upgrade-survivor/summary.json` を書き込み、その後 loopback Gateway を起動して、設定済み intent、状態保持、起動、`/healthz`、`/readyz`、RPC ステータスバジェットを確認する。`OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` で 1 つのベースラインを上書きし、`all-since-2026.4.23` のような `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` で集約スケジューラーに正確なベースラインを展開させ、`reported-issues` のような `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` で issue 形式のフィクスチャを展開する。reported-issues セットには、外部 OpenClaw Plugin インストールの自動修復用に `configured-plugin-installs` が含まれる。Package Acceptance はそれらを `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines`、`published_upgrade_survivor_scenarios` として公開する。 -- セッションランタイムコンテキストスモーク: `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` でホストビルドをスキップするか、`OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` でビルド済み Docker イメージから `dist/` をコピーする。 -- インストーラー 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 インストーラーチェックでは、root 所有のキャッシュエントリがユーザーローカルのインストール動作を隠さないように、分離された npm キャッシュを維持する。ローカル再実行間で 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`) はデフォルトで root 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` で install-smoke イメージを再利用する。 -- 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 最小 reasoning リグレッション: `pnpm test:docker:openai-web-search-minimal` (スクリプト: `scripts/e2e/openai-web-search-minimal-docker.sh`) は、モックされた OpenAI サーバーを Gateway 経由で実行し、`web_search` が `reasoning.effort` を `minimal` から `low` に上げることを検証し、その後プロバイダースキーマを強制的に拒否させ、生の詳細が Gateway ログに出現することを確認する。 +- Npm tarball のオンボーディング/チャネル/エージェントスモーク: `pnpm test:docker:npm-onboard-channel-agent` は、パック済みの OpenClaw tarball を Docker 内でグローバルにインストールし、env-ref オンボーディング経由の OpenAI とデフォルトの Telegram を構成し、doctor を実行して、モックされた OpenAI エージェントターンを 1 回実行します。ビルド済み tarball を再利用するには `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` を使い、ホスト側の再ビルドをスキップするには `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` を使い、チャネルを切り替えるには `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` または `OPENCLAW_NPM_ONBOARD_CHANNEL=slack` を使います。 +- 更新チャネル切り替えスモーク: `pnpm test:docker:update-channel-switch` は、パック済みの OpenClaw tarball を Docker 内でグローバルにインストールし、パッケージ `stable` から git `dev` に切り替え、永続化されたチャネルと Plugin の更新後動作を検証した後、パッケージ `stable` に戻して更新状態を確認します。 +- アップグレードサバイバースモーク: `pnpm test:docker:upgrade-survivor` は、エージェント、チャネル設定、Plugin allowlist、古い Plugin 依存関係状態、既存のワークスペース/セッションファイルを含む、汚れた古いユーザーフィクスチャの上にパック済みの OpenClaw tarball をインストールします。ライブプロバイダーやチャネルキーなしで、パッケージ更新と非対話 doctor を実行した後、loopback Gateway を起動し、設定/状態の保持と起動/状態予算を確認します。 +- 公開済みアップグレードサバイバースモーク: `pnpm test:docker:published-upgrade-survivor` は、デフォルトで `openclaw@latest` をインストールし、現実的な既存ユーザーファイルをシードし、焼き込み済みコマンドレシピでそのベースラインを構成し、生成された設定を検証し、その公開済みインストールを候補 tarball に更新し、非対話 doctor を実行し、`.artifacts/upgrade-survivor/summary.json` を書き込み、その後 loopback Gateway を起動して、構成済み intent、状態保持、起動、`/healthz`、`/readyz`、RPC 状態予算を確認します。1 つのベースラインを上書きするには `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` を使い、集約スケジューラーに正確なベースラインを展開させるには `all-since-2026.4.23` のような `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` を使い、課題形状のフィクスチャを展開するには `reported-issues` のような `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` を使います。reported-issues セットには、外部 OpenClaw Plugin インストールの自動修復用に `configured-plugin-installs` が含まれます。Package Acceptance では、これらを `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines`、`published_upgrade_survivor_scenarios` として公開します。Full Release Validation は、ブロッキングパスではデフォルトの latest ベースラインを使い、`run_release_soak=true` または `release_profile=full` の場合にのみ all-since/reported-issues に展開します。 +- セッションランタイムコンテキストスモーク: `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 インストーラーチェックは、root 所有のキャッシュエントリがユーザーローカルのインストール挙動を隠さないように、隔離された npm キャッシュを維持します。ローカル再実行間で root/update/direct-npm キャッシュを再利用するには `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` を設定します。 +- Install Smoke CI は、重複する direct-npm グローバル更新を `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` でスキップします。直接の `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 とワークスペース保持動作を検証します。install-smoke イメージを再利用するには `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 最小 reasoning 回帰: `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 プロファイル allow/deny スモーク): `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`) -- Plugins (ローカルパス、`file:`、巻き上げられた依存関係を持つ npm レジストリ、git moving refs、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`) -- Plugin ライフサイクルマトリックススモーク: `pnpm test:docker:plugin-lifecycle-matrix` は、パック済みの OpenClaw tarball を空のコンテナにインストールし、npm Plugin をインストールし、有効/無効を切り替え、ローカル npm レジストリ経由でアップグレードとダウングレードを行い、インストール済みコードを削除し、その後、各ライフサイクルフェーズの RSS/CPU メトリクスをログに記録しながら、アンインストールが古い状態を引き続き削除することを検証する。 +- Pi バンドル MCP ツール (実際の stdio MCP サーバー + 埋め込み Pi プロファイル allow/deny スモーク): `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`) +- Plugins (ローカルパス、`file:`、hoist された依存関係を持つ npm レジストリ、git moving refs、ClawHub kitchen-sink、marketplace 更新、Claude-bundle の有効化/検査のインストール/更新スモーク): `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`) +- Plugin ライフサイクルマトリックススモーク: `pnpm test:docker:plugin-lifecycle-matrix` は、パック済みの OpenClaw tarball を空のコンテナにインストールし、npm Plugin をインストールし、有効化/無効化を切り替え、ローカル npm レジストリ経由でアップグレードとダウングレードを行い、インストール済みコードを削除した後、各ライフサイクルフェーズの RSS/CPU メトリクスをログに記録しつつ、アンインストールが古い状態を引き続き削除することを検証します。 - 設定リロードメタデータスモーク: `pnpm test:docker:config-reload` (スクリプト: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` は、ローカルパス、`file:`、巻き上げられた依存関係を持つ npm レジストリ、git moving refs、ClawHub フィクスチャ、マーケットプレイス更新、Claude バンドルの有効化/検査のインストール/更新スモークを対象にする。`pnpm test:docker:plugin-update` は、インストール済み Plugin の変更なし更新動作を対象にする。`pnpm test:docker:plugin-lifecycle-matrix` は、リソース追跡付きの npm Plugin のインストール、有効化、無効化、アップグレード、ダウングレード、コード欠落時のアンインストールを対象にする。 +- Plugins: `pnpm test:docker:plugins` は、ローカルパス、`file:`、hoist された依存関係を持つ npm レジストリ、git moving refs、ClawHub フィクスチャ、marketplace 更新、Claude-bundle の有効化/検査のインストール/更新スモークを対象にします。`pnpm test:docker:plugin-update` は、インストール済み Plugin の未変更更新動作を対象にします。`pnpm test:docker:plugin-lifecycle-matrix` は、リソース追跡付きの npm Plugin インストール、有効化、無効化、アップグレード、ダウングレード、コード欠落時のアンインストールを対象にします。 共有機能イメージを手動で事前ビルドして再利用するには: @@ -562,134 +571,111 @@ OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker: 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` のようなスイート固有のイメージ上書きは、設定されている場合は引き続き優先されます。`OPENCLAW_SKIP_DOCKER_BUILD=1` がリモート共有イメージを指す場合、スクリプトはそれがローカルにまだ存在しなければ pull します。QR とインストーラーの Docker テストは、共有ビルド済みアプリランタイムではなく、パッケージ/インストール動作を検証するため、それぞれ独自の Dockerfile を維持します。 -ライブモデル Docker ランナーは、現在のチェックアウトも読み取り専用で bind mount し、 +ライブモデルの Docker ランナーは、現在のチェックアウトも読み取り専用でバインドマウントし、 コンテナ内の一時作業ディレクトリにステージングします。これにより、ランタイム イメージをスリムに保ちながら、正確なローカルソース/設定に対して 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` を公開していることを検証してから、 -Open WebUI の `/api/chat/completions` プロキシ経由で実際のチャットリクエストを送信します。 -初回実行は、Docker が Open WebUI イメージを pull する必要があり、Open WebUI が自身のコールドスタート設定を完了する必要があるため、 -目に見えて遅くなる場合があります。 -このレーンでは使用可能なライブモデルキーが必要で、`OPENCLAW_PROFILE_FILE` -(デフォルトは `~/.profile`) が Docker 化された実行でそれを提供する主な方法です。 -成功した実行では `{ "ok": true, "model": +ステージング手順では、`.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` を公開していることを検証してから、Open WebUI の `/api/chat/completions` プロキシを通じて実際のチャットリクエストを送信します。 +初回実行は、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 bundle -MCP ランタイムを通じてそのサーバーを具現化し、ツールを実行してから、`coding` と `messaging` が -`bundle-mcp` ツールを保持し、`minimal` と `tools.deny: ["bundle-mcp"]` がそれらをフィルターすることを検証します。 -`test:docker:cron-mcp-cleanup` は決定的であり、ライブモデルキーは不要です。実際の stdio MCP プローブサーバーを持つシード済み Gateway を起動し、 -分離された Cron ターンと `/subagents spawn` の 1 回限りの子ターンを実行してから、 -各実行後に MCP 子プロセスが終了することを検証します。 +`test:docker:mcp-channels` は意図的に決定的であり、実際の Telegram、Discord、iMessage アカウントは不要です。シード済みの Gateway コンテナを起動し、`openclaw mcp serve` を spawn する 2 つ目のコンテナを起動してから、実際の stdio MCP ブリッジ上で、ルーティングされた会話の検出、トランスクリプト読み取り、添付ファイルメタデータ、ライブイベントキューの動作、アウトバウンド送信ルーティング、Claude 形式のチャネル + 権限通知を検証します。通知チェックは、生の 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` の 1 回限りの子ターンを実行してから、各実行後に MCP 子プロセスが終了することを検証します。 -手動 ACP 平易言語スレッドスモーク (CI ではありません): +手動 ACP 平易言語スレッドスモーク（CI ではありません）: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- このスクリプトは回帰/デバッグワークフロー用に保持してください。ACP スレッドルーティング検証で再び必要になる可能性があるため、削除しないでください。 +- このスクリプトはリグレッション/デバッグワークフロー用に保持してください。ACP スレッドルーティング検証で再び必要になる可能性があるため、削除しないでください。 -有用な環境変数: +有用な env vars: -- `OPENCLAW_CONFIG_DIR=...` (デフォルト: `~/.openclaw`) は `/home/node/.openclaw` にマウントされます -- `OPENCLAW_WORKSPACE_DIR=...` (デフォルト: `~/.openclaw/workspace`) は `/home/node/.openclaw/workspace` にマウントされます -- `OPENCLAW_PROFILE_FILE=...` (デフォルト: `~/.profile`) は `/home/node/.profile` にマウントされ、テスト実行前に source されます -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` は、一時的な設定/ワークスペースディレクトリを使用し、外部 CLI 認証マウントなしで、`OPENCLAW_PROFILE_FILE` から source された環境変数だけを検証します -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (デフォルト: `~/.cache/openclaw/docker-cli-tools`) は Docker 内のキャッシュ済み CLI インストール用に `/home/node/.npm-global` にマウントされます -- `$HOME` 配下の外部 CLI 認証ディレクトリ/ファイルは `/host-auth...` 配下に読み取り専用でマウントされ、その後テスト開始前に `/home/node/...` へコピーされます +- `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` は、一時的な設定/ワークスペースディレクトリを使用し、外部 CLI 認証マウントなしで、`OPENCLAW_PROFILE_FILE` から source された env vars のみを検証します +- `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` から推定された必要なディレクトリ/ファイルのみをマウントします + - デフォルトファイル: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` + - 絞り込まれた provider 実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推定された必要なディレクトリ/ファイルのみをマウントします - `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_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` はコンテナ内の provider をフィルタリングします - `OPENCLAW_SKIP_DOCKER_BUILD=1` は、再ビルドが不要な再実行で既存の `openclaw:local-live` イメージを再利用します -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` は、認証情報がプロファイルストアから来ることを保証します (env ではありません) -- `OPENCLAW_OPENWEBUI_MODEL=...` は Open WebUI スモーク用に Gateway が公開するモデルを選択します -- `OPENCLAW_OPENWEBUI_PROMPT=...` は Open WebUI スモークで使用する nonce チェックプロンプトを上書きします -- `OPENWEBUI_IMAGE=...` は固定された Open WebUI イメージタグを上書きします +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` は、認証情報が（env ではなく）プロファイルストアから来ていることを保証します +- `OPENCLAW_OPENWEBUI_MODEL=...` は、Open WebUI スモーク用に Gateway が公開するモデルを選択します +- `OPENCLAW_OPENWEBUI_PROMPT=...` は、Open WebUI スモークで使用される nonce チェックプロンプトを上書きします +- `OPENWEBUI_IMAGE=...` は、固定された Open WebUI イメージタグを上書きします -## ドキュメント健全性 +## Docs の健全性 -ドキュメント編集後にドキュメントチェックを実行します: `pnpm check:docs`。 +ドキュメント編集後に docs チェックを実行します: `pnpm check:docs`。 ページ内見出しチェックも必要な場合は、完全な Mintlify アンカー検証を実行します: `pnpm docs:check-links:anchors`。 -## オフライン回帰 (CI セーフ) +## オフラインリグレッション（CI セーフ） -これらは実プロバイダーなしの「実際のパイプライン」回帰です: +これらは実際の provider を使わない「実パイプライン」リグレッションです: -- Gateway ツール呼び出し (モック OpenAI、実 Gateway + エージェントループ): `src/gateway/gateway.test.ts` (ケース: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Gateway ウィザード (WS `wizard.start`/`wizard.next`、設定を書き込み + 認証を強制): `src/gateway/gateway.test.ts` (ケース: "runs wizard over ws and writes auth token config") +- Gateway ツール呼び出し（モック OpenAI、実際の Gateway + agent loop）: `src/gateway/gateway.test.ts`（ケース: "runs a mock OpenAI tool call end-to-end via gateway agent loop"） +- Gateway ウィザード（WS `wizard.start`/`wizard.next`、設定を書き込み + auth enforced）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） -## エージェント信頼性 eval (Skills) +## エージェント信頼性 evals（skills） -「エージェント信頼性 eval」のように振る舞う CI セーフなテストはすでにいくつかあります: +「エージェント信頼性 evals」のように振る舞う CI セーフなテストは、すでにいくつかあります: -- 実 Gateway + エージェントループを通じたモックツール呼び出し (`src/gateway/gateway.test.ts`)。 -- セッション配線と設定効果を検証するエンドツーエンドのウィザードフロー (`src/gateway/gateway.test.ts`)。 +- 実際の Gateway + agent loop を通じたモックツール呼び出し（`src/gateway/gateway.test.ts`）。 +- セッション配線と設定効果を検証するエンドツーエンドのウィザードフロー（`src/gateway/gateway.test.ts`）。 -Skills でまだ不足しているもの ([Skills](/ja-JP/tools/skills) を参照): +Skills でまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: -- **意思決定:** プロンプトに Skills が列挙されているとき、エージェントは正しい skill を選ぶか (または無関係なものを避けるか)? -- **準拠:** エージェントは使用前に `SKILL.md` を読み、必須の手順/引数に従うか? -- **ワークフロー契約:** ツール順序、セッション履歴の引き継ぎ、サンドボックス境界をアサートするマルチターンシナリオ。 +- **判定:** Skills がプロンプトに列挙されているとき、エージェントは適切な skill を選ぶ（または無関係なものを避ける）か？ +- **遵守:** エージェントは使用前に `SKILL.md` を読み、必要な手順/引数に従うか？ +- **ワークフロー契約:** ツール順序、セッション履歴の引き継ぎ、sandbox 境界をアサートする複数ターンのシナリオ。 -将来の eval は、まず決定的であるべきです: +将来の evals は、まず決定的であるべきです: -- ツール呼び出し + 順序、skill ファイル読み取り、セッション配線をアサートする、モックプロバイダーを使用したシナリオランナー。 -- skill に焦点を当てた小さなシナリオスイート (使用 vs 回避、ゲート、プロンプトインジェクション)。 -- CI セーフなスイートが整ってからの、任意のライブ eval (オプトイン、env ゲート付き)。 +- mock provider を使用して、ツール呼び出し + 順序、skill ファイル読み取り、セッション配線をアサートするシナリオランナー。 +- skill に焦点を当てた小さなシナリオスイート（使用 vs 回避、ゲーティング、プロンプトインジェクション）。 +- CI セーフなスイートが整った後の、任意のライブ evals（opt-in、env-gated）のみ。 -## 契約テスト (plugin と channel の形状) +## 契約テスト（plugin とチャネル形状） -契約テストは、登録済みのすべての plugin と channel がそれぞれの -インターフェイス契約に準拠していることを検証します。検出されたすべての plugin を反復処理し、 -形状と動作のアサーションスイートを実行します。デフォルトの `pnpm test` unit レーンは、これらの共有境界およびスモークファイルを意図的に -スキップします。共有 channel または provider サーフェスに触れる場合は、契約コマンドを明示的に -実行してください。 +契約テストは、登録されているすべての Plugin とチャネルがその +インターフェイス契約に準拠していることを検証します。検出されたすべての Plugin を反復処理し、 +形状と動作のアサーションスイートを実行します。デフォルトの `pnpm test` ユニットレーンは、 +これらの共有 seam とスモークファイルを意図的にスキップします。共有チャネルまたは provider サーフェスを触るときは、契約コマンドを明示的に実行してください。 ### コマンド - すべての契約: `pnpm test:contracts` -- Channel 契約のみ: `pnpm test:contracts:channels` +- チャネル契約のみ: `pnpm test:contracts:channels` - Provider 契約のみ: `pnpm test:contracts:plugins` -### Channel 契約 +### チャネル契約 `src/channels/plugins/contracts/*.contract.test.ts` にあります: -- **plugin** - 基本的な plugin 形状 (id, name, capabilities) +- **plugin** - 基本的な plugin 形状（id、name、capabilities） - **setup** - セットアップウィザード契約 - **session-binding** - セッションバインディング動作 - **outbound-payload** - メッセージペイロード構造 -- **inbound** - 受信メッセージ処理 -- **actions** - Channel アクションハンドラー +- **inbound** - インバウンドメッセージ処理 +- **actions** - チャネルアクションハンドラー - **threading** - スレッド ID 処理 - **directory** - ディレクトリ/roster API -- **group-policy** - グループポリシー強制 +- **group-policy** - グループポリシー適用 ### Provider ステータス契約 `src/plugins/contracts/*.contract.test.ts` にあります。 -- **status** - Channel ステータスプローブ +- **status** - チャネルステータスプローブ - **registry** - Plugin レジストリ形状 ### Provider 契約 @@ -705,29 +691,29 @@ Skills でまだ不足しているもの ([Skills](/ja-JP/tools/skills) を参 - **shape** - Plugin 形状/インターフェイス - **wizard** - セットアップウィザード -### 実行タイミング +### 実行するタイミング -- plugin-sdk の export または subpath を変更した後 -- channel または provider plugin を追加または変更した後 -- plugin の登録または検出をリファクタリングした後 +- plugin-sdk exports または subpaths を変更した後 +- チャネルまたは provider Plugin を追加または変更した後 +- Plugin 登録または検出をリファクタリングした後 契約テストは CI で実行され、実際の API キーは不要です。 -## 回帰の追加 (ガイダンス) +## リグレッションの追加（ガイダンス） -ライブで見つかった provider/model の問題を修正する場合: +ライブで見つかった provider/モデル問題を修正するとき: -- 可能であれば CI セーフな回帰を追加します (モック/スタブ provider、または正確なリクエスト形状変換のキャプチャ) -- 本質的にライブ専用の場合 (レート制限、認証ポリシー)、ライブテストを狭く保ち、環境変数経由のオプトインにします -- バグを捕捉する最小レイヤーを優先して対象にします: - - provider リクエスト変換/リプレイのバグ → 直接の models テスト - - 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 セーフなリグレッションを追加します（mock/stub provider、または正確なリクエスト形状変換のキャプチャ） +- 本質的にライブ専用の場合（レート制限、認証ポリシー）、ライブテストは狭く保ち、env vars で opt-in にします +- バグを捕捉できる最小の層を対象にすることを優先します: + - provider リクエスト変換/リプレイバグ → 直接の models テスト + - Gateway セッション/履歴/ツールパイプラインバグ → Gateway ライブスモークまたは CI セーフな Gateway mock テスト +- 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 で意図的に失敗するため、新しいクラスが静かにスキップされることはありません。 ## 関連 - [ライブテスト](/ja-JP/help/testing-live) -- [更新とプラグインのテスト](/ja-JP/help/testing-updates-plugins) +- [アップデートと Plugin のテスト](/ja-JP/help/testing-updates-plugins) - [CI](/ja-JP/ci) diff --git a/docs/ja-JP/plugins/bundles.md b/docs/ja-JP/plugins/bundles.md index 2322e6573..15f243f37 100644 --- a/docs/ja-JP/plugins/bundles.md +++ b/docs/ja-JP/plugins/bundles.md @@ -1,46 +1,49 @@ --- read_when: - - Codex、Claude、または Cursor と互換性のあるバンドルをインストールしたい場合 - - OpenClaw がバンドルの内容をネイティブ機能にどのように対応付けるかを理解する必要があります + - Codex、Claude、またはCursor互換のバンドルをインストールしたい場合 + - OpenClaw がバンドルコンテンツをネイティブ機能にどのようにマッピングするかを理解する必要があります - バンドル検出または不足している機能をデバッグしている summary: Codex、Claude、Cursor のバンドルを OpenClaw Plugin としてインストールして使用する title: Plugin バンドル x-i18n: - generated_at: "2026-05-02T05:00:32Z" + generated_at: "2026-05-05T01:47:49Z" model: gpt-5.5 provider: openai - source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4 + source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157 source_path: plugins/bundles.md workflow: 16 --- -OpenClaw は、**Codex**、**Claude**、**Cursor** の 3 つの外部エコシステムから Plugin をインストールできます。これらは **バンドル** と呼ばれます。OpenClaw が Skills、hooks、MCP ツールなどのネイティブ機能にマッピングする、コンテンツとメタデータのパックです。 +OpenClawは、3つの外部エコシステム（**Codex**、**Claude**、 +**Cursor**）からPluginをインストールできます。これらは**バンドル**と呼ばれます。つまり、 +OpenClawがSkills、フック、MCPツールのようなネイティブ機能へマッピングするコンテンツとメタデータのパックです。 - バンドルはネイティブ OpenClaw Plugin と**同じではありません**。ネイティブ Plugin は - プロセス内で実行され、任意の capability を登録できます。バンドルは、選択的な機能マッピングと - より狭い信頼境界を持つコンテンツパックです。 + バンドルは、ネイティブOpenClaw Pluginと**同じではありません**。ネイティブPluginは + インプロセスで実行され、任意の機能を登録できます。バンドルはコンテンツパックであり、 + 選択的な機能マッピングと、より狭い信頼境界を持ちます。 ## バンドルが存在する理由 -有用な Plugin の多くは Codex、Claude、Cursor 形式で公開されています。 -作者にネイティブ OpenClaw Plugin として書き直すことを求める代わりに、OpenClaw は -これらの形式を検出し、対応しているコンテンツをネイティブ機能セットにマッピングします。 -つまり、Claude コマンドパックや Codex skill バンドルをインストールして、すぐに使えます。 +多くの有用なPluginは、Codex、Claude、またはCursor形式で公開されています。作者に +ネイティブOpenClaw Pluginとして書き直すことを求める代わりに、OpenClawは +これらの形式を検出し、対応するコンテンツをネイティブ機能セットへマッピングします。 +つまり、ClaudeコマンドパックやCodex skillバンドルをインストールして、 +すぐに使えます。 ## バンドルをインストールする - + ```bash - # Local directory + # ローカルディレクトリ openclaw plugins install ./my-bundle - # Archive + # アーカイブ openclaw plugins install ./my-bundle.tgz - # Claude marketplace + # Claudeマーケットプレイス openclaw plugins marketplace list openclaw plugins install @ ``` @@ -53,7 +56,7 @@ OpenClaw は、**Codex**、**Claude**、**Cursor** の 3 つの外部エコシ openclaw plugins inspect ``` - バンドルは `Format: bundle` と表示され、subtype は `codex`、`claude`、または `cursor` です。 + バンドルは、`codex`、`claude`、または`cursor`のサブタイプを持つ`Format: bundle`として表示されます。 @@ -62,62 +65,62 @@ OpenClaw は、**Codex**、**Claude**、**Cursor** の 3 つの外部エコシ openclaw gateway restart ``` - マッピングされた機能（Skills、hooks、MCP ツール、LSP デフォルト）は次のセッションで利用できます。 + マッピングされた機能（Skills、フック、MCPツール、LSPデフォルト）は次のセッションで利用できます。 -## OpenClaw がバンドルからマッピングするもの +## OpenClawがバンドルからマッピングするもの -現在、すべてのバンドル機能が OpenClaw で実行されるわけではありません。以下は動作するものと、 -検出はされるもののまだ接続されていないものです。 +現在のOpenClawでは、すべてのバンドル機能が実行されるわけではありません。以下は、 +動作するものと、検出されるもののまだ接続されていないものです。 ### 現在対応済み -| 機能 | マッピング方法 | 対象 | -| ------------- | ------------------------------------------------------------------------------------------- | -------------- | -| Skill コンテンツ | バンドルの skill ルートは通常の OpenClaw Skills として読み込まれます | すべての形式 | -| コマンド | `commands/` と `.cursor/commands/` は skill ルートとして扱われます | Claude、Cursor | -| Hook パック | OpenClaw 形式の `HOOK.md` + `handler.ts` レイアウト | Codex | -| MCP ツール | バンドル MCP 設定は組み込み Pi 設定にマージされ、対応している stdio と HTTP サーバーが読み込まれます | すべての形式 | -| LSP サーバー | Claude `.lsp.json` と manifest で宣言された `lspServers` は組み込み Pi LSP デフォルトにマージされます | Claude | -| 設定 | Claude `settings.json` は組み込み Pi デフォルトとしてインポートされます | Claude | +| 機能 | マッピング方法 | 対象 | +| ------------- | --------------------------------------------------------------------------------------------- | -------------- | +| Skillコンテンツ | バンドルのskillルートは通常のOpenClaw Skillsとして読み込まれます | すべての形式 | +| コマンド | `commands/`と`.cursor/commands/`はskillルートとして扱われます | Claude、Cursor | +| フックパック | OpenClawスタイルの`HOOK.md` + `handler.ts`レイアウト | Codex | +| MCPツール | バンドルMCP設定は埋め込みPi設定へマージされ、対応するstdioおよびHTTPサーバーが読み込まれます | すべての形式 | +| LSPサーバー | Claudeの`.lsp.json`とマニフェスト宣言の`lspServers`は埋め込みPi LSPデフォルトへマージされます | Claude | +| 設定 | Claudeの`settings.json`は埋め込みPiデフォルトとしてインポートされます | Claude | -#### Skill コンテンツ +#### Skillコンテンツ -- バンドルの skill ルートは通常の OpenClaw skill ルートとして読み込まれます -- Claude `commands` ルートは追加の skill ルートとして扱われます -- Cursor `.cursor/commands` ルートは追加の skill ルートとして扱われます +- バンドルのskillルートは通常のOpenClaw skillルートとして読み込まれます +- Claudeの`commands`ルートは追加のskillルートとして扱われます +- Cursorの`.cursor/commands`ルートは追加のskillルートとして扱われます -つまり、Claude markdown コマンドファイルは通常の OpenClaw skill -ローダーを通じて動作します。Cursor コマンド markdown も同じ経路で動作します。 +つまり、ClaudeのMarkdownコマンドファイルは通常のOpenClaw skill +ローダーを通じて動作します。CursorコマンドMarkdownも同じ経路で動作します。 -#### Hook パック +#### フックパック -- バンドル hook ルートは、通常の OpenClaw hook-pack - レイアウトを使用している場合に**のみ**動作します。現在これは主に Codex 互換ケースです。 +- バンドルのフックルートは、通常のOpenClawフックパック + レイアウトを使用する場合に**のみ**動作します。現在、これは主にCodex互換のケースです。 - `HOOK.md` - - `handler.ts` または `handler.js` + - `handler.ts`または`handler.js` -#### Pi 向け MCP +#### Pi向けMCP -- 有効化されたバンドルは MCP サーバー設定を提供できます -- OpenClaw はバンドル MCP 設定を、有効な組み込み Pi 設定の - `mcpServers` にマージします -- OpenClaw は、組み込み Pi agent ターン中に対応しているバンドル MCP ツールを公開します。 - その際、stdio サーバーを起動するか、HTTP サーバーに接続します -- `coding` と `messaging` のツールプロファイルには、デフォルトでバンドル MCP ツールが含まれます。 - agent または Gateway で除外するには `tools.deny: ["bundle-mcp"]` を使用します -- project-local の Pi 設定はバンドルのデフォルト後にも適用されるため、必要に応じて workspace - 設定でバンドル MCP エントリを上書きできます -- バンドル MCP ツールカタログは登録前に決定論的にソートされるため、 - upstream の `listTools()` 順序が変わっても prompt-cache のツールブロックが乱れません +- 有効なバンドルはMCPサーバー設定を提供できます +- OpenClawは、バンドルMCP設定を有効な埋め込みPi設定に + `mcpServers`としてマージします +- OpenClawは、stdioサーバーを起動するかHTTPサーバーへ接続することで、 + 埋め込みPiエージェントターン中に対応するバンドルMCPツールを公開します +- `coding`および`messaging`ツールプロファイルには、デフォルトでバンドルMCPツールが含まれます。 + エージェントまたはGatewayでオプトアウトするには`tools.deny: ["bundle-mcp"]`を使用します +- プロジェクトローカルのPi設定はバンドルデフォルトの後にも適用されるため、 + 必要に応じてワークスペース設定でバンドルMCPエントリを上書きできます +- バンドルMCPツールカタログは登録前に決定的にソートされるため、 + 上流の`listTools()`の順序変更によってプロンプトキャッシュのツールブロックが頻繁に変化することはありません ##### トランスポート -MCP サーバーは stdio または HTTP トランスポートを使用できます。 +MCPサーバーはstdioまたはHTTPトランスポートを使用できます。 -**Stdio** は子プロセスを起動します。 +**Stdio**は子プロセスを起動します。 ```json { @@ -133,7 +136,7 @@ MCP サーバーは stdio または HTTP トランスポートを使用できま } ``` -**HTTP** は、デフォルトでは `sse`、要求された場合は `streamable-http` で実行中の MCP サーバーに接続します。 +**HTTP**は、デフォルトでは`sse`で、要求された場合は`streamable-http`で実行中のMCPサーバーへ接続します。 ```json { @@ -152,159 +155,160 @@ MCP サーバーは stdio または HTTP トランスポートを使用できま } ``` -- `transport` は `"streamable-http"` または `"sse"` に設定できます。省略した場合、OpenClaw は `sse` を使用します -- `type: "http"` は CLI ネイティブの downstream 形状です。OpenClaw config では `transport: "streamable-http"` を使用してください。`openclaw mcp set` と `openclaw doctor --fix` は一般的な alias を正規化します。 -- 許可される URL scheme は `http:` と `https:` のみです -- `headers` 値は `${ENV_VAR}` 補間に対応しています -- `command` と `url` の両方を含むサーバーエントリは拒否されます -- URL 認証情報（userinfo と query params）は、ツールの +- `transport`は`"streamable-http"`または`"sse"`に設定できます。省略した場合、OpenClawは`sse`を使用します +- `type: "http"`はCLIネイティブの下流形状です。OpenClaw設定では`transport: "streamable-http"`を使用します。`openclaw mcp set`と`openclaw doctor --fix`は一般的な別名を正規化します。 +- 許可されるURLスキームは`http:`と`https:`のみです +- `headers`の値は`${ENV_VAR}`補間に対応します +- `command`と`url`の両方を持つサーバーエントリは拒否されます +- URL認証情報（userinfoとクエリパラメーター）は、ツール 説明とログから秘匿されます -- `connectionTimeoutMs` は、stdio と HTTP の両トランスポートについて、 - デフォルトの 30 秒接続タイムアウトを上書きします +- `connectionTimeoutMs`は、stdioとHTTPの両方のトランスポートについて、 + デフォルトの30秒接続タイムアウトを上書きします ##### ツール命名 -OpenClaw は、バンドル MCP ツールを `serverName__toolName` 形式の -provider-safe な名前で登録します。たとえば、`"vigil-harbor"` というキーのサーバーが -`memory_search` ツールを公開している場合、`vigil-harbor__memory_search` として登録されます。 +OpenClawは、`serverName__toolName`形式のプロバイダー安全な名前でバンドルMCPツールを登録します。 +たとえば、`memory_search`ツールを公開する`"vigil-harbor"`キーのサーバーは、 +`vigil-harbor__memory_search`として登録されます。 -- `A-Za-z0-9_-` 以外の文字は `-` に置き換えられます -- サーバープレフィックスは 30 文字に制限されます -- 完全なツール名は 64 文字に制限されます -- 空のサーバー名は `mcp` にフォールバックします -- sanitized 後に衝突した名前は数値 suffix で曖昧さが解消されます -- 最終的に公開されるツール順序は safe name によって決定論的になり、繰り返しの Pi +- `A-Za-z0-9_-`以外の文字は`-`に置き換えられます +- サーバープレフィックスは30文字に制限されます +- 完全なツール名は64文字に制限されます +- 空のサーバー名は`mcp`にフォールバックします +- サニタイズ後に衝突する名前は、数値サフィックスで曖昧さを解消します +- 最終的に公開されるツール順序は安全な名前によって決定的になり、繰り返しのPi ターンでキャッシュが安定します -- プロファイル filtering は、1 つのバンドル MCP サーバー由来のすべてのツールを - `bundle-mcp` による plugin-owned として扱うため、profile allowlists と deny lists には、 - 個別の公開ツール名または `bundle-mcp` Plugin key のどちらも含められます +- プロファイルフィルタリングは、1つのバンドルMCPサーバーからのすべてのツールを + `bundle-mcp`が所有するPluginとして扱うため、プロファイルの許可リストと拒否リストには、 + 個別の公開ツール名または`bundle-mcp`Pluginキーのいずれかを含められます -#### 組み込み Pi 設定 +#### 埋め込みPi設定 -- Claude `settings.json` は、バンドルが有効化されたときにデフォルトの組み込み Pi 設定としてインポートされます -- OpenClaw は shell override keys を適用前に sanitize します +- Claudeの`settings.json`は、バンドルが有効な場合にデフォルトの埋め込みPi設定としてインポートされます +- OpenClawは、シェル上書きキーを適用前にサニタイズします -Sanitized keys: +サニタイズされるキー: - `shellPath` - `shellCommandPrefix` -#### 組み込み Pi LSP +#### 埋め込みPi LSP -- 有効化された Claude バンドルは LSP サーバー設定を提供できます -- OpenClaw は `.lsp.json` と、manifest で宣言された任意の `lspServers` パスを読み込みます -- バンドル LSP 設定は、有効な組み込み Pi LSP デフォルトにマージされます -- 現在実行可能なのは、対応している stdio backed LSP サーバーのみです。未対応の - トランスポートも `openclaw plugins inspect ` には表示されます +- 有効なClaudeバンドルはLSPサーバー設定を提供できます +- OpenClawは`.lsp.json`に加え、マニフェスト宣言の`lspServers`パスを読み込みます +- バンドルLSP設定は、有効な埋め込みPi LSPデフォルトへマージされます +- 現在実行可能なのは、対応済みのstdioバックエンドLSPサーバーのみです。非対応の + トランスポートも`openclaw plugins inspect `には表示されます ### 検出されるが実行されないもの -これらは認識され診断に表示されますが、OpenClaw は実行しません。 +これらは認識され診断に表示されますが、OpenClawは実行しません。 -- Claude `agents`、`hooks.json` automation、`outputStyles` -- Cursor `.cursor/agents`、`.cursor/hooks.json`、`.cursor/rules` -- capability reporting を超える Codex inline/app metadata +- Claudeの`agents`、`hooks.json`自動化、`outputStyles` +- Cursorの`.cursor/agents`、`.cursor/hooks.json`、`.cursor/rules` +- 機能レポートを超えるCodexインライン/アプリメタデータ ## バンドル形式 - + マーカー: `.codex-plugin/plugin.json` - オプションのコンテンツ: `skills/`、`hooks/`、`.mcp.json`、`.app.json` + 任意のコンテンツ: `skills/`、`hooks/`、`.mcp.json`、`.app.json` - Codex バンドルは、skill ルートと OpenClaw 形式の - hook-pack ディレクトリ（`HOOK.md` + `handler.ts`）を使用すると、OpenClaw に最もよく適合します。 + Codexバンドルは、skillルートとOpenClawスタイルの + フックパックディレクトリ（`HOOK.md` + `handler.ts`）を使用すると、OpenClawに最もよく適合します。 - - 2 つの検出モード: + + 2つの検出モード: - - **Manifest ベース:** `.claude-plugin/plugin.json` - - **Manifest なし:** デフォルトの Claude レイアウト（`skills/`、`commands/`、`agents/`、`hooks/`、`.mcp.json`、`.lsp.json`、`settings.json`） + - **マニフェストベース:** `.claude-plugin/plugin.json` + - **マニフェストなし:** デフォルトのClaudeレイアウト（`skills/`、`commands/`、`agents/`、`hooks/`、`.mcp.json`、`.lsp.json`、`settings.json`） - Claude 固有の挙動: + Claude固有の動作: - - `commands/` は skill コンテンツとして扱われます - - `settings.json` は組み込み Pi 設定にインポートされます（shell override keys は sanitized されます） - - `.mcp.json` は対応している stdio ツールを組み込み Pi に公開します - - `.lsp.json` と manifest で宣言された `lspServers` パスは、組み込み Pi LSP デフォルトに読み込まれます - - `hooks/hooks.json` は検出されますが実行されません - - manifest 内のカスタム component paths は追加的です（デフォルトを置き換えるのではなく拡張します） + - `commands/`はskillコンテンツとして扱われます + - `settings.json`は埋め込みPi設定へインポートされます（シェル上書きキーはサニタイズされます） + - `.mcp.json`は、対応するstdioツールを埋め込みPiに公開します + - `.lsp.json`とマニフェスト宣言の`lspServers`パスは、埋め込みPi LSPデフォルトへ読み込まれます + - `hooks/hooks.json`は検出されますが実行されません + - マニフェスト内のカスタムコンポーネントパスは加算的です（デフォルトを置き換えるのではなく拡張します） - + マーカー: `.cursor-plugin/plugin.json` - オプションのコンテンツ: `skills/`、`.cursor/commands/`、`.cursor/agents/`、`.cursor/rules/`、`.cursor/hooks.json`、`.mcp.json` + 任意のコンテンツ: `skills/`、`.cursor/commands/`、`.cursor/agents/`、`.cursor/rules/`、`.cursor/hooks.json`、`.mcp.json` - - `.cursor/commands/` は skill コンテンツとして扱われます - - `.cursor/rules/`、`.cursor/agents/`、`.cursor/hooks.json` は detect-only です + - `.cursor/commands/`はskillコンテンツとして扱われます + - `.cursor/rules/`、`.cursor/agents/`、`.cursor/hooks.json`は検出のみです ## 検出の優先順位 -OpenClaw はまずネイティブ Plugin 形式を確認します。 +OpenClawは最初にネイティブPlugin形式を確認します。 -1. `openclaw.plugin.json`、または `openclaw.extensions` を含む有効な `package.json` — **ネイティブ Plugin** として扱われます -2. バンドルマーカー（`.codex-plugin/`、`.claude-plugin/`、またはデフォルトの Claude/Cursor レイアウト）— **バンドル** として扱われます +1. `openclaw.plugin.json`、または`openclaw.extensions`を持つ有効な`package.json` — **ネイティブPlugin**として扱われます +2. バンドルマーカー（`.codex-plugin/`、`.claude-plugin/`、またはデフォルトのClaude/Cursorレイアウト） — **バンドル**として扱われます -ディレクトリに両方が含まれる場合、OpenClaw はネイティブの経路を使用します。これにより、 -dual-format パッケージがバンドルとして部分的にインストールされることを防ぎます。 +ディレクトリに両方が含まれる場合、OpenClawはネイティブ経路を使用します。これにより、 +デュアル形式パッケージがバンドルとして部分的にインストールされることを防ぎます。 -## Runtime 依存関係とクリーンアップ +## ランタイム依存関係とクリーンアップ -- サードパーティ互換バンドルには、起動時の `npm install` 修復は適用されません。 - これらは `openclaw plugins install` を通じてインストールし、必要なものをすべて - インストール済み Plugin ディレクトリ内に同梱する必要があります。 -- OpenClaw 所有の bundled Plugin は、core に軽量に同梱されるか、 - Plugin インストーラーを通じてダウンロード可能です。Gateway 起動時にそれらのために - package manager が実行されることはありません。 -- `openclaw doctor --fix` は legacy staged dependency directories を削除し、 - local Plugin index に存在しない、設定済みのダウンロード可能な Plugin をインストールできます。 +- サードパーティ互換バンドルでは、起動時の`npm install`修復は行われません。それらは + `openclaw plugins install`を通じてインストールされ、必要なものをすべて + インストール済みPluginディレクトリ内に同梱している必要があります。 +- OpenClaw所有の同梱Pluginは、core内で軽量に同梱されるか、 + Pluginインストーラーを通じてダウンロード可能です。Gateway起動時に、それらのために + パッケージマネージャーが実行されることはありません。 +- `openclaw doctor --fix`は、レガシーのステージング済み依存関係ディレクトリを削除し、 + 設定が参照しているにもかかわらずローカルPluginインデックスに存在しないダウンロード可能Pluginを + 復旧できます。 ## セキュリティ -バンドルはネイティブ Plugin よりも狭い信頼境界を持ちます。 +バンドルは、ネイティブPluginよりも狭い信頼境界を持ちます。 -- OpenClaw は任意のバンドル runtime module をプロセス内に読み込みません -- Skills と hook-pack パスは Plugin root の内側に留まる必要があります（boundary-checked） +- OpenClawは任意のバンドルランタイムモジュールをインプロセスで読み込みません +- SkillsとフックパックのパスはPluginルート内に留まる必要があります（境界チェック済み） - 設定ファイルは同じ境界チェックで読み込まれます -- 対応している stdio MCP サーバーは subprocess として起動される場合があります +- 対応するstdio MCPサーバーはサブプロセスとして起動される場合があります -これにより、バンドルはデフォルトでより安全になります。ただし、サードパーティバンドルについては、 -それらが公開する機能に対する trusted content として扱う必要があります。 +これにより、バンドルはデフォルトでより安全になりますが、それでもサードパーティ +バンドルは、公開する機能について信頼済みコンテンツとして扱う必要があります。 ## トラブルシューティング - - `openclaw plugins inspect ` を実行してください。capability が listed されているものの - not wired と表示される場合、それは product limit であり、壊れたインストールではありません。 + + `openclaw plugins inspect `を実行します。機能が一覧表示されているものの + 未接続としてマークされている場合、それは製品上の制限であり、インストールの破損ではありません。 - - バンドルが有効化されており、markdown ファイルが検出済みの - `commands/` または `skills/` ルート内にあることを確認してください。 + + バンドルが有効であり、Markdownファイルが検出済みの + `commands/`または`skills/`ルート内にあることを確認してください。 - - `settings.json` からの組み込み Pi 設定のみが対応しています。OpenClaw は - バンドル設定を raw config patches として扱いません。 + + `settings.json`からの埋め込みPi設定のみが対応対象です。OpenClawは + バンドル設定を生の設定パッチとして扱いません。 - - `hooks/hooks.json` は detect-only です。実行可能な hooks が必要な場合は、 - OpenClaw hook-pack レイアウトを使用するか、ネイティブ Plugin を同梱してください。 + + `hooks/hooks.json`は検出のみです。実行可能なフックが必要な場合は、 + OpenClawフックパックレイアウトを使用するか、ネイティブPluginを提供してください。 ## 関連 -- [Plugin をインストールして設定する](/ja-JP/tools/plugin) -- [Plugin を構築する](/ja-JP/plugins/building-plugins) — ネイティブ Plugin を作成する -- [Plugin Manifest](/ja-JP/plugins/manifest) — ネイティブ manifest schema +- [Pluginのインストールと設定](/ja-JP/tools/plugin) +- [Pluginの構築](/ja-JP/plugins/building-plugins) — ネイティブPluginを作成する +- [Pluginマニフェスト](/ja-JP/plugins/manifest) — ネイティブマニフェストスキーマ diff --git a/docs/ja-JP/plugins/codex-harness.md b/docs/ja-JP/plugins/codex-harness.md index 23b7f33c0..46da7f702 100644 --- a/docs/ja-JP/plugins/codex-harness.md +++ b/docs/ja-JP/plugins/codex-harness.md @@ -1,61 +1,61 @@ --- read_when: - - 同梱の Codex app-server ハーネスを使用したい場合 - - Codex ハーネス設定例が必要です - - Codex のみのデプロイでは、PI にフォールバックするのではなく失敗させたい -summary: OpenClaw の埋め込みエージェントターンを同梱の Codex app-server ハーネス経由で実行する + - 同梱の Codex アプリサーバーハーネスを使用したい場合 + - Codex ハーネス設定の例が必要です + - Codex のみのデプロイでは、PI にフォールバックするのではなく失敗するようにしたい +summary: 同梱の Codex app-server ハーネスを通じて OpenClaw の埋め込みエージェントターンを実行する title: Codex ハーネス x-i18n: - generated_at: "2026-05-03T21:36:14Z" + generated_at: "2026-05-05T01:48:07Z" model: gpt-5.5 provider: openai - source_hash: f5187e54e2dc94e511c0243227f741d3486669f595c2b15cf239b1c03ea466c8 + source_hash: 76302351e7e162e858dd6e3cffca84b3fd54497dd060104da9f90fe4c1a33f9b source_path: plugins/codex-harness.md workflow: 16 --- -バンドルされた `codex` Plugin により、OpenClaw は組み込みの PI ハーネスではなく -Codex app-server 経由で埋め込みエージェントターンを実行できます。 +バンドルされた `codex` plugin により、OpenClaw は組み込みの PI ハーネスではなく +Codex アプリサーバー経由で埋め込みエージェントターンを実行できます。 -Codex に低レベルのエージェントセッションを所有させたい場合に使用します。対象は、モデル -検出、ネイティブスレッド再開、ネイティブ Compaction、app-server 実行です。 -OpenClaw は引き続き、チャットチャンネル、セッションファイル、モデル選択、ツール、 -承認、メディア配信、可視トランスクリプトミラーを所有します。 +低レベルのエージェントセッションを Codex に所有させたい場合に使用します。対象には、モデル +検出、ネイティブスレッドの再開、ネイティブ Compaction、アプリサーバー実行が含まれます。 +OpenClaw は引き続きチャットチャネル、セッションファイル、モデル選択、ツール、 +承認、メディア配信、表示されるトランスクリプトミラーを所有します。 -ソースチャットターンが Codex ハーネス経由で実行される場合、デプロイメントで -`messages.visibleReplies` が明示的に設定されていなければ、可視返信はデフォルトで -OpenClaw の `message` ツールになります。エージェントは Codex ターンを非公開で -完了できます。チャンネルに投稿されるのは `message(action="send")` を呼び出した場合だけです。 -従来の自動配信パスで直接チャットの最終返信を維持するには、 +ソースチャットターンが Codex ハーネス経由で実行される場合、デプロイで +`messages.visibleReplies` が明示的に設定されていなければ、表示される返信は既定で +OpenClaw の `message` ツールになります。エージェントは Codex ターンを非公開で完了できます。 +チャネルに投稿するのは `message(action="send")` を呼び出したときだけです。 +直接チャットの最終返信を従来の自動配信パスに維持するには、 `messages.visibleReplies: "automatic"` を設定します。 -Codex Heartbeat ターンではデフォルトで `heartbeat_respond` ツールも取得するため、 +Codex Heartbeat ターンにも既定で `heartbeat_respond` ツールが付与されるため、 エージェントは最終テキストにその制御フローをエンコードせずに、ウェイクを静かに保つか通知するかを記録できます。 -Heartbeat 固有の主導性ガイダンスは、Heartbeat ターン自体で Codex コラボレーションモードの -開発者指示として送信されます。通常のチャットターンでは、通常のランタイムプロンプトに -Heartbeat の思想を持ち込まず、Codex Default モードを復元します。 +Heartbeat 固有の自発性ガイダンスは、その Heartbeat ターン自体で Codex のコラボレーションモード +developer 指示として送信されます。通常のチャットターンでは、通常の +ランタイムプロンプトに Heartbeat の思想を持ち越すのではなく、Codex Default モードに戻します。 状況を把握したい場合は、 [エージェントランタイム](/ja-JP/concepts/agent-runtimes) から始めてください。短く言うと、 `openai/gpt-5.5` はモデル参照、`codex` はランタイムであり、Telegram、 -Discord、Slack、または別のチャンネルは通信サーフェスのままです。 +Discord、Slack、または別のチャネルがコミュニケーション面として残ります。 ## クイック設定 -「OpenClaw 内の Codex」を望むほとんどのユーザーが求めているのはこのルートです。つまり、 -ChatGPT/Codex サブスクリプションでサインインし、その後ネイティブ -Codex app-server ランタイム経由で埋め込みエージェントターンを実行します。モデル参照は引き続き -`openai/gpt-*` として正規のままです。サブスクリプション認証は -`openai-codex/*` モデルプレフィックスではなく、Codex アカウント/プロファイルから取得されます。 +「OpenClaw 内の Codex」を求めるほとんどのユーザーには、この経路が適しています。つまり、 +ChatGPT/Codex サブスクリプションでサインインし、ネイティブ +Codex アプリサーバーランタイム経由で埋め込みエージェントターンを実行します。モデル参照は引き続き +`openai/gpt-*` として正規のままです。サブスクリプション認証は Codex アカウント/プロファイルから取得され、 +`openai-codex/*` モデル接頭辞からではありません。 -まだの場合は、まず Codex OAuth でサインインします。 +まだ実行していない場合は、まず Codex OAuth でサインインします。 ```bash openclaw models auth login --provider openai-codex ``` -次に、バンドルされた `codex` Plugin を有効化し、Codex ランタイムを強制します。 +次に、バンドルされた `codex` plugin を有効にし、Codex ランタイムを強制します。 ```json5 { @@ -92,182 +92,178 @@ openclaw models auth login --provider openai-codex } ``` -ネイティブ Codex ランタイムを意図している場合は、`openai-codex/gpt-*` を使用しないでください。そのプレフィックスは、 -明示的な「PI 経由の Codex OAuth」ルートです。設定変更は新規または -リセット済みセッションに適用されます。既存セッションは記録済みのランタイムを保持します。 +ネイティブ Codex ランタイムを意図している場合、`openai-codex/gpt-*` は使用しないでください。この接頭辞は、 +明示的な「PI 経由の Codex OAuth」経路です。設定変更は新規または +リセットされたセッションに適用されます。既存のセッションは記録済みのランタイムを保持します。 -## この Plugin が変更すること +## この plugin が変更すること -バンドルされた `codex` Plugin は、いくつかの個別機能を提供します。 +バンドルされた `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 ネイティブツール/ファイナライズイベントを観測/ブロックできるようにします。 | +| ネイティブ埋め込みランタイム | `agentRuntime.id: "codex"` | OpenClaw の埋め込みエージェントターンを Codex アプリサーバー経由で実行します。 | +| ネイティブチャット制御コマンド | `/codex bind`, `/codex resume`, `/codex steer`, ... | メッセージング会話から Codex アプリサーバースレッドをバインドおよび制御します。 | +| Codex アプリサーバープロバイダー/カタログ | `codex` internals, surfaced through the harness | ランタイムがアプリサーバーモデルを検出して検証できるようにします。 | +| Codex メディア理解パス | `codex/*` image-model compatibility paths | 対応する画像理解モデル向けに、境界付き Codex アプリサーバーターンを実行します。 | +| ネイティブフックリレー | Plugin hooks around Codex-native events | OpenClaw が対応する Codex ネイティブのツール/最終化イベントを監視またはブロックできるようにします。 | -Plugin を有効化すると、これらの機能が利用可能になります。有効化しても、次のことは**行いません**。 +plugin を有効にすると、これらの機能が利用可能になります。これは次のことを**行いません**。 -- すべての OpenAI モデルで Codex の使用を開始する +- すべての OpenAI モデルで Codex を使い始める - `openai-codex/*` モデル参照をネイティブランタイムに変換する -- ACP/acpx をデフォルトの Codex パスにする -- すでに PI ランタイムを記録済みの既存セッションをホットスイッチする -- OpenClaw のチャンネル配信、セッションファイル、認証プロファイル保存、または +- ACP/acpx を既定の Codex パスにする +- すでに PI ランタイムを記録している既存セッションをホットスイッチする +- OpenClaw のチャネル配信、セッションファイル、認証プロファイルストレージ、または メッセージルーティングを置き換える -同じ Plugin は、ネイティブ `/codex` チャット制御コマンドサーフェスも所有します。 -Plugin が有効で、ユーザーがチャットから Codex スレッドのバインド、再開、誘導、停止、または検査を求めた場合、 -エージェントは ACP よりも `/codex ...` を優先する必要があります。ACP は、ユーザーが ACP/acpx を求めた場合、 -または ACP Codex アダプターをテストしている場合の明示的なフォールバックのままです。 +同じ plugin は、ネイティブ `/codex` チャット制御コマンド面も所有します。 +plugin が有効で、ユーザーがチャットから Codex スレッドをバインド、再開、操作、停止、または調査するよう求めた場合、 +エージェントは ACP より `/codex ...` を優先する必要があります。ACP は、ユーザーが ACP/acpx を求めた場合、または ACP +Codex アダプターをテストしている場合の明示的なフォールバックのままです。 -ネイティブ Codex ターンでは、公開互換レイヤーとして OpenClaw Plugin フックが保持されます。 -これらはプロセス内 OpenClaw フックであり、Codex `hooks.json` コマンドフックではありません。 +ネイティブ 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` はミラーされたトランスクリプトレコード用 +- `before_message_write` はミラーされたトランスクリプトレコード向け - Codex `Stop` リレー経由の `before_agent_finalize` - `agent_end` -Plugin は、ランタイム非依存のツール結果ミドルウェアも登録でき、OpenClaw がツールを実行した後、 -結果が Codex に返される前に OpenClaw の動的ツール結果を書き換えられます。これは公開 -`tool_result_persist` Plugin フックとは別のものです。この公開フックは、OpenClaw 所有のトランスクリプト -ツール結果書き込みを変換します。 +Plugins は、ランタイム非依存のツール結果ミドルウェアも登録できます。これは、 +OpenClaw がツールを実行した後、結果が Codex に返される前に OpenClaw の動的ツール結果を書き換えるためのものです。 +これは、OpenClaw 所有のトランスクリプト +ツール結果書き込みを変換する公開 `tool_result_persist` plugin フックとは別です。 -Plugin フックのセマンティクス自体については、[Plugin フック](/ja-JP/plugins/hooks) -と [Plugin ガード動作](/ja-JP/tools/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/*` モデル参照は互換性のために引き続き -ハーネスを自動選択しますが、ランタイムで裏付けられた従来のプロバイダープレフィックスは、 -通常のモデル/プロバイダー選択肢としては表示されません。 +ハーネスは既定で無効です。新しい設定では OpenAI モデル参照を +`openai/gpt-*` として正規に保ち、ネイティブアプリサーバー実行を望む場合は +`agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を明示的に強制する必要があります。 +従来の `codex/*` モデル参照は互換性のために引き続き自動でハーネスを選択しますが、 +ランタイムに裏付けられた従来プロバイダー接頭辞は通常のモデル/プロバイダー選択肢として表示されません。 -`codex` Plugin が有効でもプライマリモデルがまだ -`openai-codex/*` の場合、`openclaw doctor` はルートを変更するのではなく警告します。これは -意図的です。`openai-codex/*` は PI Codex OAuth/サブスクリプションパスのままであり、 -ネイティブ app-server 実行は明示的なランタイム選択のままです。 +`codex` plugin が有効でも、プライマリモデルがまだ +`openai-codex/*` の場合、`openclaw doctor` は経路を変更せずに警告します。これは意図的です。 +`openai-codex/*` は引き続き PI Codex OAuth/サブスクリプションパスであり、 +ネイティブアプリサーバー実行は明示的なランタイム選択のままです。 -## ルートマップ +## 経路マップ 設定を変更する前に、この表を使用してください。 -| 望む動作 | モデル参照 | ランタイム設定 | 認証/プロファイルルート | 期待されるステータスラベル | -| ---------------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | -| ネイティブ Codex ランタイムを使う ChatGPT/Codex サブスクリプション | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth または Codex アカウント | `Runtime: OpenAI Codex` | -| 通常の OpenClaw ランナー経由の OpenAI API | `openai/gpt-*` | 省略または `runtime: "pi"` | OpenAI API キー | `Runtime: OpenClaw Pi Default` | -| PI 経由の ChatGPT/Codex サブスクリプション | `openai-codex/gpt-*` | 省略または `runtime: "pi"` | OpenAI Codex OAuth プロバイダー | `Runtime: OpenClaw Pi Default` | -| 保守的な自動モードを使う混在プロバイダー | プロバイダー固有の参照 | `agentRuntime.id: "auto"` | 選択されたプロバイダーごと | 選択されたランタイムに依存 | -| 明示的な Codex ACP アダプターセッション | ACP プロンプト/モデル依存 | `sessions_spawn` と `runtime: "acp"` | ACP バックエンド認証 | ACP タスク/セッションステータス | +| 望ましい動作 | モデル参照 | ランタイム設定 | 認証/プロファイル経路 | 期待されるステータスラベル | +| ------------------------------------------------------ | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | +| ネイティブ Codex ランタイムでの ChatGPT/Codex サブスクリプション | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth または Codex アカウント | `Runtime: OpenAI Codex` | +| 通常の OpenClaw ランナー経由の OpenAI API | `openai/gpt-*` | omitted or `runtime: "pi"` | OpenAI API キー | `Runtime: OpenClaw Pi Default` | +| PI 経由の ChatGPT/Codex サブスクリプション | `openai-codex/gpt-*` | omitted or `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` | +| 保守的な自動モードでの混在プロバイダー | provider-specific refs | `agentRuntime.id: "auto"` | 選択されたプロバイダーごと | 選択されたランタイムに依存 | +| 明示的な Codex ACP アダプターセッション | ACP prompt/model dependent | `sessions_spawn` with `runtime: "acp"` | ACP バックエンド認証 | ACP タスク/セッションステータス | -重要な分岐は、プロバイダーとランタイムです。 +重要な分岐は、プロバイダーとランタイムの違いです。 -- `openai-codex/*` は「PI はどのプロバイダー/認証ルートを使うべきか」に答えます -- `agentRuntime.id: "codex"` は「どのループがこの - 埋め込みターンを実行すべきか」に答えます -- `/codex ...` は「このチャットはどのネイティブ Codex 会話をバインドまたは - 制御すべきか」に答えます -- ACP は「acpx はどの外部ハーネスプロセスを起動すべきか」に答えます +- `openai-codex/*` は「PI はどのプロバイダー/認証経路を使用するべきか」に答えます。 +- `agentRuntime.id: "codex"` は「この埋め込みターンをどのループで実行するべきか」に答えます。 +- `/codex ...` は「このチャットはどのネイティブ Codex 会話をバインドまたは制御するべきか」に答えます。 +- ACP は「acpx はどの外部ハーネスプロセスを起動するべきか」に答えます。 -## 適切なモデルプレフィックスを選ぶ +## 適切なモデル接頭辞を選ぶ -OpenAI ファミリーのルートはプレフィックス固有です。一般的なサブスクリプションと -ネイティブ Codex ランタイムの組み合わせでは、`agentRuntime.id: "codex"` とともに `openai/*` を使用します。 -PI 経由で Codex OAuth を意図的に使いたい場合にのみ、`openai-codex/*` を使用します。 +OpenAI ファミリーの経路は接頭辞ごとに固有です。一般的なサブスクリプションと +ネイティブ Codex ランタイムのセットアップでは、`agentRuntime.id: "codex"` とともに `openai/*` を使用します。 +`openai-codex/*` は、PI 経由の Codex OAuth を意図している場合にのみ使用します。 -| モデル参照 | ランタイムパス | 使用する場合 | -| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `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 実行で ChatGPT/Codex サブスクリプション認証を使いたい場合。 | +| モデル参照 | ランタイムパス | 使用する場合 | +| --------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------- | +| `openai/gpt-5.4` | OpenClaw/PI plumbing 経由の OpenAI provider | `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 アプリサーバーハーネス | ネイティブ Codex 実行で ChatGPT/Codex サブスクリプション認証を使いたい場合。 | -GPT-5.5 は、アカウントで公開されている場合、直接 OpenAI API キーと Codex サブスクリプションの両方のルートに表示されることがあります。 -ネイティブ Codex ランタイムには Codex app-server -ハーネス付きの `openai/gpt-5.5`、PI OAuth には `openai-codex/gpt-5.5`、 -直接 API キートラフィックには Codex ランタイムオーバーライドなしの -`openai/gpt-5.5` を使用します。 +GPT-5.5 は、アカウントで公開されている場合、直接 OpenAI API キー経路と Codex サブスクリプション経路の両方に表示されることがあります。 +ネイティブ Codex ランタイムには Codex アプリサーバー +ハーネス付きの `openai/gpt-5.5` を、PI OAuth には `openai-codex/gpt-5.5` を、 +直接 API キートラフィックには Codex ランタイム上書きなしの `openai/gpt-5.5` を使用します。 -従来の `codex/gpt-*` 参照は、互換エイリアスとして引き続き受け入れられます。Doctor の -互換性移行は、従来のプライマリランタイム参照を正規モデル参照に書き換え、 -ランタイムポリシーを別途記録します。一方、フォールバック専用の従来参照は、 -ランタイムがエージェントコンテナ全体に対して設定されるため、変更されません。 +従来の `codex/gpt-*` 参照は、互換エイリアスとして引き続き受け入れられます。Doctor +互換性マイグレーションは、従来のプライマリランタイム参照を正規モデル +参照に書き換え、ランタイムポリシーを別に記録します。一方、フォールバック専用の従来参照は、 +ランタイムがエージェントコンテナー全体に対して設定されるため、変更されません。 新しい PI Codex OAuth 設定では `openai-codex/gpt-*` を使用し、新しいネイティブ -app-server ハーネス設定では `agentRuntime.id: "codex"` とともに -`openai/gpt-*` を使用してください。 +アプリサーバーハーネス設定では `openai/gpt-*` に +`agentRuntime.id: "codex"` を組み合わせて使用します。 -`agents.defaults.imageModel` も同じプレフィックス分岐に従います。 -画像理解を OpenAI Codex OAuth プロバイダーパス経由で実行する場合は -`openai-codex/gpt-*` を使用します。画像理解を境界付き Codex app-server ターン経由で実行する場合は -`codex/gpt-*` を使用します。Codex app-server モデルは -画像入力サポートを広告している必要があります。テキスト専用の Codex モデルは、メディアターンが -開始される前に失敗します。 +`agents.defaults.imageModel` も同じ接頭辞分岐に従います。画像理解を OpenAI +Codex OAuth プロバイダーパス経由で実行する必要がある場合は、 +`openai-codex/gpt-*` を使用します。画像理解を境界付き Codex アプリサーバーターン経由で実行する必要がある場合は、 +`codex/gpt-*` を使用します。Codex アプリサーバーモデルは +画像入力対応を広告している必要があります。テキスト専用 Codex モデルは、メディアターンが +開始する前に失敗します。 -現在のセッションで有効なハーネスを確認するには `/status` を使用します。選択が予想外の場合は、 -`agents/harness` サブシステムのデバッグログを有効にし、Gateway の構造化された `agent harness selected` レコードを -調べてください。これには、選択されたハーネス ID、選択理由、ランタイム/フォールバックポリシー、および -`auto` モードでは各 Plugin 候補のサポート結果が含まれます。 +現在のセッションの有効なハーネスを確認するには `/status` を使用します。選択が予想外の場合は、 +`agents/harness` サブシステムのデバッグログを有効にし、Gateway の構造化された +`agent harness selected` レコードを確認します。そこには、選択されたハーネス ID、選択理由、 +ランタイム/フォールバックポリシー、および `auto` モードでは各 plugin 候補のサポート結果が含まれます。 ### doctor 警告の意味 -次のすべてが真の場合、`openclaw doctor` は警告します。 +`openclaw doctor` は、以下がすべて true の場合に警告します。 -- バンドルされた `codex` Plugin が有効または許可されている +- バンドルされた `codex` plugin が有効または許可されている - エージェントのプライマリモデルが `openai-codex/*` -- そのエージェントの有効ランタイムが `codex` ではない +- そのエージェントの有効なランタイムが `codex` ではない -この警告が存在するのは、ユーザーがしばしば「Codex Plugin が有効」を -「ネイティブ Codex app-server ランタイム」を意味すると期待するためです。OpenClaw はその飛躍を行いません。警告の意味は次のとおりです。 +この警告が存在するのは、ユーザーがしばしば「Codex plugin 有効」は +「ネイティブ Codex アプリサーバーランタイム」を意味すると期待するためです。OpenClaw はその飛躍を行いません。 +この警告の意味は次のとおりです。 -- PI 経由の ChatGPT/Codex OAuth を意図している場合、**変更は不要です**。 -- ネイティブ app-server 実行を意図している場合は、モデルを `openai/` に変更し、 +- PI 経由の ChatGPT/Codex OAuth を意図していた場合、**変更は不要**です。 +- ネイティブアプリサーバー実行を意図していた場合は、モデルを `openai/` に変更し、 `agentRuntime.id: "codex"` を設定します。 -- セッションランタイムのピン留めは固定されるため、ランタイム変更後も既存セッションには - `/new` または `/reset` が必要です。 +- ランタイム変更後も、既存セッションには `/new` または `/reset` が必要です。 + セッションのランタイムピンは固定されるためです。 ハーネス選択はライブセッション制御ではありません。埋め込みターンが実行されると、 -OpenClaw は選択されたハーネス ID をそのセッションに記録し、同じセッション ID の -後続ターンでもそれを使い続けます。今後のセッションで別のハーネスを使いたい場合は -`agentRuntime` 設定または `OPENCLAW_AGENT_RUNTIME` を変更してください。 -既存の会話を PI と Codex の間で切り替える前に、新しいセッションを開始するには -`/new` または `/reset` を使用します。これにより、1 つのトランスクリプトを +OpenClaw は選択されたハーネス ID をそのセッションに記録し、同じセッション ID の後続ターンでもそれを使い続けます。 +将来のセッションで別のハーネスを使いたい場合は、`agentRuntime` 設定または +`OPENCLAW_AGENT_RUNTIME` を変更します。既存の会話を PI と Codex の間で切り替える前に、 +`/new` または `/reset` を使って新しいセッションを開始します。これにより、1 つのトランスクリプトを 互換性のない 2 つのネイティブセッションシステムで再生することを避けられます。 -ハーネス固定前に作成されたレガシーセッションは、トランスクリプト履歴があると PI 固定として扱われます。設定を変更した後、その会話を Codex に参加させるには `/new` または `/reset` を使用します。 +既存のセッションがハーネスのピン留め前に作成され、トランスクリプト履歴を持っている場合は、PI にピン留めされたものとして扱われます。設定変更後にその会話を Codex にオプトインするには、`/new` または `/reset` を使用します。 -`/status` は有効なモデルランタイムを表示します。デフォルトの PI ハーネスは `Runtime: OpenClaw Pi Default` として表示され、Codex app-server ハーネスは `Runtime: OpenAI Codex` として表示されます。 +`/status` は有効なモデルランタイムを表示します。デフォルトの PI ハーネスは `Runtime: OpenClaw Pi Default` と表示され、Codex アプリサーバーハーネスは `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、plugins、設定、スレッド状態、またはネイティブの `$HOME/.agents/skills` を読み取りません。 +- Codex アプリサーバー `0.125.0` 以降。バンドルされた Plugin は、デフォルトで互換性のある Codex アプリサーバーバイナリを管理するため、`PATH` 上のローカル `codex` コマンドは通常のハーネス起動に影響しません。 +- アプリサーバープロセスまたは OpenClaw の Codex 認証ブリッジで Codex 認証が利用可能であること。ローカルのアプリサーバー起動では、各エージェントに対して OpenClaw 管理の Codex ホームと分離された子 `HOME` を使用するため、デフォルトでは個人の `~/.codex` アカウント、Skills、Plugin、設定、スレッド状態、またはネイティブの `$HOME/.agents/skills` を読み取りません。 -Plugin は、古い、またはバージョン未指定の app-server ハンドシェイクをブロックします。これにより、OpenClaw はテスト済みのプロトコルサーフェス上に保たれます。 +Plugin は、古い、またはバージョンなしのアプリサーバーハンドシェイクをブロックします。これにより、OpenClaw はテスト済みのプロトコルサーフェス上に維持されます。 -ライブおよび Docker スモークテストでは、認証は通常 Codex CLI アカウント、または OpenClaw の `openai-codex` 認証プロファイルから取得されます。ローカル stdio app-server 起動では、アカウントが存在しない場合に `CODEX_API_KEY` / `OPENAI_API_KEY` にフォールバックすることもできます。 +ライブおよび Docker スモークテストでは、認証は通常、Codex CLI アカウントまたは OpenClaw の `openai-codex` 認証プロファイルから取得されます。ローカル stdio アプリサーバー起動では、アカウントが存在しない場合に `CODEX_API_KEY` / `OPENAI_API_KEY` にフォールバックすることもできます。 -## ワークスペースのブートストラップファイル +## ワークスペースブートストラップファイル -Codex は、ネイティブのプロジェクトドキュメント検出を通じて `AGENTS.md` を自身で処理します。OpenClaw は合成 Codex プロジェクトドキュメントファイルを書き込まず、ペルソナファイルについて Codex のフォールバックファイル名にも依存しません。Codex のフォールバックは `AGENTS.md` が存在しない場合にのみ適用されるためです。 +Codex は、ネイティブのプロジェクトドキュメント検出を通じて `AGENTS.md` 自体を処理します。OpenClaw は、Codex の合成プロジェクトドキュメントファイルを書き込まず、ペルソナファイル用の Codex フォールバックファイル名にも依存しません。Codex のフォールバックは `AGENTS.md` がない場合にのみ適用されるためです。 -OpenClaw のワークスペース同等性のために、Codex ハーネスは他のブートストラップファイル（存在する場合は `SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、および `MEMORY.md`）を解決し、`thread/start` と `thread/resume` で Codex 設定命令を通じて転送します。これにより、`AGENTS.md` を複製せずに、`SOUL.md` と関連するワークスペースのペルソナ/プロファイルコンテキストが見える状態に保たれます。 +OpenClaw のワークスペース整合性のため、Codex ハーネスは他のブートストラップファイル（存在する場合は `SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、および `MEMORY.md`）を解決し、`thread/start` と `thread/resume` で Codex 設定指示を通じて転送します。これにより、`AGENTS.md` を複製せずに、`SOUL.md` と関連するワークスペースのペルソナ/プロファイルコンテキストを可視化できます。 -## 他のモデルと並べて Codex を追加する +## Codex を他のモデルと併用する -同じエージェントが Codex と非 Codex プロバイダーモデルを自由に切り替える必要がある場合、`agentRuntime.id: "codex"` をグローバルに設定しないでください。強制されたランタイムは、そのエージェントまたはセッションのすべての埋め込みターンに適用されます。そのランタイムが強制されている間に Anthropic モデルを選択しても、OpenClaw は引き続き Codex ハーネスを試行し、そのターンを PI 経由で静かにルーティングする代わりにクローズドに失敗します。 +同じエージェントが Codex と非 Codex プロバイダーモデルを自由に切り替える必要がある場合は、`agentRuntime.id: "codex"` をグローバルに設定しないでください。強制されたランタイムは、そのエージェントまたはセッションのすべての埋め込みターンに適用されます。そのランタイムが強制されている状態で Anthropic モデルを選択すると、OpenClaw はそれでも Codex ハーネスを試行し、そのターンを PI 経由で静かにルーティングするのではなく、クローズドに失敗します。 -代わりに、次のいずれかの形を使用します。 +代わりに、次のいずれかの形を使用してください。 -- `agentRuntime.id: "codex"` を持つ専用エージェントに Codex を置く。 -- 通常の混在プロバイダー利用のために、デフォルトエージェントを `agentRuntime.id: "auto"` と PI フォールバックのままにする。 -- レガシーの `codex/*` 参照は互換性のためにのみ使用する。新しい設定では、`openai/*` と明示的な Codex ランタイムポリシーを優先する。 +- `agentRuntime.id: "codex"` を指定した専用エージェントに Codex を置く。 +- 通常の混在プロバイダー利用のために、デフォルトエージェントは `agentRuntime.id: "auto"` と PI フォールバックのままにする。 +- 互換性のためだけに既存の `codex/*` 参照を使用する。新しい設定では、`openai/*` と明示的な Codex ランタイムポリシーを優先してください。 -たとえば、これはデフォルトエージェントを通常の自動選択のままにし、別の Codex エージェントを追加します。 +たとえば、これはデフォルトエージェントを通常の自動選択のままにし、別個の Codex エージェントを追加します。 ```json5 { @@ -305,31 +301,31 @@ OpenClaw のワークスペース同等性のために、Codex ハーネスは この形では次のようになります。 -- デフォルトの `main` エージェントは、通常のプロバイダーパスと PI 互換フォールバックを使用します。 -- `codex` エージェントは Codex app-server ハーネスを使用します。 -- `codex` エージェントで Codex が見つからない、またはサポートされていない場合、PI を静かに使用する代わりにターンは失敗します。 +- デフォルトの `main` エージェントは通常のプロバイダーパスと PI 互換性フォールバックを使用します。 +- `codex` エージェントは Codex アプリサーバーハーネスを使用します。 +- `codex` エージェントで Codex が欠落している、またはサポートされていない場合、そのターンは PI を静かに使用するのではなく失敗します。 -## エージェントコマンドのルーティング +## エージェントコマンドルーティング -エージェントは「Codex」という単語だけではなく、意図によってユーザーリクエストをルーティングする必要があります。 +エージェントは、「Codex」という単語だけでなく、意図に基づいてユーザーリクエストをルーティングする必要があります。 -| ユーザーが依頼する内容... | エージェントが使用すべきもの... | +| ユーザーの依頼内容... | エージェントが使用すべきもの... | | ------------------------------------------------------ | ------------------------------------------------ | -| 「このチャットを Codex にバインドして」 | `/codex bind` | -| 「Codex スレッド `` をここで再開して」 | `/codex resume ` | -| 「Codex スレッドを表示して」 | `/codex threads` | -| 「失敗した Codex 実行のサポートレポートを提出して」 | `/diagnostics [note]` | -| 「この添付スレッドについてだけ Codex フィードバックを送信して」 | `/codex diagnostics [note]` | -| 「Codex ランタイムで ChatGPT/Codex サブスクリプションを使って」 | `openai/*` と `agentRuntime.id: "codex"` | -| 「PI 経由で ChatGPT/Codex サブスクリプションを使って」 | `openai-codex/*` モデル参照 | -| 「ACP/acpx 経由で Codex を実行して」 | ACP `sessions_spawn({ runtime: "acp", ... })` | -| 「スレッド内で Claude Code/Gemini/OpenCode/Cursor を開始して」 | ACP/acpx、`/codex` ではなくネイティブサブエージェントでもない | +| 「このチャットを Codex にバインドする」 | `/codex bind` | +| 「Codex スレッド `` をここで再開する」 | `/codex resume ` | +| 「Codex スレッドを表示する」 | `/codex threads` | +| 「問題のある Codex 実行のサポートレポートを提出する」 | `/diagnostics [note]` | +| 「この添付スレッドについてのみ Codex フィードバックを送信する」 | `/codex diagnostics [note]` | +| 「ChatGPT/Codex サブスクリプションを Codex ランタイムで使用する」 | `openai/*` に加えて `agentRuntime.id: "codex"` | +| 「ChatGPT/Codex サブスクリプションを PI 経由で使用する」 | `openai-codex/*` モデル参照 | +| 「ACP/acpx 経由で Codex を実行する」 | ACP `sessions_spawn({ runtime: "acp", ... })` | +| 「スレッドで Claude Code/Gemini/OpenCode/Cursor を開始する」 | ACP/acpx。`/codex` でもネイティブサブエージェントでもない | -OpenClaw は、ACP が有効で、ディスパッチ可能で、ロード済みランタイムバックエンドに支えられている場合にのみ、ACP スポーンのガイダンスをエージェントに広告します。ACP が利用できない場合、システムプロンプトと Plugin Skills は、ACP ルーティングについてエージェントに教えるべきではありません。 +OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれたランタイムバックエンドに支えられている場合にのみ、ACP スポーンガイダンスをエージェントに通知します。ACP が利用できない場合、システムプロンプトと Plugin Skills は ACP ルーティングについてエージェントに教えるべきではありません。 ## Codex 専用デプロイ -すべての埋め込みエージェントターンが Codex を使用することを証明する必要がある場合、Codex ハーネスを強制します。明示的な Plugin ランタイムはクローズドに失敗し、PI 経由で静かに再試行されることはありません。 +すべての埋め込みエージェントターンが Codex を使用することを証明する必要がある場合は、Codex ハーネスを強制します。明示的な Plugin ランタイムはクローズドに失敗し、PI 経由で静かに再試行されることはありません。 ```json5 { @@ -350,11 +346,11 @@ OpenClaw は、ACP が有効で、ディスパッチ可能で、ロード済み OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Codex が強制されている場合、Codex Plugin が無効である、app-server が古すぎる、または app-server を開始できないと、OpenClaw は早期に失敗します。 +Codex が強制されている場合、Codex Plugin が無効、アプリサーバーが古すぎる、またはアプリサーバーを起動できないとき、OpenClaw は早期に失敗します。 ## エージェントごとの Codex -デフォルトエージェントが通常の自動選択を維持したまま、1 つのエージェントを Codex 専用にできます。 +デフォルトエージェントは通常の自動選択を維持しつつ、1 つのエージェントを Codex 専用にできます。 ```json5 { @@ -383,17 +379,17 @@ Codex が強制されている場合、Codex Plugin が無効である、app-ser } ``` -エージェントとモデルを切り替えるには、通常のセッションコマンドを使用します。`/new` は新しい OpenClaw セッションを作成し、Codex ハーネスは必要に応じてサイドカー app-server スレッドを作成または再開します。`/reset` はそのスレッドの OpenClaw セッションバインディングをクリアし、次のターンで現在の設定からハーネスを再度解決できるようにします。 +エージェントとモデルを切り替えるには、通常のセッションコマンドを使用します。`/new` は新しい OpenClaw セッションを作成し、Codex ハーネスは必要に応じてサイドカーアプリサーバースレッドを作成または再開します。`/reset` はそのスレッドの OpenClaw セッションバインディングをクリアし、次のターンで現在の設定からハーネスを再度解決できるようにします。 ## モデル検出 -デフォルトでは、Codex Plugin は利用可能なモデルを app-server に問い合わせます。検出が失敗する、またはタイムアウトした場合、次のバンドル済みフォールバックカタログを使用します。 +デフォルトでは、Codex Plugin は利用可能なモデルをアプリサーバーに問い合わせます。検出が失敗またはタイムアウトした場合は、次のバンドル済みフォールバックカタログを使用します。 - GPT-5.5 - GPT-5.4 mini - GPT-5.2 -`plugins.entries.codex.config.discovery` で検出を調整できます。 +`plugins.entries.codex.config.discovery` の下で検出を調整できます。 ```json5 { @@ -413,7 +409,7 @@ Codex が強制されている場合、Codex Plugin が無効である、app-ser } ``` -Codex のプローブを避け、フォールバックカタログに固定して起動したい場合は、検出を無効にします。 +起動時に Codex のプローブを避け、フォールバックカタログに固定したい場合は、検出を無効にします。 ```json5 { @@ -432,17 +428,17 @@ Codex のプローブを避け、フォールバックカタログに固定し } ``` -## App-server 接続とポリシー +## アプリサーバー接続とポリシー -デフォルトでは、Plugin は OpenClaw が管理する Codex バイナリをローカルで次のように起動します。 +デフォルトでは、Plugin は OpenClaw の管理下にある Codex バイナリをローカルで次のように起動します。 ```bash codex app-server --listen stdio:// ``` -管理対象バイナリは `codex` Plugin パッケージに同梱されています。これにより、app-server のバージョンは、ローカルにたまたまインストールされている別の Codex CLI ではなく、バンドルされた Plugin に紐づけられます。別の実行ファイルを意図的に実行したい場合にのみ `appServer.command` を設定してください。 +管理対象バイナリは `codex` Plugin パッケージに同梱されています。これにより、アプリサーバーのバージョンは、ローカルにたまたまインストールされている別個の 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"` を設定します。 @@ -464,11 +460,11 @@ Codex のガーディアンレビュー付き承認にオプトインするに } ``` -Guardian モードは Codex のネイティブ自動レビュー承認パスを使用します。Codex がサンドボックスの外に出る、ワークスペース外に書き込む、またはネットワークアクセスなどの権限を追加するよう求めると、Codex はその承認リクエストを人間向けプロンプトではなくネイティブレビュアーにルーティングします。レビュアーは Codex のリスクフレームワークを適用し、特定のリクエストを承認または拒否します。YOLO モードより多くのガードレールが必要だが、無人エージェントにも進捗を出させる必要がある場合は 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 トランスポートを使用します。 +すでに実行中のアプリサーバーには、WebSocket トランスポートを使用します。 ```json5 { @@ -490,26 +486,26 @@ 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、plugins、設定、アカウント、スレッド状態は、オペレーター個人の Codex CLI ホームから漏れ込むのではなく、OpenClaw エージェントにスコープされます。 +stdio アプリサーバー起動はデフォルトで OpenClaw のプロセス環境を継承しますが、OpenClaw は Codex アプリサーバーのアカウントブリッジを所有し、`CODEX_HOME` と `HOME` の両方を、そのエージェントの OpenClaw 状態配下にあるエージェントごとのディレクトリに設定します。Codex 自身のスキルローダーは `$CODEX_HOME/skills` と `$HOME/.agents/skills` を読み取るため、ローカルアプリサーバー起動では両方の値が分離されます。これにより、Codex ネイティブの Skills、Plugin、設定、アカウント、スレッド状態は、オペレーター個人の Codex CLI ホームから漏れ込むのではなく、OpenClaw エージェントにスコープされます。 -OpenClaw plugins と OpenClaw skill スナップショットは、引き続き OpenClaw 独自の Plugin レジストリと skill ローダーを通じて流れます。個人用 Codex CLI アセットは流れません。OpenClaw エージェントの一部にすべき有用な Codex CLI Skills または plugins がある場合は、明示的にインベントリします。 +OpenClaw Plugin と OpenClaw スキルスナップショットは、引き続き OpenClaw 自身の Plugin レジストリとスキルローダーを通じて流れます。個人の Codex CLI アセットは流れません。OpenClaw エージェントの一部にすべき有用な Codex CLI Skills または Plugin がある場合は、明示的に棚卸ししてください。 ```bash openclaw migrate codex --dry-run openclaw migrate apply codex --yes ``` -Codex 移行プロバイダーは、Skills を現在の OpenClaw エージェントワークスペースにコピーします。Codex ネイティブの plugins、フック、設定ファイルは、コマンドを実行したり、MCP サーバーを公開したり、認証情報を含んだりする可能性があるため、自動的に有効化されるのではなく、手動レビュー用に報告またはアーカイブされます。 +Codex 移行プロバイダーは、Skills を現在の OpenClaw エージェントワークスペースにコピーします。Codex ネイティブの Plugin、フック、設定ファイルは、コマンドを実行したり、MCP サーバーを公開したり、認証情報を含んだりする可能性があるため、自動的に有効化されるのではなく、手動レビューのために報告またはアーカイブされます。 認証は次の順序で選択されます。 1. エージェント用の明示的な OpenClaw Codex 認証プロファイル。 -2. そのエージェントの Codex ホームにある app-server の既存アカウント。 -3. ローカル stdio app-server 起動の場合のみ、app-server アカウントが存在せず、OpenAI 認証がまだ必要なときは、`CODEX_API_KEY`、次に `OPENAI_API_KEY`。 +2. そのエージェントの Codex ホーム内にあるアプリサーバーの既存アカウント。 +3. ローカル stdio アプリサーバー起動の場合のみ、アプリサーバーアカウントが存在せず、OpenAI 認証がまだ必要なときは、`CODEX_API_KEY`、次に `OPENAI_API_KEY`。 -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 自身のアカウントを使用してください。 +OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロファイルを検出した場合、生成される Codex 子プロセスから `CODEX_API_KEY` と `OPENAI_API_KEY` を削除します。これにより、Gateway レベルの API キーは埋め込みや直接の OpenAI モデルに使用できるまま、ネイティブ Codex アプリサーバーのターンが誤って API 経由で課金されることを防ぎます。明示的な Codex API キープロファイルとローカル stdio 環境キーのフォールバックは、継承された子プロセス環境ではなく、アプリサーバーログインを使用します。WebSocket アプリサーバー接続は Gateway 環境 API キーフォールバックを受け取りません。明示的な認証プロファイルまたはリモートアプリサーバー自身のアカウントを使用してください。 -デプロイで追加の環境分離が必要な場合は、それらの変数を `appServer.clearEnv` に追加します。 +デプロイで追加の環境分離が必要な場合は、それらの変数を `appServer.clearEnv` に追加してください。 ```json5 { @@ -528,51 +524,46 @@ OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロフ } ``` -`appServer.clearEnv` は、生成された Codex app-server の子プロセスにのみ影響します。 +`appServer.clearEnv` は、生成された Codex app-server 子プロセスにのみ影響します。 -Codex の動的ツールは、デフォルトで `native-first` プロファイルを使用します。このモードでは、 +Codex の動的ツールはデフォルトで `native-first` プロファイルを使用します。このモードでは、 OpenClaw は Codex ネイティブのワークスペース操作と重複する動的ツールを公開しません: -`read`、`write`、`edit`、`apply_patch`、`exec`、`process`、および -`update_plan`。メッセージング、セッション、メディア、 -cron、ブラウザー、ノード、gateway、`heartbeat_respond`、`web_search` などの OpenClaw 統合ツールは -引き続き利用できます。 +`read`、`write`、`edit`、`apply_patch`、`exec`、`process`、`update_plan`。メッセージング、セッション、メディア、 +cron、ブラウザー、ノード、gateway、`heartbeat_respond`、`web_search` などの OpenClaw 連携ツールは引き続き +利用できます。 -サポートされている最上位の Codex plugin フィールド: +サポートされているトップレベルの Codex Plugin フィールド: -| フィールド | デフォルト | 意味 | -| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- | -| `codexDynamicToolsProfile` | `"native-first"` | Codex app-server に OpenClaw の動的ツールセット全体を公開するには、`"openclaw-compat"` を使用します。 | -| `codexDynamicToolsExclude` | `[]` | Codex app-server のターンから除外する追加の OpenClaw 動的ツール名。 | +| フィールド | デフォルト | 意味 | +| -------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- | +| `codexDynamicToolsProfile` | `"native-first"` | Codex app-server に OpenClaw の動的ツールセット全体を公開するには `"openclaw-compat"` を使用します。 | +| `codexDynamicToolsExclude` | `[]` | Codex app-server のターンから省略する追加の OpenClaw 動的ツール名。 | サポートされている `appServer` フィールド: -| フィールド | デフォルト | 意味 | -| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `transport` | `"stdio"` | `"stdio"` は Codex を生成し、`"websocket"` は `url` に接続します。 | -| `command` | 管理対象の Codex バイナリ | stdio transport の実行ファイル。管理対象バイナリを使用するには未設定のままにし、明示的に上書きする場合にのみ設定します。 | -| `args` | `["app-server", "--listen", "stdio://"]` | stdio transport の引数。 | -| `url` | 未設定 | WebSocket app-server の URL。 | -| `authToken` | 未設定 | WebSocket transport の Bearer トークン。 | -| `headers` | `{}` | 追加の WebSocket ヘッダー。 | -| `clearEnv` | `[]` | OpenClaw が継承環境を構築した後に、生成された stdio app-server プロセスから削除される追加の環境変数名。`CODEX_HOME` と `HOME` は、ローカル起動時の OpenClaw のエージェント単位の Codex 分離用に予約されています。 | -| `requestTimeoutMs` | `60000` | app-server control-plane 呼び出しのタイムアウト。 | -| `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"` | スレッドの開始、再開、ターンに送信されるネイティブ Codex 承認ポリシー。 | +| `sandbox` | `"danger-full-access"` | スレッドの開始、再開に送信されるネイティブ 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 セッションレーンを解放します。 ローカルテスト用の環境上書きは引き続き利用できます: @@ -582,30 +573,27 @@ Codex ターンを中断し、診断タイムアウトを記録し、OpenClaw - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`appServer.command` が未設定の場合、`OPENCLAW_CODEX_APP_SERVER_BIN` は管理対象バイナリを -迂回します。 +`appServer.command` が未設定の場合、`OPENCLAW_CODEX_APP_SERVER_BIN` は管理対象バイナリをバイパスします。 `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` は削除されました。代わりに -`plugins.entries.codex.config.appServer.mode: "guardian"` を使用するか、 -1 回限りのローカルテストには `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` を使用してください。構成は -Codex ハーネス設定の残りと同じレビュー済みファイル内に plugin の動作を保持するため、 -再現可能なデプロイでは構成が推奨されます。 +`plugins.entries.codex.config.appServer.mode: "guardian"` を使用するか、単発のローカルテストには +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` を使用してください。繰り返し可能なデプロイには設定を推奨します。これは、Codex ハーネス設定の残りと同じレビュー済みファイル内に Plugin の動作を保持できるためです。 ## コンピューター使用 -コンピューター使用については、専用の設定ガイドで説明しています: +コンピューター使用については、専用のセットアップガイドで説明しています: [Codex コンピューター使用](/ja-JP/plugins/codex-computer-use)。 -要約すると、OpenClaw はデスクトップ制御アプリを vendoring せず、デスクトップ操作自体も -実行しません。Codex app-server を準備し、`computer-use` MCP サーバーが利用可能であることを -検証したうえで、Codex モードのターン中に Codex がネイティブ MCP ツール呼び出しを処理できるようにします。 +要約すると、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 所有のコンピューター使用と直接 MCP 登録の違いについては、 [Codex コンピューター使用](/ja-JP/plugins/codex-computer-use) を参照してください。 -最小構成: +最小設定: ```json5 { @@ -632,29 +620,26 @@ Codex marketplace フロー外で TryCua ドライバーに直接アクセスす } ``` -設定はコマンドサーフェスから確認またはインストールできます: +セットアップはコマンドサーフェスから確認またはインストールできます: - `/codex computer-use status` - `/codex computer-use install` - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -コンピューター使用は macOS 固有であり、Codex MCP サーバーがアプリを制御できるようになる前に -ローカル OS 権限が必要な場合があります。`computerUse.enabled` が true で MCP -サーバーが利用できない場合、Codex モードのターンは、ネイティブのコンピューター使用ツールなしで -黙って実行されるのではなく、スレッド開始前に失敗します。marketplace の選択肢、 +コンピューター使用は macOS 固有であり、Codex MCP サーバーがアプリを制御できるようになる前に、ローカル OS 権限が必要になる場合があります。`computerUse.enabled` が true で MCP +サーバーが利用できない場合、Codex モードのターンは、ネイティブのコンピューター使用ツールなしで黙って実行されるのではなく、スレッド開始前に失敗します。marketplace の選択肢、 リモートカタログの制限、ステータス理由、トラブルシューティングについては、 [Codex コンピューター使用](/ja-JP/plugins/codex-computer-use) を参照してください。 -`computerUse.autoInstall` が true の場合、Codex がローカル marketplace をまだ検出していなければ、 -OpenClaw は `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` から -標準のバンドル済み Codex Desktop marketplace を登録できます。ランタイムまたはコンピューター使用の -構成を変更した後は、既存セッションが古い PI または Codex スレッドバインディングを保持しないように、 -`/new` または `/reset` を使用してください。 +`computerUse.autoInstall` が true の場合、Codex がまだローカル marketplace を検出していなければ、OpenClaw は +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` から +標準のバンドル済み Codex Desktop marketplace を登録できます。ランタイムまたはコンピューター使用の設定を変更した後は、既存のセッションが古い +PI または Codex スレッドバインディングを保持しないように、`/new` または `/reset` を使用してください。 -## 一般的なレシピ +## よく使うレシピ -デフォルトの stdio transport を使用するローカル Codex: +デフォルトの stdio トランスポートを使うローカル Codex: ```json5 { @@ -668,7 +653,7 @@ OpenClaw は `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` } ``` -Codex 専用ハーネス検証: +Codex のみのハーネス検証: ```json5 { @@ -690,7 +675,7 @@ Codex 専用ハーネス検証: } ``` -Guardian レビュー済み Codex 承認: +Guardian レビュー付き Codex 承認: ```json5 { @@ -712,7 +697,7 @@ Guardian レビュー済み Codex 承認: } ``` -明示的なヘッダーを持つリモート app-server: +明示的なヘッダーを使うリモート app-server: ```json5 { @@ -735,78 +720,67 @@ 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 models` は、ライブ Codex app-server モデルを一覧表示します。 +- `/codex status` は、ライブのアプリサーバー接続、モデル、アカウント、レート制限、MCP サーバー、skills を表示します。 +- `/codex models` は、ライブの Codex アプリサーバーモデルを一覧表示します。 - `/codex threads [filter]` は、最近の Codex スレッドを一覧表示します。 - `/codex resume ` は、現在の OpenClaw セッションを既存の Codex スレッドにアタッチします。 -- `/codex compact` は、アタッチされたスレッドを compact するよう Codex app-server に要求します。 +- `/codex compact` は、アタッチされたスレッドを圧縮するよう Codex アプリサーバーに要求します。 - `/codex review` は、アタッチされたスレッドに対して Codex ネイティブレビューを開始します。 -- `/codex diagnostics [note]` は、アタッチされたスレッドについて Codex 診断フィードバックを送信する前に確認します。 -- `/codex computer-use status` は、構成済みの Computer Use plugin と MCP サーバーを確認します。 -- `/codex computer-use install` は、構成済みの Computer Use plugin をインストールし、MCP サーバーを再読み込みします。 +- `/codex diagnostics [note]` は、アタッチされたスレッドの Codex 診断フィードバックを送信する前に確認します。 +- `/codex computer-use status` は、設定済みの Computer Use plugin と MCP サーバーを確認します。 +- `/codex computer-use install` は、設定済みの Computer Use plugin をインストールし、MCP サーバーを再読み込みします。 - `/codex account` は、アカウントとレート制限の状態を表示します。 -- `/codex mcp` は、Codex app-server MCP サーバーの状態を一覧表示します。 -- `/codex skills` は、Codex app-server skills を一覧表示します。 +- `/codex mcp` は、Codex アプリサーバーの MCP サーバー状態を一覧表示します。 +- `/codex skills` は、Codex アプリサーバーの skills を一覧表示します。 + +Codex が使用量制限の失敗を報告した場合、Codex が提供していれば、OpenClaw は次の +アプリサーバーのリセット時刻を含めます。同じ会話で `/codex account` を使い、 +現在のアカウントとレート制限ウィンドウを確認してください。 ### 一般的なデバッグワークフロー -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 が特定のツールまたは計画を選んだ理由を尋ねたりできます。 +2. 診断リクエストを一度承認します。この承認によりローカル Gateway 診断 zip が作成され、セッションが Codex ハーネスを使用しているため、関連する Codex フィードバックバンドルも OpenAI サーバーに送信されます。 +3. 完了した診断返信をバグレポートまたはサポートスレッドにコピーします。これには、ローカルバンドルパス、プライバシー概要、OpenClaw セッション ID、Codex スレッド ID、各 Codex スレッドの `Inspect locally` 行が含まれます。 +4. 実行を自分でデバッグしたい場合は、表示された `Inspect locally` コマンドをターミナルで実行します。これは `codex resume ` のような形で、ネイティブ Codex スレッドを開き、会話を調査したり、ローカルで続行したり、特定のツールや計画を選んだ理由を Codex に尋ねたりできます。 -現在アタッチされているスレッドについて、完全な OpenClaw -Gateway 診断バンドルなしで Codex フィードバックアップロードだけを特に行いたい場合にのみ、 -`/codex diagnostics [note]` を使用してください。ほとんどのサポートレポートでは、 -`/diagnostics [note]` のほうが適切な開始点です。ローカル Gateway の状態と Codex -スレッド ID を 1 つの返信にまとめるためです。完全なプライバシーモデルとグループチャットでの動作については、 -[診断エクスポート](/ja-JP/gateway/diagnostics)を参照してください。 +完全な OpenClaw Gateway 診断バンドルなしで、現在アタッチされているスレッドの Codex +フィードバックアップロードだけが特に必要な場合にのみ、`/codex diagnostics [note]` を使ってください。ほとんどのサポートレポートでは、`/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 は一覧表示されません。 +コア 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 は、プライベート承認ルートを通じて所有者に送信されます。プライベートな所有者ルートがない場合、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 アプリサーバーの `feedback/upload` を呼び出し、利用可能な場合は、一覧にある各スレッドと生成された Codex サブスレッドのログを含めるようアプリサーバーに要求します。アップロードは Codex の通常のフィードバック経路を通じて OpenAI サーバーに送信されます。そのアプリサーバーで Codex フィードバックが無効になっている場合、コマンドはアプリサーバーエラーを返します。完了した診断返信には、送信されたスレッドのチャネル、OpenClaw セッション ID、Codex スレッド ID、ローカルの `codex resume ` コマンドが一覧表示されます。承認を拒否または無視した場合、OpenClaw はそれらの Codex ID を表示しません。このアップロードは、ローカル Gateway 診断エクスポートを置き換えるものではありません。 -`/codex resume` は、ハーネスが通常のターンで使用するものと同じ sidecar バインディングファイルを書き込みます。次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw モデルを app-server に渡し、拡張履歴を有効なままにします。 +`/codex resume` は、ハーネスが通常のターンで使用するものと同じサイドカーのバインディングファイルを書き込みます。次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw モデルをアプリサーバーに渡し、拡張履歴を有効なままにします。 ### CLI から Codex スレッドを調査する -問題のある Codex 実行を理解する最速の方法は、多くの場合、ネイティブ Codex +不適切な Codex 実行を理解する最速の方法は、多くの場合、ネイティブ Codex スレッドを直接開くことです。 ```sh 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 アプリサーバースレッドについては `/codex threads [filter]` からスレッド ID を取得し、シェルで同じ `codex resume` コマンドを実行することもできます。 -このコマンドサーフェスには Codex app-server `0.125.0` 以降が必要です。将来版またはカスタム app-server がその JSON-RPC メソッドを公開していない場合、個々の制御メソッドは `unsupported by this Codex app-server` と報告されます。 +このコマンドサーフェスには Codex アプリサーバー `0.125.0` 以降が必要です。将来版またはカスタムのアプリサーバーがその JSON-RPC メソッドを公開していない場合、個々の制御メソッドは `unsupported by this Codex app-server` と報告されます。 ## フック境界 @@ -814,92 +788,92 @@ Codex ハーネスには 3 つのフックレイヤーがあります。 | レイヤー | 所有者 | 目的 | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw plugin フック | OpenClaw | PI と Codex ハーネス全体での製品/plugin 互換性。 | -| Codex app-server 拡張ミドルウェア | OpenClaw bundled plugins | OpenClaw 動的ツール周辺のターンごとのアダプター動作。 | -| Codex ネイティブフック | Codex | Codex config からの低レベルな Codex ライフサイクルとネイティブツールポリシー。 | +| OpenClaw plugin フック | OpenClaw | PI と Codex ハーネス全体でのプロダクト/plugin 互換性。 | +| Codex アプリサーバー拡張ミドルウェア | OpenClaw バンドル plugins | OpenClaw 動的ツール周辺のターンごとのアダプター動作。 | +| Codex ネイティブフック | Codex | Codex 設定による低レベルの Codex ライフサイクルとネイティブツールポリシー。 | -OpenClaw は、OpenClaw plugin の動作をルーティングするために、プロジェクトまたはグローバルの Codex `hooks.json` ファイルを使用しません。サポートされるネイティブツールと権限ブリッジについて、OpenClaw は `PreToolUse`、`PostToolUse`、`PermissionRequest`、`Stop` 用のスレッドごとの Codex config を注入します。`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 がアプリサーバーまたはネイティブフックコールバックを通じてその操作を公開しない限り、ネイティブ Codex スレッドを書き換えることはできません。 -Compaction と LLM ライフサイクル投影は、ネイティブ Codex フックコマンドではなく、Codex app-server 通知と OpenClaw アダプター状態から得られます。OpenClaw の `before_compaction`、`after_compaction`、`llm_input`、`llm_output` イベントはアダプターレベルの観測であり、Codex の内部リクエストまたは Compaction ペイロードのバイト単位のキャプチャではありません。 +Compaction と LLM ライフサイクルの投影は、Codex アプリサーバー通知と OpenClaw アダプター状態に由来し、ネイティブ Codex フックコマンドには由来しません。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` アプリサーバー通知は、軌跡とデバッグのために `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 は実行経路内に留まります。 | -| プロンプトとコンテキスト plugins | サポート | OpenClaw はプロンプトオーバーレイを構築し、スレッドの開始または再開前にコンテキストを Codex ターンへ投影します。 | -| コンテキストエンジンライフサイクル | サポート | Assemble、ingest またはターン後メンテナンス、およびコンテキストエンジン Compaction の調整が Codex ターンで実行されます。 | -| 動的ツールフック | サポート | `before_tool_call`、`after_tool_call`、およびツール結果ミドルウェアが、OpenClaw 所有の動的ツールの周辺で実行されます。 | -| ライフサイクルフック | アダプター観測としてサポート | `llm_input`、`llm_output`、`agent_end`、`before_compaction`、`after_compaction` は、正直な Codex モードペイロードで発火します。 | -| 最終回答改訂ゲート | ネイティブフックリレー経由でサポート | Codex `Stop` は `before_agent_finalize` にリレーされます。`revise` は最終化前に Codex へもう 1 回のモデルパスを要求します。 | -| ネイティブ shell、patch、MCP のブロックまたは観測 | ネイティブフックリレー経由でサポート | Codex `PreToolUse` と `PostToolUse` は、Codex app-server `0.125.0` 以降の MCP ペイロードを含む、コミット済みネイティブツールサーフェスにリレーされます。ブロックはサポートされますが、引数の書き換えはサポートされません。 | -| ネイティブ権限ポリシー | ネイティブフックリレー経由でサポート | runtime が公開している場合、Codex `PermissionRequest` は OpenClaw ポリシーを通じてルーティングできます。OpenClaw が判断を返さない場合、Codex は通常の guardian またはユーザー承認経路を続行します。 | -| App-server 軌跡キャプチャ | サポート | OpenClaw は app-server に送信したリクエストと、受信した app-server 通知を記録します。 | +| サーフェス | サポート | 理由 | +| ------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Codex 経由の OpenAI モデルループ | サポート | Codex アプリサーバーが OpenAI ターン、ネイティブスレッド再開、ネイティブツール継続を所有します。 | +| OpenClaw チャネルルーティングと配信 | サポート | Telegram、Discord、Slack、WhatsApp、iMessage、その他のチャネルはモデルランタイムの外側に留まります。 | +| OpenClaw 動的ツール | サポート | Codex が OpenClaw にこれらのツールの実行を求めるため、OpenClaw は実行経路に留まります。 | +| プロンプトとコンテキスト plugins | サポート | 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` は、最終化の前にもう一度モデルパスを実行するよう Codex に要求します。 | +| ネイティブシェル、パッチ、MCP のブロックまたは観測 | ネイティブフックリレー経由でサポート | Codex `PreToolUse` と `PostToolUse` は、Codex アプリサーバー `0.125.0` 以降の MCP ペイロードを含む、確定済みのネイティブツールサーフェスに対してリレーされます。ブロックはサポートされますが、引数の書き換えはサポートされません。 | +| ネイティブ権限ポリシー | ネイティブフックリレー経由でサポート | ランタイムが公開している場合、Codex `PermissionRequest` は OpenClaw ポリシーを通じてルーティングできます。OpenClaw が判断を返さない場合、Codex は通常のガーディアンまたはユーザー承認経路を続行します。 | +| アプリサーバー軌跡キャプチャ | サポート | OpenClaw は、アプリサーバーに送信したリクエストと、受信したアプリサーバー通知を記録します。 | -Codex runtime v1 でサポートされないもの: +Codex ランタイム v1 でサポートされないもの: -| サーフェス | V1 境界 | 今後の方向 | +| サーフェス | V1 の境界 | 今後の方向性 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| ネイティブツール引数の変更 | Codex ネイティブのツール実行前 hook はブロックできますが、OpenClaw は Codex ネイティブのツール引数を書き換えません。 | 置換用ツール入力には Codex hook/schema サポートが必要です。 | -| 編集可能な Codex ネイティブのトランスクリプト履歴 | Codex が正規のネイティブスレッド履歴を所有します。OpenClaw はミラーを所有し、将来のコンテキストを投影できますが、サポートされていない内部を変更すべきではありません。 | ネイティブスレッドの操作が必要な場合は、明示的な Codex app-server API を追加します。 | -| Codex ネイティブツールレコードの `tool_result_persist` | その hook は OpenClaw が所有するトランスクリプト書き込みを変換するものであり、Codex ネイティブツールレコードを変換するものではありません。 | 変換済みレコードをミラーすることはできますが、正規の書き換えには Codex サポートが必要です。 | -| リッチなネイティブ Compaction メタデータ | OpenClaw は Compaction の開始と完了を監視しますが、安定した保持/削除リスト、トークン差分、または要約ペイロードは受け取りません。 | よりリッチな Codex Compaction イベントが必要です。 | -| Compaction への介入 | 現在の OpenClaw Compaction hook は Codex モードでは通知レベルです。 | plugins がネイティブ Compaction を拒否または書き換える必要がある場合は、Codex の Compaction 前後 hook を追加します。 | -| バイト単位で一致するモデル API リクエストキャプチャ | OpenClaw は app-server リクエストと通知をキャプチャできますが、Codex core が最終的な OpenAI API リクエストを内部で構築します。 | Codex のモデルリクエスト追跡イベントまたはデバッグ API が必要です。 | +| ネイティブツール引数の変更 | 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 が必要。 | ## ツール、メディア、Compaction -Codex ハーネスは、低レベルの組み込みエージェント実行器のみを変更します。 +Codex ハーネスが変更するのは、低レベルの組み込みエージェント実行器のみ。 -OpenClaw は引き続きツールリストを構築し、ハーネスから動的なツール結果を受け取ります。テキスト、画像、動画、音楽、TTS、承認、メッセージングツール出力は、通常の OpenClaw 配信パスを通り続けます。 +OpenClaw は引き続きツールリストを構築し、ハーネスから動的ツール結果を受け取る。テキスト、画像、動画、音楽、TTS、承認、メッセージングツールの出力は、通常の OpenClaw 配信パスを引き続き通る。 -ネイティブ hook リレーは意図的に汎用化されていますが、v1 のサポート契約は OpenClaw がテストする Codex ネイティブツールおよび権限パスに限定されます。Codex ランタイムでは、これには shell、patch、および MCP の `PreToolUse`、`PostToolUse`、`PermissionRequest` ペイロードが含まれます。ランタイム契約で名前が付けられるまでは、将来のすべての Codex hook イベントが OpenClaw Plugin サーフェスであると想定しないでください。 +ネイティブフックリレーは意図的に汎用化されているが、v1 のサポート契約は OpenClaw がテストする Codex ネイティブのツールおよび権限パスに限定される。Codex ランタイムでは、これに shell、patch、MCP の `PreToolUse`、`PostToolUse`、`PermissionRequest` ペイロードが含まれる。ランタイム契約で名前が付けられるまでは、将来のすべての Codex フックイベントが OpenClaw Plugin サーフェスであると想定しないこと。 -`PermissionRequest` では、OpenClaw はポリシーが判断した場合にのみ明示的な許可または拒否の決定を返します。決定なしの結果は許可ではありません。Codex はそれを hook 決定なしとして扱い、自身の guardian またはユーザー承認パスへフォールスルーします。 +`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 ツール承認の elicitation は、Codex が `_meta.codex_approval_kind` を `"mcp_tool_call"` としてマークした場合、OpenClaw の Plugin 承認フローを通じてルーティングされる。Codex の `request_user_input` プロンプトは発信元チャットへ送り返され、次にキューされたフォローアップメッセージは追加コンテキストとして誘導されるのではなく、そのネイティブサーバーリクエストへの回答になる。その他の MCP elicitation リクエストは引き続きフェイルクローズする。 -アクティブ実行キューの誘導は Codex app-server `turn/steer` に対応します。デフォルトの `messages.queue.mode: "steer"` では、OpenClaw は構成済みの静かな時間枠内にキューされたチャットメッセージをまとめ、到着順に 1 つの `turn/steer` リクエストとして送信します。従来の `queue` モードは個別の `turn/steer` リクエストを送信します。Codex レビューおよび手動 Compaction ターンは同一ターン誘導を拒否する場合があり、その場合 OpenClaw は選択されたモードでフォールバックが許可されていれば followup queue を使用します。[誘導キュー](/ja-JP/concepts/queue-steering)を参照してください。 +アクティブ実行キューの誘導は Codex app-server の `turn/steer` に対応付けられる。デフォルトの `messages.queue.mode: "steer"` では、OpenClaw は設定された静穏時間枠内にキューされたチャットメッセージをまとめ、到着順に 1 つの `turn/steer` リクエストとして送信する。レガシーの `queue` モードは個別の `turn/steer` リクエストを送信する。Codex のレビューターンおよび手動 Compaction ターンは同一ターンの誘導を拒否することがあり、その場合 OpenClaw は選択されたモードがフォールバックを許可していれば followup キューを使用する。[誘導キュー](/ja-JP/concepts/queue-steering)を参照。 -選択されたモデルが Codex ハーネスを使用する場合、ネイティブスレッド Compaction は Codex app-server に委任されます。OpenClaw はチャンネル履歴、検索、`/new`、`/reset`、および将来のモデルまたはハーネス切り替えのためにトランスクリプトミラーを保持します。ミラーには、ユーザープロンプト、最終的なアシスタントテキスト、および app-server が発行する場合は軽量な Codex reasoning または plan レコードが含まれます。現時点では、OpenClaw はネイティブ Compaction の開始および完了シグナルのみを記録します。人間が読める Compaction 要約や、Compaction 後に Codex が保持したエントリの監査可能なリストはまだ公開していません。 +選択されたモデルが Codex ハーネスを使用する場合、ネイティブスレッド Compaction は Codex app-server に委任される。OpenClaw はチャネル履歴、検索、`/new`、`/reset`、将来のモデルまたはハーネス切り替えのためにトランスクリプトミラーを保持する。このミラーには、ユーザープロンプト、最終的なアシスタントテキスト、app-server が出力する場合の軽量な Codex 推論または計画レコードが含まれる。現時点で OpenClaw が記録するのは、ネイティブ Compaction の開始および完了シグナルのみ。人間が読める Compaction 要約や、Compaction 後に Codex が保持したエントリの監査可能な一覧はまだ公開していない。 -Codex が正規のネイティブスレッドを所有しているため、`tool_result_persist` は現在 Codex ネイティブツール結果レコードを書き換えません。これは、OpenClaw が OpenClaw 所有のセッショントランスクリプトツール結果を書き込む場合にのみ適用されます。 +Codex が正規のネイティブスレッドを所有するため、`tool_result_persist` は現在 Codex ネイティブツール結果レコードを書き換えない。これは OpenClaw が 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 ランタイムは PI にフォールバックせず失敗します。Codex app-server が選択されると、その失敗は直接表面化します。 +**OpenClaw が Codex ではなく PI を使用する:** `agentRuntime.id: "auto"` は、Codex ハーネスが実行を要求しない場合、互換性バックエンドとして引き続き PI を使用できる。テスト中に Codex 選択を強制するには `agentRuntime.id: "codex"` を設定する。強制された Codex ランタイムは、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 が拒否される:** app-server ハンドシェイクがバージョン `0.125.0` 以降を報告するように Codex をアップグレードする。同一バージョンのプレリリースや、`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` を使用してください。継続する場合は、古いネイティブ hook 登録をクリアするために 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 を再起動して再試行する。 ## 関連 -- [エージェントハーネス plugins](/ja-JP/plugins/sdk-agent-harness) +- [エージェントハーネス Plugin](/ja-JP/plugins/sdk-agent-harness) - [エージェントランタイム](/ja-JP/concepts/agent-runtimes) - [モデルプロバイダー](/ja-JP/concepts/model-providers) - [OpenAI プロバイダー](/ja-JP/providers/openai) - [ステータス](/ja-JP/cli/status) -- [Plugin hook](/ja-JP/plugins/hooks) +- [Plugin フック](/ja-JP/plugins/hooks) - [設定リファレンス](/ja-JP/gateway/configuration-reference) - [テスト](/ja-JP/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/ja-JP/plugins/dependency-resolution.md b/docs/ja-JP/plugins/dependency-resolution.md index ed7cfeaf5..97d5f728e 100644 --- a/docs/ja-JP/plugins/dependency-resolution.md +++ b/docs/ja-JP/plugins/dependency-resolution.md @@ -1,34 +1,34 @@ --- read_when: - - Pluginパッケージのインストールをデバッグしている - - Plugin の起動、doctor、または package-manager のインストール動作を変更している - - パッケージ化された OpenClaw インストール、またはバンドルされた Plugin マニフェストを保守している + - Plugin パッケージのインストールをデバッグしています + - Plugin の起動、doctor、またはパッケージマネージャーのインストール動作を変更している + - パッケージ版 OpenClaw インストールまたは同梱 Plugin マニフェストを保守している sidebarTitle: Dependencies -summary: OpenClaw が Plugin パッケージをインストールし、Plugin の依存関係を解決する仕組み +summary: OpenClaw がプラグインパッケージをインストールし、プラグイン依存関係を解決する仕組み title: Plugin の依存関係解決 x-i18n: - generated_at: "2026-05-03T21:36:16Z" + generated_at: "2026-05-05T01:48:11Z" model: gpt-5.5 provider: openai - source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d + source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20 source_path: plugins/dependency-resolution.md workflow: 16 --- -# Plugin の依存関係解決 +# Plugin 依存関係の解決 -OpenClaw は Plugin の依存関係に関する処理をインストール/更新時に行います。ランタイム読み込みでは、パッケージマネージャーの実行、依存関係ツリーの修復、OpenClaw パッケージディレクトリの変更は行いません。 +OpenClaw は Plugin 依存関係の処理をインストール/更新時に行います。ランタイム読み込みでは、パッケージマネージャーの実行、依存関係ツリーの修復、OpenClaw パッケージディレクトリの変更は行いません。 -## 責任範囲の分担 +## 責任分担 Plugin パッケージは自身の依存関係グラフを所有します。 -- ランタイム依存関係は Plugin パッケージの `dependencies` または `optionalDependencies` に配置する -- SDK/core インポートは peer または OpenClaw が提供するインポートとする -- ローカル開発 Plugin は、すでにインストール済みの依存関係を自分で持ち込む -- npm と git の Plugin は OpenClaw が所有するパッケージルートにインストールされる +- ランタイム依存関係は Plugin パッケージの `dependencies` または `optionalDependencies` に置く +- SDK/コアの import は peer、または OpenClaw から提供される import +- ローカル開発用 Plugin は、依存関係がすでにインストールされた状態で持ち込む +- npm および git Plugin は、OpenClaw が所有するパッケージルートにインストールされる -OpenClaw は Plugin ライフサイクルのみを所有します。 +OpenClaw が所有するのは Plugin ライフサイクルだけです。 - Plugin ソースを検出する - 明示的に要求されたときにパッケージをインストールまたは更新する @@ -50,7 +50,7 @@ npm インストールは、npm ルートで次を実行します。 npm install --prefix ~/.openclaw/npm --omit=dev --ignore-scripts --no-audit --no-fund ``` -npm は推移的依存関係を、Plugin パッケージの横にある `~/.openclaw/npm/node_modules` へ巻き上げることがあります。OpenClaw はインストールを信頼する前に管理対象の npm ルートをスキャンし、アンインストール時には npm を使って npm 管理のパッケージを削除するため、巻き上げられたランタイム依存関係は管理対象のクリーンアップ境界内に残ります。 +npm は推移的依存関係を Plugin パッケージの隣の `~/.openclaw/npm/node_modules` に hoist する場合があります。OpenClaw はインストールを信頼する前に管理対象の npm ルートをスキャンし、アンインストール時には npm を使って npm 管理のパッケージを削除するため、hoist されたランタイム依存関係は管理対象のクリーンアップ境界内に残ります。 git インストールはリポジトリを clone または更新してから、次を実行します。 @@ -58,19 +58,19 @@ git インストールはリポジトリを clone または更新してから、 npm install --omit=dev --ignore-scripts --no-audit --no-fund ``` -その後、インストール済み Plugin はそのパッケージディレクトリから読み込まれるため、パッケージローカルおよび親 `node_modules` の解決は通常の Node パッケージと同じように機能します。 +インストールされた Plugin はその後、そのパッケージディレクトリから読み込まれるため、package-local および親の `node_modules` 解決は通常の Node パッケージと同じように動作します。 ## ローカル Plugin -ローカル Plugin は、開発者が管理するディレクトリとして扱われます。OpenClaw はそれらに対して `npm install`、`pnpm install`、依存関係修復を実行しません。ローカル Plugin に依存関係がある場合は、その Plugin を読み込む前に、その Plugin 内で依存関係をインストールしてください。 +ローカル Plugin は開発者が管理するディレクトリとして扱われます。OpenClaw はそれらに対して `npm install`、`pnpm install`、依存関係の修復を実行しません。ローカル Plugin に依存関係がある場合は、読み込む前にその Plugin 内でインストールしてください。 -サードパーティの TypeScript ローカル Plugin は緊急用の Jiti パスを使用できます。パッケージ化された JavaScript Plugin とバンドル済み内部 Plugin は、Jiti ではなくネイティブの import/require を通じて読み込まれます。 +サードパーティの TypeScript ローカル Plugin は緊急用の Jiti パスを使用できます。パッケージ化された JavaScript Plugin とバンドルされた内部 Plugin は、Jiti ではなくネイティブの import/require を通じて読み込まれます。 ## 起動と再読み込み -Gateway の起動と設定の再読み込みでは、Plugin 依存関係をインストールしません。Plugin インストール記録を読み取り、エントリーポイントを計算し、それを読み込みます。 +Gateway の起動と設定の再読み込みでは、Plugin 依存関係は決してインストールされません。Plugin インストールレコードを読み取り、エントリーポイントを計算し、それを読み込みます。 -ランタイムで依存関係が不足している場合、Plugin の読み込みは失敗し、エラーは操作者に明示的な修正方法を示す必要があります。 +ランタイムで依存関係が不足している場合、Plugin の読み込みは失敗し、エラーは運用者に明示的な修正方法を示す必要があります。 ```bash openclaw plugins update @@ -78,26 +78,26 @@ openclaw plugins install openclaw doctor --fix ``` -`doctor --fix` は、OpenClaw が生成したレガシーな依存関係状態をクリーンアップし、ローカルのインストール記録に存在しない設定済みのダウンロード可能 Plugin をインストールできます。すでにインストール済みのローカル Plugin の依存関係は修復しません。 +`doctor --fix` は、OpenClaw が生成したレガシー依存関係状態をクリーンアップし、設定で参照されているもののローカルインストールレコードに存在しないダウンロード可能な Plugin を復旧できます。Doctor は、すでにインストール済みのローカル Plugin の依存関係を修復しません。 -## バンドル済み Plugin +## バンドル Plugin -軽量で core-critical なバンドル済み Plugin は OpenClaw の一部として出荷されます。これらは重いランタイム依存関係ツリーを持たないか、ClawHub/npm 上のダウンロード可能なパッケージへ移動する必要があります。 +軽量でコアに重要なバンドル Plugin は OpenClaw の一部として同梱されます。それらは重いランタイム依存関係ツリーを持たないか、ClawHub/npm 上のダウンロード可能なパッケージへ移す必要があります。 -core パッケージで出荷される、外部インストールされる、またはソース専用に残る Plugin の現在の生成済み一覧については、[Plugin インベントリ](/ja-JP/plugins/plugin-inventory) を参照してください。 +コアパッケージに同梱される Plugin、外部インストールされる Plugin、または source-only のままにする Plugin の現在の生成済み一覧については、[Plugin インベントリ](/ja-JP/plugins/plugin-inventory) を参照してください。 -バンドル済み Plugin のマニフェストは、依存関係のステージングを要求してはなりません。大規模または任意の Plugin 機能は通常の Plugin としてパッケージ化し、サードパーティ Plugin と同じ npm/git/ClawHub パスを通じてインストールする必要があります。 +バンドル Plugin の manifest は依存関係ステージングを要求してはなりません。大きな、または任意の Plugin 機能は通常の Plugin としてパッケージ化し、サードパーティ Plugin と同じ npm/git/ClawHub パスを通じてインストールする必要があります。 -ソース checkout では、OpenClaw はリポジトリを pnpm monorepo として扱います。`pnpm install` の後、バンドル済み Plugin は `extensions/` から読み込まれるため、パッケージローカルの workspace 依存関係が利用でき、編集内容が直接反映されます。ソース checkout 開発は pnpm のみ対応です。リポジトリルートで通常の `npm install` を実行することは、バンドル済み Plugin の依存関係を準備する方法としてサポートされていません。 +ソース checkout では、OpenClaw はリポジトリを pnpm monorepo として扱います。`pnpm install` 後、バンドル Plugin は `extensions/` から読み込まれるため、package-local な workspace 依存関係が利用可能になり、編集内容が直接反映されます。ソース checkout 開発は pnpm のみ対応です。リポジトリルートでの通常の `npm install` は、バンドル Plugin 依存関係を準備する方法としてサポートされていません。 -| インストール形態 | バンドル済み Plugin の場所 | 依存関係の所有者 | -| -------------------------------- | ----------------------------------- | -------------------------------------------------------------------- | -| `npm install -g openclaw` | パッケージ内のビルド済みランタイムツリー | OpenClaw パッケージと明示的な Plugin install/update/doctor フロー | -| Git checkout plus `pnpm install` | `extensions/` workspace パッケージ | 各 Plugin パッケージ自身の依存関係を含む pnpm workspace | -| `openclaw plugins install ...` | 管理対象の npm/git/ClawHub Plugin ルート | Plugin install/update フロー | +| インストール形態 | バンドル Plugin の場所 | 依存関係の所有者 | +| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- | +| `npm install -g openclaw` | パッケージ内のビルド済みランタイムツリー | OpenClaw パッケージと明示的な Plugin install/update/doctor フロー | +| Git checkout plus `pnpm install` | `extensions/` workspace パッケージ | 各 Plugin パッケージ自身の依存関係を含む pnpm workspace | +| `openclaw plugins install ...` | 管理対象の npm/git/ClawHub Plugin ルート | Plugin install/update フロー | ## レガシークリーンアップ -古い OpenClaw バージョンは、起動時または doctor 修復中にバンドル済み Plugin の依存関係ルートを生成していました。現在の doctor クリーンアップは、`--fix` が使用されたときに、古い `plugin-runtime-deps` ルート、削除済みの `plugin-runtime-deps` ターゲットを指すグローバル Node-prefix パッケージシンボリックリンク、`.openclaw-runtime-deps*` マニフェスト、生成済み Plugin `node_modules`、インストールステージディレクトリ、パッケージローカルの pnpm store などの古いディレクトリとシンボリックリンクを削除します。パッケージ化された postinstall も、レガシーターゲットルートを削除する前にそれらのグローバルシンボリックリンクを削除するため、アップグレード後に壊れた ESM パッケージインポートが残りません。 +古い OpenClaw バージョンは、起動時または doctor 修復中にバンドル Plugin の依存関係ルートを生成していました。現在の doctor クリーンアップは、`--fix` が使用されたときに、それらの古いディレクトリとシンボリックリンクを削除します。対象には、古い `plugin-runtime-deps` ルート、削除済みの `plugin-runtime-deps` ターゲットを指すグローバル Node-prefix パッケージのシンボリックリンク、`.openclaw-runtime-deps*` manifest、生成された Plugin `node_modules`、インストールステージディレクトリ、package-local な pnpm ストアが含まれます。パッケージ化された postinstall も、レガシーターゲットルートを pruning する前にそれらのグローバルシンボリックリンクを削除するため、アップグレード後に壊れた ESM パッケージ import が残りません。 これらのパスはレガシーな残骸にすぎません。新規インストールで作成されるべきではありません。 diff --git a/docs/ja-JP/plugins/manage-plugins.md b/docs/ja-JP/plugins/manage-plugins.md index 7156ef2c6..ac64ae404 100644 --- a/docs/ja-JP/plugins/manage-plugins.md +++ b/docs/ja-JP/plugins/manage-plugins.md @@ -1,23 +1,24 @@ --- read_when: - - Plugin のインストール、一覧表示、更新、アンインストールの簡単な例が必要な場合 - - ClawHub と npm Plugin 配布のどちらを選ぶかを決めたい + - すばやくプラグインのインストール、一覧表示、更新、またはアンインストールの例を確認したい場合 + - ClawHub と npm での Plugin 配布のどちらを選ぶかを決めたい場合 - Plugin パッケージを公開しています sidebarTitle: Manage plugins summary: OpenClaw Plugin のインストール、一覧表示、アンインストール、更新、公開の簡単な例 -title: Pluginを管理 +title: Plugin を管理する x-i18n: - generated_at: "2026-05-02T22:19:34Z" + generated_at: "2026-05-05T01:48:41Z" model: gpt-5.5 provider: openai - source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320 + source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c source_path: plugins/manage-plugins.md workflow: 16 --- -ほとんどの Plugin ワークフローは、検索、インストール、Gateway の再起動、検証、不要になった Plugin のアンインストールという数個のコマンドで構成されます。 +ほとんどの Plugin ワークフローは、数個のコマンドで済みます。検索、インストール、Gateway の再起動、 +検証、そしてその Plugin が不要になったらアンインストールです。 -## Plugin の一覧表示 +## Plugin を一覧表示する ```bash openclaw plugins list @@ -26,16 +27,18 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -スクリプトには `--json` を使用します。これには、レジストリ診断と、Plugin パッケージが `dependencies` または `optionalDependencies` を宣言している場合の各 Plugin の静的な `dependencyStatus` が含まれます。 +スクリプトには `--json` を使用してください。これにはレジストリ診断と、Plugin パッケージが `dependencies` または +`optionalDependencies` を宣言している場合の各 Plugin の静的な `dependencyStatus` が含まれます。 ```bash openclaw plugins list --json \ | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}' ``` -`plugins list` はコールドインベントリチェックです。OpenClaw が設定、マニフェスト、Plugin レジストリから検出できるものを表示しますが、すでに実行中の Gateway プロセスが Plugin ランタイムをインポートしたことを証明するものではありません。 +`plugins list` はコールドインベントリチェックです。OpenClaw が設定、マニフェスト、Plugin レジストリから +検出できるものを表示します。すでに実行中の Gateway プロセスが Plugin ランタイムをインポートしたことを証明するものではありません。 -## Plugin のインストール +## Plugin をインストールする ```bash # Search ClawHub for plugin packages. @@ -60,16 +63,17 @@ openclaw plugins install ./my-plugin openclaw plugins install --link ./my-plugin ``` -Plugin コードをインストールした後、チャンネルを提供する Gateway を再起動します。 +Plugin コードをインストールした後、チャンネルにサービスを提供する Gateway を再起動します。 ```bash openclaw gateway restart openclaw plugins inspect --runtime --json ``` -ツール、フック、サービス、Gateway メソッド、Plugin 所有の CLI コマンドなどのランタイムサーフェスを Plugin が登録した証明が必要な場合は、`inspect --runtime` を使用します。 +ツール、フック、サービス、Gateway メソッド、または Plugin が所有する CLI コマンドなどのランタイムサーフェスを +Plugin が登録したことを証明する必要がある場合は、`inspect --runtime` を使用してください。 -## Plugin の更新 +## Plugin を更新する ```bash openclaw plugins update @@ -77,18 +81,24 @@ openclaw plugins update openclaw plugins update --all ``` -Plugin が `@beta` などの npm dist-tag からインストールされていた場合、後続の `update ` 呼び出しは記録済みのそのタグを再利用します。明示的な npm spec を渡すと、今後の更新で追跡されるインストール先がその spec に切り替わります。 +Plugin が `@beta` などの npm dist-tag からインストールされた場合、以降の +`update ` 呼び出しでは、記録されたそのタグが再利用されます。明示的な npm spec を渡すと、 +今後の更新で追跡されるインストールがその spec に切り替わります。 ```bash openclaw plugins update @scope/openclaw-plugin@beta openclaw plugins update @scope/openclaw-plugin ``` -2 つ目のコマンドは、以前に正確なバージョンまたはタグに固定されていた Plugin を、レジストリのデフォルトリリースラインに戻します。 +2 つ目のコマンドは、以前に正確なバージョンまたはタグに固定されていた Plugin を、レジストリの既定のリリースラインに戻します。 -`openclaw update` がベータチャンネルで実行されると、デフォルトラインの npm と ClawHub の Plugin レコードは、対応する Plugin の `@beta` リリースを最初に試します。そのベータリリースが存在しない場合、OpenClaw は記録済みの default/latest spec にフォールバックします。正確なバージョンと、`@rc` や `@beta` などの明示的なタグは保持されます。 +`openclaw update` が beta チャンネルで実行される場合、既定ラインの npm および ClawHub +Plugin レコードは、対応する Plugin の `@beta` リリースを先に試します。その beta +リリースが存在しない場合、OpenClaw は記録済みの既定/latest spec にフォールバックします。 +npm Plugin の場合、beta パッケージは存在するもののインストール検証に失敗した場合にも OpenClaw はフォールバックします。 +正確なバージョン、および `@rc` や `@beta` などの明示的なタグは保持されます。 -## Plugin のアンインストール +## Plugin をアンインストールする ```bash openclaw plugins uninstall --dry-run @@ -97,15 +107,19 @@ openclaw plugins uninstall --keep-files openclaw gateway restart ``` -アンインストールでは、該当する場合に Plugin の設定エントリ、Plugin インデックスレコード、許可/拒否リストエントリ、リンクされたロードパスが削除されます。`--keep-files` を渡さない限り、管理対象のインストールディレクトリは削除されます。 +アンインストールでは、該当する場合、Plugin の設定エントリ、Plugin インデックスレコード、許可/拒否リスト +エントリ、リンクされたロードパスが削除されます。管理対象のインストールディレクトリは、 +`--keep-files` を渡さない限り削除されます。 -## Plugin の公開 +## Plugin を公開する -外部 Plugin は [ClawHub](https://clawhub.ai)、npmjs.com、またはその両方に公開できます。 +外部 Plugin は [ClawHub](https://clawhub.ai)、npmjs.com、または +その両方に公開できます。 -### ClawHub への公開 +### ClawHub に公開する -ClawHub は OpenClaw Plugin の主要な公開ディスカバリーサーフェスです。インストール前に、ユーザーへ検索可能なメタデータ、バージョン履歴、レジストリスキャン結果を提供します。 +ClawHub は、OpenClaw Plugin の主要な公開ディスカバリーサーフェスです。インストール前に、 +検索可能なメタデータ、バージョン履歴、レジストリスキャン結果をユーザーに提供します。 ```bash npm i -g clawhub @@ -122,11 +136,12 @@ openclaw plugins install clawhub: openclaw plugins install ``` -裸の形式でも、先に ClawHub がチェックされます。 +裸の形式でも、まず ClawHub を確認します。 -### npmjs.com への公開 +### npmjs.com に公開する -ネイティブ npm Plugin には、Plugin マニフェストと `package.json` の OpenClaw エントリポイントメタデータが含まれている必要があります。 +ネイティブ npm Plugin には、Plugin マニフェストと `package.json` の OpenClaw +エントリポイントメタデータを含める必要があります。 ```json package.json { @@ -143,7 +158,7 @@ openclaw plugins install npm publish --access public ``` -ユーザーは npm のみから次のようにインストールします。 +ユーザーは npm 専用で次のようにインストールします。 ```bash openclaw plugins install npm:@acme/openclaw-plugin @@ -151,19 +166,22 @@ openclaw plugins install npm:@acme/openclaw-plugin@beta openclaw plugins install npm:@acme/openclaw-plugin@1.0.0 ``` -同じパッケージが ClawHub でも利用可能な場合、`npm:` は ClawHub ルックアップをスキップし、npm 解決を強制します。 +同じパッケージが ClawHub でも利用可能な場合、`npm:` は ClawHub ルックアップをスキップし、 +npm 解決を強制します。 ## ソースの選択 -- **ClawHub**: OpenClaw ネイティブのディスカバリー、スキャン概要、バージョン、インストールのヒントが必要な場合に使用します。 -- **npmjs.com**: すでに JavaScript パッケージを配布している場合、または npm dist-tag/プライベートレジストリのワークフローが必要な場合に使用します。 +- **ClawHub**: OpenClaw ネイティブのディスカバリー、スキャン概要、 + バージョン、インストールヒントが必要な場合に使用します。 +- **npmjs.com**: すでに JavaScript パッケージを配布している場合、または npm + dist-tags/private registry ワークフローが必要な場合に使用します。 - **Git**: ブランチ、タグ、またはコミットから直接インストールしたい場合に使用します。 - **ローカルパス**: 同じマシン上で Plugin を開発またはテストしている場合に使用します。 -## 関連項目 +## 関連情報 - [Plugins](/ja-JP/tools/plugin) - 概要とトラブルシューティング -- [`openclaw plugins`](/ja-JP/cli/plugins) - CLI リファレンス全文 +- [`openclaw plugins`](/ja-JP/cli/plugins) - 完全な CLI リファレンス - [ClawHub](/ja-JP/tools/clawhub) - 公開とレジストリ操作 -- [Plugin の構築](/ja-JP/plugins/building-plugins) - Plugin パッケージの作成 +- [Plugin の構築](/ja-JP/plugins/building-plugins) - Plugin パッケージを作成する - [Plugin マニフェスト](/ja-JP/plugins/manifest) - マニフェストとパッケージメタデータ diff --git a/docs/ja-JP/providers/openrouter.md b/docs/ja-JP/providers/openrouter.md index ac76c0210..6b859ca22 100644 --- a/docs/ja-JP/providers/openrouter.md +++ b/docs/ja-JP/providers/openrouter.md @@ -1,21 +1,21 @@ --- read_when: - - 多くの LLM に 1 つの API キーを使いたい場合 - - OpenClaw で OpenRouter 経由でモデルを実行したい - - 画像生成にOpenRouterを使用したい + - 多くのLLMに対して単一のAPIキーを使いたい + - OpenClaw で OpenRouter 経由でモデルを実行したい場合 + - 画像生成にOpenRouterを使用したい場合 - 動画生成に OpenRouter を使用したい場合 -summary: OpenRouter の統合 API を使用して、OpenClaw で多くのモデルにアクセスする +summary: OpenRouter の統合 API を使用して OpenClaw で多数のモデルにアクセスする title: OpenRouter x-i18n: - generated_at: "2026-05-04T05:02:17Z" + generated_at: "2026-05-05T01:48:45Z" model: gpt-5.5 provider: openai - source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc + source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244 source_path: providers/openrouter.md workflow: 16 --- -OpenRouter は、単一のエンドポイントと API キーの背後で多数のモデルへリクエストをルーティングする **統合 API** を提供します。OpenAI 互換なので、ほとんどの OpenAI SDK はベース URL を切り替えるだけで動作します。 +OpenRouter は、単一のエンドポイントと API キーの背後で多数のモデルへリクエストをルーティングする **統合 API** を提供します。OpenAI 互換のため、ほとんどの OpenAI SDK はベース URL を切り替えることで動作します。 ## はじめに @@ -28,8 +28,8 @@ OpenRouter は、単一のエンドポイントと API キーの背後で多数 openclaw onboard --auth-choice openrouter-api-key ``` - - オンボーディングではデフォルトで `openrouter/auto` が使われます。後で具体的なモデルを選択します。 + + オンボーディングのデフォルトは `openrouter/auto` です。後で具体的なモデルを選択します。 ```bash openclaw models set openrouter// @@ -61,7 +61,7 @@ OpenRouter は、単一のエンドポイントと API キーの背後で多数 | モデル参照 | 注記 | | --------------------------------- | ---------------------------- | -| `openrouter/auto` | OpenRouter 自動ルーティング | +| `openrouter/auto` | OpenRouter の自動ルーティング | | `openrouter/moonshotai/kimi-k2.6` | MoonshotAI 経由の Kimi K2.6 | ## 画像生成 @@ -82,11 +82,11 @@ OpenRouter は `image_generate` ツールのバックエンドとしても使用 } ``` -OpenClaw は `modalities: ["image", "text"]` を指定して、OpenRouter のチャット補完画像 API に画像リクエストを送信します。Gemini 画像モデルは、OpenRouter の `image_config` を通じて、対応している `aspectRatio` と `resolution` のヒントを受け取ります。低速な OpenRouter 画像モデルには `agents.defaults.imageGenerationModel.timeoutMs` を使用してください。`image_generate` ツールの呼び出しごとの `timeoutMs` パラメーターは引き続き優先されます。 +OpenClaw は `modalities: ["image", "text"]` を指定して、画像リクエストを OpenRouter の chat completions image API に送信します。Gemini 画像モデルは、サポートされる `aspectRatio` と `resolution` のヒントを OpenRouter の `image_config` 経由で受け取ります。遅い OpenRouter 画像モデルには `agents.defaults.imageGenerationModel.timeoutMs` を使用します。ただし、`image_generate` ツールの呼び出しごとの `timeoutMs` パラメーターが引き続き優先されます。 ## 動画生成 -OpenRouter は、非同期 `/videos` API を通じて `video_generate` ツールのバックエンドとしても使用できます。`agents.defaults.videoGenerationModel` の下で OpenRouter 動画モデルを使用します。 +OpenRouter は非同期 `/videos` API を通じて `video_generate` ツールのバックエンドとしても使用できます。`agents.defaults.videoGenerationModel` の下で OpenRouter 動画モデルを使用します。 ```json5 { @@ -101,7 +101,7 @@ OpenRouter は、非同期 `/videos` API を通じて `video_generate` ツール } ``` -OpenClaw はテキストから動画および画像から動画のジョブを OpenRouter に送信し、返された `polling_url` をポーリングして、OpenRouter の `unsigned_urls` またはドキュメント化されたジョブコンテンツエンドポイントから完成した動画をダウンロードします。参照画像はデフォルトで先頭/末尾フレーム画像として送信されます。`reference_image` でタグ付けされた画像は、OpenRouter 入力参照として送信されます。同梱の `google/veo-3.1-fast` デフォルトは、現在対応している 4/6/8 秒の長さ、`720P`/`1080P` 解像度、`16:9`/`9:16` アスペクト比を提示します。上流の動画生成 API は現在テキストと画像参照を受け付けるため、動画から動画は OpenRouter には登録されていません。 +OpenClaw はテキストから動画、および画像から動画のジョブを OpenRouter に送信し、返された `polling_url` をポーリングして、完了した動画を OpenRouter の `unsigned_urls` またはドキュメント化されたジョブコンテンツエンドポイントからダウンロードします。参照画像はデフォルトで先頭/末尾フレーム画像として送信されます。`reference_image` タグ付きの画像は OpenRouter の入力参照として送信されます。同梱のデフォルト `google/veo-3.1-fast` は、現在サポートされている 4/6/8 秒の長さ、`720P`/`1080P` 解像度、`16:9`/`9:16` アスペクト比を通知します。アップストリームの動画生成 API は現在、テキストと画像参照を受け付けるため、動画から動画は OpenRouter には登録されていません。 ## テキスト読み上げ @@ -125,13 +125,13 @@ OpenRouter は、OpenAI 互換の `/audio/speech` エンドポイントを通じ } ``` -`messages.tts.providers.openrouter.apiKey` が省略された場合、TTS は `models.providers.openrouter.apiKey`、次に `OPENROUTER_API_KEY` を再利用します。 +`messages.tts.providers.openrouter.apiKey` が省略された場合、TTS は `models.providers.openrouter.apiKey` を再利用し、その後 `OPENROUTER_API_KEY` を使用します。 ## 認証とヘッダー -OpenRouter は内部的に、API キーを使った Bearer トークンを使用します。 +OpenRouter は内部的に、API キーを使用した Bearer トークンを使用します。 -実際の OpenRouter リクエスト (`https://openrouter.ai/api/v1`) では、OpenClaw は OpenRouter のドキュメント化されたアプリ帰属ヘッダーも追加します。 +実際の OpenRouter リクエスト（`https://openrouter.ai/api/v1`）では、OpenClaw は OpenRouter のドキュメント化されたアプリ帰属ヘッダーも追加します。 | ヘッダー | 値 | | ------------------------- | ------------------------------------------------------------------------------------------------------ | @@ -140,14 +140,14 @@ OpenRouter は内部的に、API キーを使った Bearer トークンを使用 | `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` | -OpenRouter プロバイダーを別のプロキシまたはベース URL に向け直した場合、OpenClaw はこれらの OpenRouter 固有ヘッダーや Anthropic キャッシュマーカーを注入しません。 +OpenRouter プロバイダーを別のプロキシまたはベース URL に向け直した場合、OpenClaw はそれらの OpenRouter 固有ヘッダーや Anthropic キャッシュマーカーを注入**しません**。 ## 高度な設定 - OpenRouter のレスポンスキャッシュはオプトインです。モデルパラメーターで OpenRouter モデルごとに有効化します。 + OpenRouter のレスポンスキャッシュはオプトインです。OpenRouter モデルごとにモデルパラメーターで有効にします。 ```json5 { @@ -166,34 +166,34 @@ OpenRouter プロバイダーを別のプロキシまたはベース URL に向 } ``` - OpenClaw は `X-OpenRouter-Cache: true` を送信し、設定されている場合は `X-OpenRouter-Cache-TTL` も送信します。`responseCacheClear: true` は現在のリクエストを強制的に更新し、置き換え後のレスポンスを保存します。Snake_case エイリアス (`response_cache`、`response_cache_ttl_seconds`、`response_cache_clear`) も受け付けます。 + OpenClaw は `X-OpenRouter-Cache: true` を送信し、設定されている場合は `X-OpenRouter-Cache-TTL` も送信します。`responseCacheClear: true` は現在のリクエストの更新を強制し、置換後のレスポンスを保存します。Snake_case エイリアス（`response_cache`、`response_cache_ttl_seconds`、`response_cache_clear`）も受け付けます。 - これは、プロバイダーのプロンプトキャッシュや OpenRouter の Anthropic `cache_control` マーカーとは別です。カスタムプロキシのベース URL ではなく、検証済みの `openrouter.ai` ルートでのみ適用されます。 + これは、プロバイダーのプロンプトキャッシュおよび OpenRouter の Anthropic `cache_control` マーカーとは別です。カスタムプロキシのベース URL ではなく、検証済みの `openrouter.ai` ルートにのみ適用されます。 - 検証済みの OpenRouter ルートでは、Anthropic モデル参照は、システム/開発者プロンプトブロックでのプロンプトキャッシュ再利用を向上させるために OpenClaw が使用する OpenRouter 固有の Anthropic `cache_control` マーカーを保持します。 + 検証済みの OpenRouter ルートでは、Anthropic モデル参照は、システム/開発者プロンプトブロックでプロンプトキャッシュをよりよく再利用するために OpenClaw が使用する OpenRouter 固有の Anthropic `cache_control` マーカーを保持します。 - 検証済みの OpenRouter ルートでは、reasoning が有効な Anthropic モデル参照は、リクエストが OpenRouter に到達する前に末尾のアシスタントプリフィルターンを削除します。これは、reasoning 会話はユーザーターンで終わる必要があるという Anthropic の要件に合わせるためです。 + 検証済みの OpenRouter ルートでは、reasoning が有効な Anthropic モデル参照は、リクエストが OpenRouter に到達する前に末尾の assistant プリフィルターンを削除します。これは、reasoning 会話が user ターンで終わる必要があるという Anthropic の要件に合わせるためです。 - 対応している非 `auto` ルートでは、OpenClaw は選択された thinking レベルを OpenRouter プロキシ reasoning ペイロードにマッピングします。対応していないモデルヒントと `openrouter/auto` では、その reasoning 注入をスキップします。Hunter Alpha でも、古くなった設定済みモデル参照についてはプロキシ reasoning をスキップします。その廃止済みルートでは、OpenRouter が reasoning フィールドに最終回答テキストを返す可能性があるためです。 + サポートされている非 `auto` ルートでは、OpenClaw は選択された thinking レベルを OpenRouter プロキシ reasoning ペイロードにマッピングします。サポートされていないモデルヒントと `openrouter/auto` はその reasoning 注入をスキップします。Hunter Alpha も、古い設定済みモデル参照ではプロキシ reasoning をスキップします。OpenRouter がその廃止済みルートの reasoning フィールドで最終回答テキストを返す可能性があるためです。 - - 検証済みの OpenRouter ルートでは、`openrouter/deepseek/deepseek-v4-flash` と `openrouter/deepseek/deepseek-v4-pro` は、再生されたアシスタントターンで欠落している `reasoning_content` を補完し、thinking/ツール会話が DeepSeek V4 に必要な後続形状を維持できるようにします。 + + 検証済みの OpenRouter ルートでは、`openrouter/deepseek/deepseek-v4-flash` と `openrouter/deepseek/deepseek-v4-pro` は、リプレイされた assistant ターンで不足している `reasoning_content` を補完し、thinking/tool 会話が DeepSeek V4 の必須の後続形状を維持できるようにします。OpenClaw はこれらのルートに対して OpenRouter がサポートする `reasoning_effort` 値を送信します。`xhigh` は通知されている最高レベルであり、古い `max` オーバーライドは `xhigh` にマッピングされます。 - + OpenRouter は引き続きプロキシ形式の OpenAI 互換パスを通るため、`serviceTier`、Responses `store`、OpenAI reasoning 互換ペイロード、プロンプトキャッシュヒントなどのネイティブ OpenAI 専用リクエスト整形は転送されません。 - Gemini バックエンドの OpenRouter 参照は、プロキシ Gemini パスに留まります。OpenClaw はそこで Gemini thought-signature サニタイズを維持しますが、ネイティブ Gemini 再生検証やブートストラップ書き換えは有効にしません。 + Gemini バックエンドの OpenRouter 参照はプロキシ Gemini パスにとどまります。OpenClaw はそこで Gemini thought-signature サニタイズを維持しますが、ネイティブ Gemini リプレイ検証やブートストラップ書き換えは有効にしません。 diff --git a/docs/ja-JP/reference/RELEASING.md b/docs/ja-JP/reference/RELEASING.md index d8ecee818..67e48c724 100644 --- a/docs/ja-JP/reference/RELEASING.md +++ b/docs/ja-JP/reference/RELEASING.md @@ -1,24 +1,24 @@ --- read_when: - - 公開リリースチャネルの定義を探しています + - 公開リリースチャネル定義を探しています - リリース検証またはパッケージ受け入れの実行 - - バージョン命名とリリース周期を確認する -summary: リリースレーン、オペレーターチェックリスト、検証ボックス、バージョン命名、リリース周期 + - バージョンの命名規則とリリース周期を確認しています +summary: リリースレーン、オペレーター用チェックリスト、検証ボックス、バージョン命名、ケイデンス title: リリースポリシー x-i18n: - generated_at: "2026-05-04T07:04:11Z" + generated_at: "2026-05-05T01:48:50Z" model: gpt-5.5 provider: openai - source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6 + source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3 source_path: reference/RELEASING.md workflow: 16 --- OpenClaw には 3 つの公開リリースレーンがあります。 -- stable: デフォルトでは npm `beta` に公開され、明示的に要求された場合は npm `latest` に公開されるタグ付きリリース -- beta: npm `beta` に公開されるプレリリースタグ -- dev: `main` の移動する先頭 +- 安定版: 明示的に要求された場合は npm `latest` に、それ以外はデフォルトで npm `beta` に公開されるタグ付きリリース +- ベータ: npm `beta` に公開されるプレリリースタグ +- 開発版: `main` の移動する先頭 ## バージョン命名 @@ -26,152 +26,135 @@ OpenClaw には 3 つの公開リリースレーンがあります。 - Git タグ: `vYYYY.M.D` - 安定版修正リリースバージョン: `YYYY.M.D-N` - Git タグ: `vYYYY.M.D-N` -- Beta プレリリースバージョン: `YYYY.M.D-beta.N` +- ベータプレリリースバージョン: `YYYY.M.D-beta.N` - Git タグ: `vYYYY.M.D-beta.N` - 月または日をゼロ埋めしない -- `latest` は現在昇格済みの安定版 npm リリースを意味する -- `beta` は現在の beta インストール対象を意味する -- 安定版と安定版修正リリースは、デフォルトでは npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みの beta ビルドを後で昇格することもできる -- すべての安定版 OpenClaw リリースは npm パッケージと macOS アプリを一緒に出荷する。 - beta リリースは通常、まず npm/パッケージ経路を検証して公開し、 - mac アプリのビルド/署名/公証は明示的に要求されない限り安定版用に予約される +- `latest` は現在プロモートされている安定版 npm リリースを意味する +- `beta` は現在のベータインストール対象を意味する +- 安定版および安定版修正リリースはデフォルトで npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みのベータビルドを後でプロモートすることもできる +- すべての安定版 OpenClaw リリースでは、npm パッケージと macOS アプリを同時に出荷する。 + ベータリリースでは通常、まず npm/パッケージ経路を検証して公開し、 + mac アプリのビルド/署名/公証は、明示的に要求されない限り安定版用に取っておく -## リリース周期 +## リリース頻度 -- リリースは beta 優先で進める -- 安定版は最新の beta が検証された後にのみ続く +- リリースはベータ優先で進める +- 安定版は最新ベータが検証された後にのみ続く - メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを切る。 - これにより、リリース検証と修正が `main` 上の新規開発をブロックしない -- beta タグが push または公開された後に修正が必要になった場合、メンテナーは古い beta タグを削除または再作成するのではなく、 + これにより、リリース検証と修正が `main` 上の新規開発を妨げない +- ベータタグがプッシュまたは公開済みで修正が必要な場合、メンテナーは古いベータタグを削除または再作成するのではなく、 次の `-beta.N` タグを切る - 詳細なリリース手順、承認、認証情報、復旧メモは メンテナー専用 ## リリース担当者チェックリスト -このチェックリストはリリースフローの公開上の形です。非公開の認証情報、 +このチェックリストは、リリースフローの公開部分を示します。非公開の認証情報、 署名、公証、dist-tag 復旧、緊急ロールバックの詳細は -メンテナー専用のリリース runbook に残します。 +メンテナー専用のリリースランブックに残します。 -1. 現在の `main` から開始する: 最新を pull し、対象コミットが push 済みであることを確認し、 - 現在の `main` CI がブランチ作成元として十分に green であることを確認する。 -2. 実際のコミット履歴から `/changelog` で `CHANGELOG.md` の最上位セクションを書き直し、 - エントリをユーザー向けに保ち、commit して push し、ブランチ作成前にもう一度 rebase/pull する。 +1. 現在の `main` から開始する: 最新を pull し、対象コミットがプッシュ済みであることを確認し、 + 現在の `main` CI がブランチ元として十分に緑であることを確認する。 +2. 実際のコミット履歴から `/changelog` で最上部の `CHANGELOG.md` セクションを書き直し、 + エントリをユーザー向けに保ち、コミットしてプッシュし、ブランチ作成前にもう一度 rebase/pull する。 3. `src/plugins/compat/registry.ts` と - `src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性レコードをレビューする。期限切れの - 互換性は、アップグレード経路が引き続きカバーされる場合のみ削除する。そうでない場合は、 - 意図的に保持する理由を記録する。 + `src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性記録を確認する。アップグレード経路が引き続きカバーされる場合にのみ期限切れの互換性を削除するか、 + 意図的に持ち越す理由を記録する。 4. 現在の `main` から `release/YYYY.M.D` を作成する。通常のリリース作業を - `main` 上で直接行わない。 -5. 予定タグに必要なすべてのバージョン箇所を更新し、 - `pnpm plugins:sync` を実行して公開可能な Plugin パッケージがリリース - バージョンと互換性メタデータを共有するようにする。その後、ローカルの決定的な事前確認を実行する: - `pnpm check:test-types`, `pnpm check:architecture`, - `pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, and + `main` で直接行わない。 +5. 意図したタグに必要なすべてのバージョン箇所を更新し、 + `pnpm plugins:sync` を実行して公開可能な Plugin パッケージがリリースバージョンと互換性メタデータを共有するようにし、その後ローカルの決定論的な事前確認を実行する: + `pnpm check:test-types`、`pnpm check:architecture`、 + `pnpm build && pnpm ui:build`、`pnpm plugins:sync:check`、および `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 の単一の手動エントリポイントです。 -8. 検証に失敗した場合は、リリースブランチ上で修正し、修正を証明する最小の失敗 - ファイル、レーン、ワークフロージョブ、パッケージプロファイル、プロバイダー、またはモデル allowlist を再実行する。 - 変更範囲によって以前の証拠が古くなる場合のみ、全体の umbrella を再実行する。 -9. beta の場合は `vYYYY.M.D-beta.N` をタグ付けし、その後、一致する - `release/YYYY.M.D` ブランチから `OpenClaw Release Publish` を実行する。これは `pnpm plugins:sync:check` を検証し、 - すべての公開可能な Plugin パッケージをまず npm に公開し、同じ - セットを ClawPack npm-pack tarball として次に ClawHub へ公開し、その後、一致する dist-tag で - 準備済みの OpenClaw npm 事前確認アーティファクトを昇格する。公開後、 - 公開済みの `openclaw@YYYY.M.D-beta.N` または - `openclaw@beta` パッケージに対して、公開後パッケージ - 受け入れを実行する。push または公開済みのプレリリースに修正が必要な場合は、 - 次の一致するプレリリース番号を切る。古い - プレリリースを削除または書き換えない。 -10. 安定版の場合は、検証済みの beta またはリリース候補に必要な - 検証証拠がある場合のみ続行する。安定版 npm 公開も - `OpenClaw Release Publish` を通し、`preflight_run_id` で - 成功済みの事前確認アーティファクトを再利用する。安定版 macOS リリース準備には、 - パッケージ化された `.zip`, `.dmg`, `.dSYM.zip` と、`main` 上で更新済みの `appcast.xml` も必要です。 -11. 公開後、npm 公開後 verifier、公開後チャンネル証拠が必要な場合の任意のスタンドアロン - published-npm Telegram E2E、必要に応じた dist-tag 昇格、 - 一致する完全な `CHANGELOG.md` セクションからの GitHub リリース/プレリリースノート、 - そしてリリース告知 - 手順を実行する。 +7. リリースブランチ、タグ、または完全なコミット SHA に対して `Full Release Validation` ですべてのプレリリーステストを開始する。これは 4 つの大きなリリーステストボックス、 + Vitest、Docker、QA Lab、Package のための単一の手動エントリポイントである。 +8. 検証が失敗した場合は、リリースブランチ上で修正し、修正を証明する最小の失敗ファイル、 + レーン、ワークフロージョブ、パッケージプロファイル、プロバイダー、またはモデル許可リストを再実行する。 + 変更範囲によって以前の証拠が古くなる場合にのみ、全体の包括実行を再実行する。 +9. ベータでは、`vYYYY.M.D-beta.N` をタグ付けし、その後一致する `release/YYYY.M.D` ブランチから + `OpenClaw Release Publish` を実行する。これは `pnpm plugins:sync:check` を検証し、 + まずすべての公開可能な Plugin パッケージを npm に公開し、次に同じセットを ClawPack npm-pack tarball として ClawHub に公開し、その後一致する dist-tag で準備済みの OpenClaw npm 事前確認アーティファクトをプロモートする。 + 公開後、公開された `openclaw@YYYY.M.D-beta.N` または + `openclaw@beta` パッケージに対して公開後パッケージ受け入れを実行する。プッシュ済みまたは公開済みのプレリリースに修正が必要な場合は、 + 次の一致するプレリリース番号を切る。古いプレリリースを削除または書き換えない。 +10. 安定版では、検証済みベータまたはリリース候補に必要な検証証拠が揃った後にのみ続行する。 + 安定版 npm 公開も `OpenClaw Release Publish` を通じて行い、 + `preflight_run_id` を介して成功済みの事前確認アーティファクトを再利用する。安定版 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` を実行して、より広範な import cycle とアーキテクチャ境界チェックが、より高速なローカルゲートの外でもグリーンになるようにする -- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行して、pack 検証ステップに必要な `dist/*` リリース成果物と Control UI バンドルが存在するようにする -- ルートのバージョン bump 後、タグ付け前に `pnpm plugins:sync` を実行する。これは publish 可能な Plugin パッケージのバージョン、OpenClaw peer/API 互換性メタデータ、build メタデータ、Plugin changelog スタブを core リリースバージョンに合わせて更新する。`pnpm plugins:sync:check` は変更を加えないリリースガードであり、このステップを忘れていると publish ワークフローは registry を変更する前に失敗する。 -- リリース承認前に手動の `Full Release Validation` ワークフローを実行して、すべてのリリース前テストボックスを単一のエントリポイントから起動する。これは branch、tag、または完全な commit SHA を受け取り、手動 `CI` を dispatch し、install smoke、package acceptance、Docker リリースパス suite、live/E2E、OpenWebUI、QA Lab parity、Matrix、Telegram lane 用に `OpenClaw Release Checks` を dispatch する。`release_profile=full` と `rerun_group=all` では、release checks からの `release-package-under-test` artifact に対して package Telegram E2E も実行する。同じ Telegram E2E で publish 済み npm パッケージも証明する必要がある場合は、publish 後に `npm_telegram_package_spec` を指定する。Package Acceptance が SHA から build された artifact ではなく出荷済み npm パッケージに対して package/update matrix を実行する必要がある場合は、publish 後に `package_acceptance_package_spec` を指定する。Telegram E2E を強制せずに、private evidence report で検証が publish 済み npm パッケージに一致することを証明する必要がある場合は、`evidence_package_spec` を指定する。例: +- リリースのプレフライト前に `pnpm check:test-types` を実行し、テストの TypeScript が高速なローカル `pnpm check` ゲートの外でもカバーされるようにする +- リリースのプレフライト前に `pnpm check:architecture` を実行し、より広範な import cycle とアーキテクチャ境界チェックが高速なローカルゲートの外でもグリーンになるようにする +- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行し、pack 検証ステップで期待される `dist/*` リリース成果物と Control UI バンドルが存在するようにする +- ルートのバージョンバンプ後、タグ付け前に `pnpm plugins:sync` を実行する。これにより、公開可能な plugin パッケージのバージョン、OpenClaw peer/API 互換性メタデータ、ビルドメタデータ、plugin changelog スタブが core リリースバージョンに一致するよう更新される。`pnpm plugins:sync:check` は変更を加えないリリースガードであり、このステップを忘れている場合、公開ワークフローは registry の変更前に失敗する。 +- リリース承認前に手動の `Full Release Validation` ワークフローを実行し、1つのエントリポイントからすべてのプレリリース test box を開始する。ブランチ、タグ、または完全なコミット SHA を受け取り、手動の `CI` をディスパッチし、install smoke、package acceptance、クロス OS package checks、QA Lab parity、Matrix、Telegram レーンのために `OpenClaw Release Checks` をディスパッチする。安定版/デフォルト実行では、網羅的な live/E2E と Docker リリースパス soak は `run_release_soak=true` の背後に保持され、`release_profile=full` では soak が強制的に有効になる。`release_profile=full` かつ `rerun_group=all` の場合、release checks の `release-package-under-test` 成果物に対して package Telegram E2E も実行する。同じ Telegram E2E で公開済み npm package も証明する必要がある場合は、公開後に `npm_telegram_package_spec` を指定する。Package Acceptance で SHA からビルドされた成果物の代わりに、出荷済み npm package に対して package/update matrix を実行する必要がある場合は、公開後に `package_acceptance_package_spec` を指定する。非公開 evidence report で、Telegram E2E を強制せずに検証が公開済み npm package と一致することを証明する必要がある場合は、`evidence_package_spec` を指定する。例: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- リリース作業を続けながら package candidate の side-channel 証明が必要な場合は、手動の `Package Acceptance` ワークフローを実行する。`openclaw@beta`、`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使う。現在の `workflow_ref` harness で信頼済みの `package_ref` branch/tag/SHA を pack するには `source=ref` を使う。必須 SHA-256 付きの HTTPS tarball には `source=url` を使う。別の GitHub Actions run が upload した tarball には `source=artifact` を使う。このワークフローは candidate を `package-under-test` に解決し、その tarball に対して Docker E2E release scheduler を再利用し、`telegram_mode=mock-openai` または `telegram_mode=live-frontier` で同じ tarball に対する Telegram QA も実行できる。選択された Docker lane に `published-upgrade-survivor` が含まれる場合、package artifact が candidate になり、`published_upgrade_survivor_baseline` が publish 済み baseline を選択する。 +- リリース作業を継続しながら package candidate のサイドチャネル証明が必要な場合は、手動の `Package Acceptance` ワークフローを実行する。`openclaw@beta`、`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使用する。現在の `workflow_ref` harness で信頼済みの `package_ref` ブランチ/タグ/SHA を pack するには `source=ref` を使用する。必須の SHA-256 を伴う HTTPS tarball には `source=url` を使用する。別の GitHub Actions 実行でアップロードされた tarball には `source=artifact` を使用する。ワークフローは candidate を `package-under-test` に解決し、その tarball に対して Docker E2E release scheduler を再利用し、`telegram_mode=mock-openai` または `telegram_mode=live-frontier` で同じ tarball に対して Telegram QA を実行できる。選択された Docker レーンに `published-upgrade-survivor` が含まれる場合、package artifact が candidate となり、`published_upgrade_survivor_baseline` が公開済み 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` - 一般的な profile: - - `smoke`: install/channel/agent、gateway network、config reload lane - - `package`: OpenWebUI や live ClawHub を含まない artifact-native package/update/plugin lane - - `product`: package profile に MCP channel、cron/subagent cleanup、OpenAI web search、OpenWebUI を加えたもの - - `full`: OpenWebUI 付きの Docker リリースパス chunk - - `custom`: focused rerun 用の正確な `docker_lanes` 選択 -- リリース candidate に対する通常の full CI coverage だけが必要な場合は、手動の `CI` ワークフローを直接実行する。手動 CI dispatch は changed scoping を bypass し、Linux Node shard、bundled-plugin shard、channel contract、Node 22 互換性、`check`、`check-additional`、build smoke、docs check、Python skills、Windows、macOS、Android、Control UI i18n lane を強制する。 + 一般的なプロファイル: + - `smoke`: install/channel/agent、Gateway network、config reload レーン + - `package`: OpenWebUI や live ClawHub を伴わない artifact-native package/update/plugin レーン + - `product`: package プロファイルに加え、MCP channels、cron/subagent cleanup、OpenAI web search、OpenWebUI + - `full`: OpenWebUI を伴う Docker release-path chunks + - `custom`: 集中的な再実行のための正確な `docker_lanes` 選択 +- リリース candidate に対して通常の完全な CI カバレッジだけが必要な場合は、手動の `CI` ワークフローを直接実行する。手動 CI ディスパッチは changed scoping をバイパスし、Linux Node shards、bundled-plugin shards、channel contracts、Node 22 compatibility、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android、Control UI i18n レーンを強制する。 例: `gh workflow run ci.yml --ref release/YYYY.M.D` -- リリース telemetry を検証するときは `pnpm qa:otel:smoke` を実行する。これは local OTLP/HTTP receiver 経由で QA-lab を実行し、Opik、Langfuse、その他の外部 collector を必要とせずに、export された trace span name、bounded attribute、content/identifier redaction を検証する。 -- タグ付きリリースのたびに `pnpm release:check` を実行する -- tag が存在した後、変更を伴う publish sequence には `OpenClaw Release Publish` を実行する。`release/YYYY.M.D` から dispatch し（main から到達可能な tag を publish する場合は `main`）、release tag と成功した OpenClaw npm `preflight_run_id` を渡し、意図的に focused repair を実行している場合を除き、default Plugin publish scope の `all-publishable` を維持する。このワークフローは Plugin npm publish、Plugin ClawHub publish、OpenClaw npm publish を直列化し、外部化された plugins より先に core パッケージが publish されないようにする。 -- Release checks は現在、別の手動ワークフローで実行される: +- リリース telemetry を検証する場合は `pnpm qa:otel:smoke` を実行する。これは local OTLP/HTTP receiver を通じて QA-lab を実行し、Opik、Langfuse、または別の外部 collector を必要とせずに、export された trace span names、bounded attributes、content/identifier redaction を検証する。 +- タグ付きリリースの前には毎回 `pnpm release:check` を実行する +- タグが存在した後、変更を伴う公開シーケンスのために `OpenClaw Release Publish` を実行する。`release/YYYY.M.D` からディスパッチするか、main から到達可能なタグを公開する場合は `main` からディスパッチし、リリースタグと成功した OpenClaw npm `preflight_run_id` を渡す。意図的に集中的な修復を実行しているのでない限り、デフォルトの plugin publish scope `all-publishable` を維持する。このワークフローは plugin npm publish、plugin ClawHub publish、OpenClaw npm publish を直列化し、外部化された plugins より前に core package が公開されないようにする。 +- リリースチェックは現在、別の手動ワークフローで実行される: `OpenClaw Release Checks` -- `OpenClaw Release Checks` は、リリース承認前に QA Lab mock parity lane に加えて、高速な live Matrix profile と Telegram QA lane も実行する。live lane は `qa-live-shared` environment を使い、Telegram は Convex CI credential lease も使う。full Matrix transport、media、E2EE inventory を並列で実行したい場合は、手動の `QA-Lab - All Lanes` ワークフローを `matrix_profile=all` と `matrix_shards=true` で実行する。 -- Cross-OS install と upgrade runtime validation は、再利用可能ワークフロー `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す public `OpenClaw Release Checks` と `Full Release Validation` の一部である -- この分割は意図的なもの: 実際の npm release path は短く、決定的で、artifact-focused に保ち、遅い live check は専用の lane に置くことで、publish を停滞またはブロックしないようにする -- secret を含む release check は、ワークフロー logic と secrets を制御された状態に保つため、`Full Release Validation` 経由または `main`/release workflow ref から dispatch する -- `OpenClaw Release Checks` は、resolved commit が OpenClaw branch または release tag から到達可能である限り、branch、tag、または完全な commit SHA を受け取る -- `OpenClaw NPM Release` の validation-only preflight は、push 済み tag を要求せず、現在の完全な 40 文字 workflow-branch commit SHA も受け取る -- その SHA path は validation-only であり、実際の publish に昇格できない -- SHA mode では、workflow は package metadata check のためだけに `v` を合成する。実際の publish には引き続き実際の release tag が必要である -- どちらのワークフローも実際の publish と promotion path は GitHub-hosted runner 上に保ち、変更を伴わない validation path ではより大きな Blacksmith Linux runner を使える -- そのワークフローは、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方の workflow secret を使って - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - を実行する -- npm release preflight は、別の release checks lane を待たなくなった -- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - （または対応する beta/correction tag）を実行する -- npm publish 後に - `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - （または対応する beta/correction version）を実行して、fresh temp prefix で publish 済み registry install path を検証する -- beta publish 後に `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` - を実行して、共有の lease 済み Telegram credential pool を使い、publish 済み npm パッケージに対して installed-package onboarding、Telegram setup、実際の Telegram E2E を検証する。ローカル maintainer の単発実行では Convex vars を省略し、3 つの `OPENCLAW_QA_TELEGRAM_*` env credentials を直接渡してもよい。 -- maintainer machine から full post-publish beta smoke を実行するには、`pnpm release:beta-smoke -- --beta betaN` を使う。この helper は Parallels npm update/fresh-target validation を実行し、`NPM Telegram Beta E2E` を dispatch し、正確な workflow run を poll し、artifact を download して Telegram report を出力する。 -- Maintainer は、GitHub Actions から手動の `NPM Telegram Beta E2E` ワークフロー経由で同じ post-publish check を実行できる。これは意図的に manual-only であり、すべての merge で実行されるわけではない。 -- Maintainer release automation は現在 preflight-then-promote を使う: - - 実際の npm publish には成功した npm `preflight_run_id` が必要 - - 実際の npm publish は、成功した preflight run と同じ `main` または `release/YYYY.M.D` branch から dispatch する必要がある - - stable npm release の default は `beta` - - stable npm publish は workflow input で明示的に `latest` を target にできる - - token-based npm dist-tag mutation は現在、security のため `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` にある。`npm dist-tag add` には引き続き `NPM_TOKEN` が必要であり、public repo は OIDC-only publish を維持するためである - - public `macOS Release` は validation-only である。tag が release branch 上にのみ存在し、workflow を `main` から dispatch する場合は、`public_release_branch=release/YYYY.M.D` を設定する - - 実際の private mac publish には、成功した private mac `preflight_run_id` と `validate_run_id` が必要 - - 実際の publish path は、準備済み artifact を再 build せずに promote する -- `YYYY.M.D-N` のような stable correction release では、post-publish verifier は `YYYY.M.D` から `YYYY.M.D-N` への同じ temp-prefix upgrade path も check し、release correction が古い global install を base stable payload のまま静かに残さないようにする -- npm release preflight は、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` payload の両方が含まれていない限り fail closed するため、空の browser dashboard を再び出荷しない -- Post-publish verification は、publish 済み Plugin entrypoint と package metadata が installed registry layout に存在することも check する。Plugin runtime payload が欠落したまま出荷される release は postpublish verifier に失敗し、`latest` に promote できない。 -- `pnpm test:install:smoke` は candidate update tarball に対して npm pack `unpackedSize` budget も強制するため、installer e2e は release publish path の前に偶発的な pack bloat を検出できる -- release 作業で CI planning、extension timing manifest、または extension test matrix に触れた場合は、承認前に `.github/workflows/plugin-prerelease.yml` から planner-owned の `plugin-prerelease-extension-shard` matrix output を regenerate して review し、release note が古い CI layout を説明しないようにする -- Stable macOS release readiness には updater surface も含まれる: - - GitHub release には最終的に package された `.zip`、`.dmg`、`.dSYM.zip` が含まれる必要がある - - publish 後、`main` 上の `appcast.xml` は新しい stable zip を指す必要がある - - package された app は、non-debug bundle id、空でない Sparkle feed URL、その release version の canonical Sparkle build floor 以上の `CFBundleVersion` を維持する必要がある +- `OpenClaw Release Checks` は、リリース承認前に QA Lab mock parity レーンに加え、高速な live Matrix プロファイルと Telegram QA レーンも実行する。live レーンは `qa-live-shared` 環境を使用し、Telegram は Convex CI credential leases も使用する。Matrix transport、media、E2EE inventory を並列で完全に確認したい場合は、`matrix_profile=all` と `matrix_shards=true` を指定して手動の `QA-Lab - All Lanes` ワークフローを実行する。 +- クロス OS install と upgrade runtime validation は、public `OpenClaw Release Checks` と `Full Release Validation` の一部であり、これらは reusable workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す +- この分割は意図的なもの。実際の npm リリースパスを短く、決定的で、artifact-focused に保ち、遅い live checks は独自レーンに置くことで、公開を停滞またはブロックしないようにする +- secret を含むリリースチェックは、`Full Release Validation` を通じて、または `main`/release workflow ref からディスパッチし、workflow logic と secrets が制御された状態を保つ +- `OpenClaw Release Checks` は、解決されたコミットが OpenClaw ブランチまたはリリースタグから到達可能である限り、ブランチ、タグ、または完全なコミット SHA を受け取る +- `OpenClaw NPM Release` の validation-only preflight も、push 済みタグを必要とせずに、現在の完全な 40 文字の workflow-branch commit SHA を受け取る +- その SHA パスは validation-only であり、実際の publish へ昇格できない +- SHA モードでは、workflow は package metadata check のためだけに `v` を合成する。実際の publish には引き続き実際の release tag が必要 +- 両方の workflow は実際の publish と promotion path を GitHub-hosted runners 上に保持し、変更を加えない validation path ではより大きな Blacksmith Linux runners を使用できる +- その workflow は、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方の workflow secrets を使用して `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` を実行する +- npm release preflight は、別の release checks lane を待機しなくなった +- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（または対応する beta/correction tag）を実行する +- npm publish 後に `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（または対応する beta/correction version）を実行し、新しい一時 prefix で公開済み registry install path を検証する +- beta publish 後に `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` を実行し、共有 leased Telegram credential pool を使用して、公開済み npm package に対する installed-package オンボーディング、Telegram setup、実際の Telegram E2E を検証する。ローカル maintainer の単発実行では Convex vars を省略し、3つの `OPENCLAW_QA_TELEGRAM_*` env credentials を直接渡してもよい。 +- maintainer machine から完全な post-publish beta smoke を実行するには、`pnpm release:beta-smoke -- --beta betaN` を使用する。この helper は Parallels npm update/fresh-target validation を実行し、`NPM Telegram Beta E2E` をディスパッチし、正確な workflow run を polling し、artifact をダウンロードし、Telegram report を出力する。 +- maintainer は、GitHub Actions から手動の `NPM Telegram Beta E2E` ワークフローを通じて同じ post-publish check を実行できる。これは意図的に manual-only であり、すべての merge では実行されない。 +- maintainer release automation は現在、preflight-then-promote を使用する: + - 実際の npm publish は成功した npm `preflight_run_id` を通過している必要がある + - 実際の npm publish は、成功した preflight run と同じ `main` または `release/YYYY.M.D` ブランチからディスパッチされる必要がある + - stable npm releases のデフォルトは `beta` + - stable npm publish は workflow input により明示的に `latest` を target にできる + - token-based npm dist-tag mutation は現在、セキュリティのため `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` に置かれている。`npm dist-tag add` は引き続き `NPM_TOKEN` を必要とする一方で、public repo は OIDC-only publish を維持するため + - public `macOS Release` は validation-only。タグが release branch 上にのみ存在するが workflow が `main` からディスパッチされる場合は、`public_release_branch=release/YYYY.M.D` を設定する + - 実際の private mac publish は、成功した private mac `preflight_run_id` と `validate_run_id` を通過している必要がある + - 実際の publish paths は、再ビルドせず prepared artifacts を promote する +- `YYYY.M.D-N` のような stable correction releases では、post-publish verifier は `YYYY.M.D` から `YYYY.M.D-N` への同じ temp-prefix upgrade path もチェックし、release corrections によって古い global installs が base stable payload のまま密かに残らないようにする +- npm release preflight は、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` payload の両方が含まれていない限り fail closed になる。これにより、空の browser dashboard を再び出荷しないようにする +- Post-publish verification は、公開済み plugin entrypoints と package metadata が installed registry layout に存在することもチェックする。plugin runtime payloads が欠けたリリースは postpublish verifier に失敗し、`latest` に promote できない。 +- `pnpm test:install:smoke` は candidate update tarball に対して npm pack `unpackedSize` budget も強制するため、installer e2e は release publish path の前に accidental pack bloat を検出する +- リリース作業が CI planning、extension timing manifests、または extension test matrices に触れた場合は、承認前に `.github/workflows/plugin-prerelease.yml` から planner-owned `plugin-prerelease-extension-shard` matrix outputs を再生成してレビューし、release notes が古い CI layout を説明しないようにする +- stable macOS release readiness には updater surfaces も含まれる: + - GitHub release には packaged `.zip`、`.dmg`、`.dSYM.zip` が最終的に含まれている必要がある + - publish 後、`main` 上の `appcast.xml` は新しい stable zip を指している必要がある + - packaged app は non-debug bundle id、空でない Sparkle feed URL、その release version に対する canonical Sparkle build floor 以上の `CFBundleVersion` を維持する必要がある -## リリーステストボックス +## Release test boxes -`Full Release Validation` は、operator がすべてのリリース前テストを単一のエントリポイントから起動する方法である。動きの速い branch 上で pinned commit proof が必要な場合は、すべての child workflow が target SHA に固定された temporary branch から実行されるように helper を使う: +`Full Release Validation` は、operators が1つのエントリポイントからすべてのプレリリーステストを開始する方法である。変化の速いブランチで pinned commit proof を得るには、すべての child workflow が target SHA に固定された temporary branch から実行されるように helper を使用する: ```bash pnpm ci:full-release --sha ``` -この helper は `release-ci/-...` を push し、その branch から `ref=` で `Full Release Validation` を dispatch し、すべての child workflow の `headSha` が target に一致することを検証した後、temporary branch を削除する。これにより、誤って新しい `main` child run を証明することを避けられる。 +helper は `release-ci/-...` を push し、その branch から `ref=` で `Full Release Validation` をディスパッチし、すべての child workflow の `headSha` が target と一致することを検証してから temporary branch を削除する。これにより、誤って新しい `main` の child run を証明してしまうことを避けられる。 release branch または tag validation では、信頼済みの `main` workflow ref から実行し、release branch または tag を `ref` として渡す: @@ -185,25 +168,21 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -ワークフローはターゲット ref を解決し、手動 `CI` を -`target_ref=` 付きでディスパッチし、`OpenClaw Release Checks` をディスパッチし、パッケージ向けチェック用の親 `release-package-under-test` アーティファクトを準備し、`release_profile=full` かつ `rerun_group=all` の場合、または `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` が成功と表示されている場合だけです。full/all モードでは、`npm_telegram` 子ワークフローも成功している必要があります。full/all 以外では、公開済みの `npm_telegram_package_spec` が指定されていない限りスキップされます。最終 verifier サマリーには各子実行の最遅ジョブテーブルが含まれるため、リリースマネージャーはログをダウンロードせずに現在のクリティカルパスを確認できます。 -完全なステージマトリクス、正確なワークフロージョブ名、stable プロファイルと full プロファイルの違い、アーティファクト、集中的な再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation)を参照してください。 -子ワークフローは、`Full Release -Validation` を実行する信頼済み ref、通常は `--ref main` からディスパッチされます。これはターゲット `ref` が古いリリースブランチやタグを指している場合も同じです。Full Release Validation 用の別個の workflow-ref 入力はありません。ワークフロー実行 ref を選ぶことで、信頼済みハーネスを選択します。 -移動する `main` 上で正確なコミット証跡を得るために `--ref main -f ref=` を使用しないでください。生のコミット SHA は workflow dispatch ref にできないため、固定された一時ブランチを作成するには `pnpm ci:full-release --sha ` を使用します。 +ワークフローはターゲット ref を解決し、`target_ref=` で手動 `CI` をディスパッチし、`OpenClaw Release Checks` をディスパッチし、パッケージ向けチェック用の親 `release-package-under-test` アーティファクトを準備し、`release_profile=full` で `rerun_group=all` の場合、または `npm_telegram_package_spec` が設定されている場合に、スタンドアロンのパッケージ Telegram E2E をディスパッチします。その後、`OpenClaw Release Checks` はインストールスモーク、クロス OS リリースチェック、soak が有効な場合の live/E2E Docker リリースパスカバレッジ、Telegram パッケージ QA を含む Package Acceptance、QA Lab パリティ、ライブ Matrix、ライブ Telegram へ展開します。フル実行が許容されるのは、`Full Release Validation` サマリーで `normal_ci` と `release_checks` が成功と表示されている場合だけです。full/all モードでは、`npm_telegram` 子も成功している必要があります。full/all 以外では、公開済みの `npm_telegram_package_spec` が提供されていない限りスキップされます。最終 verifier サマリーには各子実行の最遅ジョブ表が含まれるため、リリースマネージャーはログをダウンロードせずに現在のクリティカルパスを確認できます。 +完全なステージマトリクス、正確なワークフロージョブ名、stable プロファイルと full プロファイルの違い、アーティファクト、集中 rerun ハンドルについては、[フルリリース検証](/ja-JP/reference/full-release-validation) を参照してください。 +子ワークフローは、ターゲット `ref` が古いリリースブランチやタグを指している場合でも、`Full Release Validation` を実行する信頼済み ref、通常は `--ref main` からディスパッチされます。個別の Full Release Validation workflow-ref 入力はありません。ワークフロー実行 ref を選択することで、信頼済みハーネスを選択してください。移動する `main` 上の正確なコミット証明に `--ref main -f ref=` を使用しないでください。生のコミット SHA はワークフローディスパッチ ref にできないため、`pnpm ci:full-release --sha ` を使用してピン留めされた一時ブランチを作成してください。 -ライブ/プロバイダーの範囲を選択するには `release_profile` を使用します。 +live/provider の広さを選択するには `release_profile` を使用します。 -- `minimum`: 最速のリリースクリティカルな OpenAI/コアのライブおよび Docker パス -- `stable`: リリース承認向けに minimum に stable プロバイダー/バックエンドカバレッジを追加 -- `full`: stable に幅広い advisory プロバイダー/メディアカバレッジを追加 +- `minimum`: 最速のリリースクリティカルな OpenAI/core live と Docker パス +- `stable`: minimum にリリース承認用の stable provider/backend カバレッジを追加 +- `full`: stable に広範な advisory provider/media カバレッジを追加 -`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` を使用します。このレーンは最も遅いデフォルトモデルをベンチマークするのではなく、パッケージインストール、オンボーディング、Gateway 起動、ライブエージェント 1 ターンを証明するものだからです。より広範なライブプロバイダーマトリクスは、引き続きモデル固有カバレッジの場所です。 +リリースブロック対象のレーンが green で、昇格前に網羅的な live/E2E、Docker リリースパス、all-since-2026.4.23 upgrade-survivor sweep を実行したい場合は、`stable` とともに `run_release_soak=true` を使用します。`full` は `run_release_soak=true` を含意します。 -リリース段階に応じて、これらのバリアントを使用します。 +`OpenClaw Release Checks` は信頼済みワークフロー ref を使用してターゲット ref を一度だけ `release-package-under-test` として解決し、soak 実行時に cross-OS、Package Acceptance、release-path Docker チェックでそのアーティファクトを再利用します。これにより、すべてのパッケージ向け box が同じバイト列を使用し、パッケージビルドの反復を避けられます。cross-OS OpenAI インストールスモークは、repo/org 変数が設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` を使用し、それ以外の場合は `openai/gpt-5.4` を使用します。このレーンは最も遅いデフォルトモデルのベンチマークではなく、パッケージインストール、オンボーディング、Gateway 起動、1 回のライブ agent turn を証明するためです。より広範な live provider マトリクスは、モデル固有カバレッジの場所のままです。 + +リリースステージに応じて、これらのバリアントを使用します。 ```bash # Validate an unpublished release candidate branch. @@ -233,23 +212,22 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -集中的な修正後の最初の再実行として、完全な包括ワークフローを使用しないでください。1 つのボックスが失敗した場合は、次の証跡として、失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデルプロバイダー、または QA レーンを使用します。完全な包括ワークフローを再度実行するのは、その修正が共有リリースオーケストレーションを変更した場合、または以前の全ボックス証跡を古くした場合だけです。包括ワークフローの最終 verifier は記録された子ワークフロー実行 ID を再チェックするため、子ワークフローの再実行が成功した後は、失敗した親ジョブ `Verify full validation` だけを再実行します。 +focused fix 後の最初の rerun として full umbrella を使用しないでください。1 つの box が失敗した場合は、次の証明に、失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデルプロバイダー、または QA レーンを使用します。full umbrella を再度実行するのは、修正が共有リリースオーケストレーションを変更した場合、または以前の全 box エビデンスが古くなった場合だけです。umbrella の最終 verifier は記録された子ワークフロー実行 ID を再チェックするため、子ワークフローが正常に rerun された後は、失敗した親ジョブ `Verify full validation` だけを rerun します。 -範囲を限定した復旧には、包括ワークフローに `rerun_group` を渡します。`all` は実際のリリース候補実行、`ci` は通常の CI 子ワークフローのみ、`plugin-prerelease` はリリース専用 Plugin 子ワークフローのみ、`release-checks` はすべてのリリースボックスを実行し、より狭いリリースグループは `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` です。 -集中的な `npm-telegram` 再実行には `npm_telegram_package_spec` が必要です。`release_profile=full` の full/all 実行では、release-checks パッケージアーティファクトを使用します。 +範囲を限定したリカバリーでは、umbrella に `rerun_group` を渡します。`all` は実際のリリース候補実行、`ci` は通常の CI 子のみを実行、`plugin-prerelease` はリリース専用 plugin 子のみを実行、`release-checks` はすべてのリリース box を実行し、より狭いリリースグループは `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` です。focused `npm-telegram` rerun には `npm_telegram_package_spec` が必要です。`release_profile=full` の full/all 実行では release-checks パッケージアーティファクトを使用します。focused cross-OS rerun では、`cross_os_suite_filter=windows/packaged-upgrade` または別の OS/suite filter を追加できます。QA release-check の失敗は advisory です。QA のみの失敗はリリース検証をブロックしません。 ### Vitest -Vitest ボックスは手動 `CI` 子ワークフローです。手動 CI は意図的に変更スコープをバイパスし、リリース候補に対して通常のテストグラフを強制します。対象は、Linux Node シャード、バンドル Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、docs チェック、Python Skills、Windows、macOS、Android、Control UI i18n です。 +Vitest box は手動 `CI` 子ワークフローです。手動 CI は意図的に changed scoping をバイパスし、リリース候補に対して通常のテストグラフを強制します。Linux Node shards、bundled-plugin shards、channel contracts、Node 22 compatibility、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android、Control UI i18n です。 -このボックスは「ソースツリーは通常のフルテストスイートを通過したか」に答えるために使用します。リリースパスのプロダクト検証とは同じではありません。保持する証跡: +この box は「ソースツリーは通常のフルテストスイートに合格したか」に答えるために使用します。これは release-path product validation と同じではありません。保持すべきエビデンス: - ディスパッチされた `CI` 実行 URL を示す `Full Release Validation` サマリー -- 正確なターゲット SHA で緑の `CI` 実行 -- リグレッションを調査する際の CI ジョブからの失敗または低速シャード名 +- 正確なターゲット SHA で green になった `CI` 実行 +- 回帰調査時の CI ジョブからの失敗または遅い shard 名 - 実行にパフォーマンス分析が必要な場合の `.artifacts/vitest-shard-timings.json` などの Vitest タイミングアーティファクト -リリースで決定的な通常 CI は必要だが、Docker、QA Lab、ライブ、クロス OS、パッケージボックスが不要な場合のみ、手動 CI を直接実行します。 +リリースに deterministic normal CI が必要で、Docker、QA Lab、live、cross-OS、package box が不要な場合にのみ、手動 CI を直接実行します。 ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -257,14 +235,14 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker ボックスは、`openclaw-live-and-e2e-checks-reusable.yml` を通じて `OpenClaw Release Checks` 内にあり、さらにリリースモードの `install-smoke` ワークフローにもあります。これはソースレベルのテストだけではなく、パッケージ化された Docker 環境を通じてリリース候補を検証します。 +Docker box は、`openclaw-live-and-e2e-checks-reusable.yml` と release-mode `install-smoke` ワークフローを通じて、`OpenClaw Release Checks` 内にあります。ソースレベルのテストだけではなく、パッケージ化された Docker 環境を通じてリリース候補を検証します。 -リリース Docker カバレッジには以下が含まれます。 +リリース Docker カバレッジには次が含まれます。 -- 低速な Bun グローバルインストールスモークを有効にしたフルインストールスモーク -- ターゲット SHA ごとのルート Dockerfile スモークイメージ準備/再利用。QR、root/gateway、installer/Bun スモークジョブは個別の install-smoke シャードとして実行 -- リポジトリ E2E レーン -- リリースパス Docker チャンク: `core`、`package-update-openai`、 +- 遅い Bun global install smoke を有効にしたフルインストールスモーク +- ターゲット SHA による root Dockerfile smoke image の準備/再利用。QR、root/gateway、installer/Bun smoke ジョブは個別の install-smoke shards として実行 +- repository E2E レーン +- 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`、 @@ -272,49 +250,46 @@ Docker ボックスは、`openclaw-live-and-e2e-checks-reusable.yml` を通じ `plugins-runtime-install-e`、`plugins-runtime-install-f`、 `plugins-runtime-install-g`、`plugins-runtime-install-h` - 要求された場合の `plugins-runtime-services` チャンク内の OpenWebUI カバレッジ -- 分割されたバンドル Plugin インストール/アンインストールレーン +- split bundled plugin install/uninstall レーン `bundled-plugin-install-uninstall-0` から `bundled-plugin-install-uninstall-23` -- リリースチェックにライブスイートが含まれる場合のライブ/E2E プロバイダースイートと Docker ライブモデルカバレッジ +- release checks に live suites が含まれる場合の live/E2E provider suites と Docker live model カバレッジ -再実行の前に Docker アーティファクトを使用します。リリースパススケジューラーは、レーンログ、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。集中的な復旧には、すべてのリリースチャンクを再実行する代わりに、再利用可能な live/E2E ワークフローで `docker_lanes=` を使用します。生成された再実行コマンドには、利用可能な場合、以前の `package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、失敗したレーンは同じ tarball と GHCR イメージを再利用できます。 +rerun の前に Docker アーティファクトを使用してください。release-path スケジューラーは、レーンログ、`summary.json`、`failures.json`、フェーズタイミング、scheduler plan JSON、rerun コマンドを含む `.artifacts/docker-tests/` をアップロードします。focused recovery では、すべてのリリースチャンクを rerun する代わりに、reusable live/E2E workflow で `docker_lanes=` を使用します。生成された rerun コマンドには、利用可能な場合、以前の `package_artifact_run_id` と準備済み Docker image 入力が含まれるため、失敗したレーンは同じ tarball と GHCR images を再利用できます。 ### QA Lab -QA Lab ボックスも `OpenClaw Release Checks` の一部です。これは agentic な挙動とチャネルレベルのリリースゲートであり、Vitest や Docker パッケージ機構とは別です。 +QA Lab box も `OpenClaw Release Checks` の一部です。これは Vitest や Docker パッケージ機構とは別の、agentic behavior と channel-level のリリースゲートです。 -リリース QA Lab カバレッジには以下が含まれます。 +リリース QA Lab カバレッジには次が含まれます。 -- agentic parity pack を使用して OpenAI 候補レーンを Opus 4.6 ベースラインと比較する mock パリティレーン -- `qa-live-shared` 環境を使用する高速ライブ Matrix QA プロファイル -- Convex CI credential lease を使用するライブ Telegram QA レーン -- リリーステレメトリに明示的なローカル証跡が必要な場合の `pnpm qa:otel:smoke` +- agentic parity pack を使用して OpenAI candidate lane を Opus 4.6 baseline と比較する mock parity lane +- `qa-live-shared` environment を使用する fast live Matrix QA profile +- Convex CI credential leases を使用する live Telegram QA lane +- リリース telemetry に明示的な local proof が必要な場合の `pnpm qa:otel:smoke` -このボックスは「リリースは QA シナリオとライブチャネルフローで正しく動作するか」に答えるために使用します。リリースを承認する際は、パリティ、Matrix、Telegram レーンのアーティファクト URL を保持します。完全な Matrix カバレッジは、デフォルトのリリースクリティカルレーンではなく、手動のシャード化された QA-Lab 実行として引き続き利用できます。 +この box は「リリースは QA シナリオと live channel flows で正しく動作するか」に答えるために使用します。リリース承認時には、parity、Matrix、Telegram レーンのアーティファクト URL を保持してください。Full Matrix カバレッジは、デフォルトの release-critical lane ではなく、手動の sharded QA-Lab run として引き続き利用できます。 -### パッケージ +### Package -パッケージボックスは、インストール可能プロダクトのゲートです。これは `Package Acceptance` とリゾルバー `scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。リゾルバーは候補を Docker E2E が消費する `package-under-test` tarball に正規化し、パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、ワークフローハーネス ref をパッケージソース ref とは別に保ちます。 +Package box は installable-product gate です。これは `Package Acceptance` と resolver `scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。resolver は candidate を Docker E2E が消費する `package-under-test` tarball に正規化し、パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、ワークフローハーネス ref をパッケージソース ref から分離したままにします。 -サポートされる候補ソース: +サポートされる candidate sources: - `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な OpenClaw リリースバージョン -- `source=ref`: 選択された `workflow_ref` ハーネスで、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパック -- `source=url`: 必須の `package_sha256` 付きで HTTPS `.tgz` をダウンロード +- `source=ref`: 選択された `workflow_ref` ハーネスで、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA を pack +- `source=url`: 必須の `package_sha256` を伴う HTTPS `.tgz` をダウンロード - `source=artifact`: 別の GitHub Actions 実行によってアップロードされた `.tgz` を再利用 -`OpenClaw Release Checks` は、`source=artifact`、準備済みリリースパッケージアーティファクト、`suite_profile=custom`、 +`OpenClaw Release Checks` は、準備済みリリースパッケージアーティファクト、`suite_profile=custom`、 `docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、 -`published_upgrade_survivor_baselines=all-since-2026.4.23`、 -`published_upgrade_survivor_scenarios=reported-issues`、および -`telegram_mode=mock-openai` で Package Acceptance を実行します。Package Acceptance は、同じ解決済み tarball に対して、マイグレーション、更新、古い Plugin 依存関係のクリーンアップ、オフライン Plugin フィクスチャ、Plugin 更新、Telegram パッケージ QA を維持します。アップグレードマトリクスは、`2026.4.23` から `latest` までのすべての stable npm 公開済みベースラインをカバーします。すでに出荷済みの候補には `source=npm` で Package Acceptance を使用し、公開前の SHA 裏付けのあるローカル npm tarball には `source=ref`/`source=artifact` を使用します。これは、以前 Parallels を必要としていたパッケージ/更新カバレッジの大半に対する GitHub ネイティブな置き換えです。クロス OS リリースチェックは、OS 固有のオンボーディング、インストーラー、プラットフォーム挙動に引き続き重要ですが、パッケージ/更新のプロダクト検証では Package Acceptance を優先すべきです。 +`telegram_mode=mock-openai` とともに、`source=artifact` で Package Acceptance を実行します。Package Acceptance は、同じ解決済み tarball に対して migration、update、stale plugin dependency cleanup、offline plugin fixtures、plugin update、Telegram package QA を維持します。blocking release checks は、デフォルトの latest published package baseline を使用します。`run_release_soak=true` または `release_profile=full` は、`2026.4.23` から `latest` までのすべての stable npm-published baseline と reported-issue fixtures に拡張されます。すでに shipped candidate には `source=npm` の Package Acceptance を使用し、publish 前の SHA-backed local npm tarball には `source=ref`/`source=artifact` を使用します。これは、以前 Parallels が必要だった package/update カバレッジの大部分に対する GitHub-native replacement です。cross-OS release checks は OS-specific onboarding、installer、platform behavior のために引き続き重要ですが、package/update product validation は Package Acceptance を優先すべきです。 -更新と Plugin 検証の正規チェックリストは[更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins)です。Plugin のインストール/更新、doctor クリーンアップ、または公開パッケージマイグレーション変更を証明するローカル、Docker、Package Acceptance、またはリリースチェックレーンを決める際に使用します。 -すべての stable `2026.4.23+` パッケージからの網羅的な公開済み更新マイグレーションは、Full Release CI の一部ではなく、別個の手動 `Update Migration` ワークフローです。 +update と plugin validation の標準チェックリストは [update と plugins のテスト](/ja-JP/help/testing-updates-plugins) です。plugin install/update、doctor cleanup、published-package migration change を証明する local、Docker、Package Acceptance、release-check lane を判断するときに使用してください。すべての stable `2026.4.23+` package からの exhaustive published update migration は、Full Release CI の一部ではなく、別個の手動 `Update Migration` ワークフローです。 -レガシー package-acceptance の緩和は、意図的に期限付きです。`2026.4.25` までのパッケージは、すでに npm に公開されたメタデータギャップについて互換パスを使用できます。対象は、tarball にない private QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャ内の欠落したパッチファイル、永続化されていない `update.channel`、レガシー Plugin インストールレコードの場所、マーケットプレイスインストールレコード永続化の欠落、`plugins update` 中の設定メタデータマイグレーションです。公開済みの `2026.4.26` パッケージは、すでに出荷されたローカルビルドメタデータスタンプファイルについて警告する場合があります。それ以降のパッケージは、現代的なパッケージ契約を満たす必要があります。同じギャップはリリース検証で失敗します。 +legacy package-acceptance leniency は意図的に time boxed されています。`2026.4.25` までのパッケージは、npm にすでに公開済みの metadata gaps に対する compatibility path を使用できます。tarball にない private QA inventory entries、欠落した `gateway install --wrapper`、tarball-derived git fixture 内の欠落した patch files、永続化されない `update.channel`、legacy plugin install-record locations、欠落した marketplace install-record persistence、`plugins update` 中の config metadata migration です。公開済みの `2026.4.26` package は、すでに出荷済みの local build metadata stamp files に対して警告する場合があります。それ以降のパッケージは modern package contracts を満たす必要があります。同じ gaps は release validation で失敗します。 -リリース上の問いが実際のインストール可能パッケージに関するものである場合は、より広範な Package Acceptance プロファイルを使用します。 +リリースに関する問いが実際のインストール可能なパッケージに関するものである場合は、より広範な Package Acceptance プロファイルを使用します。 ```bash gh workflow run package-acceptance.yml \ @@ -328,33 +303,32 @@ gh workflow run package-acceptance.yml \ 一般的なパッケージプロファイル: -- `smoke`: パッケージのクイックインストール/チャネル/エージェント、Gateway ネットワーク、設定 - リロードのレーン -- `package`: ライブ ClawHub なしでのインストール/更新/Plugin パッケージ契約。これは release-check の +- `smoke`: すばやいパッケージのインストール/チャンネル/エージェント、gateway ネットワーク、config + reload レーン +- `package`: ライブ ClawHub を使わないインストール/更新/Plugin パッケージ契約。これは release-check の デフォルト -- `product`: `package` に加えて、MCP チャネル、cron/サブエージェントのクリーンアップ、OpenAI web +- `product`: `package` に加えて MCP チャンネル、cron/サブエージェントのクリーンアップ、OpenAI web search、OpenWebUI -- `full`: OpenWebUI を含む Docker リリースパスのチャンク -- `custom`: 集中的な再実行用の正確な `docker_lanes` リスト +- `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 も引き続き受け付けます。 +Telegram ワークフローは、公開後チェック用に公開済み npm spec を引き続き受け付けます。 -## リリース公開自動化 +## リリース公開の自動化 -`OpenClaw Release Publish` は通常の変更を伴う公開エントリポイントです。これは、 -リリースに必要な順序で trusted-publisher ワークフローをオーケストレーションします。 +`OpenClaw Release Publish` は、通常の変更を伴う公開エントリポイントです。これは、リリースに必要な順序で trusted-publisher ワークフローを調整します。 -1. リリースタグをチェックアウトし、そのコミット SHA を解決します。 -2. タグが `main` または `release/*` から到達可能であることを検証します。 +1. リリースタグをチェックアウトし、その commit SHA を解決します。 +2. そのタグが `main` または `release/*` から到達可能であることを検証します。 3. `pnpm plugins:sync:check` を実行します。 -4. `publish_scope=all-publishable` と `ref=` で `Plugin NPM Release` をディスパッチします。 -5. 同じスコープと SHA で `Plugin ClawHub Release` をディスパッチします。 -6. リリースタグ、npm dist-tag、保存済みの `preflight_run_id` で `OpenClaw NPM Release` をディスパッチします。 +4. `publish_scope=all-publishable` と `ref=` で `Plugin NPM Release` を dispatch します。 +5. 同じ scope と SHA で `Plugin ClawHub Release` を dispatch します。 +6. リリースタグ、npm dist-tag、保存済みの `preflight_run_id` で `OpenClaw NPM Release` を dispatch します。 -ベータ公開の例: +Beta 公開の例: ```bash gh workflow run openclaw-release-publish.yml \ @@ -364,7 +338,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -デフォルトの beta dist-tag への安定版公開: +デフォルトの beta dist-tag への Stable 公開: ```bash gh workflow run openclaw-release-publish.yml \ @@ -374,7 +348,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -`latest` へ直接行う安定版昇格は明示的です。 +`latest` への Stable promotion は明示的です: ```bash gh workflow run openclaw-release-publish.yml \ @@ -384,70 +358,65 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=latest ``` -下位レベルの `Plugin NPM Release` と `Plugin ClawHub Release` ワークフローは、 -集中的な修復または再公開作業にのみ使用します。選択した Plugin の修復では、 -`plugin_publish_scope=selected` と `plugins=@openclaw/name` を -`OpenClaw Release Publish` に渡すか、OpenClaw パッケージを公開してはいけない場合は -子ワークフローを直接ディスパッチします。 +低レベルの `Plugin NPM Release` と `Plugin ClawHub Release` ワークフローは、フォーカスした修復または再公開作業にのみ使用します。選択した Plugin の修復では、`OpenClaw Release Publish` に `plugin_publish_scope=selected` と `plugins=@openclaw/name` を渡すか、OpenClaw パッケージを公開してはならない場合は子ワークフローを直接 dispatch します。 ## NPM ワークフロー入力 -`OpenClaw NPM Release` は、オペレーターが制御する次の入力を受け付けます。 +`OpenClaw NPM Release` は、オペレーターが制御する次の入力を受け付けます: -- `tag`: `v2026.4.2`、`v2026.4.2-1`、または - `v2026.4.2-beta.1` のような必須のリリースタグ。`preflight_only=true` の場合は、 - 検証専用プリフライト用に現在の完全な 40 文字のワークフローブランチコミット SHA も使用できます +- `tag`: 必須のリリースタグ。例: `v2026.4.2`、`v2026.4.2-1`、または + `v2026.4.2-beta.1`。`preflight_only=true` の場合は、検証のみの preflight 用に、現在の + 40 文字の完全な workflow-branch commit SHA も使用できます - `preflight_only`: 検証/ビルド/パッケージのみの場合は `true`、実際の公開パスの場合は `false` -- `preflight_run_id`: 実際の公開パスで必須。ワークフローが成功したプリフライト実行から準備済み tarball を再利用するために使います +- `preflight_run_id`: 実際の公開パスで必須。ワークフローが成功した preflight 実行から準備済み tarball を再利用するために使用します - `npm_dist_tag`: 公開パスの npm ターゲットタグ。デフォルトは `beta` -`OpenClaw Release Publish` は、オペレーターが制御する次の入力を受け付けます。 +`OpenClaw Release Publish` は、オペレーターが制御する次の入力を受け付けます: - `tag`: 必須のリリースタグ。すでに存在している必要があります -- `preflight_run_id`: 成功した `OpenClaw NPM Release` プリフライト実行 id。 - `publish_openclaw_npm=true` の場合に必須です +- `preflight_run_id`: 成功した `OpenClaw NPM Release` preflight run id。 + `publish_openclaw_npm=true` の場合は必須 - `npm_dist_tag`: OpenClaw パッケージの npm ターゲットタグ -- `plugin_publish_scope`: デフォルトは `all-publishable`。集中的な修復作業にのみ `selected` を使用します +- `plugin_publish_scope`: デフォルトは `all-publishable`。フォーカスした修復作業にのみ `selected` を使用します - `plugins`: `plugin_publish_scope=selected` の場合の、カンマ区切りの `@openclaw/*` パッケージ名 -- `publish_openclaw_npm`: デフォルトは `true`。ワークフローを Plugin のみの修復オーケストレーターとして使用する場合にのみ `false` を設定します +- `publish_openclaw_npm`: デフォルトは `true`。ワークフローを Plugin のみの修復オーケストレーターとして使用する場合にのみ `false` に設定します -`OpenClaw Release Checks` は、オペレーターが制御する次の入力を受け付けます。 +`OpenClaw Release Checks` は、オペレーターが制御する次の入力を受け付けます: -- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを伴うチェックでは、 - 解決済みコミットが OpenClaw ブランチまたはリリースタグから到達可能である必要があります。 +- `ref`: 検証するブランチ、タグ、または完全な commit SHA。シークレットを含むチェックでは、解決されたコミットが OpenClaw ブランチまたはリリースタグから到達可能である必要があります。 +- `run_release_soak`: stable/default リリースチェックで、網羅的な live/E2E、Docker release-path、all-since upgrade-survivor soak を有効にします。`release_profile=full` により強制的に有効になります。 ルール: -- 安定版タグと修正タグは `beta` または `latest` のいずれかへ公開できます -- ベータプレリリースタグは `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` では、完全な commit SHA 入力は `preflight_only=true` の場合にのみ許可されます +- `OpenClaw Release Checks` と `Full Release Validation` は常に検証のみです +- 実際の公開パスでは、preflight 時に使用したものと同じ `npm_dist_tag` を使用する必要があります。ワークフローは公開前にそのメタデータを検証し続けます -## 安定版 npm リリース手順 +## Stable npm リリース手順 -安定版 npm リリースを切る場合: +Stable npm リリースを切る場合: 1. `preflight_only=true` で `OpenClaw NPM Release` を実行します - - タグが存在する前は、プリフライトワークフローの検証専用ドライランとして、現在の完全なワークフローブランチコミット SHA を使用できます -2. 通常の beta-first フローでは `npm_dist_tag=beta` を選択します。直接の安定版公開を意図している場合にのみ `latest` を選択します -3. 1 つの手動ワークフローから通常の CI に加えて、ライブプロンプトキャッシュ、Docker、QA Lab、Matrix、Telegram のカバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全なコミット SHA で `Full Release Validation` を実行します -4. 決定的な通常テストグラフだけが必要な場合は、代わりにリリース ref で手動の `CI` ワークフローを実行します + - タグが存在する前は、preflight ワークフローの検証のみのドライランに現在の完全な workflow-branch commit SHA を使用できます +2. 通常の beta-first フローでは `npm_dist_tag=beta` を選択し、直接 stable 公開を意図する場合にのみ `latest` を選択します +3. 1 つの手動ワークフローから通常の CI に加えて live prompt cache、Docker、QA Lab、Matrix、Telegram のカバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全な commit SHA に対して `Full Release Validation` を実行します +4. 決定的な通常のテストグラフだけが必要な場合は、代わりにリリース ref で手動 `CI` ワークフローを実行します 5. 成功した `preflight_run_id` を保存します -6. 同じ `tag`、同じ `npm_dist_tag`、保存済みの `preflight_run_id` で `OpenClaw Release Publish` を実行します。これは OpenClaw npm パッケージを昇格する前に、外部化された Plugin を npm と ClawHub に公開します -7. リリースが `beta` に着地した場合は、非公開の +6. 同じ `tag`、同じ `npm_dist_tag`、保存済みの `preflight_run_id` で `OpenClaw Release Publish` を実行します。これは OpenClaw npm パッケージを promotion する前に、外部化された Plugin を npm と ClawHub に公開します +7. リリースが `beta` に landing した場合は、private `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - ワークフローを使用して、その安定版を `beta` から `latest` へ昇格します -8. リリースを意図的に直接 `latest` へ公開し、`beta` もすぐに同じ安定版ビルドを指すべき場合は、同じ非公開ワークフローを使用して両方の dist-tag を安定版に向けるか、スケジュールされた自己修復同期によって後で `beta` が移動するようにします + ワークフローを使用して、その stable バージョンを `beta` から `latest` に promotion します +8. リリースを意図的に `latest` に直接公開し、`beta` もすぐに同じ stable build に追随させる必要がある場合は、同じ private ワークフローを使用して両方の dist-tag を stable バージョンに向けるか、スケジュールされた自己修復 sync によって後で `beta` を移動させます -dist-tag の変更は、引き続き `NPM_TOKEN` を必要とするため、セキュリティ上の理由で非公開リポジトリにあります。一方、公開リポジトリは OIDC のみの公開を維持します。 +dist-tag の変更は、引き続き `NPM_TOKEN` が必要なため、セキュリティ上の理由で private repo に置かれています。一方、public repo は OIDC のみの公開を維持します。 -これにより、直接公開パスと beta-first 昇格パスの両方が文書化され、オペレーターから見える状態になります。 +これにより、直接公開パスと beta-first promotion パスの両方が文書化され、オペレーターに見える状態になります。 -メンテナーがローカル npm 認証にフォールバックする必要がある場合は、1Password CLI（`op`）コマンドを専用の tmux セッション内でのみ実行します。メインエージェントシェルから `op` を直接呼び出さないでください。tmux 内に保つことで、プロンプト、アラート、OTP 処理を観測可能にし、ホストアラートの繰り返しを防げます。 +メンテナーがローカル npm 認証へフォールバックする必要がある場合は、1Password CLI (`op`) コマンドは専用の tmux セッション内でのみ実行してください。メインのエージェントシェルから `op` を直接呼び出さないでください。tmux 内に閉じ込めることで、プロンプト、アラート、OTP の処理を観測可能にし、ホストアラートの繰り返しを防ぎます。 -## 公開参照 +## 公開リファレンス - [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml) - [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml) @@ -459,10 +428,10 @@ dist-tag の変更は、引き続き `NPM_TOKEN` を必要とするため、セ - [`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) -メンテナーは、実際のランブックには非公開のリリースドキュメント +メンテナーは、実際の 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 index 4054f8ebb..a67db3aeb 100644 --- a/docs/ja-JP/reference/full-release-validation.md +++ b/docs/ja-JP/reference/full-release-validation.md @@ -6,19 +6,19 @@ read_when: summary: 完全リリース検証のステージ、子ワークフロー、リリースプロファイル、再実行ハンドル、証跡 title: 完全なリリース検証 x-i18n: - generated_at: "2026-05-03T21:38:07Z" + generated_at: "2026-05-05T01:48:53Z" model: gpt-5.5 provider: openai - source_hash: 038901ad751c00b35f69d7ec5caf74e577dcf2350d7658037c3ecc9ff5fab6d7 + source_hash: 6cf696761f516fc7f8e9606a2a06fab61a644731330eb484a388f276767a9e0d source_path: reference/full-release-validation.md workflow: 16 --- -`Full Release Validation` はリリース全体を統括するワークフローです。これはプレリリース証明の単一の手動 -エントリーポイントですが、作業の大半は子ワークフローで行われるため、 -失敗したボックスはリリース全体を最初からやり直さずに再実行できます。 +`Full Release Validation` はリリースの包括ワークフローです。これはプレリリース検証のための単一の手動 +エントリポイントですが、ほとんどの作業は子ワークフローで行われるため、 +失敗したボックスはリリース全体を再開せずに再実行できます。 -信頼されたワークフロー ref、通常は `main` から実行し、リリースブランチ、 +信頼済みのワークフロー参照、通常は `main` から実行し、リリースブランチ、 タグ、または完全なコミット SHA を `ref` として渡します。 ```bash @@ -30,127 +30,143 @@ gh workflow run full-release-validation.yml \ -f release_profile=stable ``` -子ワークフローはハーネスに信頼されたワークフロー ref を使用し、テスト対象の -候補には入力の `ref` を使用します。これにより、古いリリースブランチやタグを -検証するときにも、新しい検証ロジックを利用できます。 +子ワークフローはハーネスに信頼済みのワークフロー参照を使用し、テスト対象の +候補には入力 `ref` を使用します。これにより、古いリリースブランチやタグを +検証するときでも、新しい検証ロジックを利用できます。 -Package Acceptance は通常、解決された `ref` から候補 tarball をビルドします。 -これには `pnpm ci:full-release` でディスパッチされた完全 SHA 実行も含まれます。 -公開後は、`package_acceptance_package_spec=openclaw@YYYY.M.D`（または -`openclaw@beta`/`openclaw@latest`）を渡して、同じパッケージ/更新マトリクスを -出荷済みの npm パッケージに対して実行します。 +デフォルトでは、`release_profile=stable` はリリースをブロックするレーンを実行し、 +網羅的なライブ/Docker ソークをスキップします。stable 実行にソークレーンを含めるには +`run_release_soak=true` を渡します。`release_profile=full` は常にソークレーンを有効にするため、 +広範なアドバイザリプロファイルがカバレッジを黙って落とすことはありません。 -## トップレベルステージ +Package Acceptance は通常、`pnpm ci:full-release` でディスパッチされた完全 SHA 実行を含め、 +解決済みの `ref` から候補 tarball をビルドします。公開後は、 +`package_acceptance_package_spec=openclaw@YYYY.M.D`（または +`openclaw@beta`/`openclaw@latest`）を渡すと、同じパッケージ/更新マトリックスを +代わりに出荷済みの npm パッケージに対して実行できます。 -| ステージ | 詳細 | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ターゲット解決 | **ジョブ:** `Resolve target ref`
**子ワークフロー:** なし
**証明内容:** リリースブランチ、タグ、または完全なコミット SHA を解決し、選択された入力を記録します。
**再実行:** これが失敗した場合は統括ワークフローを再実行します。 | -| Vitest と通常 CI | **ジョブ:** `Run normal full CI`
**子ワークフロー:** `CI`
**証明内容:** ターゲット ref に対する手動の完全 CI グラフ。Linux Node レーン、同梱 Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、docs チェック、Python skills、Windows、macOS、Control UI i18n、統括ワークフロー経由の Android を含みます。
**再実行:** `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 parity、live Matrix、live Telegram。
**再実行:** `rerun_group=release-checks` またはより狭い release-checks ハンドル。 | -| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`
**子ワークフロー:** なし
**証明内容:** `OpenClaw Release Checks` を待つ必要がないパッケージ向けチェックで使えるよう、親の `release-package-under-test` tarball を十分早く作成します。
**再実行:** 統括ワークフローを再実行するか、`rerun_group=npm-telegram` に `npm_telegram_package_spec` を指定します。 | -| パッケージ Telegram | **ジョブ:** `Run package Telegram E2E`
**子ワークフロー:** `NPM Telegram Beta E2E`
**証明内容:** `rerun_group=all` かつ `release_profile=full` の親アーティファクトに基づく Telegram パッケージ証明、または `npm_telegram_package_spec` が設定されている場合の公開済みパッケージ Telegram 証明。
**再実行:** `npm_telegram_package_spec` 付きの `rerun_group=npm-telegram`。 | -| 統括検証 | **ジョブ:** `Verify full validation`
**子ワークフロー:** なし
**証明内容:** 記録された子実行の結論を再チェックし、子ワークフローから最も遅いジョブの表を追記します。
**再実行:** 失敗した子を再実行して成功にした後、このジョブだけを再実行します。 | +## トップレベルのステージ -`ref=main` かつ `rerun_group=all` の場合、新しい統括ワークフローは古いものを置き換えます。 +| ステージ | 詳細 | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ターゲット解決 | **ジョブ:** `Resolve target ref`
**子ワークフロー:** なし
**検証内容:** リリースブランチ、タグ、または完全なコミット SHA を解決し、選択された入力を記録します。
**再実行:** これが失敗した場合は包括ワークフローを再実行します。 | +| Vitest と通常 CI | **ジョブ:** `Run normal full CI`
**子ワークフロー:** `CI`
**検証内容:** ターゲット参照に対する手動のフル CI グラフ。Linux Node レーン、同梱 Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python skills、Windows、macOS、Control UI i18n、および包括ワークフロー経由の Android を含みます。
**再実行:** `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 パッケージチェック、Package Acceptance、QA Lab パリティ、ライブ Matrix、およびライブ Telegram。`run_release_soak=true` または `release_profile=full` の場合は、網羅的なライブ/E2E スイートと Docker リリースパスチャンクも実行します。
**再実行:** `rerun_group=release-checks` またはより狭い release-checks ハンドル。 | +| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`
**子ワークフロー:** なし
**検証内容:** `OpenClaw Release Checks` を待つ必要がないパッケージ向けチェックのために、親の `release-package-under-test` tarball を十分早く作成します。
**再実行:** 包括ワークフローを再実行するか、`rerun_group=npm-telegram` に `npm_telegram_package_spec` を指定します。 | +| パッケージ Telegram | **ジョブ:** `Run package Telegram E2E`
**子ワークフロー:** `NPM Telegram Beta E2E`
**検証内容:** `release_profile=full` を指定した `rerun_group=all` の場合は親アーティファクトを裏付けとする Telegram パッケージ検証、`npm_telegram_package_spec` が設定されている場合は公開済みパッケージの Telegram 検証。
**再実行:** `npm_telegram_package_spec` を指定した `rerun_group=npm-telegram`。 | +| 包括ワークフロー検証 | **ジョブ:** `Verify full validation`
**子ワークフロー:** なし
**検証内容:** 記録された子実行の結論を再チェックし、子ワークフローの最も遅いジョブの表を追記します。
**再実行:** 失敗した子を再実行してグリーンにした後、このジョブだけを再実行します。 | + +`ref=main` かつ `rerun_group=all` の場合、新しい包括ワークフローが古いものを置き換えます。 親がキャンセルされると、そのモニターはすでにディスパッチした子ワークフローを -キャンセルします。リリースブランチとタグの検証実行は、デフォルトでは互いにキャンセルしません。 +キャンセルします。リリースブランチおよびタグ検証の実行は、デフォルトでは互いを +キャンセルしません。 ## リリースチェックのステージ -`OpenClaw Release Checks` は最大の子ワークフローです。ターゲットを一度解決し、 -パッケージ向けまたは Docker 向けのステージが必要とするときに、共有の +`OpenClaw Release Checks` は最大の子ワークフローです。ターゲットを +一度だけ解決し、パッケージまたは Docker 向けのステージで必要な場合に共有の `release-package-under-test` アーティファクトを準備します。 -| ステージ | 詳細 | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| リリースターゲット | **ジョブ:** `Resolve target ref`
**バッキングワークフロー:** なし
**テスト:** 選択された ref、任意の期待 SHA、プロファイル、再実行グループ、フォーカスされた live スイートフィルター。
**再実行:** `rerun_group=release-checks`。 | -| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`
**バッキングワークフロー:** なし
**テスト:** 1 つの候補 tarball をパックまたは解決し、下流のパッケージ向けチェック用に `release-package-under-test` をアップロードします。
**再実行:** 影響を受けるパッケージ、クロス OS、または live/E2E グループ。 | -| インストールスモーク | **ジョブ:** `Run install smoke`
**バッキングワークフロー:** `Install Smoke`
**テスト:** ルート Dockerfile スモークイメージ再利用、QR パッケージインストール、ルートと Gateway の Docker スモーク、インストーラー Docker テスト、Bun グローバルインストールの画像プロバイダースモーク、高速な同梱 Plugin インストール/アンインストール 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)`
**テスト:** `release_profile` によって選択される、リポジトリ E2E、live キャッシュ、OpenAI websocket ストリーミング、ネイティブ live プロバイダーと Plugin シャード、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 パッケージフィクスチャ、Plugin 更新、モック OpenAI Telegram パッケージ受け入れ、`2026.4.23` 以降のすべての安定版 npm リリースから同じ tarball に対する公開済みアップグレード survivor チェック。
**再実行:** `rerun_group=package`。 | -| QA parity | **ジョブ:** `Run QA Lab parity lane` と `Run QA Lab parity report`
**バッキングワークフロー:** 直接ジョブ
**テスト:** 候補とベースラインのエージェント型 parity パック、その後の parity レポート。
**再実行:** `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`
**バッキングワークフロー:** なし
**テスト:** 選択された再実行グループに必要な release-check ジョブ。
**再実行:** フォーカスされた子ジョブが通過した後に再実行します。 | +| ステージ | 詳細 | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| リリース対象 | **ジョブ:** `Resolve target ref`
**基盤ワークフロー:** なし
**テスト:** 選択された ref、省略可能な期待 SHA、プロファイル、再実行グループ、対象を絞ったライブスイートフィルター。
**再実行:** `rerun_group=release-checks`。 | +| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`
**基盤ワークフロー:** なし
**テスト:** 候補 tarball を1つパックまたは解決し、下流のパッケージ向けチェック用に `release-package-under-test` をアップロードする。
**再実行:** 影響を受けるパッケージ、クロス OS、またはライブ/E2E グループ。 | +| インストールスモーク | **ジョブ:** `Run install smoke`
**基盤ワークフロー:** `Install Smoke`
**テスト:** ルート Dockerfile スモークイメージ再利用、QR パッケージインストール、ルートおよび Gateway Docker スモーク、インストーラー Docker テスト、Bun グローバルインストールの image-provider スモーク、高速なバンドル Plugin のインストール/アンインストール E2E を含む完全なインストールパス。
**再実行:** `rerun_group=install-smoke`。 | +| クロス OS | **ジョブ:** `cross_os_release_checks`
**基盤ワークフロー:** `OpenClaw Cross-OS Release Checks (Reusable)`
**テスト:** 候補 tarball とベースラインパッケージを使用し、選択されたプロバイダーとモードについて Linux、Windows、macOS 上の新規およびアップグレードレーン。
**再実行:** `rerun_group=cross-os`。 | +| リポジトリとライブ E2E | **ジョブ:** `Run repo/live E2E validation`
**基盤ワークフロー:** `OpenClaw Live And E2E Checks (Reusable)`
**テスト:** リポジトリ E2E、ライブキャッシュ、OpenAI websocket ストリーミング、ネイティブライブプロバイダーおよび Plugin シャード、`release_profile` によって選択される Docker ベースのライブモデル/バックエンド/Gateway ハーネス。
**実行条件:** `run_release_soak=true`、`release_profile=full`、または対象を絞った `rerun_group=live-e2e`。
**再実行:** `rerun_group=live-e2e`、省略可能で `live_suite_filter` を指定。 | +| Docker リリースパス | **ジョブ:** `Run Docker release-path validation`
**基盤ワークフロー:** `OpenClaw Live And E2E Checks (Reusable)`
**テスト:** 共有パッケージアーティファクトに対するリリースパス Docker チャンク。
**実行条件:** `run_release_soak=true`、`release_profile=full`、または対象を絞った `rerun_group=live-e2e`。
**再実行:** `rerun_group=live-e2e`。 | +| パッケージ受け入れ | **ジョブ:** `Run package acceptance`
**基盤ワークフロー:** `Package Acceptance`
**テスト:** オフライン Plugin パッケージフィクスチャ、Plugin 更新、モック OpenAI Telegram パッケージ受け入れ、同じ tarball に対する公開済みアップグレード生存チェック。ブロッキングリリースチェックではデフォルトの最新公開済みベースラインを使用し、ソークチェックでは `2026.4.23` 以降のすべての安定版 npm リリースと報告済み issue フィクスチャまで拡張する。
**再実行:** `rerun_group=package`。 | +| QA パリティ | **ジョブ:** `Run QA Lab parity lane` および `Run QA Lab parity report`
**基盤ワークフロー:** 直接ジョブ
**テスト:** 候補およびベースラインのエージェント的パリティパック、その後パリティレポート。
**再実行:** `rerun_group=qa-parity` または `rerun_group=qa`。 | +| QA ライブ Matrix | **ジョブ:** `Run QA Lab live Matrix lane`
**基盤ワークフロー:** 直接ジョブ
**テスト:** `qa-live-shared` 環境での高速ライブ Matrix QA プロファイル。
**再実行:** `rerun_group=qa-live` または `rerun_group=qa`。 | +| QA ライブ Telegram | **ジョブ:** `Run QA Lab live Telegram lane`
**基盤ワークフロー:** 直接ジョブ
**テスト:** Convex CI 認証情報リースを使用するライブ Telegram QA。
**再実行:** `rerun_group=qa-live` または `rerun_group=qa`。 | +| リリース検証器 | **ジョブ:** `Verify release checks`
**基盤ワークフロー:** なし
**テスト:** 選択された再実行グループに必要なリリースチェックジョブ。
**再実行:** 対象を絞った子ジョブが成功した後に再実行。 | ## Docker リリースパスチャンク -Docker リリースパスステージは、`live_suite_filter` が空のときに -これらのチャンクを実行します。 +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` through `plugins-runtime-install-h` | 並列リリース検証のために分割された Plugin インストール/ランタイムバッチ。 | +| `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` through `plugins-runtime-install-h` | 並列リリース検証用に分割された Plugin インストール/ランタイムバッチ。 | -再利用可能な live/E2E ワークフローで、失敗した Docker レーンが 1 つだけの場合は、対象を絞った `docker_lanes=` を使用します。リリースアーティファクトには、利用可能な場合にパッケージアーティファクトとイメージ再利用の入力を含む、レーンごとの再実行コマンドが含まれます。 +1つの Docker レーンだけが失敗した場合は、再利用可能なライブ/E2E ワークフローで対象を絞った `docker_lanes=` を使用する。リリースアーティファクトには、利用可能な場合にパッケージアーティファクトとイメージ再利用入力を含む、レーンごとの再実行コマンドが含まれる。 ## リリースプロファイル -`release_profile` は主に、リリースチェック内の live/プロバイダーの範囲を制御します。通常の完全 CI、Plugin Prerelease、インストールスモーク、パッケージ受け入れ、QA Lab、または Docker リリースパスのチャンクは削除しません。`full` は、`rerun_group=all` の場合に、親リリースパッケージアーティファクトに対してアンブレラ実行でパッケージ Telegram E2E も実行するため、完全な公開前候補がその Telegram パッケージレーンを暗黙にスキップすることはありません。 +`release_profile` は主にリリースチェック内のライブ/プロバイダーの幅を制御する。通常の完全 CI、Plugin プレリリース、インストールスモーク、パッケージ受け入れ、QA Lab は除外しない。`stable` では、網羅的なリポジトリ/ライブ E2E と Docker リリースパスチャンクはソークカバレッジであり、`run_release_soak=true` のときに実行される。`full` はソークカバレッジを強制的に有効にし、さらに `rerun_group=all` の場合、包括実行が親リリースパッケージアーティファクトに対してパッケージ Telegram E2E を実行するため、完全な公開前候補がその Telegram パッケージレーンを黙ってスキップしない。 -| プロファイル | 想定用途 | 含まれる live/プロバイダーのカバレッジ | +| プロファイル | 想定用途 | 含まれるライブ/プロバイダーカバレッジ | | --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `minimum` | 最速のリリースクリティカルスモーク。 | OpenAI/core live パス、OpenAI 用 Docker live モデル、ネイティブ Gateway core、ネイティブ OpenAI Gateway プロファイル、ネイティブ OpenAI plugin、および Docker live gateway OpenAI。 | -| `stable` | デフォルトのリリース承認プロファイル。 | `minimum` に加えて、Anthropic スモーク、Google、MiniMax、バックエンド、ネイティブ live テストハーネス、Docker live CLI バックエンド、Docker ACP バインド、Docker Codex ハーネス、および OpenCode Go スモークシャード。 | -| `full` | 広範なアドバイザリースイープ。 | `stable` に加えて、アドバイザリープロバイダー、plugin live シャード、およびメディア live シャード。 | +| `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` では含まれます。 +これらのスイートは `stable` ではスキップされ、`full` で含まれる: -| 領域 | full のみのカバレッジ | +| 領域 | full のみのカバレッジ | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| Docker live モデル | OpenCode Go、OpenRouter、xAI、Z.ai、および Fireworks。 | -| Docker live gateway | アドバイザリープロバイダーを DeepSeek/Fireworks、OpenCode Go/OpenRouter、xAI/Z.ai シャードに分割。 | -| ネイティブ Gateway プロバイダープロファイル | 完全な Anthropic Opus および Sonnet/Haiku シャード、Fireworks、DeepSeek、完全な OpenCode Go モデルシャード、OpenRouter、xAI、および Z.ai。 | -| ネイティブ plugin live シャード | Plugins A-K、L-N、O-Z その他、Moonshot、および xAI。 | -| ネイティブメディア live シャード | Audio、Google music、MiniMax music、および video groups A-D。 | +| Docker ライブモデル | OpenCode Go、OpenRouter、xAI、Z.ai、Fireworks。 | +| Docker ライブ Gateway | DeepSeek/Fireworks、OpenCode Go/OpenRouter、xAI/Z.ai シャードに分割されたアドバイザリープロバイダー。 | +| ネイティブ Gateway プロバイダープロファイル | 完全な Anthropic Opus および Sonnet/Haiku シャード、Fireworks、DeepSeek、完全な OpenCode Go モデルシャード、OpenRouter、xAI、Z.ai。 | +| ネイティブ Plugin ライブシャード | Plugins A-K、L-N、O-Z その他、Moonshot、xAI。 | +| ネイティブメディアライブシャード | Audio、Google music、MiniMax music、video groups A-D。 | -`stable` は `native-live-src-gateway-profiles-anthropic-smoke` と `native-live-src-gateway-profiles-opencode-go-smoke` を含みます。`full` は代わりに、より広範な Anthropic および OpenCode Go モデルシャードを使用します。対象を絞った再実行では、引き続き集約 `native-live-src-gateway-profiles-anthropic` または `native-live-src-gateway-profiles-opencode-go` ハンドルを使用できます。 +`stable` には `native-live-src-gateway-profiles-anthropic-smoke` と `native-live-src-gateway-profiles-opencode-go-smoke` が含まれる。`full` は代わりに、より広範な Anthropic および OpenCode Go モデルシャードを使用する。対象を絞った再実行では、引き続き集約 `native-live-src-gateway-profiles-anthropic` または `native-live-src-gateway-profiles-opencode-go` ハンドルを使用できる。 ## 対象を絞った再実行 -関連しないリリースボックスの繰り返しを避けるには、`rerun_group` を使用します。 +無関係なリリースボックスの繰り返しを避けるには `rerun_group` を使用する: -| ハンドル | スコープ | +| ハンドル | スコープ | | ------------------- | --------------------------------------------------------------------- | -| `all` | すべての完全リリース検証ステージ。 | -| `ci` | 手動の完全 CI 子のみ。 | -| `plugin-prerelease` | Plugin Prerelease 子のみ。 | -| `release-checks` | すべての OpenClaw リリースチェックのステージ。 | -| `install-smoke` | リリースチェックを通した Install Smoke。 | -| `cross-os` | クロス OS リリースチェック。 | -| `live-e2e` | リポジトリ/live E2E および Docker リリースパス検証。 | -| `package` | Package Acceptance。 | -| `qa` | QA パリティと QA live レーン。 | -| `qa-parity` | QA パリティレーンとレポートのみ。 | -| `qa-live` | QA live Matrix と Telegram のみ。 | -| `npm-telegram` | 公開済みパッケージ Telegram E2E。`npm_telegram_package_spec` が必要です。 | +| `all` | すべての完全リリース検証ステージ。 | +| `ci` | 手動の完全 CI 子のみ。 | +| `plugin-prerelease` | Plugin プレリリース子のみ。 | +| `release-checks` | すべての OpenClaw リリースチェックステージ。 | +| `install-smoke` | リリースチェックまでのインストールスモーク。 | +| `cross-os` | クロス OS リリースチェック。 | +| `live-e2e` | リポジトリ/ライブ E2E と Docker リリースパス検証。 | +| `package` | パッケージ受け入れ。 | +| `qa` | QA パリティと QA ライブレーン。 | +| `qa-parity` | QA パリティレーンとレポートのみ。 | +| `qa-live` | QA ライブ Matrix と Telegram のみ。 | +| `npm-telegram` | 公開済みパッケージの Telegram E2E。`npm_telegram_package_spec` が必要。 | -1 つの live スイートが失敗した場合は、`rerun_group=live-e2e` とともに `live_suite_filter` を使用します。有効なフィルター ID は再利用可能な live/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` が含まれます。 +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`。 -`live-gateway-advisory-docker` ハンドルは、その 3 つのプロバイダーシャード用の集約再実行ハンドルであるため、引き続きすべてのアドバイザリ Docker Gateway ジョブへ展開されます。 +`live-gateway-advisory-docker` ハンドルは、3 つのプロバイダーシャードに対する集約再実行ハンドルであるため、引き続きすべてのアドバイザリ Docker Gateway ジョブへファンアウトします。 + +1 つのクロス OS レーンが失敗した場合は、`rerun_group=cross-os` とともに `cross_os_suite_filter` を使用します。フィルターは OS id、スイート id、または OS/スイートのペアを受け付けます。例: `windows/packaged-upgrade`、`windows`、`packaged-fresh`。クロス OS サマリーには、パッケージ化アップグレードレーンのフェーズごとの所要時間が含まれます。また、長時間実行されるコマンドは Heartbeat 行を出力するため、ジョブのタイムアウト前に Windows 更新の停止が見えるようになります。 + +QA リリースチェックレーンはアドバイザリです。QA のみの失敗は警告として報告され、リリースチェック検証器をブロックしません。新しい QA エビデンスが必要な場合は、`rerun_group=qa`、 +`qa-parity`、または `qa-live` を再実行します。 ## 保持するエビデンス -`Full Release Validation` サマリーをリリースレベルのインデックスとして保持します。これは子実行 ID にリンクし、最も遅いジョブの表を含みます。失敗時は、まず子ワークフローを調査し、その後、上記の最小の一致するハンドルを再実行します。 +リリースレベルの索引として `Full Release Validation` サマリーを保持します。これは子実行 id にリンクし、最も遅いジョブの表を含みます。失敗時は、まず子ワークフローを確認してから、上記の最小の一致ハンドルを再実行します。 有用なアーティファクト: - Full Release Validation 親および `OpenClaw Release Checks` からの `release-package-under-test` - `.artifacts/docker-tests/` 配下の Docker リリースパスアーティファクト -- Package Acceptance の `package-under-test` および Docker 受け入れアーティファクト -- 各 OS とスイートの Cross-OS リリースチェックアーティファクト -- QA パリティ、Matrix、および Telegram アーティファクト +- パッケージ受け入れの `package-under-test` と Docker 受け入れアーティファクト +- 各 OS とスイートのクロス OS リリースチェックアーティファクト +- QA パリティ、Matrix、Telegram アーティファクト ## ワークフローファイル diff --git a/docs/ja-JP/reference/test.md b/docs/ja-JP/reference/test.md index b82c83459..ddd0f4661 100644 --- a/docs/ja-JP/reference/test.md +++ b/docs/ja-JP/reference/test.md @@ -1,59 +1,59 @@ --- read_when: - テストの実行または修正 -summary: テストをローカルで実行する方法 (vitest) と、force/coverage モードを使うタイミング +summary: ローカルでテストを実行する方法 (vitest) と force/coverage モードを使うタイミング title: テスト x-i18n: - generated_at: "2026-05-02T21:05:56Z" + generated_at: "2026-05-05T01:48:47Z" model: gpt-5.5 provider: openai - source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f + source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605 source_path: reference/test.md workflow: 16 --- - 完全なテストキット（スイート、ライブ、Docker）: [テスト](/ja-JP/help/testing) -- 更新と Plugin パッケージ検証: [更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins) +- 更新とPluginパッケージの検証: [更新とPluginのテスト](/ja-JP/help/testing-updates-plugins) -- `pnpm test:force`: デフォルトの制御ポートを保持している残存 Gateway プロセスを終了し、分離された Gateway ポートで完全な Vitest スイートを実行して、サーバーテストが実行中のインスタンスと衝突しないようにします。以前の Gateway 実行によってポート 18789 が占有されたままになっている場合に使用します。 -- `pnpm test:coverage`: V8 カバレッジ付きでユニットスイートを実行します（`vitest.unit.config.ts` 経由）。これは読み込まれたファイルのユニットカバレッジゲートであり、リポジトリ全体の全ファイルカバレッジではありません。しきい値は行/関数/ステートメントが 70%、ブランチが 55% です。`coverage.all` が false であるため、このゲートはすべての分割レーンのソースファイルを未カバーとして扱うのではなく、ユニットカバレッジスイートによって読み込まれたファイルを測定します。 +- `pnpm test:force`: デフォルトの制御ポートを保持している残存 Gateway プロセスを終了し、隔離された Gateway ポートで Vitest スイート全体を実行して、サーバーテストが実行中のインスタンスと衝突しないようにします。以前の Gateway 実行によってポート 18789 が使用中のまま残っている場合に使用します。 +- `pnpm test:coverage`: （`vitest.unit.config.ts` 経由で）V8 カバレッジ付きのユニットスイートを実行します。これは、リポジトリ全体の全ファイルカバレッジではなく、読み込まれたファイルのユニットカバレッジゲートです。しきい値は行/関数/ステートメントが 70%、ブランチが 55% です。`coverage.all` が false のため、このゲートは、すべての分割レーンのソースファイルを未カバーとして扱うのではなく、ユニットカバレッジスイートによって読み込まれたファイルを測定します。 - `pnpm test:coverage:changed`: `origin/main` 以降に変更されたファイルのみを対象にユニットカバレッジを実行します。 -- `pnpm test:changed`: 低コストのスマート変更テスト実行です。直接のテスト編集、隣接する `*.test.ts` ファイル、明示的なソースマッピング、ローカルのインポートグラフから精密なターゲットを実行します。広範な/config/package 変更は、精密なテストに対応付けられない限りスキップされます。 -- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: 明示的な広範囲の変更テスト実行です。テストハーネス/config/package の編集で、Vitest のより広い変更テスト動作へフォールバックすべき場合に使用します。 +- `pnpm test:changed`: 安価なスマート変更テスト実行です。直接編集されたテスト、兄弟 `*.test.ts` ファイル、明示的なソースマッピング、ローカルのインポートグラフから正確なターゲットを実行します。広範な/config/package 変更は、正確なテストにマップされない限りスキップされます。 +- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: 明示的な広範囲変更テスト実行です。テストハーネス/config/package の編集で Vitest のより広い変更テスト動作にフォールバックさせる必要がある場合に使用します。 - `pnpm changed:lanes`: `origin/main` に対する差分によってトリガーされるアーキテクチャレーンを表示します。 -- `pnpm check:changed`: `origin/main` に対する差分について、スマート変更チェックゲートを実行します。影響を受けるアーキテクチャレーンの typecheck、lint、ガードコマンドを実行しますが、Vitest テストは実行しません。テストの証明には `pnpm test:changed` または明示的な `pnpm test ` を使用します。 -- `pnpm test`: 明示的なファイル/ディレクトリターゲットをスコープ付き Vitest レーンにルーティングします。ターゲットなしの実行では固定シャードグループを使用し、ローカル並列実行のためにリーフ config へ展開します。extension グループは、巨大な単一 root-project プロセスではなく、常に extension ごとのシャード config に展開されます。 -- テストラッパーの実行は、短い `[test] passed|failed|skipped ... in ...` サマリーで終了します。Vitest 自身の所要時間行はシャードごとの詳細のままです。 -- 共有 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、ログキャプチャ、クリーンアップを一か所で扱う必要がある場合は、`test/helpers/openclaw-test-instance.ts` を使用します。 -- Docker/Bash E2E ヘルパー: `scripts/lib/docker-e2e-image.sh` を source するレーンは、`docker_e2e_test_state_shell_b64 - ワークフロー駆動のローカルまたはクラウド実行。設定されたグラフを通じて、 + ワークフロー駆動のローカルまたはクラウド実行です。設定されたグラフを通じて text-to-video と image-to-video をサポートします。 長時間実行ジョブにキュー支援フローを使用します。ほとんどの fal 動画モデルは - 単一の画像参照を受け付けます。Seedance 2.0 reference-to-video - モデルは、最大 9 つの画像、3 つの動画、3 つの音声参照を受け付け、 - 参照ファイルの合計は最大 12 件です。 + 単一の画像参照を受け付けます。Seedance 2.0 reference-to-video モデルは、 + 最大 9 つの画像、3 つの動画、3 つの音声参照を受け付け、参照ファイルの合計は + 最大 12 件です。 - 1 つの画像または 1 つの動画参照をサポートします。 + 1 つの画像参照または 1 つの動画参照をサポートします。 - 単一の画像参照のみ。 + 単一画像参照のみ。 `size` 上書きのみが転送されます。その他のスタイル上書き - （`aspectRatio`、`resolution`、`audio`、`watermark`）は警告付きで無視されます。 + （`aspectRatio`、`resolution`、`audio`、`watermark`）は警告付きで + 無視されます。 OpenRouter の非同期 `/videos` API を使用します。OpenClaw は ジョブを送信し、`polling_url` をポーリングし、`unsigned_urls` または - 文書化されたジョブコンテンツエンドポイントのいずれかをダウンロードします。バンドルされた `google/veo-3.1-fast` デフォルトは、 - 4/6/8 秒の長さ、`720P`/`1080P` 解像度、および - `16:9`/`9:16` アスペクト比を公開します。 + 文書化されたジョブコンテンツエンドポイントのいずれかをダウンロードします。 + 同梱の `google/veo-3.1-fast` デフォルトは、4/6/8 秒の継続時間、 + `720P`/`1080P` 解像度、`16:9`/`9:16` アスペクト比を告知します。 - Alibaba と同じ DashScope バックエンド。参照入力はリモートの + Alibaba と同じ DashScope バックエンドです。参照入力はリモートの `http(s)` URL である必要があります。ローカルファイルは事前に拒否されます。 - データ URI 経由でローカルファイルをサポートします。Video-to-video には + data URI 経由でローカルファイルをサポートします。video-to-video には `runway/gen4_aleph` が必要です。テキストのみの実行では `16:9` と `9:16` の アスペクト比が公開されます。 - 単一の画像参照のみ。 + 単一画像参照のみ。 - 認証を落とすリダイレクトを避けるため、`https://www.vydra.ai/api/v1` を直接使用します。 - `veo3` は text-to-video のみとしてバンドルされています。`kling` には + 認証が落ちるリダイレクトを避けるため、`https://www.vydra.ai/api/v1` を直接使用します。 + `veo3` は text-to-video のみとして同梱されています。`kling` には リモート画像 URL が必要です。 - text-to-video、単一の最初フレーム image-to-video、xAI `reference_images` 経由の最大 7 つの - `reference_image` 入力、およびリモート - 動画編集/拡張フローをサポートします。 + text-to-video、単一の最初のフレーム image-to-video、xAI `reference_images` 経由の + 最大 7 つの `reference_image` 入力、リモート動画の編集/延長フローをサポートします。 ## プロバイダー機能モード -共有の動画生成コントラクトは、フラットな集約制限だけでなく、モード固有の機能をサポートします。新しいプロバイダー実装では、明示的なモードブロックを優先してください。 +共有動画生成コントラクトは、フラットな集約制限だけではなく、 +モード固有の機能をサポートします。新しいプロバイダー実装では、 +明示的なモードブロックを優先してください。 ```typescript capabilities: { @@ -448,13 +452,20 @@ capabilities: { } ``` -`maxInputImages` や `maxInputVideos` などのフラットな集約フィールドだけでは、変換モードのサポートを示すには**不十分**です。プロバイダーは `generate`、`imageToVideo`、`videoToVideo` を明示的に宣言し、ライブテスト、コントラクトテスト、共有の `video_generate` ツールがモードサポートを決定論的に検証できるようにする必要があります。 +`maxInputImages` や `maxInputVideos` などのフラットな集約フィールドだけでは、 +変換モードのサポートを示すには**不十分**です。プロバイダーは +`generate`、`imageToVideo`、`videoToVideo` を明示的に宣言し、ライブテスト、 +コントラクトテスト、共有 `video_generate` ツールがモードサポートを +決定論的に検証できるようにしてください。 -プロバイダー内の 1 つのモデルが他のモデルより広い参照入力サポートを持つ場合は、モード全体の制限を引き上げるのではなく、`maxInputImagesByModel`、`maxInputVideosByModel`、または `maxInputAudiosByModel` を使用してください。 +プロバイダー内のあるモデルだけが、他のモデルより広い参照入力サポートを +持つ場合は、モード全体の制限を引き上げるのではなく、 +`maxInputImagesByModel`、`maxInputVideosByModel`、または +`maxInputAudiosByModel` を使用してください。 ## ライブテスト -共有の同梱プロバイダー向けのライブカバレッジはオプトインです。 +共有バンドルプロバイダーのライブカバレッジにオプトインします。 ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts @@ -466,24 +477,31 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv pnpm test:live:media video ``` -このライブファイルは、不足しているプロバイダー環境変数を `~/.profile` から読み込み、デフォルトでは保存済み認証プロファイルよりもライブ/環境 API キーを優先し、デフォルトでリリースに安全なスモークを実行します。 +このライブファイルは、不足しているプロバイダー環境変数を `~/.profile` から読み込み、 +デフォルトで保存済み認証プロファイルよりライブ/環境 APIキーを優先し、 +デフォルトでリリースに安全なスモークを実行します。 -- スイープ内のすべての非 FAL プロバイダーに対する `generate`。 -- 1 秒のロブスタープロンプト。 -- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` から取得するプロバイダーごとの操作上限（デフォルトは `180000`）。 +- スイープ内のすべての非FALプロバイダーに対する `generate`。 +- 1秒のロブスタープロンプト。 +- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` からのプロバイダーごとの操作上限 + （デフォルトは `180000`）。 -FAL はオプトインです。プロバイダー側のキュー遅延がリリース時間の大部分を占める可能性があるためです。 +FAL はプロバイダー側のキュー待ち時間がリリース時間を支配する可能性があるため、 +オプトインです。 ```bash pnpm test:live:media video --video-providers fal ``` -`OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定すると、共有スイープがローカルメディアで安全に実行できる、宣言済みの変換モードも実行します。 +`OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定すると、共有スイープが +ローカルメディアで安全に実行できる宣言済み変換モードも実行します。 -- `capabilities.imageToVideo.enabled` の場合の `imageToVideo`。 -- `capabilities.videoToVideo.enabled` で、プロバイダー/モデルが共有スイープ内のバッファバックのローカル動画入力を受け入れる場合の `videoToVideo`。 +- `capabilities.imageToVideo.enabled` の場合は `imageToVideo`。 +- `capabilities.videoToVideo.enabled` で、プロバイダー/モデルが共有スイープ内の + バッファに基づくローカル動画入力を受け付ける場合は `videoToVideo`。 -現在、共有の `videoToVideo` ライブレーンは、`runway/gen4_aleph` を選択した場合にのみ `runway` をカバーします。 +現在、共有 `videoToVideo` ライブレーンは、`runway/gen4_aleph` を選択した場合にのみ +`runway` を対象にします。 ## 設定 @@ -502,7 +520,7 @@ OpenClaw 設定でデフォルトの動画生成モデルを設定します。 } ``` -または CLI から設定します。 +または CLI 経由: ```bash openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v" diff --git a/docs/ja-JP/web/dashboard.md b/docs/ja-JP/web/dashboard.md index 17b66ed08..a5ed2cf5a 100644 --- a/docs/ja-JP/web/dashboard.md +++ b/docs/ja-JP/web/dashboard.md @@ -1,97 +1,94 @@ --- read_when: - - ダッシュボードの認証または公開モードを変更する場合 -summary: Gateway ダッシュボード（Control UI）へのアクセスと認証 + - ダッシュボードの認証または公開モードの変更 +summary: Gateway ダッシュボード（コントロール UI）のアクセスと認証 title: ダッシュボード x-i18n: - refreshed_at: '2026-04-28T05:23:26Z' - generated_at: "2026-04-25T14:02:39Z" - model: gpt-5.4 - provider: openai - source_hash: 5e0e7c8cebe715f96e7f0e967e9fd86c4c6c54f7cc08a4291b02515fc0933a1a - source_path: web/dashboard.md - workflow: 15 + generated_at: "2026-05-05T01:50:50Z" + model: gpt-5.5 + provider: openai + source_hash: 0e2086587fee6303221663748c3047886a5beae29862d66e2edf78e02bfe3da1 + source_path: web/dashboard.md + workflow: 16 --- -Gateway ダッシュボードは、デフォルトで `/` で提供されるブラウザー Control UI です -（`gateway.controlUi.basePath` で上書き可能）。 +Gateway ダッシュボードは、デフォルトで `/` から提供されるブラウザー版 Control UI です +（`gateway.controlUi.basePath` で上書きできます）。 -クイックオープン（ローカル Gateway）: +すばやく開く（ローカル Gateway）: - [http://127.0.0.1:18789/](http://127.0.0.1:18789/)（または [http://localhost:18789/](http://localhost:18789/)） -- `gateway.tls.enabled: true` の場合は、`https://127.0.0.1:18789/` と - WebSocket エンドポイント `wss://127.0.0.1:18789` を使います。 +- `gateway.tls.enabled: true` の場合は、WebSocket エンドポイントに `https://127.0.0.1:18789/` と + `wss://127.0.0.1:18789` を使用します。 -主な参照先: +主なリファレンス: -- 使用方法と UI 機能については [Control UI](/ja-JP/web/control-ui)。 +- 使い方と UI 機能については [Control UI](/ja-JP/web/control-ui)。 - Serve/Funnel 自動化については [Tailscale](/ja-JP/gateway/tailscale)。 -- bind モードとセキュリティ注記については [Web surfaces](/ja-JP/web)。 +- バインドモードとセキュリティ上の注意については [Web サーフェス](/ja-JP/web)。 -認証は、設定された Gateway の auth 経路を通じて、WebSocket ハンドシェイク時に強制されます。 +認証は、設定された gateway 認証パスを通じて WebSocket ハンドシェイクで強制されます。 - `connect.params.auth.token` - `connect.params.auth.password` -- `gateway.auth.allowTailscale: true` のときの Tailscale Serve identity ヘッダー -- `gateway.auth.mode: "trusted-proxy"` のときの trusted-proxy identity ヘッダー +- `gateway.auth.allowTailscale: true` の場合は Tailscale Serve ID ヘッダー +- `gateway.auth.mode: "trusted-proxy"` の場合は信頼済みプロキシ ID ヘッダー -`gateway.auth` については [Gateway configuration](/ja-JP/gateway/configuration) を参照してください。 +[Gateway 設定](/ja-JP/gateway/configuration)の `gateway.auth` を参照してください。 -セキュリティ注記: Control UI は **管理用サーフェス** です（chat、config、exec approvals）。 -公開インターネットへ露出させないでください。UI は、現在のブラウザータブセッションと選択された Gateway URL に対するダッシュボード URL トークンを sessionStorage に保持し、ロード後に URL から取り除きます。 +セキュリティ上の注意: Control UI は**管理者サーフェス**です（チャット、設定、exec 承認）。 +公開しないでください。UI は、現在のブラウザータブセッションと選択された gateway URL について、ダッシュボード URL トークンを sessionStorage に保持し、読み込み後に URL から削除します。 localhost、Tailscale Serve、または SSH トンネルを優先してください。 -## ファストパス（推奨） +## 高速パス（推奨） -- オンボーディング後、CLI は自動的にダッシュボードを開き、クリーンな（トークンなし）リンクを表示します。 -- いつでも再度開くには: `openclaw dashboard`（リンクをコピーし、可能ならブラウザーを開き、headless なら SSH ヒントを表示）。 -- UI が shared-secret 認証を求める場合は、設定された token または - password を Control UI 設定に貼り付けてください。 +- オンボーディング後、CLI はダッシュボードを自動的に開き、クリーンな（トークン化されていない）リンクを表示します。 +- いつでも再度開く: `openclaw dashboard`（リンクをコピーし、可能ならブラウザーを開き、ヘッドレスの場合は SSH ヒントを表示します）。 +- クリップボードとブラウザー配信に失敗した場合でも、`openclaw dashboard` はクリーンな URL を表示し、 + `OPENCLAW_GATEWAY_TOKEN` または `gateway.auth.token` のトークンを URL フラグメントキー `token` として使用するよう伝えます。ログにはトークン値を表示しません。 +- UI が共有シークレット認証を求めた場合は、設定済みのトークンまたは + パスワードを Control UI 設定に貼り付けます。 ## 認証の基本（ローカルとリモート） - **Localhost**: `http://127.0.0.1:18789/` を開きます。 -- **Gateway TLS**: `gateway.tls.enabled: true` の場合、ダッシュボード/ステータスのリンクは - `https://` を使い、Control UI の WebSocket リンクは `wss://` を使います。 -- **Shared-secret token の取得元**: `gateway.auth.token`（または - `OPENCLAW_GATEWAY_TOKEN`）。`openclaw dashboard` は 1 回限りの bootstrap 用に - URL fragment 経由でこれを渡せます。Control UI はこれを localStorage ではなく、 - 現在のブラウザータブセッションと選択された Gateway URL 用の sessionStorage に保持します。 -- `gateway.auth.token` が SecretRef 管理されている場合、`openclaw dashboard` は - 設計上、トークンなし URL を表示/コピー/オープンします。これにより、外部管理トークンがシェルログ、クリップボード履歴、ブラウザー起動引数に露出するのを防ぎます。 -- `gateway.auth.token` が SecretRef として設定されていて、現在のシェルで未解決の場合でも、 - `openclaw dashboard` はトークンなし URL と、実行可能な認証セットアップ案内を表示します。 -- **Shared-secret password**: 設定済みの `gateway.auth.password`（または - `OPENCLAW_GATEWAY_PASSWORD`）を使います。ダッシュボードは reload をまたいで password を保持しません。 -- **Identity を持つモード**: `gateway.auth.allowTailscale: true` の場合、Tailscale Serve は identity ヘッダーを通じて Control UI/WebSocket 認証を満たせます。また、 - loopback 以外の identity-aware reverse proxy は - `gateway.auth.mode: "trusted-proxy"` を満たせます。これらのモードでは、ダッシュボードは WebSocket 用に shared secret を貼り付ける必要がありません。 -- **localhost 以外**: Tailscale Serve、loopback 以外の shared-secret bind、 - `gateway.auth.mode: "trusted-proxy"` を使う loopback 以外の identity-aware reverse proxy、 - または SSH トンネルを使ってください。HTTP API は、意図的に private-ingress の - `gateway.auth.mode: "none"` または trusted-proxy HTTP auth を使わない限り、引き続き shared-secret 認証を使います。詳しくは - [Web surfaces](/ja-JP/web) を参照してください。 +- **Gateway TLS**: `gateway.tls.enabled: true` の場合、ダッシュボード/ステータスリンクは + `https://` を使用し、Control UI WebSocket リンクは `wss://` を使用します。 +- **共有シークレットトークンのソース**: `gateway.auth.token`（または + `OPENCLAW_GATEWAY_TOKEN`）。`openclaw dashboard` は 1 回限りのブートストラップのために URL フラグメント経由で渡すことができ、Control UI はそれを localStorage ではなく、現在のブラウザータブセッションと選択された gateway URL の sessionStorage に保持します。 +- `gateway.auth.token` が SecretRef 管理の場合、`openclaw dashboard` は設計上、トークン化されていない URL を表示/コピー/開きます。これにより、外部管理トークンがシェルログ、クリップボード履歴、ブラウザー起動引数に露出することを避けます。 +- `gateway.auth.token` が SecretRef として設定され、現在のシェルで解決されていない場合でも、`openclaw dashboard` はトークン化されていない URL と実行可能な認証セットアップガイダンスを表示します。 +- **共有シークレットパスワード**: 設定済みの `gateway.auth.password`（または + `OPENCLAW_GATEWAY_PASSWORD`）を使用します。ダッシュボードはリロードをまたいでパスワードを保持しません。 +- **ID を伴うモード**: `gateway.auth.allowTailscale: true` の場合、Tailscale Serve は ID ヘッダーによって Control UI/WebSocket 認証を満たせます。また、local loopback ではない ID 対応リバースプロキシは + `gateway.auth.mode: "trusted-proxy"` を満たせます。これらのモードでは、ダッシュボードは WebSocket 用に共有シークレットを貼り付ける必要がありません。 +- **Localhost ではない場合**: Tailscale Serve、local loopback ではない共有シークレットバインド、 + `gateway.auth.mode: "trusted-proxy"` を使用する local loopback ではない ID 対応リバースプロキシ、または SSH トンネルを使用します。意図的にプライベートイングレスの + `gateway.auth.mode: "none"` または trusted-proxy HTTP 認証を実行していない限り、HTTP API は引き続き共有シークレット認証を使用します。 + [Web サーフェス](/ja-JP/web)を参照してください。 ## 「unauthorized」/ 1008 が表示される場合 -- Gateway に到達できることを確認してください（ローカル: `openclaw status`、リモート: SSH トンネル `ssh -N -L 18789:127.0.0.1:18789 user@host` の後に `http://127.0.0.1:18789/` を開く）。 -- `AUTH_TOKEN_MISMATCH` の場合、Gateway が retry ヒントを返すと、クライアントはキャッシュ済み device token で 1 回だけ信頼済み再試行を行うことがあります。そのキャッシュトークン再試行では、そのトークンのキャッシュ済み承認 scope を再利用します。明示的な `deviceToken` / 明示的な `scopes` 呼び出し元は、要求した scope 集合を保持します。その再試行後も認証が失敗する場合は、token drift を手動で解消してください。 -- その再試行経路以外では、connect 認証の優先順位は、明示的 shared token/password、次に明示的 `deviceToken`、次に保存済み device token、最後に bootstrap token です。 -- 非同期 Tailscale Serve Control UI 経路では、同じ - `{scope, ip}` に対する失敗試行は、failed-auth limiter が記録する前に直列化されるため、2 回目の同時不正再試行で、すでに `retry later` が表示される場合があります。 -- token drift の修復手順については、[Token drift recovery checklist](/ja-JP/cli/devices#token-drift-recovery-checklist) を参照してください。 -- shared secret を Gateway ホストから取得または指定します: - - Token: `openclaw config get gateway.auth.token` - - Password: 設定済みの `gateway.auth.password` または - `OPENCLAW_GATEWAY_PASSWORD` を解決する - - SecretRef 管理トークン: 外部 secret provider を解決するか、このシェルで - `OPENCLAW_GATEWAY_TOKEN` を export してから `openclaw dashboard` を再実行する - - shared secret が未設定: `openclaw doctor --generate-gateway-token` -- ダッシュボード設定で、auth フィールドに token または password を貼り付けてから接続してください。 -- UI の言語ピッカーは **Overview -> Gateway Access -> Language** にあります。 - Appearance セクションではなく、access カードの一部です。 +- gateway に到達できることを確認します（ローカル: `openclaw status`、リモート: SSH トンネル `ssh -N -L 18789:127.0.0.1:18789 user@host` の後、`http://127.0.0.1:18789/` を開きます）。 +- `AUTH_TOKEN_MISMATCH` の場合、gateway が再試行ヒントを返すと、クライアントはキャッシュされたデバイストークンで 1 回の信頼済み再試行を行うことがあります。そのキャッシュトークン再試行では、トークンのキャッシュ済み承認スコープが再利用されます。明示的な `deviceToken` / 明示的な `scopes` 呼び出し元は、要求したスコープセットを保持します。その再試行後も認証が失敗する場合は、トークンのずれを手動で解決してください。 +- その再試行パス以外では、接続認証の優先順位は、明示的な共有トークン/パスワード、明示的な `deviceToken`、保存済みデバイストークン、ブートストラップトークンの順です。 +- 非同期 Tailscale Serve Control UI パスでは、同じ + `{scope, ip}` に対する失敗した試行は、失敗認証リミッターが記録する前に直列化されるため、 + 2 回目の同時不正再試行はすでに `retry later` を表示することがあります。 +- トークンずれの修復手順については、[トークンずれ回復チェックリスト](/ja-JP/cli/devices#token-drift-recovery-checklist)に従ってください。 +- gateway ホストから共有シークレットを取得または指定します。 + - トークン: `openclaw config get gateway.auth.token` + - パスワード: 設定済みの `gateway.auth.password` または + `OPENCLAW_GATEWAY_PASSWORD` を解決します + - SecretRef 管理トークン: 外部シークレットプロバイダーを解決するか、このシェルで + `OPENCLAW_GATEWAY_TOKEN` をエクスポートしてから、`openclaw dashboard` を再実行します + - 共有シークレットが設定されていない: `openclaw doctor --generate-gateway-token` +- ダッシュボード設定で、認証フィールドにトークンまたはパスワードを貼り付けてから、 + 接続します。 +- UI 言語ピッカーは **概要 -> Gateway アクセス -> 言語** にあります。 + これはアクセスカードの一部であり、外観セクションではありません。 ## 関連