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-01 05:05:59 +00:00
parent 3c73751118
commit 9b101fdc74
19 changed files with 3191 additions and 2811 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,52 +1,51 @@
---
read_when:
- 進行中または最近完了したバックグラウンド作業の確認
- 進行中または最近完了したバックグラウンド作業を確認する
- デタッチされたエージェント実行の配信失敗をデバッグする
- バックグラウンド実行がセッション、Cron、Heartbeat とどのように関係するかを理解する
- バックグラウンド実行がセッション、Cron、Heartbeat とどう関係するかを理解する
sidebarTitle: Background tasks
summary: ACP 実行、サブエージェント、分離された Cron ジョブ、CLI 操作のバックグラウンドタスク追跡
title: バックグラウンドタスク
x-i18n:
generated_at: "2026-04-30T16:28:03Z"
generated_at: "2026-05-01T05:00:32Z"
model: gpt-5.5
provider: openai
source_hash: 999653c9360323d5135e33193c76458cba8c288227de46a6217f1ccbed2a6d34
source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4
source_path: automation/tasks.md
workflow: 16
---
<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>
## 要点
## 要約
- タスクはスケジューラではなく**記録**です。CronとHeartbeatが作業を_いつ_実行するかを決め、タスクは_何が起きたか_を追跡します。
- ACP、サブエージェント、すべてのCronジョブ、CLI操作はタスクを作成します。Heartbeatターンは作成しません。
- 各タスクは `queued → running → terminal`（succeeded、failed、timed_out、cancelled、lost）を遷移します。
- Cronタスクは、Cronランタイムがまだジョブを所有している間はライブのままです。
インメモリのランタイム状態が失われている場合、タスクメンテナンスはまず永続化されたCron実行履歴を確認してから、タスクをlostとしてマークします。
- 完了はプッシュ駆動です。切り離された作業は、完了時に直接通知するか、
リクエスト元セッション/Heartbeatを起こすことができるため、ステータスのポーリングループは
通常は適切な形ではありません。
- 分離されたCron実行とサブエージェント完了は、最終的なクリーンアップ記録の前に、子セッションで追跡されているブラウザタブ/プロセスをベストエフォートでクリーンアップします。
- 分離されたCron配信は、子孫サブエージェント作業がまだ完了処理中の場合、古くなった途中の親返信を抑制し、配信前に子孫の最終出力が届いた場合はそれを優先します。
- 完了通知はチャンネルへ直接配信されるか、次のHeartbeatに向けてキューに入れられます。
- `openclaw tasks list` はすべてのタスクを表示します。`openclaw tasks audit` は問題を表示します。
- terminalレコードは7日間保持され、その後自動的に削除されます。
- タスクはスケジューラーではなく**レコード**です。cron と Heartbeat は作業を_いつ_実行するかを決め、タスクは_何が起きたか_を追跡します。
- ACP、サブエージェント、すべての cron ジョブ、CLI 操作はタスクを作成します。Heartbeat ターンは作成しません。
- 各タスクは `queued → running → terminal`（succeeded、failed、timed_out、cancelled、または lost）を進みます。
- cron タスクは、cron ランタイムがまだジョブを所有している間はライブのままです。
メモリ内のランタイム状態がなくなった場合、タスクのメンテナンスはタスクを lost としてマークする前に、まず永続化された cron
実行履歴を確認します。
- 完了はプッシュ駆動です: 分離された作業は完了時に直接通知するか、リクエスターのセッション/Heartbeat を起こせるため、ステータスのポーリングループは通常適切な形ではありません。
- 分離された cron 実行とサブエージェント完了は、最終クリーンアップの帳簿処理の前に、子セッションで追跡されているブラウザータブ/プロセスをベストエフォートでクリーンアップします。
- 分離された cron 配信は、子孫サブエージェントの作業がまだ排出中の間は古くなった暫定的な親返信を抑制し、配信前に子孫の最終出力が届いた場合はそれを優先します。
- 完了通知はチャンネルに直接配信されるか、次の Heartbeat 用にキューに入れられます。
- `openclaw tasks list` はすべてのタスクを表示します。`openclaw tasks audit` は問題を表面化します。
- 終端レコードは 7 日間保持され、その後自動的に削除されます。
## クイックスタート
<Tabs>
<Tab title="一覧表示とフィルタ">
<Tab title="一覧表示とフィルター">
```bash
# List all tasks (newest first)
openclaw tasks list
@ -57,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>
@ -84,7 +83,7 @@ x-i18n:
```
</Tab>
<Tab title="タスクフロー">
<Tab title="TaskFlow">
```bash
# Inspect TaskFlow state
openclaw tasks flow list
@ -96,26 +95,26 @@ x-i18n:
## タスクを作成するもの
| ソース | ランタイム種別 | タスクレコードが作成されるタイミング | デフォルト通知ポリシー |
| ソース | ランタイムタイプ | タスクレコードが作成されるタイミング | デフォルト通知ポリシー |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| ACPバックグラウンド実行 | `acp` | 子ACPセッションの起動 | `done_only` |
| サブエージェントのオーケストレーション | `subagent` | `sessions_spawn` によるサブエージェントの起動 | `done_only` |
| Cronジョブ（全種別） | `cron` | すべてのCron実行（メインセッションと分離実行） | `silent` |
| CLI操作 | `cli` | Gateway経由で実行される `openclaw agent` コマンド | `silent` |
| エージェントメディアジョブ | `cli` | セッションに紐づく `video_generate` 実行 | `silent` |
| ACP バックグラウンド実行 | `acp` | 子 ACP セッションを起動する時 | `done_only` |
| サブエージェントのオーケストレーション | `subagent` | `sessions_spawn` 経由でサブエージェントを起動する時 | `done_only` |
| cron ジョブ（全タイプ） | `cron` | すべての cron 実行（メインセッションおよび分離） | `silent` |
| CLI 操作 | `cli` | Gateway を通じて実行される `openclaw agent` コマンド | `silent` |
| エージェントメディアジョブ | `cli` | セッション backed の `music_generate`/`video_generate` 実行 | `silent` |
<AccordionGroup>
<Accordion title="Cronとメディアの通知デフォルト">
メインセッションのCronタスクは、デフォルトで `silent` 通知ポリシーを使用します。追跡用のレコードは作成しますが、通知は生成しません。分離されたCronタスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より見えやすくなります。
<Accordion title="cron とメディアの通知デフォルト">
メインセッションの cron タスクは、デフォルトで `silent` 通知ポリシーを使用します。追跡用のレコードは作成しますが、通知は生成しません。分離された cron タスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より見えやすくなります。
セッションに紐づく `video_generate` 実行も `silent` 通知ポリシーを使用します。タスクレコードは引き続き作成しますが、完了は内部wakeとして元のエージェントセッションに戻されるため、エージェントがフォローアップメッセージを書き、完成した動画を自分で添付できます。`tools.media.asyncCompletion.directSend` を有効にすると、非同期の `music_generate` と `video_generate` の完了は、リクエスト元セッションのwake経路へフォールバックする前に、まずチャンネルへの直接配信を試みます。
セッション backed の `music_generate` と `video_generate` 実行も `silent` 通知ポリシーを使用します。それでもタスクレコードは作成されますが、完了は内部 wake として元のエージェントセッションに戻され、エージェントがフォローアップメッセージを書き、完成したメディアを自分で添付できるようにします。`tools.media.asyncCompletion.directSend` を有効にすると、非同期の `video_generate` 完了はまず直接チャンネル配信を試せます。非同期の `music_generate` 完了はリクエスターセッションの wake パスに留まります。
</Accordion>
<Accordion title="同時video_generateのガードレール">
セッションに紐づく `video_generate` タスクがまだアクティブな間、このツールはガードレールとしても機能します。同じセッションで `video_generate` を繰り返し呼び出すと、2つ目の同時生成を開始する代わりに、アクティブなタスクのステータスを返します。エージェント側から明示的に進捗/ステータスを取得したい場合は、`action: "status"` を使用してください。
<Accordion title="同時 video_generate ガードレール">
セッション backed の `video_generate` タスクがまだアクティブな間、このツールはガードレールとしても機能します。同じセッションで `video_generate` が繰り返し呼び出されると、2 つ目の同時生成を開始する代わりに、アクティブなタスクのステータスを返します。エージェント側から明示的に進行状況/ステータスを参照したい場合は `action: "status"` を使用してください。
</Accordion>
<Accordion title="タスクを作成しないもの">
- Heartbeatターン — メインセッション。[Heartbeat](/ja-JP/gateway/heartbeat)を参照
- Heartbeat ターン（メインセッション）。[Heartbeat](/ja-JP/gateway/heartbeat)を参照
- 通常の対話型チャットターン
- 直接の `/command` 応答
@ -136,64 +135,63 @@ stateDiagram-v2
running --> lost : session gone > 5 min
```
| ステータス | 意味 |
| ステータス | 意味 |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | 作成済みで、エージェントの開始を待機中 |
| `running` | エージェントターンがアクティブに実行中 |
| `succeeded` | 正常に完了 |
| `failed` | エラーで完了 |
| `timed_out` | 設定されたタイムアウトを超過 |
| `cancelled` | `openclaw tasks cancel` によりオペレーターが停止 |
| `lost` | 5分間の猶予期間後に、ランタイムが信頼できる裏付け状態を失った |
| `queued` | 作成済みで、エージェントの開始を待っています |
| `running` | エージェントターンがアクティブに実行中です |
| `succeeded` | 正常に完了しました |
| `failed` | エラーで完了しました |
| `timed_out` | 構成されたタイムアウトを超過しました |
| `cancelled` | オペレーターが `openclaw tasks cancel` で停止しました |
| `lost` | ランタイムが 5 分間の猶予期間後に、信頼できる裏付け状態を失いました |
遷移は自動的に発生します。関連するエージェント実行が終了すると、タスクステータスがそれに合わせて更新されます。
遷移は自動的に発生します。関連付けられたエージェント実行が終了すると、タスクステータスはそれに合わせて更新されます。
エージェント実行の完了は、アクティブなタスクレコードに対する信頼できる情報源です。成功した切り離し実行は `succeeded` として最終化され、通常の実行エラーは `failed` として最終化され、タイムアウトまたは中止の結果は `timed_out` として最終化されます。オペレーターがすでにタスクをキャンセルしている場合、またはランタイムが `failed`、`timed_out`、`lost` などより強いterminal状態をすでに記録している場合、後から成功シグナルが来ても、そのterminalステータスは弱められません。
エージェント実行の完了は、アクティブなタスクレコードに対して信頼できる情報源です。成功した分離実行は `succeeded` として確定し、通常の実行エラーは `failed` として確定し、タイムアウトまたは中止の結果は `timed_out` として確定します。オペレーターがすでにタスクをキャンセルしている場合、またはランタイムが `failed`、`timed_out`、`lost` など、より強い終端状態をすでに記録している場合、後から成功シグナルが来てもその終端ステータスは引き下げられません。
`lost` はランタイムを考慮します。
`lost` はランタイムを考慮します:
- ACPタスク: 裏付けとなるACP子セッションメタデータが消えた。
- サブエージェントタスク: 裏付けとなる子セッションがターゲットエージェントストアから消えた。
- Cronタスク: Cronランタイムがジョブをアクティブとして追跡しなくなり、永続化された
Cron実行履歴にもその実行のterminal結果がない。オフラインCLI
監査は、自身の空のインプロセスCronランタイム状態を権威として扱いません。
- CLIタスク: 分離された子セッションタスクは子セッションを使用します。チャットに紐づく
CLIタスクは代わりにライブ実行コンテキストを使用するため、残存する
チャンネル/グループ/ダイレクトのセッション行がそれらを生存状態に保つことはありません。Gatewayに紐づく
`openclaw agent` 実行も実行結果から最終化されるため、完了済み実行が
スイーパーによって `lost` とマークされるまでアクティブのまま残ることはありません。
- ACP タスク: 裏付けとなる ACP 子セッションのメタデータが消えました。
- サブエージェントタスク: 裏付けとなる子セッションがターゲットエージェントストアから消えました。
- cron タスク: cron ランタイムがそのジョブをアクティブとして追跡しなくなり、永続化された
cron 実行履歴にもその実行の終端結果が示されていません。オフライン CLI
監査は、自身の空のインプロセス cron ランタイム状態を権威として扱いません。
- CLI タスク: 分離された子セッションタスクは子セッションを使用します。チャット backed の
CLI タスクは代わりにライブ実行コンテキストを使用するため、残存する
チャンネル/グループ/ダイレクトセッション行がそれらを生存状態に保つことはありません。Gateway backed の
`openclaw agent` 実行も実行結果から確定されるため、完了済みの実行がスイーパーにより `lost` とマークされるまでアクティブなまま残ることはありません。
## 配信と通知
タスクがterminal状態に到達すると、OpenClawが通知します。配信経路は2つあります。
タスクが終端状態に達すると、OpenClaw が通知します。配信パスは 2 つあります:
**直接配信** — タスクにチャンネルターゲット（`requesterOrigin`）がある場合、完了メッセージはそのチャンネル（Telegram、Discord、Slackなど）へ直接送られます。サブエージェント完了では、OpenClawは利用可能な場合に紐づいたスレッド/トピックのルーティングも保持し、直接配信を諦める前に、リクエスト元セッションに保存された経路（`lastChannel` / `lastTo` / `lastAccountId`）から不足している `to` / account を補完できます。
**直接配信** — タスクにチャンネルターゲット（`requesterOrigin`）がある場合、完了メッセージはそのチャンネル（Telegram、Discord、Slack など）に直接送られます。サブエージェント完了では、OpenClaw は利用可能な場合に紐付いたスレッド/トピックのルーティングも保持し、直接配信を諦める前に、リクエスターセッションに保存されたルート（`lastChannel` / `lastTo` / `lastAccountId`）から欠けている `to` / アカウントを補完できます。
**セッションキュー配信** — 直接配信が失敗するかoriginが設定されていない場合、更新はリクエスト元のセッションにシステムイベントとしてキューに入れられ、次のHeartbeatで表示されます。
**セッションキュー配信** — 直接配信が失敗した場合、または origin が設定されていない場合、更新はリクエスターのセッション内のシステムイベントとしてキューに入れられ、次の Heartbeat で表面化します。
<Tip>
タスク完了は即時のHeartbeat wakeをトリガーするため、結果をすぐに確認できます。次にスケジュールされたHeartbeat tickを待つ必要はありません。
タスク完了は即時の Heartbeat wake をトリガーするため、結果をすばやく確認できます。次のスケジュール済み Heartbeat tick を待つ必要はありません。
</Tip>
つまり、通常のワークフローはプッシュベースです。切り離された作業を一度開始し、その後は完了時にランタイムがwakeまたは通知するのに任せます。デバッグ、介入、明示的な監査が必要な場合にのみタスク状態をポーリングしてください。
つまり、通常のワークフローはプッシュベースです。分離された作業を一度開始したら、完了時にランタイムが wake または通知するのを待ちます。デバッグ、介入、明示的な監査が必要な場合にのみタスク状態をポーリングしてください。
### 通知ポリシー
各タスクについて、どの程度通知を受け取るかを制御します。
各タスクについて、どの程度通知を受けるかを制御します:
| ポリシー | 配信される内容 |
| ポリシー | 配信される内容 |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only`（デフォルト） | terminal状態（succeeded、failedなど）のみ — **これがデフォルトです** |
| `state_changes` | すべての状態遷移と進捗更新 |
| `silent` | 何もなし |
| `done_only`（デフォルト） | 終端状態（succeeded、failed など）のみ — **これがデフォルトです** |
| `state_changes` | すべての状態遷移と進行状況更新 |
| `silent` | 何も配信されません |
タスクの実行中にポリシーを変更します。
タスクの実行中にポリシーを変更します:
```bash
openclaw tasks notify <lookup> state_changes
```
## CLIリファレンス
## CLI リファレンス
<AccordionGroup>
<Accordion title="tasks list">
@ -201,7 +199,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
出力列: Task ID、Kind、Status、Delivery、Run ID、Child Session、Summary。
出力列: タスク ID、種類、ステータス、配信、実行 ID、子セッション、要約。
</Accordion>
<Accordion title="tasks show">
@ -209,7 +207,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
lookupトークンには、タスクID、実行ID、セッションキーを指定できます。タイミング、配信状態、エラー、terminalサマリーを含む完全なレコードを表示します。
参照トークンには、タスク ID、実行 ID、またはセッションキーを指定できます。タイミング、配信状態、エラー、終端要約を含む完全なレコードを表示します。
</Accordion>
<Accordion title="tasks cancel">
@ -217,7 +215,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
ACPタスクとサブエージェントタスクでは、これは子セッションを終了します。CLIで追跡されるタスクでは、キャンセルはタスクレジストリに記録されます（別個の子ランタイムハンドルはありません）。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。
ACP とサブエージェントタスクでは、これにより子セッションが終了されます。CLI で追跡されるタスクでは、キャンセルはタスクレジストリに記録されます（別個の子ランタイムハンドルはありません）。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。
</Accordion>
<Accordion title="tasks notify">
@ -230,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` までは警告になり、その後エラーになる |
| `lost` | warn/error | ランタイムに裏付けられたタスク所有権が消失した。保持中の lost タスクは `cleanupAfter` まで警告になり、その後エラーになる |
| `delivery_failed` | warn | 配信に失敗し、通知ポリシーが `silent` ではない |
| `missing_cleanup` | warn | クリーンアップタイムスタンプがない終端タスク |
| `inconsistent_timestamps` | warn | タイムライン違反（たとえば開始前に終了している） |
| `missing_cleanup` | warn | クリーンアップタイムスタンプがない終端タスク |
| `inconsistent_timestamps` | warn | タイムライン違反（たとえば開始前に終了している） |
</Accordion>
<Accordion title="tasks maintenance">
<Accordion title="tasks メンテナンス">
```bash
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
これを使用して、タスクと Task Flow 状態の照合、クリーンアップのタイムスタンプ付与、プルーニングをプレビューまたは適用します。
タスクと Task Flow 状態の照合、クリーンアップのスタンプ付け、枝刈りをプレビューまたは適用するために使います。
照合はランタイムを考慮します。
照合はランタイムを認識します。
- ACP/サブエージェントタスクは、裏付けとなる子セッションを確認します。
- 子セッションに再起動リカバリの tombstone があるサブエージェントタスクは、リカバリ可能な裏付けセッションとして扱われるのではなく lost とマークされます。
- Cron タスクは、cron ランタイムがまだジョブを所有しているかどうかを確認し、その後 `lost` にフォールバックする前に、永続化された cron 実行ログ/ジョブ状態から終端ステータスを復元します。メモリ内の cron アクティブジョブセットについて権威を持つのは Gateway プロセスだけです。オフライン CLI 監査は永続履歴を使用しますが、そのローカル Set が空であることだけを理由に cron タスクを lost とマークしません。
- チャットに裏付けられた CLI タスクは、チャットセッション行だけでなく、所有するライブ実行コンテキストを確認します。
- 子セッションに再起動復旧の墓標があるサブエージェントタスクは、復旧可能な裏付けセッションとして扱われるのではなく、lost としてマークされます。
- Cron タスクは、cron ランタイムがまだジョブを所有しているかを確認し、その後 `lost` にフォールバックする前に、永続化された cron 実行ログ/ジョブ状態から終端ステータスを復旧します。メモリ内の cron アクティブジョブセットについて権威を持つのは Gateway プロセスだけです。オフライン CLI 監査は永続履歴を使いますが、そのローカル Set が空であるという理由だけで cron タスクを lost にしません。
- チャットに裏付けられた CLI タスクは、チャットセッション行だけでなく、所有しているライブ実行コンテキストを確認します。
完了クリーンアップもランタイムを考慮します。
完了時のクリーンアップもランタイムを認識します。
- サブエージェント完了では、通知クリーンアップを続ける前に、子セッションで追跡されているブラウザータブ/プロセスをベストエフォートで閉じます。
- 分離 cron 完了では、実行が完全に終了する前に、cron セッションで追跡されているブラウザータブ/プロセスをベストエフォートで閉じます。
- 分離 cron 配信は、必要に応じて子孫サブエージェントのフォローアップを待ち、古い親の確認応答テキストを通知する代わりに抑制します。
- サブエージェント完了配信は、最新の表示可能なアシスタントテキストを優先します。それが空の場合は、サニタイズされた最新の tool/toolResult テキストにフォールバックし、タイムアウトのみのツール呼び出し実行は短い部分進捗サマリーに折りたたまれることがあります。終端失敗実行は、キャプチャされた返信テキストを再生せずに失敗ステータスを通知します。
- クリーンアップ失敗は、実際のタスク結果を隠しません。
- サブエージェントの完了では、通知クリーンアップが続行する前に、子セッションの追跡対象ブラウザータブ/プロセスをベストエフォートで閉じます。
- 分離 cron の完了では、実行が完全に終了する前に、cron セッションの追跡対象ブラウザータブ/プロセスをベストエフォートで閉じます。
- 分離 cron の配信は、必要に応じて子孫サブエージェントのフォローアップを待機し、古くなった親の確認応答テキストを通知する代わりに抑制します。
- サブエージェントの完了配信では、最新の表示可能な assistant テキストが優先されます。それが空の場合は、サニタイズ済みの最新 tool/toolResult テキストにフォールバックし、タイムアウトのみのツール呼び出し実行は短い部分進捗サマリーにまとめられることがあります。終端失敗実行では、キャプチャされた返信テキストを再生せずに失敗ステータスを通知します。
- クリーンアップ失敗は、実際のタスク結果を覆い隠しません。
</Accordion>
<Accordion title="tasks flow list | show | cancel">
@ -273,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` ごとの内訳
- **byRuntime** — `acp`、`subagent`、`cron`、`cli` 別の内訳
`/status` と `session_status` ツールはいずれも、クリーンアップを考慮したタスクスナップショットを使用します。アクティブなタスクが優先され、古い完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは今重要な内容に集中できます。
`/status` と `session_status` ツールはいずれも、クリーンアップを認識したタスクスナップショットを使います。アクティブなタスクが優先され、古くなった完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは現在重要なものに集中できます。
## ストレージとメンテナンス
### タスクの保存場所
タスクレコードは、SQLite で次の場所に永続化されます。
タスクレコードは次の SQLite に永続化されます。
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
レジストリは Gateway 起動時にメモリへ読み込まれ、再起動後も耐久性を保つために書き込みを SQLite に同期します。
Gateway は、SQLite のデフォルトの自動チェックポイントしきい値に加え、定期的およびシャットダウン時の `TRUNCATE` チェックポイントを使用して、SQLite write-ahead log を一定範囲に保ちます。
レジストリは Gateway 起動時にメモリへ読み込まれ、再起動をまたいだ耐久性のために書き込みを SQLite に同期します。
Gateway は、SQLite のデフォルト自動チェックポイントしきい値に加えて、定期的およびシャットダウン時の `TRUNCATE` チェックポイントを使うことで、SQLite の先行書き込みログを一定範囲に保ちます。
### 自動メンテナンス
sweeper は **60 秒** ごとに実行され、4 つの処理を行います。
スイーパーは **60 秒** ごとに実行され、4 つのことを処理します。
<Steps>
<Step title="照合">
アクティブなタスクに、まだ権威あるランタイムの裏付けがあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使用し、cron タスクはアクティブジョブ所有権を使用し、チャットに裏付けられた CLI タスクは所有する実行コンテキストを使用します。その裏付け状態が 5 分を超えて消失している場合、タスクは `lost` とマークされます。
アクティブなタスクに、まだ権威あるランタイムの裏付けがあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使い、cron タスクはアクティブジョブの所有権を使い、チャットに裏付けられた CLI タスクは所有している実行コンテキストを使います。その裏付け状態が 5 分を超えて失われている場合、タスクは `lost` としてマークされます。
</Step>
<Step title="ACP セッション修復">
終端または孤立した親所有のワンショット ACP セッションを閉じ、アクティブな会話バインディングが残っていない場合にのみ、古い終端または孤立した永続 ACP セッションを閉じます。
終端または孤立した親所有のワンショット ACP セッションを閉じ、アクティブな会話バインディングが残っていない場合にのみ、古くなった終端または孤立した永続 ACP セッションを閉じます。
</Step>
<Step title="クリーンアップのタイムスタンプ付与">
終端タスクに `cleanupAfter` タイムスタンプを設定します（endedAt + 7 日）。保持期間中、lost タスクは監査で警告として表示されます。`cleanupAfter` が期限切れになった後、またはクリーンアップメタデータが欠落している場合はエラーになります。
<Step title="クリーンアップのスタンプ付け">
終端タスクに `cleanupAfter` タイムスタンプを設定します（endedAt + 7 日）。保持期間中、lost タスクは監査で引き続き警告として表示されます。`cleanupAfter` が期限切れになった後、またはクリーンアップメタデータが欠落している場合は、エラーになります。
</Step>
<Step title="プルーニング">
<Step title="枝刈り">
`cleanupAfter` 日付を過ぎたレコードを削除します。
</Step>
</Steps>
<Note>
**保持期間:** 終端タスクレコードは **7 日間** 保持され、その後自動的にプルーニングされます。設定は不要です。
**保持:** 終端タスクレコードは **7 日間** 保持され、その後自動的に枝刈りされます。設定は不要です。
</Note>
## タスクと他システムの関係
<AccordionGroup>
<Accordion title="タスクと Task Flow">
[Task Flow](/ja-JP/automation/taskflow) は、バックグラウンドタスクの上位にあるフローオーケストレーションレイヤーです。1 つのフローは、そのライフタイム中に managed または mirrored 同期モードを使用して複数のタスクを調整する場合があります。個々のタスクレコードを調べるには `openclaw tasks` を使用し、オーケストレーションしているフローを調べるには `openclaw tasks flow` を使用します。
[Task Flow](/ja-JP/automation/taskflow) は、バックグラウンドタスクの上位にあるフローオーケストレーション層です。1 つのフローは、そのライフタイムを通じて、管理同期モードまたはミラー同期モードを使って複数のタスクを調整できます。個別のタスクレコードを調べるには `openclaw tasks` を使い、オーケストレーションしているフローを調べるには `openclaw tasks flow` を使います。
詳細は [Task Flow](/ja-JP/automation/taskflow) を参照してください。
</Accordion>
<Accordion title="タスクと cron">
cron ジョブ**定義**は `~/.openclaw/cron/jobs.json` にあり、ランタイム実行状態はその横の `~/.openclaw/cron/jobs-state.json` にあります。**すべての** cron 実行は、メインセッションと分離実行の両方でタスクレコードを作成します。メインセッション cron タスクは、通知を生成せずに追跡できるよう、通知ポリシーのデフォルトが `silent` です。
cron ジョブの**定義**は `~/.openclaw/cron/jobs.json` にあり、ランタイム実行状態はその隣の `~/.openclaw/cron/jobs-state.json` にあります。cron 実行は**すべて**タスクレコードを作成します。メインセッションと分離セッションの両方です。メインセッションの cron タスクはデフォルトで `silent` 通知ポリシーになっているため、通知を生成せずに追跡されます。
[Cron ジョブ](/ja-JP/automation/cron-jobs) を参照してください。
</Accordion>
<Accordion title="タスクと Heartbeat">
Heartbeat 実行はメインセッションのターンであり、タスクレコードを作成しません。タスクが完了すると、結果をすぐに確認できるよう Heartbeat のウェイクをトリガーできます。
Heartbeat の実行はメインセッションのターンです。タスクレコードは作成しません。タスクが完了すると、結果をすぐに確認できるように Heartbeat ウェイクをトリガーできます。
[Heartbeat](/ja-JP/gateway/heartbeat) を参照してください。
</Accordion>
<Accordion title="タスクとセッション">
タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（開始した人）を参照する場合があります。セッションは会話コンテキストであり、タスクはその上にあるアクティビティ追跡です。
タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（それを開始した人）を参照することがあります。セッションは会話コンテキストであり、タスクはその上にあるアクティビティ追跡です。
</Accordion>
<Accordion title="タスクとエージェント実行">
タスクの `runId` は、作業を実行しているエージェント実行にリンクします。エージェントのライフサイクルイベント（開始、終了、エラー）は、タスクステータスを自動的に更新します。ライフサイクルを手動で管理する必要はありません。
タスクの `runId` は、作業を行っているエージェント実行にリンクします。エージェントのライフサイクルイベント（開始、終了、エラー）はタスクステータスを自動的に更新するため、ライフサイクルを手動で管理する必要はありません。
</Accordion>
</AccordionGroup>
@ -372,5 +370,5 @@ sweeper は **60 秒** ごとに実行され、4 つの処理を行います。
- [自動化とタスク](/ja-JP/automation) — すべての自動化メカニズムの概要
- [CLI: タスク](/ja-JP/cli/tasks) — CLI コマンドリファレンス
- [Heartbeat](/ja-JP/gateway/heartbeat) — 定期的なメインセッションターン
- [Scheduled Tasks](/ja-JP/automation/cron-jobs) — バックグラウンド作業のスケジューリング
- [Task Flow](/ja-JP/automation/taskflow) — タスクの上位にあるフローオーケストレーション
- [スケジュール済みタスク](/ja-JP/automation/cron-jobs) — バックグラウンド作業のスケジューリング
- [Task Flow](/ja-JP/automation/taskflow) — タスク上位のフローオーケストレーション

207
docs/ja-JP/channels/groups.md
View File

@ -1,38 +1,38 @@
---
read_when:
- グループチャットの動作またはメンションゲーティングの変更
- グループチャットの挙動またはメンション制御を変更する
sidebarTitle: Groups
summary: 各サーフェスにおけるグループチャットの動作 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
summary: 各サーフェスでのグループチャットの挙動 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: グループ
x-i18n:
generated_at: "2026-04-30T16:27:42Z"
generated_at: "2026-05-01T05:00:19Z"
model: gpt-5.5
provider: openai
source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e
source_hash: a8580f98ab03c89770688102da776627d8ce18b7bd34c4a687009fd4aabb6213
source_path: channels/groups.md
workflow: 16
---
OpenClaw は、Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo の各サーフェスでグループチャットを一貫して扱います。
## 初心者向け概要（2 分）
## 初心者向けイントロ（2 分）
OpenClaw は自分のメッセージングアカウント上に「存在」します。別個の WhatsApp ボットユーザーはありません。**あなた** がグループにいる場合、OpenClaw はそのグループを認識し、そこで応答できます。
OpenClaw は自分のメッセージングアカウント上に「存在」します。別の WhatsApp bot ユーザーはありません。**あなた**がグループにいる場合、OpenClaw はそのグループを認識し、そこで応答できます。
デフォルトの動作:
- グループは制限されます（`groupPolicy: "allowlist"`）。
- 明示的にメンションゲートを無効化しない限り、返信にはメンションが必要です。
- グループ/チャンネルでの通常の最終返信は、デフォルトでは非公開です。ルームに表示される出力には `message` ツールを使用します。
- グループは制限されています（`groupPolicy: "allowlist"`）。
- メンションゲートを明示的に無効にしない限り、返信にはメンションが必要です。
- グループ/チャンネル内の通常の最終返信は、デフォルトで非公開です。ルームに表示される出力には `message` ツールを使います。
つまり、許可リストに含まれる送信者は、OpenClaw にメンションすることで OpenClaw をトリガーできます。
つまり、許可リストに登録された送信者は、OpenClaw にメンションすることで OpenClaw をトリガーできます。
<Note>
**要約**
- **DM アクセス** は `*.allowFrom` で制御されます。
- **グループアクセス** は `*.groupPolicy` + 許可リスト（`*.groups`、`*.groupAllowFrom`）で制御されます。
- **返信のトリガー** はメンションゲート（`requireMention`、`/activation`）で制御されます。
- **DM アクセス**は `*.allowFrom` で制御されます。
- **グループアクセス**は `*.groupPolicy` + 許可リスト（`*.groups`、`*.groupAllowFrom`）で制御されます。
- **返信のトリガー**はメンションゲート（`requireMention`、`/activation`）で制御されます。
</Note>
@ -45,18 +45,21 @@ requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply
```
## 表示される返信
## 表示返信
グループ/チャンネルルームでは、OpenClaw のデフォルトは `messages.groupChat.visibleReplies: "message_tool"` です。
つまり、エージェントはそのターンを引き続き処理し、メモリ/セッション状態を更新できますが、通常の最終回答はルームに自動投稿されません。表示される形で発言するには、エージェントは `message(action=send)` を使用します。
これは、エージェントがターンを処理し、メモリ/セッション状態を更新できる一方で、通常の最終回答は自動的にはルームに投稿されないことを意味します。表示される形で発言するには、エージェントは `message(action=send)` を使います。
直接チャットやその他のソースターンで同じツール専用の表示返信動作をグローバルに適用するには、`messages.visibleReplies: "message_tool"` を使用します。`messages.groupChat.visibleReplies` は、グループ/チャンネルルーム向けのより具体的なオーバーライドのままです。
アクティブなツールポリシーの下でメッセージツールを利用できない場合、OpenClaw は応答を黙って抑制するのではなく、自動の表示返信にフォールバックします。
`openclaw doctor` はこの不一致について警告します。
これは、ほとんどの潜伏モードのターンでモデルに `NO_REPLY` と答えさせる古いパターンを置き換えます。ツール専用モードでは、表示上何もしないとは、単に message ツールを呼び出さないことを意味します。
ダイレクトチャットやその他のソースターンに対して同じツールのみの表示返信動作をグローバルに適用するには、`messages.visibleReplies: "message_tool"` を使います。`messages.groupChat.visibleReplies` は、グループ/チャンネルルーム向けのより具体的なオーバーライドとして残ります。
ツール専用モードでエージェントが作業している間も、入力中インジケーターは送信されます。これらのターンでは、エージェントが message ツールを呼び出すかどうかを決める前に通常のアシスタントメッセージテキストが存在しない可能性があるため、デフォルトのグループ入力中モードは "message" から "instant" にアップグレードされます。明示的な入力中モード設定がある場合は、引き続きそちらが優先されます。
これは、ほとんどの待機モードのターンでモデルに `NO_REPLY` と回答させる古いパターンを置き換えます。ツールのみモードでは、表示されることを何もしないとは、単にメッセージツールを呼び出さないことを意味します。
グループ/チャンネルルームで従来の自動最終返信に戻すには:
エージェントがツールのみモードで作業している間も、入力中インジケーターは送信されます。これらのターンでは、エージェントがメッセージツールを呼び出すかどうかを決める前に通常のアシスタントメッセージ本文が存在しない場合があるため、デフォルトのグループ入力モードは "message" から "instant" にアップグレードされます。明示的な入力モード設定は引き続き優先されます。
グループ/チャンネルルームで従来の自動最終返信を復元するには:
```json5
{
@ -68,9 +71,9 @@ otherwise -> reply
}
```
ファイルが保存されると、Gateway は `messages` 設定をホットリロードします。デプロイでファイル監視または設定リロードが無効になっている場合のみ再起動してください。
Gateway は、ファイル保存後に `messages` 設定をホットリロードします。デプロイでファイル監視または設定リロードが無効になっている場合にのみ再起動してください。
すべてのソースチャットで、表示される出力を message ツール経由にするには:
すべてのソースチャットで、表示出力をメッセージツール経由にする必要がある場合:
```json5
{
@ -80,70 +83,70 @@ otherwise -> reply
}
```
ネイティブスラッシュコマンド（Discord、Telegram、およびネイティブコマンド対応のその他のサーフェス）は `visibleReplies: "message_tool"` をバイパスし、チャンネルネイティブのコマンド UI が期待する応答を得られるように、常に表示される形で返信します。これは検証済みのネイティブコマンドターンにのみ適用されます。テキストとして入力された `/...` コマンドや通常のチャットターンは、引き続き設定済みのグループデフォルトに従います。
ネイティブスラッシュコマンド（Discord、Telegram、およびネイティブコマンド対応のその他のサーフェス）は `visibleReplies: "message_tool"` をバイパスし、チャンネルネイティブのコマンド UI が期待する応答を受け取れるように常に表示返信します。これは検証済みのネイティブコマンドターンにのみ適用されます。テキスト入力された `/...` コマンドと通常のチャットターンは、引き続き設定済みのグループデフォルトに従います。
## コンテキストの可視性と許可リスト
グループの安全性には 2 つの異なる制御が関係します。
グループの安全性には、2 つの異なる制御が関わります。
- **トリガー承認**: 誰がエージェントをトリガーできるか（`groupPolicy`、`groups`、`groupAllowFrom`、チャンネル固有の許可リスト）。
- **コンテキストの可視性**: どの補足コンテキストをモデルに注入するか（返信テキスト、引用、スレッド履歴、転送メタデータ）。
- **トリガー認可**: エージェントをトリガーできる人（`groupPolicy`、`groups`、`groupAllowFrom`、チャンネル固有の許可リスト）。
- **コンテキストの可視性**: モデルに注入される補足コンテキスト（返信テキスト、引用、スレッド履歴、転送メタデータ）。
デフォルトでは、OpenClaw は通常のチャット動作を優先し、受信したコンテキストをほぼそのまま保持します。つまり、許可リストは主に誰がアクションをトリガーできるかを決めるものであり、引用や履歴スニペットすべてに対する普遍的な編集境界ではありません。
デフォルトでは、OpenClaw は通常のチャット動作を優先し、コンテキストをほぼ受信したまま保持します。つまり、許可リストは主に、すべての引用や履歴スニペットに対する普遍的な墨消し境界ではなく、誰がアクションをトリガーできるかを決定します。
<AccordionGroup>
<Accordion title="現在の動作はチャンネル固有です">
- 一部のチャンネルでは、特定の経路で補足コンテキストに対して送信者ベースのフィルタリングをすでに適用しています（例: Slack スレッドのシード、Matrix の返信/スレッド検索）。
- 他のチャンネルでは、引用/返信/転送コンテキストを受信したまま渡します。
- 一部のチャンネルでは、特定のパスで補足コンテキストに対して送信者ベースのフィルタリングをすでに適用しています（たとえば Slack のスレッドシード、Matrix の返信/スレッド検索）。
- 他のチャンネルでは、引用/返信/転送コンテキストを受信したまま渡しています。
</Accordion>
<Accordion title="強化の方向性（計画中）">
- `contextVisibility: "all"`（デフォルト）は、現在の受信どおりの動作を維持します。
<Accordion title="強化の方向性（予定）">
- `contextVisibility: "all"`（デフォルト）は、現在の受信時のままの動作を維持します。
- `contextVisibility: "allowlist"` は、補足コンテキストを許可リスト内の送信者にフィルタリングします。
- `contextVisibility: "allowlist_quote"` は `allowlist` に、明示的な引用/返信の例外を 1 つ加えたものです。
- `contextVisibility: "allowlist_quote"` は `allowlist` に加えて、明示的な引用/返信の例外を 1 つ許可します。
この強化モデルがチャンネル全体で一貫して実装されるまでは、サーフェスごとの差異があるものとして扱ってください。
この強化モデルがチャンネル全体で一貫して実装されるまでは、サーフェスごとの差異があることを想定してください。
</Accordion>
</AccordionGroup>
![グループメッセージフロー](/images/groups-flow.svg)
やりたいこと...
目的別の設定:
| 目的 | 設定する内容 |
| -------------------------------------------- | ---------------------------------------------------------- |
| すべてのグループを許可するが @メンション時のみ返信する | `groups: { "*": { requireMention: true } }` |
| すべてのグループ返信を無効化する | `groupPolicy: "disabled"` |
| すべてのグループを許可し、@メンション時のみ返信する | `groups: { "*": { requireMention: true } }` |
| すべてのグループ返信を無効にする | `groupPolicy: "disabled"` |
| 特定のグループのみ | `groups: { "<group-id>": { ... } }`（`"*"` キーなし） |
| グループで自分だけがトリガーできる | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
| グループであなただけがトリガーできる | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
## セッションキー
- グループセッションは `agent:<agentId>:<channel>:group:<id>` セッションキーを使用します（ルーム/チャンネルは `agent:<agentId>:<channel>:channel:<id>` を使用します）。
- Telegram のフォーラムトピックでは、各トピックが独自のセッションを持つように、グループ ID に `:topic:<threadId>` を追加します。
- 直接チャットはメインセッションを使用します（設定されている場合は送信者ごとのセッション）。
- グループセッションは `agent:<agentId>:<channel>:group:<id>` セッションキーを使います（ルーム/チャンネルは `agent:<agentId>:<channel>:channel:<id>` を使います）。
- Telegram フォーラムトピックは、各トピックが独自のセッションを持つように、グループ ID に `:topic:<threadId>` を追加します。
- ダイレクトチャットはメインセッション（または設定されている場合は送信者ごと）を使います。
- Heartbeat はグループセッションではスキップされます。
<a id="pattern-personal-dms-public-groups-single-agent"></a>
## パターン: 個人 DM + 公開グループ（単一エージェント）
はい。「個人」トラフィックが **DM** で、「公開」トラフィックが **グループ** なら、この構成はうまく機能します。
はい。「個人」トラフィックが **DM** で、「公開」トラフィックが **グループ** であれば、これはうまく機能します。
理由: 単一エージェントモードでは、DM は通常 **メイン** セッションキー（`agent:main:main`）に入り、グループは常に **非メイン** セッションキー（`agent:main:<channel>:group:<id>`）を使用します。`mode: "non-main"` でサンドボックス化を有効にすると、それらのグループセッションは設定済みのサンドボックスバックエンドで実行され、メインの DM セッションはホスト上に残ります。バックエンドを選択しない場合、Docker がデフォルトです。
理由: 単一エージェントモードでは、DM は通常 **メイン** セッションキー（`agent:main:main`）に入り、グループは常に **非メイン** セッションキー（`agent:main:<channel>:group:<id>`）を使います。`mode: "non-main"` でサンドボックス化を有効にすると、それらのグループセッションは設定済みのサンドボックスバックエンドで実行され、メインの DM セッションはホスト上に残ります。バックエンドを選択しない場合、Docker がデフォルトのバックエンドです。
これにより、1 つのエージェント「頭脳」（共有ワークスペース + メモリ）で、2 つの実行姿勢を持てます。
これにより、1 つのエージェントの「頭脳」（共有ワークスペース + メモリ）を持ちながら、2 つの実行姿勢を取れます。
- **DM**: 完全なツール（ホスト）
- **DM**: フルツール（ホスト）
- **グループ**: サンドボックス + 制限付きツール
<Note>
本当に分離されたワークスペース/ペルソナ（「個人」と「公開」が絶対に混ざってはいけない）が必要な場合は、2 つ目のエージェント + バインディングを使用してください。[マルチエージェントルーティング](/ja-JP/concepts/multi-agent)を参照してください。
本当に分離されたワークスペース/ペルソナ（「個人」と「公開」が決して混ざらない必要がある）を必要とする場合は、2 つ目のエージェント + バインディングを使います。[マルチエージェントルーティング](/ja-JP/concepts/multi-agent)を参照してください。
</Note>
<Tabs>
<Tab title="DM はホスト上、グループはサンドボックス化">
<Tab title="ホスト上の DM、サンドボックス化されたグループ">
```json5
{
agents: {
@ -167,8 +170,8 @@ otherwise -> reply
}
```
</Tab>
<Tab title="グループには許可リスト内のフォルダーだけを見せる">
「ホストアクセスなし」ではなく「グループはフォルダー X だけを見られる」ようにしたい場合は、`workspaceAccess: "none"` を維持し、許可リストに含めたパスだけをサンドボックスにマウントします。
<Tab title="グループには許可リストに登録されたフォルダーのみが見える">
「ホストアクセスなし」ではなく「グループはフォルダー X だけ見える」ようにしたい場合は、`workspaceAccess: "none"` のままにして、許可リストに登録したパスだけをサンドボックスにマウントします。
```json5
{
@ -201,12 +204,12 @@ otherwise -> reply
## 表示ラベル
- UI ラベルは、利用可能な場合 `displayName` を使用し、`<channel>:<token>` としてフォーマットされます。
- `#room` はルーム/チャンネル用に予約されています。グループチャットは `g-<slug>` を使用します（小文字、スペース -> `-`、`#@+._-` を保持）。
- UI ラベルは、利用可能な場合は `displayName` を使い、`<channel>:<token>` としてフォーマットされます。
- `#room` はルーム/チャンネル用に予約されています。グループチャットは `g-<slug>` を使います（小文字、スペース -> `-`、`#@+._-` は保持）。
## グループポリシー
チャンネルごとに、グループ/ルームメッセージの処理方法を制御します。
チャンネルごとにグループ/ルームメッセージの処理方法を制御します。
```json5
{
@ -261,40 +264,40 @@ otherwise -> reply
<AccordionGroup>
<Accordion title="チャンネルごとの注意事項">
- `groupPolicy` はメンションゲート（@メンションを要求するもの）とは別です。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: `groupAllowFrom` を使用します（フォールバック: 明示的な `allowFrom`）。
- Signal: `groupAllowFrom` は、受信 Signal グループ ID または送信者の電話番号/UUID のどちらにも一致できます。
- DM ペアリング承認（`*-allowFrom` ストアエントリ）は DM アクセスにのみ適用されます。グループ送信者の承認は、グループ許可リストで明示的に行われます。
- Discord: 許可リストは `channels.discord.guilds.<id>.channels` を使用します。
- Slack: 許可リストは `channels.slack.channels` を使用します。
- Matrix: 許可リストは `channels.matrix.groups` を使用します。ルーム ID またはエイリアスを推奨します。参加済みルーム名の検索はベストエフォートで、解決できない名前はランタイムで無視されます。送信者を制限するには `channels.matrix.groupAllowFrom` を使用します。ルームごとの `users` 許可リストもサポートされています。
- グループ DM は別に制御されます（`channels.discord.dm.*`、`channels.slack.dm.*`）。
- Telegram の許可リストは、ユーザー ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）またはユーザー名（`"@alice"` または `"alice"`）に一致できます。プレフィックスは大文字小文字を区別しません。
- `groupPolicy` は、メンションゲート（@メンションを必要とするもの）とは別です。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: `groupAllowFrom` を使います（フォールバック: 明示的な `allowFrom`）。
- Signal: `groupAllowFrom` は、受信した Signal グループ ID または送信者の電話番号/UUID のどちらにも一致できます。
- DM ペアリング承認（`*-allowFrom` ストアエントリ）は DM アクセスにのみ適用されます。グループ送信者の認可は、グループ許可リストに対して明示的なままです。
- Discord: 許可リストは `channels.discord.guilds.<id>.channels` を使います。
- Slack: 許可リストは `channels.slack.channels` を使います。
- Matrix: 許可リストは `channels.matrix.groups` を使います。ルーム ID またはエイリアスを推奨します。参加済みルーム名の検索はベストエフォートであり、解決できない名前は実行時に無視されます。送信者を制限するには `channels.matrix.groupAllowFrom` を使います。ルームごとの `users` 許可リストもサポートされています。
- グループ DM は別途制御されます（`channels.discord.dm.*`、`channels.slack.dm.*`）。
- Telegram の許可リストは、ユーザー ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）またはユーザー名（`"@alice"` または `"alice"`）に一致できます。プレフィックスは大文字と小文字を区別しません。
- デフォルトは `groupPolicy: "allowlist"` です。グループ許可リストが空の場合、グループメッセージはブロックされます。
- ランタイム安全性: プロバイダーブロックが完全に存在しない場合（`channels.<provider>` がない場合）、グループポリシーは `channels.defaults.groupPolicy` を継承するのではなく、フェイルクローズモード（通常は `allowlist`）にフォールバックします。
- 実行時の安全性: provider ブロックが完全に存在しない場合（`channels.<provider>` がない場合）、グループポリシーは `channels.defaults.groupPolicy` を継承するのではなく、フェイルクローズモード（通常は `allowlist`）にフォールバックします。
</Accordion>
</AccordionGroup>
簡単なメンタルモデル（グループメッセージの評価順序）:
簡単なメンタルモデル（グループメッセージの評価順）:
<Steps>
<Step title="groupPolicy">
`groupPolicy`（open/disabled/allowlist）。
`groupPolicy` (open/disabled/allowlist)。
</Step>
<Step title="グループ許可リスト">
グループ許可リスト（`*.groups`、`*.groupAllowFrom`、チャンネル固有の許可リスト）。
グループ許可リスト (`*.groups`、`*.groupAllowFrom`、チャンネル固有の許可リスト)。
</Step>
<Step title="メンションゲート">
メンションゲート（`requireMention`、`/activation`）。
<Step title="メンションゲーティング">
メンションゲーティング (`requireMention`、`/activation`)。
</Step>
</Steps>
## メンションゲート（デフォルト）
## メンションゲーティング (デフォルト)
グループメッセージは、グループごとに上書きされない限りメンションを必要とします。デフォルトは各サブシステムの `*.groups."*"` 配下にあります。
グループメッセージは、グループごとに上書きされていない限りメンションが必要です。デフォルトは各サブシステムの `*.groups."*"` の下にあります。
ボットメッセージへの返信は、チャンネルが返信メタデータに対応している場合、暗黙的なメンションとして扱われます。ボットメッセージの引用も、引用メタデータを公開するチャンネルでは暗黙的なメンションとして扱われる場合があります。現在の組み込みケースには、Telegram、WhatsApp、Slack、Discord、Microsoft Teams、ZaloUser が含まれます。
ボットメッセージへの返信は、チャンネルが返信メタデータをサポートしている場合、暗黙的なメンションとして扱われます。ボットメッセージの引用も、引用メタデータを公開するチャンネルでは暗黙的なメンションとして扱われる場合があります。現在の組み込みケースには Telegram、WhatsApp、Slack、Discord、Microsoft Teams、ZaloUser が含まれます。
```json5
{
@ -334,44 +337,44 @@ otherwise -> reply
<AccordionGroup>
<Accordion title="メンションゲーティングのメモ">
- `mentionPatterns` は大文字小文字を区別しない安全な正規表現パターンです。無効なパターンと安全でないネストした反復形式は無視されます。
- `mentionPatterns` は大文字小文字を区別しない安全な正規表現パターンです。不正なパターンや安全でない入れ子の繰り返し形式は無視されます。
- 明示的なメンションを提供するサーフェスは引き続き通過します。パターンはフォールバックです。
- エージェントごとのオーバーライド: `agents.list[].groupChat.mentionPatterns`（複数のエージェントがグループを共有する場合に便利です）。
- メンションゲーティングは、メンション検出が可能な場合（ネイティブメンションまたは `mentionPatterns` が設定されている場合）にのみ適用されます。
- グループまたは送信者を許可リストに入れても、メンションゲーティングは無効になりません。すべてのメッセージでトリガーする必要がある場合は、そのグループの `requireMention` を `false` に設定します。
- グループチャットのプロンプトコンテキストは、解決済みのサイレント返信指示を毎ターン保持します。ワークスペースファイルで `NO_REPLY` の仕組みを重複させるべきではありません。
- サイレント返信が許可されているグループでは、クリーンな空のモデルターンまたは推論のみのモデルターンは、`NO_REPLY` と同等のサイレントとして扱われます。ダイレクトチャットでは、ダイレクトのサイレント返信が明示的に許可されている場合のみ同じ扱いになります。それ以外の場合、空の返信は失敗したエージェントターンのままです。
- Discord のデフォルトは `channels.discord.guilds."*"` にあります（ギルド/チャンネルごとにオーバーライド可能）。
- グループ履歴コンテキストはチャンネルをまたいで一貫してラップされ、**保留中のみ**です（メンションゲーティングによってスキップされたメッセージ）。グローバルデフォルトには `messages.groupChat.historyLimit` を使用し、オーバーライドには `channels.<channel>.historyLimit`（または `channels.<channel>.accounts.*.historyLimit`）を使用します。無効にするには `0` を設定します。
- エージェントごとの上書き: `agents.list[].groupChat.mentionPatterns` (複数のエージェントがグループを共有する場合に便利です)。
- メンションゲーティングは、メンション検出が可能な場合 (ネイティブメンション、または `mentionPatterns` が設定されている場合) にのみ適用されます。
- グループまたは送信者を許可リストに追加しても、メンションゲーティングは無効になりません。すべてのメッセージでトリガーする必要がある場合は、そのグループの `requireMention` を `false` に設定してください。
- グループチャットのプロンプトコンテキストは、各ターンで解決済みのサイレント返信指示を持ちます。ワークスペースファイルで `NO_REPLY` の仕組みを重複させないでください。
- サイレント返信が許可されているグループでは、クリーンな空のモデルターンまたは推論のみのモデルターンは、`NO_REPLY` と同等のサイレントとして扱われます。ダイレクトチャットでも、ダイレクトのサイレント返信が明示的に許可されている場合にのみ同じ扱いになります。それ以外の場合、空の返信は失敗したエージェントターンのままです。
- Discord のデフォルトは `channels.discord.guilds."*"` にあります (ギルド/チャンネルごとに上書き可能)。
- グループ履歴コンテキストはチャンネル全体で一律にラップされ、**保留中のみ** です (メンションゲーティングによりスキップされたメッセージ)。グローバルデフォルトには `messages.groupChat.historyLimit` を使用し、上書きには `channels.<channel>.historyLimit` (または `channels.<channel>.accounts.*.historyLimit`) を使用します。無効にするには `0` を設定します。
</Accordion>
</AccordionGroup>
## グループ/チャンネルのツール制限（任意）
## グループ/チャンネルのツール制限 (任意)
一部のチャンネル設定では、**特定のグループ/ルーム/チャンネル内**で利用できるツールを制限できます。
一部のチャンネル設定では、**特定のグループ/ルーム/チャンネル内** で利用できるツールを制限できます。
- `tools`: グループ全体でツールを許可/拒否します。
- `toolsBySender`: グループ内の送信者ごとのオーバーライドです。明示的なキープレフィックスを使用します: `id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`、および `"*"` ワイルドカード。従来のプレフィックスなしキーも引き続き受け付けられ、`id:` としてのみ照合されます。
- `tools`: グループ全体のツールを許可/拒否します。
- `toolsBySender`: グループ内の送信者ごとの上書きです。明示的なキープレフィックスを使用します: `id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`、および `"*"` ワイルドカード。従来のプレフィックスなしキーも引き続き受け付けられ、`id:` としてのみ照合されます。
解決順序（最も具体的なものが優先されます）:
解決順序 (最も具体的なものが優先):
<Steps>
<Step title="グループ toolsBySender">
グループ/チャンネルの `toolsBySender` の一致。
グループ/チャンネルの `toolsBySender` 照合。
</Step>
<Step title="グループ tools">
グループ/チャンネルの `tools`。
</Step>
<Step title="デフォルト toolsBySender">
デフォルト（`"*"`）の `toolsBySender` の一致。
デフォルト (`"*"`) の `toolsBySender` 照合。
</Step>
<Step title="デフォルト tools">
デフォルト（`"*"`）の `tools`。
デフォルト (`"*"`) の `tools`。
</Step>
</Steps>
例（Telegram）:
例 (Telegram):
```json5
{
@ -392,18 +395,18 @@ otherwise -> reply
```
<Note>
グループ/チャンネルのツール制限は、グローバル/エージェントのツールポリシーに追加して適用されます（拒否は引き続き優先されます）。一部のチャンネルでは、ルーム/チャンネルに異なるネストを使用します（例: Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
グループ/チャンネルのツール制限は、グローバル/エージェントのツールポリシーに加えて適用されます (拒否は引き続き優先されます)。一部のチャンネルでは、ルーム/チャンネルに異なるネストを使用します (例: Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`)。
</Note>
## グループ許可リスト
`channels.whatsapp.groups`、`channels.telegram.groups`、または `channels.imessage.groups` が設定されている場合、キーはグループ許可リストとして機能します。デフォルトのメンション動作を設定しつつすべてのグループを許可するには、`"*"` を使用します。
`channels.whatsapp.groups`、`channels.telegram.groups`、または `channels.imessage.groups` が設定されている場合、キーはグループ許可リストとして機能します。デフォルトのメンション動作を設定しながらすべてのグループを許可するには、`"*"` を使用します。
<Warning>
よくある混同: DM ペアリング承認はグループ認可と同じではありません。DM ペアリングに対応するチャンネルでは、ペアリングストアが解除するのは DM のみです。グループコマンドには、`groupAllowFrom` やそのチャンネルのドキュメント化された設定フォールバックなど、設定許可リストによる明示的なグループ送信者認可が引き続き必要です。
よくある混同: DM ペアリング承認はグループ認可と同じではありません。DM ペアリングをサポートするチャンネルでは、ペアリングストアが解除するのは DM のみです。グループコマンドには、`groupAllowFrom` やそのチャンネルで文書化された設定フォールバックなど、設定許可リストによる明示的なグループ送信者認可が引き続き必要です。
</Warning>
一般的な意図（コピー/貼り付け）:
一般的な目的 (コピー/貼り付け):
<Tabs>
<Tab title="すべてのグループ返信を無効にする">
@ -413,7 +416,7 @@ otherwise -> reply
}
```
</Tab>
<Tab title="特定のグループのみ許可する（WhatsApp）">
<Tab title="特定のグループのみ許可する (WhatsApp)">
```json5
{
channels: {
@ -438,7 +441,7 @@ otherwise -> reply
}
```
</Tab>
<Tab title="所有者のみのトリガー（WhatsApp）">
<Tab title="オーナーのみのトリガー (WhatsApp)">
```json5
{
channels: {
@ -453,44 +456,44 @@ otherwise -> reply
</Tab>
</Tabs>
## 有効化（所有者のみ）
## 有効化 (オーナーのみ)
グループ所有者は、グループごとの有効化を切り替えられます。
グループオーナーは、グループごとの有効化を切り替えられます。
- `/activation mention`
- `/activation always`
所有者は `channels.whatsapp.allowFrom`（未設定の場合はボット自身の E.164）によって決定されます。コマンドは単独のメッセージとして送信します。他のサーフェスは現在 `/activation` を無視します。
オーナーは `channels.whatsapp.allowFrom` (未設定の場合はボット自身の E.164) によって決定されます。コマンドは単独のメッセージとして送信してください。現在、他のサーフェスは `/activation` を無視します。
## コンテキストフィールド
グループの受信ペイロードは次を設定します。
- `ChatType=group`
- `GroupSubject`（既知の場合）
- `GroupMembers`（既知の場合）
- `WasMentioned`（メンションゲーティング結果）
- `GroupSubject` (既知の場合)
- `GroupMembers` (既知の場合)
- `WasMentioned` (メンションゲーティングの結果)
- Telegram フォーラムトピックには `MessageThreadId` と `IsForum` も含まれます。
チャンネル固有のメモ:
- BlueBubbles は、`GroupMembers` を設定する前に、名前のない macOS グループ参加者をローカルの連絡先データベースから任意で補強できます。これはデフォルトでオフであり、通常のグループゲーティングに通過した後にのみ実行されます。
- BlueBubbles は、`GroupMembers` に入力する前に、名前のない macOS グループ参加者をローカルの連絡先データベースから任意で補強できます。これはデフォルトではオフで、通常のグループゲーティングが通過した後にのみ実行されます。
エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループの導入が含まれます。これにより、モデルに対して、人間のように応答すること、Markdown テーブルを避けること、空行を最小限にして通常のチャット間隔に従うこと、リテラルの `\n` シーケンスを入力しないことを思い出させます。チャンネル由来のグループ名と参加者ラベルは、インラインのシステム指示ではなく、フェンス付きの信頼されていないメタデータとしてレンダリングされます。
エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループのイントロが含まれます。これはモデルに、人間のように応答し、Markdown テーブルを避け、空行を最小限にして通常のチャットの間隔に従い、リテラルの `\n` シーケンスを入力しないよう促します。チャンネル由来のグループ名と参加者ラベルは、インラインのシステム指示ではなく、フェンス付きの信頼されていないメタデータとしてレンダリングされます。
## iMessage の詳細
- ルーティングまたは許可リスト登録には `chat_id:<id>` を優先します。
- ルーティングまたは許可リスト追加では `chat_id:<id>` を優先してください。
- チャット一覧: `imsg chats --limit 20`。
- グループ返信は常に同じ `chat_id` に戻ります。
## WhatsApp システムプロンプト
グループとダイレクトのプロンプト解決、ワイルドカード動作、アカウントオーバーライドのセマンティクスを含む、標準的な WhatsApp システムプロンプトルールについては [WhatsApp](/ja-JP/channels/whatsapp#system-prompts) を参照してください。
グループおよびダイレクトプロンプトの解決、ワイルドカード動作、アカウント上書きセマンティクスを含む、正規の WhatsApp システムプロンプトルールについては [WhatsApp](/ja-JP/channels/whatsapp#system-prompts) を参照してください。
## WhatsApp の詳細
WhatsApp のみの動作（履歴注入、メンション処理の詳細）については、[グループメッセージ](/ja-JP/channels/group-messages) を参照してください。
WhatsApp のみの動作 (履歴注入、メンション処理の詳細) については [グループメッセージ](/ja-JP/channels/group-messages) を参照してください。
## 関連

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

@ -1,75 +1,75 @@
---
read_when:
- CI ジョブが実行された理由、または実行されなかった理由を理解する必要がある
- CI ジョブが実行された理由、または実行されなかった理由を把握する必要がある
- 失敗している GitHub Actions チェックをデバッグしています
- リリース検証の実行または再実行を調整しています
summary: CI ジョブグラフ、スコープゲート、リリース包括、ローカルコマンド相当
summary: CI ジョブグラフ、スコープゲート、リリース包括項目、およびローカルコマンド相当
title: CI パイプライン
x-i18n:
generated_at: "2026-04-30T18:38:38Z"
generated_at: "2026-05-01T05:00:31Z"
model: gpt-5.5
provider: openai
source_hash: a24afc27606ac7f4e9ead89acdd319bffa23336610f8a6cd8b576ea1a5b233dd
source_hash: aea06f9f336f9a478a284473b5c5f38730b87837b1acb0390161bf2c455f6c41
source_path: ci.md
workflow: 16
---
OpenClaw CI は `main` への各プッシュとすべてのプルリクエストで実行されます。`preflight` ジョブは差分を分類し、関係のない領域だけが変更された場合は高コストなレーンを無効にします。手動の `workflow_dispatch` 実行は、意図的にスマートスコープをバイパスし、リリース候補と広範な検証のためにグラフ全体へ展開します。Android レーンは `include_android` を通じてオプトインのままです。リリース専用の Plugin カバレッジは別の [`Plugin Prerelease`](#plugin-prerelease) ワークフローにあり、[`Full Release Validation`](#full-release-validation) または明示的な手動ディスパッチからのみ実行されます。
OpenClaw CI は `main` へのすべての push とすべての pull request で実行されます。`preflight` ジョブは diff を分類し、関係のない領域だけが変更された場合は高コストなレーンを無効にします。手動の `workflow_dispatch` 実行は意図的にスマートスコープをバイパスし、リリース候補と広範な検証のためにグラフ全体へ展開します。Android レーンは `include_android` によるオプトインのままです。リリース専用の Plugin カバレッジは別の [`Plugin Prerelease`](#plugin-prerelease) ワークフローにあり、[`Full Release Validation`](#full-release-validation) または明示的な手動ディスパッチからのみ実行されます。
## パイプライン概要
| ジョブ | 目的 | 実行タイミング |
| -------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------- |
| `preflight` | docs のみの変更、変更スコープ、変更された拡張、CI マニフェストの構築を検出 | 非ドラフトのプッシュと PR で常時 |
| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | 非ドラフトのプッシュと PR で常時 |
| `security-dependency-audit` | npm アドバイザリに対する、依存関係なしの本番ロックファイル監査 | 非ドラフトのプッシュと PR で常時 |
| `security-fast` | 高速セキュリティジョブの必須集約 | 非ドラフトのプッシュと PR で常時 |
| `check-dependencies` | 本番 Knip の依存関係のみのパスと、未使用ファイル許可リストガード | Node 関連の変更 |
| `build-artifacts` | `dist/`、Control UI、ビルド済み成果物チェック、再利用可能な下流成果物をビルド | Node 関連の変更 |
| `checks-fast-core` | バンドル/Plugin 契約/プロトコルチェックなどの高速 Linux 正当性レーン | Node 関連の変更 |
| `checks-fast-contracts-channels` | 安定した集約チェック結果を持つ、シャード化されたチャンネル契約チェック | Node 関連の変更 |
| `checks-node-core-test` | チャンネル、バンドル、契約、拡張レーンを除く Core Node テストシャード | Node 関連の変更 |
| `check` | 本番型、lint、ガード、テスト型、厳格な smoke の、シャード化された主要ローカルゲート相当 | Node 関連の変更 |
| `check-additional` | アーキテクチャ、境界、拡張サーフェスガード、パッケージ境界、gateway-watch シャード | Node 関連の変更 |
| `build-smoke` | ビルド済み CLI の smoke テストと起動時メモリ smoke | Node 関連の変更 |
| `checks` | ビルド済み成果物チャンネルテストの検証 | Node 関連の変更 |
| `checks-node-compat-node22` | Node 22 互換性ビルドと smoke レーン | リリース用の手動 CI ディスパッチ |
| `check-docs` | Docs のフォーマット、lint、壊れたリンクのチェック | Docs が変更された場合 |
| `skills-python` | Python バックの Skills 用 Ruff + pytest | Python Skills 関連の変更 |
| `checks-windows` | Windows 固有のプロセス/パステストと、共有ランタイム import specifier の回帰 | Windows 関連の変更 |
| `macos-node` | 共有ビルド済み成果物を使う macOS TypeScript テストレーン | macOS 関連の変更 |
| `macos-swift` | macOS アプリの Swift lint、ビルド、テスト | macOS 関連の変更 |
| `android` | 両方のフレーバーの Android ユニットテストと、1 つの debug APK ビルド | Android 関連の変更 |
| `test-performance-agent` | 信頼済みアクティビティ後の日次 Codex 低速テスト最適化 | Main CI 成功または手動ディスパッチ |
| ジョブ | 目的 | 実行タイミング |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | docs のみの変更、変更されたスコープ、変更された extensions を検出し、CI マニフェストを構築する | draft でない push と PR では常に |
| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | draft でない push と PR では常に |
| `security-dependency-audit` | npm advisories に対する、依存関係なしの本番 lockfile 監査 | draft でない push と PR では常に |
| `security-fast` | 高速セキュリティジョブの必須集約 | draft でない push と PR では常に |
| `check-dependencies` | 本番 Knip 依存関係のみのパスと未使用ファイル許可リストガード | Node 関連の変更 |
| `build-artifacts` | `dist/`、Control UI、ビルド済みアーティファクトチェック、再利用可能な下流アーティファクトをビルド | Node 関連の変更 |
| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速 Linux 正当性レーン | Node 関連の変更 |
| `checks-fast-contracts-channels` | 安定した集約チェック結果を伴う、シャード化されたチャンネル契約チェック | Node 関連の変更 |
| `checks-node-core-test` | channel、bundled、contract、extension レーンを除く Core Node テストシャード | Node 関連の変更 |
| `check` | シャード化されたメインのローカルゲート相当: 本番型、lint、ガード、テスト型、厳格な smoke | Node 関連の変更 |
| `check-additional` | アーキテクチャ、境界、extension サーフェスガード、package-boundary、gateway-watch シャード | Node 関連の変更 |
| `build-smoke` | ビルド済み CLI smoke テストと起動メモリ smoke | Node 関連の変更 |
| `checks` | ビルド済みアーティファクトのチャンネルテスト用検証 | Node 関連の変更 |
| `checks-node-compat-node22` | Node 22 互換性ビルドと smoke レーン | リリース用の手動 CI ディスパッチ |
| `check-docs` | docs のフォーマット、lint、リンク切れチェック | docs が変更された場合 |
| `skills-python` | Python バックの Skills 向け Ruff + pytest | Python skill 関連の変更 |
| `checks-windows` | Windows 固有の process/path テストと共有ランタイム import specifier 回帰 | Windows 関連の変更 |
| `macos-node` | 共有ビルド済みアーティファクトを使う macOS TypeScript テストレーン | macOS 関連の変更 |
| `macos-swift` | macOS アプリ向け Swift lint、ビルド、テスト | macOS 関連の変更 |
| `android` | 両方の flavor の Android unit test と 1 つの debug APK ビルド | Android 関連の変更 |
| `test-performance-agent` | 信頼済みアクティビティ後の日次 Codex 低速テスト最適化 | main CI 成功または手動ディスパッチ |
## フェイルファスト順序
1. `preflight` は、どのレーンがそもそも存在するかを決定します。`docs-scope` と `changed-scope` のロジックはこのジョブ内のステップであり、独立したジョブではありません。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、`skills-python` は、より重い成果物ジョブやプラットフォームマトリックスジョブを待たずにすばやく失敗します。
3. `build-artifacts` は高速 Linux レーンと重なって実行されるため、共有ビルドの準備ができ次第、下流のコンシューマーを開始できます。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、`skills-python` は、より重いアーティファクトとプラットフォームのマトリックスジョブを待たずにすばやく失敗します。
3. `build-artifacts` は高速 Linux レーンと重なって実行されるため、共有ビルドの準備ができ次第、下流の利用側が開始できます。
4. その後、より重いプラットフォームとランタイムのレーンが展開されます: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、`android`。
同じ PR または `main` ref に新しいプッシュが入ると、GitHub は置き換えられたジョブを `cancelled` としてマークすることがあります。同じ ref の最新実行も失敗していない限り、これは CI ノイズとして扱ってください。集約シャードチェックは `!cancelled() && always()` を使用するため、通常のシャード失敗は引き続き報告しますが、ワークフロー全体がすでに置き換えられた後にはキューに入りません。自動 CI の concurrency キーはバージョン付き (`CI-v7-*`) なので、古いキューグループ内の GitHub 側ゾンビが新しい main 実行を無期限にブロックすることはありません。手動のフルスイート実行は `CI-manual-v1-*` を使用し、進行中の実行をキャンセルしません。
同じ PR または `main` ref に新しい push が入ると、GitHub は置き換えられたジョブを `cancelled` としてマークする場合があります。同じ ref の最新実行も失敗していない限り、これは CI ノイズとして扱います。集約シャードチェックは `!cancelled() && always()` を使うため、通常のシャード失敗は引き続き報告しますが、ワークフロー全体がすでに置き換えられた後にはキューに入りません。自動 CI concurrency key はバージョン付き (`CI-v7-*`) なので、古いキューグループに残った GitHub 側のゾンビが新しい main 実行を無期限にブロックすることはありません。手動フルスイート実行は `CI-manual-v1-*` を使い、進行中の実行をキャンセルしません。
## スコープとルーティング
スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` のユニットテストでカバーされています。手動ディスパッチは changed-scope 検出をスキップし、すべてのスコープ対象領域が変更されたかのように preflight マニフェストを動作させます。
スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` の unit test でカバーされています。手動ディスパッチは changed-scope 検出をスキップし、すべてのスコープ領域が変更されたかのように preflight マニフェストを動作させます。
- **CI ワークフロー編集** は Node CI グラフとワークフロー lint を検証しますが、それだけで Windows、Android、macOS ネイティブビルドを強制することはありません。これらのプラットフォームレーンは、プラットフォームソースの変更にスコープされたままです。
- **CI ルーティングのみの編集、選択された低コストな core-test fixture 編集、狭い Plugin 契約ヘルパー/テストルーティング編集** は、高速な Node のみのマニフェストパスを使用します: `preflight`、セキュリティ、単一の `checks-fast-core` タスクです。そのパスは、変更が高速タスクが直接実行するルーティングまたはヘルパーサーフェスに限定される場合、ビルド成果物、Node 22 互換性、チャンネル契約、完全な Core シャード、バンドル Plugin シャード、追加ガードマトリックスをスキップします。
- **Windows Node チェック** は、Windows 固有のプロセス/パスラッパー、npm/pnpm/UI runner ヘルパー、パッケージマネージャー設定、そのレーンを実行する CI ワークフローサーフェスにスコープされます。関係のないソース、Plugin、install-smoke、テストのみの変更は Linux Node レーンに残ります。
- **CI workflow edits** は Node CI グラフとワークフロー lint を検証しますが、それ自体では Windows、Android、macOS のネイティブビルドを強制しません。これらのプラットフォームレーンはプラットフォームソース変更にスコープされたままです。
- **CI routing-only edits, selected cheap core-test fixture edits, and narrow plugin contract helper/test-routing edits** は、高速な Node のみのマニフェストパスを使います: `preflight`、security、単一の `checks-fast-core` タスクです。このパスは、変更がその高速タスクで直接実行されるルーティングまたは helper サーフェスに限定される場合、ビルドアーティファクト、Node 22 互換性、チャンネル契約、完全な core シャード、bundled-plugin シャード、追加ガードマトリックスをスキップします。
- **Windows Node checks** は、Windows 固有の process/path wrapper、npm/pnpm/UI runner helper、package manager config、そのレーンを実行する CI workflow サーフェスにスコープされます。無関係なソース、Plugin、install-smoke、test-only の変更は Linux Node レーンに残ります。
最も遅い Node テストファミリーは、各ジョブを小さく保ちつつ runner を過剰予約しないように分割またはバランス調整されています。チャンネル契約は 3 つの重み付きシャードとして実行され、小さな Core ユニットレーンはペアにされ、auto-reply は 4 つのバランス済みワーカーとして実行されます（reply サブツリーは agent-runner、dispatch、commands/state-routing シャードに分割されます）。また、agentic Gateway/Plugin 設定は、ビルド済み成果物を待つ代わりに、既存のソースのみの agentic Node ジョブ全体に分散されます。広範なブラウザー、QA、メディア、その他の Plugin テストは、共有 Plugin キャッチオールではなく専用の Vitest 設定を使用します。include-pattern シャードは CI シャード名を使ってタイミングエントリを記録するため、`.artifacts/vitest-shard-timings.json` は設定全体とフィルター済みシャードを区別できます。`check-additional` はパッケージ境界の compile/canary 作業をまとめ、runtime topology アーキテクチャを gateway watch カバレッジから分離します。boundary guard シャードは、小さな独立ガードを 1 つのジョブ内で同時に実行します。Gateway watch、チャンネルテスト、Core support-boundary シャードは、`dist/` と `dist-runtime/` がすでにビルドされた後に `build-artifacts` 内で同時に実行されます。
最も遅い Node テストファミリーは、各ジョブが小さく保たれ、runner を過剰に確保しないように分割またはバランス調整されています。チャンネル契約は 3 つの重み付きシャードとして実行され、小さな core unit レーンはペア化され、auto-reply は 4 つのバランスされた worker として実行されます（reply サブツリーは agent-runner、dispatch、commands/state-routing シャードに分割）。agentic gateway/plugin config は、ビルド済みアーティファクトを待つ代わりに、既存の source-only agentic Node ジョブ全体に分散されます。広範な browser、QA、media、その他の Plugin テストは、共有 Plugin catch-all ではなく専用の Vitest config を使います。include-pattern シャードは CI シャード名を使ってタイミングエントリを記録するため、`.artifacts/vitest-shard-timings.json` は config 全体とフィルター済みシャードを区別できます。`check-additional` は package-boundary の compile/canary 作業をまとめ、runtime topology アーキテクチャを gateway watch カバレッジから分離します。boundary guard シャードは、小さな独立ガードを 1 つのジョブ内で並行実行します。Gateway watch、チャンネルテスト、core support-boundary シャードは、`dist/` と `dist-runtime/` がすでにビルドされた後に `build-artifacts` 内で並行実行されます。
Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party フレーバーには個別の source set や manifest はありません。そのユニットテストレーンは、SMS/call-log BuildConfig フラグ付きでフレーバーを引き続きコンパイルしつつ、Android 関連の各プッシュで重複した debug APK packaging ジョブを避けます。
Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party flavor には個別の source set や manifest はありません。その unit-test レーンは SMS/call-log BuildConfig フラグ付きで flavor を引き続きコンパイルしつつ、Android 関連の各 push で重複した debug APK packaging ジョブを避けます。
`check-dependencies` シャードは `pnpm deadcode:dependencies`（最新の Knip バージョンに固定された本番 Knip の依存関係のみのパスで、`dlx` インストールでは pnpm の最小リリース経過期間が無効）と `pnpm deadcode:unused-files` を実行します。後者は Knip の本番未使用ファイル検出結果を `scripts/deadcode-unused-files.allowlist.mjs` と比較します。未使用ファイルガードは、PR が新しい未レビューの未使用ファイルを追加した場合、または古い許可リストエントリを残した場合に失敗します。一方で、Knip が静的に解決できない意図的な dynamic Plugin、生成物、ビルド、live-test、package bridge サーフェスは保持します。
`check-dependencies` シャードは `pnpm deadcode:dependencies`（最新の Knip バージョンに固定された本番 Knip 依存関係のみのパスで、`dlx` install では pnpm の minimum release age を無効化）と `pnpm deadcode:unused-files` を実行します。後者は Knip の本番未使用ファイル検出結果を `scripts/deadcode-unused-files.allowlist.mjs` と比較します。unused-file guard は、意図的な動的 Plugin、生成物、ビルド、live-test、package bridge サーフェスなど Knip が静的に解決できないものを保持しながら、PR が新しい未レビューの未使用ファイルを追加した場合や古い許可リストエントリを残した場合に失敗します。
## 手動ディスパッチ
手動 CI ディスパッチは通常の CI と同じジョブグラフを実行しますが、Android 以外のすべてのスコープ対象レーンを強制的に有効にします: Linux Node シャード、バンドル Plugin シャード、チャンネル契約、Node 22 互換性、`check`、`check-additional`、build smoke、docs チェック、Python Skills、Windows、macOS、Control UI i18n です。スタンドアロンの手動 CI ディスパッチは `include_android=true` の場合のみ Android を実行します。フルリリースの包括ワークフローは `include_android=true` を渡して Android を有効にします。Plugin prerelease static checks、リリース専用の `agentic-plugins` シャード、完全な extension batch sweep、Plugin prerelease Docker レーンは CI から除外されます。Docker prerelease スイートは、`Full Release Validation` が release-validation gate を有効にして別の `Plugin Prerelease` ワークフローをディスパッチした場合にのみ実行されます。
手動 CI ディスパッチは通常の CI と同じジョブグラフを実行しますが、Android 以外のすべてのスコープ付きレーンを強制的に有効にします: Linux Node シャード、bundled-plugin シャード、チャンネル契約、Node 22 互換性、`check`、`check-additional`、build smoke、docs チェック、Python Skills、Windows、macOS、Control UI i18n です。スタンドアロンの手動 CI ディスパッチは `include_android=true` の場合にのみ Android を実行します。フルリリースの umbrella は `include_android=true` を渡して Android を有効にします。Plugin prerelease static チェック、リリース専用の `agentic-plugins` シャード、完全な extension batch sweep、Plugin prerelease Docker レーンは CI から除外されます。Docker prerelease スイートは、`Full Release Validation` が release-validation gate を有効にして別の `Plugin Prerelease` ワークフローをディスパッチした場合にのみ実行されます。
手動実行は一意の concurrency group を使用するため、リリース候補のフルスイートが、同じ ref 上の別のプッシュや PR 実行によってキャンセルされることはありません。任意の `target_ref` 入力により、信頼済みの呼び出し元は、選択されたディスパッチ ref のワークフローファイルを使いながら、ブランチ、タグ、または完全なコミット SHA に対してそのグラフを実行できます。
手動実行は一意の concurrency group を使うため、リリース候補のフルスイートが同じ ref 上の別の push や PR 実行によってキャンセルされることはありません。任意の `target_ref` 入力により、信頼済みの呼び出し元は、選択された dispatch ref のワークフローファイルを使いながら、ブランチ、タグ、または完全な commit SHA に対してそのグラフを実行できます。
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -77,17 +77,17 @@ gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_andro
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
```
## Runners
## ランナー
| ランナー | ジョブ |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`、高速セキュリティジョブと集約（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速プロトコル/コントラクト/バンドル済みチェック、シャード化されたチャンネルコントラクトチェック、lint を除く `check` シャード、`check-additional` シャードと集約、Node テスト集約検証、ドキュメントチェック、Python Skills、workflow-sanity、labeler、auto-response。install-smoke preflight も GitHub ホストの Ubuntu を使うため、Blacksmith マトリクスはより早くキューに入れられる |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、低負荷の Plugin シャード、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types`、`check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node テストシャード、バンドル済み Plugin テストシャード、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（CPU 依存が強く、8 vCPU は節約分よりコストが大きかった）。install-smoke Docker ビルド（32 vCPU は節約分よりキュー時間のコストが大きかった） |
| `ubuntu-24.04` | `preflight`、高速セキュリティジョブと集約（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速プロトコル/契約/同梱チェック、シャード化されたチャンネル契約チェック、lint を除く `check` シャード、`check-additional` シャードと集約、Node テスト集約ベリファイア、ドキュメントチェック、Python Skills、workflow-sanity、labeler、auto-response。install-smoke の preflight も GitHub ホストの Ubuntu を使うため、Blacksmith マトリックスはより早くキューに入れられる |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、軽量な Plugin シャード、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types`、`check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node テストシャード、同梱 Plugin テストシャード、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（8 vCPU は節約できた分よりもコストが大きいほど CPU 依存が強い）。install-smoke Docker ビルド（32-vCPU は節約できた分よりもキュー時間のコストが大きい） |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` では `macos-node`。フォークでは `macos-latest` にフォールバックする |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` では `macos-swift`。フォークでは `macos-latest` にフォールバックする |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`。フォークでは `macos-latest` にフォールバックする |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-swift`。フォークでは `macos-latest` にフォールバックする |
## ローカルでの同等コマンド
@ -117,19 +117,31 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
## 完全リリース検証
`Full Release Validation` は、「リリース前にすべてを実行する」ための手動の包括ワークフローです。ブランチ、タグ、または完全なコミット SHA を受け取り、そのターゲットで手動の `CI` ワークフローをディスパッチし、リリース専用の Plugin/パッケージ/静的/Docker 検証のために `Plugin Prerelease` をディスパッチし、install smoke、package acceptance、Docker リリースパススイート、live/E2E、OpenWebUI、QA Lab parity、Matrix、Telegram レーンのために `OpenClaw Release Checks` をディスパッチします。公開済みパッケージ仕様が指定された場合は、公開後の `NPM Telegram Beta E2E` ワークフローも実行できます。
`Full Release Validation` は、「リリース前にすべてを実行する」ための手動包括ワークフローです。ブランチ、タグ、または完全なコミット SHA を受け取り、その対象で手動 `CI` ワークフローをディスパッチし、リリース専用の Plugin/パッケージ/静的/Docker 証明用に `Plugin Prerelease` をディスパッチし、インストールスモーク、パッケージ受け入れ、Docker リリースパススイート、live/E2E、OpenWebUI、QA Lab パリティ、Matrix、Telegram レーン用に `OpenClaw Release Checks` をディスパッチします。公開済みパッケージ仕様が指定された場合は、公開後の `NPM Telegram Beta E2E` ワークフローも実行できます。
`release_profile` は、リリースチェックへ渡す live/provider の範囲を制御します。
ステージマトリックス、正確なワークフロージョブ名、プロファイルの違い、成果物、
および絞り込んだ再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation)
を参照してください。
- `minimum` は最速の OpenAI/core リリースクリティカルレーンを維持します。
`release_profile` は、リリースチェックに渡される live/provider の範囲を制御します。
手動リリースワークフローのデフォルトは `stable` です。広範な勧告用 provider/media マトリックスを
意図的に実行したい場合にのみ `full` を使ってください。
- `minimum` は最速の OpenAI/core リリース重要レーンに絞ります。
- `stable` は安定版 provider/backend セットを追加します。
- `full` は広範な advisory provider/media マトリクスを実行します。
- `full` は広範な勧告用 provider/media マトリックスを実行します。
包括ワークフローはディスパッチされた子実行 ID を記録し、最後の `Verify full validation` ジョブが現在の子実行の結果を再チェックし、各子実行の最遅ジョブテーブルを追記します。子ワークフローを再実行して成功した場合は、包括結果とタイミング要約を更新するために親の検証ジョブだけを再実行してください。
包括ワークフローはディスパッチした子 run ID を記録し、最後の `Verify full validation` ジョブが現在の子 run の結論を再チェックし、各子 run の最も遅いジョブの表を追記します。子ワークフローを再実行して green になった場合は、包括結果とタイミング要約を更新するため、親のベリファイアジョブだけを再実行してください。
復旧用に、`Full Release Validation` と `OpenClaw Release Checks` はどちらも `rerun_group` を受け付けます。リリース候補には `all`、通常の完全な CI 子だけには `ci`、すべてのリリース子には `release-checks`、より狭いグループには包括ワークフロー上で `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、または `npm-telegram` を使います。これにより、集中修正後の失敗したリリースボックスの再実行を限定できます。
復旧用に、`Full Release Validation` と `OpenClaw Release Checks` はどちらも `rerun_group` を受け取ります。リリース候補には `all`、通常の完全 CI 子だけには `ci`、Plugin prerelease 子だけには `plugin-prerelease`、すべてのリリース子には `release-checks`、またはより狭いグループとして、包括ワークフロー上で `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` を使います。これにより、絞り込んだ修正後に、失敗したリリースボックスの再実行範囲を限定できます。
`OpenClaw Release Checks` は、信頼されたワークフロー ref を使って選択された ref を一度だけ `release-package-under-test` tarball に解決し、そのアーティファクトを live/E2E リリースパス Docker ワークフローと package acceptance シャードの両方へ渡します。これにより、リリースボックス全体でパッケージのバイト列が一貫し、複数の子ジョブで同じ候補を再パックすることを避けられます。
`OpenClaw Release Checks` は、信頼されたワークフロー ref を使って選択された ref を一度だけ `release-package-under-test` tarball に解決し、その成果物を live/E2E リリースパス Docker ワークフローとパッケージ受け入れシャードの両方に渡します。これにより、リリースボックス間でパッケージのバイト列が一貫し、複数の子ジョブで同じ候補を再パッケージすることを避けられます。
`ref=main` かつ `rerun_group=all` の重複した `Full Release Validation` run は、
古い包括ワークフローを置き換えます。親モニターは親がキャンセルされたとき、すでに
ディスパッチ済みの子ワークフローをすべてキャンセルするため、新しい main 検証が
古い 2 時間の release-check run の後ろで待機することはありません。リリースブランチ/タグの
検証と絞り込んだ再実行グループでは `cancel-in-progress: false` を維持します。
## Live と E2E シャード
@ -137,7 +149,7 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
- `native-live-src-agents`
- `native-live-src-gateway-core`
- provider でフィルターされた `native-live-src-gateway-profiles` ジョブ
- provider でフィルタされた `native-live-src-gateway-profiles` ジョブ
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -145,57 +157,57 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- 分割されたメディア audio/video シャードと、provider でフィルターされた music シャード
- 分割されたメディア audio/video シャードと provider でフィルタされた music シャード
これにより、同じファイルカバレッジを保ちながら、遅い live provider の失敗を再実行および診断しやすくなります。集約用の `native-live-extensions-o-z`、`native-live-extensions-media`、`native-live-extensions-media-music` シャード名は、手動の単発再実行でも引き続き有効です。
これにより、同じファイルカバレッジを維持しながら、遅い live provider の失敗を再実行して診断しやすくなります。集約 `native-live-extensions-o-z`、`native-live-extensions-media`、`native-live-extensions-media-music` のシャード名は、手動の一括再実行でも引き続き有効です。
ネイティブ live media シャードは、`Live Media Runner Image` ワークフローでビルドされる `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 内で実行されます。このイメージには `ffmpeg` と `ffprobe` が事前インストールされています。media ジョブはセットアップ前にバイナリを検証するだけです。Docker バックの live スイートは通常の Blacksmith ランナー上に維持してください。コンテナジョブはネストされた Docker テストを起動する場所として不適切です。
ネイティブ live media シャードは、`Live Media Runner Image` ワークフローでビルドされる `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 内で実行されます。このイメージには `ffmpeg` と `ffprobe` が事前インストールされています。media ジョブはセットアップ前にバイナリを検証するだけです。Docker ベースの live スイートは通常の Blacksmith ランナー上に維持してください。コンテナジョブはネストされた Docker テストを起動する場所として適していません。
Docker バックの live model/backend シャードは、選択されたコミットごとに別の共有 `ghcr.io/openclaw/openclaw-live-test:<sha>` イメージを使います。live リリースワークフローはそのイメージを一度だけビルドしてプッシュし、その後 Docker live model、Gateway、CLI backend、ACP bind、Codex harness シャードは `OPENCLAW_SKIP_DOCKER_BUILD=1` で実行されます。これらのシャードがフルソース Docker ターゲットを個別に再ビルドする場合、そのリリース実行は設定ミスであり、重複イメージビルドで実時間を浪費します。
Docker ベースの live model/backend シャードは、選択されたコミットごとに別の共有 `ghcr.io/openclaw/openclaw-live-test:<sha>` イメージを使います。live リリースワークフローはそのイメージを一度だけビルドしてプッシュし、その後 Docker live model、provider シャード化 Gateway、CLI backend、ACP bind、Codex harness シャードが `OPENCLAW_SKIP_DOCKER_BUILD=1` で実行されます。Gateway Docker シャードは、スタックしたコンテナやクリーンアップ経路がリリースチェック予算全体を消費せずに速く失敗するよう、ワークフロージョブタイムアウトより短い明示的なスクリプトレベルの `timeout` 上限を持ちます。これらのシャードが完全なソース Docker ターゲットを個別に再ビルドする場合、そのリリース run は設定ミスであり、重複イメージビルドに実時間を浪費します。
## パッケージ受け入れ
「このインストール可能な OpenClaw パッケージは製品として動作するか」という問いには `Package Acceptance` を使います。これは通常の CI とは異なります。通常の CI はソースツリーを検証しますが、package acceptance はインストールまたは更新後にユーザーが実行するものと同じ Docker E2E ハーネスを通して、単一の tarball を検証します。
「このインストール可能な OpenClaw パッケージは製品として機能するか」という問いには、`Package Acceptance` を使います。これは通常の CI とは異なります。通常の CI はソースツリーを検証しますが、パッケージ受け入れは、インストールまたは更新後にユーザーが実行するものと同じ Docker E2E harness を通じて単一の tarball を検証します。
### ジョブ
1. `resolve_package` は `workflow_ref` をチェックアウトし、1 つのパッケージ候補を解決し、`.artifacts/docker-e2e-package/openclaw-current.tgz` を書き込み、`.artifacts/docker-e2e-package/package-candidate.json` を書き込み、両方を `package-under-test` アーティファクトとしてアップロードし、GitHub ステップ要約にソース、ワークフロー ref、パッケージ ref、バージョン、SHA-256、プロファイルを出力します。
2. `docker_acceptance` は、`ref=workflow_ref` と `package_artifact_name=package-under-test` で `openclaw-live-and-e2e-checks-reusable.yml` を呼び出します。再利用可能ワークフローはそのアーティファクトをダウンロードし、tarball インベントリを検証し、必要に応じて package-digest Docker イメージを準備し、ワークフローチェックアウトをパックする代わりにそのパッケージに対して選択された Docker レーンを実行します。プロファイルが複数の対象 `docker_lanes` を選択する場合、再利用可能ワークフローはパッケージと共有イメージを一度だけ準備し、その後それらのレーンを一意のアーティファクトを持つ並列の対象 Docker ジョブとして展開します。
3. `package_telegram` は任意で `NPM Telegram Beta E2E` を呼び出します。`telegram_mode` が `none` でなく、Package Acceptance が解決したものがある場合は同じ `package-under-test` アーティファクトをインストールします。スタンドアロンの Telegram ディスパッチは、公開済み npm 仕様を引き続きインストールできます。
1. `resolve_package` は `workflow_ref` をチェックアウトし、1 つのパッケージ候補を解決し、`.artifacts/docker-e2e-package/openclaw-current.tgz` を書き込み、`.artifacts/docker-e2e-package/package-candidate.json` を書き込み、両方を `package-under-test` アーティファクトとしてアップロードし、GitHub ステップサマリーにソース、ワークフロー ref、パッケージ ref、バージョン、SHA-256、プロファイルを出力します。
2. `docker_acceptance` は `ref=workflow_ref` と `package_artifact_name=package-under-test` で `openclaw-live-and-e2e-checks-reusable.yml` を呼び出します。再利用可能ワークフローはそのアーティファクトをダウンロードし、tarball インベントリを検証し、必要に応じて package-digest Docker イメージを準備し、ワークフローのチェックアウトをパックする代わりに、そのパッケージに対して選択された Docker レーンを実行します。プロファイルが複数の対象 `docker_lanes` を選択する場合、再利用可能ワークフローはパッケージと共有イメージを一度だけ準備し、それらのレーンを一意のアーティファクトを持つ並列の対象 Docker ジョブとしてファンアウトします。
3. `package_telegram` は任意で `NPM Telegram Beta E2E` を呼び出します。これは `telegram_mode` が `none` でない場合に実行され、Package Acceptance がパッケージを解決した場合は同じ `package-under-test` アーティファクトをインストールします。スタンドアロンの Telegram ディスパッチでは、公開済み npm spec を引き続きインストールできます。
4. `summary` は、パッケージ解決、Docker acceptance、または任意の Telegram レーンが失敗した場合にワークフローを失敗させます。
### 候補ソース
- `source=npm` は `openclaw@beta`、`openclaw@latest`、または `openclaw@2026.4.27-beta.2` のような正確な OpenClaw リリースバージョンのみを受け付けます。公開済みの beta/stable 受け入れにこれを使用します。
- `source=ref` は、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパックします。リゾルバーは OpenClaw のブランチ/タグを取得し、選択したコミットがリポジトリのブランチ履歴またはリリースタグから到達可能であることを検証し、切り離されたワークツリーに依存関係をインストールして、`scripts/package-openclaw-for-docker.mjs` でパックします。
- `source=url` は HTTPS の `.tgz` をダウンロードします。`package_sha256` が必須です。
- `source=artifact` は `artifact_run_id` と `artifact_name` から 1 つの `.tgz` をダウンロードします。`package_sha256` は任意ですが、外部共有アーティファクトには指定するべきです。
- `source=npm` は `openclaw@beta`、`openclaw@latest`、または `openclaw@2026.4.27-beta.2` のような正確な OpenClaw リリースバージョンのみを受け付けます。公開済み beta/stable acceptance にこれを使用します。
- `source=ref` は信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパックします。リゾルバーは OpenClaw ブランチ/タグをフェッチし、選択されたコミットがリポジトリのブランチ履歴またはリリースタグから到達可能であることを検証し、デタッチされたワークツリーで依存関係をインストールし、`scripts/package-openclaw-for-docker.mjs` でパックします。
- `source=url` は HTTPS の `.tgz` をダウンロードします。`package_sha256` は必須です。
- `source=artifact` は `artifact_run_id` と `artifact_name` から 1 つの `.tgz` をダウンロードします。`package_sha256` は任意ですが、外部共有アーティファクトでは指定するべきです。
`workflow_ref` と `package_ref` は分けておきます。`workflow_ref` はテストを実行する信頼済みのワークフロー/ハーネスコードです。`package_ref` は `source=ref` のときにパックされるソースコミットです。これにより、現在のテストハーネスは古いワークフローロジックを実行せずに、古い信頼済みソースコミットを検証できます。
`workflow_ref` と `package_ref` は分けておきます。`workflow_ref` はテストを実行する信頼済みのワークフロー/ハーネスコードです。`package_ref` は `source=ref` の場合にパックされるソースコミットです。これにより、現在のテストハーネスで、古いワークフローロジックを実行せずに、古い信頼済みソースコミットを検証できます。
### スイートプロファイル
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `product` — `package` に加えて `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — OpenWebUI を含む完全な Docker リリースパスチャンク
- `custom` — 正確な `docker_lanes`。`suite_profile=custom` のとき必須
- `custom` — 正確な `docker_lanes`。`suite_profile=custom` の場合に必須
`package` プロファイルはオフライン Plugin カバレッジを使用するため、公開済みパッケージの検証はライブ ClawHub の可用性に左右されません。任意の Telegram レーンは `NPM Telegram Beta E2E` の `package-under-test` アーティファクトを再利用し、公開済み npm 仕様パスはスタンドアロンのディスパッチ用に保持されます。
`package` プロファイルはオフライン Plugin カバレッジを使用するため、公開済みパッケージ検証はライブの ClawHub 可用性に左右されません。任意の Telegram レーンは `NPM Telegram Beta E2E` で `package-under-test` アーティファクトを再利用し、公開済み npm spec パスはスタンドアロンディスパッチ用に保持されます。
リリースチェックは、`source=ref`、`package_ref=<release-ref>`、`workflow_ref=<release workflow ref>`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'`、`telegram_mode=mock-openai` で Package Acceptance を呼び出します。リリースパス Docker チャンクは重複する package/update/plugin レーンをカバーします。Package Acceptance は、同じ解決済みパッケージ tarball に対して、アーティファクトネイティブの bundled-channel 互換性、オフライン Plugin、Telegram の証明を保持します。Cross-OS リリースチェックは引き続き OS 固有のオンボーディング、インストーラー、プラットフォーム挙動をカバーします。package/update の製品検証は Package Acceptance から始めるべきです。Windows の packaged レーンと installer fresh レーンは、インストール済みパッケージが生の絶対 Windows パスから browser-control オーバーライドをインポートできることも検証します。OpenAI cross-OS agent-turn smoke は、設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` をデフォルトとし、そうでない場合は `openai/gpt-5.4-mini` を使用するため、インストールと Gateway の証明は高速かつ決定的に保たれます。
リリースチェックは、`source=ref`、`package_ref=<release-ref>`、`workflow_ref=<release workflow ref>`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'`、`telegram_mode=mock-openai` で Package Acceptance を呼び出します。リリースパス Docker チャンクは、重複する package/update/plugin レーンをカバーします。Package Acceptance は、同じ解決済みパッケージ tarball に対して、アーティファクトネイティブな bundled-channel 互換性、オフライン Plugin、Telegram の証明を保持します。Cross-OS リリースチェックは引き続き OS 固有のオンボーディング、インストーラー、プラットフォーム動作をカバーします。package/update のプロダクト検証は Package Acceptance から始めるべきです。`published-upgrade-survivor` Docker レーンは、1 回の実行につき 1 つの公開済みパッケージベースラインを検証します。Package Acceptance では、解決済みの `package-under-test` tarball が常に候補であり、`published_upgrade_survivor_baseline` が公開済みベースラインを選択します。既定値は `openclaw@latest` です。失敗レーンの再実行コマンドはそのベースラインを保持します。ローカル実行では、`OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` を `openclaw@2026.4.15` のような正確なパッケージに設定できます。公開済みレーンは、焼き込み済みの `openclaw config set` コマンドレシピでベースラインを構成し、その後レシピ手順を `summary.json` に記録します。より広範な以前のバージョンのカバレッジでは、正確な `published_upgrade_survivor_baseline` 値ごとに Package Acceptance をシャードするべきです。Windows の packaged レーンと installer fresh レーンは、インストール済みパッケージが raw の絶対 Windows パスから browser-control override をインポートできることも検証します。OpenAI cross-OS agent-turn smoke は、`OPENCLAW_CROSS_OS_OPENAI_MODEL` が設定されている場合はそれを既定で使用し、それ以外の場合は `openai/gpt-5.4-mini` を使用するため、インストールと Gateway の証明は高速かつ決定的なままです。
### レガシー互換性ウィンドウ
Package Acceptance には、すでに公開済みのパッケージ向けに範囲を限定したレガシー互換性ウィンドウがあります。`2026.4.25` までのパッケージ（`2026.4.25-beta.*` を含む）は、互換性パスを使用できます。
Package Acceptance には、すでに公開済みのパッケージ向けに範囲を限定したレガシー互換性ウィンドウがあります。`2026.4.25-beta.*` を含む `2026.4.25` までのパッケージは、互換性パスを使用できます。
- `dist/postinstall-inventory.json` 内の既知の private QA エントリは、tarball から省略されたファイルを指す場合があります。
- `dist/postinstall-inventory.json` の既知の private QA エントリは、tarball から省略されたファイルを指している場合があります。
- パッケージがそのフラグを公開していない場合、`doctor-switch` は `gateway install --wrapper` 永続化サブケースをスキップする場合があります。
- `update-channel-switch` は、tarball 由来の偽 git fixture から欠落している `pnpm.patchedDependencies` を刈り込む場合があり、永続化された `update.channel` の欠落をログに記録する場合があります。
- Plugin smoke はレガシーの install-record 位置を読み取る場合があり、または marketplace install-record 永続化の欠落を許容する場合があります。
- `plugin-update` は、install record と no-reinstall 挙動が変更されないことを引き続き要求しながら、設定メタデータ移行を許容する場合があります。
- `update-channel-switch` は、tarball 由来の fake git fixture から欠落している `pnpm.patchedDependencies` を刈り込む場合があり、永続化された `update.channel` の欠落をログ出力する場合があります。
- Plugin smoke はレガシーの install-record 場所を読む場合があり、または marketplace install-record 永続化の欠落を許容する場合があります。
- `plugin-update` は、install record と no-reinstall 動作が変わらないことを引き続き要求しつつ、config メタデータ移行を許容する場合があります。
公開済みの `2026.4.26` パッケージは、すでに出荷済みのローカルビルドメタデータスタンプファイルについて警告する場合もあります。それ以降のパッケージは最新の契約を満たす必要があります。同じ条件は警告やスキップではなく失敗になります。
公開済みの `2026.4.26` パッケージでは、すでに出荷済みだったローカルビルドメタデータスタンプファイルについても警告する場合があります。それ以降のパッケージは最新の契約を満たす必要があります。同じ条件は、警告またはスキップではなく失敗になります。
### 例
@ -238,152 +250,152 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
失敗した package acceptance 実行をデバッグするときは、`resolve_package` サマリーから開始して、パッケージソース、バージョン、SHA-256 を確認します。次に `docker_acceptance` 子実行とその Docker アーティファクト（`.artifacts/docker-tests/**/summary.json`、`failures.json`、レーンログ、フェーズタイミング、再実行コマンド）を調査します。完全なリリース検証を再実行するのではなく、失敗した package プロファイルまたは正確な Docker レーンを再実行することを優先します。
失敗した package acceptance 実行をデバッグする場合は、まず `resolve_package` サマリーでパッケージソース、バージョン、SHA-256 を確認します。次に、`docker_acceptance` 子実行とその Docker アーティファクトを調べます: `.artifacts/docker-tests/**/summary.json`、`failures.json`、レーンログ、フェーズタイミング、再実行コマンド。完全なリリース検証を再実行するのではなく、失敗したパッケージプロファイルまたは正確な Docker レーンを再実行することを優先します。
## インストール smoke
別個の `Install Smoke` ワークフローは、独自の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。smoke カバレッジを `run_fast_install_smoke` と `run_full_install_smoke` に分割します。
- **高速パス** は、Docker/package サーフェス、バンドル済み Plugin パッケージ/マニフェスト変更、または Docker smoke ジョブが実行する core plugin/channel/gateway/Plugin SDK サーフェスに触れるプルリクエストで実行されます。ソースのみのバンドル済み Plugin 変更、テストのみの編集、docs のみの編集では Docker ワーカーは予約されません。高速パスはルート Dockerfile イメージを一度ビルドし、CLI をチェックし、agents delete shared-workspace CLI smoke を実行し、コンテナ gateway-network e2e を実行し、バンドル済み extension ビルド引数を検証し、240 秒の集約コマンドタイムアウト（各シナリオの Docker 実行は別途上限あり）内で、範囲を限定した bundled-plugin Docker プロファイルを実行します。
- **フルパス** は、夜間スケジュール実行、手動ディスパッチ、workflow-call リリースチェック、および installer/package/Docker サーフェスに本当に触れるプルリクエスト向けに、QR package install と installer Docker/update カバレッジを保持します。フルモードでは、install-smoke は target-SHA GHCR ルート Dockerfile smoke イメージを 1 つ準備または再利用し、QR package install、ルート Dockerfile/Gateway smoke、installer/update smoke、高速 bundled-plugin Docker E2E を別々のジョブとして実行するため、installer 作業はルートイメージ smoke の後ろで待機しません。
- **高速パス** は、Docker/package サーフェス、バンドル済み Plugin package/manifest の変更、または Docker smoke ジョブが実行する core plugin/channel/gateway/Plugin SDK サーフェスに触れるプルリクエストで実行されます。ソースのみのバンドル済み Plugin 変更、テストのみの編集、docs のみの編集は Docker worker を予約しません。高速パスはルート Dockerfile イメージを一度ビルドし、CLI をチェックし、agents delete shared-workspace CLI smoke を実行し、container gateway-network e2e を実行し、バンドル済み拡張機能の build arg を検証し、240 秒の集約コマンドタイムアウト内で範囲限定の bundled-plugin Docker プロファイルを実行します（各シナリオの Docker 実行は別個に上限設定されます）。
- **フルパス** は、nightly scheduled 実行、手動ディスパッチ、workflow-call リリースチェック、および installer/package/Docker サーフェスに実際に触れるプルリクエスト向けに、QR package install と installer Docker/update カバレッジを保持します。full モードでは、install-smoke は 1 つの target-SHA GHCR ルート Dockerfile smoke イメージを準備または再利用し、その後 QR package install、ルート Dockerfile/Gateway smoke、installer/update smoke、高速 bundled-plugin Docker E2E を別々のジョブとして実行するため、installer 作業がルートイメージ smoke の後ろで待つことはありません。
`main` へのプッシュ（マージコミットを含む）はフルパスを強制しません。変更スコープロジックがプッシュでフルカバレッジを要求する場合、ワークフローは高速 Docker smoke を維持し、フル install smoke は夜間またはリリース検証に任せます。
`main` push（マージコミットを含む）はフルパスを強制しません。変更スコープロジックが push でフルカバレッジを要求する場合でも、ワークフローは高速 Docker smoke を維持し、フル install smoke は nightly またはリリース検証に任せます。
遅い Bun global install image-provider smoke は、`run_bun_global_install_smoke` で別途ゲートされます。夜間スケジュールとリリースチェックワークフローから実行され、手動の `Install Smoke` ディスパッチはこれを opt in できますが、プルリクエストと `main` へのプッシュでは実行されません。QR と installer Docker テストは、それぞれ独自のインストール重視 Dockerfile を維持します。
低速な Bun global install image-provider smoke は、`run_bun_global_install_smoke` によって別個にゲートされます。これは nightly schedule とリリースチェックワークフローから実行され、手動の `Install Smoke` ディスパッチでは opt in できますが、プルリクエストと `main` push では実行されません。QR と installer Docker テストは、それぞれ独自のインストール向け Dockerfile を維持します。
## ローカル Docker E2E
`pnpm test:docker:all` は共有ライブテストイメージを 1 つ事前ビルドし、OpenClaw を npm tarball として一度パックし、2 つの共有 `scripts/e2e/Dockerfile` イメージをビルドします。
`pnpm test:docker:all` は、1 つの共有 live-test イメージを事前ビルドし、OpenClaw を npm tarball として一度パックし、2 つの共有 `scripts/e2e/Dockerfile` イメージをビルドします。
- installer/update/plugin-dependency レーン用の最小 Node/Git ランナー。
- 通常の機能レーン用に、同じ tarball を `/app` にインストールする機能イメージ。
- installer/update/plugin-dependency レーン用の素の Node/Git runner。
- 通常の機能レーン用に、同じ tarball を `/app` にインストールする functional イメージ。
Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーロジックは `scripts/lib/docker-e2e-plan.mjs` にあり、ランナーは選択されたプランのみを実行します。スケジューラーは `OPENCLAW_DOCKER_E2E_BARE_IMAGE` と `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` を使用してレーンごとにイメージを選択し、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` でレーンを実行します。
Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーロジックは `scripts/lib/docker-e2e-plan.mjs` にあり、ランナーは選択されたプランのみを実行します。スケジューラーは `OPENCLAW_DOCKER_E2E_BARE_IMAGE` と `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` でレーンごとにイメージを選択し、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` でレーンを実行します。
### 調整項目
| 変数 | デフォルト | 目的 |
| -------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 通常レーン用のメインプールのスロット数。 |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | provider-sensitive tail-pool のスロット数。 |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | provider がスロットリングしないようにする同時ライブレーン上限。 |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 同時 npm install レーン上限。 |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 同時 multi-service レーン上限。 |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Docker daemon の create storm を避けるためのレーン開始間隔。間隔なしにするには `0` を設定。 |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | レーンごとのフォールバックタイムアウト（120 分）。選択された live/tail レーンはより厳しい上限を使用します。 |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` はレーンを実行せずにスケジューラープランを出力します。 |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | カンマ区切りの正確なレーンリスト。cleanup smoke をスキップし、agent が 1 つの失敗レーンを再現できるようにします。 |
| 変数 | 既定値 | 目的 |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 通常レーン用のメインプールスロット数。 |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | provider-sensitive tail-pool スロット数。 |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | provider がスロットリングしないようにする同時 live レーン上限。 |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 同時 npm install レーン上限。 |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 同時 multi-service レーン上限。 |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Docker daemon create storm を避けるためのレーン開始間隔。stagger なしにするには `0` を設定。 |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | レーンごとのフォールバックタイムアウト（120 分）。選択された live/tail レーンはより厳しい上限を使用します。 |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | 未設定 | `1` はレーンを実行せずにスケジューラープランを出力します。 |
| `OPENCLAW_DOCKER_ALL_LANES` | 未設定 | カンマ区切りの正確なレーンリスト。agents が 1 つの失敗レーンを再現できるよう cleanup smoke をスキップします。 |
有効上限より重いレーンでも、空のプールから開始でき、その後容量を解放するまで単独で実行されます。ローカル集約は Docker を preflight し、古い OpenClaw E2E コンテナを削除し、アクティブレーン状態を出力し、最長優先の順序付けのためにレーンタイミングを永続化し、デフォルトでは最初の失敗後に新しいプール済みレーンのスケジュールを停止します。
有効な上限より重いレーンでも、空のプールからなら開始でき、その後は容量を解放するまで単独で実行されます。ローカル集約は Docker を事前チェックし、古い OpenClaw E2E コンテナを削除し、アクティブなレーンの状態を出力し、最長優先の順序付けのためにレーンのタイミングを永続化し、既定では最初の失敗後に新しいプール済みレーンのスケジュールを停止します。
### 再利用可能な live/E2E ワークフロー
### 再利用可能なライブ/E2Eワークフロー
再利用可能な live/E2E ワークフローは、必要な package、image kind、live image、lane、credential カバレッジを `scripts/test-docker-all.mjs --plan-json` に問い合わせます。その後 `scripts/docker-e2e.mjs` がそのプランを GitHub outputs とサマリーに変換します。`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw をパックするか、現在の実行の package artifact をダウンロードするか、`package_artifact_run_id` から package artifact をダウンロードします。tarball inventory を検証し、プランが package-installed レーンを必要とする場合は Blacksmith の Docker layer cache を通じて package-digest-tagged bare/functional GHCR Docker E2E イメージをビルドしてプッシュし、再ビルドの代わりに、指定された `docker_e2e_bare_image`/`docker_e2e_functional_image` 入力または既存の package-digest イメージを再利用します。Docker イメージの pull は、1 試行あたり 180 秒の範囲限定タイムアウトで再試行されるため、停止した registry/cache stream が CI クリティカルパスの大半を消費する代わりに、素早く再試行されます。
再利用可能なライブ/E2Eワークフローは、どのパッケージ、イメージ種別、ライブイメージ、レーン、認証情報カバレッジが必要かを `scripts/test-docker-all.mjs --plan-json` に問い合わせます。その後、`scripts/docker-e2e.mjs` がその計画を GitHub の出力とサマリーに変換します。これは、`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw をパッケージ化するか、現在の実行のパッケージアーティファクトをダウンロードするか、`package_artifact_run_id` からパッケージアーティファクトをダウンロードします。さらに、tarball のインベントリを検証し、計画がパッケージインストール済みレーンを必要とする場合は Blacksmith の Docker レイヤーキャッシュを通じてパッケージダイジェスト付きタグの bare/functional GHCR Docker E2E イメージをビルドしてプッシュし、再ビルドの代わりに指定された `docker_e2e_bare_image`/`docker_e2e_functional_image` 入力または既存のパッケージダイジェストイメージを再利用します。Docker イメージの pull は、試行ごとに上限付きの 180 秒タイムアウトで再試行されるため、停止した registry/cache ストリームが CI のクリティカルパスの大半を消費する代わりにすばやく再試行されます。
### リリースパスチャンク
### リリースパスのチャンク
リリース Docker カバレッジは、`OPENCLAW_SKIP_DOCKER_BUILD=1` を指定した小さなチャンク化ジョブを実行するため、各チャンクは必要な image kind だけを pull し、同じ重み付きスケジューラーを通じて複数のレーンを実行します。
リリース Docker カバレッジは、`OPENCLAW_SKIP_DOCKER_BUILD=1` を使ってより小さなチャンク化されたジョブを実行するため、各チャンクは必要なイメージ種別だけを pull し、同じ重み付きスケジューラを通じて複数のレーンを実行します。
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | bundled-channels`
現在のリリース Docker チャンクは、`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a` から `plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b`、および `bundled-channels-contracts` です。集約 `bundled-channels` チャンクは手動のワンショット再実行用に引き続き利用でき、`plugins-runtime-core`、`plugins-runtime`、および `plugins-integrations` は集約 plugin/runtime エイリアスのままです。`install-e2e` レーンエイリアスは、両方のプロバイダーインストーラーレーン向けの集約手動再実行エイリアスのままです。`bundled-channels` チャンクは、直列のオールインワン `bundled-channel-deps` レーンではなく、分割された `bundled-channel-*` と `bundled-channel-update-*` レーンを実行します。
現在のリリース Docker チャンクは、`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a` から `plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b`、`bundled-channels-contracts` です。集約 `bundled-channels` チャンクは手動の単発再実行用として引き続き利用でき、`plugins-runtime-core`、`plugins-runtime`、`plugins-integrations` も集約 Plugin/runtime エイリアスとして残ります。`install-e2e` レーンエイリアスは、両方のプロバイダーインストーラーレーン向けの集約手動再実行エイリアスとして残ります。`bundled-channels` チャンクは、直列の一体型 `bundled-channel-deps` レーンではなく、分割された `bundled-channel-*` および `bundled-channel-update-*` レーンを実行します。
OpenWebUI は、完全なリリースパスカバレッジが要求する場合に `plugins-runtime-services` に組み込まれ、OpenWebUI のみのディスパッチに限ってスタンドアロンの `openwebui` チャンクを保持します。バンドルチャンネル更新レーンは、一時的な npm ネットワーク障害に対して 1 回再試行します。
OpenWebUI は、完全なリリースパスカバレッジが要求する場合は `plugins-runtime-services` に組み込まれ、OpenWebUI のみの dispatch 向けにだけ単独の `openwebui` チャンクを保持します。バンドル済みチャンネル更新レーンは、一時的な npm ネットワーク障害に対して 1 回再試行します。
各チャンクは、レーンログ、タイミング、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、低速レーンテーブル、およびレーンごとの再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。ワークフローの `docker_lanes` 入力は、チャンクジョブの代わりに、準備済みイメージに対して選択されたレーンを実行します。これにより、失敗したレーンのデバッグを 1 つの対象 Docker ジョブに限定し、その実行用のパッケージアーティファクトを準備、ダウンロード、または再利用できます。選択されたレーンがライブ Docker レーンの場合、対象ジョブはその再実行用にライブテストイメージをローカルでビルドします。生成されるレーンごとの GitHub 再実行コマンドには、それらの値が存在する場合、`package_artifact_run_id`、`package_artifact_name`、および準備済みイメージ入力が含まれるため、失敗したレーンは失敗した実行から正確なパッケージとイメージを再利用できます。
各チャンクは、レーンログ、タイミング、`summary.json`、`failures.json`、フェーズタイミング、スケジューラ計画 JSON、低速レーンの表、レーンごとの再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。ワークフローの `docker_lanes` 入力は、チャンクジョブの代わりに選択されたレーンを準備済みイメージに対して実行します。これにより、失敗したレーンのデバッグは対象を絞った 1 つの Docker ジョブに限定され、その実行用のパッケージアーティファクトを準備、ダウンロード、または再利用します。選択されたレーンがライブ Docker レーンの場合、対象ジョブはその再実行のためにライブテストイメージをローカルでビルドします。生成されるレーンごとの GitHub 再実行コマンドには、値が存在する場合に `package_artifact_run_id`、`package_artifact_name`、準備済みイメージ入力が含まれるため、失敗したレーンは失敗した実行とまったく同じパッケージとイメージを再利用できます。
```bash
pnpm test:docker:rerun <run-id> # Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
スケジュールされたライブ/E2E ワークフローは、完全なリリースパス Docker スイートを毎日実行します。
スケジュールされたライブ/E2Eワークフローは、完全なリリースパス Docker スイートを毎日実行します。
## Plugin プレリリース
`Plugin Prerelease` は、より高コストな製品/パッケージカバレッジであるため、`Full Release Validation` または明示的なオペレーターによってディスパッチされる別ワークフローです。通常のプルリクエスト、`main` プッシュ、および単独の手動 CI ディスパッチでは、このスイートはオフのままです。これは、バンドル plugin テストを 8 つの拡張ワーカーに分散します。これらの拡張シャードジョブは、グループごとに 1 つの Vitest ワーカーとより大きな Node ヒープを使い、一度に最大 2 つの plugin 設定グループを実行するため、インポート負荷の高い plugin バッチが余分な CI ジョブを作成しません。
`Plugin Prerelease` はより高コストな製品/パッケージカバレッジであるため、`Full Release Validation` または明示的なオペレーターによって dispatch される別ワークフローです。通常の pull request、`main` push、単独の手動 CI dispatch では、このスイートは無効のままです。これは、バンドル済み Plugin テストを 8 つの extension ワーカーに分散します。これらの extension shard ジョブは、グループごとに 1 つの Vitest ワーカーとより大きな Node heap を使い、同時に最大 2 つの Plugin config グループを実行するため、import の重い Plugin バッチが追加の CI ジョブを作成しません。リリース専用の Docker プレリリースパスは、1 から 3 分のジョブのために多数の runner を予約しないよう、対象 Docker レーンを小さなグループでバッチ化します。
## QA ラボ
## QA Lab
QA ラボには、メインのスマートスコープワークフローの外に専用の CI レーンがあります。
QA Lab には、メインのスマートスコープワークフローの外に専用の CI レーンがあります。
- `Parity gate` ワークフローは、一致する PR 変更と手動ディスパッチで実行されます。プライベート QA ランタイムをビルドし、モック GPT-5.5 と Opus 4.6 のエージェントパックを比較します。
- `QA-Lab - All Lanes` ワークフローは、`main` で毎晩、および手動ディスパッチで実行されます。モックパリティゲート、ライブ Matrix レーン、ライブ Telegram レーンと Discord レーンを並列ジョブとしてファンアウトします。ライブジョブは `qa-live-shared` 環境を使用し、Telegram/Discord は Convex リースを使用します。
- `Parity gate` ワークフローは、一致する PR 変更と手動 dispatch で実行されます。プライベート QA runtime をビルドし、mock GPT-5.5 と Opus 4.6 の agentic pack を比較します。
- `QA-Lab - All Lanes` ワークフローは、`main` で毎晩および手動 dispatch で実行されます。mock parity gate、live Matrix レーン、live Telegram および Discord レーンを並列ジョブとしてファンアウトします。live ジョブは `qa-live-shared` environment を使用し、Telegram/Discord は Convex lease を使用します。
リリースチェックは、決定論的モックプロバイダーとモック認定モデル（`mock-openai/gpt-5.5` と `mock-openai/gpt-5.5-alt`）で Matrix と Telegram のライブトランスポートレーンを実行するため、チャンネル契約はライブモデルのレイテンシと通常の provider-plugin 起動から分離されます。ライブトランスポート Gateway はメモリ検索を無効にします。QA パリティがメモリ動作を別途カバーするためです。プロバイダー接続性は、別のライブモデル、ネイティブプロバイダー、および Docker プロバイダースイートでカバーされます。
リリースチェックは、決定的な mock provider と mock-qualified model（`mock-openai/gpt-5.5` および `mock-openai/gpt-5.5-alt`）を使って Matrix と Telegram の live transport レーンを実行するため、チャンネル契約は live model のレイテンシや通常の provider-plugin startup から分離されます。live transport gateway は memory search を無効化します。QA parity が memory behavior を別途カバーしているためです。provider connectivity は、別個の live model、native provider、Docker provider の各スイートでカバーされます。
Matrix は、スケジュールゲートとリリースゲートで `--profile fast` を使用し、チェックアウトされた CLI が対応している場合にのみ `--fail-fast` を追加します。CLI のデフォルトと手動ワークフロー入力は `all` のままです。手動の `matrix_profile=all` ディスパッチは、常に完全な Matrix カバレッジを `transport`、`media`、`e2ee-smoke`、`e2ee-deep`、および `e2ee-cli` ジョブにシャードします。
Matrix はスケジュールおよびリリースゲートで `--profile fast` を使用し、チェックアウトされた CLI が対応している場合にのみ `--fail-fast` を追加します。CLI の既定値と手動ワークフロー入力は `all` のままです。手動の `matrix_profile=all` dispatch は、常に完全な Matrix カバレッジを `transport`、`media`、`e2ee-smoke`、`e2ee-deep`、`e2ee-cli` ジョブに shard します。
`OpenClaw Release Checks` は、リリース承認前にリリースクリティカルな QA ラボレーンも実行します。その QA パリティゲートは、候補パックとベースラインパックを並列レーンジョブとして実行し、その後、最終的なパリティ比較用に小さなレポートジョブへ両方のアーティファクトをダウンロードします。
`OpenClaw Release Checks` は、リリース承認前にリリースで重要な QA Lab レーンも実行します。その QA parity gate は候補 pack と baseline pack を並列レーンジョブとして実行し、その後、最終的な parity 比較のために小さなレポートジョブへ両方のアーティファクトをダウンロードします。
変更が実際に QA ランタイム、モデルパックパリティ、またはパリティワークフローが所有するサーフェスに触れる場合を除き、PR ランディングパスを `Parity gate` の背後に置かないでください。通常のチャンネル、設定、ドキュメント、または単体テスト修正では、これを任意のシグナルとして扱い、スコープ付き CI/チェックの証拠に従ってください。
変更が実際に QA runtime、model-pack parity、または parity ワークフローが所有する surface に触れる場合を除き、PR の landing path を `Parity gate` の背後に置かないでください。通常のチャンネル、config、docs、または unit-test 修正では、これは任意のシグナルとして扱い、スコープされた CI/check evidence に従ってください。
## CodeQL
`CodeQL` ワークフローは、完全なリポジトリスイープではなく、意図的に絞り込まれた初回パスのセキュリティスキャナーです。毎日、手動、および非ドラフトのプルリクエストガード実行では、Actions ワークフローコードに加え、最もリスクの高い JavaScript/TypeScript サーフェスを、high/critical の `security-severity` にフィルタリングされた高信頼度のセキュリティクエリでスキャンします。
`CodeQL` ワークフローは意図的に狭い初回パスのセキュリティスキャナーであり、リポジトリ全体の sweep ではありません。毎日、手動、非 draft pull request の guard 実行では、Actions workflow code に加え、最もリスクの高い JavaScript/TypeScript surface を、高/critical の `security-severity` に絞った高信頼度のセキュリティクエリでスキャンします。
プルリクエストガードは軽量に保たれます。`.github/actions`、`.github/codeql`、`.github/workflows`、`packages`、または `src` 配下の変更に対してのみ開始され、スケジュールされたワークフローと同じ高信頼度セキュリティマトリクスを実行します。Android と macOS の CodeQL は PR デフォルトから外れています。
pull request guard は軽量に保たれています。`.github/actions`、`.github/codeql`、`.github/workflows`、`packages`、または `src` 配下の変更でのみ開始され、スケジュールワークフローと同じ高信頼度セキュリティマトリクスを実行します。Android と macOS の CodeQL は PR 既定値には含まれません。
### セキュリティカテゴリ
| カテゴリ | サーフェス |
| カテゴリ | Surface |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | 認証、シークレット、サンドボックス、Cron、および Gateway ベースライン |
| `/codeql-security-high/channel-runtime-boundary` | コアチャンネル実装契約に加え、チャンネル plugin ランタイム、Gateway、Plugin SDK、シークレット、監査タッチポイント |
| `/codeql-security-high/network-ssrf-boundary` | コア SSRF、IP 解析、ネットワークガード、web-fetch、および Plugin SDK SSRF ポリシーサーフェス |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP サーバー、プロセス実行ヘルパー、アウトバウンド配信、およびエージェントツール実行ゲート |
| `/codeql-security-high/plugin-trust-boundary` | Plugin インストール、ローダー、マニフェスト、レジストリ、runtime-dependency ステージング、source-loading、および Plugin SDK パッケージ契約の信頼サーフェス |
| `/codeql-security-high/core-auth-secrets` | Auth、secrets、sandbox、cron、gateway baseline |
| `/codeql-security-high/channel-runtime-boundary` | Core channel implementation contracts に加え、channel Plugin runtime、gateway、Plugin SDK、secrets、audit touchpoints |
| `/codeql-security-high/network-ssrf-boundary` | Core SSRF、IP parsing、network guard、web-fetch、Plugin SDK SSRF policy surfaces |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP servers、process execution helpers、outbound delivery、agent tool-execution gates |
| `/codeql-security-high/plugin-trust-boundary` | Plugin install、loader、manifest、registry、runtime-dependency staging、source-loading、Plugin SDK package contract trust surfaces |
### プラットフォーム固有のセキュリティシャード
### プラットフォーム固有のセキュリティ shard
- `CodeQL Android Critical Security` — スケジュールされた Android セキュリティシャード。ワークフロー健全性が許容する最小の Blacksmith Linux ランナー上で、CodeQL 用に Android アプリを手動でビルドします。`/codeql-critical-security/android` 配下にアップロードします。
- `CodeQL macOS Critical Security` — 週次/手動の macOS セキュリティシャード。Blacksmith macOS 上で CodeQL 用に macOS アプリを手動でビルドし、依存関係ビルド結果をアップロード済み SARIF からフィルタリングし、`/codeql-critical-security/macos` 配下にアップロードします。クリーンな場合でも macOS ビルドがランタイムを支配するため、日次デフォルトの外に保持されています。
- `CodeQL Android Critical Security` — スケジュールされた Android セキュリティ shard。workflow sanity が受け入れる最小の Blacksmith Linux runner 上で、CodeQL 用に Android app を手動でビルドします。`/codeql-critical-security/android` 配下にアップロードします。
- `CodeQL macOS Critical Security` — 週次/手動の macOS セキュリティ shard。Blacksmith macOS 上で CodeQL 用に macOS app を手動でビルドし、アップロードされる SARIF から依存関係のビルド結果を除外し、`/codeql-critical-security/macos` 配下にアップロードします。クリーンな場合でも macOS build が runtime を支配するため、日次の既定値の外に置かれています。
### 重大品質カテゴリ
### Critical Quality カテゴリ
`CodeQL Critical Quality` は、対応する非セキュリティシャードです。これは、より小さな Blacksmith Linux ランナー上で、狭い高価値サーフェスに対し、エラー重大度の非セキュリティ JavaScript/TypeScript 品質クエリのみを実行します。そのプルリクエストガードは、スケジュールされたプロファイルよりも意図的に小さくなっています。非ドラフト PR では、エージェントコマンド/モデル/ツール実行および返信ディスパッチコード、設定スキーマ/マイグレーション/IO コード、認証/シークレット/サンドボックス/セキュリティコード、コアチャンネルおよびバンドルチャンネル plugin ランタイム、Gateway protocol/server-method、メモリランタイム/SDK グルー、MCP/プロセス/アウトバウンド配信、プロバイダーランタイム/モデルカタログ、セッション診断/配信キュー、plugin ローダー、Plugin SDK/package-contract、または Plugin SDK 返信ランタイムの変更に対して、一致する `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract`、および `plugin-sdk-reply-runtime` シャードのみを実行します。CodeQL 設定と品質ワークフローの変更では、12 個すべての PR 品質シャードを実行します。
`CodeQL Critical Quality` は対応する非セキュリティ shard です。これは、より小さな Blacksmith Linux runner 上で、狭い高価値 surface に対して error-severity の非セキュリティ JavaScript/TypeScript quality query だけを実行します。その pull request guard はスケジュールプロファイルより意図的に小さくなっています。非 draft PR は、agent command/model/tool execution と reply dispatch code、config schema/migration/IO code、auth/secrets/sandbox/security code、core channel とバンドル済み channel Plugin runtime、gateway protocol/server-method、memory runtime/SDK glue、MCP/process/outbound delivery、provider runtime/model catalog、session diagnostics/delivery queues、Plugin loader、Plugin SDK/package-contract、または Plugin SDK reply runtime の変更に対して、対応する `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract`、`plugin-sdk-reply-runtime` shard のみを実行します。CodeQL config と quality workflow の変更は、12 個すべての PR quality shard を実行します。
手動ディスパッチは以下を受け付けます。
手動 dispatch は次を受け付けます。
```
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
狭いプロファイルは、1 つの品質シャードを単独で実行するための教育/反復フックです。
狭いプロファイルは、1 つの quality shard を単独で実行するための教育/反復用フックです。
| カテゴリ | サーフェス |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | 認証、シークレット、サンドボックス、Cron、Gateway のセキュリティ境界コード |
| `/codeql-critical-quality/config-boundary` | 設定スキーマ、移行、正規化、IO 契約 |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway プロトコルスキーマとサーバーメソッド契約 |
| `/codeql-critical-quality/channel-runtime-boundary` | コアチャネルとバンドルされたチャネル Plugin の実装契約 |
| `/codeql-critical-quality/agent-runtime-boundary` | コマンド実行、モデル/プロバイダーのディスパッチ、自動返信ディスパッチとキュー、ACP コントロールプレーンランタイム契約 |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP サーバーとツールブリッジ、プロセス監視ヘルパー、送信配信契約 |
| `/codeql-critical-quality/core-auth-secrets` | 認証、シークレット、サンドボックス、cron、Gateway のセキュリティ境界コード |
| `/codeql-critical-quality/config-boundary` | 設定スキーマ、移行、正規化、IO コントラクト |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway プロトコルスキーマとサーバーメソッドコントラクト |
| `/codeql-critical-quality/channel-runtime-boundary` | コアチャネルとバンドル済みチャネル Plugin 実装コントラクト |
| `/codeql-critical-quality/agent-runtime-boundary` | コマンド実行、モデル/プロバイダーディスパッチ、自動返信ディスパッチとキュー、ACP コントロールプレーンランタイムコントラクト |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP サーバーとツールブリッジ、プロセス監視ヘルパー、アウトバウンド配信コントラクト |
| `/codeql-critical-quality/memory-runtime-boundary` | メモリホスト SDK、メモリランタイムファサード、メモリ Plugin SDK エイリアス、メモリランタイム有効化グルー、メモリ doctor コマンド |
| `/codeql-critical-quality/session-diagnostics-boundary` | 返信キュー内部、セッション配信キュー、送信セッションのバインディング/配信ヘルパー、診断イベント/ログバンドルサーフェス、セッション doctor CLI 契約 |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin SDK の受信返信ディスパッチ、返信ペイロード/チャンク化/ランタイムヘルパー、チャネル返信オプション、配信キュー、セッション/スレッドのバインディングヘルパー |
| `/codeql-critical-quality/provider-runtime-boundary` | モデルカタログ正規化、プロバイダー認証と検出、プロバイダーランタイム登録、プロバイダーのデフォルト/カタログ、web/search/fetch/embedding レジストリ |
| `/codeql-critical-quality/ui-control-plane` | コントロール UI ブートストラップ、ローカル永続化、Gateway コントロールフロー、タスクコントロールプレーンランタイム契約 |
| `/codeql-critical-quality/web-media-runtime-boundary` | コア web fetch/search、メディア IO、メディア理解、画像生成、メディア生成ランタイム契約 |
| `/codeql-critical-quality/plugin-boundary` | ローダー、レジストリ、公開サーフェス、Plugin SDK エントリポイント契約 |
| `/codeql-critical-quality/plugin-sdk-package-contract` | 公開パッケージ側の Plugin SDK ソースと Plugin パッケージ契約ヘルパー |
| `/codeql-critical-quality/session-diagnostics-boundary` | 返信キュー内部、セッション配信キュー、アウトバウンドセッションバインディング/配信ヘルパー、診断イベント/ログバンドルサーフェス、セッション doctor CLI コントラクト |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin SDK インバウンド返信ディスパッチ、返信ペイロード/チャンク化/ランタイムヘルパー、チャネル返信オプション、配信キュー、セッション/スレッドバインディングヘルパー |
| `/codeql-critical-quality/provider-runtime-boundary` | モデルカタログ正規化、プロバイダー認証と検出、プロバイダーランタイム登録、プロバイダーデフォルト/カタログ、web/search/fetch/embedding レジストリ |
| `/codeql-critical-quality/ui-control-plane` | コントロール UI ブートストラップ、ローカル永続化、Gateway コントロールフロー、タスクコントロールプレーンランタイムコントラクト |
| `/codeql-critical-quality/web-media-runtime-boundary` | コア web fetch/search、メディア IO、メディア理解、画像生成、メディア生成ランタイムコントラクト |
| `/codeql-critical-quality/plugin-boundary` | ローダー、レジストリ、公開サーフェス、Plugin SDK エントリポイントコントラクト |
| `/codeql-critical-quality/plugin-sdk-package-contract` | 公開パッケージ側の Plugin SDK ソースと Plugin パッケージコントラクトヘルパー |
品質はセキュリティとは分離されたままにすることで、品質の検出結果をスケジュール、測定、無効化、拡張してもセキュリティシグナルを不明瞭にしない。Swift、Python、バンドル Plugin の CodeQL 拡張は、狭いプロファイルのランタイムとシグナルが安定してから、スコープ指定またはシャード化されたフォローアップ作業としてのみ戻すべきである。
品質をセキュリティから分離しておくことで、品質の検出結果を、セキュリティシグナルを不明瞭にせずにスケジュール、測定、無効化、拡張できます。Swift、Python、バンドル済み Plugin の CodeQL 拡張は、狭いプロファイルのランタイムとシグナルが安定してから、スコープ化またはシャーディングされたフォローアップ作業としてのみ追加し直すべきです。
## メンテナンスワークフロー
### Docs Agent
`Docs Agent` ワークフローは、最近取り込まれた変更に既存ドキュメントを合わせ続けるための、イベント駆動型 Codex メンテナンスレーンである。純粋なスケジュールはない。`main` への bot 以外の push CI 実行が成功するとトリガーでき、手動ディスパッチでも直接実行できる。ワークフロー実行による呼び出しは、`main` が先に進んでいる場合、またはスキップされていない別の Docs Agent 実行が過去 1 時間以内に作成されている場合はスキップする。実行時には、スキップされていない直前の Docs Agent ソース SHA から現在の `main` までのコミット範囲をレビューするため、1 時間に 1 回の実行で、前回の docs パス以降に蓄積されたすべての main 変更をカバーできる。
`Docs Agent` ワークフローは、最近取り込まれた変更と既存ドキュメントの整合性を保つための、イベント駆動の Codex メンテナンスレーンです。純粋なスケジュールはありません。`main` への bot 以外の push CI 実行が成功するとトリガーされ、手動ディスパッチでも直接実行できます。ワークフロー実行による呼び出しは、`main` が先に進んでいる場合、またはスキップされていない別の Docs Agent 実行が直近 1 時間以内に作成されている場合はスキップされます。実行時には、前回スキップされなかった Docs Agent ソース SHA から現在の `main` までのコミット範囲をレビューするため、1 時間ごとの 1 回の実行で、前回のドキュメント確認以降に蓄積されたすべての main 変更をカバーできます。
### Test Performance Agent
`Test Performance Agent` ワークフローは、遅いテスト向けのイベント駆動型 Codex メンテナンスレーンである。純粋なスケジュールはない。`main` への bot 以外の push CI 実行が成功するとトリガーできるが、別のワークフロー実行による呼び出しがその UTC 日にすでに実行済みまたは実行中の場合はスキップする。手動ディスパッチは、その日次アクティビティゲートを迂回する。このレーンは、フルスイートのグループ化された Vitest パフォーマンスレポートを作成し、Codex には広範なリファクタリングではなく、カバレッジを維持する小さなテストパフォーマンス修正だけを行わせ、その後フルスイートレポートを再実行して、合格ベースラインテスト数を減らす変更を拒否する。ベースラインに失敗テストがある場合、Codex は明らかな失敗だけを修正でき、エージェント後のフルスイートレポートは、何かがコミットされる前に合格しなければならない。bot push が取り込まれる前に `main` が進んだ場合、このレーンは検証済みパッチをリベースし、`pnpm check:changed` を再実行して push を再試行する。競合する古いパッチはスキップされる。Codex アクションが docs agent と同じ drop-sudo の安全姿勢を維持できるよう、GitHub ホストの Ubuntu を使用する。
`Test Performance Agent` ワークフローは、遅いテスト向けのイベント駆動の Codex メンテナンスレーンです。純粋なスケジュールはありません。`main` への bot 以外の push CI 実行が成功するとトリガーされますが、その UTC 日に別のワークフロー実行呼び出しがすでに実行済みまたは実行中の場合はスキップされます。手動ディスパッチは、その日次アクティビティゲートを迂回します。このレーンはフルスイートのグループ化された Vitest パフォーマンスレポートを作成し、Codex には広範なリファクタリングではなく、カバレッジを維持する小さなテストパフォーマンス修正だけを行わせます。その後、フルスイートレポートを再実行し、合格ベースラインテスト数を減らす変更を拒否します。ベースラインに失敗テストがある場合、Codex は明白な失敗のみ修正でき、エージェント後のフルスイートレポートはコミット前に合格しなければなりません。bot push が取り込まれる前に `main` が進んだ場合、このレーンは検証済みパッチをリベースし、`pnpm check:changed` を再実行して、push を再試行します。競合する古いパッチはスキップされます。Docs Agent と同じ drop-sudo 安全姿勢を Codex アクションが維持できるよう、GitHub ホストの Ubuntu を使用します。
### マージ後の重複 PR
`Duplicate PRs After Merge` ワークフローは、取り込み後の重複クリーンアップ向けの手動メンテナーワークフローである。デフォルトは dry-run で、`apply=true` の場合にのみ明示的に列挙された PR をクローズする。GitHub を変更する前に、取り込まれた PR がマージ済みであり、各重複が共有の参照 issue または重複する変更ハンクを持つことを検証する。
`Duplicate PRs After Merge` ワークフローは、取り込み後の重複クリーンアップ用の手動メンテナーワークフローです。デフォルトは dry-run で、`apply=true` の場合に明示的に列挙された PR のみを閉じます。GitHub を変更する前に、取り込まれた PR がマージ済みであり、各重複に共有された参照 Issue または重複する変更 hunk があることを検証します。
```bash
gh workflow run duplicate-after-merge.yml \
@ -394,25 +406,25 @@ gh workflow run duplicate-after-merge.yml \
## ローカルチェックゲートと変更ルーティング
ローカルの変更レーンロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行される。このローカルチェックゲートは、広範な CI プラットフォームスコープよりもアーキテクチャ境界について厳格である。
ローカル変更レーンロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。このローカルチェックゲートは、広範な CI プラットフォームスコープよりもアーキテクチャ境界について厳格です。
- コア本番変更は、コア本番とコアテストの typecheck に加えてコア lint/guard を実行する。
- コアのテストのみの変更は、コアテストの typecheck に加えてコア lint のみを実行する。
- extension 本番変更は、extension 本番と extension テストの typecheck に加えて extension lint を実行する。
- extension のテストのみの変更は、extension テストの typecheck に加えて extension lint を実行する。
- 公開 Plugin SDK または Plugin 契約の変更は、extension がそれらのコア契約に依存しているため、extension typecheck へ拡張される（Vitest extension sweep は明示的なテスト作業のまま）。
- リリースメタデータのみのバージョン更新は、対象を絞ったバージョン/設定/ルート依存関係チェックを実行する。
- 不明なルート/設定変更は、安全側に倒してすべてのチェックレーンへ送る。
- コア本番変更は、コア本番とコアテストの型チェックに加えてコア lint/guard を実行します。
- コアのテストのみの変更は、コアテストの型チェックに加えてコア lint のみを実行します。
- 拡張機能本番変更は、拡張機能本番と拡張機能テストの型チェックに加えて拡張機能 lint を実行します。
- 拡張機能のテストのみの変更は、拡張機能テストの型チェックに加えて拡張機能 lint を実行します。
- 公開 Plugin SDK または Plugin コントラクトの変更は、拡張機能がそれらのコアコントラクトに依存するため、拡張機能の型チェックまで拡張されます（Vitest 拡張機能スイープは明示的なテスト作業のままです）。
- リリースメタデータのみのバージョン更新は、対象を絞ったバージョン/設定/ルート依存関係チェックを実行します。
- 不明なルート/設定変更は、安全側に倒してすべてのチェックレーンを実行します。
ローカルの変更テストルーティングは `scripts/test-projects.test-support.mjs` にあり、意図的に `check:changed` より軽量である。直接のテスト編集はそのテスト自体を実行し、ソース編集は明示的なマッピング、次に兄弟テストとインポートグラフ依存先を優先する。共有グループルーム配信設定は明示的なマッピングの一つである。グループの可視返信設定、ソース返信配信モード、またはメッセージツールのシステムプロンプトへの変更は、コア返信テストに加えて Discord と Slack の配信リグレッションを通るため、共有デフォルト変更は最初の PR push の前に失敗する。変更がハーネス全体に及ぶほど広範で、安価なマッピング済みセットが信頼できるプロキシではない場合にのみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用する。
ローカルの変更テストルーティングは `scripts/test-projects.test-support.mjs` にあり、意図的に `check:changed` より低コストです。直接のテスト編集はそれ自体を実行し、ソース編集は明示的なマッピングを優先し、その後に sibling テストと import-graph 依存先を使います。共有グループルーム配信設定は、明示的なマッピングの 1 つです。グループの可視返信設定、ソース返信配信モード、またはメッセージツールシステムプロンプトへの変更は、コア返信テストに加えて Discord と Slack の配信回帰を通るため、共有デフォルトの変更は最初の PR push の前に失敗します。安価なマッピング済みセットが信頼できるプロキシにならないほど変更がハーネス全体に及ぶ場合のみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。
## Testbox 検証
Testbox はリポジトリルートから実行し、広範な証明には新しくウォームアップした box を優先する。再利用された、期限切れになった、または予想外に大きな同期を報告したばかりの box で遅いゲートに時間を使う前に、まず box 内で `pnpm testbox:sanity` を実行する。
Testbox はリポジトリルートから実行し、広範な証明には新しく warmed した box を優先してください。再利用された、期限切れになった、または予想外に大きな同期を報告したばかりの box で遅いゲートに時間を使う前に、まず box 内で `pnpm testbox:sanity` を実行してください。
sanity check は、`pnpm-lock.yaml` などの必須ルートファイルが消えている場合、または `git status --short` が少なくとも 200 個の追跡済み削除を示す場合に早期失敗する。これは通常、リモート同期状態が PR の信頼できるコピーではないことを意味する。製品テスト失敗をデバッグするのではなく、その box を停止して新しいものをウォームアップする。意図的な大量削除 PR では、その sanity run に `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` を設定する。
sanity check は、`pnpm-lock.yaml` などの必須ルートファイルが消えている場合、または `git status --short` が 200 件以上の tracked deletion を示す場合に即座に失敗します。これは通常、リモート同期状態が PR の信頼できるコピーではないことを意味します。製品テストの失敗をデバッグするのではなく、その box を停止して新しいものを warm してください。意図的な大規模削除 PR の場合は、その sanity 実行に `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` を設定してください。
`pnpm testbox:run` は、sync フェーズに 5 分を超えて留まり、同期後の出力がないローカル Blacksmith CLI 呼び出しも終了する。その guard を無効化するには `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` を設定し、通常より大きなローカル diff にはより大きなミリ秒値を使用する。
`pnpm testbox:run` は、同期後出力がないまま同期フェーズに 5 分を超えて留まるローカル Blacksmith CLI 呼び出しも終了します。その guard を無効化するには `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` を設定するか、通常より大きなローカル差分にはより大きいミリ秒値を使用してください。
## 関連

135
docs/ja-JP/cli/models.md
View File

@ -1,29 +1,29 @@
---
read_when:
- デフォルトモデルを変更したい、またはプロバイダーの認証ステータスを確認したい場合
- デフォルトモデルを変更したい、またはプロバイダーの認証ステータスを確認したい
- 利用可能なモデル/プロバイダーをスキャンし、認証プロファイルをデバッグしたい
summary: '`openclaw models` の CLI リファレンス（status/list/set/scan、エイリアス、フォールバック、認証）'
title: モデル
x-i18n:
generated_at: "2026-04-30T05:05:30Z"
generated_at: "2026-05-01T05:00:28Z"
model: gpt-5.5
provider: openai
source_hash: 95e2361989b583f7f52947dad1faaaba44dc6a5f58719cc2e83c13fce7c33adc
source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1
source_path: cli/models.md
workflow: 16
---
# `openclaw models`
モデルの検出、スキャン、設定 (デフォルトモデル、フォールバック、認証プロファイル)。
モデル検出、スキャン、設定（デフォルトモデル、フォールバック、認証プロファイル）。
関連:
- プロバイダー + モデル: [モデル](/ja-JP/providers/models)
- モデル選択の概念 + `/models` スラッシュコマンド: [モデルの概念](/ja-JP/concepts/models)
- プロバイダー認証のセットアップ: [はじめに](/ja-JP/start/getting-started)
- プロバイダーとモデル: [モデル](/ja-JP/providers/models)
- モデル選択の概念と `/models` スラッシュコマンド: [モデルの概念](/ja-JP/concepts/models)
- プロバイダー認証の設定: [はじめに](/ja-JP/start/getting-started)
## 一般的なコマンド
## 共通コマンド
```bash
openclaw models status
@ -32,76 +32,80 @@ openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` は、解決済みのデフォルト/フォールバックと認証の概要を表示します。
プロバイダー使用状況のスナップショットが利用できる場合、OAuth/APIキーのステータスセクションには
プロバイダー使用期間とクォータスナップショットが含まれます。
`openclaw models status` は、解決済みのデフォルト/フォールバックに加えて認証の概要を表示します。
プロバイダー使用状況のスナップショットが利用可能な場合、OAuth/APIキーのステータスセクションには
プロバイダーの使用期間とクォータのスナップショットが含まれます。
現在の使用期間プロバイダー: Anthropic、GitHub Copilot、Gemini CLI、OpenAI
Codex、MiniMax、Xiaomi、z.ai。使用状況の認証は、利用可能な場合はプロバイダー固有のフックから取得されます。
それ以外の場合、OpenClaw は認証プロファイル、環境変数、または設定から一致する OAuth/APIキー
資格情報へフォールバックします。
`--json` 出力では、`auth.providers` は環境変数/設定/ストアを考慮したプロバイダー
それ以外の場合、OpenClaw は認証プロファイル、環境、または設定内の一致する OAuth/APIキー
認証情報にフォールバックします。
`--json` 出力では、`auth.providers` は環境/設定/ストアを認識するプロバイダー
概要であり、`auth.oauth` は認証ストアのプロファイル健全性のみです。
各設定済みプロバイダープロファイルに対してライブ認証プローブを実行するには、`--probe` を追加します。
プローブは実際のリクエストです (トークンを消費し、レート制限を引き起こす可能性があります)。
設定済みエージェントのモデル/認証状態を調べるには、`--agent <id>` を使用します。省略した場合、
コマンドは、設定されていれば `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` を使用し、それ以外の場合は
設定済みの各プロバイダープロファイルに対してライブ認証プローブを実行するには、`--probe` を追加します。
プローブは実際のリクエストです（トークンを消費し、レート制限を発生させる可能性があります）。
設定済みエージェントのモデル/認証状態を検査するには、`--agent <id>` を使用します。省略した場合、
コマンドは `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` が設定されていればそれを使用し、そうでなければ
設定済みのデフォルトエージェントを使用します。
プローブ行は、認証プロファイル、環境変数資格情報、または `models.json` から取得されることがあります。
プローブ行は、認証プロファイル、環境認証情報、または `models.json` から取得される場合があります。
注:
注記:
- `models set <model-or-alias>` は `provider/model` またはエイリアスを受け付けます。
- `models list` は読み取り専用です。設定、認証プロファイル、既存のカタログ
状態、プロバイダー所有のカタログ行を読み取りますが、
`models.json` は書き換えません。
- `Auth` 列はプロバイダーレベルで読み取り専用です。これはローカルの
認証プロファイルメタデータ、環境変数マーカー、設定済みプロバイダーキー、ローカルプロバイダー
マーカー、AWS Bedrock の環境変数/プロファイルマーカー、Plugin の合成認証メタデータから計算されます。
- `Auth` 列はプロバイダーレベルで読み取り専用です。ローカルの
認証プロファイルメタデータ、環境マーカー、設定済みプロバイダーキー、ローカルプロバイダー
マーカー、AWS Bedrock 環境/プロファイルマーカー、Plugin の合成認証メタデータから計算されます。
プロバイダーランタイムの読み込み、キーチェーンシークレットの読み取り、プロバイダー
API の呼び出し、モデル単位の正確な実行準備状況の証明は行いません。
API の呼び出し、またはモデル単位の正確な実行準備状況の証明は行いません。
- `models list --all --provider <id>` は、そのプロバイダーでまだ認証していない場合でも、
Plugin マニフェストまたはバンドルされたプロバイダーカタログメタデータからの、プロバイダー所有の静的カタログ
行を含めることがあります。それらの行は、一致する認証が設定されるまで
Plugin マニフェストまたはバンドルされたプロバイダーカタログメタデータから、プロバイダー所有の静的カタログ
行を含めることができます。それらの行は、一致する認証が設定されるまで
利用不可として表示されます。
- 広範な `models list --all` は、プロバイダーランタイム補助フックを読み込まずに、
マニフェストカタログ行をレジストリ行より優先してマージします。プロバイダーでフィルタリングされたマニフェスト
高速パスは、`static` とマークされたプロバイダーのみを使用します。`refreshable` とマークされたプロバイダーは
レジストリ/キャッシュベースのままで、マニフェスト行を補助として追加します。一方、
- `models list` は、プロバイダーカタログ
検出が遅い間も制御プレーンの応答性を保ちます。デフォルトビューと設定済みビューは、短い待機後に設定済みまたは
合成モデル行へフォールバックし、検出は
バックグラウンドで完了させます。正確な完全検出済みカタログが必要で、
プロバイダー検出を待てる場合は `--all` を使用します。
- 広範な `models list --all` は、プロバイダーランタイム補足フックを読み込まずに、マニフェストカタログ行をレジストリ行の上にマージします。
プロバイダーで絞り込まれたマニフェスト高速パスは、`static` とマークされたプロバイダーのみを使用します。`refreshable` とマークされたプロバイダーは
レジストリ/キャッシュベースのままで、マニフェスト行を補足として追加します。一方、
`runtime` とマークされたプロバイダーはレジストリ/ランタイム検出のままです。
- `models list` は、ネイティブのモデルメタデータとランタイム上限を区別して保持します。テーブル
出力では、有効なランタイム上限がネイティブのコンテキストウィンドウと異なる場合、
`Ctx` は `contextTokens/contextWindow` を表示します。プロバイダーがその上限を公開する場合、JSON 行には `contextTokens`
- `models list` は、ネイティブモデルメタデータとランタイム上限を区別して保持します。表
出力では、有効なランタイム
上限がネイティブのコンテキストウィンドウと異なる場合、`Ctx` は `contextTokens/contextWindow` を表示します。プロバイダーがその上限を公開している場合、JSON 行には `contextTokens`
が含まれます。
- `models list --provider <id>` は、`moonshot` や
`openai-codex` などのプロバイダー ID でフィルタリングします。`Moonshot AI` など、
対話型プロバイダー選択での表示ラベルは受け付けません。
- モデル参照は **最初の** `/` で分割して解析されます。モデル ID に `/` が含まれる場合 (OpenRouter 形式)、プロバイダープレフィックスを含めます (例: `openrouter/moonshotai/kimi-k2`)。
`openai-codex` などのプロバイダー ID でフィルターします。`Moonshot AI` など、対話型プロバイダー
ピッカーの表示ラベルは受け付けません。
- モデル参照は **最初の** `/` で分割して解析されます。モデル ID に `/` が含まれる場合（OpenRouter 形式）、プロバイダープレフィックスを含めます（例: `openrouter/moonshotai/kimi-k2`）。
- プロバイダーを省略すると、OpenClaw はまず入力をエイリアスとして解決し、次に
その正確なモデル ID に対する一意の設定済みプロバイダー一致として解決し、その後でのみ
非推奨警告付きで設定済みのデフォルトプロバイダーへフォールバックします。
そのプロバイダーが設定済みのデフォルトモデルをもう公開していない場合、OpenClaw は
古い削除済みプロバイダーのデフォルトを表示するのではなく、最初の設定済みプロバイダー/モデルへ
そのプロバイダーが設定済みのデフォルトモデルを公開しなくなった場合、OpenClaw は
古い削除済みプロバイダーのデフォルトを表面化する代わりに、最初の設定済みプロバイダー/モデルへ
フォールバックします。
- `models status` は、認証出力で非シークレットのプレースホルダー (たとえば `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`) について、シークレットとしてマスクする代わりに `marker(<value>)` を表示することがあります。
- `models status` は、シークレットではないプレースホルダー（たとえば `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`）について、シークレットとしてマスクする代わりに、認証出力に `marker(<value>)` を表示する場合があります。
### モデルスキャン
`models scan` は OpenRouter の公開 `:free` カタログを読み取り、フォールバック用途の
候補をランク付けします。カタログ自体は公開されているため、メタデータのみのスキャンには
候補をランク付けします。カタログ自体は公開されているため、メタデータのみのスキャンでは
OpenRouter キーは不要です。
デフォルトでは、OpenClaw はライブモデル呼び出しでツールと画像のサポートをプローブしようとします。
OpenRouter キーが設定されていない場合、コマンドはメタデータのみの
出力へフォールバックし、`:free` モデルでもプローブと推論には `OPENROUTER_API_KEY` が必要であることを説明します。
出力にフォールバックし、`:free` モデルでもプローブと推論には `OPENROUTER_API_KEY` が必要であることを説明します。
オプション:
- `--no-probe` (メタデータのみ。設定/シークレットの検索なし)
- `--no-probe`（メタデータのみ。設定/シークレットの検索なし）
- `--min-params <b>`
- `--max-age-days <days>`
- `--provider <name>`
- `--max-candidates <n>`
- `--timeout <ms>` (カタログリクエストと各プローブのタイムアウト)
- `--timeout <ms>`（カタログリクエストと各プローブのタイムアウト）
- `--concurrency <n>`
- `--yes`
- `--no-input`
@ -118,17 +122,17 @@ OpenRouter キーが設定されていない場合、コマンドはメタデー
- `--json`
- `--plain`
- `--check` (終了コード 1=期限切れ/不足、2=期限間近)
- `--probe` (設定済み認証プロファイルのライブプローブ)
- `--probe-provider <name>` (1つのプロバイダーをプローブ)
- `--probe-profile <id>` (繰り返しまたはカンマ区切りのプロファイル ID)
- `--check`（終了コード 1=期限切れ/欠落、2=期限間近）
- `--probe`（設定済み認証プロファイルのライブプローブ）
- `--probe-provider <name>`（1つのプロバイダーをプローブ）
- `--probe-profile <id>`（繰り返し指定またはカンマ区切りのプロファイル ID）
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>` (設定済みエージェント ID。`OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` を上書き)
- `--agent <id>`（設定済みエージェント ID。`OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` を上書き）
`--json` は stdout を JSON ペイロード専用に保持します。認証プロファイル、プロバイダー、
起動時診断は stderr に送られるため、スクリプトは stdout を `jq` などのツールへ直接
`--json` は stdout を JSON ペイロード専用に保ちます。認証プロファイル、プロバイダー、
起動診断は stderr に送られるため、スクリプトは stdout を `jq` などのツールへ直接
パイプできます。
プローブステータスの分類:
@ -145,14 +149,14 @@ OpenRouter キーが設定されていない場合、コマンドはメタデー
想定されるプローブ詳細/理由コードのケース:
- `excluded_by_auth_order`: 保存済みプロファイルは存在しますが、明示的な
`auth.order.<provider>` がそれを省略したため、プローブは試行する代わりに
`auth.order.<provider>` がそれを省略しているため、プローブは試行する代わりに
除外を報告します。
- `missing_credential`、`invalid_expires`、`expired`、`unresolved_ref`:
プロファイルは存在しますが、適格でないか解決できません。
- `no_model`: プロバイダー認証は存在しますが、OpenClaw はそのプロバイダーに対してプローブ可能な
プロファイルは存在しますが、対象外または解決不能です。
- `no_model`: プロバイダー認証は存在しますが、OpenClaw はそのプロバイダー用のプローブ可能な
モデル候補を解決できませんでした。
## エイリアス + フォールバック
## エイリアスとフォールバック
```bash
openclaw models aliases list
@ -168,13 +172,14 @@ openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```
`models auth add` は対話型の認証ヘルパーです。選択したプロバイダーに応じて、
プロバイダー認証フロー (OAuth/APIキー) を起動するか、手動のトークン貼り付けへ案内します。
`models auth add` は対話型の認証ヘルパーです。選択した
プロバイダーに応じて、プロバイダー認証フロー（OAuth/APIキー）を起動するか、手動トークン貼り付けへ案内します。
`models auth login` はプロバイダー Plugin の認証フロー (OAuth/APIキー) を実行します。
インストールされているプロバイダーを確認するには、`openclaw plugins list` を使用します。
特定の設定済みエージェントストアへ認証結果を書き込むには、`openclaw models auth --agent <id> <subcommand>` を使用します。
親の `--agent` フラグは、`add`、`login`、`setup-token`、`paste-token`、`login-github-copilot` によって尊重されます。
`models auth login` は、プロバイダー Plugin の認証フロー（OAuth/APIキー）を実行します。
インストールされているプロバイダーを確認するには `openclaw plugins list` を使用します。
認証結果を特定の設定済みエージェントストアに書き込むには、`openclaw models auth --agent <id> <subcommand>` を使用します。
親の `--agent` フラグは、
`add`、`login`、`setup-token`、`paste-token`、`login-github-copilot` で有効です。
例:
@ -182,18 +187,18 @@ openclaw models auth paste-token
openclaw models auth login --provider openai-codex --set-default
```
注:
注記:
- `setup-token` と `paste-token` は、トークン認証メソッドを公開するプロバイダー向けの
- `setup-token` と `paste-token` は、トークン認証方式を公開するプロバイダー向けの
汎用トークンコマンドのままです。
- `setup-token` には対話型 TTY が必要で、プロバイダーのトークン認証
メソッドを実行します (プロバイダーが公開している場合は、そのプロバイダーの `setup-token` メソッドがデフォルト)。
方式を実行します（プロバイダーが公開している場合は、デフォルトでそのプロバイダーの `setup-token` 方式になります）。
- `paste-token` は、別の場所または自動化から生成されたトークン文字列を受け付けます。
- `paste-token` は `--provider` を必要とし、トークン値をプロンプトで求め、
- `paste-token` には `--provider` が必要で、トークン値の入力を求め、
`--profile-id` を渡さない限り、デフォルトのプロファイル ID `<provider>:manual` に書き込みます。
- `paste-token --expires-in <duration>` は、`365d` や `12h` などの
相対期間から絶対トークン有効期限を保存します。
- Anthropic 注: Anthropic スタッフは、OpenClaw 形式の Claude CLI 使用が再び許可されていると伝えたため、Anthropic が新しいポリシーを公開しない限り、OpenClaw はこの統合における Claude CLI の再利用と `claude -p` 使用を認可済みとして扱います。
- Anthropic の注記: Anthropic スタッフは、OpenClaw 形式の Claude CLI 使用が再び許可されたと伝えているため、Anthropic が新しいポリシーを公開しない限り、OpenClaw はこの連携において Claude CLI の再利用と `claude -p` の使用を認可済みとして扱います。
- Anthropic の `setup-token` / `paste-token` は、サポートされる OpenClaw トークンパスとして引き続き利用できますが、OpenClaw は現在、利用可能な場合は Claude CLI の再利用と `claude -p` を優先します。
## 関連

52
docs/ja-JP/cli/voicecall.md
View File

@ -1,31 +1,32 @@
---
read_when:
- voice-call Plugin を使用していて、CLI のエントリポイントを知りたい場合
- '`voicecall setup|smoke|call|continue|dtmf|status|tail|expose` のクイック例を見たい場合'
summary: '`openclaw voicecall` の CLI リファレンス（voice-call Plugin のコマンド画面）'
title: Voicecall
- voice-call プラグインを使用していて、CLI エントリポイントが必要な場合
- '`voicecall setup|smoke|call|continue|dtmf|status|tail|expose` の簡単な例が必要です'
summary: '`openclaw voicecall` の CLI リファレンス（音声通話 Plugin のコマンドサーフェス）'
title: 音声通話
x-i18n:
generated_at: "2026-04-25T13:44:56Z"
model: gpt-5.4
generated_at: "2026-05-01T05:00:28Z"
model: gpt-5.5
provider: openai
source_hash: 7c8b83ef75f792920024a67b0dee1b07aff9f55486de1149266c6d94854ca0fe
source_hash: 4090858a58b7defaff955a370c8cb0ff025ef68061e68a6c69a637de24707c0b
source_path: cli/voicecall.md
workflow: 15
workflow: 16
---
# `openclaw voicecall`
`voicecall` は Plugin 提供のコマンドです。voice-call Plugin がインストールされ、有効化されている場合にのみ表示されます。
`voicecall` はPluginが提供するコマンドです。音声通話Pluginがインストールされ、有効化されている場合にのみ表示されます。
主なドキュメント:
主要ドキュメント:
- voice-call Plugin: [Voice Call](/ja-JP/plugins/voice-call)
- 音声通話Plugin: [音声通話](/ja-JP/plugins/voice-call)
## よく使うコマンド
## 一般的なコマンド
```bash
openclaw voicecall setup
openclaw voicecall smoke
openclaw voicecall status --json
openclaw voicecall status --call-id <id>
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
openclaw voicecall continue --call-id <id> --message "Any questions?"
@ -33,22 +34,29 @@ openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
openclaw voicecall end --call-id <id>
```
`setup` はデフォルトで人間が読みやすい準備状況チェックを表示します。スクリプトでは `--json` を使用してください:
`setup` はデフォルトで人間が読める形式の準備状況チェックを出力します。
スクリプト向けには `--json` を使用します:
```bash
openclaw voicecall setup --json
```
外部プロバイダー（`twilio`、`telnyx`、`plivo`）では、setup は `publicUrl`、トンネル、または Tailscale 公開からパブリックな Webhook URL を解決する必要があります。loopback/private の serve フォールバックは、キャリアから到達できないため拒否されます。
`status` はデフォルトでアクティブな通話をJSONとして出力します。1件の通話を調べるには
`--call-id <id>` を渡します。
`smoke` は同じ準備状況チェックを実行します。`--to` と `--yes` の両方が指定されていない限り、実際の電話は発信しません:
外部プロバイダー (`twilio`, `telnyx`, `plivo`) では、セットアップ時に `publicUrl`、トンネル、または Tailscale の公開から公開
Webhook URLを解決できる必要があります。通信事業者が到達できないため、local loopback/プライベートの
配信フォールバックは拒否されます。
`smoke` は同じ準備状況チェックを実行します。`--to` と `--yes` の両方が存在しない限り、
実際の電話発信は行いません:
```bash
openclaw voicecall smoke --to "+15555550123" # ドライラン
openclaw voicecall smoke --to "+15555550123" --yes # 実際の通知コール
openclaw voicecall smoke --to "+15555550123" # dry run
openclaw voicecall smoke --to "+15555550123" --yes # live notify call
```
## Webhook の公開（Tailscale）
## Webhookの公開 (Tailscale)
```bash
openclaw voicecall expose --mode serve
@ -56,9 +64,9 @@ openclaw voicecall expose --mode funnel
openclaw voicecall expose --mode off
```
セキュリティに関する注記: Webhook エンドポイントは、信頼できるネットワークにのみ公開してください。可能な場合は Tailscale Funnel より Tailscale Serve を優先してください。
セキュリティ注記: Webhookエンドポイントは、信頼するネットワークにのみ公開してください。可能な場合は Funnel より Tailscale Serve を優先してください。
## 関連
## 関連項目
- [CLI reference](/ja-JP/cli)
- [Voice call plugin](/ja-JP/plugins/voice-call)
- [CLIリファレンス](/ja-JP/cli)
- [音声通話Plugin](/ja-JP/plugins/voice-call)

117
docs/ja-JP/concepts/commitments.md
View File

@ -1,38 +1,38 @@
---
read_when:
- OpenClaw に自然なフォローアップを記憶させたい場合
- 推論されたチェックインがリマインダーとどう異なるかを理解したい場合
- フォローアップの約束事項を確認または却下したい
- 推定されたチェックインがリマインダーとどう異なるかを理解したい場合
- フォローアップのコミットメントを確認または却下したい場合
sidebarTitle: Commitments
summary: 正確なリマインダーではないチェックイン向けの推論されたフォローアップメモリ
summary: 厳密なリマインダーではないチェックイン向けの推定フォローアップメモリ
title: 推定されたコミットメント
x-i18n:
generated_at: "2026-04-30T05:07:21Z"
generated_at: "2026-05-01T05:00:31Z"
model: gpt-5.5
provider: openai
source_hash: 3f51af0ac2c9841258fbeeb8f2f98dba6f438b8e0c9433f601a0504d6ef27111
source_hash: 78841d87fe749aa5b04a967218396df1c1a7884c5767b09215c96aee34fa2014
source_path: concepts/commitments.md
workflow: 16
---
コミットメントは短期間だけ残るフォローアップ記憶です。有効にすると、OpenClaw は
会話が将来の確認機会を生んだことに気づき、あとでそれを持ち出すように
覚えておけます。
コミットメントは短期間だけ保持されるフォローアップ用メモリです。有効にすると、OpenClaw は
会話から将来のチェックイン機会が生まれたことに気づき、あとで再び取り上げるように
記憶できます。
例:
- 明日の面接について話す。OpenClaw はその後に確認することがあります。
- 疲れ切っていると言う。OpenClaw はあとで眠れたか尋ねることがあります。
- 何かが変わったあとでフォローアップするとエージェントが言う。OpenClaw はその
未完了のループを追跡することがあります。
- 明日の面接について言及した場合。OpenClaw はその後に確認することがあります。
- 疲れ切っていると言った場合。OpenClaw はあとで眠れたかどうか尋ねることがあります。
- エージェントが、何かが変わったあとでフォローアップすると言った場合。OpenClaw はその未完了ループを
追跡することがあります。
コミットメントは `MEMORY.md` のような永続的な事実ではなく、正確な
リマインダーでもありません。記憶と自動化の中間にあります。OpenClaw は
会話に紐づく義務を記憶し、期限が来たら heartbeat がそれを届けます。
リマインダーでもありません。メモリと自動化の中間に位置します。OpenClaw は
会話に紐づいた義務を記憶し、期限が来ると heartbeat がそれを届けます。
## コミットメントを有効にする
コミットメントはデフォルトでオフです。config で有効にします:
コミットメントはデフォルトでオフです。config で有効にします。
```bash
openclaw config set commitments.enabled true
@ -50,60 +50,64 @@ openclaw config set commitments.maxPerDay 3
}
```
`commitments.maxPerDay` は、推測されたフォローアップをローリング 1 日あたり
エージェントセッションごとにいくつ届けられるかを制限します。デフォルトは `3` です。
`commitments.maxPerDay` は、ローリング方式の 1 日内でエージェントセッションごとに届けられる
推論されたフォローアップの数を制限します。デフォルトは `3` です。
## 仕組み
エージェントの返信後、OpenClaw は別のコンテキストで隠れたバックグラウンド抽出パスを
実行することがあります。そのパスは、推測されたフォローアップコミットメントだけを探します。
表示される会話には書き込まず、抽出について推論するようメインエージェントに
求めることもありません。
エージェントの返信後、OpenClaw は別コンテキストで非表示のバックグラウンド抽出パスを実行することがあります。
このパスは、推論されたフォローアップコミットメントだけを探します。
表示中の会話には書き込まず、メインのエージェントに抽出について
推論させることもありません。
高信頼度の候補が見つかると、OpenClaw は次の情報を含むコミットメントを保存します:
高信頼度の候補が見つかると、OpenClaw は次の情報を持つコミットメントを保存します。
- エージェント id
- エージェント ID
- セッションキー
- 元のチャネルと配信先
- 期限ウィンドウ
- 短い推奨の確認
- heartbeat が送信するかどうかを判断するために十分なソースコンテキスト
- 短いチェックイン案
- 送信するかどうかを heartbeat が判断するための、指示ではないメタデータ
配信は heartbeat を通じて行われます。コミットメントの期限が来ると、heartbeat は
同じエージェントとチャネルスコープの heartbeat ターンにそのコミットメントを追加します。
モデルは自然な確認を 1 つ送信するか、`HEARTBEAT_OK` と返信して却下できます。
同じエージェントおよびチャネルスコープの heartbeat ターンにコミットメントを追加します。
モデルは自然なチェックインを 1 件送信するか、`HEARTBEAT_OK` と返信して破棄できます。
heartbeat が `target: "none"` で設定されている場合、期限が来たコミットメントは
内部に残り、外部チェックインは送信されません。コミットメント配信プロンプトは
元の会話テキストを再生せず、期限が来たコミットメントの heartbeat ターンは
OpenClaw ツールなしで実行されます。
OpenClaw は、推測されたコミットメントを書き込んだ直後に配信することはありません。
期限時刻は、コミットメント作成後の少なくとも 1 heartbeat 間隔後に制限されるため、
フォローアップが推測されたその瞬間にそのまま返ってくることはありません。
OpenClaw は、推論されたコミットメントを書き込んだ直後に配信することはありません。
期限時刻は、コミットメント作成後少なくとも 1 回分の heartbeat 間隔以降に制限されます。
そのため、フォローアップが推論されたその瞬間にそのまま返ってくることはありません。
## スコープ
コミットメントは、作成された正確なエージェントとチャネルコンテキストにスコープされます。
Discord であるエージェントと会話中に推測されたフォローアップが、別のエージェント、
別のチャネル、または無関係なセッションによって配信されることはありません。
コミットメントは、作成された正確なエージェントおよびチャネルコンテキストにスコープされます。
Discord であるエージェントと話している間に推論されたフォローアップは、
別のエージェント、別のチャネル、または無関係なセッションからは配信されません。
このスコープは機能の一部です。自然な確認は、グローバルなリマインダーシステムではなく、
このスコープは機能の一部です。自然なチェックインは、グローバルなリマインダーシステムのようではなく、
同じ会話が続いているように感じられるべきです。
## コミットメントとリマインダー
| 必要なこと | 使用するもの |
| ----------------------------------------------- | ------------------------------------------- |
| 「午後 3 時にリマインドして」 | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) |
| 「20 分後に通知して」 | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) |
| 「このレポートを平日毎日実行して」 | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) |
| 「明日面接がある」 | コミットメント |
| 「一晩中起きていた」 | コミットメント |
| 「この未完了スレッドに回答しなかったらフォローアップして」 | コミットメント |
| 必要なこと | 使用するもの |
| ----------------------------------------------- | ---------------------------------------- |
| "Remind me at 3 PM" | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) |
| "Ping me in 20 minutes" | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) |
| "Run this report every weekday" | [スケジュール済みタスク](/ja-JP/automation/cron-jobs) |
| "I have an interview tomorrow" | コミットメント |
| "I was up all night" | コミットメント |
| "Follow up if I do not answer this open thread" | コミットメント |
ユーザーからの明確なリクエストは、すでにスケジューラーパスの対象です。コミットメントは
推測されたフォローアップ専用です。つまり、ユーザーがリマインダーを依頼していなくても、
会話から将来の有用な確認が明確に生まれた場面のためのものです。
ユーザーの明示的な依頼は、すでにスケジューラーの経路に属します。コミットメントは
推論されたフォローアップ専用です。つまり、ユーザーがリマインダーを依頼していなくても、
会話の中で将来の有用なチェックインが明確に生まれた場面です。
## コミットメントを管理する
保存されたコミットメントを確認してクリアするには CLI を使用します:
保存されたコミットメントの確認と消去には CLI を使用します。
```bash
openclaw commitments
@ -117,13 +121,12 @@ openclaw commitments dismiss cm_abc123
## プライバシーとコスト
コミットメント抽出は LLM パスを使用するため、有効にすると対象となるターンの後に
バックグラウンドのモデル使用量が追加されます。このパスはユーザーに表示される
会話からは隠されていますが、フォローアップが存在するかどうかを判断するために必要な
直近のやり取りを読み取ることがあります。
コミットメント抽出は LLM パスを使用するため、有効にすると対象ターンの後にバックグラウンドのモデル
使用量が追加されます。このパスはユーザーに表示される会話からは隠されていますが、
フォローアップが存在するかどうかを判断するために必要な直近のやり取りを読み取ることがあります。
保存されたコミットメントはローカルの OpenClaw 状態です。これは運用上の記憶であり、
長期記憶ではありません。この機能を無効にするには、次を実行します:
保存されたコミットメントはローカルの OpenClaw 状態です。これは運用上のメモリであり、
長期メモリではありません。この機能は次のコマンドで無効にできます。
```bash
openclaw config set commitments.enabled false
@ -134,17 +137,17 @@ openclaw config set commitments.enabled false
期待したフォローアップが表示されない場合:
- `commitments.enabled` が `true` であることを確認します。
- 保留中、却下済み、スヌーズ済み、または期限切れのレコードがないか
- 保留中、破棄済み、スヌーズ中、または期限切れのレコードについて
`openclaw commitments --all` を確認します。
- エージェントの heartbeat が実行中であることを確認します。
- エージェントで heartbeat が実行されていることを確認します。
- そのエージェントセッションで `commitments.maxPerDay` にすでに達していないか確認します。
- 明確なリマインダーはコミットメント抽出ではスキップされ、代わりに
- 明示的なリマインダーはコミットメント抽出ではスキップされ、代わりに
[スケジュール済みタスク](/ja-JP/automation/cron-jobs) に表示されるべきであることを覚えておいてください。
## 関連
- [記憶の概要](/ja-JP/concepts/memory)
- [Active memory](/ja-JP/concepts/active-memory)
- [メモリ概要](/ja-JP/concepts/memory)
- [Active Memory](/ja-JP/concepts/active-memory)
- [Heartbeat](/ja-JP/gateway/heartbeat)
- [スケジュール済みタスク](/ja-JP/automation/cron-jobs)
- [`openclaw commitments`](/ja-JP/cli/commitments)

157
docs/ja-JP/concepts/openclaw-sdk.md
View File

@ -1,21 +1,21 @@
---
read_when:
- OpenClaw と通信する外部アプリ、スクリプト、ダッシュボード、CI ジョブ、または IDE 拡張機能を構築している場合
- App SDKとPlugin SDKのどちらを選ぶか
- Gateway エージェントの実行、セッション、イベント、承認、モデル、またはツールと統合している
- OpenClaw と通信する外部アプリ、スクリプト、ダッシュボード、CIジョブ、またはIDE拡張機能を構築している
- App SDKとPlugin SDKのどちらを選ぶべきかを検討している
- Gateway のエージェント実行、セッション、イベント、承認、モデル、またはツールと連携する場合
sidebarTitle: App SDK
summary: 外部アプリ、スクリプト、ダッシュボード、CIジョブ、IDE拡張機能向けの公開 OpenClaw アプリ SDK
summary: 外部アプリ、スクリプト、ダッシュボード、CIジョブ、IDE拡張機能向けの公開 OpenClaw App SDK
title: OpenClaw アプリ SDK
x-i18n:
generated_at: "2026-04-30T05:09:17Z"
generated_at: "2026-05-01T05:00:28Z"
model: gpt-5.5
provider: openai
source_hash: 9c46454d172a25d329a796461982dc4307d3720a28df777eda8605996505e38c
source_hash: e531e985ca82026b230b03f8df5ab908d66e2b608e09c46af2ec060b9def0c24
source_path: concepts/openclaw-sdk.md
workflow: 16
---
**OpenClaw App SDK** は、OpenClaw プロセスの外部にあるアプリ向けの公開クライアント API です。スクリプト、ダッシュボード、CI ジョブ、IDE 拡張、またはその他の外部アプリが Gateway へ接続し、エージェント実行を開始し、イベントをストリーミングし、結果を待機し、作業をキャンセルし、Gateway リソースを調べる場合は `@openclaw/sdk` を使用します。
**OpenClaw App SDK** は、OpenClaw プロセス外のアプリ向けの公開クライアント API です。スクリプト、ダッシュボード、CI ジョブ、IDE 拡張機能、またはその他の外部アプリが Gateway に接続し、エージェント実行を開始し、イベントをストリームし、結果を待機し、作業をキャンセルし、Gateway リソースを調査する場合は `@openclaw/sdk` を使用します。
<Note>
App SDK は [Plugin SDK](/ja-JP/plugins/sdk-overview) とは異なります。
@ -23,38 +23,40 @@ x-i18n:
`openclaw/plugin-sdk/*` は、OpenClaw 内で実行され、プロバイダー、チャネル、ツール、フック、または信頼済みランタイムを登録する Plugin 専用です。
</Note>
## 現在同梱されているもの
## 現在提供されているもの
`@openclaw/sdk` には次が含まれます。
`@openclaw/sdk` には次が含まれています。
| サーフェス | 状態 | 役割 |
| ------------------------- | ---------- | ---------------------------------------------------------------------------- |
| `OpenClaw` | 利用可能 | メインのクライアントエントリーポイント。トランスポート、接続、リクエスト、イベントを所有します。 |
| `GatewayClientTransport` | 利用可能 | Gateway クライアントに支えられた WebSocket トランスポート。 |
| `oc.agents` | 利用可能 | エージェントハンドルの一覧表示、作成、更新、削除、取得を行います。 |
| `Agent.run()` | 利用可能 | Gateway の `agent` 実行を開始し、`Run` を返します。 |
| `oc.runs` | 利用可能 | 実行の作成、取得、待機、キャンセル、ストリーミングを行います。 |
| `Run.events()` | 利用可能 | 高速な実行向けのリプレイ付きで、実行単位の正規化済みイベントをストリーミングします。 |
| `Run.wait()` | 利用可能 | `agent.wait` を呼び出し、安定した `RunResult` を返します。 |
| `Run.cancel()` | 利用可能 | 実行 ID により `sessions.abort` を呼び出し、利用可能な場合はセッションキーも使います。 |
| `oc.sessions` | 利用可能 | セッションハンドルの作成、解決、送信、パッチ適用、圧縮、取得を行います。 |
| `Session.send()` | 利用可能 | `sessions.send` を呼び出し、`Run` を返します。 |
| `oc.models` | 利用可能 | `models.list` と現在の `models.authStatus` 状態 RPC を呼び出します。 |
| `oc.tools` | 一部対応 | ツールカタログと有効なツールを一覧表示します。直接のツール呼び出しは未接続です。 |
| `oc.approvals` | 利用可能 | Gateway の承認 RPC を通じて exec 承認の一覧表示と解決を行います。 |
| `oc.rawEvents()` | 利用可能 | 高度な利用者向けに生の Gateway イベントを公開します。 |
| `normalizeGatewayEvent()` | 利用可能 | 生の Gateway イベントを安定した SDK イベント形状へ変換します。 |
| サーフェス | 状態 | 機能 |
| ------------------------- | ------- | ---------------------------------------------------------------------------- |
| `OpenClaw` | 準備完了 | メインのクライアントエントリポイント。トランスポート、接続、リクエスト、イベントを所有します。 |
| `GatewayClientTransport` | 準備完了 | Gateway クライアントを基盤にした WebSocket トランスポート。 |
| `oc.agents` | 準備完了 | エージェントハンドルの一覧表示、作成、更新、削除、取得を行います。 |
| `Agent.run()` | 準備完了 | Gateway `agent` 実行を開始し、`Run` を返します。 |
| `oc.runs` | 準備完了 | 実行の作成、取得、待機、キャンセル、ストリームを行います。 |
| `Run.events()` | 準備完了 | 高速な実行向けのリプレイ付きで、実行ごとに正規化されたイベントをストリームします。 |
| `Run.wait()` | 準備完了 | `agent.wait` を呼び出し、安定した `RunResult` を返します。 |
| `Run.cancel()` | 準備完了 | 実行 ID により `sessions.abort` を呼び出し、利用可能な場合はセッションキーも使います。 |
| `oc.sessions` | 準備完了 | セッションハンドルの作成、解決、送信、パッチ、Compaction、取得を行います。 |
| `Session.send()` | 準備完了 | `sessions.send` を呼び出し、`Run` を返します。 |
| `oc.models` | 準備完了 | `models.list` と現在の `models.authStatus` ステータス RPC を呼び出します。 |
| `oc.tools` | 一部対応 | ツールカタログと有効なツールを一覧表示します。直接のツール呼び出しは接続されていません。 |
| `oc.artifacts` | 準備完了 | Gateway トランスクリプトアーティファクトの一覧表示、取得、ダウンロードを行います。 |
| `oc.approvals` | 準備完了 | Gateway 承認 RPC を通じて exec 承認を一覧表示および解決します。 |
| `oc.rawEvents()` | 準備完了 | 高度なコンシューマー向けに生の Gateway イベントを公開します。 |
| `normalizeGatewayEvent()` | 準備完了 | 生の Gateway イベントを安定した SDK イベント形状に変換します。 |
SDK は、これらのサーフェスで使われる中核型もエクスポートします。
SDK は、これらのサーフェスで使用される中核型もエクスポートします。
`AgentRunParams`、`RunResult`、`RunStatus`、`OpenClawEvent`、
`OpenClawEventType`、`GatewayEvent`、`OpenClawTransport`、
`GatewayRequestOptions`、`SessionCreateParams`、`SessionSendParams`、
`RuntimeSelection`、`EnvironmentSelection`、`WorkspaceSelection`、
`ApprovalMode`、および関連する結果型です。
`ArtifactSummary`、`ArtifactQuery`、`ArtifactsListResult`、
`ArtifactsGetResult`、`ArtifactsDownloadResult`、`RuntimeSelection`、
`EnvironmentSelection`、`WorkspaceSelection`、`ApprovalMode`、および関連する結果型です。
## Gateway への接続
## Gateway に接続する
明示的な Gateway URL でクライアントを作成するか、テストや埋め込みアプリランタイム向けにカスタムトランスポートを注入します。
明示的な Gateway URL でクライアントを作成するか、テストや組み込みアプリランタイム向けにカスタムトランスポートを注入します。
```typescript
import { OpenClaw } from "@openclaw/sdk";
@ -68,7 +70,7 @@ const oc = new OpenClaw({
await oc.connect();
```
`new OpenClaw({ gateway: "ws://..." })` は `url` と同等です。コンストラクターは `gateway: "auto"` オプションを受け付けますが、自動 Gateway 検出はまだ独立した SDK 機能ではありません。アプリが Gateway を検出する方法をすでに把握していない場合は `url` を渡してください。
`new OpenClaw({ gateway: "ws://..." })` は `url` と同等です。`gateway: "auto"` オプションはコンストラクターで受け付けられますが、自動 Gateway 検出はまだ独立した SDK 機能ではありません。アプリが Gateway の検出方法をまだ知らない場合は `url` を渡してください。
テストでは、`OpenClawTransport` を実装するオブジェクトを渡します。
@ -83,7 +85,7 @@ const oc = new OpenClaw({
});
```
## エージェントの実行
## エージェントを実行する
アプリがエージェントハンドルを必要とする場合は `oc.agents.get(id)` を使用し、その後 `agent.run()` を呼び出します。
@ -108,13 +110,13 @@ const result = await run.wait({ timeoutMs: 120_000 });
console.log(result.status);
```
`openai/gpt-5.5` のようなプロバイダー修飾モデル参照は、Gateway の `provider` と `model` のオーバーライドに分割されます。SDK 内の `timeoutMs` はミリ秒のままで、`agent` RPC 向けに Gateway のタイムアウト秒数へ変換されます。
`openai/gpt-5.5` のようなプロバイダー修飾付きモデル参照は、Gateway の `provider` と `model` のオーバーライドに分割されます。`timeoutMs` は SDK 内ではミリ秒のままで、`agent` RPC 向けに Gateway のタイムアウト秒数へ変換されます。
`run.wait()` は Gateway の `agent.wait` RPC を使用します。実行がまだアクティブな間に待機期限が切れた場合、実行自体がタイムアウトしたように見せかけるのではなく、`status: "accepted"` を返します。ランタイムのタイムアウト、中止された実行、キャンセルされた実行は、`timed_out` または `cancelled` に正規化されます。
`run.wait()` は Gateway の `agent.wait` RPC を使用します。実行がまだアクティブな間に待機期限が切れた場合、実行自体がタイムアウトしたかのように装うのではなく、`status: "accepted"` を返します。ランタイムのタイムアウト、中止された実行、キャンセルされた実行は、`timed_out` または `cancelled` に正規化されます。
## セッションの作成と再利用
## セッションを作成して再利用する
アプリが永続的なトランスクリプト状態を必要とする場合は、セッションを使用します。
アプリが永続的なトランスクリプト状態を必要とする場合はセッションを使用します。
```typescript
const session = await oc.sessions.create({
@ -126,7 +128,7 @@ const run = await session.send("Prepare release notes from the current diff.");
await run.wait();
```
`Session.send()` は `sessions.send` を呼び出し、`Run` を返します。セッションハンドルは次にも対応しています。
`Session.send()` は `sessions.send` を呼び出し、`Run` を返します。セッションハンドルは次もサポートします。
```typescript
await session.abort(run.id);
@ -134,9 +136,9 @@ await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });
```
## イベントのストリーミング
## イベントをストリームする
SDK は、生の Gateway イベントを安定した `OpenClawEvent` エンベロープへ正規化します。
SDK は生の Gateway イベントを安定した `OpenClawEvent` エンベロープに正規化します。
```typescript
type OpenClawEvent = {
@ -156,30 +158,30 @@ type OpenClawEvent = {
一般的なイベント型は次のとおりです。
| イベント型 | 元の Gateway イベント |
| イベント型 | ソース Gateway イベント |
| --------------------- | ------------------------------------------- |
| `run.started` | `agent` ライフサイクル開始 |
| `run.completed` | `agent` ライフサイクル終了 |
| `run.failed` | `agent` ライフサイクルエラー |
| `run.cancelled` | 中止/キャンセルされたライフサイクル終了 |
| `run.timed_out` | タイムアウトのライフサイクル終了 |
| `assistant.delta` | アシスタントのストリーミング差分 |
| `assistant.message` | アシスタントメッセージ |
| `thinking.delta` | 思考またはプランのストリーム |
| `tool.call.started` | ツール/項目/コマンドの開始 |
| `tool.call.delta` | ツール/項目/コマンドの更新 |
| `tool.call.completed` | ツール/項目/コマンドの完了 |
| `tool.call.failed` | ツール/項目/コマンドの失敗またはブロック状態 |
| `approval.requested` | exec または Plugin 承認リクエスト |
| `approval.resolved` | exec または Plugin 承認の解決 |
| `session.created` | `sessions.changed` の作成 |
| `session.updated` | `sessions.changed` の更新 |
| `session.compacted` | `sessions.changed` の圧縮 |
| `task.updated` | タスク更新イベント |
| `artifact.updated` | パッチストリームイベント |
| `run.started` | `agent` ライフサイクル開始 |
| `run.completed` | `agent` ライフサイクル終了 |
| `run.failed` | `agent` ライフサイクルエラー |
| `run.cancelled` | 中止またはキャンセルされたライフサイクル終了 |
| `run.timed_out` | タイムアウトによるライフサイクル終了 |
| `assistant.delta` | アシスタントのストリーミング差分 |
| `assistant.message` | アシスタントメッセージ |
| `thinking.delta` | 思考またはプランのストリーム |
| `tool.call.started` | ツール、項目、コマンドの開始 |
| `tool.call.delta` | ツール、項目、コマンドの更新 |
| `tool.call.completed` | ツール、項目、コマンドの完了 |
| `tool.call.failed` | ツール、項目、コマンドの失敗またはブロック状態 |
| `approval.requested` | exec または Plugin 承認リクエスト |
| `approval.resolved` | exec または Plugin 承認の解決 |
| `session.created` | `sessions.changed` 作成 |
| `session.updated` | `sessions.changed` 更新 |
| `session.compacted` | `sessions.changed` Compaction |
| `task.updated` | タスク更新イベント |
| `artifact.updated` | パッチストリームイベント |
| `raw` | まだ安定した SDK マッピングがない任意のイベント |
`Run.events()` はイベントを 1 つの実行 ID に絞り込み、高速な実行向けに、すでに確認済みのイベントをリプレイします。つまり、記載されている次のフローは安全です。
`Run.events()` はイベントを 1 つの実行 ID に絞り込み、高速な実行のために既に確認済みのイベントをリプレイします。つまり、ドキュメント化された次のフローは安全です。
```typescript
const run = await agent.run("Summarize the latest session.");
@ -193,7 +195,7 @@ for await (const event of run.events()) {
アプリ全体のストリームには `oc.events()` を使用します。生の Gateway フレームには `oc.rawEvents()` を使用します。
## モデル、ツール、承認
## モデル、ツール、アーティファクト、承認
モデルヘルパーは現在の Gateway メソッドに対応します。
@ -209,6 +211,19 @@ await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
```
アーティファクトヘルパーは、セッション、実行、またはタスクコンテキスト向けの Gateway アーティファクト投影を公開します。各呼び出しには、明示的な `sessionKey`、`runId`、または `taskId` スコープのいずれか 1 つが必要です。
```typescript
const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });
const first = artifacts[0];
if (first) {
const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });
const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });
console.log(download.encoding, download.url);
}
```
承認ヘルパーは exec 承認 RPC を使用します。
```typescript
@ -216,9 +231,9 @@ const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });
```
## 現時点で明示的に非対応
## 現在明示的にサポートされていないもの
SDK には目指すプロダクトモデルの名前が含まれていますが、Gateway RPC が存在するかのように黙って振る舞うことはありません。現在、次の呼び出しは明示的な非対応エラーを投げます。
SDK には今後目指すプロダクトモデル用の名前が含まれていますが、Gateway RPC が存在するかのように暗黙的に装うことはありません。現在、これらの呼び出しは明示的な未サポートエラーをスローします。
```typescript
await oc.tasks.list();
@ -227,26 +242,22 @@ await oc.tasks.cancel("task-id");
await oc.tools.invoke("tool-name", {});
await oc.artifacts.list();
await oc.artifacts.get("artifact-id");
await oc.artifacts.download("artifact-id");
await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
await oc.environments.delete("environment-id");
```
実行単位の `workspace`、`runtime`、`environment`、`approvals` フィールドは将来の形状として型付けされていますが、現在の Gateway は `agent` RPC でこれらのオーバーライドをサポートしていません。呼び出し元がこれらを渡した場合、SDK は実行を送信する前に例外を投げます。これにより、デフォルトのワークスペース、ランタイム、環境、または承認の挙動で作業が誤って実行されることを防ぎます。
実行ごとの `workspace`、`runtime`、`environment`、`approvals` フィールドは将来の形状として型付けされていますが、現在の Gateway は `agent` RPC でこれらのオーバーライドをサポートしていません。呼び出し元がそれらを渡した場合、作業がデフォルトのワークスペース、ランタイム、環境、または承認動作で誤って実行されないよう、SDK は実行を送信する前にスローします。
## App SDK と Plugin SDK の違い
## App SDK と Plugin SDK
コードが OpenClaw の外部にある場合は App SDK を使用します。
- エージェント実行を開始または監視する Node スクリプト
- Gateway を呼び出す CI ジョブ
- ダッシュボードと管理パネル
- IDE 拡張
- IDE 拡張機能
- チャネル Plugin になる必要がない外部ブリッジ
- 偽または実際の Gateway トランスポートを使う統合テスト
@ -258,7 +269,7 @@ await oc.environments.delete("environment-id");
- エージェントハーネス Plugin
- 信頼済みランタイムヘルパー
App SDK コードは `@openclaw/sdk` からインポートする必要があります。Plugin コードは、ドキュメント化された `openclaw/plugin-sdk/*` サブパスからインポートする必要があります。この 2 つの契約を混在させないでください。
App SDK コードは `@openclaw/sdk` からインポートする必要があります。Plugin コードは、ドキュメント化された `openclaw/plugin-sdk/*` サブパスからインポートする必要があります。この 2 つのコントラクトを混在させないでください。
## 関連ドキュメント
@ -269,4 +280,4 @@ App SDK コードは `@openclaw/sdk` からインポートする必要があり
- [セッション](/ja-JP/concepts/session)
- [バックグラウンドタスク](/ja-JP/automation/tasks)
- [ACP エージェント](/ja-JP/tools/acp-agents)
- [Plugin SDK 概要](/ja-JP/plugins/sdk-overview)
- [Plugin SDK の概要](/ja-JP/plugins/sdk-overview)

292
docs/ja-JP/gateway/config-channels.md
View File

@ -1,24 +1,24 @@
---
read_when:
- チャンネルPluginの設定（認証、アクセス制御、複数アカウント）
- チャネル Plugin の設定（認証、アクセス制御、マルチアカウント）
- チャネルごとの設定キーのトラブルシューティング
- DMポリシー、グループポリシー、またはメンションゲーティングの監査
- DM ポリシー、グループポリシー、またはメンションゲーティングの監査
summary: 'チャネル設定: Slack、Discord、Telegram、WhatsApp、Matrix、iMessage などにわたるアクセス制御、ペアリング、チャネルごとのキー'
title: 設定 — チャンネル
x-i18n:
generated_at: "2026-04-30T16:28:52Z"
generated_at: "2026-05-01T05:00:30Z"
model: gpt-5.5
provider: openai
source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915
source_hash: ce1571d51e026182d49b935780a986780a90b05afc0acca027b2541b80a1aac2
source_path: gateway/config-channels.md
workflow: 16
---
`channels.*` 配下のチャンネル別設定キー。DM とグループアクセス、
マルチアカウント構成、メンション制御、Slack、Discord、
Telegram、WhatsApp、Matrix、iMessage、およびその他の同梱チャンネル Plugin のチャンネル別キーを扱います。
複数アカウント構成、メンションゲート、Slack、Discord、
Telegram、WhatsApp、Matrix、iMessage、その他の同梱チャンネル Plugin 用のチャンネル別キーを扱います。
エージェント、ツール、Gateway ランタイム、およびその他のトップレベルキーについては、
エージェント、ツール、Gateway ランタイム、その他のトップレベルキーについては、
[設定リファレンス](/ja-JP/gateway/configuration-reference)を参照してください。
## チャンネル
@ -29,28 +29,28 @@ Telegram、WhatsApp、Matrix、iMessage、およびその他の同梱チャン
すべてのチャンネルは DM ポリシーとグループポリシーに対応しています。
| DM ポリシー | 挙動 |
| DM ポリシー | 動作 |
| ------------------- | --------------------------------------------------------------- |
| `pairing` (デフォルト) | 未知の送信者は一度限りのペアリングコードを受け取り、所有者の承認が必要 |
| `allowlist` | `allowFrom` 内（またはペアリング済みの許可ストア内）の送信者のみ |
| `pairing` (default) | 未知の送信者には一度限りのペアリングコードが届き、所有者の承認が必要 |
| `allowlist` | `allowFrom` 内（またはペアリング済み許可ストア内）の送信者のみ |
| `open` | すべての受信 DM を許可（`allowFrom: ["*"]` が必要） |
| `disabled` | すべての受信 DM を無視 |
| グループポリシー | 挙動 |
| グループポリシー | 動作 |
| --------------------- | ------------------------------------------------------ |
| `allowlist` (デフォルト) | 設定済みの許可リストに一致するグループのみ |
| `open` | グループ許可リストをバイパス（メンション制御は引き続き適用） |
| `disabled` | すべてのグループ/ルームメッセージをブロック |
| `allowlist` (default) | 設定された許可リストに一致するグループのみ |
| `open` | グループ許可リストをバイパス（メンションゲートは引き続き適用） |
| `disabled` | すべてのグループ/ルームメッセージをブロック |
<Note>
`channels.defaults.groupPolicy` は、プロバイダーの `groupPolicy` が未設定の場合のデフォルトを設定します。
ペアリングコードは 1 時間後に期限切れになります。保留中の DM ペアリングリクエストは **チャンネルごとに 3 件**に制限されます。
プロバイダーブロックが完全に存在しない場合（`channels.<provider>` がない場合）、ランタイムのグループポリシーは起動時の警告付きで `allowlist`（フェイルクローズ）にフォールバックします。
ペアリングコードは 1 時間後に期限切れになります。保留中の DM ペアリング要求は **チャンネルごとに 3 件** に制限されます。
プロバイダーブロック全体が存在しない場合（`channels.<provider>` がない場合）、ランタイムのグループポリシーは起動時の警告付きで `allowlist`（fail-closed）にフォールバックします。
</Note>
### チャンネルモデルの上書き
`channels.modelByChannel` を使用して、特定のチャンネル ID をモデルに固定します。値には `provider/model` または設定済みのモデルエイリアスを指定できます。チャンネルマッピングは、セッションにモデルの上書きがまだない場合（たとえば `/model` で設定された場合）に適用されます。
`channels.modelByChannel` を使用して、特定のチャンネル ID をモデルに固定します。値には `provider/model` または設定済みのモデルエイリアスを指定できます。チャンネルマッピングは、セッションに既存のモデル上書き（例: `/model` で設定）がない場合に適用されます。
```json5
{
@ -71,9 +71,9 @@ Telegram、WhatsApp、Matrix、iMessage、およびその他の同梱チャン
}
```
### チャンネルのデフォルトと Heartbeat
### チャンネルデフォルトと Heartbeat
プロバイダー間で共有するグループポリシーと Heartbeat の挙動には `channels.defaults` を使用します。
プロバイダー間で共有されるグループポリシーと Heartbeat の動作には、`channels.defaults` を使用します。
```json5
{
@ -91,11 +91,11 @@ Telegram、WhatsApp、Matrix、iMessage、およびその他の同梱チャン
}
```
- `channels.defaults.groupPolicy`: プロバイダーレベルの `groupPolicy` が未設定の場合のフォールバック用グループポリシー。
- `channels.defaults.contextVisibility`: すべてのチャンネルに対する補足コンテキスト表示モードのデフォルト。値: `all`（デフォルト、引用/スレッド/履歴コンテキストをすべて含める）、`allowlist`（許可リストに含まれる送信者からのコンテキストのみ含める）、`allowlist_quote`（allowlist と同じだが、明示的な引用/返信コンテキストは保持する）。チャンネル別の上書き: `channels.<channel>.contextVisibility`。
- `channels.defaults.groupPolicy`: プロバイダーレベルの `groupPolicy` が未設定の場合のフォールバックグループポリシー。
- `channels.defaults.contextVisibility`: すべてのチャンネルのデフォルト補足コンテキスト表示モード。値: `all`（デフォルト、すべての引用/スレッド/履歴コンテキストを含める）、`allowlist`（許可リスト内の送信者からのコンテキストのみを含める）、`allowlist_quote`（allowlist と同じだが、明示的な引用/返信コンテキストは保持）。チャンネル別上書き: `channels.<channel>.contextVisibility`。
- `channels.defaults.heartbeat.showOk`: Heartbeat 出力に正常なチャンネルステータスを含める。
- `channels.defaults.heartbeat.showAlerts`: Heartbeat 出力に劣化/エラーステータスを含める。
- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケータースタイルの Heartbeat 出力を描画する。
- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケーター形式の Heartbeat 出力を描画する。
### WhatsApp
@ -139,7 +139,7 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し
}
```
<Accordion title="マルチアカウント WhatsApp">
<Accordion title="複数アカウント WhatsApp">
```json5
{
@ -157,9 +157,9 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し
}
```
- 送信コマンドは、存在する場合はアカウント `default` にデフォルトで送られます。存在しない場合は、設定済みアカウント ID の先頭（ソート済み）が使われます。
- 送信コマンドは、存在する場合はアカウント `default` をデフォルトにします。それ以外の場合は、設定済みアカウント ID のうち最初のもの（ソート後）を使用します。
- 任意の `channels.whatsapp.defaultAccount` は、設定済みアカウント ID と一致する場合に、そのフォールバックのデフォルトアカウント選択を上書きします。
- 従来の単一アカウント Baileys 認証ディレクトリは、`openclaw doctor` によって `whatsapp/default` へ移行されます。
- レガシーの単一アカウント Baileys 認証ディレクトリは、`openclaw doctor` によって `whatsapp/default` に移行されます。
- アカウント別の上書き: `channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
</Accordion>
@ -219,13 +219,13 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し
}
```
- Bot トークン: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。シンボリックリンクは拒否）、デフォルトアカウントのフォールバックとして `TELEGRAM_BOT_TOKEN` を使用します。
- `apiRoot` は Telegram Bot API のルートのみです。`https://api.telegram.org/bot<TOKEN>` ではなく、`https://api.telegram.org` または自己ホスト/プロキシのルートを使用してください。`openclaw doctor --fix` は、誤って末尾に付いた `/bot<TOKEN>` サフィックスを削除します。
- 任意の `channels.telegram.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。
- マルチアカウント構成（2 つ以上のアカウント ID）では、フォールバックルーティングを避けるために明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定してください。これがない、または無効な場合、`openclaw doctor` が警告します。
- ボットトークン: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。シンボリックリンクは拒否）。デフォルトアカウントのフォールバックとして `TELEGRAM_BOT_TOKEN` を使用します。
- `apiRoot` は Telegram Bot API のルートのみです。`https://api.telegram.org/bot<TOKEN>` ではなく、`https://api.telegram.org` または自前ホスト/プロキシのルートを使用してください。`openclaw doctor --fix` は、誤って付いた末尾の `/bot<TOKEN>` サフィックスを削除します。
- 任意の `channels.telegram.defaultAccount` は、設定済みアカウント ID と一致する場合に、デフォルトアカウント選択を上書きします。
- 複数アカウント構成（2 個以上のアカウント ID）では、フォールバックルーティングを避けるために明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定します。これがない、または無効な場合、`openclaw doctor` が警告します。
- `configWrites: false` は、Telegram 起点の設定書き込み（スーパーグループ ID 移行、`/config set|unset`）をブロックします。
- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、フォーラムトピック用の永続的な ACP バインディングを設定します（`match.peer.id` では正規形式の `chatId:topic:topicId` を使用）。フィールドの意味は [ACP エージェント](/ja-JP/tools/acp-agents#channel-specific-settings)で共有されています。
- Telegram ストリームプレビューは `sendMessage` + `editMessageText` を使用します（ダイレクトチャットとグループチャットで動作）。
- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、フォーラムトピック用の永続 ACP バインディングを設定します（`match.peer.id` では正規形式の `chatId:topic:topicId` を使用）。フィールドの意味は [ACP エージェント](/ja-JP/tools/acp-agents#channel-specific-settings)で共有されています。
- Telegram ストリームプレビューは `sendMessage` + `editMessageText` を使用します（ダイレクトチャットとグループチャットで動作します）。
- リトライポリシー: [リトライポリシー](/ja-JP/concepts/retry)を参照してください。
### Discord
@ -329,33 +329,33 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し
```
- トークン: `channels.discord.token`。デフォルトアカウントのフォールバックとして `DISCORD_BOT_TOKEN` を使用します。
- 明示的な Discord `token` を提供する直接の送信呼び出しは、その呼び出しにそのトークンを使用します。アカウントの再試行/ポリシー設定は、引き続きアクティブなランタイムスナップショット内で選択されたアカウントから取得されます。
- 任意の `channels.discord.defaultAccount` は、構成済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。
- 配信ターゲットには `user:<id>` (DM) または `channel:<id>` (ギルドチャンネル) を使用します。裸の数値 ID は拒否されます。
- ギルドスラッグは小文字で、空白は `-` に置換されます。チャンネルキーにはスラッグ化された名前を使用します (`#` なし)。ギルド ID を推奨します。
- ボットが作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効化します。ボットにメンションしているボットメッセージのみを受け付けるには `allowBots: "mentions"` を使用します (自身のメッセージは引き続きフィルターされます)。
- `channels.discord.guilds.<id>.ignoreOtherMentions` (およびチャンネル上書き) は、ボットではなく別のユーザーまたはロールにメンションしているメッセージを破棄します (@everyone/@here を除く)。
- 明示的な Discord `token` を指定する直接アウトバウンド呼び出しは、その呼び出しにそのトークンを使用します。アカウントの再試行/ポリシー設定は、引き続きアクティブなランタイムスナップショットで選択されたアカウントから取得されます。
- 任意の `channels.discord.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウントの選択を上書きします。
- 配信先には `user:<id>` (DM) または `channel:<id>` (ギルドチャンネル) を使用します。裸の数値 ID は拒否されます。
- ギルドスラッグは小文字で、空白は `-` に置換されます。チャンネルキーはスラッグ化された名前 (`#` なし) を使用します。ギルド ID を推奨します。
- ボットが作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効になります。ボットにメンションするボットメッセージだけを受け付けるには `allowBots: "mentions"` を使用します (自身のメッセージは引き続きフィルタされます)。
- `channels.discord.guilds.<id>.ignoreOtherMentions` (およびチャンネル上書き) は、別のユーザーまたはロールにメンションしているがボットにはメンションしていないメッセージを破棄します (@everyone/@here を除く)。
- `maxLinesPerMessage` (デフォルト 17) は、2000 文字未満でも縦に長いメッセージを分割します。
- `channels.discord.threadBindings` は Discord のスレッドバインド型ルーティングを制御します。
- `enabled`: スレッドバインド型セッション機能 (`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインドされた配信/ルーティング) に対する Discord 上書き
- `idleHours`: 非アクティブ時の自動アンフォーカスまでの時間 (時間単位) に対する Discord 上書き (`0` で無効)
- `maxAgeHours`: ハード最大有効期間 (時間単位) に対する Discord 上書き (`0` で無効)
- `spawnSubagentSessions`: `sessions_spawn({ thread: true })` の自動スレッド作成/バインド用のオプトインスイッチ
- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、チャンネルとスレッド用の永続 ACP バインディングを構成します (`match.peer.id` にはチャンネル/スレッド ID を使用)。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) で共有されています。
- `channels.discord.ui.components.accentColor` は、Discord components v2 コンテナのアクセントカラーを設定します。
- `channels.discord.voice` は、Discord ボイスチャンネル会話と、任意の自動参加 + LLM + TTS 上書きを有効化します。
- `channels.discord.threadBindings` は Discord のスレッドバインド型ルーティングを制御します:
- `enabled`: スレッドバインド型セッション機能 (`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインドされた配信/ルーティング) の Discord 上書き
- `idleHours`: 非アクティブ時の自動フォーカス解除の Discord 上書き (時間単位、`0` で無効)
- `maxAgeHours`: ハード最大期間の Discord 上書き (時間単位、`0` で無効)
- `spawnSubagentSessions`: `sessions_spawn({ thread: true })` による自動スレッド作成/バインドのオプトインスイッチ
- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、チャンネルとスレッド用の永続的な ACP バインディングを設定します (`match.peer.id` にはチャンネル/スレッド ID を使用します)。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) で共有されています。
- `channels.discord.ui.components.accentColor` は Discord コンポーネント v2 コンテナのアクセントカラーを設定します。
- `channels.discord.voice` は Discord ボイスチャンネル会話と、任意の自動参加 + LLM + TTS 上書きを有効にします。
- `channels.discord.voice.model` は、Discord ボイスチャンネル応答に使用する LLM モデルを任意で上書きします。
- `channels.discord.voice.daveEncryption` と `channels.discord.voice.decryptionFailureTolerance` は、`@discordjs/voice` の DAVE オプションにそのまま渡されます (デフォルトは `true` と `24`)。
- OpenClaw はさらに、復号失敗が繰り返された後にボイスセッションを退出/再参加することで、ボイス受信の回復を試みます。
- OpenClaw はさらに、復号失敗が繰り返された後にボイスセッションから退出/再参加することで、ボイス受信の復旧を試みます。
- `channels.discord.streaming` は正規のストリームモードキーです。レガシーの `streamMode` と真偽値の `streaming` 値は自動移行されます。
- `channels.discord.autoPresence` はランタイム可用性をボットプレゼンスにマップし (healthy => online, degraded => idle, exhausted => dnd)、任意のステータステキスト上書きを許可します。
- `channels.discord.dangerouslyAllowNameMatching` は、可変の名前/タグ照合を再有効化します (緊急互換モード)。
- `channels.discord.autoPresence` はランタイムの可用性をボットプレゼンスに対応付け (healthy => online、degraded => idle、exhausted => dnd)、任意のステータステキスト上書きを許可します。
- `channels.discord.dangerouslyAllowNameMatching` は、可変の名前/タグ照合を再度有効にします (緊急互換モード)。
- `channels.discord.execApprovals`: Discord ネイティブの exec 承認配信と承認者認可。
- `enabled`: `true`、`false`、または `"auto"` (デフォルト)。自動モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効化されます。
- `enabled`: `true`、`false`、または `"auto"` (デフォルト)。自動モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効になります。
- `approvers`: exec リクエストの承認を許可された Discord ユーザー ID。省略時は `commands.ownerAllowFrom` にフォールバックします。
- `agentFilter`: 任意のエージェント ID 許可リスト。すべてのエージェントの承認を転送するには省略します。
- `sessionFilter`: 任意のセッションキーパターン (部分文字列または正規表現)。
- `target`: 承認プロンプトの送信先。`"dm"` (デフォルト) は承認者 DM に送信し、`"channel"` は発信元チャンネルに送信し、`"both"` は両方に送信します。ターゲットに `"channel"` が含まれる場合、ボタンは解決済みの承認者のみが使用できます。
- `target`: 承認プロンプトの送信先。`"dm"` (デフォルト) は承認者の DM に送信し、`"channel"` は発信元チャンネルに送信し、`"both"` は両方に送信します。target に `"channel"` が含まれる場合、ボタンは解決済みの承認者のみ使用できます。
- `cleanupAfterResolve`: `true` の場合、承認、拒否、またはタイムアウト後に承認 DM を削除します。
**リアクション通知モード:** `off` (なし)、`own` (ボットのメッセージ、デフォルト)、`all` (すべてのメッセージ)、`allowlist` (すべてのメッセージで `guilds.<id>.users` から)。
@ -392,8 +392,8 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し
- サービスアカウント JSON: インライン (`serviceAccount`) またはファイルベース (`serviceAccountFile`)。
- サービスアカウント SecretRef もサポートされています (`serviceAccountRef`)。
- 環境変数フォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 配信ターゲットには `spaces/<spaceId>` または `users/<userId>` を使用します。
- `channels.googlechat.dangerouslyAllowNameMatching` は、可変のメールプリンシパル照合を再有効化します (緊急互換モード)。
- 配信先には `spaces/<spaceId>` または `users/<userId>` を使用します。
- `channels.googlechat.dangerouslyAllowNameMatching` は、可変のメールプリンシパル照合を再度有効にします (緊急互換モード)。
### Slack
@ -465,35 +465,35 @@ WhatsApp は Gateway の Web チャンネル（Baileys Web）経由で動作し
}
```
- **Socket mode** には `botToken` と `appToken` の両方が必要です (デフォルトアカウントの環境変数フォールバックには `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`)。
- **HTTP mode** には `botToken` と `signingSecret` (ルートまたはアカウントごと) が必要です。
- `socketMode` は、Slack SDK Socket Mode トランスポート調整を公開 Bolt receiver API にそのまま渡します。ping/pong タイムアウトまたは古い websocket 動作を調査する場合にのみ使用してください。
- `botToken`、`appToken`、`signingSecret`、`userToken` はプレーンテキスト文字列または SecretRef オブジェクトを受け付けます。
- Slack アカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、および HTTP mode の `signingSecretStatus` など、認証情報ごとのソース/ステータスフィールドを公開します。`configured_unavailable` は、アカウントが SecretRef 経由で構成されているものの、現在のコマンド/ランタイムパスでシークレット値を解決できなかったことを意味します。
- `configWrites: false` は、Slack から開始される構成書き込みをブロックします。
- 任意の `channels.slack.defaultAccount` は、構成済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。
- **ソケットモード** には `botToken` と `appToken` の両方が必要です (デフォルトアカウントの環境変数フォールバックは `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`)。
- **HTTP モード** には `botToken` と `signingSecret` (ルートまたはアカウントごと) が必要です。
- `socketMode` は Slack SDK のソケットモードトランスポート調整を公開 Bolt レシーバー API にそのまま渡します。ping/pong タイムアウトや古い websocket 挙動を調査する場合にのみ使用します。
- `botToken`、`appToken`、`signingSecret`、`userToken` は、平文文字列または SecretRef オブジェクトを受け付けます。
- Slack アカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、および HTTP モードでは `signingSecretStatus` など、認証情報ごとのソース/ステータスフィールドを公開します。`configured_unavailable` は、そのアカウントが SecretRef で設定されているものの、現在のコマンド/ランタイムパスでシークレット値を解決できなかったことを意味します。
- `configWrites: false` は Slack 起点の設定書き込みをブロックします。
- 任意の `channels.slack.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウントの選択を上書きします。
- `channels.slack.streaming.mode` は正規の Slack ストリームモードキーです。`channels.slack.streaming.nativeTransport` は Slack のネイティブストリーミングトランスポートを制御します。レガシーの `streamMode`、真偽値の `streaming`、および `nativeStreaming` 値は自動移行されます。
- 配信ターゲットには `user:<id>` (DM) または `channel:<id>` を使用します。
- 配信先には `user:<id>` (DM) または `channel:<id>` を使用します。
**リアクション通知モード:** `off`、`own` (デフォルト)、`all`、`allowlist` (`reactionAllowlist` から)。
**スレッドセッション分離:** `thread.historyScope` はスレッドごと (デフォルト) またはチャンネル全体で共有です。`thread.inheritParent` は親チャンネルのトランスクリプトを新しいスレッドにコピーします。
**スレッドセッション分離:** `thread.historyScope` はスレッドごと (デフォルト) またはチャンネル全体で共有されます。`thread.inheritParent` は親チャンネルのトランスクリプトを新しいスレッドにコピーします。
- Slack ネイティブストリーミングと Slack アシスタント風の「is typing...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベル DM はデフォルトでスレッド外のままなので、スレッド形式のプレビューではなく `typingReaction` または通常配信を使用します。
- `typingReaction` は、返信の実行中に受信 Slack メッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` のような Slack 絵文字ショートコードを使用してください。
- `channels.slack.execApprovals`: Slack ネイティブの exec 承認配信と承認者認可。Discord と同じスキーマです: `enabled` (`true`/`false`/`"auto"`)、`approvers` (Slack ユーザー ID)、`agentFilter`、`sessionFilter`、および `target` (`"dm"`、`"channel"`、または `"both"`)。
- Slack ネイティブストリーミングと Slack アシスタント風の「入力中...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベルの DM はデフォルトでスレッド外のままなので、スレッド風プレビューの代わりに `typingReaction` または通常の配信を使用します。
- `typingReaction` は、返信の実行中に受信 Slack メッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` などの Slack 絵文字ショートコードを使用します。
- `channels.slack.execApprovals`: Slack ネイティブの exec 承認配信と承認者認可。Discord と同じスキーマです: `enabled` (`true`/`false`/`"auto"`)、`approvers` (Slack ユーザー ID)、`agentFilter`、`sessionFilter`、`target` (`"dm"`、`"channel"`、または `"both"`)。
| アクショングループ | デフォルト | 注記 |
| アクショングループ | デフォルト | 注記 |
| ------------ | ------- | ---------------------- |
| reactions | 有効 | リアクション + リアクション一覧 |
| messages | 有効 | 読み取り/送信/編集/削除 |
| pins | 有効 | ピン留め/ピン解除/一覧 |
| memberInfo | 有効 | メンバー情報 |
| emojiList | 有効 | カスタム絵文字一覧 |
| messages | 有効 | 読み取り/送信/編集/削除 |
| pins | 有効 | ピン留め/ピン解除/一覧 |
| memberInfo | 有効 | メンバー情報 |
| emojiList | 有効 | カスタム絵文字一覧 |
### Mattermost
Mattermost は現在の OpenClaw リリースではバンドルされた Plugin として提供されています。古いビルドまたはカスタムビルドでは、`openclaw plugins install @openclaw/mattermost` で現在の npm パッケージをインストールできます。npm が OpenClaw 所有のパッケージを非推奨として報告する場合は、新しい npm パッケージが公開されるまで、バンドルされた Plugin またはローカルチェックアウトを使用してください。
Mattermost は現在の OpenClaw リリースではバンドル Plugin として同梱されています。古いビルドやカスタムビルドでは、`openclaw plugins install @openclaw/mattermost` で現在の npm パッケージをインストールできます。npm が OpenClaw 所有のパッケージを非推奨として報告する場合は、新しい npm パッケージが公開されるまで、バンドル Plugin またはローカルチェックアウトを使用してください。
```json5
{
@ -527,14 +527,14 @@ Mattermost は現在の OpenClaw リリースではバンドルされた Plugin
Mattermost ネイティブコマンドが有効な場合:
- `commands.callbackPath` はフル URL ではなく、パス (例: `/api/channels/mattermost/command`) でなければなりません。
- `commands.callbackUrl` は OpenClaw Gateway エンドポイントに解決され、Mattermost サーバーから到達可能でなければなりません。
- ネイティブスラッシュコールバックは、スラッシュコマンド登録中に Mattermost から返されるコマンドごとのトークンで認証されます。登録に失敗した場合、または有効化されたコマンドがない場合、OpenClaw は `Unauthorized: invalid command token.` でコールバックを拒否します。
- private/tailnet/internal コールバックホストでは、Mattermost が `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含めることを要求する場合があります。フル URL ではなく、ホスト/ドメイン値を使用してください。
- `channels.mattermost.configWrites`: Mattermost から開始される構成書き込みを許可または拒否します。
- `commands.callbackPath` は完全な URL ではなく、パス (例: `/api/channels/mattermost/command`) である必要があります。
- `commands.callbackUrl` は OpenClaw Gateway エンドポイントに解決され、Mattermost サーバーから到達可能である必要があります。
- ネイティブスラッシュコールバックは、スラッシュコマンド登録中に Mattermost が返すコマンドごとのトークンで認証されます。登録に失敗した場合、または有効化されたコマンドがない場合、OpenClaw は `Unauthorized: invalid command token.` でコールバックを拒否します。
- プライベート/tailnet/内部コールバックホストでは、Mattermost が `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含めることを要求する場合があります。完全な URL ではなく、ホスト/ドメイン値を使用してください。
- `channels.mattermost.configWrites`: Mattermost 起点の設定書き込みを許可または拒否します。
- `channels.mattermost.requireMention`: チャンネルで返信する前に `@mention` を要求します。
- `channels.mattermost.groups.<channelId>.requireMention`: チャンネルごとのメンションゲート上書き (デフォルトには `"*"` )。
- 任意の `channels.mattermost.defaultAccount` は、構成済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。
- `channels.mattermost.groups.<channelId>.requireMention`: チャンネルごとのメンションゲート上書き (デフォルトは `"*"`)。
- 任意の `channels.mattermost.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウントの選択を上書きします。
### Signal
@ -555,15 +555,15 @@ Mattermost ネイティブコマンドが有効な場合:
}
```
**リアクション通知モード:** `off`、`own` (デフォルト)、`all`、`allowlist` (`reactionAllowlist` から)。
**リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。
- `channels.signal.account`: チャンネル起動を特定の Signal アカウント ID に固定します。
- `channels.signal.configWrites`: Signal から開始された設定の書き込みを許可または拒否します。
- `channels.signal.configWrites`: Signal から開始される設定書き込みを許可または拒否します。
- 任意の `channels.signal.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトのアカウント選択を上書きします。
### BlueBubbles
BlueBubbles は推奨される iMessage 経路です (Plugin ベースで、`channels.bluebubbles` の下で設定します)。
BlueBubbles は推奨される iMessage 経路です（Plugin が支え、`channels.bluebubbles` 配下で設定されます）。
```json5
{
@ -578,14 +578,14 @@ BlueBubbles は推奨される iMessage 経路です (Plugin ベースで、`cha
}
```
- ここで扱うコアキーのパス: `channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
- ここで扱うコアキーパス: `channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
- 任意の `channels.bluebubbles.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトのアカウント選択を上書きします。
- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続的な ACP セッションにバインドできます。`match.peer.id` では BlueBubbles ハンドルまたはターゲット文字列 (`chat_id:*`、`chat_guid:*`、`chat_identifier:*`) を使用します。共有フィールドのセマンティクス: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。
- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続 ACP セッションにバインドできます。`match.peer.id` では BlueBubbles ハンドルまたはターゲット文字列（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共有フィールドのセマンティクス: [ACP エージェント](/ja-JP/tools/acp-agents#channel-specific-settings)。
- 完全な BlueBubbles チャンネル設定は [BlueBubbles](/ja-JP/channels/bluebubbles) に記載されています。
### iMessage
OpenClaw は `imsg rpc` (stdio 上の JSON-RPC) を起動します。デーモンやポートは不要です。
OpenClaw は `imsg rpc`（stdio 経由の JSON-RPC）を起動します。デーモンやポートは不要です。
```json5
{
@ -612,12 +612,12 @@ OpenClaw は `imsg rpc` (stdio 上の JSON-RPC) を起動します。デーモ
- 任意の `channels.imessage.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトのアカウント選択を上書きします。
- Messages DB へのフルディスクアクセスが必要です。
- `chat_id:<id>` ターゲットを推奨します。チャットの一覧表示には `imsg chats --limit 20` を使用します。
- `cliPath` は SSH ラッパーを指すことができます。SCP による添付ファイル取得には `remoteHost` (`host` または `user@host`) を設定します。
- `attachmentRoots` と `remoteAttachmentRoots` は受信添付ファイルのパスを制限します (デフォルト: `/Users/*/Library/Messages/Attachments`)。
- SCP は厳格なホストキー確認を使用するため、リレーホストのキーがすでに `~/.ssh/known_hosts` に存在することを確認してください。
- `channels.imessage.configWrites`: iMessage から開始された設定の書き込みを許可または拒否します。
- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続的な ACP セッションにバインドできます。`match.peer.id` では正規化済みハンドルまたは明示的なチャットターゲット (`chat_id:*`、`chat_guid:*`、`chat_identifier:*`) を使用します。共有フィールドのセマンティクス: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。
- `chat_id:<id>` ターゲットを優先します。チャット一覧を表示するには `imsg chats --limit 20` を使用します。
- `cliPath` は SSH ラッパーを指すことができます。SCP による添付ファイル取得には `remoteHost`（`host` または `user@host`）を設定します。
- `attachmentRoots` と `remoteAttachmentRoots` は受信添付ファイルのパスを制限します（デフォルト: `/Users/*/Library/Messages/Attachments`）。
- SCP は厳密なホストキー検証を使用するため、リレーホストキーがすでに `~/.ssh/known_hosts` に存在することを確認してください。
- `channels.imessage.configWrites`: iMessage から開始される設定書き込みを許可または拒否します。
- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続 ACP セッションにバインドできます。正規化済みハンドルまたは明示的なチャットターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を `match.peer.id` で使用します。共有フィールドのセマンティクス: [ACP エージェント](/ja-JP/tools/acp-agents#channel-specific-settings)。
<Accordion title="iMessage SSH ラッパーの例">
@ -630,7 +630,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
Matrix は Plugin ベースで、`channels.matrix` の下で設定します。
Matrix は Plugin が支え、`channels.matrix` 配下で設定されます。
```json5
{
@ -661,24 +661,24 @@ Matrix は Plugin ベースで、`channels.matrix` の下で設定します。
```
- トークン認証は `accessToken` を使用します。パスワード認証は `userId` + `password` を使用します。
- `channels.matrix.proxy` は Matrix の HTTP トラフィックを明示的な HTTP(S) プロキシ経由でルーティングします。名前付きアカウントでは `channels.matrix.accounts.<id>.proxy` で上書きできます。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` はプライベート/内部 homeserver を許可します。`proxy` とこのネットワークのオプトインは独立した制御です。
- `channels.matrix.defaultAccount` は、マルチアカウント設定で優先アカウントを選択します。
- `channels.matrix.autoJoin` のデフォルトは `off` なので、招待されたルームと新しい DM 形式の招待は、`autoJoinAllowlist` を指定して `autoJoin: "allowlist"` を設定するか、`autoJoin: "always"` を設定するまで無視されます。
- `channels.matrix.proxy` は Matrix HTTP トラフィックを明示的な HTTP(S) プロキシ経由でルーティングします。名前付きアカウントは `channels.matrix.accounts.<id>.proxy` で上書きできます。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` はプライベート/内部ホームサーバーを許可します。`proxy` とこのネットワークオプトインは独立した制御です。
- `channels.matrix.defaultAccount` は、複数アカウント構成で優先アカウントを選択します。
- `channels.matrix.autoJoin` のデフォルトは `off` です。そのため、招待されたルームや新しい DM 風の招待は、`autoJoinAllowlist` 付きで `autoJoin: "allowlist"` を設定するか `autoJoin: "always"` を設定するまで無視されます。
- `channels.matrix.execApprovals`: Matrix ネイティブの exec 承認配信と承認者認可。
- `enabled`: `true`、`false`、または `"auto"` (デフォルト)。auto モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効になります。
- `approvers`: exec リクエストの承認を許可された Matrix ユーザー ID (例: `@owner:example.org`)。
- `enabled`: `true`、`false`、または `"auto"`（デフォルト）。自動モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効になります。
- `approvers`: exec リクエストの承認を許可された Matrix ユーザー ID（例: `@owner:example.org`）。
- `agentFilter`: 任意のエージェント ID 許可リスト。省略すると、すべてのエージェントの承認を転送します。
- `sessionFilter`: 任意のセッションキーパターン (部分文字列または正規表現)。
- `target`: 承認プロンプトの送信先。`"dm"` (デフォルト)、`"channel"` (送信元ルーム)、または `"both"`。
- アカウント単位の上書き: `channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` は、Matrix DM をセッションにグループ化する方法を制御します。`per-user` (デフォルト) はルーティングされたピアごとに共有し、`per-room` は各 DM ルームを分離します。
- Matrix のステータスプローブとライブディレクトリ検索は、ランタイムトラフィックと同じプロキシポリシーを使用します。
- 完全な Matrix 設定、ターゲット指定ルール、セットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。
- `sessionFilter`: 任意のセッションキーパターン（部分文字列または正規表現）。
- `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）、`"channel"`（発信元ルーム）、または `"both"`。
- アカウントごとの上書き: `channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` は Matrix DM をセッションにグループ化する方法を制御します。`per-user`（デフォルト）はルーティングされた相手ごとに共有し、`per-room` は各 DM ルームを分離します。
- Matrix ステータスプローブとライブディレクトリ検索は、ランタイムトラフィックと同じプロキシポリシーを使用します。
- 完全な Matrix 設定、ターゲティングルール、セットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。
### Microsoft Teams
Microsoft Teams は Plugin ベースで、`channels.msteams` の下で設定します。
Microsoft Teams は Plugin が支え、`channels.msteams` 配下で設定されます。
```json5
{
@ -693,12 +693,12 @@ Microsoft Teams は Plugin ベースで、`channels.msteams` の下で設定し
}
```
- ここで扱うコアキーのパス: `channels.msteams`、`channels.msteams.configWrites`。
- 完全な Teams 設定 (認証情報、Webhook、DM/グループポリシー、チーム単位/チャンネル単位の上書き) は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。
- ここで扱うコアキーパス: `channels.msteams`、`channels.msteams.configWrites`。
- 完全な Teams 設定（資格情報、Webhook、DM/グループポリシー、チーム別/チャンネル別の上書き）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。
### IRC
IRC は Plugin ベースで、`channels.irc` の下で設定します。
IRC は Plugin が支え、`channels.irc` 配下で設定されます。
```json5
{
@ -719,13 +719,13 @@ IRC は Plugin ベースで、`channels.irc` の下で設定します。
}
```
- ここで扱うコアキーのパス: `channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- ここで扱うコアキーパス: `channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 任意の `channels.irc.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトのアカウント選択を上書きします。
- 完全な IRC チャンネル設定 (ホスト/ポート/TLS/チャンネル/許可リスト/メンションゲート) は [IRC](/ja-JP/channels/irc) に記載されています。
- 完全な IRC チャンネル設定（ホスト/ポート/TLS/チャンネル/許可リスト/メンションゲート）は [IRC](/ja-JP/channels/irc) に記載されています。
### マルチアカウント (すべてのチャンネル)
### 複数アカウント（すべてのチャンネル）
チャンネルごとに複数のアカウントを実行します (各アカウントは独自の `accountId` を持ちます)。
チャンネルごとに複数のアカウントを実行します（それぞれ独自の `accountId` を持ちます）。
```json5
{
@ -746,32 +746,34 @@ IRC は Plugin ベースで、`channels.irc` の下で設定します。
}
```
- `accountId` が省略された場合は `default` が使用されます (CLI + ルーティング)。
- `accountId` が省略された場合は `default` が使用されます（CLI + ルーティング）。
- 環境変数トークンは **デフォルト** アカウントにのみ適用されます。
- ベースチャンネル設定は、アカウント単位で上書きされない限り、すべてのアカウントに適用されます。
- 各アカウントを別のエージェントにルーティングするには `bindings[].match.accountId` を使用します。
- 単一アカウントのトップレベルチャンネル設定のまま `openclaw channels add` (またはチャンネルのオンボーディング) で非デフォルトアカウントを追加した場合、OpenClaw はまず、アカウントスコープのトップレベル単一アカウント値をそのチャンネルのアカウントマップに昇格させ、元のアカウントが引き続き動作するようにします。ほとんどのチャンネルではそれらを `channels.<channel>.accounts.default` に移動します。Matrix では、代わりに既存の一致する名前付き/デフォルトターゲットを保持できます。
- 既存のチャンネルのみのバインディング (`accountId` なし) はデフォルトアカウントとの照合を継続します。アカウントスコープのバインディングは引き続き任意です。
- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値を、そのチャンネルで選択された昇格先アカウントへ移動することで混在形状を修復します。ほとんどのチャンネルでは `accounts.default` を使用します。Matrix では、代わりに既存の一致する名前付き/デフォルトターゲットを保持できます。
- ベースチャンネル設定は、アカウントごとに上書きされない限りすべてのアカウントに適用されます。
- 各アカウントを別のエージェントへルーティングするには `bindings[].match.accountId` を使用します。
- 単一アカウントのトップレベルチャンネル設定のまま `openclaw channels add`（またはチャンネルオンボーディング）で非デフォルトアカウントを追加すると、OpenClaw はまずアカウントスコープのトップレベル単一アカウント値をチャンネルのアカウントマップへ昇格し、元のアカウントが動作し続けるようにします。ほとんどのチャンネルではそれらを `channels.<channel>.accounts.default` に移動します。Matrix では既存の一致する名前付き/デフォルトターゲットを保持できる場合があります。
- 既存のチャンネルのみのバインディング（`accountId` なし）は、引き続きデフォルトアカウントに一致します。アカウントスコープのバインディングは引き続き任意です。
- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値をそのチャンネルで選ばれた昇格先アカウントへ移動することで混在形状を修復します。ほとんどのチャンネルは `accounts.default` を使用します。Matrix では既存の一致する名前付き/デフォルトターゲットを保持できる場合があります。
### その他の Plugin チャンネル
多くの Plugin チャンネルは `channels.<id>` として設定され、専用のチャンネルページに記載されています (例: Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch)。
多くの Plugin チャンネルは `channels.<id>` として設定され、それぞれ専用のチャンネルページに記載されています（例: Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。
完全なチャンネルインデックスを参照してください: [チャンネル](/ja-JP/channels)。
### グループチャットのメンションゲート
グループメッセージのデフォルトは **メンション必須** (メタデータメンションまたは安全な正規表現パターン) です。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。
グループメッセージのデフォルトは **メンション必須**（メタデータメンションまたは安全な正規表現パターン）です。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。
表示される返信は別に制御されます。グループ/チャンネルルームのデフォルトは `messages.groupChat.visibleReplies: "message_tool"` です。OpenClaw は引き続きターンを処理しますが、通常の最終返信は非公開のままで、ルームに表示される出力には `message(action=send)` が必要です。通常の返信をルームに投稿する従来の挙動が必要な場合にのみ `"automatic"` を設定します。同じツールのみの表示返信の挙動を直接チャットにも適用するには、`messages.visibleReplies: "message_tool"` を設定します。
表示返信は別に制御されます。グループ/チャンネルルームのデフォルトは `messages.groupChat.visibleReplies: "message_tool"` です。OpenClaw は引き続きターンを処理しますが、通常の最終返信はプライベートのままで、ルームに表示される出力には `message(action=send)` が必要です。通常の返信をルームへ投稿する従来の動作が必要な場合にのみ `"automatic"` を設定してください。同じツールのみの表示返信動作を直接チャットにも適用するには、`messages.visibleReplies: "message_tool"` を設定します。
Gateway は、ファイル保存後に `messages` 設定をホットリロードします。デプロイでファイル監視または設定リロードが無効化されている場合にのみ再起動してください。
アクティブなツールポリシーの下でメッセージツールが利用できない場合、OpenClaw はレスポンスを黙って抑制するのではなく、自動表示返信にフォールバックします。`openclaw doctor` はこの不一致について警告します。
**メンションタイプ:**
Gateway はファイル保存後に `messages` 設定をホットリロードします。デプロイでファイル監視または設定リロードが無効な場合にのみ再起動してください。
- **メタデータメンション**: ネイティブプラットフォームの @メンション。WhatsApp のセルフチャットモードでは無視されます。
- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` 内の安全な正規表現パターン。無効なパターンと安全でない入れ子の繰り返しは無視されます。
- メンションゲートは、検出が可能な場合 (ネイティブメンションまたは少なくとも 1 つのパターン) にのみ適用されます。
**メンションの種類:**
- **メタデータメンション**: ネイティブプラットフォームの @ メンション。WhatsApp のセルフチャットモードでは無視されます。
- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` の安全な正規表現パターン。無効なパターンと安全でないネストした繰り返しは無視されます。
- メンションゲートは、検出が可能な場合（ネイティブメンションまたは少なくとも 1 つのパターンがある場合）にのみ強制されます。
```json5
{
@ -788,9 +790,9 @@ Gateway は、ファイル保存後に `messages` 設定をホットリロード
}
```
`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。チャンネルは `channels.<channel>.historyLimit` (またはアカウント単位) で上書きできます。無効化するには `0` を設定します。
`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。チャンネルは `channels.<channel>.historyLimit`（またはアカウントごと）で上書きできます。無効にするには `0` を設定します。
`messages.visibleReplies` はグローバルなソースターンのデフォルトです。`messages.groupChat.visibleReplies` は、グループ/チャンネルのソースターンでこれを上書きします。チャンネル許可リストとメンションゲートは、ターンを処理するかどうかを引き続き決定します。
`messages.visibleReplies` はグローバルなソースターンのデフォルトです。`messages.groupChat.visibleReplies` はグループ/チャンネルのソースターンについてそれを上書きします。チャンネル許可リストとメンションゲートは、ターンを処理するかどうかを引き続き決定します。
#### DM 履歴制限
@ -807,13 +809,13 @@ Gateway は、ファイル保存後に `messages` 設定をホットリロード
}
```
解決順序: DM 単位の上書き → プロバイダーのデフォルト → 制限なし (すべて保持)。
解決順序: DM ごとの上書き → プロバイダーデフォルト → 制限なし（すべて保持）。
対応: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。
#### セルフチャットモード
セルフチャットモードを有効にするには、自分の電話番号を `allowFrom` に含めます (ネイティブ @メンションを無視し、テキストパターンにのみ応答します)。
セルフチャットモードを有効にするには、自分の番号を `allowFrom` に含めます（ネイティブ @ メンションは無視し、テキストパターンにのみ応答します）。
```json5
{
@ -834,7 +836,7 @@ Gateway は、ファイル保存後に `messages` 設定をホットリロード
}
```
### コマンド (チャットコマンド処理)
### コマンド（チャットコマンド処理）
```json5
{
@ -864,25 +866,25 @@ Gateway は、ファイル保存後に `messages` 設定をホットリロード
<Accordion title="コマンドの詳細">
- このブロックはコマンドサーフェスを設定します。現在の組み込み + バンドル済みコマンドカタログについては、[スラッシュコマンド](/ja-JP/tools/slash-commands)を参照してください。
- このページは**設定キーのリファレンス**であり、完全なコマンドカタログではありません。QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、デバイスペアリング `/pair`、メモリ `/dreaming`、電話操作 `/phone`、Talk `/voice` など、チャンネル/Plugin 所有のコマンドは、それぞれのチャンネル/Plugin ページおよび[スラッシュコマンド](/ja-JP/tools/slash-commands)に記載されています。
- テキストコマンドは、先頭に `/` が付いた**単独の**メッセージである必要があります。
- このページは**設定キーリファレンス**であり、完全なコマンドカタログではありません。QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、デバイスペアリング `/pair`、メモリ `/dreaming`、電話制御 `/phone`、Talk `/voice` などのチャンネル/Plugin 所有コマンドは、それぞれのチャンネル/Plugin ページと [スラッシュコマンド](/ja-JP/tools/slash-commands)に記載されています。
- テキストコマンドは、先頭に `/` を付けた**単独の**メッセージである必要があります。
- `native: "auto"` は Discord/Telegram のネイティブコマンドを有効にし、Slack は無効のままにします。
- `nativeSkills: "auto"` は Discord/Telegram のネイティブ Skills コマンドを有効にし、Slack は無効のままにします。
- チャンネルごとの上書き: `channels.discord.commands.native`（bool または `"auto"`）。`false` は以前に登録されたコマンドを消去します。
- `channels.<provider>.commands.nativeSkills` でチャンネルごとのネイティブ Skills 登録を上書きします。
- `channels.telegram.customCommands` は追加の Telegram bot メニューエントリを追加します。
- `bash: true` はホストシェル向けの `! <cmd>` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.<channel>` に含まれていることが必要です。
- `config: true` は `/config`（`openclaw.json` の読み書き）を有効にします。Gateway `chat.send` クライアントでは、永続的な `/config set|unset` の書き込みにも `operator.admin` が必要です。読み取り専用の `/config show` は、通常の書き込みスコープを持つ operator クライアントでも引き続き利用できます。
- `mcp: true` は、`mcp.servers` 配下の OpenClaw 管理 MCP サーバー設定向けに `/mcp` を有効にします。
- `plugins: true` は、Plugin の検出、インストール、有効化/無効化の制御向けに `/plugins` を有効にします。
- `channels.<provider>.configWrites` はチャンネルごとの設定変更を制御します（デフォルト: true）。
- 複数アカウントのチャンネルでは、`channels.<provider>.accounts.<id>.configWrites` も、そのアカウントを対象にする書き込みを制御します（例: `/allowlist --config --account <id>` または `/config set channels.<provider>.accounts.<id>...`）。
- `restart: false` は `/restart` と Gateway 再起動ツールのアクションを無効にします。デフォルト: `true`。
- `ownerAllowFrom` は、所有者専用のコマンド/ツール向けの明示的な所有者 allowlist です。`allowFrom` とは別です。
- チャンネルごとの上書き: `channels.discord.commands.native` (bool または `"auto"`)。`false` は以前に登録されたコマンドを消去します。
- チャンネルごとのネイティブ Skills 登録は `channels.<provider>.commands.nativeSkills` で上書きします。
- `channels.telegram.customCommands` は追加の Telegram ボットメニュー項目を追加します。
- `bash: true` はホストシェル用の `! <cmd>` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.<channel>` に含まれていることが必要です。
- `config: true` は `/config` (`openclaw.json` の読み書き) を有効にします。Gateway `chat.send` クライアントでは、永続的な `/config set|unset` 書き込みには `operator.admin` も必要です。読み取り専用の `/config show` は通常の書き込みスコープ付き operator クライアントでも引き続き利用できます。
- `mcp: true` は `mcp.servers` 配下の OpenClaw 管理 MCP サーバー設定用の `/mcp` を有効にします。
- `plugins: true` は Plugin の検出、インストール、有効化/無効化コントロール用の `/plugins` を有効にします。
- `channels.<provider>.configWrites` はチャンネルごとの設定変更を制御します (デフォルト: true)。
- マルチアカウントチャンネルでは、`channels.<provider>.accounts.<id>.configWrites` も、そのアカウントを対象にした書き込みを制御します (例: `/allowlist --config --account <id>` または `/config set channels.<provider>.accounts.<id>...`)。
- `restart: false` は `/restart` と Gateway 再起動ツールアクションを無効にします。デフォルト: `true`。
- `ownerAllowFrom` は所有者専用コマンド/ツールの明示的な所有者許可リストです。`allowFrom` とは別です。
- `ownerDisplay: "hash"` はシステムプロンプト内の所有者 ID をハッシュ化します。ハッシュ化を制御するには `ownerDisplaySecret` を設定します。
- `allowFrom` はプロバイダーごとの設定です。設定されている場合、それが**唯一の**認可ソースになります（チャンネルの allowlist/ペアリングと `useAccessGroups` は無視されます）。
- `useAccessGroups: false` は、`allowFrom` が設定されていない場合に、コマンドがアクセスグループポリシーをバイパスすることを許可します。
- コマンドドキュメントの対応表:
- `allowFrom` はプロバイダーごとです。設定されている場合、これは**唯一の**認可ソースになります (チャンネル許可リスト/ペアリングと `useAccessGroups` は無視されます)。
- `useAccessGroups: false` は、`allowFrom` が設定されていない場合に、コマンドがアクセスグループポリシーをバイパスできるようにします。
- コマンドドキュメントマップ:
- 組み込み + バンドル済みカタログ: [スラッシュコマンド](/ja-JP/tools/slash-commands)
- チャンネル固有のコマンドサーフェス: [チャンネル](/ja-JP/channels)
- QQ Bot コマンド: [QQ Bot](/ja-JP/channels/qqbot)

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

@ -4,27 +4,27 @@ read_when:
- カスタムプロバイダーの登録またはベース URL の上書き
- OpenAI 互換のセルフホスト型エンドポイントの設定
sidebarTitle: Tools and custom providers
summary: ツール設定（ポリシー、実験的な切り替え、プロバイダー支援ツール）とカスタムプロバイダー/base-URL 設定
summary: ツール設定（ポリシー、実験的なトグル、プロバイダー基盤のツール）とカスタムプロバイダー/ベース URL のセットアップ
title: 設定 — ツールとカスタムプロバイダー
x-i18n:
generated_at: "2026-04-30T05:11:44Z"
generated_at: "2026-05-01T05:01:12Z"
model: gpt-5.5
provider: openai
source_hash: 1790c92ecaf822c837326d8e22e9d72cc44e5d4cc0bcc00c154ba5160975002a
source_hash: 97e6bd8c762f6f7a9985b99ec016dde22c8ea8adc925778b11c2ae5103b887a8
source_path: gateway/config-tools.md
workflow: 16
---
`tools.*` 設定キーとカスタムプロバイダー / base-URL 設定。エージェント、チャネル、その他のトップレベル設定キーについては、[設定リファレンス](/ja-JP/gateway/configuration-reference)を参照してください。
`tools.*` 設定キーとカスタムプロバイダー / ベース URL 設定。エージェント、チャネル、その他のトップレベル設定キーについては、[設定リファレンス](/ja-JP/gateway/configuration-reference)を参照してください。
## ツール
### ツールプロファイル
`tools.profile` は `tools.allow`/`tools.deny` の前に基本 allowlist を設定します。
`tools.profile` は、`tools.allow`/`tools.deny` の前にベース許可リストを設定します。
<Note>
ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトを `tools.profile: "coding"` にします (既存の明示的なプロファイルは保持されます)。
ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトが `tools.profile: "coding"` になります（既存の明示的なプロファイルは保持されます）。
</Note>
| プロファイル | 含まれるもの |
@ -32,13 +32,13 @@ x-i18n:
| `minimal` | `session_status` のみ |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `full` | 制限なし (未設定と同じ) |
| `full` | 制限なし（未設定と同じ） |
### ツールグループ
| グループ | ツール |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` は `exec` のエイリアスとして受け入れられます) |
| `group:runtime` | `exec`, `process`, `code_execution`（`bash` は `exec` のエイリアスとして受け付けられます） |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
@ -49,11 +49,11 @@ x-i18n:
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
| `group:openclaw` | すべての組み込みツール (プロバイダー Plugin を除く) |
| `group:openclaw` | すべての組み込みツール（プロバイダー Plugin は除く） |
### `tools.allow` / `tools.deny`
グローバルなツールの許可/拒否ポリシー (拒否が優先)。大文字と小文字を区別せず、`*` ワイルドカードをサポートします。Docker サンドボックスがオフの場合でも適用されます。
グローバルなツール許可/拒否ポリシー（拒否が優先）。大文字小文字を区別せず、`*` ワイルドカードをサポートします。Docker サンドボックスがオフでも適用されます。
```json5
{
@ -63,7 +63,7 @@ x-i18n:
### `tools.byProvider`
特定のプロバイダーまたはモデルのツールをさらに制限します。順序: 基本プロファイル → プロバイダープロファイル → allow/deny。
特定のプロバイダーまたはモデル向けにツールをさらに制限します。順序: ベースプロファイル → プロバイダープロファイル → 許可/拒否。
```json5
{
@ -95,9 +95,9 @@ x-i18n:
}
```
- エージェントごとのオーバーライド (`agents.list[].tools.elevated`) は、さらに制限することしかできません。
- エージェントごとの上書き（`agents.list[].tools.elevated`）では、さらに制限することしかできません。
- `/elevated on|off|ask|full` はセッションごとに状態を保存します。インラインディレクティブは単一メッセージに適用されます。
- 昇格 `exec` はサンドボックスをバイパスし、設定済みのエスケープパスを使用します (デフォルトは `gateway`、または exec ターゲットが `node` の場合は `node`)。
- 昇格 `exec` はサンドボックス化をバイパスし、設定されたエスケープパスを使用します（デフォルトは `gateway`、または exec ターゲットが `node` の場合は `node`）。
### `tools.exec`
@ -121,7 +121,7 @@ x-i18n:
### `tools.loopDetection`
ツールループの安全チェックは**デフォルトで無効**です。検出を有効にするには `enabled: true` を設定してください。設定は `tools.loopDetection` でグローバルに定義でき、`agents.list[].tools.loopDetection` でエージェントごとにオーバーライドできます。
ツールループの安全チェックは**デフォルトで無効**です。検出を有効にするには `enabled: true` を設定します。設定は `tools.loopDetection` でグローバルに定義でき、`agents.list[].tools.loopDetection` でエージェントごとに上書きできます。
```json5
{
@ -146,22 +146,22 @@ x-i18n:
ループ分析のために保持されるツール呼び出し履歴の最大数。
</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>
@ -200,7 +200,7 @@ x-i18n:
### `tools.media`
受信メディア理解（画像/音声/動画）を設定します。
受信メディア理解（画像/音声/動画）を構成します。
```json5
{
@ -208,7 +208,7 @@ x-i18n:
media: {
concurrency: 2,
asyncCompletion: {
directSend: false, // opt-in: send finished async music/video directly to the channel
directSend: false, // opt-in: send finished async video directly to the channel
},
audio: {
enabled: true,
@ -238,30 +238,30 @@ x-i18n:
```
<AccordionGroup>
<Accordion title="メディアモデルエントリのフィールド">
**プロバイダーエントリ**（`type: "provider"` または省略）:
<Accordion title="Media model entry fields">
**プロバイダーエントリー**（`type: "provider"` または省略）:
- `provider`: API プロバイダー ID（`openai`、`anthropic`、`google`/`gemini`、`groq` など）
- `model`: モデル ID のオーバーライド
- `provider`: APIプロバイダーID（`openai`、`anthropic`、`google`/`gemini`、`groq` など）
- `model`: モデルIDの上書き
- `profile` / `preferredProfile`: `auth-profiles.json` プロファイルの選択
**CLI エントリ**（`type: "cli"`）:
**CLIエントリー**（`type: "cli"`）:
- `command`: 実行する実行可能ファイル
- `args`: テンプレート化された引数（`{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` などをサポート。`openclaw doctor --fix` は非推奨の `{input}` プレースホルダーを `{{MediaPath}}` に移行します）
**共通フィールド:**
- `capabilities`: 任意のリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → image、`google` → image+audio+video、`groq` → audio。
- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリごとのオーバーライド。
- `tools.media.image.timeoutSeconds` と対応する画像モデルの `timeoutSeconds` エントリは、エージェントが明示的な `image` ツールを呼び出す場合にも適用されます。
- 失敗時は次のエントリにフォールバックします。
- `capabilities`: 任意のリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → 画像、`google` → 画像+音声+動画、`groq` → 音声。
- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリーごとの上書き。
- `tools.media.image.timeoutSeconds` と対応する画像モデルの `timeoutSeconds` エントリーは、エージェントが明示的な `image` ツールを呼び出す場合にも適用されます。
- 失敗すると次のエントリーにフォールバックします。
プロバイダー認証は標準の順序に従います: `auth-profiles.json` → 環境変数 → `models.providers.*.apiKey`。
**非同期完了フィールド:**
- `asyncCompletion.directSend`: `true` の場合、完了した非同期 `music_generate` と `video_generate` タスクは、まずチャンネルへの直接配信を試みます。デフォルト: `false`（従来のリクエスターセッション wake/model-delivery パス）。
- `asyncCompletion.directSend`: `true` の場合、直接完了配信をサポートする完了済みの非同期メディアタスクは、まずチャンネルへの直接配信を試みます。デフォルト: `false`（リクエスターセッションのウェイク/モデル配信パス）。現在これは非同期 `video_generate` に適用されます。非同期 `music_generate` の完了は、これが有効な場合でもリクエスターセッション経由のままです。
</Accordion>
</AccordionGroup>
@ -281,9 +281,9 @@ x-i18n:
### `tools.sessions`
セッションツール（`sessions_list`、`sessions_history`、`sessions_send`）で対象にできるセッションを制御します。
セッションツール（`sessions_list`、`sessions_history`、`sessions_send`）でターゲットにできるセッションを制御します。
デフォルト: `tree`（現在のセッション + そこから生成されたセッション、サブエージェントなど）。
デフォルト: `tree`（現在のセッション + サブエージェントなど、それによって生成されたセッション）。
```json5
{
@ -297,12 +297,12 @@ x-i18n:
```
<AccordionGroup>
<Accordion title="可視性スコープ">
<Accordion title="Visibility scopes">
- `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>
@ -328,13 +328,13 @@ x-i18n:
```
<AccordionGroup>
<Accordion title="添付ファイルの注意事項">
- 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACP ランタイムでは拒否されます。
<Accordion title="Attachment notes">
- 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACPランタイムは添付ファイルを拒否します。
- ファイルは子ワークスペースの `.openclaw/attachments/<uuid>/` に `.manifest.json` とともに実体化されます。
- 添付ファイルの内容は、トランスクリプト永続化から自動的にリダクションされます。
- Base64 入力は、厳密なアルファベット/パディングチェックとデコード前のサイズガードで検証されます。
- ファイル権限は、ディレクトリが `0700`、ファイルが `0600` です。
- クリーンアップは `cleanup` ポリシーに従います。`delete` は常に添付ファイルを削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。
- 添付ファイルの内容は、トランスクリプト永続化から自動的に編集されます。
- Base64入力は、厳格なアルファベット/パディングチェックとデコード前サイズガードで検証されます。
- ファイル権限はディレクトリが `0700`、ファイルが `0600` です。
- クリーンアップは `cleanup` ポリシーに従います。`delete` は常に添付ファイルを削除し、`keep` は `retainOnSessionKeep: true` の場合のみ保持します。
</Accordion>
</AccordionGroup>
@ -343,7 +343,7 @@ x-i18n:
### `tools.experimental`
実験的な組み込みツールフラグ。strict-agentic GPT-5 の自動有効化ルールが適用されない限り、デフォルトではオフです。
実験的な組み込みツールフラグ。strict-agentic GPT-5 の自動有効化ルールが適用される場合を除き、デフォルトではオフです。
```json5
{
@ -355,9 +355,9 @@ x-i18n:
}
```
- `planTool`: 重要な複数ステップ作業の追跡用に、構造化された `update_plan` ツールを有効にします。
- 既定値: OpenAI または OpenAI Codex GPT-5 ファミリーの実行で、`agents.defaults.embeddedPi.executionContract`（またはエージェントごとの上書き）が `"strict-agentic"` に設定されていない限り `false` です。その範囲外でツールを強制的に有効にするには `true` を設定し、strict-agentic GPT-5 実行でも無効のままにするには `false` を設定します。
- 有効にすると、システムプロンプトには使用ガイダンスも追加されるため、モデルは実質的な作業にのみこれを使用し、`in_progress` のステップを最大 1 つに保ちます。
- `planTool`: 重要な複数ステップの作業を追跡するための構造化された `update_plan` ツールを有効にします。
- 既定値: OpenAI または OpenAI Codex の GPT-5 ファミリー実行で `agents.defaults.embeddedPi.executionContract`（またはエージェントごとの上書き）が `"strict-agentic"` に設定されていない限り、`false` です。その範囲外でツールを強制的に有効にするには `true` を設定し、strict-agentic GPT-5 実行でも無効のままにするには `false` を設定します。
- 有効にすると、システムプロンプトにも使用ガイダンスが追加され、モデルは実質的な作業にのみこのツールを使い、`in_progress` のステップを最大 1 つに保ちます。
### `agents.defaults.subagents`
@ -377,16 +377,16 @@ x-i18n:
}
```
- `model`: 生成されたサブエージェントの既定モデル。省略すると、サブエージェントは呼び出し元のモデルを継承します。
- `allowAgents`: 要求元エージェントが独自の `subagents.allowAgents` を設定していない場合の、`sessions_spawn` の対象エージェント ID の既定許可リスト（`["*"]` = 任意、既定値: 同じエージェントのみ）。
- `runTimeoutSeconds`: ツール呼び出しで `runTimeoutSeconds` が省略された場合の、`sessions_spawn` の既定タイムアウト（秒）。`0` はタイムアウトなしを意味します。
- `model`: 生成されるサブエージェントの既定モデル。省略すると、サブエージェントは呼び出し元のモデルを継承します。
- `allowAgents`: リクエスト元エージェントが自身の `subagents.allowAgents` を設定していない場合に `sessions_spawn` で使う対象エージェント ID の既定許可リスト（`["*"]` = 任意、既定値: 同じエージェントのみ）。
- `runTimeoutSeconds`: ツール呼び出しで `runTimeoutSeconds` が省略された場合に `sessions_spawn` で使う既定のタイムアウト（秒）。`0` はタイムアウトなしを意味します。
- サブエージェントごとのツールポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。
---
## カスタムプロバイダーとベース URL
OpenClaw は組み込みのモデルカタログを使用します。カスタムプロバイダーは、config の `models.providers` または `~/.openclaw/agents/<agentId>/agent/models.json` で追加します。
OpenClaw は組み込みのモデルカタログを使用します。カスタムプロバイダーは、設定内の `models.providers` または `~/.openclaw/agents/<agentId>/agent/models.json` で追加します。
```json5
{
@ -416,19 +416,19 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
```
<AccordionGroup>
<Accordion title="認証とマージの優先順位">
<Accordion title="Auth and merge precedence">
- カスタム認証が必要な場合は、`authHeader: true` + `headers` を使用します。
- エージェント config ルートは `OPENCLAW_AGENT_DIR`（または従来の環境変数エイリアス `PI_CODING_AGENT_DIR`）で上書きします。
- エージェント設定ルートは `OPENCLAW_AGENT_DIR`（または従来の環境変数エイリアス `PI_CODING_AGENT_DIR`）で上書きします。
- 一致するプロバイダー ID のマージ優先順位:
- 空でないエージェント `models.json` の `baseUrl` 値が優先されます。
- 空でないエージェント `apiKey` 値は、そのプロバイダーが現在の config/auth-profile コンテキストで SecretRef 管理されていない場合にのみ優先されます。
- SecretRef 管理のプロバイダー `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（env 参照の場合は `ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。
- SecretRef 管理のプロバイダーヘッダー値は、ソースマーカー（env 参照の場合は `secretref-env:ENV_VAR_NAME`、file/exec 参照の場合は `secretref-managed`）から更新されます。
- 空または欠落しているエージェント `apiKey`/`baseUrl` は、config の `models.providers` にフォールバックします。
- 一致するモデルの `contextWindow`/`maxTokens` は、明示的な config 値と暗黙のカタログ値のうち高い方を使用します。
- 空でないエージェント `apiKey` 値は、そのプロバイダーが現在の設定/認証プロファイルコンテキストで SecretRef 管理されていない場合のみ優先されます。
- SecretRef 管理のプロバイダー `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（環境変数参照では `ENV_VAR_NAME`、ファイル/exec 参照では `secretref-managed`）から更新されます。
- SecretRef 管理のプロバイダーヘッダー値は、ソースマーカー（環境変数参照では `secretref-env:ENV_VAR_NAME`、ファイル/exec 参照では `secretref-managed`）から更新されます。
- 空または欠落しているエージェント `apiKey`/`baseUrl` は、設定内の `models.providers` にフォールバックします。
- 一致するモデルの `contextWindow`/`maxTokens` は、明示的な設定値と暗黙のカタログ値のうち高い方を使用します。
- 一致するモデルの `contextTokens` は、存在する場合は明示的なランタイム上限を保持します。ネイティブモデルメタデータを変更せずに有効コンテキストを制限するために使用します。
- config で `models.json` を完全に書き換えたい場合は、`models.mode: "replace"` を使用します。
- マーカーの永続化はソースを正とします。マーカーは、解決済みランタイムシークレット値ではなく、アクティブなソース config スナップショット（解決前）から書き込まれます。
- 設定で `models.json` を完全に書き換えたい場合は、`models.mode: "replace"` を使用します。
- マーカーの永続化はソースを権威とします。マーカーは、解決済みランタイムシークレット値ではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。
</Accordion>
</AccordionGroup>
@ -436,64 +436,64 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
### プロバイダーフィールドの詳細
<AccordionGroup>
<Accordion title="トップレベルカタログ">
<Accordion title="Top-level catalog">
- `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` を渡さない限り破壊的な置換を拒否します。
- 安全な編集: 追加更新には `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 置換を推奨）。
<Accordion title="Provider connection and auth">
- `models.providers.*.api`: リクエストアダプター（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。MLX、vLLM、SGLang、および多くの OpenAI 互換ローカルサーバーなど、セルフホストの `/v1/chat/completions` バックエンドでは、`openai-completions` を使用します。`baseUrl` があり `api` がないカスタムプロバイダーは、既定で `openai-completions` になります。バックエンドが `/v1/responses` をサポートしている場合のみ `openai-responses` を設定します。
- `models.providers.*.apiKey`: プロバイダー資格情報（SecretRef/環境変数置換を推奨）。
- `models.providers.*.auth`: 認証戦略（`api-key`、`token`、`oauth`、`aws-sdk`）。
- `models.providers.*.contextWindow`: モデルエントリが `contextWindow` を設定していない場合の、このプロバイダー配下のモデルに対する既定のネイティブコンテキストウィンドウ。
- `models.providers.*.contextTokens`: モデルエントリが `contextTokens` を設定していない場合の、このプロバイダー配下のモデルに対する既定の有効ランタイムコンテキスト上限。
- `models.providers.*.maxTokens`: モデルエントリが `maxTokens` を設定していない場合の、このプロバイダー配下のモデルに対する既定の出力トークン上限。
- `models.providers.*.timeoutSeconds`: 接続、ヘッダー、本文、およびリクエスト全体の中止処理を含む、プロバイダーごとの任意のモデル HTTP リクエストタイムアウト（秒）。
- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` の場合、リクエストに `options.num_ctx` を注入します（既定値: `true`）。
- `models.providers.*.authHeader`: 必要な場合に、資格情報の転送を `Authorization` ヘッダーに強制します。
- `models.providers.*.baseUrl`: 上流 API ベース URL。
- `models.providers.*.headers`: プロキシ/テナントルーティング用の追加静的ヘッダー。
- `models.providers.*.contextWindow`: モデルエントリで `contextWindow` が設定されていない場合に、このプロバイダー配下のモデルに使う既定のネイティブコンテキストウィンドウ。
- `models.providers.*.contextTokens`: モデルエントリで `contextTokens` が設定されていない場合に、このプロバイダー配下のモデルに使う既定の有効ランタイムコンテキスト上限。
- `models.providers.*.maxTokens`: モデルエントリで `maxTokens` が設定されていない場合に、このプロバイダー配下のモデルに使う既定の出力トークン上限。
- `models.providers.*.timeoutSeconds`: 接続、ヘッダー、本文、リクエスト全体の中断処理を含む、プロバイダーごとの任意のモデル HTTP リクエストタイムアウト（秒）。
- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` で、リクエストに `options.num_ctx` を注入します（既定値: `true`）。
- `models.providers.*.authHeader`: 必要な場合に、資格情報の送信を `Authorization` ヘッダーで強制します。
- `models.providers.*.baseUrl`: アップストリーム API ベース URL。
- `models.providers.*.headers`: プロキシ/テナントルーティング用の追加の静的ヘッダー。
</Accordion>
<Accordion title="リクエスト転送の上書き">
`models.providers.*.request`: モデルプロバイダー HTTP リクエストの転送上書き。
<Accordion title="Request transport overrides">
`models.providers.*.request`: モデルプロバイダー HTTP リクエストのトランスポート上書き。
- `request.headers`: 追加ヘッダー（プロバイダー既定値とマージされます）。値は SecretRef を受け付けます。
- `request.auth`: 認証戦略の上書き。モード: `"provider-default"`（プロバイダーの組み込み認証を使用）、`"authorization-bearer"`（`token` と使用）、`"header"`（`headerName`、`value`、任意の `prefix` と使用）。
- `request.proxy`: HTTP プロキシの上書き。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` env 変数を使用）、`"explicit-proxy"`（`url` と使用）。どちらのモードも任意の `tls` サブオブジェクトを受け付けます。
- `request.tls`: 直接接続用の TLS 上書き。フィールド: `ca`、`cert`、`key`、`passphrase`（すべて SecretRef を受け付けます）、`serverName`、`insecureSkipVerify`。
- `request.allowPrivateNetwork`: `true` の場合、DNS がプライベート、CGNAT、または類似の範囲に解決されるときでも、プロバイダー HTTP fetch ガード経由で `baseUrl` への HTTPS を許可します（信頼済みのセルフホスト OpenAI 互換エンドポイントに対するオペレーターのオプトイン）。`localhost`、`127.0.0.1`、`[::1]` などの local loopback モデルプロバイダーストリーム URL は、これが明示的に `false` に設定されていない限り自動的に許可されます。LAN、tailnet、およびプライベート DNS ホストは引き続きオプトインが必要です。WebSocket はヘッダー/TLS に同じ `request` を使用しますが、その fetch SSRF ゲートは使用しません。既定値は `false` です。
- `request.headers`: 追加ヘッダー（プロバイダー既定値とマージされます）。値には SecretRef を指定できます。
- `request.auth`: 認証戦略の上書き。モード: `"provider-default"`（プロバイダーの組み込み認証を使用）、`"authorization-bearer"`（`token` を使用）、`"header"`（`headerName`、`value`、任意の `prefix` を使用）。
- `request.proxy`: HTTP プロキシの上書き。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` 環境変数を使用）、`"explicit-proxy"`（`url` を使用）。どちらのモードも任意の `tls` サブオブジェクトを受け付けます。
- `request.tls`: 直接接続の TLS 上書き。フィールド: `ca`、`cert`、`key`、`passphrase`（すべて SecretRef を受け付けます）、`serverName`、`insecureSkipVerify`。
- `request.allowPrivateNetwork`: `true` の場合、DNS がプライベート、CGNAT、または類似の範囲に解決される場合でも、プロバイダー HTTP fetch ガードを介して `baseUrl` への HTTPS を許可します（信頼されたセルフホスト OpenAI 互換エンドポイント向けのオペレーターによるオプトイン）。`localhost`、`127.0.0.1`、`[::1]` などのループバックモデルプロバイダーストリーム URL は、これが明示的に `false` に設定されていない限り自動的に許可されます。LAN、tailnet、プライベート DNS ホストには引き続きオプトインが必要です。WebSocket はヘッダー/TLS に同じ `request` を使用しますが、その fetch SSRF ゲートは使用しません。既定値は `false` です。
</Accordion>
<Accordion title="モデルカタログエントリ">
<Accordion title="Model catalog entries">
- `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 検出">
<Accordion title="Amazon Bedrock discovery">
- `plugins.entries.amazon-bedrock.config.discovery`: Bedrock 自動検出設定のルート。
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙的な検出のオン/オフを切り替えます。
- `plugins.entries.amazon-bedrock.config.discovery.region`: 検出用の AWS リージョン。
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象を絞った検出用の任意のプロバイダー ID フィルター。
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙の検出をオン/オフにします。
- `plugins.entries.amazon-bedrock.config.discovery.region`: 検出に使う AWS リージョン。
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象を絞った検出に使う任意のプロバイダー ID フィルター。
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: 検出更新のポーリング間隔。
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出されたモデルのフォールバックコンテキストウィンドウ。
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出されたモデルのフォールバック最大出力トークン。
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出されたモデルのフォールバック最大出力トークン数。
</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` プロバイダー Plugin は、`openclaw onboard --auth-choice cerebras-api-key` でこれを構成できます。既定値を上書きする場合にのみ、明示的なプロバイダー config を使用します。
<Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
バンドルされた `cerebras` プロバイダー Plugin は、`openclaw onboard --auth-choice cerebras-api-key` でこれを設定できます。既定値を上書きする場合のみ、明示的なプロバイダー設定を使用します。
```json5
{
@ -547,7 +547,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
</Accordion>
<Accordion title="ローカルモデル (LM Studio)">
[ローカルモデル](/ja-JP/gateway/local-models)を参照してください。要約: 本格的なハードウェア上で LM Studio Responses API 経由の大規模なローカルモデルを実行し、フォールバック用にホスト型モデルをマージしたままにします。
[ローカルモデル](/ja-JP/gateway/local-models)を参照してください。要約: 本格的なハードウェア上で、LM Studio Responses API 経由で大規模なローカルモデルを実行します。フォールバック用にホスト型モデルもマージしたままにしてください。
</Accordion>
<Accordion title="MiniMax M2.7 (直接)">
```json5
@ -584,7 +584,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
}
```
`MINIMAX_API_KEY` を設定します。ショートカット: `openclaw onboard --auth-choice minimax-global-api` または `openclaw onboard --auth-choice minimax-cn-api`。モデルカタログのデフォルトは M2.7 のみです。Anthropic 互換のストリーミングパスでは、`thinking` を明示的に自分で設定しない限り、OpenClaw はデフォルトで MiniMax の thinking を無効にします。`/fast on` または `params.fastMode: true` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。
`MINIMAX_API_KEY` を設定します。ショートカット: `openclaw onboard --auth-choice minimax-global-api` または `openclaw onboard --auth-choice minimax-cn-api`。モデルカタログのデフォルトは M2.7 のみです。Anthropic 互換ストリーミングパスでは、自分で `thinking` を明示的に設定しない限り、OpenClaw はデフォルトで MiniMax の思考を無効にします。`/fast on` または `params.fastMode: true` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。
</Accordion>
<Accordion title="Moonshot AI (Kimi)">
@ -623,7 +623,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
中国エンドポイントの場合: `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn`。
ネイティブの Moonshot エンドポイントは、共有の `openai-completions` トランスポート上でストリーミング使用量の互換性を通知し、OpenClaw は組み込み provider id だけではなく、エンドポイント機能に基づいてそれを判定します。
ネイティブの Moonshot エンドポイントは、共有 `openai-completions` トランスポート上でストリーミング使用量の互換性を通知し、OpenClaw は組み込みプロバイダー ID だけではなくエンドポイント機能に基づいてそれを判定します。
</Accordion>
<Accordion title="OpenCode">
@ -638,7 +638,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
}
```
`OPENCODE_API_KEY` (または `OPENCODE_ZEN_API_KEY`) を設定します。Zen カタログには `opencode/...` refs を、Go カタログには `opencode-go/...` refs を使用します。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。
`OPENCODE_API_KEY` (または `OPENCODE_ZEN_API_KEY`) を設定します。Zen カタログには `opencode/...` 参照を、Go カタログには `opencode-go/...` 参照を使用します。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。
</Accordion>
<Accordion title="Synthetic (Anthropic 互換)">
@ -675,7 +675,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
}
```
ベース URL では `/v1` を省略する必要があります (Anthropic クライアントが付加します)。ショートカット: `openclaw onboard --auth-choice synthetic-api-key`。
ベース URL では `/v1` を省略してください (Anthropic クライアントが追加します)。ショートカット: `openclaw onboard --auth-choice synthetic-api-key`。
</Accordion>
<Accordion title="Z.AI (GLM-4.7)">
@ -690,11 +690,11 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
}
```
`ZAI_API_KEY` を設定します。`z.ai/*` と `z-ai/*` はエイリアスとして受け入れられます。ショートカット: `openclaw onboard --auth-choice zai-api-key`。
`ZAI_API_KEY` を設定します。`z.ai/*` と `z-ai/*` は別名として受け付けられます。ショートカット: `openclaw onboard --auth-choice zai-api-key`。
- 汎用エンドポイント: `https://api.z.ai/api/paas/v4`
- コーディングエンドポイント (デフォルト): `https://api.z.ai/api/coding/paas/v4`
- 汎用エンドポイントの場合は、ベース URL のオーバーライドを含むカスタム provider を定義します。
- 汎用エンドポイントの場合は、ベース URL の上書きを持つカスタムプロバイダーを定義します。
</Accordion>
</AccordionGroup>
@ -703,7 +703,7 @@ OpenClaw は組み込みのモデルカタログを使用します。カスタ
## 関連
- [設定 — agents](/ja-JP/gateway/config-agents)
- [設定 — channels](/ja-JP/gateway/config-channels)
- [設定 — エージェント](/ja-JP/gateway/config-agents)
- [設定 — チャンネル](/ja-JP/gateway/config-channels)
- [設定リファレンス](/ja-JP/gateway/configuration-reference) — その他のトップレベルキー
- [ツールとplugins](/ja-JP/tools)
- [ツールと plugins](/ja-JP/tools)

415
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-04-30T16:28:59Z"
generated_at: "2026-05-01T05:01:21Z"
model: gpt-5.5
provider: openai
source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e
source_hash: 52183eaf6024eface20089f9d11143ef1e952d2488eee766dc154512f5d3c6b4
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor`はOpenClawの修復 + 移行ツールです。古い設定/状態を修正し、健全性をチェックし、実行可能な修復手順を提供します。
`openclaw doctor` は OpenClaw の修復 + 移行ツールです。古い設定/状態を修正し、正常性を確認し、実行可能な修復手順を提示します。
## クイックスタート
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
プロンプトを表示せずにデフォルトを受け入れます（該当する場合は再起動/サービス/サンドボックス修復手順も含む）。
プロンプトを表示せずにデフォルトを受け入れます（該当する場合は再起動/サービス/サンドボックス修復手順を含む）。
</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 設定を上書きします）。
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
プロンプトなしで実行し、安全な移行のみを適用します（設定の正規化 + ディスク上の状態移動）。人による確認が必要な再起動/サービス/サンドボックス操作はスキップします。レガシー状態の移行は、検出されると自動的に実行されます。
プロンプトなしで実行し、安全な移行のみを適用します（設定の正規化 + ディスク上の状態移動）。人間の確認が必要な再起動/サービス/サンドボックス操作はスキップします。レガシー状態の移行は検出時に自動実行されます。
</Tab>
<Tab title="--deep">
@ -62,12 +62,12 @@ openclaw doctor
openclaw doctor --deep
```
追加のGatewayインストール（launchd/systemd/schtasks）についてシステムサービスをスキャンします。
追加の gateway インストールについてシステムサービスをスキャンします（launchd/systemd/schtasks）。
</Tab>
</Tabs>
書き込む前に変更を確認したい場合は、まず設定ファイルを開いてください。
書き込む前に変更を確認したい場合は、まず設定ファイルを開きます。
```bash
cat ~/.openclaw/openclaw.json
@ -76,112 +76,117 @@ cat ~/.openclaw/openclaw.json
## 実行内容（概要）
<AccordionGroup>
<Accordion title="健全性、UI、更新">
- gitインストール向けの任意の事前更新（対話時のみ）。
- UIプロトコル鮮度チェック（プロトコルスキーマが新しい場合にControl UIを再ビルド）。
- 健全性チェック + 再起動プロンプト。
- Skillsステータス概要（対象/欠落/ブロック）とPluginステータス。
<Accordion title="正常性、UI、更新">
- git インストール向けの任意の事前更新（対話モードのみ）。
- UI プロトコル鮮度チェック（プロトコルスキーマが新しい場合に Control UI を再ビルド）。
- 正常性チェック + 再起動プロンプト。
- Skills ステータス概要（対象/不足/ブロック中）と 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前提条件チェック。
- レガシーのディスク上状態移行（セッション/エージェントディレクトリ/WhatsApp認証）。
- レガシーPluginマニフェスト契約キー移行（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
- レガシーCronストア移行（`jobId`、`schedule.cron`、トップレベルの配信/ペイロードフィールド、ペイロード`provider`、単純な`notify: true` webhookフォールバックジョブ）。
- レガシーエージェントランタイムポリシーを`agents.defaults.agentRuntime`と`agents.list[].agentRuntime`へ移行。
- Pluginが有効な場合は古いPlugin設定をクリーンアップします。`plugins.enabled=false`の場合、古いPlugin参照は不活性な封じ込め設定として扱われ、保持されます。
- レガシーのフラットな `talk.*` フィールドから `talk.provider` + `talk.providers.<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 フォールバックジョブ）。
- レガシーエージェントランタイムポリシーを `agents.defaults.agentRuntime` と `agents.list[].agentRuntime` へ移行。
- plugins が有効な場合の古い plugin 設定のクリーンアップ。`plugins.enabled=false` の場合、古い plugin 参照は不活性な封じ込め設定として扱われ、保持されます。
</Accordion>
<Accordion title="状態と整合性">
- セッションロックファイルの検査と古いロックのクリーンアップ。
- 影響を受けた2026.4.24ビルドによって作成された重複プロンプト書き換えブランチに対するセッショントランスクリプト修復。
- 行き詰まったサブエージェントの再起動リカバリ墓標検出。古い中断済みリカバリフラグをクリアして、起動時に子を再起動中断として扱い続けないようにする`--fix`サポート付き。
- 状態整合性と権限チェック（セッション、トランスクリプト、状態ディレクトリ）。
- 影響を受けた 2026.4.24 ビルドによって作成された重複プロンプト書き換えブランチのセッショントランスクリプト修復。
- 行き詰まったサブエージェントの再起動リカバリ tombstone 検出。古い中止済みリカバリフラグをクリアして、起動時に子を再起動中止済みとして扱い続けないようにするための `--fix` サポート付き。
- 状態の整合性と権限チェック（セッション、トランスクリプト、状態ディレクトリ）。
- ローカル実行時の設定ファイル権限チェック（chmod 600）。
- モデル認証の健全性: OAuth期限切れをチェックし、期限が近いトークンを更新でき、認証プロファイルのクールダウン/無効状態を報告します。
- モデル認証の正常性: OAuth 有効期限を確認し、期限が近いトークンを更新でき、auth-profile のクールダウン/無効状態を報告します。
- 追加ワークスペースディレクトリ検出（`~/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 vs Bun、バージョンマネージャーパス）。
- Gatewayポート衝突診断（デフォルト`18789`）。
- レガシーサービス移行と追加 gateway 検出。
- Matrix チャンネルのレガシー状態移行（`--fix` / `--repair` モード）。
- Gateway ランタイムチェック（サービスがインストール済みだが実行されていない、キャッシュ済み launchd ラベル）。
- チャンネルステータス警告（実行中の gateway からプローブ）。
- 任意修復付き supervisor 設定監査（launchd/systemd/schtasks）。
- インストールまたは更新時にシェルの `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 値を取り込んだ gateway サービス向けの埋め込みプロキシ環境クリーンアップ。
- Gateway ランタイムのベストプラクティスチェック（Node と Bun、バージョンマネージャーパス）。
- Gateway ポート衝突診断（デフォルト `18789`）。
</Accordion>
<Accordion title="認証、セキュリティ、ペアリング">
- オープンDMポリシーに関するセキュリティ警告。
- ローカルトークンモード向けGateway認証チェック（トークンソースが存在しない場合はトークン生成を提案します。SecretRefトークン設定は上書きしません）。
- デバイスペアリング問題の検出（保留中の初回ペアリクエスト、保留中のロール/スコープアップグレード、古いローカルデバイストークンキャッシュのずれ、ペアリング済みレコードの認証ずれ）。
- オープン DM ポリシーのセキュリティ警告。
- ローカルトークンモード向け Gateway 認証チェック（トークンソースがない場合にトークン生成を提示します。トークン SecretRef 設定は上書きしません）。
- デバイスペアリング問題の検出（保留中の初回ペアリングリクエスト、保留中のロール/スコープアップグレード、古いローカルデバイストークンキャッシュのずれ、ペアリング済みレコードの認証ずれ）。
</Accordion>
<Accordion title="ワークスペースとシェル">
- Linuxでのsystemd lingerチェック。
- ワークスペースブートストラップファイルサイズチェック（コンテキストファイルの切り詰め/上限接近警告）。
- Linux での systemd linger チェック。
- ワークスペース bootstrap ファイルサイズチェック（コンテキストファイルの切り詰め/上限接近の警告）。
- シェル補完ステータスチェックと自動インストール/アップグレード。
- メモリ検索埋め込みプロバイダー準備状況チェック（ローカルモデル、リモートAPIキー、またはQMDバイナリ）。
- ソースインストールチェック（pnpmワークスペース不一致、UIアセット欠落、tsxバイナリ欠落）。
- メモリ検索埋め込みプロバイダー準備状態チェック（ローカルモデル、リモート API キー、または QMD バイナリ）。
- ソースインストールチェック（pnpm ワークスペース不一致、不足 UI アセット、不足 tsx バイナリ）。
- 更新済み設定 + ウィザードメタデータを書き込みます。
</Accordion>
</AccordionGroup>
## Dreams UIのバックフィルとリセット
## Dreams UI バックフィルとリセット
Control UIのDreamsシーンには、グラウンデッドDreamingワークフロー向けに**バックフィル**、**リセット**、**グラウンデッドをクリア**アクションが含まれています。これらのアクションはGatewayのdoctor形式RPCメソッドを使用しますが、`openclaw doctor` CLIの修復/移行の一部では**ありません**。
Control UI の Dreams シーンには、grounded dreaming ワークフロー向けの **Backfill**、**Reset**、**Clear Grounded** アクションがあります。これらのアクションは gateway の doctor 形式の RPC メソッドを使いますが、`openclaw doctor` CLI の修復/移行の一部では**ありません**。
実行内容:
- **バックフィル**は、アクティブワークスペース内の履歴`memory/YYYY-MM-DD.md`ファイルをスキャンし、グラウンデッドREM日記パスを実行し、可逆バックフィルエントリを`DREAMS.md`に書き込みます。
- **リセット**は、`DREAMS.md`からマークされたバックフィル日記エントリのみを削除します。
- **グラウンデッドをクリア**は、履歴リプレイから来ていて、まだライブリコールや日次サポートが蓄積されていない、ステージ済みのグラウンデッド限定短期エントリのみを削除します。
- **Backfill** はアクティブワークスペース内の過去の `memory/YYYY-MM-DD.md` ファイルをスキャンし、grounded REM diary パスを実行し、可逆的なバックフィルエントリを `DREAMS.md` に書き込みます。
- **Reset** は `DREAMS.md` から、マークされたバックフィル diary エントリのみを削除します。
- **Clear Grounded** は、履歴リプレイから来て、まだライブ recall や日次サポートを蓄積していない、ステージ済みの grounded-only 短期エントリのみを削除します。
それ自体では**実行しない**こと:
それ自体では実行**しない**こと:
- `MEMORY.md`を編集しません
- 完全なdoctor移行を実行しません
- 先にステージ済みCLIパスを明示的に実行しない限り、グラウンデッド候補をライブ短期昇格ストアへ自動的にステージしません
- `MEMORY.md` を編集しません
- 完全な doctor 移行を実行しません
- ステージ済み CLI パスを明示的に先に実行しない限り、grounded 候補をライブ短期プロモーションストアへ自動的にステージしません
グラウンデッド履歴リプレイを通常のディープ昇格レーンに反映したい場合は、代わりにCLIフローを使用してください。
grounded 履歴リプレイを通常の deep promotion レーンに影響させたい場合は、代わりに CLI フローを使います。
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
これにより、`DREAMS.md`をレビュー面として維持しながら、グラウンデッドで永続的な候補を短期Dreamingストアにステージします。
これにより、`DREAMS.md` をレビュー面として維持しながら、grounded durable 候補を短期 dreaming ストアへステージします。
## 詳細な挙動と根拠
## 詳細な動作と根拠
<AccordionGroup>
<Accordion title="0. 任意の更新（gitインストール）">
これがgit checkoutでdoctorが対話的に実行されている場合、doctorを実行する前に更新（fetch/rebase/build）を提案します。
<Accordion title="0. 任意の更新（git インストール）">
これが git checkout であり doctor が対話的に実行されている場合、doctor 実行前に更新（fetch/rebase/build）を提示します。
</Accordion>
<Accordion title="1. 設定の正規化">
設定にレガシー値の形（たとえばチャネル固有の上書きがない`messages.ackReaction`）が含まれている場合、doctorはそれらを現在のスキーマへ正規化します。
設定にレガシー値の形（たとえばチャンネル固有の上書きがない `messages.ackReaction`）が含まれている場合、doctor はそれらを現在のスキーマへ正規化します。
これにはレガシーTalkフラットフィールドが含まれます。現在の公開Talk設定は`talk.provider` + `talk.providers.<provider>`です。Doctorは古い`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey`の形をプロバイダーマップへ書き換えます。
これにはレガシー Talk フラットフィールドが含まれます。現在の公開 Talk 設定は `talk.provider` + `talk.providers.<provider>` です。Doctor は古い `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形式をプロバイダーマップへ書き換えます。
Doctor はまた、`plugins.allow` が空でなく、ツールポリシーが
ワイルドカードまたは plugin 所有ツールエントリを使う場合に警告します。`tools.allow: ["*"]` は実際にロードされる plugins のツールだけに一致します。
排他的な plugin 許可リストをバイパスするものではありません。
</Accordion>
<Accordion title="2. レガシー設定キーの移行">
設定に非推奨キーが含まれている場合、他のコマンドは実行を拒否し、`openclaw doctor`の実行を求めます。
設定に非推奨キーが含まれている場合、他のコマンドは実行を拒否し、`openclaw doctor` の実行を求めます。
Doctorは次を行います。
Doctor は次を行います。
- 検出されたレガシーキーを説明します。
- 見つかったレガシーキーを説明します。
- 適用した移行を表示します。
- 更新済みスキーマで`~/.openclaw/openclaw.json`を書き換えます。
- 更新済みスキーマで `~/.openclaw/openclaw.json` を書き換えます。
Gatewayもレガシー設定形式を検出すると起動時にdoctor移行を自動実行するため、古い設定は手動介入なしで修復されます。Cronジョブストアの移行は`openclaw doctor --fix`で処理されます。
Gateway も起動時にレガシー設定形式を検出すると doctor 移行を自動実行するため、古い設定は手動介入なしで修復されます。Cron ジョブストア移行は `openclaw doctor --fix` によって処理されます。
現在の移行:
@ -190,88 +195,88 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- `routing.queue` → `messages.queue`
- `routing.bindings` → トップレベルの`bindings`
- `routing.bindings` → トップレベルの `bindings`
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- レガシー`talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- レガシー `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `messages.tts.providers.<provider>`
- `messages.tts.provider: "edge"`および`messages.tts.providers.edge` → `messages.tts.provider: "microsoft"`および`messages.tts.providers.microsoft`
- `channels.discord.voice.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.voice.tts.providers.<provider>`
- `channels.discord.accounts.<id>.voice.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
- `plugins.entries.voice-call.config.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `plugins.entries.voice-call.config.tts.providers.<provider>`
- `plugins.entries.voice-call.config.tts.provider: "edge"`および`plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"`および`providers.microsoft`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
- `messages.tts.provider: "edge"` と `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` と `messages.tts.providers.microsoft`
- `channels.discord.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.<provider>`
- `channels.discord.accounts.<id>.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
- `plugins.entries.voice-call.config.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.<provider>`
- `plugins.entries.voice-call.config.tts.provider: "edge"` と `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` と `providers.microsoft`
- `plugins.entries.voice-call.config.provider: "log"` → `"mock"`
- `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber`
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- 名前付き`accounts`があるものの、単一アカウントのトップレベルチャネル値が残っているチャネルでは、それらのアカウントスコープ値を、そのチャネルに対して選択された昇格先アカウントへ移動します（ほとんどのチャネルでは`accounts.default`。Matrixは既存の一致する名前付き/デフォルトターゲットを保持できます）
- 名前付き `accounts` がありながら、単一アカウント用のトップレベルチャネル値が残っているチャネルでは、そのアカウントスコープの値をそのチャネル用に選ばれた昇格済みアカウントへ移動する（ほとんどのチャネルでは `accounts.default`。Matrix は既存の一致する名前付き/デフォルトターゲットを維持できる）
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents）
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- `agents.defaults.llm`を削除。低速なプロバイダー/モデルのタイムアウトには`models.providers.<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値に設定されているプロバイダーは、閉じて失敗するのではなくスキップします）
- `browser.relayBindHost` を削除する（レガシー拡張リレー設定）
- レガシー `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 起動時は、`api` が将来の enum 値または不明な enum 値に設定されたプロバイダーについても、フェイルクローズせずにスキップする）
Doctor警告には、マルチアカウントチャネル向けのアカウントデフォルトガイダンスも含まれます。
Doctor の警告には、複数アカウントチャネル向けのアカウントデフォルトのガイダンスも含まれる。
- 2 つ以上の `channels.<channel>.accounts` エントリが `channels.<channel>.defaultAccount` または `accounts.default` なしで設定されている場合、doctor はフォールバックルーティングが予期しないアカウントを選ぶ可能性があると警告します。
- `channels.<channel>.defaultAccount` が不明なアカウント ID に設定されている場合、doctor は警告し、設定済みのアカウント 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 に強制されたり、コストがゼロになったりすることがあります。doctor は警告を出すため、そのオーバーライドを削除して、モデルごとの API ルーティングとコストを復元できます。
`models.providers.opencode`、`opencode-zen`、または `opencode-go` を手動で追加している場合、`@mariozechner/pi-ai` の組み込み OpenCode カタログをオーバーライドします。その結果、モデルが誤った API に割り当てられたり、コストがゼロになったりすることがあります。doctor は、オーバーライドを削除してモデルごとの API ルーティングとコストを復元できるように警告します。
</Accordion>
<Accordion title="2c. ブラウザー移行と Chrome MCP の準備状況">
ブラウザー設定が削除済みの Chrome 拡張機能パスをまだ指している場合、doctor は現在のホストローカル 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` プロファイルを使用している場合、doctor はホストローカル Chrome MCP パスも監査します。
doctor は、`defaultProfile: "user"` または設定済みの `existing-session` プロファイルを使う場合、ホストローカル Chrome MCP パスも監査します。
- デフォルトの自動接続プロファイルについて、同じホストに Google Chrome がインストールされているか確認します
- 検出された Chrome バージョンを確認し、Chrome 144 未満の場合は警告します
- ブラウザーの検査ページでリモートデバッグを有効にするよう通知します（例: `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`、または `edge://inspect/#remote-debugging`）
- デフォルトの自動接続プロファイルについて、同じホストに Google Chrome がインストールされているかを確認する
- 検出された Chrome バージョンを確認し、Chrome 144 未満の場合に警告する
- ブラウザーの検査ページでリモートデバッグを有効にするよう通知する（例: `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`、または `edge://inspect/#remote-debugging`）
doctor は Chrome 側の設定を有効にすることはできません。ホストローカル Chrome MCP には引き続き次が必要です。
doctor は Chrome 側の設定を有効化できません。ホストローカル Chrome MCP には引き続き以下が必要です。
- Gateway/Node ホスト上の Chromium ベースのブラウザー 144 以降
- ブラウザーがローカルで実行されていること
- そのブラウザーでリモートデバッグが有効になっていること
- ブラウザー内の最初のアタッチ同意プロンプトを承認すること
- gateway/node ホスト上の Chromium ベースブラウザー 144+
- ブラウザーがローカルで実行中であること
- そのブラウザーでリモートデバッグが有効であること
- ブラウザーで最初のアタッチ同意プロンプトを承認すること
ここでの準備状況は、ローカルアタッチの前提条件のみに関するものです。Existing-session は現在の Chrome MCP ルート制限を維持します。`responsebody`、PDF エクスポート、ダウンロードのインターセプト、バッチアクションなどの高度なルートには、引き続きマネージドブラウザーまたは生の CDP プロファイルが必要です。
ここでの準備状況はローカルアタッチの前提条件だけを対象とします。Existing-session は現在の Chrome MCP ルート制限を維持します。`responsebody`、PDF エクスポート、ダウンロードインターセプト、バッチアクションなどの高度なルートには、引き続き管理ブラウザーまたは raw CDP プロファイルが必要です。
このチェックは Docker、sandbox、remote-browser、またはその他のヘッドレスフローには**適用されません**。それらは引き続き生の CDP を使用します。
このチェックは Docker、sandbox、remote-browser、またはその他のヘッドレスフローには**適用されません**。それらは引き続き raw CDP を使用します。
</Accordion>
<Accordion title="2d. OAuth TLS の前提条件">
OpenAI Codex OAuth プロファイルが設定されている場合、doctor は OpenAI 認可エンドポイントをプローブし、ローカルの Node/OpenSSL TLS スタックが証明書チェーンを検証できることを確認します。プローブが証明書エラー（例: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、期限切れ証明書、または自己署名証明書）で失敗した場合、doctor はプラットフォーム別の修正ガイダンスを出力します。macOS で Homebrew Node を使用している場合、通常の修正は `brew postinstall ca-certificates` です。`--deep` では、Gateway が正常な場合でもプローブが実行されます。
OpenAI Codex OAuth プロファイルが設定されている場合、doctor は OpenAI 認可エンドポイントを検査し、ローカルの Node/OpenSSL TLS スタックが証明書チェーンを検証できるかを確認します。検査が証明書エラー（例: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、期限切れ証明書、自己署名証明書）で失敗した場合、doctor はプラットフォーム固有の修正ガイダンスを出力します。Homebrew Node を使っている macOS では、通常の修正は `brew postinstall ca-certificates` です。`--deep` では、Gateway が正常な場合でも検査が実行されます。
</Accordion>
<Accordion title="2e. Codex OAuth プロバイダーのオーバーライド">
以前に `models.providers.openai-codex` の下へレガシー OpenAI トランスポート設定を追加していた場合、新しいリリースが自動的に使用する組み込み Codex OAuth プロバイダーパスをそれらが覆い隠すことがあります。doctor は Codex OAuth と並んでそれらの古いトランスポート設定を検出すると警告するため、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を取り戻せます。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しません。
以前にレガシー OpenAI トランスポート設定を `models.providers.openai-codex` の下に追加していた場合、それらは新しいリリースが自動的に使う組み込み Codex OAuth プロバイダーパスをシャドーすることがあります。doctor は、Codex OAuth と並んでそれらの古いトランスポート設定を検出すると警告し、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を取り戻せるようにします。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しません。
</Accordion>
<Accordion title="2f. Codex Plugin ルート警告">
バンドルされた Codex Plugin が有効な場合、doctor は `openai-codex/*` のプライマリモデル参照がまだデフォルトの PI ランナー経由で解決されるかどうかも確認します。この組み合わせは、PI 経由で Codex OAuth/サブスクリプション認証を使いたい場合には有効ですが、ネイティブ Codex アプリサーバーハーネスと混同しやすいものです。doctor は警告し、明示的なアプリサーバー形式を示します: `openai/*` と `agentRuntime.id: "codex"`、または `OPENCLAW_AGENT_RUNTIME=codex`。
バンドルされた Codex Plugin が有効な場合、doctor は `openai-codex/*` のプライマリモデル参照がまだデフォルトの PI ランナー経由で解決されるかどうかも確認します。この組み合わせは PI 経由で Codex OAuth/サブスクリプション認証を使いたい場合には有効ですが、ネイティブ Codex アプリサーバーハーネスと混同しやすいものです。doctor は警告し、明示的なアプリサーバー形状として `openai/*` と `agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を示します。
doctor はこれを自動修復しません。どちらのルートも有効だからです。
両方のルートが有効であるため、doctor はこれを自動修復しません。
- `openai-codex/*` + PI は「通常の OpenClaw ランナー経由で Codex OAuth/サブスクリプション認証を使う」ことを意味します。
- `openai/*` + `runtime: "codex"` は「埋め込みターンをネイティブ Codex アプリサーバー経由で実行する」ことを意味します。
- `/codex ...` は「チャットからネイティブ Codex 会話を制御またはバインドする」ことを意味します。
- `/acp ...` または `runtime: "acp"` は「外部 ACP/acpx アダプターを使用する」ことを意味します。
- `openai-codex/*` + PI は「通常の OpenClaw ランナー経由で Codex OAuth/サブスクリプション認証を使う」という意味です。
- `openai/*` + `runtime: "codex"` は「埋め込みターンをネイティブ Codex アプリサーバー経由で実行する」という意味です。
- `/codex ...` は「チャットからネイティブ Codex 会話を制御またはバインドする」という意味です。
- `/acp ...` または `runtime: "acp"` は「外部 ACP/acpx アダプターを使う」という意味です。
警告が表示された場合は、意図したルートを選び、設定を手動で編集してください。PI Codex OAuth が意図したものである場合は、警告をそのままにしてください。
警告が表示された場合は、意図したルートを選び、設定を手動で編集してください。PI Codex OAuth が意図したものなら、警告はそのままにします。
</Accordion>
<Accordion title="3. レガシー状態の移行（ディスクレイアウト）">
<Accordion title="3. レガシー状態移行（ディスクレイアウト）">
doctor は古いオンディスクレイアウトを現在の構造へ移行できます。
- セッションストアとトランスクリプト:
- セッションストア + トランスクリプト:
- `~/.openclaw/sessions/` から `~/.openclaw/agents/<agentId>/sessions/` へ
- エージェントディレクトリ:
- `~/.openclaw/agent/` から `~/.openclaw/agents/<agentId>/agent/` へ
@ -279,16 +284,16 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- レガシー `~/.openclaw/credentials/*.json` から（`oauth.json` を除く）
- `~/.openclaw/credentials/whatsapp/<accountId>/...` へ（デフォルトアカウント ID: `default`）
これらの移行はベストエフォートで冪等です。doctor はレガシーフォルダーをバックアップとして残す場合、警告を出します。Gateway/CLI も起動時にレガシーのセッションとエージェントディレクトリを自動移行するため、手動で doctor を実行しなくても、履歴/認証/モデルはエージェントごとのパスに配置されます。WhatsApp 認証は意図的に `openclaw doctor` 経由でのみ移行されます。Talk プロバイダー/プロバイダーマップの正規化は現在、構造的等価性で比較するため、キー順序のみの差分では `doctor --fix` の無操作変更が繰り返し発生しなくなりました。
これらの移行はベストエフォートで冪等です。doctor は、バックアップとしてレガシーフォルダーを残す場合に警告を出します。Gateway/CLI も起動時にレガシーセッションとエージェントディレクトリを自動移行するため、手動で doctor を実行しなくても履歴/認証/モデルはエージェントごとのパスに配置されます。WhatsApp 認証は意図的に `openclaw doctor` 経由でのみ移行されます。Talk プロバイダー/プロバイダーマップの正規化は構造的等価性で比較するようになったため、キー順序だけの差分では、繰り返しの no-op `doctor --fix` 変更が発生しなくなりました。
</Accordion>
<Accordion title="3a. レガシー Plugin マニフェストの移行">
doctor は、非推奨のトップレベル機能キー（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）がないか、インストール済み Plugin マニフェストをすべてスキャンします。見つかった場合、それらを `contracts` オブジェクトへ移動し、マニフェストファイルをインプレースで書き換えることを提案します。この移行は冪等です。`contracts` キーに同じ値がすでにある場合、データを重複させずにレガシーキーが削除されます。
<Accordion title="3a. レガシー Plugin マニフェスト移行">
doctor は、非推奨のトップレベル機能キー（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）について、インストール済みのすべての Plugin マニフェストをスキャンします。見つかった場合、それらを `contracts` オブジェクトへ移動し、マニフェストファイルをその場で書き換えることを提案します。この移行は冪等です。`contracts` キーにすでに同じ値がある場合、データを重複させずにレガシーキーが削除されます。
</Accordion>
<Accordion title="3b. レガシー Cron ストアの移行">
doctor は 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`
@ -297,189 +302,189 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- ペイロードの `provider` 配信エイリアス → 明示的な `delivery.channel`
- 単純なレガシー `notify: true` Webhook フォールバックジョブ → `delivery.to=cron.webhook` を伴う明示的な `delivery.mode="webhook"`
doctor は、動作を変更せずに実行できる場合にのみ `notify: true` ジョブを自動移行します。ジョブがレガシー通知フォールバックと既存の非 Webhook 配信モードを組み合わせている場合、doctor は警告し、そのジョブを手動レビュー用に残します。
doctor は、動作を変えずに実行できる場合にのみ `notify: true` ジョブを自動移行します。ジョブがレガシー通知フォールバックと既存の非 Webhook 配信モードを組み合わせている場合、doctor は警告し、そのジョブを手動レビュー用に残します。
</Accordion>
<Accordion title="3c. セッションロックのクリーンアップ">
doctor は、各エージェントセッションディレクトリで古い書き込みロックファイル、つまりセッションが異常終了したときに残されたファイルをスキャンします。見つかった各ロックファイルについて、パス、PID、PID がまだ生存しているか、ロックの経過時間、古いと見なされるか（死んだ PID または 30 分超）を報告します。`--fix` / `--repair` モードでは古いロックファイルを自動的に削除します。それ以外の場合は注記を表示し、`--fix` で再実行するよう指示します。
doctor は、古い書き込みロックファイル、つまりセッションが異常終了したときに残されたファイルについて、すべてのエージェントセッションディレクトリをスキャンします。見つかった各ロックファイルについて、パス、PID、その PID がまだ生存しているか、ロックの経過時間、古いと見なされるかどうか（終了済み PID または 30 分超）を報告します。`--fix` / `--repair` モードでは、古いロックファイルを自動的に削除します。それ以外の場合は注記を出力し、`--fix` を付けて再実行するよう指示します。
</Accordion>
<Accordion title="3d. セッショントランスクリプトのブランチ修復">
doctor は、2026.4.24 のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形状がないか、エージェントセッション JSONL ファイルをスキャンします。これは、OpenClaw 内部ランタイムコンテキストを持つ放棄されたユーザーターンと、同じ可視ユーザープロンプトを含むアクティブな兄弟がある形状です。`--fix` / `--repair` モードでは、doctor は影響を受けた各ファイルを元ファイルの隣にバックアップし、Gateway 履歴とメモリーリーダーが重複ターンを見なくなるよう、トランスクリプトをアクティブブランチへ書き換えます。
doctor は、2026.4.24 のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形状について、エージェントセッション JSONL ファイルをスキャンします。その形状は、OpenClaw 内部ランタイムコンテキストを持つ放棄されたユーザーターンと、同じ表示ユーザープロンプトを含むアクティブな兄弟から成ります。`--fix` / `--repair` モードでは、doctor は影響を受けた各ファイルを元ファイルの隣にバックアップし、トランスクリプトをアクティブブランチへ書き換えることで、Gateway 履歴とメモリーリーダーが重複ターンを見ないようにします。
</Accordion>
<Accordion title="4. 状態の整合性チェック（セッション永続化、ルーティング、安全性）">
状態ディレクトリは運用上の中枢です。これが消えると、セッション、認証情報、ログ、設定を失います（別の場所にバックアップがない限り）。
<Accordion title="4. 状態整合性チェック（セッション永続化、ルーティング、安全性）">
状態ディレクトリは運用上の中枢です。これが消えると、セッション、認証情報、ログ、設定を失います（ほかにバックアップがある場合を除く）。
doctor は次を確認します。
doctor は以下を確認します。
- **状態ディレクトリの欠落**: 破滅的な状態喪失について警告し、ディレクトリの再作成を促し、失われたデータは復旧できないことを通知します。
- **状態ディレクトリの権限**: 書き込み可能性を検証します。権限の修復を提案します（所有者/グループの不一致が検出された場合は `chown` ヒントを出します）。
- **macOS のクラウド同期状態ディレクトリ**: 状態が iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）または `~/Library/CloudStorage/...` の下に解決される場合に警告します。同期バックアップ付きパスは I/O が遅くなり、ロック/同期競合を引き起こす可能性があるためです。
- **Linux の SD または eMMC 状態ディレクトリ**: 状態が `mmcblk*` マウントソースへ解決される場合に警告します。SD または eMMC バックのランダム I/O は、セッションと認証情報の書き込み時に遅く、摩耗が早くなる可能性があるためです。
- **セッションディレクトリの欠落**: 履歴を永続化し、`ENOENT` クラッシュを避けるため、`sessions/` とセッションストアディレクトリが必要です。
- **トランスクリプトの不一致**: 最近のセッションエントリにトランスクリプトファイルが欠落している場合に警告します。
- **メインセッション「1 行 JSONL」**: メイントランスクリプトが 1 行だけの場合にフラグを立てます（履歴が蓄積されていません）。
- **複数の状態ディレクトリ**: ホームディレクトリ間に複数の `~/.openclaw` フォルダーが存在する場合、または `OPENCLAW_STATE_DIR` が別の場所を指している場合に警告します（履歴がインストール間で分割される可能性があります）。
- **リモートモードのリマインダー**: `gateway.mode=remote` の場合、doctor はリモートホストで実行するよう通知します（状態はそこにあります）。
- **設定ファイルの権限**: `~/.openclaw/openclaw.json` がグループ/全員に読み取り可能な場合に警告し、`600` へ厳格化することを提案します。
- **状態ディレクトリがない**: 壊滅的な状態データの喪失について警告し、ディレクトリの再作成を促し、不足しているデータは復元できないことを通知します。
- **状態ディレクトリの権限**: 書き込み可能かを検証します。権限の修復を提案します（所有者/グループの不一致が検出された場合は `chown` のヒントも出力します）。
- **macOS のクラウド同期された状態ディレクトリ**: 状態が iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）または `~/Library/CloudStorage/...` の下に解決される場合に警告します。同期対象のパスでは I/O が遅くなり、ロック/同期の競合が発生する可能性があるためです。
- **Linux の SD または eMMC 状態ディレクトリ**: 状態が `mmcblk*` マウントソースに解決される場合に警告します。SD または eMMC ベースのランダム I/O は、セッションや認証情報の書き込み時に遅く、消耗が速くなる可能性があるためです。
- **セッションディレクトリがない**: 履歴を永続化し、`ENOENT` クラッシュを避けるには、`sessions/` とセッションストアディレクトリが必要です。
- **トランスクリプトの不一致**: 最近のセッションエントリに対応するトランスクリプトファイルがない場合に警告します。
- **メインセッション「1 行 JSONL」**: メインのトランスクリプトが 1 行しかない場合にフラグを立てます（履歴が蓄積されていません）。
- **複数の状態ディレクトリ**: 複数の `~/.openclaw` フォルダがホームディレクトリ間に存在する場合、または `OPENCLAW_STATE_DIR` が別の場所を指している場合に警告します（履歴がインストール間で分断される可能性があります）。
- **リモートモードのリマインダー**: `gateway.mode=remote` の場合、doctor はリモートホスト上で実行するよう通知します（状態はそこにあります）。
- **設定ファイルの権限**: `~/.openclaw/openclaw.json` がグループ/全員に読み取り可能な場合に警告し、`600` に厳格化することを提案します。
</Accordion>
<Accordion title="5. モデル認証の健全性（OAuth 有効期限）">
doctor は認証ストア内の OAuth プロファイルを検査し、トークンが期限切れ間近または期限切れの場合に警告し、安全な場合は更新できます。Anthropic OAuth/トークンプロファイルが古い場合、Anthropic API キーまたは Anthropic セットアップトークンパスを提案します。更新プロンプトは対話的に実行している場合（TTY）にのみ表示されます。`--non-interactive` は更新の試行をスキップします。
<Accordion title="5. モデル認証の健全性（OAuth の有効期限）">
Doctor は認証ストア内の OAuth プロファイルを検査し、トークンが期限切れ間近または期限切れの場合に警告し、安全な場合は更新できます。Anthropic OAuth/トークンプロファイルが古い場合は、Anthropic API キーまたは Anthropic セットアップトークンの経路を提案します。更新プロンプトは対話的に実行している場合（TTY）にのみ表示されます。`--non-interactive` では更新の試行をスキップします。
OAuth 更新が恒久的に失敗した場合（例: `refresh_token_reused`、`invalid_grant`、またはプロバイダーが再サインインを求める場合）、doctor は再認証が必要であることを報告し、実行すべき正確な `openclaw models auth login --provider ...` コマンドを出力します。
OAuth 更新が恒久的に失敗した場合（たとえば `refresh_token_reused`、`invalid_grant`、またはプロバイダーが再サインインを求めている場合）、doctor は再認証が必要であることを報告し、実行すべき正確な `openclaw models auth login --provider ...` コマンドを表示します。
doctor は、次の理由により一時的に利用できない認証プロファイルも報告します。
Doctor は、次の理由で一時的に使用できない認証プロファイルも報告します。
- 短いクールダウン（レート制限/タイムアウト/認証失敗）
- より長い無効化（請求/クレジット失敗）
</Accordion>
<Accordion title="6. フックのモデル検証">
`hooks.gmail.model` が設定されている場合、doctor はモデル参照をカタログおよび許可リストと照合して検証し、解決できない、または許可されていない場合に警告します。
<Accordion title="6. フックモデルの検証">
`hooks.gmail.model` が設定されている場合、doctor はモデル参照をカタログおよび許可リストに照らして検証し、解決できない場合や許可されていない場合に警告します。
</Accordion>
<Accordion title="7. サンドボックス画像の修復">
サンドボックスが有効な場合、doctor は Docker イメージを確認し、現在のイメージが見つからない場合は、ビルドするかレガシー名へ切り替えることを提案します。
<Accordion title="7. サンドボックスイメージの修復">
サンドボックス化が有効な場合、doctor は Docker イメージを確認し、現在のイメージがない場合はビルドまたはレガシー名への切り替えを提案します。
</Accordion>
<Accordion title="7b. バンドル済みPluginのランタイム依存関係">
Doctor は、現在の設定でアクティブなバンドル済みプラグイン、またはバンドル済みマニフェストのデフォルトで有効になっているバンドル済みプラグインについてのみ、ランタイム依存関係を検証します。例として、`plugins.entries.discord.enabled: true`、レガシーの `channels.discord.enabled: true`、設定済みの `models.providers.*` / エージェントモデル参照、またはプロバイダー所有権のないデフォルト有効のバンドル済みプラグインがあります。不足しているものがある場合、doctor はパッケージを報告し、`openclaw doctor --fix` / `openclaw doctor --repair` モードでそれらをインストールします。外部プラグインは引き続き `openclaw plugins install` / `openclaw plugins update` を使用します。doctor は任意のプラグインパスに対して依存関係をインストールしません。
<Accordion title="7b. バンドル済み Plugin のランタイム依存関係">
Doctor は、現在の設定でアクティブなバンドル済み Plugin、またはバンドル済みマニフェストのデフォルトで有効化される Plugin についてのみランタイム依存関係を検証します。たとえば、`plugins.entries.discord.enabled: true`、レガシーの `channels.discord.enabled: true`、設定済みの `models.providers.*` / エージェントモデル参照、またはプロバイダー所有権のないデフォルト有効のバンドル済み Plugin です。不足がある場合、doctor はパッケージを報告し、`openclaw doctor --fix` / `openclaw doctor --repair` モードでインストールします。外部 Plugin は引き続き `openclaw plugins install` / `openclaw plugins update` を使用します。doctor は任意の Plugin パスの依存関係をインストールしません。
doctor の修復中、バンドル済みランタイム依存関係の npm インストールは、TTY セッションではスピナー進捗を、パイプまたはヘッドレス出力では定期的な行単位の進捗を報告します。Gateway とローカル CLI は、バンドル済みプラグインをインポートする前に、必要に応じてアクティブなバンドル済みプラグインのランタイム依存関係も修復できます。これらのインストールはプラグインランタイムのインストールルートにスコープされ、スクリプトを無効化して実行され、パッケージロックを書き込まず、インストールルートのロックで保護されるため、同時実行される CLI または Gateway の起動が同じ `node_modules` ツリーを同時に変更することはありません。
doctor の修復中、バンドル済みランタイム依存関係の npm インストールは、TTY セッションではスピナー進捗を、パイプ/ヘッドレス出力では定期的な行進捗を報告します。Gateway とローカル CLI も、バンドル済み Plugin をインポートする前に、アクティブなバンドル済み Plugin のランタイム依存関係を必要に応じて修復できます。これらのインストールは Plugin ランタイムインストールルートに限定され、スクリプトを無効化して実行され、パッケージロックを書き込まず、インストールルートロックで保護されるため、同時に開始された CLI や Gateway が同じ `node_modules` ツリーを同時に変更することはありません。
</Accordion>
<Accordion title="8. Gateway サービス移行とクリーンアップのヒント">
Doctor はレガシーの gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して現在の gateway ポートを使用する OpenClaw サービスをインストールすることを提案します。また、追加の gateway 風サービスをスキャンして、クリーンアップのヒントを出力することもできます。プロファイル名付きの OpenClaw gateway サービスは第一級のものとみなされ、「extra」としてフラグされません。
<Accordion title="8. Gateway サービスの移行とクリーンアップのヒント">
Doctor はレガシー Gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して現在の Gateway ポートを使用する OpenClaw サービスをインストールすることを提案します。追加の Gateway 風サービスをスキャンしてクリーンアップのヒントを表示することもできます。プロファイル名付きの OpenClaw Gateway サービスは第一級のものと見なされ、「余分」としてフラグ付けされません。
Linux では、ユーザーレベルの gateway サービスが存在しない一方で、システムレベルの OpenClaw gateway サービスが存在する場合、doctor は 2 つ目のユーザーレベルサービスを自動的にはインストールしません。`openclaw gateway status --deep` または `openclaw doctor --deep` で確認してから、重複を削除するか、システムのスーパーバイザーが gateway ライフサイクルを所有している場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定してください。
Linux では、ユーザーレベルの Gateway サービスがない一方でシステムレベルの OpenClaw Gateway サービスが存在する場合、doctor は 2 つ目のユーザーレベルサービスを自動ではインストールしません。`openclaw gateway status --deep` または `openclaw doctor --deep` で調査し、重複を削除するか、システム supervisor が Gateway ライフサイクルを所有している場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定してください。
</Accordion>
<Accordion title="8b. 起動時の Matrix 移行">
Matrix チャネルアカウントに保留中または対応可能なレガシー状態移行がある場合、doctor は（`--fix` / `--repair` モードで）移行前スナップショットを作成し、その後ベストエフォートの移行手順を実行します。レガシー Matrix 状態移行とレガシー暗号化状態の準備です。どちらの手順も致命的ではありません。エラーはログに記録され、起動は継続します。読み取り専用モード（`--fix` なしの `openclaw doctor`）では、このチェックは完全にスキップされます。
Matrix チャネルアカウントに保留中または対応可能なレガシー状態移行がある場合、doctor は（`--fix` / `--repair` モードで）移行前スナップショットを作成し、その後ベストエフォートの移行手順を実行します。レガシー Matrix 状態移行と、レガシー暗号化状態の準備です。どちらの手順も致命的ではありません。エラーはログに記録され、起動は続行します。読み取り専用モード（`--fix` なしの `openclaw doctor`）では、このチェックは完全にスキップされます。
</Accordion>
<Accordion title="8c. デバイスペアリングと認証のずれ">
Doctor は通常のヘルスパスの一部として、デバイスペアリング状態を検査するようになりました。
<Accordion title="8c. デバイスのペアリングと認証ドリフト">
Doctor は通常の健全性チェックの一部として、デバイスペアリング状態を検査するようになりました。
報告内容:
- 保留中の初回ペアリング要求
- 保留中の初回ペアリングリクエスト
- すでにペアリング済みのデバイスに対する保留中のロールアップグレード
- すでにペアリング済みのデバイスに対する保留中のスコープアップグレード
- デバイス ID はまだ一致しているが、デバイス ID 情報が承認済みレコードと一致しなくなった場合の公開鍵不一致修復
- デバイス ID はまだ一致しているが、デバイス ID 情報が承認済みレコードと一致しなくなった公開鍵不一致の修復
- 承認済みロールのアクティブなトークンがないペアリング済みレコード
- スコープが承認済みペアリングベースラインの外へずれたペアリング済みトークン
- gateway 側のトークンローテーションより古い、または古いスコープメタデータを持つ、現在のマシン用のローカルキャッシュ済みデバイストークンエントリ
- 承認済みペアリングベースラインの外へスコープがずれたペアリング済みトークン
- Gateway 側のトークンローテーションより古い、または古いスコープメタデータを持つ、現在のマシンのローカルキャッシュ済みデバイストークンエントリ
Doctor はペアリング要求を自動承認したり、デバイストークンを自動ローテーションしたりしません。代わりに正確な次の手順を出力します。
Doctor はペアリングリクエストを自動承認したり、デバイストークンを自動ローテーションしたりしません。代わりに正確な次の手順を表示します。
- `openclaw devices list` で保留中の要求を確認する
- `openclaw devices approve <requestId>` で正確な要求を承認する
- `openclaw devices list` で保留中のリクエストを調査する
- `openclaw devices approve <requestId>` で正確なリクエストを承認する
- `openclaw devices rotate --device <deviceId> --role <role>` で新しいトークンをローテーションする
- `openclaw devices remove <deviceId>` で古いレコードを削除して再承認する
これにより、よくある「すでにペアリング済みなのに、まだペアリングが必要と表示される」穴が塞がれます。doctor は初回ペアリング、保留中のロール/スコープアップグレード、古いトークン/デバイス ID 情報のずれを区別するようになりました。
これにより、よくある「すでにペアリング済みなのにまだペアリングが必要と表示される」問題が解消されます。doctor は初回ペアリングを、保留中のロール/スコープアップグレードや、古いトークン/デバイス ID 情報のドリフトと区別するようになりました。
</Accordion>
<Accordion title="9. セキュリティ警告">
Doctor は、プロバイダーが許可リストなしで DM に開放されている場合、またはポリシーが危険な方法で設定されている場合に警告を出します。
Doctor は、プロバイダーが許可リストなしで DM に開かれている場合、またはポリシーが危険な方法で設定されている場合に警告を出力します。
</Accordion>
<Accordion title="10. systemd linger（Linux）">
systemd ユーザーサービスとして実行している場合、doctor はログアウト後も gateway が稼働し続けるよう lingering が有効であることを確認します。
systemd ユーザーサービスとして実行している場合、doctor はログアウト後も Gateway が稼働し続けるよう linger が有効になっていることを確認します。
</Accordion>
<Accordion title="11. ワークスペース状態（skills、プラグイン、レガシーディレクトリ）">
Doctor はデフォルトエージェントのワークスペース状態の概要を出力します。
<Accordion title="11. ワークスペース状態（Skills、plugins、レガシーディレクトリ）">
Doctor はデフォルトエージェントのワークスペース状態の概要を表示します。
- **Skills 状態**: 対象、要件不足、許可リストでブロックされた Skills の数。
- **レガシーワークスペースディレクトリ**: `~/openclaw` またはその他のレガシーワークスペースディレクトリが現在のワークスペースと並んで存在する場合に警告します。
- **プラグイン状態**: 有効/無効/エラーのプラグイン数を数えます。エラーがある場合はプラグイン ID を列挙します。バンドルプラグインの機能を報告します。
- **プラグイン互換性警告**: 現在のランタイムとの互換性の問題があるプラグインにフラグを付けます。
- **プラグイン診断**: プラグインレジストリがロード時に出力した警告またはエラーを表示します。
- **Skills 状態**: 対象、要件不足、許可リストでブロックされた Skills の数を数えます。
- **レガシーワークスペースディレクトリ**: `~/openclaw` または他のレガシーワークスペースディレクトリが現在のワークスペースと並んで存在する場合に警告します。
- **Plugin 状態**: 有効/無効/エラーの Plugin 数を数えます。エラーがある場合は Plugin ID を一覧表示します。バンドル Plugin の機能を報告します。
- **Plugin 互換性警告**: 現在のランタイムと互換性の問題がある Plugin にフラグを立てます。
- **Plugin 診断**: Plugin レジストリがロード時に出力した警告やエラーを表示します。
</Accordion>
<Accordion title="11b. ブートストラップファイルサイズ">
Doctor は、ワークスペースのブートストラップファイル（例: `AGENTS.md`、`CLAUDE.md`、またはその他の注入済みコンテキストファイル）が、設定された文字数予算に近い、または超過していないかを確認します。ファイルごとの生の文字数と注入済み文字数、切り詰め率、切り詰め原因（`max/file` または `max/total`）、および合計注入文字数を合計予算に対する割合として報告します。ファイルが切り詰められている、または上限に近い場合、doctor は `agents.defaults.bootstrapMaxChars` と `agents.defaults.bootstrapTotalMaxChars` を調整するためのヒントを出力します。
Doctor は、ワークスペースのブートストラップファイル（たとえば `AGENTS.md`、`CLAUDE.md`、またはその他の挿入済みコンテキストファイル）が、設定済みの文字数予算に近いか超過しているかを確認します。ファイルごとの raw と挿入後の文字数、切り詰め率、切り詰め原因（`max/file` または `max/total`）、および合計挿入文字数が総予算に占める割合を報告します。ファイルが切り詰められている、または上限に近い場合、doctor は `agents.defaults.bootstrapMaxChars` と `agents.defaults.bootstrapTotalMaxChars` の調整に関するヒントを表示します。
</Accordion>
<Accordion title="11d. 古いチャネルプラグインのクリーンアップ">
`openclaw doctor --fix` が見つからないチャネルプラグインを削除する場合、そのプラグインを参照していたぶら下がったチャネルスコープ設定も削除します。`channels.<id>` エントリ、チャネル名を指定した heartbeat ターゲット、および `agents.*.models["<channel>/*"]` オーバーライドです。これにより、チャネルランタイムがなくなっているのに設定が gateway にそれへのバインドを求め続ける Gateway ブートループを防ぎます。
<Accordion title="11d. 古いチャネル Plugin のクリーンアップ">
`openclaw doctor --fix` が不足しているチャネル Plugin を削除する場合、その Plugin を参照していたぶら下がりのチャネルスコープ設定も削除します。`channels.<id>` エントリ、そのチャネル名を指定していた Heartbeat ターゲット、`agents.*.models["<channel>/*"]` オーバーライドです。これにより、チャネルランタイムがなくなっているのに設定が Gateway にバインドを求め続ける Gateway ブートループを防ぎます。
</Accordion>
<Accordion title="11c. シェル補完">
Doctor は、現在のシェル（zsh、bash、fish、または PowerShell）にタブ補完がインストールされているかを確認します。
- シェルプロファイルが低速な動的補完パターン（`source <(openclaw completion ...)`）を使用している場合、doctor はそれをより高速なキャッシュ済みファイルのバリアントへアップグレードします。
- 補完がプロファイルに設定されているがキャッシュファイルがない場合、doctor はキャッシュを自動的に再生成します。
- 補完がまったく設定されていない場合、doctor はインストールを促します（インタラクティブモードのみ。`--non-interactive` ではスキップ）。
- シェルプロファイルが遅い動的補完パターン（`source <(openclaw completion ...)`）を使用している場合、doctor はより高速なキャッシュファイル方式にアップグレードします。
- 補完がプロファイルで設定されているがキャッシュファイルがない場合、doctor はキャッシュを自動で再生成します。
- 補完がまったく設定されていない場合、doctor はインストールを促します（対話モードのみ。`--non-interactive` ではスキップされます）。
キャッシュを手動で再生成するには、`openclaw completion --write-state` を実行してください。
キャッシュを手動で再生成するには `openclaw completion --write-state` を実行してください。
</Accordion>
<Accordion title="12. Gateway 認証チェック（ローカルトークン）">
Doctor はローカル gateway トークン認証の準備状態を確認します。
Doctor はローカル Gateway トークン認証の準備状態を確認します。
- トークンモードでトークンが必要で、トークンソースが存在しない場合、doctor は生成を提案します。
- `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 経由で設定されているが、現在のコマンドパスで利用できない場合、doctor はその認証情報が設定済みだが利用不可であることを報告し、クラッシュしたりトークンがないと誤報告したりする代わりに自動解決をスキップします。
- `openclaw doctor --fix` は、対象を絞った設定修復に、status 系コマンドと同じ読み取り専用 SecretRef サマリーモデルを使用するようになりました。
- 例: Telegram の `allowFrom` / `groupAllowFrom` `@username` 修復は、利用可能な場合に設定済み bot 認証情報の使用を試みます。
- Telegram bot トークンが SecretRef 経由で設定されているが、現在のコマンド経路で利用できない場合、doctor はその認証情報が設定済みだが利用不可であることを報告し、クラッシュしたりトークンがないと誤報告したりする代わりに自動解決をスキップします。
</Accordion>
<Accordion title="13. Gateway ヘルスチェック + 再起動">
Doctor はヘルスチェックを実行し、gateway が異常に見える場合は再起動を提案します。
<Accordion title="13. Gateway の健全性チェックと再起動">
Doctor は健全性チェックを実行し、Gateway が不健全に見える場合は再起動を提案します。
</Accordion>
<Accordion title="13b. メモリ検索の準備状態">
Doctor は、設定済みのメモリ検索埋め込みプロバイダーがデフォルトエージェントに対して準備できているかを確認します。動作は設定されたバックエンドとプロバイダーによって異なります。
Doctor は、設定済みのメモリ検索埋め込みプロバイダーがデフォルトエージェントで使用可能かどうかを確認します。動作は、設定されたバックエンドとプロバイダーによって異なります。
- **QMD バックエンド**: `qmd` バイナリが利用可能で起動可能かをプローブします。そうでない場合は、npm パッケージと手動バイナリパスのオプションを含む修正ガイダンスを出力します。
- **QMD バックエンド**: `qmd` バイナリが利用可能で起動可能かどうかをプローブします。そうでない場合、npm パッケージや手動バイナリパスの選択肢を含む修正ガイダンスを表示します。
- **明示的なローカルプロバイダー**: ローカルモデルファイル、または認識済みのリモート/ダウンロード可能なモデル URL を確認します。不足している場合は、リモートプロバイダーへの切り替えを提案します。
- **明示的なリモートプロバイダー**（`openai`、`voyage` など）: API キーが環境または認証ストアに存在することを検証します。不足している場合は、実行可能な修正ヒントを出力します。
- **自動プロバイダー**: まずローカルモデルの可用性を確認し、その後、自動選択順に各リモートプロバイダーを試します。
- **明示的なリモートプロバイダー**（`openai`、`voyage` など）: API キーが環境または認証ストアに存在することを検証します。不足している場合は、実行可能な修正ヒントを表示します。
- **自動プロバイダー**: まずローカルモデルの可用性を確認し、その後、自動選択順で各リモートプロバイダーを試します。
キャッシュ済み gateway プローブ結果が利用可能な場合（チェック時点で gateway が正常だった場合）、doctor はその結果を CLI から見える設定と相互参照し、差異があれば通知します。doctor はデフォルトパスで新しい埋め込み ping を開始しません。ライブのプロバイダーチェックが必要な場合は、詳細なメモリ状態コマンドを使用してください。
キャッシュされた Gateway プローブ結果が利用可能な場合（チェック時点で Gateway が正常だった場合）、doctor はその結果を CLI から見える設定と照合し、不一致があれば記録します。Doctor はデフォルトパスでは新しい埋め込み ping を開始しません。ライブのプロバイダーチェックが必要な場合は、deep memory status コマンドを使用します。
実行時の埋め込み準備状態を検証するには、`openclaw memory status --deep` を使用してください。
実行時の埋め込み準備状態を確認するには `openclaw memory status --deep` を使用します。
</Accordion>
<Accordion title="14. チャネル状態の警告">
gateway が正常な場合、doctor はチャネル状態プローブを実行し、推奨される修正とともに警告を報告します。
<Accordion title="14. チャンネルステータス警告">
Gateway が正常な場合、doctor はチャンネルステータスプローブを実行し、推奨される修正とともに警告を報告します。
</Accordion>
<Accordion title="15. スーパーバイザー設定の監査 + 修復">
Doctor は、インストール済みのスーパーバイザー設定（launchd/systemd/schtasks）について、欠落または古くなったデフォルト（例: systemd の network-online 依存関係と再起動遅延）を確認します。不一致を見つけた場合、更新を推奨し、サービスファイル/タスクを現在のデフォルトに書き換えることができます。
<Accordion title="15. Supervisor 設定監査 + 修復">
Doctor はインストール済みの supervisor 設定（launchd/systemd/schtasks）に、欠落または古いデフォルト（例: systemd の network-online 依存関係や再起動遅延）がないか確認します。不一致が見つかった場合は更新を推奨し、サービスファイル/タスクを現在のデフォルトに書き換えることができます。
注:
注記:
- `openclaw doctor` はスーパーバイザー設定を書き換える前に確認します。
- `openclaw doctor` は supervisor 設定を書き換える前に確認を求めます。
- `openclaw doctor --yes` はデフォルトの修復プロンプトを承認します。
- `openclaw doctor --repair` はプロンプトなしで推奨修正を適用します。
- `openclaw doctor --repair --force` はカスタムのスーパーバイザー設定を上書きします。
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` は Gateway サービスのライフサイクルについて doctor を読み取り専用のままにします。サービスの健全性は引き続き報告し、サービス以外の修復も実行しますが、外部スーパーバイザーがそのライフサイクルを所有しているため、サービスのインストール/開始/再起動/ブートストラップ、スーパーバイザー設定の書き換え、レガシーサービスのクリーンアップはスキップします。
- Linux では、一致する systemd Gateway ユニットがアクティブな間、doctor はコマンド/エントリポイントのメタデータを書き換えません。また、重複サービスのスキャン中に非アクティブで非レガシーの追加 Gateway 風ユニットを無視するため、関連サービスファイルによってクリーンアップのノイズが発生しません。
- トークン認証にトークンが必要で、`gateway.auth.token` が SecretRef 管理の場合、doctor のサービスインストール/修復は SecretRef を検証しますが、解決済みの平文トークン値をスーパーバイザーサービス環境メタデータには永続化しません。
- Doctor は、古い LaunchAgent、systemd、または Windows Scheduled Task のインストールがインラインで埋め込んだ、管理対象の `.env`/SecretRef ベースのサービス環境値を検出し、それらの値がスーパーバイザー定義ではなくランタイムソースから読み込まれるようにサービスメタデータを書き換えます。
- Doctor は、`gateway.port` の変更後もサービスコマンドが古い `--port` に固定されている場合に検出し、サービスメタデータを現在のポートに書き換えます。
- トークン認証にトークンが必要で、設定済みのトークン SecretRef が解決されていない場合、doctor は実行可能なガイダンスを示してインストール/修復パスをブロックします。
- `gateway.auth.token` と `gateway.auth.password` の両方が設定され、`gateway.auth.mode` が未設定の場合、doctor はモードが明示的に設定されるまでインストール/修復をブロックします。
- Linux のユーザー systemd ユニットでは、doctor のトークンドリフトチェックは、サービス認証メタデータを比較するときに `Environment=` と `EnvironmentFile=` の両方のソースを含むようになりました。
- `openclaw doctor --repair --force` はカスタム supervisor 設定を上書きします。
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` は Gateway サービスライフサイクルについて doctor を読み取り専用にします。サービスの健全性を引き続き報告し、サービス以外の修復も実行しますが、外部 supervisor がそのライフサイクルを所有しているため、サービスのインストール/開始/再起動/bootstrap、supervisor 設定の書き換え、レガシーサービスのクリーンアップはスキップします。
- Linux では、対応する systemd Gateway ユニットがアクティブな間、doctor はコマンド/エントリポイントのメタデータを書き換えません。また、重複サービスのスキャン中は、非アクティブな非レガシーの追加 Gateway 風ユニットを無視するため、付随するサービスファイルがクリーンアップのノイズを生みません。
- トークン認証にトークンが必要で、`gateway.auth.token` が SecretRef 管理の場合、doctor のサービスインストール/修復は SecretRef を検証しますが、解決済みの平文トークン値を supervisor サービス環境メタデータには永続化しません。
- Doctor は、古い LaunchAgent、systemd、または Windows Scheduled Task のインストールがインラインに埋め込んだ、管理対象の `.env`/SecretRef ベースのサービス環境値を検出し、それらの値が supervisor 定義ではなく実行時ソースから読み込まれるようにサービスメタデータを書き換えます。
- Doctor は、`gateway.port` の変更後もサービスコマンドが古い `--port` を固定している場合に検出し、サービスメタデータを現在のポートに書き換えます。
- トークン認証にトークンが必要で、設定されたトークン SecretRef が解決されていない場合、doctor は実行可能な案内とともにインストール/修復パスをブロックします。
- `gateway.auth.token` と `gateway.auth.password` の両方が設定され、`gateway.auth.mode` が未設定の場合、doctor は mode が明示的に設定されるまでインストール/修復をブロックします。
- Linux user-systemd ユニットでは、doctor のトークンドリフトチェックは、サービス認証メタデータの比較時に `Environment=` と `EnvironmentFile=` の両方のソースを含むようになりました。
- Doctor のサービス修復は、設定がより新しいバージョンによって最後に書き込まれている場合、古い OpenClaw バイナリから Gateway サービスを書き換えたり、停止したり、再起動したりすることを拒否します。[Gateway トラブルシューティング](/ja-JP/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)を参照してください。
- `openclaw gateway install --force` を使えば、いつでも完全な書き換えを強制できます。
- `openclaw gateway install --force` を使用すれば、いつでも完全な書き換えを強制できます。
</Accordion>
<Accordion title="16. Gateway ランタイム + ポート診断">
Doctor はサービスランタイム（PID、直近の終了ステータス）を検査し、サービスがインストールされているのに実際には実行されていない場合に警告します。また、Gateway ポート（デフォルトは `18789`）でポート競合がないか確認し、考えられる原因（Gateway がすでに実行中、SSH トンネル）を報告します。
Doctor はサービスランタイム（PID、最後の終了ステータス）を検査し、サービスがインストールされているのに実際には実行されていない場合に警告します。また、Gateway ポート（デフォルト `18789`）のポート衝突を確認し、考えられる原因（Gateway がすでに実行中、SSH トンネル）を報告します。
</Accordion>
<Accordion title="17. Gateway ランタイムのベストプラクティス">
Doctor は、Gateway サービスが Bun またはバージョン管理された Node パス（`nvm`、`fnm`、`volta`、`asdf` など）で実行されている場合に警告します。WhatsApp + Telegram チャネルには Node が必要であり、バージョンマネージャーのパスは、サービスがシェル初期化を読み込まないため、アップグレード後に壊れる可能性があります。Doctor は、利用可能な場合はシステムの Node インストール（Homebrew/apt/choco）へ移行するよう提案します。
Doctor は、Gateway サービスが Bun またはバージョン管理された Node パス（`nvm`、`fnm`、`volta`、`asdf` など）で実行されている場合に警告します。WhatsApp + Telegram チャンネルには Node が必要であり、バージョンマネージャーのパスは、サービスがシェル初期化を読み込まないため、アップグレード後に壊れる可能性があります。Doctor は、利用可能な場合にシステムの Node インストール（Homebrew/apt/choco）への移行を提案します。
新規インストールまたは修復されたサービスは、明示的な環境ルート（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）と安定したユーザー bin ディレクトリを保持しますが、推測されたバージョンマネージャーのフォールバックディレクトリは、そのディレクトリがディスク上に存在する場合にのみサービス PATH に書き込まれます。これにより、生成されたスーパーバイザー PATH が、後で doctor が実行する同じ最小 PATH 監査と整合します。
新しくインストールまたは修復されたサービスは、明示的な環境ルート（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）と安定したユーザー bin ディレクトリを保持しますが、推測されたバージョンマネージャーのフォールバックディレクトリは、それらのディレクトリがディスク上に存在する場合にのみサービス PATH に書き込まれます。これにより、生成された supervisor PATH は、doctor が後で実行する同じ最小 PATH 監査と整合します。
</Accordion>
<Accordion title="18. 設定書き込み + ウィザードメタデータ">
Doctor は設定変更を永続化し、doctor 実行を記録するためにウィザードメタデータをスタンプします。
</Accordion>
<Accordion title="19. ワークスペースのヒント（バックアップ + メモリシステム）">
Doctor は、ワークスペースメモリシステムがない場合に提案し、ワークスペースがまだ git 管理下にない場合はバックアップのヒントを出力します。
Doctor は、不足している場合にワークスペースメモリシステムを提案し、ワークスペースがまだ git 管理下にない場合はバックアップのヒントを表示します。
ワークスペース構造と git バックアップ（プライベート GitHub または GitLab を推奨）の完全なガイドについては、[/concepts/agent-workspace](/ja-JP/concepts/agent-workspace) を参照してください。
@ -488,5 +493,5 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
## 関連
- [Gateway ランブック](/ja-JP/gateway)
- [Gateway runbook](/ja-JP/gateway)
- [Gateway トラブルシューティング](/ja-JP/gateway/troubleshooting)

392
docs/ja-JP/gateway/protocol.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Gateway WS クライアントの実装または更新
- プロトコルの不一致や接続失敗のデバッグ
- プロトコルスキーマ/モデルの再生成
summary: 'Gateway WebSocketプロトコル: ハンドシェイク、フレーム、バージョン管理'
- プロトコルの不一致または接続失敗のデバッグ
- プロトコルのスキーマ/モデルを再生成する
summary: 'Gateway WebSocket プロトコル: ハンドシェイク、フレーム、バージョン管理'
title: Gateway プロトコル
x-i18n:
generated_at: "2026-04-30T05:15:25Z"
generated_at: "2026-05-01T05:01:24Z"
model: gpt-5.5
provider: openai
source_hash: c0d922e9b4b778c333873e551498b905461f30f944e809555b45669ae2f5c404
source_hash: a6da9ce755b941789ae6b9e866247c8bebb86e9a1530fb8cb258fb0650b24b8a
source_path: gateway/protocol.md
workflow: 16
---
Gateway WS プロトコルは、OpenClaw の**単一のコントロールプレーン + ノードトランスポート**です。すべてのクライアント（CLI、Web UI、macOS アプリ、iOS/Android ノード、ヘッドレスノード）は WebSocket 経由で接続し、ハンドシェイク時に自身の**ロール** + **スコープ**を宣言します。
OpenClaw における Gateway WS プロトコルは、**単一のコントロールプレーン + ノードトランスポート**です。すべてのクライアント（CLI、Web UI、macOS アプリ、iOS/Android ノード、ヘッドレスノード）は WebSocket 経由で接続し、ハンドシェイク時に自身の **role** + **scope** を宣言します。
## トランスポート
- WebSocket、JSON ペイロードを持つテキストフレーム。
- 最初のフレームは**必ず** `connect` リクエストでなければなりません。
- 接続前フレームは 64 KiB に制限されます。ハンドシェイクが成功した後、クライアントは `hello-ok.policy.maxPayload` と `hello-ok.policy.maxBufferedBytes` の制限に従う必要があります。診断が有効な場合、過大な受信フレームと遅い送信バッファーは、gateway が対象フレームを閉じるか破棄する前に `payload.large` イベントを発行します。これらのイベントは、サイズ、制限、サーフェス、安全な理由コードを保持します。メッセージ本文、添付ファイルの内容、生フレーム本文、トークン、Cookie、秘密値は保持しません。
- 最初のフレームは **必ず** `connect` リクエストでなければなりません。
- 接続前フレームは 64 KiB に制限されます。ハンドシェイクが成功した後、クライアントは `hello-ok.policy.maxPayload` と `hello-ok.policy.maxBufferedBytes` の制限に従う必要があります。診断が有効な場合、サイズ超過の受信フレームと低速な送信バッファーは、Gateway が対象フレームを閉じるか破棄する前に `payload.large` イベントを発行します。これらのイベントは、サイズ、制限、サーフェス、安全な理由コードを保持します。メッセージ本文、添付内容、生フレーム本文、トークン、Cookie、シークレット値は保持しません。
## ハンドシェイク（connect）
@ -95,9 +95,9 @@ Gateway → クライアント:
}
```
Gateway がまだ起動サイドカーの完了処理中の場合、`connect` リクエストは、`details.reason` が `"startup-sidecars"` に設定され、`retryAfterMs` を含む、再試行可能な `UNAVAILABLE` エラーを返すことがあります。クライアントは、その応答を最終的なハンドシェイク失敗として表面化させるのではなく、全体の接続予算内で再試行する必要があります。
Gateway がまだ起動サイドカーを完了中の場合、`connect` リクエストは `details.reason` が `"startup-sidecars"` に設定され、`retryAfterMs` を持つ再試行可能な `UNAVAILABLE` エラーを返すことがあります。クライアントは、その応答を最終的なハンドシェイク失敗として表示するのではなく、全体の接続予算内で再試行する必要があります。
`server`、`features`、`snapshot`、`policy` はすべてスキーマ（`src/gateway/protocol/schema/frames.ts`）で必須です。`auth` も必須で、ネゴシエートされたロール/スコープを報告します。`canvasHostUrl` は任意です。
`server`、`features`、`snapshot`、`policy` はすべてスキーマ（`src/gateway/protocol/schema/frames.ts`）で必須です。`auth` も必須で、ネゴシエートされた role/scopes を報告します。`canvasHostUrl` は任意です。
デバイストークンが発行されない場合、`hello-ok.auth` はトークンフィールドなしでネゴシエートされた権限を報告します。
@ -110,7 +110,7 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect`
}
```
信頼された同一プロセスのバックエンドクライアント（`client.id: "gateway-client"`、`client.mode: "backend"`）は、共有 gateway トークン/パスワードで認証する場合、直接ループバック接続で `device` を省略できます。この経路は内部コントロールプレーン RPC 用に予約されており、古い CLI/デバイスペアリングのベースラインが、サブエージェントセッション更新などのローカルバックエンド作業をブロックしないようにします。リモートクライアント、ブラウザーオリジンのクライアント、ノードクライアント、および明示的なデバイストークン/デバイス ID クライアントは、引き続き通常のペアリングとスコープアップグレードのチェックを使用します。
信頼済みの同一プロセスバックエンドクライアント（`client.id: "gateway-client"`、`client.mode: "backend"`）は、共有 Gateway トークン/パスワードで認証する場合、直接 local loopback 接続で `device` を省略できます。この経路は内部コントロールプレーン RPC 用に予約されており、古い CLI/デバイスペアリング基準値がサブエージェントセッション更新などのローカルバックエンド作業をブロックしないようにします。リモートクライアント、ブラウザーオリジンクライアント、ノードクライアント、明示的なデバイストークン/デバイス ID クライアントは、引き続き通常のペアリングとスコープアップグレードチェックを使用します。
デバイストークンが発行される場合、`hello-ok` には次も含まれます。
@ -124,7 +124,7 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect`
}
```
信頼されたブートストラップ引き渡し中、`hello-ok.auth` には `deviceTokens` に追加の境界付きロールエントリが含まれる場合もあります。
信頼済みブートストラップの引き渡し中、`hello-ok.auth` には `deviceTokens` 内の追加の制限付き role エントリも含まれることがあります。
```json
{
@ -143,9 +143,9 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect`
}
```
組み込みのノード/オペレーターブートストラップフローでは、プライマリノードトークンは `scopes: []` のままで、引き渡されたオペレータートークンはブートストラップオペレーターの許可リスト（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）に境界付けられたままです。ブートストラップスコープチェックはロールプレフィックス付きのままです。operator エントリは operator リクエストのみを満たし、operator 以外のロールは引き続き自身のロールプレフィックス配下のスコープを必要とします。
組み込みのノード/operator ブートストラップフローでは、プライマリノードトークンは `scopes: []` のままで、引き渡された operator トークンはブートストラップ operator 許可リスト（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）に制限されたままです。ブートストラップスコープチェックは role 接頭辞付きのままです。operator エントリは operator リクエストのみを満たし、operator 以外の role は引き続き自身の role 接頭辞配下のスコープを必要とします。
### ノード例
### Node の例
```json
{
@ -186,11 +186,11 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect`
- **レスポンス**: `{type:"res", id, ok, payload|error}`
- **イベント**: `{type:"event", event, payload, seq?, stateVersion?}`
副作用のあるメソッドには**冪等性キー**が必要です（スキーマを参照）。
副作用のあるメソッドには **冪等性キー** が必要です（スキーマを参照）。
## ロール + スコープ
## role + scope
### ロール
### role
- `operator` = コントロールプレーンクライアント（CLI/UI/自動化）。
- `node` = 機能ホスト（camera/screen/canvas/system.run）。
@ -208,36 +208,35 @@ Gateway がまだ起動サイドカーの完了処理中の場合、`connect`
`includeSecrets: true` を指定した `talk.config` には `operator.talk.secrets`（または `operator.admin`）が必要です。
Plugin 登録の gateway RPC メソッドは独自の operator スコープを要求できますが、予約済みのコア管理プレフィックス（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は常に `operator.admin` に解決されます。
Plugin に登録された Gateway RPC メソッドは独自の operator スコープを要求できますが、予約済みのコア管理接頭辞（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は常に `operator.admin` に解決されます。
メソッドスコープは最初のゲートにすぎません。`chat.send` を通じて到達する一部のスラッシュコマンドでは、その上により厳格なコマンドレベルのチェックが適用されます。たとえば、永続的な `/config set` と `/config unset` の書き込みには `operator.admin` が必要です。
メソッドスコープは最初のゲートにすぎません。`chat.send` 経由で到達する一部のスラッシュコマンドは、さらに厳格なコマンドレベルのチェックを適用します。たとえば、永続的な `/config set` と `/config unset` の書き込みには `operator.admin` が必要です。
`node.pair.approve` には、基本メソッドスコープに加えて、承認時の追加スコープチェックもあります。
- コマンドなしリクエスト: `operator.pairing`
- exec 以外のノードコマンドを含むリクエスト: `operator.pairing` + `operator.write`
- `system.run`、`system.run.prepare`、または `system.which` を含むリクエスト:
`operator.pairing` + `operator.admin`
- `system.run`、`system.run.prepare`、または `system.which` を含むリクエスト: `operator.pairing` + `operator.admin`
### caps/commands/permissions（node）
ノードは接続時に機能要求を宣言します。
- `caps`: 高レベルの機能カテゴリ。
- `commands`: invoke のコマンド許可リスト。
- `permissions`: 詳細な切り替え（例: `screen.record`、`camera.capture`）。
- `commands`: invoke 用のコマンド許可リスト。
- `permissions`: きめ細かなトグル（例: `screen.record`、`camera.capture`）。
Gateway はこれらを**要求**として扱い、サーバー側の許可リストを強制します。
Gateway はこれらを **要求** として扱い、サーバー側の許可リストを適用します。
## プレゼンス
- `system-presence` はデバイス ID をキーにしたエントリを返します。
- プレゼンスエントリには `deviceId`、`roles`、`scopes` が含まれるため、UI は同じデバイスが **operator** と **node** の両方として接続している場合でも、デバイスごとに 1 行で表示できます。
- `node.list` には任意の `lastSeenAtMs` と `lastSeenReason` フィールドが含まれます。接続中のノードは、現在の接続時刻を理由 `connect` とともに `lastSeenAtMs` として報告します。ペアリング済みノードは、信頼されたノードイベントがペアリングメタデータを更新したときに、永続的なバックグラウンドプレゼンスも報告できます。
- `node.list` には任意の `lastSeenAtMs` と `lastSeenReason` フィールドが含まれます。接続中のノードは現在の接続時刻を `lastSeenAtMs` として、理由 `connect` とともに報告します。ペアリング済みノードは、信頼済みノードイベントがペアリングメタデータを更新したときに、永続的なバックグラウンドプレゼンスも報告できます。
### ノードバックグラウンド生存イベント
### ノードのバックグラウンド生存イベント
ノードは `event: "node.presence.alive"` を指定して `node.event` を呼び出し、ペアリング済みノードがバックグラウンドウェイク中に生存していたことを、接続済みとしてマークせずに記録できます。
ノードは `event: "node.presence.alive"` を指定して `node.event` を呼び出し、ペアリング済みノードがバックグラウンドウェイク中に生存していたことを、接続済みにせずに記録できます。
```json
{
@ -246,9 +245,9 @@ Gateway はこれらを**要求**として扱い、サーバー側の許可リ
}
```
`trigger` は閉じた列挙型です: `background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual`、または `connect`。未知のトリガー文字列は、永続化前に gateway によって `background` に正規化されます。このイベントは認証済みノードデバイスセッションでのみ永続化されます。デバイスなし、または未ペアリングのセッションは `handled: false` を返します。
`trigger` は閉じた enum です: `background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual`、または `connect`。未知のトリガー文字列は、永続化の前に Gateway によって `background` に正規化されます。このイベントは、認証済みのノードデバイスセッションに対してのみ永続的です。デバイスなしまたは未ペアリングのセッションは `handled: false` を返します。
成功した gateway は構造化された結果を返します。
成功した Gateway は構造化された結果を返します。
```json
{
@ -259,212 +258,215 @@ Gateway はこれらを**要求**として扱い、サーバー側の許可リ
}
```
古い gateway は `node.event` に対してまだ `{ "ok": true }` を返す場合があります。クライアントはそれを、永続的なプレゼンス永続化ではなく、承認済み RPC として扱う必要があります。
古い Gateway は `node.event` に対して引き続き `{ "ok": true }` を返すことがあります。クライアントはこれを、永続的なプレゼンス保存ではなく、確認済みの RPC として扱う必要があります。
## ブロードキャストイベントのスコープ設定
サーバーからプッシュされる WebSocket ブロードキャストイベントはスコープでゲートされるため、ペアリングスコープまたはノード専用セッションがセッション内容を受動的に受け取ることはありません。
サーバーからプッシュされる WebSocket ブロードキャストイベントはスコープでゲートされるため、ペアリングスコープ付きセッションやノード専用セッションがセッション内容を受動的に受信することはありません。
- **チャット、エージェント、ツール結果フレーム**（ストリーミングされた `agent` イベントとツール呼び出し結果を含む）には、少なくとも `operator.read` が必要です。`operator.read` を持たないセッションは、これらのフレームを完全にスキップします。
- **Plugin 定義の `plugin.*` ブロードキャスト**は、Plugin が登録した方法に応じて `operator.write` または `operator.admin` にゲートされます。
- **ステータスおよびトランスポートイベント**（`heartbeat`、`presence`、`tick`、接続/切断ライフサイクルなど）は、すべての認証済みセッションがトランスポートの健全性を観測できるように、制限なしのままです。
- **未知のブロードキャストイベントファミリー**は、登録済みハンドラーが明示的に緩和しない限り、デフォルトでスコープゲートされます（フェイルクローズ）。
- **チャット、エージェント、ツール結果フレーム**（ストリーミングされた `agent` イベントとツール呼び出し結果を含む）には少なくとも `operator.read` が必要です。`operator.read` を持たないセッションは、これらのフレームを完全にスキップします。
- **Plugin 定義の `plugin.*` ブロードキャスト** は、Plugin が登録した方法に応じて `operator.write` または `operator.admin` にゲートされます。
- **ステータスおよびトランスポートイベント**（`heartbeat`、`presence`、`tick`、接続/切断ライフサイクルなど）は、すべての認証済みセッションでトランスポートの健全性を観測可能に保つため、制限されません。
- **未知のブロードキャストイベントファミリー** は、登録済みハンドラーが明示的に緩和しない限り、デフォルトでスコープゲートされます（フェイルクローズ）。
各クライアント接続はクライアントごとの独自のシーケンス番号を保持するため、異なるクライアントがイベントストリームの異なるスコープフィルター済みサブセットを見る場合でも、ブロードキャストはそのソケット上で単調な順序を維持します。
各クライアント接続は独自のクライアントごとのシーケンス番号を保持するため、異なるクライアントがイベントストリームの異なるスコープフィルター済みサブセットを見る場合でも、ブロードキャストはそのソケット上で単調な順序を維持します。
## 一般的な RPC メソッドファミリー
公開 WS サーフェスは、上記のハンドシェイク/認証例よりも広範です。これは生成されたダンプではありません。`hello-ok.features.methods` は、`src/gateway/server-methods-list.ts` と読み込まれた Plugin/チャネルメソッドエクスポートから構築される保守的な検出リストです。`src/gateway/server-methods/*.ts` の完全な列挙ではなく、機能検出として扱ってください。
公開 WS サーフェスは、上記のハンドシェイク/認証例よりも広範です。これは生成されたダンプではありません。`hello-ok.features.methods` は、`src/gateway/server-methods-list.ts` と読み込まれた Plugin/チャンネルメソッドエクスポートから構築される保守的な検出リストです。これは機能検出として扱い、`src/gateway/server-methods/*.ts` の完全な列挙とは見なさないでください。
<AccordionGroup>
<Accordion title="システムと ID">
- `health` はキャッシュ済み、または新たにプローブされた gateway ヘルススナップショットを返します。
- `diagnostics.stability` は、最近の境界付き診断安定性レコーダーを返します。イベント名、件数、バイトサイズ、メモリ読み取り値、キュー/セッション状態、チャネル/Plugin 名、セッション ID などの運用メタデータを保持します。チャットテキスト、webhook 本文、ツール出力、生のリクエスト本文またはレスポンス本文、トークン、Cookie、秘密値は保持しません。operator read スコープが必要です。
- `status` は `/status` スタイルの gateway サマリーを返します。機密フィールドは admin スコープの operator クライアントにのみ含まれます。
- `gateway.identity.get` は、リレーおよびペアリングフローで使用される gateway デバイス ID を返します。
- `health` は、キャッシュ済みまたは新たにプローブされた Gateway ヘルススナップショットを返します。
- `diagnostics.stability` は、最近の制限付き診断安定性レコーダーを返します。イベント名、カウント、バイトサイズ、メモリ読み取り値、キュー/セッション状態、チャンネル/Plugin 名、セッション ID などの運用メタデータを保持します。チャットテキスト、Webhook 本文、ツール出力、生のリクエストまたはレスポンス本文、トークン、Cookie、シークレット値は保持しません。operator read スコープが必要です。
- `status` は `/status` 形式の Gateway サマリーを返します。機微なフィールドは、管理者スコープ付きの operator クライアントにのみ含まれます。
- `gateway.identity.get` は、リレーおよびペアリングフローで使用される Gateway デバイス ID を返します。
- `system-presence` は、接続中の operator/node デバイスの現在のプレゼンススナップショットを返します。
- `system-event` はシステムイベントを追加し、プレゼンスコンテキストを更新/ブロードキャストできます。
- `last-heartbeat` は最新の永続化された Heartbeat イベントを返します。
- `set-heartbeats` は gateway 上の Heartbeat 処理を切り替えます。
- `last-heartbeat` は、最新の永続化された Heartbeat イベントを返します。
- `set-heartbeats` は、Gateway 上の Heartbeat 処理を切り替えます。
</Accordion>
<Accordion title="モデルと使用状況">
- `models.list` は、ランタイムで許可されたモデルカタログを返します。ピッカー向けサイズの構成済みモデル（まず `agents.defaults.models`、次に `models.providers.*.models`）には `{ "view": "configured" }` を渡し、完全なカタログには `{ "view": "all" }` を渡します。
- `usage.status` は、プロバイダーの使用状況ウィンドウ/残りクォータの概要を返します。
- `usage.cost` は、日付範囲に対する集計済みコスト使用状況の概要を返します。
- `doctor.memory.status` は、アクティブなデフォルトエージェントワークスペースのベクトルメモリ / キャッシュ済み埋め込みの準備状態を返します。呼び出し元がライブ埋め込みプロバイダーへの ping を明示的に要求する場合のみ、`{ "probe": true }` または `{ "deep": true }` を渡します。
- `doctor.memory.remHarness` は、リモート制御プレーンのクライアント向けに、範囲制限された読み取り専用の REM ハーネスプレビューを返します。ワークスペースパス、メモリスニペット、レンダリング済みの根拠付きマークダウン、深いプロモーション候補を含むことがあるため、呼び出し元には `operator.read` が必要です。
- `sessions.usage` は、セッションごとの使用状況の概要を返します。
- `sessions.usage.timeseries` は、1つのセッションの時系列使用状況を返します。
- `sessions.usage.logs` は、1つのセッションの使用状況ログエントリを返します。
<Accordion title="モデルと使用量">
- `models.list` は、ランタイムで許可されているモデルカタログを返します。ピッカーに適したサイズの設定済みモデル（まず `agents.defaults.models`、次に `models.providers.*.models`）には `{ "view": "configured" }` を渡し、完全なカタログには `{ "view": "all" }` を渡します。
- `usage.status` は、プロバイダーの使用量ウィンドウと残りクォータの要約を返します。
- `usage.cost` は、日付範囲に対する集計済みコスト使用量の要約を返します。
- `doctor.memory.status` は、アクティブなデフォルトエージェントワークスペースのベクトルメモリ / キャッシュ済み埋め込みの準備状況を返します。呼び出し元がライブ埋め込みプロバイダーへの ping を明示的に求める場合にのみ、`{ "probe": true }` または `{ "deep": true }` を渡します。
- `doctor.memory.remHarness` は、リモート制御プレーンのクライアント向けに、範囲が制限された読み取り専用の REM ハーネスプレビューを返します。ワークスペースパス、メモリスニペット、レンダリング済みの根拠付き Markdown、深い昇格候補を含められるため、呼び出し元には `operator.read` が必要です。
- `sessions.usage` は、セッションごとの使用量要約を返します。
- `sessions.usage.timeseries` は、1 つのセッションの時系列使用量を返します。
- `sessions.usage.logs` は、1 つのセッションの使用量ログエントリを返します。
</Accordion>
<Accordion title="チャネルとログインヘルパー">
- `channels.status` は、組み込み + バンドル済みチャネル/Plugin のステータス概要を返します。
- `channels.logout` は、チャネルがログアウトをサポートしている場合に、特定のチャネル/アカウントをログアウトします。
- `web.login.start` は、現在の QR 対応 Web チャネルプロバイダーの QR/Web ログインフローを開始します。
- `web.login.wait` は、その QR/Web ログインフローの完了を待機し、成功時にチャネルを開始します。
- `push.test` は、登録済み iOS ノードにテスト APNs プッシュを送信します。
- `channels.status` は、組み込み + バンドル済みチャネル / plugin のステータス要約を返します。
- `channels.logout` は、チャネルがログアウトをサポートしている場合に、特定のチャネル / アカウントからログアウトします。
- `web.login.start` は、現在の QR 対応 Web チャネルプロバイダーに対する QR / Web ログインフローを開始します。
- `web.login.wait` は、その QR / Web ログインフローの完了を待機し、成功時にチャネルを開始します。
- `push.test` は、登録済み iOS ノードにテスト用 APNs プッシュを送信します。
- `voicewake.get` は、保存済みのウェイクワードトリガーを返します。
- `voicewake.set` は、ウェイクワードトリガーを更新し、変更をブロードキャストします。
</Accordion>
<Accordion title="メッセージングとログ">
- `send` は、チャットランナー外でチャネル/アカウント/スレッドを対象に送信するための、直接アウトバウンド配信 RPC です。
- `logs.tail` は、カーソル/リミットと最大バイト数の制御を備えた、構成済み Gateway ファイルログの末尾を返します。
- `send` は、チャットランナーの外部でチャネル / アカウント / スレッドを対象に送信するための、直接アウトバウンド配信 RPC です。
- `logs.tail` は、カーソル / 制限と最大バイト数の制御付きで、設定済み Gateway ファイルログの末尾を返します。
</Accordion>
<Accordion title="Talk と TTS">
<Accordion title="トークと TTS">
- `talk.config` は、有効な Talk 設定ペイロードを返します。`includeSecrets` には `operator.talk.secrets`（または `operator.admin`）が必要です。
- `talk.mode` は、WebChat/Control UI クライアント向けに現在の Talk モード状態を設定/ブロードキャストします。
- `talk.mode` は、WebChat / Control UI クライアント向けに現在の Talk モード状態を設定 / ブロードキャストします。
- `talk.speak` は、アクティブな Talk 音声プロバイダーを通じて音声を合成します。
- `tts.status` は、TTS の有効状態、アクティブなプロバイダー、フォールバックプロバイダー、プロバイダー設定状態を返します。
- `tts.providers` は、表示可能な TTS プロバイダーインベントリを返します。
- `tts.status` は、TTS の有効状態、アクティブプロバイダー、フォールバックプロバイダー、プロバイダー設定状態を返します。
- `tts.providers` は、表示可能な TTS プロバイダーのインベントリを返します。
- `tts.enable` と `tts.disable` は、TTS 設定状態を切り替えます。
- `tts.setProvider` は、優先 TTS プロバイダーを更新します。
- `tts.convert` は、1回限りのテキスト読み上げ変換を実行します。
- `tts.convert` は、単発のテキスト読み上げ変換を実行します。
</Accordion>
<Accordion title="シークレット、設定、更新、ウィザード">
- `secrets.reload` は、アクティブな SecretRefs を再解決し、完全に成功した場合のみランタイムのシークレット状態を差し替えます。
- `secrets.resolve` は、特定のコマンド/ターゲットセットに対するコマンド対象のシークレット割り当てを解決します。
- `secrets.reload` は、アクティブな SecretRefs を再解決し、完全に成功した場合にのみランタイムのシークレット状態を差し替えます。
- `secrets.resolve` は、特定のコマンド / ターゲットセットに対するコマンド対象のシークレット割り当てを解決します。
- `config.get` は、現在の設定スナップショットとハッシュを返します。
- `config.set` は、検証済みの設定ペイロードを書き込みます。
- `config.patch` は、部分的な設定更新をマージします。
- `config.apply` は、完全な設定ペイロードを検証して置き換えます。
- `config.schema` は、Control UI と CLI ツールが使用するライブ設定スキーマペイロードを返します。スキーマ、`uiHints`、バージョン、生成メタデータに加えて、ランタイムが読み込める場合は Plugin + チャネルのスキーマメタデータも含みます。このスキーマには、UI で使用される同じラベルとヘルプテキストから派生したフィールドの `title` / `description` メタデータが含まれます。対応するフィールドドキュメントが存在する場合は、ネストされたオブジェクト、ワイルドカード、配列項目、`anyOf` / `oneOf` / `allOf` の合成ブランチも含まれます。
- `config.schema.lookup` は、1つの設定パスに対するパススコープのルックアップペイロードを返します。正規化されたパス、浅いスキーマノード、一致したヒント + `hintPath`、UI/CLI のドリルダウン向けの直接の子要素概要を含みます。ルックアップスキーマノードは、ユーザー向けドキュメントと共通の検証フィールド（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数値/文字列/配列/オブジェクトの境界、および `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` などのフラグ）を保持します。子要素概要は、`key`、正規化された `path`、`type`、`required`、`hasChildren`、および一致した `hint` / `hintPath` を公開します。
- `update.run` は、Gateway 更新フローを実行し、更新自体が成功した場合のみ再起動をスケジュールします。
- `update.status` は、利用可能な場合は再起動後に稼働中のバージョンを含め、最新のキャッシュ済み更新再起動センチネルを返します。
- `config.schema` は、Control UI と CLI ツールで使用されるライブ設定スキーマペイロードを返します。これには、スキーマ、`uiHints`、バージョン、生成メタデータが含まれ、ランタイムが読み込める場合は plugin + チャネルスキーマメタデータも含まれます。スキーマには、UI で使用される同じラベルとヘルプテキストから派生したフィールド `title` / `description` メタデータが含まれ、対応するフィールドドキュメントが存在する場合は、ネストされたオブジェクト、ワイルドカード、配列項目、`anyOf` / `oneOf` / `allOf` の合成分岐も含まれます。
- `config.schema.lookup` は、1 つの設定パスに対してパススコープの検索ペイロードを返します。正規化されたパス、浅いスキーマノード、一致したヒント + `hintPath`、UI / CLI の掘り下げ用の直下の子要約が含まれます。検索スキーマノードは、ユーザー向けドキュメントと一般的な検証フィールド（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数値 / 文字列 / 配列 / オブジェクトの境界、`additionalProperties`、`deprecated`、`readOnly`、`writeOnly` などのフラグ）を保持します。子要約は、`key`、正規化済みの `path`、`type`、`required`、`hasChildren` に加え、一致した `hint` / `hintPath` を公開します。
- `update.run` は Gateway 更新フローを実行し、更新自体が成功した場合にのみ再起動をスケジュールします。
- `update.status` は、利用可能な場合は再起動後に実行中のバージョンを含め、最新のキャッシュ済み更新再起動センチネルを返します。
- `wizard.start`、`wizard.next`、`wizard.status`、`wizard.cancel` は、オンボーディングウィザードを WS RPC 経由で公開します。
</Accordion>
<Accordion title="エージェントとワークスペースのヘルパー">
- `agents.list` は、有効なモデルとランタイムメタデータを含む、構成済みエージェントエントリを返します。
- `agents.create`、`agents.update`、`agents.delete` は、エージェントレコードとワークスペースの配線を管理します。
- `agents.list` は、有効なモデルとランタイムメタデータを含む、設定済みエージェントエントリを返します。
- `agents.create`、`agents.update`、`agents.delete` は、エージェントレコードとワークスペースの結線を管理します。
- `agents.files.list`、`agents.files.get`、`agents.files.set` は、エージェント向けに公開されるブートストラップワークスペースファイルを管理します。
- `artifacts.list`、`artifacts.get`、`artifacts.download` は、明示的な `sessionKey`、`runId`、または `taskId` スコープに対して、トランスクリプト由来のアーティファクト要約とダウンロードを公開します。実行クエリとタスククエリは、所有するセッションをサーバー側で解決し、一致する来歴を持つトランスクリプトメディアのみを返します。安全でない URL ソースやローカル URL ソースは、サーバー側で取得せず、サポートされていないダウンロードを返します。
- `agent.identity.get` は、エージェントまたはセッションに対する有効なアシスタント ID を返します。
- `agent.wait` は、実行の終了を待機し、利用可能な場合は終了時のスナップショットを返します。
- `agent.wait` は、実行の完了を待機し、利用可能な場合は終端スナップショットを返します。
</Accordion>
<Accordion title="セッション制御">
- `sessions.list` は、現在のセッションインデックスを返します。エージェントランタイムバックエンドが構成されている場合は、各行の `agentRuntime` メタデータも含みます。
- `sessions.list` は、エージェントランタイムバックエンドが設定されている場合、行ごとの `agentRuntime` メタデータを含む現在のセッションインデックスを返します。
- `sessions.subscribe` と `sessions.unsubscribe` は、現在の WS クライアントに対するセッション変更イベント購読を切り替えます。
- `sessions.messages.subscribe` と `sessions.messages.unsubscribe` は、1つのセッションに対するトランスクリプト/メッセージイベント購読を切り替えます。
- `sessions.preview` は、特定のセッションキーに対する範囲制限されたトランスクリプトプレビューを返します。
- `sessions.messages.subscribe` と `sessions.messages.unsubscribe` は、1 つのセッションに対するトランスクリプト / メッセージイベント購読を切り替えます。
- `sessions.preview` は、特定のセッションキーに対して範囲が制限されたトランスクリプトプレビューを返します。
- `sessions.resolve` は、セッションターゲットを解決または正規化します。
- `sessions.create` は、新しいセッションエントリを作成します。
- `sessions.send` は、既存のセッションにメッセージを送信します。
- `sessions.steer` は、アクティブなセッション向けの中断して誘導するバリアントです。
- `sessions.abort` は、セッションのアクティブな作業を中止します。呼び出し元は `key` と任意の `runId` を渡すか、Gateway がセッションへ解決できるアクティブな実行については `runId` のみを渡すことができます。
- `sessions.patch` は、セッションのメタデータ/オーバーライドを更新し、解決済みの正規モデルと有効な `agentRuntime` を報告します。
- `sessions.reset`、`sessions.delete`、`sessions.compact` は、セッションのメンテナンスを実行します。
- `sessions.get` は、保存済みの完全なセッション行を返します。
- チャット実行では引き続き `chat.history`、`chat.send`、`chat.abort`、`chat.inject` を使用します。`chat.history` は UI クライアント向けに表示正規化されます。インラインディレクティブタグは表示テキストから取り除かれ、プレーンテキストのツール呼び出し XML ペイロード（`<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`、切り詰められたツール呼び出しブロックを含む）と漏れた ASCII/全角のモデル制御トークンは取り除かれ、正確に `NO_REPLY` / `no_reply` であるような純粋なサイレントトークンのアシスタント行は省略され、過大な行はプレースホルダーで置き換えられることがあります。
- `sessions.steer` は、アクティブなセッション向けの割り込みおよび誘導バリアントです。
- `sessions.abort` は、セッションのアクティブな作業を中止します。呼び出し元は `key` と任意の `runId` を渡すか、Gateway がセッションへ解決できるアクティブな実行については `runId` のみを渡せます。
- `sessions.patch` は、セッションのメタデータ / オーバーライドを更新し、解決済みの正規モデルと有効な `agentRuntime` を報告します。
- `sessions.reset`、`sessions.delete`、`sessions.compact` は、セッションメンテナンスを実行します。
- `sessions.get` は、保存済みセッション行全体を返します。
- チャット実行では引き続き `chat.history`、`chat.send`、`chat.abort`、`chat.inject` を使用します。`chat.history` は UI クライアント向けに表示正規化されています。インラインディレクティブタグは表示テキストから取り除かれ、プレーンテキストのツール呼び出し XML ペイロード（`<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`、切り詰められたツール呼び出しブロックを含む）と漏出した ASCII / 全角のモデル制御トークンは取り除かれ、正確に `NO_REPLY` / `no_reply` のような純粋なサイレントトークンのアシスタント行は省略され、過大な行はプレースホルダーに置き換えられる場合があります。
</Accordion>
<Accordion title="デバイスペアリングとデバイストークン">
- `device.pair.list` は、保留中および承認済みのペアリング済みデバイスを返します。
- `device.pair.approve`、`device.pair.reject`、`device.pair.remove` は、デバイスペアリングレコードを管理します。
- `device.token.rotate` は、承認済みロールと呼び出し元のスコープ境界内で、ペアリング済みデバイストークンをローテーションします。
- `device.token.revoke` は、承認済みロールと呼び出し元のスコープ境界内で、ペアリング済みデバイストークンを取り消します。
- `device.token.rotate` は、承認済みロールと呼び出し元スコープの境界内で、ペアリング済みデバイストークンをローテーションします。
- `device.token.revoke` は、承認済みロールと呼び出し元スコープの境界内で、ペアリング済みデバイストークンを失効させます。
</Accordion>
<Accordion title="ノードペアリング、呼び出し、保留中の作業">
- `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.remove`、`node.pair.verify` は、ノードペアリングとブートストラップ検証を扱います。
- `node.list` と `node.describe` は、既知/接続済みノードの状態を返します。
- `node.list` と `node.describe` は、既知 / 接続済みノードの状態を返します。
- `node.rename` は、ペアリング済みノードのラベルを更新します。
- `node.invoke` は、接続済みノードにコマンドを転送します。
- `node.invoke.result` は、呼び出しリクエストの結果を返します。
- `node.event` は、ノード起点のイベントを Gateway に戻します。
- `node.event` は、ノード発信のイベントを Gateway に戻します。
- `node.canvas.capability.refresh` は、スコープ付きキャンバス機能トークンを更新します。
- `node.pending.pull` と `node.pending.ack` は、接続済みノードのキュー API です。
- `node.pending.enqueue` と `node.pending.drain` は、オフライン/切断済みノード向けの永続的な保留中作業を管理します。
- `node.pending.enqueue` と `node.pending.drain` は、オフライン / 切断済みノード向けの永続的な保留作業を管理します。
</Accordion>
<Accordion title="承認ファミリー">
- `exec.approval.request`、`exec.approval.get`、`exec.approval.list`、`exec.approval.resolve` は、1回限りの exec 承認リクエストと、保留中の承認の検索/再生を扱います。
- `exec.approval.waitDecision` は、1つの保留中 exec 承認を待機し、最終決定（またはタイムアウト時は `null`）を返します。
- `exec.approvals.get` と `exec.approvals.set` は、Gateway exec 承認ポリシースナップショットを管理します。
- `exec.approvals.node.get` と `exec.approvals.node.set` は、ノードリレーコマンドを介してノードローカル exec 承認ポリシーを管理します。
- `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision`、`plugin.approval.resolve` は、Plugin 定義の承認フローを扱います。
- `exec.approval.request`、`exec.approval.get`、`exec.approval.list`、`exec.approval.resolve` は、単発の exec 承認リクエストと、保留中の承認検索 / 再生を扱います。
- `exec.approval.waitDecision` は、保留中の exec 承認を 1 件待機し、最終判断（またはタイムアウト時は `null`）を返します。
- `exec.approvals.get` と `exec.approvals.set` は、Gateway の exec 承認ポリシースナップショットを管理します。
- `exec.approvals.node.get` と `exec.approvals.node.set` は、ノードリレーコマンド経由でノードローカルの exec 承認ポリシーを管理します。
- `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision`、`plugin.approval.resolve` は、plugin 定義の承認フローを扱います。
</Accordion>
<Accordion title="自動化、Skills、ツール">
- 自動化: `wake` は、即時または次回 Heartbeat のウェイクテキスト挿入をスケジュールします。`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` は、スケジュール済み作業を管理します。
- 自動化: `wake` は即時または次回 Heartbeat のウェイクテキスト注入をスケジュールします。`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` はスケジュール済み作業を管理します。
- Skills とツール: `commands.list`、`skills.*`、`tools.catalog`、`tools.effective`。
</Accordion>
</AccordionGroup>
### 共通イベントファミリー
### 一般的なイベントファミリー
- `chat`: `chat.inject` などの UI チャット更新、およびその他のトランスクリプト専用チャットイベント。
- `session.message` と `session.tool`: 購読済みセッションのトランスクリプト/イベントストリーム更新。
- `chat`: `chat.inject` などの UI チャット更新、およびその他のトランスクリプト専用チャット
イベント。
- `session.message` と `session.tool`: 購読済みセッションに対するトランスクリプト / イベントストリーム更新。
- `sessions.changed`: セッションインデックスまたはメタデータが変更されました。
- `presence`: システムプレゼンススナップショット更新。
- `presence`: システムプレゼンスのスナップショット更新。
- `tick`: 定期的な keepalive / 生存確認イベント。
- `health`: Gateway ヘルススナップショット更新。
- `heartbeat`: Heartbeat イベントストリーム更新。
- `cron`: Cron 実行/ジョブ変更イベント。
- `cron`: Cron 実行 / ジョブ変更イベント。
- `shutdown`: Gateway シャットダウン通知。
- `node.pair.requested` / `node.pair.resolved`: ノードペアリングのライフサイクル。
- `node.invoke.request`: ノード呼び出しリクエストのブロードキャスト。
- `device.pair.requested` / `device.pair.resolved`: ペアリング済みデバイスのライフサイクル。
- `voicewake.changed`: ウェイクワードトリガー設定が変更されました。
- `exec.approval.requested` / `exec.approval.resolved`: exec 承認のライフサイクル。
- `plugin.approval.requested` / `plugin.approval.resolved`: Plugin 承認のライフサイクル。
- `exec.approval.requested` / `exec.approval.resolved`: exec 承認
ライフサイクル。
- `plugin.approval.requested` / `plugin.approval.resolved`: plugin 承認
ライフサイクル。
### ノードヘルパーメソッド
- ノードは、自動許可チェック向けに現在の Skills 実行可能ファイル一覧を取得するため、`skills.bins` を呼び出すことができます。
- ノードは、自動許可チェック用の現在のスキル実行ファイル一覧を取得するために、`skills.bins` を呼び出せます。
### オペレーターヘルパーメソッド
- オペレーターは `commands.list`（`operator.read`）を呼び出して、エージェントのランタイム
- オペレーターは `commands.list` (`operator.read`) を呼び出して、エージェントのランタイム
コマンドインベントリを取得できます。
- `agentId` は任意です。デフォルトのエージェントワークスペースを読み取るには省略します。
- `scope` は、主 `name` が対象にするサーフェスを制御します。
- `text` は、先頭の `/` を除いた主テキストコマンドトークンを返します
- `scope` は、主要な `name` がどのサーフェスを対象にするかを制御します。
- `text` は、先頭の `/` を含まない主要なテキストコマンドトークンを返します
- `native` とデフォルトの `both` パスは、利用可能な場合にプロバイダー対応のネイティブ名を返します
- `textAliases` は `/model` や `/m` などの正確なスラッシュエイリアスを保持します。
- `nativeName` は、存在する場合にプロバイダー対応のネイティブコマンド名を保持します。
- `provider` は任意で、ネイティブ命名とネイティブ Plugin
コマンドの利用可否にのみ影響します。
コマンドの可用性にのみ影響します。
- `includeArgs=false` は、シリアライズされた引数メタデータをレスポンスから省略します。
- オペレーターは `tools.catalog`（`operator.read`）を呼び出して、エージェントのランタイムツールカタログを取得できます。レスポンスには、グループ化されたツールと来歴メタデータが含まれます。
- オペレーターは `tools.catalog` (`operator.read`) を呼び出して、エージェントのランタイムツールカタログを取得できます。レスポンスには、グループ化されたツールと来歴メタデータが含まれます。
- `source`: `core` または `plugin`
- `pluginId`: `source="plugin"` の場合の Plugin 所有者
- `optional`: Plugin ツールが任意かどうか
- オペレーターは `tools.effective`（`operator.read`）を呼び出して、セッションでランタイム上有効なツール
- オペレーターは `tools.effective` (`operator.read`) を呼び出して、セッションでランタイム上有効なツール
インベントリを取得できます。
- `sessionKey` は必須です。
- Gateway は、呼び出し元から提供された認証または配信コンテキストを受け入れる代わりに、セッションから信頼済みランタイムコンテキストをサーバー側で導出します。
- Gateway は、呼び出し元が指定した認証または配信コンテキストを受け入れるのではなく、セッションサーバー側から信頼済みランタイムコンテキストを導出します。
- レスポンスはセッションスコープであり、コア、Plugin、チャネルツールを含め、アクティブな会話が現時点で使用できるものを反映します。
- オペレーターは `skills.status`（`operator.read`）を呼び出して、エージェントで表示可能な
- オペレーターは `skills.status` (`operator.read`) を呼び出して、エージェントに表示される
スキルインベントリを取得できます。
- `agentId` は任意です。デフォルトのエージェントワークスペースを読み取るには省略します。
- レスポンスには、適格性、不足している要件、設定チェック、および
生のシークレット値を公開しないサニタイズ済みインストールオプションが含まれます。
- オペレーターは ClawHub の検出メタデータ用に `skills.search` と `skills.detail`（`operator.read`）を呼び出せます。
- オペレーターは `skills.install`（`operator.admin`）を 2 つのモードで呼び出せます。
- ClawHub モード: `{ source: "clawhub", slug, version?, force? }` は、
デフォルトのエージェントワークスペースの `skills/` ディレクトリにスキルフォルダーをインストールします。
- オペレーターは ClawHub 探索メタデータのために `skills.search` と `skills.detail` (`operator.read`) を呼び出せます。
- オペレーターは `skills.install` (`operator.admin`) を 2 つのモードで呼び出せます。
- ClawHub モード: `{ source: "clawhub", slug, version?, force? }` は、スキルフォルダーをデフォルトエージェントワークスペースの `skills/` ディレクトリにインストールします。
- Gateway インストーラーモード: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
は、Gateway ホスト上で宣言済みの `metadata.openclaw.install` アクションを実行します。
- オペレーターは `skills.update`（`operator.admin`）を 2 つのモードで呼び出せます。
- ClawHub モードは、デフォルトのエージェントワークスペース内で、追跡対象の 1 つの slug または追跡対象のすべての ClawHub インストールを更新します。
- オペレーターは `skills.update` (`operator.admin`) を 2 つのモードで呼び出せます。
- ClawHub モードは、デフォルトエージェントワークスペース内の追跡対象 slug 1 件、または追跡対象のすべての ClawHub インストールを更新します。
- 設定モードは、`enabled`、`apiKey`、`env` などの `skills.entries.<skillKey>` 値にパッチを適用します。
### `models.list` ビュー
@ -472,142 +474,136 @@ Gateway はこれらを**要求**として扱い、サーバー側の許可リ
`models.list` は任意の `view` パラメーターを受け付けます。
- 省略または `"default"`: 現在のランタイム動作です。`agents.defaults.models` が設定されている場合、レスポンスは許可されたカタログになります。それ以外の場合、レスポンスは完全な Gateway カタログになります。
- `"configured"`: ピッカー向けサイズの動作です。`agents.defaults.models` が設定されている場合は、引き続きそれが優先されます。それ以外の場合、レスポンスは明示的な `models.providers.*.models` エントリを使用し、設定済みモデル行が存在しない場合にのみ完全なカタログへフォールバックします。
- `"all"`: 完全な Gateway カタログで、`agents.defaults.models` をバイパスします。通常のモデルピッカーではなく、診断および検出 UI に使用してください。
- `"configured"`: ピッカー向けのサイズの動作です。`agents.defaults.models` が設定されている場合は、引き続きそれが優先されます。それ以外の場合、レスポンスは明示的な `models.providers.*.models` エントリを使用し、設定済みモデル行が存在しない場合にのみ完全なカタログへフォールバックします。
- `"all"`: 完全な Gateway カタログで、`agents.defaults.models` をバイパスします。通常のモデルピッカーではなく、診断と探索 UI に使用します。
## 実行承認
## Exec 承認
- exec リクエストが承認を必要とする場合、Gateway は `exec.approval.requested` をブロードキャストします。
- オペレータークライアントは `exec.approval.resolve`（`operator.approvals` スコープが必要）を呼び出して解決します。
- exec リクエストに承認が必要な場合、Gateway は `exec.approval.requested` をブロードキャストします。
- オペレータークライアントは `exec.approval.resolve` を呼び出して解決します（`operator.approvals` スコープが必要）。
- `host=node` の場合、`exec.approval.request` には `systemRunPlan`（正規の `argv`/`cwd`/`rawCommand`/セッションメタデータ）を含める必要があります。`systemRunPlan` がないリクエストは拒否されます。
- 承認後、転送された `node.invoke system.run` 呼び出しは、その正規の
`systemRunPlan` を信頼できるコマンド/cwd/セッションコンテキストとして再利用します。
- 呼び出し元が prepare と最終的な承認済み `system.run` 転送の間に `command`、`rawCommand`、`cwd`、`agentId`、または
`sessionKey` を変更した場合、Gateway は変更されたペイロードを信頼せず、実行を拒否します。
- 承認後、転送される `node.invoke system.run` 呼び出しは、その正規の
`systemRunPlan` を権威あるコマンド/cwd/セッションコンテキストとして再利用します。
- 呼び出し元が準備から最終承認済み `system.run` 転送までの間に `command`、`rawCommand`、`cwd`、`agentId`、または
`sessionKey` を変更した場合、Gateway は変更後のペイロードを信頼せず、その実行を拒否します。
## エージェント配信フォールバック
- `agent` リクエストには、アウトバウンド配信を要求するために `deliver=true` を含めることができます。
- `bestEffortDeliver=false` は厳格な動作を維持します。解決できない配信先または内部専用の配信先は `INVALID_REQUEST` を返します。
- `bestEffortDeliver=true` は、外部へ配信可能なルートを解決できない場合（たとえば内部/webchat セッションや曖昧なマルチチャネル設定）、セッションのみの実行へのフォールバックを許可します。
- `bestEffortDeliver=false` は厳格な動作を維持します。解決できない、または内部専用の配信先は `INVALID_REQUEST` を返します。
- `bestEffortDeliver=true` は、外部に配信可能なルートを解決できない場合（例: 内部/webchat セッションや曖昧な複数チャネル設定）、セッションのみの実行へのフォールバックを許可します。
## バージョニング
- `PROTOCOL_VERSION` は `src/gateway/protocol/schema/protocol-schemas.ts` にあります。
- クライアントは `minProtocol` + `maxProtocol` を送信し、サーバーは不一致を拒否します。
- スキーマ + モデルは TypeBox 定義から生成されます。
- スキーマとモデルは TypeBox 定義から生成されます。
- `pnpm protocol:gen`
- `pnpm protocol:gen:swift`
- `pnpm protocol:check`
### クライアント定数
`src/gateway/client.ts` のリファレンスクライアントは、これらのデフォルトを使用します。値は
protocol v3 全体で安定しており、サードパーティクライアントの想定ベースラインです。
`src/gateway/client.ts` の参照クライアントはこれらのデフォルトを使用します。値は
プロトコル v3 全体で安定しており、サードパーティクライアントに期待される基準です。
| 定数 | デフォルト | ソース |
| ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
| リクエストタイムアウト（RPC ごと） | `30_000` ms | `src/gateway/client.ts`（`requestTimeoutMs`） |
| 事前認証 / 接続チャレンジタイムアウト | `15_000` ms | `src/gateway/handshake-timeouts.ts`（config/env でサーバー/クライアントの組み合わせ予算を引き上げ可能） |
| 初回再接続バックオフ | `1_000` ms | `src/gateway/client.ts`（`backoffMs`） |
| 最大再接続バックオフ | `30_000` ms | `src/gateway/client.ts`（`scheduleReconnect`） |
| デバイストークン close 後の高速リトライ上限 | `250` ms | `src/gateway/client.ts` |
| リクエストタイムアウト（RPC ごと） | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
| 事前認証 / 接続チャレンジタイムアウト | `15_000` ms | `src/gateway/handshake-timeouts.ts`（config/env で対応するサーバー/クライアントの予算を増やせます） |
| 初期再接続バックオフ | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
| 最大再接続バックオフ | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
| デバイストークンクローズ後の高速リトライ上限 | `250` ms | `src/gateway/client.ts` |
| `terminate()` 前の強制停止猶予 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
| `stopAndWait()` デフォルトタイムアウト | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
| `stopAndWait()` デフォルトタイムアウト | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
| デフォルト tick 間隔（`hello-ok` 前） | `30_000` ms | `src/gateway/client.ts` |
| tick タイムアウト close | 無通信が `tickIntervalMs * 2` を超えると code `4000` | `src/gateway/client.ts` |
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024`（25 MB） | `src/gateway/server-constants.ts` |
| tick タイムアウトクローズ | 無音が `tickIntervalMs * 2` を超えた場合は code `4000` | `src/gateway/client.ts` |
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
サーバーは有効な `policy.tickIntervalMs`、`policy.maxPayload`、
`policy.maxBufferedBytes` を `hello-ok` で通知します。クライアントは
ハンドシェイク前のデフォルトではなく、それらの値に従う必要があります。
サーバーは実効 `policy.tickIntervalMs`、`policy.maxPayload`、および `policy.maxBufferedBytes` を `hello-ok` で通知します。クライアントは、ハンドシェイク前のデフォルトではなく、これらの値に従うべきです。
## 認証
- 共有シークレット Gateway 認証は、設定済みの認証モードに応じて `connect.params.auth.token` または
- 共有シークレット Gateway 認証は、設定済み認証モードに応じて `connect.params.auth.token` または
`connect.params.auth.password` を使用します。
- Tailscale Serve
（`gateway.auth.allowTailscale: true`）や非ループバックの
`gateway.auth.mode: "trusted-proxy"` など、アイデンティティを持つモードは、
`connect.params.auth.*` ではなくリクエストヘッダーから接続認証チェックを満たします。
- プライベート入口の `gateway.auth.mode: "none"` は、共有シークレット接続認証を
完全にスキップします。このモードを公開/信頼できない入口で公開しないでください。
- ペアリング後、Gateway は接続ロール + スコープに限定された **デバイストークン** を発行します。これは `hello-ok.auth.deviceToken` で返され、クライアントが今後の接続用に永続化する必要があります。
- クライアントは、接続に成功するたびに主 `hello-ok.auth.deviceToken` を永続化する必要があります。
- その **保存済み** デバイストークンで再接続する場合は、そのトークンに対して保存された承認済みスコープセットも再利用する必要があります。これにより、すでに付与された read/probe/status アクセスが維持され、再接続がより狭い暗黙の admin のみのスコープへ静かに縮小されることを避けられます。
- Tailscale Serve (`gateway.auth.allowTailscale: true`) や non-loopback
`gateway.auth.mode: "trusted-proxy"` などの ID を持つモードは、`connect.params.auth.*` ではなく
リクエストヘッダーから接続認証チェックを満たします。
- プライベートイングレスの `gateway.auth.mode: "none"` は、共有シークレット接続認証を完全にスキップします。このモードを公開または信頼されていないイングレスに公開しないでください。
- ペアリング後、Gateway は接続ロール + スコープに限定された **デバイストークン** を発行します。これは `hello-ok.auth.deviceToken` で返され、今後の接続のためにクライアントが永続化すべきです。
- クライアントは、接続が成功するたびに主要な `hello-ok.auth.deviceToken` を永続化すべきです。
- その **保存済み** デバイストークンで再接続する場合、そのトークンに対して保存済みの承認済みスコープセットも再利用すべきです。これにより、すでに許可された読み取り/プローブ/ステータスアクセスが保持され、再接続が暗黙の管理者専用スコープへ密かに狭まることを避けられます。
- クライアント側の接続認証組み立て（`src/gateway/client.ts` の `selectConnectAuth`）:
- `auth.password` は独立しており、設定されている場合は常に転送されます。
- `auth.token` は優先順位に従って設定されます。最初に明示的な共有トークン、次に明示的な `deviceToken`、次に保存済みのデバイスごとのトークン（`deviceId` + `role` をキーにする）です。
- `auth.bootstrapToken` は、上記のいずれも `auth.token` を解決しなかった場合にのみ送信されます。共有トークンまたは解決済みデバイストークンはこれを抑制します。
- ワンショットの `AUTH_TOKEN_MISMATCH` リトライで、保存済みデバイストークンを自動昇格する処理は、**信頼済みエンドポイントのみ** に制限されます。
つまり、ループバック、またはピン留めされた `tlsFingerprint` を持つ `wss://` です。ピン留めのない公開 `wss://`
は該当しません。
- 追加の `hello-ok.auth.deviceTokens` エントリは、ブートストラップの引き渡しトークンです。
`wss://` やループバック/local ペアリングなど、信頼済みトランスポート上でブートストラップ認証を使用した接続の場合にのみ永続化してください。
- クライアントが **明示的な** `deviceToken` または明示的な `scopes` を提供した場合、
呼び出し元が要求したそのスコープセットが引き続き信頼できる値になります。キャッシュ済みスコープは、クライアントが保存済みのデバイスごとのトークンを再利用している場合にのみ再利用されます。
- `auth.password` は直交しており、設定されている場合は常に転送されます。
- `auth.token` は優先順位に従って設定されます。まず明示的な共有トークン、次に明示的な `deviceToken`、最後に保存済みのデバイス単位トークン（`deviceId` + `role` をキーにする）です。
- `auth.bootstrapToken` は、上記のいずれも `auth.token` を解決しなかった場合にのみ送信されます。共有トークンまたは解決済みデバイストークンがある場合は抑制されます。
- 一度限りの `AUTH_TOKEN_MISMATCH` リトライで保存済みデバイストークンを自動昇格する処理は、**信頼済みエンドポイントのみ** に制限されます —
loopback、または固定された `tlsFingerprint` を持つ `wss://` です。ピン留めのない公開 `wss://` は該当しません。
- 追加の `hello-ok.auth.deviceTokens` エントリはブートストラップ引き渡しトークンです。
`wss://` や loopback/local ペアリングなどの信頼済みトランスポートでブートストラップ認証を使用して接続した場合にのみ永続化します。
- クライアントが **明示的な** `deviceToken` または明示的な `scopes` を指定した場合、その呼び出し元が要求したスコープセットが引き続き権威を持ちます。キャッシュ済みスコープは、クライアントが保存済みのデバイス単位トークンを再利用している場合にのみ再利用されます。
- デバイストークンは `device.token.rotate` と
`device.token.revoke`（`operator.pairing` スコープが必要）でローテーション/失効できます。
- `device.token.rotate` はローテーションメタデータを返します。置換用ベアラートークンは、そのデバイストークンですでに認証されている同一デバイスの呼び出しに対してのみエコーするため、トークンのみのクライアントは再接続前に置換トークンを永続化できます。共有/admin ローテーションではベアラートークンはエコーされません。
- トークンの発行、ローテーション、失効は、そのデバイスのペアリングエントリに記録された承認済みロールセットに限定されます。トークン変更によって、ペアリング承認で付与されていないデバイスロールへ拡張したり、それを対象にしたりすることはできません。
- ペアリング済みデバイストークンセッションでは、呼び出し元が `operator.admin` も持つ場合を除き、デバイス管理は自己スコープです。非 admin 呼び出し元は **自分自身の** デバイスエントリのみを削除/失効/ローテーションできます。
- `device.token.rotate` と `device.token.revoke` は、対象オペレータートークンのスコープセットを、呼び出し元の現在のセッションスコープとも照合します。非 admin 呼び出し元は、自分がすでに保持しているものより広いオペレータートークンをローテーションまたは失効できません。
- 認証失敗には、`error.details.code` と復旧ヒントが含まれます。
- `device.token.rotate` はローテーションメタデータを返します。置換後の bearer token をエコーするのは、そのデバイストークンですでに認証されている同一デバイス呼び出しの場合のみです。そのため、トークンのみのクライアントは再接続前に置換トークンを永続化できます。共有/管理者ローテーションでは bearer token はエコーされません。
- トークンの発行、ローテーション、失効は、そのデバイスのペアリングエントリに記録された承認済みロールセットの範囲内に留まります。トークン変更によって、ペアリング承認で許可されていないデバイスロールへ拡張したり対象化したりすることはできません。
- ペアリング済みデバイストークンセッションでは、呼び出し元が `operator.admin` も持っていない限り、デバイス管理は自身のスコープに限定されます。非管理者の呼び出し元は **自分自身の** デバイスエントリのみを削除/失効/ローテーションできます。
- `device.token.rotate` と `device.token.revoke` は、対象オペレータートークンのスコープセットも呼び出し元の現在のセッションスコープと照合します。非管理者の呼び出し元は、自分がすでに保持しているより広いオペレータートークンをローテーションまたは失効できません。
- 認証失敗には、`error.details.code` と回復ヒントが含まれます。
- `error.details.canRetryWithDeviceToken`（boolean）
- `error.details.recommendedNextStep`（`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`）
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
- `AUTH_TOKEN_MISMATCH` に対するクライアント動作:
- 信頼済みクライアントは、キャッシュ済みのデバイスごとのトークンで、制限された 1 回のリトライを試行できます。
- そのリトライが失敗した場合、クライアントは自動再接続ループを停止し、オペレーターの対応ガイダンスを表示する必要があります。
- 信頼済みクライアントは、キャッシュ済みデバイス単位トークンで 1 回だけ範囲を限定したリトライを試行できます。
- そのリトライが失敗した場合、クライアントは自動再接続ループを停止し、オペレーター向けの対応ガイダンスを表示すべきです。
## デバイス ID + ペアリング
- Node には、キーペアのフィンガープリントから導出された安定したデバイス ID（`device.id`）を含める必要がある。
- Gateway はデバイス + ロールごとにトークンを発行する。
- local 自動承認が有効でない限り、新しいデバイス ID にはペアリング承認が必要。
- ペアリングの自動承認は、直接の local loopback 接続を中心にしている。
- OpenClaw には、信頼済み共有シークレットのヘルパーフロー向けに、限定的なバックエンド/コンテナ内 self-connect パスもある。
- 同一ホストの tailnet または LAN 接続も、ペアリングでは引き続きリモートとして扱われ、承認が必要。
- WS クライアントは通常、`connect` 時に `device` identity を含める（operator + node）。デバイスなしの operator 例外は、明示的な trust パスのみ。
- localhost 専用の安全でない HTTP 互換性のための `gateway.controlUi.allowInsecureAuth=true`。
- 成功した `gateway.auth.mode: "trusted-proxy"` operator Control UI 認証。
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（緊急回避、重大なセキュリティ低下）。
- 共有 gateway トークン/パスワードで認証された、direct-loopback の `gateway-client` バックエンド RPC。
- すべての接続は、サーバーから提供された `connect.challenge` nonce に署名する必要がある。
- Node には、キーペアのフィンガープリントから派生した安定したデバイス ID（`device.id`）を含める必要があります。
- Gateway はデバイス + ロールごとにトークンを発行します。
- local auto-approval が有効でない限り、新しいデバイス ID にはペアリング承認が必要です。
- ペアリングの自動承認は、直接の local loopback 接続を中心にしています。
- OpenClaw には、信頼済み共有シークレットのヘルパーフロー向けに、限定的なバックエンド/コンテナローカルの自己接続パスもあります。
- 同一ホストの tailnet または LAN 接続も、ペアリングでは引き続きリモートとして扱われ、承認が必要です。
- WS クライアントは通常、`connect` 時に `device` ID を含めます（オペレーター + node）。デバイスなしオペレーターの例外は、明示的な信頼パスのみです:
- localhost 限定の安全でない HTTP 互換性のための `gateway.controlUi.allowInsecureAuth=true`。
- 成功した `gateway.auth.mode: "trusted-proxy"` のオペレーター Control UI 認証。
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（緊急回避用、重大なセキュリティ低下）。
- 共有 Gateway トークン/パスワードで認証された、直接 loopback の `gateway-client` バックエンド RPC。
- すべての接続は、サーバーが提供する `connect.challenge` nonce に署名する必要があります。
### デバイス認証移行診断
pre-challenge 署名動作をまだ使用しているレガシークライアントでは、`connect` は安定した `error.details.reason` とともに、`error.details.code` に `DEVICE_AUTH_*` 詳細コードを返すようになった。
チャレンジ前署名の挙動をまだ使用しているレガシークライアントでは、`connect` は安定した `error.details.reason` とともに、`error.details.code` に `DEVICE_AUTH_*` 詳細コードを返すようになりました。
一般的な移行失敗:
| メッセージ | details.code | details.reason | 意味 |
| メッセージ | details.code | details.reason | 意味 |
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | クライアントが `device.nonce` を省略した（または空で送信した）。 |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | クライアントが古い/誤った nonce で署名した。 |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 署名ペイロードが v2 ペイロードと一致しない。 |
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 署名済みタイムスタンプが許容 skew の範囲外。 |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | クライアントが `device.nonce` を省略した（または空を送信した）。 |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | クライアントが古い/誤った nonce で署名した。 |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 署名ペイロードが v2 ペイロードと一致しない。 |
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 署名済みタイムスタンプが許容スキューの範囲外です。 |
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` が公開鍵フィンガープリントと一致しない。 |
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公開鍵の形式/正規化に失敗した。 |
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公開鍵の形式/正規化に失敗した。 |
移行先:
- 常に `connect.challenge` を待つ。
- サーバー nonce を含む v2 ペイロードに署名する。
- 同じ nonce を `connect.params.device.nonce` で送信する。
- 推奨される署名ペイロードは `v3`。これは device/client/role/scopes/token/nonce フィールドに加えて、`platform` と `deviceFamily` を束縛する。
- レガシー `v2` 署名は互換性のため引き続き受け入れられるが、再接続時のコマンドポリシーは paired-device メタデータのピン留めによって引き続き制御される。
- 必ず `connect.challenge` を待ちます。
- サーバー nonce を含む v2 ペイロードに署名します。
- 同じ nonce を `connect.params.device.nonce` で送信します。
- 推奨される署名ペイロードは `v3` で、device/client/role/scopes/token/nonce フィールドに加えて `platform` と `deviceFamily` を束縛します。
- レガシー `v2` 署名は互換性のため引き続き受け入れられますが、ペアリング済みデバイスのメタデータ pinning が、再接続時のコマンドポリシーを引き続き制御します。
## TLS + ピン留め
## TLS + pinning
- TLS は WS 接続でサポートされる。
- クライアントは必要に応じて gateway 証明書フィンガープリントをピン留めできる（`gateway.tls` config に加えて、`gateway.remote.tlsFingerprint` または CLI `--tls-fingerprint` を参照）。
- WS 接続では TLS がサポートされています。
- クライアントは任意で Gateway 証明書フィンガープリントを pinning できます（`gateway.tls` 設定と `gateway.remote.tlsFingerprint`、または CLI `--tls-fingerprint` を参照）。
## スコープ
このプロトコルは **完全な gateway API**（status、channels、models、chat、agent、sessions、nodes、approvals など）を公開する。正確なサーフェスは `src/gateway/protocol/schema.ts` の TypeBox schemas で定義される。
このプロトコルは、**完全な Gateway API**（ステータス、チャネル、モデル、チャット、エージェント、セッション、ノード、承認など）を公開します。正確なサーフェスは、`src/gateway/protocol/schema.ts` の TypeBox スキーマで定義されています。
## 関連
- [Bridge protocol](/ja-JP/gateway/bridge-protocol)
- [Gateway runbook](/ja-JP/gateway)
- [ブリッジプロトコル](/ja-JP/gateway/bridge-protocol)
- [Gateway ランブック](/ja-JP/gateway)

365
docs/ja-JP/gateway/troubleshooting.md
View File

@ -1,24 +1,24 @@
---
read_when:
- トラブルシューティングハブから、より詳しい診断のためにここへ案内されました
- 正確なコマンドを含む、安定した症状ベースのランブックセクションが必要です
- 正確なコマンドを含む、症状別の安定したランブックセクションが必要です
sidebarTitle: Troubleshooting
summary: Gateway、チャンネル、自動化、ノード、ブラウザー向けの詳細なトラブルシューティングランブック
title: トラブルシューティング
x-i18n:
generated_at: "2026-04-30T05:16:29Z"
generated_at: "2026-05-01T05:01:23Z"
model: gpt-5.5
provider: openai
source_hash: 48735a68daa92678867a9cafb3ceeb37063bb91dee8c4c94e185f74eb0296fcb
source_hash: a808dcfd8527b041f629cff24308550f961e9eeb4d7d4ce6f1ce84dff6bbef89
source_path: gateway/troubleshooting.md
workflow: 16
---
このページは詳細なランブックです。先に高速なトリアージフローを確認したい場合は、[/help/troubleshooting](/ja-JP/help/troubleshooting) から始めてください。
このページは詳細なランブックです。まず高速なトリアージフローを確認したい場合は、[/help/troubleshooting](/ja-JP/help/troubleshooting) から始めてください。
## コマンドの手順
## コマンドの順序
最初に、次の順序で実行します。
まず、次の順序で実行します。
```bash
openclaw status
@ -31,14 +31,14 @@ openclaw channels status --probe
正常時に期待されるシグナル:
- `openclaw gateway status` に `Runtime: running`、`Connectivity probe: ok`、および `Capability: ...` 行が表示される。
- `openclaw doctor` がブロック要因となる設定/サービスの問題を報告しない。
- `openclaw channels status --probe` がアカウントごとのライブ転送ステータスと、対応している場合は `works` や `audit ok` などのプローブ/監査結果を表示する。
- `openclaw doctor` が、ブロック要因となる設定/サービスの問題を報告しない。
- `openclaw channels status --probe` に、アカウントごとのライブのトランスポート状態と、対応している場合は `works` や `audit ok` などのプローブ/監査結果が表示される。
## 分裂したインストールと新しい設定ガード
## スプリットブレインインストールと新しい設定ガード
更新後に Gateway サービスが予期せず停止する場合、またはログに、ある `openclaw` バイナリが最後に `openclaw.json` を書き込んだバージョンより古いことが示される場合に使用します。
更新後に Gateway サービスが予期せず停止する場合、またはログに、ある `openclaw` バイナリが最後に `openclaw.json` を書き込んだバージョンより古いことが示されている場合に使用します。
OpenClaw は設定の書き込みに `meta.lastTouchedVersion` を記録します。読み取り専用コマンドは、より新しい OpenClaw によって書き込まれた設定を引き続き検査できますが、プロセスとサービスの変更は古いバイナリからの継続を拒否します。ブロックされる操作には、Gateway サービスの開始、停止、再起動、アンインストール、強制サービス再インストール、サービスモードでの Gateway 起動、`gateway --force` のポートクリーンアップが含まれます。
OpenClaw は設定の書き込みに `meta.lastTouchedVersion` をスタンプします。読み取り専用コマンドは、新しい OpenClaw が書き込んだ設定を引き続き検査できますが、プロセスとサービスの変更は古いバイナリからの続行を拒否します。ブロックされる操作には、Gateway サービスの起動、停止、再起動、アンインストール、強制サービス再インストール、サービスモードでの Gateway 起動、`gateway --force` によるポートクリーンアップが含まれます。
```bash
which openclaw
@ -49,10 +49,10 @@ openclaw config get meta.lastTouchedVersion
<Steps>
<Step title="PATH を修正する">
`openclaw` がより新しいインストールを解決するように `PATH` を修正し、その後アクションを再実行します。
`PATH` を修正して、`openclaw` が新しいインストール先を解決するようにしてから、操作を再実行します。
</Step>
<Step title="Gateway サービスを再インストールする">
より新しいインストールから、意図した Gateway サービスを再インストールします。
新しいインストール先から意図した Gateway サービスを再インストールします。
```bash
openclaw gateway install --force
@ -61,15 +61,15 @@ openclaw config get meta.lastTouchedVersion
</Step>
<Step title="古いラッパーを削除する">
古い `openclaw` バイナリをまだ指している、古いシステムパッケージまたは古いラッパーエントリを削除します。
古い `openclaw` バイナリをまだ指している古いシステムパッケージまたはラッパーのエントリを削除します。
</Step>
</Steps>
<Warning>
意図的なダウングレードまたは緊急復旧の場合にのみ、単一のコマンドに対して `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` を設定してください。通常運用では未設定のままにします。
意図的なダウングレードまたは緊急復旧の場合のみ、その単一のコマンドに `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` を設定してください。通常運用では未設定のままにします。
</Warning>
## 長いコンテキストには Anthropic 429 の追加使用量が必要
## 長いコンテキストには Anthropic 429 追加使用量が必要
ログ/エラーに `HTTP 429: rate_limit_error: Extra usage is required for long context requests` が含まれる場合に使用します。
@ -79,23 +79,23 @@ openclaw models status
openclaw config get agents.defaults.models
```
確認する内容:
確認すること:
- 選択された Anthropic Opus/Sonnet モデルに `params.context1m: true` がある。
- 現在の Anthropic 認証情報が長いコンテキストの使用対象ではない。
- リクエストが、1M ベータパスを必要とする長いセッション/モデル実行でのみ失敗する。
- 失敗するのは、1M ベータパスを必要とする長いセッション/モデル実行のみ。
修正オプション:
<Steps>
<Step title="context1m を無効にする">
そのモデルの `context1m` を無効にして、通常のコンテキストウィンドウへフォールバックします。
そのモデルの `context1m` を無効にして、通常のコンテキストウィンドウにフォールバックします。
</Step>
<Step title="対象となる認証情報を使用する">
長いコンテキストリクエストの対象となる Anthropic 認証情報を使用するか、Anthropic API キーに切り替えます。
長いコンテキスト要求の対象となる Anthropic 認証情報を使用するか、Anthropic API キーに切り替えます。
</Step>
<Step title="フォールバックモデルを設定する">
Anthropic の長いコンテキストリクエストが拒否されても実行が継続するように、フォールバックモデルを設定します。
Anthropic の長いコンテキスト要求が拒否された場合でも実行が継続されるように、フォールバックモデルを設定します。
</Step>
</Steps>
@ -122,29 +122,29 @@ openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow
```
確認する内容:
確認すること:
- 小さな直接呼び出しは成功するが、OpenClaw の実行は大きなプロンプトでのみ失敗する
- 同じ素のモデル ID で直接 `/v1/chat/completions`
が動作しているにもかかわらず、`model_not_found` または 404 エラーが発生する
- `messages[].content` が文字列を期待しているというバックエンドエラー
- OpenAI 互換ローカルバックエンドで、断続的に `incomplete turn detected ... stopReason=stop payloads=0` 警告が出る
は動作するにもかかわらず、`model_not_found` または 404 エラーが発生する
- `messages[].content` が文字列を想定しているというバックエンドエラー
- OpenAI 互換のローカルバックエンドで断続的に発生する `incomplete turn detected ... stopReason=stop payloads=0` 警告
- より大きなプロンプトトークン数または完全なエージェントランタイムプロンプトでのみ発生するバックエンドクラッシュ
<AccordionGroup>
<Accordion title="一般的なシグネチャ">
- ローカル MLX/vLLM スタイルのサーバーで `model_not_found` → `baseUrl` に `/v1` が含まれること、`/v1/chat/completions` バックエンドでは `api` が `"openai-completions"` であること、`models.providers.<provider>.models[].id` が素のプロバイダー内 ID であることを確認します。選択時は一度だけプロバイダープレフィックス付きで指定します。例: `mlx/mlx-community/Qwen3-30B-A3B-6bit`; カタログエントリは `mlx-community/Qwen3-30B-A3B-6bit` のままにします。
- `messages[...].content: invalid type: sequence, expected a string` → バックエンドが構造化された Chat Completions コンテンツパーツを拒否しています。修正: `models.providers.<provider>.models[].compat.requiresStringContent: true` を設定します。
- `incomplete turn detected ... stopReason=stop payloads=0` → バックエンドは Chat Completions リクエストを完了しましたが、そのターンにユーザーが見えるアシスタントテキストを返していません。OpenClaw は再生しても安全な空の OpenAI 互換ターンを一度だけ再試行します。継続的な失敗は通常、バックエンドが空/非テキストのコンテンツを出力しているか、最終回答テキストを抑制していることを意味します。
- 小さな直接リクエストは成功するが、OpenClaw エージェント実行がバックエンド/モデルのクラッシュで失敗する（例: 一部の `inferrs` ビルド上の Gemma）→ OpenClaw の転送はおそらくすでに正しいです。バックエンドが、より大きなエージェントランタイムプロンプト形状で失敗しています。
- ツールを無効化すると失敗は減るが消えない → ツールスキーマは負荷の一部でしたが、残る問題は依然として上流モデル/サーバーの容量またはバックエンドのバグです。
- ローカルの MLX/vLLM スタイルのサーバーで `model_not_found` → `baseUrl` に `/v1` が含まれていること、`/v1/chat/completions` バックエンドでは `api` が `"openai-completions"` であること、`models.providers.<provider>.models[].id` が素のプロバイダーローカル ID であることを確認してください。たとえば `mlx/mlx-community/Qwen3-30B-A3B-6bit` のように、プロバイダープレフィックスを一度付けて選択します。カタログエントリは `mlx-community/Qwen3-30B-A3B-6bit` のままにします。
- `messages[...].content: invalid type: sequence, expected a string` → バックエンドが構造化された Chat Completions のコンテンツパーツを拒否しています。修正: `models.providers.<provider>.models[].compat.requiresStringContent: true` を設定します。
- `incomplete turn detected ... stopReason=stop payloads=0` → バックエンドは Chat Completions 要求を完了しましたが、そのターンでユーザーに表示されるアシスタントテキストを返していません。OpenClaw は、再生しても安全な空の OpenAI 互換ターンを 1 回再試行します。失敗が継続する場合、通常はバックエンドが空/非テキストのコンテンツを出力しているか、最終回答テキストを抑制していることを意味します。
- 小さな直接要求は成功するが、OpenClaw エージェント実行がバックエンド/モデルのクラッシュで失敗する（たとえば一部の `inferrs` ビルド上の Gemma）→ OpenClaw のトランスポートはすでに正しい可能性が高く、バックエンドが大きなエージェントランタイムプロンプト形状で失敗しています。
- ツールを無効にすると失敗は減るが、消えない → ツールスキーマは負荷の一部でしたが、残る問題は依然として上流のモデル/サーバー容量、またはバックエンドのバグです。
</Accordion>
<Accordion title="修正オプション">
1. 文字列のみの Chat Completions バックエンドには `compat.requiresStringContent: true` を設定します。
2. OpenClaw のツールスキーマサーフェスを確実に処理できないモデル/バックエンドには `compat.supportsTools: false` を設定します。
3. 可能な範囲でプロンプト負荷を下げます: より小さいワークスペースブートストラップ、より短いセッション履歴、より軽いローカルモデル、またはより強力な長いコンテキスト対応を持つバックエンド。
4. 小さな直接リクエストは通り続ける一方で OpenClaw エージェントターンがバックエンド内部でまだクラッシュする場合は、上流サーバー/モデルの制限として扱い、受け入れられたペイロード形状とともにそこで再現報告を提出します。
2. OpenClaw のツールスキーマサーフェスを安定して処理できないモデル/バックエンドには `compat.supportsTools: false` を設定します。
3. 可能な範囲でプロンプト負荷を下げます。小さめのワークスペースブートストラップ、短いセッション履歴、軽量なローカルモデル、またはより強い長いコンテキスト対応を持つバックエンドを使用します。
4. 小さな直接要求が通り続ける一方で OpenClaw エージェントターンがバックエンド内でまだクラッシュする場合は、上流のサーバー/モデルの制限として扱い、受け入れられたペイロード形状とともに再現手順をそちらに報告します。
</Accordion>
</AccordionGroup>
@ -166,16 +166,16 @@ openclaw config get channels
openclaw logs --follow
```
確認する内容:
確認すること:
- DM 送信者のペアリングが保留中。
- グループメンションのゲート制御（`requireMention`、`mentionPatterns`）。
- グループメンションゲーティング（`requireMention`、`mentionPatterns`）。
- チャンネル/グループの許可リスト不一致。
一般的なシグネチャ:
- `drop guild message (mention required` → メンションされるまでグループメッセージは無視されます。
- `pairing request` → 送信者の承認が必要です。
- `pairing request` → 送信者には承認が必要です。
- `blocked` / `allowlist` → 送信者/チャンネルがポリシーによってフィルタリングされました。
関連:
@ -186,7 +186,7 @@ openclaw logs --follow
## ダッシュボード制御 UI の接続性
ダッシュボード/制御 UI が接続しない場合は、URL、認証モード、セキュアコンテキストの前提を検証します。
ダッシュボード/制御 UI が接続しない場合は、URL、認証モード、およびセキュアコンテキストの前提を検証します。
```bash
openclaw gateway status
@ -196,42 +196,42 @@ openclaw doctor
openclaw gateway status --json
```
確認する内容:
確認すること:
- 正しいプローブ URL とダッシュボード URL。
- クライアントと Gateway の間の認証モード/トークン不一致。
- クライアントと Gateway の間で認証モード/トークンが不一致。
- デバイス ID が必要な場所で HTTP を使用している。
<AccordionGroup>
<Accordion title="接続 / 認証シグネチャ">
- `device identity required` → 非セキュアコンテキスト、またはデバイス認証の欠落。
- `origin not allowed` → ブラウザーの `Origin` が `gateway.controlUi.allowedOrigins` に含まれていません（または明示的な許可リストなしで非ループバックブラウザーオリジンから接続しています）。
- `origin not allowed` → ブラウザーの `Origin` が `gateway.controlUi.allowedOrigins` に含まれていません（または、明示的な許可リストなしで非ループバックのブラウザーオリジンから接続しています）。
- `device nonce required` / `device nonce mismatch` → クライアントがチャレンジベースのデバイス認証フロー（`connect.challenge` + `device.nonce`）を完了していません。
- `device signature invalid` / `device signature expired` → クライアントが現在のハンドシェイクに対して誤ったペイロード（または古いタイムスタンプ）に署名しました。
- `AUTH_TOKEN_MISMATCH` かつ `canRetryWithDeviceToken=true` → クライアントはキャッシュ済みデバイストークンで信頼済みリトライを一度実行できます。
- そのキャッシュトークンリトライでは、ペアリング済みデバイストークンとともに保存されたキャッシュ済みスコープセットを再利用します。明示的な `deviceToken` / 明示的な `scopes` 呼び出し元は、代わりに要求したスコープセットを保持します。
- そのリトライパスの外では、接続認証の優先順位は、明示的な共有トークン/パスワード、次に明示的な `deviceToken`、次に保存済みデバイストークン、最後にブートストラップトークンです。
- 非同期 Tailscale Serve Control UI パスでは、同じ `{scope, ip}` に対する失敗試行は、リミッターが失敗を記録する前に直列化されます。そのため、同じクライアントからの不正な同時リトライが 2 つある場合、2 つの単純な不一致ではなく、2 回目の試行で `retry later` が表面化することがあります。
- ブラウザーオリジンのループバッククライアントから `too many failed authentication attempts (retry later)` → 同じ正規化済み `Origin` からの失敗が繰り返され、一時的にロックアウトされています。別の localhost オリジンは別バケットを使用します。
- そのリトライ後も `unauthorized` が繰り返される → 共有トークン/デバイストークンのずれです。必要に応じてトークン設定を更新し、デバイストークンを再承認/ローテーションします。
- `gateway connect failed:` → ホスト/ポート/URL ターゲットが誤っています。
- `AUTH_TOKEN_MISMATCH` かつ `canRetryWithDeviceToken=true` → クライアントはキャッシュ済みデバイストークンで信頼済みリトライを 1 回実行できます。
- そのキャッシュ済みトークンでのリトライは、ペアリング済みデバイストークンとともに保存されたキャッシュ済みスコープセットを再利用します。明示的な `deviceToken` / 明示的な `scopes` の呼び出し元は、代わりに要求したスコープセットを維持します。
- そのリトライパス以外では、接続認証の優先順位は、明示的な共有トークン/パスワード、明示的な `deviceToken`、保存済みデバイストークン、ブートストラップトークンの順です。
- 非同期 Tailscale Serve Control UI パスでは、同じ `{scope, ip}` の失敗試行は、リミッターが失敗を記録する前にシリアル化されます。そのため、同じクライアントからの 2 つの不正な同時リトライでは、2 つの単純な不一致ではなく、2 回目の試行で `retry later` が表面化することがあります。
- ブラウザーオリジンのループバッククライアントから `too many failed authentication attempts (retry later)` → 同じ正規化済み `Origin` からの繰り返し失敗が一時的にロックアウトされています。別の localhost オリジンは別のバケットを使用します。
- そのリトライ後も `unauthorized` が繰り返される → 共有トークン/デバイストークンのドリフトです。トークン設定を更新し、必要に応じてデバイストークンを再承認/ローテーションしてください。
- `gateway connect failed:` → ホスト/ポート/URL ターゲットが間違っています。
</Accordion>
</AccordionGroup>
### 認証詳細コードのクイックマップ
失敗した `connect` レスポンスの `error.details.code` を使用して、次のアクションを選択します。
失敗した `connect` レスポンスの `error.details.code` を使用して、次の操作を選択します。
| 詳細コード | 意味 | 推奨される対応 |
| 詳細コード | 意味 | 推奨アクション |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | クライアントが必要な共有トークンを送信しませんでした。 | クライアントにトークンを貼り付けるか設定して、再試行します。ダッシュボードのパスの場合: `openclaw config get gateway.auth.token` を実行してから、Control UI 設定に貼り付けます。 |
| `AUTH_TOKEN_MISMATCH` | 共有トークンが Gateway 認証トークンと一致しませんでした。 | `canRetryWithDeviceToken=true` の場合は、信頼済みの再試行を 1 回許可します。キャッシュされたトークンでの再試行では、保存済みの承認済みスコープを再利用します。明示的な `deviceToken` / `scopes` 呼び出し元は要求したスコープを保持します。それでも失敗する場合は、[トークンドリフト復旧チェックリスト](/ja-JP/cli/devices#token-drift-recovery-checklist)を実行します。 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | キャッシュされたデバイスごとのトークンが古いか、取り消されています。 | [デバイス CLI](/ja-JP/cli/devices) を使ってデバイストークンをローテーションまたは再承認してから、再接続します。 |
| `PAIRING_REQUIRED` | デバイス ID の承認が必要です。`error.details.reason` で `not-paired`、`scope-upgrade`、`role-upgrade`、または `metadata-upgrade` を確認し、存在する場合は `requestId` / `remediationHint` を使用します。 | 保留中のリクエストを承認します: `openclaw devices list` の後に `openclaw devices approve <requestId>` を実行します。スコープ/ロールのアップグレードでは、要求されたアクセスを確認した後に同じフローを使用します。 |
| `AUTH_TOKEN_MISSING` | クライアントが必須の共有トークンを送信しませんでした。 | クライアントにトークンを貼り付けるか設定して、再試行します。ダッシュボード経路の場合: `openclaw config get gateway.auth.token` を実行してから Control UI 設定に貼り付けます。 |
| `AUTH_TOKEN_MISMATCH` | 共有トークンが Gateway 認証トークンと一致しませんでした。 | `canRetryWithDeviceToken=true` の場合は、信頼済みの再試行を 1 回許可します。キャッシュ済みトークンによる再試行では、保存済みの承認済みスコープを再利用します。明示的な `deviceToken` / `scopes` 呼び出し元は、要求したスコープを維持します。それでも失敗する場合は、[トークンドリフト復旧チェックリスト](/ja-JP/cli/devices#token-drift-recovery-checklist)を実行します。 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | キャッシュ済みのデバイス単位トークンが古いか、取り消されています。 | [devices CLI](/ja-JP/cli/devices) を使ってデバイストークンをローテートまたは再承認し、その後再接続します。 |
| `PAIRING_REQUIRED` | デバイス ID の承認が必要です。`error.details.reason` で `not-paired`、`scope-upgrade`、`role-upgrade`、または `metadata-upgrade` を確認し、存在する場合は `requestId` / `remediationHint` を使います。 | 保留中のリクエストを承認します: `openclaw devices list` の後に `openclaw devices approve <requestId>` を実行します。スコープ/ロールのアップグレードも、要求されたアクセスを確認した後に同じフローを使います。 |
<Note>
共有 Gateway トークン/パスワードで認証される直接 loopback バックエンド RPC は、CLI のペアリング済みデバイススコープのベースラインに依存すべきではありません。サブエージェントやその他の内部呼び出しがまだ `scope-upgrade` で失敗する場合は、呼び出し元が `client.id: "gateway-client"` と `client.mode: "backend"` を使用しており、明示的な `deviceIdentity` やデバイストークンを強制していないことを確認してください。
共有 Gateway トークン/パスワードで認証された直接 loopback バックエンド RPC は、CLI のペアリング済みデバイスのスコープベースラインに依存すべきではありません。サブエージェントやその他の内部呼び出しがまだ `scope-upgrade` で失敗する場合は、呼び出し元が `client.id: "gateway-client"` と `client.mode: "backend"` を使っており、明示的な `deviceIdentity` やデバイストークンを強制していないことを確認します。
</Note>
デバイス認証 v2 の移行チェック:
@ -242,24 +242,24 @@ openclaw doctor
openclaw gateway status
```
ログに nonce/署名エラーが表示される場合は、接続元クライアントを更新して検証します。
ログに nonce/署名エラーが表示される場合は、接続元クライアントを更新して検証します:
<Steps>
<Step title="connect.challenge を待つ">
クライアントは Gateway が発行した `connect.challenge` を待ちます。
<Step title="connect.challenge を待機">
クライアントは Gateway が発行する `connect.challenge` を待機します。
</Step>
<Step title="ペイロードに署名する">
クライアントはチャレンジにバインドされたペイロードに署名します。
<Step title="ペイロードに署名">
クライアントはチャレンジに紐づいたペイロードに署名します。
</Step>
<Step title="デバイス nonce を送信する">
クライアントは同じチャレンジ nonce を使用して `connect.params.device.nonce` を送信します。
<Step title="デバイス nonce を送信">
クライアントは同じチャレンジ nonce を使って `connect.params.device.nonce` を送信します。
</Step>
</Steps>
`openclaw devices rotate` / `revoke` / `remove` が予期せず拒否される場合:
- ペアリング済みデバイストークンのセッションは、呼び出し元が `operator.admin` も持っていない限り、**自身の**デバイスしか管理できません
- `openclaw devices rotate --scope ...` は、呼び出し元セッションがすでに保持しているオペレータースコープのみ要求できます
- ペアリング済みデバイストークンのセッションは、呼び出し元が `operator.admin` も持っていない限り、**自身の** デバイスしか管理できません
- `openclaw devices rotate --scope ...` は、呼び出し元セッションがすでに保持している operator スコープのみを要求できます
関連:
@ -271,7 +271,7 @@ openclaw gateway status
## Gateway サービスが実行されていない
サービスはインストールされているが、プロセスが起動したままにならない場合に使用します。
サービスはインストール済みだが、プロセスが起動し続けない場合に使います。
```bash
openclaw gateway status
@ -281,22 +281,22 @@ openclaw doctor
openclaw gateway status --deep # also scan system-level services
```
確認する項目:
確認すること:
- `Runtime: stopped` と終了ヒント。
- サービス構成の不一致 (`Config (cli)` と `Config (service)`)。
- ポート/リスナーの競合。
- `--deep` が使用されている場合の追加の launchd/systemd/schtasks インストール。
- `--deep` を使った場合の余分な launchd/systemd/schtasks インストール。
- `Other gateway-like services detected (best effort)` のクリーンアップヒント。
<AccordionGroup>
<Accordion title="一般的なシグネチャ">
- `Gateway start blocked: set gateway.mode=local` または `existing config is missing gateway.mode` → ローカル Gateway モードが有効になっていないか、構成ファイルが上書きされて `gateway.mode` が失われています。修正: 構成で `gateway.mode="local"` を設定するか、`openclaw onboard --mode local` / `openclaw setup` を再実行して、想定されるローカルモード構成を再スタンプします。Podman 経由で OpenClaw を実行している場合、デフォルトの構成パスは `~/.openclaw/openclaw.json` です。
- `refusing to bind gateway ... without auth` → 有効な Gateway 認証パス (トークン/パスワード、または構成済みの場合は信頼済みプロキシ) なしで非 loopback にバインドしようとしています。
<Accordion title="一般的な兆候">
- `Gateway start blocked: set gateway.mode=local` または `existing config is missing gateway.mode` → local Gateway モードが有効ではない、または構成ファイルが上書きされて `gateway.mode` が失われています。修正: 構成で `gateway.mode="local"` を設定するか、`openclaw onboard --mode local` / `openclaw setup` を再実行して、想定される local モード構成を再スタンプします。Podman 経由で OpenClaw を実行している場合、デフォルトの構成パスは `~/.openclaw/openclaw.json` です。
- `refusing to bind gateway ... without auth` → 有効な Gateway 認証経路 (トークン/パスワード、または構成済みの場合は信頼済みプロキシ) なしで非 loopback にバインドしようとしています。
- `another gateway instance is already listening` / `EADDRINUSE` → ポート競合です。
- `Other gateway-like services detected (best effort)` → 古い、または並行する launchd/systemd/schtasks ユニットが存在します。ほとんどのセットアップでは、1 台のマシンにつき 1 つの Gateway にするべきです。複数必要な場合は、ポート + 構成/状態/ワークスペースを分離してください。[/gateway#multiple-gateways-same-host](/ja-JP/gateway#multiple-gateways-same-host) を参照してください。
- doctor からの `System-level OpenClaw gateway service detected` → ユーザーレベルのサービスがない一方で、systemd システムユニットが存在します。doctor にユーザーサービスをインストールさせる前に重複を削除または無効化するか、システムユニットが意図したスーパーバイザーである場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。
- `Gateway service port does not match current gateway config` → インストール済みのスーパーバイザーがまだ古い `--port` を固定しています。`openclaw doctor --fix` または `openclaw gateway install --force` を実行してから、Gateway サービスを再起動します。
- `Other gateway-like services detected (best effort)` → 古い、または並列の launchd/systemd/schtasks ユニットが存在します。ほとんどのセットアップでは、1 台のマシンにつき 1 つの Gateway にするべきです。複数必要な場合は、ポート + 構成/状態/ワークスペースを分離してください。[/gateway#multiple-gateways-same-host](/ja-JP/gateway#multiple-gateways-same-host) を参照してください。
- doctor の `System-level OpenClaw gateway service detected` → ユーザーレベルサービスがない一方で systemd システムユニットが存在します。doctor にユーザーサービスのインストールを許可する前に重複を削除または無効化するか、システムユニットが意図したスーパーバイザーである場合は `OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。
- `Gateway service port does not match current gateway config` → インストール済みスーパーバイザーがまだ古い `--port` を固定しています。`openclaw doctor --fix` または `openclaw gateway install --force` を実行してから、Gateway サービスを再起動します。
</Accordion>
</AccordionGroup>
@ -307,9 +307,9 @@ openclaw gateway status --deep # also scan system-level services
- [構成](/ja-JP/gateway/configuration)
- [Doctor](/ja-JP/gateway/doctor)
## Gateway が最後に正常だった構成を復元した
## Gateway が最後の正常な構成を復元した
Gateway は起動するものの、ログで `openclaw.json` を復元したと表示される場合に使用します。
Gateway は起動するが、ログに `openclaw.json` を復元したと表示される場合に使います。
```bash
openclaw logs --follow
@ -318,24 +318,24 @@ openclaw config validate
openclaw doctor
```
確認する項目:
確認すること:
- `Config auto-restored from last-known-good`
- `gateway: invalid config was restored from last-known-good backup`
- `config reload restored last-known-good config after invalid-config`
- アクティブな構成の横にある、タイムスタンプ付きの `openclaw.json.clobbered.*` ファイル
- アクティブな構成の隣にある、タイムスタンプ付きの `openclaw.json.clobbered.*` ファイル
- `Config recovery warning` で始まるメインエージェントのシステムイベント
<AccordionGroup>
<Accordion title="何が起きたか">
- 拒否された構成は、起動中またはホットリロード中の検証に通りませんでした。
- OpenClaw は拒否されたペイロードを `.clobbered.*` として保持しました。
- アクティブな構成は、最後に検証された last-known-good コピーから復元されました。
- 次のメインエージェントターンには、拒否された構成を無条件に書き直さないよう警告されます。
- すべての検証問題が `plugins.entries.<id>...` の下にある場合、OpenClaw はファイル全体を復元しません。Plugin ローカルの失敗は明示されたまま、無関係なユーザー設定はアクティブな構成に残ります。
- 拒否された構成は、起動中またはホットリロード中に検証に合格しませんでした。
- OpenClaw は拒否されたペイロードを `.clobbered.*` として保存しました。
- アクティブな構成は、最後に検証済みの last-known-good コピーから復元されました。
- 次のメインエージェントターンでは、拒否された構成を盲目的に書き直さないよう警告されます。
- すべての検証問題が `plugins.entries.<id>...` の下にあった場合、OpenClaw はファイル全体を復元しません。Plugin ローカルの失敗は明確に残り、無関係なユーザー設定はアクティブな構成に残ります。
</Accordion>
<Accordion title="検査と修復">
<Accordion title="調査と修復">
```bash
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
@ -344,18 +344,19 @@ openclaw doctor
openclaw doctor
```
</Accordion>
<Accordion title="一般的なシグネチャ">
- `.clobbered.*` が存在する → 外部からの直接編集、または起動時の読み取りが復元されました。
- `.rejected.*` が存在する → OpenClaw 所有の構成書き込みが、コミット前にスキーマまたは clobber チェックに失敗しました。
- `Config write rejected:` → 書き込みが必要な形状を落とそうとした、ファイルを急激に縮小しようとした、または無効な構成を永続化しようとしました。
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good`、または `size-drop-vs-last-good:*` → 現在のファイルが、last-known-good バックアップと比較してフィールドまたはサイズを失っていたため、起動時に clobber されたものとして扱われました。
- `Config last-known-good promotion skipped` → 候補に `***` などの秘匿済みシークレットプレースホルダーが含まれていました。
<Accordion title="一般的な兆候">
- `.clobbered.*` が存在する → 外部からの直接編集または起動時読み取りが復元されました。
- `.rejected.*` が存在する → OpenClaw が所有する構成書き込みが、コミット前にスキーマまたは上書きチェックで失敗しました。
- `Config write rejected:` → 書き込みが必須の形を落とす、ファイルを急激に縮小する、または無効な構成を永続化しようとしました。
- `Rejected validation details:` → 復旧ログまたはメインエージェント通知に、復元の原因となったスキーマパスが含まれます。例: `agents.defaults.execution` または `gateway.auth.password.source`。
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good`、または `size-drop-vs-last-good:*` → 現在のファイルが last-known-good バックアップと比較してフィールドまたはサイズを失っていたため、起動時に上書きされたものとして扱われました。
- `Config last-known-good promotion skipped` → 候補に `***` などの墨消し済みシークレットプレースホルダーが含まれていました。
</Accordion>
<Accordion title="修正オプション">
1. 復元されたアクティブ構成が正しければ、そのまま保持します。
1. 復元されたアクティブな構成が正しい場合は、そのまま維持します。
2. `.clobbered.*` または `.rejected.*` から意図したキーだけをコピーし、`openclaw config set` または `config.patch` で適用します。
3. 再起動する前に `openclaw config validate` を実行します。
3. 再起動前に `openclaw config validate` を実行します。
4. 手作業で編集する場合は、変更したい部分オブジェクトだけではなく、完全な JSON5 構成を保持します。
</Accordion>
</AccordionGroup>
@ -364,12 +365,12 @@ openclaw doctor
- [Config](/ja-JP/cli/config)
- [構成: ホットリロード](/ja-JP/gateway/configuration#config-hot-reload)
- [構成: 厳密な検証](/ja-JP/gateway/configuration#strict-validation)
- [構成: 厳格な検証](/ja-JP/gateway/configuration#strict-validation)
- [Doctor](/ja-JP/gateway/doctor)
## Gateway プローブ警告
## Gateway probe の警告
`openclaw gateway probe` が何かに到達するものの、警告ブロックも出力する場合に使用します。
`openclaw gateway probe` が何かに到達するものの、警告ブロックも表示する場合に使います。
```bash
openclaw gateway probe
@ -377,19 +378,19 @@ openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host
```
確認する項目:
確認すること:
- JSON 出力内の `warnings[].code` と `primaryTargetId`。
- 警告が SSH フォールバック、複数 Gateway、スコープ不足、または未解決の認証参照に関するものかどうか。
- JSON 出力の `warnings[].code` と `primaryTargetId`。
- 警告が SSH フォールバック、複数の Gateway、不足スコープ、未解決の認証参照のいずれに関するものか。
一般的なシグネチャ:
一般的な兆候:
- `SSH tunnel failed to start; falling back to direct probes.` → SSH セットアップに失敗しましたが、コマンドは構成済み/loopback ターゲットへの直接プローブを試行しました。
- `multiple reachable gateways detected` → 複数のターゲットが応答しました。通常、これは意図的な複数 Gateway セットアップ、または古い/重複したリスナーを意味します。
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 接続は成功しましたが、詳細 RPC はスコープで制限されています。デバイス ID をペアリングするか、`operator.read` を持つ認証情報を使用してください。
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 接続は成功しましたが、完全な診断 RPC セットがタイムアウトまたは失敗しました。これは診断機能が低下した到達可能な Gateway として扱い、`--json` 出力の `connect.ok` と `connect.rpcOk` を比較してください。
- `Capability: pairing-pending` または `gateway closed (1008): pairing required` → Gateway は応答しましたが、このクライアントは通常のオペレーターアクセスの前に、まだペアリング/承認が必要です。
- 未解決の `gateway.auth.*` / `gateway.remote.*` SecretRef 警告テキスト → 失敗したターゲットについて、このコマンドパスで認証素材を利用できませんでした。
- `SSH tunnel failed to start; falling back to direct probes.` → SSH セットアップに失敗しましたが、コマンドは引き続き構成済み/loopback の直接ターゲットを試しました。
- `multiple reachable gateways detected` → 複数のターゲットが応答しました。通常これは、意図的なマルチ Gateway セットアップ、または古い/重複したリスナーを意味します。
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 接続は成功しましたが、詳細 RPC はスコープによって制限されています。デバイス ID をペアリングするか、`operator.read` を持つ認証情報を使ってください。
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 接続は成功しましたが、完全な診断 RPC セットがタイムアウトまたは失敗しました。これは診断が劣化した到達可能な Gateway として扱い、`--json` 出力の `connect.ok` と `connect.rpcOk` を比較します。
- `Capability: pairing-pending` または `gateway closed (1008): pairing required` → Gateway は応答しましたが、このクライアントは通常の operator アクセスの前にまだペアリング/承認が必要です。
- 未解決の `gateway.auth.*` / `gateway.remote.*` SecretRef 警告テキスト → 失敗したターゲットに対して、このコマンド経路では認証素材を利用できませんでした。
関連:
@ -399,7 +400,7 @@ openclaw gateway probe --ssh user@gateway-host
## チャネルは接続済みだが、メッセージが流れない
チャネル状態が接続済みでもメッセージフローが停止している場合は、ポリシー、権限、チャネル固有の配信ルールに注目します。
チャネル状態が接続済みだがメッセージフローが停止している場合は、ポリシー、権限、チャネル固有の配信ルールに注目します。
```bash
openclaw channels status --probe
@ -409,28 +410,28 @@ openclaw logs --follow
openclaw config get channels
```
確認する項目:
確認すること:
- DM ポリシー (`pairing`、`allowlist`、`open`、`disabled`)。
- グループ許可リストとメンション要件。
- 不足しているチャネル API 権限/スコープ。
- DM ポリシー（`pairing`、`allowlist`、`open`、`disabled`）。
- グループの許可リストとメンション要件。
- チャネル API 権限/スコープの不足。
一般的なシグネチャ:
一般的な兆候:
- `mention required` → グループメンションポリシーによりメッセージは無視されます。
- `mention required` → グループのメンションポリシーによりメッセージが無視されました。
- `pairing` / 承認待ちのトレース → 送信者が承認されていません。
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → チャンネルの認証/権限の問題です。
- `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → チャネル認証/権限の問題です。
関連:
- [チャンネルのトラブルシューティング](/ja-JP/channels/troubleshooting)
- [チャネルのトラブルシューティング](/ja-JP/channels/troubleshooting)
- [Discord](/ja-JP/channels/discord)
- [Telegram](/ja-JP/channels/telegram)
- [WhatsApp](/ja-JP/channels/whatsapp)
## Cron と Heartbeat の配信
Cron または Heartbeat が実行されなかった、または配信されなかった場合は、まずスケジューラの状態を確認し、その後で配信先を確認します。
Cron または Heartbeat が実行されなかった、または配信されなかった場合は、まずスケジューラーの状態を確認し、その後に配信先を確認します。
```bash
openclaw cron status
@ -440,21 +441,21 @@ openclaw system heartbeat last
openclaw logs --follow
```
確認する内容:
確認すること:
- Cron が有効で、次回の起床時刻が存在すること。
- ジョブ実行履歴のステータス (`ok`, `skipped`, `error`)。
- Heartbeat のスキップ理由 (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`)。
- Cron が有効で、次回の起動が存在する。
- ジョブ実行履歴の状態（`ok`、`skipped`、`error`）。
- Heartbeat のスキップ理由（`quiet-hours`、`requests-in-flight`、`cron-in-progress`、`lanes-busy`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。
<AccordionGroup>
<Accordion title="一般的なシグネチャ">
- `cron: scheduler disabled; jobs will not run automatically` → cron が無効です。
- `cron: timer tick failed` → スケジューラの tick に失敗しました。ファイル/ログ/ランタイムエラーを確認してください。
- `heartbeat skipped` で `reason=quiet-hours` → アクティブ時間帯の範囲外です。
- `heartbeat skipped` で `reason=empty-heartbeat-file` → `HEARTBEAT.md` は存在しますが、空行または Markdown 見出ししか含まれていないため、OpenClaw はモデル呼び出しをスキップします。
- `heartbeat skipped` で `reason=no-tasks-due` → `HEARTBEAT.md` に `tasks:` ブロックがありますが、この tick で期限に達したタスクがありません。
<Accordion title="Common signatures">
- `cron: scheduler disabled; jobs will not run automatically` → Cron が無効です。
- `cron: timer tick failed` → スケジューラーの tick に失敗しました。ファイル/ログ/ランタイムエラーを確認してください。
- `heartbeat skipped` と `reason=quiet-hours` → アクティブ時間帯の範囲外です。
- `heartbeat skipped` と `reason=empty-heartbeat-file` → `HEARTBEAT.md` は存在しますが、空行または Markdown 見出ししか含まれていないため、OpenClaw はモデル呼び出しをスキップします。
- `heartbeat skipped` と `reason=no-tasks-due` → `HEARTBEAT.md` に `tasks:` ブロックが含まれていますが、この tick で期限を迎えるタスクがありません。
- `heartbeat: unknown accountId` → Heartbeat 配信先のアカウント ID が無効です。
- `heartbeat skipped` で `reason=dm-blocked` → `agents.defaults.heartbeat.directPolicy` (またはエージェントごとの上書き) が `block` に設定されている間に、Heartbeat の送信先が DM 形式の送信先として解決されました。
- `heartbeat skipped` と `reason=dm-blocked` → `agents.defaults.heartbeat.directPolicy`（またはエージェントごとの上書き）が `block` に設定されている間に、Heartbeat の対象が DM 形式の宛先に解決されました。
</Accordion>
</AccordionGroup>
@ -465,9 +466,9 @@ openclaw logs --follow
- [スケジュール済みタスク](/ja-JP/automation/cron-jobs)
- [スケジュール済みタスク: トラブルシューティング](/ja-JP/automation/cron-jobs#troubleshooting)
## Node はペアリング済みだが、ツールが失敗する
## Node はペアリング済みだがツールが失敗する
Node がペアリング済みでもツールが失敗する場合は、フォアグラウンド、権限、承認状態を切り分けます。
Node がペアリング済みでもツールが失敗する場合は、フォアグラウンド、権限、承認の状態を切り分けます。
```bash
openclaw nodes status
@ -477,22 +478,22 @@ openclaw logs --follow
openclaw status
```
確認する内容:
確認すること:
- Node がオンラインで、期待される機能を持っていること。
- カメラ/マイク/位置情報/画面に対する OS 権限の付与。
- 実行承認と allowlist の状態。
- Node がオンラインで、期待される機能を備えている。
- カメラ/マイク/位置情報/画面の OS 権限付与。
- exec 承認と許可リストの状態。
一般的なシグネチャ:
一般的な兆候:
- `NODE_BACKGROUND_UNAVAILABLE` → node アプリをフォアグラウンドにする必要があります。
- `NODE_BACKGROUND_UNAVAILABLE` → Node アプリをフォアグラウンドにする必要があります。
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → OS 権限が不足しています。
- `SYSTEM_RUN_DENIED: approval required` → 実行承認が保留中です。
- `SYSTEM_RUN_DENIED: allowlist miss` → コマンドが allowlist によってブロックされています。
- `SYSTEM_RUN_DENIED: approval required` → exec 承認が保留中です。
- `SYSTEM_RUN_DENIED: allowlist miss` → コマンドが許可リストによりブロックされました。
関連:
- [実行承認](/ja-JP/tools/exec-approvals)
- [Exec 承認](/ja-JP/tools/exec-approvals)
- [Node のトラブルシューティング](/ja-JP/nodes/troubleshooting)
- [Node](/ja-JP/nodes/index)
@ -508,56 +509,56 @@ openclaw logs --follow
openclaw doctor
```
確認する内容:
確認すること:
- `plugins.allow` が設定されており、`browser` を含んでいるか。
- 有効なブラウザ実行ファイルのパス。
- CDP プロファイルに到達できるか。
- `existing-session` / `user` プロファイル用のローカル Chrome が利用可能か。
- `plugins.allow` が設定され、`browser` を含んでいるか。
- 有効なブラウザ実行ファイルパス。
- CDP プロファイルへの到達性。
- `existing-session` / `user` プロファイル向けのローカル Chrome の可用性。
<AccordionGroup>
<Accordion title="Plugin / 実行ファイルのシグネチャ">
- `unknown command "browser"` または `unknown command 'browser'` → バンドルされたブラウザ Plugin が `plugins.allow` によって除外されています。
- `browser.enabled=true` なのにブラウザツールが見つからない/利用できない → `plugins.allow` が `browser` を除外しているため、Plugin が読み込まれていません。
<Accordion title="Plugin / executable signatures">
- `unknown command "browser"` または `unknown command 'browser'` → 同梱のブラウザ Plugin が `plugins.allow` により除外されています。
- `browser.enabled=true` の間にブラウザツールが欠落/利用不可 → `plugins.allow` が `browser` を除外しているため、Plugin が読み込まれていません。
- `Failed to start Chrome CDP on port` → ブラウザプロセスの起動に失敗しました。
- `browser.executablePath not found` → 設定されたパスが無効です。
- `browser.cdpUrl must be http(s) or ws(s)` → 設定された CDP URL が `file:` や `ftp:` などのサポートされないスキームを使用しています。
- `browser.cdpUrl has invalid port` → 設定された CDP URL のポートが不正、または範囲外です。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 現在の gateway インストールには、バンドルされたブラウザ Plugin の `playwright-core` ランタイム依存関係がありません。`openclaw doctor --fix` を実行し、その後 Gateway を再起動してください。ARIA スナップショットと基本的なページスクリーンショットは引き続き動作しますが、ナビゲーション、AI スナップショット、CSS セレクタ要素スクリーンショット、PDF エクスポートは利用できないままです。
- `browser.cdpUrl must be http(s) or ws(s)` → 設定された CDP URL が `file:` や `ftp:` などの未対応スキームを使用しています。
- `browser.cdpUrl has invalid port` → 設定された CDP URL のポートが不正または範囲外です。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 現在の Gateway インストールには、同梱ブラウザ Plugin の `playwright-core` ランタイム依存関係がありません。`openclaw doctor --fix` を実行してから Gateway を再起動してください。ARIA スナップショットと基本的なページスクリーンショットは引き続き動作する場合がありますが、ナビゲーション、AI スナップショット、CSS セレクター要素スクリーンショット、PDF エクスポートは利用できません。
</Accordion>
<Accordion title="Chrome MCP / existing-session のシグネチャ">
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session は、選択されたブラウザデータディレクトリにまだ接続できませんでした。ブラウザの inspect ページを開き、リモートデバッグを有効にし、ブラウザを開いたままにして、最初の接続プロンプトを承認してから再試行してください。サインイン状態が不要な場合は、管理対象の `openclaw` プロファイルを優先してください。
- `No Chrome tabs found for profile="user"` → Chrome MCP 接続プロファイルに、開いているローカル Chrome タブがありません。
<Accordion title="Chrome MCP / existing-session signatures">
- `Could not find DevToolsActivePort for chrome` → Chrome MCP の existing-session が、選択されたブラウザデータディレクトリにまだアタッチできませんでした。ブラウザの inspect ページを開き、リモートデバッグを有効にし、ブラウザを開いたままにして、最初のアタッチプロンプトを承認してから再試行してください。サインイン状態が不要な場合は、管理対象の `openclaw` プロファイルを優先してください。
- `No Chrome tabs found for profile="user"` → Chrome MCP のアタッチプロファイルに、開いているローカル Chrome タブがありません。
- `Remote CDP for profile "<name>" is not reachable` → 設定されたリモート CDP エンドポイントに Gateway ホストから到達できません。
- `Browser attachOnly is enabled ... not reachable` または `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only プロファイルに到達可能なターゲットがない、または HTTP エンドポイントは応答したものの CDP WebSocket を開けませんでした。
- `Browser attachOnly is enabled ... not reachable` または `Browser attachOnly is enabled and CDP websocket ... is not reachable` → アタッチ専用プロファイルに到達可能なターゲットがないか、HTTP エンドポイントは応答したものの CDP WebSocket を開けませんでした。
</Accordion>
<Accordion title="要素 / スクリーンショット / アップロードのシグネチャ">
- `fullPage is not supported for element screenshots` → スクリーンショットリクエストで `--full-page` と `--ref` または `--element` が混在しています。
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` のスクリーンショット呼び出しでは、CSS の `--element` ではなく、ページキャプチャまたはスナップショットの `--ref` を使用する必要があります。
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP のアップロードフックには、CSS セレクタではなくスナップショット ref が必要です。
- `existing-session file uploads currently support one file at a time.` → Chrome MCP プロファイルでは、1 回の呼び出しにつき 1 ファイルを送信してください。
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP プロファイルのダイアログフックはタイムアウトの上書きをサポートしていません。
- `existing-session type does not support timeoutMs overrides.` → `profile="user"` / Chrome MCP existing-session プロファイルで `act:type` を使う場合は `timeoutMs` を省略してください。カスタムタイムアウトが必要な場合は、管理対象/CDP ブラウザプロファイルを使用してください。
- `existing-session evaluate does not support timeoutMs overrides.` → `profile="user"` / Chrome MCP existing-session プロファイルで `act:evaluate` を使う場合は `timeoutMs` を省略してください。カスタムタイムアウトが必要な場合は、管理対象/CDP ブラウザプロファイルを使用してください。
- `response body is not supported for existing-session profiles yet.` → `responsebody` には、まだ管理対象ブラウザまたは raw CDP プロファイルが必要です。
- attach-only またはリモート CDP プロファイルでの古い viewport / dark-mode / locale / offline 上書き → Gateway 全体を再起動せずにアクティブな制御セッションを閉じ、Playwright/CDP エミュレーション状態を解放するには、`openclaw browser stop --browser-profile <name>` を実行します。
<Accordion title="Element / screenshot / upload signatures">
- `fullPage is not supported for element screenshots` → スクリーンショット要求で `--full-page` と `--ref` または `--element` が混在しています。
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` のスクリーンショット呼び出しでは、CSS `--element` ではなく、ページキャプチャまたはスナップショットの `--ref` を使用する必要があります。
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP のアップロードフックには、CSS セレクターではなくスナップショット ref が必要です。
- `existing-session file uploads currently support one file at a time.` → Chrome MCP プロファイルでは、1 回の呼び出しにつき 1 ファイルをアップロードしてください。
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP プロファイル上のダイアログフックはタイムアウトの上書きをサポートしていません。
- `existing-session type does not support timeoutMs overrides.` → `profile="user"` / Chrome MCP existing-session プロファイルの `act:type` では `timeoutMs` を省略するか、カスタムタイムアウトが必要な場合は管理対象/CDP ブラウザプロファイルを使用してください。
- `existing-session evaluate does not support timeoutMs overrides.` → `profile="user"` / Chrome MCP existing-session プロファイルの `act:evaluate` では `timeoutMs` を省略するか、カスタムタイムアウトが必要な場合は管理対象/CDP ブラウザプロファイルを使用してください。
- `response body is not supported for existing-session profiles yet.` → `responsebody` にはまだ管理対象ブラウザまたは raw CDP プロファイルが必要です。
- アタッチ専用またはリモート CDP プロファイルで viewport / dark-mode / locale / offline の上書きが古い → Gateway 全体を再起動せずに、`openclaw browser stop --browser-profile <name>` を実行してアクティブな制御セッションを閉じ、Playwright/CDP エミュレーション状態を解放してください。
</Accordion>
</AccordionGroup>
関連:
- [ブラウザ (OpenClaw 管理)](/ja-JP/tools/browser)
- [ブラウザ（OpenClaw 管理）](/ja-JP/tools/browser)
- [ブラウザのトラブルシューティング](/ja-JP/tools/browser-linux-troubleshooting)
## アップグレード後に突然何かが壊れた場合
## アップグレード後に何かが突然壊れた場合
アップグレード後の破損の多くは、設定のドリフト、またはより厳格なデフォルトが現在適用されていることが原因です。
アップグレード後の破損の多くは、設定のドリフト、または現在はより厳格なデフォルトが適用されていることが原因です。
<AccordionGroup>
<Accordion title="1. 認証と URL 上書きの動作が変更されました">
<Accordion title="1. Auth and URL override behavior changed">
```bash
openclaw gateway status
openclaw config get gateway.mode
@ -565,18 +566,18 @@ openclaw doctor
openclaw config get gateway.auth.mode
```
確認する内容:
確認すること:
- `gateway.mode=remote` の場合、ローカルサービスに問題がなくても CLI 呼び出しがリモートを対象にしている可能性があります。
- 明示的な `--url` 呼び出しは、保存済み資格情報にフォールバックしません。
- `gateway.mode=remote` の場合、ローカルサービスは正常でも CLI 呼び出しがリモートを対象にしている可能性があります。
- 明示的な `--url` 呼び出しは、保存済みの認証情報にフォールバックしません。
一般的なシグネチャ:
一般的な兆候:
- `gateway connect failed:` → URL ターゲットが誤っています。
- `unauthorized` → エンドポイントには到達できますが、認証が誤っています。
</Accordion>
<Accordion title="2. バインドと認証のガードレールがより厳格になりました">
<Accordion title="2. Bind and auth guardrails are stricter">
```bash
openclaw config get gateway.bind
openclaw config get gateway.auth.mode
@ -585,18 +586,18 @@ openclaw doctor
openclaw logs --follow
```
確認する内容:
確認すること:
- 非ループバックバインド (`lan`, `tailnet`, `custom`) には、有効な Gateway 認証パスが必要です。共有トークン/パスワード認証、または正しく設定された非ループバックの `trusted-proxy` デプロイです。
- `gateway.token` のような古いキーは `gateway.auth.token` の代わりにはなりません。
- 非ループバックバインド（`lan`、`tailnet`、`custom`）には、有効な Gateway 認証パスが必要です。共有トークン/パスワード認証、または正しく設定された非ループバックの `trusted-proxy` デプロイです。
- `gateway.token` のような古いキーは `gateway.auth.token` を置き換えません。
一般的なシグネチャ:
一般的な兆候:
- `refusing to bind gateway ... without auth` → 有効な Gateway 認証パスなしの非ループバックバインドです。
- ランタイムは実行中なのに `Connectivity probe: failed` → Gateway は生きていますが、現在の認証/URL ではアクセスできません。
- ランタイムが実行中なのに `Connectivity probe: failed` → Gateway は稼働していますが、現在の認証/URL ではアクセスできません。
</Accordion>
<Accordion title="3. ペアリングとデバイス ID の状態が変更されました">
<Accordion title="3. Pairing and device identity state changed">
```bash
openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
@ -604,12 +605,12 @@ openclaw doctor
openclaw doctor
```
確認する内容:
確認すること:
- ダッシュボード/Node の保留中のデバイス承認。
- ポリシーまたは ID 変更後の保留中の DM ペアリング承認。
- ダッシュボード/Node の保留中デバイス承認。
- ポリシーまたは ID 変更後の保留中 DM ペアリング承認。
一般的なシグネチャ:
一般的な兆候:
- `device identity required` → デバイス認証が満たされていません。
- `pairing required` → 送信者/デバイスを承認する必要があります。
@ -617,7 +618,7 @@ openclaw doctor
</Accordion>
</AccordionGroup>
確認後もサービス設定とランタイムがまだ一致しない場合は、同じプロファイル/状態ディレクトリからサービスメタデータを再インストールしてください。
確認後もサービス設定とランタイムが一致しない場合は、同じプロファイル/状態ディレクトリからサービスメタデータを再インストールします。
```bash
openclaw gateway install --force
@ -627,8 +628,8 @@ openclaw gateway restart
関連:
- [認証](/ja-JP/gateway/authentication)
- [バックグラウンド実行とプロセスツール](/ja-JP/gateway/background-process)
- [Gateway 所有のペアリング](/ja-JP/gateway/pairing)
- [バックグラウンド exec とプロセスツール](/ja-JP/gateway/background-process)
- [Gateway 管理のペアリング](/ja-JP/gateway/pairing)
## 関連

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

File diff suppressed because it is too large Load Diff

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

@ -1,135 +1,28 @@
---
read_when:
- バンドルされている Codex アプリサーバーハーネスを使用したい場合
- Codex ハーネス設定の例が必要です
- Codex のみのデプロイで、PI にフォールバックするのではなく失敗させたい場合
summary: バンドルされた Codex app-server ハーネスを通じて OpenClaw の埋め込みエージェントターンを実行する
- 同梱の Codex app-server ハーネスを使用したい場合
- Codex ハーネス設定例が必要です
- Codex のみのデプロイでは、PI にフォールバックするのではなく失敗するようにしたい
summary: 同梱の Codex app-server ハーネスを介して OpenClaw の組み込みエージェントターンを実行する
title: Codex ハーネス
x-i18n:
generated_at: "2026-04-30T20:05:45Z"
generated_at: "2026-05-01T05:02:10Z"
model: gpt-5.5
provider: openai
source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f
source_hash: 740e8fa9e6f4a737dfd250fe26b85865a7f7e40839b41e879e9224a45cbe8d72
source_path: plugins/codex-harness.md
workflow: 16
---
同梱の `codex` Plugin により、OpenClaw は組み込みの PI ハーネスではなく Codex app-server を通じて埋め込みエージェントターンを実行できます。
バンドルされた `codex` Plugin により、OpenClaw は組み込み PI ハーネスの代わりに Codex app-server を通じて埋め込みエージェントターンを実行できます。
低レベルのエージェントセッション、つまりモデル検出、ネイティブスレッドの再開、ネイティブ Compaction、app-server 実行を Codex に所有させたい場合に使用します。OpenClaw は引き続き、チャットチャネル、セッションファイル、モデル選択、ツール、承認、メディア配信、表示されるトランスクリプトミラーを所有します。
低レベルのエージェントセッションを Codex に所有させたい場合に使います。モデル検出、ネイティブスレッドの再開、ネイティブ Compaction、app-server 実行が対象です。OpenClaw は引き続き、チャットチャネル、セッションファイル、モデル選択、ツール、承認、メディア配信、表示されるトランスクリプトのミラーを所有します。
全体像を把握したい場合は、[エージェントランタイム](/ja-JP/concepts/agent-runtimes) から始めてください。短く言えば、`openai/gpt-5.5` はモデル参照、`codex` はランタイムであり、Telegram、Discord、Slack、または別のチャネルが通信サーフェスのままです。
方向性を把握したい場合は、[エージェントランタイム](/ja-JP/concepts/agent-runtimes) から始めてください。短く言うと、`openai/gpt-5.5` がモデル参照、`codex` がランタイムであり、Telegram、Discord、Slack、または別のチャネルが通信面のままです。
## この Plugin が変更すること
## クイック設定
同梱の `codex` Plugin は、複数の独立した機能を提供します。
| 機能 | 使い方 | 何をするか |
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| ネイティブ組み込みランタイム | `agentRuntime.id: "codex"` | Codex app-server を通じて OpenClaw の埋め込みエージェントターンを実行します。 |
| ネイティブチャット制御コマンド | `/codex bind`, `/codex resume`, `/codex steer`, ... | メッセージング会話から Codex app-server スレッドをバインドおよび制御します。 |
| Codex app-server プロバイダー/カタログ | `codex` 内部、ハーネス経由で公開 | ランタイムが app-server モデルを検出および検証できるようにします。 |
| Codex メディア理解パス | `codex/*` 画像モデル互換パス | 対応する画像理解モデル向けに境界付きの Codex app-server ターンを実行します。 |
| ネイティブフックリレー | Codex ネイティブイベント周辺の Plugin フック | 対応する Codex ネイティブのツール/完了イベントを OpenClaw が監視/ブロックできるようにします。 |
この Plugin を有効にすると、これらの機能が利用可能になります。次のことは**行いません**。
- すべての OpenAI モデルで Codex を使い始める
- `openai-codex/*` モデル参照をネイティブランタイムに変換する
- ACP/acpx をデフォルトの Codex パスにする
- すでに PI ランタイムを記録した既存セッションをホットスイッチする
- OpenClaw のチャネル配信、セッションファイル、認証プロファイル保存、またはメッセージルーティングを置き換える
同じ Plugin は、ネイティブの `/codex` チャット制御コマンドサーフェスも所有します。Plugin が有効で、ユーザーがチャットから Codex スレッドのバインド、再開、ステアリング、停止、または調査を求めた場合、エージェントは ACP よりも `/codex ...` を優先するべきです。ユーザーが ACP/acpx を求めている場合、または ACP Codex アダプターをテストしている場合、ACP は明示的なフォールバックのままです。
ネイティブ Codex ターンでは、OpenClaw Plugin フックが公開互換レイヤーとして維持されます。これらはプロセス内の OpenClaw フックであり、Codex の `hooks.json` コマンドフックではありません。
- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `before_tool_call`, `after_tool_call`
- `before_message_write`（ミラーされたトランスクリプトレコード用）
- Codex `Stop` リレーを通じた `before_agent_finalize`
- `agent_end`
Plugin は、ランタイム中立のツール結果ミドルウェアも登録でき、OpenClaw がツールを実行した後、結果が Codex に返される前に OpenClaw の動的ツール結果を書き換えられます。これは公開 `tool_result_persist` Plugin フックとは別のものです。このフックは、OpenClaw が所有するトランスクリプトのツール結果書き込みを変換します。
Plugin フックのセマンティクス自体については、[Plugin フック](/ja-JP/plugins/hooks) と [Plugin ガード動作](/ja-JP/tools/plugin) を参照してください。
ハーネスはデフォルトで無効です。新しい設定では、OpenAI モデル参照を `openai/gpt-*` として正規のまま維持し、ネイティブ app-server 実行が必要な場合は `agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を明示的に強制するべきです。レガシーの `codex/*` モデル参照は互換性のために引き続きハーネスを自動選択しますが、ランタイムに裏付けられたレガシープロバイダープレフィックスは通常のモデル/プロバイダー選択肢として表示されません。
`codex` Plugin が有効でも、プライマリモデルがまだ `openai-codex/*` の場合、`openclaw doctor` は経路を変更せずに警告します。これは意図的なものです。`openai-codex/*` は PI Codex OAuth/サブスクリプションパスのままであり、ネイティブ app-server 実行は明示的なランタイム選択のままです。
## ルートマップ
設定を変更する前に、この表を使用してください。
| 望ましい動作 | モデル参照 | ランタイム設定 | Plugin 要件 | 期待されるステータスラベル |
| --------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ |
| 通常の OpenClaw ランナー経由の OpenAI API | `openai/gpt-*` | 省略、または `runtime: "pi"` | OpenAI プロバイダー | `Runtime: OpenClaw Pi Default` |
| PI 経由の Codex OAuth/サブスクリプション | `openai-codex/gpt-*` | 省略、または `runtime: "pi"` | OpenAI Codex OAuth プロバイダー | `Runtime: OpenClaw Pi Default` |
| ネイティブ Codex app-server 組み込みターン | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` |
| 保守的な自動モードでの混在プロバイダー | プロバイダー固有の参照 | `agentRuntime.id: "auto"` | 任意の Plugin ランタイム | 選択されたランタイムに依存 |
| 明示的な Codex ACP アダプターセッション | ACP プロンプト/モデルに依存 | `sessions_spawn` with `runtime: "acp"` | 正常な `acpx` バックエンド | ACP タスク/セッションステータス |
重要な分離は、プロバイダーとランタイムの違いです。
- `openai-codex/*` は「PI はどのプロバイダー/認証経路を使用するべきか？」に答えます
- `agentRuntime.id: "codex"` は「この埋め込みターンをどのループで実行するべきか？」に答えます
- `/codex ...` は「このチャットはどのネイティブ Codex 会話をバインドまたは制御するべきか？」に答えます
- ACP は「acpx はどの外部ハーネスプロセスを起動するべきか？」に答えます
## 適切なモデルプレフィックスを選ぶ
OpenAI ファミリーのルートはプレフィックス固有です。PI 経由の Codex OAuth が必要な場合は `openai-codex/*` を使用し、直接の OpenAI API アクセスが必要な場合、またはネイティブ Codex app-server ハーネスを強制する場合は `openai/*` を使用します。
| モデル参照 | ランタイムパス | 使用する場合 |
| --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
| `openai/gpt-5.4` | OpenClaw/PI 配管経由の OpenAI プロバイダー | `OPENAI_API_KEY` による現在の直接 OpenAI Platform API アクセスが必要な場合。 |
| `openai-codex/gpt-5.5` | OpenClaw/PI 経由の OpenAI Codex OAuth | デフォルトの PI ランナーで ChatGPT/Codex サブスクリプション認証が必要な場合。 |
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server ハーネス | 埋め込みエージェントターンでネイティブ Codex app-server 実行が必要な場合。 |
GPT-5.5 は現在 OpenClaw ではサブスクリプション/OAuth のみです。PI OAuth には `openai-codex/gpt-5.5` を使用し、Codex app-server ハーネスには `openai/gpt-5.5` を使用してください。OpenAI が公開 API で GPT-5.5 を有効にすると、`openai/gpt-5.5` の直接 API キーアクセスがサポートされます。
レガシーの `codex/gpt-*` 参照は、互換エイリアスとして引き続き受け入れられます。Doctor の互換移行は、レガシーのプライマリランタイム参照を正規モデル参照に書き換え、ランタイムポリシーを別に記録します。一方で、フォールバック専用のレガシー参照は、ランタイムがエージェントコンテナ全体に対して設定されるため変更されません。新しい PI Codex OAuth 設定では `openai-codex/gpt-*` を使用し、新しいネイティブ app-server ハーネス設定では `openai/gpt-*` と `agentRuntime.id: "codex"` を組み合わせて使用してください。
`agents.defaults.imageModel` も同じプレフィックス分離に従います。画像理解を OpenAI Codex OAuth プロバイダーパス経由で実行する必要がある場合は `openai-codex/gpt-*` を使用してください。画像理解を境界付きの Codex app-server ターン経由で実行する必要がある場合は `codex/gpt-*` を使用してください。Codex app-server モデルは画像入力サポートを公開している必要があります。テキスト専用の Codex モデルは、メディアターンが開始する前に失敗します。
現在のセッションで有効なハーネスを確認するには `/status` を使用してください。選択が予想外の場合は、`agents/harness` サブシステムのデバッグログを有効にし、Gateway の構造化された `agent harness selected` レコードを調べてください。これには、選択されたハーネス ID、選択理由、ランタイム/フォールバックポリシー、および `auto` モードでは各 Plugin 候補のサポート結果が含まれます。
### doctor 警告の意味
`openclaw doctor` は、次のすべてが真の場合に警告します。
- 同梱の `codex` Plugin が有効、または許可されている
- エージェントのプライマリモデルが `openai-codex/*`
- そのエージェントの有効なランタイムが `codex` ではない
この警告が存在するのは、ユーザーがしばしば「Codex Plugin が有効」であれば「ネイティブ Codex app-server ランタイム」も意味すると期待するためです。OpenClaw はその飛躍を行いません。この警告の意味は次のとおりです。
- PI 経由の ChatGPT/Codex OAuth を意図していた場合、**変更は不要です**。
- ネイティブ app-server 実行を意図していた場合は、モデルを `openai/<model>` に変更し、`agentRuntime.id: "codex"` を設定してください。
- セッションランタイムピンは固定されるため、ランタイム変更後も既存セッションには `/new` または `/reset` が必要です。
ハーネス選択はライブセッション制御ではありません。埋め込みターンが実行されると、OpenClaw は選択されたハーネス ID をそのセッションに記録し、同じセッション ID の後続ターンでもそれを使用し続けます。将来のセッションで別のハーネスを使いたい場合は、`agentRuntime` 設定または `OPENCLAW_AGENT_RUNTIME` を変更してください。既存の会話を PI と Codex の間で切り替える前には、`/new` または `/reset` を使用して新しいセッションを開始してください。これにより、1 つのトランスクリプトを互換性のない 2 つのネイティブセッションシステムで再生することを避けられます。
ハーネスピン導入前に作成されたレガシーセッションは、トランスクリプト履歴があると PI ピン済みとして扱われます。設定を変更した後、その会話を Codex に参加させるには `/new` または `/reset` を使用してください。
`/status` は有効なモデルランタイムを表示します。デフォルトの PI ハーネスは `Runtime: OpenClaw Pi Default` と表示され、Codex app-server ハーネスは `Runtime: OpenAI Codex` と表示されます。
## 要件
- 同梱の `codex` Plugin が利用可能な OpenClaw。
- Codex app-server `0.125.0` 以降。同梱 Plugin はデフォルトで互換性のある Codex app-server バイナリを管理するため、`PATH` 上のローカル `codex` コマンドは通常のハーネス起動に影響しません。
- app-server プロセス、または OpenClaw の Codex 認証ブリッジで利用可能な Codex 認証。ローカルの app-server 起動は、各エージェント用の OpenClaw 管理 Codex ホームと分離された子 `HOME` を使用するため、デフォルトでは個人の `~/.codex` アカウント、Skills、Plugin、設定、スレッド状態、またはネイティブ `$HOME/.agents/skills` を読み取りません。
Plugin は、古い、またはバージョンなしの app-server ハンドシェイクをブロックします。これにより、OpenClaw はテスト済みのプロトコルサーフェス上に維持されます。
ライブおよび Docker スモークテストでは、認証は通常 Codex CLI アカウント、または OpenClaw の `openai-codex` 認証プロファイルから取得されます。ローカル stdio app-server 起動では、アカウントが存在しない場合に `CODEX_API_KEY` / `OPENAI_API_KEY` にフォールバックすることもできます。
## 最小設定
`openai/gpt-5.5` を使用し、同梱 Plugin を有効にして、`codex` ハーネスを強制します。
GPT エージェントターンに Codex ハーネスを使うには、モデル参照を `openai/gpt-*` として正規のままにし、バンドルされた `codex` Plugin を有効にして、`agentRuntime.id: "codex"` を設定します。
```json5
{
@ -145,13 +38,14 @@ Plugin は、古い、またはバージョンなしの app-server ハンドシ
model: "openai/gpt-5.5",
agentRuntime: {
id: "codex",
fallback: "none",
},
},
},
}
```
設定で `plugins.allow` を使用している場合は、そこにも `codex` を含めてください。
設定で `plugins.allow` を使っている場合は、そこにも `codex` を含めてください。
```json5
{
@ -166,17 +60,124 @@ Plugin は、古い、またはバージョンなしの app-server ハンドシ
}
```
`agents.defaults.model` またはエージェントモデルを `codex/<model>` に設定するレガシー設定では、引き続き同梱の `codex` Plugin が自動的に有効になります。新しい設定では、上記の明示的な `agentRuntime` エントリと組み合わせて `openai/<model>` を使用することを推奨します。
このパスでは `openai-codex/gpt-*` を使わないでください。ランタイムを別途強制しない限り、これは通常の PI ランナーを通じた Codex OAuth を選択します。設定変更は新規またはリセットされたセッションに適用されます。既存セッションは記録済みのランタイムを保持します。
## Codex を他のモデルと併用する
## この Plugin が変更する内容
同じエージェントが Codex と非 Codex プロバイダーモデルの間を自由に切り替える必要がある場合は、`agentRuntime.id: "codex"` をグローバルに設定しないでください。強制されたランタイムは、そのエージェントまたはセッションのすべての埋め込みターンに適用されます。そのランタイムが強制されている状態で Anthropic モデルを選択すると、OpenClaw は引き続き Codex ハーネスを試行し、そのターンを PI 経由で黙ってルーティングするのではなく、クローズドに失敗します。
バンドルされた `codex` Plugin は、複数の独立した機能を提供します。
| 機能 | 使い方 | 内容 |
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| ネイティブ埋め込みランタイム | `agentRuntime.id: "codex"` | OpenClaw の埋め込みエージェントターンを Codex app-server 経由で実行します。 |
| ネイティブチャット制御コマンド | `/codex bind`, `/codex resume`, `/codex steer`, ... | メッセージング会話から Codex app-server スレッドをバインドして制御します。 |
| Codex app-server プロバイダー/カタログ | `codex` 内部、ハーネス経由で公開 | ランタイムが app-server モデルを検出して検証できるようにします。 |
| Codex メディア理解パス | `codex/*` 画像モデル互換パス | 対応する画像理解モデル向けに、境界付き Codex app-server ターンを実行します。 |
| ネイティブフックリレー | Codex ネイティブイベント周辺の Plugin フック | OpenClaw が対応する Codex ネイティブのツール/終了イベントを観測またはブロックできるようにします。 |
Plugin を有効にすると、これらの機能が利用可能になります。これは次のことを**しません**。
- すべての OpenAI モデルで Codex を使い始める
- `openai-codex/*` モデル参照をネイティブランタイムに変換する
- ACP/acpx をデフォルトの Codex パスにする
- すでに PI ランタイムを記録した既存セッションをホットスイッチする
- OpenClaw のチャネル配信、セッションファイル、認証プロファイル保存、メッセージルーティングを置き換える
同じ Plugin は、ネイティブな `/codex` チャット制御コマンド面も所有します。Plugin が有効で、ユーザーがチャットから Codex スレッドのバインド、再開、誘導、停止、または検査を求めた場合、エージェントは ACP よりも `/codex ...` を優先するべきです。ユーザーが ACP/acpx を求めた場合、または ACP Codex アダプターをテストしている場合、ACP は明示的なフォールバックのままです。
ネイティブ Codex ターンは、公開互換レイヤーとして OpenClaw Plugin フックを保持します。これらはインプロセスの OpenClaw フックであり、Codex `hooks.json` コマンドフックではありません。
- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `before_tool_call`, `after_tool_call`
- `before_message_write`（ミラーされたトランスクリプトレコード用）
- Codex `Stop` リレーを通じた `before_agent_finalize`
- `agent_end`
Plugin は、ランタイム非依存のツール結果ミドルウェアも登録できます。これは、OpenClaw がツールを実行した後、結果が Codex に返される前に、OpenClaw の動的ツール結果を書き換えるためのものです。これは、OpenClaw が所有するトランスクリプトのツール結果書き込みを変換する公開 `tool_result_persist` Plugin フックとは別です。
Plugin フック自体のセマンティクスについては、[Plugin フック](/ja-JP/plugins/hooks) と [Plugin ガード動作](/ja-JP/tools/plugin) を参照してください。
ハーネスはデフォルトで無効です。新しい設定では、OpenAI モデル参照を `openai/gpt-*` として正規のままにし、ネイティブ app-server 実行が必要な場合に `agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を明示的に強制するべきです。互換性のため、レガシー `codex/*` モデル参照は引き続きハーネスを自動選択しますが、ランタイムに支えられたレガシープロバイダープレフィックスは通常のモデル/プロバイダー選択肢としては表示されません。
`codex` Plugin が有効でも、プライマリモデルがまだ `openai-codex/*` の場合、`openclaw doctor` はルートを変更せずに警告します。これは意図的です。`openai-codex/*` は PI Codex OAuth/サブスクリプションパスのままであり、ネイティブ app-server 実行は明示的なランタイム選択のままです。
## ルートマップ
設定を変更する前にこの表を使ってください。
| 望ましい動作 | モデル参照 | ランタイム設定 | Plugin 要件 | 期待されるステータスラベル |
| ------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ |
| 通常の OpenClaw ランナー経由の OpenAI API | `openai/gpt-*` | 省略、または `runtime: "pi"` | OpenAI プロバイダー | `Runtime: OpenClaw Pi Default` |
| PI 経由の Codex OAuth/サブスクリプション | `openai-codex/gpt-*` | 省略、または `runtime: "pi"` | OpenAI Codex OAuth プロバイダー | `Runtime: OpenClaw Pi Default` |
| ネイティブ Codex app-server 埋め込みターン | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` |
| 保守的な自動モードでの混在プロバイダー | プロバイダー固有の参照 | `agentRuntime.id: "auto"` | 任意の Plugin ランタイム | 選択されたランタイムに依存 |
| 明示的な Codex ACP アダプターセッション | ACP プロンプト/モデルに依存 | `runtime: "acp"` 付きの `sessions_spawn` | 正常な `acpx` バックエンド | ACP タスク/セッションステータス |
重要な分岐は、プロバイダーとランタイムの違いです。
- `openai-codex/*` は「PI はどのプロバイダー/認証ルートを使うべきか？」に答えます
- `agentRuntime.id: "codex"` は「この埋め込みターンをどのループで実行するべきか？」に答えます
- `/codex ...` は「このチャットはどのネイティブ Codex 会話にバインドまたは制御するべきか？」に答えます
- ACP は「acpx はどの外部ハーネスプロセスを起動するべきか？」に答えます
## 適切なモデルプレフィックスを選ぶ
OpenAI 系ルートはプレフィックス固有です。PI 経由で Codex OAuth を使いたい場合は `openai-codex/*` を使い、直接 OpenAI API アクセスが必要な場合、またはネイティブ Codex app-server ハーネスを強制している場合は `openai/*` を使います。
| モデル参照 | ランタイムパス | 使う場合 |
| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `openai/gpt-5.4` | OpenClaw/PI 配管経由の OpenAI プロバイダー | `OPENAI_API_KEY` による現在の直接 OpenAI Platform API アクセスが必要な場合。 |
| `openai-codex/gpt-5.5` | OpenClaw/PI 経由の OpenAI Codex OAuth | デフォルトの PI ランナーで ChatGPT/Codex サブスクリプション認証を使いたい場合。 |
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server ハーネス | 埋め込みエージェントターンにネイティブ Codex app-server 実行が必要な場合。 |
GPT-5.5 は現在、OpenClaw ではサブスクリプション/OAuth のみです。PI OAuth には `openai-codex/gpt-5.5` を使うか、Codex app-server ハーネスとともに `openai/gpt-5.5` を使ってください。OpenAI が公開 API で GPT-5.5 を有効にすると、`openai/gpt-5.5` への直接 API キーアクセスがサポートされます。
レガシー `codex/gpt-*` 参照は互換エイリアスとして引き続き受け付けられます。doctor 互換性移行は、レガシーのプライマリランタイム参照を正規モデル参照に書き換え、ランタイムポリシーを別途記録します。一方、フォールバック専用のレガシー参照は、ランタイムがエージェントコンテナ全体に対して設定されるため、変更されません。新しい PI Codex OAuth 設定では `openai-codex/gpt-*` を使うべきです。新しいネイティブ app-server ハーネス設定では、`openai/gpt-*` に加えて `agentRuntime.id: "codex"` を使うべきです。
`agents.defaults.imageModel` も同じプレフィックス分岐に従います。画像理解を OpenAI Codex OAuth プロバイダーパス経由で実行する場合は `openai-codex/gpt-*` を使います。画像理解を境界付き Codex app-server ターン経由で実行する場合は `codex/gpt-*` を使います。Codex app-server モデルは画像入力対応を広告している必要があります。テキスト専用 Codex モデルは、メディアターンが始まる前に失敗します。
現在のセッションで有効なハーネスを確認するには `/status` を使います。選択が予想外の場合は、`agents/harness` サブシステムのデバッグログを有効にし、Gateway の構造化された `agent harness selected` レコードを確認してください。これには、選択されたハーネス ID、選択理由、ランタイム/フォールバックポリシー、および `auto` モードでは各 Plugin 候補のサポート結果が含まれます。
### doctor 警告の意味
`openclaw doctor` は、次のすべてが真の場合に警告します。
- バンドルされた `codex` Plugin が有効または許可されている
- エージェントのプライマリモデルが `openai-codex/*` である
- そのエージェントの有効ランタイムが `codex` ではない
この警告が存在するのは、ユーザーが「Codex Plugin 有効」は「ネイティブ Codex app-server ランタイム」を意味すると期待しがちだからです。OpenClaw はその飛躍を行いません。この警告の意味は次のとおりです。
- PI 経由の ChatGPT/Codex OAuth を意図していた場合、**変更は不要です**。
- ネイティブ app-server 実行を意図していた場合は、モデルを `openai/<model>` に変更し、`agentRuntime.id: "codex"` を設定してください。
- ランタイム変更後も、既存セッションには `/new` または `/reset` が必要です。セッションランタイムのピン留めは固定的だからです。
ハーネス選択はライブセッション制御ではありません。埋め込みターンが実行されると、OpenClaw は選択されたハーネス ID をそのセッションに記録し、同じセッション ID 内の後続ターンでも使い続けます。将来のセッションで別のハーネスを使いたい場合は、`agentRuntime` 設定または `OPENCLAW_AGENT_RUNTIME` を変更してください。既存の会話を PI と Codex の間で切り替える前に、`/new` または `/reset` を使って新しいセッションを開始してください。これにより、1 つのトランスクリプトを互換性のない 2 つのネイティブセッションシステムに通すことを避けられます。
ハーネスのピン留め以前に作成されたレガシーセッションは、トランスクリプト履歴がある時点で PI にピン留めされたものとして扱われます。設定変更後にその会話を Codex に移行するには、`/new` または `/reset` を使ってください。
`/status` は有効なモデルランタイムを表示します。デフォルトの PI ハーネスは `Runtime: OpenClaw Pi Default` と表示され、Codex app-server ハーネスは `Runtime: OpenAI Codex` と表示されます。
## 要件
- バンドルされた `codex` Plugin が利用可能な OpenClaw。
- Codex app-server `0.125.0` 以降。バンドルされた Plugin はデフォルトで互換性のある Codex app-server バイナリを管理するため、`PATH` 上のローカル `codex` コマンドは通常のハーネス起動に影響しません。
- app-server プロセス、または OpenClaw の Codex 認証ブリッジから Codex 認証を利用できること。ローカル app-server 起動では、各エージェントごとに OpenClaw 管理の Codex ホームと分離された子 `HOME` を使うため、デフォルトでは個人の `~/.codex` アカウント、Skills、Plugin、設定、スレッド状態、またはネイティブ `$HOME/.agents/skills` を読み取りません。
Plugin は、古いまたはバージョン未指定の app-server ハンドシェイクをブロックします。これにより、OpenClaw はテスト済みのプロトコル面に留まります。
ライブおよび Docker スモークテストでは、認証は通常 Codex CLI アカウント、または OpenClaw の `openai-codex` 認証プロファイルから取得されます。ローカル stdio app-server 起動では、アカウントが存在しない場合に `CODEX_API_KEY` / `OPENAI_API_KEY` にフォールバックすることもできます。
## Codex を他のモデルと並べて追加する
同じエージェントが Codex と Codex 以外のプロバイダーモデルを自由に切り替える必要がある場合は、`agentRuntime.id: "codex"` をグローバルに設定しないでください。強制されたランタイムは、そのエージェントまたはセッションのすべての埋め込みターンに適用されます。そのランタイムが強制されている状態で Anthropic モデルを選択すると、OpenClaw はそれでも Codex ハーネスを試行し、そのターンを黙って PI 経由にルーティングするのではなく、失敗として閉じます。
代わりに、次のいずれかの形を使用してください。
- `agentRuntime.id: "codex"` を設定した専用エージェントに Codex を置く。
- 通常の混在プロバイダー利用では、デフォルトエージェントを `agentRuntime.id: "auto"` と PI フォールバックのままにする。
- レガシーの `codex/*` 参照は互換性のためだけに使用する。新しい設定では、`openai/*` と明示的な Codex ランタイムポリシーを優先する。
- Codex を `agentRuntime.id: "codex"` の専用エージェントに配置します。
- 通常の混在プロバイダー利用では、デフォルトエージェントを `agentRuntime.id: "auto"` と PI フォールバックのままにします。
- レガシーの `codex/*` 参照は互換性のためだけに使用します。新しい設定では、`openai/*` に加えて明示的な Codex ランタイムポリシーを優先してください。
たとえば、これはデフォルトエージェントを通常の自動選択のままにし、別の Codex エージェントを追加します。
@ -219,29 +220,29 @@ Plugin は、古い、またはバージョンなしの app-server ハンドシ
- デフォルトの `main` エージェントは、通常のプロバイダーパスと PI 互換フォールバックを使用します。
- `codex` エージェントは Codex app-server ハーネスを使用します。
- `codex` エージェントで Codex が見つからない、またはサポートされていない場合、そのターンは PI を静かに使うのではなく失敗します。
- `codex` エージェントで Codex が存在しないかサポートされていない場合、そのターンは静かに PI を使用するのではなく失敗します。
## エージェントコマンドのルーティング
エージェントは「Codex」という単語だけではなく、意図に基づいてユーザーリクエストをルーティングする必要があります。
エージェントは、単語「Codex」だけではなく、意図に基づいてユーザーリクエストをルーティングする必要があります。
| ユーザーの依頼... | エージェントが使用すべきもの... |
| ユーザーの依頼... | エージェントが使用すべきもの... |
| -------------------------------------------------------- | ------------------------------------------------ |
| 「このチャットを Codex にバインドして」 | `/codex bind` |
| 「Codex スレッド `<id>` をここで再開して」 | `/codex resume <id>` |
| 「Codex スレッドを表示して」 | `/codex threads` |
| 「問題のある Codex 実行についてサポートレポートを提出して」 | `/diagnostics [note]` |
| 「この添付スレッドについてのみ Codex フィードバックを送信して」 | `/codex diagnostics [note]` |
| 「このエージェントのランタイムとして Codex を使用して」 | `agentRuntime.id` への設定変更 |
| 「通常の OpenClaw で自分の ChatGPT/Codex サブスクリプションを使って」 | `openai-codex/*` モデル参照 |
| 「ACP/acpx 経由で Codex を実行して」 | ACP `sessions_spawn({ runtime: "acp", ... })` |
| 「スレッド内で Claude Code/Gemini/OpenCode/Cursor を開始して」 | `/codex` やネイティブサブエージェントではなく ACP/acpx |
| 「このチャットを Codex にバインドして」 | `/codex bind` |
| 「Codex スレッド `<id>` をここで再開して」 | `/codex resume <id>` |
| 「Codex スレッドを表示して」 | `/codex threads` |
| 「問題のある Codex 実行のサポートレポートを提出して」 | `/diagnostics [note]` |
| 「この添付スレッドについてだけ Codex フィードバックを送信して」 | `/codex diagnostics [note]` |
| 「このエージェントのランタイムに Codex を使用して」 | `agentRuntime.id` への設定変更 |
| 「通常の OpenClaw で自分の ChatGPT/Codex サブスクリプションを使用して」 | `openai-codex/*` モデル参照 |
| 「ACP/acpx 経由で Codex を実行して」 | ACP `sessions_spawn({ runtime: "acp", ... })` |
| 「Claude Code/Gemini/OpenCode/Cursor をスレッドで開始して」 | ACP/acpx。`/codex` でもネイティブサブエージェントでもありません |
OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれたランタイムバックエンドに支えられている場合にのみ、エージェントへ ACP spawn ガイダンスを提示します。ACP が利用できない場合、システムプロンプトと Plugin Skills はエージェントに ACP ルーティングを教えるべきではありません。
OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれたランタイムバックエンドに支えられている場合にのみ、ACP 生成ガイダンスをエージェントに提示します。ACP が利用できない場合、システムプロンプトと Plugin Skills は、ACP ルーティングについてエージェントに教えるべきではありません。
## Codex 専用デプロイ
すべての埋め込みエージェントターンが Codex を使用することを証明する必要がある場合は、Codex ハーネスを強制します。明示的な Plugin ランタイムはデフォルトで PI フォールバックなしになるため、`fallback: "none"` は任意ですが、ドキュメントとして有用なことがよくあります。
すべての埋め込みエージェントターンが Codex を使用することを証明する必要がある場合は、Codex ハーネスを強制します。明示的な Plugin ランタイムはデフォルトで PI フォールバックなしになるため、`fallback: "none"` は任意ですが、ドキュメントとして役立つことがよくあります。
```json5
{
@ -263,11 +264,11 @@ OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれ
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
```
Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app-server が古すぎる、または app-server を起動できない場合に早期に失敗します。ハーネス選択が見つからない場合に PI で処理させたいことを意図している場合にのみ、`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` を設定してください。
Codex が強制されている場合、Codex Plugin が無効、app-server が古すぎる、または app-server を起動できないと、OpenClaw は早期に失敗します。ハーネス選択ができない場合に PI に処理させたい意図がある場合にのみ、`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` を設定してください。
## エージェントごとの Codex
デフォルトエージェントは通常の自動選択を維持したまま、1 つのエージェントを Codex 専用にできます。
デフォルトエージェントは通常の自動選択を維持しながら、1 つのエージェントだけを Codex 専用にできます。
```json5
{
@ -298,11 +299,11 @@ Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app
}
```
エージェントとモデルの切り替えには通常のセッションコマンドを使用します。`/new` は新しい OpenClaw セッションを作成し、Codex ハーネスは必要に応じてサイドカー app-server スレッドを作成または再開します。`/reset` はそのスレッドの OpenClaw セッションバインディングをクリアし、次のターンで現在の設定からハーネスを再解決できるようにします。
エージェントとモデルを切り替えるには、通常のセッションコマンドを使用します。`/new` は新しい OpenClaw セッションを作成し、Codex ハーネスは必要に応じてサイドカーの app-server スレッドを作成または再開します。`/reset` はそのスレッドの OpenClaw セッションバインドをクリアし、次のターンで現在の設定からハーネスを再解決できるようにします。
## モデル検出
デフォルトでは、Codex Plugin は利用可能なモデルを app-server に問い合わせます。検出に失敗するかタイムアウトした場合、次のバンドル済みフォールバックカタログを使用します。
デフォルトでは、Codex Plugin は利用可能なモデルを app-server に問い合わせます。検出が失敗するかタイムアウトした場合、次のバンドル済みフォールバックカタログを使用します。
- GPT-5.5
- GPT-5.4 mini
@ -328,7 +329,7 @@ Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app
}
```
起動時に Codex のプローブを避け、フォールバックカタログに固定したい場合は検出を無効にします。
起動時に Codex へのプローブを避け、フォールバックカタログに固定したい場合は、検出を無効にします。
```json5
{
@ -347,7 +348,7 @@ Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app
}
```
## app-server の接続とポリシー
## app-server 接続とポリシー
デフォルトでは、Plugin は OpenClaw の管理対象 Codex バイナリをローカルで次のように起動します。
@ -355,9 +356,9 @@ Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app
codex app-server --listen stdio://
```
管理対象バイナリは、バンドル済み Plugin ランタイム依存関係として宣言され、残りの `codex` Plugin 依存関係とともにステージングされます。これにより、app-server のバージョンは、ローカルにインストールされている別の Codex CLI ではなく、バンドル済み Plugin に紐付けられます。別の実行可能ファイルを意図的に実行したい場合にのみ、`appServer.command` を設定してください。
管理対象バイナリは、バンドル済み Plugin ランタイム依存関係として宣言され、残りの `codex` Plugin 依存関係とともにステージングされます。これにより、app-server のバージョンは、ローカルにたまたまインストールされている別の Codex CLI ではなく、バンドル済み Plugin に結び付けられます。別の実行ファイルを意図的に実行したい場合にのみ、`appServer.command` を設定してください。
デフォルトでは、OpenClaw はローカル Codex ハーネスセッションを YOLO モードで開始します。`approvalPolicy: "never"`、`approvalsReviewer: "user"`、および `sandbox: "danger-full-access"` です。これは自律的な Heartbeat に使用される、信頼されたローカルオペレーターの姿勢です。Codex は、応答する人がいないネイティブ承認プロンプトで停止せずに、シェルとネットワークツールを使用できます。
デフォルトでは、OpenClaw はローカルの Codex ハーネスセッションを YOLO モードで開始します。`approvalPolicy: "never"`、`approvalsReviewer: "user"`、`sandbox: "danger-full-access"` です。これは自律 Heartbeat に使用される信頼済みローカルオペレーターの姿勢です。Codex は、応答する人がいないネイティブ承認プロンプトで停止せずに、シェルとネットワークツールを使用できます。
Codex のガーディアンレビュー付き承認を有効にするには、`appServer.mode:
"guardian"` を設定します。
@ -380,9 +381,9 @@ Codex のガーディアンレビュー付き承認を有効にするには、`a
}
```
Guardian モードは Codex のネイティブ自動レビュー承認パスを使用します。Codex が sandbox を離れる、ワークスペース外に書き込む、またはネットワークアクセスなどの権限を追加するよう求める場合、Codex はその承認リクエストを人間のプロンプトではなくネイティブレビュアーへルーティングします。レビュアーは Codex のリスクフレームワークを適用し、特定のリクエストを承認または拒否します。YOLO モードより多くのガードレールが欲しいが、無人エージェントを進行させる必要がある場合は Guardian を使用してください。
Guardian モードは、Codex のネイティブな自動レビュー承認パスを使用します。Codex がサンドボックスを離れる、ワークスペース外に書き込む、またはネットワークアクセスなどの権限を追加するよう求める場合、Codex はその承認リクエストを人間のプロンプトではなくネイティブレビュー担当にルーティングします。レビュー担当は Codex のリスクフレームワークを適用し、特定のリクエストを承認または拒否します。YOLO モードより多くのガードレールが必要だが、無人エージェントにも進捗が必要な場合は Guardian を使用してください。
`guardian` プリセットは、`approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"`、および `sandbox: "workspace-write"` に展開されます。個々のポリシーフィールドは引き続き `mode` を上書きするため、高度なデプロイではプリセットと明示的な選択を組み合わせることができます。古い `guardian_subagent` レビュアー値は互換エイリアスとして引き続き受け付けられますが、新しい設定では `auto_review` を使用する必要があります。
`guardian` プリセットは、`approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"`、`sandbox: "workspace-write"` に展開されます。個別のポリシーフィールドは引き続き `mode` を上書きするため、高度なデプロイではプリセットと明示的な選択を混在できます。以前の `guardian_subagent` レビュー担当値は互換エイリアスとして引き続き受け入れられますが、新しい設定では `auto_review` を使用してください。
すでに実行中の app-server には、WebSocket トランスポートを使用します。
@ -406,25 +407,24 @@ Guardian モードは Codex のネイティブ自動レビュー承認パスを
}
```
Stdio app-server の起動はデフォルトで OpenClaw のプロセス環境を継承しますが、OpenClaw は Codex app-server アカウントブリッジを所有し、`CODEX_HOME` と `HOME` の両方を、そのエージェントの OpenClaw 状態配下にあるエージェントごとのディレクトリに設定します。Codex 独自の skill ローダーは `$CODEX_HOME/skills` と `$HOME/.agents/skills` を読み取るため、ローカル app-server 起動では両方の値が分離されます。これにより、Codex ネイティブの Skills、Plugin、設定、アカウント、スレッド状態は、オペレーター個人の Codex CLI ホームから漏れ込むのではなく、OpenClaw エージェントにスコープされます。
Stdio app-server の起動は、デフォルトで OpenClaw のプロセス環境を継承しますが、OpenClaw は Codex app-server アカウントブリッジを所有し、`CODEX_HOME` と `HOME` の両方を、そのエージェントの OpenClaw 状態配下にあるエージェントごとのディレクトリに設定します。Codex 独自の Skills ローダーは `$CODEX_HOME/skills` と `$HOME/.agents/skills` を読み取るため、ローカル app-server 起動では両方の値が分離されます。これにより、Codex ネイティブの Skills、plugins、設定、アカウント、スレッド状態は、オペレーター個人の Codex CLI ホームから漏れ込むのではなく、OpenClaw エージェントにスコープされます。
OpenClaw Plugin と OpenClaw skill スナップショットは、引き続き OpenClaw 独自の Plugin レジストリと skill ローダーを通ります。個人の Codex CLI アセットは通りません。OpenClaw エージェントの一部にすべき有用な Codex CLI Skills や Plugin がある場合は、明示的に棚卸ししてください。
OpenClaw plugins と OpenClaw Skills スナップショットは、引き続き OpenClaw 独自の Plugin レジストリと Skills ローダーを通じて流れます。個人の Codex CLI アセットは流れません。OpenClaw エージェントの一部にすべき有用な Codex CLI Skills または plugins がある場合は、明示的にインベントリしてください。
```bash
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes
```
Codex 移行プロバイダーは Skills を現在の OpenClaw エージェントワークスペースへコピーします。Codex ネイティブの Plugin、フック、設定ファイルは、コマンドを実行したり、MCP サーバーを公開したり、資格情報を含んだりする可能性があるため、自動的に有効化されるのではなく、手動レビュー用に報告またはアーカイブされます。
Codex 移行プロバイダーは、Skills を現在の OpenClaw エージェントワークスペースにコピーします。Codex ネイティブ plugins、フック、設定ファイルは、コマンドを実行したり、MCP サーバーを公開したり、資格情報を保持したりする可能性があるため、自動的に有効化されるのではなく、手動レビュー用に報告またはアーカイブされます。
認証は次の順序で選択されます。
1. エージェント用の明示的な OpenClaw Codex 認証プロファイル。
2. そのエージェントの Codex ホーム内にある app-server の既存アカウント。
3. ローカル stdio app-server 起動のみで、app-server アカウントが存在せず OpenAI 認証が引き続き必要な場合、`CODEX_API_KEY`、次に
`OPENAI_API_KEY`。
1. そのエージェントの明示的な OpenClaw Codex 認証プロファイル。
2. そのエージェントの Codex ホームにある app-server の既存アカウント。
3. ローカル stdio app-server 起動の場合のみ、app-server アカウントが存在せず、OpenAI 認証がまだ必要な場合は、`CODEX_API_KEY`、次に `OPENAI_API_KEY`。
OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロファイルを検出すると、spawn される Codex 子プロセスから `CODEX_API_KEY` と `OPENAI_API_KEY` を削除します。これにより、Gateway レベルの API キーを埋め込みや直接の OpenAI モデルで利用可能にしたまま、ネイティブ Codex app-server ターンが誤って API 経由で課金されることを防ぎます。明示的な Codex API キープロファイルとローカル stdio 環境キーのフォールバックは、継承された子プロセス環境ではなく app-server ログインを使用します。WebSocket app-server 接続は Gateway 環境 API キーフォールバックを受け取りません。明示的な認証プロファイルまたはリモート app-server 独自のアカウントを使用してください。
OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロファイルを検出すると、生成される Codex 子プロセスから `CODEX_API_KEY` と `OPENAI_API_KEY` を削除します。これにより、Gateway レベルの API キーは埋め込みや直接の OpenAI モデルに利用可能なまま、ネイティブ Codex app-server ターンが誤って API 経由で課金されることを防ぎます。明示的な Codex API キープロファイルとローカル stdio 環境キーのフォールバックは、継承された子プロセス環境ではなく app-server ログインを使用します。WebSocket app-server 接続は Gateway 環境 API キーフォールバックを受け取りません。明示的な認証プロファイルまたはリモート app-server 独自のアカウントを使用してください。
デプロイで追加の環境分離が必要な場合は、それらの変数を `appServer.clearEnv` に追加します。
@ -445,40 +445,31 @@ OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロフ
}
```
`appServer.clearEnv` は spawn された Codex app-server 子プロセスにのみ影響します。
`appServer.clearEnv` は、生成された Codex app-server 子プロセスにのみ影響します。
サポートされている `appServer` フィールド:
サポートされる `appServer` フィールド:
| フィールド | デフォルト | 意味 |
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` は Codex を起動します。`"websocket"` は `url` に接続します。 |
| `command` | 管理対象の Codex バイナリ | stdio トランスポート用の実行ファイル。管理対象バイナリを使う場合は未設定のままにします。明示的に上書きする場合にのみ設定してください。 |
| `args` | `["app-server", "--listen", "stdio://"]` | stdio トランスポート用の引数。 |
| `url` | 未設定 | WebSocket app-server URL。 |
| `authToken` | 未設定 | WebSocket トランスポート用の Bearer トークン。 |
| `headers` | `{}` | 追加の WebSocket ヘッダー。 |
| `clearEnv` | `[]` | OpenClaw が継承環境を構築したあと、起動された stdio app-server プロセスから削除される追加の環境変数名。`CODEX_HOME` と `HOME` は、ローカル起動時の OpenClaw のエージェントごとの Codex 分離用に予約されています。 |
| `requestTimeoutMs` | `60000` | app-server コントロールプレーン呼び出しのタイムアウト。 |
| `mode` | `"yolo"` | YOLO または guardian レビュー付き実行のプリセット。 |
| `approvalPolicy` | `"never"` | スレッドの開始、再開、ターンに送信されるネイティブ Codex 承認ポリシー。 |
| `sandbox` | `"danger-full-access"` | スレッドの開始、再開に送信されるネイティブ Codex サンドボックスモード。 |
| `approvalsReviewer` | `"user"` | Codex にネイティブ承認プロンプトをレビューさせるには `"auto_review"` を使います。`guardian_subagent` は従来のエイリアスとして残っています。 |
| `serviceTier` | 未設定 | 任意の Codex app-server サービスティア: `"fast"`、`"flex"`、または `null`。無効な従来の値は無視されます。 |
| フィールド | デフォルト | 意味 |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transport` | `"stdio"` | `"stdio"` は Codex を起動し、`"websocket"` は `url` に接続します。 |
| `command` | 管理対象の Codex バイナリ | stdio トランスポート用の実行ファイルです。管理対象バイナリを使う場合は未設定のままにし、明示的に上書きする場合にのみ設定します。 |
| `args` | `["app-server", "--listen", "stdio://"]` | stdio トランスポート用の引数です。 |
| `url` | 未設定 | WebSocket app-server URL です。 |
| `authToken` | 未設定 | WebSocket トランスポート用の Bearer トークンです。 |
| `headers` | `{}` | 追加の WebSocket ヘッダーです。 |
| `clearEnv` | `[]` | OpenClaw が継承環境を構築した後、起動された stdio app-server プロセスから削除される追加の環境変数名です。`CODEX_HOME` と `HOME` は、ローカル起動時の OpenClaw のエージェントごとの Codex 分離用に予約されています。 |
| `requestTimeoutMs` | `60000` | app-server コントロールプレーン呼び出しのタイムアウトです。 |
| `mode` | `"yolo"` | YOLO または guardian レビュー付き実行のプリセットです。 |
| `approvalPolicy` | `"never"` | thread start/resume/turn に送信されるネイティブ Codex 承認ポリシーです。 |
| `sandbox` | `"danger-full-access"` | thread start/resume に送信されるネイティブ Codex サンドボックスモードです。 |
| `approvalsReviewer` | `"user"` | Codex にネイティブ承認プロンプトをレビューさせるには `"auto_review"` を使います。`guardian_subagent` は従来のエイリアスのままです。 |
| `serviceTier` | 未設定 | 任意の Codex app-server サービスティアです: `"fast"`、`"flex"`、または `null`。無効な従来値は無視されます。 |
OpenClaw が所有する動的ツール呼び出しは、`appServer.requestTimeoutMs` とは
独立して制限されます。各 Codex `item/tool/call` リクエストは、30 秒以内に
OpenClaw のレスポンスを受け取る必要があります。タイムアウト時、OpenClaw は対応している場合にツール
シグナルを中止し、失敗した動的ツールレスポンスを Codex に返すため、
セッションを `processing` のまま残す代わりにターンを続行できます。
OpenClaw 所有の動的ツール呼び出しは、`appServer.requestTimeoutMs` とは独立して制限されます。各 Codex `item/tool/call` リクエストは、30 秒以内に OpenClaw の応答を受け取る必要があります。タイムアウト時、OpenClaw はサポートされている場合はツールシグナルを中止し、失敗した動的ツール応答を Codex に返すため、セッションを `processing` のまま残す代わりにターンを継続できます。
OpenClaw が Codex のターンスコープ app-server リクエストに応答したあと、ハーネスは
Codex がネイティブターンを `turn/completed` で完了することも期待します。その
応答後に app-server が 60 秒間無応答になった場合、OpenClaw はベストエフォートで
Codex ターンに割り込み、診断タイムアウトを記録し、
OpenClaw セッションレーンを解放して、後続のチャットメッセージが古い
ネイティブターンの背後にキューされないようにします。
OpenClaw が Codex のターンスコープ app-server リクエストに応答した後、ハーネスは Codex がネイティブターンを `turn/completed` で終了することも期待します。その応答後に app-server が 60 秒間沈黙した場合、OpenClaw はベストエフォートで Codex ターンを中断し、診断タイムアウトを記録し、OpenClaw セッションレーンを解放して、後続のチャットメッセージが古いネイティブターンの後ろにキューされないようにします。
ローカルテストでは環境による上書きが引き続き利用できます。
ローカルテストでは環境オーバーライドを引き続き利用できます。
- `OPENCLAW_CODEX_APP_SERVER_BIN`
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
@ -486,29 +477,18 @@ OpenClaw セッションレーンを解放して、後続のチャットメッ
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
`OPENCLAW_CODEX_APP_SERVER_BIN` は、`appServer.command` が未設定の場合に
管理対象バイナリをバイパスします。
`OPENCLAW_CODEX_APP_SERVER_BIN` は、`appServer.command` が未設定の場合に管理対象バイナリをバイパスします。
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` は削除されました。代わりに
`plugins.entries.codex.config.appServer.mode: "guardian"` を使うか、
一回限りのローカルテストでは `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` を使います。繰り返し可能なデプロイでは、
Codex ハーネス設定の他の部分と同じレビュー済みファイルに Plugin の動作を保持できるため、
設定を使うことが推奨されます。
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` は削除されました。代わりに `plugins.entries.codex.config.appServer.mode: "guardian"` を使うか、1 回限りのローカルテストには `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` を使ってください。再現可能なデプロイでは、Plugin の動作が Codex ハーネス設定の残り部分と同じレビュー対象ファイルに保たれるため、設定を使うことを推奨します。
## コンピューター使用
Computer Use は専用のセットアップガイドで扱います:
[Codex Computer Use](/ja-JP/plugins/codex-computer-use)。
コンピューター使用は専用のセットアップガイドで説明しています:
[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use)。
短く言えば、OpenClaw はデスクトップ制御アプリをベンダー提供せず、デスクトップ操作も
自ら実行しません。OpenClaw は Codex app-server を準備し、
`computer-use` MCP サーバーが利用可能であることを検証してから、Codex モードのターン中に
ネイティブ MCP ツール呼び出しを Codex に処理させます。
要約すると、OpenClaw はデスクトップ制御アプリをベンダー化せず、デスクトップ操作自体も実行しません。Codex app-server を準備し、`computer-use` MCP サーバーが利用可能であることを確認してから、Codex モードのターン中に Codex がネイティブ MCP ツール呼び出しを処理できるようにします。
Codex marketplace フロー外で TryCua ドライバーに直接アクセスするには、
`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` で
`cua-driver mcp` を登録します。Codex が所有する Computer Use と直接 MCP 登録の違いについては、
[Codex Computer Use](/ja-JP/plugins/codex-computer-use) を参照してください。
Codex マーケットプレイスフローの外で TryCua ドライバーへ直接アクセスするには、`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` で `cua-driver mcp` を登録します。Codex 所有のコンピューター使用と直接 MCP 登録の違いについては、[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use)を参照してください。
最小設定:
@ -538,28 +518,18 @@ Codex marketplace フロー外で TryCua ドライバーに直接アクセスす
}
```
セットアップはコマンド面から確認またはインストールできます。
セットアップはコマンドサーフェスから確認またはインストールできます。
- `/codex computer-use status`
- `/codex computer-use install`
- `/codex computer-use install --source <marketplace-source>`
- `/codex computer-use install --marketplace-path <path>`
Computer Use は macOS 固有で、Codex MCP サーバーがアプリを制御できるようになる前に
ローカル OS 権限が必要になる場合があります。`computerUse.enabled` が true で MCP
サーバーが利用できない場合、Codex モードのターンは、ネイティブ Computer Use ツールなしで
黙って実行されるのではなく、スレッド開始前に失敗します。marketplace の選択肢、
リモートカタログの制限、ステータス理由、トラブルシューティングについては
[Codex Computer Use](/ja-JP/plugins/codex-computer-use) を参照してください。
コンピューター使用は macOS 固有であり、Codex MCP サーバーがアプリを制御できるようになる前に、ローカル OS 権限が必要になる場合があります。`computerUse.enabled` が true で MCP サーバーが利用できない場合、Codex モードのターンは、ネイティブのコンピューター使用ツールなしで密かに実行されるのではなく、スレッド開始前に失敗します。マーケットプレイスの選択肢、リモートカタログの制限、ステータス理由、トラブルシューティングについては、[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use)を参照してください。
`computerUse.autoInstall` が true の場合、Codex がまだローカル marketplace を検出していなければ、
OpenClaw は
`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` から標準の
バンドル済み Codex Desktop marketplace を登録できます。ランタイムまたは Computer Use 設定を変更したあとは、
既存のセッションが古い PI または Codex スレッドバインディングを保持しないように、
`/new` または `/reset` を使います。
`computerUse.autoInstall` が true の場合、Codex がまだローカルマーケットプレイスを検出していなければ、OpenClaw は `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` から標準のバンドル版 Codex Desktop マーケットプレイスを登録できます。ランタイムまたはコンピューター使用設定を変更した後は、既存セッションが古い PI または Codex スレッドバインディングを保持しないように、`/new` または `/reset` を使ってください。
## 一般的なレシピ
## よく使うレシピ
デフォルトの stdio トランスポートを使うローカル Codex:
@ -575,7 +545,7 @@ OpenClaw は
}
```
Codex 専用ハーネス検証:
Codex のみのハーネス検証:
```json5
{
@ -619,7 +589,7 @@ guardian レビュー付き Codex 承認:
}
```
明示的なヘッダーを持つリモート app-server:
明示的なヘッダーを使うリモート app-server:
```json5
{
@ -642,58 +612,45 @@ guardian レビュー付き Codex 承認:
}
```
モデル切り替えは OpenClaw が制御したままです。OpenClaw セッションが
既存の Codex スレッドにアタッチされている場合、次のターンは現在選択されている
OpenAI モデル、プロバイダー、承認ポリシー、サンドボックス、サービスティアを
app-server に再送信します。`openai/gpt-5.5` から `openai/gpt-5.2` に切り替えると、
スレッドバインディングは保持されますが、新しく選択されたモデルで続行するよう Codex に要求します。
モデル切り替えは OpenClaw 側で制御されます。OpenClaw セッションが既存の Codex スレッドにアタッチされている場合、次のターンで現在選択されている OpenAI モデル、プロバイダー、承認ポリシー、サンドボックス、サービスティアが再度 app-server に送信されます。`openai/gpt-5.5` から `openai/gpt-5.2` に切り替えると、スレッドバインディングは維持されますが、新しく選択されたモデルで続行するよう Codex に要求します。
## Codex コマンド
バンドルされた Plugin は、`/codex` を承認済みスラッシュコマンドとして登録します。これは
汎用であり、OpenClaw テキストコマンドに対応する任意のチャンネルで動作します。
バンドルされた Plugin は、認可済みスラッシュコマンドとして `/codex` を登録します。これは汎用であり、OpenClaw テキストコマンドをサポートする任意のチャンネルで動作します。
一般的な形式:
- `/codex status` は、ライブ app-server 接続性、モデル、アカウント、レート制限、MCP サーバー、Skills を表示します。
- `/codex status` は、ライブ app-server 接続、モデル、アカウント、レート制限、MCP サーバー、Skills を表示します。
- `/codex models` は、ライブ Codex app-server モデルを一覧表示します。
- `/codex threads [filter]` は、最近の Codex スレッドを一覧表示します。
- `/codex resume <thread-id>` は、現在の OpenClaw セッションを既存の Codex スレッドにアタッチします。
- `/codex compact` は、アタッチされたスレッドを compact するよう Codex app-server に依頼します。
- `/codex review` は、アタッチされたスレッドの Codex ネイティブレビューを開始します。
- `/codex compact` は、アタッチされたスレッドをコンパクト化するよう Codex app-server に要求します。
- `/codex review` は、アタッチされたスレッドに対して Codex ネイティブレビューを開始します。
- `/codex diagnostics [note]` は、アタッチされたスレッドの Codex 診断フィードバックを送信する前に確認します。
- `/codex computer-use status` は、設定済みの Computer Use Plugin と MCP サーバーを確認します。
- `/codex computer-use install` は、設定済みの Computer Use Plugin をインストールし、MCP サーバーをリロードします。
- `/codex computer-use status` は、設定済みのコンピューター使用 Plugin と MCP サーバーを確認します。
- `/codex computer-use install` は、設定済みのコンピューター使用 Plugin をインストールし、MCP サーバーを再読み込みします。
- `/codex account` は、アカウントとレート制限のステータスを表示します。
- `/codex mcp` は、Codex app-server MCP サーバーのステータスを一覧表示します。
- `/codex skills` は、Codex app-server skills を一覧表示します。
- `/codex skills` は、Codex app-server の Skills を一覧表示します。
### 一般的なデバッグワークフロー
Codex ベースのエージェントが Telegram、Discord、Slack、
または別のチャンネルで予想外の動作をした場合は、問題が発生した会話から開始します。
Codex バックエンドのエージェントが Telegram、Discord、Slack、または別のチャンネルで予期しない動作をした場合は、問題が発生した会話から始めます。
1. 見た内容を説明する `/diagnostics bad tool choice after image upload` または別の短いメモを実行します。
2. 診断リクエストを一度承認します。この承認によりローカル Gateway
診断 zip が作成され、セッションが Codex ハーネスを使用しているため、
関連する Codex フィードバックバンドルも OpenAI サーバーに送信されます。
3. 完了した診断返信をバグレポートまたはサポートスレッドにコピーします。
そこには、ローカルバンドルパス、プライバシー概要、OpenClaw セッション ID、
Codex スレッド ID、および各 Codex スレッドの `Inspect locally` 行が含まれます。
4. 自分で実行をデバッグしたい場合は、表示された `Inspect locally`
コマンドをターミナルで実行します。これは `codex resume <thread-id>` のような形で、
ネイティブ Codex スレッドを開くため、会話を調査したり、ローカルで続行したり、
Codex が特定のツールや計画を選んだ理由を Codex に尋ねたりできます。
1. `/diagnostics bad tool choice after image upload`、または見た内容を説明する別の短いメモを実行します。
2. 診断リクエストを一度承認します。この承認により、ローカル Gateway 診断 zip が作成され、セッションが Codex ハーネスを使用しているため、関連する Codex フィードバックバンドルも OpenAI サーバーに送信されます。
3. 完了した診断返信をバグレポートまたはサポートスレッドにコピーします。これには、ローカルバンドルパス、プライバシー概要、OpenClaw セッション ID、Codex スレッド ID、および各 Codex スレッドの `Inspect locally` 行が含まれます。
4. 実行を自分でデバッグしたい場合は、表示された `Inspect locally` コマンドをターミナルで実行します。これは `codex resume <thread-id>` のような形式で、ネイティブ Codex スレッドを開くため、会話を調査したり、ローカルで続行したり、特定のツールや計画を選んだ理由を Codex に尋ねたりできます。
`/codex diagnostics [note]` は、OpenClaw Gateway 診断バンドル全体なしで、現在アタッチされているスレッドの Codex フィードバックアップロードだけを明示的に必要とする場合にのみ使用します。ほとんどのサポートレポートでは、`/diagnostics [note]` のほうが適切な開始点です。これは、ローカル Gateway の状態と Codex スレッド ID を 1 つの返信で結び付けるためです。完全なプライバシーモデルとグループチャットの動作については、[診断エクスポート](/ja-JP/gateway/diagnostics)を参照してください。
`/codex diagnostics [note]` は、完全な OpenClaw Gateway 診断バンドルではなく、現在添付されているスレッドの Codex フィードバックアップロードだけが特に必要な場合にのみ使用します。ほとんどのサポート報告では、`/diagnostics [note]` の方が出発点として適しています。これは、ローカル Gateway の状態と Codex スレッド ID を 1 つの返信で結び付けるためです。完全なプライバシーモデルとグループチャットでの動作については、[診断エクスポート](/ja-JP/gateway/diagnostics)を参照してください。
Core OpenClaw は、一般的な Gateway 診断コマンドとして、オーナー専用の `/diagnostics [note]` も公開しています。その承認プロンプトには機微データに関する前文が表示され、[診断エクスポート](/ja-JP/gateway/diagnostics)へのリンクがあり、毎回、明示的な exec 承認を通じて `openclaw gateway diagnostics export --json` を要求します。allow-all ルールで診断を承認しないでください。承認後、OpenClaw はローカルバンドルパスとマニフェスト概要を含む貼り付け可能なレポートを送信します。アクティブな OpenClaw セッションが Codex ハーネスを使用している場合、同じ承認により、関連する Codex フィードバックバンドルを OpenAI サーバーへ送信することも許可されます。承認プロンプトには Codex フィードバックが送信されることが記載されますが、承認前に Codex セッション ID やスレッド ID は表示されません。
Core OpenClaw は、一般的な Gateway 診断コマンドとして、所有者専用の `/diagnostics [note]` も公開しています。その承認プロンプトには、機密データに関する前置きが表示され、[診断エクスポート](/ja-JP/gateway/diagnostics)へのリンクが示され、毎回明示的な exec 承認を通じて `openclaw gateway diagnostics export --json` を要求します。allow-all ルールで診断を承認しないでください。承認後、OpenClaw はローカルバンドルのパスとマニフェストの概要を含む、貼り付け可能なレポートを送信します。アクティブな OpenClaw セッションが Codex ハーネスを使用している場合、その同じ承認により、関連する Codex フィードバックバンドルを OpenAI サーバーへ送信することも許可されます。承認プロンプトには Codex フィードバックが送信されることが示されますが、承認前に Codex セッション ID やスレッド ID は列挙されません。
グループチャットでオーナーが `/diagnostics` を呼び出した場合、OpenClaw は共有チャンネルをクリーンに保ちます。グループには短い通知だけが届き、診断の前文、承認プロンプト、Codex セッション/スレッド ID はプライベート承認ルートを通じてオーナーに送信されます。プライベートなオーナールートがない場合、OpenClaw はグループでの要求を拒否し、DM から実行するようオーナーに求めます。
グループチャットで所有者が `/diagnostics` を呼び出した場合、OpenClaw は共有チャンネルをクリーンに保ちます。グループには短い通知だけが届き、診断の前置き、承認プロンプト、Codex セッション ID/スレッド ID は、非公開の承認ルートを通じて所有者に送信されます。非公開の所有者ルートがない場合、OpenClaw はグループからの要求を拒否し、所有者に DM から実行するよう求めます。
承認された Codex アップロードは、Codex app-server の `feedback/upload` を呼び出し、一覧に含まれる各スレッドと、利用可能な場合は生成された Codex サブスレッドのログを含めるよう app-server に要求します。アップロードは Codex の通常のフィードバック経路を通じて OpenAI サーバーへ送信されます。その app-server で Codex フィードバックが無効になっている場合、コマンドは app-server エラーを返します。完了した診断返信には、送信されたスレッドについて、チャンネル、OpenClaw セッション ID、Codex スレッド ID、ローカルの `codex resume <thread-id>` コマンドが一覧表示されます。承認を拒否または無視した場合、OpenClaw はそれらの Codex ID を出力しません。このアップロードは、ローカル Gateway 診断エクスポートの代替ではありません。
承認された Codex アップロードは Codex app-server の `feedback/upload` を呼び出し、利用可能な場合は、列挙された各スレッドと生成された Codex サブスレッドのログを含めるよう app-server に要求します。アップロードは Codex の通常のフィードバック経路を通じて OpenAI サーバーへ送信されます。その app-server で Codex フィードバックが無効になっている場合、コマンドは app-server エラーを返します。完了した診断返信には、送信されたスレッドについて、チャンネル、OpenClaw セッション ID、Codex スレッド ID、およびローカルの `codex resume <thread-id>` コマンドが列挙されます。承認を拒否または無視した場合、OpenClaw はそれらの Codex ID を出力しません。このアップロードは、ローカル Gateway 診断エクスポートを置き換えるものではありません。
`/codex resume` は、通常のターンでハーネスが使用するものと同じサイドカー束縛ファイルを書き込みます。次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw モデルを app-server に渡し、拡張履歴を有効に保ちます。
`/codex resume` は、ハーネスが通常のターンで使用するものと同じサイドカーのバインディングファイルを書き込みます。次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw モデルを app-server に渡し、拡張履歴を有効なままにします。
### CLI から Codex スレッドを調査する
@ -703,96 +660,96 @@ Core OpenClaw は、一般的な Gateway 診断コマンドとして、オーナ
codex resume <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 app-server スレッドについては `/codex threads [filter]` からスレッド ID を取得し、同じ `codex resume` コマンドをシェルで実行することもできます。
このコマンドサーフェスには Codex app-server `0.125.0` 以降が必要です。将来の app-server またはカスタム app-server がその JSON-RPC メソッドを公開していない場合、個々の制御メソッドは `unsupported by this Codex app-server` と報告されます。
このコマンドサーフェスには Codex app-server `0.125.0` 以降が必要です。将来の app-server またはカスタム app-server がその JSON-RPC メソッドを公開していない場合、個々の制御メソッドは `unsupported by this Codex app-server` として報告されます。
## フック境界
Codex ハーネスには 3 つのフック層があります。
| 層 | オーナー | 目的 |
| レイヤー | 所有者 | 目的 |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| OpenClaw Plugin フック | OpenClaw | PI と Codex ハーネス全体での製品/Plugin 互換性。 |
| Codex app-server 拡張ミドルウェア | OpenClaw バンドル Plugin | OpenClaw 動的ツール周辺のターンごとのアダプター動作。 |
| OpenClaw Plugin フック | OpenClaw | PI と Codex ハーネス全体での製品/Plugin 互換性。 |
| Codex app-server 拡張ミドルウェア | OpenClaw 同梱 Plugin | OpenClaw 動的ツール周辺のターンごとのアダプター動作。 |
| Codex ネイティブフック | Codex | Codex 設定からの低レベル Codex ライフサイクルとネイティブツールポリシー。 |
OpenClaw は、OpenClaw Plugin の動作をルーティングするために、プロジェクトまたはグローバルの Codex `hooks.json` ファイルを使用しません。サポートされるネイティブツールと権限ブリッジについて、OpenClaw は `PreToolUse`、`PostToolUse`、`PermissionRequest`、`Stop` 用に、スレッドごとの Codex 設定を注入します。`SessionStart` や `UserPromptSubmit` などの他の Codex フックは Codex レベルの制御のままです。これらは v1 契約では OpenClaw Plugin フックとして公開されません。
OpenClaw は、OpenClaw Plugin の動作をルーティングするために、プロジェクトまたはグローバルの Codex `hooks.json` ファイルを使用しません。サポートされているネイティブツールと権限ブリッジについて、OpenClaw は `PreToolUse`、`PostToolUse`、`PermissionRequest`、`Stop` 用のスレッドごとの Codex 設定を注入します。`SessionStart` や `UserPromptSubmit` などの他の Codex フックは Codex レベルの制御のままであり、v1 コントラクトでは OpenClaw Plugin フックとして公開されません。
OpenClaw 動的ツールでは、Codex が呼び出しを要求した後に OpenClaw がツールを実行するため、OpenClaw は自分が所有する Plugin とミドルウェアの動作をハーネスアダプター内で発火します。Codex ネイティブツールでは、Codex が正規のツールレコードを所有します。OpenClaw は選択されたイベントをミラーできますが、Codex が app-server またはネイティブフックコールバックを通じてその操作を公開しない限り、ネイティブ Codex スレッドを書き換えることはできません。
OpenClaw 動的ツールの場合、Codex が呼び出しを要求した後に OpenClaw がツールを実行するため、OpenClaw はハーネスアダプター内で、自身が所有する Plugin とミドルウェアの動作を発火します。Codex ネイティブツールの場合、Codex が正規のツールレコードを所有します。OpenClaw は選択されたイベントをミラーできますが、Codex が app-server またはネイティブフックコールバックを通じてその操作を公開しない限り、ネイティブ Codex スレッドを書き換えることはできません。
Compaction と LLM ライフサイクル投影は、ネイティブ Codex フックコマンドではなく、Codex app-server 通知と OpenClaw アダプター状態から得られます。OpenClaw の `before_compaction`、`after_compaction`、`llm_input`、`llm_output` イベントはアダプターレベルの観測であり、Codex の内部リクエストや Compaction ペイロードをバイト単位で取得したものではありません。
Compaction と LLM ライフサイクルの投影は、ネイティブ Codex フックコマンドではなく、Codex app-server 通知と OpenClaw アダプター状態から来ます。OpenClaw の `before_compaction`、`after_compaction`、`llm_input`、`llm_output` イベントはアダプターレベルの観測であり、Codex の内部リクエストや Compaction ペイロードをバイト単位で取得したものではありません。
Codex ネイティブの `hook/started` および `hook/completed` app-server 通知は、軌跡とデバッグ用に `codex_app_server.hook` エージェントイベントとして投影されます。これらは OpenClaw Plugin フックを呼び出しません。
Codex ネイティブの `hook/started` および `hook/completed` app-server 通知は、軌跡とデバッグのために `codex_app_server.hook` エージェントイベントとして投影されます。これらは OpenClaw Plugin フックを呼び出しません。
## V1 サポート契約
## V1 サポートコントラクト
Codex モードは、下層のモデル呼び出しだけが異なる PI ではありません。Codex はネイティブモデルループのより多くを所有し、OpenClaw はその境界に合わせて Plugin とセッションのサーフェスを適応させます。
Codex モードは、内部のモデル呼び出しを変えた PI ではありません。Codex はネイティブモデルループのより多くを所有し、OpenClaw はその境界に合わせて Plugin とセッションのサーフェスを適応させます。
Codex runtime v1 でサポートされるもの:
Codex ランタイム v1 でサポートされるもの:
| サーフェス | サポート | 理由 |
| サーフェス | サポート | 理由 |
| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Codex 経由の OpenAI モデルループ | サポート | Codex app-server が OpenAI ターン、ネイティブスレッド再開、ネイティブツール継続を所有します。 |
| OpenClaw チャンネルルーティングと配信 | サポート | Telegram、Discord、Slack、WhatsApp、iMessage、その他のチャンネルはモデル runtime の外側に残ります。 |
| OpenClaw 動的ツール | サポート | Codex は OpenClaw にこれらのツールの実行を依頼するため、OpenClaw は実行経路内に残ります。 |
| プロンプトとコンテキスト Plugin | サポート | OpenClaw はプロンプトオーバーレイを構築し、スレッドの開始または再開前にコンテキストを Codex ターンへ投影します。 |
| コンテキストエンジンライフサイクル | サポート | Codex ターンでは、組み立て、取り込みまたはターン後メンテナンス、コンテキストエンジン Compaction 調整が実行されます。 |
| 動的ツールフック | サポート | `before_tool_call`、`after_tool_call`、ツール結果ミドルウェアは、OpenClaw 所有の動的ツールの周辺で実行されます。 |
| ライフサイクルフック | アダプター観測としてサポート | `llm_input`、`llm_output`、`agent_end`、`before_compaction`、`after_compaction` は、正直な Codex モードペイロードで発火します。 |
| 最終回答修正ゲート | ネイティブフックリレーを通じてサポート | Codex `Stop` は `before_agent_finalize` にリレーされます。`revise` は最終化前にもう 1 回のモデルパスを Codex に要求します。 |
| ネイティブシェル、パッチ、MCP のブロックまたは観測 | ネイティブフックリレーを通じてサポート | Codex `PreToolUse` と `PostToolUse` は、Codex app-server `0.125.0` 以降での MCP ペイロードを含め、確定済みのネイティブツールサーフェスに対してリレーされます。ブロックはサポートされますが、引数の書き換えはサポートされません。 |
| ネイティブ権限ポリシー | ネイティブフックリレーを通じてサポート | Codex `PermissionRequest` は、runtime が公開している場合、OpenClaw ポリシーを通じてルーティングできます。OpenClaw が決定を返さない場合、Codex は通常の guardian またはユーザー承認経路を通じて続行します。 |
| App-server 軌跡キャプチャ | サポート | OpenClaw は app-server に送信したリクエストと、受信した app-server 通知を記録します。 |
| Codex を通じた OpenAI モデルループ | サポート | Codex app-server が OpenAI ターン、ネイティブスレッド再開、ネイティブツール継続を所有するため。 |
| OpenClaw チャンネルルーティングと配信 | サポート | Telegram、Discord、Slack、WhatsApp、iMessage、その他のチャンネルはモデルランタイムの外側に留まるため。 |
| OpenClaw 動的ツール | サポート | Codex が OpenClaw にこれらのツールの実行を要求するため、OpenClaw は実行経路に留まるため。 |
| プロンプトとコンテキスト Plugin | サポート | OpenClaw が、スレッドを開始または再開する前に、プロンプトオーバーレイを構築し、コンテキストを Codex ターンへ投影するため。 |
| コンテキストエンジンのライフサイクル | サポート | Codex ターンに対して、組み立て、取り込みまたはターン後メンテナンス、コンテキストエンジンの Compaction 調整が実行されるため。 |
| 動的ツールフック | サポート | `before_tool_call`、`after_tool_call`、およびツール結果ミドルウェアが、OpenClaw 所有の動的ツールの周辺で実行されるため。 |
| ライフサイクルフック | アダプター観測としてサポート | `llm_input`、`llm_output`、`agent_end`、`before_compaction`、`after_compaction` は、正確な Codex モードペイロードで発火するため。 |
| 最終回答の修正ゲート | ネイティブフックリレーを通じてサポート | Codex `Stop` は `before_agent_finalize` にリレーされ、`revise` は最終化前にもう 1 回のモデルパスを Codex に要求するため。 |
| ネイティブ shell、patch、MCP のブロックまたは観測 | ネイティブフックリレーを通じてサポート | Codex `PreToolUse` と `PostToolUse` は、Codex app-server `0.125.0` 以降の MCP ペイロードを含む、コミット済みのネイティブツールサーフェスに対してリレーされるため。ブロックはサポートされますが、引数の書き換えはサポートされません。 |
| ネイティブ権限ポリシー | ネイティブフックリレーを通じてサポート | ランタイムが公開している場合、Codex `PermissionRequest` は OpenClaw ポリシーを通じてルーティングできます。OpenClaw が決定を返さない場合、Codex は通常の guardian またはユーザー承認経路を通じて続行します。 |
| App-server 軌跡キャプチャ | サポート | OpenClaw は app-server に送信したリクエストと、受信した app-server 通知を記録するため。 |
Codex runtime v1 でサポートされないもの:
Codex ランタイム v1 でサポートされないもの:
| サーフェス | V1 境界 | 将来のパス |
| サーフェス | V1 境界 | 今後のパス |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| ネイティブツール引数の変更 | Codex ネイティブのツール前フックはブロックできるが、OpenClaw は Codex ネイティブのツール引数を書き換えない。 | 置換用ツール入力には Codex のフック/スキーマサポートが必要。 |
| 編集可能な Codex ネイティブのトランスクリプト履歴 | Codex が正規のネイティブスレッド履歴を所有する。OpenClaw はミラーを所有し、将来のコンテキストを投影できるが、サポートされていない内部状態を変更すべきではない。 | ネイティブスレッドの手術が必要な場合は、明示的な Codex app-server API を追加する。 |
| Codex ネイティブツールレコード向けの `tool_result_persist` | そのフックは OpenClaw が所有するトランスクリプト書き込みを変換するものであり、Codex ネイティブのツールレコードを変換するものではない。 | 変換済みレコードをミラーできる可能性はあるが、正規の書き換えには Codex のサポートが必要。 |
| リッチなネイティブ Compaction メタデータ | OpenClaw は Compaction の開始と完了を観測するが、安定した保持/破棄リスト、トークン差分、または要約ペイロードは受け取らない。 | よりリッチな Codex Compaction イベントが必要。 |
| Compaction 介入 | 現在の OpenClaw Compaction フックは Codex モードでは通知レベル。 | Plugin がネイティブ Compaction を拒否または書き換える必要がある場合は、Codex の Compaction 前後フックを追加する。 |
| バイト単位で同一のモデル API リクエストキャプチャ | OpenClaw は app-server のリクエストと通知をキャプチャできるが、Codex コアは最終的な OpenAI API リクエストを内部で構築する。 | Codex のモデルリクエストトレースイベントまたはデバッグ API が必要。 |
| ネイティブツール引数の変更 | Codex のネイティブなツール実行前フックはブロックできますが、OpenClaw は Codex ネイティブツール引数を書き換えません。 | 置換後のツール入力には、Codex のフック/スキーマサポートが必要です。 |
| 編集可能な Codex ネイティブ transcript 履歴 | Codex は正規のネイティブスレッド履歴を所有します。OpenClaw はミラーを所有し、将来のコンテキストを投影できますが、未サポートの内部状態を変更すべきではありません。 | ネイティブスレッドの直接編集が必要な場合は、明示的な Codex app-server API を追加します。 |
| Codex ネイティブツールレコード用の `tool_result_persist` | そのフックは OpenClaw が所有する transcript 書き込みを変換するもので、Codex ネイティブツールレコードは変換しません。 | 変換済みレコードをミラーすることはできますが、正規の書き換えには Codex のサポートが必要です。 |
| リッチなネイティブ Compaction メタデータ | OpenClaw は Compaction の開始と完了を監視しますが、安定した保持/破棄リスト、トークン差分、要約ペイロードは受け取りません。 | よりリッチな Codex Compaction イベントが必要です。 |
| Compaction 介入 | 現在の OpenClaw Compaction フックは、Codex モードでは通知レベルです。 | Plugin がネイティブ Compaction の拒否や書き換えを必要とする場合は、Codex の Compaction 前後フックを追加します。 |
| バイト単位で一致するモデル API リクエストの捕捉 | OpenClaw は app-server のリクエストと通知を捕捉できますが、Codex core は最終的な OpenAI API リクエストを内部で構築します。 | Codex のモデルリクエスト追跡イベントまたはデバッグ API が必要です。 |
## ツール、メディア、Compaction
Codex ハーネスは、低レベルの組み込みエージェント実行器のみを変更する。
Codex ハーネスが変更するのは、低レベルの組み込みエージェント実行器だけです。
OpenClaw は引き続きツールリストを構築し、ハーネスから動的ツール結果を受け取る。テキスト、画像、動画、音楽、TTS、承認、メッセージングツールの出力は、通常の OpenClaw 配信パスを通り続ける。
OpenClaw は引き続きツールリストを構築し、ハーネスから動的ツール結果を受け取ります。テキスト、画像、動画、音楽、TTS、承認、メッセージングツール出力は、通常の OpenClaw 配信パスを通り続けます。
ネイティブフックリレーは意図的に汎用的だが、v1 のサポート契約は OpenClaw がテストする Codex ネイティブのツールと権限のパスに限定される。Codex ランタイムでは、これに shell、patch、MCP の `PreToolUse`、`PostToolUse`、`PermissionRequest` ペイロードが含まれる。ランタイム契約で名前が示されるまでは、将来のすべての Codex フックイベントが OpenClaw Plugin サーフェスであると想定しないこと。
ネイティブフックリレーは意図的に汎用的ですが、v1 のサポート契約は OpenClaw がテストする Codex ネイティブのツールおよび権限パスに限定されます。Codex ランタイムでは、それに shell、patch、MCP の `PreToolUse`、`PostToolUse`、`PermissionRequest` ペイロードが含まれます。ランタイム契約が名前を挙げるまでは、将来のすべての Codex フックイベントが OpenClaw Plugin サーフェスであると仮定しないでください。
`PermissionRequest` について、OpenClaw はポリシーが判断した場合にのみ明示的な許可または拒否の決定を返す。決定なしの結果は許可ではない。Codex はそれをフック決定なしとして扱い、独自のガーディアンまたはユーザー承認パスへフォールスルーする。
`PermissionRequest` では、OpenClaw はポリシーが判断した場合にのみ、明示的な許可または拒否の決定を返します。決定なしの結果は許可ではありません。Codex はそれをフック判断なしとして扱い、自身のガーディアンまたはユーザー承認パスにフォールスルーします。
Codex MCP ツール承認の elicitation は、Codex が `_meta.codex_approval_kind` を `"mcp_tool_call"` としてマークした場合、OpenClaw の Plugin 承認フローを通じてルーティングされる。Codex の `request_user_input` プロンプトは元のチャットへ送り返され、次にキューされたフォローアップメッセージは、追加コンテキストとしてステアリングされる代わりに、そのネイティブサーバーリクエストに回答する。他の MCP elicitation リクエストは引き続き fail closed する。
Codex MCP ツール承認の要求は、Codex が `_meta.codex_approval_kind` を `"mcp_tool_call"` としてマークした場合、OpenClaw の Plugin 承認フローを通してルーティングされます。Codex の `request_user_input` プロンプトは発信元チャットに送り返され、次にキューに入ったフォローアップメッセージは、追加コンテキストとして誘導されるのではなく、そのネイティブサーバーリクエストに回答します。その他の MCP 要求リクエストは引き続き安全側に失敗します。
アクティブ実行キューステアリングは Codex app-server の `turn/steer` に対応する。デフォルトの `messages.queue.mode: "steer"` では、OpenClaw は設定された静音ウィンドウの間、キューされたチャットメッセージをまとめ、到着順に 1 つの `turn/steer` リクエストとして送信する。レガシーの `queue` モードは個別の `turn/steer` リクエストを送信する。Codex レビューと手動 Compaction ターンは同一ターンのステアリングを拒否する場合があり、その場合 OpenClaw は選択されたモードでフォールバックが許可されているときにフォローアップキューを使用する。[ステアリングキュー](/ja-JP/concepts/queue-steering)を参照。
アクティブ実行キューの誘導は、Codex app-server の `turn/steer` に対応します。デフォルトの `messages.queue.mode: "steer"` では、OpenClaw は設定済みの静穏ウィンドウ中にキュー化されたチャットメッセージをまとめ、到着順に 1 つの `turn/steer` リクエストとして送信します。レガシーの `queue` モードでは、個別の `turn/steer` リクエストを送信します。Codex のレビューターンと手動 Compaction ターンは同一ターンの誘導を拒否することがあり、その場合、選択されたモードでフォールバックが許可されていれば OpenClaw はフォローアップキューを使用します。[誘導キュー](/ja-JP/concepts/queue-steering)を参照してください。
選択したモデルが Codex ハーネスを使用する場合、ネイティブスレッド Compaction は Codex app-server に委任される。OpenClaw はチャンネル履歴、検索、`/new`、`/reset`、および将来のモデルまたはハーネス切り替えのためにトランスクリプトミラーを保持する。ミラーには、ユーザープロンプト、最終アシスタントテキスト、および app-server が出力する場合の軽量な Codex 推論または計画レコードが含まれる。現在、OpenClaw はネイティブ Compaction の開始と完了シグナルのみを記録する。Codex が Compaction 後に保持したエントリーについて、人間が読める Compaction 要約や監査可能なリストはまだ公開していない。
選択されたモデルが Codex ハーネスを使用する場合、ネイティブスレッド Compaction は Codex app-server に委任されます。OpenClaw はチャンネル履歴、検索、`/new`、`/reset`、将来のモデルまたはハーネス切り替えのために transcript ミラーを保持します。このミラーには、ユーザープロンプト、最終アシスタントテキスト、app-server が発行した場合の軽量な Codex 推論または計画レコードが含まれます。現時点では、OpenClaw はネイティブ Compaction の開始および完了シグナルのみを記録します。人間が読める Compaction 要約や、Compaction 後に Codex が保持したエントリの監査可能なリストはまだ公開していません。
Codex が正規のネイティブスレッドを所有するため、`tool_result_persist` は現在、Codex ネイティブのツール結果レコードを書き換えない。これは OpenClaw が所有するセッショントランスクリプトのツール結果を OpenClaw が書き込む場合にのみ適用される。
Codex が正規のネイティブスレッドを所有するため、`tool_result_persist` は現在 Codex ネイティブツール結果レコードを書き換えません。これは OpenClaw が所有するセッション transcript のツール結果を OpenClaw が書き込む場合にのみ適用されます。
メディア生成に PI は不要。画像、動画、音楽、PDF、TTS、メディア理解は、`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel`、`messages.tts` など、対応するプロバイダー/モデル設定を引き続き使用する。
メディア生成に PI は必要ありません。画像、動画、音楽、PDF、TTS、メディア理解は、`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel`、`messages.tts` などの対応するプロバイダー/モデル設定を引き続き使用します。
## トラブルシューティング
**Codex が通常の `/model` プロバイダーとして表示されない:** 新しい設定では想定どおり。`agentRuntime.id: "codex"` を指定した `openai/gpt-*` モデル（またはレガシーの `codex/*` ref）を選択し、`plugins.entries.codex.enabled` を有効にし、`plugins.allow` が `codex` を除外していないか確認する。
**Codex が通常の `/model` プロバイダーとして表示されない:** 新しい設定では想定どおりです。`agentRuntime.id: "codex"` を指定した `openai/gpt-*` モデル（またはレガシーの `codex/*` 参照）を選択し、`plugins.entries.codex.enabled` を有効にして、`plugins.allow` が `codex` を除外していないか確認してください。
**OpenClaw が Codex ではなく PI を使用する:** `agentRuntime.id: "auto"` は、Codex ハーネスが実行を要求しない場合、互換性バックエンドとして引き続き PI を使用できる。テスト中に Codex 選択を強制するには `agentRuntime.id: "codex"` を設定する。強制された Codex ランタイムは、`agentRuntime.fallback: "pi"` を明示的に設定しない限り、PI へフォールバックせず失敗するようになった。Codex app-server が選択されると、その失敗は追加のフォールバック設定なしで直接表面化する。
**OpenClaw が Codex ではなく PI を使用する:** `agentRuntime.id: "auto"` は、どの Codex ハーネスも実行を引き受けない場合、互換性バックエンドとして引き続き PI を使用できます。テスト中に Codex の選択を強制するには、`agentRuntime.id: "codex"` を設定します。強制された Codex ランタイムは、`agentRuntime.fallback: "pi"` を明示的に設定しない限り、PI にフォールバックせず失敗するようになりました。Codex app-server が選択されると、その失敗は追加のフォールバック設定なしで直接表面化します。
**app-server が拒否される:** app-server ハンドシェイクがバージョン `0.125.0` 以降を報告するように Codex をアップグレードする。同一バージョンのプレリリースや、`0.125.0-alpha.2` または `0.125.0+custom` のようなビルドサフィックス付きバージョンは拒否される。OpenClaw がテストする安定版のプロトコル下限が `0.125.0` だからである。
**app-server が拒否される:** Codex をアップグレードして、app-server ハンドシェイクがバージョン `0.125.0` 以降を報告するようにしてください。`0.125.0-alpha.2` や `0.125.0+custom` などの同一バージョンのプレリリースやビルドサフィックス付きバージョンは、安定版 `0.125.0` のプロトコル下限が OpenClaw のテスト対象であるため拒否されます。
**モデル検出が遅い:** `plugins.entries.codex.config.discovery.timeoutMs` を下げるか、検出を無効にする。
**モデル検出が遅い:** `plugins.entries.codex.config.discovery.timeoutMs` を下げるか、検出を無効にしてください。
**WebSocket トランスポートが即座に失敗する:** `appServer.url`、`authToken`、およびリモート app-server が同じ Codex app-server プロトコルバージョンを話していることを確認する。
**WebSocket トランスポートが即座に失敗する:** `appServer.url`、`authToken`、リモート app-server が同じ Codex app-server プロトコルバージョンを話していることを確認してください。
**Codex 以外のモデルが PI を使用する:** そのエージェントに対して `agentRuntime.id: "codex"` を強制した場合、またはレガシーの `codex/*` ref を選択した場合を除き、これは想定どおり。通常の `openai/gpt-*` とその他のプロバイダー ref は、`auto` モードでは通常のプロバイダーパスに留まる。`agentRuntime.id: "codex"` を強制する場合、そのエージェントのすべての組み込みターンは Codex がサポートする OpenAI モデルでなければならない。
**非 Codex モデルが PI を使用する:** そのエージェントに `agentRuntime.id: "codex"` を強制しているか、レガシーの `codex/*` 参照を選択している場合を除き、これは想定どおりです。通常の `openai/gpt-*` とその他のプロバイダー参照は、`auto` モードでは通常のプロバイダーパスに留まります。`agentRuntime.id: "codex"` を強制する場合、そのエージェントのすべての組み込みターンは Codex 対応の OpenAI モデルである必要があります。
**Computer Use はインストールされているがツールが実行されない:** 新しいセッションから `/codex computer-use status` を確認する。ツールが `Native hook relay unavailable` を報告する場合は `/new` または `/reset` を使用する。継続する場合は、古いネイティブフック登録をクリアするために Gateway を再起動する。`computer-use.list_apps` がタイムアウトする場合は、Codex Computer Use または Codex Desktop を再起動して再試行する。
**Computer Use はインストールされているがツールが実行されない:** 新しいセッションから `/codex computer-use status` を確認してください。ツールが `Native hook relay unavailable` を報告する場合は、`/new` または `/reset` を使用してください。それでも続く場合は、Gateway を再起動して古いネイティブフック登録をクリアしてください。`computer-use.list_apps` がタイムアウトする場合は、Codex Computer Use または Codex Desktop を再起動して再試行してください。
## 関連

498
docs/ja-JP/plugins/google-meet.md
View File

File diff suppressed because it is too large Load Diff

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

@ -1,124 +1,229 @@
---
read_when:
- 公開リリースチャンネルの定義を探しています
- 公開リリースチャネル定義を検索しています
- リリース検証またはパッケージ受け入れの実行
- バージョンの命名規則とリリース周期を探す
summary: リリースレーン、運用者チェックリスト、検証ボックス、バージョン命名規則、ケイデンス
- バージョン命名規則とリリース周期を確認中
summary: リリースレーン、オペレーター用チェックリスト、検証ボックス、バージョン命名、周期
title: リリースポリシー
x-i18n:
generated_at: "2026-04-30T05:33:04Z"
generated_at: "2026-05-01T05:03:13Z"
model: gpt-5.5
provider: openai
source_hash: 54dc9ad7918ac95ec535a0404bbcbc04461a2b977151db0c2039b91e7e69c15c
source_hash: dfe579099a9580e2d0400cd0b24f26d3fa3ee917899423604ebc13aa2519b4ee
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw には3つの公開リリースレーンがあります。
OpenClaw には 3 つの公開リリースレーンがあります。
- 安定版: デフォルトでは npm `beta` に公開され、明示的に要求された場合は npm `latest` に公開されるタグ付きリリース
- ベータ: npm `beta` に公開されるプレリリースタグ
- 開発版: `main` の移動する先頭
- stable: 既定では npm `beta` に公開され、明示的に要求された場合は npm `latest` に公開されるタグ付きリリース
- beta: npm `beta` に公開されるプレリリースタグ
- dev: `main` の移動する先頭
## バージョン命名
- 安定版リリースバージョン: `YYYY.M.D`
- stable リリースバージョン: `YYYY.M.D`
- Git タグ: `vYYYY.M.D`
- 安定版修正リリースバージョン: `YYYY.M.D-N`
- stable 修正リリースバージョン: `YYYY.M.D-N`
- Git タグ: `vYYYY.M.D-N`
- ベータプレリリースバージョン: `YYYY.M.D-beta.N`
- beta プレリリースバージョン: `YYYY.M.D-beta.N`
- Git タグ: `vYYYY.M.D-beta.N`
- 月または日にゼロ埋めはしない
- `latest` は現在昇格済みの安定版 npm リリースを意味する
- `beta` は現在のベータインストール対象を意味する
- 安定版および安定版修正リリースはデフォルトで npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みのベータビルドを後から昇格することもできる
- すべての安定版 OpenClaw リリースでは、npm パッケージと macOS アプリを一緒に出荷する。
ベータリリースでは通常、まず npm/パッケージ経路を検証して公開し、mac アプリのビルド/署名/公証は明示的に要求されない限り安定版向けに保持する
- 月または日をゼロ埋めしない
- `latest` は現在昇格済みの stable npm リリースを意味する
- `beta` は現在の beta インストール対象を意味する
- stable および stable 修正リリースは既定で npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みの beta ビルドを後で昇格することもできる
- すべての stable OpenClaw リリースは npm パッケージと macOS アプリを一緒に出荷する。
beta リリースでは通常、npm/パッケージ経路の検証と公開を先に行い、
mac アプリのビルド/署名/公証は明示的に要求されない限り stable 用に予約される
## リリース頻度
## リリースサイクル
- リリースはベータ優先で進む
- 安定版は最新のベータが検証された後にのみ続く
- メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを切るため、リリース検証と修正が `main` 上の新規開発を妨げない
- ベータタグがプッシュまたは公開済みで修正が必要な場合、メンテナーは古いベータタグを削除または再作成する代わりに、次の `-beta.N` タグを切る
- 詳細なリリース手順、承認、認証情報、復旧メモはメンテナー専用
- リリースは beta 優先で進む
- stable は最新の beta が検証された後にのみ続く
- メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを切る。
これにより、リリース検証と修正が `main` での新規開発をブロックしない
- beta タグがプッシュまたは公開済みで修正が必要な場合、メンテナーは古い beta タグを削除または再作成するのではなく、
次の `-beta.N` タグを切る
- 詳細なリリース手順、承認、認証情報、復旧メモは
メンテナー専用
## リリース担当者チェックリスト
このチェックリストは、リリースフローの公開部分を示します。非公開の認証情報、署名、公証、dist-tag 復旧、緊急ロールバックの詳細は、メンテナー専用のリリースランブックに保持されます。
このチェックリストはリリースフローの公開上の形を示します。非公開の認証情報、
署名、公証、dist-tag 復旧、緊急ロールバックの詳細は
メンテナー専用のリリースランブックに保持します。
1. 現在の `main` から開始する: 最新を pull し、対象コミットがプッシュ済みであることを確認し、現在の `main` CI がそこからブランチを切れる程度に green であることを確認する。
2. 実際のコミット履歴から `/changelog` で最上部の `CHANGELOG.md` セクションを書き換え、エントリをユーザー向けに保ち、コミットしてプッシュし、ブランチを切る前にもう一度 rebase/pull する。
3. `src/plugins/compat/registry.ts` と `src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性記録をレビューする。アップグレード経路が引き続きカバーされる場合にのみ期限切れの互換性を削除するか、意図的に持ち越す理由を記録する。
4. 現在の `main` から `release/YYYY.M.D` を作成する。通常のリリース作業を `main` で直接行わない。
5. 意図したタグに必要なすべてのバージョン箇所を更新し、その後ローカルの決定的なプリフライトを実行する:
1. 現在の `main` から開始する: 最新を pull し、対象コミットがプッシュ済みであることを確認し、
現在の `main` CI がブランチ作成に十分な程度に成功していることを確認する。
2. 実際のコミット履歴から最上位の `CHANGELOG.md` セクションを
`/changelog` で書き直し、エントリをユーザー向けに保ち、コミットしてプッシュし、
ブランチ作成前にもう一度 rebase/pull する。
3. `src/plugins/compat/registry.ts` と
`src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性記録を確認する。期限切れの
互換性はアップグレード経路が引き続きカバーされている場合にのみ削除し、そうでなければ
意図的に保持している理由を記録する。
4. 現在の `main` から `release/YYYY.M.D` を作成する。通常のリリース作業を
`main` で直接行わない。
5. 予定しているタグに必要なすべてのバージョン箇所を更新し、その後
ローカルの決定的プリフライトを実行する:
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build`, `pnpm release:check`。
6. `OpenClaw NPM Release` を `preflight_only=true` で実行する。タグが存在する前は、検証専用プリフライトのために40文字の完全なリリースブランチ SHA を使用できる。成功した `preflight_run_id` を保存する。
7. リリースブランチ、タグ、または完全なコミット SHA に対して `Full Release Validation` ですべてのプレリリーステストを開始する。これは4つの大きなリリーステストボックス、つまり Vitest、Docker、QA Lab、Package の単一の手動エントリポイントです。
8. 検証が失敗した場合は、リリースブランチ上で修正し、その修正を証明する最小の失敗ファイル、レーン、ワークフロージョブ、パッケージプロファイル、プロバイダー、またはモデル許可リストを再実行する。変更面によって以前の証拠が古くなる場合にのみ、完全な包括ワークフローを再実行する。
9. ベータでは、`vYYYY.M.D-beta.N` をタグ付けし、npm dist-tag `beta` で公開し、その後公開済みの `openclaw@YYYY.M.D-beta.N` または `openclaw@beta` パッケージに対して公開後パッケージ受け入れを実行する。プッシュ済みまたは公開済みのベータに修正が必要な場合は、次の `-beta.N` を切る。古いベータを削除または書き換えない。
10. 安定版では、検証済みのベータまたはリリース候補に必要な検証証拠がある場合にのみ続行する。安定版 npm 公開では、成功したプリフライトアーティファクトを `preflight_run_id` 経由で再利用する。安定版 macOS リリース準備には、パッケージ化された `.zip`、`.dmg`、`.dSYM.zip`、および `main` 上の更新済み `appcast.xml` も必要です。
11. 公開後、npm 公開後検証ツール、公開後のチャンネル証明が必要な場合は任意のスタンドアロン公開済み npm Telegram E2E、必要に応じた dist-tag 昇格、完全に一致する `CHANGELOG.md` セクションからの GitHub リリース/プレリリースノート、およびリリース告知手順を実行する。
`pnpm build && pnpm ui:build`, および `pnpm release:check`。
6. `preflight_only=true` で `OpenClaw NPM Release` を実行する。タグが存在する前は、
検証専用プリフライトに完全な 40 文字のリリースブランチ SHA を使用できる。
成功した `preflight_run_id` を保存する。
7. リリースブランチ、タグ、または完全なコミット SHA に対して
`Full Release Validation` ですべてのプレリリーステストを開始する。これは
4 つの大きなリリーステストボックスである Vitest、Docker、QA Lab、Package の
1 つの手動エントリポイントである。
8. 検証が失敗した場合はリリースブランチで修正し、修正を証明する最小の失敗した
ファイル、レーン、ワークフロージョブ、パッケージプロファイル、プロバイダー、またはモデル許可リストを再実行する。
変更面によって既存の証拠が古くなる場合にのみ、全体のアンブレラを再実行する。
9. beta の場合は `vYYYY.M.D-beta.N` をタグ付けし、npm dist-tag `beta` で公開してから、
公開済みの `openclaw@YYYY.M.D-beta.N` または `openclaw@beta` パッケージに対して
公開後のパッケージ受け入れを実行する。プッシュ済みまたは公開済みの beta に修正が必要な場合は、
次の `-beta.N` を切る。古い beta を削除または書き換えない。
10. stable の場合は、検証済みの beta またはリリース候補に必要な検証証拠がある場合にのみ続行する。
stable npm 公開では、成功したプリフライト成果物を
`preflight_run_id` 経由で再利用する。stable macOS リリースの準備完了には、
パッケージ化された `.zip`、`.dmg`、`.dSYM.zip`、および `main` 上の更新済み
`appcast.xml` も必要である。
11. 公開後、npm 公開後検証ツール、公開後のチャンネル証拠が必要な場合の任意のスタンドアロン
公開済み npm Telegram E2E、必要に応じた dist-tag 昇格、
完全に一致する `CHANGELOG.md` セクションからの GitHub リリース/プレリリースノート、
およびリリース告知手順を実行する。
## リリースプリフライト
- リリース事前検証の前に `pnpm check:test-types` を実行し、テストの TypeScript がより高速なローカル `pnpm check` ゲートの外でもカバーされるようにする
- リリース事前検証の前に `pnpm check:architecture` を実行し、より広範なインポートサイクルとアーキテクチャ境界のチェックがより高速なローカルゲートの外でもグリーンになるようにする
- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行し、パック検証ステップ用の想定される `dist/*` リリース成果物と Control UI バンドルが存在するようにする
- リリース承認の前に手動の `Full Release Validation` ワークフローを実行し、すべてのリリース前テストボックスを 1 つのエントリポイントから開始する。これはブランチ、タグ、または完全なコミット SHA を受け取り、手動の `CI` をディスパッチし、インストールスモーク、パッケージ受け入れ、Docker リリースパススイート、ライブ/E2E、OpenWebUI、QA Lab パリティ、Matrix、Telegram レーン用の `OpenClaw Release Checks` をディスパッチする。パッケージが公開済みで、公開後の Telegram E2E も実行する必要がある場合にのみ `npm_telegram_package_spec` を指定する。Telegram E2E を強制せずに、非公開の証拠レポートで検証が公開済み npm パッケージと一致することを証明する必要がある場合は `evidence_package_spec` を指定する。例:
- リリースのプリフライト前に `pnpm check:test-types` を実行し、テスト TypeScript が高速なローカル `pnpm check` ゲートの外でも
対象に含まれるようにする
- リリースのプリフライト前に `pnpm check:architecture` を実行し、より広範なインポート
サイクルとアーキテクチャ境界チェックが高速なローカルゲートの外でもグリーンになるようにする
- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行し、想定される
`dist/*` リリース成果物と Control UI バンドルがパック
検証ステップ用に存在するようにする
- リリース承認前に手動 `Full Release Validation` ワークフローを実行し、すべてのリリース前テストボックスを 1 つのエントリポイントから
開始する。これはブランチ、
タグ、または完全なコミット SHA を受け取り、手動 `CI` をディスパッチし、インストールスモーク、パッケージ受け入れ、Docker
リリースパススイート、ライブ/E2E、OpenWebUI、QA Lab パリティ、Matrix、Telegram
レーン用に `OpenClaw Release Checks` をディスパッチする。パッケージが
公開済みで、公開後の Telegram E2E も実行する必要がある場合にのみ `npm_telegram_package_spec` を指定する。プライベート証跡レポートで、Telegram E2E を強制せずに
検証が公開済み npm パッケージと一致することを証明する必要がある場合は
`evidence_package_spec` を指定する。
例:
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- リリース作業を継続しながらパッケージ候補のサイドチャネル証拠が必要な場合は、手動の `Package Acceptance` ワークフローを実行する。`openclaw@beta`、`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使う。現在の `workflow_ref` ハーネスで信頼済みの `package_ref` ブランチ/タグ/SHA をパックするには `source=ref` を使う。必須の SHA-256 を伴う HTTPS tarball には `source=url` を使う。または、別の GitHub Actions 実行でアップロードされた tarball には `source=artifact` を使う。このワークフローは候補を `package-under-test` に解決し、その tarball に対して Docker E2E リリーススケジューラを再利用し、同じ tarball に対して `telegram_mode=mock-openai` または `telegram_mode=live-frontier` で Telegram QA を実行できる。
例: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai`
共通プロファイル:
- `smoke`: インストール/チャネル/エージェント、Gateway ネットワーク、設定リロードのレーン
- リリース作業を続けながらパッケージ候補のサイドチャネル証跡が必要な場合は、手動 `Package Acceptance` ワークフローを実行する。`openclaw@beta`、
`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使用する。現在の
`workflow_ref` ハーネスで信頼済みの `package_ref` ブランチ/タグ/SHA をパックするには `source=ref`
を使用する。必須の SHA-256 付き HTTPS tarball には `source=url` を使用する。または、別の GitHub
Actions 実行でアップロードされた tarball には `source=artifact` を使用する。このワークフローは候補を
`package-under-test` に解決し、その tarball に対して Docker E2E リリーススケジューラを再利用し、
同じ tarball に対して `telegram_mode=mock-openai` または `telegram_mode=live-frontier` で
Telegram QA を実行できる。選択された Docker レーンに
`published-upgrade-survivor` が含まれる場合、パッケージ成果物が候補になり、`published_upgrade_survivor_baseline` が
公開済みベースラインを選択する。
例: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
一般的なプロファイル:
- `smoke`: インストール/チャネル/エージェント、Gateway ネットワーク、構成リロードの各レーン
- `package`: OpenWebUI またはライブ ClawHub を含まない、成果物ネイティブのパッケージ/更新/Plugin レーン
- `product`: パッケージプロファイルに加えて、MCP チャネル、cron/サブエージェントのクリーンアップ、OpenAI Web 検索、OpenWebUI
- `full`: OpenWebUI を含む Docker リリースパスチャンク
- `product`: パッケージプロファイルに加え、MCP チャネル、cron/サブエージェントのクリーンアップ、
OpenAI Web 検索、OpenWebUI
- `full`: OpenWebUI を含む Docker リリースパスのチャンク
- `custom`: 集中的な再実行用の正確な `docker_lanes` 選択
- リリース候補に対して通常の CI の完全なカバレッジだけが必要な場合は、手動の `CI` ワークフローを直接実行する。手動 CI ディスパッチは変更範囲のスコープをバイパスし、Linux Node シャード、バンドル済み Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Android、Control UI i18n レーンを強制する。
- リリース候補について通常の完全な CI カバレッジだけが必要な場合は、手動 `CI` ワークフローを直接実行する。手動 CI ディスパッチは変更スコープを
バイパスし、Linux Node シャード、同梱 Plugin シャード、チャネル
契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、
ドキュメントチェック、Python Skills、Windows、macOS、Android、Control UI i18n
レーンを強制する。
例: `gh workflow run ci.yml --ref release/YYYY.M.D`
- リリーステレメトリを検証するときは `pnpm qa:otel:smoke` を実行する。これはローカル OTLP/HTTP レシーバーを通じて QA-lab を実行し、Opik、Langfuse、または別の外部コレクターを必要とせずに、エクスポートされたトレーススパン名、境界付き属性、コンテンツ/識別子のリダクションを検証する。
- すべてのタグ付きリリースの前に `pnpm release:check` を実行する
- リリーステレメトリを検証する場合は `pnpm qa:otel:smoke` を実行する。これは
ローカル OTLP/HTTP レシーバーを通じて QA-lab を実行し、Opik、Langfuse、その他の外部コレクターを
必要とせずに、エクスポートされたトレース
スパン名、制限付き属性、コンテンツ/識別子のリダクションを検証する。
- すべてのタグ付きリリース前に `pnpm release:check` を実行する
- リリースチェックは現在、別の手動ワークフローで実行される:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` は、リリース承認の前に QA Lab モックパリティゲートに加え、高速なライブ Matrix プロファイルと Telegram QA レーンも実行する。ライブレーンは `qa-live-shared` 環境を使う。Telegram は Convex CI の資格情報リースも使う。完全な Matrix トランスポート、メディア、E2EE インベントリを並列で確認したい場合は、`matrix_profile=all` と `matrix_shards=true` で手動の `QA-Lab - All Lanes` ワークフローを実行する。
- クロス OS インストールおよびアップグレードのランタイム検証は、再利用可能ワークフロー `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す公開 `OpenClaw Release Checks` と `Full Release Validation` の一部である
- この分割は意図的なもの。実際の npm リリースパスを短く、決定的で、成果物中心に保ちつつ、遅いライブチェックは独自のレーンに置き、公開を停滞またはブロックしないようにする
- シークレットを伴うリリースチェックは、ワークフローのロジックとシークレットが制御された状態に保たれるように、`Full Release Validation` 経由、または `main`/release ワークフロー ref からディスパッチする必要がある
- `OpenClaw Release Checks` は、解決されたコミットが OpenClaw ブランチまたはリリースタグから到達可能である限り、ブランチ、タグ、または完全なコミット SHA を受け取る
- `OpenClaw NPM Release` の検証専用事前検証は、プッシュ済みタグを必要とせずに、現在の完全な 40 文字のワークフローブランチコミット SHA も受け取る
- その SHA パスは検証専用であり、実際の公開に昇格することはできない
- SHA モードでは、ワークフローはパッケージメタデータチェックのためだけに `v<package.json version>` を合成する。実際の公開には引き続き実際のリリースタグが必要である
- どちらのワークフローも、実際の公開と昇格のパスは GitHub ホストランナー上に保ち、変更を伴わない検証パスではより大きな Blacksmith Linux ランナーを使用できる
- そのワークフローは、`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` を `OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方のワークフローシークレットを使って実行する
- npm リリース事前検証は、別のリリースチェックレーンを待たなくなった
- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（または対応する beta/修正版タグ）を実行する
- npm 公開後、`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（または対応する beta/修正版バージョン）を実行し、新しい一時プレフィックスで公開済みレジストリのインストールパスを検証する
- beta 公開後、共有リース済み Telegram 資格情報プールを使って、公開済み npm パッケージに対するインストール済みパッケージのオンボーディング、Telegram セットアップ、実際の Telegram E2E を検証するために、`OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` を実行する。ローカルのメンテナーによる一回限りの実行では、Convex 変数を省略し、3 つの `OPENCLAW_QA_TELEGRAM_*` 環境資格情報を直接渡してもよい。
- メンテナーは、GitHub Actions から手動の `NPM Telegram Beta E2E` ワークフロー経由で同じ公開後チェックを実行できる。これは意図的に手動専用であり、すべてのマージで実行されるわけではない。
- メンテナーのリリース自動化は現在、事前検証後に昇格する方式を使う:
- `OpenClaw Release Checks` はリリース承認前に、QA Lab モックパリティゲートに加えて高速な
ライブ Matrix プロファイルと Telegram QA レーンも実行する。ライブ
レーンは `qa-live-shared` 環境を使用し、Telegram は Convex CI
認証情報リースも使用する。Matrix の
トランスポート、メディア、E2EE インベントリ全体を並列で実行したい場合は、`matrix_profile=all` と `matrix_shards=true` で手動 `QA-Lab - All Lanes` ワークフローを実行する。
- クロス OS インストールとアップグレードのランタイム検証は、公開
`OpenClaw Release Checks` と `Full Release Validation` の一部であり、再利用可能ワークフロー
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す
- この分割は意図的なもの: 実際の npm リリースパスを短く、
決定的で、成果物に集中したものに保ちつつ、時間のかかるライブチェックは独自のレーンに置き、
公開を停滞またはブロックしないようにするため
- シークレットを含むリリースチェックは `Full Release
Validation` を通じて、または `main`/release ワークフロー ref からディスパッチし、ワークフローロジックと
シークレットを制御された状態に保つ必要がある
- `OpenClaw Release Checks` は、解決されたコミットが OpenClaw ブランチまたはリリースタグから到達可能である限り、
ブランチ、タグ、または完全なコミット SHA を受け付ける
- `OpenClaw NPM Release` の検証専用プリフライトも、プッシュ済みタグを要求せずに、現在の
完全な 40 文字のワークフローブランチコミット SHA を受け付ける
- その SHA パスは検証専用であり、実際の公開に昇格できない
- SHA モードでは、ワークフローはパッケージメタデータチェックのためだけに `v<package.json version>` を
合成する。実際の公開には引き続き実際のリリースタグが必要
- 両方のワークフローは実際の公開と昇格パスを GitHub ホストランナー上に保ちつつ、
非変更の検証パスでは、より大きな Blacksmith Linux ランナーを使用できる
- そのワークフローは
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
を、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方のワークフローシークレットを使って実行する
- npm リリースプリフライトは、別個のリリースチェックレーンを待たなくなった
- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(または対応するベータ/修正版タグ) を実行する
- npm 公開後に
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(または対応するベータ/修正版バージョン) を実行し、新しい一時プレフィックスで公開済みレジストリの
インストールパスを検証する
- ベータ公開後に `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
を実行し、共有リース済み Telegram 認証情報
プールを使って、公開済み npm パッケージに対するインストール済みパッケージのオンボーディング、Telegram セットアップ、実際の Telegram E2E
を検証する。ローカルメンテナーの単発実行では Convex 変数を省略し、3 つの
`OPENCLAW_QA_TELEGRAM_*` env 認証情報を直接渡してもよい。
- メンテナーは、手動 `NPM Telegram Beta E2E` ワークフローを使って、GitHub Actions から同じ公開後チェックを実行できる。これは意図的に手動専用であり、
すべてのマージで実行されるわけではない。
- メンテナー向けリリース自動化は現在、プリフライト後に昇格する方式を使用する:
- 実際の npm 公開は、成功した npm `preflight_run_id` に合格している必要がある
- 実際の npm 公開は、成功した事前検証実行と同じ `main` または `release/YYYY.M.D` ブランチからディスパッチされている必要がある
- stable npm リリースのデフォルトは `beta`
- stable npm 公開は、ワークフロー入力で明示的に `latest` を対象にできる
- トークンベースの npm dist-tag 変更は現在、セキュリティのため `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` に置かれている。これは、公開リポジトリが OIDC のみの公開を維持する一方で、`npm dist-tag add` にはまだ `NPM_TOKEN` が必要なためである
- 公開 `macOS Release` は検証専用である
- 実際の非公開 mac 公開は、成功した非公開 mac の `preflight_run_id` と `validate_run_id` に合格している必要がある
- 実際の公開パスは、準備済み成果物を再ビルドせずに昇格する
- `YYYY.M.D-N` のような stable 修正版リリースでは、公開後検証ツールは同じ一時プレフィックスのアップグレードパスも `YYYY.M.D` から `YYYY.M.D-N` へ確認し、リリース修正版が古いグローバルインストールをベース stable ペイロードのまま静かに残さないようにする
- npm リリース事前検証は、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` ペイロードの両方が含まれていない限り、フェイルクローズする。これにより、空のブラウザダッシュボードを再び出荷しないようにする
- 公開後検証では、公開済みレジストリのインストールに、ルートの `dist/*` レイアウト配下で空でないバンドル済み Plugin ランタイム依存関係が含まれていることも確認する。バンドル済み Plugin 依存関係ペイロードが欠落または空のまま出荷されたリリースは、公開後検証に失敗し、`latest` に昇格できない。
- `pnpm test:install:smoke` は、候補更新 tarball に対して npm パックの `unpackedSize` 予算も強制するため、インストーラー e2e はリリース公開パスの前に偶発的なパック肥大化を検出する
- リリース作業で CI 計画、Plugin タイミングマニフェスト、または Plugin テストマトリックスに触れた場合は、承認前に `.github/workflows/plugin-prerelease.yml` からプランナー所有の `plugin-prerelease-extension-shard` マトリックス出力を再生成してレビューし、リリースノートが古い CI レイアウトを説明しないようにする
- stable macOS リリース準備には、アップデーターのサーフェスも含まれる:
- GitHub リリースには、パッケージ化された `.zip`、`.dmg`、`.dSYM.zip` が最終的に含まれている必要がある
- `main` 上の `appcast.xml` は、公開後に新しい stable zip を指している必要がある
- パッケージ化されたアプリは、非デバッグのバンドル ID、空でない Sparkle フィード URL、そのリリースバージョンの正規 Sparkle ビルド下限以上の `CFBundleVersion` を維持している必要がある
- 実際の npm 公開は、成功したプリフライト実行と同じ `main` または
`release/YYYY.M.D` ブランチからディスパッチされている必要がある
- 安定版 npm リリースのデフォルトは `beta`
- 安定版 npm 公開は、ワークフロー入力で明示的に `latest` を対象にできる
- トークンベースの npm dist-tag 変更は現在、セキュリティのため
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` にある。これは、公開リポジトリが OIDC のみの公開を維持する一方で、
`npm dist-tag add` には引き続き `NPM_TOKEN` が必要なため
- 公開 `macOS Release` は検証専用である。タグがリリースブランチにのみ存在するが
ワークフローが `main` からディスパッチされる場合は、
`public_release_branch=release/YYYY.M.D` を設定する
- 実際のプライベート Mac 公開は、成功したプライベート Mac
`preflight_run_id` と `validate_run_id` に合格している必要がある
- 実際の公開パスは、成果物を再ビルドするのではなく、準備済み成果物を昇格する
- `YYYY.M.D-N` のような安定版修正リリースでは、公開後検証ツールが
`YYYY.M.D` から `YYYY.M.D-N` への同じ一時プレフィックスアップグレードパスもチェックし、
リリース修正が古いグローバルインストールをベース安定版ペイロードのままに
気づかず残さないようにする
- npm リリースプリフライトは、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` ペイロードの両方が含まれていない限り
クローズドに失敗する。これにより、空のブラウザダッシュボードを再び出荷しない
- 公開後検証では、公開済みレジストリインストールに、ルート `dist/*`
レイアウト配下の空でない同梱 Plugin ランタイム依存関係が含まれることも確認する。同梱 Plugin
依存関係ペイロードが欠落または空のまま出荷されるリリースは公開後検証ツールに失敗し、
`latest` に昇格できない。
- `pnpm test:install:smoke` は、候補更新 tarball に対して npm pack の `unpackedSize` 予算も適用するため、
インストーラー e2e がリリース公開パスの前に偶発的なパック肥大を検出する
- リリース作業が CI 計画、Plugin タイミングマニフェスト、または
Plugin テストマトリックスに触れた場合は、承認前に
`.github/workflows/plugin-prerelease.yml` からプランナー所有の `plugin-prerelease-extension-shard` マトリックス出力を再生成してレビューし、リリースノートが
古い CI レイアウトを説明しないようにする
- 安定版 macOS リリースの準備状況には、アップデーター関連の面も含まれる:
- GitHub リリースには、パッケージ済みの `.zip`、`.dmg`、`.dSYM.zip` が最終的に含まれている必要がある
- 公開後、`main` 上の `appcast.xml` は新しい安定版 zip を指している必要がある
- パッケージ済みアプリは、非デバッグのバンドル ID、空でない Sparkle フィード
URL、そのリリースバージョンの正規 Sparkle ビルド下限以上の `CFBundleVersion` を維持する必要がある
## リリーステストボックス
`Full Release Validation` は、オペレーターがすべてのリリース前テストを 1 つのエントリポイントから開始する方法である。信頼済みの `main` ワークフロー ref から実行し、リリースブランチ、タグ、または完全なコミット SHA を `ref` として渡す:
`Full Release Validation` は、オペレーターが 1 つのエントリポイントからすべてのリリース前テストを
開始する方法である。信頼済みの `main` ワークフロー ref から実行し、リリース
ブランチ、タグ、または完全なコミット SHA を `ref` として渡す:
```bash
gh workflow run full-release-validation.yml \
@ -126,23 +231,44 @@ gh workflow run full-release-validation.yml \
-f ref=release/YYYY.M.D \
-f provider=openai \
-f mode=both \
-f release_profile=full \
-f release_profile=stable \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
このワークフローはターゲット ref を解決し、`target_ref=<release-ref>` で手動の `CI` をディスパッチし、`OpenClaw Release Checks` をディスパッチし、`npm_telegram_package_spec` が設定されている場合は、任意でスタンドアロンの公開後 Telegram E2E をディスパッチする。その後、`OpenClaw Release Checks` は、インストールスモーク、クロス OS リリースチェック、ライブ/E2E Docker リリースパスカバレッジ、Telegram パッケージ QA を伴う Package Acceptance、QA Lab パリティ、ライブ Matrix、ライブ Telegram にファンアウトする。完全な実行が許容されるのは、`Full Release Validation` サマリーで `normal_ci` と `release_checks` が成功しており、任意の `npm_telegram` 子が成功しているか意図的にスキップされている場合のみである。最終検証サマリーには各子実行の最遅ジョブ表が含まれるため、リリースマネージャーはログをダウンロードせずに現在のクリティカルパスを確認できる。
子ワークフローは、ターゲット `ref` が古いリリースブランチまたはタグを指している場合でも、`Full Release Validation` を実行する信頼済み ref、通常は `--ref main` からディスパッチされる。別個の Full Release Validation ワークフロー ref 入力は存在しない。ワークフロー実行 ref を選ぶことで、信頼済みハーネスを選択する。
このワークフローは対象 ref を解決し、`target_ref=<release-ref>` で手動 `CI` をディスパッチし、
`OpenClaw Release Checks` をディスパッチし、
`npm_telegram_package_spec` が設定されている場合は任意でスタンドアロンの公開後 Telegram E2E をディスパッチする。その後、`OpenClaw Release Checks` は
インストールスモーク、クロス OS リリースチェック、ライブ/E2E Docker リリースパスカバレッジ、
Telegram パッケージ QA を含む Package Acceptance、QA Lab パリティ、ライブ Matrix、ライブ Telegram に展開する。フル実行が受け入れられるのは、`Full Release Validation`
サマリーで `normal_ci` と `release_checks` が成功しており、任意の
`npm_telegram` 子が成功しているか意図的にスキップされている場合のみである。最終
検証サマリーには各子実行の最遅ジョブ表が含まれるため、リリース
マネージャーはログをダウンロードせずに現在のクリティカルパスを確認できる。
完全なステージマトリックス、正確なワークフロージョブ名、安定版とフルプロファイルの
違い、成果物、集中的な再実行ハンドルについては、[フルリリース検証](/ja-JP/reference/full-release-validation) を参照。
子ワークフローは、`Full Release
Validation` を実行する信頼済み ref、通常は `--ref main` からディスパッチされる。これは対象 `ref` が
古いリリースブランチまたはタグを指す場合でも同じである。Full Release Validation 専用の
ワークフロー ref 入力はない。信頼済みハーネスはワークフロー実行 ref を選択して指定する。
ライブ/プロバイダーの広さを選択するには `release_profile` を使う:
ライブ/プロバイダーの範囲を選択するには `release_profile` を使用する:
- `minimum`: 最速のリリースクリティカルな OpenAI/core ライブおよび Docker パス
- `stable`: リリース承認用に minimum に stable プロバイダー/バックエンドカバレッジを追加
- `minimum`: 最速のリリース重要 OpenAI/core ライブおよび Docker パス
- `stable`: リリース承認用に minimum に安定版プロバイダー/バックエンドカバレッジを追加
- `full`: stable に広範なアドバイザリプロバイダー/メディアカバレッジを追加
`OpenClaw Release Checks` は、信頼済みワークフロー ref を使ってターゲット ref を一度 `release-package-under-test` として解決し、リリースパス Docker チェックと Package Acceptance の両方でその成果物を再利用する。これにより、パッケージ向けのすべてのボックスが同じバイト列を使い、パッケージの再ビルドを繰り返さずに済む。
クロス OS OpenAI インストールスモークは、repo/org 変数が設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` を使い、それ以外の場合は `openai/gpt-5.4-mini` を使う。このレーンは、最も遅いデフォルトモデルのベンチマークではなく、パッケージインストール、オンボーディング、Gateway 起動、1 回のライブエージェントターンを証明するためである。より広範なライブプロバイダーマトリックスが、モデル固有のカバレッジの場である。
`OpenClaw Release Checks` は、信頼済みワークフロー ref を使用して対象
ref を `release-package-under-test` として一度だけ解決し、そのアーティファクトを
release-path Docker チェックと Package Acceptance の両方で再利用します。これにより、
パッケージ向けのすべてのボックスが同じバイト列を使い、パッケージビルドの繰り返しを避けられます。
cross-OS OpenAI install smoke は、repo/org 変数が設定されている場合は
`OPENCLAW_CROSS_OS_OPENAI_MODEL` を使用し、そうでない場合は `openai/gpt-5.4-mini`
を使用します。このレーンは、最も遅いデフォルトモデルのベンチマークではなく、
パッケージインストール、オンボーディング、Gateway 起動、1 回の live agent ターンを
証明するためのものだからです。より広範な live provider matrix が、モデル固有の
カバレッジの場所として残ります。
リリース段階に応じて、これらのバリアントを使う:
リリース段階に応じて、これらのバリアントを使用します。
```bash
# Validate an unpublished release candidate branch.
@ -171,22 +297,37 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
焦点を絞った修正後の最初の再実行として、包括的な全体ワークフローを使用しないでください。1 つのボックスが失敗した場合は、次の証明には失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデルプロバイダー、または QA レーンを使用します。修正が共有リリースオーケストレーションを変更した場合、または以前の全ボックス証拠が古くなった場合にのみ、包括的な全体ワークフローを再実行してください。包括的な全体ワークフローの最終検証では、記録された子ワークフロー実行 ID が再チェックされるため、子ワークフローの再実行が成功した後は、失敗した親ジョブ `Verify full validation` だけを再実行します。
焦点を絞った修正後の最初の再実行として、フル umbrella を使用しないでください。1 つのボックスが
失敗した場合は、次の証明に、失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデル
provider、または QA レーンを使用します。修正によって共有リリースオーケストレーションが変更された場合、または
以前の全ボックス証拠が古くなった場合にのみ、フル umbrella を再度実行します。umbrella の最終 verifier は、記録された子ワークフロー実行
ID を再チェックするため、子ワークフローを正常に再実行した後は、失敗した
`Verify full validation` 親ジョブだけを再実行します。
範囲を限定したリカバリーでは、包括的な全体ワークフローに `rerun_group` を渡します。`all` は実際のリリース候補実行、`ci` は通常の CI 子だけを実行し、`plugin-prerelease` はリリース専用 Plugin 子だけを実行し、`release-checks` はすべてのリリースボックスを実行します。より狭いリリースグループは、スタンドアロンのパッケージ Telegram レーンが指定されている場合、`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` です。
範囲を限定した復旧には、umbrella に `rerun_group` を渡します。`all` は実際の
リリース候補実行、`ci` は通常の CI 子だけを実行し、`plugin-prerelease`
はリリース専用 Plugin 子だけを実行し、`release-checks` はすべてのリリース
ボックスを実行します。より狭いリリースグループは、単独のパッケージ Telegram レーンが指定されている場合の
`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、および `npm-telegram` です。
### Vitest
Vitest ボックスは手動の `CI` 子ワークフローです。手動 CI は意図的に変更範囲による絞り込みを回避し、リリース候補に対して通常のテストグラフを強制します。対象は Linux Node シャード、バンドル済み Plugin シャード、チャンネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Android、Control UI i18n です。
Vitest ボックスは手動の `CI` 子ワークフローです。手動 CI は意図的に
changed スコープをバイパスし、リリース候補に対して通常のテストグラフを強制します:
Linux Node シャード、バンドル済み Plugin シャード、チャネル契約、Node 22
互換性、`check`、`check-additional`、build smoke、docs checks、Python
Skills、Windows、macOS、Android、および Control UI i18n。
このボックスは、「ソースツリーが通常の完全なテストスイートに合格したか」に答えるために使用します。これはリリースパスのプロダクト検証とは同じではありません。保持する証拠:
このボックスは「ソースツリーが通常のフルテストスイートを通過したか」に答えるために使用します。
release-path の製品検証とは同じではありません。保持する証拠:
- ディスパッチされた `CI` 実行 URL を示す `Full Release Validation` サマリー
- 正確なターゲット SHA で成功した `CI` 実行
- dispatch された `CI` 実行 URL を示す `Full Release Validation` サマリー
- 正確な対象 SHA で green になった `CI` 実行
- 回帰を調査するときの CI ジョブからの失敗または遅いシャード名
- 実行にパフォーマンス分析が必要な場合の `.artifacts/vitest-shard-timings.json` などの Vitest タイミングアーティファクト
リリースに決定的な通常 CI が必要だが、Docker、QA Lab、ライブ、クロス OS、またはパッケージボックスが不要な場合にのみ、手動 CI を直接実行します。
リリースに決定論的な通常 CI が必要で、Docker、QA Lab、live、cross-OS、またはパッケージボックスが不要な場合にのみ、
手動 CI を直接実行します。
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -194,50 +335,102 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Docker ボックスは `OpenClaw Release Checks` の中の `openclaw-live-and-e2e-checks-reusable.yml` と、リリースモードの `install-smoke` ワークフローにあります。これはソースレベルのテストだけでなく、パッケージ化された Docker 環境を通じてリリース候補を検証します。
Docker ボックスは、`openclaw-live-and-e2e-checks-reusable.yml` を通じた
`OpenClaw Release Checks` と、release-mode の
`install-smoke` ワークフローにあります。ソースレベルのテストだけでなく、パッケージ化された
Docker 環境を通じてリリース候補を検証します。
リリース Docker カバレッジには次が含まれます。
リリース Docker カバレッジには以下が含まれます。
- 低速な Bun グローバルインストールスモークを有効にした完全なインストールスモーク
- ターゲット SHA ごとのルート Dockerfile スモークイメージ準備/再利用。QR、ルート/Gateway、インストーラー/Bun スモークジョブは個別の install-smoke シャードとして実行
- 遅い Bun グローバルインストール smoke を有効にした full install smoke
- 対象 SHA ごとの root Dockerfile smoke イメージ準備/再利用。QR、
root/gateway、installer/Bun smoke ジョブは個別の install-smoke
シャードとして実行
- リポジトリ E2E レーン
- リリースパス Docker チャンク: `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b`、`bundled-channels-contracts`
- release-path Docker チャンク: `core`、`package-update-openai`、
`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、
`plugins-runtime-services`、
`plugins-runtime-install-a`、`plugins-runtime-install-b`、
`plugins-runtime-install-c`、`plugins-runtime-install-d`、
`plugins-runtime-install-e`、`plugins-runtime-install-f`、
`plugins-runtime-install-g`、`plugins-runtime-install-h`、
`bundled-channels-core`、`bundled-channels-update-a`、
`bundled-channels-update-discord`、`bundled-channels-update-b`、および
`bundled-channels-contracts`
- 要求された場合の `plugins-runtime-services` チャンク内の OpenWebUI カバレッジ
- バンドル済みチャンネル依存レーンを、1 つの大きなバンドル済みチャンネルジョブではなく、channel-smoke、update-target、setup/runtime 契約チャンクに分割
- 分割されたバンドル済み Plugin インストール/アンインストールレーン `bundled-plugin-install-uninstall-0` から `bundled-plugin-install-uninstall-23`
- リリースチェックにライブスイートが含まれる場合のライブ/E2E プロバイダースイートと Docker ライブモデルカバレッジ
- 1 つの大きな bundled-channel ジョブではなく、channel-smoke、update-target、
setup/runtime contract チャンクに分割された bundled-channel 依存関係レーン
- `bundled-plugin-install-uninstall-0` から
`bundled-plugin-install-uninstall-23` までの、分割されたバンドル済み Plugin install/uninstall レーン
- リリースチェックに live スイートが含まれる場合の live/E2E provider スイートと Docker live model カバレッジ
再実行の前に Docker アーティファクトを使用してください。リリースパスのスケジューラーは `.artifacts/docker-tests/` をアップロードし、そこにはレーンログ、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、再実行コマンドが含まれます。焦点を絞ったリカバリーでは、すべてのリリースチャンクを再実行するのではなく、再利用可能なライブ/E2E ワークフローで `docker_lanes=<lane[,lane]>` を使用します。生成される再実行コマンドには、利用可能な場合、以前の `package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、失敗したレーンは同じ tarball と GHCR イメージを再利用できます。
再実行する前に Docker アーティファクトを使用してください。release-path scheduler は
`.artifacts/docker-tests/` をアップロードし、レーンログ、`summary.json`、`failures.json`、
フェーズタイミング、scheduler plan JSON、および再実行コマンドを含めます。焦点を絞った復旧には、
すべてのリリースチャンクを再実行する代わりに、再利用可能な live/E2E ワークフローで
`docker_lanes=<lane[,lane]>` を使用します。生成された再実行コマンドには、利用可能な場合、以前の
`package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、
失敗したレーンは同じ tarball と GHCR イメージを再利用できます。
### QA Lab
QA Lab ボックスも `OpenClaw Release Checks` の一部です。これはエージェント的な振る舞いとチャンネルレベルのリリースゲートであり、Vitest や Docker パッケージ機構とは別です。
QA Lab ボックスも `OpenClaw Release Checks` の一部です。これは agentic
behavior とチャネルレベルのリリースゲートであり、Vitest や Docker
パッケージ機構とは別のものです。
リリース QA Lab カバレッジには次が含まれます。
リリース QA Lab カバレッジには以下が含まれます。
- エージェント的パリティパックを使用して OpenAI 候補レーンを Opus 4.6 ベースラインと比較するモックパリティゲート
- `qa-live-shared` 環境を使用する高速ライブ Matrix QA プロファイル
- Convex CI 認証情報リースを使用するライブ Telegram QA レーン
- リリーステレメトリーに明示的なローカル証明が必要な場合の `pnpm qa:otel:smoke`
- agentic parity pack を使用して OpenAI 候補レーンを Opus 4.6
ベースラインと比較する mock parity gate
- `qa-live-shared` 環境を使用する高速 live Matrix QA プロファイル
- Convex CI credential lease を使用する live Telegram QA レーン
- リリース telemetry に明示的なローカル証明が必要な場合の `pnpm qa:otel:smoke`
このボックスは、「リリースが QA シナリオとライブチャンネルフローで正しく動作するか」に答えるために使用します。リリースを承認するときは、パリティ、Matrix、Telegram レーンのアーティファクト URL を保持してください。完全な Matrix カバレッジは、デフォルトのリリースクリティカルレーンではなく、手動のシャード化された QA-Lab 実行として引き続き利用できます。
このボックスは「リリースが QA シナリオと live チャネルフローで正しく動作するか」に答えるために使用します。
リリースを承認するときは、parity、Matrix、Telegram レーンのアーティファクト URL を保持してください。
Full Matrix カバレッジは、デフォルトの release-critical レーンではなく、手動の sharded QA-Lab 実行として引き続き利用できます。
### パッケージ
パッケージボックスはインストール可能なプロダクトのゲートです。これは `Package Acceptance` とリゾルバー `scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。リゾルバーは候補を Docker E2E で消費される `package-under-test` tarball に正規化し、パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、ワークフローハーネス ref をパッケージソース ref から分離して保持します。
Package ボックスは、インストール可能な製品のゲートです。これは
`Package Acceptance` と resolver
`scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。resolver は候補を
Docker E2E が消費する `package-under-test` tarball に正規化し、
パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、
ワークフローハーネス ref をパッケージソース ref から分離します。
サポートされる候補ソース:
- `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な OpenClaw リリースバージョン
- `source=ref`: 選択された `workflow_ref` ハーネスで、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパックする
- `source=url`: 必須の `package_sha256` を指定して HTTPS `.tgz` をダウンロードする
- `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な OpenClaw リリース
バージョン
- `source=ref`: 選択した `workflow_ref` ハーネスで、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA
を pack する
- `source=url`: 必須の `package_sha256` を伴う HTTPS `.tgz` をダウンロードする
- `source=artifact`: 別の GitHub Actions 実行によってアップロードされた `.tgz` を再利用する
`OpenClaw Release Checks` は、`source=ref`、`package_ref=<release-ref>`、`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline`、`telegram_mode=mock-openai` で Package Acceptance を実行します。リリースパス Docker チャンクは、重複するインストール、更新、Plugin 更新レーンをカバーします。Package Acceptance は、同じ解決済み tarball に対して、アーティファクトネイティブなバンドル済みチャンネル互換性、オフライン Plugin フィクスチャ、Telegram パッケージ QA を維持します。これは、以前は Parallels が必要だったパッケージ/更新カバレッジの大部分に対する GitHub ネイティブな置き換えです。クロス OS リリースチェックは OS 固有のオンボーディング、インストーラー、プラットフォーム挙動に引き続き重要ですが、パッケージ/更新のプロダクト検証では Package Acceptance を優先してください。
`OpenClaw Release Checks` は、`source=ref`、
`package_ref=<release-ref>`、`suite_profile=custom`、
`docker_lanes=bundled-channel-deps-compat plugins-offline`、および
`telegram_mode=mock-openai` で Package Acceptance を実行します。release-path Docker チャンクは、
重複する install、update、および plugin-update レーンをカバーします。Package Acceptance は、
artifact-native の bundled-channel compat、offline plugin fixtures、および Telegram
package QA を、同じ解決済み tarball に対して保持します。これは、以前は
Parallels が必要だった package/update カバレッジの大半に対する GitHub-native の
置き換えです。cross-OS release checks は OS 固有のオンボーディング、
installer、および platform behavior について引き続き重要ですが、package/update の製品検証では
Package Acceptance を優先するべきです。
レガシー package-acceptance の許容は意図的に期限付きです。`2026.4.25` までのパッケージは、すでに npm に公開済みのメタデータギャップに対して互換性パスを使用できます。対象は tarball に含まれない非公開 QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャ内の欠落パッチファイル、欠落した永続化 `update.channel`、レガシー Plugin インストール記録の場所、欠落したマーケットプレイスインストール記録の永続化、`plugins update` 中の設定メタデータ移行です。公開済みの `2026.4.26` パッケージは、すでに出荷されたローカルビルドメタデータスタンプファイルについて警告しても構いません。それ以降のパッケージは、現代のパッケージ契約を満たす必要があります。同じギャップはリリース検証で失敗します。
レガシー package-acceptance の緩和は、意図的に期限付きです。
`2026.4.25` までのパッケージは、すでに npm に公開されたメタデータギャップについて互換性パスを使用できます:
tarball に含まれない private QA inventory entries、欠落した
`gateway install --wrapper`、tarball 由来の git
fixture に含まれない patch files、欠落した永続化 `update.channel`、レガシー Plugin install-record
locations、欠落した marketplace install-record persistence、および `plugins update` 中の config metadata
migration。公開済みの `2026.4.26` パッケージでは、すでに出荷された local build metadata stamp files について
警告が出る場合があります。それ以降のパッケージは、現代のパッケージ契約を満たす必要があります。同じギャップはリリース
検証で失敗します。
リリースの問いが実際にインストール可能なパッケージに関するものである場合は、より広い Package Acceptance プロファイルを使用します。
リリースの質問が実際のインストール可能パッケージに関する場合は、より広範な Package Acceptance プロファイルを使用します。
```bash
gh workflow run package-acceptance.yml \
@ -245,62 +438,85 @@ gh workflow run package-acceptance.yml \
-f workflow_ref=main \
-f source=npm \
-f package_spec=openclaw@beta \
-f suite_profile=product
-f suite_profile=product \
-f published_upgrade_survivor_baseline=openclaw@2026.4.26
```
一般的なパッケージプロファイル:
- `smoke`: 簡易パッケージインストール/チャンネル/エージェント、Gateway ネットワーク、設定リロードレーン
- `package`: ライブ ClawHub なしのインストール/更新/Plugin パッケージ契約。これはリリースチェックのデフォルト
- `product`: `package` に加えて MCP チャンネル、cron/subagent クリーンアップ、OpenAI web search、OpenWebUI
- `full`: OpenWebUI を含む Docker リリースパスチャンク
- `smoke`: 簡易パッケージ install/channel/agent、gateway network、および config
reload レーン
- `package`: live ClawHub なしの install/update/plugin package contracts。これは release-check
のデフォルトです
- `product`: `package` に MCP channels、cron/subagent cleanup、OpenAI web
search、および OpenWebUI を加えたもの
- `full`: OpenWebUI 付きの Docker release-path チャンク
- `custom`: 焦点を絞った再実行用の正確な `docker_lanes` リスト
パッケージ候補 Telegram 証明では、Package Acceptance で `telegram_mode=mock-openai` または `telegram_mode=live-frontier` を有効にします。このワークフローは解決済みの `package-under-test` tarball を Telegram レーンに渡します。スタンドアロン Telegram ワークフローは、公開後チェック用に公開済み npm spec を引き続き受け付けます。
package-candidate Telegram 証明には、Package Acceptance で `telegram_mode=mock-openai` または
`telegram_mode=live-frontier` を有効にします。ワークフローは、解決済みの
`package-under-test` tarball を Telegram レーンに渡します。単独の
Telegram ワークフローは、公開後チェック用に公開済み npm spec を引き続き受け付けます。
## NPM ワークフロー入力
`OpenClaw NPM Release` は、次のオペレーター制御入力を受け付けます。
`OpenClaw NPM Release` は、以下の operator-controlled inputs を受け付けます。
- `tag`: `v2026.4.2`、`v2026.4.2-1`、`v2026.4.2-beta.1` などの必須リリースタグ。`preflight_only=true` の場合は、検証専用プリフライトのために、現在の完全な 40 文字のワークフローブランチコミット SHA も使用できます
- `preflight_only`: 検証/ビルド/パッケージのみの場合は `true`、実際の公開パスの場合は `false`
- `preflight_run_id`: 実際の公開パスで必須。ワークフローが成功したプリフライト実行から準備済み tarball を再利用するために使用します
- `npm_dist_tag`: 公開パスの npm ターゲットタグ。デフォルトは `beta`
- `tag`: 必須のリリースタグ。例: `v2026.4.2`、`v2026.4.2-1`、または
`v2026.4.2-beta.1`。`preflight_only=true` の場合は、validation-only preflight 用に現在の
完全な 40 文字の workflow-branch commit SHA も使用できます
- `preflight_only`: validation/build/package のみの場合は `true`、実際の publish path の場合は `false`
- `preflight_run_id`: 実際の publish path で必須。これにより、ワークフローは成功した preflight run から
準備済み tarball を再利用します
- `npm_dist_tag`: publish path の npm target tag。デフォルトは `beta`
`OpenClaw Release Checks` は、次のオペレーター制御入力を受け付けます。
`OpenClaw Release Checks` は、以下の operator-controlled inputs を受け付けます。
- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを含むチェックでは、解決されたコミットが OpenClaw ブランチまたはリリースタグから到達可能である必要があります。
- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを持つチェックでは、
解決されたコミットが OpenClaw ブランチまたは
リリースタグから到達可能である必要があります。
ルール:
- stable タグと correction タグは `beta` または `latest` のいずれにも公開できます
- Beta プレリリースタグは `beta` にのみ公開できます
- `OpenClaw NPM Release` では、完全なコミット SHA 入力は `preflight_only=true` の場合にのみ許可されます
- `OpenClaw Release Checks` と `Full Release Validation` は常に検証専用です
- 実際の公開パスでは、プリフライト中に使用したものと同じ `npm_dist_tag` を使用する必要があります。ワークフローは、公開前にそのメタデータが継続していることを検証します
- stable タグと correction タグは、`beta` または `latest` のどちらにも公開できます
- Beta prerelease タグは `beta` にのみ公開できます
- `OpenClaw NPM Release` では、完全なコミット SHA 入力は
`preflight_only=true` の場合にのみ許可されます
- `OpenClaw Release Checks` と `Full Release Validation` は常に
validation-only です
- 実際の publish path は、preflight 中に使用したものと同じ `npm_dist_tag` を使用する必要があります。
ワークフローは、publish が続行される前にそのメタデータを検証します
## Stable npm リリース手順
## stable npm リリース手順
stable npm リリースを切る場合:
1. `preflight_only=true` で `OpenClaw NPM Release` を実行します
- タグが存在する前は、プリフライトワークフローの検証専用ドライランとして、現在の完全なワークフローブランチコミット SHA を使用できます
2. 通常の beta-first フローでは `npm_dist_tag=beta` を選択し、意図的に直接 stable 公開を行いたい場合にのみ `latest` を選択します
3. 1 つの手動ワークフローから通常 CI に加えてライブプロンプトキャッシュ、Docker、QA Lab、Matrix、Telegram カバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全なコミット SHA で `Full Release Validation` を実行します
4. 意図的に決定的な通常テストグラフだけが必要な場合は、代わりにリリース ref で手動の `CI` ワークフローを実行します
5. 成功した `preflight_run_id` を保存します
6. 同じ `tag`、同じ `npm_dist_tag`、保存した `preflight_run_id` を指定して、`preflight_only=false` で `OpenClaw NPM Release` を再度実行します
7. リリースが `beta` に着地した場合は、非公開の `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` ワークフローを使用して、その stable バージョンを `beta` から `latest` に昇格します
8. リリースが意図的に `latest` に直接公開され、`beta` もすぐに同じ stable ビルドを追従すべき場合は、同じ非公開ワークフローを使用して両方の dist-tag を stable バージョンに向けるか、そのスケジュールされた自己修復同期によって後で `beta` が移動するようにします
1. `preflight_only=true` で `OpenClaw NPM Release` を実行する
- タグが存在する前は、preflight ワークフローの検証専用ドライランに、
現在の完全なワークフローブランチのコミット SHA を使用できる
2. 通常の beta-first フローでは `npm_dist_tag=beta` を選び、意図的に直接 stable 公開したい場合にのみ
`latest` を選ぶ
3. 1 つの手動ワークフローから通常の CI に加えて live prompt cache、Docker、QA Lab、
Matrix、Telegram のカバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全な
コミット SHA で `Full Release Validation` を実行する
4. 決定的な通常のテストグラフだけが意図的に必要な場合は、代わりにリリース ref で
手動の `CI` ワークフローを実行する
5. 成功した `preflight_run_id` を保存する
6. `preflight_only=false`、同じ
`tag`、同じ `npm_dist_tag`、保存した `preflight_run_id` で `OpenClaw NPM Release` を再度実行する
7. リリースが `beta` に landed した場合は、private の
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
ワークフローを使用して、その stable バージョンを `beta` から `latest` に昇格する
8. リリースが意図的に `latest` へ直接公開され、`beta` も同じ stable build をすぐに追従すべき場合は、
同じ private ワークフローを使用して両方の dist-tag が stable バージョンを指すようにするか、スケジュールされた
自己修復同期で後から `beta` を移動させる
dist-tag の変更は、引き続き `NPM_TOKEN` が必要なため、セキュリティ上の理由で非公開リポジトリにあります。一方、公開リポジトリは OIDC のみの公開を維持します。
dist-tag の変更は、引き続き `NPM_TOKEN` が必要なためセキュリティ上 private repo にあり、
public repo は OIDC のみの公開を維持する。
これにより、直接公開パスと beta-first 昇格パスの両方が文書化され、オペレーターに見える状態になります。
これにより、直接公開パスと beta-first 昇格パスの両方が文書化され、operator から見える状態になる。
メンテナーがローカルの npm 認証にフォールバックする必要がある場合は、1Password
CLI (`op`) コマンドは専用の tmux セッション内でのみ実行してください。メインエージェントシェルから `op`
を直接呼び出さないでください。tmux 内に閉じ込めることで、プロンプト、
アラート、OTP 処理が観測可能になり、ホストアラートの繰り返しを防げます。
maintainer が local npm authentication にフォールバックする必要がある場合は、1Password CLI (`op`) コマンドを必ず専用の tmux セッション内でのみ実行する。main agent shell から `op` を直接呼び出してはならない。tmux 内に保つことで、プロンプト、アラート、OTP 処理を観測可能にし、繰り返し発生するホストアラートを防げる。
## 公開リファレンス
@ -314,10 +530,10 @@ CLI (`op`) コマンドは専用の tmux セッション内でのみ実行して
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
メンテナーは実際のランブックとして、非公開のリリースドキュメント
maintainer は、実際の runbook には private release docs の
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
を使用します。
を使用する。
## 関連
- [リリースチャンネル](/ja-JP/install/development-channels)
- [リリースチャネル](/ja-JP/install/development-channels)

147
docs/ja-JP/reference/full-release-validation.md Normal file
View File

@ -0,0 +1,147 @@
---
read_when:
- 完全リリース検証の実行または再実行
- stable と full のリリース検証プロファイルの比較
- リリース検証ステージの失敗をデバッグする
summary: 完全なリリース検証のステージ、子ワークフロー、リリースプロファイル、再実行ハンドル、証跡
title: 完全なリリース検証
x-i18n:
generated_at: "2026-05-01T05:03:22Z"
model: gpt-5.5
provider: openai
source_hash: dcbfafd744437c160c09a9c508a639781549193669b300e5249023f9f5dd4afe
source_path: reference/full-release-validation.md
workflow: 16
---
`Full Release Validation` はリリースの包括ワークフローです。プレリリースの検証のための単一の手動エントリーポイントですが、ほとんどの処理は子ワークフローで行われるため、失敗したボックスはリリース全体を最初からやり直さずに再実行できます。
通常は `main` のような信頼できるワークフロー ref から実行し、リリースブランチ、タグ、または完全なコミット SHA を `ref` として渡します。
```bash
gh workflow run full-release-validation.yml \
--ref main \
-f ref=release/YYYY.M.D \
-f provider=openai \
-f mode=both \
-f release_profile=stable
```
子ワークフローは、ハーネスには信頼できるワークフロー ref を使用し、テスト対象の候補には入力 `ref` を使用します。これにより、古いリリースブランチやタグを検証する場合でも、新しい検証ロジックを利用できます。
## トップレベルステージ
| ステージ | 詳細 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ターゲット解決 | **ジョブ:** `Resolve target ref`<br />**子ワークフロー:** なし<br />**証明内容:** リリースブランチ、タグ、または完全なコミット SHA を解決し、選択された入力を記録します。<br />**再実行:** これが失敗した場合は包括ワークフローを再実行します。 |
| Vitest と通常 CI | **ジョブ:** `Run normal full CI`<br />**子ワークフロー:** `CI`<br />**証明内容:** Linux Node レーン、バンドル済み Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Control UI i18n、包括ワークフロー経由の Android を含む、ターゲット ref に対する手動のフル CI グラフ。<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 パリティ、live Matrix、live Telegram。<br />**再実行:** `rerun_group=release-checks` またはより狭い release-checks ハンドル。 |
| 公開後 Telegram | **ジョブ:** `Run post-publish Telegram E2E`<br />**子ワークフロー:** `NPM Telegram Beta E2E`<br />**証明内容:** `npm_telegram_package_spec` が設定されている場合の、任意の公開済みパッケージ Telegram 検証。<br />**再実行:** `rerun_group=npm-telegram`。 |
| 包括ワークフロー検証 | **ジョブ:** `Verify full validation`<br />**子ワークフロー:** なし<br />**証明内容:** 記録された子実行の結論を再チェックし、子ワークフローから最も遅いジョブの表を追記します。<br />**再実行:** 失敗した子を再実行してグリーンにした後、このジョブのみを再実行します。 |
`ref=main` かつ `rerun_group=all` の場合、新しい包括ワークフローが古いものを置き換えます。親がキャンセルされると、そのモニターはすでにディスパッチした子ワークフローをすべてキャンセルします。リリースブランチとタグの検証実行は、デフォルトでは互いにキャンセルしません。
## リリースチェックのステージ
`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 />**テスト:** 候補 tarball を 1 つパックまたは解決し、下流のパッケージ向けチェック用に `release-package-under-test` をアップロードします。<br />**再実行:** 影響を受けるパッケージ、クロス OS、または live/E2E グループ。 |
| インストールスモーク | **ジョブ:** `Run install smoke`<br />**バッキングワークフロー:** `Install Smoke`<br />**テスト:** ルート Dockerfile スモークイメージ再利用、QR パッケージインストール、ルートと Gateway の Docker スモーク、インストーラー Docker テスト、Bun グローバルインストールの image-provider スモーク、高速なバンドル済み Plugin Docker 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 />**テスト:** リポジトリ E2E、live キャッシュ、OpenAI websocket ストリーミング、ネイティブ live プロバイダーと Plugin シャード、`release_profile` によって選択される 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 パッケージフィクスチャ、同じ tarball に対する mock-OpenAI Telegram パッケージ受け入れ。<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 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 />**テスト:** 選択された再実行グループに必要なリリースチェックジョブ。<br />**再実行:** 絞り込まれた子ジョブが通過した後に再実行します。 |
## Docker リリースパスチャンク
Docker リリースパスステージは、`live_suite_filter` が空の場合にこれらのチャンクを実行します。
| チャンク | カバレッジ |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `core` | Core Docker リリースパスのスモークレーン。 |
| `package-update-openai` | OpenAI パッケージのインストールと更新動作。 |
| `package-update-anthropic` | Anthropic パッケージのインストールと更新動作。 |
| `package-update-core` | プロバイダー中立のパッケージと更新動作。 |
| `plugins-runtime-plugins` | Plugin 動作を実行する Plugin ランタイムレーン。 |
| `plugins-runtime-services` | サービスベースの Plugin ランタイムレーン。要求された場合は OpenWebUI を含みます。 |
| `plugins-runtime-install-a` から `plugins-runtime-install-h` | 並列リリース検証のために分割された Plugin インストール/ランタイムバッチ。 |
| `bundled-channels-core` | バンドル済みチャネルの Docker 動作。 |
| `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` | バンドル済みチャネルの更新動作。 |
| `bundled-channels-contracts` | Docker リリースパス内のバンドル済みチャネル契約チェック。 |
再利用可能なライブ/E2E ワークフローで、失敗した Docker レーンが 1 つだけの場合は、対象を絞った `docker_lanes=<lane[,lane]>` を使用します。リリース成果物には、利用可能な場合、パッケージ成果物とイメージ再利用入力を含むレーンごとの再実行コマンドが含まれます。
## リリースプロファイル
`release_profile` は、リリースチェック内のライブ/プロバイダーの範囲のみを制御します。通常のフル CI、Plugin Prerelease、インストールスモーク、パッケージ受け入れ、QA Lab、または Docker リリースパスのチャンクは削除しません。
| プロファイル | 想定用途 | 含まれるライブ/プロバイダーのカバレッジ |
| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | 最速のリリースクリティカルなスモーク。 | OpenAI/コアのライブパス、OpenAI 向け Docker ライブモデル、ネイティブ Gateway コア、ネイティブ OpenAI Gateway プロファイル、ネイティブ OpenAI plugin、および Docker ライブ Gateway OpenAI。 |
| `stable` | デフォルトのリリース承認プロファイル。 | `minimum` に加えて、Anthropic、Google、MiniMax、バックエンド、ネイティブライブテストハーネス、Docker ライブ CLI バックエンド、Docker ACP バインド、Docker Codex ハーネス、および OpenCode Go スモークシャード。 |
| `full` | 広範な助言的スイープ。 | `stable` に加えて、助言的プロバイダー、plugin ライブシャード、およびメディアライブシャード。 |
## `full` のみの追加項目
これらのスイートは `stable` ではスキップされ、`full` に含まれます。
| 領域 | `full` のみのカバレッジ |
| -------------------------------- | ------------------------------------------------------------------------------- |
| Docker ライブモデル | OpenCode Go、OpenRouter、xAI、Z.ai、および Fireworks。 |
| Docker ライブ Gateway | DeepSeek、Fireworks、OpenCode Go、OpenRouter、xAI、および Z.ai の助言的シャード。 |
| ネイティブ Gateway プロバイダープロファイル | Fireworks、DeepSeek、完全な OpenCode Go モデルシャード、OpenRouter、xAI、および Z.ai。 |
| ネイティブ plugin ライブシャード | Plugins A-K、L-N、O-Z other、Moonshot、および xAI。 |
| ネイティブメディアライブシャード | Audio、Google music、MiniMax music、および video groups A-D。 |
`stable` には `native-live-src-gateway-profiles-opencode-go-smoke` が含まれます。`full` は代わりに、より広範な OpenCode Go モデルシャードを使用します。
## 対象を絞った再実行
関連しないリリースボックスの繰り返しを避けるには、`rerun_group` を使用します。
| ハンドル | 範囲 |
| ------------------- | ------------------------------------------------- |
| `all` | すべての Full Release Validation ステージ。 |
| `ci` | 手動フル CI 子のみ。 |
| `plugin-prerelease` | Plugin Prerelease 子のみ。 |
| `release-checks` | すべての OpenClaw Release Checks ステージ。 |
| `install-smoke` | リリースチェックまでの Install Smoke。 |
| `cross-os` | Cross-OS リリースチェック。 |
| `live-e2e` | リポジトリ/ライブ E2E および Docker リリースパス検証。 |
| `package` | Package Acceptance。 |
| `qa` | QA パリティと QA ライブレーン。 |
| `qa-parity` | QA パリティレーンとレポートのみ。 |
| `qa-live` | QA ライブ Matrix と Telegram のみ。 |
| `npm-telegram` | 公開後の任意の Telegram E2E のみ。 |
1 つのライブスイートが失敗した場合は、`rerun_group=live-e2e` とともに `live_suite_filter` を使用します。有効なフィルター ID は再利用可能なライブ/E2E ワークフローで定義されており、`docker-live-models`、`live-gateway-docker`、`live-gateway-anthropic-docker`、`live-gateway-google-docker`、`live-gateway-minimax-docker`、`live-gateway-advisory-docker`、`live-cli-backend-docker`、`live-acp-bind-docker`、および `live-codex-harness-docker` が含まれます。
## 保持する証跡
リリースレベルの索引として `Full Release Validation` のサマリーを保持します。これは子 run ID にリンクし、最も遅いジョブの表を含みます。失敗時は、まず子ワークフローを確認し、その後で上記の最小の一致するハンドルを再実行します。
有用な成果物:
- `OpenClaw Release Checks` からの `release-package-under-test`
- `.artifacts/docker-tests/` 以下の Docker リリースパス成果物
- Package Acceptance の `package-under-test` と Docker 受け入れ成果物
- 各 OS とスイートの Cross-OS リリースチェック成果物
- QA パリティ、Matrix、および Telegram の成果物
## ワークフローファイル
- `.github/workflows/full-release-validation.yml`
- `.github/workflows/openclaw-release-checks.yml`
- `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml`
- `.github/workflows/plugin-prerelease.yml`
- `.github/workflows/install-smoke.yml`
- `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- `.github/workflows/package-acceptance.yml`

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

File diff suppressed because one or more lines are too long

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

@ -1,32 +1,38 @@
---
read_when:
- Pluginのインストールまたは設定
- Plugin のインストールまたは設定
- Plugin の検出と読み込みルールを理解する
- Codex/Claude 互換の Plugin バンドルを扱う
sidebarTitle: Install and Configure
summary: OpenClaw Plugin をインストール、設定、管理する
title: Plugin
x-i18n:
generated_at: "2026-04-30T05:39:28Z"
generated_at: "2026-05-01T05:03:57Z"
model: gpt-5.5
provider: openai
source_hash: 7a12d158053c13b47a56d8d6b382818962e9b5109fdf8ededd3ecf92b83089e6
source_hash: 69f876df0c2ed3ff356ada9462b56f2b5a65a662b64b328ecc97d8b463036934
source_path: tools/plugin.md
workflow: 16
---
Plugins は、チャンネル、モデルプロバイダー、エージェントハーネス、ツール、Skills、音声、リアルタイム文字起こし、リアルタイム音声、メディア理解、画像生成、動画生成、Web 取得、Web 検索などの新しい機能で OpenClaw を拡張します。一部の Plugin は **core**（OpenClaw に同梱）で、その他は **external** です。ほとんどの外部 Plugin は [ClawHub](/ja-JP/tools/clawhub) を通じて公開および検出されます。npm は、その移行が完了するまでの間、直接インストールと OpenClaw 所有 Plugin パッケージの一時的なセット向けに引き続きサポートされます。
PluginはOpenClawを新しい機能で拡張します: チャネル、モデルプロバイダー、
エージェントハーネス、ツール、Skills、音声、リアルタイム文字起こし、リアルタイム
音声、メディア理解、画像生成、動画生成、Web取得、Web
検索などです。一部のPluginは**コア**（OpenClawに同梱）で、その他は
**外部**です。ほとんどの外部Pluginは
[ClawHub](/ja-JP/tools/clawhub)を通じて公開、検出されます。npmは直接インストールと、その移行が完了するまでの
OpenClaw所有Pluginパッケージの一時的なセット向けに、引き続きサポートされます。
## クイックスタート
<Steps>
<Step title="読み込まれているものを確認する">
<Step title="See what is loaded">
```bash
openclaw plugins list
```
</Step>
<Step title="Plugin をインストールする">
<Step title="Install a plugin">
```bash
# From npm
openclaw plugins install npm:@acme/openclaw-plugin
@ -38,17 +44,17 @@ Plugins は、チャンネル、モデルプロバイダー、エージェント
</Step>
<Step title="Gateway を再起動する">
<Step title="Restart the Gateway">
```bash
openclaw gateway restart
```
その後、設定ファイルの `plugins.entries.\<id\>.config` で設定します。
次に、設定ファイル内の`plugins.entries.\<id\>.config`で設定します。
</Step>
</Steps>
チャットネイティブな制御を好む場合は、`commands.plugins: true` を有効にして次を使用します。
チャットネイティブの制御を好む場合は、`commands.plugins: true`を有効にして次を使用します:
```text
/plugin install clawhub:<package>
@ -56,38 +62,67 @@ Plugins は、チャンネル、モデルプロバイダー、エージェント
/plugin enable <plugin-id>
```
インストールパスは CLI と同じリゾルバーを使用します。ローカルパス/アーカイブ、明示的な `clawhub:<pkg>`、明示的な `npm:<pkg>`、または素のパッケージ指定（まず ClawHub、次に npm フォールバック）です。
インストールパスはCLIと同じリゾルバーを使用します: ローカルパス/アーカイブ、明示的な
`clawhub:<pkg>`、明示的な`npm:<pkg>`、または素のパッケージ指定（ClawHubが先で、その後
npmフォールバック）。
設定が無効な場合、通常インストールはフェイルクローズし、`openclaw doctor --fix` を案内します。唯一の回復例外は、`openclaw.install.allowInvalidConfigRecovery` にオプトインした Plugin 向けの狭い範囲の同梱 Plugin 再インストールパスです。
Gateway 起動中、1 つの Plugin の無効な設定はその Plugin に隔離されます。起動は `plugins.entries.<id>.config` の問題をログに記録し、読み込み中にその Plugin をスキップして、他の 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 を再度有効化してください。
設定が無効な場合、通常インストールはフェイルクローズし、
`openclaw doctor --fix`を案内します。唯一の復旧例外は、
`openclaw.install.allowInvalidConfigRecovery`を選択したPlugin向けの、狭い同梱Plugin
再インストールパスです。
Gateway起動中、1つのPluginの無効な設定はそのPluginに分離されます:
起動時に`plugins.entries.<id>.config`の問題をログに記録し、読み込み時にそのPluginをスキップし、
他の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を再度有効化してください。
パッケージ化された OpenClaw インストールは、すべての同梱 Plugin のランタイム依存関係ツリーを先行してインストールしません。OpenClaw 所有の同梱 Plugin が Plugin 設定、レガシーチャンネル設定、またはデフォルト有効のマニフェストからアクティブな場合、起動はその Plugin をインポートする前に、その Plugin が宣言したランタイム依存関係だけを修復します。永続化されたチャンネル認証状態だけでは、Gateway 起動時のランタイム依存関係修復のために同梱チャンネルは有効化されません。
明示的な無効化は引き続き優先されます。`plugins.entries.<id>.enabled: false`、`plugins.deny`、`plugins.enabled: false`、`channels.<id>.enabled: false` は、その Plugin/チャンネルの同梱ランタイム依存関係の自動修復を防ぎます。
空でない `plugins.allow` も、デフォルト有効の同梱ランタイム依存関係修復の範囲を制限します。明示的な同梱チャンネル有効化（`channels.<id>.enabled: true`）では、そのチャンネルの Plugin 依存関係を引き続き修復できます。
外部 Plugin とカスタム読み込みパスは、引き続き `openclaw plugins install` を通じてインストールする必要があります。
パッケージ化されたOpenClawインストールは、すべての同梱Pluginの
ランタイム依存ツリーを先行してインストールしません。同梱されたOpenClaw所有Pluginが
Plugin設定、レガシーチャネル設定、またはデフォルト有効のマニフェストから有効になっている場合、起動は
そのPluginをインポートする前に、そのPluginが宣言したランタイム依存関係だけを修復します。
永続化されたチャネル認証状態だけでは、Gateway起動時のランタイム依存関係修復のために
同梱チャネルは有効化されません。
明示的な無効化は引き続き優先されます: `plugins.entries.<id>.enabled: false`、
`plugins.deny`、`plugins.enabled: false`、`channels.<id>.enabled: false`は、
そのPlugin/チャネルの同梱ランタイム依存関係の自動修復を防ぎます。
空でない`plugins.allow`も、デフォルト有効の同梱ランタイム依存関係
修復を制限します。明示的な同梱チャネル有効化（`channels.<id>.enabled: true`）は、
引き続きそのチャネルのPlugin依存関係を修復できます。
外部Pluginとカスタム読み込みパスは、引き続き
`openclaw plugins install`を通じてインストールする必要があります。
## 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/` |
| **ネイティブ** | `openclaw.plugin.json` + ランタイムモジュール。プロセス内で実行 | 公式Plugin、コミュニティnpmパッケージ |
| **バンドル** | Codex/Claude/Cursor互換レイアウト。OpenClaw機能にマッピングされる | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
どちらも `openclaw plugins list` に表示されます。Bundle の詳細は [Plugin Bundles](/ja-JP/plugins/bundles) を参照してください。
どちらも`openclaw plugins list`に表示されます。バンドルの詳細は[Plugin Bundles](/ja-JP/plugins/bundles)を参照してください。
Native Plugin を作成する場合は、[Building Plugins](/ja-JP/plugins/building-plugins)
と [Plugin SDK Overview](/ja-JP/plugins/sdk-overview) から始めてください。
ネイティブPluginを作成する場合は、[Building Plugins](/ja-JP/plugins/building-plugins)
と[Plugin SDK Overview](/ja-JP/plugins/sdk-overview)から始めてください。
## パッケージエントリポイント
Native Plugin npm パッケージは、`package.json` で `openclaw.extensions` を宣言する必要があります。
各エントリはパッケージディレクトリ内に収まり、読み取り可能なランタイムファイル、または `src/index.ts` から `dist/index.js` のように推論されたビルド済み JavaScript ピアを持つ TypeScript ソースファイルへ解決される必要があります。
ネイティブPluginのnpmパッケージは、`package.json`で`openclaw.extensions`を宣言する必要があります。
各エントリはパッケージディレクトリ内にとどまり、読み取り可能な
ランタイムファイル、または`src/index.ts`から`dist/index.js`のように推定されるビルド済みJavaScript
ピアを持つTypeScriptソースファイルに解決される必要があります。
公開済みランタイムファイルがソースエントリと同じパスに存在しない場合は、`openclaw.runtimeExtensions` を使用します。存在する場合、`runtimeExtensions` はすべての `extensions` エントリに対して正確に 1 つのエントリを含む必要があります。リストが一致しない場合、ソースパスへ黙ってフォールバックするのではなく、インストールと Plugin 検出は失敗します。
公開済みランタイムファイルがソースエントリと同じパスに存在しない場合は、
`openclaw.runtimeExtensions`を使用します。存在する場合、`runtimeExtensions`には
すべての`extensions`エントリに対して正確に1つのエントリが含まれている必要があります。一致しないリストは、ソースパスへ暗黙にフォールバックするのではなく、インストールと
Plugin検出を失敗させます。
```json
{
@ -99,15 +134,20 @@ Native Plugin npm パッケージは、`package.json` で `openclaw.extensions`
}
```
## 公式 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 パッケージを deprecated と報告する場合、そのパッケージバージョンは古い外部パッケージ系列のものです。より新しい npm パッケージが公開されるまで、現在の OpenClaw に同梱された Plugin またはローカルチェックアウトを使用してください。
npmが`@openclaw/*`Pluginパッケージを非推奨として報告する場合、そのパッケージ
バージョンは古い外部パッケージ列のものです。新しいnpmパッケージが公開されるまでは、
現在のOpenClawに同梱されているPlugin、またはローカルチェックアウトを使用してください。
| Plugin | パッケージ | ドキュメント |
| Plugin | パッケージ | ドキュメント |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/ja-JP/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/ja-JP/channels/discord) |
@ -123,10 +163,10 @@ npm が `@openclaw/*` Plugin パッケージを deprecated と報告する場合
| Zalo | `@openclaw/zalo` | [Zalo](/ja-JP/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/ja-JP/plugins/zalouser) |
### Core（OpenClaw に同梱）
### コア（OpenClawに同梱）
<AccordionGroup>
<Accordion title="モデルプロバイダー（デフォルトで有効）">
<Accordion title="Model providers (enabled by default)">
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
@ -134,26 +174,27 @@ npm が `@openclaw/*` Plugin パッケージを deprecated と報告する場合
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
</Accordion>
<Accordion title="メモリ Plugin">
- `memory-core` — 同梱メモリ検索（デフォルトは `plugins.slots.memory` 経由）
- `memory-lancedb` — 自動リコール/キャプチャ付きのオンデマンドインストール長期メモリ（`plugins.slots.memory = "memory-lancedb"` を設定）
<Accordion title="Memory plugins">
- `memory-core` — 同梱メモリ検索（デフォルトは`plugins.slots.memory`経由）
- `memory-lancedb` — 自動リコール/キャプチャ付きのオンデマンドインストール長期メモリ（`plugins.slots.memory = "memory-lancedb"`を設定）
OpenAI 互換の embedding セットアップ、Ollama の例、リコール制限、トラブルシューティングについては [Memory LanceDB](/ja-JP/plugins/memory-lancedb) を参照してください。
OpenAI互換の埋め込みセットアップ、Ollamaの例、リコール上限、トラブルシューティングについては、
[Memory LanceDB](/ja-JP/plugins/memory-lancedb)を参照してください。
</Accordion>
<Accordion title="音声プロバイダー（デフォルトで有効）">
<Accordion title="Speech providers (enabled by default)">
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="その他">
- `browser` — ブラウザーツール、`openclaw browser` CLI、`browser.request` Gateway メソッド、ブラウザーランタイム、デフォルトのブラウザー制御サービス向けの同梱ブラウザー Plugin（デフォルトで有効。置き換える前に無効化してください）
- `copilot-proxy` — VS Code Copilot Proxy ブリッジ（デフォルトで無効）
<Accordion title="Other">
- `browser` — ブラウザツール、`openclaw browser` CLI、`browser.request` gatewayメソッド、ブラウザランタイム、デフォルトブラウザ制御サービス向けの同梱ブラウザPlugin（デフォルトで有効。置き換える前に無効化してください）
- `copilot-proxy` — VS Code Copilot Proxyブリッジ（デフォルトで無効）
</Accordion>
</AccordionGroup>
サードパーティ Plugin を探している場合は、[Community Plugins](/ja-JP/plugins/community) を参照してください。
サードパーティPluginを探していますか？[Community Plugins](/ja-JP/plugins/community)を参照してください。
## 設定
@ -171,34 +212,50 @@ npm が `@openclaw/*` Plugin パッケージを deprecated と報告する場合
}
```
| フィールド | 説明 |
| ---------------- | --------------------------------------------------------- |
| `enabled` | マスタートグル（デフォルト: `true`） |
| `allow` | Plugin 許可リスト（任意） |
| `deny` | Plugin 拒否リスト（任意。deny が優先） |
| `load.paths` | 追加の Plugin ファイル/ディレクトリ |
| `slots` | 排他的なスロットセレクター（例: `memory`, `contextEngine`） |
| `entries.\<id\>` | Plugin ごとのトグル + 設定 |
| フィールド | 説明 |
| ---------------- | -------------------------------------------------------- |
| `enabled` | マスタートグル（デフォルト: `true`） |
| `allow` | Plugin許可リスト（任意） |
| `deny` | Plugin拒否リスト（任意。拒否が優先） |
| `load.paths` | 追加のPluginファイル/ディレクトリ |
| `slots` | 排他的なスロットセレクター（例: `memory`、`contextEngine`） |
| `entries.\<id\>` | Pluginごとのトグル + 設定 |
設定変更には **Gateway の再起動が必要** です。Gateway が設定監視 + インプロセス再起動を有効にして実行されている場合（デフォルトの `openclaw gateway` パス）、その再起動は通常、設定の書き込みが反映された少し後に自動的に実行されます。Native Plugin のランタイムコードやライフサイクルフックには、サポートされているホットリロードパスはありません。更新された `register(api)` コード、`api.on(...)` フック、ツール、サービス、またはプロバイダー/ランタイムフックが実行されることを期待する前に、ライブチャンネルを提供している Gateway プロセスを再起動してください。
`plugins.allow`は排他的です。空でない場合、`tools.allow`に`"*"`または特定のPlugin所有
ツール名が含まれていても、一覧にあるPluginだけが読み込まれるかツールを公開できます。
ツール許可リストがPluginツールを参照する場合は、所有するPlugin IDを
`plugins.allow`に追加するか、`plugins.allow`を削除してください。`openclaw doctor`はこの
形状について警告します。
`openclaw plugins list` はローカルの Plugin レジストリ/設定スナップショットです。そこにある `enabled` Plugin は、永続化されたレジストリと現在の設定がその Plugin の参加を許可していることを意味します。すでに実行中のリモート Gateway 子プロセスが同じ Plugin コードへ再起動済みであることを証明するものではありません。ラッパープロセスを使用する VPS/コンテナーセットアップでは、実際の `openclaw gateway run` プロセスへ再起動を送信するか、実行中の Gateway に対して `openclaw gateway restart` を使用してください。
設定変更には**Gatewayの再起動が必要**です。Gatewayが設定
監視 + プロセス内再起動を有効にして実行されている場合（デフォルトの`openclaw gateway`パス）、
通常は設定書き込みが反映された少し後にその再起動が自動的に実行されます。
ネイティブPluginのランタイムコードやライフサイクル
フックに対してサポートされるホットリロードパスはありません。更新された`register(api)`コード、`api.on(...)`フック、ツール、サービス、または
プロバイダー/ランタイムフックが実行されることを期待する前に、ライブチャネルを提供しているGatewayプロセスを再起動してください。
<Accordion title="Plugin の状態: 無効、欠落、無効">
- **無効**: Plugin は存在しますが、有効化ルールによってオフになっています。設定は保持されます。
- **欠落**: 設定が、検出で見つからなかった Plugin ID を参照しています。
- **無効**: Plugin は存在しますが、その設定が宣言されたスキーマと一致しません。Gateway 起動はその Plugin だけをスキップします。`openclaw doctor --fix` は、そのエントリを無効化し設定ペイロードを削除することで、無効なエントリを隔離できます。
`openclaw plugins list`はローカルPluginレジストリ/設定スナップショットです。そこで
`enabled`になっているPluginは、永続化されたレジストリと現在の設定がそのPluginの参加を許可していることを意味します。
すでに実行中のリモートGateway
子プロセスが同じPluginコードで再起動済みであることを証明するものではありません。ラッパープロセスを伴うVPS/コンテナセットアップでは、
実際の`openclaw gateway run`プロセスへ再起動を送るか、実行中のGatewayに対して
`openclaw gateway restart`を使用してください。
<Accordion title="Plugin states: disabled vs missing vs invalid">
- **無効**: Pluginは存在するが、有効化ルールによりオフになっています。設定は保持されます。
- **欠落**: 設定が、検出で見つからなかったPlugin IDを参照しています。
- **無効**: Pluginは存在するが、その設定が宣言されたスキーマと一致しません。Gateway起動はそのPluginだけをスキップします。`openclaw doctor --fix`は、そのPluginを無効化し、設定ペイロードを削除して、無効なエントリを隔離できます。
</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">
@ -210,57 +267,35 @@ OpenClaw は次の順序で Plugin をスキャンします（最初の一致が
</Step>
<Step title="同梱 Plugin">
OpenClaw に同梱されています。多くはデフォルトで有効です（モデルプロバイダー、音声）。
OpenClaw に同梱されています。多くはデフォルトで有効化されています（モデルプロバイダー、音声）。
その他は明示的な有効化が必要です。
</Step>
</Steps>
パッケージ化されたインストールと Docker イメージは、通常、コンパイル済みの
`dist/extensions` ツリーから同梱 Plugin を解決します。同梱 Plugin のソースディレクトリが、
対応するパッケージ化済みソースパスに bind mount されている場合、たとえば
`/app/extensions/synology-chat` のような場合、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.deny` は常に allow より優先されます
- `plugins.entries.\<id\>.enabled: false` はその Plugin を無効化します
- ワークスペース由来の Plugin は**デフォルトで無効**です（明示的に有効化する必要があります）
- ワークスペース由来の Plugin は **デフォルトで無効** です（明示的な有効化が必要です）
- 同梱 Plugin は、上書きされない限り、組み込みのデフォルト有効セットに従います
- 排他的スロットは、そのスロットで選択された Plugin を強制的に有効化できます
- 一部のオプトイン同梱 Plugin は、プロバイダーモデル参照、チャンネル設定、ハーネス
runtime など、設定で 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 は、設定で Plugin 所有のサーフェス（プロバイダーモデル参照、チャンネル設定、ハーネスランタイムなど）が指定されると自動的に有効化されます
- `plugins.enabled: false` が有効な間、古い Plugin 設定は保持されます。古い id を削除したい場合は、doctor cleanup を実行する前に Plugin を再度有効化します
- OpenAI 系の Codex ルートは個別の Plugin 境界を維持します:
`openai-codex/*` は OpenAI Plugin に属し、同梱 Codex app-server Plugin は `agentRuntime.id: "codex"` またはレガシーの `codex/*` モデル参照で選択されます
## runtime hook のトラブルシューティング
## ランタイムフックのトラブルシューティング
Plugin が `plugins list` に表示されているのに、ライブチャットトラフィックで
`register(api)` の副作用や hook が実行されない場合は、まず次を確認してください。
Plugin が `plugins list` に表示されているのに、ライブチャットトラフィックで `register(api)` の副作用やフックが実行されない場合は、まず次を確認してください。
- `openclaw gateway status --deep --require-rpc` を実行し、アクティブな
Gateway URL、プロファイル、設定パス、プロセスが編集対象のものであることを確認します。
- Plugin のインストール/設定/コード変更後に、ライブ Gateway を再起動します。ラッパー
コンテナでは、PID 1 は supervisor にすぎない場合があります。子プロセスである
`openclaw gateway run` プロセスを再起動するか、シグナルを送ります。
- `openclaw plugins inspect <id> --json` を使って hook 登録と診断を確認します。
`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end` などの
非同梱 conversation hook には
`plugins.entries.<id>.hooks.allowConversationAccess=true` が必要です。
- モデル切り替えには、`before_model_resolve` を優先してください。これは agent turn のモデル
解決前に実行されます。`llm_output` は、モデル試行が assistant 出力を生成した後にのみ実行されます。
- 有効なセッションモデルの証明には、`openclaw sessions` または
Gateway のセッション/ステータスサーフェスを使用し、プロバイダーペイロードをデバッグする場合は
`--raw-stream --raw-stream-path <path>` を付けて Gateway を起動します。
- `openclaw gateway status --deep --require-rpc` を実行し、アクティブな Gateway URL、プロファイル、設定パス、プロセスが編集対象と一致していることを確認します。
- Plugin のインストール、設定、コード変更後にライブ Gateway を再起動します。ラッパーコンテナでは、PID 1 がスーパーバイザーにすぎない場合があります。その場合は、子の `openclaw gateway run` プロセスを再起動するかシグナルを送ります。
- `openclaw plugins inspect <id> --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 を起動します。
### チャンネルまたはツール所有権の重複
@ -270,32 +305,24 @@ Plugin が `plugins list` に表示されているのに、ライブチャット
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
これは、有効化された複数の Plugin が同じチャンネル、セットアップフロー、またはツール名を所有しようとしていることを意味します。最も一般的な原因は、同じチャンネル id を提供するようになった同梱 Plugin の横に、外部チャンネル Plugin がインストールされていることです。
これは、複数の有効な Plugin が同じチャンネル、セットアップフロー、またはツール名を所有しようとしていることを意味します。最も一般的な原因は、同じチャンネル id を提供するようになった同梱 Plugin の横に外部チャンネル Plugin がインストールされていることです。
デバッグ手順:
- `openclaw plugins list --enabled --verbose` を実行して、有効なすべての Plugin と
由来を確認します。
- 疑わしい各 Plugin に対して `openclaw plugins inspect <id> --json` を実行し、
`channels`、`channelConfigs`、`tools`、診断を比較します。
- Plugin パッケージをインストールまたは削除した後、`openclaw plugins registry --refresh` を実行して、
永続化されたメタデータが現在のインストールを反映するようにします。
- インストール、registry、または設定を変更した後は Gateway を再起動します。
- `openclaw plugins list --enabled --verbose` を実行し、有効なすべての Plugin と由来を確認します。
- 疑わしい各 Plugin について `openclaw plugins inspect <id> --json` を実行し、`channels`、`channelConfigs`、`tools`、診断を比較します。
- Plugin パッケージをインストールまたは削除した後は、`openclaw plugins registry --refresh` を実行して、永続化されたメタデータが現在のインストールを反映するようにします。
- インストール、レジストリ、または設定の変更後に Gateway を再起動します。
修正オプション:
- ある 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 所有のツール名を変更して、
runtime サーフェスが曖昧にならないようにします。
- ある 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
{
@ -308,10 +335,10 @@ Plugin が `plugins list` に表示されているのに、ライブチャット
}
```
| スロット | 制御対象 | デフォルト |
| --------------- | ------------------------- | ------------------- |
| `memory` | アクティブメモリ Plugin | `memory-core` |
| `contextEngine` | アクティブ context engine | `legacy` (built-in) |
| スロット | 制御対象 | デフォルト |
| --------------- | --------------------- | ------------------- |
| `memory` | アクティブメモリ Plugin | `memory-core` |
| `contextEngine` | アクティブコンテキストエンジン | `legacy`（組み込み） |
## CLI リファレンス
@ -351,75 +378,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 または hook pack をその場で上書きします。
追跡対象の npm Plugin の通常アップグレードには
`openclaw plugins update <id-or-npm-spec>` を使用してください。これは `--link` とは併用できません。
`--link` は管理対象のインストール先へコピーする代わりに、ソースパスを再利用します。
`--force` は、既存のインストール済み Plugin またはフックパックをその場で上書きします。追跡対象 npm Plugin の通常のアップグレードには `openclaw plugins update <id-or-npm-spec>` を使用します。これは `--link` とは併用できません。`--link` は管理対象インストール先へコピーする代わりに、ソースパスを再利用します。
`plugins.allow` がすでに設定されている場合、`openclaw plugins install` は
インストールされた Plugin id をその allowlist に追加してから有効化します。同じ Plugin id が
`plugins.deny` に存在する場合、インストールはその古い deny エントリを削除するため、
再起動後すぐに明示的なインストールを読み込めます。
`plugins.allow` がすでに設定されている場合、`openclaw plugins install` はインストールした Plugin id を、その Plugin を有効化する前に allowlist へ追加します。同じ Plugin id が `plugins.deny` に存在する場合、install はその古い deny エントリを削除するため、明示的にインストールした Plugin は再起動後すぐに読み込み可能になります。
OpenClaw は、Plugin インベントリ、contribution 所有権、起動計画の cold read モデルとして、
永続化されたローカル Plugin registry を保持します。インストール、更新、
アンインストール、有効化、無効化のフローは、Plugin 状態を変更した後にその registry を更新します。
同じ `plugins/installs.json` ファイルは、トップレベルの `installRecords` に永続的なインストールメタデータを、
`plugins` に再構築可能な manifest メタデータを保持します。registry が存在しない、古い、または無効な場合、
`openclaw plugins registry --refresh` は、Plugin runtime モジュールを読み込まずに、
インストール記録、設定ポリシー、manifest/package メタデータから manifest ビューを再構築します。
`openclaw plugins update <id-or-npm-spec>` は追跡対象のインストールに適用されます。
dist-tag または正確なバージョンを含む npm パッケージ spec を渡すと、パッケージ名を
追跡対象の Plugin レコードへ解決し、今後の更新用に新しい spec を記録します。
バージョンなしのパッケージ名を渡すと、正確に pin されたインストールは registry の
デフォルトリリースラインへ戻ります。インストール済みの npm Plugin がすでに解決済みバージョンおよび記録済み
artifact identity と一致している場合、OpenClaw はダウンロード、再インストール、設定の書き換えを行わずに更新をスキップします。
OpenClaw は、Plugin インベントリ、コントリビューション所有権、起動計画のコールド読み取りモデルとして、永続化されたローカル Plugin レジストリを保持します。インストール、更新、アンインストール、有効化、無効化の各フローは、Plugin 状態を変更した後にそのレジストリを更新します。同じ `plugins/installs.json` ファイルは、永続的なインストールメタデータをトップレベルの `installRecords` に、再構築可能なマニフェストメタデータを `plugins` に保持します。レジストリが存在しない、古い、または無効な場合、`openclaw plugins registry
--refresh` は、Plugin ランタイムモジュールを読み込まずに、インストール記録、設定ポリシー、マニフェスト/パッケージメタデータからマニフェストビューを再構築します。
`openclaw plugins update <id-or-npm-spec>` は追跡対象インストールに適用されます。dist-tag または正確なバージョンを含む npm パッケージ spec を渡すと、パッケージ名を追跡対象 Plugin レコードへ解決し直し、今後の更新用に新しい spec を記録します。バージョンなしでパッケージ名を渡すと、正確にピン留めされたインストールがレジストリのデフォルトリリースラインへ戻ります。インストール済み npm Plugin が解決済みバージョンおよび記録されたアーティファクト ID とすでに一致する場合、OpenClaw はダウンロード、再インストール、設定の書き換えを行わずに更新をスキップします。
`--pin` は npm 専用です。`--marketplace` とは併用できません。marketplace インストールは
npm spec ではなく marketplace ソースメタデータを永続化するためです。
`--pin` は npm 専用です。`--marketplace` とは併用できません。marketplace インストールは npm spec ではなく marketplace ソースメタデータを永続化するためです。
`--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーによる誤検出に対する
break-glass オーバーライドです。Plugin のインストールと Plugin の更新が、組み込みの
`critical` findings を越えて続行できるようにしますが、Plugin の `before_install` ポリシーブロックや
スキャン失敗によるブロックは依然として回避しません。インストールスキャンは、パッケージ化された test mock をブロックしないように、
`tests/`、`__tests__/`、`*.test.*`、`*.spec.*` などの一般的なテストファイルやディレクトリを無視します。
宣言された Plugin runtime entrypoint は、それらの名前のいずれかを使用していても引き続きスキャンされます。
`--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーによる誤検知に対する緊急用の上書きです。これにより、組み込みの `critical` findings を超えて Plugin インストールと Plugin 更新を続行できますが、Plugin の `before_install` ポリシーブロックやスキャン失敗によるブロックは回避しません。インストールスキャンは、パッケージ化されたテストモックでブロックされるのを避けるため、`tests/`、`__tests__/`、`*.test.*`、`*.spec.*` などの一般的なテストファイルやディレクトリを無視します。ただし、宣言された Plugin ランタイムエントリポイントは、それらの名前のいずれかを使用していても引き続きスキャンされます。
この CLI フラグは、Plugin のインストール/更新フローにのみ適用されます。Gateway-backed skill の
依存関係インストールでは、代わりに対応する `dangerouslyForceUnsafeInstall` request
override を使用し、`openclaw skills install` は別個の ClawHub
skill ダウンロード/インストールフローのままです。
この CLI フラグは Plugin のインストール/更新フローにのみ適用されます。Gateway が支える skill 依存関係インストールでは、代わりに対応する `dangerouslyForceUnsafeInstall` リクエスト上書きを使用します。一方、`openclaw skills install` は引き続き別個の ClawHub skill ダウンロード/インストールフローです。
ClawHub で公開した Plugin がスキャンによって非表示またはブロックされた場合は、
ClawHub dashboard を開くか、`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 list/inspect/enable/disable フローに参加します。
現在の runtime サポートには、bundle skills、Claude command-skills、
Claude `settings.json` defaults、Claude `.lsp.json` と manifest 宣言の
`lspServers` defaults、Cursor command-skills、互換 Codex hook
ディレクトリが含まれます。
互換バンドルは、同じ Plugin list/inspect/enable/disable フローに参加します。現在のランタイムサポートには、bundle skills、Claude command-skills、Claude `settings.json` デフォルト、Claude `.lsp.json` とマニフェスト宣言 `lspServers` デフォルト、Cursor command-skills、互換 Codex フックディレクトリが含まれます。
`openclaw plugins inspect <id>` は、検出された bundle capabilities に加えて、
bundle-backed Plugin のサポート対象または非サポート対象の MCP および LSP server entry も報告します。
`openclaw plugins inspect <id>` は、検出されたバンドル機能に加えて、バンドルベース Plugin のサポート対象または非サポートの MCP および LSP サーバーエントリも報告します。
Marketplace sources には、`~/.claude/plugins/known_marketplaces.json` の Claude known-marketplace 名、
ローカル marketplace root または `marketplace.json` パス、`owner/repo` のような GitHub shorthand、
GitHub repo URL、または git URL を指定できます。リモート marketplace の場合、Plugin エントリは
cloned marketplace repo 内に留まり、relative path sources のみを使用する必要があります。
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) を参照してください。
## Plugin API 概要
Native Plugin は `register(api)` を公開するエントリオブジェクトを export します。古い
Plugin は legacy alias として `activate(api)` をまだ使用する場合がありますが、新しい Plugin は
`register` を使用する必要があります。
ネイティブ Plugin は `register(api)` を公開するエントリオブジェクトをエクスポートします。古い Plugin はレガシーエイリアスとして `activate(api)` をまだ使用している場合がありますが、新しい Plugin は `register` を使用する必要があります。
```typescript
export default definePluginEntry({
@ -439,67 +426,52 @@ export default definePluginEntry({
});
```
OpenClaw はエントリオブジェクトを読み込み、Plugin
activation 中に `register(api)` を呼び出します。loader は古い Plugin 向けに
`activate(api)` へまだフォールバックしますが、同梱 Plugin と新しい外部 Plugin は
`register` を public contract として扱う必要があります。
OpenClaw は Plugin の有効化中にエントリオブジェクトを読み込み、`register(api)` を呼び出します。ローダーは古い Plugin 向けに引き続き `activate(api)` へフォールバックしますが、同梱 Plugin と新しい外部 Plugin は `register` を公開コントラクトとして扱う必要があります。
`api.registrationMode` は、なぜそのエントリが読み込まれているのかを Plugin に伝えます:
`api.registrationMode` は、Plugin のエントリが読み込まれる理由を 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"` でガードする必要があります。検出用の読み込みは有効化用の読み込みとは別にキャッシュされ、実行中の Gateway レジストリを置き換えません。検出は有効化を伴いませんが、インポート不要ではありません。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 }` は no-op であり、以前のブロックを解除しません。
- `before_tool_call`: `{ block: false }` は何もせず、以前のブロックをクリアしません。
- `before_install`: `{ block: true }` は終端です。優先度の低いハンドラーはスキップされます。
- `before_install`: `{ block: false }` は no-op であり、以前のブロックを解除しません。
- `before_install`: `{ block: false }` は何もせず、以前のブロックをクリアしません。
- `message_sending`: `{ cancel: true }` は終端です。優先度の低いハンドラーはスキップされます。
- `message_sending`: `{ cancel: false }` は no-op であり、以前のキャンセルを解除しません。
- `message_sending`: `{ cancel: false }` は何もせず、以前のキャンセルをクリアしません。
ネイティブ Codex アプリサーバーの実行では、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 ハーネス v1 サポートコントラクト](/ja-JP/plugins/codex-harness#v1-support-contract)にあります。
型付きフックの完全な動作については、[SDK 概要](/ja-JP/plugins/sdk-overview#hook-decision-semantics)を参照してください。
@ -510,4 +482,4 @@ OpenClaw は、信頼済みの Plugin エントリまたはチャネル Plugin
- [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/community) — サードパーティ一覧