diff --git a/docs/ja-JP/channels/matrix.md b/docs/ja-JP/channels/matrix.md index 8ebf7fc3f..6c9cde032 100644 --- a/docs/ja-JP/channels/matrix.md +++ b/docs/ja-JP/channels/matrix.md @@ -2,29 +2,29 @@ read_when: - OpenClawでのMatrixのセットアップ - MatrixのE2EEと検証の設定 -summary: Matrixのサポート状況、セットアップ、設定例 +summary: Matrixのサポート状況、セットアップ、および設定例 title: Matrix x-i18n: - generated_at: "2026-04-15T04:43:33Z" + generated_at: "2026-04-15T19:41:36Z" model: gpt-5.4 provider: openai - source_hash: 631f6fdcfebc23136c1a66b04851a25c047535d13cceba5650b8b421bc3afcf8 + source_hash: bd730bb9d0c8a548ee48b20931b3222e9aa1e6e95f1390b0c236645e03f3576d source_path: channels/matrix.md workflow: 15 --- # Matrix -MatrixはOpenClawのバンドル済みチャネルPluginです。 +MatrixはOpenClaw用のバンドルされたchannel Pluginです。 公式の`matrix-js-sdk`を使用し、DM、ルーム、スレッド、メディア、リアクション、投票、位置情報、E2EEをサポートします。 -## バンドル済みPlugin +## バンドルされたPlugin -Matrixは現在のOpenClawリリースではバンドル済みPluginとして提供されるため、通常の +Matrixは現在のOpenClawリリースではバンドルされたPluginとして同梱されているため、通常の パッケージ済みビルドでは別途インストールは不要です。 -古いビルドまたはMatrixを含まないカスタムインストールを使用している場合は、 -手動でインストールしてください。 +古いビルド、またはMatrixを除外したカスタムインストールを使用している場合は、手動で +インストールしてください。 npmからインストール: @@ -43,15 +43,15 @@ Pluginの動作とインストールルールについては、[Plugins](/ja-JP/ ## セットアップ 1. Matrix Pluginが利用可能であることを確認します。 - - 現在のパッケージ済みOpenClawリリースにはすでにバンドルされています。 - - 古いインストールやカスタムインストールでは、上記のコマンドで手動追加できます。 -2. homeserverでMatrixアカウントを作成します。 -3. `channels.matrix`を次のいずれかで設定します: + - 現在のパッケージ済みOpenClawリリースには、すでに同梱されています。 + - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 +2. ご利用のhomeserverでMatrixアカウントを作成します。 +3. `channels.matrix`を次のいずれかで設定します。 - `homeserver` + `accessToken`、または - `homeserver` + `userId` + `password`。 4. Gatewayを再起動します。 -5. ボットとのDMを開始するか、ルームに招待します。 - - 新規のMatrix招待は、`channels.matrix.autoJoin`で許可されている場合にのみ機能します。 +5. ボットとDMを開始するか、ルームに招待します。 + - 新しいMatrix招待は、`channels.matrix.autoJoin`で許可されている場合にのみ機能します。 対話型セットアップのパス: @@ -60,30 +60,30 @@ openclaw channels add openclaw configure --section channels ``` -Matrixウィザードが尋ねる項目: +Matrixウィザードでは、次の項目を尋ねます。 - homeserver URL -- 認証方法: access token または password -- ユーザーID（password認証のみ） -- 任意のデバイス名 -- E2EEを有効にするか -- ルームアクセスと招待自動参加を設定するか +- 認証方法: アクセストークンまたはパスワード +- ユーザーID（パスワード認証のみ） +- オプションのデバイス名 +- E2EEを有効にするかどうか +- ルームアクセスと招待自動参加を設定するかどうか -ウィザードの主な動作: +主なウィザードの動作: -- Matrix認証env varがすでに存在し、そのアカウントの認証情報がまだconfigに保存されていない場合、ウィザードは認証をenv varに保持するためのenvショートカットを提示します。 +- Matrix認証の環境変数がすでに存在し、そのアカウントの認証がまだconfigに保存されていない場合、ウィザードは認証を環境変数に保持するためのenvショートカットを提示します。 - アカウント名はアカウントIDに正規化されます。たとえば、`Ops Bot`は`ops-bot`になります。 -- DM allowlistエントリは`@user:server`をそのまま受け付けます。表示名は、ライブディレクトリ検索で完全一致が1件見つかった場合にのみ機能します。 -- ルームallowlistエントリは、ルームIDとエイリアスをそのまま受け付けます。`!room:server`または`#alias:server`を推奨します。未解決の名前はallowlist解決時に実行時に無視されます。 -- 招待自動参加のallowlistモードでは、安定した招待対象のみを使用してください: `!roomId:server`、`#alias:server`、または`*`。通常のルーム名は拒否されます。 +- DM allowlistエントリは`@user:server`をそのまま受け付けます。表示名が機能するのは、ライブディレクトリ検索で1件の完全一致が見つかった場合のみです。 +- ルーム allowlistエントリはルームIDとエイリアスをそのまま受け付けます。`!room:server`または`#alias:server`を推奨します。未解決の名前は、allowlist解決時にランタイムで無視されます。 +- 招待自動参加のallowlistモードでは、安定した招待ターゲットのみを使用してください: `!roomId:server`、`#alias:server`、または`*`。プレーンなルーム名は拒否されます。 - 保存前にルーム名を解決するには、`openclaw channels resolve --channel matrix "Project Room"`を使用します。 `channels.matrix.autoJoin`のデフォルトは`off`です。 -未設定のままにすると、ボットは招待されたルームや新しいDM形式の招待に参加しないため、手動で先に参加しない限り、新しいグループや招待されたDMには表示されません。 +これを未設定のままにすると、ボットは招待されたルームや新しいDM形式の招待に参加しないため、先に手動で参加しない限り、新しいグループや招待されたDMには表示されません。 -受け入れる招待を制限したい場合は、`autoJoin: "allowlist"`と`autoJoinAllowlist`を一緒に設定するか、すべての招待に参加させたい場合は`autoJoin: "always"`を設定してください。 +受け付ける招待を制限したい場合は、`autoJoinAllowlist`と一緒に`autoJoin: "allowlist"`を設定し、すべての招待に参加させたい場合は`autoJoin: "always"`を設定してください。 `allowlist`モードでは、`autoJoinAllowlist`は`!roomId:server`、`#alias:server`、または`*`のみ受け付けます。 @@ -118,7 +118,7 @@ allowlistの例: } ``` -最小構成のトークンベースセットアップ: +最小限のトークンベース設定: ```json5 { @@ -133,7 +133,7 @@ allowlistの例: } ``` -パスワードベースのセットアップ（ログイン後にトークンがキャッシュされます）: +パスワードベースの設定（ログイン後にトークンがキャッシュされます）: ```json5 { @@ -149,11 +149,11 @@ allowlistの例: } ``` -Matrixはキャッシュ済み認証情報を`~/.openclaw/credentials/matrix/`に保存します。 -デフォルトアカウントは`credentials.json`を使用し、名前付きアカウントは`credentials-.json`を使用します。 -そこにキャッシュ済み認証情報が存在する場合、現在の認証がconfigに直接設定されていなくても、OpenClawはセットアップ、doctor、チャネルステータス検出においてMatrixを設定済みとして扱います。 +Matrixはキャッシュされた認証情報を`~/.openclaw/credentials/matrix/`に保存します。 +デフォルトアカウントでは`credentials.json`を使用し、名前付きアカウントでは`credentials-.json`を使用します。 +そこにキャッシュされた認証情報が存在する場合、現在の認証がconfigに直接設定されていなくても、OpenClawはセットアップ、doctor、channel-status検出のためにMatrixが設定済みであると見なします。 -環境変数の対応（configキーが設定されていない場合に使用されます）: +環境変数の対応版（configキーが設定されていない場合に使用されます）: - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -162,7 +162,7 @@ Matrixはキャッシュ済み認証情報を`~/.openclaw/credentials/matrix/` - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -デフォルト以外のアカウントでは、アカウントスコープ付きenv varを使用します: +デフォルト以外のアカウントでは、アカウントスコープ付きの環境変数を使用します。 - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -176,19 +176,19 @@ Matrixはキャッシュ済み認証情報を`~/.openclaw/credentials/matrix/` - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -正規化されたアカウントID`ops-bot`では、次を使用します: +正規化されたアカウントID `ops-bot`では、次を使用します。 - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -MatrixはアカウントID内の句読点をエスケープして、スコープ付きenv varの衝突を防ぎます。 -たとえば、`-`は`_X2D_`になるため、`ops-prod`は`MATRIX_OPS_X2D_PROD_*`にマップされます。 +MatrixはアカウントID内の句読点をエスケープし、スコープ付き環境変数の衝突を防ぎます。 +たとえば、`-`は`_X2D_`になるため、`ops-prod`は`MATRIX_OPS_X2D_PROD_*`に対応します。 -対話型ウィザードがenv-varショートカットを提示するのは、それらの認証env varがすでに存在し、選択したアカウントにMatrix認証がまだconfigへ保存されていない場合のみです。 +対話型ウィザードがenv-varショートカットを提示するのは、それらの認証環境変数がすでに存在し、選択したアカウントにMatrix認証がまだconfigへ保存されていない場合のみです。 ## 設定例 -これは、DM pairing、ルームallowlist、E2EE有効化を含む実用的なベースライン設定です: +これは、DMペアリング、ルームallowlist、E2EE有効化を含む実用的なベースライン設定です。 ```json5 { @@ -223,16 +223,17 @@ MatrixはアカウントID内の句読点をエスケープして、スコープ } ``` -`autoJoin`はDM形式の招待を含むすべてのMatrix招待に適用されます。OpenClawは招待時点では -招待されたルームをDMかグループかとして確実に分類できないため、すべての招待は最初に`autoJoin`を通過します。 -`dm.policy`は、ボットが参加し、そのルームがDMとして分類された後に適用されます。 +`autoJoin`は、DM形式の招待を含むすべてのMatrix招待に適用されます。OpenClawは招待時点で +招待されたルームがDMかグループかを確実に分類できないため、すべての招待はまず`autoJoin` +を通ります。`dm.policy`は、ボットが参加してルームがDMとして分類された後に適用されます。 ## ストリーミングプレビュー Matrixの返信ストリーミングはオプトインです。 -OpenClawに単一のライブプレビュー返信を送信させ、モデルのテキスト生成中にそのプレビューをその場で編集し、 -返信完了時に確定させたい場合は、`channels.matrix.streaming`を`"partial"`に設定します: +OpenClawに単一のライブプレビュー返信を送信させ、モデルがテキストを生成している間はその +プレビューをその場で編集し、返信が完了したら確定させたい場合は、`channels.matrix.streaming` +を`"partial"`に設定します。 ```json5 { @@ -244,38 +245,37 @@ OpenClawに単一のライブプレビュー返信を送信させ、モデルの } ``` -- `streaming: "off"`がデフォルトです。OpenClawは最終返信を待ってから1回だけ送信します。 -- `streaming: "partial"`は、現在のアシスタントブロック用に通常のMatrixテキストメッセージを使った編集可能なプレビューメッセージを1つ作成します。これによりMatrixの従来の「プレビュー先行」通知動作が維持されるため、標準クライアントでは完成したブロックではなく、最初のストリーミングプレビューテキストで通知されることがあります。 -- `streaming: "quiet"`は、現在のアシスタントブロック用に編集可能な静かなプレビュー通知を1つ作成します。これを使用するのは、確定したプレビュー編集に対する受信者のプッシュルールも設定する場合のみにしてください。 -- `blockStreaming: true`は、個別のMatrix進捗メッセージを有効にします。プレビューのストリーミングが有効な場合、Matrixは現在のブロックのライブ下書きを維持し、完了済みブロックを個別のメッセージとして保持します。 -- プレビューが有効で`blockStreaming`がoffの場合、Matrixはライブ下書きをその場で編集し、ブロックまたはターンの完了時にその同じイベントを確定します。 -- プレビューが1つのMatrixイベントに収まらなくなった場合、OpenClawはプレビューのストリーミングを停止し、通常の最終配信にフォールバックします。 -- メディア返信は引き続き通常どおり添付ファイルを送信します。古いプレビューを安全に再利用できなくなった場合、OpenClawは最終メディア返信を送る前にそのプレビューを削除します。 -- プレビュー編集には追加のMatrix API呼び出しコストがかかります。もっとも保守的なレート制限の挙動を望む場合は、ストリーミングをoffのままにしてください。 +- `streaming: "off"`がデフォルトです。OpenClawは最終返信を待ってから1回送信します。 +- `streaming: "partial"`は、現在のassistantブロック用に通常のMatrixテキストメッセージを使った編集可能なプレビューを1つ作成します。これにより、Matrixの従来の「プレビュー先行」通知動作が維持されるため、標準クライアントでは完成したブロックではなく、最初のストリーミングプレビューテキストで通知される場合があります。 +- `streaming: "quiet"`は、現在のassistantブロック用に編集可能な静かなプレビュー通知を1つ作成します。これを使用するのは、確定したプレビュー編集に対する受信者のプッシュルールも設定する場合だけにしてください。 +- `blockStreaming: true`は、個別のMatrix進行状況メッセージを有効にします。プレビューストリーミングが有効な場合、Matrixは現在のブロックのライブ下書きを保持し、完了したブロックを別メッセージとして保持します。 +- プレビューストリーミングがオンで`blockStreaming`がオフの場合、Matrixはライブ下書きをその場で編集し、ブロックまたはターンの完了時にその同じイベントを確定します。 +- プレビューが1つのMatrixイベントに収まらなくなった場合、OpenClawはプレビューストリーミングを停止し、通常の最終配信にフォールバックします。 +- メディア返信は引き続き通常どおり添付ファイルを送信します。古いプレビューを安全に再利用できなくなった場合、OpenClawは最終的なメディア返信を送る前にそのプレビューをリダクトします。 +- プレビュー編集には追加のMatrix API呼び出しコストがかかります。最も保守的なレート制限動作を求める場合は、ストリーミングをオフのままにしてください。 -`blockStreaming`自体では下書きプレビューは有効になりません。 -プレビュー編集には`streaming: "partial"`または`streaming: "quiet"`を使用し、完了したアシスタントブロックも個別の進捗メッセージとして表示したい場合にのみ`blockStreaming: true`を追加してください。 +`blockStreaming`だけでは下書きプレビューは有効になりません。 +プレビュー編集には`streaming: "partial"`または`streaming: "quiet"`を使用し、完了したassistantブロックも個別の進行状況メッセージとして表示したい場合にのみ、さらに`blockStreaming: true`を追加してください。 -カスタムプッシュルールなしで標準のMatrix通知が必要な場合は、プレビュー先行の動作には`streaming: "partial"`を使用するか、最終配信のみでよければ`streaming`をoffのままにしてください。`streaming: "off"`では: +カスタムプッシュルールなしで標準のMatrix通知が必要な場合は、プレビュー先行動作のために`streaming: "partial"`を使用するか、最終配信のみのために`streaming`をオフのままにしてください。`streaming: "off"`の場合: -- `blockStreaming: true`は、完了した各ブロックを通常の通知付きMatrixメッセージとして送信します。 +- `blockStreaming: true`は、各完了ブロックを通常の通知付きMatrixメッセージとして送信します。 - `blockStreaming: false`は、最終的に完成した返信のみを通常の通知付きMatrixメッセージとして送信します。 -### 静かな確定プレビュー向けのセルフホストpush rules +### セルフホスト環境で、確定した静かなプレビュー用のプッシュルールを設定する -独自のMatrixインフラを運用していて、静かなプレビューでブロックまたは -最終返信の完了時のみ通知したい場合は、`streaming: "quiet"`を設定し、確定したプレビュー編集用のユーザーごとのpush ruleを追加します。 +独自のMatrixインフラを運用していて、ブロックまたは最終返信が完了したときにのみ静かなプレビューで通知したい場合は、`streaming: "quiet"`を設定し、確定したプレビュー編集用のユーザーごとのプッシュルールを追加します。 -これは通常、homeserver全体の設定変更ではなく、受信ユーザー側のセットアップです: +これは通常、homeserver全体の設定変更ではなく、受信ユーザー側の設定です。 -始める前の簡単な対応表: +開始前の簡単な対応関係: - recipient user = 通知を受け取る人 - bot user = 返信を送信するOpenClaw Matrixアカウント -- 以下のAPI呼び出しでは受信ユーザーのaccess tokenを使用する -- push rule内の`sender`はbot userの完全なMXIDに一致させる +- 以下のAPI呼び出しではrecipient userのアクセストークンを使用します +- プッシュルール内の`sender`はbot userの完全なMXIDに一致させます -1. OpenClawで静かなプレビューを使用するよう設定します: +1. OpenClawが静かなプレビューを使うように設定します。 ```json5 { @@ -287,13 +287,13 @@ OpenClawに単一のライブプレビュー返信を送信させ、モデルの } ``` -2. 受信アカウントがすでに通常のMatrixプッシュ通知を受け取れることを確認します。静かなプレビュー - ルールが機能するのは、そのユーザーにすでに動作中のpusher/deviceがある場合のみです。 +2. recipientアカウントがすでに通常のMatrixプッシュ通知を受け取っていることを確認します。静かなプレビュー + ルールが機能するのは、そのユーザーに有効なpusher/デバイスがすでにある場合のみです。 -3. 受信ユーザーのaccess tokenを取得します。 - - ボットのトークンではなく、受信ユーザーのトークンを使用します。 - - 既存のクライアントセッショントークンを再利用するのが通常はもっとも簡単です。 - - 新しいトークンを発行する必要がある場合は、標準のMatrix Client-Server API経由でログインできます: +3. recipient userのアクセストークンを取得します。 + - botのトークンではなく、受信側ユーザーのトークンを使用してください。 + - 既存のクライアントセッショントークンを再利用するのが通常は最も簡単です。 + - 新しいトークンを発行する必要がある場合は、標準のMatrix Client-Server APIからログインできます。 ```bash curl -sS -X POST \ @@ -309,7 +309,7 @@ curl -sS -X POST \ }' ``` -4. 受信アカウントにすでにpusherがあることを確認します: +4. recipientアカウントにすでにpusherがあることを確認します。 ```bash curl -sS \ @@ -317,10 +317,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -ここで有効なpusher/deviceが返ってこない場合は、以下の +これで有効なpusher/デバイスが返らない場合は、以下の OpenClawルールを追加する前に、まず通常のMatrix通知を修正してください。 -OpenClawは、確定したテキストのみのプレビュー編集に次の印を付けます: +OpenClawは、確定したテキストのみのプレビュー編集を次のようにマークします。 ```json { @@ -328,7 +328,7 @@ OpenClawは、確定したテキストのみのプレビュー編集に次の印 } ``` -5. これらの通知を受け取る各受信アカウントに対してoverride push ruleを作成します: +5. これらの通知を受け取る必要がある各recipientアカウントに対して、overrideプッシュルールを作成します。 ```bash curl -sS -X PUT \ @@ -358,25 +358,25 @@ curl -sS -X PUT \ }' ``` -コマンド実行前に次の値を置き換えてください: +コマンド実行前に次の値を置き換えてください。 -- `https://matrix.example.org`: あなたのhomeserverベースURL -- `$USER_ACCESS_TOKEN`: 受信ユーザーのaccess token -- `openclaw-finalized-preview-botname`: この受信ユーザーに対するこのボット専用の一意なrule ID -- `@bot:example.org`: 受信ユーザーのMXIDではなく、OpenClaw MatrixボットのMXID +- `https://matrix.example.org`: ご利用のhomeserverのベースURL +- `$USER_ACCESS_TOKEN`: 受信側ユーザーのアクセストークン +- `openclaw-finalized-preview-botname`: この受信側ユーザーに対するこのbot固有のルールID +- `@bot:example.org`: 受信側ユーザーのMXIDではなく、OpenClaw Matrix botのMXID -マルチボット構成で重要: +複数bot構成で重要な点: -- push ruleは`ruleId`で識別されます。同じrule IDに対して`PUT`を再実行すると、その1つのルールが更新されます。 -- 1人の受信ユーザーが複数のOpenClaw Matrixボットアカウントからの通知を受ける必要がある場合は、各`sender`一致ごとに一意のrule IDを持つルールをボットごとに1つ作成してください。 -- シンプルなパターンは`openclaw-finalized-preview-`です。たとえば、`openclaw-finalized-preview-ops`や`openclaw-finalized-preview-support`です。 +- プッシュルールは`ruleId`をキーにしています。同じルールIDに対して`PUT`を再実行すると、その1つのルールが更新されます。 +- 1人の受信ユーザーが複数のOpenClaw Matrix botアカウントに対して通知を受け取る必要がある場合は、各送信者一致ごとに一意のルールIDを使って、botごとに1つのルールを作成してください。 +- 単純なパターンは`openclaw-finalized-preview-`です。たとえば、`openclaw-finalized-preview-ops`や`openclaw-finalized-preview-support`です。 -このルールはイベント送信者に対して評価されます: +このルールはイベント送信者に対して評価されます。 - 受信ユーザーのトークンで認証する -- `sender`をOpenClawボットのMXIDに一致させる +- `sender`をOpenClaw botのMXIDに一致させる -6. ルールが存在することを確認します: +6. ルールが存在することを確認します。 ```bash curl -sS \ @@ -384,10 +384,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. ストリーミング返信をテストします。quietモードでは、ルームには静かな下書きプレビューが表示され、 - ブロックまたはターンが完了すると最終的なインプレース編集で1回通知されるはずです。 +7. ストリーミング返信をテストします。quietモードでは、ルームに静かな下書きプレビューが表示され、 + ブロックまたはターンが完了すると、最終的なインプレース編集で1回通知されるはずです。 -後でルールを削除する必要がある場合は、受信ユーザーのトークンで同じrule IDを削除します: +後でルールを削除する必要がある場合は、受信ユーザーのトークンを使って同じルールIDを削除してください。 ```bash curl -sS -X DELETE \ @@ -395,35 +395,35 @@ curl -sS -X DELETE \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -注記: +注意: -- ルールはボットのaccess tokenではなく、受信ユーザーのaccess tokenで作成してください。 -- 新しいユーザー定義の`override`ルールはデフォルトの抑制ルールより前に挿入されるため、追加の順序パラメータは不要です。 -- これは、OpenClawが安全にその場で確定できるテキストのみのプレビュー編集にのみ影響します。メディアフォールバックと古いプレビューフォールバックでは、引き続き通常のMatrix配信が使われます。 -- `GET /_matrix/client/v3/pushers`でpusherが表示されない場合、そのユーザーはまだそのアカウント/デバイスで動作するMatrixプッシュ配信を持っていません。 +- ルールはbotのトークンではなく、受信ユーザーのアクセストークンで作成してください。 +- 新しいユーザー定義の`override`ルールは、デフォルトの抑制ルールより前に挿入されるため、追加の順序パラメーターは不要です。 +- これは、OpenClawが安全にその場で確定できるテキストのみのプレビュー編集にのみ影響します。メディアへのフォールバックや古いプレビューへのフォールバックでは、通常のMatrix配信が引き続き使われます。 +- `GET /_matrix/client/v3/pushers`でpusherが表示されない場合、そのユーザーはまだこのアカウント/デバイスで有効なMatrixプッシュ配信を利用できていません。 #### Synapse -Synapseでは、通常は上記のセットアップだけで十分です: +Synapseでは、通常は上記のセットアップだけで十分です。 -- 確定したOpenClawプレビュー通知のために特別な`homeserver.yaml`変更は不要です。 -- Synapseデプロイですでに通常のMatrixプッシュ通知が送信されている場合、主なセットアップ手順は上記のユーザートークン + `pushrules`呼び出しです。 -- Synapseをリバースプロキシまたはworkerの背後で動かしている場合は、`/_matrix/client/.../pushrules/`が正しくSynapseに到達することを確認してください。 -- Synapse workerを使用している場合は、pusherが正常であることを確認してください。プッシュ配信はメインプロセスまたは`synapse.app.pusher` / 設定されたpusher workerによって処理されます。 +- 確定したOpenClawプレビュー通知のために、特別な`homeserver.yaml`変更は不要です。 +- Synapseのデプロイですでに通常のMatrixプッシュ通知が送信されている場合、主なセットアップ手順は上記のユーザートークン + `pushrules`呼び出しです。 +- Synapseをリバースプロキシまたはworkerの背後で実行している場合は、`/_matrix/client/.../pushrules/`が正しくSynapseに到達することを確認してください。 +- Synapse workersを使用している場合は、pusherが正常であることを確認してください。プッシュ配信はメインプロセスまたは`synapse.app.pusher` / 設定済みのpusher workerによって処理されます。 #### Tuwunel -Tuwunelでは、上記と同じセットアップフローとpush-rule API呼び出しを使用します: +Tuwunelでは、上記と同じセットアップフローとpush-rule API呼び出しを使用してください。 -- 確定プレビューマーカー自体に対して、Tuwunel固有の設定は不要です。 +- 確定したプレビューマーカー自体に対して、Tuwunel固有の設定は不要です。 - そのユーザーに対して通常のMatrix通知がすでに機能している場合、主なセットアップ手順は上記のユーザートークン + `pushrules`呼び出しです。 -- ユーザーが別のデバイスでアクティブな間に通知が消えるように見える場合は、`suppress_push_when_active`が有効になっていないか確認してください。Tuwunelは2025年9月12日のTuwunel 1.4.2でこのオプションを追加しており、1つのデバイスがアクティブな間、他のデバイスへのプッシュを意図的に抑制することがあります。 +- ユーザーが別のデバイスでアクティブな間に通知が消えるように見える場合は、`suppress_push_when_active`が有効になっているか確認してください。Tuwunelでは2025年9月12日のTuwunel 1.4.2でこのオプションが追加されており、1つのデバイスがアクティブな間、他のデバイスへのプッシュを意図的に抑制することがあります。 -## ボット同士のルーム +## bot同士のルーム -デフォルトでは、設定済みの他のOpenClaw MatrixアカウントからのMatrixメッセージは無視されます。 +デフォルトでは、他の設定済みOpenClaw MatrixアカウントからのMatrixメッセージは無視されます。 -エージェント間のMatrixトラフィックを意図的に許可したい場合は、`allowBots`を使用します: +意図的にagent間のMatrixトラフィックを許可したい場合は、`allowBots`を使用します。 ```json5 { @@ -440,17 +440,17 @@ Tuwunelでは、上記と同じセットアップフローとpush-rule API呼び } ``` -- `allowBots: true`は、許可されたルームとDMで、設定済みの他のMatrixボットアカウントからのメッセージを受け入れます。 -- `allowBots: "mentions"`は、ルーム内でそれらのメッセージがこのボットに明示的にメンションしている場合にのみ受け入れます。DMは引き続き許可されます。 +- `allowBots: true`は、許可されたルームとDMにおいて、他の設定済みMatrix botアカウントからのメッセージを受け付けます。 +- `allowBots: "mentions"`は、ルーム内でそのメッセージがこのbotに明示的にメンションしている場合にのみ受け付けます。DMは引き続き許可されます。 - `groups..allowBots`は、1つのルームに対してアカウントレベル設定を上書きします。 -- OpenClawは自己返信ループを避けるため、同じMatrixユーザーIDからのメッセージは引き続き無視します。 -- Matrixはここでネイティブのボットフラグを公開していません。OpenClawは「ボット作成」とは「このOpenClaw Gateway上の別の設定済みMatrixアカウントによって送信されたもの」と見なします。 +- OpenClawは自己返信ループを避けるため、同じMatrix user IDからのメッセージは引き続き無視します。 +- Matrixはここでネイティブのbotフラグを公開していません。OpenClawは「botが作成した」を「このOpenClaw gateway上の別の設定済みMatrixアカウントが送信した」と見なします。 -共有ルームでボット同士のトラフィックを有効にする場合は、厳格なルームallowlistとメンション必須設定を使用してください。 +共有ルームでbot同士のトラフィックを有効にする場合は、厳格なルームallowlistとメンション必須設定を使用してください。 ## 暗号化と検証 -暗号化された（E2EE）ルームでは、送信する画像イベントは`thumbnail_file`を使用するため、画像プレビューは完全な添付ファイルと一緒に暗号化されます。暗号化されていないルームでは、引き続き通常の`thumbnail_url`を使用します。設定は不要です — PluginがE2EE状態を自動検出します。 +暗号化された（E2EE）ルームでは、送信画像イベントは`thumbnail_file`を使用するため、画像プレビューは完全な添付ファイルとともに暗号化されます。暗号化されていないルームでは、引き続きプレーンな`thumbnail_url`を使用します。設定は不要で、PluginがE2EE状態を自動検出します。 暗号化を有効にする: @@ -468,43 +468,43 @@ Tuwunelでは、上記と同じセットアップフローとpush-rule API呼び } ``` -検証ステータスを確認する: +検証状態を確認する: ```bash openclaw matrix verify status ``` -詳細ステータス（完全な診断情報）: +詳細な状態（完全な診断情報）: ```bash openclaw matrix verify status --verbose ``` -保存済みのrecovery keyを機械可読出力に含める: +保存されているリカバリーキーを機械可読出力に含める: ```bash openclaw matrix verify status --include-recovery-key --json ``` -cross-signingと検証状態をbootstrapする: +クロス署名と検証状態をブートストラップする: ```bash openclaw matrix verify bootstrap ``` -詳細なbootstrap診断情報: +詳細なブートストラップ診断情報: ```bash openclaw matrix verify bootstrap --verbose ``` -bootstrap前に新しいcross-signing IDリセットを強制する: +ブートストラップ前に新しいクロス署名IDリセットを強制する: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -recovery keyでこのデバイスを検証する: +リカバリーキーでこのデバイスを検証する: ```bash openclaw matrix verify device "" @@ -516,19 +516,19 @@ openclaw matrix verify device "" openclaw matrix verify device "" --verbose ``` -ルームキーbackupの健全性を確認する: +ルームキーのバックアップ状態を確認する: ```bash openclaw matrix verify backup status ``` -詳細なbackup健全性診断情報: +詳細なバックアップ状態診断情報: ```bash openclaw matrix verify backup status --verbose ``` -サーバーbackupからルームキーを復元する: +サーバーバックアップからルームキーを復元する: ```bash openclaw matrix verify backup restore @@ -540,20 +540,20 @@ openclaw matrix verify backup restore openclaw matrix verify backup restore --verbose ``` -現在のサーバーbackupを削除し、新しいbackupベースラインを作成します。保存済みの -backup keyを正常に読み込めない場合、このリセットによってsecret storageも再作成され、 -将来のコールドスタートで新しいbackup keyを読み込めるようになることがあります: +現在のサーバーバックアップを削除し、新しいバックアップベースラインを作成します。保存されている +バックアップキーを正常に読み込めない場合、このリセットによって秘密ストレージも再作成され、 +今後のコールドスタートで新しいバックアップキーを読み込めるようになることがあります。 ```bash openclaw matrix verify backup reset --yes ``` -すべての`verify`コマンドはデフォルトで簡潔です（quietな内部SDKロギングを含む）で、詳細な診断情報は`--verbose`を付けた場合のみ表示されます。 +すべての`verify`コマンドはデフォルトで簡潔です（内部SDKログもquietを含む）で、詳細な診断情報は`--verbose`を付けた場合にのみ表示されます。 スクリプトで使用する場合は、完全な機械可読出力のために`--json`を使用してください。 -マルチアカウント構成では、Matrix CLIコマンドは`--account `を渡さない限り暗黙のMatrixデフォルトアカウントを使用します。 -複数の名前付きアカウントを設定する場合は、先に`channels.matrix.defaultAccount`を設定してください。設定しないと、それらの暗黙のCLI操作は停止して、どのアカウントを使うか明示的に選ぶよう求めます。 -検証またはデバイス操作を明示的に名前付きアカウントに向けたい場合は、常に`--account`を使用してください: +複数アカウント構成では、Matrix CLIコマンドは`--account `を渡さない限り暗黙のMatrixデフォルトアカウントを使用します。 +複数の名前付きアカウントを設定している場合は、まず`channels.matrix.defaultAccount`を設定してください。そうしないと、これらの暗黙のCLI操作は停止して、明示的にアカウント選択を求めます。 +検証またはデバイス操作を明示的に名前付きアカウントに向けたい場合は、常に`--account`を使用してください。 ```bash openclaw matrix verify status --account assistant @@ -561,42 +561,42 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -暗号化が無効または名前付きアカウントで利用不可の場合、Matrixの警告と検証エラーはそのアカウントのconfigキー、たとえば`channels.matrix.accounts.assistant.encryption`を指します。 +暗号化が無効、または名前付きアカウントで利用できない場合、Matrixの警告と検証エラーはそのアカウントのconfigキーを指します。たとえば`channels.matrix.accounts.assistant.encryption`です。 -### 「検証済み」の意味 +### 「verified」の意味 -OpenClawは、このMatrixデバイスがあなた自身のcross-signing IDによって検証されている場合にのみ、このデバイスを検証済みとして扱います。 -実際には、`openclaw matrix verify status --verbose`は3つの信頼シグナルを表示します: +OpenClawは、このMatrixデバイスがあなた自身のクロス署名IDによって検証されている場合にのみ、検証済みと見なします。 +実際には、`openclaw matrix verify status --verbose`は次の3つの信頼シグナルを表示します。 - `Locally trusted`: このデバイスは現在のクライアントでのみ信頼されています -- `Cross-signing verified`: SDKがこのデバイスをcross-signing経由で検証済みとして報告します -- `Signed by owner`: このデバイスはあなた自身のself-signing keyで署名されています +- `Cross-signing verified`: SDKが、このデバイスがクロス署名によって検証済みであると報告しています +- `Signed by owner`: このデバイスは、あなた自身のself-signingキーによって署名されています -`Verified by owner`が`yes`になるのは、cross-signingによる検証またはowner-signingが存在する場合のみです。 +`Verified by owner`が`yes`になるのは、クロス署名検証またはowner署名が存在する場合のみです。 ローカル信頼だけでは、OpenClawはこのデバイスを完全に検証済みとは見なしません。 -### bootstrapが行うこと +### ブートストラップが行うこと -`openclaw matrix verify bootstrap`は、暗号化されたMatrixアカウントの修復およびセットアップコマンドです。 -次のすべてを順に実行します: +`openclaw matrix verify bootstrap`は、暗号化されたMatrixアカウントの修復とセットアップのためのコマンドです。 +これにより、次のすべてが順番に実行されます。 -- secret storageをbootstrapし、可能であれば既存のrecovery keyを再利用する -- cross-signingをbootstrapし、不足している公開cross-signing keyをアップロードする -- 現在のデバイスに印を付けてcross-signingすることを試みる -- まだ存在しない場合は、新しいサーバー側のルームキーbackupを作成する +- 可能であれば既存のリカバリーキーを再利用して、秘密ストレージをブートストラップする +- クロス署名をブートストラップし、不足している公開クロス署名キーをアップロードする +- 現在のデバイスにマークを付けてクロス署名することを試みる +- サーバー側の新しいルームキーバックアップを、まだ存在しない場合に作成する -homeserverがcross-signing keyのアップロードに対して対話的認証を要求する場合、OpenClawはまず認証なしでアップロードを試行し、次に`m.login.dummy`で、`channels.matrix.password`が設定されている場合は`m.login.password`でも試行します。 +homeserverがクロス署名キーのアップロードに対話的認証を要求する場合、OpenClawはまず認証なしでアップロードを試し、その後`m.login.dummy`、さらに`channels.matrix.password`が設定されている場合は`m.login.password`を試します。 -`--force-reset-cross-signing`は、現在のcross-signing IDを破棄して新しいものを作成したい場合にのみ使用してください。 +`--force-reset-cross-signing`は、現在のクロス署名IDを破棄して新しいものを作成したい場合にのみ使用してください。 -現在のルームキーbackupを意図的に破棄し、今後のメッセージ用に新しい -backupベースラインを開始したい場合は、`openclaw matrix verify backup reset --yes`を使用してください。 -これは、回復不能な古い暗号化履歴が引き続き利用できないままであることと、 -現在のbackup secretを安全に読み込めない場合にOpenClawがsecret storageを再作成する可能性があることを受け入れる場合にのみ行ってください。 +現在のルームキーバックアップを意図的に破棄し、将来のメッセージ用に新しい +バックアップベースラインを開始したい場合は、`openclaw matrix verify backup reset --yes`を使用してください。 +これは、復元不可能な古い暗号化履歴が引き続き利用不能のままであること、および現在のバックアップ +シークレットを安全に読み込めない場合にOpenClawが秘密ストレージを再作成する可能性があることを受け入れる場合にのみ実行してください。 -### 新しいbackupベースライン +### 新しいバックアップベースライン -今後の暗号化メッセージを機能させ続けつつ、回復不能な古い履歴の喪失を受け入れる場合は、次のコマンドを順に実行してください: +将来の暗号化メッセージを引き続き利用可能にしつつ、復元不可能な古い履歴を失うことを受け入れる場合は、次のコマンドを順に実行してください。 ```bash openclaw matrix verify backup reset --yes @@ -609,68 +609,70 @@ openclaw matrix verify status ### 起動時の動作 `encryption: true`の場合、Matrixは`startupVerification`のデフォルトを`"if-unverified"`にします。 -起動時にこのデバイスがまだ未検証であれば、Matrixは別のMatrixクライアントで自己検証を要求し、 -すでに保留中の要求がある場合は重複要求をスキップし、再起動後の再試行前にローカルクールダウンを適用します。 -失敗した要求試行は、デフォルトでは要求作成の成功後よりも早く再試行されます。 -自動起動時要求を無効にするには`startupVerification: "off"`を設定するか、再試行ウィンドウを短くまたは長くしたい場合は`startupVerificationCooldownHours`を調整してください。 +起動時にこのデバイスがまだ未検証である場合、Matrixは別のMatrixクライアントで自己検証を要求し、 +すでに保留中の要求がある間は重複要求をスキップし、再起動後の再試行前にローカルのクールダウンを適用します。 +失敗した要求試行は、成功した要求作成よりもデフォルトで早く再試行されます。 +自動起動時要求を無効にするには`startupVerification: "off"`を設定し、再試行間隔を短くまたは長くしたい場合は`startupVerificationCooldownHours` +を調整してください。 -起動時には、保守的なcrypto bootstrapパスも自動的に実行されます。 -このパスは、最初に現在のsecret storageとcross-signing IDの再利用を試み、明示的なbootstrap修復フローを実行しない限りcross-signingのリセットを避けます。 +起動時には、保守的なcryptoブートストラップ処理も自動的に実行されます。 +この処理はまず現在の秘密ストレージとクロス署名IDの再利用を試み、明示的なブートストラップ修復フローを実行しない限り、クロス署名のリセットを避けます。 -起動時に壊れたbootstrap状態が見つかり、`channels.matrix.password`が設定されている場合、OpenClawはより厳格な修復パスを試みることがあります。 -現在のデバイスがすでにowner-signedである場合、OpenClawはそれを自動的にリセットせず、そのIDを保持します。 +それでも起動時に壊れたブートストラップ状態が見つかった場合、OpenClawは`channels.matrix.password`が設定されていなくても、保護付き修復パスを試みることがあります。 +その修復でhomeserverがパスワードベースのUIAを要求する場合、OpenClawは警告をログに出し、botを中止するのではなく起動を非致命のまま維持します。 +現在のデバイスがすでにowner署名済みである場合、OpenClawはそれを自動的にリセットせず、そのIDを保持します。 -完全なアップグレードフロー、制限、回復コマンド、一般的な移行メッセージについては、[Matrix migration](/ja-JP/install/migrating-matrix)を参照してください。 +完全なアップグレードフロー、制限、復旧コマンド、一般的な移行メッセージについては、[Matrix migration](/ja-JP/install/migrating-matrix)を参照してください。 ### 検証通知 Matrixは、厳格なDM検証ルームに検証ライフサイクル通知を`m.notice`メッセージとして直接投稿します。 -これには次が含まれます: +これには次が含まれます。 - 検証要求通知 - 検証準備完了通知（明示的な「絵文字で検証」ガイダンス付き） - 検証開始および完了通知 - 利用可能な場合のSAS詳細（絵文字と10進数） -別のMatrixクライアントからの受信検証要求は、OpenClawによって追跡され自動承認されます。 -自己検証フローでは、OpenClawは絵文字検証が利用可能になるとSASフローも自動的に開始し、自身の側を確認します。 -別のMatrixユーザー/デバイスからの検証要求については、OpenClawは要求を自動承認し、その後SASフローが通常どおり進行するのを待ちます。 -検証を完了するには、引き続きMatrixクライアントで絵文字または10進数のSASを比較し、そこで「一致する」を確認する必要があります。 +別のMatrixクライアントからの受信検証要求は、OpenClawが追跡して自動受諾します。 +自己検証フローでは、絵文字検証が利用可能になると、OpenClawはSASフローも自動的に開始し、自身の側を確認します。 +別のMatrixユーザー/デバイスからの検証要求については、OpenClawは要求を自動受諾し、その後SASフローが通常どおり進行するのを待ちます。 +検証を完了するには、引き続きMatrixクライアントで絵文字または10進SASを比較し、そこで「一致する」を確認する必要があります。 -OpenClawは、自己開始された重複フローを無条件に自動承認しません。自己検証要求がすでに保留中の場合、起動時に新しい要求の作成はスキップされます。 +OpenClawは、自己開始された重複フローを無条件に自動受諾しません。自己検証要求がすでに保留中の場合、起動時には新しい要求の作成をスキップします。 -検証プロトコル/システム通知はエージェントチャットパイプラインには転送されないため、`NO_REPLY`は生成されません。 +検証プロトコル/システム通知はagentチャットパイプラインには転送されないため、`NO_REPLY`は発生しません。 -### デバイス衛生 +### デバイス管理 -古いOpenClaw管理のMatrixデバイスがアカウントに蓄積し、暗号化ルームの信頼性を把握しにくくなることがあります。 -次のコマンドで一覧表示します: +古いOpenClaw管理のMatrixデバイスがアカウント上に蓄積し、暗号化ルームの信頼性を把握しづらくなることがあります。 +次のコマンドで一覧表示します。 ```bash openclaw matrix devices list ``` -古くなったOpenClaw管理デバイスを削除するには: +古いOpenClaw管理デバイスを削除するには: ```bash openclaw matrix devices prune-stale ``` -### Crypto store +### Cryptoストア -Matrix E2EEは、Node上で公式の`matrix-js-sdk` Rust cryptoパスを使用し、IndexedDB shimとして`fake-indexeddb`を使います。Crypto状態はスナップショットファイル（`crypto-idb-snapshot.json`）に永続化され、起動時に復元されます。スナップショットファイルは、制限されたファイル権限で保存される機密性の高いランタイム状態です。 +MatrixのE2EEは、Node上で公式の`matrix-js-sdk` Rust cryptoパスを使用し、IndexedDBのshimとして`fake-indexeddb`を使用します。Crypto状態はスナップショットファイル（`crypto-idb-snapshot.json`）に永続化され、起動時に復元されます。スナップショットファイルは機密性の高いランタイム状態であり、制限されたファイル権限で保存されます。 -暗号化されたランタイム状態は、アカウントごと・ユーザーのtoken-hashごとのルートの下に -`~/.openclaw/matrix/accounts//__//`として保存されます。 -このディレクトリには、sync store（`bot-storage.json`）、crypto store（`crypto/`）、 -recovery keyファイル（`recovery-key.json`）、IndexedDB snapshot（`crypto-idb-snapshot.json`）、 -thread binding（`thread-bindings.json`）、およびstartup verification state（`startup-verification.json`）が含まれます。 -トークンが変わってもアカウントIDが同じままであれば、OpenClawはそのアカウント/homeserver/user組み合わせに対して最適な既存ルートを再利用するため、以前のsync state、crypto state、thread binding、 -およびstartup verification stateは引き続き参照できます。 +暗号化されたランタイム状態は、アカウントごと・ユーザートークンハッシュごとのルート配下で +`~/.openclaw/matrix/accounts//__//`に保存されます。 +このディレクトリには、syncストア（`bot-storage.json`）、cryptoストア（`crypto/`）、 +リカバリーキーファイル（`recovery-key.json`）、IndexedDBスナップショット（`crypto-idb-snapshot.json`）、 +スレッドバインディング（`thread-bindings.json`）、起動時検証状態（`startup-verification.json`）が含まれます。 +トークンが変更されてもアカウントIDが同じままであれば、OpenClawはそのアカウント/homeserver/userタプルに対して最適な既存ルートを再利用するため、以前のsync状態、crypto状態、スレッドバインディング、 +起動時検証状態は引き続き利用できます。 ## プロファイル管理 -選択したアカウントのMatrixセルフプロファイルを更新するには、次を実行します: +選択したアカウントのMatrixセルフプロファイルを更新するには、次を使用します。 ```bash openclaw matrix profile set --name "OpenClaw Assistant" @@ -679,47 +681,47 @@ openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png 名前付きMatrixアカウントを明示的に対象にしたい場合は、`--account `を追加してください。 -Matrixは`mxc://` avatar URLをそのまま受け付けます。`http://`または`https://`のavatar URLを渡した場合、OpenClawはまずそれをMatrixにアップロードし、解決された`mxc://` URLを`channels.matrix.avatarUrl`（または選択したアカウントのoverride）に保存します。 +Matrixは`mxc://`アバターURLをそのまま受け付けます。`http://`または`https://`のアバターURLを渡した場合、OpenClawはまずそれをMatrixにアップロードし、解決後の`mxc://` URLを`channels.matrix.avatarUrl`（または選択したアカウントの上書き先）へ保存します。 ## スレッド -Matrixは、自動返信とmessage-tool送信の両方についてネイティブのMatrixスレッドをサポートします。 +Matrixは、自動返信とmessage-tool送信の両方でネイティブのMatrixスレッドをサポートします。 -- `dm.sessionScope: "per-user"`（デフォルト）は、Matrix DMルーティングを送信者スコープのままにするため、同じ相手に解決される複数のDMルームで1つのセッションを共有できます。 -- `dm.sessionScope: "per-room"`は、通常のDM認証とallowlistチェックを使いながら、各Matrix DMルームを独自のセッションキーに分離します。 -- 明示的なMatrix会話bindingは引き続き`dm.sessionScope`より優先されるため、binding済みのルームとスレッドは選択された対象セッションを維持します。 -- `threadReplies: "off"`は、返信をトップレベルのままにし、受信したスレッドメッセージを親セッション上に維持します。 -- `threadReplies: "inbound"`は、受信メッセージがすでにそのスレッド内にあった場合にのみ、スレッド内で返信します。 -- `threadReplies: "always"`は、トリガーとなったメッセージをルートとするスレッド内にルーム返信を維持し、その会話を最初のトリガーメッセージから対応するスレッドスコープのセッション経由でルーティングします。 +- `dm.sessionScope: "per-user"`（デフォルト）は、Matrix DMルーティングを送信者単位で維持するため、複数のDMルームが同じ相手に解決される場合は1つのセッションを共有できます。 +- `dm.sessionScope: "per-room"`は、通常のDM認証とallowlistチェックを維持しながら、各Matrix DMルームを独自のセッションキーに分離します。 +- 明示的なMatrix会話バインディングは引き続き`dm.sessionScope`より優先されるため、バインドされたルームとスレッドは選択された対象セッションを維持します。 +- `threadReplies: "off"`は返信をトップレベルに保ち、受信したスレッド付きメッセージを親セッション上で維持します。 +- `threadReplies: "inbound"`は、受信メッセージがすでにそのスレッド内にある場合にのみ、そのスレッド内で返信します。 +- `threadReplies: "always"`は、ルーム返信をトリガー元メッセージをルートとするスレッド内に維持し、その会話を最初のトリガー元メッセージに一致するスレッドスコープのセッションへルーティングします。 - `dm.threadReplies`は、DMに対してのみトップレベル設定を上書きします。たとえば、ルームスレッドは分離したまま、DMはフラットに保てます。 -- 受信したスレッドメッセージには、追加のagentコンテキストとしてスレッドのルートメッセージが含まれます。 -- message-tool送信は、明示的な`threadId`が指定されていない限り、対象が同じルームまたは同じDMユーザー対象であれば、現在のMatrixスレッドを自動継承します。 -- 同一セッションのDMユーザー対象再利用が有効になるのは、現在のセッションmetadataによって、同じMatrixアカウント上の同じDM相手であることが証明される場合のみです。それ以外では、OpenClawは通常のユーザースコープルーティングにフォールバックします。 -- OpenClawが、同じ共有Matrix DMセッション上で1つのMatrix DMルームが別のDMルームと衝突していることを検出すると、thread bindingが有効で`dm.sessionScope`ヒントがある場合、そのルームに`/focus`の退避手段を含む1回限りの`m.notice`を投稿します。 -- Matrixではランタイムthread bindingがサポートされます。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびスレッドにbindingされた`/acp spawn`は、MatrixルームとDMで動作します。 -- トップレベルのMatrixルーム/DMでの`/focus`は、`threadBindings.spawnSubagentSessions=true`のとき、新しいMatrixスレッドを作成し、それを対象セッションにbindします。 -- 既存のMatrixスレッド内で`/focus`または`/acp spawn --thread here`を実行すると、代わりにその現在のスレッドがbindされます。 +- 受信したスレッド付きメッセージには、追加のagentコンテキストとしてスレッドのルートメッセージが含まれます。 +- Message-tool送信は、明示的な`threadId`が指定されていない限り、対象が同じルーム、または同じDMユーザー対象であれば、現在のMatrixスレッドを自動的に継承します。 +- 同一セッションのDMユーザー対象の再利用は、現在のセッションメタデータが同じMatrixアカウント上の同一DM相手であることを証明している場合にのみ有効になります。それ以外の場合、OpenClawは通常のユーザースコープルーティングにフォールバックします。 +- OpenClawが、あるMatrix DMルームが同じ共有Matrix DMセッション上の別のDMルームと衝突していることを検出すると、スレッドバインディングが有効で`dm.sessionScope`ヒントがある場合、そのルームに`/focus`エスケープハッチ付きの1回限りの`m.notice`を投稿します。 +- Matrixはランタイムスレッドバインディングをサポートします。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびスレッドにバインドされた`/acp spawn`は、MatrixルームとDMで機能します。 +- トップレベルのMatrixルーム/DMでの`/focus`は、`threadBindings.spawnSubagentSessions=true`のとき、新しいMatrixスレッドを作成して対象セッションにバインドします。 +- 既存のMatrixスレッド内で`/focus`または`/acp spawn --thread here`を実行すると、代わりにその現在のスレッドがバインドされます。 -## ACP会話binding +## ACP会話バインディング -Matrixルーム、DM、既存のMatrixスレッドは、チャットの表面を変えずに永続的なACP workspaceにできます。 +Matrixルーム、DM、既存のMatrixスレッドは、チャット画面を変えることなく永続的なACPワークスペースにできます。 高速なオペレーターフロー: - 使い続けたいMatrix DM、ルーム、または既存スレッドの中で`/acp spawn codex --bind here`を実行します。 -- トップレベルのMatrix DMまたはルームでは、現在のDM/ルームがチャットの表面として維持され、以後のメッセージは生成されたACPセッションにルーティングされます。 -- 既存のMatrixスレッド内では、`--bind here`がその現在のスレッドをその場でbindします。 -- `/new`と`/reset`は、同じbinding済みACPセッションをその場でリセットします。 -- `/acp close`はACPセッションを閉じてbindingを削除します。 +- トップレベルのMatrix DMまたはルームでは、現在のDM/ルームがチャット画面のまま維持され、以後のメッセージは生成されたACPセッションにルーティングされます。 +- 既存のMatrixスレッド内では、`--bind here`がその現在のスレッドをその場でバインドします。 +- `/new`と`/reset`は、同じバインド済みACPセッションをその場でリセットします。 +- `/acp close`はACPセッションを閉じて、バインディングを削除します。 -注記: +注意: -- `--bind here`は子Matrixスレッドを作成しません。 -- `threadBindings.spawnAcpSessions`が必要なのは、OpenClawが子Matrixスレッドを作成またはbindする必要がある`/acp spawn --thread auto|here`の場合のみです。 +- `--bind here`は子のMatrixスレッドを作成しません。 +- `threadBindings.spawnAcpSessions`が必要になるのは、OpenClawが子のMatrixスレッドを作成またはバインドする必要がある`/acp spawn --thread auto|here`の場合のみです。 -### スレッドbinding設定 +### スレッドバインディング設定 -Matrixは`session.threadBindings`からグローバルデフォルトを継承し、チャネルごとのoverrideもサポートします: +Matrixは`session.threadBindings`からグローバルデフォルトを継承し、channelごとの上書きもサポートします。 - `threadBindings.enabled` - `threadBindings.idleHours` @@ -727,35 +729,35 @@ Matrixは`session.threadBindings`からグローバルデフォルトを継承 - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Matrixのスレッドbinding付きspawnフラグはオプトインです: +Matrixのスレッドバインドspawnフラグはオプトインです。 -- トップレベルの`/focus`で新しいMatrixスレッドを作成してbindできるようにするには、`threadBindings.spawnSubagentSessions: true`を設定します。 -- `/acp spawn --thread auto|here`でACPセッションをMatrixスレッドにbindできるようにするには、`threadBindings.spawnAcpSessions: true`を設定します。 +- トップレベルの`/focus`で新しいMatrixスレッドを作成してバインドできるようにするには、`threadBindings.spawnSubagentSessions: true`を設定します。 +- `/acp spawn --thread auto|here`でACPセッションをMatrixスレッドにバインドできるようにするには、`threadBindings.spawnAcpSessions: true`を設定します。 ## リアクション -Matrixは、送信リアクションアクション、受信リアクション通知、および受信ackリアクションをサポートします。 +Matrixは、送信リアクション操作、受信リアクション通知、受信ackリアクションをサポートします。 - 送信リアクションtoolingは`channels["matrix"].actions.reactions`で制御されます。 -- `react`は、特定のMatrixイベントにリアクションを追加します。 -- `reactions`は、特定のMatrixイベントに対する現在のリアクション要約を一覧表示します。 -- `emoji=""`は、そのイベント上のボットアカウント自身のリアクションを削除します。 -- `remove: true`は、ボットアカウントから指定した絵文字リアクションのみを削除します。 +- `react`は特定のMatrixイベントにリアクションを追加します。 +- `reactions`は特定のMatrixイベントの現在のリアクション要約を一覧表示します。 +- `emoji=""`は、そのイベントに対するbotアカウント自身のリアクションを削除します。 +- `remove: true`は、botアカウントから指定された絵文字リアクションのみを削除します。 -ackリアクションは標準のOpenClaw解決順序を使用します: +ackリアクションは、標準のOpenClaw解決順序を使用します。 - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- agent identity emoji fallback +- agent identityの絵文字フォールバック -ackリアクションスコープは次の順で解決されます: +ackリアクションスコープは次の順で解決されます。 - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -リアクション通知モードは次の順で解決されます: +リアクション通知モードは次の順で解決されます。 - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` @@ -763,30 +765,30 @@ ackリアクションスコープは次の順で解決されます: 動作: -- `reactionNotifications: "own"`は、ボット作成のMatrixメッセージを対象とする追加された`m.reaction`イベントを転送します。 -- `reactionNotifications: "off"`はリアクションシステムイベントを無効にします。 -- リアクション削除は、Matrixがそれらを独立した`m.reaction`削除ではなくredactionとして表現するため、システムイベントには合成されません。 +- `reactionNotifications: "own"`は、botが作成したMatrixメッセージを対象とする追加済み`m.reaction`イベントを転送します。 +- `reactionNotifications: "off"`は、リアクションシステムイベントを無効にします。 +- リアクション削除は、Matrixではそれらが独立した`m.reaction`削除ではなくredactionとして表現されるため、システムイベントには合成されません。 ## 履歴コンテキスト -- `channels.matrix.historyLimit`は、Matrixルームメッセージがagentをトリガーしたときに`InboundHistory`として含める最近のルームメッセージ数を制御します。`messages.groupChat.historyLimit`にフォールバックし、両方とも未設定の場合、実効デフォルトは`0`です。無効化するには`0`を設定してください。 -- Matrixルーム履歴はルーム専用です。DMは通常のセッション履歴を引き続き使用します。 -- Matrixルーム履歴は保留中のみです。OpenClawはまだ返信をトリガーしていないルームメッセージをバッファし、メンションや他のトリガーが来たときにそのウィンドウをスナップショットします。 -- 現在のトリガーメッセージは`InboundHistory`に含まれません。そのターンのメイン受信本文に残ります。 -- 同じMatrixイベントの再試行では、新しいルームメッセージへ前進してずれることなく、元の履歴スナップショットが再利用されます。 +- `channels.matrix.historyLimit`は、Matrixルームメッセージがagentをトリガーしたときに`InboundHistory`として含める最近のルームメッセージ数を制御します。`messages.groupChat.historyLimit`にフォールバックし、両方とも未設定なら実効デフォルトは`0`です。無効にするには`0`を設定します。 +- Matrixルーム履歴はルームのみです。DMは通常のセッション履歴を引き続き使用します。 +- Matrixルーム履歴はpending-onlyです。OpenClawは、まだ返信をトリガーしていないルームメッセージをバッファし、メンションやその他のトリガーが到着した時点でそのウィンドウをスナップショットします。 +- 現在のトリガーメッセージは`InboundHistory`には含まれず、そのターンのメインの受信本文に残ります。 +- 同じMatrixイベントの再試行では、新しいルームメッセージへずれていくのではなく、元の履歴スナップショットを再利用します。 ## コンテキスト可視性 -Matrixは、取得した返信テキスト、スレッドルート、保留中の履歴などの補助的なルームコンテキストに対する共有の`contextVisibility`制御をサポートします。 +Matrixは、取得した返信テキスト、スレッドルート、pending履歴などの補足ルームコンテキストに対して、共有の`contextVisibility`制御をサポートします。 -- `contextVisibility: "all"`がデフォルトです。補助コンテキストは受信したまま保持されます。 -- `contextVisibility: "allowlist"`は、アクティブなルーム/ユーザーallowlistチェックで許可された送信者に補助コンテキストを絞り込みます。 -- `contextVisibility: "allowlist_quote"`は`allowlist`と同様に動作しますが、1つの明示的な引用返信は保持します。 +- `contextVisibility: "all"`がデフォルトです。補足コンテキストは受信したまま保持されます。 +- `contextVisibility: "allowlist"`は、補足コンテキストを、アクティブなルーム/ユーザーallowlistチェックで許可された送信者に絞り込みます。 +- `contextVisibility: "allowlist_quote"`は`allowlist`と同様に動作しますが、明示的に引用された1件の返信は保持します。 -この設定は補助コンテキストの可視性に影響し、受信メッセージ自体が返信をトリガーできるかどうかには影響しません。 -トリガーの認可は引き続き`groupPolicy`、`groups`、`groupAllowFrom`、およびDM policy設定から行われます。 +この設定は補足コンテキストの可視性に影響するものであり、受信メッセージ自体が返信をトリガーできるかどうかには影響しません。 +トリガーの認可は引き続き`groupPolicy`、`groups`、`groupAllowFrom`、およびDMポリシー設定から行われます。 -## DMとルームポリシー +## DMとルームのポリシー ```json5 { @@ -818,13 +820,13 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -未承認のMatrixユーザーが承認前に繰り返しメッセージを送ってきた場合、OpenClawは同じ保留中のpairing codeを再利用し、新しいコードを発行する代わりに、短いクールダウン後に再度リマインダー返信を送ることがあります。 +未承認のMatrixユーザーが承認前にメッセージを送り続けた場合、OpenClawは同じ保留中のpairingコードを再利用し、新しいコードを発行する代わりに、短いクールダウン後に再度リマインダー返信を送ることがあります。 共有のDM pairingフローと保存レイアウトについては、[Pairing](/ja-JP/channels/pairing)を参照してください。 -## ダイレクトルーム修復 +## 直接ルーム修復 -ダイレクトメッセージ状態の同期が崩れると、OpenClawがライブDMではなく古い単独ルームを指す古い`m.direct`マッピングを保持してしまうことがあります。相手の現在のマッピングを確認するには、次を実行します: +ダイレクトメッセージ状態の同期が崩れると、OpenClawはライブのDMではなく古い1対1ルームを指す古い`m.direct`マッピングを持つことがあります。相手に対する現在のマッピングを確認するには、次を使用します。 ```bash openclaw matrix direct inspect --user-id @alice:example.org @@ -838,55 +840,55 @@ openclaw matrix direct repair --user-id @alice:example.org 修復フロー: -- `m.direct`にすでにマッピングされている厳密な1:1 DMを優先する -- それがない場合、そのユーザーとの現在参加中の厳密な1:1 DMにフォールバックする -- 健全なDMが存在しない場合は、新しいダイレクトルームを作成して`m.direct`を書き換える +- すでに`m.direct`にマッピングされている厳密な1:1 DMを優先します +- それがなければ、そのユーザーとの現在参加中の厳密な1:1 DMにフォールバックします +- 正常なDMが存在しない場合は、新しいダイレクトルームを作成して`m.direct`を書き換えます -修復フローは古いルームを自動削除しません。健全なDMを選び、新しいMatrix送信、検証通知、その他のダイレクトメッセージフローが再び正しいルームを対象にするよう、マッピングを更新するだけです。 +修復フローは古いルームを自動削除しません。正常なDMを選択してマッピングを更新するだけで、新しいMatrix送信、検証通知、その他のダイレクトメッセージフローが再び正しいルームを対象にするようになります。 ## Exec承認 -Matrixは、Matrixアカウントのネイティブ承認クライアントとして機能できます。ネイティブの -DM/チャネルルーティング設定は、引き続きexec approval configの下にあります: +Matrixは、Matrixアカウント用のネイティブ承認クライアントとして動作できます。ネイティブの +DM/channelルーティング設定は、引き続きexec承認設定の下にあります。 - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers`（任意。`channels.matrix.dm.allowFrom`にフォールバック） +- `channels.matrix.execApprovals.approvers`（オプション。`channels.matrix.dm.allowFrom`にフォールバック） - `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -承認者は`@owner:example.org`のようなMatrix user IDである必要があります。`enabled`が未設定または`"auto"`で、少なくとも1人の承認者を解決できる場合、Matrixはネイティブ承認を自動有効化します。Exec承認は最初に`execApprovals.approvers`を使用し、`channels.matrix.dm.allowFrom`にフォールバックできます。Plugin承認は`channels.matrix.dm.allowFrom`を通じて認可されます。Matrixをネイティブ承認クライアントとして明示的に無効化するには、`enabled: false`を設定してください。そうしない場合、承認要求は他の設定済み承認ルートまたは承認フォールバックポリシーにフォールバックします。 +承認者は`@owner:example.org`のようなMatrix user IDである必要があります。Matrixは、`enabled`が未設定または`"auto"`で、少なくとも1人の承認者を解決できる場合、自動的にネイティブ承認を有効にします。Exec承認はまず`execApprovals.approvers`を使用し、`channels.matrix.dm.allowFrom`にフォールバックできます。Plugin承認は`channels.matrix.dm.allowFrom`を通じて認可されます。Matrixをネイティブ承認クライアントとして明示的に無効にするには、`enabled: false`を設定してください。それ以外の場合、承認要求は他の設定済み承認ルートまたは承認フォールバックポリシーにフォールバックします。 -Matrixネイティブルーティングは両方の承認種別をサポートします: +Matrixネイティブルーティングは両方の承認種別をサポートします。 -- `channels.matrix.execApprovals.*`は、Matrix承認プロンプトのネイティブDM/チャネルfanoutモードを制御します。 -- Exec承認は、`execApprovals.approvers`または`channels.matrix.dm.allowFrom`からexec approver setを使用します。 -- Plugin承認は、`channels.matrix.dm.allowFrom`のMatrix DM allowlistを使用します。 +- `channels.matrix.execApprovals.*`は、Matrix承認プロンプトのネイティブDM/channelファンアウトモードを制御します。 +- Exec承認は`execApprovals.approvers`または`channels.matrix.dm.allowFrom`からexec承認者セットを使用します。 +- Plugin承認は`channels.matrix.dm.allowFrom`からMatrix DM allowlistを使用します。 - Matrixリアクションショートカットとメッセージ更新は、exec承認とPlugin承認の両方に適用されます。 配信ルール: -- `target: "dm"`は、承認プロンプトを承認者のDMに送信します -- `target: "channel"`は、プロンプトを発信元のMatrixルームまたはDMに送り返します -- `target: "both"`は、承認者のDMと発信元のMatrixルームまたはDMの両方に送信します +- `target: "dm"`は承認プロンプトを承認者DMへ送信します +- `target: "channel"`はプロンプトを元のMatrixルームまたはDMへ送り返します +- `target: "both"`は承認者DMと元のMatrixルームまたはDMの両方へ送信します -Matrix承認プロンプトは、主要な承認メッセージにリアクションショートカットを設定します: +Matrix承認プロンプトは、主要な承認メッセージにリアクションショートカットを設定します。 - `✅` = 1回だけ許可 - `❌` = 拒否 -- `♾️` = 実効exec policyでその決定が許可されている場合は常に許可 +- `♾️` = 実効execポリシーでその判断が許可されている場合、常に許可 -承認者はそのメッセージにリアクションするか、フォールバックのスラッシュコマンド`/approve allow-once`、`/approve allow-always`、または`/approve deny`を使用できます。 +承認者はそのメッセージにリアクションするか、フォールバックのスラッシュコマンド `/approve allow-once`、`/approve allow-always`、または`/approve deny`を使用できます。 -承認または拒否できるのは、解決済みの承認者だけです。Exec承認では、チャネル配信にコマンドテキストが含まれるため、`channel`または`both`は信頼されたルームでのみ有効にしてください。 +解決済みの承認者のみが承認または拒否できます。Exec承認では、channel配信にコマンドテキストが含まれるため、`channel`または`both`は信頼できるルームでのみ有効にしてください。 -アカウントごとのoverride: +アカウントごとの上書き: - `channels.matrix.accounts..execApprovals` 関連ドキュメント: [Exec approvals](/ja-JP/tools/exec-approvals) -## マルチアカウント +## 複数アカウント ```json5 { @@ -916,25 +918,25 @@ Matrix承認プロンプトは、主要な承認メッセージにリアクシ } ``` -トップレベルの`channels.matrix`の値は、アカウント側でoverrideされない限り、名前付きアカウントのデフォルトとして機能します。 -継承されたルームエントリは、`groups..account`で1つのMatrixアカウントにスコープできます。 -`account`のないエントリはすべてのMatrixアカウント間で共有されたままとなり、`account: "default"`を持つエントリは、デフォルトアカウントがトップレベルの`channels.matrix.*`に直接設定されている場合にも引き続き機能します。 -共有された部分的な認証デフォルトだけでは、それ自体で別個の暗黙のデフォルトアカウントは作成されません。OpenClawがトップレベルの`default`アカウントを合成するのは、そのデフォルトに新しい認証情報（`homeserver` + `accessToken`、または`homeserver` + `userId` + `password`）がある場合のみです。名前付きアカウントは、後でキャッシュ済み認証情報が認証要件を満たすなら、`homeserver` + `userId`から引き続き検出可能なままにできます。 -Matrixにすでにちょうど1つの名前付きアカウントがある場合、または`defaultAccount`が既存の名前付きアカウントキーを指している場合、単一アカウントからマルチアカウントへの修復/セットアップ昇格では、新しい`accounts.default`エントリを作成する代わりにそのアカウントが保持されます。昇格されたアカウントに移動するのはMatrix認証/bootstrapキーのみで、共有配信ポリシーキーはトップレベルに残ります。 -OpenClawに暗黙のルーティング、プローブ、CLI操作で1つの名前付きMatrixアカウントを優先させたい場合は、`defaultAccount`を設定してください。 -複数のMatrixアカウントが設定されていて、そのうち1つのアカウントIDが`default`である場合、`defaultAccount`が未設定でもOpenClawはそのアカウントを暗黙的に使用します。 +トップレベルの`channels.matrix`値は、アカウント側で上書きされない限り、名前付きアカウントのデフォルトとして機能します。 +継承されたルームエントリを1つのMatrixアカウントに限定するには、`groups..account`を使用できます。 +`account`なしのエントリはすべてのMatrixアカウントで共有されたままとなり、`account: "default"`が付いたエントリは、デフォルトアカウントがトップレベルの`channels.matrix.*`に直接設定されている場合でも引き続き機能します。 +共有認証デフォルトが部分的に存在するだけでは、それ自体で別個の暗黙のデフォルトアカウントは作成されません。OpenClawがトップレベルの`default`アカウントを合成するのは、そのデフォルトに新しい認証情報（`homeserver` + `accessToken`、または`homeserver` + `userId` + `password`）がある場合のみです。名前付きアカウントは、後からキャッシュされた認証情報が認証要件を満たす場合、`homeserver` + `userId`の段階でも引き続き検出可能なままです。 +Matrixにすでにちょうど1つの名前付きアカウントがある場合、または`defaultAccount`が既存の名前付きアカウントキーを指している場合、単一アカウントから複数アカウントへの修復/セットアップ昇格では、新しい`accounts.default`エントリを作成せず、そのアカウントが保持されます。その昇格済みアカウントに移動するのはMatrix認証/ブートストラップキーのみであり、共有の配信ポリシーキーはトップレベルに残ります。 +暗黙のルーティング、プローブ、CLI操作で1つの名前付きMatrixアカウントを優先させたい場合は、`defaultAccount`を設定してください。 +複数のMatrixアカウントが設定されていて、そのうちの1つのアカウントIDが`default`である場合、`defaultAccount`が未設定でもOpenClawはそのアカウントを暗黙的に使用します。 複数の名前付きアカウントを設定する場合は、暗黙のアカウント選択に依存するCLIコマンドのために`defaultAccount`を設定するか、`--account `を渡してください。 1つのコマンドだけでその暗黙選択を上書きしたい場合は、`openclaw matrix verify ...`と`openclaw matrix devices ...`に`--account `を渡してください。 -共有のマルチアカウントパターンについては、[Configuration reference](/ja-JP/gateway/configuration-reference#multi-account-all-channels)を参照してください。 +共有の複数アカウントパターンについては、[Configuration reference](/ja-JP/gateway/configuration-reference#multi-account-all-channels)を参照してください。 -## Private/LAN homeserver +## プライベート/LAN homeserver -デフォルトでは、OpenClawはSSRF保護のため、private/internal Matrix homeserverをブロックします。 -明示的にアカウントごとにオプトインした場合のみ許可されます。 +デフォルトでは、OpenClawはSSRF保護のため、プライベート/内部のMatrix homeserverをブロックします。アカウントごとに +明示的にオプトインしない限り接続できません。 -homeserverがlocalhost、LAN/Tailscale IP、または内部ホスト名で動作している場合は、そのMatrixアカウントで -`network.dangerouslyAllowPrivateNetwork`を有効にしてください: +homeserverがlocalhost、LAN/Tailscale IP、または内部ホスト名で動作している場合は、そのMatrixアカウントに対して +`network.dangerouslyAllowPrivateNetwork`を有効にしてください。 ```json5 { @@ -960,12 +962,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -このオプトインは、信頼されたprivate/internalターゲットのみを許可します。`http://matrix.example.org:8008`のような -公開クリアテキストhomeserverは引き続きブロックされます。可能な限り`https://`を推奨します。 +このオプトインは、信頼されたプライベート/内部ターゲットのみを許可します。たとえば +`http://matrix.example.org:8008`のような公開クリアテキストhomeserverは引き続きブロックされます。可能な限り`https://`を使用してください。 ## Matrixトラフィックのプロキシ -Matrixデプロイで明示的な送信HTTP(S)プロキシが必要な場合は、`channels.matrix.proxy`を設定してください: +Matrixデプロイで明示的な送信HTTP(S)プロキシが必要な場合は、`channels.matrix.proxy`を設定します。 ```json5 { @@ -979,85 +981,85 @@ Matrixデプロイで明示的な送信HTTP(S)プロキシが必要な場合は } ``` -名前付きアカウントは、`channels.matrix.accounts..proxy`でトップレベルのデフォルトをoverrideできます。 -OpenClawは、ランタイムのMatrixトラフィックとアカウントステータスのプローブの両方で同じプロキシ設定を使用します。 +名前付きアカウントは、トップレベルのデフォルトを`channels.matrix.accounts..proxy`で上書きできます。 +OpenClawは、ランタイムのMatrixトラフィックとアカウント状態プローブの両方で同じプロキシ設定を使用します。 ## ターゲット解決 -Matrixは、OpenClawがルームまたはユーザーのターゲットを求めるすべての場所で、次のターゲット形式を受け付けます: +Matrixは、OpenClawがルームまたはユーザーターゲットを求めるあらゆる箇所で、次のターゲット形式を受け付けます。 - ユーザー: `@user:server`、`user:@user:server`、または`matrix:user:@user:server` - ルーム: `!room:server`、`room:!room:server`、または`matrix:room:!room:server` - エイリアス: `#alias:server`、`channel:#alias:server`、または`matrix:channel:#alias:server` -ライブディレクトリ検索は、ログイン済みのMatrixアカウントを使用します: +ライブディレクトリ検索は、ログイン済みのMatrixアカウントを使用します。 -- ユーザー検索は、そのhomeserver上のMatrixユーザーディレクトリに問い合わせます。 -- ルーム検索は、明示的なルームIDとエイリアスをそのまま受け付け、その後そのアカウントの参加済みルーム名の検索にフォールバックします。 -- 参加済みルーム名検索はベストエフォートです。ルーム名をIDまたはエイリアスに解決できない場合、ランタイムのallowlist解決で無視されます。 +- ユーザー検索は、そのhomeserver上のMatrixユーザーディレクトリを問い合わせます。 +- ルーム検索は、明示的なルームIDとエイリアスをそのまま受け付け、その後そのアカウントで参加済みのルーム名検索にフォールバックします。 +- 参加済みルーム名検索はベストエフォートです。ルーム名をIDまたはエイリアスに解決できない場合、ランタイムallowlist解決では無視されます。 ## 設定リファレンス -- `enabled`: チャネルを有効または無効にします。 -- `name`: アカウントの任意ラベル。 -- `defaultAccount`: 複数のMatrixアカウントが設定されている場合の優先アカウントID。 +- `enabled`: channelを有効または無効にします。 +- `name`: アカウントのオプションラベル。 +- `defaultAccount`: 複数のMatrixアカウントが設定されているときの優先アカウントID。 - `homeserver`: homeserver URL。例: `https://matrix.example.org`。 -- `network.dangerouslyAllowPrivateNetwork`: このMatrixアカウントがprivate/internal homeserverに接続できるようにします。homeserverが`localhost`、LAN/Tailscale IP、または`matrix-synapse`のような内部ホストに解決される場合に有効にしてください。 -- `proxy`: Matrixトラフィック用の任意のHTTP(S)プロキシURL。名前付きアカウントは独自の`proxy`でトップレベルのデフォルトをoverrideできます。 +- `network.dangerouslyAllowPrivateNetwork`: このMatrixアカウントがプライベート/内部homeserverへ接続できるようにします。homeserverが`localhost`、LAN/Tailscale IP、または`matrix-synapse`のような内部ホストに解決される場合に有効化してください。 +- `proxy`: Matrixトラフィック用のオプションHTTP(S)プロキシURL。名前付きアカウントは独自の`proxy`でトップレベルデフォルトを上書きできます。 - `userId`: 完全なMatrix user ID。例: `@bot:example.org`。 -- `accessToken`: トークンベース認証用のaccess token。プレーンテキスト値とSecretRef値は、env/file/exec provider全体で`channels.matrix.accessToken`および`channels.matrix.accounts..accessToken`に対してサポートされます。[Secrets Management](/ja-JP/gateway/secrets)を参照してください。 -- `password`: パスワードベースログイン用のpassword。プレーンテキスト値とSecretRef値がサポートされます。 +- `accessToken`: トークンベース認証用のアクセストークン。プレーンテキスト値とSecretRef値は、env/file/execプロバイダー全体で`channels.matrix.accessToken`および`channels.matrix.accounts..accessToken`に対応しています。[Secrets Management](/ja-JP/gateway/secrets)を参照してください。 +- `password`: パスワードベースログイン用のパスワード。プレーンテキスト値とSecretRef値に対応しています。 - `deviceId`: 明示的なMatrix device ID。 - `deviceName`: パスワードログイン用のデバイス表示名。 -- `avatarUrl`: プロファイル同期および`profile set`更新用の保存済みself-avatar URL。 -- `initialSyncLimit`: 起動時sync中に取得されるイベントの最大数。 +- `avatarUrl`: プロファイル同期および`profile set`更新用に保存されるセルフアバターURL。 +- `initialSyncLimit`: 起動時sync中に取得するイベントの最大数。 - `encryption`: E2EEを有効にします。 -- `allowlistOnly`: `true`の場合、`open`ルームポリシーを`allowlist`に昇格し、`disabled`以外のすべてのアクティブなDM policy（`pairing`および`open`を含む）を`allowlist`に強制します。`disabled`ポリシーには影響しません。 +- `allowlistOnly`: `true`の場合、`open`ルームポリシーを`allowlist`に引き上げ、`disabled`以外のすべてのアクティブなDMポリシー（`pairing`と`open`を含む）を`allowlist`に強制します。`disabled`ポリシーには影響しません。 - `allowBots`: 他の設定済みOpenClaw Matrixアカウントからのメッセージを許可します（`true`または`"mentions"`）。 - `groupPolicy`: `open`、`allowlist`、または`disabled`。 -- `contextVisibility`: 補助的なルームコンテキストの可視性モード（`all`、`allowlist`、`allowlist_quote`）。 -- `groupAllowFrom`: ルームトラフィック用のallowlist user ID。エントリは完全なMatrix user IDにしてください。未解決の名前は実行時に無視されます。 -- `historyLimit`: グループ履歴コンテキストとして含めるルームメッセージの最大数。`messages.groupChat.historyLimit`にフォールバックし、両方とも未設定の場合、実効デフォルトは`0`です。無効化するには`0`を設定してください。 +- `contextVisibility`: 補足ルームコンテキストの可視性モード（`all`、`allowlist`、`allowlist_quote`）。 +- `groupAllowFrom`: ルームトラフィック用のuser ID allowlist。エントリは完全なMatrix user IDにしてください。未解決の名前はランタイムで無視されます。 +- `historyLimit`: グループ履歴コンテキストとして含めるルームメッセージの最大数。`messages.groupChat.historyLimit`にフォールバックし、両方とも未設定なら実効デフォルトは`0`です。無効にするには`0`を設定します。 - `replyToMode`: `off`、`first`、`all`、または`batched`。 -- `markdown`: 送信Matrixテキスト用の任意のMarkdownレンダリング設定。 -- `streaming`: `off`（デフォルト）、`"partial"`、`"quiet"`、`true`、または`false`。`"partial"`と`true`は、通常のMatrixテキストメッセージによるプレビュー先行の下書き更新を有効にします。`"quiet"`は、セルフホストのpush-ruleセットアップ向けに通知しないプレビューノーティスを使用します。`false`は`"off"`と同等です。 -- `blockStreaming`: `true`は、下書きプレビューのストリーミングが有効な間、完了したassistantブロックごとに個別の進捗メッセージを有効にします。 +- `markdown`: 送信Matrixテキスト用のオプションMarkdownレンダリング設定。 +- `streaming`: `off`（デフォルト）、`"partial"`、`"quiet"`、`true`、または`false`。`"partial"`と`true`は、通常のMatrixテキストメッセージによるプレビュー先行の下書き更新を有効にします。`"quiet"`は、セルフホストのプッシュルール構成向けに通知しないプレビューnoticeを使用します。`false`は`"off"`と同等です。 +- `blockStreaming`: `true`は、下書きプレビューストリーミングが有効なとき、完了したassistantブロック用の個別進行状況メッセージを有効にします。 - `threadReplies`: `off`、`inbound`、または`always`。 -- `threadBindings`: スレッドにbindingされたセッションルーティングとライフサイクルに対するチャネルごとのoverride。 +- `threadBindings`: スレッドにバインドされたセッションルーティングとライフサイクル用のchannelごとの上書き。 - `startupVerification`: 起動時の自動自己検証要求モード（`if-unverified`、`off`）。 -- `startupVerificationCooldownHours`: 起動時の自動検証要求を再試行する前のクールダウン時間。 -- `textChunkLimit`: 送信メッセージの文字数ベースのチャンクサイズ（`chunkMode`が`length`の場合に適用）。 -- `chunkMode`: `length`はメッセージを文字数で分割し、`newline`は行境界で分割します。 -- `responsePrefix`: このチャネルのすべての送信返信の前に付加される任意の文字列。 -- `ackReaction`: このチャネル/アカウント用の任意のackリアクションoverride。 -- `ackReactionScope`: 任意のackリアクションスコープoverride（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 +- `startupVerificationCooldownHours`: 起動時自動検証要求を再試行するまでのクールダウン。 +- `textChunkLimit`: 送信メッセージの文字数チャンクサイズ（`chunkMode`が`length`のときに適用）。 +- `chunkMode`: `length`は文字数でメッセージを分割し、`newline`は改行境界で分割します。 +- `responsePrefix`: このchannelのすべての送信返信の先頭に付加されるオプション文字列。 +- `ackReaction`: このchannel/アカウント用のオプションackリアクション上書き。 +- `ackReactionScope`: オプションackリアクションスコープ上書き（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 - `reactionNotifications`: 受信リアクション通知モード（`own`、`off`）。 -- `mediaMaxMb`: 送信と受信メディア処理におけるメディアサイズ上限（MB）。 -- `autoJoin`: 招待への自動参加ポリシー（`always`、`allowlist`、`off`）。デフォルト: `off`。DM形式の招待を含むすべてのMatrix招待に適用されます。 +- `mediaMaxMb`: 送信送信および受信メディア処理用のメディアサイズ上限（MB）。 +- `autoJoin`: 招待自動参加ポリシー（`always`、`allowlist`、`off`）。デフォルト: `off`。DM形式の招待を含むすべてのMatrix招待に適用されます。 - `autoJoinAllowlist`: `autoJoin`が`allowlist`のときに許可されるルーム/エイリアス。エイリアスエントリは招待処理中にルームIDへ解決されます。OpenClawは、招待されたルームが主張するエイリアス状態を信頼しません。 -- `dm`: DM policyブロック（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 -- `dm.policy`: OpenClawがルームに参加し、それをDMとして分類した後のDMアクセスを制御します。招待に自動参加するかどうかは変更しません。 -- `dm.allowFrom`: ライブディレクトリ検索で解決済みでない限り、エントリは完全なMatrix user IDにしてください。 -- `dm.sessionScope`: `per-user`（デフォルト）または`per-room`。相手が同じでも各Matrix DMルームに別々のコンテキストを持たせたい場合は`per-room`を使用してください。 -- `dm.threadReplies`: DM専用のスレッドポリシーoverride（`off`、`inbound`、`always`）。DMにおける返信配置とセッション分離の両方について、トップレベルの`threadReplies`設定をoverrideします。 -- `execApprovals`: Matrixネイティブのexec承認配信（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 -- `execApprovals.approvers`: exec要求を承認できるMatrix user ID。`dm.allowFrom`がすでに承認者を特定している場合は任意です。 +- `dm`: DMポリシーブロック（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 +- `dm.policy`: OpenClawがルームに参加し、それをDMと分類した後のDMアクセスを制御します。招待が自動参加されるかどうかは変更しません。 +- `dm.allowFrom`: すでにライブディレクトリ検索で解決済みでない限り、エントリは完全なMatrix user IDにしてください。 +- `dm.sessionScope`: `per-user`（デフォルト）または`per-room`。相手が同じでも各Matrix DMルームで別々のコンテキストを維持したい場合は`per-room`を使用します。 +- `dm.threadReplies`: DM専用のスレッドポリシー上書き（`off`、`inbound`、`always`）。DMにおける返信配置とセッション分離の両方で、トップレベルの`threadReplies`設定を上書きします。 +- `execApprovals`: Matrixネイティブexec承認配信（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 +- `execApprovals.approvers`: execリクエストを承認できるMatrix user ID。`dm.allowFrom`ですでに承認者が識別されている場合は省略可能です。 - `execApprovals.target`: `dm | channel | both`（デフォルト: `dm`）。 -- `accounts`: 名前付きのアカウントごとのoverride。トップレベルの`channels.matrix`値はこれらのエントリのデフォルトとして機能します。 -- `groups`: ルームごとのポリシーマップ。ルームIDまたはエイリアスを推奨します。未解決のルーム名は実行時に無視されます。セッション/グループIDには、解決後の安定したルームIDが使用されます。 -- `groups..account`: マルチアカウント構成で、1つの継承ルームエントリを特定のMatrixアカウントに限定します。 -- `groups..allowBots`: 設定済みボット送信者に対するルームレベルoverride（`true`または`"mentions"`）。 +- `accounts`: 名前付きのアカウントごとの上書き。トップレベルの`channels.matrix`値はこれらのエントリのデフォルトとして機能します。 +- `groups`: ルームごとのポリシーマップ。ルームIDまたはエイリアスを推奨します。未解決のルーム名はランタイムで無視されます。解決後のセッション/グループIDには安定したルームIDが使用されます。 +- `groups..account`: 複数アカウント構成で、1つの継承ルームエントリを特定のMatrixアカウントに限定します。 +- `groups..allowBots`: 設定済みbot送信者に対するルームレベル上書き（`true`または`"mentions"`）。 - `groups..users`: ルームごとの送信者allowlist。 -- `groups..tools`: ルームごとのtool許可/拒否override。 -- `groups..autoReply`: ルームレベルのメンション制御override。`true`はそのルームのメンション必須を無効にし、`false`は再び有効にします。 -- `groups..skills`: 任意のルームレベルskill filter。 -- `groups..systemPrompt`: 任意のルームレベルsystem promptスニペット。 +- `groups..tools`: ルームごとのtool許可/拒否上書き。 +- `groups..autoReply`: ルームレベルのメンション制御上書き。`true`はそのルームのメンション必須を無効化し、`false`は再び有効化します。 +- `groups..skills`: オプションのルームレベルSkillsフィルター。 +- `groups..systemPrompt`: オプションのルームレベルsystem promptスニペット。 - `rooms`: `groups`のレガシーエイリアス。 - `actions`: アクションごとのtool制御（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 ## 関連 -- [Channels Overview](/ja-JP/channels) — サポートされているすべてのチャネル +- [Channels Overview](/ja-JP/channels) — サポートされているすべてのchannel - [Pairing](/ja-JP/channels/pairing) — DM認証とpairingフロー - [Groups](/ja-JP/channels/groups) — グループチャットの動作とメンション制御 - [Channel Routing](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング diff --git a/docs/ja-JP/concepts/system-prompt.md b/docs/ja-JP/concepts/system-prompt.md index 0c27a4467..3c0580ad0 100644 --- a/docs/ja-JP/concepts/system-prompt.md +++ b/docs/ja-JP/concepts/system-prompt.md @@ -1,79 +1,80 @@ --- read_when: - - システムプロンプトのテキスト、ツール一覧、または時刻 / ハートビートのセクションの編集 + - システムプロンプトのテキスト、ツール一覧、または時刻／Heartbeat セクションの編集 - ワークスペースのブートストラップや Skills の注入動作の変更 -summary: OpenClaw のシステムプロンプトに含まれる内容と、その組み立て方法 +summary: OpenClawのシステムプロンプトに何が含まれているか、およびそれがどのように組み立てられるか title: システムプロンプト x-i18n: - generated_at: "2026-04-12T04:43:45Z" + generated_at: "2026-04-15T19:41:42Z" model: gpt-5.4 provider: openai - source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f + source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 source_path: concepts/system-prompt.md workflow: 15 --- # システムプロンプト -OpenClaw は、エージェントの実行ごとにカスタムのシステムプロンプトを構築します。このプロンプトは **OpenClaw が管理** しており、pi-coding-agent のデフォルトプロンプトは使用しません。 +OpenClaw は、エージェントの各実行ごとにカスタムのシステムプロンプトを構築します。このプロンプトは **OpenClaw が所有** しており、pi-coding-agent のデフォルトプロンプトは使用しません。 このプロンプトは OpenClaw によって組み立てられ、各エージェント実行に注入されます。 -プロバイダープラグインは、OpenClaw 管理の完全なプロンプトを置き換えることなく、キャッシュ対応のプロンプトガイダンスを提供できます。プロバイダーランタイムでは、次のことが可能です。 +プロバイダ Plugin は、完全な OpenClaw 所有のプロンプトを置き換えることなく、キャッシュを意識したプロンプトガイダンスを提供できます。プロバイダランタイムでは次のことが可能です。 - 少数の名前付きコアセクション（`interaction_style`、`tool_call_style`、`execution_bias`）を置き換える -- プロンプトキャッシュ境界の上に**安定したプレフィックス**を注入する -- プロンプトキャッシュ境界の下に**動的なサフィックス**を注入する +- プロンプトキャッシュ境界の上に **stable prefix** を注入する +- プロンプトキャッシュ境界の下に **dynamic suffix** を注入する -モデルファミリー固有のチューニングには、プロバイダー管理の追加を使用してください。従来の -`before_prompt_build` によるプロンプト変更は、互換性のため、または本当にグローバルなプロンプト変更にのみ使い、通常のプロバイダー挙動には使わないでください。 +モデルファミリー固有のチューニングには、プロバイダ所有の寄与を使ってください。従来の +`before_prompt_build` によるプロンプト変更は、互換性維持や本当にグローバルなプロンプト変更のために残し、通常のプロバイダ動作には使わないでください。 ## 構造 このプロンプトは意図的にコンパクトで、固定セクションを使用します。 -- **Tooling**: structured-tool の信頼できる情報源であることのリマインダーと、ランタイムのツール使用ガイダンス。 -- **Safety**: 権力志向の挙動や監督の回避を避けるための短いガードレールのリマインダー。 -- **Skills**（利用可能な場合）: 必要に応じて skill の指示を読み込む方法をモデルに伝えます。 -- **OpenClaw Self-Update**: `config.schema.lookup` で安全に設定を調べる方法、`config.patch` で設定にパッチを当てる方法、`config.apply` で完全な設定を置き換える方法、および明示的なユーザー要求がある場合にのみ `update.run` を実行する方法。owner 限定の `gateway` ツールは、`tools.exec.ask` / `tools.exec.security` の書き換えも拒否します。これには、それらの保護された exec パスに正規化される旧来の `tools.bash.*` エイリアスも含まれます。 +- **Tooling**: 構造化ツールの source-of-truth リマインダーと、ランタイムのツール使用ガイダンス。 +- **Safety**: 権力追求的な振る舞いや監督の回避を避けるための短いガードレールリマインダー。 +- **Skills**（利用可能な場合）: 必要に応じてスキル指示を読み込む方法をモデルに伝えます。 +- **OpenClaw Self-Update**: `config.schema.lookup` を使った安全な設定確認方法、`config.patch` による設定パッチ、`config.apply` による完全設定置換、そして明示的なユーザー要求時にのみ `update.run` を実行する方法。owner-only の `gateway` ツールは、保護された exec パスに正規化される従来の `tools.bash.*` エイリアスを含め、`tools.exec.ask` / `tools.exec.security` の書き換えも拒否します。 - **Workspace**: 作業ディレクトリ（`agents.defaults.workspace`）。 -- **Documentation**: OpenClaw ドキュメントのローカルパス（リポジトリまたは npm パッケージ）と、それを読むべきタイミング。 -- **Workspace Files (injected)**: ブートストラップファイルが以下に含まれていることを示します。 -- **Sandbox**（有効な場合）: サンドボックス化されたランタイム、サンドボックスパス、および権限昇格付き exec が利用可能かどうかを示します。 -- **Current Date & Time**: ユーザーのローカル時刻、タイムゾーン、時刻形式。 -- **Reply Tags**: 対応プロバイダー向けのオプションの返信タグ構文。 -- **Heartbeats**: デフォルトエージェントで heartbeat が有効な場合の、heartbeat プロンプトと ack の挙動。 -- **Runtime**: ホスト、OS、node、モデル、リポジトリルート（検出された場合）、thinking level（1 行）。 -- **Reasoning**: 現在の可視性レベルと `/reasoning` 切り替えのヒント。 +- **Documentation**: OpenClaw ドキュメントへのローカルパス（リポジトリまたは npm パッケージ）と、それを読むべきタイミング。 +- **Workspace Files (injected)**: ブートストラップファイルが以下に含まれることを示します。 +- **Sandbox**（有効な場合）: サンドボックス化されたランタイム、サンドボックスのパス、昇格 exec が利用可能かどうかを示します。 +- **Current Date & Time**: ユーザーローカル時刻、タイムゾーン、時刻形式。 +- **Reply Tags**: 対応プロバイダ向けの任意の返信タグ構文。 +- **Heartbeats**: デフォルトエージェントで Heartbeat が有効な場合の Heartbeat プロンプトと ack 動作。 +- **Runtime**: ホスト、OS、node、モデル、repo ルート（検出された場合）、thinking レベル（1 行）。 +- **Reasoning**: 現在の可視性レベルと `/reasoning` 切り替えヒント。 -Tooling セクションには、長時間実行される作業に対するランタイムガイダンスも含まれます。 +Tooling セクションには、長時間実行される作業向けのランタイムガイダンスも含まれます。 -- 将来のフォローアップ（`check back later`、リマインダー、定期作業）には `cron` を使用し、`exec` の sleep ループ、`yieldMs` の遅延トリック、繰り返しの `process` ポーリングは使わない -- 今すぐ開始してバックグラウンドで継続実行されるコマンドにのみ `exec` / `process` を使用する -- 自動完了 wake が有効な場合は、コマンドを一度だけ開始し、出力が出たときや失敗したときの push ベースの wake 経路に任せる -- 実行中コマンドのログ、状態、入力、介入を確認する必要がある場合は `process` を使用する -- タスクがより大きい場合は `sessions_spawn` を優先する。サブエージェントの完了は push ベースで、要求元に自動通知される -- 完了を待つためだけに `subagents list` / `sessions_list` をループでポーリングしない +- `exec` の sleep ループ、`yieldMs` の遅延トリック、`process` の繰り返しポーリングではなく、将来のフォローアップ（`check back later`、リマインダー、定期作業）には cron を使う +- `exec` / `process` は、今すぐ開始してバックグラウンドで継続実行されるコマンドにのみ使う +- 自動完了ウェイクが有効な場合は、コマンドを一度だけ開始し、出力または失敗時の push ベースのウェイク経路に依存する +- 実行中コマンドを確認する必要があるときのログ、状態、入力、介入には `process` を使う +- タスクがより大きい場合は、`sessions_spawn` を優先する。サブエージェントの完了は push ベースで、依頼元へ自動通知される +- 完了待ちのためだけに `subagents list` / `sessions_list` をループでポーリングしない -実験的な `update_plan` ツールが有効な場合、Tooling では、これを自明でない複数ステップの作業にのみ使用し、`in_progress` のステップをちょうど 1 つに保ち、更新のたびに計画全体を繰り返さないようモデルに伝えます。 +実験的な `update_plan` ツールが有効な場合、Tooling では、それを自明でない複数ステップ作業にのみ使い、`in_progress` ステップをちょうど 1 つ維持し、各更新後に計画全体を繰り返さないようモデルに伝えます。 -システムプロンプト内の Safety ガードレールは助言的なものです。これらはモデルの挙動を導きますが、ポリシーを強制するものではありません。強制にはツールポリシー、exec 承認、サンドボックス、チャンネル allowlist を使用してください。オペレーターは設計上これらを無効化できます。 +システムプロンプト内の Safety ガードレールは助言的なものです。モデルの動作を導きますが、ポリシーを強制するものではありません。強制には、ツールポリシー、exec 承認、サンドボックス化、チャネル許可リストを使ってください。運用者は設計上これらを無効化できます。 -ネイティブの承認カードやボタンがあるチャンネルでは、ランタイムプロンプトは、まずそのネイティブ承認 UI に依存するようエージェントに伝えます。手動の `/approve` コマンドを含めるのは、ツール結果がチャット承認を利用できないと示している場合、または手動承認が唯一の経路である場合だけです。 +ネイティブの承認カード／ボタンがあるチャネルでは、ランタイムプロンプトはエージェントに対して、まずそのネイティブ承認 UI に依存するよう伝えます。手動の +`/approve` コマンドを含めるのは、ツール結果がチャット承認を利用不可と示した場合、または手動承認のみが唯一の経路である場合だけです。 ## プロンプトモード -OpenClaw は、サブエージェント向けにより小さいシステムプロンプトをレンダリングできます。ランタイムは各実行に `promptMode` を設定します（ユーザー向けの設定ではありません）。 +OpenClaw はサブエージェント向けにより小さいシステムプロンプトをレンダリングできます。ランタイムは各実行に `promptMode` を設定します（ユーザー向け設定ではありません）。 -- `full`（デフォルト）: 上記のすべてのセクションを含みます。 -- `minimal`: サブエージェントに使用されます。**Skills**、**Memory Recall**、**OpenClaw Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、**Messaging**、**Silent Replies**、**Heartbeats** を省略します。Tooling、**Safety**、Workspace、Sandbox、Current Date & Time（既知の場合）、Runtime、および注入されたコンテキストは引き続き利用可能です。 -- `none`: ベースとなる識別行のみを返します。 +- `full`（デフォルト）: 上記の全セクションを含みます。 +- `minimal`: サブエージェントで使われ、**Skills**、**Memory Recall**、**OpenClaw Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、**Messaging**、**Silent Replies**、**Heartbeats** を省略します。Tooling、**Safety**、Workspace、Sandbox、Current Date & Time（既知の場合）、Runtime、および注入コンテキストは引き続き利用可能です。 +- `none`: ベースの識別 1 行のみを返します。 `promptMode=minimal` の場合、追加で注入されるプロンプトは **Group Chat Context** ではなく **Subagent Context** とラベル付けされます。 ## ワークスペースのブートストラップ注入 -ブートストラップファイルは切り詰められたうえで **Project Context** の下に追加されるため、モデルは明示的に読まなくても識別情報とプロファイルコンテキストを把握できます。 +ブートストラップファイルはトリミングされ、**Project Context** の下に追加されます。これにより、モデルは明示的に読み取らなくても識別情報やプロファイルコンテキストを把握できます。 - `AGENTS.md` - `SOUL.md` @@ -81,47 +82,49 @@ OpenClaw は、サブエージェント向けにより小さいシステムプ - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md`（新規ワークスペースでのみ） -- `MEMORY.md` がある場合はそれを、ない場合は小文字のフォールバックとして `memory.md` +- `BOOTSTRAP.md`（新規ワークスペースのみ） +- `MEMORY.md` が存在する場合はそれを、存在しない場合は小文字のフォールバックとして `memory.md` -これらのファイルはすべて、**ファイルごとのゲートが適用される場合を除き**、毎ターン **コンテキストウィンドウに注入** されます。`HEARTBEAT.md` は、通常の実行では、デフォルトエージェントで heartbeat が無効な場合、または -`agents.defaults.heartbeat.includeSystemPromptSection` が false の場合に省略されます。注入されるファイルは簡潔に保ってください。特に `MEMORY.md` は時間とともに大きくなり、予想外にコンテキスト使用量が増えたり、compaction がより頻繁に発生したりする可能性があります。 +これらのファイルはすべて、**ファイル固有のゲートが適用されない限り**、各ターンで **コンテキストウィンドウに注入** されます。`HEARTBEAT.md` は、通常実行では、デフォルトエージェントで Heartbeat が無効な場合、または +`agents.defaults.heartbeat.includeSystemPromptSection` が false の場合に省略されます。注入ファイルは簡潔に保ってください。特に `MEMORY.md` は時間とともに大きくなりやすく、予想外にコンテキスト使用量が増えたり、Compaction がより頻繁に発生したりする原因になります。 -> **注:** `memory/*.md` の日次ファイルは、通常のブートストラップ Project Context の一部**ではありません**。通常のターンでは、これらは `memory_search` および `memory_get` ツールを通じて必要時にアクセスされるため、モデルが明示的に読むまでコンテキストウィンドウを消費しません。例外は素の `/new` および `/reset` ターンで、この最初のターンに限り、ランタイムが最近の日次メモリをワンショットの起動コンテキストブロックとして前置できる場合があります。 +> **注:** `memory/*.md` の日次ファイルは、通常のブートストラップ Project Context の一部では **ありません**。通常ターンでは、これらは +> `memory_search` と `memory_get` ツールを通じて必要時にアクセスされるため、モデルが明示的にそれらを読まない限りコンテキストウィンドウを消費しません。例外は素の `/new` および `/reset` ターンです。この最初のターンでは、ランタイムが最近の日次メモリを 1 回限りの起動コンテキストブロックとして先頭に追加することがあります。 大きなファイルはマーカー付きで切り詰められます。ファイルごとの最大サイズは -`agents.defaults.bootstrapMaxChars`（デフォルト: 20000）で制御されます。ファイル全体にまたがる注入済みブートストラップ内容の総量は -`agents.defaults.bootstrapTotalMaxChars`（デフォルト: 150000）で上限が設定されます。欠落しているファイルには短い欠落ファイルマーカーが注入されます。切り詰めが発生した場合、OpenClaw は Project Context に警告ブロックを注入できます。これは -`agents.defaults.bootstrapPromptTruncationWarning`（`off`、`once`、`always`；デフォルト: `once`）で制御します。 +`agents.defaults.bootstrapMaxChars`（デフォルト: 20000）で制御されます。ファイル横断で注入されるブートストラップコンテンツ総量は +`agents.defaults.bootstrapTotalMaxChars`（デフォルト: 150000）で上限が設けられています。見つからないファイルは短い missing-file マーカーを注入します。切り詰めが発生した場合、OpenClaw は Project Context に警告ブロックを注入できます。これは +`agents.defaults.bootstrapPromptTruncationWarning`（`off`、`once`、`always`； +デフォルト: `once`）で制御します。 -サブエージェントセッションでは `AGENTS.md` と `TOOLS.md` のみが注入されます（サブエージェントのコンテキストを小さく保つため、他のブートストラップファイルは除外されます）。 +サブエージェントセッションでは `AGENTS.md` と `TOOLS.md` のみが注入されます（サブエージェントコンテキストを小さく保つため、他のブートストラップファイルは除外されます）。 -内部フックは `agent:bootstrap` を介してこのステップを横取りし、注入されるブートストラップファイルを変更または置き換えできます（たとえば `SOUL.md` を別のペルソナに差し替えるなど）。 +内部フックは `agent:bootstrap` を通じてこのステップを横取りし、注入されるブートストラップファイルを変更または置換できます（たとえば `SOUL.md` を別のペルソナに差し替えるなど）。 -エージェントの口調をより汎用的でなくしたい場合は、まず +エージェントの話し方をより generic でなくしたい場合は、まず [SOUL.md Personality Guide](/ja-JP/concepts/soul) から始めてください。 -各注入ファイルがどれだけ寄与しているか（生データと注入後、切り詰め、さらにツールスキーマのオーバーヘッド）を確認するには、`/context list` または `/context detail` を使用してください。[Context](/ja-JP/concepts/context) を参照してください。 +各注入ファイルの寄与量（raw と injected、切り詰め、さらにツールスキーマのオーバーヘッド）を確認するには、`/context list` または `/context detail` を使ってください。[Context](/ja-JP/concepts/context) を参照してください。 -## 時刻の扱い +## 時刻処理 -システムプロンプトには、ユーザーのタイムゾーンが既知の場合、専用の **Current Date & Time** セクションが含まれます。プロンプトキャッシュを安定させるため、ここには現在 **タイムゾーン** のみが含まれます（動的な時計や時刻形式は含みません）。 +ユーザーのタイムゾーンがわかっている場合、システムプロンプトには専用の **Current Date & Time** セクションが含まれます。プロンプトキャッシュを安定させるため、現在は **タイムゾーン** のみを含みます（動的な時計や時刻形式は含みません）。 -エージェントが現在時刻を必要とする場合は `session_status` を使用してください。ステータスカードにはタイムスタンプ行が含まれます。同じツールでは、セッションごとのモデル上書きも任意で設定できます（`model=default` でクリアされます）。 +エージェントが現在時刻を必要とする場合は `session_status` を使ってください。ステータスカードにはタイムスタンプ行が含まれます。同じツールは、セッションごとのモデル上書きも任意で設定できます（`model=default` でクリアされます）。 -設定は次で行います。 +設定項目: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat`（`auto` | `12` | `24`） -完全な挙動の詳細は [Date & Time](/ja-JP/date-time) を参照してください。 +完全な動作の詳細は [Date & Time](/ja-JP/date-time) を参照してください。 ## Skills -対象となる skill が存在する場合、OpenClaw は **available skills list** のコンパクト版（`formatSkillsForPrompt`）を注入し、各 skill の **ファイルパス** を含めます。プロンプトは、列挙された場所（ワークスペース、管理対象、または同梱）にある SKILL.md を読み込むために `read` を使うようモデルに指示します。対象 skill がない場合、Skills セクションは省略されます。 +条件を満たすスキルが存在する場合、OpenClaw は **利用可能なスキル一覧** をコンパクトに注入します（`formatSkillsForPrompt`）。これには各スキルの **ファイルパス** が含まれます。プロンプトは、列挙された場所（ワークスペース、managed、または bundled）にある SKILL.md を `read` で読み込むようモデルに指示します。条件を満たすスキルがない場合、Skills セクションは省略されます。 -対象判定には、skill メタデータのゲート、ランタイム環境 / 設定チェック、および `agents.defaults.skills` または -`agents.list[].skills` が設定されている場合の有効なエージェント skill allowlist が含まれます。 +適格性には、スキルメタデータのゲート、ランタイム環境／設定チェック、そして `agents.defaults.skills` または +`agents.list[].skills` が設定されている場合の有効なエージェントスキル許可リストが含まれます。 ``` @@ -133,8 +136,20 @@ OpenClaw は、サブエージェント向けにより小さいシステムプ ``` -これにより、ベースプロンプトを小さく保ちながら、必要な skill だけを使えるようにしています。 +これにより、ベースプロンプトを小さく保ちながら、対象を絞ったスキル利用を可能にします。 + +スキル一覧の予算はスキルサブシステムが管理します。 + +- グローバルデフォルト: `skills.limits.maxSkillsPromptChars` +- エージェントごとの上書き: `agents.list[].skillsLimits.maxSkillsPromptChars` + +一般的な境界付きランタイム抜粋は別のサーフェスを使います。 + +- `agents.defaults.contextLimits.*` +- `agents.list[].contextLimits.*` + +この分離により、スキルのサイズ設定を、`memory_get`、ライブツール結果、Compaction 後の AGENTS.md リフレッシュなどのランタイム読み取り／注入サイズから分けて扱えます。 ## Documentation -利用可能な場合、システムプロンプトには **Documentation** セクションが含まれ、OpenClaw ドキュメントディレクトリのローカルパス（リポジトリ内の `docs/` または npm パッケージに同梱されたドキュメント）を示します。また、公開ミラー、ソースリポジトリ、コミュニティ Discord、および Skills を見つけるための ClawHub（[https://clawhub.ai](https://clawhub.ai)）にも触れます。プロンプトは、OpenClaw の挙動、コマンド、設定、またはアーキテクチャについては、まずローカルドキュメントを参照し、可能であれば自分で `openclaw status` を実行するようモデルに指示します（アクセス権がない場合にのみユーザーに尋ねます）。 +利用可能な場合、システムプロンプトには **Documentation** セクションが含まれ、ローカルの OpenClaw ドキュメントディレクトリ（リポジトリワークスペース内の `docs/` またはバンドルされた npm パッケージのドキュメント）を指し示します。さらに、公開ミラー、ソースリポジトリ、コミュニティ Discord、そしてスキル発見用の ClawHub（[https://clawhub.ai](https://clawhub.ai)）も記載されます。プロンプトは、OpenClaw の動作、コマンド、設定、またはアーキテクチャについては、まずローカルドキュメントを参照し、可能な場合は `openclaw status` を自分で実行するようモデルに指示します（アクセスできない場合にのみユーザーに尋ねます）。 diff --git a/docs/ja-JP/gateway/configuration-reference.md b/docs/ja-JP/gateway/configuration-reference.md index 47d732ec6..c8895ee2c 100644 --- a/docs/ja-JP/gateway/configuration-reference.md +++ b/docs/ja-JP/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - 正確なフィールドレベルの設定セマンティクスまたはデフォルト値が必要です - - channel、model、gateway、またはtoolの設定ブロックを検証しています -summary: core OpenClaw のキー、デフォルト値、および各サブシステム専用リファレンスへのリンクのためのGateway設定リファレンス + - channel、model、gateway、または tool の設定ブロックを検証しています +summary: コア OpenClaw のキー、デフォルト値、および各サブシステム専用リファレンスへのリンクのための Gateway 設定リファレンス title: 設定リファレンス x-i18n: - generated_at: "2026-04-15T14:40:37Z" + generated_at: "2026-04-15T19:41:39Z" model: gpt-5.4 provider: openai - source_hash: 7a4da3b41d0304389bd6359aac1185c231e529781b607656ab352f8a8104bdba + source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,21 +17,21 @@ x-i18n: `~/.openclaw/openclaw.json` のコア設定リファレンスです。タスク指向の概要については、[Configuration](/ja-JP/gateway/configuration) を参照してください。 -このページでは、主要な OpenClaw の設定サーフェスを扱い、サブシステムに独自のより詳細なリファレンスがある場合はそのリンクを示します。このページでは、すべての channel/plugin 所有のコマンドカタログや、メモリ/QMD の詳細なすべてのノブを 1 ページにインライン展開することは**意図していません**。 +このページでは、主要な OpenClaw の設定サーフェスを扱い、サブシステムごとにより詳細な専用リファレンスがある場合はそちらへリンクします。このページでは、すべての channel/plugin 所有のコマンドカタログや、メモリ/QMD の詳細なノブを 1 ページにすべてインライン展開することは**意図していません**。 -コード上の正: +コード上の真実: -- `openclaw config schema` は、検証と Control UI に使用される現在の JSON Schema を出力します。利用可能な場合は、bundled/plugin/channel のメタデータがマージされます -- `config.schema.lookup` は、ドリルダウン用ツール向けに、1 つのパススコープのスキーマノードを返します +- `openclaw config schema` は、検証と Control UI に使われるライブ JSON Schema を出力し、利用可能な場合は bundled/plugin/channel のメタデータもマージされます +- `config.schema.lookup` は、ドリルダウン用ツールのために、1 つのパスにスコープされたスキーマノードを返します - `pnpm config:docs:check` / `pnpm config:docs:gen` は、設定ドキュメントのベースラインハッシュを現在のスキーマサーフェスに対して検証します 専用の詳細リファレンス: -- `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`、および `plugins.entries.memory-core.config.dreaming` 配下の dreaming 設定については [Memory configuration reference](/ja-JP/reference/memory-config) -- 現在の組み込み + bundled コマンドカタログについては [Slash Commands](/ja-JP/tools/slash-commands) +- `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`、および `plugins.entries.memory-core.config.dreaming` 配下の dreaming 設定については [メモリ設定リファレンス](/ja-JP/reference/memory-config) +- 現在の組み込み + bundled コマンドカタログについては [スラッシュコマンド](/ja-JP/tools/slash-commands) - channel 固有のコマンドサーフェスについては各 channel/plugin ページ -設定形式は **JSON5** です（コメント + 末尾カンマを許可）。すべてのフィールドは省略可能です — OpenClaw は省略時に安全なデフォルトを使用します。 +設定形式は **JSON5** です（コメントと末尾カンマを許可）。すべてのフィールドは省略可能です。省略された場合、OpenClaw は安全なデフォルト値を使用します。 --- @@ -39,32 +39,32 @@ x-i18n: 各 channel は、その設定セクションが存在すると自動的に起動します（`enabled: false` の場合を除く）。 -### DM とグループのアクセス +### DM とグループアクセス すべての channel は DM ポリシーとグループポリシーをサポートします: -| DM ポリシー | 動作 | -| -------------------- | -------------------------------------------------------------- | -| `pairing` (デフォルト) | 不明な送信者には 1 回限りのペアリングコードが送られ、owner の承認が必要 | -| `allowlist` | `allowFrom`（またはペア済み allow ストア）内の送信者のみ | +| DM ポリシー | 動作 | +| -------------------- | --------------------------------------------------------------- | +| `pairing` (デフォルト) | 未知の送信者には 1 回限りのペアリングコードが送られ、owner の承認が必要 | +| `allowlist` | `allowFrom` 内の送信者のみ（またはペア済みの許可ストア） | | `open` | すべての受信 DM を許可（`allowFrom: ["*"]` が必要） | -| `disabled` | すべての受信 DM を無視 | +| `disabled` | すべての受信 DM を無視 | -| グループポリシー | 動作 | -| ---------------------- | -------------------------------------------------------- | -| `allowlist` (デフォルト) | 設定された許可リストに一致するグループのみ | -| `open` | グループ許可リストをバイパス（mention-gating は引き続き適用） | -| `disabled` | すべてのグループ/ルームメッセージをブロック | +| グループポリシー | 動作 | +| ------------------------ | ------------------------------------------------------ | +| `allowlist` (デフォルト) | 設定された許可リストに一致するグループのみ | +| `open` | グループ許可リストをバイパス（mention-gating は引き続き適用） | +| `disabled` | すべてのグループ/ルームメッセージをブロック | -`channels.defaults.groupPolicy` は、provider の `groupPolicy` が未設定のときのデフォルトを設定します。 -ペアリングコードは 1 時間後に期限切れになります。保留中の DM ペアリング要求は **channel ごとに 3 件** に制限されます。 -provider ブロック全体が存在しない場合（`channels.` がない場合）、ランタイムのグループポリシーは起動時警告付きで `allowlist`（fail-closed）にフォールバックします。 +`channels.defaults.groupPolicy` は、provider の `groupPolicy` が未設定のときのデフォルト値を設定します。 +ペアリングコードは 1 時間後に期限切れになります。保留中の DM ペアリングリクエストは **channel ごとに 3 件**までです。 +provider ブロック自体が完全に欠けている場合（`channels.` がない場合）、ランタイムのグループポリシーは起動時警告とともに `allowlist`（フェイルクローズ）へフォールバックします。 -### Channel のモデル上書き +### Channel モデルのオーバーライド -特定の channel ID をモデルに固定するには `channels.modelByChannel` を使用します。値には `provider/model` または設定済みモデルエイリアスを指定できます。channel マッピングは、セッションにすでにモデル上書きがない場合に適用されます（たとえば `/model` で設定された場合など）。 +特定の channel ID をモデルに固定するには `channels.modelByChannel` を使います。値には `provider/model` または設定済みのモデルエイリアスを指定できます。channel マッピングは、セッションにすでにモデルオーバーライドが存在しない場合に適用されます（たとえば `/model` で設定された場合など）。 ```json5 { @@ -85,9 +85,9 @@ provider ブロック全体が存在しない場合（`channels.` が } ``` -### Channel のデフォルトと Heartbeat +### Channel のデフォルト設定と Heartbeat -provider 間で共有するグループポリシーと Heartbeat の動作には `channels.defaults` を使用します: +provider 間で共有するグループポリシーと Heartbeat の動作には `channels.defaults` を使います: ```json5 { @@ -106,14 +106,14 @@ provider 間で共有するグループポリシーと Heartbeat の動作には ``` - `channels.defaults.groupPolicy`: provider レベルの `groupPolicy` が未設定のときのフォールバックグループポリシー。 -- `channels.defaults.contextVisibility`: すべての channel に対するデフォルトの補助コンテキスト可視性モード。値: `all`（デフォルト、引用/スレッド/履歴のすべてのコンテキストを含める）、`allowlist`（許可リストにある送信者からのコンテキストのみ含める）、`allowlist_quote`（allowlist と同じだが、明示的な引用/返信コンテキストは保持する）。channel ごとの上書き: `channels..contextVisibility`。 +- `channels.defaults.contextVisibility`: すべての channel に対する補足コンテキスト可視性モードのデフォルト値。値: `all`（デフォルト。引用/スレッド/履歴のすべてのコンテキストを含める）、`allowlist`（許可リストにある送信者からのコンテキストのみ含める）、`allowlist_quote`（`allowlist` と同じだが、明示的な引用/返信コンテキストは保持する）。channel ごとのオーバーライド: `channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`: 正常な channel ステータスを Heartbeat 出力に含めます。 -- `channels.defaults.heartbeat.showAlerts`: 劣化/エラーステータスを Heartbeat 出力に含めます。 -- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケータ形式の Heartbeat 出力をレンダリングします。 +- `channels.defaults.heartbeat.showAlerts`: 劣化/エラー状態のステータスを Heartbeat 出力に含めます。 +- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケータ形式の Heartbeat 出力を描画します。 ### WhatsApp -WhatsApp は gateway の web channel（Baileys Web）を通じて動作します。リンク済みセッションが存在すると自動的に起動します。 +WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。リンク済みセッションが存在すると自動的に起動します。 ```json5 { @@ -164,10 +164,10 @@ WhatsApp は gateway の web channel（Baileys Web）を通じて動作します } ``` -- 送信コマンドは、`default` アカウントが存在する場合はそれを既定とし、そうでない場合は最初に設定されたアカウント ID（ソート順）を使用します。 -- 任意の `channels.whatsapp.defaultAccount` は、設定済みアカウント ID と一致する場合に、そのフォールバックの既定アカウント選択を上書きします。 -- レガシーな単一アカウント Baileys auth dir は、`openclaw doctor` により `whatsapp/default` へ移行されます。 -- アカウントごとの上書き: `channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 送信コマンドは、`default` アカウントが存在する場合はそれを、存在しない場合は最初に設定されたアカウント ID（ソート順）をデフォルトにします。 +- 任意の `channels.whatsapp.defaultAccount` は、設定済みアカウント ID と一致する場合に、このフォールバックのデフォルトアカウント選択を上書きします。 +- 従来の単一アカウント Baileys auth dir は、`openclaw doctor` によって `whatsapp/default` へ移行されます。 +- アカウントごとのオーバーライド: `channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -225,13 +225,13 @@ WhatsApp は gateway の web channel（Baileys Web）を通じて動作します } ``` -- Bot token: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。symlink は拒否）、デフォルトアカウントでは `TELEGRAM_BOT_TOKEN` がフォールバックとして使われます。 +- Bot トークン: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。symlink は拒否されます）。デフォルトアカウントには `TELEGRAM_BOT_TOKEN` もフォールバックとして使えます。 - 任意の `channels.telegram.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- マルチアカウント構成（2 個以上のアカウント ID）では、フォールバックルーティングを避けるために明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定してください。これが不足または無効な場合、`openclaw doctor` が警告します。 -- `configWrites: false` は、Telegram 起点の設定書き込み（supergroup ID 移行、`/config set|unset`）をブロックします。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、フォーラムトピック用の永続的な ACP バインディングを設定します（`match.peer.id` には正規の `chatId:topic:topicId` を使用）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 -- Telegram のストリームプレビューは `sendMessage` + `editMessageText` を使用します（ダイレクトチャットとグループチャットの両方で動作）。 -- リトライポリシー: [Retry policy](/ja-JP/concepts/retry) を参照してください。 +- マルチアカウント構成（2 個以上のアカウント ID）では、フォールバックルーティングを避けるために明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定してください。これがない、または無効な場合、`openclaw doctor` が警告します。 +- `configWrites: false` は、Telegram 起点の設定書き込み（supergroup ID の移行、`/config set|unset`）をブロックします。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、フォーラムトピック用の永続 ACP バインディングを設定します（`match.peer.id` には正規の `chatId:topic:topicId` を使用）。フィールドのセマンティクスは [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 +- Telegram のストリームプレビューは `sendMessage` + `editMessageText` を使います（ダイレクトチャットとグループチャットの両方で動作）。 +- retry ポリシー: [Retry policy](/ja-JP/concepts/retry) を参照してください。 ### Discord @@ -333,36 +333,36 @@ WhatsApp は gateway の web channel（Baileys Web）を通じて動作します } ``` -- Token: `channels.discord.token`。デフォルトアカウントでは `DISCORD_BOT_TOKEN` がフォールバックとして使われます。 -- 明示的な Discord `token` を指定する直接送信呼び出しでは、その呼び出しにその token が使用されます。アカウントの retry/policy 設定は、アクティブなランタイムスナップショット内で選択されたアカウントから引き続き取得されます。 +- トークン: `channels.discord.token`。デフォルトアカウントでは `DISCORD_BOT_TOKEN` もフォールバックとして使えます。 +- 明示的な Discord `token` を指定する直接の送信呼び出しでは、その呼び出しにそのトークンが使われます。アカウントの retry/ポリシー設定は、引き続きアクティブなランタイムスナップショット内で選択されたアカウントから取得されます。 - 任意の `channels.discord.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- 配信ターゲットには `user:`（DM）または `channel:`（guild channel）を使用します。数字のみの ID は拒否されます。 -- Guild slug は小文字で、空白は `-` に置き換えられます。channel キーには slug 化された名前（`#` なし）を使用します。guild ID の使用を推奨します。 -- bot 自身が作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効になります。bot への mention を含む bot メッセージのみを受け付けるには `allowBots: "mentions"` を使用します（自分自身のメッセージは引き続き除外されます）。 -- `channels.discord.guilds..ignoreOtherMentions`（および channel ごとの上書き）は、bot を mention せずに別のユーザーまたはロールを mention しているメッセージを破棄します（@everyone/@here は除く）。 +- 配信ターゲットには `user:`（DM）または `channel:`（guild channel）を使用します。数値 ID 単体は拒否されます。 +- Guild slug は小文字で、スペースは `-` に置き換えられます。channel キーには slug 化された名前（`#` なし）を使います。guild ID の使用を推奨します。 +- bot 自身が作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効になります。bot をメンションした bot メッセージだけを受け付けるには `allowBots: "mentions"` を使ってください（自分自身のメッセージは引き続きフィルタされます）。 +- `channels.discord.guilds..ignoreOtherMentions`（および channel オーバーライド）は、別のユーザーまたはロールにはメンションしているが bot にはメンションしていないメッセージを破棄します（@everyone/@here は除く）。 - `maxLinesPerMessage`（デフォルト 17）は、2000 文字未満でも行数の多いメッセージを分割します。 - `channels.discord.threadBindings` は Discord のスレッドバインド型ルーティングを制御します: - - `enabled`: スレッドバインドセッション機能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインドされた配信/ルーティング）に対する Discord 上書き - - `idleHours`: 非アクティブ時の自動 unfocus の時間単位の Discord 上書き（`0` で無効） - - `maxAgeHours`: ハード最大寿命の時間単位の Discord 上書き（`0` で無効） + - `enabled`: スレッドバインドセッション機能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインド配信/ルーティング）に対する Discord オーバーライド + - `idleHours`: 非アクティブ時の自動 unfocus を時間単位で指定する Discord オーバーライド（`0` で無効） + - `maxAgeHours`: ハード最大経過時間を時間単位で指定する Discord オーバーライド（`0` で無効） - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` の自動スレッド作成/バインドを有効にするオプトインスイッチ -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、channel とスレッド用の永続的な ACP バインディングを設定します（`match.peer.id` には channel/thread id を使用）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、channel とスレッド用の永続 ACP バインディングを設定します（`match.peer.id` には channel/thread id を使用）。フィールドのセマンティクスは [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 - `channels.discord.ui.components.accentColor` は、Discord components v2 コンテナのアクセントカラーを設定します。 -- `channels.discord.voice` は、Discord 音声 channel での会話と、任意の自動参加 + TTS 上書きを有効にします。 +- `channels.discord.voice` は、Discord 音声 channel での会話と、任意の自動参加 + TTS オーバーライドを有効にします。 - `channels.discord.voice.daveEncryption` と `channels.discord.voice.decryptionFailureTolerance` は、`@discordjs/voice` の DAVE オプションにそのまま渡されます（デフォルトは `true` と `24`）。 -- OpenClaw はさらに、復号失敗が繰り返された後に音声セッションから離脱して再参加することで、音声受信の回復も試みます。 -- `channels.discord.streaming` は正規のストリームモードキーです。レガシーな `streamMode` と boolean の `streaming` 値は自動移行されます。 -- `channels.discord.autoPresence` は、ランタイムの可用性を bot presence にマッピングします（healthy => online、degraded => idle、exhausted => dnd）。任意でステータステキストの上書きも可能です。 -- `channels.discord.dangerouslyAllowNameMatching` は、変更可能な name/tag マッチングを再有効化します（緊急時用の互換モード）。 +- さらに OpenClaw は、復号失敗が繰り返された後に音声セッションを離脱/再参加することで、音声受信の回復も試みます。 +- `channels.discord.streaming` は正規のストリームモードキーです。従来の `streamMode` と boolean の `streaming` 値は自動移行されます。 +- `channels.discord.autoPresence` は、ランタイム可用性を bot の presence にマッピングします（healthy => online、degraded => idle、exhausted => dnd）。任意のステータステキスト上書きも可能です。 +- `channels.discord.dangerouslyAllowNameMatching` は、変更可能な name/tag マッチングを再有効化します（非常時用の互換モード）。 - `channels.discord.execApprovals`: Discord ネイティブの exec 承認配信と承認者認可。 - - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。auto モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できると exec 承認が有効化されます。 + - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。auto モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効化されます。 - `approvers`: exec リクエストを承認できる Discord ユーザー ID。省略時は `commands.ownerAllowFrom` にフォールバックします。 - - `agentFilter`: 任意の agent ID 許可リスト。省略するとすべての agent の承認が転送されます。 + - `agentFilter`: 任意の agent ID 許可リスト。省略するとすべての agent の承認を転送します。 - `sessionFilter`: 任意のセッションキーパターン（部分文字列または regex）。 - - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）は承認者 DM に送信し、`"channel"` は発信元 channel に送信し、`"both"` は両方に送信します。target に `"channel"` が含まれる場合、ボタンを使用できるのは解決済み承認者のみです。 + - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）は承認者 DM に送信し、`"channel"` は元の channel に送信し、`"both"` は両方に送信します。target に `"channel"` が含まれる場合、ボタンを使用できるのは解決済み承認者のみです。 - `cleanupAfterResolve`: `true` の場合、承認、拒否、またはタイムアウト後に承認 DM を削除します。 -**リアクション通知モード:** `off`（なし）、`own`（bot 自身のメッセージ、デフォルト）、`all`（すべてのメッセージ）、`allowlist`（すべてのメッセージについて `guilds..users` から）。 +**リアクション通知モード:** `off`（なし）、`own`（bot のメッセージ、デフォルト）、`all`（すべてのメッセージ）、`allowlist`（すべてのメッセージに対して `guilds..users` から）。 ### Google Chat @@ -395,9 +395,9 @@ WhatsApp は gateway の web channel（Baileys Web）を通じて動作します - サービスアカウント JSON: インライン（`serviceAccount`）またはファイルベース（`serviceAccountFile`）。 - サービスアカウントの SecretRef（`serviceAccountRef`）もサポートされます。 -- env フォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 +- 環境変数フォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 - 配信ターゲットには `spaces/` または `users/` を使用します。 -- `channels.googlechat.dangerouslyAllowNameMatching` は、変更可能なメール principal マッチングを再有効化します（緊急時用の互換モード）。 +- `channels.googlechat.dangerouslyAllowNameMatching` は、変更可能なメール principal マッチングを再有効化します（非常時用の互換モード）。 ### Slack @@ -464,30 +464,30 @@ WhatsApp は gateway の web channel（Baileys Web）を通じて動作します } ``` -- **Socket mode** では `botToken` と `appToken` の両方が必要です（デフォルトアカウントの env フォールバックは `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **Socket mode** では `botToken` と `appToken` の両方が必要です（デフォルトアカウントの環境変数フォールバックは `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 - **HTTP mode** では `botToken` と `signingSecret`（ルートまたはアカウントごと）が必要です。 -- `botToken`、`appToken`、`signingSecret`、`userToken` は平文文字列または SecretRef オブジェクトを受け付けます。 -- Slack アカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、HTTP mode では `signingSecretStatus` などの、資格情報ごとの source/status フィールドを公開します。`configured_unavailable` は、そのアカウントが SecretRef で設定されているが、現在のコマンド/ランタイム経路ではシークレット値を解決できなかったことを意味します。 +- `botToken`、`appToken`、`signingSecret`、`userToken` はプレーンテキスト文字列または SecretRef オブジェクトを受け付けます。 +- Slack アカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、HTTP mode では `signingSecretStatus` など、認証情報ごとの source/status フィールドを公開します。`configured_unavailable` は、そのアカウントが SecretRef 経由で設定されているが、現在のコマンド/ランタイム経路では secret 値を解決できなかったことを意味します。 - `configWrites: false` は、Slack 起点の設定書き込みをブロックします。 - 任意の `channels.slack.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- `channels.slack.streaming.mode` は正規の Slack ストリームモードキーです。`channels.slack.streaming.nativeTransport` は Slack のネイティブストリーミング転送を制御します。レガシーな `streamMode`、boolean の `streaming`、および `nativeStreaming` の値は自動移行されます。 +- `channels.slack.streaming.mode` は正規の Slack ストリームモードキーです。`channels.slack.streaming.nativeTransport` は Slack のネイティブストリーミング転送を制御します。従来の `streamMode`、boolean の `streaming`、`nativeStreaming` の値は自動移行されます。 - 配信ターゲットには `user:`（DM）または `channel:` を使用します。 **リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 -**スレッドセッション分離:** `thread.historyScope` はスレッド単位（デフォルト）または channel 共有です。`thread.inheritParent` は親 channel の transcript を新しいスレッドにコピーします。 +**スレッドセッション分離:** `thread.historyScope` はスレッド単位（デフォルト）または channel 共有です。`thread.inheritParent` は親 channel のトランスクリプトを新しいスレッドにコピーします。 -- Slack のネイティブストリーミングと、Slack assistant スタイルの「入力中...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベル DM はデフォルトでスレッド外のままなので、スレッドスタイルのプレビューではなく `typingReaction` または通常配信を使用します。 -- `typingReaction` は、返信の実行中に受信した Slack メッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` のような Slack 絵文字ショートコードを使用します。 +- Slack ネイティブストリーミングと、Slack の assistant スタイル「is typing...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベル DM はデフォルトでスレッド外のままなので、スレッドスタイルのプレビューではなく `typingReaction` または通常配信を使います。 +- `typingReaction` は、返信の実行中に受信した Slack メッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` のような Slack 絵文字 shortcode を使用してください。 - `channels.slack.execApprovals`: Slack ネイティブの exec 承認配信と承認者認可。スキーマは Discord と同じです: `enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack ユーザー ID）、`agentFilter`、`sessionFilter`、`target`（`"dm"`、`"channel"`、または `"both"`）。 -| アクショングループ | デフォルト | 注記 | +| アクショングループ | デフォルト | 備考 | | ------------------ | ---------- | ------------------------ | -| reactions | enabled | リアクション + リアクション一覧 | -| messages | enabled | 読み取り/送信/編集/削除 | -| pins | enabled | ピン留め/解除/一覧 | -| memberInfo | enabled | メンバー情報 | -| emojiList | enabled | カスタム絵文字一覧 | +| reactions | enabled | リアクト + リアクション一覧 | +| messages | enabled | 読み取り/送信/編集/削除 | +| pins | enabled | ピン留め/解除/一覧 | +| memberInfo | enabled | メンバー情報 | +| emojiList | enabled | カスタム絵文字一覧 | ### Mattermost @@ -521,19 +521,17 @@ Mattermost は Plugin として提供されます: `openclaw plugins install @op } ``` -チャットモード: `oncall`（@-mention で応答、デフォルト）、`onmessage`（すべてのメッセージ）、`onchar`（トリガープレフィックスで始まるメッセージ）。 +チャットモード: `oncall`（@-mention 時に応答、デフォルト）、`onmessage`（すべてのメッセージ）、`onchar`（トリガープレフィックスで始まるメッセージ）。 Mattermost ネイティブコマンドが有効な場合: -- `commands.callbackPath` は完全 URL ではなくパスでなければなりません（例: `/api/channels/mattermost/command`）。 -- `commands.callbackUrl` は OpenClaw gateway エンドポイントに解決され、Mattermost サーバーから到達可能でなければなりません。 -- ネイティブスラッシュコールバックは、スラッシュコマンド登録時に Mattermost が返すコマンドごとの token で認証されます。登録に失敗した場合、または有効なコマンドがない場合、OpenClaw は次のエラーでコールバックを拒否します: - `Unauthorized: invalid command token.` -- 非公開/tailnet/internal のコールバックホストでは、Mattermost で `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含める必要がある場合があります。 - 完全 URL ではなくホスト/ドメイン値を使用してください。 +- `commands.callbackPath` はフル URL ではなくパスである必要があります（例: `/api/channels/mattermost/command`）。 +- `commands.callbackUrl` は OpenClaw Gateway エンドポイントを指し、Mattermost サーバーから到達可能である必要があります。 +- ネイティブスラッシュコールバックは、スラッシュコマンド登録時に Mattermost が返すコマンド単位のトークンで認証されます。登録に失敗した場合、または有効化されたコマンドがない場合、OpenClaw はコールバックを `Unauthorized: invalid command token.` で拒否します。 +- 非公開/tailnet/internal のコールバックホストでは、Mattermost 側で `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含める必要がある場合があります。フル URL ではなく、ホスト/ドメイン値を使用してください。 - `channels.mattermost.configWrites`: Mattermost 起点の設定書き込みを許可または拒否します。 - `channels.mattermost.requireMention`: channel で返信する前に `@mention` を必須にします。 -- `channels.mattermost.groups..requireMention`: channel ごとの mention-gating 上書き（デフォルトには `"*"`）。 +- `channels.mattermost.groups..requireMention`: channel ごとの mention-gating オーバーライド（デフォルトは `"*"`）。 - 任意の `channels.mattermost.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 ### Signal @@ -557,13 +555,13 @@ Mattermost ネイティブコマンドが有効な場合: **リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 -- `channels.signal.account`: channel の起動を特定の Signal アカウント ID に固定します。 +- `channels.signal.account`: channel の起動先を特定の Signal アカウント ID に固定します。 - `channels.signal.configWrites`: Signal 起点の設定書き込みを許可または拒否します。 - 任意の `channels.signal.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 ### BlueBubbles -BlueBubbles は推奨される iMessage 経路です（Plugin ベースで、`channels.bluebubbles` 配下に設定します）。 +BlueBubbles は推奨される iMessage 経路です（Plugin バック、`channels.bluebubbles` 配下で設定）。 ```json5 { @@ -580,8 +578,8 @@ BlueBubbles は推奨される iMessage 経路です（Plugin ベースで、`ch - ここで扱うコアのキーパス: `channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 - 任意の `channels.bluebubbles.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続的な ACP セッションにバインドできます。`match.peer.id` には BlueBubbles の handle または target 文字列（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共有されるフィールドの意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 -- BlueBubbles channel の完全な設定は [BlueBubbles](/ja-JP/channels/bluebubbles) に記載されています。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続 ACP セッションにバインドできます。`match.peer.id` には BlueBubbles の handle またはターゲット文字列（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共通フィールドセマンティクス: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 +- 完全な BlueBubbles channel 設定は [BlueBubbles](/ja-JP/channels/bluebubbles) に記載されています。 ### iMessage @@ -611,13 +609,13 @@ OpenClaw は `imsg rpc`（stdio 上の JSON-RPC）を起動します。daemon - 任意の `channels.imessage.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- Messages DB への Full Disk Access が必要です。 -- `chat_id:` ターゲットの使用を推奨します。チャット一覧を表示するには `imsg chats --limit 20` を使用します。 -- `cliPath` は SSH ラッパーを指すこともできます。SCP で添付ファイルを取得するには `remoteHost`（`host` または `user@host`）を設定します。 +- Messages DB へのフルディスクアクセスが必要です。 +- `chat_id:` ターゲットの使用を推奨します。チャット一覧は `imsg chats --limit 20` で取得できます。 +- `cliPath` は SSH ラッパーを指すこともできます。SCP で添付ファイルを取得するには `remoteHost`（`host` または `user@host`）を設定してください。 - `attachmentRoots` と `remoteAttachmentRoots` は受信添付ファイルのパスを制限します（デフォルト: `/Users/*/Library/Messages/Attachments`）。 -- SCP は厳格なホストキー検証を使用するため、リレーホストのキーがすでに `~/.ssh/known_hosts` に存在していることを確認してください。 +- SCP は厳格なホストキー検証を使うため、リレーホストのキーがすでに `~/.ssh/known_hosts` に存在している必要があります。 - `channels.imessage.configWrites`: iMessage 起点の設定書き込みを許可または拒否します。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続的な ACP セッションにバインドできます。`match.peer.id` には正規化された handle または明示的なチャットターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共有されるフィールドの意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続 ACP セッションにバインドできます。`match.peer.id` には正規化済み handle または明示的な chat ターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共通フィールドセマンティクス: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 @@ -630,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix は extension ベースで、`channels.matrix` 配下に設定します。 +Matrix は extension バックで、`channels.matrix` 配下で設定します。 ```json5 { @@ -660,25 +658,25 @@ Matrix は extension ベースで、`channels.matrix` 配下に設定します } ``` -- token 認証は `accessToken` を使用します。パスワード認証は `userId` + `password` を使用します。 -- `channels.matrix.proxy` は Matrix HTTP トラフィックを明示的な HTTP(S) proxy 経由にします。名前付きアカウントは `channels.matrix.accounts..proxy` でこれを上書きできます。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` は private/internal homeserver を許可します。`proxy` とこの network オプトインは独立した制御です。 -- `channels.matrix.defaultAccount` は、マルチアカウント構成で優先するアカウントを選択します。 -- `channels.matrix.autoJoin` のデフォルトは `off` なので、`autoJoin: "allowlist"` と `autoJoinAllowlist`、または `autoJoin: "always"` を設定するまで、招待された room や新しい DM スタイルの招待は無視されます。 +- トークン認証は `accessToken` を使用し、パスワード認証は `userId` + `password` を使用します。 +- `channels.matrix.proxy` は Matrix HTTP トラフィックを明示的な HTTP(S) proxy 経由にします。名前付きアカウントは `channels.matrix.accounts..proxy` で上書きできます。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` は private/internal な homeserver を許可します。`proxy` とこのネットワーク opt-in は独立した制御です。 +- `channels.matrix.defaultAccount` は、マルチアカウント構成で優先アカウントを選択します。 +- `channels.matrix.autoJoin` のデフォルトは `off` なので、招待された room や新しい DM スタイルの招待は、`autoJoin: "allowlist"` と `autoJoinAllowlist` を設定するか、`autoJoin: "always"` を設定するまで無視されます。 - `channels.matrix.execApprovals`: Matrix ネイティブの exec 承認配信と承認者認可。 - - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。auto モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できると exec 承認が有効化されます。 + - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。auto モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効化されます。 - `approvers`: exec リクエストを承認できる Matrix ユーザー ID（例: `@owner:example.org`）。 - - `agentFilter`: 任意の agent ID 許可リスト。省略するとすべての agent の承認が転送されます。 + - `agentFilter`: 任意の agent ID 許可リスト。省略するとすべての agent の承認を転送します。 - `sessionFilter`: 任意のセッションキーパターン（部分文字列または regex）。 - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）、`"channel"`（発信元 room）、または `"both"`。 - - アカウントごとの上書き: `channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` は、Matrix DM をセッションへどのようにグループ化するかを制御します: `per-user`（デフォルト）はルーティングされた peer ごとに共有し、`per-room` は各 DM room を分離します。 -- Matrix ステータスプローブとライブディレクトリ参照は、ランタイムトラフィックと同じ proxy ポリシーを使用します。 -- 完全な Matrix 設定、ターゲティングルール、およびセットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 + - アカウントごとのオーバーライド: `channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` は、Matrix DM をどのようにセッションへグループ化するかを制御します: `per-user`（デフォルト）はルーティングされた peer 単位で共有し、`per-room` は各 DM room を分離します。 +- Matrix のステータス probe とライブディレクトリ参照は、ランタイムトラフィックと同じ proxy ポリシーを使います。 +- 完全な Matrix 設定、ターゲティングルール、セットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 ### Microsoft Teams -Microsoft Teams は extension ベースで、`channels.msteams` 配下に設定します。 +Microsoft Teams は extension バックで、`channels.msteams` 配下で設定します。 ```json5 { @@ -694,11 +692,11 @@ Microsoft Teams は extension ベースで、`channels.msteams` 配下に設定 ``` - ここで扱うコアのキーパス: `channels.msteams`、`channels.msteams.configWrites`。 -- Teams の完全な設定（認証情報、webhook、DM/グループポリシー、team/channel ごとの上書き）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 +- 完全な Teams 設定（資格情報、webhook、DM/グループポリシー、team/channel ごとのオーバーライド）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 ### IRC -IRC は extension ベースで、`channels.irc` 配下に設定します。 +IRC は extension バックで、`channels.irc` 配下で設定します。 ```json5 { @@ -721,11 +719,11 @@ IRC は extension ベースで、`channels.irc` 配下に設定します。 - ここで扱うコアのキーパス: `channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 - 任意の `channels.irc.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- IRC channel の完全な設定（host/port/TLS/channels/allowlists/mention gating）は [IRC](/ja-JP/channels/irc) に記載されています。 +- 完全な IRC channel 設定（host/port/TLS/channels/allowlists/mention gating）は [IRC](/ja-JP/channels/irc) に記載されています。 -### マルチアカウント（すべての channel） +### マルチアカウント（すべての channels） -channel ごとに複数アカウントを実行できます（各アカウントは独自の `accountId` を持ちます）: +channel ごとに複数のアカウントを実行できます（各アカウントは独自の `accountId` を持ちます）: ```json5 { @@ -746,28 +744,28 @@ channel ごとに複数アカウントを実行できます（各アカウント } ``` -- `accountId` を省略した場合は `default` が使用されます（CLI + routing）。 -- env token は **default** アカウントにのみ適用されます。 -- ベース channel 設定は、アカウントごとに上書きされない限り、すべてのアカウントに適用されます。 -- 各アカウントを別の agent にルーティングするには `bindings[].match.accountId` を使用します。 -- 単一アカウントのトップレベル channel 設定のまま `openclaw channels add`（または channel オンボーディング）で非 default アカウントを追加すると、OpenClaw は元のアカウントが引き続き動作するように、まずアカウントスコープのトップレベル単一アカウント値を channel のアカウントマップへ昇格します。ほとんどの channel ではそれらを `channels..accounts.default` へ移動します。Matrix は既存の一致する名前付き/default ターゲットを代わりに保持できます。 -- 既存の channel のみ対象のバインディング（`accountId` なし）は引き続き default アカウントに一致します。アカウントスコープのバインディングは任意のままです。 -- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値をその channel 用に選択された昇格先アカウントへ移動することで、混在した形状を修復します。ほとんどの channel では `accounts.default` を使用します。Matrix は既存の一致する名前付き/default ターゲットを代わりに保持できます。 +- `accountId` を省略した場合は `default` が使われます（CLI + ルーティング）。 +- 環境変数トークンは **default** アカウントにのみ適用されます。 +- ベース channel 設定は、アカウントごとに上書きしない限りすべてのアカウントに適用されます。 +- `bindings[].match.accountId` を使うと、各アカウントを異なる agent にルーティングできます。 +- 単一アカウントのトップレベル channel 設定のまま `openclaw channels add`（または channel オンボーディング）で非デフォルトアカウントを追加すると、OpenClaw はまずアカウントスコープのトップレベル単一アカウント値を channel のアカウントマップへ昇格させるため、元のアカウントはそのまま動作し続けます。ほとんどの channels ではそれらは `channels..accounts.default` に移動されますが、Matrix では既存の一致する named/default ターゲットを代わりに保持できます。 +- 既存の channel のみのバインディング（`accountId` なし）は引き続きデフォルトアカウントに一致します。アカウントスコープ付きバインディングは引き続き任意です。 +- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値をその channel 用に選ばれた昇格先アカウントへ移動することで、混在した形状を修復します。ほとんどの channels では `accounts.default` が使われますが、Matrix では既存の一致する named/default ターゲットを代わりに保持できます。 -### その他の extension channel +### その他の extension channels -多くの extension channel は `channels.` として設定され、専用の channel ページに記載されています（たとえば Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch など）。 +多くの extension channels は `channels.` として設定され、専用の channel ページに記載されています（たとえば Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 完全な channel 一覧は [Channels](/ja-JP/channels) を参照してください。 ### グループチャットの mention gating -グループメッセージはデフォルトで **mention 必須** です（メタデータ mention または安全な regex パターン）。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。 +グループメッセージでは、デフォルトで **メンション必須** です（メタデータメンションまたは安全な regex パターン）。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。 -**mention の種類:** +**メンションの種類:** -- **メタデータ mention**: ネイティブプラットフォームの @-mention。WhatsApp の self-chat モードでは無視されます。 +- **メタデータメンション**: ネイティブプラットフォームの @-mention。WhatsApp の self-chat mode では無視されます。 - **テキストパターン**: `agents.list[].groupChat.mentionPatterns` 内の安全な regex パターン。無効なパターンや安全でないネストされた繰り返しは無視されます。 -- mention gating は、検出が可能な場合にのみ適用されます（ネイティブ mention または少なくとも 1 つのパターンがある場合）。 +- mention gating は、検出可能な場合にのみ適用されます（ネイティブメンションまたは少なくとも 1 つのパターンがある場合）。 ```json5 { @@ -780,7 +778,7 @@ channel ごとに複数アカウントを実行できます（各アカウント } ``` -`messages.groupChat.historyLimit` はグローバルなデフォルトを設定します。channel は `channels..historyLimit`（またはアカウントごと）で上書きできます。無効にするには `0` を設定します。 +`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。channels は `channels..historyLimit`（またはアカウントごと）で上書きできます。無効にするには `0` を設定します。 #### DM 履歴制限 @@ -797,13 +795,13 @@ channel ごとに複数アカウントを実行できます（各アカウント } ``` -解決順序: DM ごとの上書き → provider デフォルト → 制限なし（すべて保持）。 +解決順序: DM ごとのオーバーライド → provider デフォルト → 制限なし（すべて保持）。 -対応: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 +サポート対象: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### self-chat モード +#### self-chat mode -`allowFrom` に自分の番号を含めると self-chat モードが有効になります（ネイティブ @-mention は無視し、テキストパターンにのみ応答します）: +自分の電話番号を `allowFrom` に含めると self-chat mode が有効になります（ネイティブ @-mention は無視し、テキストパターンのみに応答します）: ```json5 { @@ -829,16 +827,16 @@ channel ごとに複数アカウントを実行できます（各アカウント ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // supported の場合はネイティブコマンドを登録 + nativeSkills: "auto", // supported の場合はネイティブ skill コマンドを登録 + text: true, // チャットメッセージ内の /commands を解析 + bash: false, // ! を許可（alias: /bash） bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // /config を許可 + mcp: false, // /mcp を許可 + plugins: false, // /plugins を許可 + debug: false, // /debug を許可 + restart: true, // /restart + Gateway restart tool を許可 ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -851,29 +849,29 @@ channel ごとに複数アカウントを実行できます（各アカウント } ``` - + -- このブロックはコマンドサーフェスを設定します。現在の組み込み + bundled コマンドカタログについては [Slash Commands](/ja-JP/tools/slash-commands) を参照してください。 -- このページは**設定キーのリファレンス**であり、完全なコマンドカタログではありません。QQ Bot の `/bot-ping` `/bot-help` `/bot-logs`、LINE の `/card`、device-pair の `/pair`、memory の `/dreaming`、phone-control の `/phone`、Talk の `/voice` など、channel/plugin 所有のコマンドは、それぞれの channel/plugin ページおよび [Slash Commands](/ja-JP/tools/slash-commands) に記載されています。 +- このブロックはコマンドサーフェスを設定します。現在の組み込み + bundled コマンドカタログについては [スラッシュコマンド](/ja-JP/tools/slash-commands) を参照してください。 +- このページは**設定キーリファレンス**であり、完全なコマンドカタログではありません。QQ Bot の `/bot-ping` `/bot-help` `/bot-logs`、LINE の `/card`、device-pair の `/pair`、memory の `/dreaming`、phone-control の `/phone`、Talk の `/voice` などの channel/plugin 所有コマンドは、それぞれの channel/plugin ページと [スラッシュコマンド](/ja-JP/tools/slash-commands) に記載されています。 - テキストコマンドは、先頭が `/` の**単独メッセージ**である必要があります。 -- `native: "auto"` は Discord/Telegram のネイティブコマンドを有効にし、Slack は無効のままにします。 -- `nativeSkills: "auto"` は Discord/Telegram のネイティブ Skills コマンドを有効にし、Slack は無効のままにします。 -- channel ごとの上書き: `channels.discord.commands.native`（bool または `"auto"`）。`false` は以前に登録されたコマンドをクリアします。 -- channel ごとのネイティブ skill 登録は `channels..commands.nativeSkills` で上書きします。 -- `channels.telegram.customCommands` は、追加の Telegram bot メニュー項目を追加します。 -- `bash: true` はホストシェル向けの `! ` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.` に含まれていることが必要です。 -- `config: true` は `/config` を有効にします（`openclaw.json` の読み取り/書き込み）。gateway `chat.send` クライアントでは、永続的な `/config set|unset` の書き込みに `operator.admin` も必要です。読み取り専用の `/config show` は通常の書き込みスコープを持つ operator クライアントでも引き続き利用できます。 -- `mcp: true` は、`mcp.servers` 配下の OpenClaw 管理 MCP サーバー設定に対する `/mcp` を有効にします。 -- `plugins: true` は、Plugin の検出、インストール、有効化/無効化制御のための `/plugins` を有効にします。 -- `channels..configWrites` は、channel ごとの設定変更を制御します（デフォルト: true）。 -- マルチアカウント channel では、`channels..accounts..configWrites` も、そのアカウントを対象とする書き込み（たとえば `/allowlist --config --account ` や `/config set channels..accounts....`）を制御します。 -- `restart: false` は `/restart` と gateway restart tool のアクションを無効にします。デフォルト: `true`。 -- `ownerAllowFrom` は owner 専用コマンド/tool 用の明示的な owner 許可リストです。`allowFrom` とは別です。 -- `ownerDisplay: "hash"` は system prompt 内の owner ID をハッシュ化します。ハッシュ化を制御するには `ownerDisplaySecret` を設定します。 -- `allowFrom` は provider ごとです。設定されている場合、それが**唯一の**認可ソースになります（channel の allowlist/pairing と `useAccessGroups` は無視されます）。 +- `native: "auto"` は Discord/Telegram でネイティブコマンドを有効にし、Slack では無効のままにします。 +- `nativeSkills: "auto"` は Discord/Telegram でネイティブ Skills コマンドを有効にし、Slack では無効のままにします。 +- channel ごとのオーバーライド: `channels.discord.commands.native`（bool または `"auto"`）。`false` を指定すると、以前登録されたコマンドをクリアします。 +- ネイティブ skill 登録は `channels..commands.nativeSkills` で provider ごとにオーバーライドできます。 +- `channels.telegram.customCommands` は追加の Telegram bot メニュー項目を追加します。 +- `bash: true` はホスト shell 用の `! ` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.` に含まれていることが必要です。 +- `config: true` は `/config`（`openclaw.json` の読み書き）を有効にします。Gateway の `chat.send` クライアントでは、永続的な `/config set|unset` 書き込みには `operator.admin` も必要です。読み取り専用の `/config show` は通常の書き込みスコープを持つ operator クライアントでも引き続き使用できます。 +- `mcp: true` は、`mcp.servers` 配下の OpenClaw 管理 MCP サーバー設定用の `/mcp` を有効にします。 +- `plugins: true` は、Plugin の検出、インストール、有効化/無効化制御用の `/plugins` を有効にします。 +- `channels..configWrites` は channel ごとの設定変更を制御します（デフォルト: true）。 +- マルチアカウント channel では、`channels..accounts..configWrites` も、そのアカウントを対象とする書き込みを制御します（たとえば `/allowlist --config --account ` や `/config set channels..accounts....`）。 +- `restart: false` は `/restart` と Gateway restart tool アクションを無効にします。デフォルト: `true`。 +- `ownerAllowFrom` は、owner 専用コマンド/ツール用の明示的な owner 許可リストです。`allowFrom` とは別です。 +- `ownerDisplay: "hash"` は、system prompt 内の owner ID をハッシュ化します。ハッシュ化を制御するには `ownerDisplaySecret` を設定してください。 +- `allowFrom` は provider ごとです。設定されている場合、これが**唯一の**認可ソースになります（channel の allowlist/pairing と `useAccessGroups` は無視されます）。 - `useAccessGroups: false` は、`allowFrom` が設定されていない場合に、コマンドが access-group ポリシーをバイパスできるようにします。 -- コマンドドキュメントの対応: - - 組み込み + bundled カタログ: [Slash Commands](/ja-JP/tools/slash-commands) +- コマンドドキュメントの対応表: + - 組み込み + bundled カタログ: [スラッシュコマンド](/ja-JP/tools/slash-commands) - channel 固有のコマンドサーフェス: [Channels](/ja-JP/channels) - QQ Bot コマンド: [QQ Bot](/ja-JP/channels/qqbot) - pairing コマンド: [Pairing](/ja-JP/channels/pairing) @@ -884,7 +882,7 @@ channel ごとに複数アカウントを実行できます（各アカウント --- -## Agent のデフォルト +## Agent のデフォルト設定 ### `agents.defaults.workspace` @@ -898,7 +896,7 @@ channel ごとに複数アカウントを実行できます（各アカウント ### `agents.defaults.repoRoot` -system prompt の Runtime 行に表示される任意のリポジトリルートです。未設定の場合、OpenClaw は workspace から上位へたどって自動検出します。 +system prompt の Runtime 行に表示される任意のリポジトリルートです。未設定の場合、OpenClaw は workspace から上方向にたどって自動検出します。 ```json5 { @@ -908,7 +906,7 @@ system prompt の Runtime 行に表示される任意のリポジトリルート ### `agents.defaults.skills` -`agents.list[].skills` を設定していない agent 向けの、任意のデフォルト Skills 許可リストです。 +`agents.list[].skills` を設定していない agent 用の、任意のデフォルト Skills 許可リストです。 ```json5 { @@ -916,7 +914,7 @@ system prompt の Runtime 行に表示される任意のリポジトリルート defaults: { skills: ["github", "weather"] }, list: [ { id: "writer" }, // github, weather を継承 - { id: "docs", skills: ["docs-search"] }, // defaults を置き換える + { id: "docs", skills: ["docs-search"] }, // デフォルトを置き換え { id: "locked-down", skills: [] }, // Skills なし ], }, @@ -926,12 +924,11 @@ system prompt の Runtime 行に表示される任意のリポジトリルート - デフォルトで Skills を無制限にするには `agents.defaults.skills` を省略します。 - デフォルトを継承するには `agents.list[].skills` を省略します。 - Skills なしにするには `agents.list[].skills: []` を設定します。 -- 空でない `agents.list[].skills` リストは、その agent の最終セットです。 - defaults とはマージされません。 +- 空でない `agents.list[].skills` リストは、その agent の最終セットです。デフォルトとはマージされません。 ### `agents.defaults.skipBootstrap` -workspace ブートストラップファイル（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）の自動作成を無効にします。 +workspace bootstrap ファイル（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）の自動作成を無効にします。 ```json5 { @@ -941,9 +938,9 @@ workspace ブートストラップファイル（`AGENTS.md`、`SOUL.md`、`TOOL ### `agents.defaults.contextInjection` -workspace ブートストラップファイルを system prompt にいつ注入するかを制御します。デフォルト: `"always"`。 +workspace bootstrap ファイルを 언제 system prompt に注入するかを制御します。デフォルト: `"always"`。 -- `"continuation-skip"`: 安全な継続ターン（assistant の応答完了後）では workspace ブートストラップの再注入をスキップし、prompt サイズを削減します。Heartbeat 実行と compaction 後の再試行では、引き続きコンテキストを再構築します。 +- `"continuation-skip"`: 安全な継続ターン（assistant の応答完了後）では workspace bootstrap の再注入をスキップし、プロンプトサイズを削減します。Heartbeat 実行と Compaction 後の再試行では引き続きコンテキストが再構築されます。 ```json5 { @@ -953,7 +950,7 @@ workspace ブートストラップファイルを system prompt にいつ注入 ### `agents.defaults.bootstrapMaxChars` -切り詰め前の workspace ブートストラップファイルごとの最大文字数です。デフォルト: `20000`。 +切り詰め前の、workspace bootstrap ファイルごとの最大文字数です。デフォルト: `20000`。 ```json5 { @@ -963,7 +960,7 @@ workspace ブートストラップファイルを system prompt にいつ注入 ### `agents.defaults.bootstrapTotalMaxChars` -すべての workspace ブートストラップファイルにわたって注入される最大総文字数です。デフォルト: `150000`。 +すべての workspace bootstrap ファイルにまたがって注入される最大総文字数です。デフォルト: `150000`。 ```json5 { @@ -973,10 +970,10 @@ workspace ブートストラップファイルを system prompt にいつ注入 ### `agents.defaults.bootstrapPromptTruncationWarning` -ブートストラップコンテキストが切り詰められたときに agent に見える警告テキストを制御します。 +bootstrap コンテキストが切り詰められたときに agent に見える警告テキストを制御します。 デフォルト: `"once"`。 -- `"off"`: 警告テキストを system prompt に一切注入しません。 +- `"off"`: system prompt に警告テキストを一切注入しません。 - `"once"`: 一意の切り詰めシグネチャごとに 1 回だけ警告を注入します（推奨）。 - `"always"`: 切り詰めが存在する場合、毎回の実行で警告を注入します。 @@ -986,12 +983,139 @@ workspace ブートストラップファイルを system prompt にいつ注入 } ``` +### コンテキスト予算の所有マップ + +OpenClaw には大容量の prompt/context 予算が複数あり、それらは 1 つの汎用ノブにまとめず、サブシステムごとに意図的に分割されています。 + +- `agents.defaults.bootstrapMaxChars` / + `agents.defaults.bootstrapTotalMaxChars`: + 通常の workspace bootstrap 注入。 +- `agents.defaults.startupContext.*`: + 1 回限りの `/new` と `/reset` の起動前奏コンテキスト。最近の + `memory/*.md` ファイルを含みます。 +- `skills.limits.*`: + system prompt に注入されるコンパクトな Skills 一覧。 +- `agents.defaults.contextLimits.*`: + 制限付きランタイム抜粋と、注入されるランタイム所有ブロック。 +- `memory.qmd.limits.*`: + インデックス化された memory search スニペットと注入サイズ。 + +特定の agent にのみ別の予算が必要な場合に限り、対応する agent ごとのオーバーライドを使用してください: + +- `agents.list[].skillsLimits.maxSkillsPromptChars` +- `agents.list[].contextLimits.*` + +#### `agents.defaults.startupContext` + +素の `/new` と `/reset` 実行時に注入される、最初のターンの起動前奏コンテキストを制御します。 + +```json5 +{ + agents: { + defaults: { + startupContext: { + enabled: true, + applyOn: ["new", "reset"], + dailyMemoryDays: 2, + maxFileBytes: 16384, + maxFileChars: 1200, + maxTotalChars: 2800, + }, + }, + }, +} +``` + +#### `agents.defaults.contextLimits` + +制限付きランタイムコンテキストサーフェスの共有デフォルトです。 + +```json5 +{ + agents: { + defaults: { + contextLimits: { + memoryGetMaxChars: 12000, + memoryGetDefaultLines: 120, + toolResultMaxChars: 16000, + postCompactionMaxChars: 1800, + }, + }, + }, +} +``` + +- `memoryGetMaxChars`: 切り詰めメタデータと継続通知が追加される前の、デフォルトの `memory_get` 抜粋上限。 +- `memoryGetDefaultLines`: `lines` を省略した場合の、デフォルトの `memory_get` 行ウィンドウ。 +- `toolResultMaxChars`: 永続化される結果とオーバーフロー回復に使われる、ライブ tool result 上限。 +- `postCompactionMaxChars`: Compaction 後の再注入時に使われる AGENTS.md 抜粋上限。 + +#### `agents.list[].contextLimits` + +共有 `contextLimits` ノブの agent ごとのオーバーライドです。省略されたフィールドは `agents.defaults.contextLimits` から継承されます。 + +```json5 +{ + agents: { + defaults: { + contextLimits: { + memoryGetMaxChars: 12000, + toolResultMaxChars: 16000, + }, + }, + list: [ + { + id: "tiny-local", + contextLimits: { + memoryGetMaxChars: 6000, + toolResultMaxChars: 8000, + }, + }, + ], + }, +} +``` + +#### `skills.limits.maxSkillsPromptChars` + +system prompt に注入されるコンパクトな Skills 一覧のグローバル上限です。 +これは必要に応じて `SKILL.md` ファイルを読むことには影響しません。 + +```json5 +{ + skills: { + limits: { + maxSkillsPromptChars: 18000, + }, + }, +} +``` + +#### `agents.list[].skillsLimits.maxSkillsPromptChars` + +Skills prompt 予算の agent ごとのオーバーライドです。 + +```json5 +{ + agents: { + list: [ + { + id: "tiny-local", + skillsLimits: { + maxSkillsPromptChars: 6000, + }, + }, + ], + }, +} +``` + ### `agents.defaults.imageMaxDimensionPx` -provider 呼び出し前に transcript/tool の画像ブロックで許可される、画像の長辺の最大ピクセルサイズです。 +provider 呼び出し前に、transcript/tool の画像ブロックで最長辺に適用される最大ピクセルサイズです。 デフォルト: `1200`。 -値を小さくすると、通常は vision token 使用量と、スクリーンショットが多い実行でのリクエストペイロードサイズが減少します。 +通常、値を小さくするとスクリーンショットの多い実行で vision token 使用量とリクエスト payload サイズが減ります。 値を大きくすると、より多くの視覚的詳細が保持されます。 ```json5 @@ -1002,7 +1126,7 @@ provider 呼び出し前に transcript/tool の画像ブロックで許可され ### `agents.defaults.userTimezone` -system prompt コンテキスト用のタイムゾーンです（メッセージのタイムスタンプではありません）。ホストのタイムゾーンにフォールバックします。 +system prompt コンテキスト用のタイムゾーンです（メッセージタイムスタンプ用ではありません）。未設定の場合はホストのタイムゾーンにフォールバックします。 ```json5 { @@ -1012,7 +1136,7 @@ system prompt コンテキスト用のタイムゾーンです（メッセージ ### `agents.defaults.timeFormat` -system prompt 内の時刻形式です。デフォルト: `auto`（OS 設定）。 +system prompt 内の時刻形式です。デフォルト: `auto`（OS の設定）。 ```json5 { @@ -1050,7 +1174,7 @@ system prompt 内の時刻形式です。デフォルト: `auto`（OS 設定） primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // グローバルなデフォルト provider params embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1070,48 +1194,47 @@ system prompt 内の時刻形式です。デフォルト: `auto`（OS 設定） ``` - `model`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - 文字列形式は primary model のみを設定します。 - - オブジェクト形式は primary に加えて順序付きのフェイルオーバー model を設定します。 + - 文字列形式はプライマリモデルのみを設定します。 + - オブジェクト形式は、プライマリに加えて順序付きのフェイルオーバーモデルを設定します。 - `imageModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - `image` tool パスで、その vision-model 設定として使用されます。 - - 選択済み/デフォルトの model が画像入力を受け付けられない場合のフォールバックルーティングにも使用されます。 + - `image` tool パスで、その vision-model 設定として使われます。 + - 選択された/デフォルトの model が画像入力を受け付けられない場合のフォールバックルーティングにも使われます。 - `imageGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - 共有の画像生成機能と、今後の画像生成を行う tool/plugin サーフェスで使用されます。 - - 一般的な値: Gemini ネイティブ画像生成には `google/gemini-3.1-flash-image-preview`、fal には `fal/fal-ai/flux/dev`、OpenAI Images には `openai/gpt-image-1`。 - - provider/model を直接選択する場合は、一致する provider の auth/API key も設定してください（たとえば `google/*` には `GEMINI_API_KEY` または `GOOGLE_API_KEY`、`openai/*` には `OPENAI_API_KEY`、`fal/*` には `FAL_KEY`）。 - - 省略した場合でも、`image_generate` は auth 済み provider のデフォルトを推測できます。まず現在のデフォルト provider を試し、その後、残りの登録済み画像生成 provider を provider-id 順に試します。 + - 共有の画像生成機能と、今後追加される画像生成用の tool/plugin サーフェスで使われます。 + - 代表的な値: Gemini ネイティブ画像生成用の `google/gemini-3.1-flash-image-preview`、fal 用の `fal/fal-ai/flux/dev`、または OpenAI Images 用の `openai/gpt-image-1`。 + - provider/model を直接選択する場合は、対応する provider の auth/API キーも設定してください（例: `google/*` には `GEMINI_API_KEY` または `GOOGLE_API_KEY`、`openai/*` には `OPENAI_API_KEY`、`fal/*` には `FAL_KEY`）。 + - 省略しても、`image_generate` は auth に裏付けられた provider デフォルトを推論できます。まず現在のデフォルト provider を試し、その後、残りの登録済み画像生成 provider を provider-id 順で試します。 - `musicGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - 共有の音楽生成機能と、組み込みの `music_generate` tool で使用されます。 - - 一般的な値: `google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`、または `minimax/music-2.5+`。 - - 省略した場合でも、`music_generate` は auth 済み provider のデフォルトを推測できます。まず現在のデフォルト provider を試し、その後、残りの登録済み音楽生成 provider を provider-id 順に試します。 - - provider/model を直接選択する場合は、一致する provider の auth/API key も設定してください。 + - 共有の音楽生成機能と、組み込みの `music_generate` tool で使われます。 + - 代表的な値: `google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`、または `minimax/music-2.5+`。 + - 省略しても、`music_generate` は auth に裏付けられた provider デフォルトを推論できます。まず現在のデフォルト provider を試し、その後、残りの登録済み音楽生成 provider を provider-id 順で試します。 + - provider/model を直接選択する場合は、対応する provider の auth/API キーも設定してください。 - `videoGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - 共有の動画生成機能と、組み込みの `video_generate` tool で使用されます。 - - 一般的な値: `qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`、または `qwen/wan2.7-r2v`。 - - 省略した場合でも、`video_generate` は auth 済み provider のデフォルトを推測できます。まず現在のデフォルト provider を試し、その後、残りの登録済み動画生成 provider を provider-id 順に試します。 - - provider/model を直接選択する場合は、一致する provider の auth/API key も設定してください。 + - 共有の動画生成機能と、組み込みの `video_generate` tool で使われます。 + - 代表的な値: `qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`、または `qwen/wan2.7-r2v`。 + - 省略しても、`video_generate` は auth に裏付けられた provider デフォルトを推論できます。まず現在のデフォルト provider を試し、その後、残りの登録済み動画生成 provider を provider-id 順で試します。 + - provider/model を直接選択する場合は、対応する provider の auth/API キーも設定してください。 - bundled の Qwen 動画生成 provider は、最大 1 本の出力動画、1 枚の入力画像、4 本の入力動画、10 秒の長さ、および provider レベルの `size`、`aspectRatio`、`resolution`、`audio`、`watermark` オプションをサポートします。 - `pdfModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - `pdf` tool の model ルーティングに使用されます。 - - 省略した場合、PDF tool は `imageModel` にフォールバックし、その後、解決済みの session/デフォルト model にフォールバックします。 -- `pdfMaxBytesMb`: `pdf` tool の呼び出し時に `maxBytesMb` が渡されない場合の、デフォルト PDF サイズ制限です。 -- `pdfMaxPages`: `pdf` tool の抽出フォールバックモードで考慮されるデフォルトの最大ページ数です。 + - `pdf` tool で model ルーティングに使われます。 + - 省略した場合、PDF tool は `imageModel` にフォールバックし、その後、解決済みのセッション/デフォルト model にフォールバックします。 +- `pdfMaxBytesMb`: 呼び出し時に `maxBytesMb` が渡されない場合の、`pdf` tool のデフォルト PDF サイズ上限。 +- `pdfMaxPages`: `pdf` tool の抽出フォールバックモードで考慮されるページ数のデフォルト上限。 - `verboseDefault`: agent のデフォルト verbose レベル。値: `"off"`、`"on"`、`"full"`。デフォルト: `"off"`。 - `elevatedDefault`: agent のデフォルト elevated-output レベル。値: `"off"`、`"on"`、`"ask"`、`"full"`。デフォルト: `"on"`。 -- `model.primary`: 形式は `provider/model`（例: `openai/gpt-5.4`）。provider を省略すると、OpenClaw はまずエイリアスを試し、次にその正確な model id に対する一意の configured-provider 一致を試し、それでもだめな場合にのみ設定済みデフォルト provider へフォールバックします（非推奨の互換動作なので、明示的な `provider/model` を推奨します）。その provider が設定済みデフォルト model をもう提供していない場合、OpenClaw は古くなった削除済み provider のデフォルトを表面化する代わりに、最初の configured provider/model にフォールバックします。 -- `models`: `/model` 用の設定済み model カタログおよび allowlist です。各エントリには `alias`（ショートカット）と `params`（provider 固有。たとえば `temperature`、`maxTokens`、`cacheRetention`、`context1m`）を含めることができます。 -- `params`: すべての model に適用されるグローバルなデフォルト provider パラメータです。`agents.defaults.params` に設定します（例: `{ cacheRetention: "long" }`）。 -- `params` のマージ優先順位（設定）: `agents.defaults.params`（グローバルベース）は `agents.defaults.models["provider/model"].params`（model ごと）で上書きされ、その後 `agents.list[].params`（一致する agent id）がキーごとに上書きします。詳細は [Prompt Caching](/ja-JP/reference/prompt-caching) を参照してください。 -- `embeddedHarness`: デフォルトの低レベル埋め込み agent ランタイムポリシーです。`runtime: "auto"` を使うと、登録済み plugin harness が対応 model を引き受けられます。`runtime: "pi"` で組み込み PI harness を強制し、`runtime: "codex"` のように登録済み harness id も指定できます。自動 PI フォールバックを無効にするには `fallback: "none"` を設定します。 -- これらのフィールドを変更する設定書き込み機能（たとえば `/models set`、`/models set-image`、fallback の追加/削除コマンド）は、正規のオブジェクト形式で保存し、可能な限り既存の fallback リストを保持します。 -- `maxConcurrent`: session をまたいだ並列 agent 実行数の最大値です（各 session 自体は直列化されます）。デフォルト: 4。 +- `model.primary`: 形式は `provider/model`（例: `openai/gpt-5.4`）。provider を省略すると、OpenClaw はまず alias を試し、次にその正確な model id に一致する一意の configured-provider を試し、それでもだめなら設定済みのデフォルト provider にフォールバックします（非推奨の互換挙動なので、明示的な `provider/model` を推奨します）。その provider が設定済みデフォルト model をもはや公開していない場合、OpenClaw は古くなった削除済み provider のデフォルトを出す代わりに、最初の設定済み provider/model にフォールバックします。 +- `models`: `/model` 用の設定済み model カタログ兼許可リスト。各エントリには `alias`（短縮名）と `params`（provider 固有。例: `temperature`、`maxTokens`、`cacheRetention`、`context1m`）を含められます。 +- `params`: すべての models に適用されるグローバルなデフォルト provider パラメータ。`agents.defaults.params` に設定します（例: `{ cacheRetention: "long" }`）。 +- `params` のマージ優先順位（設定）: `agents.defaults.params`（グローバルベース）が `agents.defaults.models["provider/model"].params`（model ごと）で上書きされ、その後 `agents.list[].params`（一致する agent id）がキーごとに上書きします。詳細は [Prompt Caching](/ja-JP/reference/prompt-caching) を参照してください。 +- `embeddedHarness`: デフォルトの低レベル埋め込み agent ランタイムポリシー。`runtime: "auto"` を使うと、登録済み plugin harness がサポート対象 model を引き受けられるようになり、`runtime: "pi"` で組み込み PI harness を強制し、`runtime: "codex"` のような登録済み harness id も指定できます。自動 PI フォールバックを無効にするには `fallback: "none"` を設定します。 +- これらのフィールドを変更する設定ライター（たとえば `/models set`、`/models set-image`、fallback の追加/削除コマンド）は、正規のオブジェクト形式で保存し、可能な限り既存の fallback リストを保持します。 +- `maxConcurrent`: セッションをまたいで並列実行できる agent run の最大数です（各セッション自体は引き続き直列化されます）。デフォルト: 4。 ### `agents.defaults.embeddedHarness` `embeddedHarness` は、埋め込み agent ターンをどの低レベル executor で実行するかを制御します。 -ほとんどのデプロイではデフォルトの `{ runtime: "auto", fallback: "pi" }` のままで問題ありません。 -bundled の -Codex app-server harness のように、信頼できる plugin がネイティブ harness を提供する場合に使用します。 +ほとんどの環境では、デフォルトの `{ runtime: "auto", fallback: "pi" }` のままで構いません。 +bundled の Codex app-server harness のように、信頼できる plugin がネイティブ harness を提供する場合に使ってください。 ```json5 { @@ -1127,13 +1250,13 @@ Codex app-server harness のように、信頼できる plugin がネイティ } ``` -- `runtime`: `"auto"`、`"pi"`、または登録済み plugin harness id。bundled Codex Plugin は `codex` を登録します。 -- `fallback`: `"pi"` または `"none"`。`"pi"` は組み込み PI harness を互換フォールバックとして維持します。`"none"` は、plugin harness の選択が存在しない、または未対応の場合に、暗黙で PI を使用せず失敗させます。 +- `runtime`: `"auto"`、`"pi"`、または登録済み plugin harness id。bundled の Codex Plugin は `codex` を登録します。 +- `fallback`: `"pi"` または `"none"`。`"pi"` は互換性用フォールバックとして組み込み PI harness を維持します。`"none"` は、plugin harness の選択が存在しない、または未対応の場合に、黙って PI を使わず失敗させます。 - 環境変数による上書き: `OPENCLAW_AGENT_RUNTIME=` は `runtime` を上書きし、`OPENCLAW_AGENT_HARNESS_FALLBACK=none` はそのプロセスの PI フォールバックを無効にします。 -- Codex 専用デプロイでは、`model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"`、`embeddedHarness.fallback: "none"` を設定してください。 -- これは埋め込み chat harness のみを制御します。メディア生成、vision、PDF、音楽、動画、TTS は引き続きそれぞれの provider/model 設定を使用します。 +- Codex 専用環境では、`model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"`、`embeddedHarness.fallback: "none"` を設定してください。 +- これは埋め込み chat harness のみを制御します。media generation、vision、PDF、music、video、TTS は引き続きそれぞれの provider/model 設定を使います。 -**組み込みエイリアス短縮形**（model が `agents.defaults.models` にある場合のみ適用されます）: +**組み込み alias 短縮名**（model が `agents.defaults.models` にある場合のみ適用）: | Alias | Model | | ------------------- | -------------------------------------- | @@ -1146,15 +1269,15 @@ Codex app-server harness のように、信頼できる plugin がネイティ | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -設定したエイリアスは常にデフォルトより優先されます。 +設定済みの alias は常にデフォルトより優先されます。 -Z.AI GLM-4.x model は、`--thinking off` を設定するか、`agents.defaults.models["zai/"].params.thinking` を自分で定義しない限り、自動的に thinking モードを有効にします。 -Z.AI model は、tool 呼び出しストリーミングのためにデフォルトで `tool_stream` を有効にします。無効にするには `agents.defaults.models["zai/"].params.tool_stream` を `false` に設定してください。 -Anthropic Claude 4.6 model は、明示的な thinking レベルが設定されていない場合、デフォルトで `adaptive` thinking を使用します。 +Z.AI の GLM-4.x models は、`--thinking off` を設定するか、`agents.defaults.models["zai/"].params.thinking` を自分で定義しない限り、自動的に thinking mode を有効にします。 +Z.AI models は、tool call ストリーミングのためにデフォルトで `tool_stream` を有効にします。無効にするには `agents.defaults.models["zai/"].params.tool_stream` を `false` に設定してください。 +Anthropic Claude 4.6 models は、明示的な thinking レベルが設定されていない場合、デフォルトで `adaptive` thinking を使用します。 ### `agents.defaults.cliBackends` -テキスト専用フォールバック実行用の任意の CLI バックエンドです（tool 呼び出しなし）。API provider が失敗したときのバックアップとして便利です。 +テキスト専用のフォールバック実行用の任意の CLI バックエンドです（tool call なし）。API provider が失敗したときのバックアップとして役立ちます。 ```json5 { @@ -1183,12 +1306,12 @@ Anthropic Claude 4.6 model は、明示的な thinking レベルが設定され ``` - CLI バックエンドはテキスト優先です。tools は常に無効です。 -- `sessionArg` が設定されている場合は session をサポートします。 +- `sessionArg` が設定されている場合はセッションをサポートします。 - `imageArg` がファイルパスを受け付ける場合は画像パススルーをサポートします。 ### `agents.defaults.systemPromptOverride` -OpenClaw が組み立てた system prompt 全体を固定文字列で置き換えます。デフォルトレベル（`agents.defaults.systemPromptOverride`）または agent ごと（`agents.list[].systemPromptOverride`）に設定します。agent ごとの値が優先されます。空または空白のみの値は無視されます。制御された prompt 実験に便利です。 +OpenClaw が組み立てた system prompt 全体を固定文字列で置き換えます。デフォルトレベル（`agents.defaults.systemPromptOverride`）または agent ごと（`agents.list[].systemPromptOverride`）で設定します。agent ごとの値が優先されます。空または空白のみの値は無視されます。制御された prompt 実験に役立ちます。 ```json5 { @@ -1229,15 +1352,15 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 } ``` -- `every`: 期間文字列（ms/s/m/h）。デフォルト: `30m`（API-key 認証）または `1h`（OAuth 認証）。無効にするには `0m` を設定します。 -- `includeSystemPromptSection`: false の場合、system prompt から Heartbeat セクションを省略し、ブートストラップコンテキストへの `HEARTBEAT.md` の注入もスキップします。デフォルト: `true`。 -- `suppressToolErrorWarnings`: true の場合、Heartbeat 実行中の tool エラー警告ペイロードを抑制します。 -- `timeoutSeconds`: Heartbeat の agent ターンが中断されるまでに許可される最大秒数です。未設定の場合は `agents.defaults.timeoutSeconds` を使用します。 -- `directPolicy`: 直接/DM 配信ポリシー。`allow`（デフォルト）は直接ターゲット配信を許可します。`block` は直接ターゲット配信を抑制し、`reason=dm-blocked` を出力します。 -- `lightContext`: true の場合、Heartbeat 実行は軽量なブートストラップコンテキストを使用し、workspace ブートストラップファイルから `HEARTBEAT.md` のみを保持します。 -- `isolatedSession`: true の場合、各 Heartbeat は過去の会話履歴のない新しい session で実行されます。Cron の `sessionTarget: "isolated"` と同じ分離パターンです。Heartbeat ごとの token コストを約 100K から約 2〜5K token に削減します。 -- agent ごと: `agents.list[].heartbeat` を設定します。いずれかの agent が `heartbeat` を定義している場合、Heartbeat を実行するのは**それらの agent のみ**です。 -- Heartbeat は完全な agent ターンを実行します — 間隔を短くするとより多くの token を消費します。 +- `every`: 期間文字列（ms/s/m/h）。デフォルト: `30m`（API-key auth）または `1h`（OAuth auth）。無効にするには `0m` を設定します。 +- `includeSystemPromptSection`: false の場合、system prompt から Heartbeat セクションを省略し、bootstrap コンテキストへの `HEARTBEAT.md` 注入もスキップします。デフォルト: `true`。 +- `suppressToolErrorWarnings`: true の場合、Heartbeat 実行中の tool error 警告 payload を抑制します。 +- `timeoutSeconds`: 中断されるまでに Heartbeat agent ターンに許可される最大秒数。未設定の場合は `agents.defaults.timeoutSeconds` を使います。 +- `directPolicy`: direct/DM 配信ポリシー。`allow`（デフォルト）は direct-target 配信を許可します。`block` は direct-target 配信を抑制し、`reason=dm-blocked` を出力します。 +- `lightContext`: true の場合、Heartbeat 実行は軽量 bootstrap コンテキストを使い、workspace bootstrap ファイルから `HEARTBEAT.md` のみを保持します。 +- `isolatedSession`: true の場合、各 Heartbeat は以前の会話履歴がない新しいセッションで実行されます。Cron の `sessionTarget: "isolated"` と同じ分離パターンです。Heartbeat あたりの token コストを約 100K から約 2〜5K token に削減します。 +- agent ごと: `agents.list[].heartbeat` を設定します。いずれかの agent が `heartbeat` を定義している場合、Heartbeat を実行するのは**その agent だけ**です。 +- Heartbeat は完全な agent ターンを実行するため、間隔を短くするとより多くの token を消費します。 ### `agents.defaults.compaction` @@ -1247,19 +1370,19 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // 登録済み Compaction provider Plugin の id（任意） timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "デプロイ ID、チケット ID、host:port の組み合わせを正確に保持してください。", // identifierPolicy=custom のときに使用 + postCompactionSections: ["Session Startup", "Red Lines"], // [] で再注入を無効化 + model: "openrouter/anthropic/claude-sonnet-4-6", // Compaction 専用の model オーバーライド（任意） + notifyUser: true, // Compaction 開始時に簡単な通知を送信（デフォルト: false） memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "セッションはまもなく Compaction に入ります。永続的な記憶を今すぐ保存してください。", + prompt: "持続的に残すべきメモがあれば memory/YYYY-MM-DD.md に書き込んでください。保存するものがなければ、正確なサイレントトークン NO_REPLY で応答してください。", }, }, }, @@ -1267,19 +1390,19 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 } ``` -- `mode`: `default` または `safeguard`（長い履歴に対するチャンク化要約）。[Compaction](/ja-JP/concepts/compaction) を参照してください。 -- `provider`: 登録済み compaction provider Plugin の id。設定すると、組み込みの LLM 要約の代わりに provider の `summarize()` が呼び出されます。失敗時は組み込みにフォールバックします。provider を設定すると `mode: "safeguard"` が強制されます。[Compaction](/ja-JP/concepts/compaction) を参照してください。 -- `timeoutSeconds`: 1 回の compaction 操作に OpenClaw が許可する最大秒数。デフォルト: `900`。 -- `identifierPolicy`: `strict`（デフォルト）、`off`、または `custom`。`strict` は、compaction 要約時に組み込みの不透明識別子保持ガイダンスを先頭に追加します。 -- `identifierInstructions`: `identifierPolicy=custom` のときに使用される、任意のカスタム識別子保持テキスト。 -- `postCompactionSections`: compaction 後に再注入する任意の `AGENTS.md` H2/H3 セクション名。デフォルトは `["Session Startup", "Red Lines"]` です。再注入を無効にするには `[]` を設定します。未設定、または明示的にそのデフォルトの組み合わせが設定されている場合、古い `Every Session`/`Safety` 見出しもレガシーフォールバックとして受け付けられます。 -- `model`: compaction 要約専用の任意の `provider/model-id` 上書きです。メイン session は 1 つの model のままにしつつ、compaction 要約だけ別の model で実行したい場合に使用します。未設定の場合、compaction は session の primary model を使用します。 -- `notifyUser`: `true` のとき、compaction 開始時にユーザーへ短い通知を送信します（例: 「Compacting context...」）。compaction を無言に保つため、デフォルトでは無効です。 -- `memoryFlush`: 自動 compaction 前に永続メモリを保存するための、無言の agent ターンです。workspace が読み取り専用の場合はスキップされます。 +- `mode`: `default` または `safeguard`（長い履歴向けのチャンク化された要約）。[Compaction](/ja-JP/concepts/compaction) を参照してください。 +- `provider`: 登録済みの Compaction provider Plugin の id。設定すると、組み込み LLM 要約の代わりに、その provider の `summarize()` が呼び出されます。失敗時は組み込み方式にフォールバックします。provider を設定すると `mode: "safeguard"` が強制されます。[Compaction](/ja-JP/concepts/compaction) を参照してください。 +- `timeoutSeconds`: OpenClaw が中断するまでに、1 回の Compaction 操作に許可される最大秒数。デフォルト: `900`。 +- `identifierPolicy`: `strict`（デフォルト）、`off`、または `custom`。`strict` は、Compaction 要約中に組み込みの不透明識別子保持ガイダンスを先頭に追加します。 +- `identifierInstructions`: `identifierPolicy=custom` のときに使われる、任意のカスタム識別子保持テキスト。 +- `postCompactionSections`: Compaction 後に再注入する任意の AGENTS.md の H2/H3 セクション名。デフォルトは `["Session Startup", "Red Lines"]` です。`[]` を設定すると再注入を無効にします。未設定、または明示的にそのデフォルトの組み合わせを設定した場合、従来互換のフォールバックとして古い `Every Session`/`Safety` 見出しも受け付けます。 +- `model`: Compaction 要約専用の任意の `provider/model-id` オーバーライド。メインセッションは 1 つの model を維持しつつ、Compaction 要約は別の model で実行したい場合に使います。未設定の場合、Compaction はセッションのプライマリ model を使います。 +- `notifyUser`: `true` の場合、Compaction 開始時にユーザーへ短い通知を送ります（例: 「コンテキストを Compaction 中...」）。デフォルトでは、Compaction をサイレントに保つため無効です。 +- `memoryFlush`: 自動 Compaction 前に永続メモリを保存するサイレントな agent ターンです。workspace が読み取り専用の場合はスキップされます。 ### `agents.defaults.contextPruning` -LLM へ送信する前に、メモリ内コンテキストから**古い tool 結果**を刈り込みます。ディスク上の session 履歴は**変更しません**。 +LLM に送信する前に、メモリ内コンテキストから**古い tool result** を削減します。ディスク上のセッション履歴は**変更しません**。 ```json5 { @@ -1293,7 +1416,7 @@ LLM へ送信する前に、メモリ内コンテキストから**古い tool hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[古い tool result の内容は削除されました]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1303,19 +1426,19 @@ LLM へ送信する前に、メモリ内コンテキストから**古い tool -- `mode: "cache-ttl"` は刈り込みパスを有効にします。 -- `ttl` は、最後にキャッシュへ触れてから次に刈り込みを再実行できる頻度を制御します。 -- 刈り込みは、まず大きすぎる tool 結果をソフトトリムし、その後必要に応じて古い tool 結果をハードクリアします。 +- `mode: "cache-ttl"` は pruning パスを有効にします。 +- `ttl` は、最後のキャッシュ更新後に pruning を再実行できる頻度を制御します。 +- pruning は、まず大きすぎる tool result をソフトトリムし、その後必要に応じて古い tool result を完全クリアします。 -**ソフトトリム** は先頭 + 末尾を保持し、中間に `...` を挿入します。 +**soft-trim** は先頭と末尾を保持し、中間に `...` を挿入します。 -**ハードクリア** は、tool 結果全体をプレースホルダーに置き換えます。 +**hard-clear** は tool result 全体をプレースホルダーに置き換えます。 注意: -- 画像ブロックはトリム/クリアされません。 -- 比率はトークン数の正確な値ではなく、文字数ベース（概算）です。 -- `keepLastAssistants` より少ない assistant メッセージしか存在しない場合、刈り込みはスキップされます。 +- 画像ブロックは切り詰め/クリアされません。 +- 比率は文字数ベース（概算）であり、正確な token 数ではありません。 +- assistant メッセージが `keepLastAssistants` 未満の場合、pruning はスキップされます。 @@ -1338,12 +1461,12 @@ LLM へ送信する前に、メモリ内コンテキストから**古い tool ``` - Telegram 以外の channel では、ブロック返信を有効にするには明示的な `*.blockStreaming: true` が必要です。 -- channel ごとの上書き: `channels..blockStreamingCoalesce`（およびアカウントごとのバリアント）。Signal/Slack/Discord/Google Chat のデフォルトは `minChars: 1500` です。 -- `humanDelay`: ブロック返信間のランダムな待機。`natural` = 800–2500ms。agent ごとの上書き: `agents.list[].humanDelay`。 +- channel ごとのオーバーライド: `channels..blockStreamingCoalesce`（およびアカウントごとのバリアント）。Signal/Slack/Discord/Google Chat のデフォルトは `minChars: 1500` です。 +- `humanDelay`: ブロック返信間のランダムな待機時間。`natural` = 800〜2500ms。agent ごとのオーバーライド: `agents.list[].humanDelay`。 -動作とチャンク分割の詳細は [Streaming](/ja-JP/concepts/streaming) を参照してください。 +動作とチャンク化の詳細は [Streaming](/ja-JP/concepts/streaming) を参照してください。 -### 入力中インジケーター +### タイピングインジケーター ```json5 { @@ -1356,8 +1479,8 @@ LLM へ送信する前に、メモリ内コンテキストから**古い tool } ``` -- デフォルト: ダイレクトチャット/mention では `instant`、mention されていないグループチャットでは `message`。 -- session ごとの上書き: `session.typingMode`、`session.typingIntervalSeconds`。 +- デフォルト: ダイレクトチャット/メンションでは `instant`、メンションされていないグループチャットでは `message`。 +- セッションごとのオーバーライド: `session.typingMode`、`session.typingIntervalSeconds`。 [Typing Indicators](/ja-JP/concepts/typing-indicators) を参照してください。 @@ -1411,7 +1534,7 @@ LLM へ送信する前に、メモリ内コンテキストから**古い tool identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // SecretRef / インライン内容もサポート: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1460,42 +1583,42 @@ LLM へ送信する前に、メモリ内コンテキストから**古い tool } ``` - + **バックエンド:** - `docker`: ローカル Docker ランタイム（デフォルト） -- `ssh`: 汎用 SSH ベースのリモートランタイム +- `ssh`: 汎用 SSH バックのリモートランタイム - `openshell`: OpenShell ランタイム -`backend: "openshell"` を選択すると、ランタイム固有の設定は +`backend: "openshell"` を選択した場合、ランタイム固有の設定は `plugins.entries.openshell.config` に移ります。 **SSH バックエンド設定:** - `target`: `user@host[:port]` 形式の SSH ターゲット - `command`: SSH クライアントコマンド（デフォルト: `ssh`） -- `workspaceRoot`: スコープごとの workspace に使用される絶対リモートルート +- `workspaceRoot`: スコープごとの workspace に使う絶対リモートルート - `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSH に渡される既存のローカルファイル -- `identityData` / `certificateData` / `knownHostsData`: OpenClaw がランタイム時に一時ファイルへ実体化する、インライン内容または SecretRef +- `identityData` / `certificateData` / `knownHostsData`: OpenClaw がランタイム時に一時ファイルへ実体化するインライン内容または SecretRef - `strictHostKeyChecking` / `updateHostKeys`: OpenSSH のホストキー方針ノブ **SSH 認証の優先順位:** -- `identityData` は `identityFile` より優先されます -- `certificateData` は `certificateFile` より優先されます -- `knownHostsData` は `knownHostsFile` より優先されます -- SecretRef ベースの `*Data` 値は、sandbox session 開始前にアクティブな secrets ランタイムスナップショットから解決されます +- `identityData` は `identityFile` より優先 +- `certificateData` は `certificateFile` より優先 +- `knownHostsData` は `knownHostsFile` より優先 +- SecretRef バックの `*Data` 値は、sandbox セッション開始前にアクティブな secrets ランタイムスナップショットから解決されます **SSH バックエンドの動作:** -- 作成または再作成の後に、リモート workspace を 1 回だけシードします -- その後は、リモート SSH workspace を正規として維持します -- `exec`、ファイル tools、メディアパスを SSH 経由でルーティングします -- リモート側の変更は自動ではホストへ同期されません +- 作成または再作成後に、リモート workspace を 1 回だけシードします +- その後はリモート SSH workspace を正規の状態として維持します +- `exec`、ファイル tools、media パスを SSH 経由でルーティングします +- リモート変更は自動ではホストへ同期されません - sandbox browser コンテナはサポートしません -**Workspace アクセス:** +**workspace アクセス:** - `none`: `~/.openclaw/sandboxes` 配下のスコープごとの sandbox workspace - `ro`: `/workspace` に sandbox workspace、`/agent` に agent workspace を読み取り専用でマウント @@ -1503,9 +1626,9 @@ LLM へ送信する前に、メモリ内コンテキストから**古い tool **スコープ:** -- `session`: session ごとのコンテナ + workspace +- `session`: セッションごとのコンテナ + workspace - `agent`: agent ごとに 1 つのコンテナ + workspace（デフォルト） -- `shared`: 共有コンテナと workspace（session 間分離なし） +- `shared`: 共有コンテナと共有 workspace（セッション間分離なし） **OpenShell Plugin 設定:** @@ -1535,33 +1658,32 @@ LLM へ送信する前に、メモリ内コンテキストから**古い tool **OpenShell モード:** -- `mirror`: exec 前にローカルからリモートへシードし、exec 後に同期して戻します。ローカル workspace が正規のまま維持されます -- `remote`: sandbox 作成時に 1 回だけリモートへシードし、その後はリモート workspace を正規として維持します +- `mirror`: 実行前にローカルからリモートへシードし、実行後に同期し戻します。ローカル workspace が正規状態のまま維持されます +- `remote`: sandbox 作成時に 1 回だけリモートをシードし、その後はリモート workspace を正規状態として維持します -`remote` モードでは、シード後に OpenClaw 外で行われたホストローカルの編集は、自動では sandbox に同期されません。 -転送は SSH で OpenShell sandbox に入りますが、sandbox のライフサイクルと任意の mirror 同期は Plugin が管理します。 +`remote` モードでは、シード後に OpenClaw 外で行われたホストローカル編集は、自動では sandbox に同期されません。 +転送は OpenShell sandbox への SSH ですが、sandbox のライフサイクルと任意の mirror 同期は Plugin が管理します。 **`setupCommand`** はコンテナ作成後に 1 回だけ実行されます（`sh -lc` 経由）。ネットワーク外向き通信、書き込み可能なルート、root ユーザーが必要です。 -**コンテナのデフォルトは `network: "none"`** です — agent が外向きアクセスを必要とする場合は `"bridge"`（またはカスタム bridge network）に設定してください。 +**コンテナのデフォルトは `network: "none"`** です。agent に外向きアクセスが必要な場合は `"bridge"`（またはカスタム bridge network）に設定してください。 `"host"` はブロックされます。`"container:"` は、明示的に -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（緊急用） -を設定しない限り、デフォルトでブロックされます。 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` を設定しない限り（非常時用）デフォルトでブロックされます。 -**受信添付ファイル** は、アクティブな workspace の `media/inbound/*` にステージングされます。 +**受信添付ファイル** は、アクティブな workspace の `media/inbound/*` にステージされます。 **`docker.binds`** は追加のホストディレクトリをマウントします。グローバルと agent ごとの binds はマージされます。 -**Sandbox 化された browser**（`sandbox.browser.enabled`）: コンテナ内で動作する Chromium + CDP。noVNC URL は system prompt に注入されます。`openclaw.json` で `browser.enabled` を必要としません。 -noVNC のオブザーバーアクセスはデフォルトで VNC 認証を使用し、OpenClaw は共有 URL にパスワードを露出する代わりに、短命な token URL を出力します。 +**sandbox 化された browser**（`sandbox.browser.enabled`）: コンテナ内の Chromium + CDP。noVNC URL は system prompt に注入されます。`openclaw.json` で `browser.enabled` は不要です。 +noVNC の閲覧専用アクセスはデフォルトで VNC 認証を使用し、OpenClaw は共有 URL にパスワードを露出させる代わりに短命トークン URL を発行します。 -- `allowHostControl: false`（デフォルト）は、sandbox 化された session がホスト browser を対象にすることをブロックします。 -- `network` のデフォルトは `openclaw-sandbox-browser`（専用 bridge network）です。グローバル bridge 接続を明示的に望む場合にのみ `bridge` に設定してください。 -- `cdpSourceRange` は、任意で CDP の流入をコンテナ境界で CIDR 範囲に制限します（例: `172.21.0.1/32`）。 -- `sandbox.browser.binds` は、追加のホストディレクトリを sandbox browser コンテナのみにマウントします。設定されている場合（`[]` を含む）、browser コンテナでは `docker.binds` を置き換えます。 -- 起動時のデフォルトは `scripts/sandbox-browser-entrypoint.sh` で定義されており、コンテナホスト向けに調整されています: +- `allowHostControl: false`（デフォルト）は、sandbox 化されたセッションがホスト browser を対象にすることをブロックします。 +- `network` のデフォルトは `openclaw-sandbox-browser`（専用 bridge network）です。グローバル bridge 接続性が明示的に必要な場合のみ `bridge` に設定してください。 +- `cdpSourceRange` は、必要に応じて CDP の受信接続をコンテナ境界で CIDR 範囲（例: `172.21.0.1/32`）に制限します。 +- `sandbox.browser.binds` は、追加のホストディレクトリを sandbox browser コンテナにのみマウントします。設定されると（`[]` を含む）、browser コンテナでは `docker.binds` の代わりにこれが使われます。 +- 起動時のデフォルトは `scripts/sandbox-browser-entrypoint.sh` で定義され、コンテナホスト向けに調整されています: - `--remote-debugging-address=127.0.0.1` - - `--remote-debugging-port=` + - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` @@ -1578,29 +1700,28 @@ noVNC のオブザーバーアクセスはデフォルトで VNC 認証を使用 - `--metrics-recording-only` - `--disable-extensions`（デフォルトで有効） - `--disable-3d-apis`、`--disable-software-rasterizer`、`--disable-gpu` は - デフォルトで有効で、WebGL/3D の使用で必要な場合は + デフォルトで有効であり、WebGL/3D の使用で必要な場合は `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` で無効化できます。 - - ワークフローが拡張機能に依存する場合は - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` で拡張機能を再有効化できます。 + - ワークフローで extensions が必要な場合は + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` で再有効化できます。 - `--renderer-process-limit=2` は `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` で変更できます。Chromium の - デフォルトのプロセス制限を使うには `0` を設定します。 + デフォルトプロセス上限を使うには `0` を設定してください。 - さらに、`noSandbox` が有効な場合は `--no-sandbox` と `--disable-setuid-sandbox`。 - - これらのデフォルトはコンテナイメージのベースラインです。コンテナのデフォルトを変更するには、 - カスタム entrypoint を持つカスタム browser イメージを使用してください。 + - これらのデフォルトはコンテナイメージのベースラインです。コンテナのデフォルトを変更するには、カスタム entrypoint を持つカスタム browser イメージを使用してください。 -browser sandboxing と `sandbox.docker.binds` は Docker 専用です。 +browser sandbox 化と `sandbox.docker.binds` は Docker 専用です。 イメージをビルド: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # メイン sandbox イメージ +scripts/sandbox-browser-setup.sh # 任意の browser イメージ ``` -### `agents.list`（agent ごとの上書き） +### `agents.list`（agent ごとのオーバーライド） ```json5 { @@ -1612,13 +1733,13 @@ scripts/sandbox-browser-setup.sh # optional browser image name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override + model: "anthropic/claude-opus-4-6", // または { primary, fallbacks } + thinkingDefault: "high", // agent ごとの thinking レベル上書き + reasoningDefault: "on", // agent ごとの reasoning 可視性上書き + fastModeDefault: false, // agent ごとの fast mode 上書き embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + params: { cacheRetention: "none" }, // 一致する defaults.models params をキーごとに上書き + skills: ["docs-search"], // 設定時は agents.defaults.skills を置き換え identity: { name: "Samantha", theme: "helpful sloth", @@ -1650,24 +1771,24 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: 安定した agent id（必須）。 -- `default`: 複数設定されている場合は最初のものが優先されます（警告を記録）。1 つも設定されていない場合は、リストの最初のエントリがデフォルトです。 -- `model`: 文字列形式は `primary` のみを上書きし、オブジェクト形式 `{ primary, fallbacks }` は両方を上書きします（`[]` はグローバル fallback を無効化）。`primary` のみを上書きする Cron ジョブは、`fallbacks: []` を設定しない限りデフォルトの fallback を引き続き継承します。 -- `params`: `agents.defaults.models` 内の選択された model エントリにマージされる agent ごとの stream params です。`cacheRetention`、`temperature`、`maxTokens` などの agent 固有上書きを、model カタログ全体を複製せずに設定するのに使います。 -- `skills`: 任意の agent ごとの Skills 許可リスト。省略した場合、`agents.defaults.skills` が設定されていれば agent はそれを継承します。明示的なリストはデフォルトをマージせず置き換え、`[]` は Skills なしを意味します。 -- `thinkingDefault`: 任意の agent ごとのデフォルト thinking レベル（`off | minimal | low | medium | high | xhigh | adaptive`）。メッセージごとまたは session ごとの上書きが設定されていない場合、この agent の `agents.defaults.thinkingDefault` を上書きします。 -- `reasoningDefault`: 任意の agent ごとのデフォルト reasoning 可視性（`on | off | stream`）。メッセージごとまたは session ごとの reasoning 上書きが設定されていない場合に適用されます。 -- `fastModeDefault`: 任意の agent ごとの fast mode のデフォルト（`true | false`）。メッセージごとまたは session ごとの fast-mode 上書きが設定されていない場合に適用されます。 -- `embeddedHarness`: 任意の agent ごとの低レベル harness ポリシー上書き。1 つの agent だけを Codex 専用にし、他の agent はデフォルトの PI フォールバックを維持するには `{ runtime: "codex", fallback: "none" }` を使用します。 -- `runtime`: 任意の agent ごとのランタイム記述子。agent がデフォルトで ACP harness session を使用するべき場合は、`runtime.acp` デフォルト（`agent`、`backend`、`mode`、`cwd`）を持つ `type: "acp"` を使用します。 +- `default`: 複数設定されている場合は最初のものが優先されます（警告を記録）。どれも設定されていない場合は、リストの最初のエントリがデフォルトです。 +- `model`: 文字列形式は `primary` のみを上書きし、オブジェクト形式 `{ primary, fallbacks }` は両方を上書きします（`[]` はグローバル fallbacks を無効化）。`primary` のみを上書きする Cron ジョブは、`fallbacks: []` を設定しない限りデフォルトの fallbacks を引き続き継承します。 +- `params`: `agents.defaults.models` の選択された model エントリにマージされる agent ごとの stream params。model カタログ全体を複製せずに、`cacheRetention`、`temperature`、`maxTokens` などの agent 固有オーバーライドに使います。 +- `skills`: 任意の agent ごとの Skills 許可リスト。省略した場合、その agent は `agents.defaults.skills` が設定されていればそれを継承します。明示的なリストはデフォルトとマージせず置き換え、`[]` は Skills なしを意味します。 +- `thinkingDefault`: 任意の agent ごとのデフォルト thinking レベル（`off | minimal | low | medium | high | xhigh | adaptive`）。メッセージごとまたはセッションごとの上書きがない場合、この agent では `agents.defaults.thinkingDefault` を上書きします。 +- `reasoningDefault`: 任意の agent ごとのデフォルト reasoning 可視性（`on | off | stream`）。メッセージごとまたはセッションごとの reasoning 上書きがない場合に適用されます。 +- `fastModeDefault`: 任意の agent ごとの fast mode デフォルト（`true | false`）。メッセージごとまたはセッションごとの fast-mode 上書きがない場合に適用されます。 +- `embeddedHarness`: 任意の agent ごとの低レベル harness ポリシー上書き。ある 1 つの agent だけを Codex 専用にし、他の agents はデフォルトの PI フォールバックを維持するには `{ runtime: "codex", fallback: "none" }` を使います。 +- `runtime`: 任意の agent ごとのランタイム記述子。agent をデフォルトで ACP harness セッションにしたい場合は、`type: "acp"` と `runtime.acp` のデフォルト（`agent`、`backend`、`mode`、`cwd`）を使います。 - `identity.avatar`: workspace 相対パス、`http(s)` URL、または `data:` URI。 -- `identity` はデフォルトを導出します: `ackReaction` は `emoji` から、`mentionPatterns` は `name`/`emoji` から。 +- `identity` はデフォルト値を導出します: `emoji` から `ackReaction`、`name`/`emoji` から `mentionPatterns`。 - `subagents.allowAgents`: `sessions_spawn` 用の agent id 許可リスト（`["*"]` = 任意、デフォルト: 同じ agent のみ）。 -- Sandbox 継承ガード: 要求元 session が sandbox 化されている場合、`sessions_spawn` は sandbox なしで実行されるターゲットを拒否します。 -- `subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制、デフォルト: false）。 +- sandbox 継承ガード: 要求元セッションが sandbox 化されている場合、`sessions_spawn` は sandbox なしで実行されるターゲットを拒否します。 +- `subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制。デフォルト: false）。 --- -## マルチエージェントルーティング +## マルチ agent ルーティング 1 つの Gateway 内で複数の分離された agent を実行します。[Multi-Agent](/ja-JP/concepts/multi-agent) を参照してください。 @@ -1686,9 +1807,9 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### バインディングの match フィールド +### バインディング一致フィールド -- `type`（任意）: 通常のルーティングは `route`（type 未指定時のデフォルトも route）、永続的な ACP 会話バインディングは `acp`。 +- `type`（任意）: 通常のルーティングには `route`（type 省略時も route）、永続 ACP 会話バインディングには `acp` - `match.channel`（必須） - `match.accountId`（任意。`*` = 任意のアカウント、省略 = デフォルトアカウント） - `match.peer`（任意。`{ kind: direct|group|channel, id }`） @@ -1700,13 +1821,13 @@ scripts/sandbox-browser-setup.sh # optional browser image 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（正確一致、peer/guild/team なし） +4. `match.accountId`（完全一致、peer/guild/team なし） 5. `match.accountId: "*"`（channel 全体） 6. デフォルト agent 各 tier 内では、最初に一致した `bindings` エントリが優先されます。 -`type: "acp"` エントリでは、OpenClaw は正確な会話 ID（`match.channel` + account + `match.peer.id`）で解決し、上記の route バインディング tier 順序は使用しません。 +`type: "acp"` エントリについては、OpenClaw は正確な会話 ID（`match.channel` + account + `match.peer.id`）で解決し、上記の route バインディング tier 順序は使用しません。 ### agent ごとのアクセスプロファイル @@ -1829,22 +1950,22 @@ scripts/sandbox-browser-setup.sh # optional browser image }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // この token 数を超える親スレッド fork はスキップ（0 で無効） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // duration または false + maxDiskBytes: "500mb", // 任意のハード予算 + highWaterBytes: "400mb", // 任意のクリーンアップ目標 }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // 非アクティブ時の自動 unfocus のデフォルト時間（`0` で無効） + maxAgeHours: 0, // ハード最大経過時間のデフォルト時間（`0` で無効） }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // legacy（ランタイムは常に "main" を使用） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1854,37 +1975,37 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + - **`scope`**: グループチャット文脈における基本の session グループ化戦略。 - - `per-sender`（デフォルト）: channel 文脈内で、各送信者が分離された session を持ちます。 + - `per-sender`（デフォルト）: channel 文脈内で、各送信者ごとに分離された session を使います。 - `global`: channel 文脈内のすべての参加者が 1 つの session を共有します（共有コンテキストを意図する場合にのみ使用してください）。 - **`dmScope`**: DM のグループ化方法。 - - `main`: すべての DM が main session を共有します。 - - `per-peer`: channel をまたいで送信者 id ごとに分離します。 + - `main`: すべての DM がメイン session を共有します。 + - `per-peer`: channels をまたいで送信者 id ごとに分離します。 - `per-channel-peer`: channel + 送信者ごとに分離します（マルチユーザー受信箱に推奨）。 - `per-account-channel-peer`: account + channel + 送信者ごとに分離します（マルチアカウントに推奨）。 -- **`identityLinks`**: channel 間で session を共有するために、正規 id を provider 接頭辞付き peer にマッピングします。 -- **`reset`**: 主たるリセットポリシー。`daily` はローカル時刻の `atHour` にリセットし、`idle` は `idleMinutes` 経過後にリセットします。両方が設定されている場合は、先に期限切れになる方が優先されます。 -- **`resetByType`**: タイプごとの上書き（`direct`、`group`、`thread`）。レガシーな `dm` は `direct` のエイリアスとして受け付けられます。 -- **`parentForkMaxTokens`**: fork されたスレッド session を作成するときに許可される親 session の `totalTokens` 最大値（デフォルト `100000`）。 - - 親の `totalTokens` がこの値を超える場合、OpenClaw は親の transcript 履歴を継承せず、新しいスレッド session を開始します。 +- **`identityLinks`**: channel 間で session を共有するため、正規 id を provider 接頭辞付き peer にマッピングします。 +- **`reset`**: 基本のリセットポリシー。`daily` はローカル時刻の `atHour` にリセットし、`idle` は `idleMinutes` 後にリセットします。両方が設定されている場合、先に期限を迎えた方が優先されます。 +- **`resetByType`**: タイプごとのオーバーライド（`direct`、`group`、`thread`）。従来の `dm` も `direct` の alias として受け付けます。 +- **`parentForkMaxTokens`**: fork されたスレッド session を作成するときに許可される親 session の `totalTokens` 上限（デフォルト `100000`）。 + - 親の `totalTokens` がこの値を超える場合、OpenClaw は親 transcript 履歴を継承せず、新しいスレッド session を開始します。 - このガードを無効にして常に親 fork を許可するには `0` を設定します。 -- **`mainKey`**: レガシーフィールドです。ランタイムは main のダイレクトチャットバケットに常に `"main"` を使用します。 -- **`agentToAgent.maxPingPongTurns`**: agent 間のやり取り中に許可される、agent 間の返信往復ターン数の最大値です（整数、範囲: `0`–`5`）。`0` は ping-pong 連鎖を無効にします。 -- **`sendPolicy`**: `channel`、`chatType`（`direct|group|channel`、レガシーな `dm` エイリアスあり）、`keyPrefix`、または `rawKeyPrefix` で一致させます。最初の deny が優先されます。 +- **`mainKey`**: legacy フィールドです。ランタイムはメインのダイレクトチャットバケットに常に `"main"` を使います。 +- **`agentToAgent.maxPingPongTurns`**: agent 間のやり取り中に許可される agent 間の返信往復ターン数の上限（整数、範囲: `0`–`5`）。`0` は ping-pong 連鎖を無効にします。 +- **`sendPolicy`**: `channel`、`chatType`（`direct|group|channel`、従来の `dm` alias あり）、`keyPrefix`、または `rawKeyPrefix` で一致させます。最初の deny が優先されます。 - **`maintenance`**: session ストアのクリーンアップ + 保持制御。 - - `mode`: `warn` は警告のみを出力し、`enforce` はクリーンアップを適用します。 - - `pruneAfter`: 古いエントリに対する経過時間しきい値（デフォルト `30d`）。 + - `mode`: `warn` は警告のみ出し、`enforce` はクリーンアップを適用します。 + - `pruneAfter`: 古いエントリの期限切れまでの期間（デフォルト `30d`）。 - `maxEntries`: `sessions.json` 内の最大エントリ数（デフォルト `500`）。 - - `rotateBytes`: `sessions.json` がこのサイズを超えたときにローテーションします（デフォルト `10mb`）。 - - `resetArchiveRetention`: `*.reset.` transcript アーカイブの保持期間。デフォルトは `pruneAfter`。無効にするには `false` を設定します。 - - `maxDiskBytes`: 任意の sessions ディレクトリのディスク予算。`warn` モードでは警告を記録し、`enforce` モードでは最も古い artifact/session から削除します。 + - `rotateBytes`: `sessions.json` がこのサイズを超えたらローテーションします（デフォルト `10mb`）。 + - `resetArchiveRetention`: `*.reset.` transcript アーカイブの保持期間。デフォルトでは `pruneAfter` を使います。無効にするには `false` を設定します。 + - `maxDiskBytes`: 任意の sessions ディレクトリのディスク予算。`warn` モードでは警告を記録し、`enforce` モードでは最も古い成果物/session から削除します。 - `highWaterBytes`: 予算クリーンアップ後の任意の目標値。デフォルトは `maxDiskBytes` の `80%` です。 -- **`threadBindings`**: スレッドバインド型 session 機能のグローバルデフォルト。 - - `enabled`: マスターのデフォルトスイッチ（provider で上書き可能。Discord は `channels.discord.threadBindings.enabled` を使用） - - `idleHours`: 非アクティブ時の自動 unfocus のデフォルト時間（`0` で無効。provider で上書き可能） - - `maxAgeHours`: ハード最大寿命のデフォルト時間（`0` で無効。provider で上書き可能） +- **`threadBindings`**: スレッドバインド session 機能のグローバルデフォルト。 + - `enabled`: マスターのデフォルトスイッチ（provider ごとに上書き可能。Discord は `channels.discord.threadBindings.enabled` を使用） + - `idleHours`: 非アクティブ時の自動 unfocus のデフォルト時間数（`0` で無効。provider ごとに上書き可能） + - `maxAgeHours`: ハード最大経過時間のデフォルト時間数（`0` で無効。provider ごとに上書き可能） @@ -1895,7 +2016,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // または "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1910,7 +2031,7 @@ scripts/sandbox-browser-setup.sh # optional browser image }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 で無効 byChannel: { whatsapp: 5000, slack: 1500, @@ -1922,36 +2043,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 応答プレフィックス -channel/account ごとの上書き: `channels..responsePrefix`、`channels..accounts..responsePrefix`。 +channel/account ごとのオーバーライド: `channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解決順序（より具体的なものが優先）: account → channel → global。`""` は無効化し、カスケードも停止します。`"auto"` は `[{identity.name}]` を導出します。 +解決順序（最も具体的なものが優先）: account → channel → global。`""` は無効化し、カスケードも停止します。`"auto"` は `[{identity.name}]` を導出します。 **テンプレート変数:** -| Variable | 説明 | 例 | -| ----------------- | --------------------- | --------------------------- | -| `{model}` | 短い model 名 | `claude-opus-4-6` | -| `{modelFull}` | 完全な model 識別子 | `anthropic/claude-opus-4-6` | -| `{provider}` | provider 名 | `anthropic` | +| 変数 | 説明 | 例 | +| ----------------- | -------------------- | --------------------------- | +| `{model}` | 短い model 名 | `claude-opus-4-6` | +| `{modelFull}` | 完全な model 識別子 | `anthropic/claude-opus-4-6` | +| `{provider}` | provider 名 | `anthropic` | | `{thinkingLevel}` | 現在の thinking レベル | `high`, `low`, `off` | -| `{identity.name}` | agent の identity 名 | （`"auto"` と同じ） | +| `{identity.name}` | agent identity 名 | （`"auto"` と同じ） | -変数は大文字小文字を区別しません。`{think}` は `{thinkingLevel}` のエイリアスです。 +変数は大文字小文字を区別しません。`{think}` は `{thinkingLevel}` の alias です。 -### ack リアクション +### 確認リアクション -- デフォルトはアクティブな agent の `identity.emoji`、それ以外は `"👀"` です。無効化するには `""` を設定します。 -- channel ごとの上書き: `channels..ackReaction`、`channels..accounts..ackReaction`。 +- デフォルトはアクティブな agent の `identity.emoji`、それ以外は `"👀"` です。無効にするには `""` を設定します。 +- channel ごとのオーバーライド: `channels..ackReaction`、`channels..accounts..ackReaction`。 - 解決順序: account → channel → `messages.ackReaction` → identity フォールバック。 - スコープ: `group-mentions`（デフォルト）、`group-all`、`direct`、`all`。 - `removeAckAfterReply`: Slack、Discord、Telegram で返信後に ack を削除します。 -- `messages.statusReactions.enabled`: Slack、Discord、Telegram でライフサイクルステータスリアクションを有効にします。 - Slack と Discord では、未設定の場合、ack リアクションが有効なときはステータスリアクションも有効のままです。 - Telegram では、ライフサイクルステータスリアクションを有効にするには、これを明示的に `true` に設定してください。 +- `messages.statusReactions.enabled`: Slack、Discord、Telegram でライフサイクル status リアクションを有効にします。 + Slack と Discord では、未設定の場合、ack リアクションが有効なら status リアクションも有効のままになります。 + Telegram では、ライフサイクル status リアクションを有効にするには明示的に `true` を設定してください。 ### 受信 debounce -同じ送信者からの連続したテキストのみのメッセージを、1 回の agent ターンにまとめます。メディア/添付ファイルは即座にフラッシュされます。制御コマンドは debouncing をバイパスします。 +同じ送信者からの連続するテキストのみのメッセージを 1 回の agent ターンにまとめます。media/添付ファイルは即時フラッシュされます。制御コマンドは debouncing をバイパスします。 ### TTS（text-to-speech） @@ -1994,18 +2115,18 @@ channel/account ごとの上書き: `channels..responsePrefix`、`chann } ``` -- `auto` はデフォルトの自動 TTS モードを制御します: `off`、`always`、`inbound`、または `tagged`。`/tts on|off` はローカル設定を上書きでき、`/tts status` は有効な状態を表示します。 -- `summaryModel` は、自動要約用に `agents.defaults.model.primary` を上書きします。 -- `modelOverrides` はデフォルトで有効です。`modelOverrides.allowProvider` はデフォルトで `false`（オプトイン）です。 -- API key は `ELEVENLABS_API_KEY`/`XI_API_KEY` および `OPENAI_API_KEY` にフォールバックします。 -- `openai.baseUrl` は OpenAI TTS エンドポイントを上書きします。解決順序は、config、次に `OPENAI_TTS_BASE_URL`、最後に `https://api.openai.com/v1` です。 -- `openai.baseUrl` が OpenAI 以外のエンドポイントを指している場合、OpenClaw はそれを OpenAI 互換 TTS サーバーとして扱い、model/voice の検証を緩和します。 +- `auto` はデフォルトの自動 TTS モードを制御します: `off`、`always`、`inbound`、または `tagged`。`/tts on|off` でローカル設定を上書きでき、`/tts status` で実効状態を確認できます。 +- `summaryModel` は、自動要約に対して `agents.defaults.model.primary` を上書きします。 +- `modelOverrides` はデフォルトで有効です。`modelOverrides.allowProvider` のデフォルトは `false`（オプトイン）です。 +- API キーは `ELEVENLABS_API_KEY`/`XI_API_KEY` および `OPENAI_API_KEY` にフォールバックします。 +- `openai.baseUrl` は OpenAI TTS エンドポイントを上書きします。解決順序は、設定、次に `OPENAI_TTS_BASE_URL`、最後に `https://api.openai.com/v1` です。 +- `openai.baseUrl` が OpenAI 以外のエンドポイントを指している場合、OpenClaw はそれを OpenAI 互換 TTS サーバーとして扱い、model/voice 検証を緩和します。 --- ## Talk -Talk モードのデフォルトです（macOS/iOS/Android）。 +Talk mode（macOS/iOS/Android）のデフォルト設定です。 ```json5 { @@ -2030,12 +2151,12 @@ Talk モードのデフォルトです（macOS/iOS/Android）。 ``` - `talk.provider` は、複数の Talk provider が設定されている場合、`talk.providers` 内のキーと一致している必要があります。 -- レガシーなフラット Talk キー（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）は互換性専用であり、自動的に `talk.providers.` へ移行されます。 +- 従来のフラットな Talk キー（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）は互換性専用であり、`talk.providers.` に自動移行されます。 - Voice ID は `ELEVENLABS_VOICE_ID` または `SAG_VOICE_ID` にフォールバックします。 -- `providers.*.apiKey` は平文文字列または SecretRef オブジェクトを受け付けます。 -- `ELEVENLABS_API_KEY` フォールバックは、Talk API key が設定されていない場合にのみ適用されます。 -- `providers.*.voiceAliases` により、Talk ディレクティブでわかりやすい名前を使用できます。 -- `silenceTimeoutMs` は、Talk モードがユーザーの無音後どれだけ待って transcript を送信するかを制御します。未設定の場合はプラットフォームのデフォルトの待機時間が維持されます（`macOS と Android では 700 ms、iOS では 900 ms`）。 +- `providers.*.apiKey` はプレーンテキスト文字列または SecretRef オブジェクトを受け付けます。 +- `ELEVENLABS_API_KEY` へのフォールバックは、Talk API キーが設定されていない場合にのみ適用されます。 +- `providers.*.voiceAliases` を使うと、Talk ディレクティブで親しみやすい名前を使えます。 +- `silenceTimeoutMs` は、Talk mode がユーザーの無音後に transcript を送信するまで待機する時間を制御します。未設定の場合はプラットフォームのデフォルト待機時間が使われます（`macOS と Android では 700 ms、iOS では 900 ms`）。 --- @@ -2043,22 +2164,22 @@ Talk モードのデフォルトです（macOS/iOS/Android）。 ### Tool プロファイル -`tools.profile` は、`tools.allow`/`tools.deny` の前にベース allowlist を設定します: +`tools.profile` は、`tools.allow`/`tools.deny` の前に基本 allowlist を設定します。 -ローカルのオンボーディングでは、未設定の場合、新しいローカル設定のデフォルトを `tools.profile: "coding"` にします（既存の明示的なプロファイルは保持されます）。 +ローカルのオンボーディングでは、新しいローカル設定で未設定の場合、デフォルトで `tools.profile: "coding"` を設定します（既存の明示的なプロファイルは保持されます）。 -| Profile | 含まれるもの | -| ----------- | -------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | `session_status` のみ | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | 制限なし（未設定と同じ） | +| プロファイル | 含まれるもの | +| ------------ | --------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | `session_status` のみ | +| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | 制限なし（未設定と同じ） | ### Tool グループ -| Group | Tools | +| グループ | Tools | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution`（`bash` は `exec` のエイリアスとして受け付けられます） | +| `group:runtime` | `exec`, `process`, `code_execution`（`bash` は `exec` の alias として受け付けられます） | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | @@ -2083,7 +2204,7 @@ Talk モードのデフォルトです（macOS/iOS/Android）。 ### `tools.byProvider` -特定の provider または model に対して tools をさらに制限します。順序: ベース profile → provider profile → allow/deny。 +特定の provider または model に対して tools をさらに制限します。順序: ベースプロファイル → provider プロファイル → allow/deny。 ```json5 { @@ -2099,7 +2220,7 @@ Talk モードのデフォルトです（macOS/iOS/Android）。 ### `tools.elevated` -sandbox 外での elevated exec アクセスを制御します: +sandbox の外での elevated exec アクセスを制御します: ```json5 { @@ -2115,9 +2236,9 @@ sandbox 外での elevated exec アクセスを制御します: } ``` -- agent ごとの上書き（`agents.list[].tools.elevated`）は、さらに制限することしかできません。 -- `/elevated on|off|ask|full` は session ごとに状態を保存します。インラインディレクティブは単一メッセージに適用されます。 -- Elevated `exec` は sandboxing をバイパスし、設定されたエスケープパス（デフォルトは `gateway`、exec ターゲットが `node` の場合は `node`）を使用します。 +- agent ごとのオーバーライド（`agents.list[].tools.elevated`）は、さらに制限することしかできません。 +- `/elevated on|off|ask|full` は状態を session ごとに保存します。インラインディレクティブは 1 件のメッセージにのみ適用されます。 +- Elevated `exec` は sandbox 化をバイパスし、設定された escape path を使います（デフォルトは `gateway`、exec ターゲットが `node` の場合は `node`）。 ### `tools.exec` @@ -2141,8 +2262,8 @@ sandbox 外での elevated exec アクセスを制御します: ### `tools.loopDetection` -tool ループの安全チェックはデフォルトでは**無効**です。検出を有効にするには `enabled: true` を設定します。 -設定は `tools.loopDetection` にグローバルで定義でき、`agents.list[].tools.loopDetection` で agent ごとに上書きできます。 +tool ループの安全チェックは**デフォルトで無効**です。有効化するには `enabled: true` を設定してください。 +設定はグローバルに `tools.loopDetection` で定義でき、agent ごとに `agents.list[].tools.loopDetection` で上書きできます。 ```json5 { @@ -2163,13 +2284,13 @@ tool ループの安全チェックはデフォルトでは**無効**です。 } ``` -- `historySize`: ループ解析のために保持する tool 呼び出し履歴の最大数。 -- `warningThreshold`: 進捗のない繰り返しパターンに対して警告を出すしきい値。 +- `historySize`: ループ分析のために保持する tool 呼び出し履歴の最大数。 +- `warningThreshold`: 警告を出す、進捗なしの繰り返しパターンのしきい値。 - `criticalThreshold`: 重大なループをブロックするための、より高い繰り返ししきい値。 -- `globalCircuitBreakerThreshold`: あらゆる進捗のない実行に対するハード停止しきい値。 +- `globalCircuitBreakerThreshold`: あらゆる進捗なし実行に対するハード停止しきい値。 - `detectors.genericRepeat`: 同じ tool/同じ引数の繰り返し呼び出しに警告します。 -- `detectors.knownPollNoProgress`: 既知の poll tool（`process.poll`、`command_status` など）の進捗なし状態に対して警告/ブロックします。 -- `detectors.pingPong`: 進捗のない交互ペアパターンに対して警告/ブロックします。 +- `detectors.knownPollNoProgress`: 既知の poll tools（`process.poll`、`command_status` など）に対して警告/ブロックします。 +- `detectors.pingPong`: 交互に続く進捗なしのペアパターンに警告/ブロックします。 - `warningThreshold >= criticalThreshold` または `criticalThreshold >= globalCircuitBreakerThreshold` の場合、検証は失敗します。 ### `tools.web` @@ -2180,14 +2301,14 @@ tool ループの安全チェックはデフォルトでは**無効**です。 web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // または BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // 任意。自動検出する場合は省略 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2204,7 +2325,7 @@ tool ループの安全チェックはデフォルトでは**無効**です。 ### `tools.media` -受信メディア理解（画像/音声/動画）を設定します: +受信 media 理解（画像/音声/動画）を設定します: ```json5 { @@ -2212,7 +2333,7 @@ tool ループの安全チェックはデフォルトでは**無効**です。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // opt-in: 完了した非同期 music/video を channel に直接送信 }, audio: { enabled: true, @@ -2236,13 +2357,13 @@ tool ループの安全チェックはデフォルトでは**無効**です。 } ``` - + -**Provider エントリ**（`type: "provider"` または省略時）: +**Provider エントリ**（`type: "provider"` または省略）: - `provider`: API provider id（`openai`、`anthropic`、`google`/`gemini`、`groq` など） -- `model`: model id 上書き -- `profile` / `preferredProfile`: `auth-profiles.json` の profile 選択 +- `model`: model id オーバーライド +- `profile` / `preferredProfile`: `auth-profiles.json` のプロファイル選択 **CLI エントリ**（`type: "cli"`）: @@ -2252,15 +2373,15 @@ tool ループの安全チェックはデフォルトでは**無効**です。 **共通フィールド:** - `capabilities`: 任意のリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → image、`google` → image+audio+video、`groq` → audio。 -- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリごとの上書き。 +- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリごとのオーバーライド。 - 失敗した場合は次のエントリにフォールバックします。 -provider の認証は標準順序に従います: `auth-profiles.json` → env vars → `models.providers.*.apiKey`。 +provider の auth は標準順序に従います: `auth-profiles.json` → env vars → `models.providers.*.apiKey`。 **非同期完了フィールド:** - `asyncCompletion.directSend`: `true` の場合、完了した非同期 `music_generate` - と `video_generate` タスクは、まず直接 channel 配信を試みます。デフォルト: `false` + および `video_generate` タスクは、まず direct channel 配信を試みます。デフォルト: `false` （従来の requester-session wake/model-delivery パス）。 @@ -2280,9 +2401,9 @@ provider の認証は標準順序に従います: `auth-profiles.json` → env v ### `tools.sessions` -session tools（`sessions_list`、`sessions_history`、`sessions_send`）で対象にできる session を制御します。 +session tools（`sessions_list`、`sessions_history`、`sessions_send`）でどの session を対象にできるかを制御します。 -デフォルト: `tree`（現在の session + そこから spawn された session、たとえば subagent）。 +デフォルト: `tree`（現在の session + そこから spawn された session。たとえば subagents）。 ```json5 { @@ -2298,25 +2419,25 @@ session tools（`sessions_list`、`sessions_history`、`sessions_send`）で対 注意: - `self`: 現在の session key のみ。 -- `tree`: 現在の session + 現在の session から spawn された session（subagent）。 -- `agent`: 現在の agent id に属する任意の session（同じ agent id の下で per-sender session を実行している場合は、他のユーザーも含まれることがあります）。 +- `tree`: 現在の session + 現在の session から spawn された session（subagents）。 +- `agent`: 現在の agent id に属する任意の session（同じ agent id の下で送信者ごとの session を実行している場合、他のユーザーを含むことがあります）。 - `all`: 任意の session。agent 間ターゲティングには引き続き `tools.agentToAgent` が必要です。 -- Sandbox clamp: 現在の session が sandbox 化されており、`agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` であっても visibility は `tree` に強制されます。 +- sandbox クランプ: 現在の session が sandbox 化されており、`agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` でも可視性は `tree` に強制されます。 ### `tools.sessions_spawn` -`sessions_spawn` のインライン添付ファイルサポートを制御します。 +`sessions_spawn` のインライン添付サポートを制御します。 ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // opt-in: true にするとインラインファイル添付を許可 + maxTotalBytes: 5242880, // すべてのファイル合計で 5 MB maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 1 ファイルあたり 1 MB + retainOnSessionKeep: false, // cleanup="keep" のときに添付を保持 }, }, }, @@ -2325,22 +2446,22 @@ session tools（`sessions_list`、`sessions_history`、`sessions_send`）で対 注意: -- 添付ファイルは `runtime: "subagent"` の場合のみサポートされます。ACP runtime では拒否されます。 +- 添付は `runtime: "subagent"` でのみサポートされます。ACP ランタイムはこれを拒否します。 - ファイルは子 workspace の `.openclaw/attachments//` に `.manifest.json` とともに実体化されます。 -- 添付ファイルの内容は transcript 永続化から自動的に秘匿化されます。 -- Base64 入力は、厳格な alphabet/padding チェックと、デコード前のサイズガードで検証されます。 +- 添付内容は transcript 永続化から自動的に秘匿化されます。 +- Base64 入力は、厳格なアルファベット/パディング検査とデコード前サイズガードで検証されます。 - ファイル権限は、ディレクトリが `0700`、ファイルが `0600` です。 -- クリーンアップは `cleanup` ポリシーに従います: `delete` は常に添付ファイルを削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 +- クリーンアップは `cleanup` ポリシーに従います: `delete` は常に添付を削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 ### `tools.experimental` -実験的な組み込み tool フラグです。strict-agentic GPT-5 の自動有効化ルールが適用されない限り、デフォルトはオフです。 +実験的な組み込み tool フラグです。strict-agentic GPT-5 の自動有効化ルールが適用される場合を除き、デフォルトはオフです。 ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // 実験的な update_plan を有効化 }, }, } @@ -2348,9 +2469,9 @@ session tools（`sessions_list`、`sessions_history`、`sessions_send`）で対 注意: -- `planTool`: 自明でない複数ステップ作業の追跡のために、構造化された `update_plan` tool を有効にします。 -- デフォルト: `agents.defaults.embeddedPi.executionContract`（または agent ごとの上書き）が OpenAI または OpenAI Codex の GPT-5 ファミリー実行で `"strict-agentic"` に設定されていない限り `false`。その範囲外でも強制的に有効にするには `true` を設定し、strict-agentic GPT-5 実行でもオフのままにするには `false` を設定します。 -- 有効な場合、system prompt にも使用ガイダンスが追加され、model は実質的な作業に対してのみこれを使用し、`in_progress` のステップを最大 1 つに保つようになります。 +- `planTool`: 自明でない複数ステップ作業の追跡用に、構造化された `update_plan` tool を有効にします。 +- デフォルト: `agents.defaults.embeddedPi.executionContract`（または agent ごとのオーバーライド）が OpenAI または OpenAI Codex の GPT-5 系実行に対して `"strict-agentic"` に設定されている場合を除き `false`。その範囲外でも強制的に有効にするには `true` を、strict-agentic GPT-5 実行でも無効に保つには `false` を設定してください。 +- 有効な場合、system prompt にも使用ガイダンスが追加され、model はそれを実質的な作業にのみ使い、`in_progress` のステップを最大 1 つまでに保ちます。 ### `agents.defaults.subagents` @@ -2370,16 +2491,16 @@ session tools（`sessions_list`、`sessions_history`、`sessions_send`）で対 } ``` -- `model`: spawn される sub-agent のデフォルト model。省略した場合、sub-agent は呼び出し元の model を継承します。 -- `allowAgents`: 要求元 agent が自身の `subagents.allowAgents` を設定していない場合の、`sessions_spawn` 用のデフォルトターゲット agent id 許可リスト（`["*"]` = 任意、デフォルト: 同じ agent のみ）。 -- `runTimeoutSeconds`: tool 呼び出しが `runTimeoutSeconds` を省略した場合の、`sessions_spawn` のデフォルトタイムアウト（秒）。`0` はタイムアウトなしを意味します。 -- subagent ごとの tool ポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `model`: spawn された sub-agent のデフォルト model。省略した場合、sub-agent は呼び出し元の model を継承します。 +- `allowAgents`: 要求元 agent が独自の `subagents.allowAgents` を設定していない場合に、`sessions_spawn` で対象にできる agent id のデフォルト allowlist（`["*"]` = 任意、デフォルト: 同じ agent のみ）。 +- `runTimeoutSeconds`: tool 呼び出しで `runTimeoutSeconds` を省略した場合の、`sessions_spawn` のデフォルトタイムアウト（秒）。`0` はタイムアウトなしを意味します。 +- sub-agent ごとの tool ポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## カスタム provider と base URL -OpenClaw は組み込み model カタログを使用します。カスタム provider は、config の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加します。 +OpenClaw は組み込み model カタログを使用します。カスタム provider は設定の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加できます。 ```json5 { @@ -2408,48 +2529,48 @@ OpenClaw は組み込み model カタログを使用します。カスタム pro } ``` -- カスタム認証が必要な場合は `authHeader: true` + `headers` を使用します。 -- agent 設定ルートを上書きするには `OPENCLAW_AGENT_DIR`（またはレガシーな環境変数エイリアス `PI_CODING_AGENT_DIR`）を使用します。 +- カスタム auth が必要な場合は `authHeader: true` + `headers` を使用します。 +- agent 設定ルートは `OPENCLAW_AGENT_DIR`（または legacy な環境変数 alias の `PI_CODING_AGENT_DIR`）で上書きできます。 - 一致する provider ID に対するマージ優先順位: - - 空でない agent `models.json` の `baseUrl` 値が優先されます。 - - 空でない agent の `apiKey` 値は、その provider が現在の config/auth-profile 文脈で SecretRef 管理されていない場合にのみ優先されます。 - - SecretRef 管理された provider の `apiKey` 値は、解決済みシークレットを永続化する代わりに、ソースマーカー（env ref は `ENV_VAR_NAME`、file/exec ref は `secretref-managed`）から更新されます。 - - SecretRef 管理された provider の header 値は、ソースマーカー（env ref は `secretref-env:ENV_VAR_NAME`、file/exec ref は `secretref-managed`）から更新されます。 - - 空または欠落している agent の `apiKey`/`baseUrl` は、config の `models.providers` にフォールバックします。 - - 一致する model の `contextWindow`/`maxTokens` は、明示的な config 値と暗黙のカタログ値のうち高い方を使用します。 - - 一致する model の `contextTokens` は、明示的なランタイム上限がある場合それを保持します。ネイティブ model メタデータを変更せずに有効コンテキストを制限するために使用してください。 - - config で `models.json` を完全に書き換えたい場合は `models.mode: "replace"` を使用します。 - - マーカー永続化はソースを正とします: マーカーは、解決済みランタイムシークレット値からではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。 + - 空でない agent の `models.json` `baseUrl` 値が優先されます。 + - 空でない agent の `apiKey` 値は、その provider が現在の config/auth-profile コンテキストで SecretRef 管理されていない場合にのみ優先されます。 + - SecretRef 管理された provider の `apiKey` 値は、解決済み secret を永続化する代わりに、ソースマーカー（env ref には `ENV_VAR_NAME`、file/exec ref には `secretref-managed`）から再更新されます。 + - SecretRef 管理された provider ヘッダー値も、ソースマーカー（env ref には `secretref-env:ENV_VAR_NAME`、file/exec ref には `secretref-managed`）から再更新されます。 + - agent の `apiKey`/`baseUrl` が空または欠落している場合は、設定の `models.providers` にフォールバックします。 + - 一致する model の `contextWindow`/`maxTokens` には、明示的な設定値と暗黙のカタログ値のうち高い方が使われます。 + - 一致する model の `contextTokens` は、明示的なランタイム上限が存在する場合それを保持します。ネイティブ model メタデータを変更せずに有効コンテキストを制限したい場合に使ってください。 + - 設定で `models.json` を完全に上書きしたい場合は `models.mode: "replace"` を使います。 + - マーカーの永続化はソース優先です。マーカーは、解決済みランタイム secret 値からではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。 -### Provider フィールドの詳細 +### Provider フィールド詳細 - `models.mode`: provider カタログの動作（`merge` または `replace`）。 -- `models.providers`: provider id をキーとするカスタム provider マップ。 -- `models.providers.*.api`: リクエストアダプタ（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。 -- `models.providers.*.apiKey`: provider 認証情報（SecretRef/env 置換の使用を推奨）。 +- `models.providers`: provider id をキーにしたカスタム provider マップ。 +- `models.providers.*.api`: リクエストアダプター（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。 +- `models.providers.*.apiKey`: provider の認証情報（SecretRef/env 置換の利用を推奨）。 - `models.providers.*.auth`: 認証戦略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` 用に、リクエストへ `options.num_ctx` を注入します（デフォルト: `true`）。 +- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` 用。リクエストに `options.num_ctx` を注入します（デフォルト: `true`）。 - `models.providers.*.authHeader`: 必要な場合に、認証情報を `Authorization` ヘッダーで送るよう強制します。 - `models.providers.*.baseUrl`: 上流 API の base URL。 -- `models.providers.*.headers`: proxy/tenant ルーティング用の追加静的ヘッダー。 -- `models.providers.*.request`: model-provider HTTP リクエストの転送上書き。 - - `request.headers`: 追加ヘッダー（provider デフォルトとマージ）。値は SecretRef を受け付けます。 - - `request.auth`: 認証戦略の上書き。モード: `"provider-default"`（provider 組み込み認証を使用）、`"authorization-bearer"`（`token` とともに使用）、`"header"`（`headerName`、`value`、任意で `prefix`）。 - - `request.proxy`: HTTP proxy の上書き。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` env vars を使用）、`"explicit-proxy"`（`url` とともに使用）。どちらのモードも任意の `tls` サブオブジェクトを受け付けます。 - - `request.tls`: 直接接続用の TLS 上書き。フィールド: `ca`、`cert`、`key`、`passphrase`（すべて SecretRef を受け付けます）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`: `true` の場合、DNS が private、CGNAT、または類似範囲に解決されるときに、provider HTTP fetch ガード経由で `baseUrl` への HTTPS を許可します（信頼されたセルフホスト OpenAI 互換エンドポイント向けの operator オプトイン）。WebSocket では、ヘッダー/TLS には同じ `request` を使いますが、その fetch SSRF ガードは使いません。デフォルト `false`。 +- `models.providers.*.headers`: proxy/tenant ルーティング用の追加の静的ヘッダー。 +- `models.providers.*.request`: model-provider HTTP リクエストの転送オーバーライド。 + - `request.headers`: 追加ヘッダー（provider デフォルトとマージ）。値には SecretRef を使えます。 + - `request.auth`: 認証戦略オーバーライド。モード: `"provider-default"`（provider 組み込み auth を使う）、`"authorization-bearer"`（`token` とともに使用）、`"header"`（`headerName`、`value`、任意の `prefix` とともに使用）。 + - `request.proxy`: HTTP proxy オーバーライド。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` env vars を使用）、`"explicit-proxy"`（`url` とともに使用）。どちらのモードも任意の `tls` サブオブジェクトを受け付けます。 + - `request.tls`: 直接接続用の TLS オーバーライド。フィールド: `ca`、`cert`、`key`、`passphrase`（すべて SecretRef を受け付けます）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`: `true` の場合、provider HTTP fetch ガード経由で、DNS が private、CGNAT、または類似レンジへ解決される `baseUrl` への HTTPS を許可します（信頼済みセルフホスト OpenAI 互換 endpoint 用の operator opt-in）。WebSocket はヘッダー/TLS には同じ `request` を使いますが、その fetch SSRF ガードは使いません。デフォルトは `false`。 - `models.providers.*.models`: 明示的な provider model カタログエントリ。 -- `models.providers.*.models.*.contextWindow`: ネイティブ model のコンテキストウィンドウメタデータ。 -- `models.providers.*.models.*.contextTokens`: 任意のランタイムコンテキスト上限。model のネイティブ `contextWindow` より小さい有効コンテキスト予算にしたい場合に使用します。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`: 任意の互換性ヒント。`api: "openai-completions"` で、空でない非ネイティブの `baseUrl`（host が `api.openai.com` ではない）の場合、OpenClaw はランタイムでこれを強制的に `false` にします。`baseUrl` が空または省略されている場合は、デフォルトの OpenAI 動作を維持します。 -- `models.providers.*.models.*.compat.requiresStringContent`: 文字列のみの OpenAI 互換 chat エンドポイント向けの任意の互換性ヒント。`true` の場合、OpenClaw はリクエスト送信前に、純粋なテキストの `messages[].content` 配列をプレーン文字列に平坦化します。 +- `models.providers.*.models.*.contextWindow`: model ネイティブのコンテキストウィンドウメタデータ。 +- `models.providers.*.models.*.contextTokens`: 任意のランタイムコンテキスト上限。model 本来の `contextWindow` より小さい実効コンテキスト予算にしたい場合に使います。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`: 任意の互換性ヒント。`api: "openai-completions"` かつ空でない非ネイティブ `baseUrl`（host が `api.openai.com` ではない）の場合、OpenClaw はランタイム時にこれを `false` に強制します。`baseUrl` が空または省略されている場合は、OpenAI のデフォルト動作を維持します。 +- `models.providers.*.models.*.compat.requiresStringContent`: 文字列のみを受け付ける OpenAI 互換 chat endpoint 用の任意の互換性ヒント。`true` の場合、OpenClaw はリクエスト送信前に、純粋なテキストの `messages[].content` 配列をプレーン文字列へ平坦化します。 - `plugins.entries.amazon-bedrock.config.discovery`: Bedrock 自動検出設定のルート。 - `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙的な検出をオン/オフします。 -- `plugins.entries.amazon-bedrock.config.discovery.region`: 検出用の AWS region。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象を絞った検出のための任意の provider-id フィルタ。 +- `plugins.entries.amazon-bedrock.config.discovery.region`: 検出に使う AWS リージョン。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象を絞った検出用の任意の provider-id フィルター。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: 検出更新のポーリング間隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出された model 用のフォールバックコンテキストウィンドウ。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出された model 用のフォールバック最大出力トークン数。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出された models 用のフォールバック context window。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出された models 用のフォールバック最大出力 token 数。 ### Provider の例 @@ -2487,7 +2608,7 @@ OpenClaw は組み込み model カタログを使用します。カスタム pro } ``` -Cerebras には `cerebras/zai-glm-4.7` を使用してください。Z.AI 直結には `zai/glm-4.7` を使用してください。 +Cerebras には `cerebras/zai-glm-4.7` を使用し、Z.AI へ直接接続する場合は `zai/glm-4.7` を使います。 @@ -2504,7 +2625,7 @@ Cerebras には `cerebras/zai-glm-4.7` を使用してください。Z.AI 直結 } ``` -`OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`）を設定してください。Zen カタログには `opencode/...` 参照、Go カタログには `opencode-go/...` 参照を使用します。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。 +`OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`）を設定してください。Zen カタログには `opencode/...` 参照を、Go カタログには `opencode-go/...` 参照を使います。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。 @@ -2521,11 +2642,11 @@ Cerebras には `cerebras/zai-glm-4.7` を使用してください。Z.AI 直結 } ``` -`ZAI_API_KEY` を設定してください。`z.ai/*` と `z-ai/*` は受け付けられるエイリアスです。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 +`ZAI_API_KEY` を設定してください。`z.ai/*` と `z-ai/*` は受け付けられる alias です。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 -- 一般エンドポイント: `https://api.z.ai/api/paas/v4` -- Coding エンドポイント（デフォルト）: `https://api.z.ai/api/coding/paas/v4` -- 一般エンドポイント用には、base URL 上書きを持つカスタム provider を定義してください。 +- 一般 endpoint: `https://api.z.ai/api/paas/v4` +- コーディング endpoint（デフォルト）: `https://api.z.ai/api/coding/paas/v4` +- 一般 endpoint を使う場合は、base URL オーバーライド付きのカスタム provider を定義してください。 @@ -2564,10 +2685,10 @@ Cerebras には `cerebras/zai-glm-4.7` を使用してください。Z.AI 直結 } ``` -中国エンドポイントには `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn` を使用してください。 +China endpoint 用: `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn`。 -ネイティブの Moonshot エンドポイントは、共有の -`openai-completions` 転送上でストリーミング使用互換性を広告しており、OpenClaw はそれを組み込み provider id のみではなく、エンドポイント機能に基づいて判断します。 +ネイティブ Moonshot endpoint は、共有の +`openai-completions` 転送上でストリーミング使用互換性を公開しており、OpenClaw は組み込み provider id だけでなく、その endpoint の機能に基づいてそれを判断します。 @@ -2628,7 +2749,7 @@ base URL には `/v1` を含めないでください（Anthropic クライアン - + ```json5 { @@ -2668,15 +2789,16 @@ base URL には `/v1` を含めないでください（Anthropic クライアン `openclaw onboard --auth-choice minimax-global-api` または `openclaw onboard --auth-choice minimax-cn-api`。 model カタログのデフォルトは M2.7 のみです。 -Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に `thinking` を設定しない限り、MiniMax の thinking をデフォルトで無効にします。`/fast on` または +Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を明示的に設定しない限り、 +デフォルトで MiniMax の thinking を無効にします。`/fast on` または `params.fastMode: true` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。 - + -[Local Models](/ja-JP/gateway/local-models) を参照してください。要約: 十分なハードウェア上で LM Studio Responses API により大きなローカル model を実行し、フォールバック用にホスト型 model をマージしたままにしてください。 +[Local Models](/ja-JP/gateway/local-models) を参照してください。要点: 十分な性能のハードウェア上で LM Studio Responses API を使って大きなローカル model を実行し、フォールバック用にホスト型 models もマージしたままにしておきます。 @@ -2697,7 +2819,7 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // またはプレーンテキスト文字列 env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2707,14 +2829,13 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に } ``` -- `allowBundled`: bundled Skills のみを対象とする任意の許可リストです（managed/workspace Skills は影響を受けません）。 +- `allowBundled`: bundled Skills のみを対象にした任意の allowlist です（managed/workspace Skills には影響しません）。 - `load.extraDirs`: 追加の共有 skill ルート（最も低い優先順位）。 -- `install.preferBrew`: true の場合、`brew` が利用可能なら、他のインストーラー種別にフォールバックする前に Homebrew インストーラーを優先します。 +- `install.preferBrew`: `true` の場合、`brew` が利用可能なら他の installer 種別へフォールバックする前に Homebrew installer を優先します。 - `install.nodeManager`: `metadata.openclaw.install` - 仕様向けの node インストーラー優先設定 - （`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false` は、その skill が bundled/インストール済みであっても無効にします。 -- `entries..apiKey`: 主たる env var を宣言する skill 向けの簡易設定です（平文文字列または SecretRef オブジェクト）。 + 指定用の node installer 優先設定（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false` は、その skill が bundled/installed であっても無効にします。 +- `entries..apiKey`: 主要 env var を宣言する Skills 向けの簡易設定です（プレーンテキスト文字列または SecretRef オブジェクト）。 --- @@ -2743,38 +2864,38 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に ``` - `~/.openclaw/extensions`、`/.openclaw/extensions`、および `plugins.load.paths` から読み込まれます。 -- 検出では、ネイティブ OpenClaw Plugin に加え、互換性のある Codex bundle と Claude bundle（manifest を持たない Claude のデフォルトレイアウト bundle を含む）を受け付けます。 -- **設定変更には gateway の再起動が必要です。** -- `allow`: 任意の許可リスト（一覧にある Plugin のみ読み込みます）。`deny` が優先されます。 -- `plugins.entries..apiKey`: Plugin レベルの API key 簡易フィールド（Plugin が対応している場合）。 +- 検出では、ネイティブ OpenClaw Plugins に加えて、互換性のある Codex bundle と Claude bundle も受け付けます。manifest のない Claude のデフォルトレイアウト bundle も含まれます。 +- **設定変更には Gateway の再起動が必要です。** +- `allow`: 任意の allowlist（一覧にある Plugins のみ読み込まれます）。`deny` が優先されます。 +- `plugins.entries..apiKey`: Plugin レベルの API キー用簡易フィールド（Plugin がサポートしている場合）。 - `plugins.entries..env`: Plugin スコープの env var マップ。 -- `plugins.entries..hooks.allowPromptInjection`: `false` の場合、core は `before_prompt_build` をブロックし、レガシーな `before_agent_start` からの prompt 変更フィールドを無視します。一方で、レガシーな `modelOverride` と `providerOverride` は保持します。ネイティブ Plugin hooks と、対応する bundle 提供の hook ディレクトリに適用されます。 -- `plugins.entries..subagent.allowModelOverride`: この Plugin がバックグラウンド subagent 実行に対して、実行ごとの `provider` と `model` の上書きを要求できるよう、明示的に信頼します。 -- `plugins.entries..subagent.allowedModels`: 信頼された subagent 上書き用の、任意の正規 `provider/model` ターゲット許可リスト。任意の model を許可したい意図がある場合にのみ `"*"` を使用してください。 -- `plugins.entries..config`: Plugin 定義の設定オブジェクト（利用可能な場合はネイティブ OpenClaw Plugin スキーマで検証されます）。 -- `plugins.entries.firecrawl.config.webFetch`: Firecrawl web-fetch provider 設定。 - - `apiKey`: Firecrawl API key（SecretRef を受け付けます）。`plugins.entries.firecrawl.config.webSearch.apiKey`、レガシーな `tools.web.fetch.firecrawl.apiKey`、または `FIRECRAWL_API_KEY` env var にフォールバックします。 +- `plugins.entries..hooks.allowPromptInjection`: `false` の場合、core は `before_prompt_build` をブロックし、従来の `before_agent_start` からの prompt 変更フィールドを無視します。一方で、従来の `modelOverride` と `providerOverride` は保持します。ネイティブ Plugin hooks と、サポートされる bundle 提供の hook ディレクトリに適用されます。 +- `plugins.entries..subagent.allowModelOverride`: この Plugin が、バックグラウンド subagent 実行ごとに `provider` と `model` のオーバーライドを要求することを明示的に信頼します。 +- `plugins.entries..subagent.allowedModels`: 信頼済み subagent オーバーライド用の、正規 `provider/model` ターゲットの任意の allowlist。任意の model を許可したい意図がある場合にのみ `"*"` を使ってください。 +- `plugins.entries..config`: Plugin 定義の設定オブジェクト（利用可能な場合はネイティブ OpenClaw Plugin schema で検証されます）。 +- `plugins.entries.firecrawl.config.webFetch`: Firecrawl の web fetch provider 設定。 + - `apiKey`: Firecrawl API キー（SecretRef を受け付けます）。`plugins.entries.firecrawl.config.webSearch.apiKey`、従来の `tools.web.fetch.firecrawl.apiKey`、または `FIRECRAWL_API_KEY` env var にフォールバックします。 - `baseUrl`: Firecrawl API の base URL（デフォルト: `https://api.firecrawl.dev`）。 - - `onlyMainContent`: ページからメインコンテンツのみを抽出します（デフォルト: `true`）。 - - `maxAgeMs`: キャッシュの最大経過時間（ミリ秒）（デフォルト: `172800000` / 2 日）。 - - `timeoutSeconds`: scrape リクエストのタイムアウト秒数（デフォルト: `60`）。 + - `onlyMainContent`: ページから主要コンテンツのみを抽出します（デフォルト: `true`）。 + - `maxAgeMs`: キャッシュの最大有効期間（ミリ秒）（デフォルト: `172800000` / 2 日）。 + - `timeoutSeconds`: スクレイプリクエストのタイムアウト秒数（デフォルト: `60`）。 - `plugins.entries.xai.config.xSearch`: xAI X Search（Grok web search）設定。 - `enabled`: X Search provider を有効にします。 - - `model`: 検索に使用する Grok model（例: `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`: memory dreaming 設定。フェーズとしきい値については [Dreaming](/ja-JP/concepts/dreaming) を参照してください。 - - `enabled`: dreaming のマスタースイッチ（デフォルト `false`）。 - - `frequency`: 各フル dreaming スイープの Cron cadence（デフォルトは `"0 3 * * *"`）。 - - フェーズポリシーとしきい値は実装詳細です（ユーザー向け設定キーではありません）。 -- memory の完全な設定は [Memory configuration reference](/ja-JP/reference/memory-config) にあります: + - `model`: 検索に使う Grok model（例: `"grok-4-1-fast"`）。 +- `plugins.entries.memory-core.config.dreaming`: memory の Dreaming 設定。フェーズとしきい値については [Dreaming](/ja-JP/concepts/dreaming) を参照してください。 + - `enabled`: Dreaming のマスタースイッチ（デフォルト `false`）。 + - `frequency`: 各フル Dreaming スイープの Cron 間隔（デフォルトは `"0 3 * * *"`）。 + - フェーズポリシーとしきい値は実装詳細であり、ユーザー向け設定キーではありません。 +- 完全な memory 設定は [メモリ設定リファレンス](/ja-JP/reference/memory-config) にあります: - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 有効な Claude bundle Plugin は、`settings.json` から埋め込み Pi デフォルトを提供することもできます。OpenClaw はそれらを生の OpenClaw 設定パッチとしてではなく、サニタイズ済みの agent 設定として適用します。 -- `plugins.slots.memory`: アクティブな memory Plugin id を選択するか、memory Plugin を無効にするには `"none"` を指定します。 +- 有効な Claude bundle Plugins は、`settings.json` から埋め込み Pi デフォルトも提供できます。OpenClaw はそれらを生の OpenClaw 設定パッチではなく、サニタイズ済み agent 設定として適用します。 +- `plugins.slots.memory`: アクティブな memory Plugin id を選択するか、memory Plugins を無効にするには `"none"` を指定します。 - `plugins.slots.contextEngine`: アクティブな context engine Plugin id を選択します。別の engine をインストールして選択しない限り、デフォルトは `"legacy"` です。 -- `plugins.installs`: `openclaw plugins update` で使用される CLI 管理のインストールメタデータ。 +- `plugins.installs`: `openclaw plugins update` が使用する CLI 管理のインストールメタデータ。 - `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt` を含みます。 - `plugins.installs.*` は管理状態として扱い、手動編集より CLI コマンドを優先してください。 @@ -2791,7 +2912,7 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // dangerouslyAllowPrivateNetwork: true, // 信頼できる private-network アクセスに対してのみ opt in // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2820,27 +2941,28 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に - `evaluateEnabled: false` は `act:evaluate` と `wait --fn` を無効にします。 - `ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定時には無効なので、browser ナビゲーションはデフォルトで strict のままです。 -- private-network browser ナビゲーションを意図的に信頼する場合にのみ `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` を設定してください。 -- strict モードでは、リモート CDP profile エンドポイント（`profiles.*.cdpUrl`）も、到達性/検出チェック時に同じ private-network ブロックの対象になります。 -- `ssrfPolicy.allowPrivateNetwork` はレガシーなエイリアスとして引き続きサポートされます。 -- strict モードでは、明示的な例外には `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使用します。 -- リモート profile は attach-only です（start/stop/reset は無効）。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` は、private-network browser ナビゲーションを意図的に信頼する場合にのみ設定してください。 +- strict モードでは、リモート CDP profile endpoint（`profiles.*.cdpUrl`）にも、到達性/検出チェック時に同じ private-network ブロックが適用されます。 +- `ssrfPolicy.allowPrivateNetwork` は従来の alias として引き続きサポートされます。 +- strict モードでは、明示的な例外には `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使います。 +- リモート profiles は attach-only です（start/stop/reset は無効）。 - `profiles.*.cdpUrl` は `http://`、`https://`、`ws://`、`wss://` を受け付けます。 - provider が `/json/version` を検出できるようにしたい場合は HTTP(S) を使い、 - 直接の DevTools WebSocket URL が提供される場合は WS(S) を使ってください。 -- `existing-session` profile はホスト専用で、CDP の代わりに Chrome MCP を使用します。 -- `existing-session` profile は、Brave や Edge のような特定の - Chromium ベース browser profile を対象にするために `userDataDir` を設定できます。 -- `existing-session` profile は現在の Chrome MCP ルート制限を維持します: - CSS セレクタ対象指定ではなく snapshot/ref ベースの操作、単一ファイルアップロード - hook、ダイアログタイムアウト上書きなし、`wait --load networkidle` なし、 - `responsebody`、PDF エクスポート、ダウンロードインターセプト、バッチ操作なし。 -- ローカル管理の `openclaw` profile は `cdpPort` と `cdpUrl` を自動割り当てします。明示的に - `cdpUrl` を設定するのはリモート CDP の場合だけにしてください。 -- 自動検出順序: デフォルト browser が Chromium ベースならそれ → Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 制御サービス: loopback のみ（port は `gateway.port` から導出、デフォルト `18791`）。 + `/json/version` を OpenClaw に検出させたい場合は HTTP(S) を使い、 + provider が直接の DevTools WebSocket URL を提供する場合は WS(S) + を使ってください。 +- `existing-session` profiles は host 専用で、CDP の代わりに Chrome MCP を使います。 +- `existing-session` profiles では、特定の + Chromium ベース browser profile（Brave や Edge など）を対象にするために `userDataDir` を設定できます。 +- `existing-session` profiles は、現在の Chrome MCP ルート制限を維持します: + CSS セレクター指定ではなく snapshot/ref ベースのアクション、単一ファイルのアップロード + hooks、dialog タイムアウト上書きなし、`wait --load networkidle` なし、 + さらに `responsebody`、PDF エクスポート、ダウンロード傍受、バッチアクションもありません。 +- ローカル管理の `openclaw` profiles は `cdpPort` と `cdpUrl` を自動割り当てします。明示的に + `cdpUrl` を設定するのはリモート CDP の場合のみです。 +- 自動検出順序: デフォルト browser が Chromium ベースならそれを優先 → Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 制御サービス: loopback のみ（port は `gateway.port` から導出。デフォルト `18791`）。 - `extraArgs` は、ローカル Chromium 起動に追加の起動フラグを付加します（たとえば - `--disable-gpu`、ウィンドウサイズ指定、またはデバッグフラグ）。 + `--disable-gpu`、ウィンドウサイズ設定、デバッグフラグなど）。 --- @@ -2858,8 +2980,8 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に } ``` -- `seamColor`: ネイティブアプリ UI のクローム用アクセントカラーです（Talk Mode のバブル色など）。 -- `assistant`: Control UI の identity 上書き。アクティブな agent identity にフォールバックします。 +- `seamColor`: ネイティブ app UI chrome 用のアクセントカラーです（Talk Mode のバブル色合いなど）。 +- `assistant`: Control UI の identity オーバーライド。アクティブな agent identity にフォールバックします。 --- @@ -2875,7 +2997,7 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に mode: "token", // none | token | password | trusted-proxy token: "your-token", // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // trustedProxy: { userHeader: "x-forwarded-user" }, // mode=trusted-proxy 用。/gateway/trusted-proxy-auth を参照 allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2893,9 +3015,9 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowExternalEmbedUrls: false, // 危険: 絶対外部 http(s) 埋め込み URL を許可 + // allowedOrigins: ["https://control.example.com"], // 非 loopback の Control UI に必須 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危険な Host ヘッダー origin フォールバックモード // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2906,12 +3028,12 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // 任意。デフォルトは false。 allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // /tools/invoke HTTP に対する追加 deny deny: ["browser"], - // Remove tools from the default HTTP deny list + // デフォルトの HTTP deny リストから tools を除外 allow: ["gateway"], }, push: { @@ -2926,67 +3048,67 @@ Anthropic 互換のストリーミングパスでは、OpenClaw は明示的に } ``` - + -- `mode`: `local`（gateway を実行）または `remote`（リモート gateway に接続）。Gateway は `local` でない限り起動を拒否します。 +- `mode`: `local`（Gateway を実行）または `remote`（リモート Gateway に接続）。`local` でない限り Gateway は起動を拒否します。 - `port`: WS + HTTP 用の単一多重化ポート。優先順位: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`: `auto`、`loopback`（デフォルト）、`lan`（`0.0.0.0`）、`tailnet`（Tailscale IP のみ）、または `custom`。 -- **レガシー bind エイリアス**: `gateway.bind` ではホストエイリアス（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）ではなく、bind mode 値（`auto`、`loopback`、`lan`、`tailnet`、`custom`）を使用してください。 -- **Docker に関する注意**: デフォルトの `loopback` bind はコンテナ内の `127.0.0.1` で待ち受けます。Docker bridge networking（`-p 18789:18789`）では、トラフィックは `eth0` に到着するため、gateway へ到達できません。`--network host` を使うか、全インターフェースで待ち受けるために `bind: "lan"`（または `customBindHost: "0.0.0.0"` とともに `bind: "custom"`）を設定してください。 -- **Auth**: デフォルトで必須です。loopback 以外の bind では gateway auth が必要です。実際には、共有 token/password、または `gateway.auth.mode: "trusted-proxy"` を使用した identity-aware reverse proxy を意味します。オンボーディング wizard はデフォルトで token を生成します。 -- `gateway.auth.token` と `gateway.auth.password` の両方が設定されている場合（SecretRef を含む）、`gateway.auth.mode` を `token` または `password` に明示的に設定してください。両方が設定されていて mode が未設定の場合、起動とサービスのインストール/修復フローは失敗します。 -- `gateway.auth.mode: "none"`: 明示的な no-auth モードです。信頼された local loopback セットアップでのみ使用してください。これはオンボーディングプロンプトでは意図的に提供されません。 -- `gateway.auth.mode: "trusted-proxy"`: auth を identity-aware reverse proxy に委譲し、`gateway.trustedProxies` からの identity ヘッダーを信頼します（[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照）。このモードは **loopback 以外** の proxy ソースを前提とします。同一ホストの loopback reverse proxy は trusted-proxy auth の条件を満たしません。 -- `gateway.auth.allowTailscale`: `true` の場合、Tailscale Serve の identity ヘッダーが Control UI/WebSocket auth を満たせます（`tailscale whois` で検証）。HTTP API エンドポイントはこの Tailscale ヘッダー auth を使用しません。代わりに gateway の通常の HTTP auth モードに従います。この token なしフローは gateway ホストが信頼されている前提です。`tailscale.mode = "serve"` のときのデフォルトは `true` です。 -- `gateway.auth.rateLimit`: 任意の認証失敗リミッターです。クライアント IP ごと、かつ auth スコープごとに適用されます（共有シークレットと device-token は独立して追跡されます）。ブロックされた試行は `429` + `Retry-After` を返します。 - - 非同期 Tailscale Serve Control UI パスでは、同じ `{scope, clientIp}` に対する失敗試行は、失敗書き込み前に直列化されます。したがって、同じクライアントからの同時の不正試行は、両方が単なる不一致として通過する代わりに、2 回目のリクエストでリミッターを発動させることがあります。 - - `gateway.auth.rateLimit.exemptLoopback` のデフォルトは `true` です。localhost トラフィックにも意図的に rate limit を適用したい場合（テスト構成や厳格な proxy デプロイなど）は `false` を設定してください。 -- browser 起点の WS auth 試行は、loopback 免除を無効にした状態で常にスロットルされます（browser ベースの localhost 総当たり攻撃に対する多層防御）。 -- loopback では、それらの browser 起点ロックアウトは正規化された `Origin` - 値ごとに分離されるため、ある localhost origin からの繰り返し失敗が +- **従来の bind alias**: `gateway.bind` にはホスト alias（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）ではなく、bind mode 値（`auto`、`loopback`、`lan`、`tailnet`、`custom`）を使ってください。 +- **Docker 注意事項**: デフォルトの `loopback` bind は、コンテナ内では `127.0.0.1` で待ち受けます。Docker bridge ネットワーク（`-p 18789:18789`）では、トラフィックは `eth0` に到着するため、Gateway に到達できません。`--network host` を使うか、すべてのインターフェースで待ち受けるために `bind: "lan"`（または `bind: "custom"` と `customBindHost: "0.0.0.0"`）を設定してください。 +- **Auth**: デフォルトで必須です。loopback 以外の bind には Gateway auth が必要です。実運用では、共有 token/password または `gateway.auth.mode: "trusted-proxy"` を使う ID 認識型 reverse proxy を意味します。オンボーディングウィザードはデフォルトで token を生成します。 +- `gateway.auth.token` と `gateway.auth.password` の両方が設定されている場合（SecretRef を含む）、`gateway.auth.mode` を `token` または `password` に明示設定してください。両方が設定されていて mode が未設定の場合、起動と service のインストール/修復フローは失敗します。 +- `gateway.auth.mode: "none"`: 明示的な no-auth mode。信頼できる local loopback 構成でのみ使用してください。これは意図的にオンボーディングプロンプトでは提供されません。 +- `gateway.auth.mode: "trusted-proxy"`: auth を ID 認識型 reverse proxy に委譲し、`gateway.trustedProxies` からの ID ヘッダーを信頼します（[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照）。この mode は**非 loopback** の proxy ソースを前提とします。同一ホストの loopback reverse proxy は trusted-proxy auth の要件を満たしません。 +- `gateway.auth.allowTailscale`: `true` の場合、Tailscale Serve の identity ヘッダーで Control UI/WebSocket auth を満たせます（`tailscale whois` で検証）。HTTP API endpoint はこの Tailscale ヘッダー auth を**使わず**、通常の Gateway HTTP auth mode に従います。この token なしフローは Gateway ホストが信頼されている前提です。`tailscale.mode = "serve"` の場合、デフォルトは `true` です。 +- `gateway.auth.rateLimit`: 任意の認証失敗レート制限です。クライアント IP ごと、および auth スコープごとに適用されます（共有 secret と device token は独立して追跡されます）。ブロックされた試行には `429` + `Retry-After` が返されます。 + - 非同期の Tailscale Serve Control UI パスでは、同じ `{scope, clientIp}` に対する失敗試行は、失敗書き込み前に直列化されます。そのため、同じクライアントからの並行する不正試行は、両方が単なる不一致として競合通過するのではなく、2 回目のリクエストで制限に達する場合があります。 + - `gateway.auth.rateLimit.exemptLoopback` のデフォルトは `true` です。localhost トラフィックも意図的にレート制限したい場合（テスト構成や厳格な proxy 配置など）は `false` に設定してください。 +- browser 由来の WS auth 試行は、loopback 免除を無効にした状態で常にスロットルされます（browser ベースの localhost ブルートフォースに対する多層防御）。 +- loopback 上では、それらの browser 由来ロックアウトは正規化された `Origin` + 値ごとに分離されるため、ある localhost origin からの繰り返し失敗が、 自動的に別の origin をロックアウトすることはありません。 - `tailscale.mode`: `serve`（tailnet のみ、loopback bind）または `funnel`（公開、auth 必須）。 -- `controlUi.allowedOrigins`: Gateway WebSocket 接続用の明示的な browser-origin 許可リストです。loopback 以外の origin から browser クライアントを想定する場合は必須です。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host-header origin ポリシーに意図的に依存するデプロイ向けに、Host-header origin フォールバックを有効にする危険なモードです。 +- `controlUi.allowedOrigins`: Gateway WebSocket 接続用の明示的な browser origin allowlist。非 loopback origin から browser クライアントが接続する想定なら必須です。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host ヘッダー origin ポリシーに意図的に依存するデプロイ向けの、危険な Host ヘッダー origin フォールバックモードを有効にします。 - `remote.transport`: `ssh`（デフォルト）または `direct`（ws/wss）。`direct` の場合、`remote.url` は `ws://` または `wss://` でなければなりません。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: 信頼された private-network IP への平文 `ws://` を許可するクライアント側の緊急用上書きです。平文のデフォルトは引き続き loopback のみです。 -- `gateway.remote.token` / `.password` はリモートクライアント用の認証情報フィールドです。それ自体では gateway auth を設定しません。 -- `gateway.push.apns.relay.baseUrl`: 公式/TestFlight iOS ビルドが relay ベース登録を gateway に公開した後に使用する、外部 APNs relay の base HTTPS URL です。この URL は、iOS ビルドにコンパイルされた relay URL と一致している必要があります。 -- `gateway.push.apns.relay.timeoutMs`: gateway から relay への送信タイムアウト（ミリ秒）。デフォルトは `10000`。 -- relay ベース登録は特定の gateway identity に委譲されます。ペアリングされた iOS アプリは `gateway.identity.get` を取得し、その identity を relay 登録に含め、登録スコープの send grant を gateway に転送します。別の gateway は、その保存済み登録を再利用できません。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 上記 relay 設定の一時的な env 上書きです。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTP relay URL 用の開発専用エスケープハッチです。本番の relay URL は HTTPS を維持すべきです。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: クライアント側の非常時用オーバーライドで、信頼できる private-network IP への平文 `ws://` を許可します。デフォルトでは、平文は引き続き loopback のみです。 +- `gateway.remote.token` / `.password` はリモートクライアント用の認証情報フィールドです。これら自体は Gateway auth を設定しません。 +- `gateway.push.apns.relay.baseUrl`: 公式/TestFlight iOS ビルドが relay バック登録を Gateway に公開した後に使用される、外部 APNs relay の base HTTPS URL。この URL は iOS ビルドにコンパイルされた relay URL と一致している必要があります。 +- `gateway.push.apns.relay.timeoutMs`: Gateway から relay への送信タイムアウト（ミリ秒）。デフォルトは `10000`。 +- relay バック登録は特定の Gateway identity に委譲されます。ペア済み iOS app は `gateway.identity.get` を取得し、その identity を relay 登録に含め、登録スコープの送信権限を Gateway へ転送します。別の Gateway はその保存済み登録を再利用できません。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 上記 relay 設定の一時的な env オーバーライド。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTP relay URL 用の開発専用 escape hatch。本番 relay URL は HTTPS のままにしてください。 - `gateway.channelHealthCheckMinutes`: channel ヘルスモニター間隔（分）。ヘルスモニター再起動をグローバルに無効にするには `0` を設定します。デフォルト: `5`。 -- `gateway.channelStaleEventThresholdMinutes`: stale-socket しきい値（分）。これは `gateway.channelHealthCheckMinutes` 以上に保ってください。デフォルト: `30`。 -- `gateway.channelMaxRestartsPerHour`: ローリング 1 時間あたり、channel/account ごとに行うヘルスモニター再起動の最大数。デフォルト: `10`。 -- `channels..healthMonitor.enabled`: グローバルモニターを有効にしたまま、channel ごとにヘルスモニター再起動をオプトアウトします。 -- `channels..accounts..healthMonitor.enabled`: マルチアカウント channel 用のアカウントごとの上書き。設定されている場合、channel レベルの上書きより優先されます。 -- ローカル gateway 呼び出しパスでは、`gateway.auth.*` が未設定の場合にのみ `gateway.remote.*` をフォールバックとして使用できます。 -- `gateway.auth.token` / `gateway.auth.password` が SecretRef 経由で明示的に設定され、未解決の場合、解決は fail-closed します（リモートフォールバックによる隠蔽はありません）。 -- `trustedProxies`: TLS を終端する、または転送クライアントヘッダーを注入する reverse proxy の IP です。自分で管理している proxy のみを列挙してください。loopback エントリは同一ホスト proxy/ローカル検出セットアップ（たとえば Tailscale Serve やローカル reverse proxy）では依然有効ですが、loopback リクエストが `gateway.auth.mode: "trusted-proxy"` の対象になるわけでは**ありません**。 -- `allowRealIpFallback`: `true` の場合、`X-Forwarded-For` がないときに gateway は `X-Real-IP` を受け付けます。fail-closed 動作のためデフォルトは `false`。 -- `gateway.tools.deny`: HTTP `POST /tools/invoke` に対してブロックする追加 tool 名です（デフォルト deny リストを拡張）。 -- `gateway.tools.allow`: デフォルト HTTP deny リストから tool 名を削除します。 +- `gateway.channelStaleEventThresholdMinutes`: 古い socket と見なすしきい値（分）。これは `gateway.channelHealthCheckMinutes` 以上に保ってください。デフォルト: `30`。 +- `gateway.channelMaxRestartsPerHour`: ローリング 1 時間あたりの、channel/account ごとのヘルスモニター再起動回数上限。デフォルト: `10`。 +- `channels..healthMonitor.enabled`: グローバルモニターを有効のまま、channel ごとにヘルスモニター再起動を opt out します。 +- `channels..accounts..healthMonitor.enabled`: マルチアカウント channel 用のアカウントごとのオーバーライド。設定されている場合、channel レベルのオーバーライドより優先されます。 +- ローカル Gateway 呼び出しパスでは、`gateway.auth.*` が未設定の場合にのみ `gateway.remote.*` をフォールバックとして使えます。 +- `gateway.auth.token` / `gateway.auth.password` が SecretRef 経由で明示設定されていて未解決の場合、解決はフェイルクローズします（リモートフォールバックで隠蔽されません）。 +- `trustedProxies`: TLS を終端する、または転送クライアントヘッダーを注入する reverse proxy の IP。自分が管理する proxy のみを列挙してください。loopback エントリは、同一ホスト proxy/ローカル検出構成（たとえば Tailscale Serve やローカル reverse proxy）では依然有効ですが、loopback リクエストが `gateway.auth.mode: "trusted-proxy"` の対象になるわけでは**ありません**。 +- `allowRealIpFallback`: `true` の場合、`X-Forwarded-For` がないときに `X-Real-IP` を受け入れます。デフォルトは、フェイルクローズ動作のため `false` です。 +- `gateway.tools.deny`: HTTP `POST /tools/invoke` に対して追加でブロックする tool 名（デフォルト deny リストを拡張）。 +- `gateway.tools.allow`: デフォルトの HTTP deny リストから tool 名を除外します。 -### OpenAI 互換エンドポイント +### OpenAI 互換 endpoint - Chat Completions: デフォルトでは無効です。`gateway.http.endpoints.chatCompletions.enabled: true` で有効にします。 - Responses API: `gateway.http.endpoints.responses.enabled`。 -- Responses の URL 入力ハードニング: +- Responses の URL 入力 hardening: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` 空の allowlist は未設定として扱われます。URL 取得を無効にするには `gateway.http.endpoints.responses.files.allowUrl=false` - および/または `gateway.http.endpoints.responses.images.allowUrl=false` を使用してください。 -- 任意の応答ハードニングヘッダー: - - `gateway.http.securityHeaders.strictTransportSecurity`（自分で管理する HTTPS origin に対してのみ設定してください。 [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts) を参照） + および/または `gateway.http.endpoints.responses.images.allowUrl=false` を使ってください。 +- 任意のレスポンス hardening ヘッダー: + - `gateway.http.securityHeaders.strictTransportSecurity`（自分が制御する HTTPS origin に対してのみ設定。 [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts) を参照） ### マルチインスタンス分離 -1 台のホストで、ポートと state ディレクトリを一意にして複数の gateway を実行します: +1 台のホストで複数の Gateway を、固有のポートと状態ディレクトリで実行します: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2994,7 +3116,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -便利なフラグ: `--dev`（`~/.openclaw-dev` + port `19001` を使用）、`--profile `（`~/.openclaw-` を使用）。 +便利なフラグ: `--dev`（`~/.openclaw-dev` + ポート `19001` を使用）、`--profile `（`~/.openclaw-` を使用）。 [Multiple Gateways](/ja-JP/gateway/multiple-gateways) を参照してください。 @@ -3014,11 +3136,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: gateway リスナーで TLS 終端（HTTPS/WSS）を有効にします（デフォルト: `false`）。 -- `autoGenerate`: 明示的なファイルが設定されていない場合に、ローカル自己署名 cert/key ペアを自動生成します。local/dev 用のみです。 +- `enabled`: Gateway リスナーで TLS 終端（HTTPS/WSS）を有効にします（デフォルト: `false`）。 +- `autoGenerate`: 明示的なファイルが設定されていない場合に、ローカルの自己署名 cert/key ペアを自動生成します。ローカル/開発用途専用です。 - `certPath`: TLS 証明書ファイルへのファイルシステムパス。 -- `keyPath`: TLS 秘密鍵ファイルへのファイルシステムパス。権限を制限してください。 -- `caPath`: クライアント検証またはカスタム trust chain 用の任意の CA バンドルパス。 +- `keyPath`: TLS 秘密鍵ファイルへのファイルシステムパス。権限制限を維持してください。 +- `caPath`: クライアント検証またはカスタム信頼チェーン用の任意の CA バンドルパス。 ### `gateway.reload` @@ -3034,13 +3156,13 @@ openclaw gateway --port 19001 } ``` -- `mode`: config 編集をランタイムでどのように適用するかを制御します。 +- `mode`: 設定編集をランタイムでどのように適用するかを制御します。 - `"off"`: ライブ編集を無視します。変更には明示的な再起動が必要です。 - - `"restart"`: config 変更時に常に gateway プロセスを再起動します。 + - `"restart"`: 設定変更時に常に Gateway プロセスを再起動します。 - `"hot"`: 再起動せずにプロセス内で変更を適用します。 - - `"hybrid"`（デフォルト）: まず hot reload を試し、必要なら再起動にフォールバックします。 -- `debounceMs`: config 変更を適用する前の debounce ウィンドウ（ms）（非負整数）。 -- `deferralTimeoutMs`: 進行中の操作を待ってから強制再起動するまでの最大時間（ms）（デフォルト: `300000` = 5 分）。 + - `"hybrid"`（デフォルト）: まず hot reload を試し、必要であれば restart にフォールバックします。 +- `debounceMs`: 設定変更を適用する前の debounce ウィンドウ（ms）（非負整数）。 +- `deferralTimeoutMs`: 進行中の操作を待ってから再起動を強制するまでの最大時間（ms）（デフォルト: `300000` = 5 分）。 --- @@ -3082,36 +3204,36 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 検証と安全性に関する注意: -- `hooks.enabled=true` には空でない `hooks.token` が必要です。 -- `hooks.token` は `gateway.auth.token` と**異なる**必要があります。Gateway token の再利用は拒否されます。 -- `hooks.path` は `/` にできません。`/hooks` のような専用サブパスを使用してください。 -- `hooks.allowRequestSessionKey=true` の場合、`hooks.allowedSessionKeyPrefixes`（たとえば `["hook:"]`）で制限してください。 +- `hooks.enabled=true` には、空でない `hooks.token` が必要です。 +- `hooks.token` は `gateway.auth.token` と**異なっている必要があります**。Gateway token の再利用は拒否されます。 +- `hooks.path` は `/` にできません。`/hooks` のような専用サブパスを使ってください。 +- `hooks.allowRequestSessionKey=true` の場合は、`hooks.allowedSessionKeyPrefixes` を制限してください（例: `["hook:"]`）。 -**エンドポイント:** +**Endpoints:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - リクエストペイロードの `sessionKey` は、`hooks.allowRequestSessionKey=true` の場合のみ受け付けられます（デフォルト: `false`）。 -- `POST /hooks/` → `hooks.mappings` により解決されます + - リクエスト payload の `sessionKey` は、`hooks.allowRequestSessionKey=true` の場合にのみ受け付けられます（デフォルト: `false`）。 +- `POST /hooks/` → `hooks.mappings` 経由で解決されます - + - `match.path` は `/hooks` の後のサブパスに一致します（例: `/hooks/gmail` → `gmail`）。 -- `match.source` は汎用パス用のペイロードフィールドに一致します。 -- `{{messages[0].subject}}` のようなテンプレートはペイロードから読み取ります。 -- `transform` は、hook action を返す JS/TS モジュールを指すことができます。 - - `transform.module` は相対パスでなければならず、`hooks.transformsDir` 内に留まる必要があります（絶対パスと traversal は拒否されます）。 -- `agentId` は特定の agent にルーティングします。不明な ID はデフォルトにフォールバックします。 +- `match.source` は汎用パス用の payload フィールドに一致します。 +- `{{messages[0].subject}}` のようなテンプレートは payload から読み取ります。 +- `transform` は、hook アクションを返す JS/TS module を指せます。 + - `transform.module` は相対パスである必要があり、`hooks.transformsDir` 内にとどまります（絶対パスと path traversal は拒否されます）。 +- `agentId` は特定の agent にルーティングします。不明な ID はデフォルトへフォールバックします。 - `allowedAgentIds`: 明示的なルーティングを制限します（`*` または省略 = すべて許可、`[]` = すべて拒否）。 -- `defaultSessionKey`: 明示的な `sessionKey` を持たない hook agent 実行用の任意の固定 session key。 -- `allowRequestSessionKey`: `/hooks/agent` の呼び出し元が `sessionKey` を設定できるようにします（デフォルト: `false`）。 -- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（リクエスト + マッピング）用の任意のプレフィックス許可リストです。例: `["hook:"]`。 +- `defaultSessionKey`: 明示的な `sessionKey` がない hook agent 実行用の任意の固定 session key。 +- `allowRequestSessionKey`: `/hooks/agent` 呼び出し元が `sessionKey` を設定できるようにします（デフォルト: `false`）。 +- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（リクエスト + マッピング）用の任意の接頭辞 allowlist。例: `["hook:"]`。 - `deliver: true` は最終返信を channel に送信します。`channel` のデフォルトは `last` です。 -- `model` はこの hook 実行用の LLM を上書きします（model カタログが設定されている場合は許可されている必要があります）。 +- `model` はこの hook 実行用の LLM を上書きします（model カタログが設定されている場合、許可されている必要があります）。 -### Gmail 連携 +### Gmail 統合 ```json5 { @@ -3134,8 +3256,8 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 } ``` -- 設定されている場合、Gateway は起動時に `gog gmail watch serve` を自動起動します。無効にするには `OPENCLAW_SKIP_GMAIL_WATCHER=1` を設定します。 -- Gateway と並行して別個の `gog gmail watch serve` を実行しないでください。 +- 設定されている場合、Gateway は起動時に `gog gmail watch serve` を自動起動します。無効にするには `OPENCLAW_SKIP_GMAIL_WATCHER=1` を設定してください。 +- Gateway と並行して別の `gog gmail watch serve` を実行しないでください。 --- @@ -3146,22 +3268,22 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // または OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- agent が編集可能な HTML/CSS/JS と A2UI を、Gateway port 配下の HTTP で提供します: +- agent が編集可能な HTML/CSS/JS と A2UI を、Gateway ポート配下の HTTP で配信します: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - ローカル専用: `gateway.bind: "loopback"`（デフォルト）のままにしてください。 -- loopback 以外の bind では、canvas ルートは他の Gateway HTTP サーフェスと同様に Gateway auth（token/password/trusted-proxy）を必要とします。 -- Node WebView は通常 auth ヘッダーを送信しません。node がペアリングされ接続されると、Gateway は canvas/A2UI アクセス用の node スコープ capability URL を通知します。 -- Capability URL はアクティブな node WS session に結び付けられており、すぐに期限切れになります。IP ベースのフォールバックは使用されません。 -- 提供される HTML に live-reload クライアントを注入します。 +- loopback 以外の bind では、canvas ルートにも他の Gateway HTTP サーフェスと同様に Gateway auth（token/password/trusted-proxy）が必要です。 +- Node WebViews は通常 auth ヘッダーを送信しません。node がペアリングされ接続されると、Gateway は canvas/A2UI アクセス用の node スコープ capability URL を通知します。 +- capability URL はアクティブな node WS セッションにバインドされ、すぐに期限切れになります。IP ベースのフォールバックは使われません。 +- 配信される HTML に live-reload クライアントを注入します。 - 空の場合はスターター `index.html` を自動作成します。 -- A2UI も `/__openclaw__/a2ui/` で提供します。 -- 変更には gateway の再起動が必要です。 +- A2UI も `/__openclaw__/a2ui/` で配信します。 +- 変更には Gateway の再起動が必要です。 - 大きなディレクトリや `EMFILE` エラーの場合は live reload を無効にしてください。 --- @@ -3182,7 +3304,7 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 - `minimal`（デフォルト）: TXT レコードから `cliPath` + `sshPort` を省略します。 - `full`: `cliPath` + `sshPort` を含めます。 -- hostname のデフォルトは `openclaw` です。`OPENCLAW_MDNS_HOSTNAME` で上書きします。 +- hostname のデフォルトは `openclaw`。上書きするには `OPENCLAW_MDNS_HOSTNAME` を使います。 ### 広域（DNS-SD） @@ -3194,7 +3316,7 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 } ``` -`~/.openclaw/dns/` 配下にユニキャスト DNS-SD ゾーンを書き込みます。ネットワークをまたぐ検出には、DNS サーバー（推奨: CoreDNS）+ Tailscale split DNS と組み合わせてください。 +`~/.openclaw/dns/` 配下にユニキャスト DNS-SD zone を書き込みます。ネットワーク間 discovery には、DNS サーバー（推奨: CoreDNS）+ Tailscale split DNS と組み合わせてください。 セットアップ: `openclaw dns setup --apply`。 @@ -3219,14 +3341,14 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 } ``` -- インライン env var は、process env にそのキーがない場合にのみ適用されます。 -- `.env` ファイル: CWD の `.env` + `~/.openclaw/.env`（どちらも既存の var を上書きしません）。 -- `shellEnv`: login shell profile から不足している想定キーをインポートします。 +- インライン env vars は、プロセス env にそのキーが存在しない場合にのみ適用されます。 +- `.env` ファイル: カレントディレクトリの `.env` + `~/.openclaw/.env`（どちらも既存の変数は上書きしません）。 +- `shellEnv`: ログイン shell プロファイルから、足りない想定キーを取り込みます。 - 完全な優先順位は [Environment](/ja-JP/help/environment) を参照してください。 ### Env var 置換 -任意の config 文字列で `${VAR_NAME}` により env var を参照できます: +任意の設定文字列で `${VAR_NAME}` を使って env vars を参照できます: ```json5 { @@ -3237,19 +3359,19 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 ``` - 一致するのは大文字名のみです: `[A-Z_][A-Z0-9_]*`。 -- 欠落または空の var は config 読み込み時にエラーになります。 -- リテラルの `${VAR}` にするには `$${VAR}` でエスケープします。 -- `$include` とともに動作します。 +- 変数が欠落している、または空の場合、設定読み込み時にエラーになります。 +- リテラルの `${VAR}` にするには `$${VAR}` でエスケープしてください。 +- `$include` でも動作します。 --- ## Secrets -Secret ref は加算的です。平文値も引き続き動作します。 +Secret refs は加算的です。プレーンテキスト値も引き続き使えます。 ### `SecretRef` -1 つのオブジェクト形を使用します: +次の 1 つのオブジェクト形を使います: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3261,13 +3383,13 @@ Secret ref は加算的です。平文値も引き続き動作します。 - `source: "env"` の id パターン: `^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` の id: 絶対 JSON pointer（例: `"/providers/openai/apiKey"`） - `source: "exec"` の id パターン: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` の id には `.` または `..` のスラッシュ区切りパスセグメントを含めてはなりません（例: `a/../b` は拒否されます） +- `source: "exec"` の id には、`.` または `..` のスラッシュ区切りパスセグメントを含めてはいけません（例: `a/../b` は拒否されます） -### 対応する認証情報サーフェス +### サポートされる認証情報サーフェス -- 正規マトリクス: [SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface) -- `secrets apply` は、対応する `openclaw.json` の認証情報パスを対象にします。 -- `auth-profiles.json` の ref はランタイム解決と監査範囲にも含まれます。 +- 正規の一覧: [SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface) +- `secrets apply` は、サポートされる `openclaw.json` の認証情報パスを対象にします。 +- `auth-profiles.json` の refs もランタイム解決と監査対象に含まれます。 ### Secret provider 設定 @@ -3275,7 +3397,7 @@ Secret ref は加算的です。平文値も引き続き動作します。 { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // 任意の明示的 env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3299,13 +3421,13 @@ Secret ref は加算的です。平文値も引き続き動作します。 注意: -- `file` provider は `mode: "json"` と `mode: "singleValue"` をサポートします（singleValue モードでは `id` は `"value"` でなければなりません）。 -- `exec` provider は絶対 `command` パスを必要とし、stdin/stdout 上でプロトコルペイロードを使用します。 -- デフォルトでは、symlink の command パスは拒否されます。解決後のターゲットパスを検証しつつ symlink パスを許可するには `allowSymlinkCommand: true` を設定します。 +- `file` provider は `mode: "json"` と `mode: "singleValue"` をサポートします（singleValue mode では `id` は `"value"` でなければなりません）。 +- `exec` provider には絶対 `command` パスが必要で、stdin/stdout 上のプロトコル payload を使用します。 +- デフォルトでは symlink の command パスは拒否されます。解決後のターゲットパスを検証しつつ symlink パスを許可するには `allowSymlinkCommand: true` を設定してください。 - `trustedDirs` が設定されている場合、trusted-dir チェックは解決後のターゲットパスに適用されます。 - `exec` 子プロセス環境はデフォルトで最小限です。必要な変数は `passEnv` で明示的に渡してください。 -- Secret ref はアクティベーション時にメモリ内スナップショットへ解決され、その後リクエストパスはそのスナップショットのみを読み取ります。 -- アクティブサーフェスフィルタリングはアクティベーション中に適用されます: 有効サーフェス上の未解決 ref は起動/リロードを失敗させ、非アクティブサーフェスは診断付きでスキップされます。 +- Secret refs は有効化時にメモリ内スナップショットへ解決され、その後のリクエストパスはそのスナップショットだけを読みます。 +- アクティブサーフェスフィルタリングは有効化中に適用されます。有効なサーフェス上の未解決 refs は起動/リロードを失敗させ、非アクティブなサーフェスは診断付きでスキップされます。 --- @@ -3327,13 +3449,13 @@ Secret ref は加算的です。平文値も引き続き動作します。 } ``` -- agent ごとの profile は `/auth-profiles.json` に保存されます。 -- `auth-profiles.json` は、静的認証モード向けの値レベル ref（`api_key` には `keyRef`、`token` には `tokenRef`）をサポートします。 -- OAuth モード profile（`auth.profiles..mode = "oauth"`）は、SecretRef ベースの auth-profile 認証情報をサポートしません。 -- 静的ランタイム認証情報は、メモリ内で解決済みのスナップショットから取得されます。レガシーな静的 `auth.json` エントリは見つかった場合に除去されます。 -- レガシー OAuth は `~/.openclaw/credentials/oauth.json` からインポートされます。 +- agent ごとの profiles は `/auth-profiles.json` に保存されます。 +- `auth-profiles.json` は、静的認証モード用の値レベル refs（`api_key` には `keyRef`、`token` には `tokenRef`）をサポートします。 +- OAuth モード profile（`auth.profiles..mode = "oauth"`）は、SecretRef バックの auth-profile 認証情報をサポートしません。 +- 静的ランタイム認証情報はメモリ内の解決済みスナップショットから取得され、従来の静的 `auth.json` エントリは見つかると除去されます。 +- 従来の OAuth インポート元は `~/.openclaw/credentials/oauth.json` です。 - [OAuth](/ja-JP/concepts/oauth) を参照してください。 -- Secrets ランタイム動作および `audit/configure/apply` ツール: [Secrets Management](/ja-JP/gateway/secrets)。 +- Secrets ランタイム動作と `audit/configure/apply` ツール群: [Secrets Management](/ja-JP/gateway/secrets)。 ### `auth.cooldowns` @@ -3355,15 +3477,21 @@ Secret ref は加算的です。平文値も引き続き動作します。 } ``` -- `billingBackoffHours`: profile が真の請求/残高不足エラーで失敗したときの基本バックオフ時間（時間）（デフォルト: `5`）。明示的な billing テキストは `401`/`403` 応答でもここに分類されることがありますが、provider 固有のテキストマッチャーは、それを所有する provider に限定されたままです（例: OpenRouter の `Key limit exceeded`）。再試行可能な HTTP `402` の使用量ウィンドウまたは organization/workspace の支出上限メッセージは、代わりに `rate_limit` パスに残ります。 -- `billingBackoffHoursByProvider`: 請求バックオフ時間の任意の provider ごとの上書き。 -- `billingMaxHours`: billing バックオフの指数増加の上限時間（デフォルト: `24`）。 -- `authPermanentBackoffMinutes`: 高信頼な `auth_permanent` 失敗用の基本バックオフ時間（分）（デフォルト: `10`）。 -- `authPermanentMaxMinutes`: `auth_permanent` バックオフ増加の上限分数（デフォルト: `60`）。 -- `failureWindowHours`: バックオフカウンターに使用されるローリングウィンドウ時間（デフォルト: `24`）。 -- `overloadedProfileRotations`: 過負荷エラーに対して model フォールバックへ切り替える前に行う、同一 provider の auth-profile ローテーション最大回数（デフォルト: `1`）。`ModelNotReadyException` のような provider-busy 形状はここに分類されます。 -- `overloadedBackoffMs`: 過負荷の provider/profile ローテーションを再試行する前の固定遅延時間（ミリ秒）（デフォルト: `0`）。 -- `rateLimitedProfileRotations`: rate-limit エラーに対して model フォールバックへ切り替える前に行う、同一 provider の auth-profile ローテーション最大回数（デフォルト: `1`）。その rate-limit バケットには、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` などの provider 形状テキストが含まれます。 +- `billingBackoffHours`: 真の + billing/insufficient-credit エラーで profile が失敗したときの基本バックオフ時間（時）（デフォルト: `5`）。明示的な billing テキストは + `401`/`403` 応答でもここに入ることがありますが、provider 固有のテキスト + マッチャーはその provider に属するものだけに限定されます（例: OpenRouter の + `Key limit exceeded`）。再試行可能な HTTP `402` の使用量ウィンドウや + organization/workspace 支出上限メッセージは、代わりに `rate_limit` パス + に残ります。 +- `billingBackoffHoursByProvider`: billing バックオフ時間の任意の provider ごとの上書き。 +- `billingMaxHours`: billing バックオフ指数増加の上限時間（時）（デフォルト: `24`）。 +- `authPermanentBackoffMinutes`: 高信頼の `auth_permanent` 失敗に対する基本バックオフ時間（分）（デフォルト: `10`）。 +- `authPermanentMaxMinutes`: `auth_permanent` バックオフ増加の上限時間（分）（デフォルト: `60`）。 +- `failureWindowHours`: バックオフカウンターに使うローリングウィンドウ時間（時）（デフォルト: `24`）。 +- `overloadedProfileRotations`: overloaded エラーで model フォールバックに切り替える前に行う、同一 provider 内 auth-profile ローテーションの最大回数（デフォルト: `1`）。`ModelNotReadyException` のような provider busy 形状はここに入ります。 +- `overloadedBackoffMs`: overloaded な provider/profile ローテーションを再試行する前の固定遅延（デフォルト: `0`）。 +- `rateLimitedProfileRotations`: rate-limit エラーで model フォールバックに切り替える前に行う、同一 provider 内 auth-profile ローテーションの最大回数（デフォルト: `1`）。その rate-limit バケットには、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` のような provider 由来テキストも含まれます。 --- @@ -3383,9 +3511,9 @@ Secret ref は加算的です。平文値も引き続き動作します。 ``` - デフォルトのログファイル: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 安定したパスには `logging.file` を設定してください。 -- `consoleLevel` は `--verbose` のとき `debug` に引き上げられます。 -- `maxFileBytes`: 書き込み抑止前の最大ログファイルサイズ（バイト）（正の整数。デフォルト: `524288000` = 500 MB）。本番デプロイでは外部ログローテーションを使用してください。 +- 安定したパスにするには `logging.file` を設定してください。 +- `consoleLevel` は `--verbose` で `debug` に上がります。 +- `maxFileBytes`: 書き込みを抑止する前の最大ログファイルサイズ（バイト）（正の整数。デフォルト: `524288000` = 500 MB）。本番デプロイでは外部ログローテーションを使ってください。 --- @@ -3422,20 +3550,20 @@ Secret ref は加算的です。平文値も引き続き動作します。 } ``` -- `enabled`: 計測出力のマスタートグルです（デフォルト: `true`）。 -- `flags`: 対象を絞ったログ出力を有効にするフラグ文字列の配列です（`"telegram.*"` や `"*"` のようなワイルドカードをサポート）。 -- `stuckSessionWarnMs`: session が処理状態のままである間に、stuck-session 警告を出力するための経過時間しきい値（ms）。 +- `enabled`: 計装出力のマスタートグルです（デフォルト: `true`）。 +- `flags`: 対象を絞ったログ出力を有効にするフラグ文字列の配列です（`"telegram.*"` や `"*"` のようなワイルドカードをサポートします）。 +- `stuckSessionWarnMs`: session が処理中状態のままの間に stuck-session 警告を出すための経過時間しきい値（ms）。 - `otel.enabled`: OpenTelemetry エクスポートパイプラインを有効にします（デフォルト: `false`）。 - `otel.endpoint`: OTel エクスポート用の collector URL。 - `otel.protocol`: `"http/protobuf"`（デフォルト）または `"grpc"`。 - `otel.headers`: OTel エクスポートリクエストとともに送信される追加の HTTP/gRPC メタデータヘッダー。 -- `otel.serviceName`: resource 属性用の service 名。 -- `otel.traces` / `otel.metrics` / `otel.logs`: trace、metrics、または log のエクスポートを有効にします。 +- `otel.serviceName`: リソース属性用のサービス名。 +- `otel.traces` / `otel.metrics` / `otel.logs`: trace、metrics、または log エクスポートを有効にします。 - `otel.sampleRate`: trace サンプリング率 `0`–`1`。 -- `otel.flushIntervalMs`: 定期的な telemetry flush 間隔（ms）。 +- `otel.flushIntervalMs`: 定期テレメトリ flush 間隔（ms）。 - `cacheTrace.enabled`: 埋め込み実行の cache trace スナップショットを記録します（デフォルト: `false`）。 - `cacheTrace.filePath`: cache trace JSONL の出力パス（デフォルト: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: cache trace 出力に何を含めるかを制御します（すべてデフォルト: `true`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: cache trace 出力に何を含めるかを制御します（すべてデフォルトは `true`）。 --- @@ -3458,11 +3586,11 @@ Secret ref は加算的です。平文値も引き続き動作します。 ``` - `channel`: npm/git インストール用のリリース channel — `"stable"`、`"beta"`、または `"dev"`。 -- `checkOnStart`: gateway 起動時に npm 更新を確認します（デフォルト: `true`）。 -- `auto.enabled`: package インストールのバックグラウンド自動更新を有効にします（デフォルト: `false`）。 -- `auto.stableDelayHours`: stable channel 自動適用までの最小遅延時間（時間）（デフォルト: `6`、最大: `168`）。 -- `auto.stableJitterHours`: stable channel ロールアウト分散用の追加時間窓（時間）（デフォルト: `12`、最大: `168`）。 -- `auto.betaCheckIntervalHours`: beta channel の確認実行間隔（時間）（デフォルト: `1`、最大: `24`）。 +- `checkOnStart`: Gateway 起動時に npm アップデートを確認します（デフォルト: `true`）。 +- `auto.enabled`: package インストール用のバックグラウンド自動アップデートを有効にします（デフォルト: `false`）。 +- `auto.stableDelayHours`: stable channel の自動適用までの最小遅延時間（時）（デフォルト: `6`、最大: `168`）。 +- `auto.stableJitterHours`: stable channel ロールアウトの追加分散ウィンドウ時間（時）（デフォルト: `12`、最大: `168`）。 +- `auto.betaCheckIntervalHours`: beta channel の確認を実行する間隔（時）（デフォルト: `1`、最大: `24`）。 --- @@ -3496,21 +3624,21 @@ Secret ref は加算的です。平文値も引き続き動作します。 ``` - `enabled`: グローバル ACP 機能ゲート（デフォルト: `false`）。 -- `dispatch.enabled`: ACP session ターン dispatch 用の独立したゲートです（デフォルト: `true`）。ACP コマンドを利用可能なまま実行をブロックするには `false` を設定します。 -- `backend`: デフォルトの ACP ランタイム backend id（登録済み ACP ランタイム Plugin と一致する必要があります）。 -- `defaultAgent`: spawn が明示的なターゲットを指定しない場合のフォールバック ACP ターゲット agent id。 -- `allowedAgents`: ACP ランタイム session に許可される agent id の許可リストです。空は追加制限なしを意味します。 -- `maxConcurrentSessions`: 同時にアクティブにできる ACP session の最大数。 -- `stream.coalesceIdleMs`: ストリームされたテキスト用のアイドル flush ウィンドウ（ms）。 -- `stream.maxChunkChars`: ストリームされたブロック投影を分割する前の最大チャンクサイズ。 +- `dispatch.enabled`: ACP session ターンディスパッチ用の独立したゲート（デフォルト: `true`）。ACP コマンドは利用可能なまま実行だけをブロックしたい場合は `false` に設定します。 +- `backend`: デフォルト ACP ランタイムバックエンド id（登録済み ACP ランタイム Plugin と一致している必要があります）。 +- `defaultAgent`: spawn 時に明示的なターゲットが指定されない場合のフォールバック ACP ターゲット agent id。 +- `allowedAgents`: ACP ランタイム session に許可される agent id の allowlist。空の場合は追加制限なしを意味します。 +- `maxConcurrentSessions`: 同時にアクティブになれる ACP session の最大数。 +- `stream.coalesceIdleMs`: ストリーミング text 用のアイドル flush ウィンドウ（ms）。 +- `stream.maxChunkChars`: ストリーミングされたブロック投影を分割する前の最大チャンクサイズ。 - `stream.repeatSuppression`: ターンごとの繰り返し status/tool 行を抑制します（デフォルト: `true`）。 -- `stream.deliveryMode`: `"live"` は増分的にストリームし、`"final_only"` はターン終端イベントまでバッファします。 -- `stream.hiddenBoundarySeparator`: 非表示 tool イベント後の可視テキスト前に入れるセパレータ（デフォルト: `"paragraph"`）。 -- `stream.maxOutputChars`: ACP ターンごとに投影される assistant 出力文字数の最大値。 +- `stream.deliveryMode`: `"live"` は段階的にストリーミングし、`"final_only"` はターン終端イベントまでバッファリングします。 +- `stream.hiddenBoundarySeparator`: 非表示 tool イベントの後、可視 text の前に入れる区切り（デフォルト: `"paragraph"`）。 +- `stream.maxOutputChars`: ACP ターンごとに投影される assistant 出力文字数の上限。 - `stream.maxSessionUpdateChars`: 投影される ACP status/update 行の最大文字数。 -- `stream.tagVisibility`: ストリームイベント用のタグ名から boolean 可視性上書きへの記録です。 +- `stream.tagVisibility`: ストリーミングイベント用のタグ名から boolean 可視性オーバーライドへの記録。 - `runtime.ttlMinutes`: クリーンアップ対象になるまでの ACP session worker のアイドル TTL（分）。 -- `runtime.installCommand`: ACP ランタイム環境をブートストラップするときに実行する任意の install command。 +- `runtime.installCommand`: ACP ランタイム環境をブートストラップするときに実行する任意の install コマンド。 --- @@ -3526,17 +3654,17 @@ Secret ref は加算的です。平文値も引き続き動作します。 } ``` -- `cli.banner.taglineMode` は banner の tagline スタイルを制御します: - - `"random"`（デフォルト）: ローテーションする面白い/季節限定 tagline。 - - `"default"`: 固定の中立的 tagline（`All your chats, one OpenClaw.`）。 - - `"off"`: tagline テキストなし（banner のタイトル/バージョンは引き続き表示）。 -- banner 全体を隠すには（tagline だけでなく）、env `OPENCLAW_HIDE_BANNER=1` を設定します。 +- `cli.banner.taglineMode` はバナーのタグラインスタイルを制御します: + - `"random"`（デフォルト）: ローテーションする面白い/季節限定タグライン。 + - `"default"`: 固定の中立タグライン（`All your chats, one OpenClaw.`）。 + - `"off"`: タグラインテキストなし（バナーのタイトル/バージョンは引き続き表示）。 +- バナー全体を隠すには（タグラインだけでなく）、env `OPENCLAW_HIDE_BANNER=1` を設定してください。 --- ## Wizard -CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doctor`）によって書き込まれるメタデータ: +CLI のガイド付きセットアップフロー（`onboard`、`configure`、`doctor`）によって書き込まれるメタデータ: ```json5 { @@ -3554,15 +3682,15 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct ## Identity -[Agent のデフォルト](#agent-defaults) の `agents.list` identity フィールドを参照してください。 +[Agent のデフォルト設定](#agent-defaults) の `agents.list` identity フィールドを参照してください。 --- -## Bridge（レガシー、削除済み） +## Bridge（legacy、削除済み） -現在のビルドには TCP bridge は含まれていません。Nodes は Gateway WebSocket 経由で接続します。`bridge.*` キーはもはや設定スキーマの一部ではありません（削除するまで検証は失敗します。`openclaw doctor --fix` で未知のキーを取り除けます）。 +現在のビルドには TCP bridge は含まれていません。Nodes は Gateway WebSocket 経由で接続します。`bridge.*` キーはもはや設定 schema の一部ではありません（削除するまで検証は失敗します。`openclaw doctor --fix` で不明キーを除去できます）。 - + ```json { @@ -3589,22 +3717,22 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // 非推奨: 保存済み notify:true ジョブ用のフォールバック + webhookToken: "replace-with-dedicated-token", // 任意: outbound webhook auth 用 bearer token + sessionRetention: "24h", // duration 文字列または false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // デフォルト 2_000_000 bytes + keepLines: 2000, // デフォルト 2000 }, }, } ``` -- `sessionRetention`: 完了した分離 cron 実行 session を `sessions.json` から削除する前にどれだけ保持するか。アーカイブされた削除済み cron transcript のクリーンアップも制御します。デフォルト: `24h`。無効にするには `false` を設定します。 -- `runLog.maxBytes`: 削除前の実行ログファイルごとの最大サイズ（`cron/runs/.jsonl`）。デフォルト: `2_000_000` bytes。 -- `runLog.keepLines`: 実行ログの削除が発動したときに保持される最新行数。デフォルト: `2000`。 -- `webhookToken`: cron webhook POST 配信（`delivery.mode = "webhook"`）に使用される bearer token です。省略時は auth ヘッダーは送信されません。 -- `webhook`: 非推奨のレガシーフォールバック webhook URL（http/https）で、`notify: true` を持つ保存済みジョブに対してのみ使用されます。 +- `sessionRetention`: 完了済みの isolated cron 実行 session を `sessions.json` から pruning するまで保持する期間です。アーカイブされた削除済み cron transcript のクリーンアップも制御します。デフォルト: `24h`。無効にするには `false` を設定します。 +- `runLog.maxBytes`: pruning 前の実行ログファイルごとの最大サイズ（`cron/runs/.jsonl`）。デフォルト: `2_000_000` bytes。 +- `runLog.keepLines`: 実行ログの pruning が発動したときに保持される最新行数。デフォルト: `2000`。 +- `webhookToken`: cron webhook POST 配信（`delivery.mode = "webhook"`）に使う bearer token。省略した場合、auth ヘッダーは送信されません。 +- `webhook`: 非推奨の従来フォールバック webhook URL（http/https）。まだ `notify: true` を持つ保存済みジョブにのみ使われます。 ### `cron.retry` @@ -3620,11 +3748,11 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct } ``` -- `maxAttempts`: 一時的なエラー時にワンショットジョブに対して行う最大リトライ回数（デフォルト: `3`、範囲: `0`–`10`）。 -- `backoffMs`: 各リトライ試行に対するバックオフ遅延の ms 配列（デフォルト: `[30000, 60000, 300000]`、1〜10 エントリ）。 -- `retryOn`: リトライを発動するエラー種別 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略すると、すべての一時的種別をリトライします。 +- `maxAttempts`: 一過性エラー時の one-shot ジョブに対する最大 retry 回数（デフォルト: `3`、範囲: `0`–`10`）。 +- `backoffMs`: 各 retry 試行に対する backoff 遅延（ms）の配列（デフォルト: `[30000, 60000, 300000]`、1〜10 エントリ）。 +- `retryOn`: retry を引き起こすエラー種別 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略した場合、すべての一過性エラー種別を retry します。 -これはワンショット cron ジョブにのみ適用されます。繰り返しジョブでは別の失敗処理を使用します。 +これは one-shot cron ジョブにのみ適用されます。定期ジョブでは別の失敗処理が使われます。 ### `cron.failureAlert` @@ -3644,9 +3772,9 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct - `enabled`: cron ジョブの失敗アラートを有効にします（デフォルト: `false`）。 - `after`: アラート発火までの連続失敗回数（正の整数、最小: `1`）。 -- `cooldownMs`: 同じジョブに対する繰り返しアラートの最小間隔（ミリ秒）（非負整数）。 +- `cooldownMs`: 同じジョブに対して繰り返しアラートを出すまでの最小間隔（ミリ秒）（非負整数）。 - `mode`: 配信モード — `"announce"` は channel メッセージで送信し、`"webhook"` は設定済み webhook に POST します。 -- `accountId`: アラート配信のスコープを限定する任意の account または channel id。 +- `accountId`: アラート配信のスコープを絞る任意の account または channel id。 ### `cron.failureDestination` @@ -3663,51 +3791,51 @@ CLI ガイド付きセットアップフロー（`onboard`、`configure`、`doct } ``` -- すべてのジョブに対する cron 失敗通知のデフォルト宛先です。 -- `mode`: `"announce"` または `"webhook"`。十分なターゲット情報が存在する場合のデフォルトは `"announce"` です。 -- `channel`: announce 配信用の channel 上書き。`"last"` は最後に既知だった配信 channel を再利用します。 -- `to`: 明示的な announce ターゲットまたは webhook URL。webhook モードでは必須です。 -- `accountId`: 配信用の任意の account 上書き。 +- すべてのジョブに共通する、cron 失敗通知のデフォルト送信先です。 +- `mode`: `"announce"` または `"webhook"`。十分なターゲットデータが存在する場合、デフォルトは `"announce"` です。 +- `channel`: announce 配信用の channel オーバーライド。`"last"` は最後に使われた配信 channel を再利用します。 +- `to`: 明示的な announce ターゲットまたは webhook URL。webhook mode では必須です。 +- `accountId`: 配信用の任意の account オーバーライド。 - ジョブごとの `delivery.failureDestination` はこのグローバルデフォルトを上書きします。 -- グローバルにもジョブごとにも failure destination が設定されていない場合、すでに `announce` で配信するジョブは、失敗時にその主要な announce ターゲットへフォールバックします。 -- `delivery.failureDestination` は、ジョブの主要 `delivery.mode` が `"webhook"` でない限り、`sessionTarget="isolated"` ジョブでのみサポートされます。 +- グローバルにもジョブごとにも失敗送信先が設定されていない場合、すでに `announce` で配信するジョブは、失敗時にそのプライマリ announce ターゲットへフォールバックします。 +- `delivery.failureDestination` は、ジョブのプライマリ `delivery.mode` が `"webhook"` の場合を除き、`sessionTarget="isolated"` ジョブでのみサポートされます。 -[Cron Jobs](/ja-JP/automation/cron-jobs) を参照してください。分離された cron 実行は [background tasks](/ja-JP/automation/tasks) として追跡されます。 +[Cron Jobs](/ja-JP/automation/cron-jobs) を参照してください。isolated cron 実行は [background tasks](/ja-JP/automation/tasks) として追跡されます。 --- -## メディア model テンプレート変数 +## Media model テンプレート変数 `tools.media.models[].args` で展開されるテンプレートプレースホルダー: -| Variable | 説明 | +| 変数 | 説明 | | ------------------ | ----------------------------------------- | -| `{{Body}}` | 完全な受信メッセージ本文 | +| `{{Body}}` | 受信メッセージ本文全体 | | `{{RawBody}}` | 生の本文（履歴/送信者ラッパーなし） | -| `{{BodyStripped}}` | グループ mention を除去した本文 | +| `{{BodyStripped}}` | グループメンションを除去した本文 | | `{{From}}` | 送信者識別子 | | `{{To}}` | 宛先識別子 | | `{{MessageSid}}` | channel メッセージ id | | `{{SessionId}}` | 現在の session UUID | -| `{{IsNewSession}}` | 新しい session が作成されたとき `"true"` | -| `{{MediaUrl}}` | 受信メディアの疑似 URL | -| `{{MediaPath}}` | ローカルメディアパス | -| `{{MediaType}}` | メディア種別（image/audio/document/…） | +| `{{IsNewSession}}` | 新しい session が作成された場合 `"true"` | +| `{{MediaUrl}}` | 受信 media の擬似 URL | +| `{{MediaPath}}` | ローカル media パス | +| `{{MediaType}}` | media タイプ（image/audio/document/…） | | `{{Transcript}}` | 音声 transcript | -| `{{Prompt}}` | CLI エントリ用に解決されたメディア prompt | +| `{{Prompt}}` | CLI エントリ用に解決された media prompt | | `{{MaxChars}}` | CLI エントリ用に解決された最大出力文字数 | | `{{ChatType}}` | `"direct"` または `"group"` | -| `{{GroupSubject}}` | グループ subject（best effort） | -| `{{GroupMembers}}` | グループメンバープレビュー（best effort） | -| `{{SenderName}}` | 送信者表示名（best effort） | -| `{{SenderE164}}` | 送信者電話番号（best effort） | +| `{{GroupSubject}}` | グループ件名（ベストエフォート） | +| `{{GroupMembers}}` | グループメンバーのプレビュー（ベストエフォート） | +| `{{SenderName}}` | 送信者表示名（ベストエフォート） | +| `{{SenderE164}}` | 送信者電話番号（ベストエフォート） | | `{{Provider}}` | provider ヒント（whatsapp、telegram、discord など） | --- ## Config include（`$include`） -config を複数ファイルに分割します: +設定を複数ファイルに分割できます: ```json5 // ~/.openclaw/openclaw.json @@ -3723,11 +3851,11 @@ config を複数ファイルに分割します: **マージ動作:** - 単一ファイル: そのオブジェクト全体を置き換えます。 -- ファイル配列: 順に deep-merge されます（後のものが前のものを上書き）。 -- 兄弟キー: include の後にマージされます（include された値を上書き）。 -- ネストされた include: 最大 10 階層まで。 -- パス: include 元ファイルからの相対で解決されますが、トップレベル config ディレクトリ（`openclaw.json` の `dirname`）内に留まる必要があります。絶対パス/`../` 形式は、その境界内に解決される場合にのみ許可されます。 -- エラー: ファイル欠落、パースエラー、循環 include に対して明確なメッセージが表示されます。 +- ファイル配列: 順番に deep merge されます（後ろのものが前を上書き）。 +- 同階層キー: include の後にマージされます（include された値を上書き）。 +- ネストした include: 最大 10 レベル。 +- パス: include 元ファイルからの相対で解決されますが、トップレベル設定ディレクトリ（`openclaw.json` の `dirname`）内に収まっている必要があります。絶対パスや `../` 形式も、最終的にその境界内に解決される場合にのみ許可されます。 +- エラー: 欠落ファイル、解析エラー、循環 include に対して明確なメッセージが出ます。 --- diff --git a/docs/ja-JP/plugins/sdk-channel-plugins.md b/docs/ja-JP/plugins/sdk-channel-plugins.md index ef0c7d725..aedc4d532 100644 --- a/docs/ja-JP/plugins/sdk-channel-plugins.md +++ b/docs/ja-JP/plugins/sdk-channel-plugins.md @@ -2,91 +2,86 @@ read_when: - 新しいメッセージングチャネルPluginを構築しています - OpenClawをメッセージングプラットフォームに接続したいと考えています - - ChannelPluginアダプターの公開インターフェースを理解する必要があります + - ChannelPluginアダプターの表面を理解する必要があります sidebarTitle: Channel Plugins -summary: OpenClaw向けメッセージングチャネルPluginを構築するためのステップバイステップガイド +summary: OpenClaw向けメッセージングチャネルPluginを構築するためのステップごとのガイド title: チャネルPluginの構築 x-i18n: - generated_at: "2026-04-15T04:43:33Z" + generated_at: "2026-04-15T19:41:39Z" model: gpt-5.4 provider: openai - source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65 + source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # チャネルPluginの構築 -このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャネルPluginの構築方法を説明します。最後には、DMセキュリティ、ペアリング、返信スレッド化、送信メッセージングを備えた動作するチャネルが完成します。 +このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャネルpluginの構築方法を説明します。最終的には、DMセキュリティ、ペアリング、返信スレッド化、送信メッセージングを備えた動作するチャネルを完成させます。 - OpenClaw Pluginをまだ一度も構築したことがない場合は、基本的なパッケージ - 構造とマニフェスト設定について最初に + OpenClaw pluginをこれまでに一度も構築したことがない場合は、基本的なパッケージ構造とマニフェスト設定について、まず [はじめに](/ja-JP/plugins/building-plugins)を読んでください。 ## チャネルPluginの仕組み -チャネルPluginには独自の送信・編集・リアクション用ツールは不要です。OpenClawはコアで1つの共有`message`ツールを維持します。Pluginが担当するのは次の項目です。 +チャネルpluginには、独自の送信・編集・リアクションツールは不要です。OpenClawは、コアに1つの共有`message`ツールを保持しています。pluginが担うのは次の項目です。 -- **設定** — アカウント解決とセットアップウィザード -- **セキュリティ** — DMポリシーと許可リスト -- **ペアリング** — DM承認フロー -- **セッショングラマー** — プロバイダー固有の会話idをベースチャット、スレッドid、親フォールバックにどう対応付けるか -- **送信** — テキスト、メディア、投票をプラットフォームに送信すること -- **スレッド化** — 返信をどうスレッド化するか +- **Config** — アカウント解決とセットアップウィザード +- **Security** — DMポリシーと許可リスト +- **Pairing** — DM承認フロー +- **Session grammar** — プロバイダー固有の会話IDを、ベースチャット、スレッドID、親フォールバックにどのように対応付けるか +- **Outbound** — テキスト、メディア、投票をプラットフォームへ送信すること +- **Threading** — 返信をどのようにスレッド化するか -コアは共有messageツール、プロンプト配線、外側のセッションキー形状、汎用的な`:thread:`管理、およびディスパッチを担当します。 +コアは、共有messageツール、プロンプト配線、外側のセッションキー形状、汎用的な`:thread:`管理、ディスパッチを担います。 -チャネルでメディアソースを運ぶmessage-toolパラメータを追加する場合は、それらの -パラメータ名を`describeMessageTool(...).mediaSourceParams`を通じて公開してください。コアはその明示的な一覧をサンドボックスパス正規化と送信メディアアクセスポリシーに使用するため、Plugin側でプロバイダー固有のアバター、添付ファイル、カバー画像パラメータに対して共有コアの特別扱いは不要です。 -可能であれば、`{ "set-profile": ["avatarUrl", "avatarPath"] }`のようなアクションキー付きマップを返してください。そうすることで、無関係なアクションが別アクションのメディア引数を継承しません。意図的に公開されるすべてのアクションで共有するパラメータであれば、フラットな配列でも引き続き使用できます。 +チャネルがメディアソースを運ぶmessage-toolパラメーターを追加する場合は、それらのパラメーター名を`describeMessageTool(...).mediaSourceParams`を通じて公開してください。コアはその明示的なリストを、サンドボックスパスの正規化と送信メディアアクセス方針に使用するため、plugin側でプロバイダー固有のアバター、添付ファイル、またはカバー画像パラメーターのために共有コアの特別扱いを追加する必要はありません。 +できれば、`{ "set-profile": ["avatarUrl", "avatarPath"] }`のようなアクションキー付きマップを返してください。そうすることで、無関係なアクションが別のアクションのメディア引数を継承しません。意図的にすべての公開アクションで共有されるパラメーターであれば、フラットな配列でも引き続き利用できます。 -プラットフォームが会話id内に追加のスコープを格納する場合は、その解析を -`messaging.resolveSessionConversation(...)`でPlugin内に保持してください。これは、`rawId`をベース会話id、任意のスレッドid、明示的な`baseConversationId`、および任意の`parentConversationCandidates`に対応付けるための正規のフックです。 -`parentConversationCandidates`を返す場合は、最も狭い親から最も広い親/ベース会話の順に並べてください。 +プラットフォームが会話IDの中に追加のスコープを保存する場合は、その解析をplugin内で`messaging.resolveSessionConversation(...)`を使って行ってください。これは、`rawId`をベース会話ID、任意のスレッドID、明示的な`baseConversationId`、および任意の`parentConversationCandidates`に対応付けるための正規のフックです。 +`parentConversationCandidates`を返す場合は、最も狭い親から最も広い/ベース会話までの順に並べてください。 -チャネルレジストリの起動前に同じ解析が必要な同梱Pluginでは、対応する -`resolveSessionConversation(...)`エクスポートを持つトップレベルの`session-key-api.ts`ファイルも公開できます。コアは、実行時Pluginレジストリがまだ利用できない場合にのみ、このブートストラップ安全な公開インターフェースを使用します。 +チャネルレジストリが起動する前に同じ解析を必要とする同梱pluginは、一致する`resolveSessionConversation(...)`エクスポートを持つトップレベルの`session-key-api.ts`ファイルも公開できます。コアは、実行時pluginレジストリがまだ利用できない場合に限って、このブートストラップ安全なサーフェスを使用します。 -`messaging.resolveParentConversationCandidates(...)`は、Pluginが汎用/raw idに加えて親フォールバックのみを必要とする場合の、従来の互換性フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず -`resolveSessionConversation(...).parentConversationCandidates`を使用し、その正規フックがそれらを省略した場合にのみ`resolveParentConversationCandidates(...)`へフォールバックします。 +`messaging.resolveParentConversationCandidates(...)`は、pluginが汎用/生のIDに加えて親フォールバックだけを必要とする場合の、レガシー互換フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず`resolveSessionConversation(...).parentConversationCandidates`を使用し、正規フックがそれらを省略した場合にのみ`resolveParentConversationCandidates(...)`へフォールバックします。 ## 承認とチャネル機能 -ほとんどのチャネルPluginでは、承認固有のコードは不要です。 +ほとんどのチャネルpluginでは、承認固有のコードは不要です。 -- コアは同一チャット内の`/approve`、共有承認ボタンのペイロード、および汎用フォールバック配信を担当します。 -- チャネルで承認固有の動作が必要な場合は、チャネルPlugin上に1つの`approvalCapability`オブジェクトを置くことを推奨します。 +- コアは、同一チャット内の`/approve`、共有承認ボタンのペイロード、汎用フォールバック配信を担います。 +- チャネルが承認固有の動作を必要とする場合は、チャネルplugin上で1つの`approvalCapability`オブジェクトを使うようにしてください。 - `ChannelPlugin.approvals`は削除されました。承認の配信/ネイティブ/レンダリング/認証に関する情報は`approvalCapability`に置いてください。 -- `plugin.auth`はlogin/logout専用です。コアはそのオブジェクトから承認認証フックを読み取らなくなりました。 -- `approvalCapability.authorizeActorAction`と`approvalCapability.getActionAvailabilityState`が正規の承認認証インターフェースです。 -- 同一チャット内の承認認証の可用性には`approvalCapability.getActionAvailabilityState`を使用してください。 -- チャネルがネイティブexec承認を公開する場合、開始サーフェス/ネイティブクライアント状態が同一チャット内承認認証と異なるときは、`approvalCapability.getExecInitiatingSurfaceState`を使用してください。コアはこのexec固有のフックを使用して`enabled`と`disabled`を区別し、開始チャネルがネイティブexec承認をサポートしているかを判断し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)`は一般的なケースに対してこれを補います。 -- 重複するローカル承認プロンプトの非表示や、配信前の入力中インジケーター送信のような、チャネル固有のペイロードライフサイクル動作には、`outbound.shouldSuppressLocalPayloadPrompt`または`outbound.beforeDeliverPayload`を使用してください。 +- `plugin.auth`はlogin/logout専用です。コアはもはやそのオブジェクトから承認認証フックを読み取りません。 +- `approvalCapability.authorizeActorAction`と`approvalCapability.getActionAvailabilityState`が、正規の承認認証シームです。 +- 同一チャット承認の認証可用性には`approvalCapability.getActionAvailabilityState`を使用してください。 +- チャネルがネイティブexec承認を公開する場合、開始サーフェス/ネイティブクライアント状態が同一チャット承認認証と異なるときは、`approvalCapability.getExecInitiatingSurfaceState`を使用してください。コアはこのexec固有フックを使って、開始チャネルがネイティブexec承認をサポートしているかどうかを判定し、`enabled`と`disabled`を区別し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)`は、一般的なケース向けにこれを補います。 +- 重複するローカル承認プロンプトの非表示や、配信前の入力中インジケーター送信など、チャネル固有のペイロードライフサイクル動作には、`outbound.shouldSuppressLocalPayloadPrompt`または`outbound.beforeDeliverPayload`を使用してください。 - `approvalCapability.delivery`は、ネイティブ承認ルーティングまたはフォールバック抑制にのみ使用してください。 -- チャネル所有のネイティブ承認情報には`approvalCapability.nativeRuntime`を使用してください。`createLazyChannelApprovalNativeRuntimeAdapter(...)`を使って、ホットなチャネルエントリーポイントではこれを遅延ロードにしてください。これにより、コアは承認ライフサイクルを組み立てつつ、必要時に実行時モジュールをimportできます。 -- 共有レンダラーではなく、チャネルが本当に独自の承認ペイロードを必要とする場合にのみ`approvalCapability.render`を使用してください。 -- チャネルが、無効時パスの返信でネイティブexec承認を有効化するために必要な正確な設定項目を説明したい場合は、`approvalCapability.describeExecApprovalSetup`を使用してください。このフックは`{ channel, channelLabel, accountId }`を受け取ります。名前付きアカウントのチャネルでは、トップレベルのデフォルトではなく、`channels..accounts..execApprovals.*`のようなアカウントスコープのパスを表示してください。 -- 既存設定から安定した所有者相当のDMアイデンティティを推測できるチャネルでは、承認固有のコアロジックを追加せずに同一チャット内の`/approve`を制限するため、`openclaw/plugin-sdk/approval-runtime`の`createResolvedApproverActionAuthAdapter`を使用してください。 -- チャネルにネイティブ承認配信が必要な場合、チャネルコードはターゲット正規化とトランスポート/プレゼンテーション情報に集中させてください。`openclaw/plugin-sdk/approval-runtime`の`createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability`を使用してください。チャネル固有の情報は`approvalCapability.nativeRuntime`の背後に置き、理想的には`createChannelApprovalNativeRuntimeAdapter(...)`または`createLazyChannelApprovalNativeRuntimeAdapter(...)`を通してください。これにより、コアはハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、有効期限、Gatewayサブスクリプション、別経路通知を担当できます。`nativeRuntime`はいくつかの小さなインターフェースに分割されています。 -- `availability` — アカウントが設定済みか、およびリクエストを処理すべきかどうか -- `presentation` — 共有承認ビューモデルを、保留/解決済み/期限切れのネイティブペイロードまたは最終アクションにマッピングする +- チャネル所有のネイティブ承認情報には`approvalCapability.nativeRuntime`を使用してください。ホットなチャネルエントリーポイントでは、`createLazyChannelApprovalNativeRuntimeAdapter(...)`でこれを遅延化してください。これにより、コアが承認ライフサイクルを組み立てつつ、必要時に実行時モジュールをimportできます。 +- チャネルが共有レンダラーの代わりに本当にカスタム承認ペイロードを必要とする場合にのみ、`approvalCapability.render`を使用してください。 +- チャネルが、無効パスの返信でネイティブexec承認を有効化するために必要な正確なconfigノブを説明したい場合は、`approvalCapability.describeExecApprovalSetup`を使用してください。このフックは`{ channel, channelLabel, accountId }`を受け取ります。名前付きアカウントのチャネルは、トップレベルのデフォルトではなく、`channels..accounts..execApprovals.*`のようなアカウントスコープ付きパスを描画する必要があります。 +- チャネルが既存configから安定したオーナー的DMアイデンティティを推論できる場合は、承認固有のコアロジックを追加せずに同一チャット`/approve`を制限するため、`openclaw/plugin-sdk/approval-runtime`の`createResolvedApproverActionAuthAdapter`を使用してください。 +- チャネルがネイティブ承認配信を必要とする場合、チャネルコードはターゲット正規化と転送/表示情報に集中させてください。`openclaw/plugin-sdk/approval-runtime`の`createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability`を使用してください。チャネル固有の情報は`approvalCapability.nativeRuntime`の背後に置き、理想的には`createChannelApprovalNativeRuntimeAdapter(...)`または`createLazyChannelApprovalNativeRuntimeAdapter(...)`を通してください。そうすることで、コアがハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、有効期限、Gateway購読、別経路通知を担えます。`nativeRuntime`はいくつかのより小さなシームに分かれています。 +- `availability` — アカウントが設定されているか、およびリクエストを処理すべきかどうか +- `presentation` — 共有承認ビューモデルを、保留/解決済み/期限切れのネイティブペイロードまたは最終アクションへ対応付ける - `transport` — ターゲットを準備し、ネイティブ承認メッセージを送信/更新/削除する -- `interactions` — ネイティブボタンやリアクション向けの任意のbind/unbind/clear-actionフック +- `interactions` — ネイティブボタンやリアクションのための任意のbind/unbind/clear-actionフック - `observe` — 任意の配信診断フック -- チャネルにclient、token、Boltアプリ、Webhookレシーバーのような実行時所有オブジェクトが必要な場合は、`openclaw/plugin-sdk/channel-runtime-context`を通じて登録してください。汎用runtime-contextレジストリにより、コアは承認固有のラッパーを追加せずに、チャネル起動状態から機能駆動ハンドラーをブートストラップできます。 -- capability駆動インターフェースでまだ十分に表現できない場合にのみ、より低レベルの`createChannelApprovalHandler`または`createChannelNativeApprovalRuntime`を使用してください。 -- ネイティブ承認チャネルでは、これらのヘルパーを通じて`accountId`と`approvalKind`の両方をルーティングする必要があります。`accountId`はマルチアカウント承認ポリシーを正しいボットアカウントにスコープし、`approvalKind`はコアでハードコードされた分岐なしにexecとplugin承認の動作をチャネルで利用可能にします。 -- コアは承認の再ルーティング通知も担当するようになりました。チャネルPluginは、`createChannelNativeApprovalRuntime`から独自の「承認はDM/別チャネルに送られました」という追跡メッセージを送信すべきではありません。代わりに、共有承認capabilityヘルパーを通じて正確なoriginとapprover-DMルーティングを公開し、開始チャットに通知を投稿する前にコアが実際の配信を集約するようにしてください。 -- 配信された承認idの種類をエンドツーエンドで保持してください。ネイティブクライアントは、チャネルローカルの状態からexecとplugin承認のルーティングを推測または書き換えるべきではありません。 -- 異なる承認種類で、意図的に異なるネイティブサーフェスを公開してもかまいません。 +- チャネルがクライアント、トークン、Boltアプリ、Webhook受信側のような実行時所有オブジェクトを必要とする場合は、`openclaw/plugin-sdk/channel-runtime-context`を通じて登録してください。汎用のruntime-contextレジストリにより、コアは承認固有のラッパー接着コードを追加せずに、チャネル起動状態からcapability駆動ハンドラーをブートストラップできます。 +- capability駆動シームだけではまだ表現力が足りない場合にのみ、下位レベルの`createChannelApprovalHandler`または`createChannelNativeApprovalRuntime`に手を伸ばしてください。 +- ネイティブ承認チャネルは、`accountId`と`approvalKind`の両方をそれらのヘルパーに渡す必要があります。`accountId`は複数アカウント承認ポリシーを正しいbotアカウントにスコープし、`approvalKind`はコア内のハードコード分岐なしでexec対plugin承認動作をチャネルで利用可能にします。 +- コアは現在、承認の再ルーティング通知も担います。チャネルpluginは、`createChannelNativeApprovalRuntime`から独自の「承認はDM/別チャネルへ送られました」フォローアップメッセージを送信すべきではありません。代わりに、共有承認capabilityヘルパーを通じて正確な発信元+承認者DMルーティングを公開し、開始チャットへ通知を投稿する前に実際の配信をコアに集約させてください。 +- 配信済み承認IDの種類は、エンドツーエンドで保持してください。ネイティブクライアントは、チャネルローカル状態からexec対plugin承認ルーティングを推測したり書き換えたりしてはいけません。 +- 異なる承認種別は、意図的に異なるネイティブサーフェスを公開できます。 現在の同梱例: - - Slackは、exec idとplugin idの両方でネイティブ承認ルーティングを利用可能にしています。 - - Matrixは、exec承認とplugin承認で同じネイティブDM/チャネルルーティングとリアクションUXを維持しつつ、承認種類による認証の違いも許可しています。 -- `createApproverRestrictedNativeApprovalAdapter`は互換性ラッパーとしてまだ存在しますが、新しいコードではcapability builderを推奨し、Plugin上で`approvalCapability`を公開してください。 + - Slackは、execとpluginの両方のIDに対してネイティブ承認ルーティングを利用可能に保っています。 + - Matrixは、execとpluginの承認で認証を異ならせつつ、同じネイティブDM/チャネルルーティングとリアクションUXを維持しています。 +- `createApproverRestrictedNativeApprovalAdapter`は互換ラッパーとして引き続き存在しますが、新しいコードではcapability builderを優先し、plugin上に`approvalCapability`を公開してください。 -ホットなチャネルエントリーポイントでは、そのファミリーのうち1つの部分だけが必要な場合、より狭いruntimeサブパスを優先してください。 +ホットなチャネルエントリーポイントでは、そのファミリーの一部だけが必要な場合、より狭いruntimeサブパスを優先してください。 - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -98,77 +93,70 @@ x-i18n: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -同様に、より広い包括的な公開インターフェースが不要な場合は、 -`openclaw/plugin-sdk/setup-runtime`、 -`openclaw/plugin-sdk/setup-adapter-runtime`、 -`openclaw/plugin-sdk/reply-runtime`、 -`openclaw/plugin-sdk/reply-dispatch-runtime`、 -`openclaw/plugin-sdk/reply-reference`、および -`openclaw/plugin-sdk/reply-chunking` -を優先してください。 +同様に、より広い傘型サーフェスが不要な場合は、`openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/reply-runtime`、`openclaw/plugin-sdk/reply-dispatch-runtime`、`openclaw/plugin-sdk/reply-reference`、`openclaw/plugin-sdk/reply-chunking`を優先してください。 -セットアップに関しては特に次のとおりです。 +セットアップについては、特に次のとおりです。 -- `openclaw/plugin-sdk/setup-runtime`はruntime-safeなセットアップヘルパーを提供します: - import-safeなセットアップパッチアダプター（`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime`は、runtime-safeなセットアップヘルパーを扱います: + import-safeなセットアップパッチアダプター（`createPatchedAccountSetupAdapter`、 `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`）、lookup-note出力、 - `promptResolvedAllowFrom`、`splitSetupEntries`、および委譲された + `promptResolvedAllowFrom`、`splitSetupEntries`、委譲された setup-proxy builder -- `openclaw/plugin-sdk/setup-adapter-runtime`は、`createEnvPatchedAccountSetupAdapter`向けの狭いenv-aware adapterインターフェースです -- `openclaw/plugin-sdk/channel-setup`は、オプションインストール用セットアップbuilderと、いくつかのセットアップ安全なプリミティブを提供します: +- `openclaw/plugin-sdk/setup-adapter-runtime`は、`createEnvPatchedAccountSetupAdapter`向けの狭いenv対応アダプターシームです +- `openclaw/plugin-sdk/channel-setup`は、オプションインストールのセットアップbuilderと、いくつかのセットアップ安全なプリミティブを扱います: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -チャネルがenv駆動のセットアップまたは認証をサポートし、汎用の起動/設定フローでruntimeロード前にそれらのenv名を把握する必要がある場合は、Pluginマニフェストで`channelEnvVars`として宣言してください。チャネルruntimeの`envVars`やローカル定数は、オペレーター向け文言専用にとどめてください。 +チャネルがenv駆動のセットアップまたは認証をサポートし、汎用の起動/configフローがruntimeロード前にそれらのenv名を知る必要がある場合は、pluginマニフェストで`channelEnvVars`として宣言してください。チャネルruntimeの`envVars`またはローカル定数は、運用者向けコピー専用にしてください。 `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, および `splitSetupEntries` -- より重い共有セットアップ/設定ヘルパー、たとえば - `moveSingleAccountChannelSectionToDefaultAccount(...)` - も必要な場合にのみ、より広い`openclaw/plugin-sdk/setup`インターフェースを使用してください +- より重い共有セットアップ/configヘルパー、たとえば + `moveSingleAccountChannelSectionToDefaultAccount(...)`も必要な場合にのみ、より広い`openclaw/plugin-sdk/setup`シームを使用してください -チャネルがセットアップ画面で「まずこのPluginをインストールしてください」と案内したいだけなら、`createOptionalChannelSetupSurface(...)`を優先してください。生成されるadapter/wizardは設定書き込みと最終化でfail closedし、検証、最終化、ドキュメントリンク文言で同じインストール必須メッセージを再利用します。 +チャネルがセットアップサーフェス内で「まずこのpluginをインストールしてください」と告知したいだけなら、`createOptionalChannelSetupSurface(...)`を優先してください。生成されるアダプター/ウィザードはconfig書き込みと最終化でフェイルクローズし、検証、最終化、ドキュメントリンク文言の各所で同じインストール必須メッセージを再利用します。 -そのほかのホットなチャネルパスでも、より広い従来の公開インターフェースより狭いヘルパーを優先してください。 +その他のホットなチャネルパスでも、より広いレガシーサーフェスより狭いヘルパーを優先してください。 -- `openclaw/plugin-sdk/account-core`, - `openclaw/plugin-sdk/account-id`, - `openclaw/plugin-sdk/account-resolution`, および - `openclaw/plugin-sdk/account-helpers` は、マルチアカウント設定と - デフォルトアカウントへのフォールバック用です -- `openclaw/plugin-sdk/inbound-envelope` および - `openclaw/plugin-sdk/inbound-reply-dispatch` は、受信route/envelopeと - record-and-dispatch配線用です -- `openclaw/plugin-sdk/messaging-targets` はターゲット解析/照合用です -- `openclaw/plugin-sdk/outbound-media` および +- `openclaw/plugin-sdk/account-core`、 + `openclaw/plugin-sdk/account-id`、 + `openclaw/plugin-sdk/account-resolution`、および + `openclaw/plugin-sdk/account-helpers` は、複数アカウントconfigと + デフォルトアカウントフォールバック向けです +- `openclaw/plugin-sdk/inbound-envelope` と + `openclaw/plugin-sdk/inbound-reply-dispatch` は、受信ルート/エンベロープと + record-and-dispatch配線向けです +- `openclaw/plugin-sdk/messaging-targets` は、ターゲット解析/マッチング向けです +- `openclaw/plugin-sdk/outbound-media` と `openclaw/plugin-sdk/outbound-runtime` は、メディア読み込みと送信 - identity/send delegate用です -- `openclaw/plugin-sdk/thread-bindings-runtime` は、スレッドbindingライフサイクル - とadapter登録用です -- `openclaw/plugin-sdk/agent-media-payload` は、従来のagent/media - ペイロードフィールド配置がまだ必要な場合にのみ使用してください + アイデンティティ/送信デリゲート向けです +- `openclaw/plugin-sdk/thread-bindings-runtime` は、スレッドバインディングのライフサイクル + とアダプター登録向けです +- `openclaw/plugin-sdk/agent-media-payload` は、レガシーなagent/media + ペイロードのフィールドレイアウトが依然必要な場合にのみ使用してください - `openclaw/plugin-sdk/telegram-command-config` は、Telegramカスタムコマンドの - 正規化、重複/競合検証、およびフォールバック安定なコマンド設定コントラクト用です + 正規化、重複/競合検証、およびフォールバック安定なコマンド + config契約向けです -認証専用チャネルは通常、デフォルトの経路で十分です。コアが承認を処理し、Pluginは送信/認証capabilityを公開するだけで済みます。Matrix、Slack、Telegram、カスタムチャットトランスポートのようなネイティブ承認チャネルは、独自の承認ライフサイクルを実装するのではなく、共有のネイティブヘルパーを使用してください。 +認証専用チャネルは通常、デフォルトのパスで十分です。コアが承認を処理し、pluginは送信/認証capabilityを公開するだけです。Matrix、Slack、Telegram、カスタムチャット転送のようなネイティブ承認チャネルは、独自の承認ライフサイクルを実装するのではなく、共有ネイティブヘルパーを使うべきです。 ## 受信メンションポリシー -受信メンション処理は、次の2層に分けたままにしてください。 +受信メンション処理は、次の2層に分けてください。 -- Plugin所有の証拠収集 +- plugin所有の証拠収集 - 共有ポリシー評価 共有レイヤーには`openclaw/plugin-sdk/channel-inbound`を使用してください。 -Pluginローカルロジックに適しているもの: +pluginローカルロジックに適しているもの: -- botへの返信の検出 -- botを引用したメッセージの検出 +- botへの返信検出 +- bot引用の検出 - スレッド参加チェック - サービス/システムメッセージの除外 -- botの参加を証明するために必要なプラットフォームネイティブキャッシュ +- bot参加を証明するために必要なプラットフォームネイティブキャッシュ 共有ヘルパーに適しているもの: @@ -176,13 +164,13 @@ Pluginローカルロジックに適しているもの: - 明示的メンション結果 - 暗黙的メンション許可リスト - コマンドバイパス -- 最終的なスキップ判定 +- 最終スキップ判定 推奨フロー: 1. ローカルのメンション情報を計算します。 2. その情報を`resolveInboundMentionDecision({ facts, policy })`に渡します。 -3. 受信ゲートで`decision.effectiveWasMentioned`、`decision.shouldBypassMention`、`decision.shouldSkip`を使用します。 +3. 受信ゲートでは`decision.effectiveWasMentioned`、`decision.shouldBypassMention`、`decision.shouldSkip`を使用します。 ```typescript import { @@ -221,7 +209,7 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions`は、すでにruntime injectionに依存している同梱チャネルPlugin向けに、同じ共有メンションヘルパーを公開します。 +`api.runtime.channel.mentions`は、すでにruntime injectionに依存している同梱チャネルplugin向けに、同じ共有メンションヘルパーを公開します。 - `buildMentionRegexes` - `matchesMentionPatterns` @@ -229,17 +217,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 })`を使用してください。 ## ウォークスルー - 標準的なPluginファイルを作成します。`package.json`の`channel`フィールドが、 - これをチャネルPluginにします。完全なパッケージメタデータの公開インターフェースについては、 + 標準のpluginファイルを作成します。`package.json`内の`channel`フィールドが、これをチャネルpluginにする要素です。完全なパッケージメタデータのサーフェスについては、 [Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel)を参照してください。 @@ -289,9 +274,8 @@ if (decision.shouldSkip) return; - - `ChannelPlugin`インターフェースには、多くの任意のアダプター公開インターフェースがあります。まずは - 最小構成である`id`と`setup`から始め、必要に応じてアダプターを追加してください。 + + `ChannelPlugin`インターフェースには、多数のオプションのアダプターサーフェスがあります。まずは最小限、つまり`id`と`setup`から始め、必要に応じてアダプターを追加してください。 `src/channel.ts`を作成します: @@ -386,19 +370,17 @@ if (decision.shouldSkip) return; }); ``` - - 低レベルのアダプターインターフェースを手動で実装する代わりに、 - 宣言的なオプションを渡すと、builderがそれらを組み合わせます。 + + 低レベルのアダプターインターフェースを手動で実装する代わりに、宣言的なオプションを渡すと、builderがそれらを組み合わせます。 - | Option | 配線されるもの | + | オプション | 配線される内容 | | --- | --- | - | `security.dm` | 設定フィールドからのスコープ付きDMセキュリティリゾルバー | + | `security.dm` | configフィールドからスコープ付きDMセキュリティリゾルバー | | `pairing.text` | コード交換を伴うテキストベースのDMペアリングフロー | | `threading` | reply-to-modeリゾルバー（固定、アカウントスコープ、またはカスタム） | - | `outbound.attachedResults` | 結果メタデータ（message ID）を返す送信関数 | + | `outbound.attachedResults` | 結果メタデータ（メッセージID）を返す送信関数 | - 完全な制御が必要な場合は、宣言的オプションの代わりに - 生のアダプターオブジェクトを渡すこともできます。 + 完全な制御が必要な場合は、宣言的オプションの代わりに生のアダプターオブジェクトを渡すこともできます。 @@ -439,19 +421,14 @@ if (decision.shouldSkip) return; }); ``` - チャネル所有のCLI descriptorは`registerCliMetadata(...)`に置いてください。これにより、OpenClawは完全なチャネルruntimeを有効化せずに - ルートヘルプでそれらを表示でき、通常の完全ロードでも実際のコマンド登録のために - 同じdescriptorを取得できます。`registerFull(...)`はruntime専用の処理に残してください。 - `registerFull(...)`がGateway RPCメソッドを登録する場合は、 - Plugin固有のprefixを使用してください。コア管理namespace（`config.*`、 - `exec.approvals.*`, `wizard.*`, `update.*`）は予約されたままで、 - 常に`operator.admin`に解決されます。 - `defineChannelPluginEntry`は登録モードの分岐を自動的に処理します。すべての - オプションについては[Entry Points](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry)を参照してください。 + チャネル所有のCLI descriptorは`registerCliMetadata(...)`に置いてください。これにより、OpenClawは完全なチャネルruntimeを起動せずにルートヘルプでそれらを表示でき、通常の完全ロードでも実際のコマンド登録に同じdescriptorを利用できます。`registerFull(...)`はruntime専用の処理に使ってください。 + `registerFull(...)`がGateway RPCメソッドを登録する場合は、plugin固有のプレフィックスを使用してください。コア管理名前空間（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は予約されており、常に`operator.admin`に解決されます。 + `defineChannelPluginEntry`は、この登録モード分割を自動的に処理します。すべてのオプションについては + [Entry Points](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry)を参照してください。 - + オンボーディング中の軽量ロード用に`setup-entry.ts`を作成します: ```typescript setup-entry.ts @@ -461,16 +438,15 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClawは、チャネルが無効または未設定のとき、完全なentryの代わりにこれをロードします。 - これにより、セットアップフロー中に重いruntimeコードを読み込まずに済みます。 - 詳細は[Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry)を参照してください。 + OpenClawは、チャネルが無効または未設定のときに、完全なエントリの代わりにこれをロードします。これにより、セットアップフロー中に重いruntimeコードを引き込まずに済みます。詳細は[Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry)を参照してください。 + + セットアップ安全なエクスポートをサイドカーモジュールに分離している同梱workspaceチャネルは、 + `openclaw/plugin-sdk/channel-entry-contract`の`defineBundledChannelSetupEntry(...)`を使用できます。これは、明示的なセットアップ時runtime setterも必要な場合に有効です。 - Pluginはプラットフォームからメッセージを受信し、それを - OpenClawに転送する必要があります。典型的なパターンは、リクエストを検証し、 - チャネルの受信ハンドラーを通してディスパッチするWebhookです。 + pluginは、プラットフォームからメッセージを受信し、それをOpenClawへ転送する必要があります。一般的なパターンは、リクエストを検証し、チャネルの受信ハンドラーを通じてディスパッチするWebhookです。 ```typescript registerFull(api) { @@ -494,17 +470,15 @@ if (decision.shouldSkip) return; ``` - 受信メッセージ処理はチャネル固有です。各チャネルPluginは - 独自の受信パイプラインを所有します。実際のパターンについては、 - 同梱チャネルPlugin - （たとえばMicrosoft TeamsまたはGoogle ChatのPluginパッケージ）を参照してください。 + 受信メッセージ処理はチャネル固有です。各チャネルpluginが独自の受信パイプラインを所有します。実際のパターンについては、同梱チャネルplugin + （たとえばMicrosoft TeamsまたはGoogle Chatのpluginパッケージ）を見てください。 -`src/channel.test.ts`に同じ場所のテストを書きます: +`src/channel.test.ts`に同居テストを書いてください: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -551,14 +525,14 @@ if (decision.shouldSkip) return; ``` /acme-chat/ -├── package.json # openclaw.channelメタデータ -├── openclaw.plugin.json # 設定スキーマを含むマニフェスト +├── package.json # openclaw.channel メタデータ +├── openclaw.plugin.json # configスキーマを含むマニフェスト ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # 公開エクスポート（任意） ├── runtime-api.ts # 内部runtimeエクスポート（任意） └── src/ - ├── channel.ts # createChatChannelPlugin経由のChannelPlugin + ├── channel.ts # createChatChannelPluginによるChannelPlugin ├── channel.test.ts # テスト ├── client.ts # プラットフォームAPIクライアント └── runtime.ts # runtimeストア（必要な場合） @@ -571,27 +545,23 @@ if (decision.shouldSkip) return; 固定、アカウントスコープ、またはカスタムの返信モード - describeMessageToolとアクション検出 + describeMessageTool とアクションディスカバリー inferTargetChatType, looksLikeId, resolveTarget - api.runtime経由のTTS、STT、メディア、subagent + api.runtime を介したTTS、STT、メディア、subagent -一部の同梱ヘルパーインターフェースは、同梱Pluginのメンテナンスと -互換性のためにまだ存在します。これらは新しいチャネルPluginに推奨される -パターンではありません。その同梱Pluginファミリーを直接メンテナンスしている場合を除き、 -共通SDK公開インターフェースの汎用channel/setup/reply/runtimeサブパスを -優先してください。 +一部の同梱ヘルパーシームは、同梱pluginの保守と互換性のために引き続き存在します。これらは新しいチャネルpluginに推奨されるパターンではありません。その同梱pluginファミリーを直接保守しているのでない限り、共通SDKサーフェスの汎用的なchannel/setup/reply/runtimeサブパスを優先してください。 ## 次のステップ -- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — Pluginがモデルも提供する場合 +- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — pluginがモデルも提供する場合 - [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全なサブパスimportリファレンス -- [SDK Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティとコントラクトテスト +- [SDK Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティと契約テスト - [Plugin Manifest](/ja-JP/plugins/manifest) — 完全なマニフェストスキーマ diff --git a/docs/ja-JP/plugins/sdk-entrypoints.md b/docs/ja-JP/plugins/sdk-entrypoints.md index f876c0497..b23f07603 100644 --- a/docs/ja-JP/plugins/sdk-entrypoints.md +++ b/docs/ja-JP/plugins/sdk-entrypoints.md @@ -1,36 +1,36 @@ --- read_when: - - definePluginEntry または defineChannelPluginEntry の正確な型シグネチャが必要 - - 登録モード（full / setup / CLI metadata）を理解したい - - エントリーポイントのオプションを調べている + - '`definePluginEntry` または `defineChannelPluginEntry` の正確な型シグネチャが必要です' + - 登録モード（full と setup と CLI メタデータ）の違いを理解したい場合 + - エントリポイントのオプションを調べている場合 sidebarTitle: Entry Points summary: definePluginEntry、defineChannelPluginEntry、defineSetupPluginEntry のリファレンス -title: プラグインのエントリーポイント +title: Plugin エントリポイント x-i18n: - generated_at: "2026-04-05T12:52:13Z" + generated_at: "2026-04-15T19:41:43Z" model: gpt-5.4 provider: openai - source_hash: 799dbfe71e681dd8ba929a7a631dfe745c3c5c69530126fea2f9c137b120f51f + source_hash: aabca25bc9b8ff1b5bb4852bafe83640ffeba006ea6b6a8eff4e2c37a10f1fe4 source_path: plugins/sdk-entrypoints.md workflow: 15 --- -# プラグインのエントリーポイント +# Plugin エントリポイント -すべてのプラグインはデフォルトのエントリーオブジェクトを export します。SDK は、 +すべての Plugin はデフォルトのエントリオブジェクトをエクスポートします。SDK は、 それらを作成するための 3 つのヘルパーを提供します。 - **手順ガイドを探していますか？** [Channel Plugins](/plugins/sdk-channel-plugins) - または [Provider Plugins](/plugins/sdk-provider-plugins) のステップごとのガイドを参照してください。 + **手順を追ったガイドをお探しですか？** ステップごとのガイドについては、[Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) + または [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) を参照してください。 ## `definePluginEntry` -**Import:** `openclaw/plugin-sdk/plugin-entry` +**インポート:** `openclaw/plugin-sdk/plugin-entry` -provider plugin、tool plugin、hook plugin、およびメッセージングチャンネル**ではない** -ものに使用します。 +provider plugins、tool plugins、hook plugins、およびメッセージングチャネル +**ではない** あらゆるもの向けです。 ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -50,28 +50,28 @@ export default definePluginEntry({ }); ``` -| Field | Type | Required | Default | -| -------------- | ---------------------------------------------------------------- | -------- | ------------------- | -| `id` | `string` | Yes | — | -| `name` | `string` | Yes | — | -| `description` | `string` | Yes | — | -| `kind` | `string` | No | — | -| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | No | Empty object schema | -| `register` | `(api: OpenClawPluginApi) => void` | Yes | — | +| フィールド | 型 | 必須 | デフォルト | +| ---------------- | ---------------------------------------------------------------- | ---- | ------------------- | +| `id` | `string` | はい | — | +| `name` | `string` | はい | — | +| `description` | `string` | はい | — | +| `kind` | `string` | いいえ | — | +| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | いいえ | 空のオブジェクトスキーマ | +| `register` | `(api: OpenClawPluginApi) => void` | はい | — | - `id` は `openclaw.plugin.json` マニフェストと一致している必要があります。 - `kind` は排他的スロット用です: `"memory"` または `"context-engine"`。 - `configSchema` は遅延評価のために関数にできます。 -- OpenClaw はそのスキーマを初回アクセス時に解決してメモ化するため、高コストなスキーマ +- OpenClaw は最初のアクセス時にそのスキーマを解決してメモ化するため、高コストなスキーマ ビルダーは 1 回しか実行されません。 ## `defineChannelPluginEntry` -**Import:** `openclaw/plugin-sdk/channel-core` +**インポート:** `openclaw/plugin-sdk/channel-core` -チャンネル固有の配線で `definePluginEntry` をラップします。自動的に -`api.registerChannel({ plugin })` を呼び出し、任意のルートヘルプ CLI metadata シームを公開し、 -登録モードに応じて `registerFull` を制御します。 +チャネル固有の配線を追加して `definePluginEntry` をラップします。 +`api.registerChannel({ plugin })` を自動的に呼び出し、オプションのルートヘルプ CLI メタデータ +接続点を公開し、登録モードに応じて `registerFull` を制御します。 ```typescript import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -91,41 +91,44 @@ export default defineChannelPluginEntry({ }); ``` -| Field | Type | Required | Default | -| --------------------- | ---------------------------------------------------------------- | -------- | ------------------- | -| `id` | `string` | Yes | — | -| `name` | `string` | Yes | — | -| `description` | `string` | Yes | — | -| `plugin` | `ChannelPlugin` | Yes | — | -| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | No | Empty object schema | -| `setRuntime` | `(runtime: PluginRuntime) => void` | No | — | -| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | No | — | -| `registerFull` | `(api: OpenClawPluginApi) => void` | No | — | +| フィールド | 型 | 必須 | デフォルト | +| --------------------- | ---------------------------------------------------------------- | ---- | ------------------- | +| `id` | `string` | はい | — | +| `name` | `string` | はい | — | +| `description` | `string` | はい | — | +| `plugin` | `ChannelPlugin` | はい | — | +| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | いいえ | 空のオブジェクトスキーマ | +| `setRuntime` | `(runtime: PluginRuntime) => void` | いいえ | — | +| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | いいえ | — | +| `registerFull` | `(api: OpenClawPluginApi) => void` | いいえ | — | - `setRuntime` は登録中に呼び出されるため、ランタイム参照を保存できます - （通常は `createPluginRuntimeStore` を使います）。CLI metadata の + （通常は `createPluginRuntimeStore` を介します）。CLI メタデータの 取得中はスキップされます。 -- `registerCliMetadata` は `api.registrationMode === "cli-metadata"` - と `api.registrationMode === "full"` の両方で実行されます。 - ルートヘルプを非アクティブのまま保ちつつ、通常の CLI コマンド登録を full plugin load と互換に保つため、 - チャンネル所有の CLI descriptor の正規の置き場所としてこれを使ってください。 -- `registerFull` は `api.registrationMode === "full"` のときだけ実行されます。setup-only の読み込み中はスキップされます。 +- `registerCliMetadata` は `api.registrationMode === "cli-metadata"` と + `api.registrationMode === "full"` の両方で実行されます。 + これをチャネル所有の CLI 記述子の正式な配置場所として使用してください。そうすることで、 + ルートヘルプは非アクティベートのまま維持され、通常の CLI コマンド登録は完全な Plugin + 読み込みとの互換性を保てます。 +- `registerFull` は `api.registrationMode === "full"` の場合にのみ実行されます。 + setup-only 読み込み中はスキップされます。 - `definePluginEntry` と同様に、`configSchema` は遅延ファクトリーにでき、 - OpenClaw は解決済みスキーマを初回アクセス時にメモ化します。 -- プラグイン所有のルート CLI コマンドでは、コマンドを - ルート CLI parse tree から消さずに lazy-load のままにしたい場合、 - `api.registerCli(..., { descriptors: [...] })` を優先してください。channel plugin では、 - それらの descriptor は `registerCliMetadata(...)` から登録し、`registerFull(...)` はランタイム専用の処理に集中させてください。 -- `registerFull(...)` が gateway RPC method も登録する場合は、それらを - plugin 固有の prefix に保ってください。予約済みの core admin namespace（`config.*`、 - `exec.approvals.*`、`wizard.*`、`update.*`）は常に + OpenClaw は最初のアクセス時に解決済みスキーマをメモ化します。 +- Plugin 所有のルート CLI コマンドについては、実際のコマンドを + ルート CLI 解析ツリーから消さずに遅延読み込みにしたい場合、 + `api.registerCli(..., { descriptors: [...] })` を優先してください。チャネル Plugin + では、それらの記述子は `registerCliMetadata(...)` から登録し、 + `registerFull(...)` はランタイム専用の処理に集中させてください。 +- `registerFull(...)` でも gateway RPC メソッドを登録する場合は、 + Plugin 固有のプレフィックスにしてください。予約済みのコア管理名前空間 + （`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は常に `operator.admin` に強制されます。 ## `defineSetupPluginEntry` -**Import:** `openclaw/plugin-sdk/channel-core` +**インポート:** `openclaw/plugin-sdk/channel-core` -軽量な `setup-entry.ts` ファイル用です。ランタイムや CLI の配線を持たず、 +軽量な `setup-entry.ts` ファイル向けです。ランタイムや CLI 配線なしで、 単に `{ plugin }` を返します。 ```typescript @@ -134,35 +137,61 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; export default defineSetupPluginEntry(myChannelPlugin); ``` -OpenClaw は、チャンネルが無効、未設定、または遅延読み込みが有効な場合、 -full entry の代わりにこれを読み込みます。これが重要になる場面については -[Setup and Config](/plugins/sdk-setup#setup-entry) を参照してください。 +チャネルが無効化されている場合、未設定の場合、または遅延読み込みが有効な場合、 +OpenClaw は完全なエントリの代わりにこれを読み込みます。これが重要になる場面については、 +[Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry) を参照してください。 -実際には、`defineSetupPluginEntry(...)` は次の狭い setup helper -ファミリーと組み合わせて使ってください。 +実際には、`defineSetupPluginEntry(...)` を次のような絞り込まれた setup ヘルパー +群と組み合わせてください。 -- `openclaw/plugin-sdk/setup-runtime` は、import-safe な setup patch adapter、 - lookup-note 出力、 - `promptResolvedAllowFrom`、`splitSetupEntries`、委譲 setup proxy などの - ランタイムセーフな setup helper 用 -- `openclaw/plugin-sdk/channel-setup` は任意インストールの setup surface 用 -- `openclaw/plugin-sdk/setup-tools` は setup / install CLI / archive / docs helper 用 +- `openclaw/plugin-sdk/setup-runtime`: + import-safe な setup patch アダプター、lookup-note 出力、 + `promptResolvedAllowFrom`、`splitSetupEntries`、委譲された setup proxy + などのランタイムセーフな setup ヘルパー向け +- `openclaw/plugin-sdk/channel-setup`: + オプションのインストール用 setup サーフェス向け +- `openclaw/plugin-sdk/setup-tools`: + setup/install CLI/archive/docs ヘルパー向け -重い SDK、CLI 登録、長寿命ランタイム service は full -entry に置いてください。 +重い SDK、CLI 登録、長寿命のランタイムサービスは完全なエントリに置いてください。 + +setup サーフェスとランタイムサーフェスを分離するバンドル済みワークスペースチャネルでは、 +代わりに `openclaw/plugin-sdk/channel-entry-contract` の +`defineBundledChannelSetupEntry(...)` を使用できます。このコントラクトにより、 +setup エントリは runtime setter を公開しつつ、setup-safe な +plugin/secrets エクスポートを保持できます。 + +```typescript +import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract"; + +export default defineBundledChannelSetupEntry({ + importMetaUrl: import.meta.url, + plugin: { + specifier: "./channel-plugin-api.js", + exportName: "myChannelPlugin", + }, + runtime: { + specifier: "./runtime-api.js", + exportName: "setMyChannelRuntime", + }, +}); +``` + +そのバンドル済みコントラクトは、完全なチャネルエントリが読み込まれる前に、 +setup フローが本当に軽量な runtime setter を必要とする場合にのみ使用してください。 ## 登録モード -`api.registrationMode` は、プラグインがどのように読み込まれたかを示します。 +`api.registrationMode` は、Plugin がどのように読み込まれたかを示します。 -| Mode | When | 何を登録するか | -| ----------------- | --------------------------------- | ------------- | -| `"full"` | 通常の gateway 起動時 | すべて | -| `"setup-only"` | 無効または未設定のチャンネル | チャンネル登録のみ | -| `"setup-runtime"` | ランタイム利用可能な setup フロー | チャンネル登録に加え、full entry が読み込まれる前に必要な軽量ランタイムのみ | -| `"cli-metadata"` | ルートヘルプ / CLI metadata 取得 | CLI descriptor のみ | +| モード | タイミング | 登録すべきもの | +| ----------------- | ---------------------------------- | --------------------------------------------------------------------------------------- | +| `"full"` | 通常の Gateway 起動 | すべて | +| `"setup-only"` | 無効化済み / 未設定のチャネル | チャネル登録のみ | +| `"setup-runtime"` | ランタイム利用可能な setup フロー | チャネル登録に加えて、完全なエントリが読み込まれる前に必要な軽量ランタイムのみ | +| `"cli-metadata"` | ルートヘルプ / CLI メタデータ取得 | CLI 記述子のみ | -`defineChannelPluginEntry` は、この分岐を自動的に処理します。チャンネルに +`defineChannelPluginEntry` はこの分岐を自動的に処理します。チャネルに対して `definePluginEntry` を直接使う場合は、自分でモードを確認してください。 ```typescript @@ -175,41 +204,43 @@ register(api) { api.registerChannel({ plugin: myPlugin }); if (api.registrationMode !== "full") return; - // 重いランタイム専用の登録 + // Heavy runtime-only registrations api.registerService(/* ... */); } ``` -`"setup-runtime"` は、setup-only の起動サーフェスが -full の bundled channel runtime に再突入せずに存在しなければならない期間として扱ってください。 -適しているのは、チャンネル登録、setup-safe な HTTP route、setup-safe な gateway method、 -および委譲 setup helper です。重い background service、CLI registrar、 -provider / client SDK の bootstrap は、引き続き `"full"` に属します。 +`"setup-runtime"` は、setup-only の起動サーフェスが完全なバンドル済みチャネルランタイムに +再入せずに存在しなければならない期間として扱ってください。適しているのは、 +チャネル登録、setup-safe な HTTP ルート、setup-safe な gateway メソッド、 +委譲された setup ヘルパーです。重いバックグラウンドサービス、CLI レジストラー、 +provider/client SDK のブートストラップは、引き続き `"full"` に属します。 -特に CLI registrar について: +特に CLI レジストラーについては: -- registrar が 1 つ以上のルートコマンドを所有し、 - 最初の呼び出し時に OpenClaw に実際の CLI module を lazy-load させたい場合は `descriptors` を使ってください -- それらの descriptor が、その registrar によって公開されるすべてのトップレベルコマンド root をカバーしていることを確認してください -- `commands` 単独は eager な互換パスにのみ使ってください +- レジストラーが 1 つ以上のルートコマンドを所有しており、最初の呼び出し時に + OpenClaw に実際の CLI モジュールを遅延読み込みさせたい場合は、 + `descriptors` を使用してください +- それらの記述子が、レジストラーによって公開されるすべてのトップレベルコマンドルートを + カバーしていることを確認してください +- 即時互換パスでは `commands` 単独のみを使用してください -## プラグイン形状 +## Plugin の形状 -OpenClaw は、読み込まれたプラグインをその登録動作によって分類します。 +OpenClaw は、読み込まれた Plugin をその登録動作によって分類します。 -| Shape | 説明 | -| --------------------- | ---- | -| **plain-capability** | 1 種類の capability のみ（例: provider のみ） | -| **hybrid-capability** | 複数種類の capability（例: provider + speech） | -| **hook-only** | hook のみで、capability はなし | -| **non-capability** | tools / commands / services はあるが capability はなし | +| 形状 | 説明 | +| --------------------- | -------------------------------------------------- | +| **plain-capability** | 1 種類の capability のみ（例: provider-only） | +| **hybrid-capability** | 複数種類の capability（例: provider + speech） | +| **hook-only** | hooks のみで、capability はなし | +| **non-capability** | Tools/commands/services はあるが capability はなし | -プラグインの形状を確認するには `openclaw plugins inspect ` を使ってください。 +Plugin の形状を確認するには `openclaw plugins inspect ` を使用してください。 ## 関連 -- [SDK Overview](/plugins/sdk-overview) — 登録 API と subpath リファレンス -- [Runtime Helpers](/plugins/sdk-runtime) — `api.runtime` と `createPluginRuntimeStore` -- [Setup and Config](/plugins/sdk-setup) — マニフェスト、setup entry、遅延読み込み -- [Channel Plugins](/plugins/sdk-channel-plugins) — `ChannelPlugin` オブジェクトの構築 -- [Provider Plugins](/plugins/sdk-provider-plugins) — provider 登録と hook +- [SDK Overview](/ja-JP/plugins/sdk-overview) — 登録 API とサブパスのリファレンス +- [Runtime Helpers](/ja-JP/plugins/sdk-runtime) — `api.runtime` と `createPluginRuntimeStore` +- [Setup and Config](/ja-JP/plugins/sdk-setup) — マニフェスト、setup エントリ、遅延読み込み +- [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) — `ChannelPlugin` オブジェクトの構築 +- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — provider 登録と hooks diff --git a/docs/ja-JP/plugins/sdk-runtime.md b/docs/ja-JP/plugins/sdk-runtime.md index b4117b818..3b2b23809 100644 --- a/docs/ja-JP/plugins/sdk-runtime.md +++ b/docs/ja-JP/plugins/sdk-runtime.md @@ -1,27 +1,28 @@ --- read_when: - - プラグインからコアヘルパー（TTS、STT、画像生成、Web検索、サブエージェント）を呼び出す必要があります - - '`api.runtime`が何を公開しているかを理解したいです' - - プラグインコードから設定、エージェント、またはメディアヘルパーにアクセスしています + - Pluginからコアヘルパー（TTS、STT、画像生成、ウェブ検索、subagent）を呼び出す必要があります + - '`api.runtime` が何を公開しているのかを理解したい' + - Pluginコードから設定、agent、またはメディアヘルパーにアクセスしています sidebarTitle: Runtime Helpers -summary: api.runtime -- プラグインで利用できる注入済みランタイムヘルパー -title: プラグインランタイムヘルパー +summary: api.runtime -- Pluginで利用できる注入済みランタイムヘルパー +title: Pluginランタイムヘルパー x-i18n: - generated_at: "2026-04-11T02:47:20Z" + generated_at: "2026-04-15T19:41:39Z" model: gpt-5.4 provider: openai - source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be + source_hash: c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8 source_path: plugins/sdk-runtime.md workflow: 15 --- -# プラグインランタイムヘルパー +# Pluginランタイムヘルパー -登録時にすべてのプラグインへ注入される`api.runtime`オブジェクトのリファレンスです。ホスト内部を直接インポートする代わりに、これらのヘルパーを使用してください。 +登録時にすべてのPluginへ注入される `api.runtime` オブジェクトのリファレンスです。 +ホスト内部を直接 import する代わりに、これらのヘルパーを使用してください。 - **ウォークスルーを探していますか？** [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) - または[Provider Plugins](/ja-JP/plugins/sdk-provider-plugins)で、これらのヘルパーが実際の流れの中でどう使われるかを段階的に確認できます。 + **手順の説明を探していますか？** これらのヘルパーが実際の文脈でどのように使われるかを段階的に示したガイドは、[Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) + または [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) を参照してください。 ```typescript @@ -34,28 +35,28 @@ register(api) { ### `api.runtime.agent` -エージェントID、ディレクトリ、セッション管理。 +agentの識別情報、ディレクトリ、およびセッション管理。 ```typescript -// エージェントの作業ディレクトリを解決 +// agentの作業ディレクトリを解決 const agentDir = api.runtime.agent.resolveAgentDir(cfg); -// エージェントワークスペースを解決 +// agentワークスペースを解決 const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg); -// エージェントIDを取得 +// agentの識別情報を取得 const identity = api.runtime.agent.resolveAgentIdentity(cfg); -// デフォルトthinkingレベルを取得 +// デフォルトの思考レベルを取得 const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model); -// エージェントタイムアウトを取得 +// agentのタイムアウトを取得 const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); -// ワークスペースの存在を保証 +// ワークスペースが存在することを保証 await api.runtime.agent.ensureAgentWorkspace(cfg); -// 埋め込みエージェントターンを実行 +// 埋め込みagentターンを実行 const agentDir = api.runtime.agent.resolveAgentDir(cfg); const result = await api.runtime.agent.runEmbeddedAgent({ sessionId: "my-plugin:task-1", @@ -67,13 +68,12 @@ const result = await api.runtime.agent.runEmbeddedAgent({ }); ``` -`runEmbeddedAgent(...)`は、プラグインコードから通常のOpenClaw -エージェントターンを開始するための中立的なヘルパーです。これは、チャネル起点の返信と同じプロバイダー/モデル解決および -エージェントハーネス選択を使用します。 +`runEmbeddedAgent(...)` は、Pluginコードから通常のOpenClaw agentターンを開始するための中立的なヘルパーです。 +これは、チャネルによってトリガーされる返信と同じプロバイダー/モデル解決およびagentハーネス選択を使用します。 -`runEmbeddedPiAgent(...)`は、互換性エイリアスとして引き続き利用できます。 +`runEmbeddedPiAgent(...)` は、互換性のためのエイリアスとして残されています。 -**セッションストアヘルパー**は`api.runtime.agent.session`配下にあります: +**セッションストアヘルパー** は `api.runtime.agent.session` 配下にあります。 ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -84,7 +84,7 @@ const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId ### `api.runtime.agent.defaults` -デフォルトのモデル定数とプロバイダー定数: +デフォルトのモデルおよびプロバイダー定数: ```typescript const model = api.runtime.agent.defaults.model; // 例: "anthropic/claude-sonnet-4-6" @@ -93,22 +93,22 @@ 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", // 任意の上書き - model: "gpt-4.1-mini", // 任意の上書き + 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, @@ -121,15 +121,14 @@ await api.runtime.subagent.deleteSession({ ``` - モデル上書き（`provider`/`model`）には、設定内の - `plugins.entries..subagent.allowModelOverride: true`によるオペレーターの明示的オプトインが必要です。 - 信頼されていないプラグインでもサブエージェントは実行できますが、上書き要求は拒否されます。 + モデル上書き（`provider`/`model`）には、設定の + `plugins.entries..subagent.allowModelOverride: true` によるオペレーターのオプトインが必要です。 + 信頼されていないPluginでもsubagentは実行できますが、上書きリクエストは拒否されます。 ### `api.runtime.taskFlow` -Task Flowランタイムを既存のOpenClawセッションキーまたは信頼済みツール -コンテキストにバインドし、毎回ownerを渡さずにTask Flowを作成・管理します。 +TaskFlowランタイムを既存のOpenClawセッションキーまたは信頼されたツールコンテキストにバインドし、呼び出しごとに所有者を渡さずにTaskFlowを作成および管理します。 ```typescript const taskFlow = api.runtime.taskFlow.fromToolContext(ctx); @@ -156,12 +155,11 @@ const waiting = taskFlow.setWaiting({ }); ``` -独自のバインディングレイヤーから信頼済みのOpenClawセッションキーをすでに持っている場合は、 -`bindSession({ sessionKey, requesterOrigin })`を使用してください。生のユーザー入力からバインドしてはいけません。 +独自のバインディングレイヤーから取得した信頼済みのOpenClawセッションキーがすでにある場合は、`bindSession({ sessionKey, requesterOrigin })` を使用してください。生のユーザー入力からバインドしないでください。 ### `api.runtime.tts` -テキスト読み上げ。 +テキスト読み上げ合成。 ```typescript // 標準TTS @@ -170,7 +168,7 @@ const clip = await api.runtime.tts.textToSpeech({ cfg: api.config, }); -// 電話向け最適化TTS +// 電話向けに最適化されたTTS const telephonyClip = await api.runtime.tts.textToSpeechTelephony({ text: "Hello from OpenClaw", cfg: api.config, @@ -183,12 +181,11 @@ const voices = await api.runtime.tts.listVoices({ }); ``` -コアの`messages.tts`設定とプロバイダー選択を使用します。PCMオーディオ -バッファ + サンプルレートを返します。 +コアの `messages.tts` 設定とプロバイダー選択を使用します。PCM音声バッファーとサンプルレートを返します。 ### `api.runtime.mediaUnderstanding` -画像、音声、動画の解析。 +画像、音声、および動画の解析。 ```typescript // 画像を説明 @@ -202,7 +199,7 @@ const image = await api.runtime.mediaUnderstanding.describeImageFile({ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - mime: "audio/ogg", // 任意。MIMEを推定できない場合に使用 + mime: "audio/ogg", // MIMEを推定できない場合はオプション }); // 動画を説明 @@ -218,11 +215,11 @@ const result = await api.runtime.mediaUnderstanding.runFile({ }); ``` -出力が生成されない場合（例: 入力がスキップされた場合）は`{ text: undefined }`を返します。 +出力が生成されない場合（例: 入力がスキップされた場合）は、`{ text: undefined }` を返します。 - `api.runtime.stt.transcribeAudioFile(...)`は、 - `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`の互換性エイリアスとして引き続き利用できます。 + `api.runtime.stt.transcribeAudioFile(...)` は、 + `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` の互換性エイリアスとして残されています。 ### `api.runtime.imageGeneration` @@ -240,7 +237,7 @@ const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config }) ### `api.runtime.webSearch` -Web検索。 +ウェブ検索。 ```typescript const providers = api.runtime.webSearch.listProviders({ config: api.config }); @@ -253,7 +250,7 @@ const result = await api.runtime.webSearch.search({ ### `api.runtime.media` -低レベルメディアユーティリティ。 +低レベルのメディアユーティリティ。 ```typescript const webMedia = await api.runtime.media.loadWebMedia(url); @@ -275,7 +272,7 @@ await api.runtime.config.writeConfigFile(cfg); ### `api.runtime.system` -システムレベルユーティリティ。 +システムレベルのユーティリティ。 ```typescript await api.runtime.system.enqueueSystemEvent(event); @@ -308,7 +305,7 @@ const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, ### `api.runtime.modelAuth` -モデルおよびプロバイダー認証の解決。 +モデルおよびプロバイダーの認証解決。 ```typescript const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg }); @@ -320,7 +317,7 @@ const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({ ### `api.runtime.state` -状態ディレクトリ解決。 +stateディレクトリの解決。 ```typescript const stateDir = api.runtime.state.resolveStateDir(); @@ -328,7 +325,7 @@ const stateDir = api.runtime.state.resolveStateDir(); ### `api.runtime.tools` -メモリツールファクトリーとCLI。 +メモリツールファクトリーおよびCLI。 ```typescript const getTool = api.runtime.tools.createMemoryGetTool(/* ... */); @@ -338,10 +335,9 @@ api.runtime.tools.registerMemoryCli(/* ... */); ### `api.runtime.channel` -チャネル固有のランタイムヘルパー（チャネルプラグインが読み込まれている場合に利用可能）。 +チャネル固有のランタイムヘルパー（チャネルPluginが読み込まれている場合に利用可能）。 -`api.runtime.channel.mentions`は、ランタイム注入を使用する -バンドル版チャネルプラグイン向けの共有受信メンションポリシーサーフェスです: +`api.runtime.channel.mentions` は、ランタイム注入を使用するバンドル済みチャネルPlugin向けの共有受信メンションポリシーサーフェスです。 ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -376,20 +372,22 @@ const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({ - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -`api.runtime.channel.mentions`は、古い -`resolveMentionGating*`互換ヘルパーを意図的に公開していません。正規化された -`{ facts, policy }`経路を優先してください。 +`api.runtime.channel.mentions` は、意図的に古い +`resolveMentionGating*` 互換ヘルパーを公開していません。正規化された +`{ facts, policy }` パスを使用してください。 ## ランタイム参照の保存 -`register`コールバックの外で使用するためにランタイム参照を保存するには、 -`createPluginRuntimeStore`を使用してください: +`register` コールバックの外で使用するためにランタイム参照を保存するには、`createPluginRuntimeStore` を使用します。 ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; -const store = createPluginRuntimeStore("my-plugin runtime not initialized"); +const store = createPluginRuntimeStore({ + pluginId: "my-plugin", + errorMessage: "my-plugin runtime not initialized", +}); // エントリーポイント内 export default defineChannelPluginEntry({ @@ -402,30 +400,32 @@ export default defineChannelPluginEntry({ // 他のファイル内 export function getRuntime() { - return store.getRuntime(); // 初期化されていない場合はthrow + return store.getRuntime(); // 初期化されていない場合は例外を投げる } export function tryGetRuntime() { - return store.tryGetRuntime(); // 初期化されていない場合はnullを返す + return store.tryGetRuntime(); // 初期化されていない場合は null を返す } ``` -## その他のトップレベル`api`フィールド +ランタイムストアの識別には `pluginId` を優先してください。より低レベルの `key` 形式は、1つのPluginが意図的に複数のランタイムスロットを必要とするまれなケース向けです。 -`api.runtime`に加えて、APIオブジェクトは以下も提供します: +## その他のトップレベル `api` フィールド -| フィールド | 型 | 説明 | -| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------- | -| `api.id` | `string` | プラグインID | -| `api.name` | `string` | プラグイン表示名 | -| `api.config` | `OpenClawConfig` | 現在の設定スナップショット（利用可能な場合は、アクティブなインメモリ実行時スナップショット） | -| `api.pluginConfig` | `Record` | `plugins.entries..config`から取得したプラグイン固有設定 | -| `api.logger` | `PluginLogger` | スコープ付きロガー（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 現在の読み込みモード。`"setup-runtime"`は、完全なエントリー起動/設定前の軽量ウィンドウです | -| `api.resolvePath(input)` | `(string) => string` | プラグインルートからの相対パスを解決します | +`api.runtime` に加えて、APIオブジェクトは次も提供します: + +| フィールド | 型 | 説明 | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Plugin id | +| `api.name` | `string` | Plugin表示名 | +| `api.config` | `OpenClawConfig` | 現在の設定スナップショット（利用可能な場合は、アクティブなインメモリランタイムスナップショット） | +| `api.pluginConfig` | `Record` | `plugins.entries..config` から取得したPlugin固有の設定 | +| `api.logger` | `PluginLogger` | スコープ付きロガー（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 現在のロードモード。`"setup-runtime"` は、完全なエントリー前の軽量な起動/セットアップ用ウィンドウです | +| `api.resolvePath(input)` | `(string) => string` | Pluginルートを基準に相対パスを解決 | ## 関連 - [SDK Overview](/ja-JP/plugins/sdk-overview) -- サブパスリファレンス -- [SDK Entry Points](/ja-JP/plugins/sdk-entrypoints) -- `definePluginEntry`オプション -- [Plugin Internals](/ja-JP/plugins/architecture) -- capability modelとレジストリ +- [SDK Entry Points](/ja-JP/plugins/sdk-entrypoints) -- `definePluginEntry` オプション +- [Plugin Internals](/ja-JP/plugins/architecture) -- 機能モデルとレジストリ diff --git a/docs/ja-JP/plugins/sdk-setup.md b/docs/ja-JP/plugins/sdk-setup.md index cbda25edb..b9bf45ce7 100644 --- a/docs/ja-JP/plugins/sdk-setup.md +++ b/docs/ja-JP/plugins/sdk-setup.md @@ -1,36 +1,37 @@ --- read_when: - - プラグインにセットアップウィザードを追加している - - setup-entry.tsとindex.tsの違いを理解する必要がある - - プラグイン設定スキーマまたはpackage.jsonのopenclawメタデータを定義している + - Plugin にセットアップ ウィザードを追加しています + - '`setup-entry.ts` と `index.ts` の違いを理解する必要があります' + - Plugin の設定スキーマまたは `package.json` の openclaw メタデータを定義しています sidebarTitle: Setup and Config -summary: セットアップウィザード、setup-entry.ts、設定スキーマ、およびpackage.jsonメタデータ -title: プラグインのセットアップと設定 +summary: セットアップ ウィザード、setup-entry.ts、設定スキーマ、package.json メタデータ +title: Plugin セットアップと設定 x-i18n: - generated_at: "2026-04-06T03:11:30Z" + generated_at: "2026-04-15T19:41:42Z" model: gpt-5.4 provider: openai - source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9 + source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b source_path: plugins/sdk-setup.md workflow: 15 --- -# プラグインのセットアップと設定 +# Plugin セットアップと設定 -プラグインパッケージング（`package.json`メタデータ）、マニフェスト -（`openclaw.plugin.json`）、セットアップエントリー、および設定スキーマのリファレンスです。 +Plugin パッケージング（`package.json` メタデータ）、マニフェスト +（`openclaw.plugin.json`）、セットアップ エントリ、設定スキーマのリファレンスです。 - **手順ガイドを探していますか?** パッケージングを文脈付きで説明するハウツーガイドは次を参照してください: + **手順を追った説明を探していますか？** ハウツー ガイドでは、パッケージングを文脈の中で扱っています： [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins#step-1-package-and-manifest) と [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins#step-1-package-and-manifest)。 -## パッケージメタデータ +## パッケージ メタデータ -プラグインシステムにプラグインが何を提供するかを伝えるため、`package.json`には`openclaw`フィールドが必要です。 +`package.json` には、Plugin システムにこの Plugin が何を提供するかを伝える +`openclaw` フィールドが必要です。 -**チャネルプラグイン:** +**Channel Plugin:** ```json { @@ -49,7 +50,7 @@ x-i18n: } ``` -**プロバイダープラグイン / ClawHub公開ベースライン:** +**Provider Plugin / ClawHub 公開ベースライン:** ```json openclaw-clawhub-package.json { @@ -70,46 +71,47 @@ x-i18n: } ``` -プラグインをClawHubで外部公開する場合、これらの`compat`フィールドと`build` +Plugin を ClawHub で外部公開する場合、これらの `compat` フィールドと `build` フィールドは必須です。正式な公開用スニペットは -`docs/snippets/plugin-publish/`にあります。 +`docs/snippets/plugin-publish/` にあります。 -### `openclaw`フィールド +### `openclaw` フィールド -| Field | Type | Description | -| ------------ | ---------- | -------------------------------------------------------------------------------------------------------- | -| `extensions` | `string[]` | エントリーポイントファイル（パッケージルートからの相対パス） | -| `setupEntry` | `string` | 軽量なセットアップ専用エントリー（任意） | -| `channel` | `object` | セットアップ、ピッカー、クイックスタート、およびステータス画面向けのチャネルカタログメタデータ | -| `providers` | `string[]` | このプラグインが登録するプロバイダーid | -| `install` | `object` | インストールヒント: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | -| `startup` | `object` | 起動時の動作フラグ | +| フィールド | 型 | 説明 | +| ---------- | ---------- | ------------------------------------------------------------------------------------------------------ | +| `extensions` | `string[]` | エントリ ポイント ファイル（パッケージ ルートからの相対パス） | +| `setupEntry` | `string` | 軽量なセットアップ専用エントリ（任意） | +| `channel` | `object` | セットアップ、ピッカー、クイックスタート、ステータス画面向けの Channel カタログ メタデータ | +| `providers` | `string[]` | この Plugin によって登録される Provider ID | +| `install` | `object` | インストール ヒント: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | +| `startup` | `object` | 起動時の動作フラグ | ### `openclaw.channel` -`openclaw.channel`は、ランタイム読み込み前のチャネル検出およびセットアップ画面向けの軽量なパッケージメタデータです。 +`openclaw.channel` は、ランタイムが読み込まれる前に Channel の検出とセットアップ画面で使われる、 +低コストなパッケージ メタデータです。 -| Field | Type | What it means | -| -------------------------------------- | ---------- | ----------------------------------------------------------------------- | -| `id` | `string` | 正式なチャネルid。 | -| `label` | `string` | 主チャネルラベル。 | -| `selectionLabel` | `string` | `label`と異なるべき場合のピッカー/セットアップ用ラベル。 | -| `detailLabel` | `string` | より豊かなチャネルカタログおよびステータス画面向けの補助詳細ラベル。 | -| `docsPath` | `string` | セットアップおよび選択リンク用のドキュメントパス。 | -| `docsLabel` | `string` | チャネルidと異なるべき場合にドキュメントリンクで使う上書きラベル。 | -| `blurb` | `string` | 短いオンボーディング/カタログ説明。 | -| `order` | `number` | チャネルカタログでの並び順。 | -| `aliases` | `string[]` | チャネル選択用の追加参照エイリアス。 | -| `preferOver` | `string[]` | このチャネルが上位に来るべき低優先度のプラグイン/チャネルid。 | -| `systemImage` | `string` | チャネルUIカタログ用の任意のアイコン/system-image名。 | -| `selectionDocsPrefix` | `string` | 選択画面でのドキュメントリンク前に置く接頭辞テキスト。 | -| `selectionDocsOmitLabel` | `boolean` | ラベル付きドキュメントリンクの代わりにドキュメントパスを直接表示する。 | -| `selectionExtras` | `string[]` | 選択文言に追加される短い文字列。 | -| `markdownCapable` | `boolean` | 送信書式判断で、このチャネルをMarkdown対応として扱います。 | -| `exposure` | `object` | セットアップ、設定済み一覧、およびドキュメント画面向けの可視性制御。 | -| `quickstartAllowFrom` | `boolean` | このチャネルを標準クイックスタート`allowFrom`セットアップフローに含めます。 | -| `forceAccountBinding` | `boolean` | アカウントが1つしかない場合でも、明示的なアカウントバインディングを要求します。 | -| `preferSessionLookupForAnnounceTarget` | `boolean` | このチャネルの通知先解決でセッション検索を優先します。 | +| フィールド | 型 | 意味 | +| ---------------------------------------- | ---------- | ----------------------------------------------------------------------------- | +| `id` | `string` | 正式な Channel ID。 | +| `label` | `string` | 主要な Channel ラベル。 | +| `selectionLabel` | `string` | `label` と異なる必要がある場合の、ピッカー/セットアップ用ラベル。 | +| `detailLabel` | `string` | より充実した Channel カタログやステータス画面向けの補助ラベル。 | +| `docsPath` | `string` | セットアップや選択リンク用のドキュメント パス。 | +| `docsLabel` | `string` | Channel ID と異なる必要がある場合に、ドキュメント リンクで使う上書きラベル。 | +| `blurb` | `string` | 短いオンボーディング/カタログ説明。 | +| `order` | `number` | Channel カタログでの並び順。 | +| `aliases` | `string[]` | Channel 選択用の追加の検索別名。 | +| `preferOver` | `string[]` | この Channel が優先されるべき、より優先度の低い Plugin/Channel ID。 | +| `systemImage` | `string` | Channel UI カタログ用の任意のアイコン/system-image 名。 | +| `selectionDocsPrefix` | `string` | 選択画面でドキュメント リンクの前に付ける接頭辞テキスト。 | +| `selectionDocsOmitLabel` | `boolean` | ラベル付きのドキュメント リンクではなく、ドキュメント パスを直接表示します。 | +| `selectionExtras` | `string[]` | 選択テキストに追加される短い追加文字列。 | +| `markdownCapable` | `boolean` | 送信時の書式設定判断のため、この Channel が Markdown 対応であることを示します。 | +| `exposure` | `object` | セットアップ、設定済み一覧、ドキュメント画面向けの Channel 表示制御。 | +| `quickstartAllowFrom` | `boolean` | この Channel を標準のクイックスタート `allowFrom` セットアップ フローに含めます。 | +| `forceAccountBinding` | `boolean` | アカウントが 1 つしかない場合でも、明示的なアカウント バインディングを必須にします。 | +| `preferSessionLookupForAnnounceTarget` | `boolean` | この Channel の告知先解決時に、セッション検索を優先します。 | 例: @@ -141,35 +143,39 @@ x-i18n: } ``` -`exposure`は次をサポートします。 +`exposure` では以下をサポートします。 -- `configured`: 設定済み/ステータス系の一覧画面にそのチャネルを含める -- `setup`: 対話型セットアップ/設定ピッカーにそのチャネルを含める -- `docs`: ドキュメント/ナビゲーション画面でそのチャネルを公開向けとして扱う +- `configured`: 設定済み/ステータス形式の一覧画面に Channel を含める +- `setup`: 対話型のセットアップ/設定ピッカーに Channel を含める +- `docs`: ドキュメント/ナビゲーション画面で Channel を公開対象として扱う -`showConfigured`と`showInSetup`は、レガシーエイリアスとして引き続きサポートされます。`exposure`を推奨します。 +`showConfigured` と `showInSetup` もレガシー エイリアスとして引き続きサポートされます。 +`exposure` を優先してください。 ### `openclaw.install` -`openclaw.install`はマニフェストメタデータではなく、パッケージメタデータです。 +`openclaw.install` はマニフェスト メタデータではなく、パッケージ メタデータです。 -| Field | Type | What it means | +| フィールド | 型 | 意味 | | ---------------------------- | -------------------- | -------------------------------------------------------------------------------- | -| `npmSpec` | `string` | インストール/更新フロー用の正式なnpm spec。 | -| `localPath` | `string` | ローカル開発またはバンドルインストールパス。 | -| `defaultChoice` | `"npm"` \| `"local"` | 両方利用可能な場合の優先インストール元。 | -| `minHostVersion` | `string` | `>=x.y.z`形式での最小サポートOpenClawバージョン。 | -| `allowInvalidConfigRecovery` | `boolean` | 特定の古い設定失敗からバンドルプラグイン再インストールフローが回復できるようにします。 | +| `npmSpec` | `string` | インストール/更新フローで使う正式な npm spec。 | +| `localPath` | `string` | ローカル開発用またはバンドル済みインストール パス。 | +| `defaultChoice` | `"npm"` \| `"local"` | 両方利用可能な場合の推奨インストール元。 | +| `minHostVersion` | `string` | `>=x.y.z` 形式で表す、サポートされる最小 OpenClaw バージョン。 | +| `allowInvalidConfigRecovery` | `boolean` | バンドル済み Plugin の再インストール フローで、特定の古い設定不整合からの回復を許可します。 | -`minHostVersion`が設定されている場合、インストールとマニフェストレジストリ読み込みの両方で強制されます。 -古いホストではプラグインはスキップされ、無効なバージョン文字列は拒否されます。 +`minHostVersion` が設定されている場合、インストール時とマニフェスト レジストリ読み込み時の両方で +それが適用されます。古いホストはその Plugin をスキップし、不正なバージョン文字列は拒否されます。 -`allowInvalidConfigRecovery`は壊れた設定全般を回避するものではありません。 -これは限定的なバンドルプラグイン回復専用であり、再インストール/セットアップが、欠落したバンドルプラグインパスや、その同じプラグインに対する古い`channels.`エントリーのような既知のアップグレード残骸を修復できるようにするためのものです。無関係な理由で設定が壊れている場合、インストールは引き続きフェイルクローズし、オペレーターに`openclaw doctor --fix`の実行を案内します。 +`allowInvalidConfigRecovery` は、壊れた設定全般に対する一般的なバイパスではありません。 +これは、同じ Plugin に対応するバンドル済み Plugin パスの欠落や古い `channels.` +エントリのような、既知のアップグレード残骸を再インストール/セットアップで修復できるようにする、 +限定的なバンドル済み Plugin 回復専用です。無関係な理由で設定が壊れている場合、 +インストールは引き続き安全側で失敗し、オペレーターに `openclaw doctor --fix` の実行を案内します。 -### 完全読み込みの遅延 +### 完全ロードの遅延 -チャネルプラグインは、次の設定で遅延読み込みにオプトインできます。 +Channel Plugin は、以下のように遅延読み込みを有効にできます。 ```json { @@ -183,20 +189,25 @@ x-i18n: } ``` -有効にすると、OpenClawはlisten前の起動フェーズでは、すでに設定済みのチャネルに対しても`setupEntry`だけを読み込みます。完全なエントリーはGatewayがlistenを開始した後に読み込まれます。 +これを有効にすると、OpenClaw は、すでに設定済みの Channel であっても、 +リッスン開始前の起動フェーズでは `setupEntry` のみを読み込みます。完全なエントリは +Gateway がリッスンを開始した後に読み込まれます。 - 遅延読み込みを有効にするのは、`setupEntry`がGatewayがlisten開始前に必要とするすべて（チャネル登録、HTTPルート、Gatewayメソッド）を登録している場合だけにしてください。完全なエントリーが必要な起動capabilityを所有している場合は、デフォルト動作のままにしてください。 + 遅延読み込みを有効にするのは、`setupEntry` が Gateway のリッスン開始前に必要なすべて + （Channel 登録、HTTP ルート、Gateway メソッド）を登録する場合に限ってください。 + 必要な起動機能を完全なエントリが担っている場合は、デフォルトの動作を維持してください。 -セットアップ/完全エントリーがGateway RPCメソッドを登録する場合は、プラグイン固有の接頭辞を維持してください。予約済みのコア管理名前空間（`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`）は引き続きコア所有であり、常に -`operator.admin`へ解決されます。 +セットアップ エントリまたは完全エントリで Gateway RPC メソッドを登録する場合は、 +Plugin 固有の接頭辞を付けてください。予約済みのコア管理名前空間（`config.*`、 +`exec.approvals.*`, `wizard.*`, `update.*`）はコア側の所有のままであり、常に +`operator.admin` に解決されます。 -## プラグインマニフェスト +## Plugin マニフェスト -すべてのネイティブプラグインは、パッケージルートに`openclaw.plugin.json`を必ず含める必要があります。 -OpenClawはこれを使って、プラグインコードを実行せずに設定を検証します。 +すべてのネイティブ Plugin は、パッケージ ルートに `openclaw.plugin.json` を含める必要があります。 +OpenClaw はこれを使って、Plugin コードを実行せずに設定を検証します。 ```json { @@ -216,7 +227,7 @@ OpenClawはこれを使って、プラグインコードを実行せずに設定 } ``` -チャネルプラグインでは、`kind`と`channels`を追加します。 +Channel Plugin の場合は、`kind` と `channels` を追加します。 ```json { @@ -231,7 +242,7 @@ OpenClawはこれを使って、プラグインコードを実行せずに設定 } ``` -設定がないプラグインでもスキーマは必須です。空のスキーマも有効です。 +設定を持たない Plugin でも、スキーマを含める必要があります。空のスキーマも有効です。 ```json { @@ -243,24 +254,25 @@ OpenClawはこれを使って、プラグインコードを実行せずに設定 } ``` -完全なスキーマリファレンスについては[Plugin Manifest](/ja-JP/plugins/manifest)を参照してください。 +完全なスキーマ リファレンスについては、[Plugin Manifest](/ja-JP/plugins/manifest) を参照してください。 -## ClawHub公開 +## ClawHub 公開 -プラグインパッケージには、パッケージ固有のClawHubコマンドを使ってください。 +Plugin パッケージでは、パッケージ専用の ClawHub コマンドを使用します。 ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -従来のskill専用公開エイリアスはSkills用です。プラグインパッケージでは常に -`clawhub package publish`を使用してください。 +旧来の skill 専用公開エイリアスは Skills 用です。Plugin パッケージでは、 +常に `clawhub package publish` を使用してください。 -## セットアップエントリー +## セットアップ エントリ -`setup-entry.ts`ファイルは、セットアップ画面のみ（オンボーディング、設定修復、 -無効化されたチャネルの検査）が必要なときにOpenClawが読み込む、`index.ts`の軽量な代替です。 +`setup-entry.ts` ファイルは `index.ts` の軽量な代替で、OpenClaw がセットアップ画面 +（オンボーディング、設定修復、無効化された Channel の確認）だけを必要とする場合に +読み込まれます。 ```typescript // setup-entry.ts @@ -270,62 +282,83 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -これにより、セットアップフロー中に重いランタイムコード（暗号ライブラリ、CLI登録、 -バックグラウンドサービス）を読み込まずに済みます。 +これにより、セットアップ フロー中に重いランタイム コード（暗号ライブラリ、CLI 登録、 +バックグラウンド サービス）を読み込まずに済みます。 -**OpenClawが完全なエントリーの代わりに`setupEntry`を使う場面:** +セットアップ安全なエクスポートをサイドカー モジュールに保持しているバンドル済みワークスペース Channel では、 +`defineSetupPluginEntry(...)` の代わりに +`openclaw/plugin-sdk/channel-entry-contract` の +`defineBundledChannelSetupEntry(...)` を使えます。このバンドル済みコントラクトは、 +任意の `runtime` エクスポートもサポートしており、セットアップ時のランタイム配線を +軽量かつ明示的に保てます。 -- チャネルは無効だが、セットアップ/オンボーディング画面が必要 -- チャネルは有効だが未設定 -- 遅延読み込みが有効（`deferConfiguredChannelFullLoadUntilAfterListen`） +**OpenClaw が完全なエントリではなく `setupEntry` を使う場合:** -**`setupEntry`が登録しなければならないもの:** +- Channel は無効化されているが、セットアップ/オンボーディング画面が必要な場合 +- Channel は有効だが未設定の場合 +- 遅延読み込みが有効な場合（`deferConfiguredChannelFullLoadUntilAfterListen`） -- チャネルプラグインオブジェクト（`defineSetupPluginEntry`経由） -- Gatewayのlisten前に必要なHTTPルート -- 起動中に必要なGatewayメソッド +**`setupEntry` が登録しなければならないもの:** -これらの起動時Gatewayメソッドでも、`config.*`や`update.*`のような予約済みコア管理名前空間は避ける必要があります。 +- Channel Plugin オブジェクト（`defineSetupPluginEntry` 経由） +- Gateway のリッスン前に必要な HTTP ルート +- 起動時に必要な Gateway メソッド -**`setupEntry`に含めるべきでないもの:** +これらの起動時 Gateway メソッドでも、`config.*` や `update.*` のような +予約済みコア管理名前空間は引き続き避ける必要があります。 -- CLI登録 -- バックグラウンドサービス -- 重いランタイムimport（crypto、SDK） -- 起動後にのみ必要なGatewayメソッド +**`setupEntry` に含めるべきではないもの:** -### 狭いセットアップヘルパーimport +- CLI 登録 +- バックグラウンド サービス +- 重いランタイム import（crypto、SDK） +- 起動後にのみ必要な Gateway メソッド -セットアップ専用のホットパスでは、セットアップ画面の一部だけが必要な場合、より広い -`plugin-sdk/setup`アンブレラではなく、狭いセットアップヘルパー境界を優先してください。 +### 狭いセットアップ ヘルパー import -| Import path | Use it for | Key exports | -| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | `setupEntry` / 遅延チャネル起動でも利用可能なセットアップ時ランタイムヘルパー | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | -| `plugin-sdk/setup-adapter-runtime` | 環境認識型アカウントセットアップアダプター | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | セットアップ/インストールCLI/アーカイブ/ドキュメントヘルパー | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +セットアップ専用のホット パスでは、セットアップ画面の一部だけが必要な場合、 +より広い `plugin-sdk/setup` アンブレラではなく、より狭いセットアップ ヘルパーの境界を優先してください。 -設定パッチヘルパー（`moveSingleAccountChannelSectionToDefaultAccount(...)`など）を含む完全な共有セットアップツールボックスが必要な場合は、より広い -`plugin-sdk/setup`境界を使用してください。 +| import パス | 用途 | 主な export | +| ---------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/setup-runtime` | `setupEntry` / 遅延 Channel 起動でも利用可能な、セットアップ時ランタイム ヘルパー | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-adapter-runtime` | 環境対応のアカウント セットアップ アダプター | `createEnvPatchedAccountSetupAdapter` | +| `plugin-sdk/setup-tools` | セットアップ/インストール用 CLI/アーカイブ/ドキュメント ヘルパー | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | -セットアップパッチアダプターは、import時にもホットパス安全性を維持します。バンドルされた単一アカウント昇格契約サーフェス検索は遅延評価されるため、`plugin-sdk/setup-runtime`をimportしても、アダプターが実際に使われる前にバンドル契約サーフェス検出を先行ロードしません。 +設定パッチ ヘルパー（例: +`moveSingleAccountChannelSectionToDefaultAccount(...)`）を含む共有セットアップ ツールボックス全体が必要な場合は、 +より広い `plugin-sdk/setup` 境界を使用してください。 -### チャネル所有の単一アカウント昇格 +セットアップ パッチ アダプターは import 時もホット パスで安全なままです。これらのバンドル済み +単一アカウント昇格コントラクト画面ルックアップは遅延されるため、 +`plugin-sdk/setup-runtime` を import しても、アダプターが実際に使われる前に +バンドル済みコントラクト画面検出が即座に読み込まれることはありません。 -チャネルが単一アカウントのトップレベル設定から -`channels..accounts.*`へアップグレードする際、共有のデフォルト動作では、昇格されたアカウントスコープ値を`accounts.default`へ移動します。 +### Channel 所有の単一アカウント昇格 -バンドルされたチャネルは、そのセットアップ契約サーフェスを通じてこの昇格を絞り込むか上書きできます。 +Channel が単一アカウントのトップレベル設定から +`channels..accounts.*` にアップグレードする場合、共有のデフォルト動作では、 +昇格されたアカウント スコープ値を `accounts.default` に移動します。 -- `singleAccountKeysToMove`: 昇格されたアカウントへ移動すべき追加のトップレベルキー -- `namedAccountPromotionKeys`: 名前付きアカウントがすでに存在する場合、これらのキーだけが昇格先アカウントへ移動し、共有ポリシー/配信キーはチャネルルートに残る -- `resolveSingleAccountPromotionTarget(...)`: どの既存アカウントが昇格値を受け取るかを選択 +バンドル済み Channel は、セットアップ コントラクト画面を通じてその昇格を +絞り込んだり上書きしたりできます。 -現在のバンドル例はMatrixです。既存の名前付きMatrixアカウントがちょうど1つある場合、または`defaultAccount`が`Ops`のような既存の非標準キーを指している場合、昇格では新しい`accounts.default`エントリーを作らず、そのアカウントを保持します。 +- `singleAccountKeysToMove`: 昇格されたアカウントに移動すべき追加のトップレベル キー +- `namedAccountPromotionKeys`: 名前付きアカウントがすでに存在する場合、これらの + キーだけが昇格されたアカウントに移動されます。共有のポリシー/配信キーは + Channel ルートに残ります +- `resolveSingleAccountPromotionTarget(...)`: どの既存アカウントが昇格された値を + 受け取るかを選択します + +現在のバンドル済みの例は Matrix です。名前付き Matrix アカウントがちょうど 1 つ +すでに存在する場合、または `defaultAccount` が `Ops` のような既存の非標準キーを +指している場合、昇格では新しい `accounts.default` エントリを作成せず、 +そのアカウントを維持します。 ## 設定スキーマ -プラグイン設定は、マニフェスト内のJSON Schemaに対して検証されます。ユーザーは次のようにプラグインを設定します。 +Plugin 設定は、マニフェスト内の JSON Schema に対して検証されます。ユーザーは +次のように Plugin を設定します。 ```json5 { @@ -341,9 +374,9 @@ export default defineSetupPluginEntry(myChannelPlugin); } ``` -プラグインは、登録中にこの設定を`api.pluginConfig`として受け取ります。 +Plugin は登録時に、この設定を `api.pluginConfig` として受け取ります。 -チャネル固有の設定には、代わりにチャネル設定セクションを使ってください。 +Channel 固有の設定では、代わりに Channel 設定セクションを使います。 ```json5 { @@ -356,10 +389,10 @@ export default defineSetupPluginEntry(myChannelPlugin); } ``` -### チャネル設定スキーマの構築 +### Channel 設定スキーマの構築 -`openclaw/plugin-sdk/core`の`buildChannelConfigSchema`を使うと、 -Zodスキーマを、OpenClawが検証する`ChannelConfigSchema`ラッパーへ変換できます。 +`openclaw/plugin-sdk/core` の `buildChannelConfigSchema` を使うと、 +Zod スキーマを OpenClaw が検証する `ChannelConfigSchema` ラッパーに変換できます。 ```typescript import { z } from "zod"; @@ -375,10 +408,10 @@ const accountSchema = z.object({ const configSchema = buildChannelConfigSchema(accountSchema); ``` -## セットアップウィザード +## セットアップ ウィザード -チャネルプラグインは、`openclaw onboard`向けに対話型セットアップウィザードを提供できます。 -ウィザードは`ChannelPlugin`上の`ChannelSetupWizard`オブジェクトです。 +Channel Plugin は `openclaw onboard` 向けに対話型セットアップ ウィザードを提供できます。 +ウィザードは `ChannelPlugin` 上の `ChannelSetupWizard` オブジェクトです。 ```typescript import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup"; @@ -411,21 +444,26 @@ const setupWizard: ChannelSetupWizard = { }; ``` -`ChannelSetupWizard`型は、`credentials`, `textInputs`, -`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize`などをサポートします。 -完全な例については、バンドルされたプラグインパッケージ（たとえばDiscordプラグインの`src/channel.setup.ts`）を参照してください。 +`ChannelSetupWizard` 型は、`credentials`、`textInputs`、 +`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` などをサポートします。 +完全な例については、バンドル済み Plugin パッケージ +（たとえば Discord Plugin の `src/channel.setup.ts`）を参照してください。 -標準的な -`note -> prompt -> parse -> merge -> patch`フローだけが必要なDM許可リストプロンプトには、`openclaw/plugin-sdk/setup`の共有セットアップヘルパー -`createPromptParsedAllowFromForAccount(...)`, -`createTopLevelChannelParsedAllowFromPrompt(...)`, および -`createNestedChannelParsedAllowFromPrompt(...)`を優先してください。 +標準の +`note -> prompt -> parse -> merge -> patch` フローだけが必要な DM 許可リスト プロンプトでは、 +`openclaw/plugin-sdk/setup` の共有セットアップ ヘルパー +`createPromptParsedAllowFromForAccount(...)`、 +`createTopLevelChannelParsedAllowFromPrompt(...)`、 +`createNestedChannelParsedAllowFromPrompt(...)` を優先してください。 -ラベル、スコア、および任意の追加行だけが異なるチャネルセットアップステータスブロックには、各プラグインで同じ`status`オブジェクトを手作業で作る代わりに、 -`openclaw/plugin-sdk/setup`の`createStandardChannelSetupStatus(...)`を優先してください。 +ラベル、スコア、任意の追加行だけが異なる Channel セットアップ ステータス ブロックでは、 +各 Plugin で同じ `status` オブジェクトを手書きする代わりに、 +`openclaw/plugin-sdk/setup` の +`createStandardChannelSetupStatus(...)` を優先してください。 -特定の文脈でのみ表示すべき任意セットアップ画面には、 -`openclaw/plugin-sdk/channel-setup`の`createOptionalChannelSetupSurface`を使ってください。 +特定の文脈でのみ表示されるべき任意のセットアップ画面では、 +`openclaw/plugin-sdk/channel-setup` の +`createOptionalChannelSetupSurface` を使います。 ```typescript import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; @@ -436,60 +474,72 @@ const setupSurface = createOptionalChannelSetupSurface({ npmSpec: "@myorg/openclaw-my-channel", docsPath: "/channels/my-channel", }); -// { setupAdapter, setupWizard } を返します +// Returns { setupAdapter, setupWizard } ``` -`plugin-sdk/channel-setup`は、任意インストール画面の片側だけが必要な場合のために、より低レベルの -`createOptionalChannelSetupAdapter(...)`および -`createOptionalChannelSetupWizard(...)`ビルダーも公開しています。 +`plugin-sdk/channel-setup` は、下位レベルの +`createOptionalChannelSetupAdapter(...)` と +`createOptionalChannelSetupWizard(...)` ビルダーも公開しており、 +その任意インストール画面の片方だけが必要な場合に使えます。 -生成される任意アダプター/ウィザードは、実際の設定書き込みではフェイルクローズします。`validateInput`, -`applyAccountConfig`, および `finalize` の間で1つの共通インストール必須メッセージを再利用し、`docsPath`が設定されていればドキュメントリンクを追加します。 +生成された任意アダプター/ウィザードは、実際の設定書き込み時には安全側で失敗します。 +これらは `validateInput`、`applyAccountConfig`、`finalize` の間で +1 つのインストール必須メッセージを再利用し、`docsPath` が設定されている場合は +ドキュメント リンクを追加します。 -バイナリ依存のセットアップUIでは、同じバイナリ/ステータス接着コードを各チャネルへ複製する代わりに、共有の委譲ヘルパーを優先してください。 +バイナリ ベースのセットアップ UI では、同じバイナリ/ステータス用の接着コードを +各 Channel に複製するのではなく、共有の委譲ヘルパーを優先してください。 -- `createDetectedBinaryStatus(...)`: ラベル、ヒント、スコア、およびバイナリ検出だけが異なるステータスブロック向け -- `createCliPathTextInput(...)`: パスベースのテキスト入力向け -- `createDelegatedSetupWizardStatusResolvers(...)`, - `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)`, および - `createDelegatedResolveConfigured(...)`: `setupEntry`がより重い完全ウィザードへ遅延的に転送する必要がある場合 -- `createDelegatedTextInputShouldPrompt(...)`: `setupEntry`が`textInputs[*].shouldPrompt`判定だけを委譲する必要がある場合 +- `createDetectedBinaryStatus(...)`: ラベル、ヒント、スコア、バイナリ検出だけが異なる + ステータス ブロック向け +- `createCliPathTextInput(...)`: パス ベースのテキスト入力向け +- `createDelegatedSetupWizardStatusResolvers(...)`、 + `createDelegatedPrepare(...)`、`createDelegatedFinalize(...)`、 + `createDelegatedResolveConfigured(...)`: + `setupEntry` が、より重い完全ウィザードへ遅延的に転送する必要がある場合 +- `createDelegatedTextInputShouldPrompt(...)`: + `setupEntry` が `textInputs[*].shouldPrompt` の判断だけを委譲する必要がある場合 ## 公開とインストール -**外部プラグイン:** [ClawHub](/ja-JP/tools/clawhub)またはnpmへ公開してから、次のようにインストールします。 +**外部 Plugin:** [ClawHub](/ja-JP/tools/clawhub) または npm に公開し、その後インストールします。 ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` -OpenClawは最初にClawHubを試し、自動的にnpmへフォールバックします。ClawHubを明示的に強制することもできます。 +OpenClaw は最初に ClawHub を試し、自動的に npm にフォールバックします。 +ClawHub を明示的に強制することもできます。 ```bash -openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHubのみ +openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub only ``` -対応する`npm:`上書きはありません。ClawHubフォールバック後にnpm経路を使いたい場合は、通常のnpmパッケージspecを使ってください。 +対応する `npm:` 上書きはありません。ClawHub フォールバック後に npm 経路を使いたい場合は、 +通常の npm パッケージ spec を使ってください。 ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` -**リポジトリ内プラグイン:** バンドルされたプラグインワークスペースツリー配下に置くと、ビルド中に自動検出されます。 +**リポジトリ内 Plugin:** バンドル済み Plugin ワークスペース ツリー配下に置くと、 +ビルド時に自動的に検出されます。 -**ユーザーがインストールできる形式:** +**ユーザーがインストールできるもの:** ```bash openclaw plugins install ``` - npm由来のインストールでは、`openclaw plugins install`は - `npm install --ignore-scripts`（ライフサイクルスクリプトなし）を実行します。プラグイン依存ツリーは純粋なJS/TSに保ち、`postinstall`ビルドを必要とするパッケージは避けてください。 + npm 由来のインストールでは、`openclaw plugins install` は + `npm install --ignore-scripts`（ライフサイクル スクリプトなし）を実行します。 + Plugin 依存ツリーは純粋な JS/TS に保ち、`postinstall` ビルドが必要な + パッケージは避けてください。 ## 関連 -- [SDK Entry Points](/ja-JP/plugins/sdk-entrypoints) -- `definePluginEntry`および`defineChannelPluginEntry` -- [Plugin Manifest](/ja-JP/plugins/manifest) -- 完全なマニフェストスキーマリファレンス -- [Building Plugins](/ja-JP/plugins/building-plugins) -- ステップごとの導入ガイド +- [SDK Entry Points](/ja-JP/plugins/sdk-entrypoints) -- `definePluginEntry` と `defineChannelPluginEntry` +- [Plugin Manifest](/ja-JP/plugins/manifest) -- 完全なマニフェスト スキーマ リファレンス +- [Building Plugins](/ja-JP/plugins/building-plugins) -- ステップごとの はじめに ガイド diff --git a/docs/ja-JP/plugins/sdk-testing.md b/docs/ja-JP/plugins/sdk-testing.md index 9947ce18b..bc9696254 100644 --- a/docs/ja-JP/plugins/sdk-testing.md +++ b/docs/ja-JP/plugins/sdk-testing.md @@ -1,36 +1,35 @@ --- read_when: - - plugin のテストを書いている場合 - - plugin SDK のテストユーティリティが必要な場合 - - bundled plugin の contract test を理解したい場合 + - あなたはPluginのテストを書いています + - Plugin SDKのテストユーティリティが必要です + - バンドルされたPluginのコントラクトテストを理解したい場合 sidebarTitle: Testing -summary: OpenClaw plugin 向けのテストユーティリティとパターン -title: Plugin Testing +summary: OpenClaw Pluginのテストユーティリティとパターン +title: Pluginのテスト x-i18n: - generated_at: "2026-04-05T12:52:48Z" + generated_at: "2026-04-15T19:41:37Z" model: gpt-5.4 provider: openai - source_hash: 2e95ed58ed180feadad17bb5138bd09e3b45f1f3ecdff4e2fba4874bb80099fe + source_hash: 2f75bd3f3b5ba34b05786e0dd96d493c36db73a1d258998bf589e27e45c0bd09 source_path: plugins/sdk-testing.md workflow: 15 --- -# Plugin Testing +# Pluginのテスト -OpenClaw plugin 向けのテストユーティリティ、パターン、および lint enforcement の -リファレンスです。 +OpenClaw Plugin向けのテストユーティリティ、パターン、およびlint適用に関するリファレンスです。 - **テスト例を探していますか?** ハウツーガイドには実際のテスト例が含まれています: - [Channel plugin tests](/plugins/sdk-channel-plugins#step-6-test) と - [Provider plugin tests](/plugins/sdk-provider-plugins#step-6-test)。 + **テスト例を探していますか？** ハウツーガイドには実際のテスト例が含まれています: + [Channel Pluginのテスト](/ja-JP/plugins/sdk-channel-plugins#step-6-test) と + [Provider Pluginのテスト](/ja-JP/plugins/sdk-provider-plugins#step-6-test)。 ## テストユーティリティ -**import:** `openclaw/plugin-sdk/testing` +**インポート:** `openclaw/plugin-sdk/testing` -testing subpath は、plugin 作成者向けに絞られた helper 群を export します: +このtestingサブパスは、Plugin作成者向けに絞り込まれた一連のヘルパーをエクスポートします: ```typescript import { @@ -40,17 +39,17 @@ import { } from "openclaw/plugin-sdk/testing"; ``` -### 利用可能な export +### 利用可能なエクスポート -| Export | Purpose | -| -------------------------------------- | ------------------------------------------------------ | -| `installCommonResolveTargetErrorCases` | target 解決のエラーハンドリング用の共通テストケース | -| `shouldAckReaction` | channel が ack reaction を追加すべきか確認する | -| `removeAckReactionAfterReply` | reply 配信後に ack reaction を削除する | +| Export | 用途 | +| -------------------------------------- | -------------------------------------- | +| `installCommonResolveTargetErrorCases` | ターゲット解決のエラーハンドリング向け共有テストケース | +| `shouldAckReaction` | チャンネルがackリアクションを追加すべきかどうかを確認 | +| `removeAckReactionAfterReply` | reply配信後にackリアクションを削除 | ### 型 -testing subpath は、テストファイルで便利な型も再 export します: +testingサブパスは、テストファイルで役立つ型も再エクスポートします: ```typescript import type { @@ -63,10 +62,9 @@ import type { } from "openclaw/plugin-sdk/testing"; ``` -## target 解決のテスト +## ターゲット解決のテスト -channel target 解決の標準エラーケースを追加するには、 -`installCommonResolveTargetErrorCases` を使います: +チャンネルのターゲット解決に対する標準的なエラーケースを追加するには、`installCommonResolveTargetErrorCases` を使用します: ```typescript import { describe } from "vitest"; @@ -75,13 +73,13 @@ import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testin describe("my-channel target resolution", () => { installCommonResolveTargetErrorCases({ resolveTarget: ({ to, mode, allowFrom }) => { - // あなたの channel の target 解決ロジック + // Your channel's target resolution logic return myChannelResolveTarget({ to, mode, allowFrom }); }, implicitAllowFrom: ["user1", "user2"], }); - // channel 固有のテストケースを追加 + // Add channel-specific test cases it("should resolve @username targets", () => { // ... }); @@ -90,7 +88,7 @@ describe("my-channel target resolution", () => { ## テストパターン -### channel plugin のユニットテスト +### Channel Pluginのユニットテスト ```typescript import { describe, it, expect, vi } from "vitest"; @@ -120,13 +118,13 @@ describe("my-channel plugin", () => { const inspection = myPlugin.setup.inspectAccount(cfg, undefined); expect(inspection.configured).toBe(true); expect(inspection.tokenStatus).toBe("available"); - // token 値は公開されない + // No token value exposed expect(inspection).not.toHaveProperty("token"); }); }); ``` -### provider plugin のユニットテスト +### Provider Pluginのユニットテスト ```typescript import { describe, it, expect } from "vitest"; @@ -154,72 +152,75 @@ describe("my-provider plugin", () => { }); ``` -### plugin runtime のモック +### Pluginランタイムのモック -`createPluginRuntimeStore` を使うコードでは、テスト内で runtime をモックします: +`createPluginRuntimeStore` を使用するコードでは、テスト内でランタイムをモックします: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; -const store = createPluginRuntimeStore("test runtime not set"); +const store = createPluginRuntimeStore({ + pluginId: "test-plugin", + errorMessage: "test runtime not set", +}); -// テストセットアップ内 +// In test setup const mockRuntime = { agent: { resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"), - // ... その他のモック + // ... other mocks }, config: { loadConfig: vi.fn(), writeConfigFile: vi.fn(), }, - // ... その他の namespace + // ... other namespaces } as unknown as PluginRuntime; store.setRuntime(mockRuntime); -// テスト後 +// After tests store.clearRuntime(); ``` -### インスタンスごとの stub を使ったテスト +### インスタンスごとのスタブを使ったテスト -prototype の変更ではなく、インスタンスごとの stub を推奨します: +プロトタイプの変更よりも、インスタンスごとのスタブを優先してください: ```typescript -// 推奨: インスタンスごとの stub +// Preferred: per-instance stub const client = new MyChannelClient(); client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); -// 非推奨: prototype の変更 +// Avoid: prototype mutation // MyChannelClient.prototype.sendMessage = vi.fn(); ``` -## contract test（repo 内 plugin） +## コントラクトテスト（リポジトリ内Plugin） -bundled plugin には、登録の所有権を検証する contract test があります: +バンドルされたPluginには、登録の所有権を検証するコントラクトテストがあります: ```bash pnpm test -- src/plugins/contracts/ ``` -これらのテストは次を検証します: +これらのテストでは、次の内容を検証します: -- どの plugin がどの provider を登録するか -- どの plugin がどの speech provider を登録するか +- どのPluginがどのProviderを登録するか +- どのPluginがどのspeech providerを登録するか - 登録形状の正しさ -- runtime contract への準拠 +- ランタイムのコントラクト準拠 ### スコープ付きテストの実行 -特定の plugin 向け: +特定のPluginに対して: ```bash pnpm test -- /my-channel/ ``` -contract test のみを実行する場合: +コントラクトテストのみを実行する場合: ```bash pnpm test -- src/plugins/contracts/shape.contract.test.ts @@ -227,36 +228,35 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts pnpm test -- src/plugins/contracts/runtime.contract.test.ts ``` -## lint enforcement（repo 内 plugin） +## lint適用（リポジトリ内Plugin） -repo 内 plugin には、`pnpm check` により 3 つのルールが強制されます: +リポジトリ内Pluginに対しては、`pnpm check` により3つのルールが適用されます: -1. **単一ルート import の禁止** -- `openclaw/plugin-sdk` のルート barrel は拒否される -2. **直接の `src/` import の禁止** -- plugin は `../../src/` を直接 import できない -3. **self-import の禁止** -- plugin は自身の `plugin-sdk/` subpath を import できない +1. **モノリシックなルートインポートの禁止** -- `openclaw/plugin-sdk` のルートbarrelは拒否されます +2. **直接の `src/` インポートの禁止** -- Pluginは `../../src/` を直接インポートできません +3. **自己インポートの禁止** -- Pluginは自身の `plugin-sdk/` サブパスをインポートできません -外部 plugin はこれらの lint ルールの対象ではありませんが、同じ -パターンに従うことが推奨されます。 +外部Pluginはこれらのlintルールの対象ではありませんが、同じパターンに従うことを推奨します。 ## テスト設定 -OpenClaw は、V8 coverage threshold を持つ Vitest を使用します。plugin テストでは: +OpenClawは、V8カバレッジしきい値付きのVitestを使用しています。Pluginテストでは次を使用します: ```bash -# すべてのテストを実行 +# Run all tests pnpm test -# 特定の plugin テストを実行 +# Run specific plugin tests pnpm test -- /my-channel/src/channel.test.ts -# 特定のテスト名フィルターで実行 +# Run with a specific test name filter pnpm test -- /my-channel/ -t "resolves account" -# coverage 付きで実行 +# Run with coverage pnpm test:coverage ``` -ローカル実行でメモリー圧迫が起きる場合: +ローカル実行でメモリ負荷が発生する場合: ```bash OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test @@ -264,7 +264,7 @@ OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ## 関連 -- [SDK Overview](/plugins/sdk-overview) -- import 規約 -- [SDK Channel Plugins](/plugins/sdk-channel-plugins) -- channel plugin interface -- [SDK Provider Plugins](/plugins/sdk-provider-plugins) -- provider plugin hook -- [Building Plugins](/plugins/building-plugins) -- はじめにガイド +- [SDK Overview](/ja-JP/plugins/sdk-overview) -- インポート規約 +- [SDK Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) -- Channel Pluginインターフェース +- [SDK Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) -- Provider Pluginフック +- [Building Plugins](/ja-JP/plugins/building-plugins) -- はじめにガイド diff --git a/docs/ja-JP/reference/token-use.md b/docs/ja-JP/reference/token-use.md index e010e68b2..1264f69fe 100644 --- a/docs/ja-JP/reference/token-use.md +++ b/docs/ja-JP/reference/token-use.md @@ -1,102 +1,143 @@ --- read_when: - トークン使用量、コスト、またはコンテキストウィンドウの説明 - - コンテキストの増大や圧縮の挙動のデバッグ -summary: OpenClaw がプロンプトコンテキストを構築する方法と、トークン使用量 + コストを報告する方法 + - コンテキストの増大やCompactionの挙動をデバッグすること +summary: OpenClawがどのようにプロンプトコンテキストを構築し、トークン使用量とコストを報告するか title: トークン使用量とコスト x-i18n: - generated_at: "2026-04-12T04:43:45Z" + generated_at: "2026-04-15T19:42:12Z" model: gpt-5.4 provider: openai - source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb + source_hash: 9a706d3df8b2ea1136b3535d216c6b358e43aee2a31a4759824385e1345e6fe5 source_path: reference/token-use.md workflow: 15 --- # トークン使用量とコスト -OpenClaw は文字数ではなく、**トークン**を追跡します。トークンはモデルごとに異なりますが、ほとんどの OpenAI スタイルのモデルでは、英語テキストは平均して 1 トークンあたり約 4 文字です。 +OpenClawは**文字数**ではなく**トークン**を追跡します。トークンはモデル固有ですが、ほとんどのOpenAI系モデルでは英語テキストで平均して1トークンあたり約4文字です。 ## システムプロンプトの構築方法 -OpenClaw は実行のたびに独自のシステムプロンプトを組み立てます。これには次が含まれます。 +OpenClawは実行のたびに独自のシステムプロンプトを組み立てます。これには次が含まれます: - ツール一覧 + 短い説明 -- Skills 一覧（メタデータのみ。指示は必要時に `read` で読み込まれます） -- セルフアップデートの指示 -- ワークスペース + ブートストラップファイル（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、新規時の `BOOTSTRAP.md`、さらに存在する場合は `MEMORY.md`、または小文字の代替として `memory.md`）。大きなファイルは `agents.defaults.bootstrapMaxChars`（デフォルト: 20000）で切り詰められ、ブートストラップ全体の注入量は `agents.defaults.bootstrapTotalMaxChars`（デフォルト: 150000）で上限設定されます。`memory/*.md` の日次ファイルは通常のブートストラッププロンプトには含まれません。通常のターンではメモリツール経由で必要時に利用されますが、素の `/new` と `/reset` では、最初のターンに限って最近の日次メモリを含むワンショットの起動コンテキストブロックが前置されることがあります。この起動プレリュードは `agents.defaults.startupContext` で制御されます。 +- Skills一覧（メタデータのみ。指示は必要時に `read` で読み込まれます）。 + コンパクトなSkillsブロックは `skills.limits.maxSkillsPromptChars` によって制限され、 + エージェントごとのオーバーライドとして + `agents.list[].skillsLimits.maxSkillsPromptChars` を設定することもできます。 +- 自己更新の指示 +- ワークスペース + ブートストラップファイル（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、新規時の `BOOTSTRAP.md`、および存在する場合の `MEMORY.md` または小文字フォールバックの `memory.md`）。大きなファイルは `agents.defaults.bootstrapMaxChars`（デフォルト: 12000）で切り詰められ、ブートストラップ注入全体は `agents.defaults.bootstrapTotalMaxChars`（デフォルト: 60000）で上限が設定されます。`memory/*.md` の日次ファイルは通常のブートストラッププロンプトには含まれません。通常のターンではメモリツール経由のオンデマンドのままですが、素の `/new` と `/reset` では、最初のターンに限り最近の日次メモリを含むワンショットの起動コンテキストブロックを先頭に追加できます。この起動プレリュードは `agents.defaults.startupContext` で制御されます。 - 時刻（UTC + ユーザーのタイムゾーン） -- 返信タグ + ハートビートの挙動 -- ランタイムメタデータ（ホスト/OS/モデル/思考） +- 返信タグ + Heartbeatの挙動 +- ランタイムメタデータ（ホスト/OS/モデル/thinking） -完全な内訳は [システムプロンプト](/ja-JP/concepts/system-prompt) を参照してください。 +完全な内訳は [System Prompt](/ja-JP/concepts/system-prompt) を参照してください。 ## コンテキストウィンドウに含まれるもの -モデルが受け取るものはすべて、コンテキスト上限に対してカウントされます。 +モデルが受け取るものはすべてコンテキスト上限に含まれます: -- システムプロンプト（上記のすべてのセクション） +- システムプロンプト（上記の全セクション） - 会話履歴（ユーザー + アシスタントメッセージ） - ツール呼び出しとツール結果 - 添付ファイル/文字起こし（画像、音声、ファイル） -- 圧縮サマリーと枝刈りアーティファクト -- プロバイダーのラッパーや安全性ヘッダー（表示されませんが、やはりカウントされます） +- Compactionの要約とpruning成果物 +- Providerラッパーや安全性ヘッダー（表示はされませんが、カウント対象です） -画像については、OpenClaw はプロバイダー呼び出し前に文字起こし/ツールの画像ペイロードを縮小します。これを調整するには `agents.defaults.imageMaxDimensionPx`（デフォルト: `1200`）を使用します。 +ランタイム負荷の高い一部のサーフェスには、独自の明示的な上限があります: -- 値を小さくすると、通常はビジョントークン使用量とペイロードサイズが減ります。 -- 値を大きくすると、OCR や UI を多く含むスクリーンショットでより多くの視覚的詳細が保持されます。 +- `agents.defaults.contextLimits.memoryGetMaxChars` +- `agents.defaults.contextLimits.memoryGetDefaultLines` +- `agents.defaults.contextLimits.toolResultMaxChars` +- `agents.defaults.contextLimits.postCompactionMaxChars` -実用的な内訳（注入された各ファイル、ツール、Skills、システムプロンプトサイズごと）を確認するには、`/context list` または `/context detail` を使ってください。[コンテキスト](/ja-JP/concepts/context) も参照してください。 +エージェントごとのオーバーライドは `agents.list[].contextLimits` の下にあります。これらのノブは、 +上限付きのランタイム抜粋と、ランタイム所有の注入ブロックに対するものです。これらは +ブートストラップ上限、起動コンテキスト上限、Skillsプロンプト上限とは別です。 + +画像については、OpenClawはProvider呼び出し前に文字起こし/ツール画像ペイロードを縮小します。 +これを調整するには `agents.defaults.imageMaxDimensionPx`（デフォルト: `1200`）を使用します: + +- 値を低くすると、通常はvisionトークン使用量とペイロードサイズが減少します。 +- 値を高くすると、OCRやUI中心のスクリーンショットでより多くの視覚的詳細を保持できます。 + +実用的な内訳（注入された各ファイル、ツール、Skills、システムプロンプトサイズごと）を確認するには、`/context list` または `/context detail` を使用してください。[Context](/ja-JP/concepts/context) を参照してください。 ## 現在のトークン使用量を確認する方法 -チャットでは次を使用します。 +チャットでは次を使用します: -- `/status` → セッションモデル、コンテキスト使用量、前回応答の入力/出力トークン、**推定コスト**（API キー時のみ）を表示する **絵文字豊富なステータスカード**。 -- `/usage off|tokens|full` → すべての返信に **応答ごとの使用量フッター** を追加します。 - - セッション単位で永続化されます（`responseUsage` として保存）。 - - OAuth 認証では **コストは非表示** です（トークンのみ）。 -- `/usage cost` → OpenClaw のセッションログからローカルのコスト概要を表示します。 +- `/status` → セッションモデル、コンテキスト使用量、 + 直近の応答の入力/出力トークン、および**推定コスト**（APIキーのみ）を表示する + **絵文字豊富なステータスカード**。 +- `/usage off|tokens|full` → すべての返信に**応答ごとの使用量フッター**を追加します。 + - セッションごとに保持されます（`responseUsage` として保存）。 + - OAuth認証では**コストは非表示**です（トークンのみ）。 +- `/usage cost` → OpenClawのセッションログからローカルのコスト概要を表示します。 -その他の画面: +その他のサーフェス: -- **TUI/Web TUI:** `/status` と `/usage` がサポートされています。 -- **CLI:** `openclaw status --usage` と `openclaw channels list` は、正規化されたプロバイダーのクォータウィンドウ（応答ごとのコストではなく `X% left`）を表示します。 - 現在の使用量ウィンドウ対応プロバイダー: Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi、z.ai。 +- **TUI/Web TUI:** `/status` + `/usage` がサポートされています。 +- **CLI:** `openclaw status --usage` と `openclaw channels list` は + 正規化されたProviderクォータウィンドウ（`X% left`。応答ごとのコストではありません）を表示します。 + 現在の使用量ウィンドウ対応Provider: Anthropic、GitHub Copilot、Gemini CLI、 + OpenAI Codex、MiniMax、Xiaomi、z.ai。 -使用量表示では、表示前に一般的なプロバイダーネイティブのフィールド別名を正規化します。OpenAI 系 Responses トラフィックでは、これに `input_tokens` / `output_tokens` と `prompt_tokens` / `completion_tokens` の両方が含まれるため、転送方式固有のフィールド名によって `/status`、`/usage`、またはセッション概要の表示が変わることはありません。 -Gemini CLI の JSON 使用量も正規化されます。返信テキストは `response` から取得され、CLI が明示的な `stats.input` フィールドを省略した場合は、`stats.cached` が `cacheRead` に対応付けられ、`stats.input_tokens - stats.cached` が使われます。 -ネイティブな OpenAI 系 Responses トラフィックでは、WebSocket/SSE の使用量別名も同様に正規化され、`total_tokens` が欠落しているか `0` の場合は、合計が正規化済みの input + output にフォールバックします。 -現在のセッションスナップショットが疎な場合、`/status` と `session_status` は最新の transcript 使用量ログからトークン/キャッシュカウンターやアクティブなランタイムモデルラベルを復元することもできます。既存のゼロ以外のライブ値は引き続き transcript フォールバック値より優先され、保存済み合計が存在しないか小さい場合は、より大きなプロンプト指向の transcript 合計が優先されることがあります。 -プロバイダーのクォータウィンドウ用の使用量認証は、利用可能な場合はプロバイダー固有のフックから取得されます。そうでない場合、OpenClaw は auth profile、env、または config から一致する OAuth/API キー資格情報にフォールバックします。 +使用量サーフェスは、表示前に一般的なProviderネイティブのフィールド別名を正規化します。 +OpenAI系のResponsesトラフィックでは、これに `input_tokens` / +`output_tokens` と `prompt_tokens` / `completion_tokens` の両方が含まれるため、トランスポート固有の +フィールド名によって `/status`、`/usage`、またはセッション要約が変わることはありません。 +Gemini CLIのJSON使用量も正規化されます: 返信テキストは `response` から取得され、 +CLIが明示的な `stats.input` フィールドを省略した場合は、`stats.cached` は `cacheRead` にマップされ、 +`stats.input_tokens - stats.cached` が使用されます。 +ネイティブなOpenAI系Responsesトラフィックでは、WebSocket/SSEの使用量別名も同様に正規化され、 +`total_tokens` が欠けているか `0` の場合は、正規化された入力 + 出力から合計が補完されます。 +現在のセッションスナップショットが疎な場合、`/status` と `session_status` は +直近の文字起こし使用量ログからトークン/キャッシュカウンターとアクティブなランタイムモデルラベルを復元することもできます。 +既存のゼロ以外のライブ値は、引き続き文字起こしのフォールバック値より優先され、 +保存済み合計が欠けているか小さい場合には、より大きいプロンプト指向の文字起こし合計が優先されることがあります。 +Providerクォータウィンドウの使用量認証は、利用可能な場合はProvider固有のフックから取得されます。 +それ以外の場合、OpenClawは認証プロファイル、環境変数、または設定から一致するOAuth/APIキー資格情報へフォールバックします。 ## コスト見積もり（表示される場合） -コストは、モデルの価格設定 config から見積もられます。 +コストはモデルの価格設定から見積もられます: ``` models.providers..models[].cost ``` -これらは `input`、`output`、`cacheRead`、`cacheWrite` に対する **100 万トークンあたりの USD** です。価格設定がない場合、OpenClaw はトークンのみを表示します。OAuth トークンではドル建てコストは表示されません。 +これらは `input`、`output`、`cacheRead`、`cacheWrite` に対する**100万トークンあたりのUSD**です。 +価格設定がない場合、OpenClawはトークンのみを表示します。OAuthトークンでは +ドルコストは表示されません。 -## キャッシュ TTL と枝刈りの影響 +## キャッシュTTLとpruningの影響 -プロバイダーのプロンプトキャッシュは、キャッシュ TTL ウィンドウ内でのみ適用されます。OpenClaw はオプションで **cache-ttl pruning** を実行できます。これは、キャッシュ TTL の期限切れ後にセッションを枝刈りし、その後キャッシュウィンドウをリセットして、以降のリクエストで履歴全体を再キャッシュする代わりに新たにキャッシュされたコンテキストを再利用できるようにするものです。これにより、セッションが TTL を超えてアイドル状態になった場合のキャッシュ書き込みコストを低く保てます。 +Providerのプロンプトキャッシュは、キャッシュTTLウィンドウ内でのみ適用されます。OpenClawは +オプションで**cache-ttl pruning**を実行できます: キャッシュTTLの有効期限が切れたらセッションをpruneし、 +その後キャッシュウィンドウをリセットして、後続のリクエストが履歴全体を再キャッシュする代わりに +新たにキャッシュされたコンテキストを再利用できるようにします。これにより、セッションがTTLを超えて +アイドル状態になった場合のキャッシュ書き込みコストを低く保てます。 -これは [Gateway configuration](/ja-JP/gateway/configuration) で設定でき、挙動の詳細は [Session pruning](/ja-JP/concepts/session-pruning) を参照してください。 +これを設定するには [Gateway configuration](/ja-JP/gateway/configuration) を参照し、 +挙動の詳細は [Session pruning](/ja-JP/concepts/session-pruning) を参照してください。 -ハートビートは、アイドル期間をまたいでキャッシュを**ウォーム**な状態に保つことができます。モデルのキャッシュ TTL が `1h` の場合、ハートビート間隔をその少し手前（例: `55m`）に設定すると、完全なプロンプトの再キャッシュを避けられ、キャッシュ書き込みコストを減らせます。 +Heartbeatは、アイドルギャップをまたいでキャッシュを**温かい**状態に保つことができます。モデルのキャッシュTTLが +`1h` の場合、Heartbeat間隔をそれより少し短く（例: `55m`）設定すると、 +完全なプロンプトの再キャッシュを避けられ、キャッシュ書き込みコストを削減できます。 -マルチエージェント構成では、1 つの共有モデル config を維持しつつ、`agents.list[].params.cacheRetention` でエージェントごとにキャッシュ挙動を調整できます。 +マルチエージェント構成では、共有のモデル設定を1つ保ちつつ、 +`agents.list[].params.cacheRetention` でエージェントごとにキャッシュ挙動を調整できます。 -各設定項目の完全なガイドについては、[Prompt Caching](/ja-JP/reference/prompt-caching) を参照してください。 +各ノブの完全ガイドは [Prompt Caching](/ja-JP/reference/prompt-caching) を参照してください。 -Anthropic API の価格設定では、キャッシュ読み取りは入力トークンよりかなり安価である一方、キャッシュ書き込みはより高い倍率で課金されます。最新の料金と TTL 倍率については、Anthropic の prompt caching pricing を参照してください: +Anthropic APIの価格設定では、cache readはinputトークンより大幅に安価である一方、 +cache writeはより高い倍率で課金されます。最新の料金とTTL倍率については、 +Anthropicのプロンプトキャッシュ料金を参照してください: [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) -### 例: heartbeat で 1h キャッシュをウォームに保つ +### 例: Heartbeatで1時間キャッシュを温かい状態に保つ ```yaml agents: @@ -111,7 +152,7 @@ agents: every: "55m" ``` -### 例: エージェントごとのキャッシュ戦略を使った混在トラフィック +### 例: エージェントごとのキャッシュ戦略を使った混合トラフィック ```yaml agents: @@ -121,22 +162,25 @@ agents: models: "anthropic/claude-opus-4-6": params: - cacheRetention: "long" # ほとんどのエージェント向けのデフォルトのベースライン + cacheRetention: "long" # default baseline for most agents list: - id: "research" default: true heartbeat: - every: "55m" # 長時間セッション向けに長いキャッシュをウォームに保つ + every: "55m" # keep long cache warm for deep sessions - id: "alerts" params: - cacheRetention: "none" # バースト的な通知ではキャッシュ書き込みを避ける + cacheRetention: "none" # avoid cache writes for bursty notifications ``` -`agents.list[].params` は、選択されたモデルの `params` の上にマージされるため、`cacheRetention` だけを上書きし、他のモデルデフォルトはそのまま継承できます。 +`agents.list[].params` は選択されたモデルの `params` の上にマージされるため、 +`cacheRetention` のみをオーバーライドし、他のモデルデフォルトはそのまま継承できます。 -### 例: Anthropic 1M context beta ヘッダーを有効化する +### 例: Anthropicの1Mコンテキストベータヘッダーを有効にする -Anthropic の 1M コンテキストウィンドウは現在ベータ制限付きです。OpenClaw は、対応する Opus または Sonnet モデルで `context1m` を有効にすると、必要な `anthropic-beta` 値を注入できます。 +Anthropicの1Mコンテキストウィンドウは現在ベータ制限付きです。OpenClawでは、 +サポートされているOpusまたはSonnetモデルで `context1m` を有効にすると、 +必要な `anthropic-beta` 値を注入できます。 ```yaml agents: @@ -147,20 +191,23 @@ agents: context1m: true ``` -これは Anthropic の `context-1m-2025-08-07` beta ヘッダーに対応します。 +これはAnthropicの `context-1m-2025-08-07` ベータヘッダーにマップされます。 これは、そのモデルエントリで `context1m: true` が設定されている場合にのみ適用されます。 -要件: 資格情報が long-context 利用対象である必要があります。そうでない場合、Anthropic はそのリクエストに対してプロバイダー側のレート制限エラーを返します。 +要件: 資格情報がロングコンテキスト利用の対象である必要があります。そうでない場合、 +Anthropicはそのリクエストに対してProvider側のレート制限エラーを返します。 -Anthropic を OAuth/サブスクリプショントークン（`sk-ant-oat-*`）で認証している場合、OpenClaw は `context-1m-*` beta ヘッダーをスキップします。これは Anthropic が現在その組み合わせを HTTP 401 で拒否するためです。 +AnthropicをOAuth/サブスクリプショントークン（`sk-ant-oat-*`）で認証している場合、 +Anthropicは現在その組み合わせをHTTP 401で拒否するため、OpenClawは +`context-1m-*` ベータヘッダーをスキップします。 -## トークン圧迫を減らすためのヒント +## トークン負荷を減らすためのヒント -- `/compact` を使って長いセッションを要約する。 -- ワークフロー内で大きなツール出力を削減する。 -- スクリーンショットが多いセッションでは `agents.defaults.imageMaxDimensionPx` を下げる。 -- Skill の説明は短く保つ（Skill 一覧はプロンプトに注入されるため）。 -- 冗長で探索的な作業には小さいモデルを優先する。 +- 長いセッションは `/compact` を使って要約します。 +- ワークフロー内で大きなツール出力を切り詰めます。 +- スクリーンショット中心のセッションでは `agents.defaults.imageMaxDimensionPx` を下げます。 +- Skillの説明は短く保ちます（Skill一覧はプロンプトに注入されます）。 +- 冗長で探索的な作業には、より小さいモデルを優先します。 -正確な Skill 一覧のオーバーヘッド計算式は [Skills](/ja-JP/tools/skills) を参照してください。 +正確なSkill一覧のオーバーヘッド計算式については [Skills](/ja-JP/tools/skills) を参照してください。