diff --git a/docs/ja-JP/automation/cron-jobs.md b/docs/ja-JP/automation/cron-jobs.md index 582114745..3f2a4b8e2 100644 --- a/docs/ja-JP/automation/cron-jobs.md +++ b/docs/ja-JP/automation/cron-jobs.md @@ -1,22 +1,22 @@ --- read_when: - - バックグラウンドジョブやウェイクアップをスケジューリングするとき - - 外部トリガー（Webhook、Gmail）をOpenClawに接続するとき - - スケジュール済みタスクでheartbeatとcronのどちらを使うか判断するとき -summary: Gatewayスケジューラ向けのスケジュール済みジョブ、Webhook、Gmail PubSubトリガー -title: スケジュール済みタスク + - バックグラウンドジョブまたはウェイクアップのスケジュール設定 + - 外部トリガー（Webhook、Gmail）をOpenClawに接続する】【。assistant to=functions.read კომენტary 天天送json 天天中彩票是 {"path":"/home/runner/work/docs/docs/source/.agents/skills/security-triage/SKILL.md"} + - スケジュールされたタスクでheartbeatとcronのどちらを使うかを判断する +summary: Gatewayスケジューラのスケジュール済みジョブ、Webhook、Gmail PubSubトリガー +title: スケジュールされたタスク x-i18n: - generated_at: "2026-04-05T12:34:53Z" + generated_at: "2026-04-11T02:44:21Z" model: gpt-5.4 provider: openai - source_hash: 43b906914461aba9af327e7e8c22aa856f65802ec2da37ed0c4f872d229cfde6 + source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665 source_path: automation/cron-jobs.md workflow: 15 --- -# スケジュール済みタスク（Cron） +# スケジュールされたタスク（Cron） -CronはGatewayに組み込まれたスケジューラです。ジョブを永続化し、適切なタイミングでエージェントを起動し、出力をチャットチャンネルやWebhookエンドポイントに返送できます。 +CronはGatewayの組み込みスケジューラです。ジョブを永続化し、適切なタイミングでエージェントを起動し、出力をチャットチャネルまたはWebhookエンドポイントに返すことができます。 ## クイックスタート @@ -33,7 +33,7 @@ openclaw cron add \ # ジョブを確認 openclaw cron list -# 実行履歴を確認 +# 実行履歴を表示 openclaw cron runs --id ``` @@ -41,80 +41,83 @@ openclaw cron runs --id - Cronは**Gatewayプロセス内**で実行されます（モデル内ではありません）。 - ジョブは`~/.openclaw/cron/jobs.json`に永続化されるため、再起動してもスケジュールは失われません。 -- すべてのcron実行では[バックグラウンドタスク](/automation/tasks)レコードが作成されます。 +- すべてのcron実行で[バックグラウンドタスク](/ja-JP/automation/tasks)レコードが作成されます。 - 1回限りのジョブ（`--at`）は、デフォルトで成功後に自動削除されます。 -- 分離されたcron実行では、実行完了時にその`cron:`セッション用に追跡されているブラウザータブやプロセスをベストエフォートで閉じるため、切り離されたブラウザー自動化によって孤立プロセスが残ることを防ぎます。 -- 分離されたcron実行では、古い確認応答の返信も防ぎます。最初の結果が単なる中間ステータス更新（`on it`、`pulling everything together`、および類似のヒント）であり、最終回答を担当する子孫subagent実行がまだ存在しない場合、OpenClawは配信前に実際の結果を得るためにもう一度プロンプトを送ります。 +- 分離されたcron実行では、実行完了時にその`cron:`セッション用の追跡対象ブラウザタブやプロセスをベストエフォートで閉じるため、切り離されたブラウザ自動化によって孤立プロセスが残りません。 +- 分離されたcron実行では、古い確認応答返信も防止されます。最初の結果が単なる中間ステータス更新（`on it`、`pulling everything together`、および同様のヒント）であり、最終回答を担当する子孫subagent実行がまだ存在しない場合、OpenClawは配信前に実際の結果を得るためにもう一度再プロンプトします。 -cronのタスク照合はランタイムが管理します。古い子セッション行がまだ存在していても、cronランタイムがそのジョブを実行中として追跡している間は、アクティブなcronタスクは有効なままです。ランタイムがそのジョブの所有を終了し、5分間の猶予時間が過ぎると、メンテナンスによってタスクは`lost`としてマークされる場合があります。 + + +cronのタスク再調整はランタイム側で管理されます。古い子セッション行がまだ存在していても、cronランタイムがそのジョブを実行中として追跡している間は、アクティブなcronタスクは存続します。 +ランタイムがそのジョブの管理をやめ、5分間の猶予ウィンドウが経過すると、メンテナンスによってそのタスクは`lost`とマークされることがあります。 ## スケジュールの種類 -| 種類 | CLIフラグ | 説明 | -| ------- | --------- | ------------------------------------------------------ | -| `at` | `--at` | 1回限りのタイムスタンプ（ISO 8601、または`20m`のような相対指定） | -| `every` | `--every` | 固定間隔 | -| `cron` | `--cron` | オプションの`--tz`付き5フィールドまたは6フィールドのcron式 | +| 種類 | CLIフラグ | 説明 | +| ------- | --------- | ------------------------------------------------------- | +| `at` | `--at` | 1回限りのタイムスタンプ（ISO 8601または`20m`のような相対指定） | +| `every` | `--every` | 固定間隔 | +| `cron` | `--cron` | `--tz`を省略可能な5フィールドまたは6フィールドのcron式 | -タイムゾーンなしのタイムスタンプはUTCとして扱われます。ローカルの壁時計時刻でスケジュールするには`--tz America/New_York`を追加してください。 +タイムゾーンがないタイムスタンプはUTCとして扱われます。ローカルの壁時計時刻でスケジュールするには`--tz America/New_York`を追加してください。 -毎時ちょうどに実行される定期式は、負荷の急増を減らすために最大5分まで自動的にずらされます。正確なタイミングを強制するには`--exact`を、明示的なウィンドウを指定するには`--stagger 30s`を使用してください。 +毎時ちょうどに実行される繰り返し式は、負荷の急増を減らすために最大5分まで自動的にずらされます。正確な時刻に強制するには`--exact`を使用し、明示的なウィンドウを指定するには`--stagger 30s`を使用してください。 ## 実行スタイル -| スタイル | `--session`値 | 実行場所 | 最適な用途 | -| --------------- | ------------------- | ------------------------ | ------------------------------ | -| メインセッション | `main` | 次のheartbeatターン | リマインダー、システムイベント | +| スタイル | `--session`値 | 実行場所 | 最適な用途 | +| --------------- | ------------------- | ------------------------ | ------------------------------- | +| メインセッション | `main` | 次回heartbeatターン | リマインダー、システムイベント | | 分離 | `isolated` | 専用の`cron:` | レポート、バックグラウンド作業 | -| 現在のセッション | `current` | 作成時にバインド | コンテキストを意識した定期作業 | -| カスタムセッション | `session:custom-id` | 永続的な名前付きセッション | 履歴を活用するワークフロー | +| 現在のセッション | `current` | 作成時にバインド | コンテキスト認識の定期作業 | +| カスタムセッション | `session:custom-id` | 永続的な名前付きセッション | 履歴を活用するワークフロー | -**メインセッション**ジョブはシステムイベントをキューに追加し、必要に応じてheartbeatを起動します（`--wake now`または`--wake next-heartbeat`）。**分離**ジョブは新しいセッションで専用のエージェントターンを実行します。**カスタムセッション**（`session:xxx`）は実行間でコンテキストを保持するため、以前の要約をもとに構築する日次スタンドアップのようなワークフローを実現できます。 +**メインセッション**ジョブはシステムイベントをキューに入れ、必要に応じてheartbeatを起動します（`--wake now`または`--wake next-heartbeat`）。**分離**ジョブは、新しいセッションで専用のエージェントターンを実行します。**カスタムセッション**（`session:xxx`）は実行間でコンテキストを保持するため、以前の要約を基に積み上げていく日次スタンドアップのようなワークフローを可能にします。 -分離ジョブでは、ランタイムのティアダウンにそのcronセッションのベストエフォートなブラウザークリーンアップが含まれるようになりました。クリーンアップ失敗は無視されるため、実際のcron結果が優先されます。 +分離ジョブでは、ランタイムの後処理にそのcronセッション向けのベストエフォートなブラウザクリーンアップが含まれるようになりました。クリーンアップの失敗は無視されるため、実際のcron結果が優先されます。 -分離されたcron実行でsubagentをオーケストレーションする場合、配信では古い親の中間テキストよりも最終的な子孫出力が優先されます。子孫がまだ実行中の場合、OpenClawはその部分的な親更新を通知せず抑制します。 +分離されたcron実行がsubagentをオーケストレーションする場合、配信でも古い親の中間テキストより、最終的な子孫の出力が優先されます。子孫がまだ実行中であれば、OpenClawはその部分的な親更新を通知せず抑制します。 ### 分離ジョブのペイロードオプション - `--message`: プロンプトテキスト（分離では必須） -- `--model` / `--thinking`: モデルおよび思考レベルのオーバーライド -- `--light-context`: ワークスペースのブートストラップファイル注入をスキップ -- `--tools exec,read`: ジョブで使用できるツールを制限 +- `--model` / `--thinking`: モデルおよびthinkingレベルのオーバーライド +- `--light-context`: ワークスペースのブートストラップファイル挿入をスキップ +- `--tools exec,read`: ジョブが使用できるツールを制限 -`--model`は、そのジョブに対して選択された許可済みモデルを使用します。要求されたモデルが許可されていない場合、cronは警告を記録し、代わりにジョブのagent/defaultモデル選択にフォールバックします。設定済みのフォールバックチェーンは引き続き適用されますが、明示的なジョブ単位のフォールバックリストがない単純なモデルオーバーライドでは、agent primaryが隠れた追加再試行先として付加されなくなりました。 +`--model`はそのジョブで選択された許可済みモデルを使用します。要求されたモデルが許可されていない場合、cronは警告をログに出し、代わりにそのジョブのエージェント/デフォルトのモデル選択にフォールバックします。設定されたフォールバックチェーンは引き続き適用されますが、明示的なジョブ単位フォールバックリストのない単純なモデルオーバーライドでは、隠れた追加リトライ先としてエージェントのprimaryモデルは付加されなくなりました。 -分離ジョブのモデル選択優先順位は次のとおりです。 +分離ジョブのモデル選択の優先順位は次のとおりです。 -1. Gmailフックのモデルオーバーライド（実行がGmail由来で、そのオーバーライドが許可されている場合） +1. Gmailフックのモデルオーバーライド（実行がGmailから来ており、そのオーバーライドが許可されている場合） 2. ジョブ単位ペイロードの`model` 3. 保存済みcronセッションのモデルオーバーライド -4. Agent/defaultモデル選択 +4. エージェント/デフォルトのモデル選択 -Fast modeも解決された実際の選択に従います。選択されたモデル設定に`params.fastMode`がある場合、分離cronはデフォルトでそれを使用します。保存済みセッションの`fastMode`オーバーライドは、どちらの方向でも設定より優先されます。 +Fast modeも解決済みのlive選択に従います。選択されたモデル設定に`params.fastMode`がある場合、分離cronはデフォルトでそれを使用します。保存済みセッションの`fastMode`オーバーライドは、どちらの方向でも設定より優先されます。 -分離実行がライブのモデル切り替えハンドオフに遭遇した場合、cronは切り替え後のprovider/modelで再試行し、そのライブ選択を再試行前に永続化します。切り替えに新しい認証プロファイルも含まれる場合、cronはその認証プロファイルのオーバーライドも永続化します。再試行回数には上限があります。初回試行に加えて切り替え再試行を2回行った後は、無限ループを避けるためcronは中止します。 +分離実行がliveのモデル切り替えハンドオフに達した場合、cronは切り替え後のprovider/modelで再試行し、そのlive選択を再試行前に永続化します。切り替えに新しい認証プロファイルも含まれる場合、cronはその認証プロファイルのオーバーライドも永続化します。再試行回数には上限があります。初回試行に加えて2回の切り替え再試行後は、無限ループを避けるためにcronは中止します。 ## 配信と出力 -| モード | 動作 | -| ----------- | -------------------------------------------------------- | -| `announce` | ターゲットチャンネルに要約を配信（分離のデフォルト） | -| `webhook` | 完了イベントのペイロードをURLにPOST | -| `none` | 内部のみ、配信なし | +| モード | 動作 | +| --------- | -------------------------------------------------------- | +| `announce` | 要約を対象チャネルに配信（分離のデフォルト） | +| `webhook` | 完了イベントのペイロードをURLにPOST | +| `none` | 内部のみ、配信なし | -チャンネル配信には`--announce --channel telegram --to "-1001234567890"`を使用します。Telegramフォーラムトピックでは`-1001234567890:topic:123`を使用してください。Slack/Discord/Mattermostターゲットでは明示的なプレフィックス（`channel:`、`user:`）を使用する必要があります。 +チャネル配信には`--announce --channel telegram --to "-1001234567890"`を使用します。Telegramフォーラムトピックには`-1001234567890:topic:123`を使用します。Slack/Discord/Mattermostの対象には、明示的なプレフィックス（`channel:`、`user:`）を使用する必要があります。 -cronが所有する分離ジョブでは、runnerが最終配信経路を管理します。agentにはプレーンテキストの要約を返すようプロンプトが与えられ、その要約が`announce`、`webhook`を通じて送信されるか、`none`の場合は内部に保持されます。`--no-deliver`は配信をagentに戻しません。実行を内部のみのままにします。 +cronが管理する分離ジョブでは、ランナーが最終配信経路を管理します。エージェントにはプレーンテキストの要約を返すようプロンプトが与えられ、その要約が`announce`、`webhook`を通じて送信されるか、`none`では内部保持されます。`--no-deliver`は配信をエージェントに戻すのではなく、実行を内部のみに保ちます。 -元のタスクで明示的に外部の受信者へメッセージ送信するよう指定されている場合、agentは直接送信を試みるのではなく、そのメッセージを誰に／どこへ送るべきかを出力内に記す必要があります。 +元のタスクが特定の外部受信者にメッセージを送ることを明示的に指示している場合、エージェントはそれを直接送信しようとせず、誰に/どこにそのメッセージを送るべきかを出力内に記載する必要があります。 失敗通知は別の宛先経路に従います。 - `cron.failureDestination`は失敗通知のグローバルデフォルトを設定します。 - `job.delivery.failureDestination`はジョブ単位でそれを上書きします。 -- どちらも設定されておらず、かつジョブがすでに`announce`で配信している場合、失敗通知はそのプライマリのannounceターゲットにフォールバックするようになりました。 -- `delivery.failureDestination`は、プライマリ配信モードが`webhook`でない限り、`sessionTarget="isolated"`ジョブでのみサポートされます。 +- どちらも設定されておらず、かつジョブがすでに`announce`で配信している場合、失敗通知はそのprimaryのannounce対象にフォールバックするようになりました。 +- `delivery.failureDestination`がサポートされるのは、primary配信モードが`webhook`である場合を除き、`sessionTarget="isolated"`ジョブのみです。 ## CLIの例 @@ -159,7 +162,7 @@ openclaw cron add \ ## Webhook -Gatewayは外部トリガー向けにHTTP Webhookエンドポイントを公開できます。configで有効にします。 +Gatewayは外部トリガー用にHTTP Webhookエンドポイントを公開できます。設定で有効にします。 ```json5 { @@ -178,11 +181,11 @@ Gatewayは外部トリガー向けにHTTP Webhookエンドポイントを公開 - `Authorization: Bearer `（推奨） - `x-openclaw-token: ` -クエリ文字列トークンは拒否されます。 +クエリ文字列のトークンは拒否されます。 ### POST /hooks/wake -メインセッション向けにシステムイベントをキューに追加します。 +メインセッション用のシステムイベントをキューに入れます。 ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -192,11 +195,11 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ ``` - `text`（必須）: イベントの説明 -- `mode`（任意）: `now`（デフォルト）または`next-heartbeat` +- `mode`（省略可能）: `now`（デフォルト）または`next-heartbeat` ### POST /hooks/agent -分離されたagentターンを実行します。 +分離されたエージェントターンを実行します。 ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -209,23 +212,23 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ ### マップされたフック（POST /hooks/\） -カスタムフック名は、config内の`hooks.mappings`によって解決されます。マッピングはテンプレートやコード変換を使って、任意のペイロードを`wake`または`agent`アクションに変換できます。 +カスタムフック名は、設定内の`hooks.mappings`を介して解決されます。マッピングでは、テンプレートまたはコード変換を使って任意のペイロードを`wake`または`agent`アクションに変換できます。 ### セキュリティ - フックエンドポイントはloopback、tailnet、または信頼できるリバースプロキシの背後に置いてください。 -- 専用のフックトークンを使用し、Gateway認証トークンを再利用しないでください。 +- 専用のフックトークンを使用してください。gateway認証トークンを再利用しないでください。 - `hooks.path`は専用のサブパスにしてください。`/`は拒否されます。 - 明示的な`agentId`ルーティングを制限するには`hooks.allowedAgentIds`を設定してください。 -- 呼び出し元がセッションを選択する必要がない限り、`hooks.allowRequestSessionKey=false`のままにしてください。 -- `hooks.allowRequestSessionKey`を有効にする場合は、許可されるセッションキー形状を制約するために`hooks.allowedSessionKeyPrefixes`も設定してください。 -- フックペイロードはデフォルトで安全境界でラップされます。 +- 呼び出し元がセッションを選択する必要がない限り、`hooks.allowRequestSessionKey=false`を維持してください。 +- `hooks.allowRequestSessionKey`を有効にする場合は、許可されるセッションキーの形状を制約するために`hooks.allowedSessionKeyPrefixes`も設定してください。 +- フックペイロードはデフォルトで安全境界によりラップされます。 -## Gmail PubSub統合 +## Gmail PubSub連携 -Google PubSubを通じてGmail受信トリガーをOpenClawに接続します。 +Google PubSubを介してGmail受信トリガーをOpenClawに接続します。 -**前提条件**: `gcloud` CLI、`gog`（gogcli）、OpenClaw hooksが有効、公開HTTPSエンドポイント用のTailscale。 +**前提条件**: `gcloud` CLI、`gog`（gogcli）、OpenClaw hooks有効化、公開HTTPSエンドポイント用のTailscale。 ### ウィザードセットアップ（推奨） @@ -233,15 +236,15 @@ Google PubSubを通じてGmail受信トリガーをOpenClawに接続します。 openclaw webhooks gmail setup --account openclaw@gmail.com ``` -これにより`hooks.gmail` configが書き込まれ、Gmailプリセットが有効化され、プッシュエンドポイントにはTailscale Funnelが使用されます。 +これにより`hooks.gmail`設定が書き込まれ、Gmailプリセットが有効になり、pushエンドポイントにはTailscale Funnelが使用されます。 ### Gateway自動起動 -`hooks.enabled=true`かつ`hooks.gmail.account`が設定されている場合、Gatewayは起動時に`gog gmail watch serve`を開始し、watchを自動更新します。無効にするには`OPENCLAW_SKIP_GMAIL_WATCHER=1`を設定してください。 +`hooks.enabled=true`かつ`hooks.gmail.account`が設定されている場合、Gatewayは起動時に`gog gmail watch serve`を開始し、watchを自動更新します。無効化するには`OPENCLAW_SKIP_GMAIL_WATCHER=1`を設定してください。 -### 手動による1回限りのセットアップ +### 手動の一回限りセットアップ -1. `gog`で使用されるOAuthクライアントを所有するGCPプロジェクトを選択します。 +1. `gog`が使用するOAuthクライアントを所有するGCPプロジェクトを選択します。 ```bash gcloud auth login @@ -249,7 +252,7 @@ gcloud config set project gcloud services enable gmail.googleapis.com pubsub.googleapis.com ``` -2. トピックを作成し、Gmailのpushアクセス権を付与します。 +2. トピックを作成し、Gmailにpushアクセスを付与します。 ```bash gcloud pubsub topics create gog-gmail-watch @@ -301,7 +304,7 @@ openclaw cron runs --id --limit 50 # ジョブを削除 openclaw cron remove -# Agent選択（マルチagentセットアップ） +# エージェント選択（マルチエージェント構成） openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops openclaw cron edit --clear-agent ``` @@ -309,9 +312,9 @@ openclaw cron edit --clear-agent モデルオーバーライドに関する注意: - `openclaw cron add|edit --model ...`はジョブの選択モデルを変更します。 -- モデルが許可されている場合、その正確なprovider/modelが分離agent実行に渡されます。 -- 許可されていない場合、cronは警告を出し、ジョブのagent/defaultモデル選択にフォールバックします。 -- 設定済みのフォールバックチェーンは引き続き適用されますが、明示的なジョブ単位のフォールバックリストがない単純な`--model`オーバーライドでは、agent primaryに暗黙の追加再試行先としてフォールスルーしなくなりました。 +- モデルが許可されている場合、その正確なprovider/modelが分離エージェント実行に渡されます。 +- 許可されていない場合、cronは警告を出し、そのジョブのエージェント/デフォルトのモデル選択にフォールバックします。 +- 設定されたフォールバックチェーンは引き続き適用されますが、明示的なジョブ単位フォールバックリストのない単純な`--model`オーバーライドでは、無言の追加リトライ先としてエージェントprimaryにフォールスルーしなくなりました。 ## 設定 @@ -326,24 +329,24 @@ openclaw cron edit --clear-agent backoffMs: [60000, 120000, 300000], retryOn: ["rate_limit", "overloaded", "network", "server_error"], }, - webhookToken: "replace-with-dedicated-webhook-token", + webhookToken: "専用のWebhookトークンに置き換えてください", sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000 }, }, } ``` -cronを無効化するには: `cron.enabled: false`または`OPENCLAW_SKIP_CRON=1`。 +cronを無効にするには: `cron.enabled: false` または `OPENCLAW_SKIP_CRON=1`。 -**1回限りの再試行**: 一時的なエラー（レート制限、過負荷、ネットワーク、サーバーエラー）は指数バックオフで最大3回まで再試行されます。永続的なエラーは即座に無効化されます。 +**1回限りのリトライ**: 一時的なエラー（レート制限、過負荷、ネットワーク、サーバーエラー）は指数バックオフで最大3回まで再試行されます。永続的なエラーは即座に無効化されます。 -**定期実行の再試行**: 再試行間には指数バックオフ（30秒〜60分）が適用されます。次に成功した実行の後でバックオフはリセットされます。 +**定期実行のリトライ**: 再試行の間に指数バックオフ（30秒〜60分）が適用されます。次回の実行が成功するとバックオフはリセットされます。 -**メンテナンス**: `cron.sessionRetention`（デフォルト`24h`）は分離実行セッションエントリーを剪定します。`cron.runLog.maxBytes` / `cron.runLog.keepLines`は実行ログファイルを自動的に剪定します。 +**メンテナンス**: `cron.sessionRetention`（デフォルトは`24h`）は分離実行のセッションエントリを削除します。`cron.runLog.maxBytes` / `cron.runLog.keepLines`は実行ログファイルを自動的に削除します。 ## トラブルシューティング -### コマンド一覧 +### コマンドの手順 ```bash openclaw status @@ -359,27 +362,27 @@ openclaw doctor ### cronが実行されない - `cron.enabled`と`OPENCLAW_SKIP_CRON`環境変数を確認してください。 -- Gatewayが継続的に実行中であることを確認してください。 -- `cron`スケジュールでは、タイムゾーン（`--tz`）とホストのタイムゾーンの違いを確認してください。 -- 実行出力の`reason: not-due`は、手動実行が`openclaw cron run --due`で確認され、そのジョブがまだ期限前だったことを意味します。 +- Gatewayが継続的に実行されていることを確認してください。 +- `cron`スケジュールでは、タイムゾーン（`--tz`）とホストのタイムゾーンを確認してください。 +- 実行出力の`reason: not-due`は、手動実行が`openclaw cron run --due`で確認され、そのジョブの期限がまだ来ていなかったことを意味します。 ### cronは実行されたが配信されない -- 配信モードが`none`の場合、外部メッセージは送信されません。 -- 配信ターゲットが欠落または無効（`channel`/`to`）な場合、送信はスキップされます。 -- チャンネル認証エラー（`unauthorized`、`Forbidden`）は、認証情報によって配信がブロックされたことを意味します。 -- 分離実行がサイレントトークン（`NO_REPLY` / `no_reply`）のみを返した場合、OpenClawは直接の外向き配信を抑制し、フォールバックのキュー要約経路も抑制するため、チャットには何も投稿されません。 -- cronが所有する分離ジョブでは、agentがフォールバックとしてmessageツールを使うことは想定しないでください。runnerが最終配信を管理します。`--no-deliver`は直接送信を許可するのではなく、内部のまま保持します。 +- 配信モードが`none`の場合、外部メッセージは想定されません。 +- 配信先が欠落または無効（`channel`/`to`）の場合、送信はスキップされます。 +- チャネル認証エラー（`unauthorized`、`Forbidden`）は、認証情報によって配信がブロックされたことを意味します。 +- 分離実行がサイレントトークン（`NO_REPLY` / `no_reply`）のみを返した場合、OpenClawは直接の外部配信を抑制し、フォールバックのキュー済み要約経路も抑制するため、チャットには何も投稿されません。 +- cronが管理する分離ジョブでは、フォールバックとしてエージェントがmessageツールを使うことを期待しないでください。ランナーが最終配信を管理し、`--no-deliver`は直接送信を許可する代わりに内部処理のままにします。 ### タイムゾーンの注意点 -- `--tz`なしのcronはGatewayホストのタイムゾーンを使用します。 +- `--tz`なしのcronはgatewayホストのタイムゾーンを使用します。 - タイムゾーンなしの`at`スケジュールはUTCとして扱われます。 -- Heartbeatの`activeHours`は設定済みタイムゾーン解決を使用します。 +- heartbeatの`activeHours`は設定済みタイムゾーン解決を使用します。 ## 関連 -- [Automation & Tasks](/automation) — すべての自動化メカニズムの概要 -- [Background Tasks](/automation/tasks) — cron実行のタスク台帳 -- [Heartbeat](/gateway/heartbeat) — 定期的なメインセッションターン -- [Timezone](/concepts/timezone) — タイムゾーン設定 +- [Automation & Tasks](/ja-JP/automation) — すべての自動化メカニズムの概要 +- [Background Tasks](/ja-JP/automation/tasks) — cron実行のタスク台帳 +- [Heartbeat](/ja-JP/gateway/heartbeat) — 定期的なメインセッションのターン +- [Timezone](/ja-JP/concepts/timezone) — タイムゾーン設定 diff --git a/docs/ja-JP/automation/hooks.md b/docs/ja-JP/automation/hooks.md index 443fe173a..7962e061e 100644 --- a/docs/ja-JP/automation/hooks.md +++ b/docs/ja-JP/automation/hooks.md @@ -1,68 +1,68 @@ --- read_when: - - '`/new`、`/reset`、`/stop`、およびエージェントのライフサイクルイベント向けのイベント駆動型自動化が必要な場合' - - hooksの構築、インストール、またはデバッグを行いたい場合 -summary: Hooks：コマンドとライフサイクルイベントのためのイベント駆動型自動化 -title: Hooks + - /new、/reset、/stop、およびエージェントのライフサイクルイベントに対するイベント駆動型自動化が必要な場合 + - フックを構築、インストール、またはデバッグしたい場合 +summary: 'フック: コマンドとライフサイクルイベントのためのイベント駆動型自動化' +title: フック x-i18n: - generated_at: "2026-04-05T12:34:32Z" + generated_at: "2026-04-11T02:44:16Z" model: gpt-5.4 provider: openai - source_hash: 66eb75bb2b3b2ad229bf3da24fdb0fe021ed08f812fd1d13c69b3bd9df0218e5 + source_hash: 14296398e4042d442ebdf071a07c6be99d4afda7cbf3c2b934e76dc5539742c7 source_path: automation/hooks.md workflow: 15 --- -# Hooks +# フック -Hooksは、Gateway内で何かが起きたときに実行される小さなスクリプトです。ディレクトリから自動的に検出され、`openclaw hooks`で確認できます。 +フックは、Gateway内部で何かが起きたときに実行される小さなスクリプトです。ディレクトリから自動的に検出され、`openclaw hooks`で確認できます。 -OpenClawには2種類のhooksがあります。 +OpenClawには2種類のフックがあります。 -- **内部hooks**（このページ）: `/new`、`/reset`、`/stop`、またはライフサイクルイベントのようなエージェントイベントが発生したときにGateway内で実行されます。 -- **Webhooks**: 他のシステムがOpenClaw内で処理をトリガーできるようにする外部HTTPエンドポイントです。[Webhooks](/automation/cron-jobs#webhooks)を参照してください。 +- **内部フック**（このページ）: `/new`、`/reset`、`/stop`、またはライフサイクルイベントのようなエージェントイベントが発火したときにGateway内で実行されます。 +- **Webhook**: 外部HTTPエンドポイントで、他のシステムがOpenClaw内の処理をトリガーできるようにします。[Webhook](/ja-JP/automation/cron-jobs#webhooks)を参照してください。 -Hooksはplugins内に同梱することもできます。`openclaw hooks list`には、スタンドアロンhooksとplugin管理hooksの両方が表示されます。 +フックはプラグイン内に同梱することもできます。`openclaw hooks list`には、スタンドアロンのフックとプラグイン管理のフックの両方が表示されます。 ## クイックスタート ```bash -# 利用可能なhooksを一覧表示 +# 利用可能なフックを一覧表示 openclaw hooks list -# hookを有効化 +# フックを有効化 openclaw hooks enable session-memory -# hookのステータスを確認 +# フックの状態を確認 openclaw hooks check # 詳細情報を取得 openclaw hooks info session-memory ``` -## イベントの種類 +## イベントタイプ -| Event | 発火するタイミング | -| ------------------------ | -------------------------------------- | -| `command:new` | `/new`コマンドが実行されたとき | -| `command:reset` | `/reset`コマンドが実行されたとき | -| `command:stop` | `/stop`コマンドが実行されたとき | -| `command` | 任意のコマンドイベント（汎用リスナー） | -| `session:compact:before` | compactionが履歴を要約する前 | -| `session:compact:after` | compactionの完了後 | -| `session:patch` | セッションのプロパティが変更されたとき | -| `agent:bootstrap` | ワークスペースのbootstrapファイルが注入される前 | -| `gateway:startup` | channelsが起動し、hooksが読み込まれた後 | -| `message:received` | 任意のchannelから受信した受信メッセージ | -| `message:transcribed` | 音声文字起こしの完了後 | -| `message:preprocessed` | すべてのメディア処理とリンク理解の完了後 | -| `message:sent` | 送信メッセージが配信されたとき | +| イベント | 発火するタイミング | +| ------------------------ | ------------------------------------------------ | +| `command:new` | `/new`コマンドが実行されたとき | +| `command:reset` | `/reset`コマンドが実行されたとき | +| `command:stop` | `/stop`コマンドが実行されたとき | +| `command` | 任意のコマンドイベント（汎用リスナー） | +| `session:compact:before` | compactが履歴を要約する前 | +| `session:compact:after` | compactの完了後 | +| `session:patch` | セッションプロパティが変更されたとき | +| `agent:bootstrap` | ワークスペースのbootstrapファイルが注入される前 | +| `gateway:startup` | チャンネル開始後、かつフックが読み込まれた後 | +| `message:received` | 任意のチャンネルから受信メッセージが届いたとき | +| `message:transcribed` | 音声文字起こしが完了した後 | +| `message:preprocessed` | すべてのメディアとリンクの理解が完了した後 | +| `message:sent` | 送信メッセージが配信されたとき | -## hooksの作成 +## フックの作成 -### hookの構成 +### フックの構成 -各hookは、2つのファイルを含むディレクトリです。 +各フックは2つのファイルを含むディレクトリです。 ``` my-hook/ @@ -75,7 +75,7 @@ my-hook/ ```markdown --- name: my-hook -description: "このhookが行うことの短い説明" +description: "このフックが行うことの短い説明" metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } --- @@ -87,13 +87,13 @@ metadata: **メタデータフィールド**（`metadata.openclaw`）: -| Field | 説明 | +| フィールド | 説明 | | ---------- | ---------------------------------------------------- | | `emoji` | CLIに表示する絵文字 | | `events` | 監視するイベントの配列 | -| `export` | 使用する名前付きexport（デフォルトは`"default"`） | +| `export` | 使用する名前付きエクスポート（デフォルトは`"default"`） | | `os` | 必要なプラットフォーム（例: `["darwin", "linux"]`） | -| `requires` | 必須の`bins`、`anyBins`、`env`、または`config`パス | +| `requires` | 必要な`bins`、`anyBins`、`env`、または`config`パス | | `always` | 適格性チェックをバイパスするかどうか（boolean） | | `install` | インストール方法 | @@ -106,18 +106,18 @@ const handler = async (event) => { } console.log(`[my-hook] New command triggered`); - // Your logic here + // ここにロジックを記述 - // Optionally send message to user + // 必要に応じてユーザーにメッセージを送信 event.messages.push("Hook executed!"); }; export default handler; ``` -各イベントには次が含まれます: `type`、`action`、`sessionKey`、`timestamp`、`messages`（ユーザーに送信するにはpush）、および`context`（イベント固有のデータ）。 +各イベントには`type`、`action`、`sessionKey`、`timestamp`、`messages`（ユーザー送信用にpush）、および`context`（イベント固有のデータ）が含まれます。 -### イベントコンテキストの主な項目 +### イベントコンテキストの要点 **コマンドイベント**（`command:new`、`command:reset`）: `context.sessionEntry`、`context.previousSessionEntry`、`context.commandSource`、`context.workspaceDir`、`context.cfg`。 @@ -131,49 +131,53 @@ export default handler; **Bootstrapイベント**（`agent:bootstrap`）: `context.bootstrapFiles`（変更可能な配列）、`context.agentId`。 -**セッションpatchイベント**（`session:patch`）: `context.sessionEntry`、`context.patch`（変更されたフィールドのみ）、`context.cfg`。patchイベントをトリガーできるのは特権クライアントのみです。 +**セッションパッチイベント**（`session:patch`）: `context.sessionEntry`、`context.patch`（変更されたフィールドのみ）、`context.cfg`。パッチイベントをトリガーできるのは特権クライアントのみです。 -**Compactionイベント**: `session:compact:before`には`messageCount`、`tokenCount`が含まれます。`session:compact:after`にはさらに`compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`が追加されます。 +**Compactイベント**: `session:compact:before`には`messageCount`、`tokenCount`が含まれます。`session:compact:after`には`compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`が追加されます。 -## hookの検出 +## フックの検出 -Hooksは、上書き優先度が低い順から高い順に、次のディレクトリから検出されます。 +フックは、優先順位の低い順から高い順に、次のディレクトリから検出されます。 -1. **同梱hooks**: OpenClawに同梱されるもの -2. **Plugin hooks**: インストール済みplugins内に同梱されるhooks -3. **Managed hooks**: `~/.openclaw/hooks/`（ユーザーがインストールし、ワークスペース間で共有されるもの）。`hooks.internal.load.extraDirs`の追加ディレクトリもこの優先度を共有します。 -4. **Workspace hooks**: `/hooks/`（エージェントごと。明示的に有効化するまでデフォルトでは無効） +1. **同梱フック**: OpenClawに同梱されているもの +2. **プラグインフック**: インストール済みプラグインに同梱されているフック +3. **管理フック**: `~/.openclaw/hooks/`（ユーザーがインストールした、ワークスペース間で共有されるもの）。`hooks.internal.load.extraDirs`の追加ディレクトリもこの優先順位を共有します。 +4. **ワークスペースフック**: `/hooks/`（エージェント単位、明示的に有効化されるまでデフォルトで無効） -Workspace hooksは新しいhook名を追加できますが、同じ名前の同梱、managed、またはplugin提供hookを上書きすることはできません。 +ワークスペースフックは新しいフック名を追加できますが、同じ名前の同梱、管理、またはプラグイン提供フックを上書きすることはできません。 -### hookパック +### フックパック -hookパックは、`package.json`内の`openclaw.hooks`を通じてhooksを公開するnpmパッケージです。次のようにインストールします。 +フックパックは、`package.json`の`openclaw.hooks`を通じてフックをエクスポートするnpmパッケージです。次のコマンドでインストールします。 ```bash openclaw plugins install ``` -npm specはレジストリ専用です（パッケージ名 + 任意の正確なバージョンまたはdist-tag）。Git/URL/file specおよびsemver rangeは拒否されます。 +npm specとして使えるのはレジストリのみです（パッケージ名 + 任意の厳密なバージョンまたはdist-tag）。Git/URL/file specやsemver rangeは拒否されます。 -## 同梱hooks +## 同梱フック -| Hook | Events | 動作内容 | +| フック | イベント | 動作内容 | | --------------------- | ------------------------------ | ----------------------------------------------------- | | session-memory | `command:new`, `command:reset` | セッションコンテキストを`/memory/`に保存 | | bootstrap-extra-files | `agent:bootstrap` | globパターンから追加のbootstrapファイルを注入 | | command-logger | `command` | すべてのコマンドを`~/.openclaw/logs/commands.log`に記録 | -| boot-md | `gateway:startup` | gatewayの起動時に`BOOT.md`を実行 | +| boot-md | `gateway:startup` | Gateway起動時に`BOOT.md`を実行 | -任意の同梱hookを有効化するには、次を実行します。 +任意の同梱フックを有効化するには: ```bash openclaw hooks enable ``` + + ### session-memoryの詳細 -直近15件のユーザー/assistantメッセージを抽出し、LLMで説明的なファイル名スラッグを生成して、`/memory/YYYY-MM-DD-slug.md`に保存します。`workspace.dir`が設定されている必要があります。 +直近15件のuser/assistantメッセージを抽出し、LLMで説明的なファイル名slugを生成して、`/memory/YYYY-MM-DD-slug.md`に保存します。`workspace.dir`の設定が必要です。 + + ### bootstrap-extra-filesの設定 @@ -192,13 +196,25 @@ openclaw hooks enable } ``` -パスはワークスペースを基準に解決されます。認識されるbootstrap basenameのみが読み込まれます（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 +パスはワークスペース基準で解決されます。読み込まれるのは認識されたbootstrap basenameのみです（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 -## Plugin hooks + -Pluginsは、より深い統合のためにPlugin SDKを通じてhooksを登録できます。これには、ツール呼び出しのインターセプト、プロンプトの変更、メッセージフローの制御などが含まれます。Plugin SDKは、モデル解決、エージェントライフサイクル、メッセージフロー、ツール実行、subagent協調、gatewayライフサイクルをカバーする28個のhooksを公開しています。 +### command-loggerの詳細 -`before_tool_call`、`before_agent_reply`、`before_install`、およびその他すべてのplugin hooksを含む完全なplugin hookリファレンスについては、[Plugin Architecture](/plugins/architecture#provider-runtime-hooks)を参照してください。 +すべてのスラッシュコマンドを`~/.openclaw/logs/commands.log`に記録します。 + + + +### boot-mdの詳細 + +Gateway起動時にアクティブなワークスペースの`BOOT.md`を実行します。 + +## プラグインフック + +プラグインは、より深い統合のためにPlugin SDKを通じてフックを登録できます。たとえば、ツール呼び出しのインターセプト、プロンプトの変更、メッセージフローの制御などです。Plugin SDKは、モデル解決、エージェントライフサイクル、メッセージフロー、ツール実行、サブエージェント連携、Gatewayライフサイクルをカバーする28個のフックを公開しています。 + +`before_tool_call`、`before_agent_reply`、`before_install`、およびその他すべてのプラグインフックを含む完全なプラグインフックリファレンスについては、[プラグインアーキテクチャ](/ja-JP/plugins/architecture#provider-runtime-hooks)を参照してください。 ## 設定 @@ -216,7 +232,7 @@ Pluginsは、より深い統合のためにPlugin SDKを通じてhooksを登録 } ``` -hookごとの環境変数: +フックごとの環境変数: ```json { @@ -233,7 +249,7 @@ hookごとの環境変数: } ``` -追加のhookディレクトリ: +追加のフックディレクトリ: ```json { @@ -248,16 +264,16 @@ hookごとの環境変数: ``` -従来の`hooks.internal.handlers`配列設定形式も後方互換性のため引き続きサポートされていますが、新しいhooksでは検出ベースのシステムを使用してください。 +従来の`hooks.internal.handlers`配列設定形式も後方互換性のため引き続きサポートされていますが、新しいフックでは検出ベースのシステムを使用してください。 ## CLIリファレンス ```bash -# すべてのhooksを一覧表示（--eligible、--verbose、または--jsonを追加可能） +# すべてのフックを一覧表示（--eligible、--verbose、または--jsonを追加可能） openclaw hooks list -# hookの詳細情報を表示 +# フックの詳細情報を表示 openclaw hooks info # 適格性の概要を表示 @@ -270,25 +286,25 @@ openclaw hooks disable ## ベストプラクティス -- **ハンドラーは高速に保つ。** Hooksはコマンド処理中に実行されます。重い処理は`void processInBackground(event)`でfire-and-forgetにしてください。 -- **エラーは適切に処理する。** 危険な処理はtry/catchで囲み、他のハンドラーが実行できるようにthrowしないでください。 +- **ハンドラーは高速に保つ。** フックはコマンド処理中に実行されます。重い処理は`void processInBackground(event)`でfire-and-forgetにしてください。 +- **エラーは適切に処理する。** 危険な操作はtry/catchで囲み、他のハンドラーが実行できるようにthrowしないでください。 - **早い段階でイベントを絞り込む。** イベントのtype/actionが関係ない場合はすぐにreturnしてください。 -- **具体的なイベントキーを使う。** オーバーヘッドを減らすため、`"events": ["command"]`より`"events": ["command:new"]`を優先してください。 +- **具体的なイベントキーを使う。** オーバーヘッド削減のため、`"events": ["command"]`より`"events": ["command:new"]`を優先してください。 ## トラブルシューティング -### hookが検出されない +### フックが検出されない ```bash -# ディレクトリ構造を確認 +# ディレクトリ構成を確認 ls -la ~/.openclaw/hooks/my-hook/ -# 表示されるべきもの: HOOK.md, handler.ts +# 表示されるべき内容: HOOK.md, handler.ts -# 検出されたすべてのhooksを一覧表示 +# 検出されたフックをすべて一覧表示 openclaw hooks list ``` -### hookが適格でない +### フックが適格でない ```bash openclaw hooks info my-hook @@ -296,15 +312,15 @@ openclaw hooks info my-hook 不足しているバイナリ（PATH）、環境変数、設定値、またはOS互換性を確認してください。 -### hookが実行されない +### フックが実行されない -1. hookが有効になっていることを確認します: `openclaw hooks list` -2. hooksが再読み込みされるようにgatewayプロセスを再起動します。 -3. gatewayログを確認します: `./scripts/clawlog.sh | grep hook` +1. フックが有効になっていることを確認してください: `openclaw hooks list` +2. フックを再読み込みするためにGatewayプロセスを再起動してください。 +3. Gatewayログを確認してください: `./scripts/clawlog.sh | grep hook` ## 関連 -- [CLI Reference: hooks](/cli/hooks) -- [Webhooks](/automation/cron-jobs#webhooks) -- [Plugin Architecture](/plugins/architecture#provider-runtime-hooks) — 完全なplugin hookリファレンス -- [Configuration](/gateway/configuration-reference#hooks) +- [CLIリファレンス: hooks](/cli/hooks) +- [Webhook](/ja-JP/automation/cron-jobs#webhooks) +- [プラグインアーキテクチャ](/ja-JP/plugins/architecture#provider-runtime-hooks) — 完全なプラグインフックリファレンス +- [設定](/ja-JP/gateway/configuration-reference#hooks) diff --git a/docs/ja-JP/ci.md b/docs/ja-JP/ci.md index f35dcc680..a95ad03cf 100644 --- a/docs/ja-JP/ci.md +++ b/docs/ja-JP/ci.md @@ -1,74 +1,75 @@ --- read_when: - - CIジョブが実行された理由、または実行されなかった理由を理解する必要がある - - 失敗しているGitHub Actionsチェックをデバッグしている -summary: CIジョブグラフ、スコープゲート、およびローカルコマンドの対応関係 -title: CIパイプライン + - CI ジョブが実行された、または実行されなかった理由を理解する必要があります + - 失敗している GitHub Actions チェックをデバッグしています +summary: CI ジョブグラフ、スコープゲート、および対応するローカルコマンド +title: CI パイプライン x-i18n: - generated_at: "2026-04-09T04:41:19Z" + generated_at: "2026-04-11T02:44:16Z" model: gpt-5.4 provider: openai - source_hash: d104f2510fadd674d7952aa08ad73e10f685afebea8d7f19adc1d428e2bdc908 + source_hash: ca7e355b7f73bfe8ea8c6971e78164b8b2e68cbb27966964955e267fed89fce6 source_path: ci.md workflow: 15 --- -# CIパイプライン +# CI パイプライン -CIは`main`へのすべてのpushとすべてのpull requestで実行されます。スマートなスコープ判定を使って、変更が無関係な領域のみに及ぶ場合は高コストなジョブをスキップします。 +CI は `main` へのすべての push とすべての pull request で実行されます。スマートなスコープ判定を使用して、変更が無関係な領域のみに限定される場合は高コストなジョブをスキップします。 ## ジョブ概要 -| ジョブ | 目的 | 実行されるタイミング | -| ------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------- | -| `preflight` | ドキュメントのみの変更、変更されたスコープ、変更された拡張機能を検出し、CIマニフェストをビルドする | draftではないpushとPRで常に実行 | -| `security-fast` | 秘密鍵の検出、`zizmor`によるワークフロー監査、本番依存関係の監査 | draftではないpushとPRで常に実行 | -| `build-artifacts` | `dist/`とControl UIを一度ビルドし、下流ジョブ向けに再利用可能なアーティファクトをアップロードする | Node関連の変更 | -| `checks-fast-core` | バンドル済み/plugin-contract/protocolチェックなどの高速なLinux正当性レーン | Node関連の変更 | -| `checks-fast-extensions` | `checks-fast-extensions-shard`の完了後に拡張機能シャードレーンを集約する | Node関連の変更 | -| `extension-fast` | 変更されたバンドル済みプラグインのみを対象にした集中テスト | 拡張機能の変更が検出された場合 | -| `check` | CIにおけるメインのローカルゲート: `pnpm check` と `pnpm build:strict-smoke` | Node関連の変更 | -| `check-additional` | アーキテクチャ、境界、import-cycleガードに加えて、Gateway watch regression harness | Node関連の変更 | -| `build-smoke` | ビルド済みCLIのスモークテストと起動メモリのスモーク | Node関連の変更 | -| `checks` | より重いLinux Nodeレーン: 完全なテスト、チャネルテスト、push時のみのNode 22互換性 | Node関連の変更 | -| `check-docs` | ドキュメントのフォーマット、lint、リンク切れチェック | ドキュメントが変更された場合 | -| `skills-python` | PythonベースのSkillsに対するRuff + pytest | Python Skills関連の変更 | -| `checks-windows` | Windows固有のテストレーン | Windows関連の変更 | -| `macos-node` | 共有のビルド済みアーティファクトを使用するmacOS TypeScriptテストレーン | macOS関連の変更 | -| `macos-swift` | macOSアプリ向けのSwift lint、ビルド、テスト | macOS関連の変更 | -| `android` | Androidのビルドおよびテストマトリクス | Android関連の変更 | +| ジョブ | 目的 | 実行されるタイミング | +| ------------------------ | ------------------------------------------------------------------------------------ | ----------------------------- | +| `preflight` | docs のみの変更、変更されたスコープ、変更された拡張機能を検出し、CI マニフェストを構築する | draft ではない push と PR で常に実行 | +| `security-fast` | 秘密鍵の検出、`zizmor` によるワークフロー監査、本番依存関係の監査 | draft ではない push と PR で常に実行 | +| `build-artifacts` | `dist/` と Control UI を一度だけビルドし、下流ジョブ向けに再利用可能な成果物をアップロードする | Node 関連の変更 | +| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速な Linux 正当性レーン | Node 関連の変更 | +| `checks-node-extensions` | 拡張機能スイート全体にわたる bundled-plugin テストの完全なシャード | Node 関連の変更 | +| `checks-node-core-test` | channel、bundled、contract、extension レーンを除く、Core Node テストのシャード | Node 関連の変更 | +| `extension-fast` | 変更された bundled plugins のみに対する集中テスト | extension の変更が検出された場合 | +| `check` | CI におけるメインのローカルゲート: `pnpm check` と `pnpm build:strict-smoke` | Node 関連の変更 | +| `check-additional` | アーキテクチャ、境界、import-cycle ガードに加え、Gateway watch regression ハーネス | 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 Skills 関連の変更 | +| `checks-windows` | Windows 固有のテストレーン | Windows 関連の変更 | +| `macos-node` | 共有ビルド成果物を使用する macOS TypeScript テストレーン | macOS 関連の変更 | +| `macos-swift` | macOS アプリ向けの Swift lint、build、tests | macOS 関連の変更 | +| `android` | Android の build および test マトリクス | Android 関連の変更 | ## フェイルファスト順序 -ジョブは、高コストなものが実行される前に低コストなチェックが失敗するように順序付けされています。 +ジョブは、コストの低いチェックが高コストなジョブより先に失敗するように順序付けられています。 -1. `preflight`が、そもそもどのレーンを存在させるかを決定します。`docs-scope`と`changed-scope`のロジックは、このジョブ内のステップであり、独立したジョブではありません。 -2. `security-fast`、`check`、`check-additional`、`check-docs`、`skills-python`は、より重いアーティファクトジョブやプラットフォームマトリクスジョブを待たずにすばやく失敗します。 -3. `build-artifacts`は高速なLinuxレーンと並行して実行され、共有ビルドの準備ができしだい下流コンシューマーが開始できるようにします。 -4. その後、より重いプラットフォームおよびランタイムレーンが分岐します: `checks-fast-core`、`checks-fast-extensions`、`extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、`android`。 +1. `preflight` が、どのレーンをそもそも存在させるかを決定します。`docs-scope` と `changed-scope` のロジックは独立したジョブではなく、このジョブ内のステップです。 +2. `security-fast`、`check`、`check-additional`、`check-docs`、`skills-python` は、より重い artifact や platform matrix ジョブを待たずに素早く失敗します。 +3. `build-artifacts` は高速な Linux レーンと並行して動作するため、共有ビルドの準備ができ次第、下流の利用側が開始できます。 +4. その後、より重い platform および runtime レーンがファンアウトします: `checks-fast-core`、`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`ワークフローは、独自の`preflight`ジョブを通じて同じスコープスクリプトを再利用します。これは、より狭いchanged-smokeシグナルから`run_install_smoke`を計算するため、Docker/install smokeはインストール、パッケージング、コンテナ関連の変更に対してのみ実行されます。 +スコープロジックは `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 関連の変更に対してのみ実行されます。 -pushでは、`checks`マトリクスにpush時のみの`compat-node22`レーンが追加されます。pull requestでは、このレーンはスキップされ、マトリクスは通常のテスト/チャネルレーンに集中したままになります。 +push では、`checks` マトリクスに push 専用の `compat-node22` レーンが追加されます。pull request では、そのレーンはスキップされ、マトリクスは通常の test/channel レーンに集中したままになります。 ## ランナー -| ランナー | ジョブ | -| -------------------------------- | ---------------------------------------------------------------------------------------------------- | -| `blacksmith-16vcpu-ubuntu-2404` | `preflight`、`security-fast`、`build-artifacts`、Linuxチェック、ドキュメントチェック、Python Skills、`android` | -| `blacksmith-32vcpu-windows-2025` | `checks-windows` | -| `macos-latest` | `macos-node`、`macos-swift` | +| ランナー | ジョブ | +| -------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `blacksmith-16vcpu-ubuntu-2404` | `preflight`、`security-fast`、`build-artifacts`、Linux checks、docs checks、Python skills、`android` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `macos-latest` | `macos-node`、`macos-swift` | -## ローカルでの対応コマンド +## 対応するローカルコマンド ```bash -pnpm check # 型チェック + lint + フォーマット +pnpm check # 型チェック + lint + format pnpm build:strict-smoke pnpm check:import-cycles pnpm test:gateway:watch-regression -pnpm test # vitestテスト +pnpm test # vitest テスト pnpm test:channels -pnpm check:docs # ドキュメントのフォーマット + lint + リンク切れ -pnpm build # CIのartifact/build-smokeレーンが関係する場合にdistをビルド +pnpm check:docs # docs の format + lint + broken links +pnpm build # CI の artifact/build-smoke レーンが関係する場合に dist をビルド ``` diff --git a/docs/ja-JP/concepts/agent-loop.md b/docs/ja-JP/concepts/agent-loop.md index 923c24cfb..8cf4810c7 100644 --- a/docs/ja-JP/concepts/agent-loop.md +++ b/docs/ja-JP/concepts/agent-loop.md @@ -1,129 +1,128 @@ --- read_when: - - エージェントループまたはライフサイクルイベントの正確な手順が必要な場合 -summary: エージェントループのライフサイクル、ストリーム、待機セマンティクス -title: Agent Loop + - エージェントループまたはライフサイクルイベントの正確なウォークスルーが必要です +summary: エージェントループのライフサイクル、ストリーム、および待機セマンティクス +title: エージェントループ x-i18n: - generated_at: "2026-04-09T01:27:54Z" + generated_at: "2026-04-11T02:44:15Z" model: gpt-5.4 provider: openai - source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1 + source_hash: b6831a5b11e9100e49f650feca51ab44a2bef242ce1b5db2766d0b3b5c5ba729 source_path: concepts/agent-loop.md workflow: 15 --- -# Agent Loop (OpenClaw) +# エージェントループ（OpenClaw） -agentic loop とは、エージェントの完全な「実際の」実行のことです: 受信 → コンテキストの組み立て → モデル推論 → -ツール実行 → ストリーミング返信 → 永続化。これは、セッション状態の整合性を保ちながら、メッセージを -アクションと最終返信に変換する権威ある経路です。 +エージェントループは、エージェントの完全な「実際の」実行です: 受信 → コンテキストの組み立て → モデル推論 → +ツール実行 → 返信のストリーミング → 永続化。これは、セッション状態の整合性を保ちながら、 +メッセージをアクションと最終返信に変換する正式な経路です。 -OpenClaw では、ループはセッションごとに単一の直列化された実行であり、モデルが思考し、ツールを呼び出し、 -出力をストリーミングする間にライフサイクルイベントとストリームイベントを発行します。このドキュメントでは、 -その実際のループがエンドツーエンドでどのように配線されているかを説明します。 +OpenClawでは、ループはセッションごとに単一の直列化された実行であり、モデルが思考し、ツールを呼び出し、出力をストリーミングする間、 +ライフサイクルイベントとストリームイベントを発行します。このドキュメントでは、その本物のループがエンドツーエンドでどのように構成されているかを説明します。 -## エントリポイント +## エントリーポイント -- Gateway RPC: `agent` と `agent.wait` -- CLI: `agent` コマンド +- Gateway RPC: `agent` および `agent.wait`。 +- CLI: `agent` コマンド。 -## 仕組み（高レベル） +## 仕組み（概要） -1. `agent` RPC はパラメータを検証し、セッションを解決し（sessionKey/sessionId）、セッションメタデータを永続化し、すぐに `{ runId, acceptedAt }` を返します。 +1. `agent` RPCはパラメータを検証し、セッション（sessionKey/sessionId）を解決し、セッションメタデータを永続化し、すぐに `{ runId, acceptedAt }` を返します。 2. `agentCommand` がエージェントを実行します: - - モデルと thinking/verbose のデフォルトを解決 + - モデルと thinking/verbose のデフォルト値を解決 - Skills スナップショットを読み込み - - `runEmbeddedPiAgent` を呼び出し（pi-agent-core ランタイム） - - 埋め込みループが発行しない場合は **ライフサイクル end/error** を発行 + - `runEmbeddedPiAgent`（pi-agent-coreランタイム）を呼び出し + - 埋め込みループが発行しない場合は **lifecycle end/error** を発行 3. `runEmbeddedPiAgent`: - - セッション単位 + グローバルキューにより実行を直列化 - - モデル + auth プロファイルを解決して pi セッションを構築 - - pi イベントを購読し、assistant/tool の差分をストリーミング - - タイムアウトを強制し、超過した場合は実行を中断 - - ペイロード + usage メタデータを返す -4. `subscribeEmbeddedPiSession` が pi-agent-core のイベントを OpenClaw の `agent` ストリームに橋渡しします: + - セッション単位 + グローバルキューを通じて実行を直列化 + - モデル + auth profile を解決し、piセッションを構築 + - piイベントを購読し、assistant/tool の差分をストリーミング + - タイムアウトを強制し、超過時は実行を中断 + - ペイロード + 使用量メタデータを返す +4. `subscribeEmbeddedPiSession` が pi-agent-core イベントを OpenClaw の `agent` ストリームに橋渡しします: - ツールイベント => `stream: "tool"` - assistant 差分 => `stream: "assistant"` - ライフサイクルイベント => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` は `waitForAgentRun` を使用します: - - `runId` の **ライフサイクル end/error** を待機 + - `runId` の **lifecycle end/error** を待機 - `{ status: ok|error|timeout, startedAt, endedAt, error? }` を返す ## キューイング + 並行性 -- 実行はセッションキー単位（セッションレーン）で直列化され、必要に応じてグローバルレーンも通ります。 +- 実行はセッションキーごと（セッションレーン）に直列化され、必要に応じてグローバルレーンも通ります。 - これによりツール/セッションの競合を防ぎ、セッション履歴の整合性を保ちます。 - メッセージングチャネルは、このレーンシステムに流し込まれるキューモード（collect/steer/followup）を選択できます。 詳しくは [Command Queue](/ja-JP/concepts/queue) を参照してください。 ## セッション + ワークスペースの準備 -- ワークスペースは解決および作成され、サンドボックス化された実行ではサンドボックスのワークスペースルートにリダイレクトされる場合があります。 +- ワークスペースは解決されて作成されます。サンドボックス実行では、サンドボックス用ワークスペースルートにリダイレクトされることがあります。 - Skills が読み込まれ（またはスナップショットから再利用され）、env とプロンプトに注入されます。 -- Bootstrap/context ファイルが解決され、システムプロンプトレポートに注入されます。 -- セッション書き込みロックが取得され、`SessionManager` がストリーミング前にオープンおよび準備されます。 +- bootstrap/context ファイルが解決され、システムプロンプトレポートに注入されます。 +- セッション書き込みロックが取得され、`SessionManager` がストリーミング前に開かれて準備されます。 ## プロンプトの組み立て + システムプロンプト - システムプロンプトは、OpenClaw のベースプロンプト、Skills プロンプト、bootstrap コンテキスト、および実行ごとのオーバーライドから構築されます。 -- モデル固有の制限と compaction の予約トークンが適用されます。 -- モデルが何を見るかについては [System prompt](/ja-JP/concepts/system-prompt) を参照してください。 +- モデル固有の制限と compaction 用の予約トークンが適用されます。 +- モデルが何を見るかについては、[System prompt](/ja-JP/concepts/system-prompt) を参照してください。 ## フックポイント（介入できる場所） -OpenClaw には 2 つのフックシステムがあります。 +OpenClaw には2つのフックシステムがあります: -- **内部フック**（Gateway hooks）: コマンドとライフサイクルイベントのためのイベント駆動スクリプト -- **プラグインフック**: エージェント/ツールのライフサイクルおよび Gateway パイプライン内の拡張ポイント +- **内部フック**（Gateway フック）: コマンドおよびライフサイクルイベント用のイベント駆動スクリプト。 +- **プラグインフック**: エージェント/ツールのライフサイクルおよび Gateway パイプライン内の拡張ポイント。 -### 内部フック（Gateway hooks） +### 内部フック（Gateway フック） -- **`agent:bootstrap`**: システムプロンプトが最終化される前に bootstrap ファイルを構築している間に実行されます。 - これを使用して bootstrap コンテキストファイルを追加/削除します。 -- **コマンドフック**: `/new`、`/reset`、`/stop`、およびその他のコマンドイベント（Hooks ドキュメントを参照） +- **`agent:bootstrap`**: システムプロンプトが確定する前に bootstrap ファイルを構築している間に実行されます。 + これを使って bootstrap コンテキストファイルを追加/削除します。 +- コマンドフック: `/new`、`/reset`、`/stop`、およびその他のコマンドイベント（Hooks ドキュメントを参照）。 セットアップと例については [Hooks](/ja-JP/automation/hooks) を参照してください。 ### プラグインフック（エージェント + Gateway ライフサイクル） -これらはエージェントループまたは Gateway パイプライン内で実行されます。 +これらはエージェントループ内または Gateway パイプライン内で実行されます: -- **`before_model_resolve`**: モデル解決前に、provider/model を決定的にオーバーライドするためにセッション前（`messages` なし）に実行されます。 -- **`before_prompt_build`**: セッション読み込み後（`messages` あり）に実行され、プロンプト送信前に `prependContext`、`systemPrompt`、`prependSystemContext`、または `appendSystemContext` を注入します。ターンごとの動的テキストには `prependContext` を使用し、システムプロンプト空間に配置されるべき安定したガイダンスには system-context フィールドを使用します。 -- **`before_agent_start`**: どちらのフェーズでも実行される可能性があるレガシー互換フックです。明示的な上記フックを優先してください。 -- **`before_agent_reply`**: インラインアクションの後、LLM 呼び出しの前に実行され、プラグインがそのターンを引き受けて合成返信を返したり、そのターンを完全に無言にしたりできます。 -- **`agent_end`**: 完了後に最終メッセージリストと実行メタデータを検査します。 -- **`before_compaction` / `after_compaction`**: compaction サイクルを観測または注釈付けします。 +- **`before_model_resolve`**: モデル解決前に、provider/model を決定論的に上書きするために、セッション前（`messages` なし）で実行されます。 +- **`before_prompt_build`**: セッション読み込み後（`messages` あり）に実行され、プロンプト送信前に `prependContext`、`systemPrompt`、`prependSystemContext`、または `appendSystemContext` を注入します。ターンごとの動的テキストには `prependContext` を使用し、システムプロンプト空間に置くべき安定したガイダンスには system-context フィールドを使用します。 +- **`before_agent_start`**: レガシー互換性フックで、どちらのフェーズでも実行される可能性があります。できるだけ上記の明示的なフックを使用してください。 +- **`before_agent_reply`**: インラインアクションの後、LLM 呼び出しの前に実行され、プラグインがそのターンを引き受けて synthetic reply を返したり、そのターンを完全に無言にしたりできます。 +- **`agent_end`**: 完了後の最終メッセージ一覧と実行メタデータを検査します。 +- **`before_compaction` / `after_compaction`**: compaction サイクルを監視または注釈付けします。 - **`before_tool_call` / `after_tool_call`**: ツールのパラメータ/結果に介入します。 -- **`before_install`**: 組み込みのスキャン結果を検査し、必要に応じて skill または plugin のインストールをブロックします。 +- **`before_install`**: 組み込みスキャン結果を検査し、必要に応じて skill または plugin のインストールをブロックします。 - **`tool_result_persist`**: ツール結果がセッショントランスクリプトに書き込まれる前に、同期的に変換します。 -- **`message_received` / `message_sending` / `message_sent`**: 受信 + 送信メッセージフック -- **`session_start` / `session_end`**: セッションライフサイクルの境界 -- **`gateway_start` / `gateway_stop`**: Gateway ライフサイクルイベント +- **`message_received` / `message_sending` / `message_sent`**: 受信および送信メッセージフック。 +- **`session_start` / `session_end`**: セッションライフサイクルの境界。 +- **`gateway_start` / `gateway_stop`**: Gateway ライフサイクルイベント。 送信/ツールガードのフック判定ルール: -- `before_tool_call`: `{ block: true }` は終端であり、優先度の低いハンドラーを停止します。 +- `before_tool_call`: `{ block: true }` は終端であり、より低い優先度のハンドラーを停止します。 - `before_tool_call`: `{ block: false }` は no-op であり、以前の block を解除しません。 -- `before_install`: `{ block: true }` は終端であり、優先度の低いハンドラーを停止します。 +- `before_install`: `{ block: true }` は終端であり、より低い優先度のハンドラーを停止します。 - `before_install`: `{ block: false }` は no-op であり、以前の block を解除しません。 -- `message_sending`: `{ cancel: true }` は終端であり、優先度の低いハンドラーを停止します。 +- `message_sending`: `{ cancel: true }` は終端であり、より低い優先度のハンドラーを停止します。 - `message_sending`: `{ cancel: false }` は no-op であり、以前の cancel を解除しません。 -フック API と登録の詳細については [Plugin hooks](/ja-JP/plugins/architecture#provider-runtime-hooks) を参照してください。 +フック API と登録の詳細は [Plugin hooks](/ja-JP/plugins/architecture#provider-runtime-hooks) を参照してください。 ## ストリーミング + 部分返信 - assistant 差分は pi-agent-core からストリーミングされ、`assistant` イベントとして発行されます。 -- ブロックストリーミングでは、`text_end` または `message_end` で部分返信を発行できます。 -- reasoning ストリーミングは、別個のストリームとして、またはブロック返信として発行できます。 +- ブロックストリーミングは、`text_end` または `message_end` で部分返信を発行できます。 +- reasoning ストリーミングは、別ストリームとして、またはブロック返信として発行できます。 - チャンク化とブロック返信の挙動については [Streaming](/ja-JP/concepts/streaming) を参照してください。 ## ツール実行 + メッセージングツール - ツールの start/update/end イベントは `tool` ストリームで発行されます。 -- ツール結果は、ログ記録/発行の前に、サイズと画像ペイロードについてサニタイズされます。 -- メッセージングツールの送信は、assistant の重複確認を抑制するために追跡されます。 +- ツール結果は、ログ出力/発行の前に、サイズおよび画像ペイロードに関してサニタイズされます。 +- メッセージングツールの送信は、assistant による重複確認を抑制するために追跡されます。 ## 返信の整形 + 抑制 @@ -131,41 +130,41 @@ OpenClaw には 2 つのフックシステムがあります。 - assistant テキスト（および任意の reasoning） - インラインツール要約（verbose かつ許可されている場合） - モデルエラー時の assistant エラーテキスト -- 正確な silent token `NO_REPLY` / `no_reply` は送信ペイロードから - フィルタリングされます。 -- メッセージングツールの重複は最終ペイロードリストから削除されます。 -- 描画可能なペイロードが何も残っておらず、かつツールでエラーが発生した場合は、フォールバックのツールエラー返信が発行されます +- 正確な silent token `NO_REPLY` / `no_reply` は送信ペイロードから除外されます。 +- メッセージングツールの重複は最終ペイロード一覧から削除されます。 +- 描画可能なペイロードが何も残っておらず、かつツールでエラーが発生した場合は、 + フォールバックのツールエラー返信が発行されます （ただし、メッセージングツールがすでにユーザーに見える返信を送信している場合を除きます）。 ## compaction + リトライ - 自動 compaction は `compaction` ストリームイベントを発行し、リトライを引き起こすことがあります。 -- リトライ時には、重複出力を避けるためにインメモリバッファとツール要約がリセットされます。 +- リトライ時には、重複出力を避けるため、インメモリバッファとツール要約がリセットされます。 - compaction パイプラインについては [Compaction](/ja-JP/concepts/compaction) を参照してください。 ## イベントストリーム（現時点） -- `lifecycle`: `subscribeEmbeddedPiSession` により発行されます（およびフォールバックとして `agentCommand` からも発行されます） -- `assistant`: pi-agent-core からストリーミングされる差分 -- `tool`: pi-agent-core からストリーミングされるツールイベント +- `lifecycle`: `subscribeEmbeddedPiSession` によって発行されます（およびフォールバックとして `agentCommand` からも発行されます） +- `assistant`: pi-agent-core からのストリーミング差分 +- `tool`: pi-agent-core からのストリーミングツールイベント ## チャットチャネルの処理 -- assistant 差分はチャット `delta` メッセージにバッファリングされます。 +- assistant 差分はチャット `delta` メッセージにバッファされます。 - チャット `final` は **lifecycle end/error** で発行されます。 ## タイムアウト -- `agent.wait` のデフォルト: 30 秒（待機のみ）。`timeoutMs` パラメータで上書きします。 -- エージェント実行時: `agents.defaults.timeoutSeconds` のデフォルトは 172800 秒（48 時間）で、`runEmbeddedPiAgent` の中断タイマーで強制されます。 -- LLM アイドルタイムアウト: `agents.defaults.llm.idleTimeoutSeconds` は、アイドルウィンドウ内に応答チャンクが到着しない場合にモデルリクエストを中断します。低速なローカルモデルや reasoning/tool-call provider では明示的に設定してください。無効にするには 0 に設定します。これが設定されていない場合、OpenClaw は `agents.defaults.timeoutSeconds` が設定されていればそれを使用し、そうでなければ 60 秒を使用します。明示的な LLM またはエージェントタイムアウトがない cron トリガー実行では、アイドルウォッチドッグは無効化され、cron の外側のタイムアウトに依存します。 +- `agent.wait` のデフォルト: 30秒（待機のみ）。`timeoutMs` パラメータで上書きできます。 +- エージェント実行時: `agents.defaults.timeoutSeconds` のデフォルトは 172800秒（48時間）で、`runEmbeddedPiAgent` の abort タイマーで強制されます。 +- LLM アイドルタイムアウト: `agents.defaults.llm.idleTimeoutSeconds` は、アイドルウィンドウ内にレスポンスチャンクが到着しない場合にモデルリクエストを中断します。遅いローカルモデルや reasoning/ツール呼び出し provider には明示的に設定してください。無効化するには 0 に設定します。設定されていない場合、OpenClaw は `agents.defaults.timeoutSeconds` が設定されていればそれを使用し、そうでなければ 120秒を使用します。明示的な LLM またはエージェントタイムアウトのない cron トリガー実行では、アイドルウォッチドッグは無効化され、cron の外側のタイムアウトに依存します。 -## 早期終了する可能性がある場所 +## 途中で早期終了する可能性がある場所 -- エージェントタイムアウト（中断） +- エージェントタイムアウト（abort） - AbortSignal（キャンセル） - Gateway 切断または RPC タイムアウト -- `agent.wait` タイムアウト（待機のみで、エージェントは停止しない） +- `agent.wait` タイムアウト（待機のみで、エージェント自体は停止しません） ## 関連 diff --git a/docs/ja-JP/concepts/model-providers.md b/docs/ja-JP/concepts/model-providers.md index 604094781..41ebf5f08 100644 --- a/docs/ja-JP/concepts/model-providers.md +++ b/docs/ja-JP/concepts/model-providers.md @@ -1,41 +1,40 @@ --- read_when: - - プロバイダーごとのモデル設定リファレンスが必要な場合 - - モデルプロバイダー向けの設定例やCLIオンボーディングコマンドを確認したい場合 -summary: 設定例とCLIフロー付きのモデルプロバイダー概要 + - プロバイダーごとのモデル設定リファレンスが必要です + - モデルプロバイダー向けの設定例やCLIオンボーディングコマンドが必要です +summary: モデルプロバイダーの概要と設定例 + CLIフロー title: モデルプロバイダー x-i18n: - generated_at: "2026-04-09T01:30:09Z" + generated_at: "2026-04-11T02:44:15Z" model: gpt-5.4 provider: openai - source_hash: 53e3141256781002bbe1d7e7b78724a18d061fcf36a203baae04a091b8c9ea1b + source_hash: 910ea7895e74c03910757d9d3e02825754b779b204eca7275b28422647ed0151 source_path: concepts/model-providers.md workflow: 15 --- # モデルプロバイダー -このページでは**LLM/モデルプロバイダー**を扱います（WhatsApp/Telegramのようなチャットチャンネルではありません）。 +このページでは、**LLM/モデルプロバイダー**（WhatsApp/Telegramのようなチャットチャネルではありません）を扱います。 モデル選択ルールについては、[/concepts/models](/ja-JP/concepts/models)を参照してください。 ## クイックルール - モデル参照は`provider/model`を使用します（例: `opencode/claude-opus-4-6`）。 - `agents.defaults.models`を設定すると、それが許可リストになります。 -- CLIヘルパー: `openclaw onboard`, `openclaw models list`, `openclaw models set `。 -- フォールバックのランタイムルール、クールダウンプローブ、セッション上書き永続化は - [/concepts/model-failover](/ja-JP/concepts/model-failover)に記載されています。 +- CLIヘルパー: `openclaw onboard`、`openclaw models list`、`openclaw models set `。 +- フォールバックの実行時ルール、クールダウンプローブ、セッション上書きの永続化は、[/concepts/model-failover](/ja-JP/concepts/model-failover)に記載されています。 - `models.providers.*.models[].contextWindow`はネイティブなモデルメタデータです。 - `models.providers.*.models[].contextTokens`は実効ランタイム上限です。 + `models.providers.*.models[].contextTokens`は実行時に有効な上限です。 - プロバイダープラグインは`registerProvider({ catalog })`を通じてモデルカタログを注入できます。 OpenClawはその出力を`models.providers`にマージしてから `models.json`を書き込みます。 -- プロバイダーマニフェストでは`providerAuthEnvVars`と - `providerAuthAliases`を宣言できるため、汎用のenvベース認証プローブやプロバイダーバリアントで - プラグインランタイムを読み込む必要がありません。残っているコアのenv-varマップは現在、 - 非プラグイン/コアプロバイダーと、AnthropicのAPIキーファーストなオンボーディングのような - いくつかの汎用優先順位ケース専用です。 -- プロバイダープラグインは、以下を通じてプロバイダーのランタイム挙動も所有できます: +- プロバイダーマニフェストは`providerAuthEnvVars`と + `providerAuthAliases`を宣言できるため、汎用の環境変数ベース認証プローブやプロバイダーバリアントで + プラグインランタイムを読み込む必要がありません。残っているコアの環境変数マップは現在、 + 非プラグイン/コアプロバイダーと、AnthropicのAPIキー優先オンボーディングのような + いくつかの汎用優先順位ケースのためだけに使われています。 +- プロバイダープラグインは、以下を通じてプロバイダーの実行時動作も所有できます: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -53,230 +52,224 @@ x-i18n: `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and `onModelSelected`。 -- 注: プロバイダーランタイムの`capabilities`は共有ランナーメタデータです（プロバイダーファミリー、 - transcript/toolingの癖、transport/cacheのヒント）。これは、 - プラグインが何を登録するか（テキスト推論、音声など）を記述する - [公開 capability モデル](/ja-JP/plugins/architecture#public-capability-model) - とは異なります。 +- 注: プロバイダー実行時の`capabilities`は共有ランナーのメタデータです（プロバイダーファミリー、文字起こし/ツールの癖、トランスポート/キャッシュのヒント）。 + これは、プラグインが何を登録するか（テキスト推論、音声など）を説明する + [公開 capability model](/ja-JP/plugins/architecture#public-capability-model) + とは同じではありません。 +- バンドル版の`codex`プロバイダーは、バンドル版Codexエージェントハーネスと組みになっています。 + Codexが所有するログイン、モデル検出、ネイティブなスレッド再開、 + アプリサーバー実行を使いたい場合は、`codex/gpt-*`を使用してください。通常の`openai/gpt-*`参照は引き続き + OpenAIプロバイダーと通常のOpenClawプロバイダートランスポートを使用します。 + Codex専用デプロイでは、自動PIフォールバックを + `agents.defaults.embeddedHarness.fallback: "none"`で無効にできます。詳細は + [Codex Harness](/ja-JP/plugins/codex-harness)を参照してください。 -## プラグイン所有のプロバイダー挙動 +## プラグイン所有のプロバイダー動作 -プロバイダープラグインは、OpenClawが汎用推論ループを維持したまま、 -プロバイダー固有ロジックの大部分を所有できるようになりました。 +OpenClawが汎用推論ループを維持しつつ、 +プロバイダープラグインがプロバイダー固有ロジックの大半を所有できるようになりました。 -典型的な分担: +一般的な分担: -- `auth[].run` / `auth[].runNonInteractive`: `openclaw onboard`、 - `openclaw models auth`、ヘッドレスセットアップ向けのオンボーディング/ログイン - フローをプロバイダーが所有 -- `wizard.setup` / `wizard.modelPicker`: 認証選択ラベル、 - レガシーエイリアス、オンボーディングの許可リストヒント、オンボーディング/モデルピッカー内の - セットアップ項目をプロバイダーが所有 +- `auth[].run` / `auth[].runNonInteractive`: プロバイダーが`openclaw onboard`、`openclaw models auth`、ヘッドレス設定向けのオンボーディング/ログイン + フローを所有 +- `wizard.setup` / `wizard.modelPicker`: プロバイダーが認証選択ラベル、 + レガシーエイリアス、オンボーディング許可リストのヒント、オンボーディング/モデルピッカー内のセットアップ項目を所有 - `catalog`: プロバイダーが`models.providers`に表示される -- `normalizeModelId`: 検索や正規化の前に、レガシー/プレビューモデルIDを - プロバイダーが正規化 -- `normalizeTransport`: 汎用モデル組み立て前にtransportファミリーの`api` / `baseUrl`を - プロバイダーが正規化。OpenClawはまず一致したプロバイダーを確認し、 - その後、実際にtransportを変更するものが見つかるまで、他のhook対応プロバイダープラグインを確認します -- `normalizeConfig`: ランタイムが使う前に、`models.providers.`設定を - プロバイダーが正規化。OpenClawはまず一致したプロバイダーを確認し、その後、 - 実際に設定を変更するものが見つかるまで、他のhook対応プロバイダープラグインを確認します。どの - プロバイダーフックも設定を書き換えない場合、バンドルされたGoogle系ヘルパーが引き続き - 対応するGoogleプロバイダー項目を正規化します。 -- `applyNativeStreamingUsageCompat`: 設定プロバイダーに対して、 - エンドポイント駆動のネイティブなstreaming-usage互換書き換えをプロバイダーが適用 -- `resolveConfigApiKey`: ランタイム認証全体の読み込みを強制せずに、 - 設定プロバイダー向けのenv-marker認証をプロバイダーが解決。 - `amazon-bedrock`には、Bedrockのランタイム認証が - AWS SDKデフォルトチェーンを使うにもかかわらず、ここに組み込みのAWS env-marker resolverもあります。 -- `resolveSyntheticAuth`: プレーンテキスト秘密情報を永続化せずに、 - local/self-hostedやその他の設定ベース認証の利用可否をプロバイダーが公開可能 -- `shouldDeferSyntheticProfileAuth`: 保存済みのsynthetic profile - プレースホルダーを、env/configベース認証より低優先度としてプロバイダーが扱える -- `resolveDynamicModel`: ローカルの静的カタログにまだ存在しないモデルIDを - プロバイダーが受け付ける -- `prepareDynamicModel`: 動的解決を再試行する前に、 - メタデータ更新が必要であることをプロバイダーが示す -- `normalizeResolvedModel`: transportまたはbase URLの書き換えが - 必要であることをプロバイダーが示す -- `contributeResolvedModelCompat`: 他の互換transport経由で届いた場合でも、 - ベンダーモデル向けの互換フラグをプロバイダーが提供 -- `capabilities`: transcript/tooling/provider-familyの癖を - プロバイダーが公開 -- `normalizeToolSchemas`: 埋め込みランナーが見る前にツールスキーマを - プロバイダーが整形 -- `inspectToolSchemas`: 正規化後にtransport固有のスキーマ警告を - プロバイダーが表示 -- `resolveReasoningOutputMode`: ネイティブかタグ付きかの - reasoning-output契約をプロバイダーが選択 -- `prepareExtraParams`: モデルごとのリクエストパラメータを - プロバイダーがデフォルト化または正規化 -- `createStreamFn`: 通常のストリーム経路を完全にカスタムなtransportで - プロバイダーが置き換える -- `wrapStreamFn`: リクエストヘッダー/ボディ/モデル互換ラッパーを - プロバイダーが適用 -- `resolveTransportTurnState`: ターンごとのネイティブtransport - ヘッダーまたはメタデータをプロバイダーが提供 -- `resolveWebSocketSessionPolicy`: ネイティブWebSocketセッション用の - ヘッダーまたはセッションクールダウンポリシーをプロバイダーが提供 -- `createEmbeddingProvider`: コアのembedding switchboardではなく - プロバイダープラグイン側に属する場合、メモリembedding挙動をプロバイダーが所有 -- `formatApiKey`: 保存済み認証プロファイルを、transportが期待する - ランタイム`apiKey`文字列へプロバイダーが整形 -- `refreshOAuth`: 共通の`pi-ai` - refreshersでは足りない場合に、OAuth更新をプロバイダーが所有 -- `buildAuthDoctorHint`: OAuth更新 - 失敗時に修復ガイダンスをプロバイダーが追加 -- `matchesContextOverflowError`: 汎用ヒューリスティクスでは見逃す - プロバイダー固有のコンテキストウィンドウ超過エラーをプロバイダーが認識 -- `classifyFailoverReason`: プロバイダー固有の生transport/API - エラーを、レート制限や過負荷などのフェイルオーバー理由へプロバイダーがマッピング -- `isCacheTtlEligible`: どの上流モデルIDがprompt-cache TTLをサポートするかを - プロバイダーが判断 -- `buildMissingAuthMessage`: 汎用のauth-storeエラーを、 - プロバイダー固有の復旧ヒントにプロバイダーが置き換える -- `suppressBuiltInModel`: 古くなった上流行をプロバイダーが隠し、直接解決失敗時に - ベンダー所有のエラーを返せる -- `augmentModelCatalog`: 発見と設定マージの後に、synthetic/finalカタログ行を - プロバイダーが追加 -- `isBinaryThinking`: バイナリのオン/オフthinking UXを - プロバイダーが所有 -- `supportsXHighThinking`: 選択されたモデルを`xhigh`に - プロバイダーが対応させる -- `resolveDefaultThinkingLevel`: モデルファミリーの - デフォルト`/think`ポリシーをプロバイダーが所有 -- `applyConfigDefaults`: 認証モード、env、モデルファミリーに基づいて、 - 設定具体化中にプロバイダー固有のグローバルデフォルトをプロバイダーが適用 -- `isModernModelRef`: live/smoke向けの推奨モデル一致を - プロバイダーが所有 -- `prepareRuntimeAuth`: 設定済み資格情報を短命な - ランタイムトークンへプロバイダーが変換 -- `resolveUsageAuth`: `/usage` - や関連する状態/レポート画面向けの使用量/クォータ資格情報をプロバイダーが解決 -- `fetchUsageSnapshot`: 使用量エンドポイントの取得/解析を - プロバイダーが所有し、要約シェルと整形は引き続きコアが所有 -- `onModelSelected`: テレメトリーやプロバイダー所有のセッション記録管理など、 - 選択後の副作用をプロバイダーが実行 +- `normalizeModelId`: プロバイダーが、検索または正規化の前に + レガシー/プレビューモデルIDを正規化する +- `normalizeTransport`: プロバイダーが、汎用モデル組み立ての前にトランスポートファミリーの`api` / `baseUrl`を正規化する。 + OpenClawはまず一致したプロバイダーを確認し、 + その後、実際にトランスポートを変更するものが見つかるまで、他のフック対応プロバイダープラグインを確認します +- `normalizeConfig`: プロバイダーが、ランタイムで使用する前に`models.providers.`設定を正規化する。 + OpenClawはまず一致したプロバイダーを確認し、その後、 + 実際に設定を変更するものが見つかるまで、他のフック対応プロバイダープラグインを確認します。どの + プロバイダーフックも設定を書き換えない場合でも、バンドル版のGoogleファミリーヘルパーは引き続き + サポート対象のGoogleプロバイダーエントリーを正規化します。 +- `applyNativeStreamingUsageCompat`: プロバイダーが、設定プロバイダー向けにエンドポイント主導のネイティブストリーミング使用量互換リライトを適用する +- `resolveConfigApiKey`: プロバイダーが、完全なランタイム認証の読み込みを強制せずに + 設定プロバイダー向けの環境マーカー認証を解決する。 + `amazon-bedrock`にはここにAWS環境マーカー用の組み込みリゾルバーもありますが、 + Bedrockランタイム認証自体はAWS SDKのデフォルトチェーンを使用します。 +- `resolveSyntheticAuth`: プロバイダーが、平文のシークレットを永続化せずに + ローカル/セルフホスト型またはその他の設定ベース認証の可用性を公開できる +- `shouldDeferSyntheticProfileAuth`: プロバイダーが、保存された合成プロファイル + プレースホルダーを、環境変数/設定ベース認証より低い優先順位としてマークできる +- `resolveDynamicModel`: プロバイダーが、まだローカルの + 静的カタログに存在しないモデルIDを受け入れる +- `prepareDynamicModel`: プロバイダーが、動的解決の再試行前に + メタデータ更新を必要とする +- `normalizeResolvedModel`: プロバイダーが、トランスポートまたはベースURLの書き換えを必要とする +- `contributeResolvedModelCompat`: プロバイダーが、別の互換トランスポート経由で届いた場合でも、 + 自社ベンダーモデル向けの互換フラグを提供する +- `capabilities`: プロバイダーが文字起こし/ツール/プロバイダーファミリーの癖を公開する +- `normalizeToolSchemas`: プロバイダーが、埋め込みランナーが参照する前に + ツールスキーマを整える +- `inspectToolSchemas`: プロバイダーが、正規化後に + トランスポート固有のスキーマ警告を提示する +- `resolveReasoningOutputMode`: プロバイダーが、ネイティブとタグ付きの + reasoning出力契約を選択する +- `prepareExtraParams`: プロバイダーが、モデルごとのリクエストパラメータをデフォルト設定または正規化する +- `createStreamFn`: プロバイダーが通常のストリーム経路を + 完全なカスタムトランスポートに置き換える +- `wrapStreamFn`: プロバイダーがリクエストヘッダー/ボディ/モデル互換ラッパーを適用する +- `resolveTransportTurnState`: プロバイダーが、ターンごとのネイティブトランスポート + ヘッダーまたはメタデータを提供する +- `resolveWebSocketSessionPolicy`: プロバイダーが、ネイティブWebSocketセッション + ヘッダーまたはセッションクールダウンポリシーを提供する +- `createEmbeddingProvider`: プロバイダーが、コアの埋め込みスイッチボードではなく + プロバイダープラグインに属するメモリ埋め込み動作を所有する +- `formatApiKey`: プロバイダーが、保存された認証プロファイルを + トランスポートが期待する実行時`apiKey`文字列へ整形する +- `refreshOAuth`: プロバイダーが、共有の`pi-ai` + リフレッシャーでは不十分な場合にOAuth更新を所有する +- `buildAuthDoctorHint`: プロバイダーが、OAuth更新に失敗したときに + 修復ガイダンスを追加する +- `matchesContextOverflowError`: プロバイダーが、汎用ヒューリスティクスでは見逃される + プロバイダー固有のコンテキストウィンドウ超過エラーを認識する +- `classifyFailoverReason`: プロバイダーが、プロバイダー固有の生のトランスポート/API + エラーを、レート制限や過負荷などのフェイルオーバー理由に対応付ける +- `isCacheTtlEligible`: プロバイダーが、どの上流モデルIDがプロンプトキャッシュTTLをサポートするかを判断する +- `buildMissingAuthMessage`: プロバイダーが、汎用認証ストアエラーを + プロバイダー固有の復旧ヒントに置き換える +- `suppressBuiltInModel`: プロバイダーが、古くなった上流行を非表示にし、 + 直接解決の失敗時にはベンダー所有のエラーを返せる +- `augmentModelCatalog`: プロバイダーが、検出と設定マージの後に + 合成/最終カタログ行を追加する +- `isBinaryThinking`: プロバイダーが、二値のオン/オフthinking UXを所有する +- `supportsXHighThinking`: プロバイダーが、選択したモデルで`xhigh`を有効にする +- `resolveDefaultThinkingLevel`: プロバイダーが、モデルファミリー向けの + デフォルト`/think`ポリシーを所有する +- `applyConfigDefaults`: プロバイダーが、認証モード、環境変数、またはモデルファミリーに基づいて、 + 設定具体化中にプロバイダー固有のグローバルデフォルトを適用する +- `isModernModelRef`: プロバイダーが、ライブ/スモーク向けの推奨モデル照合を所有する +- `prepareRuntimeAuth`: プロバイダーが、設定済み資格情報を + 短命な実行時トークンに変換する +- `resolveUsageAuth`: プロバイダーが、`/usage` + や関連するステータス/レポート画面向けの使用量/クォータ資格情報を解決する +- `fetchUsageSnapshot`: プロバイダーが使用量エンドポイントの取得/解析を所有し、 + コアは引き続き概要の外枠と整形を所有する +- `onModelSelected`: プロバイダーが、テレメトリやプロバイダー所有セッション管理のような + モデル選択後の副作用を実行する 現在のバンドル例: - `anthropic`: Claude 4.6の前方互換フォールバック、認証修復ヒント、使用量 - エンドポイント取得、cache-TTL/provider-familyメタデータ、認証対応のグローバル + エンドポイントの取得、キャッシュTTL/プロバイダーファミリーのメタデータ、および認証を考慮したグローバル 設定デフォルト -- `amazon-bedrock`: Bedrock固有のスロットル/未準備エラーに対する - プロバイダー所有のコンテキスト超過判定とフェイルオーバー理由分類に加え、 - Anthropicトラフィック上のClaude専用replay-policy - ガードのための共通`anthropic-by-model` replayファミリー -- `anthropic-vertex`: Anthropic-message - トラフィック上のClaude専用replay-policyガード -- `openrouter`: モデルIDの透過、リクエストラッパー、プロバイダーcapability - ヒント、プロキシGeminiトラフィック上のGemini thought-signatureサニタイズ、 - `openrouter-thinking` streamファミリーを通じたプロキシ - reasoning注入、ルーティングメタデータ転送、cache-TTLポリシー +- `amazon-bedrock`: Bedrock固有のスロットリング/未準備エラー向けに、プロバイダー所有のコンテキスト超過一致と + フェイルオーバー理由分類を提供し、さらに + Claude専用のリプレイポリシー保護のための共有`anthropic-by-model`リプレイファミリーを + Anthropicトラフィックに適用 +- `anthropic-vertex`: Anthropicメッセージ + トラフィック向けのClaude専用リプレイポリシー保護 +- `openrouter`: モデルIDのパススルー、リクエストラッパー、プロバイダー capability + ヒント、プロキシGeminiトラフィック上でのGemini thought-signatureサニタイズ、 + `openrouter-thinking`ストリームファミリー経由のプロキシreasoning注入、ルーティング + メタデータの転送、およびキャッシュTTLポリシー - `github-copilot`: オンボーディング/デバイスログイン、前方互換モデルフォールバック、 - Claude-thinking transcriptヒント、ランタイムトークン交換、使用量エンドポイント - 取得 -- `openai`: GPT-5.4の前方互換フォールバック、直接OpenAI transport - 正規化、Codex対応の認証不足ヒント、Spark抑制、syntheticな - OpenAI/Codexカタログ行、thinking/live-modelポリシー、使用量トークンエイリアス - 正規化（`input` / `output`および`prompt` / `completion`ファミリー）、 - ネイティブOpenAI/Codexラッパー用の共通`openai-responses-defaults` streamファミリー、 - provider-familyメタデータ、`gpt-image-1`向けのバンドル済み画像生成プロバイダー - 登録、および`sora-2`向けのバンドル済み動画生成プロバイダー + Claude-thinking文字起こしヒント、ランタイムトークン交換、および使用量エンドポイント + の取得 +- `openai`: GPT-5.4の前方互換フォールバック、直接OpenAIトランスポート + 正規化、Codex対応の認証不足ヒント、Sparkの抑制、合成 + OpenAI/Codexカタログ行、thinking/ライブモデルポリシー、使用量トークンエイリアス + 正規化（`input` / `output`および`prompt` / `completion`ファミリー）、ネイティブOpenAI/Codex + ラッパー向けの共有`openai-responses-defaults`ストリームファミリー、 + プロバイダーファミリーのメタデータ、`gpt-image-1`向けのバンドル版画像生成プロバイダー + 登録、および`sora-2`向けのバンドル版動画生成プロバイダー 登録 - `google`および`google-gemini-cli`: Gemini 3.1の前方互換フォールバック、 - ネイティブGemini replay検証、ブートストラップreplayサニタイズ、タグ付き - reasoning-outputモード、modern-model一致、Gemini image-previewモデル向けのバンドル済み画像生成 - プロバイダー登録、およびVeoモデル向けのバンドル済み - 動画生成プロバイダー登録。Gemini CLI OAuthはさらに - 認証プロファイルのトークン整形、使用量トークン解析、使用量画面向けのクォータ - エンドポイント取得も所有します -- `moonshot`: 共通transport、プラグイン所有のthinkingペイロード正規化 -- `kilocode`: 共通transport、プラグイン所有のリクエストヘッダー、reasoningペイロード - 正規化、プロキシGemini thought-signatureサニタイズ、cache-TTL + ネイティブGeminiリプレイ検証、ブートストラップリプレイサニタイズ、タグ付き + reasoning出力モード、モダンモデル照合、Gemini image-previewモデル向けのバンドル版画像生成 + プロバイダー登録、およびVeoモデル向けのバンドル版 + 動画生成プロバイダー登録。Gemini CLI OAuthはさらに、 + 使用量画面向けの認証プロファイルトークン整形、使用量トークン解析、クォータエンドポイント + 取得も所有します +- `moonshot`: 共有トランスポート、プラグイン所有のthinkingペイロード正規化 +- `kilocode`: 共有トランスポート、プラグイン所有のリクエストヘッダー、reasoningペイロード + 正規化、プロキシGemini thought-signatureサニタイズ、およびキャッシュTTL ポリシー -- `zai`: GLM-5の前方互換フォールバック、`tool_stream`デフォルト、cache-TTL - ポリシー、binary-thinking/live-modelポリシー、使用量認証 + クォータ取得。 - 不明な`glm-5*` IDは、バンドル済みの`glm-4.7`テンプレートから合成されます -- `xai`: ネイティブResponses transport正規化、Grok高速バリアント向けの`/fast` - エイリアス書き換え、デフォルト`tool_stream`、xAI固有のtool-schema / - reasoning-payloadクリーンアップ、およびバンドル済み動画生成プロバイダー - `grok-imagine-video`登録 -- `mistral`: プラグイン所有のcapabilityメタデータ -- `opencode`および`opencode-go`: プラグイン所有のcapabilityメタデータに加え、 +- `zai`: GLM-5の前方互換フォールバック、`tool_stream`デフォルト、キャッシュTTL + ポリシー、二値thinking/ライブモデルポリシー、および使用量認証 + クォータ取得。 + 不明な`glm-5*` IDは、バンドル版`glm-4.7`テンプレートから合成されます +- `xai`: ネイティブResponsesトランスポート正規化、Grok高速バリアント向けの + `/fast`エイリアス書き換え、デフォルト`tool_stream`、xAI固有のツールスキーマ / + reasoningペイロード整理、および`grok-imagine-video`向けのバンドル版動画生成プロバイダー + 登録 +- `mistral`: プラグイン所有の capabilityメタデータ +- `opencode`および`opencode-go`: プラグイン所有の capabilityメタデータに加え、 プロキシGemini thought-signatureサニタイズ - `alibaba`: `alibaba/wan2.6-t2v`のような直接Wanモデル参照向けの プラグイン所有動画生成カタログ -- `byteplus`: プラグイン所有カタログに加え、Seedance text-to-video/image-to-videoモデル向けの - バンドル済み動画生成プロバイダー登録 -- `fal`: FLUX画像モデル向けのホスト型サードパーティ画像生成プロバイダー - 登録と、ホスト型サードパーティ動画モデル向けのバンドル済み +- `byteplus`: プラグイン所有カタログに加え、Seedanceのテキストから動画/画像から動画モデル向けの + バンドル版動画生成プロバイダー登録 +- `fal`: ホスト型サードパーティ動画モデル向けの + バンドル版動画生成プロバイダー登録、およびFLUX画像モデル向けのホスト型サードパーティ画像生成プロバイダー + 登録に加え、ホスト型サードパーティ動画モデル向けのバンドル版 動画生成プロバイダー登録 - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway`, および`volcengine`: プラグイン所有カタログのみ -- `qwen`: テキストモデル向けのプラグイン所有カタログに加え、 - そのマルチモーダル画面向けの共通media-understandingおよび動画生成プロバイダー登録。 - Qwen動画生成は、`wan2.6-t2v`や`wan2.7-r2v`などの - バンドル済みWanモデルとともに、標準DashScope動画エンドポイントを使用します -- `runway`: `gen4.5`のようなネイティブRunwayタスクベースモデル向けの - プラグイン所有動画生成プロバイダー登録 -- `minimax`: プラグイン所有カタログ、Hailuo動画モデル向けのバンドル済み動画生成プロバイダー - 登録、`image-01`向けのバンドル済み画像生成プロバイダー - 登録、ハイブリッドAnthropic/OpenAI replay-policy +- `qwen`: テキストモデル向けのプラグイン所有カタログに加え、その + マルチモーダル画面向けの共有media-understandingおよび動画生成プロバイダー登録。 + Qwen動画生成は、`wan2.6-t2v`や`wan2.7-r2v`のような + バンドル版Wanモデルを伴う標準DashScope動画エンドポイントを使用します +- `runway`: `gen4.5`のようなネイティブ + Runwayタスクベースモデル向けのプラグイン所有動画生成プロバイダー登録 +- `minimax`: プラグイン所有カタログ、Hailuo動画モデル向けのバンドル版動画生成プロバイダー + 登録、`image-01`向けのバンドル版画像生成プロバイダー + 登録、ハイブリッドAnthropic/OpenAIリプレイポリシー 選択、および使用量認証/スナップショットロジック -- `together`: プラグイン所有カタログに加え、Wan動画モデル向けのバンドル済み動画生成 - プロバイダー登録 +- `together`: プラグイン所有カタログに加え、Wan動画モデル向けのバンドル版動画生成プロバイダー + 登録 - `xiaomi`: プラグイン所有カタログに加え、使用量認証/スナップショットロジック -バンドル済みの`openai`プラグインは現在、`openai`と -`openai-codex`の両方のプロバイダーIDを所有しています。 +バンドル版`openai`プラグインは現在、両方のプロバイダーIDである`openai`と +`openai-codex`を所有します。 -以上は、OpenClawの通常transportに収まるプロバイダーを対象にしています。完全に -カスタムなリクエスト実行器を必要とするプロバイダーは、別の、より深い拡張サーフェスです。 +これで、OpenClawの通常トランスポートにまだ適合するプロバイダーを網羅しています。完全にカスタムのリクエスト実行子を必要とするプロバイダーは、 +別の、より深い拡張サーフェスになります。 ## APIキーのローテーション - 選択されたプロバイダー向けの汎用プロバイダーローテーションをサポートします。 -- 複数キーの設定方法: - - `OPENCLAW_LIVE__KEY`（単一のlive override、最優先） +- 複数キーは以下で設定します: + - `OPENCLAW_LIVE__KEY`（単一のライブ上書き、最優先） - `_API_KEYS`（カンマまたはセミコロン区切りのリスト） - `_API_KEY`（プライマリキー） - `_API_KEY_*`（番号付きリスト、例: `_API_KEY_1`） -- Googleプロバイダーでは、フォールバックとして`GOOGLE_API_KEY`も含まれます。 -- キー選択順序は優先度を保持し、値を重複排除します。 -- リクエストは、レート制限応答時のみ次のキーで再試行されます（ - 例: `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Googleプロバイダーでは、`GOOGLE_API_KEY`もフォールバックとして含まれます。 +- キーの選択順序は優先順位を維持し、値の重複を排除します。 +- リクエストは、レート制限レスポンスのときだけ次のキーで再試行されます（例: + `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded`、または周期的な使用量制限メッセージ）。 + `workers_ai ... quota limit exceeded`、または定期的な使用量制限メッセージ）。 - レート制限以外の失敗は即座に失敗し、キーのローテーションは試行されません。 - すべての候補キーが失敗した場合、最後の試行の最終エラーが返されます。 -## 組み込みプロバイダー（pi-ai catalog） +## 組み込みプロバイダー（pi-aiカタログ） -OpenClawにはpi‑ai catalogが同梱されています。これらのプロバイダーでは +OpenClawにはpi‑aiカタログが同梱されています。これらのプロバイダーでは `models.providers`設定は**不要**です。認証を設定してモデルを選ぶだけです。 ### OpenAI - プロバイダー: `openai` - 認証: `OPENAI_API_KEY` -- 任意のローテーション: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, および`OPENCLAW_LIVE_OPENAI_KEY`（単一override） -- 例のモデル: `openai/gpt-5.4`, `openai/gpt-5.4-pro` +- 任意のローテーション: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, に加えて`OPENCLAW_LIVE_OPENAI_KEY`（単一上書き） +- モデル例: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- デフォルトtransportは`auto`です（WebSocket優先、SSEフォールバック） -- モデルごとの上書きは`agents.defaults.models["openai/"].params.transport`で行います（`"sse"`, `"websocket"`, または`"auto"`） -- OpenAI Responses WebSocket warm-upは、`params.openaiWsWarmup`（`true`/`false`）によりデフォルトで有効です -- OpenAI priority processingは、`agents.defaults.models["openai/"].params.serviceTier`で有効化できます -- `/fast`と`params.fastMode`は、直接の`openai/*` Responsesリクエストを`api.openai.com`上の`service_tier=priority`へマッピングします -- 共有の`/fast`トグルではなく明示的なtierを使いたい場合は、`params.serviceTier`を使用してください -- 非表示のOpenClaw attributionヘッダー（`originator`, `version`, - `User-Agent`）は、`api.openai.com`へのネイティブOpenAIトラフィックにのみ適用され、 - 汎用のOpenAI互換プロキシには適用されません -- ネイティブOpenAIルートでは、Responsesの`store`、prompt-cacheヒント、 - OpenAI reasoning互換のペイロード整形も維持されます。 - プロキシルートでは維持されません -- `openai/gpt-5.3-codex-spark`は、live OpenAI APIが拒否するため、OpenClawでは意図的に抑制されています。SparkはCodex専用として扱われます +- デフォルトトランスポートは`auto`です（WebSocket優先、SSEフォールバック） +- モデルごとの上書きは`agents.defaults.models["openai/"].params.transport`（`"sse"`、`"websocket"`、または`"auto"`）で行います +- OpenAI Responses WebSocketウォームアップは、`params.openaiWsWarmup`（`true`/`false`）によりデフォルトで有効です +- OpenAI優先処理は`agents.defaults.models["openai/"].params.serviceTier`で有効にできます +- `/fast`および`params.fastMode`は、直接の`openai/*` Responsesリクエストを`api.openai.com`上の`service_tier=priority`にマップします +- 共有の`/fast`トグルではなく明示的なティアを使いたい場合は`params.serviceTier`を使用してください +- 非表示のOpenClawアトリビューションヘッダー（`originator`, `version`, + `User-Agent`）は、汎用OpenAI互換プロキシではなく、`api.openai.com`へのネイティブOpenAIトラフィックにのみ適用されます +- ネイティブOpenAIルートは、Responsesの`store`、プロンプトキャッシュヒント、 + OpenAI reasoning互換ペイロード整形も維持します。プロキシルートでは維持されません +- `openai/gpt-5.3-codex-spark`は、ライブのOpenAI APIが拒否するため、OpenClawでは意図的に抑制されています。SparkはCodex専用として扱われます ```json5 { @@ -288,12 +281,12 @@ OpenClawにはpi‑ai catalogが同梱されています。これらのプロバ - プロバイダー: `anthropic` - 認証: `ANTHROPIC_API_KEY` -- 任意のローテーション: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, および`OPENCLAW_LIVE_ANTHROPIC_KEY`（単一override） -- 例のモデル: `anthropic/claude-opus-4-6` +- 任意のローテーション: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, に加えて`OPENCLAW_LIVE_ANTHROPIC_KEY`（単一上書き） +- モデル例: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- 直接の公開Anthropicリクエストでは、`api.anthropic.com`に送られるAPIキー認証とOAuth認証のトラフィックを含め、共有の`/fast`トグルと`params.fastMode`をサポートします。OpenClawはこれをAnthropicの`service_tier`（`auto`対`standard_only`）へマッピングします -- Anthropic注記: Anthropicのスタッフから、OpenClaw形式のClaude CLI利用は再び許可されていると伝えられたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはClaude CLI再利用と`claude -p`利用をこの統合向けに認可済みとして扱います。 -- Anthropic setup-tokenも、引き続きサポートされるOpenClawトークン経路として利用可能ですが、OpenClawは現在、利用可能な場合はClaude CLI再利用と`claude -p`を優先します。 +- 直接の公開Anthropicリクエストは、共有の`/fast`トグルと`params.fastMode`もサポートし、`api.anthropic.com`へ送られるAPIキー認証およびOAuth認証トラフィックを含みます。OpenClawはこれをAnthropicの`service_tier`（`auto`対`standard_only`）にマップします +- Anthropicに関する注記: Anthropicスタッフから、OpenClawスタイルのClaude CLI使用は再び許可されていると伝えられたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはClaude CLIの再利用と`claude -p`の使用をこの統合で認可済みとして扱います。 +- Anthropic setup-tokenは、引き続きサポートされたOpenClawトークン経路として利用可能ですが、OpenClawは現在、利用可能であればClaude CLIの再利用と`claude -p`を優先します。 ```json5 { @@ -305,17 +298,17 @@ OpenClawにはpi‑ai catalogが同梱されています。これらのプロバ - プロバイダー: `openai-codex` - 認証: OAuth（ChatGPT） -- 例のモデル: `openai-codex/gpt-5.4` -- CLI: `openclaw onboard --auth-choice openai-codex` または `openclaw models auth login --provider openai-codex` -- デフォルトtransportは`auto`です（WebSocket優先、SSEフォールバック） -- モデルごとの上書きは`agents.defaults.models["openai-codex/"].params.transport`で行います（`"sse"`, `"websocket"`, または`"auto"`） -- `params.serviceTier`もネイティブCodex Responsesリクエスト（`chatgpt.com/backend-api`）で転送されます -- 非表示のOpenClaw attributionヘッダー（`originator`, `version`, - `User-Agent`）は、`chatgpt.com/backend-api`へのネイティブCodexトラフィックにのみ付与され、 - 汎用のOpenAI互換プロキシには付与されません -- 直接の`openai/*`と同じ`/fast`トグルおよび`params.fastMode`設定を共有し、OpenClawはこれを`service_tier=priority`へマッピングします -- `openai-codex/gpt-5.3-codex-spark`は、Codex OAuthカタログが公開している場合は引き続き利用可能です。利用権限に依存します -- `openai-codex/gpt-5.4`はネイティブの`contextWindow = 1050000`と、デフォルトのランタイム`contextTokens = 272000`を維持します。ランタイム上限は`models.providers.openai-codex.models[].contextTokens`で上書きしてください +- モデル例: `openai-codex/gpt-5.4` +- CLI: `openclaw onboard --auth-choice openai-codex`または`openclaw models auth login --provider openai-codex` +- デフォルトトランスポートは`auto`です（WebSocket優先、SSEフォールバック） +- モデルごとの上書きは`agents.defaults.models["openai-codex/"].params.transport`（`"sse"`、`"websocket"`、または`"auto"`）で行います +- `params.serviceTier`は、ネイティブCodex Responsesリクエスト（`chatgpt.com/backend-api`）でも転送されます +- 非表示のOpenClawアトリビューションヘッダー（`originator`, `version`, + `User-Agent`）は、汎用OpenAI互換プロキシではなく、 + `chatgpt.com/backend-api`へのネイティブCodexトラフィックにのみ付与されます +- 直接の`openai/*`と同じ`/fast`トグルおよび`params.fastMode`設定を共有し、OpenClawはこれを`service_tier=priority`にマップします +- `openai-codex/gpt-5.3-codex-spark`は、Codex OAuthカタログがそれを公開している場合は引き続き利用可能です。利用権に依存します +- `openai-codex/gpt-5.4`は、ネイティブの`contextWindow = 1050000`とデフォルトの実行時`contextTokens = 272000`を維持します。実行時上限は`models.providers.openai-codex.models[].contextTokens`で上書きできます - ポリシー注記: OpenAI Codex OAuthは、OpenClawのような外部ツール/ワークフロー向けに明示的にサポートされています。 ```json5 @@ -347,8 +340,8 @@ OpenClawにはpi‑ai catalogが同梱されています。これらのプロバ - 認証: `OPENCODE_API_KEY`（または`OPENCODE_ZEN_API_KEY`） - Zenランタイムプロバイダー: `opencode` - Goランタイムプロバイダー: `opencode-go` -- 例のモデル: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` -- CLI: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go` +- モデル例: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` +- CLI: `openclaw onboard --auth-choice opencode-zen`または`openclaw onboard --auth-choice opencode-go` ```json5 { @@ -360,148 +353,146 @@ OpenClawにはpi‑ai catalogが同梱されています。これらのプロバ - プロバイダー: `google` - 認証: `GEMINI_API_KEY` -- 任意のローテーション: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY`フォールバック、および`OPENCLAW_LIVE_GEMINI_KEY`（単一override） -- 例のモデル: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` -- 互換性: `google/gemini-3.1-flash-preview`を使うレガシーOpenClaw設定は、`google/gemini-3-flash-preview`に正規化されます +- 任意のローテーション: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY`フォールバック、および`OPENCLAW_LIVE_GEMINI_KEY`（単一上書き） +- モデル例: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` +- 互換性: `google/gemini-3.1-flash-preview`を使うレガシーOpenClaw設定は`google/gemini-3-flash-preview`へ正規化されます - CLI: `openclaw onboard --auth-choice gemini-api-key` -- 直接のGemini実行では、`agents.defaults.models["google/"].params.cachedContent` - （または旧式の`cached_content`）も受け付け、プロバイダーネイティブな - `cachedContents/...`ハンドルを転送します。GeminiのキャッシュヒットはOpenClawの`cacheRead`として表示されます +- 直接Gemini実行では、`agents.defaults.models["google/"].params.cachedContent` + （またはレガシーの`cached_content`）も受け付け、 + プロバイダーネイティブの`cachedContents/...`ハンドルを転送します。GeminiのキャッシュヒットはOpenClawの`cacheRead`として表示されます -### Google Vertex と Gemini CLI +### Google VertexとGemini CLI - プロバイダー: `google-vertex`, `google-gemini-cli` - 認証: Vertexはgcloud ADCを使用し、Gemini CLIは独自のOAuthフローを使用します -- 注意: OpenClawでのGemini CLI OAuthは非公式の統合です。サードパーティクライアントの利用後にGoogleアカウントの制限が発生したと報告しているユーザーもいます。進める場合はGoogleの利用規約を確認し、重要でないアカウントを使用してください。 -- Gemini CLI OAuthは、バンドル済みの`google`プラグインの一部として提供されます。 +- 注意: OpenClawでのGemini CLI OAuthは非公式な統合です。サードパーティクライアントの使用後にGoogleアカウントの制限が発生したと報告しているユーザーもいます。利用を続行する場合は、Googleの利用規約を確認し、重要ではないアカウントを使用してください。 +- Gemini CLI OAuthは、バンドル版`google`プラグインの一部として提供されます。 - まずGemini CLIをインストールします: - `brew install gemini-cli` - - または `npm install -g @google/gemini-cli` + - または`npm install -g @google/gemini-cli` - 有効化: `openclaw plugins enable google` - ログイン: `openclaw models auth login --provider google-gemini-cli --set-default` - デフォルトモデル: `google-gemini-cli/gemini-3-flash-preview` - - 注: `openclaw.json`にclient idやsecretを貼り付ける必要は**ありません**。CLIログインフローは - トークンをGatewayホスト上のauth profileに保存します。 + - 注: `openclaw.json`にクライアントIDやシークレットを貼り付けることは**ありません**。CLIログインフローは + Gatewayホスト上の認証プロファイルにトークンを保存します。 - ログイン後にリクエストが失敗する場合は、Gatewayホストで`GOOGLE_CLOUD_PROJECT`または`GOOGLE_CLOUD_PROJECT_ID`を設定してください。 - - Gemini CLIのJSON応答は`response`から解析され、使用量は - `stats`へフォールバックし、`stats.cached`はOpenClawの`cacheRead`へ正規化されます。 + - Gemini CLIのJSON返信は`response`から解析され、使用量は + `stats`にフォールバックし、`stats.cached`はOpenClawの`cacheRead`に正規化されます。 ### Z.AI（GLM） - プロバイダー: `zai` - 認証: `ZAI_API_KEY` -- 例のモデル: `zai/glm-5.1` +- モデル例: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - - エイリアス: `z.ai/*`と`z-ai/*`は`zai/*`に正規化されます - - `zai-api-key`は一致するZ.AIエンドポイントを自動検出し、`zai-coding-global`, `zai-coding-cn`, `zai-global`, および`zai-cn`は特定のサーフェスを強制します + - エイリアス: `z.ai/*`および`z-ai/*`は`zai/*`に正規化されます + - `zai-api-key`は一致するZ.AIエンドポイントを自動検出します。`zai-coding-global`、`zai-coding-cn`、`zai-global`、および`zai-cn`は特定のサーフェスを強制します ### Vercel AI Gateway - プロバイダー: `vercel-ai-gateway` - 認証: `AI_GATEWAY_API_KEY` -- 例のモデル: `vercel-ai-gateway/anthropic/claude-opus-4.6` +- モデル例: `vercel-ai-gateway/anthropic/claude-opus-4.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway - プロバイダー: `kilocode` - 認証: `KILOCODE_API_KEY` -- 例のモデル: `kilocode/kilo/auto` +- モデル例: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Base URL: `https://api.kilo.ai/api/gateway/` +- ベースURL: `https://api.kilo.ai/api/gateway/` - 静的フォールバックカタログには`kilocode/kilo/auto`が同梱されており、 - liveの`https://api.kilo.ai/api/gateway/models`検出により、ランタイム + ライブの`https://api.kilo.ai/api/gateway/models`検出によって実行時 カタログがさらに拡張される場合があります。 - `kilocode/kilo/auto`の背後にある正確な上流ルーティングはKilo Gatewayが所有しており、 OpenClawにハードコードされていません。 -セットアップの詳細は[/providers/kilocode](/ja-JP/providers/kilocode)を参照してください。 +設定の詳細は[/providers/kilocode](/ja-JP/providers/kilocode)を参照してください。 -### その他のバンドル済みプロバイダープラグイン +### その他のバンドル版プロバイダープラグイン - OpenRouter: `openrouter`（`OPENROUTER_API_KEY`） -- 例のモデル: `openrouter/auto` -- OpenClawは、リクエストが実際に`openrouter.ai`を対象としている場合にのみ、 - OpenRouterで文書化されているアプリattributionヘッダーを適用します +- モデル例: `openrouter/auto` +- OpenClawは、リクエストの実際の宛先が`openrouter.ai`である場合にのみ、 + OpenRouterが文書化しているアプリ属性ヘッダーを適用します - OpenRouter固有のAnthropic `cache_control`マーカーも同様に、 - 検証済みのOpenRouterルートにのみ適用され、任意のプロキシURLには適用されません -- OpenRouterは引き続きプロキシ型のOpenAI互換経路上にあるため、ネイティブ - OpenAI専用のリクエスト整形（`serviceTier`, Responsesの`store`, - prompt-cacheヒント、OpenAI reasoning互換ペイロード）は転送されません -- GeminiベースのOpenRouter参照では、プロキシGemini thought-signatureサニタイズ - のみ維持されます。ネイティブGemini replay検証やbootstrap書き換えは無効のままです + 任意のプロキシURLではなく、検証済みのOpenRouterルートにのみ適用されます +- OpenRouterは引き続きプロキシ形式のOpenAI互換経路上にあるため、ネイティブ + OpenAI専用のリクエスト整形（`serviceTier`、Responsesの`store`、 + プロンプトキャッシュヒント、OpenAI reasoning互換ペイロード）は転送されません +- GeminiベースのOpenRouter参照では、プロキシGeminiのthought-signatureサニタイズ + のみが維持されます。ネイティブGeminiのリプレイ検証およびブートストラップ書き換えは無効のままです - Kilo Gateway: `kilocode`（`KILOCODE_API_KEY`） -- 例のモデル: `kilocode/kilo/auto` -- GeminiベースのKilo参照でも同じプロキシGemini thought-signature - サニタイズ経路が維持されます。`kilocode/kilo/auto`やその他のプロキシreasoning非対応 - ヒントでは、プロキシreasoning注入はスキップされます +- モデル例: `kilocode/kilo/auto` +- GeminiベースのKilo参照では、同じプロキシGemini thought-signature + サニタイズ経路が維持されます。`kilocode/kilo/auto`やその他のプロキシでreasoning非対応 + のヒントでは、プロキシreasoning注入をスキップします - MiniMax: `minimax`（APIキー）および`minimax-portal`（OAuth） - 認証: `minimax`には`MINIMAX_API_KEY`、`minimax-portal`には`MINIMAX_OAUTH_TOKEN`または`MINIMAX_API_KEY` -- 例のモデル: `minimax/MiniMax-M2.7` または `minimax-portal/MiniMax-M2.7` -- MiniMaxのオンボーディング/APIキー設定では、`input: ["text", "image"]`付きの - 明示的なM2.7モデル定義が書き込まれます。バンドル済みプロバイダーカタログでは、 - そのプロバイダー設定が具体化されるまで、チャット参照は - テキスト専用のままです +- モデル例: `minimax/MiniMax-M2.7`または`minimax-portal/MiniMax-M2.7` +- MiniMaxのオンボーディング/APIキー設定では、 + `input: ["text", "image"]`を持つ明示的なM2.7モデル定義が書き込まれます。バンドル版プロバイダーカタログでは、そのプロバイダー設定が具体化されるまでは + チャット参照をテキスト専用のまま維持します - Moonshot: `moonshot`（`MOONSHOT_API_KEY`） -- 例のモデル: `moonshot/kimi-k2.5` +- モデル例: `moonshot/kimi-k2.5` - Kimi Coding: `kimi`（`KIMI_API_KEY`または`KIMICODE_API_KEY`） -- 例のモデル: `kimi/kimi-code` +- モデル例: `kimi/kimi-code` - Qianfan: `qianfan`（`QIANFAN_API_KEY`） -- 例のモデル: `qianfan/deepseek-v3.2` -- Qwen Cloud: `qwen`（`QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, または`DASHSCOPE_API_KEY`） -- 例のモデル: `qwen/qwen3.5-plus` +- モデル例: `qianfan/deepseek-v3.2` +- Qwen Cloud: `qwen`（`QWEN_API_KEY`、`MODELSTUDIO_API_KEY`、または`DASHSCOPE_API_KEY`） +- モデル例: `qwen/qwen3.5-plus` - NVIDIA: `nvidia`（`NVIDIA_API_KEY`） -- 例のモデル: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` +- モデル例: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` - StepFun: `stepfun` / `stepfun-plan`（`STEPFUN_API_KEY`） -- 例のモデル: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` +- モデル例: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` - Together: `together`（`TOGETHER_API_KEY`） -- 例のモデル: `together/moonshotai/Kimi-K2.5` +- モデル例: `together/moonshotai/Kimi-K2.5` - Venice: `venice`（`VENICE_API_KEY`） - Xiaomi: `xiaomi`（`XIAOMI_API_KEY`） -- 例のモデル: `xiaomi/mimo-v2-flash` +- モデル例: `xiaomi/mimo-v2-flash` - Vercel AI Gateway: `vercel-ai-gateway`（`AI_GATEWAY_API_KEY`） - Hugging Face Inference: `huggingface`（`HUGGINGFACE_HUB_TOKEN`または`HF_TOKEN`） - Cloudflare AI Gateway: `cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`） - Volcengine: `volcengine`（`VOLCANO_ENGINE_API_KEY`） -- 例のモデル: `volcengine-plan/ark-code-latest` +- モデル例: `volcengine-plan/ark-code-latest` - BytePlus: `byteplus`（`BYTEPLUS_API_KEY`） -- 例のモデル: `byteplus-plan/ark-code-latest` +- モデル例: `byteplus-plan/ark-code-latest` - xAI: `xai`（`XAI_API_KEY`） - - ネイティブのバンドル済みxAIリクエストはxAI Responses経路を使用します - - `/fast`または`params.fastMode: true`は、`grok-3`, `grok-3-mini`, - `grok-4`, および`grok-4-0709`をそれぞれの`*-fast`バリアントへ書き換えます - - `tool_stream`はデフォルトでオンです。無効化するには + - ネイティブのバンドル版xAIリクエストはxAI Responses経路を使用します + - `/fast`または`params.fastMode: true`は、`grok-3`、`grok-3-mini`、 + `grok-4`、および`grok-4-0709`をそれぞれの`*-fast`バリアントに書き換えます + - `tool_stream`はデフォルトで有効です。無効にするには、 `agents.defaults.models["xai/"].params.tool_stream`を`false`に 設定してください - Mistral: `mistral`（`MISTRAL_API_KEY`） -- 例のモデル: `mistral/mistral-large-latest` +- モデル例: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq`（`GROQ_API_KEY`） - Cerebras: `cerebras`（`CEREBRAS_API_KEY`） - - Cerebras上のGLMモデルでは、ID `zai-glm-4.7`および`zai-glm-4.6`を使用します。 - - OpenAI互換のbase URL: `https://api.cerebras.ai/v1`。 + - Cerebras上のGLMモデルは`zai-glm-4.7`および`zai-glm-4.6`というIDを使用します。 + - OpenAI互換ベースURL: `https://api.cerebras.ai/v1`。 - GitHub Copilot: `github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`） -- Hugging Face Inferenceの例のモデル: `huggingface/deepseek-ai/DeepSeek-R1`。CLI: `openclaw onboard --auth-choice huggingface-api-key`。[Hugging Face (Inference)](/ja-JP/providers/huggingface)を参照してください。 +- Hugging Face Inferenceのモデル例: `huggingface/deepseek-ai/DeepSeek-R1`。CLI: `openclaw onboard --auth-choice huggingface-api-key`。詳細は[Hugging Face (Inference)](/ja-JP/providers/huggingface)を参照してください。 -## `models.providers`経由のプロバイダー（custom/base URL） +## `models.providers`経由のプロバイダー（カスタム/ベースURL） **カスタム**プロバイダーまたは -OpenAI/Anthropic互換プロキシを追加するには、`models.providers`（または`models.json`）を使います。 +OpenAI/Anthropic互換プロキシを追加するには、`models.providers`（または`models.json`）を使用します。 -以下のバンドル済みプロバイダープラグインの多くは、すでにデフォルトカタログを公開しています。 -デフォルトのbase URL、ヘッダー、モデル一覧を上書きしたい場合にのみ、 +以下のバンドル版プロバイダープラグインの多くは、すでにデフォルトカタログを公開しています。 +デフォルトのベースURL、ヘッダー、またはモデル一覧を上書きしたい場合にのみ、 明示的な`models.providers.`エントリーを使用してください。 ### Moonshot AI（Kimi） -Moonshotはバンドル済みプロバイダープラグインとして提供されています。デフォルトでは -組み込みプロバイダーを使用し、base URLまたはモデルメタデータを上書きする必要がある場合のみ -明示的な`models.providers.moonshot`エントリーを追加してください。 +Moonshotはバンドル版プロバイダープラグインとして提供されています。通常は組み込みプロバイダーを使用し、 +ベースURLまたはモデルメタデータを上書きする必要がある場合にのみ、明示的な`models.providers.moonshot`エントリーを追加してください。 - プロバイダー: `moonshot` - 認証: `MOONSHOT_API_KEY` -- 例のモデル: `moonshot/kimi-k2.5` -- CLI: `openclaw onboard --auth-choice moonshot-api-key` または `openclaw onboard --auth-choice moonshot-api-key-cn` +- モデル例: `moonshot/kimi-k2.5` +- CLI: `openclaw onboard --auth-choice moonshot-api-key`または`openclaw onboard --auth-choice moonshot-api-key-cn` Kimi K2モデルID: @@ -539,7 +530,7 @@ Kimi CodingはMoonshot AIのAnthropic互換エンドポイントを使用しま - プロバイダー: `kimi` - 認証: `KIMI_API_KEY` -- 例のモデル: `kimi/kimi-code` +- モデル例: `kimi/kimi-code` ```json5 { @@ -550,15 +541,15 @@ Kimi CodingはMoonshot AIのAnthropic互換エンドポイントを使用しま } ``` -旧式の`kimi/k2p5`も、互換モデルIDとして引き続き受け付けられます。 +レガシーな`kimi/k2p5`も互換モデルIDとして引き続き受け付けられます。 ### Volcano Engine（Doubao） -Volcano Engine（火山引擎）は、中国でDoubaoおよびその他のモデルへのアクセスを提供します。 +Volcano Engine（火山引擎）は、中国でDoubaoやその他のモデルへのアクセスを提供します。 - プロバイダー: `volcengine`（coding: `volcengine-plan`） - 認証: `VOLCANO_ENGINE_API_KEY` -- 例のモデル: `volcengine-plan/ark-code-latest` +- モデル例: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` ```json5 @@ -569,12 +560,13 @@ Volcano Engine（火山引擎）は、中国でDoubaoおよびその他のモデ } ``` -オンボーディングはデフォルトでcodingサーフェスを使用しますが、一般的な`volcengine/*` +オンボーディングではデフォルトでcodingサーフェスが選ばれますが、一般的な`volcengine/*` カタログも同時に登録されます。 -オンボーディング/設定モデルピッカーでは、Volcengine認証選択は -`volcengine/*`と`volcengine-plan/*`の両方の行を優先します。これらのモデルがまだ読み込まれていない場合、 -OpenClawは空のプロバイダースコープピッカーを表示する代わりに、フィルターなしカタログへフォールバックします。 +オンボーディング/モデル設定ピッカーでは、Volcengineの認証選択は +`volcengine/*`行と`volcengine-plan/*`行の両方を優先します。これらのモデルがまだ読み込まれていない場合、 +OpenClawは空のプロバイダースコープ付きピッカーを表示する代わりに、 +フィルターなしカタログへフォールバックします。 利用可能なモデル: @@ -584,7 +576,7 @@ OpenClawは空のプロバイダースコープピッカーを表示する代わ - `volcengine/glm-4-7-251222`（GLM 4.7） - `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K） -Codingモデル（`volcengine-plan`）: +コーディングモデル（`volcengine-plan`）: - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -592,13 +584,13 @@ Codingモデル（`volcengine-plan`）: - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus（International） +### BytePlus（国際） -BytePlus ARKは、国際ユーザー向けにVolcano Engineと同じモデル群へのアクセスを提供します。 +BytePlus ARKは、国際ユーザー向けにVolcano Engineと同じモデルへのアクセスを提供します。 - プロバイダー: `byteplus`（coding: `byteplus-plan`） - 認証: `BYTEPLUS_API_KEY` -- 例のモデル: `byteplus-plan/ark-code-latest` +- モデル例: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` ```json5 @@ -609,12 +601,13 @@ BytePlus ARKは、国際ユーザー向けにVolcano Engineと同じモデル群 } ``` -オンボーディングはデフォルトでcodingサーフェスを使用しますが、一般的な`byteplus/*` +オンボーディングではデフォルトでcodingサーフェスが選ばれますが、一般的な`byteplus/*` カタログも同時に登録されます。 -オンボーディング/設定モデルピッカーでは、BytePlus認証選択は -`byteplus/*`と`byteplus-plan/*`の両方の行を優先します。これらのモデルがまだ読み込まれていない場合、 -OpenClawは空のプロバイダースコープピッカーを表示する代わりに、フィルターなしカタログへフォールバックします。 +オンボーディング/モデル設定ピッカーでは、BytePlusの認証選択は +`byteplus/*`行と`byteplus-plan/*`行の両方を優先します。これらのモデルがまだ読み込まれていない場合、 +OpenClawは空のプロバイダースコープ付きピッカーを表示する代わりに、 +フィルターなしカタログへフォールバックします。 利用可能なモデル: @@ -622,7 +615,7 @@ OpenClawは空のプロバイダースコープピッカーを表示する代わ - `byteplus/kimi-k2-5-260127`（Kimi K2.5） - `byteplus/glm-4-7-251222`（GLM 4.7） -Codingモデル（`byteplus-plan`）: +コーディングモデル（`byteplus-plan`）: - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -636,7 +629,7 @@ Syntheticは、`synthetic`プロバイダーの背後でAnthropic互換モデル - プロバイダー: `synthetic` - 認証: `SYNTHETIC_API_KEY` -- 例のモデル: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` +- モデル例: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` ```json5 @@ -660,7 +653,7 @@ Syntheticは、`synthetic`プロバイダーの背後でAnthropic互換モデル ### MiniMax -MiniMaxはカスタムエンドポイントを使うため、`models.providers`経由で設定されます。 +MiniMaxはカスタムエンドポイントを使用するため、`models.providers`経由で設定します。 - MiniMax OAuth（Global）: `--auth-choice minimax-global-oauth` - MiniMax OAuth（CN）: `--auth-choice minimax-cn-oauth` @@ -669,11 +662,11 @@ MiniMaxはカスタムエンドポイントを使うため、`models.providers` - 認証: `minimax`には`MINIMAX_API_KEY`、`minimax-portal`には`MINIMAX_OAUTH_TOKEN`または `MINIMAX_API_KEY` -セットアップ詳細、モデルオプション、設定スニペットについては[/providers/minimax](/ja-JP/providers/minimax)を参照してください。 +設定の詳細、モデルオプション、設定スニペットについては[/providers/minimax](/ja-JP/providers/minimax)を参照してください。 -MiniMaxのAnthropic互換ストリーミング経路では、明示的に設定しない限り -OpenClawはthinkingをデフォルトで無効化し、`/fast on`は -`MiniMax-M2.7`を`MiniMax-M2.7-highspeed`へ書き換えます。 +MiniMaxのAnthropic互換ストリーミング経路では、OpenClawは +明示的に設定しない限りthinkingをデフォルトで無効にし、`/fast on`は +`MiniMax-M2.7`を`MiniMax-M2.7-highspeed`に書き換えます。 プラグイン所有のcapability分割: @@ -684,15 +677,15 @@ OpenClawはthinkingをデフォルトで無効化し、`/fast on`は ### Ollama -Ollamaはバンドル済みプロバイダープラグインとして提供され、OllamaのネイティブAPIを使用します。 +Ollamaはバンドル版プロバイダープラグインとして提供され、OllamaのネイティブAPIを使用します。 - プロバイダー: `ollama` - 認証: 不要（ローカルサーバー） -- 例のモデル: `ollama/llama3.3` +- モデル例: `ollama/llama3.3` - インストール: [https://ollama.com/download](https://ollama.com/download) ```bash -# Ollamaをインストールしてから、モデルをpullします: +# Ollamaをインストールし、その後モデルをpullします: ollama pull llama3.3 ``` @@ -704,21 +697,21 @@ ollama pull llama3.3 } ``` -Ollamaは、`OLLAMA_API_KEY`でオプトインするとローカルの`http://127.0.0.1:11434`で検出され、 -バンドル済みプロバイダープラグインによってOllamaが -`openclaw onboard`とモデルピッカーに直接追加されます。オンボーディング、cloud/localモード、 +`OLLAMA_API_KEY`でオプトインすると、Ollamaはローカルの`http://127.0.0.1:11434`で検出され、 +バンドル版プロバイダープラグインがOllamaを`openclaw onboard`と +モデルピッカーに直接追加します。オンボーディング、クラウド/ローカルモード、 カスタム設定については[/providers/ollama](/ja-JP/providers/ollama)を参照してください。 ### vLLM -vLLMは、local/self-hostedなOpenAI互換 -サーバー向けのバンドル済みプロバイダープラグインとして提供されます。 +vLLMは、ローカル/セルフホストのOpenAI互換 +サーバー向けバンドル版プロバイダープラグインとして提供されます。 - プロバイダー: `vllm` -- 認証: 任意（サーバー構成による） -- デフォルトbase URL: `http://127.0.0.1:8000/v1` +- 認証: 任意（サーバーによる） +- デフォルトベースURL: `http://127.0.0.1:8000/v1` -ローカルで自動検出にオプトインするには（サーバーが認証を強制しない場合は任意の値で可）: +ローカルで自動検出にオプトインするには（サーバーで認証を強制しない場合は任意の値で動作します）: ```bash export VLLM_API_KEY="vllm-local" @@ -738,15 +731,15 @@ export VLLM_API_KEY="vllm-local" ### SGLang -SGLangは、高速なself-hosted -OpenAI互換サーバー向けのバンドル済みプロバイダープラグインとして提供されます。 +SGLangは、高速なセルフホスト +OpenAI互換サーバー向けバンドル版プロバイダープラグインとして提供されます。 - プロバイダー: `sglang` -- 認証: 任意（サーバー構成による） -- デフォルトbase URL: `http://127.0.0.1:30000/v1` +- 認証: 任意（サーバーによる） +- デフォルトベースURL: `http://127.0.0.1:30000/v1` -ローカルで自動検出にオプトインするには（サーバーが -認証を強制しない場合は任意の値で可）: +ローカルで自動検出にオプトインするには（サーバーが認証を +強制しない場合は任意の値で動作します）: ```bash export SGLANG_API_KEY="sglang-local" @@ -764,7 +757,7 @@ export SGLANG_API_KEY="sglang-local" 詳細は[/providers/sglang](/ja-JP/providers/sglang)を参照してください。 -### ローカルプロキシ（LM Studio、vLLM、LiteLLM など） +### ローカルプロキシ（LM Studio、vLLM、LiteLLMなど） 例（OpenAI互換）: @@ -773,7 +766,7 @@ export SGLANG_API_KEY="sglang-local" agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "Local" } }, + models: { "lmstudio/my-local-model": { alias: "ローカル" } }, }, }, models: { @@ -801,21 +794,21 @@ export SGLANG_API_KEY="sglang-local" 注記: -- カスタムプロバイダーでは、`reasoning`, `input`, `cost`, `contextWindow`, および`maxTokens`は任意です。 - 省略した場合、OpenClawは次をデフォルトとして使用します: +- カスタムプロバイダーでは、`reasoning`、`input`、`cost`、`contextWindow`、および`maxTokens`は任意です。 + 省略した場合、OpenClawのデフォルトは以下になります: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- 推奨: プロキシ/モデルの制限に合う明示的な値を設定してください。 -- 非ネイティブエンドポイント（`api.openai.com`以外のホストを持つ非空の`baseUrl`）で`api: "openai-completions"`を使う場合、OpenClawは、未対応の`developer`ロールによるプロバイダー400エラーを避けるため、`compat.supportsDeveloperRole: false`を強制します。 -- プロキシ型のOpenAI互換ルートでも、ネイティブOpenAI専用のリクエスト - 整形はスキップされます: `service_tier`なし、Responsesの`store`なし、prompt-cacheヒントなし、 - OpenAI reasoning互換ペイロード整形なし、非表示のOpenClaw attribution - ヘッダーなし。 -- `baseUrl`が空または省略されている場合、OpenClawはデフォルトのOpenAI挙動（`api.openai.com`へ解決される）を維持します。 -- 安全のため、非ネイティブな`openai-completions`エンドポイントでは、明示的な`compat.supportsDeveloperRole: true`も引き続き上書きされます。 +- 推奨: プロキシ/モデルの制限に一致する明示的な値を設定してください。 +- 非ネイティブエンドポイント（ホストが`api.openai.com`ではない非空の`baseUrl`）で`api: "openai-completions"`を使用する場合、OpenClawは、未対応の`developer`ロールによるプロバイダー400エラーを避けるため、`compat.supportsDeveloperRole: false`を強制します。 +- プロキシ形式のOpenAI互換ルートでは、ネイティブOpenAI専用のリクエスト + 整形もスキップされます。`service_tier`、Responsesの`store`、プロンプトキャッシュヒント、 + OpenAI reasoning互換ペイロード整形、非表示のOpenClawアトリビューション + ヘッダーは送信されません。 +- `baseUrl`が空または省略されている場合、OpenClawはデフォルトのOpenAI動作（`api.openai.com`に解決される）を維持します。 +- 安全のため、非ネイティブの`openai-completions`エンドポイントでは、明示的な`compat.supportsDeveloperRole: true`も引き続き上書きされます。 ## CLIの例 @@ -825,11 +818,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -完全な設定例については、[/gateway/configuration](/ja-JP/gateway/configuration)も参照してください。 +関連項目: 完全な設定例については[/gateway/configuration](/ja-JP/gateway/configuration)を参照してください。 ## 関連 - [Models](/ja-JP/concepts/models) — モデル設定とエイリアス -- [Model Failover](/ja-JP/concepts/model-failover) — フォールバックチェーンと再試行挙動 +- [Model Failover](/ja-JP/concepts/model-failover) — フォールバックチェーンと再試行動作 - [Configuration Reference](/ja-JP/gateway/configuration-reference#agent-defaults) — モデル設定キー -- [Providers](/ja-JP/providers) — プロバイダーごとのセットアップガイド +- [Providers](/ja-JP/providers) — プロバイダーごとの設定ガイド diff --git a/docs/ja-JP/concepts/qa-e2e-automation.md b/docs/ja-JP/concepts/qa-e2e-automation.md index 5ffc6f430..a2e770530 100644 --- a/docs/ja-JP/concepts/qa-e2e-automation.md +++ b/docs/ja-JP/concepts/qa-e2e-automation.md @@ -1,30 +1,30 @@ --- read_when: - qa-labまたはqa-channelの拡張 - - リポジトリに裏付けられたQAシナリオの追加 - - Gatewayダッシュボードを中心とした、より現実性の高いQA自動化の構築 + - リポジトリ連動のQAシナリオの追加 + - Gatewayダッシュボードを中心とした、より現実に近いQA自動化の構築 summary: qa-lab、qa-channel、シード済みシナリオ、プロトコルレポート向けの非公開QA自動化の構成 title: QA E2E自動化 x-i18n: - generated_at: "2026-04-10T04:43:39Z" + generated_at: "2026-04-11T02:44:18Z" model: gpt-5.4 provider: openai - source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de + source_hash: 5427b505e26bfd542e984e3920c3f7cb825473959195ba9737eff5da944c60d0 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # QA E2E自動化 -非公開QAスタックは、単一のユニットテストではできない、より現実的でチャネルに即した形でOpenClawを検証することを目的としています。 +非公開のQAスタックは、単一のユニットテストよりも現実のチャネルに近い形でOpenClawを検証することを目的としています。 現在の構成要素: - `extensions/qa-channel`: DM、チャネル、スレッド、リアクション、編集、削除の各サーフェスを備えた合成メッセージチャネル。 - `extensions/qa-lab`: トランスクリプトの観察、受信メッセージの注入、Markdownレポートのエクスポートを行うためのデバッガUIとQAバス。 -- `qa/`: キックオフタスクとベースラインQAシナリオ向けの、リポジトリに裏付けられたシードアセット。 +- `qa/`: キックオフタスクとベースラインQAシナリオ用の、リポジトリ連動のシード資産。 -現在のQAオペレーターフローは2ペインのQAサイトです: +現在のQAオペレーターのフローは、2ペインのQAサイトです: - 左: エージェントを表示するGatewayダッシュボード（Control UI）。 - 右: Slack風のトランスクリプトとシナリオ計画を表示するQA Lab。 @@ -35,9 +35,9 @@ x-i18n: pnpm qa:lab:up ``` -これによりQAサイトがビルドされ、Dockerベースのgatewayレーンが起動し、オペレーターまたは自動化ループがエージェントにQAミッションを与え、実際のチャネル動作を観察し、何が機能したか、何が失敗したか、何がブロックされたままだったかを記録できるQA Labページが公開されます。 +これによりQAサイトがビルドされ、DockerベースのGatewayレーンが起動し、オペレーターまたは自動化ループがエージェントにQAミッションを与え、実際のチャネルの挙動を観察し、何が機能し、何が失敗し、何がブロックされたままかを記録できるQA Labページが公開されます。 -Dockerイメージを毎回再ビルドせずにQA Lab UIをより高速に反復したい場合は、バインドマウントされたQA Labバンドルでスタックを起動します: +Dockerイメージを毎回再ビルドせずにQA Lab UIをより高速に反復したい場合は、QA Labバンドルをバインドマウントした状態でスタックを起動します: ```bash pnpm openclaw qa docker-build-image @@ -46,48 +46,76 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` は、事前ビルド済みイメージ上でDockerサービスを維持しつつ、`extensions/qa-lab/web/dist` を `qa-lab` コンテナにバインドマウントします。`qa:lab:watch` は変更時にそのバンドルを再ビルドし、QA Labのアセットハッシュが変わるとブラウザは自動リロードされます。 +`qa:lab:up:fast` は、Dockerサービスを事前ビルド済みイメージ上で維持しつつ、`extensions/qa-lab/web/dist` を `qa-lab` コンテナにバインドマウントします。`qa:lab:watch` は変更時にそのバンドルを再ビルドし、QA Labのアセットハッシュが変わるとブラウザが自動再読み込みされます。 -DockerをQAパスに持ち込まない使い捨てのLinux VMレーンでは、次を実行します: +実際のトランスポートを使うMatrixスモークレーンを実行するには、次を実行します: + +```bash +pnpm openclaw qa matrix +``` + +このレーンはDocker内に使い捨てのTuwunelホームサーバーをプロビジョニングし、一時的なドライバー、SUT、オブザーバーユーザーを登録し、1つのプライベートルームを作成したうえで、実際のMatrixプラグインをQA Gateway子プロセス内で実行します。ライブトランスポートレーンでは、子設定をテスト対象トランスポートに限定するため、Matrixは子設定内で `qa-channel` なしで実行されます。 + +実際のトランスポートを使うTelegramスモークレーンを実行するには、次を実行します: + +```bash +pnpm openclaw qa telegram +``` + +このレーンは使い捨てサーバーをプロビジョニングする代わりに、実在する1つのプライベートTelegramグループを対象にします。`OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要で、同じプライベートグループ内に2つの異なるボットが必要です。SUTボットにはTelegramユーザー名が必要で、ボット同士の観察は、両方のボットで `@BotFather` のBot-to-Bot Communication Modeが有効になっていると最もうまく機能します。 + +ライブトランスポートレーンは、それぞれが独自のシナリオリスト形状を考案する代わりに、より小さな1つの共通契約を共有するようになりました: + +`qa-channel` は引き続き広範な合成プロダクト挙動スイートであり、ライブトランスポートのカバレッジマトリクスには含まれません。 + +| レーン | Canary | メンションのゲーティング | 許可リストのブロック | トップレベル返信 | 再起動後の再開 | スレッドでのフォローアップ | スレッドの分離 | リアクションの観察 | ヘルプコマンド | +| ------- | ------ | ------------------------ | -------------------- | ---------------- | -------------- | -------------------------- | -------------- | ------------------ | -------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | + +これにより、`qa-channel` は広範なプロダクト挙動スイートとして維持されつつ、Matrix、Telegram、および今後のライブトランスポートが、明示的なトランスポート契約チェックリストを共有できます。 + +DockerをQAパスに持ち込まずに使い捨てのLinux VMレーンを実行するには、次を実行します: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -これにより新しいMultipassゲストが起動し、依存関係がインストールされ、ゲスト内でOpenClawがビルドされ、`qa suite` が実行された後、通常のQAレポートとサマリーがホスト上の `.artifacts/qa-e2e/...` にコピーされます。 -ホスト上の `qa suite` と同じシナリオ選択動作を再利用します。 -ライブ実行では、ゲストで実用的な対応済みQA認証入力、つまり環境変数ベースのプロバイダーキー、QAライブプロバイダー設定パス、存在する場合は `CODEX_HOME` が転送されます。ゲストがマウントされたワークスペース経由で書き戻せるように、`--output-dir` はリポジトリルート配下に保ってください。 +これにより新しいMultipassゲストが起動し、そのゲスト内で依存関係のインストールとOpenClawのビルドが行われ、`qa suite` が実行された後、通常のQAレポートとサマリーがホスト側の `.artifacts/qa-e2e/...` にコピーされます。 +シナリオ選択の挙動は、ホスト上の `qa suite` と同じものを再利用します。 +ホストとMultipassのスイート実行は、デフォルトで分離されたGatewayワーカーを使って複数の選択シナリオを並列実行し、最大64ワーカーまたは選択シナリオ数のいずれか小さい方まで利用します。ワーカー数を調整するには `--concurrency ` を使用し、直列実行には `--concurrency 1` を使用します。 +ライブ実行では、ゲストにとって実用的な対応QA認証入力が転送されます。具体的には、環境変数ベースのプロバイダーキー、QAライブプロバイダー設定パス、存在する場合の `CODEX_HOME` です。ゲストがマウントされたワークスペース経由で書き戻せるように、`--output-dir` はリポジトリルート配下に維持してください。 -## リポジトリに裏付けられたシード +## リポジトリ連動のシード -シードアセットは `qa/` にあります: +シード資産は `qa/` にあります: - `qa/scenarios/index.md` - `qa/scenarios/*.md` -これらは、QA計画が人間にもエージェントにも見えるよう、意図的にgitに含められています。ベースライン一覧は、次をカバーできる程度に十分広く保つべきです: +これらは、QA計画が人間とエージェントの両方から見えるように、意図的にgitに含められています。ベースライン一覧は、次をカバーできる程度に十分広く保つ必要があります: - DMとチャネルチャット - スレッド動作 - メッセージアクションのライフサイクル - cronコールバック -- メモリーの再想起 +- メモリー想起 - モデル切り替え - サブエージェントのハンドオフ - リポジトリ読み取りとドキュメント読み取り -- Lobster Invadersのような小さなビルドタスク1件 +- Lobster Invadersのような小さなビルドタスク1つ ## レポート -`qa-lab` は、観察されたバスタイムラインからMarkdownのプロトコルレポートをエクスポートします。 -レポートでは次に答える必要があります: +`qa-lab` は、観察されたバスタイムラインからMarkdown形式のプロトコルレポートをエクスポートします。 +レポートでは、次の点に答える必要があります: - 何が機能したか - 何が失敗したか - 何がブロックされたままだったか - どのフォローアップシナリオを追加する価値があるか -キャラクターとスタイルのチェックでは、同じシナリオを複数のライブモデル参照で実行し、評価済みのMarkdownレポートを書き出します: +キャラクターとスタイルのチェックを行うには、同じシナリオを複数のライブモデル参照で実行し、評価済みMarkdownレポートを書き出します: ```bash pnpm openclaw qa character-eval \ @@ -106,13 +134,13 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -このコマンドはDockerではなく、ローカルのQA gateway子プロセスを実行します。character evalシナリオでは、`SOUL.md` を通じてペルソナを設定し、その後にチャット、ワークスペース支援、小規模なファイルタスクなどの通常のユーザーターンを実行する必要があります。候補モデルには、それが評価されていることを知らせてはいけません。コマンドは各完全なトランスクリプトを保持し、基本的な実行統計を記録した後、自然さ、雰囲気、ユーモアに基づいて実行結果を順位付けするよう、高速モードで `xhigh` 推論を使ってjudgeモデルに依頼します。 -プロバイダーを比較する際は `--blind-judge-models` を使ってください。judgeプロンプトには依然としてすべてのトランスクリプトと実行ステータスが渡されますが、候補参照は `candidate-01` のような中立ラベルに置き換えられます。レポートは解析後に順位を実際の参照へ再マッピングします。 -候補実行のデフォルトは `high` thinking で、対応しているOpenAIモデルでは `xhigh` になります。特定の候補を上書きするには、`--model provider/model,thinking=` をインラインで指定します。`--thinking ` は引き続きグローバルなフォールバックを設定し、古い `--model-thinking ` 形式も互換性のため維持されています。 -OpenAI候補参照はデフォルトで高速モードになっており、プロバイダーが対応している場合は優先処理が使われます。単一の候補またはjudgeで上書きが必要な場合は、`,fast`、`,no-fast`、または `,fast=false` をインラインで追加してください。すべての候補モデルで高速モードを強制的に有効にしたい場合にのみ `--fast` を渡してください。候補とjudgeの所要時間はベンチマーク分析のためレポートに記録されますが、judgeプロンプトでは速度で順位付けしないよう明示されています。 -候補実行とjudgeモデル実行は、どちらもデフォルトで同時実行数16です。プロバイダー制限やローカルgateway負荷によって実行がノイジーになりすぎる場合は、`--concurrency` または `--judge-concurrency` を下げてください。 -候補 `--model` が渡されない場合、character evalのデフォルトは `openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、`moonshot/kimi-k2.5`、`google/gemini-3.1-pro-preview` です。 -`--judge-model` が渡されない場合、judgeのデフォルトは `openai/gpt-5.4,thinking=xhigh,fast` と `anthropic/claude-opus-4-6,thinking=high` です。 +このコマンドはDockerではなく、ローカルのQA Gateway子プロセスを実行します。キャラクター評価シナリオでは、`SOUL.md` を通じてペルソナを設定し、その後、チャット、ワークスペースヘルプ、小さなファイルタスクのような通常のユーザーターンを実行する必要があります。候補モデルには、評価されていることを伝えないでください。このコマンドは各完全トランスクリプトを保持し、基本的な実行統計を記録したうえで、ジャッジモデルに高速モードかつ `xhigh` 推論で、自然さ、雰囲気、ユーモアに基づいて各実行を順位付けするよう求めます。 +プロバイダー比較時には `--blind-judge-models` を使用してください。ジャッジプロンプトには引き続きすべてのトランスクリプトと実行ステータスが渡されますが、候補参照は `candidate-01` のような中立ラベルに置き換えられ、レポートは解析後に順位を実際の参照へ対応付け直します。 +候補実行の思考レベルはデフォルトで `high` であり、それをサポートするOpenAIモデルでは `xhigh` が使われます。特定の候補を個別に上書きするには、`--model provider/model,thinking=` をインラインで指定します。`--thinking ` は引き続きグローバルなフォールバックを設定し、旧形式の `--model-thinking ` も互換性のために維持されています。 +OpenAI候補参照は、プロバイダーが対応している場合に優先処理が使われるよう、デフォルトで高速モードになります。個別の候補またはジャッジで上書きしたい場合は、`,fast`、`,no-fast`、または `,fast=false` をインラインで追加してください。すべての候補モデルで高速モードを強制的に有効にしたい場合にのみ `--fast` を渡してください。候補とジャッジの所要時間はベンチマーク分析のためにレポートへ記録されますが、ジャッジプロンプトでは速度で順位付けしないよう明示的に指示されています。 +候補モデル実行とジャッジモデル実行はいずれも、デフォルトで並列数16です。プロバイダー制限やローカルGateway負荷によって実行がうるさくなりすぎる場合は、`--concurrency` または `--judge-concurrency` を下げてください。 +候補の `--model` が渡されない場合、キャラクター評価ではデフォルトで `openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、`moonshot/kimi-k2.5`、`google/gemini-3.1-pro-preview` が使用されます。 +`--judge-model` が渡されない場合、ジャッジはデフォルトで `openai/gpt-5.4,thinking=xhigh,fast` と `anthropic/claude-opus-4-6,thinking=high` になります。 ## 関連ドキュメント diff --git a/docs/ja-JP/gateway/cli-backends.md b/docs/ja-JP/gateway/cli-backends.md index 19eb42048..b6045aee2 100644 --- a/docs/ja-JP/gateway/cli-backends.md +++ b/docs/ja-JP/gateway/cli-backends.md @@ -1,41 +1,41 @@ --- read_when: - - APIプロバイダーが失敗したときに信頼できるフォールバックが必要 - - Codex CLIや他のローカルAI CLIを実行していて、それらを再利用したい - - CLIバックエンドのツールアクセス向けMCP loopback bridgeを理解したい + - APIプロバイダーが失敗したときに、信頼できるフォールバックが必要です + - Codex CLIやその他のローカルAI CLIを実行していて、それらを再利用したいと考えています + - CLIバックエンドのツールアクセスのためのMCP loopbackブリッジを理解したいと考えています summary: 'CLIバックエンド: オプションのMCPツールブリッジを備えたローカルAI CLIフォールバック' title: CLIバックエンド x-i18n: - generated_at: "2026-04-09T01:28:08Z" + generated_at: "2026-04-11T02:44:18Z" model: gpt-5.4 provider: openai - source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20 + source_hash: d108dbea043c260a80d15497639298f71a6b4d800f68d7b39bc129f7667ca608 source_path: gateway/cli-backends.md workflow: 15 --- # CLIバックエンド（フォールバックランタイム） -OpenClawは、APIプロバイダーが停止している、レート制限されている、または一時的に不安定な場合に、**テキスト専用のフォールバック**として**ローカルAI CLI**を実行できます。これは意図的に保守的な設計です。 +OpenClawは、APIプロバイダーが停止している、レート制限されている、または一時的に不安定なときに、**テキスト専用のフォールバック**として**ローカルAI CLI**を実行できます。これは意図的に保守的な設計です。 -- `bundleMcp: true` を持つバックエンドはloopback MCP bridge経由でGatewayツールを受け取れますが、**OpenClawのツールは直接注入されません**。 -- 対応するCLIでは**JSONLストリーミング**を利用できます。 -- **セッションをサポート**しています（そのため後続のターンでも一貫性が保たれます）。 -- CLIが画像パスを受け付ける場合、**画像をそのまま渡せます**。 +- **OpenClawツールは直接注入されません**が、`bundleMcp: true` を持つバックエンドは、loopback MCPブリッジ経由でGatewayツールを受け取れます。 +- それをサポートするCLI向けの**JSONLストリーミング**。 +- **セッションをサポート**しているため、後続のターンでも一貫性が保たれます。 +- CLIが画像パスを受け付ける場合は、**画像をそのまま渡す**ことができます。 -これは主要経路ではなく、**セーフティネット**として設計されています。外部APIに依存せず、「常に動作する」テキスト応答がほしい場合に使ってください。 +これは主要な経路というより、**セーフティネット**として設計されています。外部APIに依存せず、「常に動作する」テキスト応答が必要な場合に使用してください。 -ACPセッション制御、バックグラウンドタスク、スレッド/会話バインディング、永続的な外部コーディングセッションを備えた完全なハーネスランタイムが必要な場合は、代わりに[ACP Agents](/ja-JP/tools/acp-agents)を使ってください。CLIバックエンドはACPではありません。 +ACPセッション制御、バックグラウンドタスク、スレッド/会話のバインディング、永続的な外部コーディングセッションを備えた完全なハーネスランタイムが必要な場合は、代わりに[ACP Agents](/ja-JP/tools/acp-agents)を使用してください。CLIバックエンドはACPではありません。 ## 初心者向けクイックスタート -Codex CLIは**設定なし**で使えます（同梱のOpenAIプラグインがデフォルトのバックエンドを登録します）。 +設定なしでもCodex CLIを使用できます（バンドルされたOpenAIプラグインがデフォルトのバックエンドを登録します）。 ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Gatewayがlaunchd/systemd配下で動作していてPATHが最小限の場合は、コマンドパスだけを追加してください。 +Gatewayがlaunchd/systemd配下で実行され、PATHが最小限の場合は、コマンドパスだけを追加してください。 ```json5 { @@ -51,13 +51,13 @@ Gatewayがlaunchd/systemd配下で動作していてPATHが最小限の場合は } ``` -これで完了です。CLI自体に必要なものを除き、キーや追加の認証設定は不要です。 +これで完了です。CLI自体に必要なもの以外、キーも追加の認証設定も不要です。 -同梱CLIバックエンドをGatewayホスト上の**主要メッセージプロバイダー**として使う場合、設定でモデル参照または`agents.defaults.cliBackends`の下にそのバックエンドを明示的に参照していれば、OpenClawはその所有元である同梱プラグインを自動で読み込むようになりました。 +バンドルされたCLIバックエンドをGatewayホスト上の**主要メッセージプロバイダー**として使用する場合、設定でモデル参照または`agents.defaults.cliBackends`の下にそのバックエンドを明示的に参照すると、OpenClawはそのバックエンドを所有するバンドルプラグインを自動で読み込みます。 ## フォールバックとして使う -CLIバックエンドをフォールバック一覧に追加すると、主要モデルが失敗したときだけ実行されます。 +CLIバックエンドをフォールバックリストに追加すると、主要モデルが失敗したときだけ実行されます。 ```json5 { @@ -76,20 +76,20 @@ CLIバックエンドをフォールバック一覧に追加すると、主要 } ``` -注意: +注意点: -- `agents.defaults.models`（許可リスト）を使う場合は、そこにCLIバックエンドのモデルも含める必要があります。 +- `agents.defaults.models`（許可リスト）を使う場合は、CLIバックエンドのモデルもそこに含める必要があります。 - 主要プロバイダーが失敗した場合（認証、レート制限、タイムアウト）、OpenClawは次にCLIバックエンドを試します。 ## 設定の概要 -すべてのCLIバックエンドは次の配下にあります。 +すべてのCLIバックエンドは次の場所にあります。 ``` agents.defaults.cliBackends ``` -各エントリーは**provider id**（例: `codex-cli`, `my-cli`）をキーにします。 +各エントリーは**provider id**（例: `codex-cli`、`my-cli`）をキーとして持ちます。 provider idはモデル参照の左側になります。 ``` @@ -120,7 +120,7 @@ provider idはモデル参照の左側になります。 sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // CodexスタイルのCLIでは、代わりにプロンプトファイルを指定できます: + // CodexスタイルのCLIは代わりにプロンプトファイルを指定できます: // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -138,58 +138,60 @@ provider idはモデル参照の左側になります。 1. providerプレフィックス（`codex-cli/...`）に基づいて**バックエンドを選択**します。 2. 同じOpenClawプロンプトとワークスペースコンテキストを使って**システムプロンプトを構築**します。 -3. 履歴の整合性が保たれるよう、（対応していれば）セッションid付きで**CLIを実行**します。 -4. **出力を解析**し（JSONまたはプレーンテキスト）、最終テキストを返します。 -5. バックエンドごとに**セッションidを永続化**するので、後続のやり取りでも同じCLIセッションを再利用します。 +3. 履歴の一貫性を保つため、対応している場合はセッションID付きで**CLIを実行**します。 +4. **出力を解析**し（JSONまたはプレーンテキスト）、最終的なテキストを返します。 +5. バックエンドごとに**セッションIDを永続化**し、後続のやり取りで同じCLIセッションを再利用します。 -同梱のAnthropic `claude-cli`バックエンドが再びサポートされました。Anthropicのスタッフから、OpenClawスタイルのClaude CLI利用は再び許可されると案内があったため、Anthropicが新しいポリシーを公開しない限り、OpenClawはこの連携における`claude -p`の利用を公認済みとして扱います。 +バンドルされたAnthropicの`claude-cli`バックエンドが再びサポートされました。Anthropicのスタッフから、OpenClawスタイルのClaude CLI使用は再び許可されていると案内されたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはこの統合における`claude -p`の使用を認可済みとして扱います。 -同梱のOpenAI `codex-cli`バックエンドは、OpenClawのシステムプロンプトをCodexの`model_instructions_file`設定オーバーライド（`-c model_instructions_file="..."`）経由で渡します。CodexにはClaudeスタイルの`--append-system-prompt`フラグがないため、OpenClawは新しいCodex CLIセッションごとに組み立て済みプロンプトを一時ファイルに書き込みます。 +バンドルされたOpenAIの`codex-cli`バックエンドは、Codexの`model_instructions_file`設定オーバーライド（`-c model_instructions_file="..."`）を通じてOpenClawのシステムプロンプトを渡します。CodexはClaudeスタイルの`--append-system-prompt`フラグを公開していないため、OpenClawは新しいCodex CLIセッションごとに組み立てたプロンプトを一時ファイルに書き込みます。 + +バンドルされたAnthropicの`claude-cli`バックエンドは、OpenClawのSkillsスナップショットを2つの方法で受け取ります。1つは追加されたシステムプロンプト内のコンパクトなOpenClaw Skillsカタログ、もう1つは`--plugin-dir`で渡される一時的なClaude Codeプラグインです。このプラグインには、そのエージェント/セッションに対して適格なSkillsのみが含まれるため、Claude Codeネイティブのスキルリゾルバーは、OpenClawが通常プロンプトで提示するのと同じフィルタ済みセットを見ることになります。Skillのenv/APIキー上書きは、実行時に子プロセス環境へOpenClawから引き続き適用されます。 ## セッション -- CLIがセッションをサポートしている場合は、`sessionArg`（例: `--session-id`）または`sessionArgs`（プレースホルダー`{sessionId}`）を設定してください。後者はIDを複数のフラグに挿入する必要がある場合に使います。 -- CLIが異なるフラグを持つ**resumeサブコマンド**を使う場合は、`resumeArgs`（再開時に`args`を置き換えます）を設定し、必要に応じて`resumeOutput`（JSON以外の再開用）も設定してください。 +- CLIがセッションをサポートしている場合は、`sessionArg`（例: `--session-id`）または、IDを複数のフラグに挿入する必要があるときは`sessionArgs`（プレースホルダー`{sessionId}`）を設定してください。 +- CLIが異なるフラグを使う**resumeサブコマンド**を使用する場合は、`resumeArgs`（再開時に`args`を置き換える）と、必要に応じて`resumeOutput`（JSON以外の再開向け）を設定してください。 - `sessionMode`: - - `always`: 常にセッションidを送信します（保存済みがなければ新しいUUID）。 - - `existing`: 以前に保存されたセッションidがある場合のみ送信します。 - - `none`: セッションidを送信しません。 + - `always`: 常にセッションIDを送信します（保存済みがなければ新しいUUID）。 + - `existing`: 以前に保存されていた場合のみセッションIDを送信します。 + - `none`: セッションIDを送信しません。 シリアライズに関する注意: -- `serialize: true` は同一レーンでの実行順を保ちます。 -- 多くのCLIは1つのproviderレーン上で直列化されます。 -- OpenClawは、再ログイン、トークンローテーション、認証プロファイル資格情報の変更を含め、バックエンドの認証状態が変わると、保存済みCLIセッションの再利用を破棄します。 +- `serialize: true` は同じレーンの実行順を維持します。 +- ほとんどのCLIは1つのproviderレーン上でシリアライズされます。 +- OpenClawは、再ログイン、トークンローテーション、または認証プロファイル資格情報の変更を含め、バックエンドの認証状態が変わると、保存済みCLIセッションの再利用を破棄します。 ## 画像（パススルー） -CLIが画像パスを受け付ける場合は、`imageArg`を設定してください。 +CLIが画像パスを受け付ける場合は、`imageArg`を設定します。 ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClawはbase64画像を一時ファイルに書き込みます。`imageArg`が設定されていれば、それらのパスはCLI引数として渡されます。`imageArg`がない場合、OpenClawはファイルパスをプロンプトに追記します（パス注入）。これは、プレーンなパスからローカルファイルを自動読み込みするCLIでは十分です。 +OpenClawはbase64画像を一時ファイルに書き込みます。`imageArg`が設定されている場合、それらのパスはCLI引数として渡されます。`imageArg`がない場合、OpenClawはファイルパスをプロンプトに追記します（パス注入）。これは、プレーンなパスからローカルファイルを自動読み込みするCLIには十分です。 ## 入力 / 出力 -- `output: "json"`（デフォルト）はJSONを解析し、テキストとセッションidの抽出を試みます。 -- Gemini CLIのJSON出力では、`usage`がないか空の場合、OpenClawは応答テキストを`response`から、使用量を`stats`から読み取ります。 -- `output: "jsonl"` はJSONLストリーム（例: Codex CLI `--json`）を解析し、最終エージェントメッセージと存在する場合はセッション識別子を抽出します。 +- `output: "json"`（デフォルト）はJSONを解析し、テキストとセッションIDの抽出を試みます。 +- Gemini CLIのJSON出力では、`usage`がない、または空の場合、OpenClawは`response`から返信テキストを、`stats`から使用量を読み取ります。 +- `output: "jsonl"` はJSONLストリーム（例: Codex CLI `--json`）を解析し、存在する場合は最終的なエージェントメッセージとセッション識別子を抽出します。 - `output: "text"` はstdoutを最終応答として扱います。 入力モード: -- `input: "arg"`（デフォルト）はプロンプトを最後のCLI引数として渡します。 -- `input: "stdin"` はstdin経由でプロンプトを送信します。 -- プロンプトが非常に長く、`maxPromptArgChars`が設定されている場合はstdinが使われます。 +- `input: "arg"`（デフォルト）は、プロンプトを最後のCLI引数として渡します。 +- `input: "stdin"` は、プロンプトをstdin経由で送信します。 +- プロンプトが非常に長く、`maxPromptArgChars`が設定されている場合は、stdinが使用されます。 ## デフォルト（プラグイン所有） -同梱のOpenAIプラグインは`codex-cli`のデフォルトも登録します。 +バンドルされたOpenAIプラグインは、`codex-cli`用のデフォルトも登録します。 - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -200,7 +202,7 @@ OpenClawはbase64画像を一時ファイルに書き込みます。`imageArg` - `imageArg: "--image"` - `sessionMode: "existing"` -同梱のGoogleプラグインは`google-gemini-cli`のデフォルトも登録します。 +バンドルされたGoogleプラグインも、`google-gemini-cli`用のデフォルトを登録します。 - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -211,57 +213,78 @@ OpenClawはbase64画像を一時ファイルに書き込みます。`imageArg` - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -前提条件: ローカルのGemini CLIがインストールされ、`PATH`上で`gemini`として利用可能である必要があります（`brew install gemini-cli` または `npm install -g @google/gemini-cli`）。 +前提条件: ローカルのGemini CLIがインストールされており、`PATH`上で`gemini`として利用できる必要があります（`brew install gemini-cli` または `npm install -g @google/gemini-cli`）。 Gemini CLI JSONに関する注意: -- 応答テキストはJSONの`response`フィールドから読み取られます。 -- 使用量は`usage`が存在しないか空の場合に`stats`へフォールバックします。 -- `stats.cached`はOpenClawの`cacheRead`に正規化されます。 -- `stats.input`がない場合、OpenClawは`stats.input_tokens - stats.cached`から入力トークン数を導出します。 +- 返信テキストはJSONの`response`フィールドから読み取られます。 +- `usage`が存在しない、または空の場合、使用量は`stats`にフォールバックします。 +- `stats.cached`はOpenClawの`cacheRead`へ正規化されます。 +- `stats.input`がない場合、OpenClawは`stats.input_tokens - stats.cached`から入力トークンを導出します。 -必要な場合にのみ上書きしてください（一般的なのは絶対`command`パスです）。 +必要な場合のみ上書きしてください（一般的なのは絶対`command`パスです）。 ## プラグイン所有のデフォルト -CLIバックエンドのデフォルトは現在、プラグインサーフェスの一部です。 +CLIバックエンドのデフォルトは、現在ではプラグインサーフェスの一部です。 - プラグインは`api.registerCliBackend(...)`でそれらを登録します。 -- バックエンドの`id`がモデル参照におけるproviderプレフィックスになります。 +- バックエンドの`id`は、モデル参照内のproviderプレフィックスになります。 - `agents.defaults.cliBackends.`内のユーザー設定は、引き続きプラグインのデフォルトを上書きします。 - バックエンド固有の設定クリーンアップは、オプションの`normalizeConfig`フックを通じて引き続きプラグイン所有です。 -## Bundle MCPオーバーレイ +小さなプロンプト/メッセージ互換シムが必要なプラグインは、プロバイダーやCLIバックエンドを置き換えずに、双方向のテキスト変換を宣言できます。 -CLIバックエンドは**OpenClawのツール呼び出しを直接受け取りません**が、バックエンドは`bundleMcp: true`で生成されたMCP設定オーバーレイにオプトインできます。 +```typescript +api.registerTextTransforms({ + input: [ + { from: /red basket/g, to: "blue basket" }, + { from: /paper ticket/g, to: "digital ticket" }, + { from: /left shelf/g, to: "right shelf" }, + ], + output: [ + { from: /blue basket/g, to: "red basket" }, + { from: /digital ticket/g, to: "paper ticket" }, + { from: /right shelf/g, to: "left shelf" }, + ], +}); +``` -現在の同梱動作: +`input`は、CLIに渡されるシステムプロンプトとユーザープロンプトを書き換えます。`output`は、ストリーミングされたassistantデルタと、解析済みの最終テキストを、OpenClaw自身のコントロールマーカー処理とチャネル配信の前に書き換えます。 + +Claude Codeのstream-json互換JSONLを出力するCLIでは、そのバックエンドの設定に`jsonlDialect: "claude-stream-json"`を設定してください。 + +## bundle MCPオーバーレイ + +CLIバックエンドは**OpenClawツール呼び出しを直接受け取りません**が、バックエンドは`bundleMcp: true`で生成されたMCP設定オーバーレイにオプトインできます。 + +現在のバンドル動作: - `claude-cli`: 生成されたstrict MCP設定ファイル -- `codex-cli`: `mcp_servers`向けのインライン設定オーバーライド -- `google-gemini-cli`: 生成されたGemini system settingsファイル +- `codex-cli`: `mcp_servers`用のインライン設定オーバーライド +- `google-gemini-cli`: 生成されたGeminiシステム設定ファイル bundle MCPが有効な場合、OpenClawは次を行います。 - GatewayツールをCLIプロセスに公開するloopback HTTP MCPサーバーを起動する - セッションごとのトークン（`OPENCLAW_MCP_TOKEN`）でブリッジを認証する -- ツールアクセスを現在のセッション、アカウント、チャンネルコンテキストに限定する +- ツールアクセスを現在のセッション、アカウント、チャネルコンテキストにスコープする - 現在のワークスペースで有効なbundle-MCPサーバーを読み込む - それらを既存のバックエンドMCP設定/設定形状とマージする -- 所有元拡張機能のバックエンド所有integration modeを使って起動設定を書き換える +- 起動設定を、所有拡張のバックエンド所有統合モードを使って書き換える -MCPサーバーが1つも有効でない場合でも、バックエンドがbundle MCPにオプトインしていれば、バックグラウンド実行を分離した状態に保つためにOpenClawはstrict設定を注入します。 +MCPサーバーが1つも有効でない場合でも、バックエンドがbundle MCPにオプトインしていれば、バックグラウンド実行を分離したままにするため、OpenClawはstrict設定を引き続き注入します。 ## 制限事項 -- **OpenClawのツール呼び出しを直接行えません。** OpenClawはCLIバックエンドプロトコルにツール呼び出しを注入しません。バックエンドが`bundleMcp: true`にオプトインした場合にのみ、Gatewayツールを利用できます。 -- **ストリーミングはバックエンド依存です。** JSONLをストリームするバックエンドもあれば、終了までバッファするものもあります。 +- **直接のOpenClawツール呼び出しはありません。** OpenClawはCLIバックエンドプロトコルにツール呼び出しを注入しません。バックエンドが`bundleMcp: true`にオプトインした場合のみ、Gatewayツールを見ることができます。 +- **ストリーミングはバックエンド依存です。** JSONLをストリーミングするバックエンドもあれば、終了までバッファするバックエンドもあります。 - **構造化出力**はCLIのJSON形式に依存します。 -- **Codex CLIセッション**はテキスト出力で再開されます（JSONLではありません）。そのため、最初の`--json`実行より構造化が弱くなります。それでもOpenClawセッション自体は通常どおり動作します。 +- **Codex CLIセッション**はテキスト出力経由で再開されます（JSONLではありません）。そのため、初回の`--json`実行より構造化が弱くなります。OpenClawセッション自体は通常どおり機能します。 ## トラブルシューティング -- **CLIが見つからない**: `command`に完全パスを設定してください。 -- **モデル名が間違っている**: `modelAliases`を使って`provider/model` → CLIモデルをマッピングしてください。 -- **セッションの継続性がない**: `sessionArg`が設定され、`sessionMode`が`none`でないことを確認してください（Codex CLIは現在、JSON出力で再開できません）。 -- **画像が無視される**: `imageArg`を設定し（あわせてCLIがファイルパスをサポートしていることも確認してください）。 +- **CLIが見つからない**: `command`をフルパスに設定してください。 +- **モデル名が間違っている**: `modelAliases`を使って`provider/model` → CLIモデルにマッピングしてください。 +- **セッションの継続性がない**: `sessionArg`が設定され、`sessionMode`が`none`でないことを確認してください（Codex CLIは現在JSON出力で再開できません）。 +- **画像が無視される**: `imageArg`を設定し（CLIがファイルパスをサポートしていることも確認してください）。 diff --git a/docs/ja-JP/gateway/configuration-reference.md b/docs/ja-JP/gateway/configuration-reference.md index 5b63ef262..142fb44d7 100644 --- a/docs/ja-JP/gateway/configuration-reference.md +++ b/docs/ja-JP/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - - 正確なフィールド単位の設定セマンティクスやデフォルト値が必要なとき - - channel、model、gateway、またはtoolの設定ブロックを検証しているとき -summary: コアとなるOpenClawキー、デフォルト値、専用サブシステム参照へのリンクを含むGateway設定リファレンス + - 正確なフィールドレベルの設定の意味またはデフォルト値が必要な場合 + - channel、model、gateway、またはtoolの設定ブロックを検証している場合 +summary: Gateway設定リファレンス。OpenClawコアのキー、デフォルト値、および専用のサブシステムリファレンスへのリンクを含みます。 title: 設定リファレンス x-i18n: - generated_at: "2026-04-09T01:33:43Z" + generated_at: "2026-04-11T02:44:17Z" model: gpt-5.4 provider: openai - source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c + source_hash: 32acb82e756e4740d13ef12277842081f4c90df7b67850c34f8a76701fcd37d0 source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,54 +17,54 @@ x-i18n: `~/.openclaw/openclaw.json` のコア設定リファレンスです。タスク指向の概要については、[Configuration](/ja-JP/gateway/configuration) を参照してください。 -このページでは、主要なOpenClawの設定面を扱い、サブシステムに独自のより詳細なリファレンスがある場合はリンクを示します。このページでは、すべてのchannel/plugin所有のコマンドカタログや、すべての詳細なmemory/QMDノブを1ページにインライン展開しようとはしていません。 +このページでは、主要なOpenClaw設定サーフェスを扱い、サブシステムごとにより詳細な専用リファレンスがある場合はそこへリンクします。このページでは、すべてのchannel/plugin所有のコマンドカタログや、詳細なmemory/QMDノブを1ページにすべてインライン展開することは**しません**。 コード上の真実: -- `openclaw config schema` は、検証およびControl UIで使用されるライブJSON Schemaを出力し、利用可能な場合はbundled/plugin/channelメタデータがマージされます -- `config.schema.lookup` は、詳細確認用ツール向けに1つのパススコープschemaノードを返します -- `pnpm config:docs:check` / `pnpm config:docs:gen` は、config-docベースラインハッシュを現在のschema面に対して検証します +- `openclaw config schema` は、検証とControl UIで使用されるライブJSON Schemaを出力します。利用可能な場合は、bundled/plugin/channelメタデータがマージされます +- `config.schema.lookup` は、ドリルダウン用ツール向けに、パススコープされた単一のschemaノードを返します +- `pnpm config:docs:check` / `pnpm config:docs:gen` は、config-docベースラインハッシュを現在のschemaサーフェスに対して検証します 専用の詳細リファレンス: - `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`、および `plugins.entries.memory-core.config.dreaming` 配下のdreaming設定については [Memory configuration reference](/ja-JP/reference/memory-config) - 現在の組み込み + bundledコマンドカタログについては [Slash Commands](/ja-JP/tools/slash-commands) -- channel固有のコマンド面については各所有channel/pluginページ +- channel固有のコマンドサーフェスについては各channel/pluginページ -設定形式は **JSON5** です（コメントと末尾カンマを許可）。すべてのフィールドは任意です — OpenClawは省略時に安全なデフォルト値を使います。 +設定形式は **JSON5** です（コメント + 末尾カンマ可）。すべてのフィールドは任意です。省略された場合、OpenClawは安全なデフォルト値を使用します。 --- ## Channels -各channelは、その設定セクションが存在すれば自動的に開始されます（`enabled: false` の場合を除く）。 +各channelは、その設定セクションが存在すると自動的に起動します（`enabled: false` の場合を除く）。 -### DMとグループアクセス +### DMとグループのアクセス すべてのchannelはDMポリシーとグループポリシーをサポートします: | DM policy | 動作 | | ------------------- | -------------------------------------------------------------- | -| `pairing` (default) | 未知の送信者には1回限りのペアリングコードが送られ、所有者が承認する必要があります | -| `allowlist` | `allowFrom`（またはペア済みallowストア）内の送信者のみ | -| `open` | すべての受信DMを許可（`allowFrom: ["*"]` が必要） | +| `pairing` (default) | 未知の送信者には一度限りのペアリングコードが送られ、所有者の承認が必要 | +| `allowlist` | `allowFrom` 内の送信者のみ（またはペア済み許可ストア） | +| `open` | すべての受信DMを許可（`allowFrom: ["*"]` が必要） | | `disabled` | すべての受信DMを無視 | -| Group policy | 動作 | -| --------------------- | -------------------------------------------------------- | -| `allowlist` (default) | 設定されたallowlistに一致するグループのみ | -| `open` | グループallowlistをバイパス（mention-gatingは引き続き適用） | -| `disabled` | すべてのgroup/roomメッセージをブロック | +| Group policy | 動作 | +| --------------------- | ------------------------------------------------------ | +| `allowlist` (default) | 設定された許可リストに一致するグループのみ | +| `open` | グループ許可リストをバイパス（メンションゲートは引き続き適用） | +| `disabled` | すべてのグループ/ルームメッセージをブロック | `channels.defaults.groupPolicy` は、providerの `groupPolicy` が未設定のときのデフォルトを設定します。 -ペアリングコードは1時間後に期限切れになります。保留中のDMペアリング要求は **channelごとに3件** に制限されます。 -providerブロック自体が完全に欠けている場合（`channels.` が存在しない場合）、実行時のgroup policyは `allowlist`（fail-closed）にフォールバックし、起動時に警告が出ます。 +ペアリングコードの有効期限は1時間です。保留中のDMペアリングリクエストは **channelごとに3件** までに制限されます。 +providerブロック全体が存在しない場合（`channels.` がない場合）、実行時のグループポリシーは起動時警告付きで `allowlist`（fail-closed）にフォールバックします。 -### Channel modelオーバーライド +### Channelのモデル上書き -特定のchannel IDをmodelに固定するには `channels.modelByChannel` を使います。値には `provider/model` または設定済みmodel alias を指定できます。このchannelマッピングは、sessionにすでにmodelオーバーライド（たとえば `/model` で設定）がない場合に適用されます。 +特定のchannel IDをモデルに固定するには `channels.modelByChannel` を使用します。値には `provider/model` または設定済みのモデルエイリアスを指定できます。このchannelマッピングは、セッションにすでにモデル上書きがない場合（たとえば `/model` で設定された場合）に適用されます。 ```json5 { @@ -85,9 +85,9 @@ providerブロック自体が完全に欠けている場合（`channels..contextVisibility`。 -- `channels.defaults.heartbeat.showOk`: 正常なchannelステータスをheartbeat出力に含めます。 -- `channels.defaults.heartbeat.showAlerts`: 劣化/エラーステータスをheartbeat出力に含めます。 -- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケーター形式のheartbeat出力を描画します。 +- `channels.defaults.groupPolicy`: providerレベルの `groupPolicy` が未設定のときのフォールバック用グループポリシー。 +- `channels.defaults.contextVisibility`: すべてのchannelに対する補足コンテキスト可視性モードのデフォルト。値: `all`（デフォルト。引用/スレッド/履歴コンテキストをすべて含む）、`allowlist`（許可リストに含まれる送信者のコンテキストのみ含む）、`allowlist_quote`（allowlistと同じだが、明示的な引用/返信コンテキストは保持）。channelごとの上書き: `channels..contextVisibility`。 +- `channels.defaults.heartbeat.showOk`: heartbeat出力に正常なchannelステータスを含めます。 +- `channels.defaults.heartbeat.showAlerts`: heartbeat出力に劣化/エラーステータスを含めます。 +- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケーター形式のheartbeat出力を表示します。 ### WhatsApp -WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リンク済みsessionが存在すると自動で開始されます。 +WhatsAppはGatewayのweb channel（Baileys Web）経由で実行されます。リンク済みセッションが存在すると自動的に起動します。 ```json5 { @@ -124,7 +124,7 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (self-chat modeではfalse) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -146,7 +146,7 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ } ``` - + ```json5 { @@ -164,10 +164,10 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ } ``` -- 送信コマンドは、`default` アカウントが存在する場合はそれを、そうでない場合は最初に設定されたアカウントid（ソート順）をデフォルトで使用します。 -- 任意の `channels.whatsapp.defaultAccount` は、設定済みアカウントidと一致する場合、このフォールバックのデフォルトアカウント選択を上書きします。 -- レガシーな単一アカウントBaileys認証ディレクトリは、`openclaw doctor` によって `whatsapp/default` へ移行されます。 -- アカウントごとのオーバーライド: `channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 送信コマンドは、`default` アカウントが存在する場合はそれを、存在しない場合は最初に設定されたアカウントID（ソート順）をデフォルトに使用します。 +- 任意の `channels.whatsapp.defaultAccount` は、設定済みアカウントIDに一致する場合、このフォールバックのデフォルトアカウント選択を上書きします。 +- レガシーな単一アカウントBaileys auth dirは、`openclaw doctor` によって `whatsapp/default` へ移行されます。 +- アカウントごとの上書き: `channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -202,7 +202,7 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; preview-edit rate limitを避けるため明示的にopt in) + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,13 +225,13 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ } ``` -- Bot token: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。symlinkは拒否）、デフォルトアカウントのフォールバックとして `TELEGRAM_BOT_TOKEN` も使用可能です。 -- 任意の `channels.telegram.defaultAccount` は、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 -- マルチアカウント構成（2つ以上のアカウントid）では、フォールバックルーティングを避けるため明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定してください。これが欠けているか無効な場合、`openclaw doctor` が警告します。 -- `configWrites: false` は、Telegram起点のconfig書き込み（supergroup ID移行、`/config set|unset`）をブロックします。 -- 最上位の `bindings[]` エントリーで `type: "acp"` を持つものは、forum topic向けの永続ACPバインディングを設定します（`match.peer.id` には正規の `chatId:topic:topicId` を使用）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 -- Telegramのstream previewは `sendMessage` + `editMessageText` を使用します（direct chatとgroup chatの両方で機能します）。 -- Retryポリシー: [Retry policy](/ja-JP/concepts/retry) を参照してください。 +- Botトークン: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。symlinkは拒否されます）。デフォルトアカウントのフォールバックとして `TELEGRAM_BOT_TOKEN` も利用できます。 +- 任意の `channels.telegram.defaultAccount` は、設定済みアカウントIDに一致する場合、デフォルトアカウント選択を上書きします。 +- 複数アカウント構成（2つ以上のアカウントID）では、フォールバックルーティングを避けるため、明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定してください。これがない、または無効な場合、`openclaw doctor` が警告します。 +- `configWrites: false` は、Telegram起点の設定書き込み（supergroup ID移行、`/config set|unset`）をブロックします。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、フォーラムトピック向けの永続ACPバインディングを設定します（`match.peer.id` には正規形の `chatId:topic:topicId` を使用）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) で共通に定義されています。 +- Telegramのストリームプレビューは `sendMessage` + `editMessageText` を使用します（ダイレクトチャットとグループチャットの両方で動作）。 +- リトライポリシー: [Retry policy](/ja-JP/concepts/retry) を参照してください。 ### Discord @@ -286,7 +286,7 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progressはDiscordではpartialに対応) + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // sessions_spawn({ thread: true }) のopt-in + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,35 +334,35 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ ``` - Token: `channels.discord.token`。デフォルトアカウントのフォールバックとして `DISCORD_BOT_TOKEN` を使用します。 -- 明示的なDiscord `token` を指定する直接送信呼び出しでは、その呼び出しにそのtokenを使用します。アカウントのretry/policy設定は、アクティブなruntime snapshotで選択されたアカウントから引き続き取得されます。 -- 任意の `channels.discord.defaultAccount` は、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 -- 配信先ターゲットには `user:`（DM）または `channel:`（guild channel）を使用します。数字のみのIDは拒否されます。 -- Guild slugは小文字で、空白は `-` に置き換えられます。channelキーにはslug化された名前（`#` なし）を使用します。guild IDを優先してください。 -- Bot自身が投稿したメッセージはデフォルトで無視されます。`allowBots: true` で有効化できます。botにmentionしたbotメッセージのみ受け入れるには `allowBots: "mentions"` を使用します（自分自身のメッセージは引き続き除外されます）。 -- `channels.discord.guilds..ignoreOtherMentions`（およびchannelオーバーライド）は、別のユーザーまたはroleにmentionしているがbotにはmentionしていないメッセージを破棄します（@everyone/@hereは除く）。 -- `maxLinesPerMessage`（デフォルト17）は、2000文字未満でも行数の多いメッセージを分割します。 -- `channels.discord.threadBindings` はDiscordのthread-bound routingを制御します: - - `enabled`: thread-bound session機能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびbound delivery/routing）のDiscordオーバーライド - - `idleHours`: 非アクティブ時の自動unfocusのDiscordオーバーライド（時間単位、`0` で無効） - - `maxAgeHours`: ハード最大期間のDiscordオーバーライド（時間単位、`0` で無効） - - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` に対する自動thread作成/バインドのopt-inスイッチ -- 最上位の `bindings[]` エントリーで `type: "acp"` を持つものは、channelおよびthread向けの永続ACPバインディングを設定します（`match.peer.id` にはchannel/thread idを使用）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 -- `channels.discord.ui.components.accentColor` は、Discord components v2 containerのアクセントカラーを設定します。 -- `channels.discord.voice` は、Discord voice channel会話と任意のauto-join + TTSオーバーライドを有効にします。 -- `channels.discord.voice.daveEncryption` および `channels.discord.voice.decryptionFailureTolerance` は、`@discordjs/voice` のDAVEオプションにそのまま渡されます（デフォルトは `true` と `24`）。 -- OpenClawはさらに、繰り返しdecrypt失敗が起きた後にvoice sessionを退出/再参加することでvoice receive recoveryも試みます。 -- `channels.discord.streaming` が正規のstream modeキーです。レガシーな `streamMode` と真偽値 `streaming` は自動移行されます。 -- `channels.discord.autoPresence` はruntimeの可用性をbot presenceに対応付けます（healthy => online、degraded => idle、exhausted => dnd）。任意のstatus textオーバーライドも可能です。 -- `channels.discord.dangerouslyAllowNameMatching` は、可変なname/tag一致を再有効化します（緊急避難用の互換モード）。 +- 明示的なDiscord `token` を指定する直接の送信呼び出しでは、その呼び出しにそのtokenを使用します。アカウントのリトライ/ポリシー設定は、アクティブなランタイムスナップショット内で選択されたアカウントから引き続き取得されます。 +- 任意の `channels.discord.defaultAccount` は、設定済みアカウントIDに一致する場合、デフォルトアカウント選択を上書きします。 +- 配信ターゲットには `user:`（DM）または `channel:`（guild channel）を使用します。数字のみのIDは拒否されます。 +- Guild slugは小文字で、スペースは `-` に置き換えられます。channelキーにはslug化された名前（`#` なし）を使用します。guild IDの使用を推奨します。 +- Botが作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効化されます。botへのメンションがあるbotメッセージのみを受け付けるには `allowBots: "mentions"` を使用します（自分自身のメッセージは引き続き除外されます）。 +- `channels.discord.guilds..ignoreOtherMentions`（およびchannel上書き）は、botではなく別のユーザーまたはロールにメンションしているメッセージを破棄します（@everyone/@here は除く）。 +- `maxLinesPerMessage`（デフォルト17）は、2000文字未満であっても縦に長いメッセージを分割します。 +- `channels.discord.threadBindings` は、Discordのスレッドにバインドされたルーティングを制御します: + - `enabled`: スレッドバインドセッション機能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインド配信/ルーティング）に対するDiscord上書き + - `idleHours`: 非アクティブ時の自動unfocusまでの時間のDiscord上書き（時間単位、`0` で無効） + - `maxAgeHours`: セッションのハード最大期間のDiscord上書き（時間単位、`0` で無効） + - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` の自動スレッド作成/バインドを有効にするオプトインスイッチ +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、channelおよびスレッド向けの永続ACPバインディングを設定します（`match.peer.id` にはchannel/thread idを使用）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) で共通に定義されています。 +- `channels.discord.ui.components.accentColor` は、Discord components v2コンテナーのアクセントカラーを設定します。 +- `channels.discord.voice` は、Discordのボイスchannel会話と、オプションの自動参加 + TTS上書きを有効にします。 +- `channels.discord.voice.daveEncryption` と `channels.discord.voice.decryptionFailureTolerance` は、`@discordjs/voice` のDAVEオプションにそのまま渡されます（デフォルトは `true` と `24`）。 +- OpenClawはさらに、復号失敗が繰り返された後にボイスセッションから退出して再参加することで、音声受信の回復も試みます。 +- `channels.discord.streaming` は正規のストリームモードキーです。レガシーな `streamMode` と真偽値の `streaming` は自動移行されます。 +- `channels.discord.autoPresence` は、ランタイムの可用性をbotのプレゼンスにマッピングします（healthy => online、degraded => idle、exhausted => dnd）。オプションのステータステキスト上書きも可能です。 +- `channels.discord.dangerouslyAllowNameMatching` は、変更可能なname/tagマッチングを再有効化します（緊急互換モード）。 - `channels.discord.execApprovals`: Discordネイティブのexec承認配信と承認者認可。 - - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。autoモードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合にexec承認が有効になります。 - - `approvers`: exec要求を承認できるDiscord user ID。省略時は `commands.ownerAllowFrom` にフォールバックします。 - - `agentFilter`: 任意のagent ID allowlist。省略するとすべてのagentの承認を転送します。 - - `sessionFilter`: 任意のsession key pattern（部分文字列またはregex）。 - - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）は承認者DMへ、`"channel"` は元channelへ、`"both"` は両方へ送信します。targetに `"channel"` を含む場合、ボタンは解決済み承認者のみ使用できます。 - - `cleanupAfterResolve`: `true` の場合、承認、拒否、またはtimeout後に承認DMを削除します。 + - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。autoモードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合にexec承認が有効化されます。 + - `approvers`: execリクエストを承認できるDiscordユーザーID。省略時は `commands.ownerAllowFrom` にフォールバックします。 + - `agentFilter`: 任意のagent ID許可リスト。省略すると、すべてのagentの承認を転送します。 + - `sessionFilter`: 任意のセッションキーパターン（部分文字列または正規表現）。 + - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）は承認者DMに送信し、`"channel"` は元のchannelに送信し、`"both"` は両方に送信します。targetに `"channel"` が含まれる場合、ボタンを使用できるのは解決済み承認者のみです。 + - `cleanupAfterResolve`: `true` の場合、承認、拒否、またはタイムアウト後に承認DMを削除します。 -**Reaction notificationモード:** `off`（なし）、`own`（botのメッセージ、デフォルト）、`all`（すべてのメッセージ）、`allowlist`（すべてのメッセージに対して `guilds..users` から）。 +**リアクション通知モード:** `off`（なし）、`own`（bot自身のメッセージ、デフォルト）、`all`（すべてのメッセージ）、`allowlist`（`guilds..users` にあるユーザーからの全メッセージ）。 ### Google Chat @@ -393,11 +393,11 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ } ``` -- Service account JSON: インライン（`serviceAccount`）またはファイルベース（`serviceAccountFile`）。 -- Service account SecretRefもサポートされています（`serviceAccountRef`）。 -- Envフォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 配信先ターゲットには `spaces/` または `users/` を使用します。 -- `channels.googlechat.dangerouslyAllowNameMatching` は、可変なemail principal一致を再有効化します（緊急避難用の互換モード）。 +- サービスアカウントJSON: インライン（`serviceAccount`）またはファイルベース（`serviceAccountFile`）。 +- サービスアカウントのSecretRef（`serviceAccountRef`）もサポートされます。 +- 環境変数フォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 +- 配信ターゲットには `spaces/` または `users/` を使用します。 +- `channels.googlechat.dangerouslyAllowNameMatching` は、変更可能なメールプリンシパルマッチングを再有効化します（緊急互換モード）。 ### Slack @@ -449,7 +449,7 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // mode=partialのときSlackネイティブstreaming APIを使用 + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,30 +464,30 @@ WhatsAppはgatewayのweb channel（Baileys Web）経由で動作します。リ } ``` -- **Socket mode** では `botToken` と `appToken` の両方が必要です（デフォルトアカウントのenvフォールバックとして `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** では `botToken` と `signingSecret`（ルートまたはアカウントごと）が必要です。 +- **Socket mode** には `botToken` と `appToken` の両方が必要です（デフォルトアカウントの環境変数フォールバックは `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** には `botToken` と `signingSecret` が必要です（ルートまたはアカウントごと）。 - `botToken`、`appToken`、`signingSecret`、`userToken` は平文文字列またはSecretRefオブジェクトを受け付けます。 -- Slackアカウントsnapshotは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、HTTP modeでは `signingSecretStatus` などの資格情報ごとのsource/statusフィールドを公開します。`configured_unavailable` は、そのアカウントがSecretRefで設定されているが、現在のcommand/runtime pathではsecret値を解決できなかったことを意味します。 -- `configWrites: false` はSlack起点のconfig書き込みをブロックします。 -- 任意の `channels.slack.defaultAccount` は、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 -- `channels.slack.streaming.mode` が正規のSlack stream modeキーです。`channels.slack.streaming.nativeTransport` はSlackのネイティブstreaming transportを制御します。レガシーな `streamMode`、真偽値 `streaming`、`nativeStreaming` は自動移行されます。 -- 配信先ターゲットには `user:`（DM）または `channel:` を使用します。 +- Slackアカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、およびHTTP modeでは `signingSecretStatus` などの資格情報ごとのsource/statusフィールドを公開します。`configured_unavailable` は、アカウントがSecretRef経由で設定されているものの、現在のコマンド/ランタイム経路ではsecret値を解決できなかったことを意味します。 +- `configWrites: false` は、Slack起点の設定書き込みをブロックします。 +- 任意の `channels.slack.defaultAccount` は、設定済みアカウントIDに一致する場合、デフォルトアカウント選択を上書きします。 +- `channels.slack.streaming.mode` は正規のSlackストリームモードキーです。`channels.slack.streaming.nativeTransport` はSlackのネイティブストリーミング転送を制御します。レガシーな `streamMode`、真偽値の `streaming`、および `nativeStreaming` は自動移行されます。 +- 配信ターゲットには `user:`（DM）または `channel:` を使用します。 -**Reaction notificationモード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 +**リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 -**Thread session isolation:** `thread.historyScope` はthread単位（デフォルト）またはchannel共有です。`thread.inheritParent` は親channelのtranscriptを新しいthreadにコピーします。 +**スレッドセッション分離:** `thread.historyScope` はスレッド単位（デフォルト）またはchannel共有です。`thread.inheritParent` は親channelのトランスクリプトを新しいスレッドにコピーします。 -- SlackネイティブstreamingとSlack assistant風の「is typing...」thread statusにはreply thread targetが必要です。最上位DMはデフォルトでthread外のままなので、thread風previewではなく `typingReaction` または通常配信が使用されます。 -- `typingReaction` は、replyの実行中に受信Slackメッセージへ一時的にreactionを追加し、完了時に削除します。`"hourglass_flowing_sand"` のようなSlack emoji shortcodeを使用してください。 -- `channels.slack.execApprovals`: Slackネイティブのexec承認配信と承認者認可。schemaはDiscordと同じです: `enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack user ID）、`agentFilter`、`sessionFilter`、`target`（`"dm"`、`"channel"`、または `"both"`）。 +- Slackネイティブストリーミングと、Slackアシスタント風の「入力中...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベルDMはデフォルトでスレッド外のままなので、スレッド形式プレビューではなく `typingReaction` または通常配信を使用します。 +- `typingReaction` は、返信の実行中に受信Slackメッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` のようなSlack絵文字ショートコードを使用してください。 +- `channels.slack.execApprovals`: Slackネイティブのexec承認配信と承認者認可。schemaはDiscordと同じです: `enabled`（`true`/`false`/`"auto"`）、`approvers`（SlackユーザーID）、`agentFilter`、`sessionFilter`、`target`（`"dm"`、`"channel"`、または `"both"`）。 -| Action group | Default | 注記 | -| ------------ | ------- | ----------------------- | -| reactions | enabled | React + reaction一覧 | -| messages | enabled | 読み取り/送信/編集/削除 | -| pins | enabled | Pin/unpin/list | -| memberInfo | enabled | Member情報 | -| emojiList | enabled | カスタムemoji一覧 | +| Action group | デフォルト | 注記 | +| ------------ | ---------- | ---------------------- | +| reactions | enabled | リアクション追加 + 一覧取得 | +| messages | enabled | 読み取り/送信/編集/削除 | +| pins | enabled | ピン留め/解除/一覧 | +| memberInfo | enabled | メンバー情報 | +| emojiList | enabled | カスタム絵文字一覧 | ### Mattermost @@ -511,7 +511,7 @@ Mattermostはpluginとして提供されます: `openclaw plugins install @openc native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // reverse-proxy/publicデプロイ向けの任意の明示URL + // リバースプロキシ/公開デプロイ向けの任意の明示URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,19 +521,18 @@ Mattermostはpluginとして提供されます: `openclaw plugins install @openc } ``` -Chat mode: `oncall`（@-mention時に応答、デフォルト）、`onmessage`（すべてのメッセージ）、`onchar`（トリガーprefixで始まるメッセージ）。 +チャットモード: `oncall`（@メンション時に応答、デフォルト）、`onmessage`（すべてのメッセージ）、`onchar`（トリガープレフィックスで始まるメッセージ）。 Mattermostネイティブコマンドが有効な場合: -- `commands.callbackPath` はフルURLではなくパスでなければなりません（例: `/api/channels/mattermost/command`）。 -- `commands.callbackUrl` はOpenClaw gateway endpointに解決され、Mattermostサーバーから到達可能である必要があります。 -- ネイティブslash callbackは、slash command登録時にMattermostが返すコマンドごとのtokenで認証されます。登録に失敗した場合、または有効なコマンドがない場合、OpenClawは callbackを `Unauthorized: invalid command token.` で拒否します。 -- 非公開/tailnet/internal callback hostでは、Mattermostが `ServiceSettings.AllowedUntrustedInternalConnections` にcallback host/domainを含める必要があることがあります。 - フルURLではなくhost/domain値を使用してください。 -- `channels.mattermost.configWrites`: Mattermost起点のconfig書き込みを許可または拒否します。 -- `channels.mattermost.requireMention`: channel内で返信する前に `@mention` を必須にします。 -- `channels.mattermost.groups..requireMention`: channelごとのmention-gatingオーバーライド（デフォルトには `"*"`）。 -- 任意の `channels.mattermost.defaultAccount` は、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 +- `commands.callbackPath` はパスである必要があります（例: `/api/channels/mattermost/command`）。完全なURLではありません。 +- `commands.callbackUrl` はOpenClaw Gatewayエンドポイントを解決し、Mattermostサーバーから到達可能である必要があります。 +- ネイティブslashコールバックは、slashコマンド登録時にMattermostから返されるコマンドごとのtokenで認証されます。登録に失敗した場合や有効化されたコマンドがない場合、OpenClawはコールバックを `Unauthorized: invalid command token.` で拒否します。 +- プライベート/tailnet/internalなコールバックホストでは、Mattermostは `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含める必要がある場合があります。完全なURLではなく、ホスト/ドメイン値を使用してください。 +- `channels.mattermost.configWrites`: Mattermost起点の設定書き込みを許可または拒否します。 +- `channels.mattermost.requireMention`: channelで返信する前に `@mention` を要求します。 +- `channels.mattermost.groups..requireMention`: channelごとのメンションゲート上書き（デフォルトには `"*"`）。 +- 任意の `channels.mattermost.defaultAccount` は、設定済みアカウントIDに一致する場合、デフォルトアカウント選択を上書きします。 ### Signal @@ -542,7 +541,7 @@ Mattermostネイティブコマンドが有効な場合: channels: { signal: { enabled: true, - account: "+15555550123", // 任意のアカウントバインディング + account: "+15555550123", // 任意のアカウントバインド dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -554,15 +553,15 @@ Mattermostネイティブコマンドが有効な場合: } ``` -**Reaction notificationモード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 +**リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 -- `channels.signal.account`: channelの起動先を特定のSignalアカウントidentityに固定します。 -- `channels.signal.configWrites`: Signal起点のconfig書き込みを許可または拒否します。 -- 任意の `channels.signal.defaultAccount` は、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 +- `channels.signal.account`: channelの起動を特定のSignalアカウントIDに固定します。 +- `channels.signal.configWrites`: Signal起点の設定書き込みを許可または拒否します。 +- 任意の `channels.signal.defaultAccount` は、設定済みアカウントIDに一致する場合、デフォルトアカウント選択を上書きします。 ### BlueBubbles -BlueBubblesは推奨されるiMessage経路です（pluginベース、`channels.bluebubbles` 配下で設定）。 +BlueBubblesは推奨されるiMessage経路です（pluginバックエンドで、`channels.bluebubbles` 配下に設定します）。 ```json5 { @@ -570,21 +569,21 @@ BlueBubblesは推奨されるiMessage経路です（pluginベース、`channels. bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl、password、webhookPath、group control、高度なaction: - // /channels/bluebubbles を参照 + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` - ここで扱うコアキーパス: `channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 任意の `channels.bluebubbles.defaultAccount` は、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 -- 最上位の `bindings[]` エントリーで `type: "acp"` を持つものは、BlueBubbles会話を永続ACP sessionにバインドできます。`match.peer.id` にはBlueBubbles handleまたはtarget文字列（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用してください。共通フィールド意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 +- 任意の `channels.bluebubbles.defaultAccount` は、設定済みアカウントIDに一致する場合、デフォルトアカウント選択を上書きします。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles会話を永続ACPセッションにバインドできます。`match.peer.id` にはBlueBubbles handleまたはターゲット文字列（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共有フィールドの意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 - 完全なBlueBubbles channel設定は [BlueBubbles](/ja-JP/channels/bluebubbles) に記載されています。 ### iMessage -OpenClawは `imsg rpc`（stdio上のJSON-RPC）を起動します。daemonやportは不要です。 +OpenClawは `imsg rpc`（stdio経由のJSON-RPC）を起動します。daemonやportは不要です。 ```json5 { @@ -608,17 +607,17 @@ OpenClawは `imsg rpc`（stdio上のJSON-RPC）を起動します。daemonやpor } ``` -- 任意の `channels.imessage.defaultAccount` は、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 +- 任意の `channels.imessage.defaultAccount` は、設定済みアカウントIDに一致する場合、デフォルトアカウント選択を上書きします。 -- Messages DBへのFull Disk Accessが必要です。 -- `chat_id:` ターゲットを推奨します。チャット一覧には `imsg chats --limit 20` を使用してください。 -- `cliPath` はSSH wrapperを指すことができます。SCPでattachmentを取得するには `remoteHost`（`host` または `user@host`）を設定します。 -- `attachmentRoots` と `remoteAttachmentRoots` は受信attachmentパスを制限します（デフォルト: `/Users/*/Library/Messages/Attachments`）。 -- SCPでは厳格なhost-keyチェックを使うため、relay host keyがすでに `~/.ssh/known_hosts` に存在していることを確認してください。 -- `channels.imessage.configWrites`: iMessage起点のconfig書き込みを許可または拒否します。 -- 最上位の `bindings[]` エントリーで `type: "acp"` を持つものは、iMessage会話を永続ACP sessionにバインドできます。`match.peer.id` には正規化されたhandleまたは明示的なchat target（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用してください。共通フィールド意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 +- Messages DBへのフルディスクアクセスが必要です。 +- `chat_id:` ターゲットの使用を推奨します。チャット一覧は `imsg chats --limit 20` で確認できます。 +- `cliPath` はSSHラッパーを指すことができます。SCPで添付ファイルを取得する場合は `remoteHost`（`host` または `user@host`）を設定してください。 +- `attachmentRoots` と `remoteAttachmentRoots` は受信添付ファイルのパスを制限します（デフォルト: `/Users/*/Library/Messages/Attachments`）。 +- SCPは厳格なhost-key checkingを使用するため、relay host keyがすでに `~/.ssh/known_hosts` に存在していることを確認してください。 +- `channels.imessage.configWrites`: iMessage起点の設定書き込みを許可または拒否します。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage会話を永続ACPセッションにバインドできます。`match.peer.id` には正規化済みhandleまたは明示的なchatターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共有フィールドの意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 - + ```bash #!/usr/bin/env bash @@ -629,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrixはextensionベースで、`channels.matrix` 配下で設定します。 +Matrixはextensionバックエンドで、`channels.matrix` 配下に設定します。 ```json5 { @@ -660,24 +659,24 @@ Matrixはextensionベースで、`channels.matrix` 配下で設定します。 ``` - Token認証は `accessToken` を使用し、password認証は `userId` + `password` を使用します。 -- `channels.matrix.proxy` はMatrix HTTPトラフィックを明示的なHTTP(S) proxy経由にします。名前付きアカウントは `channels.matrix.accounts..proxy` でこれを上書きできます。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` はprivate/internal homeserverを許可します。`proxy` とこのnetwork opt-inは独立した制御です。 -- `channels.matrix.defaultAccount` はマルチアカウント構成で優先アカウントを選択します。 -- `channels.matrix.autoJoin` のデフォルトは `off` なので、招待されたroomや新しいDM風の招待は、`autoJoin: "allowlist"` と `autoJoinAllowlist`、または `autoJoin: "always"` を設定するまで無視されます。 +- `channels.matrix.proxy` は、Matrix HTTPトラフィックを明示的なHTTP(S) proxy経由でルーティングします。名前付きアカウントは `channels.matrix.accounts..proxy` で上書きできます。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` は、プライベート/内部homeserverを許可します。`proxy` とこのネットワークopt-inは独立した制御です。 +- `channels.matrix.defaultAccount` は、複数アカウント構成で優先アカウントを選択します。 +- `channels.matrix.autoJoin` のデフォルトは `off` であり、`autoJoin: "allowlist"` と `autoJoinAllowlist`、または `autoJoin: "always"` を設定するまで、招待されたルームや新しいDMスタイルの招待は無視されます。 - `channels.matrix.execApprovals`: Matrixネイティブのexec承認配信と承認者認可。 - - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。autoモードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合にexec承認が有効になります。 - - `approvers`: exec要求を承認できるMatrix user ID（例: `@owner:example.org`）。 - - `agentFilter`: 任意のagent ID allowlist。省略するとすべてのagentの承認を転送します。 - - `sessionFilter`: 任意のsession key pattern（部分文字列またはregex）。 - - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）、`"channel"`（元room）、または `"both"`。 - - アカウントごとのオーバーライド: `channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` はMatrix DMがsessionへどうグループ化されるかを制御します: `per-user`（デフォルト）はroutingされたpeer単位で共有し、`per-room` は各DM roomを分離します。 -- Matrix status probeとlive directory lookupはruntime trafficと同じproxy policyを使用します。 -- 完全なMatrix設定、ターゲティングルール、セットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 + - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。autoモードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合にexec承認が有効化されます。 + - `approvers`: execリクエストを承認できるMatrixユーザーID（例: `@owner:example.org`）。 + - `agentFilter`: 任意のagent ID許可リスト。省略すると、すべてのagentの承認を転送します。 + - `sessionFilter`: 任意のセッションキーパターン（部分文字列または正規表現）。 + - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）、`"channel"`（元のroom）、または `"both"`。 + - アカウントごとの上書き: `channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` は、Matrix DMをどのようにセッションにまとめるかを制御します: `per-user`（デフォルト）はルーティングされたpeerごとに共有し、`per-room` は各DM roomを分離します。 +- Matrixのステータスプローブとライブディレクトリ参照は、ランタイムトラフィックと同じproxyポリシーを使用します。 +- 完全なMatrix設定、ターゲティングルール、およびセットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 ### Microsoft Teams -Microsoft Teamsはextensionベースで、`channels.msteams` 配下で設定します。 +Microsoft Teamsはextensionバックエンドで、`channels.msteams` 配下に設定します。 ```json5 { @@ -685,19 +684,19 @@ Microsoft Teamsはextensionベースで、`channels.msteams` 配下で設定し msteams: { enabled: true, configWrites: true, - // appId、appPassword、tenantId、webhook、team/channel policy: - // /channels/msteams を参照 + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` - ここで扱うコアキーパス: `channels.msteams`、`channels.msteams.configWrites`。 -- 完全なTeams設定（資格情報、webhook、DM/group policy、team/channelごとのオーバーライド）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 +- 完全なTeams設定（資格情報、webhook、DM/グループポリシー、teamごと/channelごとの上書き）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 ### IRC -IRCはextensionベースで、`channels.irc` 配下で設定します。 +IRCはextensionバックエンドで、`channels.irc` 配下に設定します。 ```json5 { @@ -719,12 +718,12 @@ IRCはextensionベースで、`channels.irc` 配下で設定します。 ``` - ここで扱うコアキーパス: `channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 任意の `channels.irc.defaultAccount` は、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 -- 完全なIRC channel設定（host/port/TLS/channels/allowlist/mention gating）は [IRC](/ja-JP/channels/irc) に記載されています。 +- 任意の `channels.irc.defaultAccount` は、設定済みアカウントIDに一致する場合、デフォルトアカウント選択を上書きします。 +- 完全なIRC channel設定（host/port/TLS/channels/allowlists/mention gating）は [IRC](/ja-JP/channels/irc) に記載されています。 -### マルチアカウント（全channel共通） +### 複数アカウント（全channels） -channelごとに複数アカウント（それぞれ独自の `accountId`）を実行します: +channelごとに複数アカウントを実行できます（それぞれ独自の `accountId` を持ちます）: ```json5 { @@ -745,28 +744,28 @@ channelごとに複数アカウント（それぞれ独自の `accountId`）を } ``` -- `accountId` が省略された場合、`default` が使われます（CLI + routing）。 -- Env tokenは **default** アカウントにのみ適用されます。 +- `accountId` が省略された場合は `default` が使用されます（CLI + ルーティング）。 +- 環境変数tokenは **default** アカウントにのみ適用されます。 - ベースchannel設定は、アカウントごとに上書きされない限り、すべてのアカウントに適用されます。 -- 各アカウントを異なるagentへルーティングするには `bindings[].match.accountId` を使用します。 -- 単一アカウントの最上位channel configのまま `openclaw channels add`（またはchannel onboarding）で非defaultアカウントを追加すると、OpenClawは最初にアカウントスコープの最上位単一アカウント値をそのchannel account mapへ昇格し、元のアカウントが引き続き動作するようにします。ほとんどのchannelではこれらを `channels..accounts.default` へ移動しますが、Matrixは既存の一致するnamed/default targetを保持できます。 -- 既存のchannel専用binding（`accountId` なし）は引き続きdefaultアカウントに一致します。accountスコープbindingは引き続き任意です。 -- `openclaw doctor --fix` も、アカウントスコープの最上位単一アカウント値をそのchannelで選ばれた昇格先アカウントへ移動することで混在形状を修復します。ほとんどのchannelは `accounts.default` を使用し、Matrixは既存の一致するnamed/default targetを保持できます。 +- 各アカウントを別のagentにルーティングするには `bindings[].match.accountId` を使用します。 +- 単一アカウントのトップレベルchannel設定のまま `openclaw channels add`（またはchannelオンボーディング）で非defaultアカウントを追加すると、OpenClawはまずアカウントスコープのトップレベル単一アカウント値をchannelアカウントマップへ昇格し、元のアカウントが引き続き動作するようにします。ほとんどのchannelsではそれらを `channels..accounts.default` に移動します。Matrixは代わりに既存の一致するnamed/defaultターゲットを保持できます。 +- 既存のchannelのみのbinding（`accountId` なし）はdefaultアカウントに引き続き一致し、アカウントスコープのbindingは引き続き任意です。 +- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値を、そのchannel向けに選ばれた昇格先アカウントへ移動することで、混在した形状を修復します。ほとんどのchannelsでは `accounts.default` を使用し、Matrixは既存の一致するnamed/defaultターゲットを保持できます。 ### その他のextension channel 多くのextension channelは `channels.` として設定され、専用のchannelページに記載されています（たとえば Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 -完全なchannel索引: [Channels](/ja-JP/channels)。 +完全なchannel一覧は [Channels](/ja-JP/channels) を参照してください。 -### グループチャットmention gating +### グループチャットのメンションゲート -グループメッセージはデフォルトで **mention必須** です（メタデータmentionまたは安全なregex pattern）。WhatsApp、Telegram、Discord、Google Chat、iMessageのグループチャットに適用されます。 +グループメッセージはデフォルトで **メンション必須** です（メタデータメンションまたは安全な正規表現パターン）。WhatsApp、Telegram、Discord、Google Chat、およびiMessageグループチャットに適用されます。 -**Mentionの種類:** +**メンションの種類:** -- **Metadata mentions**: ネイティブプラットフォームの @-mention。WhatsApp self-chat modeでは無視されます。 -- **Text patterns**: `agents.list[].groupChat.mentionPatterns` 内の安全なregex pattern。無効なpatternや安全でない入れ子反復は無視されます。 -- Mention gatingは、検出が可能な場合（ネイティブmentionまたは少なくとも1つのpatternがある場合）にのみ適用されます。 +- **メタデータメンション**: ネイティブなプラットフォームの@メンション。WhatsAppのself-chat modeでは無視されます。 +- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` 内の安全な正規表現パターン。無効なパターンや安全でないネストした反復は無視されます。 +- メンションゲートは、検出が可能な場合にのみ適用されます（ネイティブメンションまたは少なくとも1つのパターンがある場合）。 ```json5 { @@ -779,9 +778,9 @@ channelごとに複数アカウント（それぞれ独自の `accountId`）を } ``` -`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。channel側で `channels..historyLimit`（またはアカウントごと）で上書きできます。無効化するには `0` を設定します。 +`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。channelsは `channels..historyLimit`（またはアカウントごと）で上書きできます。無効化するには `0` を設定します。 -#### DM履歴上限 +#### DM履歴制限 ```json5 { @@ -796,13 +795,13 @@ channelごとに複数アカウント（それぞれ独自の `accountId`）を } ``` -解決順序: DMごとのオーバーライド → providerデフォルト → 上限なし（すべて保持）。 +解決順: DMごとの上書き → providerデフォルト → 制限なし（すべて保持）。 対応: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### Self-chat mode -自分自身の番号を `allowFrom` に含めるとself-chat modeが有効になります（ネイティブ @-mentionを無視し、text patternにのみ応答）: +自分の番号を `allowFrom` に含めるとself-chat modeが有効になります（ネイティブな@メンションは無視し、テキストパターンにのみ応答します）: ```json5 { @@ -828,10 +827,10 @@ channelごとに複数アカウント（それぞれ独自の `accountId`）を ```json5 { commands: { - native: "auto", // サポートされる場合はネイティブコマンドを登録 - nativeSkills: "auto", // サポートされる場合はネイティブskillコマンドを登録 + native: "auto", // サポートされている場合はネイティブコマンドを登録 + nativeSkills: "auto", // サポートされている場合はネイティブskillコマンドを登録 text: true, // チャットメッセージ内の /commands を解析 - bash: false, // ! を許可（alias: /bash） + bash: false, // ! を許可（別名: /bash） bashForegroundMs: 2000, config: false, // /config を許可 mcp: false, // /mcp を許可 @@ -850,32 +849,32 @@ channelごとに複数アカウント（それぞれ独自の `accountId`）を } ``` - + -- このブロックはコマンド面を設定します。現在の組み込み + bundledコマンドカタログについては [Slash Commands](/ja-JP/tools/slash-commands) を参照してください。 -- このページは **config-keyリファレンス** であり、完全なコマンドカタログではありません。QQ Botの `/bot-ping` `/bot-help` `/bot-logs`、LINEの `/card`、device-pairの `/pair`、memoryの `/dreaming`、phone-controlの `/phone`、Talkの `/voice` など、channel/plugin所有のコマンドは各channel/pluginページと [Slash Commands](/ja-JP/tools/slash-commands) に記載されています。 -- Text commandは先頭に `/` が付いた **単独メッセージ** でなければなりません。 -- `native: "auto"` はDiscord/Telegramではネイティブコマンドを有効にし、Slackではオフのままにします。 -- `nativeSkills: "auto"` はDiscord/Telegramではネイティブskillコマンドを有効にし、Slackではオフのままにします。 -- channelごとの上書き: `channels.discord.commands.native`（bool または `"auto"`）。`false` は以前に登録されたコマンドを解除します。 -- `channels..commands.nativeSkills` でネイティブskill登録をchannelごとに上書きできます。 -- `channels.telegram.customCommands` は追加のTelegram bot menuエントリーを加えます。 -- `bash: true` はホストshell用の `! ` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.` に含まれている必要があります。 -- `config: true` は `/config` を有効にします（`openclaw.json` の読み書き）。gateway `chat.send` clientでは、永続的な `/config set|unset` 書き込みには `operator.admin` も必要です。読み取り専用の `/config show` は通常の書き込みスコープoperator clientでも引き続き利用できます。 -- `mcp: true` は、`mcp.servers` 配下のOpenClaw管理MCP server設定に対する `/mcp` を有効にします。 -- `plugins: true` は、plugin検出、インストール、有効/無効制御の `/plugins` を有効にします。 -- `channels..configWrites` はchannelごとのconfig変更を制御します（デフォルト: true）。 -- マルチアカウントchannelでは、`channels..accounts..configWrites` も、そのアカウントを対象とする書き込み（たとえば `/allowlist --config --account ` や `/config set channels..accounts....`）を制御します。 -- `restart: false` は `/restart` とgateway restart tool actionを無効化します。デフォルト: `true`。 -- `ownerAllowFrom` はowner専用コマンド/tool用の明示的なowner allowlistです。`allowFrom` とは別です。 -- `ownerDisplay: "hash"` はsystem prompt内のowner idをハッシュ化します。ハッシュ制御には `ownerDisplaySecret` を設定してください。 -- `allowFrom` はproviderごとです。設定されると、これが **唯一の** 認可ソースとなります（channel allowlist/pairing と `useAccessGroups` は無視されます）。 -- `useAccessGroups: false` は、`allowFrom` が設定されていないときにコマンドがaccess-groupポリシーをバイパスできるようにします。 -- コマンドドキュメント対応表: +- このブロックはコマンドサーフェスを設定します。現在の組み込み + bundledコマンドカタログについては、[Slash Commands](/ja-JP/tools/slash-commands) を参照してください。 +- このページは**設定キーのリファレンス**であり、完全なコマンドカタログではありません。QQ Botの `/bot-ping` `/bot-help` `/bot-logs`、LINEの `/card`、device-pairの `/pair`、memoryの `/dreaming`、phone-controlの `/phone`、Talkの `/voice` など、channel/plugin所有のコマンドは、それぞれのchannel/pluginページと [Slash Commands](/ja-JP/tools/slash-commands) に記載されています。 +- テキストコマンドは、先頭に `/` が付いた**単独の**メッセージである必要があります。 +- `native: "auto"` はDiscord/Telegramでネイティブコマンドを有効にし、Slackでは無効のままにします。 +- `nativeSkills: "auto"` はDiscord/Telegramでネイティブskillコマンドを有効にし、Slackでは無効のままにします。 +- channelごとの上書き: `channels.discord.commands.native`（bool または `"auto"`）。`false` は以前に登録されたコマンドをクリアします。 +- ネイティブskill登録は `channels..commands.nativeSkills` でchannelごとに上書きできます。 +- `channels.telegram.customCommands` は追加のTelegram botメニュー項目を加えます。 +- `bash: true` はホストshell向けの `! ` を有効にします。`tools.elevated.enabled` が必要で、送信者が `tools.elevated.allowFrom.` に含まれている必要があります。 +- `config: true` は `/config` を有効にします（`openclaw.json` を読み書きします）。Gateway `chat.send` クライアントでは、永続的な `/config set|unset` 書き込みには `operator.admin` も必要です。読み取り専用の `/config show` は通常の書き込みスコープを持つoperatorクライアントでも引き続き使用できます。 +- `mcp: true` は `mcp.servers` 配下のOpenClaw管理MCPサーバー設定に対する `/mcp` を有効にします。 +- `plugins: true` はpluginの検出、インストール、有効化/無効化制御のための `/plugins` を有効にします。 +- `channels..configWrites` はchannelごとの設定変更を制御します（デフォルト: true）。 +- 複数アカウントchannelでは、`channels..accounts..configWrites` も、そのアカウントを対象とする書き込み（たとえば `/allowlist --config --account ` や `/config set channels..accounts....`）を制御します。 +- `restart: false` は `/restart` とgateway restart toolアクションを無効にします。デフォルト: `true`。 +- `ownerAllowFrom` は、owner専用コマンド/tool向けの明示的なowner許可リストです。`allowFrom` とは別です。 +- `ownerDisplay: "hash"` は、system prompt内のowner IDをハッシュ化します。ハッシュ化を制御するには `ownerDisplaySecret` を設定してください。 +- `allowFrom` はproviderごとです。設定されている場合、それが**唯一の**認可ソースになります（channel allowlist/ペアリングと `useAccessGroups` は無視されます）。 +- `useAccessGroups: false` は、`allowFrom` が設定されていない場合に、コマンドがaccess-groupポリシーをバイパスできるようにします。 +- コマンドドキュメントの対応: - 組み込み + bundledカタログ: [Slash Commands](/ja-JP/tools/slash-commands) - - channel固有のコマンド面: [Channels](/ja-JP/channels) + - channel固有のコマンドサーフェス: [Channels](/ja-JP/channels) - QQ Botコマンド: [QQ Bot](/ja-JP/channels/qqbot) - - pairingコマンド: [Pairing](/ja-JP/channels/pairing) + - ペアリングコマンド: [Pairing](/ja-JP/channels/pairing) - LINE cardコマンド: [LINE](/ja-JP/channels/line) - memory dreaming: [Dreaming](/ja-JP/concepts/dreaming) @@ -883,7 +882,7 @@ channelごとに複数アカウント（それぞれ独自の `accountId`）を --- -## Agent defaults +## Agentのデフォルト ### `agents.defaults.workspace` @@ -897,7 +896,7 @@ channelごとに複数アカウント（それぞれ独自の `accountId`）を ### `agents.defaults.repoRoot` -system promptのRuntime行に表示される任意のrepository rootです。未設定の場合、OpenClawはworkspaceから上方向へたどって自動検出します。 +system promptのRuntime行に表示される任意のリポジトリルートです。未設定の場合、OpenClawはworkspaceから上方向にたどって自動検出します。 ```json5 { @@ -907,29 +906,29 @@ system promptのRuntime行に表示される任意のrepository rootです。未 ### `agents.defaults.skills` -`agents.list[].skills` を設定していないagent向けの任意のデフォルトskill allowlistです。 +`agents.list[].skills` を設定していないagent向けの、任意のデフォルトskill許可リストです。 ```json5 { agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // github, weatherを継承 - { id: "docs", skills: ["docs-search"] }, // デフォルトを置き換え + { id: "writer" }, // github, weather を継承 + { id: "docs", skills: ["docs-search"] }, // デフォルトを置き換える { id: "locked-down", skills: [] }, // skillなし ], }, } ``` -- デフォルトで制限なしのSkillsにするには `agents.defaults.skills` を省略します。 -- デフォルト値を継承するには `agents.list[].skills` を省略します。 +- デフォルトでskillsを無制限にするには `agents.defaults.skills` を省略します。 +- デフォルトを継承するには `agents.list[].skills` を省略します。 - skillなしにするには `agents.list[].skills: []` を設定します。 -- 空でない `agents.list[].skills` 一覧は、そのagentの最終セットです。デフォルトとはマージされません。 +- 空でない `agents.list[].skills` の一覧は、そのagentの最終セットです。デフォルトとはマージされません。 ### `agents.defaults.skipBootstrap` -workspace bootstrapファイル（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）の自動作成を無効化します。 +workspace bootstrapファイル（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）の自動作成を無効にします。 ```json5 { @@ -939,9 +938,9 @@ workspace bootstrapファイル（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTI ### `agents.defaults.contextInjection` -workspace bootstrapファイルがsystem promptに注入されるタイミングを制御します。デフォルトは `"always"` です。 +workspace bootstrapファイルをsystem promptに注入するタイミングを制御します。デフォルト: `"always"`。 -- `"continuation-skip"`: 安全な継続ターン（assistantの応答完了後）ではworkspace bootstrapの再注入をスキップし、promptサイズを削減します。heartbeat実行やcompaction後の再試行では引き続きcontextを再構築します。 +- `"continuation-skip"`: 安全な継続ターン（assistant応答が完了した後）ではworkspace bootstrapの再注入をスキップし、promptサイズを削減します。heartbeat実行とcompact後の再試行では引き続きコンテキストを再構築します。 ```json5 { @@ -961,7 +960,7 @@ workspace bootstrapファイルがsystem promptに注入されるタイミング ### `agents.defaults.bootstrapTotalMaxChars` -全workspace bootstrapファイルにまたがって注入される総最大文字数。デフォルト: `150000`。 +すべてのworkspace bootstrapファイルにまたがって注入される最大合計文字数。デフォルト: `150000`。 ```json5 { @@ -971,12 +970,12 @@ workspace bootstrapファイルがsystem promptに注入されるタイミング ### `agents.defaults.bootstrapPromptTruncationWarning` -bootstrap contextが切り詰められたときにagentへ見える警告文を制御します。 +bootstrapコンテキストが切り詰められたときにagentに見える警告テキストを制御します。 デフォルト: `"once"`。 -- `"off"`: 警告文をsystem promptへ一切注入しません。 -- `"once"`: 一意の切り詰め署名ごとに1回だけ警告を注入します（推奨）。 -- `"always"`: 切り詰めが存在するたびに毎回警告を注入します。 +- `"off"`: 警告テキストをsystem promptに一切注入しません。 +- `"once"`: 一意の切り詰めシグネチャごとに1回だけ警告を注入します（推奨）。 +- `"always"`: 切り詰めが存在する場合、毎回の実行で警告を注入します。 ```json5 { @@ -986,11 +985,11 @@ bootstrap contextが切り詰められたときにagentへ見える警告文を ### `agents.defaults.imageMaxDimensionPx` -provider呼び出し前にtranscript/tool image blockで長辺に許可される最大ピクセルサイズ。 +provider呼び出し前のトランスクリプト/tool画像ブロックにおける、画像の最長辺の最大ピクセルサイズ。 デフォルト: `1200`。 -低い値は通常、vision token使用量とrequest payloadサイズを削減します。 -高い値はより多くの視覚的詳細を保持します。 +通常、値を低くすると、スクリーンショットが多い実行でのvision token使用量とリクエストペイロードサイズが減少します。 +値を高くすると、より多くの視覚的詳細が保持されます。 ```json5 { @@ -1000,7 +999,7 @@ provider呼び出し前にtranscript/tool image blockで長辺に許可される ### `agents.defaults.userTimezone` -system prompt context用のtimezoneです（メッセージtimestampではありません）。ホストtimezoneにフォールバックします。 +system promptコンテキスト用のタイムゾーンです（メッセージのタイムスタンプではありません）。ホストのタイムゾーンにフォールバックします。 ```json5 { @@ -1010,7 +1009,7 @@ system prompt context用のtimezoneです（メッセージtimestampではあり ### `agents.defaults.timeFormat` -system prompt内の時刻形式。デフォルト: `auto`（OS設定）。 +system prompt内の時刻形式です。デフォルト: `auto`（OS設定）。 ```json5 { @@ -1048,7 +1047,11 @@ system prompt内の時刻形式。デフォルト: `auto`（OS設定）。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // グローバルデフォルトprovider params + params: { cacheRetention: "long" }, // グローバルなデフォルトprovider params + embeddedHarness: { + runtime: "auto", // auto | pi | 登録済みharness id（例: codex） + fallback: "pi", // pi | none + }, pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1064,44 +1067,71 @@ system prompt内の時刻形式。デフォルト: `auto`（OS設定）。 ``` - `model`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - 文字列形式はprimary modelのみを設定します。 - - オブジェクト形式はprimaryに加えて順序付きfailover modelを設定します。 + - 文字列形式はプライマリモデルのみを設定します。 + - オブジェクト形式はプライマリに加え、順序付きのフェイルオーバーモデルを設定します。 - `imageModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - `image` tool pathがvision-model設定として使用します。 - - 選択済み/デフォルトmodelがimage入力を受け付けられない場合のフォールバックroutingにも使用されます。 + - `image` tool経路で、そのvision-model設定として使用されます。 + - 選択済み/デフォルトのモデルが画像入力を受け付けられない場合のフォールバックルーティングにも使用されます。 - `imageGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - 共有image-generation capabilityと、将来のimage生成tool/plugin面で使用されます。 - - 一般的な値: Geminiネイティブimage生成には `google/gemini-3.1-flash-image-preview`、falには `fal/fal-ai/flux/dev`、OpenAI Imagesには `openai/gpt-image-1`。 - - provider/modelを直接選択する場合は、対応するprovider auth/API keyも設定してください（たとえば `google/*` なら `GEMINI_API_KEY` または `GOOGLE_API_KEY`、`openai/*` なら `OPENAI_API_KEY`、`fal/*` なら `FAL_KEY`）。 - - 省略した場合でも、`image_generate` はauth付きproviderデフォルトを推測できます。まず現在のデフォルトproviderを試し、その後残りの登録済みimage-generation providerをprovider-id順に試します。 + - 共有の画像生成機能、および今後画像を生成するあらゆるtool/pluginサーフェスで使用されます。 + - 典型的な値: Geminiネイティブ画像生成には `google/gemini-3.1-flash-image-preview`、falには `fal/fal-ai/flux/dev`、OpenAI Imagesには `openai/gpt-image-1`。 + - provider/modelを直接選択する場合は、一致するprovider auth/APIキーも設定してください（たとえば `google/*` には `GEMINI_API_KEY` または `GOOGLE_API_KEY`、`openai/*` には `OPENAI_API_KEY`、`fal/*` には `FAL_KEY`）。 + - 省略した場合でも、`image_generate` はauthが有効なproviderデフォルトを推論できます。最初に現在のデフォルトproviderを試し、その後、残りの登録済み画像生成providerをprovider-id順に試します。 - `musicGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - 共有music-generation capabilityと組み込み `music_generate` toolで使用されます。 - - 一般的な値: `google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`、または `minimax/music-2.5+`。 - - 省略した場合でも、`music_generate` はauth付きproviderデフォルトを推測できます。まず現在のデフォルトproviderを試し、その後残りの登録済みmusic-generation providerをprovider-id順に試します。 - - provider/modelを直接選択する場合は、対応するprovider auth/API keyも設定してください。 + - 共有の音楽生成機能と組み込みの `music_generate` toolで使用されます。 + - 典型的な値: `google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`、または `minimax/music-2.5+`。 + - 省略した場合でも、`music_generate` はauthが有効なproviderデフォルトを推論できます。最初に現在のデフォルトproviderを試し、その後、残りの登録済み音楽生成providerをprovider-id順に試します。 + - provider/modelを直接選択する場合は、一致するprovider auth/APIキーも設定してください。 - `videoGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - 共有video-generation capabilityと組み込み `video_generate` toolで使用されます。 - - 一般的な値: `qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`、または `qwen/wan2.7-r2v`。 - - 省略した場合でも、`video_generate` はauth付きproviderデフォルトを推測できます。まず現在のデフォルトproviderを試し、その後残りの登録済みvideo-generation providerをprovider-id順に試します。 - - provider/modelを直接選択する場合は、対応するprovider auth/API keyも設定してください。 - - bundledのQwen video-generation providerは、最大1本の出力video、1枚の入力image、4本の入力video、10秒のduration、およびproviderレベルの `size`、`aspectRatio`、`resolution`、`audio`、`watermark` オプションをサポートします。 + - 共有の動画生成機能と組み込みの `video_generate` toolで使用されます。 + - 典型的な値: `qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`、または `qwen/wan2.7-r2v`。 + - 省略した場合でも、`video_generate` はauthが有効なproviderデフォルトを推論できます。最初に現在のデフォルトproviderを試し、その後、残りの登録済み動画生成providerをprovider-id順に試します。 + - provider/modelを直接選択する場合は、一致するprovider auth/APIキーも設定してください。 + - bundledのQwen動画生成providerは、最大で出力動画1本、入力画像1枚、入力動画4本、長さ10秒、およびproviderレベルの `size`、`aspectRatio`、`resolution`、`audio`、`watermark` オプションをサポートします。 - `pdfModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - `pdf` toolのmodel routingに使用されます。 - - 省略時、PDF toolは `imageModel` にフォールバックし、その後解決済みsession/default modelへフォールバックします。 -- `pdfMaxBytesMb`: `pdf` toolで呼び出し時に `maxBytesMb` が渡されない場合のデフォルトPDFサイズ上限。 -- `pdfMaxPages`: `pdf` toolの抽出フォールバックモードで考慮されるデフォルト最大ページ数。 + - `pdf` toolのモデルルーティングに使用されます。 + - 省略した場合、PDF toolは `imageModel` にフォールバックし、その後、解決済みのセッション/デフォルトモデルにフォールバックします。 +- `pdfMaxBytesMb`: 呼び出し時に `maxBytesMb` が渡されない場合の、`pdf` toolに対するデフォルトPDFサイズ上限。 +- `pdfMaxPages`: `pdf` toolの抽出フォールバックモードで考慮するデフォルトの最大ページ数。 - `verboseDefault`: agentのデフォルトverboseレベル。値: `"off"`、`"on"`、`"full"`。デフォルト: `"off"`。 - `elevatedDefault`: agentのデフォルトelevated-outputレベル。値: `"off"`、`"on"`、`"ask"`、`"full"`。デフォルト: `"on"`。 -- `model.primary`: 形式は `provider/model`（例: `openai/gpt-5.4`）。providerを省略すると、OpenClawはまずaliasを試し、次にその正確なmodel idに一致する一意のconfigured-provider matchを試し、その後でのみ設定済みデフォルトproviderへフォールバックします（レガシー互換動作のため非推奨なので、明示的な `provider/model` を推奨）。そのproviderが設定済みデフォルトmodelを提供しなくなった場合、OpenClawは古い削除済みproviderデフォルトを表示する代わりに、最初の設定済みprovider/modelへフォールバックします。 -- `models`: 設定されたmodel catalogおよび `/model` 用allowlistです。各エントリーには `alias`（短縮名）と `params`（provider固有、たとえば `temperature`、`maxTokens`、`cacheRetention`、`context1m`）を含められます。 -- `params`: すべてのmodelに適用されるグローバルデフォルトprovider parameterです。`agents.defaults.params` で設定します（例: `{ cacheRetention: "long" }`）。 -- `params` のマージ優先順位（config）: `agents.defaults.params`（グローバルベース）は `agents.defaults.models["provider/model"].params`（modelごと）で上書きされ、その後 `agents.list[].params`（一致するagent id）がキーごとに上書きします。詳細は [Prompt Caching](/ja-JP/reference/prompt-caching) を参照してください。 -- これらのフィールドを変更するconfig writer（たとえば `/models set`、`/models set-image`、fallback add/remove command）は、可能な限り既存fallback listを保持しつつ正規のobject formで保存します。 -- `maxConcurrent`: sessionをまたいだ並列agent実行の最大数（各session自体は引き続き直列化されます）。デフォルト: 4。 +- `model.primary`: 形式は `provider/model`（例: `openai/gpt-5.4`）。providerを省略した場合、OpenClawは最初にaliasを試し、次にその正確なmodel idに対する一意のconfigured-provider一致を試し、それでもだめならconfigured default providerにフォールバックします（非推奨の互換動作のため、明示的な `provider/model` を推奨します）。そのproviderが設定済みのデフォルトモデルをもう提供していない場合、OpenClawは古い削除済みproviderデフォルトをそのまま出す代わりに、最初のconfigured provider/modelにフォールバックします。 +- `models`: `/model` 用の設定済みモデルカタログおよび許可リストです。各エントリには `alias`（ショートカット）と `params`（provider固有。例: `temperature`、`maxTokens`、`cacheRetention`、`context1m`）を含められます。 +- `params`: すべてのモデルに適用されるグローバルなデフォルトproviderパラメーターです。`agents.defaults.params` に設定します（例: `{ cacheRetention: "long" }`）。 +- `params` のマージ優先順位（config）: `agents.defaults.params`（グローバルベース）は、`agents.defaults.models["provider/model"].params`（モデルごと）で上書きされ、その後 `agents.list[].params`（一致するagent id）がキーごとに上書きします。詳細は [Prompt Caching](/ja-JP/reference/prompt-caching) を参照してください。 +- `embeddedHarness`: デフォルトの低レベル埋め込みagentランタイムポリシー。登録済みplugin harnessに対応モデルを引き受けさせるには `runtime: "auto"`、組み込みPI harnessを強制するには `runtime: "pi"`、または `runtime: "codex"` のような登録済みharness idを使用します。自動PIフォールバックを無効にするには `fallback: "none"` を設定します。 +- これらのフィールドを変更するconfig writer（たとえば `/models set`、`/models set-image`、fallbackの追加/削除コマンド）は、正規のオブジェクト形式で保存し、可能な限り既存のfallbackリストを保持します。 +- `maxConcurrent`: セッションをまたいだagent実行の最大並列数です（各セッション自体は引き続き直列化されます）。デフォルト: 4。 -**組み込みalias短縮形**（modelが `agents.defaults.models` にある場合のみ適用）: +### `agents.defaults.embeddedHarness` -| Alias | Model | +`embeddedHarness` は、埋め込みagentターンを実行する低レベルexecutorを制御します。 +ほとんどのデプロイでは、デフォルトの `{ runtime: "auto", fallback: "pi" }` のままにしておくべきです。 +bundledのCodex app-server harnessのように、信頼できるpluginがネイティブharnessを提供する場合に使用します。 + +```json5 +{ + agents: { + defaults: { + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + }, +} +``` + +- `runtime`: `"auto"`、`"pi"`、または登録済みplugin harness id。bundledのCodex pluginは `codex` を登録します。 +- `fallback`: `"pi"` または `"none"`。`"pi"` は互換フォールバックとして組み込みPI harnessを維持します。`"none"` は、plugin harnessの選択が存在しない、または未対応の場合に、黙ってPIを使うのではなく失敗させます。 +- 環境変数による上書き: `OPENCLAW_AGENT_RUNTIME=` は `runtime` を上書きし、`OPENCLAW_AGENT_HARNESS_FALLBACK=none` はそのプロセスでPIフォールバックを無効にします。 +- Codex専用デプロイでは、`model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"`、`embeddedHarness.fallback: "none"` を設定します。 +- これは埋め込みchat harnessのみを制御します。メディア生成、vision、PDF、音楽、動画、およびTTSは引き続きそれぞれのprovider/model設定を使用します。 + +**組み込みalias短縮形**（モデルが `agents.defaults.models` にある場合にのみ適用されます）: + +| Alias | モデル | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1114,13 +1144,13 @@ system prompt内の時刻形式。デフォルト: `auto`（OS設定）。 設定したaliasは常にデフォルトより優先されます。 -Z.AI GLM-4.x modelでは、`--thinking off` を設定するか `agents.defaults.models["zai/"].params.thinking` を自分で定義しない限り、自動的にthinking modeが有効になります。 -Z.AI modelではtool call streaming向けにデフォルトで `tool_stream` が有効です。無効にするには `agents.defaults.models["zai/"].params.tool_stream` を `false` に設定してください。 -Anthropic Claude 4.6 modelでは、明示的なthinking levelが設定されていない場合、デフォルトで `adaptive` thinkingになります。 +Z.AIのGLM-4.xモデルは、`--thinking off` を設定するか、`agents.defaults.models["zai/"].params.thinking` を自分で定義しない限り、自動的にthinking modeを有効にします。 +Z.AIモデルは、tool callストリーミングのためにデフォルトで `tool_stream` を有効にします。無効にするには `agents.defaults.models["zai/"].params.tool_stream` を `false` に設定してください。 +Anthropic Claude 4.6モデルは、明示的なthinkingレベルが設定されていない場合、デフォルトで `adaptive` thinkingを使用します。 ### `agents.defaults.cliBackends` -text-onlyフォールバック実行（tool callなし）向けの任意のCLI backendです。API providerが失敗したときのバックアップとして便利です。 +テキストのみのフォールバック実行（tool callなし）向けの任意のCLI backendです。API providerが失敗したときのバックアップとして便利です。 ```json5 { @@ -1148,13 +1178,13 @@ text-onlyフォールバック実行（tool callなし）向けの任意のCLI b } ``` -- CLI backendはtext-firstです。toolは常に無効です。 -- `sessionArg` が設定されていればsessionをサポートします。 -- `imageArg` がfile pathを受け付ける場合、image pass-throughをサポートします。 +- CLI backendはテキスト優先です。toolsは常に無効です。 +- `sessionArg` が設定されている場合はセッションをサポートします。 +- `imageArg` がファイルパスを受け付ける場合は画像のパススルーをサポートします。 ### `agents.defaults.systemPromptOverride` -OpenClawが組み立てたsystem prompt全体を固定文字列で置き換えます。デフォルトレベル（`agents.defaults.systemPromptOverride`）またはagentごと（`agents.list[].systemPromptOverride`）で設定します。agentごとの値が優先され、空または空白のみの値は無視されます。制御されたprompt実験に便利です。 +OpenClawが組み立てたsystem prompt全体を固定文字列で置き換えます。デフォルトレベル（`agents.defaults.systemPromptOverride`）またはagentごと（`agents.list[].systemPromptOverride`）に設定します。agentごとの値が優先され、空または空白のみの値は無視されます。制御されたprompt実験に便利です。 ```json5 { @@ -1178,30 +1208,32 @@ OpenClawが組み立てたsystem prompt全体を固定文字列で置き換え every: "30m", // 0m で無効 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false でsystem promptからHeartbeatセクションを省略 - lightContext: false, // default: false; true でworkspace bootstrap fileからHEARTBEAT.mdのみ保持 - isolatedSession: false, // default: false; true で各heartbeatを新しいsessionで実行（会話履歴なし） + includeSystemPromptSection: true, // デフォルト: true; false ではsystem promptからHeartbeatセクションを省略 + lightContext: false, // デフォルト: false; true ではworkspace bootstrapファイルからHEARTBEAT.mdのみを保持 + isolatedSession: false, // デフォルト: false; true では各heartbeatを新しいセッションで実行（会話履歴なし） session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow（デフォルト）| block + target: "none", // デフォルト: none | 選択肢: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, + timeoutSeconds: 45, }, }, }, } ``` -- `every`: duration文字列（ms/s/m/h）。デフォルト: `30m`（API-key認証）または `1h`（OAuth認証）。無効化するには `0m` を設定します。 -- `includeSystemPromptSection`: false の場合、system promptからHeartbeatセクションを省略し、bootstrap contextへの `HEARTBEAT.md` 注入もスキップします。デフォルト: `true`。 -- `suppressToolErrorWarnings`: true の場合、heartbeat実行中のtool error warning payloadを抑制します。 -- `directPolicy`: direct/DM配信ポリシー。`allow`（デフォルト）はdirect-target配信を許可します。`block` はdirect-target配信を抑制し、`reason=dm-blocked` を出力します。 -- `lightContext`: true の場合、heartbeat実行は軽量bootstrap contextを使用し、workspace bootstrap fileから `HEARTBEAT.md` のみを保持します。 -- `isolatedSession`: true の場合、各heartbeatは以前の会話履歴を持たない新しいsessionで実行されます。cronの `sessionTarget: "isolated"` と同じ分離パターンです。heartbeatごとのtokenコストを約100Kから約2-5K tokenへ削減します。 -- agentごと: `agents.list[].heartbeat` を設定します。いずれかのagentが `heartbeat` を定義すると、heartbeatを実行するのは **それらのagentのみ** になります。 -- Heartbeatは完全なagent turnを実行します — 短い間隔ほど多くのtokenを消費します。 +- `every`: 期間文字列（ms/s/m/h）。デフォルト: `30m`（API-key auth）または `1h`（OAuth auth）。無効にするには `0m` を設定します。 +- `includeSystemPromptSection`: false の場合、system promptからHeartbeatセクションを省略し、bootstrapコンテキストへの `HEARTBEAT.md` 注入をスキップします。デフォルト: `true`。 +- `suppressToolErrorWarnings`: true の場合、heartbeat実行中のtool error warningペイロードを抑制します。 +- `timeoutSeconds`: 中断されるまでにheartbeat agentターンに許可される最大時間（秒）。未設定の場合は `agents.defaults.timeoutSeconds` を使用します。 +- `directPolicy`: 直接/DM配信ポリシー。`allow`（デフォルト）は直接ターゲット配信を許可します。`block` は直接ターゲット配信を抑制し、`reason=dm-blocked` を出力します。 +- `lightContext`: true の場合、heartbeat実行は軽量bootstrapコンテキストを使用し、workspace bootstrapファイルから `HEARTBEAT.md` のみを保持します。 +- `isolatedSession`: true の場合、各heartbeat実行は以前の会話履歴がない新しいセッションで行われます。cronの `sessionTarget: "isolated"` と同じ分離パターンです。heartbeatあたりのtokenコストを約100Kから約2〜5K tokenに削減します。 +- agentごと: `agents.list[].heartbeat` を設定します。いずれかのagentが `heartbeat` を定義すると、heartbeatを実行するのは**それらのagentのみ**になります。 +- heartbeatは完全なagentターンを実行します。間隔を短くするほどtoken消費量は増えます。 ### `agents.defaults.compaction` @@ -1215,10 +1247,10 @@ OpenClawが組み立てたsystem prompt全体を固定文字列で置き換え timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // identifierPolicy=customで使用 + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // identifierPolicy=custom のときに使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] で再注入を無効化 - model: "openrouter/anthropic/claude-sonnet-4-6", // 任意のcompaction専用modelオーバーライド - notifyUser: true, // compaction開始時に短い通知を送る（デフォルト: false） + model: "openrouter/anthropic/claude-sonnet-4-6", // compaction専用の任意のモデル上書き + notifyUser: true, // compaction開始時に短い通知を送信（デフォルト: false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1231,19 +1263,19 @@ OpenClawが組み立てたsystem prompt全体を固定文字列で置き換え } ``` -- `mode`: `default` または `safeguard`（長い履歴向けのchunked summarization）。[Compaction](/ja-JP/concepts/compaction) を参照してください。 -- `provider`: 登録済みcompaction provider pluginのid。設定すると、組み込みLLM summarizationの代わりにそのproviderの `summarize()` が呼ばれます。失敗時は組み込みへフォールバックします。providerを設定すると `mode: "safeguard"` が強制されます。[Compaction](/ja-JP/concepts/compaction) を参照してください。 -- `timeoutSeconds`: OpenClawが中止するまでの単一compaction操作の最大秒数。デフォルト: `900`。 -- `identifierPolicy`: `strict`（デフォルト）、`off`、または `custom`。`strict` はcompaction summarization時に組み込みのopaque identifier保持ガイダンスを先頭に追加します。 -- `identifierInstructions`: `identifierPolicy=custom` のときに使う任意のカスタムidentifier保持文。 -- `postCompactionSections`: compaction後に再注入する任意のAGENTS.md H2/H3セクション名。デフォルトは `["Session Startup", "Red Lines"]`。無効化するには `[]` を設定します。未設定、またはそのデフォルト組が明示設定されている場合、古い `Every Session`/`Safety` 見出しもレガシーフォールバックとして受け付けます。 -- `model`: compaction summarization専用の任意の `provider/model-id` オーバーライド。メインsessionはあるmodelを維持しつつ、compaction summaryだけ別modelで実行したい場合に使います。未設定時はcompactionはsessionのprimary modelを使用します。 -- `notifyUser`: `true` の場合、compaction開始時にユーザーへ短い通知（例: 「Compacting context...」）を送信します。compactionを静かに保つため、デフォルトでは無効です。 -- `memoryFlush`: 自動compaction前に永続memoryを保存するためのサイレントagentic turn。workspaceがread-onlyの場合はスキップされます。 +- `mode`: `default` または `safeguard`（長い履歴向けのチャンク化要約）。[Compaction](/ja-JP/concepts/compaction) を参照してください。 +- `provider`: 登録済みcompaction provider pluginのid。設定されている場合、組み込みLLM要約の代わりにproviderの `summarize()` が呼び出されます。失敗時は組み込みにフォールバックします。providerを設定すると `mode: "safeguard"` が強制されます。[Compaction](/ja-JP/concepts/compaction) を参照してください。 +- `timeoutSeconds`: OpenClawが中断するまでに、単一のcompaction処理に許可される最大秒数。デフォルト: `900`。 +- `identifierPolicy`: `strict`（デフォルト）、`off`、または `custom`。`strict` は、compaction要約時に組み込みの不透明識別子保持ガイダンスを先頭に追加します。 +- `identifierInstructions`: `identifierPolicy=custom` のときに使用される、任意のカスタム識別子保持テキスト。 +- `postCompactionSections`: compaction後に再注入する任意のAGENTS.md H2/H3セクション名。デフォルトは `["Session Startup", "Red Lines"]` です。再注入を無効にするには `[]` を設定します。未設定の場合、または明示的にそのデフォルトの組み合わせに設定した場合、レガシーフォールバックとして古い `Every Session` / `Safety` 見出しも受け付けます。 +- `model`: compaction要約専用の任意の `provider/model-id` 上書き。メインセッションでは1つのモデルを維持しつつ、compaction要約は別のモデルで実行したい場合に使用します。未設定の場合、compactionはセッションのプライマリモデルを使用します。 +- `notifyUser`: `true` の場合、compaction開始時にユーザーへ短い通知（たとえば「Compacting context...」）を送信します。compactionを静かに保つため、デフォルトでは無効です。 +- `memoryFlush`: 自動compaction前に耐久メモリーを保存するためのサイレントagentターン。workspaceが読み取り専用の場合はスキップされます。 ### `agents.defaults.contextPruning` -LLMへ送信する前に、メモリ内contextから **古いtool result** を剪定します。ディスク上のsession historyは変更しません。 +LLMへ送信する前に、メモリー内コンテキストから**古いtool結果**を剪定します。ディスク上のセッション履歴は**変更しません**。 ```json5 { @@ -1251,7 +1283,7 @@ LLMへ送信する前に、メモリ内contextから **古いtool result** を defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), デフォルト単位: 分 + ttl: "1h", // 期間（ms/s/m/h）、デフォルト単位: 分 keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1265,21 +1297,21 @@ LLMへ送信する前に、メモリ内contextから **古いtool result** を } ``` - + -- `mode: "cache-ttl"` でpruning passが有効になります。 -- `ttl` は、最後のcache touch後に再びpruningを実行できるまでの頻度を制御します。 -- Pruningは、必要に応じてまず大きすぎるtool resultをsoft-trimし、その後より古いtool resultをhard-clearします。 +- `mode: "cache-ttl"` で剪定パスが有効になります。 +- `ttl` は、前回のキャッシュタッチ後に再び剪定を実行できる頻度を制御します。 +- 剪定では、まず大きすぎるtool結果をソフトトリムし、必要であればその後に古いtool結果をハードクリアします。 -**Soft-trim** は先頭と末尾を保持し、中央に `...` を挿入します。 +**ソフトトリム** は先頭 + 末尾を保持し、中間に `...` を挿入します。 -**Hard-clear** はtool result全体をplaceholderで置き換えます。 +**ハードクリア** はtool結果全体をプレースホルダーに置き換えます。 -注記: +注意: -- Image blockは切り詰め/クリアされません。 -- 比率はtoken数ではなく文字数ベース（概算）です。 -- `keepLastAssistants` 未満のassistant messageしか存在しない場合、pruningはスキップされます。 +- 画像ブロックはトリムもクリアもされません。 +- 比率は文字数ベース（概算）であり、正確なtoken数ではありません。 +- `keepLastAssistants` 未満のassistantメッセージしか存在しない場合、剪定はスキップされます。 @@ -1295,17 +1327,17 @@ LLMへ送信する前に、メモリ内contextから **古いtool result** を blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (minMs/maxMsを使用) + humanDelay: { mode: "natural" }, // off | natural | custom（minMs/maxMs を使用） }, }, } ``` -- Telegram以外のchannelでは、block replyを有効にするには明示的な `*.blockStreaming: true` が必要です。 -- Channelごとのオーバーライド: `channels..blockStreamingCoalesce`（およびアカウントごとの変種）。Signal/Slack/Discord/Google Chatのデフォルトは `minChars: 1500` です。 -- `humanDelay`: block reply間のランダムな待機。`natural` = 800–2500ms。agentごとのオーバーライド: `agents.list[].humanDelay`。 +- Telegram以外のchannelでは、block返信を有効にするには明示的な `*.blockStreaming: true` が必要です。 +- channelごとの上書き: `channels..blockStreamingCoalesce`（およびアカウントごとの派生設定）。Signal/Slack/Discord/Google Chatのデフォルトは `minChars: 1500` です。 +- `humanDelay`: block返信間のランダムな待機。`natural` = 800〜2500ms。agentごとの上書き: `agents.list[].humanDelay`。 -動作とchunkingの詳細は [Streaming](/ja-JP/concepts/streaming) を参照してください。 +動作とチャンク化の詳細は [Streaming](/ja-JP/concepts/streaming) を参照してください。 ### Typing indicators @@ -1320,8 +1352,8 @@ LLMへ送信する前に、メモリ内contextから **古いtool result** を } ``` -- デフォルト: direct chat/mentionでは `instant`、mentionされていないgroup chatでは `message`。 -- Sessionごとのオーバーライド: `session.typingMode`、`session.typingIntervalSeconds`。 +- デフォルト: ダイレクトチャット/メンションでは `instant`、メンションなしのグループチャットでは `message`。 +- セッションごとの上書き: `session.typingMode`、`session.typingIntervalSeconds`。 [Typing Indicators](/ja-JP/concepts/typing-indicators) を参照してください。 @@ -1424,52 +1456,52 @@ LLMへ送信する前に、メモリ内contextから **古いtool result** を } ``` - + **Backend:** -- `docker`: ローカルDocker runtime（デフォルト） -- `ssh`: 汎用SSHベースのremote runtime -- `openshell`: OpenShell runtime +- `docker`: ローカルDockerランタイム（デフォルト） +- `ssh`: 汎用SSHバックエンドのリモートランタイム +- `openshell`: OpenShellランタイム -`backend: "openshell"` を選択した場合、runtime固有設定は -`plugins.entries.openshell.config` へ移動します。 +`backend: "openshell"` を選択した場合、ランタイム固有設定は +`plugins.entries.openshell.config` に移動します。 **SSH backend設定:** -- `target`: `user@host[:port]` 形式のSSH target -- `command`: SSH client command（デフォルト: `ssh`） -- `workspaceRoot`: スコープごとのworkspaceに使用する絶対remote root -- `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSHへ渡される既存のローカルファイル -- `identityData` / `certificateData` / `knownHostsData`: OpenClawがruntime時に一時ファイルへ実体化するインライン内容またはSecretRef -- `strictHostKeyChecking` / `updateHostKeys`: OpenSSHのhost-key policyノブ +- `target`: `user@host[:port]` 形式のSSHターゲット +- `command`: SSHクライアントコマンド（デフォルト: `ssh`） +- `workspaceRoot`: スコープごとのworkspaceに使用する絶対リモートルート +- `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSHに渡される既存のローカルファイル +- `identityData` / `certificateData` / `knownHostsData`: OpenClawが実行時に一時ファイルへ実体化するインライン内容またはSecretRef +- `strictHostKeyChecking` / `updateHostKeys`: OpenSSHのhost-keyポリシー設定 **SSH認証の優先順位:** -- `identityData` が `identityFile` に優先 -- `certificateData` が `certificateFile` に優先 -- `knownHostsData` が `knownHostsFile` に優先 -- SecretRefベースの `*Data` 値は、sandbox session開始前にアクティブsecrets runtime snapshotから解決されます +- `identityData` は `identityFile` より優先されます +- `certificateData` は `certificateFile` より優先されます +- `knownHostsData` は `knownHostsFile` より優先されます +- SecretRefバックエンドの `*Data` 値は、sandboxセッション開始前にアクティブなsecretsランタイムスナップショットから解決されます **SSH backendの動作:** -- 作成または再作成後にremote workspaceを1回seedする -- その後はremote SSH workspaceを正本として維持する -- `exec`、file tool、media pathをSSH経由でルーティングする -- remote変更を自動でホストへ同期しない -- sandbox browser containerをサポートしない +- 作成または再作成後に一度だけリモートworkspaceをシードします +- その後はリモートSSH workspaceを正規として維持します +- `exec`、ファイルtools、およびメディアパスをSSH経由でルーティングします +- リモート変更をホストへ自動同期しません +- sandbox browserコンテナーはサポートしません **Workspace access:** - `none`: `~/.openclaw/sandboxes` 配下のスコープごとのsandbox workspace -- `ro`: sandbox workspaceは `/workspace`、agent workspaceは読み取り専用で `/agent` にmount -- `rw`: agent workspaceを読み書き可能で `/workspace` にmount +- `ro`: `/workspace` にsandbox workspace、`/agent` にagent workspaceを読み取り専用でマウント +- `rw`: agent workspaceを `/workspace` に読み書き可能でマウント **Scope:** -- `session`: sessionごとのcontainer + workspace -- `agent`: agentごとに1つのcontainer + workspace（デフォルト） -- `shared`: 共有containerおよびworkspace（session間分離なし） +- `session`: セッションごとのコンテナー + workspace +- `agent`: agentごとに1つのコンテナー + workspace（デフォルト） +- `shared`: 共有コンテナーとworkspace（セッション間分離なし） **OpenShell plugin設定:** @@ -1484,10 +1516,10 @@ LLMへ送信する前に、メモリ内contextから **古いtool result** を from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // 任意 + gatewayEndpoint: "https://lab.example", // 任意 + policy: "strict", // 任意のOpenShell policy id + providers: ["openai"], // 任意 autoProviders: true, timeoutSeconds: 120, }, @@ -1497,32 +1529,32 @@ LLMへ送信する前に、メモリ内contextから **古いtool result** を } ``` -**OpenShell mode:** +**OpenShellモード:** -- `mirror`: exec前にlocalからremoteへseedし、exec後に同期し戻す。local workspaceが正本のままになります -- `remote`: sandbox作成時に1度だけremoteへseedし、その後はremote workspaceを正本として維持します +- `mirror`: 実行前にローカルからリモートへシードし、実行後に同期し戻します。ローカルworkspaceが正規のままです +- `remote`: sandbox作成時に一度だけリモートをシードし、その後はリモートworkspaceを正規として維持します -`remote` modeでは、OpenClaw外で行われたホストローカル編集は、seedステップ後にsandboxへ自動同期されません。 -転送はOpenShell sandboxへのSSHですが、sandboxのライフサイクルと任意のmirror syncはpluginが所有します。 +`remote` モードでは、OpenClawの外で行われたホストローカルの編集は、シード後にsandboxへ自動同期されません。 +転送はOpenShell sandboxへのSSHですが、sandboxライフサイクルと任意のmirror同期はpluginが管理します。 -**`setupCommand`** はcontainer作成後に1回だけ実行されます（`sh -lc` 経由）。network egress、書き込み可能root、root userが必要です。 +**`setupCommand`** はコンテナー作成後に一度だけ実行されます（`sh -lc` 経由）。ネットワークegress、書き込み可能なroot、rootユーザーが必要です。 -**Containerのデフォルトは `network: "none"`** です — agentに送信アクセスが必要なら `"bridge"`（またはカスタムbridge network）に設定してください。 -`"host"` はブロックされます。`"container:"` もデフォルトでブロックされますが、 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` を明示設定した場合のみ許可されます（緊急避難用）。 +**コンテナーのデフォルトは `network: "none"`** です。agentに外向きアクセスが必要な場合は `"bridge"`（またはカスタムbridge network）に設定してください。 +`"host"` はブロックされます。`"container:"` もデフォルトではブロックされますが、 +明示的に `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` を設定した場合のみ許可されます（緊急用）。 -**受信attachment** はアクティブworkspace内の `media/inbound/*` にステージングされます。 +**受信添付ファイル** は、アクティブworkspace内の `media/inbound/*` にステージされます。 -**`docker.binds`** は追加のhost directoryをmountします。グローバルとagentごとのbindはマージされます。 +**`docker.binds`** は追加のホストディレクトリをマウントします。グローバルとagentごとのbindはマージされます。 -**Sandboxed browser**（`sandbox.browser.enabled`）: container内のChromium + CDP。noVNC URLがsystem promptに注入されます。`openclaw.json` で `browser.enabled` を必要としません。 -noVNC observer accessはデフォルトでVNC認証を使用し、OpenClawは共有URLにpasswordを露出する代わりに短命token URLを発行します。 +**Sandbox化されたbrowser**（`sandbox.browser.enabled`）: コンテナー内でChromium + CDPを実行します。noVNC URLはsystem promptに注入されます。`openclaw.json` で `browser.enabled` は不要です。 +noVNCのobserverアクセスはデフォルトでVNC認証を使用し、OpenClawは共有URLにパスワードを露出する代わりに短命のtoken URLを出力します。 -- `allowHostControl: false`（デフォルト）は、sandboxed sessionがhost browserを対象にすることをブロックします。 -- `network` のデフォルトは `openclaw-sandbox-browser`（専用bridge network）です。グローバルbridge接続が明示的に必要な場合にのみ `bridge` に設定してください。 -- `cdpSourceRange` は、container境界でCDP ingressをCIDR範囲（例: `172.21.0.1/32`）へ任意に制限します。 -- `sandbox.browser.binds` は追加のhost directoryをsandbox browser containerのみにmountします。設定された場合（`[]` を含む）、browser containerでは `docker.binds` を置き換えます。 -- 起動デフォルトは `scripts/sandbox-browser-entrypoint.sh` で定義され、container host向けに調整されています: +- `allowHostControl: false`（デフォルト）は、sandbox化されたセッションがホストbrowserをターゲットにすることをブロックします。 +- `network` のデフォルトは `openclaw-sandbox-browser`（専用bridge network）です。グローバルbridge接続を明示的に望む場合にのみ `bridge` に設定してください。 +- `cdpSourceRange` は、CDPへの流入をコンテナー境界でCIDR範囲に制限できます（例: `172.21.0.1/32`）。 +- `sandbox.browser.binds` は、追加のホストディレクトリをsandbox browserコンテナーにのみマウントします。設定されている場合（`[]` を含む）、browserコンテナーでは `docker.binds` の代わりにこれが使われます。 +- 起動時のデフォルトは `scripts/sandbox-browser-entrypoint.sh` で定義されており、コンテナーホスト向けに調整されています: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1541,29 +1573,28 @@ noVNC observer accessはデフォルトでVNC認証を使用し、OpenClawは共 - `--metrics-recording-only` - `--disable-extensions`（デフォルトで有効） - `--disable-3d-apis`、`--disable-software-rasterizer`、`--disable-gpu` は - デフォルトで有効であり、WebGL/3D利用に必要な場合は - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` で無効化できます。 - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` は、workflowがextensionに依存する場合に - extensionを再有効化します。 + デフォルトで有効であり、WebGL/3D利用で必要な場合は + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` で無効にできます。 + - ワークフローが拡張機能に依存している場合は + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` で拡張機能を再有効化します。 - `--renderer-process-limit=2` は `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` で変更できます。Chromiumの - デフォルトprocess上限を使うには `0` を設定してください。 - - 加えて、`noSandbox` が有効な場合は `--no-sandbox` と `--disable-setuid-sandbox`。 - - デフォルトはcontainer imageのベースラインです。containerデフォルトを変更するには、 - カスタムentrypointを持つ独自browser imageを使用してください。 + デフォルトのプロセス上限を使うには `0` を設定してください。 + - さらに、`noSandbox` が有効な場合は `--no-sandbox` と `--disable-setuid-sandbox` も追加されます。 + - デフォルトはコンテナーimageのベースラインです。コンテナーのデフォルトを変更するには、カスタムentrypointを持つカスタムbrowser imageを使用してください。 -browser sandboxingと `sandbox.docker.binds` はDocker専用です。 +browser sandboxing と `sandbox.docker.binds` はDocker専用です。 -imageのビルド: +imageをビルド: ```bash scripts/sandbox-setup.sh # メインsandbox image scripts/sandbox-browser-setup.sh # 任意のbrowser image ``` -### `agents.list`（agentごとのオーバーライド） +### `agents.list`（agentごとの上書き） ```json5 { @@ -1576,11 +1607,12 @@ scripts/sandbox-browser-setup.sh # 任意のbrowser image workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // または { primary, fallbacks } - thinkingDefault: "high", // agentごとのthinking levelオーバーライド - reasoningDefault: "on", // agentごとのreasoning visibilityオーバーライド - fastModeDefault: false, // agentごとのfast modeオーバーライド - params: { cacheRetention: "none" }, // 一致するdefaults.models paramsをキーごとに上書き - skills: ["docs-search"], // 設定時はagents.defaults.skillsを置き換え + thinkingDefault: "high", // agentごとのthinkingレベル上書き + reasoningDefault: "on", // agentごとのreasoning可視性上書き + fastModeDefault: false, // agentごとのfast mode上書き + embeddedHarness: { runtime: "auto", fallback: "pi" }, + params: { cacheRetention: "none" }, // 一致する defaults.models params をキーごとに上書き + skills: ["docs-search"], // 設定されている場合は agents.defaults.skills を置き換える identity: { name: "Samantha", theme: "helpful sloth", @@ -1612,23 +1644,24 @@ scripts/sandbox-browser-setup.sh # 任意のbrowser image ``` - `id`: 安定したagent id（必須）。 -- `default`: 複数設定されている場合は最初が勝ちます（警告を記録）。どれも設定されていない場合、最初のlist entryがデフォルトです。 -- `model`: 文字列形式は `primary` のみを上書きし、object形式 `{ primary, fallbacks }` は両方を上書きします（`[]` でグローバルfallbackを無効化）。`primary` だけを上書きするcron jobは、`fallbacks: []` を設定しない限りデフォルトfallbackを継承します。 -- `params`: 選択されたmodel entryに対して `agents.defaults.models` の上にマージされるagentごとのstream params。`cacheRetention`、`temperature`、`maxTokens` などagent固有の上書きに使用し、model catalog全体の複製を避けます。 -- `skills`: 任意のagentごとのskill allowlist。省略時、そのagentは設定されていれば `agents.defaults.skills` を継承します。明示listはデフォルトとマージせず置き換え、`[]` はskillなしを意味します。 -- `thinkingDefault`: 任意のagentごとのデフォルトthinking level（`off | minimal | low | medium | high | xhigh | adaptive`）。message単位またはsession単位の上書きが未設定のとき、このagentに対して `agents.defaults.thinkingDefault` を上書きします。 -- `reasoningDefault`: 任意のagentごとのデフォルトreasoning visibility（`on | off | stream`）。message単位またはsession単位のreasoningオーバーライドが未設定のときに適用されます。 -- `fastModeDefault`: 任意のagentごとのfast modeデフォルト（`true | false`）。message単位またはsession単位のfast-modeオーバーライドが未設定のときに適用されます。 -- `runtime`: 任意のagentごとのruntime descriptor。agentがデフォルトでACP harness sessionを使うべき場合は、`type: "acp"` と `runtime.acp` のデフォルト（`agent`、`backend`、`mode`、`cwd`）を使用してください。 -- `identity.avatar`: workspace相対path、`http(s)` URL、または `data:` URI。 -- `identity` はデフォルトを導出します: `emoji` から `ackReaction`、`name`/`emoji` から `mentionPatterns`。 -- `subagents.allowAgents`: `sessions_spawn` 用agent id allowlist（`["*"]` = 任意。デフォルト: 同じagentのみ）。 -- Sandbox継承ガード: 要求元sessionがsandbox化されている場合、`sessions_spawn` はsandbox化されないターゲットを拒否します。 -- `subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なprofile選択を強制。デフォルト: false）。 +- `default`: 複数設定されている場合は最初のものが優先されます（警告が記録されます）。どれも設定されていない場合は、最初のリスト項目がデフォルトです。 +- `model`: 文字列形式は `primary` のみを上書きします。オブジェクト形式 `{ primary, fallbacks }` は両方を上書きします（`[]` はグローバルfallbackを無効化）。`primary` だけを上書きするcron jobは、`fallbacks: []` を設定しない限りデフォルトfallbackを継承します。 +- `params`: 選択された `agents.defaults.models` 内のモデルエントリの上にマージされるagentごとのstream paramsです。モデルカタログ全体を複製せずに、`cacheRetention`、`temperature`、`maxTokens` などのagent固有上書きに使います。 +- `skills`: 任意のagentごとのskill許可リスト。省略時、設定されていればagentは `agents.defaults.skills` を継承します。明示的なリストはデフォルトをマージせず置き換え、`[]` はskillなしを意味します。 +- `thinkingDefault`: 任意のagentごとのデフォルトthinkingレベル（`off | minimal | low | medium | high | xhigh | adaptive`）。メッセージごとまたはセッションごとの上書きがない場合、このagentでは `agents.defaults.thinkingDefault` を上書きします。 +- `reasoningDefault`: 任意のagentごとのデフォルトreasoning可視性（`on | off | stream`）。メッセージごとまたはセッションごとのreasoning上書きがない場合に適用されます。 +- `fastModeDefault`: 任意のagentごとのfast modeデフォルト（`true | false`）。メッセージごとまたはセッションごとのfast-mode上書きがない場合に適用されます。 +- `embeddedHarness`: 任意のagentごとの低レベルharnessポリシー上書き。1つのagentだけをCodex専用にし、他のagentはデフォルトのPIフォールバックを維持するには `{ runtime: "codex", fallback: "none" }` を使用します。 +- `runtime`: 任意のagentごとのruntime記述子。agentがデフォルトでACP harnessセッションを使うべき場合は、`type: "acp"` と `runtime.acp` のデフォルト（`agent`、`backend`、`mode`、`cwd`）を使用します。 +- `identity.avatar`: workspace相対パス、`http(s)` URL、または `data:` URI。 +- `identity` はデフォルトを導出します: `emoji` から `ackReaction`、`name` / `emoji` から `mentionPatterns`。 +- `subagents.allowAgents`: `sessions_spawn` 用のagent id許可リスト（`["*"]` = 任意、デフォルト: 同じagentのみ）。 +- Sandbox継承ガード: 要求元セッションがsandbox化されている場合、`sessions_spawn` は非sandboxで実行されるターゲットを拒否します。 +- `subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制。デフォルト: false）。 --- -## マルチagent routing +## 複数agentルーティング 1つのGateway内で複数の分離されたagentを実行します。[Multi-Agent](/ja-JP/concepts/multi-agent) を参照してください。 @@ -1647,31 +1680,31 @@ scripts/sandbox-browser-setup.sh # 任意のbrowser image } ``` -### Binding matchフィールド +### Binding一致フィールド -- `type`（任意）: 通常のroutingには `route`（type未指定もroute扱い）、永続ACP会話bindingには `acp` +- `type`（任意）: 通常のルーティングは `route`（type未指定もroute）、永続ACP会話bindingは `acp` - `match.channel`（必須） - `match.accountId`（任意。`*` = 任意のアカウント、省略 = デフォルトアカウント） - `match.peer`（任意。`{ kind: direct|group|channel, id }`） - `match.guildId` / `match.teamId`（任意。channel固有） - `acp`（任意。`type: "acp"` のみ）: `{ mode, label, cwd, backend }` -**決定的なmatch順序:** +**決定的な一致順序:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（peer/guild/teamなしの完全一致） +4. `match.accountId`（完全一致、peer/guild/teamなし） 5. `match.accountId: "*"`（channel全体） 6. デフォルトagent -各tier内では、最初に一致した `bindings` エントリーが勝ちます。 +各階層内では、最初に一致した `bindings` エントリが優先されます。 -`type: "acp"` エントリーでは、OpenClawは正確な会話identity（`match.channel` + account + `match.peer.id`）で解決し、上記のroute binding tier順序は使用しません。 +`type: "acp"` のエントリでは、OpenClawは正確な会話ID（`match.channel` + account + `match.peer.id`）で解決し、上記のroute binding階層順は使用しません。 -### Agentごとのaccess profile +### agentごとのアクセスプロファイル - + ```json5 { @@ -1790,22 +1823,22 @@ scripts/sandbox-browser-setup.sh # 任意のbrowser image }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // このtoken数を超える親thread forkはスキップ（0で無効） + parentForkMaxTokens: 100000, // このtoken数を超える親スレッドforkはスキップ（0 で無効） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration または false - maxDiskBytes: "500mb", // 任意のハード予算 - highWaterBytes: "400mb", // 任意のcleanup target + resetArchiveRetention: "30d", // 期間または false + maxDiskBytes: "500mb", // 任意のハード上限 + highWaterBytes: "400mb", // 任意のクリーンアップ目標 }, threadBindings: { enabled: true, - idleHours: 24, // 非アクティブ時の自動unfocusデフォルト（時間単位、`0` で無効） - maxAgeHours: 0, // ハード最大期間のデフォルト（時間単位、`0` で無効） + idleHours: 24, // 非アクティブ時の自動unfocusまでのデフォルト時間（時間単位、`0` で無効） + maxAgeHours: 0, // ハード最大期間のデフォルト時間（時間単位、`0` で無効） }, - mainKey: "main", // レガシー（runtimeは常に "main" を使用） + mainKey: "main", // legacy（ランタイムは常に "main" を使用） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1815,37 +1848,37 @@ scripts/sandbox-browser-setup.sh # 任意のbrowser image } ``` - + -- **`scope`**: group-chat context向けの基本session grouping戦略。 - - `per-sender`（デフォルト）: channel context内で各senderごとに分離sessionを持ちます。 - - `global`: channel context内の全参加者が1つのsessionを共有します（共有contextが意図されている場合にのみ使用してください）。 -- **`dmScope`**: DMのグルーピング方法。 - - `main`: すべてのDMがmain sessionを共有します。 - - `per-peer`: channelをまたいでsender idごとに分離します。 - - `per-channel-peer`: channel + senderごとに分離します（複数ユーザーinboxに推奨）。 - - `per-account-channel-peer`: account + channel + senderごとに分離します（マルチアカウントに推奨）。 -- **`identityLinks`**: channel間session共有のため、provider prefix付きpeerへ正規idをマップします。 -- **`reset`**: 主要resetポリシー。`daily` はローカル時刻の `atHour` にresetし、`idle` は `idleMinutes` 後にresetします。両方が設定されている場合、先に期限切れになる方が優先されます。 -- **`resetByType`**: typeごとのオーバーライド（`direct`、`group`、`thread`）。レガシー `dm` は `direct` のaliasとして受け付けます。 -- **`parentForkMaxTokens`**: forked thread session作成時に許可する親session `totalTokens` の最大値（デフォルト `100000`）。 - - 親の `totalTokens` がこの値を超える場合、OpenClawは親transcript historyを継承せず、新しいthread sessionを開始します。 - - このガードを無効化し、常に親forkを許可するには `0` を設定します。 -- **`mainKey`**: レガシーフィールド。runtimeはmain direct-chat bucketに常に `"main"` を使用します。 -- **`agentToAgent.maxPingPongTurns`**: agent間やり取り中の応答往復回数の最大値（整数、範囲: `0`–`5`）。`0` はping-pong連鎖を無効化します。 -- **`sendPolicy`**: `channel`、`chatType`（`direct|group|channel`。レガシー `dm` aliasあり）、`keyPrefix`、または `rawKeyPrefix` でmatchします。最初のdenyが勝ちます。 -- **`maintenance`**: session-storeのcleanup + retention制御。 - - `mode`: `warn` は警告のみ、`enforce` はcleanupを適用します。 - - `pruneAfter`: 古いentryの期限（デフォルト `30d`）。 - - `maxEntries`: `sessions.json` 内の最大entry数（デフォルト `500`）。 - - `rotateBytes`: `sessions.json` がこのサイズを超えたときにローテーションします（デフォルト `10mb`）。 - - `resetArchiveRetention`: `*.reset.` transcript archiveの保持期間。デフォルトは `pruneAfter`。無効にするには `false` を設定します。 - - `maxDiskBytes`: 任意のsessions directoryディスク予算。`warn` modeでは警告を記録し、`enforce` modeでは最も古いartifact/sessionから削除します。 - - `highWaterBytes`: 予算cleanup後の任意target。デフォルトは `maxDiskBytes` の `80%`。 -- **`threadBindings`**: thread-bound session機能のグローバルデフォルト。 - - `enabled`: マスターデフォルトスイッチ（provider側で上書き可能。Discordは `channels.discord.threadBindings.enabled` を使用） - - `idleHours`: 非アクティブ時の自動unfocusデフォルト（時間単位。`0` で無効。provider側で上書き可能） - - `maxAgeHours`: ハード最大期間デフォルト（時間単位。`0` で無効。provider側で上書き可能） +- **`scope`**: グループチャット文脈向けの基本セッショングループ化戦略。 + - `per-sender`（デフォルト）: channel文脈内で送信者ごとに分離されたセッションを使用します。 + - `global`: channel文脈内の全参加者が単一のセッションを共有します（共有コンテキストを意図する場合にのみ使用してください）。 +- **`dmScope`**: DMのグループ化方法。 + - `main`: すべてのDMがメインセッションを共有します。 + - `per-peer`: channelをまたいで送信者IDごとに分離します。 + - `per-channel-peer`: channel + 送信者ごとに分離します（複数ユーザーの受信箱に推奨）。 + - `per-account-channel-peer`: アカウント + channel + 送信者ごとに分離します（複数アカウントに推奨）。 +- **`identityLinks`**: channelをまたいだセッション共有のために、正規IDをprovider接頭辞付きpeerへマッピングします。 +- **`reset`**: 主なリセットポリシー。`daily` はローカル時刻の `atHour` にリセットし、`idle` は `idleMinutes` 後にリセットします。両方が設定されている場合、先に期限切れになる方が優先されます。 +- **`resetByType`**: タイプごとの上書き（`direct`、`group`、`thread`）。レガシーな `dm` も `direct` の別名として受け付けます。 +- **`parentForkMaxTokens`**: forkされたスレッドセッションを作成するときに許可される親セッションの `totalTokens` の最大値（デフォルト `100000`）。 + - 親の `totalTokens` がこの値を超えている場合、OpenClawは親のトランスクリプト履歴を継承する代わりに、新しいスレッドセッションを開始します。 + - このガードを無効にして常に親forkを許可するには `0` を設定します。 +- **`mainKey`**: レガシーフィールドです。ランタイムはメインのダイレクトチャットバケットに常に `"main"` を使用します。 +- **`agentToAgent.maxPingPongTurns`**: agent間のやり取り中に、agent同士で返信し合う最大ターン数（整数、範囲: `0`–`5`）。`0` はping-pong連鎖を無効にします。 +- **`sendPolicy`**: `channel`、`chatType`（`direct|group|channel`、レガシーな `dm` 別名あり）、`keyPrefix`、または `rawKeyPrefix` で一致させます。最初のdenyが優先されます。 +- **`maintenance`**: セッションストアのクリーンアップ + 保持制御。 + - `mode`: `warn` は警告のみを出し、`enforce` はクリーンアップを適用します。 + - `pruneAfter`: 古いエントリに対する期限（デフォルト `30d`）。 + - `maxEntries`: `sessions.json` 内の最大エントリ数（デフォルト `500`）。 + - `rotateBytes`: `sessions.json` がこのサイズを超えたらローテーションします（デフォルト `10mb`）。 + - `resetArchiveRetention`: `*.reset.` トランスクリプトアーカイブの保持期間。デフォルトは `pruneAfter`。無効にするには `false` を設定します。 + - `maxDiskBytes`: 任意のsessionsディレクトリディスク上限。`warn` モードでは警告を記録し、`enforce` モードでは最も古いartifact/sessionから削除します。 + - `highWaterBytes`: 上限制御後の任意の目標値。デフォルトは `maxDiskBytes` の `80%` です。 +- **`threadBindings`**: スレッドバインドセッション機能のグローバルデフォルト。 + - `enabled`: マスターのデフォルトスイッチ（providerは上書き可能。Discordは `channels.discord.threadBindings.enabled` を使用） + - `idleHours`: 非アクティブ時の自動unfocusまでのデフォルト時間（時間単位、`0` で無効。providerは上書き可能） + - `maxAgeHours`: ハード最大期間のデフォルト時間（時間単位、`0` で無効。providerは上書き可能） @@ -1881,38 +1914,38 @@ scripts/sandbox-browser-setup.sh # 任意のbrowser image } ``` -### Response prefix +### 応答プレフィックス -channel/アカウントごとのオーバーライド: `channels..responsePrefix`、`channels..accounts..responsePrefix`。 +channel/アカウントごとの上書き: `channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解決順（最も具体的なものが勝つ）: account → channel → global。`""` は無効化し、cascadeを止めます。`"auto"` は `[{identity.name}]` を導出します。 +解決順（最も具体的なものが優先）: アカウント → channel → グローバル。`""` は無効化し、カスケードも停止します。`"auto"` は `[{identity.name}]` を導出します。 -**Template変数:** +**テンプレート変数:** -| Variable | 説明 | 例 | -| ----------------- | --------------------- | --------------------------- | -| `{model}` | 短いmodel名 | `claude-opus-4-6` | -| `{modelFull}` | 完全なmodel識別子 | `anthropic/claude-opus-4-6` | -| `{provider}` | Provider名 | `anthropic` | -| `{thinkingLevel}` | 現在のthinking level | `high`, `low`, `off` | -| `{identity.name}` | Agent identity名 | (`"auto"` と同じ) | +| Variable | 説明 | 例 | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | 短いモデル名 | `claude-opus-4-6` | +| `{modelFull}` | 完全なモデル識別子 | `anthropic/claude-opus-4-6` | +| `{provider}` | provider名 | `anthropic` | +| `{thinkingLevel}` | 現在のthinkingレベル | `high`, `low`, `off` | +| `{identity.name}` | Agent identity名 | （`"auto"` と同じ） | -変数は大文字小文字を区別しません。`{think}` は `{thinkingLevel}` のaliasです。 +変数は大文字小文字を区別しません。`{think}` は `{thinkingLevel}` の別名です。 -### Ack reaction +### Ackリアクション -- デフォルトはアクティブagentの `identity.emoji`、なければ `"👀"`。無効化するには `""` を設定します。 -- Channelごとのオーバーライド: `channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解決順: account → channel → `messages.ackReaction` → identity fallback。 -- Scope: `group-mentions`（デフォルト）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`: Slack、Discord、Telegramでreply後にackを削除します。 -- `messages.statusReactions.enabled`: Slack、Discord、Telegramでライフサイクルstatus reactionを有効にします。 - SlackとDiscordでは、未設定の場合、ack reactionが有効ならstatus reactionも有効のままです。 - Telegramでは、ライフサイクルstatus reactionを有効にするには明示的に `true` を設定してください。 +- デフォルトはアクティブagentの `identity.emoji`、なければ `"👀"` です。無効にするには `""` を設定します。 +- channelごとの上書き: `channels..ackReaction`、`channels..accounts..ackReaction`。 +- 解決順: アカウント → channel → `messages.ackReaction` → identityフォールバック。 +- スコープ: `group-mentions`（デフォルト）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`: Slack、Discord、Telegramで返信後にackを削除します。 +- `messages.statusReactions.enabled`: Slack、Discord、Telegramでライフサイクルstatusリアクションを有効にします。 + SlackとDiscordでは、未設定の場合、ackリアクションが有効なときはstatusリアクションも有効のままです。 + Telegramでは、ライフサイクルstatusリアクションを有効にするには、これを明示的に `true` に設定してください。 -### Inbound debounce +### 受信debounce -同じsenderからの高速なtext-only messageを1つのagent turnにまとめます。media/attachmentは即時flushされます。control commandはdebouncingをバイパスします。 +同じ送信者からの短時間のテキストのみのメッセージを1回のagentターンにまとめます。メディア/添付ファイルは即座にフラッシュされます。制御コマンドはdebouncingをバイパスします。 ### TTS（text-to-speech） @@ -1955,18 +1988,18 @@ channel/アカウントごとのオーバーライド: `channels..respo } ``` -- `auto` はデフォルトの自動TTS modeを制御します: `off`、`always`、`inbound`、または `tagged`。`/tts on|off` はローカル設定を上書きでき、`/tts status` は有効状態を表示します。 -- `summaryModel` は自動summary用に `agents.defaults.model.primary` を上書きします。 -- `modelOverrides` はデフォルトで有効です。`modelOverrides.allowProvider` はデフォルトで `false`（opt-in）です。 -- API keyのフォールバックは `ELEVENLABS_API_KEY`/`XI_API_KEY` と `OPENAI_API_KEY` です。 -- `openai.baseUrl` はOpenAI TTS endpointを上書きします。解決順はconfig、次に `OPENAI_TTS_BASE_URL`、最後に `https://api.openai.com/v1` です。 -- `openai.baseUrl` がOpenAI以外のendpointを指す場合、OpenClawはそれをOpenAI互換TTS serverとして扱い、model/voice validationを緩和します。 +- `auto` はデフォルトの自動TTSモードを制御します: `off`、`always`、`inbound`、または `tagged`。`/tts on|off` でローカル設定を上書きでき、`/tts status` で有効状態を確認できます。 +- `summaryModel` は、自動要約に対して `agents.defaults.model.primary` を上書きします。 +- `modelOverrides` はデフォルトで有効です。`modelOverrides.allowProvider` のデフォルトは `false`（オプトイン）です。 +- APIキーは `ELEVENLABS_API_KEY`/`XI_API_KEY` および `OPENAI_API_KEY` にフォールバックします。 +- `openai.baseUrl` はOpenAI TTSエンドポイントを上書きします。解決順は config、次に `OPENAI_TTS_BASE_URL`、その後 `https://api.openai.com/v1` です。 +- `openai.baseUrl` がOpenAI以外のエンドポイントを指している場合、OpenClawはそれをOpenAI互換TTSサーバーとして扱い、model/voice検証を緩和します。 --- ## Talk -Talk mode（macOS/iOS/Android）のデフォルト値です。 +Talk mode（macOS/iOS/Android）のデフォルトです。 ```json5 { @@ -1994,47 +2027,47 @@ Talk mode（macOS/iOS/Android）のデフォルト値です。 - レガシーなフラットTalkキー（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）は互換性専用であり、自動的に `talk.providers.` へ移行されます。 - Voice IDは `ELEVENLABS_VOICE_ID` または `SAG_VOICE_ID` にフォールバックします。 - `providers.*.apiKey` は平文文字列またはSecretRefオブジェクトを受け付けます。 -- `ELEVENLABS_API_KEY` フォールバックは、Talk API keyが設定されていない場合にのみ適用されます。 -- `providers.*.voiceAliases` により、Talk directiveでフレンドリー名を使用できます。 -- `silenceTimeoutMs` は、Talk modeがユーザーの無音後どれだけ待ってからtranscriptを送信するかを制御します。未設定時はプラットフォーム既定の待機時間が維持されます（`macOSとAndroidでは700 ms、iOSでは900 ms`）。 +- `ELEVENLABS_API_KEY` のフォールバックは、Talk APIキーが設定されていない場合にのみ適用されます。 +- `providers.*.voiceAliases` により、Talkディレクティブでわかりやすい名前を使用できます。 +- `silenceTimeoutMs` は、Talk modeがユーザーの無音後どれだけ待ってからトランスクリプトを送信するかを制御します。未設定の場合はプラットフォームのデフォルト待機時間（`macOSとAndroidでは700 ms、iOSでは900 ms`）を使用します。 --- ## Tools -### Tool profile +### Toolプロファイル -`tools.profile` は `tools.allow`/`tools.deny` より前に基本allowlistを設定します: +`tools.profile` は、`tools.allow` / `tools.deny` より前にベース許可リストを設定します。 -ローカルonboardingでは、未設定の新しいローカルconfigに対してデフォルトで `tools.profile: "coding"` を設定します（既存の明示profileは保持されます）。 +ローカルのオンボーディングでは、未設定の新しいローカルconfigに対してデフォルトで `tools.profile: "coding"` を設定します（既存の明示的なプロファイルは保持されます）。 -| Profile | 含まれるもの | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | `session_status` のみ | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | 制限なし（未設定と同じ） | +| Profile | 含まれるもの | +| ----------- | -------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | `session_status` のみ | +| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 制限なし（未設定と同じ） | -### Tool group +### Toolグループ | Group | Tools | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution`（`bash` は `exec` のaliasとして受け付けられます） | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | すべての組み込みtool（provider pluginを除く） | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` は `exec` の別名として受け付けられます） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | すべての組み込みtools（provider pluginは除く） | ### `tools.allow` / `tools.deny` -グローバルtool allow/deny policy（denyが優先）。大文字小文字を区別せず、`*` wildcardをサポートします。Docker sandboxがオフでも適用されます。 +グローバルなtool許可/拒否ポリシーです（denyが優先）。大文字小文字を区別せず、`*` ワイルドカードをサポートします。Docker sandboxが無効でも適用されます。 ```json5 { @@ -2044,7 +2077,7 @@ Talk mode（macOS/iOS/Android）のデフォルト値です。 ### `tools.byProvider` -特定のproviderまたはmodelに対してtoolをさらに制限します。順序: base profile → provider profile → allow/deny。 +特定のproviderまたはmodel向けにtoolsをさらに制限します。順序: ベースprofile → provider profile → allow/deny。 ```json5 { @@ -2076,9 +2109,9 @@ sandbox外のelevated execアクセスを制御します: } ``` -- agentごとのオーバーライド（`agents.list[].tools.elevated`）はさらに制限することしかできません。 -- `/elevated on|off|ask|full` は状態をsessionごとに保存します。インラインdirectiveは単一messageに適用されます。 -- Elevated `exec` はsandboxをバイパスし、設定されたescape path（デフォルトは `gateway`、exec targetが `node` の場合は `node`）を使います。 +- agentごとの上書き（`agents.list[].tools.elevated`）では、さらに制限を加えることしかできません。 +- `/elevated on|off|ask|full` は状態をセッションごとに保存します。インラインディレクティブは単一メッセージにのみ適用されます。 +- Elevated `exec` はsandbox化をバイパスし、設定済みのescape path（デフォルトでは `gateway`、execターゲットが `node` の場合は `node`）を使用します。 ### `tools.exec` @@ -2102,8 +2135,8 @@ sandbox外のelevated execアクセスを制御します: ### `tools.loopDetection` -tool-loop安全性チェックは **デフォルトで無効** です。有効にするには `enabled: true` を設定します。 -設定はグローバルの `tools.loopDetection` で定義でき、agentごとに `agents.list[].tools.loopDetection` で上書きできます。 +toolループの安全チェックはデフォルトでは**無効**です。検出を有効にするには `enabled: true` を設定します。 +設定はグローバルに `tools.loopDetection` で定義でき、agentごとに `agents.list[].tools.loopDetection` で上書きできます。 ```json5 { @@ -2124,14 +2157,14 @@ tool-loop安全性チェックは **デフォルトで無効** です。有効 } ``` -- `historySize`: loop分析用に保持する最大tool-call history数。 -- `warningThreshold`: 警告用の繰り返し無進捗pattern閾値。 -- `criticalThreshold`: 重大なloopをブロックするためのより高い繰り返し閾値。 -- `globalCircuitBreakerThreshold`: 任意の無進捗実行に対するハード停止閾値。 -- `detectors.genericRepeat`: 同じtool/同じargs呼び出しの繰り返しに警告します。 -- `detectors.knownPollNoProgress`: 既知のpoll tool（`process.poll`、`command_status` など）に対する無進捗に警告/ブロックします。 -- `detectors.pingPong`: 交互に発生する無進捗ペアpatternに警告/ブロックします。 -- `warningThreshold >= criticalThreshold` または `criticalThreshold >= globalCircuitBreakerThreshold` の場合、validationは失敗します。 +- `historySize`: ループ分析のために保持する最大tool call履歴数。 +- `warningThreshold`: 警告を出す、進捗のない繰り返しパターンのしきい値。 +- `criticalThreshold`: 重大なループをブロックするための、より高い繰り返ししきい値。 +- `globalCircuitBreakerThreshold`: あらゆる進捗のない実行に対するハード停止しきい値。 +- `detectors.genericRepeat`: 同じtool/同じ引数の繰り返し呼び出しで警告します。 +- `detectors.knownPollNoProgress`: 既知のpoll tool（`process.poll`、`command_status` など）で進捗がない場合に警告/ブロックします。 +- `detectors.pingPong`: 進捗のない交互ペアパターンで警告/ブロックします。 +- `warningThreshold >= criticalThreshold` または `criticalThreshold >= globalCircuitBreakerThreshold` の場合、検証は失敗します。 ### `tools.web` @@ -2141,14 +2174,14 @@ tool-loop安全性チェックは **デフォルトで無効** です。有効 web: { search: { enabled: true, - apiKey: "brave_api_key", // または BRAVE_API_KEY env + apiKey: "brave_api_key", // または BRAVE_API_KEY 環境変数 maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // 任意。自動検出するなら省略 + provider: "firecrawl", // 任意。自動検出する場合は省略 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2165,7 +2198,7 @@ tool-loop安全性チェックは **デフォルトで無効** です。有効 ### `tools.media` -受信media理解（image/audio/video）を設定します: +受信メディア理解（画像/音声/動画）を設定します: ```json5 { @@ -2173,7 +2206,7 @@ tool-loop安全性チェックは **デフォルトで無効** です。有効 media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: 完了したasync music/videoを直接channelへ送信 + directSend: false, // オプトイン: 完了した非同期music/videoをchannelへ直接送信 }, audio: { enabled: true, @@ -2197,32 +2230,32 @@ tool-loop安全性チェックは **デフォルトで無効** です。有効 } ``` - + -**Provider entry**（`type: "provider"` または省略時）: +**Providerエントリ**（`type: "provider"` または省略時）: - `provider`: API provider id（`openai`、`anthropic`、`google`/`gemini`、`groq` など） -- `model`: model idオーバーライド -- `profile` / `preferredProfile`: `auth-profiles.json` profile選択 +- `model`: model id上書き +- `profile` / `preferredProfile`: `auth-profiles.json` のprofile選択 -**CLI entry**（`type: "cli"`）: +**CLIエントリ**（`type: "cli"`）: -- `command`: 実行するexecutable -- `args`: template化されたargs（`{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` などをサポート） +- `command`: 実行する実行ファイル +- `args`: テンプレート化された引数（`{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` などをサポート） **共通フィールド:** - `capabilities`: 任意の一覧（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → image、`google` → image+audio+video、`groq` → audio。 -- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: entryごとのオーバーライド。 -- 失敗時は次のentryへフォールバックします。 +- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリごとの上書き。 +- 失敗時は次のエントリにフォールバックします。 -Provider authは標準順序に従います: `auth-profiles.json` → env vars → `models.providers.*.apiKey`。 +provider authは標準順序に従います: `auth-profiles.json` → 環境変数 → `models.providers.*.apiKey`。 -**Async completionフィールド:** +**非同期完了フィールド:** -- `asyncCompletion.directSend`: `true` の場合、完了したasync `music_generate` - および `video_generate` タスクは、まずdirect channel配信を試みます。デフォルト: `false` - （レガシーのrequester-session wake/model-delivery path）。 +- `asyncCompletion.directSend`: `true` の場合、完了した非同期 `music_generate` + および `video_generate` タスクは、まずchannelへの直接配信を試みます。デフォルト: `false` + （レガシーのrequester-session wake/model-delivery経路）。 @@ -2241,9 +2274,9 @@ Provider authは標準順序に従います: `auth-profiles.json` → env vars ### `tools.sessions` -session tool（`sessions_list`、`sessions_history`、`sessions_send`）でターゲットにできるsessionを制御します。 +セッションtool（`sessions_list`、`sessions_history`、`sessions_send`）で対象にできるセッションを制御します。 -デフォルト: `tree`（現在のsession + そこからspawnされたsession。subagentなど）。 +デフォルト: `tree`（現在のセッション + そこからspawnされたセッション。subagentなど）。 ```json5 { @@ -2256,46 +2289,46 @@ session tool（`sessions_list`、`sessions_history`、`sessions_send`）でタ } ``` -注記: +注意: -- `self`: 現在のsession keyのみ。 -- `tree`: 現在のsession + 現在のsessionからspawnされたsession（subagent）。 -- `agent`: 現在のagent idに属する任意のsession（同じagent idの下でper-sender sessionを実行している場合、他ユーザーを含むことがあります）。 -- `all`: 任意のsession。cross-agent targetingには依然として `tools.agentToAgent` が必要です。 -- Sandbox clamp: 現在のsessionがsandbox化されており、`agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` であっても可視性は `tree` に強制されます。 +- `self`: 現在のセッションキーのみ。 +- `tree`: 現在のセッション + 現在のセッションからspawnされたセッション（subagent）。 +- `agent`: 現在のagent idに属する任意のセッション（同じagent id配下でper-senderセッションを実行している場合、他のユーザーを含むことがあります）。 +- `all`: 任意のセッション。agentをまたぐターゲティングには引き続き `tools.agentToAgent` が必要です。 +- Sandbox clamp: 現在のセッションがsandbox化されていて `agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` であっても visibility は `tree` に強制されます。 ### `tools.sessions_spawn` -`sessions_spawn` のインラインattachmentサポートを制御します。 +`sessions_spawn` のインライン添付ファイルサポートを制御します。 ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: インラインfile attachmentを許可するには true - maxTotalBytes: 5242880, // 全file合計 5 MB + enabled: false, // オプトイン: true にするとインラインファイル添付を許可 + maxTotalBytes: 5242880, // 全ファイル合計 5 MB maxFiles: 50, - maxFileBytes: 1048576, // fileごと 1 MB - retainOnSessionKeep: false, // cleanup="keep" のときattachmentを保持 + maxFileBytes: 1048576, // 1ファイルあたり 1 MB + retainOnSessionKeep: false, // cleanup="keep" のときに添付を保持 }, }, }, } ``` -注記: +注意: -- Attachmentは `runtime: "subagent"` でのみサポートされます。ACP runtimeでは拒否されます。 -- Fileは子workspaceの `.openclaw/attachments//` に `.manifest.json` とともに実体化されます。 -- Attachment内容はtranscript永続化から自動的にredactされます。 -- Base64入力は、厳格なalphabet/paddingチェックとdecode前サイズガードで検証されます。 -- File permissionはdirectoryに `0700`、fileに `0600` です。 -- Cleanupは `cleanup` policyに従います: `delete` は常にattachmentを削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 +- 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACP runtimeはこれらを拒否します。 +- ファイルは `.manifest.json` とともに、子workspaceの `.openclaw/attachments//` に実体化されます。 +- 添付内容はトランスクリプト永続化から自動的に秘匿化されます。 +- Base64入力は、厳格なアルファベット/パディング検査とデコード前サイズガードで検証されます。 +- ファイル権限はディレクトリが `0700`、ファイルが `0600` です。 +- クリーンアップは `cleanup` ポリシーに従います: `delete` は常に添付を削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 ### `tools.experimental` -実験的な組み込みtoolフラグです。runtime固有の自動有効化ルールが適用されない限り、デフォルトはオフです。 +実験的な組み込みtoolフラグです。strict-agentic GPT-5の自動有効化ルールが適用されない限り、デフォルトは無効です。 ```json5 { @@ -2307,11 +2340,11 @@ session tool（`sessions_list`、`sessions_history`、`sessions_send`）でタ } ``` -注記: +注意: -- `planTool`: 構造化された `update_plan` toolを有効にし、単純でない複数ステップ作業の追跡に使用します。 -- デフォルト: OpenAI以外のproviderでは `false`。OpenAIおよびOpenAI Codex実行では未設定時に自動有効化されます。自動有効化を無効にするには `false` を設定してください。 -- 有効時、system promptにも利用ガイダンスが追加され、modelがこれを実質的な作業にのみ使い、`in_progress` のステップを最大1つに保つようにします。 +- `planTool`: 重要な複数ステップ作業を追跡するための構造化 `update_plan` toolを有効にします。 +- デフォルト: `false`。ただし、`agents.defaults.embeddedPi.executionContract`（またはagentごとの上書き）がOpenAIまたはOpenAI CodexのGPT-5ファミリー実行向けに `"strict-agentic"` に設定されている場合は除きます。その範囲外でもtoolを強制的に有効にするには `true`、strict-agentic GPT-5実行でも無効のままにするには `false` を設定します。 +- 有効時は、system promptにも使用ガイダンスが追加され、モデルはこれを実質的な作業にのみ使い、`in_progress` のステップを最大1つまでに保つようになります。 ### `agents.defaults.subagents` @@ -2331,21 +2364,21 @@ session tool（`sessions_list`、`sessions_history`、`sessions_send`）でタ } ``` -- `model`: spawnされるsub-agent用のデフォルトmodel。省略時、sub-agentは呼び出し元のmodelを継承します。 -- `allowAgents`: 要求元agentが独自の `subagents.allowAgents` を設定していない場合の `sessions_spawn` ターゲットagent idデフォルトallowlist（`["*"]` = 任意。デフォルト: 同じagentのみ）。 -- `runTimeoutSeconds`: tool callで `runTimeoutSeconds` を省略した場合の `sessions_spawn` デフォルトtimeout（秒）。`0` はtimeoutなしを意味します。 -- subagentごとのtool policy: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `model`: spawnされたsub-agentのデフォルトモデル。省略時、sub-agentは呼び出し元のモデルを継承します。 +- `allowAgents`: 要求元agentが独自の `subagents.allowAgents` を設定していない場合の、`sessions_spawn` 向けターゲットagent idのデフォルト許可リスト（`["*"]` = 任意、デフォルト: 同じagentのみ）。 +- `runTimeoutSeconds`: tool callで `runTimeoutSeconds` が省略された場合の、`sessions_spawn` のデフォルトタイムアウト（秒）。`0` はタイムアウトなしを意味します。 +- subagentごとのtoolポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## カスタムproviderとbase URL -OpenClawは組み込みmodel catalogを使用します。カスタムproviderはconfig内の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加してください。 +OpenClawは組み込みモデルカタログを使用します。カスタムproviderはconfig内の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加します。 ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge（デフォルト）| replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2369,51 +2402,52 @@ OpenClawは組み込みmodel catalogを使用します。カスタムproviderは } ``` -- カスタム認証が必要な場合は `authHeader: true` + `headers` を使用してください。 -- Agent config rootは `OPENCLAW_AGENT_DIR`（またはレガシー環境変数aliasの `PI_CODING_AGENT_DIR`）で上書きできます。 +- カスタム認証が必要な場合は `authHeader: true` + `headers` を使用します。 +- agent config rootは `OPENCLAW_AGENT_DIR`（またはレガシー環境変数別名の `PI_CODING_AGENT_DIR`）で上書きできます。 - 一致するprovider IDに対するマージ優先順位: - 空でないagent `models.json` の `baseUrl` 値が優先されます。 - - 空でないagent `apiKey` 値は、そのproviderが現在のconfig/auth-profile contextでSecretRef管理されていない場合にのみ優先されます。 - - SecretRef管理されたprovider `apiKey` 値は、解決済みsecretを永続化する代わりに、source marker（env refなら `ENV_VAR_NAME`、file/exec refなら `secretref-managed`）から更新されます。 - - SecretRef管理されたprovider header値は、source marker（env refなら `secretref-env:ENV_VAR_NAME`、file/exec refなら `secretref-managed`）から更新されます。 - - agentの `apiKey`/`baseUrl` が空または欠落している場合は、config内の `models.providers` にフォールバックします。 - - 一致するmodelの `contextWindow`/`maxTokens` には、明示config値と暗黙catalog値の高い方が使われます。 - - 一致するmodelの `contextTokens` は、明示的なruntime capが存在する場合はそれを保持します。ネイティブmodel metadataを変更せずに有効contextを制限したい場合に使用してください。 - - configで `models.json` を完全に書き換えたい場合は `models.mode: "replace"` を使ってください。 - - Marker永続化はsource-authoritativeです: markerは解決済みruntime secret値からではなく、アクティブなsource config snapshot（解決前）から書き込まれます。 + - 空でないagentの `apiKey` 値は、そのproviderが現在のconfig/auth-profile文脈でSecretRef管理されていない場合にのみ優先されます。 + - SecretRef管理されたproviderの `apiKey` 値は、解決済みsecretを永続化する代わりに、ソースマーカー（環境変数参照なら `ENV_VAR_NAME`、file/exec参照なら `secretref-managed`）から更新されます。 + - SecretRef管理されたprovider header値は、ソースマーカー（環境変数参照なら `secretref-env:ENV_VAR_NAME`、file/exec参照なら `secretref-managed`）から更新されます。 + - 空または欠落しているagentの `apiKey` / `baseUrl` は、config内の `models.providers` にフォールバックします。 + - 一致するmodelの `contextWindow` / `maxTokens` には、明示的config値と暗黙のカタログ値のうち高い方が使われます。 + - 一致するmodelの `contextTokens` は、明示的なランタイム上限がある場合それを保持します。ネイティブなmodelメタデータを変えずに有効コンテキストを制限したい場合に使用してください。 + - configで `models.json` を完全に書き換えたい場合は `models.mode: "replace"` を使用します。 + - マーカーの永続化はソースを正とします。マーカーは、解決済みのランタイムsecret値からではなく、アクティブなソースconfigスナップショット（解決前）から書き込まれます。 -### Providerフィールド詳細 +### Providerフィールドの詳細 -- `models.mode`: provider catalogの動作（`merge` または `replace`）。 -- `models.providers`: provider idをキーとするカスタムprovider map。 -- `models.providers.*.api`: request adapter（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。 -- `models.providers.*.apiKey`: provider資格情報（SecretRef/env substitution推奨）。 +- `models.mode`: providerカタログの動作（`merge` または `replace`）。 +- `models.providers`: provider idをキーにしたカスタムproviderマップ。 +- `models.providers.*.api`: リクエストアダプター（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。 +- `models.providers.*.apiKey`: provider認証情報（SecretRef/環境変数置換の利用を推奨）。 - `models.providers.*.auth`: 認証戦略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` 用に `options.num_ctx` をrequestへ注入します（デフォルト: `true`）。 -- `models.providers.*.authHeader`: 必要な場合に資格情報を `Authorization` headerで送るよう強制します。 -- `models.providers.*.baseUrl`: 上流API base URL。 -- `models.providers.*.headers`: proxy/tenant routing用の追加静的header。 -- `models.providers.*.request`: model-provider HTTP request用の転送オーバーライド。 - - `request.headers`: 追加header（providerデフォルトとマージ）。値はSecretRefを受け付けます。 - - `request.auth`: 認証戦略オーバーライド。モード: `"provider-default"`（provider組み込み認証を使用）、`"authorization-bearer"`（`token` とともに使用）、`"header"`（`headerName`、`value`、任意の `prefix` とともに使用）。 - - `request.proxy`: HTTP proxyオーバーライド。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` env varsを使用）、`"explicit-proxy"`（`url` とともに使用）。両モードとも任意の `tls` サブオブジェクトを受け付けます。 - - `request.tls`: direct connection用TLSオーバーライド。フィールド: `ca`、`cert`、`key`、`passphrase`（いずれもSecretRefを受け付けます）、`serverName`、`insecureSkipVerify`。 -- `models.providers.*.models`: 明示的なprovider model catalog entry。 -- `models.providers.*.models.*.contextWindow`: ネイティブmodel context window metadata。 -- `models.providers.*.models.*.contextTokens`: 任意のruntime context cap。modelのネイティブ `contextWindow` より小さい有効context budgetを使いたい場合に使用してください。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`: 任意の互換性ヒント。`api: "openai-completions"` かつ空でない非ネイティブ `baseUrl`（hostが `api.openai.com` ではない）の場合、OpenClawはruntime時にこれを `false` に強制します。空または省略された `baseUrl` ではデフォルトのOpenAI動作が維持されます。 -- `models.providers.*.models.*.compat.requiresStringContent`: string-onlyのOpenAI互換chat endpoint向けの任意互換性ヒント。`true` の場合、OpenClawは純粋なtext `messages[].content` 配列をrequest送信前に単純文字列へ平坦化します。 -- `plugins.entries.amazon-bedrock.config.discovery`: Bedrock auto-discovery設定ルート。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙discoveryのオン/オフ。 -- `plugins.entries.amazon-bedrock.config.discovery.region`: discovery用のAWS region。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象discovery用の任意provider-id filter。 -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: discovery refreshのpolling interval。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 発見されたmodel用のフォールバックcontext window。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 発見されたmodel用のフォールバック最大出力token数。 +- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` 向けに、リクエストへ `options.num_ctx` を注入します（デフォルト: `true`）。 +- `models.providers.*.authHeader`: 必要な場合に、認証情報を `Authorization` ヘッダーで送るよう強制します。 +- `models.providers.*.baseUrl`: 上流APIのbase URL。 +- `models.providers.*.headers`: proxy/tenantルーティング用の追加静的ヘッダー。 +- `models.providers.*.request`: model-provider HTTPリクエスト向けの転送上書き。 + - `request.headers`: 追加ヘッダー（providerデフォルトとマージされます）。値にはSecretRefを指定できます。 + - `request.auth`: 認証戦略の上書き。モード: `"provider-default"`（provider組み込み認証を使用）、`"authorization-bearer"`（`token` を使用）、`"header"`（`headerName`、`value`、任意の `prefix` を使用）。 + - `request.proxy`: HTTP proxy上書き。モード: `"env-proxy"`（`HTTP_PROXY` / `HTTPS_PROXY` 環境変数を使用）、`"explicit-proxy"`（`url` を使用）。どちらのモードでも任意の `tls` サブオブジェクトを受け付けます。 + - `request.tls`: 直接接続向けのTLS上書き。フィールド: `ca`、`cert`、`key`、`passphrase`（すべてSecretRef可）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`: `true` の場合、provider HTTPフェッチガードを通じて、DNSがプライベート、CGNAT、または類似範囲へ解決される `baseUrl` へのHTTPSを許可します（信頼済みのセルフホストOpenAI互換エンドポイント向けのoperatorオプトイン）。WebSocketはヘッダー/TLSに同じ `request` を使いますが、そのfetch SSRFガードは使いません。デフォルト `false`。 +- `models.providers.*.models`: 明示的なproviderモデルカタログエントリ。 +- `models.providers.*.models.*.contextWindow`: ネイティブなmodelコンテキストウィンドウメタデータ。 +- `models.providers.*.models.*.contextTokens`: 任意のランタイムコンテキスト上限。model本来の `contextWindow` より小さい有効コンテキスト予算にしたい場合に使用します。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`: 任意の互換性ヒント。`api: "openai-completions"` で、空でない非ネイティブ `baseUrl`（ホストが `api.openai.com` ではない）の場合、OpenClawは実行時にこれを `false` に強制します。`baseUrl` が空または省略時は、デフォルトのOpenAI動作を維持します。 +- `models.providers.*.models.*.compat.requiresStringContent`: 文字列のみを受け付けるOpenAI互換chatエンドポイント向けの任意の互換性ヒント。`true` の場合、OpenClawはリクエスト送信前に、純粋なテキストの `messages[].content` 配列をプレーン文字列へ平坦化します。 +- `plugins.entries.amazon-bedrock.config.discovery`: Bedrock自動検出設定のルート。 +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙の検出をオン/オフします。 +- `plugins.entries.amazon-bedrock.config.discovery.region`: 検出に使うAWSリージョン。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象を絞った検出のための任意のprovider-idフィルター。 +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: 検出更新のポーリング間隔。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出されたmodelのフォールバックコンテキストウィンドウ。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出されたmodelのフォールバック最大出力token数。 -### Provider例 +### Providerの例 - + ```json5 { @@ -2447,7 +2481,7 @@ OpenClawは組み込みmodel catalogを使用します。カスタムproviderは } ``` -Cerebrasには `cerebras/zai-glm-4.7`、Z.AI directには `zai/glm-4.7` を使用してください。 +Cerebrasには `cerebras/zai-glm-4.7` を使用します。Z.AI直結には `zai/glm-4.7` を使用します。 @@ -2464,11 +2498,11 @@ Cerebrasには `cerebras/zai-glm-4.7`、Z.AI directには `zai/glm-4.7` を使 } ``` -`OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`）を設定してください。Zen catalogには `opencode/...` ref、Go catalogには `opencode-go/...` refを使用します。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。 +`OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`）を設定してください。Zenカタログには `opencode/...` 参照、Goカタログには `opencode-go/...` 参照を使用します。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。 - + ```json5 { @@ -2481,15 +2515,15 @@ Cerebrasには `cerebras/zai-glm-4.7`、Z.AI directには `zai/glm-4.7` を使 } ``` -`ZAI_API_KEY` を設定してください。`z.ai/*` と `z-ai/*` は受け付けられるaliasです。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 +`ZAI_API_KEY` を設定してください。`z.ai/*` と `z-ai/*` は受け付けられる別名です。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 -- 一般endpoint: `https://api.z.ai/api/paas/v4` -- Coding endpoint（デフォルト）: `https://api.z.ai/api/coding/paas/v4` -- 一般endpointを使う場合は、base URLオーバーライド付きのカスタムproviderを定義してください。 +- 一般エンドポイント: `https://api.z.ai/api/paas/v4` +- Codingエンドポイント（デフォルト）: `https://api.z.ai/api/coding/paas/v4` +- 一般エンドポイントを使う場合は、base URL上書きを持つカスタムproviderを定義してください。 - + ```json5 { @@ -2524,11 +2558,11 @@ Cerebrasには `cerebras/zai-glm-4.7`、Z.AI directには `zai/glm-4.7` を使 } ``` -China endpointには `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn` を使用してください。 +中国向けエンドポイントでは、`baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn` を使用してください。 -ネイティブMoonshot endpointは、共有 -`openai-completions` transport上でstreaming使用互換性を提示し、OpenClawは組み込みprovider id単独ではなく -そのendpoint capabilityに基づいて処理します。 +ネイティブMoonshotエンドポイントは、共有の +`openai-completions` 転送上でのストリーミング利用互換性を通知しており、 +OpenClawは組み込みprovider idだけでなく、そのエンドポイント機能に基づいて動作を決定します。 @@ -2550,7 +2584,7 @@ Anthropic互換の組み込みproviderです。ショートカット: `openclaw - + ```json5 { @@ -2585,11 +2619,11 @@ Anthropic互換の組み込みproviderです。ショートカット: `openclaw } ``` -Base URLには `/v1` を含めないでください（Anthropic clientが付加します）。ショートカット: `openclaw onboard --auth-choice synthetic-api-key`。 +base URLには `/v1` を含めないでください（Anthropicクライアントが追加します）。ショートカット: `openclaw onboard --auth-choice synthetic-api-key`。 - + ```json5 { @@ -2628,17 +2662,17 @@ Base URLには `/v1` を含めないでください（Anthropic clientが付加 `MINIMAX_API_KEY` を設定してください。ショートカット: `openclaw onboard --auth-choice minimax-global-api` または `openclaw onboard --auth-choice minimax-cn-api`。 -model catalogのデフォルトはM2.7のみです。 -Anthropic互換streaming pathでは、OpenClawは明示的に `thinking` を設定しない限り -デフォルトでMiniMax thinkingを無効にします。`/fast on` または +モデルカタログのデフォルトはM2.7のみです。 +Anthropic互換ストリーミング経路では、OpenClawは明示的に `thinking` を設定しない限り、 +MiniMaxのthinkingをデフォルトで無効にします。`/fast on` または `params.fastMode: true` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。 - + -[Local Models](/ja-JP/gateway/local-models) を参照してください。要点: 十分なハードウェア上でLM Studio Responses API経由の大規模ローカルmodelを実行し、フォールバック用にhosted modelはマージしたままにしてください。 +[Local Models](/ja-JP/gateway/local-models) を参照してください。要点: 十分なハードウェア上でLM Studio Responses API経由の大規模ローカルモデルを実行し、フォールバック用にホスト型モデルをマージしたままにしておきます。 @@ -2660,4 +2694,1031 @@ Anthropic互換streaming pathでは、OpenClawは明示的に `thinking` を設 entries: { "image-lab": { apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // または平文文字列 - env: { GEMINI_API \ No newline at end of file + env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, + }, + peekaboo: { enabled: true }, + sag: { enabled: false }, + }, + }, +} +``` + +- `allowBundled`: bundled skillsのみに対する任意の許可リストです（managed/workspace skillsには影響しません）。 +- `load.extraDirs`: 追加の共有skillルート（最も低い優先順位）。 +- `install.preferBrew`: true の場合、`brew` が利用可能なら他のインストーラー種別へフォールバックする前にHomebrewインストーラーを優先します。 +- `install.nodeManager`: `metadata.openclaw.install` 仕様に対するnodeインストーラーの優先設定（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false` は、bundled/installedであってもそのskillを無効にします。 +- `entries..apiKey`: 主たる環境変数を宣言するskills向けの簡易指定です（平文文字列またはSecretRefオブジェクト）。 + +--- + +## Plugins + +```json5 +{ + plugins: { + enabled: true, + allow: ["voice-call"], + deny: [], + load: { + paths: ["~/Projects/oss/voice-call-extension"], + }, + entries: { + "voice-call": { + enabled: true, + hooks: { + allowPromptInjection: false, + }, + config: { provider: "twilio" }, + }, + }, + }, +} +``` + +- `~/.openclaw/extensions`、`/.openclaw/extensions`、および `plugins.load.paths` から読み込まれます。 +- 検出では、ネイティブOpenClaw pluginに加えて、manifestのないClaudeデフォルトレイアウトbundleを含む互換Codex bundleとClaude bundleも受け付けます。 +- **設定変更にはgatewayの再起動が必要です。** +- `allow`: 任意の許可リスト（列挙されたpluginのみ読み込み）。`deny` が優先されます。 +- `plugins.entries..apiKey`: pluginレベルのAPIキー簡易フィールド（pluginが対応している場合）。 +- `plugins.entries..env`: pluginスコープの環境変数マップ。 +- `plugins.entries..hooks.allowPromptInjection`: `false` の場合、coreは `before_prompt_build` をブロックし、レガシーな `before_agent_start` からのprompt変更フィールドを無視します。一方で、レガシーな `modelOverride` と `providerOverride` は保持します。ネイティブplugin hookと、対応するbundle提供hookディレクトリに適用されます。 +- `plugins.entries..subagent.allowModelOverride`: このpluginがバックグラウンドsubagent実行で実行ごとの `provider` と `model` 上書きを要求することを明示的に信頼します。 +- `plugins.entries..subagent.allowedModels`: 信頼済みsubagent上書き向けの、任意の正規 `provider/model` ターゲット許可リスト。任意のmodelを許可したい意図がある場合にのみ `"*"` を使用してください。 +- `plugins.entries..config`: plugin定義のconfigオブジェクト（利用可能な場合はネイティブOpenClaw plugin schemaで検証されます）。 +- `plugins.entries.firecrawl.config.webFetch`: Firecrawl web-fetch provider設定。 + - `apiKey`: Firecrawl APIキー（SecretRef可）。`plugins.entries.firecrawl.config.webSearch.apiKey`、レガシーな `tools.web.fetch.firecrawl.apiKey`、または `FIRECRAWL_API_KEY` 環境変数にフォールバックします。 + - `baseUrl`: Firecrawl APIのbase URL（デフォルト: `https://api.firecrawl.dev`）。 + - `onlyMainContent`: ページからメインコンテンツのみを抽出します（デフォルト: `true`）。 + - `maxAgeMs`: キャッシュの最大有効期間（ミリ秒）（デフォルト: `172800000` / 2日）。 + - `timeoutSeconds`: スクレイプリクエストのタイムアウト（秒）（デフォルト: `60`）。 +- `plugins.entries.xai.config.xSearch`: xAI X Search（Grok web search）設定。 + - `enabled`: X Search providerを有効にします。 + - `model`: 検索に使うGrokモデル（例: `"grok-4-1-fast"`）。 +- `plugins.entries.memory-core.config.dreaming`: memory dreaming（実験的）設定。フェーズとしきい値は [Dreaming](/ja-JP/concepts/dreaming) を参照してください。 + - `enabled`: dreamingのマスタースイッチ（デフォルト `false`）。 + - `frequency`: 各フルdreaming sweepのcron間隔（デフォルトは `"0 3 * * *"`）。 + - フェーズポリシーとしきい値は実装詳細であり、ユーザー向けconfigキーではありません。 +- 完全なmemory設定は [Memory configuration reference](/ja-JP/reference/memory-config) にあります: + - `agents.defaults.memorySearch.*` + - `memory.backend` + - `memory.citations` + - `memory.qmd.*` + - `plugins.entries.memory-core.config.dreaming` +- 有効なClaude bundle pluginは、`settings.json` から埋め込みPiデフォルトを提供することもできます。OpenClawはそれらを生のOpenClaw configパッチではなく、サニタイズ済みagent設定として適用します。 +- `plugins.slots.memory`: アクティブなmemory plugin idを選択します。memory pluginを無効にするには `"none"` を指定します。 +- `plugins.slots.contextEngine`: アクティブなcontext engine plugin idを選択します。別のengineをインストールして選択しない限り、デフォルトは `"legacy"` です。 +- `plugins.installs`: `openclaw plugins update` で使用されるCLI管理のインストールメタデータです。 + - `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt` を含みます。 + - `plugins.installs.*` は管理対象状態として扱い、手動編集よりCLIコマンドを優先してください。 + +[Plugins](/ja-JP/tools/plugin) を参照してください。 + +--- + +## Browser + +```json5 +{ + browser: { + enabled: true, + evaluateEnabled: true, + defaultProfile: "user", + ssrfPolicy: { + // dangerouslyAllowPrivateNetwork: true, // 信頼済みプライベートネットワークアクセスにのみオプトイン + // allowPrivateNetwork: true, // レガシー別名 + // hostnameAllowlist: ["*.example.com", "example.com"], + // allowedHostnames: ["localhost"], + }, + profiles: { + openclaw: { cdpPort: 18800, color: "#FF4500" }, + work: { cdpPort: 18801, color: "#0066CC" }, + user: { driver: "existing-session", attachOnly: true, color: "#00AA00" }, + brave: { + driver: "existing-session", + attachOnly: true, + userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser", + color: "#FB542B", + }, + remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }, + }, + color: "#FF4500", + // headless: false, + // noSandbox: false, + // extraArgs: [], + // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", + // attachOnly: false, + }, +} +``` + +- `evaluateEnabled: false` は `act:evaluate` と `wait --fn` を無効にします。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定時は無効なので、browserナビゲーションはデフォルトで厳格なままです。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` は、プライベートネットワークbrowserナビゲーションを意図的に信頼する場合にのみ設定してください。 +- strictモードでは、リモートCDP profileエンドポイント（`profiles.*.cdpUrl`）も、到達性/検出チェック中に同じプライベートネットワークブロックの対象になります。 +- `ssrfPolicy.allowPrivateNetwork` は引き続きレガシー別名としてサポートされます。 +- strictモードでは、明示的な例外に `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使用します。 +- リモートprofileはattach-onlyです（start/stop/resetは無効）。 +- `profiles.*.cdpUrl` は `http://`、`https://`、`ws://`、`wss://` を受け付けます。 + `/json/version` をOpenClawに検出させたい場合はHTTP(S)を使用し、 + providerが直接のDevTools WebSocket URLを提供する場合はWS(S)を使用してください。 +- `existing-session` profileはホスト専用で、CDPではなくChrome MCPを使用します。 +- `existing-session` profileでは、BraveやEdgeのような特定の + Chromiumベースbrowser profileをターゲットにするために `userDataDir` を設定できます。 +- `existing-session` profileは、現在のChrome MCPルート制限を維持します: + CSSセレクター指定ではなくsnapshot/refベースのアクション、単一ファイルアップロード + hook、dialog timeout上書きなし、`wait --load networkidle` なし、 + `responsebody`、PDFエクスポート、ダウンロード横取り、バッチアクションなし。 +- ローカル管理の `openclaw` profileは `cdpPort` と `cdpUrl` を自動割り当てします。明示的に `cdpUrl` を設定するのはリモートCDPの場合のみです。 +- 自動検出順: デフォルトbrowserがChromiumベースならそれを優先 → Chrome → Brave → Edge → Chromium → Chrome Canary。 +- Control service: loopbackのみ（portは `gateway.port` から導出。デフォルト `18791`）。 +- `extraArgs` は、ローカルChromium起動に追加の起動フラグを付加します（たとえば `--disable-gpu`、ウィンドウサイズ指定、デバッグフラグなど）。 + +--- + +## UI + +```json5 +{ + ui: { + seamColor: "#FF4500", + assistant: { + name: "OpenClaw", + avatar: "CB", // emoji、短いテキスト、画像URL、またはdata URI + }, + }, +} +``` + +- `seamColor`: ネイティブアプリUIクローム向けのアクセントカラーです（Talk Modeの吹き出し色など）。 +- `assistant`: Control UIのidentity上書き。アクティブagent identityにフォールバックします。 + +--- + +## Gateway + +```json5 +{ + gateway: { + mode: "local", // local | remote + port: 18789, + bind: "loopback", + auth: { + mode: "token", // none | token | password | trusted-proxy + token: "your-token", + // password: "your-password", // または OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // mode=trusted-proxy 用。/gateway/trusted-proxy-auth を参照 + allowTailscale: true, + rateLimit: { + maxAttempts: 10, + windowMs: 60000, + lockoutMs: 300000, + exemptLoopback: true, + }, + }, + tailscale: { + mode: "off", // off | serve | funnel + resetOnExit: false, + }, + controlUi: { + enabled: true, + basePath: "/openclaw", + // root: "dist/control-ui", + // allowedOrigins: ["https://control.example.com"], // loopback以外のControl UIでは必須 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危険なHostヘッダーoriginフォールバックモード + // allowInsecureAuth: false, + // dangerouslyDisableDeviceAuth: false, + }, + remote: { + url: "ws://gateway.tailnet:18789", + transport: "ssh", // ssh | direct + token: "your-token", + // password: "your-password", + }, + trustedProxies: ["10.0.0.1"], + // 任意。デフォルトは false。 + allowRealIpFallback: false, + tools: { + // 追加の /tools/invoke HTTP deny + deny: ["browser"], + // デフォルトのHTTP denyリストからtoolを除外 + allow: ["gateway"], + }, + push: { + apns: { + relay: { + baseUrl: "https://relay.example.com", + timeoutMs: 10000, + }, + }, + }, + }, +} +``` + + + +- `mode`: `local`（gatewayを実行）または `remote`（リモートgatewayへ接続）。Gatewayは `local` でない限り起動を拒否します。 +- `port`: WS + HTTP用の単一多重化port。優先順位: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `bind`: `auto`、`loopback`（デフォルト）、`lan`（`0.0.0.0`）、`tailnet`（Tailscale IPのみ）、または `custom`。 +- **レガシーbind別名**: `gateway.bind` では、ホスト別名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）ではなく、bind mode値（`auto`、`loopback`、`lan`、`tailnet`、`custom`）を使用してください。 +- **Docker注記**: デフォルトの `loopback` bindは、コンテナー内の `127.0.0.1` で待ち受けます。Docker bridgeネットワーク（`-p 18789:18789`）では、トラフィックは `eth0` に到着するため、gatewayには到達できません。`--network host` を使用するか、全インターフェースで待ち受けるために `bind: "lan"`（または `bind: "custom"` と `customBindHost: "0.0.0.0"`）を設定してください。 +- **Auth**: デフォルトで必須です。loopback以外のbindではgateway authが必要です。実際には、共有token/password、または `gateway.auth.mode: "trusted-proxy"` を持つidentity-aware reverse proxyを意味します。オンボーディングウィザードはデフォルトでtokenを生成します。 +- `gateway.auth.token` と `gateway.auth.password` の両方が設定されている場合（SecretRefを含む）、`gateway.auth.mode` を `token` または `password` に明示設定してください。両方が設定されていてmodeが未設定の場合、起動およびサービスのインストール/修復フローは失敗します。 +- `gateway.auth.mode: "none"`: 明示的な認証なしモードです。信頼されたローカルのlocal loopback構成でのみ使用してください。これは意図的にオンボーディングプロンプトでは提供されません。 +- `gateway.auth.mode: "trusted-proxy"`: authをidentity-aware reverse proxyへ委譲し、`gateway.trustedProxies` からのIDヘッダーを信頼します（[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照）。このモードは**非loopback**のproxyソースを前提とします。同一ホストのloopback reverse proxyはtrusted-proxy authの条件を満たしません。 +- `gateway.auth.allowTailscale`: `true` の場合、Tailscale ServeのIDヘッダーでControl UI/WebSocket authを満たせます（`tailscale whois` で検証）。HTTP APIエンドポイントではそのTailscaleヘッダーauthは使われず、通常のgateway HTTP auth modeに従います。このtoken不要フローは、gateway hostが信頼されていることを前提とします。`tailscale.mode = "serve"` の場合、デフォルトは `true` です。 +- `gateway.auth.rateLimit`: 任意の認証失敗リミッター。クライアントIPごとかつ認証スコープごとに適用されます（共有secretとdevice-tokenは独立して追跡されます）。ブロックされた試行では `429` + `Retry-After` が返されます。 + - 非同期のTailscale Serve Control UI経路では、同じ `{scope, clientIp}` に対する失敗試行は、失敗書き込み前に直列化されます。そのため、同一クライアントからの同時の不正試行は、両方が単なる不一致として通るのではなく、2回目のリクエストでリミッターにかかることがあります。 + - `gateway.auth.rateLimit.exemptLoopback` のデフォルトは `true` です。localhostトラフィックにもレート制限をかけたい場合（テスト環境や厳格なproxy構成など）は `false` に設定してください。 +- browser起点のWS auth試行は、loopback除外を無効にした状態で常にスロットルされます（browserベースのlocalhost総当たりに対する多層防御）。 +- loopback上では、それらのbrowser起点lockoutは正規化された `Origin` + 値ごとに分離されるため、あるlocalhost originからの繰り返し失敗が、 + 別のoriginを自動的にロックアウトすることはありません。 +- `tailscale.mode`: `serve`（tailnetのみ、loopback bind）または `funnel`（公開、auth必須）。 +- `controlUi.allowedOrigins`: Gateway WebSocket接続向けの明示的なbrowser-origin許可リストです。browserクライアントをloopback以外のoriginから想定する場合は必須です。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Hostヘッダーoriginポリシーへ意図的に依存するデプロイ向けの危険なモードで、Hostヘッダーoriginフォールバックを有効にします。 +- `remote.transport`: `ssh`（デフォルト）または `direct`（ws/wss）。`direct` の場合、`remote.url` は `ws://` または `wss://` である必要があります。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: 信頼済みプライベートネットワークIPへの平文 `ws://` を許可するクライアント側の緊急用上書きです。デフォルトでは、平文は引き続きloopbackのみです。 +- `gateway.remote.token` / `.password` はリモートクライアントの認証情報フィールドです。これ自体ではgateway authを設定しません。 +- `gateway.push.apns.relay.baseUrl`: 公式/TestFlightのiOSビルドがrelayバックエンド登録をgatewayへ公開した後に使う、外部APNs relayのベースHTTPS URLです。このURLはiOSビルドにコンパイルされたrelay URLと一致している必要があります。 +- `gateway.push.apns.relay.timeoutMs`: gatewayからrelayへの送信タイムアウト（ミリ秒）。デフォルトは `10000`。 +- relayバックエンド登録は特定のgateway identityへ委譲されます。ペアリングされたiOSアプリは `gateway.identity.get` を取得し、そのidentityをrelay登録に含め、登録スコープの送信権限をgatewayへ転送します。別のgatewayはその保存済み登録を再利用できません。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 上記relay設定に対する一時的な環境変数上書きです。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTP relay URL向けの開発専用エスケープハッチです。本番relay URLはHTTPSのままにしてください。 +- `gateway.channelHealthCheckMinutes`: channelヘルスモニターの間隔（分）。グローバルにヘルスモニター再起動を無効にするには `0` を設定します。デフォルト: `5`。 +- `gateway.channelStaleEventThresholdMinutes`: stale-socketしきい値（分）。これは `gateway.channelHealthCheckMinutes` 以上にしてください。デフォルト: `30`。 +- `gateway.channelMaxRestartsPerHour`: ローリング1時間あたりの、channel/アカウントごとのヘルスモニター再起動最大回数。デフォルト: `10`。 +- `channels..healthMonitor.enabled`: グローバルモニターを有効のまま、channelごとにヘルスモニター再起動をオプトアウトします。 +- `channels..accounts..healthMonitor.enabled`: 複数アカウントchannel向けのアカウントごとの上書き。設定されている場合、channelレベル上書きより優先されます。 +- ローカルgateway呼び出し経路は、`gateway.auth.*` が未設定の場合にのみ、フォールバックとして `gateway.remote.*` を使用できます。 +- `gateway.auth.token` / `gateway.auth.password` がSecretRef経由で明示的に設定され、未解決の場合、解決はfail-closedになります（リモートフォールバックでマスクされません）。 +- `trustedProxies`: TLS終端や転送元クライアントヘッダー注入を行うreverse proxyのIPです。自分で管理しているproxyのみを列挙してください。loopbackエントリは同一ホストproxy/ローカル検出構成（たとえばTailscale Serveやローカルreverse proxy）では依然として有効ですが、loopbackリクエストが `gateway.auth.mode: "trusted-proxy"` の対象になることは**ありません**。 +- `allowRealIpFallback`: `true` の場合、`X-Forwarded-For` がないときにgatewayが `X-Real-IP` を受け付けます。fail-closed動作のためデフォルトは `false` です。 +- `gateway.tools.deny`: HTTP `POST /tools/invoke` でブロックする追加tool名です（デフォルトdenyリストを拡張）。 +- `gateway.tools.allow`: デフォルトHTTP denyリストからtool名を除外します。 + + + +### OpenAI互換エンドポイント + +- Chat Completions: デフォルトでは無効です。`gateway.http.endpoints.chatCompletions.enabled: true` で有効にします。 +- Responses API: `gateway.http.endpoints.responses.enabled`。 +- ResponsesのURL入力ハードニング: + - `gateway.http.endpoints.responses.maxUrlParts` + - `gateway.http.endpoints.responses.files.urlAllowlist` + - `gateway.http.endpoints.responses.images.urlAllowlist` + 空のallowlistは未設定として扱われます。URL取得を無効にするには + `gateway.http.endpoints.responses.files.allowUrl=false` + および/または `gateway.http.endpoints.responses.images.allowUrl=false` を使用してください。 +- 任意の応答ハードニングヘッダー: + - `gateway.http.securityHeaders.strictTransportSecurity`（自分で管理するHTTPS originに対してのみ設定してください。[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts) を参照） + +### 複数インスタンスの分離 + +1台のホストで複数のgatewayを、固有のportとstate dirで実行します: + +```bash +OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ +OPENCLAW_STATE_DIR=~/.openclaw-a \ +openclaw gateway --port 19001 +``` + +便利なフラグ: `--dev`（`~/.openclaw-dev` + port `19001` を使用）、`--profile `（`~/.openclaw-` を使用）。 + +[Multiple Gateways](/ja-JP/gateway/multiple-gateways) を参照してください。 + +### `gateway.tls` + +```json5 +{ + gateway: { + tls: { + enabled: false, + autoGenerate: false, + certPath: "/etc/openclaw/tls/server.crt", + keyPath: "/etc/openclaw/tls/server.key", + caPath: "/etc/openclaw/tls/ca-bundle.crt", + }, + }, +} +``` + +- `enabled`: gatewayリスナーでのTLS終端（HTTPS/WSS）を有効にします（デフォルト: `false`）。 +- `autoGenerate`: 明示的なファイルが設定されていない場合に、ローカルの自己署名cert/keyペアを自動生成します。ローカル/開発用途専用です。 +- `certPath`: TLS証明書ファイルのファイルシステムパス。 +- `keyPath`: TLS秘密鍵ファイルのファイルシステムパス。権限を制限しておいてください。 +- `caPath`: クライアント検証またはカスタム信頼チェーン用の任意のCA bundleパス。 + +### `gateway.reload` + +```json5 +{ + gateway: { + reload: { + mode: "hybrid", // off | restart | hot | hybrid + debounceMs: 500, + deferralTimeoutMs: 300000, + }, + }, +} +``` + +- `mode`: config編集を実行時にどう適用するかを制御します。 + - `"off"`: ライブ編集を無視します。変更には明示的な再起動が必要です。 + - `"restart"`: config変更時に常にgatewayプロセスを再起動します。 + - `"hot"`: 再起動せずにプロセス内で変更を適用します。 + - `"hybrid"`（デフォルト）: まずhot reloadを試し、必要なら再起動へフォールバックします。 +- `debounceMs`: config変更を適用する前のdebounce時間（ms）（非負整数）。 +- `deferralTimeoutMs`: 再起動を強制する前に進行中処理を待つ最大時間（ms）（デフォルト: `300000` = 5分）。 + +--- + +## Hooks + +```json5 +{ + hooks: { + enabled: true, + token: "shared-secret", + path: "/hooks", + maxBodyBytes: 262144, + defaultSessionKey: "hook:ingress", + allowRequestSessionKey: false, + allowedSessionKeyPrefixes: ["hook:"], + allowedAgentIds: ["hooks", "main"], + presets: ["gmail"], + transformsDir: "~/.openclaw/hooks/transforms", + mappings: [ + { + match: { path: "gmail" }, + action: "agent", + agentId: "hooks", + wakeMode: "now", + name: "Gmail", + sessionKey: "hook:gmail:{{messages[0].id}}", + messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", + deliver: true, + channel: "last", + model: "openai/gpt-5.4-mini", + }, + ], + }, +} +``` + +認証: `Authorization: Bearer ` または `x-openclaw-token: `。 +クエリ文字列のhook tokenは拒否されます。 + +検証と安全性に関する注意: + +- `hooks.enabled=true` には空でない `hooks.token` が必要です。 +- `hooks.token` は `gateway.auth.token` と**異なる**必要があります。Gateway tokenの再利用は拒否されます。 +- `hooks.path` は `/` にできません。`/hooks` のような専用サブパスを使用してください。 +- `hooks.allowRequestSessionKey=true` の場合は、`hooks.allowedSessionKeyPrefixes` を制約してください（例: `["hook:"]`）。 + +**エンドポイント:** + +- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` +- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` + - リクエストペイロードの `sessionKey` は、`hooks.allowRequestSessionKey=true`（デフォルト: `false`）の場合にのみ受け付けられます。 +- `POST /hooks/` → `hooks.mappings` 経由で解決されます + + + +- `match.path` は `/hooks` の後のサブパスに一致します（例: `/hooks/gmail` → `gmail`）。 +- `match.source` は、汎用パス向けにペイロードフィールドに一致します。 +- `{{messages[0].subject}}` のようなテンプレートはペイロードから読み取ります。 +- `transform` は、hook actionを返すJS/TSモジュールを指せます。 + - `transform.module` は相対パスである必要があり、`hooks.transformsDir` 内にとどまります（絶対パスやトラバーサルは拒否されます）。 +- `agentId` は特定のagentへルーティングします。未知のIDはデフォルトへフォールバックします。 +- `allowedAgentIds`: 明示的なルーティングを制限します（`*` または省略 = すべて許可、`[]` = すべて拒否）。 +- `defaultSessionKey`: 明示的な `sessionKey` がないhook agent実行向けの任意の固定セッションキー。 +- `allowRequestSessionKey`: `/hooks/agent` 呼び出し元が `sessionKey` を設定できるようにします（デフォルト: `false`）。 +- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（リクエスト + mapping）向けの任意のプレフィックス許可リスト。例: `["hook:"]`。 +- `deliver: true` は最終返信をchannelへ送信します。`channel` のデフォルトは `last` です。 +- `model` はこのhook実行のLLMを上書きします（モデルカタログが設定されている場合は許可されている必要があります）。 + + + +### Gmail連携 + +```json5 +{ + hooks: { + gmail: { + account: "openclaw@gmail.com", + topic: "projects//topics/gog-gmail-watch", + subscription: "gog-gmail-watch-push", + pushToken: "shared-push-token", + hookUrl: "http://127.0.0.1:18789/hooks/gmail", + includeBody: true, + maxBytes: 20000, + renewEveryMinutes: 720, + serve: { bind: "127.0.0.1", port: 8788, path: "/" }, + tailscale: { mode: "funnel", path: "/gmail-pubsub" }, + model: "openrouter/meta-llama/llama-3.3-70b-instruct:free", + thinking: "off", + }, + }, +} +``` + +- 設定されている場合、Gatewayは起動時に自動で `gog gmail watch serve` を開始します。無効にするには `OPENCLAW_SKIP_GMAIL_WATCHER=1` を設定してください。 +- Gatewayと並行して別の `gog gmail watch serve` を実行しないでください。 + +--- + +## Canvas host + +```json5 +{ + canvasHost: { + root: "~/.openclaw/workspace/canvas", + liveReload: true, + // enabled: false, // または OPENCLAW_SKIP_CANVAS_HOST=1 + }, +} +``` + +- agentが編集可能なHTML/CSS/JSとA2UIを、Gateway port配下のHTTPで配信します: + - `http://:/__openclaw__/canvas/` + - `http://:/__openclaw__/a2ui/` +- ローカル専用: `gateway.bind: "loopback"`（デフォルト）のままにしてください。 +- loopback以外のbindでは、canvasルートには他のGateway HTTPサーフェスと同様にGateway auth（token/password/trusted-proxy）が必要です。 +- Node WebViewは通常authヘッダーを送信しません。nodeがペアリングされ接続されると、Gatewayはcanvas/A2UIアクセス用のnodeスコープcapability URLを通知します。 +- Capability URLはアクティブなnode WSセッションに紐づけられ、短時間で期限切れになります。IPベースのフォールバックは使用されません。 +- 配信HTMLにlive-reloadクライアントを注入します。 +- 空の場合はスターター `index.html` を自動作成します。 +- A2UIも `/__openclaw__/a2ui/` で配信します。 +- 変更にはgatewayの再起動が必要です。 +- 大きなディレクトリや `EMFILE` エラーの場合はlive reloadを無効にしてください。 + +--- + +## Discovery + +### mDNS（Bonjour） + +```json5 +{ + discovery: { + mdns: { + mode: "minimal", // minimal | full | off + }, + }, +} +``` + +- `minimal`（デフォルト）: TXTレコードから `cliPath` + `sshPort` を省略します。 +- `full`: `cliPath` + `sshPort` を含めます。 +- hostnameのデフォルトは `openclaw` です。`OPENCLAW_MDNS_HOSTNAME` で上書きします。 + +### 広域（DNS-SD） + +```json5 +{ + discovery: { + wideArea: { enabled: true }, + }, +} +``` + +`~/.openclaw/dns/` 配下にユニキャストDNS-SDゾーンを書き込みます。ネットワークをまたぐ検出には、DNSサーバー（推奨はCoreDNS）+ Tailscale split DNS と組み合わせてください。 + +セットアップ: `openclaw dns setup --apply`。 + +--- + +## Environment + +### `env`（インライン環境変数） + +```json5 +{ + env: { + OPENROUTER_API_KEY: "sk-or-...", + vars: { + GROQ_API_KEY: "gsk-...", + }, + shellEnv: { + enabled: true, + timeoutMs: 15000, + }, + }, +} +``` + +- インライン環境変数は、process環境にキーが存在しない場合にのみ適用されます。 +- `.env` ファイル: カレントワーキングディレクトリの `.env` + `~/.openclaw/.env`（どちらも既存変数を上書きしません）。 +- `shellEnv`: ログインshellプロファイルから、不足している想定キーを取り込みます。 +- 完全な優先順位は [Environment](/ja-JP/help/environment) を参照してください。 + +### 環境変数置換 + +任意のconfig文字列で `${VAR_NAME}` を使って環境変数を参照できます: + +```json5 +{ + gateway: { + auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" }, + }, +} +``` + +- 一致するのは大文字名のみです: `[A-Z_][A-Z0-9_]*`。 +- 変数が欠落している、または空の場合、config読み込み時にエラーになります。 +- リテラルの `${VAR}` にしたい場合は `$${VAR}` でエスケープします。 +- `$include` でも動作します。 + +--- + +## Secrets + +SecretRefは追加的です。平文値も引き続き使えます。 + +### `SecretRef` + +1つのオブジェクト形状を使用します: + +```json5 +{ source: "env" | "file" | "exec", provider: "default", id: "..." } +``` + +検証: + +- `provider` パターン: `^[a-z][a-z0-9_-]{0,63}$` +- `source: "env"` のidパターン: `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` のid: 絶対JSONポインター（例: `"/providers/openai/apiKey"`） +- `source: "exec"` のidパターン: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `source: "exec"` のidには、`.` または `..` のスラッシュ区切りパスセグメントを含めてはいけません（例: `a/../b` は拒否されます） + +### 対応する認証情報サーフェス + +- 正規マトリクス: [SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface) +- `secrets apply` は、対応する `openclaw.json` の認証情報パスを対象にします。 +- `auth-profiles.json` のrefも、ランタイム解決と監査対象に含まれます。 + +### Secret provider設定 + +```json5 +{ + secrets: { + providers: { + default: { source: "env" }, // 任意の明示的env provider + filemain: { + source: "file", + path: "~/.openclaw/secrets.json", + mode: "json", + timeoutMs: 5000, + }, + vault: { + source: "exec", + command: "/usr/local/bin/openclaw-vault-resolver", + passEnv: ["PATH", "VAULT_ADDR"], + }, + }, + defaults: { + env: "default", + file: "filemain", + exec: "vault", + }, + }, +} +``` + +注意: + +- `file` providerは `mode: "json"` と `mode: "singleValue"` をサポートします（singleValueモードでは `id` は `"value"` である必要があります）。 +- `exec` providerは絶対 `command` パスを必要とし、stdin/stdout上のプロトコルペイロードを使用します。 +- デフォルトでは、symlinkのcommandパスは拒否されます。解決後のターゲットパスを検証したうえでsymlinkパスを許可するには `allowSymlinkCommand: true` を設定します。 +- `trustedDirs` が設定されている場合、trusted-dirチェックは解決後のターゲットパスに適用されます。 +- `exec` の子環境はデフォルトで最小限です。必要な変数は `passEnv` で明示的に渡してください。 +- SecretRefはアクティベーション時にメモリー内スナップショットへ解決され、その後のリクエスト経路はそのスナップショットのみを読み取ります。 +- アクティブサーフェスフィルタリングはアクティベーション中に適用されます。有効なサーフェス上の未解決refは起動/リロードを失敗させ、非アクティブサーフェスは診断付きでスキップされます。 + +--- + +## Authストレージ + +```json5 +{ + auth: { + profiles: { + "anthropic:default": { provider: "anthropic", mode: "api_key" }, + "anthropic:work": { provider: "anthropic", mode: "api_key" }, + "openai-codex:personal": { provider: "openai-codex", mode: "oauth" }, + }, + order: { + anthropic: ["anthropic:default", "anthropic:work"], + "openai-codex": ["openai-codex:personal"], + }, + }, +} +``` + +- agentごとのprofileは `/auth-profiles.json` に保存されます。 +- `auth-profiles.json` は、静的認証情報モード向けに値レベルref（`api_key` の `keyRef`、`token` の `tokenRef`）をサポートします。 +- OAuthモードprofile（`auth.profiles..mode = "oauth"`）は、SecretRefバックエンドのauth-profile認証情報をサポートしません。 +- 静的ランタイム認証情報はメモリー内の解決済みスナップショットから取得され、レガシーな静的 `auth.json` エントリは見つかると削除されます。 +- レガシーOAuthは `~/.openclaw/credentials/oauth.json` からインポートされます。 +- [OAuth](/ja-JP/concepts/oauth) を参照してください。 +- Secretsランタイムの動作と `audit/configure/apply` ツール: [Secrets Management](/ja-JP/gateway/secrets)。 + +### `auth.cooldowns` + +```json5 +{ + auth: { + cooldowns: { + billingBackoffHours: 5, + billingBackoffHoursByProvider: { anthropic: 3, openai: 8 }, + billingMaxHours: 24, + authPermanentBackoffMinutes: 10, + authPermanentMaxMinutes: 60, + failureWindowHours: 24, + overloadedProfileRotations: 1, + overloadedBackoffMs: 0, + rateLimitedProfileRotations: 1, + }, + }, +} +``` + +- `billingBackoffHours`: 真の請求/残高不足エラーによりprofileが失敗したときの基本バックオフ時間（時間）（デフォルト: `5`）。明示的な請求文言は、`401`/`403` 応答でもここに分類されることがありますが、provider固有の文言マッチャーは引き続きそのproviderに限定されます（例: OpenRouterの `Key limit exceeded`）。再試行可能なHTTP `402` の利用ウィンドウまたは organization/workspace 支出上限メッセージは、代わりに `rate_limit` 経路に残ります。 +- `billingBackoffHoursByProvider`: 請求バックオフ時間の任意のproviderごとの上書き。 +- `billingMaxHours`: 請求バックオフの指数増加に対する上限時間（デフォルト: `24`）。 +- `authPermanentBackoffMinutes`: 高信頼な `auth_permanent` 失敗に対する基本バックオフ時間（分）（デフォルト: `10`）。 +- `authPermanentMaxMinutes`: `auth_permanent` バックオフ増加の上限時間（分）（デフォルト: `60`）。 +- `failureWindowHours`: バックオフカウンターに使うローリングウィンドウ時間（デフォルト: `24`）。 +- `overloadedProfileRotations`: 過負荷エラー時に、model fallbackへ切り替える前に行う同一provider auth-profileローテーションの最大回数（デフォルト: `1`）。`ModelNotReadyException` のようなprovider-busy形状はここに分類されます。 +- `overloadedBackoffMs`: 過負荷provider/profileローテーションを再試行する前の固定遅延（デフォルト: `0`）。 +- `rateLimitedProfileRotations`: レート制限エラー時に、model fallbackへ切り替える前に行う同一provider auth-profileローテーションの最大回数（デフォルト: `1`）。そのrate-limitバケットには、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` のようなprovider形状の文言も含まれます。 + +--- + +## Logging + +```json5 +{ + logging: { + level: "info", + file: "/tmp/openclaw/openclaw.log", + consoleLevel: "info", + consoleStyle: "pretty", // pretty | compact | json + redactSensitive: "tools", // off | tools + redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"], + }, +} +``` + +- デフォルトのログファイル: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 +- 安定したパスには `logging.file` を設定してください。 +- `consoleLevel` は `--verbose` のとき `debug` に上がります。 +- `maxFileBytes`: 書き込み抑止前の最大ログファイルサイズ（バイト）（正の整数。デフォルト: `524288000` = 500 MB）。本番デプロイでは外部ログローテーションを使用してください。 + +--- + +## Diagnostics + +```json5 +{ + diagnostics: { + enabled: true, + flags: ["telegram.*"], + stuckSessionWarnMs: 30000, + + otel: { + enabled: false, + endpoint: "https://otel-collector.example.com:4318", + protocol: "http/protobuf", // http/protobuf | grpc + headers: { "x-tenant-id": "my-org" }, + serviceName: "openclaw-gateway", + traces: true, + metrics: true, + logs: false, + sampleRate: 1.0, + flushIntervalMs: 5000, + }, + + cacheTrace: { + enabled: false, + filePath: "~/.openclaw/logs/cache-trace.jsonl", + includeMessages: true, + includePrompt: true, + includeSystem: true, + }, + }, +} +``` + +- `enabled`: instrumentation出力のマスタースイッチ（デフォルト: `true`）。 +- `flags`: 対象を絞ったログ出力を有効にするflag文字列の配列です（`"telegram.*"` や `"*"` のようなワイルドカードをサポート）。 +- `stuckSessionWarnMs`: セッションが処理中状態のままである間に、stuck-session警告を出すまでの経過時間しきい値（ms）。 +- `otel.enabled`: OpenTelemetryエクスポートパイプラインを有効にします（デフォルト: `false`）。 +- `otel.endpoint`: OTelエクスポート先collectorのURL。 +- `otel.protocol`: `"http/protobuf"`（デフォルト）または `"grpc"`。 +- `otel.headers`: OTelエクスポートリクエストとともに送信される追加のHTTP/gRPCメタデータヘッダー。 +- `otel.serviceName`: リソース属性用のサービス名。 +- `otel.traces` / `otel.metrics` / `otel.logs`: trace、metrics、またはlogエクスポートを有効にします。 +- `otel.sampleRate`: traceサンプリング率 `0`–`1`。 +- `otel.flushIntervalMs`: 定期telemetryフラッシュ間隔（ms）。 +- `cacheTrace.enabled`: 埋め込み実行向けにcache traceスナップショットを記録します（デフォルト: `false`）。 +- `cacheTrace.filePath`: cache trace JSONLの出力パス（デフォルト: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: cache trace出力に何を含めるかを制御します（すべてデフォルト: `true`）。 + +--- + +## Update + +```json5 +{ + update: { + channel: "stable", // stable | beta | dev + checkOnStart: true, + + auto: { + enabled: false, + stableDelayHours: 6, + stableJitterHours: 12, + betaCheckIntervalHours: 1, + }, + }, +} +``` + +- `channel`: npm/gitインストール向けのリリースchannel — `"stable"`、`"beta"`、または `"dev"`。 +- `checkOnStart`: gateway起動時にnpm更新を確認します（デフォルト: `true`）。 +- `auto.enabled`: packageインストール向けのバックグラウンド自動更新を有効にします（デフォルト: `false`）。 +- `auto.stableDelayHours`: stable channelの自動適用までの最小遅延時間（デフォルト: `6`、最大: `168`）。 +- `auto.stableJitterHours`: stable channelロールアウトの追加分散ウィンドウ時間（デフォルト: `12`、最大: `168`）。 +- `auto.betaCheckIntervalHours`: beta channelの確認を実行する頻度（時間）（デフォルト: `1`、最大: `24`）。 + +--- + +## ACP + +```json5 +{ + acp: { + enabled: false, + dispatch: { enabled: true }, + backend: "acpx", + defaultAgent: "main", + allowedAgents: ["main", "ops"], + maxConcurrentSessions: 10, + + stream: { + coalesceIdleMs: 50, + maxChunkChars: 1000, + repeatSuppression: true, + deliveryMode: "live", // live | final_only + hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph + maxOutputChars: 50000, + maxSessionUpdateChars: 500, + }, + + runtime: { + ttlMinutes: 30, + }, + }, +} +``` + +- `enabled`: グローバルACP機能ゲート（デフォルト: `false`）。 +- `dispatch.enabled`: ACPセッションターンディスパッチ向けの独立ゲート（デフォルト: `true`）。ACPコマンドは利用可能なまま、実行だけをブロックしたい場合は `false` に設定します。 +- `backend`: デフォルトのACP runtime backend id（登録済みACP runtime pluginと一致している必要があります）。 +- `defaultAgent`: spawn時に明示ターゲットが指定されない場合のフォールバックACP対象agent id。 +- `allowedAgents`: ACP runtimeセッションで許可されるagent idの許可リスト。空の場合、追加制限はありません。 +- `maxConcurrentSessions`: 同時にアクティブにできるACPセッションの最大数。 +- `stream.coalesceIdleMs`: ストリーミングテキスト向けのアイドルフラッシュ時間（ms）。 +- `stream.maxChunkChars`: ストリーミングされたブロック投影を分割する前の最大チャンクサイズ。 +- `stream.repeatSuppression`: ターンごとに繰り返されるstatus/tool行を抑制します（デフォルト: `true`）。 +- `stream.deliveryMode`: `"live"` は増分的にストリーミングし、`"final_only"` はターン終端イベントまでバッファします。 +- `stream.hiddenBoundarySeparator`: 非表示toolイベント後、可視テキストの前に入れる区切り文字（デフォルト: `"paragraph"`）。 +- `stream.maxOutputChars`: ACPターンごとに投影されるassistant出力の最大文字数。 +- `stream.maxSessionUpdateChars`: 投影されるACP status/update行の最大文字数。 +- `stream.tagVisibility`: ストリーミングイベントに対する、tag名から真偽値の可視性上書きへの記録。 +- `runtime.ttlMinutes`: ACPセッションworkerがクリーンアップ対象になるまでのアイドルTTL（分）。 +- `runtime.installCommand`: ACP runtime環境をブートストラップするときに実行する任意のインストールコマンド。 + +--- + +## CLI + +```json5 +{ + cli: { + banner: { + taglineMode: "off", // random | default | off + }, + }, +} +``` + +- `cli.banner.taglineMode` はbannerのtaglineスタイルを制御します: + - `"random"`（デフォルト）: ローテーションするユーモラス/季節限定tagline。 + - `"default"`: 固定の中立tagline（`All your chats, one OpenClaw.`）。 + - `"off"`: taglineテキストなし（bannerのタイトル/バージョンは引き続き表示）。 +- banner全体を隠すには（taglineだけでなく）、環境変数 `OPENCLAW_HIDE_BANNER=1` を設定してください。 + +--- + +## ウィザード + +CLIのガイド付きセットアップフロー（`onboard`、`configure`、`doctor`）によって書き込まれるメタデータ: + +```json5 +{ + wizard: { + lastRunAt: "2026-01-01T00:00:00.000Z", + lastRunVersion: "2026.1.4", + lastRunCommit: "abc1234", + lastRunCommand: "configure", + lastRunMode: "local", + }, +} +``` + +--- + +## Identity + +[Agent defaults](#agent-defaults) の `agents.list` identityフィールドを参照してください。 + +--- + +## Bridge（legacy、削除済み） + +現在のbuildにはTCP bridgeは含まれていません。nodeはGateway WebSocket経由で接続します。`bridge.*` キーはもはやconfig schemaの一部ではありません（削除するまで検証は失敗します。`openclaw doctor --fix` で未知のキーを除去できます）。 + + + +```json +{ + "bridge": { + "enabled": true, + "port": 18790, + "bind": "tailnet", + "tls": { + "enabled": true, + "autoGenerate": true + } + } +} +``` + + + +--- + +## Cron + +```json5 +{ + cron: { + enabled: true, + maxConcurrentRuns: 2, + webhook: "https://example.invalid/legacy", // 保存済みの notify:true ジョブ向けの非推奨フォールバック + webhookToken: "replace-with-dedicated-token", // 送信webhook認証用の任意のbearer token + sessionRetention: "24h", // 期間文字列または false + runLog: { + maxBytes: "2mb", // デフォルト 2_000_000 bytes + keepLines: 2000, // デフォルト 2000 + }, + }, +} +``` + +- `sessionRetention`: 完了した分離cron実行セッションを `sessions.json` から剪定するまで保持する期間です。アーカイブされた削除済みcronトランスクリプトのクリーンアップも制御します。デフォルト: `24h`。無効にするには `false` を設定します。 +- `runLog.maxBytes`: 剪定前の実行ログファイルごとの最大サイズ（`cron/runs/.jsonl`）。デフォルト: `2_000_000` bytes。 +- `runLog.keepLines`: 実行ログ剪定が発動したときに保持する最新行数。デフォルト: `2000`。 +- `webhookToken`: cron webhook POST配信（`delivery.mode = "webhook"`）で使用するbearer tokenです。省略時はauthヘッダーは送信されません。 +- `webhook`: 非推奨のレガシーフォールバックwebhook URL（http/https）で、依然として `notify: true` を持つ保存済みジョブにのみ使用されます。 + +### `cron.retry` + +```json5 +{ + cron: { + retry: { + maxAttempts: 3, + backoffMs: [30000, 60000, 300000], + retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"], + }, + }, +} +``` + +- `maxAttempts`: 一過性エラー時に単発ジョブへ行う最大再試行回数（デフォルト: `3`、範囲: `0`–`10`）。 +- `backoffMs`: 各再試行で使用するバックオフ遅延（ms）の配列（デフォルト: `[30000, 60000, 300000]`、1〜10エントリ）。 +- `retryOn`: 再試行を発動するエラータイプ — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略時は、すべての一過性タイプで再試行します。 + +単発cronジョブにのみ適用されます。定期実行ジョブでは別の失敗処理を使用します。 + +### `cron.failureAlert` + +```json5 +{ + cron: { + failureAlert: { + enabled: false, + after: 3, + cooldownMs: 3600000, + mode: "announce", + accountId: "main", + }, + }, +} +``` + +- `enabled`: cronジョブ向けの失敗アラートを有効にします（デフォルト: `false`）。 +- `after`: アラート発火前の連続失敗回数（正の整数、最小: `1`）。 +- `cooldownMs`: 同じジョブに対する繰り返しアラート間の最小時間（ms）（非負整数）。 +- `mode`: 配信モード — `"announce"` はchannelメッセージで送信し、`"webhook"` は設定済みwebhookへPOSTします。 +- `accountId`: アラート配信をスコープする任意のアカウントまたはchannel id。 + +### `cron.failureDestination` + +```json5 +{ + cron: { + failureDestination: { + mode: "announce", + channel: "last", + to: "channel:C1234567890", + accountId: "main", + }, + }, +} +``` + +- すべてのジョブにまたがるcron失敗通知のデフォルト送信先です。 +- `mode`: `"announce"` または `"webhook"`。十分なターゲットデータがある場合、デフォルトは `"announce"` です。 +- `channel`: announce配信向けのchannel上書き。`"last"` は最後に使用した配信channelを再利用します。 +- `to`: 明示的なannounceターゲットまたはwebhook URL。webhookモードでは必須です。 +- `accountId`: 配信向けの任意のアカウント上書き。 +- ジョブごとの `delivery.failureDestination` がこのグローバルデフォルトを上書きします。 +- グローバルにもジョブごとにも失敗送信先が設定されていない場合、すでに `announce` で配信するジョブは、失敗時にそのプライマリannounceターゲットへフォールバックします。 +- `delivery.failureDestination` は、ジョブのプライマリ `delivery.mode` が `"webhook"` でない限り、`sessionTarget="isolated"` ジョブでのみサポートされます。 + +[Cron Jobs](/ja-JP/automation/cron-jobs) を参照してください。分離cron実行は [background tasks](/ja-JP/automation/tasks) として追跡されます。 + +--- + +## Mediaモデルテンプレート変数 + +`tools.media.models[].args` で展開されるテンプレートプレースホルダー: + +| Variable | 説明 | +| ------------------ | ----------------------------------------------- | +| `{{Body}}` | 完全な受信メッセージ本文 | +| `{{RawBody}}` | 生の本文（履歴/送信者ラッパーなし） | +| `{{BodyStripped}}` | グループメンションを除去した本文 | +| `{{From}}` | 送信者識別子 | +| `{{To}}` | 送信先識別子 | +| `{{MessageSid}}` | channelメッセージid | +| `{{SessionId}}` | 現在のセッションUUID | +| `{{IsNewSession}}` | 新しいセッションが作成されたとき `"true"` | +| `{{MediaUrl}}` | 受信メディアの擬似URL | +| `{{MediaPath}}` | ローカルメディアパス | +| `{{MediaType}}` | メディアタイプ（image/audio/document/…） | +| `{{Transcript}}` | 音声トランスクリプト | +| `{{Prompt}}` | CLIエントリ向けに解決されたメディアprompt | +| `{{MaxChars}}` | CLIエントリ向けに解決された最大出力文字数 | +| `{{ChatType}}` | `"direct"` または `"group"` | +| `{{GroupSubject}}` | グループ件名（ベストエフォート） | +| `{{GroupMembers}}` | グループメンバープレビュー（ベストエフォート） | +| `{{SenderName}}` | 送信者表示名（ベストエフォート） | +| `{{SenderE164}}` | 送信者電話番号（ベストエフォート） | +| `{{Provider}}` | providerヒント（whatsapp、telegram、discordなど） | + +--- + +## Config includes（`$include`） + +configを複数ファイルに分割できます: + +```json5 +// ~/.openclaw/openclaw.json +{ + gateway: { port: 18789 }, + agents: { $include: "./agents.json5" }, + broadcast: { + $include: ["./clients/mueller.json5", "./clients/schmidt.json5"], + }, +} +``` + +**マージ動作:** + +- 単一ファイル: 含んでいるオブジェクト全体を置き換えます。 +- ファイル配列: 順番にdeep mergeされます（後のものが前のものを上書き）。 +- 兄弟キー: includeの後にマージされます（includeされた値を上書き）。 +- ネストしたinclude: 最大10階層まで。 +- パス: include元ファイルからの相対で解決されますが、トップレベルconfigディレクトリ（`openclaw.json` の `dirname`）内にとどまる必要があります。絶対/`../` 形式も、その境界内に解決される場合にのみ許可されます。 +- エラー: ファイル欠落、パースエラー、循環includeに対して明確なメッセージを出します。 + +--- + +_関連: [Configuration](/ja-JP/gateway/configuration) · [Configuration Examples](/ja-JP/gateway/configuration-examples) · [Doctor](/ja-JP/gateway/doctor)_ diff --git a/docs/ja-JP/gateway/configuration.md b/docs/ja-JP/gateway/configuration.md index 0688b8c74..4efa392cc 100644 --- a/docs/ja-JP/gateway/configuration.md +++ b/docs/ja-JP/gateway/configuration.md @@ -1,36 +1,36 @@ --- read_when: - - OpenClaw を初めて設定するとき - - 一般的な設定パターンを探しているとき - - 特定の設定セクションに移動したいとき -summary: 設定の概要：一般的なタスク、クイックセットアップ、完全なリファレンスへのリンク + - OpenClaw を初めてセットアップすること + - 一般的な設定パターンを探すこと + - 特定の設定セクションに移動すること +summary: '設定の概要: 一般的なタスク、クイックセットアップ、および完全なリファレンスへのリンク' title: 設定 x-i18n: - generated_at: "2026-04-08T06:02:30Z" + generated_at: "2026-04-11T02:44:41Z" model: gpt-5.4 provider: openai - source_hash: 199a1e515bd4003319e71593a2659bb883299a76ff67e273d92583df03c96604 + source_hash: e874be80d11b9123cac6ce597ec02667fbc798f622a076f68535a1af1f0e399c source_path: gateway/configuration.md workflow: 15 --- # 設定 -OpenClaw は `~/.openclaw/openclaw.json` から任意の **JSON5** 設定を読み込みます。 +OpenClaw は、`~/.openclaw/openclaw.json` から任意の **JSON5** 設定を読み込みます。 -ファイルが存在しない場合、OpenClaw は安全なデフォルト設定を使用します。設定を追加する一般的な理由は次のとおりです。 +ファイルが存在しない場合、OpenClaw は安全なデフォルト値を使用します。設定を追加する一般的な理由は次のとおりです。 - チャンネルを接続し、誰がボットにメッセージを送れるかを制御する -- モデル、ツール、サンドボックス化、または自動化（cron、hooks）を設定する -- セッション、メディア、ネットワーク、または UI を調整する +- モデル、ツール、サンドボックス化、自動化（cron、hooks）を設定する +- セッション、メディア、ネットワーク、UI を調整する -利用可能なすべてのフィールドについては、[完全なリファレンス](/ja-JP/gateway/configuration-reference)を参照してください。 +利用可能なすべてのフィールドについては、[完全なリファレンス](/ja-JP/gateway/configuration-reference) を参照してください。 -**設定が初めてですか？** 対話形式のセットアップには `openclaw onboard` から始めるか、完全なコピーペースト用設定を掲載した[設定例](/ja-JP/gateway/configuration-examples)ガイドを確認してください。 +**設定が初めてですか？** 対話型セットアップには `openclaw onboard` から始めるか、完全なコピー＆ペースト用設定をまとめた [設定例](/ja-JP/gateway/configuration-examples) ガイドを確認してください。 -## 最小設定 +## 最小構成 ```json5 // ~/.openclaw/openclaw.json @@ -45,8 +45,8 @@ OpenClaw は `~/.openclaw/openclaw.json` から任意の ```bash - openclaw onboard # full onboarding flow - openclaw configure # config wizard + openclaw onboard # 完全なオンボーディングフロー + openclaw configure # 設定ウィザード ``` @@ -58,58 +58,46 @@ OpenClaw は `~/.openclaw/openclaw.json` から任意の [http://127.0.0.1:18789](http://127.0.0.1:18789) を開き、**Config** タブを使用します。 - Control UI は、利用可能な場合はフィールドの - `title` / `description` ドキュメントメタデータに加えて、プラグインとチャンネルのスキーマも含めて、 - ライブ設定スキーマからフォームをレンダリングし、 - 逃げ道として **Raw JSON** エディターも提供します。詳細確認用の - UI やその他のツール向けに、gateway は `config.schema.lookup` も公開しており、 - 1 つのパス範囲のスキーマノードと、その直下の子サマリーを取得できます。 + Control UI は、ライブ設定スキーマからフォームをレンダリングします。これには、利用可能な場合はフィールドの + `title` / `description` のドキュメントメタデータに加えて、plugin と channel のスキーマも含まれ、 + エスケープハッチとして **Raw JSON** エディターも提供されます。ドリルダウン UI やその他のツール向けに、 + Gateway は `config.schema.lookup` も公開しており、1 つのパスにスコープされたスキーマノードと、 + その直下の子要約を取得できます。 - `~/.openclaw/openclaw.json` を直接編集します。Gateway はファイルを監視し、自動的に変更を適用します（[ホットリロード](#config-hot-reload)を参照）。 + `~/.openclaw/openclaw.json` を直接編集します。Gateway はこのファイルを監視し、変更を自動的に適用します（[ホットリロード](#config-hot-reload) を参照）。 ## 厳格な検証 -OpenClaw は、スキーマに完全に一致する設定のみを受け付けます。不明なキー、不正な型、または無効な値があると、Gateway は**起動を拒否**します。唯一のルートレベル例外は `$schema`（文字列）で、エディターが JSON Schema メタデータを付与できるようにするためのものです。 +OpenClaw は、スキーマに完全に一致する設定のみを受け入れます。不明なキー、不正な型、無効な値があると、Gateway は**起動を拒否**します。ルートレベルの唯一の例外は `$schema`（文字列）で、エディターが JSON Schema メタデータを付与できるようにするためのものです。 -スキーマツールに関する注意： +スキーマツールに関する注記: -- `openclaw config schema` は、Control UI と - 設定検証で使用されるのと同じ JSON Schema ファミリーを出力します。 -- そのスキーマ出力は、`openclaw.json` の - 正式な機械可読コントラクトとして扱ってください。この概要と設定リファレンスはそれを要約したものです。 -- フィールドの `title` と `description` の値は、 - エディターやフォームツール向けにスキーマ出力へ引き継がれます。 -- ネストされたオブジェクト、ワイルドカード（`*`）、配列項目（`[]`）のエントリーは、 - 一致するフィールドドキュメントが存在する場合、同じ - ドキュメントメタデータを継承します。 -- `anyOf` / `oneOf` / `allOf` の合成ブランチも同じドキュメント - メタデータを継承するため、union / intersection の各バリアントでも同じフィールドヘルプが維持されます。 -- `config.schema.lookup` は、正規化された 1 つの設定パスと、 - 浅いスキーマノード（`title`、`description`、`type`、`enum`、`const`、一般的な境界、 - および類似の検証フィールド）、一致した UI ヒントメタデータ、および - 詳細確認ツール向けの直下の子サマリーを返します。 -- 実行時のプラグイン / チャンネルスキーマは、gateway が - 現在のマニフェストレジストリを読み込める場合にマージされます。 -- `pnpm config:docs:check` は、ドキュメント向け設定ベースライン - アーティファクトと現在のスキーマサーフェスのずれを検出します。 +- `openclaw config schema` は、Control UI と設定検証で使用されるものと同じ JSON Schema ファミリーを出力します。 +- そのスキーマ出力は、`openclaw.json` の正規の機械可読コントラクトとして扱ってください。この概要と設定リファレンスはその要約です。 +- フィールドの `title` と `description` の値は、エディターやフォームツール向けにスキーマ出力へ引き継がれます。 +- ネストしたオブジェクト、ワイルドカード（`*`）、配列要素（`[]`）の各エントリは、一致するフィールドドキュメントが存在する場合、同じドキュメントメタデータを継承します。 +- `anyOf` / `oneOf` / `allOf` の合成ブランチも同じドキュメントメタデータを継承するため、union/intersection の各バリアントでも同じフィールドヘルプが維持されます。 +- `config.schema.lookup` は、正規化された 1 つの設定パスについて、浅いスキーマノード（`title`、`description`、`type`、`enum`、`const`、一般的な境界値、および類似の検証フィールド）、一致した UI ヒントメタデータ、そしてドリルダウンツール向けの直下の子要約を返します。 +- 実行時の plugin/channel スキーマは、gateway が現在のマニフェストレジストリを読み込める場合にマージされます。 +- `pnpm config:docs:check` は、ドキュメント向け設定ベースライン成果物と現在のスキーマサーフェスとのドリフトを検出します。 -検証に失敗した場合： +検証に失敗した場合: - Gateway は起動しません -- 診断コマンドのみ動作します（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`） +- 診断コマンドのみが動作します（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`） - 正確な問題を確認するには `openclaw doctor` を実行します - 修復を適用するには `openclaw doctor --fix`（または `--yes`）を実行します ## 一般的なタスク - - 各チャンネルには、`channels.` の下に独自の設定セクションがあります。設定手順については、各チャンネル専用ページを参照してください。 + + 各チャンネルには、`channels.` の下に専用の設定セクションがあります。セットアップ手順については、各チャンネル専用ページを参照してください。 - [WhatsApp](/ja-JP/channels/whatsapp) — `channels.whatsapp` - [Telegram](/ja-JP/channels/telegram) — `channels.telegram` @@ -131,7 +119,7 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け enabled: true, botToken: "123:abc", dmPolicy: "pairing", // pairing | allowlist | open | disabled - allowFrom: ["tg:123"], // only for allowlist/open + allowFrom: ["tg:123"], // allowlist/open の場合のみ }, }, } @@ -159,30 +147,30 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - - `agents.defaults.models` はモデルカタログを定義し、`/model` の許可リストとして機能します。 - - モデル参照には `provider/model` 形式を使用します（例：`anthropic/claude-opus-4-6`）。 - - `agents.defaults.imageMaxDimensionPx` は transcript / tool 画像の縮小を制御します（デフォルトは `1200`）。値を小さくすると、スクリーンショットが多い実行で vision-token の使用量が通常は減ります。 - - チャット内でのモデル切り替えについては[Models CLI](/ja-JP/concepts/models)を、認証ローテーションとフォールバック動作については[Model Failover](/ja-JP/concepts/model-failover)を参照してください。 - - カスタム / セルフホスト型プロバイダーについては、リファレンス内の[Custom providers](/ja-JP/gateway/configuration-reference#custom-providers-and-base-urls)を参照してください。 + - `agents.defaults.models` はモデルカタログを定義し、`/model` の許可リストとしても機能します。 + - モデル参照は `provider/model` 形式を使用します（例: `anthropic/claude-opus-4-6`）。 + - `agents.defaults.imageMaxDimensionPx` は transcript/tool 画像の縮小サイズを制御します（デフォルトは `1200`）。値を小さくすると、スクリーンショットの多い実行で vision token 使用量を減らせることが一般的です。 + - チャット中のモデル切り替えについては [Models CLI](/ja-JP/concepts/models) を、認証ローテーションとフォールバック動作については [Model Failover](/ja-JP/concepts/model-failover) を参照してください。 + - カスタム/セルフホスト型 provider については、リファレンスの [Custom providers](/ja-JP/gateway/configuration-reference#custom-providers-and-base-urls) を参照してください。 - DM アクセスは、チャンネルごとに `dmPolicy` で制御されます。 + DM アクセスは `dmPolicy` によってチャンネルごとに制御されます。 - - `"pairing"`（デフォルト）：未知の送信者は承認用のワンタイムペアリングコードを受け取る - - `"allowlist"`：`allowFrom` 内の送信者（またはペア済み許可ストア）のみ - - `"open"`：すべての受信 DM を許可する（`allowFrom: ["*"]` が必要） - - `"disabled"`：すべての DM を無視する + - `"pairing"`（デフォルト）: 未知の送信者には承認用の一度限りのペアリングコードが送られます + - `"allowlist"`: `allowFrom`（またはペア済みの許可ストア）に含まれる送信者のみ + - `"open"`: すべての受信 DM を許可します（`allowFrom: ["*"]` が必要） + - `"disabled"`: すべての DM を無視します - グループについては、`groupPolicy` + `groupAllowFrom` またはチャンネル固有の許可リストを使用します。 + グループでは、`groupPolicy` + `groupAllowFrom` またはチャンネル固有の許可リストを使用します。 - チャンネルごとの詳細は、[完全なリファレンス](/ja-JP/gateway/configuration-reference#dm-and-group-access)を参照してください。 + チャンネルごとの詳細については、[完全なリファレンス](/ja-JP/gateway/configuration-reference#dm-and-group-access) を参照してください。 - - グループメッセージはデフォルトで**メンション必須**です。エージェントごとにパターンを設定します。 + + グループメッセージはデフォルトで**メンション必須**です。agent ごとにパターンを設定します。 ```json5 { @@ -204,16 +192,15 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - - **メタデータメンション**：ネイティブの @-mention（WhatsApp のタップしてメンション、Telegram の @bot など） - - **テキストパターン**：`mentionPatterns` 内の安全な regex パターン - - チャンネルごとの上書きと self-chat モードについては、[完全なリファレンス](/ja-JP/gateway/configuration-reference#group-chat-mention-gating)を参照してください。 + - **メタデータメンション**: ネイティブの @ メンション（WhatsApp のタップしてメンション、Telegram の @bot など） + - **テキストパターン**: `mentionPatterns` 内の安全な regex パターン + - チャンネルごとの上書きや self-chat モードについては、[完全なリファレンス](/ja-JP/gateway/configuration-reference#group-chat-mention-gating) を参照してください。 - - 共通のベースラインには `agents.defaults.skills` を使い、その後 - `agents.list[].skills` で特定の - エージェントを上書きします。 + + 共有ベースラインには `agents.defaults.skills` を使用し、その後 + 特定の agent を `agents.list[].skills` で上書きします。 ```json5 { @@ -222,24 +209,24 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け skills: ["github", "weather"], }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // github, weather を継承 + { id: "docs", skills: ["docs-search"] }, // defaults を置き換える + { id: "locked-down", skills: [] }, // Skills なし ], }, } ``` - デフォルトで Skills を無制限にするには、`agents.defaults.skills` を省略します。 - - デフォルトを継承するには、`agents.list[].skills` を省略します。 - - Skills をなしにするには、`agents.list[].skills: []` を設定します。 - - [Skills](/ja-JP/tools/skills)、[Skills 設定](/ja-JP/tools/skills-config)、および - [設定リファレンス](/ja-JP/gateway/configuration-reference#agentsdefaultsskills)を参照してください。 + - defaults を継承するには、`agents.list[].skills` を省略します。 + - Skills を無効にするには、`agents.list[].skills: []` を設定します。 + - [Skills](/ja-JP/tools/skills)、[Skills config](/ja-JP/tools/skills-config)、および + [設定リファレンス](/ja-JP/gateway/configuration-reference#agents-defaults-skills) を参照してください。 - - 停滞しているように見えるチャンネルを gateway がどの程度積極的に再起動するかを制御します。 + + stale に見えるチャンネルを gateway がどの程度積極的に再起動するかを制御します。 ```json5 { @@ -262,19 +249,19 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け ``` - ヘルス監視による再起動をグローバルに無効化するには、`gateway.channelHealthCheckMinutes: 0` を設定します。 - - `channelStaleEventThresholdMinutes` は、チェック間隔以上にする必要があります。 - - グローバル監視を無効にせずに特定のチャンネルまたはアカウントの自動再起動を無効にするには、`channels..healthMonitor.enabled` または `channels..accounts..healthMonitor.enabled` を使用します。 - - 運用上のデバッグについては[Health Checks](/ja-JP/gateway/health)を、すべてのフィールドについては[完全なリファレンス](/ja-JP/gateway/configuration-reference#gateway)を参照してください。 + - `channelStaleEventThresholdMinutes` は、チェック間隔以上である必要があります。 + - グローバル監視を無効にせずに 1 つのチャンネルまたはアカウントだけ自動再起動を無効化するには、`channels..healthMonitor.enabled` または `channels..accounts..healthMonitor.enabled` を使用します。 + - 運用上のデバッグについては [Health Checks](/ja-JP/gateway/health) を、すべてのフィールドについては [完全なリファレンス](/ja-JP/gateway/configuration-reference#gateway) を参照してください。 - セッションは、会話の継続性と分離を制御します。 + セッションは会話の継続性と分離を制御します。 ```json5 { session: { - dmScope: "per-channel-peer", // recommended for multi-user + dmScope: "per-channel-peer", // 複数ユーザー向けに推奨 threadBindings: { enabled: true, idleHours: 24, @@ -290,14 +277,14 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け ``` - `dmScope`: `main`（共有）| `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: スレッドに紐づくセッションルーティングのグローバルデフォルト（Discord は `/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` をサポート） - - スコープ、ID リンク、送信ポリシーについては[セッション管理](/ja-JP/concepts/session)を参照してください。 - - すべてのフィールドについては[完全なリファレンス](/ja-JP/gateway/configuration-reference#session)を参照してください。 + - `threadBindings`: スレッドに紐づくセッションルーティングのグローバルデフォルトです（Discord は `/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` をサポートします）。 + - スコープ、ID リンク、送信ポリシーについては [Session Management](/ja-JP/concepts/session) を参照してください。 + - すべてのフィールドについては [完全なリファレンス](/ja-JP/gateway/configuration-reference#session) を参照してください。 - エージェントセッションを分離された Docker コンテナで実行します。 + 分離された Docker コンテナ内で agent セッションを実行します。 ```json5 { @@ -312,16 +299,16 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - 最初にイメージをビルドします：`scripts/sandbox-setup.sh` + まずイメージをビルドします: `scripts/sandbox-setup.sh` - 完全なガイドについては[サンドボックス化](/ja-JP/gateway/sandboxing)を、すべてのオプションについては[完全なリファレンス](/ja-JP/gateway/configuration-reference#agentsdefaultssandbox)を参照してください。 + 完全なガイドについては [Sandboxing](/ja-JP/gateway/sandboxing) を、すべてのオプションについては [完全なリファレンス](/ja-JP/gateway/configuration-reference#agentsdefaultssandbox) を参照してください。 - - relay-backed push は `openclaw.json` で設定します。 + + relay ベースの push は `openclaw.json` で設定します。 - gateway 設定に次を指定します。 + gateway 設定に次を追加します。 ```json5 { @@ -330,7 +317,7 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け apns: { relay: { baseUrl: "https://relay.example.com", - // Optional. Default: 10000 + // 任意。デフォルト: 10000 timeoutMs: 10000, }, }, @@ -339,39 +326,39 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - CLI の同等コマンド： + CLI での同等操作: ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` - これで行われること： + これにより行われること: - - gateway が外部 relay を通じて `push.test`、wake nudges、reconnect wakes を送信できるようになります。 - - ペアリング済み iOS アプリから転送される、登録単位の send grant を使用します。gateway にデプロイ全体用の relay トークンは不要です。 - - 各 relay-backed 登録を、iOS アプリがペアリングした gateway identity に紐づけるため、別の gateway は保存済み登録を再利用できません。 - - ローカル / 手動 iOS ビルドは direct APNs のままです。relay-backed 送信は、relay 経由で登録した公式配布ビルドにのみ適用されます。 - - 公式 / TestFlight iOS ビルドに埋め込まれた relay base URL と一致している必要があります。これにより、登録トラフィックと送信トラフィックが同じ relay デプロイ先に到達します。 + - gateway が外部 relay 経由で `push.test`、wake nudges、reconnect wakes を送信できるようにします。 + - ペアリングされた iOS アプリから転送された、登録スコープの send grant を使用します。gateway にデプロイ全体の relay token は不要です。 + - 各 relay ベースの登録は、iOS アプリがペアリングした gateway identity に紐付けられるため、別の gateway が保存済み登録を再利用することはできません。 + - ローカル/手動の iOS ビルドは direct APNs のままです。relay ベースの送信が適用されるのは、relay を通じて登録された公式配布ビルドのみです。 + - 公式/TestFlight iOS ビルドに組み込まれた relay base URL と一致している必要があります。これにより、登録トラフィックと送信トラフィックの両方が同じ relay デプロイメントに到達します。 - エンドツーエンドのフロー： + エンドツーエンドのフロー: - 1. 同じ relay base URL でコンパイルされた公式 / TestFlight iOS ビルドをインストールします。 + 1. 同じ relay base URL でコンパイルされた公式/TestFlight iOS ビルドをインストールします。 2. gateway で `gateway.push.apns.relay.baseUrl` を設定します。 - 3. iOS アプリを gateway とペアリングし、node セッションと operator セッションの両方を接続します。 - 4. iOS アプリは gateway identity を取得し、App Attest とアプリレシートを使って relay に登録した後、relay-backed の `push.apns.register` ペイロードをペアリング済み gateway に公開します。 + 3. iOS アプリを gateway にペアリングし、node セッションと operator セッションの両方を接続します。 + 4. iOS アプリが gateway identity を取得し、App Attest とアプリのレシートを使って relay に登録し、その後 relay ベースの `push.apns.register` payload をペアリング済み gateway に公開します。 5. gateway は relay handle と send grant を保存し、それらを `push.test`、wake nudges、reconnect wakes に使用します。 - 運用上の注意： + 運用上の注記: - - iOS アプリを別の gateway に切り替える場合は、アプリを再接続して、その gateway に紐づいた新しい relay 登録を公開できるようにしてください。 - - 別の relay デプロイ先を指す新しい iOS ビルドを出荷した場合、アプリは古い relay origin を再利用せず、キャッシュされた relay 登録を更新します。 + - iOS アプリを別の gateway に切り替える場合、アプリを再接続して、その gateway に紐付いた新しい relay 登録を公開できるようにします。 + - 別の relay デプロイメントを指す新しい iOS ビルドを配布した場合、アプリは古い relay origin を再利用する代わりに、キャッシュされた relay 登録を更新します。 - 互換性に関する注意： + 互換性に関する注記: - - `OPENCLAW_APNS_RELAY_BASE_URL` と `OPENCLAW_APNS_RELAY_TIMEOUT_MS` は、一時的な env 上書きとして引き続き動作します。 - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` は loopback 専用の開発用エスケープハッチのままです。HTTP の relay URL を設定に永続化しないでください。 + - `OPENCLAW_APNS_RELAY_BASE_URL` と `OPENCLAW_APNS_RELAY_TIMEOUT_MS` は、一時的な env 上書きとして引き続き使用できます。 + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` は、loopback 専用の開発用エスケープハッチのままです。HTTP の relay URL を設定に永続化しないでください。 - エンドツーエンドのフローについては[iOS App](/ja-JP/platforms/ios#relay-backed-push-for-official-builds)を、relay のセキュリティモデルについては[Authentication and trust flow](/ja-JP/platforms/ios#authentication-and-trust-flow)を参照してください。 + エンドツーエンドのフローについては [iOS App](/ja-JP/platforms/ios#relay-backed-push-for-official-builds) を、relay のセキュリティモデルについては [Authentication and trust flow](/ja-JP/platforms/ios#authentication-and-trust-flow) を参照してください。 @@ -389,10 +376,10 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - - `every`: 期間文字列（`30m`、`2h`）。無効にするには `0m` を設定します。 - - `target`: `last` | `none` | ``（例：`discord`、`matrix`、`telegram`、または `whatsapp`） - - `directPolicy`: DM 形式の heartbeat ターゲット向けの `allow`（デフォルト）または `block` - - 完全なガイドについては[Heartbeat](/ja-JP/gateway/heartbeat)を参照してください。 + - `every`: 期間文字列（`30m`、`2h`）。無効化するには `0m` を設定します。 + - `target`: `last` | `none` | ``（例: `discord`、`matrix`、`telegram`、`whatsapp`） + - `directPolicy`: DM スタイルの heartbeat target に対して `allow`（デフォルト）または `block` + - 完全なガイドについては [Heartbeat](/ja-JP/gateway/heartbeat) を参照してください。 @@ -411,9 +398,9 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - - `sessionRetention`: 完了した分離実行セッションを `sessions.json` から削除します（デフォルトは `24h`、無効にするには `false` を設定）。 + - `sessionRetention`: 完了した分離実行セッションを `sessions.json` から削除します（デフォルトは `24h`、無効化するには `false` を設定）。 - `runLog`: `cron/runs/.jsonl` をサイズと保持行数で削除します。 - - 機能概要と CLI の例については[Cron jobs](/ja-JP/automation/cron-jobs)を参照してください。 + - 機能概要と CLI 例については [Cron jobs](/ja-JP/automation/cron-jobs) を参照してください。 @@ -441,21 +428,21 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - セキュリティ上の注意： - - hook / webhook のペイロード内容はすべて信頼できない入力として扱ってください。 - - 専用の `hooks.token` を使用し、共有の Gateway トークンを再利用しないでください。 - - hook 認証はヘッダーのみです（`Authorization: Bearer ...` または `x-openclaw-token`）。クエリ文字列トークンは拒否されます。 - - `hooks.path` を `/` にすることはできません。webhook 受信は `/hooks` のような専用サブパスにしてください。 - - 危険なコンテンツのバイパスフラグ（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）は、厳密に限定したデバッグを行う場合を除き無効のままにしてください。 - - `hooks.allowRequestSessionKey` を有効にする場合は、呼び出し元が選択できるセッションキーを制限するため、`hooks.allowedSessionKeyPrefixes` も設定してください。 - - hook 駆動エージェントには、強力で現代的なモデル階層と厳格なツールポリシー（たとえば可能であればメッセージング専用 + サンドボックス化）を推奨します。 + セキュリティに関する注記: + - すべての hook/webhook payload 内容は信頼できない入力として扱ってください。 + - 専用の `hooks.token` を使用してください。共有 Gateway token を使い回さないでください。 + - Hook 認証はヘッダーのみです（`Authorization: Bearer ...` または `x-openclaw-token`）。クエリ文字列の token は拒否されます。 + - `hooks.path` は `/` にできません。webhook 受信は `/hooks` のような専用サブパスにしてください。 + - 危険なコンテンツ回避フラグ（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）は、厳密に限定したデバッグを行う場合を除き無効のままにしてください。 + - `hooks.allowRequestSessionKey` を有効にする場合は、呼び出し側が選ぶ session key を制限するために `hooks.allowedSessionKeyPrefixes` も設定してください。 + - hook 駆動の agent では、強力で最新のモデル階層と厳格な tool ポリシーを優先してください（たとえば、可能であればメッセージングのみ + サンドボックス化）。 - すべてのマッピングオプションと Gmail 統合については、[完全なリファレンス](/ja-JP/gateway/configuration-reference#hooks)を参照してください。 + すべてのマッピングオプションと Gmail 統合については、[完全なリファレンス](/ja-JP/gateway/configuration-reference#hooks) を参照してください。 - ワークスペースとセッションを分離して、複数の独立したエージェントを実行します。 + 別々の workspace と session を持つ複数の分離された agent を実行します。 ```json5 { @@ -472,7 +459,7 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - バインディングルールとエージェントごとのアクセスプロファイルについては、[Multi-Agent](/ja-JP/concepts/multi-agent)と[完全なリファレンス](/ja-JP/gateway/configuration-reference#multi-agent-routing)を参照してください。 + バインディングルールと agent ごとのアクセスプロファイルについては、[Multi-Agent](/ja-JP/concepts/multi-agent) と [完全なリファレンス](/ja-JP/gateway/configuration-reference#multi-agent-routing) を参照してください。 @@ -490,28 +477,28 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け } ``` - - **単一ファイル**：含まれているオブジェクトを置き換えます - - **ファイル配列**：順番にディープマージされます（後勝ち） - - **兄弟キー**：include の後にマージされます（含まれた値を上書き） - - **ネストされた include**：最大 10 階層までサポート - - **相対パス**：include 元ファイルを基準に解決されます - - **エラー処理**：ファイル欠落、解析エラー、循環 include に対して明確なエラーを表示します + - **単一ファイル**: そのオブジェクト全体を置き換えます + - **ファイル配列**: 順番に deep-merge されます（後勝ち） + - **兄弟キー**: include の後にマージされます（include された値を上書き） + - **ネストした include**: 最大 10 階層までサポート + - **相対パス**: include 元ファイルを基準に解決されます + - **エラーハンドリング**: ファイル欠如、パースエラー、循環 include に対して明確なエラーを返します -## 設定ホットリロード +## 設定のホットリロード -Gateway は `~/.openclaw/openclaw.json` を監視し、自動的に変更を適用します。ほとんどの設定では手動再起動は不要です。 +Gateway は `~/.openclaw/openclaw.json` を監視し、変更を自動的に適用します。ほとんどの設定では手動再起動は不要です。 ### リロードモード -| モード | 動作 | -| ---------------------- | --------------------------------------------------------------------------------------- | -| **`hybrid`**（デフォルト） | 安全な変更は即座にホット適用します。重要な変更では自動的に再起動します。 | -| **`hot`** | 安全な変更のみをホット適用します。再起動が必要な場合は警告を記録し、対応は自分で行います。 | -| **`restart`** | 安全かどうかにかかわらず、任意の設定変更で Gateway を再起動します。 | -| **`off`** | ファイル監視を無効にします。変更は次回の手動再起動時に反映されます。 | +| モード | 動作 | +| ---------------------- | ------------------------------------------------------------------------------------ | +| **`hybrid`**（デフォルト） | 安全な変更を即座にホット適用します。重要な変更では自動的に再起動します。 | +| **`hot`** | 安全な変更のみをホット適用します。再起動が必要な場合は警告を記録し、対応は自分で行います。 | +| **`restart`** | 安全かどうかに関係なく、設定変更のたびに Gateway を再起動します。 | +| **`off`** | ファイル監視を無効にします。変更は次回の手動再起動で反映されます。 | ```json5 { @@ -523,61 +510,61 @@ Gateway は `~/.openclaw/openclaw.json` を監視し、自動的に変更を適 ### ホット適用されるものと再起動が必要なもの -ほとんどのフィールドは、ダウンタイムなしでホット適用されます。`hybrid` モードでは、再起動が必要な変更は自動的に処理されます。 +ほとんどのフィールドはダウンタイムなしでホット適用されます。`hybrid` モードでは、再起動が必要な変更は自動的に処理されます。 -| カテゴリー | フィールド | 再起動が必要？ | -| ------------------- | -------------------------------------------------------------------- | --------------- | -| Channels | `channels.*`, `web` (WhatsApp) — すべての組み込みチャンネルと拡張チャンネル | いいえ | -| エージェントとモデル | `agent`, `agents`, `models`, `routing` | いいえ | -| 自動化 | `hooks`, `cron`, `agent.heartbeat` | いいえ | -| セッションとメッセージ | `session`, `messages` | いいえ | -| ツールとメディア | `tools`, `browser`, `skills`, `audio`, `talk` | いいえ | -| UI とその他 | `ui`, `logging`, `identity`, `bindings` | いいえ | -| Gateway サーバー | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **はい** | -| インフラ | `discovery`, `canvasHost`, `plugins` | **はい** | +| カテゴリ | フィールド | 再起動が必要? | +| ---------------- | ---------------------------------------------------------------- | ------- | +| Channels | `channels.*`、`web`（WhatsApp）— すべての組み込みおよび extension channels | いいえ | +| Agent & models | `agent`、`agents`、`models`、`routing` | いいえ | +| Automation | `hooks`、`cron`、`agent.heartbeat` | いいえ | +| Sessions & messages | `session`、`messages` | いいえ | +| Tools & media | `tools`、`browser`、`skills`、`audio`、`talk` | いいえ | +| UI & misc | `ui`、`logging`、`identity`、`bindings` | いいえ | +| Gateway server | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **はい** | +| Infrastructure | `discovery`、`canvasHost`、`plugins` | **はい** | -`gateway.reload` と `gateway.remote` は例外で、これらを変更しても**再起動は発生しません**。 +`gateway.reload` と `gateway.remote` は例外です。これらの変更では**再起動は発生しません**。 -## 設定 RPC（プログラムによる更新） +## Config RPC（プログラムによる更新） -コントロールプレーン書き込み RPC（`config.apply`、`config.patch`、`update.run`）は、`deviceId+clientIp` ごとに **60 秒あたり 3 リクエスト** にレート制限されています。制限されると、RPC は `UNAVAILABLE` を `retryAfterMs` とともに返します。 +control-plane の書き込み RPC（`config.apply`、`config.patch`、`update.run`）は、`deviceId+clientIp` ごとに **60 秒あたり 3 リクエスト** にレート制限されます。制限された場合、RPC は `retryAfterMs` を付けて `UNAVAILABLE` を返します。 -安全な / デフォルトのフロー： +安全なデフォルトフロー: -- `config.schema.lookup`: 1 つのパス範囲の設定サブツリーを、浅い - スキーマノード、一致したヒントメタデータ、および直下の子サマリー付きで確認 -- `config.get`: 現在のスナップショット + ハッシュを取得 +- `config.schema.lookup`: 浅い + スキーマノード、一致したヒントメタデータ、直下の子要約とともに、1 つのパスにスコープされた設定サブツリーを確認する +- `config.get`: 現在のスナップショット + hash を取得する - `config.patch`: 推奨される部分更新パス - `config.apply`: 設定全体を置き換える場合のみ -- `update.run`: 明示的な自己更新 + 再起動 +- `update.run`: 明示的な self-update + restart -設定全体を置き換えない場合は、`config.schema.lookup` -の後に `config.patch` を使うことを推奨します。 +設定全体を置き換えるのでない場合は、`config.schema.lookup` +の後に `config.patch` を優先してください。 - 設定全体を検証して書き込み、1 ステップで Gateway を再起動します。 + 設定全体を検証して書き込み、Gateway を 1 ステップで再起動します。 `config.apply` は**設定全体**を置き換えます。部分更新には `config.patch` を、単一キーには `openclaw config set` を使用してください。 - パラメータ： + パラメータ: - - `raw`（文字列）— 設定全体の JSON5 ペイロード - - `baseHash`（任意）— `config.get` の設定ハッシュ（設定が存在する場合は必須） - - `sessionKey`（任意）— 再起動後のウェイクアップ ping 用セッションキー - - `note`（任意）— 再起動センチネル用メモ - - `restartDelayMs`（任意）— 再起動までの遅延（デフォルトは 2000） + - `raw`（string）— 設定全体の JSON5 payload + - `baseHash`（任意）— `config.get` からの設定 hash（設定が存在する場合は必須） + - `sessionKey`（任意）— 再起動後の wake-up ping 用 session key + - `note`（任意）— restart sentinel 用のメモ + - `restartDelayMs`（任意）— 再起動までの遅延（デフォルト 2000） - 再起動リクエストは、すでに保留中 / 進行中のものがある場合はまとめられ、再起動サイクル間には 30 秒のクールダウンが適用されます。 + 再起動リクエストは、すでに保留中/進行中のものがある場合はまとめられ、再起動サイクル間には 30 秒のクールダウンが適用されます。 ```bash - openclaw gateway call config.get --params '{}' # capture payload.hash + openclaw gateway call config.get --params '{}' # payload.hash を取得 openclaw gateway call config.apply --params '{ "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }", "baseHash": "", @@ -588,16 +575,16 @@ Gateway は `~/.openclaw/openclaw.json` を監視し、自動的に変更を適 - 部分更新を既存の設定へマージします（JSON merge patch セマンティクス）。 + 部分更新を既存の設定にマージします（JSON merge patch セマンティクス）。 - - オブジェクトは再帰的にマージ - - `null` はキーを削除 - - 配列は置換 + - オブジェクトは再帰的にマージされる + - `null` はキーを削除する + - 配列は置き換えられる - パラメータ： + パラメータ: - - `raw`（文字列）— 変更するキーだけを含む JSON5 - - `baseHash`（必須）— `config.get` の設定ハッシュ + - `raw`（string）— 変更するキーだけを含む JSON5 + - `baseHash`（必須）— `config.get` からの設定 hash - `sessionKey`、`note`、`restartDelayMs` — `config.apply` と同じ 再起動動作は `config.apply` と同じです。保留中の再起動はまとめられ、再起動サイクル間には 30 秒のクールダウンがあります。 @@ -614,12 +601,12 @@ Gateway は `~/.openclaw/openclaw.json` を監視し、自動的に変更を適 ## 環境変数 -OpenClaw は親プロセスに加えて、以下から env vars を読み込みます。 +OpenClaw は、親プロセスからの env vars に加えて、次も読み込みます。 -- 現在の作業ディレクトリにある `.env`（存在する場合） +- 現在の作業ディレクトリの `.env`（存在する場合） - `~/.openclaw/.env`（グローバルフォールバック） -どちらのファイルも、既存の env vars を上書きしません。設定内にインライン env vars を指定することもできます。 +どちらのファイルも、既存の env vars を上書きしません。設定内でインライン env vars を設定することもできます。 ```json5 { @@ -631,7 +618,7 @@ OpenClaw は親プロセスに加えて、以下から env vars を読み込み ``` - 有効な場合で、想定されるキーが設定されていないと、OpenClaw はログインシェルを実行して不足しているキーのみをインポートします。 + 有効な場合、期待されるキーが設定されていないと、OpenClaw はログインシェルを実行し、不足しているキーのみをインポートします。 ```json5 { @@ -641,7 +628,7 @@ OpenClaw は親プロセスに加えて、以下から env vars を読み込み } ``` -Env var の同等設定：`OPENCLAW_LOAD_SHELL_ENV=1` +環境変数での同等設定: `OPENCLAW_LOAD_SHELL_ENV=1` @@ -654,18 +641,18 @@ Env var の同等設定：`OPENCLAW_LOAD_SHELL_ENV=1` } ``` -ルール： +ルール: -- 一致するのは大文字の名前のみです：`[A-Z_][A-Z0-9_]*` -- 不足している / 空の変数は、読み込み時にエラーになります -- リテラル出力には `$${VAR}` でエスケープします +- 一致するのは大文字名のみ: `[A-Z_][A-Z0-9_]*` +- 存在しない/空の vars は読み込み時エラーになります +- リテラル出力にするには `$${VAR}` でエスケープします - `$include` ファイル内でも動作します -- インライン置換：`"${BASE}/v1"` → `"https://api.example.com/v1"` +- インライン置換: `"${BASE}/v1"` → `"https://api.example.com/v1"` - SecretRef オブジェクトをサポートするフィールドでは、以下を使用できます。 + SecretRef オブジェクトをサポートするフィールドでは、次を使用できます。 ```json5 { @@ -697,11 +684,11 @@ Env var の同等設定：`OPENCLAW_LOAD_SHELL_ENV=1` } ``` -SecretRef の詳細（`env` / `file` / `exec` 用の `secrets.providers` を含む）は、[Secrets Management](/ja-JP/gateway/secrets)にあります。 -サポートされる認証情報パスは、[SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface)に一覧があります。 +SecretRef の詳細（`env`/`file`/`exec` 用の `secrets.providers` を含む）は [Secrets Management](/ja-JP/gateway/secrets) にあります。 +サポートされる認証情報パスは [SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface) に一覧があります。 -完全な優先順位とソースについては、[Environment](/ja-JP/help/environment)を参照してください。 +優先順位と取得元の完全な説明については [Environment](/ja-JP/help/environment) を参照してください。 ## 完全なリファレンス diff --git a/docs/ja-JP/gateway/heartbeat.md b/docs/ja-JP/gateway/heartbeat.md index 1132deb4b..84354ea22 100644 --- a/docs/ja-JP/gateway/heartbeat.md +++ b/docs/ja-JP/gateway/heartbeat.md @@ -1,38 +1,39 @@ --- read_when: - - Heartbeat の間隔やメッセージ内容を調整する場合 - - スケジュールされたタスクで heartbeat と cron のどちらを使うか判断する場合 -summary: Heartbeat のポーリングメッセージと通知ルール -title: Heartbeat + - ハートビートの頻度またはメッセージングの調整 + - スケジュールされたタスクにハートビートと cron のどちらを使うかの判断 +summary: ハートビートポーリングメッセージと通知ルール +title: ハートビート x-i18n: - generated_at: "2026-04-08T02:15:42Z" + generated_at: "2026-04-11T02:44:56Z" model: gpt-5.4 provider: openai - source_hash: a8021d747637060eacb91ec5f75904368a08790c19f4fca32acda8c8c0a25e41 + source_hash: e4485072148753076d909867a623696829bf4a82dcd0479b95d5d0cae43100b0 source_path: gateway/heartbeat.md workflow: 15 --- -# Heartbeat (Gateway) +# ハートビート（Gateway） -> **Heartbeat と Cron の違いは？** 使い分けの指針については [Automation & Tasks](/ja-JP/automation) を参照してください。 +> **Heartbeat と Cron のどちらを使うべきですか？** 使い分けの指針については [Automation & Tasks](/ja-JP/automation) を参照してください。 -Heartbeat は、メインセッションで **定期的なエージェントターン** を実行し、必要な注意事項をあなたにスパムせずに通知できるようにします。 +Heartbeat は、**定期的なエージェントターン** をメインセッションで実行し、 +必要な注意事項をモデルが表に出せるようにしつつ、過剰な通知を防ぎます。 -Heartbeat はスケジュールされたメインセッションのターンであり、[background task](/ja-JP/automation/tasks) レコードは作成しません。 -タスクレコードは、切り離された作業（ACP 実行、サブエージェント、分離された cron ジョブ）のためのものです。 +Heartbeat は、スケジュールされたメインセッションのターンです — [background task](/ja-JP/automation/tasks) レコードは作成しません。 +タスクレコードは、切り離された作業（ACP 実行、subagent、分離された cron ジョブ）用です。 トラブルシューティング: [Scheduled Tasks](/ja-JP/automation/cron-jobs#troubleshooting) ## クイックスタート（初心者向け） -1. Heartbeat を有効のままにしておくか（デフォルトは `30m`、Anthropic OAuth / token 認証時は `1h`。Claude CLI の再利用を含む）、独自の間隔を設定します。 -2. エージェントのワークスペースに、小さな `HEARTBEAT.md` チェックリストまたは `tasks:` ブロックを作成します（任意ですが推奨）。 -3. Heartbeat メッセージの送信先を決めます（デフォルトは `target: "none"` です。最後の連絡先へ送るには `target: "last"` を設定します）。 -4. 任意: 透明性のために heartbeat reasoning 配信を有効にします。 -5. 任意: Heartbeat 実行で `HEARTBEAT.md` だけが必要な場合は、軽量なブートストラップコンテキストを使用します。 -6. 任意: 各 heartbeat で会話履歴全体を送信しないよう、分離セッションを有効にします。 -7. 任意: Heartbeat をアクティブな時間帯（ローカル時刻）に制限します。 +1. Heartbeat を有効のままにする（デフォルトは `30m`、Anthropic OAuth/token auth の場合は `1h`。Claude CLI reuse を含む）か、独自の頻度を設定します。 +2. エージェントワークスペースに小さな `HEARTBEAT.md` チェックリストまたは `tasks:` ブロックを作成します（任意ですが推奨）。 +3. Heartbeat メッセージの送信先を決めます（デフォルトは `target: "none"` です。最後の連絡先に送るには `target: "last"` を設定します）。 +4. 任意で、透明性のために heartbeat reasoning 配信を有効にします。 +5. 任意で、heartbeat 実行で `HEARTBEAT.md` だけが必要な場合は軽量な bootstrap コンテキストを使用します。 +6. 任意で、heartbeat ごとに会話履歴全体を送らないように分離セッションを有効にします。 +7. 任意で、heartbeat をアクティブ時間帯（ローカル時刻）に制限します。 設定例: @@ -42,10 +43,10 @@ Heartbeat はスケジュールされたメインセッションのターンで defaults: { heartbeat: { every: "30m", - target: "last", // 最後の連絡先へ明示的に配信（デフォルトは "none"） - directPolicy: "allow", // デフォルト: 直接 / DM 宛先を許可。抑止するには "block" を設定 - lightContext: true, // 任意: ブートストラップファイルから HEARTBEAT.md のみを注入 - isolatedSession: true, // 任意: 実行ごとに新しいセッションを使用（会話履歴なし） + target: "last", // 最後の連絡先への明示的な配信（デフォルトは "none"） + directPolicy: "allow", // デフォルト: 直接/DM 宛先を許可。抑制するには "block" を設定 + lightContext: true, // 任意: bootstrap ファイルから HEARTBEAT.md のみを注入 + isolatedSession: true, // 任意: 毎回新しいセッションで実行（会話履歴なし） // activeHours: { start: "08:00", end: "24:00" }, // includeReasoning: true, // 任意: 別の `Reasoning:` メッセージも送信 }, @@ -56,45 +57,46 @@ Heartbeat はスケジュールされたメインセッションのターンで ## デフォルト -- 間隔: `30m`（Anthropic OAuth / token 認証が検出された認証モードの場合は `1h`。Claude CLI の再利用を含む）。`agents.defaults.heartbeat.every` またはエージェント単位の `agents.list[].heartbeat.every` を設定してください。無効化するには `0m` を使用します。 +- 間隔: `30m`（または、Anthropic OAuth/token auth が検出された auth mode の場合は `1h`。Claude CLI reuse を含む）。`agents.defaults.heartbeat.every` またはエージェントごとの `agents.list[].heartbeat.every` を設定します。無効にするには `0m` を使用します。 - プロンプト本文（`agents.defaults.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」セクションが含まれます。 -- `0m` で heartbeat を無効にすると、通常実行でもブートストラップコンテキストから `HEARTBEAT.md` - が除外され、モデルは heartbeat 専用の指示を見なくなります。 +- heartbeat プロンプトは、ユーザーメッセージとして**そのまま**送信されます。システム + プロンプトには、デフォルトエージェントで heartbeat が有効かつ + 実行が内部的にフラグ付けされている場合にのみ「Heartbeat」セクションが含まれます。 +- Heartbeat を `0m` で無効にすると、通常実行でも bootstrap コンテキストから + `HEARTBEAT.md` が除外されるため、モデルは heartbeat 専用の指示を見ません。 - アクティブ時間帯（`heartbeat.activeHours`）は、設定されたタイムゾーンで判定されます。 - 時間帯の外では、次回その時間帯内に入る tick まで heartbeat はスキップされます。 + 時間帯外では、heartbeat は次に時間帯内に入る tick までスキップされます。 ## heartbeat プロンプトの目的 -デフォルトのプロンプトは意図的に広い内容になっています。 +デフォルトのプロンプトは、意図的に広い内容になっています: -- **バックグラウンドタスク**: 「未処理のタスクを検討する」という指示により、エージェントは - フォローアップ（受信箱、カレンダー、リマインダー、キューに入った作業）を見直し、 - 緊急性のあるものを通知しやすくなります。 -- **人への確認**: 「日中にときどき人間の様子を確認する」という指示により、 - 時折「何か必要ですか？」という軽い確認メッセージを促しますが、設定されたローカルタイムゾーンを使うことで - 夜間のスパムは避けます（[/concepts/timezone](/ja-JP/concepts/timezone) を参照）。 +- **バックグラウンドタスク**: 「未処理タスクを検討する」は、エージェントに + フォローアップ（受信箱、カレンダー、リマインダー、キュー済み作業）を確認させ、 + 緊急なものを表に出すよう促します。 +- **人へのチェックイン**: 「日中にときどき人間の様子を確認する」は、 + 軽い「何か必要ですか？」メッセージを時々送るよう促しますが、 + 設定されたローカルタイムゾーンを使うことで夜間の通知過多を避けます（[/concepts/timezone](/ja-JP/concepts/timezone) を参照）。 -Heartbeat は完了した [background tasks](/ja-JP/automation/tasks) に反応できますが、heartbeat 実行自体ではタスクレコードは作成されません。 +Heartbeat は完了した [background tasks](/ja-JP/automation/tasks) に反応できますが、heartbeat 実行自体はタスクレコードを作成しません。 -Heartbeat に非常に具体的なこと（たとえば「Gmail PubSub -統計を確認する」や「gateway の健全性を確認する」）をさせたい場合は、`agents.defaults.heartbeat.prompt`（または -`agents.list[].heartbeat.prompt`）をカスタム本文に設定してください（そのまま送信されます）。 +heartbeat に非常に具体的なこと（たとえば「Gmail PubSub +stats を確認する」や「Gateway の健全性を検証する」）をさせたい場合は、`agents.defaults.heartbeat.prompt`（または +`agents.list[].heartbeat.prompt`）にカスタム本文（そのまま送信される）を設定してください。 -## 応答契約 +## レスポンス契約 -- 注意すべきことが何もなければ、**`HEARTBEAT_OK`** で応答します。 -- Heartbeat 実行中、OpenClaw は応答の **先頭または末尾** に `HEARTBEAT_OK` が - ある場合、それを ack として扱います。このトークンは取り除かれ、残りの内容が - **≤ `ackMaxChars`**（デフォルト: 300）であれば応答は破棄されます。 -- `HEARTBEAT_OK` が応答の **途中** に現れた場合は、特別扱いされません。 -- アラートでは、**`HEARTBEAT_OK` を含めないでください**。アラート本文のみを返します。 +- 注意が必要なことが何もなければ、**`HEARTBEAT_OK`** で返信します。 +- heartbeat 実行中、OpenClaw は返信の**先頭または末尾**に `HEARTBEAT_OK` が現れた場合、 + それを ack として扱います。このトークンは削除され、残りの内容が + **`ackMaxChars` 以下**（デフォルト: 300）であれば、その返信は破棄されます。 +- `HEARTBEAT_OK` が返信の**途中**に現れた場合は、 + 特別扱いされません。 +- アラートの場合は、**`HEARTBEAT_OK` を含めないでください**。アラート文だけを返します。 -Heartbeat 以外では、メッセージの先頭または末尾にある余分な `HEARTBEAT_OK` は除去されてログ記録されます。 -メッセージが `HEARTBEAT_OK` のみの場合は破棄されます。 +heartbeat 以外では、メッセージの先頭/末尾に紛れ込んだ `HEARTBEAT_OK` は削除されて +ログに記録されます。メッセージが `HEARTBEAT_OK` だけの場合は破棄されます。 ## 設定 @@ -106,11 +108,11 @@ Heartbeat 以外では、メッセージの先頭または末尾にある余分 every: "30m", // デフォルト: 30m（0m で無効化） model: "anthropic/claude-opus-4-6", includeReasoning: false, // デフォルト: false（利用可能な場合は別の Reasoning: メッセージを配信） - lightContext: false, // デフォルト: false。true でワークスペースのブートストラップファイルから HEARTBEAT.md のみ保持 - isolatedSession: false, // デフォルト: false。true で各 heartbeat を新しいセッションで実行（会話履歴なし） - target: "last", // デフォルト: none | 選択肢: last | none | （コアまたはプラグイン、例: "bluebubbles"） + lightContext: false, // デフォルト: false。true の場合、ワークスペース bootstrap ファイルから HEARTBEAT.md のみを保持 + isolatedSession: false, // デフォルト: false。true の場合、各 heartbeat を新しいセッションで実行（会話履歴なし） + target: "last", // デフォルト: none | オプション: last | none | （コアまたは plugin。例: "bluebubbles"） to: "+15551234567", // 任意のチャネル固有オーバーライド - accountId: "ops-bot", // 任意のマルチアカウントチャネル ID + accountId: "ops-bot", // 任意のマルチアカウントチャネル id 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.", ackMaxChars: 300, // HEARTBEAT_OK の後に許容される最大文字数 }, @@ -122,18 +124,18 @@ Heartbeat 以外では、メッセージの先頭または末尾にある余分 ### スコープと優先順位 - `agents.defaults.heartbeat` はグローバルな heartbeat 動作を設定します。 -- `agents.list[].heartbeat` はその上にマージされます。いずれかのエージェントに `heartbeat` ブロックがある場合、**そのエージェントだけ** が heartbeat を実行します。 -- `channels.defaults.heartbeat` はすべてのチャネルの可視性デフォルトを設定します。 +- `agents.list[].heartbeat` はその上にマージされます。いずれかのエージェントに `heartbeat` ブロックがある場合、heartbeat を実行するのは**それらのエージェントだけ**です。 +- `channels.defaults.heartbeat` は全チャネルの可視性デフォルトを設定します。 - `channels..heartbeat` はチャネルデフォルトを上書きします。 -- `channels..accounts..heartbeat`（マルチアカウントチャネル）はチャネル単位設定を上書きします。 +- `channels..accounts..heartbeat`（マルチアカウントチャネル）はチャネルごとの設定を上書きします。 -### エージェントごとの Heartbeat +### エージェントごとの heartbeat -いずれかの `agents.list[]` エントリに `heartbeat` ブロックが含まれている場合、**そのエージェントだけ** -が heartbeat を実行します。エージェント単位のブロックは `agents.defaults.heartbeat` -の上にマージされます（そのため、共有デフォルトを 1 回設定して、エージェントごとに上書きできます）。 +いずれかの `agents.list[]` エントリに `heartbeat` ブロックが含まれている場合、heartbeat を実行するのは**それらのエージェントだけ**です。 +エージェントごとのブロックは `agents.defaults.heartbeat` の上にマージされます +（共有デフォルトを一度設定し、エージェントごとに上書きできます）。 -例: 2 つのエージェントがあり、2 番目のエージェントだけが heartbeat を実行します。 +例: 2つのエージェントがあり、heartbeat を実行するのは2番目のエージェントだけです。 ```json5 { @@ -141,7 +143,7 @@ Heartbeat 以外では、メッセージの先頭または末尾にある余分 defaults: { heartbeat: { every: "30m", - target: "last", // 最後の連絡先へ明示的に配信（デフォルトは "none"） + target: "last", // 最後の連絡先への明示的な配信（デフォルトは "none"） }, }, list: [ @@ -152,6 +154,7 @@ Heartbeat 以外では、メッセージの先頭または末尾にある余分 every: "1h", target: "whatsapp", to: "+15551234567", + timeoutSeconds: 45, 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.", }, }, @@ -162,7 +165,7 @@ Heartbeat 以外では、メッセージの先頭または末尾にある余分 ### アクティブ時間帯の例 -特定のタイムゾーンの営業時間内に heartbeat を制限する場合: +特定のタイムゾーンの業務時間に heartbeat を制限します: ```json5 { @@ -170,11 +173,11 @@ Heartbeat 以外では、メッセージの先頭または末尾にある余分 defaults: { heartbeat: { every: "30m", - target: "last", // 最後の連絡先へ明示的に配信（デフォルトは "none"） + target: "last", // 最後の連絡先への明示的な配信（デフォルトは "none"） activeHours: { start: "09:00", end: "22:00", - timezone: "America/New_York", // 任意。設定されていれば userTimezone を使い、なければホストのタイムゾーン + timezone: "America/New_York", // 任意。userTimezone が設定されていればそれを使い、なければホストのタイムゾーン }, }, }, @@ -182,21 +185,21 @@ Heartbeat 以外では、メッセージの先頭または末尾にある余分 } ``` -この時間帯（東部時間の午前 9 時前または午後 10 時以降）の外では、heartbeat はスキップされます。次に予定されている、その時間帯内の tick で通常どおり実行されます。 +この時間帯の外側（東部時間で午前9時前または午後10時以降）では、heartbeat はスキップされます。次に時間帯内に入る予定 tick で通常どおり実行されます。 -### 24 時間 365 日の設定 +### 24時間365日の設定 -Heartbeat を終日実行したい場合は、次のいずれかのパターンを使用してください。 +heartbeat を終日実行したい場合は、次のいずれかのパターンを使用します: -- `activeHours` を完全に省略する（時間帯の制限なし。これがデフォルトの動作です）。 +- `activeHours` を完全に省略する（時間帯制限なし。これがデフォルト動作です）。 - 終日ウィンドウを設定する: `activeHours: { start: "00:00", end: "24:00" }`。 -`start` と `end` に同じ時刻（たとえば `08:00` から `08:00`）を設定しないでください。 +同じ `start` と `end` の時刻（たとえば `08:00` から `08:00`）は設定しないでください。 これは幅ゼロのウィンドウとして扱われるため、heartbeat は常にスキップされます。 ### マルチアカウントの例 -Telegram のようなマルチアカウントチャネルで特定アカウントを対象にするには `accountId` を使います。 +Telegram のようなマルチアカウントチャネルで特定のアカウントを対象にするには `accountId` を使います: ```json5 { @@ -207,7 +210,7 @@ Telegram のようなマルチアカウントチャネルで特定アカウン heartbeat: { every: "1h", target: "telegram", - to: "12345678:topic:42", // 任意: 特定の topic / thread にルーティング + to: "12345678:topic:42", // 任意: 特定の topic/thread にルーティング accountId: "ops-bot", }, }, @@ -225,64 +228,64 @@ Telegram のようなマルチアカウントチャネルで特定アカウン ### フィールドメモ -- `every`: heartbeat の間隔（duration 文字列。デフォルト単位 = 分）。 +- `every`: heartbeat 間隔（duration string。デフォルト単位 = 分）。 - `model`: heartbeat 実行用の任意のモデル上書き（`provider/model`）。 -- `includeReasoning`: 有効時、利用可能であれば別の `Reasoning:` メッセージも配信します（`/reasoning on` と同じ形式）。 -- `lightContext`: true の場合、heartbeat 実行では軽量ブートストラップコンテキストを使用し、ワークスペースのブートストラップファイルから `HEARTBEAT.md` のみ保持します。 -- `isolatedSession`: true の場合、各 heartbeat は以前の会話履歴なしの新しいセッションで実行されます。cron の `sessionTarget: "isolated"` と同じ分離パターンを使います。heartbeat ごとのトークンコストを大幅に削減します。最大限節約したい場合は `lightContext: true` と組み合わせてください。配信ルーティングは引き続きメインセッションのコンテキストを使います。 +- `includeReasoning`: 有効な場合、利用可能なときに別の `Reasoning:` メッセージも配信します（`/reasoning on` と同じ形式）。 +- `lightContext`: true の場合、heartbeat 実行では軽量な bootstrap コンテキストを使い、ワークスペース bootstrap ファイルから `HEARTBEAT.md` のみを保持します。 +- `isolatedSession`: true の場合、各 heartbeat は以前の会話履歴を持たない新しいセッションで実行されます。cron の `sessionTarget: "isolated"` と同じ分離パターンを使用します。heartbeat ごとのトークンコストを大幅に削減します。最大限節約するには `lightContext: true` と組み合わせてください。配信ルーティングは引き続きメインセッションのコンテキストを使います。 - `session`: heartbeat 実行用の任意のセッションキー。 - `main`（デフォルト）: エージェントのメインセッション。 - 明示的なセッションキー（`openclaw sessions --json` または [sessions CLI](/cli/sessions) からコピー）。 - - セッションキー形式については [Sessions](/ja-JP/concepts/session) と [Groups](/ja-JP/channels/groups) を参照してください。 + - セッションキー形式: [Sessions](/ja-JP/concepts/session) および [Groups](/ja-JP/channels/groups) を参照してください。 - `target`: - - `last`: 最後に使われた外部チャネルへ配信します。 - - 明示的なチャネル: 任意の設定済みチャネルまたはプラグイン ID。たとえば `discord`、`matrix`、`telegram`、`whatsapp`。 - - `none`（デフォルト）: heartbeat は実行しますが、外部には **配信しません**。 -- `directPolicy`: 直接 / DM 配信の動作を制御します。 - - `allow`（デフォルト）: 直接 / DM への heartbeat 配信を許可します。 - - `block`: 直接 / DM 配信を抑止します（`reason=dm-blocked`）。 -- `to`: 任意の受信者上書き（チャネル固有 ID。例: WhatsApp の E.164 や Telegram の chat id）。Telegram の topic / thread には `:topic:` を使用します。 -- `accountId`: マルチアカウントチャネル向けの任意のアカウント ID。`target: "last"` の場合、解決された最後のチャネルがアカウントをサポートしていればそのアカウント ID が適用され、そうでなければ無視されます。アカウント ID が解決されたチャネルの設定済みアカウントと一致しない場合、配信はスキップされます。 -- `prompt`: デフォルトのプロンプト本文を上書きします（マージはされません）。 -- `ackMaxChars`: 配信前に `HEARTBEAT_OK` の後ろに許容される最大文字数。 -- `suppressToolErrorWarnings`: true の場合、heartbeat 実行中のツールエラー警告ペイロードを抑止します。 -- `activeHours`: heartbeat 実行を時間帯に制限します。`start`（HH:MM、含む。日の開始には `00:00` を使用）、`end`（HH:MM、含まない。日の終わりには `24:00` が利用可）、および任意の `timezone` を持つオブジェクトです。 + - `last`: 最後に使用された外部チャネルに配信します。 + - 明示的なチャネル: 任意の設定済みチャネルまたは plugin id。たとえば `discord`、`matrix`、`telegram`、`whatsapp`。 + - `none`（デフォルト）: heartbeat は実行しますが、外部には**配信しません**。 +- `directPolicy`: 直接/DM 配信の動作を制御します: + - `allow`（デフォルト）: 直接/DM への heartbeat 配信を許可します。 + - `block`: 直接/DM 配信を抑制します（`reason=dm-blocked`）。 +- `to`: 任意の受信者上書き（チャネル固有 id。たとえば WhatsApp の E.164 や Telegram の chat id）。Telegram の topic/thread には `:topic:` を使用します。 +- `accountId`: マルチアカウントチャネル用の任意のアカウント id。`target: "last"` の場合、そのアカウント id は、最後に解決されたチャネルがアカウントをサポートしていれば適用され、そうでなければ無視されます。アカウント id が解決されたチャネルの設定済みアカウントに一致しない場合、配信はスキップされます。 +- `prompt`: デフォルトのプロンプト本文を上書きします（マージされません）。 +- `ackMaxChars`: `HEARTBEAT_OK` の後に許容される最大文字数。 +- `suppressToolErrorWarnings`: true の場合、heartbeat 実行中のツールエラー警告ペイロードを抑制します。 +- `activeHours`: heartbeat 実行を時間帯に制限します。`start`（HH:MM、含む。日の始まりには `00:00` を使用）、`end`（HH:MM、含まない。日末には `24:00` が使用可能）、および任意の `timezone` を持つオブジェクトです。 - 省略または `"user"`: `agents.defaults.userTimezone` が設定されていればそれを使い、そうでなければホストシステムのタイムゾーンにフォールバックします。 - `"local"`: 常にホストシステムのタイムゾーンを使います。 - - 任意の IANA 識別子（例: `America/New_York`）: それを直接使用します。無効な場合は上記の `"user"` 動作にフォールバックします。 - - `start` と `end` はアクティブウィンドウでは同じ値にしてはいけません。同じ値は幅ゼロ（常にウィンドウ外）として扱われます。 - - アクティブウィンドウ外では、次回そのウィンドウ内に入る tick まで heartbeat はスキップされます。 + - 任意の IANA 識別子（例: `America/New_York`）: 直接使用されます。無効な場合は、上記の `"user"` 動作にフォールバックします。 + - アクティブウィンドウとして扱うには `start` と `end` は等しくしてはいけません。等しい値は幅ゼロ（常に時間帯外）として扱われます。 + - アクティブ時間帯の外では、heartbeat は次に時間帯内に入る tick までスキップされます。 ## 配信動作 - Heartbeat はデフォルトでエージェントのメインセッション（`agent::`）で実行され、 - `session.scope = "global"` の場合は `global` で実行されます。特定の - チャネルセッション（Discord / WhatsApp など）に上書きするには `session` を設定します。 + `session.scope = "global"` の場合は `global` で実行されます。特定のチャネルセッション（Discord/WhatsApp など）に上書きするには + `session` を設定します。 - `session` は実行コンテキストにのみ影響します。配信は `target` と `to` によって制御されます。 -- 特定のチャネル / 受信者に配信するには、`target` + `to` を設定します。 - `target: "last"` の場合、配信はそのセッションの最後の外部チャネルを使います。 -- Heartbeat 配信はデフォルトで直接 / DM 宛先を許可します。直接宛先への送信を抑止しつつ heartbeat ターンは実行したい場合は、`directPolicy: "block"` を設定してください。 -- メインキューがビジーの場合、heartbeat はスキップされ、後で再試行されます。 +- 特定のチャネル/受信者に配信するには、`target` + `to` を設定します。 + `target: "last"` の場合、配信にはそのセッションの最後の外部チャネルが使われます。 +- Heartbeat 配信は、デフォルトで直接/DM 宛先を許可します。heartbeat ターン自体は実行したまま直接宛先への送信を抑制するには、`directPolicy: "block"` を設定します。 +- メインキューがビジーな場合、heartbeat はスキップされ、後で再試行されます。 - `target` が外部宛先に解決されない場合でも、実行自体は行われますが、 外向きメッセージは送信されません。 -- `showOk`、`showAlerts`、`useIndicator` がすべて無効な場合、実行は `reason=alerts-disabled` として事前にスキップされます。 -- アラート配信だけが無効な場合でも、OpenClaw は heartbeat を実行し、期限タスクのタイムスタンプを更新し、セッションの idle タイムスタンプを復元し、外向きアラートペイロードを抑止できます。 -- heartbeat 専用の応答はセッションをアクティブのままにしません。最後の `updatedAt` +- `showOk`、`showAlerts`、`useIndicator` がすべて無効の場合、実行は事前に `reason=alerts-disabled` としてスキップされます。 +- アラート配信のみが無効な場合、OpenClaw は引き続き heartbeat を実行し、期限付きタスクのタイムスタンプを更新し、セッションのアイドルタイムスタンプを復元し、外向きのアラートペイロードを抑制できます。 +- Heartbeat 専用の返信はセッションをアクティブ状態に保ちません。`updatedAt` は復元されるため、アイドル期限切れは通常どおり動作します。 -- 切り離された [background tasks](/ja-JP/automation/tasks) は、メインセッションが何かにすばやく気付くべきときにシステムイベントをキューに積み、heartbeat を起こすことができます。この wake によって heartbeat 実行が background task になることはありません。 +- 切り離された [background tasks](/ja-JP/automation/tasks) はシステムイベントをキューに入れ、メインセッションが何かにすばやく気づくべきときに heartbeat を起こすことができます。この wake によって heartbeat 実行が background task になるわけではありません。 ## 可視性の制御 -デフォルトでは、`HEARTBEAT_OK` の確認応答は抑止され、アラート内容のみが -配信されます。これをチャネルごと、またはアカウントごとに調整できます。 +デフォルトでは、`HEARTBEAT_OK` の確認応答は抑制され、アラート内容は +配信されます。これはチャネルごと、またはアカウントごとに調整できます: ```yaml channels: defaults: heartbeat: - showOk: false # HEARTBEAT_OK を隠す（デフォルト） + showOk: false # HEARTBEAT_OK を非表示（デフォルト） showAlerts: true # アラートメッセージを表示（デフォルト） - useIndicator: true # indicator イベントを送出（デフォルト） + useIndicator: true # indicator イベントを発行（デフォルト） telegram: heartbeat: showOk: true # Telegram では OK 確認応答を表示 @@ -290,20 +293,20 @@ channels: accounts: work: heartbeat: - showAlerts: false # このアカウントではアラート配信を抑止 + showAlerts: false # このアカウントではアラート配信を抑制 ``` -優先順位: アカウント単位 → チャネル単位 → チャネルデフォルト → 組み込みデフォルト。 +優先順位: アカウントごと → チャネルごと → チャネルデフォルト → 組み込みデフォルト。 -### 各フラグの役割 +### 各フラグの意味 -- `showOk`: モデルが OK のみの応答を返したときに `HEARTBEAT_OK` 確認応答を送信します。 -- `showAlerts`: モデルが OK 以外の応答を返したときにアラート内容を送信します。 -- `useIndicator`: UI のステータス表示用に indicator イベントを送出します。 +- `showOk`: モデルが OK のみの返信を返したときに `HEARTBEAT_OK` 確認応答を送信します。 +- `showAlerts`: モデルが非 OK の返信を返したときにアラート内容を送信します。 +- `useIndicator`: UI のステータス表示向けに indicator イベントを発行します。 -**3 つすべて** が false の場合、OpenClaw は heartbeat 実行自体をスキップします（モデル呼び出しなし）。 +**3つすべて** が false の場合、OpenClaw は heartbeat 実行全体をスキップします（モデル呼び出しなし）。 -### チャネル単位とアカウント単位の例 +### チャネルごととアカウントごとの例 ```yaml channels: @@ -318,7 +321,7 @@ channels: accounts: ops: heartbeat: - showAlerts: false # ops アカウントに対してのみアラートを抑止 + showAlerts: false # ops アカウントのみアラートを抑制 telegram: heartbeat: showOk: true @@ -327,30 +330,30 @@ channels: ### よくあるパターン | 目的 | 設定 | -| ---------------------------------------- | ---------------------------------------------------------------------------------------- | -| デフォルト動作（OK は無言、アラートは送信） | _(設定不要)_ | -| 完全に無言（メッセージなし、indicator なし） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | +| --- | --- | +| デフォルト動作（OK は無言、アラートは有効） | _(設定不要)_ | +| 完全に無音（メッセージなし、indicator なし） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | | indicator のみ（メッセージなし） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | -| 1 つのチャネルでのみ OK を表示 | `channels.telegram.heartbeat: { showOk: true }` | +| 1つのチャネルでのみ OK を表示 | `channels.telegram.heartbeat: { showOk: true }` | ## HEARTBEAT.md（任意） -ワークスペースに `HEARTBEAT.md` ファイルが存在する場合、デフォルトプロンプトは -エージェントにそれを読むよう指示します。これは「heartbeat チェックリスト」と考えてください。小さく、安定していて、 -30 分ごとに含めても安全なものが理想です。 +ワークスペースに `HEARTBEAT.md` ファイルがある場合、デフォルトプロンプトは +エージェントにそれを読むよう指示します。これは「heartbeat チェックリスト」と考えてください: 小さく、安定していて、 +30分ごとに含めても安全なものです。 -通常実行では、`HEARTBEAT.md` はデフォルトエージェントで heartbeat ガイダンスが -有効な場合にのみ注入されます。 -間隔を `0m` にして heartbeat を無効にするか、 -`includeSystemPromptSection: false` を設定すると、通常のブートストラップ -コンテキストからは除外されます。 +通常実行では、`HEARTBEAT.md` は +デフォルトエージェントで heartbeat ガイダンスが有効な場合にのみ注入されます。 +頻度を `0m` にして heartbeat cadence を無効にするか、 +`includeSystemPromptSection: false` を設定すると、通常の bootstrap +コンテキストから除外されます。 -`HEARTBEAT.md` が存在しても実質的に空（空行と `# Heading` のような markdown -見出しだけ）の場合、OpenClaw は API 呼び出しを節約するため heartbeat 実行をスキップします。 +`HEARTBEAT.md` が存在していても、実質的に空（空行と +`# Heading` のような Markdown 見出しだけ）の場合、OpenClaw は API 呼び出しを節約するため heartbeat 実行をスキップします。 このスキップは `reason=empty-heartbeat-file` として報告されます。 -ファイルが存在しない場合でも heartbeat は実行され、何をするかはモデルが判断します。 +ファイルが存在しない場合でも、heartbeat は実行され、モデルが何をするかを判断します。 -プロンプト肥大化を避けるため、小さく保ってください（短いチェックリストやリマインダー）。 +プロンプト膨張を避けるため、小さく保ってください（短いチェックリストまたはリマインダー）。 `HEARTBEAT.md` の例: @@ -364,8 +367,8 @@ channels: ### `tasks:` ブロック -`HEARTBEAT.md` は、heartbeat 自体の中で間隔ベースの確認を行うための、 -小さな構造化 `tasks:` ブロックもサポートしています。 +`HEARTBEAT.md` は、heartbeat 自体の中で間隔ベースの +チェックを行うための小さな構造化 `tasks:` ブロックもサポートしています。 例: @@ -388,71 +391,70 @@ tasks: 動作: - OpenClaw は `tasks:` ブロックを解析し、各タスクをそれぞれの `interval` に対して確認します。 -- その tick で **期限到来** しているタスクだけが heartbeat プロンプトに含まれます。 -- 期限到来タスクがない場合、無駄なモデル呼び出しを避けるため heartbeat は完全にスキップされます（`reason=no-tasks-due`）。 -- `HEARTBEAT.md` のタスク以外の内容は保持され、期限到来タスクリストの後に追加コンテキストとして付加されます。 -- タスクの前回実行タイムスタンプはセッション状態（`heartbeatTaskState`）に保存されるため、通常の再起動をまたいでも間隔は維持されます。 -- タスクタイムスタンプが進むのは、heartbeat 実行が通常の応答経路を完了した後だけです。`empty-heartbeat-file` / `no-tasks-due` によるスキップ実行では、タスクは完了済みとして記録されません。 +- その tick で**期限が来ている**タスクだけが heartbeat プロンプトに含まれます。 +- 期限が来ているタスクがない場合、無駄なモデル呼び出しを避けるため、heartbeat は完全にスキップされます（`reason=no-tasks-due`）。 +- `HEARTBEAT.md` 内のタスク以外の内容は保持され、期限到来タスクリストの後に追加コンテキストとして付加されます。 +- タスクの最終実行タイムスタンプはセッション状態（`heartbeatTaskState`）に保存されるため、通常の再起動後も間隔が維持されます。 +- タスクのタイムスタンプが進むのは、heartbeat 実行が通常の返信パスを完了した後だけです。`empty-heartbeat-file` / `no-tasks-due` でスキップされた実行は、タスク完了として記録されません。 -タスクモードは、1 つの heartbeat ファイルに複数の定期チェックを持たせつつ、毎 tick ですべてのコストを払いたくない場合に便利です。 +タスクモードは、1つの heartbeat ファイルに複数の定期チェックを持たせつつ、毎 tick それらすべてのコストを払いたくない場合に便利です。 ### エージェントは HEARTBEAT.md を更新できますか？ -はい。そうするように指示すれば可能です。 +はい — そうするように指示すれば可能です。 -`HEARTBEAT.md` はエージェントのワークスペース内の通常のファイルなので、 -通常のチャットで次のように指示できます。 +`HEARTBEAT.md` はエージェントワークスペース内の通常のファイルなので、 +通常のチャットで、たとえば次のようにエージェントに指示できます: -- 「毎日のカレンダー確認を追加するように `HEARTBEAT.md` を更新して。」 -- 「もっと短くして受信箱のフォローアップに集中するよう `HEARTBEAT.md` を書き直して。」 +- 「毎日のカレンダーチェックを追加するように `HEARTBEAT.md` を更新して」 +- 「`HEARTBEAT.md` を、もっと短くして受信箱のフォローアップに集中する内容に書き直して」 -これを能動的に行いたい場合は、heartbeat プロンプトに次のような明示的な一文を -入れることもできます。「チェックリストが古くなったら、よりよいものに `HEARTBEAT.md` -を更新すること。」 +これを積極的に行わせたい場合は、heartbeat プロンプトに +「チェックリストが古くなったら、より良いものに `HEARTBEAT.md` +を更新すること」のような明示的な一文を含めることもできます。 -安全上の注意: 秘密情報（API キー、電話番号、プライベートトークン）は -`HEARTBEAT.md` に入れないでください。これはプロンプトコンテキストの一部になります。 +安全上の注意: `HEARTBEAT.md` にシークレット（API キー、電話番号、秘密トークン）を入れないでください — +これはプロンプトコンテキストの一部になります。 ## 手動 wake（オンデマンド） -次のコマンドでシステムイベントをキューに積み、即時 heartbeat を発火できます。 +システムイベントをキューに入れ、すぐに heartbeat をトリガーするには次を実行します: ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -複数のエージェントに `heartbeat` が設定されている場合、手動 wake はそれらの -エージェント heartbeat をすべて即時実行します。 +複数のエージェントに `heartbeat` が設定されている場合、 +手動 wake はそれらの各エージェント heartbeat を即座に実行します。 -次回予定 tick まで待つには `--mode next-heartbeat` を使用してください。 +次の予定 tick を待つには `--mode next-heartbeat` を使用します。 -## Reasoning 配信（任意） +## reasoning 配信（任意） -デフォルトでは、heartbeat は最終的な「answer」ペイロードだけを配信します。 +デフォルトでは、heartbeat は最終的な「回答」ペイロードのみを配信します。 -透明性が必要な場合は、次を有効にしてください。 +透明性が必要な場合は、次を有効にします: - `agents.defaults.heartbeat.includeReasoning: true` 有効にすると、heartbeat は `Reasoning:` で始まる別メッセージも配信します -（`/reasoning on` と同じ形式）。これは、エージェントが複数のセッション / codex を管理していて、 -なぜあなたに ping することにしたのか見たい場合に便利です。 -ただし、望まない内部詳細がより多く漏れる可能性もあります。グループチャットでは -無効のままにしておくことを推奨します。 +（`/reasoning on` と同じ形式）。これは、エージェントが複数のセッション/codex を管理していて、 +なぜあなたに通知すると判断したのかを見たい場合に便利です — +ただし、望まない内部詳細まで漏れる可能性もあります。グループチャットでは通常、無効のままにしておくことをおすすめします。 ## コスト意識 Heartbeat は完全なエージェントターンを実行します。間隔を短くするほどトークン消費は増えます。コストを下げるには: -- `isolatedSession: true` を使って会話履歴全体の送信を避ける（約 100K トークンから 1 回あたり約 2〜5K に削減）。 -- `lightContext: true` を使ってブートストラップファイルを `HEARTBEAT.md` だけに制限する。 +- 完全な会話履歴を送らないように `isolatedSession: true` を使用する（実行あたりおよそ 100K トークンから 2-5K に削減）。 +- bootstrap ファイルを `HEARTBEAT.md` のみに制限するため `lightContext: true` を使用する。 - より安価な `model` を設定する（例: `ollama/llama3.2:1b`）。 - `HEARTBEAT.md` を小さく保つ。 -- 内部状態更新だけが目的なら `target: "none"` を使う。 +- 内部状態更新だけが必要なら `target: "none"` を使用する。 ## 関連 -- [Automation & Tasks](/ja-JP/automation) — 自動化の仕組み全体の概要 -- [Background Tasks](/ja-JP/automation/tasks) — 切り離された作業の追跡方法 -- [Timezone](/ja-JP/concepts/timezone) — タイムゾーンが heartbeat スケジューリングに与える影響 +- [Automation & Tasks](/ja-JP/automation) — すべての自動化メカニズムの概要 +- [Background Tasks](/ja-JP/automation/tasks) — 切り離された作業がどのように追跡されるか +- [Timezone](/ja-JP/concepts/timezone) — タイムゾーンが heartbeat スケジューリングにどう影響するか - [Troubleshooting](/ja-JP/automation/cron-jobs#troubleshooting) — 自動化の問題をデバッグする方法 diff --git a/docs/ja-JP/gateway/protocol.md b/docs/ja-JP/gateway/protocol.md index 183716017..df29af88d 100644 --- a/docs/ja-JP/gateway/protocol.md +++ b/docs/ja-JP/gateway/protocol.md @@ -6,25 +6,22 @@ read_when: summary: 'Gateway WebSocketプロトコル: ハンドシェイク、フレーム、バージョニング' title: Gatewayプロトコル x-i18n: - generated_at: "2026-04-08T02:16:21Z" + generated_at: "2026-04-11T02:44:57Z" model: gpt-5.4 provider: openai - source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a + source_hash: 83c820c46d4803d571c770468fd6782619eaa1dca253e156e8087dec735c127f source_path: gateway/protocol.md workflow: 15 --- # Gatewayプロトコル（WebSocket） -Gateway WSプロトコルは、OpenClawの**単一のコントロールプレーン + ノード転送**です。 -すべてのクライアント（CLI、web UI、macOSアプリ、iOS/Androidノード、ヘッドレス -ノード）は、WebSocket経由で接続し、ハンドシェイク時に自分の**role**と**scope**を -宣言します。 +Gateway WSプロトコルは、OpenClawの**単一のコントロールプレーン + ノードトランスポート**です。すべてのクライアント（CLI、web UI、macOSアプリ、iOS/Androidノード、ヘッドレスノード）はWebSocket経由で接続し、ハンドシェイク時に自分の**role** + **scope**を宣言します。 -## 転送 +## トランスポート -- WebSocket、JSONペイロードを含むテキストフレーム。 -- 最初のフレームは**必ず** `connect` リクエストでなければなりません。 +- WebSocket、JSONペイロードを持つテキストフレーム。 +- 最初のフレームは**必ず**`connect`リクエストでなければなりません。 ## ハンドシェイク（connect） @@ -84,7 +81,7 @@ Gateway → Client: } ``` -デバイストークンが発行される場合、`hello-ok` には次も含まれます: +デバイストークンが発行されると、`hello-ok`には次も含まれます。 ```json { @@ -96,8 +93,7 @@ Gateway → Client: } ``` -信頼されたブートストラップ引き継ぎの間、`hello-ok.auth` には -`deviceTokens` に追加の制限付きroleエントリが含まれる場合もあります: +信頼されたbootstrap handoffの間、`hello-ok.auth`には`deviceTokens`内に追加の制限付きroleエントリが含まれることもあります。 ```json { @@ -116,15 +112,9 @@ Gateway → Client: } ``` -組み込みのnode/operatorブートストラップフローでは、主nodeトークンは -`scopes: []` のままで、引き渡されたoperatorトークンはブートストラップ -operator許可リスト（`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`）に制限されたままです。 -ブートストラップのscopeチェックは引き続きroleプレフィックス付きです: -operatorエントリはoperatorリクエストのみを満たし、non-operator -roleは引き続き自身のroleプレフィックス配下のscopeを必要とします。 +組み込みのnode/operator bootstrapフローでは、主要なnodeトークンは`scopes: []`のままで、引き渡されるoperatorトークンはbootstrap operator allowlist（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）に制限されたままです。bootstrap scopeチェックは引き続きrole接頭辞付きです。operatorエントリはoperatorリクエストだけを満たし、operator以外のroleは引き続き自分自身のrole接頭辞配下のscopeが必要です。 -### Nodeの例 +### ノードの例 ```json { @@ -161,18 +151,18 @@ roleは引き続き自身のroleプレフィックス配下のscopeを必要と ## フレーミング -- **リクエスト**: `{type:"req", id, method, params}` -- **レスポンス**: `{type:"res", id, ok, payload|error}` -- **イベント**: `{type:"event", event, payload, seq?, stateVersion?}` +- **Request**: `{type:"req", id, method, params}` +- **Response**: `{type:"res", id, ok, payload|error}` +- **Event**: `{type:"event", event, payload, seq?, stateVersion?}` -副作用のあるメソッドには**冪等性キー**が必要です（スキーマを参照）。 +副作用を持つメソッドには**idempotency key**が必要です（スキーマを参照）。 ## role + scope ### role -- `operator` = コントロールプレーンクライアント（CLI/UI/自動化）。 -- `node` = 機能ホスト（camera/screen/canvas/system.run）。 +- `operator` = コントロールプレーンクライアント（CLI/UI/automation）。 +- `node` = capability host（camera/screen/canvas/system.run）。 ### scope（operator） @@ -185,304 +175,232 @@ roleは引き続き自身のroleプレフィックス配下のscopeを必要と - `operator.pairing` - `operator.talk.secrets` -`includeSecrets: true` を伴う `talk.config` には `operator.talk.secrets` -（または `operator.admin`）が必要です。 +`includeSecrets: true`付きの`talk.config`には`operator.talk.secrets`（または`operator.admin`）が必要です。 -プラグイン登録されたGateway RPCメソッドは独自のoperator scopeを要求する場合がありますが、 -予約済みのコアadminプレフィックス（`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`）は常に `operator.admin` に解決されます。 +プラグイン登録されたGateway RPCメソッドは独自のoperator scopeを要求できますが、予約済みのコア管理者接頭辞（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は常に`operator.admin`に解決されます。 -メソッドscopeは最初のゲートにすぎません。`chat.send` を通じて到達する -一部のスラッシュコマンドには、さらに厳しいコマンドレベルのチェックが適用されます。 -たとえば、永続的な `/config set` と `/config unset` の書き込みには -`operator.admin` が必要です。 +メソッドscopeは最初のゲートにすぎません。`chat.send`経由で到達する一部のスラッシュコマンドには、その上にさらに厳しいコマンドレベルのチェックが適用されます。たとえば、永続的な`/config set`と`/config unset`の書き込みには`operator.admin`が必要です。 -`node.pair.approve` には、ベースメソッドscopeに加えて承認時の追加scopeチェックもあります: +`node.pair.approve`にも、ベースメソッドscopeに加えて追加の承認時scopeチェックがあります。 - コマンドなしのリクエスト: `operator.pairing` -- non-exec nodeコマンドを伴うリクエスト: `operator.pairing` + `operator.write` -- `system.run`, `system.run.prepare`, `system.which` を含むリクエスト: +- non-execノードコマンド付きのリクエスト: `operator.pairing` + `operator.write` +- `system.run`、`system.run.prepare`、または`system.which`を含むリクエスト: `operator.pairing` + `operator.admin` ### caps/commands/permissions（node） -ノードは接続時に機能クレームを宣言します: +ノードは接続時にcapability claimを宣言します。 -- `caps`: 高レベルな機能カテゴリ。 -- `commands`: invoke用のコマンド許可リスト。 -- `permissions`: 詳細なトグル（例: `screen.record`, `camera.capture`）。 +- `caps`: 高レベルのcapabilityカテゴリ。 +- `commands`: invoke用のコマンドallowlist。 +- `permissions`: 粒度の細かいトグル（例: `screen.record`、`camera.capture`）。 -Gatewayはこれらを**クレーム**として扱い、サーバー側の許可リストを適用します。 +Gatewayはこれらを**claim**として扱い、サーバー側allowlistを強制します。 ## プレゼンス -- `system-presence` はデバイスアイデンティティをキーとしたエントリを返します。 -- プレゼンスエントリには `deviceId`, `roles`, `scopes` が含まれるため、UIは - 同一デバイスが **operator** と **node** の両方として接続していても - 1行で表示できます。 +- `system-presence`はデバイスIDをキーとするエントリを返します。 +- プレゼンスエントリには`deviceId`、`roles`、`scopes`が含まれるため、UIはそのデバイスが**operator**と**node**の両方として接続していても1行で表示できます。 -## よく使われるRPCメソッドファミリー +## 一般的なRPCメソッドファミリー -このページは生成された完全なダンプではありませんが、公開WSサーフェスは -上記のハンドシェイク/認証の例よりも広範です。これらは現在Gatewayが公開している -主なメソッドファミリーです。 +このページは生成された完全ダンプではありませんが、公開WSサーフェスは上記のハンドシェイク/認証の例よりも広範です。以下は、現在Gatewayが公開している主なメソッドファミリーです。 -`hello-ok.features.methods` は、 -`src/gateway/server-methods-list.ts` と、読み込まれたプラグイン/チャネルの -メソッドエクスポートから構築された保守的な検出リストです。 -これを機能検出として扱ってください。`src/gateway/server-methods/*.ts` に実装された -呼び出し可能なすべてのヘルパーの生成ダンプではありません。 +`hello-ok.features.methods`は、`src/gateway/server-methods-list.ts`と、読み込まれたプラグイン/チャンネルのメソッドエクスポートから構築される保守的なディスカバリーリストです。これは機能検出として扱ってください。`src/gateway/server-methods/*.ts`で実装されている、呼び出し可能なすべてのヘルパーの生成ダンプではありません。 -### systemとidentity +### システムとID -- `health` は、キャッシュされた、または新たにプローブされたGatewayヘルススナップショットを返します。 -- `status` は `/status` スタイルのGatewayサマリーを返します。機密フィールドは - admin scopeを持つoperatorクライアントにのみ含まれます。 -- `gateway.identity.get` は、relayおよびpairingフローで使われるGatewayデバイスIDを返します。 -- `system-presence` は、接続中のoperator/nodeデバイスの現在のプレゼンススナップショットを返します。 -- `system-event` はsystemイベントを追加し、プレゼンスコンテキストを更新/ブロードキャストできます。 -- `last-heartbeat` は、最後に永続化されたheartbeatイベントを返します。 -- `set-heartbeats` は、Gatewayでのheartbeat処理を切り替えます。 +- `health`は、キャッシュ済みまたは新たにプローブしたGatewayのhealthスナップショットを返します。 +- `status`は`/status`形式のGateway概要を返します。機密フィールドはadmin scopeを持つoperatorクライアントにのみ含まれます。 +- `gateway.identity.get`は、relayおよびpairingフローで使用されるGatewayデバイスIDを返します。 +- `system-presence`は、接続中のoperator/nodeデバイスの現在のプレゼンススナップショットを返します。 +- `system-event`はシステムイベントを追加し、プレゼンスコンテキストを更新/ブロードキャストできます。 +- `last-heartbeat`は、最新の永続化されたheartbeatイベントを返します。 +- `set-heartbeats`は、Gateway上のheartbeat処理を切り替えます。 -### modelとusage +### モデルと使用量 -- `models.list` は、ランタイムで許可されたモデルカタログを返します。 -- `usage.status` は、プロバイダー使用量ウィンドウ/残りクォータのサマリーを返します。 -- `usage.cost` は、日付範囲の集計済みコスト使用量サマリーを返します。 -- `doctor.memory.status` は、アクティブなデフォルトagentワークスペース向けの - ベクターメモリ / embedding準備状態を返します。 -- `sessions.usage` は、セッションごとの使用量サマリーを返します。 -- `sessions.usage.timeseries` は、1つのセッションの時系列使用量を返します。 -- `sessions.usage.logs` は、1つのセッションの使用量ログエントリを返します。 +- `models.list`は、ランタイムで許可されたモデルカタログを返します。 +- `usage.status`は、プロバイダーの使用ウィンドウ/残りクォータの概要を返します。 +- `usage.cost`は、指定した日付範囲の集計済みコスト使用量サマリーを返します。 +- `doctor.memory.status`は、アクティブなデフォルトエージェントワークスペースにおけるvector-memory / embedding readinessを返します。 +- `sessions.usage`は、セッションごとの使用量サマリーを返します。 +- `sessions.usage.timeseries`は、1つのセッションの時系列使用量を返します。 +- `sessions.usage.logs`は、1つのセッションの使用量ログエントリを返します。 -### チャネルとログインヘルパー +### チャンネルとログインヘルパー -- `channels.status` は、組み込み + バンドルされたチャネル/プラグインのステータスサマリーを返します。 -- `channels.logout` は、ログアウト対応のチャネルで特定のチャネル/アカウントをログアウトします。 -- `web.login.start` は、現在のQR対応webチャネルプロバイダー向けのQR/webログインフローを開始します。 -- `web.login.wait` は、そのQR/webログインフローの完了を待ち、成功時にチャネルを開始します。 -- `push.test` は、登録済みiOSノードにテストAPNsプッシュを送信します。 -- `voicewake.get` は、保存されたウェイクワードトリガーを返します。 -- `voicewake.set` は、ウェイクワードトリガーを更新し、その変更をブロードキャストします。 +- `channels.status`は、組み込み + 同梱チャンネル/プラグインのステータスサマリーを返します。 +- `channels.logout`は、そのチャンネルがlogoutをサポートしている場合、特定のチャンネル/アカウントをログアウトします。 +- `web.login.start`は、現在のQR対応webチャンネルプロバイダー向けにQR/webログインフローを開始します。 +- `web.login.wait`は、そのQR/webログインフローの完了を待ち、成功したらチャンネルを起動します。 +- `push.test`は、登録済みiOSノードにテストAPNs pushを送信します。 +- `voicewake.get`は、保存されているウェイクワードトリガーを返します。 +- `voicewake.set`は、ウェイクワードトリガーを更新し、変更をブロードキャストします。 ### メッセージングとログ -- `send` は、chat runner外でのチャネル/アカウント/threadターゲット送信向けの - 直接のアウトバウンド配信RPCです。 -- `logs.tail` は、カーソル/上限および最大バイト制御付きで、 - 設定されたGatewayファイルログの末尾を返します。 +- `send`は、chat runnerの外で、チャンネル/アカウント/スレッド対象への送信を行う直接のアウトバウンド配信RPCです。 +- `logs.tail`は、設定済みGatewayファイルログのtailを、cursor/limitおよびmax-byte制御付きで返します。 ### TalkとTTS -- `talk.config` は、有効なTalk設定ペイロードを返します。`includeSecrets` - には `operator.talk.secrets`（または `operator.admin`）が必要です。 -- `talk.mode` は、WebChat/Control UIクライアント向けの現在のTalkモード状態を設定/ブロードキャストします。 -- `talk.speak` は、アクティブなTalk speechプロバイダーを通じて音声を合成します。 -- `tts.status` は、TTS有効状態、アクティブプロバイダー、フォールバックプロバイダー、 - およびプロバイダー設定状態を返します。 -- `tts.providers` は、表示可能なTTSプロバイダーのインベントリを返します。 -- `tts.enable` と `tts.disable` は、TTS設定状態を切り替えます。 -- `tts.setProvider` は、優先TTSプロバイダーを更新します。 -- `tts.convert` は、単発のtext-to-speech変換を実行します。 +- `talk.config`は、有効なTalk設定ペイロードを返します。`includeSecrets`には`operator.talk.secrets`（または`operator.admin`）が必要です。 +- `talk.mode`は、WebChat/Control UIクライアント向けに現在のTalkモード状態を設定/ブロードキャストします。 +- `talk.speak`は、アクティブなTalk speech providerを通じて音声を合成します。 +- `tts.status`は、TTSの有効状態、アクティブなプロバイダー、フォールバックプロバイダー、プロバイダー設定状態を返します。 +- `tts.providers`は、表示可能なTTSプロバイダー一覧を返します。 +- `tts.enable`と`tts.disable`は、TTS設定状態を切り替えます。 +- `tts.setProvider`は、優先TTSプロバイダーを更新します。 +- `tts.convert`は、単発のtext-to-speech変換を実行します。 -### シークレット、設定、更新、およびウィザード +### Secret、設定、更新、ウィザード -- `secrets.reload` は、アクティブなSecretRefを再解決し、完全成功時にのみランタイムのシークレット状態を切り替えます。 -- `secrets.resolve` は、特定のコマンド/ターゲットセット向けにコマンド対象のシークレット割り当てを解決します。 -- `config.get` は、現在の設定スナップショットとハッシュを返します。 -- `config.set` は、検証済みの設定ペイロードを書き込みます。 -- `config.patch` は、部分的な設定更新をマージします。 -- `config.apply` は、完全な設定ペイロードを検証して置き換えます。 -- `config.schema` は、Control UIおよびCLIツールで使われるライブ設定スキーマペイロード - を返します: スキーマ、`uiHints`、バージョン、生成メタデータ。これには、ランタイムで - 読み込める場合のプラグイン + チャネルスキーマメタデータも含まれます。 - スキーマには、UIで使われるものと同じラベルおよびヘルプテキストから導出された - フィールド `title` / `description` メタデータが含まれます。これには、ネストしたobject、 - wildcard、array-item、および対応するフィールドドキュメントが存在する場合の - `anyOf` / `oneOf` / `allOf` 合成分岐も含まれます。 -- `config.schema.lookup` は、1つの設定パス向けのパススコープ付きlookupペイロードを返します: - 正規化されたパス、浅いスキーマノード、一致したhint + `hintPath`、および - UI/CLIドリルダウン向けの直接の子サマリーです。 - - Lookupスキーマノードは、ユーザー向けドキュメントおよび一般的な検証フィールドを保持します: - `title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, - 数値/文字列/配列/objectの境界、および - `additionalProperties`, `deprecated`, `readOnly`, `writeOnly` のような真偽値フラグ。 - - 子サマリーは `key`、正規化された `path`、`type`、`required`、 - `hasChildren`、および一致した `hint` / `hintPath` を公開します。 -- `update.run` は、Gateway更新フローを実行し、更新自体が成功した場合にのみ再起動をスケジュールします。 -- `wizard.start`、`wizard.next`、`wizard.status`、`wizard.cancel` は、 - オンボーディングウィザードをWS RPC経由で公開します。 +- `secrets.reload`は、アクティブなSecretRefを再解決し、完全成功時のみランタイムsecret状態を切り替えます。 +- `secrets.resolve`は、特定のコマンド/ターゲットセットに対するコマンド対象secret割り当てを解決します。 +- `config.get`は、現在の設定スナップショットとハッシュを返します。 +- `config.set`は、検証済みの設定ペイロードを書き込みます。 +- `config.patch`は、部分的な設定更新をマージします。 +- `config.apply`は、完全な設定ペイロードを検証して置き換えます。 +- `config.schema`は、Control UIおよびCLIツールで使用されるライブ設定スキーマペイロードを返します。これには、スキーマ、`uiHints`、バージョン、生成メタデータが含まれ、ランタイムで読み込める場合はプラグイン + チャンネルのスキーマメタデータも含まれます。スキーマには、ネストしたオブジェクト、ワイルドカード、配列項目、`anyOf` / `oneOf` / `allOf`の分岐で一致するフィールドドキュメントが存在する場合、UIで使われるのと同じラベルおよびヘルプテキストから導出されたフィールド`title` / `description`メタデータが含まれます。 +- `config.schema.lookup`は、1つの設定パスに対するパススコープのlookupペイロードを返します。これには、正規化されたパス、浅いスキーマノード、一致したhint + `hintPath`、およびUI/CLIドリルダウン用の直下の子サマリーが含まれます。 + - Lookupスキーマノードは、ユーザー向けドキュメントと一般的な検証フィールドを保持します: `title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数値/文字列/配列/オブジェクトの境界、および`additionalProperties`、`deprecated`、`readOnly`、`writeOnly`のようなbooleanフラグ。 + - 子サマリーには、`key`、正規化された`path`、`type`、`required`、`hasChildren`、および一致した`hint` / `hintPath`が含まれます。 +- `update.run`は、Gateway更新フローを実行し、更新自体が成功した場合にのみ再起動をスケジュールします。 +- `wizard.start`、`wizard.next`、`wizard.status`、`wizard.cancel`は、WS RPC経由でオンボーディングウィザードを公開します。 ### 既存の主要ファミリー -#### agentとworkspaceヘルパー +#### エージェントとワークスペースヘルパー -- `agents.list` は、設定済みagentエントリを返します。 -- `agents.create`、`agents.update`、`agents.delete` は、agentレコードと - workspace配線を管理します。 -- `agents.files.list`、`agents.files.get`、`agents.files.set` は、 - agent向けに公開されたブートストラップworkspaceファイルを管理します。 -- `agent.identity.get` は、agentまたはセッションの有効なassistant identityを返します。 -- `agent.wait` は、実行完了を待ち、利用可能な場合は終端スナップショットを返します。 +- `agents.list`は、設定済みエージェントエントリを返します。 +- `agents.create`、`agents.update`、`agents.delete`は、エージェントレコードとワークスペース配線を管理します。 +- `agents.files.list`、`agents.files.get`、`agents.files.set`は、エージェント向けに公開されるbootstrapワークスペースファイルを管理します。 +- `agent.identity.get`は、エージェントまたはセッションに対する有効なassistant IDを返します。 +- `agent.wait`は、実行完了を待ち、利用可能な場合は終端スナップショットを返します。 #### セッション制御 -- `sessions.list` は、現在のセッションインデックスを返します。 -- `sessions.subscribe` と `sessions.unsubscribe` は、現在のWSクライアントの - セッション変更イベント購読を切り替えます。 -- `sessions.messages.subscribe` と `sessions.messages.unsubscribe` は、 - 1つのセッションのトランスクリプト/メッセージイベント購読を切り替えます。 -- `sessions.preview` は、特定のセッションキー向けに制限付きトランスクリプトプレビューを返します。 -- `sessions.resolve` は、セッションターゲットを解決または正規化します。 -- `sessions.create` は、新しいセッションエントリを作成します。 -- `sessions.send` は、既存のセッションにメッセージを送信します。 -- `sessions.steer` は、アクティブなセッション向けの中断して誘導するバリアントです。 -- `sessions.abort` は、セッションのアクティブな作業を中止します。 -- `sessions.patch` は、セッションメタデータ/上書きを更新します。 -- `sessions.reset`、`sessions.delete`、`sessions.compact` は、セッション保守を実行します。 -- `sessions.get` は、保存済みの完全なセッション行を返します。 -- chat実行では引き続き `chat.history`、`chat.send`、`chat.abort`、`chat.inject` を使用します。 -- `chat.history` は、UIクライアント向けに表示正規化されています: インラインディレクティブタグは - 表示テキストから削除され、プレーンテキストのツール呼び出しXMLペイロード - （`...`、`...`、 - `...`、`...`、 - および切り詰められたツール呼び出しブロックを含む）と、 - 漏れ出したASCII/全角のモデル制御トークンは削除され、正確に `NO_REPLY` / - `no_reply` である純粋なsilent-token assistant行は省略され、 - 過大な行はプレースホルダーに置き換えられる場合があります。 +- `sessions.list`は、現在のセッションインデックスを返します。 +- `sessions.subscribe`と`sessions.unsubscribe`は、現在のWSクライアントに対するセッション変更イベントのサブスクリプションを切り替えます。 +- `sessions.messages.subscribe`と`sessions.messages.unsubscribe`は、1つのセッションに対するtranscript/messageイベントのサブスクリプションを切り替えます。 +- `sessions.preview`は、特定のセッションキーに対する制限付きtranscriptプレビューを返します。 +- `sessions.resolve`は、セッションターゲットを解決または正規化します。 +- `sessions.create`は、新しいセッションエントリを作成します。 +- `sessions.send`は、既存のセッションにメッセージを送信します。 +- `sessions.steer`は、アクティブなセッションに対するinterrupt-and-steerバリアントです。 +- `sessions.abort`は、セッションのアクティブな処理を中止します。 +- `sessions.patch`は、セッションメタデータ/overrideを更新します。 +- `sessions.reset`、`sessions.delete`、`sessions.compact`は、セッションメンテナンスを実行します。 +- `sessions.get`は、保存されている完全なセッション行を返します。 +- chat実行では、引き続き`chat.history`、`chat.send`、`chat.abort`、`chat.inject`を使用します。 +- `chat.history`はUIクライアント向けに表示用に正規化されます。インラインdirectiveタグは表示テキストから除去され、プレーンテキストのtool-call XMLペイロード（`...`、`...`、`...`、`...`、および切り詰められたtool-callブロックを含む）や漏れたASCII/全角のモデル制御トークンは除去され、正確に`NO_REPLY` / `no_reply`である純粋なsilent-token assistant行は省略され、過大な行はプレースホルダーに置き換えられることがあります。 #### デバイスpairingとデバイストークン -- `device.pair.list` は、保留中および承認済みのpair済みデバイスを返します。 -- `device.pair.approve`、`device.pair.reject`、`device.pair.remove` は、 - デバイスpairingレコードを管理します。 -- `device.token.rotate` は、pairing済みデバイストークンを承認済みroleおよび - scopeの範囲内でローテーションします。 -- `device.token.revoke` は、pairing済みデバイストークンを失効させます。 +- `device.pair.list`は、保留中および承認済みのペアリング済みデバイスを返します。 +- `device.pair.approve`、`device.pair.reject`、`device.pair.remove`は、デバイスペアリングレコードを管理します。 +- `device.token.rotate`は、承認済みのroleおよびscopeの範囲内でペアリング済みデバイストークンをローテーションします。 +- `device.token.revoke`は、ペアリング済みデバイストークンを失効させます。 -#### node pairing、invoke、および保留中作業 +#### ノードpairing、invoke、および保留中の作業 -- `node.pair.request`、`node.pair.list`、`node.pair.approve`、 - `node.pair.reject`、`node.pair.verify` は、node pairingとブートストラップ - 検証を扱います。 -- `node.list` と `node.describe` は、既知/接続中のノード状態を返します。 -- `node.rename` は、pairing済みノードラベルを更新します。 -- `node.invoke` は、接続中ノードにコマンドを転送します。 -- `node.invoke.result` は、invokeリクエストの結果を返します。 -- `node.event` は、ノード起点イベントをGatewayへ戻します。 -- `node.canvas.capability.refresh` は、スコープ付きcanvas-capabilityトークンを更新します。 -- `node.pending.pull` と `node.pending.ack` は、接続中ノードのキューAPIです。 -- `node.pending.enqueue` と `node.pending.drain` は、 - オフライン/切断中ノード向けの永続保留作業を管理します。 +- `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.verify`は、ノードpairingとbootstrap検証を扱います。 +- `node.list`と`node.describe`は、既知/接続済みノードの状態を返します。 +- `node.rename`は、ペアリング済みノードのラベルを更新します。 +- `node.invoke`は、接続済みノードにコマンドを転送します。 +- `node.invoke.result`は、invokeリクエストの結果を返します。 +- `node.event`は、ノード起点のイベントをGatewayへ戻します。 +- `node.canvas.capability.refresh`は、スコープ付きcanvas-capabilityトークンを更新します。 +- `node.pending.pull`と`node.pending.ack`は、接続済みノード向けのキューAPIです。 +- `node.pending.enqueue`と`node.pending.drain`は、オフライン/切断中ノード向けの永続的な保留作業を管理します。 #### 承認ファミリー -- `exec.approval.request`、`exec.approval.get`、`exec.approval.list`、 - `exec.approval.resolve` は、単発のexec承認リクエストと、 - 保留中承認の検索/再生を扱います。 -- `exec.approval.waitDecision` は、1件の保留中exec承認を待機し、 - 最終判断を返します（タイムアウト時は `null`）。 -- `exec.approvals.get` と `exec.approvals.set` は、Gateway exec承認 - ポリシースナップショットを管理します。 -- `exec.approvals.node.get` と `exec.approvals.node.set` は、 - ノードリレーコマンド経由でnodeローカルのexec承認ポリシーを管理します。 -- `plugin.approval.request`、`plugin.approval.list`、 - `plugin.approval.waitDecision`、`plugin.approval.resolve` は、 - プラグイン定義の承認フローを扱います。 +- `exec.approval.request`、`exec.approval.get`、`exec.approval.list`、`exec.approval.resolve`は、単発のexec承認リクエストと、保留中の承認のlookup/replayを扱います。 +- `exec.approval.waitDecision`は、1件の保留中exec承認を待機し、最終決定を返します（タイムアウト時は`null`）。 +- `exec.approvals.get`と`exec.approvals.set`は、Gatewayのexec承認ポリシースナップショットを管理します。 +- `exec.approvals.node.get`と`exec.approvals.node.set`は、ノードrelayコマンド経由でノードローカルexec承認ポリシーを管理します。 +- `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision`、`plugin.approval.resolve`は、プラグイン定義の承認フローを扱います。 #### その他の主要ファミリー - automation: - - `wake` は、即時または次のheartbeatでのwakeテキスト注入をスケジュールします - - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, - `cron.run`, `cron.runs` -- Skills/ツール: `skills.*`, `tools.catalog`, `tools.effective` + - `wake`は、即時または次回heartbeat時のwakeテキスト注入をスケジュールします + - `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` +- skills/tools: `commands.list`、`skills.*`、`tools.catalog`、`tools.effective` ### 一般的なイベントファミリー -- `chat`: `chat.inject` などの、UI chat更新やその他のトランスクリプト専用chatイベント。 -- `session.message` と `session.tool`: 購読されたセッション向けの - トランスクリプト/イベントストリーム更新。 -- `sessions.changed`: セッションインデックスまたはメタデータが変更された。 -- `presence`: systemプレゼンススナップショット更新。 -- `tick`: 定期的なkeepalive / 生存確認イベント。 -- `health`: Gatewayヘルススナップショット更新。 +- `chat`: `chat.inject`やその他のtranscript専用chatイベントなどのUI chat更新。 +- `session.message`と`session.tool`: サブスクライブされたセッションのtranscript/event-stream更新。 +- `sessions.changed`: セッションインデックスまたはメタデータが変更されたとき。 +- `presence`: システムプレゼンススナップショット更新。 +- `tick`: 定期的なkeepalive / livenessイベント。 +- `health`: Gateway healthスナップショット更新。 - `heartbeat`: heartbeatイベントストリーム更新。 - `cron`: cron実行/ジョブ変更イベント。 - `shutdown`: Gatewayシャットダウン通知。 -- `node.pair.requested` / `node.pair.resolved`: node pairingライフサイクル。 -- `node.invoke.request`: node invokeリクエストのブロードキャスト。 -- `device.pair.requested` / `device.pair.resolved`: pair済みデバイスライフサイクル。 -- `voicewake.changed`: ウェイクワードトリガー設定が変更された。 -- `exec.approval.requested` / `exec.approval.resolved`: exec承認 - ライフサイクル。 -- `plugin.approval.requested` / `plugin.approval.resolved`: プラグイン承認 - ライフサイクル。 +- `node.pair.requested` / `node.pair.resolved`: ノードpairingライフサイクル。 +- `node.invoke.request`: ノードinvokeリクエストのブロードキャスト。 +- `device.pair.requested` / `device.pair.resolved`: ペアリング済みデバイスのライフサイクル。 +- `voicewake.changed`: ウェイクワードトリガー設定が変更されたとき。 +- `exec.approval.requested` / `exec.approval.resolved`: exec承認ライフサイクル。 +- `plugin.approval.requested` / `plugin.approval.resolved`: プラグイン承認ライフサイクル。 -### nodeヘルパーメソッド +### ノードヘルパーメソッド -- ノードは、自動許可チェック向けの現在のskill実行ファイル一覧を取得するために - `skills.bins` を呼び出せます。 +- ノードは、auto-allowチェックのために、現在のskill実行ファイル一覧を取得する`skills.bins`を呼び出せます。 ### operatorヘルパーメソッド -- operatorは、agent向けのランタイムツールカタログを取得するために - `tools.catalog`（`operator.read`）を呼び出せます。レスポンスには、グループ化された - ツールと由来メタデータが含まれます: - - `source`: `core` または `plugin` - - `pluginId`: `source="plugin"` のときのプラグイン所有者 - - `optional`: プラグインツールがオプションかどうか -- operatorは、セッションのランタイム有効ツール - インベントリを取得するために `tools.effective`（`operator.read`）を呼び出せます。 - - `sessionKey` は必須です。 - - Gatewayは、呼び出し元が指定した認証や配信コンテキストを受け取る代わりに、 - 信頼できるランタイムコンテキストをサーバー側でセッションから導出します。 - - レスポンスはセッションスコープであり、core、plugin、channelツールを含む、 - 現在アクティブな会話で今すぐ使えるものを反映します。 -- operatorは、agent向けの表示可能なskillインベントリを取得するために - `skills.status`（`operator.read`）を呼び出せます。 - - `agentId` は任意です。省略するとデフォルトagent workspaceを読み取ります。 - - レスポンスには、rawシークレット値を公開することなく、 - 適格性、不足している要件、設定チェック、およびサニタイズ済みinstall optionsが含まれます。 -- operatorは、ClawHub検出メタデータ向けに `skills.search` と `skills.detail` - （`operator.read`）を呼び出せます。 -- operatorは、2つのモードで `skills.install`（`operator.admin`）を呼び出せます: - - ClawHubモード: `{ source: "clawhub", slug, version?, force? }` は、 - デフォルトagent workspaceの `skills/` ディレクトリにskillフォルダーをインストールします。 - - Gateway installerモード: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` - は、Gatewayホスト上で宣言された `metadata.openclaw.install` アクションを実行します。 -- operatorは、2つのモードで `skills.update`（`operator.admin`）を呼び出せます: - - ClawHubモードでは、1つの追跡対象slugまたはデフォルトagent workspace内の - すべての追跡対象ClawHubインストールを更新します。 - - Configモードでは、`enabled`、 - `apiKey`、`env` などの `skills.entries.` 値をパッチします。 +- operatorは、エージェントのランタイムコマンド一覧を取得するために`commands.list`（`operator.read`）を呼び出せます。 + - `agentId`は省略可能です。省略するとデフォルトのエージェントワークスペースを読み取ります。 + - `scope`は、主`name`がどのサーフェスを対象にするかを制御します: + - `text`は、先頭の`/`を除いた主テキストコマンドトークンを返します + - `native`およびデフォルトの`both`パスは、利用可能な場合にプロバイダー対応のnative名を返します + - `textAliases`は、`/model`や`/m`のような正確なスラッシュエイリアスを保持します。 + - `nativeName`は、存在する場合にプロバイダー対応のnativeコマンド名を保持します。 + - `provider`は省略可能で、native命名とnativeプラグインコマンドの可用性にのみ影響します。 + - `includeArgs=false`は、シリアライズされた引数メタデータをレスポンスから省略します。 +- operatorは、エージェントのランタイムツールカタログを取得するために`tools.catalog`（`operator.read`）を呼び出せます。レスポンスには、グループ化されたツールとprovenanceメタデータが含まれます。 + - `source`: `core`または`plugin` + - `pluginId`: `source="plugin"`のときのプラグイン所有者 + - `optional`: プラグインツールがoptionalかどうか +- operatorは、セッションに対するランタイム有効ツール一覧を取得するために`tools.effective`（`operator.read`）を呼び出せます。 + - `sessionKey`は必須です。 + - Gatewayは、呼び出し元から提供された認証や配信コンテキストを受け入れるのではなく、サーバー側でセッションから信頼済みランタイムコンテキストを導出します。 + - レスポンスはセッションスコープで、コア、プラグイン、チャンネルツールを含め、現在アクティブな会話で今使えるものを反映します。 +- operatorは、エージェントの表示可能なskill一覧を取得するために`skills.status`（`operator.read`）を呼び出せます。 + - `agentId`は省略可能です。省略するとデフォルトのエージェントワークスペースを読み取ります。 + - レスポンスには、raw secret値を公開せずに、適格性、不足要件、設定チェック、サニタイズ済みインストールオプションが含まれます。 +- operatorは、ClawHub discoveryメタデータのために`skills.search`と`skills.detail`（`operator.read`）を呼び出せます。 +- operatorは、`skills.install`（`operator.admin`）を2つのモードで呼び出せます。 + - ClawHubモード: `{ source: "clawhub", slug, version?, force? }`は、skillフォルダーをデフォルトのエージェントワークスペース`skills/`ディレクトリにインストールします。 + - Gateway installerモード: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`は、Gatewayホスト上で宣言された`metadata.openclaw.install`アクションを実行します。 +- operatorは、`skills.update`（`operator.admin`）を2つのモードで呼び出せます。 + - ClawHubモードは、デフォルトのエージェントワークスペース内で1つの追跡済みslugまたはすべての追跡済みClawHubインストールを更新します。 + - Configモードは、`enabled`、`apiKey`、`env`のような`skills.entries.`値をパッチします。 -## exec承認 +## Exec承認 -- execリクエストに承認が必要な場合、Gatewayは `exec.approval.requested` をブロードキャストします。 -- operatorクライアントは、`exec.approval.resolve` を呼び出して解決します - （`operator.approvals` scopeが必要）。 -- `host=node` の場合、`exec.approval.request` には `systemRunPlan` - （正規の `argv`/`cwd`/`rawCommand`/sessionメタデータ）が含まれていなければなりません。 - `systemRunPlan` がないリクエストは拒否されます。 -- 承認後、転送された `node.invoke system.run` 呼び出しは、その正規の - `systemRunPlan` を権威あるコマンド/cwd/sessionコンテキストとして再利用します。 -- 呼び出し元が prepare と最終的な承認済み `system.run` 転送の間で - `command`、`rawCommand`、`cwd`、`agentId`、`sessionKey` を変更した場合、 - Gatewayは変更されたペイロードを信頼せず、実行を拒否します。 +- execリクエストに承認が必要な場合、Gatewayは`exec.approval.requested`をブロードキャストします。 +- operatorクライアントは`exec.approval.resolve`を呼び出して解決します（`operator.approvals` scopeが必要）。 +- `host=node`の場合、`exec.approval.request`には`systemRunPlan`（正規化された`argv`/`cwd`/`rawCommand`/セッションメタデータ）が必須です。`systemRunPlan`が欠けているリクエストは拒否されます。 +- 承認後、転送される`node.invoke system.run`呼び出しは、その正規化された`systemRunPlan`を権威あるcommand/cwd/sessionコンテキストとして再利用します。 +- 呼び出し元がprepareから最終的な承認済み`system.run`転送までの間に`command`、`rawCommand`、`cwd`、`agentId`、または`sessionKey`を変更した場合、Gatewayは変更されたペイロードを信頼せずに実行を拒否します。 -## agent配信フォールバック +## エージェント配信フォールバック -- `agent` リクエストには、アウトバウンド配信を要求するための `deliver=true` を含めることができます。 -- `bestEffortDeliver=false` は厳格な動作を維持します: 解決不能または内部専用の配信先は `INVALID_REQUEST` を返します。 -- `bestEffortDeliver=true` は、外部配信可能ルートを解決できない場合 - （たとえば内部/webchatセッションや曖昧なマルチチャネル設定）に、 - セッション専用実行へのフォールバックを許可します。 +- `agent`リクエストには、アウトバウンド配信を要求するための`deliver=true`を含めることができます。 +- `bestEffortDeliver=false`は厳格な動作を維持します。未解決または内部専用の配信先ターゲットは`INVALID_REQUEST`を返します。 +- `bestEffortDeliver=true`は、外部配信可能ルートを解決できない場合（たとえば内部/webchatセッションや曖昧なマルチチャンネル設定）に、セッション専用実行へのフォールバックを許可します。 ## バージョニング -- `PROTOCOL_VERSION` は `src/gateway/protocol/schema.ts` にあります。 -- クライアントは `minProtocol` + `maxProtocol` を送信し、サーバーは不一致を拒否します。 +- `PROTOCOL_VERSION`は`src/gateway/protocol/schema.ts`にあります。 +- クライアントは`minProtocol` + `maxProtocol`を送信し、サーバーは不一致を拒否します。 - スキーマ + モデルはTypeBox定義から生成されます: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` @@ -490,107 +408,69 @@ Gatewayはこれらを**クレーム**として扱い、サーバー側の許可 ## 認証 -- 共有シークレットGateway認証では、設定された認証モードに応じて - `connect.params.auth.token` または - `connect.params.auth.password` を使用します。 -- Tailscale Serve のようなIDを伴うモード - （`gateway.auth.allowTailscale: true`）や、non-loopback - `gateway.auth.mode: "trusted-proxy"` では、 - `connect.params.auth.*` の代わりにリクエストヘッダーから接続認証チェックを満たします。 -- private-ingress `gateway.auth.mode: "none"` は、共有シークレット接続認証を - 完全にスキップします。このモードを公開/信頼できないingressで公開しないでください。 -- pairing後、Gatewayは接続のrole + scopeにスコープされた**デバイストークン**を発行します。 - これは `hello-ok.auth.deviceToken` で返され、クライアントは将来の接続のために - これを永続化する必要があります。 -- クライアントは、接続成功後に主要な `hello-ok.auth.deviceToken` を永続化する必要があります。 -- その**保存済み**デバイストークンで再接続する場合は、そのトークンに対して以前承認された - scopeセットも再利用する必要があります。これにより、すでに許可された - read/probe/statusアクセスが保持され、再接続時により狭い暗黙的な - admin専用scopeへ静かに縮小されるのを防げます。 -- 通常の接続認証の優先順位は、明示的な共有token/passwordが最優先で、次に - 明示的な `deviceToken`、次に保存済みのデバイスごとのトークン、 - 最後にブートストラップトークンです。 -- 追加の `hello-ok.auth.deviceTokens` エントリは、ブートストラップ引き継ぎトークンです。 - それらは、`wss://` や loopback/local pairing のような信頼できる転送上で - 接続がブートストラップ認証を使った場合にのみ永続化してください。 -- クライアントが**明示的な** `deviceToken` または明示的な `scopes` を指定した場合、 - その呼び出し元要求のscopeセットが権威を持ち続けます。キャッシュされたscopeが再利用されるのは、 - クライアントが保存済みのデバイスごとのトークンを再利用している場合だけです。 -- デバイストークンは `device.token.rotate` と - `device.token.revoke` でローテーション/失効できます - （`operator.pairing` scopeが必要）。 -- トークン発行/ローテーションは、そのデバイスのpairingエントリに記録された - 承認済みroleセットの範囲内に制限されます。トークンのローテーションで、 - pairing承認が一度も許可していないroleへデバイスを拡張することはできません。 -- pair済みデバイストークンセッションでは、呼び出し元が `operator.admin` も - 持っていない限り、デバイス管理は自己スコープになります: - non-admin呼び出し元は、自分**自身**のデバイスエントリのみを削除/失効/ローテーションできます。 -- `device.token.rotate` は、要求されたoperator scopeセットも - 呼び出し元の現在のセッションscopeに対してチェックします。non-admin呼び出し元は、 - 現在自分が保持しているものより広いoperator scopeセットへトークンをローテーションできません。 -- 認証失敗には `error.details.code` と復旧ヒントが含まれます: +- 共有シークレットのGateway認証では、設定された認証モードに応じて`connect.params.auth.token`または`connect.params.auth.password`を使用します。 +- Tailscale Serve（`gateway.auth.allowTailscale: true`）や、loopback以外での`gateway.auth.mode: "trusted-proxy"`のようなID付きモードでは、`connect.params.auth.*`ではなくリクエストヘッダーから接続認証チェックを満たします。 +- private-ingressの`gateway.auth.mode: "none"`は共有シークレット接続認証を完全にスキップします。このモードを公開/信頼できないingressに公開しないでください。 +- pairing後、Gatewayは接続role + scopeにスコープされた**device token**を発行します。これは`hello-ok.auth.deviceToken`で返され、クライアントは今後の接続のために永続化する必要があります。 +- クライアントは、接続成功後に主`hello-ok.auth.deviceToken`を永続化する必要があります。 +- その**保存済み**device tokenで再接続する場合、そのトークンに対して承認済みの保存scopeセットも再利用する必要があります。これにより、すでに付与されていたread/probe/statusアクセスが保持され、再接続時に暗黙のadmin-only scopeへと静かに縮小することを防げます。 +- 通常の接続認証の優先順位は、まず明示的な共有token/password、次に明示的な`deviceToken`、次に保存済みのデバイス単位token、最後にbootstrap tokenです。 +- 追加の`hello-ok.auth.deviceTokens`エントリはbootstrap handoff tokenです。`wss://`やloopback/local pairingのような信頼できるトランスポートでbootstrap認証を使用した場合にのみ永続化してください。 +- クライアントが明示的な`deviceToken`または明示的な`scopes`を指定した場合、その呼び出し元が要求したscopeセットが引き続き権威を持ちます。キャッシュ済みscopeは、クライアントが保存済みのデバイス単位tokenを再利用している場合にのみ再利用されます。 +- デバイストークンは`device.token.rotate`および`device.token.revoke`でローテーション/失効できます（`operator.pairing` scopeが必要）。 +- トークンの発行/ローテーションは、そのデバイスのpairingエントリに記録された承認済みroleセットの範囲内に制限されます。トークンのローテーションによって、そのデバイスをpairing承認で一度も許可されていないroleへ拡張することはできません。 +- ペアリング済みデバイストークンセッションでは、呼び出し元が`operator.admin`も持っていない限り、デバイス管理は自己スコープです。adminでない呼び出し元は、自分**自身**のデバイスエントリに対してのみremove/revoke/rotateできます。 +- `device.token.rotate`は、要求されたoperator scopeセットを呼び出し元の現在のセッションscopeに対してもチェックします。adminでない呼び出し元は、現在保持しているより広いoperator scopeセットへトークンをローテーションできません。 +- 認証失敗には、`error.details.code`と回復ヒントが含まれます: - `error.details.canRetryWithDeviceToken`（boolean） - - `error.details.recommendedNextStep`（`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`） -- `AUTH_TOKEN_MISMATCH` に対するクライアント動作: - - 信頼されたクライアントは、キャッシュされたデバイスごとのトークンで - 1回だけ制限付き再試行を試みてもかまいません。 - - その再試行も失敗した場合、クライアントは自動再接続ループを停止し、 - operator向けの対処ガイダンスを表示する必要があります。 + - `error.details.recommendedNextStep`（`retry_with_device_token`、`update_auth_configuration`、`update_auth_credentials`、`wait_then_retry`、`review_auth_configuration`） +- `AUTH_TOKEN_MISMATCH`に対するクライアント動作: + - 信頼されたクライアントは、キャッシュ済みのデバイス単位tokenで1回だけ制限付き再試行を試みることができます。 + - その再試行が失敗した場合、クライアントは自動再接続ループを停止し、operatorに必要な対応を案内するべきです。 -## デバイスidentity + pairing +## デバイスID + pairing -- ノードは、キーペアフィンガープリントから導出された安定したデバイスidentity（`device.id`）を含める必要があります。 -- Gatewayは、デバイス + roleごとにトークンを発行します。 -- ローカル自動承認が有効でない限り、新しいデバイスIDにはpairing承認が必要です。 -- pairing自動承認は、直接のlocal loopback接続を中心にしています。 -- OpenClawには、信頼された共有シークレットヘルパーフロー向けの - 狭いbackend/container-local self-connectパスもあります。 -- 同一ホストのtailnetやLAN接続も、引き続きリモートとして扱われ、 - pairing承認が必要です。 -- すべてのWSクライアントは、`connect` 中に `device` identity を含める必要があります - （operator + node）。 - Control UIがこれを省略できるのは、次のモードだけです: - - localhost専用の非安全HTTP互換性向け `gateway.controlUi.allowInsecureAuth=true` - - `gateway.auth.mode: "trusted-proxy"` でのoperator Control UI認証成功時。 - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（緊急避難用、重大なセキュリティ低下）。 -- すべての接続は、サーバー提供の `connect.challenge` nonce に署名しなければなりません。 +- ノードは、キーペアのフィンガープリントから導出された安定したデバイスID（`device.id`）を含める必要があります。 +- Gatewayは、デバイスごと + roleごとにトークンを発行します。 +- local loopbackの自動承認が有効になっていない限り、新しいデバイスIDにはpairing承認が必要です。 +- pairing自動承認は、直接のlocal loopback接続を中心に設計されています。 +- OpenClawには、信頼された共有シークレットヘルパーフロー向けの、限定的なバックエンド/コンテナローカル自己接続パスもあります。 +- 同一ホストのtailnetまたはLAN接続は、pairingの観点では引き続きリモートとして扱われ、承認が必要です。 +- すべてのWSクライアントは、`connect`時に`device` IDを含める必要があります（operator + node）。 + Control UIがこれを省略できるのは、次のモードのみです: + - localhost専用の安全でないHTTP互換性向けの`gateway.controlUi.allowInsecureAuth=true` + - 成功した`gateway.auth.mode: "trusted-proxy"`のoperator Control UI認証 + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（緊急避難用、重大なセキュリティ低下） +- すべての接続は、サーバーから提供された`connect.challenge` nonceに署名する必要があります。 ### デバイス認証移行診断 -依然としてpre-challenge署名動作を使っているレガシークライアント向けに、 -`connect` は現在、安定した `error.details.reason` の下で -`error.details.code` に `DEVICE_AUTH_*` 詳細コードを返します。 +以前のchallenge前署名動作をまだ使っているレガシークライアント向けに、`connect`は`error.details.reason`の安定した値とともに、`error.details.code`配下で`DEVICE_AUTH_*`詳細コードを返すようになりました。 一般的な移行失敗: -| メッセージ | details.code | details.reason | 意味 | -| ------------------------------ | -------------------------------- | ------------------------ | ----------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | クライアントが `device.nonce` を省略した（または空を送信した）。 | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | クライアントが古い/誤ったnonceで署名した。 | -| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 署名ペイロードがv2ペイロードと一致しない。 | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 署名済みタイムスタンプが許容スキュー範囲外である。 | -| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` が公開鍵フィンガープリントと一致しない。 | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公開鍵の形式/正規化に失敗した。 | +| メッセージ | details.code | details.reason | 意味 | +| --------------------------- | -------------------------------- | ------------------------ | ------------------------------------------------------ | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | クライアントが`device.nonce`を省略した（または空文字を送信した）。 | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | クライアントが古い/誤ったnonceで署名した。 | +| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 署名ペイロードがv2ペイロードと一致しない。 | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 署名済みタイムスタンプが許容skewの範囲外である。 | +| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id`が公開鍵フィンガープリントと一致しない。 | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公開鍵形式/正規化に失敗した。 | -移行ターゲット: +移行の目標: -- 常に `connect.challenge` を待つ。 -- サーバーnonceを含むv2ペイロードに署名する。 -- 同じnonceを `connect.params.device.nonce` で送る。 -- 推奨署名ペイロードは `v3` で、device/client/role/scopes/token/nonce - フィールドに加えて `platform` と `deviceFamily` も結び付けます。 -- レガシーな `v2` 署名も互換性のため引き続き受け入れられますが、 - pair済みデバイスのメタデータ固定が、再接続時のコマンドポリシーを引き続き制御します。 +- 常に`connect.challenge`を待機してください。 +- サーバーnonceを含むv2ペイロードに署名してください。 +- 同じnonceを`connect.params.device.nonce`に送信してください。 +- 推奨される署名ペイロードは`v3`で、device/client/role/scopes/token/nonceフィールドに加えて`platform`と`deviceFamily`を束縛します。 +- レガシー`v2`署名も互換性のため引き続き受け入れられますが、ペアリング済みデバイスメタデータのpinningは、再接続時のコマンドポリシーを引き続き制御します。 -## TLS + ピン留め +## TLS + pinning -- WS接続ではTLSがサポートされています。 -- クライアントは、必要に応じてGateway証明書のフィンガープリントをピン留めできます - （`gateway.tls` 設定、および `gateway.remote.tlsFingerprint` または - CLI `--tls-fingerprint` を参照）。 +- WS接続ではTLSがサポートされます。 +- クライアントは、必要に応じてGateway証明書フィンガープリントをpinできます（`gateway.tls`設定、および`gateway.remote.tlsFingerprint`またはCLIの`--tls-fingerprint`を参照）。 ## スコープ -このプロトコルは、**完全なGateway API**（status、channels、models、chat、 -agent、sessions、nodes、approvalsなど）を公開します。正確なサーフェスは -`src/gateway/protocol/schema.ts` 内のTypeBoxスキーマで定義されます。 +このプロトコルは、**完全なGateway API**（status、channels、models、chat、agent、sessions、nodes、approvalsなど）を公開します。正確なサーフェスは`src/gateway/protocol/schema.ts`内のTypeBoxスキーマで定義されています。 diff --git a/docs/ja-JP/gateway/security/index.md b/docs/ja-JP/gateway/security/index.md index 0efb903a3..d8aee849e 100644 --- a/docs/ja-JP/gateway/security/index.md +++ b/docs/ja-JP/gateway/security/index.md @@ -1,13 +1,13 @@ --- read_when: - - アクセスや自動化を広げる機能を追加している場合 -summary: シェルアクセスを持つAI Gatewayを運用するためのセキュリティ上の考慮事項と脅威モデル + - アクセスや自動化を拡大する機能の追加 +summary: シェルアクセスを持つAI Gatewayを実行する際のセキュリティ上の考慮事項と脅威モデル title: セキュリティ x-i18n: - generated_at: "2026-04-05T12:49:38Z" + generated_at: "2026-04-11T02:44:59Z" model: gpt-5.4 provider: openai - source_hash: 223deb798774952f8d0208e761e163708a322045cf4ca3df181689442ef6fcfb + source_hash: 770407f64b2ce27221ebd9756b2f8490a249c416064186e64edb663526f9d6b5 source_path: gateway/security/index.md workflow: 15 --- @@ -15,29 +15,29 @@ x-i18n: # セキュリティ -**個人アシスタントの信頼モデル:** このガイダンスは、gatewayごとに1つの信頼されたオペレーター境界があることを前提としています（単一ユーザー/個人アシスタントモデル）。 -OpenClawは、複数の敵対的ユーザーが1つのagent/gatewayを共有するための、敵対的マルチテナント向けセキュリティ境界では**ありません**。 -信頼度が混在する、または敵対的ユーザーを含む運用が必要な場合は、信頼境界を分離してください（gatewayと認証情報を分け、可能ならOSユーザー/ホストも分離してください）。 +**パーソナルアシスタントの信頼モデル:** このガイダンスは、Gatewayごとに1つの信頼された運用者境界があることを前提としています（単一ユーザー／パーソナルアシスタントモデル）。 +OpenClawは、1つのエージェント／Gatewayを複数の敵対的ユーザーが共有するような、敵対的マルチテナントのセキュリティ境界では**ありません**。 +混在した信頼や敵対的ユーザーでの運用が必要な場合は、信頼境界を分割してください（Gatewayと認証情報を分離し、可能であればOSユーザーやホストも分離してください）。 -**このページの内容:** [信頼モデル](#scope-first-personal-assistant-security-model) | [クイック監査](#quick-check-openclaw-security-audit) | [60秒でできる強化ベースライン](#hardened-baseline-in-60-seconds) | [DMアクセスモデル](#dm-access-model-pairing--allowlist--open--disabled) | [設定の強化](#configuration-hardening-examples) | [インシデント対応](#incident-response) +**このページの内容:** [信頼モデル](#scope-first-personal-assistant-security-model) | [クイック監査](#quick-check-openclaw-security-audit) | [強化済みベースライン](#hardened-baseline-in-60-seconds) | [DMアクセスモデル](#dm-access-model-pairing-allowlist-open-disabled) | [設定の強化](#configuration-hardening-examples) | [インシデント対応](#incident-response) -## まず前提から: 個人アシスタントのセキュリティモデル +## まず範囲を明確にする: パーソナルアシスタントのセキュリティモデル -OpenClawのセキュリティガイダンスは、**個人アシスタント**としてのデプロイを前提にしています。つまり、1つの信頼されたオペレーター境界があり、その中に複数のagentが存在する形です。 +OpenClawのセキュリティガイダンスは、**パーソナルアシスタント**としてのデプロイを前提としています。つまり、信頼された運用者境界は1つで、そこに複数のエージェントが存在する可能性があるということです。 -- サポートされるセキュリティ姿勢: gatewayごとに1つのユーザー/信頼境界（できれば境界ごとに1つのOSユーザー/ホスト/VPS）。 -- サポート対象外のセキュリティ境界: 相互に信頼していない、または敵対的なユーザーが1つの共有gateway/agentを使うこと。 -- 敵対的ユーザー間の分離が必要なら、信頼境界ごとに分けてください（gateway + 認証情報を分離し、理想的にはOSユーザー/ホストも分離）。 -- 複数の信頼できないユーザーが1つのツール有効agentにメッセージできるなら、そのagentに委譲された同じツール権限を共有しているものとして扱ってください。 +- サポートされるセキュリティ体制: Gatewayごとに1つのユーザー／信頼境界（境界ごとに1つのOSユーザー／ホスト／VPSが望ましい）。 +- サポートされないセキュリティ境界: 相互に信頼していない、または敵対的なユーザー同士が共有する1つのGateway／エージェント。 +- 敵対的ユーザー間の分離が必要な場合は、信頼境界ごとに分割してください（Gatewayと認証情報を分離し、理想的にはOSユーザーやホストも分離します）。 +- 複数の信頼していないユーザーが、ツール有効化済みの1つのエージェントにメッセージできる場合、そのユーザーたちはそのエージェントに委任された同じツール権限を共有しているものとして扱ってください。 -このページは、**そのモデルの範囲内**での強化方法を説明します。1つの共有gateway上で敵対的マルチテナント分離ができるとは主張しません。 +このページでは、**そのモデルの範囲内での**強化方法を説明します。1つの共有Gateway上で敵対的マルチテナント分離を実現できるとは主張していません。 ## クイックチェック: `openclaw security audit` -関連項目: [Formal Verification (Security Models)](/security/formal-verification) +参照: [Formal Verification (Security Models)](/ja-JP/security/formal-verification) -これを定期的に実行してください（特に設定変更後やネットワーク公開面を増やした後）。 +これは定期的に実行してください。特に、設定を変更した後やネットワークサーフェスを公開した後は重要です。 ```bash openclaw security audit @@ -46,103 +46,103 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` は意図的に対象を絞っています。一般的なオープングループポリシーをallowlistへ切り替え、`logging.redactSensitive: "tools"` を復元し、state/config/include-fileの権限を強化し、WindowsではPOSIXの `chmod` の代わりにACLリセットを使います。 +`security audit --fix` は、意図的に対象を絞っています。一般的なオープングループポリシーを許可リストへ切り替え、`logging.redactSensitive: "tools"` を復元し、state/config/include-file の権限を強化し、Windows上で実行される場合はPOSIXの `chmod` ではなくWindows ACLのリセットを使用します。 -これは、よくある危険な設定（Gateway認証の露出、browser制御の露出、elevated allowlist、ファイルシステム権限、緩いexec承認、オープンチャンネルからのツール露出）を検出します。 +この監査は、よくある危険な設定（Gateway認証の露出、ブラウザ制御の露出、昇格済み許可リスト、ファイルシステム権限、緩いexec承認、オープンチャネルからのツール露出）を検出します。 -OpenClawは製品であると同時に実験でもあります。あなたは最先端モデルの振る舞いを、実際のメッセージング面と実際のツールに接続しています。**「完全に安全な」構成はありません。** 目標は、次の点を意識的に決めることです。 +OpenClawは製品であると同時に実験でもあります。つまり、最先端モデルの振る舞いを、実際のメッセージングサーフェスや実際のツールへ接続しています。**「完全に安全な」セットアップは存在しません。** 重要なのは、次の点について意識的であることです。 -- 誰があなたのbotに話しかけられるか -- botがどこで行動できるか -- botが何に触れられるか +- 誰があなたのボットに話しかけられるのか +- ボットがどこで動作してよいのか +- ボットが何に触れられるのか -まず、動作に必要な最小限のアクセスから始め、確信が持てるようになってから徐々に広げてください。 +まずは機能する最小限のアクセスから始め、確信が持てるようになってから少しずつ広げてください。 -### デプロイとホスト信頼 +### デプロイとホストの信頼 -OpenClawは、ホストと設定境界が信頼されていることを前提にしています。 +OpenClawは、ホストと設定の境界が信頼されていることを前提としています。 -- 誰かがGatewayホストのstate/config（`~/.openclaw`、`openclaw.json` を含む）を変更できるなら、その人は信頼されたオペレーターとして扱ってください。 -- 相互に信頼していない/敵対的な複数のオペレーターのために1つのGatewayを動かすのは、**推奨される構成ではありません**。 -- 信頼度が混在するチームでは、別々のGatewayで信頼境界を分けてください（少なくともOSユーザー/ホストは分けてください）。 -- 推奨デフォルト: マシン/ホスト（またはVPS）ごとに1ユーザー、そのユーザーに1 gateway、そのgateway内に1つ以上のagent。 -- 1つのGatewayインスタンス内では、認証済みoperatorアクセスは、ユーザーごとのテナントロールではなく、信頼されたcontrol-planeロールです。 -- セッション識別子（`sessionKey`、session ID、label）はルーティング選択子であり、認可トークンではありません。 -- 複数人が1つのツール有効agentにメッセージできるなら、それぞれが同じ権限セットを操縦できます。ユーザーごとのsession/memory分離はプライバシーには役立ちますが、共有agentをユーザーごとのホスト認可境界には変えません。 +- 誰かがGatewayホストの状態や設定（`openclaw.json` を含む `~/.openclaw`）を変更できるなら、その人は信頼された運用者として扱ってください。 +- 相互に信頼していない、または敵対的な複数の運用者のために1つのGatewayを動かすのは、**推奨される構成ではありません**。 +- 信頼が混在するチームでは、別々のGatewayで信頼境界を分離してください（少なくともOSユーザーやホストは分けてください）。 +- 推奨されるデフォルトは、マシン／ホスト（またはVPS）ごとに1ユーザー、そのユーザー用に1つのGateway、そしてそのGateway内に1つ以上のエージェント、という構成です。 +- 1つのGatewayインスタンス内では、認証済みの運用者アクセスは、ユーザー単位のテナント役割ではなく、信頼されたコントロールプレーン役割です。 +- セッション識別子（`sessionKey`、セッションID、ラベル）はルーティング選択子であり、認可トークンではありません。 +- 複数人が1つのツール有効化済みエージェントにメッセージできる場合、その全員が同じ権限セットを操作できます。ユーザーごとのセッション／メモリー分離はプライバシーには役立ちますが、共有エージェントをユーザー単位のホスト認可へ変えるものではありません。 ### 共有Slackワークスペース: 実際のリスク -「Slackの全員がbotにメッセージできる」場合の中心的リスクは、委譲されたツール権限です。 +「Slackの誰でもボットにメッセージできる」場合、中核となるリスクは委任されたツール権限です。 -- 許可された任意の送信者が、agentポリシー内でのツール呼び出し（`exec`、browser、network/file tools）を誘発できる -- 1人の送信者からのprompt/content injectionが、共有state、デバイス、出力に影響するアクションを引き起こせる -- 1つの共有agentが機密認証情報/ファイルを持っている場合、許可された任意の送信者がツール使用を通じて流出を引き起こせる可能性がある +- 許可された送信者は誰でも、エージェントのポリシー範囲内でツール呼び出し（`exec`、ブラウザ、ネットワーク／ファイルツール）を誘発できます。 +- ある送信者からのプロンプト／コンテンツインジェクションにより、共有状態、デバイス、または出力へ影響するアクションが引き起こされる可能性があります。 +- 1つの共有エージェントが機密な認証情報やファイルを持っている場合、許可された送信者は誰でも、ツール利用を通じて情報流出を引き起こせる可能性があります。 -チームワークフローには最小限のツールを持つ別agent/gatewayを使い、個人データを扱うagentは非公開に保ってください。 +チーム向けワークフローには、ツールを最小限にした別々のエージェント／Gatewayを使用し、個人データを扱うエージェントは非公開に保ってください。 -### 会社共有agent: 許容できるパターン +### 会社で共有するエージェント: 許容されるパターン -そのagentを使う全員が同じ信頼境界にいて（たとえば同じ会社チーム）、agentの対象範囲が厳密に業務に限定されているなら、これは許容できます。 +そのエージェントを使う全員が同じ信頼境界に属し（たとえば同じ会社の1チーム）、かつそのエージェントが厳密に業務範囲に限定されているなら、これは許容されます。 -- 専用のマシン/VM/containerで実行する -- そのランタイム専用のOSユーザー + 専用のbrowser/profile/accountを使う -- そのランタイムを個人のApple/Googleアカウントや、個人のpassword manager/browser profileにサインインさせない +- 専用のマシン／VM／コンテナ上で実行する。 +- そのランタイム専用のOSユーザー、専用のブラウザ／プロファイル／アカウントを使う。 +- そのランタイムで、個人のApple／Googleアカウントや個人のパスワードマネージャー／ブラウザプロファイルにサインインしない。 -同じランタイムで個人アイデンティティと会社アイデンティティを混在させると、分離が崩れ、個人データ流出リスクが高まります。 +同じランタイム上で個人用と会社用のアイデンティティを混在させると、その分離は崩れ、個人データの露出リスクが高まります。 ## Gatewayとnodeの信頼概念 -Gatewayとnodeは、役割が異なる1つのオペレーター信頼ドメインとして扱ってください。 +Gatewayとnodeは、役割の異なる1つの運用者信頼ドメインとして扱ってください。 -- **Gateway** はcontrol planeとpolicy surfaceです（`gateway.auth`、tool policy、routing）。 -- **Node** は、そのGatewayにペアリングされたリモート実行面です（コマンド、デバイス操作、ホストローカル機能）。 -- Gatewayに認証された呼び出し元は、Gatewayスコープで信頼されます。ペアリング後、node操作はそのnode上での信頼されたoperatorアクションになります。 -- `sessionKey` はルーティング/コンテキスト選択であり、ユーザーごとの認証ではありません。 -- Exec承認（allowlist + ask）は、operator意図のためのガードレールであり、敵対的マルチテナント分離ではありません。 -- 信頼された単一オペレーター構成におけるOpenClawの製品デフォルトは、`gateway`/`node` でのhost execを承認プロンプトなしで許可することです（`security="full"`、厳しくしない限り `ask="off"`）。このデフォルトは意図されたUXであり、それ自体が脆弱性ではありません。 -- Exec承認は、正確なリクエストコンテキストと、ベストエフォートな直接ローカルファイルオペランドに結び付きます。すべてのランタイム/インタープリターのローダーパスを意味的にモデル化するわけではありません。強い境界が必要ならsandboxingとホスト分離を使ってください。 +- **Gateway** はコントロールプレーンであり、ポリシーサーフェスです（`gateway.auth`、ツールポリシー、ルーティング）。 +- **Node** はそのGatewayとペアリングされたリモート実行サーフェスです（コマンド、デバイス操作、ホストローカル機能）。 +- Gatewayに認証された呼び出し元は、Gatewayスコープで信頼されます。ペアリング後のnodeアクションは、そのnode上での信頼された運用者アクションです。 +- `sessionKey` はルーティング／コンテキスト選択であり、ユーザー単位の認証ではありません。 +- Exec承認（許可リスト + ask）は、運用者の意図に対するガードレールであり、敵対的マルチテナント分離ではありません。 +- 信頼された単一運用者セットアップにおけるOpenClawの製品デフォルトでは、`gateway`／`node` 上のホストexecは承認プロンプトなしで許可されます（`security="full"`、それを厳しくしない限り `ask="off"`）。このデフォルトは意図的なUXであり、それ自体は脆弱性ではありません。 +- Exec承認は、正確なリクエストコンテキストと、ベストエフォートの直接的なローカルファイルオペランドに結び付きます。あらゆるランタイム／インタープリターのローダーパスを意味的にモデル化するものではありません。強い境界が必要なら、サンドボックス化とホスト分離を使用してください。 -敵対的ユーザー分離が必要なら、OSユーザー/ホストごとに信頼境界を分割し、別々のgatewayを実行してください。 +敵対的ユーザー分離が必要な場合は、OSユーザー／ホスト単位で信頼境界を分割し、別々のGatewayを実行してください。 ## 信頼境界マトリクス -リスクを判断するときは、これをクイックモデルとして使ってください。 +リスクをトリアージするときの簡易モデルとして、これを使ってください。 -| 境界または制御 | 意味 | よくある誤解 | -| --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | gateway APIへの呼び出し元を認証する | 「安全にするには各フレームごとにメッセージ署名が必要」 | -| `sessionKey` | コンテキスト/session選択のためのルーティングキー | 「session keyはユーザー認証境界」 | -| Prompt/content guardrails | モデル悪用リスクを下げる | 「prompt injectionだけで認証バイパスが証明される」 | -| `canvas.eval` / browser evaluate | 有効化時の意図的なoperator機能 | 「どんなJS evalプリミティブもこの信頼モデルでは自動的に脆弱性になる」 | -| ローカルTUI `!` shell | 明示的なoperatorトリガーのローカル実行 | 「ローカルshell用の便利コマンドはリモート注入だ」 | -| Node pairingとnode command | ペア済みデバイス上でのoperatorレベルの遠隔実行 | 「リモートデバイス制御はデフォルトで信頼できないユーザーアクセス扱いにすべき」 | +| 境界または制御 | それが意味すること | よくある誤解 | +| -------------- | ------------------ | ------------ | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Gateway APIへの呼び出し元を認証する | 「安全にするには、すべてのフレームにメッセージ単位の署名が必要」 | +| `sessionKey` | コンテキスト／セッション選択のためのルーティングキー | 「セッションキーはユーザー認証境界である」 | +| プロンプト／コンテンツのガードレール | モデル悪用リスクを低減する | 「プロンプトインジェクションだけで認証回避が証明される」 | +| `canvas.eval` / browser evaluate | 有効化されている場合の意図的な運用者機能 | 「どんなJS evalプリミティブでも、この信頼モデルでは自動的に脆弱性になる」 | +| ローカルTUIの `!` shell | 明示的に運用者が起動するローカル実行 | 「ローカルのシェル利便機能コマンドはリモートインジェクションである」 | +| Nodeペアリングとnodeコマンド | ペアリング済みデバイス上での運用者レベルのリモート実行 | 「リモートデバイス制御は、デフォルトで信頼されていないユーザーアクセスとして扱うべき」 | ## 設計上、脆弱性ではないもの -以下のパターンはよく報告されますが、実際の境界バイパスが示されない限り、通常は対応不要としてクローズされます。 +以下のパターンはよく報告されますが、実際の境界回避が示されない限り、通常は対応不要としてクローズされます。 -- ポリシー/auth/sandboxバイパスを伴わない、prompt injectionのみの連鎖。 -- 1つの共有host/configで敵対的マルチテナント運用を前提にした主張。 -- 共有gateway構成で、通常のoperator読み取り経路アクセス（たとえば `sessions.list`/`sessions.preview`/`chat.history`）をIDORとみなす主張。 -- localhost専用デプロイの指摘（たとえばloopback専用gatewayへのHSTS）。 -- このrepoに存在しない受信パスに対するDiscord inbound webhook署名の指摘。 -- `system.run` に対して、node pairing metadataを隠れた第2のコマンド単位承認層として扱う報告。実際の実行境界は依然としてgatewayのグローバルnode command policyとnode自身のexec approvalsです。 -- `sessionKey` を認証トークンとして扱う「ユーザーごとの認可欠如」の指摘。 +- ポリシー／認証／サンドボックス回避を伴わない、プロンプトインジェクションのみの連鎖。 +- 1つの共有ホスト／設定上での敵対的マルチテナント運用を前提にした主張。 +- 共有Gateway構成で、通常の運用者の読み取り経路アクセス（たとえば `sessions.list`／`sessions.preview`／`chat.history`）をIDORとして分類する主張。 +- localhost限定デプロイに対する指摘（たとえば、loopback専用GatewayでのHSTS）。 +- このリポジトリに存在しない受信パスに対する、Discord受信webhook署名の指摘。 +- `system.run` に対して、nodeペアリングメタデータを隠れた第2のコマンド単位承認レイヤーとして扱う報告。ただし実際の実行境界は依然としてGatewayのグローバルnodeコマンドポリシーとnode自身のexec承認です。 +- `sessionKey` を認証トークンとして扱う「ユーザー単位認可の欠如」の指摘。 -## 研究者向け事前チェックリスト +## 研究者向けの事前チェックリスト -GHSAを開く前に、次をすべて確認してください。 +GHSAを開く前に、次のすべてを確認してください。 -1. 再現が最新の `main` または最新リリースでも成立する。 -2. 報告に、正確なコードパス（`file`、function、line range）と検証したversion/commitが含まれている。 -3. 影響が文書化された信頼境界をまたいでいる（単なるprompt injectionではない）。 -4. 主張が [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope) に載っていない。 -5. 既存のadvisoryに重複がないか確認済みである（該当時は既存GHSAを再利用する）。 -6. デプロイ前提（loopback/localか、公開か、trusted operatorかuntrustedか）が明示されている。 +1. 再現手順が最新の `main` または最新リリースでも成立する。 +2. 報告に、正確なコードパス（`file`、関数、行範囲）と、テストしたバージョン／コミットが含まれている。 +3. 影響が、文書化された信頼境界をまたいでいる（単なるプロンプトインジェクションではない）。 +4. 主張が [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope) に記載されていない。 +5. 既存アドバイザリに重複がないか確認済みである（該当する場合は正規のGHSAを再利用する）。 +6. デプロイ前提（loopback/local か公開済みか、信頼された運用者か信頼していない運用者か）が明示されている。 -## 60秒でできる強化ベースライン +## 60秒でできる強化済みベースライン -まずこのベースラインを使い、その後で信頼するagentごとに必要なツールだけ再有効化してください。 +まずこのベースラインを使い、その後、信頼するエージェントごとに必要なツールだけを再有効化してください。 ```json5 { @@ -167,205 +167,209 @@ GHSAを開く前に、次をすべて確認してください。 } ``` -これにより、Gatewayはローカル専用のまま、DMは分離され、control-plane/runtime toolsはデフォルトで無効になります。 +これにより、Gatewayはローカル専用のままとなり、DMは分離され、コントロールプレーン／ランタイムツールはデフォルトで無効化されます。 -## 共有受信箱のクイックルール +## 共有受信箱の簡易ルール -複数人があなたのbotにDMできるなら: +複数人があなたのボットへDMできる場合: -- `session.dmScope: "per-channel-peer"` を設定してください（マルチアカウントchannelなら `"per-account-channel-peer"`）。 -- `dmPolicy: "pairing"` または厳格なallowlistを維持してください。 -- 共有DMと広いツールアクセスを組み合わせないでください。 -- これは協調/共有受信箱の強化にはなりますが、ユーザーがhost/config書き込みアクセスを共有する場合の敵対的共同テナント分離として設計されたものではありません。 +- `session.dmScope: "per-channel-peer"` を設定してください（マルチアカウントチャネルでは `"per-account-channel-peer"`）。 +- `dmPolicy: "pairing"` または厳格な許可リストを維持してください。 +- 共有DMと広範なツールアクセスを絶対に組み合わせないでください。 +- これにより協調型／共有受信箱は強化されますが、ユーザーがホスト／設定への書き込みアクセスを共有している場合の、敵対的な共同テナント分離を目的とした設計ではありません。 ## コンテキスト可視性モデル -OpenClawは、次の2つを分けています。 +OpenClawは、次の2つの概念を分離しています。 -- **トリガー認可**: 誰がagentを起動できるか（`dmPolicy`、`groupPolicy`、allowlist、mention gate）。 -- **コンテキスト可視性**: どの補足コンテキストがモデル入力に注入されるか（返信本文、引用テキスト、スレッド履歴、転送メタデータ）。 +- **トリガー認可**: 誰がエージェントを起動できるか（`dmPolicy`、`groupPolicy`、許可リスト、メンションゲート）。 +- **コンテキスト可視性**: どの補助コンテキストがモデル入力へ注入されるか（返信本文、引用テキスト、スレッド履歴、転送メタデータ）。 -Allowlistsはトリガーとコマンド認可を制御します。`contextVisibility` は、補足コンテキスト（引用返信、スレッドルート、取得履歴）をどうフィルタするかを制御します。 +許可リストは、トリガーとコマンド認可を制御します。`contextVisibility` 設定は、補助コンテキスト（引用返信、スレッドルート、取得済み履歴）をどのようにフィルタリングするかを制御します。 -- `contextVisibility: "all"`（デフォルト）は、補足コンテキストを受信したまま保持します。 -- `contextVisibility: "allowlist"` は、補足コンテキストを現在有効なallowlistチェックで許可された送信者に絞ります。 -- `contextVisibility: "allowlist_quote"` は `allowlist` と同様ですが、1つの明示的な引用返信だけは保持します。 +- `contextVisibility: "all"`（デフォルト）は、補助コンテキストを受信したまま保持します。 +- `contextVisibility: "allowlist"` は、補助コンテキストを現在有効な許可リストチェックで許可された送信者に限定してフィルタリングします。 +- `contextVisibility: "allowlist_quote"` は `allowlist` と同様に動作しますが、明示的な引用返信を1つだけ保持します。 -`contextVisibility` はchannel単位またはroom/conversation単位で設定してください。設定方法は [Group Chats](/ja-JP/channels/groups#context-visibility) を参照してください。 +`contextVisibility` は、チャネル単位またはルーム／会話単位で設定してください。設定の詳細は [Group Chats](/ja-JP/channels/groups#context-visibility-and-allowlists) を参照してください。 -Advisoryトリアージの指針: +アドバイザリのトリアージ指針: -- 「モデルがallowlist外送信者の引用や履歴テキストを見られる」だけを示す主張は、`contextVisibility` で対応する強化事項であり、それ単体ではauthやsandbox境界バイパスではありません。 -- セキュリティ影響ありとするには、依然として信頼境界のバイパス（auth、policy、sandbox、approval、または他の文書化された境界）の実証が必要です。 +- 「モデルが、許可リストにない送信者からの引用文や履歴テキストを見られる」ことだけを示す主張は、`contextVisibility` で対処できる強化上の指摘であり、それ自体では認証やサンドボックス境界の回避ではありません。 +- セキュリティ上の影響を持つには、報告は依然として、信頼境界（認証、ポリシー、サンドボックス、承認、または他の文書化された境界）の回避を実証する必要があります。 -## 監査がチェックするもの（高レベル） +## 監査でチェックされるもの（概要） -- **受信アクセス**（DM policy、group policy、allowlist）: 見知らぬ相手がbotを起動できるか。 -- **ツールの影響範囲**（elevated tools + オープンルーム）: prompt injectionがshell/file/network操作に繋がるか。 -- **Exec承認のドリフト**（`security=full`、`autoAllowSkills`、`strictInlineEval` なしのinterpreter allowlist）: host-execガードレールがまだ想定どおり機能しているか。 - - `security="full"` は広い姿勢への警告であり、バグの証明ではありません。これは信頼された個人アシスタント構成で選ばれたデフォルトです。脅威モデルが承認やallowlistガードレールを必要とするときだけ厳しくしてください。 -- **ネットワーク露出**（Gateway bind/auth、Tailscale Serve/Funnel、弱い/短いauth token）。 -- **Browser制御の露出**（remote nodes、relay ports、remote CDP endpoints）。 -- **ローカルディスク衛生**（権限、symlink、config includes、「同期フォルダー」パス）。 -- **Plugins**（明示的allowlistなしで拡張が存在する）。 -- **ポリシードリフト/誤設定**（sandbox docker設定があるのにsandbox modeがoff、`gateway.nodes.denyCommands` のパターンが実際には正確なコマンド名にしか一致せずshell textを見ないため効かない、危険な `gateway.nodes.allowCommands`、グローバル `tools.profile="minimal"` がagent単位profileで上書きされている、緩いtool policyでextension plugin toolsに到達できる）。 -- **ランタイム期待値のドリフト**（たとえば `tools.exec.host` のデフォルトが `auto` になった後も暗黙のexecが `sandbox` だと思い込んでいる、または `tools.exec.host="sandbox"` を明示しているのにsandbox modeがoff）。 -- **モデル衛生**（設定モデルがlegacyっぽい場合に警告。ハードブロックではない）。 +- **受信アクセス**（DMポリシー、グループポリシー、許可リスト）: 見知らぬ相手がボットを起動できるか？ +- **ツールの影響範囲**（昇格ツール + オープンなルーム）: プロンプトインジェクションがシェル／ファイル／ネットワーク操作に発展しうるか？ +- **Exec承認のずれ**（`security=full`、`autoAllowSkills`、`strictInlineEval` なしのインタープリター許可リスト）: ホストexecのガードレールは、まだ意図したとおりに機能しているか？ + - `security="full"` は広範な姿勢に関する警告であり、バグの証明ではありません。これは、信頼されたパーソナルアシスタント構成向けに選ばれたデフォルトです。脅威モデル上、承認や許可リストのガードレールが必要な場合にのみ、これを厳しくしてください。 +- **ネットワーク露出**（Gatewayのbind/auth、Tailscale Serve/Funnel、弱い／短い認証トークン）。 +- **ブラウザ制御の露出**（リモートnode、リレーポート、リモートCDPエンドポイント）。 +- **ローカルディスク衛生**（権限、symlink、設定include、`「同期フォルダー」` のパス）。 +- **プラグイン**（明示的な許可リストなしで拡張機能が存在している）。 +- **ポリシーのずれ／誤設定**（sandbox docker設定はあるのにsandboxモードがオフ、`gateway.nodes.denyCommands` パターンが無効になっているのは、マッチングが正確なコマンド名のみを対象とし、シェルテキストを検査しないためであることへの注意。たとえば `system.run`。危険な `gateway.nodes.allowCommands` エントリー。グローバルな `tools.profile="minimal"` がエージェント単位プロファイルで上書きされている。緩いツールポリシー下で拡張プラグインのツールへ到達可能）。 +- **ランタイム期待値のずれ**（たとえば、`tools.exec.host` のデフォルトが `auto` になった後でも、暗黙のexecが `sandbox` を意味すると想定している場合や、sandboxモードがオフなのに明示的に `tools.exec.host="sandbox"` を設定している場合）。 +- **モデル衛生**（設定されたモデルがレガシーに見える場合に警告。ハードブロックではありません）。 -`--deep` を使うと、OpenClawはベストエフォートのライブGateway probeも試みます。 +`--deep` を実行すると、OpenClawはベストエフォートでライブGatewayプローブも試みます。 -## 認証情報保存マップ +## 認証情報ストレージの対応表 -アクセス監査やバックアップ対象の判断にはこれを使ってください。 +アクセス監査やバックアップ対象の判断時には、これを使ってください。 - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` - **Telegram bot token**: config/env または `channels.telegram.tokenFile`（通常ファイルのみ。symlinkは拒否） -- **Discord bot token**: config/env または SecretRef（env/file/exec providers） -- **Slack tokens**: config/env (`channels.slack.*`) -- **Pairing allowlists**: - - `~/.openclaw/credentials/-allowFrom.json`（デフォルトaccount） - - `~/.openclaw/credentials/--allowFrom.json`（非デフォルトaccount） -- **Model auth profiles**: `~/.openclaw/agents//agent/auth-profiles.json` -- **ファイルベースsecret payload（任意）**: `~/.openclaw/secrets.json` -- **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json` +- **Discord bot token**: config/env または SecretRef（env/file/execプロバイダー） +- **Slackトークン**: config/env (`channels.slack.*`) +- **ペアリング許可リスト**: + - `~/.openclaw/credentials/-allowFrom.json`（デフォルトアカウント） + - `~/.openclaw/credentials/--allowFrom.json`（デフォルト以外のアカウント） +- **モデル認証プロファイル**: `~/.openclaw/agents//agent/auth-profiles.json` +- **ファイルベースのシークレットペイロード（任意）**: `~/.openclaw/secrets.json` +- **レガシーOAuthインポート**: `~/.openclaw/credentials/oauth.json` ## セキュリティ監査チェックリスト -監査が検出を出したら、次の優先順で扱ってください。 +監査で検出結果が表示された場合は、次の優先順位で扱ってください。 -1. **「open」かつtools有効**のもの: まずDM/groupsを絞り（pairing/allowlists）、次にtool policy/sandboxingを厳しくする。 -2. **公開ネットワーク露出**（LAN bind、Funnel、authなし）: 直ちに修正する。 -3. **Browser controlのリモート露出**: operator accessと同等として扱う（tailnet専用、意図的なnode pairing、公開しない）。 -4. **権限**: state/config/credentials/authがgroup/world readableでないことを確認する。 -5. **Plugins/extensions**: 明示的に信頼するものだけを読み込む。 -6. **モデル選択**: toolsを持つbotには、現行の堅牢なinstruction-hardenedモデルを優先する。 +1. **`「open」` な設定 + ツール有効化**: まずDM／グループをロックダウンします（ペアリング／許可リスト）。その後でツールポリシーやsandbox化を強化してください。 +2. **公開ネットワーク露出**（LAN bind、Funnel、auth欠如）: 直ちに修正してください。 +3. **ブラウザ制御のリモート露出**: 運用者アクセスと同等に扱ってください（tailnet限定、意図的なnodeペアリング、公開露出を避ける）。 +4. **権限**: state／config／credentials／auth がグループまたは全員に読み取り可能になっていないことを確認してください。 +5. **プラグイン／拡張機能**: 明示的に信頼するものだけを読み込んでください。 +6. **モデル選択**: ツールを持つボットには、現代的で命令耐性の高いモデルを優先してください。 ## セキュリティ監査用語集 -実運用でよく見る、シグナルの強い `checkId` 値を示します（網羅的ではありません）。 +実運用環境で特によく見かける、シグナルの強い `checkId` 値は次のとおりです（網羅的ではありません）: -| `checkId` | 重大度 | なぜ重要か | 主な修正キー/パス | 自動修正 | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -------- | -| `fs.state_dir.perms_world_writable` | critical | 他ユーザー/プロセスがOpenClaw state全体を変更できる | `~/.openclaw` のファイルシステム権限 | yes | -| `fs.state_dir.perms_group_writable` | warn | グループユーザーがOpenClaw state全体を変更できる | `~/.openclaw` のファイルシステム権限 | yes | -| `fs.state_dir.perms_readable` | warn | state dirが他者に読める | `~/.openclaw` のファイルシステム権限 | yes | -| `fs.state_dir.symlink` | warn | state dirの実体が別の信頼境界になる | state dirのファイルシステムレイアウト | no | -| `fs.config.perms_writable` | critical | 他者がauth/tool policy/configを変更できる | `~/.openclaw/openclaw.json` のファイルシステム権限 | yes | -| `fs.config.symlink` | warn | configの実体が別の信頼境界になる | config fileのファイルシステムレイアウト | no | -| `fs.config.perms_group_readable` | warn | グループユーザーがconfig token/settingsを読める | config fileのファイルシステム権限 | yes | -| `fs.config.perms_world_readable` | critical | configからtoken/settingsが漏れる可能性がある | config fileのファイルシステム権限 | yes | -| `fs.config_include.perms_writable` | critical | config include fileを他者が変更できる | `openclaw.json` から参照されるinclude-fileの権限 | yes | -| `fs.config_include.perms_group_readable` | warn | グループユーザーがincludeされたsecret/settingsを読める | `openclaw.json` から参照されるinclude-fileの権限 | yes | -| `fs.config_include.perms_world_readable` | critical | includeされたsecret/settingsがworld-readable | `openclaw.json` から参照されるinclude-fileの権限 | yes | -| `fs.auth_profiles.perms_writable` | critical | 他者が保存済みmodel credentialを注入/置換できる | `agents//agent/auth-profiles.json` の権限 | yes | -| `fs.auth_profiles.perms_readable` | warn | 他者がAPI keysとOAuth tokensを読める | `agents//agent/auth-profiles.json` の権限 | yes | -| `fs.credentials_dir.perms_writable` | critical | 他者がchannel pairing/credential stateを変更できる | `~/.openclaw/credentials` のファイルシステム権限 | yes | -| `fs.credentials_dir.perms_readable` | warn | 他者がchannel credential stateを読める | `~/.openclaw/credentials` のファイルシステム権限 | yes | -| `fs.sessions_store.perms_readable` | warn | 他者がsession transcript/metadataを読める | session storeの権限 | yes | -| `fs.log_file.perms_readable` | warn | 他者が、redact済みでも機微なlogを読める | gateway log fileの権限 | yes | -| `fs.synced_dir` | warn | state/configをiCloud/Dropbox/Driveに置くとtoken/transcript露出が広がる | config/stateを同期フォルダーから外す | no | -| `gateway.bind_no_auth` | critical | リモートbindなのに共有secretがない | `gateway.bind`, `gateway.auth.*` | no | -| `gateway.loopback_no_auth` | critical | reverse proxy越しのloopbackが未認証になる可能性がある | `gateway.auth.*`, proxy setup | no | -| `gateway.trusted_proxies_missing` | warn | reverse-proxyヘッダーがあるのにtrustedではない | `gateway.trustedProxies` | no | -| `gateway.http.no_auth` | warn/critical | `auth.mode="none"` でGateway HTTP APIへ到達できる | `gateway.auth.mode`, `gateway.http.endpoints.*` | no | -| `gateway.http.session_key_override_enabled` | info | HTTP API呼び出し元が `sessionKey` を上書きできる | `gateway.http.allowSessionKeyOverride` | no | -| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | HTTP API経由で危険なtoolsを再有効化している | `gateway.tools.allow` | no | -| `gateway.nodes.allow_commands_dangerous` | warn/critical | 高影響なnode commands（camera/screen/contacts/calendar/SMS）を有効にする | `gateway.nodes.allowCommands` | no | -| `gateway.nodes.deny_commands_ineffective` | warn | パターン風deny項目がshell textやgroupに一致しない | `gateway.nodes.denyCommands` | no | -| `gateway.tailscale_funnel` | critical | パブリックインターネット露出 | `gateway.tailscale.mode` | no | -| `gateway.tailscale_serve` | info | Serve経由のtailnet露出が有効 | `gateway.tailscale.mode` | no | -| `gateway.control_ui.allowed_origins_required` | critical | 非loopbackのControl UIなのにbrowser-origin allowlistがない | `gateway.controlUi.allowedOrigins` | no | -| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` でbrowser-origin allowlistingを無効化 | `gateway.controlUi.allowedOrigins` | no | -| `gateway.control_ui.host_header_origin_fallback` | warn/critical | Host-header origin fallbackを有効にしている（DNS rebinding対策の低下） | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | no | -| `gateway.control_ui.insecure_auth` | warn | insecure-auth互換トグルが有効 | `gateway.controlUi.allowInsecureAuth` | no | -| `gateway.control_ui.device_auth_disabled` | critical | device identity checkを無効化している | `gateway.controlUi.dangerouslyDisableDeviceAuth` | no | -| `gateway.real_ip_fallback_enabled` | warn/critical | `X-Real-IP` フォールバックを信頼するとproxy誤設定時にsource-IP偽装が可能 | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | no | -| `gateway.token_too_short` | warn | 共有tokenが短く総当たりされやすい | `gateway.auth.token` | no | -| `gateway.auth_no_rate_limit` | warn | 公開authなのにrate limitがなく、総当たりリスクが高い | `gateway.auth.rateLimit` | no | -| `gateway.trusted_proxy_auth` | critical | proxy identityがauth境界になる | `gateway.auth.mode="trusted-proxy"` | no | -| `gateway.trusted_proxy_no_proxies` | critical | trusted-proxy authなのにtrusted proxy IPがない | `gateway.trustedProxies` | no | -| `gateway.trusted_proxy_no_user_header` | critical | trusted-proxy authがユーザーidentityを安全に解決できない | `gateway.auth.trustedProxy.userHeader` | no | -| `gateway.trusted_proxy_no_allowlist` | warn | trusted-proxy authが認証済み上流ユーザーを誰でも受け入れる | `gateway.auth.trustedProxy.allowUsers` | no | -| `gateway.probe_auth_secretref_unavailable` | warn | deep probeがこのコマンド経路でauth SecretRefを解決できなかった | deep-probe auth source / SecretRef availability | no | -| `gateway.probe_failed` | warn/critical | ライブGateway probeに失敗した | gateway reachability/auth | no | -| `discovery.mdns_full_mode` | warn/critical | mDNS full modeが `cliPath`/`sshPort` をローカルネットワークに公開する | `discovery.mdns.mode`, `gateway.bind` | no | -| `config.insecure_or_dangerous_flags` | warn | insecure/dangerousなdebug flagsが有効 | 複数キー（詳細参照） | no | -| `config.secrets.gateway_password_in_config` | warn | Gateway passwordをconfigに直接保存している | `gateway.auth.password` | no | -| `config.secrets.hooks_token_in_config` | warn | hook bearer tokenをconfigに直接保存している | `hooks.token` | no | -| `hooks.token_reuse_gateway_token` | critical | hook ingress tokenがGateway authも解除できる | `hooks.token`, `gateway.auth.token` | no | -| `hooks.token_too_short` | warn | hook ingressが総当たりされやすい | `hooks.token` | no | -| `hooks.default_session_key_unset` | warn | hook agent runがリクエストごとの生成sessionへ分散する | `hooks.defaultSessionKey` | no | -| `hooks.allowed_agent_ids_unrestricted` | warn/critical | 認証済みhook呼び出し元が任意のconfigured agentへルーティングできる | `hooks.allowedAgentIds` | no | -| `hooks.request_session_key_enabled` | warn/critical | 外部呼び出し元がsessionKeyを選べる | `hooks.allowRequestSessionKey` | no | -| `hooks.request_session_key_prefixes_missing` | warn/critical | 外部session key形式への制約がない | `hooks.allowedSessionKeyPrefixes` | no | -| `hooks.path_root` | critical | hook pathが `/` で、衝突や誤ルーティングが起きやすい | `hooks.path` | no | -| `hooks.installs_unpinned_npm_specs` | warn | hook install recordが不変なnpm specに固定されていない | hook install metadata | no | -| `hooks.installs_missing_integrity` | warn | hook install recordにintegrity metadataがない | hook install metadata | no | -| `hooks.installs_version_drift` | warn | hook install recordとインストール済みpackageがずれている | hook install metadata | no | -| `logging.redact_off` | warn | 機微値がlogs/statusに漏れる | `logging.redactSensitive` | yes | -| `browser.control_invalid_config` | warn | browser control configが実行前から無効 | `browser.*` | no | -| `browser.control_no_auth` | critical | browser controlがtoken/password authなしで露出 | `gateway.auth.*` | no | -| `browser.remote_cdp_http` | warn | plain HTTP上のremote CDPはtransport encryptionがない | browser profile `cdpUrl` | no | -| `browser.remote_cdp_private_host` | warn | remote CDPがprivate/internal hostを向いている | browser profile `cdpUrl`, `browser.ssrfPolicy.*` | no | -| `sandbox.docker_config_mode_off` | warn | sandbox Docker configがあるのに無効 | `agents.*.sandbox.mode` | no | -| `sandbox.bind_mount_non_absolute` | warn | 相対bind mountは予測不能に解決される可能性がある | `agents.*.sandbox.docker.binds[]` | no | -| `sandbox.dangerous_bind_mount` | critical | sandbox bind mount先が禁止system/credential/Docker socket path | `agents.*.sandbox.docker.binds[]` | no | -| `sandbox.dangerous_network_mode` | critical | sandbox Docker networkが `host` または `container:*` 名前空間共有モード | `agents.*.sandbox.docker.network` | no | -| `sandbox.dangerous_seccomp_profile` | critical | sandbox seccomp profileがcontainer isolationを弱める | `agents.*.sandbox.docker.securityOpt` | no | -| `sandbox.dangerous_apparmor_profile` | critical | sandbox AppArmor profileがcontainer isolationを弱める | `agents.*.sandbox.docker.securityOpt` | no | -| `sandbox.browser_cdp_bridge_unrestricted` | warn | sandbox browser bridgeが送信元制限なしで露出 | `sandbox.browser.cdpSourceRange` | no | -| `sandbox.browser_container.non_loopback_publish` | critical | 既存browser containerが非loopback interfaceでCDPを公開している | browser sandbox container publish config | no | -| `sandbox.browser_container.hash_label_missing` | warn | 既存browser containerが現行config-hash label以前のもの | `openclaw sandbox recreate --browser --all` | no | -| `sandbox.browser_container.hash_epoch_stale` | warn | 既存browser containerが現行browser config epoch以前のもの | `openclaw sandbox recreate --browser --all` | no | -| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | `exec host=sandbox` はsandbox off時にfail-closedする | `tools.exec.host`, `agents.defaults.sandbox.mode` | no | -| `tools.exec.host_sandbox_no_sandbox_agents` | warn | agent単位の `exec host=sandbox` はsandbox off時にfail-closedする | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | no | -| `tools.exec.security_full_configured` | warn/critical | Host execが `security="full"` で動作している | `tools.exec.security`, `agents.list[].tools.exec.security` | no | -| `tools.exec.auto_allow_skills_enabled` | warn | Exec approvalsがskill binを暗黙に信頼している | `~/.openclaw/exec-approvals.json` | no | -| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Interpreter allowlistでinline evalが再承認なしに通る | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, exec approvals allowlist | no | -| `tools.exec.safe_bins_interpreter_unprofiled` | warn | `safeBins` のinterpreter/runtime binsが明示profileなしでexecリスクを広げる | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | no | -| `tools.exec.safe_bins_broad_behavior` | warn | 広い振る舞いのtoolsを `safeBins` に入れると低リスクstdin-filter信頼モデルが弱まる | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | no | -| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` に変更可能または危険なディレクトリが含まれる | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | no | -| `skills.workspace.symlink_escape` | warn | workspaceの `skills/**/SKILL.md` がworkspace root外へ解決される | workspace `skills/**` のファイルシステム状態 | no | -| `plugins.extensions_no_allowlist` | warn | 明示plugin allowlistなしでextensionsがインストールされている | `plugins.allowlist` | no | -| `plugins.installs_unpinned_npm_specs` | warn | plugin install recordが不変なnpm specに固定されていない | plugin install metadata | no | -| `plugins.installs_missing_integrity` | warn | plugin install recordにintegrity metadataがない | plugin install metadata | no | -| `plugins.installs_version_drift` | warn | plugin install recordとインストール済みpackageがずれている | plugin install metadata | no | -| `plugins.code_safety` | warn/critical | plugin code scanで疑わしい/危険なパターンが見つかった | plugin code / install source | no | -| `plugins.code_safety.entry_path` | warn | plugin entry pathが隠し場所や `node_modules` を指している | plugin manifest `entry` | no | -| `plugins.code_safety.entry_escape` | critical | plugin entryがplugin directoryを逸脱している | plugin manifest `entry` | no | -| `plugins.code_safety.scan_failed` | warn | plugin code scanを完了できなかった | plugin extension path / scan environment | no | -| `skills.code_safety` | warn/critical | skill installer metadata/codeに疑わしい/危険なパターンがある | skill install source | no | -| `skills.code_safety.scan_failed` | warn | skill code scanを完了できなかった | skill scan environment | no | -| `security.exposure.open_channels_with_exec` | warn/critical | 共有/公開roomからexec有効agentに到達できる | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | no | -| `security.exposure.open_groups_with_elevated` | critical | オープングループ + elevated toolsで高影響なprompt injection経路ができる | `channels.*.groupPolicy`, `tools.elevated.*` | no | -| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | オープングループからsandbox/workspace guardなしでcommand/file toolsに到達できる | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | no | -| `security.trust_model.multi_user_heuristic` | warn | configがmulti-userに見えるがgateway trust modelは個人アシスタント前提 | 信頼境界を分割、または共有ユーザー強化（`sandbox.mode`、tool deny/workspace scoping） | no | -| `tools.profile_minimal_overridden` | warn | agent overrideがグローバルminimal profileを迂回している | `agents.list[].tools.profile` | no | -| `plugins.tools_reachable_permissive_policy` | warn | permissive policy下でextension toolsに到達できる | `tools.profile` + tool allow/deny | no | -| `models.legacy` | warn | legacy model familyがまだ設定されている | model selection | no | -| `models.weak_tier` | warn | 設定モデルが現在の推奨tierより弱い | model selection | no | -| `models.small_params` | critical/info | 小さいモデル + 危険なtool surfaceでinjectionリスクが上がる | model choice + sandbox/tool policy | no | -| `summary.attack_surface` | info | auth、channel、tool、exposure姿勢の集約サマリー | 複数キー（詳細参照） | no | +| `checkId` | 重大度 | 重要な理由 | 主な修正キー／パス | 自動修正 | +| ------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | +| `fs.state_dir.perms_world_writable` | critical | 他のユーザー／プロセスがOpenClawの状態全体を変更できる | `~/.openclaw` のファイルシステム権限 | あり | +| `fs.state_dir.perms_group_writable` | warn | 同じグループのユーザーがOpenClawの状態全体を変更できる | `~/.openclaw` のファイルシステム権限 | あり | +| `fs.state_dir.perms_readable` | warn | stateディレクトリを他者が読み取れる | `~/.openclaw` のファイルシステム権限 | あり | +| `fs.state_dir.symlink` | warn | stateディレクトリの参照先が別の信頼境界になる | stateディレクトリのファイルシステムレイアウト | なし | +| `fs.config.perms_writable` | critical | 他者がauth／ツールポリシー／設定を変更できる | `~/.openclaw/openclaw.json` のファイルシステム権限 | あり | +| `fs.config.symlink` | warn | configの参照先が別の信頼境界になる | configファイルのファイルシステムレイアウト | なし | +| `fs.config.perms_group_readable` | warn | 同じグループのユーザーがconfig内のトークン／設定を読める | configファイルのファイルシステム権限 | あり | +| `fs.config.perms_world_readable` | critical | configからトークン／設定が露出する可能性がある | configファイルのファイルシステム権限 | あり | +| `fs.config_include.perms_writable` | critical | config includeファイルを他者が変更できる | `openclaw.json` から参照されるincludeファイルの権限 | あり | +| `fs.config_include.perms_group_readable` | warn | 同じグループのユーザーがincludeされたシークレット／設定を読める | `openclaw.json` から参照されるincludeファイルの権限 | あり | +| `fs.config_include.perms_world_readable` | critical | includeされたシークレット／設定が誰でも読める | `openclaw.json` から参照されるincludeファイルの権限 | あり | +| `fs.auth_profiles.perms_writable` | critical | 他者が保存済みモデル認証情報を注入または置換できる | `agents//agent/auth-profiles.json` の権限 | あり | +| `fs.auth_profiles.perms_readable` | warn | 他者がAPIキーやOAuthトークンを読める | `agents//agent/auth-profiles.json` の権限 | あり | +| `fs.credentials_dir.perms_writable` | critical | 他者がチャネルのペアリング／認証情報状態を変更できる | `~/.openclaw/credentials` のファイルシステム権限 | あり | +| `fs.credentials_dir.perms_readable` | warn | 他者がチャネルの認証情報状態を読める | `~/.openclaw/credentials` のファイルシステム権限 | あり | +| `fs.sessions_store.perms_readable` | warn | 他者がセッショントランスクリプト／メタデータを読める | セッションストアの権限 | あり | +| `fs.log_file.perms_readable` | warn | 他者が、マスク済みではあるが依然として機微なログを読める | Gatewayログファイルの権限 | あり | +| `fs.synced_dir` | warn | iCloud／Dropbox／Drive内のstate／configは、トークン／トランスクリプト露出範囲を広げる | config／stateを同期フォルダーから移動する | なし | +| `gateway.bind_no_auth` | critical | 共有シークレットなしでリモートbindしている | `gateway.bind`、`gateway.auth.*` | なし | +| `gateway.loopback_no_auth` | critical | リバースプロキシ経由のloopbackが未認証になる可能性がある | `gateway.auth.*`、プロキシ設定 | なし | +| `gateway.trusted_proxies_missing` | warn | リバースプロキシヘッダーが存在するのに信頼されていない | `gateway.trustedProxies` | なし | +| `gateway.http.no_auth` | warn/critical | `auth.mode="none"` の状態でGateway HTTP APIに到達できる | `gateway.auth.mode`、`gateway.http.endpoints.*` | なし | +| `gateway.http.session_key_override_enabled` | info | HTTP API呼び出し元が `sessionKey` を上書きできる | `gateway.http.allowSessionKeyOverride` | なし | +| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | HTTP API経由で危険なツールを再有効化する | `gateway.tools.allow` | なし | +| `gateway.nodes.allow_commands_dangerous` | warn/critical | 影響の大きいnodeコマンド（camera／screen／contacts／calendar／SMS）を有効にする | `gateway.nodes.allowCommands` | なし | +| `gateway.nodes.deny_commands_ineffective` | warn | denyエントリーのパターン風指定は、シェルテキストやグループにはマッチしない | `gateway.nodes.denyCommands` | なし | +| `gateway.tailscale_funnel` | critical | 公開インターネットへの露出 | `gateway.tailscale.mode` | なし | +| `gateway.tailscale_serve` | info | Serve経由のtailnet露出が有効になっている | `gateway.tailscale.mode` | なし | +| `gateway.control_ui.allowed_origins_required` | critical | loopback以外のControl UIで、明示的なブラウザオリジン許可リストがない | `gateway.controlUi.allowedOrigins` | なし | +| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` によりブラウザオリジン許可リストが無効化される | `gateway.controlUi.allowedOrigins` | なし | +| `gateway.control_ui.host_header_origin_fallback` | warn/critical | Hostヘッダー由来のオリジンフォールバックを有効にし、DNS rebinding対策が弱まる | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | なし | +| `gateway.control_ui.insecure_auth` | warn | 互換性のための安全でないauthトグルが有効になっている | `gateway.controlUi.allowInsecureAuth` | なし | +| `gateway.control_ui.device_auth_disabled` | critical | デバイスアイデンティティチェックを無効化する | `gateway.controlUi.dangerouslyDisableDeviceAuth` | なし | +| `gateway.real_ip_fallback_enabled` | warn/critical | `X-Real-IP` フォールバックを信頼すると、プロキシ誤設定経由で送信元IP偽装が可能になる | `gateway.allowRealIpFallback`、`gateway.trustedProxies` | なし | +| `gateway.token_too_short` | warn | 短い共有トークンは総当たりしやすい | `gateway.auth.token` | なし | +| `gateway.auth_no_rate_limit` | warn | 認証付きの公開面にレート制限がないと総当たりリスクが高まる | `gateway.auth.rateLimit` | なし | +| `gateway.trusted_proxy_auth` | critical | プロキシのアイデンティティがauth境界になる | `gateway.auth.mode="trusted-proxy"` | なし | +| `gateway.trusted_proxy_no_proxies` | critical | trusted-proxy authなのに信頼するプロキシIPがないのは安全ではない | `gateway.trustedProxies` | なし | +| `gateway.trusted_proxy_no_user_header` | critical | trusted-proxy authでユーザーアイデンティティを安全に解決できない | `gateway.auth.trustedProxy.userHeader` | なし | +| `gateway.trusted_proxy_no_allowlist` | warn | trusted-proxy authで、認証済みの任意の上流ユーザーを受け入れてしまう | `gateway.auth.trustedProxy.allowUsers` | なし | +| `checkId` | 重大度 | 重要な理由 | 主な修正キー／パス | 自動修正 | +| ------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | +| `gateway.probe_auth_secretref_unavailable` | warn | このコマンド経路ではディーププローブがauth SecretRefを解決できなかった | ディーププローブのauthソース／SecretRefの可用性 | なし | +| `gateway.probe_failed` | warn/critical | ライブGatewayプローブが失敗した | Gatewayの到達性／auth | なし | +| `discovery.mdns_full_mode` | warn/critical | mDNSのfullモードはローカルネットワーク上に `cliPath`／`sshPort` メタデータを広告する | `discovery.mdns.mode`、`gateway.bind` | なし | +| `config.insecure_or_dangerous_flags` | warn | 安全でない／危険なデバッグフラグが有効になっている | 複数のキー（検出詳細を参照） | なし | +| `config.secrets.gateway_password_in_config` | warn | Gatewayパスワードがconfig内に直接保存されている | `gateway.auth.password` | なし | +| `config.secrets.hooks_token_in_config` | warn | Hook bearer tokenがconfig内に直接保存されている | `hooks.token` | なし | +| `hooks.token_reuse_gateway_token` | critical | Hook受信トークンがGateway authの解除にも使われる | `hooks.token`、`gateway.auth.token` | なし | +| `hooks.token_too_short` | warn | Hook受信で総当たりが容易になる | `hooks.token` | なし | +| `hooks.default_session_key_unset` | warn | Hookエージェントの実行が、リクエストごとに生成されるセッションへファンアウトする | `hooks.defaultSessionKey` | なし | +| `hooks.allowed_agent_ids_unrestricted` | warn/critical | 認証済みHook呼び出し元が、設定済みの任意のエージェントへルーティングできる | `hooks.allowedAgentIds` | なし | +| `hooks.request_session_key_enabled` | warn/critical | 外部呼び出し元が `sessionKey` を選べる | `hooks.allowRequestSessionKey` | なし | +| `hooks.request_session_key_prefixes_missing` | warn/critical | 外部セッションキーの形状に制限がない | `hooks.allowedSessionKeyPrefixes` | なし | +| `hooks.path_root` | critical | Hookパスが `/` のため、受信が衝突または誤ルーティングしやすい | `hooks.path` | なし | +| `hooks.installs_unpinned_npm_specs` | warn | Hookインストール記録が不変のnpm specに固定されていない | Hookインストールメタデータ | なし | +| `hooks.installs_missing_integrity` | warn | Hookインストール記録に整合性メタデータがない | Hookインストールメタデータ | なし | +| `hooks.installs_version_drift` | warn | Hookインストール記録がインストール済みパッケージとずれている | Hookインストールメタデータ | なし | +| `logging.redact_off` | warn | 機密値がログ／statusへ漏れる | `logging.redactSensitive` | あり | +| `browser.control_invalid_config` | warn | ランタイム前の時点でブラウザ制御設定が不正 | `browser.*` | なし | +| `browser.control_no_auth` | critical | トークン／パスワードauthなしでブラウザ制御が公開されている | `gateway.auth.*` | なし | +| `browser.remote_cdp_http` | warn | 平文HTTP経由のリモートCDPには通信の暗号化がない | ブラウザプロファイルの `cdpUrl` | なし | +| `browser.remote_cdp_private_host` | warn | リモートCDPの対象がプライベート／内部ホストである | ブラウザプロファイルの `cdpUrl`、`browser.ssrfPolicy.*` | なし | +| `sandbox.docker_config_mode_off` | warn | Sandbox Docker設定はあるが有効化されていない | `agents.*.sandbox.mode` | なし | +| `sandbox.bind_mount_non_absolute` | warn | 相対bind mountは予測しにくい形で解決される可能性がある | `agents.*.sandbox.docker.binds[]` | なし | +| `sandbox.dangerous_bind_mount` | critical | Sandboxのbind mount先が、ブロック対象のシステム／認証情報／Dockerソケットのパスである | `agents.*.sandbox.docker.binds[]` | なし | +| `sandbox.dangerous_network_mode` | critical | Sandbox Dockerネットワークが `host` または `container:*` の名前空間共有モードを使う | `agents.*.sandbox.docker.network` | なし | +| `sandbox.dangerous_seccomp_profile` | critical | Sandbox seccompプロファイルがコンテナ分離を弱める | `agents.*.sandbox.docker.securityOpt` | なし | +| `sandbox.dangerous_apparmor_profile` | critical | Sandbox AppArmorプロファイルがコンテナ分離を弱める | `agents.*.sandbox.docker.securityOpt` | なし | +| `sandbox.browser_cdp_bridge_unrestricted` | warn | Sandboxブラウザブリッジが送信元範囲制限なしで公開されている | `sandbox.browser.cdpSourceRange` | なし | +| `sandbox.browser_container.non_loopback_publish` | critical | 既存のブラウザコンテナが、loopback以外のインターフェースでCDPを公開している | ブラウザsandboxコンテナの公開設定 | なし | +| `sandbox.browser_container.hash_label_missing` | warn | 既存のブラウザコンテナは、現在のconfig-hashラベル導入前のものである | `openclaw sandbox recreate --browser --all` | なし | +| `sandbox.browser_container.hash_epoch_stale` | warn | 既存のブラウザコンテナは、現在のブラウザ設定エポックより前のものである | `openclaw sandbox recreate --browser --all` | なし | +| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | sandboxがオフのとき、`exec host=sandbox` はフェイルクローズする | `tools.exec.host`、`agents.defaults.sandbox.mode` | なし | +| `tools.exec.host_sandbox_no_sandbox_agents` | warn | エージェント単位の `exec host=sandbox` は、sandboxがオフのときフェイルクローズする | `agents.list[].tools.exec.host`、`agents.list[].sandbox.mode` | なし | +| `tools.exec.security_full_configured` | warn/critical | ホストexecが `security="full"` で実行されている | `tools.exec.security`、`agents.list[].tools.exec.security` | なし | +| `tools.exec.auto_allow_skills_enabled` | warn | Exec承認がskill binを暗黙に信頼する | `~/.openclaw/exec-approvals.json` | なし | +| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | インタープリター許可リストが、再承認を強制せずにインラインevalを許可する | `tools.exec.strictInlineEval`、`agents.list[].tools.exec.strictInlineEval`、exec approvals allowlist | なし | +| `tools.exec.safe_bins_interpreter_unprofiled` | warn | `safeBins` にあるインタープリター／ランタイムbinが明示プロファイルなしでexecリスクを広げる | `tools.exec.safeBins`、`tools.exec.safeBinProfiles`、`agents.list[].tools.exec.*` | なし | +| `tools.exec.safe_bins_broad_behavior` | warn | `safeBins` にある広範動作ツールが、低リスクstdinフィルタ信頼モデルを弱める | `tools.exec.safeBins`、`agents.list[].tools.exec.safeBins` | なし | +| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` に可変または危険なディレクトリが含まれている | `tools.exec.safeBinTrustedDirs`、`agents.list[].tools.exec.safeBinTrustedDirs` | なし | +| `skills.workspace.symlink_escape` | warn | ワークスペースの `skills/**/SKILL.md` がワークスペースルート外を解決する（symlink連鎖のずれ） | ワークスペース `skills/**` のファイルシステム状態 | なし | +| `plugins.extensions_no_allowlist` | warn | 明示的なプラグイン許可リストなしで拡張機能がインストールされている | `plugins.allowlist` | なし | +| `plugins.installs_unpinned_npm_specs` | warn | プラグインインストール記録が不変のnpm specに固定されていない | プラグインインストールメタデータ | なし | +| `checkId` | 重大度 | 重要な理由 | 主な修正キー／パス | 自動修正 | +| ------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | +| `plugins.installs_missing_integrity` | warn | プラグインインストール記録に整合性メタデータがない | プラグインインストールメタデータ | なし | +| `plugins.installs_version_drift` | warn | プラグインインストール記録がインストール済みパッケージとずれている | プラグインインストールメタデータ | なし | +| `plugins.code_safety` | warn/critical | プラグインコードスキャンで疑わしいまたは危険なパターンが見つかった | プラグインコード／インストール元 | なし | +| `plugins.code_safety.entry_path` | warn | プラグインのエントリーパスが隠し場所または `node_modules` 配下を指している | プラグインマニフェストの `entry` | なし | +| `plugins.code_safety.entry_escape` | critical | プラグインのエントリーがプラグインディレクトリ外へ抜けている | プラグインマニフェストの `entry` | なし | +| `plugins.code_safety.scan_failed` | warn | プラグインコードスキャンを完了できなかった | プラグイン拡張パス／スキャン環境 | なし | +| `skills.code_safety` | warn/critical | Skillインストーラーメタデータ／コードに疑わしいまたは危険なパターンが含まれる | Skillインストール元 | なし | +| `skills.code_safety.scan_failed` | warn | Skillコードスキャンを完了できなかった | Skillスキャン環境 | なし | +| `security.exposure.open_channels_with_exec` | warn/critical | 共有／公開ルームからexec有効化済みエージェントへ到達できる | `channels.*.dmPolicy`、`channels.*.groupPolicy`、`tools.exec.*`、`agents.list[].tools.exec.*` | なし | +| `security.exposure.open_groups_with_elevated` | critical | オープングループ + 昇格ツールは、影響の大きいプロンプトインジェクション経路を作る | `channels.*.groupPolicy`、`tools.elevated.*` | なし | +| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | オープングループから、sandbox／workspaceガードなしでコマンド／ファイルツールへ到達できる | `channels.*.groupPolicy`、`tools.profile/deny`、`tools.fs.workspaceOnly`、`agents.*.sandbox.mode` | なし | +| `security.trust_model.multi_user_heuristic` | warn | Gatewayの信頼モデルはパーソナルアシスタントなのに、configがマルチユーザーに見える | 信頼境界を分離する、または共有ユーザー向け強化（`sandbox.mode`、tool deny／workspaceスコープ化） | なし | +| `tools.profile_minimal_overridden` | warn | エージェントの上書きがグローバルなminimalプロファイルを迂回している | `agents.list[].tools.profile` | なし | +| `plugins.tools_reachable_permissive_policy` | warn | 緩いポリシー文脈で拡張ツールへ到達可能 | `tools.profile` + tool allow/deny | なし | +| `models.legacy` | warn | レガシーモデルファミリーがまだ設定されている | モデル選択 | なし | +| `models.weak_tier` | warn | 設定されたモデルが現在の推奨ティアを下回っている | モデル選択 | なし | +| `models.small_params` | critical/info | 小規模モデル + 安全でないツールサーフェスはインジェクションリスクを高める | モデル選択 + sandbox／ツールポリシー | なし | +| `summary.attack_surface` | info | auth、チャネル、ツール、露出姿勢の要約 | 複数のキー（検出詳細を参照） | なし | ## HTTP経由のControl UI -Control UIはdevice identityを生成するために**安全なコンテキスト**（HTTPSまたはlocalhost）を必要とします。`gateway.controlUi.allowInsecureAuth` はローカル互換トグルです。 +Control UIがデバイスアイデンティティを生成するには、**安全なコンテキスト**（HTTPSまたはlocalhost）が必要です。`gateway.controlUi.allowInsecureAuth` はローカル互換用のトグルです。 -- localhostでは、ページが非安全HTTPで読み込まれた場合に、device identityなしでControl UI authを許可します。 -- これはpairing checksを回避しません。 -- リモート（non-localhost）のdevice identity要件を緩めることもありません。 +- localhost上では、ページが安全でないHTTPで読み込まれた場合でも、デバイスアイデンティティなしでControl UI認証を許可します。 +- これはペアリングチェックをバイパスしません。 +- リモート（localhost以外）のデバイスアイデンティティ要件は緩和しません。 -HTTPS（Tailscale Serve）を優先するか、UIを `127.0.0.1` で開いてください。 +HTTPS（Tailscale Serve）を優先するか、UIを `127.0.0.1` 上で開いてください。 -緊急時専用として、`gateway.controlUi.dangerouslyDisableDeviceAuth` はdevice identity checksを完全に無効化します。これは重大なセキュリティ低下です。積極的にデバッグしていて、すぐに元へ戻せる場合以外はoffのままにしてください。 +緊急時専用の手段として、`gateway.controlUi.dangerouslyDisableDeviceAuth` はデバイスアイデンティティチェックを完全に無効化します。これは重大なセキュリティ低下です。積極的にデバッグしていて、すぐに元へ戻せる場合を除き、無効のままにしてください。 -それらのdangerous flagsとは別に、成功した `gateway.auth.mode: "trusted-proxy"` は、device identityなしで**operator**のControl UI sessionを受け入れられます。これは意図されたauth-mode挙動であり、`allowInsecureAuth` の近道ではありません。また、node-roleのControl UI sessionには広がりません。 +これらの危険なフラグとは別に、`gateway.auth.mode: "trusted-proxy"` が成功すると、デバイスアイデンティティなしで**運用者**のControl UIセッションを受け入れることがあります。これは意図されたauthモードの挙動であり、`allowInsecureAuth` の近道ではありません。また、nodeロールのControl UIセッションには適用されません。 -`openclaw security audit` は、この設定が有効なとき警告します。 +`openclaw security audit` は、この設定が有効な場合に警告します。 -## insecureまたはdangerous flagsの要約 +## 安全でない／危険なフラグの概要 -`openclaw security audit` は、既知の insecure/dangerous debug switchesが有効だと `config.insecure_or_dangerous_flags` を含めます。現在このチェックが集約しているのは次です。 +`openclaw security audit` は、既知の安全でない／危険なデバッグスイッチが有効な場合、`config.insecure_or_dangerous_flags` を含めます。現在このチェックで集約されるのは次のとおりです。 - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` @@ -375,7 +379,7 @@ HTTPS（Tailscale Serve）を優先するか、UIを `127.0.0.1` で開いてく - `tools.exec.applyPatch.workspaceOnly=false` - `plugins.entries.acpx.config.permissionMode=approve-all` -OpenClaw config schemaで定義されている完全な `dangerous*` / `dangerously*` キー: +OpenClawのconfigスキーマで定義されている、完全な `dangerous*` / `dangerously*` configキーは次のとおりです。 - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` @@ -387,15 +391,15 @@ OpenClaw config schemaで定義されている完全な `dangerous*` / `dangerou - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.googlechat.accounts..dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` -- `channels.synology-chat.dangerouslyAllowNameMatching` (extension channel) -- `channels.synology-chat.accounts..dangerouslyAllowNameMatching` (extension channel) -- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (extension channel) -- `channels.zalouser.dangerouslyAllowNameMatching` (extension channel) -- `channels.zalouser.accounts..dangerouslyAllowNameMatching` (extension channel) -- `channels.irc.dangerouslyAllowNameMatching` (extension channel) -- `channels.irc.accounts..dangerouslyAllowNameMatching` (extension channel) -- `channels.mattermost.dangerouslyAllowNameMatching` (extension channel) -- `channels.mattermost.accounts..dangerouslyAllowNameMatching` (extension channel) +- `channels.synology-chat.dangerouslyAllowNameMatching`（拡張チャネル） +- `channels.synology-chat.accounts..dangerouslyAllowNameMatching`（拡張チャネル） +- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath`（拡張チャネル） +- `channels.zalouser.dangerouslyAllowNameMatching`（拡張チャネル） +- `channels.zalouser.accounts..dangerouslyAllowNameMatching`（拡張チャネル） +- `channels.irc.dangerouslyAllowNameMatching`（拡張チャネル） +- `channels.irc.accounts..dangerouslyAllowNameMatching`（拡張チャネル） +- `channels.mattermost.dangerouslyAllowNameMatching`（拡張チャネル） +- `channels.mattermost.accounts..dangerouslyAllowNameMatching`（拡張チャネル） - `channels.telegram.network.dangerouslyAllowPrivateNetwork` - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` @@ -405,132 +409,130 @@ OpenClaw config schemaで定義されている完全な `dangerous*` / `dangerou - `agents.list[].sandbox.docker.dangerouslyAllowExternalBindSources` - `agents.list[].sandbox.docker.dangerouslyAllowContainerNamespaceJoin` -## Reverse Proxy設定 +## リバースプロキシ設定 -Gatewayをreverse proxy（nginx、Caddy、Traefikなど）の背後で動かす場合、forwarded-client IPを正しく扱うために `gateway.trustedProxies` を設定してください。 +Gatewayをリバースプロキシ（nginx、Caddy、Traefikなど）の背後で動かす場合は、転送されたクライアントIPを正しく扱うために `gateway.trustedProxies` を設定してください。 -Gatewayが、`trustedProxies` に入っていないアドレスから来たproxy headersを検出すると、その接続を**ローカルクライアントとして扱いません**。gateway authが無効なら、その接続は拒否されます。これにより、proxy越しの接続がlocalhost由来に見えて自動信頼される認証バイパスを防ぎます。 +Gatewayが、`trustedProxies` に**含まれていない**アドレスからのプロキシヘッダーを検出した場合、その接続をローカルクライアントとしては扱いません。Gateway authが無効なら、その接続は拒否されます。これにより、プロキシ経由の接続がlocalhostから来たように見えて自動的に信頼される、という認証バイパスを防げます。 -`gateway.trustedProxies` は `gateway.auth.mode: "trusted-proxy"` にも使われますが、このauth modeはさらに厳格です。 +`gateway.trustedProxies` は `gateway.auth.mode: "trusted-proxy"` にも使われますが、このauthモードはさらに厳格です。 -- trusted-proxy authは**loopback-source proxyに対してfail-closed**する -- 同一host上のloopback reverse proxyでも、`gateway.trustedProxies` はlocal-client判定とforwarded IP処理に使える -- 同一hostのloopback reverse proxyでは、`gateway.auth.mode: "trusted-proxy"` ではなくtoken/password authを使う +- trusted-proxy authは**loopback送信元のプロキシに対してフェイルクローズ**します。 +- 同一ホスト上のloopbackリバースプロキシは、ローカルクライアント判定と転送IP処理のために `gateway.trustedProxies` を引き続き利用できます。 +- 同一ホスト上のloopbackリバースプロキシでは、`gateway.auth.mode: "trusted-proxy"` ではなく、token/password authを使用してください。 ```yaml gateway: trustedProxies: - "10.0.0.1" # reverse proxy IP - # Optional. Default false. - # Only enable if your proxy cannot provide X-Forwarded-For. + # 任意。デフォルトはfalse。 + # プロキシが X-Forwarded-For を提供できない場合にのみ有効化してください。 allowRealIpFallback: false auth: mode: password password: ${OPENCLAW_GATEWAY_PASSWORD} ``` -`trustedProxies` が設定されていると、Gatewayは `X-Forwarded-For` を使ってclient IPを決定します。`X-Real-IP` は、`gateway.allowRealIpFallback: true` を明示しない限りデフォルトでは無視されます。 +`trustedProxies` が設定されている場合、GatewayはクライアントIPの判定に `X-Forwarded-For` を使います。`X-Real-IP` は、`gateway.allowRealIpFallback: true` が明示的に設定されていない限り、デフォルトでは無視されます。 -良いreverse proxy挙動（受信したforwarding headersを上書きする）: +良いリバースプロキシの挙動（受信した転送ヘッダーを上書きする）: ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -悪いreverse proxy挙動（信頼できないforwarding headersを追加/保持する）: +悪いリバースプロキシの挙動（信頼されていない転送ヘッダーを追記／保持する）: ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## HSTSとoriginに関する注意 +## HSTSとオリジンに関する注意 -- OpenClaw gatewayはまずlocal/loopback前提です。TLSをreverse proxyで終端する場合、HSTSはそのproxy側HTTPSドメインで設定してください。 -- gateway自体がHTTPSを終端する場合は、`gateway.http.securityHeaders.strictTransportSecurity` を設定して、OpenClawレスポンスからHSTS headerを出せます。 -- 詳しいデプロイ指針は [Trusted Proxy Auth](/gateway/trusted-proxy-auth#tls-termination-and-hsts) にあります。 -- non-loopbackのControl UIデプロイでは、デフォルトで `gateway.controlUi.allowedOrigins` が必須です。 -- `gateway.controlUi.allowedOrigins: ["*"]` は、強化されたデフォルトではなく、明示的なbrowser-origin全許可ポリシーです。厳密に管理されたローカルテスト以外では避けてください。 -- loopback上のbrowser-origin auth失敗も、一般のloopback免除が有効でもrate-limitedされます。ただしlockout keyは共有localhostバケットではなく、正規化された `Origin` 値ごとに分かれます。 -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` はHost-header origin fallback modeを有効にします。これはdangerousなoperator選択ポリシーとして扱ってください。 -- DNS rebindingとproxy host header挙動は、デプロイ強化の問題として扱ってください。`trustedProxies` は厳密に保ち、gatewayをパブリックインターネットへ直接公開しないでください。 +- OpenClaw Gatewayは、まずlocal／loopbackを前提としています。TLSをリバースプロキシで終端する場合は、そのプロキシ側のHTTPSドメインでHSTSを設定してください。 +- Gateway自身がHTTPSを終端する場合は、`gateway.http.securityHeaders.strictTransportSecurity` を設定して、OpenClawのレスポンスからHSTSヘッダーを送出できます。 +- 詳細なデプロイ指針は [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts) にあります。 +- loopback以外でControl UIをデプロイする場合、`gateway.controlUi.allowedOrigins` はデフォルトで必須です。 +- `gateway.controlUi.allowedOrigins: ["*"]` は、明示的な「すべて許可」のブラウザオリジンポリシーであり、強化されたデフォルトではありません。厳密に管理されたローカルテスト以外では避けてください。 +- loopback上で一般的なloopback免除が有効な場合でも、ブラウザオリジン認証の失敗には引き続きレート制限がかかります。ただし、ロックアウトキーは共有のlocalhostバケット1つではなく、正規化された `Origin` 値ごとにスコープされます。 +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` は、Hostヘッダー由来のオリジンフォールバックモードを有効にします。運用者が選択した危険なポリシーとして扱ってください。 +- DNS rebindingやプロキシのHostヘッダー挙動は、デプロイ強化上の懸念として扱ってください。`trustedProxies` は厳密に保ち、Gatewayを公開インターネットへ直接露出しないでください。 -## ローカルsession logsはディスク上にある +## ローカルセッションログはディスク上に保存される -OpenClawはsession transcriptsを `~/.openclaw/agents//sessions/*.jsonl` にディスク保存します。 -これはsession continuityや（任意で）session memory indexingに必要ですが、同時に -**ファイルシステムアクセスできる任意のprocess/userがそれらのlogを読める**ことも意味します。信頼境界はディスクアクセスだと考え、`~/.openclaw` の権限を厳しくしてください（下の監査セクション参照）。agent間でより強い分離が必要なら、別々のOSユーザーまたは別々のホストで動かしてください。 +OpenClawは、セッショントランスクリプトを `~/.openclaw/agents//sessions/*.jsonl` に保存します。 +これはセッション継続性と、必要に応じてセッションメモリーのインデックス化に必要ですが、同時に**ファイルシステムへアクセスできる任意のプロセス／ユーザーがそのログを読める**ことも意味します。信頼境界はディスクアクセスだと考え、`~/.openclaw` の権限を厳しくしてください（下の監査セクションを参照）。エージェント間でより強い分離が必要なら、別々のOSユーザーまたは別々のホストで実行してください。 -## Node実行 (`system.run`) +## Node実行（system.run） -macOS nodeがペアリングされていると、Gatewayはそのnode上で `system.run` を呼び出せます。これはMac上での**リモートコード実行**です。 +macOS nodeがペアリングされている場合、Gatewayはそのnode上で `system.run` を呼び出せます。これはMac上での**リモートコード実行**です。 -- node pairing（承認 + token）が必要です。 -- Gateway node pairingはコマンドごとの承認面ではありません。これはnode identity/trustとtoken発行を確立するものです。 -- Gatewayは `gateway.nodes.allowCommands` / `denyCommands` を使って大まかなグローバルnode command policyを適用します。 -- Mac側では **Settings → Exec approvals**（security + ask + allowlist）で制御されます。 -- ノードごとの `system.run` policyは、node自身のexec approvals file（`exec.approvals.node.*`）で、gatewayのグローバルcommand-ID policyより厳しいことも緩いこともあります。 -- `security="full"` と `ask="off"` で動くnodeは、デフォルトのtrusted-operator modelに従っています。あなたのデプロイがより厳しい承認またはallowlist姿勢を明示的に必要としない限り、これは想定された動作として扱ってください。 -- 承認モードは、正確なリクエストコンテキストと、可能なら1つの具体的なローカルscript/fileオペランドに結び付きます。OpenClawがinterpreter/runtime commandに対して正確に1つの直接ローカルファイルを特定できない場合、承認付き実行は拒否されます。完全な意味的カバレッジを約束することはしません。 -- `host=node` では、承認付き実行は正規化済みの `systemRunPlan` も保存します。後続の承認済みforwardではその保存済みplanを再利用し、gateway validationは承認リクエスト作成後のcommand/cwd/session context変更を拒否します。 -- リモート実行が不要なら、securityを **deny** にして、そのMacのnode pairingを削除してください。 +- nodeのペアリング（承認 + token）が必要です。 +- Gatewayのnodeペアリングは、コマンド単位の承認サーフェスではありません。これはnodeのアイデンティティ／信頼とtoken発行を確立するものです。 +- Gatewayは、`gateway.nodes.allowCommands` / `denyCommands` を通じて、大まかなグローバルnodeコマンドポリシーを適用します。 +- Mac側では **Settings → Exec approvals** で制御します（security + ask + allowlist）。 +- node単位の `system.run` ポリシーは、そのnode自身のexec approvalsファイル（`exec.approvals.node.*`）であり、GatewayのグローバルなコマンドIDポリシーより厳しい場合も緩い場合もあります。 +- `security="full"` かつ `ask="off"` で動作するnodeは、デフォルトの信頼された運用者モデルに従っています。デプロイでより厳密な承認または許可リスト方針が明示的に必要でない限り、これは想定内の挙動として扱ってください。 +- 承認モードは、正確なリクエストコンテキストと、可能な場合は1つの具体的なローカルスクリプト／ファイルオペランドに結び付きます。インタープリター／ランタイムコマンドに対して、OpenClawが正確に1つの直接ローカルファイルを特定できない場合、完全な意味的カバレッジを約束するのではなく、承認ベース実行は拒否されます。 +- `host=node` の場合、承認ベース実行では、整形済みの正規 `systemRunPlan` も保存されます。その後の承認済み転送ではその保存済みプランが再利用され、承認リクエスト作成後に呼び出し元がコマンド／cwd／セッションコンテキストを編集しようとすると、Gateway側の検証で拒否されます。 +- リモート実行が不要なら、securityを **deny** に設定し、そのMacのnodeペアリングを削除してください。 -これはトリアージ上重要です。 +この区別はトリアージで重要です。 -- 再接続したpaired nodeが異なるcommand listを広告していても、それだけで脆弱性ではありません。実際の実行境界は依然としてGateway global policyとnode local exec approvalsが強制します。 -- Node pairing metadataを第2の隠れたコマンド単位承認層として扱う報告は、通常はポリシー/UXの混乱であり、セキュリティ境界バイパスではありません。 +- 再接続したペアリング済みnodeが別のコマンド一覧を広告していても、それだけでは脆弱性ではありません。Gatewayのグローバルポリシーとnodeのローカルexec approvalsが、実際の実行境界を引き続き強制している限りは問題ではありません。 +- nodeペアリングメタデータを、隠れた第2のコマンド単位承認レイヤーとして扱う報告は、通常はポリシー／UX上の混乱であり、セキュリティ境界の回避ではありません。 ## 動的Skills（watcher / remote nodes） -OpenClawはsession途中でskills listを更新できます。 +OpenClawはセッションの途中でSkills一覧を更新できます。 -- **Skills watcher**: `SKILL.md` の変更は、次のagent turnでskills snapshotを更新できます。 -- **Remote nodes**: macOS nodeを接続すると、macOS専用Skillsが有効候補になることがあります（bin probingに基づく）。 +- **Skills watcher**: `SKILL.md` の変更により、次のエージェントターンでSkillsスナップショットが更新されることがあります。 +- **Remote nodes**: macOS nodeを接続すると、macOS専用Skillsが対象になることがあります（binのプローブに基づく）。 -skill folderは**信頼されたコード**として扱い、誰が変更できるかを制限してください。 +Skillフォルダーは**信頼されたコード**として扱い、誰が変更できるかを制限してください。 ## 脅威モデル -あなたのAI assistantは次ができます。 +あなたのAIアシスタントは次のことができます。 -- 任意のshell commandを実行する +- 任意のシェルコマンドを実行する - ファイルを読み書きする -- network serviceへアクセスする -- 誰にでもメッセージを送る（WhatsAppアクセスを与えていれば） +- ネットワークサービスへアクセスする +- 誰にでもメッセージを送る（WhatsAppアクセスを与えた場合） -あなたにメッセージする人は次を試せます。 +あなたにメッセージを送れる人は次のことができます。 -- AIを騙して危険なことをさせる -- データへのアクセスをソーシャルエンジニアリングする -- インフラ詳細を探る +- AIをだまして悪いことをさせようとする +- あなたのデータへのアクセスをソーシャルエンジニアリングで引き出そうとする +- インフラの詳細を探ろうとする -## 中核概念: 知能の前にアクセス制御 +## 中核概念: 知能より先にアクセス制御 -ここで起きる失敗の大半は高度な攻撃ではなく、「誰かがbotにメッセージし、botが言われたとおりにした」です。 +ここで起きる失敗の多くは、高度な攻撃ではありません。単に「誰かがボットにメッセージし、ボットがその依頼どおりに動いた」というものです。 -OpenClawの立場: +OpenClawの立場は次のとおりです。 -- **Identity first:** まず誰がbotに話しかけられるかを決める（DM pairing / allowlists / 明示的な「open」）。 -- **Scope next:** 次に、botがどこで行動できるかを決める（group allowlists + mention gating、tools、sandboxing、device permissions）。 -- **Model last:** モデルは操作されうると仮定し、操作されても影響範囲が限られるように設計する。 +- **まずアイデンティティ:** 誰がボットに話しかけられるかを決める（DMペアリング／許可リスト／明示的な `「open」`）。 +- **次にスコープ:** ボットがどこで動作してよいかを決める（グループ許可リスト + メンションゲーティング、ツール、sandbox化、デバイス権限）。 +- **最後にモデル:** モデルは操作されうるものだと想定し、操作されても影響範囲が限定されるように設計する。 ## コマンド認可モデル -Slash commandsとdirectiveは、**認可された送信者**に対してのみ有効です。認可は -channel allowlists/pairingと `commands.useAccessGroups` から導かれます（[Configuration](/gateway/configuration) と [Slash commands](/tools/slash-commands) を参照）。channel allowlistが空、または `"*"` を含む場合、commandsはそのchannelで実質的にopenです。 +スラッシュコマンドとディレクティブは、**認可された送信者**に対してのみ処理されます。認可は、チャネルの許可リスト／ペアリングと `commands.useAccessGroups` から導出されます（[Configuration](/ja-JP/gateway/configuration) および [Slash commands](/ja-JP/tools/slash-commands) を参照）。チャネル許可リストが空、または `"*"` を含む場合、そのチャネルのコマンドは事実上オープンです。 -`/exec` は認可済みoperator向けのsession専用便利機能です。これはconfigを書き換えたり、他sessionを変更したりはしません。 +`/exec` は、認可された運用者向けのセッション限定の利便機能です。これはconfigへ書き込んだり、他のセッションを変更したりはしません。 -## Control plane toolsのリスク +## コントロールプレーンツールのリスク -永続的なcontrol-plane変更を行える組み込みtoolが2つあります。 +2つの組み込みツールは、永続的なコントロールプレーン変更を行えます。 -- `gateway` は `config.schema.lookup` / `config.get` でconfigを調べられ、`config.apply`、`config.patch`、`update.run` で永続変更もできます。 -- `cron` は、元のchat/task終了後も動き続けるscheduled jobを作成できます。 +- `gateway` は `config.schema.lookup` / `config.get` でconfigを調べられ、`config.apply`、`config.patch`、`update.run` で永続変更を行えます。 +- `cron` は、元のチャット／タスク終了後も動き続けるスケジュールジョブを作成できます。 -owner専用の `gateway` runtime toolは、今も `tools.exec.ask` や `tools.exec.security` の書き換えを拒否します。legacyな `tools.bash.*` aliasは、書き込み前に同じ保護されたexec pathへ正規化されます。 +オーナー専用の `gateway` ランタイムツールは、現在も `tools.exec.ask` または `tools.exec.security` の書き換えを拒否します。レガシーな `tools.bash.*` エイリアスは、書き込み前に同じ保護されたexecパスへ正規化されます。 -信頼できないコンテンツを扱うagent/surfaceでは、デフォルトでこれらをdenyしてください。 +信頼していないコンテンツを扱うエージェント／サーフェスでは、デフォルトでこれらを拒否してください。 ```json5 { @@ -540,47 +542,49 @@ owner専用の `gateway` runtime toolは、今も `tools.exec.ask` や `tools.ex } ``` -`commands.restart=false` はrestart actionだけをブロックします。`gateway` のconfig/update actionsは無効化しません。 +`commands.restart=false` は再起動アクションをブロックするだけです。`gateway` のconfig／updateアクションは無効化しません。 -## Plugins/extensions +## プラグイン／拡張機能 -PluginsはGateway内で**インプロセス**実行されます。信頼されたコードとして扱ってください。 +プラグインはGateway内で**インプロセス**で実行されます。信頼されたコードとして扱ってください。 -- 信頼するソースからのみpluginをインストールする -- 明示的な `plugins.allow` allowlistを優先する -- 有効化前にplugin configを確認する -- plugin変更後はGatewayを再起動する -- pluginをインストール/更新する場合（`openclaw plugins install `、`openclaw plugins update `）、未信頼コードを実行するのと同じものとして扱う: - - インストール先は、アクティブなplugin install root配下のpluginごとのディレクトリ - - OpenClawはinstall/update前に組み込みの危険コードスキャンを実行する。`critical` 検出はデフォルトでブロックされる - - OpenClawは `npm pack` を使い、そのディレクトリで `npm install --omit=dev` を実行する（npm lifecycle scriptsはinstall中にコードを実行できる） - - 固定された正確なversion（`@scope/pkg@1.2.3`）を優先し、有効化前にディスク上へ展開されたコードを確認する - - `--dangerously-force-unsafe-install` は、plugin install/updateフローでの組み込みスキャン誤検知に対する緊急回避専用です。plugin `before_install` hookのpolicy blockやscan failureは回避しません - - Gateway-backedなskill dependency installも同じ dangerous/suspicious 分類に従います。組み込みの `critical` 検出は、呼び出し元が明示的に `dangerouslyForceUnsafeInstall` を指定しない限りブロックされ、suspicious検出は警告のみです。`openclaw skills install` は別のClawHub skill download/installフローのままです。 +- 信頼できる提供元からのプラグインだけをインストールしてください。 +- 明示的な `plugins.allow` 許可リストを優先してください。 +- 有効化する前にプラグイン設定を確認してください。 +- プラグイン変更後はGatewayを再起動してください。 +- プラグインをインストールまたは更新する場合（`openclaw plugins install `、`openclaw plugins update `）、これは信頼していないコードを実行するのと同じだと考えてください。 + - インストール先は、現在有効なプラグインインストールルート配下にある、プラグインごとのディレクトリです。 + - OpenClawは、インストール／更新前に組み込みの危険コードスキャンを実行します。`critical` 検出はデフォルトでブロックされます。 + - OpenClawは `npm pack` を使用し、その後そのディレクトリ内で `npm install --omit=dev` を実行します（npmのライフサイクルスクリプトは、インストール中にコードを実行できます）。 + - 固定された厳密バージョン（`@scope/pkg@1.2.3`）を優先し、有効化前にディスク上へ展開されたコードを確認してください。 + - `--dangerously-force-unsafe-install` は、プラグインのインストール／更新フローにおける組み込みスキャンの誤検知に対する緊急手段専用です。これはプラグインの `before_install` フックによるポリシーブロックを回避せず、スキャン失敗も回避しません。 + - Gateway連動のSkill依存関係インストールも、同じ危険／疑わしいの区別に従います。組み込みの `critical` 検出は、呼び出し元が明示的に `dangerouslyForceUnsafeInstall` を設定しない限りブロックされ、疑わしい検出は引き続き警告のみです。`openclaw skills install` は、引き続き別個のClawHub Skillダウンロード／インストールフローです。 -詳細: [Plugins](/tools/plugin) +詳細: [Plugins](/ja-JP/tools/plugin) + + ## DMアクセスモデル（pairing / allowlist / open / disabled） -現在のDM対応channelはすべて、メッセージ処理**前**に受信DMを制御するDM policy（`dmPolicy` または `*.dm.policy`）を持ちます。 +現在DMに対応しているすべてのチャネルは、メッセージが処理される**前に**受信DMを制御するDMポリシー（`dmPolicy` または `*.dm.policy`）をサポートしています。 -- `pairing`（デフォルト）: 未知の送信者には短いpairing codeが送られ、承認されるまでbotはそのメッセージを無視します。codeは1時間で期限切れになります。繰り返しDMしても、新しいリクエストが作られるまで再送されません。保留リクエストはデフォルトで**channelごとに3件**までです。 -- `allowlist`: 未知の送信者はブロックされます（pairing handshakeなし）。 -- `open`: 誰でもDM可（公開）。**channel allowlistに `"*"` が必要**です（明示的オプトイン）。 +- `pairing`（デフォルト）: 未知の送信者には短いペアリングコードが送られ、承認されるまでボットはそのメッセージを無視します。コードの有効期限は1時間です。新しいリクエストが作成されるまでは、繰り返しDMしてもコードは再送されません。保留中リクエストは、デフォルトで**チャネルごとに3件**までに制限されます。 +- `allowlist`: 未知の送信者はブロックされます（ペアリングのハンドシェイクなし）。 +- `open`: 誰でもDM可能にします（公開）。チャネル許可リストに `"*"` を含めることが**必須**です（明示的なオプトイン）。 - `disabled`: 受信DMを完全に無視します。 -CLIで承認: +CLIで承認するには: ```bash openclaw pairing list openclaw pairing approve ``` -詳細とディスク上ファイル: [Pairing](/ja-JP/channels/pairing) +詳細とディスク上のファイル: [Pairing](/ja-JP/channels/pairing) -## DM session分離（multi-user mode） +## DMセッション分離（マルチユーザーモード） -デフォルトでは、OpenClawは**すべてのDMをmain sessionへルーティング**するため、assistantはデバイスやchannelをまたいで連続性を持てます。**複数人**がbotにDMできるなら（open DMsや複数人allowlist）、DM sessionsを分離することを検討してください。 +デフォルトでは、OpenClawは**すべてのDMをメインセッションへルーティング**するため、あなたのアシスタントはデバイスやチャネルをまたいで継続性を保てます。**複数人**がボットへDMできる場合（オープンDMや複数人の許可リスト）、DMセッションを分離することを検討してください。 ```json5 { @@ -588,173 +592,171 @@ openclaw pairing approve } ``` -これにより、group chatsを分離したまま、ユーザー間コンテキスト漏れを防げます。 +これにより、グループチャットの分離を維持しつつ、ユーザー間のコンテキスト漏えいを防げます。 -これはメッセージングコンテキスト境界であって、host-admin境界ではありません。ユーザー同士が敵対的で、同じGateway host/configを共有するなら、信頼境界ごとに別Gatewayを実行してください。 +これはメッセージングコンテキストの境界であり、ホスト管理者境界ではありません。ユーザー同士が敵対的で、同じGatewayホスト／configを共有している場合は、信頼境界ごとに別々のGatewayを実行してください。 -### Secure DM mode（推奨） +### セキュアDMモード（推奨） -上のスニペットを**secure DM mode**として扱ってください。 +上記のスニペットは、**セキュアDMモード**として扱ってください。 -- デフォルト: `session.dmScope: "main"`（すべてのDMが1つのsessionを共有し連続性を持つ） -- ローカルCLI onboardingデフォルト: 未設定なら `session.dmScope: "per-channel-peer"` を書き込む（既存の明示設定は保持） -- Secure DM mode: `session.dmScope: "per-channel-peer"`（channel+senderごとに独立したDM context） -- Cross-channel peer isolation: `session.dmScope: "per-peer"`（同じtypeの全channelsをまたいでsenderごとに1つのsession） +- デフォルト: `session.dmScope: "main"`（継続性のため、すべてのDMが1つのセッションを共有） +- ローカルCLIオンボーディングのデフォルト: 未設定時は `session.dmScope: "per-channel-peer"` を書き込む（既存の明示値は保持） +- セキュアDMモード: `session.dmScope: "per-channel-peer"`（各チャネル + 送信者の組み合わせごとに独立したDMコンテキスト） +- チャネル横断の送信者分離: `session.dmScope: "per-peer"`（同じタイプの全チャネルを通して、送信者ごとに1つのセッション） -同じchannel上で複数accountを動かすなら、代わりに `per-account-channel-peer` を使ってください。同じ人物が複数channelから連絡してくるなら、`session.identityLinks` を使ってそれらのDM sessionsを1つのcanonical identityに統合してください。[Session Management](/concepts/session) と [Configuration](/gateway/configuration) を参照してください。 +同じチャネル上で複数アカウントを動かす場合は、代わりに `per-account-channel-peer` を使ってください。同じ人物が複数チャネルから連絡してくる場合は、`session.identityLinks` を使ってそれらのDMセッションを1つの正規アイデンティティへ統合します。詳細は [Session Management](/ja-JP/concepts/session) と [Configuration](/ja-JP/gateway/configuration) を参照してください。 -## Allowlists（DM + groups）- 用語 +## 許可リスト（DM + グループ）- 用語 -OpenClawには、「誰が私を起動できるか」を決める別々のレイヤーが2つあります。 +OpenClawには、「誰が自分を起動できるか」に関する2つの別々のレイヤーがあります。 -- **DM allowlist**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; legacy: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`）: direct messagesでbotに話しかけられる相手。 - - `dmPolicy="pairing"` のとき、承認は `~/.openclaw/credentials/` 配下のaccount-scoped pairing allowlist storeへ書かれます（デフォルトaccountは `-allowFrom.json`、非デフォルトaccountは `--allowFrom.json`）。それがconfig allowlistsとマージされます。 -- **Group allowlist**（channel固有）: botがどのgroups/channels/guildsからのメッセージを受け付けるか。 +- **DM許可リスト**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; レガシー: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`）: ダイレクトメッセージでボットへ話しかけることを許可される相手。 + - `dmPolicy="pairing"` の場合、承認は `~/.openclaw/credentials/` 配下のアカウント単位ペアリング許可リストストアへ書き込まれます（デフォルトアカウントは `-allowFrom.json`、デフォルト以外のアカウントは `--allowFrom.json`）。その後、config許可リストとマージされます。 +- **グループ許可リスト**（チャネル固有）: ボットがどのグループ／チャネル／guildからのメッセージをそもそも受け付けるか。 - 一般的なパターン: - - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: `requireMention` のようなgroupごとのデフォルト。設定するとgroup allowlistとしても機能する（全許可を維持するなら `"*"` を含める） - - `groupPolicy="allowlist"` + `groupAllowFrom`: group session内で誰がbotを起動できるかを制限する（WhatsApp/Telegram/Signal/iMessage/Microsoft Teams） - - `channels.discord.guilds` / `channels.slack.channels`: surfaceごとのallowlists + mention defaults - - Group checksはこの順で実行されます: 先に `groupPolicy`/group allowlists、その後mention/reply activation。 - - bot messageへの返信（暗黙mention）は、`groupAllowFrom` のようなsender allowlistsをバイパスしません。 - - **セキュリティ注意:** `dmPolicy="open"` と `groupPolicy="open"` は最後の手段として扱ってください。極力使わず、room全員を完全に信頼しない限りpairing + allowlistsを優先してください。 + - `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`: `requireMention` のようなグループ単位デフォルト。これが設定されると、グループ許可リストとしても機能します（すべて許可を維持するには `"*"` を含めます）。 + - `groupPolicy="allowlist"` + `groupAllowFrom`: グループセッション内で誰がボットを起動できるかを制限します（WhatsApp／Telegram／Signal／iMessage／Microsoft Teams）。 + - `channels.discord.guilds` / `channels.slack.channels`: サーフェス単位の許可リスト + メンションのデフォルト。 + - グループチェックは次の順で実行されます。まず `groupPolicy`／グループ許可リスト、その次にメンション／返信による起動です。 + - ボットのメッセージへ返信すること（暗黙のメンション）は、`groupAllowFrom` のような送信者許可リストをバイパスしません。 + - **セキュリティ上の注意:** `dmPolicy="open"` と `groupPolicy="open"` は最終手段として扱ってください。これらはほとんど使うべきではありません。部屋の全員を完全に信頼している場合を除き、pairing + 許可リストを優先してください。 -詳細: [Configuration](/gateway/configuration) と [Groups](/ja-JP/channels/groups) +詳細: [Configuration](/ja-JP/gateway/configuration) および [Groups](/ja-JP/channels/groups) -## Prompt injection（それが何か、なぜ重要か） +## プロンプトインジェクション（何か、なぜ重要か） -Prompt injectionとは、攻撃者がモデルを操作して危険なことをさせるメッセージを作ることです（「指示を無視しろ」「ファイルシステムを吐き出せ」「このリンクを開いてコマンドを実行しろ」など）。 +プロンプトインジェクションとは、攻撃者が、モデルを操作して危険なことをさせるようなメッセージを作ることです（「指示を無視しろ」「ファイルシステムを吐き出せ」「このリンクを開いてコマンドを実行しろ」など）。 -強いsystem promptがあっても、**prompt injectionは未解決**です。System prompt guardrailsはあくまでソフトな指針であり、ハードな強制はtool policy、exec approvals、sandboxing、channel allowlistsから来ます（そしてoperatorは設計上それらを無効化できます）。実際に役立つのは次です。 +強力なシステムプロンプトがあっても、**プロンプトインジェクションは未解決です**。システムプロンプトのガードレールは、あくまで緩い指針にすぎません。強制力のある制御は、ツールポリシー、exec承認、sandbox化、チャネル許可リストから来ます（しかも、これらは設計上、運用者が無効化できます）。実際に役立つ対策は次のとおりです。 -- 受信DMを厳しく絞る（pairing/allowlists）。 -- groupsではmention gatingを優先し、公開roomで「常時反応する」botを避ける。 -- links、attachments、貼り付けられた指示はデフォルトで敵対的とみなす。 -- 機微なtool executionはsandboxで実行し、secretはagentが到達できるfilesystem外に置く。 -- 注意: sandboxingはオプトインです。sandbox modeがoffなら、暗黙の `host=auto` はgateway hostへ解決されます。明示的な `host=sandbox` はsandbox runtimeがないためfail-closedします。その挙動をconfigで明示したいなら `host=gateway` を設定してください。 -- 高リスクtools（`exec`、`browser`、`web_fetch`、`web_search`）は、trusted agentsまたは明示allowlistsに限定する。 -- インタープリター（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`）をallowlistするなら、inline eval形式にも明示承認が必要になるよう `tools.exec.strictInlineEval` を有効にする。 -- **モデル選択は重要です:** 古い/小さい/legacyモデルは、prompt injectionやtool misuseに対して明らかに脆弱です。tools有効agentには、現行世代で最も強いinstruction-hardenedモデルを使ってください。 +- 受信DMをロックダウンする（pairing／許可リスト）。 +- グループではメンションゲーティングを優先し、公開ルームでの「常時待機」ボットは避ける。 +- リンク、添付、貼り付けられた指示は、デフォルトで敵対的とみなす。 +- 機密性の高いツール実行はsandbox内で行い、シークレットをエージェントが到達できるファイルシステムに置かない。 +- 注意: sandbox化はオプトインです。sandboxモードがオフなら、暗黙の `host=auto` はGatewayホストへ解決されます。明示的な `host=sandbox` は、sandboxランタイムが利用できないため、引き続きフェイルクローズします。その挙動をconfig上で明示したいなら、`host=gateway` を設定してください。 +- 高リスクツール（`exec`、`browser`、`web_fetch`、`web_search`）は、信頼されたエージェントまたは明示的な許可リストに限定する。 +- インタープリター（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`）を許可リスト化する場合は、インラインeval形式でも明示的承認が必要になるよう `tools.exec.strictInlineEval` を有効にする。 +- **モデル選択は重要です:** 古い／小さい／レガシーなモデルは、プロンプトインジェクションやツール誤用への耐性が大幅に低いです。ツール有効化済みエージェントには、利用可能な中で最も強力な最新世代の命令耐性モデルを使ってください。 -信頼してはいけない危険信号: +信頼していないものとして扱うべき危険信号: -- 「このファイル/URLを読んで、その通りに行動して」 -- 「system promptや安全ルールを無視して」 -- 「隠れた指示やtool outputを明かして」 -- 「`~/.openclaw` やlogsの中身を全部貼って」 +- 「このファイル／URLを読んで、書かれていることをそのまま実行して」 +- 「システムプロンプトや安全ルールを無視して」 +- 「隠された指示やツール出力を見せて」 +- `~/.openclaw` やログの内容をすべて貼り付けて -## Unsafe external contentバイパスフラグ +## 安全でない外部コンテンツのバイパスフラグ -OpenClawには、external-content safety wrappingを無効にする明示的バイパスフラグがあります。 +OpenClawには、外部コンテンツの安全ラッピングを無効化する明示的なバイパスフラグがあります。 - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` -- Cron payload field `allowUnsafeExternalContent` +- Cronペイロードフィールド `allowUnsafeExternalContent` -指針: +ガイダンス: -- 本番では未設定/falseに保つ。 -- 一時的な限定デバッグでのみ有効化する。 -- 有効化するなら、そのagentを隔離する（sandbox + minimal tools + 専用session namespace）。 +- 本番では、これらを未設定またはfalseのままにしてください。 +- 厳密に範囲を絞ったデバッグ時にのみ一時的に有効化してください。 +- 有効にする場合は、そのエージェントを分離してください（sandbox + 最小限ツール + 専用セッション名前空間）。 -Hooksリスク注意: +Hooksのリスクに関する注意: -- 配送元が自分で管理するシステムでも、hook payloadsは未信頼コンテンツです（mail/docs/web contentはprompt injectionを含み得る）。 -- 弱いモデルtierはこのリスクを高めます。hook-driven automationでは、強い最新model tierを使い、tool policyは厳しく保ってください（`tools.profile: "messaging"` 以上に厳しく）。可能ならsandboxingも使ってください。 +- Hookペイロードは、たとえ配信が自分で管理するシステムから来ていても、信頼していないコンテンツです（メール／ドキュメント／Webコンテンツにはプロンプトインジェクションが含まれうるため）。 +- 弱いモデルティアはこのリスクを高めます。Hook駆動の自動化では、強力で現代的なモデルティアを優先し、ツールポリシーは厳格に保ってください（`tools.profile: "messaging"` またはそれより厳格）。可能であればsandbox化も行ってください。 -### Prompt injectionは公開DMがなくても起こる +### プロンプトインジェクションは公開DMでなくても起こる -botにDMできるのが**自分だけ**でも、botが読む**未信頼コンテンツ**（web search/fetch結果、browser pages、emails、docs、attachments、貼り付けられたlogs/code）を通じてprompt injectionは起こりえます。つまり、脅威面は送信者だけではなく、**コンテンツ自体**です。 +**自分だけ**がボットへメッセージできる場合でも、ボットが読む**信頼していないコンテンツ**（Web検索／取得結果、ブラウザページ、メール、ドキュメント、添付、貼り付けられたログ／コード）を通じて、プロンプトインジェクションは起こりえます。言い換えると、脅威サーフェスは送信者だけではなく、**コンテンツそのもの**も敵対的な指示を運びうるということです。 -toolsが有効だと、典型的なリスクはコンテキスト流出やtool call誘発です。影響範囲を減らすには: +ツールが有効な場合の典型的なリスクは、コンテキストの流出やツール呼び出しの誘発です。影響範囲は次の方法で小さくできます。 -- read-onlyまたはtool無効の**reader agent**を使って未信頼コンテンツを要約し、その要約をmain agentへ渡す。 -- `web_search` / `web_fetch` / `browser` は、必要な場合を除き、tools有効agentではoffにする。 -- OpenResponsesのURL入力（`input_file` / `input_image`）では、`gateway.http.endpoints.responses.files.urlAllowlist` と `gateway.http.endpoints.responses.images.urlAllowlist` を厳しくし、`maxUrlParts` は低く保つ。空allowlistsは未設定扱いです。URL fetchを完全に無効化したいなら `files.allowUrl: false` / `images.allowUrl: false` を使ってください。 -- OpenResponses file inputsでは、デコードされた `input_file` テキストも依然として**未信頼な外部コンテンツ**として注入されます。Gatewayがローカルでデコードしたからといって信頼できると思わないでください。長い `SECURITY NOTICE:` バナーは省略されても、注入ブロックには明示的な `<<>>` 境界マーカーと `Source: External` メタデータが付きます。 -- 同じマーカーベースのラッピングは、media-understandingが添付文書からテキストを抽出してmedia promptへ追加するときにも適用されます。 -- 未信頼入力に触れるagentにはsandboxingと厳格なtool allowlistsを有効にする。 -- secretはpromptへ入れず、gateway host上のenv/config経由で渡す。 +- 信頼していないコンテンツの要約には、読み取り専用またはツール無効の**reader agent** を使い、その要約をメインエージェントへ渡す。 +- 必要になるまで、ツール有効化済みエージェントでは `web_search` / `web_fetch` / `browser` をオフにしておく。 +- OpenResponsesのURL入力（`input_file` / `input_image`）では、`gateway.http.endpoints.responses.files.urlAllowlist` と `gateway.http.endpoints.responses.images.urlAllowlist` を厳しく設定し、`maxUrlParts` は低く保つ。 + 空の許可リストは未設定として扱われます。URL取得を完全に無効化したいなら、`files.allowUrl: false` / `images.allowUrl: false` を使ってください。 +- OpenResponsesのファイル入力では、デコードされた `input_file` のテキストも引き続き**信頼していない外部コンテンツ**として注入されます。Gatewayがローカルでデコードしたからといって、そのファイルテキストを信頼してはいけません。注入されるブロックには、長い `SECURITY NOTICE:` バナーはありませんが、明示的な `<<>>` 境界マーカーと `Source: External` メタデータが引き続き付きます。 +- 添付ドキュメントからテキストを抽出し、それをメディアプロンプトへ追加する前にも、同じマーカーベースのラッピングが適用されます。 +- 信頼していない入力に触れるエージェントでは、sandbox化と厳格なツール許可リストを有効にする。 +- シークレットをプロンプト内に置かず、Gatewayホスト上のenv/config経由で渡す。 -### モデル強度（セキュリティ注意） +### モデルの強さ（セキュリティ上の注意） -Prompt injection耐性は、model tierごとに**均一ではありません**。小さい/安価なモデルほど、特に敵対的prompt下でtool misuseやinstruction hijackingに弱い傾向があります。 +プロンプトインジェクション耐性は、モデルティア間で**均一ではありません**。小型で安価なモデルほど、特に敵対的プロンプト下では、ツール誤用や命令ハイジャックに弱い傾向があります。 -tools有効agentや未信頼コンテンツを読むagentでは、古い/小さいモデルによるprompt injectionリスクは高すぎることが多いです。その種のワークロードを弱いmodel tiersで動かさないでください。 +ツール有効化済みエージェントや、信頼していないコンテンツを読むエージェントでは、古い／小さいモデルによるプロンプトインジェクションリスクは、しばしば高すぎます。そのようなワークロードを弱いモデルティアで実行しないでください。 -推奨: +推奨事項: -- tools実行やfiles/networksに触れられるbotには、**最新世代の最上位モデル**を使う。 -- **古い/弱い/小さいtier** は、tools有効agentや未信頼受信箱には使わない。prompt injectionリスクが高すぎる。 -- どうしても小さいモデルを使うなら、**影響範囲を縮小**する（read-only tools、強いsandboxing、最小のfilesystem access、厳格allowlists）。 -- 小さいモデルを動かすときは、**全sessionsでsandboxingを有効化**し、入力が厳密管理されていない限り **web_search/web_fetch/browserを無効化**する。 -- toolsなしでtrusted inputだけを扱うchat-only personal assistantなら、小さいモデルでもたいてい問題ありません。 +- ツールを実行できる、またはファイル／ネットワークへ触れられるボットには、**最新世代かつ最上位ティアのモデル**を使ってください。 +- ツール有効化済みエージェントや、信頼していない受信箱には、**古い／弱い／小さいティアを使わないでください**。プロンプトインジェクションリスクが高すぎます。 +- やむを得ず小さいモデルを使う場合は、**影響範囲を縮小**してください（読み取り専用ツール、強力なsandbox化、最小限のファイルシステムアクセス、厳格な許可リスト）。 +- 小型モデルを実行する場合は、**すべてのセッションでsandbox化を有効にし**、入力が厳密に制御されていない限り **web_search/web_fetch/browser を無効化**してください。 +- 信頼された入力のみでツールなしのチャット専用パーソナルアシスタントであれば、小型モデルでも通常は問題ありません。 -## groupsでのReasoningとverbose output +## グループでのReasoningと詳細出力 -`/reasoning` と `/verbose` は、公開channel向けではない内部reasoningやtool outputを露出する可能性があります。group設定では、これらは**デバッグ専用**として扱い、明示的に必要な場合以外はoffにしてください。 +`/reasoning` と `/verbose` は、公開チャネル向けではない内部推論やツール出力を露出することがあります。グループ設定では、これらは**デバッグ専用**として扱い、明確に必要な場合を除いて無効のままにしてください。 -指針: +ガイダンス: -- 公開roomでは `/reasoning` と `/verbose` をoffに保つ。 -- 有効化するなら、trusted DMsまたは厳密に管理されたroomだけにする。 -- 忘れないでください: verbose outputには、tool args、URLs、モデルが見たデータが含まれうる。 +- 公開ルームでは `/reasoning` と `/verbose` を無効のままにしてください。 +- 有効にする場合は、信頼されたDMまたは厳密に管理されたルームでのみ行ってください。 +- 忘れないでください: 詳細出力には、ツール引数、URL、モデルが見たデータが含まれる可能性があります。 ## 設定の強化（例） ### 0) ファイル権限 -gateway host上のconfig + stateは非公開に保ってください。 +Gatewayホスト上では、config + stateを非公開に保ってください。 -- `~/.openclaw/openclaw.json`: `600`（ユーザーの読み書きのみ） +- `~/.openclaw/openclaw.json`: `600`（ユーザーのみ読み書き） - `~/.openclaw`: `700`（ユーザーのみ） -`openclaw doctor` は、これらの権限を警告し、厳しくする提案をできます。 +`openclaw doctor` は、これらの権限について警告し、強化を提案できます。 ### 0.4) ネットワーク露出（bind + port + firewall） -Gatewayは単一ポートで **WebSocket + HTTP** を多重化します。 +Gatewayは、単一ポート上で **WebSocket + HTTP** を多重化します。 - デフォルト: `18789` -- Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` +- config／フラグ／env: `gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT` -このHTTP surfaceには、Control UIとcanvas hostが含まれます。 +このHTTPサーフェスには、Control UIとcanvas hostが含まれます。 -- Control UI（SPA assets）（デフォルトbase path `/`） -- Canvas host: `/__openclaw__/canvas/` と `/__openclaw__/a2ui/`（任意HTML/JS。未信頼コンテンツとして扱う） +- Control UI（SPAアセット）（デフォルトのベースパス `/`） +- Canvas host: `/__openclaw__/canvas/` および `/__openclaw__/a2ui/`（任意のHTML/JS。信頼していないコンテンツとして扱ってください） -普通のbrowserでcanvas contentを読み込むなら、他の未信頼web pageと同様に扱ってください。 +通常のブラウザでcanvasコンテンツを読み込む場合は、他の信頼していないWebページと同様に扱ってください。 -- canvas hostを信頼できないネットワーク/ユーザーへ公開しない -- 権限の高いweb surfaceと同じoriginをcanvas contentに共有させない。影響を完全に理解している場合を除く +- 信頼していないネットワーク／ユーザーへcanvas hostを公開しないでください。 +- 影響を十分に理解していない限り、canvasコンテンツを特権的なWebサーフェスと同一オリジンで共有させないでください。 -Bind modeは、Gatewayがどこでlistenするかを決めます。 +bindモードは、Gatewayがどこで待ち受けるかを制御します。 -- `gateway.bind: "loopback"`（デフォルト）: ローカルクライアントだけが接続可能 -- non-loopback bind（`"lan"`、`"tailnet"`、`"custom"`）は攻撃面を広げる。gateway auth（shared token/passwordまたは正しく設定されたnon-loopback trusted proxy）と実際のfirewallがある場合にのみ使う +- `gateway.bind: "loopback"`（デフォルト）: ローカルクライアントだけが接続できます。 +- loopback以外のbind（`"lan"`、`"tailnet"`、`"custom"`）は攻撃面を広げます。これらは、gateway auth（共有token／password、または正しく設定された非loopback trusted proxy）と実際のファイアウォールがある場合にのみ使ってください。 経験則: -- LAN bindよりTailscale Serveを優先する（ServeならGatewayはloopbackのまま、アクセスはTailscaleが処理する） -- LANへbindする必要があるなら、portは厳しい送信元IP allowlistでfirewallし、広くport-forwardしない -- `0.0.0.0` へ未認証でGatewayを公開しない +- LAN bindよりTailscale Serveを優先してください（ServeはGatewayをloopback上に保ち、アクセスはTailscaleが処理します）。 +- どうしてもLANへbindする必要がある場合は、ポートへのアクセスを送信元IPの厳格な許可リストでファイアウォールしてください。広くポートフォワードしないでください。 +- 認証なしのGatewayを `0.0.0.0` へ絶対に公開しないでください。 -### 0.4.1) Docker port publishing + UFW (`DOCKER-USER`) +### 0.4.1) Dockerのポート公開 + UFW（`DOCKER-USER`） -VPS上でDockerと一緒にOpenClawを動かす場合、公開container port -（`-p HOST:CONTAINER` またはCompose `ports:`）は、ホストの `INPUT` ルールだけでなくDockerのforwarding chainsも通ることに注意してください。 +VPS上でDockerを使ってOpenClawを動かす場合は、公開されたコンテナポート（`-p HOST:CONTAINER` またはComposeの `ports:`）が、ホストの `INPUT` ルールだけでなく、Dockerの転送チェーンを通ってルーティングされることを忘れないでください。 -Dockerトラフィックをfirewall policyと一致させるには、 -`DOCKER-USER` でルールを強制してください（このchainはDocker自身のaccept rulesより先に評価されます）。 -多くの最近のdistroでは、`iptables`/`ip6tables` は `iptables-nft` frontendを使い、これらのルールは引き続きnftables backendに適用されます。 +Dockerのトラフィックをファイアウォールポリシーに合わせるには、`DOCKER-USER` でルールを強制してください（このチェーンはDocker自身のacceptルールより前に評価されます）。最近の多くのディストリビューションでは、`iptables`／`ip6tables` は `iptables-nft` フロントエンドを使っており、それでもこれらのルールはnftablesバックエンドに適用されます。 -最小allowlist例（IPv4）: +最小限の許可リスト例（IPv4）: ```bash -# /etc/ufw/after.rules (append as its own *filter section) +# /etc/ufw/after.rules（独立した *filter セクションとして追記） *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN @@ -770,12 +772,11 @@ Dockerトラフィックをfirewall policyと一致させるには、 COMMIT ``` -IPv6には別テーブルがあります。Docker IPv6を有効にしているなら、 -`/etc/ufw/after6.rules` にも対応するpolicyを追加してください。 +IPv6には別のテーブルがあります。Docker IPv6が有効なら、`/etc/ufw/after6.rules` に対応するポリシーも追加してください。 -docsの例に `eth0` のようなinterface名を固定で書かないでください。interface名はVPS imageごとに異なり（`ens3`、`enp*` など）、不一致だとdeny ruleが意図せず効かないことがあります。 +ドキュメントのスニペットに `eth0` のようなインターフェース名をハードコードしないでください。インターフェース名はVPSイメージごとに異なり（`ens3`、`enp*` など）、一致しないとdenyルールが意図せずスキップされることがあります。 -reload後の簡易検証: +再読み込み後の簡易確認: ```bash ufw reload @@ -784,21 +785,21 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -外部から見えるportは、意図して公開したものだけであるべきです（多くの構成では SSH + reverse proxy ports）。 +外部から見える想定ポートは、意図的に公開したものだけであるべきです（多くの構成ではSSH + リバースプロキシ用ポート）。 ### 0.4.2) mDNS/Bonjour discovery（情報漏えい） -Gatewayはローカルデバイス発見のために、mDNS（port 5353上の `_openclaw-gw._tcp`）で自身の存在をブロードキャストします。full modeでは、運用詳細を漏らす可能性のあるTXT recordsを含みます。 +Gatewayは、ローカルデバイス探索のためにmDNS（ポート5353上の `_openclaw-gw._tcp`）で自身の存在をブロードキャストします。fullモードでは、運用上の詳細を露出しうるTXTレコードが含まれます。 -- `cliPath`: CLI binaryの完全filesystem path（usernameとinstall locationを露出） -- `sshPort`: host上でSSHが使えることを広告する -- `displayName`, `lanHost`: hostname情報 +- `cliPath`: CLIバイナリへの完全なファイルシステムパス（ユーザー名とインストール場所が分かる） +- `sshPort`: ホスト上でのSSH利用可否を広告する +- `displayName`、`lanHost`: ホスト名に関する情報 -**運用セキュリティ上の考慮:** インフラ詳細をブロードキャストすると、ローカルネットワーク上の誰に対しても偵察が容易になります。filesystem pathsやSSH可用性のような「無害に見える」情報でも、攻撃者が環境を把握する助けになります。 +**運用セキュリティ上の考慮:** インフラの詳細をブロードキャストすると、ローカルネットワーク上の誰にとっても偵察が容易になります。ファイルシステムパスやSSH可用性のような「無害に見える」情報でも、攻撃者が環境を把握する助けになります。 -**推奨:** +**推奨事項:** -1. **minimal mode**（デフォルト、公開gatewayでは推奨）: mDNS broadcastから機微なフィールドを省く +1. **Minimalモード**（デフォルト。公開Gateway向けに推奨）: mDNSブロードキャストから機微なフィールドを省略します。 ```json5 { @@ -808,7 +809,7 @@ Gatewayはローカルデバイス発見のために、mDNS（port 5353上の `_ } ``` -2. ローカルデバイス発見が不要なら**完全に無効化**する +2. ローカルデバイス探索が不要なら、**完全に無効化**してください。 ```json5 { @@ -818,7 +819,7 @@ Gatewayはローカルデバイス発見のために、mDNS（port 5353上の `_ } ``` -3. **full mode**（オプトイン）: TXT recordsに `cliPath` + `sshPort` を含める +3. **Fullモード**（オプトイン）: TXTレコードに `cliPath` + `sshPort` を含めます。 ```json5 { @@ -828,19 +829,17 @@ Gatewayはローカルデバイス発見のために、mDNS（port 5353上の `_ } ``` -4. **環境変数**（代替）: config変更なしでmDNSを無効にするには `OPENCLAW_DISABLE_BONJOUR=1` を設定する +4. **環境変数**（代替手段）: configを変更せずにmDNSを無効化するには、`OPENCLAW_DISABLE_BONJOUR=1` を設定してください。 -minimal modeでは、Gatewayはデバイス発見に十分な情報（`role`, `gatewayPort`, `transport`）はbroadcastしますが、`cliPath` と `sshPort` は省きます。CLI path情報が必要なappsは、認証済みWebSocket接続経由でそれを取得できます。 +minimalモードでも、Gatewayはデバイス探索に十分な情報（`role`、`gatewayPort`、`transport`）は引き続きブロードキャストしますが、`cliPath` と `sshPort` は省略します。CLIパス情報が必要なアプリは、認証済みWebSocket接続経由で取得できます。 -### 0.5) Gateway WebSocketをロックダウンする（local auth） +### 0.5) Gateway WebSocketをロックダウンする（ローカルauth） -Gateway authはデフォルトで**必須**です。正しいgateway auth pathが設定されていないと、 -GatewayはWebSocket接続を拒否します（fail-closed）。 +Gateway authはデフォルトで**必須**です。有効なgateway auth経路が設定されていない場合、GatewayはWebSocket接続を拒否します（フェイルクローズ）。 -Onboardingはデフォルトでtokenを生成するため（loopbackでも）、 -ローカルクライアントも認証が必要です。 +オンボーディングはデフォルトでtokenを生成するため（loopbackであっても）、ローカルクライアントも認証が必要です。 -tokenを設定して、**すべての**WS clientsが認証されるようにします。 +**すべての**WSクライアントに認証を要求するには、tokenを設定してください。 ```json5 { @@ -850,114 +849,111 @@ tokenを設定して、**すべての**WS clientsが認証されるようにし } ``` -Doctorは生成できます: `openclaw doctor --generate-gateway-token` +Doctorはこれを生成できます: `openclaw doctor --generate-gateway-token` -注意: `gateway.remote.token` / `.password` はclient credential sourceです。 -それ自体ではローカルWS accessを保護しません。 -ローカル呼び出し経路は、`gateway.auth.*` が未設定のときのみ `gateway.remote.*` をfallbackとして使えます。 -`gateway.auth.token` / `gateway.auth.password` がSecretRef経由で明示設定されていて未解決の場合、解決はfail-closedします（remote fallbackで隠されません）。 -任意: `wss://` 使用時は `gateway.remote.tlsFingerprint` でremote TLSをpinできます。 -平文 `ws://` はデフォルトでloopback専用です。信頼されたprivate-network path向けには、緊急回避としてclient processで `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` を設定してください。 +注意: `gateway.remote.token` / `.password` はクライアント認証情報の取得元です。これら**単体では**ローカルWSアクセスを保護しません。 +ローカル呼び出し経路では、`gateway.auth.*` が未設定のときに限り、フォールバックとして `gateway.remote.*` を使用できます。 +`gateway.auth.token` / `gateway.auth.password` がSecretRef経由で明示的に設定されていて未解決の場合、解決はフェイルクローズし、リモートフォールバックで隠されることはありません。 +任意: `wss://` を使う場合は、`gateway.remote.tlsFingerprint` でリモートTLSをピン留めできます。 +平文の `ws://` はデフォルトでloopback専用です。信頼されたプライベートネットワーク経路での緊急手段として、クライアントプロセスに `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` を設定してください。 -ローカルdevice pairing: +ローカルデバイスのペアリング: -- 同一host上のdirect local loopback connectは、same-host clientsを滑らかにするため自動承認されます。 -- OpenClawには、信頼されたshared-secret helper flows向けの、狭いbackend/container-local self-connect pathもあります。 -- TailnetとLAN接続は、same-host tailnet bindを含め、pairing上はremoteとして扱われ、引き続き承認が必要です。 +- 同一ホスト上のクライアント接続を円滑にするため、直接のローカルloopback接続ではデバイスペアリングは自動承認されます。 +- OpenClawには、信頼された共有シークレットのヘルパーフロー向けに、限定的なバックエンド／コンテナローカルのセルフ接続経路もあります。 +- Tailnet接続とLAN接続は、同一ホスト上のtailnet bindを含め、ペアリング上はリモートとして扱われ、引き続き承認が必要です。 -Auth modes: +authモード: -- `gateway.auth.mode: "token"`: shared bearer token（多くの構成で推奨） -- `gateway.auth.mode: "password"`: password auth（`OPENCLAW_GATEWAY_PASSWORD` をenvで設定するのを推奨） -- `gateway.auth.mode: "trusted-proxy"`: identity-aware reverse proxyがユーザー認証し、headersでidentityを渡すことを信頼する（[Trusted Proxy Auth](/gateway/trusted-proxy-auth) 参照） +- `gateway.auth.mode: "token"`: 共有bearer token（ほとんどの構成で推奨）。 +- `gateway.auth.mode: "password"`: password auth（envでの設定推奨: `OPENCLAW_GATEWAY_PASSWORD`）。 +- `gateway.auth.mode: "trusted-proxy"`: アイデンティティ対応のリバースプロキシを信頼し、ヘッダー経由で渡されるアイデンティティでユーザーを認証します（[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照）。 -ローテーション手順（token/password）: +ローテーションチェックリスト（token／password）: -1. 新しいsecretを生成/設定する（`gateway.auth.token` または `OPENCLAW_GATEWAY_PASSWORD`）。 -2. Gatewayを再起動する（またはmacOS appがGatewayを監督しているならそのappを再起動する）。 -3. remote clientsを更新する（Gatewayを呼ぶ各マシンの `gateway.remote.token` / `.password`）。 -4. 古いcredentialでは接続できなくなったことを確認する。 +1. 新しいシークレットを生成／設定する（`gateway.auth.token` または `OPENCLAW_GATEWAY_PASSWORD`）。 +2. Gatewayを再起動する（または、macOSアプリがGatewayを監督している場合は、そのアプリを再起動する）。 +3. リモートクライアントを更新する（Gatewayへ接続する各マシン上の `gateway.remote.token` / `.password`）。 +4. 古い認証情報では接続できなくなったことを確認する。 -### 0.6) Tailscale Serve identity headers +### 0.6) Tailscale Serveのアイデンティティヘッダー -`gateway.auth.allowTailscale` が `true` のとき（Serveではデフォルト）、OpenClawは -Control UI/WebSocket認証にTailscale Serve identity headers（`tailscale-user-login`）を受け入れます。OpenClawは、`x-forwarded-for` アドレスをローカルTailscale daemon経由（`tailscale whois`）で解決し、その結果をheaderと照合することでidentityを検証します。これは、リクエストがloopbackへ到達し、かつ `x-forwarded-for`、`x-forwarded-proto`、`x-forwarded-host` をTailscaleにより注入されている場合にのみ発動します。 -この非同期identity check pathでは、同じ `{scope, ip}` に対する失敗試行はlimiterが失敗を記録する前に直列化されます。そのため1つのServe clientからの悪い並行再試行は、2つの単なる不一致としてすり抜けるのではなく、2回目が即座にlock outされることがあります。 -HTTP API endpoints（たとえば `/v1/*`、`/tools/invoke`、`/api/channels/*`）はTailscale identity-header authを使いません。これらは引き続きgatewayで設定されたHTTP auth modeに従います。 +`gateway.auth.allowTailscale` が `true` の場合（Serveではデフォルト）、OpenClawはControl UI／WebSocket認証にTailscale Serveのアイデンティティヘッダー（`tailscale-user-login`）を受け入れます。OpenClawは、`x-forwarded-for` アドレスをローカルのTailscaleデーモン（`tailscale whois`）で解決し、その結果をヘッダーと照合することでアイデンティティを検証します。これは、Tailscaleによって注入される `x-forwarded-for`、`x-forwarded-proto`、`x-forwarded-host` を含み、かつloopbackへ到達するリクエストに対してのみ発動します。 +この非同期アイデンティティチェック経路では、同じ `{scope, ip}` に対する失敗試行は、リミッターが失敗を記録する前に直列化されます。そのため、同一Serveクライアントからの並行した不正リトライでは、2回目の試行が単なる並走ミスマッチになる代わりに、即座にロックアウトされることがあります。 +HTTP APIエンドポイント（たとえば `/v1/*`、`/tools/invoke`、`/api/channels/*`）は、Tailscaleのアイデンティティヘッダーauthを**使用しません**。これらは引き続き、Gatewayに設定されたHTTP authモードに従います。 -重要な境界メモ: +重要な境界上の注意: -- Gateway HTTP bearer authは、実質的にall-or-nothingのoperator accessです。 -- `/v1/chat/completions`、`/v1/responses`、または `/api/channels/*` を呼べるcredentialは、そのgatewayに対する完全アクセスoperator secretとして扱ってください。 -- OpenAI互換HTTP surfaceでは、shared-secret bearer authは完全なデフォルトoperator scopes（`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`）と、agent turnsに対するowner semanticsを復元します。より狭い `x-openclaw-scopes` 値では、このshared-secret pathは狭まりません。 -- HTTPでのper-request scope semanticsは、trusted proxy authやprivate ingress上の `gateway.auth.mode="none"` のようなidentity-bearing modeから来たリクエストにのみ適用されます。 -- それらのidentity-bearing modesでは、`x-openclaw-scopes` を省略すると通常のoperatorデフォルトscope setにフォールバックします。より狭いscope setが欲しいなら、そのheaderを明示的に送ってください。 -- `/tools/invoke` も同じshared-secret ruleに従います: token/password bearer authはそこでも完全operator accessとして扱われ、identity-bearing modesでは引き続き宣言scopeを尊重します。 -- これらのcredentialを信頼できない呼び出し元と共有しないでください。信頼境界ごとに別gatewayを使う方がよいです。 +- Gateway HTTP bearer authは、事実上、全面的な運用者アクセスです。 +- `/v1/chat/completions`、`/v1/responses`、または `/api/channels/*` を呼び出せる認証情報は、そのGatewayに対するフルアクセスの運用者シークレットとして扱ってください。 +- OpenAI互換HTTPサーフェスでは、共有シークレットbearer authは、デフォルトの完全な運用者スコープ（`operator.admin`、`operator.approvals`、`operator.pairing`、`operator.read`、`operator.talk.secrets`、`operator.write`）と、エージェントターンに対するownerセマンティクスを復元します。より狭い `x-openclaw-scopes` 値を送っても、この共有シークレット経路では権限は縮小されません。 +- HTTPでのリクエスト単位スコープセマンティクスが適用されるのは、trusted proxy authや、プライベート受信面での `gateway.auth.mode="none"` のような、アイデンティティを持つモードから来るリクエストだけです。 +- それらのアイデンティティ付きモードでは、`x-openclaw-scopes` を省略すると通常の運用者デフォルトスコープセットへフォールバックします。より狭いスコープにしたい場合は、ヘッダーを明示的に送ってください。 +- `/tools/invoke` も同じ共有シークレットルールに従います。つまり、そこでのtoken／password bearer authもフル運用者アクセスとして扱われます。一方、アイデンティティ付きモードでは、宣言されたスコープが引き続き尊重されます。 +- これらの認証情報を信頼していない呼び出し元と共有しないでください。信頼境界ごとに別々のGatewayを使うことを優先してください。 -**信頼前提:** tokenless Serve authはgateway hostが信頼されている前提です。敵対的なsame-host processからの保護だと考えないでください。gateway host上で未信頼のローカルコードが動く可能性があるなら、`gateway.auth.allowTailscale` を無効にし、`gateway.auth.mode: "token"` または `"password"` による明示shared-secret authを必須にしてください。 +**信頼前提:** tokenなしのServe authは、gateway hostが信頼されていることを前提としています。これを、敵対的な同一ホストプロセスに対する保護だと考えないでください。信頼していないローカルコードがgateway host上で動作する可能性があるなら、`gateway.auth.allowTailscale` を無効にし、`gateway.auth.mode: "token"` または `"password"` による明示的な共有シークレットauthを要求してください。 -**セキュリティルール:** 自分のreverse proxyからこれらのheadersをforwardしないでください。TLSをgateway手前で終端したりproxyしたりするなら、`gateway.auth.allowTailscale` を無効にし、shared-secret auth（`gateway.auth.mode: "token"` または `"password"`）または [Trusted Proxy Auth](/gateway/trusted-proxy-auth) を使ってください。 +**セキュリティルール:** これらのヘッダーを、自分のリバースプロキシから転送しないでください。Gatewayの手前でTLSを終端またはプロキシする場合は、`gateway.auth.allowTailscale` を無効にし、代わりに共有シークレットauth（`gateway.auth.mode: "token"` または `"password"`）か [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を使用してください。 -Trusted proxies: +信頼するプロキシ: -- Gateway手前でTLS終端するなら、proxy IPを `gateway.trustedProxies` に設定してください。 -- OpenClawは、それらのIPから来た `x-forwarded-for`（または `x-real-ip`）を信頼し、local pairing checksやHTTP auth/local checksのためのclient IP決定に使います。 -- proxyが `x-forwarded-for` を**上書き**し、Gateway portへの直接アクセスを遮断することを確認してください。 +- Gatewayの手前でTLSを終端する場合は、`gateway.trustedProxies` にプロキシIPを設定してください。 +- OpenClawは、それらのIPからの `x-forwarded-for`（または `x-real-ip`）を信頼し、ローカルペアリングチェックやHTTP auth／ローカルチェックのためのクライアントIP判定に使います。 +- プロキシが `x-forwarded-for` を**上書き**し、Gatewayポートへの直接アクセスをブロックしていることを確認してください。 -[ Tailscale ](/gateway/tailscale) と [Web overview](/web) も参照してください。 +参照: [Tailscale](/ja-JP/gateway/tailscale) および [Web overview](/web) -### 0.6.1) node host経由のbrowser control（推奨） +### 0.6.1) node host経由のブラウザ制御（推奨） -Gatewayがremoteでもbrowserが別マシン上で動くなら、そのbrowserマシンで **node host** を動かし、Gatewayにbrowser actionsをproxyさせてください（[Browser tool](/tools/browser) 参照）。 -node pairingはadmin accessとして扱ってください。 +Gatewayがリモートにあり、ブラウザが別のマシンで動作している場合は、そのブラウザマシン上で **node host** を実行し、Gatewayにブラウザ操作をプロキシさせてください（[Browser tool](/ja-JP/tools/browser) を参照）。nodeペアリングは管理者アクセスとして扱ってください。 推奨パターン: -- Gatewayとnode hostを同じtailnet（Tailscale）上に保つ。 -- 意図的にnodeをpairし、不要ならbrowser proxy routingを無効化する。 +- Gatewayとnode hostは同じtailnet（Tailscale）上に保つ。 +- nodeは意図的にペアリングし、ブラウザプロキシルーティングが不要なら無効化する。 避けるべきこと: -- relay/control portsをLANや公開Internetへ露出すること。 -- browser control endpointsに対するTailscale Funnel（公開露出）。 +- リレーポートや制御ポートをLANや公開インターネットへ露出すること。 +- ブラウザ制御エンドポイントにTailscale Funnelを使うこと（公開露出）。 -### 0.7) ディスク上のsecret（機密データ） +### 0.7) ディスク上のシークレット（機微データ） -`~/.openclaw/`（または `$OPENCLAW_STATE_DIR/`）配下のものは、secretやprivate dataを含みうると考えてください。 +`~/.openclaw/`（または `$OPENCLAW_STATE_DIR/`）配下のものは、シークレットまたは非公開データを含みうると考えてください。 -- `openclaw.json`: configにはtokens（gateway、remote gateway）、provider settings、allowlistsが入りうる -- `credentials/**`: channel credentials（例: WhatsApp creds）、pairing allowlists、legacy OAuth imports -- `agents//agent/auth-profiles.json`: API keys、token profiles、OAuth tokens、任意の `keyRef`/`tokenRef` -- `secrets.json`（任意）: `file` SecretRef providersで使うファイルベースsecret payload（`secrets.providers`） -- `agents//agent/auth.json`: legacy互換ファイル。静的な `api_key` entriesは検出時にscrubされる -- `agents//sessions/**`: session transcripts（`*.jsonl`）+ routing metadata（`sessions.json`）。private messagesやtool outputを含みうる -- bundled plugin packages: インストール済みplugins（およびそれらの `node_modules/`） -- `sandboxes/**`: tool sandbox workspaces。sandbox内で読んだ/書いたファイルのコピーが蓄積しうる +- `openclaw.json`: configには、token（gateway、remote gateway）、プロバイダー設定、許可リストが含まれる可能性があります。 +- `credentials/**`: チャネル認証情報（例: WhatsApp creds）、ペアリング許可リスト、レガシーOAuthインポート。 +- `agents//agent/auth-profiles.json`: APIキー、tokenプロファイル、OAuthトークン、および任意の `keyRef`／`tokenRef`。 +- `secrets.json`（任意）: `file` SecretRefプロバイダー（`secrets.providers`）で使われるファイルベースのシークレットペイロード。 +- `agents//agent/auth.json`: レガシー互換ファイル。静的な `api_key` エントリーは、発見時に削除されます。 +- `agents//sessions/**`: セッショントランスクリプト（`*.jsonl`）+ ルーティングメタデータ（`sessions.json`）。プライベートメッセージやツール出力を含むことがあります。 +- バンドル済みプラグインパッケージ: インストール済みプラグイン（およびその `node_modules/`）。 +- `sandboxes/**`: ツールsandboxワークスペース。sandbox内で読み書きしたファイルのコピーが蓄積されることがあります。 強化のヒント: -- 権限は厳しくする（dirは `700`、fileは `600`） -- gateway hostではfull-disk encryptionを使う -- host共有時はGateway専用のOS user accountを優先する +- 権限を厳しく保つ（ディレクトリは `700`、ファイルは `600`）。 +- Gatewayホストではフルディスク暗号化を使用する。 +- ホストを共有する場合は、Gateway専用のOSユーザーアカウントを優先する。 -### 0.8) Logs + transcripts（redaction + retention） +### 0.8) ログ + トランスクリプト（マスキング + 保持） -アクセス制御が正しくても、logsやtranscriptsは機微情報を漏らしえます。 +アクセス制御が正しくても、ログやトランスクリプトから機微情報が漏れることがあります。 -- Gateway logsにはtool summary、errors、URLsが含まれうる -- Session transcriptsには貼り付けられたsecret、file contents、command output、linksが含まれうる +- Gatewayログには、ツールの要約、エラー、URLが含まれることがあります。 +- セッショントランスクリプトには、貼り付けられたシークレット、ファイル内容、コマンド出力、リンクが含まれることがあります。 -推奨: +推奨事項: -- tool summary redactionを有効に保つ（`logging.redactSensitive: "tools"`; デフォルト） -- 環境固有のパターン（tokens、hostnames、internal URLs）を `logging.redactPatterns` で追加する -- 診断を共有するときは、生logsより `openclaw status --all`（貼り付け向け、secrets redacted）を優先する -- 長期保持が不要なら、古いsession transcriptsとlog filesを整理する +- ツール要約のマスキングを有効のままにしてください（`logging.redactSensitive: "tools"`。デフォルト）。 +- 自分の環境向けに `logging.redactPatterns` でカスタムパターンを追加してください（token、ホスト名、内部URLなど）。 +- 診断情報を共有する場合は、生ログではなく、`openclaw status --all` を優先してください（貼り付けやすく、シークレットはマスク済み）。 +- 長期保持が不要なら、古いセッショントランスクリプトやログファイルを削除してください。 -詳細: [Logging](/gateway/logging) +詳細: [Logging](/ja-JP/gateway/logging) -### 1) DMs: デフォルトでpairing +### 1) DM: デフォルトでpairing ```json5 { @@ -965,7 +961,7 @@ node pairingはadmin accessとして扱ってください。 } ``` -### 2) Groups: どこでもmention必須 +### 2) グループ: すべてでメンション必須 ```json { @@ -987,31 +983,31 @@ node pairingはadmin accessとして扱ってください。 } ``` -group chatsでは、明示的にmentionされたときだけ応答してください。 +グループチャットでは、明示的にメンションされたときだけ応答してください。 -### 3) 別番号を使う（WhatsApp、Signal、Telegram） +### 3) 番号を分ける（WhatsApp、Signal、Telegram） -電話番号ベースchannelでは、AI用に個人番号とは別の電話番号を使うことを検討してください。 +電話番号ベースのチャネルでは、AI用に個人用とは別の電話番号で運用することを検討してください。 -- 個人番号: あなたの会話を非公開に保てる -- bot番号: AIが適切な境界付きで処理する +- 個人用番号: あなたの会話は非公開のまま +- ボット用番号: AIが適切な境界付きで対応する ### 4) 読み取り専用モード（sandbox + tools経由） -以下を組み合わせることで、読み取り専用profileを作れます。 +次を組み合わせることで、読み取り専用プロファイルを構築できます。 -- `agents.defaults.sandbox.workspaceAccess: "ro"`（またはworkspace accessなしなら `"none"`） -- `write`、`edit`、`apply_patch`、`exec`、`process` などをブロックするtool allow/deny lists +- `agents.defaults.sandbox.workspaceAccess: "ro"`（またはワークスペースアクセスなしなら `"none"`） +- `write`、`edit`、`apply_patch`、`exec`、`process` などをブロックするツールallow／denyリスト 追加の強化オプション: -- `tools.exec.applyPatch.workspaceOnly: true`（デフォルト）: sandboxingがoffでも `apply_patch` がworkspace directory外を書き換え/削除できないようにする。workspace外へ触れさせたい意図がある場合だけ `false` にする。 -- `tools.fs.workspaceOnly: true`（任意）: `read`/`write`/`edit`/`apply_patch` のパスと、ネイティブprompt image auto-load pathsをworkspace directoryに制限する（今は絶対パスを許していて、1つのガードレールが欲しい場合に有用）。 -- Filesystem rootsは狭く保つ: agent workspaces/sandbox workspacesにhome directory全体のような広いrootを使わない。広いrootは、`~/.openclaw` 配下のstate/configのような機微ファイルをfilesystem toolsへ露出し得る。 +- `tools.exec.applyPatch.workspaceOnly: true`（デフォルト）: sandbox化がオフでも、`apply_patch` がワークスペースディレクトリ外へ書き込み／削除できないようにします。`apply_patch` でワークスペース外のファイルへ触れさせたい意図がある場合にのみ `false` に設定してください。 +- `tools.fs.workspaceOnly: true`（任意）: `read`／`write`／`edit`／`apply_patch` のパスと、ネイティブプロンプト画像の自動読み込みパスをワークスペースディレクトリに制限します（現在絶対パスを許可していて、単一のガードレールを追加したい場合に有用です）。 +- ファイルシステムルートは狭く保ってください。エージェントワークスペースやsandboxワークスペースに、ホームディレクトリのような広いルートを使わないでください。広いルートは、機微なローカルファイル（たとえば `~/.openclaw` 配下のstate／config）をファイルシステムツールへ露出する可能性があります。 -### 5) 安全なベースライン（そのまま使える） +### 5) セキュアベースライン（コピー＆ペースト用） -Gatewayを非公開に保ち、DM pairingを要求し、常時反応するgroup botを避ける「安全側のデフォルト」設定例です。 +Gatewayを非公開に保ち、DMにpairingを要求し、グループボットの常時応答を避ける、1つの `「安全なデフォルト」` configです。 ```json5 { @@ -1030,66 +1026,66 @@ Gatewayを非公開に保ち、DM pairingを要求し、常時反応するgroup } ``` -tool executionも「より安全側」にしたいなら、sandboxを有効にし、owner以外のagentではdangerous toolsをdenyしてください（下の「agentごとのアクセスプロファイル」の例参照）。 +ツール実行も `「より安全なデフォルト」` にしたい場合は、sandboxを追加し、オーナー以外のエージェントでは危険なツールをdenyしてください（下の `「エージェントごとのアクセスプロファイル」` の例を参照）。 -chat-drivenなagent turnsに対する組み込みベースラインでは、owner以外の送信者は `cron` や `gateway` toolsを使えません。 +チャット駆動のエージェントターン向けの組み込みベースラインでは、オーナー以外の送信者は `cron` または `gateway` ツールを使用できません。 ## Sandboxing（推奨） -専用ドキュメント: [Sandboxing](/gateway/sandboxing) +専用ドキュメント: [Sandboxing](/ja-JP/gateway/sandboxing) 補完し合う2つの方法があります。 -- **Gateway全体をDockerで実行する**（container boundary）: [Docker](/install/docker) -- **Tool sandbox**（`agents.defaults.sandbox`、gateway hostはそのまま + toolsだけDocker隔離）: [Sandboxing](/gateway/sandboxing) +- **Gateway全体をDockerで実行する**（コンテナ境界）: [Docker](/ja-JP/install/docker) +- **ツールsandbox**（`agents.defaults.sandbox`、Gateway本体はホスト上 + ツールはDocker分離）: [Sandboxing](/ja-JP/gateway/sandboxing) -注意: cross-agent accessを防ぐには、`agents.defaults.sandbox.scope` を `"agent"`（デフォルト）に保つか、より厳格な `"session"` にしてください。`scope: "shared"` は単一container/workspaceを共有します。 +注意: エージェント間アクセスを防ぐには、`agents.defaults.sandbox.scope` を `"agent"`（デフォルト）のままにするか、より厳密なセッション単位分離が必要なら `"session"` を使ってください。`scope: "shared"` は単一のコンテナ／ワークスペースを使います。 -sandbox内のagent workspace accessも検討してください。 +また、sandbox内でのエージェントワークスペースアクセスも検討してください。 -- `agents.defaults.sandbox.workspaceAccess: "none"`（デフォルト）はagent workspaceを見せず、toolsは `~/.openclaw/sandboxes` 配下のsandbox workspaceで動く -- `agents.defaults.sandbox.workspaceAccess: "ro"` はagent workspaceを `/agent` にread-only mountする（`write`/`edit`/`apply_patch` を無効化） -- `agents.defaults.sandbox.workspaceAccess: "rw"` はagent workspaceを `/workspace` にread/write mountする -- 追加の `sandbox.docker.binds` は、正規化・canonical化されたsource pathsに対して検証される。親symlink tricksやcanonical home aliasesも、`/etc`、`/var/run`、OS home配下のcredential directoriesなど禁止rootへ解決される場合はfail-closedする。 +- `agents.defaults.sandbox.workspaceAccess: "none"`（デフォルト）では、エージェントワークスペースはアクセス不可のままで、ツールは `~/.openclaw/sandboxes` 配下のsandboxワークスペースに対して実行されます。 +- `agents.defaults.sandbox.workspaceAccess: "ro"` は、エージェントワークスペースを `/agent` に読み取り専用でマウントします（`write`／`edit`／`apply_patch` を無効化）。 +- `agents.defaults.sandbox.workspaceAccess: "rw"` は、エージェントワークスペースを `/workspace` に読み書き可能でマウントします。 +- 追加の `sandbox.docker.binds` は、正規化およびcanonical化されたソースパスに対して検証されます。親symlinkのトリックやcanonical home aliasを使っても、`/etc`、`/var/run`、またはOSホーム配下の認証情報ディレクトリのようなブロック対象ルートへ解決される場合は、引き続きフェイルクローズします。 -重要: `tools.elevated` は、sandbox外でexecを実行するグローバルbaseline escape hatchです。実効hostはデフォルトで `gateway`、exec targetが `node` に設定されていれば `node` になります。`tools.elevated.allowFrom` は厳しく保ち、見知らぬ相手には有効にしないでください。agentごとに `agents.list[].tools.elevated` でもさらに制限できます。[Elevated Mode](/tools/elevated) を参照してください。 +重要: `tools.elevated` は、sandbox外でexecを実行するグローバルなベースラインのエスケープハッチです。有効なhostはデフォルトで `gateway`、exec対象が `node` に設定されている場合は `node` です。`tools.elevated.allowFrom` は厳格に保ち、見知らぬ相手には有効化しないでください。さらに、エージェント単位で `agents.list[].tools.elevated` により制限できます。参照: [Elevated Mode](/ja-JP/tools/elevated) -### Sub-agent delegation guardrail +### サブエージェント委任のガードレール -session toolsを許可するなら、委譲されたsub-agent runsも別の境界判断として扱ってください。 +セッションツールを許可する場合、委任されたサブエージェント実行も別の境界判断として扱ってください。 -- agentが本当にdelegationを必要としない限り、`sessions_spawn` をdenyする。 -- `agents.defaults.subagents.allowAgents` と、agentごとの `agents.list[].subagents.allowAgents` overridesは、既知の安全なtarget agentsに限定する。 -- sandbox内に留まる必要があるワークフローでは、`sessions_spawn` を `sandbox: "require"` で呼ぶ（デフォルトは `inherit`）。 -- `sandbox: "require"` は、target child runtimeがsandboxedでない場合に即失敗する。 +- エージェントが本当に委任を必要としない限り、`sessions_spawn` をdenyしてください。 +- `agents.defaults.subagents.allowAgents` と、エージェント単位の `agents.list[].subagents.allowAgents` 上書きは、既知の安全な対象エージェントに限定してください。 +- sandbox化を維持すべきワークフローでは、`sessions_spawn` を `sandbox: "require"` で呼び出してください（デフォルトは `inherit`）。 +- `sandbox: "require"` は、対象の子ランタイムがsandbox化されていない場合に即座に失敗します。 -## Browser controlのリスク +## ブラウザ制御のリスク -browser controlを有効にすると、モデルに実browserを操作する力を与えます。 -そのbrowser profileにログイン済みsessionが入っていれば、モデルはそれらのaccountやdataへアクセスできます。browser profilesは**機微なstate**として扱ってください。 +ブラウザ制御を有効にすると、モデルに実際のブラウザを操作する能力を与えることになります。 +そのブラウザプロファイルにログイン済みセッションが含まれている場合、モデルはそれらのアカウントやデータへアクセスできます。ブラウザプロファイルは**機微な状態**として扱ってください。 -- agent専用profileを優先する（デフォルトの `openclaw` profile） -- agentをあなたの個人用daily-driver profileに向けない -- sandboxed agentsでは、信頼していない限りhost browser controlを無効にする -- standaloneなloopback browser control APIはshared-secret auth（gateway token bearer authまたはgateway password）だけを受け入れる。trusted-proxyやTailscale Serve identity headersは使わない -- browser downloadsは未信頼入力として扱い、できれば隔離downloads directoryを使う -- agent profileではbrowser sync/password managersを無効にできるなら無効にする（影響範囲縮小） -- remote gatewaysでは、「browser control」はそのprofileが到達できる範囲への「operator access」と同等だと考える -- Gatewayとnode hostsはtailnet専用に保ち、browser control portsをLANや公開Internetへ露出しない -- browser proxy routingは不要なら無効にする（`gateway.nodes.browser.mode="off"`） -- Chrome MCP existing-session modeは**より安全ではありません**。そのhostのChrome profileが到達できるものに対して、あなた本人として動けます。 +- エージェント専用のプロファイルを優先してください（デフォルトの `openclaw` プロファイル）。 +- 個人で普段使っているプロファイルをエージェントに向けないでください。 +- sandbox化されたエージェントでは、信頼していない限りホストのブラウザ制御を無効にしてください。 +- スタンドアロンのloopbackブラウザ制御APIは、共有シークレットauth（gateway token bearer authまたはgateway password）だけを受け付けます。trusted-proxyやTailscale Serveのアイデンティティヘッダーは使用しません。 +- ブラウザのダウンロードは信頼していない入力として扱い、分離されたダウンロードディレクトリを優先してください。 +- 可能なら、エージェントプロファイルではブラウザ同期／パスワードマネージャーを無効にしてください（影響範囲を小さくするため）。 +- リモートGatewayでは、`「ブラウザ制御」` は、そのプロファイルが到達できる範囲に対する `「運用者アクセス」` と同等だと考えてください。 +- Gatewayとnode hostはtailnet限定に保ち、ブラウザ制御ポートをLANや公開インターネットへ露出しないでください。 +- ブラウザプロキシルーティングが不要なら無効化してください（`gateway.nodes.browser.mode="off"`）。 +- Chrome MCPの既存セッションモードは**より安全ではありません**。そのホストのChromeプロファイルが到達できる範囲に対して、あなたとして振る舞えます。 -### Browser SSRF policy（trusted-networkデフォルト） +### ブラウザSSRFポリシー（デフォルトで厳格） -OpenClawのbrowser network policyは、デフォルトでtrusted-operator modelです。明示的に無効化しない限り、private/internal destinationsが許可されます。 +OpenClawのブラウザナビゲーションポリシーは、デフォルトで厳格です。プライベート／内部宛先は、明示的にオプトインしない限りブロックされたままです。 -- デフォルト: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`（未設定時も暗黙的にtrue） -- Legacy alias: `browser.ssrfPolicy.allowPrivateNetwork` も互換のため受け付ける -- Strict mode: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: false` を設定すると、private/internal/special-use destinationsをデフォルトでブロックする -- strict modeでは、明示例外に `hostnameAllowlist`（`*.example.com` のようなパターン）と `allowedHostnames`（`localhost` のようなblocked namesを含む正確なhost例外）を使う -- redirect-based pivotsを減らすため、navigationはrequest前にチェックされ、navigation後の最終 `http(s)` URLでもベストエフォートで再チェックされる +- デフォルト: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定であるため、ブラウザナビゲーションはプライベート／内部／特殊用途の宛先を引き続きブロックします。 +- レガシーエイリアス: `browser.ssrfPolicy.allowPrivateNetwork` も互換性のため引き続き受け付けられます。 +- オプトインモード: プライベート／内部／特殊用途の宛先を許可するには、`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` を設定します。 +- 厳格モードでは、明示的な例外のために `hostnameAllowlist`（`*.example.com` のようなパターン）と `allowedHostnames`（`localhost` のようなブロック対象名を含む正確なホスト例外）を使用します。 +- リダイレクト経由のピボットを減らすため、ナビゲーションはリクエスト前にチェックされ、ナビゲーション後の最終 `http(s)` URLに対してもベストエフォートで再チェックされます。 -strict policy例: +厳格ポリシーの例: ```json5 { @@ -1103,19 +1099,17 @@ strict policy例: } ``` -## agentごとのアクセスプロファイル（multi-agent） +## エージェントごとのアクセスプロファイル（マルチエージェント） -multi-agent routingでは、各agentが独自のsandbox + tool policyを持てます: -これを使って、agentごとに **full access**、**read-only**、**no access** を与えてください。 -詳細と優先順位ルールは [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) を参照してください。 +マルチエージェントルーティングでは、各エージェントに独自のsandbox + ツールポリシーを持たせられます。これを使って、エージェントごとに**フルアクセス**、**読み取り専用**、**アクセスなし**を与えてください。詳細と優先順位ルールは [Multi-Agent Sandbox & Tools](/ja-JP/tools/multi-agent-sandbox-tools) を参照してください。 -一般的な用途: +一般的なユースケース: -- 個人agent: full access、sandboxなし -- family/work agent: sandboxed + read-only tools -- 公開agent: sandboxed + filesystem/shell toolsなし +- 個人用エージェント: フルアクセス、sandboxなし +- 家族／業務エージェント: sandbox化 + 読み取り専用ツール +- 公開エージェント: sandbox化 + ファイルシステム／シェルツールなし -### 例: full access（sandboxなし） +### 例: フルアクセス（sandboxなし） ```json5 { @@ -1131,7 +1125,7 @@ multi-agent routingでは、各agentが独自のsandbox + tool policyを持て } ``` -### 例: read-only tools + read-only workspace +### 例: 読み取り専用ツール + 読み取り専用ワークスペース ```json5 { @@ -1155,7 +1149,7 @@ multi-agent routingでは、各agentが独自のsandbox + tool policyを持て } ``` -### 例: filesystem/shell accessなし（provider messagingは許可） +### 例: ファイルシステム／シェルアクセスなし（プロバイダーメッセージングは許可） ```json5 { @@ -1169,9 +1163,9 @@ multi-agent routingでは、各agentが独自のsandbox + tool policyを持て scope: "agent", workspaceAccess: "none", }, - // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools - // to the current session + spawned subagent sessions, but you can clamp further if needed. - // See `tools.sessions.visibility` in the configuration reference. + // セッションツールはトランスクリプトから機微データを露出する可能性があります。デフォルトではOpenClawはこれらのツールを + // 現在のセッション + 生成されたサブエージェントセッションに制限していますが、必要に応じてさらに絞り込めます。 + // 設定リファレンスの `tools.sessions.visibility` を参照してください。 tools: { sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ @@ -1208,7 +1202,7 @@ multi-agent routingでは、各agentが独自のsandbox + tool policyを持て ## AIに伝えるべきこと -agentのsystem promptにセキュリティ指針を含めてください。 +エージェントのシステムプロンプトには、セキュリティガイドラインを含めてください。 ``` ## Security Rules @@ -1221,65 +1215,65 @@ agentのsystem promptにセキュリティ指針を含めてください。 ## インシデント対応 -AIが何かまずいことをしたら: +AIが問題のある行動をした場合: -### 封じ込める +### 封じ込め -1. **止める:** macOS app（Gatewayを監督している場合）を止めるか、`openclaw gateway` processを終了する。 -2. **露出を閉じる:** 何が起きたか理解するまで、`gateway.bind: "loopback"` にする（またはTailscale Funnel/Serveを無効にする）。 -3. **アクセスを凍結する:** 危険なDM/groupsは `dmPolicy: "disabled"` にする / mention必須にする / `"*"` の全許可エントリがあれば削除する。 +1. **止める:** macOSアプリ（Gatewayを監督している場合）を停止するか、`openclaw gateway` プロセスを終了します。 +2. **露出を閉じる:** 何が起きたか把握するまで、`gateway.bind: "loopback"` に設定するか、Tailscale Funnel／Serveを無効化します。 +3. **アクセスを凍結する:** リスクの高いDM／グループを `dmPolicy: "disabled"` またはメンション必須へ切り替え、もし `"*"` の全許可エントリーがあれば削除します。 -### ローテーションする（secretが漏れたなら侵害前提で動く） +### ローテーション（シークレットが漏れたなら侵害を前提にする） -1. Gateway auth（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）をローテーションし、再起動する。 -2. remote client secrets（Gatewayを呼べる各マシンの `gateway.remote.token` / `.password`）をローテーションする。 -3. provider/API credentials（WhatsApp creds、Slack/Discord tokens、`auth-profiles.json` 内のmodel/API keys、暗号化secret payload values）をローテーションする。 +1. Gateway auth（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）をローテーションし、再起動します。 +2. Gatewayを呼び出せる各マシン上のリモートクライアントシークレット（`gateway.remote.token` / `.password`）をローテーションします。 +3. プロバイダー／API認証情報（WhatsApp creds、Slack／Discordトークン、`auth-profiles.json` 内のモデル／APIキー、および使用している場合は暗号化シークレットペイロード値）をローテーションします。 -### 監査する +### 監査 -1. Gateway logsを確認する: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`（または `logging.file`）。 -2. 関連transcript(s)を確認する: `~/.openclaw/agents//sessions/*.jsonl`。 -3. 最近のconfig changesを確認する（アクセスを広げた可能性があるもの: `gateway.bind`、`gateway.auth`、dm/group policies、`tools.elevated`、plugin changes）。 -4. `openclaw security audit --deep` を再実行し、critical findingsが解消されたことを確認する。 +1. Gatewayログを確認する: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`（または `logging.file`）。 +2. 関連するトランスクリプトを確認する: `~/.openclaw/agents//sessions/*.jsonl`。 +3. 最近のconfig変更を確認する（アクセス拡大につながりうるもの: `gateway.bind`、`gateway.auth`、DM／グループポリシー、`tools.elevated`、プラグイン変更）。 +4. `openclaw security audit --deep` を再実行し、criticalな検出結果が解消されたことを確認する。 -### 報告用に集めるもの +### レポート用に収集する้อมูล -- タイムスタンプ、gateway host OS + OpenClaw version -- session transcript(s) + 短いlog tail（redact後） -- 攻撃者が送ったもの + agentがしたこと -- Gatewayがloopbackを超えて露出していたか（LAN/Tailscale Funnel/Serve） +- タイムスタンプ、GatewayホストのOS + OpenClawバージョン +- セッショントランスクリプト + 短いログ末尾（マスク後） +- 攻撃者が送った内容 + エージェントが実行した内容 +- Gatewayがloopback以外へ露出していたか（LAN／Tailscale Funnel／Serve） -## Secret Scanning (`detect-secrets`) +## シークレットスキャン（detect-secrets） -CIは `secrets` jobで `detect-secrets` pre-commit hookを実行します。 -`main` へのpushでは常に全ファイルスキャンを行います。pull requestでは、base commitがあると変更ファイルだけの高速経路を使い、なければ全ファイルスキャンへフォールバックします。失敗した場合、baselineにまだ入っていない新しい候補があります。 +CIは、`secrets` ジョブで `detect-secrets` のpre-commitフックを実行します。 +`main` へのpushでは常に全ファイルスキャンが実行されます。pull requestでは、ベースコミットが利用可能なら変更ファイルだけの高速経路を使い、そうでなければ全ファイルスキャンへフォールバックします。失敗した場合、ベースラインにまだ含まれていない新しい候補があることを意味します。 -### CIが失敗したら +### CIが失敗した場合 -1. ローカルで再現する: +1. ローカルで再現します: ```bash pre-commit run --all-files detect-secrets ``` -2. ツールを理解する: - - pre-commit内の `detect-secrets` は、repoのbaselineとexcludeを使って `detect-secrets-hook` を実行する。 - - `detect-secrets audit` は対話的レビューを開き、baselineの各項目を本物か誤検知かに印付けする。 -3. 本物のsecretなら: rotate/removeし、その後スキャンを再実行してbaselineを更新する。 -4. 誤検知なら: 対話監査を実行し、falseとしてマークする: +2. ツールの挙動を理解します: + - pre-commit内の `detect-secrets` は、リポジトリのベースラインと除外設定を使って `detect-secrets-hook` を実行します。 + - `detect-secrets audit` は対話式レビューを開き、各ベースライン項目を実際のシークレットか誤検知かとしてマークできます。 +3. 実際のシークレットであれば、ローテーションまたは削除し、その後スキャンを再実行してベースラインを更新します。 +4. 誤検知であれば、対話式監査を実行して false としてマークします: ```bash detect-secrets audit .secrets.baseline ``` -5. 新しいexcludeが必要なら、`.detect-secrets.cfg` に追加し、対応する `--exclude-files` / `--exclude-lines` フラグ付きでbaselineを再生成する（config fileは参照用であり、detect-secretsは自動では読まない）。 +5. 新しい除外が必要な場合は、それを `.detect-secrets.cfg` に追加し、対応する `--exclude-files` / `--exclude-lines` フラグでベースラインを再生成してください（configファイルは参照専用であり、detect-secretsはこれを自動では読み込みません）。 意図した状態を反映した `.secrets.baseline` をコミットしてください。 ## セキュリティ問題の報告 -OpenClawで脆弱性を見つけた場合は、責任ある方法で報告してください。 +OpenClawに脆弱性を見つけた場合は、責任ある形で報告してください。 -1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. 修正されるまで公開しない -3. 希望しない場合を除き、クレジットします +1. メール: [security@openclaw.ai](mailto:security@openclaw.ai) +2. 修正されるまで公開投稿しない +3. 希望する場合は匿名で、そうでなければクレジットを掲載します diff --git a/docs/ja-JP/gateway/troubleshooting.md b/docs/ja-JP/gateway/troubleshooting.md index ca7439228..7d6afd24b 100644 --- a/docs/ja-JP/gateway/troubleshooting.md +++ b/docs/ja-JP/gateway/troubleshooting.md @@ -1,26 +1,26 @@ --- read_when: - - トラブルシューティングハブから、より詳細な診断のためにここへ案内された場合 - - 正確なコマンド付きの、安定した症状ベースの手順セクションが必要な場合 -summary: Gateway、チャネル、自動化、ノード、ブラウザー向けの詳細なトラブルシューティング手順書 + - トラブルシューティングハブから、より深い診断のためにここへ案内されました + - 正確なコマンドを含む、症状ベースの安定したランブックセクションが必要です +summary: Gateway、チャネル、自動化、ノード、ブラウザー向けの詳細なトラブルシューティングランブック title: トラブルシューティング x-i18n: - generated_at: "2026-04-08T02:16:39Z" + generated_at: "2026-04-11T02:45:07Z" model: gpt-5.4 provider: openai - source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba + source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5 source_path: gateway/troubleshooting.md workflow: 15 --- -# Gateway のトラブルシューティング +# Gatewayトラブルシューティング -このページは詳細な手順書です。 -まず簡易トリアージフローを確認したい場合は、[/help/troubleshooting](/ja-JP/help/troubleshooting) から始めてください。 +このページは詳細なランブックです。 +まず高速なトリアージ手順を見たい場合は[/help/troubleshooting](/ja-JP/help/troubleshooting)から始めてください。 -## コマンドの段階的実行 +## コマンドラダー -まずはこの順番で実行してください: +まず、次の順番でこれらを実行してください。 ```bash openclaw status @@ -33,13 +33,12 @@ openclaw channels status --probe 正常時に期待されるシグナル: - `openclaw gateway status` に `Runtime: running` と `RPC probe: ok` が表示される。 -- `openclaw doctor` で、設定やサービスに関するブロッキングな問題が報告されない。 -- `openclaw channels status --probe` で、アカウントごとのライブなトランスポート状態と、 - サポートされている場合は `works` や `audit ok` のような probe/audit 結果が表示される。 +- `openclaw doctor` が、ブロッキングする設定/サービスの問題なしと報告する。 +- `openclaw channels status --probe` が、アカウントごとのライブなトランスポート状態と、対応している場合は `works` や `audit ok` のような probe/audit 結果を表示する。 -## 長いコンテキストに対して Anthropic 429 extra usage required が出る +## 長いコンテキストでAnthropic 429の追加使用量が必要 -ログやエラーに次が含まれている場合に使用してください: +ログやエラーに次が含まれる場合に使用してください: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. ```bash @@ -48,17 +47,17 @@ openclaw models status openclaw config get agents.defaults.models ``` -確認する点: +確認ポイント: -- 選択された Anthropic Opus/Sonnet モデルで `params.context1m: true` になっている。 -- 現在の Anthropic 認証情報が long-context 利用の対象ではない。 -- リクエストが失敗するのは、1M ベータパスが必要な長いセッション/モデル実行時のみである。 +- 選択されたAnthropic Opus/Sonnetモデルで `params.context1m: true` になっている。 +- 現在のAnthropic認証情報が長いコンテキスト利用の対象外である。 +- リクエストが、1Mベータ経路を必要とする長いセッション/モデル実行でのみ失敗する。 修正方法: 1. そのモデルの `context1m` を無効にして、通常のコンテキストウィンドウにフォールバックする。 -2. long-context リクエスト対象の Anthropic 認証情報を使うか、Anthropic API キーに切り替える。 -3. Anthropic の long-context リクエストが拒否されたときも実行が継続するように、フォールバックモデルを設定する。 +2. 長いコンテキストリクエストの対象となるAnthropic認証情報を使うか、Anthropic APIキーに切り替える。 +3. Anthropicの長いコンテキストリクエストが拒否されたときにも実行が継続するよう、フォールバックモデルを設定する。 関連: @@ -66,13 +65,13 @@ openclaw config get agents.defaults.models - [/reference/token-use](/ja-JP/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/ja-JP/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## ローカルの OpenAI-compatible バックエンドでは直接 probe は通るが、エージェント実行は失敗する +## ローカルのOpenAI互換バックエンドは直接probeには通るが、agent実行は失敗する 次の場合に使用してください: - `curl ... /v1/models` は動作する - 小さな直接 `/v1/chat/completions` 呼び出しは動作する -- OpenClaw のモデル実行が失敗するのは通常のエージェントターンのみ +- OpenClawのモデル実行が通常のagentターンでのみ失敗する ```bash curl http://127.0.0.1:1234/v1/models @@ -83,34 +82,34 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -確認する点: +確認ポイント: -- 直接の小さな呼び出しは成功するが、OpenClaw 実行はより大きなプロンプトのときだけ失敗する -- バックエンドエラーで、`messages[].content` が文字列を期待している -- より大きな prompt token 数や、完全なエージェントランタイムプロンプトでのみバックエンドがクラッシュする +- 小さな直接呼び出しは成功するが、OpenClaw実行は大きなプロンプトでのみ失敗する +- バックエンドエラーで `messages[].content` が文字列を期待している +- より大きいプロンプトトークン数や完全なagentランタイムプロンプトでのみ現れるバックエンドクラッシュ よくあるシグネチャ: -- `messages[...].content: invalid type: sequence, expected a string` → バックエンドが構造化された Chat Completions の content parts を拒否している。修正: `models.providers..models[].compat.requiresStringContent: true` を設定する。 -- 直接の小さなリクエストは成功するが、OpenClaw のエージェント実行はバックエンド/モデルのクラッシュで失敗する（たとえば一部の `inferrs` ビルド上の Gemma） → OpenClaw のトランスポートはすでに正しい可能性が高く、バックエンドがより大きいエージェントランタイムのプロンプト形状で失敗している。 -- ツールを無効にすると失敗は減るが消えない → ツールスキーマが負荷の一因ではあったが、残っている問題は依然として上流のモデル/サーバー容量かバックエンドバグである。 +- `messages[...].content: invalid type: sequence, expected a string` → バックエンドが構造化されたChat Completionsのcontent partsを拒否している。修正: `models.providers..models[].compat.requiresStringContent: true` を設定する。 +- 小さな直接リクエストは成功するが、OpenClawのagent実行がバックエンド/モデルクラッシュで失敗する（例: 一部の`inferrs`ビルド上のGemma）→ OpenClawのトランスポートはすでに正しい可能性が高く、バックエンドがより大きなagentランタイムのプロンプト形状で失敗している。 +- ツールを無効にすると失敗は減るが消えない → 圧力の一部はツールスキーマだったが、残っている問題は依然として上流のモデル/サーバー容量またはバックエンドバグ。 修正方法: -1. 文字列のみの Chat Completions バックエンドに対して `compat.requiresStringContent: true` を設定する。 -2. OpenClaw のツールスキーマ面を安定して処理できないモデル/バックエンドには `compat.supportsTools: false` を設定する。 -3. 可能な範囲でプロンプト負荷を下げる: より小さい workspace bootstrap、より短いセッション履歴、より軽いローカルモデル、または long-context サポートがより強いバックエンドを使う。 -4. 直接の小さなリクエストが引き続き成功する一方で、OpenClaw のエージェントターンがバックエンド内部で依然としてクラッシュする場合は、上流のサーバー/モデルの制限として扱い、受け入れられたペイロード形状を添えてそこで再現報告を出す。 +1. 文字列専用のChat Completionsバックエンドに対して `compat.requiresStringContent: true` を設定する。 +2. OpenClawのツールスキーマサーフェスを安定して処理できないモデル/バックエンドに対して `compat.supportsTools: false` を設定する。 +3. 可能な範囲でプロンプト圧力を下げる: より小さいワークスペースブートストラップ、より短いセッション履歴、より軽量なローカルモデル、または長いコンテキストのサポートがより強いバックエンドを使う。 +4. 小さな直接リクエストが引き続き成功する一方で、OpenClawのagentターンがバックエンド内部でなおクラッシュする場合は、上流サーバー/モデルの制限として扱い、受け入れられるペイロード形状を添えてそこで再現報告を出す。 関連: - [/gateway/local-models](/ja-JP/gateway/local-models) -- [/gateway/configuration#models](/ja-JP/gateway/configuration#models) +- [/gateway/configuration](/ja-JP/gateway/configuration) - [/gateway/configuration-reference#openai-compatible-endpoints](/ja-JP/gateway/configuration-reference#openai-compatible-endpoints) ## 返信がない -チャネルは稼働しているのに何も応答しない場合は、何かを再接続する前に、ルーティングとポリシーを確認してください。 +チャネルは起動しているのに何も応答しない場合は、何かを再接続する前にルーティングとポリシーを確認してください。 ```bash openclaw status @@ -120,17 +119,17 @@ openclaw config get channels openclaw logs --follow ``` -確認する点: +確認ポイント: -- DM 送信者に対してペアリングが保留中になっている。 -- グループのメンションゲーティング（`requireMention`、`mentionPatterns`）。 -- チャネル/グループの allowlist 不一致。 +- DM送信者のペアリングが保留中。 +- グループのメンションゲート（`requireMention`、`mentionPatterns`）。 +- チャネル/グループの許可リスト不一致。 よくあるシグネチャ: -- `drop guild message (mention required` → メンションされるまでグループメッセージは無視される。 +- `drop guild message (mention required` → メンションされるまでグループメッセージが無視される。 - `pairing request` → 送信者に承認が必要。 -- `blocked` / `allowlist` → 送信者/チャネルがポリシーによってフィルタリングされた。 +- `blocked` / `allowlist` → 送信者/チャネルがポリシーでフィルタされた。 関連: @@ -138,9 +137,9 @@ openclaw logs --follow - [/channels/pairing](/ja-JP/channels/pairing) - [/channels/groups](/ja-JP/channels/groups) -## Dashboard control ui の接続性 +## Dashboard control ui接続 -dashboard/control UI が接続できない場合は、URL、認証モード、安全なコンテキスト前提を確認してください。 +dashboard/control UIが接続できない場合は、URL、認証モード、セキュアコンテキスト前提を確認してください。 ```bash openclaw gateway status @@ -150,40 +149,38 @@ openclaw doctor openclaw gateway status --json ``` -確認する点: +確認ポイント: -- probe URL と dashboard URL が正しい。 -- クライアントと Gateway の認証モード/トークンが一致している。 -- デバイス ID が必要な場面で HTTP を使用していない。 +- 正しいprobe URLとdashboard URL。 +- クライアントとGateway間の認証モード/トークン不一致。 +- デバイスIDが必要な場面でHTTPを使用している。 よくあるシグネチャ: -- `device identity required` → 安全でないコンテキスト、または device auth が不足している。 -- `origin not allowed` → ブラウザーの `Origin` が `gateway.controlUi.allowedOrigins` - に入っていない（または、明示的な allowlist なしで非 loopback のブラウザー origin から接続している）。 -- `device nonce required` / `device nonce mismatch` → クライアントが challenge ベースの device auth フロー（`connect.challenge` + `device.nonce`）を完了していない。 -- `device signature invalid` / `device signature expired` → クライアントが現在のハンドシェイクに対して誤ったペイロード（または古いタイムスタンプ）に署名した。 -- `AUTH_TOKEN_MISMATCH` と `canRetryWithDeviceToken=true` → クライアントはキャッシュされた device token で 1 回だけ信頼された再試行ができる。 -- そのキャッシュトークン再試行では、ペアリング済み device token に保存されているキャッシュ済み scope セットが再利用される。明示的な `deviceToken` / 明示的な `scopes` 呼び出し元は、代わりに要求した scope セットを維持する。 -- その再試行パス以外では、接続認証の優先順位は、明示的な共有 - token/password が最初、その次に明示的な `deviceToken`、その次に保存済み device token、最後に bootstrap token。 -- 非同期の Tailscale Serve Control UI パスでは、同じ `{scope, ip}` に対する失敗試行は、リミッターが失敗を記録する前に直列化される。したがって、同じクライアントからの不正な同時再試行 2 件では、単純に 2 件の不一致になるのではなく、2 件目で `retry later` が出ることがある。 -- ブラウザー origin の loopback クライアントから `too many failed authentication attempts (retry later)` → 同じ正規化済み `Origin` からの繰り返し失敗は一時的にロックアウトされる。別の localhost origin は別バケットを使う。 -- その再試行後も `unauthorized` が繰り返される → 共有 token/device token のずれ。トークン設定を更新し、必要に応じて device token を再承認/ローテーションする。 -- `gateway connect failed:` → ホスト/ポート/url の接続先が間違っている。 +- `device identity required` → 非セキュアコンテキスト、またはデバイス認証の欠落。 +- `origin not allowed` → ブラウザーの`Origin`が`gateway.controlUi.allowedOrigins`に含まれていない（または、明示的な許可リストなしでloopback以外のブラウザーoriginから接続している）。 +- `device nonce required` / `device nonce mismatch` → クライアントがチャレンジベースのデバイス認証フロー（`connect.challenge` + `device.nonce`）を完了していない。 +- `device signature invalid` / `device signature expired` → クライアントが現在のハンドシェイクに対して誤ったペイロード（または古いタイムスタンプ）に署名している。 +- `AUTH_TOKEN_MISMATCH` と `canRetryWithDeviceToken=true` → クライアントはキャッシュ済みデバイストークンで1回だけ信頼されたリトライができる。 +- そのキャッシュトークン再試行では、ペアリング済みデバイストークンとともに保存されたキャッシュ済みscopeセットを再利用する。明示的な`deviceToken` / 明示的な`scopes`呼び出し元は、要求したscopeセットをそのまま維持する。 +- その再試行経路以外では、接続認証の優先順位は、まず明示的な共有トークン/パスワード、次に明示的な`deviceToken`、次に保存済みデバイストークン、最後にbootstrapトークン。 +- 非同期のTailscale Serve Control UI経路では、同じ`{scope, ip}`に対する失敗試行は、リミッターが失敗を記録する前に直列化される。したがって、同じクライアントからの誤った並行リトライが2回あると、2回とも単純な不一致ではなく、2回目に`retry later`が出ることがある。 +- ブラウザーoriginのloopbackクライアントからの `too many failed authentication attempts (retry later)` → 同じ正規化された`Origin`からの繰り返し失敗は一時的にロックアウトされる。別のlocalhost originは別バケットを使う。 +- その再試行後も `unauthorized` が繰り返される → 共有トークン/デバイストークンのドリフト。必要に応じてトークン設定を更新し、デバイストークンを再承認/ローテーションする。 +- `gateway connect failed:` → ホスト/ポート/URLターゲットが間違っている。 ### 認証詳細コードのクイックマップ -失敗した `connect` レスポンスの `error.details.code` を使って、次の対応を選んでください: +失敗した`connect`レスポンスの`error.details.code`を使って、次の対応を選んでください。 -| Detail code | 意味 | 推奨対応 | +| Detail code | 意味 | 推奨アクション | | ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | クライアントが必要な共有トークンを送信していない。 | クライアントにトークンを貼り付け/設定して再試行する。dashboard パスでは: `openclaw config get gateway.auth.token` を実行し、その値を Control UI の設定に貼り付ける。 | -| `AUTH_TOKEN_MISMATCH` | 共有トークンが Gateway の認証トークンと一致しなかった。 | `canRetryWithDeviceToken=true` の場合は、信頼された再試行を 1 回許可する。キャッシュトークン再試行では保存済みの承認済み scope が再利用される。明示的な `deviceToken` / `scopes` 呼び出し元は要求した scope を維持する。それでも失敗する場合は、[token drift recovery checklist](/cli/devices#token-drift-recovery-checklist) を実行する。 | -| `AUTH_DEVICE_TOKEN_MISMATCH` | デバイスごとにキャッシュされたトークンが古いか失効している。 | [devices CLI](/cli/devices) を使って device token をローテーション/再承認してから再接続する。 | -| `PAIRING_REQUIRED` | デバイス ID は認識されているが、このロールでは承認されていない。 | 保留中の要求を承認する: `openclaw devices list` を実行し、その後 `openclaw devices approve ` を実行する。 | +| `AUTH_TOKEN_MISSING` | クライアントが必要な共有トークンを送信しなかった。 | クライアントにトークンを貼り付け/設定して再試行する。dashboard経路では: `openclaw config get gateway.auth.token` を実行して、その値をControl UI設定に貼り付ける。 | +| `AUTH_TOKEN_MISMATCH` | 共有トークンがGateway認証トークンと一致しなかった。 | `canRetryWithDeviceToken=true` の場合は、1回だけ信頼された再試行を許可する。キャッシュトークン再試行では保存済みの承認済みscopeを再利用し、明示的な`deviceToken` / `scopes`呼び出し元は要求したscopeを維持する。それでも失敗する場合は、[token drift recovery checklist](/cli/devices#token-drift-recovery-checklist)を実行する。 | +| `AUTH_DEVICE_TOKEN_MISMATCH` | キャッシュされたデバイスごとのトークンが古いか、失効している。 | [devices CLI](/cli/devices)を使ってデバイストークンをローテーション/再承認してから再接続する。 | +| `PAIRING_REQUIRED` | デバイスIDは認識されているが、このロールでは未承認。 | 保留中のリクエストを承認する: `openclaw devices list` を実行し、次に `openclaw devices approve ` を実行する。 | -Device auth v2 の移行確認: +Device auth v2移行チェック: ```bash openclaw --version @@ -191,28 +188,26 @@ openclaw doctor openclaw gateway status ``` -ログに nonce/signature エラーが出ている場合は、接続元クライアントを更新し、次を確認してください: +ログにnonce/signatureエラーがある場合は、接続側クライアントを更新して、次を確認してください。 -1. `connect.challenge` を待つ -2. challenge に束縛されたペイロードに署名する -3. 同じ challenge nonce を使って `connect.params.device.nonce` を送る +1. `connect.challenge` を待機する +2. challengeに紐づいたペイロードに署名する +3. 同じchallenge nonceを使って `connect.params.device.nonce` を送信する `openclaw devices rotate` / `revoke` / `remove` が予期せず拒否される場合: -- paired-device token セッションは、呼び出し元が - `operator.admin` も持っていない限り、**自分自身** のデバイスしか管理できない -- `openclaw devices rotate --scope ...` は、呼び出し元セッションがすでに保有している - operator scope しか要求できない +- ペアリング済みデバイストークンのセッションは、呼び出し元が`operator.admin`も持っていない限り、**自分自身の**デバイスしか管理できない +- `openclaw devices rotate --scope ...` は、呼び出し元セッションがすでに保持しているoperator scopeしか要求できない 関連: - [/web/control-ui](/web/control-ui) -- [/gateway/configuration](/ja-JP/gateway/configuration)（Gateway の認証モード） +- [/gateway/configuration](/ja-JP/gateway/configuration) （Gateway認証モード） - [/gateway/trusted-proxy-auth](/ja-JP/gateway/trusted-proxy-auth) - [/gateway/remote](/ja-JP/gateway/remote) - [/cli/devices](/cli/devices) -## Gateway サービスが動作していない +## Gatewayサービスが実行されていない サービスはインストールされているが、プロセスが起動し続けない場合に使用してください。 @@ -221,23 +216,23 @@ openclaw gateway status openclaw status openclaw logs --follow openclaw doctor -openclaw gateway status --deep # also scan system-level services +openclaw gateway status --deep # システムレベルのサービスもスキャン ``` -確認する点: +確認ポイント: -- `Runtime: stopped` と終了ヒント。 -- サービス設定の不一致（`Config (cli)` と `Config (service)`）。 -- ポート/リスナー競合。 -- `--deep` 使用時の追加の launchd/systemd/schtasks インストール。 +- 終了ヒント付きの `Runtime: stopped`。 +- サービス設定の不一致（`Config (cli)` 対 `Config (service)`）。 +- ポート/リスナーの競合。 +- `--deep` 使用時の余分なlaunchd/systemd/schtasksインストール。 - `Other gateway-like services detected (best effort)` のクリーンアップヒント。 よくあるシグネチャ: -- `Gateway start blocked: set gateway.mode=local` または `existing config is missing gateway.mode` → local Gateway モードが有効ではない、または設定ファイルが上書きされて `gateway.mode` が失われた。修正: 設定で `gateway.mode="local"` を設定するか、`openclaw onboard --mode local` / `openclaw setup` を再実行して、想定される local-mode 設定を再作成する。Podman 経由で OpenClaw を実行している場合、デフォルトの設定パスは `~/.openclaw/openclaw.json` です。 -- `refusing to bind gateway ... without auth` → 有効な Gateway 認証経路（token/password、または設定された trusted-proxy）がない非 loopback bind。 +- `Gateway start blocked: set gateway.mode=local` または `existing config is missing gateway.mode` → local Gatewayモードが有効化されていない、または設定ファイルが壊れて `gateway.mode` が失われている。修正: 設定で `gateway.mode="local"` を設定するか、`openclaw onboard --mode local` / `openclaw setup` を再実行して期待されるlocal-mode設定を再作成する。Podman経由でOpenClawを実行している場合、デフォルトの設定パスは `~/.openclaw/openclaw.json`。 +- `refusing to bind gateway ... without auth` → 有効なGateway認証経路（token/password、または設定されているtrusted-proxy）がないまま、非loopback bindをしようとしている。 - `another gateway instance is already listening` / `EADDRINUSE` → ポート競合。 -- `Other gateway-like services detected (best effort)` → 古い、または並行する launchd/systemd/schtasks ユニットが存在する。ほとんどのセットアップでは、1 台のマシンにつき 1 つの Gateway を維持するべきです。複数必要な場合は、ポート + config/state/workspace を分離してください。[/gateway#multiple-gateways-same-host](/ja-JP/gateway#multiple-gateways-same-host) を参照してください。 +- `Other gateway-like services detected (best effort)` → 古い、または並行するlaunchd/systemd/schtasksユニットが存在する。ほとんどのセットアップでは、1台のマシンにつき1つのGatewayにするべきです。複数必要な場合は、ポート + config/state/workspaceを分離してください。詳細は[/gateway#multiple-gateways-same-host](/ja-JP/gateway#multiple-gateways-same-host)を参照してください。 関連: @@ -245,9 +240,9 @@ openclaw gateway status --deep # also scan system-level services - [/gateway/configuration](/ja-JP/gateway/configuration) - [/gateway/doctor](/ja-JP/gateway/doctor) -## Gateway probe の警告 +## Gateway probeの警告 -`openclaw gateway probe` が何かには到達するが、警告ブロックも表示する場合に使用してください。 +`openclaw gateway probe` が何かに到達しているのに、なお警告ブロックを表示する場合に使用してください。 ```bash openclaw gateway probe @@ -255,17 +250,17 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -確認する点: +確認ポイント: -- JSON 出力の `warnings[].code` と `primaryTargetId`。 -- 警告が SSH フォールバック、複数 Gateway、不足している scope、未解決の auth ref のどれに関するものか。 +- JSON出力内の `warnings[].code` と `primaryTargetId`。 +- 警告がSSHフォールバック、複数Gateway、不足しているscope、または未解決のauth refに関するものかどうか。 よくあるシグネチャ: -- `SSH tunnel failed to start; falling back to direct probes.` → SSH セットアップは失敗したが、コマンドは引き続き設定済み/loopback の直接ターゲットを試行した。 -- `multiple reachable gateways detected` → 複数のターゲットが応答した。通常、これは意図的な複数 Gateway セットアップか、古い/重複したリスナーを意味する。 -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 接続自体は成功したが、詳細 RPC は scope により制限されている。device identity をペアリングするか、`operator.read` を持つ認証情報を使用する。 -- 未解決の `gateway.auth.*` / `gateway.remote.*` SecretRef 警告テキスト → 失敗したターゲットに対するこのコマンド経路では認証情報が利用できなかった。 +- `SSH tunnel failed to start; falling back to direct probes.` → SSHセットアップに失敗したが、コマンドは引き続き設定済み/loopbackターゲットへの直接probeを試した。 +- `multiple reachable gateways detected` → 複数のターゲットが応答した。通常、これは意図的なマルチGateway構成か、古い/重複したリスナーを意味する。 +- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 接続は成功したが、詳細RPCがscope不足で制限されている。デバイスIDをペアリングするか、`operator.read` を持つ認証情報を使用する。 +- 未解決の `gateway.auth.*` / `gateway.remote.*` SecretRef警告テキスト → 失敗したターゲットに対するこのコマンド経路では認証情報を利用できなかった。 関連: @@ -275,7 +270,7 @@ openclaw gateway probe --ssh user@gateway-host ## チャネルは接続済みだがメッセージが流れない -チャネル状態は connected だがメッセージフローが止まっている場合は、ポリシー、権限、チャネル固有の配信ルールに集中してください。 +チャネル状態は接続済みなのにメッセージフローが止まっている場合は、ポリシー、権限、チャネル固有の配信ルールに注目してください。 ```bash openclaw channels status --probe @@ -285,16 +280,16 @@ openclaw logs --follow openclaw config get channels ``` -確認する点: +確認ポイント: -- DM ポリシー（`pairing`、`allowlist`、`open`、`disabled`）。 -- グループ allowlist とメンション要件。 -- チャネル API の権限/scope 不足。 +- DMポリシー（`pairing`、`allowlist`、`open`、`disabled`）。 +- グループ許可リストとメンション要件。 +- 不足しているチャネルAPI権限/scope。 よくあるシグネチャ: -- `mention required` → グループのメンションポリシーによりメッセージが無視された。 -- `pairing` / 保留中の承認トレース → 送信者が承認されていない。 +- `mention required` → グループメンションポリシーによってメッセージが無視されている。 +- `pairing` / 保留中の承認トレース → 送信者が未承認。 - `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → チャネル認証/権限の問題。 関連: @@ -304,9 +299,9 @@ openclaw config get channels - [/channels/telegram](/ja-JP/channels/telegram) - [/channels/discord](/ja-JP/channels/discord) -## Cron と heartbeat の配信 +## Cronとheartbeatの配信 -cron または heartbeat が実行されなかった、あるいは配信されなかった場合は、まず scheduler の状態、その次に配信先を確認してください。 +cronまたはheartbeatが実行されなかった、あるいは配信されなかった場合は、まずschedulerの状態を確認し、その後で配信先を確認してください。 ```bash openclaw cron status @@ -316,21 +311,21 @@ openclaw system heartbeat last openclaw logs --follow ``` -確認する点: +確認ポイント: -- Cron が有効で、次回 wake が存在する。 +- Cronが有効で、次回wakeが存在する。 - ジョブ実行履歴の状態（`ok`、`skipped`、`error`）。 -- heartbeat のスキップ理由（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 +- Heartbeatのskip理由（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 よくあるシグネチャ: -- `cron: scheduler disabled; jobs will not run automatically` → cron が無効。 -- `cron: timer tick failed` → scheduler tick に失敗。ファイル/ログ/ランタイムエラーを確認する。 -- `heartbeat skipped` と `reason=quiet-hours` → アクティブ時間帯の外側。 -- `heartbeat skipped` と `reason=empty-heartbeat-file` → `HEARTBEAT.md` は存在するが、空行または markdown ヘッダーしか含まれていないため、OpenClaw はモデル呼び出しをスキップする。 -- `heartbeat skipped` と `reason=no-tasks-due` → `HEARTBEAT.md` に `tasks:` ブロックはあるが、この tick で期限の来ているタスクがない。 -- `heartbeat: unknown accountId` → heartbeat 配信先の account id が無効。 -- `heartbeat skipped` と `reason=dm-blocked` → heartbeat の宛先が DM 形式の送信先に解決されたが、`agents.defaults.heartbeat.directPolicy`（またはエージェントごとの上書き）が `block` に設定されている。 +- `cron: scheduler disabled; jobs will not run automatically` → cronが無効。 +- `cron: timer tick failed` → scheduler tickに失敗した。ファイル/ログ/ランタイムエラーを確認する。 +- `heartbeat skipped` と `reason=quiet-hours` → アクティブ時間帯の外。 +- `heartbeat skipped` と `reason=empty-heartbeat-file` → `HEARTBEAT.md` は存在するが、空行またはMarkdown見出ししか含まれていないため、OpenClawがモデル呼び出しをスキップしている。 +- `heartbeat skipped` と `reason=no-tasks-due` → `HEARTBEAT.md` に `tasks:` ブロックはあるが、このtick時点で期限の来ているタスクがない。 +- `heartbeat: unknown accountId` → heartbeat配信先として無効なaccount id。 +- `heartbeat skipped` と `reason=dm-blocked` → heartbeatターゲットがDMスタイルの宛先に解決されたが、`agents.defaults.heartbeat.directPolicy`（またはagentごとの上書き）が `block` に設定されている。 関連: @@ -338,9 +333,9 @@ openclaw logs --follow - [/automation/cron-jobs](/ja-JP/automation/cron-jobs) - [/gateway/heartbeat](/ja-JP/gateway/heartbeat) -## ノードのペアリング済みツールが失敗する +## ペアリング済みノードのツールが失敗する -ノードはペアリング済みだがツールが失敗する場合は、フォアグラウンド、権限、承認状態を切り分けてください。 +ノードはペアリングされているのにツールが失敗する場合は、foreground、権限、承認状態を切り分けてください。 ```bash openclaw nodes status @@ -350,18 +345,18 @@ openclaw logs --follow openclaw status ``` -確認する点: +確認ポイント: -- ノードがオンラインで、期待する capabilities を持っている。 -- camera/mic/location/screen に対する OS 権限が付与されている。 -- exec 承認と allowlist の状態。 +- ノードがオンラインで、期待どおりのcapabilityを持っている。 +- camera/mic/location/screenに対するOS権限が付与されている。 +- exec承認とallowlist状態。 よくあるシグネチャ: -- `NODE_BACKGROUND_UNAVAILABLE` → ノードアプリをフォアグラウンドに置く必要がある。 -- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → OS 権限が不足している。 -- `SYSTEM_RUN_DENIED: approval required` → exec 承認が保留中。 -- `SYSTEM_RUN_DENIED: allowlist miss` → コマンドが allowlist によりブロックされた。 +- `NODE_BACKGROUND_UNAVAILABLE` → ノードアプリがforegroundにある必要がある。 +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → OS権限が不足している。 +- `SYSTEM_RUN_DENIED: approval required` → exec承認が保留中。 +- `SYSTEM_RUN_DENIED: allowlist miss` → コマンドがallowlistによりブロックされている。 関連: @@ -369,9 +364,9 @@ openclaw status - [/nodes/index](/ja-JP/nodes/index) - [/tools/exec-approvals](/ja-JP/tools/exec-approvals) -## Browser ツールが失敗する +## Browserツールが失敗する -Gateway 自体は正常なのに browser ツールのアクションが失敗する場合に使用してください。 +Gateway自体は正常なのにbrowserツールのアクションが失敗する場合に使用してください。 ```bash openclaw browser status @@ -381,32 +376,32 @@ openclaw logs --follow openclaw doctor ``` -確認する点: +確認ポイント: -- `plugins.allow` が設定されており、`browser` を含んでいるか。 -- browser executable path が有効か。 -- CDP profile に到達できるか。 -- `existing-session` / `user` profile でローカル Chrome が利用可能か。 +- `plugins.allow` が設定されていて、`browser` を含んでいるかどうか。 +- 有効なbrowser executable path。 +- CDP profileへの到達可能性。 +- `existing-session` / `user` profile向けのローカルChromeの可用性。 よくあるシグネチャ: -- `unknown command "browser"` または `unknown command 'browser'` → バンドルされた browser plugin が `plugins.allow` によって除外されている。 -- `browser.enabled=true` なのに browser ツールが見つからない / 利用不可 → `plugins.allow` が `browser` を除外しているため、plugin が読み込まれていない。 -- `Failed to start Chrome CDP on port` → browser プロセスの起動に失敗した。 +- `unknown command "browser"` または `unknown command 'browser'` → バンドルされたbrowserプラグインが `plugins.allow` によって除外されている。 +- `browser.enabled=true` なのにbrowserツールが見つからない / 利用できない → `plugins.allow` が `browser` を除外しているため、プラグインが読み込まれていない。 +- `Failed to start Chrome CDP on port` → browserプロセスの起動に失敗した。 - `browser.executablePath not found` → 設定されたパスが無効。 -- `browser.cdpUrl must be http(s) or ws(s)` → 設定された CDP URL が `file:` や `ftp:` など未対応のスキームを使用している。 -- `browser.cdpUrl has invalid port` → 設定された CDP URL のポートが不正または範囲外。 -- `No Chrome tabs found for profile="user"` → Chrome MCP attach profile にローカルの開いている Chrome タブがない。 -- `Remote CDP for profile "" is not reachable` → 設定されたリモート CDP エンドポイントに Gateway ホストから到達できない。 -- `Browser attachOnly is enabled ... not reachable` または `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile に到達可能なターゲットがない、または HTTP エンドポイントは応答しても CDP WebSocket を依然として開けない。 -- `Playwright is not available in this gateway build; '' is unsupported.` → 現在の Gateway インストールには完全な Playwright パッケージが含まれていない。ARIA スナップショットや基本的なページスクリーンショットは動作する場合があるが、ナビゲーション、AI スナップショット、CSS セレクターによる要素スクリーンショット、PDF エクスポートは利用できない。 -- `fullPage is not supported for element screenshots` → スクリーンショット要求で `--full-page` と `--ref` または `--element` を混在させている。 -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` のスクリーンショット呼び出しでは、CSS の `--element` ではなくページキャプチャまたはスナップショットの `--ref` を使う必要がある。 -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP のアップロードフックには CSS セレクターではなくスナップショット ref が必要。 -- `existing-session file uploads currently support one file at a time.` → Chrome MCP profile では、アップロードは 1 回の呼び出しにつき 1 ファイルだけ送信する。 -- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP profile のダイアログフックでは timeout の上書きがサポートされていない。 -- `response body is not supported for existing-session profiles yet.` → `responsebody` は依然として managed browser または raw CDP profile が必要。 -- attach-only または remote CDP profile で viewport / dark-mode / locale / offline の上書きが古い状態のまま残っている → `openclaw browser stop --browser-profile ` を実行し、アクティブな制御セッションを閉じて、Gateway 全体を再起動せずに Playwright/CDP のエミュレーション状態を解放する。 +- `browser.cdpUrl must be http(s) or ws(s)` → 設定されたCDP URLが `file:` や `ftp:` のような未対応スキームを使用している。 +- `browser.cdpUrl has invalid port` → 設定されたCDP URLのポートが不正、または範囲外。 +- `No Chrome tabs found for profile="user"` → Chrome MCP attach profileに開いているローカルChromeタブがない。 +- `Remote CDP for profile "" is not reachable` → 設定されたリモートCDP endpointにGatewayホストから到達できない。 +- `Browser attachOnly is enabled ... not reachable` または `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profileに到達可能なターゲットがない、またはHTTP endpointは応答したがCDP WebSocketをまだ開けなかった。 +- `Playwright is not available in this gateway build; '' is unsupported.` → 現在のGatewayインストールには完全なPlaywrightパッケージが含まれていない。ARIAスナップショットと基本的なページスクリーンショットは引き続き動作する可能性があるが、ナビゲーション、AIスナップショット、CSSセレクターの要素スクリーンショット、PDFエクスポートは利用できない。 +- `fullPage is not supported for element screenshots` → スクリーンショット要求で `--full-page` と `--ref` または `--element` が混在していた。 +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` のスクリーンショット呼び出しでは、CSS `--element` ではなくページキャプチャまたはスナップショット `--ref` を使う必要がある。 +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCPアップロードフックでは、CSSセレクターではなくスナップショットrefが必要。 +- `existing-session file uploads currently support one file at a time.` → Chrome MCP profileでは、1回の呼び出しにつき1つのアップロードだけを送信する。 +- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP profileのdialogフックはtimeout上書きをサポートしていない。 +- `response body is not supported for existing-session profiles yet.` → `responsebody` はまだmanaged browserまたはraw CDP profileを必要とする。 +- attach-onlyまたはremote CDP profileでviewport / dark-mode / locale / offline上書きが古いまま残っている → `openclaw browser stop --browser-profile ` を実行して、Gateway全体を再起動せずにアクティブなcontrol sessionを閉じ、Playwright/CDPエミュレーション状態を解放する。 関連: @@ -415,9 +410,9 @@ openclaw doctor ## アップグレード後に突然何かが壊れた場合 -アップグレード後の破損の多くは、設定のずれか、より厳格なデフォルトが適用されるようになったことが原因です。 +アップグレード後の不具合の多くは、設定のドリフトか、より厳格なデフォルトが現在適用されていることが原因です。 -### 1) 認証と URL 上書き動作が変わった +### 1) 認証とURL上書きの動作が変わった ```bash openclaw gateway status @@ -426,17 +421,17 @@ openclaw config get gateway.remote.url openclaw config get gateway.auth.mode ``` -確認する点: +確認事項: -- `gateway.mode=remote` の場合、CLI 呼び出しがリモートを対象にしている一方で、ローカルサービス自体は正常なことがある。 -- 明示的な `--url` 呼び出しは保存済み認証情報にフォールバックしない。 +- `gateway.mode=remote` の場合、ローカルサービスは正常でもCLI呼び出しがremoteを対象にしている可能性がある。 +- 明示的な `--url` 呼び出しは保存済み認証情報へフォールバックしない。 よくあるシグネチャ: -- `gateway connect failed:` → URL の接続先が間違っている。 -- `unauthorized` → エンドポイントには到達しているが認証が間違っている。 +- `gateway connect failed:` → URLターゲットが間違っている。 +- `unauthorized` → endpointには到達しているが認証が間違っている。 -### 2) bind と auth のガードレールがより厳格になった +### 2) bindとauthのガードレールがより厳格になった ```bash openclaw config get gateway.bind @@ -446,17 +441,17 @@ openclaw gateway status openclaw logs --follow ``` -確認する点: +確認事項: -- 非 loopback bind（`lan`、`tailnet`、`custom`）には、有効な Gateway 認証経路が必要: 共有 token/password 認証、または正しく設定された非 loopback の `trusted-proxy` デプロイメント。 +- 非loopback bind（`lan`、`tailnet`、`custom`）には、有効なGateway認証経路が必要: 共有token/password認証、または正しく設定された非loopbackの`trusted-proxy`デプロイ。 - `gateway.token` のような古いキーは `gateway.auth.token` の代わりにはならない。 よくあるシグネチャ: -- `refusing to bind gateway ... without auth` → 有効な Gateway 認証経路がない非 loopback bind。 -- ランタイムは動作中なのに `RPC probe: failed` → Gateway は生きているが、現在の auth/url ではアクセスできない。 +- `refusing to bind gateway ... without auth` → 有効なGateway認証経路なしで非loopback bindしようとしている。 +- ランタイムは実行中なのに `RPC probe: failed` → Gatewayは生きているが、現在のauth/urlではアクセスできない。 -### 3) ペアリングと device identity の状態が変わった +### 3) ペアリングとデバイスIDの状態が変わった ```bash openclaw devices list @@ -465,17 +460,17 @@ openclaw logs --follow openclaw doctor ``` -確認する点: +確認事項: -- dashboard/nodes の保留中 device 承認。 -- ポリシーまたは identity の変更後に保留中になっている DM pairing 承認。 +- dashboard/nodes向けの保留中デバイス承認。 +- ポリシーまたはID変更後の保留中DMペアリング承認。 よくあるシグネチャ: -- `device identity required` → device auth 要件が満たされていない。 +- `device identity required` → デバイス認証が満たされていない。 - `pairing required` → 送信者/デバイスの承認が必要。 -確認後もサービス設定とランタイムが一致しない場合は、同じ profile/state ディレクトリーからサービスメタデータを再インストールしてください。 +確認後もサービス設定とランタイムが一致しない場合は、同じprofile/state directoryからサービスメタデータを再インストールしてください。 ```bash openclaw gateway install --force diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index 572af55f4..651a146f9 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -1,53 +1,53 @@ --- read_when: - ローカルまたはCIでテストを実行する - - モデル/プロバイダーのバグに対する回帰テストの追加 + - モデル/プロバイダーのバグに対する回帰テストを追加する - Gateway + エージェントの動作をデバッグする -summary: 'テストキット: unit/e2e/liveスイート、Dockerランナー、各テストがカバーする内容' -title: テスト中 +summary: 'テストキット: unit/e2e/liveスイート、Dockerランナー、および各テストでカバーされる内容' +title: テスト x-i18n: - generated_at: "2026-04-10T04:43:41Z" + generated_at: "2026-04-11T02:45:31Z" model: gpt-5.4 provider: openai - source_hash: 21b78e59a5189f4e8e6e1b490d350f4735c0395da31d21fc5d10b825313026b4 + source_hash: 55e75d056306a77b0d112a3902c08c7771f53533250847fc3d785b1df3e0e9e7 source_path: help/testing.md workflow: 15 --- # テスト -OpenClawには3つのVitestスイート（unit/integration、e2e、live）と、少数のDockerランナーがあります。 +OpenClawには3つのVitestスイート（unit/integration、e2e、live）と、小規模なDockerランナー群があります。 このドキュメントは「どのようにテストするか」のガイドです。 -- 各スイートが何をカバーするか（そして意図的に何を _カバーしないか_） -- 一般的なワークフロー（ローカル、push前、デバッグ）で実行するコマンド +- 各スイートが何をカバーするか（そして意図的に何をカバーしないか） +- 一般的なワークフロー（ローカル、push前、デバッグ）でどのコマンドを実行するか - liveテストがどのように認証情報を検出し、モデル/プロバイダーを選択するか -- 実際のモデル/プロバイダーの問題に対する回帰テストを追加する方法 +- 実運用で発生したモデル/プロバイダーの問題に対する回帰テストをどう追加するか ## クイックスタート -ほとんどの日は次で十分です。 +たいていの日は次を使います。 - フルゲート（push前に想定）: `pnpm build && pnpm check && pnpm test` -- 余裕のあるマシンでの高速なローカル全スイート実行: `pnpm test:max` -- 直接Vitestのwatchループを使う: `pnpm test:watch` -- 直接ファイル指定はextension/channelのパスにも対応するようになりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 単一の失敗を反復しているときは、まず対象を絞った実行を優先してください。 +- 余裕のあるマシンでのより高速なローカルフルスイート実行: `pnpm test:max` +- 直接のVitestウォッチループ: `pnpm test:watch` +- 直接のファイル指定は、extension/channelパスにも対応するようになりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 単一の失敗を反復修正しているときは、まず対象を絞った実行を優先してください。 - DockerベースのQAサイト: `pnpm qa:lab:up` - Linux VMベースのQAレーン: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -テストに触れたときや、追加の確信がほしいとき: +テストに手を入れたとき、または追加の確信がほしいとき: - カバレッジゲート: `pnpm test:coverage` - E2Eスイート: `pnpm test:e2e` 実際のプロバイダー/モデルをデバッグするとき（実際の認証情報が必要）: -- liveスイート（モデル + Gatewayのtool/imageプローブ）: `pnpm test:live` +- liveスイート（モデル + Gatewayツール/画像プローブ）: `pnpm test:live` - 1つのliveファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -ヒント: 必要なのが1つの失敗ケースだけなら、以下で説明するallowlist環境変数を使ってliveテストを絞り込むのを優先してください。 +ヒント: 必要なのが1つの失敗ケースだけなら、以下で説明するallowlist環境変数でliveテストを絞り込むことを優先してください。 ## QA専用ランナー @@ -55,103 +55,124 @@ OpenClawには3つのVitestスイート（unit/integration、e2e、live）と、 - `pnpm openclaw qa suite` - リポジトリベースのQAシナリオをホスト上で直接実行します。 + - デフォルトでは、分離されたgatewayワーカーで複数の選択シナリオを並列実行します。最大64ワーカーまたは選択したシナリオ数までです。ワーカー数を調整するには`--concurrency `を使用し、以前の直列レーンにするには`--concurrency 1`を使用してください。 - `pnpm openclaw qa suite --runner multipass` - 同じQAスイートを使い捨てのMultipass Linux VM内で実行します。 - - ホスト上の`qa suite`と同じシナリオ選択の挙動を維持します。 + - ホスト上の`qa suite`と同じシナリオ選択動作を維持します。 - `qa suite`と同じプロバイダー/モデル選択フラグを再利用します。 - - live実行では、ゲストで現実的に扱える対応QA認証入力を転送します: - 環境変数ベースのプロバイダーキー、QA liveプロバイダー設定パス、存在する場合の`CODEX_HOME`。 - - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に維持する必要があります。 - - 通常のQAレポート + サマリーに加えて、Multipassログを`.artifacts/qa-e2e/...`配下に書き込みます。 + - live実行では、ゲストで実用的なサポート対象QA認証入力を転送します: + 環境変数ベースのプロバイダーキー、QA liveプロバイダー設定パス、存在する場合は`CODEX_HOME`。 + - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に保つ必要があります。 + - 通常のQAレポート + サマリーに加え、Multipassログを`.artifacts/qa-e2e/...`配下に書き込みます。 - `pnpm qa:lab:up` - - オペレーター形式のQA作業向けに、DockerベースのQAサイトを起動します。 + - オペレーター型QA作業向けにDockerベースのQAサイトを起動します。 +- `pnpm openclaw qa matrix` + - 使い捨てのDockerベースTuwunel homeserverに対して、Matrix live QAレーンを実行します。 + - 一時的な3人のMatrixユーザー（`driver`、`sut`、`observer`）と1つのプライベートルームをプロビジョニングし、その後、実際のMatrix pluginをSUTトランスポートとして使うQA gateway子プロセスを起動します。 + - デフォルトでは固定された安定版Tuwunelイメージ`ghcr.io/matrix-construct/tuwunel:v1.5.1`を使用します。別のイメージをテストする必要がある場合は`OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`で上書きしてください。 + - Matrix QAレポート、サマリー、およびobserved-eventsアーティファクトを`.artifacts/qa-e2e/...`配下に書き込みます。 +- `pnpm openclaw qa telegram` + - 環境変数から取得したdriverおよびSUTボットトークンを使って、実際のプライベートグループに対してTelegram live QAレーンを実行します。 + - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`が必要です。グループIDは数値のTelegramチャットIDである必要があります。 + - 同じプライベートグループ内に2つの異なるボットが必要で、SUTボットはTelegramユーザー名を公開している必要があります。 + - 安定したbot間観測のため、両方のボットで`@BotFather`のBot-to-Bot Communication Modeを有効にし、driverボットがグループ内ボットトラフィックを観測できることを確認してください。 + - Telegram QAレポート、サマリー、およびobserved-messagesアーティファクトを`.artifacts/qa-e2e/...`配下に書き込みます。 -## テストスイート（どこで何が動くか） +liveトランスポートレーンは、新しいトランスポートがずれないように、1つの標準コントラクトを共有します。 -スイートは「現実性が高くなるほど、flakiness/コストも増える」と考えてください。 +`qa-channel`は引き続き広範な合成QAスイートであり、liveトランスポートのカバレッジマトリクスには含まれません。 + +| レーン | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | +| --------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | + +## テストスイート（どこで何が実行されるか） + +スイートは「現実性が増していくもの」（そして不安定さ/コストも増していくもの）として考えてください。 ### Unit / integration（デフォルト） - コマンド: `pnpm test` -- 設定: 既存のスコープ付きVitestプロジェクトに対する10個の順次シャード実行（`vitest.full-*.config.ts`） -- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`配下のcore/unitインベントリと、`vitest.unit.config.ts`でカバーされる許可済みの`ui` nodeテスト -- スコープ: - - 純粋なunitテスト - - プロセス内integrationテスト（Gateway認証、ルーティング、tooling、パース、設定） - - 既知バグに対する決定論的な回帰テスト -- 想定: +- 設定: 既存のスコープ付きVitestプロジェクトに対する10個の逐次シャード実行（`vitest.full-*.config.ts`） +- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`配下のcore/unitインベントリと、`vitest.unit.config.ts`でカバーされるホワイトリスト化された`ui`のnodeテスト +- 範囲: + - 純粋なユニットテスト + - プロセス内統合テスト（gateway認証、ルーティング、ツーリング、パース、設定） + - 既知のバグに対する決定的な回帰テスト +- 期待事項: - CIで実行される - 実際のキーは不要 - - 高速で安定しているべき -- プロジェクトに関する補足: - - 対象指定なしの`pnpm test`は、巨大な単一のネイティブルートプロジェクトプロセスではなく、11個の小さなシャード設定（`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`）を実行するようになりました。これにより、負荷の高いマシンでのピークRSSを削減し、auto-reply/extension作業が無関係なスイートを圧迫するのを防ぎます。 - - `pnpm test --watch`は、マルチシャードのwatchループが現実的でないため、引き続きネイティブルートの`vitest.config.ts`プロジェクトグラフを使用します。 - - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports`は、明示的なファイル/ディレクトリ指定をまずスコープ付きレーンにルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`ではフルルートプロジェクト起動のコストを回避できます。 - - `pnpm test:changed`は、差分がルーティング可能なソース/テストファイルのみに触れている場合、変更されたgitパスを同じスコープ付きレーンに展開します。設定/セットアップの編集は引き続き広範なルートプロジェクト再実行にフォールバックします。 - - 一部の`plugin-sdk`および`commands`テストも、`test/setup-openclaw-runtime.ts`をスキップする専用の軽量レーンを通るようにルーティングされます。stateful/runtime-heavyなファイルは既存のレーンに残ります。 - - 一部の`plugin-sdk`および`commands`のヘルパーソースファイルも、changedモード実行をそれらの軽量レーン内の明示的な兄弟テストにマッピングするため、ヘルパー編集でそのディレクトリの重い全スイートを再実行せずに済みます。 - - `auto-reply`には現在、3つの専用バケットがあります: トップレベルのcoreヘルパー、トップレベルの`reply.*` integrationテスト、`src/auto-reply/reply/**`サブツリーです。これにより、最も重いreplyハーネスの処理を軽量なstatus/chunk/tokenテストから切り離せます。 -- 埋め込みランナーに関する補足: - - メッセージtool検出入力またはcompactionランタイムコンテキストを変更する場合は、両方のレベルのカバレッジを維持してください。 - - 純粋なルーティング/正規化境界に対して、焦点を絞ったヘルパー回帰テストを追加してください。 - - 加えて、埋め込みランナーintegrationスイートも健全に保ってください: + - 高速かつ安定しているべき +- プロジェクトに関する注記: + - 対象未指定の`pnpm test`は、1つの巨大なネイティブルートプロジェクトプロセスではなく、11個の小さなシャード設定（`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`）を実行するようになりました。これにより、負荷の高いマシンでのピークRSSが削減され、auto-reply/extensionの作業が無関係なスイートを圧迫するのを防ぎます。 + - `pnpm test --watch`は、マルチシャードのウォッチループが現実的ではないため、引き続きネイティブルート`vitest.config.ts`プロジェクトグラフを使います。 + - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports`は、明示的なファイル/ディレクトリ対象をまずスコープ付きレーン経由でルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`ではルートプロジェクト全体の起動コストを払わずに済みます。 + - `pnpm test:changed`は、差分がルーティング可能なソース/テストファイルだけに触れている場合、変更されたgitパスを同じスコープ付きレーンに展開します。設定/セットアップの編集は、引き続き広範なルートプロジェクト再実行にフォールバックします。 + - agents、commands、plugins、auto-replyヘルパー、`plugin-sdk`、および同様の純粋なユーティリティ領域からの軽量importユニットテストは、`test/setup-openclaw-runtime.ts`をスキップする`unit-fast`レーンを通ります。状態を持つ/ランタイム負荷の高いファイルは既存レーンに残ります。 + - 一部の`plugin-sdk`および`commands`ヘルパーソースファイルは、変更モード実行をそれらの軽量レーン内の明示的な隣接テストにもマッピングするため、ヘルパー編集でそのディレクトリの重いフルスイートを再実行せずに済みます。 + - `auto-reply`には現在3つの専用バケットがあります: トップレベルcoreヘルパー、トップレベル`reply.*`統合テスト、`src/auto-reply/reply/**`サブツリー。これにより、最も重いreplyハーネス作業を軽量なstatus/chunk/tokenテストから切り離せます。 +- 組み込みランナーに関する注記: + - メッセージツール検出入力またはcompactionランタイムコンテキストを変更する場合は、両方のレベルのカバレッジを維持してください。 + - 純粋なルーティング/正規化境界については、焦点を絞ったヘルパー回帰テストを追加してください。 + - また、組み込みランナーの統合スイートも健全に保ってください: `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`、および `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - これらのスイートは、スコープ付きidとcompactionの挙動が実際の`run.ts` / `compact.ts`経路を通って引き続き流れることを検証します。ヘルパーだけのテストは、これらのintegration経路の十分な代替にはなりません。 -- プールに関する補足: - - ベースのVitest設定は現在デフォルトで`threads`を使用します。 - - 共通のVitest設定では`isolate: false`も固定されており、ルートプロジェクト、e2e、live設定全体で非分離ランナーを使用します。 - - ルートUIレーンはその`jsdom`セットアップとoptimizerを維持しつつ、共通の非分離ランナー上で実行されるようになりました。 - - 各`pnpm test`シャードは、共通のVitest設定から同じ`threads` + `isolate: false`のデフォルトを継承します。 - - 共通の`scripts/run-vitest.mjs`ランチャーは、大規模なローカル実行中のV8コンパイル負荷を減らすため、Vitestの子Nodeプロセスにデフォルトで`--no-maglev`も追加するようになりました。標準のV8挙動と比較したい場合は、`OPENCLAW_VITEST_ENABLE_MAGLEV=1`を設定してください。 -- 高速なローカル反復に関する補足: - - `pnpm test:changed`は、変更パスがより小さいスイートにきれいに対応する場合、スコープ付きレーンを通してルーティングします。 - - `pnpm test:max`および`pnpm test:changed:max`も同じルーティング挙動を維持しつつ、ワーカー上限だけを高くします。 - - ローカルワーカーの自動スケーリングは現在意図的に保守的で、ホストのロードアベレージがすでに高い場合にも抑制されるため、複数のVitest実行が同時に走ってもデフォルトで被害が少なくなります。 - - ベースのVitest設定は、テスト配線が変わったときにもchangedモードの再実行が正しくなるよう、プロジェクト/設定ファイルを`forceRerunTriggers`としてマークします。 - - 設定は、対応ホスト上で`OPENCLAW_VITEST_FS_MODULE_CACHE`を有効に維持します。直接プロファイリング用に明示的なキャッシュ場所を1つ指定したい場合は、`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`を設定してください。 -- パフォーマンスデバッグに関する補足: - - `pnpm test:perf:imports`は、Vitestのimport時間レポートとimport内訳出力を有効にします。 - - `pnpm test:perf:imports:changed`は、`origin/main`以降で変更されたファイルに同じプロファイリングビューを絞り込みます。 -- `pnpm test:perf:changed:bench -- --ref `は、そのコミット済み差分に対してルーティングされた`test:changed`とネイティブルートプロジェクト経路を比較し、wall timeとmacOS max RSSを出力します。 -- `pnpm test:perf:changed:bench -- --worktree`は、変更されたファイル一覧を`scripts/test-projects.mjs`とルートVitest設定に通すことで、現在のdirty treeをベンチマークします。 - - `pnpm test:perf:profile:main`は、Vitest/Viteの起動とtransformオーバーヘッドに対するメインスレッドCPUプロファイルを書き出します。 - - `pnpm test:perf:profile:runner`は、ファイル並列を無効にしたunitスイート向けのランナーCPU+heapプロファイルを書き出します。 + - これらのスイートは、スコープ付きIDとcompaction動作が実際の`run.ts` / `compact.ts`経路を通って流れ続けることを検証します。ヘルパーのみのテストは、これらの統合経路の十分な代替にはなりません。 +- プールに関する注記: + - ベースVitest設定は現在デフォルトで`threads`です。 + - 共有Vitest設定は`isolate: false`も固定し、root projects、e2e、live設定全体で非分離ランナーを使用します。 + - ルートUIレーンはその`jsdom`セットアップとオプティマイザーを維持しますが、現在は共有の非分離ランナー上でも動作します。 + - 各`pnpm test`シャードは、共有Vitest設定から同じ`threads` + `isolate: false`デフォルトを継承します。 + - 共有`scripts/run-vitest.mjs`ランチャーは、大規模なローカル実行中のV8コンパイル負荷を減らすため、Vitest子Nodeプロセスに対してデフォルトで`--no-maglev`も追加するようになりました。標準V8動作と比較したい場合は`OPENCLAW_VITEST_ENABLE_MAGLEV=1`を設定してください。 +- 高速ローカル反復に関する注記: + - `pnpm test:changed`は、変更パスがより小さなスイートにきれいに対応する場合、スコープ付きレーンを経由します。 + - `pnpm test:max`と`pnpm test:changed:max`も同じルーティング動作を維持しつつ、ワーカー上限を高くします。 + - ローカルワーカー自動スケーリングは現在意図的に保守的で、ホストのロードアベレージがすでに高い場合にも抑制されるため、複数のVitest実行が同時に走っても通常は影響が小さくなります。 + - ベースVitest設定は、変更モード再実行がテスト配線の変更時にも正しく保たれるよう、projects/configファイルを`forceRerunTriggers`としてマークします。 + - 設定は、サポートされるホストで`OPENCLAW_VITEST_FS_MODULE_CACHE`を有効に保ちます。直接プロファイリング用に明示的なキャッシュ場所を1つ指定したい場合は`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`を設定してください。 +- パフォーマンスデバッグに関する注記: + - `pnpm test:perf:imports`はVitestのimport所要時間レポートとimport内訳出力を有効にします。 + - `pnpm test:perf:imports:changed`は、`origin/main`以降に変更されたファイルに対して同じプロファイリング表示を絞り込みます。 +- `pnpm test:perf:changed:bench -- --ref `は、そのコミット済み差分に対してルーティングされた`test:changed`とネイティブルートプロジェクト経路を比較し、wall timeとmacOS max RSSを表示します。 +- `pnpm test:perf:changed:bench -- --worktree`は、変更中の現在ツリーを`script/test-projects.mjs`とルートVitest設定経由で変更ファイル一覧にルーティングしてベンチマークします。 + - `pnpm test:perf:profile:main`は、Vitest/Vite起動とtransformオーバーヘッドのmain-thread CPUプロファイルを書き出します。 + - `pnpm test:perf:profile:runner`は、ファイル並列を無効にしたunitスイート用のrunner CPU+heapプロファイルを書き出します。 -### E2E（Gatewayスモーク） +### E2E（gatewayスモーク） - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` -- ファイル: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- ランタイムデフォルト: - - リポジトリ全体の他の部分と同様に、Vitestの`threads`と`isolate: false`を使用します。 - - 適応型ワーカーを使用します（CI: 最大2、ローカル: デフォルトで1）。 - - コンソールI/Oオーバーヘッドを減らすため、デフォルトでsilentモードで実行されます。 +- ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts` +- ランタイムのデフォルト: + - リポジトリの他部分と同様に、Vitest `threads`と`isolate: false`を使用します。 + - 適応型ワーカーを使用します（CI: 最大2、ローカル: デフォルト1）。 + - コンソールI/Oのオーバーヘッドを減らすため、デフォルトでsilent modeで実行されます。 - 便利なオーバーライド: - - ワーカー数を強制するには`OPENCLAW_E2E_WORKERS=`（上限16）。 - - 詳細なコンソール出力を再有効化するには`OPENCLAW_E2E_VERBOSE=1`。 -- スコープ: - - 複数インスタンスのGatewayエンドツーエンド挙動 - - WebSocket/HTTPサーフェス、ノードペアリング、より重いネットワーキング -- 想定: + - ワーカー数を強制するには`OPENCLAW_E2E_WORKERS=`（上限16） + - 詳細なコンソール出力を再有効化するには`OPENCLAW_E2E_VERBOSE=1` +- 範囲: + - 複数インスタンスgatewayのエンドツーエンド動作 + - WebSocket/HTTPサーフェス、ノードペアリング、およびより重いネットワーキング +- 期待事項: - CIで実行される（パイプラインで有効な場合） - 実際のキーは不要 - - unitテストより可動部分が多い（遅くなることがある） + - ユニットテストより可動部が多い（遅くなることがある） ### E2E: OpenShellバックエンドスモーク - コマンド: `pnpm test:e2e:openshell` - ファイル: `test/openshell-sandbox.e2e.test.ts` -- スコープ: - - Docker経由でホスト上に分離されたOpenShell Gatewayを起動 +- 範囲: + - Docker経由でホスト上に分離されたOpenShell gatewayを起動 - 一時的なローカルDockerfileからsandboxを作成 - 実際の`sandbox ssh-config` + SSH execを通じてOpenClawのOpenShellバックエンドを実行 - - sandbox fs bridgeを通じてリモート正準ファイルシステムの挙動を検証 -- 想定: - - オプトインのみ。デフォルトの`pnpm test:e2e`実行には含まれない - - ローカルの`openshell` CLIと動作するDocker daemonが必要 - - 分離された`HOME` / `XDG_CONFIG_HOME`を使用し、その後テスト用Gatewayとsandboxを破棄する + - sandbox fs bridgeを通じてリモート正規filesystem動作を検証 +- 期待事項: + - オプトイン専用であり、デフォルトの`pnpm test:e2e`実行には含まれない + - ローカルの`openshell` CLIと動作するDockerデーモンが必要 + - 分離された`HOME` / `XDG_CONFIG_HOME`を使用し、その後テストgatewayとsandboxを破棄する - 便利なオーバーライド: - より広いe2eスイートを手動実行するときにテストを有効化するには`OPENCLAW_E2E_OPENSHELL=1` - デフォルト以外のCLIバイナリまたはラッパースクリプトを指定するには`OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` @@ -162,262 +183,264 @@ OpenClawには3つのVitestスイート（unit/integration、e2e、live）と、 - 設定: `vitest.live.config.ts` - ファイル: `src/**/*.live.test.ts` - デフォルト: `pnpm test:live`で**有効**（`OPENCLAW_LIVE_TEST=1`を設定） -- スコープ: - - 「このプロバイダー/モデルは、実際の認証情報で _今日_ 本当に動くか？」 - - プロバイダー形式の変更、tool-callingの癖、認証問題、レート制限の挙動を検出 -- 想定: - - 設計上CIで安定しない（実ネットワーク、実プロバイダーポリシー、クォータ、障害） +- 範囲: + - 「このprovider/modelは、実際の認証情報で、_今日_実際に動くか？」 + - providerのフォーマット変更、tool-callingの癖、認証の問題、レート制限の挙動を検出 +- 期待事項: + - 設計上、CIで安定するものではない（実ネットワーク、実際のproviderポリシー、クォータ、障害） - コストがかかる / レート制限を消費する - - 「すべて」より、絞り込んだサブセット実行を優先 -- live実行は、不足しているAPIキーを取り込むために`~/.profile`を読み込みます。 -- デフォルトでは、live実行は引き続き`HOME`を分離し、設定/認証マテリアルを一時的なテストホームにコピーするため、unitフィクスチャが実際の`~/.openclaw`を変更できません。 -- liveテストで意図的に実際のホームディレクトリを使う必要がある場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1`を設定してください。 -- `pnpm test:live`は現在、より静かなモードがデフォルトです: `[live] ...`の進行出力は維持しますが、追加の`~/.profile`通知を抑制し、Gateway起動ログ/Bonjour chatterをミュートします。完全な起動ログを再表示したい場合は、`OPENCLAW_LIVE_TEST_QUIET=0`を設定してください。 -- APIキーのローテーション（プロバイダー別）: カンマ/セミコロン形式の`*_API_KEYS`または`*_API_KEY_1`、`*_API_KEY_2`を設定します（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）。あるいは、liveごとの上書きとして`OPENCLAW_LIVE_*_KEY`を使います。テストはレート制限レスポンス時にリトライします。 -- 進行状況/ハートビート出力: - - liveスイートは現在、長いプロバイダー呼び出し中でもVitestのコンソールキャプチャが静かなときにアクティブ状態が見えるよう、進行行をstderrに出力します。 - - `vitest.live.config.ts`はVitestのコンソールインターセプトを無効化するため、プロバイダー/Gatewayの進行行がlive実行中に即座にストリームされます。 - - 直接モデルのハートビートを調整するには`OPENCLAW_LIVE_HEARTBEAT_MS`。 - - Gateway/プローブのハートビートを調整するには`OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`。 + - 「全部」を実行するより、絞り込んだサブセットを優先する +- live実行では、不足しているAPIキーを取得するために`~/.profile`を読み込みます。 +- デフォルトでは、live実行は引き続き`HOME`を分離し、設定/認証情報を一時的なテスト用homeにコピーするため、unit用fixtureが実際の`~/.openclaw`を変更できません。 +- liveテストで意図的に実際のhomeディレクトリを使う必要がある場合のみ、`OPENCLAW_LIVE_USE_REAL_HOME=1`を設定してください。 +- `pnpm test:live`は現在、より静かなモードがデフォルトです。`[live] ...`の進行状況出力は維持しますが、追加の`~/.profile`通知は抑制し、gateway起動ログ/Bonjour chatterをミュートします。完全な起動ログを再表示したい場合は`OPENCLAW_LIVE_TEST_QUIET=0`を設定してください。 +- APIキーのローテーション（provider別）: カンマ/セミコロン形式の`*_API_KEYS`、または`*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）を設定するか、live専用のオーバーライドとして`OPENCLAW_LIVE_*_KEY`を使います。テストはレート制限レスポンス時に再試行します。 +- 進行状況/heartbeat出力: + - liveスイートは現在、stderrに進行状況行を出力するため、Vitestのコンソールキャプチャが静かでも、長いprovider呼び出しが動作中であることが見えるようになっています。 + - `vitest.live.config.ts`はVitestのコンソール割り込みを無効にしているため、provider/gatewayの進行状況行がlive実行中に即座にストリームされます。 + - 直接モデルのheartbeatは`OPENCLAW_LIVE_HEARTBEAT_MS`で調整します。 + - gateway/probeのheartbeatは`OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`で調整します。 ## どのスイートを実行すべきか？ この判断表を使ってください。 -- ロジック/テストを編集している: `pnpm test`を実行する（大きく変更したなら`pnpm test:coverage`も） -- Gatewayのネットワーキング / WSプロトコル / ペアリングに触れている: `pnpm test:e2e`も追加する -- 「ボットが落ちている」/ プロバイダー固有の障害 / tool callingをデバッグしている: 絞り込んだ`pnpm test:live`を実行する +- ロジック/テストを編集した: `pnpm test`を実行（大きく変更したなら`pnpm test:coverage`も） +- gatewayネットワーキング / WSプロトコル / ペアリングに触れた: `pnpm test:e2e`も追加 +- 「botが落ちている」 / provider固有の失敗 / tool callingをデバッグしている: 絞り込んだ`pnpm test:live`を実行 ## Live: Androidノード機能スイープ - テスト: `src/gateway/android-node.capabilities.live.test.ts` - スクリプト: `pnpm android:test:integration` -- 目的: 接続されたAndroidノードが**現在公開しているすべてのコマンド**を呼び出し、コマンド契約の挙動を検証すること。 -- スコープ: - - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/起動/ペアリングを行いません）。 - - 選択されたAndroidノードに対する、コマンドごとのGateway `node.invoke`検証。 +- 目的: 接続されたAndroidノードが現在公開している**すべてのコマンド**を呼び出し、コマンドコントラクトの挙動を検証すること。 +- 範囲: + - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/起動/ペアリングは行いません）。 + - 選択したAndroidノードに対するコマンド単位のgateway `node.invoke`検証。 - 必要な事前セットアップ: - - AndroidアプリがすでにGatewayに接続され、ペアリング済みであること。 - - アプリをフォアグラウンドに維持すること。 - - 成功を期待する機能に必要な権限/キャプチャ同意が付与されていること。 -- 任意のターゲット上書き: + - Androidアプリがすでにgatewayに接続され、ペアリング済みであること。 + - アプリがフォアグラウンドに維持されていること。 + - 通過を期待する機能に対して、権限/キャプチャ同意が付与されていること。 +- 任意の対象オーバーライド: - `OPENCLAW_ANDROID_NODE_ID`または`OPENCLAW_ANDROID_NODE_NAME`。 - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。 - Androidの完全なセットアップ詳細: [Android App](/ja-JP/platforms/android) -## Live: モデルスモーク（プロファイルキー） +## Live: modelスモーク（profileキー） -liveテストは、障害を切り分けられるように2つのレイヤーに分かれています。 +liveテストは、失敗を切り分けられるように2つのレイヤーに分かれています。 -- 「Direct model」は、指定したキーでプロバイダー/モデルがそもそも応答できるかを教えてくれます。 -- 「Gateway smoke」は、そのモデルに対して完全なGateway+エージェントパイプラインが動作するか（セッション、履歴、ツール、sandboxポリシーなど）を教えてくれます。 +- 「Direct model」は、そのprovider/modelが与えられたキーで少なくとも応答できるかを示します。 +- 「Gateway smoke」は、そのモデルに対して完全なgateway+agentパイプラインが動作するかを示します（sessions、history、tools、sandbox policyなど）。 -### レイヤー1: Direct model completion（Gatewayなし） +### レイヤー1: 直接モデル補完（gatewayなし） - テスト: `src/agents/models.profiles.live.test.ts` - 目的: - 検出されたモデルを列挙する - - `getApiKeyForModel`を使って、認証情報を持っているモデルを選択する - - モデルごとに小さなcompletionを実行する（必要に応じて対象を絞った回帰テストも実行） + - `getApiKeyForModel`を使って、認証情報を持つモデルを選択する + - モデルごとに小さな補完を実行する（必要に応じて対象回帰も） - 有効化方法: - `pnpm test:live`（またはVitestを直接呼び出す場合は`OPENCLAW_LIVE_TEST=1`） -- このスイートを実際に実行するには`OPENCLAW_LIVE_MODELS=modern`（または`all`。modernの別名）を設定します。そうしないと、`pnpm test:live`をGateway smokeに集中させるためスキップされます -- モデルの選択方法: - - modern allowlistを実行するには`OPENCLAW_LIVE_MODELS=modern`（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） +- このスイートを実際に実行するには`OPENCLAW_LIVE_MODELS=modern`（または`all`、`modern`の別名）を設定します。そうしないと、`pnpm test:live`をgateway smokeに集中させるためにスキップされます。 +- モデルの選び方: + - `OPENCLAW_LIVE_MODELS=modern`でmodern allowlistを実行（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - `OPENCLAW_LIVE_MODELS=all`はmodern allowlistの別名 - または`OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（カンマ区切りallowlist） - - modern/allスイープはデフォルトで厳選された高シグナル上限を使います。modernを網羅的にスイープするには`OPENCLAW_LIVE_MAX_MODELS=0`を設定し、より小さい上限にするには正の数を設定します。 -- プロバイダーの選択方法: + - modern/allスイープはデフォルトで厳選された高シグナル上限を使います。網羅的なmodernスイープには`OPENCLAW_LIVE_MAX_MODELS=0`を、より小さい上限には正の数を設定してください。 +- providerの選び方: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（カンマ区切りallowlist） - キーの取得元: - - デフォルト: プロファイルストアと環境変数フォールバック - - **プロファイルストアのみ**を強制するには`OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`を設定 + - デフォルト: profile storeとenvフォールバック + - **profile storeのみ**を強制するには`OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`を設定 - これが存在する理由: - - 「プロバイダーAPIが壊れている / キーが無効」と「Gatewayエージェントパイプラインが壊れている」を分離するため - - 小さく分離された回帰テストを収容するため（例: OpenAI Responses/Codex Responsesのreasoning replay + tool-callフロー） + - 「provider APIが壊れている / キーが無効」と「gateway agentパイプラインが壊れている」を切り分けるため + - 小さく分離された回帰を含めるため（例: OpenAI Responses/Codex Responsesのreasoning replay + tool-callフロー） -### レイヤー2: Gateway + devエージェントスモーク（`@openclaw`が実際に行うこと） +### レイヤー2: Gateway + dev agentスモーク（`@openclaw`が実際に何をするか） - テスト: `src/gateway/gateway-models.profiles.live.test.ts` - 目的: - - プロセス内Gatewayを起動する - - `agent:dev:*`セッションを作成/パッチする（実行ごとにモデル上書き） + - プロセス内gatewayを起動する + - `agent:dev:*`セッションを作成/パッチする（実行ごとにモデルオーバーライド） - キー付きモデルを反復し、次を検証する: - - 「意味のある」応答（ツールなし） - - 実際のツール呼び出しが機能すること（readプローブ） - - 任意の追加ツールプローブ（exec+readプローブ） - - OpenAIの回帰経路（tool-call-only → follow-up）が引き続き動作すること -- プローブ詳細（障害をすぐ説明できるように）: - - `read`プローブ: テストはワークスペースにnonceファイルを書き込み、エージェントにそれを`read`してnonceを返答内でそのまま返すよう求めます。 - - `exec+read`プローブ: テストは、エージェントに`exec`でnonceを一時ファイルへ書き込み、その後`read`で読み戻すよう求めます。 - - imageプローブ: テストは生成したPNG（cat + ランダムコード）を添付し、モデルが`cat `を返すことを期待します。 - - 実装リファレンス: `src/gateway/gateway-models.profiles.live.test.ts`および`src/gateway/live-image-probe.ts`。 + - 「意味のある」応答（toolsなし） + - 実際のtool呼び出しが動作する（read probe） + - 任意の追加tool probe（exec+read probe） + - OpenAIの回帰パス（tool-callのみ → フォローアップ）が機能し続ける +- probeの詳細（失敗を素早く説明できるように）: + - `read` probe: テストがワークスペースにnonceファイルを書き込み、エージェントにそれを`read`してnonceをそのまま返すよう要求します。 + - `exec+read` probe: テストがエージェントに`exec`で一時ファイルへnonceを書かせ、その後それを`read`で読み戻すよう要求します。 + - image probe: テストが生成したPNG（cat + ランダムコード）を添付し、モデルが`cat `を返すことを期待します。 + - 実装参照: `src/gateway/gateway-models.profiles.live.test.ts`および`src/gateway/live-image-probe.ts`。 - 有効化方法: - `pnpm test:live`（またはVitestを直接呼び出す場合は`OPENCLAW_LIVE_TEST=1`） -- モデルの選択方法: +- モデルの選び方: - デフォルト: modern allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - `OPENCLAW_LIVE_GATEWAY_MODELS=all`はmodern allowlistの別名 - - または、絞り込むには`OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（またはカンマ区切りリスト）を設定 - - modern/all Gatewayスイープはデフォルトで厳選された高シグナル上限を使います。modernを網羅的にスイープするには`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`を設定し、より小さい上限にするには正の数を設定します。 -- プロバイダーの選択方法（「OpenRouterの全部」を避ける）: + - または`OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（またはカンマ区切りリスト）で絞り込み + - modern/all gatewayスイープはデフォルトで厳選された高シグナル上限を使います。網羅的なmodernスイープには`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`を、より小さい上限には正の数を設定してください。 +- providerの選び方（「OpenRouter全部」を避ける）: - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（カンマ区切りallowlist） -- このliveテストではtool + imageプローブは常に有効です: - - `read`プローブ + `exec+read`プローブ（ツール負荷テスト） - - image入力対応をモデルが公開している場合はimageプローブを実行 +- このliveテストではtool + image probeは常に有効です: + - `read` probe + `exec+read` probe`（toolストレス） + - image input supportをモデルが公開している場合、image probeを実行 - フロー（高レベル）: - - テストが「CAT」+ ランダムコードを含む小さなPNGを生成する（`src/gateway/live-image-probe.ts`） - - `agent` `attachments: [{ mimeType: "image/png", content: "" }]`で送信する - - Gatewayが添付を`images[]`にパースする（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） - - 埋め込みエージェントがマルチモーダルなユーザーメッセージをモデルへ転送する + - テストが「CAT」+ランダムコード入りの小さなPNGを生成（`src/gateway/live-image-probe.ts`） + - それを`agent`へ`attachments: [{ mimeType: "image/png", content: "" }]`として送信 + - Gatewayが添付を`images[]`へパース（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） + - 組み込みagentがマルチモーダルなユーザーメッセージをモデルへ転送 - 検証: 返信に`cat` + そのコードが含まれること（OCR許容: 軽微な誤りは許可） -ヒント: 自分のマシンで何をテストできるか（および正確な`provider/model` id）を確認するには、次を実行してください。 - -```bash -openclaw models list -openclaw models list --json -``` - -## Live: CLIバックエンドスモーク（Claude、Codex、Gemini、または他のローカルCLI） +ヒント: 自分のマシンで何をテストできるか（および正確な`provider/model` ID）を見るには、次を実行してください。 +__OC_I18N_900000__ +## Live: CLIバックエンドスモーク（Claude、Codex、Gemini、またはその他のローカルCLI） - テスト: `src/gateway/gateway-cli-backend.live.test.ts` -- 目的: デフォルト設定に触れずに、ローカルCLIバックエンドを使ってGateway + エージェントパイプラインを検証すること。 +- 目的: デフォルト設定に触れずに、ローカルCLIバックエンドを使ってGateway + agentパイプラインを検証すること。 - バックエンド固有のスモークデフォルトは、所有するextensionの`cli-backend.ts`定義にあります。 - 有効化: - `pnpm test:live`（またはVitestを直接呼び出す場合は`OPENCLAW_LIVE_TEST=1`） - `OPENCLAW_LIVE_CLI_BACKEND=1` - デフォルト: - - デフォルトのプロバイダー/モデル: `claude-cli/claude-sonnet-4-6` - - コマンド/引数/image挙動は、所有するCLIバックエンドpluginメタデータから取得されます。 -- 上書き（任意）: + - デフォルトprovider/model: `claude-cli/claude-sonnet-4-6` + - command/args/image動作は、所有するCLIバックエンドpluginメタデータから取得されます。 +- オーバーライド（任意）: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - 実際の画像添付を送るには`OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`（パスはプロンプトに注入されます）。 - - プロンプト注入ではなくCLI引数として画像ファイルパスを渡すには`OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`。 - - `IMAGE_ARG`が設定されているときの画像引数の渡し方を制御するには`OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または`"list"`）。 - - 2ターン目を送ってresumeフローを検証するには`OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`。 - - デフォルトのClaude Sonnet -> Opus同一セッション継続性プローブを無効にするには`OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択モデルが切り替え先をサポートするときに強制的に有効化するには`1`）。 + - プロンプト注入ではなくCLI引数として画像ファイルパスを渡すには`OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` + - `IMAGE_ARG`が設定されているときの画像引数の渡し方を制御するには`OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または`"list"`） + - 2ターン目を送り、resumeフローを検証するには`OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` + - デフォルトのClaude Sonnet -> Opus同一セッション継続性probeを無効にするには`OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択モデルが切り替え先をサポートしているときに強制的に有効化するには`1`） 例: - -```bash -OPENCLAW_LIVE_CLI_BACKEND=1 \ - OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \ - pnpm test:live src/gateway/gateway-cli-backend.live.test.ts -``` - +__OC_I18N_900001__ Dockerレシピ: - -```bash -pnpm test:docker:live-cli-backend -``` - -単一プロバイダー用Dockerレシピ: - -```bash -pnpm test:docker:live-cli-backend:claude -pnpm test:docker:live-cli-backend:codex -pnpm test:docker:live-cli-backend:gemini -``` - -補足: +__OC_I18N_900002__ +単一providerのDockerレシピ: +__OC_I18N_900003__ +注記: - Dockerランナーは`scripts/test-live-cli-backend-docker.sh`にあります。 -- リポジトリDockerイメージ内で、非rootの`node`ユーザーとしてlive CLIバックエンドスモークを実行します。 -- 所有するextensionからCLIスモークメタデータを解決し、一致するLinux CLIパッケージ（`@anthropic-ai/claude-code`、`@openai/codex`、または`@google/gemini-cli`）を、`OPENCLAW_DOCKER_CLI_TOOLS_DIR`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）のキャッシュ可能で書き込み可能なprefixにインストールします。 -- live CLIバックエンドスモークは現在、Claude、Codex、Geminiに対して同じエンドツーエンドフローを実行します: テキストターン、画像分類ターン、その後Gateway CLI経由で検証されるMCP `cron`ツール呼び出しです。 -- Claudeのデフォルトスモークでは、セッションをSonnetからOpusへパッチし、再開したセッションが以前のメモを引き続き覚えていることも検証します。 +- これは、リポジトリDockerイメージ内で、非rootの`node`ユーザーとしてlive CLI-backendスモークを実行します。 +- 所有するextensionからCLIスモークメタデータを解決し、対応するLinux CLIパッケージ（`@anthropic-ai/claude-code`、`@openai/codex`、または`@google/gemini-cli`）を、`OPENCLAW_DOCKER_CLI_TOOLS_DIR`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）にあるキャッシュ可能な書き込み可能prefixへインストールします。 +- `pnpm test:docker:live-cli-backend:claude-subscription`は、`~/.claude/.credentials.json`内の`claudeAiOauth.subscriptionType`、または`claude setup-token`由来の`CLAUDE_CODE_OAUTH_TOKEN`のいずれかによるポータブルなClaude Code subscription OAuthを必要とします。これはまずDocker内での直接`claude -p`を検証し、その後Anthropic APIキーenvを保持せずに2回のGateway CLI-backendターンを実行します。このsubscriptionレーンでは、Claudeが現在、サードパーティーアプリ利用を通常のsubscriptionプラン上限ではなく追加利用課金経由で処理しているため、Claude MCP/toolおよびimage probeはデフォルトで無効化されます。 +- live CLI-backendスモークは現在、Claude、Codex、Geminiに対して同じエンドツーエンドフローを実行します: テキストターン、画像分類ターン、その後gateway CLI経由で検証されるMCP `cron` tool call。 +- Claudeのデフォルトスモークは、セッションをSonnetからOpusへパッチし、再開したセッションが以前のメモを引き続き記憶していることも検証します。 -## Live: ACP bindスモーク（`/acp spawn ... --bind here`） +## Live: ACPバインドスモーク（`/acp spawn ... --bind here`） - テスト: `src/gateway/gateway-acp-bind.live.test.ts` -- 目的: live ACPエージェントを使って、実際のACP会話バインドフローを検証すること: - - `/acp spawn --bind here`を送る - - 合成メッセージチャネル会話をその場でバインドする - - 同じ会話上で通常のfollow-upを送る - - そのfollow-upが、バインドされたACPセッショントランスクリプトに記録されることを検証する +- 目的: live ACP agentを使った実際のACP conversation-bindフローを検証すること: + - `/acp spawn --bind here`を送信する + - 合成されたmessage-channel会話をその場でバインドする + - 同じ会話上で通常のフォローアップを送る + - そのフォローアップが、バインドされたACPセッションのトランスクリプトに到達することを確認する - 有効化: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - デフォルト: - - Docker内のACPエージェント: `claude,codex,gemini` - - 直接`pnpm test:live ...`する場合のACPエージェント: `claude` - - 合成チャネル: Slack DM形式の会話コンテキスト + - Docker内のACP agent: `claude,codex,gemini` + - 直接`pnpm test:live ...`用のACP agent: `claude` + - 合成チャネル: Slack DM風の会話コンテキスト - ACPバックエンド: `acpx` -- 上書き: +- オーバーライド: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` -- 補足: - - このレーンでは、テストが外部配信を装わずにメッセージチャネルコンテキストを付与できるよう、管理者専用の合成originating-routeフィールドを持つGateway `chat.send`サーフェスを使用します。 - - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND`が未設定の場合、テストは選択されたACPハーネスエージェントに対して埋め込み`acpx`pluginの組み込みエージェントレジストリを使用します。 +- 注記: + - このレーンは、admin専用の合成originating-routeフィールドを持つgatewayの`chat.send`サーフェスを使うため、外部配信を装わずにmessage-channelコンテキストをテストへアタッチできます。 + - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND`が未設定の場合、テストは埋め込み`acpx`pluginの組み込みagent registryを使って選択したACPハーネスagentを解決します。 例: - -```bash -OPENCLAW_LIVE_ACP_BIND=1 \ - OPENCLAW_LIVE_ACP_BIND_AGENT=claude \ - pnpm test:live src/gateway/gateway-acp-bind.live.test.ts -``` - +__OC_I18N_900004__ Dockerレシピ: - -```bash -pnpm test:docker:live-acp-bind -``` - -単一エージェント用Dockerレシピ: - -```bash -pnpm test:docker:live-acp-bind:claude -pnpm test:docker:live-acp-bind:codex -pnpm test:docker:live-acp-bind:gemini -``` - -Docker補足: +__OC_I18N_900005__ +単一agentのDockerレシピ: +__OC_I18N_900006__ +Dockerに関する注記: - Dockerランナーは`scripts/test-live-acp-bind-docker.sh`にあります。 -- デフォルトでは、対応するすべてのlive CLIエージェントに対してACP bindスモークを順番に実行します: `claude`、`codex`、`gemini`です。 -- マトリクスを絞り込むには`OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`を使います。 -- `~/.profile`を読み込み、一致するCLI認証マテリアルをコンテナにステージし、書き込み可能なnpm prefixへ`acpx`をインストールし、その後不足していれば要求されたlive CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または`@google/gemini-cli`）をインストールします。 -- Docker内では、`acpx`が読み込まれたprofileのプロバイダー環境変数を子ハーネスCLIで使えるよう維持するため、ランナーは`OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`を設定します。 +- デフォルトでは、サポートされているすべてのlive CLI agentに対してACP bindスモークを順番に実行します: `claude`、`codex`、`gemini`。 +- マトリクスを絞り込むには、`OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`を使用してください。 +- これは`~/.profile`を読み込み、一致するCLI認証情報をコンテナにステージし、書き込み可能なnpm prefixに`acpx`をインストールした後、必要なら要求されたlive CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または`@google/gemini-cli`）をインストールします。 +- Docker内では、ランナーは`OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`を設定し、`acpx`が読み込まれたprofileのprovider env varを子ハーネスCLIで使えるようにします。 + +## Live: Codex app-serverハーネススモーク + +- 目的: pluginが所有するCodexハーネスを通常のgateway + `agent`メソッド経由で検証すること: + - バンドルされた`codex`pluginを読み込む + - `OPENCLAW_AGENT_RUNTIME=codex`を選択する + - 最初のgateway agentターンを`codex/gpt-5.4`へ送信する + - 2回目のターンを同じOpenClawセッションへ送信し、app-server + スレッドが再開できることを確認する + - 同じgatewayコマンド + 経路を通じて`/codex status`と`/codex models`を実行する +- テスト: `src/gateway/gateway-codex-harness.live.test.ts` +- 有効化: `OPENCLAW_LIVE_CODEX_HARNESS=1` +- デフォルトモデル: `codex/gpt-5.4` +- 任意のimage probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- 任意のMCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- このスモークでは`OPENCLAW_AGENT_HARNESS_FALLBACK=none`を設定するため、壊れたCodex + ハーネスがPIへ黙ってフォールバックして通過することはできません。 +- 認証: シェル/profileからの`OPENAI_API_KEY`に加え、任意でコピーされる + `~/.codex/auth.json`と`~/.codex/config.toml` + +ローカルレシピ: +__OC_I18N_900007__ +Dockerレシピ: +__OC_I18N_900008__ +Dockerに関する注記: + +- Dockerランナーは`scripts/test-live-codex-harness-docker.sh`にあります。 +- これはマウントされた`~/.profile`を読み込み、`OPENAI_API_KEY`を渡し、存在する場合はCodex CLIの + 認証ファイルをコピーし、書き込み可能なマウント済みnpm + prefixに`@openai/codex`をインストールし、ソースツリーをステージした後、Codex-harness liveテストのみを実行します。 +- DockerはデフォルトでimageおよびMCP/tool probeを有効にします。より狭いデバッグ実行が必要な場合は + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`または + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`を設定してください。 +- Dockerは`OPENCLAW_AGENT_HARNESS_FALLBACK=none`もエクスポートし、live + テスト設定に合わせることで、`openai-codex/*`またはPIフォールバックがCodexハーネスの + 回帰を隠せないようにします。 ### 推奨liveレシピ -狭く明示的なallowlistが最も高速で、flakyさも最小です。 +狭く明示的なallowlistが最も高速で、最も不安定さが少ないです。 -- 単一モデル、direct（Gatewayなし）: +- 単一モデル、直接（gatewayなし）: - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- 単一モデル、Gateway smoke: +- 単一モデル、gatewayスモーク: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 複数プロバイダーにまたがるtool calling: +- 複数providerにまたがるtool calling: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Google重視（Gemini APIキー + Antigravity）: - - Gemini（APIキー）: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Google重視（Gemini API key + Antigravity）: + - Gemini（API key）: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity（OAuth）: `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -補足: +注記: -- `google/...`はGemini API（APIキー）を使います。 -- `google-antigravity/...`はAntigravity OAuthブリッジ（Cloud Code Assist形式のエージェントエンドポイント）を使います。 -- `google-gemini-cli/...`は、あなたのマシン上のローカルGemini CLIを使います（別の認証 + tooling特有の癖があります）。 -- Gemini APIとGemini CLIの違い: - - API: OpenClawがGoogleのホスト型Gemini APIをHTTP経由で呼び出します（APIキー / プロファイル認証）。ほとんどのユーザーが「Gemini」と言うときに意味しているのはこれです。 - - CLI: OpenClawがローカルの`gemini`バイナリをシェル実行します。独自の認証を持ち、挙動も異なることがあります（ストリーミング/ツール対応/バージョンずれ）。 +- `google/...`はGemini API（API key）を使います。 +- `google-antigravity/...`はAntigravity OAuthブリッジ（Cloud Code Assist風のagent endpoint）を使います。 +- `google-gemini-cli/...`はローカルマシン上のGemini CLIを使います（別個の認証 + ツーリングの癖があります）。 +- Gemini APIとGemini CLI: + - API: OpenClawがGoogleのホスト型Gemini APIをHTTP経由で呼び出します（API key / profile auth）。これはたいていのユーザーが「Gemini」と言うときに意味するものです。 + - CLI: OpenClawがローカルの`gemini`バイナリをシェル実行します。独自の認証があり、挙動が異なることがあります（streaming/tool support/version skew）。 -## Live: モデルマトリクス（何をカバーするか） +## Live: modelマトリクス（何をカバーしているか） -固定の「CIモデル一覧」はありません（liveはオプトイン）が、キーを持つ開発マシンで定期的にカバーすることを**推奨**するモデルは以下です。 +固定の「CIモデル一覧」はありません（liveはオプトイン）が、キーを持つ開発マシンで定期的にカバーすることを**推奨**するモデルは次のとおりです。 ### Modernスモークセット（tool calling + image） -これは、動作し続けることを期待する「一般的なモデル」実行です。 +これは、動作し続けることを期待している「一般的なモデル」の実行です。 - OpenAI（非Codex）: `openai/gpt-5.4`（任意: `openai/gpt-5.4-mini`） - OpenAI Codex: `openai-codex/gpt-5.4` @@ -427,12 +450,12 @@ Docker補足: - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -tools + image付きでGateway smokeを実行: +tools + image付きでgatewayスモークを実行: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### ベースライン: tool calling（Read + 任意のExec） -少なくともプロバイダーファミリーごとに1つ選んでください。 +providerファミリーごとに少なくとも1つ選んでください。 - OpenAI: `openai/gpt-5.4`（または`openai/gpt-5.4-mini`） - Anthropic: `anthropic/claude-opus-4-6`（または`anthropic/claude-sonnet-4-6`） @@ -440,44 +463,44 @@ tools + image付きでGateway smokeを実行: - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -任意の追加カバレッジ（あると望ましい）: +任意の追加カバレッジ（あるとよい）: - xAI: `xai/grok-4`（または利用可能な最新） -- Mistral: `mistral/`…（有効化している「tools」対応モデルを1つ選ぶ） -- Cerebras: `cerebras/`…（アクセスがある場合） -- LM Studio: `lmstudio/`…（ローカル。tool callingはAPIモードに依存） +- Mistral: `mistral/`…（有効化済みの「tools」対応モデルを1つ選ぶ） +- Cerebras: `cerebras/`…（アクセス権がある場合） +- LM Studio: `lmstudio/`…（ローカル; tool callingはAPIモードに依存） -### Vision: image send（添付 → マルチモーダルメッセージ） +### Vision: image送信（添付 → マルチモーダルメッセージ） -imageプローブを実行するため、`OPENCLAW_LIVE_GATEWAY_MODELS`に少なくとも1つの画像対応モデル（Claude/Gemini/OpenAIのvision対応バリアントなど）を含めてください。 +image probeを通すために、少なくとも1つのimage対応モデルを`OPENCLAW_LIVE_GATEWAY_MODELS`に含めてください（Claude/Gemini/OpenAIのvision対応バリアントなど）。 -### Aggregator / 代替Gateway +### アグリゲーター / 代替gateway -キーが有効なら、次経由のテストもサポートしています。 +キーが有効であれば、次経由のテストもサポートしています。 -- OpenRouter: `openrouter/...`（数百のモデル。tools+image対応候補を見つけるには`openclaw models scan`を使ってください） +- OpenRouter: `openrouter/...`（数百のモデル; tool+image対応候補を見つけるには`openclaw models scan`を使用） - OpenCode: Zen用の`opencode/...`およびGo用の`opencode-go/...`（認証は`OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`） -liveマトリクスに含められる他のプロバイダー（認証情報/設定がある場合）: +liveマトリクスに含められるproviderは他にもあります（認証情報/設定がある場合）: - 組み込み: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- `models.providers`経由（カスタムエンドポイント）: `minimax`（cloud/API）、および任意のOpenAI/Anthropic互換プロキシ（LM Studio、vLLM、LiteLLMなど） +- `models.providers`経由（カスタムエンドポイント）: `minimax`（cloud/API）、および任意のOpenAI/Anthropic互換proxy（LM Studio、vLLM、LiteLLMなど） -ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。信頼できる一覧は、あなたのマシンで`discoverModels(...)`が返すもの + 利用可能なキーです。 +ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。権威ある一覧は、そのマシン上で`discoverModels(...)`が返すものと、利用可能なキーによって決まります。 ## 認証情報（絶対にコミットしない） -liveテストは、CLIと同じ方法で認証情報を検出します。実際上の意味は次のとおりです。 +liveテストはCLIと同じ方法で認証情報を検出します。実際上の意味は次のとおりです。 - CLIが動くなら、liveテストも同じキーを見つけられるはずです。 -- liveテストが「認証情報なし」と言う場合は、`openclaw models list` / モデル選択をデバッグするときと同じようにデバッグしてください。 +- liveテストが「認証情報なし」と言うなら、`openclaw models list` / モデル選択のデバッグと同じ方法で調査してください。 -- エージェントごとの認証プロファイル: `~/.openclaw/agents//agent/auth-profiles.json`（liveテストでの「profile keys」が意味するものです） +- エージェント単位のauth profile: `~/.openclaw/agents//agent/auth-profiles.json`（これがliveテストにおける「profile keys」の意味です） - 設定: `~/.openclaw/openclaw.json`（または`OPENCLAW_CONFIG_PATH`） -- レガシーstateディレクトリ: `~/.openclaw/credentials/`（存在する場合はステージされたlive homeにコピーされますが、メインのprofile-keyストアではありません） -- ローカルのlive実行は、デフォルトでアクティブ設定、エージェントごとの`auth-profiles.json`ファイル、レガシー`credentials/`、対応する外部CLI認証ディレクトリを一時的なテストhomeにコピーします。ステージされたlive homeでは`workspace/`と`sandboxes/`は除外され、`agents.*.workspace` / `agentDir`のパス上書きは除去されるため、プローブが実際のホストワークスペースに触れません。 +- 旧stateディレクトリ: `~/.openclaw/credentials/`（存在する場合はステージ済みlive homeへコピーされますが、mainのprofile-key storeではありません） +- ローカルlive実行は、デフォルトでアクティブ設定、エージェント単位の`auth-profiles.json`ファイル、旧`credentials/`、およびサポートされる外部CLI認証ディレクトリを一時テストhomeへコピーします。ステージ済みlive homeでは`workspace/`と`sandboxes/`はスキップされ、`agents.*.workspace` / `agentDir`のパスオーバーライドは削除されるため、probeが実際のホストworkspaceに触れません。 -環境変数キー（たとえば`~/.profile`でexportされたもの）に依存したい場合は、`source ~/.profile`の後にローカルテストを実行するか、以下のDockerランナーを使ってください（コンテナに`~/.profile`をマウントできます）。 +envキーに依存したい場合（たとえば`~/.profile`でexportしている場合）は、`source ~/.profile`の後にローカルテストを実行するか、以下のDockerランナーを使ってください（これらは`~/.profile`をコンテナにマウントできます）。 ## Deepgram live（音声文字起こし） @@ -488,262 +511,274 @@ liveテストは、CLIと同じ方法で認証情報を検出します。実際 - テスト: `src/agents/byteplus.live.test.ts` - 有効化: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- 任意のモデル上書き: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- 任意のモデルオーバーライド: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## ComfyUI workflow media live - テスト: `extensions/comfy/comfy.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- スコープ: - - バンドルされたcomfyの画像、動画、`music_generate`経路を実行する - - `models.providers.comfy.`が設定されていない限り、各機能をスキップする +- 範囲: + - バンドルされたcomfyの画像、動画、`music_generate`経路を実行 + - `models.providers.comfy.`が設定されていない限り、各機能はスキップ - comfyのworkflow送信、ポーリング、ダウンロード、またはplugin登録を変更した後に有用 -## Image generation live +## 画像生成live - テスト: `src/image-generation/runtime.live.test.ts` - コマンド: `pnpm test:live src/image-generation/runtime.live.test.ts` - ハーネス: `pnpm test:live:media image` -- スコープ: - - 登録されているすべてのimage-generation provider pluginを列挙する - - プローブ前に、ログインシェル（`~/.profile`）から不足しているprovider環境変数を読み込む - - デフォルトでは、保存済み認証プロファイルよりlive/env APIキーを優先して使うため、`auth-profiles.json`内の古いテストキーが実際のシェル認証情報を覆い隠しません - - 使用可能な認証/プロファイル/モデルがないプロバイダーはスキップする - - 共有ランタイム機能を通じて標準のimage-generationバリアントを実行する: +- 範囲: + - 登録されているすべての画像生成provider pluginを列挙 + - probe前に、ログインシェル（`~/.profile`）から不足しているprovider env varを読み込む + - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json`内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 使用可能なauth/profile/modelがないproviderはスキップ + - 共有ランタイム機能を通じて標準の画像生成バリアントを実行: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- 現在カバーされているバンドル済みプロバイダー: +- 現在カバーされるバンドル済みprovider: - `openai` - `google` - 任意の絞り込み: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- 任意の認証挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`でprofile-store認証を強制し、環境変数のみの上書きを無視する +- 任意の認証動作: + - profile-store認証を強制し、envのみのオーバーライドを無視するには`OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Music generation live +## 音楽生成live - テスト: `extensions/music-generation-providers.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - ハーネス: `pnpm test:live:media music` -- スコープ: - - 共有のバンドル済みmusic-generation provider経路を実行する - - 現在はGoogleとMiniMaxをカバーする - - プローブ前に、ログインシェル（`~/.profile`）からprovider環境変数を読み込む - - デフォルトでは、保存済み認証プロファイルよりlive/env APIキーを優先して使うため、`auth-profiles.json`内の古いテストキーが実際のシェル認証情報を覆い隠しません - - 使用可能な認証/プロファイル/モデルがないプロバイダーはスキップする - - 利用可能な場合、宣言された両方のランタイムモードを実行する: - - プロンプトのみ入力の`generate` - - プロバイダーが`capabilities.edit.enabled`を宣言している場合の`edit` - - 現在の共有レーンのカバレッジ: +- 範囲: + - 共有のバンドル済み音楽生成provider経路を実行 + - 現在はGoogleとMiniMaxをカバー + - probe前に、ログインシェル（`~/.profile`）からprovider env varを読み込む + - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json`内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 使用可能なauth/profile/modelがないproviderはスキップ + - 利用可能な場合、宣言された両方のランタイムモードを実行: + - プロンプトのみ入力での`generate` + - providerが`capabilities.edit.enabled`を宣言している場合の`edit` + - 現在の共有レーンカバレッジ: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: 別のComfy liveファイルであり、この共有スイープではない + - `comfy`: この共有スイープではなく、別のComfy liveファイル - 任意の絞り込み: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- 任意の認証挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`でprofile-store認証を強制し、環境変数のみの上書きを無視する +- 任意の認証動作: + - profile-store認証を強制し、envのみのオーバーライドを無視するには`OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Video generation live +## 動画生成live - テスト: `extensions/video-generation-providers.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - ハーネス: `pnpm test:live:media video` -- スコープ: - - 共有のバンドル済みvideo-generation provider経路を実行する - - プローブ前に、ログインシェル（`~/.profile`）からprovider環境変数を読み込む - - デフォルトでは、保存済み認証プロファイルよりlive/env APIキーを優先して使うため、`auth-profiles.json`内の古いテストキーが実際のシェル認証情報を覆い隠しません - - 使用可能な認証/プロファイル/モデルがないプロバイダーはスキップする - - 利用可能な場合、宣言された両方のランタイムモードを実行する: - - プロンプトのみ入力の`generate` - - プロバイダーが`capabilities.imageToVideo.enabled`を宣言しており、選択されたプロバイダー/モデルが共有スイープでbuffer-backedなローカル画像入力を受け付ける場合の`imageToVideo` - - プロバイダーが`capabilities.videoToVideo.enabled`を宣言しており、選択されたプロバイダー/モデルが共有スイープでbuffer-backedなローカル動画入力を受け付ける場合の`videoToVideo` - - 共有スイープ内で現在宣言済みだがスキップされる`imageToVideo`プロバイダー: +- 範囲: + - 共有のバンドル済み動画生成provider経路を実行 + - probe前に、ログインシェル（`~/.profile`）からprovider env varを読み込む + - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json`内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 使用可能なauth/profile/modelがないproviderはスキップ + - 利用可能な場合、宣言された両方のランタイムモードを実行: + - プロンプトのみ入力での`generate` + - providerが`capabilities.imageToVideo.enabled`を宣言しており、選択されたprovider/modelが共有スイープでバッファベースのローカル画像入力を受け付ける場合の`imageToVideo` + - providerが`capabilities.videoToVideo.enabled`を宣言しており、選択されたprovider/modelが共有スイープでバッファベースのローカル動画入力を受け付ける場合の`videoToVideo` + - 現在の共有スイープで宣言済みだがスキップされる`imageToVideo` provider: - バンドル済み`veo3`はテキスト専用で、バンドル済み`kling`はリモート画像URLを必要とするため、`vydra` - - プロバイダー固有のVydraカバレッジ: + - provider固有のVydraカバレッジ: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - このファイルは、`veo3`のtext-to-videoに加え、デフォルトでリモート画像URLフィクスチャを使う`kling`レーンを実行します + - このファイルは、`veo3`のテキストから動画へのレーンと、デフォルトでリモート画像URL fixtureを使う`kling`レーンを実行します - 現在の`videoToVideo` liveカバレッジ: - - 選択モデルが`runway/gen4_aleph`のときのみ`runway` - - 共有スイープ内で現在宣言済みだがスキップされる`videoToVideo`プロバイダー: + - 選択モデルが`runway/gen4_aleph`の場合のみ`runway` + - 現在の共有スイープで宣言済みだがスキップされる`videoToVideo` provider: - これらの経路は現在リモート`http(s)` / MP4参照URLを必要とするため、`alibaba`、`qwen`、`xai` - - 現在の共有Gemini/Veoレーンはローカルbuffer-backed入力を使い、その経路は共有スイープでは受け付けられないため、`google` - - 現在の共有レーンにはorg固有のvideo inpaint/remixアクセス保証がないため、`openai` + - 現在の共有Gemini/Veoレーンはローカルのバッファベース入力を使い、その経路は共有スイープでは受け付けられないため、`google` + - 現在の共有レーンにはorg固有の動画inpaint/remixアクセス保証がないため、`openai` - 任意の絞り込み: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` -- 任意の認証挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`でprofile-store認証を強制し、環境変数のみの上書きを無視する +- 任意の認証動作: + - profile-store認証を強制し、envのみのオーバーライドを無視するには`OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Media liveハーネス +## メディアliveハーネス - コマンド: `pnpm test:live:media` - 目的: - - 共有のimage、music、video liveスイートを、リポジトリ標準の単一エントリーポイントから実行する - - `~/.profile`から不足しているprovider環境変数を自動読み込みする - - デフォルトで、現在使用可能な認証を持つプロバイダーに各スイートを自動で絞り込む - - `scripts/test-live.mjs`を再利用するため、heartbeatとquiet modeの挙動が一貫する + - 共有の画像、音楽、動画liveスイートを、リポジトリ標準の1つのエントリーポイントから実行 + - `~/.profile`から不足しているprovider env varを自動読み込み + - デフォルトで、現在使用可能なauthを持つproviderに各スイートを自動的に絞り込む + - `scripts/test-live.mjs`を再利用するため、heartbeatとquiet-modeの挙動が一貫する - 例: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Dockerランナー（任意の「Linuxでも動く」確認） +## Dockerランナー（任意の「Linuxで動く」確認） -これらのDockerランナーは2つのカテゴリに分かれます。 +これらのDockerランナーは2つのバケットに分かれます。 -- Live modelランナー: `test:docker:live-models`と`test:docker:live-gateway`は、対応するprofile-key liveファイルのみをリポジトリDockerイメージ内で実行します（`src/agents/models.profiles.live.test.ts`と`src/gateway/gateway-models.profiles.live.test.ts`）。ローカルのconfigディレクトリとworkspaceをマウントし（マウントされていれば`~/.profile`も読み込みます）。対応するローカルエントリーポイントは`test:live:models-profiles`と`test:live:gateway-profiles`です。 -- Docker liveランナーは、完全なDockerスイープを現実的に保つため、デフォルトで小さめのスモーク上限を使います: +- live-modelランナー: `test:docker:live-models`と`test:docker:live-gateway`は、それぞれ対応するprofile-key liveファイルのみをリポジトリDockerイメージ内で実行します（`src/agents/models.profiles.live.test.ts`と`src/gateway/gateway-models.profiles.live.test.ts`）。対応するローカルエントリーポイントは`test:live:models-profiles`と`test:live:gateway-profiles`です。 +- Docker liveランナーは、完全なDockerスイープを現実的に保つため、デフォルトでより小さいスモーク上限を使います: `test:docker:live-models`はデフォルトで`OPENCLAW_LIVE_MAX_MODELS=12`、 `test:docker:live-gateway`はデフォルトで`OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`、および - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`を使います。より大きい網羅的スキャンを明示的に行いたい場合は、これらの環境変数を上書きしてください。 -- `test:docker:all`は、まず`test:docker:live-build`でlive Dockerイメージを一度だけビルドし、その後2つのlive Dockerレーンでそれを再利用します。 -- コンテナスモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:plugins`は、1つ以上の実コンテナを起動し、より高レベルのintegration経路を検証します。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`を設定します。より大きな網羅的スキャンを明示的に行いたい場合は、これらのenv varを上書きしてください。 +- `test:docker:all`は、まず`test:docker:live-build`でlive Dockerイメージを一度ビルドし、その後2つのlive Dockerレーンでそれを再利用します。 +- コンテナスモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:plugins`は、1つ以上の実コンテナを起動し、より高レベルの統合経路を検証します。 -live model Dockerランナーは、必要なCLI認証homeだけ（または実行が絞り込まれていない場合は対応するものすべて）をbind mountし、実行前にそれらをコンテナhomeへコピーします。これにより、外部CLI OAuthがホストの認証ストアを変更せずにトークンを更新できます。 +live-model Dockerランナーは、必要なCLI認証homeのみ（または実行が絞り込まれていない場合はサポート対象すべて）をbind mountし、実行前にそれらをコンテナhomeへコピーするため、外部CLI OAuthはホストの認証ストアを変更せずにトークンを更新できます。 -- Direct models: `pnpm test:docker:live-models`（スクリプト: `scripts/test-live-models-docker.sh`） +- 直接モデル: `pnpm test:docker:live-models`（スクリプト: `scripts/test-live-models-docker.sh`） - ACP bindスモーク: `pnpm test:docker:live-acp-bind`（スクリプト: `scripts/test-live-acp-bind-docker.sh`） - CLIバックエンドスモーク: `pnpm test:docker:live-cli-backend`（スクリプト: `scripts/test-live-cli-backend-docker.sh`） -- Gateway + devエージェント: `pnpm test:docker:live-gateway`（スクリプト: `scripts/test-live-gateway-models-docker.sh`） +- Codex app-serverハーネススモーク: `pnpm test:docker:live-codex-harness`（スクリプト: `scripts/test-live-codex-harness-docker.sh`） +- Gateway + dev agent: `pnpm test:docker:live-gateway`（スクリプト: `scripts/test-live-gateway-models-docker.sh`） - Open WebUI liveスモーク: `pnpm test:docker:openwebui`（スクリプト: `scripts/e2e/openwebui-docker.sh`） - オンボーディングウィザード（TTY、完全なscaffolding）: `pnpm test:docker:onboard`（スクリプト: `scripts/e2e/onboard-docker.sh`） -- Gatewayネットワーキング（2コンテナ、WS認証 + ヘルス）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） -- MCP channel bridge（シード済みGateway + stdio bridge + 生のClaude notification-frameスモーク）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） -- Plugins（インストールスモーク + `/plugin`エイリアス + Claudeバンドル再起動セマンティクス）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） +- Gatewayネットワーキング（2コンテナ、WS認証 + health）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） +- MCPチャネルブリッジ（seed済みGateway + stdioブリッジ + 生のClaude notification-frameスモーク）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） +- Plugins（インストールスモーク + `/plugin` alias + Claude-bundle再起動セマンティクス）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） -live model Dockerランナーは、現在のチェックアウトも読み取り専用でbind mountし、それをコンテナ内の一時workdirへステージします。これにより、ランタイムイメージをスリムに保ちながら、正確なローカルソース/設定に対してVitestを実行できます。 -このステージング手順では、`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、アプリローカルの`.build`やGradle出力ディレクトリなど、大きなローカル専用キャッシュやアプリのビルド出力をスキップするため、Docker live実行でマシン固有の成果物のコピーに何分も費やすことがありません。 -また、Gateway liveプローブがコンテナ内で実際のTelegram/Discordなどのchannelワーカーを起動しないよう、`OPENCLAW_SKIP_CHANNELS=1`も設定します。 -`test:docker:live-models`は引き続き`pnpm test:live`を実行するため、そのDockerレーンでGateway liveカバレッジを絞り込む、または除外する必要がある場合は、`OPENCLAW_LIVE_GATEWAY_*`も渡してください。 -`test:docker:openwebui`は、より高レベルの互換性スモークです。OpenAI互換HTTPエンドポイントを有効にしたOpenClaw Gatewayコンテナを起動し、そのGatewayに対して固定版のOpen WebUIコンテナを起動し、Open WebUI経由でサインインし、`/api/models`が`openclaw/default`を公開していることを検証したうえで、Open WebUIの`/api/chat/completions`プロキシ経由で実際のchatリクエストを送信します。 -初回実行は、DockerがOpen WebUIイメージをpullする必要があったり、Open WebUI自身のコールドスタートセットアップを完了する必要があったりするため、目に見えて遅くなることがあります。 -このレーンは使用可能なliveモデルキーを前提とし、Docker化された実行では`OPENCLAW_PROFILE_FILE`（デフォルトは`~/.profile`）がそれを提供する主要な方法です。 -成功した実行では、`{ "ok": true, "model": "openclaw/default", ... }`のような小さなJSONペイロードが出力されます。 -`test:docker:mcp-channels`は意図的に決定論的で、実際のTelegram、Discord、iMessageアカウントを必要としません。シード済みGatewayコンテナを起動し、`openclaw mcp serve`を起動する2つ目のコンテナを開始し、その後、ルーティングされた会話検出、トランスクリプト読み取り、添付メタデータ、liveイベントキューの挙動、送信ルーティング、および実際のstdio MCP bridge上のClaude形式のchannel + permission通知を検証します。通知チェックは、生のstdio MCPフレームを直接検査するため、このスモークは特定のclient SDKがたまたま表面化するものではなく、bridgeが実際に出力する内容を検証します。 +live-model Dockerランナーは、現在のチェックアウトも読み取り専用でbind mountし、コンテナ内の一時workdirへステージします。これにより、ランタイムイメージをスリムに保ちつつ、手元の正確なソース/設定に対してVitestを実行できます。 +ステージングでは、`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの`.build`やGradle出力ディレクトリのような、大きなローカル専用キャッシュやアプリビルド出力をスキップするため、Docker live実行でマシン固有アーティファクトのコピーに何分も費やしません。 +また、`OPENCLAW_SKIP_CHANNELS=1`も設定するため、gateway live probeがコンテナ内で実際のTelegram/Discordなどのチャネルワーカーを起動しません。 +`test:docker:live-models`は引き続き`pnpm test:live`を実行するため、そのDockerレーンからgateway liveカバレッジを絞り込む、または除外したい場合は、`OPENCLAW_LIVE_GATEWAY_*`も渡してください。 +`test:docker:openwebui`はより高レベルの互換性スモークです。OpenAI互換HTTPエンドポイントを有効にした +OpenClaw gatewayコンテナを起動し、そのgatewayに対して固定版のOpen WebUIコンテナを起動し、Open WebUI経由でサインインし、`/api/models`が`openclaw/default`を公開していることを確認し、その後Open WebUIの`/api/chat/completions`プロキシ経由で実際のチャットリクエストを送信します。 +初回実行は、DockerがOpen WebUIイメージをpullする必要があったり、Open WebUI自身のコールドスタートセットアップ完了が必要だったりするため、目に見えて遅くなることがあります。 +このレーンは使用可能なlive modelキーを前提としており、Docker化実行では`OPENCLAW_PROFILE_FILE` +（デフォルトは`~/.profile`）がそれを提供する主な方法です。 +成功した実行では、`{ "ok": true, "model": +"openclaw/default", ... }`のような小さなJSONペイロードが出力されます。 +`test:docker:mcp-channels`は意図的に決定的であり、実際のTelegram、Discord、iMessageアカウントは必要ありません。これはseed済みGateway +コンテナを起動し、`openclaw mcp serve`を起動する2つ目のコンテナを開始し、その後、ルーティングされた会話検出、トランスクリプト読み取り、添付メタデータ、 +live event queue動作、外向き送信ルーティング、および実際のstdio MCPブリッジ上でのClaude風チャネル + +権限通知を検証します。通知チェックでは生のstdio MCPフレームを直接検査するため、このスモークは特定クライアントSDKがたまたま表面化するものではなく、 +ブリッジが実際に出力する内容を検証します。 -手動ACPプレーンランゲージスレッドスモーク（CIではない）: +手動ACP平文スレッドスモーク（CIではない）: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- このスクリプトは回帰/デバッグワークフロー用に残してください。ACPスレッドルーティングの検証で再び必要になる可能性があるため、削除しないでください。 +- このスクリプトは回帰/デバッグワークフロー用に維持してください。ACPスレッドルーティングの検証で再び必要になる可能性があるため、削除しないでください。 -便利な環境変数: +便利なenv var: - `OPENCLAW_CONFIG_DIR=...`（デフォルト: `~/.openclaw`）を`/home/node/.openclaw`にマウント - `OPENCLAW_WORKSPACE_DIR=...`（デフォルト: `~/.openclaw/workspace`）を`/home/node/.openclaw/workspace`にマウント -- `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`）を`/home/node/.profile`にマウントし、テスト実行前に読み込む +- `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`）を`/home/node/.profile`にマウントし、テスト実行前に読み込み - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）を`/home/node/.npm-global`にマウントし、Docker内でCLIインストールをキャッシュ -- `$HOME`配下の外部CLI認証ディレクトリ/ファイルは、`/host-auth...`配下に読み取り専用でマウントされ、テスト開始前に`/home/node/...`へコピーされます - - デフォルトディレクトリ: `.minimax` - - デフォルトファイル: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 絞り込まれたプロバイダー実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`から推定された必要なディレクトリ/ファイルだけをマウントします - - 手動で上書きするには`OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または`OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`のようなカンマ区切りリストを使います +- `$HOME`配下の外部CLI認証ディレクトリ/ファイルは、`/host-auth...`配下に読み取り専用でマウントされ、その後テスト開始前に`/home/node/...`へコピーされます + - デフォルトのディレクトリ: `.minimax` + - デフォルトのファイル: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` + - providerを絞り込んだ実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`から推定された必要なディレクトリ/ファイルだけをマウント + - 手動で上書きするには`OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または`OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`のようなカンマ区切りリストを使用 - 実行を絞り込むには`OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` -- コンテナ内でプロバイダーをフィルタするには`OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` -- 認証情報がprofileストア由来であることを保証するには`OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`（環境変数由来ではない） -- Open WebUIスモーク向けにGatewayが公開するモデルを選ぶには`OPENCLAW_OPENWEBUI_MODEL=...` -- Open WebUIスモークで使うnonceチェックプロンプトを上書きするには`OPENCLAW_OPENWEBUI_PROMPT=...` +- コンテナ内でproviderを絞り込むには`OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` +- 再ビルド不要の再実行で既存の`openclaw:local-live`イメージを再利用するには`OPENCLAW_SKIP_DOCKER_BUILD=1` +- 認証情報がprofile store由来であることを保証するには`OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`（envではなく） +- Open WebUIスモークでgatewayが公開するモデルを選ぶには`OPENCLAW_OPENWEBUI_MODEL=...` +- Open WebUIスモークで使うnonce確認プロンプトを上書きするには`OPENCLAW_OPENWEBUI_PROMPT=...` - 固定されたOpen WebUIイメージタグを上書きするには`OPENWEBUI_IMAGE=...` ## ドキュメントの健全性確認 -ドキュメント編集後は、ドキュメントチェックを実行してください: `pnpm check:docs`。 +ドキュメント編集後は次を実行してください: `pnpm check:docs`。 ページ内見出しチェックも必要な場合は、完全なMintlifyアンカー検証を実行してください: `pnpm docs:check-links:anchors`。 -## オフライン回帰テスト（CIで安全） +## オフライン回帰（CI対応） -これらは、実プロバイダーなしでの「実パイプライン」回帰テストです。 +これらは、実際のproviderなしで行う「実パイプライン」回帰です。 -- Gateway tool calling（モックOpenAI、実際のGateway + エージェントループ）: `src/gateway/gateway.test.ts`（ケース: "runs a mock OpenAI tool call end-to-end via gateway agent loop"） -- Gatewayウィザード（WS `wizard.start`/`wizard.next`、設定 + 認証の書き込みを強制）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） +- Gateway tool calling（mock OpenAI、実際のgateway + agent loop）: `src/gateway/gateway.test.ts`（ケース: "runs a mock OpenAI tool call end-to-end via gateway agent loop"） +- Gatewayウィザード（WS `wizard.start`/`wizard.next`、設定 + authの書き込みを強制）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） -## エージェント信頼性evals（Skills） +## エージェント信頼性eval（Skills） -すでにいくつかのCIで安全なテストがあり、それらは「エージェント信頼性eval」に近い振る舞いをします。 +すでに、いくつかのCI対応テストが「エージェント信頼性eval」のように振る舞います。 -- 実際のGateway + エージェントループを通したモックtool-calling（`src/gateway/gateway.test.ts`）。 +- 実際のgateway + agent loopを通したmock tool-calling（`src/gateway/gateway.test.ts`）。 - セッション配線と設定効果を検証するエンドツーエンドのウィザードフロー（`src/gateway/gateway.test.ts`）。 -Skillsについてまだ不足しているもの（[Skills](/ja-JP/tools/skills)を参照）: +Skillsについてまだ不足しているもの（[Skills](/tools/skills)を参照）: -- **Decisioning:** Skillsがプロンプトに一覧表示されたとき、エージェントは正しいskillを選ぶか（または無関係なものを避けるか）？ -- **Compliance:** エージェントは使用前に`SKILL.md`を読み、必要な手順/引数に従うか？ -- **Workflow contracts:** ツール順序、セッション履歴の引き継ぎ、sandbox境界を検証する複数ターンのシナリオ。 +- **意思決定:** Skillsがプロンプトに列挙されているとき、エージェントは正しいskillを選ぶか（または無関係なものを避けるか）？ +- **準拠性:** エージェントは使用前に`SKILL.md`を読み、必要な手順/引数に従うか？ +- **ワークフローコントラクト:** ツール順序、セッション履歴の引き継ぎ、sandbox境界を検証するマルチターンシナリオ。 -将来のevalは、まず決定論的であるべきです。 +今後のevalは、まず決定的であるべきです。 -- mock providerを使って、ツール呼び出し + 順序、skillファイルの読み取り、セッション配線を検証するシナリオランナー。 -- skillに焦点を当てた小規模シナリオスイート（使う/避ける、ゲーティング、プロンプトインジェクション）。 -- オプションのlive evals（オプトイン、環境変数ゲート付き）は、CIで安全なスイートが整ってからにする。 +- mock providerを使って、tool呼び出し + 順序、skillファイル読み取り、セッション配線を検証するシナリオランナー。 +- skillに焦点を当てた小規模シナリオ群（使う/避ける、ゲーティング、プロンプトインジェクション）。 +- CI対応スイートが整ってからのみ、任意のlive eval（オプトイン、envでゲート）。 -## Contract tests（pluginとchannelの形状） +## コントラクトテスト（pluginおよびchannelの形状） -Contract testsは、登録されているすべてのpluginとchannelがそのinterface contractに準拠していることを検証します。検出されたすべてのpluginを反復し、形状と挙動に関する一連のアサーションを実行します。デフォルトの`pnpm test` unitレーンでは、これらの共有seamおよびスモークファイルを意図的にスキップします。共有channelまたはproviderサーフェスに触れた場合は、contractコマンドを明示的に実行してください。 +コントラクトテストは、登録されているすべてのpluginとchannelがその +インターフェースコントラクトに準拠していることを検証します。検出されたすべてのpluginを反復し、 +形状と動作に関する一連のアサーションを実行します。デフォルトの`pnpm test` unitレーンは、これらの共有seamおよびスモークファイルを意図的に +スキップします。共有channelまたはproviderサーフェスに触れた場合は、コントラクトコマンドを明示的に実行してください。 ### コマンド -- すべてのcontract: `pnpm test:contracts` -- channel contractのみ: `pnpm test:contracts:channels` -- provider contractのみ: `pnpm test:contracts:plugins` +- すべてのコントラクト: `pnpm test:contracts` +- channelコントラクトのみ: `pnpm test:contracts:channels` +- providerコントラクトのみ: `pnpm test:contracts:plugins` -### Channel contracts +### Channelコントラクト -`src/channels/plugins/contracts/*.contract.test.ts`にあります: +`src/channels/plugins/contracts/*.contract.test.ts`にあります。 -- **plugin** - 基本的なplugin形状（id、name、capabilities） -- **setup** - セットアップウィザードcontract +- **plugin** - 基本plugin形状（id、name、capabilities） +- **setup** - セットアップウィザードのコントラクト - **session-binding** - セッションバインディングの挙動 -- **outbound-payload** - メッセージpayload構造 -- **inbound** - 受信メッセージ処理 +- **outbound-payload** - メッセージペイロード構造 +- **inbound** - inboundメッセージ処理 - **actions** - channel actionハンドラー - **threading** - スレッドID処理 - **directory** - ディレクトリ/roster API -- **group-policy** - グループポリシー強制 +- **group-policy** - グループポリシーの適用 -### Provider status contracts +### Provider statusコントラクト `src/plugins/contracts/*.contract.test.ts`にあります。 -- **status** - Channel statusプローブ -- **registry** - Plugin registryの形状 +- **status** - Channel status probe +- **registry** - Plugin registry shape -### Provider contracts +### Providerコントラクト -`src/plugins/contracts/*.contract.test.ts`にあります: +`src/plugins/contracts/*.contract.test.ts`にあります。 -- **auth** - 認証フローcontract -- **auth-choice** - 認証の選択 -- **catalog** - モデルcatalog API -- **discovery** - Plugin検出 -- **loader** - Plugin読み込み -- **runtime** - Providerランタイム -- **shape** - Pluginの形状/interface +- **auth** - 認証フローのコントラクト +- **auth-choice** - 認証方式の選択 +- **catalog** - モデルカタログAPI +- **discovery** - Plugin discovery +- **loader** - Plugin loading +- **runtime** - Provider runtime +- **shape** - Plugin shape/interface - **wizard** - セットアップウィザード -### 実行するタイミング +### 実行すべきタイミング - plugin-sdkのexportまたはsubpathを変更した後 - channelまたはprovider pluginを追加または変更した後 -- plugin登録または検出をリファクタリングした後 +- plugin登録またはdiscoveryをリファクタリングした後 -Contract testsはCIで実行され、実際のAPIキーは不要です。 +コントラクトテストはCIで実行され、実際のAPIキーは不要です。 -## 回帰テストの追加（ガイダンス） +## 回帰を追加する際のガイダンス -liveで見つかったprovider/modelの問題を修正するときは: +liveで見つかったprovider/modelの問題を修正したとき: -- 可能ならCIで安全な回帰テストを追加してください（providerのmock/stub、または正確なリクエスト形状変換のキャプチャ） -- 本質的にlive専用の場合（レート制限、認証ポリシーなど）は、liveテストを狭く保ち、環境変数でオプトインにしてください -- バグを捉えられる最小のレイヤーを狙うことを優先してください: +- 可能ならCI対応の回帰を追加してください（mock/stub provider、または正確なrequest-shape変換をキャプチャ） +- 本質的にlive専用の場合（レート制限、認証ポリシー）は、liveテストを狭く保ち、env varでオプトインにしてください +- バグを検出できる最小のレイヤーを対象にすることを優先してください: - providerのリクエスト変換/replayバグ → direct modelsテスト - - Gatewayのセッション/履歴/ツールパイプラインのバグ → Gateway liveスモークまたはCIで安全なGateway mockテスト + - gatewayのsession/history/toolパイプラインバグ → gateway liveスモークまたはCI対応gateway mockテスト - SecretRef走査のガードレール: - - `src/secrets/exec-secret-ref-id-parity.test.ts`は、registryメタデータ（`listSecretTargetRegistryEntries()`）からSecretRefクラスごとに1つのサンプル対象を導出し、走査セグメントのexec idが拒否されることを検証します。 - - `src/secrets/target-registry-data.ts`に新しい`includeInPlan` SecretRef対象ファミリーを追加する場合は、そのテストの`classifyTargetClass`を更新してください。このテストは、未分類のtarget idで意図的に失敗するため、新しいクラスが黙ってスキップされることはありません。 + - `src/secrets/exec-secret-ref-id-parity.test.ts`は、registryメタデータ（`listSecretTargetRegistryEntries()`）からSecretRefクラスごとに1つのサンプル対象を導出し、走査セグメントのexec IDが拒否されることを検証します。 + - `src/secrets/target-registry-data.ts`に新しい`includeInPlan` SecretRef target familyを追加する場合は、そのテスト内の`classifyTargetClass`を更新してください。このテストは、分類されていないtarget IDに対して意図的に失敗するため、新しいクラスが黙ってスキップされることを防ぎます。 diff --git a/docs/ja-JP/help/troubleshooting.md b/docs/ja-JP/help/troubleshooting.md index ce5601c56..64ed64b00 100644 --- a/docs/ja-JP/help/troubleshooting.md +++ b/docs/ja-JP/help/troubleshooting.md @@ -1,14 +1,14 @@ --- read_when: - - OpenClaw が動作しておらず、最短で解決する方法が必要な場合 - - 詳細な手順に入る前にトリアージの流れを確認したい場合 + - OpenClaw が動作しておらず、最も早く解決する方法が必要です + - 詳細なランブックに入る前にトリアージフローが必要です summary: OpenClaw の症状別トラブルシューティングハブ title: 一般的なトラブルシューティング x-i18n: - generated_at: "2026-04-08T02:16:48Z" + generated_at: "2026-04-11T02:46:01Z" model: gpt-5.4 provider: openai - source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3 + source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a source_path: help/troubleshooting.md workflow: 15 --- @@ -19,7 +19,7 @@ x-i18n: ## 最初の 60 秒 -この順番どおりに、次のコマンドを実行してください。 +次の手順をこの順番でそのまま実行してください。 ```bash openclaw status @@ -31,47 +31,49 @@ openclaw channels status --probe openclaw logs --follow ``` -良い出力の目安: +良好な出力の目安: -- `openclaw status` → 設定済みチャネルが表示され、明らかな認証エラーがない。 -- `openclaw status --all` → 完全なレポートが表示され、共有可能である。 -- `openclaw gateway probe` → 想定している Gateway ターゲットに到達できる（`Reachable: yes`）。`RPC: limited - missing scope: operator.read` は診断機能の劣化であり、接続失敗ではありません。 -- `openclaw gateway status` → `Runtime: running` と `RPC probe: ok`。 -- `openclaw doctor` → ブロッキングな設定 / サービスエラーがない。 -- `openclaw channels status --probe` → 到達可能な Gateway は、アカウントごとの live な - transport 状態に加えて、`works` や `audit ok` などの probe / audit 結果を返します。Gateway に到達できない場合、このコマンドは設定のみのサマリーにフォールバックします。 -- `openclaw logs --follow` → 安定したアクティビティがあり、繰り返す致命的エラーがない。 +- `openclaw status` → 設定済みの channels が表示され、明らかな認証エラーがない。 +- `openclaw status --all` → 完全なレポートが表示され、共有可能な状態である。 +- `openclaw gateway probe` → 想定される gateway target に到達できる（`Reachable: yes`）。`RPC: limited - missing scope: operator.read` は診断機能の劣化であり、接続失敗ではありません。 +- `openclaw gateway status` → `Runtime: running` かつ `RPC probe: ok`。 +- `openclaw doctor` → 起動を妨げる config/service エラーがない。 +- `openclaw channels status --probe` → 到達可能な gateway では、account ごとの live な + transport 状態に加え、`works` や `audit ok` などの probe/audit 結果が返ります。gateway に到達できない場合、 + このコマンドは config のみの要約にフォールバックします。 +- `openclaw logs --follow` → 安定したアクティビティがあり、繰り返し発生する致命的エラーがない。 -## Anthropic の長いコンテキストでの 429 +## Anthropic long context 429 -次のエラーが表示される場合: +次の表示が出る場合: `HTTP 429: rate_limit_error: Extra usage is required for long context requests` -[/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/ja-JP/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context) を参照してください。 +[/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/ja-JP/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context) に進んでください。 -## ローカルの OpenAI 互換バックエンドは直接では動くが、OpenClaw では失敗する +## ローカルの OpenAI 互換バックエンドは直接では動くが OpenClaw では失敗する ローカルまたはセルフホストの `/v1` バックエンドが、小さな直接の -`/v1/chat/completions` プローブには応答するのに、`openclaw infer model run` や通常の -エージェントターンでは失敗する場合: +`/v1/chat/completions` プローブには応答するものの、`openclaw infer model run` や通常の +agent ターンでは失敗する場合: -1. エラーに `messages[].content` が文字列であることを期待するとある場合は、 - `models.providers..models[].compat.requiresStringContent: true` を設定してください。 -2. それでも OpenClaw のエージェントターンでのみバックエンドが失敗する場合は、 - `models.providers..models[].compat.supportsTools: false` を設定して再試行してください。 -3. 小さな直接呼び出しは依然として動作するのに、より大きな OpenClaw プロンプトでバックエンドがクラッシュする場合は、 - 残る問題を上流のモデル / サーバーの制限として扱い、詳細な手順に進んでください: +1. エラーに `messages[].content` が文字列を期待していると出る場合は、 + `models.providers..models[].compat.requiresStringContent: true` を設定します。 +2. それでも OpenClaw の agent ターンでのみバックエンドが失敗する場合は、 + `models.providers..models[].compat.supportsTools: false` を設定して再試行します。 +3. 小さな直接呼び出しは依然として成功するのに、大きな OpenClaw プロンプトでバックエンドがクラッシュする場合、 + 残る問題は upstream の model/server の制限として扱い、 + 詳細ランブックに進んでください: [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/ja-JP/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) -## openclaw extensions の不足でプラグインのインストールに失敗する +## Plugin のインストールが openclaw extensions 不足で失敗する -`package.json missing openclaw.extensions` でインストールが失敗する場合、そのプラグインパッケージは -OpenClaw が現在受け付けない古い形式を使っています。 +インストールが `package.json missing openclaw.extensions` で失敗する場合、その plugin package +は OpenClaw が現在受け付けない古い形式を使用しています。 -プラグインパッケージでの修正方法: +plugin package 側で修正する内容: 1. `package.json` に `openclaw.extensions` を追加します。 -2. エントリをビルド済みランタイムファイル（通常は `./dist/index.js`）に向けます。 -3. プラグインを再公開し、`openclaw plugins install ` を再度実行します。 +2. エントリをビルド済み runtime ファイル（通常は `./dist/index.js`）に向けます。 +3. plugin を再公開し、`openclaw plugins install ` を再実行します。 例: @@ -85,9 +87,9 @@ OpenClaw が現在受け付けない古い形式を使っています。 } ``` -参考: [プラグインアーキテクチャ](/ja-JP/plugins/architecture) +参考: [Plugin architecture](/ja-JP/plugins/architecture) -## 決定木 +## デシジョンツリー ```mermaid flowchart TD @@ -110,7 +112,7 @@ flowchart TD ``` - + ```bash openclaw status openclaw gateway status @@ -119,18 +121,18 @@ flowchart TD openclaw logs --follow ``` - 良い出力の目安: + 良好な出力の目安: - `Runtime: running` - `RPC probe: ok` - - 対象チャネルで transport connected が表示され、サポートされている場合は `channels status --probe` に `works` または `audit ok` が表示される - - 送信者が承認済みである（または DM ポリシーが open / allowlist である） + - 使用中の channel が transport connected を示し、サポートされる場合は `channels status --probe` に `works` または `audit ok` が表示される + - 送信者が承認済みとして表示される（または DM policy が open/allowlist になっている） よくあるログシグネチャ: - - `drop guild message (mention required` → Discord で mention gating によりメッセージがブロックされた。 - - `pairing request` → 送信者が未承認で、DM pairing 承認待ちになっている。 - - チャネルログ内の `blocked` / `allowlist` → 送信者、room、または group がフィルタリングされている。 + - `drop guild message (mention required` → Discord でメンションゲートによりメッセージ処理がブロックされた。 + - `pairing request` → 送信者が未承認で、DM pairing 承認待ちである。 + - channel ログ内の `blocked` / `allowlist` → 送信者、room、または group がフィルタされている。 詳細ページ: @@ -140,7 +142,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -149,7 +151,7 @@ flowchart TD openclaw channels status --probe ``` - 良い出力の目安: + 良好な出力の目安: - `openclaw gateway status` に `Dashboard: http://...` が表示される - `RPC probe: ok` @@ -157,18 +159,17 @@ flowchart TD よくあるログシグネチャ: - - `device identity required` → HTTP / 非セキュアコンテキストでは device auth を完了できない。 - - `origin not allowed` → ブラウザの `Origin` が Control UI の - Gateway ターゲットで許可されていない。 - - `AUTH_TOKEN_MISMATCH` と再試行ヒント（`canRetryWithDeviceToken=true`）→ 信頼済み device-token による再試行が 1 回だけ自動で行われることがある。 - - そのキャッシュ済みトークン再試行では、ペアリング済み - device token と一緒に保存されたキャッシュ済みスコープセットが再利用される。明示的な `deviceToken` / 明示的な `scopes` の呼び出し元は、要求したスコープセットをそのまま維持する。 - - 非同期 Tailscale Serve の Control UI 経路では、同じ - `{scope, ip}` に対する失敗試行は、limiter が失敗を記録する前に直列化されるため、2 回目の同時の不正な再試行でもすでに `retry later` が表示されることがある。 - - localhost の - ブラウザ origin からの `too many failed authentication attempts (retry later)` → 同じ `Origin` からの繰り返し失敗は一時的にロックアウトされる。別の localhost origin は別バケットを使用する。 - - その再試行後も繰り返される `unauthorized` → トークン / パスワードの誤り、認証モード不一致、または古いペアリング済み device token。 - - `gateway connect failed:` → UI が誤った URL / ポートを参照しているか、Gateway に到達できない。 + - `device identity required` → HTTP/非セキュアコンテキストでは device auth を完了できない。 + - `origin not allowed` → browser の `Origin` がその Control UI + gateway target で許可されていない。 + - `AUTH_TOKEN_MISMATCH` と再試行ヒント（`canRetryWithDeviceToken=true`）→ 信頼済み device-token による再試行が 1 回、自動で行われることがあります。 + - そのキャッシュ済み token の再試行では、ペアリング済み + device token とともに保存されたキャッシュ済みスコープセットが再利用されます。明示的な `deviceToken` / 明示的な `scopes` を使う呼び出し元は、要求したスコープセットがそのまま維持されます。 + - 非同期の Tailscale Serve Control UI パスでは、同じ + `{scope, ip}` に対する失敗した試行は、limiter が失敗を記録する前に直列化されるため、2 回目の同時不正再試行でもすでに `retry later` が表示されることがあります。 + - localhost browser origin からの `too many failed authentication attempts (retry later)` → 同じ `Origin` からの繰り返し失敗は一時的にロックアウトされます。別の localhost origin は別バケットを使用します。 + - その再試行後も `unauthorized` が繰り返される → token/password の誤り、auth mode の不一致、または古い paired device token。 + - `gateway connect failed:` → UI が誤った URL/port を向いているか、gateway に到達できません。 詳細ページ: @@ -178,7 +179,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -187,7 +188,7 @@ flowchart TD openclaw channels status --probe ``` - 良い出力の目安: + 良好な出力の目安: - `Service: ... (loaded)` - `Runtime: running` @@ -195,9 +196,9 @@ flowchart TD よくあるログシグネチャ: - - `Gateway start blocked: set gateway.mode=local` または `existing config is missing gateway.mode` → gateway モードが remote になっているか、設定ファイルに local-mode の印がなく、修復が必要。 - - `refusing to bind gateway ... without auth` → 有効な Gateway 認証経路（token / password、または設定済み trusted-proxy）がない状態で non-loopback bind をしようとしている。 - - `another gateway instance is already listening` または `EADDRINUSE` → ポートがすでに使用されている。 + - `Gateway start blocked: set gateway.mode=local` または `existing config is missing gateway.mode` → gateway mode が remote、または config file に local-mode の印がなく、修復が必要。 + - `refusing to bind gateway ... without auth` → 有効な gateway auth パス（token/password、または設定されている trusted-proxy）なしで non-loopback bind をしようとしている。 + - `another gateway instance is already listening` または `EADDRINUSE` → その port はすでに使用中。 詳細ページ: @@ -207,7 +208,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -216,17 +217,17 @@ flowchart TD openclaw channels status --probe ``` - 良い出力の目安: + 良好な出力の目安: - - チャネル transport が接続されている。 - - Pairing / allowlist チェックが通る。 - - 必要な場所で mention が検出される。 + - Channel transport が接続されている。 + - Pairing/allowlist チェックに合格している。 + - 必要な場合にメンションが検出されている。 よくあるログシグネチャ: - - `mention required` → group mention gating により処理がブロックされた。 - - `pairing` / `pending` → DM 送信者がまだ承認されていない。 - - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → チャネル権限トークンの問題。 + - `mention required` → group mention ゲートにより処理がブロックされた。 + - `pairing` / `pending` → DM の送信者がまだ承認されていない。 + - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → channel 権限 token の問題。 詳細ページ: @@ -235,7 +236,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -245,30 +246,31 @@ flowchart TD openclaw logs --follow ``` - 良い出力の目安: + 良好な出力の目安: - - `cron.status` が有効で、次回 wake が表示される。 + - `cron.status` が有効状態で次回 wake を示している。 - `cron runs` に最近の `ok` エントリが表示される。 - Heartbeat が有効で、active hours の外ではない。 よくあるログシグネチャ: -- `cron: scheduler disabled; jobs will not run automatically` → cron が無効。 -- `heartbeat skipped` with `reason=quiet-hours` → 設定された active hours の外。 -- `heartbeat skipped` with `reason=empty-heartbeat-file` → `HEARTBEAT.md` は存在するが、空行またはヘッダーのみのひな形しか含まれていない。 -- `heartbeat skipped` with `reason=no-tasks-due` → `HEARTBEAT.md` のタスクモードは有効だが、まだどのタスク間隔も期限になっていない。 -- `heartbeat skipped` with `reason=alerts-disabled` → heartbeat の可視性がすべて無効（`showOk`、`showAlerts`、`useIndicator` がすべてオフ）。 -- `requests-in-flight` → メインレーンがビジー。heartbeat wake は延期された。 - `unknown accountId` → heartbeat 配信先のアカウントが存在しない。 + - `cron: scheduler disabled; jobs will not run automatically` → cron が無効。 + - `heartbeat skipped` と `reason=quiet-hours` → 設定された active hours の外。 + - `heartbeat skipped` と `reason=empty-heartbeat-file` → `HEARTBEAT.md` は存在するが、空白またはヘッダーのみの足場しか含まれていない。 + - `heartbeat skipped` と `reason=no-tasks-due` → `HEARTBEAT.md` の task モードが有効だが、まだ期限の来ている task interval がない。 + - `heartbeat skipped` と `reason=alerts-disabled` → heartbeat の可視性がすべて無効（`showOk`、`showAlerts`、`useIndicator` がすべて off）。 + - `requests-in-flight` → main レーンがビジーで、heartbeat wake が延期された。 + - `unknown accountId` → heartbeat の配信先 account が存在しない。 - 詳細ページ: + 詳細ページ: - - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/ja-JP/gateway/troubleshooting#cron-and-heartbeat-delivery) - - [/automation/cron-jobs#troubleshooting](/ja-JP/automation/cron-jobs#troubleshooting) - - [/gateway/heartbeat](/ja-JP/gateway/heartbeat) + - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/ja-JP/gateway/troubleshooting#cron-and-heartbeat-delivery) + - [/automation/cron-jobs#troubleshooting](/ja-JP/automation/cron-jobs#troubleshooting) + - [/gateway/heartbeat](/ja-JP/gateway/heartbeat) - + ```bash openclaw status openclaw gateway status @@ -277,17 +279,17 @@ flowchart TD openclaw logs --follow ``` - 良い出力の目安: + 良好な出力の目安: - - Node が role `node` で接続済みかつペアリング済みとして表示される。 - - 呼び出しているコマンドの capability が存在する。 - - ツールの permission state が許可済みである。 + - Node が接続済みかつ role `node` で paired として一覧表示される。 + - 呼び出しているコマンドに対する capability が存在する。 + - その tool の permission state が許可済みである。 よくあるログシグネチャ: - - `NODE_BACKGROUND_UNAVAILABLE` → node アプリをフォアグラウンドにしてください。 - - `*_PERMISSION_REQUIRED` → OS 権限が拒否されたか不足している。 - - `SYSTEM_RUN_DENIED: approval required` → exec 承認待ち。 + - `NODE_BACKGROUND_UNAVAILABLE` → node app をフォアグラウンドに戻す。 + - `*_PERMISSION_REQUIRED` → OS 権限が拒否されている、または不足している。 + - `SYSTEM_RUN_DENIED: approval required` → exec approval が保留中。 - `SYSTEM_RUN_DENIED: allowlist miss` → コマンドが exec allowlist にない。 詳細ページ: @@ -298,7 +300,7 @@ flowchart TD - + ```bash openclaw config get tools.exec.host openclaw config get tools.exec.security @@ -306,16 +308,16 @@ flowchart TD openclaw gateway restart ``` - 何が変わったのか: + 何が変わったか: - - `tools.exec.host` が未設定の場合、デフォルトは `auto`。 - - `host=auto` は、sandbox ランタイムが有効なときは `sandbox`、それ以外は `gateway` に解決される。 - - `host=auto` はルーティングのみ。確認なしの「YOLO」動作は、gateway / node 上の `security=full` と `ask=off` によるもの。 - - `gateway` と `node` では、未設定の `tools.exec.security` のデフォルトは `full`。 - - 未設定の `tools.exec.ask` のデフォルトは `off`。 - - 結果として、承認が表示されている場合は、何らかのホストローカルまたはセッション単位のポリシーが、現在のデフォルトよりも exec を厳しくしたことを意味する。 + - `tools.exec.host` が未設定の場合、デフォルトは `auto` です。 + - `host=auto` は、sandbox runtime がアクティブなときは `sandbox` に、そうでない場合は `gateway` に解決されます。 + - `host=auto` はルーティングだけの設定です。プロンプトなしの「YOLO」動作は、gateway/node 上の `security=full` と `ask=off` によって決まります。 + - `gateway` と `node` では、未設定の `tools.exec.security` のデフォルトは `full` です。 + - 未設定の `tools.exec.ask` のデフォルトは `off` です。 + - したがって、approval が表示されているなら、現在のデフォルトから外れるように host ローカルまたはセッション単位の policy が強化されたことを意味します。 - 現在のデフォルトの承認不要動作に戻す: + 現在のデフォルトである approval なしの動作を復元する: ```bash openclaw config set tools.exec.host gateway @@ -326,25 +328,25 @@ flowchart TD より安全な代替案: - - ホストルーティングを安定させたいだけなら `tools.exec.host=gateway` のみを設定する。 - - ホスト exec を使いつつ allowlist ミス時に確認もしたい場合は、`security=allowlist` と `ask=on-miss` を使う。 - - `host=auto` を再び `sandbox` に解決させたい場合は、sandbox モードを有効にする。 + - host ルーティングを安定させたいだけなら、`tools.exec.host=gateway` のみを設定します。 + - host exec を使いつつ allowlist ミス時にはレビューしたい場合は、`security=allowlist` と `ask=on-miss` を使います。 + - `host=auto` が再び `sandbox` に解決されるようにしたい場合は、sandbox mode を有効にします。 よくあるログシグネチャ: - - `Approval required.` → コマンドが `/approve ...` を待っている。 - - `SYSTEM_RUN_DENIED: approval required` → node-host exec の承認待ち。 - - `exec host=sandbox requires a sandbox runtime for this session` → 暗黙的または明示的に sandbox が選択されているが、sandbox モードがオフ。 + - `Approval required.` → コマンドが `/approve ...` を待っています。 + - `SYSTEM_RUN_DENIED: approval required` → node-host exec approval が保留中です。 + - `exec host=sandbox requires a sandbox runtime for this session` → 暗黙または明示的に sandbox が選択されているが、sandbox mode が無効です。 詳細ページ: - [/tools/exec](/ja-JP/tools/exec) - [/tools/exec-approvals](/ja-JP/tools/exec-approvals) - - [/gateway/security#runtime-expectation-drift](/ja-JP/gateway/security#runtime-expectation-drift) + - [/gateway/security#what-the-audit-checks-high-level](/ja-JP/gateway/security#what-the-audit-checks-high-level) - + ```bash openclaw status openclaw gateway status @@ -353,22 +355,22 @@ flowchart TD openclaw doctor ``` - 良い出力の目安: + 良好な出力の目安: - - Browser status に `running: true` と、選択された browser / profile が表示される。 + - Browser status に `running: true` と選択された browser/profile が表示される。 - `openclaw` が起動する、または `user` がローカルの Chrome タブを確認できる。 よくあるログシグネチャ: - - `unknown command "browser"` または `unknown command 'browser'` → `plugins.allow` が設定されており、`browser` が含まれていない。 - - `Failed to start Chrome CDP on port` → ローカル browser の起動に失敗した。 - - `browser.executablePath not found` → 設定されたバイナリパスが誤っている。 - - `browser.cdpUrl must be http(s) or ws(s)` → 設定された CDP URL がサポートされないスキームを使っている。 - - `browser.cdpUrl has invalid port` → 設定された CDP URL のポートが不正または範囲外。 - - `No Chrome tabs found for profile="user"` → Chrome MCP attach profile に開いているローカル Chrome タブがない。 - - `Remote CDP for profile "" is not reachable` → 設定された remote CDP endpoint にこのホストから到達できない。 - - `Browser attachOnly is enabled ... not reachable` または `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile に live な CDP ターゲットがない。 - - attach-only または remote CDP profile で viewport / dark-mode / locale / offline の上書きが古いまま残っている → `openclaw browser stop --browser-profile ` を実行して、Gateway を再起動せずにアクティブな control session を閉じ、emulation state を解放してください。 + - `unknown command "browser"` または `unknown command 'browser'` → `plugins.allow` が設定されており、`browser` が含まれていません。 + - `Failed to start Chrome CDP on port` → ローカル browser の起動に失敗しました。 + - `browser.executablePath not found` → 設定されたバイナリパスが誤っています。 + - `browser.cdpUrl must be http(s) or ws(s)` → 設定された CDP URL に未対応のスキームが使われています。 + - `browser.cdpUrl has invalid port` → 設定された CDP URL の port が不正または範囲外です。 + - `No Chrome tabs found for profile="user"` → Chrome MCP attach profile に開いているローカル Chrome タブがありません。 + - `Remote CDP for profile "" is not reachable` → 設定されたリモート CDP エンドポイントにこのホストから到達できません。 + - `Browser attachOnly is enabled ... not reachable` または `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile に有効な CDP target がありません。 + - attach-only または remote CDP profile で viewport / dark-mode / locale / offline の上書き状態が残っている → gateway を再起動せずに `openclaw browser stop --browser-profile ` を実行して、アクティブな制御セッションを閉じ、エミュレーション状態を解放します。 詳細ページ: @@ -378,6 +380,7 @@ flowchart TD - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/ja-JP/tools/browser-wsl2-windows-remote-cdp-troubleshooting) + ## 関連 @@ -385,5 +388,5 @@ flowchart TD - [FAQ](/ja-JP/help/faq) — よくある質問 - [Gateway Troubleshooting](/ja-JP/gateway/troubleshooting) — Gateway 固有の問題 - [Doctor](/ja-JP/gateway/doctor) — 自動ヘルスチェックと修復 -- [Channel Troubleshooting](/ja-JP/channels/troubleshooting) — チャネル接続の問題 +- [Channel Troubleshooting](/ja-JP/channels/troubleshooting) — channel 接続の問題 - [Automation Troubleshooting](/ja-JP/automation/cron-jobs#troubleshooting) — cron と heartbeat の問題 diff --git a/docs/ja-JP/plugins/codex-harness.md b/docs/ja-JP/plugins/codex-harness.md new file mode 100644 index 000000000..5b388bd6f --- /dev/null +++ b/docs/ja-JP/plugins/codex-harness.md @@ -0,0 +1,488 @@ +--- +read_when: + - バンドルされた Codex app-server ハーネスを使いたい場合 + - Codex のモデル参照と設定例が必要です + - Codex 専用デプロイ向けに PI フォールバックを無効にしたい場合 +summary: バンドルされた Codex app-server ハーネスを通じて OpenClaw の埋め込みエージェントターンを実行する +title: Codex ハーネス +x-i18n: + generated_at: "2026-04-11T02:46:08Z" + model: gpt-5.4 + provider: openai + source_hash: 60e1dcf4f1a00c63c3ef31d72feac44bce255421c032c58fa4fd67295b3daf23 + source_path: plugins/codex-harness.md + workflow: 15 +--- + +# Codex ハーネス + +バンドルされた `codex` plugin により、OpenClaw は組み込み PI ハーネスの代わりに +Codex app-server を通して埋め込みエージェントターンを実行できます。 + +これは、低レベルのエージェントセッションを Codex に担わせたい場合に使用します: モデル +ディスカバリー、ネイティブスレッド再開、ネイティブ compaction、app-server 実行です。 +OpenClaw は引き続き、チャットチャネル、セッションファイル、モデル選択、ツール、 +approvals、メディア配信、および可視のトランスクリプトミラーを管理します。 + +このハーネスはデフォルトでオフです。`codex` plugin が +有効で、解決されたモデルが `codex/*` モデルである場合、または +`embeddedHarness.runtime: "codex"` か `OPENCLAW_AGENT_RUNTIME=codex` を明示的に強制した場合にのみ選択されます。 +`codex/*` を一切設定しなければ、既存の PI、OpenAI、Anthropic、Gemini、local、 +および custom-provider の実行は現在の動作を維持します。 + +## 正しいモデルプレフィックスを選ぶ + +OpenClaw には、OpenAI アクセス用と Codex 形式アクセス用の別々の経路があります: + +| モデル参照 | ランタイム経路 | 使用する場面 | +| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | +| `openai/gpt-5.4` | OpenClaw/PI 配線を通る OpenAI provider | `OPENAI_API_KEY` を使った直接の OpenAI Platform API アクセスが必要な場合。 | +| `openai-codex/gpt-5.4` | PI を通る OpenAI Codex OAuth provider | Codex app-server ハーネスなしで ChatGPT/Codex OAuth を使いたい場合。 | +| `codex/gpt-5.4` | バンドルされた Codex provider + Codex ハーネス | 埋め込みエージェントターンでネイティブな Codex app-server 実行を使いたい場合。 | + +Codex ハーネスが引き受けるのは `codex/*` モデル参照だけです。既存の `openai/*`、 +`openai-codex/*`、Anthropic、Gemini、xAI、local、および custom provider 参照は、 +通常の経路のままです。 + +## 要件 + +- バンドルされた `codex` plugin が利用可能な OpenClaw。 +- Codex app-server `0.118.0` 以降。 +- app-server プロセスで利用可能な Codex auth。 + +この plugin は、古い app-server ハンドシェイクまたはバージョンなしの app-server ハンドシェイクをブロックします。これにより、 +OpenClaw はテスト済みのプロトコルサーフェス上に保たれます。 + +ライブおよび Docker スモークテストでは、auth は通常 `OPENAI_API_KEY` と、 +必要に応じて `~/.codex/auth.json` や +`~/.codex/config.toml` のような Codex CLI ファイルから取得されます。ローカルの Codex app-server と同じ auth 情報を使ってください。 + +## 最小構成 + +`codex/gpt-5.4` を使用し、バンドルされた plugin を有効化し、`codex` ハーネスを強制します: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + }, + }, + }, + agents: { + defaults: { + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + }, +} +``` + +設定で `plugins.allow` を使用している場合は、そこにも `codex` を含めてください: + +```json5 +{ + plugins: { + allow: ["codex"], + entries: { + codex: { + enabled: true, + }, + }, + }, +} +``` + +`agents.defaults.model` またはエージェントモデルを `codex/` に設定しても、 +バンドルされた `codex` plugin は自動的に有効になります。明示的な plugin エントリは、 +共有設定でデプロイ意図を明確に示せるため、依然として有用です。 + +## 他のモデルを置き換えずに Codex を追加する + +`codex/*` モデルには Codex、その他すべてには PI を使いたい場合は `runtime: "auto"` のままにします: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + }, + }, + }, + agents: { + defaults: { + model: { + primary: "codex/gpt-5.4", + fallbacks: ["openai/gpt-5.4", "anthropic/claude-opus-4-6"], + }, + models: { + "codex/gpt-5.4": { alias: "codex" }, + "codex/gpt-5.4-mini": { alias: "codex-mini" }, + "openai/gpt-5.4": { alias: "gpt" }, + "anthropic/claude-opus-4-6": { alias: "opus" }, + }, + embeddedHarness: { + runtime: "auto", + fallback: "pi", + }, + }, + }, +} +``` + +この構成では: + +- `/model codex` または `/model codex/gpt-5.4` は Codex app-server ハーネスを使用します。 +- `/model gpt` または `/model openai/gpt-5.4` は OpenAI provider 経路を使用します。 +- `/model opus` は Anthropic provider 経路を使用します。 +- Codex 以外のモデルが選択された場合、PI は互換性ハーネスのままです。 + +## Codex 専用デプロイ + +すべての埋め込みエージェントターンが +Codex ハーネスを使うことを保証したい場合は、PI フォールバックを無効にします: + +```json5 +{ + agents: { + defaults: { + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + }, +} +``` + +環境変数での上書き: + +```bash +OPENCLAW_AGENT_RUNTIME=codex \ +OPENCLAW_AGENT_HARNESS_FALLBACK=none \ +openclaw gateway run +``` + +フォールバックを無効にすると、Codex plugin が無効、 +要求されたモデルが `codex/*` 参照ではない、app-server が古すぎる、または +app-server を起動できない場合に、OpenClaw は早い段階で失敗します。 + +## エージェントごとの Codex + +あるエージェントだけを Codex 専用にしつつ、デフォルトエージェントは通常の +自動選択を維持できます: + +```json5 +{ + agents: { + defaults: { + embeddedHarness: { + runtime: "auto", + fallback: "pi", + }, + }, + list: [ + { + id: "main", + default: true, + model: "anthropic/claude-opus-4-6", + }, + { + id: "codex", + name: "Codex", + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + ], + }, +} +``` + +通常のセッションコマンドを使ってエージェントとモデルを切り替えます。`/new` は新しい +OpenClaw セッションを作成し、Codex ハーネスは必要に応じてその sidecar app-server +スレッドを作成または再開します。`/reset` はそのスレッドの OpenClaw セッションバインディングをクリアします。 + +## モデルディスカバリー + +デフォルトでは、Codex plugin は利用可能なモデルを app-server に問い合わせます。 +ディスカバリーが失敗するかタイムアウトした場合は、バンドルされたフォールバックカタログを使用します: + +- `codex/gpt-5.4` +- `codex/gpt-5.4-mini` +- `codex/gpt-5.2` + +ディスカバリーは `plugins.entries.codex.config.discovery` で調整できます: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + discovery: { + enabled: true, + timeoutMs: 2500, + }, + }, + }, + }, + }, +} +``` + +起動時に Codex を probe せず、フォールバックカタログに固定したい場合は、 +ディスカバリーを無効にします: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + discovery: { + enabled: false, + }, + }, + }, + }, + }, +} +``` + +## app-server 接続とポリシー + +デフォルトでは、この plugin は次のコマンドでローカルに Codex を起動します: + +```bash +codex app-server --listen stdio:// +``` + +このデフォルトを維持しつつ、Codex ネイティブポリシーだけを調整できます: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + approvalPolicy: "on-request", + sandbox: "workspace-write", + serviceTier: "priority", + }, + }, + }, + }, + }, +} +``` + +すでに起動中の app-server には、WebSocket トランスポートを使用します: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + transport: "websocket", + url: "ws://127.0.0.1:39175", + authToken: "${CODEX_APP_SERVER_TOKEN}", + requestTimeoutMs: 60000, + }, + }, + }, + }, + }, +} +``` + +サポートされる `appServer` フィールド: + +| フィールド | デフォルト | 意味 | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` は Codex を起動します。`"websocket"` は `url` に接続します。 | +| `command` | `"codex"` | stdio トランスポート用の実行ファイル。 | +| `args` | `["app-server", "--listen", "stdio://"]` | stdio トランスポート用の引数。 | +| `url` | 未設定 | WebSocket app-server URL。 | +| `authToken` | 未設定 | WebSocket トランスポート用の Bearer token。 | +| `headers` | `{}` | 追加の WebSocket ヘッダー。 | +| `requestTimeoutMs` | `60000` | app-server コントロールプレーン呼び出しのタイムアウト。 | +| `approvalPolicy` | `"never"` | スレッド start/resume/turn に送信されるネイティブ Codex approval policy。 | +| `sandbox` | `"workspace-write"` | スレッド start/resume に送信されるネイティブ Codex sandbox モード。 | +| `approvalsReviewer` | `"user"` | ネイティブ approvals を Codex guardian にレビューさせるには `"guardian_subagent"` を使用します。 | +| `serviceTier` | 未設定 | 任意の Codex service tier。たとえば `"priority"`。 | + +古い環境変数も、対応する設定フィールドが未設定なら、 +ローカルテスト用のフォールバックとして引き続き利用できます: + +- `OPENCLAW_CODEX_APP_SERVER_BIN` +- `OPENCLAW_CODEX_APP_SERVER_ARGS` +- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` +- `OPENCLAW_CODEX_APP_SERVER_SANDBOX` +- `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` + +再現可能なデプロイには設定の使用が推奨されます。 + +## よくあるレシピ + +デフォルトの stdio トランスポートを使うローカル Codex: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + }, + }, + }, +} +``` + +PI フォールバックを無効にした Codex 専用ハーネスの検証: + +```json5 +{ + embeddedHarness: { + fallback: "none", + }, + plugins: { + entries: { + codex: { + enabled: true, + }, + }, + }, +} +``` + +guardian レビュー付き Codex approvals: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + approvalPolicy: "on-request", + approvalsReviewer: "guardian_subagent", + sandbox: "workspace-write", + }, + }, + }, + }, + }, +} +``` + +明示的なヘッダー付きのリモート app-server: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + transport: "websocket", + url: "ws://gateway-host:39175", + headers: { + "X-OpenClaw-Agent": "main", + }, + }, + }, + }, + }, + }, +} +``` + +モデル切り替えは引き続き OpenClaw が制御します。OpenClaw セッションが既存の Codex スレッドに接続されている場合、 +次のターンでは、現在選択されている +`codex/*` モデル、provider、approval policy、sandbox、および service tier が +再び app-server に送信されます。`codex/gpt-5.4` から `codex/gpt-5.2` に切り替えると、 +スレッドバインディングは維持されますが、Codex には新しく選択されたモデルで継続するよう要求します。 + +## Codex コマンド + +バンドルされた plugin は、認可されたスラッシュコマンドとして `/codex` を登録します。これは +汎用的で、OpenClaw のテキストコマンドをサポートする任意のチャネルで動作します。 + +一般的な形式: + +- `/codex status` は、ライブの app-server 接続性、モデル、アカウント、レート制限、MCP サーバー、および Skills を表示します。 +- `/codex models` は、ライブの Codex app-server モデルを一覧表示します。 +- `/codex threads [filter]` は、最近の Codex スレッドを一覧表示します。 +- `/codex resume ` は、現在の OpenClaw セッションを既存の Codex スレッドに接続します。 +- `/codex compact` は、接続されたスレッドの compaction を Codex app-server に要求します。 +- `/codex review` は、接続されたスレッドに対して Codex ネイティブレビューを開始します。 +- `/codex account` は、アカウントとレート制限の状態を表示します。 +- `/codex mcp` は、Codex app-server の MCP サーバー状態を一覧表示します。 +- `/codex skills` は、Codex app-server の Skills を一覧表示します。 + +`/codex resume` は、ハーネスが通常ターンで使用するものと同じ sidecar バインディングファイルを書き込みます。 +次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw の +`codex/*` モデルを app-server に渡し、拡張履歴を有効のまま維持します。 + +コマンドサーフェスには Codex app-server `0.118.0` 以降が必要です。将来版またはカスタム app-server がその JSON-RPC メソッドを公開していない場合、個々の +制御メソッドは `unsupported by this Codex app-server` として報告されます。 + +## ツール、メディア、および compaction + +Codex ハーネスが変更するのは、低レベルの埋め込みエージェント実行器のみです。 + +OpenClaw は引き続きツール一覧を構築し、ハーネスから動的なツール結果を受け取ります。テキスト、画像、動画、音楽、TTS、approvals、およびメッセージングツール出力は、 +通常どおり OpenClaw の配信経路を通ります。 + +選択されたモデルが Codex ハーネスを使う場合、ネイティブスレッド compaction は +Codex app-server に委譲されます。OpenClaw は、チャネル履歴、検索、`/new`、`/reset`、および将来のモデルまたはハーネス切り替えのために、トランスクリプトミラーを維持します。この +ミラーには、ユーザープロンプト、最終 assistant テキスト、および +app-server が出力した場合の軽量な Codex reasoning または plan レコードが含まれます。 + +メディア生成に PI は不要です。画像、動画、音楽、PDF、TTS、およびメディア理解は、 +引き続き `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel`、`messages.tts` のような対応する provider/model 設定を使用します。 + +## トラブルシューティング + +**`/model` に Codex が表示されない:** `plugins.entries.codex.enabled` を有効にし、 +`codex/*` モデル参照を設定するか、`plugins.allow` が `codex` を除外していないか確認してください。 + +**OpenClaw が PI にフォールバックする:** テスト中は `embeddedHarness.fallback: "none"` または +`OPENCLAW_AGENT_HARNESS_FALLBACK=none` を設定してください。 + +**app-server が拒否される:** app-server ハンドシェイクが +バージョン `0.118.0` 以降を報告するように Codex をアップグレードしてください。 + +**モデルディスカバリーが遅い:** `plugins.entries.codex.config.discovery.timeoutMs` +を下げるか、ディスカバリーを無効にしてください。 + +**WebSocket トランスポートがすぐに失敗する:** `appServer.url`、`authToken`、 +およびリモート app-server が同じ Codex app-server プロトコルバージョンを話していることを確認してください。 + +**Codex 以外のモデルが PI を使う:** それは想定どおりです。Codex ハーネスが引き受けるのは +`codex/*` モデル参照だけです。 + +## 関連 + +- [Agent Harness Plugins](/ja-JP/plugins/sdk-agent-harness) +- [Model Providers](/ja-JP/concepts/model-providers) +- [Configuration Reference](/ja-JP/gateway/configuration-reference) +- [Testing](/ja-JP/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/ja-JP/plugins/manifest.md b/docs/ja-JP/plugins/manifest.md index 6a4e38f7d..118c78f9d 100644 --- a/docs/ja-JP/plugins/manifest.md +++ b/docs/ja-JP/plugins/manifest.md @@ -1,23 +1,23 @@ --- read_when: - - OpenClawプラグインを構築している - - プラグイン設定スキーマを出荷する必要がある、またはプラグイン検証エラーをデバッグする必要がある -summary: プラグインマニフェスト + JSON Schema要件（厳格な設定検証） + - OpenClawプラグインを構築しています + - プラグイン設定スキーマを提供する必要がある、またはプラグイン検証エラーをデバッグする必要があります +summary: プラグインマニフェスト + JSONスキーマ要件（厳格な設定検証） title: プラグインマニフェスト x-i18n: - generated_at: "2026-04-09T01:29:46Z" + generated_at: "2026-04-11T02:46:37Z" model: gpt-5.4 provider: openai - source_hash: 9a7ee4b621a801d2a8f32f8976b0e1d9433c7810eb360aca466031fc0ffb286a + source_hash: 6b254c121d1eb5ea19adbd4148243cf47339c960442ab1ca0e0bfd52e0154c88 source_path: plugins/manifest.md workflow: 15 --- # プラグインマニフェスト（openclaw.plugin.json） -このページは**ネイティブOpenClawプラグインマニフェスト**専用です。 +このページは、**ネイティブなOpenClawプラグインマニフェスト**のみを対象としています。 -互換バンドルのレイアウトについては、[Plugin bundles](/ja-JP/plugins/bundles)を参照してください。 +互換性のあるバンドルレイアウトについては、[Plugin bundles](/ja-JP/plugins/bundles)を参照してください。 互換バンドル形式では、異なるマニフェストファイルを使用します。 @@ -27,36 +27,35 @@ x-i18n: OpenClawはそれらのバンドルレイアウトも自動検出しますが、ここで説明する`openclaw.plugin.json`スキーマに対しては検証されません。 -互換バンドルについて、OpenClawは現在、レイアウトがOpenClawランタイムの期待に一致する場合、バンドルメタデータに加えて、宣言されたskill root、Claude command root、Claudeバンドルの`settings.json`デフォルト、ClaudeバンドルのLSPデフォルト、およびサポートされるhook packを読み取ります。 +互換バンドルについては、OpenClawは現在、レイアウトがOpenClawランタイムの期待に一致している場合に、バンドルメタデータに加えて、宣言されたskill root、Claude command root、Claudeバンドルの`settings.json`デフォルト、ClaudeバンドルのLSPデフォルト、およびサポートされるhook packを読み取ります。 -すべてのネイティブOpenClawプラグインは、**plugin root**に`openclaw.plugin.json`ファイルを**必ず**含める必要があります。OpenClawはこのマニフェストを使って、**プラグインコードを実行せずに**設定を検証します。マニフェストがない、または無効な場合はプラグインエラーとして扱われ、設定検証がブロックされます。 +すべてのネイティブOpenClawプラグインは、**plugin root**に`openclaw.plugin.json`ファイルを含める**必要があります**。OpenClawはこのマニフェストを使って、**プラグインコードを実行せずに**設定を検証します。マニフェストが欠落している、または不正な場合はプラグインエラーとして扱われ、設定検証をブロックします。 -完全なプラグインシステムガイドは[Plugins](/ja-JP/tools/plugin)を参照してください。 -ネイティブのcapability modelと現在の外部互換性ガイダンスについては、 -[Capability model](/ja-JP/plugins/architecture#public-capability-model)を参照してください。 +完全なプラグインシステムガイドについては[Plugins](/ja-JP/tools/plugin)を参照してください。 +ネイティブなcapabilityモデルと現在の外部互換性ガイダンスについては、[Capability model](/ja-JP/plugins/architecture#public-capability-model)を参照してください。 ## このファイルの役割 -`openclaw.plugin.json`は、OpenClawがプラグインコードを読み込む前に読み取るメタデータです。 +`openclaw.plugin.json` は、OpenClawがプラグインコードを読み込む前に読むメタデータです。 用途: -- プラグインの識別 +- プラグインID - 設定検証 -- プラグインランタイムを起動しなくても利用可能であるべき認証およびオンボーディングメタデータ -- プラグインランタイムが読み込まれる前に解決されるべきエイリアスおよび自動有効化メタデータ -- ランタイムが読み込まれる前にプラグインを自動有効化すべき短縮モデルファミリー所有メタデータ -- 同梱互換配線およびコントラクトカバレッジに使う静的capability ownershipスナップショット -- ランタイムを読み込まずにカタログおよび検証サーフェスにマージされるべきチャンネル固有設定メタデータ +- プラグインランタイムを起動せずに利用可能であるべき認証およびオンボーディングメタデータ +- プラグインランタイムの読み込み前に解決されるべきエイリアスおよび自動有効化メタデータ +- ランタイム読み込み前にプラグインを自動有効化するための短縮形モデルファミリー所有メタデータ +- バンドル互換ワイヤリングおよびコントラクトカバレッジに使われる静的なcapability所有スナップショット +- ランタイムを読み込まずにcatalogおよび検証サーフェスへマージされるべきチャネル固有の設定メタデータ - 設定UIヒント -使わないでください: +使ってはいけない用途: - ランタイム動作の登録 -- コードエントリーポイントの宣言 -- npmインストールメタデータ +- コードentrypointの宣言 +- npm installメタデータ -それらはプラグインコードおよび`package.json`に属します。 +これらはプラグインコードと`package.json`に属します。 ## 最小例 @@ -71,13 +70,13 @@ OpenClawはそれらのバンドルレイアウトも自動検出しますが、 } ``` -## 詳細な例 +## リッチな例 ```json { "id": "openrouter", "name": "OpenRouter", - "description": "OpenRouter provider plugin", + "description": "OpenRouterプロバイダープラグイン", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -98,19 +97,19 @@ OpenClawはそれらのバンドルレイアウトも自動検出しますが、 "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "OpenRouter APIキー", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "OpenRouter APIキー", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "APIキー", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -129,57 +128,80 @@ OpenClawはそれらのバンドルレイアウトも自動検出しますが、 ## トップレベルフィールドリファレンス -| Field | Required | Type | 意味 | -| ----------------------------------- | -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Yes | `string` | 正式なplugin idです。このidは`plugins.entries.`で使われます。 | -| `configSchema` | Yes | `object` | このプラグイン設定用のインラインJSON Schemaです。 | -| `enabledByDefault` | No | `true` | 同梱プラグインをデフォルトで有効にすることを示します。省略するか、`true`以外の値を設定すると、プラグインはデフォルトで無効のままになります。 | -| `legacyPluginIds` | No | `string[]` | この正式plugin idに正規化される旧idです。 | -| `autoEnableWhenConfiguredProviders` | No | `string[]` | auth、config、またはmodel refでそれらが言及されたときにこのプラグインを自動有効化すべきprovider idです。 | -| `kind` | No | `"memory"` \| `"context-engine"` | `plugins.slots.*`で使われる排他的なプラグイン種別を宣言します。 | -| `channels` | No | `string[]` | このプラグインが所有するchannel idです。検出と設定検証に使われます。 | -| `providers` | No | `string[]` | このプラグインが所有するprovider idです。 | -| `modelSupport` | No | `object` | ランタイム前にプラグインを自動読み込みするために使われる、マニフェスト所有の短縮モデルファミリーメタデータです。 | -| `cliBackends` | No | `string[]` | このプラグインが所有するCLI推論バックエンドidです。明示的な設定参照からの起動時自動有効化に使われます。 | -| `providerAuthEnvVars` | No | `Record` | OpenClawがプラグインコードを読み込まずに確認できる、軽量なprovider-auth環境変数メタデータです。 | -| `providerAuthAliases` | No | `Record` | 認証参照に別のprovider idを再利用すべきprovider idです。たとえば、ベースproviderのAPIキーやauth profileを共有するコーディングproviderなどです。 | -| `channelEnvVars` | No | `Record` | OpenClawがプラグインコードを読み込まずに確認できる、軽量なchannel環境変数メタデータです。env駆動のchannelセットアップや、汎用起動/設定ヘルパーが見るべきauthサーフェスに使います。 | -| `providerAuthChoices` | No | `object[]` | オンボーディングpicker、preferred-provider解決、および単純なCLIフラグ配線のための軽量なauth choiceメタデータです。 | -| `contracts` | No | `object` | speech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search、およびtool ownership向けの静的な同梱capability snapshotです。 | -| `channelConfigs` | No | `Record` | ランタイムが読み込まれる前に検出および検証サーフェスにマージされる、マニフェスト所有のchannel設定メタデータです。 | -| `skills` | No | `string[]` | 読み込むSkillsディレクトリです。plugin rootからの相対パスです。 | -| `name` | No | `string` | 人間が読むためのプラグイン名です。 | -| `description` | No | `string` | プラグインサーフェスに表示される短い要約です。 | -| `version` | No | `string` | 参考情報としてのプラグインバージョンです。 | -| `uiHints` | No | `Record` | 設定フィールド用のUIラベル、プレースホルダー、機密性ヒントです。 | +| Field | Required | Type | What it means | +| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Yes | `string` | 正式なplugin idです。これは`plugins.entries.`で使われるidです。 | +| `configSchema` | Yes | `object` | このプラグイン設定用のインラインJSONスキーマです。 | +| `enabledByDefault` | No | `true` | バンドルされたプラグインをデフォルトで有効にすることを示します。省略するか、`true`以外の値を設定すると、プラグインはデフォルトで無効のままになります。 | +| `legacyPluginIds` | No | `string[]` | この正式plugin idに正規化されるレガシーidです。 | +| `autoEnableWhenConfiguredProviders` | No | `string[]` | 認証、設定、またはモデル参照でそれらのprovider idに言及されたときに、このプラグインを自動有効化すべきprovider idです。 | +| `kind` | No | `"memory"` \| `"context-engine"` | `plugins.slots.*`で使われる排他的なplugin kindを宣言します。 | +| `channels` | No | `string[]` | このプラグインが所有するchannel idです。検出と設定検証に使われます。 | +| `providers` | No | `string[]` | このプラグインが所有するprovider idです。 | +| `modelSupport` | No | `object` | ランタイムの前にプラグインを自動読み込みするために使われる、マニフェスト所有の短縮形モデルファミリーメタデータです。 | +| `cliBackends` | No | `string[]` | このプラグインが所有するCLI推論バックエンドidです。明示的な設定参照からの起動時自動有効化に使われます。 | +| `commandAliases` | No | `object[]` | このプラグインが所有するコマンド名で、ランタイム読み込み前にプラグイン対応の設定およびCLI診断を生成すべきものです。 | +| `providerAuthEnvVars` | No | `Record` | OpenClawがプラグインコードを読み込まずに調べられる、軽量なprovider認証envメタデータです。 | +| `providerAuthAliases` | No | `Record` | 認証参照のために別のprovider idを再利用すべきprovider idです。たとえば、ベースproviderのAPIキーや認証プロファイルを共有するcoding providerなどです。 | +| `channelEnvVars` | No | `Record` | OpenClawがプラグインコードを読み込まずに調べられる、軽量なchannel envメタデータです。env駆動のchannelセットアップや、汎用の起動/設定ヘルパーが認識すべき認証サーフェスに使用します。 | +| `providerAuthChoices` | No | `object[]` | オンボーディングピッカー、優先provider解決、単純なCLIフラグ配線のための軽量な認証選択メタデータです。 | +| `contracts` | No | `object` | speech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search、およびtool ownership向けの静的なバンドルcapabilityスナップショットです。 | +| `channelConfigs` | No | `Record` | ランタイム読み込み前に検出および検証サーフェスへマージされる、マニフェスト所有のchannel設定メタデータです。 | +| `skills` | No | `string[]` | plugin rootからの相対パスで指定する、読み込むSkillsディレクトリです。 | +| `name` | No | `string` | 人が読めるプラグイン名です。 | +| `description` | No | `string` | プラグインサーフェスに表示される短い要約です。 | +| `version` | No | `string` | 情報提供用のプラグインバージョンです。 | +| `uiHints` | No | `Record` | 設定フィールド用のUIラベル、プレースホルダー、およびsensitivityヒントです。 | ## providerAuthChoicesリファレンス -各`providerAuthChoices`エントリーは、1つのオンボーディングまたは認証選択肢を記述します。 -OpenClawはこれをproviderランタイムが読み込まれる前に読み取ります。 +各`providerAuthChoices`エントリーは、1つのオンボーディングまたは認証の選択肢を記述します。 +OpenClawはこれをproviderランタイムの読み込み前に読み取ります。 -| Field | Required | Type | 意味 | -| --------------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- | -| `provider` | Yes | `string` | このchoiceが属するprovider idです。 | -| `method` | Yes | `string` | ディスパッチ先のauth method idです。 | -| `choiceId` | Yes | `string` | オンボーディングおよびCLIフローで使われる安定したauth-choice idです。 | -| `choiceLabel` | No | `string` | ユーザー向けラベルです。省略した場合、OpenClawは`choiceId`へフォールバックします。 | -| `choiceHint` | No | `string` | picker用の短い補助テキストです。 | -| `assistantPriority` | No | `number` | assistant主導の対話型pickerで、値が小さいほど先に並びます。 | -| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | assistant pickerからは隠しつつ、手動CLI選択は引き続き許可します。 | -| `deprecatedChoiceIds` | No | `string[]` | この置き換えchoiceへユーザーをリダイレクトすべき旧choice idです。 | -| `groupId` | No | `string` | 関連するchoiceをグループ化するための任意のgroup idです。 | -| `groupLabel` | No | `string` | そのグループのユーザー向けラベルです。 | -| `groupHint` | No | `string` | グループ用の短い補助テキストです。 | -| `optionKey` | No | `string` | 単一フラグの単純なauthフロー用の内部option keyです。 | -| `cliFlag` | No | `string` | `--openrouter-api-key`のようなCLIフラグ名です。 | -| `cliOption` | No | `string` | `--openrouter-api-key `のような完全なCLIオプション形状です。 | -| `cliDescription` | No | `string` | CLIヘルプで使われる説明です。 | -| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | このchoiceを表示すべきオンボーディングサーフェスです。省略した場合、`["text-inference"]`がデフォルトになります。 | +| Field | Required | Type | What it means | +| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | Yes | `string` | この選択肢が属するprovider id。 | +| `method` | Yes | `string` | ディスパッチ先の認証method id。 | +| `choiceId` | Yes | `string` | オンボーディングおよびCLIフローで使われる安定した認証選択id。 | +| `choiceLabel` | No | `string` | ユーザー向けラベル。省略した場合、OpenClawは`choiceId`にフォールバックします。 | +| `choiceHint` | No | `string` | ピッカー向けの短い補助テキスト。 | +| `assistantPriority` | No | `number` | assistant主導の対話型ピッカーで、値が小さいほど先に並びます。 | +| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | assistantピッカーではこの選択肢を非表示にしつつ、手動CLI選択は引き続き許可します。 | +| `deprecatedChoiceIds` | No | `string[]` | この置き換え用選択肢へユーザーをリダイレクトすべきレガシーchoice id。 | +| `groupId` | No | `string` | 関連する選択肢をグループ化するためのオプションのgroup id。 | +| `groupLabel` | No | `string` | そのグループのユーザー向けラベル。 | +| `groupHint` | No | `string` | グループ向けの短い補助テキスト。 | +| `optionKey` | No | `string` | 単一フラグの単純な認証フロー向けの内部option key。 | +| `cliFlag` | No | `string` | `--openrouter-api-key`のようなCLIフラグ名。 | +| `cliOption` | No | `string` | `--openrouter-api-key `のような完全なCLIオプション形状。 | +| `cliDescription` | No | `string` | CLIヘルプで使われる説明。 | +| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | この選択肢をどのオンボーディングサーフェスに表示すべきか。省略した場合、デフォルトは`["text-inference"]`です。 | + +## commandAliasesリファレンス + +`commandAliases` は、プラグインが所有するランタイムコマンド名を、ユーザーが誤って`plugins.allow`に入れたり、ルートCLIコマンドとして実行しようとしたりする可能性がある場合に使用します。OpenClawはこのメタデータを、プラグインランタイムコードをimportせずに診断へ使用します。 + +```json +{ + "commandAliases": [ + { + "name": "dreaming", + "kind": "runtime-slash", + "cliCommand": "memory" + } + ] +} +``` + +| Field | Required | Type | What it means | +| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | +| `name` | Yes | `string` | このプラグインに属するコマンド名。 | +| `kind` | No | `"runtime-slash"` | エイリアスがルートCLIコマンドではなく、チャットスラッシュコマンドであることを示します。 | +| `cliCommand` | No | `string` | 存在する場合、CLI操作向けに提案する関連ルートCLIコマンド。 | ## uiHintsリファレンス -`uiHints`は、設定フィールド名から小さなレンダリングヒントへのマップです。 +`uiHints` は、設定フィールド名から小さなレンダリングヒントへのマップです。 ```json { @@ -194,20 +216,20 @@ OpenClawはこれをproviderランタイムが読み込まれる前に読み取 } ``` -各フィールドヒントには次を含められます。 +各フィールドヒントには次を含めることができます。 -| Field | Type | 意味 | -| ------------- | ---------- | -------------------------------- | -| `label` | `string` | ユーザー向けフィールドラベルです。 | -| `help` | `string` | 短い補助テキストです。 | -| `tags` | `string[]` | 任意のUIタグです。 | -| `advanced` | `boolean` | フィールドを高度な項目として示します。 | -| `sensitive` | `boolean` | フィールドをシークレットまたは機密として示します。 | -| `placeholder` | `string` | フォーム入力用のプレースホルダーテキストです。 | +| Field | Type | What it means | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | ユーザー向けフィールドラベル。 | +| `help` | `string` | 短い補助テキスト。 | +| `tags` | `string[]` | オプションのUIタグ。 | +| `advanced` | `boolean` | フィールドを高度な項目として扱います。 | +| `sensitive` | `boolean` | フィールドをシークレットまたはセンシティブとして扱います。 | +| `placeholder` | `string` | フォーム入力用のプレースホルダーテキスト。 | ## contractsリファレンス -`contracts`は、OpenClawがプラグインランタイムをimportせずに読める静的なcapability ownershipメタデータにのみ使ってください。 +`contracts` は、OpenClawがプラグインランタイムをimportせずに読める、静的なcapability所有メタデータにのみ使用してください。 ```json { @@ -225,23 +247,23 @@ OpenClawはこれをproviderランタイムが読み込まれる前に読み取 } ``` -各リストは任意です。 +各リストはオプションです。 -| Field | Type | 意味 | -| -------------------------------- | ---------- | -------------------------------------------------- | -| `speechProviders` | `string[]` | このプラグインが所有するspeech provider idです。 | -| `realtimeTranscriptionProviders` | `string[]` | このプラグインが所有するrealtime-transcription provider idです。 | -| `realtimeVoiceProviders` | `string[]` | このプラグインが所有するrealtime-voice provider idです。 | -| `mediaUnderstandingProviders` | `string[]` | このプラグインが所有するmedia-understanding provider idです。 | -| `imageGenerationProviders` | `string[]` | このプラグインが所有するimage-generation provider idです。 | -| `videoGenerationProviders` | `string[]` | このプラグインが所有するvideo-generation provider idです。 | -| `webFetchProviders` | `string[]` | このプラグインが所有するweb-fetch provider idです。 | -| `webSearchProviders` | `string[]` | このプラグインが所有するweb-search provider idです。 | -| `tools` | `string[]` | 同梱コントラクトチェック用にこのプラグインが所有するagent tool名です。 | +| Field | Type | What it means | +| -------------------------------- | ---------- | -------------------------------------------------------------- | +| `speechProviders` | `string[]` | このプラグインが所有するspeech provider id。 | +| `realtimeTranscriptionProviders` | `string[]` | このプラグインが所有するrealtime-transcription provider id。 | +| `realtimeVoiceProviders` | `string[]` | このプラグインが所有するrealtime-voice provider id。 | +| `mediaUnderstandingProviders` | `string[]` | このプラグインが所有するmedia-understanding provider id。 | +| `imageGenerationProviders` | `string[]` | このプラグインが所有するimage-generation provider id。 | +| `videoGenerationProviders` | `string[]` | このプラグインが所有するvideo-generation provider id。 | +| `webFetchProviders` | `string[]` | このプラグインが所有するweb-fetch provider id。 | +| `webSearchProviders` | `string[]` | このプラグインが所有するweb-search provider id。 | +| `tools` | `string[]` | バンドルされたコントラクトチェック向けに、このプラグインが所有するagentツール名。 | ## channelConfigsリファレンス -`channelConfigs`は、channel pluginがランタイム読み込み前に軽量な設定メタデータを必要とする場合に使ってください。 +`channelConfigs` は、チャネルプラグインがランタイム読み込み前に軽量な設定メタデータを必要とする場合に使用します。 ```json { @@ -268,19 +290,19 @@ OpenClawはこれをproviderランタイムが読み込まれる前に読み取 } ``` -各channelエントリーには次を含められます。 +各チャネルエントリーには次を含めることができます。 -| Field | Type | 意味 | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | -| `schema` | `object` | `channels.`用のJSON Schemaです。宣言された各channel設定エントリーで必須です。 | -| `uiHints` | `Record` | そのchannel設定セクション用の任意のUIラベル/プレースホルダー/機密性ヒントです。 | -| `label` | `string` | ランタイムメタデータがまだ準備できていないときにpickerおよびinspectサーフェスへマージされるchannelラベルです。 | -| `description` | `string` | inspectおよびcatalogサーフェス用の短いchannel説明です。 | -| `preferOver` | `string[]` | 選択サーフェスでこのchannelが優先されるべき旧plugin idまたは低優先度plugin idです。 | +| Field | Type | What it means | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| `schema` | `object` | `channels.`用のJSONスキーマ。宣言された各チャネル設定エントリーで必須です。 | +| `uiHints` | `Record` | そのチャネル設定セクション用のオプションのUIラベル/プレースホルダー/sensitiveヒント。 | +| `label` | `string` | ランタイムメタデータが未準備のときに、ピッカーおよびinspectサーフェスへマージされるチャネルラベル。 | +| `description` | `string` | inspectおよびcatalogサーフェス向けの短いチャネル説明。 | +| `preferOver` | `string[]` | 選択サーフェスでこのチャネルが優先されるべき、レガシーまたは低優先度のplugin id。 | ## modelSupportリファレンス -`modelSupport`は、`gpt-5.4`や`claude-sonnet-4.6`のような短縮model idから、プラグインランタイム読み込み前にOpenClawがprovider pluginを推測すべき場合に使います。 +`modelSupport` は、プラグインランタイムの読み込み前に、`gpt-5.4` や `claude-sonnet-4.6` のような短縮形モデルidからOpenClawがproviderプラグインを推測すべき場合に使用します。 ```json { @@ -293,61 +315,58 @@ OpenClawはこれをproviderランタイムが読み込まれる前に読み取 OpenClawは次の優先順位を適用します。 -- 明示的な`provider/model`参照では、所有する`providers`マニフェストメタデータを使います -- `modelPatterns`は`modelPrefixes`より優先されます -- 非同梱プラグイン1つと同梱プラグイン1つの両方が一致する場合、非同梱プラグインが優先されます -- それ以外の曖昧さは、ユーザーまたは設定がproviderを指定するまで無視されます +- 明示的な`provider/model`参照は、所有する`providers`マニフェストメタデータを使用する +- `modelPatterns` は `modelPrefixes` より優先される +- 非バンドルプラグイン1つとバンドルプラグイン1つの両方が一致する場合、非バンドルプラグインが勝つ +- 残る曖昧さは、ユーザーまたは設定がproviderを指定するまで無視される フィールド: -| Field | Type | 意味 | -| --------------- | ---------- | --------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 短縮model idに対して`startsWith`で一致させるプレフィックスです。 | -| `modelPatterns` | `string[]` | profile suffix削除後の短縮model idに対して一致させるregex sourceです。 | +| Field | Type | What it means | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | 短縮形モデルidに対して`startsWith`で一致させるプレフィックス。 | +| `modelPatterns` | `string[]` | プロファイル接尾辞を除去した後の短縮形モデルidに対して一致させる正規表現ソース。 | -旧来のトップレベルcapabilityキーは非推奨です。`speechProviders`、`realtimeTranscriptionProviders`、 -`realtimeVoiceProviders`、`mediaUnderstandingProviders`、 -`imageGenerationProviders`、`videoGenerationProviders`、 -`webFetchProviders`、および`webSearchProviders`を`contracts`配下へ移動するには`openclaw doctor --fix`を使ってください。通常のマニフェスト読み込みでは、これらのトップレベルフィールドをcapability ownershipとしては扱いません。 +レガシーなトップレベルcapabilityキーは非推奨です。`openclaw doctor --fix` を使用して、`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` を `contracts` 配下へ移動してください。通常のマニフェスト読み込みでは、これらのトップレベルフィールドをcapability所有としてはもう扱いません。 ## マニフェストとpackage.jsonの違い この2つのファイルは異なる役割を持ちます。 -| File | 用途 | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | 検出、設定検証、auth-choiceメタデータ、およびプラグインコード実行前に存在している必要があるUIヒント | -| `package.json` | npmメタデータ、依存関係インストール、およびエントリーポイント、インストールゲート、セットアップ、またはcatalogメタデータに使う`openclaw`ブロック | +| File | Use it for | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | 検出、設定検証、認証選択メタデータ、およびプラグインコード実行前に存在している必要があるUIヒント | +| `package.json` | npmメタデータ、依存関係のインストール、およびentrypoint、インストールゲーティング、セットアップ、またはcatalogメタデータに使われる`openclaw`ブロック | -どこにメタデータを置くべきか迷う場合は、次のルールを使ってください。 +どこにどのメタデータを置くべきか迷った場合は、次のルールを使ってください。 -- OpenClawがプラグインコードを読み込む前に知っておく必要があるなら、`openclaw.plugin.json`に置きます -- パッケージング、エントリーファイル、またはnpmインストール動作に関するものなら、`package.json`に置きます +- OpenClawがプラグインコードを読み込む前に知っている必要がある場合は、`openclaw.plugin.json` に置く +- パッケージング、entry file、またはnpm install動作に関するものであれば、`package.json` に置く ### 検出に影響するpackage.jsonフィールド -一部のランタイム前プラグインメタデータは、`openclaw.plugin.json`ではなく、`package.json`の`openclaw`ブロック配下に意図的に置かれています。 +一部のランタイム前プラグインメタデータは、`openclaw.plugin.json` ではなく、意図的に`package.json`の`openclaw`ブロック配下に置かれます。 重要な例: -| Field | 意味 | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | ネイティブプラグインのエントリーポイントを宣言します。 | -| `openclaw.setupEntry` | オンボーディングおよび遅延channel起動時に使われる、軽量なセットアップ専用エントリーポイントです。 | -| `openclaw.channel` | ラベル、docs path、エイリアス、選択用コピーなどの軽量なchannel catalogメタデータです。 | -| `openclaw.channel.configuredState` | 完全なchannelランタイムを読み込まずに「envのみのセットアップはすでに存在するか？」へ答えられる、軽量なconfigured-state checkerメタデータです。 | -| `openclaw.channel.persistedAuthState` | 完全なchannelランタイムを読み込まずに「何かがすでにサインイン済みか？」へ答えられる、軽量なpersisted-auth checkerメタデータです。 | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 同梱および外部公開プラグイン用のインストール/更新ヒントです。 | -| `openclaw.install.defaultChoice` | 複数のインストール元が利用可能な場合の優先インストールパスです。 | -| `openclaw.install.minHostVersion` | `>=2026.3.22`のようなsemver floorを使う、サポートされる最小OpenClaw host versionです。 | -| `openclaw.install.allowInvalidConfigRecovery` | 設定が無効な場合に、限定的な同梱プラグイン再インストール回復パスを許可します。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 起動中、完全なchannelプラグインより先にセットアップ専用channelサーフェスを読み込めるようにします。 | +| Field | What it means | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | ネイティブプラグインのentrypointを宣言します。 | +| `openclaw.setupEntry` | オンボーディングおよび遅延チャネル起動時に使われる、軽量なセットアップ専用entrypointです。 | +| `openclaw.channel` | ラベル、ドキュメントパス、エイリアス、選択時コピーなどの軽量なチャネルcatalogメタデータです。 | +| `openclaw.channel.configuredState` | 「envのみのセットアップがすでに存在するか」を、完全なチャネルランタイムを読み込まずに判定できる軽量なconfigured-state checkerメタデータです。 | +| `openclaw.channel.persistedAuthState` | 「すでに何かログイン済みか」を、完全なチャネルランタイムを読み込まずに判定できる軽量なpersisted-auth checkerメタデータです。 | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | バンドルプラグインおよび外部公開プラグイン向けのインストール/更新ヒントです。 | +| `openclaw.install.defaultChoice` | 複数のインストール元が利用可能なときの優先インストール経路です。 | +| `openclaw.install.minHostVersion` | `>=2026.3.22` のようなsemver floorを使う、サポートされる最小OpenClawホストバージョンです。 | +| `openclaw.install.allowInvalidConfigRecovery` | 設定が不正な場合に、限定的なバンドルプラグイン再インストール回復経路を許可します。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 起動時に、完全なチャネルプラグインの前にセットアップ専用チャネルサーフェスを読み込めるようにします。 | -`openclaw.install.minHostVersion`は、インストール時とmanifest registry読み込み時に適用されます。無効な値は拒否され、新しすぎるが有効な値は古いhost上でそのプラグインをスキップします。 +`openclaw.install.minHostVersion` は、インストール時およびマニフェストレジストリ読み込み時に適用されます。不正な値は拒否され、有効ではあるが新しすぎる値の場合、古いホストではそのプラグインはスキップされます。 -`openclaw.install.allowInvalidConfigRecovery`は意図的に限定的です。任意の壊れた設定をインストール可能にするものではありません。現時点では、特定の古い同梱プラグインアップグレード失敗、たとえば同梱プラグインパスの欠落や、その同じ同梱プラグインに対する古い`channels.`エントリーのような場合から、インストールフローが回復することだけを許可します。無関係な設定エラーは引き続きインストールをブロックし、オペレーターは`openclaw doctor --fix`に誘導されます。 +`openclaw.install.allowInvalidConfigRecovery` は意図的に限定的です。これによって任意の壊れた設定がインストール可能になるわけではありません。現時点では、特定の古いバンドルプラグインのアップグレード失敗、たとえば欠落したバンドルプラグインパスや、同じバンドルプラグインに対する古い `channels.` エントリーなどから、インストールフローが回復できるようにするだけです。無関係な設定エラーは引き続きインストールをブロックし、運用者を `openclaw doctor --fix` へ誘導します。 -`openclaw.channel.persistedAuthState`は、小さなchecker module向けのpackageメタデータです。 +`openclaw.channel.persistedAuthState` は、小さなcheckerモジュール用のpackageメタデータです。 ```json { @@ -363,9 +382,9 @@ OpenClawは次の優先順位を適用します。 } ``` -これは、セットアップ、doctor、またはconfigured-stateフローが、完全なchannel pluginを読み込む前に軽量なyes/no auth probeを必要とする場合に使います。対象のexportは永続化状態のみを読む小さな関数にしてください。完全なchannel runtime barrelを経由させないでください。 +これは、セットアップ、doctor、configured-stateフローが、完全なチャネルプラグインを読み込む前に、軽量なyes/no認証probeを必要とする場合に使います。対象のexportは、永続化された状態だけを読む小さな関数にしてください。完全なチャネルランタイムbarrel経由にしないでください。 -`openclaw.channel.configuredState`も、軽量なenv-only configured check用に同じ形を取ります。 +`openclaw.channel.configuredState` も、軽量なenv-only configuredチェック向けに同じ形状に従います。 ```json { @@ -381,39 +400,38 @@ OpenClawは次の優先順位を適用します。 } ``` -これは、channelがenvやその他の小さな非ランタイム入力からconfigured-stateに答えられる場合に使います。その判定に完全なconfig解決または実際のchannel runtimeが必要なら、そのロジックは代わりにプラグインの`config.hasConfiguredState`フックに置いてください。 +これは、チャネルがenvまたはその他の小さな非ランタイム入力からconfigured-stateを判定できる場合に使います。チェックに完全な設定解決や実際のチャネルランタイムが必要な場合は、そのロジックを代わりにプラグインの`config.hasConfiguredState`フックに置いてください。 -## JSON Schema要件 +## JSONスキーマ要件 -- **すべてのプラグインはJSON Schemaを必ず含める必要があります**。設定を受け付けない場合でも同様です。 -- 空のスキーマでも構いません（例: `{ "type": "object", "additionalProperties": false }`）。 -- スキーマはランタイム時ではなく、設定の読み書き時に検証されます。 +- **すべてのプラグインはJSONスキーマを含める必要があります**。設定を受け付けない場合でも同様です。 +- 空のスキーマでも問題ありません（例: `{ "type": "object", "additionalProperties": false }`）。 +- スキーマはランタイム時ではなく、設定の読み取り/書き込み時に検証されます。 -## 検証の挙動 +## 検証の動作 -- 不明な`channels.*`キーは、channel idがプラグインマニフェストで宣言されていない限り**エラー**です。 -- `plugins.entries.`、`plugins.allow`、`plugins.deny`、および`plugins.slots.*`は、**検出可能な**plugin idを参照していなければなりません。不明なidは**エラー**です。 -- プラグインがインストールされていても、マニフェストまたはスキーマが壊れているか欠けている場合、検証は失敗し、Doctorはそのプラグインエラーを報告します。 -- プラグイン設定が存在していても、プラグインが**無効**の場合、設定は保持され、Doctorとログに**警告**が表示されます。 +- 未知の`channels.*`キーは、チャネルidがプラグインマニフェストで宣言されていない限り、**エラー**です。 +- `plugins.entries.`、`plugins.allow`、`plugins.deny`、`plugins.slots.*` は、**検出可能な**plugin idを参照している必要があります。未知のidは**エラー**です。 +- プラグインがインストールされていても、マニフェストまたはスキーマが壊れている、あるいは欠落している場合、検証は失敗し、Doctorがそのプラグインエラーを報告します。 +- プラグイン設定が存在するがプラグインが**無効**な場合、設定は保持され、Doctorとログに**警告**が表示されます。 完全な`plugins.*`スキーマについては、[Configuration reference](/ja-JP/gateway/configuration)を参照してください。 -## 注意 +## 注意事項 - マニフェストは、ローカルファイルシステム読み込みを含む**ネイティブOpenClawプラグインで必須**です。 - ランタイムは引き続きプラグインモジュールを別途読み込みます。マニフェストは検出と検証専用です。 -- ネイティブマニフェストはJSON5で解析されるため、最終値がオブジェクトである限り、コメント、末尾カンマ、引用符なしキーを受け付けます。 -- マニフェストローダーが読むのは、文書化されたマニフェストフィールドのみです。ここに独自のトップレベルキーを追加するのは避けてください。 -- `providerAuthEnvVars`は、auth probe、env-marker検証、および環境変数名を確認するだけのためにプラグインランタイムを起動すべきでない類似のprovider-authサーフェス向けの軽量メタデータ経路です。 -- `providerAuthAliases`により、providerバリアントは、別のproviderのauth env vars、auth profile、設定ベースauth、およびAPIキーのオンボーディング選択肢を、コアにその関係をハードコードせずに再利用できます。 -- `channelEnvVars`は、shell-envフォールバック、セットアッププロンプト、および環境変数名を確認するだけのためにプラグインランタイムを起動すべきでない類似のchannelサーフェス向けの軽量メタデータ経路です。 -- `providerAuthChoices`は、providerランタイム読み込み前のauth-choice picker、`--auth-choice`解決、preferred-providerマッピング、および単純なオンボーディングCLIフラグ登録向けの軽量メタデータ経路です。providerコードを必要とするランタイムのウィザードメタデータについては、[Provider runtime hooks](/ja-JP/plugins/architecture#provider-runtime-hooks)を参照してください。 -- 排他的なプラグイン種別は`plugins.slots.*`を通じて選択されます。 - - `kind: "memory"` は`plugins.slots.memory`で選択されます。 - - `kind: "context-engine"` は`plugins.slots.contextEngine`で選択されます - （デフォルト: 組み込みの`legacy`）。 -- `channels`、`providers`、`cliBackends`、および`skills`は、プラグインでそれらが不要な場合は省略できます。 -- プラグインがネイティブモジュールに依存する場合は、ビルド手順と、必要なpackage manager allowlist要件（たとえばpnpm `allow-build-scripts` +- ネイティブマニフェストはJSON5として解析されるため、最終値がオブジェクトである限り、コメント、末尾カンマ、引用符なしキーを使用できます。 +- マニフェストローダーが読み取るのは文書化されたマニフェストフィールドだけです。ここに独自のトップレベルキーを追加しないでください。 +- `providerAuthEnvVars` は、認証probe、env-marker検証、および同様の、env名を調べるためだけにプラグインランタイムを起動すべきでないprovider認証サーフェス向けの軽量メタデータ経路です。 +- `providerAuthAliases` を使うと、providerバリアントが別のproviderの認証env var、認証プロファイル、設定ベース認証、およびAPIキーのオンボーディング選択肢を再利用できます。この関係をcoreにハードコードする必要はありません。 +- `channelEnvVars` は、shell-envフォールバック、セットアッププロンプト、および同様の、env名を調べるためだけにチャネルランタイムを起動すべきでないチャネルサーフェス向けの軽量メタデータ経路です。 +- `providerAuthChoices` は、認証選択ピッカー、`--auth-choice` 解決、preferred-providerマッピング、およびproviderランタイム読み込み前の単純なオンボーディングCLIフラグ登録向けの軽量メタデータ経路です。providerコードを必要とするランタイムのウィザードメタデータについては、[Provider runtime hooks](/ja-JP/plugins/architecture#provider-runtime-hooks)を参照してください。 +- 排他的なplugin kindは `plugins.slots.*` を通じて選択されます。 + - `kind: "memory"` は `plugins.slots.memory` で選択されます。 + - `kind: "context-engine"` は `plugins.slots.contextEngine` で選択されます（デフォルト: 組み込みの`legacy`）。 +- プラグインに不要であれば、`channels`、`providers`、`cliBackends`、`skills` は省略できます。 +- プラグインがネイティブモジュールに依存している場合は、ビルド手順と必要なpackage managerのallowlist要件（例: pnpm `allow-build-scripts` - `pnpm rebuild `）を文書化してください。 ## 関連 diff --git a/docs/ja-JP/plugins/sdk-agent-harness.md b/docs/ja-JP/plugins/sdk-agent-harness.md new file mode 100644 index 000000000..bd4a8eefd --- /dev/null +++ b/docs/ja-JP/plugins/sdk-agent-harness.md @@ -0,0 +1,257 @@ +--- +read_when: + - 埋め込みエージェントランタイムまたはハーネスレジストリを変更しています + - バンドル版または信頼済みプラグインからエージェントハーネスを登録しています + - Codexプラグインがモデルプロバイダーとどのように関係するかを理解する必要があります +sidebarTitle: Agent Harness +summary: 低レベルの埋め込みエージェント実行子を置き換えるプラグイン向けの実験的SDKサーフェス +title: エージェントハーネスプラグイン +x-i18n: + generated_at: "2026-04-11T02:46:40Z" + model: gpt-5.4 + provider: openai + source_hash: 43c1f2c087230398b0162ed98449f239c8db1e822e51c7dcd40c54fa6c3374e1 + source_path: plugins/sdk-agent-harness.md + workflow: 15 +--- + +# エージェントハーネスプラグイン + +**エージェントハーネス**は、準備済みのOpenClawエージェントターン1回分に対する低レベル実行子です。これはモデルプロバイダーでも、チャネルでも、ツールレジストリでもありません。 + +このサーフェスは、バンドル版または信頼済みのネイティブプラグインでのみ使用してください。パラメーター型が意図的に現在の埋め込みランナーを反映しているため、この契約はまだ実験的です。 + +## ハーネスを使うべき場合 + +モデルファミリーが独自のネイティブセッションランタイムを持ち、通常のOpenClawプロバイダートランスポートでは抽象化として不適切な場合に、エージェントハーネスを登録します。 + +例: + +- スレッドとコンパクションを管理するネイティブのコーディングエージェントサーバー +- ネイティブのプラン/reasoning/ツールイベントをストリーミングしなければならないローカルCLIまたはデーモン +- OpenClawセッションの文字起こしに加えて独自の再開IDを必要とするモデルランタイム + +新しいLLM APIを追加するだけの目的でハーネスを登録してはいけません。通常のHTTPまたはWebSocketモデルAPIであれば、[provider plugin](/ja-JP/plugins/sdk-provider-plugins)を構築してください。 + +## コアが引き続き所有するもの + +ハーネスが選択される前に、OpenClawはすでに以下を解決しています: + +- プロバイダーとモデル +- ランタイム認証状態 +- thinkingレベルとコンテキスト予算 +- OpenClawの文字起こし/セッションファイル +- ワークスペース、サンドボックス、ツールポリシー +- チャネル返信コールバックとストリーミングコールバック +- モデルフォールバックとライブモデル切り替えポリシー + +この分割は意図的なものです。ハーネスは準備済みの試行を実行しますが、プロバイダーを選択したり、チャネル配信を置き換えたり、黙ってモデルを切り替えたりはしません。 + +## ハーネスを登録する + +**インポート:** `openclaw/plugin-sdk/agent-harness` + +```typescript +import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness"; +import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; + +const myHarness: AgentHarness = { + id: "my-harness", + label: "My native agent harness", + + supports(ctx) { + return ctx.provider === "my-provider" + ? { supported: true, priority: 100 } + : { supported: false }; + }, + + async runAttempt(params) { + // ネイティブスレッドを開始または再開します。 + // params.prompt、params.tools、params.images、params.onPartialReply、 + // params.onAgentEvent、およびその他の準備済み試行フィールドを使用します。 + return await runMyNativeTurn(params); + }, +}; + +export default definePluginEntry({ + id: "my-native-agent", + name: "My Native Agent", + description: "Runs selected models through a native agent daemon.", + register(api) { + api.registerAgentHarness(myHarness); + }, +}); +``` + +## 選択ポリシー + +OpenClawは、プロバイダー/モデル解決後にハーネスを選択します: + +1. `OPENCLAW_AGENT_RUNTIME=`は、そのIDを持つ登録済みハーネスを強制します。 +2. `OPENCLAW_AGENT_RUNTIME=pi`は、組み込みPIハーネスを強制します。 +3. `OPENCLAW_AGENT_RUNTIME=auto`は、登録済みハーネスに、解決済みのプロバイダー/モデルをサポートしているか問い合わせます。 +4. 一致する登録済みハーネスがない場合、PIフォールバックが無効でなければOpenClawはPIを使用します。 + +強制されたプラグインハーネスの失敗は、実行失敗として表面化します。`auto`モードでは、 +選択されたプラグインハーネスがターンの副作用を生成する前に失敗した場合、 +OpenClawはPIにフォールバックすることがあります。代わりにそのフォールバックを確定的な失敗にしたい場合は、`OPENCLAW_AGENT_HARNESS_FALLBACK=none`または +`embeddedHarness.fallback: "none"`を設定してください。 + +バンドル版Codexプラグインは、ハーネスIDとして`codex`を登録します。コアはこれを +通常のプラグインハーネスIDとして扱います。Codex固有のエイリアスは共有ランタイムセレクターではなく、 +プラグインまたはオペレーター設定に属します。 + +## プロバイダーとハーネスの組み合わせ + +ほとんどのハーネスは、プロバイダーもあわせて登録するべきです。プロバイダーは、 +モデル参照、認証状態、モデルメタデータ、および`/model`選択をOpenClawの他の部分から見えるようにします。 +その後、ハーネスは`supports(...)`内でそのプロバイダーを要求します。 + +バンドル版Codexプラグインはこのパターンに従っています: + +- プロバイダーID: `codex` +- ユーザーモデル参照: `codex/gpt-5.4`、`codex/gpt-5.2`、またはCodexアプリサーバーが返すその他のモデル +- ハーネスID: `codex` +- 認証: 合成プロバイダー可用性。CodexハーネスがネイティブのCodexログイン/セッションを所有するため +- アプリサーバーリクエスト: OpenClawは生のモデルIDをCodexに送信し、 + ハーネスがネイティブのアプリサーバープロトコルと通信します + +Codexプラグインは追加的なものです。通常の`openai/gpt-*`参照は引き続きOpenAIプロバイダー参照であり、 +通常のOpenClawプロバイダー経路を使用し続けます。Codex管理の認証、 +Codexモデル検出、ネイティブスレッド、およびCodexアプリサーバー実行が必要な場合は`codex/gpt-*` +を選択してください。`/model`は、OpenAIプロバイダー資格情報を必要とせずに、 +Codexアプリサーバーが返すCodexモデル間を切り替えられます。 + +オペレーター設定、モデルプレフィックス例、Codex専用設定については、 +[Codex Harness](/ja-JP/plugins/codex-harness)を参照してください。 + +OpenClawはCodexアプリサーバー`0.118.0`以降を必要とします。Codexプラグインは +アプリサーバーの初期化ハンドシェイクを確認し、古いまたはバージョン未設定のサーバーをブロックすることで、 +OpenClawがテスト済みのプロトコルサーフェスに対してのみ実行されるようにします。 + +## PIフォールバックを無効にする + +デフォルトでは、OpenClawは埋め込みエージェントを`agents.defaults.embeddedHarness` +が`{ runtime: "auto", fallback: "pi" }`に設定された状態で実行します。`auto`モードでは、登録済みプラグイン +ハーネスがプロバイダー/モデルの組み合わせを要求できます。一致するものがない場合、または自動選択された +プラグインハーネスが出力生成前に失敗した場合、OpenClawはPIにフォールバックします。 + +プラグインハーネスだけが実際に使用されていることを証明する必要がある場合は、`fallback: "none"`を設定してください。これにより自動PIフォールバックは無効になりますが、 +明示的な`runtime: "pi"`や`OPENCLAW_AGENT_RUNTIME=pi`はブロックされません。 + +Codex専用の埋め込み実行の場合: + +```json +{ + "agents": { + "defaults": { + "model": "codex/gpt-5.4", + "embeddedHarness": { + "runtime": "codex", + "fallback": "none" + } + } + } +} +``` + +一致するモデルを任意の登録済みプラグインハーネスに要求させつつ、OpenClawが黙ってPIにフォールバックすることは避けたい場合は、 +`runtime: "auto"`のままにしてフォールバックを無効にしてください: + +```json +{ + "agents": { + "defaults": { + "embeddedHarness": { + "runtime": "auto", + "fallback": "none" + } + } + } +} +``` + +エージェント単位の上書きも同じ形を使います: + +```json +{ + "agents": { + "defaults": { + "embeddedHarness": { + "runtime": "auto", + "fallback": "pi" + } + }, + "list": [ + { + "id": "codex-only", + "model": "codex/gpt-5.4", + "embeddedHarness": { + "runtime": "codex", + "fallback": "none" + } + } + ] + } +} +``` + +`OPENCLAW_AGENT_RUNTIME`は引き続き設定済みランタイムを上書きします。環境から +PIフォールバックを無効にするには`OPENCLAW_AGENT_HARNESS_FALLBACK=none`を使用してください。 + +```bash +OPENCLAW_AGENT_RUNTIME=codex \ +OPENCLAW_AGENT_HARNESS_FALLBACK=none \ +openclaw gateway run +``` + +フォールバックを無効にすると、要求されたハーネスが +登録されていない、解決済みのプロバイダー/モデルをサポートしていない、または +ターンの副作用を生成する前に失敗した場合、セッションは早い段階で失敗します。これは +Codex専用デプロイや、Codexアプリサーバー経路が実際に使われていることを証明しなければならない +ライブテストでは意図された動作です。 + +この設定が制御するのは埋め込みエージェントハーネスだけです。画像、 +動画、音楽、TTS、PDF、その他のプロバイダー固有のモデルルーティングは無効化されません。 + +## ネイティブセッションと文字起こしミラー + +ハーネスは、ネイティブセッションID、スレッドID、またはデーモン側の再開トークンを保持する場合があります。 +その対応付けはOpenClawセッションに明示的に関連付けたままにし、 +ユーザーに見えるassistant/tool出力をOpenClawの文字起こしへミラーし続けてください。 + +OpenClawの文字起こしは、以下の互換レイヤーのままです: + +- チャネルから見えるセッション履歴 +- 文字起こし検索とインデックス作成 +- 後続ターンで組み込みPIハーネスに戻すこと +- 汎用の`/new`、`/reset`、およびセッション削除動作 + +ハーネスがサイドカーの対応情報を保存する場合は、所有するOpenClawセッションがリセットされたときに +OpenClawがそれをクリアできるよう、`reset(...)`を実装してください。 + +## ツールおよびメディア結果 + +コアはOpenClawのツール一覧を構築し、それを準備済み試行に渡します。 +ハーネスが動的ツール呼び出しを実行する場合は、チャネルメディアを自分で送信するのではなく、 +ハーネス結果の形を通じてツール結果を返してください。 + +これにより、テキスト、画像、動画、音楽、TTS、承認、メッセージングツール出力が、 +PIベース実行と同じ配信経路に保たれます。 + +## 現在の制限 + +- 公開インポートパスは汎用ですが、一部の試行/結果型エイリアスには互換性のためにまだ + `Pi`名が残っています。 +- サードパーティ製ハーネスのインストールは実験的です。ネイティブセッションランタイムが必要になるまでは + provider pluginを優先してください。 +- ターンをまたいだハーネス切り替えはサポートされています。ネイティブツール、承認、assistantテキスト、またはメッセージ送信が始まった後、 + ターンの途中でハーネスを切り替えないでください。 + +## 関連 + +- [SDK Overview](/ja-JP/plugins/sdk-overview) +- [Runtime Helpers](/ja-JP/plugins/sdk-runtime) +- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) +- [Codex Harness](/ja-JP/plugins/codex-harness) +- [Model Providers](/ja-JP/concepts/model-providers) diff --git a/docs/ja-JP/plugins/sdk-channel-plugins.md b/docs/ja-JP/plugins/sdk-channel-plugins.md index 07e68ac55..e33e933c3 100644 --- a/docs/ja-JP/plugins/sdk-channel-plugins.md +++ b/docs/ja-JP/plugins/sdk-channel-plugins.md @@ -1,100 +1,82 @@ --- read_when: - - 新しいメッセージングチャネルプラグインを構築している場合 + - 新しいメッセージングチャンネルプラグインを構築している場合 - OpenClawをメッセージングプラットフォームに接続したい場合 - ChannelPluginアダプターサーフェスを理解する必要がある場合 sidebarTitle: Channel Plugins -summary: OpenClaw向けメッセージングチャネルプラグインを構築するためのステップバイステップガイド -title: チャネルプラグインの構築 +summary: OpenClaw向けメッセージングチャンネルプラグインを構築するためのステップバイステップガイド +title: チャンネルプラグインの構築 x-i18n: - generated_at: "2026-04-08T02:17:43Z" + generated_at: "2026-04-11T02:46:50Z" model: gpt-5.4 provider: openai - source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f + source_hash: 8a026e924f9ae8a3ddd46287674443bcfccb0247be504261522b078e1f440aef source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# チャネルプラグインの構築 +# チャンネルプラグインの構築 -このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャネルプラグインの構築手順を説明します。最後には、DMセキュリティ、 -pairing、返信のスレッド化、アウトバウンドメッセージングを備えた動作するチャネルを手に入れられます。 +このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャンネルプラグインの構築方法を説明します。最後には、DMセキュリティ、pairing、返信スレッド化、アウトバウンドメッセージングを備えた動作するチャンネルが完成します。 - まだOpenClawプラグインを一度も作成したことがない場合は、基本的なパッケージ - 構造とマニフェスト設定について、先に - [はじめに](/ja-JP/plugins/building-plugins)を読んでください。 + まだOpenClawプラグインを一度も構築したことがない場合は、まず基本的なパッケージ構造とmanifest設定について[はじめに](/ja-JP/plugins/building-plugins)を読んでください。 -## チャネルプラグインの仕組み +## チャンネルプラグインの仕組み -チャネルプラグインは、独自の send/edit/react ツールを必要としません。OpenClawは -共有の `message` ツールを1つcoreに保持します。プラグインが所有するのは次の部分です: +チャンネルプラグインには、独自のsend/edit/reactツールは不要です。OpenClawはコア内で1つの共有`message`ツールを維持します。プラグインが担当するのは次の領域です。 - **設定** — アカウント解決とセットアップウィザード -- **セキュリティ** — DMポリシーと許可リスト -- **pairing** — DM承認フロー -- **セッション文法** — プロバイダー固有の会話IDを、どのようにベースチャット、thread id、親フォールバックに対応付けるか +- **セキュリティ** — DMポリシーとallowlist +- **Pairing** — DM承認フロー +- **セッショングラマー** — プロバイダー固有の会話IDを、ベースチャット、スレッドID、親フォールバックへどう対応付けるか - **アウトバウンド** — テキスト、メディア、pollをプラットフォームへ送信 -- **スレッド化** — 返信をどのようにスレッド化するか +- **スレッド化** — 返信をどうスレッド化するか -coreは共有messageツール、プロンプト配線、外側のセッションキー形状、 -汎用の `:thread:` 管理、およびディスパッチを所有します。 +コアは、共有messageツール、プロンプト配線、外側のsession-key形状、汎用的な`:thread:`管理、およびディスパッチを担当します。 -プラットフォームが会話ID内に追加スコープを保存する場合は、その解析を -`messaging.resolveSessionConversation(...)` を使ってプラグイン内に保持してください。これが、 -`rawId` をベース会話ID、任意のthread id、明示的な `baseConversationId`、 -および `parentConversationCandidates` に対応付けるための正規のフックです。 -`parentConversationCandidates` を返す場合は、それらを最も狭い親から最も広い/ベース会話の順に並べてください。 +プラットフォームが会話IDの中に追加のscopeを保持する場合、その解析はプラグイン内で`messaging.resolveSessionConversation(...)`を使って維持してください。これは、`rawId`をベース会話ID、任意のスレッドID、明示的な`baseConversationId`、および任意の`parentConversationCandidates`に対応付けるための正式なフックです。`parentConversationCandidates`を返す場合は、最も狭い親から最も広い/ベース会話の順に並べてください。 -チャネルレジストリが起動する前に同じ解析が必要なバンドルプラグインは、 -一致する `resolveSessionConversation(...)` エクスポートを持つトップレベルの -`session-key-api.ts` ファイルを公開することもできます。coreは、ランタイムの -プラグインレジストリがまだ利用できない場合にのみ、そのブートストラップ安全なサーフェスを使います。 +同じ解析をチャンネルレジストリ起動前に必要とする同梱プラグインは、一致する`resolveSessionConversation(...)`エクスポートを持つトップレベルの`session-key-api.ts`ファイルも公開できます。コアは、ランタイムプラグインレジストリがまだ利用できないときにのみ、このbootstrap安全なサーフェスを使用します。 -`messaging.resolveParentConversationCandidates(...)` は、 -プラグインが汎用/raw id に加えて親フォールバックだけを必要とする場合の -レガシー互換フォールバックとして引き続き利用できます。両方のフックが存在する場合、 -coreはまず `resolveSessionConversation(...).parentConversationCandidates` を使い、 -正規フックがそれらを省略した場合にのみ -`resolveParentConversationCandidates(...)` へフォールバックします。 +`messaging.resolveParentConversationCandidates(...)`は、プラグインが汎用/raw IDの上に親フォールバックだけを必要とする場合の、レガシー互換フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず`resolveSessionConversation(...).parentConversationCandidates`を使い、その正式なフックで省略された場合にのみ`resolveParentConversationCandidates(...)`へフォールバックします。 -## 承認とチャネル機能 +## 承認とチャンネルcapability -ほとんどのチャネルプラグインでは、承認専用コードは不要です。 +ほとんどのチャンネルプラグインでは、承認専用コードは不要です。 -- coreは、同一チャット内の `/approve`、共有承認ボタンペイロード、および汎用フォールバック配信を所有します。 -- チャネルに承認固有の動作が必要な場合は、チャネルプラグイン上の1つの `approvalCapability` オブジェクトを優先してください。 -- `ChannelPlugin.approvals` は削除されました。承認配信/ネイティブ/レンダリング/認証の情報は `approvalCapability` に置いてください。 -- `plugin.auth` は login/logout 専用です。coreはそのオブジェクトから承認認証フックをもう読み取りません。 -- `approvalCapability.authorizeActorAction` と `approvalCapability.getActionAvailabilityState` が正規の承認認証シームです。 -- 同一チャットでの承認認証可用性には `approvalCapability.getActionAvailabilityState` を使ってください。 -- チャネルがネイティブexec承認を公開する場合は、開始サーフェス/ネイティブクライアント状態が同一チャットの承認認証と異なるときに `approvalCapability.getExecInitiatingSurfaceState` を使ってください。coreはこのexec専用フックを使って `enabled` と `disabled` を区別し、開始元チャネルがネイティブexec承認をサポートするかを判断し、ネイティブクライアントのフォールバックガイダンスにそのチャネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)` は一般的なケース向けにこれを埋めます。 -- 重複するローカル承認プロンプトの非表示や、配信前の入力中インジケーター送信のようなチャネル固有のペイロードライフサイクル動作には、`outbound.shouldSuppressLocalPayloadPrompt` または `outbound.beforeDeliverPayload` を使ってください。 -- `approvalCapability.delivery` はネイティブ承認ルーティングまたはフォールバック抑制にのみ使ってください。 -- チャネル所有のネイティブ承認情報には `approvalCapability.nativeRuntime` を使ってください。ホットなチャネルエントリポイントでは、`createLazyChannelApprovalNativeRuntimeAdapter(...)` でこれを遅延化し、必要時にランタイムモジュールをインポートしつつ、coreが承認ライフサイクルを組み立てられるようにしてください。 -- チャネルが共有レンダラーではなく、本当にカスタム承認ペイロードを必要とする場合にのみ `approvalCapability.render` を使ってください。 -- チャネルが、ネイティブexec承認を有効にするために必要な正確な設定ノブを無効化パス返信で説明したい場合は `approvalCapability.describeExecApprovalSetup` を使ってください。このフックは `{ channel, channelLabel, accountId }` を受け取ります。名前付きアカウントチャネルでは、トップレベルのデフォルトではなく `channels..accounts..execApprovals.*` のようなアカウントスコープのパスをレンダリングする必要があります。 -- チャネルが既存設定から安定した所有者類似のDM identityを推測できる場合は、承認固有のcoreロジックを追加せずに同一チャットの `/approve` を制限するために `openclaw/plugin-sdk/approval-runtime` の `createResolvedApproverActionAuthAdapter` を使ってください。 -- チャネルがネイティブ承認配信を必要とする場合、チャネルコードはターゲット正規化と転送/表示情報に集中させてください。`openclaw/plugin-sdk/approval-runtime` の `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability` を使ってください。チャネル固有の情報は `approvalCapability.nativeRuntime` の背後に置き、理想的には `createChannelApprovalNativeRuntimeAdapter(...)` または `createLazyChannelApprovalNativeRuntimeAdapter(...)` を介して提供してください。そうすることで、coreがハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、有効期限、Gateway購読、および別経路配信通知を所有できます。`nativeRuntime` はいくつかの小さなシームに分かれています: -- `availability` — アカウントが設定済みかどうか、およびリクエストを処理すべきかどうか -- `presentation` — 共有承認ビューモデルを保留中/解決済み/期限切れのネイティブペイロードまたは最終アクションへ対応付け -- `transport` — ネイティブ承認メッセージのターゲット準備と送信/更新/削除 -- `interactions` — ネイティブボタンやreaction向けの任意の bind/unbind/clear-action フック +- コアは、同一チャット内の`/approve`、共有承認ボタンpayload、および汎用フォールバック配信を担当します。 +- チャンネルに承認固有の動作が必要な場合は、チャンネルプラグイン上の1つの`approvalCapability`オブジェクトを優先してください。 +- `ChannelPlugin.approvals`は削除されました。承認配信/native/render/authの情報は`approvalCapability`に置いてください。 +- `plugin.auth`はlogin/logout専用です。コアはそのオブジェクトから承認authフックをもう読みません。 +- `approvalCapability.authorizeActorAction`と`approvalCapability.getActionAvailabilityState`が正式な承認authの接合面です。 +- 同一チャット内の承認auth可用性には`approvalCapability.getActionAvailabilityState`を使用してください。 +- チャンネルがnative exec承認を公開する場合、開始元サーフェス/native client状態が同一チャット承認authと異なるときは`approvalCapability.getExecInitiatingSurfaceState`を使用してください。コアはこのexec専用フックを使って`enabled`と`disabled`を区別し、開始元チャンネルがnative exec承認をサポートしているかを判断し、native clientフォールバック案内にそのチャンネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)`は一般的なケースでこれを補完します。 +- 重複するローカル承認プロンプトの非表示や、配信前のtyping indicator送信のようなチャンネル固有のpayloadライフサイクル動作には、`outbound.shouldSuppressLocalPayloadPrompt`または`outbound.beforeDeliverPayload`を使用してください。 +- `approvalCapability.delivery`は、native承認ルーティングまたはフォールバック抑制にのみ使用してください。 +- `approvalCapability.nativeRuntime`は、チャンネル所有のnative承認情報に使用してください。ホットなチャンネルエントリポイントでは、`createLazyChannelApprovalNativeRuntimeAdapter(...)`で遅延化してください。これにより、コアが承認ライフサイクルを組み立てられる一方で、必要に応じてランタイムモジュールをオンデマンドでimportできます。 +- `approvalCapability.render`は、チャンネルが共有レンダラーではなく本当にカスタム承認payloadを必要とする場合にのみ使用してください。 +- チャンネルが無効時の返信で、native exec承認を有効化するために必要な正確な設定ノブを説明したい場合は`approvalCapability.describeExecApprovalSetup`を使用してください。このフックは`{ channel, channelLabel, accountId }`を受け取ります。名前付きアカウントのあるチャンネルは、トップレベルのデフォルトではなく、`channels..accounts..execApprovals.*`のようなアカウントスコープのパスを描画するべきです。 +- チャンネルが既存設定から安定したowner風のDM IDを推測できるなら、承認固有のコアロジックを追加せずに同一チャット内の`/approve`を制限するために、`openclaw/plugin-sdk/approval-runtime`の`createResolvedApproverActionAuthAdapter`を使用してください。 +- チャンネルにnative承認配信が必要な場合、チャンネルコードはターゲット正規化とトランスポート/プレゼンテーション情報に集中させてください。`openclaw/plugin-sdk/approval-runtime`の`createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability`を使用してください。チャンネル固有の情報は、理想的には`createChannelApprovalNativeRuntimeAdapter(...)`または`createLazyChannelApprovalNativeRuntimeAdapter(...)`を通じて`approvalCapability.nativeRuntime`の背後に置いてください。これにより、コアはハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、有効期限、Gatewayサブスクリプション、別経路通知を担当できます。`nativeRuntime`はいくつかのより小さい接合面に分割されています: +- `availability` — アカウントが設定されているか、およびリクエストを処理すべきかどうか +- `presentation` — 共有承認view modelを保留中/解決済み/期限切れのnative payloadまたは最終アクションに対応付ける +- `transport` — ターゲットを準備し、native承認メッセージを送信/更新/削除する +- `interactions` — nativeボタンまたはreaction向けの任意のbind/unbind/clear-actionフック - `observe` — 任意の配信診断フック -- チャネルがclient、token、Bolt app、webhook受信側のようなランタイム所有オブジェクトを必要とする場合は、`openclaw/plugin-sdk/channel-runtime-context` を通じて登録してください。汎用ランタイムコンテキストレジストリにより、coreは承認固有のラッパー接着コードを追加することなく、チャネル起動状態から機能駆動ハンドラーをブートストラップできます。 -- 機能駆動シームでまだ表現しきれない場合にのみ、より低レベルな `createChannelApprovalHandler` または `createChannelNativeApprovalRuntime` を使ってください。 -- ネイティブ承認チャネルは、`accountId` と `approvalKind` の両方をそれらのヘルパー経由でルーティングする必要があります。`accountId` はマルチアカウント承認ポリシーを正しいbotアカウントにスコープし、`approvalKind` はcore内のハードコード分岐なしで exec と plugin 承認の動作をチャネル側で利用可能にします。 -- coreは現在、承認再ルーティング通知も所有しています。チャネルプラグインは `createChannelNativeApprovalRuntime` から独自の「承認はDM / 別チャネルに送られました」というフォローアップメッセージを送信すべきではありません。代わりに、共有承認機能ヘルパーを通じて正確な起点 + approver-DM ルーティングを公開し、開始チャットへ通知を投稿する前に、coreに実際の配信結果を集約させてください。 -- 配信された承認IDの種類はエンドツーエンドで保持してください。ネイティブクライアントは、チャネルローカル状態から exec と plugin 承認ルーティングを推測または書き換えるべきではありません。 -- 異なる承認種類は、意図的に異なるネイティブサーフェスを公開してもかまいません。 - 現在のバンドル例: - - Slack は exec と plugin の両方のIDでネイティブ承認ルーティングを利用可能に保ちます。 - - Matrix は exec と plugin の承認で同じネイティブDM/チャネルルーティングと reaction UX を維持しつつ、承認種類ごとに認証を変えられるようにしています。 -- `createApproverRestrictedNativeApprovalAdapter` は依然として互換ラッパーとして存在しますが、新しいコードでは機能ビルダーを優先し、プラグイン上に `approvalCapability` を公開してください。 +- チャンネルがclient、token、Bolt app、webhook receiverのようなランタイム所有オブジェクトを必要とする場合は、`openclaw/plugin-sdk/channel-runtime-context`を通じて登録してください。汎用runtime-contextレジストリにより、コアは承認固有のラッパー接着コードを追加せずに、チャンネル起動状態からcapability駆動ハンドラーをbootstrapできます。 +- capability駆動の接合面だけではまだ表現力が足りない場合にのみ、より低レベルな`createChannelApprovalHandler`または`createChannelNativeApprovalRuntime`を使用してください。 +- native承認チャンネルは、`accountId`と`approvalKind`の両方をそれらのヘルパー経由でルーティングする必要があります。`accountId`はマルチアカウント承認ポリシーを正しいボットアカウントにスコープし、`approvalKind`はコアにハードコードされた分岐なしで、execとプラグイン承認の動作をチャンネルから利用可能に保ちます。 +- コアは現在、承認の再ルーティング通知も担当します。チャンネルプラグインは、`createChannelNativeApprovalRuntime`から独自の「承認はDM/別チャンネルへ送られました」フォローアップメッセージを送るべきではありません。代わりに、共有承認capabilityヘルパーを通じて正確なorigin + approver-DMルーティングを公開し、開始元チャットへ通知を返す前にコアが実際の配信を集約できるようにしてください。 +- 配信された承認IDの種類をエンドツーエンドで維持してください。native clientは、チャンネルローカル状態からexecかプラグインかの承認ルーティングを推測したり書き換えたりしてはいけません。 +- 異なる承認種別は、意図的に異なるnativeサーフェスを公開できます。 + 現在の同梱例: + - Slackは、exec IDとプラグインIDの両方に対してnative承認ルーティングを利用可能なままにします。 + - Matrixは、exec承認とプラグイン承認で同じnative DM/チャンネルルーティングとreaction UXを維持しつつ、承認種別ごとにauthを異ならせることができます。 +- `createApproverRestrictedNativeApprovalAdapter`は互換ラッパーとして依然存在しますが、新しいコードではcapability builderを優先し、プラグイン上に`approvalCapability`を公開してください。 -ホットなチャネルエントリポイントでは、このファミリーの一部だけが必要な場合、 -より狭いランタイムsubpathを優先してください: +ホットなチャンネルエントリポイントでは、そのファミリーの一部だけが必要な場合、より狭いランタイムsubpathを優先してください。 - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -106,97 +88,77 @@ coreはまず `resolveSessionConversation(...).parentConversationCandidates` を - `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-safe なセットアップパッチアダプター（`createPatchedAccountSetupAdapter`, - `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`）、lookup-note 出力、 - `promptResolvedAllowFrom`、`splitSetupEntries`、および委譲された - setup-proxy ビルダー -- `openclaw/plugin-sdk/setup-adapter-runtime` は、`createEnvPatchedAccountSetupAdapter` 向けの狭い env 対応アダプターシームです -- `openclaw/plugin-sdk/channel-setup` は、オプションインストールのセットアップ - ビルダーと、いくつかのセットアップ安全プリミティブをカバーします: - `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime`は、ランタイム安全なセットアップヘルパーを扱います: + import安全なセットアップpatchアダプター（`createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`）、lookup-note出力、`promptResolvedAllowFrom`、`splitSetupEntries`、および委譲セットアップproxy builder +- `openclaw/plugin-sdk/setup-adapter-runtime`は、`createEnvPatchedAccountSetupAdapter`向けの狭いenv対応アダプター接合面です +- `openclaw/plugin-sdk/channel-setup`は、optional-installセットアップbuilderといくつかのセットアップ安全プリミティブを扱います: + `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、 -チャネルが env 駆動のセットアップまたは認証をサポートし、汎用の起動/設定 -フローがランタイム読み込み前にその env 名を知る必要がある場合は、 -プラグインマニフェストで `channelEnvVars` として宣言してください。チャネルランタイムの -`envVars` またはローカル定数は、operator 向けコピー専用にしてください。 -`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, -`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` +チャンネルがenv駆動のセットアップやauthをサポートし、ランタイムがロードされる前に汎用の起動/設定フローがそれらのenv名を知る必要がある場合は、プラグインmanifestで`channelEnvVars`として宣言してください。チャンネルランタイムの`envVars`またはローカル定数は、operator向けコピー専用にしてください。 +`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、および`splitSetupEntries` -- より重い共有セットアップ/設定ヘルパー、たとえば - `moveSingleAccountChannelSectionToDefaultAccount(...)` - も必要な場合にのみ、より広い `openclaw/plugin-sdk/setup` シームを使ってください +- `moveSingleAccountChannelSectionToDefaultAccount(...)`のような、より重い共有セットアップ/設定ヘルパーも必要な場合にのみ、より広い`openclaw/plugin-sdk/setup`接合面を使用してください -チャネルがセットアップサーフェスで「まずこのプラグインをインストールしてください」と広告したいだけであれば、 -`createOptionalChannelSetupSurface(...)` を優先してください。生成される -adapter/wizard は設定書き込みと最終化で fail closed になり、検証、最終化、ドキュメントリンクの文言全体で同じインストール必須メッセージを再利用します。 +チャンネルがセットアップサーフェス内で「まずこのプラグインをインストールしてください」と案内するだけでよい場合は、`createOptionalChannelSetupSurface(...)`を優先してください。生成されるadapter/wizardは、設定書き込みと最終化でfail closedし、検証・最終化・docsリンクのコピー全体で同じインストール必須メッセージを再利用します。 -他のホットなチャネルパスでも、より広いレガシーサーフェスより狭いヘルパーを優先してください: +その他のホットなチャンネルパスでも、より広いレガシーサーフェスより狭いヘルパーを優先してください。 -- マルチアカウント設定とデフォルトアカウントフォールバックには - `openclaw/plugin-sdk/account-core`、 +- `openclaw/plugin-sdk/account-core`、 `openclaw/plugin-sdk/account-id`、 - `openclaw/plugin-sdk/account-resolution`、 - `openclaw/plugin-sdk/account-helpers` -- インバウンドroute/envelope と - record-and-dispatch 配線には - `openclaw/plugin-sdk/inbound-envelope` と - `openclaw/plugin-sdk/inbound-reply-dispatch` -- ターゲット解析/照合には `openclaw/plugin-sdk/messaging-targets` -- メディア読み込みとアウトバウンド - identity/send delegate には `openclaw/plugin-sdk/outbound-media` と - `openclaw/plugin-sdk/outbound-runtime` -- thread-binding ライフサイクル - とアダプター登録には `openclaw/plugin-sdk/thread-bindings-runtime` -- レガシー agent/media - ペイロードフィールド構造がまだ必要な場合にのみ `openclaw/plugin-sdk/agent-media-payload` -- Telegram カスタムコマンド + `openclaw/plugin-sdk/account-resolution`、および + `openclaw/plugin-sdk/account-helpers`は、マルチアカウント設定と + デフォルトアカウントフォールバック向け +- `openclaw/plugin-sdk/inbound-envelope`と + `openclaw/plugin-sdk/inbound-reply-dispatch`は、インバウンドのルート/envelopeと + record-and-dispatch配線向け +- `openclaw/plugin-sdk/messaging-targets`は、ターゲット解析/照合向け +- `openclaw/plugin-sdk/outbound-media`と + `openclaw/plugin-sdk/outbound-runtime`は、メディア読み込みと + アウトバウンドID/送信delegate向け +- `openclaw/plugin-sdk/thread-bindings-runtime`は、スレッドbindingライフサイクル + とadapter登録向け +- `openclaw/plugin-sdk/agent-media-payload`は、レガシーのagent/media + payloadフィールドレイアウトがまだ必要な場合のみ +- `openclaw/plugin-sdk/telegram-command-config`は、Telegramカスタムコマンド 正規化、重複/競合検証、およびフォールバック安定なコマンド - 設定コントラクトには `openclaw/plugin-sdk/telegram-command-config` + 設定契約向け -認証専用チャネルは通常、デフォルトパスで十分です: coreが承認を処理し、プラグインは outbound/auth 機能を公開するだけです。Matrix、Slack、Telegram、およびカスタムchat転送のようなネイティブ承認チャネルは、独自の承認ライフサイクルを作るのではなく、共有ネイティブヘルパーを使うべきです。 +認証専用チャンネルは通常、デフォルトパスで十分です。コアが承認を処理し、プラグインはアウトバウンド/auth capabilityを公開するだけです。Matrix、Slack、Telegram、およびカスタムチャットトランスポートのようなnative承認チャンネルは、独自に承認ライフサイクルを実装するのではなく、共有nativeヘルパーを使用してください。 ## インバウンドメンションポリシー -インバウンドメンション処理は、次の2層に分けてください: +インバウンドメンション処理は、次の2層に分けて維持してください。 - プラグイン所有の証拠収集 - 共有ポリシー評価 -共有レイヤーには `openclaw/plugin-sdk/channel-inbound` を使ってください。 +共有レイヤーには`openclaw/plugin-sdk/channel-inbound`を使用してください。 プラグインローカルロジックに適しているもの: -- bot への返信検出 -- bot の引用検出 -- thread 参加チェック -- サービス/システムメッセージの除外 -- bot 参加の証明に必要なプラットフォームネイティブキャッシュ +- botへの返信検出 +- bot引用の検出 +- スレッド参加チェック +- service/systemメッセージの除外 +- bot参加を証明するために必要なプラットフォームネイティブキャッシュ 共有ヘルパーに適しているもの: - `requireMention` - 明示的メンション結果 -- 暗黙メンション許可リスト +- 暗黙的メンションallowlist - コマンドバイパス - 最終的なスキップ判定 推奨フロー: -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 { @@ -235,8 +197,7 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` は、すでにランタイム注入に依存している -バンドルチャネルプラグイン向けに、同じ共有メンションヘルパーも公開します: +`api.runtime.channel.mentions`は、すでにランタイム注入に依存している同梱チャンネルプラグイン向けに、同じ共有メンションヘルパーを公開します。 - `buildMentionRegexes` - `matchesMentionPatterns` @@ -244,19 +205,14 @@ if (decision.shouldSkip) return; - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -古い `resolveMentionGating*` ヘルパーは、 -`openclaw/plugin-sdk/channel-inbound` 上に互換エクスポートとしてのみ残っています。新しいコードでは -`resolveInboundMentionDecision({ facts, policy })` を使ってください。 +古い`resolveMentionGating*`ヘルパーは、`openclaw/plugin-sdk/channel-inbound`上に互換エクスポートとしてのみ残っています。新しいコードでは`resolveInboundMentionDecision({ facts, policy })`を使用してください。 ## ウォークスルー - - 標準的なプラグインファイルを作成します。`package.json` の `channel` フィールドが、 - これをチャネルプラグインにします。完全なパッケージメタデータサーフェスについては、 - [プラグインのセットアップと設定](/ja-JP/plugins/sdk-setup#openclawchannel) - を参照してください: + + 標準的なプラグインファイルを作成します。`package.json`内の`channel`フィールドが、これをチャンネルプラグインにします。完全なパッケージメタデータサーフェスについては、[Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel)を参照してください。 ```json package.json @@ -305,11 +261,10 @@ if (decision.shouldSkip) return; - - `ChannelPlugin` インターフェースには、多くの任意アダプターサーフェスがあります。まずは - 最小限の `id` と `setup` から始め、必要に応じてアダプターを追加してください。 + + `ChannelPlugin`インターフェースには、多くの省略可能なアダプターサーフェスがあります。最小構成の`id`と`setup`から始め、必要に応じてアダプターを追加してください。 - `src/channel.ts` を作成します: + `src/channel.ts`を作成します: ```typescript src/channel.ts import { @@ -317,7 +272,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"; // your platform API client + import { acmeChatApi } from "./client.js"; // あなたのプラットフォームAPIクライアント type ResolvedAccount = { accountId: string | null; @@ -358,7 +313,7 @@ if (decision.shouldSkip) return; }, }), - // DM security: who can message the bot + // DMセキュリティ: botにメッセージを送れる相手 security: { dm: { channelKey: "acme-chat", @@ -368,21 +323,21 @@ if (decision.shouldSkip) return; }, }, - // Pairing: approval flow for new DM contacts + // Pairing: 新しいDM連絡先向け承認フロー pairing: { text: { idLabel: "Acme Chat username", - message: "Send this code to verify your identity:", + message: "本人確認のため、このコードを送信してください:", notify: async ({ target, code }) => { await acmeChatApi.sendDm(target, `Pairing code: ${code}`); }, }, }, - // Threading: how replies are delivered + // スレッド化: 返信の配信方法 threading: { topLevelReplyToMode: "reply" }, - // Outbound: send messages to the platform + // アウトバウンド: プラットフォームへメッセージを送信 outbound: { attachedResults: { sendText: async (params) => { @@ -402,24 +357,23 @@ if (decision.shouldSkip) return; }); ``` - - 低レベルのアダプターインターフェースを手動で実装する代わりに、 - 宣言的なオプションを渡すと、ビルダーがそれらを組み合わせます: + + 低レベルのアダプターインターフェースを手動で実装する代わりに、宣言的なオプションを渡すと、builderがそれらを組み合わせます。 - | オプション | 配線される内容 | + | オプション | 配線されるもの | | --- | --- | | `security.dm` | 設定フィールドからのスコープ付きDMセキュリティリゾルバー | - | `pairing.text` | コード交換を伴うテキストベースのDM pairing フロー | - | `threading` | 返信モードリゾルバー（固定、アカウントスコープ、またはカスタム） | - | `outbound.attachedResults` | 結果メタデータ（message ID）を返す送信関数 | + | `pairing.text` | コード交換付きのテキストベースDM pairingフロー | + | `threading` | reply-to-modeリゾルバー（固定、アカウントスコープ、またはカスタム） | + | `outbound.attachedResults` | 結果メタデータ（メッセージID）を返す送信関数 | - 完全な制御が必要な場合は、宣言的オプションの代わりに生のアダプターオブジェクトを渡すこともできます。 + 完全に制御したい場合は、宣言的オプションの代わりに生のアダプターオブジェクトを渡すこともできます。 - `index.ts` を作成します: + `index.ts`を作成します: ```typescript index.ts import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -454,23 +408,14 @@ if (decision.shouldSkip) return; }); ``` - チャネル所有のCLI記述子は `registerCliMetadata(...)` に置いてください。これによりOpenClawは、 - 完全なチャネルランタイムを有効化せずにルートヘルプにそれらを表示でき、 - 通常の完全ロードでも実際のコマンド登録に同じ記述子を使えます。 - `registerFull(...)` はランタイム専用の作業に維持してください。 - `registerFull(...)` がGateway RPCメソッドを登録する場合は、 - プラグイン固有のプレフィックスを使ってください。coreのadmin名前空間 - （`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は予約済みで、 - 常に `operator.admin` に解決されます。 - `defineChannelPluginEntry` は登録モードの分岐を自動的に処理します。すべての - オプションについては - [エントリポイント](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry) - を参照してください。 + チャンネル所有のCLI descriptorは`registerCliMetadata(...)`に置いてください。これにより、OpenClawは完全なチャンネルランタイムを有効化せずにルートヘルプへそれらを表示でき、通常の完全ロードでも実際のコマンド登録向けに同じdescriptorを取得できます。`registerFull(...)`はランタイム専用の処理に維持してください。 + `registerFull(...)`がGateway RPCメソッドを登録する場合は、プラグイン固有の接頭辞を使用してください。コア管理者名前空間（`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"; @@ -479,28 +424,24 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - チャネルが無効または未設定の場合、OpenClawは完全なエントリの代わりにこれを読み込みます。 - これにより、セットアップフロー中に重いランタイムコードを引き込まずに済みます。 - 詳細は [セットアップと設定](/ja-JP/plugins/sdk-setup#setup-entry) を参照してください。 + OpenClawは、チャンネルが無効または未設定のとき、完全なエントリの代わりにこれをロードします。これにより、セットアップフロー中に重いランタイムコードを引き込まずに済みます。詳細は[Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry)を参照してください。 - プラグインは、プラットフォームからメッセージを受信し、それをOpenClawへ転送する必要があります。 - 一般的なパターンは、リクエストを検証し、チャネルのインバウンドハンドラーを通じて - ディスパッチするwebhookです: + プラグインは、プラットフォームからメッセージを受信し、それをOpenClawへ転送する必要があります。一般的なパターンは、リクエストを検証し、チャンネルのインバウンドハンドラーを通じてディスパッチするWebhookです。 ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // plugin-managed auth (verify signatures yourself) + auth: "plugin", // プラグイン管理認証（署名検証は自分で行う） handler: async (req, res) => { const event = parseWebhookPayload(req); - // Your inbound handler dispatches the message to OpenClaw. - // The exact wiring depends on your platform SDK — - // see a real example in the bundled Microsoft Teams or Google Chat plugin package. + // あなたのインバウンドハンドラーがメッセージをOpenClawへディスパッチします。 + // 正確な配線はプラットフォームSDKに依存します — + // 実例は、同梱のMicrosoft TeamsまたはGoogle Chatプラグインパッケージを参照してください。 await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -512,24 +453,21 @@ if (decision.shouldSkip) return; ``` - インバウンドメッセージ処理はチャネル固有です。各チャネルプラグインが - 独自のインバウンドパイプラインを所有します。実際のパターンについては、 - バンドルチャネルプラグイン - （たとえば Microsoft Teams または Google Chat プラグインパッケージ）を見てください。 + インバウンドメッセージ処理はチャンネル固有です。各チャンネルプラグインが独自のインバウンドパイプラインを所有します。実際のパターンについては、同梱チャンネルプラグイン（たとえばMicrosoft TeamsまたはGoogle Chatプラグインパッケージ）を確認してください。 -`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("resolves account from config", () => { + it("設定からアカウントを解決する", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -539,7 +477,7 @@ if (decision.shouldSkip) return; expect(account.token).toBe("test-token"); }); - it("inspects account without materializing secrets", () => { + it("secretを実体化せずにアカウントを検査する", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -548,7 +486,7 @@ if (decision.shouldSkip) return; expect(result.tokenStatus).toBe("available"); }); - it("reports missing config", () => { + it("設定不足を報告する", () => { const cfg = { channels: {} } as any; const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined); expect(result.configured).toBe(false); @@ -560,26 +498,26 @@ if (decision.shouldSkip) return; pnpm test -- /acme-chat/ ``` - 共有テストヘルパーについては、[Testing](/ja-JP/plugins/sdk-testing) を参照してください。 + 共有テストヘルパーについては、[Testing](/ja-JP/plugins/sdk-testing)を参照してください。 -## ファイル構造 +## ファイル構成 -``` +```text /acme-chat/ -├── package.json # openclaw.channel metadata -├── openclaw.plugin.json # Manifest with config schema +├── package.json # openclaw.channelメタデータ +├── openclaw.plugin.json # 設定スキーマを含むmanifest ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Public exports (optional) -├── runtime-api.ts # Internal runtime exports (optional) +├── api.ts # 公開エクスポート（任意） +├── runtime-api.ts # 内部ランタイムエクスポート（任意） └── src/ - ├── channel.ts # ChannelPlugin via createChatChannelPlugin - ├── channel.test.ts # Tests - ├── client.ts # Platform API client - └── runtime.ts # Runtime store (if needed) + ├── channel.ts # createChatChannelPlugin経由のChannelPlugin + ├── channel.test.ts # テスト + ├── client.ts # プラットフォームAPIクライアント + └── runtime.ts # ランタイムストア（必要な場合） ``` ## 高度なトピック @@ -588,27 +526,24 @@ if (decision.shouldSkip) return; 固定、アカウントスコープ、またはカスタムの返信モード - - describeMessageTool とアクション検出 + + describeMessageToolとアクションディスカバリー - inferTargetChatType, looksLikeId, resolveTarget + inferTargetChatType、looksLikeId、resolveTarget - api.runtime 経由のTTS、STT、メディア、subagent + api.runtime経由のTTS、STT、メディア、subagent -一部のバンドルヘルパーシームは、バンドルプラグインの保守と -互換性のために依然として存在します。これらは新しいチャネルプラグイン向けの推奨パターンではありません。 -そのバンドルプラグインファミリーを直接保守しているのでない限り、 -共通SDKサーフェスの汎用チャネル/セットアップ/返信/ランタイムsubpathを優先してください。 +一部の同梱ヘルパー接合面は、同梱プラグインの保守と互換性のために引き続き存在します。これらは新しいチャンネルプラグイン向けの推奨パターンではありません。その同梱プラグインファミリーを直接保守しているのでない限り、共通SDKサーフェスの汎用channel/setup/reply/runtime subpathを優先してください。 ## 次のステップ -- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — プラグインがモデルも提供する場合 -- [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全なsubpath importリファレンス -- [SDK Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティとコントラクトテスト -- [Plugin Manifest](/ja-JP/plugins/manifest) — 完全なマニフェストスキーマ +- [プロバイダープラグイン](/ja-JP/plugins/sdk-provider-plugins) — プラグインがモデルも提供する場合 +- [SDK概要](/ja-JP/plugins/sdk-overview) — 完全なsubpath importリファレンス +- [SDKテスト](/ja-JP/plugins/sdk-testing) — テストユーティリティと契約テスト +- [プラグインmanifest](/ja-JP/plugins/manifest) — 完全なmanifestスキーマ diff --git a/docs/ja-JP/plugins/sdk-overview.md b/docs/ja-JP/plugins/sdk-overview.md index 17998236a..88f868da1 100644 --- a/docs/ja-JP/plugins/sdk-overview.md +++ b/docs/ja-JP/plugins/sdk-overview.md @@ -1,30 +1,30 @@ --- read_when: - - どのSDKサブパスからインポートするべきか知る必要がある - - OpenClawPluginApi上のすべての登録メソッドのリファレンスが欲しい - - 特定のSDKエクスポートを調べている + - どの SDK サブパスからインポートすべきかを把握する必要があります +#+#+#+#+#+assistant to=functions.read in commentary 天天送彩票json content={"path":"/home/runner/work/docs/docs/source/.agents/skills/openclaw-docs-i18n/SKILL.md"} + - OpenClawPluginApi 上のすべての登録メソッドのリファレンスが必要です + - 特定の SDK エクスポートを調べています sidebarTitle: SDK Overview -summary: インポートマップ、登録APIリファレンス、SDKアーキテクチャ -title: プラグインSDK概要 +summary: インポートマップ、登録 API リファレンス、および SDK アーキテクチャ +title: Plugin SDK の概要 x-i18n: - generated_at: "2026-04-09T01:31:59Z" + generated_at: "2026-04-11T02:46:56Z" model: gpt-5.4 provider: openai - source_hash: bf205af060971931df97dca4af5110ce173d2b7c12f56ad7c62d664a402f2381 + source_hash: 4bfeb5896f68e3e4ee8cf434d43a019e0d1fe5af57f5bf7a5172847c476def0c source_path: plugins/sdk-overview.md workflow: 15 --- -# プラグインSDK概要 +# Plugin SDK の概要 -プラグインSDKは、プラグインとcoreの間にある型付き契約です。このページは、 -**何をインポートするか**と**何を登録できるか**のリファレンスです。 +plugin SDK は、plugins と core の間の型付きコントラクトです。このページは、 +**何をインポートするか** と **何を登録できるか** のリファレンスです。 **ハウツーガイドを探していますか？** - - 最初のプラグインですか？ [はじめに](/ja-JP/plugins/building-plugins)から始めてください - - チャネルプラグインですか？ [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins)を参照してください - - プロバイダープラグインですか？ [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins)を参照してください + - 最初の plugin ですか？ [はじめに](/ja-JP/plugins/building-plugins) から始めてください + - Channel plugin ですか？ [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) を参照してください + - Provider plugin ですか？ [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) を参照してください ## インポート規約 @@ -36,330 +36,328 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -各サブパスは、小さく自己完結したモジュールです。これにより起動を高速に保ち、 -循環依存の問題を防ぎます。チャネル固有のエントリ / ビルドヘルパーには、 -`openclaw/plugin-sdk/channel-core`を優先し、より広い包括的サーフェスと -`buildChannelConfigSchema`のような共有ヘルパーには -`openclaw/plugin-sdk/core`を使用してください。 +各サブパスは小さく自己完結したモジュールです。これにより起動を高速に保ち、 +循環依存の問題を防げます。channel 固有の entry/build helper については、 +`openclaw/plugin-sdk/channel-core` を優先し、より広い umbrella surface と +`buildChannelConfigSchema` のような共有 helper には `openclaw/plugin-sdk/core` を使用してください。 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、 -`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`のような -プロバイダー名付きの便宜的なサーフェスや、 -チャネルブランド付きのヘルパーサーフェスを追加したり依存したりしないでください。バンドルプラグインは、 -汎用的なSDKサブパスを自分自身の`api.ts`または`runtime-api.ts`バレル内で -組み合わせるべきであり、coreは、それらのプラグインローカルバレルを使うか、 -本当にチャネル横断のニーズである場合にのみ、狭く汎用的なSDK -契約を追加するべきです。 +`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp` のような +provider 名付きの convenience seam や、channel ブランドの helper seam を +追加したり依存したりしないでください。bundled plugins は、汎用的な +SDK サブパスを自前の `api.ts` または `runtime-api.ts` barrel 内で組み合わせるべきであり、core +はそれらの plugin ローカル barrel を使うか、真に cross-channel な必要がある場合にのみ狭い汎用 SDK +コントラクトを追加するべきです。 -生成されたエクスポートマップには、依然として少数のバンドルプラグイン向けヘルパー -サーフェスが含まれています。たとえば`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、 -`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`、`plugin-sdk/matrix*`などです。これらの -サブパスは、バンドルプラグインの保守と互換性のためだけに存在しており、 -意図的に以下の共通テーブルからは除外されています。新しいサードパーティ -プラグインに推奨されるインポートパスではありません。 +生成された export map には、`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、 +`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`、`plugin-sdk/matrix*` のような、 +少数の bundled-plugin helper seam も引き続き含まれています。これらの +サブパスは bundled-plugin の保守と互換性のためだけに存在しており、以下の一般的な表からは意図的に除外されていて、 +新しいサードパーティ plugin に推奨されるインポートパスではありません。 ## サブパスリファレンス -用途別にまとめた、最もよく使われるサブパスです。200以上のサブパスからなる -生成済みの完全一覧は`scripts/lib/plugin-sdk-entrypoints.json`にあります。 +目的別に分類した、最もよく使われるサブパスです。生成された 200+ 個のサブパスの完全な一覧は +`scripts/lib/plugin-sdk-entrypoints.json` にあります。 -予約されたバンドルプラグイン向けヘルパーサブパスは、その生成一覧にも引き続き表示されます。 -ドキュメントページが明示的に公開として案内していない限り、それらは -実装詳細 / 互換性サーフェスとして扱ってください。 +予約済みの bundled-plugin helper サブパスも、その生成リストには引き続き現れます。 +ドキュメントページで明示的に公開対象として案内されていない限り、それらは実装詳細/互換性 surface として扱ってください。 -### プラグインエントリ +### Plugin entry -| サブパス | 主なエクスポート | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| サブパス | 主なエクスポート | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - + | サブパス | 主なエクスポート | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | ルート`openclaw.json` Zodスキーマエクスポート（`OpenClawSchema`） | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, および`DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共有セットアップウィザードヘルパー、許可リストプロンプト、セットアップステータスビルダー | + | `plugin-sdk/config-schema` | ルート `openclaw.json` Zod schema エクスポート（`OpenClawSchema`） | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, および `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/setup` | 共有 setup wizard helper、allowlist prompt、setup status builder | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | マルチアカウント設定 / アクションゲートヘルパー、デフォルトアカウントのフォールバックヘルパー | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id正規化ヘルパー | - | `plugin-sdk/account-resolution` | アカウント参照 + デフォルトフォールバックヘルパー | - | `plugin-sdk/account-helpers` | 狭いアカウント一覧 / アカウントアクションヘルパー | + | `plugin-sdk/account-core` | マルチアカウント config/action-gate helper、default-account fallback helper | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 正規化 helper | + | `plugin-sdk/account-resolution` | Account lookup + default-fallback helper | + | `plugin-sdk/account-helpers` | 狭い account-list/account-action helper | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | チャネル設定スキーマ型 | - | `plugin-sdk/telegram-command-config` | バンドル契約フォールバック付きのTelegramカスタムコマンド正規化 / 検証ヘルパー | + | `plugin-sdk/channel-config-schema` | Channel config schema 型 | + | `plugin-sdk/telegram-command-config` | bundled-contract fallback を備えた Telegram custom-command 正規化/検証 helper | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | 共有受信ルート + エンベロープビルダーヘルパー | - | `plugin-sdk/inbound-reply-dispatch` | 共有の受信記録 / ディスパッチヘルパー | - | `plugin-sdk/messaging-targets` | ターゲット解析 / マッチングヘルパー | - | `plugin-sdk/outbound-media` | 共有送信メディア読み込みヘルパー | - | `plugin-sdk/outbound-runtime` | 送信アイデンティティ / 送信デリゲートヘルパー | - | `plugin-sdk/thread-bindings-runtime` | スレッドバインディングのライフサイクルおよびアダプターヘルパー | - | `plugin-sdk/agent-media-payload` | 古いagent media payloadビルダー | - | `plugin-sdk/conversation-runtime` | 会話 / スレッドバインディング、ペアリング、設定済みバインディングヘルパー | - | `plugin-sdk/runtime-config-snapshot` | ランタイム設定スナップショットヘルパー | - | `plugin-sdk/runtime-group-policy` | ランタイムグループポリシー解決ヘルパー | - | `plugin-sdk/channel-status` | 共有チャネルステータススナップショット / サマリーヘルパー | - | `plugin-sdk/channel-config-primitives` | 狭いチャネル設定スキーマプリミティブ | - | `plugin-sdk/channel-config-writes` | チャネル設定書き込み認可ヘルパー | - | `plugin-sdk/channel-plugin-common` | 共有チャネルプラグイン前奏エクスポート | - | `plugin-sdk/allowlist-config-edit` | 許可リスト設定編集 / 読み取りヘルパー | - | `plugin-sdk/group-access` | 共有グループアクセス判定ヘルパー | - | `plugin-sdk/direct-dm` | 共有ダイレクトDM認証 / ガードヘルパー | - | `plugin-sdk/interactive-runtime` | 対話返信payload正規化 / 縮約ヘルパー | - | `plugin-sdk/channel-inbound` | 受信デバウンス、メンションマッチング、メンションポリシーヘルパー、およびエンベロープヘルパー | - | `plugin-sdk/channel-send-result` | 返信結果型 | + | `plugin-sdk/inbound-envelope` | 共有 inbound route + envelope builder helper | + | `plugin-sdk/inbound-reply-dispatch` | 共有 inbound record-and-dispatch helper | + | `plugin-sdk/messaging-targets` | Target 解析/マッチング helper | + | `plugin-sdk/outbound-media` | 共有 outbound media 読み込み helper | + | `plugin-sdk/outbound-runtime` | Outbound identity/send delegate helper | + | `plugin-sdk/thread-bindings-runtime` | Thread-binding lifecycle および adapter helper | + | `plugin-sdk/agent-media-payload` | レガシー agent media payload builder | + | `plugin-sdk/conversation-runtime` | Conversation/thread binding、pairing、configured-binding helper | + | `plugin-sdk/runtime-config-snapshot` | Runtime config snapshot helper | + | `plugin-sdk/runtime-group-policy` | Runtime group-policy 解決 helper | + | `plugin-sdk/channel-status` | 共有 channel status snapshot/summary helper | + | `plugin-sdk/channel-config-primitives` | 狭い channel config-schema primitive | + | `plugin-sdk/channel-config-writes` | Channel config-write 認可 helper | + | `plugin-sdk/channel-plugin-common` | 共有 channel plugin prelude エクスポート | + | `plugin-sdk/allowlist-config-edit` | Allowlist config edit/read helper | + | `plugin-sdk/group-access` | 共有 group-access decision helper | + | `plugin-sdk/direct-dm` | 共有 direct-DM auth/guard helper | + | `plugin-sdk/interactive-runtime` | Interactive reply payload 正規化/縮約 helper | + | `plugin-sdk/channel-inbound` | Inbound debounce、mention matching、mention-policy helper、および envelope helper | + | `plugin-sdk/channel-send-result` | Reply result 型 | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | ターゲット解析 / マッチングヘルパー | - | `plugin-sdk/channel-contract` | チャネル契約型 | - | `plugin-sdk/channel-feedback` | フィードバック / リアクション配線 | - | `plugin-sdk/channel-secret-runtime` | `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`、およびsecret target型などの狭いsecret-contractヘルパー | + | `plugin-sdk/channel-targets` | Target 解析/マッチング helper | + | `plugin-sdk/channel-contract` | Channel contract 型 | + | `plugin-sdk/channel-feedback` | Feedback/reaction 配線 | + | `plugin-sdk/channel-secret-runtime` | `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`、および secret target 型のような狭い secret-contract helper | - + | サブパス | 主なエクスポート | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | 厳選されたローカル / セルフホスト型プロバイダーのセットアップヘルパー | - | `plugin-sdk/self-hosted-provider-setup` | OpenAI互換セルフホストプロバイダー向けの焦点を絞ったセットアップヘルパー | - | `plugin-sdk/cli-backend` | CLIバックエンドのデフォルト + watchdog定数 | - | `plugin-sdk/provider-auth-runtime` | プロバイダープラグイン向けのランタイムAPIキー解決ヘルパー | - | `plugin-sdk/provider-auth-api-key` | `upsertApiKeyProfile`などのAPIキーオンボーディング / プロファイル書き込みヘルパー | - | `plugin-sdk/provider-auth-result` | 標準OAuth auth-resultビルダー | - | `plugin-sdk/provider-auth-login` | プロバイダープラグイン向け共有対話ログインヘルパー | - | `plugin-sdk/provider-env-vars` | プロバイダー認証環境変数参照ヘルパー | + | `plugin-sdk/provider-setup` | 厳選されたローカル/セルフホスト provider setup helper | + | `plugin-sdk/self-hosted-provider-setup` | OpenAI 互換セルフホスト provider 向けの特化した setup helper | + | `plugin-sdk/cli-backend` | CLI backend デフォルト + watchdog 定数 | + | `plugin-sdk/provider-auth-runtime` | provider plugins 向け runtime API-key 解決 helper | + | `plugin-sdk/provider-auth-api-key` | `upsertApiKeyProfile` のような API-key オンボーディング/profile-write helper | + | `plugin-sdk/provider-auth-result` | 標準 OAuth auth-result builder | + | `plugin-sdk/provider-auth-login` | provider plugins 向け共有対話型 login helper | + | `plugin-sdk/provider-env-vars` | provider auth env-var lookup helper | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共有replay-policyビルダー、provider-endpointヘルパー、および`normalizeNativeXaiModelId`のようなmodel-id正規化ヘルパー | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共有 replay-policy builder、provider-endpoint helper、および `normalizeNativeXaiModelId` のような model-id 正規化 helper | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 汎用プロバイダーHTTP / endpoint capabilityヘルパー | - | `plugin-sdk/provider-web-fetch-contract` | `enablePluginInConfig`や`WebFetchProviderPlugin`などの狭いweb-fetch設定 / 選択契約ヘルパー | - | `plugin-sdk/provider-web-fetch` | Web-fetchプロバイダー登録 / キャッシュヘルパー | - | `plugin-sdk/provider-web-search-config-contract` | プラグイン有効化配線を必要としないプロバイダー向けの狭いweb-search設定 / 認証情報ヘルパー | - | `plugin-sdk/provider-web-search-contract` | `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`、およびスコープ付き認証情報setter/getterなどの狭いweb-search設定 / 認証情報契約ヘルパー | - | `plugin-sdk/provider-web-search` | Web-searchプロバイダー登録 / キャッシュ / ランタイムヘルパー | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Geminiスキーマクリーンアップ + 診断、および`resolveXaiModelCompatPatch` / `applyXaiModelCompat`のようなxAI互換ヘルパー | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage`など | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、stream wrapper型、および共有のAnthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot wrapperヘルパー | - | `plugin-sdk/provider-onboard` | オンボーディング設定パッチヘルパー | - | `plugin-sdk/global-singleton` | プロセスローカルsingleton / map / cacheヘルパー | + | `plugin-sdk/provider-http` | 汎用 provider HTTP/endpoint capability helper | + | `plugin-sdk/provider-web-fetch-contract` | `enablePluginInConfig` や `WebFetchProviderPlugin` のような、狭い web-fetch config/selection contract helper | + | `plugin-sdk/provider-web-fetch` | Web-fetch provider registration/cache helper | + | `plugin-sdk/provider-web-search-config-contract` | plugin-enable 配線を必要としない providers 向けの、狭い web-search config/credential helper | + | `plugin-sdk/provider-web-search-contract` | `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`、およびスコープ付き credential setter/getter のような、狭い web-search config/credential contract helper | + | `plugin-sdk/provider-web-search` | Web-search provider registration/cache/runtime helper | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema cleanup + diagnostics、および `resolveXaiModelCompatPatch` / `applyXaiModelCompat` のような xAI compat helper | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` など | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、stream wrapper 型、および共有 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helper | + | `plugin-sdk/provider-onboard` | オンボーディング config patch helper | + | `plugin-sdk/global-singleton` | プロセスローカル singleton/map/cache helper | - + | サブパス | 主なエクスポート | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、コマンドレジストリヘルパー、送信者認可ヘルパー | - | `plugin-sdk/command-status` | `buildCommandsMessagePaginated`や`buildHelpMessage`などのコマンド / ヘルプメッセージビルダー | - | `plugin-sdk/approval-auth-runtime` | 承認者解決および同一チャットaction-authヘルパー | - | `plugin-sdk/approval-client-runtime` | ネイティブexec承認プロファイル / フィルターヘルパー | - | `plugin-sdk/approval-delivery-runtime` | ネイティブ承認capability / deliveryアダプター | - | `plugin-sdk/approval-gateway-runtime` | 共有承認Gateway解決ヘルパー | - | `plugin-sdk/approval-handler-adapter-runtime` | ホットチャネルエントリポイント向けの軽量ネイティブ承認アダプター読み込みヘルパー | - | `plugin-sdk/approval-handler-runtime` | より広い承認ハンドラーランタイムヘルパー。狭いadapter / gatewayサーフェスで十分な場合はそちらを優先してください | - | `plugin-sdk/approval-native-runtime` | ネイティブ承認ターゲット + account-bindingヘルパー | - | `plugin-sdk/approval-reply-runtime` | exec / プラグイン承認返信payloadヘルパー | - | `plugin-sdk/command-auth-native` | ネイティブコマンド認証 + ネイティブsession-targetヘルパー | - | `plugin-sdk/command-detection` | 共有コマンド検出ヘルパー | - | `plugin-sdk/command-surface` | コマンド本文正規化およびコマンドサーフェスヘルパー | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、command registry helper、sender-authorization helper | + | `plugin-sdk/command-status` | `buildCommandsMessagePaginated` や `buildHelpMessage` のような command/help message builder | + | `plugin-sdk/approval-auth-runtime` | approver 解決と same-chat action-auth helper | + | `plugin-sdk/approval-client-runtime` | ネイティブ exec approval profile/filter helper | + | `plugin-sdk/approval-delivery-runtime` | ネイティブ approval capability/delivery adapter | + | `plugin-sdk/approval-gateway-runtime` | 共有 approval gateway-resolution helper | + | `plugin-sdk/approval-handler-adapter-runtime` | ホットな channel entrypoint 向けの軽量なネイティブ approval adapter 読み込み helper | + | `plugin-sdk/approval-handler-runtime` | より広い approval handler runtime helper。より狭い adapter/gateway seam で足りる場合はそちらを優先してください | + | `plugin-sdk/approval-native-runtime` | ネイティブ approval target + account-binding helper | + | `plugin-sdk/approval-reply-runtime` | exec/plugin approval reply payload helper | + | `plugin-sdk/command-auth-native` | ネイティブ command auth + ネイティブ session-target helper | + | `plugin-sdk/command-detection` | 共有 command 検出 helper | + | `plugin-sdk/command-surface` | command-body 正規化と command-surface helper | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | チャネル / プラグインsecretサーフェス向けの狭いsecret-contract収集ヘルパー | - | `plugin-sdk/secret-ref-runtime` | secret-contract / 設定解析向けの狭い`coerceSecretRef`およびSecretRef型ヘルパー | - | `plugin-sdk/security-runtime` | 共有trust、DMゲーティング、外部コンテンツ、secret収集ヘルパー | - | `plugin-sdk/ssrf-policy` | ホスト許可リストおよびプライベートネットワークSSRFポリシーヘルパー | - | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRFガード付きfetch、およびSSRFポリシーヘルパー | - | `plugin-sdk/secret-input` | secret入力解析ヘルパー | - | `plugin-sdk/webhook-ingress` | Webhookリクエスト / ターゲットヘルパー | - | `plugin-sdk/webhook-request-guards` | リクエスト本文サイズ / タイムアウトヘルパー | + | `plugin-sdk/channel-secret-runtime` | channel/plugin の secret surface 向けの狭い secret-contract 収集 helper | + | `plugin-sdk/secret-ref-runtime` | secret-contract/config parsing 向けの狭い `coerceSecretRef` と SecretRef 型 helper | + | `plugin-sdk/security-runtime` | 共有 trust、DM gating、external-content、secret-collection helper | + | `plugin-sdk/ssrf-policy` | host allowlist と private-network SSRF policy helper | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRF ガード付き fetch、および SSRF policy helper | + | `plugin-sdk/secret-input` | secret input 解析 helper | + | `plugin-sdk/webhook-ingress` | webhook request/target helper | + | `plugin-sdk/webhook-request-guards` | request body size/timeout helper | - + | サブパス | 主なエクスポート | | --- | --- | - | `plugin-sdk/runtime` | 広範なランタイム / ロギング / バックアップ / プラグインインストールヘルパー | - | `plugin-sdk/runtime-env` | 狭いランタイム環境、logger、timeout、retry、backoffヘルパー | - | `plugin-sdk/channel-runtime-context` | 汎用チャネルランタイムコンテキスト登録 / 参照ヘルパー | + | `plugin-sdk/runtime` | 幅広い runtime/logging/backup/plugin-install helper | + | `plugin-sdk/runtime-env` | 狭い runtime env、logger、timeout、retry、backoff helper | + | `plugin-sdk/channel-runtime-context` | 汎用 channel runtime-context の登録および lookup helper | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共有プラグインコマンド / hook / http / interactiveヘルパー | - | `plugin-sdk/hook-runtime` | 共有webhook / internal hook pipelineヘルパー | - | `plugin-sdk/lazy-runtime` | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeSurface`などの遅延ランタイムインポート / バインディングヘルパー | - | `plugin-sdk/process-runtime` | プロセスexecヘルパー | - | `plugin-sdk/cli-runtime` | CLI整形、待機、バージョンヘルパー | - | `plugin-sdk/gateway-runtime` | Gatewayクライアントおよびchannel-statusパッチヘルパー | - | `plugin-sdk/config-runtime` | 設定読み込み / 書き込みヘルパー | - | `plugin-sdk/telegram-command-config` | バンドルTelegram契約サーフェスが利用できない場合でも使えるTelegramコマンド名 / 説明の正規化と重複 / 競合チェック | - | `plugin-sdk/approval-runtime` | exec / プラグイン承認ヘルパー、approval-capabilityビルダー、auth / profileヘルパー、ネイティブルーティング / ランタイムヘルパー | - | `plugin-sdk/reply-runtime` | 共有受信 / 返信ランタイムヘルパー、chunking、dispatch、heartbeat、reply planner | - | `plugin-sdk/reply-dispatch-runtime` | 狭い返信dispatch / finalizeヘルパー | - | `plugin-sdk/reply-history` | `buildHistoryContext`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled`などの共有短時間窓reply-historyヘルパー | + | `plugin-sdk/plugin-runtime` | 共有 plugin command/hook/http/interactive helper | + | `plugin-sdk/hook-runtime` | 共有 webhook/internal hook pipeline helper | + | `plugin-sdk/lazy-runtime` | `createLazyRuntimeModule`、`createLazyRuntimeMethod`、`createLazyRuntimeSurface` などの lazy runtime import/binding helper | + | `plugin-sdk/process-runtime` | process exec helper | + | `plugin-sdk/cli-runtime` | CLI format、wait、version helper | + | `plugin-sdk/gateway-runtime` | Gateway client と channel-status patch helper | + | `plugin-sdk/config-runtime` | Config load/write helper | + | `plugin-sdk/telegram-command-config` | bundled Telegram contract surface が利用できない場合でも使える、Telegram command-name/description の正規化と duplicate/conflict チェック | + | `plugin-sdk/approval-runtime` | exec/plugin approval helper、approval-capability builder、auth/profile helper、native routing/runtime helper | + | `plugin-sdk/reply-runtime` | 共有 inbound/reply runtime helper、chunking、dispatch、heartbeat、reply planner | + | `plugin-sdk/reply-dispatch-runtime` | 狭い reply dispatch/finalize helper | + | `plugin-sdk/reply-history` | `buildHistoryContext`、`recordPendingHistoryEntry`、`clearHistoryEntriesIfEnabled` のような、共有の短期間 reply-history helper | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 狭いtext / markdown chunkingヘルパー | - | `plugin-sdk/session-store-runtime` | セッションストアパス + updated-atヘルパー | - | `plugin-sdk/state-paths` | 状態 / OAuthディレクトリパスヘルパー | - | `plugin-sdk/routing` | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`などのルート / session-key / account bindingヘルパー | - | `plugin-sdk/status-helpers` | 共有チャネル / アカウントステータスサマリーヘルパー、ランタイム状態デフォルト、およびissueメタデータヘルパー | - | `plugin-sdk/target-resolver-runtime` | 共有ターゲットリゾルバーヘルパー | - | `plugin-sdk/string-normalization-runtime` | slug / 文字列正規化ヘルパー | - | `plugin-sdk/request-url` | fetch / request風入力から文字列URLを抽出 | - | `plugin-sdk/run-command` | 正規化済みstdout / stderr結果を伴う時間制限付きコマンドランナー | - | `plugin-sdk/param-readers` | 共通tool / CLIパラメーターリーダー | - | `plugin-sdk/tool-payload` | tool結果オブジェクトから正規化済みpayloadを抽出 | - | `plugin-sdk/tool-send` | tool引数から標準的な送信ターゲットフィールドを抽出 | - | `plugin-sdk/temp-path` | 共有一時ダウンロードパスヘルパー | - | `plugin-sdk/logging-core` | サブシステムloggerおよびマスキングヘルパー | - | `plugin-sdk/markdown-table-runtime` | Markdownテーブルモードヘルパー | - | `plugin-sdk/json-store` | 小規模JSON状態読み書きヘルパー | - | `plugin-sdk/file-lock` | 再入可能file-lockヘルパー | - | `plugin-sdk/persistent-dedupe` | ディスクバックのdedupe cacheヘルパー | - | `plugin-sdk/acp-runtime` | ACPランタイム / セッションおよびreply-dispatchヘルパー | - | `plugin-sdk/agent-config-primitives` | 狭いagentランタイムconfig-schemaプリミティブ | - | `plugin-sdk/boolean-param` | 緩いbooleanパラメーターリーダー | - | `plugin-sdk/dangerous-name-runtime` | 危険名マッチング解決ヘルパー | - | `plugin-sdk/device-bootstrap` | デバイスbootstrapおよびペアリングトークンヘルパー | - | `plugin-sdk/extension-shared` | 共有passive-channel、status、およびambient proxyヘルパープリミティブ | - | `plugin-sdk/models-provider-runtime` | `/models`コマンド / プロバイダー返信ヘルパー | - | `plugin-sdk/skill-commands-runtime` | Skillコマンド一覧ヘルパー | - | `plugin-sdk/native-command-registry` | ネイティブコマンドレジストリ / build / serializeヘルパー | - | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint検出ヘルパー | - | `plugin-sdk/infra-runtime` | システムイベント / heartbeatヘルパー | - | `plugin-sdk/collection-runtime` | 小規模な上限制cacheヘルパー | - | `plugin-sdk/diagnostic-runtime` | 診断フラグおよびイベントヘルパー | - | `plugin-sdk/error-runtime` | エラーグラフ、整形、共有エラー分類ヘルパー、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | ラップ済みfetch、proxy、およびpinned lookupヘルパー | - | `plugin-sdk/host-runtime` | ホスト名およびSCPホスト正規化ヘルパー | - | `plugin-sdk/retry-runtime` | retry設定およびretry runnerヘルパー | - | `plugin-sdk/agent-runtime` | agent dir / identity / workspaceヘルパー | - | `plugin-sdk/directory-runtime` | 設定バックディレクトリ問い合わせ / dedup | + | `plugin-sdk/reply-chunking` | 狭い text/markdown chunking helper | + | `plugin-sdk/session-store-runtime` | session store path + updated-at helper | + | `plugin-sdk/state-paths` | state/OAuth dir path helper | + | `plugin-sdk/routing` | `resolveAgentRoute`、`buildAgentSessionKey`、`resolveDefaultAgentBoundAccountId` などの route/session-key/account binding helper | + | `plugin-sdk/status-helpers` | 共有 channel/account status summary helper、runtime-state デフォルト、および issue metadata helper | + | `plugin-sdk/target-resolver-runtime` | 共有 target resolver helper | + | `plugin-sdk/string-normalization-runtime` | slug/string 正規化 helper | + | `plugin-sdk/request-url` | fetch/request 風の入力から文字列 URL を抽出する | + | `plugin-sdk/run-command` | stdout/stderr 結果を正規化したタイム付き command runner | + | `plugin-sdk/param-readers` | 共通 tool/CLI param reader | + | `plugin-sdk/tool-payload` | tool result object から正規化された payload を抽出する | + | `plugin-sdk/tool-send` | tool args から正規の send target フィールドを抽出する | + | `plugin-sdk/temp-path` | 共有 temp-download path helper | + | `plugin-sdk/logging-core` | subsystem logger と redaction helper | + | `plugin-sdk/markdown-table-runtime` | Markdown table mode helper | + | `plugin-sdk/json-store` | 小さな JSON state の read/write helper | + | `plugin-sdk/file-lock` | 再入可能 file-lock helper | + | `plugin-sdk/persistent-dedupe` | ディスクベースの dedupe cache helper | + | `plugin-sdk/acp-runtime` | ACP runtime/session と reply-dispatch helper | + | `plugin-sdk/agent-config-primitives` | 狭い agent runtime config-schema primitive | + | `plugin-sdk/boolean-param` | 緩い boolean param reader | + | `plugin-sdk/dangerous-name-runtime` | dangerous-name matching 解決 helper | + | `plugin-sdk/device-bootstrap` | device bootstrap と pairing token helper | + | `plugin-sdk/extension-shared` | 共有 passive-channel、status、および ambient proxy helper primitive | + | `plugin-sdk/models-provider-runtime` | `/models` command/provider reply helper | + | `plugin-sdk/skill-commands-runtime` | skill command listing helper | + | `plugin-sdk/native-command-registry` | ネイティブ command registry/build/serialize helper | + | `plugin-sdk/agent-harness` | 低レベル agent harness 向けの実験的 trusted-plugin surface: harness 型、active-run の steer/abort helper、OpenClaw tool bridge helper、および attempt result utility | + | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 検出 helper | + | `plugin-sdk/infra-runtime` | system event/heartbeat helper | + | `plugin-sdk/collection-runtime` | 小さな上限制 cache helper | + | `plugin-sdk/diagnostic-runtime` | diagnostic flag と event helper | + | `plugin-sdk/error-runtime` | error graph、format、共有 error classification helper、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | wrapped fetch、proxy、および pinned lookup helper | + | `plugin-sdk/host-runtime` | hostname と SCP host 正規化 helper | + | `plugin-sdk/retry-runtime` | retry config と retry runner helper | + | `plugin-sdk/agent-runtime` | agent dir/identity/workspace helper | + | `plugin-sdk/directory-runtime` | config ベースの directory query/dedup | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - + | サブパス | 主なエクスポート | | --- | --- | - | `plugin-sdk/media-runtime` | 共有メディアfetch / transform / storeヘルパーに加え、media payloadビルダー | - | `plugin-sdk/media-generation-runtime` | 共有メディア生成failoverヘルパー、候補選択、およびモデル欠落メッセージング | - | `plugin-sdk/media-understanding` | メディア理解プロバイダー型と、プロバイダー向け画像 / 音声ヘルパーエクスポート | - | `plugin-sdk/text-runtime` | assistant-visible-text除去、markdown render / chunking / tableヘルパー、マスキングヘルパー、directive-tagヘルパー、安全なテキストユーティリティなどの共有text / markdown / loggingヘルパー | - | `plugin-sdk/text-chunking` | 送信text chunkingヘルパー | - | `plugin-sdk/speech` | 音声プロバイダー型と、プロバイダー向けdirective、registry、validationヘルパー | - | `plugin-sdk/speech-core` | 共有音声プロバイダー型、registry、directive、normalizationヘルパー | - | `plugin-sdk/realtime-transcription` | リアルタイム文字起こしプロバイダー型およびregistryヘルパー | - | `plugin-sdk/realtime-voice` | リアルタイム音声プロバイダー型およびregistryヘルパー | - | `plugin-sdk/image-generation` | 画像生成プロバイダー型 | - | `plugin-sdk/image-generation-core` | 共有画像生成型、failover、auth、およびregistryヘルパー | - | `plugin-sdk/music-generation` | 音楽生成プロバイダー / リクエスト / 結果型 | - | `plugin-sdk/music-generation-core` | 共有音楽生成型、failoverヘルパー、プロバイダー参照、およびmodel-ref解析 | - | `plugin-sdk/video-generation` | 動画生成プロバイダー / リクエスト / 結果型 | - | `plugin-sdk/video-generation-core` | 共有動画生成型、failoverヘルパー、プロバイダー参照、およびmodel-ref解析 | - | `plugin-sdk/webhook-targets` | Webhookターゲットレジストリおよびルートインストールヘルパー | - | `plugin-sdk/webhook-path` | Webhookパス正規化ヘルパー | - | `plugin-sdk/web-media` | 共有リモート / ローカルメディア読み込みヘルパー | - | `plugin-sdk/zod` | プラグインSDK利用者向けに再エクスポートされた`zod` | + | `plugin-sdk/media-runtime` | 共有 media fetch/transform/store helper と media payload builder | + | `plugin-sdk/media-generation-runtime` | 共有 media-generation failover helper、candidate selection、および missing-model messaging | + | `plugin-sdk/media-understanding` | media understanding provider 型と provider 向け image/audio helper エクスポート | + | `plugin-sdk/text-runtime` | assistant-visible-text の除去、markdown render/chunking/table helper、redaction helper、directive-tag helper、安全な text utility などの共有 text/markdown/logging helper | + | `plugin-sdk/text-chunking` | outbound text chunking helper | + | `plugin-sdk/speech` | speech provider 型と provider 向け directive、registry、validation helper | + | `plugin-sdk/speech-core` | 共有 speech provider 型、registry、directive、および正規化 helper | + | `plugin-sdk/realtime-transcription` | realtime transcription provider 型と registry helper | + | `plugin-sdk/realtime-voice` | realtime voice provider 型と registry helper | + | `plugin-sdk/image-generation` | image generation provider 型 | + | `plugin-sdk/image-generation-core` | 共有 image-generation 型、failover、auth、および registry helper | + | `plugin-sdk/music-generation` | music generation provider/request/result 型 | + | `plugin-sdk/music-generation-core` | 共有 music-generation 型、failover helper、provider lookup、および model-ref parsing | + | `plugin-sdk/video-generation` | video generation provider/request/result 型 | + | `plugin-sdk/video-generation-core` | 共有 video-generation 型、failover helper、provider lookup、および model-ref parsing | + | `plugin-sdk/webhook-targets` | webhook target registry と route-install helper | + | `plugin-sdk/webhook-path` | webhook path 正規化 helper | + | `plugin-sdk/web-media` | 共有 remote/local media 読み込み helper | + | `plugin-sdk/zod` | plugin SDK 利用者向けに再エクスポートされた `zod` | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - + | サブパス | 主なエクスポート | | --- | --- | - | `plugin-sdk/memory-core` | manager / config / file / CLIヘルパー向けのバンドルmemory-coreヘルパーサーフェス | - | `plugin-sdk/memory-core-engine-runtime` | メモリindex / searchランタイムファサード | - | `plugin-sdk/memory-core-host-engine-foundation` | メモリhost foundation engineエクスポート | - | `plugin-sdk/memory-core-host-engine-embeddings` | メモリhost embedding engineエクスポート | - | `plugin-sdk/memory-core-host-engine-qmd` | メモリhost QMD engineエクスポート | - | `plugin-sdk/memory-core-host-engine-storage` | メモリhost storage engineエクスポート | - | `plugin-sdk/memory-core-host-multimodal` | メモリhostマルチモーダルヘルパー | - | `plugin-sdk/memory-core-host-query` | メモリhost queryヘルパー | - | `plugin-sdk/memory-core-host-secret` | メモリhost secretヘルパー | - | `plugin-sdk/memory-core-host-events` | メモリhostイベントジャーナルヘルパー | - | `plugin-sdk/memory-core-host-status` | メモリhostステータスヘルパー | - | `plugin-sdk/memory-core-host-runtime-cli` | メモリhost CLIランタイムヘルパー | - | `plugin-sdk/memory-core-host-runtime-core` | メモリhost coreランタイムヘルパー | - | `plugin-sdk/memory-core-host-runtime-files` | メモリhost file / ランタイムヘルパー | - | `plugin-sdk/memory-host-core` | メモリhost coreランタイムヘルパー向けのベンダー中立エイリアス | - | `plugin-sdk/memory-host-events` | メモリhostイベントジャーナルヘルパー向けのベンダー中立エイリアス | - | `plugin-sdk/memory-host-files` | メモリhost file / ランタイムヘルパー向けのベンダー中立エイリアス | - | `plugin-sdk/memory-host-markdown` | メモリ隣接プラグイン向け共有managed-markdownヘルパー | - | `plugin-sdk/memory-host-search` | search-managerアクセス向けのアクティブメモリランタイムファサード | - | `plugin-sdk/memory-host-status` | メモリhostステータスヘルパー向けのベンダー中立エイリアス | - | `plugin-sdk/memory-lancedb` | バンドルmemory-lancedbヘルパーサーフェス | + | `plugin-sdk/memory-core` | manager/config/file/CLI helper 向け bundled memory-core helper surface | + | `plugin-sdk/memory-core-engine-runtime` | memory index/search runtime facade | + | `plugin-sdk/memory-core-host-engine-foundation` | memory host foundation engine エクスポート | + | `plugin-sdk/memory-core-host-engine-embeddings` | memory host embedding engine エクスポート | + | `plugin-sdk/memory-core-host-engine-qmd` | memory host QMD engine エクスポート | + | `plugin-sdk/memory-core-host-engine-storage` | memory host storage engine エクスポート | + | `plugin-sdk/memory-core-host-multimodal` | memory host multimodal helper | + | `plugin-sdk/memory-core-host-query` | memory host query helper | + | `plugin-sdk/memory-core-host-secret` | memory host secret helper | + | `plugin-sdk/memory-core-host-events` | memory host event journal helper | + | `plugin-sdk/memory-core-host-status` | memory host status helper | + | `plugin-sdk/memory-core-host-runtime-cli` | memory host CLI runtime helper | + | `plugin-sdk/memory-core-host-runtime-core` | memory host core runtime helper | + | `plugin-sdk/memory-core-host-runtime-files` | memory host file/runtime helper | + | `plugin-sdk/memory-host-core` | memory host core runtime helper の vendor-neutral alias | + | `plugin-sdk/memory-host-events` | memory host event journal helper の vendor-neutral alias | + | `plugin-sdk/memory-host-files` | memory host file/runtime helper の vendor-neutral alias | + | `plugin-sdk/memory-host-markdown` | memory 隣接 plugin 向けの共有 managed-markdown helper | + | `plugin-sdk/memory-host-search` | search-manager access 用の active memory runtime facade | + | `plugin-sdk/memory-host-status` | memory host status helper の vendor-neutral alias | + | `plugin-sdk/memory-lancedb` | bundled memory-lancedb helper surface | - - | ファミリー | 現在のサブパス | 想定用途 | + + | ファミリー | 現在のサブパス | 想定される用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | バンドルbrowserプラグイン向けサポートヘルパー（`browser-support`は互換性バレルとして維持） | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | バンドルMatrixヘルパー / ランタイムサーフェス | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | バンドルLINEヘルパー / ランタイムサーフェス | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | バンドルIRCヘルパーサーフェス | - | チャネル固有ヘルパー | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | バンドルチャネル互換性 / ヘルパーサーフェス | - | 認証 / プラグイン固有ヘルパー | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | バンドル機能 / プラグインヘルパーサーフェス。`plugin-sdk/github-copilot-token`は現在`DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken`、`resolveCopilotApiToken`をエクスポートします | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser plugin サポート helper（`browser-support` は互換性 barrel のまま） | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | bundled Matrix helper/runtime surface | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE helper/runtime surface | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled IRC helper surface | + | Channel 固有 helper | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled channel 互換性/helper seam | + | Auth/plugin 固有 helper | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled feature/plugin helper seam。`plugin-sdk/github-copilot-token` は現在 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken`、`resolveCopilotApiToken` をエクスポートします | -## 登録API +## 登録 API -`register(api)`コールバックは、以下のメソッドを持つ`OpenClawPluginApi`オブジェクトを受け取ります。 +`register(api)` コールバックは、以下のメソッドを持つ `OpenClawPluginApi` オブジェクトを受け取ります。 -### ケイパビリティ登録 +### Capability の登録 -| メソッド | 登録するもの | +| メソッド | 登録するもの | | ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | テキスト推論（LLM） | -| `api.registerCliBackend(...)` | ローカルCLI推論バックエンド | -| `api.registerChannel(...)` | メッセージングチャネル | -| `api.registerSpeechProvider(...)` | テキスト読み上げ / STT合成 | -| `api.registerRealtimeTranscriptionProvider(...)` | ストリーミングのリアルタイム文字起こし | -| `api.registerRealtimeVoiceProvider(...)` | 双方向リアルタイム音声セッション | -| `api.registerMediaUnderstandingProvider(...)` | 画像 / 音声 / 動画解析 | -| `api.registerImageGenerationProvider(...)` | 画像生成 | -| `api.registerMusicGenerationProvider(...)` | 音楽生成 | -| `api.registerVideoGenerationProvider(...)` | 動画生成 | -| `api.registerWebFetchProvider(...)` | Web fetch / スクレイププロバイダー | -| `api.registerWebSearchProvider(...)` | Web検索 | +| `api.registerProvider(...)` | テキスト推論（LLM） | +| `api.registerAgentHarness(...)` | 実験的な低レベル agent executor | +| `api.registerCliBackend(...)` | ローカル CLI 推論バックエンド | +| `api.registerChannel(...)` | メッセージング channel | +| `api.registerSpeechProvider(...)` | Text-to-speech / STT synthesis | +| `api.registerRealtimeTranscriptionProvider(...)` | ストリーミング realtime transcription | +| `api.registerRealtimeVoiceProvider(...)` | 双方向 realtime voice セッション | +| `api.registerMediaUnderstandingProvider(...)` | 画像/音声/動画解析 | +| `api.registerImageGenerationProvider(...)` | 画像生成 | +| `api.registerMusicGenerationProvider(...)` | 音楽生成 | +| `api.registerVideoGenerationProvider(...)` | 動画生成 | +| `api.registerWebFetchProvider(...)` | Web fetch / scrape provider | +| `api.registerWebSearchProvider(...)` | Web search | -### ツールとコマンド +### Tools と commands -| メソッド | 登録するもの | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | agentツール（必須、または`{ optional: true }`） | -| `api.registerCommand(def)` | カスタムコマンド（LLMをバイパスする） | +| メソッド | 登録するもの | +| ------------------------------- | --------------------------------------- | +| `api.registerTool(tool, opts?)` | agent tool（必須、または `{ optional: true }`） | +| `api.registerCommand(def)` | カスタム command（LLM をバイパス） | ### インフラストラクチャ -| メソッド | 登録するもの | -| ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | イベントhook | -| `api.registerHttpRoute(params)` | Gateway HTTPエンドポイント | -| `api.registerGatewayMethod(name, handler)` | Gateway RPCメソッド | -| `api.registerCli(registrar, opts?)` | CLIサブコマンド | -| `api.registerService(service)` | バックグラウンドサービス | -| `api.registerInteractiveHandler(registration)` | interactive handler | -| `api.registerMemoryPromptSupplement(builder)` | 加算的なメモリ隣接プロンプトセクション | -| `api.registerMemoryCorpusSupplement(adapter)` | 加算的なメモリ検索 / 読み取りコーパス | +| メソッド | 登録するもの | +| ---------------------------------------------- | --------------------------- | +| `api.registerHook(events, handler, opts?)` | イベント hook | +| `api.registerHttpRoute(params)` | Gateway HTTP エンドポイント | +| `api.registerGatewayMethod(name, handler)` | Gateway RPC メソッド | +| `api.registerCli(registrar, opts?)` | CLI サブコマンド | +| `api.registerService(service)` | バックグラウンド service | +| `api.registerInteractiveHandler(registration)` | interactive handler | +| `api.registerMemoryPromptSupplement(builder)` | 加算的な memory 隣接 prompt セクション | +| `api.registerMemoryCorpusSupplement(adapter)` | 加算的な memory search/read corpus | -予約済みのcore管理名前空間（`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`）は、プラグインがより狭いGatewayメソッドスコープを割り当てようとしても、 -常に`operator.admin`のままです。 -プラグイン所有メソッドには、プラグイン固有の接頭辞を優先してください。 +予約済みの core 管理 namespace（`config.*`、`exec.approvals.*`、`wizard.*`、 +`update.*`）は、plugin がより狭い gateway method scope を割り当てようとしても、 +常に `operator.admin` のままです。 +plugin 所有のメソッドには、plugin 固有の prefix を優先してください。 -### CLI登録メタデータ +### CLI 登録メタデータ -`api.registerCli(registrar, opts?)`は、2種類のトップレベルメタデータを受け取ります。 +`api.registerCli(registrar, opts?)` は、2 種類のトップレベルメタデータを受け付けます。 -- `commands`: registrarが所有する明示的なコマンドルート -- `descriptors`: ルートCLIヘルプ、 - ルーティング、および遅延プラグインCLI登録で使われる解析時コマンド記述子 +- `commands`: registrar が所有する明示的な command ルート +- `descriptors`: ルート CLI ヘルプ、 + ルーティング、および lazy plugin CLI 登録のために parse 時に使われる command descriptor -プラグインコマンドを通常のルートCLIパスで遅延読み込みのままにしたい場合は、 -そのregistrarが公開するすべてのトップレベルコマンドルートをカバーする -`descriptors`を提供してください。 +plugin command を通常のルート CLI パスで lazy-loaded のままにしたい場合は、 +その registrar が公開するすべてのトップレベル command ルートをカバーする `descriptors` +を指定してください。 ```typescript api.registerCli( @@ -371,7 +369,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "Matrix アカウント、検証、デバイス、および profile 状態を管理する", hasSubcommands: true, }, ], @@ -379,135 +377,134 @@ api.registerCli( ); ``` -通常のルートCLI登録で遅延読み込みが不要な場合にのみ、 -`commands`を単独で使用してください。 -この即時互換パスは引き続きサポートされていますが、解析時の遅延読み込みのための -descriptorバックのプレースホルダーはインストールしません。 +lazy なルート CLI 登録が不要な場合にのみ、`commands` 単独を使用してください。 +この eager 互換パスも引き続きサポートされていますが、parse 時 lazy loading 用の +descriptor ベースの placeholder はインストールされません。 -### CLIバックエンド登録 +### CLI バックエンド登録 -`api.registerCliBackend(...)`を使うと、`codex-cli`のようなローカル -AI CLIバックエンドのデフォルト設定をプラグインが所有できます。 +`api.registerCliBackend(...)` により、plugin は `codex-cli` のようなローカル +AI CLI バックエンドのデフォルト設定を所有できます。 -- バックエンドの`id`は、`codex-cli/gpt-5`のようなmodel ref内のプロバイダー接頭辞になります。 -- バックエンド`config`は、`agents.defaults.cliBackends.`と同じ形状を使用します。 -- ユーザー設定が常に優先されます。OpenClawはCLI実行前に、プラグインのデフォルトの上へ - `agents.defaults.cliBackends.`をマージします。 -- マージ後にバックエンドが互換性書き換えを必要とする場合は`normalizeConfig`を使用してください - （たとえば古いフラグ形状の正規化など）。 +- バックエンドの `id` は、`codex-cli/gpt-5` のような model ref における provider prefix になります。 +- バックエンド `config` は、`agents.defaults.cliBackends.` と同じ shape を使います。 +- ユーザー設定が引き続き優先されます。OpenClaw は CLI 実行前に `agents.defaults.cliBackends.` を + plugin デフォルトの上にマージします。 +- マージ後に互換性のための書き換えが必要なバックエンドでは、 + `normalizeConfig` を使用してください + （たとえば古い flag shape の正規化など）。 ### 排他的スロット -| メソッド | 登録するもの | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | コンテキストエンジン（一度に1つだけアクティブ）。`assemble()`コールバックは`availableTools`と`citationsMode`を受け取るため、エンジンはそれに応じてプロンプト追加を調整できます。 | -| `api.registerMemoryCapability(capability)` | 統合メモリケイパビリティ | -| `api.registerMemoryPromptSection(builder)` | メモリプロンプトセクションビルダー | -| `api.registerMemoryFlushPlan(resolver)` | メモリflush planリゾルバー | -| `api.registerMemoryRuntime(runtime)` | メモリランタイムアダプター | +| メソッド | 登録するもの | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | コンテキストエンジン（一度に 1 つだけアクティブ）。`assemble()` コールバックは `availableTools` と `citationsMode` を受け取り、エンジンが prompt 追加内容を調整できるようにします。 | +| `api.registerMemoryCapability(capability)` | 統一メモリ capability | +| `api.registerMemoryPromptSection(builder)` | メモリ prompt セクション builder | +| `api.registerMemoryFlushPlan(resolver)` | メモリ flush plan resolver | +| `api.registerMemoryRuntime(runtime)` | メモリ runtime adapter | -### メモリ埋め込みアダプター +### メモリ embedding adapter -| メソッド | 登録するもの | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | アクティブなプラグイン向けのメモリ埋め込みアダプター | +| メソッド | 登録するもの | +| ---------------------------------------------- | ------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | アクティブな plugin 用のメモリ embedding adapter | -- `registerMemoryCapability`は、推奨される排他的メモリプラグインAPIです。 -- `registerMemoryCapability`は`publicArtifacts.listArtifacts(...)`も公開できるため、 - コンパニオンプラグインは特定のメモリプラグインの非公開レイアウトに入り込むのではなく、 - `openclaw/plugin-sdk/memory-host-core`経由でエクスポートされたメモリアーティファクトを利用できます。 +- `registerMemoryCapability` は、推奨される排他的 memory-plugin API です。 +- `registerMemoryCapability` は `publicArtifacts.listArtifacts(...)` も公開でき、 + companion plugins が特定の + memory plugin の private layout に入り込むのではなく、 + `openclaw/plugin-sdk/memory-host-core` を通じてエクスポートされた memory artifacts を利用できるようにします。 - `registerMemoryPromptSection`、`registerMemoryFlushPlan`、および - `registerMemoryRuntime`は、古い互換性のある排他的メモリプラグインAPIです。 -- `registerMemoryEmbeddingProvider`を使うと、アクティブなメモリプラグインは1つ以上の - 埋め込みアダプターID（たとえば`openai`、`gemini`、またはカスタムの - プラグイン定義ID）を登録できます。 -- `agents.defaults.memorySearch.provider`や - `agents.defaults.memorySearch.fallback`のようなユーザー設定は、 - それらの登録済みアダプターIDに対して解決されます。 + `registerMemoryRuntime` は、レガシー互換の排他的 memory-plugin API です。 +- `registerMemoryEmbeddingProvider` により、アクティブな memory plugin は + 1 つ以上の embedding adapter id（例: `openai`、`gemini`、または plugin 定義のカスタム id）を登録できます。 +- `agents.defaults.memorySearch.provider` や + `agents.defaults.memorySearch.fallback` のようなユーザー設定は、 + それらの登録済み adapter id に対して解決されます。 ### イベントとライフサイクル -| メソッド | 役割 | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | 型付きライフサイクルhook | -| `api.onConversationBindingResolved(handler)` | 会話バインディングコールバック | +| メソッド | 役割 | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | 型付きライフサイクル hook | +| `api.onConversationBindingResolved(handler)` | 会話バインディング callback | -### Hook判定セマンティクス +### Hook 判定セマンティクス -- `before_tool_call`: `{ block: true }`を返すと終端です。いずれかのハンドラーがこれを設定すると、より低優先度のハンドラーはスキップされます。 -- `before_tool_call`: `{ block: false }`を返しても判定なしとして扱われます（`block`を省略した場合と同じ）であり、上書きではありません。 -- `before_install`: `{ block: true }`を返すと終端です。いずれかのハンドラーがこれを設定すると、より低優先度のハンドラーはスキップされます。 -- `before_install`: `{ block: false }`を返しても判定なしとして扱われます（`block`を省略した場合と同じ）であり、上書きではありません。 -- `reply_dispatch`: `{ handled: true, ... }`を返すと終端です。いずれかのハンドラーがdispatchを引き受けると、より低優先度のハンドラーとデフォルトのモデルdispatchパスはスキップされます。 -- `message_sending`: `{ cancel: true }`を返すと終端です。いずれかのハンドラーがこれを設定すると、より低優先度のハンドラーはスキップされます。 -- `message_sending`: `{ cancel: false }`を返しても判定なしとして扱われます（`cancel`を省略した場合と同じ）であり、上書きではありません。 +- `before_tool_call`: `{ block: true }` を返すと終端です。いずれかの handler がこれを設定すると、優先度の低い handler はスキップされます。 +- `before_tool_call`: `{ block: false }` を返しても判定なしとして扱われます（`block` を省略した場合と同じ）であり、上書きではありません。 +- `before_install`: `{ block: true }` を返すと終端です。いずれかの handler がこれを設定すると、優先度の低い handler はスキップされます。 +- `before_install`: `{ block: false }` を返しても判定なしとして扱われます（`block` を省略した場合と同じ）であり、上書きではありません。 +- `reply_dispatch`: `{ handled: true, ... }` を返すと終端です。いずれかの handler が dispatch を引き受けると、優先度の低い handler とデフォルトの model dispatch パスはスキップされます。 +- `message_sending`: `{ cancel: true }` を返すと終端です。いずれかの handler がこれを設定すると、優先度の低い handler はスキップされます。 +- `message_sending`: `{ cancel: false }` を返しても判定なしとして扱われます（`cancel` を省略した場合と同じ）であり、上書きではありません。 -### APIオブジェクトのフィールド +### API オブジェクトのフィールド -| フィールド | 型 | 説明 | +| フィールド | 型 | 説明 | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | プラグインID | -| `api.name` | `string` | 表示名 | -| `api.version` | `string?` | プラグインバージョン（任意） | -| `api.description` | `string?` | プラグイン説明（任意） | -| `api.source` | `string` | プラグインソースパス | -| `api.rootDir` | `string?` | プラグインルートディレクトリ（任意） | -| `api.config` | `OpenClawConfig` | 現在の設定スナップショット（利用可能な場合はアクティブなインメモリランタイムスナップショット） | -| `api.pluginConfig` | `Record` | `plugins.entries..config`からのプラグイン固有設定 | -| `api.runtime` | `PluginRuntime` | [ランタイムヘルパー](/ja-JP/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | スコープ付きlogger（`debug`, `info`, `warn`, `error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 現在の読み込みモード。`"setup-runtime"`は、完全なエントリ起動 / セットアップ前の軽量ウィンドウです | -| `api.resolvePath(input)` | `(string) => string` | プラグインルート相対でパスを解決する | +| `api.id` | `string` | Plugin id | +| `api.name` | `string` | 表示名 | +| `api.version` | `string?` | Plugin version（任意） | +| `api.description` | `string?` | Plugin の説明（任意） | +| `api.source` | `string` | Plugin のソースパス | +| `api.rootDir` | `string?` | Plugin のルートディレクトリ（任意） | +| `api.config` | `OpenClawConfig` | 現在の config スナップショット（利用可能な場合は、アクティブなインメモリ runtime スナップショット） | +| `api.pluginConfig` | `Record` | `plugins.entries..config` からの plugin 固有 config | +| `api.runtime` | `PluginRuntime` | [Runtime helpers](/ja-JP/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | スコープ付き logger（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 現在の load mode。`"setup-runtime"` は軽量な full-entry 起動前/セットアップ用ウィンドウです | +| `api.resolvePath(input)` | `(string) => string` | plugin root を基準にパスを解決する | ## 内部モジュール規約 -プラグイン内部では、内部インポートにローカルバレルファイルを使用してください。 +plugin 内では、内部インポートにローカル barrel ファイルを使用してください。 ``` my-plugin/ - api.ts # 外部利用者向け公開エクスポート - runtime-api.ts # 内部専用ランタイムエクスポート - index.ts # プラグインエントリポイント - setup-entry.ts # 軽量セットアップ専用エントリ（任意） + api.ts # 外部利用者向けの公開エクスポート + runtime-api.ts # 内部専用の runtime エクスポート + index.ts # Plugin entry point + setup-entry.ts # 軽量な setup 専用 entry（任意） ``` - 本番コードから、自分自身のプラグインを`openclaw/plugin-sdk/` - 経由でインポートしてはいけません。内部インポートは`./api.ts`または - `./runtime-api.ts`経由にしてください。SDKパスは外部契約専用です。 + 本番コード内で自分自身の plugin を `openclaw/plugin-sdk/` + 経由でインポートしてはいけません。内部インポートは `./api.ts` または + `./runtime-api.ts` を通してください。SDK パスは外部コントラクト専用です。 -ファサード読み込みのバンドルプラグイン公開サーフェス（`api.ts`、`runtime-api.ts`、 -`index.ts`、`setup-entry.ts`、および類似の公開エントリファイル）は、現在、 -OpenClawがすでに実行中であればアクティブなランタイム設定スナップショットを優先します。 -まだランタイムスナップショットが存在しない場合は、ディスク上の解決済み設定ファイルへフォールバックします。 +Facade-loaded bundled plugin の公開 surface（`api.ts`、`runtime-api.ts`、 +`index.ts`、`setup-entry.ts`、および同様の公開 entry ファイル）は、OpenClaw がすでに動作中であれば +アクティブな runtime config スナップショットを優先して使用するようになりました。 +まだ runtime スナップショットが存在しない場合は、ディスク上で解決された config file にフォールバックします。 -プロバイダープラグインは、ヘルパーが意図的にプロバイダー固有で、 -まだ汎用SDKサブパスに属さない場合に、狭いプラグインローカル契約バレルを公開することもできます。 -現在のバンドル例: Anthropicプロバイダーは、Anthropicのbeta-headerと -`service_tier`ロジックを汎用`plugin-sdk/*`契約へ昇格させる代わりに、 -Claude streamヘルパーを独自の公開`api.ts` / `contract-api.ts`サーフェスに保持しています。 +Provider plugins は、helper が意図的に provider 固有であり、まだ汎用 SDK +サブパスに属さない場合、狭い plugin ローカル contract barrel を公開することもできます。現在の bundled の例: +Anthropic provider は、Anthropic beta-header や `service_tier` ロジックを +汎用 `plugin-sdk/*` コントラクトに昇格させる代わりに、自身の公開 `api.ts` / `contract-api.ts` seam に Claude +stream helper を保持しています。 -現在のその他のバンドル例: +その他の現在の bundled の例: -- `@openclaw/openai-provider`: `api.ts`はプロバイダービルダー、 - default-modelヘルパー、およびリアルタイムプロバイダービルダーをエクスポートします -- `@openclaw/openrouter-provider`: `api.ts`はプロバイダービルダーに加えて - オンボーディング / 設定ヘルパーをエクスポートします +- `@openclaw/openai-provider`: `api.ts` は provider builder、 + default-model helper、および realtime provider builder をエクスポートします +- `@openclaw/openrouter-provider`: `api.ts` は provider builder に加えて + onboarding/config helper をエクスポートします - 拡張機能の本番コードも、`openclaw/plugin-sdk/`の - インポートを避けるべきです。ヘルパーが本当に共有されるべきものであれば、 - 2つのプラグインを結合してしまうのではなく、`openclaw/plugin-sdk/speech`、 - `.../provider-model-shared`、または別の - ケイパビリティ指向サーフェスのような中立的なSDKサブパスへ昇格してください。 + Extension の本番コードでも、`openclaw/plugin-sdk/` + のインポートは避けるべきです。helper が本当に共有対象であるなら、2 つの plugin を結合してしまう代わりに、 + `openclaw/plugin-sdk/speech`、`.../provider-model-shared`、または別の + capability 指向 surface のような中立な SDK サブパスに昇格させてください。 ## 関連 -- [Entry Points](/ja-JP/plugins/sdk-entrypoints) — `definePluginEntry`と`defineChannelPluginEntry`のオプション -- [Runtime Helpers](/ja-JP/plugins/sdk-runtime) — `api.runtime`名前空間の完全リファレンス -- [Setup and Config](/ja-JP/plugins/sdk-setup) — パッケージング、マニフェスト、設定スキーマ -- [Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティとlintルール -- [SDK Migration](/ja-JP/plugins/sdk-migration) — 非推奨サーフェスからの移行 -- [Plugin Internals](/ja-JP/plugins/architecture) — 詳細なアーキテクチャとケイパビリティモデル +- [Entry Points](/ja-JP/plugins/sdk-entrypoints) — `definePluginEntry` と `defineChannelPluginEntry` のオプション +- [Runtime Helpers](/ja-JP/plugins/sdk-runtime) — `api.runtime` 名前空間の完全なリファレンス +- [Setup and Config](/ja-JP/plugins/sdk-setup) — パッケージ化、マニフェスト、config schema +- [Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティと lint ルール +- [SDK Migration](/ja-JP/plugins/sdk-migration) — 非推奨 surface からの移行 +- [Plugin Internals](/ja-JP/plugins/architecture) — 詳細なアーキテクチャと capability モデル diff --git a/docs/ja-JP/plugins/sdk-provider-plugins.md b/docs/ja-JP/plugins/sdk-provider-plugins.md index ae7b1b9b2..5e9b86296 100644 --- a/docs/ja-JP/plugins/sdk-provider-plugins.md +++ b/docs/ja-JP/plugins/sdk-provider-plugins.md @@ -1,36 +1,45 @@ --- read_when: - - 新しいモデルprovider pluginを構築している - - OpenClawにOpenAI互換プロキシまたはカスタムLLMを追加したい - - provider認証、catalog、およびruntime hookを理解する必要がある + - 新しいモデル provider plugin を構築する場合 + - OpenAI 互換プロキシまたはカスタム LLM を OpenClaw に追加したい場合 + - provider auth、catalog、およびランタイムフックを理解する必要があります sidebarTitle: Provider Plugins -summary: OpenClaw向けモデルprovider pluginを構築するためのステップバイステップガイド -title: Provider Pluginsの構築 +summary: OpenClaw 向けモデル provider plugin の構築手順ガイド +title: provider plugin の構築 x-i18n: - generated_at: "2026-04-09T01:31:28Z" + generated_at: "2026-04-11T02:46:57Z" model: gpt-5.4 provider: openai - source_hash: 38d9af522dc19e49c81203a83a4096f01c2398b1df771c848a30ad98f251e9e1 + source_hash: 06d7c5da6556dc3d9673a31142ff65eb67ddc97fc0c1a6f4826a2c7693ecd5e3 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- -# Provider Pluginsの構築 +# provider plugin の構築 -このガイドでは、OpenClawにモデルprovider -（LLM）を追加するprovider pluginの構築手順を説明します。最後には、モデルcatalog、APIキー認証、動的モデル解決を備えたproviderが完成します。 +このガイドでは、OpenClaw にモデル provider +（LLM）を追加する provider plugin の構築手順を説明します。最終的には、モデル catalog、 +API キー認証、および動的モデル解決を備えた provider が完成します。 - まだOpenClawプラグインを1つも作成したことがない場合は、まず - 基本的なパッケージ構造とマニフェスト設定について - [はじめに](/ja-JP/plugins/building-plugins)を読んでください。 + まだ OpenClaw plugin を一度も作成したことがない場合は、まず + 基本的なパッケージ構造と manifest 設定について + [はじめに](/ja-JP/plugins/building-plugins) を読んでください。 -## 手順 + + Provider plugin は OpenClaw の通常の推論ループにモデルを追加します。モデルを、 + スレッド、compaction、またはツールイベントを管理するネイティブなエージェントデーモン経由で実行する必要がある場合は、 + デーモンのプロトコル詳細を core に入れるのではなく、 + provider を [agent harness](/ja-JP/plugins/sdk-agent-harness) + と組み合わせてください。 + + +## ウォークスルー - + ```json package.json { @@ -88,13 +97,17 @@ x-i18n: ``` - マニフェストでは`providerAuthEnvVars`を宣言することで、OpenClawが - プラグインruntimeを読み込まずに認証情報を検出できるようになります。providerの派生形が別のprovider idの認証を再利用する場合は、`providerAuthAliases`を追加してください。`modelSupport`は任意で、runtime hookが存在する前でも、`acme-large`のような短縮model idからOpenClawがprovider pluginを自動読み込みできるようにします。providerをClawHubで公開する場合、`package.json`内のそれらの`openclaw.compat`および`openclaw.build`フィールドは必須です。 + manifest は `providerAuthEnvVars` を宣言することで、OpenClaw が + plugin ランタイムを読み込まずに認証情報を検出できるようにします。ある provider バリアントで別の provider id の auth を再利用させたい場合は、`providerAuthAliases` + を追加してください。`modelSupport` + は任意で、ランタイムフックが存在する前でも、`acme-large` のような短縮モデル id から OpenClaw が provider plugin を自動読み込みできるようにします。provider を + ClawHub で公開する場合、これらの `openclaw.compat` および `openclaw.build` フィールドは + `package.json` 内で必須です。 - - 最小限のproviderには、`id`、`label`、`auth`、および`catalog`が必要です。 + + 最小限の provider に必要なのは、`id`、`label`、`auth`、および `catalog` です: ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -165,12 +178,35 @@ x-i18n: }); ``` - これで動作するproviderになります。ユーザーは - `openclaw onboard --acme-ai-api-key ` を実行し、 - モデルとして`acme-ai/acme-large`を選択できるようになります。 + これで動作する provider になります。ユーザーは + `openclaw onboard --acme-ai-api-key ` を実行して、 + モデルとして `acme-ai/acme-large` を選択できるようになります。 - APIキー認証を持つ1つのテキストproviderと、catalogベースの単一runtimeだけを登録する同梱providerでは、より狭い - `defineSingleProviderPluginEntry(...)`ヘルパーを使うのが適しています。 + アップストリーム provider が OpenClaw と異なる制御トークンを使う場合は、 + ストリーム経路を置き換えるのではなく、小さな双方向テキスト変換を追加してください: + + ```typescript + api.registerTextTransforms({ + input: [ + { from: /red basket/g, to: "blue basket" }, + { from: /paper ticket/g, to: "digital ticket" }, + { from: /left shelf/g, to: "right shelf" }, + ], + output: [ + { from: /blue basket/g, to: "red basket" }, + { from: /digital ticket/g, to: "paper ticket" }, + { from: /right shelf/g, to: "left shelf" }, + ], + }); + ``` + + `input` は、転送前に最終システムプロンプトとテキストメッセージ内容を書き換えます。 + `output` は、assistant テキスト差分と最終テキストを、OpenClaw が自身の + 制御マーカーやチャネル配信を解析する前に書き換えます。 + + API キー認証と単一の catalog ベースランタイムを持つ + 1 つのテキスト provider だけを登録するバンドル provider では、より狭い + `defineSingleProviderPluginEntry(...)` ヘルパーを優先してください: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -205,26 +241,28 @@ x-i18n: }); ``` - 認証フローで、オンボーディング中に`models.providers.*`、エイリアス、およびagentのデフォルトモデルも更新する必要がある場合は、 - `openclaw/plugin-sdk/provider-onboard`のpreset helperを使ってください。最も狭いhelperは - `createDefaultModelPresetAppliers(...)`、 + auth フローで、オンボーディング中に `models.providers.*`、aliases、 + およびエージェントのデフォルトモデルも更新する必要がある場合は、 + `openclaw/plugin-sdk/provider-onboard` の preset ヘルパーを使用してください。最も狭い + ヘルパーは `createDefaultModelPresetAppliers(...)`、 `createDefaultModelsPresetAppliers(...)`、および - `createModelCatalogPresetAppliers(...)`です。 + `createModelCatalogPresetAppliers(...)` です。 - providerのネイティブendpointが通常の - `openai-completions` transport上でストリーミングusage blockをサポートしている場合は、provider-idのチェックをハードコードするのではなく、 - `openclaw/plugin-sdk/provider-catalog-shared`の共有catalog helperを優先して使ってください。`supportsNativeStreamingUsageCompat(...)`と - `applyProviderNativeStreamingUsageCompat(...)`はendpoint capability mapからサポートを検出するため、カスタムprovider idを使っているpluginでも、ネイティブのMoonshot/DashScope系endpointをオプトインできます。 + provider ネイティブエンドポイントが、通常の + `openai-completions` 転送でストリーミング usage ブロックをサポートしている場合は、provider-id チェックをハードコードするのではなく + `openclaw/plugin-sdk/provider-catalog-shared` の共通 catalog ヘルパーを優先してください。 + `supportsNativeStreamingUsageCompat(...)` と + `applyProviderNativeStreamingUsageCompat(...)` は、エンドポイント capability map からサポートを検出するため、custom provider id を使う plugin でも、ネイティブ Moonshot/DashScope 形式エンドポイントをオプトインさせられます。 - providerが任意のmodel ID（プロキシやrouterのようなもの）を受け付ける場合は、 - `resolveDynamicModel`を追加してください。 + provider が任意のモデル ID を受け付ける場合（プロキシやルーターのようなケース）は、 + `resolveDynamicModel` を追加します: ```typescript api.registerProvider({ - // ... 上記の id, label, auth, catalog + // ... id, label, auth, catalog from above resolveDynamicModel: (ctx) => ({ id: ctx.modelId, @@ -242,15 +280,16 @@ x-i18n: ``` 解決にネットワーク呼び出しが必要な場合は、非同期ウォームアップ用に - `prepareDynamicModel`を使ってください。完了後に - `resolveDynamicModel`が再び実行されます。 + `prepareDynamicModel` を使ってください — 完了後に `resolveDynamicModel` が再度実行されます。 - - ほとんどのproviderでは`catalog` + `resolveDynamicModel`だけで十分です。providerに必要な場合にのみ、段階的にhookを追加してください。 + + ほとんどの provider では `catalog` + `resolveDynamicModel` だけで十分です。provider に必要になったら、 + フックを段階的に追加してください。 - 共有helper builderが現在、最も一般的なreplay/tool-compatファミリーをカバーしているため、通常pluginは各hookを1つずつ手作業で配線する必要はありません。 + 共通ヘルパービルダーは、現在最も一般的な replay/tool-compat + ファミリーをカバーしているため、plugin では通常、各フックを 1 つずつ手作業で接続する必要はありません: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -270,61 +309,64 @@ x-i18n: }); ``` - 現在利用可能なreplayファミリー: + 現在利用可能な replay ファミリー: - | Family | 配線される内容 | + | ファミリー | 接続される内容 | | --- | --- | - | `openai-compatible` | OpenAI互換transport向けの共有OpenAIスタイルreplayポリシー。tool-call-idのサニタイズ、assistant-first順序修正、transportが必要とする場合の汎用Geminiターン検証を含みます | - | `anthropic-by-model` | `modelId`で選択されるClaude対応replayポリシー。Anthropic message transportでは、解決されたモデルが実際にClaude idである場合にのみ、Claude固有のthinking blockクリーンアップを適用します | - | `google-gemini` | ネイティブGemini replayポリシーに加え、bootstrap replayサニタイズとタグ付きreasoning-outputモード | - | `passthrough-gemini` | OpenAI互換proxy transport経由で動作するGeminiモデル向けのGemini thought-signatureサニタイズ。ネイティブGemini replay検証やbootstrap書き換えは有効にしません | - | `hybrid-anthropic-openai` | 1つのplugin内でAnthropic message系とOpenAI互換model surfaceが混在するprovider向けハイブリッドポリシー。任意のClaude専用thinking block削除はAnthropic側に限定されたままです | + | `openai-compatible` | OpenAI 互換転送向けの共有 OpenAI スタイル replay ポリシー。tool-call-id のサニタイズ、assistant-first 順序の修正、およびその転送で必要な場合の汎用 Gemini ターン検証を含みます | + | `anthropic-by-model` | `modelId` によって選ばれる Claude 対応 replay ポリシー。Anthropic-message 転送では、解決されたモデルが実際に Claude id の場合にのみ Claude 固有の thinking-block クリーンアップが適用されます | + | `google-gemini` | ネイティブ Gemini replay ポリシーに加え、bootstrap replay サニタイズとタグ付き reasoning-output モード | + | `passthrough-gemini` | OpenAI 互換プロキシ転送上で動作する Gemini モデル向けの Gemini thought-signature サニタイズ。ネイティブ Gemini replay 検証や bootstrap 書き換えは有効にしません | + | `hybrid-anthropic-openai` | 1 つの plugin 内で Anthropic-message と OpenAI 互換のモデルサーフェスを混在させる provider 向けのハイブリッドポリシー。任意の Claude 専用 thinking-block 除去は Anthropic 側に限定されます | - 実際の同梱例: + 実際のバンドル例: - - `google` および `google-gemini-cli`: `google-gemini` + - `google` と `google-gemini-cli`: `google-gemini` - `openrouter`、`kilocode`、`opencode`、および `opencode-go`: `passthrough-gemini` - - `amazon-bedrock` および `anthropic-vertex`: `anthropic-by-model` + - `amazon-bedrock` と `anthropic-vertex`: `anthropic-by-model` - `minimax`: `hybrid-anthropic-openai` - `moonshot`、`ollama`、`xai`、および `zai`: `openai-compatible` - 現在利用可能なstreamファミリー: + 現在利用可能なストリームファミリー: - | Family | 配線される内容 | + | ファミリー | 接続される内容 | | --- | --- | - | `google-thinking` | 共有streamパス上でのGemini thinkingペイロード正規化 | - | `kilocode-thinking` | 共有proxy streamパス上でのKilo reasoningラッパー。`kilo/auto`および未対応proxy reasoning idでは注入thinkingをスキップします | - | `moonshot-thinking` | config + `/think`レベルからのMoonshotバイナリnative-thinkingペイロードマッピング | - | `minimax-fast-mode` | 共有streamパス上でのMiniMax fast-modeモデル書き換え | - | `openai-responses-defaults` | 共有のネイティブOpenAI/Codex Responsesラッパー: attribution header、`/fast`/`serviceTier`、text verbosity、ネイティブCodex web search、reasoning-compatペイロード整形、およびResponsesコンテキスト管理 | - | `openrouter-thinking` | proxy route向けOpenRouter reasoningラッパー。未対応モデルや`auto`のスキップは中央で処理されます | - | `tool-stream-default-on` | Z.AIのように明示的に無効化されない限りtool streamingを有効にしたいprovider向けのデフォルト有効`tool_stream`ラッパー | + | `google-thinking` | 共有ストリーム経路上での Gemini thinking ペイロード正規化 | + | `kilocode-thinking` | 共有プロキシストリーム経路上での Kilo reasoning ラッパー。`kilo/auto` と未対応のプロキシ reasoning id では注入された thinking をスキップ | + | `moonshot-thinking` | config + `/think` レベルからの Moonshot バイナリ native-thinking ペイロードマッピング | + | `minimax-fast-mode` | 共有ストリーム経路上での MiniMax fast-mode モデル書き換え | + | `openai-responses-defaults` | 共有のネイティブ OpenAI/Codex Responses ラッパー: attribution headers、`/fast`/`serviceTier`、text verbosity、ネイティブ Codex web search、reasoning-compat ペイロード整形、および Responses コンテキスト管理 | + | `openrouter-thinking` | プロキシ経路向けの OpenRouter reasoning ラッパー。未対応モデル/`auto` スキップは中央処理されます | + | `tool-stream-default-on` | Z.AI のような provider 向けのデフォルト有効 `tool_stream` ラッパー。明示的に無効化されない限りツールストリーミングを使用 | - 実際の同梱例: + 実際のバンドル例: - - `google` および `google-gemini-cli`: `google-thinking` + - `google` と `google-gemini-cli`: `google-thinking` - `kilocode`: `kilocode-thinking` - `moonshot`: `moonshot-thinking` - - `minimax` および `minimax-portal`: `minimax-fast-mode` - - `openai` および `openai-codex`: `openai-responses-defaults` + - `minimax` と `minimax-portal`: `minimax-fast-mode` + - `openai` と `openai-codex`: `openai-responses-defaults` - `openrouter`: `openrouter-thinking` - `zai`: `tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared`は、replayファミリーenumと、それらのファミリーの構築に使われる共有helperもexportします。一般的な公開exportには次が含まれます。 + `openclaw/plugin-sdk/provider-model-shared` は、replay-family + enum と、それらのファミリーの土台となる共有ヘルパーもエクスポートします。一般的な公開エクスポートには次が含まれます: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - `buildOpenAICompatibleReplayPolicy(...)`、 `buildAnthropicReplayPolicyForModel(...)`、 `buildGoogleGeminiReplayPolicy(...)`、および - `buildHybridAnthropicOrOpenAIReplayPolicy(...)`のような共有replay builder + `buildHybridAnthropicOrOpenAIReplayPolicy(...)` のような共有 replay ビルダー - `sanitizeGoogleGeminiReplayHistory(...)` - および `resolveTaggedReasoningOutputMode()`のようなGemini replay helper + や `resolveTaggedReasoningOutputMode()` のような Gemini replay ヘルパー - `resolveProviderEndpoint(...)`、 `normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)`、および - `normalizeNativeXaiModelId(...)`のようなendpoint/model helper + `normalizeNativeXaiModelId(...)` のような endpoint/model ヘルパー - `openclaw/plugin-sdk/provider-stream`は、ファミリーbuilderと、それらのファミリーが再利用する公開wrapper helperの両方を公開します。一般的な公開exportには次が含まれます。 + `openclaw/plugin-sdk/provider-stream` は、family builder と、 + それらのファミリーが再利用する公開ラッパーヘルパーの両方を公開します。一般的な公開エクスポート + には次が含まれます: - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` @@ -333,41 +375,53 @@ x-i18n: `createOpenAIFastModeWrapper(...)`、 `createOpenAIServiceTierWrapper(...)`、 `createOpenAIResponsesContextManagementWrapper(...)`、および - `createCodexNativeWebSearchWrapper(...)`のような共有OpenAI/Codex wrapper + `createCodexNativeWebSearchWrapper(...)` のような共有 OpenAI/Codex ラッパー - `createOpenRouterWrapper(...)`、 - `createToolStreamWrapper(...)`、および `createMinimaxFastModeWrapper(...)`のような共有proxy/provider wrapper + `createToolStreamWrapper(...)`、および `createMinimaxFastModeWrapper(...)` のような共有 proxy/provider ラッパー - 一部のstream helperは意図的にproviderローカルのままです。現在の同梱例: - `@openclaw/anthropic-provider`は、その公開`api.ts` / - `contract-api.ts` seamから + 一部のストリームヘルパーは意図的に provider ローカルのままになっています。現在のバンドル + 例: `@openclaw/anthropic-provider` は `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`、および下位レベルのAnthropic wrapper builderをexportします。これらのhelperは、Claude OAuth beta処理と`context1m` gatingもエンコードしているため、Anthropic固有のままになっています。 + `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`、および + より低レベルの Anthropic ラッパービルダーを公開 `api.ts` / + `contract-api.ts` シームからエクスポートします。これらのヘルパーが Anthropic 固有のままなのは、 + Claude OAuth beta 処理と `context1m` ゲーティングもエンコードしているためです。 - 他の同梱providerも、動作をファミリー間できれいに共有できない場合、transport固有のwrapperをローカルに保持しています。現在の例: 同梱xAI pluginは、`wrapStreamFn`内でネイティブxAI Responses整形を保持しており、`/fast`エイリアス書き換え、デフォルトの`tool_stream`、未対応strict-toolクリーンアップ、およびxAI固有のreasoningペイロード削除を含みます。 + 他のバンドル provider も、動作がファミリー間でうまく共有できない場合は、 + 転送固有ラッパーをローカルに保持します。現在の例: バンドルされた + xAI plugin は、ネイティブ xAI Responses 整形を自身の + `wrapStreamFn` 内に保持しています。これには `/fast` エイリアス書き換え、デフォルトの `tool_stream`、 + 未対応 strict-tool クリーンアップ、および xAI 固有の reasoning-payload + 除去が含まれます。 - `openclaw/plugin-sdk/provider-tools`は現在、1つの共有tool-schemaファミリーと共有schema/compat helperを公開しています。 + `openclaw/plugin-sdk/provider-tools` は現在、1つの共有 + tool-schema ファミリーと共有 schema/compat ヘルパーを公開しています: - - `ProviderToolCompatFamily`は、現在の共有ファミリー一覧を文書化しています。 - - `buildProviderToolCompatFamilyHooks("gemini")`は、Gemini安全なtool schemaが必要なprovider向けにGemini schemaクリーンアップ + 診断を配線します。 - - `normalizeGeminiToolSchemas(...)`と`inspectGeminiToolSchemas(...)`は、その基盤となる公開Gemini schema helperです。 - - `resolveXaiModelCompatPatch()`は、同梱xAI compat patchを返します: - `toolSchemaProfile: "xai"`、未対応schema keyword、ネイティブ - `web_search`サポート、およびHTMLエンティティ化されたtool-call引数のデコードです。 - - `applyXaiModelCompat(model)`は、runnerに届く前の解決済みmodelに同じxAI compat patchを適用します。 + - `ProviderToolCompatFamily` は、現在の共有ファミリー一覧を文書化します。 + - `buildProviderToolCompatFamilyHooks("gemini")` は、Gemini-safe なツールスキーマが必要な provider 向けに Gemini スキーマ + クリーンアップ + diagnostics を接続します。 + - `normalizeGeminiToolSchemas(...)` と `inspectGeminiToolSchemas(...)` + は、その土台となる公開 Gemini スキーマヘルパーです。 + - `resolveXaiModelCompatPatch()` は、バンドルされた xAI compat patch を返します: + `toolSchemaProfile: "xai"`、未対応スキーマキーワード、ネイティブ + `web_search` サポート、および HTML entity のツール呼び出し引数デコードです。 + - `applyXaiModelCompat(model)` は、同じ xAI compat patch を + 解決済みモデルに適用してから runner に渡します。 - 実際の同梱例: xAI pluginは`normalizeResolvedModel`と - `contributeResolvedModelCompat`を使い、そのcompatメタデータをコアにxAIルールをハードコードするのではなく、provider所有のままにしています。 + 実際のバンドル例: xAI plugin は `normalizeResolvedModel` と + `contributeResolvedModelCompat` を使い、その compat メタデータを + core に xAI ルールをハードコードするのではなく provider 側で管理しています。 - 同じpackage rootパターンは他の同梱providerも支えています。 + 同じ package-root パターンは、他のバンドル provider でも使われています: - - `@openclaw/openai-provider`: `api.ts`はprovider builder、 - default-model helper、およびrealtime provider builderをexportします - - `@openclaw/openrouter-provider`: `api.ts`はprovider builder - とオンボーディング/config helperをexportします + - `@openclaw/openai-provider`: `api.ts` は provider builder、 + default-model ヘルパー、および realtime provider builder をエクスポート + - `@openclaw/openrouter-provider`: `api.ts` は provider builder + に加えて onboarding/config ヘルパーをエクスポート - 各推論呼び出しの前にトークン交換が必要なproviderの場合: + 各推論呼び出しの前にトークン交換が必要な provider の場合: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -381,10 +435,10 @@ x-i18n: ``` - カスタムリクエストヘッダーやボディ変更が必要なproviderの場合: + カスタムリクエストヘッダーやボディ変更が必要な provider の場合: ```typescript - // wrapStreamFn は ctx.streamFn から派生した StreamFn を返します + // wrapStreamFn returns a StreamFn derived from ctx.streamFn wrapStreamFn: (ctx) => { if (!ctx.streamFn) return undefined; const inner = ctx.streamFn; @@ -398,8 +452,9 @@ x-i18n: }, ``` - - 汎用HTTPまたはWebSocket transport上で、ネイティブのリクエスト/セッションヘッダーまたはメタデータが必要なproviderの場合: + + 汎用 HTTP または WebSocket 転送上で、ネイティブの + リクエスト/セッションヘッダーやメタデータが必要な provider の場合: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -419,8 +474,8 @@ x-i18n: }), ``` - - 使用量/課金データを公開するproviderの場合: + + 使用量/請求データを公開する provider の場合: ```typescript resolveUsageAuth: async (ctx) => { @@ -434,77 +489,85 @@ x-i18n: - - OpenClawはこの順序でhookを呼び出します。ほとんどのproviderが使うのは2〜3個だけです。 + + OpenClaw は次の順序でフックを呼び出します。ほとんどの provider では 2〜3 個しか使いません: - | # | Hook | 使う場面 | + | # | フック | 使用するタイミング | | --- | --- | --- | - | 1 | `catalog` | モデルcatalogまたはbase URLのデフォルト | - | 2 | `applyConfigDefaults` | config materialization中のprovider所有グローバルデフォルト | - | 3 | `normalizeModelId` | lookup前の旧/preview model-idエイリアスクリーンアップ | - | 4 | `normalizeTransport` | 汎用モデル組み立て前のproviderファミリー`api` / `baseUrl`クリーンアップ | - | 5 | `normalizeConfig` | `models.providers.` configの正規化 | - | 6 | `applyNativeStreamingUsageCompat` | config provider向けネイティブstreaming-usage compat書き換え | - | 7 | `resolveConfigApiKey` | provider所有のenv-marker認証解決 | - | 8 | `resolveSyntheticAuth` | ローカル/セルフホストまたはconfigベースのsynthetic auth | - | 9 | `shouldDeferSyntheticProfileAuth` | synthetic保存profileプレースホルダーをenv/config authより後ろに下げる | - | 10 | `resolveDynamicModel` | 任意のupstream model IDを受け付ける | + | 1 | `catalog` | モデル catalog または base URL のデフォルト | + | 2 | `applyConfigDefaults` | config マテリアライズ時の provider 所有グローバルデフォルト | + | 3 | `normalizeModelId` | 参照前の legacy/preview model-id エイリアスクリーンアップ | + | 4 | `normalizeTransport` | 汎用モデル組み立て前の provider-family `api` / `baseUrl` クリーンアップ | + | 5 | `normalizeConfig` | `models.providers.` config を正規化 | + | 6 | `applyNativeStreamingUsageCompat` | config provider 向けネイティブ streaming-usage compat 書き換え | + | 7 | `resolveConfigApiKey` | provider 所有の env-marker auth 解決 | + | 8 | `resolveSyntheticAuth` | local/self-hosted または config ベースの synthetic auth | + | 9 | `shouldDeferSyntheticProfileAuth` | synthetic な保存済み profile プレースホルダーを env/config auth より後ろに下げる | + | 10 | `resolveDynamicModel` | 任意のアップストリームモデル ID を受け入れる | | 11 | `prepareDynamicModel` | 解決前の非同期メタデータ取得 | - | 12 | `normalizeResolvedModel` | runner前のtransport書き換え | + | 12 | `normalizeResolvedModel` | runner 前の転送書き換え | - Runtime fallbackに関する注意: + ランタイムフォールバックに関する注意: - - `normalizeConfig`は、最初に一致したproviderを確認し、その後、実際にconfigを変更するものが見つかるまで、他のhook対応provider pluginを確認します。 - どのprovider hookもサポート対象のGoogleファミリーconfigエントリーを書き換えなかった場合、同梱Google config normalizerが引き続き適用されます。 - - `resolveConfigApiKey`は、公開されている場合はprovider hookを使います。同梱 - `amazon-bedrock`パスには、Bedrock runtime auth自体は依然としてAWS SDKのdefault chainを使うものの、ここに組み込みのAWS env-marker resolverもあります。 - | 13 | `contributeResolvedModelCompat` | 別の互換transportの背後にあるvendor model向けcompatフラグ | - | 14 | `capabilities` | 旧来の静的capability bag。互換性目的のみ | - | 15 | `normalizeToolSchemas` | 登録前のprovider所有tool-schemaクリーンアップ | - | 16 | `inspectToolSchemas` | provider所有tool-schema診断 | - | 17 | `resolveReasoningOutputMode` | タグ付きまたはネイティブreasoning-output契約 | - | 18 | `prepareExtraParams` | デフォルトのリクエストparams | - | 19 | `createStreamFn` | 完全にカスタムなStreamFn transport | - | 20 | `wrapStreamFn` | 通常streamパス上のカスタムヘッダー/ボディwrapper | + - `normalizeConfig` は、まず一致した provider を確認し、その後 + 実際に config を変更するものが見つかるまで、他の + フック対応 provider plugin を確認します。 + サポート対象の Google-family config エントリを書き換える provider フックがなければ、 + バンドルされた Google config normalizer が引き続き適用されます。 + - `resolveConfigApiKey` は、公開されている場合は provider フックを使います。バンドルされた + `amazon-bedrock` 経路にも、ここに組み込みの AWS env-marker resolver がありますが、 + Bedrock ランタイム auth 自体は引き続き AWS SDK デフォルト + チェーンを使います。 + | 13 | `contributeResolvedModelCompat` | 別の互換転送の背後にある vendor モデル向け compat フラグ | + | 14 | `capabilities` | legacy な静的 capability バッグ。互換性専用 | + | 15 | `normalizeToolSchemas` | 登録前の provider 所有ツールスキーマクリーンアップ | + | 16 | `inspectToolSchemas` | provider 所有ツールスキーマ diagnostics | + | 17 | `resolveReasoningOutputMode` | タグ付き vs ネイティブ reasoning-output 契約 | + | 18 | `prepareExtraParams` | デフォルトリクエストパラメータ | + | 19 | `createStreamFn` | 完全カスタムの StreamFn 転送 | + | 20 | `wrapStreamFn` | 通常ストリーム経路上のカスタムヘッダー/ボディラッパー | | 21 | `resolveTransportTurnState` | ネイティブなターンごとのヘッダー/メタデータ | - | 22 | `resolveWebSocketSessionPolicy` | ネイティブWSセッションヘッダー/クールダウン | - | 23 | `formatApiKey` | カスタムruntimeトークン形状 | - | 24 | `refreshOAuth` | カスタムOAuth更新 | - | 25 | `buildAuthDoctorHint` | 認証修復ガイダンス | - | 26 | `matchesContextOverflowError` | provider所有のオーバーフロー検出 | - | 27 | `classifyFailoverReason` | provider所有のレート制限/過負荷分類 | - | 28 | `isCacheTtlEligible` | プロンプトキャッシュTTLゲーティング | - | 29 | `buildMissingAuthMessage` | カスタム未認証ヒント | - | 30 | `suppressBuiltInModel` | 古くなったupstream行を隠す | - | 31 | `augmentModelCatalog` | synthetic forward-compat行 | - | 32 | `isBinaryThinking` | バイナリthinkingのオン/オフ | - | 33 | `supportsXHighThinking` | `xhigh` reasoningサポート | - | 34 | `resolveDefaultThinkingLevel` | デフォルトの`/think`ポリシー | - | 35 | `isModernModelRef` | live/smoke model一致 | + | 22 | `resolveWebSocketSessionPolicy` | ネイティブ WS セッションヘッダー/クールダウン | + | 23 | `formatApiKey` | カスタムランタイムトークン形式 | + | 24 | `refreshOAuth` | カスタム OAuth リフレッシュ | + | 25 | `buildAuthDoctorHint` | auth 修復ガイダンス | + | 26 | `matchesContextOverflowError` | provider 所有のオーバーフロー検出 | + | 27 | `classifyFailoverReason` | provider 所有のレート制限/過負荷分類 | + | 28 | `isCacheTtlEligible` | プロンプトキャッシュ TTL ゲーティング | + | 29 | `buildMissingAuthMessage` | カスタムの認証欠落ヒント | + | 30 | `suppressBuiltInModel` | 古くなったアップストリーム行を非表示 | + | 31 | `augmentModelCatalog` | synthetic な forward-compat 行 | + | 32 | `isBinaryThinking` | バイナリ thinking のオン/オフ | + | 33 | `supportsXHighThinking` | `xhigh` reasoning サポート | + | 34 | `resolveDefaultThinkingLevel` | デフォルト `/think` ポリシー | + | 35 | `isModernModelRef` | live/smoke モデルマッチング | | 36 | `prepareRuntimeAuth` | 推論前のトークン交換 | - | 37 | `resolveUsageAuth` | カスタムusage認証情報解析 | - | 38 | `fetchUsageSnapshot` | カスタムusage endpoint | - | 39 | `createEmbeddingProvider` | memory/search向けprovider所有embedding adapter | - | 40 | `buildReplayPolicy` | カスタムtranscript replay/compactionポリシー | - | 41 | `sanitizeReplayHistory` | 汎用クリーンアップ後のprovider固有replay書き換え | - | 42 | `validateReplayTurns` | 埋め込みrunner前の厳格なreplayターン検証 | + | 37 | `resolveUsageAuth` | カスタム使用量認証情報解析 | + | 38 | `fetchUsageSnapshot` | カスタム使用量エンドポイント | + | 39 | `createEmbeddingProvider` | memory/search 用の provider 所有 embedding アダプター | + | 40 | `buildReplayPolicy` | カスタム transcript replay/compaction ポリシー | + | 41 | `sanitizeReplayHistory` | 汎用クリーンアップ後の provider 固有 replay 書き換え | + | 42 | `validateReplayTurns` | 埋め込み runner 前の厳格な replay-turn 検証 | | 43 | `onModelSelected` | 選択後コールバック（例: telemetry） | - プロンプト調整に関する注意: + プロンプトチューニングに関する注意: - - `resolveSystemPromptContribution`を使うと、providerはモデルファミリー向けのキャッシュ対応システムプロンプトガイダンスを注入できます。この動作が1つのprovider/モデルファミリーに属し、stable/dynamic cache splitを維持すべき場合は、`before_prompt_build`よりこちらを優先してください。 + - `resolveSystemPromptContribution` を使うと、provider はモデルファミリー向けにキャッシュを意識した + システムプロンプトガイダンスを注入できます。動作が 1 つの provider/モデル + ファミリーに属し、安定/動的キャッシュ分割を維持すべき場合は、 + `before_prompt_build` よりこちらを優先してください。 詳細な説明と実例については、 - [Internals: Provider Runtime Hooks](/ja-JP/plugins/architecture#provider-runtime-hooks)を参照してください。 + [Internals: Provider Runtime Hooks](/ja-JP/plugins/architecture#provider-runtime-hooks) を参照してください。 - provider pluginは、テキスト推論に加えて、speech、realtime transcription、realtime - voice、media understanding、image generation、video generation、web fetch、 - およびweb searchを登録できます。 + provider plugin は、テキスト推論に加えて、speech、realtime transcription、realtime + voice、メディア理解、画像生成、動画生成、web fetch、 + および web search を登録できます: ```typescript register(api) { @@ -612,17 +675,22 @@ x-i18n: } ``` - OpenClawはこれを**hybrid-capability** pluginとして分類します。これは - 企業向けplugin（ベンダーごとに1プラグイン）に推奨されるパターンです。 - [Internals: Capability Ownership](/ja-JP/plugins/architecture#capability-ownership-model)を参照してください。 + OpenClaw はこれを **hybrid-capability** plugin と分類します。これは + 会社単位の plugin（ベンダーごとに 1 plugin）に推奨される + パターンです。 + [Internals: Capability Ownership](/ja-JP/plugins/architecture#capability-ownership-model) を参照してください。 - video generationでは、上記のモード認識capability形状を優先してください: - `generate`、`imageToVideo`、および`videoToVideo`です。`maxInputImages`、 - `maxInputVideos`、`maxDurationSeconds`のようなフラットな集約フィールドだけでは、変換モードのサポートや無効モードをきれいに表現できません。 + 動画生成では、上記のようなモード認識 capability 形状を優先してください: + `generate`、`imageToVideo`、`videoToVideo`。`maxInputImages`、`maxInputVideos`、`maxDurationSeconds` のような + フラットな集約フィールドだけでは、 + transform-mode サポートや無効なモードを適切に表現できません。 - music-generation providerも同じパターンに従うべきです: - プロンプトのみの生成には`generate`、参照画像ベースの生成には`edit`です。`maxInputImages`、 - `supportsLyrics`、`supportsFormat`のようなフラットな集約フィールドだけでは、editサポートを表現するには不十分であり、明示的な`generate` / `edit`ブロックが期待される契約です。 + 音楽生成 provider も同じパターンに従う必要があります: + プロンプトのみの生成には `generate`、参照画像ベースの + 生成には `edit` を使用します。`maxInputImages`、 + `supportsLyrics`、`supportsFormat` のようなフラットな集約フィールドだけでは + edit サポートを表現できません。明示的な `generate` / `edit` + ブロックが期待される契約です。 @@ -630,11 +698,11 @@ x-i18n: ```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; - // provider config object を index.ts または専用ファイルから export してください + // index.ts または専用ファイルから provider config object を export してください import { acmeProvider } from "./provider.js"; describe("acme-ai provider", () => { - it("resolves dynamic models", () => { + it("動的モデルを解決する", () => { const model = acmeProvider.resolveDynamicModel!({ modelId: "acme-beta-v3", } as any); @@ -642,14 +710,14 @@ x-i18n: expect(model.provider).toBe("acme-ai"); }); - it("returns catalog when key is available", async () => { + it("キーがある場合に catalog を返す", async () => { const result = await acmeProvider.catalog!.run({ resolveProviderApiKey: () => ({ apiKey: "test-key" }), } as any); expect(result?.provider?.models).toHaveLength(2); }); - it("returns null catalog when no key", async () => { + it("キーがない場合は null catalog を返す", async () => { const result = await acmeProvider.catalog!.run({ resolveProviderApiKey: () => ({ apiKey: undefined }), } as any); @@ -661,44 +729,45 @@ x-i18n: -## ClawHubへ公開する +## ClawHub に公開する -provider pluginは、他の外部コードpluginと同じ方法で公開します。 +provider plugin は、他の外部コード plugin と同じ方法で公開します: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -ここでは旧来のskill専用公開エイリアスを使わないでください。plugin packageは -`clawhub package publish`を使う必要があります。 +ここではレガシーな skill 専用 publish エイリアスを使わないでください。plugin パッケージでは +`clawhub package publish` を使う必要があります。 ## ファイル構成 ``` /acme-ai/ ├── package.json # openclaw.providers メタデータ -├── openclaw.plugin.json # provider認証メタデータを含むマニフェスト +├── openclaw.plugin.json # provider auth メタデータを含む Manifest ├── index.ts # definePluginEntry + registerProvider └── src/ ├── provider.test.ts # テスト - └── usage.ts # usage endpoint（任意） + └── usage.ts # 使用量エンドポイント（任意） ``` -## Catalog順序リファレンス +## catalog order リファレンス -`catalog.order`は、組み込みproviderに対してcatalogをどのタイミングでマージするかを制御します。 +`catalog.order` は、組み込み +provider に対して catalog をいつマージするかを制御します: -| Order | タイミング | 用途 | -| --------- | ------------- | ------------------------------------------- | -| `simple` | 最初のパス | 単純なAPIキーprovider | -| `profile` | simpleの後 | auth profileで制御されるprovider | -| `paired` | profileの後 | 複数の関連エントリーを合成する | -| `late` | 最後のパス | 既存providerを上書きする（衝突時に優先） | +| Order | タイミング | 使用例 | +| --------- | ------------- | ----------------------------------------------- | +| `simple` | 最初のパス | プレーンな API キー provider | +| `profile` | `simple` の後 | auth profile によって制御される provider | +| `paired` | `profile` の後 | 複数の関連エントリを合成する | +| `late` | 最後のパス | 既存の provider を上書きする（衝突時に優先） | ## 次のステップ -- [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) — pluginがchannelも提供する場合 -- [SDK Runtime](/ja-JP/plugins/sdk-runtime) — `api.runtime` helper（TTS、search、subagent） -- [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全なsubpath importリファレンス -- [Plugin Internals](/ja-JP/plugins/architecture#provider-runtime-hooks) — hookの詳細と同梱例 +- [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) — plugin がチャネルも提供する場合 +- [SDK Runtime](/ja-JP/plugins/sdk-runtime) — `api.runtime` ヘルパー（TTS、search、subagent） +- [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全な subpath import リファレンス +- [Plugin Internals](/ja-JP/plugins/architecture#provider-runtime-hooks) — フック詳細とバンドル例 diff --git a/docs/ja-JP/plugins/sdk-runtime.md b/docs/ja-JP/plugins/sdk-runtime.md index 24c355252..b4117b818 100644 --- a/docs/ja-JP/plugins/sdk-runtime.md +++ b/docs/ja-JP/plugins/sdk-runtime.md @@ -1,28 +1,27 @@ --- read_when: - - plugin から core helper（TTS、STT、画像生成、Web 検索、subagent）を呼び出す必要がある場合 - - api.runtime が何を公開しているかを理解したい場合 - - plugin コードから config、agent、または media helper にアクセスしている場合 + - プラグインからコアヘルパー（TTS、STT、画像生成、Web検索、サブエージェント）を呼び出す必要があります + - '`api.runtime`が何を公開しているかを理解したいです' + - プラグインコードから設定、エージェント、またはメディアヘルパーにアクセスしています sidebarTitle: Runtime Helpers -summary: api.runtime -- plugin で利用できる注入済みランタイムヘルパー -title: Plugin Runtime Helpers +summary: api.runtime -- プラグインで利用できる注入済みランタイムヘルパー +title: プラグインランタイムヘルパー x-i18n: - generated_at: "2026-04-08T02:18:00Z" + generated_at: "2026-04-11T02:47:20Z" model: gpt-5.4 provider: openai - source_hash: acb9e56678e9ed08d0998dfafd7cd1982b592be5bc34d9e2d2c1f70274f8f248 + source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be source_path: plugins/sdk-runtime.md workflow: 15 --- -# Plugin Runtime Helpers +# プラグインランタイムヘルパー -各 plugin の登録時に注入される `api.runtime` オブジェクトのリファレンスです。 -ホスト内部実装を直接 import する代わりに、これらの helper を使用してください。 +登録時にすべてのプラグインへ注入される`api.runtime`オブジェクトのリファレンスです。ホスト内部を直接インポートする代わりに、これらのヘルパーを使用してください。 - **手順付きガイドを探していますか？** これらの helper が実際の文脈でどのように使われるかを段階的に示すガイドについては、[Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) - または [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) を参照してください。 + **ウォークスルーを探していますか？** [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) + または[Provider Plugins](/ja-JP/plugins/sdk-provider-plugins)で、これらのヘルパーが実際の流れの中でどう使われるかを段階的に確認できます。 ```typescript @@ -35,30 +34,30 @@ register(api) { ### `api.runtime.agent` -agent ID、ディレクトリ、セッション管理です。 +エージェントID、ディレクトリ、セッション管理。 ```typescript -// agent の作業ディレクトリを解決する +// エージェントの作業ディレクトリを解決 const agentDir = api.runtime.agent.resolveAgentDir(cfg); -// agent workspace を解決する +// エージェントワークスペースを解決 const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg); -// agent ID を取得する +// エージェントIDを取得 const identity = api.runtime.agent.resolveAgentIdentity(cfg); -// デフォルトの thinking レベルを取得する +// デフォルトthinkingレベルを取得 const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model); -// agent のタイムアウトを取得する +// エージェントタイムアウトを取得 const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); -// workspace の存在を保証する +// ワークスペースの存在を保証 await api.runtime.agent.ensureAgentWorkspace(cfg); -// 組み込み Pi agent を実行する +// 埋め込みエージェントターンを実行 const agentDir = api.runtime.agent.resolveAgentDir(cfg); -const result = await api.runtime.agent.runEmbeddedPiAgent({ +const result = await api.runtime.agent.runEmbeddedAgent({ sessionId: "my-plugin:task-1", runId: crypto.randomUUID(), sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"), @@ -68,7 +67,13 @@ const result = await api.runtime.agent.runEmbeddedPiAgent({ }); ``` -**Session store helper** は `api.runtime.agent.session` 配下にあります: +`runEmbeddedAgent(...)`は、プラグインコードから通常のOpenClaw +エージェントターンを開始するための中立的なヘルパーです。これは、チャネル起点の返信と同じプロバイダー/モデル解決および +エージェントハーネス選択を使用します。 + +`runEmbeddedPiAgent(...)`は、互換性エイリアスとして引き続き利用できます。 + +**セッションストアヘルパー**は`api.runtime.agent.session`配下にあります: ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -79,7 +84,7 @@ const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId ### `api.runtime.agent.defaults` -デフォルトのモデル定数と provider 定数: +デフォルトのモデル定数とプロバイダー定数: ```typescript const model = api.runtime.agent.defaults.model; // 例: "anthropic/claude-sonnet-4-6" @@ -88,43 +93,43 @@ const provider = api.runtime.agent.defaults.provider; // 例: "anthropic" ### `api.runtime.subagent` -バックグラウンド subagent 実行を起動して管理します。 +バックグラウンドサブエージェント実行の開始と管理。 ```typescript -// subagent 実行を開始する +// サブエージェント実行を開始 const { runId } = await api.runtime.subagent.run({ sessionKey: "agent:main:subagent:search-helper", message: "Expand this query into focused follow-up searches.", - provider: "openai", // 任意の override - model: "gpt-4.1-mini", // 任意の override + provider: "openai", // 任意の上書き + model: "gpt-4.1-mini", // 任意の上書き deliver: false, }); -// 完了を待つ +// 完了を待機 const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 }); -// セッションメッセージを読む +// セッションメッセージを読み取り const { messages } = await api.runtime.subagent.getSessionMessages({ sessionKey: "agent:main:subagent:search-helper", limit: 10, }); -// セッションを削除する +// セッションを削除 await api.runtime.subagent.deleteSession({ sessionKey: "agent:main:subagent:search-helper", }); ``` - モデル override（`provider`/`model`）には、config の - `plugins.entries..subagent.allowModelOverride: true` によるオペレーターのオプトインが必要です。 - 信頼されていない plugin でも subagent は実行できますが、override 要求は拒否されます。 + モデル上書き（`provider`/`model`）には、設定内の + `plugins.entries..subagent.allowModelOverride: true`によるオペレーターの明示的オプトインが必要です。 + 信頼されていないプラグインでもサブエージェントは実行できますが、上書き要求は拒否されます。 ### `api.runtime.taskFlow` -Task Flow ランタイムを既存の OpenClaw セッションキーまたは信頼済み tool -context にバインドし、毎回 owner を渡さずに Task Flow を作成・管理します。 +Task Flowランタイムを既存のOpenClawセッションキーまたは信頼済みツール +コンテキストにバインドし、毎回ownerを渡さずにTask Flowを作成・管理します。 ```typescript const taskFlow = api.runtime.taskFlow.fromToolContext(ctx); @@ -151,56 +156,56 @@ const waiting = taskFlow.setWaiting({ }); ``` -自分の binding レイヤーからすでに信頼済みの OpenClaw セッションキーを持っている場合は、`bindSession({ sessionKey, requesterOrigin })` を使用してください。生の -ユーザー入力から bind しないでください。 +独自のバインディングレイヤーから信頼済みのOpenClawセッションキーをすでに持っている場合は、 +`bindSession({ sessionKey, requesterOrigin })`を使用してください。生のユーザー入力からバインドしてはいけません。 ### `api.runtime.tts` -テキスト読み上げ合成です。 +テキスト読み上げ。 ```typescript -// 標準 TTS +// 標準TTS const clip = await api.runtime.tts.textToSpeech({ text: "Hello from OpenClaw", cfg: api.config, }); -// 電話向け最適化 TTS +// 電話向け最適化TTS const telephonyClip = await api.runtime.tts.textToSpeechTelephony({ text: "Hello from OpenClaw", cfg: api.config, }); -// 利用可能な音声を一覧表示する +// 利用可能な音声を一覧表示 const voices = await api.runtime.tts.listVoices({ provider: "elevenlabs", cfg: api.config, }); ``` -core の `messages.tts` 設定と provider 選択を使用します。PCM 音声 -buffer と sample rate を返します。 +コアの`messages.tts`設定とプロバイダー選択を使用します。PCMオーディオ +バッファ + サンプルレートを返します。 ### `api.runtime.mediaUnderstanding` -画像、音声、動画の解析です。 +画像、音声、動画の解析。 ```typescript -// 画像を説明する +// 画像を説明 const image = await api.runtime.mediaUnderstanding.describeImageFile({ filePath: "/tmp/inbound-photo.jpg", cfg: api.config, agentDir: "/tmp/agent", }); -// 音声を文字起こしする +// 音声を文字起こし const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - mime: "audio/ogg", // 任意。MIME を推定できない場合に使用 + mime: "audio/ogg", // 任意。MIMEを推定できない場合に使用 }); -// 動画を説明する +// 動画を説明 const video = await api.runtime.mediaUnderstanding.describeVideoFile({ filePath: "/tmp/inbound-video.mp4", cfg: api.config, @@ -213,16 +218,16 @@ const result = await api.runtime.mediaUnderstanding.runFile({ }); ``` -出力が生成されなかった場合（例: 入力がスキップされた場合）は `{ text: undefined }` を返します。 +出力が生成されない場合（例: 入力がスキップされた場合）は`{ text: undefined }`を返します。 - `api.runtime.stt.transcribeAudioFile(...)` は、互換性のための - `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` の alias として引き続き利用できます。 + `api.runtime.stt.transcribeAudioFile(...)`は、 + `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`の互換性エイリアスとして引き続き利用できます。 ### `api.runtime.imageGeneration` -画像生成です。 +画像生成。 ```typescript const result = await api.runtime.imageGeneration.generate({ @@ -235,7 +240,7 @@ const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config }) ### `api.runtime.webSearch` -Web 検索です。 +Web検索。 ```typescript const providers = api.runtime.webSearch.listProviders({ config: api.config }); @@ -248,7 +253,7 @@ const result = await api.runtime.webSearch.search({ ### `api.runtime.media` -低レベル media ユーティリティです。 +低レベルメディアユーティリティ。 ```typescript const webMedia = await api.runtime.media.loadWebMedia(url); @@ -261,7 +266,7 @@ const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 }); ### `api.runtime.config` -config の読み込みと書き込みです。 +設定の読み込みと書き込み。 ```typescript const cfg = await api.runtime.config.loadConfig(); @@ -270,7 +275,7 @@ await api.runtime.config.writeConfigFile(cfg); ### `api.runtime.system` -システムレベルのユーティリティです。 +システムレベルユーティリティ。 ```typescript await api.runtime.system.enqueueSystemEvent(event); @@ -281,7 +286,7 @@ const hint = api.runtime.system.formatNativeDependencyHint(pkg); ### `api.runtime.events` -イベント購読です。 +イベント購読。 ```typescript api.runtime.events.onAgentEvent((event) => { @@ -294,7 +299,7 @@ api.runtime.events.onSessionTranscriptUpdate((update) => { ### `api.runtime.logging` -ロギングです。 +ロギング。 ```typescript const verbose = api.runtime.logging.shouldLogVerbose(); @@ -303,7 +308,7 @@ const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, ### `api.runtime.modelAuth` -モデルおよび provider の認証解決です。 +モデルおよびプロバイダー認証の解決。 ```typescript const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg }); @@ -315,7 +320,7 @@ const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({ ### `api.runtime.state` -状態ディレクトリの解決です。 +状態ディレクトリ解決。 ```typescript const stateDir = api.runtime.state.resolveStateDir(); @@ -323,7 +328,7 @@ const stateDir = api.runtime.state.resolveStateDir(); ### `api.runtime.tools` -メモリ tool ファクトリーと CLI です。 +メモリツールファクトリーとCLI。 ```typescript const getTool = api.runtime.tools.createMemoryGetTool(/* ... */); @@ -333,10 +338,10 @@ api.runtime.tools.registerMemoryCli(/* ... */); ### `api.runtime.channel` -チャネル固有のランタイム helper です（channel plugin がロードされたときに利用できます）。 +チャネル固有のランタイムヘルパー（チャネルプラグインが読み込まれている場合に利用可能）。 -`api.runtime.channel.mentions` は、ランタイム注入を使用する -バンドルチャネル plugin 向けの共有受信 mention-policy surface です: +`api.runtime.channel.mentions`は、ランタイム注入を使用する +バンドル版チャネルプラグイン向けの共有受信メンションポリシーサーフェスです: ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -363,7 +368,7 @@ const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({ }); ``` -利用可能な mention helper: +利用可能なメンションヘルパー: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -371,13 +376,14 @@ const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({ - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -`api.runtime.channel.mentions` は、意図的に古い -`resolveMentionGating*` 互換 helper を公開していません。正規化された -`{ facts, policy }` パスを優先してください。 +`api.runtime.channel.mentions`は、古い +`resolveMentionGating*`互換ヘルパーを意図的に公開していません。正規化された +`{ facts, policy }`経路を優先してください。 ## ランタイム参照の保存 -`register` コールバックの外で使うためにランタイム参照を保存するには、`createPluginRuntimeStore` を使用します: +`register`コールバックの外で使用するためにランタイム参照を保存するには、 +`createPluginRuntimeStore`を使用してください: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; @@ -385,7 +391,7 @@ import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; const store = createPluginRuntimeStore("my-plugin runtime not initialized"); -// エントリポイント内 +// エントリーポイント内 export default defineChannelPluginEntry({ id: "my-plugin", name: "My Plugin", @@ -396,30 +402,30 @@ export default defineChannelPluginEntry({ // 他のファイル内 export function getRuntime() { - return store.getRuntime(); // 初期化されていなければ throw する + return store.getRuntime(); // 初期化されていない場合はthrow } export function tryGetRuntime() { - return store.tryGetRuntime(); // 初期化されていなければ null を返す + return store.tryGetRuntime(); // 初期化されていない場合はnullを返す } ``` -## その他のトップレベル `api` フィールド +## その他のトップレベル`api`フィールド -`api.runtime` に加えて、API オブジェクトは次も提供します: +`api.runtime`に加えて、APIオブジェクトは以下も提供します: -| Field | Type | Description | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | plugin ID | -| `api.name` | `string` | plugin 表示名 | -| `api.config` | `OpenClawConfig` | 現在の config snapshot（利用可能な場合はアクティブなインメモリ runtime snapshot） | -| `api.pluginConfig` | `Record` | `plugins.entries..config` からの plugin 固有 config | -| `api.logger` | `PluginLogger` | スコープ付き logger（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 現在のロードモード。`"setup-runtime"` は完全エントリ前の軽量な起動/セットアップ用ウィンドウです | -| `api.resolvePath(input)` | `(string) => string` | plugin ルートからの相対パスを解決する | +| フィールド | 型 | 説明 | +| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------- | +| `api.id` | `string` | プラグインID | +| `api.name` | `string` | プラグイン表示名 | +| `api.config` | `OpenClawConfig` | 現在の設定スナップショット（利用可能な場合は、アクティブなインメモリ実行時スナップショット） | +| `api.pluginConfig` | `Record` | `plugins.entries..config`から取得したプラグイン固有設定 | +| `api.logger` | `PluginLogger` | スコープ付きロガー（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 現在の読み込みモード。`"setup-runtime"`は、完全なエントリー起動/設定前の軽量ウィンドウです | +| `api.resolvePath(input)` | `(string) => string` | プラグインルートからの相対パスを解決します | ## 関連 - [SDK Overview](/ja-JP/plugins/sdk-overview) -- サブパスリファレンス -- [SDK Entry Points](/ja-JP/plugins/sdk-entrypoints) -- `definePluginEntry` オプション -- [Plugin Internals](/ja-JP/plugins/architecture) -- capability モデルと registry +- [SDK Entry Points](/ja-JP/plugins/sdk-entrypoints) -- `definePluginEntry`オプション +- [Plugin Internals](/ja-JP/plugins/architecture) -- capability modelとレジストリ diff --git a/docs/ja-JP/providers/fal.md b/docs/ja-JP/providers/fal.md index b94436b5c..1ae89e9e1 100644 --- a/docs/ja-JP/providers/fal.md +++ b/docs/ja-JP/providers/fal.md @@ -1,36 +1,36 @@ --- read_when: - - OpenClaw で fal の画像生成を使いたい場合 - - FAL_KEY の認証フローが必要な場合 - - image_generate または video_generate 向けの fal デフォルトを使いたい場合 -summary: OpenClaw での fal 画像・動画生成のセットアップ + - OpenClawでfal画像生成を使用したいです + - '`FAL_KEY`認証フローが必要です' + - '`image_generate`または`video_generate`向けのfalデフォルト設定が必要です' +summary: OpenClawでのfal画像生成および動画生成の設定 title: fal x-i18n: - generated_at: "2026-04-06T03:11:20Z" + generated_at: "2026-04-11T02:48:00Z" model: gpt-5.4 provider: openai - source_hash: 1922907d2c8360c5877a56495323d54bd846d47c27a801155e3d11e3f5706fbd + source_hash: 9bfe4f69124e922a79a516a1bd78f0c00f7a45f3c6f68b6d39e0d196fa01beb3 source_path: providers/fal.md workflow: 15 --- # fal -OpenClaw には、ホスト型の画像生成および動画生成向けのバンドル `fal` provider が含まれています。 +OpenClawには、ホスト型の画像生成および動画生成向けにバンドル版`fal`プロバイダーが含まれています。 -- Provider: `fal` -- 認証: `FAL_KEY`（正式。`FAL_API_KEY` もフォールバックとして動作します） -- API: fal model endpoint +- プロバイダー: `fal` +- 認証: `FAL_KEY`（正規。`FAL_API_KEY`もフォールバックとして動作） +- API: falモデルエンドポイント ## クイックスタート -1. API キーを設定します: +1. APIキーを設定します: ```bash openclaw onboard --auth-choice fal-api-key ``` -2. デフォルトの画像 model を設定します: +2. デフォルトの画像モデルを設定します: ```json5 { @@ -46,15 +46,16 @@ openclaw onboard --auth-choice fal-api-key ## 画像生成 -バンドル `fal` image-generation provider のデフォルトは -`fal/fal-ai/flux/dev` です。 +バンドル版`fal`画像生成プロバイダーのデフォルトは +`fal/fal-ai/flux/dev`です。 -- Generate: リクエストごとに最大 4 枚の画像 -- Edit mode: 有効、参照画像は 1 枚 -- `size`、`aspectRatio`、`resolution` をサポート -- 現在の edit に関する注意点: fal の画像 edit endpoint は **`aspectRatio` の上書きに対応していません** +- 生成: 1回のリクエストで最大4枚の画像 +- 編集モード: 有効、参照画像は1枚 +- `size`、`aspectRatio`、`resolution`をサポート +- 現在の編集時の注意点: fal画像編集エンドポイントは + `aspectRatio`上書きをサポートしていません -fal をデフォルトの画像 provider として使うには: +falをデフォルト画像プロバイダーとして使用するには: ```json5 { @@ -70,20 +71,41 @@ fal をデフォルトの画像 provider として使うには: ## 動画生成 -バンドル `fal` video-generation provider のデフォルトは -`fal/fal-ai/minimax/video-01-live` です。 +バンドル版`fal`動画生成プロバイダーのデフォルトは +`fal/fal-ai/minimax/video-01-live`です。 -- モード: text-to-video と単一画像参照フロー -- 実行時: 長時間実行ジョブ向けの queue ベース submit/status/result フロー +- モード: テキストから動画、および単一画像参照フロー +- ランタイム: 長時間実行ジョブ向けのキュー対応submit/status/resultフロー +- HeyGen video-agentモデル参照: + - `fal/fal-ai/heygen/v2/video-agent` +- Seedance 2.0モデル参照: + - `fal/bytedance/seedance-2.0/fast/text-to-video` + - `fal/bytedance/seedance-2.0/fast/image-to-video` + - `fal/bytedance/seedance-2.0/text-to-video` + - `fal/bytedance/seedance-2.0/image-to-video` -fal をデフォルトの動画 provider として使うには: +Seedance 2.0をデフォルト動画モデルとして使用するには: ```json5 { agents: { defaults: { videoGenerationModel: { - primary: "fal/fal-ai/minimax/video-01-live", + primary: "fal/bytedance/seedance-2.0/fast/text-to-video", + }, + }, + }, +} +``` + +HeyGen video-agentをデフォルト動画モデルとして使用するには: + +```json5 +{ + agents: { + defaults: { + videoGenerationModel: { + primary: "fal/fal-ai/heygen/v2/video-agent", }, }, }, @@ -92,6 +114,6 @@ fal をデフォルトの動画 provider として使うには: ## 関連 -- [画像生成](/ja-JP/tools/image-generation) -- [動画生成](/tools/video-generation) -- [設定リファレンス](/ja-JP/gateway/configuration-reference#agent-defaults) +- [Image Generation](/ja-JP/tools/image-generation) +- [Video Generation](/ja-JP/tools/video-generation) +- [Configuration Reference](/ja-JP/gateway/configuration-reference#agent-defaults) diff --git a/docs/ja-JP/reference/RELEASING.md b/docs/ja-JP/reference/RELEASING.md index 0cb4fffe2..e1c93262c 100644 --- a/docs/ja-JP/reference/RELEASING.md +++ b/docs/ja-JP/reference/RELEASING.md @@ -1,143 +1,109 @@ --- read_when: - - 公開リリースチャンネルの定義を確認したい場合 - - バージョン命名と頻度を確認したい場合 -summary: 公開リリースチャンネル、バージョン命名、およびリリース頻度 + - 公開リリースチャネルの定義を探しています + - バージョン命名とリリース頻度を探しています +summary: 公開リリースチャネル、バージョン命名、およびリリース頻度 title: リリースポリシー x-i18n: - generated_at: "2026-04-05T12:55:16Z" + generated_at: "2026-04-11T02:48:05Z" model: gpt-5.4 provider: openai - source_hash: bb52a13264c802395aa55404c6baeec5c7b2a6820562e7a684057e70cc85668f + source_hash: ca613d094c93670c012f0b79720fad0d5d85be802f54b0acb7a8f22aca5bde12 source_path: reference/RELEASING.md workflow: 15 --- # リリースポリシー -OpenClawには3つの公開リリースレーンがあります: +OpenClawには3つの公開リリースレーンがあります。 -- stable: タグ付きリリース。デフォルトではnpmの`beta`へ公開され、明示的に要求された場合はnpmの`latest`へ公開されます +- stable: デフォルトでnpmの`beta`へ公開されるタグ付きリリース。明示的に要求された場合はnpmの`latest`へ公開 - beta: npmの`beta`へ公開されるプレリリースタグ -- dev: `main`の移動中の先端 +- dev: `main`の移動する先頭 ## バージョン命名 - Stableリリースバージョン: `YYYY.M.D` - - Gitタグ: `vYYYY.M.D` -- Stable修正リリースバージョン: `YYYY.M.D-N` - - Gitタグ: `vYYYY.M.D-N` + - Git tag: `vYYYY.M.D` +- Stable修正版リリースバージョン: `YYYY.M.D-N` + - Git tag: `vYYYY.M.D-N` - Betaプレリリースバージョン: `YYYY.M.D-beta.N` - - Gitタグ: `vYYYY.M.D-beta.N` -- 月と日はゼロ埋めしない -- `latest`は現在昇格済みのstable npmリリースを意味する -- `beta`は現在のbetaインストール対象を意味する -- Stableおよびstable修正リリースはデフォルトでnpmの`beta`へ公開されます。リリース運用者は明示的に`latest`を指定することもでき、また後で検証済みのbetaビルドを昇格させることもできます -- すべてのOpenClawリリースは、npmパッケージとmacOSアプリを同時に出荷します + - Git tag: `vYYYY.M.D-beta.N` +- 月や日はゼロ埋めしない +- `latest` は現在昇格済みのstableなnpmリリースを意味する +- `beta` は現在のbetaインストール対象を意味する +- Stableおよびstable修正版リリースは、デフォルトでnpmの`beta`へ公開される。リリース運用者は明示的に`latest`を対象にすることも、検証済みのbetaビルドを後で昇格させることもできる +- すべてのOpenClawリリースはnpmパッケージとmacOSアプリを一緒に出荷する ## リリース頻度 -- リリースはbeta-firstで進行します -- Stableは最新betaが検証された後にのみ続きます -- 詳細なリリース手順、承認、認証情報、および復旧メモは - maintainer専用です +- リリースはbeta-firstで進む +- Stableは、最新のbetaが検証された後にのみ続く +- 詳細なリリース手順、承認、認証情報、リカバリーノートはメンテナー専用 ## リリース事前確認 -- `pnpm release:check`の前に`pnpm build && pnpm ui:build`を実行して、 - pack - 検証ステップに必要な`dist/*`リリースアーティファクトとControl UIバンドルが存在するようにしてください -- タグ付きリリースの前には毎回`pnpm release:check`を実行してください -- mainブランチのnpm事前確認では - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - もtarballパッケージ化前に実行され、`OPENAI_API_KEY`と - `ANTHROPIC_API_KEY`の両workflow secretを使用します -- 承認前に`RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - （または対応するbeta/修正タグ）を実行してください -- npm公開後は、 - `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - （または対応するbeta/修正バージョン）を実行し、新しいtemp prefixで - 公開済みregistryインストールパスを検証してください -- Maintainerリリース自動化では現在、事前確認後に昇格する方式を使用しています: - - 実際のnpm公開は、成功したnpm `preflight_run_id`を通過していなければならない - - stable npmリリースのデフォルトは`beta` - - stable npm公開では、workflow入力によって明示的に`latest`を指定できる - - stable npmの`beta`から`latest`への昇格は、信頼済みの`OpenClaw NPM Release` workflow上で、依然として明示的な手動モードとして利用可能 - - この昇格モードでも、有効な`NPM_TOKEN`が`npm-release`環境に必要です。npmの`dist-tag`管理は信頼済み公開とは別だからです +- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行して、pack検証ステップに必要な `dist/*` リリース成果物とControl UIバンドルを用意する +- すべてのタグ付きリリース前に `pnpm release:check` を実行する +- mainブランチのnpm事前確認では、tarballをパッケージ化する前に、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両workflow secretを使って `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` も実行する +- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（または対応するbeta/修正版タグ）を実行する +- npm公開後に、公開済みレジストリのインストール経路を新しい一時prefixで検証するため、`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（または対応するbeta/修正版バージョン）を実行する +- Maintainerのリリース自動化は現在、preflight-then-promoteを使う: + - 実際のnpm公開は、成功したnpm `preflight_run_id` を通過していなければならない + - stableなnpmリリースはデフォルトで`beta` + - stableなnpm公開は、workflow inputで明示的に`latest`を対象にできる + - stableなnpmの`beta`から`latest`への昇格は、信頼された`OpenClaw NPM Release` workflow上で引き続き明示的な手動モードとして利用可能 + - その昇格モードでも、npmの`dist-tag`管理はtrusted publishingとは別であるため、`npm-release` environment内に有効な`NPM_TOKEN`が必要 - 公開の`macOS Release`は検証専用 - - 実際の非公開mac公開は、成功した非公開macの - `preflight_run_id`と`validate_run_id`を通過していなければならない - - 実際の公開パスでは、再度ビルドするのではなく準備済みアーティファクトを昇格する -- `YYYY.M.D-N`のようなstable修正リリースでは、公開後検証でも - `YYYY.M.D`から`YYYY.M.D-N`への同じtemp-prefixアップグレードパスを確認し、 - リリース修正によって古いグローバルインストールが - ベースstable payloadのまま静かに残ることがないようにします -- npmリリース事前確認では、tarballに - `dist/control-ui/index.html`と空でない`dist/control-ui/assets/`ペイロードの両方が含まれていなければフェイルクローズするため、 - 空のブラウザーダッシュボードを再び出荷することはありません -- リリース作業がCI planning、extension timing manifest、または高速 - test matrixに触れた場合は、承認前に`.github/workflows/ci.yml`から - planner所有の`checks-fast-extensions` - workflow matrix出力を再生成して確認してください。そうしないとリリースノートが古いCIレイアウトを説明してしまいます -- Stable macOSリリースの準備には、updaterサーフェスも含まれます: - - GitHubリリースには、パッケージ済みの`.zip`、`.dmg`、`.dSYM.zip`が最終的に含まれていなければならない - - 公開後の`main`上の`appcast.xml`は、新しいstable zipを指していなければならない - - パッケージ済みアプリは、非デバッグbundle id、空でないSparkle feed - URL、およびそのリリースバージョン向けの正規Sparkleビルド下限以上の - `CFBundleVersion`を維持していなければならない + - 実際の非公開mac公開は、成功した非公開macの `preflight_run_id` と `validate_run_id` を通過していなければならない + - 実際の公開経路では、再ビルドではなく準備済み成果物を昇格させる +- `YYYY.M.D-N` のようなstable修正版リリースでは、post-publish verifierが `YYYY.M.D` から `YYYY.M.D-N` への同じ一時prefixアップグレード経路も確認するため、リリース修正によって古いグローバルインストールがベースstableペイロードのまま静かに残ることはない +- npmリリース事前確認は、tarballに `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` ペイロードの両方が含まれていない限りclosed failになる。これにより空のブラウザーダッシュボードを再び出荷しないようにする +- リリース作業でCI計画、拡張タイミングマニフェスト、または拡張テストマトリクスに触れた場合は、承認前に `.github/workflows/ci.yml` からplanner所有の `checks-node-extensions` workflow matrix出力を再生成して確認する。これによりリリースノートが古いCIレイアウトを記述しないようにする +- stableなmacOSリリース準備には、updaterサーフェスも含まれる: + - GitHub releaseには、パッケージ化された `.zip`、`.dmg`、`.dSYM.zip` が最終的に含まれていなければならない + - `main` 上の `appcast.xml` は、公開後に新しいstable zipを指していなければならない + - パッケージ化されたアプリは、デバッグでないbundle id、空でないSparkle feed URL、およびそのリリースバージョンに対する正式なSparkle build floor以上の `CFBundleVersion` を維持しなければならない ## NPM workflow入力 -`OpenClaw NPM Release`は、運用者が制御する次の入力を受け付けます: +`OpenClaw NPM Release` は、運用者が制御する次の入力を受け付けます。 -- `tag`: 必須のリリースタグ。例: `v2026.4.2`、`v2026.4.2-1`、または - `v2026.4.2-beta.1` -- `preflight_only`: 検証/ビルド/パッケージのみなら`true`、実際の - 公開パスなら`false` -- `preflight_run_id`: 実際の公開パスで必須。workflowが成功した事前確認実行から準備済みtarballを再利用するため -- `npm_dist_tag`: 公開パス向けのnpm対象タグ。デフォルトは`beta` -- `promote_beta_to_latest`: すでに公開済みの - stable `beta`ビルドを`latest`へ移す場合は`true`。公開はスキップする +- `tag`: `v2026.4.2`、`v2026.4.2-1`、`v2026.4.2-beta.1` のような必須リリースタグ +- `preflight_only`: 検証/ビルド/パッケージのみの場合は `true`、実際の公開経路の場合は `false` +- `preflight_run_id`: 実際の公開経路で必須。workflowが成功した事前確認実行から準備済みtarballを再利用するために使う +- `npm_dist_tag`: 公開経路用のnpm対象タグ。デフォルトは `beta` +- `promote_beta_to_latest`: 公開をスキップして、すでに公開済みのstableな`beta`ビルドを`latest`へ移動する場合は `true` ルール: -- Stableおよび修正タグは`beta`または`latest`のいずれかへ公開可能 -- Betaプレリリースタグは`beta`にのみ公開可能 -- 実際の公開パスでは、事前確認時と同じ`npm_dist_tag`を使わなければならず、 - workflowは公開継続前にそのメタデータを検証する -- 昇格モードでは、stableまたは修正タグ、`preflight_only=false`、 - 空の`preflight_run_id`、および`npm_dist_tag=beta`を使用しなければならない -- 昇格モードでも、`npm dist-tag add`には通常のnpm認証が必要なため、 - `npm-release`環境に有効な`NPM_TOKEN`が必要です +- Stableおよび修正版タグは、`beta` または `latest` のどちらにも公開できる +- Betaプレリリースタグは `beta` にのみ公開できる +- 実際の公開経路では、事前確認時に使ったものと同じ `npm_dist_tag` を使わなければならない。workflowは公開続行前にそのメタデータを検証する +- 昇格モードでは、stableまたは修正版タグ、`preflight_only=false`、空の `preflight_run_id`、および `npm_dist_tag=beta` を使わなければならない +- 昇格モードでも、`npm dist-tag add` には通常のnpm認証が必要なため、`npm-release` environment内に有効な `NPM_TOKEN` が必要 ## Stable npmリリース手順 -stable npmリリースを切るとき: +stableなnpmリリースを切るとき: -1. `preflight_only=true`で`OpenClaw NPM Release`を実行する -2. 通常のbeta-firstフローでは`npm_dist_tag=beta`を選び、意図的に直接stable公開したい場合にのみ`latest`を選ぶ -3. 成功した`preflight_run_id`を保存する -4. `preflight_only=false`、同じ - `tag`、同じ`npm_dist_tag`、保存した`preflight_run_id`で - 再度`OpenClaw NPM Release`を実行する -5. リリースが`beta`へ出た場合、その後 - 同じstable `tag`、`promote_beta_to_latest=true`、`preflight_only=false`、 - `preflight_run_id`を空、`npm_dist_tag=beta`で`OpenClaw NPM Release`を実行し、 - その公開済みビルドを`latest`へ移したいタイミングで昇格する +1. `preflight_only=true` で `OpenClaw NPM Release` を実行する +2. 通常のbeta-firstフローでは `npm_dist_tag=beta` を選び、意図的に直接stable公開したい場合にのみ `latest` を選ぶ +3. 成功した `preflight_run_id` を保存する +4. `preflight_only=false`、同じ `tag`、同じ `npm_dist_tag`、保存した `preflight_run_id` で再度 `OpenClaw NPM Release` を実行する +5. リリースが `beta` に入った場合、その公開済みビルドを `latest` に移したいタイミングで、同じstableな `tag`、`promote_beta_to_latest=true`、`preflight_only=false`、空の `preflight_run_id`、`npm_dist_tag=beta` で後から `OpenClaw NPM Release` を実行する -この昇格モードでも、`npm-release`環境の承認と、その -環境内の有効な`NPM_TOKEN`が必要です。 +昇格モードでも、`npm-release` environmentの承認と、そのenvironment内の有効な `NPM_TOKEN` が必要です。 -これにより、直接公開パスとbeta-first昇格パスの両方が文書化され、 -運用者から見える状態に保たれます。 +これにより、直接公開経路とbeta-first昇格経路の両方が、文書化され、運用者から見える状態に保たれます。 -## 公開参照 +## 公開リファレンス - [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml) - [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts) - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -Maintainerは、実際のランブックとして +実際のランブックについては、メンテナーは [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -内の非公開リリースドキュメントを使用します。 +の非公開リリースドキュメントを使用します。 diff --git a/docs/ja-JP/reference/templates/AGENTS.md b/docs/ja-JP/reference/templates/AGENTS.md index db41d9eaf..e6a117f9f 100644 --- a/docs/ja-JP/reference/templates/AGENTS.md +++ b/docs/ja-JP/reference/templates/AGENTS.md @@ -1,180 +1,177 @@ --- read_when: - - ワークスペースを手動でブートストラップするとき + - ワークスペースを手動でbootstrapする場合 summary: AGENTS.mdのワークスペーステンプレート title: AGENTS.mdテンプレート x-i18n: - generated_at: "2026-04-05T12:56:42Z" + generated_at: "2026-04-11T02:48:17Z" model: gpt-5.4 provider: openai - source_hash: ede171764b5443af3dabf9dd511c1952e64cd4b11d61346f2bda56923bbebb78 + source_hash: 6d8a3e96f547da6cc082d747c042555b0ec4963b66921d1700b4590f0e0c38b4 source_path: reference/templates/AGENTS.md workflow: 15 --- # AGENTS.md - あなたのワークスペース -このフォルダがホームです。そう扱ってください。 +このフォルダーはホームです。そう扱ってください。 ## 初回実行 -`BOOTSTRAP.md` があるなら、それがあなたの出生証明書です。それに従い、自分が何者かを把握してから削除してください。もう二度と必要ありません。 +`BOOTSTRAP.md`が存在するなら、それがあなたの出生証明書です。それに従い、自分が何者かを把握してから削除してください。もう二度と必要ありません。 ## セッション開始時 -何より先に、以下を行ってください。 +他のことをする前に、次を実行してください。 -1. `SOUL.md` を読む — これがあなた自身です -2. `USER.md` を読む — これがあなたが助ける相手です -3. `memory/YYYY-MM-DD.md`（今日と昨日）を読んで最近の文脈を確認する -4. **MAIN SESSIONの場合**（人間との直接チャット）: `MEMORY.md` も読む +1. `SOUL.md`を読む — これはあなたが何者かです +2. `USER.md`を読む — これはあなたが誰を助けているかです +3. `memory/YYYY-MM-DD.md`（今日と昨日）を読んで最近の文脈を把握する +4. **MAIN SESSION内の場合**（あなたの人間との直接チャット）: `MEMORY.md`も読む -許可は求めないでください。そのまま実行してください。 +許可を求めないでください。そのまま実行してください。 ## 記憶 -あなたはセッションごとに新しい状態で目覚めます。これらのファイルが継続性を担います。 +あなたは各セッションで新しく目覚めます。これらのファイルがあなたの連続性です。 -- **日次メモ:** `memory/YYYY-MM-DD.md`（必要なら `memory/` を作成）— 起きたことの生ログ -- **長期:** `MEMORY.md` — 人間の長期記憶のような、整理された記憶 +- **日次ノート:** `memory/YYYY-MM-DD.md`（必要なら`memory/`を作成）— 何が起きたかの生ログ +- **長期:** `MEMORY.md` — 人間の長期記憶のような、厳選された記憶 -重要なことを記録してください。決定、文脈、覚えておくべきこと。保持してほしいと頼まれない限り、秘密は飛ばしてください。 +重要なことを記録してください。決定、文脈、覚えておくべきこと。保持を求められない限り、secretは省いてください。 ### 🧠 MEMORY.md - あなたの長期記憶 -- **main sessionでのみ読み込む**（人間との直接チャット） +- **main session内でのみ読み込む**（あなたの人間との直接チャット） - **共有コンテキストでは読み込まない**（Discord、グループチャット、他の人とのセッション） -- これは**セキュリティ**のためです — 見知らぬ相手に漏れるべきでない個人的な文脈が含まれます -- main sessionでは MEMORY.md を自由に**読み取り、編集、更新**してかまいません -- 重要な出来事、考え、決定、意見、学んだことを書いてください -- これは整理された記憶です — 生ログではなく、蒸留された本質です -- 時間が経ったら日次ファイルを見直し、残す価値がある内容を MEMORY.md に反映してください +- これは**セキュリティ**のためです — 見知らぬ人に漏れるべきでない個人的な文脈が含まれています +- main sessionでは`MEMORY.md`を自由に**読み取り、編集、更新**できます +- 重要な出来事、考え、決定、意見、学んだ教訓を書いてください +- これはあなたの厳選された記憶です — 生ログではなく、蒸留された本質です +- 時間が経ったら、日次ファイルを見直し、保持する価値のある内容で`MEMORY.md`を更新してください -### 📝 書き残すこと - 「頭の中のメモ」はなし！ +### 📝 書き残す - 「心のメモ」はなし! - **記憶には限りがあります** — 何かを覚えておきたいなら、**ファイルに書いてください** -- 「頭の中のメモ」はセッション再起動をまたげません。ファイルはまたげます。 -- 誰かに「これを覚えておいて」と言われたら → `memory/YYYY-MM-DD.md` または関連ファイルを更新する -- 教訓を得たら → AGENTS.md、TOOLS.md、または関連する skill を更新する -- ミスをしたら → 未来の自分が繰り返さないよう文書化する -- **テキスト > 脳** 📝 +- 「心のメモ」はセッション再起動を生き残れません。ファイルなら生き残ります。 +- 誰かに「これを覚えておいて」と言われたら → `memory/YYYY-MM-DD.md`または関連ファイルを更新する +- 教訓を学んだら → AGENTS.md、TOOLS.md、または関連するskillを更新する +- ミスをしたら → 将来の自分が繰り返さないように文書化する +- **Text > Brain** 📝 -## 越えてはいけない一線 +## 越えてはいけない線 - 個人データを持ち出さない。絶対に。 - 破壊的なコマンドは確認なしで実行しない。 -- `trash` > `rm`（復元できるほうが完全削除より良い） -- 迷ったら確認する。 +- `rm`より`trash`（復旧可能な方が、完全消去よりよい） +- 迷ったら聞く。 ## 外部と内部 -**自由に行ってよいこと:** +**自由にやってよいこと:** - ファイルを読む、探索する、整理する、学ぶ -- Web検索をする、カレンダーを確認する +- Webを検索する、カレンダーを確認する - このワークスペース内で作業する -**先に確認が必要なこと:** +**先に確認すること:** -- メール送信、ツイート、公開投稿 -- マシンの外に出るあらゆること -- 自信が持てないこと全般 +- メール、ツイート、公開投稿を送ること +- マシンの外へ出ていくあらゆること +- 自信が持てないこと ## グループチャット -あなたは人間の持ち物にアクセスできます。だからといって、それを_共有していい_わけではありません。グループでは、あなたは参加者です — 人間本人でもなければ、その代理でもありません。話す前に考えてください。 +あなたは人間の持ち物にアクセスできます。でも、それはその持ち物を_共有する_という意味ではありません。グループでは、あなたは参加者です — その人の代弁者でも代理人でもありません。発言する前に考えてください。 -### 💬 話すべきタイミングを見極める！ +### 💬 話すべきときを見極める! -すべてのメッセージを受け取るグループチャットでは、**いつ発言するかを賢く判断して**ください。 +すべてのメッセージを受け取るグループチャットでは、**いつ貢献するかを賢く判断**してください。 -**返信するとき:** +**返信するのはこんなとき:** -- 直接言及された、または質問された -- 本当に価値を足せる（情報、洞察、助け） -- 気の利いた／面白いひと言が自然に合う -- 重要な誤情報を正す +- 直接メンションされた、または質問された +- 本当に価値を加えられる（情報、洞察、助け） +- 気の利いた/面白いひと言が自然に合う +- 重要な誤情報を訂正する - 求められて要約する **黙っているべきとき（HEARTBEAT_OK）:** -- 人間同士の雑談にすぎない -- すでに誰かが質問に答えている -- あなたの返答が単に「そうだね」や「いいね」になるだけ -- あなたがいなくても会話が問題なく流れている -- メッセージを足すと場の空気を壊す +- 人間同士のただの雑談 +- 誰かがすでに質問に答えている +- あなたの返答が「うん」や「いいね」程度にしかならない +- 会話があなたなしでうまく流れている +- メッセージを足すと雰囲気を切ってしまう -**人間のルール:** グループチャットの人間は、すべてのメッセージにいちいち反応しません。あなたもそうすべきです。量より質。本当の友達とのグループチャットで送らない内容なら、送らないでください。 +**人間ルール:** 人間はグループチャットで全メッセージに返答しません。あなたも同じです。量より質。実際の友人グループチャットで送らない内容なら、送らないでください。 -**三連投を避ける:** 同じメッセージに対して、別々の反応で何度も返答しないでください。断片的な3通より、考えた1通のほうが良いです。 +**三連投を避ける:** 同じメッセージに対して、異なる反応で何度も返答しないでください。3つの断片より、1つの考えられた返答の方がよいです。 -主役にならず、参加してください。 +支配するのではなく、参加してください。 -### 😊 人間らしくリアクションする！ +### 😊 人間らしくリアクションする! -リアクションに対応しているプラットフォーム（Discord、Slack）では、絵文字リアクションを自然に使ってください。 +リアクションに対応するプラットフォーム（Discord、Slack）では、絵文字リアクションを自然に使ってください。 -**リアクションするとき:** +**リアクションするのはこんなとき:** -- 感謝はしたいが、返信までは不要なとき（👍, ❤️, 🙌） -- 何かが笑えたとき（😂, 💀） -- 興味深い、または考えさせられると感じたとき（🤔, 💡） -- 会話の流れを邪魔せずに認識を示したいとき -- 単純な yes/no や承認の場面（✅, 👀） +- 返信は不要だが感謝を示したい（👍、❤️、🙌） +- 何かが面白かった（😂、💀） +- 興味深い、または考えさせられた（🤔、💡） +- 流れを止めずに受け取ったことを示したい +- 単純なyes/noや承認の場面（✅、👀） -**重要な理由:** -リアクションは軽量なソーシャルシグナルです。人間は常に使っています — チャットを散らかさずに「見たよ、認識しているよ」と伝えられます。あなたもそうしてください。 +**なぜ重要か:** +リアクションは軽量な社会的シグナルです。人間はこれを常に使っています — 「見たよ、受け取ったよ」を、チャットを散らかさずに伝えます。あなたもそうしてください。 -**やりすぎないこと:** 1メッセージにつきリアクションは最大1つ。最も合うものを選んでください。 +**やりすぎない:** 1メッセージにつきリアクションは最大1つ。最も合うものを選んでください。 ## ツール -ツールは Skills が提供します。必要になったらその `SKILL.md` を確認してください。ローカルメモ（カメラ名、SSH詳細、音声設定）は `TOOLS.md` に残してください。 +Skillsがあなたのツールを提供します。必要なときは、その`SKILL.md`を確認してください。ローカルメモ（カメラ名、SSH詳細、音声設定）は`TOOLS.md`に保存してください。 -**🎭 音声ストーリーテリング:** `sag`（ElevenLabs TTS）が使えるなら、物語、映画の要約、「お話タイム」には音声を使ってください。文字の壁よりずっと引き込まれます。面白い声で人を驚かせてください。 +**🎭 音声ストーリーテリング:** `sag`（ElevenLabs TTS）があるなら、物語、映画の要約、「お話タイム」には音声を使ってください。テキストの壁よりずっと魅力的です。面白い声で人を驚かせてください。 -**📝 プラットフォームごとの書式:** +**📝 プラットフォームの書式設定:** -- **Discord/WhatsApp:** Markdownの表は使わないこと！代わりに箇条書きを使ってください -- **Discordのリンク:** 埋め込みを抑制するため、複数のリンクは `<>` で囲む: `` -- **WhatsApp:** 見出しは使わない — 強調には **太字** または大文字を使う +- **Discord/WhatsApp:** Markdownテーブルは禁止! 代わりに箇条書きを使ってください +- **Discordのリンク:** 埋め込みを抑制するため、複数リンクは`<>`で囲んでください: `` +- **WhatsApp:** 見出しは使わない — 強調には**太字**または大文字を使ってください -## 💓 Heartbeats - 自発的に動く！ +## 💓 Heartbeat - 自分から動く! -heartbeat poll を受け取ったら（メッセージが設定済みの heartbeat prompt に一致したら）、毎回ただ `HEARTBEAT_OK` と返すだけにしないでください。heartbeats を生産的に使いましょう。 +heartbeat poll（メッセージが設定されたheartbeatプロンプトに一致する）を受け取ったら、毎回ただ`HEARTBEAT_OK`と返すだけにしないでください。heartbeatを生産的に使いましょう。 -デフォルトの 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.md`を自由に編集して構いません。トークン消費を抑えるため、内容は小さく保ってください。 -`HEARTBEAT.md` は短いチェックリストやリマインダーで自由に編集してかまいません。トークン消費を抑えるため、小さく保ってください。 +### Heartbeatとcron: 使い分け -### Heartbeat と cron: それぞれを使うタイミング - -**heartbeat を使うとき:** +**heartbeatを使うべきとき:** - 複数の確認をまとめて処理できる（受信箱 + カレンダー + 通知を1ターンで） -- 最近のメッセージから会話の文脈が必要 -- タイミングに多少のずれがあってもよい（約30分ごとで十分、厳密でなくてよい） -- 定期確認をまとめて API 呼び出しを減らしたい +- 直近メッセージからの会話文脈が必要 +- タイミングが多少ずれてもよい（約30分ごとで十分、厳密でなくてよい） +- 定期確認をまとめてAPI呼び出しを減らしたい -**cron を使うとき:** +**cronを使うべきとき:** -- 正確な時刻が重要（「毎週月曜の午前9:00ちょうど」） -- タスクを main session の履歴から切り離したい +- 正確な時刻が重要（「毎週月曜の9:00ちょうど」） +- タスクをmain session履歴から切り離したい - そのタスクに別のモデルや思考レベルを使いたい -- 単発リマインダー（「20分後に知らせて」） -- main session を介さず、出力を直接チャンネルに届けたい +- 単発のリマインダー（「20分後に思い出させて」） +- 出力をmain sessionを介さず直接チャンネルへ届けたい -**ヒント:** 似た定期確認は複数の cron ジョブにせず、`HEARTBEAT.md` にまとめてください。正確なスケジュールや独立タスクには cron を使ってください。 +**ヒント:** 複数の定期確認ジョブを作る代わりに、似た定期確認は`HEARTBEAT.md`へまとめてください。正確なスケジュールや独立タスクにはcronを使ってください。 -**確認すること（これらをローテーションし、1日2〜4回）:** +**確認すること（これらをローテーション、1日2〜4回）:** -- **メール** - 急ぎの未読メッセージはあるか？ -- **カレンダー** - 今後24〜48時間の予定はあるか？ -- **メンション** - Twitter/ソーシャル通知はあるか？ -- **天気** - 人間が外出しそうなら関係あるか？ +- **メール** - 緊急の未読メッセージはあるか +- **カレンダー** - 今後24〜48時間の予定はあるか +- **メンション** - Twitter/SNS通知はあるか +- **天気** - 人間が外出しそうなら関係あるか -**確認記録**は `memory/heartbeat-state.json` に残してください: +**確認履歴を**`memory/heartbeat-state.json`**に記録してください:** ```json { @@ -186,41 +183,41 @@ heartbeat poll を受け取ったら（メッセージが設定済みの heartbe } ``` -**声をかけるタイミング:** +**連絡すべきとき:** - 重要なメールが届いた -- カレンダーの予定が近い（<2h） -- 何か面白いものを見つけた -- 最後に何か伝えてから >8h 経っている +- カレンダー予定が近い（<2時間） +- 面白いことを見つけた +- 最後に何か言ってから8時間以上経った -**静かにしているタイミング（HEARTBEAT_OK）:** +**静かにしているべきとき（HEARTBEAT_OK）:** -- 深夜（23:00-08:00）で、緊急ではない +- 深夜（23:00-08:00）、緊急時を除く - 人間が明らかに忙しい -- 前回の確認から新しいことが何もない -- さっき確認したばかり（<30分前） +- 前回の確認以降、新しいことがない +- 30分未満前に確認したばかり -**確認なしで自発的にやってよい作業:** +**確認なしでできる能動的な作業:** -- 記憶ファイルを読んで整理する -- プロジェクトの状況確認（git status など） +- memoryファイルを読む、整理する +- プロジェクトの様子を見る（`git status`など） - ドキュメントを更新する -- 自分の変更をコミットして push する -- **MEMORY.md を見直して更新する**（下記参照） +- 自分の変更をcommitしてpushする +- **MEMORY.mdを見直して更新する**（下記参照） -### 🔄 記憶のメンテナンス（Heartbeat中） +### 🔄 記憶のメンテナンス（heartbeat中） -数日に一度は、heartbeat を使って次を行ってください。 +定期的に（数日ごと）、heartbeatを使って次を行ってください。 -1. 最近の `memory/YYYY-MM-DD.md` ファイルを読み返す -2. 長期的に残す価値のある重要な出来事、教訓、洞察を見つける -3. 蒸留した学びを `MEMORY.md` に反映する -4. もはや関連しない古い情報を MEMORY.md から削除する +1. 最近の`memory/YYYY-MM-DD.md`ファイルを読み返す +2. 長期的に保持する価値のある重要な出来事、教訓、洞察を特定する +3. 蒸留した学びで`MEMORY.md`を更新する +4. もう関係のない古い情報を`MEMORY.md`から削除する -これは、人間が日記を見返して自分のメンタルモデルを更新するようなものです。日次ファイルは生メモで、MEMORY.md は整理された知恵です。 +これは、人間が日記を見返して自分のメンタルモデルを更新するのに似ています。日次ファイルは生メモ、`MEMORY.md`は厳選された知恵です。 -目標は、うるさくならずに役に立つこと。1日に数回確認し、役立つ裏方作業をしつつ、静かな時間は尊重してください。 +目標は、うるさくならずに役立つことです。1日に数回は様子を見て、有用な裏方作業をしつつ、静かな時間は尊重してください。 ## 自分のものにする -これは出発点です。何がうまくいくかを見極めながら、自分なりの慣習、スタイル、ルールを足していってください。 +これは出発点です。何がうまくいくかが分かってきたら、自分の慣習、スタイル、ルールを追加してください。 diff --git a/docs/ja-JP/tools/browser.md b/docs/ja-JP/tools/browser.md index 572014cf2..f5ad18069 100644 --- a/docs/ja-JP/tools/browser.md +++ b/docs/ja-JP/tools/browser.md @@ -1,15 +1,15 @@ --- read_when: - - エージェント制御のブラウザ自動化を追加しています - - openclaw があなた自身の Chrome に干渉している理由をデバッグする - - macOSアプリでブラウザ設定 + ライフサイクルを実装する + - エージェント制御のブラウザ自動化の追加 + - OpenClaw が自分の Chrome に干渉している理由のデバッグ + - macOS アプリでのブラウザ設定とライフサイクルの実装 summary: 統合ブラウザ制御サービス + アクションコマンド -title: ブラウザ（OpenClaw管理） +title: ブラウザ（OpenClaw 管理） x-i18n: - generated_at: "2026-04-10T04:43:40Z" + generated_at: "2026-04-11T02:48:37Z" model: gpt-5.4 provider: openai - source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604 + source_hash: da6fed36a6f40a50e825f90e5616778954545bd7e52397f7e088b85251ee024f source_path: tools/browser.md workflow: 15 --- @@ -17,24 +17,25 @@ x-i18n: # ブラウザ（openclaw 管理） OpenClaw は、エージェントが制御する**専用の Chrome/Brave/Edge/Chromium プロファイル**を実行できます。 -これはあなたの個人用ブラウザから分離されており、Gateway 内の小さなローカル +これは個人用ブラウザから分離されており、Gateway 内の小さなローカル 制御サービス（loopback のみ）を通じて管理されます。 初心者向けの見方: - これは**エージェント専用の別ブラウザ**だと考えてください。 -- `openclaw` プロファイルは、あなたの個人用ブラウザプロファイルに**触れません**。 +- `openclaw` プロファイルは個人用ブラウザプロファイルには**触れません**。 - エージェントは安全なレーン内で**タブを開き、ページを読み取り、クリックし、入力**できます。 -- 組み込みの `user` プロファイルは、Chrome MCP を通じてあなたの実際のサインイン済み Chrome セッションに接続します。 +- 組み込みの `user` プロファイルは、Chrome MCP を通じて、実際にサインイン済みの Chrome セッションに接続します。 -## 利用できる機能 +## できること -- **openclaw** という名前の個別ブラウザプロファイル（デフォルトではオレンジのアクセント）。 +- **openclaw** という名前の別ブラウザプロファイル（デフォルトでオレンジのアクセント）。 - 決定論的なタブ制御（一覧表示/開く/フォーカス/閉じる）。 - エージェントアクション（クリック/入力/ドラッグ/選択）、スナップショット、スクリーンショット、PDF。 -- オプションのマルチプロファイル対応（`openclaw`、`work`、`remote`、...）。 +- 任意のマルチプロファイル対応（`openclaw`、`work`、`remote`、...）。 -このブラウザは**日常使い用ではありません**。これはエージェントの自動化と検証のための、安全で分離された操作面です。 +このブラウザは日常使いのブラウザ**ではありません**。これは +エージェント自動化と検証のための、安全で分離されたサーフェスです。 ## クイックスタート @@ -45,15 +46,17 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -「Browser disabled」と表示された場合は、設定で有効にし（下記参照）、Gateway を再起動してください。 +「Browser disabled」と表示される場合は、config で有効にし（以下を参照）、 +Gateway を再起動してください。 -`openclaw browser` 自体がまったく存在しない場合、またはエージェントがブラウザツールを -利用できないと言う場合は、[ブラウザコマンドまたはツールが見つからない](/ja-JP/tools/browser#missing-browser-command-or-tool) に進んでください。 +`openclaw browser` 自体が存在しない、またはエージェントが browser tool +を利用できないと言う場合は、[Missing browser command or tool](/ja-JP/tools/browser#missing-browser-command-or-tool) に進んでください。 -## プラグイン制御 +## plugin 制御 -デフォルトの `browser` ツールは、現在はデフォルトで有効な状態で同梱されるバンドル済みプラグインです。 -つまり、OpenClaw の残りのプラグインシステムを削除しなくても、これを無効化または置き換えできます。 +デフォルトの `browser` tool は、現在デフォルトで有効な +バンドル plugin です。つまり、OpenClaw の残りの plugin システムを削除せずに、 +これを無効化または置き換えできます: ```json5 { @@ -67,27 +70,33 @@ openclaw browser --browser-profile openclaw snapshot } ``` -同じ `browser` ツール名を提供する別のプラグインをインストールする前に、バンドル済みプラグインを無効化してください。デフォルトのブラウザ体験には、以下の両方が必要です。 +同じ `browser` tool 名を提供する別の plugin をインストールする前に、 +バンドル plugin を無効にしてください。デフォルトのブラウザ体験には次の両方が必要です: - `plugins.entries.browser.enabled` が無効化されていないこと - `browser.enabled=true` -プラグインだけをオフにすると、バンドル済みブラウザ CLI（`openclaw browser`）、 -Gateway メソッド（`browser.request`）、エージェントツール、デフォルトのブラウザ制御サービスはすべてまとめて消えます。 -`browser.*` 設定は、置き換え用プラグインが再利用できるようそのまま残ります。 +plugin だけをオフにすると、バンドルされた browser CLI（`openclaw browser`）、 +gateway メソッド（`browser.request`）、エージェント tool、およびデフォルトの browser 制御 +サービスがすべて一緒に消えます。`browser.*` config はそのまま残るため、 +置き換え plugin が再利用できます。 -バンドル済みブラウザプラグインは、現在ではブラウザランタイム実装も所有しています。 -コアには、共有の Plugin SDK ヘルパーと、古い内部 import パス向けの互換性 re-export のみが残されています。 -実際には、ブラウザプラグインパッケージを削除または置き換えると、2 つ目のコア所有ランタイムが残るのではなく、ブラウザ機能セット全体が取り除かれます。 +バンドル browser plugin は、現在 browser ランタイム実装も所有しています。 +core には共有 Plugin SDK ヘルパーと、 +古い内部 import パス向けの互換性 re-export だけが残ります。実際には、 +browser plugin パッケージを削除または置き換えると、 +2つ目の core 所有ランタイムが残るのではなく、browser 機能セット自体がなくなります。 -ブラウザ設定の変更では、新しい設定でバンドル済みプラグインがブラウザサービスを再登録できるようにするため、引き続き Gateway の再起動が必要です。 +browser config の変更は引き続き Gateway の再起動が必要です。これはバンドル plugin が +新しい設定で browser サービスを再登録するためです。 -## ブラウザコマンドまたはツールが見つからない +## browser コマンドまたは tool が見つからない -アップグレード後に `openclaw browser` が突然未知のコマンドになった場合、または -エージェントがブラウザツールがないと報告する場合、最も一般的な原因は、`browser` を含まない制限的な `plugins.allow` リストです。 +アップグレード後に `openclaw browser` が突然 unknown command になったり、 +エージェントが browser tool がないと報告したりする場合、最も一般的な原因は、 +`browser` を含まない制限付き `plugins.allow` リストです。 -壊れた設定の例: +問題のある config の例: ```json5 { @@ -97,7 +106,7 @@ Gateway メソッド（`browser.request`）、エージェントツール、デ } ``` -`browser` をプラグイン許可リストに追加して修正してください。 +修正するには、plugin allowlist に `browser` を追加します: ```json5 { @@ -107,47 +116,49 @@ Gateway メソッド（`browser.request`）、エージェントツール、デ } ``` -重要な注意点: +重要な注意: - `plugins.allow` が設定されている場合、`browser.enabled=true` だけでは不十分です。 - `plugins.allow` が設定されている場合、`plugins.entries.browser.enabled=true` だけでも不十分です。 -- `tools.alsoAllow: ["browser"]` は、バンドル済みブラウザプラグインを読み込み**ません**。これは、プラグインがすでに読み込まれた後にツールポリシーを調整するだけです。 -- 制限的なプラグイン許可リストが不要な場合、`plugins.allow` を削除してもデフォルトのバンドル済みブラウザ動作が復元されます。 +- `tools.alsoAllow: ["browser"]` はバンドルされた browser plugin を読み込み**ません**。これは plugin がすでに読み込まれた後に tool ポリシーを調整するだけです。 +- 制限付き plugin allowlist が不要なら、`plugins.allow` を削除してもデフォルトのバンドル browser 動作に戻せます。 典型的な症状: -- `openclaw browser` が未知のコマンドになる。 -- `browser.request` がない。 -- エージェントがブラウザツールを利用不可または欠落と報告する。 +- `openclaw browser` が unknown command になる。 +- `browser.request` が存在しない。 +- エージェントが browser tool を利用不可または欠落と報告する。 ## プロファイル: `openclaw` と `user` - `openclaw`: 管理された分離ブラウザ（拡張機能不要）。 -- `user`: あなたの**実際のサインイン済み Chrome** セッション用の組み込み Chrome MCP 接続プロファイル。 +- `user`: 実際にサインイン済みの Chrome + セッション向けの組み込み Chrome MCP 接続プロファイル。 -エージェントのブラウザツール呼び出しでは: +エージェント browser tool 呼び出しでは: -- デフォルト: 分離された `openclaw` ブラウザを使用します。 -- 既存のログイン済みセッションが重要で、ユーザーがコンピューターの前にいて接続プロンプトのクリック/承認ができる場合は、`profile="user"` を優先します。 +- デフォルト: 分離された `openclaw` ブラウザを使います。 +- 既存のログイン済みセッションが重要で、ユーザーが + コンピューターの前にいて接続プロンプトをクリック/承認できる場合は、`profile="user"` を優先します。 - `profile` は、特定のブラウザモードを使いたいときの明示的な上書きです。 -デフォルトで管理モードを使いたい場合は、`browser.defaultProfile: "openclaw"` を設定してください。 +管理モードをデフォルトにしたい場合は `browser.defaultProfile: "openclaw"` を設定します。 ## 設定 -ブラウザ設定は `~/.openclaw/openclaw.json` にあります。 +browser 設定は `~/.openclaw/openclaw.json` にあります。 ```json5 { browser: { enabled: true, // デフォルト: true ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // デフォルトは trusted-network モード - // allowPrivateNetwork: true, // 従来のエイリアス + // dangerouslyAllowPrivateNetwork: true, // 信頼できるプライベートネットワークアクセスにのみ opt in + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // 従来の単一プロファイル上書き + // cdpUrl: "http://127.0.0.1:18792", // legacy な単一プロファイル上書き remoteCdpTimeoutMs: 1500, // リモート CDP HTTP タイムアウト（ms） remoteCdpHandshakeTimeoutMs: 3000, // リモート CDP WebSocket ハンドシェイクタイムアウト（ms） defaultProfile: "openclaw", @@ -176,33 +187,34 @@ Gateway メソッド（`browser.request`）、エージェントツール、デ } ``` -注意点: +注意: -- ブラウザ制御サービスは、`gateway.port` から導出されたポートの loopback にバインドされます - （デフォルト: `18791`、つまり gateway + 2）。 +- browser 制御サービスは `gateway.port` から導出されるポートで loopback にバインドします + （デフォルト: `18791`。gateway + 2）。 - Gateway ポート（`gateway.port` または `OPENCLAW_GATEWAY_PORT`）を上書きすると、 - 導出されるブラウザポートも同じ「ファミリー」に収まるようにずれます。 -- `cdpUrl` は、未設定時には管理対象のローカル CDP ポートがデフォルトになります。 + 派生 browser ポートも同じ「ファミリー」に収まるように移動します。 +- `cdpUrl` が未設定の場合、デフォルトは管理されたローカル CDP ポートです。 - `remoteCdpTimeoutMs` は、リモート（非 loopback）CDP 到達性チェックに適用されます。 - `remoteCdpHandshakeTimeoutMs` は、リモート CDP WebSocket 到達性チェックに適用されます。 -- ブラウザのナビゲーション/タブを開く操作には、ナビゲーション前に SSRF ガードが適用され、ナビゲーション後の最終 `http(s)` URL に対してベストエフォートで再チェックされます。 -- strict SSRF モードでは、リモート CDP エンドポイントの検出/プローブ（`cdpUrl`。`/json/version` 参照を含む）もチェックされます。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` のデフォルトは `true` です（trusted-network モデル）。strict な public-only ブラウジングにするには `false` に設定してください。 -- `browser.ssrfPolicy.allowPrivateNetwork` は、互換性のため従来のエイリアスとして引き続きサポートされています。 -- `attachOnly: true` は、「ローカルブラウザを絶対に起動せず、すでに実行中の場合のみ接続する」ことを意味します。 -- `color` とプロファイルごとの `color` はブラウザ UI に色味を付け、どのプロファイルがアクティブかを視覚的に確認できるようにします。 -- デフォルトプロファイルは `openclaw` です（OpenClaw 管理のスタンドアロンブラウザ）。サインイン済みのユーザーブラウザを使うには `defaultProfile: "user"` を使用してください。 -- 自動検出順序: Chromium ベースであればシステムのデフォルトブラウザ、それ以外の場合は Chrome → Brave → Edge → Chromium → Chrome Canary。 -- ローカルの `openclaw` プロファイルには `cdpPort`/`cdpUrl` が自動割り当てされます。これらを設定するのはリモート CDP の場合だけにしてください。 -- `driver: "existing-session"` は、生の CDP の代わりに Chrome DevTools MCP を使用します。 - この driver では `cdpUrl` を設定しないでください。 -- 既存セッションプロファイルを Brave や Edge などのデフォルト以外の Chromium ユーザープロファイルに接続する場合は、 - `browser.profiles..userDataDir` を設定してください。 +- browser の navigation/open-tab は、ナビゲーション前に SSRF ガードされ、 + ナビゲーション後の最終 `http(s)` URL に対してもベストエフォートで再チェックされます。 +- strict SSRF モードでは、リモート CDP エンドポイントのディスカバリー/probe（`cdpUrl`。`/json/version` 参照を含む）もチェック対象です。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` はデフォルトで無効です。意図的にプライベートネットワーク browser アクセスを信頼する場合にのみ `true` に設定してください。 +- `browser.ssrfPolicy.allowPrivateNetwork` は、互換性のための legacy alias として引き続きサポートされます。 +- `attachOnly: true` は「ローカルブラウザを起動しない。すでに実行中なら接続のみ行う」という意味です。 +- `color` とプロファイルごとの `color` は browser UI に色を付け、どのプロファイルがアクティブかを見分けやすくします。 +- デフォルトプロファイルは `openclaw`（OpenClaw 管理のスタンドアロンブラウザ）です。サインイン済みユーザーブラウザに opt in するには `defaultProfile: "user"` を使います。 +- 自動検出順序: システムデフォルトブラウザが Chromium ベースならそれを使用し、そうでなければ Chrome → Brave → Edge → Chromium → Chrome Canary の順です。 +- ローカル `openclaw` プロファイルは `cdpPort`/`cdpUrl` を自動割り当てするため、これらを設定するのはリモート CDP の場合だけにしてください。 +- `driver: "existing-session"` は、生の CDP ではなく Chrome DevTools MCP を使います。 + この driver には `cdpUrl` を設定しないでください。 +- Brave や Edge のような非デフォルトの Chromium ユーザープロファイルに + existing-session プロファイルを接続させるには、`browser.profiles..userDataDir` を設定してください。 ## Brave（または別の Chromium ベースブラウザ）を使う -**システムのデフォルト**ブラウザが Chromium ベース（Chrome/Brave/Edge など）の場合、 -OpenClaw は自動的にそれを使用します。自動検出を上書きするには `browser.executablePath` を設定してください。 +**システムデフォルト**ブラウザが Chromium ベース（Chrome/Brave/Edge など）の場合、 +OpenClaw は自動的にそれを使います。自動検出を上書きするには `browser.executablePath` を設定します: CLI の例: @@ -236,50 +248,49 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## ローカル制御とリモート制御 - **ローカル制御（デフォルト）:** Gateway が loopback 制御サービスを起動し、ローカルブラウザを起動できます。 -- **リモート制御（ノードホスト）:** ブラウザがあるマシン上でノードホストを実行すると、Gateway はブラウザアクションをそこにプロキシできます。 -- **リモート CDP:** `browser.profiles..cdpUrl`（または `browser.cdpUrl`）を設定して、 - リモートの Chromium ベースブラウザに接続します。この場合、OpenClaw はローカルブラウザを起動しません。 +- **リモート制御（node host）:** ブラウザがあるマシン上で node host を実行し、Gateway が browser アクションをその node にプロキシします。 +- **リモート CDP:** リモートの Chromium ベースブラウザに接続するには `browser.profiles..cdpUrl`（または `browser.cdpUrl`）を設定します。この場合、OpenClaw はローカルブラウザを起動しません。 -停止時の動作はプロファイルモードによって異なります: +停止動作はプロファイルモードによって異なります: - ローカル管理プロファイル: `openclaw browser stop` は - OpenClaw が起動したブラウザプロセスを停止します -- attach-only および remote CDP プロファイル: `openclaw browser stop` はアクティブな - 制御セッションを閉じ、Playwright/CDP のエミュレーション上書き（ビューポート、 - カラースキーム、ロケール、タイムゾーン、オフラインモード、および類似の状態）を解放します。 - この場合でも、OpenClaw が起動したブラウザプロセスは存在しません + OpenClaw が起動した browser プロセスを停止します +- attach-only およびリモート CDP プロファイル: `openclaw browser stop` は、アクティブな + 制御セッションを閉じ、Playwright/CDP のエミュレーション上書き（viewport、 + color scheme、locale、timezone、offline mode などの状態）を解除します。 + OpenClaw 自体が browser プロセスを起動していない場合でも同様です -リモート CDP URL には認証情報を含めることができます: +リモート CDP URL には auth を含めることができます: - クエリトークン（例: `https://provider.example?token=`） -- HTTP Basic 認証（例: `https://user:pass@provider.example`） +- HTTP Basic auth（例: `https://user:pass@provider.example`） OpenClaw は `/json/*` エンドポイント呼び出し時と -CDP WebSocket 接続時の両方で認証情報を保持します。 -トークンを設定ファイルにコミットする代わりに、環境変数またはシークレットマネージャーを使うことを推奨します。 +CDP WebSocket 接続時の両方で auth を保持します。 +トークンは config ファイルにコミットするのではなく、環境変数やシークレットマネージャーを使うことを推奨します。 -## ノードブラウザプロキシ（デフォルトでゼロ設定） +## Node browser プロキシ（ゼロ設定デフォルト） -ブラウザがあるマシン上で**ノードホスト**を実行している場合、OpenClaw は -追加のブラウザ設定なしでブラウザツール呼び出しをそのノードへ自動ルーティングできます。 -これはリモート Gateway のデフォルトパスです。 +browser があるマシンで **node host** を実行している場合、OpenClaw は +追加の browser 設定なしで browser tool 呼び出しをその node に自動ルーティングできます。 +これはリモート Gateway のデフォルト経路です。 -注意点: +注意: -- ノードホストは、ローカルのブラウザ制御サーバーを**プロキシコマンド**経由で公開します。 -- プロファイルはノード自身の `browser.profiles` 設定から取得されます（ローカルと同じ）。 -- `nodeHost.browserProxy.allowProfiles` はオプションです。従来/デフォルトの動作にするには空のままにしてください。設定済みのすべてのプロファイルが、プロファイル作成/削除ルートを含めて、プロキシ経由で引き続き到達可能です。 -- `nodeHost.browserProxy.allowProfiles` を設定すると、OpenClaw はそれを最小権限の境界として扱います。許可リストにあるプロファイルのみを対象にでき、永続プロファイルの作成/削除ルートはプロキシ面でブロックされます。 -- 不要であれば無効化できます: - - ノード側: `nodeHost.browserProxy.enabled=false` - - Gateway 側: `gateway.nodes.browser.mode="off"` +- node host は、そのローカル browser 制御サーバーを **proxy command** として公開します。 +- プロファイルは node 側の `browser.profiles` 設定（ローカルと同じ）から取得されます。 +- `nodeHost.browserProxy.allowProfiles` は任意です。空のままにすると legacy/デフォルト動作になり、設定済みのすべてのプロファイルがプロキシ経由で到達可能なままです。プロファイル作成/削除ルートも含まれます。 +- `nodeHost.browserProxy.allowProfiles` を設定すると、OpenClaw はそれを最小権限境界として扱います: allowlist に含まれるプロファイルだけを対象にでき、永続プロファイル作成/削除ルートはプロキシサーフェス上でブロックされます。 +- 不要なら無効化できます: + - node 側: `nodeHost.browserProxy.enabled=false` + - gateway 側: `gateway.nodes.browser.mode="off"` ## Browserless（ホスト型リモート CDP） -[Browserless](https://browserless.io) は、HTTPS と WebSocket 経由で -CDP 接続 URL を公開するホスト型 Chromium サービスです。OpenClaw はどちらの形式も使用できますが、 -リモートブラウザプロファイルでは、もっとも簡単なのは Browserless の接続ドキュメントにある -直接の WebSocket URL です。 +[Browserless](https://browserless.io) は、 +HTTPS および WebSocket 経由で CDP 接続 URL を公開するホスト型 Chromium サービスです。OpenClaw はどちらの形式も使用できますが、 +リモート browser プロファイルでは Browserless の接続ドキュメントにある +直接 WebSocket URL が最も簡単です。 例: @@ -300,31 +311,31 @@ CDP 接続 URL を公開するホスト型 Chromium サービスです。OpenCla } ``` -注意点: +注意: -- `` を実際の Browserless トークンに置き換えてください。 -- Browserless アカウントに対応するリージョンエンドポイントを選択してください（詳細はそのドキュメントを参照）。 +- `` は実際の Browserless token に置き換えてください。 +- Browserless アカウントに対応するリージョン endpoint を選んでください（詳細は Browserless のドキュメントを参照）。 - Browserless から HTTPS ベース URL が提供される場合は、それを - 直接 CDP 接続用の `wss://` に変換するか、HTTPS URL のままにして OpenClaw に - `/json/version` を検出させることができます。 + 直接 CDP 接続用に `wss://` に変換することも、 + HTTPS URL のまま使って OpenClaw に `/json/version` をディスカバーさせることもできます。 -## 直接 WebSocket CDP プロバイダー +## 直接 WebSocket CDP provider -一部のホスト型ブラウザサービスは、標準の HTTP ベース CDP 検出（`/json/version`）ではなく -**直接 WebSocket** エンドポイントを公開しています。OpenClaw はその両方をサポートします: +一部のホスト型 browser サービスは、標準の HTTP ベース CDP ディスカバリー（`/json/version`）ではなく、 +**直接 WebSocket** endpoint を公開しています。OpenClaw は両方をサポートします: - **HTTP(S) エンドポイント** — OpenClaw は `/json/version` を呼び出して - WebSocket デバッガー URL を検出し、その後接続します。 -- **WebSocket エンドポイント**（`ws://` / `wss://`）— OpenClaw は `/json/version` をスキップして - 直接接続します。これは、 + WebSocket debugger URL を検出してから接続します。 +- **WebSocket エンドポイント**（`ws://` / `wss://`）— OpenClaw は `/json/version` をスキップして直接接続します。これは [Browserless](https://browserless.io)、 [Browserbase](https://www.browserbase.com)、または - WebSocket URL を提供する任意のプロバイダーのようなサービスで使用してください。 + WebSocket URL を提供する任意の provider で使用してください。 ### Browserbase -[Browserbase](https://www.browserbase.com) は、組み込みの CAPTCHA 解決、ステルスモード、 -住宅用プロキシを備えたヘッドレスブラウザ実行用のクラウドプラットフォームです。 +[Browserbase](https://www.browserbase.com) は、 +組み込み CAPTCHA 解決、stealth mode、および residential +proxy を備えた headless browser 実行用クラウドプラットフォームです。 ```json5 { @@ -343,82 +354,84 @@ CDP 接続 URL を公開するホスト型 Chromium サービスです。OpenCla } ``` -注意点: +注意: -- [サインアップ](https://www.browserbase.com/sign-up) して、 - [Overview ダッシュボード](https://www.browserbase.com/overview) から **API Key** +- [Sign up](https://www.browserbase.com/sign-up) して、 + [Overview dashboard](https://www.browserbase.com/overview) から **API Key** をコピーしてください。 -- `` を実際の Browserbase API キーに置き換えてください。 -- Browserbase は WebSocket 接続時にブラウザセッションを自動作成するため、 +- `` は実際の Browserbase API key に置き換えてください。 +- Browserbase は WebSocket 接続時に browser session を自動作成するため、 手動のセッション作成手順は不要です。 -- 無料プランでは、同時セッション 1 つと月あたり 1 ブラウザ時間が利用できます。 +- 無料プランでは、同時セッション 1 つ、月あたり browser 1 時間まで利用できます。 有料プランの上限については [pricing](https://www.browserbase.com/pricing) を参照してください。 -- 完全な API リファレンス、SDK ガイド、統合例については - [Browserbase docs](https://docs.browserbase.com) を参照してください。 +- 完全な API + リファレンス、SDK ガイド、および統合例については [Browserbase docs](https://docs.browserbase.com) を参照してください。 ## セキュリティ -主な考え方: +重要な考え方: -- ブラウザ制御は loopback のみです。アクセスは Gateway の認証またはノードペアリングを経由します。 -- スタンドアロンの loopback ブラウザ HTTP API は、**shared-secret 認証のみ**を使用します: - Gateway トークンの Bearer 認証、`x-openclaw-password`、または - 設定された Gateway パスワードを使う HTTP Basic 認証です。 -- Tailscale Serve の identity ヘッダーと `gateway.auth.mode: "trusted-proxy"` は、 - このスタンドアロン loopback ブラウザ API を**認証しません**。 -- ブラウザ制御が有効で、shared-secret 認証が設定されていない場合、OpenClaw は - 起動時に `gateway.auth.token` を自動生成し、それを設定に永続化します。 -- `gateway.auth.mode` がすでに - `password`、`none`、または `trusted-proxy` の場合、OpenClaw はそのトークンを自動生成しません。 -- Gateway とすべてのノードホストはプライベートネットワーク（Tailscale）上に置いてください。公開露出は避けてください。 -- リモート CDP URL/トークンはシークレットとして扱ってください。環境変数またはシークレットマネージャーの使用を推奨します。 +- browser 制御は loopback 専用です。アクセスは Gateway の auth または node pairing を通じて流れます。 +- スタンドアロンの loopback browser HTTP API は、**shared-secret auth のみ**を使用します: + gateway token bearer auth、`x-openclaw-password`、または + 設定された gateway password を使う HTTP Basic auth です。 +- Tailscale Serve の identity headers と `gateway.auth.mode: "trusted-proxy"` は、 + このスタンドアロン loopback browser API の認証には**なりません**。 +- browser 制御が有効で、shared-secret auth が設定されていない場合、OpenClaw は + 起動時に `gateway.auth.token` を自動生成し、config に永続化します。 +- `gateway.auth.mode` が + すでに `password`、`none`、または `trusted-proxy` の場合、OpenClaw はその token を自動生成**しません**。 +- Gateway とすべての node host はプライベートネットワーク（Tailscale）上に保ち、 + 公開インターネットに露出させないでください。 +- リモート CDP URL/token はシークレットとして扱い、環境変数やシークレットマネージャーを優先してください。 リモート CDP のヒント: -- 可能な場合は、暗号化されたエンドポイント（HTTPS または WSS）と短命トークンを優先してください。 -- 長寿命トークンを設定ファイルに直接埋め込むのは避けてください。 +- 可能であれば暗号化されたエンドポイント（HTTPS または WSS）と短命トークンを使ってください。 +- 長期トークンを config ファイルに直接埋め込むのは避けてください。 ## プロファイル（マルチブラウザ） OpenClaw は複数の名前付きプロファイル（ルーティング設定）をサポートします。プロファイルには次の種類があります: -- **openclaw 管理**: 専用の Chromium ベースブラウザインスタンス。独自のユーザーデータディレクトリ + CDP ポートを持ちます -- **リモート**: 明示的な CDP URL（別の場所で動作している Chromium ベースブラウザ） -- **既存セッション**: Chrome DevTools MCP 自動接続経由の既存 Chrome プロファイル +- **openclaw-managed**: 専用の Chromium ベース browser インスタンス。独自の user data directory + CDP port を持ちます +- **remote**: 明示的な CDP URL（別の場所で動作している Chromium ベース browser） +- **existing session**: Chrome DevTools MCP 自動接続を通じた既存の Chrome プロファイル デフォルト: - `openclaw` プロファイルは、存在しない場合に自動作成されます。 -- `user` プロファイルは、Chrome MCP の既存セッション接続用に組み込まれています。 -- `user` 以外の既存セッションプロファイルはオプトインです。`--driver existing-session` で作成してください。 -- ローカル CDP ポートは、デフォルトで **18800–18899** から割り当てられます。 -- プロファイルを削除すると、そのローカルデータディレクトリはゴミ箱に移動されます。 +- `user` プロファイルは、Chrome MCP の existing-session 接続用に組み込まれています。 +- existing-session プロファイルは `user` 以外では opt-in です。`--driver existing-session` で作成してください。 +- ローカル CDP ポートはデフォルトで **18800–18899** から割り当てられます。 +- プロファイルを削除すると、そのローカルデータディレクトリは Trash に移動されます。 -すべての制御エンドポイントは `?profile=` を受け付けます。CLI では `--browser-profile` を使用します。 +すべての制御エンドポイントは `?profile=` を受け付けます。CLI では `--browser-profile` を使います。 -## Chrome DevTools MCP 経由の既存セッション +## Chrome DevTools MCP 経由の existing-session -OpenClaw は、公式の Chrome DevTools MCP サーバーを通じて、実行中の Chromium ベースブラウザプロファイルにも接続できます。 -これにより、そのブラウザプロファイルですでに開かれているタブとログイン状態を再利用できます。 +OpenClaw は、公式の Chrome DevTools MCP サーバーを通じて、 +実行中の Chromium ベース browser プロファイルにも接続できます。これにより、その browser プロファイルですでに +開かれているタブとログイン状態を再利用できます。 -公式の背景説明とセットアップ参考資料: +公式の背景説明とセットアップ参照: -- [Chrome for Developers: ブラウザセッションで Chrome DevTools MCP を使う](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) +- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) 組み込みプロファイル: - `user` -オプション: 別の名前、色、またはブラウザデータディレクトリを使いたい場合は、 -独自のカスタム既存セッションプロファイルを作成できます。 +任意: 名前、色、または browser data directory を変えたい場合は、 +独自の custom existing-session プロファイルを作成できます。 デフォルト動作: -- 組み込みの `user` プロファイルは Chrome MCP 自動接続を使用し、 +- 組み込みの `user` プロファイルは Chrome MCP auto-connect を使い、 デフォルトのローカル Google Chrome プロファイルを対象にします。 -Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファイルには `userDataDir` を使ってください: +Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファイルには `userDataDir` を使います: ```json5 { @@ -435,19 +448,19 @@ Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファ } ``` -次に、対応するブラウザで以下を行います: +次に、対応する browser 側で次を行います: -1. そのブラウザのリモートデバッグ用 inspect ページを開きます。 -2. リモートデバッグを有効にします。 -3. ブラウザを起動したままにし、OpenClaw が接続するときに接続プロンプトを承認します。 +1. その browser の inspect page for remote debugging を開きます。 +2. remote debugging を有効にします。 +3. browser を起動したままにし、OpenClaw が接続するときに接続プロンプトを承認します。 -一般的な inspect ページ: +一般的な inspect page: - Chrome: `chrome://inspect/#remote-debugging` - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -ライブ接続のスモークテスト: +ライブ接続スモークテスト: ```bash openclaw browser --browser-profile user start @@ -458,66 +471,71 @@ openclaw browser --browser-profile user snapshot --format ai 成功時の見え方: -- `status` に `driver: existing-session` と表示される -- `status` に `transport: chrome-mcp` と表示される -- `status` に `running: true` と表示される -- `tabs` に、すでに開いているブラウザタブが一覧表示される +- `status` に `driver: existing-session` が表示される +- `status` に `transport: chrome-mcp` が表示される +- `status` に `running: true` が表示される +- `tabs` に、すでに開いている browser タブが一覧表示される - `snapshot` が、選択されたライブタブから refs を返す -接続が機能しない場合の確認事項: +接続がうまくいかない場合の確認事項: -- 対象の Chromium ベースブラウザがバージョン `144+` であること -- そのブラウザの inspect ページでリモートデバッグが有効になっていること -- ブラウザが接続同意プロンプトを表示し、あなたがそれを承認したこと -- `openclaw doctor` は古い拡張機能ベースのブラウザ設定を移行し、 - デフォルトの自動接続プロファイル用に Chrome がローカルにインストールされていることを確認しますが、 - ブラウザ側のリモートデバッグをあなたの代わりに有効化することはできません +- 対象の Chromium ベース browser がバージョン `144+` である +- その browser の inspect page で remote debugging が有効である +- browser に接続同意プロンプトが表示され、それを承認した +- `openclaw doctor` は古い拡張機能ベースの browser config を移行し、 + デフォルト auto-connect プロファイル用に Chrome がローカルにインストールされているかを確認しますが、 + browser 側の remote debugging を代わりに有効化することはできません -エージェントでの利用: +エージェント利用: -- ユーザーのログイン済みブラウザ状態が必要な場合は `profile="user"` を使ってください。 -- カスタム既存セッションプロファイルを使う場合は、その明示的なプロファイル名を渡してください。 -- このモードを選ぶのは、ユーザーが接続プロンプトを承認できるようコンピューターの前にいる場合だけにしてください。 -- Gateway またはノードホストは `npx chrome-devtools-mcp@latest --autoConnect` を起動できます +- ユーザーのログイン済み browser 状態が必要な場合は `profile="user"` を使います。 +- custom existing-session プロファイルを使う場合は、その明示的なプロファイル名を渡してください。 +- このモードは、ユーザーがコンピューターの前にいて接続 + プロンプトを承認できる場合にのみ選んでください。 +- Gateway または node host は `npx chrome-devtools-mcp@latest --autoConnect` を起動できます -注意点: +注意: -- この経路は、サインイン済みブラウザセッション内で操作できるため、分離された `openclaw` プロファイルより高リスクです。 -- OpenClaw はこの driver でブラウザを起動しません。既存セッションにのみ接続します。 +- この経路は、サインイン済み browser セッション内で + 操作できるため、分離された `openclaw` プロファイルより高リスクです。 +- OpenClaw はこの driver では browser を起動せず、 + 既存セッションにのみ接続します。 - OpenClaw はここで公式の Chrome DevTools MCP `--autoConnect` フローを使用します。 `userDataDir` が設定されている場合、OpenClaw はそれを渡して、その明示的な - Chromium ユーザーデータディレクトリを対象にします。 -- 既存セッションのスクリーンショットは、ページキャプチャとスナップショットからの `--ref` 要素キャプチャをサポートしますが、 - CSS `--element` セレクターはサポートしません。 -- 既存セッションのページスクリーンショットは、Playwright なしで Chrome MCP を通じて動作します。 - ref ベースの要素スクリーンショット（`--ref`）もそこで動作しますが、`--full-page` は `--ref` や `--element` と組み合わせられません。 -- 既存セッションのアクションは、管理ブラウザ経路より依然として制限があります: - - `click`、`type`、`hover`、`scrollIntoView`、`drag`、`select` では、 - CSS セレクターではなくスナップショット refs が必要です - - `click` は左ボタンのみです（ボタン上書きや修飾キーは不可） + Chromium user data directory を対象にします。 +- existing-session のスクリーンショットは、snapshot からのページキャプチャと `--ref` 要素 + キャプチャをサポートしますが、CSS `--element` セレクターはサポートしません。 +- existing-session のページスクリーンショットは、Playwright なしで Chrome MCP 経由で動作します。 + ref ベースの要素スクリーンショット（`--ref`）もそこでは動作しますが、`--full-page` + は `--ref` や `--element` と組み合わせられません。 +- existing-session のアクションは、依然として managed browser + 経路より制限があります: + - `click`、`type`、`hover`、`scrollIntoView`、`drag`、`select` には + CSS セレクターではなく snapshot refs が必要です + - `click` は左ボタンのみ対応です（ボタン上書きや modifier は不可） - `type` は `slowly=true` をサポートしません。`fill` または `press` を使ってください - `press` は `delayMs` をサポートしません - `hover`、`scrollIntoView`、`drag`、`select`、`fill`、`evaluate` は - 呼び出しごとのタイムアウト上書きをサポートしません - - `select` は現在単一値のみサポートします -- 既存セッションの `wait --url` は、他のブラウザ driver と同様に完全一致、部分一致、glob パターンをサポートします。 - `wait --load networkidle` はまだサポートされていません。 -- 既存セッションのアップロードフックは `ref` または `inputRef` を必要とし、一度に 1 ファイルのみをサポートし、 - CSS `element` ターゲティングはサポートしません。 -- 既存セッションのダイアログフックはタイムアウト上書きをサポートしません。 -- 一部の機能は引き続き管理ブラウザ経路が必要で、バッチアクション、PDF エクスポート、ダウンロードのインターセプト、`responsebody` などが該当します。 -- 既存セッションはホストローカルです。Chrome が別のマシンまたは別のネットワーク名前空間にある場合は、 - 代わりにリモート CDP またはノードホストを使用してください。 + 呼び出しごとの timeout 上書きをサポートしません + - `select` は現在 1 つの値のみサポートします +- existing-session の `wait --url` は、他の browser driver と同様に完全一致、部分一致、および glob パターンをサポートします。`wait --load networkidle` はまだサポートされていません。 +- existing-session の upload hook には `ref` または `inputRef` が必要で、 + 一度に 1 ファイルのみサポートし、CSS `element` ターゲティングはサポートしません。 +- existing-session の dialog hook は timeout 上書きをサポートしません。 +- batch + actions、PDF エクスポート、ダウンロードインターセプト、`responsebody` など、一部の機能は依然として managed browser 経路を必要とします。 +- existing-session はホストローカルです。Chrome が別のマシン上、または + 別のネットワーク名前空間にある場合は、代わりに remote CDP または node host を使ってください。 -## 分離の保証 +## 分離保証 -- **専用のユーザーデータディレクトリ**: あなたの個人用ブラウザプロファイルには決して触れません。 -- **専用ポート**: 開発ワークフローとの衝突を防ぐため `9222` を避けます。 -- **決定論的なタブ制御**: 「最後のタブ」ではなく `targetId` でタブを対象にします。 +- **専用 user data dir**: 個人用 browser プロファイルには決して触れません。 +- **専用ポート**: 開発ワークフローとの衝突を避けるため `9222` を使いません。 +- **決定論的タブ制御**: 「最後のタブ」ではなく `targetId` でタブを対象にします。 -## ブラウザの選択 +## browser 選択 -ローカル起動時、OpenClaw は利用可能な最初のものを選びます: +ローカル起動時、OpenClaw は利用可能なもののうち最初のものを選びます: 1. Chrome 2. Brave @@ -533,7 +551,7 @@ openclaw browser --browser-profile user snapshot --format ai - Linux: `google-chrome`、`brave`、`microsoft-edge`、`chromium` などを探します。 - Windows: 一般的なインストール場所を確認します。 -## 制御 API（オプション） +## 制御 API（任意） ローカル統合専用として、Gateway は小さな loopback HTTP API を公開します: @@ -552,22 +570,22 @@ openclaw browser --browser-profile user snapshot --format ai すべてのエンドポイントは `?profile=` を受け付けます。 -shared-secret Gateway 認証が設定されている場合、ブラウザ HTTP ルートでも認証が必要です: +shared-secret gateway auth が設定されている場合、browser HTTP ルートにも auth が必要です: - `Authorization: Bearer ` -- `x-openclaw-password: ` またはそのパスワードを使う HTTP Basic 認証 +- `x-openclaw-password: ` またはその password を使う HTTP Basic auth -注意点: +注意: -- このスタンドアロン loopback ブラウザ API は `trusted-proxy` や - Tailscale Serve の identity ヘッダーを利用**しません**。 -- `gateway.auth.mode` が `none` または `trusted-proxy` の場合、これらの loopback ブラウザ - ルートはそうした identity 付きモードを継承しません。loopback のみに保ってください。 +- このスタンドアロン loopback browser API は、trusted-proxy や + Tailscale Serve の identity headers を**利用しません**。 +- `gateway.auth.mode` が `none` または `trusted-proxy` の場合、これらの loopback browser + ルートはそれらの identity-bearing モードを継承しません。loopback 専用に保ってください。 -### `/act` エラー契約 +### `/act` のエラー契約 -`POST /act` は、ルートレベルのバリデーションと -ポリシー失敗に対して構造化されたエラーレスポンスを使用します: +`POST /act` は、ルートレベルの検証および +ポリシー失敗に対して構造化エラーレスポンスを使います: ```json { "error": "", "code": "ACT_*" } @@ -575,74 +593,71 @@ shared-secret Gateway 認証が設定されている場合、ブラウザ HTTP 現在の `code` 値: -- `ACT_KIND_REQUIRED` (HTTP 400): `kind` が欠落しているか、認識されません。 -- `ACT_INVALID_REQUEST` (HTTP 400): アクションペイロードの正規化またはバリデーションに失敗しました。 -- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): サポートされていないアクション種別で `selector` が使用されました。 -- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate`（または `wait --fn`）が設定で無効になっています。 -- `ACT_TARGET_ID_MISMATCH` (HTTP 403): トップレベルまたはバッチ化された `targetId` がリクエスト対象と競合しています。 -- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): このアクションは既存セッションプロファイルではサポートされていません。 +- `ACT_KIND_REQUIRED`（HTTP 400）: `kind` が欠落しているか認識されません。 +- `ACT_INVALID_REQUEST`（HTTP 400）: アクションペイロードの正規化または検証に失敗しました。 +- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）: 未対応のアクション種別で `selector` が使用されました。 +- `ACT_EVALUATE_DISABLED`（HTTP 403）: config により `evaluate`（または `wait --fn`）が無効です。 +- `ACT_TARGET_ID_MISMATCH`（HTTP 403）: トップレベルまたは batch の `targetId` がリクエスト対象と競合しています。 +- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）: existing-session プロファイルではそのアクションはサポートされていません。 -その他のランタイム失敗では、`code` フィールドなしの -`{ "error": "" }` が返ることもあります。 +その他のランタイム失敗では、依然として `code` +フィールドなしの `{ "error": "" }` が返る場合があります。 ### Playwright 要件 一部の機能（navigate/act/AI snapshot/role snapshot、要素スクリーンショット、 -PDF）には Playwright が必要です。Playwright がインストールされていない場合、 -これらのエンドポイントは明確な 501 エラーを返します。 +PDF）には Playwright が必要です。Playwright がインストールされていない場合、それらのエンドポイントは +明確な 501 エラーを返します。 Playwright なしでも動作するもの: - ARIA スナップショット -- タブごとの CDP WebSocket が利用可能な場合の、管理 `openclaw` ブラウザのページスクリーンショット -- `existing-session` / Chrome MCP プロファイルのページスクリーンショット -- スナップショット出力からの `existing-session` の ref ベーススクリーンショット（`--ref`） +- タブごとの CDP + WebSocket が利用可能な場合の managed `openclaw` browser 向けページスクリーンショット +- `existing-session` / Chrome MCP プロファイル向けページスクリーンショット +- snapshot 出力からの `existing-session` ref ベーススクリーンショット（`--ref`） 引き続き Playwright が必要なもの: - `navigate` - `act` -- AI スナップショット / role スナップショット +- AI snapshots / role snapshots - CSS セレクター要素スクリーンショット（`--element`） -- ブラウザ全体の PDF エクスポート +- 完全な browser PDF エクスポート 要素スクリーンショットでは `--full-page` も拒否されます。このルートは `fullPage is not supported for element screenshots` を返します。 -`Playwright is not available in this gateway build` と表示された場合は、完全な +Playwright is not available in this gateway build` と表示された場合は、完全な Playwright パッケージ（`playwright-core` ではなく）をインストールして Gateway を再起動するか、 -ブラウザサポート付きで OpenClaw を再インストールしてください。 +browser サポート付きで OpenClaw を再インストールしてください。 #### Docker での Playwright インストール -Gateway が Docker 上で動作している場合は、`npx playwright` を避けてください（npm override の競合があります）。 -代わりに、同梱の CLI を使ってください: - -```bash -docker compose run --rm openclaw-cli \ - node /app/node_modules/playwright-core/cli.js install chromium -``` - -ブラウザダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH`（たとえば +Gateway が Docker で動作している場合は、`npx playwright` を避けてください（npm override の競合があります）。 +代わりにバンドルされた CLI を使います: +__OC_I18N_900012__ +browser ダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH`（たとえば `/home/node/.cache/ms-playwright`）を設定し、`/home/node` が -`OPENCLAW_HOME_VOLUME` または bind mount で永続化されていることを確認してください。[Docker](/ja-JP/install/docker) を参照してください。 +`OPENCLAW_HOME_VOLUME` または bind mount によって永続化されていることを確認してください。[Docker](/install/docker) を参照してください。 ## 仕組み（内部） -高レベルのフロー: +高レベルの流れ: -- 小さな**制御サーバー**が HTTP リクエストを受け付けます。 -- **CDP** を介して Chromium ベースのブラウザ（Chrome/Brave/Edge/Chromium）に接続します。 -- 高度な操作（クリック/入力/スナップショット/PDF）には、CDP の上で **Playwright** を使用します。 +- 小さな **control server** が HTTP リクエストを受け付けます。 +- **CDP** を通じて Chromium ベース browser（Chrome/Brave/Edge/Chromium）に接続します。 +- 高度なアクション（クリック/入力/スナップショット/PDF）には、 + CDP 上で **Playwright** を使います。 - Playwright がない場合は、Playwright 非依存の操作のみ利用できます。 -この設計により、ローカル/リモートのブラウザやプロファイルを切り替えられる一方で、 -エージェントは安定した決定論的インターフェース上で動作できます。 +この設計により、エージェントは安定した決定論的インターフェース上に保たれつつ、 +ローカル/リモート browser やプロファイルを切り替えられます。 ## CLI クイックリファレンス -すべてのコマンドは、特定のプロファイルを対象にするために `--browser-profile ` を受け付けます。 -すべてのコマンドは、機械可読な出力（安定したペイロード）のために `--json` も受け付けます。 +すべてのコマンドは、特定プロファイルを対象にするため `--browser-profile ` を受け付けます。 +すべてのコマンドは、機械可読な出力（安定したペイロード）のため `--json` も受け付けます。 基本: @@ -675,9 +690,10 @@ docker compose run --rm openclaw-cli \ ライフサイクルに関する注意: -- attach-only および remote CDP プロファイルでは、テスト後の適切なクリーンアップコマンドは - 依然として `openclaw browser stop` です。これは、基盤となるブラウザを終了する代わりに、 - アクティブな制御セッションを閉じ、一時的なエミュレーション上書きを解除します。 +- attach-only およびリモート CDP プロファイルでは、テスト後のクリーンアップコマンドとしても + `openclaw browser stop` が正しい選択です。これは + 基盤となる browser を終了するのではなく、アクティブな制御セッションを閉じて + 一時的なエミュレーション上書きを解除します。 - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` @@ -726,172 +742,145 @@ docker compose run --rm openclaw-cli \ - `openclaw browser set locale en-US` - `openclaw browser set device "iPhone 14"` -注意点: +注意: -- `upload` と `dialog` は**事前待機**呼び出しです。ファイル選択ダイアログやダイアログを - 発生させる click/press の前に実行してください。 -- ダウンロードとトレースの出力パスは OpenClaw の一時ルートに制限されます: +- `upload` と `dialog` は **準備用** 呼び出しです。ファイル選択やダイアログを引き起こす click/press + の前に実行してください。 +- ダウンロードおよび trace の出力パスは OpenClaw の temp ルートに制限されます: - traces: `/tmp/openclaw`（フォールバック: `${os.tmpdir()}/openclaw`） - downloads: `/tmp/openclaw/downloads`（フォールバック: `${os.tmpdir()}/openclaw/downloads`） -- アップロードパスは OpenClaw の一時アップロードルートに制限されます: +- upload パスも OpenClaw の temp uploads ルートに制限されます: - uploads: `/tmp/openclaw/uploads`（フォールバック: `${os.tmpdir()}/openclaw/uploads`） -- `upload` は、`--input-ref` または `--element` によってファイル input を直接設定することもできます。 +- `upload` は `--input-ref` または `--element` によってファイル入力を直接設定することもできます。 - `snapshot`: - - `--format ai`（Playwright がインストールされている場合のデフォルト）: 数値 refs を含む AI スナップショットを返します（`aria-ref=""`）。 - - `--format aria`: アクセシビリティツリーを返します（refs なし。調査専用）。 - - `--efficient`（または `--mode efficient`）: コンパクトな role スナップショットのプリセットです（interactive + compact + depth + lower maxChars）。 - - 設定のデフォルト（ツール/CLI のみ）: 呼び出し側が mode を渡さないときに efficient スナップショットを使うには、`browser.snapshotDefaults.mode: "efficient"` を設定してください（[Gateway configuration](/ja-JP/gateway/configuration-reference#browser) を参照）。 - - role スナップショットオプション（`--interactive`、`--compact`、`--depth`、`--selector`）は、`ref=e12` のような refs を持つ role ベーススナップショットを強制します。 - - `--frame "