openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh ja-JP translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 01:52:21 +00:00
parent d54240ba65
commit 6b43efae95
37 changed files with 4969 additions and 4415 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

222
docs/ja-JP/automation/tasks.md
View File

@ -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
---
<Note>
スケジュール設定を探していますか？適切な仕組みを選ぶには、[自動化とタスク](/ja-JP/automation)を参照してください。このページはバックグラウンド作業のアクティビティ台帳であり、スケジューラーではありません。
スケジュール設定を探していますか？適切な仕組みの選択については、[自動化とタスク](/ja-JP/automation)を参照してください。このページはバックグラウンド作業のアクティビティ台帳であり、スケジューラーではありません。
</Note>
バックグラウンドタスクは、**メインの会話セッションの外部**で実行される作業を追跡します: ACP 実行、サブエージェントの起動、分離された cron ジョブ実行、CLI から開始された操作です。
バックグラウンドタスクは、**メインの会話セッション外**で実行される作業を追跡します: ACP 実行、サブエージェントの起動、分離された Cron ジョブ実行、CLI から開始された操作です。
タスクはセッション、cron ジョブ、Heartbeat を置き換えるものではありません。タスクは、どの分離作業がいつ発生し、成功したかどうかを記録する**アクティビティ台帳**です。
タスクは、セッション、Cron ジョブ、Heartbeat を置き換えるものではありません。タスクは、どの切り離された作業がいつ発生し、成功したかどうかを記録する**アクティビティ台帳**です。
<Note>
すべてのエージェント実行がタスクを作成するわけではありません。Heartbeat ターンと通常の対話型チャットは作成しません。すべての cron 実行、ACP 起動、サブエージェント起動、CLI エージェントコマンドは作成します。
すべてのエージェント実行がタスクを作成するわけではありません。Heartbeat ターンと通常の対話型チャットは作成しません。すべての Cron 実行、ACP 起動、サブエージェント起動、CLI エージェントコマンドは作成します。
</Note>
## 要約
## 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:
```
</Tab>
<Tab title="検査">
<Tab title="調査">
```bash
# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>
@ -83,7 +83,7 @@ x-i18n:
```
</Tab>
<Tab title="TaskFlow">
<Tab title="タスクフロー">
```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` |
<AccordionGroup>
<Accordion title="cron とメディアの通知デフォルト">
メインセッションの cron タスクは、デフォルトで `silent` 通知ポリシーを使用します。追跡用のレコードは作成しますが、通知は生成しません。分離された cron タスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より見えやすくなります。
<Accordion title="Cron とメディアの通知デフォルト">
メインセッションの 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 として元のエージェントセッションに戻されるため、エージェントがフォローアップメッセージを書き、完成したメディアを自分で添付できます。グループ/チャネルの完了は通常の可視返信ポリシーに従うため、ソース配信が必要な場合、エージェントはメッセージツールを使用します。
</Accordion>
<Accordion title="同時 video_generate ガードレール">
セッション backed の `video_generate` タスクがまだアクティブな間、このツールはガードレールとしても機能します。同じセッションで `video_generate` が繰り返し呼び出されると、2 つ目の同時生成を開始する代わりに、アクティブなタスクのステータスを返します。エージェント側から明示的に進行状況/ステータスを参照したい場合は `action: "status"` を使用してください。
セッションに支えられた `video_generate` タスクがまだアクティブな間、そのツールはガードレールとしても機能します。同じセッション内で繰り返された `video_generate` 呼び出しは、2 つ目の同時生成を開始する代わりに、アクティブなタスクステータスを返します。エージェント側から明示的な進捗/ステータス検索が必要な場合は、`action: "status"` を使用してください。
</Accordion>
<Accordion title="タスクを作成しないもの">
- Heartbeat ターン（メインセッション）。[Heartbeat](/ja-JP/gateway/heartbeat)を参照
- Heartbeat ターン — メインセッション。[Heartbeat](/ja-JP/gateway/heartbeat)を参照
- 通常の対話型チャットターン
- 直接の `/command` 応答
</Accordion>
</AccordionGroup>
## タスクのライフサイクル
## タスクライフサイクル
```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 で表示されます。
<Tip>
タスク完了は即時の Heartbeat wake をトリガーするため、結果をすばやく確認できます。次のスケジュール済み Heartbeat tick を待つ必要はありません。
タスク完了は即時の Heartbeat wake をトリガーするため、結果をすぐに確認できます。次に予定された Heartbeat tick を待つ必要はありません。
</Tip>
つまり、通常のワークフローはプッシュベースです。分離された作業を一度開始したら、完了時にランタイムが wake または通知するのを待ちます。デバッグ、介入、明示的な監査が必要な場合にのみタスク状態をポーリングしてください。
つまり、通常のワークフローはプッシュベースです。切り離された作業を一度開始し、その後は完了時にランタイムが wake または通知するのに任せます。デバッグ、介入、明示的な監査が必要な場合にのみタスク状態をポーリングしてください。
### 通知ポリシー
各タスクについて、どの程度通知を受けるかを制御します:
各タスクについて、どれだけ通知を受け取るかを制御します:
| ポリシー | 配信される内容 |
| ポリシー | 配信されるもの |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only`（デフォルト） | 終端状態（succeeded、failed など）のみ — **これがデフォルトです** |
| `state_changes` | すべての状態遷移と進行状況更新 |
| `silent` | 何も配信されません |
| `done_only` (デフォルト) | 終端状態 (succeeded、failed など) のみ — **これがデフォルトです** |
| `state_changes` | すべての状態遷移と進捗更新 |
| `silent` | 何も配信しない |
タスクの実行中にポリシーを変更します:
タスク実行中にポリシーを変更します:
```bash
openclaw tasks notify <lookup> state_changes
@ -199,7 +199,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
出力列: タスク ID、種類、ステータス、配信、実行 ID、子セッション、要約。
出力列: タスク ID、種類、ステータス、配信、実行 ID、子セッション、概要。
</Accordion>
<Accordion title="tasks show">
@ -207,7 +207,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
参照トークンには、タスク ID、実行 ID、またはセッションキーを指定できます。タイミング、配信状態、エラー、終端要約を含む完全なレコードを表示します。
検索トークンには、タスク ID、実行 ID、またはセッションキーを指定できます。タイミング、配信状態、エラー、終端概要を含む完全なレコードを表示します。
</Accordion>
<Accordion title="tasks cancel">
@ -215,7 +215,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
ACP とサブエージェントタスクでは、これにより子セッションが終了されます。CLI で追跡されるタスクでは、キャンセルはタスクレジストリに記録されます（別個の子ランタイムハンドルはありません）。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。
ACP とサブエージェントタスクでは、これは子セッションを終了します。CLI 追跡タスクでは、キャンセルはタスクレジストリに記録されます (個別の子ランタイムハンドルはありません)。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。
</Accordion>
<Accordion title="tasks notify">
@ -228,40 +228,40 @@ openclaw tasks notify <lookup> 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 | タイムライン違反（たとえば開始前に終了している） |
</Accordion>
<Accordion title="tasks メンテナンス">
<Accordion title="tasks maintenance">
```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 テキストにフォールバックし、タイムアウトのみのツール呼び出し実行は短い部分進捗サマリーに折りたたまれることがあります。終端の失敗実行は、取得された返信テキストを再生せずに失敗ステータスを通知します。
- クリーンアップ失敗が実際のタスク結果を隠すことはありません。
</Accordion>
<Accordion title="tasks flow list | show | cancel">
@ -271,97 +271,97 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks flow cancel <lookup>
```
個別のバックグラウンドタスクレコードではなく、それらをオーケストレーションする Task Flow に関心がある場合に使います。
個別のバックグラウンドタスクレコードではなく、オーケストレーションしている Task Flow を確認したい場合に使用します。
</Accordion>
</AccordionGroup>
## チャットタスクボード（`/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つのことを処理します。
<Steps>
<Step title="照合">
アクティブなタスクに、まだ権威あるランタイムの裏付けがあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使い、cron タスクはアクティブジョブの所有権を使い、チャットに裏付けられた CLI タスクは所有している実行コンテキストを使います。その裏付け状態が 5 分を超えて失われている場合、タスクは `lost` としてマークされます。
<Step title="Reconciliation">
アクティブなタスクに、権威あるランタイムの裏付けがまだあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使い、cron タスクはアクティブジョブ所有権を使い、チャットに裏付けられた CLI タスクは所有元の実行コンテキストを使います。その裏付け状態が5分を超えて消えている場合、タスクは `lost` としてマークされます。
</Step>
<Step title="ACP セッション修復">
終端または孤立した親所有のワンショット ACP セッションを閉じ、アクティブな会話バインディングが残っていない場合にのみ、古くなった終端または孤立した永続 ACP セッションを閉じます。
<Step title="ACP session repair">
終端または孤立した親所有の単発 ACP セッションを閉じます。また、アクティブな会話バインディングが残っていない場合に限り、古い終端または孤立した永続 ACP セッションを閉じます。
</Step>
<Step title="クリーンアップのスタンプ付け">
終端タスクに `cleanupAfter` タイムスタンプを設定します（endedAt + 7 日）。保持期間中、lost タスクは監査で引き続き警告として表示されます。`cleanupAfter` が期限切れになった後、またはクリーンアップメタデータが欠落している場合は、エラーになります。
<Step title="Cleanup stamping">
終端タスクに `cleanupAfter` タイムスタンプ（endedAt + 7日）を設定します。保持期間中、lost タスクは監査で引き続き警告として表示されます。`cleanupAfter` が期限切れになった後、またはクリーンアップメタデータがない場合は、エラーになります。
</Step>
<Step title="枝刈り">
<Step title="Pruning">
`cleanupAfter` 日付を過ぎたレコードを削除します。
</Step>
</Steps>
<Note>
**保持:** 終端タスクレコードは **7 日間** 保持され、その後自動的に枝刈りされます。設定は不要です。
**保持:** 終端タスクレコードは **7日間** 保持され、その後自動的に枝刈りされます。設定は不要です。
</Note>
## タスクと他システムの関係
## タスクと他のシステムの関係
<AccordionGroup>
<Accordion title="タスクと Task Flow">
[Task Flow](/ja-JP/automation/taskflow) は、バックグラウンドタスクの上位にあるフローオーケストレーション層です。1 つのフローは、そのライフタイムを通じて、管理同期モードまたはミラー同期モードを使って複数のタスクを調整できます。個別のタスクレコードを調べるには `openclaw tasks` を使い、オーケストレーションしているフローを調べるには `openclaw tasks flow` を使います。
<Accordion title="Tasks and Task Flow">
[Task Flow](/ja-JP/automation/taskflow) は、バックグラウンドタスクの上にあるフローオーケストレーション層です。1つのフローは、その存続期間中に管理モードまたはミラー同期モードを使って複数のタスクを調整できます。個別のタスクレコードを調べるには `openclaw tasks` を使い、オーケストレーションしているフローを調べるには `openclaw tasks flow` を使います。
詳細は [Task Flow](/ja-JP/automation/taskflow) を参照してください。
</Accordion>
<Accordion title="タスクと cron">
cron ジョブの**定義**は `~/.openclaw/cron/jobs.json` にあり、ランタイム実行状態はその隣の `~/.openclaw/cron/jobs-state.json` にあります。cron 実行は**すべて**タスクレコードを作成します。メインセッションと分離セッションの両方です。メインセッションの cron タスクはデフォルトで `silent` 通知ポリシーになっているため、通知を生成せずに追跡されます。
<Accordion title="Tasks and cron">
cron ジョブの**定義**は `~/.openclaw/cron/jobs.json` にあります。ランタイム実行状態は、その横の `~/.openclaw/cron/jobs-state.json` にあります。**すべての** cron 実行はタスクレコードを作成します。メインセッションと分離セッションの両方です。メインセッションの cron タスクはデフォルトで `silent` 通知ポリシーを使うため、通知を生成せずに追跡されます。
[Cron ジョブ](/ja-JP/automation/cron-jobs) を参照してください。
</Accordion>
<Accordion title="タスクと Heartbeat">
Heartbeat の実行はメインセッションのターンです。タスクレコードは作成しません。タスクが完了すると、結果をすぐに確認できるように Heartbeat ウェイクをトリガーできます。
<Accordion title="Tasks and heartbeat">
Heartbeat 実行はメインセッションのターンです。タスクレコードは作成しません。タスクが完了すると、Heartbeat ウェイクをトリガーして、結果をすばやく確認できるようにできます。
[Heartbeat](/ja-JP/gateway/heartbeat) を参照してください。
</Accordion>
<Accordion title="タスクとセッション">
タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（それを開始した人）を参照することがあります。セッションは会話コンテキストであり、タスクはその上にあるアクティビティ追跡です。
<Accordion title="Tasks and sessions">
タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（開始した主体）を参照する場合があります。セッションは会話コンテキストであり、タスクはその上にあるアクティビティ追跡です。
</Accordion>
<Accordion title="タスクとエージェント実行">
タスクの `runId` は、作業を行っているエージェント実行にリンクします。エージェントのライフサイクルイベント（開始、終了、エラー）はタスクステータスを自動的に更新するため、ライフサイクルを手動で管理する必要はありません。
<Accordion title="Tasks and agent runs">
タスクの `runId` は、作業を行うエージェント実行にリンクします。エージェントのライフサイクルイベント（開始、終了、エラー）はタスクステータスを自動的に更新します。ライフサイクルを手動で管理する必要はありません。
</Accordion>
</AccordionGroup>
@ -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) — タスクの上にあるフローオーケストレーション

712
docs/ja-JP/channels/slack.md
View File

File diff suppressed because it is too large Load Diff

382
docs/ja-JP/ci.md
View File

@ -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=<branch-or-sha>
| ランナー | ジョブ |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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/<tested-ref>/<run-id>-<attempt>/<lane>/` 配下の `openclaw/clawgrit-reports` にコミットします。現在のテスト対象 ref ポインターは `openclaw-performance/<tested-ref>/latest-<lane>.json` として書き込まれます。
すべてのレーンは GitHub アーティファクトをアップロードします。`CLAWGRIT_REPORTS_TOKEN` が構成されている場合、ワークフローは `report.json`、`report.md`、バンドル、`index.md`、ソースプローブアーティファクトも `openclaw/clawgrit-reports` の `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/` 配下にコミットします。現在のテスト対象 ref ポインターは `openclaw-performance/<tested-ref>/latest-<lane>.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=<sha>` ではなくヘルパーを使います:
移り変わりの速いブランチ上で固定コミットの証明を行う場合は、`gh workflow run ... --ref main -f ref=<sha>` の代わりにヘルパーを使います。
```bash
pnpm ci:full-release --sha <full-sha>
```
GitHub ワークフローディスパッチ ref はブランチまたはタグである必要があり、生の commit SHA ではいけません。このヘルパーはターゲット SHA に一時的な `release-ci/<sha>-...` ブランチを push し、その固定 ref から `Full Release Validation` をディスパッチし、すべての子ワークフローの `headSha` がターゲットと一致することを検証し、実行が完了したら一時ブランチを削除します。包括検証器は、いずれかの子ワークフローが異なる SHA で実行された場合にも失敗します。
GitHub ワークフローディスパッチ ref はブランチまたはタグである必要があり、生のコミット SHA は使えません。このヘルパーは、ターゲット SHA に一時的な `release-ci/<sha>-...` ブランチを 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:<sha>` イメージを使用します。ライブリリースワークフローはそのイメージを一度だけビルドしてプッシュし、その後 Docker ライブモデル、プロバイダー分割 Gateway、CLI バックエンド、ACP バインド、Codex ハーネスの各シャードが `OPENCLAW_SKIP_DOCKER_BUILD=1` で実行されます。Gateway Docker シャードには、ワークフロージョブのタイムアウトより短い明示的なスクリプトレベルの `timeout` 上限があり、停止したコンテナやクリーンアップパスがリリースチェック予算全体を消費せず、早く失敗するようにしています。これらのシャードが完全なソース Docker ターゲットを個別に再ビルドしている場合、そのリリース実行は誤設定されており、重複したイメージビルドで実時間を浪費します。
Docker ベースのライブモデル/バックエンドシャードは、選択されたコミットごとに別の共有 `ghcr.io/openclaw/openclaw-live-test:<sha>` イメージを使用します。ライブリリースワークフローは、そのイメージを一度ビルドしてプッシュし、その後 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 <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
@ -368,46 +368,46 @@ pnpm test:docker:timings <summary> # 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 <tbx_id>
```
同じハイドレート済みボックスで複数のコマンドを意図的に実行する必要がある場合にのみ、再利用を使います。
同じハイドレート済みボックスで複数のコマンドが意図的に必要な場合にのみ、再利用を使う。
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>
```
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 <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
blacksmith testbox stop --id <tbx_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 <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.crabbox.yaml` は、所有クラウドレーンのプロバイダー、同期、GitHub Actions ハイドレーションのデフォルトを管理します。ローカル `.git` は除外されるため、ハイドレートされた Actions チェックアウトは、メンテナーのローカルリモートやオブジェクトストアを同期するのではなく、独自のリモート Git メタデータを保持します。また、転送されるべきでないローカル実行時/ビルド成果物も除外されます。`.github/workflows/crabbox-hydrate.yml` は、チェックアウト、Node/pnpm セットアップ、`origin/main` フェッチ、および所有クラウドの `crabbox run --id <cbx_id>` コマンド向けの非シークレット環境の引き渡しを管理します。
`.crabbox.yaml` は、所有クラウドレーンのプロバイダー、同期、GitHub Actions ハイドレーションのデフォルトを所有する。これはローカルの `.git` を除外するため、ハイドレートされた Actions チェックアウトはメンテナーローカルのリモートとオブジェクトストアを同期する代わりに、自身のリモート Git メタデータを保持する。また、転送してはならないローカルのランタイム/ビルド成果物も除外する。`.github/workflows/crabbox-hydrate.yml` は、所有クラウドの `crabbox run --id <cbx_id>` コマンドに対するチェックアウト、Node/pnpm セットアップ、`origin/main` フェッチ、非シークレット環境の引き渡しを所有する。
## 関連
- [インストール概要](/ja-JP/install)
- [開発チャネル](/ja-JP/install/development-channels)
- [開発チャンネル](/ja-JP/install/development-channels)

30
docs/ja-JP/cli/dashboard.md
View File

@ -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 と明示的な修復手順を表示します。
## 関連

74
docs/ja-JP/cli/doctor.md
View File

@ -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.<timestamp>` としてアーカイブするには対話的な確認が必要です。`--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.<id>` エントリを無効化し、その無効な `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.<provider>` に自動移行します。
- `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.<skill>.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.<id>` エントリを無効化し、その無効な `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.<provider>` に自動マイグレーションします。
- `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.<skill>.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

263
docs/ja-JP/cli/gateway.md
View File

@ -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 …` 配下にあります。
<CardGroup cols={3}>
<Card title="Bonjour 検出" href="/ja-JP/gateway/bonjour">
ローカル mDNS + 広域 DNS-SD のセットアップ。
ローカル mDNS + 広域 DNS-SD の設定。
</Card>
<Card title="検出の概要" href="/ja-JP/gateway/discovery">
OpenClaw が Gateway を通知し、見つける方法。
OpenClaw が Gateway を告知し、見つける仕組み。
</Card>
<Card title="設定" href="/ja-JP/gateway/configuration">
トップレベルの Gateway 設定キー。
@ -31,7 +31,7 @@ Gateway は OpenClaw の WebSocket サーバー（channels、nodes、sessions、
## Gateway を実行する
ローカル Gateway プロセスを実行します。
ローカル Gateway プロセスを実行します:
```bash
openclaw gateway
@ -46,11 +46,11 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="起動時の動作">
- デフォルトでは、`~/.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 モード入力でラップしている場合は、終了前に端末を復元してください。
</Accordion>
</AccordionGroup>
@ -58,58 +58,58 @@ openclaw gateway run
### オプション
<ParamField path="--port <port>" type="number">
WebSocket ポート（デフォルトは設定/env から取得され、通常は `18789`）。
WebSocket ポート（デフォルトは設定/環境変数から取得され、通常は `18789`）。
</ParamField>
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
リスナーバインドモード。
リスナーのバインドモード。
</ParamField>
<ParamField path="--auth <token|password>" type="string">
認証モードのオーバーライド。
認証モードの上書き。
</ParamField>
<ParamField path="--token <token>" type="string">
トークンのオーバーライド（プロセスに `OPENCLAW_GATEWAY_TOKEN` も設定します）。
トークンの上書き（プロセスに `OPENCLAW_GATEWAY_TOKEN` も設定します）。
</ParamField>
<ParamField path="--password <password>" type="string">
パスワードのオーバーライド。
パスワードの上書き。
</ParamField>
<ParamField path="--password-file <path>" type="string">
ファイルから gateway パスワードを読み取ります。
Gateway パスワードをファイルから読み取ります。
</ParamField>
<ParamField path="--tailscale <off|serve|funnel>" type="string">
Gateway を Tailscale 経由で公開します。
Tailscale 経由で Gateway を公開します。
</ParamField>
<ParamField path="--tailscale-reset-on-exit" type="boolean">
シャットダウン時に Tailscale serve/funnel 設定をリセットします。
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
設定内に `gateway.mode=local` がなくても gateway の起動を許可します。アドホック/開発用ブートストラップのために起動ガードをバイパスするだけで、設定ファイルの書き込みや修復は行いません。
設定内に `gateway.mode=local` がなくても Gateway の起動を許可します。アドホック/開発用ブートストラップのためだけに起動ガードをバイパスします。設定ファイルの書き込みや修復は行いません。
</ParamField>
<ParamField path="--dev" type="boolean">
見つからない場合は開発用設定 + ワークスペースを作成します（BOOTSTRAP.md をスキップします）。
存在しない場合に開発用設定 + ワークスペースを作成します（BOOTSTRAP.md をスキップします）。
</ParamField>
<ParamField path="--reset" type="boolean">
開発用設定 + 認証情報 + セッション + ワークスペースをリセットします（`--dev` が必要）。
開発用設定 + 資格情報 + セッション + ワークスペースをリセットします（`--dev` が必要）。
</ParamField>
<ParamField path="--force" type="boolean">
起動前に、選択したポート上の既存リスナーを強制終了します。
起動前に、選択されたポート上の既存リスナーをすべて終了します。
</ParamField>
<ParamField path="--verbose" type="boolean">
詳細ログ。
</ParamField>
<ParamField path="--cli-backend-logs" type="boolean">
コンソールには CLI バックエンドログのみを表示します（stdout/stderr も有効化します）。
コンソールには CLI バックエンドログのみを表示します（stdout/stderr も有効にします）。
</ParamField>
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
Websocket ログスタイル。
WebSocket ログの形式。
</ParamField>
<ParamField path="--compact" type="boolean">
`--ws-log compact` のエイリアス。
</ParamField>
<ParamField path="--raw-stream" type="boolean">
生のモデルストリームイベントを jsonl にログ記録します。
生のモデルストリームイベントを jsonl に記録します。
</ParamField>
<ParamField path="--raw-stream-path <path>" type="string">
生ストリーム jsonl パス。
生ストリーム jsonl のパス。
</ParamField>
## 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` を使用してください。
<Warning>
インラインの `--password` はローカルのプロセス一覧に露出する可能性があります。`--password-file`、env、または SecretRef で裏付けられた `gateway.auth.password` を優先してください。
インラインの `--password` は、ローカルプロセス一覧に露出する可能性があります。`--password-file`、環境変数、または SecretRef に基づく `gateway.auth.password` を優先してください。
</Warning>
### 起動プロファイリング
- `OPENCLAW_GATEWAY_STARTUP_TRACE=1` を設定すると、Gateway 起動時のフェーズタイミングをログ記録します。フェーズごとの `eventLoopMax` 遅延と、installed-index、manifest registry、startup planning、owner-map 作業の Plugin ルックアップテーブルタイミングを含みます。
- `OPENCLAW_DIAGNOSTICS=timeline` と `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<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=<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
<Tabs>
<Tab title="出力モード">
- デフォルト: 人間が読める形式（TTY では色付き）。
- デフォルト: 人間が読みやすい形式（TTY では色付き）。
- `--json`: 機械可読 JSON（スタイル/スピナーなし）。
- `--no-color`（または `NO_COLOR=1`）: 人間向けレイアウトを維持したまま ANSI を無効化します。
- `--no-color`（または `NO_COLOR=1`）: 人間向けレイアウトを維持しながら ANSI を無効化します。
</Tab>
<Tab title="共有オプション">
<Tab title="共通オプション">
- `--url <url>`: Gateway WebSocket URL。
- `--token <token>`: Gateway トークン。
- `--password <password>`: Gateway パスワード。
- `--timeout <ms>`: タイムアウト/予算（コマンドにより異なります）。
- `--timeout <ms>`: タイムアウト/予算（コマンドごとに異なります）。
- `--expect-final`: 「final」レスポンスを待ちます（エージェント呼び出し）。
</Tab>
</Tabs>
<Note>
`--url` を設定すると、CLI は設定または環境認証情報にフォールバックしません。`--token` または `--password` を明示的に渡してください。明示的な認証情報がない場合はエラーです。
`--url` を設定すると、CLI は設定や環境変数の資格情報にフォールバックしません。`--token` または `--password` を明示的に渡してください。明示的な資格情報がない場合はエラーです。
</Note>
### `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`）。
</ParamField>
<ParamField path="--type <type>" type="string">
`payload.large` や `diagnostic.memory.pressure` などの診断イベントタイプでフィルターします。
`payload.large` や `diagnostic.memory.pressure` など、診断イベントタイプで絞り込みます。
</ParamField>
<ParamField path="--since-seq <seq>" type="number">
診断シーケンス番号より後のイベントのみを含めます。
</ParamField>
<ParamField path="--bundle [path]" type="string">
実行中の Gateway を呼び出す代わりに、永続化された stability bundle を読み取ります。状態ディレクトリ下の最新 bundle には `--bundle latest`（または単に `--bundle`）を使用するか、bundle JSON パスを直接渡します。
実行中の Gateway を呼び出す代わりに、永続化された安定性バンドルを読み取ります。状態ディレクトリ配下の最新バンドルには `--bundle latest`（または単に `--bundle`）を使用するか、バンドル JSON パスを直接渡します。
</ParamField>
<ParamField path="--export" type="boolean">
stability 詳細を出力する代わりに、共有可能なサポート診断 zip を書き込みます。
安定性の詳細を出力する代わりに、共有可能なサポート診断 zip を書き込みます。
</ParamField>
<ParamField path="--output <path>" type="string">
`--export` の出力パス。
</ParamField>
<AccordionGroup>
<Accordion title="プライバシーと bundle の動作">
- レコードは運用メタデータを保持します。イベント名、件数、バイトサイズ、メモリ測定値、キュー/セッション状態、チャンネル/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 出力に適用されます。
<Accordion title="プライバシーとバンドルの動作">
- レコードは運用メタデータを保持します。イベント名、件数、バイトサイズ、メモリ読み取り値、キュー/セッション状態、チャネル/Plugin 名、編集済みのセッション概要です。チャットテキスト、Webhook 本文、ツール出力、生のリクエスト本文またはレスポンス本文、トークン、Cookie、シークレット値、ホスト名、生のセッション ID は保持しません。レコーダーを完全に無効化するには `diagnostics.enabled: false` を設定します。
- 致命的な Gateway 終了、シャットダウンタイムアウト、再起動時の起動失敗では、レコーダーにイベントがある場合、OpenClaw は同じ診断スナップショットを `~/.openclaw/logs/stability/openclaw-stability-*.json` に書き込みます。最新バンドルは `openclaw gateway stability --bundle latest` で確認できます。`--limit`、`--type`、`--since-seq` もバンドル出力に適用されます。
</Accordion>
</AccordionGroup>
### `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
```
<ParamField path="--output <path>" type="string">
出力 zip パス。デフォルトでは状態ディレクトリ下のサポートエクスポートです。
出力 zip パス。デフォルトでは、状態ディレクトリ配下のサポートエクスポートです。
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
含めるサニタイズ済みログ行の最大数。
</ParamField>
<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
調査するログバイトの最大数。
検査するログバイト数の最大値。
</ParamField>
<ParamField path="--url <url>" type="string">
health スナップショット用の Gateway WebSocket URL。
ヘルススナップショット用の Gateway WebSocket URL。
</ParamField>
<ParamField path="--token <token>" type="string">
health スナップショット用の Gateway トークン。
ヘルススナップショット用の Gateway トークン。
</ParamField>
<ParamField path="--password <password>" type="string">
health スナップショット用の Gateway パスワード。
ヘルススナップショット用の Gateway パスワード。
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="3000">
status/health スナップショットのタイムアウト。
ステータス/ヘルススナップショットのタイムアウト。
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
永続化された stability bundle の検索をスキップします。
永続化された安定性バンドルの検索をスキップします。
</ParamField>
<ParamField path="--json" type="boolean">
書き込まれたパス、サイズ、manifest を JSON として出力します。
書き込まれたパス、サイズ、マニフェストを JSON として出力します。
</ParamField>
エクスポートには、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
```
<ParamField path="--url <url>" type="string">
明示的なプローブ対象を追加します。設定済みのリモート + localhost も引き続きプローブされます。
明示的なプローブ対象を追加します。設定済みのリモートと localhost も引き続きプローブされます。
</ParamField>
<ParamField path="--token <token>" type="string">
プローブ用のトークン認証。
@ -283,32 +283,32 @@ openclaw gateway status --require-rpc
プローブのタイムアウト。
</ParamField>
<ParamField path="--no-probe" type="boolean">
接続プローブをスキップします（サービスのみの表示）。
接続性プローブをスキップします（サービスのみの表示）。
</ParamField>
<ParamField path="--deep" type="boolean">
システムレベルのサービスもスキャンします。
</ParamField>
<ParamField path="--require-rpc" type="boolean">
デフォルトの接続プローブを読み取りプローブにアップグレードし、その読み取りプローブが失敗した場合はゼロ以外で終了します。`--no-probe` と組み合わせることはできません。
既定の接続性プローブを読み取りプローブに昇格し、その読み取りプローブが失敗した場合はゼロ以外で終了します。`--no-probe` と組み合わせることはできません。
</ParamField>
<AccordionGroup>
<Accordion title="ステータスの意味">
- ローカル 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 とサービスの設定パス/有効性のスナップショットが含まれます。
</Accordion>
<Accordion title="Linux systemd の認証ずれチェック">
- 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`、またはモード未設定でパスワードが優先され、勝てるトークン候補がない場合）、トークンずれチェックは設定トークンの解決をスキップします。
</Accordion>
</AccordionGroup>
@ -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`
<Note>
複数の Gateway に到達できる場合、それらをすべて表示します。分離されたプロファイル/ポート（例: レスキューボット）を使用する場合、複数 Gateway はサポートされますが、ほとんどのインストールでは引き続き単一の Gateway を実行します。
複数の Gateway に到達できる場合は、それらすべてを出力します。分離されたプロファイル/ポート（例: レスキューボット）を使用する場合、複数の Gateway はサポートされますが、ほとんどのインストールでは単一の Gateway を実行します。
</Note>
```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 つもない場合にのみ、終了コードはゼロ以外になります。
</Accordion>
<Accordion title="JSON 出力">
トップレベル:
- `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`: その対象に対して表面化された認証機能の分類。
</Accordion>
<Accordion title="一般的な警告コード">
- `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` が不足していたため読み取りプローブが制限されました。
</Accordion>
</AccordionGroup>
#### SSH 経由のリモート（Mac アプリ同等）
#### SSH 経由のリモート（Mac アプリとの同等性）
macOS アプリの「Remote over SSH」モードはローカルポートフォワードを使用するため、リモート Gateway（ループバックのみにバインドされている場合があります）が `ws://127.0.0.1:<port>` で到達可能になります。
macOS アプリの「Remote over SSH」モードはローカルポート転送を使用するため、リモート Gateway（ループバックのみにバインドされている場合があります）に `ws://127.0.0.1:<port>` で到達できるようになります。
CLI での同等操作:
@ -390,16 +390,16 @@ openclaw gateway probe --ssh user@gateway-host
```
<ParamField path="--ssh <target>" type="string">
`user@host` または `user@host:port`（port のデフォルトは `22`）。
`user@host` または `user@host:port`（ポートの既定値は `22`）。
</ParamField>
<ParamField path="--ssh-identity <path>" type="string">
ID ファイル。
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
解決済み検出エンドポイント（`local.` に設定済みワイドエリアドメインを加えたもの、存在する場合）から、最初に検出された Gateway ホストを SSH 対象として選択します。TXT のみのヒントは無視されます。
解決済みの検出エンドポイント（`local.` に加え、設定済みの広域ドメインがあればそれも）から、最初に検出された Gateway ホストを SSH 対象として選択します。TXT のみのヒントは無視されます。
</ParamField>
設定（任意、デフォルトとして使用）:
設定（省略可能、既定値として使用）:
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
@ -429,10 +429,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
タイムアウト予算。
</ParamField>
<ParamField path="--expect-final" type="boolean">
主に、最終ペイロードの前に中間イベントをストリームするエージェント形式の RPC 用です。
主に、最終ペイロードの前に中間イベントをストリーミングするエージェント形式の RPC 向けです。
</ParamField>
<ParamField path="--json" type="boolean">
機械可読な JSON 出力。
機械可読の JSON 出力。
</ParamField>
<Note>
@ -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
<AccordionGroup>
<Accordion title="コマンドオプション">
- `gateway status`: `--url`、`--token`、`--password`、`--timeout`、`--no-probe`、`--require-rpc`、`--deep`、`--json`
- `gateway install`: `--port`、`--runtime <node|bun>`、`--token`、`--wrapper <path>`、`--force`、`--json`
- `gateway restart`: `--force`、`--wait <duration>`、`--json`
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
- `gateway uninstall|start|stop`: `--json`
</Accordion>
<Accordion title="ライフサイクルの動作">
- 管理対象サービスを再起動するには `gateway restart` を使用します。再起動の代替として `gateway stop` と `gateway start` を連鎖させないでください。macOS では、`gateway stop` は停止前に LaunchAgent を意図的に無効化します。
<Accordion title="ライフサイクル動作">
- 管理対象サービスを再起動するには `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` を受け付けます。
</Accordion>
<Accordion title="インストール時の認証と SecretRefs">
- トークン認証がトークンを必要とし、`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 が明示的に設定されるまでインストールはブロックされます。
<Accordion title="インストール時の認証とSecretRefs">
- トークン認証でトークンが必要で、`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` が未設定の場合、モードが明示的に設定されるまでインストールはブロックされます。
</Accordion>
</AccordionGroup>
@ -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
```
<ParamField path="--timeout <ms>" type="number" default="2000">
コマンドごとのタイムアウト (ブラウズ/解決)。
コマンドごとのタイムアウト（参照/解決）。
</ParamField>
<ParamField path="--json" type="boolean">
機械可読の出力 (スタイルやスピナーも無効化します)。
機械可読な出力（スタイル設定/スピナーも無効化します）。
</ParamField>
例:
@ -544,9 +545,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- 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` はそこでも任意のままです。
</Note>

217
docs/ja-JP/cli/plugins.md
View File

@ -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、フックパック、互換バンドルを管理します。
<CardGroup cols={2}>
<Card title="Plugin システム" href="/ja-JP/tools/plugin">
プラグインのインストール、有効化、トラブルシューティングに関するエンドユーザー向けガイド。
<Card title="Pluginシステム" href="/ja-JP/tools/plugin">
Pluginのインストール、有効化、トラブルシューティングのエンドユーザー向けガイド。
</Card>
<Card title="プラグインの管理" href="/ja-JP/plugins/manage-plugins">
インストール、一覧表示、更新、アンインストール、公開の簡単な例。
<Card title="Pluginを管理" href="/ja-JP/plugins/manage-plugins">
インストール、一覧表示、更新、アンインストール、公開のクイック例。
</Card>
<Card title="Plugin バンドル" href="/ja-JP/plugins/bundles">
<Card title="Pluginバンドル" href="/ja-JP/plugins/bundles">
バンドル互換性モデル。
</Card>
<Card title="Plugin マニフェスト" href="/ja-JP/plugins/manifest">
<Card title="Pluginマニフェスト" href="/ja-JP/plugins/manifest">
マニフェストフィールドと設定スキーマ。
</Card>
<Card title="セキュリティ" href="/ja-JP/gateway/security">
プラグインインストールのセキュリティ強化。
Pluginインストールのセキュリティ強化。
</Card>
</CardGroup>
@ -63,15 +63,15 @@ openclaw plugins marketplace list <marketplace> --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)を参照してください。
<Note>
バンドル済みプラグインは 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`）と、検出されたバンドル機能も表示されます。
</Note>
### インストール
@ -93,105 +93,108 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
接頭辞なしのパッケージ名は、ローンチ切り替え期間中はデフォルトで npm からインストールされます。ClawHub には `clawhub:<package>` を使用してください。プラグインのインストールはコードの実行と同じように扱ってください。ピン留めされたバージョンを優先してください。
裸のパッケージ名は、ローンチ移行期間中はデフォルトでnpmからインストールされます。ClawHubには `clawhub:<package>` を使用してください。Pluginのインストールは、コードを実行するものとして扱ってください。固定バージョンを推奨します。
</Warning>
`plugins search` は ClawHub に対してインストール可能なプラグインパッケージを問い合わせ、インストール可能なパッケージ名を出力します。検索対象はコードプラグインとバンドルプラグインのパッケージであり、Skills ではありません。ClawHub Skills には `openclaw skills search` を使用してください。
`plugins search` は、インストール可能なPluginパッケージをClawHubに問い合わせ、
インストール可能なパッケージ名を出力します。検索対象はコードPluginとバンドルPluginのパッケージであり、
Skillsではありません。ClawHub Skillsには `openclaw skills search` を使用してください。
<Note>
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` にフォールバックします。
</Note>
<AccordionGroup>
<Accordion title="設定インクルードと無効な設定の修復">
`plugins` セクションが単一ファイルの `$include` を基にしている場合、`plugins install/update/enable/disable/uninstall` はそのインクルード先ファイルに書き込み、`openclaw.json` は変更しません。ルートのインクルード、インクルード配列、兄弟オーバーライドを伴うインクルードは、平坦化される代わりに安全側に失敗します。サポートされる形については、[設定インクルード](/ja-JP/gateway/configuration)を参照してください。
<Accordion title="設定includeと無効な設定の修復">
`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復旧経路です。
</Accordion>
<Accordion title="--force と再インストール、更新の違い">
`--force` は既存のインストール先を再利用し、すでにインストールされているプラグインまたはフックパックをその場で上書きします。同じ id を新しいローカルパス、アーカイブ、ClawHub パッケージ、または npm アーティファクトから意図的に再インストールするときに使用します。すでに追跡されている npm プラグインの通常のアップグレードには、`openclaw plugins update <id-or-npm-spec>` を優先してください。
<Accordion title="--forceと再インストール対更新">
`--force` は既存のインストール先を再利用し、すでにインストール済みのPluginまたはフックパックをその場で上書きします。同じidを新しいローカルパス、アーカイブ、ClawHubパッケージ、またはnpmアーティファクトから意図的に再インストールする場合に使用します。すでに追跡されているnpm Pluginの通常のアップグレードには、`openclaw plugins update <id-or-npm-spec>` を推奨します。
すでにインストール済みのプラグイン id に対して `plugins install` を実行すると、OpenClaw は停止し、通常のアップグレードには `plugins update <id-or-npm-spec>` を案内し、現在のインストールを別のソースから本当に上書きしたい場合には `plugins install <package> --force` を案内します。
すでにインストール済みのPlugin idに対して `plugins install` を実行すると、OpenClawは停止し、通常のアップグレードには `plugins update <id-or-npm-spec>` を、現在のインストールを別のソースから本当に上書きする場合には `plugins install <package> --force` を案内します。
</Accordion>
<Accordion title="--pin のスコープ">
`--pin` は npm インストールのみに適用されます。`git:` インストールではサポートされていません。ソースをピン留めしたい場合は、`git:github.com/acme/plugin@v1.2.3` のような明示的な git 参照を使用してください。`--marketplace` でもサポートされていません。マーケットプレイスインストールでは、npm 指定ではなくマーケットプレイスソースメタデータを永続化するためです。
<Accordion title="--pinのスコープ">
`--pin` はnpmインストールにのみ適用されます。`git:` インストールではサポートされません。固定ソースが必要な場合は、`git:github.com/acme/plugin@v1.2.3` のような明示的なgit refを使用してください。`--marketplace` でもサポートされません。marketplaceインストールはnpm specではなく、marketplaceソースメタデータを保持するためです。
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--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)の公開者向け手順を使用してください。
</Accordion>
<Accordion title="フックパックと npm 指定">
`plugins install` は、`package.json` で `openclaw.hooks` を公開するフックパックのインストール窓口でもあります。フィルタリングされたフックの表示とフックごとの有効化には `openclaw hooks` を使用し、パッケージインストールには使用しません。
<Accordion title="フックパックとnpm spec">
`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:<package>` を使用します。接頭辞なしのパッケージ指定も、ローンチ切り替え期間中は npm から直接インストールされます。
npm解決を明示したい場合は `npm:<package>` を使用してください。裸のパッケージ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`）を使用してください。
</Accordion>
<Accordion title="Git リポジトリ">
git リポジトリから直接インストールするには `git:<repo>` を使用します。サポートされる形式には、`git:github.com/owner/repo`、`git:owner/repo`、完全な `https://`、`ssh://`、`git://`、`file://`、および `git@host:owner/repo.git` のクローン URL が含まれます。インストール前にブランチ、タグ、またはコミットをチェックアウトするには、`@<ref>` または `#<ref>` を追加します。
<Accordion title="Gitリポジトリ">
gitリポジトリから直接インストールするには `git:<repo>` を使用します。サポートされる形式には、`git:github.com/owner/repo`、`git:owner/repo`、完全な `https://`、`ssh://`、`git://`、`file://`、および `git@host:owner/repo.git` クローンURLが含まれます。インストール前にブランチ、タグ、またはコミットをチェックアウトするには、`@<ref>` または `#<ref>` を追加します。
Git インストールでは一時ディレクトリにクローンし、要求された参照がある場合はそれをチェックアウトしてから、通常のプラグインディレクトリインストーラーを使用します。つまり、マニフェスト検証、危険コードスキャン、パッケージマネージャーによるインストール処理、インストール記録は npm インストールと同様に動作します。記録された git インストールには、ソース URL/参照に加えて解決済みコミットが含まれるため、`openclaw plugins update` は後でソースを再解決できます。
Gitインストールは一時ディレクトリにクローンし、指定されたrefがある場合はそれをチェックアウトしてから、通常のPluginディレクトリインストーラーを使用します。つまり、マニフェスト検証、危険コードスキャン、パッケージマネージャーのインストール作業、インストールレコードはnpmインストールと同じように動作します。記録されたgitインストールには、ソースURL/refと解決済みコミットが含まれるため、後で `openclaw plugins update` がソースを再解決できます。
git からインストールした後は、`openclaw plugins inspect <id> --runtime --json` を使用して、gateway メソッドや CLI コマンドなどのランタイム登録を検証します。プラグインが `api.registerCli` で CLI ルートを登録した場合は、そのコマンドを OpenClaw ルート CLI から直接実行します。たとえば `openclaw demo-plugin ping` です。
gitからインストールした後、GatewayメソッドやCLIコマンドなどのランタイム登録を確認するには、`openclaw plugins inspect <id> --runtime --json` を使用します。Pluginが `api.registerCli` でCLIルートを登録した場合は、たとえば `openclaw demo-plugin ping` のように、そのコマンドをOpenClawルートCLI経由で直接実行します。
</Accordion>
<Accordion title="アーカイブ">
サポートされるアーカイブ: `.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インストールもサポートされています。
</Accordion>
</AccordionGroup>
ClawHub インストールでは、明示的な `clawhub:<package>` ロケーターを使用します。
ClawHubインストールは、明示的な `clawhub:<package>` ロケーターを使用します。
```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 <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
マーケットプレイスソースを明示的に渡したい場合は `--marketplace` を使用します。
marketplaceソースを明示的に渡したい場合は、`--marketplace` を使用します。
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -203,26 +206,26 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
<Tabs>
<Tab title="マーケットプレイスソース">
- `~/.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
</Tab>
<Tab title="リモートマーケットプレイスのルール">
GitHub または git から読み込まれるリモートマーケットプレイスでは、plugin エントリはクローンされたマーケットプレイスリポジトリ内に留まる必要があります。OpenClaw はそのリポジトリからの相対パスソースを受け入れ、リモートマニフェスト内の HTTP(S)、絶対パス、git、GitHub、およびその他の非パス plugin ソースを拒否します。
GitHub または git から読み込まれるリモートマーケットプレイスでは、Plugin エントリはクローンされたマーケットプレイスリポジトリ内に留まる必要があります。OpenClaw はそのリポジトリからの相対パスソースを受け入れ、リモートマニフェスト内の HTTP(S)、絶対パス、git、GitHub、その他の非パス Plugin ソースを拒否します。
</Tab>
</Tabs>
ローカルパスとアーカイブについて、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`）
<Note>
互換バンドルは通常の 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 ディレクトリがサポートされています。その他の検出済みバンドル機能は診断/情報に表示されますが、まだランタイム実行には接続されていません。
</Note>
### 一覧
@ -238,30 +241,30 @@ openclaw plugins search <query> --json
```
<ParamField path="--enabled" type="boolean">
有効化された plugins のみを表示します。
有効化されている Plugin のみを表示します。
</ParamField>
<ParamField path="--verbose" type="boolean">
テーブル表示から、ソース/出所/バージョン/有効化メタデータを含む plugin ごとの詳細行に切り替えます。
テーブル表示から、ソース/出所/バージョン/アクティベーションメタデータを含む Plugin ごとの詳細行に切り替えます。
</ParamField>
<ParamField path="--json" type="boolean">
機械可読のインベントリに加えて、レジストリ diagnostics とパッケージ依存関係のインストール状態を出力します。
機械可読のインベントリに加えて、レジストリ診断とパッケージ依存関係のインストール状態を出力します。
</ParamField>
<Note>
`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 ランタイムコードのインポート、パッケージマネージャーの実行、欠落した依存関係の修復は行いません。
</Note>
`plugins search` はリモート ClawHub カタログ検索です。ローカル状態の検査、設定の変更、パッケージのインストール、plugin ランタイムコードの読み込みは行いません。検索結果には、ClawHub パッケージ名、ファミリー、チャンネル、バージョン、概要、および `openclaw plugins install clawhub:<package>` などのインストールヒントが含まれます。
`plugins search` はリモートの ClawHub カタログ検索です。ローカル状態の検査、config の変更、パッケージのインストール、Plugin ランタイムコードの読み込みは行いません。検索結果には、ClawHub パッケージ名、ファミリー、チャネル、バージョン、概要、および `openclaw plugins install clawhub:<package>` のようなインストールヒントが含まれます。
パッケージ化された 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 <id> --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.<id>.hooks.allowConversationAccess=true` が必要です。
- `openclaw plugins inspect <id> --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.<id>.hooks.allowConversationAccess=true` が必要です。
ローカルディレクトリのコピーを避けるには `--link` を使います（`plugins.load.paths` に追加されます）。
@ -270,16 +273,16 @@ openclaw plugins install -l ./my-plugin
```
<Note>
リンクされたインストールは管理対象インストール先にコピーする代わりにソースパスを再利用するため、`--force` は `--link` と併用できません。
リンクインストールは管理対象のインストール先へコピーする代わりにソースパスを再利用するため、`--force` は `--link` と併用できません。
npm インストールで `--pin` を使うと、デフォルト動作はピン留めなしのまま、解決された正確な spec（`name@version`）を管理対象 plugin インデックスに保存します。
npm インストールで `--pin` を使うと、デフォルト動作をピン留めなしのままにしつつ、解決された正確な spec（`name@version`）を管理対象 Plugin インデックスに保存できます。
</Note>
### 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 <id> --dry-run
openclaw plugins uninstall <id> --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` にリセットされます。
<Note>
`--keep-config` は `--keep-files` の非推奨エイリアスとしてサポートされています。
`--keep-config` は、非推奨の `--keep-files` エイリアスとしてサポートされています。
</Note>
### 更新
@ -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 インストールに適用されます。
<AccordionGroup>
<Accordion title="plugin id と npm spec の解決">
plugin id を渡すと、OpenClaw はその plugin に記録されたインストール spec を再利用します。つまり、以前に保存された `@beta` などの dist-tags や正確にピン留めされたバージョンは、以後の `update <id>` 実行でも引き続き使用されます。
<Accordion title="Plugin id と npm spec の解決">
Plugin id を渡すと、OpenClaw はその Plugin に記録されているインストール spec を再利用します。つまり、以前に保存された `@beta` のような dist-tag や正確にピン留めされたバージョンは、後続の `update <id>` 実行でも引き続き使用されます。
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 が正確なバージョンにピン留めされており、レジストリのデフォルトリリースラインへ戻したい場合に使います。
</Accordion>
<Accordion title="ベータチャンネルの更新">
`openclaw plugins update` は、新しい spec を渡さない限り、追跡対象の plugin spec を再利用します。`openclaw update` はさらに、アクティブな OpenClaw 更新チャンネルを認識します。ベータチャンネルでは、デフォルトラインの npm および ClawHub plugin レコードは最初に `@beta` を試し、plugin ベータリリースが存在しない場合は記録済みの default/latest spec にフォールバックします。正確なバージョンと明示的なタグは、そのセレクタにピン留めされたままです。
<Accordion title="ベータチャネルの更新">
`openclaw plugins update` は、新しい spec を渡さない限り、追跡対象の Plugin spec を再利用します。`openclaw update` はさらに、アクティブな OpenClaw 更新チャネルを認識します。ベータチャネルでは、デフォルトラインの npm および ClawHub Plugin レコードはまず `@beta` を試し、Plugin のベータリリースが存在しない場合は、記録済みのデフォルト/latest spec にフォールバックします。正確なバージョンと明示的なタグは、そのセレクターにピン留めされたままです。
</Accordion>
<Accordion title="バージョンチェックと整合性ドリフト">
ライブ 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 します。
</Accordion>
<Accordion title="更新時の --dangerously-force-unsafe-install">
`--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 更新にのみ適用されます。
</Accordion>
</AccordionGroup>
@ -339,21 +342,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --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 <command> ...` として実行します。たとえば、`demo-git` を登録する plugin は `openclaw demo-git ping` で検証できます。
Plugin 所有の CLI コマンドは、ルートの `openclaw` コマンドグループとしてインストールされます。`inspect --runtime` が `cliCommands` 配下にコマンドを表示したら、`openclaw <command> ...` として実行します。たとえば、`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) を参照してください。
<Note>
`--json` フラグは、スクリプトや監査に適した機械可読レポートを出力します。`inspect --all` は、形態、機能の種類、互換性通知、バンドル機能、フック概要の列を含む全体テーブルを表示します。`info` は `inspect` のエイリアスです。
`--json` フラグは、スクリプト作成と監査に適した機械可読レポートを出力します。`inspect --all` は、shape、capability kinds、compatibility notices、bundle capabilities、hook summary 列を含む全体テーブルを表示します。`info` は `inspect` のエイリアスです。
</Note>
### 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.<id>` や `plugins.allow` 設定を削除するのではなく、パス所有権や world-writable 権限など、先行するブロック済み plugin diagnostics を修正してください。
設定済み Plugin がディスク上に存在するものの、ローダーのパス安全性チェックでブロックされている場合、config バリデーションは Plugin エントリを保持し、`present but blocked` として報告します。`plugins.entries.<id>` や `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 マニフェストに対して検証されるようにします。
<Warning>
`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 フォールバックは、移行の展開中に緊急で起動を復旧する場合にのみ使用します。
</Warning>
### Marketplace
### マーケットプレイス
```bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --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)

66
docs/ja-JP/cli/sessions.md
View File

@ -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 <n>` を渡し、意図的にストア全体が必要な場合は `--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 <id>`: 設定済みエージェントストア 1 つ
- `--all-agents`: 設定済みのすべてのエージェントストアを集約
- `--store <path>`: 明示的なストアパス（`--agent` または `--all-agents` と組み合わせることはできません）
- `--agent <id>`: 1 つの設定済みエージェントストア
- `--all-agents`: すべての設定済みエージェントストアを集約
- `--store <path>`: 明示的なストアパス（`--agent` または `--all-agents` とは併用不可）
- `--limit <n|all>`: 出力する最大行数（デフォルトは `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/<jobId>.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/<jobId>.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 <key>`: 特定のアクティブキーをディスク容量予算による退避から保護します。グループセッションやスレッド単位のチャットセッションなど、永続的な外部会話ポインターも、経過時間、件数、ディスク容量予算による保守で保持されます。
- `--agent <id>`: 設定済みエージェントストア 1 つに対してクリーンアップを実行します。
- `--all-agents`: 設定済みのすべてのエージェントストアに対してクリーンアップを実行します。
- `--dry-run`: 書き込まずに、いくつのエントリが削除/上限適用されるかをプレビューします。
- テキストモードでは、dry-run はセッションごとのアクション表（`Action`、`Key`、`Age`、`Model`、`Flags`）を出力するため、何が保持され、何が削除されるかを確認できます。
- `--enforce`: `session.maintenance.mode` が `warn` の場合でもメンテナンスを適用します。
- `--fix-missing`: トランスクリプトファイルが欠落しているエントリを、通常はまだ経過時間/件数の対象外であっても削除します。
- `--active-key <key>`: 特定のアクティブキーをディスク予算による退避から保護します。グループセッションやスレッドスコープのチャットセッションなど、永続的な外部会話ポインターも、経過時間/件数/ディスク予算メンテナンスで保持されます。
- `--agent <id>`: 1 つの設定済みエージェントストアに対してクリーンアップを実行します。
- `--all-agents`: すべての設定済みエージェントストアに対してクリーンアップを実行します。
- `--store <path>`: 特定の `sessions.json` ファイルに対して実行します。
- `--json`: JSON サマリーを出力します。`--all-agents` を指定した場合、出力にはストアごとのサマリーが含まれます。
Gateway に到達できる場合、設定済みエージェントストアに対する dry-run ではないクリーンアップは Gateway 経由で送信されるため、ランタイムトラフィックと同じセッションストアライターを共有します。ストアファイルを明示的にオフライン修復するには `--store <path>` を使用してください。
Gateway に到達できる場合、設定済みエージェントストアの非 dry-run クリーンアップは
Gateway 経由で送信されるため、ランタイムトラフィックと同じセッションストアライターを共有します。ストアファイルの明示的なオフライン修復には `--store <path>` を使用してください。
`openclaw sessions cleanup --all-agents --dry-run --json`:

88
docs/ja-JP/cli/update.md
View File

@ -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 <stable|beta|dev>`: 更新チャンネルを設定します（git + npm。設定に永続化されます）。
- `--tag <dist-tag|version|spec>`: この更新でのみパッケージターゲットを上書きします。パッケージインストールでは、`main` は `github:openclaw/openclaw#main` に対応します。
- `--dry-run`: 設定の書き込み、インストール、plugins の同期、再起動を行わずに、予定されている更新アクション（チャンネル/タグ/ターゲット/再起動フロー）をプレビューします。
- `--json`: 機械可読な `UpdateRunResult` JSON を出力します。更新後の plugin 同期中に npm plugin アーティファクトのドリフトが検出された場合は
- `--no-restart`: 更新が成功した後、Gateway サービスの再起動をスキップします。Gateway を再起動するパッケージマネージャー更新では、コマンドが成功する前に、再起動されたサービスが期待される更新後バージョンを報告することを確認します。
- `--channel <stable|beta|dev>`: 更新チャネルを設定します（git + npm。設定に永続化されます）。
- `--tag <dist-tag|version|spec>`: この更新に限り、パッケージターゲットを上書きします。パッケージインストールでは、`main` は `github:openclaw/openclaw#main` にマップされます。
- `--dry-run`: 設定の書き込み、インストール、Plugin の同期、再起動を行わずに、予定されている更新アクション（チャネル/タグ/ターゲット/再起動フロー）をプレビューします。
- `--json`: 機械可読な `UpdateRunResult` JSON を出力します。更新後の Plugin 同期中に npm Plugin アーティファクトのドリフトが検出された場合は、
`postUpdate.plugins.integrityDrifts` も含まれます。
- `--timeout <seconds>`: ステップごとのタイムアウト（デフォルトは 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) を参照してください。
<Warning>
古いバージョンでは設定が壊れる可能性があるため、ダウングレードには確認が必要です。
@ -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 コアの自動更新機能（設定で有効な場合）は、実行中
### 更新ステップ
<Steps>
<Step title="クリーンなワークツリーを検証">
<Step title="クリーンな worktree を確認">
未コミットの変更がないことが必要です。
</Step>
<Step title="チャンネルを切り替え">
選択したチャンネル（タグまたはブランチ）に切り替えます。
<Step title="チャネルを切り替え">
選択したチャネル（タグまたはブランチ）に切り替えます。
</Step>
<Step title="上流を取得">
<Step title="upstream を fetch">
dev のみ。
</Step>
<Step title="事前ビルド（dev のみ）">
一時ワークツリーで lint と TypeScript ビルドを実行します。先端が失敗した場合は、最大 10 コミットさかのぼって最新のクリーンビルドを探します。
一時 worktree で lint と TypeScript ビルドを実行します。先端が失敗した場合、最大 10 コミット遡って、正常にビルドできる最新のコミットを探します。
</Step>
<Step title="Rebase">
選択したコミットに rebase します（dev のみ）。
</Step>
<Step title="依存関係をインストール">
リポジトリのパッケージマネージャーを使用します。pnpm チェックアウトの場合、アップデーターは pnpm ワークスペース内で `npm run build` を実行する代わりに、必要に応じて `pnpm` をブートストラップします（まず `corepack`、次に一時的な `npm install pnpm@10` フォールバック）。
リポジトリのパッケージマネージャーを使用します。pnpm チェックアウトでは、updater は pnpm workspace 内で `npm run build` を実行するのではなく、必要に応じて `pnpm` をブートストラップします（まず `corepack`、次に一時的な `npm install pnpm@10` フォールバック）。
</Step>
<Step title="Control UI をビルド">
Gateway と Control UI をビルドします。
gateway と Control UI をビルドします。
</Step>
<Step title="doctor を実行">
`openclaw doctor` が最後の安全更新チェックとして実行されます。
最後の安全な更新チェックとして `openclaw doctor` を実行します。
</Step>
<Step title="plugins を同期">
plugins を有効なチャンネルに同期します。dev は同梱 plugins を使用し、stable と beta は npm を使用します。追跡対象の plugin インストールを更新します。
<Step title="Plugin を同期">
Plugin をアクティブなチャネルに同期します。dev はバンドル Plugin を使用し、stable と beta は npm を使用します。追跡対象の Plugin インストールを更新します。
</Step>
</Steps>
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 はフォールバックします。正確なバージョンと明示的なタグは書き換えられません。
<Warning>
正確に固定された npm plugin 更新が、保存済みインストールレコードと integrity が異なるアーティファクトに解決された場合、`openclaw update` はその plugin アーティファクト更新をインストールせずに中止します。新しいアーティファクトを信頼できることを確認した後でのみ、plugin を明示的に再インストールまたは更新してください。
正確にピン留めされた npm Plugin 更新が、保存済みインストールレコードと整合性が異なるアーティファクトに解決された場合、`openclaw update` はその Plugin アーティファクト更新をインストールせずに中止します。新しいアーティファクトを信頼できることを確認した後でのみ、Plugin を明示的に再インストールまたは更新してください。
</Warning>
<Note>
更新後の 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` を試すのではなく、パッケージマネージャー固有のエラーで早期に停止します。
</Note>
## `--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)

171
docs/ja-JP/concepts/models.md
View File

@ -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
---
<CardGroup cols={2}>
<Card title="モデル フェイルオーバー" href="/ja-JP/concepts/model-failover">
<Card title="モデルフェイルオーバー" href="/ja-JP/concepts/model-failover">
認証プロファイルのローテーション、クールダウン、それらがフォールバックとどう相互作用するか。
</Card>
<Card title="モデルプロバイダー" href="/ja-JP/concepts/model-providers">
@ -30,7 +30,7 @@ x-i18n:
</Card>
</CardGroup>
モデル参照はプロバイダーとモデルを選択します。通常、低レベルのエージェントランタイムは選択しません。たとえば、`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 は次の順序でモデルを選択します。
<Steps>
<Step title="プライマリモデル">
`agents.defaults.model.primary`（または `agents.defaults.model`）。
`agents.defaults.model.primary` (または `agents.defaults.model`)。
</Step>
<Step title="フォールバック">
`agents.defaults.model.fallbacks`（順序どおり）。
`agents.defaults.model.fallbacks` (順番どおり)。
</Step>
<Step title="プロバイダー認証フェイルオーバー">
認証フェイルオーバーは、次のモデルへ移る前にプロバイダー内で発生します。
次のモデルへ移る前に、プロバイダー内で認証フェイルオーバーが発生します。
</Step>
</Steps>
<AccordionGroup>
<Accordion title="関連するモデルサーフェス">
- `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)を参照)。
</Accordion>
</AccordionGroup>
## 選択元とフォールバック動作
同じ `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` に書き込まれるカスタムプロバイダー)
<Note>
モデル参照は小文字に正規化されます。`z.ai/*` のようなプロバイダーエイリアスは `zai/*` に正規化されます。
プロバイダー設定例（OpenCode を含む）は [OpenCode](/ja-JP/providers/opencode) にあります。
プロバイダー設定例 (OpenCode を含む) は [OpenCode](/ja-JP/providers/opencode) にあります。
</Note>
### 安全な許可リスト編集
`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
<AccordionGroup>
<Accordion title="上書き保護ルール">
`openclaw config set` は、モデル/プロバイダーマップを意図しない上書きから保護します。`agents.defaults.models`、`models.providers`、または `models.providers.<id>.models` へのプレーンオブジェクト代入は、既存のエントリを削除する場合は拒否されます。追加変更には `--merge` を使用し、指定した値を完全なターゲット値にする場合にのみ `--replace` を使用してください。
`openclaw config set` は、モデル/プロバイダーのマップを偶発的な上書きから保護します。`agents.defaults.models`、`models.providers`、または `models.providers.<id>.models` へのプレーンなオブジェクト割り当ては、既存のエントリを削除することになる場合に拒否されます。追加変更には `--merge` を使用してください。指定した値を完全なターゲット値にする場合にのみ `--replace` を使用してください。
対話型プロバイダーセットアップと `openclaw configure --section model` も、プロバイダースコープの選択を既存の許可リストにマージするため、Codex、Ollama、または別のプロバイダーを追加しても、関係のないモデルエントリは削除されません。Configure は、プロバイダー認証が再適用されるときに既存の `agents.defaults.model.primary` を保持します。`openclaw models auth login --provider <id> --set-default` や `openclaw models set <model>` などの明示的なデフォルト設定コマンドは、引き続き `agents.defaults.model.primary` を置き換えます。
対話型プロバイダーセットアップと `openclaw configure --section model` も、プロバイダー単位の選択を既存の許可リストにマージします。そのため、Codex、Ollama、または別のプロバイダーを追加しても、無関係なモデルエントリは削除されません。プロバイダー認証を再適用するとき、Configure は既存の `agents.defaults.model.primary` を保持します。`openclaw models auth login --provider <id> --set-default` や `openclaw models set <model>` のような明示的なデフォルト設定コマンドは、引き続き `agents.defaults.model.primary` を置き換えます。
</Accordion>
</AccordionGroup>
## 「モデルは許可されていません」（そして返信が止まる理由）
## 「モデルは許可されていません」(返信が止まる理由)
`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 <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
<Warning>
これは通常の返信が生成される**前に**発生するため、メッセージは「応答しなかった」ように感じられる場合があります。修正するには、次のいずれかを行います。
これは通常の返信が生成される**前に**発生するため、メッセージが「応答しなかった」ように感じられる場合があります。修正するには、次のいずれかを行います。
- モデルを `agents.defaults.models` に追加する、または
- 許可リストをクリアする（`agents.defaults.models` を削除する）、または
- `/model list` からモデルを選ぶ。
- 許可リストをクリアする (`agents.defaults.models` を削除する)、または
- `/model list` からモデルを選択する。
</Warning>
ローカル/GGUF モデルでは、許可リストに完全なプロバイダー接頭辞付き参照を保存します。
たとえば `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`、または
`openclaw models list --provider <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>` に表示される正確な 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.
<AccordionGroup>
<Accordion title="ピッカーの動作">
- `/model`（および `/model list`）は、コンパクトな番号付きピッカーです（モデルファミリー + 利用可能なプロバイダー）。
- Discord では、`/model` と `/models` が、プロバイダーとモデルのドロップダウンに加えて送信ステップを備えた対話型ピッカーを開きます。
- `/model` (および `/model list`) は、コンパクトな番号付きピッカー (モデルファミリー + 利用可能なプロバイダー) です。
- Discord では、`/model` と `/models` は、プロバイダーとモデルのドロップダウンに加えて Submit ステップを持つ対話型ピッカーを開きます。
- Telegram では、`/models` ピッカーの選択はセッションスコープです。`openclaw.json` 内のエージェントの永続的なデフォルトは変更しません。
- `/models add` は非推奨で、現在はチャットからモデルを登録する代わりに非推奨メッセージを返します。
- `/models add` は非推奨になり、チャットからモデルを登録する代わりに非推奨メッセージを返すようになりました。
- `/model <#>` はそのピッカーから選択します。
</Accordion>
<Accordion title="永続化とライブ切り替え">
- `/model` は新しいセッション選択を即座に永続化します。
- エージェントがアイドル状態の場合、次の実行はすぐに新しいモデルを使用します。
- 実行がすでにアクティブな場合、OpenClaw はライブ切り替えを保留中としてマークし、クリーンな再試行ポイントでのみ新しいモデルへ再起動します。
- ツールのアクティビティまたは返信出力がすでに開始している場合、保留中の切り替えは、後の再試行機会または次のユーザーターンまでキューに残る場合があります。
- ユーザーが選択した `/model` 参照は、そのセッションでは厳密です。選択されたプロバイダー/モデルに到達できない場合、`agents.defaults.model.fallbacks` から静かに回答するのではなく、返信は見える形で失敗します。これは、引き続きフォールバックチェーンを使用できる設定済みデフォルトや cron ジョブのプライマリとは異なります。
- `/model status` は詳細ビューです（認証候補、および設定されている場合はプロバイダーエンドポイントの `baseUrl` + `api` モード）。
- エージェントがアイドル状態の場合、次の実行は新しいモデルをすぐに使用します。
- 実行がすでにアクティブな場合、OpenClaw はライブ切り替えを保留としてマークし、クリーンな再試行ポイントでのみ新しいモデルへ再起動します。
- ツールアクティビティまたは返信出力がすでに開始している場合、保留中の切り替えは後の再試行機会または次のユーザーターンまでキューに残ることがあります。
- ユーザーが選択した `/model` 参照は、そのセッションでは厳密です。選択されたプロバイダー/モデルに到達できない場合、返信は `agents.defaults.model.fallbacks` から黙って応答するのではなく、見える形で失敗します。これは設定済みデフォルトや cron ジョブのプライマリとは異なり、それらは引き続きフォールバックチェーンを使用できます。
- `/model status` は詳細ビューです (認証候補、および設定されている場合はプロバイダーエンドポイント `baseUrl` + `api` モード)。
</Accordion>
<Accordion title="参照の解析">
- モデル参照は、**最初の** `/` で分割して解析されます。`/model <ref>` を入力するときは `provider/model` を使用します。
- モデル ID 自体に `/` が含まれる場合（OpenRouter 形式）、プロバイダー接頭辞を含める必要があります（例: `/model openrouter/moonshotai/kimi-k2`）。
- プロバイダーを省略した場合、OpenClaw は次の順序で入力を解決します。
- モデル参照は、**最初**の `/` で分割して解析されます。`/model <ref>` を入力するときは `provider/model` を使用してください。
- モデル ID 自体に `/` が含まれる場合 (OpenRouter 形式)、プロバイダープレフィックスを含める必要があります (例: `/model openrouter/moonshotai/kimi-k2`)。
- プロバイダーを省略すると、OpenClaw は次の順序で入力を解決します。
1. エイリアス一致
2. その正確な接頭辞なしモデル ID に対する、一意の設定済みプロバイダー一致
3. 設定済みデフォルトプロバイダーへの非推奨フォールバック — そのプロバイダーが設定済みデフォルトモデルを公開しなくなっている場合、OpenClaw は古い削除済みプロバイダーのデフォルトを表示しないよう、代わりに最初の設定済みプロバイダー/モデルへフォールバックします。
2. その正確なプレフィックスなしモデル ID に対する、一意の設定済みプロバイダー一致
3. 設定済みデフォルトプロバイダーへの非推奨フォールバック。そのプロバイダーが設定済みデフォルトモデルをもう公開していない場合、OpenClaw は古くなった削除済みプロバイダーのデフォルトを表面化させないように、代わりに最初の設定済みプロバイダー/モデルへフォールバックします。
</Accordion>
</AccordionGroup>
完全なコマンド動作/設定: [スラッシュコマンド](/ja-JP/tools/slash-commands)。
コマンドの完全な動作/設定: [スラッシュコマンド](/ja-JP/tools/slash-commands)。
## CLI コマンド
@ -222,14 +225,14 @@ openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear
```
`openclaw models`（サブコマンドなし）は `models status` のショートカットです。
`openclaw models` (サブコマンドなし) は `models status` のショートカットです。
### `models list`
デフォルトでは、設定済み/認証利用可能なモデルを表示します。便利なフラグ:
<ParamField path="--all" type="boolean">
完全なカタログ。認証が設定される前の同梱プロバイダー所有の静的カタログ行を含むため、検出専用ビューで、一致するプロバイダー認証情報を追加するまで利用できないモデルを表示できます。
完全なカタログ。認証が設定される前の、同梱プロバイダー所有の静的カタログ行も含まれるため、検出専用ビューで、一致するプロバイダー認証情報を追加するまで利用できないモデルを表示できます。
</ParamField>
<ParamField path="--local" type="boolean">
ローカルプロバイダーのみ。
@ -238,7 +241,7 @@ openclaw models image-fallbacks clear
プロバイダー ID でフィルターします。例: `moonshot`。対話型ピッカーの表示ラベルは受け付けません。
</ParamField>
<ParamField path="--plain" type="boolean">
1行に1モデル。
1 行に 1 つのモデル。
</ParamField>
<ParamField path="--json" type="boolean">
機械可読出力。
@ -246,13 +249,13 @@ openclaw models image-fallbacks clear
### `models status`
解決済みのプライマリモデル、フォールバック、画像モデル、設定済みプロバイダーの認証概要を表示します。また、認証ストアで見つかったプロファイルの OAuth 有効期限ステータスも表示します（デフォルトでは24時間以内に警告）。`--plain` は解決済みのプライマリモデルのみを出力します。
解決済みのプライマリモデル、フォールバック、画像モデル、設定済みプロバイダーの認証概要を表示します。また、認証ストア内で見つかったプロファイルの OAuth 有効期限ステータスも表示します（デフォルトでは 24 時間以内に警告）。`--plain` は解決済みのプライマリモデルのみを出力します。
<AccordionGroup>
<Accordion title="認証とプローブの動作">
- 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.<provider>` が保存済みプロファイルを省略している場合、プローブは試行せずに `excluded_by_auth_order` を報告します。認証は存在するものの、そのプロバイダーでプローブ可能なモデルを解決できない場合、プローブは `status: no_model` を報告します。
@ -260,7 +263,7 @@ openclaw models image-fallbacks clear
</AccordionGroup>
<Note>
認証の選択はプロバイダー/アカウントに依存します。常時稼働の Gateway ホストでは、通常 API キーが最も予測しやすい方法です。Claude CLI の再利用と既存の Anthropic OAuth/トークンプロファイルもサポートされています。
認証の選択はプロバイダー/アカウントに依存します。常時稼働の Gateway ホストでは、通常 API キーが最も予測可能です。Claude CLI の再利用と既存の Anthropic OAuth/token プロファイルもサポートされています。
</Note>
例（Claude CLI）:
@ -272,7 +275,7 @@ openclaw models status
## スキャン（OpenRouter 無料モデル）
`openclaw models scan` は OpenRouter の **無料モデルカタログ** を検査し、任意でモデルのツールおよび画像サポートをプローブできます。
`openclaw models scan` は OpenRouter の **無料モデルカタログ** を検査し、必要に応じてツールと画像サポートについてモデルをプローブできます。
<ParamField path="--no-probe" type="boolean">
ライブプローブをスキップします（メタデータのみ）。
@ -297,10 +300,10 @@ openclaw models status
</ParamField>
<Note>
OpenRouter の `/models` カタログは公開されているため、メタデータのみのスキャンではキーなしで無料候補を一覧できます。プローブと推論には引き続き OpenRouter API キー（認証プロファイルまたは `OPENROUTER_API_KEY` から）が必要です。キーが利用できない場合、`openclaw models scan` はメタデータのみの出力にフォールバックし、設定は変更しません。メタデータのみのモードを明示的に要求するには `--no-probe` を使用します。
OpenRouter の `/models` カタログは公開されているため、メタデータのみのスキャンではキーなしで無料候補を一覧表示できます。プローブと推論には引き続き OpenRouter API キー（認証プロファイルまたは `OPENROUTER_API_KEY` から）が必要です。キーを利用できない場合、`openclaw models scan` はメタデータのみの出力にフォールバックし、設定は変更しません。メタデータのみモードを明示的に要求するには `--no-probe` を使用します。
</Note>
スキャン結果は次の順でランク付けされます。
スキャン結果は次の順でランク付けされます:
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/<agentId>/agent/models.json`）に書き込まれます。このファイルは、`models.mode` が `replace` に設定されていない限りデフォルトでマージされます。
`models.providers` のカスタムプロバイダーは、エージェントディレクトリ配下の `models.json`（デフォルト `~/.openclaw/agents/<agentId>/agent/models.json`）に書き込まれます。このファイルは、`models.mode` が `replace` に設定されていない限り、デフォルトでマージされます。
<AccordionGroup>
<Accordion title="マージモードの優先順位">
一致するプロバイダー 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` にフォールバックします。
- その他のプロバイダーフィールドは、設定と正規化済みカタログデータから更新されます。
- その他のプロバイダーフィールドは、設定と正規化されたカタログデータから更新されます。
</Accordion>
</AccordionGroup>
<Note>
マーカーの永続化ではソースが権威です。OpenClaw は、解決済みランタイムシークレット値ではなく、アクティブなソース設定スナップショット（解決前）からマーカーを書き込みます。これは、`openclaw agent` のようなコマンド駆動パスを含め、OpenClaw が `models.json` を再生成するたびに適用されます。
マーカーの永続化ではソースが権威です。OpenClaw は解決済みのランタイムシークレット値ではなく、アクティブなソース設定スナップショット（解決前）からマーカーを書き込みます。これは、`openclaw agent` のようなコマンド駆動の経路を含め、OpenClaw が `models.json` を再生成するたびに適用されます。
</Note>
## 関連

562
docs/ja-JP/concepts/qa-e2e-automation.md
View File

@ -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 <subcommand>` の下で実行されます。多くには `pnpm qa:*`
スクリプトエイリアスがあります。どちらの形式もサポートされています。
すべての QA フローは `pnpm openclaw qa <subcommand>` の下で実行されます。多くは `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-<timestamp>/` 配下に書き出します。
このレーンの完全な CLI リファレンス、プロファイル/シナリオカタログ、環境変数、成果物レイアウトは [Matrix QA](/ja-JP/concepts/qa-matrix) にあります。概要: Docker 内に使い捨て Tuwunel ホームサーバーをプロビジョニングし、一時的なドライバー/SUT/オブザーバーユーザーを登録し、そのトランスポートにスコープされた子 QA Gateway 内で実際の Matrix Plugin を実行し（`qa-channel` なし）、Markdown レポート、JSON サマリー、観測イベント成果物、結合出力ログを `.artifacts/qa-e2e/matrix-<timestamp>/` の下に書き込みます。
トランスポート実体ありの 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 <cbx_...>` を再利用してください。`--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 <cbx_...>` を再利用してください。
`--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 <count>` を使用し、シリアル実行には `--concurrency 1` を使用します。
いずれかのシナリオが失敗すると、このコマンドは非ゼロで終了します。失敗終了コードなしで
成果物が必要な場合は `--allow-failures` を使用します。
ライブ実行では、ゲストで実用的なサポート対象の QA 認証入力が転送されます:
env ベースのプロバイダーキー、QA ライブプロバイダー設定パス、および
存在する場合は `CODEX_HOME`。ゲストがマウントされたワークスペース経由で
書き戻せるように、`--output-dir` はリポジトリルート配下に置いてください。
ホストと Multipass のスイート実行では、デフォルトで、選択された複数のシナリオを分離された Gateway ワーカーで並列実行します。`qa-channel` のデフォルト並行数は 4 で、選択されたシナリオ数が上限です。ワーカー数を調整するには `--concurrency <count>` を使用し、シリアル実行には `--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 <id>` | — | このシナリオだけを実行します。繰り返し指定できます。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | レポート、サマリー、観測メッセージ、および出力ログの書き込み先です。相対パスは `--repo-root` を基準に解決されます。 |
| `--repo-root <path>` | `process.cwd()` | 中立的な cwd から呼び出す場合のリポジトリルートです。 |
| `--sut-account <id>` | `sut` | QA Gateway 設定内の一時アカウント id です。 |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` または `live-frontier` です（レガシーの `live-openai` も引き続き動作します）。 |
| `--model <ref>` / `--alt-model <ref>` | プロバイダーの既定値 | プライマリ/代替モデル ref です。 |
| `--fast` | オフ | サポートされる場合のプロバイダー高速モードです。 |
| `--credential-source <env\|convex>` | `env` | [Convex 認証情報プール](#convex-credential-pool)を参照してください。 |
| `--credential-role <maintainer\|ci>` | CI では `ci`、それ以外では `maintainer` | `--credential-source convex` の場合に使用されるロールです。 |
| `--scenario <id>` | — | このシナリオのみを実行します。繰り返し指定できます。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | レポート、サマリー、観測メッセージ、出力ログの書き込み先です。相対パスは `--repo-root` を基準に解決されます。 |
| `--repo-root <path>` | `process.cwd()` | 中立的な cwd から呼び出す場合のリポジトリルートです。 |
| `--sut-account <id>` | `sut` | QA Gateway 設定内の一時アカウント id です。 |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` または `live-frontier`（レガシーの `live-openai` も引き続き動作します）。 |
| `--model <ref>` / `--alt-model <ref>` | プロバイダーのデフォルト | プライマリ/代替モデル参照です。 |
| `--fast` | オフ | サポートされている場合のプロバイダー高速モードです。 |
| `--credential-source <env\|convex>` | `env` | [Convex 認証情報プール](#convex-credential-pool)を参照してください。 |
| `--credential-role <maintainer\|ci>` | 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/<theme>/*.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 <runner>` をマウントする方法
- そのトランスポート向けに Gateway を構成する方法
- 準備完了を確認する方法
- インバウンドイベントを注入する方法
- アウトバウンドメッセージを観測する方法
- トランスクリプトと正規化されたトランスポート状態を公開する方法
- トランスポートに裏付けられたアクションを実行する方法
- トランスポート固有のリセットまたはクリーンアップを処理する方法
- 共有 `qa` root の下に `openclaw qa <runner>` をどう 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 <runner>` としてマウントします。ランナー 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 <runner>` として 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=<level>` をインラインで指定します。`--thinking <level>` は引き続きグローバルフォールバックを設定し、古い `--model-thinking <provider/model=level>` 形式は互換性のために維持されています。
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=<level>` を使用します。`--thinking <level>` は引き続きグローバルなフォールバックを設定し、古い `--model-thinking <provider/model=level>` 形式は互換性のために保持されています。
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)

218
docs/ja-JP/gateway/config-tools.md
View File

@ -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` の前にベースの許可リストを設定します。
<Note>
ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトが `tools.profile: "coding"` になります（既存の明示的なプロファイルは保持されます）。
ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトを `tools.profile: "coding"` にします（既存の明示的なプロファイルは保持されます）。
</Note>
| プロファイル | 含まれるもの |
| プロファイル | 含まれるもの |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `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:
ループ分析のために保持されるツール呼び出し履歴の最大数。
</ParamField>
<ParamField path="warningThreshold" type="number">
警告の対象となる、進行のない繰り返しパターンのしきい値。
警告のための、進捗のない繰り返しパターンのしきい値。
</ParamField>
<ParamField path="criticalThreshold" type="number">
重大なループをブロックするための、より高い繰り返ししきい値。
</ParamField>
<ParamField path="globalCircuitBreakerThreshold" type="number">
進行のない実行をハード停止するしきい値。
進捗のない実行に対する強制停止しきい値。
</ParamField>
<ParamField path="detectors.genericRepeat" type="boolean">
同じツール / 同じ引数の呼び出しが繰り返された場合に警告します。
同じツール/同じ引数の呼び出しが繰り返された場合に警告します。
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
既知のポーリングツール（`process.poll`、`command_status` など）で警告 / ブロックします。
既知のポーリングツール（`process.poll`、`command_status` など）で警告/ブロックします。
</ParamField>
<ParamField path="detectors.pingPong" type="boolean">
進行のないペアパターンが交互に繰り返される場合に警告 / ブロックします。
進捗のないペアが交互に繰り返されるパターンで警告/ブロックします。
</ParamField>
<Warning>
@ -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:
```
<AccordionGroup>
<Accordion title="メディアモデル項目のフィールド">
**プロバイダー項目**（`type: "provider"` または省略）:
<Accordion title="メディアモデルエントリのフィールド">
**プロバイダーエントリ**（`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`: 非推奨の互換性フラグ。完了した非同期メディアタスクはリクエスターセッション経由のままになり、エージェントが結果を受け取り、ユーザーへの伝え方を決定し、ソース配信で必要な場合はメッセージツールを使用します。
</Accordion>
</AccordionGroup>
@ -291,7 +291,7 @@ x-i18n:
セッションツール（`sessions_list`、`sessions_history`、`sessions_send`）の対象にできるセッションを制御します。
デフォルト: `tree`（現在のセッション + それによって生成されたセッション、サブエージェントなど）。
デフォルト: `tree`（現在のセッション + サブエージェントなど、そのセッションから生成されたセッション）。
```json5
{
@ -307,10 +307,10 @@ x-i18n:
<AccordionGroup>
<Accordion title="可視性スコープ">
- `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` になります。
</Accordion>
</AccordionGroup>
@ -336,11 +336,11 @@ x-i18n:
```
<AccordionGroup>
<Accordion title="添付ファイルの注意事項">
- 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACP runtime は添付ファイルを拒否します。
<Accordion title="添付ファイルのメモ">
- 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACP ランタイムはそれらを拒否します。
- ファイルは子ワークスペース内の `.openclaw/attachments/<uuid>/` に `.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/<agentId>/agent/models.json` でカスタムプロバイダーを追加します。
OpenClaw は組み込みのモデルカタログを使用します。カスタムプロバイダーは、設定内の `models.providers` または `~/.openclaw/agents/<agentId>/agent/models.json` で追加します。
```json5
{
@ -425,18 +425,18 @@ OpenClaw は組み込みモデルカタログを使用します。設定内の `
<AccordionGroup>
<Accordion title="認証とマージの優先順位">
- カスタム認証の必要がある場合は、`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"` を使用します。
- マーカーの永続化はソースを正とします。マーカーは解決済みのランタイムシークレット値ではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。
- マーカーの永続化はソースを正とします。マーカーは、解決済みランタイムシークレット値からではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。
</Accordion>
</AccordionGroup>
@ -445,63 +445,63 @@ OpenClaw は組み込みモデルカタログを使用します。設定内の `
<AccordionGroup>
<Accordion title="トップレベルカタログ">
- `models.mode`: プロバイダーカタログの動作（`merge` または `replace`）。
- `models.providers`: プロバイダー ID をキーにしたカスタムプロバイダーマップ。
- 安全な編集: 追加更新には `openclaw config set models.providers.<id> '<json>' --strict-json --merge` または `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` を使用します。`config set` は、`--replace` を渡さない限り破壊的な置換を拒否します。
- `models.mode`: プロバイダーカタログの動作（`merge` または `replace`）です。
- `models.providers`: プロバイダー ID をキーにしたカスタムプロバイダーマップです。
- 安全な編集: 追加更新には、`openclaw config set models.providers.<id> '<json>' --strict-json --merge` または `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` を使用します。`config set` は、`--replace` を渡さない限り破壊的な置換を拒否します。
</Accordion>
<Accordion title="プロバイダー接続と認証">
- `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`: プロキシ/テナントルーティング用の追加静的ヘッダーです。
</Accordion>
<Accordion title="リクエスト転送の上書き">
`models.providers.*.request`: モデルプロバイダー HTTP リクエストの転送上書きです。
<Accordion title="リクエスト転送のオーバーライド">
`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` です。
</Accordion>
<Accordion title="モデルカタログエントリ">
- `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` 配列をプレーン文字列へ平坦化します。
</Accordion>
<Accordion title="Amazon Bedrock の検出">
- `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`: 検出されたモデルに使うフォールバックの最大出力トークン数です。
<Accordion title="Amazon Bedrock ディスカバリー">
- `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`: 検出されたモデル向けのフォールバック最大出力トークン数です。
</Accordion>
</AccordionGroup>
対話型のカスタムプロバイダー オンボーディングでは、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` を渡します。
### プロバイダー例
<AccordionGroup>
<Accordion title="Cerebras（GLM 4.7 / GPT OSS）">
バンドルされている `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` を使用します。
</Accordion>
<Accordion title="Kimi Coding">
<Accordion title="Kimi コーディング">
```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`。
</Accordion>
<Accordion title="Local models (LM Studio)">
[Local Models](/ja-JP/gateway/local-models) を参照してください。要約: 本格的なハードウェア上で、LM Studio Responses API 経由で大規模ローカルモデルを実行し、フォールバック用にホスト型モデルもマージしたままにします。
<Accordion title="ローカルモデル (LM Studio)">
[ローカルモデル](/ja-JP/gateway/local-models)を参照してください。要約: 本格的なハードウェア上で LM Studio Responses API 経由の大規模ローカルモデルを実行し、フォールバック用にホスト型モデルをマージしたままにします。
</Accordion>
<Accordion title="MiniMax M2.7 (direct)">
<Accordion title="MiniMax M2.7 (直接)">
```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` に書き換えます。
</Accordion>
<Accordion title="Moonshot AI (Kimi)">
@ -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 だけでなくエンドポイント機能に基づいてそれを判定します。
</Accordion>
<Accordion title="OpenCode">
@ -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`。
</Accordion>
<Accordion title="Synthetic（Anthropic 互換）">
<Accordion title="Synthetic (Anthropic 互換)">
```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`。
</Accordion>
<Accordion title="Z.AI（GLM-4.7）">
<Accordion title="Z.AI (GLM-4.7)">
```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 の上書きを持つカスタムプロバイダーを定義します。
</Accordion>
</AccordionGroup>

656
docs/ja-JP/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

98
docs/ja-JP/gateway/diagnostics.md
View File

@ -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 <thread-id>` コマンドをローカルで実行します。その調査ワークフローについては、[Codex ハーネス](/ja-JP/plugins/codex-harness#inspect-a-codex-thread-from-the-cli)を参照してください。
これにより、一般的な Codex デバッグループは短くなります。Telegram、Discord、または別のチャンネルで問題のある動作に気づき、`/diagnostics` を実行し、1 回承認し、レポートをサポートと共有し、ネイティブ Codex スレッドを自分で確認したい場合は、出力された `codex resume <thread-id>` コマンドをローカルで実行します。その確認ワークフローについては、[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 <path>`: 特定の zip パスに書き込みます。
- `--log-lines <count>`: 含めるサニタイズ済みログ行の最大数。
- `--log-bytes <bytes>`: 調べるログバイトの最大数。
- `--url <url>`: ステータスとヘルスのスナップショット用の Gateway WebSocket URL。
- `--token <token>`: ステータスとヘルスのスナップショット用の Gateway トークン。
- `--password <password>`: ステータスとヘルスのスナップショット用の Gateway パスワード。
- `--timeout <ms>`: ステータスとヘルスのスナップショットのタイムアウト。
- `--no-stability-bundle`: 永続化済み安定性バンドルの検索をスキップします。
- `--log-bytes <bytes>`: 検査するログバイトの最大数。
- `--url <url>`: ステータスおよびヘルススナップショット用の Gateway WebSocket URL。
- `--token <token>`: ステータスおよびヘルススナップショット用の Gateway トークン。
- `--password <password>`: ステータスおよびヘルススナップショット用の Gateway パスワード。
- `--timeout <ms>`: ステータスおよびヘルススナップショットのタイムアウト。
- `--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) — 診断をコレクターへストリーミングするための別フロー

446
docs/ja-JP/gateway/doctor.md
View File

@ -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
```
### ヘッドレスと自動化モード
### ヘッドレスモードと自動化モード
<Tabs>
<Tab title="--yes">
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
プロンプトを表示せずにデフォルトを受け入れます（該当する場合は再起動、サービス、サンドボックスの修復手順も含む）。
プロンプトなしで既定値を受け入れます（該当する場合は restart/service/sandbox の修復手順を含む）。
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
プロンプトを表示せずに推奨される修復を適用します（安全な場合は修復 + 再起動）。
プロンプトなしで推奨修復を適用します（安全な場合は修復 + 再起動）。
</Tab>
<Tab title="--repair --force">
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
積極的な修復も適用します（カスタム supervisor 設定を上書きします）。
強力な修復も適用します（カスタム supervisor config を上書きします）。
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
プロンプトなしで実行し、安全な移行（設定の正規化 + ディスク上の状態移動）のみを適用します。人間の確認が必要な再起動、サービス、サンドボックスの操作はスキップします。レガシー状態の移行は、検出されると自動的に実行されます。
プロンプトなしで実行し、安全な移行のみを適用します（config の正規化 + ディスク上の state 移動）。人間の確認が必要な restart/service/sandbox アクションはスキップします。レガシー state 移行は検出時に自動実行されます。
</Tab>
<Tab title="--deep">
@ -62,133 +62,130 @@ openclaw doctor
openclaw doctor --deep
```
追加の Gateway インストール（launchd/systemd/schtasks）についてシステムサービスをスキャンします。
追加の Gateway インストール（launchd/systemd/schtasks）を system services でスキャンします。
</Tab>
</Tabs>
書き込む前に変更を確認したい場合は、まず設定ファイルを開いてください。
書き込む前に変更を確認したい場合は、先に config ファイルを開きます。
```bash
cat ~/.openclaw/openclaw.json
```
## 実行内容（概要）
## 実行内容（要約）
<AccordionGroup>
<Accordion title="ヘルス、UI、更新">
<Accordion title="健全性、UI、更新">
- git インストール向けの任意の事前更新（対話時のみ）。
- UI プロトコルの鮮度チェック（プロトコルスキーマのほうが新しい場合、Control UI を再ビルドします）。
- ヘルスチェック + 再起動プロンプト。
- Skills ステータス概要（対象/不足/ブロック）と plugin ステータス。
- UI プロトコルの鮮度チェック（プロトコルスキーマが新しい場合に Control UI を再ビルド）。
- 健全性チェック + 再起動プロンプト。
- Skills ステータス要約（eligible/missing/blocked）と Plugin ステータス。
</Accordion>
<Accordion title="設定と移行">
- レガシー値の設定正規化。
- レガシーのフラットな `talk.*` フィールドから `talk.provider` + `talk.providers.<provider>` への 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 参照は不活性な封じ込め設定として扱われ、保持されます。
<Accordion title="Config と移行">
- レガシー値の config 正規化。
- レガシーのフラットな `talk.*` フィールドから `talk.provider` + `talk.providers.<provider>` への 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 として扱われ、保持されます。
</Accordion>
<Accordion title="状態と整合性">
- セッションロックファイルの検査と古いロックのクリーンアップ。
- 影響を受けた 2026.4.24 ビルドで作成された重複プロンプト書き換えブランチに対するセッショントランスクリプト修復。
- 行き詰まったサブエージェントの再起動リカバリー tombstone 検出。古い中止済みリカバリーフラグをクリアして、起動時に子を再起動中止済みとして扱い続けないようにする `--fix` サポート付き。
- 状態の整合性と権限チェック（セッション、トランスクリプト、状態ディレクトリ）。
- ローカル実行時の設定ファイル権限チェック（chmod 600）。
- モデル認証ヘルス: OAuth 有効期限を確認し、期限が近いトークンを更新でき、認証プロファイルのクールダウン/無効状態を報告します。
- 追加ワークスペースディレクトリの検出（`~/openclaw`）。
<Accordion title="State と整合性">
- 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`）。
</Accordion>
<Accordion title="Gateway、サービス、supervisor">
- サンドボックス化が有効な場合のサンドボックスイメージ修復。
- レガシーサービス移行と追加 Gateway 検出。
- Matrix チャンネルのレガシー状態移行（`--fix` / `--repair` モード）。
- Gateway ランタイムチェック（サービスはインストール済みだが実行されていない、キャッシュ済み launchd ラベル）。
- チャンネルステータス警告（実行中の gateway からプローブ）。
- supervisor 設定監査（launchd/systemd/schtasks）と任意の修復。
- インストールまたは更新中にシェルの `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 値を取り込んだ gateway サービス向けの埋め込みプロキシ環境クリーンアップ。
- Gateway ランタイムのベストプラクティスチェック（Node と Bun、バージョンマネージャーパス）。
- Gateway ポート衝突診断（デフォルト `18789`）。
<Accordion title="Gateway、services、supervisors">
- 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`）。
</Accordion>
<Accordion title="認証、セキュリティ、ペアリング">
- オープン DM ポリシーに関するセキュリティ警告。
- ローカルトークンモードの Gateway 認証チェック（トークンソースが存在しない場合にトークン生成を提案します。トークン SecretRef 設定は上書きしません）。
- デバイスペアリングの問題検出（保留中の初回ペアリングリクエスト、保留中のロール/スコープアップグレード、古いローカル device-token キャッシュのドリフト、ペアリング済みレコードの認証ドリフト）。
<Accordion title="Auth、セキュリティ、ペアリング">
- 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）。
</Accordion>
<Accordion title="ワークスペースとシェル">
<Accordion title="Workspace と shell">
- 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 を書き込みます。
</Accordion>
</AccordionGroup>
## 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 します。
## 詳細な挙動と根拠
<AccordionGroup>
<Accordion title="0. 任意の更新（git インストール）">
これが git チェックアウトで doctor が対話的に実行されている場合、doctor の実行前に更新（fetch/rebase/build）を提案します。
これが git checkout で doctor が対話的に実行されている場合、doctor 実行前に更新（fetch/rebase/build）を提案します。
</Accordion>
<Accordion title="1. 設定の正規化">
設定にレガシー値の形状（たとえばチャンネル固有の上書きがない `messages.ackReaction`）が含まれる場合、doctor はそれらを現在のスキーマへ正規化します。
<Accordion title="1. Config 正規化">
config にレガシー値の形（たとえば channel-specific override なしの `messages.ackReaction`）が含まれている場合、doctor はそれらを現在のスキーマへ正規化します。
これにはレガシー Talk のフラットフィールドが含まれます。現在の公開 Talk 設定は `talk.provider` + `talk.providers.<provider>` です。Doctor は古い `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` の形状をプロバイダーマップへ書き換えます。
これにはレガシー Talk のフラットフィールドも含まれます。現在の公開 Talk config は `talk.provider` + `talk.providers.<provider>` です。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"` 設定を案内します。
</Accordion>
<Accordion title="2. レガシー設定キーの移行">
設定に非推奨キーが含まれる場合、他のコマンドは実行を拒否し、`openclaw doctor` の実行を求めます。
<Accordion title="2. レガシー config key 移行">
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.<id>.timeoutSeconds` を使用する
- `agents.defaults.llm` を削除します。遅いプロバイダー/モデルのタイムアウトには `models.providers.<id>.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.<channel>.accounts` エントリが、`channels.<channel>.defaultAccount` または `accounts.default` なしで構成されている場合、診断はフォールバックルーティングが想定外のアカウントを選ぶ可能性があると警告する。
- `channels.<channel>.defaultAccount` が未知のアカウント ID に設定されている場合、診断は警告し、構成済みアカウント ID を一覧表示する。
- 2つ以上の `channels.<channel>.accounts` エントリが `channels.<channel>.defaultAccount` または `accounts.default` なしで設定されている場合、doctor はフォールバックルーティングが予期しないアカウントを選ぶ可能性があると警告します。
- `channels.<channel>.defaultAccount` が不明なアカウント ID に設定されている場合、doctor は警告し、設定済みのアカウント ID を一覧表示します。
</Accordion>
<Accordion title="2b. OpenCode プロバイダーオーバーライド">
`models.providers.opencode`、`opencode-zen`、または `opencode-go` を手動で追加している場合、それは `@mariozechner/pi-ai` の組み込み OpenCode カタログをオーバーライドする。その結果、モデルが誤った API に強制されたり、コストがゼロになったりする可能性がある。診断は、オーバーライドを削除してモデルごとの API ルーティングとコストを復元できるよう警告する。
<Accordion title="2b. OpenCode プロバイダーのオーバーライド">
`models.providers.opencode`、`opencode-zen`、または `opencode-go` を手動で追加している場合、`@mariozechner/pi-ai` の組み込み OpenCode カタログがオーバーライドされます。これにより、モデルが誤った API に割り当てられたり、コストがゼロになったりする可能性があります。doctor は、オーバーライドを削除してモデルごとの API ルーティングとコストを復元できるよう警告します。
</Accordion>
<Accordion title="2c. ブラウザー移行と Chrome MCP 準備状況">
ブラウザー設定がまだ削除済み Chrome 拡張パスを指している場合、診断はそれを現在のホストローカル Chrome MCP アタッチモデルへ正規化する。
<Accordion title="2c. ブラウザー移行と 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 を使用します。
</Accordion>
<Accordion title="2d. OAuth TLS 前提条件">
OpenAI Codex OAuth プロファイルが構成されている場合、診断は OpenAI 認可エンドポイントをプローブして、ローカルの Node/OpenSSL TLS スタックが証明書チェーンを検証できることを確認する。プローブが証明書エラー（例: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、期限切れ証明書、自己署名証明書）で失敗した場合、診断はプラットフォーム固有の修正ガイダンスを出力する。Homebrew Node を使用する macOS では、通常の修正は `brew postinstall ca-certificates` である。`--deep` では、gateway が正常な場合でもプローブが実行される。
<Accordion title="2d. OAuth TLS の前提条件">
OpenAI Codex OAuth プロファイルが設定されている場合、doctor は OpenAI 認可エンドポイントをプローブして、ローカルの Node/OpenSSL TLS スタックが証明書チェーンを検証できるか確認します。プローブが証明書エラー（例: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、期限切れ証明書、または自己署名証明書）で失敗した場合、doctor はプラットフォーム別の修正ガイダンスを出力します。Homebrew の Node を使っている macOS では、通常の修正は `brew postinstall ca-certificates` です。`--deep` では、Gateway が正常な場合でもプローブが実行されます。
</Accordion>
<Accordion title="2e. Codex OAuth プロバイダーオーバーライド">
以前に `models.providers.openai-codex` の下にレガシー OpenAI トランスポート設定を追加していた場合、それらは新しいリリースが自動的に使用する組み込み Codex OAuth プロバイダーパスを隠す可能性がある。診断は、Codex OAuth と並んでそれらの古いトランスポート設定を検出した場合に警告し、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を取り戻せるようにする。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しない。
<Accordion title="2e. Codex OAuth プロバイダーのオーバーライド">
以前にレガシー OpenAI トランスポート設定を `models.providers.openai-codex` の下に追加していた場合、それらが新しいリリースで自動的に使用される組み込み Codex OAuth プロバイダーパスをシャドーする可能性があります。doctor は、Codex OAuth と並んでそれらの古いトランスポート設定を見つけると警告し、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を取り戻せるようにします。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しません。
</Accordion>
<Accordion title="2f. Codex Plugin ルート警告">
バンドルされた Codex Plugin が有効な場合、診断は `openai-codex/*` プライマリモデル参照がまだデフォルトの PI ランナー経由で解決されるかどうかも確認する。この組み合わせは、PI 経由で Codex OAuth/サブスクリプション認証を使用したい場合には有効だが、ネイティブ Codex アプリサーバーハーネスと混同しやすい。診断は警告し、明示的なアプリサーバー形状を示す: `openai/*` に加えて `agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex`。
<Accordion title="2f. Codex Plugin ルートの警告">
バンドルされた 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 が意図した構成である場合は、警告をそのままにします。
</Accordion>
<Accordion title="3. レガシー状態移行（ディスクレイアウト）">
診断は古いオンディスクレイアウトを現在の構造へ移行できる。
<Accordion title="2g. セッションルートのクリーンアップ">
doctor は、設定済みのデフォルト/フォールバックモデルまたはランタイムを Codex のような Plugin 所有ルートから移動した後に、古くなった自動作成ルート状態がないかアクティブセッションストアもスキャンします。
`openclaw doctor --fix` は、所有ルートが設定されなくなった場合に、`modelOverrideSource: "auto"` モデルピン、ランタイムモデルメタデータ、固定ハーネス ID、CLI セッションバインディング、自動 auth-profile オーバーライドなど、自動作成された古い状態をクリアできます。明示的なユーザー選択またはレガシーセッションのモデル選択は手動レビュー対象として報告され、そのまま残されます。そのルートをもう意図していない場合は、`/model ...`、`/new` で切り替えるか、セッションをリセットしてください。
</Accordion>
<Accordion title="3. レガシー状態の移行（ディスクレイアウト）">
doctor は、古いディスク上レイアウトを現在の構造へ移行できます。
- セッションストア + トランスクリプト:
- `~/.openclaw/sessions/` から `~/.openclaw/agents/<agentId>/sessions/` へ
@ -287,209 +291,209 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- レガシー `~/.openclaw/credentials/*.json` から（`oauth.json` を除く）
- `~/.openclaw/credentials/whatsapp/<accountId>/...` へ（デフォルトアカウント ID: `default`）
これらの移行はベストエフォートで冪等である。診断は、バックアップとしてレガシーフォルダーを残す場合に警告を出す。Gateway/CLI も起動時にレガシーセッションとエージェントディレクトリを自動移行するため、履歴/認証/モデルは手動の診断実行なしでエージェントごとのパスに配置される。WhatsApp 認証は意図的に `openclaw doctor` 経由でのみ移行される。Talk プロバイダー/プロバイダーマップ正規化は現在、構造的等価性で比較するため、キー順序のみの差分が、何もしない `doctor --fix` 変更を繰り返し発生させることはなくなった。
これらの移行はベストエフォートで冪等です。doctor は、レガシーフォルダーをバックアップとして残した場合に警告を出します。Gateway/CLI も起動時にレガシーのセッション + エージェントディレクトリを自動移行するため、履歴/認証/モデルは手動で doctor を実行しなくてもエージェントごとのパスに配置されます。WhatsApp 認証は意図的に `openclaw doctor` 経由でのみ移行されます。Talk プロバイダー/プロバイダーマップの正規化は現在、構造的等価性で比較するため、キー順序だけの差分によって `doctor --fix` の no-op 変更が繰り返し発生することはなくなりました。
</Accordion>
<Accordion title="3a. レガシー Plugin マニフェスト移行">
診断は、インストール済みのすべての Plugin マニフェストをスキャンし、非推奨のトップレベル機能キー（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）を探す。見つかった場合、それらを `contracts` オブジェクトへ移動し、マニフェストファイルをその場で書き換えることを提案する。この移行は冪等である。`contracts` キーにすでに同じ値がある場合、データを重複させずにレガシーキーが削除される。
<Accordion title="3a. レガシー Plugin マニフェストの移行">
doctor は、インストール済みのすべての Plugin マニフェストをスキャンし、非推奨のトップレベル capability キー（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）を探します。見つかった場合、それらを `contracts` オブジェクトへ移動し、マニフェストファイルをその場で書き換えることを提案します。この移行は冪等です。`contracts` キーにすでに同じ値がある場合、データを重複させずにレガシーキーが削除されます。
</Accordion>
<Accordion title="3b. レガシー Cron ストア移行">
診断は、Cron ジョブストア（デフォルトでは `~/.openclaw/cron/jobs.json`、またはオーバーライドされている場合は `cron.store`）についても、スケジューラーが互換性のために引き続き受け入れる古いジョブ形状を確認する。
<Accordion title="3b. レガシー cron ストアの移行">
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` を使用してください。
</Accordion>
<Accordion title="3c. セッションロックのクリーンアップ">
診断機能は、すべてのエージェントセッションディレクトリで古い書き込みロックファイルをスキャンします。これは、セッションが異常終了したときに残されたファイルです。見つかった各ロックファイルについて、パス、PID、その PID がまだ生存しているかどうか、ロックの経過時間、古いと見なされるかどうか（停止した PID または 30 分超）を報告します。`--fix` / `--repair` モードでは、古いロックファイルを自動的に削除します。それ以外の場合は注記を表示し、`--fix` を付けて再実行するよう案内します。
Doctor は、古い書き込みロックファイル（セッションが異常終了したときに残されたファイル）を各エージェントセッションディレクトリでスキャンします。見つかった各ロックファイルについて、パス、PID、PID がまだ生存しているかどうか、ロックの経過時間、古いと見なされるかどうか（停止した PID または 30 分超）を報告します。`--fix` / `--repair` モードでは、古いロックファイルを自動的に削除します。それ以外の場合は注記を出力し、`--fix` 付きで再実行するよう指示します。
</Accordion>
<Accordion title="3d. セッショントランスクリプトのブランチ修復">
診断機能は、2026.4.24 のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形状について、エージェントセッション JSONL ファイルをスキャンします。これは、OpenClaw 内部ランタイムコンテキストを含む放棄されたユーザーターンと、同じ表示ユーザープロンプトを含むアクティブな兄弟ブランチです。`--fix` / `--repair` モードでは、診断機能は影響を受ける各ファイルを元のファイルの隣にバックアップし、トランスクリプトをアクティブなブランチに書き換えるため、gateway 履歴とメモリリーダーに重複ターンが見えなくなります。
Doctor は、2026.4.24 のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形状について、エージェントセッションの JSONL ファイルをスキャンします。これは、OpenClaw 内部ランタイムコンテキストを含む放棄されたユーザーターンと、同じ可視ユーザープロンプトを含むアクティブな兄弟が存在する状態です。`--fix` / `--repair` モードでは、doctor は影響を受ける各ファイルを元ファイルの隣にバックアップし、Gateway 履歴とメモリリーダーが重複ターンを見なくなるよう、トランスクリプトをアクティブなブランチへ書き換えます。
</Accordion>
<Accordion title="4. 状態整合性チェック（セッション永続化、ルーティング、安全性）">
状態ディレクトリは運用上の中枢です。これが消えると、別の場所にバックアップがない限り、セッション、認証情報、ログ、設定を失います。
<Accordion title="4. 状態の整合性チェック（セッション永続化、ルーティング、安全性）">
状態ディレクトリは運用上の中枢です。これが消えると、（別の場所にバックアップがない限り）セッション、認証情報、ログ、設定が失われます。
診断機能が確認する内容:
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` へ制限することを提案します。
</Accordion>
<Accordion title="5. モデル認証の健全性（OAuth 期限切れ）">
診断機能は認証ストア内の 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 は、次の理由で一時的に使用できない認証プロファイルも報告します。
- 短いクールダウン（レート制限/タイムアウト/認証失敗）
- 長い無効化（請求/クレジット失敗）
- より長い無効化（請求/クレジットの失敗）
</Accordion>
<Accordion title="6. フックモデル検証">
`hooks.gmail.model` が設定されている場合、診断機能はモデル参照をカタログおよび許可リストと照合して検証し、解決できない、または許可されていない場合に警告します。
`hooks.gmail.model` が設定されている場合、doctor はモデル参照をカタログと許可リストに照らして検証し、解決できない場合や許可されていない場合に警告します。
</Accordion>
<Accordion title="7. サンドボックスイメージ修復">
サンドボックス化が有効な場合、診断機能は Docker イメージを確認し、現在のイメージがない場合はビルドするかレガシー名へ切り替えることを提案します。
サンドボックスが有効な場合、doctor は Docker イメージをチェックし、現在のイメージが欠落している場合はビルドするかレガシー名へ切り替えることを提案します。
</Accordion>
<Accordion title="7b. Plugin インストールのクリーンアップ">
診断機能は、`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 作業のままです。
</Accordion>
<Accordion title="8. Gateway サービスの移行とクリーンアップのヒント">
診断機能はレガシー Gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して現在の Gateway ポートを使う OpenClaw サービスをインストールすることを提案します。追加の Gateway 風サービスをスキャンし、クリーンアップのヒントを出力することもできます。プロファイル名付きの OpenClaw Gateway サービスは第一級のものと見なされ、「追加」としてフラグ付けされません。
<Accordion title="8. 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` を設定してください。
</Accordion>
<Accordion title="8b. 起動時の Matrix 移行">
Matrix チャンネルアカウントに保留中または対処可能なレガシー状態移行がある場合、診断機能は（`--fix` / `--repair` モードで）移行前スナップショットを作成し、その後ベストエフォートの移行手順を実行します。レガシー Matrix 状態移行と、レガシー暗号化状態の準備です。どちらの手順も致命的ではなく、エラーはログに記録され、起動は続行されます。読み取り専用モード（`--fix` なしの `openclaw doctor`）では、このチェックは完全にスキップされます。
<Accordion title="8b. 起動時 Matrix 移行">
Matrix チャンネルアカウントに保留中または対応可能なレガシー状態移行がある場合、doctor は（`--fix` / `--repair` モードで）移行前スナップショットを作成してから、ベストエフォートの移行手順を実行します。レガシー Matrix 状態移行とレガシー暗号化状態の準備です。どちらの手順も致命的ではありません。エラーはログに記録され、起動は継続します。読み取り専用モード（`--fix` なしの `openclaw doctor`）では、このチェックは完全にスキップされます。
</Accordion>
<Accordion title="8c. デバイスペアリングと認証のずれ">
診断機能は通常の健全性チェックの一部として、デバイスペアリング状態を検査するようになりました。
<Accordion title="8c. デバイスペアリングと認証ドリフト">
Doctor は通常のヘルスパスの一部として、デバイスペアリング状態も検査するようになりました。
報告内容:
- 保留中の初回ペアリングリクエスト
- すでにペアリング済みのデバイスに対する保留中のロール昇格
- すでにペアリング済みのデバイスに対する保留中のスコープ昇格
- 初回ペアリングリクエストの保留
- すでにペアリング済みのデバイスに対するロールアップグレードの保留
- すでにペアリング済みのデバイスに対するスコープアップグレードの保留
- デバイス ID はまだ一致しているが、デバイス ID 情報が承認済みレコードと一致しなくなった公開鍵不一致の修復
- 承認済みロールの有効なトークンが欠落しているペアリング済みレコード
- スコープが承認済みペアリング基準から外れたペアリング済みトークン
- 現在のマシン用のローカルキャッシュ済みデバイストークンエントリのうち、Gateway 側のトークンローテーションより古いもの、または古いスコープメタデータを持つもの
- 承認済みロールのアクティブなトークンが欠落しているペアリング済みレコード
- スコープが承認済みペアリングベースラインの外へドリフトしたペアリング済みトークン
- Gateway 側のトークンローテーションより前の、または古いスコープメタデータを持つ、現在のマシン用のローカルキャッシュ済みデバイストークンエントリ
診断機能はペアリングリクエストの自動承認やデバイストークンの自動ローテーションを行いません。代わりに正確な次の手順を出力します:
Doctor はペアリングリクエストの自動承認やデバイストークンの自動ローテーションは行いません。代わりに正確な次の手順を出力します。
- `openclaw devices list` で保留中のリクエストを確認する
- `openclaw devices approve <requestId>` で正確なリクエストを承認する
- `openclaw devices rotate --device <deviceId> --role <role>` で新しいトークンをローテーションする
- `openclaw devices remove <deviceId>` で古いレコードを削除して再承認する
これにより、よくある「すでにペアリング済みなのに、まだペアリングが必要になる」穴を塞ぎます。診断機能は、初回ペアリング、保留中のロール/スコープ昇格、古いトークン/デバイス ID 情報のずれを区別するようになりました。
これにより、一般的な「すでにペアリング済みなのに、まだペアリングが必要と表示される」穴が塞がれます。doctor は、初回ペアリング、保留中のロール/スコープアップグレード、古いトークン/デバイス ID 情報のドリフトを区別するようになりました。
</Accordion>
<Accordion title="9. セキュリティ警告">
プロバイダーが許可リストなしで DM に開放されている場合、またはポリシーが危険な方法で設定されている場合、診断機能は警告を出力します。
Doctor は、プロバイダーが許可リストなしで DM に開かれている場合、またはポリシーが危険な方法で設定されている場合に警告を出します。
</Accordion>
<Accordion title="10. systemd linger（Linux）">
systemd ユーザーサービスとして実行している場合、診断機能はログアウト後も gateway が稼働し続けるよう lingering が有効であることを確認します。
systemd ユーザーサービスとして実行している場合、doctor はログアウト後も Gateway が稼働し続けるよう linger が有効であることを確認します。
</Accordion>
<Accordion title="11. ワークスペース状態（Skills、plugins、レガシーディレクトリ）">
診断機能は、デフォルトエージェントのワークスペース状態の概要を出力します:
<Accordion title="11. ワークスペース状態（Skills、Plugin、レガシーディレクトリ）">
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 レジストリから出力された読み込み時の警告やエラーを表示します。
</Accordion>
<Accordion title="11b. ブートストラップファイルサイズ">
診断機能は、ワークスペースのブートストラップファイル（たとえば `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` を調整するためのヒントを出力します。
</Accordion>
<Accordion title="11d. 古いチャンネル Plugin のクリーンアップ">
`openclaw doctor --fix` が欠落しているチャンネル Plugin を削除すると、その Plugin を参照していたぶら下がったチャンネルスコープ設定も削除します。`channels.<id>` エントリ、チャンネル名を指定していた Heartbeat ターゲット、`agents.*.models["<channel>/*"]` オーバーライドです。これにより、チャンネルランタイムはなくなっているのに、設定が gateway にそれへのバインドを求め続ける Gateway 起動ループを防ぎます。
`openclaw doctor --fix` が欠落したチャンネル Plugin を削除する場合、その Plugin を参照していたぶら下がったチャンネルスコープ設定も削除します。つまり、`channels.<id>` エントリ、そのチャンネル名を指定した Heartbeat ターゲット、`agents.*.models["<channel>/*"]` オーバーライドです。これにより、チャンネルランタイムが消えているのに設定が Gateway にバインドを求め続ける Gateway ブートループを防ぎます。
</Accordion>
<Accordion title="11c. シェル補完">
診断機能は、現在のシェル（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` を実行してください。
</Accordion>
<Accordion title="12. Gateway 認証チェック（ローカルトークン）">
診断機能はローカル Gateway トークン認証の準備状態を確認します。
Doctor はローカル Gateway トークン認証の準備状態をチェックします。
- トークンモードでトークンが必要だがトークンソースが存在しない場合、診断機能は生成を提案します。
- `gateway.auth.token` が SecretRef 管理だが利用できない場合、診断機能は警告し、平文で上書きしません。
- トークンモードでトークンが必要だがトークンソースが存在しない場合、doctor は生成を提案します。
- `gateway.auth.token` が SecretRef 管理だが利用できない場合、doctor は警告し、それを平文で上書きしません。
- `openclaw doctor --generate-gateway-token` は、トークン SecretRef が設定されていない場合にのみ生成を強制します。
</Accordion>
<Accordion title="12b. 読み取り専用の 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 が欠落していると誤報告したりせずに自動解決をスキップします。
</Accordion>
<Accordion title="13. Gateway ヘルスチェック + 再起動">
Doctor はヘルスチェックを実行し、Gateway が正常でないように見える場合は再起動を提案します。
doctor はヘルスチェックを実行し、Gateway が正常でないように見える場合は再起動を提案します。
</Accordion>
<Accordion title="13b. メモリ検索の準備状態">
Doctor は、設定されたメモリ検索の埋め込みプロバイダーがデフォルトのエージェントで準備できているかを確認します。動作は設定されたバックエンドとプロバイダーによって異なります。
<Accordion title="13b. メモリ検索の準備状況">
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` を使います。
</Accordion>
<Accordion title="14. チャンネルステータス警告">
Gateway が正常な場合、doctor はチャンネルステータス検査を実行し、推奨修正とともに警告を報告します。
<Accordion title="14. チャネルステータスの警告">
Gateway が正常な場合、doctor はチャネルステータス probe を実行し、推奨修正とともに警告を報告します。
</Accordion>
<Accordion title="15. スーパーバイザー設定の監査 + 修復">
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` により、いつでも完全な書き換えを強制できます。
</Accordion>
<Accordion title="16. Gateway ランタイム + ポート診断">
Doctor はサービスランタイム（PID、最後の終了ステータス）を検査し、サービスがインストール済みだが実際には実行されていない場合に警告します。また、Gateway ポート（デフォルトは `18789`）でのポート衝突を確認し、考えられる原因（Gateway がすでに実行中、SSH トンネル）を報告します。
doctor は service runtime（PID、last exit status）を検査し、service がインストールされているものの実際には実行されていない場合に警告します。また Gateway port（デフォルト `18789`）での port collisions を確認し、可能性の高い原因（Gateway がすでに実行中、SSH tunnel）を報告します。
</Accordion>
<Accordion title="17. Gateway ランタイムのベストプラクティス">
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 に書き込まれます。
</Accordion>
<Accordion title="18. 設定の書き込み + ウィザードメタデータ">
Doctor は設定変更を永続化し、doctor 実行を記録するためにウィザードメタデータを刻印します。
<Accordion title="18. 設定書き込み + ウィザードメタデータ">
doctor は設定変更を永続化し、doctor run を記録するためにウィザードメタデータを刻印します。
</Accordion>
<Accordion title="19. ワークスペースのヒント（バックアップ + メモリシステム）">
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)

98
docs/ja-JP/gateway/logging.md
View File

@ -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` を使用）
これにより、既存のファイルログを安定させたまま、対話的な出力をスキャンしやすくできます。
これにより、既存のファイルログを安定させたまま、対話型出力をスキャンしやすくできます。
## 関連

127
docs/ja-JP/help/debugging.md
View File

@ -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 <path>` を使用します。
ベンチマーク対象の子プロセスでデフォルトの `--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
```
<Note>
`--dev` は**グローバル**プロファイルフラグであり、一部のランナーに消費されます。明示的に指定する必要がある場合は、env var 形式を使用します。
`--dev` は**グローバル**プロファイルフラグであり、一部のランナーに消費されます。明示的に指定する必要がある場合は、環境変数形式を使用してください。
```bash
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
@ -204,11 +205,10 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
</Note>
`--reset` は設定、資格情報、セッション、開発ワークスペースを消去し（`rm` ではなく
`trash` を使用）、デフォルトの開発セットアップを再作成します。
`--reset` は設定、認証情報、セッション、開発ワークスペースを消去し（`rm` ではなく `trash` を使用）、その後デフォルトの開発セットアップを再作成します。
<Tip>
非開発 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 を削除してください。
## 関連

315
docs/ja-JP/help/faq-models.md
View File

@ -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) を参照してください。
## モデル: デフォルト、選択、エイリアス、切り替え
<AccordionGroup>
<Accordion title='「デフォルトモデル」とは何ですか？'>
<Accordion title='「default model」とは何ですか？'>
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` は**明示的に**設定してください。
</Accordion>
<Accordion title="どのモデルがおすすめですか？">
**推奨デフォルト:** 使用しているプロバイダースタックで利用可能な最強の最新世代モデルを使用してください。
**ツールを有効にしたエージェント、または信頼できない入力を扱うエージェント:** コストよりもモデルの性能を優先してください。
**日常的/低リスクのチャット:** より安価なフォールバックモデルを使用し、エージェントのロールでルーティングしてください。
<Accordion title="どのモデルを推奨しますか？">
**推奨デフォルト:** 利用しているプロバイダースタックで使える最も強力な最新世代モデルを使用してください。
**ツール対応または信頼できない入力を扱うエージェント:** コストよりモデルの強さを優先してください。
**日常的/低リスクのチャット:** 安価なフォールバックモデルを使い、エージェントの役割でルーティングしてください。
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)。
</Accordion>
<Accordion title="設定を消さずにモデルを切り替えるには？">
**モデルコマンド**を使用するか、**モデル**フィールドだけを編集してください。設定全体の置き換えは避けてください。
**モデルコマンド**を使うか、**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:
</Accordion>
<Accordion title="セルフホストモデル（llama.cpp、vLLM、Ollama）は使えますか？">
はい。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/<model>` を使用してください
- `Cloud + Local` では、クラウドモデルに加えてローカルの Ollama モデルを利用できます
- `kimi-k2.5:cloud` などのクラウドモデルはローカル取得を必要としません
- 手動で切り替えるには、`openclaw models list` と `openclaw models set ollama/<model>` を使用します
セキュリティ上の注意: 小さいモデルや大きく量子化されたモデルは、プロンプト
インジェクションに対してより脆弱です。ツールを使用できるボットには**大規模モデル**を強く推奨します。
セキュリティメモ: 小さいモデルや大きく量子化されたモデルは、プロンプト
インジェクションに対してより脆弱です。ツールを使用できるボットには、**大規模モデル**を強く推奨します。
それでも小さいモデルを使いたい場合は、サンドボックス化と厳格なツール許可リストを有効にしてください。
ドキュメント: [Ollama](/ja-JP/providers/ollama)、[ローカルモデル](/ja-JP/gateway/local-models)、
@ -98,9 +98,9 @@ x-i18n:
</Accordion>
<Accordion title="OpenClaw、Flawd、Krill はどのモデルを使っていますか？">
- これらのデプロイは異なる場合があり、時間とともに変わる可能性があります。固定のプロバイダー推奨はありません。
- 各 Gateway の現在のランタイム設定を `openclaw models status` で確認してください。
- セキュリティに敏感なエージェントやツールを有効にしたエージェントには、利用可能な最強の最新世代モデルを使用してください。
- これらのデプロイは異なる場合があり、時間とともに変更されることがあります。固定のプロバイダー推奨はありません。
- 各 Gateway で `openclaw models status` を使い、現在のランタイム設定を確認してください。
- セキュリティ上重要なエージェントやツール対応エージェントには、利用可能な最も強力な最新世代モデルを使用してください。
</Accordion>
@ -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 <default provider/model>` を送信する）してください。
どの認証プロファイルがアクティブかを確認するには `/model status` を使用してください。
デフォルトに戻したい場合は、`/model` から選ぶか（または `/model <default provider/model>` を送信します）。
どの auth profile がアクティブか確認するには、`/model status` を使用してください。
</Accordion>
<Accordion title="日常タスクには GPT 5.5、コーディングには Codex 5.5 を使えますか？">
はい。モデル選択とランタイム選択は別々に扱ってください。
はい。モデルの選択とランタイムの選択は分けて考えてください。
- **ネイティブ 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) を参照してください。
</Accordion>
<Accordion title="GPT 5.5 の高速モードを設定するには？">
セッションの切り替え、または設定デフォルトのいずれかを使用します。
セッショントグルまたは設定デフォルトのどちらかを使用します。
- **セッション単位:** セッションが `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) を参照してください。
</Accordion>
<Accordion title='「Model ... is not allowed」と表示され、その後返信がないのはなぜですか？'>
`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 <provider> 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` コマンドを再試行してください。
</Accordion>
<Accordion title='「Unknown model: minimax/MiniMax-M2.7」と表示されるのはなぜですか？'>
これは、**プロバイダーが設定されていない**（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) を参照してください。
</Accordion>
<Accordion title="MiniMax をデフォルトにし、複雑なタスクには OpenAI を使えますか？">
はい。**MiniMax をデフォルト**として使用し、必要に応じて**セッション単位**でモデルを切り替えてください。
<Accordion title="MiniMax をデフォルトにし、複雑なタスクに OpenAI を使えますか？">
はい。**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)。
</Accordion>
<Accordion title="opus / sonnet / gpt は組み込みショートカットですか？">
はい。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`
同じ名前で独自のエイリアスを設定した場合は、その値が優先されます。
同じ名前で独自のエイリアスを設定した場合は、あなたの値が優先されます。
</Accordion>
<Accordion title="モデルショートカット（エイリアス）を定義/上書きするには？">
エイリアスは `agents.defaults.models.<modelId>.alias` から来ます。例:
エイリアスは `agents.defaults.models.<modelId>.alias` から取得されます。例:
```json5
{
@ -309,7 +311,7 @@ x-i18n:
</Accordion>
<Accordion title="OpenRouter や Z.AI など他のプロバイダーのモデルを追加するには？">
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/<agentId>/agent/auth-profiles.json
@ -350,10 +352,10 @@ x-i18n:
修正方法:
- `openclaw agents add <id>` を実行し、ウィザード中に認証を設定します。
- または、メインエージェントの認証ストアから、新しいエージェントの認証ストアへ、移植可能な静的 `api_key` / `token` プロファイルだけをコピーします。
- OAuth プロファイルでは、新しいエージェントが独自のアカウントを必要とする場合、そのエージェントからサインインします。それ以外の場合、OpenClaw はリフレッシュトークンを複製せずにデフォルト/メインエージェントを参照できます。
- または、メインエージェントの認証ストアから新しいエージェントの認証ストアへ、移植可能な静的 `api_key` / `token` プロファイルだけをコピーします。
- OAuthプロファイルの場合、そのエージェント固有のアカウントが必要なときは新しいエージェントからサインインします。それ以外の場合、OpenClaw はリフレッシュトークンを複製せずにデフォルト/メインエージェントを読み取りに行けます。
エージェント間で `agentDir` を再利用**しないでください**。認証/セッションの衝突が発生します。
複数のエージェントで `agentDir` を再利用しないでください。認証/セッションの衝突を引き起こします。
</Accordion>
</AccordionGroup>
@ -361,116 +363,147 @@ x-i18n:
## モデルのフェイルオーバーと「All models failed」
<AccordionGroup>
<Accordion title="フェイルオーバーはどのように動作しますか？">
フェイルオーバーは 2 段階で発生します。
<Accordion title="フェイルオーバーはどのように動作しますか?">
フェイルオーバーは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.` のような汎用内部フォールバックテキストは保守的に扱われ、それ単体ではモデルフォールバックをトリガーしません。
</Accordion>
<Accordion title='「No credentials found for profile anthropic:default」はどういう意味ですか？'>
これは、システムが認証プロファイル ID `anthropic:default` を使用しようとしたものの、想定される認証ストア内でその認証情報を見つけられなかったことを意味します。
<Accordion title='「No credentials found for profile anthropic:default」とは何ですか?'>
これは、システムが認証プロファイルID `anthropic:default` を使用しようとしたものの、想定される認証ストア内でその認証情報を見つけられなかったことを意味します。
**修正チェックリスト:**
- **認証プロファイルの保存場所を確認する**（新しいパスとレガシーパス）
- **認証プロファイルの保存場所を確認する**（新旧のパス）
- 現行: `~/.openclaw/agents/<agentId>/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マシン上に存在します。
</Accordion>
<Accordion title="なぜ Google Gemini も試して失敗したのですか？">
モデル設定にフォールバックとして Google Gemini が含まれている（または Gemini の省略形に切り替えた）場合、OpenClaw はモデルフォールバック中にそれを試します。Google の認証情報を設定していない場合、`No API key found for provider "google"` が表示されます。
<Accordion title="なぜ Google Gemini も試して失敗したのですか?">
モデル設定にフォールバックとして 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` を設定してください。
</Accordion>
</AccordionGroup>
## 認証プロファイル: 概要と管理方法
関連: [/concepts/oauth](/ja-JP/concepts/oauth)（OAuth フロー、トークン保存、マルチアカウントパターン）
関連: [/concepts/oauth](/ja-JP/concepts/oauth)（OAuthフロー、トークン保存、マルチアカウントパターン）
<AccordionGroup>
<Accordion title="認証プロファイルとは何ですか？">
認証プロファイルとは、プロバイダーに紐づけられた名前付きの認証情報レコード（OAuth または API キー）です。プロファイルは次にあります。
<Accordion title="認証プロファイルとは何ですか?">
認証プロファイルは、プロバイダーに紐づけられた名前付きの認証情報レコード（OAuthまたはAPIキー）です。プロファイルは次の場所にあります。
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
</Accordion>
<Accordion title="典型的なプロファイル ID は何ですか？">
OpenClaw は次のような、プロバイダー接頭辞付きの ID を使用します。
- `anthropic:default`（メール ID が存在しない場合によく使われます）
- OAuth ID 用の `anthropic:<email>`
- 選択したカスタム ID（例: `anthropic:work`）
シークレットを出力せずに保存済みプロファイルを調べるには、`openclaw models auth list` を実行します（必要に応じて `--provider <id>` または `--json`）。詳細は [Models CLI](/ja-JP/cli/models#openclaw-models-auth-list) を参照してください。
</Accordion>
<Accordion title="最初に試す認証プロファイルを制御できますか？">
はい。設定では、プロファイルの任意メタデータと、プロバイダーごとの順序（`auth.order.<provider>`）をサポートしています。これはシークレットを保存しません。ID をプロバイダー/モードに対応付け、ローテーション順序を設定します。
<Accordion title="一般的なプロファイルIDは何ですか?">
OpenClaw は次のような、プロバイダー接頭辞付きIDを使用します。
OpenClaw は、プロファイルが短い**クールダウン**（レート制限/タイムアウト/認証失敗）またはより長い**無効化**状態（課金/クレジット不足）にある場合、一時的にスキップすることがあります。これを確認するには、`openclaw models status --json` を実行して `auth.unusableProfiles` を確認します。調整: `auth.cooldowns.billingBackoffHours*`。
- `anthropic:default`（メールIDがない場合によく使われます）
- OAuth ID用の `anthropic:<email>`
- 選択したカスタムID（例: `anthropic:work`）
レート制限クールダウンはモデルスコープにできます。あるモデルでクールダウン中のプロファイルでも、同じプロバイダー上の兄弟モデルでは引き続き使用可能なことがあります。一方、課金/無効化ウィンドウは引き続きプロファイル全体をブロックします。
</Accordion>
CLI を使用して、**エージェントごと**の順序オーバーライド（そのエージェントの `auth-state.json` に保存）も設定できます。
<Accordion title="最初に試す認証プロファイルを制御できますか?">
はい。設定では、プロファイルの任意メタデータと、プロバイダーごとの順序（`auth.order.<provider>`）をサポートしています。これはシークレットを保存しません。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` を報告します。
</Accordion>
<Accordion title="OAuth と API キーの違いは何ですか？">
<Accordion title="OAuthとAPIキーの違いは何ですか?">
OpenClaw は両方をサポートしています。
- **OAuth** は、多くの場合サブスクリプションアクセスを活用します（該当する場合）。
- **API キー**は従量課金を使用します。
- **OAuth** は、多くの場合（該当する場合）サブスクリプションアクセスを利用します。
- **APIキー** はトークン従量課金を使用します。
ウィザードは、Anthropic Claude CLI、OpenAI Codex OAuth、および API キーを明示的にサポートしています。
ウィザードは Anthropic Claude CLI、OpenAI Codex OAuth、APIキーを明示的にサポートしています。
</Accordion>
</AccordionGroup>
## 関連
- [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)

263
docs/ja-JP/help/testing-updates-plugins.md
View File

@ -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`。
ベースラインバージョン、候補バージョン、シナリオ、フェーズタイミング、レシピ手順を含みます。
リリース全体の傘を再実行するよりも、同じパッケージ成果物で失敗した厳密なレーンを
再実行することを優先します。
リリース全体の傘を再実行するよりも、同じパッケージ成果物で失敗した正確なレーンを再実行することを優先します。

808
docs/ja-JP/help/testing.md
View File

File diff suppressed because it is too large Load Diff

288
docs/ja-JP/plugins/bundles.md
View File

@ -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ツールのようなネイティブ機能へマッピングするコンテンツとメタデータのパックです。
<Info>
バンドルはネイティブ OpenClaw Plugin と**同じではありません**。ネイティブ Plugin は
プロセス内で実行され、任意の capability を登録できます。バンドルは、選択的な機能マッピングと
より狭い信頼境界を持つコンテンツパックです。
バンドルは、ネイティブOpenClaw Pluginと**同じではありません**。ネイティブPluginは
インプロセスで実行され、任意の機能を登録できます。バンドルはコンテンツパックであり、
選択的な機能マッピングと、より狭い信頼境界を持ちます。
</Info>
## バンドルが存在する理由
有用な Plugin の多くは Codex、Claude、Cursor 形式で公開されています。
作者にネイティブ OpenClaw Plugin として書き直すことを求める代わりに、OpenClaw は
これらの形式を検出し、対応しているコンテンツをネイティブ機能セットにマッピングします。
つまり、Claude コマンドパックや Codex skill バンドルをインストールして、すぐに使えます。
多くの有用なPluginは、Codex、Claude、またはCursor形式で公開されています。作者に
ネイティブOpenClaw Pluginとして書き直すことを求める代わりに、OpenClawは
これらの形式を検出し、対応するコンテンツをネイティブ機能セットへマッピングします。
つまり、ClaudeコマンドパックやCodex skillバンドルをインストールして、
すぐに使えます。
## バンドルをインストールする
<Steps>
<Step title="ディレクトリ、アーカイブ、マーケットプレイスからインストールする">
<Step title="ディレクトリ、アーカイブ、またはマーケットプレイスからインストールする">
```bash
# Local directory
# ローカルディレクトリ
openclaw plugins install ./my-bundle
# Archive
# アーカイブ
openclaw plugins install ./my-bundle.tgz
# Claude marketplace
# Claudeマーケットプレイス
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
@ -53,7 +56,7 @@ OpenClaw は、**Codex**、**Claude**、**Cursor** の 3 つの外部エコシ
openclaw plugins inspect <id>
```
バンドルは `Format: bundle` と表示され、subtype は `codex`、`claude`、または `cursor` です。
バンドルは、`codex`、`claude`、または`cursor`のサブタイプを持つ`Format: bundle`として表示されます。
</Step>
@ -62,62 +65,62 @@ OpenClaw は、**Codex**、**Claude**、**Cursor** の 3 つの外部エコシ
openclaw gateway restart
```
マッピングされた機能（Skills、hooks、MCP ツール、LSP デフォルト）は次のセッションで利用できます。
マッピングされた機能（Skills、フック、MCPツール、LSPデフォルト）は次のセッションで利用できます。
</Step>
</Steps>
## 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 <id>` には表示されます
- 有効なClaudeバンドルはLSPサーバー設定を提供できます
- OpenClawは`.lsp.json`に加え、マニフェスト宣言の`lspServers`パスを読み込みます
- バンドルLSP設定は、有効な埋め込みPi LSPデフォルトへマージされます
- 現在実行可能なのは、対応済みのstdioバックエンドLSPサーバーのみです。非対応の
トランスポートも`openclaw plugins inspect <id>`には表示されます
### 検出されるが実行されないもの
これらは認識され診断に表示されますが、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インライン/アプリメタデータ
## バンドル形式
<AccordionGroup>
<Accordion title="Codex バンドル">
<Accordion title="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に最もよく適合します。
</Accordion>
<Accordion title="Claude バンドル">
2 つの検出モード:
<Accordion title="Claudeバンドル">
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`は検出されますが実行されません
- マニフェスト内のカスタムコンポーネントパスは加算的です（デフォルトを置き換えるのではなく拡張します）
</Accordion>
<Accordion title="Cursor バンドル">
<Accordion title="Cursorバンドル">
マーカー: `.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`は検出のみです
</Accordion>
</AccordionGroup>
## 検出の優先順位
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 として扱う必要があります。
これにより、バンドルはデフォルトでより安全になりますが、それでもサードパーティ
バンドルは、公開する機能について信頼済みコンテンツとして扱う必要があります。
## トラブルシューティング
<AccordionGroup>
<Accordion title="バンドルは検出されるが capability が実行されない">
`openclaw plugins inspect <id>` を実行してください。capability が listed されているものの
not wired と表示される場合、それは product limit であり、壊れたインストールではありません。
<Accordion title="バンドルは検出されるが機能が実行されない">
`openclaw plugins inspect <id>`を実行します。機能が一覧表示されているものの
未接続としてマークされている場合、それは製品上の制限であり、インストールの破損ではありません。
</Accordion>
<Accordion title="Claude コマンドファイルが表示されない">
バンドルが有効化されており、markdown ファイルが検出済みの
`commands/` または `skills/` ルート内にあることを確認してください。
<Accordion title="Claudeコマンドファイルが表示されない">
バンドルが有効であり、Markdownファイルが検出済みの
`commands/`または`skills/`ルート内にあることを確認してください。
</Accordion>
<Accordion title="Claude 設定が適用されない">
`settings.json` からの組み込み Pi 設定のみが対応しています。OpenClaw は
バンドル設定を raw config patches として扱いません。
<Accordion title="Claude設定が適用されない">
`settings.json`からの埋め込みPi設定のみが対応対象です。OpenClawは
バンドル設定を生の設定パッチとして扱いません。
</Accordion>
<Accordion title="Claude hooks が実行されない">
`hooks/hooks.json` は detect-only です。実行可能な hooks が必要な場合は、
OpenClaw hook-pack レイアウトを使用するか、ネイティブ Plugin を同梱してください。
<Accordion title="Claudeフックが実行されない">
`hooks/hooks.json`は検出のみです。実行可能なフックが必要な場合は、
OpenClawフックパックレイアウトを使用するか、ネイティブPluginを提供してください。
</Accordion>
</AccordionGroup>
## 関連
- [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) — ネイティブマニフェストスキーマ

638
docs/ja-JP/plugins/codex-harness.md
View File

@ -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/<model>` に変更し、
- PI 経由の ChatGPT/Codex OAuth を意図していた場合、**変更は不要**です。
- ネイティブアプリサーバー実行を意図していた場合は、モデルを `openai/<model>` に変更し、
`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 スレッド `<id>` をここで再開して」 | `/codex resume <id>` |
| 「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 スレッド `<id>` をここで再開する」 | `/codex resume <id>` |
| 「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 <marketplace-source>`
- `/codex computer-use install --marketplace-path <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 <thread-id>` は、現在の 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 <thread-id>` のような形で、
ネイティブ Codex スレッドを開くため、会話を調査したり、ローカルで続行したり、
Codex が特定のツールまたは計画を選んだ理由を尋ねたりできます。
2. 診断リクエストを一度承認します。この承認によりローカル Gateway 診断 zip が作成され、セッションが Codex ハーネスを使用しているため、関連する Codex フィードバックバンドルも OpenAI サーバーに送信されます。
3. 完了した診断返信をバグレポートまたはサポートスレッドにコピーします。これには、ローカルバンドルパス、プライバシー概要、OpenClaw セッション ID、Codex スレッド ID、各 Codex スレッドの `Inspect locally` 行が含まれます。
4. 実行を自分でデバッグしたい場合は、表示された `Inspect locally` コマンドをターミナルで実行します。これは `codex resume <thread-id>` のような形で、ネイティブ 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 <thread-id>` コマンドが一覧表示されます。承認を拒否または無視した場合、OpenClaw はそれらの Codex ID を表示しません。このアップロードはローカル Gateway 診断エクスポートを置き換えるものではありません。
承認された Codex アップロードは、Codex アプリサーバーの `feedback/upload` を呼び出し、利用可能な場合は、一覧にある各スレッドと生成された Codex サブスレッドのログを含めるようアプリサーバーに要求します。アップロードは Codex の通常のフィードバック経路を通じて OpenAI サーバーに送信されます。そのアプリサーバーで Codex フィードバックが無効になっている場合、コマンドはアプリサーバーエラーを返します。完了した診断返信には、送信されたスレッドのチャネル、OpenClaw セッション ID、Codex スレッド ID、ローカルの `codex resume <thread-id>` コマンドが一覧表示されます。承認を拒否または無視した場合、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 <thread-id>
```
チャネル会話でバグに気づき、問題のある Codex セッションを調査したい、ローカルで続行したい、または Codex が特定のツールや推論を選んだ理由を尋ねたい場合に使用します。通常、最も簡単な手順は、まず `/diagnostics [note]` を実行することです。承認後、完了したレポートに各 Codex スレッドが一覧表示され、たとえば `codex resume <thread-id>` のような `Inspect locally` コマンドが出力されます。そのコマンドを直接ターミナルにコピーできます。
チャネルの会話でバグに気付き、問題のある Codex セッションを調査したい場合、ローカルで続行したい場合、または特定のツールや推論の選択をした理由を Codex に尋ねたい場合に使います。通常、最も簡単な手順は、先に `/diagnostics [note]` を実行することです。承認後、完了したレポートには各 Codex スレッドが一覧表示され、たとえば `codex resume <thread-id>` のような `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)

64
docs/ja-JP/plugins/dependency-resolution.md
View File

@ -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 <spec> --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 <id>
@ -78,26 +78,26 @@ openclaw plugins install <source>
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/<id>` から読み込まれるため、パッケージローカルの workspace 依存関係が利用でき、編集内容が直接反映されます。ソース checkout 開発は pnpm のみ対応です。リポジトリルートで通常の `npm install` を実行することは、バンドル済み Plugin の依存関係を準備する方法としてサポートされていません。
ソース checkout では、OpenClaw はリポジトリを pnpm monorepo として扱います。`pnpm install` 後、バンドル Plugin は `extensions/<id>` から読み込まれるため、package-local な workspace 依存関係が利用可能になり、編集内容が直接反映されます。ソース checkout 開発は pnpm のみ対応です。リポジトリルートでの通常の `npm install` は、バンドル Plugin 依存関係を準備する方法としてサポートされていません。
| インストール形態 | バンドル済み Plugin の場所 | 依存関係の所有者 |
| -------------------------------- | ----------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw` | パッケージ内のビルド済みランタイムツリー | OpenClaw パッケージと明示的な Plugin install/update/doctor フロー |
| Git checkout plus `pnpm install` | `extensions/<id>` 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/<id>` 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 が残りません。
これらのパスはレガシーな残骸にすぎません。新規インストールで作成されるべきではありません。

82
docs/ja-JP/plugins/manage-plugins.md
View File

@ -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 <plugin-id> --runtime --json
```
ツール、フック、サービス、Gateway メソッド、Plugin 所有の CLI コマンドなどのランタイムサーフェスを Plugin が登録した証明が必要な場合は、`inspect --runtime` を使用します。
ツール、フック、サービス、Gateway メソッド、または Plugin が所有する CLI コマンドなどのランタイムサーフェスを
Plugin が登録したことを証明する必要がある場合は、`inspect --runtime` を使用してください。
## Plugin の更新
## Plugin を更新する
```bash
openclaw plugins update <plugin-id>
@ -77,18 +81,24 @@ openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
```
Plugin が `@beta` などの npm dist-tag からインストールされていた場合、後続の `update <plugin-id>` 呼び出しは記録済みのそのタグを再利用します。明示的な npm spec を渡すと、今後の更新で追跡されるインストール先がその spec に切り替わります。
Plugin が `@beta` などの npm dist-tag からインストールされた場合、以降の
`update <plugin-id>` 呼び出しでは、記録されたそのタグが再利用されます。明示的な 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 <plugin-id> --dry-run
@ -97,15 +107,19 @@ openclaw plugins uninstall <plugin-id> --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:<package>
openclaw plugins install <package>
```
裸の形式でも、先に 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 <package>
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) - マニフェストとパッケージメタデータ

54
docs/ja-JP/providers/openrouter.md
View File

@ -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
```
</Step>
<Step title="(任意) 特定のモデルに切り替える">
オンボーディングではデフォルトで `openrouter/auto` が使われます。後で具体的なモデルを選択します。
<Step title="（任意）特定のモデルに切り替える">
オンボーディングのデフォルトは `openrouter/auto` です。後で具体的なモデルを選択します。
```bash
openclaw models set openrouter/<provider>/<model>
@ -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` |
<Warning>
OpenRouter プロバイダーを別のプロキシまたはベース URL に向け直した場合、OpenClaw はこれらの OpenRouter 固有ヘッダーや Anthropic キャッシュマーカーを注入しません。
OpenRouter プロバイダーを別のプロキシまたはベース URL に向け直した場合、OpenClaw はそれらの OpenRouter 固有ヘッダーや Anthropic キャッシュマーカーを注入**しません**。
</Warning>
## 高度な設定
<AccordionGroup>
<Accordion title="レスポンスキャッシュ">
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` ルートにのみ適用されます。
</Accordion>
<Accordion title="Anthropic キャッシュマーカー">
検証済みの OpenRouter ルートでは、Anthropic モデル参照は、システム/開発者プロンプトブロックでのプロンプトキャッシュ再利用を向上させるために OpenClaw が使用する OpenRouter 固有の Anthropic `cache_control` マーカーを保持します。
検証済みの OpenRouter ルートでは、Anthropic モデル参照は、システム/開発者プロンプトブロックでプロンプトキャッシュをよりよく再利用するために OpenClaw が使用する OpenRouter 固有の Anthropic `cache_control` マーカーを保持します。
</Accordion>
<Accordion title="Anthropic reasoning プリフィル">
検証済みの OpenRouter ルートでは、reasoning が有効な Anthropic モデル参照は、リクエストが OpenRouter に到達する前に末尾のアシスタントプリフィルターンを削除します。これは、reasoning 会話はユーザーターンで終わる必要があるという Anthropic の要件に合わせるためです。
検証済みの OpenRouter ルートでは、reasoning が有効な Anthropic モデル参照は、リクエストが OpenRouter に到達する前に末尾の assistant プリフィルターンを削除します。これは、reasoning 会話が user ターンで終わる必要があるという Anthropic の要件に合わせるためです。
</Accordion>
<Accordion title="Thinking / reasoning 注入">
対応している非 `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 フィールドで最終回答テキストを返す可能性があるためです。
</Accordion>
<Accordion title="DeepSeek V4 reasoning 再生">
検証済みの OpenRouter ルートでは、`openrouter/deepseek/deepseek-v4-flash` と `openrouter/deepseek/deepseek-v4-pro` は、再生されたアシスタントターンで欠落している `reasoning_content` を補完し、thinking/ツール会話が DeepSeek V4 に必要な後続形状を維持できるようにします。
<Accordion title="DeepSeek V4 reasoning リプレイ">
検証済みの 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` にマッピングされます。
</Accordion>
<Accordion title="OpenAI のみのリクエスト整形">
<Accordion title="OpenAI 専用リクエスト整形">
OpenRouter は引き続きプロキシ形式の OpenAI 互換パスを通るため、`serviceTier`、Responses `store`、OpenAI reasoning 互換ペイロード、プロンプトキャッシュヒントなどのネイティブ OpenAI 専用リクエスト整形は転送されません。
</Accordion>
<Accordion title="Gemini バックエンドのルート">
Gemini バックエンドの OpenRouter 参照は、プロキシ Gemini パスに留まります。OpenClaw はそこで Gemini thought-signature サニタイズを維持しますが、ネイティブ Gemini 再生検証やブートストラップ書き換えは有効にしません。
Gemini バックエンドの OpenRouter 参照はプロキシ Gemini パスにとどまります。OpenClaw はそこで Gemini thought-signature サニタイズを維持しますが、ネイティブ Gemini リプレイ検証やブートストラップ書き換えは有効にしません。
</Accordion>
<Accordion title="プロバイダールーティングメタデータ">

431
docs/ja-JP/reference/RELEASING.md
View File

@ -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<package.json version>` を合成する。実際の 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<package.json version>` を合成する。実際の 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 <full-sha>
```
この helper は `release-ci/<sha>-...` を push し、その branch から `ref=<sha>` で `Full Release Validation` を dispatch し、すべての child workflow の `headSha` が target に一致することを検証した後、temporary branch を削除する。これにより、誤って新しい `main` child run を証明することを避けられる。
helper は `release-ci/<sha>-...` を push し、その branch から `ref=<sha>` で `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=<release-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>` を使用しないでください。生のコミット SHA は workflow dispatch ref にできないため、固定された一時ブランチを作成するには `pnpm ci:full-release --sha <sha>` を使用します。
ワークフローはターゲット ref を解決し、`target_ref=<release-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>` を使用しないでください。生のコミット SHA はワークフローディスパッチ ref にできないため、`pnpm ci:full-release --sha <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=<lane[,lane]>` を使用します。生成された再実行コマンドには、利用可能な場合、以前の `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=<lane[,lane]>` を使用します。生成された 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=<release-sha>` で `Plugin NPM Release` をディスパッチします。
5. 同じスコープと SHA で `Plugin ClawHub Release` をディスパッチします。
6. リリースタグ、npm dist-tag、保存済みの `preflight_run_id` で `OpenClaw NPM Release` をディスパッチします。
4. `publish_scope=all-publishable` と `ref=<release-sha>` で `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)

184
docs/ja-JP/reference/full-release-validation.md
View File

@ -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`<br />**子ワークフロー:** なし<br />**証明内容:** リリースブランチ、タグ、または完全なコミット SHA を解決し、選択された入力を記録します。<br />**再実行:** これが失敗した場合は統括ワークフローを再実行します。 |
| Vitest と通常 CI | **ジョブ:** `Run normal full CI`<br />**子ワークフロー:** `CI`<br />**証明内容:** ターゲット ref に対する手動の完全 CI グラフ。Linux Node レーン、同梱 Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、docs チェック、Python skills、Windows、macOS、Control UI i18n、統括ワークフロー経由の Android を含みます。<br />**再実行:** `rerun_group=ci`。 |
| Plugin プレリリース | **ジョブ:** `Run plugin prerelease validation`<br />**子ワークフロー:** `Plugin Prerelease`<br />**証明内容:** リリース専用の Plugin 静的チェック、エージェント型 Plugin カバレッジ、完全な拡張バッチシャード、Plugin プレリリース Docker レーン。<br />**再実行:** `rerun_group=plugin-prerelease`。 |
| リリースチェック | **ジョブ:** `Run release/live/Docker/QA validation`<br />**子ワークフロー:** `OpenClaw Release Checks`<br />**証明内容:** インストールスモーク、クロス OS パッケージチェック、live/E2E スイート、Docker リリースパスチャンク、Package Acceptance、QA Lab parity、live Matrix、live Telegram。<br />**再実行:** `rerun_group=release-checks` またはより狭い release-checks ハンドル。 |
| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`<br />**子ワークフロー:** なし<br />**証明内容:** `OpenClaw Release Checks` を待つ必要がないパッケージ向けチェックで使えるよう、親の `release-package-under-test` tarball を十分早く作成します。<br />**再実行:** 統括ワークフローを再実行するか、`rerun_group=npm-telegram` に `npm_telegram_package_spec` を指定します。 |
| パッケージ Telegram | **ジョブ:** `Run package Telegram E2E`<br />**子ワークフロー:** `NPM Telegram Beta E2E`<br />**証明内容:** `rerun_group=all` かつ `release_profile=full` の親アーティファクトに基づく Telegram パッケージ証明、または `npm_telegram_package_spec` が設定されている場合の公開済みパッケージ Telegram 証明。<br />**再実行:** `npm_telegram_package_spec` 付きの `rerun_group=npm-telegram`。 |
| 統括検証 | **ジョブ:** `Verify full validation`<br />**子ワークフロー:** なし<br />**証明内容:** 記録された子実行の結論を再チェックし、子ワークフローから最も遅いジョブの表を追記します。<br />**再実行:** 失敗した子を再実行して成功にした後、このジョブだけを再実行します。 |
## トップレベルのステージ
`ref=main` かつ `rerun_group=all` の場合、新しい統括ワークフローは古いものを置き換えます。
| ステージ | 詳細 |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ターゲット解決 | **ジョブ:** `Resolve target ref`<br />**子ワークフロー:** なし<br />**検証内容:** リリースブランチ、タグ、または完全なコミット SHA を解決し、選択された入力を記録します。<br />**再実行:** これが失敗した場合は包括ワークフローを再実行します。 |
| Vitest と通常 CI | **ジョブ:** `Run normal full CI`<br />**子ワークフロー:** `CI`<br />**検証内容:** ターゲット参照に対する手動のフル CI グラフ。Linux Node レーン、同梱 Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python skills、Windows、macOS、Control UI i18n、および包括ワークフロー経由の Android を含みます。<br />**再実行:** `rerun_group=ci`。 |
| Plugin プレリリース | **ジョブ:** `Run plugin prerelease validation`<br />**子ワークフロー:** `Plugin Prerelease`<br />**検証内容:** リリース専用の Plugin 静的チェック、エージェント型 Plugin カバレッジ、完全な拡張バッチシャード、および Plugin プレリリース Docker レーン。<br />**再実行:** `rerun_group=plugin-prerelease`。 |
| リリースチェック | **ジョブ:** `Run release/live/Docker/QA validation`<br />**子ワークフロー:** `OpenClaw Release Checks`<br />**検証内容:** インストールスモーク、クロス OS パッケージチェック、Package Acceptance、QA Lab パリティ、ライブ Matrix、およびライブ Telegram。`run_release_soak=true` または `release_profile=full` の場合は、網羅的なライブ/E2E スイートと Docker リリースパスチャンクも実行します。<br />**再実行:** `rerun_group=release-checks` またはより狭い release-checks ハンドル。 |
| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`<br />**子ワークフロー:** なし<br />**検証内容:** `OpenClaw Release Checks` を待つ必要がないパッケージ向けチェックのために、親の `release-package-under-test` tarball を十分早く作成します。<br />**再実行:** 包括ワークフローを再実行するか、`rerun_group=npm-telegram` に `npm_telegram_package_spec` を指定します。 |
| パッケージ Telegram | **ジョブ:** `Run package Telegram E2E`<br />**子ワークフロー:** `NPM Telegram Beta E2E`<br />**検証内容:** `release_profile=full` を指定した `rerun_group=all` の場合は親アーティファクトを裏付けとする Telegram パッケージ検証、`npm_telegram_package_spec` が設定されている場合は公開済みパッケージの Telegram 検証。<br />**再実行:** `npm_telegram_package_spec` を指定した `rerun_group=npm-telegram`。 |
| 包括ワークフロー検証 | **ジョブ:** `Verify full validation`<br />**子ワークフロー:** なし<br />**検証内容:** 記録された子実行の結論を再チェックし、子ワークフローの最も遅いジョブの表を追記します。<br />**再実行:** 失敗した子を再実行してグリーンにした後、このジョブだけを再実行します。 |
`ref=main` かつ `rerun_group=all` の場合、新しい包括ワークフローが古いものを置き換えます。
親がキャンセルされると、そのモニターはすでにディスパッチした子ワークフローを
キャンセルします。リリースブランチとタグの検証実行は、デフォルトでは互いにキャンセルしません。
キャンセルします。リリースブランチおよびタグ検証の実行は、デフォルトでは互いを
キャンセルしません。
## リリースチェックのステージ
`OpenClaw Release Checks` は最大の子ワークフローです。ターゲットを一度解決し、
パッケージ向けまたは Docker 向けのステージが必要とするときに、共有の
`OpenClaw Release Checks` は最大の子ワークフローです。ターゲットを
一度だけ解決し、パッケージまたは Docker 向けのステージで必要な場合に共有の
`release-package-under-test` アーティファクトを準備します。
| ステージ | 詳細 |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| リリースターゲット | **ジョブ:** `Resolve target ref`<br />**バッキングワークフロー:** なし<br />**テスト:** 選択された ref、任意の期待 SHA、プロファイル、再実行グループ、フォーカスされた live スイートフィルター。<br />**再実行:** `rerun_group=release-checks`。 |
| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`<br />**バッキングワークフロー:** なし<br />**テスト:** 1 つの候補 tarball をパックまたは解決し、下流のパッケージ向けチェック用に `release-package-under-test` をアップロードします。<br />**再実行:** 影響を受けるパッケージ、クロス OS、または live/E2E グループ。 |
| インストールスモーク | **ジョブ:** `Run install smoke`<br />**バッキングワークフロー:** `Install Smoke`<br />**テスト:** ルート Dockerfile スモークイメージ再利用、QR パッケージインストール、ルートと Gateway の Docker スモーク、インストーラー Docker テスト、Bun グローバルインストールの画像プロバイダースモーク、高速な同梱 Plugin インストール/アンインストール E2E を含む完全なインストールパス。<br />**再実行:** `rerun_group=install-smoke`。 |
| クロス OS | **ジョブ:** `cross_os_release_checks`<br />**バッキングワークフロー:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**テスト:** 選択されたプロバイダーとモードについて、候補 tarball とベースラインパッケージを使用する Linux、Windows、macOS の新規およびアップグレードレーン。<br />**再実行:** `rerun_group=cross-os`。 |
| リポジトリと live E2E | **ジョブ:** `Run repo/live E2E validation`<br />**バッキングワークフロー:** `OpenClaw Live And E2E Checks (Reusable)`<br />**テスト:** `release_profile` によって選択される、リポジトリ E2E、live キャッシュ、OpenAI websocket ストリーミング、ネイティブ live プロバイダーと Plugin シャード、Docker ベースの live モデル/バックエンド/Gateway ハーネス。<br />**再実行:** `rerun_group=live-e2e`。任意で `live_suite_filter` を指定できます。 |
| Docker リリースパス | **ジョブ:** `Run Docker release-path validation`<br />**バッキングワークフロー:** `OpenClaw Live And E2E Checks (Reusable)`<br />**テスト:** 共有パッケージアーティファクトに対するリリースパス Docker チャンク。<br />**再実行:** `rerun_group=live-e2e`。 |
| Package Acceptance | **ジョブ:** `Run package acceptance`<br />**バッキングワークフロー:** `Package Acceptance`<br />**テスト:** オフライン Plugin パッケージフィクスチャ、Plugin 更新、モック OpenAI Telegram パッケージ受け入れ、`2026.4.23` 以降のすべての安定版 npm リリースから同じ tarball に対する公開済みアップグレード survivor チェック。<br />**再実行:** `rerun_group=package`。 |
| QA parity | **ジョブ:** `Run QA Lab parity lane` と `Run QA Lab parity report`<br />**バッキングワークフロー:** 直接ジョブ<br />**テスト:** 候補とベースラインのエージェント型 parity パック、その後の parity レポート。<br />**再実行:** `rerun_group=qa-parity` または `rerun_group=qa`。 |
| QA live Matrix | **ジョブ:** `Run QA Lab live Matrix lane`<br />**バッキングワークフロー:** 直接ジョブ<br />**テスト:** `qa-live-shared` 環境の高速 live Matrix QA プロファイル。<br />**再実行:** `rerun_group=qa-live` または `rerun_group=qa`。 |
| QA live Telegram | **ジョブ:** `Run QA Lab live Telegram lane`<br />**バッキングワークフロー:** 直接ジョブ<br />**テスト:** Convex CI 認証情報リースを使った live Telegram QA。<br />**再実行:** `rerun_group=qa-live` または `rerun_group=qa`。 |
| リリース検証 | **ジョブ:** `Verify release checks`<br />**バッキングワークフロー:** なし<br />**テスト:** 選択された再実行グループに必要な release-check ジョブ。<br />**再実行:** フォーカスされた子ジョブが通過した後に再実行します。 |
| ステージ | 詳細 |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| リリース対象 | **ジョブ:** `Resolve target ref`<br />**基盤ワークフロー:** なし<br />**テスト:** 選択された ref、省略可能な期待 SHA、プロファイル、再実行グループ、対象を絞ったライブスイートフィルター。<br />**再実行:** `rerun_group=release-checks`。 |
| パッケージアーティファクト | **ジョブ:** `Prepare release package artifact`<br />**基盤ワークフロー:** なし<br />**テスト:** 候補 tarball を1つパックまたは解決し、下流のパッケージ向けチェック用に `release-package-under-test` をアップロードする。<br />**再実行:** 影響を受けるパッケージ、クロス OS、またはライブ/E2E グループ。 |
| インストールスモーク | **ジョブ:** `Run install smoke`<br />**基盤ワークフロー:** `Install Smoke`<br />**テスト:** ルート Dockerfile スモークイメージ再利用、QR パッケージインストール、ルートおよび Gateway Docker スモーク、インストーラー Docker テスト、Bun グローバルインストールの image-provider スモーク、高速なバンドル Plugin のインストール/アンインストール E2E を含む完全なインストールパス。<br />**再実行:** `rerun_group=install-smoke`。 |
| クロス OS | **ジョブ:** `cross_os_release_checks`<br />**基盤ワークフロー:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**テスト:** 候補 tarball とベースラインパッケージを使用し、選択されたプロバイダーとモードについて Linux、Windows、macOS 上の新規およびアップグレードレーン。<br />**再実行:** `rerun_group=cross-os`。 |
| リポジトリとライブ E2E | **ジョブ:** `Run repo/live E2E validation`<br />**基盤ワークフロー:** `OpenClaw Live And E2E Checks (Reusable)`<br />**テスト:** リポジトリ E2E、ライブキャッシュ、OpenAI websocket ストリーミング、ネイティブライブプロバイダーおよび Plugin シャード、`release_profile` によって選択される Docker ベースのライブモデル/バックエンド/Gateway ハーネス。<br />**実行条件:** `run_release_soak=true`、`release_profile=full`、または対象を絞った `rerun_group=live-e2e`。<br />**再実行:** `rerun_group=live-e2e`、省略可能で `live_suite_filter` を指定。 |
| Docker リリースパス | **ジョブ:** `Run Docker release-path validation`<br />**基盤ワークフロー:** `OpenClaw Live And E2E Checks (Reusable)`<br />**テスト:** 共有パッケージアーティファクトに対するリリースパス Docker チャンク。<br />**実行条件:** `run_release_soak=true`、`release_profile=full`、または対象を絞った `rerun_group=live-e2e`。<br />**再実行:** `rerun_group=live-e2e`。 |
| パッケージ受け入れ | **ジョブ:** `Run package acceptance`<br />**基盤ワークフロー:** `Package Acceptance`<br />**テスト:** オフライン Plugin パッケージフィクスチャ、Plugin 更新、モック OpenAI Telegram パッケージ受け入れ、同じ tarball に対する公開済みアップグレード生存チェック。ブロッキングリリースチェックではデフォルトの最新公開済みベースラインを使用し、ソークチェックでは `2026.4.23` 以降のすべての安定版 npm リリースと報告済み issue フィクスチャまで拡張する。<br />**再実行:** `rerun_group=package`。 |
| QA パリティ | **ジョブ:** `Run QA Lab parity lane` および `Run QA Lab parity report`<br />**基盤ワークフロー:** 直接ジョブ<br />**テスト:** 候補およびベースラインのエージェント的パリティパック、その後パリティレポート。<br />**再実行:** `rerun_group=qa-parity` または `rerun_group=qa`。 |
| QA ライブ Matrix | **ジョブ:** `Run QA Lab live Matrix lane`<br />**基盤ワークフロー:** 直接ジョブ<br />**テスト:** `qa-live-shared` 環境での高速ライブ Matrix QA プロファイル。<br />**再実行:** `rerun_group=qa-live` または `rerun_group=qa`。 |
| QA ライブ Telegram | **ジョブ:** `Run QA Lab live Telegram lane`<br />**基盤ワークフロー:** 直接ジョブ<br />**テスト:** Convex CI 認証情報リースを使用するライブ Telegram QA。<br />**再実行:** `rerun_group=qa-live` または `rerun_group=qa`。 |
| リリース検証器 | **ジョブ:** `Verify release checks`<br />**基盤ワークフロー:** なし<br />**テスト:** 選択された再実行グループに必要なリリースチェックジョブ。<br />**再実行:** 対象を絞った子ジョブが成功した後に再実行。 |
## 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=<lane[,lane]>` を使用します。リリースアーティファクトには、利用可能な場合にパッケージアーティファクトとイメージ再利用の入力を含む、レーンごとの再実行コマンドが含まれます。
1つの Docker レーンだけが失敗した場合は、再利用可能なライブ/E2E ワークフローで対象を絞った `docker_lanes=<lane[,lane]>` を使用する。リリースアーティファクトには、利用可能な場合にパッケージアーティファクトとイメージ再利用入力を含む、レーンごとの再実行コマンドが含まれる。
## リリースプロファイル
`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 アーティファクト
## ワークフローファイル

118
docs/ja-JP/reference/test.md
View File

File diff suppressed because one or more lines are too long

184
docs/ja-JP/reference/transcript-hygiene.md
View File

@ -1,34 +1,34 @@
---
read_when:
- トランスクリプトの形状に関連するプロバイダーリクエストの拒否をデバッグしています
- トランスクリプトのサニタイズまたはツール呼び出しの修復ロジックを変更しています
- トランスクリプトの形状に関連するプロバイダーのリクエスト拒否をデバッグしています
- トランスクリプトのサニタイズまたはツール呼び出しの修復ロジックを変更している
- プロバイダー間のツール呼び出し ID の不一致を調査しています
summary: 'リファレンス: プロバイダー固有のトランスクリプトのサニタイズと修復ルール'
title: トランスクリプトの整理
title: 会話履歴の整理
x-i18n:
generated_at: "2026-05-03T05:04:42Z"
generated_at: "2026-05-05T01:49:31Z"
model: gpt-5.5
provider: openai
source_hash: ff3a364a4c4d1c0d1e03b2860396c2d7e32c554d7acd0791ed2eaadae06d35ab
source_hash: 9441494f3e8bb18d1648acc789a40bf9501fe3f2d32b6293792e6a24710675d0
source_path: reference/transcript-hygiene.md
workflow: 16
---
OpenClaw は、実行前（モデルコンテキストの構築時）にトランスクリプトへ**プロバイダー固有の修正**を適用します。これらの大半は、厳格なプロバイダー要件を満たすために使われる**インメモリ**調整です。別のセッションファイル修復パスが、セッションの読み込み前に保存済み JSONL を書き換えることもありますが、対象は不正な行または永続レコードとして無効な保存済みターンに限られます。配信済みのアシスタント返信はディスク上で保持されます。プロバイダー固有の assistant-prefill 除去は、送信ペイロードの構築時にのみ行われます。修復が発生した場合、元のファイルはセッションファイルの横にバックアップされます。
OpenClaw は実行前（モデルコンテキストの構築時）に、トランスクリプトへ**プロバイダー固有の修正**を適用します。これらの多くは、厳格なプロバイダー要件を満たすために使われる**インメモリ**調整です。別個のセッションファイル修復パスが、セッションの読み込み前に保存済み JSONL を書き換えることもありますが、対象は不正な形式の行、または永続レコードとして無効な保存済みターンに限られます。配信済みのアシスタント返信はディスク上で保持されます。プロバイダー固有の assistant-prefill 除去は、送信ペイロードの構築中にのみ行われます。修復が発生すると、元のファイルはセッションファイルの横にバックアップされます。
対象範囲は次のとおりです。
- ランタイム専用プロンプトコンテキストを、ユーザーに見えるトランスクリプトターンから除外する
- ツール呼び出し id のサニタイズ
- ランタイム専用のプロンプトコンテキストをユーザーに見えるトランスクリプトターンに含めないこと
- ツール呼び出し ID のサニタイズ
- ツール呼び出し入力の検証
- ツール結果ペアリングの修復
- ターン検証 / 順序付け
- Thought signature のクリーンアップ
- Thinking signature のクリーンアップ
- ツール結果のペアリング修復
- ターンの検証 / 順序付け
- 思考署名のクリーンアップ
- Thinking 署名のクリーンアップ
- 画像ペイロードのサニタイズ
- プロバイダー再生前の空テキストブロックのクリーンアップ
- ユーザー入力の由来タグ付け（セッション間でルーティングされたプロンプト用）
- Bedrock Converse 再生用の空アシスタントエラーターン修復
- プロバイダー再生前の空のテキストブロックのクリーンアップ
- ユーザー入力の出所タグ付け（セッション間でルーティングされたプロンプト用）
- Bedrock Converse 再生用の空の assistant エラーターン修復
トランスクリプト保存の詳細が必要な場合は、次を参照してください。
@ -38,55 +38,56 @@ OpenClaw は、実行前（モデルコンテキストの構築時）にトラ
## グローバルルール: ランタイムコンテキストはユーザートランスクリプトではない
ランタイム/システムコンテキストは、ターンのモデルプロンプトに追加できますが、
エンドユーザーが作成したコンテンツではありません。OpenClaw は、Gateway 返信、キュー済みフォローアップ、ACP、CLI、埋め込み Pi 実行向けに、トランスクリプト用の
プロンプト本文を別に保持します。保存される可視ユーザーターンでは、ランタイムで拡張されたプロンプトではなく、そのトランスクリプト本文が使われます。
ランタイム / システムコンテキストは、あるターンのモデルプロンプトに追加できますが、
エンドユーザーが作成したコンテンツではありません。OpenClaw は、Gateway 返信、キューに入れられたフォローアップ、ACP、CLI、埋め込み Pi
実行向けに、トランスクリプト用の
プロンプト本文を別に保持します。保存される可視のユーザーターンは、ランタイムで拡張されたプロンプトではなく、そのトランスクリプト本文を使います。
すでにランタイムラッパーを永続化しているレガシーセッションについては、Gateway 履歴
サーフェスが WebChat、TUI、REST、または SSE クライアントへメッセージを返す前に表示用プロジェクションを適用します。
ランタイムラッパーがすでに永続化されているレガシーセッションでは、Gateway 履歴
サーフェスが WebChat、
TUI、REST、または SSE クライアントへメッセージを返す前に表示用の投影を適用します。
---
## 実行箇所
## これが実行される場所
すべてのトランスクリプト衛生処理は、埋め込みランナーに集約されています。
- ポリシー選択: `src/agents/transcript-policy.ts`
- サニタイズ/修復の適用: `src/agents/pi-embedded-runner/replay-history.ts` の `sanitizeSessionHistory`
- サニタイズ / 修復の適用: `src/agents/pi-embedded-runner/replay-history.ts` の `sanitizeSessionHistory`
このポリシーは、`provider`、`modelApi`、`modelId` を使って、何を適用するかを決定します。
このポリシーは、`provider`、`modelApi`、`modelId` を使って適用内容を決定します。
トランスクリプト衛生処理とは別に、セッションファイルは読み込み前に必要に応じて修復されます。
トランスクリプト衛生処理とは別に、セッションファイルは読み込み前に（必要な場合）修復されます。
- `src/agents/session-file-repair.ts` の `repairSessionFileIfNeeded`
- `run/attempt.ts` と `compact.ts`（埋め込みランナー）から呼び出されます
---
## グローバルルール: 画像サニタイズ
## グローバルルール: 画像のサニタイズ
画像ペイロードは、サイズ制限によるプロバイダー側の拒否を防ぐために常にサニタイズされます
（大きすぎる base64 画像の縮小/再圧縮）。
画像ペイロードは、サイズ
制限によるプロバイダー側の拒否を防ぐため、常にサニタイズされます（過大な base64 画像を縮小 / 再圧縮します）。
これは、ビジョン対応モデルで画像に起因するトークン負荷を制御する助けにもなります。
最大寸法を小さくすると一般にトークン使用量が減り、寸法を大きくすると詳細が保持されます。
これは、ビジョン対応モデルで画像起因のトークン負荷を制御するのにも役立ちます。
最大寸法を小さくすると一般的にトークン使用量が減り、大きくすると詳細が保持されます。
実装:
- `src/agents/pi-embedded-helpers/images.ts` の `sanitizeSessionMessagesImages`
- `src/agents/tool-images.ts` の `sanitizeContentBlocksImages`
- 最大画像辺は `agents.defaults.imageMaxDimensionPx` で設定できます（デフォルト: `1200`）。
- 画像の最大辺は `agents.defaults.imageMaxDimensionPx` で設定できます（デフォルト: `1200`）。
- このパスが再生コンテンツを走査する間に、空のテキストブロックは削除されます。空になったアシスタント
ターンは再生コピーから削除されます。空になったユーザーおよびツール結果
ターンには、空でない omitted-content プレースホルダーが付与されます。
ターンには、空でない省略コンテンツのプレースホルダーが付与されます。
---
## グローバルルール: 不正なツール呼び出し
## グローバルルール: 不正な形式のツール呼び出し
`input` と `arguments` の両方が欠落しているアシスタントツール呼び出しブロックは、
モデルコンテキストが構築される前に削除されます。これにより、部分的に
永続化されたツール呼び出し（たとえばレート制限失敗後）によるプロバイダー拒否を防ぎます。
`input` と `arguments` の両方が欠落しているアシスタントのツール呼び出しブロックは、モデルコンテキストが構築される前に削除されます。これにより、部分的に
永続化されたツール呼び出し（たとえば、レート制限の失敗後）によるプロバイダー拒否を防ぎます。
実装:
@ -95,116 +96,111 @@ OpenClaw は、実行前（モデルコンテキストの構築時）にトラ
---
## グローバルルール: セッション間入力の由来
## グローバルルール: セッション間入力の出所
エージェントが `sessions_send`（agent-to-agent の reply/announce ステップを含む）経由で別のセッションにプロンプトを送ると、
OpenClaw は作成されたユーザーターンを次の内容で永続化します。
エージェントが `sessions_send` を介して別のセッションへプロンプトを送る場合（エージェント間の reply/announce ステップを含む）、OpenClaw は作成されたユーザーターンを次の内容で永続化します。
- `message.provenance.kind = "inter_session"`
OpenClaw はまた、ルーティングされたプロンプトテキストの前に、同じターン内の `[Inter-session message ... isUser=false]`
マーカーを付加します。これにより、アクティブなモデル呼び出しは、外部セッションの出力と外部エンドユーザー指示を区別できます。このマーカーには、
利用可能な場合、送信元セッション、チャンネル、ツールが含まれます。プロバイダー互換性のため、トランスクリプトでは引き続き
`role: "user"` を使いますが、可視テキストと由来
マーカーを付けるため、アクティブなモデル呼び出しは外部セッション出力を外部エンドユーザー指示と区別できます。このマーカーには、利用可能な場合、送信元セッション、チャンネル、ツールが含まれます。プロバイダー互換性のため、トランスクリプトは引き続き
`role: "user"` を使いますが、可視テキストと出所
メタデータの両方が、そのターンをセッション間データとして示します。
コンテキスト再構築中、OpenClaw は、由来メタデータだけを持つ古い永続化済み
コンテキスト再構築中、OpenClaw は、出所メタデータのみを持つ古い永続化済み
セッション間ユーザーターンにも同じマーカーを適用します。
---
## プロバイダーマトリクス（現在の挙動）
## プロバイダーマトリックス（現在の動作）
**OpenAI / OpenAI Codex**
- 画像サニタイズのみ。
- OpenAI Responses/Codex トランスクリプトでは、孤立した reasoning signatures（後続のコンテンツブロックがない単独の reasoning items）を削除し、モデルルート切り替え後は再生可能な OpenAI reasoning を削除します。
- 暗号化された空サマリー項目を含む、再生可能な OpenAI Responses reasoning item ペイロードを保持します。これにより、手動/WebSocket 再生で必要な `rs_*` 状態がアシスタント出力項目とペアのまま保たれます。
- ツール呼び出し id のサニタイズはありません。
- ツール結果ペアリング修復は、実際に一致した出力を移動し、不足しているツール呼び出し用に Codex 形式の `aborted` 出力を合成する場合があります。
- ターン検証または並べ替えはありません。
- 不足している OpenAI Responses ファミリーのツール出力は、Codex 再生正規化に合わせるため `aborted` として合成されます。
- thought signature の除去はありません。
- 画像のサニタイズのみ。
- OpenAI Responses/Codex トランスクリプトでは、孤立した reasoning 署名（後続のコンテンツブロックを持たないスタンドアロンの reasoning 項目）を削除し、モデルルート切り替え後には再生可能な OpenAI reasoning を削除します。
- 暗号化された空サマリー項目を含め、再生可能な OpenAI Responses reasoning 項目ペイロードを保持するため、手動 / WebSocket 再生では必要な `rs_*` 状態がアシスタント出力項目と対応付けられたままになります。
- ネイティブ ChatGPT Codex Responses は、セッションの `prompt_cache_key` を保持しつつ、事前の項目 ID なしで過去の Responses reasoning/message/function ペイロードを再生することで Codex ワイヤ互換に従います。
- ツール呼び出し ID のサニタイズはありません。
- ツール結果のペアリング修復では、実際に一致した出力を移動し、欠落したツール呼び出しに対して Codex スタイルの `aborted` 出力を合成する場合があります。
- ターンの検証や並べ替えはありません。
- 欠落している OpenAI Responses ファミリーのツール出力は、Codex 再生正規化に合わせて `aborted` として合成されます。
- 思考署名の除去はありません。
**OpenAI 互換 Gemma 4**
- 過去のアシスタント thinking/reasoning ブロックは、ローカルの
OpenAI 互換 Gemma 4 サーバーが以前のターンの reasoning コンテンツを受け取らないよう、再生前に除去されます。
OpenAI 互換 Gemma 4 サーバーが前ターンの reasoning コンテンツを受け取らないよう、再生前に除去されます。
- 現在の同一ターンのツール呼び出し継続では、ツール結果が再生されるまで、アシスタント reasoning ブロックを
ツール呼び出しに付けたままにします。
**Google（Generative AI / Gemini CLI / Antigravity）**
- ツール呼び出し id のサニタイズ: 厳格な英数字。
- ツール結果ペアリング修復と合成ツール結果。
- ターン検証（Gemini 形式のターン交替）。
- Google ターン順序修正（履歴がアシスタントで始まる場合、小さなユーザー bootstrap を先頭に追加）。
- Antigravity Claude: thinking signatures を正規化し、署名のない thinking ブロックを削除します。
- ツール呼び出し ID のサニタイズ: 厳格な英数字。
- ツール結果のペアリング修復と合成ツール結果。
- ターンの検証（Gemini スタイルのターン交替）。
- Google ターン順序の修正（履歴がアシスタントで始まる場合、小さなユーザー bootstrap を先頭に追加）。
- Antigravity Claude: thinking 署名を正規化し、署名されていない thinking ブロックを削除します。
**Anthropic / Minimax（Anthropic 互換）**
- ツール結果ペアリング修復と合成ツール結果。
- ターン検証（厳格な交替を満たすため、連続するユーザーターンを結合）。
- thinking が有効な場合、Cloudflare AI Gateway ルートを含め、末尾のアシスタント prefill ターンは送信 Anthropic Messages
- ツール結果のペアリング修復と合成ツール結果。
- ターンの検証（厳格な交替を満たすため、連続するユーザーターンをマージ）。
- thinking が有効な場合、Cloudflare AI Gateway ルートを含め、末尾のアシスタント prefill ターンは送信される Anthropic Messages
ペイロードから除去されます。
- 欠落、空、または空白の再生署名を持つ Thinking ブロックは、
プロバイダー変換前に除去されます。それによってアシスタントターンが空になる場合、OpenClaw は
空でない omitted-reasoning テキストでターン形状を保持します。
- 除去する必要がある古い thinking-only アシスタントターンは、
プロバイダーアダプターが再生ターンを削除しないよう、空でない omitted-reasoning テキストに置き換えられます。
- 欠落、空、または空白の再生署名を持つ thinking ブロックは、プロバイダー変換前に除去されます。それによりアシスタントターンが空になる場合、OpenClaw は
空でない省略 reasoning テキストでターン形状を保持します。
- 除去が必要な古い thinking のみのアシスタントターンは、プロバイダーアダプターが再生
ターンを削除しないよう、空でない省略 reasoning テキストに置き換えられます。
**Amazon Bedrock（Converse API）**
- 空のアシスタントストリームエラーターンは、再生前に空でないフォールバックテキストブロックへ修復されます。Bedrock Converse は `content: []` を持つアシスタントメッセージを拒否するため、
`stopReason: "error"` と空コンテンツを持つ永続化済みアシスタントターンも、
読み込み前にディスク上で修復されます。
- 空白テキストブロックのみを含むアシスタントストリームエラーターンは、
無効な空白ブロックを再生する代わりに、インメモリ再生コピーから削除されます。
`stopReason: "error"` と空のコンテンツを持つ永続化済みアシスタントターンも、読み込み前にディスク上で修復されます。
- 空白のテキストブロックのみを含むアシスタントストリームエラーターンは、無効な空白ブロックを再生するのではなく、
インメモリ再生コピーから削除されます。
- 欠落、空、または空白の再生署名を持つ Claude thinking ブロックは、
Converse 再生前に除去されます。それによってアシスタントターンが空になる場合、OpenClaw は
空でない omitted-reasoning テキストでターン形状を保持します。
- 除去する必要がある古い thinking-only アシスタントターンは、
Converse 再生が厳格なターン形状を保つよう、空でない omitted-reasoning テキストに置き換えられます。
- 再生は OpenClaw delivery-mirror と Gateway 注入のアシスタントターンをフィルターします。
- 画像サニタイズはグローバルルールに従って適用されます。
Converse 再生前に除去されます。それによりアシスタントターンが空になる場合、OpenClaw は
空でない省略 reasoning テキストでターン形状を保持します。
- 除去が必要な古い thinking のみのアシスタントターンは、Converse 再生が厳格なターン形状を維持するよう、空でない省略 reasoning テキストに置き換えられます。
- 再生では、OpenClaw の delivery-mirror と gateway-injected のアシスタントターンがフィルターされます。
- 画像のサニタイズはグローバルルールを通じて適用されます。
**Mistral（model-id ベースの検出を含む）**
- ツール呼び出し id のサニタイズ: strict9（英数字、長さ 9）。
- ツール呼び出し ID のサニタイズ: strict9（英数字、長さ 9）。
**OpenRouter Gemini**
- Thought signature のクリーンアップ: base64 ではない `thought_signature` 値を除去します（base64 は保持）。
- 思考署名のクリーンアップ: base64 ではない `thought_signature` 値を除去します（base64 は保持）。
**OpenRouter Anthropic**
- reasoning が有効な場合、検証済み OpenRouter
OpenAI 互換 Anthropic モデルペイロードから末尾のアシスタント prefill ターンを除去します。これは直接 Anthropic および Cloudflare Anthropic の再生挙動と一致します。
- reasoning が有効な場合、検証済みの OpenRouter
OpenAI 互換 Anthropic モデルペイロードから末尾のアシスタント prefill ターンを除去し、直接の Anthropic および Cloudflare Anthropic 再生動作に合わせます。
**その他すべて**
- 画像サニタイズのみ。
- 画像のサニタイズのみ。
---
## 過去の挙動（2026.1.22 より前）
## 過去の動作（2026.1.22 より前）
2026.1.22 リリースより前、OpenClaw は複数層のトランスクリプト衛生処理を適用していました。
2026.1.22 リリース以前、OpenClaw は複数層のトランスクリプト衛生処理を適用していました。
- **transcript-sanitize extension** がコンテキスト構築のたびに実行され、次のことが可能でした。
- ツール use/result ペアリングを修復する。
- ツール呼び出し id をサニタイズする（`_`/`-` を保持する非厳格モードを含む）。
- ランナーもプロバイダー固有のサニタイズを実行していたため、処理が重複していました。
- 次を含む追加の変更が、プロバイダーポリシーの外側で発生していました。
- 永続化前にアシスタントテキストから `<final>` タグを除去する。
- 空のアシスタントエラーターンを削除する。
- ツール呼び出し後のアシスタントコンテンツをトリミングする。
- **transcript-sanitize extension** がすべてのコンテキスト構築時に実行され、次のことができました。
- ツール use/result のペアリングを修復。
- ツール呼び出し ID をサニタイズ（`_`/`-` を保持する非厳格モードを含む）。
- ランナーもプロバイダー固有のサニタイズを実行しており、処理が重複していました。
- プロバイダーポリシーの外側でも、次のような追加の変更が発生していました。
- 永続化前にアシスタントテキストから `<final>` タグを除去。
- 空のアシスタントエラーターンを削除。
- ツール呼び出し後のアシスタントコンテンツをトリミング。
この複雑さは、プロバイダー間のリグレッション（特に `openai-responses`
`call_id|fc_id` ペアリング）を引き起こしました。2026.1.22 のクリーンアップでは extension を削除し、
ロジックをランナーに集約し、画像サニタイズ以外について OpenAI を**非介入**にしました。
この複雑さにより、プロバイダー間の回帰（特に `openai-responses`
の `call_id|fc_id` ペアリング）が発生しました。2026.1.22 のクリーンアップでは extension を削除し、ロジックをランナーに集約し、OpenAI は画像のサニタイズを除いて**変更なし**にしました。
## 関連
- [セッション管理](/ja-JP/concepts/session)
- [セッション pruning](/ja-JP/concepts/session-pruning)
- [セッションのプルーニング](/ja-JP/concepts/session-pruning)

111
docs/ja-JP/security/network-proxy.md
View File

@ -1,40 +1,40 @@
---
read_when:
- SSRF や DNS リバインディング攻撃に対して多層防御を行いたい場合
- SSRF と DNS リバインディング攻撃に対する多層防御が必要な場合
- OpenClaw ランタイムトラフィック用の外部フォワードプロキシの設定
summary: OpenClaw ランタイムの HTTP および WebSocket トラフィックをオペレーター管理のフィルタリングプロキシ経由でルーティングする方法
summary: OpenClaw ランタイムの HTTP および WebSocket トラフィックを運用者が管理するフィルタリングプロキシ経由でルーティングする方法
title: ネットワークプロキシ
x-i18n:
generated_at: "2026-05-04T18:24:16Z"
generated_at: "2026-05-05T01:49:31Z"
model: gpt-5.5
provider: openai
source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df
source_path: security/network-proxy.md
workflow: 16
---
# ネットワークプロキシ
OpenClaw は、実行時の HTTP および WebSocket トラフィックを、運用者が管理するフォワードプロキシ経由でルーティングできます。これは、中央集約された送信制御、より強固な SSRF 保護、より高いネットワーク監査性を求めるデプロイ向けの、任意の多層防御です。
OpenClaw は、実行時の HTTP および WebSocket トラフィックをオペレーター管理のフォワードプロキシ経由でルーティングできます。これは、中央集約されたエグレス制御、より強力な SSRF 保護、より優れたネットワーク監査性を必要とするデプロイ環境向けの、任意の多層防御です。
OpenClaw はプロキシを同梱、ダウンロード、起動、設定、認証しません。環境に合うプロキシ技術を実行し、OpenClaw は通常のプロセスローカルな HTTP および WebSocket クライアントをそのプロキシ経由でルーティングします。
OpenClaw はプロキシを同梱、ダウンロード、起動、設定、認定しません。環境に合ったプロキシ技術を運用し、OpenClaw は通常のプロセスローカルな HTTP および WebSocket クライアントをそのプロキシ経由でルーティングします。
## なぜプロキシを使うのか？
## なぜプロキシを使うのか?
プロキシは、運用者に送信 HTTP および WebSocket トラフィックの単一のネットワーク制御点を提供します。これは SSRF 強化以外でも有用です。
プロキシにより、オペレーターはアウトバウンド HTTP および WebSocket トラフィックのネットワーク制御点を 1 つにできます。これは SSRF 強化以外でも有用です。
- 中央ポリシー: すべてのアプリケーション HTTP 呼び出し箇所がネットワークルールを正しく扱うことに頼らず、単一の送信ポリシーを維持します。
- 中央ポリシー: すべてのアプリケーション HTTP 呼び出し箇所がネットワークルールを正しく扱うことに頼らず、1 つのエグレスポリシーを維持できます。
- 接続時チェック: DNS 解決後、プロキシが上流接続を開く直前に宛先を評価します。
- DNS リバインディング防御: アプリケーションレベルの DNS チェックと実際の送信接続の間の差を減らします。
- より広い JavaScript カバレッジ: 通常の `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch、および類似クライアントを同じ経路でルーティングします。
- 監査性: 許可および拒否された宛先を送信境界でログに記録します。
- 運用制御: OpenClaw を再ビルドせずに、宛先ルール、ネットワーク分割、レート制限、送信許可リストを適用します。
- DNS リバインディング防御: アプリケーションレベルの DNS チェックと実際のアウトバウンド接続の間のずれを減らします。
- より広い JavaScript カバレッジ: 通常の `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch、および同様のクライアントを同じ経路にルーティングします。
- 監査性: エグレス境界で許可および拒否された宛先をログに記録します。
- 運用制御: OpenClaw を再ビルドせずに、宛先ルール、ネットワークセグメンテーション、レート制限、またはアウトバウンド許可リストを適用できます。
プロキシルーティングは、通常の HTTP および WebSocket 送信に対するプロセスレベルのガードレールです。対応する JavaScript HTTP クライアントを独自のフィルタリングプロキシ経由でルーティングするフェイルクローズの経路を運用者に提供しますが、OS レベルのネットワークサンドボックスではなく、OpenClaw がプロキシの宛先ポリシーを認証するものでもありません。
プロキシルーティングは、通常の HTTP および WebSocket エグレスに対するプロセスレベルのガードレールです。対応する JavaScript HTTP クライアントを独自のフィルタリングプロキシ経由でルーティングするフェイルクローズの経路をオペレーターに提供しますが、OS レベルのネットワークサンドボックスではなく、OpenClaw がプロキシの宛先ポリシーを認定するものでもありません。
## OpenClaw がトラフィックをルーティングする仕組み
`proxy.enabled=true` でプロキシ URL が設定されている場合、`openclaw gateway run`、`openclaw node run`、`openclaw agent --local` などの保護対象ランタイムプロセスは、通常の HTTP および WebSocket 送信を設定済みプロキシ経由でルーティングします。
`proxy.enabled=true` でプロキシ URL が設定されている場合、`openclaw gateway run`、`openclaw node run`、`openclaw agent --local` などの保護対象ランタイムプロセスは、通常の HTTP および WebSocket エグレスを設定済みプロキシ経由でルーティングします。
```text
OpenClaw process
@ -43,27 +43,28 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
公開契約はルーティング動作であり、それを実装するために使われる内部 Node フックではありません。OpenClaw Gateway コントロールプレーン WebSocket クライアントは、Gateway URL が `localhost` または `127.0.0.1` や `[::1]` のようなリテラルのループバック IP を使う場合、local loopback Gateway RPC トラフィック用の狭い直接経路を使います。そのコントロールプレーン経路は、運用者プロキシがループバック宛先をブロックしている場合でも、ループバック Gateway に到達できる必要があります。通常のランタイム HTTP および WebSocket リクエストは引き続き設定済みプロキシを使います。
公開契約はルーティング動作であり、それを実装するために使われる内部の Node フックではありません。OpenClaw Gateway コントロールプレーン WebSocket クライアントは、Gateway URL が `localhost`、または `127.0.0.1` や `[::1]` などのリテラルのループバック IP を使う場合、local loopback Gateway RPC トラフィックに狭い直接経路を使います。このコントロールプレーン経路は、オペレータープロキシがループバック宛先をブロックしている場合でも、ループバック Gateway に到達できる必要があります。通常のランタイム HTTP および WebSocket リクエストは、引き続き設定済みプロキシを使います。
内部的に、OpenClaw はこの機能に 2 つのプロセスレベルのルーティングフックを使います。
- Undici ディスパッチャールーティングは、`fetch`、undici ベースのクライアント、および独自の undici ディスパッチャーを提供するトランスポートを対象にします。
- `global-agent` ルーティングは、`http.request`、`https.request`、`http.get`、`https.get` の上に構築された多くのライブラリを含む、Node コアの `node:http` および `node:https` 呼び出し元を対象にします。管理プロキシモードではそのグローバルエージェントが強制されるため、明示的な Node HTTP エージェントが誤って運用者プロキシをバイパスすることはありません。
- `global-agent` ルーティングは、`http.request`、`https.request`、`http.get`、`https.get` の上に構築された多くのライブラリを含め、Node コアの `node:http` および `node:https` 呼び出し元を対象にします。管理対象プロキシモードではそのグローバルエージェントを強制するため、明示的な Node HTTP エージェントが誤ってオペレータープロキシをバイパスすることはありません。
一部の Plugin は、プロセスレベルのルーティングが存在する場合でも明示的なプロキシ配線を必要とするカスタムトランスポートを所有します。たとえば、Telegram の Bot API トランスポートは独自の HTTP/1 undici ディスパッチャーを使うため、その所有者固有のトランスポート経路でプロセスプロキシ環境と管理対象の `OPENCLAW_PROXY_URL` フォールバックを尊重します。
一部の Plugin は、プロセスレベルのルーティングが存在する場合でも明示的なプロキシ配線を必要とするカスタムトランスポートを所有しています。たとえば、Telegram の Bot API トランスポートは独自の HTTP/1 undici ディスパッチャーを使うため、その所有者固有のトランスポート経路で、プロセスのプロキシ環境変数に加えて管理対象の `OPENCLAW_PROXY_URL` フォールバックを尊重します。
プロキシ URL 自体は `http://` を使う必要があります。HTTPS 宛先は HTTP `CONNECT` によりプロキシ経由で引き続き対応されます。これは、OpenClaw が `http://127.0.0.1:3128` のようなプレーン HTTP フォワードプロキシリスナーを期待するという意味にすぎません。
プロキシ URL 自体は `http://` を使う必要があります。HTTPS 宛先も HTTP `CONNECT` によってプロキシ経由で引き続きサポートされます。これは、OpenClaw が `http://127.0.0.1:3128` のようなプレーン HTTP フォワードプロキシリスナーを想定しているという意味にすぎません。
プロキシが有効な間、OpenClaw は `no_proxy`、`NO_PROXY`、`GLOBAL_AGENT_NO_PROXY` をクリアします。これらのバイパスリストは宛先ベースであるため、`localhost` や `127.0.0.1` を残しておくと、高リスクな SSRF ターゲットがフィルタリングプロキシを回避できてしまいます。
プロキシがアクティブな間、OpenClaw は `no_proxy`、`NO_PROXY`、`GLOBAL_AGENT_NO_PROXY` をクリアします。これらのバイパスリストは宛先ベースであるため、`localhost` や `127.0.0.1` が残っていると、高リスクの SSRF ターゲットがフィルタリングプロキシをスキップできてしまいます。
シャットダウン時、OpenClaw は以前のプロキシ環境を復元し、キャッシュされたプロセスルーティング状態をリセットします。
シャットダウン時に、OpenClaw は以前のプロキシ環境を復元し、キャッシュされたプロセスルーティング状態をリセットします。
## 関連するプロキシ用語
- `proxy.enabled` / `proxy.proxyUrl`: OpenClaw ランタイム送信用の送信フォワードプロキシルーティング。このページはその機能を文書化しています。
- `gateway.auth.mode: "trusted-proxy"`: Gateway アクセス用の、受信の ID 認識リバースプロキシ認証。[信頼されたプロキシ認証](/ja-JP/gateway/trusted-proxy-auth)を参照してください。
- `proxy.enabled` / `proxy.proxyUrl`: OpenClaw ランタイムエグレス用のアウトバウンドフォワードプロキシルーティング。このページではこの機能を説明します。
- `gateway.auth.mode: "trusted-proxy"`: Gateway アクセス用のインバウンド ID 対応リバースプロキシ認証。[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth)を参照してください。
- `openclaw proxy`: 開発およびサポート用のローカルデバッグプロキシとキャプチャインスペクター。[openclaw proxy](/ja-JP/cli/proxy)を参照してください。
- チャネルまたはプロバイダー固有のプロキシ設定: 特定のトランスポート向けの所有者固有の上書き。目的がランタイム全体の中央集約された送信制御である場合は、管理対象ネットワークプロキシを優先してください。
- `tools.web.fetch.useTrustedEnvProxy`: デフォルトの厳格な DNS ピンニングとホスト名ポリシーを維持しながら、オペレーター制御の HTTP(S) 環境プロキシに DNS 解決を任せるための `web_fetch` のオプトイン。[Web fetch](/ja-JP/tools/web-fetch#trusted-env-proxy)を参照してください。
- チャネルまたはプロバイダー固有のプロキシ設定: 特定のトランスポートに対する所有者固有の上書き。目的がランタイム全体の中央集約されたエグレス制御である場合は、管理対象ネットワークプロキシを優先してください。
## 設定
@ -73,7 +74,7 @@ proxy:
proxyUrl: http://127.0.0.1:3128
```
設定で `proxy.enabled=true` を維持したまま、環境経由で URL を指定することもできます。
設定で `proxy.enabled=true` を維持しながら、環境変数で URL を指定することもできます。
```bash
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
@ -81,9 +82,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` は `OPENCLAW_PROXY_URL` より優先されます。
`enabled=true` で有効なプロキシ URL が設定されていない場合、保護対象コマンドは直接ネットワークアクセスにフォールバックせず、起動に失敗します。
`enabled=true` でも有効なプロキシ URL が設定されていない場合、保護対象コマンドは直接ネットワークアクセスへフォールバックせず、起動に失敗します。
`openclaw gateway start` で起動する管理対象 Gateway サービスでは、URL を設定に保存することを推奨します。
`openclaw gateway start` で開始される管理対象 Gateway サービスでは、URL を設定に保存することを推奨します。
```bash
openclaw config set proxy.enabled true
@ -92,30 +93,30 @@ openclaw gateway install --force
openclaw gateway start
```
環境フォールバックはフォアグラウンド実行に最適です。インストール済みサービスで使う場合は、`OPENCLAW_PROXY_URL` を `$OPENCLAW_STATE_DIR/.env` や `~/.openclaw/.env` などのサービスの永続環境に入れ、その後サービスを再インストールして、launchd、systemd、またはスケジュールされたタスクがその値で Gateway を起動するようにしてください。
環境変数フォールバックはフォアグラウンド実行に最適です。インストール済みサービスで使う場合は、`OPENCLAW_PROXY_URL` を `$OPENCLAW_STATE_DIR/.env` や `~/.openclaw/.env` などのサービスの永続環境に入れてから、launchd、systemd、または Scheduled Tasks がその値で Gateway を起動するようにサービスを再インストールしてください。
`openclaw --container ...` コマンドでは、設定されている場合、OpenClaw は `OPENCLAW_PROXY_URL` をコンテナ対象の子 CLI に転送します。URL はコンテナ内から到達可能である必要があります。`127.0.0.1` はホストではなく、コンテナ自身を指します。OpenClaw は、明示的にその安全チェックを上書きしない限り、コンテナ対象コマンドのループバックプロキシ URL を拒否します。
`openclaw --container ...` コマンドでは、OpenClaw は `OPENCLAW_PROXY_URL` が設定されている場合、コンテナーを対象とする子 CLI に転送します。その URL はコンテナー内から到達可能である必要があります。`127.0.0.1` はホストではなくコンテナー自体を指します。OpenClaw は、明示的に安全性チェックを上書きしない限り、コンテナー対象コマンドのループバックプロキシ URL を拒否します。
## プロキシ要件
プロキシポリシーがセキュリティ境界です。OpenClaw は、プロキシが適切なターゲットをブロックしていることを検証できません。
プロキシを次のように設定してください。
プロキシは次のように設定してください。
- ループバックまたは信頼されたプライベートインターフェイスにのみバインドします。
- OpenClaw プロセス、ホスト、コンテナ、またはサービスアカウントだけが使えるようにアクセスを制限します。
- 宛先を自ら解決し、DNS 解決後に宛先 IP をブロックします。
- プレーン HTTP リクエストと HTTPS `CONNECT` トンネルの両方について、接続時にポリシーを適用します。
- ループバック、プライベート、リンクローカル、メタデータ、マルチキャスト、予約済み、またはドキュメント用範囲に対する宛先ベースのバイパスを拒否します。
- DNS 解決経路を完全に信頼している場合を除き、ホスト名許可リストを避けます。
- リクエスト本文、認可ヘッダー、Cookie、その他のシークレットを記録せずに、宛先、判断、ステータス、理由をログに記録します。
- プロキシポリシーをバージョン管理下に置き、セキュリティ上重要な設定と同様に変更をレビューします。
- ループバックまたはプライベートな信頼済みインターフェイスのみにバインドする。
- OpenClaw プロセス、ホスト、コンテナー、またはサービスアカウントだけが使えるようにアクセスを制限する。
- 宛先を自ら解決し、DNS 解決後に宛先 IP をブロックする。
- プレーン HTTP リクエストと HTTPS `CONNECT` トンネルの両方について、接続時にポリシーを適用する。
- ループバック、プライベート、リンクローカル、メタデータ、マルチキャスト、予約済み、またはドキュメント範囲に対する宛先ベースのバイパスを拒否する。
- DNS 解決経路を完全に信頼していない限り、ホスト名許可リストを避ける。
- リクエスト本文、認可ヘッダー、Cookie、その他の秘密情報をログに記録せず、宛先、判断、ステータス、理由をログに記録する。
- プロキシポリシーをバージョン管理下に置き、セキュリティ上重要な設定と同様に変更をレビューする。
## 推奨ブロック宛先
この拒否リストを、任意のフォワードプロキシ、ファイアウォール、送信ポリシーの出発点として使ってください。
この拒否リストを、任意のフォワードプロキシ、ファイアウォール、またはエグレスポリシーの出発点として使ってください。
OpenClaw のアプリケーションレベルの分類ロジックは `src/infra/net/ssrf.ts` と `src/shared/net/ip.ts` にあります。関連するパリティフックは `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`、および NAT64、6to4、Teredo、ISATAP、IPv4 マップ形式向けの埋め込み IPv4 センチネル処理です。これらのファイルは外部プロキシポリシーを保守する際の有用な参照ですが、OpenClaw がそれらのルールを自動的にプロキシへエクスポートしたり、プロキシ内で強制したりすることはありません。
OpenClaw のアプリケーションレベルの分類ロジックは `src/infra/net/ssrf.ts` と `src/shared/net/ip.ts` にあります。関連するパリティフックは `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`、および NAT64、6to4、Teredo、ISATAP、IPv4 マップ形式に対する埋め込み IPv4 センチネル処理です。これらのファイルは外部プロキシポリシーを保守する際の有用な参照ですが、OpenClaw がそれらのルールをプロキシへ自動的にエクスポートまたは適用することはありません。
| 範囲またはホスト | ブロックする理由 |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
@ -123,15 +124,15 @@ OpenClaw のアプリケーションレベルの分類ロジックは `src/infra
| `::1/128` | IPv6 ループバック |
| `0.0.0.0/8`, `::/128` | 未指定およびこのネットワークのアドレス |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 プライベートネットワーク |
| `169.254.0.0/16`, `fe80::/10` | リンクローカルアドレスと一般的なクラウドメタデータ経路 |
| `169.254.0.0/16`, `fe80::/10` | リンクローカルアドレスおよび一般的なクラウドメタデータ経路 |
| `169.254.169.254`, `metadata.google.internal` | クラウドメタデータサービス |
| `100.64.0.0/10` | キャリアグレード NAT 共有アドレス空間 |
| `198.18.0.0/15`, `2001:2::/48` | ベンチマーク範囲 |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途およびドキュメント用範囲 |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途およびドキュメント範囲 |
| `224.0.0.0/4`, `ff00::/8` | マルチキャスト |
| `240.0.0.0/4` | 予約済み IPv4 |
| `fc00::/7`, `fec0::/10` | IPv6 ローカル/プライベート範囲 |
| `100::/64`, `2001:20::/28` | IPv6 discard および ORCHIDv2 範囲 |
| `100::/64`, `2001:20::/28` | IPv6 破棄および ORCHIDv2 範囲 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | 埋め込み IPv4 を含む NAT64 プレフィックス |
| `2002::/16`, `2001::/32` | 埋め込み IPv4 を含む 6to4 および Teredo |
| `::/96`, `::ffff:0:0/96` | IPv4 互換および IPv4 マップ IPv6 |
@ -140,15 +141,15 @@ OpenClaw のアプリケーションレベルの分類ロジックは `src/infra
## 検証
OpenClaw を実行する同じホスト、コンテナ、またはサービスアカウントからプロキシを検証します。
OpenClaw を実行する同じホスト、コンテナー、またはサービスアカウントからプロキシを検証します。
```bash
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
デフォルトでは、カスタム宛先が指定されていない場合、コマンドは `https://example.com/` が成功することを確認し、プロキシが到達してはならない一時的なループバックカナリアを起動します。デフォルトの拒否チェックは、プロキシが 2xx 以外の拒否レスポンスを返すか、トランスポート失敗でカナリアをブロックした場合に合格します。成功レスポンスがカナリアに到達した場合は失敗します。プロキシが有効化および設定されていない場合、検証は設定の問題を報告します。設定を変更する前の一回限りのプリフライトには `--proxy-url` を使ってください。デプロイ固有の期待値をテストするには `--allowed-url` と `--denied-url` を使います。`--apns-reachable` を追加すると、直接 APNs HTTP/2 配信がプロキシ経由で CONNECT トンネルを開き、サンドボックス APNs レスポンスを受信できることも検証します。このプローブは意図的に無効なプロバイダートークンを使うため、`403 InvalidProviderToken` が期待され、到達可能として数えられます。カスタム拒否宛先はフェイルクローズです。どのような HTTP レスポンスでも、その宛先がプロキシ経由で到達可能だったことを意味し、どのようなトランスポートエラーでも、OpenClaw が到達可能なオリジンをプロキシがブロックしたと証明できないため、不確定として報告されます。検証に失敗すると、コマンドはコード 1 で終了します。
デフォルトでは、カスタム宛先が指定されていない場合、コマンドは `https://example.com/` が成功することを確認し、プロキシが到達してはならない一時的なループバックカナリアを開始します。デフォルトの拒否チェックは、プロキシが 2xx 以外の拒否レスポンスを返すか、トランスポート障害でカナリアをブロックした場合に成功します。成功レスポンスがカナリアに到達した場合は失敗します。プロキシが有効化および設定されていない場合、検証は設定問題を報告します。設定を変更する前の一回限りの事前確認には `--proxy-url` を使ってください。デプロイ固有の期待値をテストするには `--allowed-url` と `--denied-url` を使います。プロキシ経由で直接 APNs HTTP/2 配信が CONNECT トンネルを開き、サンドボックス APNs レスポンスを受信できることも検証するには、`--apns-reachable` を追加します。このプローブは意図的に無効なプロバイダートークンを使うため、`403 InvalidProviderToken` が期待され、到達可能として扱われます。カスタム拒否宛先はフェイルクローズです。HTTP レスポンスがある場合はその宛先にプロキシ経由で到達できたことを意味し、トランスポートエラーは、OpenClaw がプロキシが到達可能なオリジンをブロックしたと証明できないため、不確定として報告されます。検証に失敗した場合、コマンドはコード 1 で終了します。
自動化には `--json` を使ってください。JSON 出力には、全体の結果、有効なプロキシ設定ソース、設定エラー、各宛先チェックが含まれます。プロキシ URL の認証情報は、テキストおよび JSON 出力で伏せられます。
自動化には `--json` を使用します。JSON 出力には、全体の結果、有効なプロキシ設定のソース、設定エラー、各宛先チェックが含まれます。プロキシ URL の認証情報は、テキスト出力と JSON 出力で伏せられます。
```json
{
@ -184,7 +185,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
パブリックリクエストは成功するはずです。ループバックとメタデータのリクエストはプロキシによってブロックされるはずです。`openclaw proxy validate` では、組み込みのループバックカナリアによって、プロキシによる拒否と到達可能なオリジンを区別できます。カスタムの `--denied-url` チェックにはそのカナリアがないため、プロキシがデプロイ固有の拒否シグナルを公開していて別途検証できる場合を除き、HTTP レスポンスと曖昧なトランスポート障害の両方を検証失敗として扱ってください。
公開リクエストは成功するはずです。ループバックリクエストとメタデータリクエストはプロキシによってブロックされるはずです。`openclaw proxy validate` では、組み込みのループバックカナリアによって、プロキシ拒否と到達可能なオリジンを区別できます。カスタム `--denied-url` チェックにはそのカナリアがないため、プロキシがデプロイ固有の拒否シグナルを公開していて別途検証できる場合を除き、HTTP レスポンスと曖昧なトランスポート障害の両方を検証失敗として扱ってください。
次に、OpenClaw のプロキシルーティングを有効にします。
@ -194,7 +195,7 @@ openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run
```
または次を設定します。
または、次を設定します。
```yaml
proxy:
@ -204,11 +205,11 @@ proxy:
## 制限
- プロキシはプロセスローカルの JavaScript HTTP および WebSocket クライアントのカバレッジを改善しますが、OS レベルのネットワークサンドボックスではありません。
- 生の `net`、`tls`、`http2` ソケット、ネイティブアドオン、子プロセスは、プロキシ環境変数を継承して尊重しない限り、Node レベルのプロキシルーティングをバイパスする場合があります。
- IRC は、オペレーター管理のフォワードプロキシルーティングの外側にある生の TCP/TLS チャネルです。すべての外向き通信をそのフォワードプロキシ経由にする必要があるデプロイでは、直接の IRC 外向き通信が明示的に承認されていない限り、`channels.irc.enabled=false` を設定してください。
- ローカルデバッグプロキシは診断用ツールであり、管理プロキシモードが有効な間、プロキシリクエストと CONNECT トンネルに対する直接アップストリーム転送はデフォルトで無効です。直接転送は、承認されたローカル診断でのみ有効にしてください。
- 必要に応じて、ユーザーのローカル WebUI とローカルモデルサーバーをオペレーターのプロキシポリシーで許可リストに追加してください。OpenClaw は、それらに対する一般的なローカルネットワークバイパスを公開しません。
- Gateway コントロールプレーンのプロキシバイパスは、意図的に `localhost` とリテラルのループバック IP URL に限定されています。ローカルの直接 Gateway コントロールプレーン接続には、`ws://127.0.0.1:18789`、`ws://[::1]:18789`、または `ws://localhost:18789` を使用してください。その他のホスト名は、通常のホスト名ベースのトラフィックと同様にルーティングされます。
- OpenClaw は、プロキシポリシーを検査、テスト、認証しません。
- プロキシは、プロセスローカルな JavaScript HTTP クライアントと WebSocket クライアントのカバレッジを改善しますが、OS レベルのネットワークサンドボックスではありません。
- 生の `net`、`tls`、`http2` ソケット、ネイティブアドオン、子プロセスは、プロキシ環境変数を継承して尊重しない限り、Node レベルのプロキシルーティングをバイパスする可能性があります。
- IRC は、オペレーター管理のフォワードプロキシルーティングの外側にある生の TCP/TLS チャネルです。すべての外向き通信をそのフォワードプロキシ経由にする必要があるデプロイでは、直接 IRC 外向き通信が明示的に承認されていない限り、`channels.irc.enabled=false` を設定してください。
- ローカルデバッグプロキシは診断ツールです。管理対象プロキシモードが有効な間、プロキシリクエストと CONNECT トンネルの直接アップストリーム転送はデフォルトで無効です。承認済みのローカル診断でのみ直接転送を有効にしてください。
- ユーザーのローカル WebUI とローカルモデルサーバーは、必要に応じてオペレータープロキシポリシーで許可リストに追加する必要があります。OpenClaw は、それらに対する汎用的なローカルネットワークバイパスを公開しません。
- Gateway コントロールプレーンのプロキシバイパスは、意図的に `localhost` とリテラルのループバック IP URL に限定されています。ローカル直接 Gateway コントロールプレーン接続には `ws://127.0.0.1:18789`、`ws://[::1]:18789`、または `ws://localhost:18789` を使用してください。その他のホスト名は、通常のホスト名ベースのトラフィックと同様にルーティングされます。
- OpenClaw は、プロキシポリシーを検査、テスト、または認証しません。
- プロキシポリシーの変更は、セキュリティ上重要な運用変更として扱ってください。

91
docs/ja-JP/tools/loop-detection.md
View File

@ -1,29 +1,29 @@
---
read_when:
- ユーザーが、エージェントがツール呼び出しを繰り返したまま停止することを報告している
- ユーザーが、エージェントがツール呼び出しを繰り返したまま停止する問題を報告しています
- 繰り返し呼び出し保護を調整する必要があります
- エージェントのツール/ランタイムポリシーを編集している場合
summary: 反復的なツール呼び出しループを検出するガードレールを有効化し、調整する方法
- エージェントのツール/ランタイムポリシーを編集しています
summary: 反復的なツール呼び出しループを検出するガードレールを有効化し調整する方法
title: ツールループ検出
x-i18n:
generated_at: "2026-05-03T21:39:33Z"
generated_at: "2026-05-05T01:49:43Z"
model: gpt-5.5
provider: openai
source_hash: 1b3976948d5735cf08b7ce854bab048a77a778a07a9f3f66d17c15aed0d42a97
source_hash: b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb
source_path: tools/loop-detection.md
workflow: 16
---
OpenClaw は、エージェントが反復的なツール呼び出しパターンにはまり込むのを防げます。
このガードは**デフォルトでは無効**です。
OpenClaw は、エージェントが繰り返しのツール呼び出しパターンにはまり込むのを防げます。
このガードは**デフォルトで無効**です。
厳格な設定では正当な反復呼び出しをブロックする可能性があるため、必要な場所でのみ有効にしてください。
厳しい設定では正当な繰り返し呼び出しをブロックする可能性があるため、必要な場所でのみ有効にしてください。
## これが存在する理由
## 存在する理由
- 進捗のない反復シーケンスを検出する。
- 高頻度の結果なしループ（同じツール、同じ入力、反復エラー）を検出する。
- 既知のポーリングツール向けの特定の反復呼び出しパターンを検出する。
- 進行しない反復シーケンスを検出する。
- 高頻度の結果なしループ（同じツール、同じ入力、繰り返されるエラー）を検出する。
- 既知のポーリングツール向けの特定の繰り返し呼び出しパターンを検出する。
## 設定ブロック
@ -69,42 +69,65 @@ OpenClaw は、エージェントが反復的なツール呼び出しパター
}
```
### フィールドの挙動
### フィールドの動作
- `enabled`: マスタースイッチ。`false` はループ検出を実行しないことを意味する。
- `historySize`: 分析用に保持する最近のツール呼び出し数。
- `enabled`: マスタースイッチ。`false` はループ検出が実行されないことを意味します。
- `historySize`: 分析のために保持される直近のツール呼び出し数。
- `warningThreshold`: パターンを警告のみとして分類する前のしきい値。
- `criticalThreshold`: 反復的なループパターンをブロックするしきい値。
- `globalCircuitBreakerThreshold`: グローバルな進捗なしブレーカーしきい値。
- `detectors.genericRepeat`: 同じツール + 同じパラメーターの反復パターンを検出する。
- `detectors.knownPollNoProgress`: 状態変化のない既知のポーリングに似たパターンを検出する。
- `detectors.pingPong`: 交互に発生するピンポンパターンを検出する。
- `criticalThreshold`: 反復ループパターンをブロックするしきい値。
- `globalCircuitBreakerThreshold`: グローバルな進行なしブレーカーのしきい値。
- `detectors.genericRepeat`: 同じツール + 同じパラメーターの繰り返しパターンを検出します。
- `detectors.knownPollNoProgress`: 状態変化のない既知のポーリング風パターンを検出します。
- `detectors.pingPong`: 交互に繰り返すピンポンパターンを検出します。
`exec` では、進捗なしチェックは安定したコマンド結果を比較し、実行時間、PID、セッション ID、作業ディレクトリなどの揮発性の実行時メタデータを無視します。
実行 ID が利用可能な場合、最近のツール呼び出し履歴はその実行内でのみ評価されるため、スケジュールされた Heartbeat サイクルや新しい実行が、以前の実行から古いループ数を引き継ぐことはありません。
`exec` では、進行なしチェックは安定したコマンド結果を比較し、所要時間、PID、セッション ID、作業ディレクトリなどの変動しやすい実行時メタデータを無視します。
run id が利用可能な場合、直近のツール呼び出し履歴はその実行内でのみ評価されるため、スケジュールされた Heartbeat サイクルや新規実行が以前の実行から古いループ回数を引き継ぐことはありません。
## 推奨設定
## 推奨セットアップ
- 小さめのモデルでは、`enabled: true` から始め、デフォルトは変更しないでください。フラッグシップモデルではループ検出が必要になることはまれで、無効のままにできます。
- しきい値は `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold` の順序を保ってください。
- 誤検出が発生する場合:
- `warningThreshold` や `criticalThreshold` を引き上げる
- （任意で）`globalCircuitBreakerThreshold` を引き上げる
- 小さめのモデルでは、`enabled: true` にしてデフォルトは変更せずに開始します。フラッグシップモデルではループ検出が必要になることはまれで、無効のままにできます。
- しきい値は `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold` の順に保ちます。
- 誤検知が発生する場合:
- `warningThreshold` と、または `criticalThreshold` を上げる
- （任意で）`globalCircuitBreakerThreshold` を上げる
- 問題を起こしている検出器だけを無効にする
- 厳格さの低い履歴コンテキストにするために `historySize` を減らす
- 履歴コンテキストを緩くするために `historySize` を減らす
## ログと期待される挙動
## Compaction 後ガード
runner が（コンテキストオーバーフロー後に）自動 Compaction リトライを完了すると、次の数回のツール呼び出しを監視する短いウィンドウのガードを有効にします。エージェントがそのウィンドウ内で_同じ_ `(toolName, args, result)` の組を複数回出力した場合、ガードは Compaction がループを断ち切れなかったと判断し、`compaction_loop_persisted` エラーで実行を中止します。
これはグローバルな `tools.loopDetection` 検出器とは別のコードパスです。独立して設定できます:
```json5
{
tools: {
loopDetection: {
enabled: true, // existing master switch; set false to disable loop guards
postCompactionGuard: {
windowSize: 3, // default: 3
},
},
},
}
```
- `windowSize`: ガードが有効なまま維持される Compaction 後のツール呼び出し数であり、中止を引き起こす同一の（tool、args、result）組の回数でもあります。
このガードは、結果が変化している場合には中止せず、ウィンドウ全体で結果がバイト単位で同一の場合にのみ中止します。意図的に範囲を狭くしており、Compaction リトライ直後にのみ発火します。
## ログと期待される動作
ループが検出されると、OpenClaw はループイベントを報告し、重大度に応じて次のツールサイクルをブロックまたは抑制します。
これにより、通常のツールアクセスを保ちながら、暴走したトークン消費やロックアップからユーザーを保護します。
これにより、通常のツールアクセスを維持しながら、暴走するトークン消費とロックアップからユーザーを保護します。
- まず警告と一時的な抑制を優先してください。
- 反復した証拠が蓄積された場合にのみエスカレートしてください。
- まず警告と一時的な抑制を優先します。
- 繰り返しの証拠が蓄積した場合にのみエスカレートします。
## 注記
- `tools.loopDetection` はエージェントレベルの上書きとマージされます。
- エージェントごとの設定は、グローバル値を完全に上書きするか拡張します。
- エージェントごとの設定は、グローバル値を完全に上書きまたは拡張します。
- 設定が存在しない場合、ガードレールはオフのままです。
## 関連

98
docs/ja-JP/tools/media-overview.md
View File

@ -1,51 +1,51 @@
---
read_when:
- OpenClaw のメディア機能の概要を探している
- 設定するメディアプロバイダーの選択
- OpenClawのメディア機能の概要を探す
- 設定するメディアプロバイダーを決める
- 非同期メディア生成の仕組みを理解する
sidebarTitle: Media overview
summary: 画像、動画、音楽、音声、メディア理解機能の概要
title: メディアの概要
title: メディア概要
x-i18n:
generated_at: "2026-04-30T05:39:03Z"
generated_at: "2026-05-05T01:50:12Z"
model: gpt-5.5
provider: openai
source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508
source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059
source_path: tools/media-overview.md
workflow: 16
---
OpenClaw は画像、動画、音楽を生成し、受信メディア
（画像、音声、動画）を理解し、テキスト読み上げで返信を音声として読み上げます。すべての
メディア機能はツール駆動です。エージェントは会話に基づいてそれらをいつ使うかを判断し、
各ツールは少なくとも 1 つのバックエンドプロバイダーが設定されている場合にのみ表示されます。
メディア機能はツール駆動です。エージェントは会話に基づいて使用タイミングを判断し、
各ツールは少なくとも1つの対応プロバイダーが設定されている場合にのみ表示されます。
## 機能
<CardGroup cols={2}>
<Card title="画像生成" href="/ja-JP/tools/image-generation" icon="image">
テキストプロンプトまたは参照画像から
`image_generate` 経由で画像を作成・編集します。同期 — 返信内でインラインに完了します。
テキストプロンプトまたは参照画像から、
`image_generate` で画像を作成・編集します。同期処理 — 返信内で完了します。
</Card>
<Card title="動画生成" href="/ja-JP/tools/video-generation" icon="video">
`video_generate` 経由で、テキストから動画、画像から動画、動画から動画を生成します。
非同期 — バックグラウンドで実行され、準備ができると結果を投稿します。
`video_generate` で、テキストから動画、画像から動画、動画から動画を生成します。
非同期処理 — バックグラウンドで実行され、準備ができたら結果を投稿します。
</Card>
<Card title="音楽生成" href="/ja-JP/tools/music-generation" icon="music">
`music_generate` 経由で音楽または音声トラックを生成します。共有
プロバイダーでは非同期です。ComfyUI ワークフローパスは同期実行されます。
`music_generate` で音楽または音声トラックを生成します。共有
プロバイダーでは非同期です。ComfyUI ワークフローパスは同期的に実行されます。
</Card>
<Card title="テキスト読み上げ" href="/ja-JP/tools/tts" icon="microphone">
`tts` ツールと `messages.tts` 設定を使って、送信返信を音声に変換します。
同期です。
`tts` ツールと
`messages.tts` 設定により、送信返信を音声に変換します。同期処理です。
</Card>
<Card title="メディア理解" href="/ja-JP/nodes/media-understanding" icon="eye">
視覚対応モデルプロバイダーと専用のメディア理解 Plugin を使用して、
ビジョン対応モデルプロバイダーと専用のメディア理解 Plugin を使って、
受信画像、音声、動画を要約します。
</Card>
<Card title="音声テキスト変換" href="/ja-JP/nodes/audio" icon="ear-listen">
バッチ STT または Voice Call ストリーミング STT プロバイダーを通じて、
受信音声メッセージを文字起こしします。
バッチ STT または Voice Call
ストリーミング STT プロバイダーを通じて、受信ボイスメッセージを書き起こします。
</Card>
</CardGroup>
@ -77,60 +77,62 @@ OpenClaw は画像、動画、音楽を生成し、受信メディア
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
<Note>
メディア理解は、プロバイダー設定に登録された任意の視覚対応または音声対応モデルを使用します。
上のマトリクスには、専用のメディア理解サポートを持つプロバイダーを記載しています。
ほとんどのマルチモーダル LLM プロバイダー（Anthropic、Google、
OpenAI など）も、アクティブな返信モデルとして設定されている場合は受信メディアを理解できます。
メディア理解は、プロバイダー設定に登録されたビジョン対応または音声対応モデルを使用します。
上のマトリクスは専用のメディア理解サポートがあるプロバイダーを示しています。ほとんどの
マルチモーダル LLM プロバイダー（Anthropic、Google、
OpenAI など）も、有効な返信モデルとして設定されている場合は受信メディアを理解できます。
</Note>
## 非同期と同期
| 機能 | モード | 理由 |
| 機能 | モード | 理由 |
| --------------- | ------------ | ------------------------------------------------------------------ |
| 画像 | 同期 | プロバイダーの応答は数秒で返り、返信内でインラインに完了します。 |
| テキスト読み上げ | 同期 | プロバイダーの応答は数秒で返り、返信音声に添付されます。 |
| 動画 | 非同期 | プロバイダー処理には 30 秒から数分かかります。 |
| 音楽（共有） | 非同期 | 動画と同じプロバイダー処理特性です。 |
| 音楽（ComfyUI） | 同期 | ローカルワークフローが設定済みの ComfyUI サーバーに対してインラインに実行されます。 |
| 画像 | 同期 | プロバイダーの応答は数秒で返り、返信内で完了します。 |
| テキスト読み上げ | 同期 | プロバイダーの応答は数秒で返り、返信音声に添付されます。 |
| 動画 | 非同期 | プロバイダー処理に30秒から数分かかります。 |
| 音楽（共有） | 非同期 | 動画と同じプロバイダー処理特性です。 |
| 音楽（ComfyUI） | 同期 | ローカルワークフローが、設定済みの ComfyUI サーバーに対して返信内で実行されます。 |
非同期ツールの場合、OpenClaw はリクエストをプロバイダーに送信し、タスク
id を即座に返して、タスク台帳でジョブを追跡します。エージェントは
ジョブの実行中も他のメッセージへの応答を続けます。プロバイダーが完了すると、
OpenClaw はエージェントを起動し、完成したメディアを元のチャネルに投稿できるようにします。
非同期ツールでは、OpenClaw はリクエストをプロバイダーに送信し、タスク
ID を即座に返し、タスク台帳でジョブを追跡します。エージェントは
ジョブの実行中も他のメッセージへの返信を続けます。プロバイダーが完了すると、
OpenClaw は生成されたメディアパスとともにエージェントを起動し、エージェントが
ユーザーに通知し、ソース配信ポリシーで必要な場合はメッセージツールを通じて
結果を中継できるようにします。
## 音声テキスト変換と Voice Call
Deepgram、DeepInfra、ElevenLabs、Mistral、OpenAI、SenseAudio、xAI はすべて、
設定されていればバッチ `tools.media.audio` パスを通じて受信音声を文字起こしできます。
メンションゲートやコマンド解析のためにボイスノートを事前確認するチャネル Plugin は、
受信コンテキスト上で文字起こし済み添付ファイルをマークするため、共有
メディア理解パスは同じ音声に対して 2 回目の STT 呼び出しを行わず、そのトランスクリプトを再利用します。
設定されている場合、バッチ `tools.media.audio` パスを通じて受信音声を書き起こせます。
メンション制御やコマンド解析のためにボイスノートを事前チェックするチャネル Plugin は、
受信コンテキストで書き起こし済み添付ファイルをマークするため、共有の
メディア理解パスは同じ音声に対して2回目の STT 呼び出しを行わずにその文字起こしを再利用します。
Deepgram、ElevenLabs、Mistral、OpenAI、xAI は Voice Call
ストリーミング STT プロバイダーも登録するため、完了済み録音を待たずにライブ通話音声を選択した
ベンダーへ転送できます。
ストリーミング STT プロバイダーも登録するため、完了した録音を待たずに
ライブ電話音声を選択したベンダーへ転送できます。
## プロバイダーマッピング（ベンダーが各サーフェスにどう分かれるか）
## プロバイダーマッピング（ベンダーがサーフェス間でどのように分かれるか）
<AccordionGroup>
<Accordion title="Google">
画像、動画、音楽、バッチ TTS、バックエンドリアルタイム音声、および
画像、動画、音楽、バッチ TTS、バックエンドのリアルタイム音声、
メディア理解サーフェス。
</Accordion>
<Accordion title="OpenAI">
画像、動画、バッチ TTS、バッチ STT、Voice Call ストリーミング STT、バックエンド
リアルタイム音声、およびメモリエンベディングサーフェス。
画像、動画、バッチ TTS、バッチ STT、Voice Call ストリーミング STT、バックエンドの
リアルタイム音声、メモリ埋め込みサーフェス。
</Accordion>
<Accordion title="DeepInfra">
チャット/モデルルーティング、画像生成/編集、テキストから動画、バッチ TTS、
バッチ STT、画像メディア理解、およびメモリエンベディングサーフェス。
DeepInfra ネイティブのリランク/分類/物体検出モデルは、OpenClaw がそれらの
カテゴリ専用のプロバイダー契約を持つまで登録されません。
バッチ STT、画像メディア理解、メモリ埋め込みサーフェス。
DeepInfra ネイティブの再ランキング/分類/物体検出モデルは、OpenClaw が
これらのカテゴリ専用のプロバイダー契約を持つまで登録されません。
</Accordion>
<Accordion title="xAI">
画像、動画、検索、コード実行、バッチ TTS、バッチ STT、および Voice
Call ストリーミング STT。xAI Realtime voice は上流の機能ですが、共有リアルタイム音声契約で
表現できるようになるまで OpenClaw には登録されません。
画像、動画、検索、コード実行、バッチ TTS、バッチ STT、Voice
Call ストリーミング STT。xAI Realtime 音声は上流の機能ですが、
共有リアルタイム音声契約で表現できるようになるまで OpenClaw には登録されません。
</Accordion>
</AccordionGroup>

142
docs/ja-JP/tools/music-generation.md
View File

@ -1,38 +1,37 @@
---
read_when:
- エージェントによる音楽または音声の生成
- エージェント経由で音楽または音声を生成する
- 音楽生成プロバイダーとモデルの設定
- music_generate ツールのパラメーターを理解する
sidebarTitle: Music generation
summary: Google Lyria、MiniMax、ComfyUI のワークフロー全体で music_generate を介して音楽を生成する
title: 音楽生成
x-i18n:
generated_at: "2026-05-02T21:08:05Z"
generated_at: "2026-05-05T01:50:27Z"
model: gpt-5.5
provider: openai
source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26
source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650
source_path: tools/music-generation.md
workflow: 16
---
`music_generate` ツールにより、エージェントは設定済みプロバイダー（現在は Google、MiniMax、ワークフロー設定済みの ComfyUI）を使って、共有の音楽生成機能を通じて音楽または音声を作成できます。
`music_generate` ツールを使うと、エージェントは構成済みプロバイダー（現在は Google、MiniMax、ワークフロー構成済み ComfyUI）による共有の音楽生成機能を通じて、音楽または音声を作成できます。
セッションに裏付けられたエージェント実行では、OpenClaw は音楽生成をバックグラウンドタスクとして開始し、タスク台帳で追跡し、トラックの準備ができたらエージェントを再度起動して、完成した音声を元のチャンネルに投稿できるようにします。
セッションに基づくエージェント実行では、OpenClaw は音楽生成をバックグラウンドタスクとして開始し、タスク台帳で追跡し、トラックの準備ができるとエージェントを再度起動して、エージェントがユーザーに知らせ、完成した音声を添付できるようにします。メッセージツールのみで可視配信するグループ/チャンネルチャットでは、エージェントはメッセージツールを通じて結果を中継します。
<Note>
組み込みの共有ツールは、少なくとも 1 つの音楽生成プロバイダーが利用可能な場合にのみ表示されます。エージェントのツールに `music_generate` が表示されない場合は、`agents.defaults.musicGenerationModel` を設定するか、プロバイダーの API キーを設定してください。
組み込みの共有ツールは、少なくとも 1 つの音楽生成プロバイダーが利用可能な場合にのみ表示されます。エージェントのツールに `music_generate` が表示されない場合は、`agents.defaults.musicGenerationModel` を構成するか、プロバイダー API キーを設定してください。
</Note>
## クイックスタート
<Tabs>
<Tab title="Shared provider-backed">
<Tab title="共有プロバイダー利用">
<Steps>
<Step title="Configure auth">
少なくとも 1 つのプロバイダーに API キーを設定します。たとえば
`GEMINI_API_KEY` または `MINIMAX_API_KEY` です。
<Step title="認証を構成する">
少なくとも 1 つのプロバイダーに API キーを設定します。たとえば `GEMINI_API_KEY` または `MINIMAX_API_KEY` です。
</Step>
<Step title="Pick a default model (optional)">
<Step title="デフォルトモデルを選択する（任意）">
```json5
{
agents: {
@ -45,25 +44,25 @@ x-i18n:
}
```
</Step>
<Step title="Ask the agent">
_「ネオンの街を夜にドライブすることをテーマにした、明るいシンセポップのトラックを生成して。」_
<Step title="エージェントに依頼する">
_「ネオンの街を夜にドライブする、明るいシンセポップのトラックを生成して。」_
エージェントは `music_generate` を自動的に呼び出します。ツールの許可リスト設定は不要です。
エージェントは `music_generate` を自動的に呼び出します。ツールの許可リスト登録は不要です。
</Step>
</Steps>
セッションに裏付けられたエージェント実行のない直接同期コンテキストでは、組み込みツールは引き続きインライン生成にフォールバックし、ツール結果で最終メディアパスを返します。
セッションに基づくエージェント実行がない直接同期コンテキストでは、組み込みツールは引き続きインライン生成にフォールバックし、ツール結果で最終メディアパスを返します。
</Tab>
<Tab title="ComfyUI workflow">
<Tab title="ComfyUI ワークフロー">
<Steps>
<Step title="Configure the workflow">
ワークフロー JSON とプロンプト/出力ノードを使って `plugins.entries.comfy.config.music` を設定します。
<Step title="ワークフローを構成する">
ワークフロー JSON とプロンプト/出力ノードを使って `plugins.entries.comfy.config.music` を構成します。
</Step>
<Step title="Cloud auth (optional)">
<Step title="クラウド認証（任意）">
Comfy Cloud の場合は、`COMFY_API_KEY` または `COMFY_CLOUD_API_KEY` を設定します。
</Step>
<Step title="Call the tool">
<Step title="ツールを呼び出す">
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
@ -84,20 +83,20 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## サポートされているプロバイダー
| プロバイダー | デフォルトモデル | 参照入力 | サポートされる制御 | 認証 |
| プロバイダー | デフォルトモデル | 参照入力 | サポートされている制御 | 認証 |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | 最大 1 枚の画像 | ワークフロー定義の音楽または音声 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | 最大 10 枚の画像 | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| ComfyUI | `workflow` | 最大 1 画像 | ワークフローで定義された音楽または音声 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | 最大 10 画像 | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | なし | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` または MiniMax OAuth |
### 機能マトリクス
`music_generate`、コントラクトテスト、共有ライブスイープで使用される明示的なモードコントラクト:
`music_generate`、契約テスト、共有ライブスイープで使用される明示的なモード契約:
| プロバイダー | `generate` | `edit` | 編集制限 | 共有ライブレーン |
| プロバイダー | `generate` | `edit` | 編集上限 | 共有ライブレーン |
| -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- |
| ComfyUI | ✓ | ✓ | 1 枚の画像 | 共有スイープには含まれません。`extensions/comfy/comfy.live.test.ts` でカバーされます |
| Google | ✓ | ✓ | 10 枚の画像 | `generate`, `edit` |
| ComfyUI | ✓ | ✓ | 1 画像 | 共有スイープには含まれません。`extensions/comfy/comfy.live.test.ts` でカバーされます |
| Google | ✓ | ✓ | 10 画像 | `generate`, `edit` |
| MiniMax | ✓ | — | なし | `generate` |
実行時に利用可能な共有プロバイダーとモデルを調べるには、`action: "list"` を使用します。
@ -106,7 +105,7 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
/tool music_generate action=list
```
アクティブなセッション連動音楽タスクを調べるには、`action: "status"` を使用します。
アクティブなセッションに基づく音楽タスクを調べるには、`action: "status"` を使用します。
```text
/tool music_generate action=status
@ -124,56 +123,55 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
音楽生成プロンプト。`action: "generate"` では必須です。
</ParamField>
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` は現在のセッションタスクを返し、`"list"` はプロバイダーを調べます。
`"status"` は現在のセッションタスクを返します。`"list"` はプロバイダーを調べます。
</ParamField>
<ParamField path="model" type="string">
プロバイダー/モデルの上書き（例: `google/lyria-3-pro-preview`,
`comfy/workflow`）。
プロバイダー/モデルの上書き（例: `google/lyria-3-pro-preview`, `comfy/workflow`）。
</ParamField>
<ParamField path="lyrics" type="string">
プロバイダーが明示的な歌詞入力をサポートしている場合の任意の歌詞。
プロバイダーが明示的な歌詞入力をサポートする場合の任意の歌詞。
</ParamField>
<ParamField path="instrumental" type="boolean">
プロバイダーがサポートしている場合に、インストゥルメンタルのみの出力を要求します。
プロバイダーがサポートする場合に、インストゥルメンタルのみの出力を要求します。
</ParamField>
<ParamField path="image" type="string">
単一の参照画像パスまたは URL。
</ParamField>
<ParamField path="images" type="string[]">
複数の参照画像（対応プロバイダーでは最大 10 枚）。
複数の参照画像（対応プロバイダーでは最大 10）。
</ParamField>
<ParamField path="durationSeconds" type="number">
プロバイダーが長さのヒントをサポートしている場合の目標秒数。
プロバイダーが再生時間ヒントをサポートする場合の目標再生時間（秒）。
</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>
プロバイダーがサポートしている場合の出力形式ヒント。
プロバイダーがサポートする場合の出力形式ヒント。
</ParamField>
<ParamField path="filename" type="string">出力ファイル名のヒント。</ParamField>
<ParamField path="timeoutMs" type="number">任意のプロバイダーリクエストタイムアウト（ミリ秒）。10000ms 未満の値は 10000ms に引き上げられ、ツール結果で報告されます。</ParamField>
<Note>
すべてのプロバイダーがすべてのパラメーターをサポートしているわけではありません。OpenClaw は送信前に入力数などのハードリミットを引き続き検証します。プロバイダーが長さをサポートしているものの、要求値より短い最大値を使用する場合、OpenClaw は最も近いサポート対象の長さに丸めます。本当にサポートされていない任意のヒントは、選択したプロバイダーまたはモデルがそれらを満たせない場合、警告付きで無視されます。ツール結果には適用された設定が報告され、`details.normalization` には要求値から適用値へのマッピングが記録されます。
すべてのプロバイダーがすべてのパラメーターをサポートするわけではありません。OpenClaw は送信前に入力数などの厳格な上限を引き続き検証します。プロバイダーが再生時間をサポートしていても、要求値より短い最大値を使用する場合、OpenClaw は最も近いサポート済み再生時間に制限します。選択されたプロバイダーまたはモデルが本当にサポートできない任意のヒントは、警告付きで無視されます。ツール結果は適用済み設定を報告します。`details.normalization` は要求値から適用値へのマッピングを記録します。
</Note>
## 非同期動作
セッションに裏付けられた音楽生成はバックグラウンドタスクとして実行されます。
セッションに基づく音楽生成はバックグラウンドタスクとして実行されます。
- **バックグラウンドタスク:** `music_generate` はバックグラウンドタスクを作成し、開始済み/タスクレスポンスをすぐに返し、完成したトラックを後続のエージェントメッセージで後から投稿します。
- **重複防止:** タスクが `queued` または `running` の間、同じセッション内の後続の `music_generate` 呼び出しは、別の生成を開始する代わりにタスクステータスを返します。明示的に確認するには `action: "status"` を使用します。
- **ステータス検索:** `openclaw tasks list` または `openclaw tasks show <taskId>` は、キュー済み、実行中、終端ステータスを調べます。
- **完了時の起動:** OpenClaw は内部の完了イベントを同じセッションに注入し、モデルがユーザー向けのフォローアップを自分で書けるようにします。
- **プロンプトヒント:** 同じセッション内の後続のユーザー/手動ターンでは、音楽タスクがすでに進行中の場合に小さなランタイムヒントが与えられるため、モデルが無条件に `music_generate` を再度呼び出すことを防げます。
- **セッションなしのフォールバック:** 実際のエージェントセッションを持たない直接/ローカルコンテキストはインラインで実行され、同じターンで最終的な音声結果を返します。
- **バックグラウンドタスク:** `music_generate` はバックグラウンドタスクを作成し、開始済み/タスクレスポンスをすぐに返し、後続のエージェントメッセージで完成したトラックを後から投稿します。
- **重複防止:** タスクが `queued` または `running` の間、同じセッション内の後続の `music_generate` 呼び出しは、別の生成を開始せずにタスクステータスを返します。明示的に確認するには `action: "status"` を使用します。
- **ステータス検索:** `openclaw tasks list` または `openclaw tasks show <taskId>` は、キュー済み、実行中、終了ステータスを調べます。
- **完了時の起動:** OpenClaw は内部完了イベントを同じセッションへ戻して注入し、モデルがユーザー向けのフォローアップを自分で書けるようにします。
- **プロンプトヒント:** 同じセッション内の後続のユーザー/手動ターンでは、音楽タスクがすでに進行中の場合に小さな実行時ヒントを受け取り、モデルが盲目的に `music_generate` を再度呼び出さないようにします。
- **セッションなしのフォールバック:** 実際のエージェントセッションを持たない直接/ローカルコンテキストではインラインで実行され、同じターンで最終音声結果を返します。
### タスクライフサイクル
| 状態 | 意味 |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued` | タスクが作成され、プロバイダーが受け付けるのを待っています。 |
| `running` | プロバイダーが処理中です（通常はプロバイダーと長さに応じて 30 秒から 3 分）。 |
| `succeeded` | トラックの準備ができました。エージェントが起動して会話に投稿します。 |
| `failed` | プロバイダーエラーまたはタイムアウトです。エージェントがエラー詳細付きで起動します。 |
| `queued` | タスクが作成され、プロバイダーの受け付けを待っています。 |
| `running` | プロバイダーが処理中です（通常、プロバイダーと再生時間に応じて 30 秒から 3 分）。 |
| `succeeded` | トラックの準備ができました。エージェントが起動し、会話に投稿します。 |
| `failed` | プロバイダーエラーまたはタイムアウトです。エージェントがエラー詳細とともに起動します。 |
CLI からステータスを確認します。
@ -183,7 +181,7 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
## 設定
## 構成
### モデル選択
@ -200,18 +198,18 @@ openclaw tasks cancel <taskId>
}
```
### プロバイダー選択順
### プロバイダー選択順序
OpenClaw は次の順序でプロバイダーを試行します。
1. ツール呼び出しの `model` パラメーター（エージェントが指定した場合）。
2. 設定の `musicGenerationModel.primary`。
3. 順番どおりの `musicGenerationModel.fallbacks`。
4. 認証に裏付けられたプロバイダーのデフォルトのみを使った自動検出:
- 現在のデフォルトプロバイダーが最初。
- 残りの登録済み音楽生成プロバイダーを provider-id 順で。
2. 構成の `musicGenerationModel.primary`。
3. `musicGenerationModel.fallbacks`（順番どおり）。
4. 認証に基づくプロバイダーデフォルトのみを使用した自動検出:
- 現在のデフォルトプロバイダーを最初に使用します。
- 残りの登録済み音楽生成プロバイダーをプロバイダー ID 順に使用します。
プロバイダーが失敗した場合、次の候補が自動的に試行されます。すべて失敗した場合、エラーには各試行の詳細が含まれます。
プロバイダーが失敗すると、次の候補が自動的に試行されます。すべて失敗した場合、エラーには各試行の詳細が含まれます。
明示的な `model`、`primary`、`fallbacks` エントリのみを使用するには、`agents.defaults.mediaGenerationAutoProviderFallback: false` を設定します。
@ -219,29 +217,29 @@ OpenClaw は次の順序でプロバイダーを試行します。
<AccordionGroup>
<Accordion title="ComfyUI">
ワークフロー駆動であり、設定されたグラフとプロンプト/出力フィールドのノードマッピングに依存します。バンドルされた `comfy` Plugin は、音楽生成プロバイダーレジストリを通じて共有 `music_generate` ツールに接続します。
ワークフロー駆動であり、構成済みグラフと、プロンプト/出力フィールドのノードマッピングに依存します。バンドルされた `comfy` Plugin は、音楽生成プロバイダーレジストリを通じて共有 `music_generate` ツールに接続します。
</Accordion>
<Accordion title="Google (Lyria 3)">
Lyria 3 バッチ生成を使用します。現在のバンドルフローは、プロンプト、任意の歌詞テキスト、任意の参照画像をサポートしています。
Lyria 3 バッチ生成を使用します。現在のバンドルフローは、プロンプト、任意の歌詞テキスト、任意の参照画像をサポートします。
</Accordion>
<Accordion title="MiniMax">
バッチ `music_generation` エンドポイントを使用します。プロンプト、任意の歌詞、インストゥルメンタルモード、長さの誘導、mp3 出力を、`minimax` API キー認証または `minimax-portal` OAuth のいずれかを通じてサポートします。
バッチ `music_generation` エンドポイントを使用します。`minimax` API キー認証または `minimax-portal` OAuth のいずれかを通じて、プロンプト、任意の歌詞、インストゥルメンタルモード、再生時間の制御、mp3 出力をサポートします。
</Accordion>
</AccordionGroup>
## 適切なパスの選択
## 適切な経路の選択
- **共有プロバイダー連動** は、モデル選択、プロバイダーのフェイルオーバー、組み込みの非同期タスク/ステータスフローが必要な場合に使用します。
- **Plugin パス（ComfyUI）** は、カスタムワークフローグラフ、または共有バンドル音楽機能の一部ではないプロバイダーが必要な場合に使用します。
- **共有プロバイダー利用** は、モデル選択、プロバイダーフェイルオーバー、組み込みの非同期タスク/ステータスフローが必要な場合に使用します。
- **Plugin パス (ComfyUI)** は、カスタムワークフローグラフ、または共有バンドル音楽機能の一部ではないプロバイダーが必要な場合に使用します。
ComfyUI 固有の動作をデバッグしている場合は、[ComfyUI](/ja-JP/providers/comfy) を参照してください。共有プロバイダーの動作をデバッグしている場合は、[Google (Gemini)](/ja-JP/providers/google) または [MiniMax](/ja-JP/providers/minimax) から始めてください。
## プロバイダー機能モード
共有音楽生成コントラクトは、明示的なモード宣言をサポートしています。
共有音楽生成契約は、明示的なモード宣言をサポートします。
- `generate` はプロンプトのみの生成用です。
- `edit` はリクエストに 1 つ以上の参照画像が含まれる場合に使用します。
- プロンプトのみの生成には `generate`。
- リクエストに 1 つ以上の参照画像が含まれる場合は `edit`。
新しいプロバイダー実装では、明示的なモードブロックを優先してください。
@ -261,11 +259,11 @@ capabilities: {
}
```
`maxInputImages`、`supportsLyrics`、`supportsFormat` などの従来のフラットフィールドは、編集サポートを示すには**十分ではありません**。プロバイダーは `generate` と `edit` を明示的に宣言し、ライブテスト、コントラクトテスト、共有 `music_generate` ツールがモードサポートを決定論的に検証できるようにする必要があります。
`maxInputImages`、`supportsLyrics`、`supportsFormat` などの従来のフラットフィールドだけでは、編集サポートを告知するには**不十分**です。ライブテスト、契約テスト、共有 `music_generate` ツールがモードサポートを決定的に検証できるように、プロバイダーは `generate` と `edit` を明示的に宣言する必要があります。
## ライブテスト
共有バンドルプロバイダー向けのオプトインライブカバレッジ:
共有バンドルプロバイダーのオプトインライブカバレッジ:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
@ -277,23 +275,23 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv
pnpm test:live:media music
```
このライブファイルは、不足しているプロバイダー環境変数を `~/.profile` から読み込み、既定では保存済み認証プロファイルよりもライブ/環境 API キーを優先し、プロバイダーが編集モードを有効にしている場合は `generate` と宣言済み `edit` の両方のカバレッジを実行します。現在のカバレッジ:
このライブファイルは不足しているプロバイダー環境変数を `~/.profile` から読み込み、デフォルトでは保存済み認証プロファイルよりも live/env API キーを優先し、プロバイダーが編集モードを有効にしている場合は `generate` と宣言済み `edit` の両方のカバレッジを実行します。現在のカバレッジ:
- `google`: `generate` と `edit`
- `minimax`: `generate` のみ
- `comfy`: 個別の Comfy ライブカバレッジであり、共有プロバイダースイープではありません
- `comfy`: 共有プロバイダースイープではなく、別個の Comfy ライブカバレッジ
バンドルされた ComfyUI 音楽パス向けのオプトインライブカバレッジ:
バンドルされた ComfyUI 音楽パスのオプトインライブカバレッジ:
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
Comfy live ファイルは、それらのセクションが設定されている場合、comfy の画像および動画ワークフローも扱います。
この Comfy ライブファイルは、これらのセクションが設定されている場合、Comfy の画像および動画ワークフローも対象にします。
## 関連
- [バックグラウンドタスク](/ja-JP/automation/tasks) — 切り離された `music_generate` 実行のタスク追跡
- [バックグラウンドタスク](/ja-JP/automation/tasks) — デタッチされた `music_generate` 実行のタスク追跡
- [ComfyUI](/ja-JP/providers/comfy)
- [設定リファレンス](/ja-JP/gateway/config-agents#agent-defaults) — `musicGenerationModel` 設定
- [Google (Gemini)](/ja-JP/providers/google)

417
docs/ja-JP/tools/plugin.md
View File

@ -1,28 +1,32 @@
---
read_when:
- Pluginのインストールまたは設定
- Plugin の検出と読み込みルールを理解する
- Codex/Claude 互換の Plugin バンドルを扱う
- Pluginの検出と読み込みルールを理解する
- Codex/Claude 互換 Plugin バンドルを扱う
sidebarTitle: Install and Configure
summary: OpenClaw Plugin をインストール、設定、管理する
summary: OpenClaw Pluginをインストール、設定、管理する
title: Plugin
x-i18n:
generated_at: "2026-05-03T21:39:55Z"
generated_at: "2026-05-05T01:50:36Z"
model: gpt-5.5
provider: openai
source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004
source_path: tools/plugin.md
workflow: 16
---
Pluginは、チャネル、モデルプロバイダー、エージェントハーネス、ツール、Skills、音声、リアルタイム文字起こし、リアルタイム音声、メディア理解、画像生成、動画生成、web fetch、web
searchなどの新しい機能でOpenClawを拡張します。一部のPluginは**コア**（OpenClawに同梱）で、その他は**外部**です。ほとんどの外部Pluginは
[ClawHub](/ja-JP/tools/clawhub)を通じて公開・検出されます。移行が完了するまで、直接インストールおよびOpenClaw所有のPluginパッケージの一時的なセットについては、Npmも引き続きサポートされます。
Plugin は OpenClaw に新しい機能を追加します: チャネル、モデルプロバイダー、
エージェントハーネス、ツール、Skills、音声、リアルタイム文字起こし、リアルタイム
音声、メディア理解、画像生成、動画生成、Web取得、Web
検索などです。一部の Plugin は **コア** (OpenClaw に同梱) で、その他は
**外部** です。ほとんどの外部 Plugin は
[ClawHub](/ja-JP/tools/clawhub) を通じて公開・検出されます。Npm は、直接インストールと、
その移行が完了するまでの一時的な OpenClaw 所有 Plugin パッケージ群のために、引き続きサポートされます。
## クイックスタート
コピー＆ペーストできるインストール、一覧表示、アンインストール、更新、公開の例については、
[Pluginを管理](/ja-JP/plugins/manage-plugins)を参照してください。
コピー&ペースト用のインストール、一覧表示、アンインストール、更新、公開の例については、
[Pluginを管理する](/ja-JP/plugins/manage-plugins) を参照してください。
<Steps>
<Step title="読み込まれているものを確認する">
@ -52,17 +56,22 @@ searchなどの新しい機能でOpenClawを拡張します。一部のPluginは
</Step>
<Step title="Gatewayを再起動する">
<Step title="Gateway を再起動する">
```bash
openclaw gateway restart
```
その後、設定ファイル内の`plugins.entries.\<id\>.config`で構成します。
その後、設定ファイル内の `plugins.entries.\<id\>.config` で設定します。
</Step>
<Step title="チャットネイティブな管理">
実行中のGatewayでは、所有者専用の`/plugins enable`と`/plugins disable`がGateway設定リローダーをトリガーします。GatewayはPluginランタイムサーフェスをプロセス内で再読み込みし、新しいエージェントターンは更新されたレジストリからツール一覧を再構築します。`/plugins install`はPluginソースコードを変更するため、現在のプロセスがすでにインポート済みのモジュールを安全に再読み込みできるかのように扱うのではなく、Gatewayは再起動を要求します。
<Step title="チャットネイティブ管理">
実行中の Gateway では、所有者専用の `/plugins enable` と `/plugins disable` が
Gateway 設定リローダーをトリガーします。Gateway は Plugin ランタイム
サーフェスをプロセス内でリロードし、新しいエージェントターンは更新された
レジストリからツール一覧を再構築します。`/plugins install` は Plugin ソースコードを変更するため、
Gateway は、現在のプロセスがすでにインポート済みのモジュールを安全にリロードできると見せかけるのではなく、
再起動を要求します。
</Step>
@ -74,12 +83,14 @@ searchなどの新しい機能でOpenClawを拡張します。一部のPluginは
openclaw <plugin-command> --help
```
登録済みのツール、サービス、gatewayメソッド、フック、またはPlugin所有のCLIコマンドを証明する必要がある場合は、`--runtime`を使用します。通常の`inspect`はコールドなマニフェスト/レジストリチェックであり、意図的にPluginランタイムのインポートを避けます。
登録済みのツール、サービス、Gateway
メソッド、フック、または Plugin 所有の CLI コマンドを証明する必要がある場合は `--runtime` を使用します。通常の `inspect` はコールドな
マニフェスト/レジストリチェックであり、意図的に Plugin ランタイムのインポートを避けます。
</Step>
</Steps>
チャットネイティブな制御を好む場合は、`commands.plugins: true`を有効にして次を使用します。
チャットネイティブな制御を好む場合は、`commands.plugins: true` を有効にして次を使用します。
```text
/plugin install clawhub:<package>
@ -87,44 +98,80 @@ searchなどの新しい機能でOpenClawを拡張します。一部のPluginは
/plugin enable <plugin-id>
```
インストールパスはCLIと同じリゾルバーを使用します。ローカルパス/アーカイブ、明示的な`clawhub:<pkg>`、明示的な`npm:<pkg>`、明示的な`git:<repo>`、またはnpm経由のベアパッケージ指定です。
インストールパスは CLI と同じリゾルバーを使用します: ローカルパス/アーカイブ、明示的な
`clawhub:<pkg>`、明示的な `npm:<pkg>`、明示的な `git:<repo>`、または npm 経由の裸のパッケージ
指定です。
設定が無効な場合、通常インストールはフェイルクローズし、`openclaw doctor --fix`を案内します。唯一の復旧例外は、`openclaw.install.allowInvalidConfigRecovery`にオプトインしたPlugin向けの、範囲の狭い同梱Plugin再インストールパスです。
Gateway起動中は、無効なPlugin設定は他の無効な設定と同様にフェイルクローズします。不正なPlugin設定を隔離するには`openclaw doctor --fix`を実行してください。これにより、そのPluginエントリを無効化し、無効な設定ペイロードを削除します。通常の設定バックアップにより以前の値は保持されます。
チャネル設定が検出できなくなったPluginを参照している一方で、同じ古いPlugin IDがPlugin設定またはインストール記録に残っている場合、Gateway起動時は警告をログに記録し、すべての他のチャネルをブロックするのではなく、そのチャネルをスキップします。
古いチャネル/Pluginエントリを削除するには`openclaw doctor --fix`を実行してください。古いPluginの証拠がない未知のチャネルキーは引き続き検証に失敗するため、入力ミスは見える状態に保たれます。
`plugins.enabled: false`が設定されている場合、古いPlugin参照は不活性として扱われます。Gateway起動時はPlugin検出/読み込み作業をスキップし、`openclaw doctor`は無効化されたPlugin設定を自動削除せず保持します。古いPlugin IDを削除したい場合は、doctorクリーンアップを実行する前にPluginを再有効化してください。
設定が無効な場合、通常インストールはフェイルクローズし、
`openclaw doctor --fix` を案内します。唯一の復旧例外は、
`openclaw.install.allowInvalidConfigRecovery` にオプトインした Plugin 向けの、狭い同梱 Plugin
再インストールパスです。
Gateway 起動時には、無効な Plugin 設定は他の無効な設定と同様にフェイルクローズします。
`openclaw doctor --fix` を実行すると、その Plugin エントリを無効化し、無効な設定ペイロードを削除することで、不正な Plugin 設定を隔離します。通常の
設定バックアップにより以前の値は保持されます。
チャネル設定が、もはや検出できない Plugin を参照している一方で、
同じ古い Plugin ID が Plugin 設定またはインストール記録に残っている場合、Gateway 起動は
警告をログに出し、他のすべてのチャネルをブロックするのではなくそのチャネルをスキップします。
`openclaw doctor --fix` を実行すると、古いチャネル/Plugin エントリが削除されます。古い Plugin の証拠がない不明な
チャネルキーは引き続き検証に失敗するため、入力ミスは見えるままになります。
`plugins.enabled: false` が設定されている場合、古い Plugin 参照は不活性として扱われます:
Gateway 起動は Plugin の検出/読み込み作業をスキップし、`openclaw doctor` は
無効化された Plugin 設定を自動削除せずに保持します。古い Plugin ID を削除したい場合は、
doctor クリーンアップを実行する前に Plugin を再度有効にしてください。
Plugin依存関係のインストールは、明示的なインストール/更新またはdoctor修復フローの間にのみ行われます。Gateway起動、設定再読み込み、ランタイム検査は、パッケージマネージャーを実行したり依存関係ツリーを修復したりしません。ローカルPluginは依存関係がすでにインストールされている必要があります。一方、npm、git、ClawHubのPluginはOpenClawの管理対象Pluginルート配下にインストールされます。npm依存関係はOpenClawの管理対象npmルート内で巻き上げられる場合があります。インストール/更新は信頼する前にその管理対象ルートをスキャンし、アンインストールはnpmを通じてnpm管理のパッケージを削除します。外部Pluginとカスタム読み込みパスは、引き続き`openclaw plugins install`を通じてインストールする必要があります。
ランタイムコードをインポートしたり依存関係を修復したりせず、表示可能な各Pluginの静的な`dependencyStatus`を確認するには、`openclaw plugins list --json`を使用してください。
インストール時ライフサイクルについては、[Plugin依存関係の解決](/ja-JP/plugins/dependency-resolution)を参照してください。
Plugin 依存関係のインストールは、明示的なインストール/更新または
doctor 修復フローの間にのみ行われます。Gateway 起動、設定リロード、ランタイム検査では
パッケージマネージャーを実行したり、依存関係ツリーを修復したりしません。ローカル Plugin は、依存関係がすでにインストールされている必要があります。一方 npm、git、ClawHub の Plugin は
OpenClaw の管理対象 Plugin ルート配下にインストールされます。npm 依存関係は
OpenClaw の管理対象 npm ルート内で hoist される場合があります。インストール/更新は信頼する前にその管理対象ルートをスキャンし、アンインストールは npm 管理パッケージを npm 経由で削除します。外部 Plugin
とカスタム読み込みパスは、引き続き `openclaw plugins install` を通じてインストールする必要があります。
ランタイムコードをインポートしたり依存関係を修復したりせず、表示可能な各
Plugin の静的な `dependencyStatus` を確認するには、`openclaw plugins list --json` を使用します。
インストール時ライフサイクルについては、
[Plugin依存関係の解決](/ja-JP/plugins/dependency-resolution) を参照してください。
npmインストールでは、`latest`やdist-tagのような可変セレクターはインストール前に解決され、その後OpenClawの管理対象npmルート内で正確に検証済みのバージョンへ固定されます。npmが完了した後、OpenClawはインストールされた`package-lock.json`エントリが、解決済みバージョンおよび完全性とまだ一致していることを検証します。npmが異なるパッケージメタデータを書き込んだ場合、異なるPlugin成果物を受け入れるのではなく、インストールは失敗し、管理対象パッケージはロールバックされます。
npm インストールでは、`latest` や dist-tag などの可変セレクターは
インストール前に解決され、その後 OpenClaw の
管理対象 npm ルート内で検証済みの正確なバージョンに固定されます。npm 完了後、OpenClaw はインストール済みの
`package-lock.json` エントリが、解決済みバージョンおよび integrity とまだ一致することを検証します。
npm が異なるパッケージメタデータを書き込んだ場合、異なる Plugin アーティファクトを受け入れるのではなく、
インストールは失敗し、管理対象パッケージはロールバックされます。
ソースチェックアウトはpnpmワークスペースです。同梱Pluginを変更するためにOpenClawをクローンした場合は、`pnpm install`を実行してください。OpenClawはその後、`extensions/<id>`から同梱Pluginを読み込むため、編集内容とパッケージローカル依存関係が直接使用されます。
通常のnpmルートインストールは、パッケージ化されたOpenClaw向けであり、ソースチェックアウト開発向けではありません。
ソースチェックアウトは pnpm ワークスペースです。同梱 Plugin を改造するために OpenClaw をクローンした場合は、
`pnpm install` を実行してください。OpenClaw はその後、
`extensions/<id>` から同梱 Plugin を読み込むため、編集内容とパッケージローカルの依存関係が直接使用されます。
通常の npm ルートインストールはパッケージ化された OpenClaw 向けであり、ソースチェックアウト
開発向けではありません。
## Pluginの種類
## Pluginタイプ
OpenClawは2つのPlugin形式を認識します。
OpenClaw は 2 つの Plugin 形式を認識します。
| 形式 | 仕組み | 例 |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + ランタイムモジュール。プロセス内で実行 | 公式Plugin、コミュニティnpmパッケージ |
| **Bundle** | Codex/Claude/Cursor互換レイアウト。OpenClaw機能にマッピングされる | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
| **Native** | `openclaw.plugin.json` + ランタイムモジュール。プロセス内で実行される | 公式 Plugin、コミュニティ npm パッケージ |
| **Bundle** | Codex/Claude/Cursor 互換レイアウト。OpenClaw 機能にマッピングされる | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
どちらも`openclaw plugins list`に表示されます。Bundleの詳細については、[Plugin Bundle](/ja-JP/plugins/bundles)を参照してください。
どちらも `openclaw plugins list` に表示されます。Bundle の詳細については [Plugin Bundles](/ja-JP/plugins/bundles) を参照してください。
ネイティブPluginを書く場合は、[Pluginの構築](/ja-JP/plugins/building-plugins)と
[Plugin SDK概要](/ja-JP/plugins/sdk-overview)から始めてください。
Native Plugin を書く場合は、[Pluginの構築](/ja-JP/plugins/building-plugins)
と [Plugin SDK概要](/ja-JP/plugins/sdk-overview) から始めてください。
## パッケージエントリポイント
ネイティブPluginのnpmパッケージは、`package.json`で`openclaw.extensions`を宣言する必要があります。
各エントリはパッケージディレクトリ内に留まり、読み取り可能なランタイムファイル、または`src/index.ts`から`dist/index.js`のように推論されたビルド済みJavaScriptピアを持つTypeScriptソースファイルへ解決される必要があります。
パッケージ化されたインストールには、そのJavaScriptランタイム出力を同梱する必要があります。TypeScriptソースのフォールバックは、ソースチェックアウトとローカル開発パス向けであり、OpenClawの管理対象Pluginルートにインストールされたnpmパッケージ向けではありません。
Native Plugin の npm パッケージは、`package.json` で `openclaw.extensions` を宣言する必要があります。
各エントリはパッケージディレクトリ内に留まり、読み取り可能な
ランタイムファイル、または `src/index.ts` から `dist/index.js` のように推論されるビルド済み JavaScript
ピアを持つ TypeScript ソースファイルへ解決される必要があります。
パッケージ化されたインストールには、その JavaScript ランタイム出力を同梱する必要があります。TypeScript
ソースフォールバックは、ソースチェックアウトとローカル開発パス向けであり、
OpenClaw の管理対象 Plugin ルートへインストールされる npm パッケージ向けではありません。
公開されたランタイムファイルがソースエントリと同じパスに存在しない場合は、`openclaw.runtimeExtensions`を使用します。存在する場合、`runtimeExtensions`はすべての`extensions`エントリに対して正確に1つのエントリを含む必要があります。一致しない一覧は、ソースパスへ静かにフォールバックするのではなく、インストールとPlugin検出を失敗させます。`openclaw.setupEntry`も公開する場合は、そのビルド済みJavaScriptピアに`openclaw.runtimeSetupEntry`を使用してください。宣言された場合、そのファイルは必須です。
公開されたランタイムファイルがソースエントリと同じパスに存在しない場合は、
`openclaw.runtimeExtensions` を使用します。存在する場合、`runtimeExtensions` には
すべての `extensions` エントリに対応するエントリが正確に 1 つずつ含まれている必要があります。一致しない一覧は、ソースパスへ黙ってフォールバックするのではなく、インストールと
Plugin 検出を失敗させます。`openclaw.setupEntry` も
公開する場合は、そのビルド済み JavaScript ピアに `openclaw.runtimeSetupEntry` を使用してください。宣言された場合、そのファイルは必須です。
```json
{
@ -136,34 +183,39 @@ OpenClawは2つのPlugin形式を認識します。
}
```
## 公式Plugin
## 公式 Plugin
### 移行中のOpenClaw所有npmパッケージ
### 移行中の OpenClaw 所有 npm パッケージ
ClawHubはほとんどのPluginの主要な配布パスです。現在のパッケージ化されたOpenClawリリースには、すでに多くの公式Pluginが同梱されているため、通常のセットアップではそれらを個別にnpmインストールする必要はありません。すべてのOpenClaw所有PluginがClawHubへ移行するまで、OpenClawは古い/カスタムインストールと直接npmワークフロー向けに、一部の`@openclaw/*` Pluginパッケージをnpmで引き続き提供します。
ClawHub はほとんどの Plugin の主要な配布パスです。現在のパッケージ化された
OpenClaw リリースには、すでに多くの公式 Plugin が同梱されているため、通常のセットアップではそれらを
個別に npm インストールする必要はありません。すべての OpenClaw 所有 Plugin が
ClawHub へ移行するまでは、OpenClaw は古い/カスタムインストールと直接 npm ワークフロー向けに、一部の `@openclaw/*` Plugin パッケージを npm で引き続き提供します。
npmが`@openclaw/*` Pluginパッケージを非推奨として報告する場合、そのパッケージバージョンは古い外部パッケージ系列のものです。新しいnpmパッケージが公開されるまでは、現在のOpenClawに同梱されたPluginまたはローカルチェックアウトを使用してください。
npm が `@openclaw/*` Plugin パッケージを非推奨として報告する場合、そのパッケージ
バージョンは古い外部パッケージ系列のものです。より新しい npm パッケージが公開されるまでは、
現在の OpenClaw に同梱された Plugin、またはローカルチェックアウトを使用してください。
| Plugin | パッケージ | ドキュメント |
| --------------- | -------------------------- | ---------------------------------------- |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/ja-JP/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/ja-JP/channels/discord) |
| Feishu | `@openclaw/feishu` | [Feishu](/ja-JP/channels/feishu) |
| Matrix | `@openclaw/matrix` | [Matrix](/ja-JP/channels/matrix) |
| Mattermost | `@openclaw/mattermost` | [Mattermost](/ja-JP/channels/mattermost) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/ja-JP/channels/msteams) |
| Plugin | パッケージ | ドキュメント |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/ja-JP/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/ja-JP/channels/discord) |
| Feishu | `@openclaw/feishu` | [Feishu](/ja-JP/channels/feishu) |
| Matrix | `@openclaw/matrix` | [Matrix](/ja-JP/channels/matrix) |
| Mattermost | `@openclaw/mattermost` | [Mattermost](/ja-JP/channels/mattermost) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/ja-JP/channels/msteams) |
| Nextcloud Talk | `@openclaw/nextcloud-talk` | [Nextcloud Talk](/ja-JP/channels/nextcloud-talk) |
| Nostr | `@openclaw/nostr` | [Nostr](/ja-JP/channels/nostr) |
| Synology Chat | `@openclaw/synology-chat` | [Synology Chat](/ja-JP/channels/synology-chat) |
| Tlon | `@openclaw/tlon` | [Tlon](/ja-JP/channels/tlon) |
| WhatsApp | `@openclaw/whatsapp` | [WhatsApp](/ja-JP/channels/whatsapp) |
| Zalo | `@openclaw/zalo` | [Zalo](/ja-JP/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/ja-JP/plugins/zalouser) |
| Nostr | `@openclaw/nostr` | [Nostr](/ja-JP/channels/nostr) |
| Synology Chat | `@openclaw/synology-chat` | [Synology Chat](/ja-JP/channels/synology-chat) |
| Tlon | `@openclaw/tlon` | [Tlon](/ja-JP/channels/tlon) |
| WhatsApp | `@openclaw/whatsapp` | [WhatsApp](/ja-JP/channels/whatsapp) |
| Zalo | `@openclaw/zalo` | [Zalo](/ja-JP/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/ja-JP/plugins/zalouser) |
### コア（OpenClawに同梱）
### コア (OpenClaw に同梱)
<AccordionGroup>
<Accordion title="モデルプロバイダー（デフォルトで有効）">
<Accordion title="モデルプロバイダー (デフォルトで有効)">
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
@ -171,26 +223,27 @@ npmが`@openclaw/*` Pluginパッケージを非推奨として報告する場合
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
</Accordion>
<Accordion title="メモリPlugin">
- `memory-core` — 同梱のメモリ検索（デフォルトは`plugins.slots.memory`経由）
- `memory-lancedb` — LanceDBバックエンドの自動想起/キャプチャ付き長期メモリ（`plugins.slots.memory = "memory-lancedb"`を設定）
<Accordion title="メモリ Plugin">
- `memory-core` — 同梱メモリ検索 (デフォルトは `plugins.slots.memory` 経由)
- `memory-lancedb` — 自動リコール/キャプチャを備えた LanceDB ベースの長期記憶 (`plugins.slots.memory = "memory-lancedb"` を設定)
OpenAI互換の埋め込み設定、Ollamaの例、想起制限、トラブルシューティングについては、[Memory LanceDB](/ja-JP/plugins/memory-lancedb)を参照してください。
OpenAI 互換の埋め込みセットアップ、Ollama の例、リコール制限、トラブルシューティングについては
[Memory LanceDB](/ja-JP/plugins/memory-lancedb) を参照してください。
</Accordion>
<Accordion title="音声プロバイダー（デフォルトで有効）">
<Accordion title="音声プロバイダー (デフォルトで有効)">
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="その他">
- `browser` — ブラウザツール、`openclaw browser` CLI、`browser.request` gatewayメソッド、ブラウザランタイム、デフォルトのブラウザ制御サービス向けの同梱ブラウザPlugin（デフォルトで有効。置き換える前に無効化してください）
- `copilot-proxy` — VS Code Copilot Proxyブリッジ（デフォルトで無効）
- `browser` — ブラウザツール、`openclaw browser` CLI、`browser.request` gateway メソッド、ブラウザランタイム、デフォルトのブラウザ制御サービス向けの同梱ブラウザ Plugin (デフォルトで有効。置き換える前に無効化してください)
- `copilot-proxy` — VS Code Copilot Proxy ブリッジ (デフォルトで無効)
</Accordion>
</AccordionGroup>
サードパーティPluginを探していますか？[コミュニティPlugin](/ja-JP/plugins/community)を参照してください。
サードパーティ Plugin を探していますか？ [Community Plugins](/ja-JP/plugins/community) を参照してください。
## 設定
@ -208,100 +261,103 @@ npmが`@openclaw/*` Pluginパッケージを非推奨として報告する場合
}
```
| フィールド | 説明 |
| ---------------- | --------------------------------------------------------- |
| `enabled` | マスタートグル（デフォルト: `true`） |
| `allow` | Plugin 許可リスト（任意） |
| `deny` | Plugin 拒否リスト（任意、拒否が優先） |
| `load.paths` | 追加の plugin ファイル/ディレクトリ |
| `slots` | 排他的なスロットセレクター（例: `memory`, `contextEngine`） |
| `entries.\<id\>` | Plugin ごとのトグル + 設定 |
| フィールド | 説明 |
| ------------------ | --------------------------------------------------------- |
| `enabled` | マスタートグル（デフォルト: `true`） |
| `allow` | Plugin 許可リスト（任意） |
| `bundledDiscovery` | バンドル Plugin の検出モード（デフォルトは `allowlist`） |
| `deny` | Plugin 拒否リスト（任意。deny が優先） |
| `load.paths` | 追加の Plugin ファイル/ディレクトリ |
| `slots` | 排他的なスロットセレクタ（例: `memory`, `contextEngine`） |
| `entries.\<id\>` | Plugin ごとのトグル + 設定 |
`plugins.allow` は排他的です。空でない場合、`tools.allow` に `"*"` または特定の plugin 所有のツール名が含まれていても、リストされた plugin だけが読み込まれるかツールを公開できます。ツール許可リストが plugin ツールを参照する場合は、所有する plugin id を `plugins.allow` に追加するか、`plugins.allow` を削除してください。`openclaw doctor` はこの形について警告します。
`plugins.allow` は排他的です。空でない場合、`tools.allow` に `"*"` または特定の Plugin 所有ツール名が含まれていても、一覧にある Plugin だけが読み込まれるか、ツールを公開できます。ツール許可リストが Plugin ツールを参照している場合は、所有元の Plugin id を `plugins.allow` に追加するか、`plugins.allow` を削除してください。この形については `openclaw doctor` が警告します。
`/plugins enable` または `/plugins disable` を通じて行われた設定変更は、プロセス内の Gateway plugin 再読み込みをトリガーします。新しいエージェントターンは、更新された plugin レジストリからツールリストを再構築します。インストール、更新、アンインストールなどのソースを変更する操作では、すでにインポート済みの plugin モジュールをその場で安全に置き換えられないため、引き続き Gateway プロセスが再起動されます。
`plugins.bundledDiscovery` は新しい設定ではデフォルトで `"allowlist"` になるため、制限的な `plugins.allow` インベントリは、実行時の Web 検索プロバイダー検出を含め、省略されたバンドルプロバイダー Plugin もブロックします。doctor は、古い制限的な許可リスト設定に移行時に `"compat"` を付与し、オペレーターがより厳密なモードへ明示的に切り替えるまで、アップグレード後も従来のバンドルプロバイダー動作を維持します。空の `plugins.allow` は引き続き未設定/オープンとして扱われます。
`openclaw plugins list` はローカルの plugin レジストリ/設定のスナップショットです。そこで `enabled` な plugin とは、永続化されたレジストリと現在の設定がその plugin の参加を許可していることを意味します。すでに実行中のリモート Gateway が同じ plugin コードへ再読み込みまたは再起動済みであることを証明するものではありません。ラッパープロセスを使う VPS/コンテナ構成では、再起動または再読み込みをトリガーする書き込みを実際の `openclaw gateway run` プロセスへ送るか、再読み込みが失敗を報告する場合は実行中の Gateway に対して `openclaw gateway restart` を使用してください。
`/plugins enable` または `/plugins disable` を通じて行われた設定変更は、プロセス内の Gateway Plugin リロードをトリガーします。新しいエージェントターンでは、更新された Plugin レジストリからツールリストが再構築されます。install、update、uninstall などのソース変更操作では、すでにインポート済みの Plugin モジュールをその場で安全に置き換えられないため、引き続き Gateway プロセスを再起動します。
`openclaw plugins list` はローカルの Plugin レジストリ/設定スナップショットです。そこにある `enabled` の Plugin は、永続化されたレジストリと現在の設定が、その Plugin の参加を許可していることを意味します。すでに実行中のリモート Gateway が同じ Plugin コードでリロードまたは再起動済みであることを証明するものではありません。ラッパープロセスを持つ VPS/コンテナ構成では、実際の `openclaw gateway run` プロセスに対して再起動またはリロードをトリガーする書き込みを送るか、リロードで失敗が報告された場合は実行中の Gateway に対して `openclaw gateway restart` を使用してください。
<Accordion title="Plugin の状態: 無効、欠落、無効な設定">
- **無効**: plugin は存在しますが、有効化ルールによってオフになっています。設定は保持されます。
- **欠落**: 設定が参照する plugin id を検出で見つけられませんでした。
- **無効な設定**: plugin は存在しますが、その設定が宣言されたスキーマと一致しません。Gateway 起動時はその plugin だけをスキップします。`openclaw doctor --fix` は、その無効なエントリを無効化し、設定ペイロードを削除することで隔離できます。
- **無効**: Plugin は存在しますが、有効化ルールによってオフにされています。設定は保持されます。
- **欠落**: 設定が、検出で見つからなかった Plugin id を参照しています。
- **無効な設定**: Plugin は存在しますが、その設定が宣言されたスキーマと一致しません。Gateway 起動時にはその Plugin だけがスキップされます。`openclaw doctor --fix` は、その無効なエントリを無効化し、設定ペイロードを削除することで隔離できます。
</Accordion>
## 検出と優先順位
OpenClaw は次の順序で plugin をスキャンします（最初の一致が優先）:
OpenClaw は次の順序で Plugin をスキャンします（最初の一致が優先されます）。
<Steps>
<Step title="設定パス">
`plugins.load.paths` — 明示的なファイルまたはディレクトリパス。OpenClaw 自身のパッケージ済みバンドル plugin ディレクトリを指し戻すパスは無視されます。そうした古い別名を削除するには `openclaw doctor --fix` を実行してください。
`plugins.load.paths` — 明示的なファイルまたはディレクトリパス。OpenClaw 自身のパッケージ化されたバンドル Plugin ディレクトリを指すパスは無視されます。古いエイリアスを削除するには `openclaw doctor --fix` を実行してください。
</Step>
<Step title="ワークスペース plugin">
<Step title="ワークスペース Plugin">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` と `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`。
</Step>
<Step title="グローバル plugin">
<Step title="グローバル Plugin">
`~/.openclaw/<plugin-root>/*.ts` と `~/.openclaw/<plugin-root>/*/index.ts`。
</Step>
<Step title="バンドル plugin">
OpenClaw に同梱されています。多くはデフォルトで有効です（モデルプロバイダー、音声）。他のものは明示的な有効化が必要です。
<Step title="バンドル Plugin">
OpenClaw に同梱されています。多くはデフォルトで有効です（モデルプロバイダー、音声）。それ以外は明示的な有効化が必要です。
</Step>
</Steps>
パッケージインストールと Docker イメージでは、通常、コンパイル済みの `dist/extensions` ツリーからバンドル plugin を解決します。たとえば `/app/extensions/synology-chat` のように、バンドル plugin のソースディレクトリが対応するパッケージ済みソースパス上に bind mount されている場合、OpenClaw はそのマウントされたソースディレクトリをバンドルソースオーバーレイとして扱い、パッケージ済みの `/app/dist/extensions/synology-chat` バンドルより先に検出します。これにより、すべてのバンドル plugin を TypeScript ソースへ戻さなくても、メンテナーのコンテナループが動作し続けます。ソースオーバーレイマウントが存在する場合でもパッケージ済み dist バンドルを強制するには、`OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` を設定してください。
パッケージインストールと Docker イメージでは、通常、コンパイル済みの `dist/extensions` ツリーからバンドル Plugin を解決します。バンドル Plugin のソースディレクトリが一致するパッケージ化済みソースパス上にバインドマウントされている場合、たとえば `/app/extensions/synology-chat` の場合、OpenClaw はそのマウントされたソースディレクトリをバンドルソースオーバーレイとして扱い、パッケージ化済みの `/app/dist/extensions/synology-chat` バンドルより先に検出します。これにより、すべてのバンドル Plugin を TypeScript ソースへ戻さなくても、メンテナーのコンテナループが動作し続けます。ソースオーバーレイマウントが存在する場合でも、パッケージ化済み dist バンドルを強制するには `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` を設定してください。
### 有効化ルール
- `plugins.enabled: false` はすべての plugin を無効化し、plugin の検出/読み込み作業をスキップします
- `plugins.enabled: false` はすべての Plugin を無効にし、Plugin の検出/読み込み作業をスキップします
- `plugins.deny` は常に allow より優先されます
- `plugins.entries.\<id\>.enabled: false` はその plugin を無効化します
- ワークスペース由来の plugin は**デフォルトで無効**です（明示的な有効化が必要）
- バンドル plugin は、上書きされない限り組み込みのデフォルトオンセットに従います
- 排他的スロットは、そのスロットに選択された plugin を強制的に有効化できます
- 一部のオプトイン型バンドル plugin は、設定がプロバイダーモデル参照、チャネル設定、ハーネスランタイムなどの plugin 所有サーフェスを指定している場合に自動で有効化されます
- `plugins.enabled: false` が有効な間、古い plugin 設定は保持されます。古い id を削除したい場合は、doctor クリーンアップを実行する前に plugin を再度有効化してください
- OpenAI 系 Codex ルートは別々の plugin 境界を保ちます: `openai-codex/*` は OpenAI plugin に属し、バンドルされた Codex app-server plugin は `agentRuntime.id: "codex"` または従来の `codex/*` モデル参照によって選択されます
- `plugins.entries.\<id\>.enabled: false` はその Plugin を無効にします
- ワークスペース由来の Plugin は**デフォルトで無効**です（明示的に有効にする必要があります）
- バンドル Plugin は、上書きされない限り組み込みのデフォルトオン集合に従います
- 排他的スロットは、そのスロットで選択された Plugin を強制的に有効化できます
- 一部のバンドルオプトイン Plugin は、設定がプロバイダーモデル参照、チャネル設定、ハーネスランタイムなどの Plugin 所有サーフェスを名指しすると、自動的に有効になります
- `plugins.enabled: false` が有効な間は古い Plugin 設定が保持されます。古い id を削除したい場合は、doctor cleanup を実行する前に Plugin を再度有効にしてください
- OpenAI 系の Codex ルートは個別の Plugin 境界を維持します。`openai-codex/*` は OpenAI Plugin に属し、バンドルされた Codex app-server Plugin は `agentRuntime.id: "codex"` または従来の `codex/*` モデル参照によって選択されます
## ランタイムフックのトラブルシューティング
plugin が `plugins list` に表示されるのに、ライブチャットトラフィックで `register(api)` の副作用やフックが実行されない場合は、まず次を確認してください:
Plugin が `plugins list` に表示されているのに、ライブチャットトラフィックで `register(api)` の副作用やフックが実行されない場合は、まず次を確認してください。
- `openclaw gateway status --deep --require-rpc` を実行し、アクティブな Gateway URL、プロファイル、設定パス、プロセスが編集対象のものであることを確認します。
- plugin のインストール/設定/コード変更後にライブ Gateway を再起動します。ラッパーコンテナでは、PID 1 はスーパーバイザーだけの場合があります。子の `openclaw gateway run` プロセスを再起動するかシグナルを送ってください。
- `openclaw gateway status --deep --require-rpc` を実行し、アクティブな Gateway URL、プロファイル、設定パス、プロセスが編集対象のものと一致していることを確認します。
- Plugin のインストール/設定/コード変更後にライブ Gateway を再起動します。ラッパーコンテナでは、PID 1 が単なるスーパーバイザーである場合があります。子の `openclaw gateway run` プロセスを再起動するかシグナルを送ってください。
- フック登録と診断を確認するには `openclaw plugins inspect <id> --runtime --json` を使用します。`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end` などの非バンドル会話フックには `plugins.entries.<id>.hooks.allowConversationAccess=true` が必要です。
- モデル切り替えには `before_model_resolve` を推奨します。これはエージェントターンのモデル解決前に実行されます。`llm_output` はモデル試行がアシスタント出力を生成した後にのみ実行されます。
- 有効なセッションモデルの証拠には `openclaw sessions` または Gateway セッション/ステータスサーフェスを使用し、プロバイダーペイロードをデバッグする場合は `--raw-stream --raw-stream-path <path>` 付きで Gateway を起動します。
- モデル切り替えには `before_model_resolve` を優先してください。これはエージェントターンのモデル解決前に実行されます。`llm_output` は、モデル試行がアシスタント出力を生成した後にのみ実行されます。
- 有効なセッションモデルの証拠には、`openclaw sessions` または Gateway のセッション/ステータスサーフェスを使用し、プロバイダーペイロードをデバッグする場合は `--raw-stream --raw-stream-path <path>` を付けて Gateway を起動します。
### 遅い plugin ツールセットアップ
### 遅い Plugin ツールセットアップ
エージェントターンがツールの準備中に停止しているように見える場合は、トレースログを有効にして、plugin ツールファクトリのタイミング行を確認してください:
エージェントターンがツール準備中に停止しているように見える場合は、トレースログを有効にして、Plugin ツールファクトリのタイミング行を確認してください。
```bash
openclaw config set logging.level trace
openclaw logs --follow
```
次を探してください:
次を探してください。
```text
[trace:plugin-tools] factory timings ...
```
概要には、合計ファクトリ時間と、最も遅い plugin ツールファクトリが一覧表示されます。plugin id、宣言されたツール名、結果の形、ツールが任意かどうかも含まれます。単一ファクトリに少なくとも 1 秒かかる場合、または plugin ツールファクトリ準備の合計に少なくとも 5 秒かかる場合、遅い行は警告に昇格されます。
サマリーには、合計ファクトリ時間と最も遅い Plugin ツールファクトリが一覧表示されます。これには Plugin id、宣言されたツール名、結果の形、ツールが任意かどうかが含まれます。単一のファクトリに少なくとも 1 秒かかる場合、または Plugin ツールファクトリ準備全体に少なくとも 5 秒かかる場合、遅い行は警告に昇格されます。
OpenClaw は、同じ有効なリクエストコンテキストで繰り返し解決する場合に、成功した plugin ツールファクトリ結果をキャッシュします。キャッシュキーには、有効なランタイム設定、ワークスペース、エージェント/セッション id、サンドボックスポリシー、ブラウザー設定、配信コンテキスト、リクエスター ID、所有状態が含まれるため、それらの信頼済みフィールドに依存するファクトリはコンテキストが変わると再実行されます。
OpenClaw は、同じ有効なリクエストコンテキストで解決が繰り返される場合に、成功した Plugin ツールファクトリ結果をキャッシュします。キャッシュキーには、有効なランタイム設定、ワークスペース、エージェント/セッション id、サンドボックスポリシー、ブラウザー設定、配信コンテキスト、リクエスター ID、所有状態が含まれるため、それらの信頼済みフィールドに依存するファクトリは、コンテキストが変わると再実行されます。
1 つの plugin がタイミングの大半を占める場合は、そのランタイム登録を調べます:
1 つの Plugin がタイミングの大部分を占めている場合は、そのランタイム登録を調べてください。
```bash
openclaw plugins inspect <plugin-id> --runtime --json
```
その後、その plugin を更新、再インストール、または無効化してください。Plugin 作者は、高コストな依存関係の読み込みをツールファクトリ内ではなく、ツール実行パスの背後に移すべきです。
その後、その Plugin を更新、再インストール、または無効化します。Plugin 作者は、高コストな依存関係の読み込みをツールファクトリ内で行うのではなく、ツール実行パスの背後へ移すべきです。
### チャネルまたはツール所有権の重複
@ -311,24 +367,24 @@ openclaw plugins inspect <plugin-id> --runtime --json
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
これは、複数の有効な plugin が同じチャネル、セットアップフロー、またはツール名を所有しようとしていることを意味します。最も一般的な原因は、同じチャネル id を提供するようになったバンドル plugin の横に、外部チャネル plugin がインストールされていることです。
これらは、複数の有効な Plugin が同じチャネル、セットアップフロー、またはツール名を所有しようとしていることを意味します。最も一般的な原因は、同じチャネル id を提供するようになったバンドル Plugin の横に、外部チャネル Plugin がインストールされていることです。
デバッグ手順:
- 有効なすべての plugin と由来を確認するには、`openclaw plugins list --enabled --verbose` を実行します。
- 疑わしい各 plugin に対して `openclaw plugins inspect <id> --runtime --json` を実行し、`channels`、`channelConfigs`、`tools`、診断を比較します。
- plugin パッケージのインストールまたは削除後は、永続化されたメタデータが現在のインストールを反映するように `openclaw plugins registry --refresh` を実行します。
- インストール、レジストリ、設定の変更後は Gateway を再起動します。
- `openclaw plugins list --enabled --verbose` を実行して、有効なすべての Plugin と出所を確認します。
- 疑わしい各 Plugin について `openclaw plugins inspect <id> --runtime --json` を実行し、`channels`、`channelConfigs`、`tools`、診断を比較します。
- Plugin パッケージをインストールまたは削除した後は、永続化されたメタデータが現在のインストールを反映するように `openclaw plugins registry --refresh` を実行します。
- インストール、レジストリ、または設定の変更後に Gateway を再起動します。
修正オプション:
- 1 つの plugin が同じチャネル id について別の plugin を意図的に置き換える場合、推奨される plugin は低優先度の plugin id とともに `channelConfigs.<channel-id>.preferOver` を宣言するべきです。[/plugins/manifest#replacing-another-channel-plugin](/ja-JP/plugins/manifest#replacing-another-channel-plugin) を参照してください。
- 重複が意図しないものの場合は、`plugins.entries.<plugin-id>.enabled: false` で一方を無効化するか、古い plugin インストールを削除します。
- 両方の plugin を明示的に有効化した場合、OpenClaw はそのリクエストを保持し、競合を報告します。チャネルの所有者を 1 つ選ぶか、plugin 所有のツール名を変更してランタイムサーフェスを曖昧でないものにしてください。
- 1 つの Plugin が同じチャネル id について別の Plugin を意図的に置き換える場合、優先する Plugin は `channelConfigs.<channel-id>.preferOver` に低優先度の Plugin id を宣言する必要があります。[/plugins/manifest#replacing-another-channel-plugin](/ja-JP/plugins/manifest#replacing-another-channel-plugin) を参照してください。
- 重複が意図しないものの場合は、`plugins.entries.<plugin-id>.enabled: false` で一方を無効にするか、古い Plugin インストールを削除します。
- 両方の Plugin を明示的に有効にした場合、OpenClaw はその要求を保持し、競合を報告します。ランタイムサーフェスが曖昧にならないように、チャネルの所有者を 1 つ選ぶか、Plugin 所有ツールの名前を変更してください。
## Plugin スロット（排他的カテゴリ）
一部のカテゴリは排他的です（同時にアクティブにできるのは 1 つのみ）:
一部のカテゴリは排他的です（一度にアクティブにできるのは 1 つだけ）。
```json5
{
@ -341,9 +397,9 @@ openclaw plugins inspect <plugin-id> --runtime --json
}
```
| スロット | 制御対象 | デフォルト |
| --------------- | --------------------- | ------------------- |
| `memory` | Active Memory plugin | `memory-core` |
| スロット | 制御するもの | デフォルト |
| --------------- | ------------------------ | ------------------- |
| `memory` | アクティブなメモリ Plugin | `memory-core` |
| `contextEngine` | アクティブなコンテキストエンジン | `legacy`（組み込み） |
## CLI リファレンス
@ -394,46 +450,35 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
バンドル Plugin は OpenClaw とともに提供されます。多くはデフォルトで有効です（たとえば
バンドルされたモデルプロバイダー、バンドルされた音声プロバイダー、バンドルされたブラウザー
Plugin）。その他のバンドル Plugin は、引き続き `openclaw plugins enable <id>` が必要です。
バンドルされたPluginはOpenClawに同梱されています。多くはデフォルトで有効化されています（たとえば、バンドルされたモデルプロバイダー、バンドルされた音声プロバイダー、バンドルされたブラウザーPlugin）。他のバンドル済みPluginでは、引き続き`openclaw plugins enable <id>`が必要です。
`--force` は、既存のインストール済み Plugin またはフックパックをその場で上書きします。追跡対象の npm
Plugin の通常のアップグレードには
`openclaw plugins update <id-or-npm-spec>` を使用してください。これは `--link` とは併用できません。`--link` は、管理対象のインストール先へコピーする代わりにソースパスを再利用します。
`--force`は、既存のインストール済みPluginまたはフックパックをその場で上書きします。追跡対象のnpm Pluginを通常アップグレードする場合は、`openclaw plugins update <id-or-npm-spec>`を使用します。管理対象のインストール先へコピーする代わりにソースパスを再利用する`--link`とは併用できません。
`plugins.allow` がすでに設定されている場合、`openclaw plugins install` は、インストールした
Plugin ID を有効化前にその許可リストへ追加します。同じ Plugin ID が
`plugins.deny` に存在する場合、インストールはその古い拒否エントリを削除するため、明示的にインストールした
Plugin は再起動後すぐにロード可能になります。
`plugins.allow`がすでに設定されている場合、`openclaw plugins install`はインストールしたPlugin IDを有効化前にその許可リストへ追加します。同じPlugin IDが`plugins.deny`に存在する場合、installはその古い拒否エントリを削除し、明示的にインストールしたPluginが再起動後すぐに読み込めるようにします。
OpenClaw は、Plugin インベントリ、コントリビューション所有権、起動計画のコールドリードモデルとして、永続化されたローカル Plugin レジストリを保持します。インストール、更新、アンインストール、有効化、無効化の各フローは、Plugin 状態を変更した後にそのレジストリを更新します。同じ `plugins/installs.json` ファイルは、トップレベルの `installRecords` に永続的なインストールメタデータを保持し、`plugins` に再構築可能なマニフェストメタデータを保持します。レジストリが存在しない、古い、または無効な場合、`openclaw plugins registry
--refresh` は、Plugin ランタイムモジュールをロードせずに、インストール記録、構成ポリシー、マニフェスト/パッケージメタデータからマニフェストビューを再構築します。
`openclaw plugins update <id-or-npm-spec>` は追跡対象のインストールに適用されます。dist-tag または正確なバージョンを含む npm パッケージ指定を渡すと、パッケージ名は追跡対象の Plugin レコードへ解決され、今後の更新用に新しい指定が記録されます。バージョンなしでパッケージ名を渡すと、正確にピン留めされたインストールは、レジストリのデフォルトリリースラインに戻ります。インストール済み npm Plugin が、解決済みバージョンおよび記録済みアーティファクト ID とすでに一致している場合、OpenClaw はダウンロード、再インストール、構成の書き換えを行わずに更新をスキップします。
`openclaw update` がベータチャネルで実行されると、デフォルトラインの npm および ClawHub
Plugin レコードは最初に `@beta` を試し、Plugin のベータリリースが存在しない場合は default/latest にフォールバックします。正確なバージョンと明示的なタグはピン留めされたままです。
OpenClawは、Pluginインベントリ、コントリビューション所有権、起動計画のコールドリードモデルとして、永続化されたローカルPluginレジストリを保持します。install、update、uninstall、enable、disableの各フローは、Plugin状態の変更後にそのレジストリを更新します。同じ`plugins/installs.json`ファイルは、トップレベルの`installRecords`に永続的なインストールメタデータを保持し、`plugins`に再構築可能なマニフェストメタデータを保持します。レジストリが存在しない、古い、または無効な場合、`openclaw plugins registry --refresh`は、Pluginランタイムモジュールを読み込まずに、インストールレコード、設定ポリシー、マニフェスト/パッケージメタデータからマニフェストビューを再構築します。
`openclaw plugins update <id-or-npm-spec>`は追跡対象のインストールに適用されます。dist-tagまたは厳密なバージョンを含むnpmパッケージ仕様を渡すと、パッケージ名を追跡対象のPluginレコードへ解決し直し、今後の更新用に新しい仕様を記録します。バージョンなしでパッケージ名を渡すと、厳密にピン留めされたインストールはレジストリのデフォルトリリースラインへ戻ります。インストール済みのnpm Pluginが、解決されたバージョンおよび記録されたアーティファクトIDとすでに一致している場合、OpenClawはダウンロード、再インストール、設定の書き換えを行わずに更新をスキップします。
`openclaw update`がベータチャネルで実行される場合、デフォルトラインのnpmおよびClawHub Pluginレコードは最初に`@beta`を試し、Pluginのベータリリースが存在しない場合はdefault/latestへフォールバックします。厳密なバージョンと明示的なタグはピン留めされたままです。
`--pin` は npm 専用です。`--marketplace` とは併用できません。マーケットプレイスからのインストールは、npm 指定ではなくマーケットプレイスソースメタデータを永続化するためです。
`--pin`はnpm専用です。marketplaceインストールはnpm仕様ではなくmarketplaceソースメタデータを永続化するため、`--marketplace`とは併用できません。
`--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーによる誤検知に対する非常用の上書きです。これにより、組み込みの `critical` 検出を超えて Plugin のインストールと Plugin の更新を続行できますが、Plugin の `before_install` ポリシーブロックやスキャン失敗によるブロックは引き続き回避しません。インストールスキャンは、パッケージ化されたテストモックのブロックを避けるため、`tests/`、`__tests__/`、`*.test.*`、`*.spec.*` などの一般的なテストファイルとディレクトリを無視します。ただし、宣言済みの Plugin ランタイムエントリポイントは、それらの名前を使用していても引き続きスキャンされます。
`--dangerously-force-unsafe-install`は、組み込みの危険コードスキャナーによる誤検知に対する緊急用オーバーライドです。組み込みの`critical`検出があってもPluginのインストールとPlugin更新を続行できますが、Pluginの`before_install`ポリシーブロックやスキャン失敗によるブロックは迂回しません。インストールスキャンは、パッケージ化されたテストモックをブロックしないように、`tests/`、`__tests__/`、`*.test.*`、`*.spec.*`などの一般的なテストファイルとディレクトリを無視します。ただし、宣言されたPluginランタイムエントリポイントは、それらの名前のいずれかを使用している場合でも引き続きスキャンされます。
この CLI フラグは、Plugin のインストール/更新フローにのみ適用されます。Gateway ベースの Skills 依存関係インストールでは、代わりに対応する `dangerouslyForceUnsafeInstall` リクエスト上書きを使用します。一方、`openclaw skills install` は別個の ClawHub Skills ダウンロード/インストールフローのままです。
このCLIフラグはPluginのinstall/updateフローにのみ適用されます。Gateway経由のskill依存関係インストールでは、代わりに対応する`dangerouslyForceUnsafeInstall`リクエストオーバーライドを使用します。一方、`openclaw skills install`は別個のClawHub skillダウンロード/インストールフローのままです。
ClawHub で公開した Plugin がスキャンによって非表示またはブロックされた場合は、ClawHub ダッシュボードを開くか、`clawhub package rescan <name>` を実行して ClawHub に再チェックを依頼してください。`--dangerously-force-unsafe-install` は自分のマシン上のインストールにのみ影響します。ClawHub に Plugin の再スキャンを依頼したり、ブロックされたリリースを公開したりするものではありません。
ClawHubで公開したPluginがスキャンによって非表示またはブロックされている場合は、ClawHubダッシュボードを開くか、`clawhub package rescan <name>`を実行してClawHubに再チェックを依頼します。`--dangerously-force-unsafe-install`は自分のマシン上のインストールにのみ影響します。ClawHubにPluginの再スキャンを依頼したり、ブロックされたリリースを公開したりするものではありません。
互換バンドルは、同じ Plugin の一覧表示/検査/有効化/無効化フローに参加します。現在のランタイムサポートには、バンドル Skills、Claude コマンド Skills、Claude `settings.json` のデフォルト、Claude `.lsp.json` とマニフェストで宣言された `lspServers` のデフォルト、Cursor コマンド Skills、互換性のある Codex フックディレクトリが含まれます。
互換バンドルは、同じPluginのlist/inspect/enable/disableフローに参加します。現在のランタイムサポートには、バンドルSkills、ClaudeコマンドSkills、Claude `settings.json`デフォルト、Claude `.lsp.json`およびマニフェスト宣言の`lspServers`デフォルト、CursorコマンドSkills、互換性のあるCodexフックディレクトリが含まれます。
`openclaw plugins inspect <id>` は、検出されたバンドル機能に加え、バンドルベース Plugin のサポート済みまたは未サポートの MCP および LSP サーバーエントリも報告します。
`openclaw plugins inspect <id>`は、検出されたバンドル機能に加えて、バンドルに基づくPluginのサポート対象または非サポートのMCPおよびLSPサーバーエントリも報告します。
マーケットプレイスソースには、`~/.claude/plugins/known_marketplaces.json` にある Claude の既知マーケットプレイス名、ローカルマーケットプレイスルートまたは `marketplace.json` パス、`owner/repo` のような GitHub 省略表記、GitHub リポジトリ URL、または git URL を指定できます。リモートマーケットプレイスでは、Plugin エントリはクローンされたマーケットプレイスリポジトリ内にとどまり、相対パスソースのみを使用する必要があります。
Marketplaceソースには、`~/.claude/plugins/known_marketplaces.json`にあるClaudeの既知marketplace名、ローカルmarketplaceルートまたは`marketplace.json`パス、`owner/repo`のようなGitHub短縮表記、GitHubリポジトリURL、またはgit URLを指定できます。リモートmarketplaceでは、Pluginエントリはクローンされたmarketplaceリポジトリ内に留まり、相対パスソースのみを使用する必要があります。
詳細は [`openclaw plugins` CLI リファレンス](/ja-JP/cli/plugins) を参照してください。
詳細は[`openclaw plugins` CLIリファレンス](/ja-JP/cli/plugins)を参照してください。
## Plugin API の概要
## Plugin APIの概要
ネイティブ Plugin は、`register(api)` を公開するエントリオブジェクトをエクスポートします。古い
Plugin は引き続きレガシーエイリアスとして `activate(api)` を使用できますが、新しい Plugin は
`register` を使用する必要があります。
ネイティブPluginは、`register(api)`を公開するエントリオブジェクトをエクスポートします。古いPluginではレガシーエイリアスとして`activate(api)`をまだ使用している場合がありますが、新しいPluginでは`register`を使用する必要があります。
```typescript
export default definePluginEntry({
@ -453,62 +498,60 @@ export default definePluginEntry({
});
```
OpenClaw はエントリオブジェクトをロードし、Plugin の有効化中に `register(api)` を呼び出します。ローダーは古い Plugin 向けに引き続き `activate(api)` にフォールバックしますが、バンドル Plugin と新しい外部 Plugin は `register` を公開コントラクトとして扱う必要があります。
OpenClawはPluginの有効化中にエントリオブジェクトを読み込み、`register(api)`を呼び出します。ローダーは古いPlugin向けに引き続き`activate(api)`へフォールバックしますが、バンドルされたPluginと新しい外部Pluginは`register`を公開契約として扱う必要があります。
`api.registrationMode` は、エントリがロードされている理由を Plugin に伝えます。
`api.registrationMode`は、エントリが読み込まれている理由をPluginに伝えます。
| モード | 意味 |
| モード | 意味 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | ランタイム有効化。ツール、フック、サービス、コマンド、ルート、その他のライブ副作用を登録します。 |
| `discovery` | 読み取り専用の機能検出。プロバイダーとメタデータを登録します。信頼済み Plugin エントリコードはロードされる場合がありますが、ライブ副作用はスキップします。 |
| `setup-only` | 軽量なセットアップエントリを通じたチャネルセットアップメタデータのロード。 |
| `setup-runtime` | ランタイムエントリも必要とするチャネルセットアップのロード。 |
| `cli-metadata` | CLI コマンドメタデータの収集のみ。 |
| `full` | ランタイム有効化。ツール、フック、サービス、コマンド、ルート、その他のライブ副作用を登録します。 |
| `discovery` | 読み取り専用の機能検出。プロバイダーとメタデータを登録します。信頼済みPluginのエントリコードは読み込まれる場合がありますが、ライブ副作用はスキップします。 |
| `setup-only` | 軽量なセットアップエントリによるチャネルセットアップメタデータの読み込み。 |
| `setup-runtime` | ランタイムエントリも必要とするチャネルセットアップの読み込み。 |
| `cli-metadata` | CLIコマンドメタデータの収集のみ。 |
ソケット、データベース、バックグラウンドワーカー、長寿命クライアントを開く Plugin エントリは、それらの副作用を `api.registrationMode === "full"` でガードする必要があります。検出ロードは有効化ロードとは別にキャッシュされ、実行中の Gateway レジストリを置き換えません。検出は有効化を伴いませんが、インポート不要ではありません。OpenClaw はスナップショットを構築するために、信頼済み Plugin エントリまたはチャネル Plugin モジュールを評価する場合があります。モジュールのトップレベルは軽量で副作用のない状態に保ち、ネットワーククライアント、サブプロセス、リスナー、認証情報の読み取り、サービス起動はフルランタイムパスの背後へ移動してください。
ソケット、データベース、バックグラウンドワーカー、長寿命クライアントを開くPluginエントリは、それらの副作用を`api.registrationMode === "full"`でガードする必要があります。Discovery読み込みは有効化読み込みとは別にキャッシュされ、実行中のGatewayレジストリを置き換えません。Discoveryは非有効化ですが、importなしではありません。OpenClawはスナップショットを構築するために、信頼済みPluginエントリまたはチャネルPluginモジュールを評価する場合があります。モジュールのトップレベルは軽量かつ副作用なしに保ち、ネットワーククライアント、サブプロセス、リスナー、認証情報の読み取り、サービス起動はフルランタイムのパスの背後へ移動してください。
一般的な登録メソッド:
| メソッド | 登録対象 |
| メソッド | 登録内容 |
| --------------------------------------- | --------------------------- |
| `registerProvider` | モデルプロバイダー（LLM） |
| `registerChannel` | チャットチャネル |
| `registerTool` | エージェントツール |
| `registerHook` / `on(...)` | ライフサイクルフック |
| `registerSpeechProvider` | テキスト読み上げ / STT |
| `registerRealtimeTranscriptionProvider` | ストリーミング STT |
| `registerRealtimeVoiceProvider` | 双方向リアルタイム音声 |
| `registerMediaUnderstandingProvider` | 画像/音声解析 |
| `registerImageGenerationProvider` | 画像生成 |
| `registerMusicGenerationProvider` | 音楽生成 |
| `registerVideoGenerationProvider` | 動画生成 |
| `registerWebFetchProvider` | Web フェッチ / スクレイピングプロバイダー |
| `registerWebSearchProvider` | Web 検索 |
| `registerHttpRoute` | HTTP エンドポイント |
| `registerCommand` / `registerCli` | CLI コマンド |
| `registerContextEngine` | コンテキストエンジン |
| `registerService` | バックグラウンドサービス |
| `registerProvider` | モデルプロバイダー（LLM） |
| `registerChannel` | チャットチャネル |
| `registerTool` | エージェントツール |
| `registerHook` / `on(...)` | ライフサイクルフック |
| `registerSpeechProvider` | テキスト読み上げ / STT |
| `registerRealtimeTranscriptionProvider` | ストリーミングSTT |
| `registerRealtimeVoiceProvider` | 双方向リアルタイム音声 |
| `registerMediaUnderstandingProvider` | 画像/音声分析 |
| `registerImageGenerationProvider` | 画像生成 |
| `registerMusicGenerationProvider` | 音楽生成 |
| `registerVideoGenerationProvider` | 動画生成 |
| `registerWebFetchProvider` | Web取得 / スクレイピングプロバイダー |
| `registerWebSearchProvider` | Web検索 |
| `registerHttpRoute` | HTTPエンドポイント |
| `registerCommand` / `registerCli` | CLIコマンド |
| `registerContextEngine` | コンテキストエンジン |
| `registerService` | バックグラウンドサービス |
型付きライフサイクルフックのフックガード動作:
- `before_tool_call`: `{ block: true }` は終端です。優先度の低いハンドラーはスキップされます。
- `before_tool_call`: `{ block: false }` は何もせず、以前のブロックを解除しません。
- `before_install`: `{ block: true }` は終端です。優先度の低いハンドラーはスキップされます。
- `before_install`: `{ block: false }` は何もせず、以前のブロックを解除しません。
- `message_sending`: `{ cancel: true }` は終端です。優先度の低いハンドラーはスキップされます。
- `message_sending`: `{ cancel: false }` は何もせず、以前のキャンセルを解除しません。
- `before_tool_call`: `{ block: true }`は終端です。低優先度のハンドラーはスキップされます。
- `before_tool_call`: `{ block: false }`は何もせず、以前のブロックを解除しません。
- `before_install`: `{ block: true }`は終端です。低優先度のハンドラーはスキップされます。
- `before_install`: `{ block: false }`は何もせず、以前のブロックを解除しません。
- `message_sending`: `{ cancel: true }`は終端です。低優先度のハンドラーはスキップされます。
- `message_sending`: `{ cancel: false }`は何もせず、以前のキャンセルを解除しません。
ネイティブ Codex app-server は、Codex ネイティブのツールイベントをこのフックサーフェスへブリッジします。Plugin は `before_tool_call` を通じてネイティブ Codex ツールをブロックし、`after_tool_call` を通じて結果を観察し、Codex
`PermissionRequest` 承認に参加できます。このブリッジは、Codex ネイティブのツール引数をまだ書き換えません。正確な Codex ランタイムサポート境界は、
[Codex ハーネス v1 サポートコントラクト](/ja-JP/plugins/codex-harness#v1-support-contract) にあります。
ネイティブCodex app-serverは、Codexネイティブのツールイベントをこのフックサーフェスへブリッジします。Pluginは`before_tool_call`を通じてネイティブCodexツールをブロックし、`after_tool_call`を通じて結果を監視し、Codex `PermissionRequest`の承認に参加できます。このブリッジはまだCodexネイティブのツール引数を書き換えません。Codexランタイムサポートの正確な境界は、[Codex harness v1サポート契約](/ja-JP/plugins/codex-harness#v1-support-contract)にあります。
型付きフック動作の詳細は、[SDK 概要](/ja-JP/plugins/sdk-overview#hook-decision-semantics) を参照してください。
型付きフック動作の詳細は、[SDK概要](/ja-JP/plugins/sdk-overview#hook-decision-semantics)を参照してください。
## 関連情報
## 関連
- [Plugin の構築](/ja-JP/plugins/building-plugins) — 独自の Plugin を作成する
- [Plugin バンドル](/ja-JP/plugins/bundles) — Codex/Claude/Cursor バンドル互換性
- [Plugin マニフェスト](/ja-JP/plugins/manifest) — マニフェストスキーマ
- [ツールの登録](/ja-JP/plugins/building-plugins#registering-agent-tools) — Plugin にエージェントツールを追加する
- [Plugin 内部構造](/ja-JP/plugins/architecture) — 機能モデルとロードパイプライン
- [コミュニティ Plugin](/ja-JP/plugins/community) — サードパーティ一覧
- [Plugin 内部構造](/ja-JP/plugins/architecture) — ケイパビリティモデルと読み込みパイプライン
- [コミュニティ Plugin](/ja-JP/plugins/community) — サードパーティの一覧

187
docs/ja-JP/tools/thinking.md
View File

@ -1,13 +1,13 @@
---
read_when:
- thinking、fast-mode、verboseディレクティブの解析またはデフォルトの調整
summary: /think、/fast、/verbose、/trace、および推論の可視性に関するディレクティブ構文
- thinking、fast-mode、またはverboseディレクティブの解析やデフォルトの調整
summary: /think、/fast、/verbose、/trace のディレクティブ構文と推論の可視性
title: 思考レベル
x-i18n:
generated_at: "2026-05-04T18:24:21Z"
generated_at: "2026-05-05T01:50:17Z"
model: gpt-5.5
provider: openai
source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012
source_path: tools/thinking.md
workflow: 16
---
@ -15,130 +15,131 @@ x-i18n:
## 機能
- 任意の受信本文内のインラインディレクティブ: `/t <level>`、`/think:<level>`、または `/thinking <level>`。
- レベル（エイリアス）: `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → 「think」
- low → 「think hard」
- medium → 「think harder」
- high → 「ultrathink」（最大予算）
- xhigh → 「ultrathink+」（GPT-5.2+ と Codex モデル、および Anthropic Claude Opus 4.7 effort）
- adaptive → プロバイダー管理の適応的思考（Anthropic/Bedrock 上の Claude 4.6、Anthropic Claude Opus 4.7、Google Gemini の動的思考でサポート）
- max → プロバイダー最大推論（Anthropic Claude Opus 4.7。Ollama はこれをネイティブの最高 `think` effort にマップ）
- `x-high`、`x_high`、`extra-high`、`extra high`、`extra_high` は `xhigh` にマップされます。
- `highest` は `high` にマップされます。
- レベル (エイリアス): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → 「考える」
- low → 「しっかり考える」
- medium → 「さらにしっかり考える」
- high → 「ultrathink」(最大予算)
- xhigh → 「ultrathink+」(GPT-5.2+ と Codex モデル、および Anthropic Claude Opus 4.7 effort)
- adaptive → プロバイダー管理の適応型思考 (Anthropic/Bedrock 上の Claude 4.6、Anthropic Claude Opus 4.7、Google Gemini 動的思考でサポート)
- max → プロバイダー最大推論 (Anthropic Claude Opus 4.7。Ollama はこれをネイティブの最高 `think` effort にマップする)
- `x-high`、`x_high`、`extra-high`、`extra high`、`extra_high` は `xhigh` にマップされる。
- `highest` は `high` にマップされる。
- プロバイダーに関する注記:
- 思考メニューとピッカーはプロバイダープロファイルによって駆動されます。Provider plugins は、バイナリの `on` などのラベルを含め、選択されたモデルの正確なレベルセットを宣言します。
- `adaptive`、`xhigh`、`max` は、それらをサポートするプロバイダー/モデルプロファイルに対してのみ表示されます。サポートされていないレベルの型付きディレクティブは、そのモデルの有効なオプションとともに拒否されます。
- 既存の保存済みの未サポートレベルは、プロバイダープロファイルのランクによって再マップされます。`adaptive` は非適応モデルでは `medium` にフォールバックし、`xhigh` と `max` は選択されたモデルでサポートされる最大の非 off レベルにフォールバックします。
- Anthropic Claude 4.6 モデルは、明示的な思考レベルが設定されていない場合、デフォルトで `adaptive` になります。
- Anthropic Claude Opus 4.7 は適応的思考をデフォルトにしません。その API effort のデフォルトは、思考レベルを明示的に設定しない限りプロバイダー所有のままです。
- Anthropic Claude Opus 4.7 は `/think xhigh` を、適応的思考に加えて `output_config.effort: "xhigh"` にマップします。これは `/think` が思考ディレクティブであり、`xhigh` が Opus 4.7 の effort 設定であるためです。
- Anthropic Claude Opus 4.7 は `/think max` も公開します。これは同じプロバイダー所有の最大 effort パスにマップされます。
- DeepSeek V4 モデルは `/think xhigh|max` を公開します。どちらも DeepSeek の `reasoning_effort: "max"` にマップされ、より低い非 off レベルは `high` にマップされます。
- Ollama の思考対応モデルは `/think low|medium|high|max` を公開します。Ollama のネイティブ API は `low`、`medium`、`high` の effort 文字列を受け付けるため、`max` はネイティブの `think: "high"` にマップされます。
- OpenAI GPT モデルは、モデル固有の Responses API effort サポートを通じて `/think` をマップします。`/think off` は、対象モデルがサポートする場合にのみ `reasoning.effort: "none"` を送信します。それ以外の場合、OpenClaw は未サポート値を送信する代わりに、無効化された推論ペイロードを省略します。
- カスタムの OpenAI 互換カタログエントリは、`models.providers.<provider>.models[].compat.supportedReasoningEfforts` に `"xhigh"` を含めることで `/think xhigh` にオプトインできます。これは送信される OpenAI 推論 effort ペイロードをマップするものと同じ互換メタデータを使用するため、メニュー、セッション検証、エージェント CLI、`llm-task` がトランスポート動作と一致します。
- 古くなった設定済みの OpenRouter Hunter Alpha 参照は、プロキシ推論の注入をスキップします。その廃止済みルートは、推論フィールドを通じて最終回答テキストを返す可能性があるためです。
- Google Gemini は `/think adaptive` を Gemini のプロバイダー所有の動的思考にマップします。Gemini 3 リクエストは固定の `thinkingLevel` を省略し、Gemini 2.5 リクエストは `thinkingBudget: -1` を送信します。固定レベルは、そのモデルファミリーに最も近い Gemini の `thinkingLevel` または予算に引き続きマップされます。
- Anthropic 互換ストリーミングパス上の MiniMax（`minimax/*`）は、モデルパラメーターまたはリクエストパラメーターで思考を明示的に設定しない限り、デフォルトで `thinking: { type: "disabled" }` になります。これにより、MiniMax の非ネイティブ Anthropic ストリーム形式から `reasoning_content` デルタが漏れることを避けます。
- Z.AI（`zai/*`）はバイナリ思考（`on`/`off`）のみをサポートします。任意の非 `off` レベルは `on` として扱われます（`low` にマップ）。
- Moonshot（`moonshot/*`）は `/think off` を `thinking: { type: "disabled" }` にマップし、任意の非 `off` レベルを `thinking: { type: "enabled" }` にマップします。思考が有効な場合、Moonshot は `tool_choice` の `auto|none` のみを受け付けます。OpenClaw は互換性のない値を `auto` に正規化します。
- 思考メニューとピッカーはプロバイダープロファイル駆動。プロバイダー Plugin は、バイナリ `on` などのラベルを含め、選択されたモデルの正確なレベルセットを宣言する。
- `adaptive`、`xhigh`、`max` は、それらをサポートするプロバイダー/モデルプロファイルにのみ表示される。サポートされないレベルの型付きディレクティブは、そのモデルの有効な選択肢とともに拒否される。
- 既存の保存済み未サポートレベルは、プロバイダープロファイルのランクによって再マップされる。`adaptive` は非適応モデルでは `medium` にフォールバックし、`xhigh` と `max` は選択されたモデルでサポートされる最大の非 off レベルにフォールバックする。
- Anthropic Claude 4.6 モデルは、明示的な思考レベルが設定されていない場合、デフォルトで `adaptive` になる。
- Anthropic Claude Opus 4.7 は適応型思考をデフォルトにしない。その API effort のデフォルトは、思考レベルを明示的に設定しない限り、プロバイダー所有のままになる。
- Anthropic Claude Opus 4.7 は `/think xhigh` を適応型思考と `output_config.effort: "xhigh"` にマップする。これは、`/think` が思考ディレクティブであり、`xhigh` が Opus 4.7 の effort 設定であるため。
- Anthropic Claude Opus 4.7 は `/think max` も公開する。これは同じプロバイダー所有の最大 effort パスにマップされる。
- 直接の DeepSeek V4 モデルは `/think xhigh|max` を公開する。どちらも DeepSeek `reasoning_effort: "max"` にマップされ、より低い非 off レベルは `high` にマップされる。
- OpenRouter 経由の DeepSeek V4 モデルは `/think xhigh` を公開し、OpenRouter がサポートする `reasoning_effort` 値を送信する。保存済みの `max` オーバーライドは `xhigh` にフォールバックする。
- Ollama の思考対応モデルは `/think low|medium|high|max` を公開する。Ollama のネイティブ API は `low`、`medium`、`high` の effort 文字列を受け付けるため、`max` はネイティブの `think: "high"` にマップされる。
- OpenAI GPT モデルは、モデル固有の Responses API effort サポートを通じて `/think` をマップする。`/think off` は、対象モデルがサポートする場合にのみ `reasoning.effort: "none"` を送信する。それ以外の場合、OpenClaw はサポートされない値を送信する代わりに、無効化された推論ペイロードを省略する。
- カスタム OpenAI 互換カタログエントリは、`models.providers.<provider>.models[].compat.supportedReasoningEfforts` に `"xhigh"` を含めることで `/think xhigh` を有効化できる。これは送信 OpenAI 推論 effort ペイロードをマップするものと同じ互換メタデータを使用するため、メニュー、セッション検証、エージェント CLI、`llm-task` がトランスポート動作と一致する。
- 古い設定済み OpenRouter Hunter Alpha 参照は、廃止されたそのルートが推論フィールド経由で最終回答テキストを返す可能性があるため、プロキシ推論注入をスキップする。
- Google Gemini は `/think adaptive` を Gemini のプロバイダー所有の動的思考にマップする。Gemini 3 リクエストは固定 `thinkingLevel` を省略し、Gemini 2.5 リクエストは `thinkingBudget: -1` を送信する。固定レベルは引き続き、そのモデルファミリーで最も近い Gemini `thinkingLevel` または予算にマップされる。
- Anthropic 互換ストリーミングパス上の MiniMax (`minimax/*`) は、モデルパラメーターまたはリクエストパラメーターで思考を明示的に設定しない限り、デフォルトで `thinking: { type: "disabled" }` になる。これにより、MiniMax の非ネイティブ Anthropic ストリーム形式から `reasoning_content` デルタが漏れるのを避ける。
- Z.AI (`zai/*`) はバイナリ思考 (`on`/`off`) のみをサポートする。非 `off` レベルはすべて `on` として扱われる (`low` にマップされる)。
- Moonshot (`moonshot/*`) は `/think off` を `thinking: { type: "disabled" }` にマップし、非 `off` レベルをすべて `thinking: { type: "enabled" }` にマップする。思考が有効な場合、Moonshot は `tool_choice` `auto|none` のみを受け付ける。OpenClaw は互換性のない値を `auto` に正規化する。
## 解決順序
1. メッセージ上のインラインディレクティブ（そのメッセージのみに適用）。
2. セッションオーバーライド（ディレクティブのみのメッセージ送信によって設定）。
3. エージェントごとのデフォルト（設定内の `agents.list[].thinkingDefault`）。
4. グローバルデフォルト（設定内の `agents.defaults.thinkingDefault`）。
5. フォールバック: プロバイダー宣言のデフォルトが利用可能な場合はそれを使用します。それ以外の場合、推論対応モデルは `medium` またはそのモデルでサポートされる最も近い非 `off` レベルに解決され、非推論モデルは `off` のままです。
1. メッセージ上のインラインディレクティブ (そのメッセージにのみ適用)。
2. セッションオーバーライド (ディレクティブのみのメッセージ送信で設定)。
3. エージェントごとのデフォルト (config 内の `agents.list[].thinkingDefault`)。
4. グローバルデフォルト (config 内の `agents.defaults.thinkingDefault`)。
5. フォールバック: 利用可能な場合はプロバイダー宣言デフォルト。それ以外の場合、推論対応モデルは `medium` またはそのモデルでサポートされる最も近い非 `off` レベルに解決され、非推論モデルは `off` のままになる。
## セッションデフォルトの設定
- ディレクティブ**のみ**のメッセージ（空白は許可）を送信します。例: `/think:medium` または `/t high`。
- これは現在のセッションに固定されます（デフォルトでは送信者ごと）。`/think:off` またはセッションのアイドルリセットでクリアされます。
- 確認返信が送信されます（`Thinking level set to high.` / `Thinking disabled.`）。レベルが無効な場合（例: `/thinking big`）、コマンドはヒント付きで拒否され、セッション状態は変更されません。
- 現在の思考レベルを確認するには、引数なしで `/think`（または `/think:`）を送信します。
- ディレクティブ**のみ**のメッセージ (空白は許可) を送信する。例: `/think:medium` または `/t high`。
- これは現在のセッションに固定される (デフォルトでは送信者ごと)。`/think:off` またはセッションのアイドルリセットでクリアされる。
- 確認返信が送信される (`Thinking level set to high.` / `Thinking disabled.`)。レベルが無効な場合 (例: `/thinking big`)、コマンドはヒント付きで拒否され、セッション状態は変更されない。
- 現在の思考レベルを確認するには、引数なしで `/think` (または `/think:`) を送信する。
## エージェントによる適用
## エージェント別の適用
- **組み込み Pi**: 解決されたレベルはプロセス内の Pi エージェントランタイムに渡されます。
- **Claude CLI バックエンド**: `claude-cli` 使用時、非 off レベルは `--effort` として Claude Code に渡されます。[CLI バックエンド](/ja-JP/gateway/cli-backends)を参照してください。
- **組み込み Pi**: 解決されたレベルはインプロセス Pi エージェントランタイムに渡される。
- **Claude CLI バックエンド**: `claude-cli` を使用する場合、非 off レベルは `--effort` として Claude Code に渡される。[CLI バックエンド](/ja-JP/gateway/cli-backends)を参照。
## 高速モード（/fast）
## 高速モード (/fast)
- レベル: `on|off`。
- ディレクティブのみのメッセージはセッションの高速モードオーバーライドを切り替え、`Fast mode enabled.` / `Fast mode disabled.` と返信します。
- 現在有効な高速モード状態を確認するには、モードなしで `/fast`（または `/fast status`）を送信します。
- OpenClaw は次の順序で高速モードを解決します:
- ディレクティブのみのメッセージは、セッションの高速モードオーバーライドを切り替え、`Fast mode enabled.` / `Fast mode disabled.` と返信する。
- 現在の有効な高速モード状態を確認するには、モードなしで `/fast` (または `/fast status`) を送信する。
- OpenClaw は高速モードを次の順序で解決する:
1. インライン/ディレクティブのみの `/fast on|off`
2. セッションオーバーライド
3. エージェントごとのデフォルト（`agents.list[].fastModeDefault`）
4. モデルごとの設定: `agents.defaults.models["<provider>/<model>"].params.fastMode`
3. エージェントごとのデフォルト (`agents.list[].fastModeDefault`)
4. モデルごとの config: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. フォールバック: `off`
- `openai/*` では、高速モードはサポートされる Responses リクエストで `service_tier=priority` を送信することで、OpenAI の優先処理にマップされます。
- `openai-codex/*` では、高速モードは Codex Responses 上で同じ `service_tier=priority` フラグを送信します。OpenClaw は両方の認証パスで共有される単一の `/fast` トグルを維持します。
- OAuth 認証済みで `api.anthropic.com` に送信されるトラフィックを含む、直接の公開 `anthropic/*` リクエストでは、高速モードは Anthropic サービス階層にマップされます。`/fast on` は `service_tier=auto` を設定し、`/fast off` は `service_tier=standard_only` を設定します。
- Anthropic 互換パス上の `minimax/*` では、`/fast on`（または `params.fastMode: true`）が `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。
- 明示的な Anthropic `serviceTier` / `service_tier` モデルパラメーターは、両方が設定されている場合に高速モードのデフォルトを上書きします。OpenClaw は Anthropic 以外のプロキシベース URL では、引き続き Anthropic サービス階層の注入をスキップします。
- `/status` は高速モードが有効な場合のみ `Fast` を表示します。
- `openai/*` の場合、高速モードは、サポートされる Responses リクエストで `service_tier=priority` を送信することで OpenAI 優先処理にマップされる。
- `openai-codex/*` の場合、高速モードは Codex Responses に同じ `service_tier=priority` フラグを送信する。OpenClaw は両方の認証パスで共有の `/fast` トグルを 1 つ維持する。
- OAuth 認証済みで `api.anthropic.com` に送信されるトラフィックを含む、直接の公開 `anthropic/*` リクエストでは、高速モードは Anthropic サービス階層にマップされる。`/fast on` は `service_tier=auto` を設定し、`/fast off` は `service_tier=standard_only` を設定する。
- Anthropic 互換パス上の `minimax/*` では、`/fast on` (または `params.fastMode: true`) が `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換える。
- 明示的な Anthropic `serviceTier` / `service_tier` モデルパラメーターは、両方が設定されている場合、高速モードデフォルトをオーバーライドする。OpenClaw は引き続き、非 Anthropic プロキシベース URL では Anthropic サービス階層注入をスキップする。
- `/status` は、高速モードが有効な場合にのみ `Fast` を表示する。
## 詳細ディレクティブ（/verbose または /v）
## Verbose ディレクティブ (/verbose または /v)
- レベル: `on`（最小） | `full` | `off`（デフォルト）。
- ディレクティブのみのメッセージはセッション詳細出力を切り替え、`Verbose logging enabled.` / `Verbose logging disabled.` と返信します。無効なレベルは状態を変更せずにヒントを返します。
- `/verbose off` は明示的なセッションオーバーライドを保存します。Sessions UI で `inherit` を選択するとクリアできます。
- インラインディレクティブはそのメッセージのみに影響します。それ以外の場合はセッション/グローバルデフォルトが適用されます。
- 現在の詳細レベルを確認するには、引数なしで `/verbose`（または `/verbose:`）を送信します。
- 詳細が on の場合、構造化ツール結果を出力するエージェント（Pi やその他の JSON エージェント）は、各ツール呼び出しを独自のメタデータのみのメッセージとして送り返します。利用可能な場合は `<emoji> <tool-name>: <arg>` が前置されます。これらのツール概要は、各ツールの開始直後に送信され（別々の吹き出し）、ストリーミングデルタとしては送信されません。
- ツール失敗の概要は通常モードでも表示されますが、生のエラー詳細サフィックスは、詳細が `on` または `full` でない限り非表示になります。
- 詳細が `full` の場合、ツール出力も完了後に転送されます（別の吹き出し、安全な長さに切り詰め）。実行中に `/verbose on|full|off` を切り替えた場合、その後のツール吹き出しは新しい設定に従います。
- `agents.defaults.toolProgressDetail` は、`/verbose` ツール概要と進行中下書きのツール行の形式を制御します。`🛠️ Exec: checking JS syntax` のようなコンパクトな人間向けラベルには `"explain"`（デフォルト）を使用します。デバッグ用に生のコマンド/詳細も追加したい場合は `"raw"` を使用します。エージェントごとの `agents.list[].toolProgressDetail` はデフォルトを上書きします。
- レベル: `on` (最小) | `full` | `off` (デフォルト)。
- ディレクティブのみのメッセージはセッション verbose を切り替え、`Verbose logging enabled.` / `Verbose logging disabled.` と返信する。無効なレベルは、状態を変更せずにヒントを返す。
- `/verbose off` は明示的なセッションオーバーライドを保存する。Sessions UI で `inherit` を選択してクリアする。
- インラインディレクティブはそのメッセージにのみ影響する。それ以外の場合はセッション/グローバルデフォルトが適用される。
- 現在の verbose レベルを確認するには、引数なしで `/verbose` (または `/verbose:`) を送信する。
- verbose が on の場合、構造化ツール結果を出力するエージェント (Pi、その他の JSON エージェント) は、各ツール呼び出しを、それぞれ独立したメタデータのみのメッセージとして送り返す。利用可能な場合は `<emoji> <tool-name>: <arg>` が先頭に付く。これらのツール要約は、各ツールが開始されるとすぐに送信され (別々の吹き出し)、ストリーミングデルタとしては送信されない。
- ツール失敗の要約は通常モードでも表示されたままだが、raw エラー詳細サフィックスは verbose が `on` または `full` でない限り非表示になる。
- verbose が `full` の場合、ツール出力も完了後に転送される (別の吹き出し、安全な長さに切り詰め)。実行中に `/verbose on|full|off` を切り替えると、以後のツール吹き出しは新しい設定に従う。
- `agents.defaults.toolProgressDetail` は、`/verbose` ツール要約と進行中ドラフトのツール行の形式を制御する。`🛠️ Exec: checking JS syntax` のようなコンパクトな人間向けラベルには `"explain"` (デフォルト) を使用する。デバッグ用に raw コマンド/詳細も追加したい場合は `"raw"` を使用する。エージェントごとの `agents.list[].toolProgressDetail` はデフォルトをオーバーライドする。
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## Plugin トレースディレクティブ（/trace）
## Plugin トレースディレクティブ (/trace)
- レベル: `on` | `off`（デフォルト）。
- ディレクティブのみのメッセージはセッションの Plugin トレース出力を切り替え、`Plugin trace enabled.` / `Plugin trace disabled.` と返信します。
- インラインディレクティブはそのメッセージのみに影響します。それ以外の場合はセッション/グローバルデフォルトが適用されます。
- 現在のトレースレベルを確認するには、引数なしで `/trace`（または `/trace:`）を送信します。
- `/trace` は `/verbose` より範囲が狭く、Active Memory デバッグ概要など、Plugin 所有のトレース/デバッグ行のみを公開します。
- トレース行は `/status` 内、および通常のアシスタント返信後の後続診断メッセージとして表示される場合があります。
- レベル: `on` | `off` (デフォルト)。
- ディレクティブのみのメッセージはセッション Plugin トレース出力を切り替え、`Plugin trace enabled.` / `Plugin trace disabled.` と返信する。
- インラインディレクティブはそのメッセージにのみ影響する。それ以外の場合はセッション/グローバルデフォルトが適用される。
- 現在のトレースレベルを確認するには、引数なしで `/trace` (または `/trace:`) を送信する。
- `/trace` は `/verbose` より範囲が狭い。Active Memory デバッグ要約など、Plugin 所有のトレース/デバッグ行のみを公開する。
- トレース行は `/status` に表示される場合があり、通常のアシスタント返信後のフォローアップ診断メッセージとして表示される場合もある。
## 推論の可視性（/reasoning）
## 推論の可視性 (/reasoning)
- レベル: `on|off|stream`。
- ディレクティブのみのメッセージは、思考ブロックを返信に表示するかどうかを切り替えます。
- 有効な場合、推論は `Reasoning:` で始まる**別メッセージ**として送信されます。
- `stream`（Telegram のみ）: 返信の生成中に推論を Telegram の下書き吹き出しへストリーミングし、その後、推論なしで最終回答を送信します。
- ディレクティブのみのメッセージは、返信で思考ブロックを表示するかどうかを切り替える。
- 有効な場合、推論は `Reasoning:` を先頭に付けた**別メッセージ**として送信される。
- `stream` (Telegram のみ): 返信生成中に推論を Telegram のドラフト吹き出しへストリーミングし、その後、推論なしで最終回答を送信する。
- エイリアス: `/reason`。
- 現在の推論レベルを確認するには、引数なしで `/reasoning`（または `/reasoning:`）を送信します。
- 解決順序: インラインディレクティブ、その後セッションオーバーライド、その後エージェントごとのデフォルト（`agents.list[].reasoningDefault`）、その後フォールバック（`off`）。
- 現在の推論レベルを確認するには、引数なしで `/reasoning` (または `/reasoning:`) を送信する。
- 解決順序: インラインディレクティブ、次にセッションオーバーライド、次にエージェントごとのデフォルト (`agents.list[].reasoningDefault`)、次にフォールバック (`off`)。
不正な形式のローカルモデル推論タグは保守的に処理されます。閉じた `<think>...</think>` ブロックは通常の返信では非表示のままで、すでに表示されたテキストの後にある閉じられていない推論も非表示になります。返信が単一の閉じられていない開始タグで完全に囲まれており、そうでなければ空テキストとして配信される場合、OpenClaw は不正な形式の開始タグを削除し、残りのテキストを配信します。
不正な local-model 推論タグは保守的に処理される。閉じられた `<think>...</think>` ブロックは通常の返信では非表示のままで、すでに表示可能なテキストの後にある閉じられていない推論も非表示になる。返信全体が単一の閉じられていない開始タグでラップされており、そのままだと空テキストとして配信される場合、OpenClaw は不正な開始タグを削除し、残りのテキストを配信する。
## 関連
- 昇格モードのドキュメントは[昇格モード](/ja-JP/tools/elevated)にあります。
- 昇格モードのドキュメントは[昇格モード](/ja-JP/tools/elevated)にある。
## Heartbeat
## Heartbeats
- Heartbeat プローブ本文は、設定された Heartbeat プロンプトです（デフォルト: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat メッセージ内のインラインディレクティブは通常どおり適用されます（ただし、Heartbeat からセッションデフォルトを変更することは避けてください）。
- Heartbeat 配信は、デフォルトで最終ペイロードのみです。別個の `Reasoning:` メッセージ（利用可能な場合）も送信するには、`agents.defaults.heartbeat.includeReasoning: true` またはエージェントごとの `agents.list[].heartbeat.includeReasoning: true` を設定します。
- Heartbeat プローブ本文は設定済みの Heartbeat プロンプト (デフォルト: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`)。Heartbeat メッセージ内のインラインディレクティブは通常どおり適用される (ただし Heartbeat からセッションデフォルトを変更することは避ける)。
- Heartbeat 配信はデフォルトで最終ペイロードのみ。別の `Reasoning:` メッセージも送信するには (利用可能な場合)、`agents.defaults.heartbeat.includeReasoning: true` またはエージェントごとの `agents.list[].heartbeat.includeReasoning: true` を設定する。
## Web チャット UI
- Web チャットの思考セレクターは、ページ読み込み時に受信セッションストア/設定からセッションの保存済みレベルを反映します。
- 別のレベルを選択すると、`sessions.patch` を介してセッションオーバーライドが即座に書き込まれます。次回送信を待たず、一度限りの `thinkingOnce` オーバーライドでもありません。
- 最初のオプションは常に `Default (<resolved level>)` です。ここで解決済みデフォルトは、アクティブなセッションモデルのプロバイダー思考プロファイルに加えて、`/status` と `session_status` が使用するものと同じフォールバックロジックに由来します。
- ピッカーは Gateway セッション行/デフォルトから返される `thinkingLevels` を使用し、`thinkingOptions` はレガシーラベルリストとして維持されます。ブラウザー UI は独自のプロバイダー正規表現リストを保持しません。plugins がモデル固有のレベルセットを所有します。
- `/think:<level>` は引き続き機能し、同じ保存済みセッションレベルを更新するため、チャットディレクティブとピッカーは同期したままです。
- Web チャットの思考セレクターは、ページ読み込み時に受信セッションストア/config からセッションの保存済みレベルを反映する。
- 別のレベルを選択すると、`sessions.patch` 経由ですぐにセッションオーバーライドを書き込む。次回送信を待たず、一度限りの `thinkingOnce` オーバーライドでもない。
- 最初のオプションは常に `Default (<resolved level>)` で、解決済みデフォルトは、アクティブセッションモデルのプロバイダー思考プロファイルと、`/status` および `session_status` が使用するものと同じフォールバックロジックから得られる。
- ピッカーは Gateway セッション行/デフォルトが返す `thinkingLevels` を使用し、`thinkingOptions` はレガシーラベルリストとして保持される。ブラウザー UI は独自のプロバイダー正規表現リストを保持しない。Plugin がモデル固有のレベルセットを所有する。
- `/think:<level>` は引き続き機能し、同じ保存済みセッションレベルを更新するため、チャットディレクティブとピッカーは同期されたままになる。
## プロバイダープロファイル
- プロバイダーPluginは、モデルがサポートするレベルとデフォルトを定義するために `resolveThinkingProfile(ctx)` を公開できます。
- ClaudeモデルをプロキシするプロバイダーPluginは、直接のAnthropicカタログとプロキシカタログの整合性を保つために、`openclaw/plugin-sdk/provider-model-shared` の `resolveClaudeThinkingProfile(modelId)` を再利用する必要があります。
- 各プロファイルレベルには、保存される正規の `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive`、または `max`）があり、表示用の `label` を含めることができます。バイナリプロバイダーは `{ id: "low", label: "on" }` を使用します。
- 明示的なthinkingオーバーライドを検証する必要があるツールPluginは、`api.runtime.agent.resolveThinkingPolicy({ provider, model })` と `api.runtime.agent.normalizeThinkingLevel(...)` を使用する必要があります。独自のプロバイダー/モデルのレベル一覧を保持しないでください。
- 設定済みのカスタムモデルメタデータにアクセスできるツールPluginは、`resolveThinkingPolicy` に `catalog` を渡すことで、`compat.supportedReasoningEfforts` のオプトインをPlugin側の検証に反映できます。
- 公開済みのレガシーフック（`supportsXHighThinking`、`isBinaryThinking`、および `resolveDefaultThinkingLevel`）は互換性アダプターとして残りますが、新しいカスタムレベルセットでは `resolveThinkingProfile` を使用する必要があります。
- Gatewayの行/デフォルトは `thinkingLevels`、`thinkingOptions`、および `thinkingDefault` を公開するため、ACP/chatクライアントはランタイム検証で使用されるものと同じプロファイルIDとラベルをレンダリングします。
- Claude モデルをプロキシするプロバイダーPluginは、直接の Anthropic とプロキシのカタログが揃った状態を保つために、`openclaw/plugin-sdk/provider-model-shared` の `resolveClaudeThinkingProfile(modelId)` を再利用する必要があります。
- 各プロファイルレベルには保存される正規の `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive`、または `max`）があり、表示用の `label` を含めることができます。バイナリプロバイダーは `{ id: "low", label: "on" }` を使用します。
- 明示的な thinking オーバーライドを検証する必要があるツールPluginは、`api.runtime.agent.resolveThinkingPolicy({ provider, model })` と `api.runtime.agent.normalizeThinkingLevel(...)` を使用する必要があります。独自のプロバイダー/モデルレベルリストを保持するべきではありません。
- 設定済みのカスタムモデルメタデータにアクセスできるツールPluginは、`catalog` を `resolveThinkingPolicy` に渡すことで、`compat.supportedReasoningEfforts` のオプトインをPlugin側の検証に反映できます。
- 公開済みのレガシーフック（`supportsXHighThinking`、`isBinaryThinking`、`resolveDefaultThinkingLevel`）は互換性アダプターとして残りますが、新しいカスタムレベルセットでは `resolveThinkingProfile` を使用する必要があります。
- Gateway の行/デフォルトは `thinkingLevels`、`thinkingOptions`、`thinkingDefault` を公開するため、ACP/チャットクライアントはランタイム検証で使用されるものと同じプロファイル ID とラベルを表示します。

354
docs/ja-JP/tools/video-generation.md
View File

@ -2,44 +2,44 @@
read_when:
- エージェント経由で動画を生成する
- 動画生成プロバイダーとモデルの設定
- video_generate ツールのパラメーターを理解する
- video_generate ツールのパラメータを理解する
sidebarTitle: Video generation
summary: テキスト、画像、または動画参照から、16のプロバイダーバックエンドにわたって video_generate 経由で動画を生成
summary: 16 のプロバイダーバックエンドで、テキスト、画像、または動画参照から video_generate により動画を生成
title: 動画生成
x-i18n:
generated_at: "2026-04-30T05:40:13Z"
generated_at: "2026-05-05T01:50:50Z"
model: gpt-5.5
provider: openai
source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf
source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83
source_path: tools/video-generation.md
workflow: 16
---
OpenClaw エージェントは、テキストプロンプト、参照画像、または
既存の動画から動画を生成できます。16 種類のプロバイダーバックエンドに対応しており、それぞれ
異なるモデルオプション、入力モード、機能セットを備えています。エージェントは、設定と利用可能な API
キーに基づいて、適切なプロバイダーを自動的に選択します。
既存の動画から動画を生成できます。16 個のプロバイダバックエンドがサポートされており、
それぞれモデルオプション、入力モード、機能セットが異なります。エージェントは、
構成と利用可能な API キーに基づいて適切なプロバイダを自動的に選択します。
<Note>
`video_generate` ツールは、少なくとも 1 つの動画生成
プロバイダーが利用可能な場合にのみ表示されます。エージェントツールに表示されない場合は、
プロバイダー API キーを設定するか、`agents.defaults.videoGenerationModel` を設定してください。
プロバイダが利用可能な場合にのみ表示されます。エージェントツールに表示されない場合は、
プロバイダの API キーを設定するか、`agents.defaults.videoGenerationModel` を構成してください。
</Note>
OpenClaw は動画生成を 3 つのランタイムモードとして扱います。
- `generate` — 参照メディアなしのテキストから動画へのリクエスト。
- `imageToVideo` — リクエストに 1 つ以上の参照画像を含みます。
- `videoToVideo` — リクエストに 1 つ以上の参照動画を含みます。
- `imageToVideo` — リクエストに 1 つ以上の参照画像が含まれます。
- `videoToVideo` — リクエストに 1 つ以上の参照動画が含まれます。
プロバイダーは、これらのモードの任意のサブセットに対応できます。ツールは送信前に
アクティブなモードを検証し、`action=list` で対応モードを報告します。
プロバイダは、これらのモードの任意のサブセットをサポートできます。ツールは送信前に
アクティブなモードを検証し、`action=list` でサポートされるモードを報告します。
## クイックスタート
<Steps>
<Step title="認証を設定する">
対応している任意のプロバイダーの API キーを設定します。
<Step title="認証を構成する">
サポートされる任意のプロバイダの API キーを設定します。
```bash
export GEMINI_API_KEY="your-key"
@ -52,9 +52,9 @@ OpenClaw は動画生成を 3 つのランタイムモードとして扱いま
```
</Step>
<Step title="エージェントに依頼する">
> 夕日の中で人懐っこいロブスターがサーフィンする、5 秒間の映画風動画を生成してください。
> 夕暮れにサーフィンする親しみやすいロブスターの、5 秒間の映画風動画を生成して。
エージェントは `video_generate` を自動的に呼び出します。ツールの許可リスト設定は
エージェントは `video_generate` を自動的に呼び出します。ツールの許可リスト登録は
不要です。
</Step>
@ -65,32 +65,34 @@ OpenClaw は動画生成を 3 つのランタイムモードとして扱いま
動画生成は非同期です。エージェントがセッション内で `video_generate` を呼び出すと、
次のように動作します。
1. OpenClaw はリクエストをプロバイダーに送信し、すぐにタスク ID を返します。
2. プロバイダーはバックグラウンドでジョブを処理します（通常、プロバイダーと解像度に応じて 30 秒から 5 分）。
3. 動画の準備ができると、OpenClaw は内部完了イベントで同じセッションを起動します。
4. エージェントは完成した動画を元の会話に投稿します。
1. OpenClaw はリクエストをプロバイダに送信し、ただちにタスク ID を返します。
2. プロバイダはバックグラウンドでジョブを処理します（通常、プロバイダと解像度に応じて 30 秒から 5 分）。
3. 動画の準備ができると、OpenClaw は内部完了イベントで同じセッションを再開します。
4. エージェントはユーザーに通知し、完成した動画を添付します。メッセージツールのみの
可視配信を使用するグループ/チャンネルチャットでは、OpenClaw が直接投稿する代わりに、
エージェントがメッセージツールを通じて結果を中継します。
ジョブの実行中、同じセッション内で重複した `video_generate` 呼び出しがある場合は、
ジョブが進行中の間、同じセッション内で重複する `video_generate` 呼び出しは、
別の生成を開始する代わりに現在のタスクステータスを返します。CLI から進捗を確認するには、
`openclaw tasks list` または `openclaw tasks show <taskId>` を使用します。
セッションに紐づいたエージェント実行の外部（たとえば、直接のツール呼び出し）では、
セッションに裏付けられたエージェント実行の外部（たとえば、直接のツール呼び出し）では、
ツールはインライン生成にフォールバックし、同じターンで最終メディアパスを返します。
プロバイダーがバイト列を返す場合、生成された動画ファイルは OpenClaw 管理のメディアストレージに
保存されます。デフォルトの生成動画の保存上限は動画メディアの制限に従い、
`agents.defaults.mediaMaxMb` を設定すると、より大きなレンダー向けに上限を引き上げられます。
プロバイダーがホスト済み出力 URL も返す場合、ローカル永続化がサイズ超過ファイルを拒否しても、
プロバイダがバイト列を返す場合、生成された動画ファイルは OpenClaw 管理のメディアストレージに保存されます。
デフォルトの生成動画保存上限は動画メディア制限に従い、
`agents.defaults.mediaMaxMb` によって大きなレンダー向けに引き上げられます。
プロバイダがホストされた出力 URL も返す場合、ローカル永続化がサイズ超過ファイルを拒否しても、
OpenClaw はタスクを失敗させる代わりにその URL を配信できます。
### タスクライフサイクル
### タスクのライフサイクル
| 状態 | 意味 |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued` | タスクが作成され、プロバイダーの受理を待っています。 |
| `running` | プロバイダーが処理中です（通常、プロバイダーと解像度に応じて 30 秒から 5 分）。 |
| `succeeded` | 動画の準備ができました。エージェントが起動し、会話に投稿します。 |
| `failed` | プロバイダーエラーまたはタイムアウトです。エージェントがエラー詳細とともに起動します。 |
| `queued` | タスクが作成され、プロバイダによる受け付けを待っています。 |
| `running` | プロバイダが処理中です（通常、プロバイダと解像度に応じて 30 秒から 5 分）。 |
| `succeeded` | 動画の準備ができました。エージェントが再開し、会話に投稿します。 |
| `failed` | プロバイダエラーまたはタイムアウトです。エージェントがエラー詳細とともに再開します。 |
CLI からステータスを確認します。
@ -100,59 +102,59 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
現在のセッションで動画タスクがすでに `queued` または `running` の場合、
`video_generate` は新しい生成を開始する代わりに既存のタスクステータスを返します。
新しい生成をトリガーせずに明示的に確認するには、`action: "status"` を使用します。
現在のセッションに対して動画タスクがすでに `queued` または `running` の場合、
`video_generate` は新しいタスクを開始する代わりに既存のタスクステータスを返します。
新しい生成をトリガーせず明示的に確認するには、`action: "status"` を使用します。
## 対応プロバイダー
## サポートされるプロバイダ
| プロバイダー | デフォルトモデル | テキスト | 画像参照 | 動画参照 | 認証 |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | はい（リモート URL） | はい（リモート URL） | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | 最大 2 画像（I2V モデルのみ、最初 + 最後のフレーム） | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | 最大 2 画像（ロール経由の最初 + 最後のフレーム） | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | 最大 9 枚の参照画像 | 最大 3 本の動画 | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 画像 | — | `COMFY_API_KEY` または `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 画像、Seedance の参照から動画では最大 9 画像 | Seedance の参照から動画では最大 3 本の動画 | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 画像 | 1 動画 | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 画像 | — | `MINIMAX_API_KEY` または MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 画像 | 1 動画 | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | 最大 4 画像（最初/最後のフレームまたは参照） | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | はい（リモート URL） | はい（リモート URL） | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 画像 | 1 動画 | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 画像 | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 画像（`kling`） | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 枚の最初フレーム画像、または最大 7 つの `reference_image` | 1 動画 | `XAI_API_KEY` |
| プロバイダ | デフォルトモデル | テキスト | 画像参照 | 動画参照 | 認証 |
| --------------------- | ------------------------------- | :------: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | はい（リモート URL） | はい（リモート URL） | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | 最大 2 画像（I2V モデルのみ、最初 + 最後のフレーム） | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | 最大 2 画像（role 経由の最初 + 最後のフレーム） | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | 最大 9 枚の参照画像 | 最大 3 本の動画 | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 画像 | — | `COMFY_API_KEY` または `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 画像、Seedance reference-to-video では最大 9 画像 | Seedance reference-to-video では最大 3 本の動画 | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 画像 | 1 動画 | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 画像 | — | `MINIMAX_API_KEY` または MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 画像 | 1 動画 | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | 最大 4 画像（最初/最後のフレームまたは参照） | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | はい（リモート URL） | はい（リモート URL） | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 画像 | 1 動画 | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 画像 | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 画像（`kling`） | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 枚の最初フレーム画像、または最大 7 枚の `reference_image` | 1 動画 | `XAI_API_KEY` |
一部のプロバイダーは、追加または代替の API キー環境変数を受け付けます。詳細は
個別の[プロバイダーページ](#related)を参照してください。
一部のプロバイダは、追加または代替の API キー環境変数を受け付けます。詳細は
各 [プロバイダページ](#related) を参照してください。
実行時に利用可能なプロバイダー、モデル、ランタイムモードを確認するには、
実行時に利用可能なプロバイダ、モデル、ランタイムモードを調べるには、
`video_generate action=list` を実行します。
### 機能マトリクス
`video_generate`、契約テスト、共有ライブスイープで使用される明示的なモード契約は次のとおりです。
`video_generate`、コントラクトテスト、共有ライブスイープで使用される明示的なモード契約:
| プロバイダー | `generate` | `imageToVideo` | `videoToVideo` | 現在の共有ライブレーン |
| プロバイダ | `generate` | `imageToVideo` | `videoToVideo` | 現在の共有ライブレーン |
| ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。このプロバイダーはリモートの `http(s)` 動画 URL を必要とするため、`videoToVideo` はスキップされます |
| Alibaba | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。このプロバイダはリモート `http(s)` 動画 URL を必要とするため、`videoToVideo` はスキップされます |
| BytePlus | ✓ | ✓ | — | `generate`、`imageToVideo` |
| ComfyUI | ✓ | ✓ | — | 共有スイープには含まれません。ワークフロー固有のカバレッジは Comfy テスト側にあります |
| DeepInfra | ✓ | — | — | `generate`。バンドルされた契約では、ネイティブの DeepInfra 動画スキーマはテキストから動画です |
| fal | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。`videoToVideo` は Seedance の参照から動画を使用する場合のみ |
| Google | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。現在のバッファベースの Gemini/Veo スイープはその入力を受け付けないため、共有 `videoToVideo` はスキップされます |
| ComfyUI | ✓ | ✓ | — | 共有スイープには含まれません。workflow 固有のカバレッジは Comfy テスト側にあります |
| DeepInfra | ✓ | — | — | `generate`。ネイティブ DeepInfra 動画スキーマは、バンドルされたコントラクトではテキストから動画です |
| fal | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。`videoToVideo` は Seedance reference-to-video 使用時のみ |
| Google | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。現在のバッファベース Gemini/Veo スイープがその入力を受け付けないため、共有 `videoToVideo` はスキップされます |
| MiniMax | ✓ | ✓ | — | `generate`、`imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。この組織/入力パスは現在プロバイダー側のインペイント/リミックスアクセスを必要とするため、共有 `videoToVideo` はスキップされます |
| OpenAI | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。この組織/入力パスは現在プロバイダ側の inpaint/remix アクセスを必要とするため、共有 `videoToVideo` はスキップされます |
| OpenRouter | ✓ | ✓ | — | `generate`、`imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。このプロバイダーはリモートの `http(s)` 動画 URL を必要とするため、`videoToVideo` はスキップされます |
| Runway | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。`videoToVideo` は選択されたモデルが `runway/gen4_aleph` の場合のみ実行されます |
| Qwen | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。このプロバイダはリモート `http(s)` 動画 URL を必要とするため、`videoToVideo` はスキップされます |
| Runway | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。`videoToVideo` は選択されたモデルが `runway/gen4_aleph` の場合にのみ実行されます |
| Together | ✓ | ✓ | — | `generate`、`imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate`。バンドルされた `veo3` はテキスト専用で、バンドルされた `kling` はリモート画像 URL を必要とするため、共有 `imageToVideo` はスキップされます |
| xAI | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。このプロバイダーは現在リモート MP4 URL を必要とするため、`videoToVideo` はスキップされます |
| Vydra | ✓ | ✓ | — | `generate`。バンドルされた `veo3` はテキストのみで、バンドルされた `kling` はリモート画像 URL を必要とするため、共有 `imageToVideo` はスキップされます |
| xAI | ✓ | ✓ | ✓ | `generate`、`imageToVideo`。このプロバイダは現在リモート MP4 URL を必要とするため、`videoToVideo` はスキップされます |
## ツールパラメーター
## ツールパラメータ
### 必須
@ -165,33 +167,33 @@ openclaw tasks cancel <taskId>
<ParamField path="image" type="string">単一の参照画像（パスまたは URL）。</ParamField>
<ParamField path="images" type="string[]">複数の参照画像（最大 9 件）。</ParamField>
<ParamField path="imageRoles" type="string[]">
結合された画像リストと並行する、位置ごとの任意のロールヒント。
結合された画像リストと並行する、任意の位置別ロールヒント。
正規値: `first_frame`, `last_frame`, `reference_image`。
</ParamField>
<ParamField path="video" type="string">単一の参照動画（パスまたは URL）。</ParamField>
<ParamField path="videos" type="string[]">複数の参照動画（最大 4 件）。</ParamField>
<ParamField path="videoRoles" type="string[]">
結合された動画リストと並行する、位置ごとの任意のロールヒント。
結合された動画リストと並行する、任意の位置別ロールヒント。
正規値: `reference_video`。
</ParamField>
<ParamField path="audioRef" type="string">
単一の参照音声（パスまたは URL）。プロバイダーが音声入力をサポートする場合に、
単一の参照音声（パスまたは URL）。プロバイダーが音声入力をサポートしている場合に、
背景音楽または音声参照に使用されます。
</ParamField>
<ParamField path="audioRefs" type="string[]">複数の参照音声（最大 3 件）。</ParamField>
<ParamField path="audioRoles" type="string[]">
結合された音声リストと並行する、位置ごとの任意のロールヒント。
結合された音声リストと並行する、任意の位置別ロールヒント。
正規値: `reference_audio`。
</ParamField>
<Note>
ロールヒントはそのままプロバイダーに転送されます。正規値は
`VideoGenerationAssetRole` ユニオンに由来しますが、プロバイダーは追加の
ロール文字列を受け付ける場合があります。`*Roles` 配列は、対応する
参照リストより多いエントリを持ってはいけません。1 つずれのミスは明確なエラーで失敗します。
ロールヒントはそのままプロバイダーへ転送されます。正規値は
`VideoGenerationAssetRole` union に由来しますが、プロバイダーは追加の
ロール文字列を受け付ける場合があります。`*Roles` 配列のエントリー数は、
対応する参照リストを超えてはいけません。1 件ずれの誤りは明確なエラーで失敗します。
スロットを未設定のままにするには空文字列を使用します。xAI では、
その `reference_images` 生成モードを使用するために、すべての画像ロールを
`reference_image` に設定します。単一画像の image-to-video では、
`reference_images` 生成モードを使用するために、すべての画像ロールを
`reference_image` に設定します。単一画像の image-to-video には、
ロールを省略するか `first_frame` を使用します。
</Note>
@ -202,19 +204,18 @@ openclaw tasks cancel <taskId>
</ParamField>
<ParamField path="resolution" type="string">`480P`, `720P`, `768P`, または `1080P`。</ParamField>
<ParamField path="durationSeconds" type="number">
目標の長さ（秒）。最も近いプロバイダー対応値に丸められます。
目標継続時間（秒）。プロバイダーがサポートする最も近い値に丸められます。
</ParamField>
<ParamField path="size" type="string">プロバイダーがサポートする場合のサイズヒント。</ParamField>
<ParamField path="audio" type="boolean">
サポートされている場合、出力内の生成音声を有効にします。`audioRef*`（入力）とは別です。
サポートされる場合、出力で生成音声を有効にします。`audioRef*`（入力）とは別です。
</ParamField>
<ParamField path="watermark" type="boolean">サポートされている場合、プロバイダーの透かしを切り替えます。</ParamField>
<ParamField path="watermark" type="boolean">サポートされる場合、プロバイダーのウォーターマークを切り替えます。</ParamField>
`adaptive` はプロバイダー固有のセンチネルです。機能で `adaptive` を宣言している
プロバイダーにはそのまま転送されます（たとえば BytePlus
Seedance は入力画像の寸法から比率を自動検出するために使用します）。
これを宣言していないプロバイダーでは、削除が見えるようにツール結果の
`details.ignoredOverrides` 経由で値が表示されます。
プロバイダーへそのまま転送されます（例: BytePlus Seedance は入力画像の
寸法から比率を自動検出するために使用します）。宣言していないプロバイダーでは、
破棄が見えるようにツール結果の `details.ignoredOverrides` で値が提示されます。
### 高度な設定
@ -227,20 +228,20 @@ Seedance は入力画像の寸法から比率を自動検出するために使
<ParamField path="providerOptions" type="object">
JSON オブジェクトとしてのプロバイダー固有オプション（例: `{"seed": 42, "draft": true}`）。
型付きスキーマを宣言しているプロバイダーは、キーと型を検証します。不明な
キーや不一致がある場合、フォールバック中にその候補はスキップされます。宣言済みスキーマを持たない
プロバイダーはオプションをそのまま受け取ります。各プロバイダーが何を受け付けるか確認するには、
`video_generate action=list` を実行します。
キーや不一致がある場合、フォールバック中に候補がスキップされます。宣言済み
スキーマがないプロバイダーは、オプションをそのまま受け取ります。各プロバイダーが
受け付ける内容を確認するには `video_generate action=list` を実行します。
</ParamField>
<Note>
すべてのプロバイダーがすべてのパラメーターをサポートしているわけではありません。OpenClaw は長さを
最も近いプロバイダー対応値に正規化し、フォールバックプロバイダーが異なる
制御面を公開している場合、size-to-aspect-ratio などの変換済みジオメトリヒントを再マップします。
すべてのプロバイダーがすべてのパラメーターをサポートしているわけではありません。
OpenClaw は継続時間をプロバイダーがサポートする最も近い値に正規化し、
フォールバックプロバイダーが異なる制御面を公開している場合は、
size-to-aspect-ratio などの変換されたジオメトリヒントを再マップします。
本当にサポートされていない上書きはベストエフォートで無視され、
ツール結果に警告として報告されます。厳密な機能制限
（参照入力が多すぎる場合など）は送信前に失敗します。ツール結果は
適用された設定を報告します。`details.normalization` は、
要求から適用への変換をすべて記録します。
ツール結果に警告として報告されます。参照入力が多すぎるなどの
厳密な機能上限は、送信前に失敗します。ツール結果は適用された設定を報告します。
`details.normalization` には、要求値から適用値への変換が記録されます。
</Note>
参照入力はランタイムモードを選択します。
@ -248,57 +249,59 @@ Seedance は入力画像の寸法から比率を自動検出するために使
- 参照メディアなし → `generate`
- 画像参照あり → `imageToVideo`
- 動画参照あり → `videoToVideo`
- 参照音声入力は、解決されるモードを**変更しません**。画像/動画参照が選択するモードの
上に適用され、`maxInputAudios` を宣言しているプロバイダーでのみ機能します。
- 参照音声入力は、解決されるモードを変更**しません**。画像/動画参照が選択した
モードの上に適用され、`maxInputAudios` を宣言しているプロバイダーでのみ
動作します。
画像参照と動画参照の混在は、安定した共有機能面ではありません。
リクエストごとに 1 種類の参照タイプを使うことを推奨します。
リクエストごとに 1 種類の参照タイプを優先してください。
#### フォールバックと型付きオプション
一部の機能チェックはツール境界ではなくフォールバック層で適用されるため、
プライマリプロバイダーの制限を超えるリクエストでも、対応可能なフォールバックで
実行できる場合があります。
プライマリプロバイダーの上限を超えるリクエストでも、対応可能なフォールバックで
実行できます。
- アクティブな候補が `maxInputAudios` を宣言していない（または `0`）場合、
リクエストに音声参照が含まれているとスキップされ、次の候補が試されます。
- アクティブな候補の `maxDurationSeconds` が要求された `durationSeconds` を下回り、
宣言済みの `supportedDurationSeconds` リストがない場合 → スキップされます。
- リクエストに `providerOptions` が含まれており、アクティブな候補が型付き
- リクエストに音声参照が含まれている場合、`maxInputAudios` を宣言していない（または `0` の）
アクティブ候補はスキップされ、次の候補が試行されます。
- アクティブ候補の `maxDurationSeconds` が要求された `durationSeconds` を下回り、
`supportedDurationSeconds` リストが宣言されていない場合 → スキップされます。
- リクエストに `providerOptions` が含まれ、アクティブ候補が型付き
`providerOptions` スキーマを明示的に宣言している場合 → 指定されたキーが
スキーマ内にない、または値の型が一致しない場合はスキップされます。宣言済みスキーマを持たない
プロバイダーはオプションをそのまま受け取ります（後方互換の
パススルー）。プロバイダーは空のスキーマ
（`capabilities.providerOptions: {}`）を宣言することで、すべてのプロバイダーオプションを
オプトアウトできます。この場合、型不一致と同じスキップが発生します。
スキーマ内にない、または値の型が一致しない場合はスキップされます。宣言済み
スキーマがないプロバイダーは、オプションをそのまま受け取ります（後方互換の
パススルー）。プロバイダーは空スキーマ（`capabilities.providerOptions: {}`）を
宣言することで、すべてのプロバイダーオプションを拒否できます。この場合、
型不一致と同じスキップが発生します。
リクエスト内の最初のスキップ理由は `warn` でログに記録されるため、オペレーターは
プライマリプロバイダーが見送られたことを確認できます。以降のスキップは `debug` でログに記録され、
長いフォールバックチェーンを静かに保ちます。すべての候補がスキップされた場合、
集約エラーにはそれぞれのスキップ理由が含まれます。
リクエスト内の最初のスキップ理由は `warn` でログに記録されるため、
オペレーターはプライマリプロバイダーが見送られたことを確認できます。
以降のスキップは、長いフォールバックチェーンを静かに保つため `debug` で
ログに記録されます。すべての候補がスキップされた場合、集約エラーには
それぞれのスキップ理由が含まれます。
## アクション
| アクション | 実行内容 |
| アクション | 内容 |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `generate` | デフォルト。指定されたプロンプトと任意の参照入力から動画を作成します。 |
| `status` | 別の生成を開始せずに、現在のセッションで進行中の動画タスクの状態を確認します。 |
| `list` | 利用可能なプロバイダー、モデル、その機能を表示します。 |
| `generate` | デフォルト。指定されたプロンプトと任意の参照入力から動画を作成します。 |
| `status` | 別の生成を開始せずに、現在のセッションで実行中の動画タスクの状態を確認します。 |
| `list` | 利用可能なプロバイダー、モデル、およびそれらの機能を表示します。 |
## モデル選択
OpenClaw は次の順序でモデルを解決します。
1. **`model` ツールパラメーター** — エージェントが呼び出しで指定した場合。
2. 設定内の **`videoGenerationModel.primary`**。
3. 順序どおりの **`videoGenerationModel.fallbacks`**。
2. config の **`videoGenerationModel.primary`**。
3. **`videoGenerationModel.fallbacks`** を順番に。
4. **自動検出** — 有効な認証を持つプロバイダー。現在のデフォルトプロバイダーから開始し、
その後、残りのプロバイダーをアルファベット順に処理します。
残りのプロバイダーをアルファベット順に試します。
プロバイダーが失敗すると、次の候補が自動的に試されます。すべての
プロバイダーが失敗した場合、次の候補が自動的に試行されます。すべての
候補が失敗した場合、エラーには各試行の詳細が含まれます。
明示的な `model`、`primary`、`fallbacks` エントリのみを使用するには、
明示的な `model`、`primary`、`fallbacks` エントリーのみを使用するには、
`agents.defaults.mediaGenerationAutoProviderFallback: false` を設定します。
```json5
@ -329,10 +332,9 @@ OpenClaw は次の順序でモデルを解決します。
`seedance-1-0-lite-t2v-250428`、`seedance-1-0-lite-i2v-250428`。
T2V モデル（`*-t2v-*`）は画像入力を受け付けません。I2V モデルと
汎用 `*-pro-*` モデルは単一の参照画像（最初の
フレーム）をサポートします。画像を位置指定で渡すか、`role: "first_frame"` を設定します。
画像が提供されると、T2V モデル ID は対応する I2V
バリアントに自動的に切り替えられます。
一般的な `*-pro-*` モデルは単一の参照画像（最初のフレーム）をサポートします。
画像を位置指定で渡すか、`role: "first_frame"` を設定します。
画像が指定されると、T2V モデル ID は対応する I2V バリアントへ自動的に切り替わります。
サポートされる `providerOptions` キー: `seed`（number）、`draft`（boolean —
480p を強制）、`camera_fixed`（boolean）。
@ -343,10 +345,10 @@ OpenClaw は次の順序でモデルを解決します。
Plugin が必要です。プロバイダー ID: `byteplus-seedance15`。モデル:
`seedance-1-5-pro-251215`。
統合された `content[]` API を使用します。最大 2 つの入力画像
（`first_frame` + `last_frame`）をサポートします。すべての入力はリモートの `https://`
URL である必要があります。各画像に `role: "first_frame"` / `"last_frame"` を設定するか、
画像を位置指定で渡します。
統合 `content[]` API を使用します。最大 2 つの入力画像
（`first_frame` + `last_frame`）をサポートします。すべての入力はリモートの
`https://` URL である必要があります。各画像に `role: "first_frame"` /
`"last_frame"` を設定するか、画像を位置指定で渡します。
`aspectRatio: "adaptive"` は入力画像から比率を自動検出します。
`audio: true` は `generate_audio` にマップされます。`providerOptions.seed`
@ -359,10 +361,10 @@ OpenClaw は次の順序でモデルを解決します。
`dreamina-seedance-2-0-260128`、
`dreamina-seedance-2-0-fast-260128`。
統合された `content[]` API を使用します。最大 9 つの参照画像、
統合 `content[]` API を使用します。最大 9 つの参照画像、
3 つの参照動画、3 つの参照音声をサポートします。すべての入力はリモートの
`https://` URL である必要があります。各アセットに `role` を設定します。サポート値:
`"first_frame"`、`"last_frame"`、`"reference_image"`、
`https://` URL である必要があります。各アセットに `role` を設定します —
サポート値: `"first_frame"`、`"last_frame"`、`"reference_image"`、
`"reference_video"`、`"reference_audio"`。
`aspectRatio: "adaptive"` は入力画像から比率を自動検出します。
@ -371,59 +373,61 @@ OpenClaw は次の順序でモデルを解決します。
</Accordion>
<Accordion title="ComfyUI">
ワークフロー駆動のローカルまたはクラウド実行。設定されたグラフを通じて、
ワークフロー駆動のローカルまたはクラウド実行です。設定されたグラフを通じて
text-to-video と image-to-video をサポートします。
</Accordion>
<Accordion title="fal">
長時間実行ジョブにキュー支援フローを使用します。ほとんどの fal 動画モデルは
単一の画像参照を受け付けます。Seedance 2.0 reference-to-video
モデルは、最大 9 つの画像、3 つの動画、3 つの音声参照を受け付け、
参照ファイルの合計は最大 12 件です。
単一の画像参照を受け付けます。Seedance 2.0 reference-to-video モデルは、
最大 9 つの画像、3 つの動画、3 つの音声参照を受け付け、参照ファイルの合計は
最大 12 件です。
</Accordion>
<Accordion title="Google (Gemini / Veo)">
1 つの画像または 1 つの動画参照をサポートします。
1 つの画像参照または 1 つの動画参照をサポートします。
</Accordion>
<Accordion title="MiniMax">
単一の画像参照のみ。
単一画像参照のみ。
</Accordion>
<Accordion title="OpenAI">
`size` 上書きのみが転送されます。その他のスタイル上書き
（`aspectRatio`、`resolution`、`audio`、`watermark`）は警告付きで無視されます。
（`aspectRatio`、`resolution`、`audio`、`watermark`）は警告付きで
無視されます。
</Accordion>
<Accordion title="OpenRouter">
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` アスペクト比を告知します。
</Accordion>
<Accordion title="Qwen">
Alibaba と同じ DashScope バックエンド。参照入力はリモートの
Alibaba と同じ DashScope バックエンドです。参照入力はリモートの
`http(s)` URL である必要があります。ローカルファイルは事前に拒否されます。
</Accordion>
<Accordion title="Runway">
データ URI 経由でローカルファイルをサポートします。Video-to-video には
data URI 経由でローカルファイルをサポートします。video-to-video には
`runway/gen4_aleph` が必要です。テキストのみの実行では `16:9` と `9:16` の
アスペクト比が公開されます。
</Accordion>
<Accordion title="Together">
単一の画像参照のみ。
単一画像参照のみ。
</Accordion>
<Accordion title="Vydra">
認証を落とすリダイレクトを避けるため、`https://www.vydra.ai/api/v1` を直接使用します。
`veo3` は text-to-video のみとしてバンドルされています。`kling` には
認証が落ちるリダイレクトを避けるため、`https://www.vydra.ai/api/v1` を直接使用します。
`veo3` は text-to-video のみとして同梱されています。`kling` には
リモート画像 URL が必要です。
</Accordion>
<Accordion title="xAI">
text-to-video、単一の最初フレーム image-to-video、xAI `reference_images` 経由の最大 7 つの
`reference_image` 入力、およびリモート
動画編集/拡張フローをサポートします。
text-to-video、単一の最初のフレーム image-to-video、xAI `reference_images` 経由の
最大 7 つの `reference_image` 入力、リモート動画の編集/延長フローをサポートします。
</Accordion>
</AccordionGroup>
## プロバイダー機能モード
共有の動画生成コントラクトは、フラットな集約制限だけでなく、モード固有の機能をサポートします。新しいプロバイダー実装では、明示的なモードブロックを優先してください。
共有動画生成コントラクトは、フラットな集約制限だけではなく、
モード固有の機能をサポートします。新しいプロバイダー実装では、
明示的なモードブロックを優先してください。
```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"

125
docs/ja-JP/web/dashboard.md
View File

@ -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)を参照してください。
<a id="if-you-see-unauthorized-1008"></a>
## 「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 アクセス -> 言語** にあります。
これはアクセスカードの一部であり、外観セクションではありません。
## 関連