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

chore(i18n): refresh ja-JP translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-11 02:54:04 +00:00
parent 526cc05aac
commit 59817de79c
31 changed files with 7499 additions and 5792 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
docs/ja-JP/automation/cron-jobs.md
View File

@ -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 <job-id>
```
@ -41,80 +41,83 @@ openclaw cron runs --id <job-id>
- Cronは**Gatewayプロセス内**で実行されます（モデル内ではありません）。
- ジョブは`~/.openclaw/cron/jobs.json`に永続化されるため、再起動してもスケジュールは失われません。
- すべてのcron実行では[バックグラウンドタスク](/automation/tasks)レコードが作成されます。
- すべてのcron実行で[バックグラウンドタスク](/ja-JP/automation/tasks)レコードが作成されます。
- 1回限りのジョブ（`--at`）は、デフォルトで成功後に自動削除されます。
- 分離されたcron実行では、実行完了時にその`cron:<jobId>`セッション用に追跡されているブラウザータブやプロセスをベストエフォートで閉じるため、切り離されたブラウザー自動化によって孤立プロセスが残ることを防ぎます。
- 分離されたcron実行では、古い確認応答の返信も防ぎます。最初の結果が単なる中間ステータス更新（`on it`、`pulling everything together`、および類似のヒント）であり、最終回答を担当する子孫subagent実行がまだ存在しない場合、OpenClawは配信前に実際の結果を得るためにもう一度プロンプトを送ります。
- 分離されたcron実行では、実行完了時にその`cron:<jobId>`セッション用の追跡対象ブラウザタブやプロセスをベストエフォートで閉じるため、切り離されたブラウザ自動化によって孤立プロセスが残りません。
- 分離されたcron実行では、古い確認応答返信も防止されます。最初の結果が単なる中間ステータス更新（`on it`、`pulling everything together`、および同様のヒント）であり、最終回答を担当する子孫subagent実行がまだ存在しない場合、OpenClawは配信前に実際の結果を得るためにもう一度再プロンプトします。
cronのタスク照合はランタイムが管理します。古い子セッション行がまだ存在していても、cronランタイムがそのジョブを実行中として追跡している間は、アクティブなcronタスクは有効なままです。ランタイムがそのジョブの所有を終了し、5分間の猶予時間が過ぎると、メンテナンスによってタスクは`lost`としてマークされる場合があります。
<a id="maintenance"></a>
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:<jobId>` | レポート、バックグラウンド作業 |
| 現在のセッション | `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:<id>`、`user:<id>`）を使用する必要があります。
チャネル配信には`--announce --channel telegram --to "-1001234567890"`を使用します。Telegramフォーラムトピックには`-1001234567890:topic:123`を使用します。Slack/Discord/Mattermostの対象には、明示的なプレフィックス（`channel:<id>`、`user:<id>`）を使用する必要があります。
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 <token>`（推奨）
- `x-openclaw-token: <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/\<name\>）
カスタムフック名は、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 <project-id>
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 <jobId> --limit 50
# ジョブを削除
openclaw cron remove <jobId>
# Agent選択（マルチagentセットアップ）
# エージェント選択（マルチエージェント構成）
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent
```
@ -309,9 +312,9 @@ openclaw cron edit <jobId> --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 <jobId> --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 <jobId> --due`で確認され、そのジョブがまだ期限前だったことを意味します。
- Gatewayが継続的に実行されていることを確認してください。
- `cron`スケジュールでは、タイムゾーン（`--tz`）とホストのタイムゾーンを確認してください。
- 実行出力の`reason: not-due`は、手動実行が`openclaw cron run <jobId> --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) — タイムゾーン設定

184
docs/ja-JP/automation/hooks.md
View File

@ -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**: `<workspace>/hooks/`（エージェントごと。明示的に有効化するまでデフォルトでは無効）
1. **同梱フック**: OpenClawに同梱されているもの
2. **プラグインフック**: インストール済みプラグインに同梱されているフック
3. **管理フック**: `~/.openclaw/hooks/`（ユーザーがインストールした、ワークスペース間で共有されるもの）。`hooks.internal.load.extraDirs`の追加ディレクトリもこの優先順位を共有します。
4. **ワークスペースフック**: `<workspace>/hooks/`（エージェント単位、明示的に有効化されるまでデフォルトで無効）
Workspace hooksは新しいhook名を追加できますが、同じ名前の同梱、managed、またはplugin提供hookを上書きすることはできません。
ワークスペースフックは新しいフック名を追加できますが、同じ名前の同梱、管理、またはプラグイン提供フックを上書きすることはできません。
### hookパック
### フックパック
hookパックは、`package.json`内の`openclaw.hooks`を通じてhooksを公開するnpmパッケージです。次のようにインストールします。
フックパックは、`package.json`の`openclaw.hooks`を通じてフックをエクスポートするnpmパッケージです。次のコマンドでインストールします。
```bash
openclaw plugins install <path-or-spec>
```
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` | セッションコンテキストを`<workspace>/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 <hook-name>
```
<a id="session-memory"></a>
### session-memoryの詳細
直近15件のユーザー/assistantメッセージを抽出し、LLMで説明的なファイル名スラッグを生成して、`<workspace>/memory/YYYY-MM-DD-slug.md`に保存します。`workspace.dir`が設定されている必要があります。
直近15件のuser/assistantメッセージを抽出し、LLMで説明的なファイル名slugを生成して、`<workspace>/memory/YYYY-MM-DD-slug.md`に保存します。`workspace.dir`の設定が必要です。
<a id="bootstrap-extra-files"></a>
### bootstrap-extra-filesの設定
@ -192,13 +196,25 @@ openclaw hooks enable <hook-name>
}
```
パスはワークスペースを基準に解決されます。認識される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
<a id="command-logger"></a>
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`に記録します。
<a id="boot-md"></a>
### 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ごとの環境変数:
```
<Note>
従来の`hooks.internal.handlers`配列設定形式も後方互換性のため引き続きサポートされていますが、新しいhooksでは検出ベースのシステムを使用してください。
従来の`hooks.internal.handlers`配列設定形式も後方互換性のため引き続きサポートされていますが、新しいフックでは検出ベースのシステムを使用してください。
</Note>
## CLIリファレンス
```bash
# すべてのhooksを一覧表示（--eligible、--verbose、または--jsonを追加可能）
# すべてのフックを一覧表示（--eligible、--verbose、または--jsonを追加可能）
openclaw hooks list
# hookの詳細情報を表示
# フックの詳細情報を表示
openclaw hooks info <hook-name>
# 適格性の概要を表示
@ -270,25 +286,25 @@ openclaw hooks disable <hook-name>
## ベストプラクティス
- **ハンドラーは高速に保つ。** 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)

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

@ -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 をビルド
```

147
docs/ja-JP/concepts/agent-loop.md
View File

@ -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` タイムアウト（待機のみで、エージェント自体は停止しません）
## 関連

669
docs/ja-JP/concepts/model-providers.md
View File

@ -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 <provider/model>`。
- フォールバックのランタイムルール、クールダウンプローブ、セッション上書き永続化は
[/concepts/model-failover](/ja-JP/concepts/model-failover)に記載されています。
- CLIヘルパー: `openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- フォールバックの実行時ルール、クールダウンプローブ、セッション上書きの永続化は、[/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.<id>`設定を
プロバイダーが正規化。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.<id>`設定を正規化する。
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_<PROVIDER>_KEY`（単一のlive override、最優先）
- 複数キーは以下で設定します:
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（単一のライブ上書き、最優先）
- `<PROVIDER>_API_KEYS`（カンマまたはセミコロン区切りのリスト）
- `<PROVIDER>_API_KEY`（プライマリキー）
- `<PROVIDER>_API_KEY_*`（番号付きリスト、例: `<PROVIDER>_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/<model>"].params.transport`で行います（`"sse"`, `"websocket"`, または`"auto"`）
- OpenAI Responses WebSocket warm-upは、`params.openaiWsWarmup`（`true`/`false`）によりデフォルトで有効です
- OpenAI priority processingは、`agents.defaults.models["openai/<model>"].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/<model>"].params.transport`（`"sse"`、`"websocket"`、または`"auto"`）で行います
- OpenAI Responses WebSocketウォームアップは、`params.openaiWsWarmup`（`true`/`false`）によりデフォルトで有効です
- OpenAI優先処理は`agents.defaults.models["openai/<model>"].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/<model>"].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/<model>"].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/<model>"].params.cachedContent`
（または旧式の`cached_content`）も受け付け、プロバイダーネイティブな
`cachedContents/...`ハンドルを転送します。GeminiのキャッシュヒットはOpenClawの`cacheRead`として表示されます
- 直接Gemini実行では、`agents.defaults.models["google/<model>"].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/<model>"].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.<id>`エントリーを使用してください。
### 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) — プロバイダーごとの設定ガイド

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

@ -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 <count>` を使用し、直列実行には `--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=<level>` をインラインで指定します。`--thinking <level>` は引き続きグローバルなフォールバックを設定し、古い `--model-thinking <provider/model=level>` 形式も互換性のため維持されています。
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=<level>` をインラインで指定します。`--thinking <level>` は引き続きグローバルなフォールバックを設定し、旧形式の `--model-thinking <provider/model=level>` も互換性のために維持されています。
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` になります。
## 関連ドキュメント

159
docs/ja-JP/gateway/cli-backends.md
View File

@ -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セッションを再利用します。
<Note>
同梱のAnthropic `claude-cli`バックエンドが再びサポートされました。Anthropicのスタッフから、OpenClawスタイルのClaude CLI利用は再び許可されると案内があったため、Anthropicが新しいポリシーを公開しない限り、OpenClawはこの連携における`claude -p`の利用を公認済みとして扱います。
バンドルされたAnthropicの`claude-cli`バックエンドが再びサポートされました。Anthropicのスタッフから、OpenClawスタイルのClaude CLI使用は再び許可されていると案内されたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはこの統合における`claude -p`の使用を認可済みとして扱います。
</Note>
同梱の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.<id>`内のユーザー設定は、引き続きプラグインのデフォルトを上書きします。
- バックエンド固有の設定クリーンアップは、オプションの`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がファイルパスをサポートしていることも確認してください）。

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

File diff suppressed because it is too large Load Diff

373
docs/ja-JP/gateway/configuration.md
View File

@ -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` から任意の <Tooltip tip="JSON5 はコメントと末尾カンマをサポートします">**JSON5**</Tooltip> 設定を読み込みます。
OpenClaw は、`~/.openclaw/openclaw.json` から任意の <Tooltip tip="JSON5 はコメントと末尾カンマをサポートします">**JSON5**</Tooltip> 設定を読み込みます。
ファイルが存在しない場合、OpenClaw は安全なデフォルト設定を使用します。設定を追加する一般的な理由は次のとおりです。
ファイルが存在しない場合、OpenClaw は安全なデフォルト値を使用します。設定を追加する一般的な理由は次のとおりです。
- チャンネルを接続し、誰がボットにメッセージを送れるかを制御する
- モデル、ツール、サンドボックス化、または自動化（cron、hooks）を設定する
- セッション、メディア、ネットワーク、または UI を調整する
- モデル、ツール、サンドボックス化、自動化（cron、hooks）を設定する
- セッション、メディア、ネットワーク、UI を調整する
利用可能なすべてのフィールドについては、[完全なリファレンス](/ja-JP/gateway/configuration-reference)を参照してください。
利用可能なすべてのフィールドについては、[完全なリファレンス](/ja-JP/gateway/configuration-reference) を参照してください。
<Tip>
**設定が初めてですか？** 対話形式のセットアップには `openclaw onboard` から始めるか、完全なコピーペースト用設定を掲載した[設定例](/ja-JP/gateway/configuration-examples)ガイドを確認してください。
**設定が初めてですか？** 対話型セットアップには `openclaw onboard` から始めるか、完全なコピー＆ペースト用設定をまとめた [設定例](/ja-JP/gateway/configuration-examples) ガイドを確認してください。
</Tip>
## 最小設定
## 最小構成
```json5
// ~/.openclaw/openclaw.json
@ -45,8 +45,8 @@ OpenClaw は `~/.openclaw/openclaw.json` から任意の <Tooltip tip="JSON5 は
<Tabs>
<Tab title="対話型ウィザード">
```bash
openclaw onboard # full onboarding flow
openclaw configure # config wizard
openclaw onboard # 完全なオンボーディングフロー
openclaw configure # 設定ウィザード
```
</Tab>
<Tab title="CLI（ワンライナー）">
@ -58,58 +58,46 @@ OpenClaw は `~/.openclaw/openclaw.json` から任意の <Tooltip tip="JSON5 は
</Tab>
<Tab title="Control UI">
[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 つのパスにスコープされたスキーマノードと、
その直下の子要約を取得できます。
</Tab>
<Tab title="直接編集">
`~/.openclaw/openclaw.json` を直接編集します。Gateway はファイルを監視し、自動的に変更を適用します（[ホットリロード](#config-hot-reload)を参照）。
`~/.openclaw/openclaw.json` を直接編集します。Gateway はこのファイルを監視し、変更を自動的に適用します（[ホットリロード](#config-hot-reload) を参照）。
</Tab>
</Tabs>
## 厳格な検証
<Warning>
OpenClaw は、スキーマに完全に一致する設定のみを受け付けます。不明なキー、不正な型、または無効な値があると、Gateway は**起動を拒否**します。唯一のルートレベル例外は `$schema`（文字列）で、エディターが JSON Schema メタデータを付与できるようにするためのものです。
OpenClaw は、スキーマに完全に一致する設定のみを受け入れます。不明なキー、不正な型、無効な値があると、Gateway は**起動を拒否**します。ルートレベルの唯一の例外は `$schema`（文字列）で、エディターが JSON Schema メタデータを付与できるようにするためのものです。
</Warning>
スキーマツールに関する注意：
スキーマツールに関する注記:
- `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`）を実行します
## 一般的なタスク
<AccordionGroup>
<Accordion title="チャンネルを設定する（WhatsApp、Telegram、Discord など）">
各チャンネルには、`channels.<provider>` の下に独自の設定セクションがあります。設定手順については、各チャンネル専用ページを参照してください。
<Accordion title="チャンネルをセットアップする（WhatsApp、Telegram、Discord など）">
各チャンネルには、`channels.<provider>` の下に専用の設定セクションがあります。セットアップ手順については、各チャンネル専用ページを参照してください。
- [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) を参照してください。
</Accordion>
<Accordion title="誰がボットにメッセージを送れるかを制御する">
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) を参照してください。
</Accordion>
<Accordion title="グループチャットのメンション制御を設定する">
グループメッセージはデフォルトで**メンション必須**です。エージェントごとにパターンを設定します。
<Accordion title="グループチャットのメンションゲートを設定する">
グループメッセージはデフォルトで**メンション必須**です。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) を参照してください。
</Accordion>
<Accordion title="エージェントごとに Skills を制限する">
共通のベースラインには `agents.defaults.skills` を使い、その後
`agents.list[].skills` で特定の
エージェントを上書きします。
<Accordion title="agent ごとに 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) を参照してください。
</Accordion>
<Accordion title="gateway のチャンネルヘルス監視を調整する">
停滞しているように見えるチャンネルを gateway がどの程度積極的に再起動するかを制御します。
<Accordion title="Gateway のチャンネルヘルス監視を調整する">
stale に見えるチャンネルを gateway がどの程度積極的に再起動するかを制御します。
```json5
{
@ -262,19 +249,19 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け
```
- ヘルス監視による再起動をグローバルに無効化するには、`gateway.channelHealthCheckMinutes: 0` を設定します。
- `channelStaleEventThresholdMinutes` は、チェック間隔以上にする必要があります。
- グローバル監視を無効にせずに特定のチャンネルまたはアカウントの自動再起動を無効にするには、`channels.<provider>.healthMonitor.enabled` または `channels.<provider>.accounts.<id>.healthMonitor.enabled` を使用します。
- 運用上のデバッグについては[Health Checks](/ja-JP/gateway/health)を、すべてのフィールドについては[完全なリファレンス](/ja-JP/gateway/configuration-reference#gateway)を参照してください。
- `channelStaleEventThresholdMinutes` は、チェック間隔以上である必要があります。
- グローバル監視を無効にせずに 1 つのチャンネルまたはアカウントだけ自動再起動を無効化するには、`channels.<provider>.healthMonitor.enabled` または `channels.<provider>.accounts.<id>.healthMonitor.enabled` を使用します。
- 運用上のデバッグについては [Health Checks](/ja-JP/gateway/health) を、すべてのフィールドについては [完全なリファレンス](/ja-JP/gateway/configuration-reference#gateway) を参照してください。
</Accordion>
<Accordion title="セッションとリセットを設定する">
セッションは、会話の継続性と分離を制御します。
セッションは会話の継続性と分離を制御します。
```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) を参照してください。
</Accordion>
<Accordion title="サンドボックス化を有効にする">
エージェントセッションを分離された 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) を参照してください。
</Accordion>
<Accordion title="公式 iOS ビルド向けの relay-backed push を有効にする">
relay-backed push は `openclaw.json` で設定します。
<Accordion title="公式 iOS ビルド向けに relay ベースの push を有効にする">
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) を参照してください。
</Accordion>
@ -389,10 +376,10 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け
}
```
- `every`: 期間文字列（`30m`、`2h`）。無効にするには `0m` を設定します。
- `target`: `last` | `none` | `<channel-id>`（例：`discord`、`matrix`、`telegram`、または `whatsapp`）
- `directPolicy`: DM 形式の heartbeat ターゲット向けの `allow`（デフォルト）または `block`
- 完全なガイドについては[Heartbeat](/ja-JP/gateway/heartbeat)を参照してください。
- `every`: 期間文字列（`30m`、`2h`）。無効化するには `0m` を設定します。
- `target`: `last` | `none` | `<channel-id>`（例: `discord`、`matrix`、`telegram`、`whatsapp`）
- `directPolicy`: DM スタイルの heartbeat target に対して `allow`（デフォルト）または `block`
- 完全なガイドについては [Heartbeat](/ja-JP/gateway/heartbeat) を参照してください。
</Accordion>
@ -411,9 +398,9 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け
}
```
- `sessionRetention`: 完了した分離実行セッションを `sessions.json` から削除します（デフォルトは `24h`、無効にするには `false` を設定）。
- `sessionRetention`: 完了した分離実行セッションを `sessions.json` から削除します（デフォルトは `24h`、無効化するには `false` を設定）。
- `runLog`: `cron/runs/<jobId>.jsonl` をサイズと保持行数で削除します。
- 機能概要と CLI の例については[Cron jobs](/ja-JP/automation/cron-jobs)を参照してください。
- 機能概要と CLI 例については [Cron jobs](/ja-JP/automation/cron-jobs) を参照してください。
</Accordion>
@ -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) を参照してください。
</Accordion>
<Accordion title="マルチエージェントルーティングを設定する">
ワークスペースとセッションを分離して、複数の独立したエージェントを実行します。
別々の 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) を参照してください。
</Accordion>
@ -490,28 +477,28 @@ OpenClaw は、スキーマに完全に一致する設定のみを受け付け
}
```
- **単一ファイル**：含まれているオブジェクトを置き換えます
- **ファイル配列**：順番にディープマージされます（後勝ち）
- **兄弟キー**：include の後にマージされます（含まれた値を上書き）
- **ネストされた include**：最大 10 階層までサポート
- **相対パス**：include 元ファイルを基準に解決されます
- **エラー処理**：ファイル欠落、解析エラー、循環 include に対して明確なエラーを表示します
- **単一ファイル**: そのオブジェクト全体を置き換えます
- **ファイル配列**: 順番に deep-merge されます（後勝ち）
- **兄弟キー**: include の後にマージされます（include された値を上書き）
- **ネストした include**: 最大 10 階層までサポート
- **相対パス**: include 元ファイルを基準に解決されます
- **エラーハンドリング**: ファイル欠如、パースエラー、循環 include に対して明確なエラーを返します
</Accordion>
</AccordionGroup>
## 設定ホットリロード
## 設定のホットリロード
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` | **はい** |
<Note>
`gateway.reload` と `gateway.remote` は例外で、これらを変更しても**再起動は発生しません**。
`gateway.reload` と `gateway.remote` は例外です。これらの変更では**再起動は発生しません**。
</Note>
## 設定 RPC（プログラムによる更新）
## Config RPC（プログラムによる更新）
<Note>
コントロールプレーン書き込み 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` を返します。
</Note>
安全な / デフォルトのフロー：
安全なデフォルトフロー:
- `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` を優先してください。
<AccordionGroup>
<Accordion title="config.apply（完全置換）">
設定全体を検証して書き込み、1 ステップで Gateway を再起動します。
設定全体を検証して書き込み、Gateway を 1 ステップで再起動します。
<Warning>
`config.apply` は**設定全体**を置き換えます。部分更新には `config.patch` を、単一キーには `openclaw config set` を使用してください。
</Warning>
パラメータ：
パラメータ:
- `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": "<hash>",
@ -588,16 +575,16 @@ Gateway は `~/.openclaw/openclaw.json` を監視し、自動的に変更を適
</Accordion>
<Accordion title="config.patch（部分更新）">
部分更新を既存の設定へマージします（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 を読み込み
```
<Accordion title="シェル env のインポート（任意）">
有効な場合で、想定されるキーが設定されていないと、OpenClaw はログインシェルを実行して不足しているキーのみをインポートします。
有効な場合、期待されるキーが設定されていないと、OpenClaw はログインシェルを実行し、不足しているキーのみをインポートします。
```json5
{
@ -641,7 +628,7 @@ OpenClaw は親プロセスに加えて、以下から env vars を読み込み
}
```
Env var の同等設定：`OPENCLAW_LOAD_SHELL_ENV=1`
環境変数での同等設定: `OPENCLAW_LOAD_SHELL_ENV=1`
</Accordion>
<Accordion title="設定値での env var 置換">
@ -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"`
</Accordion>
<Accordion title="Secret refs（env、file、exec）">
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) に一覧があります。
</Accordion>
完全な優先順位とソースについては、[Environment](/ja-JP/help/environment)を参照してください。
優先順位と取得元の完全な説明については [Environment](/ja-JP/help/environment) を参照してください。
## 完全なリファレンス

334
docs/ja-JP/gateway/heartbeat.md
View File

@ -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 | <channel id>（コアまたはプラグイン、例: "bluebubbles"）
lightContext: false, // デフォルト: false。true の場合、ワークスペース bootstrap ファイルから HEARTBEAT.md のみを保持
isolatedSession: false, // デフォルト: false。true の場合、各 heartbeat を新しいセッションで実行（会話履歴なし）
target: "last", // デフォルト: none | オプション: last | none | <channel id>（コアまたは 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.<channel>.heartbeat` はチャネルデフォルトを上書きします。
- `channels.<channel>.accounts.<id>.heartbeat`（マルチアカウントチャネル）はチャネル単位設定を上書きします。
- `channels.<channel>.accounts.<id>.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 には `<chatId>:topic:<messageThreadId>` を使用します。
- `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 には `<chatId>:topic:<messageThreadId>` を使用します。
- `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:<id>:<mainKey>`）で実行され、
`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) — 自動化の問題をデバッグする方法

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

@ -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ペイロード
（`<tool_call>...</tool_call>`、`<function_call>...</function_call>`、
`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`、
および切り詰められたツール呼び出しブロックを含む）と、
漏れ出した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>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`、および切り詰められた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.<skillKey>` 値をパッチします。
- 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.<skillKey>`値をパッチします。
## 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スキーマで定義されています。

1258
docs/ja-JP/gateway/security/index.md
View File

File diff suppressed because it is too large Load Diff

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

@ -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 <provider/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.<provider>.models[].compat.requiresStringContent: true` を設定する。
- 直接の小さなリクエストは成功するが、OpenClaw のエージェント実行はバックエンド/モデルのクラッシュで失敗する（たとえば一部の `inferrs` ビルド上の Gemma） → OpenClaw のトランスポートはすでに正しい可能性が高く、バックエンドがより大きいエージェントランタイムのプロンプト形状で失敗している。
- ツールを無効にすると失敗は減るが消えない → ツールスキーマが負荷の一因ではあったが、残っている問題は依然として上流のモデル/サーバー容量かバックエンドバグである。
- `messages[...].content: invalid type: sequence, expected a string` → バックエンドが構造化されたChat Completionsのcontent partsを拒否している。修正: `models.providers.<provider>.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 <requestId>` を実行する。 |
| `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 <requestId>` を実行する。 |
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 "<name>" 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; '<feature>' 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 <name>` を実行し、アクティブな制御セッションを閉じて、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 "<name>" 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; '<feature>' 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 <name>` を実行して、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

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

File diff suppressed because it is too large Load Diff

239
docs/ja-JP/help/troubleshooting.md
View File

@ -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.<provider>.models[].compat.requiresStringContent: true` を設定してください。
2. それでも OpenClaw のエージェントターンでのみバックエンドが失敗する場合は、
`models.providers.<provider>.models[].compat.supportsTools: false` を設定して再試行してください。
3. 小さな直接呼び出しは依然として動作するのに、より大きな OpenClaw プロンプトでバックエンドがクラッシュする場合は、
残る問題を上流のモデル / サーバーの制限として扱い、詳細な手順に進んでください:
1. エラーに `messages[].content` が文字列を期待していると出る場合は、
`models.providers.<provider>.models[].compat.requiresStringContent: true` を設定します。
2. それでも OpenClaw の agent ターンでのみバックエンドが失敗する場合は、
`models.providers.<provider>.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 <package>` を再度実行します。
2. エントリをビルド済み runtime ファイル（通常は `./dist/index.js`）に向けます。
3. plugin を再公開し、`openclaw plugins install <package>` を再実行します。
例:
@ -85,9 +87,9 @@ OpenClaw が現在受け付けない古い形式を使っています。
}
```
参考: [プラグインアーキテクチャ](/ja-JP/plugins/architecture)
参考: [Plugin architecture](/ja-JP/plugins/architecture)
## 決定木
## デシジョンツリー
```mermaid
flowchart TD
@ -110,7 +112,7 @@ flowchart TD
```
<AccordionGroup>
<Accordion title="返信がない">
<Accordion title="応答がない">
```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
</Accordion>
<Accordion title="Dashboard または Control UI が接続できない">
<Accordion title="Dashboard または Control UI に接続できない">
```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
</Accordion>
<Accordion title="Gateway が起動しない、またはサービスはインストール済みだが動作していない">
<Accordion title="Gateway が起動しない、または service はインストール済みだが動作していない">
```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
</Accordion>
<Accordion title="チャネルは接続するがメッセージが流れない">
<Accordion title="Channel は接続するがメッセージが流れない">
```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
</Accordion>
<Accordion title="Cron または heartbeat が起動しない、または配信されない">
<Accordion title="Cron または heartbeat が発火しなかった、または配信されなかった">
```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)
</Accordion>
<Accordion title="Node はペアリング済みだが、camera canvas screen exec ツールが失敗する">
<Accordion title="Node は paired だが tool の camera canvas screen exec が失敗する">
```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
</Accordion>
<Accordion title="Exec が急に承認を求めるようになった">
<Accordion title="Exec が突然 approval を求めるようになった">
```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)
</Accordion>
<Accordion title="Browser ツールが失敗する">
<Accordion title="Browser tool が失敗する">
```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 "<name>" 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 <name>` を実行して、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 "<name>" 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 <name>` を実行して、アクティブな制御セッションを閉じ、エミュレーション状態を解放します。
詳細ページ:
@ -378,6 +380,7 @@ flowchart TD
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/ja-JP/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
</Accordion>
</AccordionGroup>
## 関連
@ -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 の問題

488
docs/ja-JP/plugins/codex-harness.md Normal file
View File

@ -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/<model>` に設定しても、
バンドルされた `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 <thread-id>` は、現在の 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)

