diff --git a/docs/ja-JP/automation/tasks.md b/docs/ja-JP/automation/tasks.md index fa3e20701..d749bd426 100644 --- a/docs/ja-JP/automation/tasks.md +++ b/docs/ja-JP/automation/tasks.md @@ -2,43 +2,43 @@ read_when: - 進行中または最近完了したバックグラウンド作業の確認 - 分離されたエージェント実行の配信失敗のデバッグ - - バックグラウンド実行がセッション、Cron、および Heartbeat とどのように関連するかを理解する -summary: ACP 実行、サブエージェント、分離された Cron ジョブ、および CLI 操作のバックグラウンドタスク追跡 + - バックグラウンド実行がセッション、Cron、Heartbeatとどのように関係するかを理解する +summary: ACP実行、サブエージェント、分離されたCronジョブ、CLI操作のためのバックグラウンドタスク追跡 title: バックグラウンドタスク x-i18n: - generated_at: "2026-04-21T04:43:45Z" + generated_at: "2026-04-21T19:20:40Z" model: gpt-5.4 provider: openai - source_hash: ba5511b1c421bdf505fc7d34f09e453ac44e85213fcb0f082078fa957aa91fe7 + source_hash: a4cd666b3eaffde8df0b5e1533eb337e44a0824824af6f8a240f18a89f71b402 source_path: automation/tasks.md workflow: 15 --- # バックグラウンドタスク -> **スケジューリングをお探しですか？** 適切な仕組みを選ぶには [Automation & Tasks](/ja-JP/automation) を参照してください。このページで扱うのはバックグラウンド作業の**追跡**であり、スケジューリングではありません。 +> **スケジュール設定を探していますか？** 適切な仕組みを選ぶには、[Automation & Tasks](/ja-JP/automation)を参照してください。このページで扱うのはバックグラウンド作業の**追跡**であり、スケジュール設定ではありません。 -バックグラウンドタスクは、**メインの会話セッションの外側**で実行される作業を追跡します: -ACP 実行、サブエージェントの起動、分離された Cron ジョブの実行、および CLI から開始された操作です。 +バックグラウンドタスクは、**メインの会話セッションの外側で**実行される作業を追跡します。 +ACP実行、サブエージェントの起動、分離されたCronジョブ実行、CLIから開始された操作が対象です。 -タスクはセッション、Cron ジョブ、または Heartbeat を置き換えるものではありません — それらは、どの分離された作業が、いつ発生し、成功したかどうかを記録する**アクティビティ台帳**です。 +タスクはセッション、Cronジョブ、Heartbeatを置き換えるものではありません — これらは切り離された作業で何が起こったか、いつ起こったか、成功したかどうかを記録する**アクティビティ台帳**です。 -すべてのエージェント実行がタスクを作成するわけではありません。Heartbeat ターンと通常の対話型チャットは作成しません。すべての Cron 実行、ACP 起動、サブエージェント起動、および CLI エージェントコマンドは作成します。 +すべてのエージェント実行でタスクが作成されるわけではありません。Heartbeatターンと通常の対話チャットでは作成されません。すべてのCron実行、ACP起動、サブエージェント起動、CLIエージェントコマンドでは作成されます。 ## 要点 -- タスクはスケジューラではなく**記録**です — Cron と Heartbeat が作業をいつ実行するかを決め、タスクは何が起きたかを追跡します。 -- ACP、サブエージェント、すべての Cron ジョブ、および CLI 操作はタスクを作成します。Heartbeat ターンは作成しません。 -- 各タスクは `queued → running → terminal`（succeeded、failed、timed_out、cancelled、または lost）を移動します。 -- Cron タスクは、Cron ランタイムがまだジョブを所有している間は存続します。チャットに裏打ちされた CLI タスクは、所有する実行コンテキストがまだアクティブな間だけ存続します。 -- 完了はプッシュ駆動です。分離された作業は完了時に直接通知するか、要求元セッション/Heartbeat を起こせるため、通常はステータスをポーリングするループは適切ではありません。 -- 分離された Cron 実行とサブエージェント完了では、最終的なクリーンアップ記録処理の前に、その子セッションに対して追跡されたブラウザータブ/プロセスをベストエフォートでクリーンアップします。 -- 分離された Cron 配信では、子孫サブエージェントの作業がまだ排出中である間は古い中間親応答を抑制し、配信前に最終的な子孫出力が到着した場合はそちらを優先します。 -- 完了通知はチャネルに直接配信されるか、次の Heartbeat のためにキューに入れられます。 -- `openclaw tasks list` はすべてのタスクを表示し、`openclaw tasks audit` は問題を明らかにします。 -- 終端レコードは 7 日間保持され、その後自動的に削除されます。 +- タスクはスケジューラではなく**記録**です — CronとHeartbeatが作業の実行_タイミング_を決め、タスクが_何が起きたか_を追跡します。 +- ACP、サブエージェント、すべてのCronジョブ、CLI操作はタスクを作成します。Heartbeatターンは作成しません。 +- 各タスクは `queued → running → terminal`（succeeded、failed、timed_out、cancelled、またはlost）を移動します。 +- Cronタスクは、Cronランタイムがまだそのジョブを所有している間は存続します。チャットに紐づくCLIタスクは、その所有元の実行コンテキストがまだアクティブな間だけ存続します。 +- 完了はプッシュ駆動です。切り離された作業は、完了時に直接通知するか、リクエスターのセッション/Heartbeatを起こせるため、通常はステータスポーリングループは適切ではありません。 +- 分離されたCron実行とサブエージェントの完了では、最終的なクリーンアップ記録処理の前に、子セッションに対して追跡中のブラウザタブ/プロセスをベストエフォートでクリーンアップします。 +- 分離されたCron配信では、子孫サブエージェント作業の排出中は古い中間親返信を抑制し、配信前に到着すれば最終的な子孫出力を優先します。 +- 完了通知は、チャンネルに直接配信されるか、次のHeartbeat用にキューされます。 +- `openclaw tasks list` はすべてのタスクを表示し、`openclaw tasks audit` は問題を表面化します。 +- 終端レコードは7日間保持され、その後自動的に削除されます。 ## クイックスタート @@ -46,11 +46,11 @@ ACP 実行、サブエージェントの起動、分離された Cron ジョブ # すべてのタスクを一覧表示（新しい順） openclaw tasks list -# ランタイムまたはステータスで絞り込み +# ランタイムまたはステータスで絞り込む openclaw tasks list --runtime acp openclaw tasks list --status running -# 特定のタスクの詳細を表示（ID、run ID、または session key で指定） +# 特定のタスクの詳細を表示（ID、run ID、またはsession keyで指定） openclaw tasks show # 実行中のタスクをキャンセル（子セッションを終了） @@ -59,14 +59,14 @@ openclaw tasks cancel # タスクの通知ポリシーを変更 openclaw tasks notify state_changes -# 健全性監査を実行 +# ヘルス監査を実行 openclaw tasks audit # メンテナンスをプレビューまたは適用 openclaw tasks maintenance openclaw tasks maintenance --apply -# TaskFlow の状態を確認 +# TaskFlowの状態を確認 openclaw tasks flow list openclaw tasks flow show openclaw tasks flow cancel @@ -74,27 +74,27 @@ openclaw tasks flow cancel ## タスクを作成するもの -| ソース | ランタイム種別 | タスクレコードが作成されるタイミング | デフォルトの通知ポリシー | -| ---------------------- | -------------- | ----------------------------------------------------- | ------------------------ | -| ACP バックグラウンド実行 | `acp` | 子 ACP セッションを起動したとき | `done_only` | -| サブエージェントオーケストレーション | `subagent` | `sessions_spawn` によってサブエージェントを起動したとき | `done_only` | -| Cron ジョブ（すべての種類） | `cron` | すべての Cron 実行（メインセッションと分離実行） | `silent` | -| CLI 操作 | `cli` | ゲートウェイ経由で実行される `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` | セッションに紐づく `video_generate` 実行 | `silent` | -メインセッションの Cron タスクは、デフォルトで `silent` 通知ポリシーを使用します — 追跡用のレコードは作成しますが、通知は生成しません。分離された Cron タスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より見えやすくなります。 +メインセッションのCronタスクはデフォルトで `silent` 通知ポリシーを使います — 追跡用のレコードは作成されますが、通知は生成されません。分離されたCronタスクもデフォルトでは `silent` ですが、独自のセッションで実行されるため、より可視性があります。 -セッションに裏打ちされた `video_generate` 実行も `silent` 通知ポリシーを使用します。これらもタスクレコードを作成しますが、完了は内部ウェイクとして元のエージェントセッションに返されるため、エージェント自身がフォローアップメッセージを書き、完成した動画を添付できます。`tools.media.asyncCompletion.directSend` を有効にすると、非同期の `music_generate` および `video_generate` 完了は、要求元セッションを起こす経路にフォールバックする前に、まずチャネルへの直接配信を試みます。 +セッションに紐づく `video_generate` 実行も `silent` 通知ポリシーを使います。これらもタスクレコードは作成されますが、完了は内部ウェイクとして元のエージェントセッションに返されるため、エージェント自身がフォローアップメッセージを書き、完成した動画を添付できます。`tools.media.asyncCompletion.directSend` を有効にすると、非同期の `music_generate` および `video_generate` 完了は、リクエスターセッションを起こす経路にフォールバックする前に、まずチャンネルへの直接配信を試みます。 -セッションに裏打ちされた `video_generate` タスクがまだアクティブな間、このツールはガードレールとしても機能します。同じセッション内で繰り返し `video_generate` を呼び出すと、2 つ目の同時生成を開始する代わりに、アクティブなタスクステータスを返します。エージェント側から明示的な進捗/ステータス確認を行いたい場合は、`action: "status"` を使用してください。 +セッションに紐づく `video_generate` タスクがまだアクティブな間、このツールはガードレールとしても機能します。同じセッション内で `video_generate` を繰り返し呼び出すと、2つ目の並行生成を開始する代わりに、アクティブなタスク状態を返します。エージェント側から明示的に進捗/状態を確認したい場合は `action: "status"` を使ってください。 **タスクを作成しないもの:** -- Heartbeat ターン — メインセッション。詳細は [Heartbeat](/ja-JP/gateway/heartbeat) を参照 -- 通常の対話型チャットターン +- Heartbeatターン — メインセッション。詳細は[Heartbeat](/ja-JP/gateway/heartbeat)を参照 +- 通常の対話チャットターン - 直接の `/command` 応答 -## タスクライフサイクル +## タスクのライフサイクル ```mermaid stateDiagram-v2 @@ -108,56 +108,56 @@ 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分の猶予期間後に、ランタイムが権威ある裏付け状態を失った | -遷移は自動で行われます — 関連するエージェント実行が終了すると、タスクステータスはそれに合わせて更新されます。 +遷移は自動的に行われます — 関連するエージェント実行が終了すると、タスクのステータスはそれに合わせて更新されます。 -`lost` はランタイムを認識します: +`lost` はランタイム認識型です。 -- ACP タスク: 裏付けとなる ACP 子セッションメタデータが消えた。 +- ACPタスク: 裏付けとなるACP子セッションのメタデータが消えた。 - サブエージェントタスク: 裏付けとなる子セッションが対象エージェントストアから消えた。 -- Cron タスク: Cron ランタイムがそのジョブをアクティブとして追跡しなくなった。 -- CLI タスク: 分離された子セッションタスクは子セッションを使用します。チャットに裏打ちされた CLI タスクは代わりにライブ実行コンテキストを使用するため、チャネル/グループ/ダイレクトセッション行が残っていても存続しません。 +- Cronタスク: Cronランタイムがそのジョブをアクティブとして追跡しなくなった。 +- CLIタスク: 分離された子セッションタスクは子セッションを使います。チャットに紐づくCLIタスクは代わりに生きた実行コンテキストを使うため、チャンネル/グループ/ダイレクトのセッション行が残っていても存続扱いにはなりません。 ## 配信と通知 -タスクが終端状態に達すると、OpenClaw が通知します。配信経路は 2 つあります。 +タスクが終端状態に到達すると、OpenClawが通知します。配信経路は2つあります。 -**直接配信** — タスクにチャネルターゲット（`requesterOrigin`）がある場合、完了メッセージはそのチャネル（Telegram、Discord、Slack など）に直接送られます。サブエージェント完了では、利用可能な場合に OpenClaw は結び付けられたスレッド/トピックのルーティングも保持し、直接配信を諦める前に、要求元セッションの保存済みルート（`lastChannel` / `lastTo` / `lastAccountId`）から欠けている `to` / account を補完できます。 +**直接配信** — タスクにチャンネルの宛先（`requesterOrigin`）がある場合、完了メッセージはそのチャンネル（Telegram、Discord、Slackなど）に直接送られます。サブエージェント完了では、OpenClawは利用可能な場合に紐づくスレッド/トピックのルーティングも保持し、直接配信を諦める前に、リクエスターセッションに保存されたルート（`lastChannel` / `lastTo` / `lastAccountId`）から不足している `to` / アカウントを補える場合があります。 -**セッションキュー配信** — 直接配信に失敗した場合、または origin が設定されていない場合、更新は要求元セッション内のシステムイベントとしてキューに入れられ、次の Heartbeat で表面化します。 +**セッションキュー配信** — 直接配信に失敗した場合、またはoriginが設定されていない場合、更新はリクエスターのセッション内のシステムイベントとしてキューされ、次のHeartbeatで表示されます。 -タスク完了は即時の Heartbeat ウェイクを引き起こすため、結果をすぐに確認できます — 次に予定された Heartbeat ティックを待つ必要はありません。 +タスク完了は即時のHeartbeatウェイクを引き起こすため、結果をすぐに確認できます — 次回スケジュールされたHeartbeatティックまで待つ必要はありません。 -つまり、通常のワークフローはプッシュベースです。分離された作業は一度開始したら、完了時にランタイムが起こすか通知するのに任せます。タスク状態のポーリングは、デバッグ、介入、または明示的な監査が必要な場合にだけ行ってください。 +つまり通常のワークフローはプッシュベースです。切り離された作業を一度開始したら、完了時にランタイムが起こすか通知するのに任せてください。タスク状態のポーリングは、デバッグ、介入、または明示的な監査が必要なときにだけ行ってください。 ### 通知ポリシー -各タスクについて、どの程度通知を受け取るかを制御します。 +各タスクについてどれだけ通知を受けるかを制御します。 -| ポリシー | 配信される内容 | +| ポリシー | 配信されるもの | | --------------------- | ----------------------------------------------------------------------- | -| `done_only` (デフォルト) | 終端状態のみ（succeeded、failed など） — **これがデフォルトです** | -| `state_changes` | すべての状態遷移と進捗更新 | -| `silent` | 何も通知しない | +| `done_only` (default) | 終端状態のみ（succeeded、failedなど） — **これがデフォルトです** | +| `state_changes` | すべての状態遷移と進捗更新 | +| `silent` | 何も配信しない | -タスク実行中にポリシーを変更します: +タスクの実行中にポリシーを変更できます。 ```bash openclaw tasks notify state_changes ``` -## CLI リファレンス +## CLIリファレンス ### `tasks list` @@ -173,7 +173,7 @@ openclaw tasks list [--runtime ] [--status ] [--j openclaw tasks show ``` -lookup トークンには task ID、run ID、または session key を指定できます。タイミング、配信状態、エラー、および終端要約を含む完全なレコードを表示します。 +lookupトークンには、task ID、run ID、またはsession keyを指定できます。タイミング、配信状態、エラー、終端サマリーを含む完全なレコードを表示します。 ### `tasks cancel` @@ -181,7 +181,7 @@ lookup トークンには task ID、run ID、または session key を指定で openclaw tasks cancel ``` -ACP およびサブエージェントタスクでは、これにより子セッションが終了されます。CLI 追跡タスクでは、キャンセルはタスクレジストリに記録されます（別個の子ランタイムハンドルはありません）。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送信されます。 +ACPタスクとサブエージェントタスクでは、これにより子セッションを終了します。CLI追跡タスクでは、キャンセルはタスクレジストリに記録されます（別個の子ランタイムハンドルはありません）。ステータスは `cancelled` に遷移し、該当する場合は配信通知が送られます。 ### `tasks notify` @@ -195,16 +195,16 @@ openclaw tasks notify openclaw tasks audit [--json] ``` -運用上の問題を明らかにします。問題が検出された場合、所見は `openclaw status` にも表示されます。 +運用上の問題を表面化します。問題が検出された場合、検出結果は `openclaw status` にも表示されます。 -| 所見 | 重大度 | トリガー | -| ------------------------- | ------ | ------------------------------------------------------ | -| `stale_queued` | warn | 10 分を超えて queued のまま | -| `stale_running` | error | 30 分を超えて running のまま | -| `lost` | error | ランタイムに裏打ちされたタスク所有権が消失 | -| `delivery_failed` | warn | 配信に失敗し、通知ポリシーが `silent` ではない | -| `missing_cleanup` | warn | 終端タスクだがクリーンアップタイムスタンプがない | -| `inconsistent_timestamps` | warn | タイムライン違反（たとえば開始前に終了している） | +| 検出項目 | 深刻度 | トリガー | +| ------------------------- | -------- | ----------------------------------------------------- | +| `stale_queued` | warn | 10分以上キュー状態 | +| `stale_running` | error | 30分以上実行中 | +| `lost` | error | ランタイムに裏付けられたタスク所有権が消失 | +| `delivery_failed` | warn | 配信に失敗し、通知ポリシーが `silent` ではない | +| `missing_cleanup` | warn | 終端タスクにクリーンアップタイムスタンプがない | +| `inconsistent_timestamps` | warn | タイムライン違反（たとえば開始前に終了している） | ### `tasks maintenance` @@ -213,21 +213,21 @@ openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` -これを使用して、タスクと Task Flow 状態の突合、クリーンアップ刻印、および削除をプレビューまたは適用します。 +これを使うと、タスクおよびTask Flow状態の照合、クリーンアップ記録、削除をプレビューまたは適用できます。 -突合はランタイムを認識します: +照合はランタイム認識型です。 - ACP/サブエージェントタスクは、裏付けとなる子セッションを確認します。 -- Cron タスクは、Cron ランタイムがまだそのジョブを所有しているかを確認します。 -- チャットに裏打ちされた CLI タスクは、チャットセッション行だけでなく、所有するライブ実行コンテキストを確認します。 +- Cronタスクは、Cronランタイムがまだそのジョブを所有しているかを確認します。 +- チャットに紐づくCLIタスクは、チャットセッション行だけでなく、所有元の生きた実行コンテキストを確認します。 -完了クリーンアップもランタイムを認識します: +完了クリーンアップもランタイム認識型です。 -- サブエージェント完了では、通知クリーンアップが続行する前に、子セッションの追跡されたブラウザータブ/プロセスをベストエフォートで閉じます。 -- 分離された Cron 完了では、実行が完全に終了する前に、Cron セッションの追跡されたブラウザータブ/プロセスをベストエフォートで閉じます。 -- 分離された Cron 配信では、必要に応じて子孫サブエージェントのフォローアップを待ち、古い親確認テキストを通知する代わりにそれを抑制します。 -- サブエージェント完了配信では、最新の可視 assistant テキストを優先し、それが空の場合はサニタイズ済みの最新 tool/toolResult テキストにフォールバックします。また、タイムアウトのみのツール呼び出し実行は短い部分進捗要約にまとめられる場合があります。 -- クリーンアップ失敗によって、実際のタスク結果が隠されることはありません。 +- サブエージェント完了では、通知クリーンアップが続行する前に、子セッションの追跡対象ブラウザタブ/プロセスをベストエフォートで閉じます。 +- 分離されたCron完了では、実行が完全に終了する前に、Cronセッションの追跡対象ブラウザタブ/プロセスをベストエフォートで閉じます。 +- 分離されたCron配信では、必要に応じて子孫サブエージェントのフォローアップを待ち、古い親確認テキストを通知せずに抑制します。 +- サブエージェント完了配信では、最新の可視なassistantテキストを優先します。それが空なら、サニタイズされた最新のtool/toolResultテキストにフォールバックし、タイムアウトのみのtool-call実行は短い部分進捗サマリーに折りたためることがあります。終端failed実行では、キャプチャ済みの返信テキストを再送せずに失敗ステータスを通知します。 +- クリーンアップの失敗によって、実際のタスク結果が隠されることはありません。 ### `tasks flow list|show|cancel` @@ -237,86 +237,86 @@ openclaw tasks flow show [--json] openclaw tasks flow cancel ``` -個々のバックグラウンドタスクレコードではなく、オーケストレーションする Task Flow のほうが関心対象である場合にこれらを使用してください。 +個々のバックグラウンドタスクレコードではなく、オーケストレーションしているTask Flow自体を重視したい場合は、これらを使ってください。 ## チャットタスクボード（`/tasks`） -任意のチャットセッションで `/tasks` を使用すると、そのセッションにリンクされたバックグラウンドタスクを確認できます。ボードには、アクティブおよび最近完了したタスクについて、ランタイム、ステータス、タイミング、進捗またはエラーの詳細が表示されます。 +任意のチャットセッションで `/tasks` を使うと、そのセッションに紐づくバックグラウンドタスクを確認できます。このボードには、アクティブなタスクと最近完了したタスクが、ランタイム、ステータス、タイミング、進捗またはエラー詳細とともに表示されます。 -現在のセッションに表示可能なリンク済みタスクがない場合、`/tasks` はエージェントローカルのタスク数にフォールバックするため、他セッションの詳細を漏らさずに概要を把握できます。 +現在のセッションに表示可能な紐づけ済みタスクがない場合、`/tasks` はエージェントローカルのタスク数にフォールバックするため、他セッションの詳細を漏らさずに概要を確認できます。 -完全なオペレーター台帳を確認するには、CLI を使用します: `openclaw tasks list`。 +完全なオペレーター台帳については、CLIの `openclaw tasks list` を使用してください。 -## Status 統合（タスク負荷） +## ステータス統合（タスク負荷） -`openclaw status` には、ひと目でわかるタスク要約が含まれます。 +`openclaw status` には、ひと目で分かるタスク概要が含まれます。 ``` Tasks: 3 queued · 2 running · 1 issues ``` -この要約では、次を報告します。 +この概要では、以下が報告されます。 - **active** — `queued` + `running` の件数 - **failures** — `failed` + `timed_out` + `lost` の件数 - **byRuntime** — `acp`、`subagent`、`cron`、`cli` ごとの内訳 -`/status` と `session_status` ツールの両方は、クリーンアップを考慮したタスクスナップショットを使用します。アクティブなタスクが優先され、古い完了済み行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは今重要なことに集中できます。 +`/status` と `session_status` ツールの両方で、クリーンアップを考慮したタスクスナップショットが使用されます。アクティブなタスクが優先され、古い完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは今重要なものに集中できます。 -## 保存とメンテナンス +## ストレージとメンテナンス ### タスクの保存場所 -タスクレコードは、次の場所にある SQLite に永続化されます。 +タスクレコードは、次のSQLiteに永続化されます。 ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -レジストリは Gateway 起動時にメモリへ読み込まれ、再起動をまたいだ永続性のために書き込みを SQLite へ同期します。 +レジストリはGateway起動時にメモリへ読み込まれ、再起動後も永続性を保つために書き込みはSQLiteへ同期されます。 ### 自動メンテナンス -スイーパーは **60 秒**ごとに実行され、次の 3 つを処理します。 +スイーパーは**60秒**ごとに実行され、次の3つを処理します。 -1. **突合** — アクティブなタスクに、まだ権威あるランタイムの裏付けがあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使用し、Cron タスクはアクティブジョブの所有状態を使用し、チャットに裏打ちされた CLI タスクは所有する実行コンテキストを使用します。その裏付け状態が 5 分を超えて失われている場合、タスクは `lost` としてマークされます。 -2. **クリーンアップ刻印** — 終端タスクに `cleanupAfter` タイムスタンプ（endedAt + 7 日）を設定します。 +1. **照合** — アクティブなタスクに、まだ権威あるランタイムの裏付けがあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使い、Cronタスクはアクティブジョブの所有権を使い、チャットに紐づくCLIタスクは所有元の実行コンテキストを使います。その裏付け状態が5分を超えて失われている場合、タスクは `lost` としてマークされます。 +2. **クリーンアップ記録** — 終端タスクに `cleanupAfter` タイムスタンプを設定します（endedAt + 7日）。 3. **削除** — `cleanupAfter` 日付を過ぎたレコードを削除します。 -**保持期間**: 終端タスクレコードは **7 日間**保持され、その後自動的に削除されます。設定は不要です。 +**保持期間**: 終端タスクレコードは**7日間**保持され、その後自動的に削除されます。設定は不要です。 -## タスクと他のシステムの関係 +## タスクと他システムとの関係 -### タスクと Task Flow +### タスクとTask Flow -[Task Flow](/ja-JP/automation/taskflow) は、バックグラウンドタスクの上位にあるフローオーケストレーション層です。1 つのフローは、そのライフタイムの間に managed または mirrored sync モードを使用して複数のタスクを調整できます。個々のタスクレコードを調べるには `openclaw tasks` を、オーケストレーションするフローを調べるには `openclaw tasks flow` を使用します。 +[Task Flow](/ja-JP/automation/taskflow) は、バックグラウンドタスクの上位にあるフローオーケストレーション層です。1つのフローが、その存続期間中に管理モードまたはミラー同期モードを使って複数のタスクを調整することがあります。個々のタスクレコードを調べるには `openclaw tasks` を使い、オーケストレーションしているフローを調べるには `openclaw tasks flow` を使ってください。 詳細は [Task Flow](/ja-JP/automation/taskflow) を参照してください。 -### タスクと Cron +### タスクと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` 通知ポリシーです。 -[Scheduled Tasks](/ja-JP/automation/cron-jobs) を参照してください。 +[Cron Jobs](/ja-JP/automation/cron-jobs) を参照してください。 -### タスクと Heartbeat +### タスクとHeartbeat -Heartbeat 実行はメインセッションターンです — タスクレコードは作成しません。タスクが完了すると、結果をすぐに確認できるよう Heartbeat ウェイクをトリガーできます。 +Heartbeat実行はメインセッションのターンです — タスクレコードは作成されません。タスクが完了すると、結果をすぐ確認できるようにHeartbeatウェイクをトリガーできます。 [Heartbeat](/ja-JP/gateway/heartbeat) を参照してください。 ### タスクとセッション -タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（それを開始した人）を参照する場合があります。セッションは会話コンテキストであり、タスクはその上でのアクティビティ追跡です。 +タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（それを開始した主体）を参照することがあります。セッションは会話コンテキストであり、タスクはその上にあるアクティビティ追跡です。 ### タスクとエージェント実行 -タスクの `runId` は、作業を実行しているエージェント実行にリンクされます。エージェントのライフサイクルイベント（開始、終了、エラー）は自動的にタスクステータスを更新するため、ライフサイクルを手動で管理する必要はありません。 +タスクの `runId` は、作業を行うエージェント実行にリンクします。エージェントのライフサイクルイベント（開始、終了、エラー）はタスクステータスを自動的に更新するため、ライフサイクルを手動で管理する必要はありません。 ## 関連 - [Automation & Tasks](/ja-JP/automation) — すべての自動化メカニズムの概要 - [Task Flow](/ja-JP/automation/taskflow) — タスクの上位にあるフローオーケストレーション -- [Scheduled Tasks](/ja-JP/automation/cron-jobs) — バックグラウンド作業のスケジューリング +- [Scheduled Tasks](/ja-JP/automation/cron-jobs) — バックグラウンド作業のスケジュール設定 - [Heartbeat](/ja-JP/gateway/heartbeat) — 定期的なメインセッションターン -- [CLI: Tasks](/cli/index#tasks) — CLI コマンドリファレンス +- [CLI: Tasks](/cli/index#tasks) — CLIコマンドリファレンス diff --git a/docs/ja-JP/channels/synology-chat.md b/docs/ja-JP/channels/synology-chat.md index 63a2c58e4..553fe4deb 100644 --- a/docs/ja-JP/channels/synology-chat.md +++ b/docs/ja-JP/channels/synology-chat.md @@ -1,53 +1,52 @@ --- read_when: - - OpenClawでSynology Chatをセットアップしているとき - - Synology Chat webhookルーティングをデバッグしているとき -summary: Synology Chat webhookのセットアップとOpenClaw設定 + - OpenClawでSynology Chatをセットアップする + - Synology ChatのWebhookルーティングをデバッグする +summary: Synology ChatのWebhookセットアップとOpenClawの設定 title: Synology Chat x-i18n: - generated_at: "2026-04-05T12:36:42Z" + generated_at: "2026-04-21T19:20:39Z" model: gpt-5.4 provider: openai - source_hash: ddb25fc6b53f896f15f43b4936d69ea071a29a91838a5b662819377271e89d81 + source_hash: 7288e2aa873ee1a1f57861d839cfb44ff324e3d40a7f36da07c6ba43cbe1e6e6 source_path: channels/synology-chat.md workflow: 15 --- # Synology Chat -ステータス: Synology Chat webhookを使用するバンドル済みプラグインのダイレクトメッセージチャンネルです。 -このプラグインは、Synology Chatの送信webhookから受信メッセージを受け取り、 -Synology Chatの受信webhookを通じて返信を送信します。 +ステータス: Synology ChatのWebhookを使う、ダイレクトメッセージ用のバンドルPluginチャンネルです。 +このPluginは、Synology Chatの送信Webhookからの受信メッセージを受け付け、Synology Chatの受信Webhookを通じて返信を送信します。 -## バンドル済みプラグイン +## バンドルPlugin -Synology Chatは現在のOpenClawリリースにバンドル済みプラグインとして含まれているため、通常の -パッケージ済みビルドでは別途インストールは不要です。 +Synology Chatは現在のOpenClawリリースではバンドルPluginとして提供されるため、通常の +パッケージ版ビルドでは別途インストールは不要です。 -古いビルドまたはSynology Chatを含まないカスタムインストールを使用している場合は、 +古いビルドを使っている場合や、Synology Chatを含まないカスタムインストールの場合は、 手動でインストールしてください。 -ローカルチェックアウトからインストールするには: +ローカルのチェックアウトからインストール: ```bash openclaw plugins install ./path/to/local/synology-chat-plugin ``` -詳細: [Plugins](/tools/plugin) +詳細: [Plugins](/ja-JP/tools/plugin) ## クイックセットアップ -1. Synology Chatプラグインが利用可能であることを確認します。 +1. Synology Chat Pluginが利用可能であることを確認します。 - 現在のパッケージ版OpenClawリリースには、すでにバンドルされています。 - - 古い/カスタムインストールでは、上記コマンドでソースチェックアウトから手動追加できます。 - - `openclaw onboard`では、`openclaw channels add`と同じチャンネルセットアップ一覧にSynology Chatが表示されるようになりました。 + - 古いインストールやカスタムインストールでは、上記のコマンドでソースのチェックアウトから手動追加できます。 + - `openclaw onboard` では、`openclaw channels add` と同じチャンネル設定一覧にSynology Chatが表示されます。 - 非対話型セットアップ: `openclaw channels add --channel synology-chat --token --url ` -2. Synology Chatの統合設定で以下を行います。 - - 受信webhookを作成し、そのURLをコピーします。 - - 送信webhookを作成し、そのシークレットトークンを設定します。 -3. 送信webhookのURLをOpenClaw Gatewayに向けます。 - - デフォルトでは`https://gateway-host/webhook/synology` - - またはカスタムの`channels.synology-chat.webhookPath` +2. Synology Chatの連携設定で: + - 受信Webhookを作成し、そのURLをコピーします。 + - シークレットトークン付きの送信Webhookを作成します。 +3. 送信WebhookのURLをOpenClaw Gatewayに向けます: + - デフォルトでは `https://gateway-host/webhook/synology` + - またはカスタムの `channels.synology-chat.webhookPath` 4. OpenClawでセットアップを完了します。 - ガイド付き: `openclaw onboard` - 直接指定: `openclaw channels add --channel synology-chat --token --url ` @@ -55,14 +54,14 @@ openclaw plugins install ./path/to/local/synology-chat-plugin Webhook認証の詳細: -- OpenClawは、まず`body.token`、次に - `?token=...`、最後にヘッダーから送信webhookトークンを受け付けます。 +- OpenClawは、まず `body.token`、次に + `?token=...`、その後にヘッダーから送信Webhookトークンを受け付けます。 - 受け付けるヘッダー形式: - `x-synology-token` - `x-webhook-token` - `x-openclaw-token` - `Authorization: Bearer ` -- 空または欠落したトークンはfail-closedになります。 +- トークンが空または欠落している場合はフェイルクローズします。 最小構成: @@ -85,7 +84,7 @@ Webhook認証の詳細: ## 環境変数 -デフォルトアカウントでは、以下の環境変数を使用できます。 +デフォルトアカウントでは、env varを使用できます: - `SYNOLOGY_CHAT_TOKEN` - `SYNOLOGY_CHAT_INCOMING_URL` @@ -94,17 +93,17 @@ Webhook認証の詳細: - `SYNOLOGY_RATE_LIMIT` - `OPENCLAW_BOT_NAME` -設定値は環境変数より優先されます。 +設定値はenv varより優先されます。 ## DMポリシーとアクセス制御 -- `dmPolicy: "allowlist"`が推奨されるデフォルトです。 -- `allowedUserIds`は、SynologyユーザーIDのリスト（またはカンマ区切り文字列）を受け付けます。 -- `allowlist`モードでは、`allowedUserIds`リストが空だと設定ミスとして扱われ、webhookルートは起動しません（全員許可にするには`dmPolicy: "open"`を使用してください）。 -- `dmPolicy: "open"`は任意の送信者を許可します。 -- `dmPolicy: "disabled"`はDMをブロックします。 -- 返信先バインディングは、デフォルトで安定した数値の`user_id`に基づきます。`channels.synology-chat.dangerouslyAllowNameMatching: true`は、返信配信で可変なusername/nickname参照を再有効化する非常用の互換モードです。 -- ペアリング承認は次で行えます。 +- `dmPolicy: "allowlist"` が推奨されるデフォルトです。 +- `allowedUserIds` は、SynologyユーザーIDのリスト（またはカンマ区切り文字列）を受け付けます。 +- `allowlist` モードでは、`allowedUserIds` リストが空だと設定ミスとして扱われ、Webhookルートは起動しません（全許可にするには `dmPolicy: "open"` を使用してください）。 +- `dmPolicy: "open"` は任意の送信者を許可します。 +- `dmPolicy: "disabled"` はDMをブロックします。 +- 返信先の紐付けは、デフォルトでは安定した数値の `user_id` に固定されます。`channels.synology-chat.dangerouslyAllowNameMatching: true` は、変更可能なユーザー名/ニックネーム検索による返信配送を再有効化する非常用の互換モードです。 +- ペアリング承認は以下で動作します: - `openclaw pairing list synology-chat` - `openclaw pairing approve synology-chat ` @@ -119,17 +118,20 @@ openclaw message send --channel synology-chat --target 123456 --text "Hello from openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again" ``` -メディア送信は、URLベースのファイル配信でサポートされています。 +メディア送信はURLベースのファイル配信でサポートされます。 +送信ファイルURLは `http` または `https` を使う必要があり、プライベートまたはその他のブロック対象ネットワークへの宛先は、OpenClawがそのURLをNASのWebhookへ転送する前に拒否されます。 -## 複数アカウント +## マルチアカウント -複数のSynology Chatアカウントは`channels.synology-chat.accounts`配下でサポートされています。 -各アカウントは、token、incoming URL、webhook path、DMポリシー、制限を上書きできます。 -ダイレクトメッセージのセッションはアカウントごと・ユーザーごとに分離されるため、異なる2つのSynologyアカウントで同じ数値の`user_id`を使ってもトランスクリプト状態は共有されません。 -有効な各アカウントには、異なる`webhookPath`を設定してください。OpenClawは現在、完全一致する重複パスを拒否し、複数アカウント構成で共有されたwebhook pathだけを継承する名前付きアカウントの起動を拒否します。 -意図的に名前付きアカウントでレガシー継承が必要な場合は、 -そのアカウントまたは`channels.synology-chat`に`dangerouslyAllowInheritedWebhookPath: true`を設定してください。 -ただし、完全一致する重複パスは引き続きfail-closedで拒否されます。明示的なアカウントごとのパスを推奨します。 +複数のSynology Chatアカウントは `channels.synology-chat.accounts` の下でサポートされます。 +各アカウントは、トークン、受信URL、Webhookパス、DMポリシー、制限を上書きできます。 +ダイレクトメッセージのセッションはアカウントごと・ユーザーごとに分離されるため、異なる2つのSynologyアカウント上で同じ数値の `user_id` +であってもトランスクリプト状態は共有されません。 +有効な各アカウントには、異なる `webhookPath` を指定してください。OpenClawは現在、完全に同一のパスの重複を拒否し、 +マルチアカウント構成で共有Webhookパスを継承するだけの名前付きアカウントは起動を拒否します。 +意図的に名前付きアカウントで従来の継承が必要な場合は、 +そのアカウント、または `channels.synology-chat` に `dangerouslyAllowInheritedWebhookPath: true` を設定してください。 +ただし、完全に同一のパスの重複は引き続きフェイルクローズで拒否されます。明示的なアカウントごとのパス指定を推奨します。 ```json5 { @@ -156,35 +158,35 @@ openclaw message send --channel synology-chat --target synology-chat:123456 --te ## セキュリティに関する注意 -- `token`は秘密に保ち、漏えいした場合はローテーションしてください。 -- 自己署名のローカルNAS証明書を明示的に信頼している場合を除き、`allowInsecureSsl: false`を維持してください。 -- 受信webhookリクエストはトークン検証され、送信者ごとにレート制限されます。 -- 無効なトークンチェックでは定数時間のシークレット比較を使用し、fail-closedになります。 -- 本番環境では`dmPolicy: "allowlist"`を推奨します。 -- レガシーのusernameベース返信配信が明示的に必要な場合を除き、`dangerouslyAllowNameMatching`は無効のままにしてください。 -- 複数アカウント構成で共有パスのルーティングリスクを明示的に受け入れる場合を除き、`dangerouslyAllowInheritedWebhookPath`は無効のままにしてください。 +- `token` は秘密に保ち、漏えいした場合はローテーションしてください。 +- 自己署名のローカルNAS証明書を明示的に信頼する場合を除き、`allowInsecureSsl: false` を維持してください。 +- 受信Webhookリクエストは、トークン検証と送信者ごとのレート制限が行われます。 +- 無効なトークンのチェックには定数時間の秘密比較が使われ、フェイルクローズします。 +- 本番環境では `dmPolicy: "allowlist"` を推奨します。 +- 従来のユーザー名ベース返信配信が明示的に必要な場合を除き、`dangerouslyAllowNameMatching` は無効のままにしてください。 +- マルチアカウント構成での共有パスルーティングのリスクを明示的に許容する場合を除き、`dangerouslyAllowInheritedWebhookPath` は無効のままにしてください。 ## トラブルシューティング - `Missing required fields (token, user_id, text)`: - - 送信webhookペイロードに必要フィールドのいずれかが欠けています - - Synologyがトークンをヘッダーで送信している場合、Gateway/プロキシがそのヘッダーを保持していることを確認してください + - 送信Webhookのペイロードに必須フィールドのいずれかが欠けています + - Synologyがトークンをヘッダーで送る場合は、Gateway/プロキシがそのヘッダーを保持していることを確認してください - `Invalid token`: - - 送信webhookのシークレットが`channels.synology-chat.token`と一致していません - - リクエストが誤ったアカウント/webhook pathに到達しています - - リバースプロキシが、リクエストがOpenClawに届く前にトークンヘッダーを削除しました + - 送信Webhookシークレットが `channels.synology-chat.token` と一致していません + - リクエストが間違ったアカウント/Webhookパスに到達しています + - リバースプロキシが、リクエストがOpenClawに到達する前にトークンヘッダーを削除しました - `Rate limit exceeded`: - - 同じ送信元からの無効トークン試行が多すぎると、その送信元が一時的にロックアウトされることがあります - - 認証済み送信者にも、別途ユーザーごとのメッセージレート制限があります + - 同じ送信元からの無効トークン試行が多すぎると、その送信元は一時的にロックアウトされることがあります + - 認証済み送信者にも、ユーザーごとの別個のメッセージレート制限があります - `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`: - - `dmPolicy="allowlist"`が有効ですが、ユーザーが設定されていません + - `dmPolicy="allowlist"` は有効ですが、ユーザーが設定されていません - `User not authorized`: - - 送信者の数値`user_id`が`allowedUserIds`に含まれていません + - 送信者の数値 `user_id` が `allowedUserIds` に含まれていません ## 関連 -- [Channels Overview](/channels) — サポートされているすべてのチャンネル -- [Pairing](/channels/pairing) — DM認証とペアリングフロー -- [Groups](/channels/groups) — グループチャットの挙動とメンション制御 -- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング -- [Security](/gateway/security) — アクセスモデルとハードニング +- [Channels Overview](/ja-JP/channels) — サポートされるすべてのチャンネル +- [Pairing](/ja-JP/channels/pairing) — DM認証とペアリングフロー +- [Groups](/ja-JP/channels/groups) — グループチャットの動作とメンション制御 +- [Channel Routing](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/ja-JP/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/ci.md b/docs/ja-JP/ci.md index 888b21496..db59b402f 100644 --- a/docs/ja-JP/ci.md +++ b/docs/ja-JP/ci.md @@ -1,89 +1,89 @@ --- read_when: - - CIジョブが実行された、または実行されなかった理由を把握する必要があります - - 失敗しているGitHub Actionsチェックをデバッグしています -summary: CIジョブグラフ、スコープゲート、およびローカルコマンドの同等物 -title: CIパイプライン + - CI ジョブが実行された、または実行されなかった理由を理解する必要があります + - 失敗している GitHub Actions チェックをデバッグしています +summary: CI ジョブグラフ、スコープゲート、およびローカルコマンドの同等物 +title: CI パイプライン x-i18n: - generated_at: "2026-04-21T04:44:38Z" + generated_at: "2026-04-21T19:20:38Z" model: gpt-5.4 provider: openai - source_hash: 88a98d777fd61be1603417b71779aaf42a24d602b2437ad549f0075f22494cec + source_hash: 4d01a178402976cdf7c3c864695e8a12d3f7d1d069a77ea1b02a8aef2a3497f7 source_path: ci.md workflow: 15 --- -# CIパイプライン +# CI パイプライン -CIは、`main`へのすべてのpushとすべてのpull requestで実行されます。無関係な領域だけが変更された場合に高コストなジョブをスキップするため、スマートなスコープ判定を使用します。 +CI は `main` へのすべてのプッシュとすべてのプルリクエストで実行されます。スマートなスコープ判定を使って、変更が無関係な領域に限られる場合は高コストなジョブをスキップします。 ## ジョブ概要 -| Job | 目的 | 実行されるタイミング | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------- | -| `preflight` | docsのみの変更、変更されたスコープ、変更されたextensionsを検出し、CIマニフェストを構築する | draftではないpushとPRで常に実行 | -| `security-scm-fast` | `zizmor`による秘密鍵検出とworkflow監査 | draftではないpushとPRで常に実行 | -| `security-dependency-audit` | npm advisoriesに対する、依存関係なしの本番lockfile監査 | draftではないpushとPRで常に実行 | -| `security-fast` | 高速なsecurity jobsの必須aggregate | draftではないpushとPRで常に実行 | -| `build-artifacts` | `dist/`とControl UIを一度ビルドし、下流ジョブ向けに再利用可能なartifactsをアップロードする | Node関連の変更がある場合 | -| `checks-fast-core` | bundled/plugin-contract/protocol checksなどの高速なLinux正当性レーン | Node関連の変更がある場合 | -| `checks-fast-contracts-channels` | 安定したaggregate check結果を持つ、分割されたchannel contract checks | Node関連の変更がある場合 | -| `checks-node-extensions` | extension suite全体にわたるbundled-plugin test shards一式 | Node関連の変更がある場合 | -| `checks-node-core-test` | channel、bundled、contract、extensionレーンを除く、core Node test shards | Node関連の変更がある場合 | -| `extension-fast` | 変更されたbundled pluginsだけを対象にした集中テスト | extensionの変更が検出された場合 | -| `check` | 分割されたメインのローカルゲート相当: 本番types、lint、guards、test types、strict smoke | Node関連の変更がある場合 | -| `check-additional` | architecture、boundary、extension-surface guards、package-boundary、gateway-watch shards | Node関連の変更がある場合 | -| `build-smoke` | ビルド済みCLI smoke testsとstartup-memory smoke | Node関連の変更がある場合 | -| `checks` | 残りのLinux Nodeレーン: channel testsと、push時のみのNode 22互換性 | Node関連の変更がある場合 | -| `check-docs` | docsのフォーマット、lint、broken-link checks | docsが変更された場合 | -| `skills-python` | PythonベースのSkillsに対するRuff + pytest | Python Skills関連の変更がある場合 | -| `checks-windows` | Windows固有のテストレーン | Windows関連の変更がある場合 | -| `macos-node` | 共有のビルド済みartifactsを使うmacOS TypeScriptテストレーン | macOS関連の変更がある場合 | -| `macos-swift` | macOSアプリ向けのSwift lint、build、tests | macOS関連の変更がある場合 | -| `android` | Android buildおよびtest matrix | Android関連の変更がある場合 | +| ジョブ | 目的 | 実行されるタイミング | +| ---------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| `preflight` | docs-only の変更、変更スコープ、変更された extension を検出し、CI マニフェストを構築する | 下書きではないプッシュと PR で常に実行 | +| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | 下書きではないプッシュと PR で常に実行 | +| `security-dependency-audit` | npm advisory に対する、依存関係なしの本番 lockfile 監査 | 下書きではないプッシュと PR で常に実行 | +| `security-fast` | 高速なセキュリティジョブ向けの必須集約ジョブ | 下書きではないプッシュと PR で常に実行 | +| `build-artifacts` | `dist/` と Control UI を一度だけビルドし、後続ジョブ向けに再利用可能なアーティファクトをアップロード | Node 関連の変更 | +| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速 Linux 正当性レーン | Node 関連の変更 | +| `checks-fast-contracts-channels` | 安定した集約チェック結果を持つ、シャーディングされた channel contract チェック | Node 関連の変更 | +| `checks-node-extensions` | extension スイート全体にわたる bundled-plugin の完全なテストシャード | Node 関連の変更 | +| `checks-node-core-test` | channel、bundled、contract、extension の各レーンを除く、コア Node テストシャード | Node 関連の変更 | +| `extension-fast` | 変更された bundled plugins のみを対象にした集中的なテスト | extension の変更が検出されたとき | +| `check` | シャーディングされた主要なローカルゲート相当: 本番 types、lint、guards、test types、および strict smoke | Node 関連の変更 | +| `check-additional` | architecture、boundary、extension-surface guards、package-boundary、および gateway-watch のシャード | Node 関連の変更 | +| `build-smoke` | ビルド済み CLI のスモークテストと起動時メモリのスモークテスト | Node 関連の変更 | +| `checks` | 残りの Linux Node レーン: channel テストと、push 時のみの Node 22 互換性 | Node 関連の変更 | +| `check-docs` | docs のフォーマット、lint、およびリンク切れチェック | Docs が変更されたとき | +| `skills-python` | Python ベースの Skills 向けの Ruff + pytest | Python skill 関連の変更 | +| `checks-windows` | Windows 固有のテストレーン | Windows 関連の変更 | +| `macos-node` | 共有ビルドアーティファクトを使う macOS TypeScript テストレーン | macOS 関連の変更 | +| `macos-swift` | macOS アプリ向けの Swift lint、ビルド、およびテスト | macOS 関連の変更 | +| `android` | Android のビルドおよびテストマトリクス | Android 関連の変更 | -## Fail-Fastの順序 +## フェイルファスト順序 -ジョブは、高コストなものが動く前に低コストなチェックが失敗するように順序付けされています。 +ジョブは、安価なチェックが高コストなジョブより先に失敗するように順序付けられています。 -1. `preflight`が、そもそもどのレーンが存在するかを決定します。`docs-scope`と`changed-scope`のロジックは、独立したジョブではなく、このジョブ内のステップです。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、`skills-python`は、より重いartifactジョブやplatform matrixジョブを待たずに素早く失敗します。 -3. `build-artifacts`は高速なLinuxレーンと並行して実行され、下流の利用側が共有ビルドの準備完了後すぐに開始できるようにします。 -4. その後、より重いplatformおよびruntimeレーンが分岐して実行されます: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、`extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、`android`。 +1. `preflight` が、そもそもどのレーンを存在させるかを決定します。`docs-scope` と `changed-scope` のロジックは独立したジョブではなく、このジョブ内のステップです。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、および `skills-python` は、より重い artifact ジョブやプラットフォームマトリクスジョブを待たずに素早く失敗します。 +3. `build-artifacts` は高速 Linux レーンと並行して実行されるため、共有ビルドの準備ができ次第、下流の利用側が開始できます。 +4. その後、より重いプラットフォームおよびランタイムレーンが分岐します: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、`extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、および `android`。 -スコープロジックは`scripts/ci-changed-scope.mjs`にあり、`src/scripts/ci-changed-scope.test.ts`のユニットテストでカバーされています。 -別の`install-smoke` workflowは、自身の`preflight`ジョブを通じて同じスコープスクリプトを再利用します。より狭いchanged-smokeシグナルから`run_install_smoke`を計算するため、Docker/install smokeはinstall、packaging、container関連の変更に対してのみ実行されます。 +スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` のユニットテストでカバーされています。 +別個の `install-smoke` ワークフローも、自身の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。これは、より狭い changed-smoke シグナルから `run_install_smoke` を計算するため、Docker/install smoke は install、packaging、および container 関連の変更に対してのみ実行されます。 -ローカルのchanged-laneロジックは`scripts/changed-lanes.mjs`にあり、`scripts/check-changed.mjs`によって実行されます。そのローカルゲートは、広いCI platform scopeよりもarchitecture boundaryに対して厳格です。core productionの変更はcore prod typecheckに加えてcore testsを実行し、core test-onlyの変更はcore test typecheck/testsのみを実行し、extension productionの変更はextension prod typecheckに加えてextension testsを実行し、extension test-onlyの変更はextension test typecheck/testsのみを実行します。公開Plugin SDKまたはplugin-contractの変更は、extensionsがそれらのcore contractsに依存しているため、extension validationまで拡張されます。未知のroot/configの変更は、安全側に倒してすべてのレーンになります。 +ローカルの changed-lane ロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。このローカルゲートは、広い CI プラットフォームスコープよりも architecture boundary に対して厳格です: core production の変更は core prod の typecheck と core tests を実行し、core test のみの変更は core test の typecheck/tests のみを実行し、extension production の変更は extension prod の typecheck と extension tests を実行し、extension test のみの変更は extension test の typecheck/tests のみを実行します。公開 Plugin SDK または plugin-contract の変更は、extensions がそれらの core contract に依存しているため、extension validation まで拡張されます。不明な root/config の変更は、安全側に倒してすべてのレーンになります。 -push時には、`checks` matrixにpush専用の`compat-node22`レーンが追加されます。pull requestではそのレーンはスキップされ、matrixは通常のtest/channelレーンに集中したままになります。 +プッシュ時には、`checks` マトリクスに push 時のみの `compat-node22` レーンが追加されます。プルリクエストではこのレーンはスキップされ、マトリクスは通常の test/channel レーンに集中したままになります。 -最も遅いNode testファミリーは、各ジョブを小さく保つためにinclude-file shardsに分割されています。channel contractsはregistryとcore coverageをそれぞれ8つの重み付きshardに分割し、auto-reply reply command testsは4つのinclude-pattern shardに分割され、その他の大きなauto-reply reply prefix groupはそれぞれ2つのshardに分割されます。`check-additional`も、package-boundary compile/canary作業をruntime topology gateway/architecture作業から分離しています。 +最も遅い Node テスト群は、各ジョブを小さく保つために include-file シャードに分割されています: channel contracts は registry と core のカバレッジをそれぞれ 8 個の重み付きシャードに分割し、auto-reply の reply command テストは 4 個の include-pattern シャードに分割され、その他の大規模な auto-reply の reply prefix グループはそれぞれ 2 個のシャードに分割されます。`check-additional` も、package-boundary の compile/canary 作業を、ランタイムトポロジーの gateway/architecture 作業から分離しています。 -同じPRまたは`main` refに対して新しいpushが来ると、GitHubは置き換えられたジョブを`cancelled`としてマークすることがあります。同じrefに対する最新のrunも失敗していない限り、これはCIノイズとして扱ってください。aggregate shard checksでは、このキャンセルケースが明示的に示されるため、テスト失敗と区別しやすくなっています。 +同じ PR または `main` ref に対して新しいプッシュが届くと、GitHub は古いジョブを `cancelled` としてマークする場合があります。同じ ref の最新実行も失敗していない限り、これを CI ノイズとして扱ってください。集約シャードチェックは、このキャンセルのケースを明示的に示すため、テスト失敗と区別しやすくなっています。 -## Runners +## ランナー -| Runner | Jobs | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `blacksmith-16vcpu-ubuntu-2404` | `preflight`、`security-scm-fast`、`security-dependency-audit`、`security-fast`、`build-artifacts`、Linux checks、docs checks、Python skills、`android` | -| `blacksmith-32vcpu-windows-2025` | `checks-windows` | -| `macos-latest` | `macos-node`、`macos-swift` | +| ランナー | ジョブ | +| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blacksmith-16vcpu-ubuntu-2404` | `preflight`、`security-scm-fast`、`security-dependency-audit`、`security-fast`、`build-artifacts`、Linux チェック、docs チェック、Python skills、`android` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`、`macos-swift`。fork では `macos-latest` にフォールバック | ## ローカルでの同等コマンド ```bash -pnpm changed:lanes # origin/main...HEADに対するローカルchanged-lane classifierを確認 -pnpm check:changed # スマートなローカルゲート: boundary laneごとの変更されたtypecheck/lint/tests -pnpm check # 高速なローカルゲート: 本番tsgo + 分割lint + 並列fast guards +pnpm changed:lanes # origin/main...HEAD に対するローカルの changed-lane 分類器を確認 +pnpm check:changed # スマートなローカルゲート: boundary レーンごとの変更済み typecheck/lint/tests +pnpm check # 高速ローカルゲート: 本番 tsgo + シャーディングされた lint + 並列高速ガード pnpm check:test-types -pnpm check:timed # 各ステージの所要時間つきで同じゲートを実行 +pnpm check:timed # 同じゲートを各ステージの所要時間付きで実行 pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression -pnpm test # vitest tests +pnpm test # vitest テスト pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # docs format + lint + broken links -pnpm build # CIのartifact/build-smokeレーンが関係する場合にdistをビルド +pnpm check:docs # docs の format + lint + リンク切れ +pnpm build # CI の artifact/build-smoke レーンが重要な場合に dist をビルド ``` diff --git a/docs/ja-JP/gateway/multiple-gateways.md b/docs/ja-JP/gateway/multiple-gateways.md index d78a4ed21..ef2bb89c4 100644 --- a/docs/ja-JP/gateway/multiple-gateways.md +++ b/docs/ja-JP/gateway/multiple-gateways.md @@ -1,107 +1,76 @@ --- read_when: - - 同じマシンで複数のGatewayを実行する - - Gatewayごとに分離された設定、状態、ポートが必要です -summary: 1台のホストで複数のOpenClaw Gatewayを実行する（分離、ポート、プロファイル） -title: 複数のGateway + - 同じマシンで複数の Gateway を実行する + - Gateway ごとに、分離された設定、状態、ポートが必要です +summary: 1台のホストで複数の OpenClaw Gateway を実行する（分離、ポート、プロファイル） +title: 複数の Gateway x-i18n: - generated_at: "2026-04-21T17:45:43Z" + generated_at: "2026-04-21T19:20:39Z" model: gpt-5.4 provider: openai - source_hash: 8c3fcb921bc6596040e9249467964bd9dcd40ea7c16e958bb378247b0f994a7b + source_hash: 36796da339d5baea1704a7f42530030ea6ef4fa4bde43452ffec946b917ed4a3 source_path: gateway/multiple-gateways.md workflow: 15 --- -# 複数のGateway（同一ホスト） +# 複数の Gateway（同一ホスト） -ほとんどの構成では1つのGatewayを使用すべきです。1つのGatewayで複数のメッセージング接続とエージェントを処理できるためです。より強い分離や冗長性（例: レスキューボット）が必要な場合は、分離されたプロファイル/ポートで別々のGatewayを実行してください。 +ほとんどの構成では、1つの Gateway で複数のメッセージング接続とエージェントを処理できるため、1つの Gateway を使うべきです。より強い分離や冗長性（たとえばレスキューボット）が必要な場合は、プロファイルとポートを分離した別々の Gateway を実行してください。 -## 分離チェックリスト（必須） +## 最も推奨されるセットアップ -- `OPENCLAW_CONFIG_PATH` — インスタンスごとの設定ファイル -- `OPENCLAW_STATE_DIR` — インスタンスごとのセッション、認証情報、キャッシュ -- `agents.defaults.workspace` — インスタンスごとのワークスペースルート -- `gateway.port`（または `--port`）— インスタンスごとに一意 -- 派生ポート（browser/canvas）は重複してはいけません - -これらを共有すると、設定の競合やポートの衝突が発生します。 - -## 推奨: メインにはデフォルトプロファイルを使い、レスキューには名前付きプロファイルを使う - -プロファイルは `OPENCLAW_STATE_DIR` と `OPENCLAW_CONFIG_PATH` を自動的にスコープし、サービス名に接尾辞を付けます。ほとんどのレスキューボット構成では、メインボットはデフォルトプロファイルのままにし、レスキューボットにだけ `rescue` のような名前付きプロファイルを割り当ててください。 - -```bash -# main (default profile) -openclaw setup -openclaw gateway --port 18789 - -# rescue -openclaw --profile rescue setup -openclaw --profile rescue gateway --port 19001 -``` - -サービス: - -```bash -openclaw gateway install -openclaw --profile rescue gateway install -``` - -両方のGatewayで名前付きプロファイルを使いたい場合でも動作しますが、必須ではありません。 - -## レスキューボットガイド - -推奨構成: +ほとんどのユーザーにとって、最もシンプルなレスキューボット構成は次のとおりです。 - メインボットはデフォルトプロファイルのままにする - レスキューボットは `--profile rescue` で実行する -- レスキューアカウントには完全に別のTelegramボットを使う -- レスキューボットは `19001` のような別のベースポートにする +- レスキュー用アカウントには完全に別の Telegram ボットを使う +- レスキューボットは `19789` のような別のベースポートで実行する -こうすることで、メインボットからレスキューボットを分離でき、プライマリボットが停止していても、デバッグや設定変更の適用ができます。派生する browser/canvas/CDP ポートが衝突しないよう、ベースポートの間は少なくとも20空けてください。 +これにより、レスキューボットはメインボットから分離されるため、プライマリボットが停止していても設定変更の適用やデバッグができます。派生する browser/canvas/CDP ポートが決して衝突しないように、ベースポート同士は少なくとも20以上離してください。 -### 推奨されるレスキューチャンネル/アカウント +## レスキューボットのクイックスタート -ほとんどの構成では、レスキュープロファイルには完全に別のTelegramボットを使ってください。 - -Telegramを使う理由: - -- オペレーター専用にしやすい -- ボットトークンとIDが分離される -- メインボットのチャンネル/アプリのインストールから独立している -- メインボットが壊れたときにDMベースの簡単な復旧経路になる - -重要なのは完全な独立性です。別のボットアカウント、別の認証情報、別のOpenClawプロファイル、別のワークスペース、別のポートが必要です。 - -### 推奨インストールフロー - -特別な理由がない限り、これをデフォルト構成として使ってください。 +強い理由がない限り、これをデフォルトの手順として使ってください。 ```bash -# Main bot (default profile, port 18789) -openclaw onboard -openclaw gateway install - -# Rescue bot (separate Telegram bot, separate profile, port 19001) +# Rescue bot (separate Telegram bot, separate profile, port 19789) openclaw --profile rescue onboard -openclaw --profile rescue gateway install +openclaw --profile rescue gateway install --port 19789 ``` -`openclaw --profile rescue onboard` の実行中: +メインボットがすでに実行中であれば、通常はこれだけで十分です。 -- 別のTelegramボットトークンを使う -- `rescue` プロファイルを維持する +`openclaw --profile rescue onboard` の実行中は、次のようにしてください。 + +- 別の Telegram ボットトークンを使う +- `rescue` プロファイルのままにする - メインボットより少なくとも20高いベースポートを使う -- すでに自分で管理している場合を除き、デフォルトのレスキューワークスペースを受け入れる +- すでに独自に管理しているのでなければ、デフォルトの rescue ワークスペースを受け入れる -オンボーディングですでにレスキューサービスがインストールされている場合、最後の `gateway install` は不要です。 +オンボーディングがすでにレスキューサービスをインストールしている場合、最後の `gateway install` は不要です。 -### オンボーディングで変更される内容 +## これが機能する理由 + +レスキューボットは、次の専用リソースを持つため独立性を保てます。 + +- プロファイル/設定 +- 状態ディレクトリ +- ワークスペース +- ベースポート（および派生ポート） +- Telegram ボットトークン + +ほとんどの構成では、rescue プロファイル用に完全に別の Telegram ボットを使ってください。 + +- オペレーター専用に保ちやすい +- ボットトークンと識別情報が分離される +- メインボットのチャネル/アプリのインストールから独立している +- メインボットが壊れているときに、DM ベースで簡単に復旧できる経路になる + +## `--profile rescue onboard` が変更するもの `openclaw --profile rescue onboard` は通常のオンボーディングフローを使いますが、すべてを別のプロファイルに書き込みます。 -実際には、レスキューボットは次の専用領域を持つことになります。 +実際には、レスキューボットは次の専用リソースを持つことになります。 - 設定ファイル - 状態ディレクトリ @@ -110,24 +79,71 @@ openclaw --profile rescue gateway install それ以外のプロンプトは通常のオンボーディングと同じです。 -## ポートマッピング（派生） +## 一般的なマルチ Gateway 構成 + +上記のレスキューボット構成が最も簡単なデフォルトですが、同じ分離パターンは、1台のホスト上の任意の2つ以上の Gateway の組み合わせにも使えます。 + +より一般的な構成では、追加する各 Gateway に固有の名前付きプロファイルと固有のベースポートを割り当ててください。 + +```bash +# main (default profile) +openclaw setup +openclaw gateway --port 18789 + +# extra gateway +openclaw --profile ops setup +openclaw --profile ops gateway --port 19789 +``` + +両方の Gateway で名前付きプロファイルを使いたい場合も問題ありません。 + +```bash +openclaw --profile main setup +openclaw --profile main gateway --port 18789 + +openclaw --profile ops setup +openclaw --profile ops gateway --port 19789 +``` + +サービスも同じパターンに従います。 + +```bash +openclaw gateway install +openclaw --profile ops gateway install --port 19789 +``` + +フォールバック用のオペレーター経路が必要な場合は、レスキューボットのクイックスタートを使ってください。異なるチャネル、テナント、ワークスペース、または運用上の役割のために、複数の長期間稼働する Gateway が必要な場合は、一般的なプロファイルパターンを使ってください。 + +## 分離チェックリスト + +各 Gateway インスタンスごとに、次を固有にしてください。 + +- `OPENCLAW_CONFIG_PATH` — インスタンスごとの設定ファイル +- `OPENCLAW_STATE_DIR` — インスタンスごとのセッション、認証情報、キャッシュ +- `agents.defaults.workspace` — インスタンスごとのワークスペースルート +- `gateway.port`（または `--port`）— インスタンスごとに固有 +- 派生する browser/canvas/CDP ポート + +これらが共有されていると、設定の競合とポート競合が発生します。 + +## ポート対応表（派生） ベースポート = `gateway.port`（または `OPENCLAW_GATEWAY_PORT` / `--port`）。 -- browser control service port = ベース + 2（loopback のみ） -- canvas host はGateway HTTPサーバーで提供されます（`gateway.port` と同じポート） -- Browser profile CDP ports は `browser.controlPort + 9 .. + 108` から自動割り当てされます +- browser 制御サービスのポート = ベース + 2（local loopback のみ） +- canvas host は Gateway HTTP サーバー上で提供される（`gateway.port` と同じポート） +- Browser プロファイルの CDP ポートは `browser.controlPort + 9 .. + 108` から自動割り当てされる -設定または環境変数でこれらを上書きする場合は、インスタンスごとに一意に保つ必要があります。 +設定または環境変数でこれらのいずれかを上書きする場合は、インスタンスごとに固有である必要があります。 -## Browser/CDP の注意点（よくある落とし穴） +## Browser/CDP に関する注意（よくある落とし穴） -- 複数のインスタンスで `browser.cdpUrl` を同じ値に固定**しないでください**。 -- 各インスタンスには、それぞれ専用の browser control port と CDP 範囲（gateway port から派生）が必要です。 -- 明示的なCDPポートが必要な場合は、インスタンスごとに `browser.profiles..cdpPort` を設定してください。 -- リモートChromeでは、`browser.profiles..cdpUrl` を使ってください（プロファイルごと、インスタンスごと）。 +- 複数のインスタンスで `browser.cdpUrl` を同じ値に固定しては **いけません**。 +- 各インスタンスには、専用の browser 制御ポートと CDP 範囲（gateway port から派生）が必要です。 +- 明示的な CDP ポートが必要な場合は、インスタンスごとに `browser.profiles..cdpPort` を設定してください。 +- リモート Chrome では、`browser.profiles..cdpUrl` を使ってください（プロファイルごと、インスタンスごと）。 -## 手動 env 例 +## 手動 env の例 ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \ @@ -136,7 +152,7 @@ openclaw gateway --port 18789 OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \ OPENCLAW_STATE_DIR=~/.openclaw-rescue \ -openclaw gateway --port 19001 +openclaw gateway --port 19789 ``` ## クイックチェック @@ -152,5 +168,5 @@ openclaw --profile rescue browser status 解釈: -- `gateway status --deep` は、古いインストールから残っている古い launchd/systemd/schtasks サービスの検出に役立ちます。 -- `gateway probe` の `multiple reachable gateways detected` のような警告テキストは、意図的に複数の分離されたGatewayを実行している場合にのみ想定されるものです。 +- `gateway status --deep` は、古いインストールによる古い launchd/systemd/schtasks サービスを見つけるのに役立ちます。 +- `gateway probe` の `multiple reachable gateways detected` のような警告文は、複数の分離された gateway を意図的に実行している場合にのみ想定されるものです。 diff --git a/docs/ja-JP/plugins/manifest.md b/docs/ja-JP/plugins/manifest.md index 6eef64223..363c154c5 100644 --- a/docs/ja-JP/plugins/manifest.md +++ b/docs/ja-JP/plugins/manifest.md @@ -1,65 +1,65 @@ --- read_when: - - OpenClaw Pluginを構築しています - - Pluginの設定スキーマを提供する必要がある、またはPluginのバリデーションエラーをデバッグする必要がある -summary: Pluginマニフェスト + JSONスキーマの要件（厳格な設定バリデーション） + - あなたはOpenClaw Pluginを構築しています + - Plugin設定スキーマを提供するか、Pluginの検証エラーをデバッグする必要があります +summary: Pluginマニフェスト + JSONスキーマの要件（厳格な設定検証） title: Pluginマニフェスト x-i18n: - generated_at: "2026-04-19T01:11:04Z" + generated_at: "2026-04-21T19:20:37Z" model: gpt-5.4 provider: openai - source_hash: 2dfc00759108ddee7bfcda8c42acf7f2d47451676447ba3caf8b5950f8a1c181 + source_hash: 304c08035724dfb1ce6349972729b621aafc00880d4d259db78c22b86e9056ba source_path: plugins/manifest.md workflow: 15 --- -# Pluginマニフェスト（`openclaw.plugin.json`） +# Pluginマニフェスト (`openclaw.plugin.json`) このページは、**ネイティブなOpenClaw Pluginマニフェスト**のみを対象としています。 -互換性のあるバンドルレイアウトについては、[Plugin bundles](/ja-JP/plugins/bundles)を参照してください。 +互換バンドルのレイアウトについては、[Plugin bundles](/ja-JP/plugins/bundles)を参照してください。 互換バンドル形式では、異なるマニフェストファイルを使用します。 -- Codexバンドル: `.codex-plugin/plugin.json` -- Claudeバンドル: `.claude-plugin/plugin.json` またはマニフェストなしのデフォルトのClaudeコンポーネントレイアウト -- Cursorバンドル: `.cursor-plugin/plugin.json` +- Codex bundle: `.codex-plugin/plugin.json` +- Claude bundle: `.claude-plugin/plugin.json` またはマニフェストなしのデフォルトのClaude componentレイアウト +- Cursor bundle: `.cursor-plugin/plugin.json` -OpenClawはそれらのバンドルレイアウトも自動検出しますが、ここで説明する`openclaw.plugin.json`スキーマに対してはバリデーションされません。 +OpenClawはそれらのバンドルレイアウトも自動検出しますが、ここで説明する `openclaw.plugin.json` スキーマに対しては検証されません。 -互換バンドルについて、OpenClawは現在、レイアウトがOpenClawランタイムの想定に一致する場合に、バンドルメタデータに加えて、宣言されたskillルート、Claudeコマンドルート、Claudeバンドルの`settings.json`デフォルト、ClaudeバンドルのLSPデフォルト、およびサポートされるhook packを読み取ります。 +互換バンドルについて、OpenClawは現在、レイアウトがOpenClawランタイムの期待に一致している場合に、バンドルメタデータに加えて、宣言されたskillルート、Claude commandルート、Claude bundleの `settings.json` デフォルト値、Claude bundleのLSPデフォルト値、およびサポートされるhook packを読み取ります。 -すべてのネイティブなOpenClaw Pluginは、**Pluginルート**に`openclaw.plugin.json`ファイルを必ず含める必要があります。OpenClawはこのマニフェストを使って、**Pluginコードを実行せずに**設定をバリデーションします。マニフェストが存在しない、または無効な場合はPluginエラーとして扱われ、設定バリデーションはブロックされます。 +すべてのネイティブなOpenClaw Pluginは、**pluginルート**に `openclaw.plugin.json` ファイルを**必ず**含める必要があります。OpenClawはこのマニフェストを使用して、**Pluginコードを実行せずに**設定を検証します。マニフェストが存在しない、または無効な場合はPluginエラーとして扱われ、設定の検証がブロックされます。 完全なPluginシステムガイドについては、[Plugins](/ja-JP/tools/plugin)を参照してください。 -ネイティブなcapabilityモデルと現在の外部互換性ガイダンスについては、 +ネイティブなcapability modelと現在の外部互換性ガイダンスについては、 [Capability model](/ja-JP/plugins/architecture#public-capability-model)を参照してください。 ## このファイルの役割 -`openclaw.plugin.json`は、OpenClawがPluginコードをロードする前に読み取るメタデータです。 +`openclaw.plugin.json` は、OpenClawがPluginコードをロードする前に読み取るメタデータです。 用途: - Pluginの識別情報 -- 設定バリデーション +- 設定の検証 - Pluginランタイムを起動せずに利用可能であるべき認証およびオンボーディングのメタデータ -- ランタイムがロードされる前にコントロールプレーンのサーフェスが確認できる、軽量なアクティベーションヒント -- ランタイムがロードされる前にセットアップ／オンボーディングのサーフェスが確認できる、軽量なセットアップ記述子 -- Pluginランタイムがロードされる前に解決されるべきエイリアスおよび自動有効化メタデータ -- ランタイムがロードされる前にPluginを自動アクティベートすべき、省略記法のモデルファミリー所有メタデータ -- バンドルされた互換性配線およびコントラクトカバレッジで使用される静的なcapability所有スナップショット -- 共有の`openclaw qa`ホストがPluginランタイムのロード前に確認できる、軽量なQAランナーメタデータ -- ランタイムをロードせずにカタログおよびバリデーションのサーフェスへマージされるべき、チャネル固有の設定メタデータ +- コントロールプレーンの画面がランタイムのロード前に確認できる、アクティベーションの軽量なヒント +- セットアップ/オンボーディングの画面がランタイムのロード前に確認できる、セットアップの軽量な記述子 +- Pluginランタイムのロード前に解決されるべきエイリアスおよび自動有効化メタデータ +- Pluginランタイムのロード前にPluginを自動アクティベートすべき、モデルファミリー所有権の簡略メタデータ +- バンドル済み互換配線および契約カバレッジに使用される、静的なcapability ownershipスナップショット +- 共有の `openclaw qa` ホストがPluginランタイムのロード前に確認できる、軽量なQA runnerメタデータ +- ランタイムをロードせずに、カタログおよび検証画面にマージされるべきチャネル固有の設定メタデータ - 設定UIのヒント 用途ではないもの: - ランタイム動作の登録 -- コードエントリーポイントの宣言 -- npmインストールメタデータ +- コードのエントリーポイントの宣言 +- npm installメタデータ -これらはPluginコードと`package.json`に属します。 +これらはPluginコードおよび `package.json` に属します。 ## 最小例 @@ -139,64 +139,64 @@ OpenClawはそれらのバンドルレイアウトも自動検出しますが、 ## トップレベルフィールドのリファレンス -| フィールド | 必須 | 型 | 意味 | +| フィールド | 必須 | 型 | 意味 | | ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | はい | `string` | 正規のPlugin idです。このidは`plugins.entries.`で使用されます。 | -| `configSchema` | はい | `object` | このPluginの設定に対するインラインJSON Schemaです。 | -| `enabledByDefault` | いいえ | `true` | バンドルされたPluginをデフォルトで有効としてマークします。省略するか、`true`以外の値を設定すると、そのPluginはデフォルトで無効のままになります。 | -| `legacyPluginIds` | いいえ | `string[]` | この正規Plugin idに正規化されるレガシーidです。 | -| `autoEnableWhenConfiguredProviders` | いいえ | `string[]` | 認証、設定、またはモデル参照でこれらが言及されたときに、このPluginを自動有効化すべきprovider idです。 | -| `kind` | いいえ | `"memory"` \| `"context-engine"` | `plugins.slots.*`で使用される排他的なPlugin種別を宣言します。 | -| `channels` | いいえ | `string[]` | このPluginが所有するチャネルidです。検出と設定バリデーションに使用されます。 | -| `providers` | いいえ | `string[]` | このPluginが所有するprovider idです。 | -| `modelSupport` | いいえ | `object` | ランタイムの前にPluginを自動ロードするために使われる、マニフェスト所有の省略記法モデルファミリーメタデータです。 | -| `providerEndpoints` | いいえ | `object[]` | providerランタイムがロードされる前にコアが分類する必要があるproviderルート向けの、マニフェスト所有のendpoint host/baseUrlメタデータです。 | -| `cliBackends` | いいえ | `string[]` | このPluginが所有するCLI推論バックエンドidです。明示的な設定参照からの起動時自動アクティベーションに使用されます。 | -| `syntheticAuthRefs` | いいえ | `string[]` | ランタイムがロードされる前のコールドなモデル検出中に、このPlugin所有のsynthetic auth hookをプローブすべきproviderまたはCLIバックエンド参照です。 | -| `nonSecretAuthMarkers` | いいえ | `string[]` | 非シークレットなローカル、OAuth、または環境依存の認証状態を表す、バンドルされたPlugin所有のプレースホルダーAPI key値です。 | -| `commandAliases` | いいえ | `object[]` | ランタイムがロードされる前に、Plugin対応の設定およびCLI診断を生成すべき、このPluginが所有するコマンド名です。 | -| `providerAuthEnvVars` | いいえ | `Record` | OpenClawがPluginコードをロードせずに確認できる、軽量なprovider認証envメタデータです。 | -| `providerAuthAliases` | いいえ | `Record` | 認証参照時に別のprovider idを再利用すべきprovider idです。たとえば、ベースproviderのAPI keyと認証プロファイルを共有するcoding providerなどです。 | -| `channelEnvVars` | いいえ | `Record` | OpenClawがPluginコードをロードせずに確認できる、軽量なチャネルenvメタデータです。envベースのチャネルセットアップや、汎用の起動／設定ヘルパーが認識すべき認証サーフェスにはこれを使用してください。 | -| `providerAuthChoices` | いいえ | `object[]` | オンボーディングの選択UI、優先providerの解決、単純なCLIフラグ配線のための軽量な認証選択メタデータです。 | -| `activation` | いいえ | `object` | provider、コマンド、チャネル、ルート、capabilityトリガーによるロードのための軽量なアクティベーションヒントです。メタデータのみであり、実際の動作は引き続きPluginランタイムが所有します。 | -| `setup` | いいえ | `object` | 検出およびセットアップのサーフェスがPluginランタイムをロードせずに確認できる、軽量なセットアップ／オンボーディング記述子です。 | -| `qaRunners` | いいえ | `object[]` | ランタイムがロードされる前に共有の`openclaw qa`ホストで使用される、軽量なQAランナー記述子です。 | -| `contracts` | いいえ | `object` | speech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search、およびtool ownershipに関する静的なバンドルcapabilityスナップショットです。 | -| `channelConfigs` | いいえ | `Record` | ランタイムがロードされる前に検出およびバリデーションのサーフェスへマージされる、マニフェスト所有のチャネル設定メタデータです。 | -| `skills` | いいえ | `string[]` | Pluginルートからの相対パスで指定する、ロードするSkillsディレクトリです。 | -| `name` | いいえ | `string` | 人間が読めるPlugin名です。 | -| `description` | いいえ | `string` | Pluginサーフェスに表示される短い概要です。 | -| `version` | いいえ | `string` | 情報用のPluginバージョンです。 | -| `uiHints` | いいえ | `Record` | 設定フィールドに対するUIラベル、プレースホルダー、および機密性ヒントです。 | +| `id` | はい | `string` | 正規のPlugin IDです。これは `plugins.entries.` で使われるIDです。 | +| `configSchema` | はい | `object` | このPluginの設定に対するインラインJSON Schemaです。 | +| `enabledByDefault` | いいえ | `true` | バンドル済みPluginがデフォルトで有効であることを示します。デフォルトで無効のままにするには、省略するか、`true` 以外の任意の値を設定します。 | +| `legacyPluginIds` | いいえ | `string[]` | この正規Plugin IDに正規化されるレガシーIDです。 | +| `autoEnableWhenConfiguredProviders` | いいえ | `string[]` | 認証、設定、またはモデル参照でこれらが言及されたときに、このPluginを自動有効化すべきprovider IDです。 | +| `kind` | いいえ | `"memory"` \| `"context-engine"` | `plugins.slots.*` で使われる排他的なPlugin種別を宣言します。 | +| `channels` | いいえ | `string[]` | このPluginが所有するchannel IDです。検出および設定検証に使用されます。 | +| `providers` | いいえ | `string[]` | このPluginが所有するprovider IDです。 | +| `modelSupport` | いいえ | `object` | ランタイムの前にPluginを自動ロードするために使われる、マニフェスト所有の簡略モデルファミリーメタデータです。 | +| `providerEndpoints` | いいえ | `object[]` | コアがproviderランタイムのロード前に分類しなければならないproviderルート向けの、マニフェスト所有のendpoint host/baseUrlメタデータです。 | +| `cliBackends` | いいえ | `string[]` | このPluginが所有するCLI推論backend IDです。明示的な設定参照からの起動時自動アクティベーションに使用されます。 | +| `syntheticAuthRefs` | いいえ | `string[]` | ランタイムのロード前に、コールドモデル検出中にPlugin所有のsynthetic auth hookを調査すべきproviderまたはCLI backend参照です。 | +| `nonSecretAuthMarkers` | いいえ | `string[]` | 非シークレットなローカル、OAuth、またはアンビエント認証情報の状態を表す、バンドル済みPlugin所有のプレースホルダーAPIキー値です。 | +| `commandAliases` | いいえ | `object[]` | ランタイムのロード前に、Plugin対応の設定およびCLI診断を生成すべき、このPluginが所有するコマンド名です。 | +| `providerAuthEnvVars` | いいえ | `Record` | OpenClawがPluginコードをロードせずに確認できる、軽量なprovider認証envメタデータです。 | +| `providerAuthAliases` | いいえ | `Record` | 認証参照に別のprovider IDを再利用すべきprovider IDです。たとえば、ベースproviderのAPIキーや認証プロファイルを共有するcoding providerなどです。 | +| `channelEnvVars` | いいえ | `Record` | OpenClawがPluginコードをロードせずに確認できる、軽量なchannel envメタデータです。env駆動のchannelセットアップや、汎用の起動/設定ヘルパーが認識すべき認証画面にはこれを使用してください。 | +| `providerAuthChoices` | いいえ | `object[]` | オンボーディングピッカー、優先provider解決、単純なCLIフラグ配線のための、軽量な認証選択メタデータです。 | +| `activation` | いいえ | `object` | provider、command、channel、route、およびcapabilityトリガー読み込み向けの軽量なアクティベーションヒントです。メタデータのみであり、実際の動作は引き続きPluginランタイムが所有します。 | +| `setup` | いいえ | `object` | 検出およびセットアップ画面がPluginランタイムをロードせずに確認できる、軽量なセットアップ/オンボーディング記述子です。 | +| `qaRunners` | いいえ | `object[]` | 共有の `openclaw qa` ホストがPluginランタイムのロード前に使用する、軽量なQA runner記述子です。 | +| `contracts` | いいえ | `object` | speech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search、およびtool所有権に対する静的なバンドル済みcapabilityスナップショットです。 | +| `channelConfigs` | いいえ | `Record` | ランタイムのロード前に検出および検証画面へマージされる、マニフェスト所有のchannel設定メタデータです。 | +| `skills` | いいえ | `string[]` | Pluginルートからの相対パスで指定する、ロードするSkillsディレクトリです。 | +| `name` | いいえ | `string` | 人が読めるPlugin名です。 | +| `description` | いいえ | `string` | Plugin画面に表示される短い要約です。 | +| `version` | いいえ | `string` | 情報用のPluginバージョンです。 | +| `uiHints` | いいえ | `Record` | 設定フィールドに対するUIラベル、プレースホルダー、および機密性ヒントです。 | ## `providerAuthChoices` リファレンス -各`providerAuthChoices`エントリは、1つのオンボーディングまたは認証の選択肢を記述します。 -OpenClawはこれをproviderランタイムがロードされる前に読み取ります。 +各 `providerAuthChoices` エントリは、1つのオンボーディングまたは認証の選択肢を記述します。 +OpenClawはこれをproviderランタイムのロード前に読み取ります。 -| フィールド | 必須 | 型 | 意味 | -| --------------------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | はい | `string` | この選択肢が属するprovider idです。 | -| `method` | はい | `string` | ディスパッチ先となる認証方式idです。 | -| `choiceId` | はい | `string` | オンボーディングおよびCLIフローで使用される安定したauth-choice idです。 | -| `choiceLabel` | いいえ | `string` | ユーザー向けラベルです。省略した場合、OpenClawは`choiceId`を代わりに使用します。 | -| `choiceHint` | いいえ | `string` | ピッカー用の短い補足テキストです。 | -| `assistantPriority` | いいえ | `number` | アシスタント主導の対話型ピッカーで、値が小さいものほど先に並びます。 | -| `assistantVisibility` | いいえ | `"visible"` \| `"manual-only"` | アシスタントのピッカーからはこの選択肢を隠しつつ、手動CLI選択は引き続き許可します。 | -| `deprecatedChoiceIds` | いいえ | `string[]` | ユーザーをこの置き換え後の選択肢へリダイレクトすべき、レガシーなchoice idです。 | -| `groupId` | いいえ | `string` | 関連する選択肢をグループ化するための任意のgroup idです。 | -| `groupLabel` | いいえ | `string` | そのグループのユーザー向けラベルです。 | -| `groupHint` | いいえ | `string` | そのグループ向けの短い補足テキストです。 | -| `optionKey` | いいえ | `string` | 単一フラグのシンプルな認証フローで使う内部オプションキーです。 | -| `cliFlag` | いいえ | `string` | `--openrouter-api-key`のようなCLIフラグ名です。 | -| `cliOption` | いいえ | `string` | `--openrouter-api-key `のような完全なCLIオプション形式です。 | -| `cliDescription` | いいえ | `string` | CLIヘルプで使われる説明です。 | -| `onboardingScopes` | いいえ | `Array<"text-inference" \| "image-generation">` | この選択肢を表示すべきオンボーディングのサーフェスです。省略した場合、デフォルトは`["text-inference"]`です。 | +| フィールド | 必須 | 型 | 意味 | +| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | はい | `string` | この選択肢が属するprovider IDです。 | +| `method` | はい | `string` | ディスパッチ先の認証方式IDです。 | +| `choiceId` | はい | `string` | オンボーディングおよびCLIフローで使われる安定した認証選択肢IDです。 | +| `choiceLabel` | いいえ | `string` | ユーザー向けラベルです。省略された場合、OpenClawは `choiceId` にフォールバックします。 | +| `choiceHint` | いいえ | `string` | ピッカー用の短いヘルパーテキストです。 | +| `assistantPriority` | いいえ | `number` | assistant主導の対話型ピッカーでは、値が小さいほど先に並びます。 | +| `assistantVisibility` | いいえ | `"visible"` \| `"manual-only"` | assistantのピッカーではこの選択肢を非表示にしつつ、手動のCLI選択は引き続き可能にします。 | +| `deprecatedChoiceIds` | いいえ | `string[]` | ユーザーをこの置き換え選択肢へリダイレクトすべきレガシーchoice IDです。 | +| `groupId` | いいえ | `string` | 関連する選択肢をグループ化するための任意のgroup IDです。 | +| `groupLabel` | いいえ | `string` | そのグループのユーザー向けラベルです。 | +| `groupHint` | いいえ | `string` | グループ用の短いヘルパーテキストです。 | +| `optionKey` | いいえ | `string` | 単一フラグの単純な認証フロー用の内部optionキーです。 | +| `cliFlag` | いいえ | `string` | `--openrouter-api-key` のようなCLIフラグ名です。 | +| `cliOption` | いいえ | `string` | `--openrouter-api-key ` のような完全なCLIオプション形式です。 | +| `cliDescription` | いいえ | `string` | CLIヘルプで使われる説明です。 | +| `onboardingScopes` | いいえ | `Array<"text-inference" \| "image-generation">` | この選択肢を表示すべきオンボーディング画面です。省略された場合、デフォルトは `["text-inference"]` です。 | ## `commandAliases` リファレンス -Pluginが、ユーザーが誤って`plugins.allow`に入れたり、ルートCLIコマンドとして実行しようとしたりする可能性があるランタイムコマンド名を所有している場合は、`commandAliases`を使用します。OpenClawはこのメタデータを、Pluginランタイムコードをインポートせずに診断に使用します。 +ユーザーがそれを誤って `plugins.allow` に書いたり、ルートCLIコマンドとして実行しようとしたりする可能性がある、Plugin所有のランタイムコマンド名がある場合は `commandAliases` を使います。OpenClawはこのメタデータを、Pluginランタイムコードをimportせずに診断に利用します。 ```json { @@ -210,37 +210,37 @@ Pluginが、ユーザーが誤って`plugins.allow`に入れたり、ルートCL } ``` -| フィールド | 必須 | 型 | 意味 | -| ------------ | -------- | ----------------- | ---------------------------------------------------------------------------- | -| `name` | はい | `string` | このPluginに属するコマンド名です。 | -| `kind` | いいえ | `"runtime-slash"` | そのエイリアスを、ルートCLIコマンドではなくチャットのスラッシュコマンドとして示します。 | -| `cliCommand` | いいえ | `string` | 存在する場合、CLI操作向けに提案する関連するルートCLIコマンドです。 | +| フィールド | 必須 | 型 | 意味 | +| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | +| `name` | はい | `string` | このPluginに属するコマンド名です。 | +| `kind` | いいえ | `"runtime-slash"` | このエイリアスを、ルートCLIコマンドではなくチャットのスラッシュコマンドとして示します。 | +| `cliCommand` | いいえ | `string` | 存在する場合、CLI操作向けに提案する関連ルートCLIコマンドです。 | ## `activation` リファレンス -Pluginが、どのコントロールプレーンイベントによって後でアクティベートされるべきかを軽量に宣言できる場合は、`activation`を使用します。 +Pluginがどのコントロールプレーンイベントで後からアクティベートされるべきかを低コストで宣言できる場合は、`activation` を使います。 ## `qaRunners` リファレンス -Pluginが共有の`openclaw qa`ルート配下に1つ以上のトランスポートランナーを提供する場合は、`qaRunners`を使用します。このメタデータは軽量かつ静的に保ってください。実際のCLI登録は引き続きPluginランタイムが所有し、`qaRunnerCliRegistrations`をエクスポートする軽量な`runtime-api.ts`サーフェスを通じて行います。 +Pluginが共有の `openclaw qa` ルート配下に1つ以上のtransport runnerを提供する場合は、`qaRunners` を使います。このメタデータは軽量かつ静的に保ってください。実際のCLI登録は引き続きPluginランタイムが所有し、`qaRunnerCliRegistrations` をexportする軽量な `runtime-api.ts` サーフェスを通じて行います。 ```json { "qaRunners": [ { "commandName": "matrix", - "description": "使い捨てhomeserverに対してDockerベースのMatrixライブQAレーンを実行します" + "description": "使い捨てのhomeserverに対してDockerベースのMatrixライブQAレーンを実行します" } ] } ``` -| フィールド | 必須 | 型 | 意味 | -| ------------- | -------- | -------- | ---------------------------------------------------------------------- | -| `commandName` | はい | `string` | `openclaw qa`配下にマウントされるサブコマンドです。たとえば`matrix`です。 | -| `description` | いいえ | `string` | 共有ホストがスタブコマンドを必要とするときに使うフォールバックのヘルプテキストです。 | +| フィールド | 必須 | 型 | 意味 | +| ------------- | -------- | -------- | ------------------------------------------------------------------ | +| `commandName` | はい | `string` | `openclaw qa` 配下にマウントされるサブコマンドです。たとえば `matrix` です。 | +| `description` | いいえ | `string` | 共有ホストがスタブコマンドを必要とする場合に使われるフォールバックのヘルプテキストです。 | -このブロックはメタデータのみです。ランタイム動作を登録するものではなく、`register(...)`、`setupEntry`、その他のランタイム／Pluginエントリーポイントを置き換えるものでもありません。現在の利用側では、より広いPluginロードの前に絞り込みヒントとして使用されるため、activationメタデータが欠けていても通常は性能にのみ影響し、レガシーなマニフェスト所有フォールバックがまだ存在する限り、正しさは変わらないはずです。 +このブロックはメタデータ専用です。ランタイム動作を登録するものではなく、`register(...)`、`setupEntry`、その他のランタイム/Pluginエントリーポイントを置き換えるものでもありません。現在の利用側は、より広いPlugin読み込みの前に絞り込みヒントとしてこれを使用しているため、`activation` メタデータが欠けていても通常は性能コストが増えるだけです。レガシーなマニフェスト所有権フォールバックがまだ存在する間は、正しさは変わらないはずです。 ```json { @@ -254,27 +254,23 @@ Pluginが共有の`openclaw qa`ルート配下に1つ以上のトランスポー } ``` -| フィールド | 必須 | 型 | 意味 | -| ---------------- | -------- | ---------------------------------------------------- | ---------------------------------------------------------------- | -| `onProviders` | いいえ | `string[]` | 要求されたときにこのPluginをアクティベートすべきprovider idです。 | -| `onCommands` | いいえ | `string[]` | このPluginをアクティベートすべきコマンドidです。 | -| `onChannels` | いいえ | `string[]` | このPluginをアクティベートすべきチャネルidです。 | -| `onRoutes` | いいえ | `string[]` | このPluginをアクティベートすべきルート種別です。 | -| `onCapabilities` | いいえ | `Array<"provider" \| "channel" \| "tool" \| "hook">` | コントロールプレーンのアクティベーション計画で使われる大まかなcapabilityヒントです。 | +| フィールド | 必須 | 型 | 意味 | +| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- | +| `onProviders` | いいえ | `string[]` | 要求されたときにこのPluginをアクティベートすべきprovider IDです。 | +| `onCommands` | いいえ | `string[]` | このPluginをアクティベートすべきcommand IDです。 | +| `onChannels` | いいえ | `string[]` | このPluginをアクティベートすべきchannel IDです。 | +| `onRoutes` | いいえ | `string[]` | このPluginをアクティベートすべきroute種別です。 | +| `onCapabilities` | いいえ | `Array<"provider" \| "channel" \| "tool" \| "hook">` | コントロールプレーンのアクティベーション計画で使われる、広範なcapabilityヒントです。 | -現在の実利用側: +現在のライブ利用側: -- コマンドトリガーのCLI計画は、レガシーな - `commandAliases[].cliCommand` または `commandAliases[].name` にフォールバックします -- チャネルトリガーのセットアップ／チャネル計画は、明示的なチャネルactivationメタデータがない場合、 - レガシーな `channels[]` 所有にフォールバックします -- providerトリガーのセットアップ／ランタイム計画は、明示的なprovider - activationメタデータがない場合、レガシーな - `providers[]` とトップレベルの `cliBackends[]` 所有にフォールバックします +- commandトリガーのCLI計画は、レガシーな `commandAliases[].cliCommand` または `commandAliases[].name` にフォールバックします +- channelトリガーのセットアップ/チャネル計画は、明示的なchannel activationメタデータがない場合、レガシーな `channels[]` 所有権にフォールバックします +- providerトリガーのセットアップ/ランタイム計画は、明示的なprovider activationメタデータがない場合、レガシーな `providers[]` およびトップレベルの `cliBackends[]` 所有権にフォールバックします ## `setup` リファレンス -ランタイムがロードされる前に、セットアップおよびオンボーディングのサーフェスでPlugin所有の軽量なメタデータが必要な場合は、`setup`を使用します。 +ランタイムのロード前に、セットアップおよびオンボーディング画面で低コストなPlugin所有メタデータが必要な場合は、`setup` を使います。 ```json { @@ -293,32 +289,32 @@ Pluginが共有の`openclaw qa`ルート配下に1つ以上のトランスポー } ``` -トップレベルの`cliBackends`は引き続き有効で、CLI推論バックエンドを記述し続けます。`setup.cliBackends`は、メタデータのみを維持すべきコントロールプレーン／セットアップフロー向けの、セットアップ専用記述子サーフェスです。 +トップレベルの `cliBackends` は引き続き有効で、CLI推論backendを記述し続けます。`setup.cliBackends` は、メタデータ専用であるべきコントロールプレーン/セットアップフロー向けの、セットアップ固有の記述子サーフェスです。 -`setup.providers`と`setup.cliBackends`が存在する場合、それらはセットアップ検出における優先的な記述子ファーストの参照サーフェスになります。記述子が候補Pluginを絞り込むだけで、セットアップにさらに豊富なセットアップ時ランタイムhookが必要な場合は、`requiresRuntime: true`を設定し、フォールバック実行パスとして`setup-api`を維持してください。 +`setup.providers` と `setup.cliBackends` が存在する場合、これらはセットアップ検出における優先的なdescriptor-first lookupサーフェスになります。記述子が候補Pluginの絞り込みだけを行い、それでもセットアップ時により豊富なランタイムhookが必要な場合は、`requiresRuntime: true` を設定し、フォールバック実行パスとして `setup-api` を維持してください。 -セットアップ参照ではPlugin所有の`setup-api`コードを実行できるため、正規化された`setup.providers[].id`および`setup.cliBackends[]`の値は、検出されたPlugin全体で一意でなければなりません。所有関係があいまいな場合は、検出順から勝者を選ぶのではなく、安全側に倒して失敗します。 +セットアップlookupはPlugin所有の `setup-api` コードを実行できるため、正規化された `setup.providers[].id` と `setup.cliBackends[]` の値は、検出されたPlugin全体で一意でなければなりません。所有権が曖昧な場合は、検出順で勝者を選ぶのではなく、クローズドに失敗します。 ### `setup.providers` リファレンス -| フィールド | 必須 | 型 | 意味 | -| ------------- | -------- | ---------- | -------------------------------------------------------------------------------------- | -| `id` | はい | `string` | セットアップまたはオンボーディング中に公開されるprovider idです。正規化されたidは全体で一意に保ってください。 | -| `authMethods` | いいえ | `string[]` | フルランタイムをロードせずにこのproviderがサポートするセットアップ／認証方式idです。 | -| `envVars` | いいえ | `string[]` | 汎用のセットアップ／ステータスサーフェスがPluginランタイムのロード前に確認できるenv varです。 | +| フィールド | 必須 | 型 | 意味 | +| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ | +| `id` | はい | `string` | セットアップまたはオンボーディング中に公開されるprovider IDです。正規化されたIDはグローバルで一意に保ってください。 | +| `authMethods` | いいえ | `string[]` | 完全なランタイムをロードせずにこのproviderがサポートする、セットアップ/認証方式IDです。 | +| `envVars` | いいえ | `string[]` | 汎用のセットアップ/ステータス画面がPluginランタイムのロード前に確認できるenv varです。 | ### `setup` フィールド -| フィールド | 必須 | 型 | 意味 | -| ------------------ | -------- | ---------- | ----------------------------------------------------------------------------------------------------- | -| `providers` | いいえ | `object[]` | セットアップおよびオンボーディング中に公開されるproviderセットアップ記述子です。 | -| `cliBackends` | いいえ | `string[]` | 記述子ファーストのセットアップ参照に使用されるセットアップ時バックエンドidです。正規化されたidは全体で一意に保ってください。 | -| `configMigrations` | いいえ | `string[]` | このPluginのセットアップサーフェスが所有する設定migration idです。 | -| `requiresRuntime` | いいえ | `boolean` | 記述子参照の後もセットアップに`setup-api`の実行が必要かどうかです。 | +| フィールド | 必須 | 型 | 意味 | +| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | +| `providers` | いいえ | `object[]` | セットアップおよびオンボーディング中に公開されるproviderセットアップ記述子です。 | +| `cliBackends` | いいえ | `string[]` | descriptor-firstなセットアップlookupに使われるセットアップ時backend IDです。正規化されたIDはグローバルで一意に保ってください。 | +| `configMigrations` | いいえ | `string[]` | このPluginのセットアップ画面が所有する設定migration IDです。 | +| `requiresRuntime` | いいえ | `boolean` | 記述子lookup後もセットアップに `setup-api` の実行が必要かどうかです。 | ## `uiHints` リファレンス -`uiHints`は、設定フィールド名から小さなレンダリングヒントへのマップです。 +`uiHints` は、設定フィールド名から小さな描画ヒントへのマップです。 ```json { @@ -335,18 +331,18 @@ Pluginが共有の`openclaw qa`ルート配下に1つ以上のトランスポー 各フィールドヒントには以下を含められます。 -| フィールド | 型 | 意味 | -| ------------- | ---------- | ---------------------------------------- | -| `label` | `string` | ユーザー向けのフィールドラベルです。 | -| `help` | `string` | 短い補足テキストです。 | -| `tags` | `string[]` | 任意のUIタグです。 | -| `advanced` | `boolean` | そのフィールドを高度な項目として示します。 | -| `sensitive` | `boolean` | そのフィールドを秘密または機密として示します。 | -| `placeholder` | `string` | フォーム入力用のプレースホルダーテキストです。 | +| フィールド | 型 | 意味 | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | ユーザー向けのフィールドラベルです。 | +| `help` | `string` | 短いヘルパーテキストです。 | +| `tags` | `string[]` | 任意のUIタグです。 | +| `advanced` | `boolean` | このフィールドを高度な項目として示します。 | +| `sensitive` | `boolean` | このフィールドを秘密または機密として示します。 | +| `placeholder` | `string` | フォーム入力用のプレースホルダーテキストです。 | ## `contracts` リファレンス -`contracts`は、OpenClawがPluginランタイムをインポートせずに読み取れる、静的なcapability所有メタデータにのみ使用してください。 +`contracts` は、OpenClawがPluginランタイムをimportせずに読み取れる、静的なcapability ownershipメタデータにのみ使用してください。 ```json { @@ -366,21 +362,21 @@ Pluginが共有の`openclaw qa`ルート配下に1つ以上のトランスポー 各リストは任意です。 -| フィールド | 型 | 意味 | -| -------------------------------- | ---------- | -------------------------------------------------------------------- | -| `speechProviders` | `string[]` | このPluginが所有するspeech provider idです。 | -| `realtimeTranscriptionProviders` | `string[]` | このPluginが所有するrealtime-transcription provider idです。 | -| `realtimeVoiceProviders` | `string[]` | このPluginが所有するrealtime-voice provider idです。 | -| `mediaUnderstandingProviders` | `string[]` | このPluginが所有するmedia-understanding provider idです。 | -| `imageGenerationProviders` | `string[]` | このPluginが所有するimage-generation provider idです。 | -| `videoGenerationProviders` | `string[]` | このPluginが所有するvideo-generation provider idです。 | -| `webFetchProviders` | `string[]` | このPluginが所有するweb-fetch provider idです。 | -| `webSearchProviders` | `string[]` | このPluginが所有するweb-search provider idです。 | -| `tools` | `string[]` | バンドルされたコントラクトチェック用にこのPluginが所有するagent tool名です。 | +| フィールド | 型 | 意味 | +| -------------------------------- | ---------- | -------------------------------------------------------------- | +| `speechProviders` | `string[]` | このPluginが所有するspeech provider IDです。 | +| `realtimeTranscriptionProviders` | `string[]` | このPluginが所有するrealtime-transcription provider IDです。 | +| `realtimeVoiceProviders` | `string[]` | このPluginが所有するrealtime-voice provider IDです。 | +| `mediaUnderstandingProviders` | `string[]` | このPluginが所有するmedia-understanding provider IDです。 | +| `imageGenerationProviders` | `string[]` | このPluginが所有するimage-generation provider IDです。 | +| `videoGenerationProviders` | `string[]` | このPluginが所有するvideo-generation provider IDです。 | +| `webFetchProviders` | `string[]` | このPluginが所有するweb-fetch provider IDです。 | +| `webSearchProviders` | `string[]` | このPluginが所有するweb-search provider IDです。 | +| `tools` | `string[]` | バンドル済み契約チェックのためにこのPluginが所有するagent tool名です。 | ## `channelConfigs` リファレンス -チャネルPluginが、ランタイムがロードされる前に軽量な設定メタデータを必要とする場合は、`channelConfigs`を使用します。 +channel Pluginがランタイムのロード前に低コストな設定メタデータを必要とする場合は、`channelConfigs` を使います。 ```json { @@ -400,26 +396,26 @@ Pluginが共有の`openclaw qa`ルート配下に1つ以上のトランスポー } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Matrix homeserver接続", "preferOver": ["matrix-legacy"] } } } ``` -各チャネルエントリには以下を含められます。 +各channelエントリには以下を含められます。 -| フィールド | 型 | 意味 | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | -| `schema` | `object` | `channels.`用のJSON Schemaです。宣言された各チャネル設定エントリで必須です。 | -| `uiHints` | `Record` | そのチャネル設定セクション向けの任意のUIラベル／プレースホルダー／機密性ヒントです。 | -| `label` | `string` | ランタイムメタデータの準備ができていないときに、ピッカーおよびinspectサーフェスへマージされるチャネルラベルです。 | -| `description` | `string` | inspectおよびcatalogサーフェス向けの短いチャネル説明です。 | -| `preferOver` | `string[]` | 選択サーフェスでこのチャネルが優先して上回るべき、レガシーまたは優先度の低いPlugin idです。 | +| フィールド | 型 | 意味 | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| `schema` | `object` | `channels.` のJSON Schemaです。宣言された各channel設定エントリで必須です。 | +| `uiHints` | `Record` | そのchannel設定セクション向けの任意のUIラベル/プレースホルダー/機密性ヒントです。 | +| `label` | `string` | ランタイムメタデータの準備ができていないときに、ピッカーおよび確認画面へマージされるchannelラベルです。 | +| `description` | `string` | 確認およびカタログ画面向けの短いchannel説明です。 | +| `preferOver` | `string[]` | 選択画面でこのchannelが優先されるべき、レガシーまたは優先度の低いPlugin IDです。 | ## `modelSupport` リファレンス -`gpt-5.4`や`claude-sonnet-4.6`のような省略記法モデルidから、Pluginランタイムがロードされる前にOpenClawがprovider Pluginを推論すべき場合は、`modelSupport`を使用します。 +`gpt-5.4` や `claude-sonnet-4.6` のような短縮モデルIDから、Pluginランタイムのロード前にOpenClawがprovider Pluginを推測すべき場合は、`modelSupport` を使います。 ```json { @@ -432,58 +428,60 @@ Pluginが共有の`openclaw qa`ルート配下に1つ以上のトランスポー OpenClawは次の優先順位を適用します。 -- 明示的な`provider/model`参照では、所有する`providers`マニフェストメタデータを使用します -- `modelPatterns`は`modelPrefixes`より優先されます -- 1つの非バンドルPluginと1つのバンドルPluginの両方が一致する場合は、非バンドルPluginが優先されます -- 残るあいまいさは、ユーザーまたは設定がproviderを指定するまで無視されます +- 明示的な `provider/model` 参照では、所有する `providers` マニフェストメタデータを使用します +- `modelPatterns` は `modelPrefixes` より優先されます +- 1つの非バンドルPluginと1つのバンドル済みPluginの両方が一致する場合、非バンドルPluginが優先されます +- 残る曖昧さは、ユーザーまたは設定がproviderを指定するまで無視されます フィールド: -| フィールド | 型 | 意味 | -| --------------- | ---------- | --------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 省略記法モデルidに対して`startsWith`で一致判定するプレフィックスです。 | -| `modelPatterns` | `string[]` | プロファイル接尾辞を除去した後の省略記法モデルidに対して一致判定する正規表現ソースです。 | +| フィールド | 型 | 意味 | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | 短縮モデルIDに対して `startsWith` で一致させるプレフィックスです。 | +| `modelPatterns` | `string[]` | プロファイルサフィックスを除去した後の短縮モデルIDに対して一致させる正規表現ソースです。 | -レガシーなトップレベルcapabilityキーは非推奨です。`openclaw doctor --fix`を使用して、`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、および`webSearchProviders`を`contracts`配下へ移動してください。通常のマニフェストロードでは、これらのトップレベルフィールドはもはやcapability所有として扱われません。 +レガシーなトップレベルcapabilityキーは非推奨です。`openclaw doctor --fix` を使って、`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` を `contracts` 配下へ移動してください。通常のマニフェスト読み込みでは、これらのトップレベルフィールドはもはやcapability ownershipとして扱われません。 ## マニフェストとpackage.jsonの違い -この2つのファイルは役割が異なります。 +この2つのファイルは異なる役割を持ちます。 -| ファイル | 用途 | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | 検出、設定バリデーション、auth-choiceメタデータ、およびPluginコード実行前に存在している必要があるUIヒント | -| `package.json` | npmメタデータ、依存関係のインストール、およびエントリーポイント、インストール制御、セットアップ、またはcatalogメタデータに使う`openclaw`ブロック | +| ファイル | 用途 | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Pluginコードの実行前に存在している必要がある、検出、設定検証、認証選択メタデータ、およびUIヒント | +| `package.json` | npmメタデータ、依存関係のインストール、およびエントリーポイント、インストール制御、セットアップ、またはカタログメタデータに使われる `openclaw` ブロック | -どこに置くべきメタデータか迷う場合は、次のルールを使ってください。 +どこに置くべきメタデータか迷った場合は、次のルールを使ってください。 -- OpenClawがPluginコードをロードする前に知っている必要があるなら、`openclaw.plugin.json`に置いてください -- パッケージ化、エントリーファイル、またはnpmインストール動作に関するものなら、`package.json`に置いてください +- OpenClawがPluginコードのロード前に知る必要がある場合は、`openclaw.plugin.json` に置きます +- パッケージ化、エントリーファイル、またはnpm installの動作に関するものであれば、`package.json` に置きます -### 検出に影響する`package.json`フィールド +### 検出に影響する `package.json` フィールド -一部の事前ランタイムPluginメタデータは、`openclaw.plugin.json`ではなく、`package.json`内の`openclaw`ブロックに意図的に置かれています。 +一部のランタイム前Pluginメタデータは、`openclaw.plugin.json` ではなく、`package.json` 内の `openclaw` ブロックに意図的に置かれています。 重要な例: -| フィールド | 意味 | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | ネイティブなPluginエントリーポイントを宣言します。 | -| `openclaw.setupEntry` | オンボーディングおよび遅延チャネル起動中に使われる、軽量なセットアップ専用エントリーポイントです。 | -| `openclaw.channel` | ラベル、ドキュメントパス、エイリアス、選択用コピーなどの軽量なチャネルcatalogメタデータです。 | -| `openclaw.channel.configuredState` | フルチャネルランタイムをロードせずに「envのみのセットアップがすでに存在するか？」に答えられる、軽量なconfigured-stateチェッカーメタデータです。 | -| `openclaw.channel.persistedAuthState` | フルチャネルランタイムをロードせずに「すでに何かサインイン済みか？」に答えられる、軽量なpersisted-authチェッカーメタデータです。 | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | バンドルPluginおよび外部公開Plugin向けのインストール／更新ヒントです。 | -| `openclaw.install.defaultChoice` | 複数のインストール元が利用可能な場合の優先インストールパスです。 | -| `openclaw.install.minHostVersion` | `>=2026.3.22`のようなsemver下限で表す、サポートされる最小のOpenClawホストバージョンです。 | -| `openclaw.install.allowInvalidConfigRecovery` | 設定が無効な場合に、限定的なバンドルPlugin再インストール回復パスを許可します。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 起動中、完全なチャネルPluginの前にセットアップ専用のチャネルサーフェスをロードできるようにします。 | +| フィールド | 意味 | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | ネイティブPluginのエントリーポイントを宣言します。 | +| `openclaw.setupEntry` | オンボーディング、遅延channel起動、読み取り専用のchannel status/SecretRef検出で使われる、軽量なセットアップ専用エントリーポイントです。 | +| `openclaw.channel` | ラベル、docs path、エイリアス、選択用コピーなどの軽量なchannelカタログメタデータです。 | +| `openclaw.channel.configuredState` | 「envのみのセットアップがすでに存在するか？」に、完全なchannelランタイムをロードせずに答えられる軽量なconfigured-state checkerメタデータです。 | +| `openclaw.channel.persistedAuthState` | 「すでに何かにサインインしているか？」に、完全なchannelランタイムをロードせずに答えられる軽量なpersisted-auth checkerメタデータです。 | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | バンドル済みおよび外部公開Plugin向けのインストール/更新ヒントです。 | +| `openclaw.install.defaultChoice` | 複数のインストール元が利用可能な場合の優先インストールパスです。 | +| `openclaw.install.minHostVersion` | `>=2026.3.22` のようなsemver下限を使用する、サポートされる最小のOpenClaw hostバージョンです。 | +| `openclaw.install.allowInvalidConfigRecovery` | 設定が無効な場合に、限定的なバンドル済みPlugin再インストール回復パスを許可します。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 起動中に完全なchannel Pluginより前に、セットアップ専用のchannel画面をロードできるようにします。 | -`openclaw.install.minHostVersion`は、インストール時およびマニフェストレジストリのロード時に強制されます。無効な値は拒否されます。新しいが有効な値の場合、古いホストではそのPluginはスキップされます。 +`openclaw.install.minHostVersion` は、インストール中およびマニフェストレジストリ読み込み中に強制されます。無効な値は拒否されます。新しすぎるが有効な値は、古いhostではそのPluginをスキップします。 -`openclaw.install.allowInvalidConfigRecovery`は意図的に限定的です。これによって任意の壊れた設定がインストール可能になるわけではありません。現在は、不足しているバンドルPluginパスや、同じバンドルPluginに対する古い`channels.`エントリなど、特定の古いバンドルPluginアップグレード失敗からインストールフローが回復できるようにするだけです。無関係な設定エラーは引き続きインストールをブロックし、オペレーターは`openclaw doctor --fix`へ案内されます。 +channel Pluginは、status、channel list、またはSecretRefスキャンで完全なランタイムをロードせずに設定済みアカウントを識別する必要がある場合、`openclaw.setupEntry` を提供すべきです。setup entryは、channelメタデータに加えて、セットアップで安全な設定、status、およびsecrets adapterを公開すべきです。ネットワーククライアント、Gatewayリスナー、およびtransport runtimeはメインのextension entrypointに置いてください。 -`openclaw.channel.persistedAuthState`は、小さなチェッカーモジュール用のパッケージメタデータです。 +`openclaw.install.allowInvalidConfigRecovery` は意図的に限定的です。任意の壊れた設定をインストール可能にするものではありません。現時点では、バンドル済みPluginパスの欠落や、その同じバンドル済みPluginに対する古い `channels.` エントリのような、特定の古いバンドル済みPluginアップグレード失敗からのインストールフロー回復のみを許可します。無関係な設定エラーは引き続きインストールをブロックし、運用者に `openclaw doctor --fix` を案内します。 + +`openclaw.channel.persistedAuthState` は、小さなcheckerモジュールのためのpackageメタデータです。 ```json { @@ -499,9 +497,9 @@ OpenClawは次の優先順位を適用します。 } ``` -セットアップ、doctor、またはconfigured-stateフローで、完全なチャネルPluginがロードされる前に、安価なyes/no認証プローブが必要な場合にこれを使用します。対象のexportは、永続化状態のみを読み取る小さな関数であるべきです。完全なチャネルランタイムbarrel経由にはしないでください。 +完全なchannel Pluginのロード前に、setup、doctor、またはconfigured-stateフローが低コストなyes/no認証確認を必要とする場合に使います。対象のexportは、永続化された状態のみを読み取る小さな関数にしてください。完全なchannel runtime barrelを経由させないでください。 -`openclaw.channel.configuredState`も、安価なenvのみのconfiguredチェックに対して同じ形に従います。 +`openclaw.channel.configuredState` も、低コストなenvのみconfiguredチェック向けに同じ形式に従います。 ```json { @@ -517,43 +515,42 @@ OpenClawは次の優先順位を適用します。 } ``` -チャネルが、envまたはその他の小さな非ランタイム入力からconfigured-stateに答えられる場合にこれを使用します。チェックに完全な設定解決または実際のチャネルランタイムが必要なら、そのロジックは代わりにPluginの`config.hasConfiguredState`hookに置いてください。 +channelがenvやその他の小さな非ランタイム入力からconfigured-stateに答えられる場合に使います。チェックに完全な設定解決や実際のchannel runtimeが必要なら、そのロジックは代わりにPluginの `config.hasConfiguredState` hookに置いてください。 ## JSON Schemaの要件 -- **すべてのPluginはJSON Schemaを必ず含める必要があります**。設定を受け付けない場合でも同様です。 -- 空のスキーマでも構いません（たとえば、`{ "type": "object", "additionalProperties": false }`）。 -- スキーマはランタイム時ではなく、設定の読み取り／書き込み時にバリデーションされます。 +- **すべてのPluginはJSON Schemaを必ず含める必要があります**。設定をまったく受け付けない場合でも同様です。 +- 空のスキーマでも受け入れられます（たとえば `{ "type": "object", "additionalProperties": false }`）。 +- スキーマはランタイム時ではなく、設定の読み書き時に検証されます。 -## バリデーション動作 +## 検証の動作 -- 不明な`channels.*`キーは、チャネルidがPluginマニフェストで宣言されていない限り、**エラー**です。 -- `plugins.entries.`、`plugins.allow`、`plugins.deny`、および`plugins.slots.*`は、**検出可能な**Plugin idを参照していなければなりません。不明なidは**エラー**です。 -- Pluginがインストールされていても、マニフェストまたはスキーマが壊れている、または存在しない場合、バリデーションは失敗し、DoctorがPluginエラーを報告します。 -- Plugin設定が存在していても、そのPluginが**無効**である場合、設定は保持され、Doctorとログに**警告**が表示されます。 +- 不明な `channels.*` キーは、channel IDがPluginマニフェストで宣言されていない限り、**エラー**です。 +- `plugins.entries.`、`plugins.allow`、`plugins.deny`、および `plugins.slots.*` は、**検出可能な**Plugin IDを参照していなければなりません。不明なIDは**エラー**です。 +- Pluginがインストールされていても、マニフェストまたはスキーマが壊れているか存在しない場合、検証は失敗し、DoctorがPluginエラーを報告します。 +- Plugin設定が存在していても、そのPluginが**無効**の場合、設定は保持され、Doctorとログで**警告**が表示されます。 -完全な`plugins.*`スキーマについては、[Configuration reference](/ja-JP/gateway/configuration)を参照してください。 +完全な `plugins.*` スキーマについては、[Configuration reference](/ja-JP/gateway/configuration)を参照してください。 -## 注意事項 +## 注意 -- マニフェストは、ローカルファイルシステムからのロードを含め、**ネイティブなOpenClaw Pluginでは必須**です。 -- ランタイムは引き続きPluginモジュールを別個にロードします。マニフェストはあくまで検出とバリデーションのためのものです。 -- ネイティブマニフェストはJSON5で解析されるため、最終的な値がオブジェクトである限り、コメント、末尾カンマ、引用符なしキーを使用できます。 -- マニフェストローダーが読み取るのは、ドキュメント化されたマニフェストフィールドのみです。ここにカスタムのトップレベルキーを追加するのは避けてください。 -- `providerAuthEnvVars`は、認証プローブ、env-markerバリデーション、およびenv名を確認するためだけにPluginランタイムを起動すべきでない類似のprovider認証サーフェス向けの、軽量なメタデータパスです。 -- `providerAuthAliases`により、providerバリアントは、その関係をコアにハードコードすることなく、別のproviderの認証env var、認証プロファイル、設定ベースの認証、およびAPI keyオンボーディング選択肢を再利用できます。 -- `providerEndpoints`により、provider Pluginは単純なendpoint host/baseUrl一致メタデータを所有できます。これはコアがすでにサポートしているendpoint classに対してのみ使用してください。ランタイム動作は引き続きPluginが所有します。 -- `syntheticAuthRefs`は、ランタイムレジストリがまだ存在しない段階のコールドなモデル検出で可視でなければならない、provider所有のsynthetic auth hook向けの軽量なメタデータパスです。ランタイムproviderまたはCLIバックエンドが実際に`resolveSyntheticAuth`を実装している参照だけを列挙してください。 -- `nonSecretAuthMarkers`は、ローカル、OAuth、または環境依存の認証マーカーなど、バンドルされたPlugin所有のプレースホルダーAPI key向けの軽量なメタデータパスです。コアは、所有するproviderをハードコードすることなく、認証表示およびシークレット監査においてこれらを非シークレットとして扱います。 -- `channelEnvVars`は、shell-envフォールバック、セットアッププロンプト、およびenv名を確認するためだけにPluginランタイムを起動すべきでない類似のチャネルサーフェス向けの、軽量なメタデータパスです。 -- `providerAuthChoices`は、providerランタイムがロードされる前のauth-choiceピッカー、`--auth-choice`解決、優先providerマッピング、および単純なオンボーディングCLIフラグ登録向けの軽量なメタデータパスです。providerコードを必要とするランタイムのウィザードメタデータについては、[Provider runtime hooks](/ja-JP/plugins/architecture#provider-runtime-hooks)を参照してください。 -- 排他的なPlugin種別は`plugins.slots.*`を通じて選択されます。 - - `kind: "memory"` は `plugins.slots.memory` で選択されます。 - - `kind: "context-engine"` は `plugins.slots.contextEngine` で選択されます - （デフォルト: 組み込みの`legacy`）。 -- Pluginが必要としない場合、`channels`、`providers`、`cliBackends`、および`skills`は省略できます。 -- Pluginがネイティブモジュールに依存している場合は、ビルド手順と、必要なパッケージマネージャーの許可リスト要件（たとえば、pnpmの`allow-build-scripts` - - `pnpm rebuild `）をドキュメント化してください。 +- マニフェストは、ローカルファイルシステム読み込みを含む**ネイティブなOpenClaw Pluginでは必須**です。 +- ランタイムは引き続きPluginモジュールを個別にロードします。マニフェストは検出と検証のためだけのものです。 +- ネイティブマニフェストはJSON5で解析されるため、最終的な値がオブジェクトである限り、コメント、末尾カンマ、引用符なしキーが許可されます。 +- マニフェストローダーが読み取るのは文書化されたマニフェストフィールドのみです。ここにカスタムのトップレベルキーを追加するのは避けてください。 +- `providerAuthEnvVars` は、認証確認、env-marker検証、およびenv名を確認するためだけにPluginランタイムを起動すべきでない類似のprovider認証画面に向けた、低コストなメタデータパスです。 +- `providerAuthAliases` により、coreにその関係をハードコードせずに、providerバリアントが別のproviderの認証env var、認証プロファイル、設定ベースの認証、およびAPIキーのオンボーディング選択肢を再利用できます。 +- `providerEndpoints` により、provider Pluginが単純なendpoint host/baseUrl一致メタデータを所有できます。coreがすでにサポートしているendpoint classに対してのみ使用してください。ランタイム動作は引き続きPluginが所有します。 +- `syntheticAuthRefs` は、ランタイムレジストリが存在する前のコールドモデル検出で可視である必要がある、provider所有のsynthetic auth hook向けの低コストなメタデータパスです。ランタイムproviderまたはCLI backendが実際に `resolveSyntheticAuth` を実装している参照のみを列挙してください。 +- `nonSecretAuthMarkers` は、ローカル、OAuth、またはアンビエント認証情報マーカーのような、バンドル済みPlugin所有のプレースホルダーAPIキー向けの低コストなメタデータパスです。coreは、所有providerをハードコードせずに、認証表示およびシークレット監査でこれらを非シークレットとして扱います。 +- `channelEnvVars` は、シェルenvフォールバック、セットアッププロンプト、およびenv名を確認するためだけにPluginランタイムを起動すべきでない類似のchannel画面に向けた、低コストなメタデータパスです。 +- `providerAuthChoices` は、認証選択ピッカー、`--auth-choice` 解決、優先providerマッピング、およびproviderランタイムのロード前の単純なオンボーディングCLIフラグ登録に向けた、低コストなメタデータパスです。providerコードを必要とするランタイムのウィザードメタデータについては、[Provider runtime hooks](/ja-JP/plugins/architecture#provider-runtime-hooks)を参照してください。 +- 排他的なPlugin種別は `plugins.slots.*` を通じて選択されます。 + - `kind: "memory"` は `plugins.slots.memory` によって選択されます。 + - `kind: "context-engine"` は `plugins.slots.contextEngine` によって選択されます（デフォルト: 組み込みの `legacy`）。 +- Pluginが必要としない場合、`channels`、`providers`、`cliBackends`、および `skills` は省略できます。 +- Pluginがネイティブモジュールに依存する場合は、ビルド手順と、必要なパッケージマネージャーの許可リスト要件を文書化してください（たとえば、pnpmの `allow-build-scripts` + - `pnpm rebuild `）。 ## 関連 diff --git a/docs/ja-JP/plugins/sdk-channel-plugins.md b/docs/ja-JP/plugins/sdk-channel-plugins.md index 6a78748ad..06fc2b8e7 100644 --- a/docs/ja-JP/plugins/sdk-channel-plugins.md +++ b/docs/ja-JP/plugins/sdk-channel-plugins.md @@ -1,85 +1,88 @@ --- read_when: - 新しいメッセージングチャネルPluginを構築しています - - OpenClawをメッセージングプラットフォームに接続したいです - - ChannelPluginアダプタ画面を理解する必要があります + - OpenClawをメッセージングプラットフォームに接続したいと考えています + - ChannelPluginアダプターのインターフェースを理解する必要があります sidebarTitle: Channel Plugins summary: OpenClaw向けメッセージングチャネルPluginを構築するためのステップバイステップガイド title: チャネルPluginの構築 x-i18n: - generated_at: "2026-04-21T04:48:46Z" + generated_at: "2026-04-21T19:20:38Z" model: gpt-5.4 provider: openai - source_hash: 569394aeefa0231ae3157a13406f91c97fe7eeff2b62df0d35a893f1ad4d5d05 + source_hash: 35cae55c13b69f2219bd2f9bd3ee2f7d8c4075bd87f0be11c35a0fddb070fe1e source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # チャネルPluginの構築 -このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャネルPluginの構築方法を順を追って説明します。最後には、DMセキュリティ、ペアリング、返信スレッド、送信メッセージングを備えた動作するチャネルが完成します。 +このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャネルpluginの構築手順を説明します。完了する頃には、DMセキュリティ、ペアリング、返信スレッド化、送信メッセージングを備えた動作するチャネルが完成しています。 - まだOpenClaw Pluginを一度も作成したことがない場合は、まず [Getting Started](/ja-JP/plugins/building-plugins) を読んで、基本的なパッケージ構造とマニフェスト設定を確認してください。 + まだOpenClaw pluginを一度も作成したことがない場合は、基本的なパッケージ構造とマニフェスト設定について先に + [はじめに](/ja-JP/plugins/building-plugins) + を読んでください。 -## チャネルPluginの仕組み +## チャネルpluginの仕組み -チャネルPluginには、独自の送信/編集/リアクションツールは不要です。OpenClawは、コアに1つの共有 `message` ツールを保持します。あなたのPluginが所有するのは次の要素です。 +チャネルpluginには、独自の送信・編集・リアクション用ツールは必要ありません。OpenClawは、コア内で共有の `message` ツールを1つ維持します。pluginが担うのは次の要素です。 - **設定** — アカウント解決とセットアップウィザード - **セキュリティ** — DMポリシーと許可リスト - **ペアリング** — DM承認フロー -- **セッショングラマー** — プロバイダ固有の会話IDが、どのようにベースチャット、スレッドID、親フォールバックに対応付けられるか -- **送信** — プラットフォームへのテキスト、メディア、投票の送信 +- **セッショングラマー** — プロバイダー固有の会話IDを、ベースチャット、スレッドID、親フォールバックへどのようにマッピングするか +- **送信** — テキスト、メディア、投票をプラットフォームへ送信する処理 - **スレッド化** — 返信をどのようにスレッド化するか -コアは、共有messageツール、プロンプト配線、外側のセッションキー形状、汎用 `:thread:` 管理、およびディスパッチを所有します。 +コアは、共有メッセージツール、プロンプト配線、外側のセッションキー形状、汎用的な `:thread:` の管理、およびディスパッチを担います。 -チャネルがメディアソースを運ぶmessage-toolパラメータを追加する場合は、それらのパラメータ名を `describeMessageTool(...).mediaSourceParams` で公開してください。コアはこの明示的な一覧を、サンドボックスパス正規化と送信メディアアクセスポリシーに使用するため、Plugin側でプロバイダ固有のアバター、添付ファイル、カバー画像パラメータに対する共有コアの特別扱いは不要です。 -`{ "set-profile": ["avatarUrl", "avatarPath"] }` のようなアクションキー付きマップを返すことを推奨します。これにより、無関係なアクションが他のアクションのメディア引数を引き継がずに済みます。意図的にすべての公開アクションで共有されるパラメータについては、フラットな配列でも引き続き動作します。 +チャネルが、メディアソースを運ぶメッセージツールのパラメータを追加する場合は、それらのパラメータ名を `describeMessageTool(...).mediaSourceParams` を通じて公開してください。コアは、その明示的な一覧をサンドボックスのパス正規化および送信メディアアクセスポリシーに使用するため、plugin側でプロバイダー固有のアバター、添付ファイル、またはカバー画像パラメータのために共有コアの特別扱いを追加する必要はありません。 +`{ "set-profile": ["avatarUrl", "avatarPath"] }` のようなアクションキー付きマップを返すことを推奨します。これにより、無関係なアクションが別のアクションのメディア引数を継承しません。意図的に公開されるすべてのアクション間で共有されるパラメータについては、フラットな配列でも機能します。 -プラットフォームが会話IDの内部に追加スコープを保存している場合、その解析はPlugin内の `messaging.resolveSessionConversation(...)` に保持してください。これは、`rawId` をベース会話ID、任意のスレッドID、明示的な `baseConversationId`、および任意の `parentConversationCandidates` に対応付けるための正規フックです。`parentConversationCandidates` を返す場合は、最も狭い親から最も広い/ベース会話の順に並べてください。 +プラットフォームが会話ID内に追加のスコープを保存する場合は、その解析をplugin内の `messaging.resolveSessionConversation(...)` に保持してください。これは、`rawId` をベース会話ID、任意のスレッドID、明示的な `baseConversationId`、および任意の `parentConversationCandidates` にマッピングするための正規フックです。 +`parentConversationCandidates` を返す場合は、最も狭い親から最も広い親／ベース会話の順に並べてください。 -チャネルレジストリ起動前にも同じ解析が必要なバンドル版Pluginは、一致する `resolveSessionConversation(...)` エクスポートを持つトップレベルの `session-key-api.ts` ファイルを公開することもできます。コアは、実行時Pluginレジストリがまだ利用できないときだけ、このブートストラップ安全な画面を使います。 +チャネルレジストリの起動前に同じ解析が必要な同梱pluginは、一致する `resolveSessionConversation(...)` エクスポートを持つトップレベルの `session-key-api.ts` ファイルを公開することもできます。コアは、このブートストラップ安全なインターフェースを、ランタイムpluginレジストリがまだ利用できない場合にのみ使用します。 -`messaging.resolveParentConversationCandidates(...)` は、Pluginが汎用/raw idの上に親フォールバックだけを必要とする場合の、レガシー互換フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず `resolveSessionConversation(...).parentConversationCandidates` を使い、その正規フックがそれらを省略したときだけ `resolveParentConversationCandidates(...)` にフォールバックします。 +`messaging.resolveParentConversationCandidates(...)` は、pluginが汎用／生のIDの上に親フォールバックだけを必要とする場合の、レガシー互換フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず `resolveSessionConversation(...).parentConversationCandidates` を使い、その正規フックがそれらを省略した場合にのみ `resolveParentConversationCandidates(...)` にフォールバックします。 -## 承認とチャネルcapability +## 承認とチャネル機能 -ほとんどのチャネルPluginでは、承認固有のコードは不要です。 +ほとんどのチャネルpluginでは、承認専用のコードは必要ありません。 -- コアは、同一チャット内の `/approve`、共有承認ボタンペイロード、および汎用フォールバック配信を所有します。 -- チャネルが承認固有の動作を必要とする場合は、チャネルPlugin上に1つの `approvalCapability` オブジェクトを置くことを推奨します。 -- `ChannelPlugin.approvals` は削除されました。承認の配信/ネイティブ/描画/認証に関する情報は `approvalCapability` に置いてください。 -- `plugin.auth` はログイン/ログアウト専用です。コアはそのオブジェクトから承認認証フックをもう読み取りません。 -- `approvalCapability.authorizeActorAction` と `approvalCapability.getActionAvailabilityState` が正規の承認認証境界です。 -- 同一チャット承認認証の可用性には `approvalCapability.getActionAvailabilityState` を使ってください。 -- チャネルがネイティブexec承認を公開する場合は、起点画面/ネイティブクライアント状態が同一チャット承認認証と異なるときに `approvalCapability.getExecInitiatingSurfaceState` を使ってください。コアはこのexec専用フックを使って `enabled` と `disabled` を区別し、起点チャネルがネイティブexec承認をサポートするかを判断し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)` は一般的なケースでこれを補います。 -- 重複するローカル承認プロンプトの非表示や、配信前のtyping indicator送信など、チャネル固有のペイロードライフサイクル動作には `outbound.shouldSuppressLocalPayloadPrompt` または `outbound.beforeDeliverPayload` を使ってください。 -- `approvalCapability.delivery` はネイティブ承認ルーティングまたはフォールバック抑制にのみ使ってください。 -- チャネル所有のネイティブ承認情報には `approvalCapability.nativeRuntime` を使ってください。ホットなチャネルエントリポイントでは、`createLazyChannelApprovalNativeRuntimeAdapter(...)` によってこれを遅延化し、必要時に実行時モジュールをimportできるようにしつつ、コアが承認ライフサイクルを組み立てられるようにしてください。 -- `approvalCapability.render` は、チャネルが共有レンダラの代わりに本当にカスタム承認ペイロードを必要とする場合にのみ使ってください。 -- チャネルが無効時レスポンスで、ネイティブexec承認を有効にするために必要な正確な設定ノブを説明したい場合は、`approvalCapability.describeExecApprovalSetup` を使ってください。このフックは `{ channel, channelLabel, accountId }` を受け取ります。名前付きアカウントのチャネルでは、トップレベルデフォルトではなく `channels..accounts..execApprovals.*` のようなアカウントスコープ付きパスを描画してください。 -- チャネルが既存設定から安定した所有者風DMアイデンティティを推測できる場合は、承認固有のコアロジックを追加せずに同一チャット `/approve` を制限するために `openclaw/plugin-sdk/approval-runtime` の `createResolvedApproverActionAuthAdapter` を使ってください。 -- チャネルがネイティブ承認配信を必要とする場合は、チャネルコードはターゲット正規化とトランスポート/提示情報に集中させてください。`openclaw/plugin-sdk/approval-runtime` の `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability` を使ってください。チャネル固有の情報は `approvalCapability.nativeRuntime` の背後に置き、理想的には `createChannelApprovalNativeRuntimeAdapter(...)` または `createLazyChannelApprovalNativeRuntimeAdapter(...)` を通して置いてください。そうすることで、コアがハンドラを組み立て、リクエストフィルタリング、ルーティング、重複排除、期限管理、Gateway購読、および別経路配信通知を所有できます。`nativeRuntime` はいくつかの小さな境界に分割されています: +- コアは、同一チャット内の `/approve`、共有承認ボタンペイロード、および汎用フォールバック配信を担います。 +- チャネルが承認固有の動作を必要とする場合は、チャネルplugin上に1つの `approvalCapability` オブジェクトを置くことを推奨します。 +- `ChannelPlugin.approvals` は削除されました。承認配信、ネイティブ、レンダリング、認可に関する情報は `approvalCapability` に置いてください。 +- `plugin.auth` はログイン／ログアウト専用です。コアは、そのオブジェクトから承認認可フックをもう読み取りません。 +- `approvalCapability.authorizeActorAction` と `approvalCapability.getActionAvailabilityState` が、正規の承認認可インターフェースです。 +- 同一チャット承認の認可可用性には `approvalCapability.getActionAvailabilityState` を使用してください。 +- チャネルがネイティブexec承認を公開する場合は、開始サーフェス／ネイティブクライアント状態が同一チャット承認認可と異なるときに `approvalCapability.getExecInitiatingSurfaceState` を使用してください。コアはこのexec専用フックを使って `enabled` と `disabled` を区別し、開始チャネルがネイティブexec承認をサポートしているか判断し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)` は一般的なケースでこれを補います。 +- 重複するローカル承認プロンプトの非表示や、配信前の入力中インジケーター送信など、チャネル固有のペイロードライフサイクル動作には `outbound.shouldSuppressLocalPayloadPrompt` または `outbound.beforeDeliverPayload` を使用してください。 +- `approvalCapability.delivery` は、ネイティブ承認ルーティングまたはフォールバック抑止にのみ使用してください。 +- チャネル所有のネイティブ承認情報には `approvalCapability.nativeRuntime` を使用してください。ホットなチャネルエントリーポイントでは、`createLazyChannelApprovalNativeRuntimeAdapter(...)` を使ってこれを遅延化してください。これにより、コアが承認ライフサイクルを組み立てられる状態を維持しつつ、必要時にランタイムモジュールをインポートできます。 +- チャネルが共有レンダラーではなく、本当にカスタム承認ペイロードを必要とする場合にのみ `approvalCapability.render` を使用してください。 +- チャネルが、無効化パスの返信でネイティブexec承認を有効化するために必要な正確な設定項目を説明したい場合は、`approvalCapability.describeExecApprovalSetup` を使用してください。このフックは `{ channel, channelLabel, accountId }` を受け取ります。名前付きアカウントチャネルでは、トップレベルのデフォルトではなく `channels..accounts..execApprovals.*` のようなアカウントスコープ付きパスを表示する必要があります。 +- 既存設定から安定したオーナー類似DMアイデンティティを推測できるチャネルでは、承認専用のコアロジックを追加せずに同一チャット `/approve` を制限するために、`openclaw/plugin-sdk/approval-runtime` の `createResolvedApproverActionAuthAdapter` を使用してください。 +- チャネルがネイティブ承認配信を必要とする場合、チャネルコードはターゲット正規化と転送／表示情報に集中させてください。`openclaw/plugin-sdk/approval-runtime` の `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、および `createApproverRestrictedNativeApprovalCapability` を使用してください。チャネル固有の情報は `approvalCapability.nativeRuntime` の背後に置き、理想的には `createChannelApprovalNativeRuntimeAdapter(...)` または `createLazyChannelApprovalNativeRuntimeAdapter(...)` を通してください。これによりコアがハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、有効期限、Gateway購読、および「別の場所へルーティングされた」通知を担えます。`nativeRuntime` はいくつかの小さなインターフェースに分割されています。 - `availability` — アカウントが設定済みか、およびリクエストを処理すべきか -- `presentation` — 共有承認ビューモデルを保留/解決済み/期限切れのネイティブペイロードまたは最終アクションに対応付ける -- `transport` — ターゲットを準備し、ネイティブ承認メッセージを送信/更新/削除する -- `interactions` — ネイティブボタンまたはリアクション向けの任意のbind/unbind/clear-actionフック +- `presentation` — 共有承認ビューモデルを、保留中／解決済み／期限切れのネイティブペイロードまたは最終アクションへマッピングする +- `transport` — ターゲットを準備し、ネイティブ承認メッセージを送信／更新／削除する +- `interactions` — ネイティブボタンやリアクションのための任意のバインド／アンバインド／アクションクリアフック - `observe` — 任意の配信診断フック -- チャネルがクライアント、トークン、Boltアプリ、Webhook受信器などの実行時所有オブジェクトを必要とする場合は、`openclaw/plugin-sdk/channel-runtime-context` を通して登録してください。汎用runtime-contextレジストリにより、コアは承認固有のラッパーコードを追加せずに、チャネル起動状態からcapability駆動ハンドラをブートストラップできます。 -- capability駆動の境界だけではまだ十分に表現できない場合にのみ、より低レベルの `createChannelApprovalHandler` または `createChannelNativeApprovalRuntime` を使ってください。 -- ネイティブ承認チャネルでは、`accountId` と `approvalKind` の両方をそれらのヘルパー経由でルーティングする必要があります。`accountId` はマルチアカウント承認ポリシーを正しいボットアカウントにスコープし、`approvalKind` はコア内にハードコード分岐を作らずに、execとPlugin承認の動作をチャネル側で利用可能に保ちます。 -- コアは現在、承認の再ルーティング通知も所有します。チャネルPluginは、`createChannelNativeApprovalRuntime` から「承認はDM/別チャネルへ送られました」という独自の追跡メッセージを送るべきではありません。代わりに、共有承認capabilityヘルパーを通して正確な起点 + 承認者DMルーティングを公開し、起点チャットへ通知を返す前にコアが実際の配信を集約するようにしてください。 -- 配信された承認IDの種類をエンドツーエンドで保持してください。ネイティブクライアントは、チャネルローカル状態からexecかPluginかの承認ルーティングを推測または書き換えてはいけません。 -- 異なる承認種類は、意図的に異なるネイティブ画面を公開してよいものです。 - 現在のバンドル例: - - Slackは、execとPluginの両方のIDについてネイティブ承認ルーティングを利用可能に保ちます。 - - Matrixは、execとPlugin承認の間で認証が異なることを許しつつも、同じネイティブDM/チャネルルーティングとリアクションUXを維持します。 -- `createApproverRestrictedNativeApprovalAdapter` は互換ラッパーとしてまだ存在しますが、新しいコードではcapability builderを優先し、Plugin上で `approvalCapability` を公開してください。 +- チャネルがクライアント、トークン、Boltアプリ、またはWebhookレシーバーのようなランタイム所有オブジェクトを必要とする場合は、`openclaw/plugin-sdk/channel-runtime-context` を通じて登録してください。汎用ランタイムコンテキストレジストリにより、コアは承認専用のラッパー接着コードを追加せずに、チャネル起動状態から機能駆動ハンドラーをブートストラップできます。 +- より低レベルの `createChannelApprovalHandler` または `createChannelNativeApprovalRuntime` を使うのは、機能駆動インターフェースでまだ十分に表現できない場合だけにしてください。 +- ネイティブ承認チャネルでは、これらのヘルパーを通じて `accountId` と `approvalKind` の両方をルーティングする必要があります。`accountId` は複数アカウントの承認ポリシーを正しいボットアカウントにスコープし、`approvalKind` はコア内のハードコード分岐なしで、execとplugin承認の動作をチャネルで利用可能に保ちます。 +- コアは現在、承認の再ルーティング通知も担います。チャネルpluginは、`createChannelNativeApprovalRuntime` から「承認はDM／別のチャネルに送られました」という独自のフォローアップメッセージを送信すべきではありません。代わりに、共有承認機能ヘルパーを通じて正確な送信元 + 承認者DMルーティングを公開し、開始チャットへ通知を返す前に、コアが実際の配信を集約できるようにしてください。 +- 配信された承認ID種別をエンドツーエンドで保持してください。ネイティブクライアントは、チャネルローカル状態からexecとplugin承認のルーティングを推測したり書き換えたりしてはいけません。 +- 異なる承認種別が、意図的に異なるネイティブサーフェスを公開することがあります。 + 現在の同梱例: + - Slack は、exec IDとplugin IDの両方に対してネイティブ承認ルーティングを利用可能に保ちます。 + - Matrix は、execとplugin承認の両方で同じネイティブDM／チャネルルーティングとリアクションUXを維持しつつ、承認種別ごとに認可を分けられるようにしています。 +- `createApproverRestrictedNativeApprovalAdapter` は互換ラッパーとして引き続き存在しますが、新しいコードでは機能ビルダーを優先し、plugin上で `approvalCapability` を公開してください。 -ホットなチャネルエントリポイントでは、そのファミリーの一部だけが必要な場合、より狭い実行時サブパスを優先してください。 +ホットなチャネルエントリーポイントでは、このファミリーの一部だけが必要な場合、より狭いランタイムサブパスを優先してください。 - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -91,53 +94,83 @@ x-i18n: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -同様に、より広い包括画面が不要な場合は、`openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/reply-runtime`、`openclaw/plugin-sdk/reply-dispatch-runtime`、`openclaw/plugin-sdk/reply-reference`、`openclaw/plugin-sdk/reply-chunking` を優先してください。 +同様に、より広い包括インターフェースが不要な場合は、 +`openclaw/plugin-sdk/setup-runtime`、 +`openclaw/plugin-sdk/setup-adapter-runtime`、 +`openclaw/plugin-sdk/reply-runtime`、 +`openclaw/plugin-sdk/reply-dispatch-runtime`、 +`openclaw/plugin-sdk/reply-reference`、 +`openclaw/plugin-sdk/reply-chunking` +を優先してください。 -セットアップについて特に言うと: +セットアップに関しては特に次のとおりです。 -- `openclaw/plugin-sdk/setup-runtime` は、実行時安全なセットアップヘルパーを扱います: - import安全なセットアップパッチアダプタ（`createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`）、lookup-note出力、`promptResolvedAllowFrom`、`splitSetupEntries`、および委譲セットアッププロキシbuilder -- `openclaw/plugin-sdk/setup-adapter-runtime` は、`createEnvPatchedAccountSetupAdapter` 向けの狭い環境変数対応アダプタ境界です -- `openclaw/plugin-sdk/channel-setup` は、任意インストールのセットアップbuilderに加え、いくつかのセットアップ安全な基本要素を扱います: +- `openclaw/plugin-sdk/setup-runtime` は、ランタイム安全なセットアップヘルパーを扱います: + import-safeなセットアップパッチアダプター（`createPatchedAccountSetupAdapter`、 + `createEnvPatchedAccountSetupAdapter`、 + `createSetupInputPresenceValidator`）、lookup-note出力、 + `promptResolvedAllowFrom`、`splitSetupEntries`、および委譲セットアッププロキシビルダー +- `openclaw/plugin-sdk/setup-adapter-runtime` は、`createEnvPatchedAccountSetupAdapter` のための、より狭いenv対応アダプターインターフェースです +- `openclaw/plugin-sdk/channel-setup` は、任意インストール用セットアップビルダーと、いくつかのセットアップ安全な基本要素を扱います: `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、 -チャネルが環境変数駆動セットアップまたは認証をサポートし、汎用起動/設定フローが実行時ロード前にそれらの環境変数名を知る必要がある場合は、Pluginマニフェスト内で `channelEnvVars` として宣言してください。チャネル実行時の `envVars` またはローカル定数は、オペレータ向けコピー専用にしてください。 -`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、および `splitSetupEntries` +チャネルがenv駆動のセットアップまたは認証をサポートし、汎用の起動／設定フローがランタイム読み込み前にそれらのenv名を知る必要がある場合は、pluginマニフェストで `channelEnvVars` として宣言してください。チャネルランタイムの `envVars` やローカル定数は、運用者向けコピー専用にしてください。 -- より重い共有セットアップ/設定ヘルパー、たとえば `moveSingleAccountChannelSectionToDefaultAccount(...)` も必要な場合にのみ、より広い `openclaw/plugin-sdk/setup` 境界を使ってください +チャネルが、pluginランタイムの開始前に `status`、`channels list`、`channels status`、またはSecretRefスキャンに現れる可能性がある場合は、`package.json` に `openclaw.setupEntry` を追加してください。そのエントリーポイントは、読み取り専用コマンドパスで安全にimportできる必要があり、それらの要約に必要なチャネルメタデータ、セットアップ安全な設定アダプター、ステータスアダプター、およびチャネルシークレットターゲットメタデータを返す必要があります。セットアップエントリーからクライアント、リスナー、または転送ランタイムを起動してはいけません。 -チャネルがセットアップ画面で「まずこのPluginをインストールしてください」と告知したいだけなら、`createOptionalChannelSetupSurface(...)` を優先してください。生成されるadapter/wizardは設定書き込みと最終化でfail closedし、検証、finalize、ドキュメントリンク文言の間で同じインストール必須メッセージを再利用します。 +`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、 +`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、および +`splitSetupEntries` -他のホットなチャネル経路でも、より広いレガシー画面より狭いヘルパーを優先してください。 +- より重い共有セットアップ／設定ヘルパー、たとえば + `moveSingleAccountChannelSectionToDefaultAccount(...)` + も必要な場合にのみ、より広い `openclaw/plugin-sdk/setup` インターフェースを使用してください -- マルチアカウント設定とデフォルトアカウントフォールバックには `openclaw/plugin-sdk/account-core`、`openclaw/plugin-sdk/account-id`、`openclaw/plugin-sdk/account-resolution`、`openclaw/plugin-sdk/account-helpers` -- 受信ルート/エンベロープとrecord-and-dispatch配線には `openclaw/plugin-sdk/inbound-envelope` と `openclaw/plugin-sdk/inbound-reply-dispatch` -- ターゲット解析/照合には `openclaw/plugin-sdk/messaging-targets` -- メディア読み込みと送信アイデンティティ/送信デリゲート、およびペイロード計画には `openclaw/plugin-sdk/outbound-media` と `openclaw/plugin-sdk/outbound-runtime` -- スレッドbindingライフサイクルとadapter登録には `openclaw/plugin-sdk/thread-bindings-runtime` -- レガシーなagent/mediaペイロード項目レイアウトがまだ必要な場合にのみ `openclaw/plugin-sdk/agent-media-payload` -- Telegramカスタムコマンド正規化、重複/競合検証、およびフォールバック安定コマンド設定契約には `openclaw/plugin-sdk/telegram-command-config` +チャネルがセットアップ画面で「まずこのpluginをインストールしてください」と案内したいだけであれば、`createOptionalChannelSetupSurface(...)` を優先してください。生成されるアダプター／ウィザードは設定書き込みと最終確定で安全側に失敗し、検証、最終確定、ドキュメントリンク文言で同じ「インストールが必要」メッセージを再利用します。 -認証専用チャネルは通常、デフォルト経路で十分です。コアが承認を処理し、Pluginは送信/認証capabilityを公開するだけです。Matrix、Slack、Telegram、カスタムチャットトランスポートのようなネイティブ承認チャネルでは、独自の承認ライフサイクルを実装するのではなく、共有ネイティブヘルパーを使ってください。 +その他のホットなチャネルパスでも、より広いレガシーインターフェースより、狭いヘルパーを優先してください: + +- 複数アカウント設定とデフォルトアカウントフォールバックには + `openclaw/plugin-sdk/account-core`、 + `openclaw/plugin-sdk/account-id`、 + `openclaw/plugin-sdk/account-resolution`、 + `openclaw/plugin-sdk/account-helpers` +- 受信ルート／エンベロープおよび記録・ディスパッチ配線には + `openclaw/plugin-sdk/inbound-envelope` と + `openclaw/plugin-sdk/inbound-reply-dispatch` +- ターゲット解析／一致判定には `openclaw/plugin-sdk/messaging-targets` +- メディア読み込みと送信アイデンティティ／送信デリゲートおよびペイロード計画には + `openclaw/plugin-sdk/outbound-media` と + `openclaw/plugin-sdk/outbound-runtime` +- スレッドバインディングのライフサイクルとアダプター登録には + `openclaw/plugin-sdk/thread-bindings-runtime` +- レガシーなエージェント／メディアペイロードのフィールドレイアウトが依然として必要な場合にのみ + `openclaw/plugin-sdk/agent-media-payload` +- Telegramカスタムコマンドの正規化、重複／競合検証、およびフォールバック時にも安定したコマンド設定契約には + `openclaw/plugin-sdk/telegram-command-config` + +認証のみのチャネルは通常、デフォルトパスで十分です。コアが承認を処理し、pluginは送信／認証機能を公開するだけです。Matrix、Slack、Telegram、およびカスタムチャット転送のようなネイティブ承認チャネルは、独自に承認ライフサイクルを実装するのではなく、共有ネイティブヘルパーを使用してください。 ## 受信メンションポリシー -受信メンション処理は、次の2層に分けてください。 +受信メンション処理は、次の2層に分けて維持してください。 -- Plugin所有の証拠収集 +- pluginが担う証拠収集 - 共有ポリシー評価 -メンションポリシーの判定には `openclaw/plugin-sdk/channel-mention-gating` を使ってください。より広い受信ヘルパーバレルが必要な場合だけ `openclaw/plugin-sdk/channel-inbound` を使ってください。 +メンションポリシーの判定には `openclaw/plugin-sdk/channel-mention-gating` を使用してください。 +より広い受信ヘルパーバレルが必要な場合にのみ +`openclaw/plugin-sdk/channel-inbound` を使用してください。 -Pluginローカルロジックに適したもの: +pluginローカルロジックに適しているもの: -- ボット宛て返信の検出 -- ボット引用の検出 -- スレッド参加チェック -- サービス/システムメッセージの除外 -- ボット参加を証明するために必要なプラットフォームネイティブキャッシュ +- botへの返信の検出 +- botを引用したメッセージの検出 +- スレッド参加の確認 +- サービス／システムメッセージの除外 +- bot参加を証明するために必要なプラットフォームネイティブキャッシュ -共有ヘルパーに適したもの: +共有ヘルパーに適しているもの: - `requireMention` - 明示的メンション結果 @@ -147,9 +180,9 @@ Pluginローカルロジックに適したもの: 推奨フロー: -1. ローカルのメンション情報を計算する。 -2. その情報を `resolveInboundMentionDecision({ facts, policy })` に渡す。 -3. 受信ゲートで `decision.effectiveWasMentioned`、`decision.shouldBypassMention`、`decision.shouldSkip` を使う。 +1. ローカルのメンション情報を計算します。 +2. その情報を `resolveInboundMentionDecision({ facts, policy })` に渡します。 +3. 受信ゲートでは `decision.effectiveWasMentioned`、`decision.shouldBypassMention`、`decision.shouldSkip` を使用します。 ```typescript import { @@ -188,7 +221,7 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` は、すでに実行時注入に依存しているバンドル版チャネルPlugin向けに、同じ共有メンションヘルパーを公開します。 +`api.runtime.channel.mentions` は、すでにランタイム注入に依存している同梱チャネルplugin向けに、同じ共有メンションヘルパーを公開します。 - `buildMentionRegexes` - `matchesMentionPatterns` @@ -196,16 +229,25 @@ if (decision.shouldSkip) return; - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -`implicitMentionKindWhen` と `resolveInboundMentionDecision` だけが必要な場合は、無関係な受信実行時ヘルパーを読み込まないように、`openclaw/plugin-sdk/channel-mention-gating` からimportしてください。 +`implicitMentionKindWhen` と +`resolveInboundMentionDecision` だけが必要な場合は、 +無関係な受信ランタイムヘルパーの読み込みを避けるため、 +`openclaw/plugin-sdk/channel-mention-gating` からimportしてください。 -古い `resolveMentionGating*` ヘルパーは、`openclaw/plugin-sdk/channel-inbound` 上に互換エクスポートとしてのみ残っています。新しいコードでは `resolveInboundMentionDecision({ facts, policy })` を使ってください。 +古い `resolveMentionGating*` ヘルパーは、 +互換エクスポートとしてのみ +`openclaw/plugin-sdk/channel-inbound` に残されています。新しいコードでは +`resolveInboundMentionDecision({ facts, policy })` を使用してください。 -## 手順 +## ウォークスルー - 標準のPluginファイルを作成します。`package.json` 内の `channel` フィールドが、これをチャネルPluginにします。完全なパッケージメタデータ画面については、[Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel) を参照してください。 + 標準的なpluginファイルを作成します。`package.json` の `channel` フィールドが、 + これをチャネルpluginとして成立させます。完全なパッケージメタデータのインターフェースについては、 + [Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel) + を参照してください。 ```json package.json @@ -219,7 +261,7 @@ if (decision.shouldSkip) return; "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "OpenClawをAcme Chatに接続します。" + "blurb": "Connect OpenClaw to Acme Chat." } } } @@ -231,7 +273,7 @@ if (decision.shouldSkip) return; "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Acme ChatチャネルPlugin", + "description": "Acme Chat channel plugin", "configSchema": { "type": "object", "additionalProperties": false, @@ -254,8 +296,9 @@ if (decision.shouldSkip) return; - - `ChannelPlugin` インターフェースには、多くの任意adapter画面があります。最小構成の `id` と `setup` から始め、必要に応じてadapterを追加してください。 + + `ChannelPlugin` インターフェースには、多数の任意アダプターインターフェースがあります。まず + 最小構成である `id` と `setup` から始め、必要に応じてアダプターを追加してください。 `src/channel.ts` を作成します: @@ -265,7 +308,7 @@ if (decision.shouldSkip) return; createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // あなたのプラットフォームAPIクライアント + import { acmeChatApi } from "./client.js"; // your platform API client type ResolvedAccount = { accountId: string | null; @@ -306,7 +349,7 @@ if (decision.shouldSkip) return; }, }), - // DM security: 誰がボットにメッセージできるか + // DM security: who can message the bot security: { dm: { channelKey: "acme-chat", @@ -316,7 +359,7 @@ if (decision.shouldSkip) return; }, }, - // Pairing: 新しいDM連絡先の承認フロー + // Pairing: approval flow for new DM contacts pairing: { text: { idLabel: "Acme Chat username", @@ -327,10 +370,10 @@ if (decision.shouldSkip) return; }, }, - // Threading: 返信をどう配信するか + // Threading: how replies are delivered threading: { topLevelReplyToMode: "reply" }, - // Outbound: プラットフォームへメッセージを送る + // Outbound: send messages to the platform outbound: { attachedResults: { sendText: async (params) => { @@ -350,22 +393,24 @@ if (decision.shouldSkip) return; }); ``` - - 低レベルadapterインターフェースを手動実装する代わりに、宣言的オプションを渡すと、builderがそれらを組み立てます。 + + 低レベルのアダプターインターフェースを手作業で実装する代わりに、 + 宣言的なオプションを渡すと、ビルダーがそれらを組み合わせます。 | オプション | 配線される内容 | | --- | --- | - | `security.dm` | 設定項目からのスコープ付きDMセキュリティリゾルバ | - | `pairing.text` | コード交換付きのテキストベースDMペアリングフロー | - | `threading` | reply-to-modeリゾルバ（固定、アカウントスコープ、またはカスタム） | + | `security.dm` | 設定フィールドからのスコープ付きDMセキュリティリゾルバー | + | `pairing.text` | コード交換を伴うテキストベースのDMペアリングフロー | + | `threading` | reply-toモードリゾルバー（固定、アカウントスコープ、またはカスタム） | | `outbound.attachedResults` | 結果メタデータ（メッセージID）を返す送信関数 | - 完全な制御が必要な場合は、宣言的オプションの代わりに生のadapterオブジェクトを渡すこともできます。 + 完全に制御する必要がある場合は、宣言的オプションの代わりに + 生のアダプターオブジェクトを渡すこともできます。 - + `index.ts` を作成します: ```typescript index.ts @@ -401,14 +446,23 @@ if (decision.shouldSkip) return; }); ``` - チャネル所有のCLI descriptorは `registerCliMetadata(...)` に置いてください。これにより、OpenClawは完全なチャネル実行時を有効化せずにルートヘルプへ表示でき、通常の完全ロードでも実際のコマンド登録に同じdescriptorを取り込めます。`registerFull(...)` は実行時専用の作業に使ってください。 - `registerFull(...)` がGateway RPCメソッドを登録する場合は、Plugin固有のプレフィックスを使ってください。コア管理名前空間（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は予約されており、常に `operator.admin` に解決されます。 - `defineChannelPluginEntry` はこの登録モード分割を自動処理します。すべてのオプションについては [Entry Points](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry) を参照してください。 + チャネルが所有するCLIディスクリプターは `registerCliMetadata(...)` に置いてください。これにより、OpenClawは + 完全なチャネルランタイムを有効化せずにルートヘルプでそれらを表示でき、 + 通常の完全ロードでは実際のコマンド登録のために同じディスクリプターが引き続き使われます。 + `registerFull(...)` はランタイム専用の処理に使用してください。 + `registerFull(...)` がGateway RPCメソッドを登録する場合は、 + plugin固有のプレフィックスを使用してください。コア管理名前空間（`config.*`、 + `exec.approvals.*`、`wizard.*`、`update.*`）は引き続き予約されており、常に + `operator.admin` に解決されます。 + `defineChannelPluginEntry` は登録モードの分岐を自動的に処理します。すべての + オプションについては + [Entry Points](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry) + を参照してください。 - - オンボーディング時の軽量ロード用に `setup-entry.ts` を作成します: + + オンボーディング中の軽量ロードのために `setup-entry.ts` を作成します: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -417,26 +471,34 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClawは、チャネルが無効または未設定のときに完全エントリの代わりにこれを読み込みます。これにより、セットアップフロー中に重い実行時コードを引き込まずに済みます。詳細は [Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry) を参照してください。 + OpenClawは、チャネルが無効または未設定の場合、完全なエントリーの代わりにこれを読み込みます。 + これにより、セットアップフロー中に重いランタイムコードを引き込まずに済みます。 + 詳細は [Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry) を参照してください。 - セットアップ安全なエクスポートをサイドカーモジュールへ分割しているバンドル版ワークスペースチャネルは、明示的なセットアップ時runtime setterも必要な場合、`openclaw/plugin-sdk/channel-entry-contract` の `defineBundledChannelSetupEntry(...)` を使えます。 + セットアップ安全なエクスポートをサイドカーモジュールに分割する同梱ワークスペースチャネルでは、 + 明示的なセットアップ時ランタイムセッターも必要な場合に + `openclaw/plugin-sdk/channel-entry-contract` の + `defineBundledChannelSetupEntry(...)` + を使用できます。 - Pluginは、プラットフォームからメッセージを受け取り、それをOpenClawへ転送する必要があります。典型的なパターンは、リクエストを検証し、チャネルの受信ハンドラ経由でディスパッチするWebhookです: + pluginは、プラットフォームからメッセージを受信し、それを + OpenClawへ転送する必要があります。典型的なパターンは、リクエストを検証し、 + チャネルの受信ハンドラーを通じてディスパッチするWebhookです: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // Plugin管理認証（署名検証は自分で行う） + auth: "plugin", // plugin管理の認証（署名検証は自分で行います） handler: async (req, res) => { const event = parseWebhookPayload(req); - // あなたの受信ハンドラがメッセージをOpenClawへディスパッチします。 - // 正確な配線はプラットフォームSDKに依存します — - // 実例はバンドル版Microsoft TeamsまたはGoogle Chat Pluginパッケージを参照してください。 + // 受信ハンドラーがメッセージをOpenClawにディスパッチします。 + // 正確な配線はプラットフォームSDKによって異なります — + // 実例は同梱のMicrosoft TeamsまたはGoogle Chat pluginパッケージを参照してください。 await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -448,21 +510,25 @@ if (decision.shouldSkip) return; ``` - 受信メッセージ処理はチャネル固有です。各チャネルPluginは独自の受信パイプラインを所有します。実際のパターンは、バンドル版チャネルPlugin（たとえばMicrosoft TeamsまたはGoogle Chat Pluginパッケージ）を参照してください。 + 受信メッセージ処理はチャネル固有です。各チャネルpluginが + 独自の受信パイプラインを担います。実際のパターンについては、 + 同梱チャネルplugin + （たとえばMicrosoft TeamsまたはGoogle Chat pluginパッケージ） + を確認してください。 -`src/channel.test.ts` に同居テストを書いてください: +`src/channel.test.ts` にコロケートされたテストを書きます: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; import { acmeChatPlugin } from "./channel.js"; describe("acme-chat plugin", () => { - it("設定からアカウントを解決する", () => { + it("resolves account from config", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -472,7 +538,7 @@ if (decision.shouldSkip) return; expect(account.token).toBe("test-token"); }); - it("シークレットを具体化せずにアカウントを検査する", () => { + it("inspects account without materializing secrets", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -481,7 +547,7 @@ if (decision.shouldSkip) return; expect(result.tokenStatus).toBe("available"); }); - it("設定不足を報告する", () => { + it("reports missing config", () => { const cfg = { channels: {} } as any; const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined); expect(result.configured).toBe(false); @@ -503,16 +569,16 @@ if (decision.shouldSkip) return; ``` /acme-chat/ ├── package.json # openclaw.channel metadata -├── openclaw.plugin.json # 設定スキーマ付きマニフェスト +├── openclaw.plugin.json # 設定スキーマを含むマニフェスト ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # 公開エクスポート（任意） -├── runtime-api.ts # 内部実行時エクスポート（任意） +├── runtime-api.ts # 内部ランタイムエクスポート（任意） └── src/ - ├── channel.ts # createChatChannelPlugin経由のChannelPlugin + ├── channel.ts # createChatChannelPluginによるChannelPlugin ├── channel.test.ts # テスト ├── client.ts # プラットフォームAPIクライアント - └── runtime.ts # 実行時ストア（必要な場合） + └── runtime.ts # ランタイムストア（必要な場合） ``` ## 高度なトピック @@ -521,24 +587,28 @@ if (decision.shouldSkip) return; 固定、アカウントスコープ、またはカスタムの返信モード - - describeMessageToolとアクション検出 + + describeMessageToolとアクションディスカバリー inferTargetChatType、looksLikeId、resolveTarget - + api.runtime経由のTTS、STT、メディア、subagent -一部のバンドル版ヘルパー境界は、バンドル版Pluginの保守と互換性のためにまだ存在します。これらは新しいチャネルPlugin向けの推奨パターンではありません。直接そのバンドル版Pluginファミリーを保守している場合を除き、共通SDK画面から汎用のchannel/setup/reply/runtimeサブパスを優先してください。 +一部の同梱ヘルパーインターフェースは、同梱pluginの保守と +互換性のために引き続き存在します。これらは新しいチャネルpluginに推奨される +パターンではありません。bundled pluginファミリーを直接保守しているのでなければ、 +共通SDKインターフェースの汎用的なチャネル／セットアップ／返信／ランタイムの +サブパスを優先してください。 ## 次のステップ -- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — Pluginがモデルも提供する場合 +- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — pluginがモデルも提供する場合 - [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全なサブパスimportリファレンス - [SDK Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティと契約テスト - [Plugin Manifest](/ja-JP/plugins/manifest) — 完全なマニフェストスキーマ diff --git a/docs/ja-JP/providers/github-copilot.md b/docs/ja-JP/providers/github-copilot.md index 2bff82343..ed4884338 100644 --- a/docs/ja-JP/providers/github-copilot.md +++ b/docs/ja-JP/providers/github-copilot.md @@ -1,31 +1,27 @@ --- read_when: - - model provider として GitHub Copilot を使いたい場合 - - '`openclaw models auth login-github-copilot` フローが必要な場合' -summary: デバイスフローを使って OpenClaw から GitHub Copilot にサインインする + - モデルプロバイダーとして GitHub Copilot を使用したい場合 + - '`openclaw models auth login-github-copilot` フローが必要です' +summary: デバイスフローを使用して OpenClaw から GitHub Copilot にサインインする title: GitHub Copilot x-i18n: - generated_at: "2026-04-21T04:50:08Z" + generated_at: "2026-04-21T19:20:40Z" model: gpt-5.4 provider: openai - source_hash: f7faafbd3bdcd8886e75fb0d40c3eec66355df3fca6160ebbbb9a0018b7839fe + source_hash: b5169839322f64b24b194302b61c5bad67c6cb6595989f9a1ef65867d8b68659 source_path: providers/github-copilot.md workflow: 15 --- # GitHub Copilot -GitHub Copilot は GitHub の AI コーディングアシスタントです。GitHub アカウントとプランに応じて、Copilot -model へのアクセスを提供します。OpenClaw は Copilot を model -provider として 2 つの異なる方法で使用できます。 +GitHub Copilot は GitHub の AI コーディングアシスタントです。GitHub アカウントとプランで Copilot モデルにアクセスできます。OpenClaw は、2 つの異なる方法で Copilot をモデルプロバイダーとして使用できます。 ## OpenClaw で Copilot を使う 2 つの方法 - - ネイティブの device-login フローを使用して GitHub token を取得し、その後 OpenClaw 実行時に - Copilot API token へ交換します。これが **デフォルト** で最も簡単な方法です。 - VS Code を必要としないためです。 + + ネイティブのデバイスログインフローを使用して GitHub トークンを取得し、その後 OpenClaw の実行時にそれを Copilot API トークンと交換します。これは **デフォルト** であり、VS Code を必要としないため最も簡単な方法です。 @@ -33,20 +29,19 @@ provider として 2 つの異なる方法で使用できます。 openclaw models auth login-github-copilot ``` - URL にアクセスして一時コードを入力するよう求められます。完了するまで - terminal は開いたままにしてください。 + URL にアクセスして 1 回限りのコードを入力するよう求められます。完了するまでターミナルを開いたままにしてください。 - + ```bash - openclaw models set github-copilot/claude-opus-4.6 + openclaw models set github-copilot/claude-opus-4.7 ``` - または config で: + または、config では次のようにします。 ```json5 { agents: { - defaults: { model: { primary: "github-copilot/claude-opus-4.6" } }, + defaults: { model: { primary: "github-copilot/claude-opus-4.7" } }, }, } ``` @@ -55,90 +50,75 @@ provider として 2 つの異なる方法で使用できます。 - - **Copilot Proxy** VS Code 拡張をローカル bridge として使用します。OpenClaw は - proxy の `/v1` endpoint と通信し、そこで設定した model 一覧を使用します。 + + **Copilot Proxy** VS Code 拡張機能をローカルブリッジとして使用します。OpenClaw はプロキシの `/v1` エンドポイントと通信し、そこで設定したモデル一覧を使用します。 - すでに VS Code で Copilot Proxy を動かしている場合や、それ経由でルーティングしたい場合はこれを選んでください。 - Plugin を有効化し、VS Code 拡張を起動したままにしておく必要があります。 + すでに VS Code で Copilot Proxy を実行している場合、またはそれを経由する必要がある場合は、こちらを選択してください。Plugin を有効にし、VS Code 拡張機能を実行したままにする必要があります。 -## 任意フラグ +## オプションフラグ -| Flag | 説明 | +| Flag | 説明 | | --------------- | --------------------------------------------------- | -| `--yes` | 確認プロンプトをスキップする | -| `--set-default` | provider 推奨のデフォルト model も適用する | +| `--yes` | 確認プロンプトをスキップする | +| `--set-default` | プロバイダー推奨のデフォルトモデルも適用する | ```bash -# Skip confirmation +# 確認をスキップ openclaw models auth login-github-copilot --yes -# Login and set the default model in one step +# ログインし、デフォルトモデルも 1 ステップで設定 openclaw models auth login --provider github-copilot --method device --set-default ``` - device-login フローには対話型 TTY が必要です。非対話スクリプトや CI パイプラインではなく、 - terminal で直接実行してください。 + デバイスログインフローには対話型 TTY が必要です。非対話型スクリプトや CI パイプラインではなく、ターミナルで直接実行してください。 - - Copilot の model 可用性は GitHub のプランに依存します。model が - 拒否される場合は、別の ID（たとえば `github-copilot/gpt-4.1`）を試してください。 + + Copilot モデルの利用可否は GitHub プランによって異なります。モデルが拒否された場合は、別の ID を試してください（例: `github-copilot/gpt-4.1`）。 - Claude の model ID は自動的に Anthropic Messages transport を使用します。GPT、 - o-series、Gemini model は OpenAI Responses transport を使い続けます。OpenClaw は - model ref に基づいて正しい transport を選択します。 + Claude モデル ID は自動的に Anthropic Messages トランスポートを使用します。GPT、o-series、Gemini モデルは OpenAI Responses トランスポートのままです。OpenClaw はモデル ref に基づいて正しいトランスポートを選択します。 - OpenClaw は Copilot auth を次の優先順位で環境変数から解決します。 + OpenClaw は、以下の優先順位で環境変数から Copilot 認証情報を解決します。 - | 優先順位 | 変数 | 注記 | + | Priority | Variable | Notes | | -------- | --------------------- | -------------------------------- | - | 1 | `COPILOT_GITHUB_TOKEN` | 最優先、Copilot 固有 | - | 2 | `GH_TOKEN` | GitHub CLI token（フォールバック） | - | 3 | `GITHUB_TOKEN` | 標準 GitHub token（最下位） | + | 1 | `COPILOT_GITHUB_TOKEN` | 最優先、Copilot 専用 | + | 2 | `GH_TOKEN` | GitHub CLI トークン（フォールバック） | + | 3 | `GITHUB_TOKEN` | 標準の GitHub トークン（最下位） | - 複数の変数が設定されている場合、OpenClaw は最優先のものを使います。 - device-login フロー（`openclaw models auth login-github-copilot`）は - auth profile store に token を保存し、すべての環境変数より優先されます。 + 複数の変数が設定されている場合、OpenClaw は最優先のものを使用します。デバイスログインフロー (`openclaw models auth login-github-copilot`) はトークンを auth profile store に保存し、すべての環境変数よりも優先されます。 - - ログインでは GitHub token を auth profile store に保存し、OpenClaw 実行時にそれを - Copilot API token に交換します。token を手動管理する必要はありません。 + + ログインにより GitHub トークンが auth profile store に保存され、OpenClaw の実行時にそれが Copilot API トークンと交換されます。トークンを手動で管理する必要はありません。 -対話型 TTY が必要です。ログインコマンドは headless script や CI job の中ではなく、 -terminal で直接実行してください。 +対話型 TTY が必要です。ログインコマンドは、ヘッドレススクリプトや CI ジョブの中ではなく、ターミナルで直接実行してください。 -## メモリ検索 embedding +## メモリ検索の埋め込み -GitHub Copilot は -[memory search](/ja-JP/concepts/memory-search) 用の embedding provider としても利用できます。Copilot サブスクリプションがあり、 -ログイン済みであれば、OpenClaw は別の API キーなしで embedding に使用できます。 +GitHub Copilot は、[メモリ検索](/ja-JP/concepts/memory-search) の埋め込みプロバイダーとしても使用できます。Copilot サブスクリプションがあり、ログイン済みであれば、OpenClaw は別個の API キーなしで埋め込みにこれを使用できます。 ### 自動検出 -`memorySearch.provider` が `"auto"`（デフォルト）の場合、GitHub Copilot は -優先度 15 で試されます。これはローカル embedding の後、OpenAI や他の有料 -provider の前です。GitHub token が利用可能なら、OpenClaw は -Copilot API から利用可能な embedding model を検出し、自動で最適なものを選びます。 +`memorySearch.provider` が `"auto"`（デフォルト）の場合、GitHub Copilot は優先度 15 で試されます。これはローカル埋め込みの後、OpenAI やその他の有料プロバイダーの前です。GitHub トークンが利用可能であれば、OpenClaw は Copilot API から利用可能な埋め込みモデルを検出し、最適なものを自動的に選択します。 -### 明示的な config +### 明示的な設定 ```json5 { @@ -146,7 +126,7 @@ Copilot API から利用可能な embedding model を検出し、自動で最適 defaults: { memorySearch: { provider: "github-copilot", - // Optional: override the auto-discovered model + // 任意: 自動検出されたモデルを上書き model: "text-embedding-3-small", }, }, @@ -156,22 +136,21 @@ Copilot API から利用可能な embedding model を検出し、自動で最適 ### 仕組み -1. OpenClaw が GitHub token を解決します（env var または auth profile から）。 -2. それを短命の Copilot API token に交換します。 -3. Copilot の `/models` endpoint に問い合わせ、利用可能な embedding model を検出します。 -4. 最適な model を選びます（`text-embedding-3-small` を優先）。 -5. embedding リクエストを Copilot の `/embeddings` endpoint に送信します。 +1. OpenClaw が GitHub トークンを解決します（環境変数または auth profile から）。 +2. それを短期間有効な Copilot API トークンと交換します。 +3. Copilot の `/models` エンドポイントを問い合わせて、利用可能な埋め込みモデルを検出します。 +4. 最適なモデルを選択します（`text-embedding-3-small` を優先）。 +5. Copilot の `/embeddings` エンドポイントに埋め込みリクエストを送信します。 -model の可用性は GitHub のプランに依存します。embedding model が -利用できない場合、OpenClaw は Copilot をスキップして次の provider を試します。 +モデルの利用可否は GitHub プランによって異なります。埋め込みモデルが利用できない場合、OpenClaw は Copilot をスキップして次のプロバイダーを試します。 ## 関連 - - provider、model ref、failover 動作の選び方。 + + プロバイダー、モデル ref、フェイルオーバー動作の選び方。 - - auth の詳細と credential 再利用ルール。 + + 認証の詳細と認証情報再利用のルール。 diff --git a/docs/ja-JP/tools/subagents.md b/docs/ja-JP/tools/subagents.md index a4b088ff8..a4ef9d8f0 100644 --- a/docs/ja-JP/tools/subagents.md +++ b/docs/ja-JP/tools/subagents.md @@ -1,26 +1,26 @@ --- read_when: - - エージェント経由でバックグラウンド/並列作業を行いたい - - '`sessions_spawn` や sub-agent tool policy を変更している' - - スレッドに束縛された subagent session を実装またはトラブルシュートしている -summary: 結果を依頼元チャットへ通知する、分離されたエージェント実行を起動するサブエージェント + - エージェントを通じてバックグラウンド/並列作業を行いたい場合 + - '`sessions_spawn` またはサブエージェントツールのポリシーを変更している場合' + - スレッドに紐づいたサブエージェントセッションを実装またはトラブルシューティングしている場合 +summary: 'サブエージェント: 結果を依頼元チャットに通知する分離されたエージェント実行を起動すること' title: サブエージェント x-i18n: - generated_at: "2026-04-05T13:01:41Z" + generated_at: "2026-04-21T19:20:44Z" model: gpt-5.4 provider: openai - source_hash: 9df7cc35a3069ce4eb9c92a95df3ce5365a00a3fae92ff73def75461b58fec3f + source_hash: 218913f0db88d40e1b5fdb0201b8d23e7af23df572c86ff4be2637cb62498281 source_path: tools/subagents.md workflow: 15 --- # サブエージェント -サブエージェントは、既存のエージェント実行から起動されるバックグラウンドのエージェント実行です。各サブエージェントは独自のセッション（`agent::subagent:`）で実行され、終了すると、その結果を依頼元のチャットチャンネルへ**通知**します。各サブエージェント実行は [background task](/ja-JP/automation/tasks) として追跡されます。 +サブエージェントは、既存のエージェント実行から起動されるバックグラウンドのエージェント実行です。各サブエージェントは自身のセッション (`agent::subagent:`) で動作し、完了するとその結果を依頼元のチャットチャネルに**通知**します。各サブエージェント実行は、[バックグラウンドタスク](/ja-JP/automation/tasks)として追跡されます。 ## スラッシュコマンド -**現在のセッション**に対するサブエージェント実行の確認や制御には `/subagents` を使用します: +現在のセッションのサブエージェント実行を確認または制御するには、`/subagents` を使用します。 - `/subagents list` - `/subagents kill ` @@ -30,9 +30,9 @@ x-i18n: - `/subagents steer ` - `/subagents spawn [--model ] [--thinking ]` -スレッド束縛の制御: +スレッドバインディング制御: -これらのコマンドは、永続的なスレッド束縛をサポートするチャンネルで動作します。以下の**スレッド対応チャンネル**を参照してください。 +これらのコマンドは、永続的なスレッドバインディングをサポートするチャネルで動作します。詳細は以下の**スレッドをサポートするチャネル**を参照してください。 - `/focus ` - `/unfocus` @@ -40,267 +40,254 @@ x-i18n: - `/session idle ` - `/session max-age ` -`/subagents info` は実行メタデータ（ステータス、タイムスタンプ、session id、transcript path、cleanup）を表示します。 -`sessions_history` は制限付きで安全性フィルター済みの再確認ビューに使用し、 -生の完全な transcript が必要な場合はディスク上の transcript path を確認してください。 +`/subagents info` は、実行メタデータ（ステータス、タイムスタンプ、セッション id、transcript パス、cleanup）を表示します。 +制限付きで安全フィルタ済みのリコール表示には `sessions_history` を使用し、生の完全な transcript が必要な場合はディスク上の transcript パスを確認してください。 -### 起動時の動作 +### 起動動作 -`/subagents spawn` は、内部リレーではなくユーザーコマンドとしてバックグラウンドのサブエージェントを起動し、実行終了時に依頼元チャットへ最終的な完了通知を 1 回送信します。 +`/subagents spawn` は、内部リレーではなくユーザーコマンドとしてバックグラウンドのサブエージェントを開始し、実行が完了すると依頼元チャットへ最終的な完了更新を 1 件送信します。 -- spawn コマンドは非ブロッキングです。run id を即座に返します。 -- 完了時に、サブエージェントはサマリー/結果メッセージを依頼元チャットチャンネルへ通知します。 -- 完了通知は push ベースです。起動後は、完了を待つためだけに `/subagents list`、 - `sessions_list`、`sessions_history` をループでポーリングしないでください。 - ステータス確認はデバッグや介入が必要なときだけ行ってください。 -- 完了時、OpenClaw は、そのサブエージェントセッションが開いた追跡対象の browser tabs/processes を、通知後の cleanup フローに進む前にベストエフォートで閉じます。 -- 手動起動では、配信は耐障害性があります: - - OpenClaw はまず、安定した idempotency key を使って直接 `agent` 配信を試みます。 - - 直接配信が失敗した場合は、queue routing にフォールバックします。 - - queue routing も利用できない場合は、最終的に諦める前に、短い指数バックオフで通知を再試行します。 -- 完了時の配信では、解決済みの依頼元ルートを維持します: - - 利用可能な場合は、thread-bound または conversation-bound の完了ルートが優先されます - - 完了元が channel しか提供しない場合、OpenClaw は依頼元セッションの解決済みルート（`lastChannel` / `lastTo` / `lastAccountId`）から不足している target/account を補い、直接配信が引き続き機能するようにします -- 依頼元セッションへの完了ハンドオフは、実行時に生成される内部コンテキスト（ユーザー作成テキストではない）であり、以下を含みます: - - `Result`（最新の表示可能な `assistant` 返信テキスト、なければサニタイズ済みの最新 `tool`/`toolResult` テキスト） +- spawn コマンドは非ブロッキングで、実行 id を即座に返します。 +- 完了時、サブエージェントは要約/結果メッセージを依頼元チャットチャネルに通知します。 +- 完了通知はプッシュベースです。起動後、完了待ちのためだけに `/subagents list`、`sessions_list`、`sessions_history` をループでポーリングしないでください。ステータス確認は、デバッグまたは介入が必要なときにオンデマンドでのみ行ってください。 +- 完了時、OpenClaw はベストエフォートで、そのサブエージェントセッションが開いた追跡対象のブラウザタブ/プロセスを閉じてから通知 cleanup フローを続行します。 +- 手動起動時、配信には耐障害性があります: + - OpenClaw はまず、安定した冪等性キーを使って直接 `agent` 配信を試みます。 + - 直接配信に失敗した場合、キュールーティングにフォールバックします。 + - キュールーティングも利用できない場合、最終的に諦める前に、短い指数バックオフで通知を再試行します。 +- 完了配信では、解決済みの依頼元ルートが維持されます: + - 利用可能な場合、スレッドバインド済みまたは会話バインド済みの完了ルートが優先されます + - 完了元がチャネルしか提供しない場合でも、OpenClaw は依頼元セッションの解決済みルート（`lastChannel` / `lastTo` / `lastAccountId`）から不足している target/account を補い、直接配信が引き続き機能するようにします +- 依頼元セッションへの完了引き渡しは、ランタイム生成の内部コンテキスト（ユーザーが作成したテキストではない）であり、次を含みます: + - `Result`（最新の表示可能な `assistant` 返信テキスト。ない場合は、サニタイズ済みの最新 `tool`/`toolResult` テキスト。失敗して終了した実行では、取得済み返信テキストを再利用しません） - `Status`（`completed successfully` / `failed` / `timed out` / `unknown`） - - コンパクトな runtime/token 統計 - - 依頼元エージェントに対し、生の内部メタデータを転送するのではなく、通常の assistant の声で書き直すよう指示する配信命令 -- `--model` と `--thinking` は、その特定の実行の既定値を上書きします。 -- 完了後の詳細や出力確認には `info`/`log` を使用します。 -- `/subagents spawn` はワンショットモード（`mode: "run"`）です。永続的なスレッド束縛セッションには、`thread: true` と `mode: "session"` を指定した `sessions_spawn` を使用してください。 -- ACP harness session（Codex、Claude Code、Gemini CLI）には、`runtime: "acp"` を指定した `sessions_spawn` を使用し、[ACP Agents](/tools/acp-agents) を参照してください。 + - コンパクトなランタイム/トークン統計 + - 依頼元エージェントに対し、生の内部メタデータを転送せず、通常の assistant の声で書き直すよう指示する配信命令 +- `--model` と `--thinking` は、その特定の実行のデフォルトを上書きします。 +- 完了後の詳細と出力の確認には `info`/`log` を使用します。 +- `/subagents spawn` はワンショットモード（`mode: "run"`）です。永続的なスレッドバインド済みセッションには、`thread: true` と `mode: "session"` を指定した `sessions_spawn` を使用してください。 +- ACP ハーネスセッション（Codex、Claude Code、Gemini CLI）には、`runtime: "acp"` を指定した `sessions_spawn` を使用し、[ACP Agents](/ja-JP/tools/acp-agents) を参照してください。 主な目的: -- メイン実行をブロックせずに、「調査 / 長時間タスク / 遅い tool」作業を並列化する。 -- サブエージェントを既定で分離した状態に保つ（セッション分離 + 任意の sandboxing）。 -- tool surface を誤用しにくく保つ。サブエージェントは既定では session tools を受け取りません。 +- メイン実行をブロックせずに、「調査 / 長時間タスク / 遅いツール」の作業を並列化する。 +- デフォルトでサブエージェントを分離状態に保つ（セッション分離 + 任意のサンドボックス化）。 +- ツールの操作を誤用しにくく保つ。サブエージェントには、デフォルトでセッションツールは付与されません。 - オーケストレーターパターン向けに、設定可能なネスト深度をサポートする。 -コストに関する注意: 各サブエージェントは**独自の**コンテキストとトークン使用量を持ちます。重いタスクや繰り返しタスクでは、サブエージェントには安価なモデルを設定し、メインエージェントには高品質なモデルを維持してください。 -これは `agents.defaults.subagents.model` またはエージェントごとの上書きで設定できます。 +コストに関する注意: 各サブエージェントは、それぞれ**独自の**コンテキストとトークン使用量を持ちます。重いタスクや反復的なタスクでは、サブエージェントにより安価なモデルを設定し、メインエージェントはより高品質なモデルのままにしてください。これは `agents.defaults.subagents.model` またはエージェントごとのオーバーライドで設定できます。 -## Tool +## ツール `sessions_spawn` を使用します: -- サブエージェント実行を開始します（`deliver: false`、global lane: `subagent`） -- その後、通知ステップを実行し、通知返信を依頼元チャットチャンネルへ投稿します -- 既定モデル: `agents.defaults.subagents.model`（またはエージェントごとの `agents.list[].subagents.model`）を設定していない限り、呼び出し元を継承します。明示的な `sessions_spawn.model` がある場合はそれが優先されます。 -- 既定の thinking: `agents.defaults.subagents.thinking`（またはエージェントごとの `agents.list[].subagents.thinking`）を設定していない限り、呼び出し元を継承します。明示的な `sessions_spawn.thinking` がある場合はそれが優先されます。 -- 既定の実行タイムアウト: `sessions_spawn.runTimeoutSeconds` が省略された場合、OpenClaw は設定されていれば `agents.defaults.subagents.runTimeoutSeconds` を使用し、そうでなければ `0`（タイムアウトなし）にフォールバックします。 +- サブエージェント実行を開始します（`deliver: false`、グローバルレーン: `subagent`） +- 次に通知ステップを実行し、その通知返信を依頼元チャットチャネルに投稿します +- デフォルトモデル: `agents.defaults.subagents.model`（またはエージェントごとの `agents.list[].subagents.model`）を設定していない場合は呼び出し元を継承します。明示的な `sessions_spawn.model` がある場合は常にそれが優先されます。 +- デフォルト thinking: `agents.defaults.subagents.thinking`（またはエージェントごとの `agents.list[].subagents.thinking`）を設定していない場合は呼び出し元を継承します。明示的な `sessions_spawn.thinking` がある場合は常にそれが優先されます。 +- デフォルトの実行タイムアウト: `sessions_spawn.runTimeoutSeconds` が省略された場合、OpenClaw は設定されていれば `agents.defaults.subagents.runTimeoutSeconds` を使用し、そうでなければ `0`（タイムアウトなし）にフォールバックします。 -Tool パラメーター: +ツールパラメータ: - `task`（必須） - `label?`（任意） -- `agentId?`（任意。許可されていれば別の agent id の下で起動） -- `model?`（任意。サブエージェントのモデルを上書き。無効な値はスキップされ、tool result に警告付きで既定モデル上でサブエージェントが実行されます） +- `agentId?`（任意。許可されていれば別の agent id で起動） +- `model?`（任意。サブエージェントのモデルを上書き。無効な値はスキップされ、サブエージェントはデフォルトモデルで実行され、警告がツール結果に表示されます） - `thinking?`（任意。サブエージェント実行の thinking レベルを上書き） -- `runTimeoutSeconds?`（設定されていれば `agents.defaults.subagents.runTimeoutSeconds` が既定値、そうでなければ `0`。設定時は N 秒後にサブエージェント実行が中止されます） -- `thread?`（既定 `false`。`true` の場合、このサブエージェントセッションに対して channel thread binding を要求） +- `runTimeoutSeconds?`（設定されていれば `agents.defaults.subagents.runTimeoutSeconds` がデフォルト、そうでなければ `0`。設定すると、サブエージェント実行は N 秒後に中止されます） +- `thread?`（デフォルト `false`。`true` の場合、このサブエージェントセッションに対してチャネルスレッドバインディングを要求します） - `mode?`（`run|session`） - - 既定は `run` - - `thread: true` で `mode` が省略された場合、既定は `session` - - `mode: "session"` には `thread: true` が必要 -- `cleanup?`（`delete|keep`、既定 `keep`） -- `sandbox?`（`inherit|require`、既定 `inherit`。`require` は、対象子ランタイムが sandboxed でない限り起動を拒否） -- `sessions_spawn` は channel-delivery パラメーター（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）を受け付けません。配信には、起動された実行側から `message`/`sessions_send` を使用してください。 + - デフォルトは `run` + - `thread: true` で `mode` が省略された場合、デフォルトは `session` になります + - `mode: "session"` には `thread: true` が必要です +- `cleanup?`（`delete|keep`、デフォルト `keep`） +- `sandbox?`（`inherit|require`、デフォルト `inherit`。`require` は、対象の子ランタイムがサンドボックス化されていない場合、起動を拒否します） +- `sessions_spawn` はチャネル配信パラメータ（`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`）を受け付けません。配信には、起動された実行から `message`/`sessions_send` を使用してください。 -## スレッド束縛セッション +## スレッドバインド済みセッション -チャンネルで thread bindings が有効になっている場合、サブエージェントはスレッドに束縛されたままにできるため、そのスレッド内の後続ユーザーメッセージは同じサブエージェントセッションへルーティングされ続けます。 +チャネルでスレッドバインディングが有効な場合、サブエージェントはスレッドにバインドされたままにでき、そのスレッド内での後続ユーザーメッセージは同じサブエージェントセッションへルーティングされ続けます。 -### スレッド対応チャンネル +### スレッドをサポートするチャネル -- Discord（現在サポートされている唯一のチャンネル）: 永続的な thread-bound subagent sessions（`thread: true` を指定した `sessions_spawn`）、手動のスレッド制御（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）、およびアダプターキー `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`、`channels.discord.threadBindings.spawnSubagentSessions` をサポートします。 +- Discord（現在サポートされている唯一のチャネル）: 永続的なスレッドバインド済みサブエージェントセッション（`thread: true` を指定した `sessions_spawn`）、手動スレッド制御（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）、およびアダプターキー `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`, `channels.discord.threadBindings.spawnSubagentSessions` をサポートします。 クイックフロー: -1. `thread: true`（必要に応じて `mode: "session"` も）を指定して `sessions_spawn` で起動します。 -2. OpenClaw が、そのセッション対象に対してアクティブチャンネル内でスレッドを作成または束縛します。 -3. そのスレッド内の返信と後続メッセージは、束縛されたセッションへルーティングされます。 -4. `/session idle` を使って、非アクティブ時の自動 unfocus を確認/更新し、`/session max-age` でハード上限を制御します。 +1. `thread: true`（必要に応じて `mode: "session"`）を指定して `sessions_spawn` で起動します。 +2. OpenClaw は、アクティブなチャネル内でそのセッション対象にスレッドを作成またはバインドします。 +3. そのスレッド内での返信や後続メッセージは、バインドされたセッションへルーティングされます。 +4. 非アクティブ時の自動 unfocus の確認/更新には `/session idle` を使用し、ハード上限の制御には `/session max-age` を使用します。 5. 手動で切り離すには `/unfocus` を使用します。 手動制御: -- `/focus ` は、現在のスレッドをサブエージェント/セッション対象に束縛します（または新しく作成します）。 -- `/unfocus` は、現在束縛されているスレッドの束縛を解除します。 -- `/agents` は、アクティブな実行と束縛状態（`thread:` または `unbound`）を一覧表示します。 -- `/session idle` と `/session max-age` は、focus 済みの束縛スレッドでのみ動作します。 +- `/focus ` は、現在のスレッドをサブエージェント/セッション対象にバインドします（または新規に作成します）。 +- `/unfocus` は、現在バインドされているスレッドのバインディングを解除します。 +- `/agents` は、アクティブな実行とバインディング状態（`thread:` または `unbound`）を一覧表示します。 +- `/session idle` と `/session max-age` は、フォーカスされたバインド済みスレッドでのみ動作します。 設定スイッチ: -- グローバル既定値: `session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours` -- チャンネル上書きと起動時の自動束縛キーはアダプター固有です。上記の**スレッド対応チャンネル**を参照してください。 +- グローバルデフォルト: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours` +- チャネル上書きおよび起動時の自動バインドキーはアダプター固有です。詳細は上記の**スレッドをサポートするチャネル**を参照してください。 -現在のアダプター詳細については [Configuration Reference](/ja-JP/gateway/configuration-reference) と [Slash commands](/tools/slash-commands) を参照してください。 +現在のアダプター詳細は [Configuration Reference](/ja-JP/gateway/configuration-reference) と [Slash commands](/ja-JP/tools/slash-commands) を参照してください。 -Allowlist: +許可リスト: -- `agents.list[].subagents.allowAgents`: `agentId` 経由で指定可能な agent id の一覧（任意のものを許可するには `["*"]`）。既定値: 依頼元エージェントのみ。 -- `agents.defaults.subagents.allowAgents`: 依頼元エージェントが独自の `subagents.allowAgents` を設定していない場合に使用される、既定の対象エージェント allowlist。 -- Sandbox 継承ガード: 依頼元セッションが sandboxed の場合、`sessions_spawn` は sandbox なしで実行される対象を拒否します。 -- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制）。既定値: false。 +- `agents.list[].subagents.allowAgents`: `agentId` 経由で対象指定できる agent id のリスト（任意を許可する場合は `["*"]`）。デフォルトでは、依頼元エージェントのみです。 +- `agents.defaults.subagents.allowAgents`: 依頼元エージェントが独自の `subagents.allowAgents` を設定していない場合に使用される、デフォルトの対象エージェント許可リストです。 +- サンドボックス継承ガード: 依頼元セッションがサンドボックス化されている場合、`sessions_spawn` はサンドボックスなしで実行される対象を拒否します。 +- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制）。デフォルトは false です。 検出: -- `sessions_spawn` で現在どの agent id が許可されているか確認するには `agents_list` を使用します。 +- `sessions_spawn` で現在許可されている agent id を確認するには `agents_list` を使用します。 自動アーカイブ: -- サブエージェントセッションは、`agents.defaults.subagents.archiveAfterMinutes`（既定値: 60）後に自動的にアーカイブされます。 +- サブエージェントセッションは、`agents.defaults.subagents.archiveAfterMinutes`（デフォルト: 60）経過後に自動的にアーカイブされます。 - アーカイブでは `sessions.delete` を使用し、transcript を `*.deleted.` にリネームします（同じフォルダー内）。 -- `cleanup: "delete"` は通知直後に即時アーカイブします（ただし transcript はリネームによって保持されます）。 -- 自動アーカイブはベストエフォートです。gateway が再起動すると保留中タイマーは失われます。 -- `runTimeoutSeconds` は自動アーカイブしません。実行を停止するだけです。セッションは自動アーカイブまで残ります。 -- 自動アーカイブは深さ 1 と深さ 2 のセッションに同様に適用されます。 -- browser cleanup は archive cleanup とは別です。追跡対象の browser tabs/processes は、transcript/session record を保持する場合でも、実行終了時にベストエフォートで閉じられます。 +- `cleanup: "delete"` は通知後すぐにアーカイブします（ただし transcript はリネームにより保持されます）。 +- 自動アーカイブはベストエフォートであり、gateway が再起動すると保留中のタイマーは失われます。 +- `runTimeoutSeconds` は自動アーカイブを行いません。実行を停止するだけです。セッションは自動アーカイブまで残ります。 +- 自動アーカイブは、深さ 1 と深さ 2 のセッションに等しく適用されます。 +- ブラウザ cleanup はアーカイブ cleanup とは別です。transcript/セッションレコードを保持する場合でも、実行完了時に追跡対象のブラウザタブ/プロセスはベストエフォートで閉じられます。 -## ネストしたサブエージェント +## ネストされたサブエージェント -既定では、サブエージェントは自分自身のサブエージェントを起動できません（`maxSpawnDepth: 1`）。`maxSpawnDepth: 2` を設定すると 1 段階のネストを有効にでき、**オーケストレーターパターン**、つまり main → orchestrator sub-agent → worker sub-sub-agents を実現できます。 +デフォルトでは、サブエージェントは自身のサブエージェントを起動できません（`maxSpawnDepth: 1`）。`maxSpawnDepth: 2` を設定すると、1 レベルのネストを有効化でき、**オーケストレーターパターン**が可能になります: main → オーケストレーターサブエージェント → ワーカーサブサブエージェント。 -### 有効化方法 +### 有効化する方法 ```json5 { agents: { defaults: { subagents: { - maxSpawnDepth: 2, // サブエージェントによる子の起動を許可（既定: 1） - maxChildrenPerAgent: 5, // エージェントセッションごとのアクティブな子の最大数（既定: 5） - maxConcurrent: 8, // グローバルな同時実行レーン上限（既定: 8） - runTimeoutSeconds: 900, // 省略時の sessions_spawn の既定タイムアウト（0 = タイムアウトなし） + maxSpawnDepth: 2, // サブエージェントによる子の起動を許可（デフォルト: 1） + maxChildrenPerAgent: 5, // エージェントセッションあたりのアクティブな子の最大数（デフォルト: 5） + maxConcurrent: 8, // グローバル同時実行レーン上限（デフォルト: 8） + runTimeoutSeconds: 900, // 省略時の sessions_spawn のデフォルトタイムアウト（0 = タイムアウトなし） }, }, }, } ``` -### 深さレベル +### 深度レベル -| Depth | Session key の形状 | 役割 | 起動可能か | -| ----- | ------------------------------------------ | -------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | メインエージェント | 常に可能 | -| 1 | `agent::subagent:` | サブエージェント（深さ 2 が許可された場合は orchestrator） | `maxSpawnDepth >= 2` の場合のみ | -| 2 | `agent::subagent::subagent:` | サブサブエージェント（leaf worker） | 不可 | +| 深度 | セッションキーの形式 | 役割 | 起動可能か | +| ----- | -------------------------------------------- | ---------------------------------------------- | ----------------------------- | +| 0 | `agent::main` | メインエージェント | 常に可能 | +| 1 | `agent::subagent:` | サブエージェント（深度 2 が許可された場合はオーケストレーター） | `maxSpawnDepth >= 2` の場合のみ | +| 2 | `agent::subagent::subagent:` | サブサブエージェント（リーフワーカー） | 不可 | ### 通知チェーン 結果はチェーンをさかのぼって流れます: -1. 深さ 2 の worker が終了 → 親（深さ 1 の orchestrator）へ通知 -2. 深さ 1 の orchestrator が通知を受信し、結果を統合して終了 → main へ通知 +1. 深度 2 のワーカーが完了 → 親（深度 1 のオーケストレーター）に通知 +2. 深度 1 のオーケストレーターが通知を受信し、結果を統合して完了 → main に通知 3. メインエージェントが通知を受信し、ユーザーへ配信 -各レベルが受け取るのは、自分の直下の子からの通知だけです。 +各レベルが受け取るのは、その直接の子からの通知だけです。 -運用上のガイダンス: +運用ガイダンス: -- `sessions_list`、`sessions_history`、`/subagents list`、または - `exec` の sleep コマンドを中心にしたポーリングループを作るのではなく、 - 子の作業は一度開始したら完了イベントを待ってください。 -- すでに最終回答を送信した後に子の完了イベントが到着した場合、 - 正しいフォローアップは厳密に無音トークン `NO_REPLY` / `no_reply` です。 +- 子の作業は一度開始し、`sessions_list`、`sessions_history`、`/subagents list`、`exec` の sleep コマンドを使ったポーリングループを組むのではなく、完了イベントを待ってください。 +- 最終回答をすでに送信した後に子の完了イベントが到着した場合、正しい後続応答は、完全に無音のトークン `NO_REPLY` / `no_reply` です。 -### 深さごとの tool policy +### 深度ごとのツールポリシー -- 役割と制御スコープは起動時に session metadata に書き込まれます。これにより、平坦化または復元された session key が誤って orchestrator 権限を取り戻すことを防ぎます。 -- **深さ 1（orchestrator、`maxSpawnDepth >= 2` の場合）**: 子を管理できるよう、`sessions_spawn`、`subagents`、`sessions_list`、`sessions_history` を取得します。その他の session/system tools は引き続き拒否されます。 -- **深さ 1（leaf、`maxSpawnDepth == 1` の場合）**: session tools はありません（現在の既定動作）。 -- **深さ 2（leaf worker）**: session tools はありません。深さ 2 では `sessions_spawn` は常に拒否されます。これ以上子を起動できません。 +- ロールと制御スコープは起動時にセッションメタデータへ書き込まれます。これにより、フラット化された、または復元されたセッションキーが、誤ってオーケストレーター権限を取り戻すことを防ぎます。 +- **深度 1（オーケストレーター、`maxSpawnDepth >= 2` の場合）**: `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history` を取得し、自身の子を管理できます。その他の session/system ツールは引き続き拒否されます。 +- **深度 1（リーフ、`maxSpawnDepth == 1` の場合）**: session ツールなし（現在のデフォルト動作）。 +- **深度 2（リーフワーカー）**: session ツールなし — 深度 2 では `sessions_spawn` は常に拒否されます。これ以上子を起動することはできません。 ### エージェントごとの起動上限 -各エージェントセッション（任意の深さ）は、同時に最大 `maxChildrenPerAgent`（既定: 5）個のアクティブな子しか持てません。これにより、単一 orchestrator からの暴走的なファンアウトを防ぎます。 +各エージェントセッション（任意の深度）は、同時に最大 `maxChildrenPerAgent`（デフォルト: 5）個までのアクティブな子を持てます。これにより、単一のオーケストレーターからの制御不能なファンアウトを防ぎます。 ### カスケード停止 -深さ 1 の orchestrator を停止すると、すべての深さ 2 の子も自動的に停止します: +深度 1 のオーケストレーターを停止すると、その深度 2 の子もすべて自動的に停止します。 -- メインチャットでの `/stop` は、すべての深さ 1 エージェントを停止し、その深さ 2 の子へもカスケードします。 -- `/subagents kill ` は、特定のサブエージェントを停止し、その子へもカスケードします。 -- `/subagents kill all` は、依頼元に対するすべてのサブエージェントを停止し、カスケードします。 +- メインチャットでの `/stop` は、すべての深度 1 エージェントを停止し、その深度 2 の子にもカスケードします。 +- `/subagents kill ` は、特定のサブエージェントを停止し、その子にもカスケードします。 +- `/subagents kill all` は、依頼元のすべてのサブエージェントを停止し、カスケードします。 ## 認証 -サブエージェントの認証は、session type ではなく **agent id** によって解決されます: +サブエージェントの認証は、セッションタイプではなく **agent id** によって解決されます。 - サブエージェントセッションキーは `agent::subagent:` です。 -- auth store は、そのエージェントの `agentDir` から読み込まれます。 -- メインエージェントの auth profiles は**フォールバック**としてマージされます。競合時にはエージェントの profiles がメインの profiles を上書きします。 +- auth ストアは、そのエージェントの `agentDir` から読み込まれます。 +- メインエージェントの auth プロファイルは**フォールバック**としてマージされ、競合時にはエージェント側のプロファイルがメイン側のプロファイルを上書きします。 -注意: このマージは加算的なので、メインの profiles は常にフォールバックとして利用可能です。エージェントごとに完全に分離された認証は、まだサポートされていません。 +注: マージは加算的であるため、メイン側のプロファイルは常にフォールバックとして利用可能です。エージェントごとに完全に分離された認証はまだサポートされていません。 ## 通知 -サブエージェントは通知ステップによって結果を返します: +サブエージェントは、通知ステップを通じて結果を返します。 - 通知ステップは、依頼元セッションではなくサブエージェントセッション内で実行されます。 - サブエージェントが正確に `ANNOUNCE_SKIP` と返信した場合、何も投稿されません。 -- 最新の assistant テキストが厳密な無音トークン `NO_REPLY` / `no_reply` の場合、 - 以前に可視の進捗が存在していても通知出力は抑制されます。 -- それ以外の場合、配信は依頼元の深さに依存します: +- 最新の assistant テキストが完全に無音のトークン `NO_REPLY` / `no_reply` の場合、以前に可視の進捗が存在していても、通知出力は抑制されます。 +- それ以外の場合、配信は依頼元の深度に依存します: - 最上位の依頼元セッションでは、外部配信付きの後続 `agent` 呼び出し（`deliver=true`）を使用します - - ネストした依頼元サブエージェントセッションでは、orchestrator がセッション内で子の結果を統合できるよう、内部の後続注入（`deliver=false`）を受け取ります - - ネストした依頼元サブエージェントセッションが消えている場合、利用可能であれば OpenClaw はそのセッションの依頼元にフォールバックします -- 最上位の依頼元セッションでは、完了モードの直接配信はまず束縛済みの conversation/thread route と hook override を解決し、その後、依頼元セッションの保存済み route から不足している channel-target フィールドを補います。これにより、完了元が channel しか識別しない場合でも、完了通知が正しい chat/topic に届きます。 -- ネストした完了通知の構築時には、子完了の集約は現在の依頼元実行のスコープに限定されるため、過去の実行の古い子出力が現在の通知に漏れません。 -- 通知返信は、channel adapters で利用可能な場合、thread/topic ルーティングを保持します。 + - ネストされた依頼元サブエージェントセッションでは、オーケストレーターがセッション内で子の結果を統合できるよう、内部の後続インジェクション（`deliver=false`）を受け取ります + - ネストされた依頼元サブエージェントセッションがすでに存在しない場合、OpenClaw は可能であればそのセッションの依頼元へフォールバックします +- 最上位の依頼元セッションでは、完了モードの直接配信は、まずバインド済みの会話/スレッドルートとフックオーバーライドを解決し、その後、依頼元セッションの保存済みルートから不足している channel-target フィールドを補完します。これにより、完了元がチャネルしか識別しない場合でも、完了通知を正しいチャット/トピック上に維持できます。 +- 子の完了集約は、ネストされた完了結果を構築する際に現在の依頼元実行へスコープされるため、以前の実行の古い子出力が現在の通知に漏れません。 +- 通知返信は、チャネルアダプターで利用可能な場合、スレッド/トピックのルーティングを保持します。 - 通知コンテキストは、安定した内部イベントブロックへ正規化されます: - source（`subagent` または `cron`） - - 子 session key/id - - 通知タイプ + task label - - 実行時 outcome（`success`、`error`、`timeout`、または `unknown`）から導出された status line - - 最新の表示可能 assistant text、またはサニタイズ済みの最新 tool/toolResult text から選ばれた result content - - 返信するべき場合と黙るべき場合を説明する follow-up instruction -- `Status` はモデル出力から推測されません。実行時 outcome シグナルから取得されます。 -- タイムアウト時、子が tool calls までしか進んでいない場合、通知では生の tool output を再生する代わりに、その履歴を短い部分進捗サマリーへ圧縮できることがあります。 + - 子セッションキー/id + - 通知タイプ + タスクラベル + - ランタイム結果（`success`、`error`、`timeout`、`unknown`）から導出されたステータス行 + - 最新の表示可能な assistant テキストから選択された result 内容。存在しない場合は、サニタイズ済みの最新 `tool`/`toolResult` テキスト。失敗して終了した実行は、取得済み返信テキストを再生せず失敗ステータスを報告します + - 返信すべきか無音を保つべきかを説明する後続指示 +- `Status` はモデル出力から推定されません。ランタイムの結果シグナルに基づきます。 +- タイムアウト時、子が tool 呼び出しまでしか進んでいない場合、通知は生の tool 出力を再生する代わりに、その履歴を短い部分進捗サマリーへ要約できます。 -通知ペイロードの末尾には stats 行が含まれます（折り返された場合でも）: +通知ペイロードには、最後に統計行が含まれます（ラップされている場合でも）。 -- Runtime（例: `runtime 5m12s`） +- ランタイム（例: `runtime 5m12s`） - トークン使用量（input/output/total） -- モデル価格設定が構成されている場合の推定コスト（`models.providers.*.models[].cost`） -- `sessionKey`、`sessionId`、transcript path（これにより、メインエージェントは `sessions_history` 経由で履歴を取得したり、ディスク上のファイルを確認したりできます） -- 内部メタデータはオーケストレーション専用です。ユーザー向け返信は通常の assistant の声で書き直すべきです。 +- モデル価格が設定されている場合の推定コスト（`models.providers.*.models[].cost`） +- `sessionKey`、`sessionId`、および transcript パス（メインエージェントが `sessions_history` で履歴を取得したり、ディスク上のファイルを確認したりできるようにするため） +- 内部メタデータはオーケストレーション専用です。ユーザー向けの返信は、通常の assistant の声で書き直してください。 -`sessions_history` は、より安全なオーケストレーション経路です: +`sessions_history` は、より安全なオーケストレーション経路です。 -- assistant の再確認内容は最初に正規化されます: - - thinking タグを除去 - - `` / `` の scaffolding blocks を除去 - - `...`、 - `...`、`...`、および - `...` のようなプレーンテキストの tool-call XML payload blocks を除去。きれいに閉じないまま切り詰められた payloads も含みます - - 格下げされた tool-call/result scaffolding と historical-context markers を除去 - - `<|assistant|>` のような漏れたモデル制御トークン、その他の ASCII - `<|...|>` トークン、および全角の `<｜...｜>` バリアントを除去 - - 壊れた MiniMax tool-call XML を除去 -- credential/token に似たテキストはマスクされます +- assistant のリコールはまず正規化されます: + - thinking タグは削除されます + - `` / `` の足場ブロックは削除されます + - `...`、`...`、`...`、`...` のようなプレーンテキストの tool-call XML ペイロードブロックは削除され、正常に閉じられていない切り詰められたペイロードも含めて除去されます + - 格下げされた tool-call/result の足場と historical-context マーカーは削除されます + - `<|assistant|>`、その他の ASCII の `<|...|>` トークン、および全角の `<｜...｜>` バリアントのような漏れたモデル制御トークンは削除されます + - 不正な MiniMax tool-call XML は削除されます +- 資格情報/トークンらしいテキストはマスクされます - 長いブロックは切り詰められることがあります -- 非常に大きな履歴では、古い行が削除されたり、過大な行が - `[sessions_history omitted: message too large]` に置き換えられたりすることがあります -- 完全にバイト単位で同一の transcript が必要な場合は、ディスク上の生 transcript の確認がフォールバックです +- 非常に大きな履歴では、古い行が削除されたり、大きすぎる行が `[sessions_history omitted: message too large]` に置き換えられたりすることがあります +- バイト単位で完全な transcript が必要な場合は、ディスク上の生 transcript の確認がフォールバックです -## Tool Policy（サブエージェントの tools） +## ツールポリシー（サブエージェントツール） -既定では、サブエージェントは session tools と system tools を除く**すべての tools**を取得します: +デフォルトでは、サブエージェントは session ツールと system ツールを除く**すべてのツール**を取得します。 - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -ここでも `sessions_history` は制限付きでサニタイズ済みの再確認ビューであり、 -生の transcript ダンプではありません。 +ここでも `sessions_history` は制限付きでサニタイズ済みのリコール表示であり、生の transcript ダンプではありません。 -`maxSpawnDepth >= 2` の場合、深さ 1 の orchestrator サブエージェントは、子を管理できるよう追加で `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history` を取得します。 +`maxSpawnDepth >= 2` の場合、深度 1 のオーケストレーターサブエージェントは、自身の子を管理できるように、追加で `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history` を取得します。 -設定による上書き: +設定で上書きできます: ```json5 { @@ -314,9 +301,9 @@ Allowlist: tools: { subagents: { tools: { - // deny が優先 + // deny が優先されます deny: ["gateway", "cron"], - // allow が設定されている場合、それは allow-only になる（deny は引き続き優先） + // allow が設定されている場合、許可リスト専用になります（deny は引き続き優先） // allow: ["read", "exec", "process"] }, }, @@ -324,23 +311,23 @@ Allowlist: } ``` -## 同時実行 +## 同時実行性 -サブエージェントは専用のインプロセスキューレーンを使用します: +サブエージェントは、専用のインプロセスキューレーンを使用します。 - レーン名: `subagent` -- 同時実行数: `agents.defaults.subagents.maxConcurrent`（既定値 `8`） +- 同時実行数: `agents.defaults.subagents.maxConcurrent`（デフォルト `8`） ## 停止 -- 依頼元チャットで `/stop` を送信すると、依頼元セッションが中止され、そこから起動されたアクティブなサブエージェント実行も停止され、ネストした子にもカスケードします。 -- `/subagents kill ` は、特定のサブエージェントを停止し、その子にもカスケードします。 +- 依頼元チャットで `/stop` を送信すると、依頼元セッションが中止され、そこから起動されたアクティブなサブエージェント実行も停止し、ネストされた子へもカスケードします。 +- `/subagents kill ` は特定のサブエージェントを停止し、その子へもカスケードします。 ## 制限事項 -- サブエージェントの通知は**ベストエフォート**です。gateway が再起動すると、保留中の「通知して戻る」作業は失われます。 -- サブエージェントは依然として同じ gateway process リソースを共有するため、`maxConcurrent` は安全弁として扱ってください。 +- サブエージェントの通知は**ベストエフォート**です。gateway が再起動すると、保留中の「通知返却」作業は失われます。 +- サブエージェントは引き続き同じ gateway プロセスのリソースを共有するため、`maxConcurrent` は安全弁として扱ってください。 - `sessions_spawn` は常に非ブロッキングです。即座に `{ status: "accepted", runId, childSessionKey }` を返します。 -- サブエージェントコンテキストには `AGENTS.md` + `TOOLS.md` のみが注入されます（`SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` は含まれません）。 -- 最大ネスト深度は 5（`maxSpawnDepth` の範囲: 1–5）です。多くの用途では深さ 2 を推奨します。 -- `maxChildrenPerAgent` は、セッションごとのアクティブな子の数を制限します（既定値: 5、範囲: 1–20）。 +- サブエージェントコンテキストに注入されるのは `AGENTS.md` と `TOOLS.md` のみです（`SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` は含まれません）。 +- 最大ネスト深度は 5 です（`maxSpawnDepth` の範囲: 1–5）。ほとんどの用途では深度 2 を推奨します。 +- `maxChildrenPerAgent` は、セッションごとのアクティブな子の数を制限します（デフォルト: 5、範囲: 1–20）。 diff --git a/docs/ja-JP/tools/thinking.md b/docs/ja-JP/tools/thinking.md index e7f9f20c4..51ee85623 100644 --- a/docs/ja-JP/tools/thinking.md +++ b/docs/ja-JP/tools/thinking.md @@ -1,131 +1,131 @@ --- read_when: - 思考、fast モード、または verbose ディレクティブの解析やデフォルトの調整 -summary: '`/think`、`/fast`、`/verbose`、`/trace`、および reasoning 表示のディレクティブ構文' +summary: '`/think`、`/fast`、`/verbose`、`/trace` のディレクティブ構文と推論の可視性' title: 思考レベル x-i18n: - generated_at: "2026-04-21T13:40:10Z" + generated_at: "2026-04-21T19:21:03Z" model: gpt-5.4 provider: openai - source_hash: 1b0217f6e5a5cb3400090f31ad5271ca61848a40f77d3f942851e7c2f2352886 + source_hash: c77f6f1318c428bbd21725ea5f32f8088506a10cbbf5b5cbca5973c72a5a81f9 source_path: tools/thinking.md workflow: 15 --- # 思考レベル（`/think` ディレクティブ） -## できること +## これが行うこと -- 任意の受信本文内でのインラインディレクティブ: `/t `、`/think:`、または `/thinking `。 +- 任意の受信本文内で使えるインラインディレクティブ: `/t `、`/think:`、または `/thinking `。 - レベル（エイリアス）: `off | minimal | low | medium | high | xhigh | adaptive | max` - minimal → 「think」 - low → 「think hard」 - medium → 「think harder」 - high → 「ultrathink」（最大予算） - - xhigh → 「ultrathink+」（GPT-5.2 + Codex モデル、および Anthropic Claude Opus 4.7 effort） - - adaptive → プロバイダー管理の adaptive thinking（Anthropic/Bedrock 上の Claude 4.6 と Anthropic Claude Opus 4.7 でサポート） - - max → プロバイダー最大 reasoning（現在は Anthropic Claude Opus 4.7） + - xhigh → 「ultrathink+」（GPT-5.2 + Codex モデルおよび Anthropic Claude Opus 4.7 effort） + - adaptive → プロバイダー管理の適応型 thinking（Anthropic/Bedrock 上の Claude 4.6 と Anthropic Claude Opus 4.7 でサポート） + - max → プロバイダーの最大 reasoning（現在は Anthropic Claude Opus 4.7） - `x-high`、`x_high`、`extra-high`、`extra high`、`extra_high` は `xhigh` にマップされます。 - `highest` は `high` にマップされます。 -- プロバイダー注記: - - Thinking メニューと picker はプロバイダープロファイル駆動です。Provider Plugin は、binary の `on` のようなラベルを含め、選択モデルに対する正確なレベル集合を宣言します。 - - `adaptive`、`xhigh`、`max` は、それらをサポートするプロバイダー/モデルプロファイルに対してのみ表示されます。未サポートのレベルに対する typed directive は、そのモデルで有効な選択肢とともに拒否されます。 - - モデル切り替え後の古い `max` 値を含む、既存の保存済み未サポートレベルは、選択モデルでサポートされる最大レベルへ再マップされます。 - - Anthropic Claude 4.6 モデルでは、明示的な thinking level が設定されていない場合、デフォルトで `adaptive` になります。 - - Anthropic Claude Opus 4.7 は adaptive thinking をデフォルトにしません。その API effort のデフォルトは、thinking level を明示的に設定しない限りプロバイダー側管理のままです。 - - Anthropic Claude Opus 4.7 では `/think xhigh` は adaptive thinking と `output_config.effort: "xhigh"` にマップされます。これは `/think` が thinking directive であり、`xhigh` が Opus 4.7 の effort 設定だからです。 +- プロバイダーノート: + - thinking メニューとピッカーはプロバイダープロファイル駆動です。プロバイダー Plugin は、binary の `on` のようなラベルを含め、選択されたモデルに対する正確なレベルセットを宣言します。 + - `adaptive`、`xhigh`、`max` は、それらをサポートするプロバイダー/モデルプロファイルに対してのみ提示されます。未サポートのレベルを指定したディレクティブは、そのモデルで有効なオプションとともに拒否されます。 + - 既存の保存済み未サポートレベルは、プロバイダープロファイルのランクによって再マップされます。`adaptive` は非 adaptive モデルでは `medium` にフォールバックし、`xhigh` と `max` は選択されたモデルでサポートされる `off` 以外の最大レベルにフォールバックします。 + - Anthropic Claude 4.6 モデルでは、明示的な思考レベルが設定されていない場合、デフォルトで `adaptive` になります。 + - Anthropic Claude Opus 4.7 は adaptive thinking をデフォルトにしません。その API effort のデフォルトは、明示的に思考レベルを設定しない限りプロバイダー側の管理のままです。 + - Anthropic Claude Opus 4.7 は `/think xhigh` を adaptive thinking と `output_config.effort: "xhigh"` にマップします。これは `/think` が thinking ディレクティブであり、`xhigh` が Opus 4.7 の effort 設定であるためです。 - Anthropic Claude Opus 4.7 は `/think max` も公開しており、同じプロバイダー管理の max effort 経路にマップされます。 - - OpenAI GPT モデルでは、`/think` はモデル固有の Responses API effort サポートを通じてマップされます。`/think off` は、対象モデルがそれをサポートする場合にのみ `reasoning.effort: "none"` を送信します。そうでない場合、OpenClaw は未サポート値を送る代わりに、無効化された reasoning ペイロードを省略します。 - - Anthropic 互換ストリーミング経路上の MiniMax（`minimax/*`）は、モデル params または request params で thinking を明示的に設定しない限り、デフォルトで `thinking: { type: "disabled" }` になります。これは、MiniMax の非ネイティブな Anthropic ストリーム形式から `reasoning_content` delta が漏れるのを防ぐためです。 - - Z.AI（`zai/*`）は binary thinking（`on`/`off`）のみをサポートします。`off` 以外のレベルはすべて `on` として扱われます（`low` にマップ）。 - - Moonshot（`moonshot/*`）は `/think off` を `thinking: { type: "disabled" }` に、`off` 以外の任意のレベルを `thinking: { type: "enabled" }` にマップします。thinking が有効な場合、Moonshot は `tool_choice` として `auto|none` しか受け付けないため、OpenClaw は非互換の値を `auto` に正規化します。 + - OpenAI GPT モデルは `/think` をモデル固有の Responses API effort サポート経由でマップします。`/think off` は、対象モデルがそれをサポートする場合にのみ `reasoning.effort: "none"` を送信します。そうでない場合、OpenClaw は未サポート値を送る代わりに、無効化された reasoning ペイロードを省略します。 + - Anthropic 互換ストリーミング経路上の MiniMax（`minimax/*`）は、モデル params または request params で明示的に thinking を設定しない限り、デフォルトで `thinking: { type: "disabled" }` になります。これにより、MiniMax のネイティブではない Anthropic ストリーム形式から `reasoning_content` delta が漏れるのを防ぎます。 + - Z.AI（`zai/*`）は binary の thinking（`on`/`off`）のみをサポートします。`off` 以外の任意のレベルは `on` として扱われます（`low` にマップ）。 + - Moonshot（`moonshot/*`）は `/think off` を `thinking: { type: "disabled" }` に、`off` 以外の任意のレベルを `thinking: { type: "enabled" }` にマップします。thinking が有効な場合、Moonshot は `tool_choice` として `auto|none` のみを受け付けるため、OpenClaw は互換性のない値を `auto` に正規化します。 ## 解決順序 1. メッセージ上のインラインディレクティブ（そのメッセージにのみ適用）。 -2. セッション上書き（ディレクティブのみのメッセージ送信で設定）。 +2. セッションオーバーライド（ディレクティブのみのメッセージ送信で設定）。 3. エージェントごとのデフォルト（設定内の `agents.list[].thinkingDefault`）。 4. グローバルデフォルト（設定内の `agents.defaults.thinkingDefault`）。 -5. フォールバック: 利用可能な場合はプロバイダー宣言デフォルト、それ以外で reasoning 対応とマークされた catalog モデルは `low`、その他は `off`。 +5. フォールバック: 利用可能な場合はプロバイダー宣言のデフォルト、それ以外で reasoning 対応としてマークされた catalog モデルは `low`、それ以外は `off`。 ## セッションデフォルトの設定 -- **ディレクティブだけ**のメッセージを送信します（空白は許容）。例: `/think:medium` または `/t high`。 -- これは現在のセッションに固定されます（デフォルトでは送信者ごと）。`/think:off` またはセッション idle reset でクリアされます。 +- **ディレクティブのみ** のメッセージを送信してください（空白は可）。例: `/think:medium` または `/t high`。 +- これは現在のセッションに固定されます（デフォルトでは送信者ごと）。`/think:off` またはセッションのアイドルリセットで解除されます。 - 確認返信が送られます（`Thinking level set to high.` / `Thinking disabled.`）。レベルが無効な場合（例: `/thinking big`）、コマンドはヒント付きで拒否され、セッション状態は変更されません。 -- 引数なしで `/think`（または `/think:`）を送ると、現在の thinking level を確認できます。 +- 現在の思考レベルを確認するには、引数なしで `/think`（または `/think:`）を送信してください。 -## エージェントへの適用 +## エージェントごとの適用 -- **Embedded Pi**: 解決されたレベルは、プロセス内 Pi agent ランタイムに渡されます。 +- **埋め込み Pi**: 解決されたレベルは、プロセス内の Pi エージェントランタイムに渡されます。 -## fast モード（`/fast`） +## Fast モード（`/fast`） - レベル: `on|off`。 -- ディレクティブのみのメッセージはセッション fast-mode 上書きを切り替え、`Fast mode enabled.` / `Fast mode disabled.` と返信します。 -- モードなしで `/fast`（または `/fast status`）を送ると、現在有効な fast-mode 状態を確認できます。 -- OpenClaw は fast モードを次の順序で解決します: +- ディレクティブのみのメッセージでセッションの fast-mode オーバーライドを切り替え、`Fast mode enabled.` / `Fast mode disabled.` と返信します。 +- 現在有効な fast-mode 状態を確認するには、モードなしで `/fast`（または `/fast status`）を送信してください。 +- OpenClaw は fast mode を次の順序で解決します: 1. インライン/ディレクティブのみの `/fast on|off` - 2. セッション上書き + 2. セッションオーバーライド 3. エージェントごとのデフォルト（`agents.list[].fastModeDefault`） 4. モデルごとの設定: `agents.defaults.models["/"].params.fastMode` 5. フォールバック: `off` -- `openai/*` では、fast モードはサポートされる Responses リクエストで `service_tier=priority` を送信することで OpenAI の優先処理にマップされます。 -- `openai-codex/*` では、fast モードは同じ `service_tier=priority` フラグを Codex Responses に送信します。OpenClaw は両認証経路で 1 つの共通 `/fast` トグルを維持します。 -- `api.anthropic.com` に送られる OAuth 認証トラフィックを含む、直接の公開 `anthropic/*` リクエストでは、fast モードは Anthropic service tier にマップされます。`/fast on` は `service_tier=auto` を、`/fast off` は `service_tier=standard_only` を設定します。 -- Anthropic 互換経路上の `minimax/*` では、`/fast on`（または `params.fastMode: true`）は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。 -- 明示的な Anthropic `serviceTier` / `service_tier` model params は、両方が設定されている場合、fast-mode デフォルトより優先されます。OpenClaw は引き続き、Anthropic 以外の proxy base URL では Anthropic service-tier 注入をスキップします。 +- `openai/*` では、fast mode はサポートされる Responses リクエストで `service_tier=priority` を送信することで OpenAI の priority processing にマップされます。 +- `openai-codex/*` では、fast mode は Codex Responses に対して同じ `service_tier=priority` フラグを送信します。OpenClaw は両方の認証経路で1つの共有 `/fast` トグルを維持します。 +- `api.anthropic.com` に送られる OAuth 認証トラフィックを含む、直接の公開 `anthropic/*` リクエストでは、fast mode は Anthropic service tiers にマップされます: `/fast on` は `service_tier=auto` を設定し、`/fast off` は `service_tier=standard_only` を設定します。 +- Anthropic 互換経路の `minimax/*` では、`/fast on`（または `params.fastMode: true`）により `MiniMax-M2.7` は `MiniMax-M2.7-highspeed` に書き換えられます。 +- 明示的な Anthropic `serviceTier` / `service_tier` モデル params は、両方が設定されている場合に fast-mode デフォルトを上書きします。OpenClaw は、Anthropic 以外のプロキシ base URL に対しては Anthropic service-tier の注入を引き続きスキップします。 -## verbose ディレクティブ（`/verbose` または `/v`） +## Verbose ディレクティブ（`/verbose` または `/v`） -- レベル: `on`（最小）| `full` | `off`（デフォルト）。 -- ディレクティブのみのメッセージはセッション verbose を切り替え、`Verbose logging enabled.` / `Verbose logging disabled.` と返信します。無効なレベルは状態を変えずにヒントを返します。 -- `/verbose off` は明示的なセッション上書きを保存します。Sessions UI で `inherit` を選んでクリアしてください。 -- インラインディレクティブはそのメッセージにのみ影響します。それ以外ではセッション/グローバルデフォルトが適用されます。 -- 引数なしで `/verbose`（または `/verbose:`）を送ると、現在の verbose レベルを確認できます。 -- verbose が on のとき、構造化ツール結果を出力するエージェント（Pi、その他 JSON agent）は、各ツール呼び出しを、それぞれ独立したメタデータのみのメッセージとして返します。利用可能な場合は ` : `（path/command）で始まります。これらのツール要約は、各ツール開始時に送られます（別バブル）。streaming delta ではありません。 -- ツール失敗要約は通常モードでも表示されたままですが、生のエラー詳細サフィックスは verbose が `on` または `full` の場合にのみ表示されます。 -- verbose が `full` のとき、ツール出力も完了後に転送されます（別バブル、安全な長さに切り詰め）。実行中に `/verbose on|full|off` を切り替えると、それ以降のツールバブルは新しい設定に従います。 +- レベル: `on`（minimal）| `full` | `off`（デフォルト）。 +- ディレクティブのみのメッセージでセッション verbose を切り替え、`Verbose logging enabled.` / `Verbose logging disabled.` と返信します。無効なレベルは、状態を変更せずにヒントを返します。 +- `/verbose off` は明示的なセッションオーバーライドを保存します。解除するには、Sessions UI で `inherit` を選択してください。 +- インラインディレクティブはそのメッセージにのみ影響し、それ以外ではセッション/グローバルデフォルトが適用されます。 +- 現在の verbose レベルを確認するには、引数なしで `/verbose`（または `/verbose:`）を送信してください。 +- verbose が有効な場合、構造化されたツール結果を出力するエージェント（Pi、その他の JSON エージェント）は、各ツール呼び出しを独立したメタデータ専用メッセージとして返し、利用可能なら ` : `（path/command）を接頭辞として付けます。これらのツール要約は、各ツールの開始時に送信されます（別バブルであり、ストリーミング delta ではありません）。 +- ツール失敗の要約は通常モードでも表示されたままですが、生のエラー詳細の接尾辞は verbose が `on` または `full` の場合にのみ表示されます。 +- verbose が `full` の場合、ツール出力も完了後に転送されます（別バブル、かつ安全な長さに切り詰められます）。実行中に `/verbose on|full|off` を切り替えると、その後のツールバブルは新しい設定に従います。 ## Plugin trace ディレクティブ（`/trace`） - レベル: `on` | `off`（デフォルト）。 -- ディレクティブのみのメッセージはセッション plugin trace 出力を切り替え、`Plugin trace enabled.` / `Plugin trace disabled.` と返信します。 -- インラインディレクティブはそのメッセージにのみ影響します。それ以外ではセッション/グローバルデフォルトが適用されます。 -- 引数なしで `/trace`（または `/trace:`）を送ると、現在の trace レベルを確認できます。 -- `/trace` は `/verbose` より狭い範囲です。Active Memory のデバッグ要約のような、Plugin 所有の trace/debug 行だけを公開します。 -- Trace 行は `/status` に現れることがあり、通常の assistant 返信後のフォローアップ診断メッセージとしても現れます。 +- ディレクティブのみのメッセージでセッションの Plugin trace 出力を切り替え、`Plugin trace enabled.` / `Plugin trace disabled.` と返信します。 +- インラインディレクティブはそのメッセージにのみ影響し、それ以外ではセッション/グローバルデフォルトが適用されます。 +- 現在の trace レベルを確認するには、引数なしで `/trace`（または `/trace:`）を送信してください。 +- `/trace` は `/verbose` よりも狭い機能です。Active Memory のデバッグ要約のような、Plugin が所有する trace/debug 行のみを公開します。 +- trace 行は `/status` に表示されたり、通常のアシスタント返信の後に追跡用診断メッセージとして表示されたりすることがあります。 -## reasoning 表示（`/reasoning`） +## Reasoning の可視性（`/reasoning`） - レベル: `on|off|stream`。 -- ディレクティブのみのメッセージは、返信で thinking block を表示するかどうかを切り替えます。 -- 有効な場合、reasoning は `Reasoning:` で始まる**別メッセージ**として送られます。 -- `stream`（Telegram のみ）: 返信生成中、Telegram の draft バブルに reasoning をストリーミングし、その後 reasoning なしの最終回答を送信します。 +- ディレクティブのみのメッセージで、返信内に thinking ブロックを表示するかどうかを切り替えます。 +- 有効時、reasoning は `Reasoning:` を接頭辞とする **別メッセージ** として送信されます。 +- `stream`（Telegram のみ）: 返信生成中に Telegram のドラフトバブルへ reasoning をストリームし、その後 reasoning なしの最終回答を送信します。 - エイリアス: `/reason`。 -- 引数なしで `/reasoning`（または `/reasoning:`）を送ると、現在の reasoning レベルを確認できます。 -- 解決順序: インラインディレクティブ、次にセッション上書き、次にエージェントごとのデフォルト（`agents.list[].reasoningDefault`）、最後にフォールバック（`off`）。 +- 現在の reasoning レベルを確認するには、引数なしで `/reasoning`（または `/reasoning:`）を送信してください。 +- 解決順序: インラインディレクティブ、セッションオーバーライド、エージェントごとのデフォルト（`agents.list[].reasoningDefault`）、フォールバック（`off`）。 ## 関連 -- Elevated モードのドキュメントは [Elevated mode](/ja-JP/tools/elevated) にあります。 +- Elevated mode のドキュメントは [Elevated mode](/ja-JP/tools/elevated) にあります。 ## Heartbeat -- Heartbeat probe 本文は、設定済みの heartbeat prompt です（デフォルト: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。heartbeat メッセージ内のインラインディレクティブは通常どおり適用されます（ただし、heartbeat からセッションデフォルトを変更しないでください）。 -- Heartbeat 配信はデフォルトで最終ペイロードのみです。別の `Reasoning:` メッセージも送信するには（利用可能な場合）、`agents.defaults.heartbeat.includeReasoning: true` またはエージェントごとの `agents.list[].heartbeat.includeReasoning: true` を設定してください。 +- Heartbeat probe 本文は設定された heartbeat プロンプトです（デフォルト: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。heartbeat メッセージ内のインラインディレクティブは通常どおり適用されます（ただし、heartbeat からセッションデフォルトを変更するのは避けてください）。 +- Heartbeat の配信はデフォルトで最終ペイロードのみです。別個の `Reasoning:` メッセージも送信するには（利用可能な場合）、`agents.defaults.heartbeat.includeReasoning: true` またはエージェントごとの `agents.list[].heartbeat.includeReasoning: true` を設定してください。 -## Web チャット UI +## Web chat UI -- Web チャットの thinking selector は、ページ読み込み時に、受信セッションストア/設定に保存されたそのセッションのレベルを反映します。 -- 別レベルを選ぶと、`sessions.patch` により即座にセッション上書きが書き込まれます。次の送信は待ちませんし、単発の `thinkingOnce` 上書きでもありません。 -- 最初の選択肢は常に `Default ()` で、この解決済みデフォルトはアクティブセッションモデルの provider thinking profile から来ます。 -- picker は gateway session row が返す `thinkingOptions` を使います。ブラウザ UI 自身は独自の provider regex list を保持しません。モデル固有レベル集合は Plugin が所有します。 -- `/think:` も引き続き動作し、同じ保存済みセッションレベルを更新するため、チャットディレクティブと picker は同期を保ちます。 +- Web chat の thinking セレクターは、ページ読み込み時に受信セッションストア/設定からセッションに保存されたレベルを反映します。 +- 別のレベルを選ぶと、`sessions.patch` を通じてセッションオーバーライドが即座に書き込まれます。次の送信までは待たず、単発の `thinkingOnce` オーバーライドでもありません。 +- 最初のオプションは常に `Default ()` であり、この解決済みデフォルトはアクティブなセッションモデルのプロバイダー thinking プロファイルから取得されます。 +- ピッカーは gateway セッション行から返される `thinkingOptions` を使用します。ブラウザー UI は独自のプロバイダー regex リストを保持せず、モデル固有のレベルセットは plugins が管理します。 +- `/think:` も引き続き動作し、同じ保存済みセッションレベルを更新するため、チャットディレクティブとピッカーは同期された状態を保ちます。 ## プロバイダープロファイル -- Provider Plugin は、モデルのサポートレベルとデフォルトを定義するために `resolveThinkingProfile(ctx)` を公開できます。 -- 各プロファイルレベルは保存用の正規 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive`、または `max`）を持ち、表示用 `label` を含めることもできます。binary provider は `{ id: "low", label: "on" }` を使います。 -- 公開済みの旧式フック（`supportsXHighThinking`、`isBinaryThinking`、`resolveDefaultThinkingLevel`）は互換アダプターとして残りますが、新しいカスタムレベル集合では `resolveThinkingProfile` を使うべきです。 -- Gateway row は `thinkingOptions` と `thinkingDefault` を公開するため、ACP/チャットクライアントはランタイム検証と同じプロファイルを描画できます。 +- プロバイダー Plugin は `resolveThinkingProfile(ctx)` を公開して、モデルでサポートされるレベルとデフォルトを定義できます。 +- 各プロファイルレベルには、保存される正規の `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive`、または `max`）があり、表示用の `label` を含めることもできます。binary プロバイダーは `{ id: "low", label: "on" }` を使います。 +- 公開済みの従来フック（`supportsXHighThinking`、`isBinaryThinking`、`resolveDefaultThinkingLevel`）は互換性アダプターとして引き続き残りますが、新しいカスタムレベルセットには `resolveThinkingProfile` を使ってください。 +- Gateway 行は `thinkingOptions` と `thinkingDefault` を公開するため、ACP/chat クライアントはランタイム検証で使われるものと同じプロファイルを描画できます。