346
docs/ja-JP/plugins/manifest.md
View File

@ -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 <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.<id>`で使われます。 |
| `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<string, string[]>` | OpenClawがプラグインコードを読み込まずに確認できる、軽量なprovider-auth環境変数メタデータです。 |
| `providerAuthAliases` | No | `Record<string, string>` | 認証参照に別のprovider idを再利用すべきprovider idです。たとえば、ベースproviderのAPIキーやauth profileを共有するコーディングproviderなどです。 |
| `channelEnvVars` | No | `Record<string, string[]>` | 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<string, object>` | ランタイムが読み込まれる前に検出および検証サーフェスにマージされる、マニフェスト所有のchannel設定メタデータです。 |
| `skills` | No | `string[]` | 読み込むSkillsディレクトリです。plugin rootからの相対パスです。 |
| `name` | No | `string` | 人間が読むためのプラグイン名です。 |
| `description` | No | `string` | プラグインサーフェスに表示される短い要約です。 |
| `version` | No | `string` | 参考情報としてのプラグインバージョンです。 |
| `uiHints` | No | `Record<string, object>` | 設定フィールド用のUIラベル、プレースホルダー、機密性ヒントです。 |
| Field | Required | Type | What it means |
| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Yes | `string` | 正式なplugin idです。これは`plugins.entries.<id>`で使われる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<string, string[]>` | OpenClawがプラグインコードを読み込まずに調べられる、軽量なprovider認証envメタデータです。 |
| `providerAuthAliases` | No | `Record<string, string>` | 認証参照のために別のprovider idを再利用すべきprovider idです。たとえば、ベースproviderのAPIキーや認証プロファイルを共有するcoding providerなどです。 |
| `channelEnvVars` | No | `Record<string, string[]>` | 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<string, object>` | ランタイム読み込み前に検出および検証サーフェスへマージされる、マニフェスト所有のchannel設定メタデータです。 |
| `skills` | No | `string[]` | plugin rootからの相対パスで指定する、読み込むSkillsディレクトリです。 |
| `name` | No | `string` | 人が読めるプラグイン名です。 |
| `description` | No | `string` | プラグインサーフェスに表示される短い要約です。 |
| `version` | No | `string` | 情報提供用のプラグインバージョンです。 |
| `uiHints` | No | `Record<string, object>` | 設定フィールド用の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 <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 <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.<id>`用のJSON Schemaです。宣言された各channel設定エントリーで必須です。 |
| `uiHints` | `Record<string, object>` | その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.<id>`用のJSONスキーマ。宣言された各チャネル設定エントリーで必須です。 |
| `uiHints` | `Record<string, object>` | そのチャネル設定セクション用のオプションの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.<id>`エントリーのような場合から、インストールフローが回復することだけを許可します。無関係な設定エラーは引き続きインストールをブロックし、オペレーターは`openclaw doctor --fix`に誘導されます。
`openclaw.install.allowInvalidConfigRecovery` は意図的に限定的です。これによって任意の壊れた設定がインストール可能になるわけではありません。現時点では、特定の古いバンドルプラグインのアップグレード失敗、たとえば欠落したバンドルプラグインパスや、同じバンドルプラグインに対する古い `channels.<id>` エントリーなどから、インストールフローが回復できるようにするだけです。無関係な設定エラーは引き続きインストールをブロックし、運用者を `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.<id>`、`plugins.allow`、`plugins.deny`、および`plugins.slots.*`は、**検出可能な**plugin idを参照していなければなりません。不明なidは**エラー**です。
- プラグインがインストールされていても、マニフェストまたはスキーマが壊れているか欠けている場合、検証は失敗し、Doctorはそのプラグインエラーを報告します。
- プラグイン設定が存在していても、プラグインが**無効**の場合、設定は保持され、Doctorとログに**警告**が表示されます。
- 未知の`channels.*`キーは、チャネルidがプラグインマニフェストで宣言されていない限り、**エラー**です。
- `plugins.entries.<id>`、`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 <package>`）を文書化してください。
## 関連

257
docs/ja-JP/plugins/sdk-agent-harness.md Normal file
View File

@ -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>`は、その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)

355
docs/ja-JP/plugins/sdk-channel-plugins.md
View File

@ -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、返信スレッド化、アウトバウンドメッセージングを備えた動作するチャンネルが完成します。
<Info>
まだOpenClawプラグインを一度も作成したことがない場合は、基本的なパッケージ
構造とマニフェスト設定について、先に
[はじめに](/ja-JP/plugins/building-plugins)を読んでください。
まだOpenClawプラグインを一度も構築したことがない場合は、まず基本的なパッケージ構造とmanifest設定について[はじめに](/ja-JP/plugins/building-plugins)を読んでください。
</Info>
## チャネルプラグインの仕組み
## チャンネルプラグインの仕組み
チャネルプラグインは、独自の 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.<channel>.accounts.<id>.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.<channel>.accounts.<id>.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 })`を使用してください。
## ウォークスルー
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="パッケージとマニフェスト">
標準的なプラグインファイルを作成します。`package.json` の `channel` フィールドが、
これをチャネルプラグインにします。完全なパッケージメタデータサーフェスについては、
[プラグインのセットアップと設定](/ja-JP/plugins/sdk-setup#openclawchannel)
を参照してください:
<Step title="パッケージとmanifest">
標準的なプラグインファイルを作成します。`package.json`内の`channel`フィールドが、これをチャンネルプラグインにします。完全なパッケージメタデータサーフェスについては、[Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel)を参照してください。
<CodeGroup>
```json package.json
@ -305,11 +261,10 @@ if (decision.shouldSkip) return;
</Step>
<Step title="チャネルプラグインオブジェクトを構築する">
`ChannelPlugin` インターフェースには、多くの任意アダプターサーフェスがあります。まずは
最小限の `id` と `setup` から始め、必要に応じてアダプターを追加してください。
<Step title="チャンネルプラグインオブジェクトを構築する">
`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;
});
```
<Accordion title="createChatChannelPlugin が行うこと">
低レベルのアダプターインターフェースを手動で実装する代わりに、
宣言的なオプションを渡すと、ビルダーがそれらを組み合わせます:
<Accordion title="createChatChannelPluginが担ってくれること">
低レベルのアダプターインターフェースを手動で実装する代わりに、宣言的なオプションを渡すと、builderがそれらを組み合わせます。
| オプション | 配線される内容 |
| オプション | 配線されるもの |
| --- | --- |
| `security.dm` | 設定フィールドからのスコープ付きDMセキュリティリゾルバー |
| `pairing.text` | コード交換を伴うテキストベースのDM pairing フロー |
| `threading` | 返信モードリゾルバー（固定、アカウントスコープ、またはカスタム） |
| `outbound.attachedResults` | 結果メタデータ（message ID）を返す送信関数 |
| `pairing.text` | コード交換付きのテキストベースDM pairingフロー |
| `threading` | reply-to-modeリゾルバー（固定、アカウントスコープ、またはカスタム） |
| `outbound.attachedResults` | 結果メタデータ（メッセージID）を返す送信関数 |
完全な制御が必要な場合は、宣言的オプションの代わりに生のアダプターオブジェクトを渡すこともできます。
完全に制御したい場合は、宣言的オプションの代わりに生のアダプターオブジェクトを渡すこともできます。
</Accordion>
</Step>
<Step title="エントリポイントを配線する">
`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)を参照してください。
</Step>
<Step title="セットアップエントリを追加する">
オンボーディング中の軽量読み込み用に `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)を参照してください。
</Step>
<Step title="インバウンドメッセージを処理する">
プラグインは、プラットフォームからメッセージを受信し、それを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;
```
<Note>
インバウンドメッセージ処理はチャネル固有です。各チャネルプラグインが
独自のインバウンドパイプラインを所有します。実際のパターンについては、
バンドルチャネルプラグイン
（たとえば Microsoft Teams または Google Chat プラグインパッケージ）を見てください。
インバウンドメッセージ処理はチャンネル固有です。各チャンネルプラグインが独自のインバウンドパイプラインを所有します。実際のパターンについては、同梱チャンネルプラグイン（たとえばMicrosoft TeamsまたはGoogle Chatプラグインパッケージ）を確認してください。
</Note>
</Step>
<a id="step-6-test"></a>
<Step title="テスト">
`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 -- <bundled-plugin-root>/acme-chat/
```
共有テストヘルパーについては、[Testing](/ja-JP/plugins/sdk-testing) を参照してください。
共有テストヘルパーについては、[Testing](/ja-JP/plugins/sdk-testing)を参照してください。
</Step>
</Steps>
## ファイル構造
## ファイル構成
```
```text
<bundled-plugin-root>/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;
<Card title="スレッド化オプション" icon="git-branch" href="/ja-JP/plugins/sdk-entrypoints#registration-mode">
固定、アカウントスコープ、またはカスタムの返信モード
</Card>
<Card title="Messageツール統合" icon="puzzle" href="/ja-JP/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageTool とアクション検出
<Card title="messageツール統合" icon="puzzle" href="/ja-JP/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageToolとアクションディスカバリー
</Card>
<Card title="ターゲット解決" icon="crosshair" href="/ja-JP/plugins/architecture#channel-target-resolution">
inferTargetChatType, looksLikeId, resolveTarget
inferTargetChatType、looksLikeId、resolveTarget
</Card>
<Card title="ランタイムヘルパー" icon="settings" href="/ja-JP/plugins/sdk-runtime">
api.runtime 経由のTTS、STT、メディア、subagent
api.runtime経由のTTS、STT、メディア、subagent
</Card>
</CardGroup>
<Note>
一部のバンドルヘルパーシームは、バンドルプラグインの保守と
互換性のために依然として存在します。これらは新しいチャネルプラグイン向けの推奨パターンではありません。
そのバンドルプラグインファミリーを直接保守しているのでない限り、
共通SDKサーフェスの汎用チャネル/セットアップ/返信/ランタイムsubpathを優先してください。
一部の同梱ヘルパー接合面は、同梱プラグインの保守と互換性のために引き続き存在します。これらは新しいチャンネルプラグイン向けの推奨パターンではありません。その同梱プラグインファミリーを直接保守しているのでない限り、共通SDKサーフェスの汎用channel/setup/reply/runtime subpathを優先してください。
</Note>
## 次のステップ
- [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スキーマ

711
docs/ja-JP/plugins/sdk-overview.md
View File

@ -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 の間の型付きコントラクトです。このページは、
**何をインポートするか** と **何を登録できるか** のリファレンスです。
<Tip>
**ハウツーガイドを探していますか？**
- 最初のプラグインですか？ [はじめに](/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) を参照してください
</Tip>
## インポート規約
@ -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` |
<AccordionGroup>
<Accordion title="チャネルサブパス">
<Accordion title="Channel サブパス">
| サブパス | 主なエクスポート |
| --- | --- |
| `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 |
</Accordion>
<Accordion title="プロバイダーサブパス">
<Accordion title="Provider サブパス">
| サブパス | 主なエクスポート |
| --- | --- |
| `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 |
</Accordion>
<Accordion title="認証およびセキュリティサブパス">
<Accordion title="認証とセキュリティのサブパス">
| サブパス | 主なエクスポート |
| --- | --- |
| `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 |
</Accordion>
<Accordion title="ランタイムおよびストレージサブパス">
<Accordion title="Runtime とストレージのサブパス">
| サブパス | 主なエクスポート |
| --- | --- |
| `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` |
</Accordion>
<Accordion title="ケイパビリティおよびテストサブパス">
<Accordion title="Capability とテストのサブパス">
| サブパス | 主なエクスポート |
| --- | --- |
| `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` |
</Accordion>
<Accordion title="メモリサブパス">
<Accordion title="メモリのサブパス">
| サブパス | 主なエクスポート |
| --- | --- |
| `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 |
</Accordion>
<Accordion title="予約済みバンドルヘルパーサブパス">
| ファミリー | 現在のサブパス | 想定用途 |
<Accordion title="予約済み bundled-helper サブパス">
| ファミリー | 現在のサブパス | 想定される用途 |
| --- | --- | --- |
| 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` をエクスポートします |
</Accordion>
</AccordionGroup>
## 登録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.<id>`と同じ形状を使用します。
- ユーザー設定が常に優先されます。OpenClawはCLI実行前に、プラグインのデフォルトの上へ
`agents.defaults.cliBackends.<id>`をマージします。
- マージ後にバックエンドが互換性書き換えを必要とする場合は`normalizeConfig`を使用してください
（たとえば古いフラグ形状の正規化など）。
- バックエンドの `id` は、`codex-cli/gpt-5` のような model ref における provider prefix になります。
- バックエンド `config` は、`agents.defaults.cliBackends.<id>` と同じ shape を使います。
- ユーザー設定が引き続き優先されます。OpenClaw は CLI 実行前に `agents.defaults.cliBackends.<id>` を
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<string, unknown>` | `plugins.entries.<id>.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<string, unknown>` | `plugins.entries.<id>.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（任意）
```
<Warning>
本番コードから、自分自身のプラグインを`openclaw/plugin-sdk/<your-plugin>`
経由でインポートしてはいけません。内部インポートは`./api.ts`または
`./runtime-api.ts`経由にしてください。SDKパスは外部契約専用です。
本番コード内で自分自身の plugin を `openclaw/plugin-sdk/<your-plugin>`
経由でインポートしてはいけません。内部インポートは `./api.ts` または
`./runtime-api.ts` を通してください。SDK パスは外部コントラクト専用です。
</Warning>
ファサード読み込みのバンドルプラグイン公開サーフェス（`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 をエクスポートします
<Warning>
拡張機能の本番コードも、`openclaw/plugin-sdk/<other-plugin>`の
インポートを避けるべきです。ヘルパーが本当に共有されるべきものであれば、
2つのプラグインを結合してしまうのではなく、`openclaw/plugin-sdk/speech`、
`.../provider-model-shared`、または別の
ケイパビリティ指向サーフェスのような中立的なSDKサブパスへ昇格してください。
Extension の本番コードでも、`openclaw/plugin-sdk/<other-plugin>`
のインポートは避けるべきです。helper が本当に共有対象であるなら、2 つの plugin を結合してしまう代わりに、
`openclaw/plugin-sdk/speech`、`.../provider-model-shared`、または別の
capability 指向 surface のような中立な SDK サブパスに昇格させてください。
</Warning>
## 関連
- [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 モデル

431
docs/ja-JP/plugins/sdk-provider-plugins.md
View File

@ -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 が完成します。
<Info>
まだOpenClawプラグインを1つも作成したことがない場合は、まず
基本的なパッケージ構造とマニフェスト設定について
[はじめに](/ja-JP/plugins/building-plugins)を読んでください。
まだ OpenClaw plugin を一度も作成したことがない場合は、まず
基本的なパッケージ構造と manifest 設定について
[はじめに](/ja-JP/plugins/building-plugins) を読んでください。
</Info>
## 手順
<Tip>
Provider plugin は OpenClaw の通常の推論ループにモデルを追加します。モデルを、
スレッド、compaction、またはツールイベントを管理するネイティブなエージェントデーモン経由で実行する必要がある場合は、
デーモンのプロトコル詳細を core に入れるのではなく、
provider を [agent harness](/ja-JP/plugins/sdk-agent-harness)
と組み合わせてください。
</Tip>
## ウォークスルー
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="パッケージとマニフェスト">
<Step title="パッケージと manifest">
<CodeGroup>
```json package.json
{
@ -88,13 +97,17 @@ x-i18n:
```
</CodeGroup>
マニフェストでは`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` 内で必須です。
</Step>
<Step title="providerを登録する">
最小限のproviderには、`id`、`label`、`auth`、および`catalog`が必要です。
<Step title="provider を登録する">
最小限の 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 <key>` を実行し、
モデルとして`acme-ai/acme-large`を選択できるようになります。
これで動作する provider になります。ユーザーは
`openclaw onboard --acme-ai-api-key <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 形式エンドポイントをオプトインさせられます。
</Step>
<Step title="動的モデル解決を追加する">
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` が再度実行されます。
</Step>
<Step title="runtime hookを追加する（必要に応じて）">
ほとんどのproviderでは`catalog` + `resolveDynamicModel`だけで十分です。providerに必要な場合にのみ、段階的にhookを追加してください。
<Step title="ランタイムフックを追加する（必要に応じて）">
ほとんどの 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 ヘルパーをエクスポート
<Tabs>
<Tab title="トークン交換">
各推論呼び出しの前にトークン交換が必要なproviderの場合:
各推論呼び出しの前にトークン交換が必要な provider の場合:
```typescript
prepareRuntimeAuth: async (ctx) => {
@ -381,10 +435,10 @@ x-i18n:
```
</Tab>
<Tab title="カスタムヘッダー">
カスタムリクエストヘッダーやボディ変更が必要な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:
},
```
</Tab>
<Tab title="ネイティブtransport識別情報">
汎用HTTPまたはWebSocket transport上で、ネイティブのリクエスト/セッションヘッダーまたはメタデータが必要なproviderの場合:
<Tab title="ネイティブ転送 ID">
汎用 HTTP または WebSocket 転送上で、ネイティブの
リクエスト/セッションヘッダーやメタデータが必要な provider の場合:
```typescript
resolveTransportTurnState: (ctx) => ({
@ -419,8 +474,8 @@ x-i18n:
}),
```
</Tab>
<Tab title="使用量と課金">
使用量/課金データを公開するproviderの場合:
<Tab title="使用量と請求">
使用量/請求データを公開する provider の場合:
```typescript
resolveUsageAuth: async (ctx) => {
@ -434,77 +489,85 @@ x-i18n:
</Tab>
</Tabs>
<Accordion title="利用可能なすべてのprovider hook">
OpenClawはこの順序でhookを呼び出します。ほとんどのproviderが使うのは2〜3個だけです。
<Accordion title="利用可能なすべての provider フック">
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.<id>` 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.<id>` 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) を参照してください。
</Accordion>
</Step>
<Step title="追加機能を加える（任意）">
<a id="step-5-add-extra-capabilities"></a>
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`
ブロックが期待される契約です。
</Step>
@ -630,11 +698,11 @@ x-i18n:
<a id="step-6-test"></a>
```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:
</Step>
</Steps>
## 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` を使う必要があります。
## ファイル構成
```
<bundled-plugin-root>/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) — フック詳細とバンドル例

176
docs/ja-JP/plugins/sdk-runtime.md
View File

@ -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`オブジェクトのリファレンスです。ホスト内部を直接インポートする代わりに、これらのヘルパーを使用してください。
<Tip>
**手順付きガイドを探していますか？** これらの 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)で、これらのヘルパーが実際の流れの中でどう使われるかを段階的に確認できます。
</Tip>
```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",
});
```
<Warning>
モデル override（`provider`/`model`）には、config の
`plugins.entries.<id>.subagent.allowModelOverride: true` によるオペレーターのオプトインが必要です。
信頼されていない plugin でも subagent は実行できますが、override 要求は拒否されます。
モデル上書き（`provider`/`model`）には、設定内の
`plugins.entries.<id>.subagent.allowModelOverride: true`によるオペレーターの明示的オプトインが必要です。
信頼されていないプラグインでもサブエージェントは実行できますが、上書き要求は拒否されます。
</Warning>
### `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 }`を返します。
<Info>
`api.runtime.stt.transcribeAudioFile(...)` は、互換性のための
`api.runtime.mediaUnderstanding.transcribeAudioFile(...)` の alias として引き続き利用できます。
`api.runtime.stt.transcribeAudioFile(...)`は、
`api.runtime.mediaUnderstanding.transcribeAudioFile(...)`の互換性エイリアスとして引き続き利用できます。
</Info>
### `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<PluginRuntime>("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<string, unknown>` | `plugins.entries.<id>.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<string, unknown>` | `plugins.entries.<id>.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とレジストリ

78
docs/ja-JP/providers/fal.md
View File

@ -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)

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

@ -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)
内の非公開リリースドキュメントを使用します。
の非公開リリースドキュメントを使用します。

225
docs/ja-JP/reference/templates/AGENTS.md
View File

@ -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のリンク:** 埋め込みを抑制するため、複数のリンクは `<>` で囲む: `<https://example.com>`
- **WhatsApp:** 見出しは使わない — 強調には **太字** または大文字を使う
- **Discord/WhatsApp:** Markdownテーブルは禁止! 代わりに箇条書きを使ってください
- **Discordのリンク:** 埋め込みを抑制するため、複数リンクは`<>`で囲んでください: `<https://example.com>`
- **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
}
```
**声をかけるタイミング:**
**連絡すべきとき:**
- 重要なメールが届いた
- カレンダーの予定が近い（&lt;2h）
- 何か面白いものを見つけた
- 最後に何か伝えてから >8h 経っている
- カレンダー予定が近い（<2時間）
- 面白いことを見つけた
- 最後に何か言ってから8時間以上経った
**静かにしているタイミング（HEARTBEAT_OK）:**
**静かにしているべきとき（HEARTBEAT_OK）:**
- 深夜（23:00-08:00）で、緊急ではない
- 深夜（23:00-08:00）、緊急時を除く
- 人間が明らかに忙しい
- 前回の確認から新しいことが何もない
- さっき確認したばかり（&lt;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日に数回は様子を見て、有用な裏方作業をしつつ、静かな時間は尊重してください。
## 自分のものにする
これは出発点です。何がうまくいくかを見極めながら、自分なりの慣習、スタイル、ルールを足していってください。
これは出発点です。何がうまくいくかが分かってきたら、自分の慣習、スタイル、ルールを追加してください。

687
docs/ja-JP/tools/browser.md
View File

File diff suppressed because it is too large Load Diff

531
docs/ja-JP/tools/exec-approvals.md
View File

@ -1,70 +1,54 @@
---
read_when:
- exec 承認や allowlist を設定する場合
- macOS アプリで exec 承認 UX を実装する場合
- sandbox 脱出プロンプトとその影響を確認する場合
summary: exec 承認、allowlist、sandbox 脱出プロンプト
title: Exec 承認
- 'exec承認またはallowlistを設定する_gsharedענדיקanalysis to=final code: null 天天中彩票可以assistant final to=all(final) code പുറ്റിയ text'
- macOSアプリでexec承認UXを実装する
- サンドボックスエスケーププロンプトとその影響を確認する
summary: exec承認、allowlist、およびサンドボックスエスケーププロンプト
title: exec承認
x-i18n:
generated_at: "2026-04-08T02:21:10Z"
generated_at: "2026-04-11T02:48:38Z"
model: gpt-5.4
provider: openai
source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9
source_hash: 5f4a2e2f1f3c13a1d1926c9de0720513ea8a74d1ca571dbe74b188d8c560c14c
source_path: tools/exec-approvals.md
workflow: 15
---
# Exec 承認
# exec承認
Exec 承認は、sandbox 化されたエージェントが実ホスト（`gateway` または `node`）上で
コマンドを実行できるようにするための **companion app / node host のガードレール** です。安全インターロックのようなものと考えてください:
コマンドは、ポリシー + allowlist + （任意の）ユーザー承認のすべてが一致した場合にのみ許可されます。
Exec 承認は、ツールポリシーや elevated gating に **追加で** 適用されます（elevated が `full` に設定されている場合は承認をスキップします）。
実効ポリシーは `tools.exec.*` と承認デフォルトの **より厳しい方** です。承認フィールドが省略されている場合は、`tools.exec` の値が使われます。
host exec は、そのマシン上のローカル承認状態も使用します。ホストローカルの
`~/.openclaw/exec-approvals.json` に `ask: "always"` があると、セッションや設定のデフォルトが `ask: "on-miss"` を要求していても、引き続き毎回プロンプトが表示されます。
要求されたポリシー、ホストポリシーのソース、および実効結果を確認するには、
`openclaw approvals get`、`openclaw approvals get --gateway`、または
`openclaw approvals get --node <id|name|ip>` を使用してください。
exec承認は、サンドボックス化されたagentが実ホスト（`gateway` または `node`）上でコマンドを実行できるようにするための**companion app / node hostのガードレール**です。安全インターロックのようなものと考えてください。コマンドは、ポリシー + allowlist + （任意の）ユーザー承認のすべてが許可した場合にのみ許可されます。exec承認は、ツールポリシーおよびelevatedゲーティングに**追加で**適用されます（`elevated` が `full` の場合を除き、この場合は承認をスキップします）。実効ポリシーは `tools.exec.*` と承認デフォルトの**より厳しい方**です。承認フィールドが省略された場合は、`tools.exec` の値が使われます。
ホストexecは、そのマシン上のローカル承認状態も使用します。`~/.openclaw/exec-approvals.json` にあるホストローカルの `ask: "always"` は、セッションや設定デフォルトが `ask: "on-miss"` を要求していても、引き続き毎回プロンプトを表示します。
要求されたポリシー、ホストポリシーのソース、および実効結果を確認するには、`openclaw approvals get`、`openclaw approvals get --gateway`、または `openclaw approvals get --node <id|name|ip>` を使用してください。
ローカルマシンでは、`openclaw exec-policy show` が同じマージ済みビューを表示し、`openclaw exec-policy set|preset` でローカルの要求ポリシーとローカルホスト承認ファイルを一度に同期できます。ローカルscopeが `host=node` を要求した場合、`openclaw exec-policy show` は、そのscopeをローカル承認ファイルが実効的な信頼できる情報源であるかのように見せかけるのではなく、ランタイムではnode管理として報告します。
companion app UI が **利用できない** 場合、プロンプトを必要とする要求はすべて
**ask fallback**（デフォルト: deny）によって処理されます。
companion app UIが**利用できない**場合、プロンプトが必要なすべての要求は**ask fallback**（デフォルト: deny）によって処理されます。
ネイティブのチャット承認クライアントは、保留中の承認メッセージにチャネル固有の操作も
表示できます。たとえば Matrix は、承認プロンプトにリアクションショートカット
（`✅` は一度だけ許可、`❌` は拒否、利用可能な場合は `♾️` で常に許可）を追加しつつ、
フォールバックとしてメッセージ内の `/approve ...` コマンドも残せます。
ネイティブなチャット承認クライアントは、保留中の承認メッセージ上にチャネル固有の操作UIを出すこともできます。たとえばMatrixでは、承認プロンプト上にリアクションショートカット（`✅` で一度だけ許可、`❌` で拒否、利用可能な場合は `♾️` で常に許可）を出しつつ、フォールバックとしてメッセージ内の `/approve ...` コマンドも残せます。
## 適用される場所
Exec 承認は、実行ホスト上でローカルに強制されます。
exec承認は、実行ホスト上でローカルに適用されます。
- **gateway host** → gateway マシン上の `openclaw` プロセス
- **gateway host** → Gatewayマシン上の `openclaw` プロセス
- **node host** → node runner（macOS companion app または headless node host）
信頼モデルに関する注意:
- Gateway 認証済みの呼び出し元は、その Gateway の信頼されたオペレーターです。
- ペアリング済み node は、その trusted operator capability を node host に拡張します。
- Exec 承認は、誤実行のリスクを減らしますが、ユーザー単位の認証境界ではありません。
- 承認済みの node-host 実行では、canonical な実行コンテキスト、すなわち canonical cwd、正確な argv、存在する場合の env
バインディング、および該当する場合の固定された実行ファイルパスが結び付けられます。
- シェルスクリプトや、インタープリター / ランタイムによる直接ファイル実行については、OpenClaw は
1 つの具体的なローカルファイル operand も結び付けようとします。承認後から実行前の間にその結び付けられたファイルが変化した場合、
変更後の内容を実行するのではなく、その実行は拒否されます。
- このファイルバインディングは、意図的に best-effort であり、すべての
インタープリター / ランタイムローダーパスに対する完全な意味論モデルではありません。承認モードで
結び付けるべき具体的なローカルファイルを正確に 1 つ特定できない場合、完全にカバーしているふりをするのではなく、
承認ベースの実行を発行すること自体を拒否します。
- Gatewayで認証された呼び出し元は、そのGatewayの信頼されたoperatorです。
- ペアリングされたnodeは、その信頼されたoperator能力をnode host上へ拡張します。
- exec承認は偶発的な実行リスクを減らしますが、ユーザーごとの認証境界ではありません。
- 承認済みのnode-host実行は、正規の実行コンテキストを束縛します: 正規のcwd、正確なargv、存在する場合のenv束縛、必要に応じた固定済み実行ファイルパス。
- シェルスクリプトおよびインタープリター/ランタイムによる直接ファイル実行については、OpenClawは1つの具体的なローカルファイルオペランドも束縛しようとします。承認後、実行前にその束縛ファイルが変更されていた場合、内容が変化したものを実行する代わりに、その実行は拒否されます。
- このファイル束縛は、すべてのインタープリター/ランタイムのローダーパスに対する完全な意味モデルではなく、意図的にベストエフォートです。承認モードで正確に1つの具体的なローカルファイルを束縛できない場合、完全にカバーされているふりをするのではなく、承認付き実行の発行を拒否します。
macOS の分割構成:
macOSでの分割:
- **node host service** は `system.run` をローカル IPC 経由で **macOS app** に転送します。
- **macOS app** は承認を強制し、UI コンテキストでコマンドを実行します。
- **node host service** は、ローカルIPC経由で `system.run` を**macOS app** に転送します。
- **macOS app** が承認を適用し、UIコンテキストでコマンドを実行します。
## 設定と保存場所
承認は、実行ホスト上のローカル JSON ファイルに保存されます。
承認は、実行ホスト上のローカルJSONファイルに保存されます。
`~/.openclaw/exec-approvals.json`
@ -103,30 +87,29 @@ macOS の分割構成:
}
```
## 承認不要の「YOLO」モード
## 承認なしの「YOLO」モード
承認プロンプトなしで host exec を実行したい場合は、**両方** のポリシーレイヤーを開く必要があります。
承認プロンプトなしでホストexecを実行したい場合は、**両方**のポリシーレイヤーを開く必要があります。
- OpenClaw 設定内の要求された exec ポリシー（`tools.exec.*`）
- `~/.openclaw/exec-approvals.json` 内の host-local approvals ポリシー
- OpenClaw設定内の要求execポリシー（`tools.exec.*`）
- `~/.openclaw/exec-approvals.json` 内のホストローカル承認ポリシー
これは現在、明示的に厳しくしない限り、デフォルトの host 動作です。
これは、明示的に厳しくしない限り、現在のデフォルトホスト動作です。
- `tools.exec.security`: `gateway` / `node` 上では `full`
- `tools.exec.security`: `gateway`/`node` では `full`
- `tools.exec.ask`: `off`
- host `askFallback`: `full`
- ホストの `askFallback`: `full`
重要な違い:
- `tools.exec.host=auto` は exec の実行場所を選びます。利用可能なら sandbox、そうでなければ gateway。
- YOLO は host exec の承認方法を選びます。`security=full` と `ask=off` です。
- YOLO モードでは、OpenClaw は、設定済み host exec ポリシーの上に、別個のヒューリスティックなコマンド難読化承認ゲートを追加しません。
- `auto` は、sandbox 化されたセッションから gateway へのルーティングを無条件の上書きにするものではありません。呼び出し単位の `host=node` 要求は `auto` から許可され、`host=gateway` は sandbox ランタイムが有効でない場合にのみ `auto` から許可されます。安定した non-auto のデフォルトが必要なら、`tools.exec.host` を設定するか、`/exec host=...` を明示的に使ってください。
- `tools.exec.host=auto` は、execをどこで実行するかを選びます: 利用可能ならサンドボックス、そうでなければgateway。
- YOLOは、ホストexecをどう承認するかを選びます: `security=full` と `ask=off`。
- YOLOモードでは、OpenClawは設定済みホストexecポリシーの上に、別個のヒューリスティックなコマンド難読化承認ゲートを追加しません。
- `auto` は、サンドボックス化されたセッションからgatewayルーティングを自由に上書きできることを意味しません。呼び出しごとの `host=node` 要求は `auto` から許可され、`host=gateway` はサンドボックスランタイムがアクティブでない場合にのみ `auto` から許可されます。安定した非autoデフォルトが必要な場合は、`tools.exec.host` を設定するか、`/exec host=...` を明示的に使ってください。
より保守的な設定にしたい場合は、どちらかのレイヤーを `allowlist` / `on-miss`
または `deny` に戻してください。
より保守的な構成にしたい場合は、どちらか一方のレイヤーを `allowlist` / `on-miss` または `deny` に戻してください。
gateway-host で永続的に「never prompt」にする設定:
Gateway hostで「絶対にプロンプトを出さない」永続設定:
```bash
openclaw config set tools.exec.host gateway
@ -135,7 +118,7 @@ openclaw config set tools.exec.ask off
openclaw gateway restart
```
次に、ホスト承認ファイルも一致するよう設定します。
次に、ホスト承認ファイルも一致するように設定します。
```bash
openclaw approvals set --stdin <<'EOF'
@ -150,7 +133,20 @@ openclaw approvals set --stdin <<'EOF'
EOF
```
node host の場合は、代わりにその node に同じ承認ファイルを適用してください。
現在のマシン上で同じGateway hostポリシーを適用するローカルショートカット:
```bash
openclaw exec-policy preset yolo
```
このローカルショートカットは次の両方を更新します。
- ローカルの `tools.exec.host/security/ask`
- ローカルの `~/.openclaw/exec-approvals.json` デフォルト
これは意図的にローカル専用です。Gateway hostまたはnode hostの承認をリモートで変更する必要がある場合は、引き続き `openclaw approvals set --gateway` または `openclaw approvals set --node <id|name|ip>` を使用してください。
node hostの場合は、同じ承認ファイルを代わりにそのnodeへ適用します。
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
@ -165,40 +161,45 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
EOF
```
重要なローカル専用の制限:
- `openclaw exec-policy` はnode承認を同期しない
- `openclaw exec-policy set --host node` は拒否される
- node exec承認はランタイム時にnodeから取得されるため、node向け更新には `openclaw approvals --node ...` を使用する必要がある
セッション限定のショートカット:
- `/exec security=full ask=off` は現在のセッションだけを変更します。
- `/elevated full` は緊急時用のショートカットで、そのセッションでは exec 承認もスキップします。
- `/exec security=full ask=off` は現在のセッションだけを変更する。
- `/elevated full` は、同じセッションでexec承認もスキップするbreak-glassショートカット。
ホスト承認ファイルの方が設定より厳しいままである場合、より厳しいホストポリシーが引き続き優先されます。
ホスト承認ファイルが設定より厳しいままなら、引き続きそのより厳しいホストポリシーが優先されます。
## ポリシーのつまみ
## ポリシーノブ
### Security (`exec.security`)
### Security（`exec.security`）
- **deny**: すべての host exec 要求をブロックします。
- **allowlist**: allowlist に含まれるコマンドのみ許可します。
- **full**: すべて許可します（elevated と同等）。
- **deny**: すべてのホストexec要求をブロックする。
- **allowlist**: allowlistにあるコマンドだけを許可する。
- **full**: すべてを許可する（elevatedと同等）。
### Ask (`exec.ask`)
### Ask（`exec.ask`）
- **off**: プロンプトを一切表示しません。
- **on-miss**: allowlist に一致しない場合のみプロンプトを表示します。
- **always**: すべてのコマンドでプロンプトを表示します。
- 実効 ask モードが `always` の場合、`allow-always` の durable trust でもプロンプトは抑止されません
- **off**: プロンプトを一切表示しない。
- **on-miss**: allowlistが一致しない場合のみプロンプトを表示する。
- **always**: すべてのコマンドでプロンプトを表示する。
- 実効askモードが `always` の場合、`allow-always` の永続的な信頼はプロンプトを抑止しない
### Ask fallback (`askFallback`)
### Ask fallback（`askFallback`）
プロンプトが必要なのに UI に到達できない場合は、fallback が決定します。
プロンプトが必要だが到達可能なUIがない場合、fallbackが次を決めます。
- **deny**: ブロックします。
- **allowlist**: allowlist に一致する場合のみ許可します。
- **full**: 許可します。
- **deny**: ブロックする。
- **allowlist**: allowlistが一致する場合のみ許可する。
- **full**: 許可する。
### インラインインタープリター eval の強化 (`tools.exec.strictInlineEval`)
### インラインインタープリターevalの強化（`tools.exec.strictInlineEval`）
`tools.exec.strictInlineEval=true` の場合、OpenClaw は、インタープリターバイナリ自体が allowlist に入っていても、
インラインコード eval 形式を承認専用として扱います。
`tools.exec.strictInlineEval=true` の場合、OpenClawはインラインコードeval形式を、インタープリターバイナリー自体がallowlistに入っていても、承認専用として扱います。
例:
@ -210,18 +211,14 @@ EOF
- `lua -e`
- `osascript -e`
これは、1 つの安定したファイル operand にきれいに対応しないインタープリターローダーに対する defense-in-depth です。strict モードでは:
これは、1つの安定したファイルオペランドへきれいに対応しないインタープリターローダーに対する多層防御です。strictモードでは:
- これらのコマンドは引き続き明示的な承認が必要です。
- `allow-always` でも、それらの新しい allowlist エントリは自動的には永続化されません。
- これらのコマンドには引き続き明示的な承認が必要です。
- `allow-always` は、それらに対して新しいallowlistエントリーを自動で永続化しません。
## Allowlist（エージェント単位）
## Allowlist（agentごと）
Allowlists は **エージェント単位** です。複数のエージェントが存在する場合は、macOS app で
編集中のエージェントを切り替えてください。パターンは **大文字小文字を区別しない glob 一致** です。
パターンは **バイナリパス** に解決される必要があります（basename のみのエントリは無視されます）。
旧来の `agents.default` エントリは、ロード時に `agents.main` へ移行されます。
`echo ok && pwd` のようなシェルチェーンでも、トップレベルの各セグメントがすべて allowlist ルールを満たす必要があります。
allowlistは**agentごと**です。複数のagentが存在する場合は、macOS appで編集中のagentを切り替えてください。パターンは**大文字小文字を区別しないglob一致**です。パターンは**バイナリーパス**に解決される必要があります（basenameのみのエントリーは無視されます）。レガシーな `agents.default` エントリーは、読み込み時に `agents.main` へ移行されます。`echo ok && pwd` のようなシェル連結でも、トップレベルの各セグメントがallowlistルールを満たす必要があります。
例:
@ -229,46 +226,34 @@ Allowlists は **エージェント単位** です。複数のエージェント
- `~/.local/bin/*`
- `/opt/homebrew/bin/rg`
各 allowlist エントリは次を追跡します。
各allowlistエントリーは次を追跡します。
- **id** UI 上の識別に使う安定した UUID（任意）
- **id** UI識別用の安定したUUID（オプション）
- **last used** タイムスタンプ
- **last used command**
- **last resolved path**
## Skills の CLI を自動許可
## Skill CLIの自動許可
**Auto-allow skill CLIs** が有効な場合、既知の Skills で参照される実行ファイルは
node 上で allowlist 済みとして扱われます（macOS node または headless node host）。これは
Gateway RPC 経由の `skills.bins` を使ってスキルの bin 一覧を取得します。厳密な手動 allowlist が必要な場合は無効にしてください。
**Auto-allow skill CLIs** が有効な場合、既知のSkillsから参照される実行ファイルは、node上（macOS nodeまたはheadless node host）でallowlist済みとして扱われます。これは、Gateway RPC経由でskill binリストを取得するために `skills.bins` を使用します。厳密な手動allowlistだけにしたい場合は、これを無効にしてください。
重要な信頼に関する注意:
- これは、手動のパス allowlist エントリとは別の **暗黙的な利便性 allowlist** です。
- これは、Gateway と node が同じ信頼境界にある trusted operator 環境を想定しています。
- 厳密な明示的信頼が必要なら、`autoAllowSkills: false` のままにして、手動のパス allowlist エントリだけを使ってください。
- これは、手動パスallowlistエントリーとは別の**暗黙の利便性allowlist**です。
- これは、Gatewayとnodeが同じ信頼境界内にある信頼済みoperator環境向けです。
- 厳密に明示的な信頼が必要な場合は、`autoAllowSkills: false` のままにして、手動パスallowlistエントリーのみを使用してください。
## Safe bins（stdin 専用）
## Safe bins（stdin専用）
`tools.exec.safeBins` は、明示的な allowlist エントリなしでも allowlist モードで実行できる、
**stdin 専用** のバイナリ（たとえば `cut`）の小さな一覧を定義します。safe bins は
位置引数のファイル引数や path 的なトークンを拒否するため、入力ストリームに対してのみ動作できます。
これは一般的な信頼リストではなく、ストリームフィルター向けの限定的な高速経路として扱ってください。
インタープリターやランタイムのバイナリ（たとえば `python3`、`node`、`ruby`、`bash`、`sh`、`zsh`）を `safeBins` に追加しては **いけません**。
コードを評価できる、サブコマンドを実行できる、または設計上ファイルを読めるコマンドについては、
明示的な allowlist エントリを優先し、承認プロンプトも有効のままにしてください。
カスタム safe bins は `tools.exec.safeBinProfiles.<bin>` に明示的なプロファイルを定義しなければなりません。
バリデーションは argv の形だけから決定論的に行われます（ホストファイルシステム上の存在確認は行いません）。これにより、
許可 / 拒否の違いからファイル存在オラクルのような振る舞いが生じるのを防ぎます。
デフォルトの safe bins では、ファイル指向オプションは拒否されます（たとえば `sort -o`、`sort --output`、
`sort --files0-from`、`sort --compress-program`、`sort --random-source`、
`sort --temporary-directory`/`-T`、`wc --files0-from`、`jq -f/--from-file`、
`grep -f/--file`）。
safe bins は、stdin 専用の動作を崩すオプションについても、バイナリごとの明示的なフラグポリシーを強制します
（たとえば `sort -o/--output/--compress-program` や grep の再帰フラグ）。
long option は safe-bin モードでは fail-closed で検証されます。不明なフラグや曖昧な
省略形は拒否されます。
safe-bin プロファイルで拒否されるフラグ:
`tools.exec.safeBins` は、明示的なallowlistエントリーなしで、allowlistモードでも実行できる**stdin専用**バイナリー（例: `cut`）の小さなリストを定義します。safe binsは位置ファイル引数とパス風トークンを拒否するため、入力ストリームに対してのみ動作できます。これは汎用的な信頼リストではなく、ストリームフィルターのための狭い高速経路として扱ってください。
インタープリターやランタイムのバイナリー（例: `python3`、`node`、`ruby`、`bash`、`sh`、`zsh`）を `safeBins` に追加してはいけません。
コマンドがコードを評価できる、サブコマンドを実行できる、または設計上ファイルを読める場合は、明示的なallowlistエントリーを優先し、承認プロンプトを有効のままにしてください。
カスタムsafe binsは、`tools.exec.safeBinProfiles.<bin>` で明示的なプロファイルを定義する必要があります。
検証はargv形状のみから決定論的に行われ（ホストファイルシステムの存在確認は行いません）、これによりallow/denyの違いによるファイル存在oracle動作を防ぎます。
デフォルトのsafe binsでは、ファイル指向オプションが拒否されます（例: `sort -o`, `sort --output`, `sort --files0-from`, `sort --compress-program`, `sort --random-source`, `sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`, `grep -f/--file`）。
safe binsは、stdin専用の挙動を壊すオプションに対して、バイナリーごとの明示的なフラグポリシーも適用します（例: `sort -o/--output/--compress-program` と grepの再帰フラグ）。
long optionはsafe-binモードでclosed fail検証されます。未知のフラグと曖昧な省略形は拒否されます。
safe-binプロファイルごとの拒否フラグ:
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
@ -279,35 +264,20 @@ safe-bin プロファイルで拒否されるフラグ:
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
safe bins は、実行時にも argv トークンを **リテラルテキスト** として扱うことを強制します
（stdin 専用セグメントでは glob 展開も `$VARS` 展開も行いません）。そのため `*` や `$HOME/...` のようなパターンを使って
ファイル読み取りを持ち込むことはできません。
safe bins は、信頼されたバイナリディレクトリ（システムデフォルト + 任意の
`tools.exec.safeBinTrustedDirs`）から解決される必要もあります。`PATH` エントリが自動で信頼されることはありません。
デフォルトの信頼済み safe-bin ディレクトリは意図的に最小限です: `/bin`、`/usr/bin`。
safe-bin 実行ファイルがパッケージマネージャー / ユーザーパス（たとえば
`/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`）にある場合は、それらを明示的に
`tools.exec.safeBinTrustedDirs` に追加してください。
シェルチェーンやリダイレクトは、allowlist モードで自動許可されません。
safe binsは、stdin専用セグメントについて、実行時にargvトークンを**リテラルテキスト**として扱うことも強制します（glob展開も `$VARS` 展開もなし）。そのため、`*` や `$HOME/...` のようなパターンを使ってファイル読み取りを紛れ込ませることはできません。
safe binsは、信頼されたバイナリーディレクトリから解決される必要もあります（システムデフォルトに加え、任意で `tools.exec.safeBinTrustedDirs`）。`PATH` エントリーが自動で信頼されることはありません。
デフォルトの信頼済みsafe-binディレクトリは、意図的に最小限です: `/bin`, `/usr/bin`。
safe-bin実行ファイルがpackage managerやユーザーパス（例: `/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`）にある場合は、それらを `tools.exec.safeBinTrustedDirs` に明示的に追加してください。
allowlistモードでは、シェル連結とリダイレクトは自動許可されません。
シェルチェーン（`&&`、`||`、`;`）は、トップレベルの各セグメントが allowlist を満たす場合に許可されます
（safe bins やスキル自動許可を含む）。リダイレクトは allowlist モードでは引き続き未対応です。
コマンド置換（`$()` / backticks）は allowlist 解析中に拒否され、double quotes 内でも拒否されます。リテラルな `$()` テキストが必要なら
single quotes を使ってください。
macOS companion-app 承認では、シェル制御または展開構文
（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）を含む生のシェルテキストは、
シェルバイナリ自体が allowlist に入っていない限り、allowlist miss として扱われます。
シェルラッパー（`bash|sh|zsh ... -c/-lc`）では、要求スコープの env 上書きは、小さな明示的 allowlist
（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）に縮小されます。
allowlist モードでの allow-always 判断では、既知のディスパッチラッパー
（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）は、ラッパーパスではなく内部の実行ファイルパスを永続化します。シェル多重化バイナリ
（`busybox`、`toybox`）も、シェル applet（`sh`、`ash` など）では展開され、
多重化バイナリではなく内部の実行ファイルが永続化されます。ラッパーまたは
多重化バイナリを安全に展開できない場合、allowlist エントリは自動的には永続化されません。
`python3` や `node` のようなインタープリターを allowlist に入れる場合でも、インライン eval が明示承認を必要とするように
`tools.exec.strictInlineEval=true` を推奨します。strict モードでは、`allow-always` でも無害なインタープリター / スクリプト呼び出しは永続化できますが、インライン eval の運び手は自動では永続化されません。
シェル連結（`&&`, `||`, `;`）は、各トップレベルセグメントがallowlist要件を満たしている場合に許可されます（safe binsまたはskill自動許可を含む）。リダイレクトは、allowlistモードでは引き続き未サポートです。
コマンド置換（`$()` / バッククォート）は、ダブルクォート内も含め、allowlist解析時に拒否されます。リテラルな `$()` テキストが必要なら、シングルクォートを使ってください。
macOS companion-app承認では、シェル制御または展開構文（`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`）を含む生のシェルテキストは、シェルバイナリー自体がallowlistにない限り、allowlist missとして扱われます。
シェルラッパー（`bash|sh|zsh ... -c/-lc`）では、リクエストスコープのenv上書きは、小さな明示的allowlist（`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`）へ縮小されます。
allowlistモードでの `allow-always` 判断では、既知のdispatchラッパー（`env`, `nice`, `nohup`, `stdbuf`, `timeout`）は、ラッパーパスではなく内部の実行ファイルパスを永続化します。シェルマルチプレクサー（`busybox`, `toybox`）も、シェルアプレット（`sh`, `ash` など）についてアンラップされるため、マルチプレクサーバイナリーではなく内部実行ファイルが永続化されます。ラッパーまたはマルチプレクサーを安全にアンラップできない場合、allowlistエントリーは自動では永続化されません。
`python3` や `node` のようなインタープリターをallowlistに入れる場合は、インラインevalに引き続き明示的承認を必要とさせるため、`tools.exec.strictInlineEval=true` を推奨します。strictモードでは、`allow-always` は安全なインタープリター/スクリプト呼び出しを引き続き永続化できますが、インラインevalキャリアは自動では永続化されません。
デフォルトの safe bins:
デフォルトのsafe bins:
[//]: # "SAFE_BIN_DEFAULTS:START"
@ -315,96 +285,75 @@ allowlist モードでの allow-always 判断では、既知のディスパッ
[//]: # "SAFE_BIN_DEFAULTS:END"
`grep` と `sort` はデフォルト一覧には含まれません。opt in する場合でも、
非 stdin ワークフローには明示的な allowlist エントリを維持してください。
safe-bin モードの `grep` では、パターンは `-e` / `--regexp` で指定してください。位置引数のパターン形式は
拒否されるため、曖昧な位置引数としてファイル operand を紛れ込ませることはできません。
`grep` と `sort` はデフォルトリストに含まれていません。これらをオプトインする場合は、stdin以外のワークフロー向けに明示的なallowlistエントリーを維持してください。
safe-binモードの `grep` では、パターンは `-e`/`--regexp` で指定してください。位置指定のパターン形式は拒否されるため、ファイルオペランドを曖昧な位置引数として紛れ込ませることはできません。
### Safe bins と allowlist の違い
### Safe binsとallowlistの違い
| 話題 | `tools.exec.safeBins` | allowlist (`exec-approvals.json`) |
| Topic | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| 目的 | 限定的な stdin フィルターを自動許可 | 特定の実行ファイルを明示的に信頼 |
| 一致方式 | 実行ファイル名 + safe-bin の argv ポリシー | 解決済み実行ファイルパスの glob パターン |
| 引数の範囲 | safe-bin プロファイルとリテラルトークン規則で制限 | パスマッチのみ。引数はそれ以外では利用者の責任 |
| 典型例 | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, カスタム CLI |
| 最適な用途 | パイプライン内の低リスクなテキスト変換 | より広い動作や副作用を持つ任意のツール |
| Goal | 狭いstdinフィルターを自動許可する | 特定の実行ファイルを明示的に信頼する |
| Match type | 実行ファイル名 + safe-bin argvポリシー | 解決済み実行ファイルパスのglobパターン |
| Argument scope | safe-binプロファイルとリテラルトークン規則によって制限される | パスマッチのみ。引数はそれ以外では利用者の責任 |
| Typical examples | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, カスタムCLI |
| Best use | パイプライン内の低リスクなテキスト変換 | より広い挙動や副作用を持つ任意のツール |
設定場所:
- `safeBins` は設定から取得されます（`tools.exec.safeBins` またはエージェント単位の `agents.list[].tools.exec.safeBins`）。
- `safeBinTrustedDirs` は設定から取得されます（`tools.exec.safeBinTrustedDirs` またはエージェント単位の `agents.list[].tools.exec.safeBinTrustedDirs`）。
- `safeBinProfiles` は設定から取得されます（`tools.exec.safeBinProfiles` またはエージェント単位の `agents.list[].tools.exec.safeBinProfiles`）。エージェント単位のプロファイルキーはグローバルキーを上書きします。
- allowlist エントリは、ホストローカルの `~/.openclaw/exec-approvals.json` の `agents.<id>.allowlist` に保存されます（または Control UI / `openclaw approvals allowlist ...` 経由）。
- `openclaw security audit` は、インタープリター / ランタイムの bin が明示プロファイルなしで `safeBins` に含まれている場合、`tools.exec.safe_bins_interpreter_unprofiled` で警告します。
- `openclaw doctor --fix` は、足りないカスタム `safeBinProfiles.<bin>` エントリを `{}` としてひな形作成できます（その後で確認して厳しくしてください）。インタープリター / ランタイムの bin は自動ひな形作成されません。
- `safeBins` は設定から取得されます（`tools.exec.safeBins` またはagentごとの `agents.list[].tools.exec.safeBins`）。
- `safeBinTrustedDirs` は設定から取得されます（`tools.exec.safeBinTrustedDirs` またはagentごとの `agents.list[].tools.exec.safeBinTrustedDirs`）。
- `safeBinProfiles` は設定から取得されます（`tools.exec.safeBinProfiles` またはagentごとの `agents.list[].tools.exec.safeBinProfiles`）。agentごとのプロファイルキーはグローバルキーを上書きします。
- allowlistエントリーは、ホストローカルの `~/.openclaw/exec-approvals.json` の `agents.<id>.allowlist` に保存されます（またはControl UI / `openclaw approvals allowlist ...` 経由）。
- `openclaw security audit` は、インタープリター/ランタイムのbinが明示的なプロファイルなしで `safeBins` に現れると、`tools.exec.safe_bins_interpreter_unprofiled` で警告します。
- `openclaw doctor --fix` は、不足しているカスタム `safeBinProfiles.<bin>` エントリーを `{}` としてひな形作成できます（その後、確認してより厳しくしてください）。インタープリター/ランタイムのbinは自動ひな形作成されません。
カスタムプロファイルの例:
__OC_I18N_900004__
`jq` を明示的に `safeBins` に opt in した場合でも、OpenClaw は safe-bin
モードで `env` 組み込みを拒否します。これにより `jq -n env` でホストプロセスの環境をダンプすることは、
明示的な allowlist パスまたは承認プロンプトなしにはできません。
カスタムプロファイル例:
__OC_I18N_900005__
`jq` を明示的に `safeBins` にオプトインした場合でも、safe-binモードではOpenClawは `env` builtinを拒否します。そのため、`jq -n env` でホストプロセス環境をダンプするには、明示的なallowlistパスまたは承認プロンプトが必要です。
## Control UI での編集
## Control UIでの編集
**Control UI → Nodes → Exec approvals** カードを使って、デフォルト、エージェント単位の
上書き、および allowlist を編集してください。スコープ（Defaults または agent）を選び、
ポリシーを調整し、allowlist パターンを追加 / 削除してから **Save** を押します。UI には
各パターンごとの **last used** metadata が表示されるため、一覧を整理しやすくなっています。
**Control UI → Nodes → Exec approvals** カードを使って、デフォルト、agentごとの上書き、およびallowlistを編集します。scope（Defaultsまたはagent）を選び、ポリシーを調整し、allowlistパターンを追加/削除して、**Save** を押してください。UIには、リストを整理しやすいように、各パターンの **last used** メタデータが表示されます。
ターゲットセレクターでは **Gateway**（ローカル承認）または **Node** を選びます。Node は
`system.execApprovals.get/set` を広告している必要があります（macOS app または headless node host）。
node がまだ exec approvals を広告していない場合は、そのローカルの
`~/.openclaw/exec-approvals.json` を直接編集してください。
ターゲットセレクターでは、**Gateway**（ローカル承認）または **Node** を選びます。Nodeは `system.execApprovals.get/set` を通知している必要があります（macOS appまたはheadless node host）。
nodeがまだexec承認を通知していない場合は、そのローカルの `~/.openclaw/exec-approvals.json` を直接編集してください。
CLI: `openclaw approvals` は gateway と node の両方の編集をサポートしています（[Approvals CLI](/cli/approvals) を参照）。
CLI: `openclaw approvals` はgatewayまたはnodeの編集をサポートします（[Approvals CLI](/cli/approvals)を参照）。
## 承認フロー
プロンプトが必要な場合、gateway は `exec.approval.requested` を operator client にブロードキャストします。
Control UI と macOS app は `exec.approval.resolve` でこれを処理し、その後 gateway は
承認された要求を node host に転送します。
プロンプトが必要な場合、Gatewayは `exec.approval.requested` をoperatorクライアントへブロードキャストします。
Control UIとmacOS appは `exec.approval.resolve` でこれを解決し、その後Gatewayが承認済み要求をnode hostへ転送します。
`host=node` の場合、承認要求には canonical な `systemRunPlan` ペイロードが含まれます。gateway は
承認済み `system.run` 要求を転送するとき、その plan を authoritative な command / cwd / session コンテキストとして使用します。
`host=node` の場合、承認要求には正規の `systemRunPlan` ペイロードが含まれます。Gatewayは、承認済み `system.run` 要求を転送するとき、このplanを権威あるコマンド/cwd/セッションコンテキストとして使います。
これは async 承認の遅延において重要です。
これは、非同期承認の待機時間において重要です。
- node exec パスは、最初に 1 つの canonical plan を準備します
- 承認レコードには、その plan とバインディング metadata が保存されます
- 一度承認されると、最終的に転送される `system.run` 呼び出しは、
後からの呼び出し元編集を信頼するのではなく、保存済み plan を再利用します
- 承認要求作成後に呼び出し元が `command`、`rawCommand`、`cwd`、`agentId`、または
`sessionKey` を変更した場合、gateway は承認不一致としてその転送実行を拒否します
- node exec経路は、最初に1つの正規planを準備する
- 承認レコードは、そのplanと束縛メタデータを保存する
- 一度承認されると、最終的に転送される `system.run` 呼び出しは、後からの呼び出し元の編集を信頼せず、保存済みplanを再利用する
- 承認要求作成後に呼び出し元が `command`、`rawCommand`、`cwd`、`agentId`、または `sessionKey` を変更すると、Gatewayはその転送実行を承認不一致として拒否する
## インタープリター / ランタイムコマンド
## インタープリター/ランタイムコマンド
承認ベースのインタープリター / ランタイム実行は、意図的に保守的です。
承認付きのインタープリター/ランタイム実行は、意図的に保守的です。
- 正確な argv / cwd / env コンテキストは常に結び付けられます。
- 直接シェルスクリプト形式と直接ランタイムファイル形式は、1 つの具体的なローカル
ファイルスナップショットへの best-effort バインディングが行われます。
- それでも 1 つの直接ローカルファイルに解決される一般的なパッケージマネージャーラッパー形式（たとえば
`pnpm exec`、`pnpm node`、`npm exec`、`npx`）は、バインディング前に展開されます。
- OpenClaw がインタープリター / ランタイムコマンドに対して、正確に 1 つの具体的ローカルファイルを特定できない場合
（たとえば package script、eval 形式、ランタイム固有のローダーチェーン、または曖昧な複数ファイル形式）、
意味論的カバレッジがあると主張するのではなく、承認ベースの実行は拒否されます。
- そのようなワークフローでは、sandbox 化、別の host 境界、または
より広いランタイム意味論をオペレーターが受け入れる明示的 trusted
allowlist / full ワークフローを優先してください。
- 正確なargv/cwd/envコンテキストは常に束縛されます。
- 直接シェルスクリプト形式および直接ランタイムファイル形式は、ベストエフォートで1つの具体的なローカルファイルスナップショットへ束縛されます。
- なお1つの直接ローカルファイルに解決される一般的なpackage managerラッパー形式（例: `pnpm exec`, `pnpm node`, `npm exec`, `npx`）は、束縛前にアンラップされます。
- OpenClawがインタープリター/ランタイムコマンドに対して正確に1つの具体的ローカルファイルを特定できない場合（例: package script、eval形式、ランタイム固有のローダーチェーン、または曖昧な複数ファイル形式）、意味的カバレッジがあると主張する代わりに、承認付き実行は拒否されます。
- そのようなワークフローでは、サンドボックス化、別のホスト境界、またはoperatorがより広いランタイム意味論を受け入れる明示的な信頼済みallowlist/fullワークフローを使ってください。
承認が必要な場合、exec ツールは承認 id を返してすぐに終了します。後で発生する system event
（`Exec finished` / `Exec denied`）との対応付けにはその id を使用してください。タイムアウトまでに決定が届かなければ、
その要求は承認タイムアウトとして扱われ、拒否理由として表面化されます。
承認が必要な場合、execツールは承認idを返して即座に終了します。そのidを使って、後続のsystemイベント（`Exec finished` / `Exec denied`）を関連付けてください。タイムアウトまでに判断が届かなければ、その要求は承認タイムアウトとして扱われ、拒否理由として表示されます。
### followup 配信動作
### フォローアップ配信の挙動
承認済み async exec が終了すると、OpenClaw は同じセッションに followup の `agent` ターンを送信します。
承認済みの非同期execが完了した後、OpenClawは同じセッションへフォローアップの `agent` ターンを送信します。
- 有効な外部配信ターゲットが存在する場合（配信可能なチャネルとターゲット `to`）、followup 配信はそのチャネルを使います。
- 外部ターゲットのない webchat 専用または internal-session フローでは、followup 配信はセッション内のみのままです（`deliver: false`）。
- 呼び出し元が明示的に strict external delivery を要求していて、解決可能な外部チャネルがない場合、要求は `INVALID_REQUEST` で失敗します。
- `bestEffortDeliver` が有効で、外部チャネルを解決できない場合、失敗する代わりに配信はセッション内のみに格下げされます。
- 有効な外部配信ターゲット（配信可能なチャネル + ターゲット `to`）が存在する場合、フォローアップ配信はそのチャネルを使用します。
- 外部ターゲットのないwebchat専用または内部セッションフローでは、フォローアップ配信はセッション専用のままです（`deliver: false`）。
- 呼び出し元が、解決可能な外部チャネルなしで厳密な外部配信を明示的に要求した場合、その要求は `INVALID_REQUEST` で失敗します。
- `bestEffortDeliver` が有効で、外部チャネルを解決できない場合、失敗する代わりに配信はセッション専用へ格下げされます。
確認ダイアログには次が含まれます。
@ -412,158 +361,128 @@ Control UI と macOS app は `exec.approval.resolve` でこれを処理し、そ
- cwd
- agent id
- 解決済み実行ファイルパス
- host + policy metadata
- host + ポリシーメタデータ
操作:
アクション:
- **Allow once** → 今回だけ実行
- **Always allow** → allowlist に追加して実行
- **Always allow** → allowlistに追加して実行
- **Deny** → ブロック
## チャットチャネルへの承認転送
exec 承認プロンプトは任意のチャットチャネル（プラグインチャネルを含む）へ転送でき、
`/approve` で承認できます。これは通常の outbound delivery pipeline を使います。
exec承認プロンプトは、任意のチャットチャネル（プラグインチャネルを含む）へ転送でき、`/approve` で承認できます。これは通常の送信配信パイプラインを使用します。
設定:
__OC_I18N_900005__
チャットでの返信:
__OC_I18N_900006__
`/approve` コマンドは exec 承認と plugin 承認の両方を処理します。ID が保留中の exec 承認に一致しない場合、
自動的に plugin 承認も確認します。
### Plugin 承認の転送
plugin 承認の転送は exec 承認と同じ delivery pipeline を使いますが、
`approvals.plugin` 配下に独立した設定を持ちます。一方を有効 / 無効にしても他方には影響しません。
チャットで返信:
__OC_I18N_900007__
設定形状は `approvals.exec` と同一です。`enabled`、`mode`、`agentFilter`、
`sessionFilter`、`targets` は同じように機能します。
`/approve` コマンドは、exec承認とプラグイン承認の両方を扱います。IDが保留中のexec承認に一致しない場合、自動的にプラグイン承認を確認します。
共有インタラクティブ返信をサポートするチャネルでは、exec と
plugin 承認の両方で同じ承認ボタンが表示されます。共有インタラクティブ UI がないチャネルでは、
`/approve` 手順付きのプレーンテキストにフォールバックします。
### プラグイン承認の転送
プラグイン承認の転送はexec承認と同じ配信パイプラインを使いますが、`approvals.plugin` 配下に独立した設定を持ちます。一方を有効/無効にしても、もう一方には影響しません。
__OC_I18N_900008__
設定形状は `approvals.exec` と同一です。`enabled`、`mode`、`agentFilter`、`sessionFilter`、`targets` は同じように動作します。
共有の対話型返信をサポートするチャネルでは、exec承認とプラグイン承認の両方に同じ承認ボタンが表示されます。共有の対話型UIを持たないチャネルでは、`/approve` 手順付きのプレーンテキストへフォールバックします。
### 任意のチャネルでの同一チャット承認
exec または plugin の承認要求が、配信可能なチャットサーフェスから発生した場合、
同じチャットでデフォルトで `/approve` を使って承認できるようになりました。これは Slack、Matrix、Microsoft Teams など、
既存の Web UI と terminal UI フローに加えたチャネルにも適用されます。
execまたはプラグイン承認要求が配信可能なチャットサーフェスから発生した場合、同じチャットでデフォルトで `/approve` により承認できるようになりました。これは、既存のWeb UIおよびterminal UIフローに加えて、Slack、Matrix、Microsoft Teamsのようなチャネルにも適用されます。
この共有テキストコマンド経路は、その会話の通常のチャネル認証モデルを使います。発生元のチャットが
すでにコマンド送信と返信受信を行えるなら、承認要求を保留にするためだけに
別個のネイティブ delivery adapter は不要です。
この共有テキストコマンド経路は、その会話に対する通常のチャネル認証モデルを使います。発生元チャットがすでにコマンド送信と返信受信を行えるなら、承認要求を保留のままにするためだけに別個のネイティブ配信アダプターは不要です。
Discord と Telegram も同一チャットの `/approve` をサポートしていますが、
それらのチャネルでは、ネイティブ承認配信が無効でも、認可には引き続き解決済み approver 一覧が使われます。
DiscordとTelegramも同一チャットの `/approve` をサポートしますが、これらのチャネルでは、ネイティブ承認配信が無効でも、認可には引き続き解決済みの承認者リストを使います。
Telegram など、Gateway を直接呼び出すネイティブ承認クライアントでは、
このフォールバックは意図的に「approval not found」失敗に限定されています。実際の
exec 承認の拒否 / エラーは、黙って plugin 承認として再試行されることはありません。
Gatewayを直接呼び出すTelegramやその他のネイティブ承認クライアントでは、このフォールバックは意図的に「承認が見つからない」失敗に限定されています。実際のexec承認の拒否/エラーは、黙ってプラグイン承認として再試行されることはありません。
### ネイティブ承認配信
一部のチャネルはネイティブ承認クライアントとしても動作できます。ネイティブクライアントは、
共有の同一チャット `/approve` フローに加えて、approver DM、発生元チャットへの fanout、
チャネル固有のインタラクティブな承認 UX を追加します。
一部のチャネルはネイティブ承認クライアントとしても機能できます。ネイティブクライアントは、共有の同一チャット `/approve` フローに加えて、承認者DM、発生元チャットfanout、チャネル固有の対話型承認UXを追加します。
ネイティブの承認カード / ボタンが利用可能な場合、そのネイティブ UI が
エージェント向けの主経路です。ツール結果がチャット承認を利用できない、または
手動承認が唯一残る経路であると示していない限り、エージェントは重複するプレーンチャットの
`/approve` コマンドを併記すべきではありません。
ネイティブ承認カード/ボタンが利用可能な場合、そのネイティブUIがagent向けの主要経路です。ツール結果にチャット承認が利用できない、または手動承認だけが残された経路だと示されていない限り、agentは重複したプレーンチャットの`/approve`コマンドも併せて出力するべきではありません。
汎用モデル:
一般的なモデル:
- host exec ポリシーは、exec 承認が必要かどうかを引き続き決定します
- `approvals.exec` は、他のチャット宛先への承認プロンプト転送を制御します
- `channels.<channel>.execApprovals` は、そのチャネルがネイティブ承認クライアントとして動作するかを制御します
- exec承認が必要かどうかは、引き続きホストexecポリシーが決定する
- `approvals.exec` は、承認プロンプトを他のチャット宛先へ転送するかどうかを制御する
- `channels.<channel>.execApprovals` は、そのチャネルがネイティブ承認クライアントとして動作するかどうかを制御する
ネイティブ承認クライアントは、以下のすべてが真である場合に、DM-first 配信を自動有効化します。
ネイティブ承認クライアントは、次のすべてが真の場合に、DM-first配信を自動有効化します。
- そのチャネルがネイティブ承認配信をサポートしている
- 明示的な `execApprovals.approvers` またはそのチャネルの文書化された
fallback source から approver を解決できる
- `channels.<channel>.execApprovals.enabled` が未設定または `"auto"` である
- 明示的な `execApprovals.approvers` またはそのチャネルで文書化されたフォールバックソースから承認者を解決できる
- `channels.<channel>.execApprovals.enabled` が未設定、または `"auto"` である
ネイティブ承認クライアントを明示的に無効にするには `enabled: false` を設定してください。approver が解決される場合に
強制的に有効にするには `enabled: true` を設定してください。公開の発生元チャット配信は
`channels.<channel>.execApprovals.target` によって明示的に制御されます。
ネイティブ承認クライアントを明示的に無効にするには `enabled: false` を設定します。承認者が解決できるときに強制的に有効にするには `enabled: true` を設定します。公開の発生元チャット配信は、引き続き `channels.<channel>.execApprovals.target` で明示的に制御します。
FAQ: [チャット承認用に exec 承認設定が 2 つあるのはなぜですか？](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
FAQ: [チャット承認にexec承認設定が2つあるのはなぜですか？](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
- Discord: `channels.discord.execApprovals.*`
- Slack: `channels.slack.execApprovals.*`
- Telegram: `channels.telegram.execApprovals.*`
これらのネイティブ承認クライアントは、共有の
同一チャット `/approve` フローと共有承認ボタンに加えて、DM ルーティングと任意のチャネル fanout を追加します。
これらのネイティブ承認クライアントは、共有の同一チャット `/approve` フローと共有承認ボタンの上に、DMルーティングとオプションのチャネルfanoutを追加します。
共有動作:
共有される動作:
- Slack、Matrix、Microsoft Teams などの配信可能なチャットでは、
同一チャット `/approve` に通常のチャネル認証モデルが使われます
- ネイティブ承認クライアントが自動有効化された場合、デフォルトのネイティブ配信先は approver DM です
- Discord と Telegram では、解決済み approver だけが承認または拒否できます
- Discord の approver は、明示的（`execApprovals.approvers`）または `commands.ownerAllowFrom` から推測できます
- Telegram の approver は、明示的（`execApprovals.approvers`）または既存の owner 設定
（`allowFrom`、およびサポートされる場合は direct-message の `defaultTo`）から推測できます
- Slack の approver は、明示的（`execApprovals.approvers`）または `commands.ownerAllowFrom` から推測できます
- Slack のネイティブボタンは承認 id の種類を保持するため、`plugin:` id は
2 段目の Slack ローカルフォールバック層なしで plugin 承認に解決できます
- Matrix のネイティブ DM / channel ルーティングとリアクションショートカットは exec と plugin 承認の両方を扱います。
plugin の認可は引き続き `channels.matrix.dm.allowFrom` に由来します
- 要求者自身が approver である必要はありません
- 発生元チャットがすでにコマンドと返信をサポートしていれば、発生元チャットは `/approve` で直接承認できます
- ネイティブ Discord 承認ボタンは承認 id の種類でルーティングします。`plugin:` id は
直接 plugin 承認に進み、それ以外はすべて exec 承認に進みます
- ネイティブ Telegram 承認ボタンは、`/approve` と同じ限定的な exec→plugin フォールバックに従います
- ネイティブ `target` が発生元チャット配信を有効にすると、承認プロンプトにはコマンドテキストが含まれます
- 保留中の exec 承認はデフォルトで 30 分後に期限切れになります
- オペレーター UI や設定済み承認クライアントのいずれも要求を受け取れない場合、プロンプトは `askFallback` にフォールバックします
- Slack、Matrix、Microsoft Teams、および同様の配信可能なチャットは、同一チャット `/approve` に通常のチャネル認証モデルを使う
- ネイティブ承認クライアントが自動有効化されると、デフォルトのネイティブ配信先は承認者DMになる
- DiscordとTelegramでは、解決済み承認者だけが承認または拒否できる
- Discord承認者は、明示的（`execApprovals.approvers`）または `commands.ownerAllowFrom` から推定できる
- Telegram承認者は、明示的（`execApprovals.approvers`）または既存のowner設定（`allowFrom`、およびサポートされる場合はダイレクトメッセージの`defaultTo`）から推定できる
- Slack承認者は、明示的（`execApprovals.approvers`）または `commands.ownerAllowFrom` から推定できる
- Slackネイティブボタンは承認idのkindを保持するため、`plugin:` idは2つ目のSlackローカルフォールバック層なしでプラグイン承認へ解決できる
- MatrixのネイティブDM/チャネルルーティングとリアクションショートカットは、exec承認とプラグイン承認の両方を扱う。プラグイン認可は引き続き `channels.matrix.dm.allowFrom` から来る
- 要求者が承認者である必要はない
- 発生元チャットがすでにコマンドと返信をサポートしている場合、そのチャットから直接 `/approve` で承認できる
- ネイティブDiscord承認ボタンは承認id kindでルーティングする: `plugin:` idは直接プラグイン承認へ、それ以外はすべてexec承認へ進む
- ネイティブTelegram承認ボタンは、`/approve` と同じ限定的なexec-to-pluginフォールバックに従う
- ネイティブ `target` が発生元チャット配信を有効にすると、承認プロンプトにはコマンドテキストが含まれる
- 保留中のexec承認はデフォルトで30分後に期限切れになる
- operator UIまたは設定済み承認クライアントのどれも要求を受け付けられない場合、プロンプトは `askFallback` へフォールバックする
Telegram のデフォルトは approver DM（`target: "dm"`）です。承認プロンプトも発生元の Telegram チャット / topic に
表示したい場合は、`channel` または `both` に切り替えられます。Telegram forum
topics では、OpenClaw は承認プロンプトと承認後の follow-up の両方で topic を維持します。
Telegramのデフォルトは承認者DM（`target: "dm"`）です。承認プロンプトを発生元のTelegramチャット/トピックにも表示したい場合は、`channel` または `both` に切り替えられます。Telegramフォーラムトピックでは、OpenClawは承認プロンプトと承認後フォローアップの両方でトピックを保持します。
参照:
- [Discord](/channels/discord)
- [Telegram](/channels/telegram)
### macOS IPC フロー
__OC_I18N_900008__
### macOS IPCフロー
__OC_I18N_900009__
セキュリティに関する注意:
- Unix socket のモードは `0600`、token は `exec-approvals.json` に保存されます。
- 同一 UID の peer チェック。
- challenge/response（nonce + HMAC token + request hash）+ 短い TTL。
- Unixソケットモードは `0600`、トークンは `exec-approvals.json` に保存される。
- 同一UIDピアチェック。
- Challenge/response（nonce + HMACトークン + リクエストハッシュ）+ 短いTTL。
## システムイベント
Exec のライフサイクルは system message として表面化されます。
execライフサイクルは、システムメッセージとして表示されます。
- `Exec running`（コマンドが running notice threshold を超えた場合のみ）
- `Exec running`（コマンドが実行中通知しきい値を超えた場合のみ）
- `Exec finished`
- `Exec denied`
これらは、node がイベントを報告した後、エージェントのセッションに投稿されます。
gateway-host exec 承認でも、コマンド終了時（および任意で、しきい値より長く動作した場合の実行中）に同じライフサイクルイベントが発行されます。
承認ゲート付き exec では、対応付けを容易にするため、これらのメッセージ内の `runId` として承認 id が再利用されます。
これらは、nodeがイベントを報告した後にagentのセッションへ投稿されます。
Gateway hostのexec承認も、コマンド完了時に同じライフサイクルイベントを出します（しきい値より長く実行中の場合はオプションで実行中イベントも出します）。
承認ゲート付きexecは、関連付けしやすいように、これらのメッセージで承認idを `runId` として再利用します。
## 拒否された承認の動作
## 拒否された承認時の挙動
async exec 承認が拒否された場合、OpenClaw は、セッション内で以前に同じコマンドを実行した
古い結果をエージェントが再利用できないようにします。拒否理由は、利用可能なコマンド出力がないという明示的なガイダンス付きで渡されるため、
新しい出力があるかのように主張したり、以前の成功実行の古い結果を使って拒否されたコマンドを繰り返したりするのを防ぎます。
非同期exec承認が拒否された場合、OpenClawはagentがそのセッション内で同じコマンドの過去の実行結果を再利用するのを防ぎます。
拒否理由は、コマンド出力が利用できないことを明示するガイダンス付きで渡されます。これにより、agentが新しい出力があると主張したり、以前に成功した実行の古い結果を使って拒否されたコマンドを繰り返したりするのを防ぎます。
## 影響
- **full** は強力です。可能な限り allowlist を優先してください。
- **ask** を使うと、高速な承認を維持しつつ、人間がループに入れます。
- エージェント単位の allowlist により、あるエージェントの承認が他のエージェントへ漏れるのを防げます。
- 承認は、**認可された送信者** からの host exec 要求にのみ適用されます。未認可の送信者は `/exec` を発行できません。
- `/exec security=full` は認可済みオペレーター向けのセッション単位の利便機能であり、設計上承認をスキップします。
host exec を完全に禁止したい場合は、承認 security を `deny` に設定するか、ツールポリシーで `exec` ツールを拒否してください。
- **full** は強力です。可能な限りallowlistを優先してください。
- **ask** を使うと、高速に承認しつつ利用者が状況を把握できます。
- agentごとのallowlistにより、あるagentの承認が他のagentへ漏れるのを防げます。
- 承認は、**認可された送信者**からのホストexec要求にのみ適用されます。認可されていない送信者は `/exec` を発行できません。
- `/exec security=full` は認可済みoperator向けのセッションレベル便宜機能であり、設計上承認をスキップします。
ホストexecを強制的にブロックしたい場合は、承認securityを `deny` に設定するか、ツールポリシーで `exec` ツールを拒否してください。
関連:
@ -574,6 +493,6 @@ async exec 承認が拒否された場合、OpenClaw は、セッション内で
## 関連
- [Exec](/ja-JP/tools/exec) — シェルコマンド実行ツール
- [Sandboxing](/ja-JP/gateway/sandboxing) — sandbox モードとワークスペースアクセス
- [Sandboxing](/ja-JP/gateway/sandboxing) — サンドボックスモードとワークスペースアクセス
- [Security](/ja-JP/gateway/security) — セキュリティモデルとハードニング
- [Sandbox vs Tool Policy vs Elevated](/ja-JP/gateway/sandbox-vs-tool-policy-vs-elevated) — それぞれをいつ使うか

54
docs/ja-JP/tools/reactions.md
View File

@ -1,22 +1,22 @@
---
read_when:
- 任意のチャンネルでリアクションに取り組んでいる
- 絵文字リアクションがプラットフォームごとにどう異なるかを理解したい
summary: サポートされているすべてのチャンネルにおけるリアクションツールのセマンティクス
- 任意の channel でリアクション機能を扱うこと
- 絵文字リアクションがプラットフォームごとにどう異なるかを理解すること
summary: サポートされているすべての channels における reaction tool のセマンティクス
title: リアクション
x-i18n:
generated_at: "2026-04-05T13:00:20Z"
generated_at: "2026-04-11T02:48:35Z"
model: gpt-5.4
provider: openai
source_hash: 9af2951eee32e73adb982dbdf39b32e4065993454e9cce2ad23b27565cab4f84
source_hash: cfac31b7f0effc89cc696e3cf34cd89503ccdbb28996723945025e4b6e159986
source_path: tools/reactions.md
workflow: 15
---
# リアクション
エージェントは、`message`
ツールの `react` アクションを使って、メッセージに絵文字リアクションを追加および削除できます。リアクションの動作はチャンネルごとに異なります。
agent は `message`
tool の `react` アクションを使って、メッセージに絵文字リアクションを追加および削除できます。リアクションの動作は channel によって異なります。
## 仕組み
@ -29,30 +29,30 @@ x-i18n:
```
- リアクションを追加する場合、`emoji` は必須です。
- ボットのリアクションを削除するには、`emoji` を空文字列（`""`）に設定します。
- 特定の絵文字を削除するには `remove: true` を設定します（空でない `emoji` が必要です）。
- bot のリアクションを削除するには、`emoji` を空文字列（`""`）に設定します。
- 特定の絵文字を削除するには、`remove: true` を設定します（空でない `emoji` が必要です）。
## チャンネルごとの動作
## Channel ごとの動作
<AccordionGroup>
<Accordion title="Discord and Slack">
- 空の `emoji` は、そのメッセージ上のボットのすべてのリアクションを削除します。
- `remove: true` は、指定した絵文字だけを削除します。
<Accordion title="Discord と Slack">
- 空の `emoji` は、そのメッセージ上の bot のリアクションをすべて削除します。
- `remove: true` は、指定された絵文字だけを削除します。
</Accordion>
<Accordion title="Google Chat">
- 空の `emoji` は、そのメッセージ上のアプリのリアクションを削除します。
- `remove: true` は、指定した絵文字だけを削除します。
- 空の `emoji` は、そのメッセージ上の app のリアクションを削除します。
- `remove: true` は、指定された絵文字だけを削除します。
</Accordion>
<Accordion title="Telegram">
- 空の `emoji` は、ボットのリアクションを削除します。
- `remove: true` もリアクションを削除しますが、ツールのバリデーション上は引き続き空でない `emoji` が必要です。
- 空の `emoji` は、bot のリアクションを削除します。
- `remove: true` でもリアクションは削除されますが、tool の検証上は引き続き空でない `emoji` が必要です。
</Accordion>
<Accordion title="WhatsApp">
- 空の `emoji` は、ボットのリアクションを削除します。
- `remove: true` は内部的に空の絵文字にマップされます（それでもツール呼び出しでは `emoji` が必要です）。
- 空の `emoji` は、bot のリアクションを削除します。
- `remove: true` は内部的に空の絵文字へマップされます（それでも tool 呼び出しでは `emoji` が必要です）。
</Accordion>
<Accordion title="Zalo Personal (zalouser)">
@ -61,25 +61,25 @@ x-i18n:
</Accordion>
<Accordion title="Feishu/Lark">
- `add`、`remove`、`list` アクションを持つ `feishu_reaction` ツールを使います。
- 追加/削除には `emoji_type` が必要で、削除にはさらに `reaction_id` も必要です。
- `add`、`remove`、`list` アクションを持つ `feishu_reaction` tool を使用します。
- 追加/削除には `emoji_type` が必要で、削除では `reaction_id` も必要です。
</Accordion>
<Accordion title="Signal">
- 受信リアクション通知は `channels.signal.reactionNotifications` で制御されます: `"off"` で無効、`"own"`（デフォルト）でユーザーがボットメッセージにリアクションしたときにイベントを発行、`"all"` ですべてのリアクションに対してイベントを発行します。
- 受信リアクション通知は `channels.signal.reactionNotifications` によって制御されます。`"off"` は無効化、`"own"`（デフォルト）はユーザーが bot メッセージにリアクションしたときにイベントを発行し、`"all"` はすべてのリアクションに対してイベントを発行します。
</Accordion>
</AccordionGroup>
## リアクションレベル
チャンネルごとの `reactionLevel` 設定は、エージェントがどの程度広くリアクションを使うかを制御します。値は通常 `off`、`ack`、`minimal`、または `extensive` です。
channel ごとの `reactionLevel` 設定は、agent がどの程度広くリアクションを使うかを制御します。値は通常 `off`、`ack`、`minimal`、または `extensive` です。
- [Telegram reactionLevel](/ja-JP/channels/telegram#reaction-notifications) — `channels.telegram.reactionLevel`
- [WhatsApp reactionLevel](/ja-JP/channels/whatsapp#reactions) — `channels.whatsapp.reactionLevel`
- [WhatsApp reactionLevel](/ja-JP/channels/whatsapp#reaction-level) — `channels.whatsapp.reactionLevel`
各チャンネルで `reactionLevel` を設定して、各プラットフォームでエージェントがどの程度積極的にメッセージへリアクションするかを調整してください。
個別の channel に `reactionLevel` を設定して、各プラットフォームで agent がどの程度積極的にメッセージへリアクションするかを調整してください。
## 関連
- [エージェント送信](/tools/agent-send) — `react` を含む `message` ツール
- [チャンネル](/ja-JP/channels) — チャンネル固有の設定
- [Agent Send](/ja-JP/tools/agent-send) — `react` を含む `message` tool
- [Channels](/ja-JP/channels) — channel 固有の設定

384
docs/ja-JP/tools/skills.md
View File

@ -1,64 +1,63 @@
---
read_when:
- Skills を追加または変更している
- Skill のゲーティングまたはロードルールを変更している
summary: 'Skills: managed と workspace、ゲーティングルール、設定/env の配線'
- Skillsを追加または変更すること
- Skillのゲーティングまたは読み込みルールを変更すること
summary: 'Skills: 管理対象とワークスペース、ゲーティングルール、および設定/環境変数の配線'
title: Skills
x-i18n:
generated_at: "2026-04-05T13:01:22Z"
generated_at: "2026-04-11T02:48:50Z"
model: gpt-5.4
provider: openai
source_hash: 6bb0e2e7c2ff50cf19c759ea1da1fd1886dc11f94adc77cbfd816009f75d93ee
source_hash: b1eaf130966950b6eb24f859d9a77ecbf81c6cb80deaaa6a3a79d2c16d83115d
source_path: tools/skills.md
workflow: 15
---
# Skills（OpenClaw）
OpenClaw は、エージェントにツールの使い方を教えるために **[AgentSkills](https://agentskills.io) 互換** の skill フォルダーを使用します。各 skill は、YAML frontmatter と説明を含む `SKILL.md` を持つディレクトリです。OpenClaw は **バンドル済み Skills** と任意のローカル上書きを読み込み、環境、設定、バイナリーの存在に基づいてロード時にそれらをフィルタリングします。
OpenClawは、エージェントにツールの使い方を教えるために**[AgentSkills](https://agentskills.io)互換**のskillフォルダーを使用します。各skillは、YAML frontmatterと指示を含む`SKILL.md`を持つディレクトリです。OpenClawは**バンドル版skills**と任意のローカル上書きを読み込み、環境、設定、バイナリの有無に基づいて読み込み時にフィルタリングします。
## 場所と優先順位
OpenClaw は次のソースから Skills を読み込みます。
OpenClawは以下のソースからskillsを読み込みます:
1. **追加 skill フォルダー**: `skills.load.extraDirs` で設定
2. **バンドル済み Skills**: インストールに同梱（npm パッケージまたは OpenClaw.app）
3. **managed/local Skills**: `~/.openclaw/skills`
4. **個人エージェント Skills**: `~/.agents/skills`
5. **プロジェクトエージェント Skills**: `<workspace>/.agents/skills`
6. **workspace Skills**: `<workspace>/skills`
1. **追加skillフォルダー**: `skills.load.extraDirs`で設定
2. **バンドル版skills**: インストール物（npmパッケージまたはOpenClaw.app）に同梱
3. **managed/local skills**: `~/.openclaw/skills`
4. **個人エージェントskills**: `~/.agents/skills`
5. **プロジェクトエージェントskills**: `<workspace>/.agents/skills`
6. **ワークスペースskills**: `<workspace>/skills`
skill 名が競合する場合の優先順位は次のとおりです。
skill名が競合した場合の優先順位は次のとおりです:
`<workspace>/skills`（最高）→ `<workspace>/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → バンドル済み Skills → `skills.load.extraDirs`（最低）
`<workspace>/skills`（最優先）→ `<workspace>/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → バンドル版skills → `skills.load.extraDirs`（最低優先）
## エージェント単位の Skills と共有 Skills
## エージェントごとのskillsと共有skills
**マルチエージェント** 構成では、各エージェントは独自の workspace を持ちます。つまり:
**マルチエージェント**構成では、各エージェントはそれぞれのワークスペースを持ちます。つまり:
- **エージェント単位の Skills** は、そのエージェント専用の `<workspace>/skills` にあります。
- **プロジェクトエージェント Skills** は `<workspace>/.agents/skills` にあり、
通常の workspace `skills/` フォルダーより前にその workspace に適用されます。
- **個人エージェント Skills** は `~/.agents/skills` にあり、
そのマシン上の複数 workspace にまたがって適用されます。
- **共有 Skills** は `~/.openclaw/skills`（managed/local）にあり、
同じマシン上の **すべてのエージェント** から見えます。
- 複数エージェントで使う共通の Skills パックが必要なら、
`skills.load.extraDirs`（最低優先度）で **共有フォルダー** を追加することもできます。
- **エージェントごとのskills**は、そのエージェント専用の`<workspace>/skills`に置かれます。
- **プロジェクトエージェントskills**は`<workspace>/.agents/skills`に置かれ、
通常のワークスペース`skills/`フォルダーより前にそのワークスペースへ適用されます。
- **個人エージェントskills**は`~/.agents/skills`に置かれ、
そのマシン上のワークスペースをまたいで適用されます。
- **共有skills**は`~/.openclaw/skills`（managed/local）に置かれ、同じマシン上の**すべてのエージェント**から見えます。
- **共有フォルダー**は、複数のエージェントで使う共通skillsパックが欲しい場合、
`skills.load.extraDirs`（最低優先）経由でも追加できます。
同じ skill 名が複数の場所に存在する場合は、通常の優先順位が
適用されます: workspace が優先され、その次が project agent Skills、personal agent skills、
managed/local、bundled、extra dirs の順です。
同じskill名が複数の場所に存在する場合は、通常の優先順位が適用されます:
workspaceが勝ち、その次にプロジェクトエージェントskills、個人エージェントskills、
managed/local、バンドル版、extra dirsの順です。
## エージェント Skill allowlist
## エージェントskill許可リスト
Skill の **場所** と Skill の **可視性** は別の制御です。
skillの**配置場所**とskillの**可視性**は別の制御です。
- 場所/優先順位は、同名 skill のどのコピーが勝つかを決定します。
- エージェント allowlist は、可視な Skills のうちそのエージェントが実際に使えるものを決定します。
- 配置場所/優先順位は、同名skillのどのコピーが勝つかを決定します。
- エージェント許可リストは、可視なskillsのうち、そのエージェントが実際にどれを使えるかを決定します。
共有ベースラインには `agents.defaults.skills` を使い、エージェント単位の上書きには
`agents.list[].skills` を使います。
共通のベースラインには`agents.defaults.skills`を使用し、その後
`agents.list[].skills`でエージェントごとに上書きします:
```json5
{
@ -67,9 +66,9 @@ Skill の **場所** と Skill の **可視性** は別の制御です。
skills: ["github", "weather"],
},
list: [
{ id: "writer" }, // github, weather を継承
{ id: "docs", skills: ["docs-search"] }, // defaults を置き換える
{ id: "locked-down", skills: [] }, // Skills なし
{ id: "writer" }, // github, weatherを継承
{ id: "docs", skills: ["docs-search"] }, // デフォルトを置き換える
{ id: "locked-down", skills: [] }, // skillsなし
],
},
}
@ -77,62 +76,66 @@ Skill の **場所** と Skill の **可視性** は別の制御です。
ルール:
- デフォルトで Skills を無制限にするには `agents.defaults.skills` を省略します。
- `agents.defaults.skills` を継承するには `agents.list[].skills` を省略します。
- Skills なしにするには `agents.list[].skills: []` を設定します。
- 空でない `agents.list[].skills` リストはそのエージェントの最終セットであり、
defaults とはマージされません。
- デフォルトでskillsを無制限にするには`agents.defaults.skills`を省略します。
- `agents.defaults.skills`を継承するには`agents.list[].skills`を省略します。
- skillsなしにするには`agents.list[].skills: []`を設定します。
- 空でない`agents.list[].skills`リストは、そのエージェントの最終セットになります。
デフォルトとはマージされません。
OpenClaw は、有効なエージェント Skill セットを、プロンプト構築、Skill の
slash-command 検出、sandbox sync、および Skill snapshot 全体に適用します。
OpenClawは、有効なエージェントskillセットを、プロンプト構築、skillスラッシュコマンド検出、
サンドボックス同期、およびskillスナップショット全体に適用します。
## Plugins + Skills
## プラグイン + skills
Plugins は、`openclaw.plugin.json` に `skills` ディレクトリを列挙することで
独自の Skills を同梱できます（plugin ルートからの相対パス）。plugin の Skills は
plugin が有効なときに読み込まれます。現時点では、それらのディレクトリは
`skills.load.extraDirs` と同じ低優先度パスにマージされるため、同名の bundled、
managed、agent、または workspace skill がそれらを上書きします。
plugin の設定エントリ上で `metadata.openclaw.requires.config` によりゲートできます。
検出/設定については [Plugins](/tools/plugin)、それらの Skills が教える
ツールサーフェスについては [Tools](/tools) を参照してください。
プラグインは、`openclaw.plugin.json`に`skills`ディレクトリ
（プラグインルートからの相対パス）を列挙することで独自のskillsを同梱できます。プラグインskillsは、そのプラグインが有効なときに読み込まれます。現在、
これらのディレクトリは`skills.load.extraDirs`と同じ低優先順位のパスへマージされるため、
同名のバンドル版、managed、agent、またはworkspace skillがそれらを上書きします。
これらはプラグイン設定エントリーの`metadata.openclaw.requires.config`
でゲートできます。検出/設定については[Plugins](/ja-JP/tools/plugin)を、これらのskillsが教える
ツールサーフェスについては[Tools](/ja-JP/tools)を参照してください。
## ClawHub（インストール + 同期）
ClawHub は OpenClaw の公開 Skills レジストリです。
[https://clawhub.ai](https://clawhub.ai) で参照できます。Skills の検出/インストール/更新には
ネイティブの `openclaw skills`
コマンドを使用し、公開/同期ワークフローが必要な場合は別の `clawhub` CLI を使ってください。
完全ガイド: [ClawHub](/tools/clawhub)。
ClawHubはOpenClaw向けの公開skillsレジストリです。
[https://clawhub.ai](https://clawhub.ai)で閲覧できます。ネイティブの`openclaw skills`
コマンドを使ってskillsを検出/インストール/更新するか、公開/同期ワークフローが必要な場合は
別の`clawhub` CLIを使用してください。
完全ガイド: [ClawHub](/ja-JP/tools/clawhub)。
一般的なフロー:
- workspace に skill をインストールする:
- skillをワークスペースにインストールする:
- `openclaw skills install <skill-slug>`
- インストール済みのすべての Skills を更新する:
- インストール済みskillsをすべて更新する:
- `openclaw skills update --all`
- 同期する（スキャン + 更新を公開）:
- `clawhub sync --all`
ネイティブの `openclaw skills install` は、アクティブな workspace の `skills/`
ディレクトリにインストールします。別個の `clawhub` CLI も、現在の作業ディレクトリ配下の `./skills`
にインストールします（または設定済みの OpenClaw workspace にフォールバックします）。
OpenClaw は次のセッションでそれを `<workspace>/skills` として検出します。
ネイティブの`openclaw skills install`は、アクティブなワークスペースの`skills/`
ディレクトリへインストールします。別の`clawhub` CLIも、現在の作業ディレクトリ配下の`./skills`
へインストールし（または設定済みOpenClawワークスペースへフォールバックし）、
OpenClawは次のセッションでそれを`<workspace>/skills`として認識します。
## セキュリティ上の注意
## セキュリティに関する注意
- サードパーティの Skills は **信頼されていないコード** として扱ってください。有効化する前に読んでください。
- 信頼できない入力や危険なツールには sandboxed 実行を優先してください。[Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。
- workspace と extra-dir の skill 検出では、解決された realpath が設定済みルート内にとどまる skill ルートと `SKILL.md` ファイルのみを受け付けます。
- Gateway バックの skill 依存関係インストール（`skills.install`、オンボーディング、および Skills 設定 UI）は、installer metadata を実行する前に組み込みの dangerous-code scanner を実行します。`critical` な検出結果は、呼び出し側が明示的に dangerous override を設定しない限り、デフォルトでブロックされます。疑わしい検出結果は警告のみです。
- `openclaw skills install <slug>` は異なります。これは ClawHub の skill フォルダーを workspace にダウンロードし、上記の installer-metadata パスは使用しません。
- `skills.entries.*.env` と `skills.entries.*.apiKey` は、そのエージェントターンに対して **host** プロセスへ secret を注入します
（sandbox ではありません）。secret をプロンプトやログに含めないでください。
- より広い脅威モデルとチェックリストについては [Security](/ja-JP/gateway/security) を参照してください。
- サードパーティskillsは**信頼されていないコード**として扱ってください。有効化する前に読んでください。
- 信頼されていない入力や危険なツールには、サンドボックス実行を優先してください。[Sandboxing](/ja-JP/gateway/sandboxing)を参照してください。
- ワークスペースおよびextra-dirのskill検出は、解決後のrealpathが設定済みルート内に収まる
skillルートと`SKILL.md`ファイルのみを受け付けます。
- Gatewayバックエンドのskill依存関係インストール（`skills.install`、オンボーディング、
Skills設定UI）は、インストーラーメタデータ実行前に組み込みの危険コードスキャナーを実行します。
`critical`所見は、呼び出し側が明示的に危険上書きを設定しない限りデフォルトでブロックされます。
suspicious所見は警告のみです。
- `openclaw skills install <slug>`は異なります。これはClawHubのskillフォルダーをワークスペースへダウンロードするだけで、
上記のインストーラーメタデータ経路は使用しません。
- `skills.entries.*.env`と`skills.entries.*.apiKey`は、そのエージェントターンについてシークレットを**ホスト**
プロセスへ注入します（サンドボックスではありません）。シークレットをプロンプトやログに入れないでください。
- より広い脅威モデルとチェックリストについては、[Security](/ja-JP/gateway/security)を参照してください。
## 形式（AgentSkills + Pi 互換）
## 形式（AgentSkills + Pi互換）
`SKILL.md` には少なくとも次が必要です。
`SKILL.md`には最低限、以下を含める必要があります:
```markdown
---
@ -141,26 +144,26 @@ description: Generate or edit images via a provider-backed image workflow
---
```
補足:
注記:
- レイアウト/意図については AgentSkills 仕様に従っています。
- 組み込みエージェントで使われる parser は **single-line** frontmatter キーのみをサポートします。
- `metadata` は **single-line JSON object** である必要があります。
- skill フォルダーパスを参照するには、説明内で `{baseDir}` を使用してください。
- 任意の frontmatter キー:
- `homepage` — macOS Skills UI で「Website」として表示される URL（`metadata.openclaw.homepage` 経由でもサポート）。
- `user-invocable` — `true|false`（デフォルト: `true`）。`true` の場合、この skill はユーザー slash command として公開されます。
- `disable-model-invocation` — `true|false`（デフォルト: `false`）。`true` の場合、この skill は model prompt から除外されます（ユーザー呼び出しでは引き続き利用可能）。
- `command-dispatch` — `tool`（任意）。`tool` に設定すると、slash command は model をバイパスしてツールへ直接ディスパッチされます。
- `command-tool` — `command-dispatch: tool` が設定されているときに呼び出すツール名。
- `command-arg-mode` — `raw`（デフォルト）。ツールディスパッチでは、生の args 文字列をそのままツールへ転送します（core 側の解析なし）。
- レイアウト/意図についてはAgentSkills仕様に従います。
- 埋め込みエージェントで使われるパーサーは、**単一行**のfrontmatterキーのみをサポートします。
- `metadata`は**単一行JSONオブジェクト**である必要があります。
- skillフォルダーパスを参照するには、指示内で`{baseDir}`を使用してください。
- 任意のfrontmatterキー:
- `homepage` — macOS Skills UIで「Website」として表示されるURL（`metadata.openclaw.homepage`経由でもサポート）。
- `user-invocable` — `true|false`（デフォルト: `true`）。`true`の場合、このskillはユーザースラッシュコマンドとして公開されます。
- `disable-model-invocation` — `true|false`（デフォルト: `false`）。`true`の場合、このskillはモデルプロンプトから除外されます（ユーザー呼び出しでは引き続き利用可能）。
- `command-dispatch` — `tool`（任意）。`tool`に設定すると、スラッシュコマンドはモデルをバイパスし、直接ツールへディスパッチします。
- `command-tool` — `command-dispatch: tool`が設定されているときに呼び出すツール名。
- `command-arg-mode` — `raw`（デフォルト）。ツールディスパッチ時、rawの引数文字列をそのままツールへ転送します（コアによる解析なし）。
ツールは次の params で呼び出されます:
ツールは以下のparamsで呼び出されます:
`{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`。
## ゲーティング（ロード時フィルター）
## ゲーティング（読み込み時フィルター）
OpenClaw は `metadata`（single-line JSON）を使って **ロード時に Skills をフィルタリング** します。
OpenClawは、`metadata`（単一行JSON）を使って**読み込み時にskillsをフィルタリング**します:
```markdown
---
@ -177,30 +180,31 @@ metadata:
---
```
`metadata.openclaw` 配下のフィールド:
`metadata.openclaw`配下のフィールド:
- `always: true` — 常にその skill を含めます（他のゲートをスキップ）。
- `emoji` — macOS Skills UI で使われる任意の絵文字。
- `homepage` — macOS Skills UI で「Website」として表示される任意の URL。
- `os` — 任意のプラットフォーム一覧（`darwin`、`linux`、`win32`）。設定されている場合、その skill はその OS でのみ対象になります。
- `requires.bins` — 一覧。各項目が `PATH` 上に存在する必要があります。
- `requires.anyBins` — 一覧。少なくとも 1 つが `PATH` 上に存在する必要があります。
- `requires.env` — 一覧。env var が存在する **か**、設定で提供されている必要があります。
- `requires.config` — truthy でなければならない `openclaw.json` パスの一覧。
- `primaryEnv` — `skills.entries.<name>.apiKey` に関連付けられる env var 名。
- `install` — macOS Skills UI で使われる installer spec の任意配列（brew/node/go/uv/download）。
- `always: true` — skillを常に含める（他のゲートをスキップ）。
- `emoji` — macOS Skills UIで使われる任意の絵文字。
- `homepage` — macOS Skills UIで「Website」として表示される任意のURL。
- `os` — 任意のプラットフォーム一覧（`darwin`, `linux`, `win32`）。設定されている場合、そのOS上でのみskillが有効候補になります。
- `requires.bins` — 一覧。各項目が`PATH`上に存在しなければなりません。
- `requires.anyBins` — 一覧。少なくとも1つが`PATH`上に存在しなければなりません。
- `requires.env` — 一覧。環境変数が存在する**か**、設定で提供されていなければなりません。
- `requires.config` — truthyでなければならない`openclaw.json`パスの一覧。
- `primaryEnv` — `skills.entries.<name>.apiKey`に関連付けられる環境変数名。
- `install` — macOS Skills UIで使われる任意のインストーラー仕様配列（brew/node/go/uv/download）。
sandboxing に関する補足:
サンドボックスに関する注記:
- `requires.bins` は、skill ロード時に **host** 上でチェックされます。
- エージェントが sandboxed の場合、そのバイナリーは **container 内にも** 存在する必要があります。
`agents.defaults.sandbox.docker.setupCommand`（または custom image）でインストールしてください。
`setupCommand` は container 作成後に 1 回実行されます。
パッケージインストールには、network egress、書き込み可能な root FS、そして sandbox 内の root ユーザーも必要です。
例: `summarize` skill（`skills/summarize/SKILL.md`）がそこで実行されるには、
`summarize` CLI が sandbox container 内に必要です。
- `requires.bins`は、skill読み込み時に**ホスト**上で確認されます。
- エージェントがサンドボックス化されている場合、そのバイナリは**コンテナ内にも**
存在しなければなりません。
`agents.defaults.sandbox.docker.setupCommand`（またはカスタムイメージ）経由でインストールしてください。
`setupCommand`は、コンテナ作成後に1回だけ実行されます。
パッケージインストールには、ネットワークegress、書き込み可能なルートFS、およびサンドボックス内のrootユーザーも必要です。
例: `summarize` skill（`skills/summarize/SKILL.md`）は、そこで実行するには
サンドボックスコンテナ内に`summarize` CLIが必要です。
installer の例:
インストーラー例:
```markdown
---
@ -227,28 +231,30 @@ metadata:
---
```
補足:
注記:
- 複数の installer が列挙されている場合、gateway は **単一の** 優先オプションを選びます（brew が利用可能なら brew、そうでなければ node）。
- すべての installer が `download` の場合、OpenClaw は利用可能なアーティファクトを見られるよう各エントリを列挙します。
- installer spec には `os: ["darwin"|"linux"|"win32"]` を含めて、プラットフォーム別に選択肢をフィルタリングできます。
- Node インストールは `openclaw.json` 内の `skills.install.nodeManager` に従います（デフォルト: npm。選択肢: npm/pnpm/yarn/bun）。
これは **skill インストール** にのみ影響します。Gateway ランタイムは引き続き Node
であるべきです（WhatsApp/Telegram では Bun は推奨されません）。
- Gateway バックの installer 選択は node-only ではなく、優先度駆動です:
install spec に複数 kind が混在している場合、OpenClaw は
`skills.install.preferBrew` が有効で `brew` が存在すれば Homebrew を優先し、その後 `uv`、次に設定済みの node manager、その後 `go` や `download` などの他のフォールバックを使います。
- すべての install spec が `download` の場合、OpenClaw は 1 つの優先 installer にまとめず、
すべての download オプションを表示します。
- Go インストール: `go` がなく `brew` が利用可能な場合、gateway は先に Homebrew で Go をインストールし、可能なら `GOBIN` を Homebrew の `bin` に設定します。
- Download インストール: `url`（必須）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（デフォルト: archive 検出時は自動）、`stripComponents`、`targetDir`（デフォルト: `~/.openclaw/tools/<skillKey>`）。
- 複数のインストーラーが列挙されている場合、gatewayは**単一の**優先オプションを選びます（brewが利用可能ならbrew、そうでなければnode）。
- すべてのインストーラーが`download`の場合、OpenClawは利用可能な成果物を確認できるよう各エントリーを一覧表示します。
- インストーラー仕様には、プラットフォームごとに選択肢を絞り込むための`os: ["darwin"|"linux"|"win32"]`を含められます。
- Nodeインストールは`openclaw.json`内の`skills.install.nodeManager`を尊重します
（デフォルト: npm、選択肢: npm/pnpm/yarn/bun）。
これは**skillインストール**にのみ影響します。Gatewayランタイムは引き続きNodeであるべきです
（WhatsApp/TelegramにはBunは推奨されません）。
- Gatewayバックエンドのインストーラー選択は、node専用ではなく優先度駆動です:
インストール仕様が複数種類を混在させている場合、OpenClawは
`skills.install.preferBrew`が有効で`brew`が存在すればHomebrewを優先し、次に`uv`、その後
設定済みnode manager、その後`go`や`download`のような他のフォールバックを選びます。
- すべてのinstall specが`download`の場合、OpenClawは
1つの優先インストーラーにまとめず、すべてのダウンロードオプションを表示します。
- Goインストール: `go`がなく`brew`が利用可能な場合、gatewayはまずHomebrew経由でGoをインストールし、可能なら`GOBIN`をHomebrewの`bin`に設定します。
- Downloadインストール: `url`（必須）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（デフォルト: archive検出時は自動）、`stripComponents`、`targetDir`（デフォルト: `~/.openclaw/tools/<skillKey>`）。
`metadata.openclaw` が存在しない場合、その skill は常に対象になります
（設定で無効化されている場合、または bundled skill に対して `skills.allowBundled` でブロックされている場合を除く）。
`metadata.openclaw`が存在しない場合、そのskillは常に有効候補です（設定で無効化されている場合や、
バンドル版skillに対して`skills.allowBundled`でブロックされている場合を除く）。
## 設定上書き（`~/.openclaw/openclaw.json`）
bundled/managed Skills は切り替え可能で、env 値も提供できます。
バンドル版/managed skillsは、有効化したりenv値を供給したりできます:
```json5
{
@ -256,7 +262,7 @@ bundled/managed Skills は切り替え可能で、env 値も提供できます
entries: {
"image-lab": {
enabled: true,
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // または plaintext string
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // または平文文字列
env: {
GEMINI_API_KEY: "GEMINI_KEY_HERE",
},
@ -272,64 +278,71 @@ bundled/managed Skills は切り替え可能で、env 値も提供できます
}
```
補足: skill 名にハイフンが含まれる場合はキーを引用してください（JSON5 では quoted key が使えます）。
注: skill名にハイフンが含まれる場合は、キーをクォートしてください（JSON5ではクォート付きキーが使えます）。
OpenClaw 自体の中で標準の画像生成/編集を使いたい場合は、bundled
skill ではなく、`agents.defaults.imageGenerationModel` とともに core の
`image_generate` ツールを使用してください。ここでの skill 例は custom または third-party ワークフロー向けです。
OpenClaw本体の中で標準の画像生成/編集を使いたい場合は、バンドル版skillではなく、
`agents.defaults.imageGenerationModel`と組み合わせたコアの
`image_generate`ツールを使用してください。ここでのskill例は、カスタムまたはサードパーティのワークフロー向けです。
ネイティブの画像解析には `agents.defaults.imageModel` とともに `image` ツールを使ってください。
ネイティブの画像生成/編集には
`agents.defaults.imageGenerationModel` とともに `image_generate` を使ってください。`openai/*`、`google/*`、
`fal/*`、または他の provider 固有の画像モデルを選ぶ場合は、その provider の auth/API
ネイティブ画像解析には、`agents.defaults.imageModel`とともに`image`ツールを使ってください。
ネイティブ画像生成/編集には、
`agents.defaults.imageGenerationModel`とともに`image_generate`を使用してください。`openai/*`、`google/*`、
`fal/*`、またはその他のプロバイダー固有画像モデルを選ぶ場合は、そのプロバイダーの認証/API
キーも追加してください。
設定キーはデフォルトで **skill 名** に一致します。skill が
`metadata.openclaw.skillKey` を定義している場合は、
`skills.entries` 配下でそのキーを使用してください。
設定キーはデフォルトで**skill名**と一致します。skillが
`metadata.openclaw.skillKey`を定義している場合は、`skills.entries`配下でそのキーを使用してください。
ルール:
- `enabled: false` は、bundled/installed であってもその skill を無効化します。
- `env`: 変数が process 内でまだ設定されていない **場合のみ** 注入されます。
- `apiKey`: `metadata.openclaw.primaryEnv` を宣言した skill 向けの
便利機能。plaintext string または SecretRef object（`{ source, provider, id }`）をサポートします。
- `config`: custom な skill ごとのフィールドのための任意の bag。custom key はここに置く必要があります。
- `allowBundled`: **bundled** Skills 専用の任意の allowlist。設定した場合、
一覧内の bundled skill のみが対象になります（managed/workspace Skills には影響しません）。
- `enabled: false`は、そのskillがバンドル済み/インストール済みでも無効化します。
- `env`: その変数がプロセスですでに設定されていない**場合にのみ**注入されます。
- `apiKey`: `metadata.openclaw.primaryEnv`を宣言しているskill向けの簡易指定です。
平文文字列またはSecretRefオブジェクト（`{ source, provider, id }`）をサポートします。
- `config`: カスタムなskillごとのフィールド用の任意バッグです。カスタムキーはここに置かなければなりません。
- `allowBundled`: **バンドル版**skills専用の任意許可リストです。設定した場合、
リスト内のバンドル版skillsだけが有効候補になります（managed/workspace skillsは影響を受けません）。
## 環境注入（エージェント実行単位）
## 環境変数注入（エージェント実行ごと）
エージェント実行が始まると、OpenClaw は次を行います。
エージェント実行が始まると、OpenClawは以下を行います:
1. skill metadata を読み取る。
2. `skills.entries.<key>.env` または `skills.entries.<key>.apiKey` を
`process.env` に適用する。
3. **対象となる** Skills を使って system prompt を構築する。
4. 実行終了後、元の環境を復元する。
1. skillメタデータを読み取る。
2. `skills.entries.<key>.env`または`skills.entries.<key>.apiKey`を
`process.env`に適用する。
3. **有効候補**skillsを使ってシステムプロンプトを構築する。
4. 実行終了後に元の環境を復元する。
これは **エージェント実行単位** であり、グローバルな shell 環境ではありません。
これは**エージェント実行にスコープされた**ものであり、グローバルなシェル環境ではありません。
## セッション snapshot（パフォーマンス）
バンドル版`claude-cli`バックエンドでは、OpenClawは同じ
有効候補スナップショットを一時的なClaude Codeプラグインとして具体化し、
`--plugin-dir`とともに渡します。これによりClaude Codeはネイティブのskillリゾルバーを使えますが、
優先順位、エージェントごとの許可リスト、ゲーティング、および
`skills.entries.*`のenv/APIキー注入は引き続きOpenClawが所有します。他のCLIバックエンドは
プロンプトカタログのみを使用します。
OpenClaw は、**セッション開始時に** 対象となる Skills を snapshot し、同じセッション内の以降のターンでその一覧を再利用します。Skills または設定の変更は、次の新しいセッションで反映されます。
## セッションスナップショット（パフォーマンス）
Skills watcher が有効な場合、または新しい対象 remote node が現れた場合、Skills はセッション途中でも更新されることがあります（下記参照）。これは **ホットリロード** と考えてください: 更新された一覧は次のエージェントターンで取り込まれます。
OpenClawは、**セッション開始時**に有効候補skillsをスナップショットし、同じセッション内の後続ターンではその一覧を再利用します。skillsまたは設定の変更は次の新規セッションで有効になります。
そのセッションの有効なエージェント Skill allowlist が変わった場合、OpenClaw
は snapshot を更新し、可視な Skills が現在のエージェントと一致した状態を保ちます。
skills watcherが有効な場合や、新たな有効候補のリモートノードが現れた場合（後述）は、セッション途中でskillsが更新されることもあります。これは**ホットリロード**と考えてください。更新された一覧は次のエージェントターンで取り込まれます。
## リモート macOS node（Linux gateway）
そのセッションに対する有効なエージェントskill許可リストが変更された場合、OpenClawは
可視skillsが現在のエージェントに揃うようスナップショットを更新します。
Gateway が Linux 上で動作していて、**macOS node** が **`system.run` 許可あり**
（Exec approvals security が `deny` ではない）で接続されている場合、OpenClaw は
必要なバイナリーがその node 上に存在すれば、macOS 専用 Skills を対象として扱えます。エージェントはそれらの Skills を `exec` ツールで `host=node` として実行すべきです。
## リモートmacOSノード（Linux Gateway）
これは、node がその command support を報告し、`system.run` による bin probe を行うことに依存します。後で macOS node がオフラインになっても、Skills は表示されたままです。node が再接続するまで呼び出しは失敗する可能性があります。
GatewayがLinux上で動作していても、**macOSノード**が接続されており、かつ**`system.run`が許可されている**
（Exec approvalsセキュリティが`deny`に設定されていない）場合、必要なバイナリがそのノード上に存在すれば、
OpenClawはmacOS専用skillsを有効候補として扱えます。エージェントは`exec`ツールを`host=node`付きで使って、
それらのskillsを実行するべきです。
これは、ノードがコマンドサポートを報告することと、`system.run`経由のbin probeに依存します。その後でmacOSノードがオフラインになっても、skillsは可視のままです。ノードが再接続するまで呼び出しは失敗する可能性があります。
## Skills watcher（自動更新）
デフォルトでは、OpenClaw は skill フォルダーを監視し、`SKILL.md` ファイルが変わると Skills snapshot を更新します。これは `skills.load` 配下で設定します。
デフォルトでは、OpenClawはskillフォルダーを監視し、`SKILL.md`ファイルが変更されるとskillsスナップショットを更新します。これは`skills.load`配下で設定します:
```json5
{
@ -342,12 +355,13 @@ Gateway が Linux 上で動作していて、**macOS node** が **`system.run`
}
```
## トークンへの影響（Skills 一覧）
## トークンへの影響（skills一覧）
Skills が対象になると、OpenClaw は利用可能な Skills のコンパクトな XML 一覧を system prompt に注入します（`pi-coding-agent` の `formatSkillsForPrompt` 経由）。コストは決定的です。
skillsが有効候補になると、OpenClawは利用可能なskillsのコンパクトなXML一覧を
システムプロンプトへ注入します（`pi-coding-agent`の`formatSkillsForPrompt`経由）。コストは決定的です:
- **ベースオーバーヘッド（1 つ以上の skill がある場合のみ）:** 195 文字。
- **skill ごと:** 97 文字 + XML エスケープされた `<name>`、`<description>`、`<location>` の長さ。
- **ベースオーバーヘッド（1件以上のskillがある場合のみ）:** 195文字。
- **skillごと:** 97文字 + XMLエスケープ済みの`<name>`、`<description>`、`<location>`値の長さ。
式（文字数）:
@ -355,31 +369,31 @@ Skills が対象になると、OpenClaw は利用可能な Skills のコンパ
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
```
補足:
注記:
- XML エスケープでは `& < > " '` がエンティティ（`&amp;`、`&lt;` など）に展開され、長さが増えます。
- トークン数は model tokenizer によって異なります。OpenAI 風の概算では約 4 文字/トークンなので、**97 文字 ≈ 24 トークン**/skill に実際のフィールド長が加わります。
- XMLエスケープは`& < > " '`をエンティティ（`&amp;`、`&lt;`など）へ展開するため、長さが増えます。
- トークン数はモデルのトークナイザーによって異なります。OpenAI風の大まかな見積もりでは約4文字/トークンなので、**97文字 ≈ 24トークン**/skillに加え、実際のフィールド長が加算されます。
## managed Skills のライフサイクル
## managed skillsのライフサイクル
OpenClaw は、インストール
（npm パッケージまたは OpenClaw.app）の一部として、ベースラインの Skills 一式を **bundled Skills** として同梱します。`~/.openclaw/skills` はローカル
上書き用です（たとえば、bundled
コピーを変更せずに skill を pin/patch する場合）。workspace Skills はユーザー所有であり、名前の競合時には両方を上書きします。
OpenClawは、インストール物
（npmパッケージまたはOpenClaw.app）の一部として、ベースラインのskillsを**バンドル版skills**として同梱します。`~/.openclaw/skills`はローカル上書き用に存在します
（たとえば、バンドル版コピーを変更せずにskillを固定/パッチする場合など）。
workspace skillsはユーザー所有であり、名前が競合した場合は両方を上書きします。
## 設定リファレンス
完全な設定スキーマは [Skills config](/tools/skills-config) を参照してください。
完全な設定スキーマについては[Skills config](/ja-JP/tools/skills-config)を参照してください。
## もっと多くの Skills を探していますか？
## もっとskillsを探していますか？
[https://clawhub.ai](https://clawhub.ai) を参照してください。
[https://clawhub.ai](https://clawhub.ai)を参照してください。
---
## 関連
- [Creating Skills](/tools/creating-skills) — custom Skills の作成
- [Skills Config](/tools/skills-config) — Skill 設定リファレンス
- [Slash Commands](/tools/slash-commands) — 利用可能なすべての slash command
- [Plugins](/tools/plugin) — plugin システム概要
- [Creating Skills](/ja-JP/tools/creating-skills) — カスタムskillsの構築
- [Skills Config](/ja-JP/tools/skills-config) — skill設定リファレンス
- [Slash Commands](/ja-JP/tools/slash-commands) — 利用可能なすべてのスラッシュコマンド
- [Plugins](/ja-JP/tools/plugin) — プラグインシステムの概要

385
docs/ja-JP/tools/slash-commands.md
View File

@ -1,36 +1,36 @@
---
read_when:
- チャットコマンドを使用または設定しているとき
- コマンドのルーティングや権限をデバッグしているとき
summary: 'スラッシュコマンド: テキストとネイティブ、設定、サポートされるコマンド'
- チャットコマンドを使用または設定すること
- コマンドのルーティングまたは権限をデバッグすること
summary: 'スラッシュコマンド: テキストとネイティブ、設定、およびサポートされているコマンド'
title: スラッシュコマンド
x-i18n:
generated_at: "2026-04-08T06:02:11Z"
generated_at: "2026-04-11T02:48:51Z"
model: gpt-5.4
provider: openai
source_hash: 4a7ee7f1a8012058279b9e632889b291d4e659e4ec81209ca8978afbb9ad4b96
source_hash: 2cc346361c3b1a63aae9ec0f28706f4cb0b866b6c858a3999101f6927b923b4a
source_path: tools/slash-commands.md
workflow: 15
---
# スラッシュコマンド
コマンドは Gateway によって処理されます。ほとんどのコマンドは、`/` で始まる**単独の**メッセージとして送信する必要があります。
ホスト専用の bash チャットコマンドは `! <cmd>` を使用します（`/bash <cmd>` はエイリアスです）。
コマンドは Gateway によって処理されます。ほとんどのコマンドは `/` で始まる**単独の**メッセージとして送信する必要があります。
host 専用の bash チャットコマンドは `! <cmd>` を使用します（`/bash <cmd>` はそのエイリアスです）。
関連するシステムは 2 つあります。
関連する 2 つの仕組みがあります。
- **コマンド**: 単独の `/...` メッセージ。
- **ディレクティブ**: `/think`, `/fast`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`。
- ディレクティブは、モデルがメッセージを見る前に取り除かれます。
- 通常のチャットメッセージ内では（ディレクティブのみのメッセージではない場合）、これらは「インラインヒント」として扱われ、セッション設定は保持されません。
- ディレクティブのみのメッセージでは（メッセージがディレクティブだけを含む場合）、セッションに保持され、確認応答が返されます。
- ディレクティブは**認可された送信者**に対してのみ適用されます。`commands.allowFrom` が設定されている場合、それが使用される唯一の
許可リストです。そうでない場合、認可はチャンネルの許可リストやペアリングに加えて `commands.useAccessGroups` から決まります。
未認可の送信者では、ディレクティブは通常のテキストとして扱われます。
- **Commands**: 単独の `/...` メッセージ。
- **Directives**: `/think`, `/fast`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`。
- Directives は、モデルがメッセージを見る前に取り除かれます。
- 通常のチャットメッセージ内（directive のみではない場合）では、「インラインヒント」として扱われ、セッション設定は永続化されません。
- directive のみのメッセージ（メッセージが directives だけを含む場合）では、セッションに永続化され、確認応答が返されます。
- Directives は**認可された送信者**に対してのみ適用されます。`commands.allowFrom` が設定されている場合、それが唯一の
allowlist として使われます。そうでない場合、認可は channel allowlists/pairing と `commands.useAccessGroups` に基づきます。
認可されていない送信者では、directives は通常のテキストとして扱われます。
**インラインショートカット**もいくつかあります（許可リストに含まれる / 認可された送信者のみ）: `/help`, `/commands`, `/status`, `/whoami` (`/id`)。
これらは即座に実行され、モデルがメッセージを見る前に取り除かれ、残りのテキストは通常のフローを続行します。
いくつかの **インラインショートカット** もあります（allowlist 済み/認可済み送信者のみ）: `/help`, `/commands`, `/status`, `/whoami` (`/id`)。
これらは即座に実行され、モデルがメッセージを見る前に取り除かれ、残りのテキストは通常フローで続行されます。
## 設定
@ -60,104 +60,105 @@ x-i18n:
```
- `commands.text`（デフォルト `true`）は、チャットメッセージ内での `/...` の解析を有効にします。
- ネイティブコマンドのないサーフェス（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）では、これを `false` に設定してもテキストコマンドは引き続き動作します。
- ネイティブコマンドを持たない surface（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）では、これを `false` に設定しても text commands は引き続き動作します。
- `commands.native`（デフォルト `"auto"`）は、ネイティブコマンドを登録します。
- Auto: Discord/Telegram ではオン、Slack ではオフ（スラッシュコマンドを追加するまで）、ネイティブサポートのないプロバイダーでは無視されます。
- プロバイダーごとに上書きするには、`channels.discord.commands.native`、`channels.telegram.commands.native`、または `channels.slack.commands.native` を設定します（bool または `"auto"`）。
- `false` にすると、起動時に Discord/Telegram で以前登録されたコマンドを削除します。Slack のコマンドは Slack アプリで管理されるため、自動では削除されません。
- `commands.nativeSkills`（デフォルト `"auto"`）は、サポートされている場合に **skill** コマンドをネイティブ登録します。
- Auto: Discord/Telegram ではオン、Slack ではオフ（Slack では skill ごとにスラッシュコマンドを作成する必要があります）。
- プロバイダーごとに上書きするには、`channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills`、または `channels.slack.commands.nativeSkills` を設定します（bool または `"auto"`）。
- `commands.bash`（デフォルト `false`）は、`! <cmd>` によるホストシェルコマンド実行を有効にします（`/bash <cmd>` はエイリアスです。`tools.elevated` の許可リストが必要です）。
- `commands.bashForegroundMs`（デフォルト `2000`）は、bash がバックグラウンドモードに切り替わる前に待機する時間を制御します（`0` の場合は即座にバックグラウンド化します）。
- `commands.config`（デフォルト `false`）は `/config` を有効にします（`openclaw.json` の読み取り / 書き込み）。
- `commands.mcp`（デフォルト `false`）は `/mcp` を有効にします（`mcp.servers` 配下の OpenClaw 管理 MCP 設定の読み取り / 書き込み）。
- `commands.plugins`（デフォルト `false`）は `/plugins` を有効にします（プラグインの検出 / 状態、およびインストール + 有効化 / 無効化の操作）。
- `commands.debug`（デフォルト `false`）は `/debug` を有効にします（ランタイム限定のオーバーライド）。
- `commands.restart`（デフォルト `true`）は `/restart` と Gateway 再起動ツールアクションを有効にします。
- `commands.ownerAllowFrom`（省略可能）は、owner 専用のコマンド / ツールサーフェス向けの明示的な owner 許可リストを設定します。これは `commands.allowFrom` とは別です。
- `commands.ownerDisplay` は、システムプロンプト内で owner ID をどのように表示するかを制御します: `raw` または `hash`。
- `commands.ownerDisplaySecret` は、`commands.ownerDisplay="hash"` のときに使用する HMAC シークレットを省略可能で設定します。
- `commands.allowFrom`（省略可能）は、コマンド認可のためのプロバイダーごとの許可リストを設定します。これが構成されている場合、コマンドとディレクティブに対する唯一の認可ソースとなり（チャンネルの許可リスト / ペアリングと `commands.useAccessGroups`
は無視されます）。グローバルデフォルトには `"*"` を使用し、プロバイダー固有のキーがそれを上書きします。
- `commands.useAccessGroups`（デフォルト `true`）は、`commands.allowFrom` が設定されていない場合に、コマンドに対して許可リスト / ポリシーを適用します。
- Auto: Discord/Telegram ではオン、Slack ではオフ（slash commands を追加するまでは）。ネイティブ対応のない provider では無視されます。
- provider ごとに上書きするには、`channels.discord.commands.native`、`channels.telegram.commands.native`、または `channels.slack.commands.native` を設定します（bool または `"auto"`）。
- `false` は、起動時に Discord/Telegram で以前登録されたコマンドを消去します。Slack commands は Slack app 側で管理され、自動削除はされません。
- `commands.nativeSkills`（デフォルト `"auto"`）は、対応している場合に **skill** commands をネイティブ登録します。
- Auto: Discord/Telegram ではオン、Slack ではオフ（Slack は skill ごとに slash command の作成が必要）。
- provider ごとに上書きするには、`channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills`、または `channels.slack.commands.nativeSkills` を設定します（bool または `"auto"`）。
- `commands.bash`（デフォルト `false`）は、`! <cmd>` による host shell command 実行を有効にします（`/bash <cmd>` はエイリアス。`tools.elevated` allowlists が必要）。
- `commands.bashForegroundMs`（デフォルト `2000`）は、bash が background mode に切り替わるまでどれだけ待つかを制御します（`0` で即座に background 化）。
- `commands.config`（デフォルト `false`）は `/config` を有効にします（`openclaw.json` の読み書き）。
- `commands.mcp`（デフォルト `false`）は `/mcp` を有効にします（`mcp.servers` 配下の OpenClaw 管理 MCP config の読み書き）。
- `commands.plugins`（デフォルト `false`）は `/plugins` を有効にします（plugin の検出/状態確認、および install + enable/disable 制御）。
- `commands.debug`（デフォルト `false`）は `/debug` を有効にします（runtime 専用の上書き）。
- `commands.restart`（デフォルト `true`）は `/restart` と gateway restart tool actions を有効にします。
- `commands.ownerAllowFrom`（任意）は、owner 専用 command/tool surface 向けの明示的な owner allowlist を設定します。これは `commands.allowFrom` とは別です。
- `commands.ownerDisplay` は、system prompt 内で owner ids をどう表示するかを制御します: `raw` または `hash`。
- `commands.ownerDisplaySecret` は、`commands.ownerDisplay="hash"` の場合に使用する HMAC secret を任意で設定します。
- `commands.allowFrom`（任意）は、command 認可のための provider ごとの allowlist を設定します。これが設定されている場合、
command と directives の認可元はこれ**のみ**になります（channel allowlists/pairing と `commands.useAccessGroups` は無視されます）。グローバルデフォルトには `"*"` を使い、provider 固有キーがそれを上書きします。
- `commands.useAccessGroups`（デフォルト `true`）は、`commands.allowFrom` が設定されていない場合に、command に対して allowlists/policies を適用します。
## コマンド一覧
現在の source-of-truth:
現在のソースオブトゥルース:
- コアの組み込みコマンドは `src/auto-reply/commands-registry.shared.ts` から
- 生成される dock コマンドは `src/auto-reply/commands-registry.data.ts` から
- プラグインコマンドはプラグインの `registerCommand()` 呼び出しから
- あなたの Gateway で実際に利用できるかどうかは、引き続き設定フラグ、チャンネルサーフェス、インストール / 有効化されたプラグインに依存します
- core 組み込みコマンドは `src/auto-reply/commands-registry.shared.ts` から来ます
- 生成された dock commands は `src/auto-reply/commands-registry.data.ts` から来ます
- plugin commands は plugin の `registerCommand()` 呼び出しから来ます
- 実際にあなたの gateway で利用可能かどうかは、引き続き config flags、channel surface、およびインストール/有効化された plugins に依存します
### コアの組み込みコマンド
### Core 組み込みコマンド
現在利用可能な組み込みコマンド:
- `/new [model]` は新しいセッションを開始します。`/reset` はリセット用エイリアスです。
- `/compact [instructions]` はセッションコンテキストを圧縮します。[/concepts/compaction](/ja-JP/concepts/compaction) を参照してください。
- `/stop` は現在の実行を中止します。
- `/session idle <duration|off>` と `/session max-age <duration|off>` は、スレッドバインディングの有効期限を管理します。
- `/think <off|minimal|low|medium|high|xhigh>` は thinking レベルを設定します。エイリアス: `/thinking`, `/t`。
- `/verbose on|off|full` は詳細出力を切り替えます。エイリアス: `/v`。
- `/fast [status|on|off]` は高速モードを表示または設定します。
- `/reasoning [on|off|stream]` は reasoning の表示を切り替えます。エイリアス: `/reason`。
- `/elevated [on|off|ask|full]` は elevated モードを切り替えます。エイリアス: `/elev`。
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` は exec のデフォルトを表示または設定します。
- `/model [name|#|status]` はモデルを表示または設定します。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` は、プロバイダーまたはプロバイダーのモデルを一覧表示します。
- `/queue <mode>` は、キューの動作（`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`）と、`debounce:2s cap:25 drop:summarize` のようなオプションを管理します。
- `/help` は短いヘルプ要約を表示します。
- `/commands` は生成されたコマンドカタログを表示します。
- `/tools [compact|verbose]` は、現在このエージェントが使えるものを表示します。
- `/status` は、利用可能な場合はプロバイダー使用量 / クォータを含むランタイム状態を表示します。
- `/tasks` は、現在のセッションのアクティブ / 最近のバックグラウンドタスクを一覧表示します。
- `/context [list|detail|json]` は、コンテキストがどのように組み立てられるかを説明します。
- `/export-session [path]` は、現在のセッションを HTML にエクスポートします。エイリアス: `/export`。
- `/whoami` はあなたの送信者 ID を表示します。エイリアス: `/id`。
- `/skill <name> [input]` は、名前で skill を実行します。
- `/allowlist [list|add|remove] ...` は、許可リストエントリを管理します。テキスト専用です。
- `/approve <id> <decision>` は、exec 承認プロンプトを解決します。
- `/btw <question>` は、将来のセッションコンテキストを変更せずに横道の質問をします。[/tools/btw](/ja-JP/tools/btw) を参照してください。
- `/subagents list|kill|log|info|send|steer|spawn` は、現在のセッションのサブエージェント実行を管理します。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` は、ACP セッションとランタイムオプションを管理します。
- `/focus <target>` は、現在の Discord スレッドまたは Telegram トピック / 会話をセッションターゲットにバインドします。
- `/unfocus` は、現在のバインディングを削除します。
- `/agents` は、現在のセッションにスレッドバインドされたエージェントを一覧表示します。
- `/kill <id|#|all>` は、実行中の 1 つまたはすべてのサブエージェントを中止します。
- `/steer <id|#> <message>` は、実行中のサブエージェントにステアリングを送信します。エイリアス: `/tell`。
- `/config show|get|set|unset` は `openclaw.json` を読み書きします。owner 専用。`commands.config: true` が必要です。
- `/mcp show|get|set|unset` は、`mcp.servers` 配下の OpenClaw 管理 MCP サーバー設定を読み書きします。owner 専用。`commands.mcp: true` が必要です。
- `/plugins list|inspect|show|get|install|enable|disable` は、プラグイン状態を検査または変更します。`/plugin` はエイリアスです。書き込みは owner 専用です。`commands.plugins: true` が必要です。
- `/debug show|set|unset|reset` は、ランタイム限定の設定オーバーライドを管理します。owner 専用。`commands.debug: true` が必要です。
- `/usage off|tokens|full|cost` は、レスポンスごとの使用量フッターを制御するか、ローカルのコスト要約を表示します。
- `/new [model]` は新しいセッションを開始します。`/reset` は reset のエイリアスです。
- `/compact [instructions]` はセッションコンテキストを compact します。[/concepts/compaction](/ja-JP/concepts/compaction) を参照してください。
- `/stop` は現在の run を中止します。
- `/session idle <duration|off>` と `/session max-age <duration|off>` は thread-binding の有効期限を管理します。
- `/think <off|minimal|low|medium|high|xhigh>` は thinking level を設定します。エイリアス: `/thinking`, `/t`。
- `/verbose on|off|full` は verbose 出力を切り替えます。エイリアス: `/v`。
- `/fast [status|on|off]` は fast mode を表示または設定します。
- `/reasoning [on|off|stream]` は reasoning の可視性を切り替えます。エイリアス: `/reason`。
- `/elevated [on|off|ask|full]` は elevated mode を切り替えます。エイリアス: `/elev`。
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` は exec defaults を表示または設定します。
- `/model [name|#|status]` は model を表示または設定します。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` は provider 一覧、または provider の models を表示します。
- `/queue <mode>` は queue 動作（`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`）と、`debounce:2s cap:25 drop:summarize` のようなオプションを管理します。
- `/help` は短い help 要約を表示します。
- `/commands` は生成された command catalog を表示します。
- `/tools [compact|verbose]` は、現在の agent が今使えるものを表示します。
- `/status` は runtime status を表示します。利用可能な場合は provider の usage/quota も含みます。
- `/tasks` は現在のセッションのアクティブ/最近の background tasks を一覧表示します。
- `/context [list|detail|json]` は、context がどのように組み立てられるかを説明します。
- `/export-session [path]` は現在のセッションを HTML にエクスポートします。エイリアス: `/export`。
- `/whoami` はあなたの sender id を表示します。エイリアス: `/id`。
- `/skill <name> [input]` は skill を名前で実行します。
- `/allowlist [list|add|remove] ...` は allowlist エントリを管理します。text-only。
- `/approve <id> <decision>` は exec approval prompt を解決します。
- `/btw <question>` は、将来のセッションコンテキストを変更せずに脇道の質問をします。[/tools/btw](/ja-JP/tools/btw) を参照してください。
- `/subagents list|kill|log|info|send|steer|spawn` は現在のセッションの sub-agent runs を管理します。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` は ACP セッションと runtime options を管理します。
- `/focus <target>` は現在の Discord thread または Telegram topic/conversation をセッション target にバインドします。
- `/unfocus` は現在の binding を削除します。
- `/agents` は現在のセッションに thread-bound された agents を一覧表示します。
- `/kill <id|#|all>` は 1 つまたはすべての実行中 sub-agent を中止します。
- `/steer <id|#> <message>` は実行中の sub-agent にステアリングを送ります。エイリアス: `/tell`。
- `/config show|get|set|unset` は `openclaw.json` を読み書きします。owner-only。`commands.config: true` が必要です。
- `/mcp show|get|set|unset` は `mcp.servers` 配下の OpenClaw 管理 MCP server config を読み書きします。owner-only。`commands.mcp: true` が必要です。
- `/plugins list|inspect|show|get|install|enable|disable` は plugin 状態を確認または変更します。`/plugin` はエイリアスです。書き込みは owner-only。`commands.plugins: true` が必要です。
- `/debug show|set|unset|reset` は runtime 専用 config overrides を管理します。owner-only。`commands.debug: true` が必要です。
- `/usage off|tokens|full|cost` はレスポンスごとの usage footer を制御するか、ローカル cost summary を表示します。
- `/tts on|off|status|provider|limit|summary|audio|help` は TTS を制御します。[/tools/tts](/ja-JP/tools/tts) を参照してください。
- `/restart` は、有効な場合に OpenClaw を再起動します。デフォルト: 有効。無効にするには `commands.restart: false` を設定します。
- `/activation mention|always` は、グループアクティベーションモードを設定します。
- `/send on|off|inherit` は、送信ポリシーを設定します。owner 専用。
- `/bash <command>` はホストシェルコマンドを実行します。テキスト専用。エイリアス: `! <command>`。`commands.bash: true` と `tools.elevated` の許可リストが必要です。
- `!poll [sessionId]` は、バックグラウンドの bash ジョブを確認します。
- `!stop [sessionId]` は、バックグラウンドの bash ジョブを停止します。
- `/restart` は、有効な場合に OpenClaw を再起動します。デフォルトは有効です。無効にするには `commands.restart: false` を設定します。
- `/activation mention|always` は group activation mode を設定します。
- `/send on|off|inherit` は send policy を設定します。owner-only。
- `/bash <command>` は host shell command を実行します。text-only。エイリアス: `! <command>`。`commands.bash: true` と `tools.elevated` allowlists が必要です。
- `!poll [sessionId]` は background bash job を確認します。
- `!stop [sessionId]` は background bash job を停止します。
### 生成される dock コマンド
### 生成された dock commands
Dock コマンドは、ネイティブコマンドをサポートするチャンネルプラグインから生成されます。現在バンドルされているセット:
Dock commands は、native-command をサポートする channel plugins から生成されます。現在の bundled セット:
- `/dock-discord`（エイリアス: `/dock_discord`）
- `/dock-mattermost`（エイリアス: `/dock_mattermost`）
- `/dock-slack`（エイリアス: `/dock_slack`）
- `/dock-telegram`（エイリアス: `/dock_telegram`）
### バンドルされたプラグインコマンド
### Bundled plugin commands
バンドルされたプラグインは、さらにスラッシュコマンドを追加できます。このリポジトリで現在バンドルされているコマンド:
bundled plugins はさらに slash commands を追加できます。このリポジトリにある現在の bundled commands:
- `/dreaming [on|off|status|help]` は、メモリ dreaming を切り替えます。[Dreaming](/ja-JP/concepts/dreaming) を参照してください。
- `/pair [qr|status|pending|approve|cleanup|notify]` は、デバイスのペアリング / セットアップフローを管理します。[Pairing](/ja-JP/channels/pairing) を参照してください。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` は、高リスクの phone node コマンドを一時的にアームします。
- `/voice status|list [limit]|set <voiceId|name>` は Talk 音声設定を管理します。Discord では、ネイティブコマンド名は `/talkvoice` です。
- `/card ...` は LINE のリッチカードプリセットを送信します。[LINE](/ja-JP/channels/line) を参照してください。
- `/dreaming [on|off|status|help]` は memory dreaming を切り替えます。[Dreaming](/ja-JP/concepts/dreaming) を参照してください。
- `/pair [qr|status|pending|approve|cleanup|notify]` はデバイスの pairing/setup flow を管理します。[Pairing](/ja-JP/channels/pairing) を参照してください。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` は高リスク phone node commands を一時的に arm します。
- `/voice status|list [limit]|set <voiceId|name>` は Talk voice config を管理します。Discord では、ネイティブ command 名は `/talkvoice` です。
- `/card ...` は LINE rich card プリセットを送信します。[LINE](/ja-JP/channels/line) を参照してください。
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` は bundled Codex app-server harness を確認および制御します。[Codex Harness](/ja-JP/plugins/codex-harness) を参照してください。
- QQBot 専用コマンド:
- `/bot-ping`
- `/bot-version`
@ -165,76 +166,72 @@ Dock コマンドは、ネイティブコマンドをサポートするチャン
- `/bot-upgrade`
- `/bot-logs`
### 動的な skill コマンド
### 動的 skill commands
ユーザーが呼び出せる skill も、スラッシュコマンドとして公開されます。
ユーザーが呼び出せる skills も slash commands として公開されます。
- `/skill <name> [input]` は、汎用エントリーポイントとして常に機能します。
- skills は、skill / プラグインがそれらを登録すると `/prose` のような直接コマンドとしても表示されることがあります。
- ネイティブ skill コマンド登録は `commands.nativeSkills` と `channels.<provider>.commands.nativeSkills` によって制御されます。
- `/skill <name> [input]` は、汎用エントリポイントとして常に使えます。
- skills は、skill/plugin が登録していれば `/prose` のような直接コマンドとして現れることもあります。
- ネイティブ skill-command 登録は `commands.nativeSkills` と `channels.<provider>.commands.nativeSkills` によって制御されます。
注:
注記:
- コマンドは、コマンドと引数の間に省略可能な `:` を受け付けます（例: `/think: high`, `/send: on`, `/help:`）。
- `/new <model>` は、モデルエイリアス、`provider/model`、またはプロバイダー名（あいまい一致）を受け付けます。一致しない場合、テキストはメッセージ本文として扱われます。
- プロバイダー使用量の完全な内訳を見るには、`openclaw status --usage` を使用します。
- `/allowlist add|remove` には `commands.config=true` が必要で、チャンネルの `configWrites` を尊重します。
- マルチアカウントチャンネルでは、設定対象の `/allowlist --account <id>` と `/config set channels.<provider>.accounts.<id>...` も、対象アカウントの `configWrites` を尊重します。
- `/usage` はレスポンスごとの使用量フッターを制御します。`/usage cost` は OpenClaw セッションログからローカルのコスト要約を表示します。
- コマンドは、コマンドと引数の間に任意で `:` を受け付けます（例: `/think: high`, `/send: on`, `/help:`）。
- `/new <model>` は model alias、`provider/model`、または provider 名（あいまい一致）を受け付けます。一致しない場合、そのテキストはメッセージ本文として扱われます。
- provider usage の完全な内訳を見るには、`openclaw status --usage` を使用してください。
- `/allowlist add|remove` は `commands.config=true` を必要とし、channel の `configWrites` に従います。
- マルチアカウント channel では、config 対象の `/allowlist --account <id>` と `/config set channels.<provider>.accounts.<id>...` も、対象 account の `configWrites` に従います。
- `/usage` はレスポンスごとの usage footer を制御します。`/usage cost` は OpenClaw session logs からローカル cost summary を表示します。
- `/restart` はデフォルトで有効です。無効にするには `commands.restart: false` を設定します。
- `/plugins install <spec>` は、`openclaw plugins install` と同じプラグイン指定を受け付けます: ローカルパス / アーカイブ、npm パッケージ、または `clawhub:<pkg>`。
- `/plugins enable|disable` は、プラグイン設定を更新し、再起動を促すことがあります。
- Discord 専用ネイティブコマンド: `/vc join|leave|status` は音声チャンネルを制御します（`channels.discord.voice` とネイティブコマンドが必要で、テキストでは利用できません）。
- Discord のスレッドバインディングコマンド（`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`）は、有効なスレッドバインディングが有効である必要があります（`session.threadBindings.enabled` および / または `channels.discord.threadBindings.enabled`）。
- ACP コマンドのリファレンスとランタイム動作: [ACP Agents](/ja-JP/tools/acp-agents)。
- `/verbose` はデバッグと追加の可視性のためのものです。通常使用では**オフ**のままにしてください。
- `/fast on|off` はセッションのオーバーライドを保持します。これをクリアして設定のデフォルトに戻すには、Sessions UI の `inherit` オプションを使用します。
- `/fast` はプロバイダー固有です: OpenAI/OpenAI Codex ではネイティブ Responses エンドポイントで `service_tier=priority` に対応し、`api.anthropic.com` に送られる OAuth 認証トラフィックを含む直接の公開 Anthropic リクエストでは `service_tier=auto` または `standard_only` に対応します。[OpenAI](/ja-JP/providers/openai) と [Anthropic](/ja-JP/providers/anthropic) を参照してください。
- ツール失敗の要約は必要に応じて引き続き表示されますが、詳細な失敗テキストが含まれるのは `/verbose` が `on` または `full` の場合のみです。
- `/reasoning`（および `/verbose`）はグループ設定では危険です: 公開する意図のなかった内部 reasoning やツール出力が漏れる可能性があります。特にグループチャットでは、オフのままにしておくことを推奨します。
- `/model` は、新しいセッションモデルを即座に保持します。
- エージェントがアイドル状態であれば、次の実行ですぐにそれが使われます。
- すでに実行がアクティブな場合、OpenClaw はライブ切り替えを保留中としてマークし、クリーンな再試行ポイントでのみ新しいモデルへ再開します。
- ツールアクティビティまたは応答出力がすでに始まっている場合、その保留中の切り替えは後の再試行機会または次のユーザーターンまでキューに残ることがあります。
- **高速パス:** 許可リストに含まれる送信者からのコマンドのみのメッセージは即座に処理されます（キュー + モデルをバイパス）。
- **グループメンションのゲーティング:** 許可リストに含まれる送信者からのコマンドのみのメッセージは、メンション要件をバイパスします。
- **インラインショートカット（許可リストに含まれる送信者のみ）:** 一部のコマンドは通常メッセージ内に埋め込まれていても動作し、モデルが残りのテキストを見る前に取り除かれます。
- 例: `hey /status` は status 応答をトリガーし、残りのテキストは通常のフローを続行します。
- 現在: `/help`, `/commands`, `/status`, `/whoami` (`/id`)。
- 未認可のコマンドのみのメッセージは黙って無視され、インラインの `/...` トークンは通常のテキストとして扱われます。
- **Skill コマンド:** `user-invocable` な skills はスラッシュコマンドとして公開されます。名前は `a-z0-9_` にサニタイズされ（最大 32 文字）、衝突した場合は数値サフィックスが付きます（例: `_2`）。
- `/skill <name> [input]` は、名前で skill を実行します（ネイティブコマンドの制限により skill ごとのコマンドを使えない場合に便利です）。
- デフォルトでは、skill コマンドは通常のリクエストとしてモデルに転送されます。
- skills は任意で `command-dispatch: tool` を宣言し、コマンドを直接ツールにルーティングできます（決定的、モデルなし）。
- 例: `/prose`（OpenProse プラグイン）— [OpenProse](/ja-JP/prose) を参照してください。
- **ネイティブコマンド引数:** Discord は動的オプションにオートコンプリートを使用します（必須引数を省略した場合はボタンメニューも使用します）。Telegram と Slack は、コマンドが選択肢をサポートしていて引数を省略した場合、ボタンメニューを表示します。
- `/plugins install <spec>` は `openclaw plugins install` と同じ plugin spec を受け付けます: ローカル path/archive、npm package、または `clawhub:<pkg>`。
- `/plugins enable|disable` は plugin config を更新し、再起動を促す場合があります。
- Discord 専用ネイティブコマンド: `/vc join|leave|status` は voice channels を制御します（`channels.discord.voice` と native commands が必要。text としては利用不可）。
- Discord の thread-binding コマンド（`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`）は、実効的に thread bindings が有効である必要があります（`session.threadBindings.enabled` および/または `channels.discord.threadBindings.enabled`）。
- ACP コマンドのリファレンスと runtime 動作: [ACP Agents](/ja-JP/tools/acp-agents)。
- `/verbose` はデバッグや追加の可視化を目的としています。通常利用では **off** のままにしてください。
- `/fast on|off` はセッション上書きを永続化します。解除して config デフォルトに戻すには、Sessions UI の `inherit` オプションを使用してください。
- `/fast` は provider 固有です。OpenAI/OpenAI Codex ではネイティブ Responses endpoint 上で `service_tier=priority` にマップされ、direct public Anthropic リクエストでは、`api.anthropic.com` に送られる OAuth 認証トラフィックを含めて `service_tier=auto` または `standard_only` にマップされます。[OpenAI](/ja-JP/providers/openai) と [Anthropic](/ja-JP/providers/anthropic) を参照してください。
- tool failure の要約は関係がある場合は引き続き表示されますが、詳細な failure テキストが含まれるのは `/verbose` が `on` または `full` のときだけです。
- `/reasoning`（および `/verbose`）は group 設定ではリスクがあります。意図しない internal reasoning や tool 出力を露出する可能性があります。特に group chats では、off のままにしておくことを推奨します。
- `/model` は新しい session model を即座に永続化します。
- agent が idle なら、次の run ですぐにそれが使われます。
- すでに run がアクティブな場合、OpenClaw は live switch を保留中としてマークし、クリーンな retry point でのみ新しい model へ再起動します。
- tool activity または reply output がすでに始まっている場合、その保留中スイッチは後の retry 機会または次の user turn までキューされたままになることがあります。
- **Fast path:** allowlist 済み送信者からのコマンドのみのメッセージは即座に処理されます（queue + model をバイパス）。
- **Group mention gating:** allowlist 済み送信者からのコマンドのみのメッセージは mention 要件をバイパスします。
- **Inline shortcuts（allowlist 済み送信者のみ）:** 一部のコマンドは通常メッセージに埋め込まれていても動作し、残りのテキストをモデルが見る前に取り除かれます。
- 例: `hey /status` は status reply をトリガーし、残りのテキストは通常フローで続行されます。
- 現在の対象: `/help`, `/commands`, `/status`, `/whoami` (`/id`)。
- 認可されていないコマンドのみのメッセージは黙って無視され、インライン `/...` トークンは通常テキストとして扱われます。
- **Skill commands:** `user-invocable` な Skills は slash commands として公開されます。名前は `a-z0-9_` にサニタイズされ（最大 32 文字）、衝突時は数値サフィックスが付きます（例: `_2`）。
- `/skill <name> [input]` は skill を名前で実行します（ネイティブ command 制限により skill ごとの commands が使えない場合に便利です）。
- デフォルトでは、skill commands は通常のリクエストとして model に転送されます。
- Skills はオプションで `command-dispatch: tool` を宣言でき、その場合 command を tool に直接ルーティングします（決定的で、model なし）。
- 例: `/prose`（OpenProse plugin）— [OpenProse](/ja-JP/prose) を参照してください。
- **Native command arguments:** Discord は動的オプションに autocomplete を使います（必須引数を省略した場合は button menus も使用）。Telegram と Slack は、コマンドが選択肢をサポートしていて引数を省略した場合に button menu を表示します。
## `/tools`
`/tools` が答えるのは設定の質問ではなく、ランタイムの質問です: **このエージェントが今この会話で使えるものは何か**
です。
`/tools` が答えるのは config の質問ではなく、runtime の質問です: **この会話でこの agent が今すぐ使えるものは何か**。
- デフォルトの `/tools` は簡潔で、すばやく見渡せるよう最適化されています。
- デフォルトの `/tools` は compact で、すばやく確認できるよう最適化されています。
- `/tools verbose` は短い説明を追加します。
- 引数をサポートするネイティブコマンドサーフェスでは、同じモード切り替え `compact|verbose` が公開されます。
- 結果はセッションスコープなので、エージェント、チャンネル、スレッド、送信者認可、またはモデルを変更すると
出力が変わることがあります。
- `/tools` には、コアツール、接続された
プラグインツール、チャンネル所有ツールを含め、実行時に実際に到達可能なツールが含まれます。
- 引数をサポートする native-command surface では、同じ `compact|verbose` モード切り替えが公開されます。
- 結果は session スコープであるため、agent、channel、thread、sender 認可、または model を変更すると出力も変わることがあります。
- `/tools` には、core tools、接続された plugin tools、channel 所有の tools を含む、runtime で実際に到達可能な tools が含まれます。
プロファイルやオーバーライドの編集には、`/tools` を静的カタログとして扱うのではなく、
Control UI の Tools パネルまたは config/catalog サーフェスを使用してください。
profile や override の編集には、`/tools` を静的 catalog として扱うのではなく、Control UI の Tools パネルまたは config/catalog surface を使用してください。
## 使用量サーフェス（どこに何が表示されるか）
## Usage surface（どこに何が表示されるか）
- **プロバイダー使用量 / クォータ**（例: 「Claude 80% left」）は、使用量トラッキングが有効な場合、現在のモデルプロバイダーについて `/status` に表示されます。OpenClaw はプロバイダーのウィンドウを `% left` に正規化します。MiniMax では残量のみの percent フィールドは表示前に反転され、`model_remains` レスポンスではチャットモデルエントリに加えてモデルタグ付きのプランラベルが優先されます。
- `/status` の**トークン / キャッシュ行**は、ライブセッションスナップショットが疎な場合、最新の transcript 使用量エントリにフォールバックできます。既存の非ゼロのライブ値が引き続き優先され、transcript フォールバックでは、保存された合計が欠落しているか小さすぎる場合に、アクティブなランタイムモデルラベルと、より大きいプロンプト指向の合計も復元できます。
- **レスポンスごとのトークン / コスト**は `/usage off|tokens|full` で制御されます（通常の応答に追記されます）。
- `/model status` は使用量ではなく、**モデル / 認証 / エンドポイント**に関するものです。
- **Provider usage/quota**（例: 「Claude 80% left」）は、usage tracking が有効なとき、現在の model provider に対して `/status` に表示されます。OpenClaw は provider の window を `% left` に正規化します。MiniMax では remaining-only の percent フィールドは表示前に反転され、`model_remains` レスポンスでは model-tagged な plan label とともに chat-model エントリが優先されます。
- `/status` 内の **Token/cache 行** は、live session snapshot が疎な場合、最新の transcript usage エントリにフォールバックできます。既存の非ゼロ live 値が引き続き優先され、保存済み total が欠けているか小さい場合には、transcript フォールバックによりアクティブな runtime model label と、より大きい prompt 指向 total も復元できます。
- **レスポンスごとの tokens/cost** は `/usage off|tokens|full` で制御されます（通常の replies に付加されます）。
- `/model status` は **models/auth/endpoints** に関するものであり、usage ではありません。
## モデル選択（`/model`）
`/model` はディレクティブとして実装されています。
`/model` は directive として実装されています。
例:
@ -247,16 +244,16 @@ Control UI の Tools パネルまたは config/catalog サーフェスを使用
/model status
```
注:
注記:
- `/model` と `/model list` は、簡潔で番号付きのピッカー（モデルファミリー + 利用可能なプロバイダー）を表示します。
- Discord では、`/model` と `/models` は、プロバイダーとモデルのドロップダウンに加え、Submit ステップ付きのインタラクティブピッカーを開きます。
- `/model <#>` はそのピッカーから選択し、可能な場合は現在のプロバイダーを優先します。
- `/model status` は詳細ビューを表示し、利用可能な場合は設定済みプロバイダーエンドポイント（`baseUrl`）と API モード（`api`）を含みます。
- `/model` と `/model list` は、compact で番号付きの picker（model family + 利用可能な providers）を表示します。
- Discord では、`/model` と `/models` は provider と model の dropdown、および Submit ステップを持つ対話型 picker を開きます。
- `/model <#>` はその picker から選択します（可能であれば現在の provider を優先します）。
- `/model status` は、設定された provider endpoint（`baseUrl`）と API mode（`api`）を含む詳細ビューを表示します（利用可能な場合）。
## デバッグオーバーライド
## デバッグ上書き
`/debug` を使うと、**ランタイム限定**の設定オーバーライド（メモリ上、ディスクではない）を設定できます。owner 専用です。デフォルトでは無効で、`commands.debug: true` で有効化します。
`/debug` では **runtime のみ** の config 上書き（ディスクではなくメモリ）を設定できます。owner-only。デフォルトでは無効で、`commands.debug: true` で有効化します。
例:
@ -268,14 +265,14 @@ Control UI の Tools パネルまたは config/catalog サーフェスを使用
/debug reset
```
注:
注記:
- オーバーライドは新しい config の読み取りに即座に適用されますが、`openclaw.json` には書き込みません。
- `/debug reset` を使うと、すべてのオーバーライドをクリアしてディスク上の config に戻せます。
- 上書きは新しい config 読み取りに即時適用されますが、`openclaw.json` には書き込まれません。
- すべての上書きを消してディスク上の config に戻るには `/debug reset` を使用してください。
## 設定更新
## Config 更新
`/config` はディスク上の設定（`openclaw.json`）に書き込みます。owner 専用です。デフォルトでは無効で、`commands.config: true` で有効化します。
`/config` はオンディスクの config（`openclaw.json`）に書き込みます。owner-only。デフォルトでは無効で、`commands.config: true` で有効化します。
例:
@ -287,14 +284,14 @@ Control UI の Tools パネルまたは config/catalog サーフェスを使用
/config unset messages.responsePrefix
```
注:
注記:
- 設定は書き込み前に検証されます。無効な変更は拒否されます。
- Config は書き込み前に検証され、不正な変更は拒否されます。
- `/config` の更新は再起動後も保持されます。
## MCP 更新
`/mcp` は `mcp.servers` 配下の OpenClaw 管理 MCP サーバー定義を書き込みます。owner 専用です。デフォルトでは無効で、`commands.mcp: true` で有効化します。
`/mcp` は `mcp.servers` 配下の OpenClaw 管理 MCP server 定義を書き込みます。owner-only。デフォルトでは無効で、`commands.mcp: true` で有効化します。
例:
@ -305,14 +302,14 @@ Control UI の Tools パネルまたは config/catalog サーフェスを使用
/mcp unset context7
```
注:
注記:
- `/mcp` は Pi 所有のプロジェクト設定ではなく、OpenClaw 設定に保存します。
- 実際にどのトランスポートを実行できるかは、ランタイムアダプターが決定します。
- `/mcp` は OpenClaw config に保存され、Pi 所有の project settings には保存されません。
- 実際にどの transport が実行可能かは runtime adapters が決定します。
## プラグイン更新
## Plugin 更新
`/plugins` を使うと、オペレーターは検出されたプラグインを確認し、設定内で有効化を切り替えられます。読み取り専用フローでは `/plugin` をエイリアスとして使えます。デフォルトでは無効で、`commands.plugins: true` で有効化します。
`/plugins` では operator が検出済み plugins を確認し、config 内の有効化状態を切り替えられます。読み取り専用フローでは `/plugin` をエイリアスとして使えます。デフォルトでは無効で、`commands.plugins: true` で有効化します。
例:
@ -324,43 +321,41 @@ Control UI の Tools パネルまたは config/catalog サーフェスを使用
/plugins disable context7
```
注:
注記:
- `/plugins list` と `/plugins show` は、現在のワークスペースとディスク上の設定に対して実際のプラグイン検出を使用します。
- `/plugins enable|disable` はプラグイン設定のみを更新します。プラグインのインストールやアンインストールは行いません。
- 有効化 / 無効化の変更後は、適用するために Gateway を再起動してください。
- `/plugins list` と `/plugins show` は、現在の workspace とオンディスク config に対する実際の plugin discovery を使用します。
- `/plugins enable|disable` は plugin config のみを更新し、plugin の install や uninstall は行いません。
- enable/disable の変更後は、適用のために gateway を再起動してください。
## サーフェスに関する注記
## Surface に関する注記
- **テキストコマンド**は通常のチャットセッションで実行されます（DM は `main` を共有し、グループは独自のセッションを持ちます）。
- **ネイティブコマンド**は分離されたセッションを使用します:
- **Text commands** は通常の chat session で実行されます（DM は `main` を共有し、groups は独自の session を持ちます）。
- **Native commands** は分離された sessions を使用します:
- Discord: `agent:<agentId>:discord:slash:<userId>`
- Slack: `agent:<agentId>:slack:slash:<userId>`（プレフィックスは `channels.slack.slashCommand.sessionPrefix` で設定可能）
- Telegram: `telegram:slash:<userId>`（`CommandTargetSessionKey` を介してチャットセッションをターゲットにします）
- **`/stop`** は、現在の実行を中止できるよう、アクティブなチャットセッションを対象にします。
- **Slack:** `channels.slack.slashCommand` は、単一の `/openclaw` スタイルコマンド向けに引き続きサポートされています。`commands.native` を有効にする場合、組み込みコマンドごとに 1 つの Slack スラッシュコマンドを作成する必要があります（名前は `/help` と同じです）。Slack 向けのコマンド引数メニューは、ephemeral な Block Kit ボタンとして配信されます。
- Slack ネイティブ例外: Slack は `/status` を予約しているため、`/status` ではなく `/agentstatus` を登録してください。テキストの `/status` は Slack メッセージ内でも引き続き動作します。
- Slack: `agent:<agentId>:slack:slash:<userId>`（prefix は `channels.slack.slashCommand.sessionPrefix` で設定可能）
- Telegram: `telegram:slash:<userId>`（`CommandTargetSessionKey` を通じて chat session を対象にします）
- **`/stop`** はアクティブな chat session を対象にして、現在の run を中止できるようにします。
- **Slack:** `channels.slack.slashCommand` は、単一の `/openclaw` 形式 command 用として引き続きサポートされています。`commands.native` を有効にする場合は、組み込み command ごとに 1 つの Slack slash command を作成する必要があります（名前は `/help` などと同じ）。Slack 向けの command 引数メニューは ephemeral Block Kit buttons として配信されます。
- Slack のネイティブ例外: Slack が `/status` を予約しているため、`/status` ではなく `/agentstatus` を登録します。text の `/status` は Slack メッセージ内では引き続き動作します。
## BTW 横道の質問
## BTW の脇道質問
`/btw` は、現在のセッションについてのすばやい**横道の質問**です。
`/btw` は、現在の session に関する素早い **脇道の質問** です。
通常のチャットとは異なり、次のような特徴があります。
通常の chat と異なり、これは:
- 現在のセッションを背景コンテキストとして使用する
- ツールなしの単発呼び出しとして実行される
- 将来のセッションコンテキストを変更しない
- transcript 履歴には書き込まれない
- 通常のアシスタントメッセージではなく、ライブの横道結果として配信される
- 現在の session を背景コンテキストとして使用し、
- tool なしの独立した one-shot call として実行され、
- 将来の session context を変更せず、
- transcript history に書き込まれず、
- 通常の assistant message ではなく、ライブの side result として配信されます。
そのため、`/btw` はメインの
タスクを進めたまま一時的な確認をしたいときに役立ちます。
そのため、メインタスクを進めたまま一時的な確認をしたいときに `/btw` が役立ちます。
例:
```text
/btw what are we doing right now?
/btw 今何をしているんだっけ？
```
完全な動作とクライアント UX の
詳細については、[BTW Side Questions](/ja-JP/tools/btw) を参照してください。
完全な動作と client UX の詳細については [BTW Side Questions](/ja-JP/tools/btw) を参照してください。

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

@ -1,39 +1,38 @@
---
read_when:
- agent経由で動画を生成する場合
- エージェント経由で動画を生成する場合
- 動画生成プロバイダーとモデルを設定する場合
- '`video_generate` toolのパラメーターを理解する必要がある場合'
summary: 12種類のプロバイダーバックエンドを使って、テキスト、画像、既存の動画から動画を生成する方法
- '`video_generate`ツールのパラメータを理解する場合'
summary: 12個のプロバイダーバックエンドを使って、テキスト、画像、または既存の動画から動画を生成する
title: 動画生成
x-i18n:
generated_at: "2026-04-07T04:47:51Z"
generated_at: "2026-04-11T02:48:59Z"
model: gpt-5.4
provider: openai
source_hash: bf1224c59a5f1217f56cf2001870aca710a09268677dcd12aad2efbe476e47b7
source_hash: 6848d03ef578181902517d068e8d9fe2f845e572a90481bbdf7bd9f1c591f245
source_path: tools/video-generation.md
workflow: 15
---
# 動画生成
OpenClawエージェントは、テキストプロンプト、参照画像、または既存の動画から動画を生成できます。12種類のプロバイダーバックエンドがサポートされており、それぞれ異なるモデルオプション、入力モード、機能セットを備えています。エージェントは、設定内容と利用可能なAPIキーに基づいて、適切なプロバイダーを自動的に選択します。
OpenClawエージェントは、テキストプロンプト、参照画像、または既存の動画から動画を生成できます。12個のプロバイダーバックエンドがサポートされており、それぞれ異なるモデルオプション、入力モード、機能セットを持っています。エージェントは、設定と利用可能なAPIキーに基づいて適切なプロバイダーを自動的に選択します。
<Note>
`video_generate` toolは、少なくとも1つの動画生成プロバイダーが利用可能な場合にのみ表示されます。agent toolsに表示されない場合は、provider API keyを設定するか、`agents.defaults.videoGenerationModel`を設定してください。
少なくとも1つの動画生成プロバイダーが利用可能な場合にのみ、`video_generate`ツールが表示されます。エージェントツール内に表示されない場合は、プロバイダーAPIキーを設定するか、`agents.defaults.videoGenerationModel`を構成してください。
</Note>
OpenClawは動画生成を3つのruntime modesとして扱います:
OpenClawは、動画生成を3つのランタイムモードとして扱います。
- 参照メディアなしのテキストから動画へのリクエストには`generate`
- 1つ以上の参照画像を含むリクエストには`imageToVideo`
- 1つ以上の参照動画を含むリクエストには`videoToVideo`
- 参照メディアなしのtext-to-videoリクエストには`generate`
- リクエストに1つ以上の参照画像が含まれる場合は`imageToVideo`
- リクエストに1つ以上の参照動画が含まれる場合は`videoToVideo`
プロバイダーは、これらのモードの任意の部分集合をサポートできます。toolは送信前にアクティブな
modeを検証し、`action=list`でサポートされるモードを報告します。
プロバイダーはこれらのモードの任意の部分集合をサポートできます。ツールは送信前にアクティブなモードを検証し、`action=list`でサポートされているモードを報告します。
## クイックスタート
1. サポートされているいずれかのプロバイダーに対してAPIキーを設定します:
1. サポートされている任意のプロバイダーのAPIキーを設定します:
```bash
export GEMINI_API_KEY="your-key"
@ -45,35 +44,35 @@ export GEMINI_API_KEY="your-key"
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
```
3. agentに依頼します:
3. エージェントに依頼します:
> 夕焼けの中でフレンドリーなロブスターがサーフィンしている、5秒のシネマティックな動画を生成して。
> 夕焼けの中、やさしいロブスターがサーフィンしている5秒のシネマティックな動画を生成して。
agentは自動的に`video_generate`を呼び出します。tool allowlistingは不要です。
エージェントは自動的に`video_generate`を呼び出します。ツールallowlistは不要です。
## 動画を生成すると何が起こるか
動画生成は非同期です。セッション内でagentが`video_generate`を呼び出すと:
動画生成は非同期です。セッション内でエージェントが`video_generate`を呼び出すと:
1. OpenClawはリクエストをプロバイダーに送信し、即座にtask IDを返します。
2. プロバイダーはバックグラウンドでジョブを処理します（通常はプロバイダーと解像度に応じて30秒から5分）。
3. 動画の準備ができると、OpenClawは内部完了イベントで同じセッションを再開します。
4. agentは完成した動画を元の会話に投稿します。
1. OpenClawはリクエストをプロバイダーに送信し、すぐにタスクIDを返します。
2. プロバイダーはバックグラウンドでジョブを処理します（通常はプロバイダーや解像度に応じて30秒から5分）。
3. 動画の準備ができると、OpenClawは内部完了イベントで同じセッションを起こします。
4. エージェントは完成した動画を元の会話に投稿します。
ジョブの処理中に、同じセッションで重複した`video_generate`呼び出しがあると、新しい生成を開始する代わりに現在のtask statusを返します。CLIから進行状況を確認するには、`openclaw tasks list`または`openclaw tasks show <taskId>`を使用してください。
ジョブが進行中の間、同じセッション内で重複する`video_generate`呼び出しは、新しい生成を開始する代わりに現在のタスク状態を返します。CLIから進行状況を確認するには、`openclaw tasks list`または`openclaw tasks show <taskId>`を使ってください。
セッションに紐づくagent実行の外部（たとえば直接のtool呼び出し）では、toolはインライン生成にフォールバックし、同じターンで最終メディアパスを返します。
セッションに紐づくエージェント実行以外（たとえば直接ツール呼び出し）では、ツールはインライン生成へフォールバックし、同じターン内で最終メディアパスを返します。
### タスクライフサイクル
各`video_generate`リクエストは、4つの状態を経由します:
各`video_generate`リクエストは4つの状態を移動します。
1. **queued** -- taskが作成され、プロバイダーが受け付けるのを待っている状態です。
2. **running** -- プロバイダーが処理中です（通常はプロバイダーと解像度に応じて30秒から5分）。
3. **succeeded** -- 動画の準備完了。agentが再開し、会話に投稿します。
4. **failed** -- プロバイダーエラーまたはタイムアウト。agentがエラー詳細付きで再開します。
1. **queued** -- タスクが作成され、プロバイダーが受け付けるのを待っている状態。
2. **running** -- プロバイダーが処理中（通常はプロバイダーや解像度に応じて30秒から5分）。
3. **succeeded** -- 動画が準備完了。エージェントが起きて会話に投稿します。
4. **failed** -- プロバイダーエラーまたはタイムアウト。エージェントがエラー詳細付きで起きます。
CLIから状態を確認するには:
CLIから状態を確認します:
```bash
openclaw tasks list
@ -81,118 +80,114 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
重複防止: 現在のセッションですでに動画taskが`queued`または`running`の場合、`video_generate`は新しいtaskを開始する代わりに既存taskのstatusを返します。新しい生成をトリガーせず明示的に確認したい場合は、`action: "status"`を使用してください。
重複防止: 現在のセッションですでに動画タスクが`queued`または`running`の場合、`video_generate`は新しいタスクを開始する代わりに既存タスクの状態を返します。新しい生成をトリガーせず明示的に確認するには、`action: "status"`を使ってください。
## サポートされているプロバイダー
| Provider | デフォルトモデル | テキスト | 画像参照 | 動画参照 | API key |
| -------- | ------------------------------- | ---- | ----------------- | ---------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | はい | はい（リモートURL） | はい（リモートURL） | `MODELSTUDIO_API_KEY` |
| BytePlus | `seedance-1-0-lite-t2v-250428` | はい | 画像1枚 | いいえ | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | はい | 画像1枚 | いいえ | `COMFY_API_KEY` または `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | はい | 画像1枚 | いいえ | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | はい | 画像1枚 | 動画1本 | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | はい | 画像1枚 | いいえ | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | はい | 画像1枚 | 動画1本 | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | はい | はい（リモートURL） | はい（リモートURL） | `QWEN_API_KEY` |
| Runway | `gen4.5` | はい | 画像1枚 | 動画1本 | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | はい | 画像1枚 | いいえ | `TOGETHER_API_KEY` |
| Vydra | `veo3` | はい | 画像1枚（`kling`） | いいえ | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | はい | 画像1枚 | 動画1本 | `XAI_API_KEY` |
| プロバイダー | デフォルトモデル | テキスト | 画像参照 | 動画参照 | APIキー |
| ------------ | ------------------------------- | -------- | ----------------- | ---------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | Yes | Yes（リモートURL） | Yes（リモートURL） | `MODELSTUDIO_API_KEY` |
| BytePlus | `seedance-1-0-lite-t2v-250428` | Yes | 1 image | No | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | Yes | 1 image | No | `COMFY_API_KEY` or `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | Yes | 1 image | No | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | Yes | 1 image | 1 video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | Yes | 1 image | No | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | Yes | 1 image | 1 video | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | Yes | Yes（リモートURL） | Yes（リモートURL） | `QWEN_API_KEY` |
| Runway | `gen4.5` | Yes | 1 image | 1 video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Yes | 1 image | No | `TOGETHER_API_KEY` |
| Vydra | `veo3` | Yes | 1 image（`kling`） | No | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | Yes | 1 image | 1 video | `XAI_API_KEY` |
一部のプロバイダーは追加または代替のAPI key env varsを受け付けます。詳細は各[provider pages](#related)を参照してください。
一部のプロバイダーは、追加または代替のAPIキーenv varも受け付けます。詳細は個別の[プロバイダーページ](#related)を参照してください。
実行時に利用可能なプロバイダー、モデル、
runtime modesを確認するには、`video_generate action=list`を実行してください。
利用可能なプロバイダー、モデル、ランタイムモードをランタイムで確認するには、`video_generate action=list`を実行してください。
### 宣言された機能マトリクス
### 宣言済みcapabilityマトリクス
これは、`video_generate`、contract tests、
および共有live sweepで使用される明示的なmode contractです。
これは、`video_generate`、契約テスト、および共有live sweepで使用される明示的なモード契約です。
| Provider | `generate` | `imageToVideo` | `videoToVideo` | 現在の共有live lanes |
| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | はい | はい | はい | `generate`、`imageToVideo`。`videoToVideo`は、このproviderがリモート`http(s)`動画URLを必要とするためスキップ |
| BytePlus | はい | はい | いいえ | `generate`、`imageToVideo` |
| ComfyUI | はい | はい | いいえ | 共有sweepには含まれません。workflow固有のカバレッジはComfy tests側にあります |
| fal | はい | はい | いいえ | `generate`、`imageToVideo` |
| Google | はい | はい | はい | `generate`、`imageToVideo`。共有`videoToVideo`は、現在のbuffer-backed Gemini/Veo sweepがその入力を受け付けないためスキップ |
| MiniMax | はい | はい | いいえ | `generate`、`imageToVideo` |
| OpenAI | はい | はい | はい | `generate`、`imageToVideo`。共有`videoToVideo`は、このorg/input pathが現在provider側のinpaint/remixアクセスを必要とするためスキップ |
| Qwen | はい | はい | はい | `generate`、`imageToVideo`。`videoToVideo`は、このproviderがリモート`http(s)`動画URLを必要とするためスキップ |
| Runway | はい | はい | はい | `generate`、`imageToVideo`。`videoToVideo`は、選択したモデルが`runway/gen4_aleph`の場合にのみ実行されます |
| Together | はい | はい | いいえ | `generate`、`imageToVideo` |
| Vydra | はい | はい | いいえ | `generate`。共有`imageToVideo`は、バンドル済み`veo3`がテキスト専用で、バンドル済み`kling`がリモート画像URLを必要とするためスキップ |
| xAI | はい | はい | はい | `generate`、`imageToVideo`。`videoToVideo`は、このproviderが現在リモートMP4 URLを必要とするためスキップ |
| プロバイダー | `generate` | `imageToVideo` | `videoToVideo` | 現在の共有live lane |
| ------------ | ---------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | Yes | Yes | Yes | `generate`、`imageToVideo`; このプロバイダーはリモート`http(s)`動画URLを必要とするため`videoToVideo`はスキップ |
| BytePlus | Yes | Yes | No | `generate`、`imageToVideo` |
| ComfyUI | Yes | Yes | No | 共有sweepには含まれない; workflow固有のカバレッジはComfyテスト側にある |
| fal | Yes | Yes | No | `generate`、`imageToVideo` |
| Google | Yes | Yes | Yes | `generate`、`imageToVideo`; 現在のbufferベースGemini/Veo sweepではその入力を受け付けないため、共有`videoToVideo`はスキップ |
| MiniMax | Yes | Yes | No | `generate`、`imageToVideo` |
| OpenAI | Yes | Yes | Yes | `generate`、`imageToVideo`; このorg/入力パスは現在プロバイダー側のinpaint/remixアクセスを必要とするため、共有`videoToVideo`はスキップ |
| Qwen | Yes | Yes | Yes | `generate`、`imageToVideo`; このプロバイダーはリモート`http(s)`動画URLを必要とするため`videoToVideo`はスキップ |
| Runway | Yes | Yes | Yes | `generate`、`imageToVideo`; `videoToVideo`は選択モデルが`runway/gen4_aleph`のときのみ実行 |
| Together | Yes | Yes | No | `generate`、`imageToVideo` |
| Vydra | Yes | Yes | No | `generate`; 同梱の`veo3`はtext専用で、同梱の`kling`はリモート画像URLを必要とするため、共有`imageToVideo`はスキップ |
| xAI | Yes | Yes | Yes | `generate`、`imageToVideo`; このプロバイダーは現在リモートMP4 URLを必要とするため`videoToVideo`はスキップ |
## Tool parameters
## ツールパラメータ
### 必須
| Parameter | Type | 説明 |
| --------- | ------ | ----------------------------------------------------------------------------- |
| `prompt` | string | 生成する動画のテキスト説明（`action: "generate"`では必須） |
| パラメータ | 型 | 説明 |
| ---------- | ------ | -------------------------------------------------------------- |
| `prompt` | string | 生成する動画のテキスト説明（`action: "generate"`で必須） |
### コンテンツ入力
| Parameter | Type | 説明 |
| --------- | -------- | ------------------------------------ |
| `image` | string | 単一の参照画像（パスまたはURL） |
| `images` | string[] | 複数の参照画像（最大5枚） |
| `video` | string | 単一の参照動画（パスまたはURL） |
| `videos` | string[] | 複数の参照動画（最大4本） |
| パラメータ | 型 | 説明 |
| ---------- | -------- | ------------------------------------ |
| `image` | string | 単一の参照画像（パスまたはURL） |
| `images` | string[] | 複数の参照画像（最大5件） |
| `video` | string | 単一の参照動画（パスまたはURL） |
| `videos` | string[] | 複数の参照動画（最大4件） |
### スタイル制御
| Parameter | Type | 説明 |
| パラメータ | 型 | 説明 |
| ----------------- | ------- | ------------------------------------------------------------------------ |
| `aspectRatio` | string | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` |
| `resolution` | string | `480P`、`720P`、`768P`、または`1080P` |
| `durationSeconds` | number | 目標の長さ（秒、最も近いprovider対応値に丸められます） |
| `size` | string | providerが対応している場合のサイズヒント |
| `audio` | boolean | 対応している場合に生成音声を有効化 |
| `watermark` | boolean | 対応している場合にproviderの透かしを切り替え |
| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `resolution` | string | `480P`, `720P`, `768P`, または`1080P` |
| `durationSeconds` | number | 目標の長さ（秒）。最も近いプロバイダー対応値に丸められる |
| `size` | string | プロバイダーが対応している場合のサイズヒント |
| `audio` | boolean | 対応時に生成音声を有効化 |
| `watermark` | boolean | 対応時にプロバイダー透かしを切り替え |
### 高度な項目
### 高度な設定
| Parameter | Type | 説明 |
| ---------- | ------ | ----------------------------------------------- |
| パラメータ | 型 | 説明 |
| ---------- | ------ | ------------------------------------------------- |
| `action` | string | `"generate"`（デフォルト）、`"status"`、または`"list"` |
| `model` | string | provider/model上書き（例: `runway/gen4.5`） |
| `filename` | string | 出力ファイル名のヒント |
| `model` | string | プロバイダー/モデルのoverride（例: `runway/gen4.5`） |
| `filename` | string | 出力ファイル名ヒント |
すべてのプロバイダーがすべてのパラメーターをサポートしているわけではありません。OpenClawはすでにdurationを最も近いprovider対応値に正規化しており、フォールバック先providerが異なるcontrol surfaceを公開している場合には、size-to-aspect-ratioのような翻訳済みgeometry hintsも再マッピングします。本当に未対応の上書きはベストエフォートで無視され、tool result内で警告として報告されます。厳格な機能制限（参照入力が多すぎる場合など）は送信前に失敗します。
すべてのプロバイダーがすべてのパラメータをサポートしているわけではありません。OpenClawはすでにdurationを最も近いプロバイダー対応値へ正規化し、フォールバック先プロバイダーが異なる制御サーフェスを公開している場合は、sizeからaspect-ratioへのような変換済みgeometry hintも再対応付けします。本当に未対応のoverrideはbest-effortで無視され、ツール結果内のwarningとして報告されます。厳格なcapability制限（参照入力が多すぎるなど）は送信前に失敗します。
tool resultには適用された設定が報告されます。providerフォールバック中にOpenClawがdurationやgeometryを再マッピングした場合、返される`durationSeconds`、`size`、`aspectRatio`、`resolution`の値には実際に送信された内容が反映され、`details.normalization`には要求値から適用値への変換が記録されます。
ツール結果は適用された設定を報告します。OpenClawがプロバイダーフォールバック中にdurationやgeometryを再対応付けした場合、返される`durationSeconds`、`size`、`aspectRatio`、`resolution`値は送信された内容を反映し、`details.normalization`には要求値から適用値への変換が記録されます。
参照入力はruntime modeも選択します:
参照入力はランタイムモードも選択します。
- 参照メディアなし: `generate`
- 画像参照がある場合: `imageToVideo`
- 動画参照がある場合: `videoToVideo`
- 何らかの画像参照あり: `imageToVideo`
- 何らかの動画参照あり: `videoToVideo`
画像参照と動画参照の混在は、安定した共有機能表面ではありません。
1リクエストにつき1種類の参照タイプを推奨します。
画像参照と動画参照の混在は、安定した共有capabilityサーフェスではありません。1リクエストにつき1種類の参照タイプを推奨します。
## Actions
## アクション
- **generate**（デフォルト） -- 与えられたプロンプトと任意の参照入力から動画を作成します。
- **status** -- 新しい生成を開始せず、現在のセッションで処理中の動画taskの状態を確認します。
- **list** -- 利用可能なプロバイダー、モデル、およびそれらの機能を表示します。
- **generate**（デフォルト） -- 与えられたプロンプトと任意の参照入力から動画を生成します。
- **status** -- 現在のセッションで進行中の動画タスク状態を、新しい生成を開始せずに確認します。
- **list** -- 利用可能なプロバイダー、モデル、およびそのcapabilityを表示します。
## モデル選択
動画生成時、OpenClawは次の順でモデルを解決します:
動画生成時、OpenClawは次の順序でモデルを解決します。
1. **`model` tool parameter** -- agentが呼び出し時に指定した場合。
2. **`videoGenerationModel.primary`** -- configから。
3. **`videoGenerationModel.fallbacks`** -- 順番に試行されます。
4. **自動検出** -- 有効なauthを持つプロバイダーを使用し、まず現在のデフォルトproviderから、次に残りのプロバイダーをアルファベット順で試します。
1. **`model`ツールパラメータ** -- エージェントが呼び出し時に指定した場合。
2. **`videoGenerationModel.primary`** -- 設定から。
3. **`videoGenerationModel.fallbacks`** -- 順番に試行。
4. **自動検出** -- 有効な認証を持つプロバイダーを使用し、現在のデフォルトプロバイダーから始め、その後は残りのプロバイダーをアルファベット順で試します。
プロバイダーが失敗した場合、次の候補が自動的に試されます。すべての候補が失敗した場合、エラーには各試行の詳細が含まれます。
動画生成で明示的な`model`、`primary`、`fallbacks`
エントリのみを使用したい場合は、`agents.defaults.mediaGenerationAutoProviderFallback: false`を設定してください。
動画生成で明示的な`model`、`primary`、`fallbacks`エントリだけを使いたい場合は、`agents.defaults.mediaGenerationAutoProviderFallback: false`を設定してください。
```json5
{
@ -207,28 +202,54 @@ tool resultには適用された設定が報告されます。providerフォー
}
```
## プロバイダーノート
fal上のHeyGen video-agentは次のように固定できます。
| Provider | Notes |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | DashScope/Model Studioの非同期endpointを使用します。参照画像と動画はリモート`http(s)` URLである必要があります。 |
| BytePlus | 単一の参照画像のみです。 |
| ComfyUI | workflow駆動のローカルまたはクラウド実行です。設定済みgraphを通じてtext-to-videoとimage-to-videoをサポートします。 |
| fal | 長時間実行ジョブにqueue-backed flowを使用します。単一の参照画像のみです。 |
| Google | Gemini/Veoを使用します。1枚の画像または1本の動画参照をサポートします。 |
| MiniMax | 単一の参照画像のみです。 |
| OpenAI | `size`上書きのみが転送されます。他のスタイル上書き（`aspectRatio`、`resolution`、`audio`、`watermark`）は警告付きで無視されます。 |
| Qwen | Alibabaと同じDashScopeバックエンドです。参照入力はリモート`http(s)` URLである必要があり、ローカルファイルは事前に拒否されます。 |
| Runway | data URI経由でローカルファイルをサポートします。video-to-videoには`runway/gen4_aleph`が必要です。テキスト専用実行では`16:9`と`9:16`のaspect ratiosを公開します。 |
| Together | 単一の参照画像のみです。 |
| Vydra | 認証が落ちるリダイレクトを避けるため、`https://www.vydra.ai/api/v1`を直接使用します。`veo3`はバンドル済みでtext-to-video専用、`kling`はリモート画像URLが必要です。 |
| xAI | text-to-video、image-to-video、およびリモート動画の編集/拡張フローをサポートします。 |
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "fal/fal-ai/heygen/v2/video-agent",
},
},
},
}
```
## プロバイダー機能モード
fal上のSeedance 2.0は次のように固定できます。
共有の動画生成contractでは、プロバイダーが単なるフラットな集約制限ではなく、
モード固有のcapabilitiesを宣言できるようになりました。新しいprovider
実装では、明示的なmode blocksを優先してください:
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
},
},
},
}
```
## プロバイダーメモ
| プロバイダー | メモ |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | DashScope/Model Studioの非同期エンドポイントを使用します。参照画像と参照動画はリモート`http(s)` URLである必要があります。 |
| BytePlus | 単一の画像参照のみ。 |
| ComfyUI | workflow駆動のローカルまたはクラウド実行。構成されたグラフを通じてtext-to-videoとimage-to-videoをサポートします。 |
| fal | 長時間実行ジョブにはqueueベースのフローを使用します。単一の画像参照のみ。HeyGen video-agentとSeedance 2.0のtext-to-videoおよびimage-to-videoモデル参照を含みます。 |
| Google | Gemini/Veoを使用します。1つの画像または1つの動画参照をサポートします。 |
| MiniMax | 単一の画像参照のみ。 |
| OpenAI | `size` overrideのみが転送されます。その他のスタイルoverride（`aspectRatio`、`resolution`、`audio`、`watermark`）はwarning付きで無視されます。 |
| Qwen | Alibabaと同じDashScopeバックエンドです。参照入力はリモート`http(s)` URLである必要があり、ローカルファイルは事前に拒否されます。 |
| Runway | data URI経由でローカルファイルをサポートします。video-to-videoには`runway/gen4_aleph`が必要です。text-only実行では`16:9`および`9:16`のaspect ratioを公開します。 |
| Together | 単一の画像参照のみ。 |
| Vydra | 認証が落ちるリダイレクトを避けるため、`https://www.vydra.ai/api/v1`を直接使用します。`veo3`はtext-to-video専用として同梱され、`kling`にはリモート画像URLが必要です。 |
| xAI | text-to-video、image-to-video、およびリモート動画edit/extendフローをサポートします。 |
## プロバイダーcapabilityモード
共有動画生成契約では、フラットな集計制限だけでなく、プロバイダーがモード固有のcapabilityを宣言できるようになりました。新しいプロバイダー実装では、明示的なモードブロックを優先してください。
```typescript
capabilities: {
@ -252,15 +273,11 @@ capabilities: {
}
```
`maxInputImages`や`maxInputVideos`のようなフラットな集約フィールドだけでは、
transform-mode supportを示すには不十分です。プロバイダーは
`generate`、`imageToVideo`、`videoToVideo`を明示的に宣言し、live tests、
contract tests、および共有の`video_generate` toolがmode supportを
決定的に検証できるようにする必要があります。
`maxInputImages`や`maxInputVideos`のようなフラットな集計フィールドだけでは、transform-modeサポートを告知するには不十分です。liveテスト、契約テスト、および共有`video_generate`ツールがモードサポートを決定的に検証できるよう、プロバイダーは`generate`、`imageToVideo`、`videoToVideo`を明示的に宣言するべきです。
## Live tests
## liveテスト
共有バンドル済みプロバイダー向けのオプトインlive coverage:
共有の同梱プロバイダー向けオプトインliveカバレッジ:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -272,21 +289,19 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv
pnpm test:live:media video
```
このliveファイルは、欠けているprovider env varsを`~/.profile`から読み込み、
デフォルトでは保存済みauth profilesよりlive/env API keysを優先し、ローカルメディアで安全に実行できる宣言済みモードを実行します:
このliveファイルは、不足しているプロバイダーenv varを`~/.profile`から読み込み、デフォルトで保存済み認証プロファイルよりlive/env APIキーを優先し、ローカルメディアで安全に実行できる宣言済みモードを実行します。
- sweep内のすべてのプロバイダーに対する`generate`
- `capabilities.imageToVideo.enabled`のときの`imageToVideo`
- `capabilities.videoToVideo.enabled`であり、provider/model
が共有sweep内でbuffer-backedローカル動画入力を受け付けるときの`videoToVideo`
- `capabilities.imageToVideo.enabled`の場合の`imageToVideo`
- `capabilities.videoToVideo.enabled`で、かつプロバイダー/モデルが共有sweep内でbufferベースのローカル動画入力を受け付ける場合の`videoToVideo`
現在、共有の`videoToVideo` live laneが対象としているのは:
現在、共有`videoToVideo` live laneがカバーするのは次です。
- `runway`（`runway/gen4_aleph`を選択した場合のみ）
## 設定
OpenClaw configでデフォルトの動画生成モデルを設定します:
OpenClaw設定でデフォルトの動画生成モデルを設定します。
```json5
{
@ -301,7 +316,7 @@ OpenClaw configでデフォルトの動画生成モデルを設定します:
}
```
またはCLIから:
またはCLI経由:
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"
@ -309,8 +324,8 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## 関連
- [Tools Overview](/ja-JP/tools)
- [Background Tasks](/ja-JP/automation/tasks) -- 非同期動画生成のtask追跡
- [ツール概要](/ja-JP/tools)
- [バックグラウンドタスク](/ja-JP/automation/tasks) -- 非同期動画生成のタスク追跡
- [Alibaba Model Studio](/ja-JP/providers/alibaba)
- [BytePlus](/ja-JP/concepts/model-providers#byteplus-international)
- [ComfyUI](/ja-JP/providers/comfy)
@ -323,5 +338,5 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
- [Together AI](/ja-JP/providers/together)
- [Vydra](/ja-JP/providers/vydra)
- [xAI](/ja-JP/providers/xai)
- [Configuration Reference](/ja-JP/gateway/configuration-reference#agent-defaults)
- [Models](/ja-JP/concepts/models)
- [設定リファレンス](/ja-JP/gateway/configuration-reference#agent-defaults)
- [モデル](/ja-JP/concepts/models)