diff --git a/docs/ja-JP/channels/discord.md b/docs/ja-JP/channels/discord.md index daa908c17..748e3095b 100644 --- a/docs/ja-JP/channels/discord.md +++ b/docs/ja-JP/channels/discord.md @@ -4,19 +4,19 @@ read_when: summary: Discord ボットのサポート状況、機能、設定 title: Discord x-i18n: - generated_at: "2026-05-04T02:21:33Z" + generated_at: "2026-05-04T07:02:47Z" model: gpt-5.5 provider: openai - source_hash: df4e045e39f8977f779fe409abf41dad0d950c92f1230c51ff356343513df812 + source_hash: 1e00f9d9b134296ac1ca52bb4058fc62ea7a95c4d46d9478648b2ecdd448652a source_path: channels/discord.md workflow: 16 --- -Discord 公式 Gateway 経由で DM とギルドチャンネルに対応しています。 +DM とギルドチャンネルで、公式 Discord gateway 経由ですぐに利用できます。 - Discord DM はデフォルトでペアリングモードになります。 + Discord の DM はデフォルトでペアリングモードになります。 ネイティブのコマンド動作とコマンドカタログ。 @@ -28,40 +28,40 @@ Discord 公式 Gateway 経由で DM とギルドチャンネルに対応して ## クイックセットアップ -bot 付きの新しいアプリケーションを作成し、その bot をサーバーに追加して、OpenClaw とペアリングする必要があります。bot は自分のプライベートサーバーに追加することをおすすめします。まだサーバーがない場合は、[先に作成してください](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（**Create My Own > For me and my friends** を選択）。 +Bot 付きの新しいアプリケーションを作成し、その Bot を自分のサーバーに追加して、OpenClaw とペアリングする必要があります。Bot は自分のプライベートサーバーに追加することをおすすめします。まだサーバーがない場合は、[先に作成してください](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（**Create My Own > For me and my friends** を選びます）。 - - [Discord Developer Portal](https://discord.com/developers/applications) に移動し、**New Application** をクリックします。名前は「OpenClaw」のようなものにします。 + + [Discord Developer Portal](https://discord.com/developers/applications) に移動し、**New Application** をクリックします。「OpenClaw」のような名前を付けます。 - サイドバーの **Bot** をクリックします。**Username** を、自分の OpenClaw エージェントに付けたい名前に設定します。 + サイドバーの **Bot** をクリックします。**Username** を OpenClaw エージェントに付けたい名前に設定します。 - 引き続き **Bot** ページで、**Privileged Gateway Intents** まで下にスクロールして、次を有効にします。 + 引き続き **Bot** ページで、**Privileged Gateway Intents** まで下にスクロールし、次を有効にします。 - **Message Content Intent**（必須） - - **Server Members Intent**（推奨。ロール許可リストと名前から ID への照合に必要） - - **Presence Intent**（任意。プレゼンス更新にのみ必要） + - **Server Members Intent**（推奨。ロール許可リストと名前から ID への照合に必須） + - **Presence Intent**（任意。プレゼンス更新が必要な場合のみ） - + **Bot** ページの上部に戻り、**Reset Token** をクリックします。 - 名前はそうなっていますが、これは最初のトークンを生成するものです。「reset」されるものはありません。 + 名前に反して、これは最初のトークンを生成します。「リセット」されるものはありません。 - トークンをコピーしてどこかに保存します。これが **Bot Token** で、まもなく必要になります。 + トークンをコピーしてどこかに保存します。これは **Bot Token** で、すぐに必要になります。 - - サイドバーの **OAuth2** をクリックします。bot をサーバーに追加するために、適切な権限を持つ招待 URL を生成します。 + + サイドバーの **OAuth2** をクリックします。Bot をサーバーに追加するための適切な権限を持つ招待 URL を生成します。 - **OAuth2 URL Generator** まで下にスクロールして、次を有効にします。 + **OAuth2 URL Generator** まで下にスクロールし、次を有効にします。 - `bot` - `applications.commands` @@ -77,31 +77,31 @@ bot 付きの新しいアプリケーションを作成し、その bot をサ - Attach Files - Add Reactions（任意） - これは通常のテキストチャンネル向けのベースラインセットです。フォーラムやメディアチャンネルのワークフローでスレッドを作成または継続する場合を含め、Discord スレッドに投稿する予定がある場合は、**Send Messages in Threads** も有効にしてください。 - 下部に生成された URL をコピーし、ブラウザーに貼り付け、サーバーを選択して **Continue** をクリックして接続します。これで Discord サーバーに bot が表示されるはずです。 + これは通常のテキストチャンネル向けの基本セットです。フォーラムやメディアチャンネルのワークフローなど、スレッドを作成または継続する Discord スレッドに投稿する予定がある場合は、**Send Messages in Threads** も有効にしてください。 + 下部に生成された URL をコピーし、ブラウザーに貼り付け、サーバーを選択して **Continue** をクリックして接続します。これで Discord サーバーに Bot が表示されるはずです。 - + Discord アプリに戻り、内部 ID をコピーできるように Developer Mode を有効にする必要があります。 - 1. **User Settings**（アバターの横にある歯車アイコン）→ **Advanced** → **Developer Mode** をオンに切り替える + 1. **User Settings**（アバター横の歯車アイコン）→ **Advanced** → **Developer Mode** をオンに切り替えます 2. サイドバーの **server icon** を右クリック → **Copy Server ID** 3. 自分の **own avatar** を右クリック → **Copy User ID** - **Server ID** と **User ID** を Bot Token と一緒に保存します。次の手順で 3 つすべてを OpenClaw に送ります。 + **Server ID** と **User ID** を Bot Token と一緒に保存します。次のステップで 3 つすべてを OpenClaw に送ります。 - ペアリングを機能させるには、Discord が bot から自分への DM を許可している必要があります。**server icon** を右クリック → **Privacy Settings** → **Direct Messages** をオンに切り替えます。 + ペアリングを機能させるには、Discord が Bot から自分への DM を許可している必要があります。**server icon** を右クリック → **Privacy Settings** → **Direct Messages** をオンに切り替えます。 - これにより、サーバーメンバー（bot を含む）が自分に DM を送信できるようになります。OpenClaw で Discord DM を使いたい場合は、この設定を有効のままにしてください。ギルドチャンネルだけを使う予定なら、ペアリング後に DM を無効にできます。 + これにより、サーバーメンバー（Bot を含む）が自分に DM を送信できます。OpenClaw で Discord の DM を使いたい場合は、これを有効のままにしてください。ギルドチャンネルだけを使う予定なら、ペアリング後に DM を無効にできます。 - - Discord bot トークンはシークレット（パスワードのようなもの）です。エージェントにメッセージを送る前に、OpenClaw を実行しているマシンで設定してください。 + + Discord Bot トークンは秘密情報（パスワードのようなもの）です。エージェントにメッセージを送る前に、OpenClaw を実行しているマシンで設定します。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -120,19 +120,19 @@ openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - OpenClaw がすでにバックグラウンドサービスとして実行されている場合は、OpenClaw Mac アプリから再起動するか、`openclaw gateway run` プロセスを停止して再起動してください。 - マネージドサービスとしてインストールしている場合は、`DISCORD_BOT_TOKEN` が存在するシェルから `openclaw gateway install` を実行するか、変数を `~/.openclaw/.env` に保存して、再起動後にサービスが env SecretRef を解決できるようにします。 - ホストが Discord の起動時アプリケーション検索によってブロックまたはレート制限される場合は、Developer Portal から Discord アプリケーション/クライアント ID を設定し、起動時にその REST 呼び出しをスキップできるようにします。デフォルトアカウントには `channels.discord.applicationId` を使用し、複数の Discord bot を実行する場合は `channels.discord.accounts..applicationId` を使用します。 + OpenClaw がすでにバックグラウンドサービスとして実行されている場合は、OpenClaw Mac アプリから再起動するか、`openclaw gateway run` プロセスを停止して再起動します。 + 管理サービスインストールの場合は、`DISCORD_BOT_TOKEN` が存在するシェルから `openclaw gateway install` を実行するか、変数を `~/.openclaw/.env` に保存して、サービスが再起動後に env SecretRef を解決できるようにします。 + ホストが Discord の起動時アプリケーション検索でブロックまたはレート制限される場合は、起動時にその REST 呼び出しをスキップできるように、Developer Portal の Discord アプリケーション/client ID を設定します。デフォルトアカウントには `channels.discord.applicationId` を使用し、複数の Discord Bot を実行する場合は `channels.discord.accounts..applicationId` を使用します。 - - 既存の任意のチャンネル（例: Telegram）で OpenClaw エージェントとチャットし、伝えます。Discord が最初のチャンネルの場合は、代わりに CLI / 設定タブを使用してください。 + + 既存の任意のチャンネル（例: Telegram）で OpenClaw エージェントとチャットし、次のように伝えます。Discord が最初のチャンネルの場合は、代わりに CLI / 設定タブを使用してください。 - > 「設定で Discord bot トークンはすでに設定しました。User ID `` と Server ID `` を使って Discord セットアップを完了してください。」 + > 「Discord Bot トークンはすでに設定に入れました。User ID `` と Server ID `` で Discord のセットアップを完了してください。」 ファイルベースの設定を使いたい場合は、次を設定します。 @@ -152,15 +152,15 @@ openclaw gateway } ``` - デフォルトアカウント向けの env フォールバック: + デフォルトアカウントの env フォールバック: ```bash DISCORD_BOT_TOKEN=... ``` - スクリプト化されたセットアップやリモートセットアップでは、同じ JSON5 ブロックを `openclaw config patch --file ./discord.patch.json5 --dry-run` で書き込み、その後 `--dry-run` なしで再実行します。平文の `token` 値がサポートされています。SecretRef 値も、env/file/exec プロバイダー全体で `channels.discord.token` に対してサポートされています。[シークレット管理](/ja-JP/gateway/secrets)を参照してください。 + スクリプトまたはリモートセットアップでは、同じ JSON5 ブロックを `openclaw config patch --file ./discord.patch.json5 --dry-run` で書き込み、その後 `--dry-run` なしで再実行します。平文の `token` 値に対応しています。SecretRef 値も、env/file/exec provider 全体で `channels.discord.token` に対応しています。[Secrets Management](/ja-JP/gateway/secrets) を参照してください。 - 複数の Discord bot では、各 bot トークンとアプリケーション ID をそれぞれのアカウント配下に保持します。トップレベルの `channels.discord.applicationId` はアカウントに継承されるため、すべてのアカウントで同じアプリケーション ID を使う場合にのみ、そこで設定してください。 + 複数の Discord Bot では、各 Bot トークンとアプリケーション ID をそれぞれのアカウント配下に保持します。トップレベルの `channels.discord.applicationId` はアカウントに継承されるため、すべてのアカウントで同じアプリケーション ID を使う場合にのみ、そこに設定してください。 ```json5 { @@ -188,11 +188,11 @@ DISCORD_BOT_TOKEN=... - Gateway が実行されるまで待ってから、Discord で bot に DM します。bot はペアリングコードを返します。 + gateway が実行されるまで待ち、その後 Discord で Bot に DM します。Bot がペアリングコードを返します。 - - 既存のチャンネルでエージェントにペアリングコードを送信します。 + + 既存のチャンネルでペアリングコードをエージェントに送信します。 > 「この Discord ペアリングコードを承認してください: ``」 @@ -208,27 +208,27 @@ openclaw pairing approve discord ペアリングコードは 1 時間後に期限切れになります。 - これで Discord の DM でエージェントとチャットできるようになるはずです。 + これで Discord の DM 経由でエージェントとチャットできるはずです。 トークン解決はアカウントを認識します。設定のトークン値は env フォールバックより優先されます。`DISCORD_BOT_TOKEN` はデフォルトアカウントにのみ使用されます。 -有効になっている 2 つの Discord アカウントが同じ bot トークンに解決される場合、OpenClaw はそのトークンに対して Gateway モニターを 1 つだけ起動します。設定由来のトークンはデフォルトの env フォールバックより優先されます。それ以外の場合は最初に有効になったアカウントが優先され、重複アカウントは無効として報告されます。 -高度なアウトバウンド呼び出し（メッセージツール/チャンネルアクション）では、明示的な呼び出しごとの `token` がその呼び出しに使用されます。これは送信アクションと読み取り/プローブ型アクション（たとえば read/search/fetch/thread/pins/permissions）に適用されます。アカウントポリシー/再試行設定は、引き続きアクティブなランタイムスナップショットで選択されたアカウントから取得されます。 +有効な 2 つの Discord アカウントが同じ Bot トークンに解決される場合、OpenClaw はそのトークンに対して gateway monitor を 1 つだけ起動します。設定由来のトークンはデフォルトの env フォールバックより優先されます。それ以外の場合は最初の有効なアカウントが優先され、重複アカウントは無効として報告されます。 +高度なアウトバウンド呼び出し（message tool/channel actions）では、明示的な呼び出しごとの `token` がその呼び出しに使用されます。これは送信および読み取り/probe-style アクション（たとえば read/search/fetch/thread/pins/permissions）に適用されます。アカウントポリシー/retry 設定は、引き続きアクティブな runtime snapshot で選択されたアカウントから取得されます。 ## 推奨: ギルドワークスペースを設定する -DM が動作したら、Discord サーバーを完全なワークスペースとして設定できます。各チャンネルには、独自のコンテキストを持つ独自のエージェントセッションが割り当てられます。自分と bot だけのプライベートサーバーでは、これをおすすめします。 +DM が動作するようになったら、Discord サーバーを完全なワークスペースとして設定できます。各チャンネルには、それぞれのコンテキストを持つ独自のエージェントセッションが割り当てられます。自分と Bot だけのプライベートサーバーでは、この構成をおすすめします。 これにより、エージェントは DM だけでなく、サーバー上の任意のチャンネルで応答できるようになります。 - + > 「Discord Server ID `` をギルド許可リストに追加してください」 @@ -255,15 +255,15 @@ DM が動作したら、Discord サーバーを完全なワークスペースと - デフォルトでは、ギルドチャンネルで @mention された場合にのみ、エージェントは応答します。プライベートサーバーでは、おそらくすべてのメッセージに応答させたいでしょう。 + デフォルトでは、エージェントはギルドチャンネルで @mentioned された場合にのみ応答します。プライベートサーバーでは、おそらくすべてのメッセージに応答させたいはずです。 - ギルドチャンネルでは、通常のアシスタントの最終返信はデフォルトで非公開のままです。表示される Discord 出力は `message` ツールで明示的に送信する必要があるため、エージェントはデフォルトで待機し、チャンネルへの返信が有用だと判断した場合にのみ投稿できます。 + ギルドチャンネルでは、通常のアシスタントの最終返信はデフォルトで非公開のままです。表示される Discord 出力は `message` tool で明示的に送信する必要があるため、エージェントはデフォルトで待機し、チャンネル返信が有用だと判断したときだけ投稿できます。 - つまり、選択したモデルが確実にツールを呼び出せる必要があります。Discord に入力中表示が出て、ログにトークン使用量が表示されているのにメッセージが投稿されない場合は、セッションログで `didSendViaMessagingTool: false` を含むアシスタントテキストを確認してください。これは、モデルが `message(action=send)` を呼び出す代わりに、非公開の最終回答を生成したことを意味します。より強力なツール呼び出しモデルに切り替えるか、以下の設定を使って従来の自動最終返信を復元してください。 + つまり、選択したモデルが確実にツールを呼び出せる必要があります。Discord で typing が表示され、ログにトークン使用量が表示されているのに投稿メッセージがない場合は、セッションログで `didSendViaMessagingTool: false` を含むアシスタントテキストを確認してください。これは、モデルが `message(action=send)` を呼び出す代わりに、非公開の最終回答を生成したことを意味します。より強力なツール呼び出しモデルに切り替えるか、下の設定を使用して従来の自動最終返信を復元してください。 - - > 「@mentioned されなくても、このサーバーでエージェントが応答できるようにしてください」 + + > 「このサーバーで @mentioned されなくてもエージェントが応答できるようにしてください」 ギルド設定で `requireMention: false` を設定します。 @@ -293,42 +293,38 @@ DM が動作したら、Discord サーバーを完全なワークスペースと デフォルトでは、長期メモリ（MEMORY.md）は DM セッションでのみ読み込まれます。ギルドチャンネルでは MEMORY.md は自動読み込みされません。 - + > 「Discord チャンネルで質問したとき、MEMORY.md から長期コンテキストが必要な場合は memory_search または memory_get を使ってください。」 - すべてのチャンネルで共有コンテキストが必要な場合は、安定した指示を `AGENTS.md` または `USER.md` に入れます（これらはすべてのセッションに注入されます）。長期ノートは `MEMORY.md` に保持し、必要に応じてメモリツールでアクセスします。 + すべてのチャンネルで共有コンテキストが必要な場合は、安定した指示を `AGENTS.md` または `USER.md` に入れてください（これらはすべてのセッションに注入されます）。長期メモは `MEMORY.md` に保持し、必要に応じてメモリツールでアクセスします。 -これで Discord サーバー上にいくつかのチャンネルを作成して、チャットを開始できます。エージェントはチャンネル名を確認でき、各チャンネルには独立したセッションが割り当てられます。つまり、`#coding`、`#home`、`#research` など、自分のワークフローに合うものを設定できます。 +これで Discord サーバーにいくつかチャンネルを作成して、チャットを始められます。エージェントはチャンネル名を確認でき、各チャンネルには独自の分離されたセッションが割り当てられます。そのため、`#coding`、`#home`、`#research` など、ワークフローに合うものを設定できます。 ## ランタイムモデル -- Gateway は Discord 接続を所有します。 -- 返信ルーティングは決定論的です。Discord の受信返信は Discord に返されます。 -- Discord のギルド/チャンネルメタデータは、ユーザーに見える返信プレフィックスではなく、信頼できない - コンテキストとしてモデルプロンプトに追加されます。モデルがそのエンベロープをコピーして - 返した場合、OpenClaw は送信返信と以後の再生コンテキストから、コピーされたメタデータを削除します。 -- デフォルト (`session.dmScope=main`) では、ダイレクトチャットはエージェントのメインセッション (`agent:main:main`) を共有します。 -- ギルドチャンネルは分離されたセッションキーです (`agent::discord:channel:`)。 -- グループ DM はデフォルトで無視されます (`channels.discord.dm.groupEnabled=false`)。 -- ネイティブスラッシュコマンドは、`CommandTargetSessionKey` をルーティング先の会話セッションに保持したまま、分離されたコマンドセッション (`agent::discord:slash:`) で実行されます。 -- Discord へのテキストのみの cron/heartbeat 通知配信では、最終的な - アシスタントに見える回答を一度だけ使用します。メディアと構造化コンポーネントペイロードは、 - エージェントが複数の配信可能なペイロードを出力した場合、複数メッセージのままです。 +- Gateway が Discord 接続を所有します。 +- 返信ルーティングは決定的です。Discord の受信返信は Discord に返されます。 +- Discord のギルド/チャンネルメタデータは、ユーザーに見える返信プレフィックスではなく、信頼されないコンテキストとしてモデルプロンプトに追加されます。モデルがそのエンベロープをコピーして返した場合、OpenClaw は送信返信と以後の再生コンテキストから、コピーされたメタデータを取り除きます。 +- デフォルトでは（`session.dmScope=main`）、ダイレクトチャットはエージェントのメインセッション（`agent:main:main`）を共有します。 +- ギルドチャンネルは分離されたセッションキーです（`agent::discord:channel:`）。 +- グループ DM はデフォルトで無視されます（`channels.discord.dm.groupEnabled=false`）。 +- ネイティブのスラッシュコマンドは分離されたコマンドセッション（`agent::discord:slash:`）で実行されますが、ルーティング先の会話セッションへ `CommandTargetSessionKey` を引き続き持ちます。 +- Discord へのテキストのみの cron/heartbeat 通知配信は、assistant に見える最終回答を 1 回使用します。メディアおよび構造化コンポーネントのペイロードは、エージェントが複数の配信可能なペイロードを出力する場合、複数メッセージのままです。 ## フォーラムチャンネル -Discord のフォーラムチャンネルとメディアチャンネルはスレッド投稿のみを受け付けます。OpenClaw は、それらを作成する 2 つの方法をサポートしています。 +Discord のフォーラムおよびメディアチャンネルはスレッド投稿のみを受け付けます。OpenClaw はそれらを作成する 2 つの方法をサポートします。 -- フォーラムの親 (`channel:`) にメッセージを送信して、スレッドを自動作成します。スレッドタイトルには、メッセージの最初の空でない行が使われます。 -- `openclaw message thread create` を使用して、スレッドを直接作成します。フォーラムチャンネルでは `--message-id` を渡さないでください。 +- フォーラム親（`channel:`）にメッセージを送信して、スレッドを自動作成します。スレッドタイトルにはメッセージの最初の空でない行が使われます。 +- `openclaw message thread create` を使用してスレッドを直接作成します。フォーラムチャンネルでは `--message-id` を渡さないでください。 -例: フォーラムの親に送信してスレッドを作成する +例: フォーラム親に送信してスレッドを作成する ```bash openclaw message send --channel discord --target channel: \ @@ -342,34 +338,34 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -フォーラムの親は Discord コンポーネントを受け付けません。コンポーネントが必要な場合は、スレッド自体 (`channel:`) に送信してください。 +フォーラム親は Discord コンポーネントを受け付けません。コンポーネントが必要な場合は、スレッド自体（`channel:`）に送信してください。 ## インタラクティブコンポーネント -OpenClaw はエージェントメッセージ用の Discord components v2 containers をサポートしています。`components` ペイロード付きでメッセージツールを使用します。インタラクション結果は通常の受信メッセージとしてエージェントにルーティングされ、既存の Discord `replyToMode` 設定に従います。 +OpenClaw はエージェントメッセージ向けに Discord components v2 containers をサポートします。`components` ペイロードを指定してメッセージツールを使用します。インタラクション結果は通常の受信メッセージとしてエージェントにルーティングされ、既存の Discord `replyToMode` 設定に従います。 サポートされるブロック: -- `text`, `section`, `separator`, `actions`, `media-gallery`, `file` -- アクション行では、最大 5 個のボタンまたは 1 つの選択メニューを使用できます -- 選択タイプ: `string`, `user`, `role`, `mentionable`, `channel` +- `text`、`section`、`separator`、`actions`、`media-gallery`、`file` +- アクション行では最大 5 個のボタン、または単一のセレクトメニューを使用できます +- セレクトタイプ: `string`、`user`、`role`、`mentionable`、`channel` -デフォルトでは、コンポーネントは 1 回限りです。ボタン、選択、フォームを有効期限まで複数回使用できるようにするには、`components.reusable=true` を設定します。 +デフォルトでは、コンポーネントは 1 回のみ使用できます。ボタン、セレクト、フォームを期限切れになるまで複数回使用できるようにするには、`components.reusable=true` を設定します。 -ボタンをクリックできるユーザーを制限するには、そのボタンに `allowedUsers` を設定します (Discord ユーザー ID、タグ、または `*`)。設定されている場合、一致しないユーザーにはエフェメラルな拒否が返されます。 +ボタンをクリックできるユーザーを制限するには、そのボタンに `allowedUsers` を設定します（Discord ユーザー ID、タグ、または `*`）。設定されている場合、一致しないユーザーには一時的な拒否が送信されます。 -`/model` と `/models` スラッシュコマンドは、プロバイダー、モデル、互換ランタイムのドロップダウンと Submit ステップを含むインタラクティブなモデルピッカーを開きます。`/models add` は非推奨になり、チャットからモデルを登録する代わりに非推奨メッセージを返すようになりました。ピッカーの返信はエフェメラルで、呼び出したユーザーだけが使用できます。 +`/model` と `/models` のスラッシュコマンドは、プロバイダー、モデル、互換性のあるランタイムのドロップダウンと Submit ステップを備えたインタラクティブなモデルピッカーを開きます。`/models add` は非推奨になり、チャットからモデルを登録する代わりに非推奨メッセージを返すようになりました。ピッカーの返信は一時的で、呼び出したユーザーだけが使用できます。 ファイル添付: -- `file` ブロックは添付参照 (`attachment://`) を指す必要があります -- `media`/`path`/`filePath` (単一ファイル) で添付を提供します。複数ファイルには `media-gallery` を使用します +- `file` ブロックは添付参照（`attachment://`）を指す必要があります +- `media`/`path`/`filePath`（単一ファイル）で添付を指定します。複数ファイルには `media-gallery` を使用します - アップロード名を添付参照と一致させる必要がある場合は、`filename` を使用して上書きします モーダルフォーム: -- 最大 5 フィールドを含む `components.modal` を追加します -- フィールドタイプ: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` +- 最大 5 つのフィールドを持つ `components.modal` を追加します +- フィールドタイプ: `text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` - OpenClaw はトリガーボタンを自動的に追加します 例: @@ -432,12 +428,12 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai `channels.discord.dmPolicy` は DM アクセスを制御します。`channels.discord.allowFrom` は正規の DM 許可リストです。 - - `pairing` (デフォルト) + - `pairing`（デフォルト） - `allowlist` - - `open` (`channels.discord.allowFrom` に `"*"` を含める必要があります) + - `open`（`channels.discord.allowFrom` に `"*"` が含まれている必要があります） - `disabled` - DM ポリシーが open でない場合、不明なユーザーはブロックされます (または `pairing` モードではペアリングを求められます)。 + DM ポリシーが open でない場合、不明なユーザーはブロックされます（または `pairing` モードではペアリングを促されます）。 複数アカウントの優先順位: @@ -446,21 +442,21 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - 名前付きアカウントは、自身の `allowFrom` とレガシーの `dm.allowFrom` が未設定の場合、`channels.discord.allowFrom` を継承します。 - 名前付きアカウントは `channels.discord.accounts.default.allowFrom` を継承しません。 - レガシーの `channels.discord.dm.policy` と `channels.discord.dm.allowFrom` は、互換性のため引き続き読み取られます。`openclaw doctor --fix` は、アクセスを変更せずに実行できる場合、それらを `dmPolicy` と `allowFrom` に移行します。 + レガシーの `channels.discord.dm.policy` と `channels.discord.dm.allowFrom` は、互換性のために引き続き読み取られます。`openclaw doctor --fix` は、アクセスを変更せずに実行できる場合、それらを `dmPolicy` と `allowFrom` に移行します。 配信用の DM ターゲット形式: - `user:` - `<@id>` メンション - 通常、チャンネルのデフォルトが有効な場合、ベア数値 ID はチャンネル ID として解決されますが、アカウントの有効な DM `allowFrom` に listed されている ID は、互換性のためユーザー DM ターゲットとして扱われます。 + ベアの数値 ID は通常、チャンネルのデフォルトが有効な場合にチャンネル ID として解決されますが、アカウントの有効な DM `allowFrom` に列挙された ID は、互換性のためにユーザー DM ターゲットとして扱われます。 Discord DM では、`channels.discord.allowFrom` 内で動的な `accessGroup:` エントリを使用できます。 - アクセスグループ名はメッセージチャンネル間で共有されます。メンバーが各チャンネルの通常の `allowFrom` 構文で表される静的グループには `type: "message.senders"` を使用し、Discord チャンネルの現在の `ViewChannel` 対象者がメンバーシップを動的に定義する必要がある場合は `type: "discord.channelAudience"` を使用します。共有アクセスグループの動作はここに記載されています: [アクセスグループ](/ja-JP/channels/access-groups)。 + アクセスグループ名はメッセージチャンネル間で共有されます。メンバーが各チャンネルの通常の `allowFrom` 構文で表される静的グループには `type: "message.senders"` を使用し、Discord チャンネルの現在の `ViewChannel` オーディエンスでメンバーシップを動的に定義する場合は `type: "discord.channelAudience"` を使用します。共有アクセスグループの動作はこちらで説明されています: [アクセスグループ](/ja-JP/channels/access-groups)。 ```json5 { @@ -483,9 +479,9 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` - Discord テキストチャンネルには個別のメンバーリストがありません。`type: "discord.channelAudience"` はメンバーシップを次のようにモデル化します。DM 送信者は設定済みギルドのメンバーであり、ロールとチャンネルの上書きが適用された後、設定済みチャンネルに対して現在有効な `ViewChannel` 権限を持っています。 + Discord テキストチャンネルには個別のメンバーリストがありません。`type: "discord.channelAudience"` はメンバーシップを次のようにモデル化します。DM 送信者が設定済みギルドのメンバーであり、ロールとチャンネル上書きが適用された後、設定済みチャンネルに対する有効な `ViewChannel` 権限を現在持っていること。 - 例: `#maintainers` を見られるすべてのユーザーがボットに DM できるようにし、それ以外のユーザーには DM を閉じたままにする。 + 例: `#maintainers` を見られる全員がボットに DM できるようにし、それ以外の全員には DM を閉じたままにします。 ```json5 { @@ -526,9 +522,9 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` - ルックアップは失敗時に閉じます。Discord が `Missing Access` を返す、メンバールックアップが失敗する、またはチャンネルが別のギルドに属している場合、DM 送信者は権限なしとして扱われます。 + ルックアップは失敗時に閉じます。Discord が `Missing Access` を返す、メンバールックアップに失敗する、またはチャンネルが別のギルドに属している場合、DM 送信者は未認可として扱われます。 - チャンネル対象者アクセスグループを使用する場合は、ボットに対して Discord Developer Portal の **Server Members Intent** を有効にします。DM にはギルドメンバー状態が含まれないため、OpenClaw は認可時に Discord REST 経由でメンバーを解決します。 + チャンネルオーディエンスアクセスグループを使用するときは、ボットに対して Discord Developer Portal の **Server Members Intent** を有効にします。DM にはギルドメンバー状態が含まれないため、OpenClaw は認可時に Discord REST を通じてメンバーを解決します。 @@ -539,15 +535,15 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - `allowlist` - `disabled` - `channels.discord` が存在する場合の安全なベースラインは `allowlist` です。 + `channels.discord` が存在する場合のセキュアなベースラインは `allowlist` です。 `allowlist` の動作: - - ギルドは `channels.discord.guilds` と一致する必要があります (`id` 推奨、slug も受け付けます) - - 任意の送信者許可リスト: `users` (安定した ID を推奨) と `roles` (ロール ID のみ)。いずれかが設定されている場合、送信者は `users` または `roles` のどちらかに一致すると許可されます + - ギルドは `channels.discord.guilds` と一致する必要があります（`id` 推奨、slug も可） + - 任意の送信者許可リスト: `users`（安定 ID 推奨）と `roles`（ロール ID のみ）。どちらかが設定されている場合、送信者は `users` または `roles` に一致すると許可されます - 直接の名前/タグ一致はデフォルトで無効です。緊急互換モードとしてのみ `channels.discord.dangerouslyAllowNameMatching: true` を有効にしてください - - `users` では名前/タグがサポートされていますが、ID の方が安全です。名前/タグエントリが使用されている場合、`openclaw security audit` が警告します - - ギルドに `channels` が設定されている場合、listed されていないチャンネルは拒否されます + - `users` では名前/タグがサポートされますが、ID の方が安全です。名前/タグエントリが使われている場合、`openclaw security audit` は警告します + - ギルドに `channels` が設定されている場合、リストにないチャンネルは拒否されます - ギルドに `channels` ブロックがない場合、その許可リスト済みギルド内のすべてのチャンネルが許可されます 例: @@ -574,35 +570,35 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` - `DISCORD_BOT_TOKEN` だけを設定し、`channels.discord` ブロックを作成しない場合、`channels.defaults.groupPolicy` が `open` であっても、ランタイムフォールバックは `groupPolicy="allowlist"` になります (ログに警告が出ます)。 + `DISCORD_BOT_TOKEN` のみを設定し、`channels.discord` ブロックを作成しない場合、ランタイムのフォールバックは `groupPolicy="allowlist"` です（ログに警告が出ます）。これは `channels.defaults.groupPolicy` が `open` であっても同じです。 - ギルドメッセージはデフォルトでメンションゲートされます。 + ギルドメッセージはデフォルトでメンションによって制御されます。 メンション検出には次が含まれます。 - 明示的なボットメンション - - 設定済みメンションパターン (`agents.list[].groupChat.mentionPatterns`、フォールバックは `messages.groupChat.mentionPatterns`) - - サポートされている場合の暗黙的なボットへの返信動作 + - 設定済みメンションパターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは `messages.groupChat.mentionPatterns`） + - サポートされるケースでの暗黙的なボットへの返信動作 - 送信 Discord メッセージを書くときは、正規のメンション構文を使用してください。ユーザーには `<@USER_ID>`、チャンネルには `<#CHANNEL_ID>`、ロールには `<@&ROLE_ID>` です。レガシーの `<@!USER_ID>` ニックネームメンション形式は使用しないでください。 + Discord の送信メッセージを書くときは、正規のメンション構文を使用します。ユーザーには `<@USER_ID>`、チャンネルには `<#CHANNEL_ID>`、ロールには `<@&ROLE_ID>` です。レガシーの `<@!USER_ID>` ニックネームメンション形式は使用しないでください。 - `requireMention` はギルド/チャンネルごとに設定されます (`channels.discord.guilds...`)。 - `ignoreOtherMentions` は、ボットではなく別のユーザー/ロールにメンションしているメッセージを任意で破棄します (@everyone/@here は除外)。 + `requireMention` はギルド/チャンネルごとに設定されます（`channels.discord.guilds...`）。 + `ignoreOtherMentions` は、ボット以外の別のユーザー/ロールにメンションしているメッセージを任意で破棄します（@everyone/@here は除きます）。 グループ DM: - - デフォルト: 無視 (`dm.groupEnabled=false`) - - `dm.groupChannels` (チャンネル ID または slug) による任意の許可リスト + - デフォルト: 無視（`dm.groupEnabled=false`） + - 任意の許可リストは `dm.groupChannels`（チャンネル ID または slug）で設定します ### ロールベースのエージェントルーティング -`bindings[].match.roles` を使用して、Discord ギルドメンバーをロール ID によって別のエージェントへルーティングします。ロールベースのバインディングはロール ID のみを受け付け、ピアまたは親ピアのバインディングの後、ギルドのみのバインディングの前に評価されます。バインディングが他の match フィールドも設定している場合 (たとえば `peer` + `guildId` + `roles`)、設定されたすべてのフィールドが一致する必要があります。 +ロール ID によって Discord ギルドメンバーを別々のエージェントにルーティングするには、`bindings[].match.roles` を使用します。ロールベースのバインディングはロール ID のみを受け付け、ピアまたは親ピアのバインディングの後、ギルドのみのバインディングの前に評価されます。バインディングが他の一致フィールド（例: `peer` + `guildId` + `roles`）も設定している場合、設定されたすべてのフィールドが一致する必要があります。 ```json5 { @@ -626,15 +622,15 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` -## ネイティブコマンドとコマンド認可 +## ネイティブコマンドとコマンド認証 - `commands.native` のデフォルトは `"auto"` で、Discord では有効です。 -- チャネル単位の上書き: `channels.discord.commands.native`。 -- `commands.native=false` にすると、起動時の Discord スラッシュコマンドの登録とクリーンアップをスキップします。以前に登録されたコマンドは、Discord アプリから削除するまで Discord に表示され続ける場合があります。 -- ネイティブコマンドの認可には、通常のメッセージ処理と同じ Discord の許可リスト/ポリシーが使われます。 -- 認可されていないユーザーにも、コマンドが Discord UI に表示される場合があります。実行時には引き続き OpenClaw の認可が適用され、「not authorized」が返されます。 +- チャンネルごとの上書き: `channels.discord.commands.native`。 +- `commands.native=false` は、起動時の Discord スラッシュコマンド登録とクリーンアップをスキップします。以前に登録されたコマンドは、Discord アプリから削除するまで Discord に表示されたままになる場合があります。 +- ネイティブコマンド認証は、通常のメッセージ処理と同じ Discord の許可リスト/ポリシーを使用します。 +- 認可されていないユーザーにも Discord UI でコマンドが表示される場合がありますが、実行時には OpenClaw 認証が引き続き適用され、「not authorized」が返されます。 -コマンドカタログと動作については、[スラッシュコマンド](/ja-JP/tools/slash-commands) を参照してください。 +コマンドカタログと動作については、[スラッシュコマンド](/ja-JP/tools/slash-commands)を参照してください。 デフォルトのスラッシュコマンド設定: @@ -657,17 +653,17 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - `batched` 注: `off` は暗黙的な返信スレッド化を無効にします。明示的な `[[reply_to_*]]` タグは引き続き尊重されます。 - `first` は、そのターンの最初の送信 Discord メッセージに、暗黙的なネイティブ返信参照を常に付与します。 - `batched` は、受信ターンが複数メッセージのデバウンス済みバッチだった場合にのみ、Discord の暗黙的なネイティブ返信参照を付与します。これは、すべての単一メッセージターンではなく、主に曖昧な連続チャットに対してネイティブ返信を使いたい場合に便利です。 + `first` は、そのターンの最初の送信 Discord メッセージに暗黙的なネイティブ返信参照を常に付加します。 + `batched` は、入力ターンが複数メッセージのデバウンス済みバッチだった場合にのみ、Discord の暗黙的なネイティブ返信参照を付加します。これは、すべての単一メッセージターンではなく、主に曖昧なバースト的チャットでネイティブ返信を使いたい場合に便利です。 - メッセージ ID はコンテキスト/履歴に表示されるため、エージェントは特定のメッセージを対象にできます。 + メッセージ ID は context/history に提示されるため、エージェントは特定のメッセージを対象にできます。 - OpenClaw は一時メッセージを送信し、テキストが届くたびに編集することで、下書き返信をストリーミングできます。`channels.discord.streaming` は `off` (デフォルト) | `partial` | `block` | `progress` を取ります。`progress` は編集可能なステータス下書きを 1 つ保持し、最終配信までツール進行状況で更新します。`streamMode` はレガシーエイリアスで、自動移行されます。 + OpenClaw は、一時メッセージを送信し、テキストが到着するたびに編集することで下書き返信をストリーミングできます。`channels.discord.streaming` は `off` (デフォルト) | `partial` | `block` | `progress` を取ります。`progress` は編集可能なステータス下書きを 1 つ保持し、最終配信までツール進捗で更新します。`streamMode` はレガシーエイリアスで、自動移行されます。 - 複数の bot や Gateway がアカウントを共有している場合、Discord のプレビュー編集はすぐにレート制限に達するため、デフォルトは `off` のままです。 + 複数のボットや Gateway がアカウントを共有している場合、Discord のプレビュー編集はすぐにレート制限に達するため、デフォルトは `off` のままです。 ```json5 { @@ -684,17 +680,36 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` - - `partial` はトークンが届くたびに単一のプレビューメッセージを編集します。 - - `block` は下書きサイズのチャンクを送信します (サイズと区切り位置の調整には `draftChunk` を使い、`textChunkLimit` にクランプされます)。 + - `partial` は、トークンが到着するたびに単一のプレビューメッセージを編集します。 + - `block` は下書きサイズのチャンクを送信します (サイズと区切り位置を調整するには `draftChunk` を使用し、`textChunkLimit` にクランプされます)。 - メディア、エラー、明示的な返信の最終メッセージは、保留中のプレビュー編集をキャンセルします。 - - `streaming.preview.toolProgress` (デフォルトは `true`) は、ツール/進行状況の更新がプレビューメッセージを再利用するかどうかを制御します。 + - `streaming.preview.toolProgress` (デフォルト `true`) は、ツール/進捗の更新でプレビューメッセージを再利用するかどうかを制御します。 + - `streaming.preview.commandText` / `streaming.progress.commandText` は、コンパクトな進捗行でのコマンド/実行の詳細を制御します: `raw` (デフォルト) または `status` (ツールラベルのみ)。 - プレビューストリーミングはテキストのみです。メディア返信は通常配信にフォールバックします。`block` ストリーミングが明示的に有効な場合、OpenClaw は二重ストリーミングを避けるためにプレビューストリームをスキップします。 + コンパクトな進捗行を維持しつつ、生のコマンド/実行テキストを非表示にします。 + + ```json + { + "channels": { + "discord": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } + } + ``` + + プレビューストリーミングはテキストのみです。メディア返信は通常の配信にフォールバックします。`block` ストリーミングが明示的に有効な場合、OpenClaw は二重ストリーミングを避けるためにプレビューストリームをスキップします。 - ギルド履歴コンテキスト: + Guild 履歴コンテキスト: - `channels.discord.historyLimit` のデフォルトは `20` - フォールバック: `messages.groupChat.historyLimit` @@ -705,28 +720,28 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - スレッドの動作: + スレッド動作: - - Discord スレッドはチャネルセッションとしてルーティングされ、上書きがない限り親チャネル設定を継承します。 - - スレッドセッションは、親チャネルのセッションレベルの `/model` 選択をモデル専用フォールバックとして継承します。スレッドローカルの `/model` 選択は引き続き優先され、トランスクリプト継承が有効でない限り親トランスクリプト履歴はコピーされません。 - - `channels.discord.thread.inheritParent` (デフォルトは `false`) は、新しい自動スレッドが親トランスクリプトをシードとして使うようにします。アカウント単位の上書きは `channels.discord.accounts..thread.inheritParent` 配下にあります。 - - メッセージツールのリアクションは `user:` の DM ターゲットを解決できます。 - - `guilds..channels..requireMention: false` は、返信段階の有効化フォールバック中も保持されます。 + - Discord スレッドはチャンネルセッションとしてルーティングされ、上書きされない限り親チャンネル設定を継承します。 + - スレッドセッションは、モデルのみのフォールバックとして、親チャンネルのセッションレベルの `/model` 選択を継承します。スレッドローカルの `/model` 選択が引き続き優先され、トランスクリプト継承が有効でない限り親トランスクリプト履歴はコピーされません。 + - `channels.discord.thread.inheritParent` (デフォルト `false`) は、新しい自動スレッドで親トランスクリプトからのシードを有効にします。アカウントごとの上書きは `channels.discord.accounts..thread.inheritParent` 配下にあります。 + - メッセージツールのリアクションは `user:` DM ターゲットを解決できます。 + - `guilds..channels..requireMention: false` は、返信段階のアクティベーションフォールバック中も保持されます。 - チャネルのトピックは**信頼されない**コンテキストとして注入されます。許可リストはエージェントを起動できるユーザーを制限しますが、補助コンテキスト全体の墨消し境界ではありません。 + チャンネルトピックは**信頼されない**コンテキストとして挿入されます。許可リストはエージェントを起動できる人物を制限しますが、補足コンテキスト全体の完全な秘匿境界ではありません。 - Discord はスレッドをセッションターゲットにバインドでき、そのスレッド内の後続メッセージを同じセッション (サブエージェントセッションを含む) にルーティングし続けられます。 + Discord はスレッドをセッションターゲットにバインドできるため、そのスレッド内の後続メッセージは同じセッション (サブエージェントセッションを含む) にルーティングされ続けます。 コマンド: - `/focus ` 現在/新規スレッドをサブエージェント/セッションターゲットにバインド - `/unfocus` 現在のスレッドバインドを削除 - `/agents` アクティブな実行とバインド状態を表示 - - `/session idle ` フォーカス中のバインドに対する非アクティブ時の自動アンフォーカスを確認/更新 - - `/session max-age ` フォーカス中のバインドに対するハード最大期間を確認/更新 + - `/session idle ` フォーカスされたバインドの非アクティブ時自動アンフォーカスを確認/更新 + - `/session max-age ` フォーカスされたバインドのハード最大寿命を確認/更新 設定: @@ -757,21 +772,21 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - `session.threadBindings.*` はグローバルデフォルトを設定します。 - `channels.discord.threadBindings.*` は Discord の動作を上書きします。 - - `spawnSessions` は、`sessions_spawn({ thread: true })` と ACP スレッドスポーンに対するスレッドの自動作成/バインドを制御します。デフォルト: `true`。 - - `defaultSpawnContext` は、スレッドバインドされたスポーンのネイティブサブエージェントコンテキストを制御します。デフォルト: `"fork"`。 - - 非推奨の `spawnSubagentSessions`/`spawnAcpSessions` キーは、`openclaw doctor --fix` により移行されます。 + - `spawnSessions` は、`sessions_spawn({ thread: true })` と ACP スレッド生成のためのスレッド自動作成/バインドを制御します。デフォルト: `true`。 + - `defaultSpawnContext` は、スレッドバインド生成のネイティブサブエージェントコンテキストを制御します。デフォルト: `"fork"`。 + - 非推奨の `spawnSubagentSessions`/`spawnAcpSessions` キーは `openclaw doctor --fix` によって移行されます。 - アカウントでスレッドバインドが無効な場合、`/focus` と関連するスレッドバインド操作は利用できません。 - [サブエージェント](/ja-JP/tools/subagents)、[ACP エージェント](/ja-JP/tools/acp-agents)、および [設定リファレンス](/ja-JP/gateway/configuration-reference) を参照してください。 + [サブエージェント](/ja-JP/tools/subagents)、[ACP エージェント](/ja-JP/tools/acp-agents)、[設定リファレンス](/ja-JP/gateway/configuration-reference)を参照してください。 - 安定した「常時オン」の ACP ワークスペースでは、Discord 会話を対象にするトップレベルの型付き ACP バインドを設定します。 + 安定した「常時オン」の ACP ワークスペースでは、Discord 会話を対象とするトップレベルの型付き ACP バインドを設定します。 設定パス: - - `type: "acp"` と `match.channel: "discord"` を持つ `bindings[]` + - `bindings[]` に `type: "acp"` と `match.channel: "discord"` を指定 例: @@ -823,16 +838,16 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai 注: - - `/acp spawn codex --bind here` は現在のチャネルまたはスレッドをその場でバインドし、今後のメッセージを同じ ACP セッションに維持します。スレッドメッセージは親チャネルのバインドを継承します。 - - バインドされたチャネルまたはスレッドでは、`/new` と `/reset` は同じ ACP セッションをその場でリセットします。一時的なスレッドバインドは、有効な間はターゲット解決を上書きできます。 - - `spawnSessions` は、`--thread auto|here` による子スレッドの作成/バインドを制御します。 + - `/acp spawn codex --bind here` は現在のチャンネルまたはスレッドをその場でバインドし、今後のメッセージを同じ ACP セッションに保持します。スレッドメッセージは親チャンネルのバインドを継承します。 + - バインドされたチャンネルまたはスレッドでは、`/new` と `/reset` が同じ ACP セッションをその場でリセットします。一時的なスレッドバインドは、アクティブな間はターゲット解決を上書きできます。 + - `spawnSessions` は `--thread auto|here` による子スレッドの作成/バインドを制御します。 - バインド動作の詳細については、[ACP エージェント](/ja-JP/tools/acp-agents) を参照してください。 + バインド動作の詳細については、[ACP エージェント](/ja-JP/tools/acp-agents)を参照してください。 - ギルド単位のリアクション通知モード: + Guild ごとのリアクション通知モード: - `off` - `own` (デフォルト) @@ -844,24 +859,24 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - `ackReaction` は、OpenClaw が受信メッセージを処理している間に確認絵文字を送信します。 + `ackReaction` は、OpenClaw が入力メッセージを処理している間に確認絵文字を送信します。 解決順序: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - エージェント ID 絵文字のフォールバック (`agents.list[].identity.emoji`、なければ "👀") + - エージェント ID 絵文字フォールバック (`agents.list[].identity.emoji`、なければ "👀") 注: - - Discord は Unicode 絵文字またはカスタム絵文字名を受け付けます。 - - チャネルまたはアカウントのリアクションを無効にするには `""` を使います。 + - Discord は Unicode 絵文字またはカスタム絵文字名を受け入れます。 + - チャンネルまたはアカウントのリアクションを無効にするには `""` を使用します。 - チャネル起点の設定書き込みはデフォルトで有効です。 + チャンネルから開始される設定書き込みはデフォルトで有効です。 これは `/config set|unset` フローに影響します (コマンド機能が有効な場合)。 @@ -880,7 +895,7 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - `channels.discord.proxy` を使って、Discord Gateway WebSocket トラフィックと起動時の REST 参照 (アプリケーション ID + 許可リスト解決) を HTTP(S) プロキシ経由でルーティングします。 + `channels.discord.proxy` を使用して、Discord Gateway WebSocket トラフィックと起動時の REST 参照 (アプリケーション ID + 許可リスト解決) を HTTP(S) プロキシ経由でルーティングします。 ```json5 { @@ -892,7 +907,7 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` - アカウント単位の上書き: + アカウントごとの上書き: ```json5 { @@ -911,7 +926,7 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - プロキシされたメッセージをシステムメンバー ID にマッピングするには、PluralKit 解決を有効にします。 + PluralKit 解決を有効にして、プロキシされたメッセージをシステムメンバー ID にマップします。 ```json5 { @@ -929,14 +944,14 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai 注: - 許可リストでは `pk:` を使用できます - - メンバー表示名は、`channels.discord.dangerouslyAllowNameMatching: true` の場合にのみ名前/slug で照合されます - - 参照には元のメッセージ ID が使われ、時間枠で制約されます - - 参照に失敗した場合、プロキシされたメッセージは bot メッセージとして扱われ、`allowBots=true` でない限り破棄されます + - `channels.discord.dangerouslyAllowNameMatching: true` の場合にのみ、メンバー表示名は name/slug で照合されます + - 参照には元のメッセージ ID が使用され、時間ウィンドウで制約されます + - 参照に失敗した場合、`allowBots=true` でない限り、プロキシされたメッセージはボットメッセージとして扱われ破棄されます - 既知の Discord ユーザーに対してエージェントが決定的な送信メンションを必要とする場合は、`mentionAliases` を使います。キーは先頭の `@` を除いたハンドルで、値は Discord ユーザー ID です。不明なハンドル、`@everyone`、`@here`、および Markdown コードスパン内のメンションは変更されません。 + エージェントが既知の Discord ユーザーに対して決定論的な送信メンションを必要とする場合は、`mentionAliases` を使用します。キーは先頭の `@` を含まないハンドルで、値は Discord ユーザー ID です。不明なハンドル、`@everyone`、`@here`、Markdown コードスパン内のメンションは変更されません。 ```json5 { @@ -974,7 +989,7 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` - アクティビティの例 (カスタムステータスがデフォルトのアクティビティタイプです): + アクティビティ例 (カスタムステータスがデフォルトのアクティビティタイプです): ```json5 { @@ -987,7 +1002,7 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` - ストリーミングの例: + ストリーミング例: ```json5 { @@ -1004,13 +1019,13 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai アクティビティタイプの対応表: - 0: プレイ中 - - 1: ストリーミング中 (`activityUrl` が必要) + - 1: ストリーミング (`activityUrl` が必要) - 2: リスニング中 - 3: 視聴中 - 4: カスタム (アクティビティテキストをステータス状態として使用します。絵文字は任意です) - - 5: 競技中 + - 5: 対戦中 - 自動プレゼンスの例 (ランタイムヘルスシグナル): + 自動プレゼンス例 (ランタイム健全性シグナル): ```json5 { @@ -1027,7 +1042,7 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai } ``` - 自動プレゼンスはランタイムの可用性を Discord ステータスにマッピングします: healthy => online、degraded または unknown => idle、exhausted または unavailable => dnd。任意のテキスト上書き: + 自動プレゼンスは、ランタイムの可用性を Discord ステータスに対応付けます: healthy => online、degraded または unknown => idle、exhausted または unavailable => dnd。任意のテキスト上書き: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -1035,33 +1050,27 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai - - Discord は DM でボタンベースの承認処理をサポートし、任意で元のチャネルに承認プロンプトを投稿できます。 + + Discord は DM でのボタンベースの承認処理をサポートし、任意で元のチャンネルに承認プロンプトを投稿できます。 設定パス: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers`（任意。可能な場合は `commands.ownerAllowFrom` にフォールバック） - - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） - - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` + - `channels.discord.execApprovals.approvers` (任意。可能な場合は `commands.ownerAllowFrom` にフォールバック) + - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`、デフォルト: `dm`) + - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord は、`enabled` が未設定または `"auto"` で、`execApprovals.approvers` または `commands.ownerAllowFrom` から少なくとも 1 人の承認者を解決できる場合、ネイティブ exec 承認を自動的に有効化します。Discord は、チャンネルの `allowFrom`、従来の `dm.allowFrom`、またはダイレクトメッセージの `defaultTo` から exec 承認者を推論しません。Discord をネイティブ承認クライアントとして明示的に無効化するには、`enabled: false` を設定します。 + Discord は、`enabled` が未設定または `"auto"` で、`execApprovals.approvers` または `commands.ownerAllowFrom` から少なくとも 1 人の承認者を解決できる場合に、ネイティブ exec 承認を自動的に有効化します。Discord は、チャンネルの `allowFrom`、レガシーの `dm.allowFrom`、またはダイレクトメッセージの `defaultTo` から exec 承認者を推論しません。Discord をネイティブ承認クライアントとして明示的に無効化するには、`enabled: false` を設定します。 - `/diagnostics` や `/export-trajectory` など、機密性の高い所有者専用グループコマンドでは、OpenClaw は承認プロンプトと最終結果を非公開で送信します。呼び出した所有者に Discord 所有者ルートがある場合は、まず Discord DM を試します。利用できない場合は、Telegram など、`commands.ownerAllowFrom` から利用可能な最初の所有者ルートにフォールバックします。 + `/diagnostics` や `/export-trajectory` など、機密性の高いオーナー専用グループコマンドでは、OpenClaw は承認プロンプトと最終結果を非公開で送信します。呼び出したオーナーに Discord オーナールートがある場合、まず Discord DM を試します。利用できない場合は、Telegram など、`commands.ownerAllowFrom` から最初に利用可能なオーナールートにフォールバックします。 - `target` が `channel` または `both` の場合、承認プロンプトはチャンネルに表示されます。ボタンを使用できるのは解決済みの承認者のみです。他のユーザーには一時的な拒否が返されます。承認プロンプトにはコマンドテキストが含まれるため、チャンネル配信は信頼済みチャンネルでのみ有効にしてください。チャンネル ID をセッションキーから導出できない場合、OpenClaw は DM 配信にフォールバックします。 + `target` が `channel` または `both` の場合、承認プロンプトはチャンネルに表示されます。解決済みの承認者だけがボタンを使用できます。他のユーザーには一時的な拒否が返されます。承認プロンプトにはコマンドテキストが含まれるため、信頼済みチャンネルでのみチャンネル配信を有効化してください。セッションキーからチャンネル ID を導出できない場合、OpenClaw は DM 配信にフォールバックします。 - Discord は、他のチャットチャンネルで使われる共有承認ボタンもレンダリングします。ネイティブ Discord アダプターは主に、承認者 DM ルーティングとチャンネルファンアウトを追加します。 - これらのボタンが存在する場合、それらが主要な承認 UX です。OpenClaw は、 - ツール結果がチャット承認を利用できない、または手動承認が唯一の経路であると示す場合にのみ、 - 手動の `/approve` コマンドを含める必要があります。 - Discord ネイティブ承認ランタイムがアクティブでない場合、OpenClaw は - ローカルで決定的な `/approve ` プロンプトを表示したままにします。 - ランタイムがアクティブでも、どのターゲットにもネイティブカードを配信できない場合、 - OpenClaw は保留中の承認から正確な `/approve` - コマンドを含む、同じチャット内のフォールバック通知を送信します。 + Discord は、他のチャットチャンネルで使われる共有承認ボタンもレンダリングします。ネイティブ Discord アダプターは主に、承認者への DM ルーティングとチャンネルへのファンアウトを追加します。 + これらのボタンが存在する場合、それらが主要な承認 UX です。OpenClaw は、ツール結果がチャット承認を利用できない、または手動承認が唯一の経路だと示す場合にのみ、手動の `/approve` コマンドを含めるべきです。 + Discord ネイティブ承認ランタイムがアクティブでない場合、OpenClaw はローカルの決定的な `/approve ` プロンプトを表示したままにします。ランタイムがアクティブでも、ネイティブカードをどのターゲットにも配信できない場合、OpenClaw は保留中の承認に由来する正確な `/approve` コマンドを含む同一チャットのフォールバック通知を送信します。 - Gateway 認証と承認解決は、共有 Gateway クライアント契約に従います（`plugin:` ID は `plugin.approval.resolve` を通じて解決され、その他の ID は `exec.approval.resolve` を通じて解決されます）。承認はデフォルトで 30 分後に期限切れになります。 + Gateway 認証と承認解決は、共有 Gateway クライアント契約に従います (`plugin:` ID は `plugin.approval.resolve` 経由で解決され、その他の ID は `exec.approval.resolve` 経由で解決されます)。承認はデフォルトで 30 分後に期限切れになります。 [Exec 承認](/ja-JP/tools/exec-approvals)を参照してください。 @@ -1070,33 +1079,33 @@ OpenClaw はエージェントメッセージ用の Discord components v2 contai ## ツールとアクションゲート -Discord メッセージアクションには、メッセージング、チャンネル管理、モデレーション、プレゼンス、メタデータの各アクションが含まれます。 +Discord メッセージアクションには、メッセージング、チャンネル管理、モデレーション、プレゼンス、メタデータのアクションが含まれます。 -主要な例: +主な例: -- メッセージング: `sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` -- リアクション: `react`、`reactions`、`emojiList` -- モデレーション: `timeout`、`kick`、`ban` +- メッセージング: `sendMessage`, `readMessages`, `editMessage`, `deleteMessage`, `threadReply` +- リアクション: `react`, `reactions`, `emojiList` +- モデレーション: `timeout`, `kick`, `ban` - プレゼンス: `setPresence` -`event-create` アクションは、スケジュール済みイベントのカバー画像を設定するための任意の `image` パラメーター（URL またはローカルファイルパス）を受け付けます。 +`event-create` アクションは、スケジュール済みイベントのカバー画像を設定するための任意の `image` パラメーター (URL またはローカルファイルパス) を受け取ります。 -アクションゲートは `channels.discord.actions.*` の下にあります。 +アクションゲートは `channels.discord.actions.*` 配下にあります。 デフォルトのゲート動作: -| アクショングループ | デフォルト | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 有効 | -| roles | 無効 | -| moderation | 無効 | -| presence | 無効 | +| アクショングループ | デフォルト | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 有効 | +| roles | 無効 | +| moderation | 無効 | +| presence | 無効 | ## Components v2 UI -OpenClaw は、exec 承認とクロスコンテキストマーカーに Discord components v2 を使用します。Discord メッセージアクションは、カスタム UI 用の `components` も受け付けられます（高度な用途。discord ツール経由でコンポーネントペイロードを構築する必要があります）。従来の `embeds` も引き続き利用できますが、推奨されません。 +OpenClaw は、exec 承認とクロスコンテキストマーカーに Discord components v2 を使用します。Discord メッセージアクションは、カスタム UI 用に `components` も受け取れます (高度。discord ツールでコンポーネントペイロードを構築する必要があります)。一方、レガシーの `embeds` も引き続き利用できますが、推奨されません。 -- `channels.discord.ui.components.accentColor` は、Discord コンポーネントコンテナーで使用されるアクセントカラー（16 進数）を設定します。 +- `channels.discord.ui.components.accentColor` は、Discord コンポーネントコンテナで使用されるアクセントカラー (hex) を設定します。 - アカウントごとに `channels.discord.accounts..ui.components.accentColor` で設定します。 - components v2 が存在する場合、`embeds` は無視されます。 @@ -1118,17 +1127,17 @@ OpenClaw は、exec 承認とクロスコンテキストマーカーに Discord ## 音声 -Discord には、リアルタイムの**音声チャンネル**（継続的な会話）と**音声メッセージ添付ファイル**（波形プレビュー形式）という 2 つの異なる音声サーフェスがあります。Gateway は両方をサポートします。 +Discord には 2 つの異なる音声サーフェスがあります。リアルタイムの**音声チャンネル** (継続的な会話) と、**音声メッセージ添付ファイル** (波形プレビュー形式) です。Gateway は両方をサポートします。 ### 音声チャンネル セットアップチェックリスト: -1. Discord Developer Portal で Message Content Intent を有効にします。 -2. ロール/ユーザー許可リストを使用する場合は、Server Members Intent を有効にします。 +1. Discord Developer Portal で Message Content Intent を有効化します。 +2. ロール/ユーザーの許可リストを使用する場合は、Server Members Intent を有効化します。 3. `bot` と `applications.commands` スコープでボットを招待します。 4. 対象の音声チャンネルで Connect、Speak、Send Messages、Read Message History を付与します。 -5. ネイティブコマンド（`commands.native` または `channels.discord.commands.native`）を有効にします。 +5. ネイティブコマンド (`commands.native` または `channels.discord.commands.native`) を有効化します。 6. `channels.discord.voice` を設定します。 セッションを制御するには `/vc join|leave|status` を使用します。このコマンドはアカウントのデフォルトエージェントを使用し、他の Discord コマンドと同じ許可リストおよびグループポリシールールに従います。 @@ -1168,38 +1177,38 @@ Discord には、リアルタイムの**音声チャンネル**（継続的な } ``` -注: +注記: -- `voice.tts` は、音声再生にのみ `messages.tts` を上書きします。 -- `voice.model` は、Discord 音声チャンネル応答に使用される LLM のみを上書きします。未設定のままにすると、ルーティングされたエージェントモデルを継承します。 +- `voice.tts` は、音声再生に限って `messages.tts` を上書きします。 +- `voice.model` は、Discord 音声チャンネルの応答に使用される LLM に限って上書きします。ルーティングされたエージェントモデルを継承するには未設定のままにします。 - STT は `tools.media.audio` を使用します。`voice.model` は文字起こしに影響しません。 - チャンネルごとの Discord `systemPrompt` 上書きは、その音声チャンネルの音声トランスクリプトターンに適用されます。 -- 音声トランスクリプトターンは、Discord `allowFrom`（または `dm.allowFrom`）から所有者ステータスを導出します。所有者以外の話者は、所有者専用ツール（例: `gateway` と `cron`）にアクセスできません。 -- Discord 音声はテキスト専用設定ではオプトインです。`/vc` コマンド、音声ランタイム、`GuildVoiceStates` gateway インテントを有効にするには、`channels.discord.voice.enabled=true` を設定します（または既存の `channels.discord.voice` ブロックを保持します）。 -- `channels.discord.intents.voiceStates` で、音声状態インテントの購読を明示的に上書きできます。有効な音声有効化状態にインテントを従わせるには、未設定のままにします。 +- 音声トランスクリプトターンは、Discord `allowFrom` (または `dm.allowFrom`) からオーナーステータスを導出します。非オーナーの発話者は、オーナー専用ツール (例: `gateway` と `cron`) にアクセスできません。 +- Discord 音声はテキスト専用設定ではオプトインです。`/vc` コマンド、音声ランタイム、`GuildVoiceStates` Gateway インテントを有効化するには、`channels.discord.voice.enabled=true` を設定します (または既存の `channels.discord.voice` ブロックを維持します)。 +- `channels.discord.intents.voiceStates` は、音声状態インテント購読を明示的に上書きできます。有効な音声有効化状態にインテントを追従させるには、未設定のままにします。 - `voice.daveEncryption` と `voice.decryptionFailureTolerance` は、`@discordjs/voice` の参加オプションにそのまま渡されます。 -- `@discordjs/voice` のデフォルトは、未設定の場合 `daveEncryption=true` と `decryptionFailureTolerance=24` です。 -- `voice.connectTimeoutMs` は、`/vc join` と自動参加試行に対する初期 `@discordjs/voice` Ready 待機を制御します。デフォルト: `30000`。 -- `voice.reconnectGraceMs` は、切断された音声セッションが再接続を開始するまでに OpenClaw が待機する時間を制御し、その後セッションを破棄します。デフォルト: `15000`。 -- OpenClaw は受信復号失敗も監視し、短時間のうちに失敗が繰り返された場合、音声チャンネルから退出して再参加することで自動復旧します。 -- 更新後に受信ログで `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` が繰り返し表示される場合は、依存関係レポートとログを収集してください。バンドルされている `@discordjs/voice` 系統には、discord.js PR #11449 の上流パディング修正が含まれており、これは discord.js issue #11419 をクローズしたものです。 +- 未設定の場合、`@discordjs/voice` のデフォルトは `daveEncryption=true` と `decryptionFailureTolerance=24` です。 +- `voice.connectTimeoutMs` は、`/vc join` と自動参加の試行で、初回の `@discordjs/voice` Ready 待機を制御します。デフォルト: `30000`。 +- `voice.reconnectGraceMs` は、切断された音声セッションが再接続を開始するまで OpenClaw が待機する時間を制御し、その後破棄します。デフォルト: `15000`。 +- OpenClaw は受信復号失敗も監視し、短時間のウィンドウ内で失敗が繰り返された場合に、音声チャンネルを退出して再参加することで自動復旧します。 +- 更新後に受信ログで `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` が繰り返し表示される場合は、依存関係レポートとログを収集してください。バンドルされている `@discordjs/voice` ラインには、discord.js issue #11419 をクローズした discord.js PR #11449 のアップストリームのパディング修正が含まれています。 音声チャンネルパイプライン: - Discord PCM キャプチャは WAV 一時ファイルに変換されます。 - `tools.media.audio` が STT を処理します。例: `openai/gpt-4o-mini-transcribe`。 -- トランスクリプトは Discord ingress とルーティングを通じて送信されます。その間、応答 LLM は、エージェントの `tts` ツールを非表示にして返却テキストを求める音声出力ポリシーで実行されます。これは Discord 音声が最終的な TTS 再生を所有するためです。 +- トランスクリプトは Discord ingress とルーティングを通して送信されます。その間、応答 LLM は、エージェントの `tts` ツールを隠して返却テキストを求める音声出力ポリシーで実行されます。これは、Discord 音声が最終的な TTS 再生を所有するためです。 - `voice.model` が設定されている場合、この音声チャンネルターンの応答 LLM のみを上書きします。 -- `voice.tts` は `messages.tts` の上にマージされ、結果の音声が参加済みチャンネルで再生されます。 +- `voice.tts` は `messages.tts` にマージされます。結果の音声は参加中のチャンネルで再生されます。 -認証情報はコンポーネントごとに解決されます。`voice.model` の LLM ルート認証、`tools.media.audio` の STT 認証、`messages.tts`/`voice.tts` の TTS 認証です。 +資格情報はコンポーネントごとに解決されます。`voice.model` の LLM ルート認証、`tools.media.audio` の STT 認証、`messages.tts`/`voice.tts` の TTS 認証です。 ### 音声メッセージ Discord 音声メッセージは波形プレビューを表示し、OGG/Opus 音声を必要とします。OpenClaw は波形を自動生成しますが、検査と変換のために Gateway ホスト上の `ffmpeg` と `ffprobe` が必要です。 -- **ローカルファイルパス**を指定します（URL は拒否されます）。 -- テキスト内容は省略します（Discord は同じペイロード内のテキスト + 音声メッセージを拒否します）。 +- **ローカルファイルパス**を指定します (URL は拒否されます)。 +- テキストコンテンツは省略します (Discord は同じペイロード内のテキスト + 音声メッセージを拒否します)。 - 任意の音声形式を受け付けます。OpenClaw は必要に応じて OGG/Opus に変換します。 ```bash @@ -1211,20 +1220,20 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - - Message Content Intent を有効にする - - ユーザー/メンバー解決に依存している場合は Server Members Intent を有効にする - - インテントを変更した後に gateway を再起動する + - Message Content Intent を有効化する + - ユーザー/メンバー解決に依存する場合は Server Members Intent を有効化する + - インテント変更後に Gateway を再起動する - `groupPolicy` を確認する - - `channels.discord.guilds` の下のギルド許可リストを確認する + - `channels.discord.guilds` 配下のギルド許可リストを確認する - ギルドの `channels` マップが存在する場合、一覧にあるチャンネルのみが許可される - `requireMention` の動作とメンションパターンを確認する - 有用な確認: + 便利な確認: ```bash openclaw doctor @@ -1234,12 +1243,12 @@ openclaw logs --follow - + よくある原因: - - 一致するギルド/チャンネル許可リストなしで `groupPolicy="allowlist"` が設定されている - - `requireMention` が誤った場所に設定されている（`channels.discord.guilds` またはチャンネルエントリの下にある必要があります） - - 送信者がギルド/チャンネルの `users` 許可リストによってブロックされている + - 一致するギルド/チャンネル許可リストがない `groupPolicy="allowlist"` + - `requireMention` が誤った場所に設定されている (`channels.discord.guilds` またはチャンネルエントリ配下である必要があります) + - 送信者がギルド/チャンネルの `users` 許可リストでブロックされている @@ -1250,13 +1259,13 @@ openclaw logs --follow - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - Discord gateway キューの調整項目: + Discord Gateway キューの調整項目: - 単一アカウント: `channels.discord.eventQueue.listenerTimeout` - 複数アカウント: `channels.discord.accounts..eventQueue.listenerTimeout` - - これは Discord gateway リスナーの作業のみを制御し、エージェントターンの寿命は制御しません + - これは Discord Gateway リスナーの処理だけを制御し、エージェントターンの生存期間は制御しない - Discord は、キューに入ったエージェントターンに対してチャンネル所有のタイムアウトを適用しません。メッセージリスナーは即座に引き渡し、キューに入った Discord 実行は、セッション/ツール/ランタイムのライフサイクルが完了するか作業を中止するまで、セッションごとの順序を保持します。 + Discord は、キューに入ったエージェントターンにチャンネル所有のタイムアウトを適用しません。メッセージリスナーは即座にハンドオフし、キューに入った Discord 実行は、セッション/ツール/ランタイムのライフサイクルが完了するか作業を中止するまで、セッションごとの順序を保持します。 ```json5 { @@ -1277,53 +1286,53 @@ openclaw logs --follow - OpenClaw は接続前に Discord `/gateway/bot` メタデータを取得します。一時的な失敗時は Discord のデフォルト Gateway URL にフォールバックし、ログではレート制限されます。 + OpenClaw は接続前に Discord `/gateway/bot` メタデータを取得します。一時的な失敗では Discord のデフォルト Gateway URL にフォールバックし、ログではレート制限されます。 メタデータタイムアウトの調整項目: - 単一アカウント: `channels.discord.gatewayInfoTimeoutMs` - 複数アカウント: `channels.discord.accounts..gatewayInfoTimeoutMs` - - 設定が未設定の場合の env フォールバック: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` - - デフォルト: `30000`（30 秒）、最大: `120000` + - config が未設定の場合の env フォールバック: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` + - デフォルト: `30000` (30 秒)、最大: `120000` - OpenClaw は、起動時とランタイム再接続後に Discord の gateway `READY` イベントを待機します。起動の時間差を設けたマルチアカウント構成では、デフォルトより長い起動時 READY ウィンドウが必要になる場合があります。 + OpenClaw は起動時と実行時の再接続後に Discord の Gateway `READY` イベントを待機します。起動時の段階的開始を使う複数アカウント構成では、デフォルトより長い起動時 READY ウィンドウが必要になる場合があります。 READY タイムアウトの調整項目: - 起動時の単一アカウント: `channels.discord.gatewayReadyTimeoutMs` - - 起動時のマルチアカウント: `channels.discord.accounts..gatewayReadyTimeoutMs` - - 設定が未指定の場合の起動時 env フォールバック: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` - - 起動時デフォルト: `15000` (15 秒)、最大: `120000` - - ランタイムの単一アカウント: `channels.discord.gatewayRuntimeReadyTimeoutMs` - - ランタイムのマルチアカウント: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` - - 設定が未指定の場合のランタイム env フォールバック: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` - - ランタイムデフォルト: `30000` (30 秒)、最大: `120000` + - 起動時の複数アカウント: `channels.discord.accounts..gatewayReadyTimeoutMs` + - config が未設定の場合の起動時 env フォールバック: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` + - 起動時のデフォルト: `15000` (15 秒)、最大: `120000` + - 実行時の単一アカウント: `channels.discord.gatewayRuntimeReadyTimeoutMs` + - 実行時の複数アカウント: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` + - config が未設定の場合の実行時 env フォールバック: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` + - 実行時のデフォルト: `30000` (30 秒)、最大: `120000` - `channels status --probe` の権限チェックは、数値のチャンネル ID でのみ機能します。 + `channels status --probe` の権限チェックは数値のチャンネル ID でのみ機能します。 - slug キーを使用している場合でもランタイムの照合は機能しますが、probe は権限を完全には検証できません。 + slug キーを使う場合、実行時のマッチングは引き続き機能することがありますが、probe は権限を完全には検証できません。 - - DM 無効: `channels.discord.dm.enabled=false` - - DM ポリシー無効: `channels.discord.dmPolicy="disabled"` (レガシー: `channels.discord.dm.policy`) + - DM が無効: `channels.discord.dm.enabled=false` + - DM ポリシーが無効: `channels.discord.dmPolicy="disabled"` (レガシー: `channels.discord.dm.policy`) - `pairing` モードでペアリング承認待ち - + デフォルトでは、bot が作成したメッセージは無視されます。 - `channels.discord.allowBots=true` を設定する場合は、ループ動作を避けるために厳密なメンションと allowlist ルールを使用してください。 - bot にメンションしている bot メッセージのみを受け入れるには、`channels.discord.allowBots="mentions"` を推奨します。 + `channels.discord.allowBots=true` を設定する場合は、ループ動作を避けるために厳格なメンションと allowlist ルールを使用してください。 + bot にメンションした bot メッセージのみを受け入れるには、`channels.discord.allowBots="mentions"` を推奨します。 ```json5 { @@ -1350,15 +1359,15 @@ openclaw logs --follow - + - Discord 音声受信の復旧ロジックが存在するよう、OpenClaw を最新に保つ (`openclaw update`) - `channels.discord.voice.daveEncryption=true` (デフォルト) を確認する - - `channels.discord.voice.decryptionFailureTolerance=24` (アップストリームのデフォルト) から始め、必要な場合のみ調整する - - ログで次を監視する: + - `channels.discord.voice.decryptionFailureTolerance=24` (上流のデフォルト) から始め、必要な場合にのみ調整する + - 次のログを監視する: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - 自動再参加後も失敗が続く場合は、ログを収集し、[discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) と [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) のアップストリーム DAVE 受信履歴と比較する + - 自動再参加後も失敗が続く場合は、ログを収集し、[discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) と [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) の上流 DAVE 受信履歴と比較する @@ -1367,13 +1376,13 @@ openclaw logs --follow 主要リファレンス: [設定リファレンス - Discord](/ja-JP/gateway/config-channels#discord)。 - + -- 起動/認証: `enabled`, `token`, `accounts.*`, `allowBots` +- 起動/auth: `enabled`, `token`, `accounts.*`, `allowBots` - ポリシー: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` - コマンド: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` -- イベントキュー: `eventQueue.listenerTimeout` (listener 予算), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` -- gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` +- イベントキュー: `eventQueue.listenerTimeout` (リスナーの予算), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` +- Gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` - 返信/履歴: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - 配信: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` - ストリーミング: `streaming` (レガシーエイリアス: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` @@ -1387,8 +1396,8 @@ openclaw logs --follow ## 安全性と運用 -- bot トークンはシークレットとして扱う (管理環境では `DISCORD_BOT_TOKEN` を推奨)。 -- 最小権限の Discord 権限を付与する。 +- bot トークンはシークレットとして扱う (管理された環境では `DISCORD_BOT_TOKEN` を推奨)。 +- Discord 権限は最小権限で付与する。 - コマンドのデプロイ/状態が古い場合は、gateway を再起動し、`openclaw channels status --probe` で再確認する。 ## 関連 @@ -1401,7 +1410,7 @@ openclaw logs --follow グループチャットと allowlist の動作。 - 受信メッセージをエージェントへルーティングします。 + 受信メッセージをエージェントにルーティングします。 脅威モデルと堅牢化。 diff --git a/docs/ja-JP/channels/slack.md b/docs/ja-JP/channels/slack.md index 55305363e..649f70b1e 100644 --- a/docs/ja-JP/channels/slack.md +++ b/docs/ja-JP/channels/slack.md @@ -1,18 +1,18 @@ --- read_when: - - Slack のセットアップまたは Slack のソケット/HTTP モードのデバッグ -summary: Slack のセットアップとランタイム動作（Socket Mode + HTTP Request URLs） + - Slack の設定、または Slack のソケット/HTTP モードのデバッグ +summary: Slack のセットアップと実行時の動作（ソケットモード + HTTP リクエスト URL） title: Slack x-i18n: - generated_at: "2026-05-04T04:58:17Z" + generated_at: "2026-05-04T07:02:57Z" model: gpt-5.5 provider: openai - source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b + source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 source_path: channels/slack.md workflow: 16 --- -DM とチャンネル向けに、Slack アプリ連携で本番運用可能です。デフォルトモードはソケットモードです。HTTPリクエストURLにも対応しています。 +DM とチャンネル向けに Slack アプリ連携経由で本番運用可能です。デフォルトのモードは Socket Mode です。HTTP Request URLs もサポートされています。 @@ -22,28 +22,28 @@ DM とチャンネル向けに、Slack アプリ連携で本番運用可能で ネイティブコマンドの動作とコマンドカタログ。 - チャンネル横断の診断と修復手順。 + チャンネル横断の診断と修復プレイブック。 ## クイックセットアップ - + - Slack アプリ設定で **[新しいアプリを作成](https://api.slack.com/apps/new)** ボタンを押します。 + Slack アプリ設定で **[Create New App](https://api.slack.com/apps/new)** ボタンを押します。 - - **マニフェストから** を選び、アプリ用のワークスペースを選択します - - 下の [サンプルマニフェスト](#manifest-and-scope-checklist) を貼り付け、作成へ進みます - - `connections:write` を持つ **アプリレベルトークン**（`xapp-...`）を生成します - - アプリをインストールし、表示された **ボットトークン**（`xoxb-...`）をコピーします + - **from a manifest** を選択し、アプリ用のワークスペースを選択します + - 下の [マニフェスト例](#manifest-and-scope-checklist) を貼り付け、作成に進みます + - `connections:write` を指定して **App-Level Token** (`xapp-...`) を生成します + - アプリをインストールし、表示された **Bot Token** (`xoxb-...`) をコピーします - 推奨の SecretRef セットアップ: + 推奨の SecretRef 設定: ```bash export SLACK_APP_TOKEN=xapp-... @@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - 環境変数フォールバック（デフォルトアカウントのみ）: + env フォールバック (デフォルトアカウントのみ): ```bash SLACK_APP_TOKEN=xapp-... @@ -84,21 +84,21 @@ openclaw gateway - + - Slack アプリ設定で **[新しいアプリを作成](https://api.slack.com/apps/new)** ボタンを押します。 + Slack アプリ設定で **[Create New App](https://api.slack.com/apps/new)** ボタンを押します。 - - **マニフェストから** を選び、アプリ用のワークスペースを選択します - - [サンプルマニフェスト](#manifest-and-scope-checklist) を貼り付け、作成前にURLを更新します - - リクエスト検証用の **署名シークレット** を保存します - - アプリをインストールし、表示された **ボットトークン**（`xoxb-...`）をコピーします + - **from a manifest** を選択し、アプリ用のワークスペースを選択します + - [マニフェスト例](#manifest-and-scope-checklist) を貼り付け、作成前に URL を更新します + - リクエスト検証用の **Signing Secret** を保存します + - アプリをインストールし、表示された **Bot Token** (`xoxb-...`) をコピーします - 推奨の SecretRef セットアップ: + 推奨の SecretRef 設定: ```bash export SLACK_BOT_TOKEN=xoxb-... @@ -121,9 +121,9 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - 複数アカウントのHTTPでは一意のWebhookパスを使用してください + 複数アカウントの HTTP には一意の webhook パスを使用する - 登録が衝突しないように、各アカウントへ個別の `webhookPath`（デフォルトは `/slack/events`）を指定してください。 + 登録が衝突しないように、各アカウントに個別の `webhookPath` (デフォルト `/slack/events`) を指定します。 @@ -140,9 +140,9 @@ openclaw gateway -## ソケットモードのトランスポート調整 +## Socket Mode トランスポート調整 -OpenClaw はソケットモードで、Slack SDK クライアントのpongタイムアウトをデフォルトで15秒に設定します。ワークスペースまたはホスト固有の調整が必要な場合にのみ、トランスポート設定を上書きしてください。 +OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアントの pong タイムアウトを 15 秒に設定します。ワークスペースまたはホスト固有の調整が必要な場合にのみ、トランスポート設定を上書きしてください。 ```json5 { @@ -159,13 +159,13 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ } ``` -これは、Slack websocket のpongタイムアウトやserver-pingタイムアウトがログに記録されるソケットモードのワークスペース、またはイベントループの枯渇が既知のホストでのみ使用してください。`clientPingTimeout` は SDK がクライアントpingを送信した後のpong待機時間です。`serverPingTimeout` は Slack サーバーpingの待機時間です。アプリメッセージとイベントはアプリケーション状態のままであり、トランスポートの生存確認シグナルではありません。 +これは、Slack websocket の pong/server-ping タイムアウトをログに記録する Socket Mode ワークスペース、または既知のイベントループ枯渇があるホストでのみ使用してください。`clientPingTimeout` は SDK がクライアント ping を送信した後の pong 待機時間です。`serverPingTimeout` は Slack サーバー ping の待機時間です。アプリメッセージとイベントは、トランスポートの生存性シグナルではなく、アプリケーション状態のままです。 ## マニフェストとスコープのチェックリスト -基本の Slack アプリマニフェストは、ソケットモードとHTTPリクエストURLで同じです。異なるのは `settings` ブロック（およびスラッシュコマンドの `url`）だけです。 +基本の Slack アプリマニフェストは Socket Mode と HTTP Request URLs で同じです。異なるのは `settings` ブロック (およびスラッシュコマンドの `url`) だけです。 -基本マニフェスト（ソケットモードのデフォルト）: +基本マニフェスト (Socket Mode デフォルト): ```json { @@ -240,7 +240,7 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ } ``` -**HTTPリクエストURLモード** では、`settings` をHTTP版に置き換え、各スラッシュコマンドに `url` を追加します。公開URLが必要です。 +**HTTP Request URLs モード** では、`settings` を HTTP バリアントに置き換え、各スラッシュコマンドに `url` を追加します。公開 URL が必要です。 ```json { @@ -284,22 +284,22 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ ### 追加のマニフェスト設定 -上記のデフォルトを拡張するさまざまな機能を公開します。 +上記のデフォルトを拡張する別の機能を公開します。 -デフォルトのマニフェストでは、Slack App Home の **ホーム** タブが有効になり、`app_home_opened` を購読します。ワークスペースメンバーがホームタブを開くと、OpenClaw は `views.publish` で安全なデフォルトのホームビューを公開します。会話ペイロードや非公開設定は含まれません。Slack DM 向けに **メッセージ** タブは有効なままです。 +デフォルトのマニフェストでは、Slack App Home の **Home** タブが有効になり、`app_home_opened` をサブスクライブします。ワークスペースメンバーが Home タブを開くと、OpenClaw は `views.publish` で安全なデフォルトの Home ビューを公開します。会話ペイロードや非公開設定は含まれません。**Messages** タブは Slack DM 用に有効なままです。 - 単一の設定済みコマンドの代わりに複数の [ネイティブスラッシュコマンド](#commands-and-slash-behavior) を使えますが、いくつか注意点があります。 + ニュアンスのある単一の設定済みコマンドの代わりに、複数の [ネイティブスラッシュコマンド](#commands-and-slash-behavior) を使用できます。 - - `/status` コマンドは予約済みのため、`/status` の代わりに `/agentstatus` を使用してください。 - - 同時に利用可能にできるスラッシュコマンドは25個までです。 + - `/status` コマンドは予約されているため、`/status` の代わりに `/agentstatus` を使用します。 + - 一度に利用可能にできるスラッシュコマンドは 25 個以下です。 - 既存の `features.slash_commands` セクションを [利用可能なコマンド](/ja-JP/tools/slash-commands#command-list) の一部に置き換えます。 + 既存の `features.slash_commands` セクションを、[利用可能なコマンド](/ja-JP/tools/slash-commands#command-list) のサブセットに置き換えます。 - + ```json { @@ -422,8 +422,8 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ ``` - - 上記のソケットモードと同じ `slash_commands` リストを使用し、すべての項目に `"url": "https://gateway-host.example.com/slack/events"` を追加します。例: + + 上の Socket Mode と同じ `slash_commands` リストを使用し、すべてのエントリに `"url": "https://gateway-host.example.com/slack/events"` を追加します。例: ```json { @@ -443,19 +443,19 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ } ``` - リスト内のすべてのコマンドで同じ `url` 値を繰り返します。 + リスト内のすべてのコマンドでその `url` 値を繰り返します。 - + 送信メッセージでデフォルトの Slack アプリ ID ではなく、アクティブなエージェント ID（カスタムユーザー名とアイコン）を使いたい場合は、`chat:write.customize` bot スコープを追加します。 絵文字アイコンを使う場合、Slack は `:emoji_name:` 構文を想定します。 - + `channels.slack.userToken` を設定する場合、一般的な読み取りスコープは次のとおりです。 - `channels:history`, `groups:history`, `im:history`, `mpim:history` @@ -473,29 +473,34 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ - Socket Mode には `botToken` + `appToken` が必要です。 - HTTP モードには `botToken` + `signingSecret` が必要です。 -- `botToken`, `appToken`, `signingSecret`, `userToken` は、プレーンテキスト文字列または SecretRef オブジェクトを受け付けます。 -- 設定トークンは env フォールバックより優先されます。 +- `botToken`、`appToken`、`signingSecret`、`userToken` はプレーンテキスト + 文字列または SecretRef オブジェクトを受け付けます。 +- 設定内のトークンは env フォールバックを上書きします。 - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env フォールバックはデフォルトアカウントにのみ適用されます。 -- `userToken`（`xoxp-...`）は設定専用（env フォールバックなし）で、デフォルトでは読み取り専用の動作（`userTokenReadOnly: true`）になります。 +- `userToken`（`xoxp-...`）は設定専用（env フォールバックなし）で、デフォルトでは読み取り専用動作（`userTokenReadOnly: true`）です。 ステータススナップショットの動作: -- Slack アカウント検査は、認証情報ごとの `*Source` と `*Status` フィールド（`botToken`, `appToken`, `signingSecret`, `userToken`）を追跡します。 -- ステータスは `available`, `configured_unavailable`, `missing` のいずれかです。 -- `configured_unavailable` は、そのアカウントが SecretRef または別の非インラインシークレットソースを通じて設定されているものの、現在のコマンドまたはランタイムパスでは実際の値を解決できなかったことを意味します。 -- HTTP モードでは `signingSecretStatus` が含まれます。Socket Mode では必要なペアは `botTokenStatus` + `appTokenStatus` です。 +- Slack アカウント検査は、認証情報ごとの `*Source` および `*Status` + フィールド（`botToken`、`appToken`、`signingSecret`、`userToken`）を追跡します。 +- ステータスは `available`、`configured_unavailable`、または `missing` です。 +- `configured_unavailable` は、アカウントが SecretRef + または別の非インラインのシークレットソースを通じて設定されているものの、現在のコマンド/runtime パスでは + 実際の値を解決できなかったことを意味します。 +- HTTP モードでは `signingSecretStatus` が含まれます。Socket Mode では + 必須のペアは `botTokenStatus` + `appTokenStatus` です。 -アクションやディレクトリ読み取りでは、設定されている場合に user token が優先されることがあります。書き込みでは bot token が引き続き優先されます。user-token 書き込みは、`userTokenReadOnly: false` で、かつ bot token が利用できない場合にのみ許可されます。 +actions/directory の読み取りでは、設定されている場合に user token が優先されることがあります。書き込みでは bot token が引き続き優先されます。user-token 書き込みは、`userTokenReadOnly: false` で bot token が利用できない場合にのみ許可されます。 ## アクションとゲート Slack アクションは `channels.slack.actions.*` で制御されます。 -現在の Slack ツールで利用できるアクショングループ: +現在の Slack ツールで利用可能なアクショングループ: -| グループ | デフォルト | +| グループ | デフォルト | | ---------- | ------- | | messages | 有効 | | reactions | 有効 | @@ -503,7 +508,7 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 | memberInfo | 有効 | | emojiList | 有効 | -現在の Slack メッセージアクションには、`send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, `emoji-list` があります。`download-file` は受信ファイルプレースホルダーに表示される Slack ファイル ID を受け取り、画像の場合は画像プレビューを、それ以外のファイル種別の場合はローカルファイルメタデータを返します。 +現在の Slack メッセージアクションには、`send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info`、`emoji-list` があります。`download-file` はインバウンドファイルプレースホルダーに表示される Slack ファイル ID を受け付け、画像の場合は画像プレビューを、それ以外のファイルタイプの場合はローカルファイルメタデータを返します。 ## アクセス制御とルーティング @@ -513,50 +518,50 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 - `pairing`（デフォルト） - `allowlist` - - `open`（`channels.slack.allowFrom` に `"*"` が含まれている必要があります） + - `open`（`channels.slack.allowFrom` に `"*"` を含める必要があります） - `disabled` DM フラグ: - - `dm.enabled`（デフォルト true） + - `dm.enabled`（デフォルトは true） - `channels.slack.allowFrom` - `dm.allowFrom`（レガシー） - `dm.groupEnabled`（グループ DM のデフォルトは false） - `dm.groupChannels`（任意の MPIM 許可リスト） - 複数アカウントでの優先順位: + マルチアカウントの優先順位: - `channels.slack.accounts.default.allowFrom` は `default` アカウントにのみ適用されます。 - 名前付きアカウントは、自身の `allowFrom` が未設定の場合に `channels.slack.allowFrom` を継承します。 - 名前付きアカウントは `channels.slack.accounts.default.allowFrom` を継承しません。 - レガシーの `channels.slack.dm.policy` と `channels.slack.dm.allowFrom` は、互換性のために引き続き読み取られます。`openclaw doctor --fix` は、アクセスを変更せずに実行できる場合、それらを `dmPolicy` と `allowFrom` に移行します。 + レガシーの `channels.slack.dm.policy` と `channels.slack.dm.allowFrom` は互換性のため引き続き読み取られます。`openclaw doctor --fix` は、アクセスを変更せずに実行できる場合、それらを `dmPolicy` と `allowFrom` に移行します。 DM でのペアリングには `openclaw pairing approve slack ` を使います。 - `channels.slack.groupPolicy` はチャンネル処理を制御します。 + `channels.slack.groupPolicy` はチャンネルの処理を制御します。 - `open` - `allowlist` - `disabled` - チャンネル許可リストは `channels.slack.channels` 配下にあり、設定キーとして**安定した Slack チャンネル ID**（例: `C12345678`）を使う必要があります。 + チャンネル許可リストは `channels.slack.channels` の下にあり、設定キーとして**安定した Slack チャンネル ID**（例: `C12345678`）を使う必要があります。 - ランタイム上の注意: `channels.slack` が完全に存在しない場合（env のみのセットアップ）、ランタイムは `groupPolicy="allowlist"` にフォールバックし、警告をログに出力します（`channels.defaults.groupPolicy` が設定されている場合でも同様です）。 + Runtime 注記: `channels.slack` が完全に存在しない場合（env のみのセットアップ）、runtime は `groupPolicy="allowlist"` にフォールバックし、警告をログに記録します（`channels.defaults.groupPolicy` が設定されている場合でも）。 名前/ID 解決: - - チャンネル許可リストエントリと DM 許可リストエントリは、トークンアクセスで許可される場合、起動時に解決されます - - 未解決のチャンネル名エントリは設定されたまま保持されますが、デフォルトではルーティングでは無視されます - - 受信認可とチャンネルルーティングはデフォルトで ID 優先です。直接のユーザー名/スラッグ照合には `channels.slack.dangerouslyAllowNameMatching: true` が必要です + - チャンネル許可リストのエントリと DM 許可リストのエントリは、トークンアクセスで可能な場合、起動時に解決されます + - 解決できないチャンネル名エントリは設定されたまま保持されますが、デフォルトではルーティングで無視されます + - インバウンド認可とチャンネルルーティングはデフォルトで ID 優先です。直接のユーザー名/slug マッチングには `channels.slack.dangerouslyAllowNameMatching: true` が必要です - 名前ベースのキー（`#channel-name` または `channel-name`）は `groupPolicy: "allowlist"` では一致しません。チャンネル検索はデフォルトで ID 優先のため、名前ベースのキーでは正常にルーティングされず、そのチャンネル内のすべてのメッセージがサイレントにブロックされます。これは、チャンネルキーがルーティングに不要で、名前ベースのキーが機能しているように見える `groupPolicy: "open"` とは異なります。 + 名前ベースのキー（`#channel-name` または `channel-name`）は `groupPolicy: "allowlist"` では一致しません。チャンネル検索はデフォルトで ID 優先のため、名前ベースのキーでは正常にルーティングされることはなく、そのチャンネル内のすべてのメッセージは静かにブロックされます。これは、ルーティングにチャンネルキーが不要で、名前ベースのキーが機能しているように見える `groupPolicy: "open"` とは異なります。 - キーには必ず Slack チャンネル ID を使ってください。確認するには、Slack でチャンネルを右クリック → **Copy link** — URL の末尾に ID（`C...`）が表示されます。 + 常に Slack チャンネル ID をキーとして使ってください。見つけるには、Slack でチャンネルを右クリック → **リンクをコピー** — URL の末尾に ID（`C...`）が表示されます。 正しい例: @@ -573,7 +578,7 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 } ``` - 誤った例（`groupPolicy: "allowlist"` ではサイレントにブロックされます）: + 誤り（`groupPolicy: "allowlist"` の下で暗黙的にブロックされます）: ```json5 { @@ -591,28 +596,28 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 - - チャンネルメッセージはデフォルトでメンションによってゲートされます。 + + チャンネルメッセージはデフォルトでメンションによって制限されます。 - メンションソース: + メンションのソース: - 明示的なアプリメンション（`<@botId>`） - - bot ユーザーがそのユーザーグループのメンバーである場合の Slack ユーザーグループメンション（``）。`usergroups:read` が必要です + - ボットユーザーがそのユーザーグループのメンバーである場合の Slack ユーザーグループメンション（``）。`usergroups:read` が必要です - メンション正規表現パターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは `messages.groupChat.mentionPatterns`） - - bot への暗黙的な返信スレッド動作（`thread.requireExplicitMention` が `true` の場合は無効） + - ボットへの返信スレッドの暗黙的な動作（`thread.requireExplicitMention` が `true` の場合は無効） - チャンネルごとの制御（`channels.slack.channels.`。名前は起動時解決または `dangerouslyAllowNameMatching` 経由のみ）: + チャンネルごとの制御（`channels.slack.channels.`。名前は起動時の解決または `dangerouslyAllowNameMatching` 経由のみ）: - `requireMention` - - `users`（許可リスト） + - `users`（allowlist） - `allowBots` - `skills` - `systemPrompt` - - `tools`, `toolsBySender` - - `toolsBySender` キー形式: `id:`, `e164:`, `username:`, `name:`, または `"*"` ワイルドカード - （レガシーの接頭辞なしキーは引き続き `id:` のみにマップされます） + - `tools`、`toolsBySender` + - `toolsBySender` のキー形式: `id:`、`e164:`、`username:`、`name:`、または `"*"` ワイルドカード + （レガシーのプレフィックスなしキーは引き続き `id:` のみにマップされます） - `allowBots` はチャンネルとプライベートチャンネルでは保守的です。bot が作成したルームメッセージは、送信元 bot がそのルームの `users` 許可リストに明示的に記載されている場合、または `channels.slack.allowFrom` の明示的な Slack 所有者 ID の少なくとも 1 つが現在ルームメンバーである場合にのみ受け付けられます。ワイルドカードや表示名の所有者エントリは、所有者の存在を満たしません。所有者の存在確認には Slack `conversations.members` を使います。アプリにルーム種別に対応する読み取りスコープ（公開チャンネルは `channels:read`、プライベートチャンネルは `groups:read`）があることを確認してください。メンバー検索に失敗した場合、OpenClaw は bot が作成したルームメッセージを破棄します。 + `allowBots` はチャンネルとプライベートチャンネルでは保守的です。ボットが作成したルームメッセージは、送信元ボットがそのルームの `users` allowlist に明示的に列挙されている場合、または `channels.slack.allowFrom` からの明示的な Slack オーナー ID が少なくとも 1 つ現在ルームメンバーである場合にのみ受け付けられます。ワイルドカードと表示名のオーナーエントリは、オーナーの存在条件を満たしません。オーナーの存在確認には Slack `conversations.members` を使用します。アプリにルーム種別に対応する読み取りスコープ（パブリックチャンネルは `channels:read`、プライベートチャンネルは `groups:read`）があることを確認してください。メンバー検索に失敗した場合、OpenClaw はボットが作成したルームメッセージを破棄します。 @@ -620,65 +625,84 @@ Slack アクションは `channels.slack.actions.*` で制御されます。 ## スレッド、セッション、返信タグ - DM は `direct` として、チャンネルは `channel` として、MPIM は `group` としてルーティングされます。 -- Slack ルートバインディングは、生のピア ID に加えて、`channel:C12345678`, `user:U12345678`, `<@U12345678>` などの Slack ターゲット形式を受け付けます。 +- Slack ルートバインディングは、生のピア ID に加えて `channel:C12345678`、`user:U12345678`、`<@U12345678>` などの Slack ターゲット形式を受け付けます。 - デフォルトの `session.dmScope=main` では、Slack DM はエージェントのメインセッションに集約されます。 - チャンネルセッション: `agent::slack:channel:`。 -- スレッド返信は、該当する場合にスレッドセッションサフィックス（`:thread:`）を作成できます。 +- スレッド返信では、該当する場合にスレッドセッション接尾辞（`:thread:`）を作成できます。 - `channels.slack.thread.historyScope` のデフォルトは `thread` です。`thread.inheritParent` のデフォルトは `false` です。 -- `channels.slack.thread.initialHistoryLimit` は、新しいスレッドセッションが開始するときに取得する既存スレッドメッセージ数を制御します（デフォルトは `20`。無効にするには `0` を設定します）。 -- `channels.slack.thread.requireExplicitMention`（デフォルト `false`）: `true` の場合、bot がすでにスレッドに参加していても、bot はスレッド内の明示的な `@bot` メンションにのみ応答するよう、暗黙的なスレッドメンションを抑制します。これがない場合、bot が参加したスレッド内の返信は `requireMention` ゲートをバイパスします。 +- `channels.slack.thread.initialHistoryLimit` は、新しいスレッドセッションの開始時に取得される既存スレッドメッセージ数を制御します（デフォルトは `20`。無効にするには `0` を設定）。 +- `channels.slack.thread.requireExplicitMention`（デフォルト `false`）: `true` の場合、暗黙的なスレッドメンションを抑制し、ボットがすでにスレッドに参加していても、スレッド内の明示的な `@bot` メンションにのみボットが応答します。これがない場合、ボットが参加したスレッド内の返信は `requireMention` の制限をバイパスします。 -返信スレッド制御: +返信スレッドの制御: - `channels.slack.replyToMode`: `off|first|all|batched`（デフォルト `off`） - `channels.slack.replyToModeByChatType`: `direct|group|channel` ごと -- 直接チャット向けのレガシーフォールバック: `channels.slack.dm.replyToMode` +- ダイレクトチャット向けのレガシーフォールバック: `channels.slack.dm.replyToMode` -手動返信タグがサポートされています。 +手動返信タグがサポートされています: - `[[reply_to_current]]` - `[[reply_to:]]` -`replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含む Slack の**すべて**の返信スレッドを無効にします。これは、`"off"` モードでも明示的なタグが引き続き尊重される Telegram とは異なります。Slack スレッドはメッセージをチャンネルから隠しますが、Telegram の返信はインラインで表示されたままです。 +`replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含む Slack の**すべての**返信スレッド化を無効にします。これは、明示的なタグが `"off"` モードでも引き続き尊重される Telegram とは異なります。Slack スレッドはチャンネルからメッセージを非表示にしますが、Telegram の返信はインラインで表示されたままです。 ## Ack リアクション -`ackReaction` は、OpenClaw が受信メッセージを処理している間、確認応答の絵文字を送信します。 +`ackReaction` は、OpenClaw が受信メッセージを処理している間に確認用絵文字を送信します。 解決順序: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- エージェント ID の絵文字フォールバック（`agents.list[].identity.emoji`、それ以外は "👀"） +- エージェント ID 絵文字フォールバック（`agents.list[].identity.emoji`、なければ「👀」） -注記: +注: -- Slack はショートコード（例: `"eyes"`）を想定します。 -- Slack アカウントまたは全体でリアクションを無効にするには `""` を使います。 +- Slack はショートコード（例: `"eyes"`）を想定しています。 +- Slack アカウントまたはグローバルでリアクションを無効にするには `""` を使用します。 ## テキストストリーミング -`channels.slack.streaming` はライブプレビューの動作を制御します。 +`channels.slack.streaming` はライブプレビューの動作を制御します: - `off`: ライブプレビューストリーミングを無効にします。 - `partial`（デフォルト）: プレビューテキストを最新の部分出力で置き換えます。 -- `block`: チャンク化されたプレビュー更新を追加します。 -- `progress`: 生成中は進行状況テキストを表示し、その後に最終テキストを送信します。 -- `streaming.preview.toolProgress`: 下書きプレビューが有効な場合、ツール/進行状況更新を同じ編集済みプレビューメッセージにルーティングします（デフォルト: `true`）。別々のツール/進行状況メッセージを維持するには `false` を設定します。 +- `block`: 分割されたプレビュー更新を追加します。 +- `progress`: 生成中は進行状況テキストを表示し、その後で最終テキストを送信します。 +- `streaming.preview.toolProgress`: 下書きプレビューが有効な場合、ツール/進行状況の更新を同じ編集済みプレビューメッセージにルーティングします（デフォルト: `true`）。個別のツール/進行状況メッセージを保持するには `false` に設定します。 +- `streaming.preview.commandText` / `streaming.progress.commandText`: 生のコマンド/実行テキストを隠しつつ、コンパクトなツール進行状況行を保持するには `status` に設定します（デフォルト: `raw`）。 + +コンパクトな進行状況行を保持しながら、生のコマンド/実行テキストを非表示にします: + +```json +{ + "channels": { + "slack": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } +} +``` `channels.slack.streaming.nativeTransport` は、`channels.slack.streaming.mode` が `partial` の場合の Slack ネイティブテキストストリーミングを制御します（デフォルト: `true`）。 - ネイティブテキストストリーミングと Slack アシスタントスレッドステータスを表示するには、返信スレッドが利用可能である必要があります。スレッド選択は引き続き `replyToMode` に従います。 -- ネイティブストリーミングが利用できない場合、または返信スレッドが存在しない場合でも、チャンネル、グループチャット、トップレベル DM ルートは通常の下書きプレビューを使用できます。 -- トップレベルの Slack DM はデフォルトでスレッド外のままなので、Slack のスレッド形式のネイティブストリーム/ステータスプレビューは表示されません。代わりに OpenClaw は DM に下書きプレビューを投稿して編集します。 -- メディアと非テキストペイロードは通常の配信にフォールバックします。 -- メディア/エラーの最終出力は保留中のプレビュー編集をキャンセルします。対象となるテキスト/ブロックの最終出力は、プレビューをその場で編集できる場合にのみフラッシュされます。 -- 返信の途中でストリーミングに失敗した場合、OpenClaw は残りのペイロードについて通常の配信にフォールバックします。 +- ネイティブストリーミングを利用できない場合、または返信スレッドが存在しない場合でも、チャンネル、グループチャット、トップレベル DM ルートは通常の下書きプレビューを使用できます。 +- トップレベルの Slack DM はデフォルトでスレッド外に留まるため、Slack のスレッド形式のネイティブストリーム/ステータスプレビューは表示されません。代わりに OpenClaw が DM に下書きプレビューを投稿して編集します。 +- メディアと非テキストペイロードは通常配信にフォールバックします。 +- メディア/エラーの最終結果は保留中のプレビュー編集をキャンセルします。対象となるテキスト/ブロックの最終結果は、プレビューをその場で編集できる場合にのみフラッシュされます。 +- 返信途中でストリーミングが失敗した場合、OpenClaw は残りのペイロードを通常配信にフォールバックします。 -Slack ネイティブテキストストリーミングの代わりに下書きプレビューを使う: +Slack ネイティブテキストストリーミングの代わりに下書きプレビューを使用します: ```json5 { @@ -696,12 +720,12 @@ Slack ネイティブテキストストリーミングの代わりに下書き レガシーキー: - `channels.slack.streamMode`（`replace | status_final | append`）は `channels.slack.streaming.mode` に自動移行されます。 -- boolean の `channels.slack.streaming` は `channels.slack.streaming.mode` と `channels.slack.streaming.nativeTransport` に自動移行されます。 +- boolean `channels.slack.streaming` は `channels.slack.streaming.mode` と `channels.slack.streaming.nativeTransport` に自動移行されます。 - レガシーの `channels.slack.nativeStreaming` は `channels.slack.streaming.nativeTransport` に自動移行されます。 -## Typing リアクションフォールバック +## タイピングリアクションのフォールバック -`typingReaction` は、OpenClaw が返信を処理している間に受信 Slack メッセージへ一時的なリアクションを追加し、実行が終了するとそれを削除します。これは、デフォルトの "is typing..." ステータスインジケーターを使うスレッド返信の外で特に役立ちます。 +`typingReaction` は、OpenClaw が返信を処理している間、受信した Slack メッセージに一時的なリアクションを追加し、実行が完了するとそれを削除します。これはデフォルトの「is typing...」ステータスインジケーターを使うスレッド返信以外で最も役立ちます。 解決順序: @@ -710,16 +734,16 @@ Slack ネイティブテキストストリーミングの代わりに下書き 注記: -- Slack はショートコード（例: `"hourglass_flowing_sand"`）を想定します。 -- リアクションはベストエフォートで、返信または失敗パスの完了後にクリーンアップが自動的に試行されます。 +- Slack はショートコードを想定します（例: `"hourglass_flowing_sand"`）。 +- リアクションはベストエフォートであり、返信または失敗パスの完了後に自動的なクリーンアップが試行されます。 -## メディア、チャンク分割、配信 +## メディア、チャンク化、配信 - Slack のファイル添付は、Slack がホストするプライベート URL（トークン認証付きリクエストフロー）からダウンロードされ、取得に成功してサイズ制限が許す場合はメディアストアに書き込まれます。ファイルプレースホルダーには Slack の `fileId` が含まれるため、エージェントは `download-file` で元のファイルを取得できます。 + Slack ファイル添付は、Slack がホストするプライベート URL（トークン認証付きリクエストフロー）からダウンロードされ、取得が成功しサイズ制限が許す場合にメディアストアへ書き込まれます。ファイルプレースホルダーには Slack の `fileId` が含まれるため、エージェントは `download-file` で元のファイルを取得できます。 - ダウンロードには、制限付きのアイドルタイムアウトと合計タイムアウトが使われます。Slack ファイルの取得が停止または失敗した場合でも、OpenClaw はメッセージの処理を継続し、ファイルプレースホルダーにフォールバックします。 + ダウンロードには、制限付きのアイドルタイムアウトと合計タイムアウトが使われます。Slack ファイル取得が停止または失敗した場合、OpenClaw はメッセージの処理を継続し、ファイルプレースホルダーにフォールバックします。 ランタイムの受信サイズ上限は、`channels.slack.mediaMaxMb` で上書きされない限り、デフォルトで `20MB` です。 @@ -728,25 +752,25 @@ Slack ネイティブテキストストリーミングの代わりに下書き - テキストチャンクは `channels.slack.textChunkLimit`（デフォルト 4000）を使います - `channels.slack.chunkMode="newline"` は段落優先の分割を有効にします - - ファイル送信は Slack アップロード API を使い、スレッド返信（`thread_ts`）を含められます - - 送信メディアの上限は、設定されている場合は `channels.slack.mediaMaxMb` に従います。それ以外の場合、チャンネル送信はメディアパイプラインの MIME 種別デフォルトを使います + - ファイル送信は Slack アップロード API を使い、スレッド返信（`thread_ts`）を含めることができます + - 送信メディア上限は、設定されている場合は `channels.slack.mediaMaxMb` に従います。それ以外の場合、チャンネル送信はメディアパイプラインの MIME 種別デフォルトを使います - - 推奨される明示的なターゲット: + + 推奨される明示的な送信先: - DM には `user:` - チャンネルには `channel:` - テキストまたはブロックのみの Slack DM はユーザー ID に直接投稿できます。ファイルアップロードとスレッド送信では具体的な会話 ID が必要なため、まず Slack 会話 API で DM を開きます。 + テキスト/ブロックのみの Slack DM はユーザー ID に直接投稿できます。ファイルアップロードとスレッド送信では、具体的な会話 ID が必要なため、まず Slack conversation API で DM を開きます。 ## コマンドとスラッシュの動作 -スラッシュコマンドは、Slack では単一の設定済みコマンド、または複数のネイティブコマンドとして表示されます。コマンドのデフォルトを変更するには、`channels.slack.slashCommand` を設定します。 +スラッシュコマンドは、Slack では単一の設定済みコマンドまたは複数のネイティブコマンドとして表示されます。コマンドのデフォルトを変更するには、`channels.slack.slashCommand` を設定します: - `enabled: false` - `name: "openclaw"` @@ -757,32 +781,32 @@ Slack ネイティブテキストストリーミングの代わりに下書き /openclaw /help ``` -ネイティブコマンドには Slack アプリで [追加のマニフェスト設定](#additional-manifest-settings) が必要で、代わりに `channels.slack.commands.native: true`、またはグローバル設定の `commands.native: true` で有効化します。 +ネイティブコマンドには Slack アプリで [追加のマニフェスト設定](#additional-manifest-settings) が必要で、代わりに `channels.slack.commands.native: true` またはグローバル設定の `commands.native: true` で有効にします。 -- Slack ではネイティブコマンドの自動モードが **オフ** のため、`commands.native: "auto"` は Slack ネイティブコマンドを有効化しません。 +- Slack ではネイティブコマンドの自動モードは **オフ** であるため、`commands.native: "auto"` は Slack ネイティブコマンドを有効にしません。 ```txt /help ``` -ネイティブ引数メニューは、選択されたオプション値をディスパッチする前に確認モーダルを表示する適応型レンダリング戦略を使います。 +ネイティブ引数メニューは、選択されたオプション値をディスパッチする前に確認モーダルを表示する適応型レンダリング戦略を使います: - 最大 5 個のオプション: ボタンブロック -- 6-100 個のオプション: 静的セレクトメニュー -- 100 個を超えるオプション: インタラクティビティオプションハンドラーが利用可能な場合、非同期オプションフィルタリング付き外部セレクト +- 6〜100 個のオプション: 静的選択メニュー +- 100 個を超えるオプション: インタラクティビティオプションハンドラーが利用可能な場合、非同期オプションフィルタリング付きの外部選択 - Slack の制限超過: エンコードされたオプション値はボタンにフォールバックします ```txt /think ``` -スラッシュセッションは `agent::slack:slash:` のような分離キーを使い、引き続き `CommandTargetSessionKey` を使ってコマンド実行をターゲット会話セッションへルーティングします。 +スラッシュセッションは `agent::slack:slash:` のような分離キーを使い、`CommandTargetSessionKey` を使って対象会話セッションへコマンド実行を引き続きルーティングします。 ## インタラクティブ返信 -Slack は、エージェントが作成したインタラクティブ返信コントロールをレンダリングできますが、この機能はデフォルトでは無効です。 +Slack はエージェント作成のインタラクティブな返信コントロールをレンダリングできますが、この機能はデフォルトで無効です。 -グローバルに有効化します。 +グローバルに有効にします: ```json5 { @@ -796,7 +820,7 @@ Slack は、エージェントが作成したインタラクティブ返信コ } ``` -または、1 つの Slack アカウントだけで有効化します。 +または、1 つの Slack アカウントだけで有効にします: ```json5 { @@ -814,29 +838,29 @@ Slack は、エージェントが作成したインタラクティブ返信コ } ``` -有効化すると、エージェントは Slack 専用の返信ディレクティブを出力できます。 +有効にすると、エージェントは Slack 専用の返信ディレクティブを出力できます: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -これらのディレクティブは Slack Block Kit にコンパイルされ、クリックや選択を既存の Slack インタラクションイベントパス経由で戻します。 +これらのディレクティブは Slack Block Kit にコンパイルされ、クリックまたは選択を既存の Slack interaction イベントパス経由でルーティングします。 注記: - これは Slack 固有の UI です。他のチャンネルは Slack Block Kit ディレクティブを独自のボタンシステムに変換しません。 - インタラクティブコールバック値は、エージェントが作成した生の値ではなく、OpenClaw が生成した不透明トークンです。 -- 生成されたインタラクティブブロックが Slack Block Kit の制限を超える場合、OpenClaw は無効なブロックペイロードを送信する代わりに、元のテキスト返信へフォールバックします。 +- 生成されたインタラクティブブロックが Slack Block Kit の制限を超える場合、OpenClaw は無効な blocks ペイロードを送信する代わりに、元のテキスト返信にフォールバックします。 ## Slack での Exec 承認 -Slack は、Web UI やターミナルへフォールバックする代わりに、インタラクティブボタンとインタラクションを備えたネイティブ承認クライアントとして機能できます。 +Slack は、Web UI やターミナルへのフォールバックの代わりに、インタラクティブボタンとインタラクションを備えたネイティブ承認クライアントとして動作できます。 -- Exec 承認は、ネイティブ DM/チャンネルルーティングに `channels.slack.execApprovals.*` を使います。 +- Exec 承認はネイティブ DM/チャンネルルーティングに `channels.slack.execApprovals.*` を使います。 - Plugin 承認は、リクエストがすでに Slack に届いていて承認 ID 種別が `plugin:` の場合、同じ Slack ネイティブボタン画面を通じて引き続き解決できます。 - 承認者の認可は引き続き強制されます。承認者として識別されたユーザーだけが、Slack 経由でリクエストを承認または拒否できます。 これは他のチャンネルと同じ共有承認ボタン画面を使います。Slack アプリ設定で `interactivity` が有効な場合、承認プロンプトは会話内に直接 Block Kit ボタンとしてレンダリングされます。 -それらのボタンが存在する場合、それらが主要な承認 UX です。OpenClaw は、ツール結果がチャット承認を利用できない、または手動承認が唯一のパスであることを示す場合にのみ、手動の `/approve` コマンドを含めるべきです。 +それらのボタンが存在する場合、それらが主要な承認 UX です。OpenClaw は、ツール結果がチャット承認は利用できない、または手動承認が唯一の経路だと示す場合に限り、手動の `/approve` コマンドを含めるべきです。 設定パス: @@ -845,9 +869,8 @@ Slack は、Web UI やターミナルへフォールバックする代わりに - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） - `agentFilter`, `sessionFilter` -Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人の -承認者が解決される場合、ネイティブ Exec 承認を自動的に有効化します。Slack をネイティブ承認クライアントとして明示的に無効化するには、`enabled: false` を設定します。 -承認者が解決される場合にネイティブ承認を強制的に有効化するには、`enabled: true` を設定します。 +Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人の承認者が解決される場合、ネイティブ Exec 承認を自動的に有効にします。Slack をネイティブ承認クライアントとして明示的に無効にするには `enabled: false` を設定します。 +承認者が解決される場合にネイティブ承認を強制的にオンにするには、`enabled: true` を設定します。 明示的な Slack Exec 承認設定がない場合のデフォルト動作: @@ -859,8 +882,7 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人 } ``` -明示的な Slack ネイティブ設定が必要なのは、承認者を上書きする、フィルターを追加する、または -送信元チャット配信にオプトインする場合だけです。 +明示的な Slack ネイティブ設定が必要なのは、承認者を上書きする、フィルターを追加する、または発信元チャットへの配信を選択する場合だけです: ```json5 { @@ -876,32 +898,32 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人 } ``` -共有 `approvals.exec` 転送は別です。Exec 承認プロンプトを他のチャットや明示的な帯域外ターゲットにもルーティングする必要がある場合にのみ使います。共有 `approvals.plugin` 転送も別です。Slack ネイティブボタンは、それらのリクエストがすでに Slack に届いている場合、引き続き Plugin 承認を解決できます。 +共有 `approvals.exec` 転送は別物です。Exec 承認プロンプトを他のチャットまたは明示的な帯域外ターゲットにもルーティングする必要がある場合にだけ使ってください。共有 `approvals.plugin` 転送も別物です。Slack ネイティブボタンは、それらのリクエストがすでに Slack に届いている場合、Plugin 承認を引き続き解決できます。 -同じチャット内の `/approve` も、すでにコマンドをサポートしている Slack チャンネルと DM で機能します。承認転送モデル全体については、[Exec 承認](/ja-JP/tools/exec-approvals) を参照してください。 +同じチャットでの `/approve` も、すでにコマンドをサポートする Slack チャンネルと DM で機能します。承認転送モデル全体については [Exec 承認](/ja-JP/tools/exec-approvals) を参照してください。 -## イベントと運用上の動作 +## イベントと運用時の動作 - メッセージの編集/削除はシステムイベントにマッピングされます。 -- スレッドブロードキャスト（「チャンネルにも送信」スレッド返信）は通常のユーザーメッセージとして処理されます。 +- スレッドブロードキャスト（「Also send to channel」スレッド返信）は通常のユーザーメッセージとして処理されます。 - リアクションの追加/削除イベントはシステムイベントにマッピングされます。 - メンバーの参加/退出、チャンネルの作成/名前変更、ピンの追加/削除イベントはシステムイベントにマッピングされます。 - `configWrites` が有効な場合、`channel_id_changed` はチャンネル設定キーを移行できます。 -- チャンネルトピック/目的メタデータは信頼できないコンテキストとして扱われ、ルーティングコンテキストに注入される可能性があります。 +- チャンネルのトピック/目的メタデータは信頼できないコンテキストとして扱われ、ルーティングコンテキストに注入されることがあります。 - スレッド開始メッセージと初期スレッド履歴コンテキストのシードは、該当する場合、設定された送信者許可リストでフィルタリングされます。 -- ブロックアクションとモーダルインタラクションは、リッチなペイロードフィールドを持つ構造化された `Slack interaction: ...` システムイベントを出力します。 +- ブロックアクションとモーダルインタラクションは、豊富なペイロードフィールドを持つ構造化された `Slack interaction: ...` システムイベントを出力します: - ブロックアクション: 選択値、ラベル、ピッカー値、`workflow_*` メタデータ - - モーダル `view_submission` と `view_closed` イベント。ルーティングされたチャンネルメタデータとフォーム入力を含みます + - ルーティングされたチャンネルメタデータとフォーム入力を含むモーダル `view_submission` および `view_closed` イベント ## 設定リファレンス -主要リファレンス: [設定リファレンス - Slack](/ja-JP/gateway/config-channels#slack)。 +主なリファレンス: [設定リファレンス - Slack](/ja-JP/gateway/config-channels#slack)。 - + - モード/認証: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - DM アクセス: `dm.enabled`, `dmPolicy`, `allowFrom`（レガシー: `dm.policy`, `dm.allowFrom`）, `dm.groupEnabled`, `dm.groupChannels` -- 互換性トグル: `dangerouslyAllowNameMatching`（緊急回避用。必要な場合を除きオフのままにしてください） +- 互換性トグル: `dangerouslyAllowNameMatching`（緊急回避用。必要な場合を除きオフのままにする） - チャンネルアクセス: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - スレッド/履歴: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - 配信: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` @@ -913,10 +935,10 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人 - 次の順に確認してください。 + 次の順に確認してください: - `groupPolicy` - - チャンネル許可リスト（`channels.slack.channels`） — **キーはチャンネル ID**（`C12345678`）である必要があり、名前（`#channel-name`）ではありません。チャンネルルーティングはデフォルトで ID 優先のため、`groupPolicy: "allowlist"` では名前ベースのキーは暗黙的に失敗します。ID を見つけるには、Slack でチャンネルを右クリック → **リンクをコピー** — URL 末尾の `C...` 値がチャンネル ID です。 + - チャンネル許可リスト（`channels.slack.channels`）— **キーはチャンネル ID**（`C12345678`）である必要があり、名前（`#channel-name`）ではありません。チャンネルルーティングはデフォルトで ID 優先のため、`groupPolicy: "allowlist"` では名前ベースのキーは静かに失敗します。ID を見つけるには、Slack でチャンネルを右クリック → **Copy link** — URL 末尾の `C...` 値がチャンネル ID です。 - `requireMention` - チャンネルごとの `users` 許可リスト @@ -931,14 +953,12 @@ openclaw doctor - 確認してください。 + 確認してください: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy`（またはレガシーの `channels.slack.dm.policy`） + - `channels.slack.dmPolicy`（またはレガシー `channels.slack.dm.policy`） - ペアリング承認 / 許可リストエントリ - - Slack Assistant DM イベント: `drop message_changed` に言及する詳細ログは、 - 通常、Slack がメッセージメタデータ内に復元可能な人間の送信者を含まない - 編集済み Assistant スレッドイベントを送信したことを意味します + - Slack Assistant DM イベント: `drop message_changed` に言及する詳細ログは、通常、メッセージメタデータ内に復元可能な人間の送信者がない編集済み Assistant スレッドイベントを Slack が送信したことを意味します ```bash openclaw pairing list slack @@ -947,28 +967,28 @@ openclaw pairing list slack - Slack アプリ設定で、ボット + アプリトークンと Socket Mode の有効化を検証してください。 + Slack アプリ設定で bot + app トークンと Socket Mode の有効化を検証してください。 `openclaw channels status --probe --json` が `botTokenStatus` または - `appTokenStatus: "configured_unavailable"` を表示する場合、その Slack アカウントは + `appTokenStatus: "configured_unavailable"` を示す場合、その Slack アカウントは 設定されていますが、現在のランタイムが SecretRef に基づく値を解決できませんでした。 - - 検証してください。 + + 検証してください: - - 署名シークレット + - signing secret - Webhook パス - - Slack リクエスト URL（Events + Interactivity + Slash Commands） - - HTTP アカウントごとに一意の `webhookPath` + - Slack Request URL（Events + Interactivity + Slash Commands） + - HTTP アカウントごとに一意な `webhookPath` - アカウントスナップショットに `signingSecretStatus: "configured_unavailable"` が表示される場合、その HTTP アカウントは設定されていますが、現在のランタイムが SecretRef に基づく署名シークレットを解決できませんでした。 + アカウントスナップショットに `signingSecretStatus: "configured_unavailable"` が表示される場合、その HTTP アカウントは設定されていますが、現在のランタイムが SecretRef に基づく signing secret を解決できませんでした。 - - どちらを意図していたか確認してください。 + + 意図していたものを確認してください: - Slack に登録された一致するスラッシュコマンドを使うネイティブコマンドモード（`channels.slack.commands.native: true`） - または単一スラッシュコマンドモード（`channels.slack.slashCommand.enabled: true`） @@ -978,62 +998,62 @@ openclaw pairing list slack -## 添付ファイルのビジョンリファレンス +## 添付ファイルの vision リファレンス -Slack ファイルのダウンロードに成功し、サイズ制限が許す場合、Slack はダウンロード済みメディアをエージェントターンに添付できます。画像ファイルはメディア理解パス経由で渡すことも、ビジョン対応の返信モデルへ直接渡すこともできます。他のファイルは、画像入力として扱われるのではなく、ダウンロード可能なファイルコンテキストとして保持されます。 +Slack ファイルのダウンロードが成功しサイズ制限が許す場合、Slack はダウンロード済みメディアをエージェントターンに添付できます。画像ファイルはメディア理解パスを通すか、vision 対応の返信モデルへ直接渡すことができます。他のファイルは画像入力として扱われるのではなく、ダウンロード可能なファイルコンテキストとして保持されます。 ### サポートされるメディアタイプ -| メディア種別 | ソース | 現在の動作 | 注記 | +| メディアタイプ | ソース | 現在の動作 | 注記 | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| JPEG / PNG / GIF / WebP 画像 | Slack ファイル URL | ダウンロードされ、ビジョン対応の処理用にターンへ添付される | ファイルごとの上限: `channels.slack.mediaMaxMb` (デフォルト 20 MB) | -| PDF ファイル | Slack ファイル URL | ダウンロードされ、`download-file` や `pdf` などのツール向けにファイルコンテキストとして公開される | Slack インバウンドは PDF を画像ビジョン入力へ自動変換しない | -| その他のファイル | Slack ファイル URL | 可能な場合はダウンロードされ、ファイルコンテキストとして公開される | バイナリファイルは画像入力として扱われない | -| スレッド返信 | スレッド開始メッセージのファイル | 返信に直接メディアがない場合、ルートメッセージのファイルをコンテキストとして取り込める | ファイルのみの開始メッセージでは添付プレースホルダーを使用する | -| 複数画像メッセージ | 複数の Slack ファイル | 各ファイルが個別に評価される | Slack の処理は 1 メッセージあたり 8 ファイルに制限される | +| JPEG / PNG / GIF / WebP 画像 | Slack ファイル URL | ダウンロードされ、ビジョン対応の処理向けにターンへ添付されます | ファイルごとの上限: `channels.slack.mediaMaxMb`（デフォルト 20 MB） | +| PDF ファイル | Slack ファイル URL | ダウンロードされ、`download-file` や `pdf` などのツール向けのファイルコンテキストとして公開されます | Slack インバウンドは PDF を画像ビジョン入力へ自動変換しません | +| その他のファイル | Slack ファイル URL | 可能な場合はダウンロードされ、ファイルコンテキストとして公開されます | バイナリファイルは画像入力として扱われません | +| スレッド返信 | スレッド開始ファイル | 返信に直接メディアがない場合、ルートメッセージのファイルをコンテキストとしてハイドレートできます | ファイルのみの開始メッセージは添付プレースホルダーを使用します | +| 複数画像メッセージ | 複数の Slack ファイル | 各ファイルは独立して評価されます | Slack 処理はメッセージごとに最大 8 ファイルまでに制限されます | ### インバウンドパイプライン -ファイル添付を含む Slack メッセージが到着した場合: +ファイル添付を含む Slack メッセージが届いた場合: -1. OpenClaw は bot トークン (`xoxb-...`) を使用して Slack のプライベート URL からファイルをダウンロードする。 -2. 成功すると、ファイルはメディアストアに書き込まれる。 -3. ダウンロードされたメディアパスとコンテンツタイプがインバウンドコンテキストに追加される。 -4. 画像対応のモデル/ツールパスは、そのコンテキストの画像添付を使用できる。 -5. 非画像ファイルは、それを処理できるツール向けにファイルメタデータまたはメディア参照として引き続き利用できる。 +1. OpenClaw は bot トークン（`xoxb-...`）を使用して、Slack のプライベート URL からファイルをダウンロードします。 +2. 成功すると、ファイルはメディアストアに書き込まれます。 +3. ダウンロードされたメディアパスとコンテンツタイプがインバウンドコンテキストに追加されます。 +4. 画像対応のモデル/ツールパスは、そのコンテキストの画像添付を使用できます。 +5. 画像以外のファイルは、それらを処理できるツール向けに、ファイルメタデータまたはメディア参照として引き続き利用できます。 ### スレッドルート添付の継承 -メッセージがスレッド内に到着した場合 (`thread_ts` の親を持つ): +メッセージがスレッド内に届いた場合（`thread_ts` 親を持つ場合）: -- 返信自体に直接メディアがなく、含まれるルートメッセージにファイルがある場合、Slack はルートファイルをスレッド開始コンテキストとして取り込める。 -- 直接の返信添付は、ルートメッセージの添付より優先される。 -- ファイルのみでテキストがないルートメッセージは、フォールバックがそのファイルを引き続き含められるように、添付プレースホルダーで表される。 +- 返信自体に直接メディアがなく、含まれているルートメッセージにファイルがある場合、Slack はルートファイルをスレッド開始コンテキストとしてハイドレートできます。 +- 直接の返信添付は、ルートメッセージ添付より優先されます。 +- ファイルのみでテキストのないルートメッセージは、フォールバックがそのファイルを引き続き含められるように、添付プレースホルダーで表されます。 ### 複数添付の処理 1 つの Slack メッセージに複数のファイル添付が含まれる場合: -- 各添付はメディアパイプラインを通じて個別に処理される。 -- ダウンロードされたメディア参照はメッセージコンテキストに集約される。 -- 処理順序はイベントペイロード内の Slack のファイル順に従う。 -- 1 つの添付のダウンロードに失敗しても、他の添付はブロックされない。 +- 各添付はメディアパイプラインを通じて独立して処理されます。 +- ダウンロードされたメディア参照は、メッセージコンテキストに集約されます。 +- 処理順序は、イベントペイロード内の Slack のファイル順序に従います。 +- 1 つの添付のダウンロード失敗は、他の添付をブロックしません。 ### サイズ、ダウンロード、モデルの制限 -- **サイズ上限**: デフォルトは 1 ファイルあたり 20 MB。`channels.slack.mediaMaxMb` で設定可能。 -- **ダウンロード失敗**: Slack が提供できないファイル、期限切れ URL、アクセス不能なファイル、サイズ超過のファイル、Slack 認証/ログイン HTML レスポンスは、未対応形式として報告されるのではなくスキップされる。 -- **ビジョンモデル**: 画像解析は、ビジョンをサポートしている場合はアクティブな返信モデルを使用し、または `agents.defaults.imageModel` で設定された画像モデルを使用する。 +- **サイズ上限**: デフォルトはファイルごとに 20 MB。`channels.slack.mediaMaxMb` で設定できます。 +- **ダウンロード失敗**: Slack が配信できないファイル、期限切れ URL、アクセス不能なファイル、サイズ超過ファイル、Slack の認証/ログイン HTML レスポンスは、未対応形式として報告されるのではなくスキップされます。 +- **ビジョンモデル**: 画像分析は、アクティブな返信モデルがビジョンをサポートする場合はそれを使用し、それ以外の場合は `agents.defaults.imageModel` に設定された画像モデルを使用します。 ### 既知の制限 -| シナリオ | 現在の動作 | 回避策 | +| シナリオ | 現在の動作 | 回避策 | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| 期限切れの Slack ファイル URL | ファイルはスキップされ、エラーは表示されない | Slack でファイルを再アップロードする | -| ビジョンモデルが設定されていない | 画像添付はメディア参照として保存されるが、画像として解析されない | `agents.defaults.imageModel` を設定するか、ビジョン対応の返信モデルを使用する | -| 非常に大きな画像 (デフォルトで > 20 MB) | サイズ上限によりスキップされる | Slack が許可する場合は `channels.slack.mediaMaxMb` を増やす | -| 転送/共有された添付 | テキストおよび Slack ホストの画像/ファイルメディアはベストエフォート | OpenClaw スレッドで直接再共有する | -| PDF 添付 | ファイル/メディアコンテキストとして保存され、画像ビジョンへ自動的にはルーティングされない | ファイルメタデータには `download-file` を使用し、PDF 解析には `pdf` ツールを使用する | +| 期限切れの Slack ファイル URL | ファイルはスキップされ、エラーは表示されません | Slack でファイルを再アップロードします | +| ビジョンモデルが設定されていない | 画像添付はメディア参照として保存されますが、画像として分析されません | `agents.defaults.imageModel` を設定するか、ビジョン対応の返信モデルを使用します | +| 非常に大きい画像（デフォルトでは 20 MB 超） | サイズ上限によりスキップされます | Slack が許可する場合は `channels.slack.mediaMaxMb` を増やします | +| 転送/共有された添付 | テキストと Slack ホストの画像/ファイルメディアはベストエフォートです | OpenClaw スレッドで直接再共有します | +| PDF 添付 | ファイル/メディアコンテキストとして保存され、画像ビジョン経由では自動的にルーティングされません | ファイルメタデータには `download-file` を使用し、PDF 分析には `pdf` ツールを使用します | ### 関連ドキュメント @@ -1046,22 +1066,22 @@ Slack ファイルのダウンロードに成功し、サイズ制限が許す ## 関連 - - Slack ユーザーを Gateway にペアリングする。 + + Slack ユーザーを Gateway にペアリングします。 - - チャンネルおよびグループ DM の動作。 + + チャネルとグループ DM の動作。 - - インバウンドメッセージをエージェントへルーティングする。 + + インバウンドメッセージをエージェントへルーティングします。 - - 脅威モデルと強化。 + + 脅威モデルと堅牢化。 - - 設定のレイアウトと優先順位。 + + 設定レイアウトと優先順位。 - + コマンドカタログと動作。 diff --git a/docs/ja-JP/channels/telegram.md b/docs/ja-JP/channels/telegram.md index ce880499a..50da5691d 100644 --- a/docs/ja-JP/channels/telegram.md +++ b/docs/ja-JP/channels/telegram.md @@ -4,33 +4,33 @@ read_when: summary: Telegram ボットのサポート状況、機能、設定 title: Telegram x-i18n: - generated_at: "2026-05-03T21:27:13Z" + generated_at: "2026-05-04T07:02:50Z" model: gpt-5.5 provider: openai - source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0 + source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6 source_path: channels/telegram.md workflow: 16 --- -本番運用に対応し、grammY 経由の bot DM とグループで利用できます。デフォルトのモードはロングポーリングです。webhook モードは任意です。 +grammY 経由のボット DM とグループで本番環境対応です。ロングポーリングが既定のモードです。Webhook モードは任意です。 - Telegram のデフォルト DM ポリシーはペアリングです。 + Telegram の既定の DM ポリシーはペアリングです。 - - チャンネル横断の診断と修復プレイブック。 + + チャネル横断の診断と修復プレイブックです。 - 完全なチャンネル設定パターンと例。 + 完全なチャネル設定パターンと例です。 ## クイックセットアップ - - Telegram を開き、**@BotFather** とチャットします（ハンドルが正確に `@BotFather` であることを確認してください）。 + + Telegram を開いて **@BotFather** とチャットします（ハンドルが正確に `@BotFather` であることを確認してください）。 `/newbot` を実行し、プロンプトに従って、トークンを保存します。 @@ -51,12 +51,12 @@ x-i18n: } ``` - env フォールバック: `TELEGRAM_BOT_TOKEN=...`（デフォルトアカウントのみ）。 - Telegram は `openclaw channels login telegram` を使用**しません**。config/env でトークンを設定してから、gateway を起動してください。 + 環境変数フォールバック: `TELEGRAM_BOT_TOKEN=...`（既定アカウントのみ）。 + Telegram は `openclaw channels login telegram` を使用しません。設定/env でトークンを構成してから、Gateway を起動してください。 - + ```bash openclaw gateway @@ -68,81 +68,81 @@ openclaw pairing approve telegram - - bot をグループに追加してから、アクセスモデルに合わせて `channels.telegram.groups` と `groupPolicy` を設定します。 + + ボットをグループに追加してから、アクセスモデルに合わせて `channels.telegram.groups` と `groupPolicy` を設定します。 -トークンの解決順序はアカウントを考慮します。実際には、config 値が env フォールバックより優先され、`TELEGRAM_BOT_TOKEN` はデフォルトアカウントにのみ適用されます。 +トークン解決順序はアカウントを考慮します。実際には、設定値が環境変数フォールバックより優先され、`TELEGRAM_BOT_TOKEN` は既定アカウントにのみ適用されます。 ## Telegram 側の設定 - Telegram bot はデフォルトで **プライバシーモード** になっており、受信できるグループメッセージが制限されます。 + Telegram ボットは既定で **プライバシーモード** になっており、受信するグループメッセージが制限されます。 - bot がすべてのグループメッセージを見る必要がある場合は、次のいずれかを行います。 + ボットがすべてのグループメッセージを確認する必要がある場合は、次のいずれかを行います。 - - `/setprivacy` でプライバシーモードを無効化する - - bot をグループ管理者にする + - `/setprivacy` でプライバシーモードを無効にする、または + - ボットをグループ管理者にする。 - プライバシーモードを切り替える場合は、各グループで bot を削除してから再追加し、Telegram に変更を適用させます。 + プライバシーモードを切り替えるときは、Telegram が変更を適用するように、各グループでボットを削除してから再追加してください。 管理者ステータスは Telegram のグループ設定で制御されます。 - 管理者 bot はすべてのグループメッセージを受信します。これは常時有効なグループ動作に便利です。 + 管理者ボットはすべてのグループメッセージを受信します。これは、常時有効なグループ動作に役立ちます。 - + - - `/setjoingroups` でグループへの追加を許可/拒否する - - `/setprivacy` でグループの可視性動作を設定する + - グループ追加を許可/拒否するには `/setjoingroups` + - グループ可視性の動作には `/setprivacy` -## アクセス制御と有効化 +## アクセス制御とアクティベーション - `channels.telegram.dmPolicy` はダイレクトメッセージのアクセスを制御します。 + `channels.telegram.dmPolicy` はダイレクトメッセージアクセスを制御します。 - - `pairing`（デフォルト） + - `pairing`（既定） - `allowlist`（`allowFrom` に少なくとも 1 つの送信者 ID が必要） - - `open`（`allowFrom` に `"*"` を含める必要がある） + - `open`（`allowFrom` に `"*"` を含める必要があります） - `disabled` - `allowFrom: ["*"]` と組み合わせた `dmPolicy: "open"` は、bot のユーザー名を見つけた、または推測した任意の Telegram アカウントが bot にコマンドを送れるようにします。意図的に公開する bot で、ツールを厳しく制限している場合にのみ使用してください。単一所有者の bot では、数値ユーザー ID を使った `allowlist` を使用してください。 + `dmPolicy: "open"` と `allowFrom: ["*"]` を組み合わせると、ボットユーザー名を見つけた、または推測した任意の Telegram アカウントがボットにコマンドを送信できます。厳しく制限されたツールを持つ意図的に公開されたボットにのみ使用してください。単一所有者のボットでは、数値ユーザー ID を指定した `allowlist` を使用するべきです。 `channels.telegram.allowFrom` は数値の Telegram ユーザー ID を受け付けます。`telegram:` / `tg:` プレフィックスは受け付けられ、正規化されます。 - 複数アカウント config では、制限的なトップレベルの `channels.telegram.allowFrom` は安全境界として扱われます。アカウントレベルの `allowFrom: ["*"]` エントリは、マージ後の有効なアカウント allowlist に明示的なワイルドカードがまだ含まれていない限り、そのアカウントを公開しません。 - 空の `allowFrom` と組み合わせた `dmPolicy: "allowlist"` はすべての DM をブロックし、config 検証で拒否されます。 + マルチアカウント設定では、制限的なトップレベルの `channels.telegram.allowFrom` は安全境界として扱われます。アカウントレベルの `allowFrom: ["*"]` エントリは、マージ後の有効なアカウント許可リストに明示的なワイルドカードがまだ含まれていない限り、そのアカウントを公開状態にはしません。 + 空の `allowFrom` を持つ `dmPolicy: "allowlist"` はすべての DM をブロックし、設定検証で拒否されます。 セットアップでは数値ユーザー ID のみを求めます。 - アップグレード後の config に `@username` allowlist エントリが含まれる場合は、`openclaw doctor --fix` を実行して解決してください（ベストエフォート。Telegram bot トークンが必要です）。 - 以前にペアリングストアの allowlist ファイルに依存していた場合、`openclaw doctor --fix` は allowlist フローで `channels.telegram.allowFrom` にエントリを復元できます（たとえば `dmPolicy: "allowlist"` に明示的な ID がまだない場合）。 + アップグレード後、設定に `@username` の許可リストエントリが含まれている場合は、`openclaw doctor --fix` を実行して解決してください（ベストエフォート。Telegram ボットトークンが必要です）。 + 以前にペアリングストアの許可リストファイルに依存していた場合、`openclaw doctor --fix` は許可リストフロー内でエントリを `channels.telegram.allowFrom` に復元できます（たとえば、`dmPolicy: "allowlist"` に明示的な ID がまだない場合）。 - 単一所有者の bot では、以前のペアリング承認に依存する代わりに、明示的な数値 `allowFrom` ID を指定した `dmPolicy: "allowlist"` を優先し、アクセスポリシーを config 内で永続化してください。 + 単一所有者のボットでは、以前のペアリング承認に依存する代わりに、明示的な数値 `allowFrom` ID を指定した `dmPolicy: "allowlist"` を推奨します。これにより、アクセスポリシーを設定内で永続化できます。 - 一般的な誤解: DM ペアリング承認は「この送信者はどこでも承認されている」という意味ではありません。 - ペアリングは DM アクセスを付与します。コマンド所有者がまだ存在しない場合、最初に承認されたペアリングは `commands.ownerAllowFrom` も設定し、所有者専用コマンドと exec 承認に明示的な操作者アカウントを持たせます。 - グループ送信者の承認は、引き続き明示的な config allowlist から取得されます。 - 「一度承認されれば DM とグループコマンドの両方が動作する」ようにしたい場合は、数値の Telegram ユーザー ID を `channels.telegram.allowFrom` に入れてください。所有者専用コマンドについては、`commands.ownerAllowFrom` に `telegram:` が含まれていることを確認してください。 + よくある混同: DM のペアリング承認は「この送信者がどこでも認可されている」という意味ではありません。 + ペアリングは DM アクセスを付与します。コマンド所有者がまだ存在しない場合、最初に承認されたペアリングは `commands.ownerAllowFrom` も設定し、所有者専用コマンドと exec 承認に明示的なオペレーターアカウントを持たせます。 + グループ送信者の認可は、引き続き明示的な設定許可リストから行われます。 + 「一度認可されれば、DM とグループコマンドの両方が機能する」ようにしたい場合は、数値の Telegram ユーザー ID を `channels.telegram.allowFrom` に入れてください。所有者専用コマンドでは、`commands.ownerAllowFrom` に `telegram:` が含まれていることを確認してください。 - ### Telegram ユーザー ID を見つける + ### Telegram ユーザー ID の確認 - より安全な方法（サードパーティ bot なし）: + より安全な方法（サードパーティボットなし）: - 1. 自分の bot に DM します。 + 1. 自分のボットに DM します。 2. `openclaw logs --follow` を実行します。 3. `from.id` を読み取ります。 - 公式 Bot API メソッド: + 公式 Bot API の方法: ```bash curl "https://api.telegram.org/bot/getUpdates" @@ -152,31 +152,31 @@ curl "https://api.telegram.org/bot/getUpdates" - - 2 つの制御が組み合わせて適用されます。 + + 2 つの制御が一緒に適用されます。 1. **許可されるグループ**（`channels.telegram.groups`） - - `groups` config なし: - - `groupPolicy: "open"` の場合: どのグループもグループ ID チェックを通過できる - - `groupPolicy: "allowlist"`（デフォルト）の場合: `groups` エントリ（または `"*"`）を追加するまでグループはブロックされる - - `groups` が設定されている場合: allowlist として動作する（明示的な ID または `"*"`） + - `groups` 設定なし: + - `groupPolicy: "open"` の場合: 任意のグループがグループ ID チェックを通過できます + - `groupPolicy: "allowlist"`（既定）の場合: `groups` エントリ（または `"*"`）を追加するまでグループはブロックされます + - `groups` が設定されている場合: 許可リストとして動作します（明示的な ID または `"*"`） 2. **グループ内で許可される送信者**（`channels.telegram.groupPolicy`） - `open` - - `allowlist`（デフォルト） + - `allowlist`（既定） - `disabled` - `groupAllowFrom` はグループ送信者フィルタリングに使用されます。設定されていない場合、Telegram は `allowFrom` にフォールバックします。 - `groupAllowFrom` エントリは数値の Telegram ユーザー ID にしてください（`telegram:` / `tg:` プレフィックスは正規化されます）。 + `groupAllowFrom` はグループ送信者のフィルタリングに使用されます。設定されていない場合、Telegram は `allowFrom` にフォールバックします。 + `groupAllowFrom` エントリは数値の Telegram ユーザー ID である必要があります（`telegram:` / `tg:` プレフィックスは正規化されます）。 Telegram グループまたはスーパーグループのチャット ID を `groupAllowFrom` に入れないでください。負のチャット ID は `channels.telegram.groups` に属します。 - 数値でないエントリは送信者承認では無視されます。 - セキュリティ境界（`2026.2.25+`）: グループ送信者認証は DM ペアリングストア承認を継承**しません**。 + 数値でないエントリは送信者認可では無視されます。 + セキュリティ境界（`2026.2.25+`）: グループ送信者の認可は DM ペアリングストア承認を継承しません。 ペアリングは DM 専用のままです。グループでは、`groupAllowFrom` またはグループごと/トピックごとの `allowFrom` を設定してください。 - `groupAllowFrom` が未設定の場合、Telegram はペアリングストアではなく config の `allowFrom` にフォールバックします。 - 単一所有者の bot 向けの実用的なパターン: 自分のユーザー ID を `channels.telegram.allowFrom` に設定し、`groupAllowFrom` は未設定のままにして、対象グループを `channels.telegram.groups` で許可します。 - ランタイム注記: `channels.telegram` が完全に存在しない場合、`channels.defaults.groupPolicy` が明示的に設定されていない限り、ランタイムは fail-closed の `groupPolicy="allowlist"` をデフォルトにします。 + `groupAllowFrom` が未設定の場合、Telegram はペアリングストアではなく、設定の `allowFrom` にフォールバックします。 + 単一所有者のボットでの実用的なパターン: 自分のユーザー ID を `channels.telegram.allowFrom` に設定し、`groupAllowFrom` は未設定のままにして、対象グループを `channels.telegram.groups` で許可します。 + ランタイムメモ: `channels.telegram` が完全に存在しない場合、`channels.defaults.groupPolicy` が明示的に設定されていない限り、ランタイムはフェイルクローズの `groupPolicy="allowlist"` を既定にします。 - 例: 1 つの特定グループ内の任意のメンバーを許可する: + 例: 特定の 1 つのグループ内の任意のメンバーを許可する: ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 例: 1 つの特定グループ内で特定ユーザーのみを許可する: + 例: 特定の 1 つのグループ内で特定のユーザーだけを許可する: ```json5 { @@ -211,22 +211,22 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - よくある間違い: `groupAllowFrom` は Telegram グループの allowlist ではありません。 + よくある間違い: `groupAllowFrom` は Telegram グループの許可リストではありません。 - `-1001234567890` のような負の Telegram グループまたはスーパーグループのチャット ID は `channels.telegram.groups` に入れます。 - - 許可されたグループ内でどの人が bot を起動できるかを制限したい場合は、`8734062810` のような Telegram ユーザー ID を `groupAllowFrom` に入れます。 - - 許可されたグループの任意のメンバーが bot と会話できるようにしたい場合にのみ、`groupAllowFrom: ["*"]` を使用します。 + - 許可されたグループ内でボットをトリガーできる人を制限したい場合は、`8734062810` のような Telegram ユーザー ID を `groupAllowFrom` に入れます。 + - 許可されたグループの任意のメンバーがボットと会話できるようにしたい場合にのみ、`groupAllowFrom: ["*"]` を使用します。 - グループ返信はデフォルトでメンションが必要です。 + グループ返信には既定でメンションが必要です。 - メンションは次から取得できます。 + メンションは次のいずれかです。 - - ネイティブの `@botusername` メンション + - ネイティブの `@botusername` メンション、または - 次のメンションパターン: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -236,9 +236,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - これらはセッション状態のみを更新します。永続化には config を使用してください。 + これらはセッション状態のみを更新します。永続化には設定を使用してください。 - 永続 config の例: + 永続設定の例: ```json5 { @@ -252,26 +252,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - グループチャット ID を取得する: + グループチャット ID の取得: - グループメッセージを `@userinfobot` / `@getidsbot` に転送する - または `openclaw logs --follow` から `chat.id` を読み取る - - または Bot API の `getUpdates` を調べる + - または Bot API の `getUpdates` を確認する ## ランタイム動作 -- Telegram は gateway プロセスが所有します。 -- ルーティングは決定的です。Telegram の受信は Telegram に返信されます（モデルがチャンネルを選ぶことはありません）。 -- 受信メッセージは、返信メタデータとメディアプレースホルダーを含む共有チャンネルエンベロープに正規化されます。 -- グループセッションはグループ ID で分離されます。フォーラムトピックは `:topic:` を追加してトピックを分離します。 -- DM メッセージは `message_thread_id` を含むことができます。OpenClaw は返信のためにスレッド ID を保持しますが、デフォルトでは DM をフラットなセッションに保ちます。意図的に DM トピックのセッション分離をしたい場合は、`channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct..threadReplies: "inbound"`、`requireTopic: true`、または一致するトピック config を設定してください。 -- ロングポーリングは grammY runner を使用し、チャットごと/スレッドごとの順序付けを行います。全体の runner sink 並行実行数は `agents.defaults.maxConcurrent` を使用します。 -- ロングポーリングは各 gateway プロセス内で保護され、同時に 1 つのアクティブな poller だけが bot トークンを使用できます。それでも `getUpdates` 409 競合が表示される場合は、別の OpenClaw gateway、スクリプト、または外部 poller が同じトークンを使用している可能性があります。 -- ロングポーリングの watchdog 再起動は、デフォルトで 120 秒間 `getUpdates` の liveness が完了しなかった場合にトリガーされます。デプロイメントで長時間実行中の作業中に誤った polling-stall 再起動がまだ発生する場合のみ、`channels.telegram.pollingStallThresholdMs` を増やしてください。値はミリ秒単位で、`30000` から `600000` まで許可されます。アカウントごとのオーバーライドがサポートされています。 -- Telegram Bot API には既読通知のサポートがありません（`sendReadReceipts` は適用されません）。 +- Telegram は Gateway プロセスが管理します。 +- ルーティングは決定論的です。Telegram からの受信は Telegram に返信されます（モデルはチャネルを選びません）。 +- 受信メッセージは、返信メタデータとメディアプレースホルダーを持つ共有チャネルエンベロープに正規化されます。 +- グループセッションはグループ ID によって分離されます。フォーラムトピックでは、トピックを分離するために `:topic:` が追加されます。 +- DM メッセージには `message_thread_id` を含めることができます。OpenClaw は返信用にスレッド ID を保持しますが、既定では DM をフラットなセッションのままにします。DM トピックのセッション分離を意図的に有効にしたい場合は、`channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct..threadReplies: "inbound"`、`requireTopic: true`、または一致するトピック設定を構成します。 +- ロングポーリングは、チャットごと/スレッドごとの順序付けを行う grammY runner を使用します。ランナーシンク全体の同時実行数は `agents.defaults.maxConcurrent` を使用します。 +- ロングポーリングは各 Gateway プロセス内でガードされるため、一度に 1 つのアクティブなポーラーだけがボットトークンを使用できます。それでも `getUpdates` の 409 競合が表示される場合は、別の OpenClaw Gateway、スクリプト、または外部ポーラーが同じトークンを使用している可能性があります。 +- ロングポーリングのウォッチドッグ再起動は、既定では完了した `getUpdates` のライブネスが 120 秒間ない場合にトリガーされます。デプロイで長時間実行される作業中に誤ったポーリング停止再起動がまだ発生する場合にのみ、`channels.telegram.pollingStallThresholdMs` を増やしてください。値はミリ秒単位で、`30000` から `600000` まで許可されます。アカウントごとの上書きがサポートされています。 +- Telegram Bot API には既読通知サポートがありません（`sendReadReceipts` は適用されません）。 ## 機能リファレンス @@ -284,12 +284,13 @@ curl "https://api.telegram.org/bot/getUpdates" 要件: - - `channels.telegram.streaming` は `off | partial | block | progress`（デフォルト: `partial`） - - `progress` は 1 つの編集可能なステータス下書きを保持し、最終配信までツール進行状況で更新します - - `streaming.preview.toolProgress` は、ツール/進行状況の更新で同じ編集済みプレビューメッセージを再利用するかを制御します（デフォルト: プレビューストリーミングが有効な場合は `true`） - - レガシーの `channels.telegram.streamMode` と boolean の `streaming` 値は検出されます。`openclaw doctor --fix` を実行して `channels.telegram.streaming.mode` に移行してください + - `channels.telegram.streaming` が `off | partial | block | progress` であること（既定: `partial`） + - `progress` は編集可能なステータス下書きを 1 つ保持し、最終配信までツール進捗で更新します + - `streaming.preview.toolProgress` は、ツール/進捗更新が同じ編集済みプレビューメッセージを再利用するかどうかを制御します（既定: プレビューストリーミングが有効な場合は `true`） + - `streaming.preview.commandText` は、それらのツール進捗行内のコマンド/exec 詳細を制御します: `raw`（既定、リリース済みの動作を保持）または `status`（ツールラベルのみ） + - 旧式の `channels.telegram.streamMode` と真偽値の `streaming` 値は検出されます。`openclaw doctor --fix` を実行して `channels.telegram.streaming.mode` に移行してください - ツール進行状況のプレビュー更新は、ツールの実行中に表示される短いステータス行です。たとえば、コマンド実行、ファイル読み取り、計画更新、パッチ要約などです。Telegram では、`v2026.4.22` 以降のリリース済み OpenClaw の動作に合わせるため、これらはデフォルトで有効です。回答テキスト用の編集済みプレビューは維持しつつ、ツール進行状況の行を非表示にするには、次を設定します。 + ツール進捗プレビュー更新は、ツール実行中に表示される短いステータス行です。たとえば、コマンド実行、ファイル読み取り、計画更新、パッチ要約などです。Telegram では、`v2026.4.22` 以降でリリースされた OpenClaw の動作に合わせるため、これらが既定で有効です。回答テキスト用の編集済みプレビューは維持しつつ、ツール進捗行を非表示にするには、次を設定します。 ```json { @@ -306,25 +307,61 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - `streaming.mode: "off"` は、最終結果のみを配信したい場合にだけ使用します。Telegram のプレビュー編集は無効になり、汎用のツール/進行状況の雑談は単独のステータスメッセージとして送信される代わりに抑制されます。承認プロンプト、メディアペイロード、エラーは引き続き通常の最終配信を通じてルーティングされます。回答プレビュー編集だけを維持し、ツール進行状況のステータス行を非表示にしたい場合は、`streaming.preview.toolProgress: false` を使用します。 + ツール進捗は表示したまま、コマンド/exec テキストを非表示にするには、次を設定します。 + + ```json + { + "channels": { + "telegram": { + "streaming": { + "mode": "partial", + "preview": { + "commandText": "status" + } + } + } + } + } + ``` + + 進行状況ドラフトモードでは、同じコマンドテキストポリシーを `streaming.progress` の下に置きます。 + + ```json + { + "channels": { + "telegram": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } + } + ``` + + 最終結果のみの配信が必要な場合にだけ `streaming.mode: "off"` を使用します。Telegram のプレビュー編集は無効になり、汎用的なツールや進行状況の雑談は、独立したステータスメッセージとして送信される代わりに抑制されます。承認プロンプト、メディアペイロード、エラーは引き続き通常の最終配信経路を通ります。回答プレビュー編集だけを維持し、ツール進行状況のステータス行を隠したい場合は `streaming.preview.toolProgress: false` を使用します。 - Telegram の選択引用返信は例外です。`replyToMode` が `"first"`、`"all"`、または `"batched"` で、受信メッセージに選択された引用テキストが含まれる場合、OpenClaw は回答プレビューを編集する代わりに Telegram のネイティブ引用返信経路で最終回答を送信するため、そのターンでは `streaming.preview.toolProgress` で短いステータス行を表示できません。選択引用テキストのない現在メッセージへの返信では、引き続きプレビューストリーミングが維持されます。ツール進行状況の可視性がネイティブ引用返信より重要な場合は `replyToMode: "off"` を設定するか、このトレードオフを受け入れるために `streaming.preview.toolProgress: false` を設定します。 + Telegram の選択引用返信は例外です。`replyToMode` が `"first"`、`"all"`、または `"batched"` で、受信メッセージに選択された引用テキストが含まれている場合、OpenClaw は回答プレビューを編集する代わりに、Telegram のネイティブな引用返信経路で最終回答を送信します。そのため、そのターンでは `streaming.preview.toolProgress` で短いステータス行を表示できません。選択引用テキストのない現在メッセージへの返信では、引き続きプレビューストリーミングが維持されます。ツール進行状況の可視性がネイティブ引用返信より重要な場合は `replyToMode: "off"` を設定するか、トレードオフを明示的に受け入れるために `streaming.preview.toolProgress: false` を設定します。 テキストのみの返信の場合: - - 短い DM/グループ/トピックのプレビュー: OpenClaw は同じプレビューメッセージを維持し、プレビューが表示された後に可視の非プレビューメッセージが送信されていない限り、最終編集をその場で実行します - - 可視の非プレビュー出力が続くプレビュー: OpenClaw は完了した返信を新しい最終メッセージとして送信し、古いプレビューをクリーンアップするため、最終回答は中間出力の後に表示されます + - 短いDM/グループ/トピックのプレビュー: プレビューが表示された後に可視の非プレビューメッセージが送信されていない限り、OpenClaw は同じプレビューメッセージを保持し、その場で最終編集を行います + - プレビューの後に可視の非プレビュー出力が続く場合: OpenClaw は完了した返信を新しい最終メッセージとして送信し、古いプレビューをクリーンアップするため、最終回答は中間出力の後に表示されます - 約1分より古いプレビュー: OpenClaw は完了した返信を新しい最終メッセージとして送信してからプレビューをクリーンアップするため、Telegram の可視タイムスタンプはプレビュー作成時刻ではなく完了時刻を反映します 複雑な返信（たとえばメディアペイロード）の場合、OpenClaw は通常の最終配信にフォールバックし、その後プレビューメッセージをクリーンアップします。 - プレビューストリーミングはブロックストリーミングとは別です。Telegram でブロックストリーミングが明示的に有効になっている場合、OpenClaw は二重ストリーミングを避けるためにプレビューストリームをスキップします。 + プレビューストリーミングはブロックストリーミングとは別です。Telegram でブロックストリーミングが明示的に有効化されている場合、OpenClaw は二重ストリーミングを避けるためにプレビューストリームをスキップします。 Telegram 専用の推論ストリーム: - `/reasoning stream` は生成中に推論をライブプレビューへ送信します + - 推論プレビューは最終配信後に削除されます。推論を表示したままにする必要がある場合は `/reasoning on` を使用します - 最終回答は推論テキストなしで送信されます @@ -332,22 +369,22 @@ curl "https://api.telegram.org/bot/getUpdates" 送信テキストは Telegram `parse_mode: "HTML"` を使用します。 - - Markdown 風のテキストは Telegram で安全な HTML にレンダリングされます。 - - 生のモデル HTML は、Telegram の解析失敗を減らすためにエスケープされます。 - - Telegram が解析済み HTML を拒否した場合、OpenClaw はプレーンテキストとして再試行します。 + - Markdown 風のテキストは Telegram で安全なHTMLにレンダリングされます。 + - 生のモデルHTMLは、Telegram の解析失敗を減らすためにエスケープされます。 + - Telegram が解析済みHTMLを拒否した場合、OpenClaw はプレーンテキストで再試行します。 - リンクプレビューはデフォルトで有効で、`channels.telegram.linkPreview: false` で無効にできます。 + リンクプレビューはデフォルトで有効で、`channels.telegram.linkPreview: false` で無効化できます。 - Telegram コマンドメニュー登録は、起動時に `setMyCommands` で処理されます。 + Telegram コマンドメニュー登録は起動時に `setMyCommands` で処理されます。 ネイティブコマンドのデフォルト: - `commands.native: "auto"` は Telegram のネイティブコマンドを有効にします - カスタムコマンドメニュー項目を追加します: + カスタムコマンドメニュー項目を追加します。 ```json5 { @@ -371,17 +408,17 @@ curl "https://api.telegram.org/bot/getUpdates" 注記: - - カスタムコマンドはメニュー項目のみです。動作を自動実装するものではありません + - カスタムコマンドはメニュー項目のみです。動作を自動実装しません - plugin/skill コマンドは、Telegram メニューに表示されていなくても、入力された場合は引き続き動作できます - ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。カスタム/plugin コマンドは、設定されていれば引き続き登録される場合があります。 + ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。設定されていれば、カスタム/plugin コマンドは引き続き登録される場合があります。 - よくあるセットアップ失敗: + 一般的なセットアップ失敗: - - `BOT_COMMANDS_TOO_MUCH` を伴う `setMyCommands failed` は、トリミング後も Telegram メニューがまだあふれていることを意味します。plugin/skill/カスタムコマンドを減らすか、`channels.telegram.commands.native` を無効にしてください。 - - 直接の Bot API curl コマンドは動作するのに、`deleteWebhook`、`deleteMyCommands`、または `setMyCommands` が `404: Not Found` で失敗する場合、`channels.telegram.apiRoot` が完全な `/bot` エンドポイントに設定されている可能性があります。`apiRoot` は Bot API ルートのみである必要があり、`openclaw doctor --fix` は誤って付いた末尾の `/bot` を削除します。 - - `getMe returned 401` は、Telegram が設定済みの bot トークンを拒否したことを意味します。`botToken`、`tokenFile`、または `TELEGRAM_BOT_TOKEN` を現在の BotFather トークンで更新してください。OpenClaw はポーリング前に停止するため、これは Webhook クリーンアップ失敗としては報告されません。 - - ネットワーク/フェッチエラーを伴う `setMyCommands failed` は、通常 `api.telegram.org` への送信 DNS/HTTPS がブロックされていることを意味します。 + - `setMyCommands failed` と `BOT_COMMANDS_TOO_MUCH` が表示される場合、トリミング後も Telegram メニューがまだ上限を超えていることを意味します。plugin/skill/カスタムコマンドを減らすか、`channels.telegram.commands.native` を無効化してください。 + - 直接の Bot API curl コマンドは動作するのに、`deleteWebhook`、`deleteMyCommands`、または `setMyCommands` が `404: Not Found` で失敗する場合、`channels.telegram.apiRoot` が完全な `/bot` エンドポイントに設定されている可能性があります。`apiRoot` は Bot API ルートだけである必要があり、`openclaw doctor --fix` は誤って末尾に付いた `/bot` を削除します。 + - `getMe returned 401` は、Telegram が設定済みのボットトークンを拒否したことを意味します。`botToken`、`tokenFile`、または `TELEGRAM_BOT_TOKEN` を現在の BotFather トークンで更新してください。OpenClaw はポーリング前に停止するため、これは Webhook クリーンアップ失敗としては報告されません。 + - `setMyCommands failed` とネットワーク/fetch エラーが表示される場合、通常は `api.telegram.org` への送信DNS/HTTPSがブロックされていることを意味します。 ### デバイスペアリングコマンド（`device-pair` plugin） @@ -389,22 +426,22 @@ curl "https://api.telegram.org/bot/getUpdates" 1. `/pair` はセットアップコードを生成します 2. iOS アプリにコードを貼り付けます - 3. `/pair pending` は保留中のリクエストを一覧表示します（ロール/スコープを含む） + 3. `/pair pending` は保留中のリクエスト（ロール/スコープを含む）を一覧表示します 4. リクエストを承認します: - 明示的な承認には `/pair approve ` - - 保留中のリクエストが1つだけの場合は `/pair approve` + - 保留中のリクエストが1件だけの場合は `/pair approve` - 最新のものには `/pair approve latest` - セットアップコードには短命のブートストラップトークンが含まれます。組み込みのブートストラップ引き渡しでは、プライマリノードトークンは `scopes: []` に維持されます。引き渡された operator トークンは、`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write` に制限されたままです。ブートストラップのスコープチェックはロール接頭辞付きであるため、その operator 許可リストは operator リクエストのみを満たします。operator 以外のロールでは、引き続き各自のロール接頭辞配下のスコープが必要です。 + セットアップコードには短命のブートストラップトークンが含まれます。組み込みのブートストラップ引き渡しでは、プライマリノードトークンは `scopes: []` に保たれます。引き渡されたオペレータートークンは `operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write` に制限されます。ブートストラップスコープチェックはロール接頭辞付きのため、そのオペレーター許可リストはオペレーターリクエストのみを満たします。非オペレーターロールには、引き続きそれぞれのロール接頭辞配下のスコープが必要です。 - デバイスが変更された認証詳細（たとえばロール/スコープ/公開鍵）で再試行した場合、以前の保留中リクエストは置き換えられ、新しいリクエストでは別の `requestId` が使用されます。承認する前に `/pair pending` を再実行してください。 + デバイスが変更された認証詳細（たとえばロール/スコープ/公開鍵）で再試行した場合、以前の保留中リクエストは置き換えられ、新しいリクエストでは別の `requestId` が使用されます。承認前に `/pair pending` を再実行してください。 詳細: [ペアリング](/ja-JP/channels/pairing#pair-via-telegram-recommended-for-ios)。 - インラインキーボードのスコープを設定します: + インラインキーボードのスコープを設定します。 ```json5 { @@ -469,8 +506,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Telegram ツールアクションには次が含まれます: + + Telegram ツールアクションには次が含まれます。 - `sendMessage`（`to`、`content`、任意の `mediaUrl`、`replyToMessageId`、`messageThreadId`） - `react`（`chatId`、`messageId`、`emoji`） @@ -478,9 +515,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage`（`chatId`、`messageId`、`content`） - `createForumTopic`（`chatId`、`name`、任意の `iconColor`、`iconCustomEmojiId`） - チャネルメッセージアクションは、使いやすいエイリアス（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）を公開します。 + チャンネルメッセージアクションは使いやすいエイリアス（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）を公開します。 - ゲーティング制御: + ゲート制御: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` @@ -488,27 +525,27 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker`（デフォルト: 無効） 注記: `edit` と `topic-create` は現在デフォルトで有効で、個別の `channels.telegram.actions.*` トグルはありません。 - ランタイム送信はアクティブな config/secrets スナップショット（起動/リロード）を使用するため、アクションパスは送信ごとにアドホックな SecretRef 再解決を行いません。 + ランタイム送信はアクティブな設定/シークレットのスナップショット（起動/リロード）を使用するため、アクションパスは送信ごとにアドホックな SecretRef 再解決を行いません。 - リアクション削除のセマンティクス: [/tools/reactions](/ja-JP/tools/reactions) + リアクション削除セマンティクス: [/tools/reactions](/ja-JP/tools/reactions) - - Telegram は、生成された出力内の明示的な返信スレッドタグをサポートします: + + Telegram は、生成された出力内の明示的な返信スレッド化タグをサポートします。 - `[[reply_to_current]]` はトリガー元メッセージに返信します - - `[[reply_to:]]` は特定の Telegram メッセージ ID に返信します + - `[[reply_to:]]` は特定の Telegram メッセージIDに返信します - `channels.telegram.replyToMode` は処理を制御します: + `channels.telegram.replyToMode` は処理を制御します。 - `off`（デフォルト） - `first` - `all` - 返信スレッドが有効で、元の Telegram テキストまたはキャプションが利用可能な場合、OpenClaw はネイティブ Telegram 引用抜粋を自動的に含めます。Telegram はネイティブ引用テキストを 1024 UTF-16 コードユニットに制限するため、より長いメッセージは先頭から引用され、Telegram が引用を拒否した場合はプレーンな返信にフォールバックします。 + 返信スレッド化が有効で、元の Telegram テキストまたはキャプションが利用可能な場合、OpenClaw はネイティブ Telegram 引用抜粋を自動的に含めます。Telegram はネイティブ引用テキストを1024 UTF-16コードユニットに制限するため、より長いメッセージは先頭から引用され、Telegram が引用を拒否した場合はプレーンな返信にフォールバックします。 - 注記: `off` は暗黙的な返信スレッドを無効にします。明示的な `[[reply_to_*]]` タグは引き続き尊重されます。 + 注記: `off` は暗黙的な返信スレッド化を無効化します。明示的な `[[reply_to_*]]` タグは引き続き尊重されます。 @@ -517,18 +554,18 @@ curl "https://api.telegram.org/bot/getUpdates" - トピックセッションキーは `:topic:` を追加します - 返信と入力中表示はトピックスレッドを対象にします - - トピック config パス: + - トピック設定パス: `channels.telegram.groups..topics.` - 一般トピック（`threadId=1`）の特別扱い: + 一般トピック（`threadId=1`）の特例: - メッセージ送信では `message_thread_id` を省略します（Telegram は `sendMessage(...thread_id=1)` を拒否します） - - 入力中アクションでは引き続き `message_thread_id` を含めます + - 入力中アクションには引き続き `message_thread_id` が含まれます - トピック継承: トピック項目は、上書きされない限りグループ設定（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）を継承します。 - `agentId` はトピック専用で、グループのデフォルトからは継承されません。 + トピックの継承: トピック項目は、上書きされない限りグループ設定（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）を継承します。 + `agentId` はトピック専用で、グループデフォルトから継承されません。 - **トピックごとのエージェントルーティング**: 各トピックは、トピック config で `agentId` を設定することで別のエージェントにルーティングできます。これにより、各トピックに独自の分離されたワークスペース、メモリ、セッションが与えられます。例: + **トピックごとのエージェントルーティング**: 各トピックは、トピック設定で `agentId` を設定することで別のエージェントへルーティングできます。これにより、各トピックは独自の分離されたワークスペース、メモリ、セッションを持てます。例: ```json5 { @@ -548,24 +585,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 各トピックはそれぞれ独自のセッションキーを持ちます: `agent:zu:telegram:group:-1001234567890:topic:3` + その後、各トピックは独自のセッションキーを持ちます: `agent:zu:telegram:group:-1001234567890:topic:3` - **永続 ACP トピックバインディング**: フォーラムトピックは、トップレベルの型付き ACP バインディング（`type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`、および `-1001234567890:topic:42` のようなトピック修飾 ID を持つ `bindings[]`）を通じて ACP ハーネスセッションをピン留めできます。現在はグループ/スーパーグループ内のフォーラムトピックにスコープされています。[ACP エージェント](/ja-JP/tools/acp-agents)を参照してください。 + **永続的な ACP トピックバインディング**: フォーラムトピックは、トップレベルの型付き ACP バインディング（`type: "acp"` と `match.channel: "telegram"`、`peer.kind: "group"`、および `-1001234567890:topic:42` のようなトピック修飾IDを持つ `bindings[]`）を通じて ACP ハーネスセッションを固定できます。現在はグループ/スーパーグループ内のフォーラムトピックにスコープされています。[ACP エージェント](/ja-JP/tools/acp-agents)を参照してください。 - **チャットからのスレッド束縛 ACP spawn**: `/acp spawn --thread here|auto` は現在のトピックを新しい ACP セッションにバインドし、後続メッセージはそこへ直接ルーティングされます。OpenClaw は spawn 確認をトピック内にピン留めします。`channels.telegram.threadBindings.spawnSessions` が有効なままである必要があります（デフォルト: `true`）。 + **チャットからのスレッドバインド ACP spawn**: `/acp spawn --thread here|auto` は現在のトピックを新しい ACP セッションにバインドします。以後のやり取りはそこへ直接ルーティングされます。OpenClaw は spawn 確認をトピック内に固定します。`channels.telegram.threadBindings.spawnSessions` が有効のままである必要があります（デフォルト: `true`）。 - テンプレートコンテキストは `MessageThreadId` と `IsForum` を公開します。`message_thread_id` を持つ DM チャットは、デフォルトではフラットセッション上の DM ルーティングと返信メタデータを維持します。`threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true`、または一致するトピック config が設定されている場合にのみ、スレッド対応セッションキーを使用します。アカウントのデフォルトにはトップレベルの `channels.telegram.dm.threadReplies` を、単一の DM には `direct..threadReplies` を使用します。 + テンプレートコンテキストは `MessageThreadId` と `IsForum` を公開します。`message_thread_id` を持つ DM チャットは、デフォルトでフラットセッション上の DM ルーティングと返信メタデータを維持します。`threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true`、または一致するトピック設定が構成されている場合にのみ、スレッド対応のセッションキーを使用します。アカウントのデフォルトにはトップレベルの `channels.telegram.dm.threadReplies` を、1 つの DM には `direct..threadReplies` を使用します。 ### 音声メッセージ - Telegram はボイスメモと音声ファイルを区別します。 + Telegram は音声メモと音声ファイルを区別します。 - デフォルト: 音声ファイルの動作 - - エージェント返信内のタグ `[[audio_as_voice]]` はボイスメモ送信を強制します - - 受信ボイスメモの文字起こしは、エージェントコンテキスト内で機械生成の信頼できないテキストとして枠付けされます。メンション検出では引き続き生の文字起こしを使用するため、メンションでゲートされた音声メッセージは動作し続けます。 + - エージェント返信内のタグ `[[audio_as_voice]]` で音声メモ送信を強制 + - 受信した音声メモの文字起こしは、エージェントコンテキスト内で機械生成の + 信頼できないテキストとしてフレーム化されます。メンション検出は引き続き生の + 文字起こしを使用するため、メンションで制御された音声メッセージは動作し続けます。 メッセージアクションの例: @@ -581,7 +620,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### 動画メッセージ - Telegram は動画ファイルとビデオノートを区別します。 + Telegram は動画ファイルと動画メモを区別します。 メッセージアクションの例: @@ -595,15 +634,15 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - ビデオノートはキャプションに対応していません。指定されたメッセージテキストは別途送信されます。 + 動画メモはキャプションをサポートしません。指定されたメッセージテキストは別送されます。 ### ステッカー 受信ステッカーの処理: - - 静的 WEBP: ダウンロードして処理されます（プレースホルダー ``） - - アニメーション TGS: スキップされます - - 動画 WEBM: スキップされます + - 静的 WEBP: ダウンロードして処理（プレースホルダー ``） + - アニメーション TGS: スキップ + - 動画 WEBM: スキップ ステッカーコンテキストフィールド: @@ -619,7 +658,7 @@ curl "https://api.telegram.org/bot/getUpdates" ステッカーは（可能な場合）一度だけ説明され、繰り返しのビジョン呼び出しを減らすためにキャッシュされます。 - ステッカーアクションを有効にします: + ステッカーアクションを有効化: ```json5 { @@ -644,7 +683,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - キャッシュされたステッカーを検索します: + キャッシュ済みステッカーを検索: ```json5 { @@ -660,7 +699,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram のリアクションは `message_reaction` 更新として届きます（メッセージペイロードとは別です）。 - 有効な場合、OpenClaw は次のようなシステムイベントをキューに入れます: + 有効化すると、OpenClaw は次のようなシステムイベントをキューに入れます。 - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` @@ -669,19 +708,19 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.reactionNotifications`: `off | own | all`（デフォルト: `own`） - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（デフォルト: `minimal`） - 注: + 注記: - - `own` は、ボットが送信したメッセージに対するユーザーのリアクションのみを意味します（送信済みメッセージキャッシュによるベストエフォート）。 - - リアクションイベントは引き続き Telegram のアクセス制御（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）に従います。許可されていない送信者は破棄されます。 + - `own` はボットが送信したメッセージへのユーザーリアクションのみを意味します（送信メッセージキャッシュによるベストエフォート）。 + - リアクションイベントは引き続き Telegram のアクセス制御（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）を尊重します。許可されていない送信者は破棄されます。 - Telegram はリアクション更新でスレッド ID を提供しません。 - - 非フォーラムグループはグループチャットセッションにルーティングされます - - フォーラムグループは、正確な発生元トピックではなく、グループの一般トピックセッション（`:topic:1`）にルーティングされます + - 非フォーラムグループはグループチャットセッションへルーティング + - フォーラムグループは、正確な発生元トピックではなく、グループの一般トピックセッション（`:topic:1`）へルーティング ポーリング/Webhook の `allowed_updates` には `message_reaction` が自動的に含まれます。 - + `ackReaction` は、OpenClaw が受信メッセージを処理している間に確認用の絵文字を送信します。 解決順序: @@ -691,17 +730,17 @@ curl "https://api.telegram.org/bot/getUpdates" - `messages.ackReaction` - エージェント ID の絵文字フォールバック（`agents.list[].identity.emoji`、なければ "👀"） - 注: + 注記: - - Telegram は Unicode 絵文字（例: "👀"）を想定します。 - - チャンネルまたはアカウントでリアクションを無効にするには `""` を使用します。 + - Telegram は Unicode 絵文字（例: "👀"）を想定しています。 + - チャンネルまたはアカウントでリアクションを無効化するには `""` を使用します。 チャンネル設定の書き込みはデフォルトで有効です（`configWrites !== false`）。 - Telegram からトリガーされる書き込みには次が含まれます: + Telegram によってトリガーされる書き込みには次が含まれます。 - `channels.telegram.groups` を更新するためのグループ移行イベント（`migrate_to_chat_id`） - `/config set` と `/config unset`（コマンドの有効化が必要） @@ -721,38 +760,38 @@ curl "https://api.telegram.org/bot/getUpdates" - デフォルトはロングポーリングです。Webhook モードでは `channels.telegram.webhookUrl` と `channels.telegram.webhookSecret` を設定します。任意で `webhookPath`、`webhookHost`、`webhookPort`（デフォルトは `/telegram-webhook`、`127.0.0.1`、`8787`）を設定できます。 + デフォルトはロングポーリングです。Webhook モードでは `channels.telegram.webhookUrl` と `channels.telegram.webhookSecret` を設定します。任意で `webhookPath`、`webhookHost`、`webhookPort`（デフォルトは `/telegram-webhook`、`127.0.0.1`、`8787`）も設定できます。 - ローカルリスナーは `127.0.0.1:8787` にバインドします。公開イングレスでは、ローカルポートの前にリバースプロキシを置くか、意図的に `webhookHost: "0.0.0.0"` を設定します。 + ローカルリスナーは `127.0.0.1:8787` にバインドします。公開入口には、ローカルポートの前段にリバースプロキシを置くか、意図的に `webhookHost: "0.0.0.0"` を設定します。 - Webhook モードは、Telegram に `200` を返す前にリクエストガード、Telegram シークレットトークン、JSON 本文を検証します。 - その後 OpenClaw は、ロングポーリングで使われるものと同じチャット別/トピック別のボットレーンを通じて更新を非同期に処理するため、遅いエージェントターンが Telegram の配信 ACK を保持しません。 + Webhook モードは、Telegram に `200` を返す前に、リクエストガード、Telegram シークレットトークン、JSON 本文を検証します。 + その後 OpenClaw は、ロングポーリングで使われるものと同じチャット単位/トピック単位のボットレーンを通じて更新を非同期に処理するため、遅いエージェントターンが Telegram の配信 ACK を保持しません。 - `channels.telegram.textChunkLimit` のデフォルトは 4000 です。 - `channels.telegram.chunkMode="newline"` は、長さで分割する前に段落境界（空行）を優先します。 - - `channels.telegram.mediaMaxMb`（デフォルト 100）は、受信および送信の Telegram メディアサイズを制限します。 - - `channels.telegram.mediaGroupFlushMs`（デフォルト 500）は、OpenClaw が Telegram のアルバム/メディアグループを 1 つの受信メッセージとしてディスパッチする前にバッファする時間を制御します。アルバムの一部が遅れて到着する場合は増やし、アルバム返信のレイテンシを減らすには減らします。 - - `channels.telegram.timeoutSeconds` は Telegram API クライアントのタイムアウトを上書きします（未設定の場合は grammY のデフォルトが適用されます）。ボットクライアントは、設定値が 60 秒の送信テキスト/タイピングリクエストガード未満の場合、その値をクランプするため、OpenClaw のトランスポートガードとフォールバックが実行される前に grammY が可視返信の配信を中止しません。ロングポーリングは引き続き 45 秒の `getUpdates` リクエストガードを使用するため、アイドル状態のポーリングが無期限に放棄されることはありません。 - - `channels.telegram.pollingStallThresholdMs` のデフォルトは `120000` です。ポーリング停止の誤検知による再起動の場合のみ、`30000` から `600000` の範囲で調整してください。 + - `channels.telegram.mediaMaxMb`（デフォルト 100）は、受信および送信 Telegram メディアのサイズ上限を設定します。 + - `channels.telegram.mediaGroupFlushMs`（デフォルト 500）は、OpenClaw が Telegram のアルバム/メディアグループを 1 つの受信メッセージとしてディスパッチする前に、どれだけバッファするかを制御します。アルバムの一部が遅れて届く場合は増やし、アルバム返信のレイテンシを下げるには減らします。 + - `channels.telegram.timeoutSeconds` は Telegram API クライアントのタイムアウトを上書きします（未設定の場合は grammY のデフォルトが適用されます）。ボットクライアントは、構成値が 60 秒の送信テキスト/タイピングリクエストガードを下回る場合にクランプするため、OpenClaw のトランスポートガードとフォールバックが実行される前に grammY が表示される返信配信を中止しません。ロングポーリングでは、アイドルポーリングが無期限に放棄されないように、引き続き 45 秒の `getUpdates` リクエストガードを使用します。 + - `channels.telegram.pollingStallThresholdMs` のデフォルトは `120000` です。ポーリング停止の誤検知による再起動の場合のみ、`30000` から `600000` の間で調整してください。 - グループコンテキスト履歴は `channels.telegram.historyLimit` または `messages.groupChat.historyLimit`（デフォルト 50）を使用します。`0` で無効化します。 - - 返信/引用/転送の補足コンテキストは、現在は受信したまま渡されます。 - - Telegram の許可リストは主に、完全な補足コンテキスト編集境界ではなく、誰がエージェントをトリガーできるかを制御します。 + - 返信/引用/転送の補足コンテキストは、現時点では受信したまま渡されます。 + - Telegram の許可リストは主に、完全な補足コンテキストの秘匿境界ではなく、誰がエージェントをトリガーできるかを制御します。 - DM 履歴制御: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` 設定は、回復可能な送信 API エラーに対して Telegram 送信ヘルパー（CLI/ツール/アクション）に適用されます。受信の最終返信配信も、Telegram の接続前障害に対して境界付きの安全送信再試行を使用しますが、可視メッセージを重複させる可能性がある送信後の曖昧なネットワークエンベロープは再試行しません。 + - `channels.telegram.retry` 設定は、回復可能な送信 API エラーに対する Telegram 送信ヘルパー（CLI/ツール/アクション）に適用されます。受信した最終返信の配信も、Telegram の接続前失敗に対して制限付きの安全な送信再試行を使用しますが、表示メッセージを重複させる可能性のある送信後の曖昧なネットワークエンベロープは再試行しません。 - CLI 送信ターゲットには数値のチャット ID またはユーザー名を使用できます: + CLI 送信ターゲットには数値チャット ID またはユーザー名を指定できます。 ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Telegram ポーリングは `openclaw message poll` を使用し、フォーラムトピックに対応しています: + Telegram ポーリングは `openclaw message poll` を使用し、フォーラムトピックをサポートします。 ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -762,57 +801,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Telegram 専用のポーリングフラグ: + Telegram 専用ポーリングフラグ: - `--poll-duration-seconds`（5-600） - `--poll-anonymous` - `--poll-public` - フォーラムトピック用の `--thread-id`（または `:topic:` ターゲットを使用） - Telegram 送信は次にも対応しています: + Telegram 送信は次もサポートします。 - - `channels.telegram.capabilities.inlineButtons` が許可している場合、インラインキーボード用の `buttons` ブロックを含む `--presentation` - - ボットがそのチャットでピン留めできる場合、ピン留め配信を要求する `--pin` または `--delivery '{"pin":true}'` - - 送信画像と GIF を、圧縮された写真またはアニメーションメディアアップロードではなく、ドキュメントとして送信する `--force-document` + - `channels.telegram.capabilities.inlineButtons` が許可する場合、インラインキーボード用の `buttons` ブロックを含む `--presentation` + - ボットがそのチャットでピン留めできる場合に、ピン留め配信を要求する `--pin` または `--delivery '{"pin":true}'` + - 送信画像と GIF を、圧縮写真またはアニメーションメディアアップロードではなくドキュメントとして送信する `--force-document` アクション制御: - - `channels.telegram.actions.sendMessage=false` は、ポーリングを含む送信 Telegram メッセージを無効にします - - `channels.telegram.actions.poll=false` は、通常の送信を有効にしたまま Telegram ポーリング作成を無効にします + - `channels.telegram.actions.sendMessage=false` は、ポーリングを含む送信 Telegram メッセージを無効化します + - `channels.telegram.actions.poll=false` は、通常の送信を有効のまま、Telegram ポーリング作成を無効化します - Telegram は承認者の DM で exec 承認に対応し、任意で元のチャットまたはトピックにプロンプトを投稿できます。承認者は数値の Telegram ユーザー ID である必要があります。 + Telegram は承認者 DM で exec 承認をサポートし、任意で発生元のチャットまたはトピックにもプロンプトを投稿できます。承認者は数値の Telegram ユーザー ID である必要があります。 設定パス: - - `channels.telegram.execApprovals.enabled`（少なくとも 1 人の承認者が解決可能な場合に自動有効化） + - `channels.telegram.execApprovals.enabled`（少なくとも 1 人の承認者を解決できる場合に自動有効化） - `channels.telegram.execApprovals.approvers`（`commands.ownerAllowFrom` の数値オーナー ID にフォールバック） - - `channels.telegram.execApprovals.target`: `dm`（デフォルト）| `channel` | `both` - - `agentFilter`、`sessionFilter` + - `channels.telegram.execApprovals.target`: `dm`（デフォルト） | `channel` | `both` + - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`、`groupAllowFrom`、`defaultTo` は、誰がボットに話しかけられるか、通常の返信をどこへ送るかを制御します。これらは誰かを exec 承認者にするものではありません。コマンドオーナーがまだ存在しない場合、最初に承認された DM ペアリングが `commands.ownerAllowFrom` をブートストラップするため、1 オーナー構成でも `execApprovals.approvers` に ID を重複して記載せずに動作します。 + `channels.telegram.allowFrom`、`groupAllowFrom`、`defaultTo` は、誰がボットと会話できるか、および通常の返信をどこへ送るかを制御します。誰かを exec 承認者にするものではありません。コマンドオーナーがまだ存在しない場合、最初に承認された DM ペアリングが `commands.ownerAllowFrom` をブートストラップするため、1 オーナー構成でも `execApprovals.approvers` に ID を重複して設定せずに動作します。 - チャンネル配信ではコマンドテキストがチャットに表示されます。信頼できるグループ/トピックでのみ `channel` または `both` を有効にしてください。プロンプトがフォーラムトピックに届いた場合、OpenClaw は承認プロンプトとフォローアップのトピックを保持します。exec 承認はデフォルトで 30 分後に期限切れになります。 + チャンネル配信ではチャット内にコマンドテキストが表示されます。`channel` または `both` は信頼できるグループ/トピックでのみ有効化してください。プロンプトがフォーラムトピックに届いた場合、OpenClaw は承認プロンプトとフォローアップのトピックを保持します。exec 承認はデフォルトで 30 分後に期限切れになります。 - インライン承認ボタンでは、`channels.telegram.capabilities.inlineButtons` が対象サーフェス（`dm`、`group`、または `all`）を許可していることも必要です。`plugin:` プレフィックス付きの承認 ID は Plugin 承認を通じて解決され、それ以外はまず exec 承認を通じて解決されます。 + インライン承認ボタンも、`channels.telegram.capabilities.inlineButtons` が対象サーフェス（`dm`、`group`、または `all`）を許可している必要があります。`plugin:` 接頭辞付きの承認 ID は Plugin 承認を通じて解決され、それ以外はまず exec 承認を通じて解決されます。 [Exec 承認](/ja-JP/tools/exec-approvals)を参照してください。 -## エラー返信の制御 +## エラー返信制御 -エージェントで配信エラーまたはプロバイダーエラーが発生した場合、Telegram はエラーテキストで返信するか、それを抑制できます。この動作は 2 つの設定キーで制御します: +エージェントが配信エラーまたはプロバイダーエラーに遭遇した場合、Telegram はエラーテキストで返信するか、それを抑制できます。この動作は 2 つの設定キーで制御します。 -| キー | 値 | デフォルト | 説明 | -| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` はチャットにわかりやすいエラーメッセージを送信します。`silent` はエラー返信を完全に抑制します。 | -| `channels.telegram.errorCooldownMs` | 数値 (ms) | `60000` | 同じチャットへのエラー返信間の最小時間です。障害中のエラースパムを防ぎます。 | +| キー | 値 | デフォルト | 説明 | +| ----------------------------------- | ----------------- | ---------- | ---------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` はチャットに親しみやすいエラーメッセージを送信します。`silent` はエラー返信を完全に抑制します。 | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 同じチャットへのエラー返信間の最小時間。障害中のエラースパムを防ぎます。 | -アカウント別、グループ別、トピック別の上書きに対応しています（他の Telegram 設定キーと同じ継承）。 +アカウント単位、グループ単位、トピック単位の上書きがサポートされています（他の Telegram 設定キーと同じ継承）。 ```json5 { @@ -833,56 +872,56 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## トラブルシューティング - + - - `requireMention=false` の場合、Telegram のプライバシーモードで完全な可視性を許可する必要があります。 + - `requireMention=false` の場合、Telegram プライバシーモードは完全な可視性を許可する必要があります。 - BotFather: `/setprivacy` -> Disable - - その後、ボットをグループから削除して再追加します + - その後、ボットをグループから削除して再追加 - 設定がメンションなしのグループメッセージを想定している場合、`openclaw channels status` が警告します。 - - `openclaw channels status --probe` は明示的な数値グループ ID を確認できます。ワイルドカード `"*"` はメンバーシップのプローブができません。 + - `openclaw channels status --probe` は明示的な数値グループ ID を確認できます。ワイルドカード `"*"` はメンバーシッププローブできません。 - 簡易セッションテスト: `/activation always`。 - + - - `channels.telegram.groups` が存在する場合、グループが一覧に含まれている必要があります（または `"*"` を含めます） - - グループ内のボットメンバーシップを確認します + - `channels.telegram.groups` が存在する場合、group は列挙されている必要があります（または `"*"` を含めます） + - group 内の bot メンバーシップを確認します - スキップ理由についてログを確認します: `openclaw logs --follow` - - 送信者 ID を承認します（ペアリングおよび/または数値の `allowFrom`） - - グループポリシーが `open` の場合でも、コマンド承認は引き続き適用されます - - `BOT_COMMANDS_TOO_MUCH` を伴う `setMyCommands failed` は、ネイティブメニューのエントリが多すぎることを意味します。Plugin/Skill/カスタムコマンドを減らすか、ネイティブメニューを無効にしてください - - `deleteMyCommands` / `setMyCommands` の起動時呼び出しと `sendChatAction` のタイピング呼び出しは境界付きで、リクエストタイムアウト時に Telegram のトランスポートフォールバックを通じて 1 回再試行します。永続的なネットワーク/fetch エラーは通常、`api.telegram.org` への DNS/HTTPS 到達性の問題を示します + - 送信者 ID を認可します（ペアリングまたは数値の `allowFrom`） + - group ポリシーが `open` の場合でも、コマンド認可は適用されます + - `BOT_COMMANDS_TOO_MUCH` を伴う `setMyCommands failed` は、ネイティブメニューの項目が多すぎることを意味します。Plugin/スキル/カスタムコマンドを減らすか、ネイティブメニューを無効にしてください + - 起動時の `deleteMyCommands` / `setMyCommands` 呼び出しと、入力中を示す `sendChatAction` 呼び出しは、範囲が制限され、リクエストのタイムアウト時には Telegram のトランスポートフォールバック経由で 1 回再試行されます。永続的なネットワーク/フェッチエラーは通常、`api.telegram.org` への DNS/HTTPS 到達性の問題を示します - + - - `getMe returned 401` は、設定済みボットトークンに対する Telegram 認証失敗です。 - - BotFather でボットトークンを再コピーまたは再生成してから、デフォルトアカウントの `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken`、または `TELEGRAM_BOT_TOKEN` を更新します。 - - 起動中の `deleteWebhook 401 Unauthorized` も認証失敗です。これを「Webhook が存在しない」として扱っても、同じ不正なトークンによる失敗が後続の API 呼び出しまで先送りされるだけです。 + - `getMe returned 401` は、設定済み bot トークンに対する Telegram 認証失敗です。 + - BotFather で bot トークンを再コピーまたは再生成し、デフォルトアカウントの `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken`、または `TELEGRAM_BOT_TOKEN` を更新します。 + - 起動中の `deleteWebhook 401 Unauthorized` も認証失敗です。これを「webhook は存在しない」と扱うと、同じ不正なトークンによる失敗を後続の API 呼び出しまで先送りするだけです。 - + - - Node 22+ とカスタム fetch/proxy の組み合わせでは、AbortSignal 型が一致しない場合に即時中断動作が発生することがあります。 - - 一部のホストは `api.telegram.org` を先に IPv6 へ解決します。IPv6 送信が壊れていると、Telegram API が断続的に失敗することがあります。 - - ログに `TypeError: fetch failed` または `Network request for 'getUpdates' failed!` が含まれる場合、OpenClaw はこれらを復旧可能なネットワークエラーとして再試行するようになりました。 - - ポーリング起動中、OpenClaw は成功した起動時の `getMe` プローブを grammY に再利用するため、ランナーは最初の `getUpdates` 前に 2 回目の `getMe` を必要としません。 - - ポーリング起動中に `deleteWebhook` が一時的なネットワークエラーで失敗した場合、OpenClaw は別の事前ポーリング制御プレーン呼び出しを行わず、ロングポーリングに進みます。まだアクティブな Webhook がある場合は `getUpdates` の競合として表面化し、その後 OpenClaw は Telegram トランスポートを再構築して Webhook クリーンアップを再試行します。 - - Telegram ソケットが短い固定間隔でリサイクルされる場合は、低い `channels.telegram.timeoutSeconds` が設定されていないか確認してください。ボットクライアントは、送信リクエストと `getUpdates` リクエストのガード値を下回る設定値をクランプしますが、古いリリースではこの値がそれらのガード値を下回っていると、すべてのポーリングまたは返信が中断されることがありました。 - - ログに `Polling stall detected` が含まれる場合、OpenClaw はデフォルトで、完了したロングポールの生存確認が 120 秒間ないと、ポーリングを再起動し Telegram トランスポートを再構築します。 - - `openclaw channels status --probe` と `openclaw doctor` は、実行中のポーリングアカウントが起動猶予後に `getUpdates` を完了していない場合、実行中の Webhook アカウントが起動猶予後に `setWebhook` を完了していない場合、または最後に成功したポーリングトランスポート活動が古い場合に警告します。 - - 長時間実行される `getUpdates` 呼び出しが健全であるにもかかわらず、ホストが誤ったポーリング停止再起動を報告する場合にのみ、`channels.telegram.pollingStallThresholdMs` を増やしてください。継続的な停止は通常、ホストと `api.telegram.org` の間の proxy、DNS、IPv6、または TLS 送信の問題を示します。 - - Telegram は Bot API トランスポートについて、`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` とそれらの小文字バリアントを含むプロセス proxy 環境変数も尊重します。`NO_PROXY` / `no_proxy` は引き続き `api.telegram.org` をバイパスできます。 - - サービス環境で OpenClaw 管理 proxy が `OPENCLAW_PROXY_URL` を通じて設定されており、標準 proxy 環境変数が存在しない場合、Telegram も Bot API トランスポートにその URL を使用します。 - - 直接の送信/TLS が不安定な VPS ホストでは、Telegram API 呼び出しを `channels.telegram.proxy` 経由でルーティングします。 + - Node 22+ とカスタム fetch/proxy の組み合わせでは、AbortSignal 型が一致しない場合に即時 abort 動作が発生することがあります。 + - 一部のホストは `api.telegram.org` を IPv6 優先で解決します。壊れた IPv6 外向き通信により、Telegram API が断続的に失敗することがあります。 + - ログに `TypeError: fetch failed` または `Network request for 'getUpdates' failed!` が含まれる場合、OpenClaw はこれらを回復可能なネットワークエラーとして再試行するようになっています。 + - ポーリング起動中、OpenClaw は成功した起動時の `getMe` プローブを grammY に再利用するため、runner は最初の `getUpdates` の前に 2 回目の `getMe` を必要としません。 + - ポーリング起動中に `deleteWebhook` が一時的なネットワークエラーで失敗した場合、OpenClaw は別の事前ポーリング control-plane 呼び出しを行わずに long polling へ進みます。webhook がまだ有効な場合は `getUpdates` の競合として表面化し、その後 OpenClaw は Telegram トランスポートを再構築して webhook クリーンアップを再試行します。 + - Telegram ソケットが短い固定間隔でリサイクルされる場合は、`channels.telegram.timeoutSeconds` が低くないか確認してください。bot クライアントは、外向き通信と `getUpdates` リクエストのガード値を下回る設定値をクランプしますが、古いリリースではこの値がそれらのガード値を下回っていると、すべてのポーリングまたは返信が abort されることがありました。 + - ログに `Polling stall detected` が含まれる場合、OpenClaw はデフォルトで、完了した long-poll liveness が 120 秒ないとポーリングを再起動し、Telegram トランスポートを再構築します。 + - `openclaw channels status --probe` と `openclaw doctor` は、実行中のポーリングアカウントが起動猶予後に `getUpdates` を完了していない場合、実行中の webhook アカウントが起動猶予後に `setWebhook` を完了していない場合、または最後に成功したポーリングトランスポート活動が古い場合に警告します。 + - 長時間実行される `getUpdates` 呼び出しが正常にもかかわらず、ホストがポーリング停止の誤検知による再起動を報告する場合にのみ、`channels.telegram.pollingStallThresholdMs` を増やしてください。永続的な停止は通常、ホストと `api.telegram.org` 間の proxy、DNS、IPv6、または TLS 外向き通信の問題を示します。 + - Telegram は Bot API トランスポートについて、`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` とそれらの小文字バリアントを含むプロセスの proxy 環境変数も尊重します。`NO_PROXY` / `no_proxy` は引き続き `api.telegram.org` をバイパスできます。 + - サービス環境で OpenClaw 管理 proxy が `OPENCLAW_PROXY_URL` によって設定され、標準の proxy 環境変数が存在しない場合、Telegram は Bot API トランスポートにもその URL を使用します。 + - 直接の外向き通信/TLS が不安定な VPS ホストでは、Telegram API 呼び出しを `channels.telegram.proxy` 経由でルーティングします: ```yaml channels: @@ -890,8 +929,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ はデフォルトで `autoSelectFamily=true` です（WSL2 を除く）。Telegram DNS 結果の順序は、`OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、次に `channels.telegram.network.dnsResultOrder`、次に `NODE_OPTIONS=--dns-result-order=ipv4first` のようなプロセス既定値に従います。いずれも適用されない場合、Node 22+ は `ipv4first` にフォールバックします。 - - ホストが WSL2 である場合、または IPv4 のみの動作の方が明示的にうまく機能する場合は、ファミリー選択を強制します。 + - Node 22+ はデフォルトで `autoSelectFamily=true` です（WSL2 を除く）。Telegram DNS 結果の順序は、`OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、次に `channels.telegram.network.dnsResultOrder`、次に `NODE_OPTIONS=--dns-result-order=ipv4first` などのプロセスデフォルトに従います。いずれも適用されない場合、Node 22+ は `ipv4first` にフォールバックします。 + - ホストが WSL2 の場合、または IPv4 のみの動作の方が明示的にうまく機能する場合は、family 選択を強制します: ```yaml channels: @@ -900,7 +939,7 @@ channels: autoSelectFamily: false ``` - - RFC 2544 ベンチマーク範囲の応答（`198.18.0.0/15`）は、デフォルトで Telegram メディアダウンロードに対してすでに許可されています。信頼済みの fake-IP または透過 proxy が、メディアダウンロード中に `api.telegram.org` を別のプライベート/内部/特殊用途アドレスへ書き換える場合は、Telegram 専用バイパスを有効にできます。 + - RFC 2544 ベンチマーク範囲の応答（`198.18.0.0/15`）は、デフォルトで Telegram メディアダウンロードについてすでに許可されています。信頼済みの fake-IP または透過 proxy が、メディアダウンロード中に `api.telegram.org` をその他の private/internal/special-use アドレスへ書き換える場合は、Telegram 専用のバイパスを有効にできます: ```yaml channels: @@ -909,26 +948,24 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 同じオプトインは、アカウントごとに + - 同じ opt-in はアカウントごとに `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` でも利用できます。 - proxy が Telegram メディアホストを `198.18.x.x` に解決する場合は、まず - 危険なフラグをオフのままにしてください。Telegram メディアはデフォルトで RFC 2544 - ベンチマーク範囲をすでに許可しています。 + 危険なフラグをオフのままにしてください。Telegram メディアはデフォルトで + RFC 2544 ベンチマーク範囲をすでに許可しています。 `channels.telegram.network.dangerouslyAllowPrivateNetwork` は Telegram - メディアの SSRF 保護を弱めます。Clash、Mihomo、Surge fake-IP ルーティングのように、 - RFC 2544 ベンチマーク範囲外のプライベートまたは特殊用途の応答を合成する、 - 信頼済みの運用者管理 proxy 環境でのみ使用してください。通常のパブリックインターネット経由の - Telegram アクセスではオフのままにしてください。 + メディアの SSRF 保護を弱めます。Clash、Mihomo、Surge の fake-IP ルーティングのように、RFC 2544 ベンチマーク範囲外の private または special-use 応答を合成する、信頼済みのオペレーター管理 proxy + 環境でのみ使用してください。通常の public internet Telegram アクセスではオフのままにしてください。 - 環境オーバーライド（一時的）: - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - DNS 応答を検証します。 + - DNS 応答を検証します: ```bash dig +short api.telegram.org A @@ -938,24 +975,24 @@ dig +short api.telegram.org AAAA -詳細ヘルプ: [チャンネルのトラブルシューティング](/ja-JP/channels/troubleshooting)。 +詳細ヘルプ: [Channel トラブルシューティング](/ja-JP/channels/troubleshooting)。 ## 設定リファレンス 主要リファレンス: [設定リファレンス - Telegram](/ja-JP/gateway/config-channels#telegram)。 - + - 起動/認証: `enabled`, `botToken`, `tokenFile`, `accounts.*`（`tokenFile` は通常ファイルを指している必要があります。シンボリックリンクは拒否されます） - アクセス制御: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, トップレベルの `bindings[]`（`type: "acp"`） -- 実行承認: `execApprovals`, `accounts.*.execApprovals` +- exec 承認: `execApprovals`, `accounts.*.execApprovals` - コマンド/メニュー: `commands.native`, `commands.nativeSkills`, `customCommands` - スレッド/返信: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` - ストリーミング: `streaming`（プレビュー）, `streaming.preview.toolProgress`, `blockStreaming` -- 書式/配信: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` +- フォーマット/配信: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - メディア/ネットワーク: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` - カスタム API ルート: `apiRoot`（Bot API ルートのみ。`/bot` は含めないでください） -- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - アクション/機能: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - リアクション: `reactionNotifications`, `reactionLevel` - エラー: `errorPolicy`, `errorCooldownMs` @@ -964,7 +1001,7 @@ dig +short api.telegram.org AAAA -マルチアカウントの優先順位: 2 つ以上のアカウント ID が設定されている場合は、`channels.telegram.defaultAccount` を設定する（または `channels.telegram.accounts.default` を含める）ことで、デフォルトルーティングを明示してください。そうでない場合、OpenClaw は最初の正規化済みアカウント ID にフォールバックし、`openclaw doctor` が警告します。名前付きアカウントは `channels.telegram.allowFrom` / `groupAllowFrom` を継承しますが、`accounts.default.*` 値は継承しません。 +マルチアカウントの優先順位: 2 つ以上のアカウント ID が設定されている場合、デフォルトルーティングを明示するために `channels.telegram.defaultAccount` を設定します（または `channels.telegram.accounts.default` を含めます）。それ以外の場合、OpenClaw は最初に正規化されたアカウント ID にフォールバックし、`openclaw doctor` が警告します。名前付きアカウントは `channels.telegram.allowFrom` / `groupAllowFrom` を継承しますが、`accounts.default.*` の値は継承しません。 ## 関連 @@ -973,19 +1010,19 @@ dig +short api.telegram.org AAAA Telegram ユーザーを Gateway にペアリングします。 - - グループとトピックの許可リスト動作。 + + group と topic の allowlist 動作。 - - 受信メッセージをエージェントにルーティングします。 + + 受信メッセージを agents にルーティングします。 - 脅威モデルと堅牢化。 + 脅威モデルと強化。 - グループとトピックをエージェントにマッピングします。 + group と topic を agents にマッピングします。 - チャンネル横断の診断。 + Channel 横断の診断。 diff --git a/docs/ja-JP/cli/sessions.md b/docs/ja-JP/cli/sessions.md index ff70d8997..dbaa47c78 100644 --- a/docs/ja-JP/cli/sessions.md +++ b/docs/ja-JP/cli/sessions.md @@ -1,13 +1,13 @@ --- read_when: - - 保存済みセッションを一覧表示し、最近のアクティビティを確認したい場合 -summary: '`openclaw sessions` のコマンドラインリファレンス（保存済みセッションの一覧表示 + 使用方法）' + - 保存済みセッションを一覧表示し、最近のアクティビティを確認したい +summary: '`openclaw sessions` の CLI リファレンス（保存済みセッションの一覧表示 + 使用方法）' title: セッション x-i18n: - generated_at: "2026-05-02T20:44:10Z" + generated_at: "2026-05-04T07:02:53Z" model: gpt-5.5 provider: openai - source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f + source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e source_path: cli/sessions.md workflow: 16 --- @@ -16,7 +16,9 @@ x-i18n: 保存済みの会話セッションを一覧表示します。 -セッション一覧は、チャンネル/プロバイダーの稼働状況チェックではありません。セッションストアから永続化済みの会話行を表示します。静かな Discord、Slack、Telegram、またはその他のチャンネルは、メッセージが処理されるまで新しいセッション行を作成せずに正常に再接続できます。ライブのチャンネル接続性が必要な場合は、`openclaw channels status --probe`、`openclaw status --deep`、または `openclaw health --verbose` を使用してください。 +セッション一覧は、チャンネルやプロバイダーの稼働状況チェックではありません。セッションストアから永続化された会話行を表示します。静かな Discord、Slack、Telegram、またはその他のチャンネルは、新しいセッション行を作成しなくても、メッセージが処理されるまで正常に再接続できます。ライブのチャンネル接続性が必要な場合は、`openclaw channels status --probe`、`openclaw status --deep`、または `openclaw health --verbose` を使用してください。 + +Gateway の `sessions.list` レスポンスはデフォルトで制限されているため、大規模で長期間存続するストアが Gateway のイベントループを占有することはありません。別の結果ウィンドウが必要な場合は、RPC クライアントから明示的に正の `limit` を渡してください。呼び出し元がさらに行が存在することを示す必要がある場合、レスポンスには `totalCount`、`limitApplied`、`hasMore` が含まれます。 ```bash openclaw sessions @@ -31,9 +33,9 @@ openclaw sessions --json - デフォルト: 設定済みのデフォルトエージェントストア - `--verbose`: 詳細ログ -- `--agent `: 1 つの設定済みエージェントストア -- `--all-agents`: すべての設定済みエージェントストアを集約 -- `--store `: 明示的なストアパス（`--agent` または `--all-agents` と併用不可） +- `--agent `: 設定済みエージェントストア 1 つ +- `--all-agents`: 設定済みのすべてのエージェントストアを集約 +- `--store `: 明示的なストアパス（`--agent` または `--all-agents` と組み合わせることはできません） 保存済みセッションの軌跡バンドルをエクスポートします: @@ -42,9 +44,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json ``` -これは、所有者が exec リクエストを承認した後に `/export-trajectory` スラッシュコマンドで使用されるコマンドパスです。出力ディレクトリは、選択されたワークスペース配下の `.openclaw/trajectory-exports/` 内に常に解決されます。 +これは、所有者が実行リクエストを承認した後に `/export-trajectory` スラッシュコマンドで使用されるコマンドパスです。出力ディレクトリは常に、選択されたワークスペース配下の `.openclaw/trajectory-exports/` 内に解決されます。 -`openclaw sessions --all-agents` は設定済みエージェントストアを読み取ります。Gateway と ACP のセッション検出はより広範です。デフォルトの `agents/` ルート、またはテンプレート化された `session.store` ルート配下で見つかったディスク上のみのストアも含まれます。検出されたストアは、エージェントルート内の通常の `sessions.json` ファイルに解決される必要があります。シンボリックリンクとルート外パスはスキップされます。 +`openclaw sessions --all-agents` は設定済みエージェントストアを読み取ります。Gateway と ACP のセッション検出はより広範です。デフォルトの `agents/` ルートまたはテンプレート化された `session.store` ルート配下で見つかった、ディスク上にのみ存在するストアも含まれます。検出されたストアは、エージェントルート内の通常の `sessions.json` ファイルに解決される必要があります。シンボリックリンクとルート外のパスはスキップされます。 JSON の例: @@ -67,9 +69,9 @@ JSON の例: } ``` -## クリーンアップメンテナンス +## クリーンアップ保守 -次の書き込みサイクルを待たずに、今すぐメンテナンスを実行します: +次の書き込みサイクルを待たずに、今すぐ保守を実行します: ```bash openclaw sessions cleanup --dry-run @@ -82,19 +84,19 @@ openclaw sessions cleanup --json `openclaw sessions cleanup` は設定の `session.maintenance` 設定を使用します: -- スコープメモ: `openclaw sessions cleanup` はセッションストア、トランスクリプト、軌跡サイドカーをメンテナンスします。Cron 実行ログ（`cron/runs/.jsonl`）は剪定しません。これらは [Cron 設定](/ja-JP/automation/cron-jobs#configuration) の `cron.runLog.maxBytes` と `cron.runLog.keepLines` によって管理され、[Cron メンテナンス](/ja-JP/automation/cron-jobs#maintenance) で説明されています。 +- スコープの注記: `openclaw sessions cleanup` は、セッションストア、トランスクリプト、軌跡サイドカーを保守します。cron 実行ログ（`cron/runs/.jsonl`）は削除しません。これは [Cron 設定](/ja-JP/automation/cron-jobs#configuration) の `cron.runLog.maxBytes` と `cron.runLog.keepLines` によって管理され、[Cron 保守](/ja-JP/automation/cron-jobs#maintenance) で説明されています。 -- `--dry-run`: 書き込みを行わずに、何件のエントリが剪定/上限適用されるかをプレビューします。 - - テキストモードでは、ドライランはセッションごとのアクション表（`Action`、`Key`、`Age`、`Model`、`Flags`）を出力するため、保持されるものと削除されるものを確認できます。 -- `--enforce`: `session.maintenance.mode` が `warn` の場合でもメンテナンスを適用します。 -- `--fix-missing`: トランスクリプトファイルが欠落しているエントリを、通常はまだ経過時間/件数の対象外であっても削除します。 -- `--active-key `: 特定のアクティブキーをディスク容量制限による退避から保護します。グループセッションやスレッドスコープのチャットセッションなど、永続的な外部会話ポインターも、経過時間/件数/ディスク容量制限メンテナンスで保持されます。 -- `--agent `: 1 つの設定済みエージェントストアに対してクリーンアップを実行します。 -- `--all-agents`: すべての設定済みエージェントストアに対してクリーンアップを実行します。 +- `--dry-run`: 書き込みを行わずに、削除または上限制限されるエントリ数をプレビューします。 + - テキストモードでは、dry-run はセッションごとのアクションテーブル（`Action`、`Key`、`Age`、`Model`、`Flags`）を出力するため、保持されるものと削除されるものを確認できます。 +- `--enforce`: `session.maintenance.mode` が `warn` の場合でも保守を適用します。 +- `--fix-missing`: トランスクリプトファイルが見つからないエントリを、通常ならまだ経過時間や件数の条件から外れない場合でも削除します。 +- `--active-key `: 特定のアクティブキーをディスク容量予算による退避から保護します。グループセッションやスレッド単位のチャットセッションなど、永続的な外部会話ポインターも、経過時間、件数、ディスク容量予算による保守で保持されます。 +- `--agent `: 設定済みエージェントストア 1 つに対してクリーンアップを実行します。 +- `--all-agents`: 設定済みのすべてのエージェントストアに対してクリーンアップを実行します。 - `--store `: 特定の `sessions.json` ファイルに対して実行します。 -- `--json`: JSON サマリーを出力します。`--all-agents` の場合、出力にはストアごとに 1 つのサマリーが含まれます。 +- `--json`: JSON サマリーを出力します。`--all-agents` を指定した場合、出力にはストアごとのサマリーが含まれます。 -Gateway に到達できる場合、設定済みエージェントストアの非ドライランクリーンアップは Gateway 経由で送信されるため、実行時トラフィックと同じセッションストア書き込み側を共有します。ストアファイルを明示的にオフライン修復する場合は `--store ` を使用してください。 +Gateway に到達できる場合、設定済みエージェントストアに対する dry-run ではないクリーンアップは Gateway 経由で送信されるため、ランタイムトラフィックと同じセッションストアライターを共有します。ストアファイルを明示的にオフライン修復するには `--store ` を使用してください。 `openclaw sessions cleanup --all-agents --dry-run --json`: diff --git a/docs/ja-JP/concepts/messages.md b/docs/ja-JP/concepts/messages.md index 2bf9f0c40..305830cac 100644 --- a/docs/ja-JP/concepts/messages.md +++ b/docs/ja-JP/concepts/messages.md @@ -2,21 +2,21 @@ read_when: - 受信メッセージが返信になる仕組みを説明する - セッション、キューイングモード、またはストリーミング動作の明確化 - - 推論の可視性と利用上の影響を文書化 + - 推論の可視性と使用上の影響の文書化 summary: メッセージフロー、セッション、キューイング、推論の可視性 title: メッセージ x-i18n: - generated_at: "2026-04-30T16:28:01Z" + generated_at: "2026-05-04T07:03:08Z" model: gpt-5.5 provider: openai - source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9 + source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f source_path: concepts/messages.md workflow: 16 --- -OpenClaw は、セッション解決、キューイング、ストリーミング、ツール実行、推論の可視性というパイプラインを通じて受信メッセージを処理します。このページでは、受信メッセージから返信までの経路を示します。 +OpenClaw は、セッション解決、キューイング、ストリーミング、ツール実行、推論の可視性からなるパイプラインで受信メッセージを処理します。このページでは、受信メッセージから返信までの経路を示します。 -## メッセージフロー (高レベル) +## メッセージフロー（高レベル） ``` Inbound message @@ -28,21 +28,21 @@ Inbound message 主要な調整項目は設定内にあります。 -- `messages.*`: プレフィックス、キューイング、グループ動作。 -- `agents.defaults.*`: ブロックストリーミングとチャンク化のデフォルト。 -- チャネルの上書き (`channels.whatsapp.*`、`channels.telegram.*` など): 上限とストリーミングの切り替え。 +- 接頭辞、キューイング、グループ動作には `messages.*`。 +- ブロックストリーミングとチャンク化のデフォルトには `agents.defaults.*`。 +- 上限とストリーミングの切り替えには、チャンネルごとの上書き（`channels.whatsapp.*`、`channels.telegram.*` など）。 完全なスキーマについては [設定](/ja-JP/gateway/configuration) を参照してください。 -## 受信重複排除 +## 受信の重複排除 -チャネルは再接続後に同じメッセージを再配信することがあります。OpenClaw は、チャネル/アカウント/ピア/セッション/メッセージ ID をキーにした短命のキャッシュを保持し、重複配信によって別のエージェント実行が起動しないようにします。 +チャンネルは、再接続後に同じメッセージを再配信することがあります。OpenClaw は、チャンネル/アカウント/ピア/セッション/メッセージ ID をキーとする短期間のキャッシュを保持し、重複配信が別のエージェント実行を起動しないようにします。 -## 受信デバウンス +## 受信のデバウンス -**同じ送信者**からの連続した短時間のメッセージは、`messages.inbound` によって単一のエージェントターンにまとめることができます。デバウンスはチャネル + 会話ごとにスコープされ、返信スレッド/ID には最新のメッセージを使用します。 +**同じ送信者**からの短時間の連続メッセージは、`messages.inbound` によって単一のエージェントターンにまとめられます。デバウンスはチャンネル + 会話単位でスコープされ、返信スレッド/ID には最新のメッセージが使用されます。 -設定 (グローバルデフォルト + チャネルごとの上書き): +設定（グローバルデフォルト + チャンネルごとの上書き）: ```json5 { @@ -62,77 +62,77 @@ Inbound message 注: - デバウンスは**テキストのみ**のメッセージに適用されます。メディア/添付ファイルは即座にフラッシュされます。 -- 制御コマンドは単独のままになるようデバウンスをバイパスします。ただし、チャネルが同一送信者の DM 結合を明示的に有効にしている場合は**例外**です (例: [BlueBubbles `coalesceSameSenderDms`](/ja-JP/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition))。この場合、分割送信ペイロードが同じエージェントターンに合流できるよう、DM コマンドはデバウンス期間内で待機します。 +- 制御コマンドはデバウンスをバイパスするため単独のままです。ただし、チャンネルが同一送信者 DM の結合を明示的に有効にしている場合（例: [BlueBubbles `coalesceSameSenderDms`](/ja-JP/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)）は**例外**で、DM コマンドは分割送信されたペイロードが同じエージェントターンに合流できるように、デバウンス期間内で待機します。 ## セッションとデバイス セッションはクライアントではなく Gateway が所有します。 -- ダイレクトチャットはエージェントのメインセッションキーにまとめられます。 -- グループ/チャネルには固有のセッションキーが割り当てられます。 -- セッションストアとトランスクリプトは Gateway ホスト上に存在します。 +- ダイレクトチャットはエージェントのメインセッションキーに集約されます。 +- グループ/チャンネルは独自のセッションキーを持ちます。 +- セッションストアとトランスクリプトは Gateway ホスト上にあります。 -複数のデバイス/チャネルを同じセッションに対応付けることはできますが、履歴がすべてのクライアントへ完全に同期されるわけではありません。推奨: 長い会話では文脈の分岐を避けるため、主デバイスを 1 つ使用してください。Control UI と TUI は常に Gateway に裏付けられたセッショントランスクリプトを表示するため、これらが信頼できる情報源です。 +複数のデバイス/チャンネルを同じセッションにマッピングできますが、履歴はすべてのクライアントに完全には同期されません。推奨事項: 長い会話では、コンテキストの分岐を避けるために 1 つの主要デバイスを使用してください。Control UI と TUI は常に Gateway が保持するセッショントランスクリプトを表示するため、これらが信頼できる情報源です。 詳細: [セッション管理](/ja-JP/concepts/session)。 ## ツール結果メタデータ -ツール結果の `content` はモデルに見える結果です。ツール結果の `details` は、UI レンダリング、診断、メディア配信、Plugin 用のランタイムメタデータです。 +ツール結果の `content` はモデルに見える結果です。ツール結果の `details` は、UI レンダリング、診断、メディア配信、Plugin のためのランタイムメタデータです。 -OpenClaw はその境界を明示的に保ちます。 +OpenClaw はこの境界を明示的に保ちます。 -- `toolResult.details` はプロバイダー再生と Compaction 入力の前に取り除かれます。 -- 永続化されたセッショントランスクリプトには、境界内の `details` のみが保持されます。過大なメタデータは、`persistedDetailsTruncated: true` とマークされたコンパクトな要約に置き換えられます。 -- Plugin とツールは、モデルが読む必要のあるテキストを `details` だけでなく `content` に入れる必要があります。 +- `toolResult.details` は、プロバイダーの再生と Compaction 入力の前に取り除かれます。 +- 永続化されたセッショントランスクリプトは、制限された `details` のみを保持します。過大なメタデータは、`persistedDetailsTruncated: true` とマークされたコンパクトな要約に置き換えられます。 +- Plugin とツールは、モデルが読む必要のあるテキストを `details` のみに入れるのではなく、`content` に入れるべきです。 ## 受信本文と履歴コンテキスト OpenClaw は**プロンプト本文**と**コマンド本文**を分離します。 -- `BodyForAgent`: 現在のメッセージについて、主にモデル向けとなるテキスト。チャネル Plugin は、送信者の現在のプロンプトを含むテキストにこれを集中させる必要があります。 -- `Body`: レガシーのプロンプトフォールバック。これにはチャネルエンベロープや任意の履歴ラッパーが含まれる場合がありますが、現在のチャネルは `BodyForAgent` が利用可能な場合、主要なモデル入力としてこれに依存するべきではありません。 +- `BodyForAgent`: 現在のメッセージに対する、主なモデル向けテキスト。チャンネル Plugin は、これを送信者の現在のプロンプトを含むテキストに集中させるべきです。 +- `Body`: レガシーのプロンプトフォールバック。チャンネルのエンベロープや任意の履歴ラッパーを含む場合がありますが、現在のチャンネルは `BodyForAgent` が利用可能な場合、これを主要なモデル入力として扱うべきではありません。 - `CommandBody`: ディレクティブ/コマンド解析用の生のユーザーテキスト。 -- `RawBody`: `CommandBody` のレガシーエイリアス (互換性のために保持)。 +- `RawBody`: `CommandBody` のレガシーエイリアス（互換性のために保持）。 -チャネルが履歴を提供する場合、共有ラッパーを使用します。 +チャンネルが履歴を提供する場合、共有ラッパーを使用します。 - `[Chat messages since your last reply - for context]` - `[Current message - respond to this]` -**非ダイレクトチャット** (グループ/チャネル/ルーム) では、**現在のメッセージ本文**の先頭に送信者ラベルが付きます (履歴エントリに使われるものと同じスタイル)。これにより、エージェントプロンプト内でリアルタイムメッセージとキュー/履歴メッセージの一貫性が保たれます。 +**非ダイレクトチャット**（グループ/チャンネル/ルーム）では、**現在のメッセージ本文**の前に送信者ラベルが付加されます（履歴エントリと同じスタイル）。これにより、リアルタイムメッセージとキュー/履歴メッセージがエージェントプロンプト内で一貫します。 -履歴バッファは**保留中のみ**です。実行をトリガーしなかったグループメッセージ (たとえばメンションゲートされたメッセージ) を含み、セッショントランスクリプトにすでにあるメッセージは**除外**します。 +履歴バッファは**保留中のみ**です。これには、実行をトリガーしなかったグループメッセージ（たとえば、メンションでゲートされたメッセージ）が含まれ、すでにセッショントランスクリプト内にあるメッセージは**除外**されます。 -ディレクティブの除去は**現在のメッセージ**セクションにのみ適用されるため、履歴はそのまま残ります。履歴をラップするチャネルは、`CommandBody` (または `RawBody`) を元のメッセージテキストに設定し、`Body` は結合済みプロンプトとして保持する必要があります。構造化された履歴、返信、転送、チャネルメタデータは、プロンプト組み立て時にユーザーロールの信頼されないコンテキストブロックとしてレンダリングされます。 -履歴バッファは、`messages.groupChat.historyLimit` (グローバルデフォルト) と、`channels.slack.historyLimit` や `channels.telegram.accounts..historyLimit` のようなチャネルごとの上書きで設定できます (無効化するには `0` を設定)。 +ディレクティブの除去は**現在のメッセージ**セクションにのみ適用されるため、履歴はそのまま保持されます。履歴をラップするチャンネルは、`CommandBody`（または `RawBody`）を元のメッセージテキストに設定し、`Body` を結合済みプロンプトとして保持するべきです。構造化された履歴、返信、転送、チャンネルメタデータは、プロンプト組み立て時にユーザー役割の信頼されないコンテキストブロックとしてレンダリングされます。 +履歴バッファは、`messages.groupChat.historyLimit`（グローバルデフォルト）と、`channels.slack.historyLimit` や `channels.telegram.accounts..historyLimit` などのチャンネルごとの上書きで設定できます（無効にするには `0` を設定）。 ## キューイングとフォローアップ -実行がすでにアクティブな場合、受信メッセージはキューに入れる、現在の実行へ誘導する、またはフォローアップターン用に収集することができます。 +実行がすでにアクティブな場合、受信メッセージはキューに入れる、現在の実行に誘導する、またはフォローアップターン用に収集することができます。 -- `messages.queue` (および `messages.queue.byChannel`) で設定します。 -- デフォルトモードは `steer` で、誘導がキュー済みフォローアップ配信へフォールバックする場合は 500ms のフォローアップデバウンスがあります。 -- モード: `steer`、`followup`、`collect`、`steer-backlog`、`interrupt`、およびレガシーの 1 回に 1 つずつ処理する `queue` モード。 +- `messages.queue`（および `messages.queue.byChannel`）で設定します。 +- デフォルトモードは `steer` で、誘導がキュー済みフォローアップ配信にフォールバックする場合は 500ms のフォローアップデバウンスがあります。 +- モード: `steer`、`followup`、`collect`、`steer-backlog`、`interrupt`、およびレガシーの 1 回に 1 件ずつ処理する `queue` モード。 -詳細: [コマンドキュー](/ja-JP/concepts/queue) と [ステアリングキュー](/ja-JP/concepts/queue-steering)。 +詳細: [コマンドキュー](/ja-JP/concepts/queue) と [Steering キュー](/ja-JP/concepts/queue-steering)。 -## チャネル実行の所有権 +## チャンネルの実行所有権 -チャネル Plugin は、メッセージがセッションキューに入る前に、順序の保持、入力のデバウンス、トランスポートのバックプレッシャー適用を行うことができます。エージェントターン自体に別個のタイムアウトを課すべきではありません。メッセージがセッションにルーティングされると、長時間実行される作業はセッション、ツール、ランタイムのライフサイクルによって管理され、すべてのチャネルが遅いターンを一貫して報告し復旧できるようになります。 +チャンネル Plugin は、メッセージがセッションキューに入る前に順序を保持し、入力をデバウンスし、トランスポートのバックプレッシャーを適用できます。エージェントターン自体に別個のタイムアウトを課すべきではありません。メッセージがセッションにルーティングされると、長時間実行される作業はセッション、ツール、ランタイムのライフサイクルによって管理されるため、すべてのチャンネルが遅いターンを一貫して報告し、回復できます。 ## ストリーミング、チャンク化、バッチ化 -ブロックストリーミングは、モデルがテキストブロックを生成するにつれて部分返信を送信します。チャンク化はチャネルのテキスト上限を尊重し、フェンス付きコードの分割を避けます。 +ブロックストリーミングは、モデルがテキストブロックを生成するにつれて部分返信を送信します。チャンク化はチャンネルのテキスト制限を尊重し、フェンス付きコードの分割を避けます。 -主要な設定: +主要設定: - `agents.defaults.blockStreamingDefault` (`on|off`、デフォルトは off) - `agents.defaults.blockStreamingBreak` (`text_end|message_end`) - `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`) -- `agents.defaults.blockStreamingCoalesce` (アイドルベースのバッチ化) -- `agents.defaults.humanDelay` (ブロック返信間の人間らしい一時停止) -- チャネルの上書き: `*.blockStreaming` と `*.blockStreamingCoalesce` (Telegram 以外のチャネルでは明示的な `*.blockStreaming: true` が必要) +- `agents.defaults.blockStreamingCoalesce`（アイドルベースのバッチ化） +- `agents.defaults.humanDelay`（ブロック返信間の人間らしい一時停止） +- チャンネルごとの上書き: `*.blockStreaming` と `*.blockStreamingCoalesce`（Telegram 以外のチャンネルでは明示的な `*.blockStreaming: true` が必要） 詳細: [ストリーミング + チャンク化](/ja-JP/concepts/streaming)。 @@ -141,39 +141,39 @@ OpenClaw は**プロンプト本文**と**コマンド本文**を分離します OpenClaw はモデルの推論を表示または非表示にできます。 - `/reasoning on|off|stream` は可視性を制御します。 -- 推論コンテンツは、モデルによって生成された場合、トークン使用量に引き続きカウントされます。 -- Telegram はドラフトバブルへの推論ストリームをサポートします。 +- 推論コンテンツは、モデルによって生成された場合、トークン使用量に含まれます。 +- Telegram は、一時的な下書きバブルへの推論ストリームをサポートしており、これは最終配信後に削除されます。永続的な推論出力には `/reasoning on` を使用してください。 詳細: [思考 + 推論ディレクティブ](/ja-JP/tools/thinking) と [トークン使用量](/ja-JP/reference/token-use)。 -## プレフィックス、スレッド化、返信 +## 接頭辞、スレッド化、返信 -送信メッセージの形式は `messages` に集約されています。 +送信メッセージのフォーマットは `messages` に集約されています。 -- `messages.responsePrefix`、`channels..responsePrefix`、`channels..accounts..responsePrefix` (送信プレフィックスのカスケード)、および `channels.whatsapp.messagePrefix` (WhatsApp 受信プレフィックス) -- `replyToMode` とチャネルごとのデフォルトによる返信スレッド化 +- `messages.responsePrefix`、`channels..responsePrefix`、`channels..accounts..responsePrefix`（送信接頭辞のカスケード）、および `channels.whatsapp.messagePrefix`（WhatsApp 受信接頭辞） +- `replyToMode` とチャンネルごとのデフォルトによる返信スレッド化 -詳細: [設定](/ja-JP/gateway/config-agents#messages) とチャネルドキュメント。 +詳細: [設定](/ja-JP/gateway/config-agents#messages) とチャンネルドキュメント。 ## サイレント返信 正確なサイレントトークン `NO_REPLY` / `no_reply` は「ユーザーに見える返信を配信しない」ことを意味します。 -ターンに生成された TTS 音声などの保留中ツールメディアもある場合、OpenClaw はサイレントテキストを取り除きますが、メディア添付ファイルは引き続き配信します。 -OpenClaw はその動作を会話タイプごとに解決します。 +ターンに生成された TTS 音声などの保留中のツールメディアもある場合、OpenClaw はサイレントテキストを取り除きますが、メディア添付ファイルは引き続き配信します。 +OpenClaw はこの動作を会話タイプ別に解決します。 -- ダイレクト会話ではデフォルトで沈黙を許可せず、裸のサイレント返信を短い可視フォールバックに書き換えます。 -- グループ/チャネルではデフォルトで沈黙を許可します。 -- 内部オーケストレーションではデフォルトで沈黙を許可します。 +- ダイレクト会話では、デフォルトでサイレンスを許可せず、サイレント返信のみの場合は短い可視フォールバックに書き換えます。 +- グループ/チャンネルでは、デフォルトでサイレンスを許可します。 +- 内部オーケストレーションでは、デフォルトでサイレンスを許可します。 -OpenClaw は、非ダイレクトチャットでアシスタント返信の前に発生した内部ランナー障害にもサイレント返信を使用するため、グループ/チャネルには Gateway エラーの定型文が表示されません。ダイレクトチャットではデフォルトで簡潔な失敗文が表示されます。生のランナー詳細は `/verbose` が `on` または `full` の場合にのみ表示されます。 +OpenClaw は、非ダイレクトチャットでアシスタント返信の前に発生した内部ランナー障害にもサイレント返信を使用するため、グループ/チャンネルには Gateway エラーの定型文が表示されません。ダイレクトチャットでは、デフォルトで簡潔な失敗文が表示されます。生のランナー詳細は、`/verbose` が `on` または `full` の場合にのみ表示されます。 -デフォルトは `agents.defaults.silentReply` と `agents.defaults.silentReplyRewrite` の下にあります。`surfaces..silentReply` と `surfaces..silentReplyRewrite` はサーフェスごとにこれらを上書きできます。 +デフォルトは `agents.defaults.silentReply` と `agents.defaults.silentReplyRewrite` の下にあり、`surfaces..silentReply` と `surfaces..silentReplyRewrite` でサーフェスごとに上書きできます。 -親セッションに保留中の生成済みサブエージェント実行が 1 つ以上ある場合、裸のサイレント返信は書き換えられる代わりにすべてのサーフェスで破棄されるため、子の完了イベントが実際の返信を配信するまで親は静かなままになります。 +親セッションに保留中の生成済みサブエージェント実行が 1 つ以上ある場合、サイレント返信のみの返信は書き換えられるのではなくすべてのサーフェスで破棄されるため、子の完了イベントが実際の返信を配信するまで親は静かなままになります。 ## 関連 - [ストリーミング](/ja-JP/concepts/streaming) — リアルタイムメッセージ配信 -- [リトライ](/ja-JP/concepts/retry) — メッセージ配信のリトライ動作 +- [再試行](/ja-JP/concepts/retry) — メッセージ配信の再試行動作 - [キュー](/ja-JP/concepts/queue) — メッセージ処理キュー -- [チャネル](/ja-JP/channels) — メッセージングプラットフォーム連携 +- [チャンネル](/ja-JP/channels) — メッセージングプラットフォーム連携 diff --git a/docs/ja-JP/concepts/streaming.md b/docs/ja-JP/concepts/streaming.md index c3404ff14..edc2580a3 100644 --- a/docs/ja-JP/concepts/streaming.md +++ b/docs/ja-JP/concepts/streaming.md @@ -1,29 +1,29 @@ --- read_when: - - チャネルでのストリーミングまたはチャンク化の仕組みの説明 - - ブロックストリーミングまたはチャネルのチャンク分割動作の変更 - - 重複または早期のブロック返信やチャンネルプレビューのストリーミングのデバッグ -summary: ストリーミング + チャンク化の動作 (ブロック返信、チャンネルプレビューのストリーミング、モードマッピング) + - チャンネルでストリーミングまたはチャンク化がどのように機能するかを説明する + - ブロックストリーミングまたはチャネルのチャンク化動作の変更 + - 重複または早期のブロック返信やチャンネルプレビューのストリーミングをデバッグする +summary: ストリーミング + チャンク化の動作 (ブロック返信、チャンネルプレビューストリーミング、モードマッピング) title: ストリーミングとチャンク化 x-i18n: - generated_at: "2026-05-03T21:31:09Z" + generated_at: "2026-05-04T07:03:15Z" model: gpt-5.5 provider: openai - source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50 + source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1 source_path: concepts/streaming.md workflow: 16 --- -OpenClaw には 2 つの別個のストリーミング層があります。 +OpenClaw には、2 つの別々のストリーミングレイヤーがあります。 -- **ブロックストリーミング（チャンネル）:** アシスタントが書き込むにつれて、完了した**ブロック**を送信します。これらは通常のチャンネルメッセージです（トークン差分ではありません）。 +- **ブロックストリーミング（チャンネル）:** アシスタントが書き込み中に、完了した**ブロック**を送信します。これらは通常のチャンネルメッセージです（トークン差分ではありません）。 - **プレビューストリーミング（Telegram/Discord/Slack）:** 生成中に一時的な**プレビューメッセージ**を更新します。 現在、チャンネルメッセージへの**真のトークン差分ストリーミング**はありません。プレビューストリーミングはメッセージベースです（送信 + 編集/追記）。 ## ブロックストリーミング（チャンネルメッセージ） -ブロックストリーミングは、利用可能になったアシスタント出力を粗いチャンクで送信します。 +ブロックストリーミングは、利用可能になったアシスタント出力を大きめのチャンクで送信します。 ``` Model output @@ -37,75 +37,75 @@ Model output 凡例: -- `text_delta/events`: モデルストリームイベント（非ストリーミングモデルではまばらな場合があります）。 -- `chunker`: min/max 境界 + 区切り優先度を適用する `EmbeddedBlockChunker`。 +- `text_delta/events`: モデルのストリームイベント（非ストリーミングモデルではまばらな場合があります）。 +- `chunker`: 最小/最大境界 + 区切り優先度を適用する `EmbeddedBlockChunker`。 - `channel send`: 実際の送信メッセージ（ブロック返信）。 **制御:** -- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"`（デフォルトは off）。 -- チャンネル上書き: チャンネルごとに `"on"`/`"off"` を強制する `*.blockStreaming`（およびアカウント単位のバリアント）。 +- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"`（デフォルトはオフ）。 +- チャンネル上書き: チャンネルごとに `"on"`/`"off"` を強制する `*.blockStreaming`（およびアカウントごとのバリアント）。 - `agents.defaults.blockStreamingBreak`: `"text_end"` または `"message_end"`。 - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`。 -- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }`（送信前にストリーミングされたブロックをマージ）。 +- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }`（送信前にストリーミングされたブロックを結合）。 - チャンネルのハード上限: `*.textChunkLimit`（例: `channels.whatsapp.textChunkLimit`）。 -- チャンネルのチャンクモード: `*.chunkMode`（デフォルトは `length`、`newline` は長さによるチャンク化の前に空行（段落境界）で分割）。 -- Discord のソフト上限: `channels.discord.maxLinesPerMessage`（デフォルト 17）は、UI のクリッピングを避けるため長い返信を分割します。 +- チャンネルのチャンクモード: `*.chunkMode`（デフォルトは `length`、`newline` は長さによるチャンク化の前に空行（段落境界）で分割します）。 +- Discord のソフト上限: `channels.discord.maxLinesPerMessage`（デフォルトは 17）は、UI の切り詰めを避けるために縦に長い返信を分割します。 -**境界セマンティクス:** +**境界の意味:** -- `text_end`: chunker が送出するとすぐにブロックをストリーミングし、各 `text_end` でフラッシュします。 -- `message_end`: アシスタントメッセージが完了するまで待ってから、バッファ済みの出力をフラッシュします。 +- `text_end`: chunker が送信したらすぐにブロックをストリーミングし、各 `text_end` でフラッシュします。 +- `message_end`: アシスタントメッセージが完了するまで待ち、その後バッファされた出力をフラッシュします。 -`message_end` でも、バッファ済みテキストが `maxChars` を超える場合は chunker を使うため、最後に複数のチャンクを送出できます。 +バッファされたテキストが `maxChars` を超える場合、`message_end` でも chunker が使われるため、最後に複数のチャンクを送信することがあります。 ### ブロックストリーミングでのメディア配信 -`MEDIA:` ディレクティブは通常の配信メタデータです。ブロックストリーミングがメディアブロックを早めに送信した場合、OpenClaw はそのターンの配信を記憶します。最終アシスタントペイロードが同じメディア URL を繰り返した場合、添付を再送信する代わりに、最終配信では重複メディアが取り除かれます。 +`MEDIA:` ディレクティブは通常の配信メタデータです。ブロックストリーミングがメディアブロックを早期に送信すると、OpenClaw はそのターンの配信を記憶します。最終的なアシスタントペイロードが同じメディア URL を繰り返す場合、最終配信では添付ファイルを再送信する代わりに重複メディアを取り除きます。 -完全に重複する最終ペイロードは抑制されます。最終ペイロードが、すでにストリーミングされたメディアの周囲に別のテキストを追加する場合、OpenClaw はメディアを 1 回だけ配信したまま新しいテキストを送信します。これにより、エージェントがストリーミング中に `MEDIA:` を送出し、プロバイダーも完了返信にそれを含める場合に、Telegram などのチャンネルで音声メモやファイルが重複するのを防ぎます。 +完全に重複する最終ペイロードは抑制されます。最終ペイロードが、すでにストリーミングされたメディアの周囲に別個のテキストを追加している場合、OpenClaw はメディアを 1 回だけ配信したまま、新しいテキストを送信します。これにより、エージェントがストリーミング中に `MEDIA:` を送信し、プロバイダーも完了した返信にそれを含める場合に、Telegram などのチャンネルで音声メモやファイルが重複するのを防ぎます。 -## チャンク化アルゴリズム（下限/上限） +## チャンク化アルゴリズム（低/高境界） ブロックチャンク化は `EmbeddedBlockChunker` によって実装されています。 -- **下限:** バッファ >= `minChars` になるまで送出しません（強制時を除く）。 -- **上限:** `maxChars` より前での分割を優先します。強制時は `maxChars` で分割します。 +- **低境界:** バッファ >= `minChars` になるまで送信しません（強制時を除く）。 +- **高境界:** `maxChars` より前での分割を優先します。強制時は `maxChars` で分割します。 - **区切り優先度:** `paragraph` → `newline` → `sentence` → `whitespace` → ハード区切り。 -- **コードフェンス:** フェンス内では決して分割しません。`maxChars` で強制される場合は、Markdown の妥当性を保つためにフェンスを閉じて再オープンします。 +- **コードフェンス:** フェンス内部では決して分割しません。`maxChars` で強制される場合は、Markdown の有効性を保つためにフェンスを閉じて再オープンします。 `maxChars` はチャンネルの `textChunkLimit` にクランプされるため、チャンネルごとの上限を超えることはできません。 ## 結合（ストリーミングされたブロックのマージ） -ブロックストリーミングが有効な場合、OpenClaw は連続するブロックチャンクを送信前に**マージ**できます。これにより、段階的な出力を維持しながら「1 行だけのスパム」を減らせます。 +ブロックストリーミングが有効な場合、OpenClaw は送信前に**連続するブロックチャンクを結合**できます。これにより、段階的な出力を提供しながら「1 行だけの大量送信」を減らせます。 -- 結合はフラッシュ前に**アイドル間隔**（`idleMs`）を待ちます。 -- バッファは `maxChars` で上限設定され、それを超えるとフラッシュされます。 -- `minChars` は、十分なテキストが蓄積されるまで小さな断片の送信を防ぎます（最終フラッシュでは残りのテキストが必ず送信されます）。 +- 結合は、フラッシュ前に**アイドル間隔**（`idleMs`）を待ちます。 +- バッファは `maxChars` で制限され、それを超えるとフラッシュされます。 +- `minChars` は、十分なテキストが蓄積されるまで小さな断片の送信を防ぎます（最終フラッシュでは常に残りのテキストを送信します）。 - 結合文字列は `blockStreamingChunk.breakPreference` から導出されます（`paragraph` → `\n\n`、`newline` → `\n`、`sentence` → スペース）。 -- チャンネル上書きは `*.blockStreamingCoalesce` で利用できます（アカウント単位の設定を含む）。 +- チャンネル上書きは `*.blockStreamingCoalesce` で利用できます（アカウントごとの設定を含む）。 - デフォルトの結合 `minChars` は、上書きされない限り Signal/Slack/Discord では 1500 に引き上げられます。 -## ブロック間の人間らしいペース調整 +## ブロック間の人間らしいペーシング -ブロックストリーミングが有効な場合、ブロック返信の間（最初のブロックの後）に**ランダム化された一時停止**を追加できます。これにより、複数吹き出しの応答がより自然に感じられます。 +ブロックストリーミングが有効な場合、ブロック返信の間（最初のブロックの後）に**ランダム化された一時停止**を追加できます。これにより、複数の吹き出しからなる応答がより自然に感じられます。 -- 設定: `agents.defaults.humanDelay`（`agents.list[].humanDelay` でエージェントごとに上書き）。 -- モード: `off`（デフォルト）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。 +- 設定: `agents.defaults.humanDelay`（エージェントごとに `agents.list[].humanDelay` で上書き）。 +- モード: `off`（デフォルト）、`natural`（800〜2500ms）、`custom`（`minMs`/`maxMs`）。 - **ブロック返信**にのみ適用され、最終返信やツール要約には適用されません。 ## 「チャンクをストリーミングするか、すべてを送るか」 これは次に対応します。 -- **チャンクをストリーミング:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（逐次送出）。Telegram 以外のチャンネルでは `*.blockStreaming: true` も必要です。 -- **最後にすべてをストリーミング:** `blockStreamingBreak: "message_end"`（1 回フラッシュ。非常に長い場合は複数チャンクになる可能性あり）。 +- **チャンクをストリーミング:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（進行に合わせて送信）。Telegram 以外のチャンネルでは `*.blockStreaming: true` も必要です。 +- **最後にすべてをストリーミング:** `blockStreamingBreak: "message_end"`（1 回フラッシュ。非常に長い場合は複数チャンクになる可能性があります）。 - **ブロックストリーミングなし:** `blockStreamingDefault: "off"`（最終返信のみ）。 -**チャンネルの注意:** `*.blockStreaming` が明示的に `true` に設定されていない限り、ブロックストリーミングは**オフ**です。チャンネルはブロック返信なしでライブプレビュー（`channels..streaming`）をストリーミングできます。 +**チャンネルの注記:** `*.blockStreaming` が明示的に `true` に設定されていない限り、ブロックストリーミングは**オフ**です。チャンネルは、ブロック返信なしでライブプレビュー（`channels..streaming`）をストリーミングできます。 -設定場所のリマインダー: `blockStreaming*` のデフォルトはルート設定ではなく `agents.defaults` 配下にあります。 +設定場所のリマインダー: `blockStreaming*` のデフォルトはルート設定ではなく、`agents.defaults` の下にあります。 ## プレビューストリーミングモード @@ -115,20 +115,20 @@ Model output - `off`: プレビューストリーミングを無効化します。 - `partial`: 最新テキストで置き換えられる単一のプレビュー。 -- `block`: チャンク化/追記のステップでプレビューを更新します。 -- `progress`: 生成中の進捗/ステータスプレビュー、完了時に最終回答。 +- `block`: チャンク化/追記ステップでプレビューを更新します。 +- `progress`: 生成中の進捗/ステータスプレビュー、完了時の最終回答。 -`streaming.mode: "block"` は、Discord や Telegram など編集可能なチャンネル向けのプレビューストリーミングモードです。そこでのチャンネルブロック配信を有効にするものではありません。通常のブロック返信が必要な場合は、`streaming.block.enabled` またはレガシーの `blockStreaming` チャンネルキーを使用してください。Microsoft Teams は例外です。下書きプレビューのブロックトランスポートがないため、`streaming.mode: "block"` はネイティブの partial/progress ストリーミングではなく Teams のブロック配信にマップされます。 +`streaming.mode: "block"` は、Discord や Telegram などの編集可能なチャンネル向けのプレビューストリーミングモードです。これは、そのチャンネルでチャンネルブロック配信を有効にするものではありません。通常のブロック返信が必要な場合は、`streaming.block.enabled` またはレガシーの `blockStreaming` チャンネルキーを使います。Microsoft Teams は例外です。下書きプレビューのブロック転送がないため、`streaming.mode: "block"` はネイティブの部分/進捗ストリーミングではなく Teams のブロック配信にマップされます。 ### チャンネルマッピング | チャンネル | `off` | `partial` | `block` | `progress` | -| ---------- | ----- | --------- | ------- | ----------------------- | +| ---------- | ----- | --------- | ------- | ---------- | | Telegram | ✅ | ✅ | ✅ | 編集可能な進捗下書き | | Discord | ✅ | ✅ | ✅ | 編集可能な進捗下書き | -| Slack | ✅ | ✅ | ✅ | ✅ | -| Mattermost | ✅ | ✅ | ✅ | ✅ | -| MS Teams | ✅ | ✅ | ✅ | ネイティブ進捗ストリーム | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | +| MS Teams | ✅ | ✅ | ✅ | ネイティブ進捗ストリーム | Slack のみ: @@ -137,60 +137,60 @@ Slack のみ: レガシーキーの移行: -- Telegram: レガシーの `streamMode` とスカラー/ブール値の `streaming` は、doctor/config 互換パスによって検出され、`streaming.mode` に移行されます。 -- Discord: `streamMode` + ブール値の `streaming` は `streaming` enum に自動移行されます。 -- Slack: `streamMode` は `streaming.mode` に自動移行されます。ブール値の `streaming` は `streaming.mode` と `streaming.nativeTransport` に自動移行されます。レガシーの `nativeStreaming` は `streaming.nativeTransport` に自動移行されます。 +- Telegram: レガシーの `streamMode` とスカラー/ブール値の `streaming` は、doctor/設定互換パスによって検出され、`streaming.mode` に移行されます。 +- Discord: `streamMode` + ブール値の `streaming` は `streaming` 列挙型へ自動移行されます。 +- Slack: `streamMode` は `streaming.mode` へ自動移行されます。ブール値の `streaming` は `streaming.mode` と `streaming.nativeTransport` へ自動移行されます。レガシーの `nativeStreaming` は `streaming.nativeTransport` へ自動移行されます。 ### ランタイム動作 Telegram: -- DM とグループ/トピック全体で `sendMessage` + `editMessageText` のプレビュー更新を使用します。 -- プレビューが約 1 分間表示されていた場合、インプレース編集の代わりに新しい最終メッセージを送信し、その後プレビューをクリーンアップして Telegram のタイムスタンプが返信完了を反映するようにします。 -- Telegram のブロックストリーミングが明示的に有効な場合、プレビューストリーミングはスキップされます（二重ストリーミングを避けるため）。 -- `/reasoning stream` は推論をプレビューに書き込めます。 +- DM とグループ/トピック全体で、`sendMessage` + `editMessageText` のプレビュー更新を使います。 +- プレビューが約 1 分間表示されていた場合、インプレース編集ではなく新しい最終メッセージを送信し、その後プレビューをクリーンアップして Telegram のタイムスタンプが返信完了を反映するようにします。 +- Telegram のブロックストリーミングが明示的に有効な場合、二重ストリーミングを避けるためにプレビューストリーミングはスキップされます。 +- `/reasoning stream` は、一時的なプレビューに推論を書き込み、最終配信後に削除できます。 Discord: -- 送信 + 編集のプレビューメッセージを使用します。 -- `block` モードは下書きチャンク化（`draftChunk`）を使用します。 +- 送信 + 編集のプレビューメッセージを使います。 +- `block` モードは下書きチャンク化（`draftChunk`）を使います。 - Discord のブロックストリーミングが明示的に有効な場合、プレビューストリーミングはスキップされます。 -- 最終メディア、エラー、明示的返信ペイロードは、新しい下書きをフラッシュせずに保留中のプレビューをキャンセルし、その後通常の配信を使用します。 +- 最終メディア、エラー、明示的返信ペイロードは、新しい下書きをフラッシュせずに保留中のプレビューをキャンセルし、その後通常配信を使います。 Slack: -- `partial` は、利用可能な場合に Slack ネイティブストリーミング（`chat.startStream`/`append`/`stop`）を使用できます。 -- `block` は追記形式の下書きプレビューを使用します。 -- `progress` はステータスプレビューテキストを使用し、その後最終回答を送信します。 -- 返信スレッドのないトップレベル DM では、Slack ネイティブストリーミングの代わりに下書きプレビュー投稿と編集を使用します。 -- ネイティブおよび下書きのプレビューストリーミングは、そのターンのブロック返信を抑制するため、Slack の返信は 1 つの配信経路だけでストリーミングされます。 -- 最終メディア/エラーペイロードと進捗の最終出力は、使い捨ての下書きメッセージを作成しません。プレビューを編集できるテキスト/ブロックの最終出力だけが、保留中の下書きテキストをフラッシュします。 +- `partial` は、利用可能な場合に Slack ネイティブストリーミング（`chat.startStream`/`append`/`stop`）を使えます。 +- `block` は追記形式の下書きプレビューを使います。 +- `progress` はステータスプレビューテキストを使い、その後に最終回答を送信します。 +- 返信スレッドのないトップレベル DM は、Slack ネイティブストリーミングの代わりに下書きプレビュー投稿と編集を使います。 +- ネイティブおよび下書きプレビューストリーミングは、そのターンのブロック返信を抑制するため、Slack の返信は 1 つの配信パスだけでストリーミングされます。 +- 最終メディア/エラーペイロードと進捗の最終送信は、使い捨ての下書きメッセージを作成しません。プレビューを編集できるテキスト/ブロックの最終送信のみが、保留中の下書きテキストをフラッシュします。 Mattermost: -- 思考、ツールアクティビティ、部分返信テキストを 1 つの下書きプレビュー投稿にストリーミングし、最終回答を安全に送信できるときにインプレースで最終化します。 -- 最終化時にプレビュー投稿が削除されている、または利用できない場合は、新しい最終投稿の送信にフォールバックします。 -- 最終メディア/エラーペイロードは、一時的なプレビュー投稿をフラッシュする代わりに、通常の配信前に保留中のプレビュー更新をキャンセルします。 +- 思考、ツールアクティビティ、部分返信テキストを単一の下書きプレビュー投稿にストリーミングし、最終回答を安全に送信できるときにインプレースで確定します。 +- プレビュー投稿が削除された、または確定時に利用できない場合は、新しい最終投稿の送信にフォールバックします。 +- 最終メディア/エラーペイロードは、一時的なプレビュー投稿をフラッシュする代わりに、通常配信の前に保留中のプレビュー更新をキャンセルします。 Matrix: -- 最終テキストがプレビューイベントを再利用できる場合、下書きプレビューはインプレースで最終化されます。 -- メディアのみ、エラー、返信ターゲット不一致の最終出力は、通常の配信前に保留中のプレビュー更新をキャンセルします。すでに表示されている古いプレビューは取り消されます。 +- 下書きプレビューは、最終テキストがプレビューイベントを再利用できる場合にインプレースで確定します。 +- メディアのみ、エラー、返信ターゲット不一致の最終送信は、通常配信の前に保留中のプレビュー更新をキャンセルします。すでに表示されている古いプレビューは削除されます。 ### ツール進捗プレビュー更新 -プレビューストリーミングには、**ツール進捗**更新も含められます。これは「ウェブを検索中」、「ファイルを読み込み中」、「ツールを呼び出し中」のような短いステータス行で、ツール実行中に最終返信より前に同じプレビューメッセージへ表示されます。これにより、複数ステップのツールターンが、最初の思考プレビューと最終回答の間で沈黙せず、視覚的に動き続けます。 +プレビューストリーミングには、**ツール進捗**更新も含められます。これは「Web を検索中」「ファイルを読み取り中」「ツールを呼び出し中」のような短いステータス行で、ツールの実行中、最終返信の前に同じプレビューメッセージ内に表示されます。これにより、複数ステップのツールターンが、最初の思考プレビューと最終回答の間で沈黙するのではなく、視覚的に進行中であることを示せます。 対応サーフェス: -- **Discord**、**Slack**、**Telegram**、**Matrix** は、プレビューストリーミングがアクティブな場合、デフォルトでツール進捗をライブプレビュー編集にストリーミングします。Microsoft Teams は個人チャットでネイティブの進捗ストリームを使用します。 -- Telegram は `v2026.4.22` 以降、ツール進捗プレビュー更新を有効にした状態で出荷されています。有効なままにすることで、そのリリース済み動作を維持できます。 -- **Mattermost** はすでにツールアクティビティを単一の下書きプレビュー投稿に組み込んでいます（上記参照）。 -- ツール進捗の編集はアクティブなプレビューストリーミングモードに従います。プレビューストリーミングが `off` の場合、またはブロックストリーミングがメッセージを引き継いだ場合はスキップされます。Telegram では、`streaming.mode: "off"` は final-only です。汎用の進捗チャットもスタンドアロンのステータスメッセージとして配信される代わりに抑制されますが、承認プロンプト、メディアペイロード、エラーは通常どおりルーティングされます。 -- プレビューストリーミングは維持しつつツール進捗行を非表示にするには、そのチャンネルの `streaming.preview.toolProgress` を `false` に設定します。プレビュー編集を完全に無効化するには、`streaming.mode` を `off` に設定します。 -- Telegram の選択引用返信は例外です。`replyToMode` が `"off"` ではなく、選択された引用テキストが存在する場合、OpenClaw はそのターンの回答プレビューストリームをスキップするため、ツール進捗プレビュー行はレンダリングできません。選択引用テキストのない現在メッセージへの返信では、プレビューストリーミングは引き続き維持されます。詳細は [Telegram チャンネルドキュメント](/ja-JP/channels/telegram) を参照してください。 +- **Discord**、**Slack**、**Telegram**、**Matrix** は、プレビューストリーミングがアクティブな場合、デフォルトでツール進捗をライブプレビュー編集へストリーミングします。Microsoft Teams は個人チャットでネイティブ進捗ストリームを使います。 +- Telegram は `v2026.4.22` 以降、ツール進捗プレビュー更新を有効にした状態でリリースされています。有効のままにすることで、そのリリース済み動作が維持されます。 +- **Mattermost** は、すでにツールアクティビティを単一の下書きプレビュー投稿に取り込みます（上記参照）。 +- ツール進捗編集は、アクティブなプレビューストリーミングモードに従います。プレビューストリーミングが `off` の場合、またはブロックストリーミングがメッセージを引き継いだ場合はスキップされます。Telegram では、`streaming.mode: "off"` は最終送信のみです。承認プロンプト、メディアペイロード、エラーは引き続き通常どおりルーティングされますが、一般的な進捗チャットも単独のステータスメッセージとして配信されずに抑制されます。 +- プレビューストリーミングは維持しつつツール進捗行を非表示にするには、そのチャンネルの `streaming.preview.toolProgress` を `false` に設定します。コマンド/実行テキストを非表示にしつつツール進捗行を表示し続けるには、`streaming.preview.commandText` を `"status"` に設定するか、`streaming.progress.commandText` を `"status"` に設定します。デフォルトはリリース済み動作を維持するため `"raw"` です。このポリシーは、OpenClaw のコンパクトな進捗レンダラーを使う下書き/進捗チャンネルで共有されます。これには Discord、Matrix、Microsoft Teams、Mattermost、Slack 下書きプレビュー、Telegram が含まれます。プレビュー編集を完全に無効にするには、`streaming.mode` を `off` に設定します。 +- Telegram の選択引用返信は例外です。`replyToMode` が `"off"` ではなく、選択された引用テキストが存在する場合、OpenClaw はそのターンの回答プレビューストリームをスキップするため、ツール進捗プレビュー行は表示されません。選択引用テキストのない現在メッセージへの返信では、引き続きプレビューストリーミングが維持されます。詳細は [Telegram チャンネルドキュメント](/ja-JP/channels/telegram) を参照してください。 -例: +進行状況行は表示したまま、未加工のコマンド/exec テキストは非表示にします。 ```json { @@ -199,7 +199,26 @@ Matrix: "streaming": { "mode": "partial", "preview": { - "toolProgress": false + "toolProgress": true, + "commandText": "status" + } + } + } + } +} +``` + +同じ形を別のコンパクトな進行状況チャンネルキーの下で使用します。たとえば、`channels.discord`、`channels.matrix`、`channels.msteams`、`channels.mattermost`、または Slack ドラフトプレビューです。進行状況ドラフトモードでは、同じポリシーを `streaming.progress` の下に置きます。 + +```json +{ + "channels": { + "telegram": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" } } } @@ -209,7 +228,7 @@ Matrix: ## 関連 -- [進捗下書き](/ja-JP/concepts/progress-drafts) — 長いターン中に更新される、表示可能な作業中メッセージ +- [進行状況ドラフト](/ja-JP/concepts/progress-drafts) — 長いターン中に更新される、表示可能な作業中メッセージ - [メッセージ](/ja-JP/concepts/messages) — メッセージのライフサイクルと配信 -- [リトライ](/ja-JP/concepts/retry) — 配信失敗時のリトライ動作 +- [再試行](/ja-JP/concepts/retry) — 配信失敗時の再試行動作 - [チャンネル](/ja-JP/channels) — チャンネルごとのストリーミング対応 diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index e3cc39084..3af13a362 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -2,152 +2,167 @@ read_when: - ローカルまたは CI でテストを実行する - モデル/プロバイダーのバグに対する回帰テストの追加 - - Gateway + エージェント動作のデバッグ -summary: 'テストキット: 単体/e2e/ライブスイート、Docker ランナー、各テストがカバーする内容' + - Gateway とエージェントの挙動のデバッグ +summary: 'テストキット: 単体/e2e/ライブスイート、Docker ランナー、および各テストの対象範囲' title: テスト x-i18n: - generated_at: "2026-05-03T21:34:58Z" + generated_at: "2026-05-04T07:03:10Z" model: gpt-5.5 provider: openai - source_hash: e7fb57bee958c4e6243f02193a657d7b19ca633c7a27f70eac6b590931390671 + source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 source_path: help/testing.md workflow: 16 --- -OpenClaw には 3 つの Vitest スイート（ユニット/統合、E2E、ライブ）と小規模な Docker ランナー群があります。このドキュメントは「テスト方法」のガイドです。 +OpenClaw には3つの Vitest スイート (unit/integration、e2e、live) と少数の Docker ランナーがあります。このドキュメントは「テスト方法」のガイドです。 -- 各スイートがカバーする内容（および意図的にカバー_しない_内容）。 -- よくあるワークフロー（ローカル、プッシュ前、デバッグ）で実行するコマンド。 -- ライブテストが認証情報を検出し、モデル/プロバイダーを選択する方法。 -- 実際のモデル/プロバイダー問題に対するリグレッションを追加する方法。 +- 各スイートがカバーするもの (および意図的にカバーしないもの)。 +- 一般的なワークフロー (ローカル、プッシュ前、デバッグ) で実行するコマンド。 +- live テストが認証情報を検出し、モデル/プロバイダーを選択する方法。 +- 実際のモデル/プロバイダーの問題に対するリグレッションを追加する方法。 -**QA スタック（qa-lab、qa-channel、ライブトランスポートレーン）**は別途ドキュメント化されています。 +**QA スタック (qa-lab、qa-channel、ライブトランスポートレーン)** は別途ドキュメント化されています。 - [QA 概要](/ja-JP/concepts/qa-e2e-automation) — アーキテクチャ、コマンドサーフェス、シナリオ作成。 - [Matrix QA](/ja-JP/concepts/qa-matrix) — `pnpm openclaw qa matrix` のリファレンス。 -- [QA チャンネル](/ja-JP/channels/qa-channel) — リポジトリベースのシナリオで使う合成トランスポート Plugin。 +- [QA channel](/ja-JP/channels/qa-channel) — リポジトリに支えられたシナリオで使用される合成トランスポートプラグイン。 -このページでは、通常のテストスイートと Docker/Parallels ランナーの実行を扱います。以下の QA 固有ランナーのセクション（[QA 固有ランナー](#qa-specific-runners)）では、具体的な `qa` 呼び出しを列挙し、上記のリファレンスに戻れるようにしています。 +このページでは、通常のテストスイートと Docker/Parallels ランナーの実行について説明します。以下の QA 固有ランナーセクション ([QA-specific runners](#qa-specific-runners)) では、具体的な `qa` 呼び出しを一覧し、上記のリファレンスへ戻る導線を示します。 ## クイックスタート -ほとんどの日は次のとおりです。 +ほとんどの日: -- フルゲート（プッシュ前に期待されるもの）: `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- 余裕のあるマシンでの高速なローカルフルスイート実行: `pnpm test:max` -- 直接の Vitest ウォッチループ: `pnpm test:watch` -- 直接のファイル指定は拡張/チャンネルのパスにもルーティングされるようになりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 単一の失敗を反復調査しているときは、まず対象を絞った実行を優先します。 +- 完全ゲート (プッシュ前に期待されるもの): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- 余裕のあるマシンでより高速なローカルのフルスイート実行: `pnpm test:max` +- 直接の Vitest watch ループ: `pnpm test:watch` +- 直接のファイル指定は extension/channel パスにもルーティングされるようになりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 単一の失敗を反復調査しているときは、まず対象を絞った実行を優先してください。 - Docker ベースの QA サイト: `pnpm qa:lab:up` - Linux VM ベースの QA レーン: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -テストを触った場合や追加の確信がほしい場合: +テストに触れる場合や、追加の確信が欲しい場合: - カバレッジゲート: `pnpm test:coverage` - E2E スイート: `pnpm test:e2e` -実際のプロバイダー/モデルをデバッグする場合（実際の認証情報が必要）: +実際のプロバイダー/モデルをデバッグする場合 (実際の認証情報が必要): -- ライブスイート（モデル + Gateway ツール/画像プローブ）: `pnpm test:live` -- 1 つのライブファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- ランタイム性能レポート: 実際の `openai/gpt-5.4` エージェントターンには `live_gpt54=true`、Kova の CPU/ヒープ/トレース成果物には `deep_profile=true` を指定して `OpenClaw Performance` をディスパッチします。日次のスケジュール実行は、`CLAWGRIT_REPORTS_TOKEN` が設定されている場合、モックプロバイダー、deep-profile、GPT 5.4 レーンの成果物を `openclaw/clawgrit-reports` に公開します。モックプロバイダーレポートには、ソースレベルの Gateway 起動、メモリ、Plugin 負荷、反復 fake-model hello ループ、CLI 起動時間の数値も含まれます。 -- Docker ライブモデルスイープ: `pnpm test:docker:live-models` - - 選択された各モデルでは、テキストターンに加えて小さなファイル読み取り形式のプローブが実行されます。メタデータで `image` 入力が示されているモデルでは、小さな画像ターンも実行されます。プロバイダーの失敗を切り分ける場合は、`OPENCLAW_LIVE_MODEL_FILE_PROBE=0` または `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` で追加プローブを無効化します。 - - CI カバレッジ: 日次の `OpenClaw Scheduled Live And E2E Checks` と手動の `OpenClaw Release Checks` はどちらも、`include_live_suites: true` を指定して再利用可能なライブ/E2E ワークフローを呼び出します。これにはプロバイダーごとにシャードされた個別の Docker ライブモデルマトリックスジョブが含まれます。 +- live スイート (モデル + Gateway ツール/画像プローブ): `pnpm test:live` +- 1つの live ファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- ランタイム性能レポート: 実際の `openai/gpt-5.4` エージェントターンには `live_gpt54=true`、Kova の CPU/ヒープ/トレースアーティファクトには `deep_profile=true` を指定して `OpenClaw Performance` をディスパッチします。毎日のスケジュール実行は、`CLAWGRIT_REPORTS_TOKEN` が設定されている場合、mock-provider、deep-profile、GPT 5.4 レーンのアーティファクトを `openclaw/clawgrit-reports` に公開します。mock-provider レポートには、ソースレベルの Gateway 起動、メモリ、プラグイン負荷、反復 fake-model hello-loop、CLI 起動時間の数値も含まれます。 +- Docker live モデルスイープ: `pnpm test:docker:live-models` + - 選択された各モデルは、テキストターンに加えて小さなファイル読み取り形式のプローブを実行します。メタデータが `image` 入力を示しているモデルでは、小さな画像ターンも実行します。プロバイダーの失敗を切り分ける場合は、`OPENCLAW_LIVE_MODEL_FILE_PROBE=0` または `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` で追加プローブを無効化します。 + - CI カバレッジ: 毎日の `OpenClaw Scheduled Live And E2E Checks` と手動の `OpenClaw Release Checks` はどちらも、`include_live_suites: true` を指定して再利用可能な live/E2E ワークフローを呼び出します。これには、プロバイダーごとにシャードされた個別の Docker live モデルマトリックスジョブが含まれます。 - 集中的な CI 再実行では、`include_live_suites: true` と `live_models_only: true` を指定して `OpenClaw Live And E2E Checks (Reusable)` をディスパッチします。 - - 高シグナルな新しいプロバイダーシークレットは、`scripts/ci-hydrate-live-auth.sh` に加え、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` とそのスケジュール/リリース呼び出し元に追加します。 + - 新しい高シグナルのプロバイダーシークレットは、`scripts/ci-hydrate-live-auth.sh`、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml`、およびそのスケジュール/リリース呼び出し元に追加します。 - ネイティブ Codex バインドチャットスモーク: `pnpm test:docker:live-codex-bind` - - Codex app-server パスに対して Docker ライブレーンを実行し、`/codex bind` で合成 Slack DM をバインドし、`/codex fast` と `/codex permissions` を実行したうえで、通常の返信と画像添付が ACP ではなくネイティブ Plugin バインディングを通ってルーティングされることを検証します。 + - Docker live レーンを Codex app-server パスに対して実行し、合成 Slack DM を `/codex bind` でバインドし、`/codex fast` と `/codex permissions` を実行したうえで、通常の返信と画像添付が ACP ではなくネイティブプラグインバインディング経由でルーティングされることを検証します。 - Codex app-server ハーネススモーク: `pnpm test:docker:live-codex-harness` - - Plugin が所有する Codex app-server ハーネスを通じて Gateway エージェントターンを実行し、`/codex status` と `/codex models` を検証します。デフォルトでは、画像、cron MCP、サブエージェント、Guardian プローブも実行します。他の Codex app-server の失敗を切り分ける場合は、`OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` でサブエージェントプローブを無効化します。サブエージェントだけを集中的に確認する場合は、他のプローブを無効化します: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`。 - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` が設定されていない限り、これはサブエージェントプローブの後に終了します。 + - プラグイン所有の Codex app-server ハーネスを通じて Gateway エージェントターンを実行し、`/codex status` と `/codex models` を検証し、デフォルトで画像、cron MCP、サブエージェント、Guardian プローブを実行します。他の Codex app-server の失敗を切り分ける場合は、`OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` でサブエージェントプローブを無効化します。集中的なサブエージェント確認では、他のプローブを無効化します: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`。 + これは `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` が設定されていない限り、サブエージェントプローブの後に終了します。 - Crestodian レスキューコマンドスモーク: `pnpm test:live:crestodian-rescue-channel` - - メッセージチャンネルのレスキューコマンドサーフェスに対するオプトインの念押しチェックです。`/crestodian status` を実行し、永続的なモデル変更をキューに入れ、`/crestodian yes` に返信し、監査/設定書き込みパスを検証します。 + - メッセージチャネルレスキューコマンドサーフェスのオプトインの念入りな確認です。`/crestodian status` を実行し、永続的なモデル変更をキューに入れ、`/crestodian yes` に返信し、監査/設定書き込みパスを検証します。 - Crestodian プランナー Docker スモーク: `pnpm test:docker:crestodian-planner` - - `PATH` 上に偽の Claude CLI を持つ設定なしコンテナで Crestodian を実行し、ファジープランナーのフォールバックが監査済みの型付き設定書き込みに変換されることを検証します。 + - `PATH` 上に偽の Claude CLI がある設定なしコンテナーで Crestodian を実行し、fuzzy プランナーフォールバックが監査付きの型付き設定書き込みに変換されることを検証します。 - Crestodian 初回実行 Docker スモーク: `pnpm test:docker:crestodian-first-run` - - 空の OpenClaw 状態ディレクトリから開始し、素の `openclaw` を Crestodian にルーティングし、セットアップ/モデル/エージェント/Discord Plugin + SecretRef 書き込みを適用し、設定を検証し、監査エントリを検証します。同じ Ring 0 セットアップパスは QA Lab でも `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` によってカバーされています。 -- Moonshot/Kimi コストスモーク: `MOONSHOT_API_KEY` を設定した状態で、`openclaw models list --provider moonshot --json` を実行し、その後 `moonshot/kimi-k2.6` に対して分離された `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` を実行します。JSON が Moonshot/K2.6 を報告し、アシスタントのトランスクリプトが正規化された `usage.cost` を保存していることを検証します。 + - 空の OpenClaw 状態ディレクトリから開始し、素の `openclaw` を Crestodian にルーティングし、setup/model/agent/Discord プラグイン + SecretRef 書き込みを適用し、設定を検証し、監査エントリを確認します。同じ Ring 0 セットアップパスは、QA Lab でも `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` によってカバーされています。 +- Moonshot/Kimi コストスモーク: `MOONSHOT_API_KEY` を設定した状態で、`openclaw models list --provider moonshot --json` を実行し、次に `moonshot/kimi-k2.6` に対して分離された `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` を実行します。JSON が Moonshot/K2.6 を報告し、アシスタントトランスクリプトが正規化された `usage.cost` を保存していることを確認します。 -失敗ケースが 1 つだけ必要な場合は、以下で説明する allowlist 環境変数でライブテストを絞り込むことを優先してください。 +失敗しているケースが1つだけ必要な場合は、以下で説明する allowlist 環境変数で live テストを絞り込むことを優先してください。 ## QA 固有ランナー QA-lab の現実性が必要な場合、これらのコマンドはメインのテストスイートの横に位置します。 -CI は専用ワークフローで QA Lab を実行します。エージェント型パリティは単独の PR ワークフローではなく、`QA-Lab - All Lanes` とリリース検証の下にネストされています。広範な検証では、`rerun_group=qa-parity` または release-checks QA グループを指定して `Full Release Validation` を使うべきです。`QA-Lab - All Lanes` は、`main` 上の夜間実行と手動ディスパッチで、モックパリティレーン、ライブ Matrix レーン、Convex 管理のライブ Telegram レーン、Convex 管理のライブ Discord レーンを並列ジョブとして実行します。スケジュール QA とリリースチェックは Matrix に明示的に `--profile fast` を渡しますが、Matrix CLI と手動ワークフロー入力のデフォルトは `all` のままです。手動ディスパッチでは、`all` を `transport`、`media`、`e2ee-smoke`、`e2ee-deep`、`e2ee-cli` ジョブにシャードできます。`OpenClaw Release Checks` はリリース承認前にパリティに加えて高速 Matrix と Telegram レーンを実行し、リリーストランスポートチェックには `mock-openai/gpt-5.5` を使用するため、決定的に保たれ、通常のプロバイダー Plugin 起動を回避できます。これらのライブトランスポート Gateway はメモリ検索を無効化します。メモリ動作は QA パリティスイートで引き続きカバーされます。 +CI は専用ワークフローで QA Lab を実行します。エージェント的パリティは `QA-Lab - All Lanes` とリリース検証の下にネストされており、単独の PR ワークフローではありません。広範な検証には、`rerun_group=qa-parity` または release-checks QA グループを指定した `Full Release Validation` を使用してください。`QA-Lab - All Lanes` は `main` で毎晩実行され、手動ディスパッチからは mock parity レーン、live Matrix レーン、Convex 管理の live Telegram レーン、Convex 管理の live Discord レーンが並列ジョブとして実行されます。スケジュール QA とリリースチェックは Matrix に `--profile fast` を明示的に渡しますが、Matrix CLI と手動ワークフロー入力のデフォルトは `all` のままです。手動ディスパッチでは、`all` を `transport`、`media`、`e2ee-smoke`、`e2ee-deep`、`e2ee-cli` ジョブにシャードできます。`OpenClaw Release Checks` は、リリース承認前にパリティに加えて高速 Matrix レーンと Telegram レーンを実行し、リリーストランスポートチェックには `mock-openai/gpt-5.5` を使用するため、決定的であり、通常のプロバイダープラグイン起動を避けられます。これらの live トランスポート Gateway はメモリ検索を無効化します。メモリ動作は QA パリティスイートで引き続きカバーされます。 -フルリリースのライブメディアシャードは `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` を使用します。このイメージにはすでに `ffmpeg` と `ffprobe` が含まれています。Docker ライブモデル/バックエンドシャードは、選択されたコミットごとに 1 回だけビルドされる共有の `ghcr.io/openclaw/openclaw-live-test:` イメージを使用し、各シャード内で再ビルドする代わりに `OPENCLAW_SKIP_DOCKER_BUILD=1` でそれを pull します。 +完全リリースの live media シャードは `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` を使用します。これにはすでに `ffmpeg` と `ffprobe` が含まれています。Docker live モデル/バックエンドシャードは、選択されたコミットごとに一度だけビルドされる共有の `ghcr.io/openclaw/openclaw-live-test:` イメージを使用し、各シャード内で再ビルドする代わりに `OPENCLAW_SKIP_DOCKER_BUILD=1` でそれを pull します。 - `pnpm openclaw qa suite` - - リポジトリに基づく QA シナリオをホスト上で直接実行します。 - - 選択された複数のシナリオを、分離された - Gateway ワーカーでデフォルトで並列実行します。`qa-channel` のデフォルト同時実行数は 4 です（選択された - シナリオ数を上限とします）。ワーカー数を調整するには `--concurrency ` を使用し、 - 以前のシリアルレーンには `--concurrency 1` を使用します。 - - いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしで成果物が必要な場合は - `--allow-failures` を使用します。 - - provider モード `live-frontier`、`mock-openai`、`aimock` をサポートします。 - `aimock` は、シナリオ対応の - `mock-openai` レーンを置き換えずに、実験的な - fixture とプロトコルモックのカバレッジ用にローカルの AIMock ベース provider サーバーを起動します。 + - リポジトリに裏付けられた QA シナリオをホスト上で直接実行します。 + - デフォルトでは、選択された複数のシナリオを、分離された + Gateway ワーカーで並列実行します。`qa-channel` のデフォルト並列数は 4 です + （選択されたシナリオ数が上限）。ワーカー数を調整するには `--concurrency ` を、 + 以前のシリアルレーンを使うには `--concurrency 1` を使用します。 + - いずれかのシナリオが失敗するとゼロ以外で終了します。失敗の終了コードなしで + アーティファクトが必要な場合は `--allow-failures` を使用します。 + - プロバイダーモード `live-frontier`、`mock-openai`、`aimock` をサポートします。 + `aimock` は、シナリオ対応の `mock-openai` レーンを置き換えずに、実験的な + フィクスチャとプロトコルモックのカバレッジ用に、ローカルの AIMock ベースの + プロバイダーサーバーを起動します。 - `pnpm test:gateway:cpu-scenarios` - - Gateway 起動ベンチに加え、小さなモック QA Lab シナリオパック + - Gateway 起動ベンチと小さなモック QA Lab シナリオパック （`channel-chat-baseline`、`memory-failure-fallback`、 `gateway-restart-inflight-run`）を実行し、結合された CPU 観測 サマリーを `.artifacts/gateway-cpu-scenarios/` 配下に書き込みます。 - デフォルトでは持続的な高 CPU 観測のみをフラグします（`--cpu-core-warn` - と `--hot-wall-warn-ms`）。そのため短い起動時バーストは、数分間続く Gateway 固定化回帰のように見えずにメトリクスとして記録されます。 - - ビルド済みの `dist` 成果物を使用します。チェックアウトに新しいランタイム出力がまだない場合は、 - 先にビルドを実行してください。 + と `--hot-wall-warn-ms`）。そのため、短い起動時のバーストは、数分間続く + Gateway 高負荷リグレッションのようには見えず、メトリクスとして記録されます。 + - ビルド済みの `dist` アーティファクトを使用します。チェックアウトに新しい + ランタイム出力がまだない場合は、先にビルドを実行してください。 - `pnpm openclaw qa suite --runner multipass` - - 同じ QA スイートを、使い捨ての Multipass Linux VM 内で実行します。 - - ホスト上の `qa suite` と同じシナリオ選択の挙動を維持します。 - - `qa suite` と同じ provider/model 選択フラグを再利用します。 - - ライブ実行では、ゲストで実用的なサポート対象の QA 認証入力を転送します: - env ベースの provider キー、QA ライブ provider 設定パス、および存在する場合は `CODEX_HOME`。 - - 出力ディレクトリはリポジトリルート配下に留める必要があります。これにより、ゲストがマウントされたワークスペースを通じて書き戻せます。 + - 同じ QA スイートを使い捨ての Multipass Linux VM 内で実行します。 + - ホスト上の `qa suite` と同じシナリオ選択動作を維持します。 + - `qa suite` と同じプロバイダー/モデル選択フラグを再利用します。 + - ライブ実行では、ゲストで実用的なサポート対象の QA 認証入力を転送します。 + env ベースのプロバイダーキー、QA ライブプロバイダー設定パス、および存在する場合の + `CODEX_HOME` です。 + - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるように、 + リポジトリルート配下に置く必要があります。 - 通常の QA レポートとサマリーに加え、Multipass ログを `.artifacts/qa-e2e/...` 配下に書き込みます。 - `pnpm qa:lab:up` - - オペレーター形式の QA 作業用に Docker ベースの QA サイトを起動します。 + - オペレーター形式の QA 作業用に、Docker ベースの QA サイトを起動します。 - `pnpm test:docker:npm-onboard-channel-agent` - - 現在のチェックアウトから npm tarball をビルドし、Docker 内にグローバルインストールし、 - 非対話型の OpenAI API キー オンボーディングを実行し、デフォルトで Telegram を設定し、 - パッケージ化された Plugin ランタイムが起動時の依存関係修復なしで読み込まれることを検証し、 - doctor を実行し、モックされた OpenAI エンドポイントに対してローカル agent turn を 1 回実行します。 - - 同じパッケージ化インストールレーンを Discord で実行するには `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使用します。 + - 現在のチェックアウトから npm tarball をビルドし、Docker 内でグローバルに + インストールし、非対話型の OpenAI API キーオンボーディングを実行し、 + デフォルトで Telegram を設定し、パッケージ化された Plugin ランタイムが + 起動時の依存関係修復なしでロードされることを検証し、doctor を実行し、 + モックされた OpenAI エンドポイントに対して 1 回のローカルエージェントターンを実行します。 + - Discord で同じパッケージ化インストールレーンを実行するには + `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使用します。 - `pnpm test:docker:session-runtime-context` - - 組み込みランタイムコンテキスト transcript 用の決定的なビルド済みアプリ Docker smoke を実行します。非表示の OpenClaw ランタイムコンテキストが、表示される user turn に漏れずに、非表示のカスタムメッセージとして永続化されることを検証し、その後、影響を受ける壊れたセッション JSONL を seed して、 - `openclaw doctor --fix` がバックアップ付きで active branch に書き換えることを検証します。 + - 埋め込みランタイムコンテキストトランスクリプト用に、決定的なビルド済みアプリの + Docker スモークを実行します。非表示の OpenClaw ランタイムコンテキストが、 + 表示されるユーザーターンに漏れず、非表示カスタムメッセージとして永続化されることを検証し、 + その後、影響を受ける壊れたセッション JSONL を投入して、 + `openclaw doctor --fix` がバックアップ付きでアクティブブランチへ書き換えることを検証します。 - `pnpm test:docker:npm-telegram-live` - OpenClaw パッケージ候補を Docker にインストールし、インストール済みパッケージの - オンボーディングを実行し、インストール済み CLI を通じて Telegram を設定し、その後、そのインストール済みパッケージを SUT Gateway として使用して - ライブ Telegram QA レーンを再利用します。 - - デフォルトは `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` です。レジストリからインストールする代わりに - 解決済みのローカル tarball をテストするには、`OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` または + オンボーディングを実行し、インストール済み CLI 経由で Telegram を設定し、 + その後、そのインストール済みパッケージを SUT Gateway として使ってライブ Telegram QA レーンを再利用します。 + - デフォルトは `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` です。 + レジストリからインストールする代わりに、解決済みのローカル tarball をテストするには + `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` または `OPENCLAW_CURRENT_PACKAGE_TGZ` を設定します。 - - `pnpm openclaw qa telegram` と同じ Telegram env 認証情報または Convex 認証情報ソースを使用します。 - CI/リリース自動化では、`OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` に加えて - `OPENCLAW_QA_CONVEX_SITE_URL` と role secret を設定します。 - `OPENCLAW_QA_CONVEX_SITE_URL` と Convex role secret が CI に存在する場合、 - Docker ラッパーは Convex を自動的に選択します。 - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` は、このレーンでのみ共有の + - `pnpm openclaw qa telegram` と同じ Telegram env 認証情報、または Convex + 認証情報ソースを使用します。CI/リリース自動化では、 + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` に加えて + `OPENCLAW_QA_CONVEX_SITE_URL` とロールシークレットを設定します。CI に + `OPENCLAW_QA_CONVEX_SITE_URL` と Convex ロールシークレットがある場合、 + Docker ラッパーは Convex を自動選択します。 + - ラッパーは、Docker のビルド/インストール作業の前に、ホスト上で Telegram または + Convex 認証情報 env を検証します。認証情報前のセットアップを意図的にデバッグする場合にのみ + `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` を設定します。 + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` は、このレーンだけで共有の `OPENCLAW_QA_CREDENTIAL_ROLE` を上書きします。 - - GitHub Actions はこのレーンを手動の maintainer ワークフロー - `NPM Telegram Beta E2E` として公開します。merge 時には実行されません。このワークフローは - `qa-live-shared` environment と Convex CI credential lease を使用します。 -- GitHub Actions は、1 つの候補パッケージに対するサイドラン製品証明用に `Package Acceptance` も公開します。信頼済み ref、公開済み npm spec、 - HTTPS tarball URL と SHA-256、または別の実行からの tarball artifact を受け付け、 - 正規化された `openclaw-current.tgz` を `package-under-test` としてアップロードし、その後、 + - GitHub Actions はこのレーンを手動メンテナー向けワークフロー + `NPM Telegram Beta E2E` として公開します。マージ時には実行されません。このワークフローは + `qa-live-shared` 環境と Convex CI 認証情報リースを使用します。 +- GitHub Actions は、候補パッケージ 1 件に対するサイドランの製品証明として + `Package Acceptance` も公開します。信頼された ref、公開済み npm spec、 + SHA-256 付き HTTPS tarball URL、または別の実行からの tarball アーティファクトを受け付け、 + 正規化された `openclaw-current.tgz` を `package-under-test` としてアップロードし、 既存の Docker E2E スケジューラーを smoke、package、product、full、または custom - レーンプロファイルで実行します。同じ `package-under-test` artifact に対して - Telegram QA ワークフローを実行するには、`telegram_mode=mock-openai` または `live-frontier` を設定します。 - - 最新 beta 製品証明: + レーンプロファイルで実行します。同じ `package-under-test` アーティファクトに対して + Telegram QA ワークフローを実行するには、`telegram_mode=mock-openai` または + `live-frontier` を設定します。 + - 最新ベータの製品証明: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -157,7 +172,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- 正確な tarball URL 証明には digest が必要です: +- 正確な tarball URL 証明にはダイジェストが必要です: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -167,7 +182,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- artifact 証明では、別の Actions 実行から tarball artifact をダウンロードします: +- アーティファクト証明は、別の Actions 実行から tarball アーティファクトをダウンロードします: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -178,24 +193,29 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - 現在の OpenClaw ビルドを Docker 内でパックしてインストールし、OpenAI を設定した状態で Gateway - を起動し、その後、設定編集によってバンドルされたチャンネル/plugins を有効にします。 - - setup discovery が未設定のダウンロード可能 Plugin を不在のままにすること、 - 最初に設定された doctor repair が不足している各ダウンロード可能 - Plugin を明示的にインストールすること、2 回目の restart では隠れた依存関係 - repair が実行されないことを検証します。 - - さらに、既知の古い npm baseline をインストールし、`openclaw update --tag ` を実行する前に Telegram を有効化し、候補の - post-update doctor が harness 側の postinstall repair なしでレガシー Plugin 依存関係の残骸を消去することを検証します。 + - 現在の OpenClaw ビルドを Docker 内でパックしてインストールし、OpenAI が設定された状態で + Gateway を起動し、その後、設定編集によりバンドル済みチャネル/Plugin を有効化します。 + - セットアップ検出で未設定のダウンロード可能 Plugin が存在しないままであること、 + 最初に設定された doctor 修復で不足している各ダウンロード可能 Plugin が明示的にインストールされること、 + 2 回目の再起動で非表示の依存関係修復が実行されないことを検証します。 + - また、既知の古い npm ベースラインをインストールし、 + `openclaw update --tag ` の実行前に Telegram を有効化し、候補の + 更新後 doctor がハーネス側の postinstall 修復なしでレガシー Plugin 依存関係の残骸を + クリーンアップすることを検証します。 - `pnpm test:parallels:npm-update` - - Parallels ゲスト全体で、ネイティブのパッケージ化インストール update smoke を実行します。選択された各 - プラットフォームは、まず要求された baseline パッケージをインストールし、その後同じゲスト内で - インストール済みの `openclaw update` コマンドを実行し、インストール済み version、update status、Gateway readiness、ローカル agent turn 1 回を検証します。 - - 1 つのゲストで反復する間は `--platform macos`、`--platform windows`、または `--platform linux` を使用します。サマリー artifact path と - レーンごとの status には `--json` を使用します。 - - OpenAI レーンは、デフォルトでライブ agent-turn 証明に `openai/gpt-5.5` を使用します。 - 別の OpenAI model を意図的に検証する場合は、`--model ` を渡すか、 + - Parallels ゲスト全体で、ネイティブのパッケージ化インストール更新スモークを実行します。 + 選択された各プラットフォームは、まず要求されたベースラインパッケージをインストールし、 + その後同じゲストでインストール済みの `openclaw update` コマンドを実行し、 + インストール済みバージョン、更新ステータス、Gateway の準備完了状態、1 回のローカル + エージェントターンを検証します。 + - 1 つのゲストで反復する間は、`--platform macos`、`--platform windows`、または + `--platform linux` を使用します。サマリーアーティファクトパスとレーンごとのステータスには + `--json` を使用します。 + - OpenAI レーンは、ライブエージェントターン証明にデフォルトで `openai/gpt-5.5` を使用します。 + 別の OpenAI モデルを意図的に検証する場合は、`--model ` を渡すか、 `OPENCLAW_PARALLELS_OPENAI_MODEL` を設定します。 - - Parallels transport の停止が残りのテスト時間を消費しないように、長いローカル実行はホスト timeout でラップします: + - Parallels トランスポートの停止が残りのテスト時間を消費しないように、長いローカル実行は + ホストタイムアウトでラップします: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json @@ -203,53 +223,52 @@ gh workflow run package-acceptance.yml --ref main \ ``` - このスクリプトは、ネストされたレーンログを `/tmp/openclaw-parallels-npm-update.*` 配下に書き込みます。 - 外側のラッパーがハングしていると判断する前に、`windows-update.log`、`macos-update.log`、または `linux-update.log` - を確認してください。 - - Windows update は、cold guest では post-update doctor と package - update 作業に 10 分から 15 分かかることがあります。ネストされた npm - debug log が進行していれば、それでも正常です。 - - この集約ラッパーを、個別の Parallels - macOS、Windows、または Linux smoke レーンと並列実行しないでください。これらは VM 状態を共有しており、 - snapshot restore、package serving、または guest Gateway 状態で衝突する可能性があります。 - - post-update 証明は通常のバンドル Plugin surface を実行します。これは、 - speech、image generation、media - understanding などの capability facade が、agent turn 自体は単純なテキスト応答だけを確認する場合でも、バンドルされたランタイム API を通じて読み込まれるためです。 + 外側のラッパーがハングしていると判断する前に、`windows-update.log`、`macos-update.log`、 + または `linux-update.log` を確認してください。 + - コールドゲストでは、Windows 更新が更新後 doctor とパッケージ更新作業に 10〜15 分かかることがあります。 + ネストされた npm デバッグログが進んでいるなら、それはまだ正常です。 + - この集約ラッパーを、個別の Parallels macOS、Windows、または Linux スモークレーンと並列に実行しないでください。 + それらは VM 状態を共有しており、スナップショット復元、パッケージ配信、またはゲスト Gateway 状態で衝突する可能性があります。 + - 更新後の証明は、通常のバンドル済み Plugin サーフェスを実行します。これは、エージェントターン自体が + 単純なテキスト応答だけをチェックする場合でも、音声、画像生成、メディア理解などの + ケイパビリティファサードがバンドル済みランタイム API 経由でロードされるためです。 - `pnpm openclaw qa aimock` - - 直接の protocol smoke testing 用に、ローカル AIMock provider server のみを起動します。 + - 直接のプロトコルスモークテスト用に、ローカル AIMock プロバイダーサーバーだけを起動します。 - `pnpm openclaw qa matrix` - - 使い捨ての Docker ベース Tuwunel homeserver に対して Matrix ライブ QA レーンを実行します。source-checkout のみです。パッケージ化インストールには `qa-lab` は含まれません。 - - 完全な CLI、profile/scenario catalog、env vars、artifact layout: [Matrix QA](/ja-JP/concepts/qa-matrix)。 + - 使い捨ての Docker ベース Tuwunel ホームサーバーに対して Matrix ライブ QA レーンを実行します。ソースチェックアウトのみです。パッケージ化インストールには `qa-lab` は含まれません。 + - 完全な CLI、プロファイル/シナリオカタログ、env vars、アーティファクトレイアウト: [Matrix QA](/ja-JP/concepts/qa-matrix)。 - `pnpm openclaw qa telegram` - - env の driver bot token と SUT bot token を使用して、実際のプライベートグループに対して Telegram ライブ QA レーンを実行します。 - - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、および `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。group id は数値の Telegram chat id である必要があります。 - - 共有プール済み認証情報用に `--credential-source convex` をサポートします。デフォルトでは env mode を使用し、プール済み lease を有効にするには `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定します。 - - いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしで成果物が必要な場合は - `--allow-failures` を使用します。 - - 同じプライベートグループ内に 2 つの異なる bot が必要で、SUT bot は Telegram username を公開している必要があります。 - - 安定した bot-to-bot 観測のため、両方の bot で `@BotFather` の Bot-to-Bot Communication Mode を有効にし、driver bot が group bot traffic を観測できることを確認してください。 - - Telegram QA レポート、サマリー、observed-messages artifact を `.artifacts/qa-e2e/...` 配下に書き込みます。replying scenario には、driver send request から観測された SUT reply までの RTT が含まれます。 + - env のドライバーと SUT ボットトークンを使用して、実際の非公開グループに対して Telegram ライブ QA レーンを実行します。 + - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、および `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。グループ ID は数値の Telegram チャット ID である必要があります。 + - 共有プール認証情報には `--credential-source convex` をサポートします。デフォルトでは env モードを使用するか、プールされたリースを有効にするには `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定します。 + - いずれかのシナリオが失敗するとゼロ以外で終了します。失敗の終了コードなしで + アーティファクトが必要な場合は `--allow-failures` を使用します。 + - 同じ非公開グループ内に 2 つの異なるボットが必要で、SUT ボットは Telegram ユーザー名を公開している必要があります。 + - 安定したボット間観測のために、両方のボットで `@BotFather` の Bot-to-Bot Communication Mode を有効化し、ドライバーボットがグループのボットトラフィックを観測できるようにしてください。 + - Telegram QA レポート、サマリー、観測メッセージアーティファクトを `.artifacts/qa-e2e/...` 配下に書き込みます。返信シナリオには、ドライバー送信要求から観測された SUT 返信までの RTT が含まれます。 -ライブ transport レーンは、新しい transport がずれないように 1 つの標準 contract を共有します。レーンごとの coverage matrix は [QA 概要 → ライブ transport カバレッジ](/ja-JP/concepts/qa-e2e-automation#live-transport-coverage) にあります。`qa-channel` は広範な synthetic suite であり、その matrix の一部ではありません。 +ライブトランスポートレーンは、新しいトランスポートが乖離しないように 1 つの標準契約を共有します。レーンごとのカバレッジマトリクスは [QA 概要 → ライブトランスポートカバレッジ](/ja-JP/concepts/qa-e2e-automation#live-transport-coverage) にあります。`qa-channel` は広範な合成スイートであり、そのマトリクスの一部ではありません。 -### Convex 経由の共有 Telegram 認証情報 (v1) +### Convex 経由の共有 Telegram 認証情報（v1） `openclaw qa telegram` で `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）が有効な場合、 -QA lab は Convex ベースの pool から排他的 lease を取得し、レーンの実行中はその lease に Heartbeat を送り、shutdown 時に lease を解放します。 +QA lab は Convex ベースのプールから排他的リースを取得し、レーンの実行中はそのリースに Heartbeat を送り、 +シャットダウン時にリースを解放します。 -参照用 Convex project scaffold: +参照用 Convex プロジェクトスキャフォールド: - `qa/convex-credential-broker/` 必須 env vars: - `OPENCLAW_QA_CONVEX_SITE_URL`（例: `https://your-deployment.convex.site`） -- 選択された role 用の secret 1 つ: +- 選択されたロール用のシークレット 1 つ: - `maintainer` 用の `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` - `ci` 用の `OPENCLAW_QA_CONVEX_SECRET_CI` -- Credential role selection: +- 認証情報ロール選択: - CLI: `--credential-role maintainer|ci` - - Env default: `OPENCLAW_QA_CREDENTIAL_ROLE`（CI ではデフォルトで `ci`、それ以外では `maintainer`） + - Env デフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（CI ではデフォルト `ci`、それ以外では `maintainer`） 任意の env vars: @@ -258,15 +277,15 @@ QA lab は Convex ベースの pool から排他的 lease を取得し、レー - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（デフォルト `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（デフォルト `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（デフォルト `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意の trace id） -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` は、ローカル限定開発用に loopback `http://` Convex URL を許可します。 +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意のトレース ID） +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` は、ローカル専用開発向けに loopback `http://` Convex URL を許可します。 -`OPENCLAW_QA_CONVEX_SITE_URL` は通常運用では `https://` を使用する必要があります。 +通常運用では、`OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使用する必要があります。 -Maintainer admin command（pool add/remove/list）には、特に -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 +メンテナー管理コマンド（プールの追加/削除/一覧）には、 +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が明示的に必要です。 -maintainer 用 CLI helper: +メンテナー向け CLI ヘルパー: ```bash pnpm openclaw qa credentials doctor @@ -275,12 +294,9 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -ライブ実行の前に `doctor` を使用して、Convex site URL、broker secrets、 -endpoint prefix、HTTP timeout、admin/list reachability を、secret 値を出力せずに確認します。 -script と CI -utility で機械可読 output が必要な場合は `--json` を使用します。 +Use `doctor` は、ライブ実行の前に Convex サイト URL、ブローカーシークレット、エンドポイントプレフィックス、HTTP タイムアウト、admin/list 到達性を、シークレット値を出力せずに確認するために使用します。スクリプトや CI ユーティリティで機械可読な出力が必要な場合は `--json` を使用します。 -デフォルトエンドポイント契約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: +デフォルトのエンドポイント契約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: - `POST /acquire` - リクエスト: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -298,12 +314,12 @@ utility で機械可読 output が必要な場合は `--json` を使用します - `POST /admin/remove`（メンテナーシークレットのみ） - リクエスト: `{ credentialId, actorId }` - 成功: `{ status: "ok", changed, credential }` - - アクティブなリースのガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - アクティブリースガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list`（メンテナーシークレットのみ） - リクエスト: `{ kind?, status?, includePayload?, limit? }` - 成功: `{ status: "ok", credentials, count }` -Telegram kind のペイロード形状: +Telegram 種別のペイロード形状: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` は数値の Telegram チャット ID 文字列である必要があります。 @@ -311,52 +327,52 @@ Telegram kind のペイロード形状: ### QA にチャンネルを追加する -新しいチャンネルアダプターのアーキテクチャとシナリオヘルパー名は、[QA 概要 → チャンネルの追加](/ja-JP/concepts/qa-e2e-automation#adding-a-channel) にあります。最低限必要なことは、共有 `qa-lab` ホストシーム上にトランスポートランナーを実装し、Plugin マニフェストで `qaRunners` を宣言し、`openclaw qa ` としてマウントし、`qa/scenarios/` 配下にシナリオを作成することです。 +新しいチャンネルアダプターのアーキテクチャとシナリオヘルパー名は、[QA 概要 → チャンネルを追加する](/ja-JP/concepts/qa-e2e-automation#adding-a-channel) にあります。最低限の条件は、共有 `qa-lab` ホストシーム上にトランスポートランナーを実装し、Plugin マニフェストで `qaRunners` を宣言し、`openclaw qa ` としてマウントし、`qa/scenarios/` 配下にシナリオを作成することです。 ## テストスイート（どこで何が実行されるか） -スイートは「リアリズムが増す」（そして不安定さ/コストも増す）ものとして考えてください。 +これらのスイートは「リアリティの段階的な増加」（およびフレーク性/コストの増加）として考えてください。 ### ユニット / 統合（デフォルト） - コマンド: `pnpm test` -- 設定: ターゲット未指定の実行では `vitest.full-*.config.ts` シャードセットを使用し、並列スケジューリングのためにマルチプロジェクトシャードをプロジェクト単位の設定へ展開する場合があります +- 設定: ターゲット指定なしの実行では `vitest.full-*.config.ts` シャードセットを使用し、並列スケジューリングのためにマルチプロジェクトシャードをプロジェクトごとの設定に展開する場合があります - ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下のコア/ユニットインベントリ。UI ユニットテストは専用の `unit-ui` シャードで実行されます -- スコープ: +- 範囲: - 純粋なユニットテスト - - プロセス内統合テスト（Gateway 認証、ルーティング、ツール、パース、設定） + - インプロセス統合テスト（Gateway 認証、ルーティング、ツール、解析、設定） - 既知のバグに対する決定的な回帰テスト -- 期待事項: +- 期待値: - CI で実行される - 実キーは不要 - - 高速で安定しているべき - - リゾルバーと公開サーフェスのローダーテストは、実際のバンドル済み Plugin ソース API ではなく、生成された小さな Plugin フィクスチャを使って、広範な `api.js` と `runtime-api.js` のフォールバック動作を証明する必要があります。実際の Plugin API ロードは、Plugin 所有の契約/統合スイートに属します。 + - 高速かつ安定しているべき + - リゾルバーと公開サーフェスのローダーテストは、実際の同梱 Plugin ソース API ではなく、生成された小さな Plugin フィクスチャを使って、広範な `api.js` と `runtime-api.js` のフォールバック動作を証明する必要があります。実 Plugin API のロードは、Plugin 所有の契約/統合スイートに属します。 - - ターゲット未指定の `pnpm test` は、巨大な単一のネイティブルートプロジェクトプロセスではなく、12 個の小さなシャード設定（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`）を実行します。これにより、負荷の高いマシンでのピーク RSS が下がり、auto-reply/拡張機能の処理が無関係なスイートを圧迫するのを避けられます。 + - ターゲット指定なしの `pnpm test` は、1 つの巨大なネイティブルートプロジェクトプロセスではなく、12 個の小さなシャード設定（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`）を実行します。これにより、負荷の高いマシンでのピーク RSS が削減され、auto-reply/Plugin 作業が無関係なスイートを飢餓状態にすることを避けます。 - `pnpm test --watch` は引き続きネイティブルートの `vitest.config.ts` プロジェクトグラフを使用します。マルチシャードの watch ループは実用的ではないためです。 - - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリターゲットをまずスコープ付きレーン経由でルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` はルートプロジェクト全体の起動コストを払わずに済みます。 - - `pnpm test:changed` は、変更された git パスをデフォルトで安価なスコープ付きレーンへ展開します。対象は、直接編集されたテスト、兄弟 `*.test.ts` ファイル、明示的なソースマッピング、ローカル import グラフ依存です。設定/セットアップ/パッケージ編集では、明示的に `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用しない限り、広範なテスト実行は行いません。 - - `pnpm check:changed` は、狭い作業向けの通常のスマートローカルチェックゲートです。diff をコア、コアテスト、拡張機能、拡張機能テスト、アプリ、ドキュメント、リリースメタデータ、ライブ Docker ツール、ツールに分類し、対応する型チェック、lint、ガードコマンドを実行します。Vitest テストは実行しません。テストの証明には `pnpm test:changed` または明示的な `pnpm test ` を呼び出してください。リリースメタデータのみのバージョン更新では、ターゲットを絞ったバージョン/設定/ルート依存チェックを実行し、トップレベルのバージョンフィールド以外のパッケージ変更を拒否するガードを含みます。 - - ライブ Docker ACP ハーネスの編集では、ライブ Docker 認証スクリプトのシェル構文と、ライブ Docker スケジューラーのドライランに絞ったチェックを実行します。`package.json` の変更は、diff が `scripts["test:docker:live-*"]` に限定される場合にのみ含まれます。依存関係、export、バージョン、その他のパッケージサーフェス編集では、引き続きより広範なガードを使用します。 - - agents、commands、plugins、auto-reply ヘルパー、`plugin-sdk`、および同様の純粋なユーティリティ領域からの import が軽いユニットテストは、`unit-fast` レーンを通ります。このレーンは `test/setup-openclaw-runtime.ts` をスキップします。状態を持つファイルやランタイム負荷の高いファイルは既存のレーンに留まります。 - - 選択された `plugin-sdk` と `commands` のヘルパーソースファイルも、変更モードの実行をそれらの軽量レーン内の明示的な兄弟テストへマッピングするため、ヘルパー編集時にそのディレクトリの重いスイート全体を再実行せずに済みます。 - - `auto-reply` には、トップレベルのコアヘルパー、トップレベルの `reply.*` 統合テスト、`src/auto-reply/reply/**` サブツリー向けの専用バケットがあります。CI ではさらに、reply サブツリーを agent-runner、dispatch、commands/state-routing シャードに分割し、import 負荷の高い 1 つのバケットが Node のテール全体を占有しないようにしています。 - - 通常の PR/main CI は、拡張機能の一括スイープとリリース専用の `agentic-plugins` シャードを意図的にスキップします。Full Release Validation は、リリース候補に対して Plugin/拡張機能の負荷が高いそれらのスイートを実行するため、別個の `Plugin Prerelease` 子ワークフローをディスパッチします。 + - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリターゲットを最初にスコープ付きレーンへルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` はルートプロジェクト全体の起動コストを払わずに済みます。 + - `pnpm test:changed` は、変更された git パスをデフォルトで低コストのスコープ付きレーンに展開します。直接のテスト編集、兄弟 `*.test.ts` ファイル、明示的なソースマッピング、ローカルインポートグラフ依存先が対象です。設定/セットアップ/パッケージの編集では、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を明示的に使用しない限り、テストは広範囲に実行されません。 + - `pnpm check:changed` は、狭い作業に対する通常のスマートローカルチェックゲートです。差分をコア、コアテスト、Plugin、Plugin テスト、アプリ、ドキュメント、リリースメタデータ、ライブ Docker ツール、ツール類に分類し、対応する型チェック、lint、ガードコマンドを実行します。Vitest テストは実行しません。テスト証明には `pnpm test:changed` または明示的な `pnpm test ` を呼び出してください。リリースメタデータのみのバージョン更新では、対象を絞ったバージョン/設定/ルート依存関係チェックが実行され、トップレベルのバージョンフィールド以外のパッケージ変更を拒否するガードがあります。 + - ライブ Docker ACP ハーネスの編集では、焦点を絞ったチェックが実行されます。ライブ Docker 認証スクリプトのシェル構文と、ライブ Docker スケジューラーのドライランです。`package.json` の変更は、差分が `scripts["test:docker:live-*"]` に限定される場合のみ含まれます。依存関係、export、バージョン、その他のパッケージサーフェス編集では、引き続きより広範なガードが使用されます。 + - エージェント、コマンド、Plugin、auto-reply ヘルパー、`plugin-sdk`、類似の純粋なユーティリティ領域のインポート軽量なユニットテストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンを通ります。ステートフル/ランタイム負荷の高いファイルは既存のレーンに残ります。 + - 選択された `plugin-sdk` と `commands` のヘルパーソースファイルも、変更モード実行をこれらの軽量レーン内の明示的な兄弟テストにマップするため、ヘルパー編集でそのディレクトリの重いスイート全体を再実行せずに済みます。 + - `auto-reply` には、トップレベルのコアヘルパー、トップレベルの `reply.*` 統合テスト、`src/auto-reply/reply/**` サブツリー用の専用バケットがあります。CI ではさらに reply サブツリーを agent-runner、dispatch、commands/state-routing シャードに分割し、インポート負荷の高い 1 つのバケットが Node の末尾全体を占有しないようにします。 + - 通常の PR/main CI は、意図的に Plugin バッチスイープとリリース専用の `agentic-plugins` シャードをスキップします。Full Release Validation は、リリース候補に対して Plugin/Plugin 負荷の高いこれらのスイートを実行する別個の `Plugin Prerelease` 子ワークフローをディスパッチします。 - - メッセージツールの検出入力または Compaction ランタイムコンテキストを変更する場合は、両方のレベルのカバレッジを維持してください。 - - 純粋なルーティングと正規化の境界に対する、焦点を絞ったヘルパー回帰テストを追加してください。 - - 埋め込みランナー統合スイートを正常な状態に保ってください: - `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`、および - `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - これらのスイートは、スコープ付き ID と Compaction の動作が実際の `run.ts` / `compact.ts` パスを通って引き続き流れることを検証します。ヘルパーのみのテストは、それらの統合パスの十分な代替にはなりません。 + - message-tool 探索入力または Compaction ランタイムコンテキストを変更する場合は、両方のレベルのカバレッジを維持してください。 + - 純粋なルーティング境界と正規化境界には、焦点を絞ったヘルパー回帰テストを追加してください。 + - 埋め込みランナー統合スイートを健全に保ってください: + `src/agents/pi-embedded-runner/compact.hooks.test.ts`, + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, and + `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. + - これらのスイートは、スコープ付き ID と Compaction 動作が実際の `run.ts` / `compact.ts` パスを通って流れ続けることを検証します。ヘルパーのみのテストは、これらの統合パスの十分な代替にはなりません。 @@ -364,35 +380,35 @@ Telegram kind のペイロード形状: - ベース Vitest 設定のデフォルトは `threads` です。 - 共有 Vitest 設定は `isolate: false` を固定し、ルートプロジェクト、e2e、ライブ設定全体で非分離ランナーを使用します。 - - ルート UI レーンは `jsdom` セットアップとオプティマイザーを維持しますが、共有の非分離ランナー上でも実行されます。 - - 各 `pnpm test` シャードは、共有 Vitest 設定から同じ `threads` + `isolate: false` のデフォルトを継承します。 - - `scripts/run-vitest.mjs` は、大規模なローカル実行中の V8 コンパイル churn を減らすため、Vitest 子 Node プロセスにデフォルトで `--no-maglev` を追加します。標準の V8 動作と比較するには `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 + - ルート UI レーンは独自の `jsdom` セットアップと optimizer を維持しますが、共有の非分離ランナー上でも実行されます。 + - 各 `pnpm test` シャードは、共有 Vitest 設定から同じ `threads` + `isolate: false` デフォルトを継承します。 + - `scripts/run-vitest.mjs` は、大きなローカル実行中の V8 コンパイル churn を減らすため、デフォルトで Vitest 子 Node プロセスに `--no-maglev` を追加します。標準の V8 動作と比較するには `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 - - `pnpm changed:lanes` は diff がどのアーキテクチャレーンをトリガーするかを表示します。 - - pre-commit フックはフォーマットのみです。フォーマット済みファイルを再ステージし、lint、型チェック、テストは実行しません。 + - `pnpm changed:lanes` は、差分がどのアーキテクチャレーンをトリガーするかを表示します。 + - pre-commit hook はフォーマットのみです。フォーマット済みファイルを再ステージし、lint、型チェック、テストは実行しません。 - スマートローカルチェックゲートが必要な場合は、引き渡しまたは push の前に `pnpm check:changed` を明示的に実行してください。 - - `pnpm test:changed` はデフォルトで安価なスコープ付きレーンを通ります。エージェントがハーネス、設定、パッケージ、または契約の編集に本当に広い Vitest カバレッジが必要だと判断した場合にのみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 - - `pnpm test:max` と `pnpm test:changed:max` は、同じルーティング動作を維持しつつ、worker 上限だけを高くします。 - - ローカル worker の自動スケーリングは意図的に保守的で、ホストのロードアベレージがすでに高い場合は後退するため、複数の Vitest 実行が並行していてもデフォルトでは影響を抑えます。 - - ベース Vitest 設定は、テスト配線が変わったときに変更モードの再実行が正しく保たれるよう、プロジェクト/設定ファイルを `forceRerunTriggers` としてマークします。 - - 設定は、サポート対象ホストで `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効に保ちます。直接プロファイリング用に明示的なキャッシュ場所を 1 つ指定したい場合は、`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 + - `pnpm test:changed` はデフォルトで低コストのスコープ付きレーンを通ります。エージェントがハーネス、設定、パッケージ、契約の編集に本当に広範な Vitest カバレッジが必要だと判断した場合のみ、`OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` を使用してください。 + - `pnpm test:max` と `pnpm test:changed:max` は同じルーティング動作を維持し、worker 上限だけを高くします。 + - ローカル worker の自動スケーリングは意図的に保守的で、ホストのロードアベレージがすでに高い場合は後退するため、複数の同時 Vitest 実行による影響はデフォルトで小さくなります。 + - ベース Vitest 設定は、テスト配線が変更されたときに変更モードの再実行が正しく保たれるよう、プロジェクト/設定ファイルを `forceRerunTriggers` としてマークします。 + - 設定は、サポートされるホストで `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効に保ちます。直接プロファイリング用に明示的なキャッシュ場所を 1 つ指定したい場合は、`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 - - `pnpm test:perf:imports` は、Vitest の import 所要時間レポートと import-breakdown 出力を有効にします。 - - `pnpm test:perf:imports:changed` は、同じプロファイリングビューを `origin/main` 以降に変更されたファイルにスコープします。 - - シャードのタイミングデータは `.artifacts/vitest-shard-timings.json` に書き込まれます。設定全体の実行では設定パスをキーとして使用します。include-pattern CI シャードでは、フィルター済みシャードを個別に追跡できるようシャード名を追加します。 - - 1 つのホットなテストが依然として起動時 import にほとんどの時間を費やしている場合は、重い依存関係を狭いローカル `*.runtime.ts` シームの背後に置き、ランタイムヘルパーを `vi.mock(...)` に通すためだけに深く import するのではなく、そのシームを直接 mock してください。 - - `pnpm test:perf:changed:bench -- --ref ` は、コミット済み diff に対するルーティング済み `test:changed` とネイティブルートプロジェクトパスを比較し、ウォールタイムと macOS 最大 RSS を出力します。 - - `pnpm test:perf:changed:bench -- --worktree` は、変更ファイルリストを `scripts/test-projects.mjs` とルート Vitest 設定へルーティングすることで、現在の dirty tree をベンチマークします。 - - `pnpm test:perf:profile:main` は、Vitest/Vite の起動と変換オーバーヘッドに対するメインスレッド CPU プロファイルを書き出します。 - - `pnpm test:perf:profile:runner` は、ファイル並列を無効にしたユニットスイートの runner CPU+heap プロファイルを書き出します。 + - `pnpm test:perf:imports` は、Vitest のインポート時間レポートと import-breakdown 出力を有効にします。 + - `pnpm test:perf:imports:changed` は、同じプロファイリングビューを `origin/main` 以降に変更されたファイルへスコープします。 + - シャードのタイミングデータは `.artifacts/vitest-shard-timings.json` に書き込まれます。設定全体の実行では設定パスをキーとして使用します。include-pattern CI シャードでは、フィルター済みシャードを個別に追跡できるようにシャード名を追加します。 + - 1 つのホットテストが依然として起動時インポートに時間の大半を費やす場合は、重い依存関係を狭いローカル `*.runtime.ts` シームの背後に置き、単に `vi.mock(...)` に渡すためにランタイムヘルパーをディープインポートするのではなく、そのシームを直接 mock してください。 + - `pnpm test:perf:changed:bench -- --ref ` は、コミット済み差分に対するルーティング済み `test:changed` とネイティブルートプロジェクトパスを比較し、ウォールタイムと macOS 最大 RSS を出力します。 + - `pnpm test:perf:changed:bench -- --worktree` は、変更されたファイルリストを `scripts/test-projects.mjs` とルート Vitest 設定に通すことで、現在の dirty tree をベンチマークします。 + - `pnpm test:perf:profile:main` は、Vitest/Vite の起動と変換オーバーヘッドのためのメインスレッド CPU プロファイルを書き込みます。 + - `pnpm test:perf:profile:runner` は、ファイル並列性を無効にしたユニットスイートの runner CPU+heap プロファイルを書き込みます。 @@ -401,142 +417,143 @@ Telegram kind のペイロード形状: - コマンド: `pnpm test:stability:gateway` - 設定: `vitest.gateway.config.ts`、1 worker に強制 -- スコープ: - - 診断をデフォルトで有効にした実際の loopback Gateway を起動する - - 診断イベントパスを通じて、合成 gateway メッセージ、メモリ、大きなペイロードの churn を駆動する - - Gateway WS RPC 経由で `diagnostics.stability` をクエリする - - 診断安定性バンドルの永続化ヘルパーをカバーする - - レコーダーが上限内に留まり、合成 RSS サンプルが圧力予算内に収まり、セッションごとのキュー深度がゼロへ戻ることをアサートする -- 期待事項: +- 範囲: + - 診断をデフォルトで有効にした実際の loopback Gateway を開始します + - 合成 Gateway メッセージ、メモリ、大容量ペイロード churn を診断イベントパス経由で駆動します + - Gateway WS RPC 経由で `diagnostics.stability` を問い合わせます + - 診断安定性バンドルの永続化ヘルパーをカバーします + - レコーダーが上限内に収まり続けること、合成 RSS サンプルがプレッシャーバジェット未満に留まること、セッションごとのキュー深度がゼロに戻って drain されることをアサートします +- 期待値: - CI セーフでキー不要 - - 安定性回帰のフォローアップ向けの狭いレーンであり、Gateway スイート全体の代替ではない + - 安定性回帰フォローアップ用の狭いレーンであり、Gateway スイート全体の代替ではありません ### E2E（Gateway スモーク） - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` -- ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`、および `extensions/` 配下の bundled-plugin E2E テスト -- ランタイムデフォルト: - - リポジトリの他の部分と同様に、Vitest `threads` を `isolate: false` で使用します。 - - 適応型 worker を使用します（CI: 最大 2、ローカル: デフォルトで 1）。 - - コンソール I/O オーバーヘッドを減らすため、デフォルトで silent モードで実行します。 -- 便利な上書き: - - worker 数を強制するには `OPENCLAW_E2E_WORKERS=`（上限 16）。 - - 詳細なコンソール出力を再有効化するには `OPENCLAW_E2E_VERBOSE=1`。 +- ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`、および `extensions/` 配下のバンドルPlugin E2E テスト +- ランタイムのデフォルト: + - リポジトリの他の部分と同様に、`isolate: false` で Vitest `threads` を使用する。 + - 適応型ワーカーを使用する（CI: 最大 2、ローカル: デフォルトで 1）。 + - コンソール I/O オーバーヘッドを減らすため、デフォルトではサイレントモードで実行する。 +- 便利なオーバーライド: + - `OPENCLAW_E2E_WORKERS=` でワーカー数を強制する（上限 16）。 + - `OPENCLAW_E2E_VERBOSE=1` で詳細なコンソール出力を再有効化する。 - スコープ: - 複数インスタンス Gateway のエンドツーエンド動作 - - WebSocket/HTTP サーフェス、node ペアリング、より重いネットワーキング + - WebSocket/HTTP サーフェス、ノードペアリング、およびより重いネットワーク処理 - 期待事項: - - CI で実行される（パイプラインで有効な場合） - - 実キーは不要 - - ユニットテストより可動部分が多い（遅くなる場合があります） + - CI で実行される（パイプラインで有効化されている場合） + - 実際のキーは不要 + - 単体テストより可動部分が多い（遅くなることがある） ### E2E: OpenShell バックエンドスモーク - コマンド: `pnpm test:e2e:openshell` - ファイル: `extensions/openshell/src/backend.e2e.test.ts` - スコープ: - - Docker 経由でホスト上に分離された OpenShell gateway を開始する - - 一時的なローカル Dockerfile からサンドボックスを作成する + - Docker 経由でホスト上に分離された OpenShell Gateway を起動する + - 一時ローカル Dockerfile からサンドボックスを作成する - 実際の `sandbox ssh-config` + SSH exec を通じて OpenClaw の OpenShell バックエンドを実行する - サンドボックス fs ブリッジを通じてリモート正規ファイルシステム動作を検証する - 期待事項: - オプトインのみ。デフォルトの `pnpm test:e2e` 実行には含まれない - - ローカルの `openshell` CLI と動作中の Docker デーモンが必要 + - ローカルの `openshell` CLI と動作する Docker デーモンが必要 - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テスト Gateway とサンドボックスを破棄する - 便利なオーバーライド: - - 広範な e2e スイートを手動で実行するときにテストを有効化するには `OPENCLAW_E2E_OPENSHELL=1` - - デフォルト以外の CLI バイナリまたはラッパースクリプトを指すには `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` + - `OPENCLAW_E2E_OPENSHELL=1` で、より広い e2e スイートを手動実行するときにテストを有効化する + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` で、デフォルト以外の CLI バイナリまたはラッパースクリプトを指定する -### ライブ（実プロバイダー + 実モデル） +### Live（実プロバイダー + 実モデル） - コマンド: `pnpm test:live` - 設定: `vitest.live.config.ts` -- ファイル: `src/**/*.live.test.ts`、`test/**/*.live.test.ts`、および `extensions/` 配下のバンドル Plugin ライブテスト +- ファイル: `src/**/*.live.test.ts`、`test/**/*.live.test.ts`、および `extensions/` 配下のバンドルPlugin live テスト - デフォルト: `pnpm test:live` により **有効**（`OPENCLAW_LIVE_TEST=1` を設定） - スコープ: - - 「このプロバイダー/モデルは、実際の認証情報で _今日_ 本当に動作するか？」 - - プロバイダー形式の変更、ツール呼び出しの癖、認証の問題、レート制限の挙動を検出する + - 「このプロバイダー/モデルは実際の認証情報で_今日_本当に動作するか？」 + - プロバイダーの形式変更、ツール呼び出しの癖、認証の問題、レート制限の動作を検出する - 期待事項: - 設計上 CI 安定ではない（実ネットワーク、実プロバイダーポリシー、クォータ、障害） - - 費用がかかる / レート制限を使用する - - 「すべて」ではなく、範囲を絞ったサブセットの実行を優先する -- ライブ実行では、不足している API キーを取得するために `~/.profile` を読み込む。 -- デフォルトでは、ライブ実行でも `HOME` を分離し、設定/認証素材を一時テストホームにコピーするため、ユニットフィクスチャが実際の `~/.openclaw` を変更することはできない。 -- ライブテストで実際のホームディレクトリを意図的に使用する必要がある場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定する。 -- `pnpm test:live` は現在、より静かなモードをデフォルトにしている。`[live] ...` の進捗出力は維持するが、追加の `~/.profile` 通知を抑制し、Gateway ブートストラップログ/Bonjour の出力をミュートする。完全な起動ログを戻したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定する。 -- API キーローテーション（プロバイダー固有）: カンマ/セミコロン形式の `*_API_KEYS`、または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）、または `OPENCLAW_LIVE_*_KEY` によるライブごとのオーバーライドを設定する。テストはレート制限レスポンス時に再試行する。 + - 費用がかかる / レート制限を消費する + - 「すべて」ではなく絞り込んだサブセットの実行を推奨 +- Live 実行は、不足している API キーを取得するために `~/.profile` を source する。 +- デフォルトでは、live 実行でも `HOME` を分離し、設定/認証素材を一時テストホームへコピーするため、単体テストのフィクスチャが実際の `~/.openclaw` を変更することはない。 +- live テストで実際のホームディレクトリを使用する必要が意図的にある場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定する。 +- `pnpm test:live` は現在、より静かなモードをデフォルトにしている。`[live] ...` 進捗出力は維持するが、追加の `~/.profile` 通知を抑制し、Gateway ブートストラップログ/Bonjour の雑音をミュートする。完全な起動ログを戻したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定する。 +- API キーローテーション（プロバイダー固有）: カンマ/セミコロン形式の `*_API_KEYS`、または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）、もしくは `OPENCLAW_LIVE_*_KEY` による live ごとのオーバーライドを設定する。テストはレート制限応答時にリトライする。 - 進捗/Heartbeat 出力: - - 長いプロバイダー呼び出しが、Vitest のコンソールキャプチャが静かな場合でもアクティブであることが見えるように、ライブスイートは stderr に進捗行を出力するようになった。 - - `vitest.live.config.ts` は Vitest のコンソールインターセプトを無効化し、ライブ実行中にプロバイダー/Gateway の進捗行が即座にストリームされるようにする。 - - ダイレクトモデルの Heartbeat は `OPENCLAW_LIVE_HEARTBEAT_MS` で調整する。 - - Gateway/プローブの Heartbeat は `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整する。 + - Live スイートは現在、長いプロバイダー呼び出しが Vitest のコンソールキャプチャで静かな場合でも目に見えて動作中と分かるように、進捗行を stderr に出力する。 + - `vitest.live.config.ts` は Vitest のコンソールインターセプトを無効化するため、live 実行中にプロバイダー/Gateway の進捗行がすぐにストリームされる。 + - 直接モデル Heartbeat は `OPENCLAW_LIVE_HEARTBEAT_MS` で調整する。 + - Gateway/プローブ Heartbeat は `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整する。 ## どのスイートを実行すべきか？ この判断表を使用する: -- ロジック/テストを編集している: `pnpm test` を実行する（多く変更した場合は `pnpm test:coverage` も） -- Gateway ネットワーキング / WS プロトコル / ペアリングに触れている: `pnpm test:e2e` を追加する -- 「自分のボットが落ちている」/ プロバイダー固有の失敗 / ツール呼び出しをデバッグしている: 範囲を絞った `pnpm test:live` を実行する +- ロジック/テストを編集している場合: `pnpm test` を実行する（多く変更した場合は `pnpm test:coverage` も） +- Gateway ネットワーク / WS プロトコル / ペアリングに触れている場合: `pnpm test:e2e` を追加する +- 「自分の bot が落ちている」/ プロバイダー固有の失敗 / ツール呼び出しをデバッグしている場合: 絞り込んだ `pnpm test:live` を実行する -## ライブ（ネットワークに触れる）テスト +## Live（ネットワークに触れる）テスト -ライブモデル行列、CLI バックエンドスモーク、ACP スモーク、Codex アプリサーバー -ハーネス、すべてのメディアプロバイダーライブテスト（Deepgram、BytePlus、ComfyUI、画像、 -音楽、動画、メディアハーネス）、およびライブ実行の認証情報処理については、 -[ライブスイートのテスト](/ja-JP/help/testing-live)を参照。専用の更新と +live モデルマトリクス、CLI バックエンドスモーク、ACP スモーク、Codex app-server +ハーネス、およびすべてのメディアプロバイダー live テスト（Deepgram、BytePlus、ComfyUI、画像、 +音楽、動画、メディアハーネス）と、live 実行の認証情報処理については、 +[Live スイートのテスト](/ja-JP/help/testing-live) を参照してください。専用の更新および Plugin 検証チェックリストについては、 -[更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins)を参照。 +[更新とPluginのテスト](/ja-JP/help/testing-updates-plugins) を参照してください。 -## Docker ランナー（任意の「Linux で動作する」チェック） +## Docker ランナー（任意の「Linux で動作する」確認） -これらの Docker ランナーは 2 つのカテゴリに分かれる: +これらの Docker ランナーは 2 つのグループに分かれる: -- ライブモデルランナー: `test:docker:live-models` と `test:docker:live-gateway` は、リポジトリ Docker イメージ内で対応するプロファイルキーのライブファイル（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）のみを実行し、ローカル設定ディレクトリとワークスペースをマウントする（マウントされている場合は `~/.profile` も読み込む）。対応するローカルエントリーポイントは `test:live:models-profiles` と `test:live:gateway-profiles`。 -- Docker ライブランナーは、Docker 全体のスイープを実用的に保つため、デフォルトで小さめのスモーク上限を使用する: +- live モデルランナー: `test:docker:live-models` と `test:docker:live-gateway` は、リポジトリの Docker イメージ内で対応する profile-key live ファイル（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）のみを実行し、ローカルの設定ディレクトリとワークスペースをマウントする（マウントされている場合は `~/.profile` も source する）。対応するローカルエントリポイントは `test:live:models-profiles` と `test:live:gateway-profiles`。 +- Docker live ランナーは、フル Docker スイープを現実的に保つため、デフォルトでより小さいスモーク上限を使用する: `test:docker:live-models` はデフォルトで `OPENCLAW_LIVE_MAX_MODELS=12`、 `test:docker:live-gateway` はデフォルトで `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`、および - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。より大きな網羅的スキャンを明示的に望む場合は、これらの環境変数をオーバーライドする。 -- `test:docker:all` は `test:docker:live-build` 経由でライブ Docker イメージを一度ビルドし、`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw を npm tarball として一度パックし、その後 2 つの `scripts/e2e/Dockerfile` イメージをビルド/再利用する。ベアイメージは install/update/Plugin 依存関係レーン用の Node/Git ランナーのみであり、これらのレーンは事前ビルド済み tarball をマウントする。機能イメージは、ビルド済みアプリ機能レーン用に同じ tarball を `/app` にインストールする。Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーのロジックは `scripts/lib/docker-e2e-plan.mjs` にあり、`scripts/test-docker-all.mjs` が選択されたプランを実行する。集約は重み付きローカルスケジューラーを使用する。`OPENCLAW_DOCKER_ALL_PARALLELISM` がプロセススロットを制御し、リソース上限により重いライブ、npm インストール、マルチサービスレーンがすべて同時に開始しないようにする。単一のレーンがアクティブな上限より重い場合でも、プールが空であればスケジューラーはそれを開始でき、その後、再び容量が利用可能になるまで単独で実行し続ける。デフォルトは 10 スロット、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`、`OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`。Docker ホストに余裕がある場合にのみ、`OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` または `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` を調整する。ランナーはデフォルトで Docker プリフライトを実行し、古い OpenClaw E2E コンテナを削除し、30 秒ごとにステータスを出力し、成功したレーンのタイミングを `.artifacts/docker-tests/lane-timings.json` に保存し、以降の実行でそれらのタイミングを使用して長いレーンを先に開始する。Docker をビルドまたは実行せずに重み付きレーンマニフェストを出力するには `OPENCLAW_DOCKER_ALL_DRY_RUN=1` を使用し、選択されたレーン、パッケージ/イメージ要件、認証情報の CI プランを出力するには `node scripts/test-docker-all.mjs --plan-json` を使用する。 -- `Package Acceptance` は、「このインストール可能な tarball は製品として動作するか？」を確認する GitHub ネイティブのパッケージゲート。`source=npm`、`source=ref`、`source=url`、または `source=artifact` から 1 つの候補パッケージを解決し、それを `package-under-test` としてアップロードし、選択された ref を再パックする代わりに、その正確な tarball に対して再利用可能な Docker E2E レーンを実行する。プロファイルは網羅範囲順に `smoke`、`package`、`product`、`full`。パッケージ/更新/Plugin コントラクト、公開済みアップグレード生存行列、リリースデフォルト、失敗トリアージについては、[更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins)を参照。 -- ビルドおよびリリースチェックは、tsdown 後に `scripts/check-cli-bootstrap-imports.mjs` を実行する。このガードは `dist/entry.js` と `dist/cli/run-main.js` から静的ビルドグラフをたどり、コマンドディスパッチ前の起動処理が Commander、プロンプト UI、undici、ロギングなどのパッケージ依存関係をプリディスパッチで import している場合に失敗する。また、バンドルされた Gateway 実行チャンクを予算内に保ち、既知のコールド Gateway パスの静的 import を拒否する。パッケージ化された CLI スモークは、ルートヘルプ、オンボードヘルプ、doctor ヘルプ、status、config schema、model-list コマンドもカバーする。 -- Package Acceptance のレガシー互換性は `2026.4.25`（`2026.4.25-beta.*` を含む）までに制限される。そのカットオフまでは、ハーネスは出荷済みパッケージのメタデータ欠落のみを許容する。省略されたプライベート QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャ内の欠落したパッチファイル、欠落した永続化 `update.channel`、レガシー Plugin インストール記録の場所、欠落したマーケットプレイスインストール記録の永続化、`plugins update` 中の設定メタデータ移行。`2026.4.25` より後のパッケージでは、これらのパスは厳密な失敗になる。 -- コンテナスモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:update-channel-switch`、`test:docker:upgrade-survivor`、`test:docker:published-upgrade-survivor`、`test:docker:session-runtime-context`、`test:docker:agents-delete-shared-workspace`、`test:docker:gateway-network`、`test:docker:browser-cdp-snapshot`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update`、`test:docker:plugin-lifecycle-matrix`、および `test:docker:config-reload` は、1 つ以上の実コンテナを起動し、より上位の統合パスを検証する。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` を使用する。より大きな網羅的スキャンを明示的に + 望む場合は、これらの環境変数をオーバーライドする。 +- `test:docker:all` は `test:docker:live-build` 経由で live Docker イメージを一度だけビルドし、`scripts/package-openclaw-for-docker.mjs` を通じて OpenClaw を npm tarball として一度だけパックし、その後 2 つの `scripts/e2e/Dockerfile` イメージをビルド/再利用する。bare イメージは install/update/plugin-dependency レーン用の Node/Git ランナーのみであり、これらのレーンは事前ビルド済み tarball をマウントする。functional イメージは同じ tarball を `/app` にインストールし、ビルド済みアプリ機能レーンに使用する。Docker レーン定義は `scripts/lib/docker-e2e-scenarios.mjs` にあり、プランナーロジックは `scripts/lib/docker-e2e-plan.mjs` にあり、`scripts/test-docker-all.mjs` が選択されたプランを実行する。集約は重み付きローカルスケジューラーを使用する。`OPENCLAW_DOCKER_ALL_PARALLELISM` はプロセススロットを制御し、リソース上限は重い live、npm-install、複数サービスレーンがすべて同時に開始しないようにする。単一レーンがアクティブな上限より重い場合でも、プールが空ならスケジューラーはそれを開始でき、その後キャパシティが再び利用可能になるまで単独で実行し続ける。デフォルトは 10 スロット、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`、および `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`。Docker ホストにより余裕がある場合にのみ `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` または `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` を調整する。ランナーはデフォルトで Docker プリフライトを実行し、古い OpenClaw E2E コンテナーを削除し、30 秒ごとにステータスを出力し、成功したレーンのタイミングを `.artifacts/docker-tests/lane-timings.json` に保存し、以降の実行で長いレーンを先に開始するためにそのタイミングを使用する。ビルドや Docker 実行なしで重み付きレーンマニフェストを出力するには `OPENCLAW_DOCKER_ALL_DRY_RUN=1` を使用し、選択されたレーン、パッケージ/イメージ要件、認証情報に関する CI プランを出力するには `node scripts/test-docker-all.mjs --plan-json` を使用する。 +- `Package Acceptance` は「このインストール可能 tarball はプロダクトとして動作するか？」を確認する GitHub ネイティブのパッケージゲート。`source=npm`、`source=ref`、`source=url`、または `source=artifact` から候補パッケージを 1 つ解決し、それを `package-under-test` としてアップロードし、選択された ref を再パックする代わりに、その正確な tarball に対して再利用可能な Docker E2E レーンを実行する。プロファイルは範囲の広さ順に `smoke`、`package`、`product`、`full`。パッケージ/更新/Plugin 契約、公開済みアップグレードのサバイバーマトリクス、リリースデフォルト、失敗トリアージについては、[更新とPluginのテスト](/ja-JP/help/testing-updates-plugins) を参照。 +- ビルドとリリース確認は tsdown 後に `scripts/check-cli-bootstrap-imports.mjs` を実行する。このガードは `dist/entry.js` と `dist/cli/run-main.js` から静的なビルド済みグラフをたどり、コマンドディスパッチ前の起動前インポートが Commander、プロンプト UI、undici、logging などのパッケージ依存関係をインポートしている場合に失敗する。また、バンドルされた Gateway 実行チャンクを予算内に保ち、既知のコールド Gateway パスの静的インポートを拒否する。パッケージ化された CLI スモークは、root help、onboard help、doctor help、status、config schema、および model-list コマンドもカバーする。 +- Package Acceptance のレガシー互換性は `2026.4.25`（`2026.4.25-beta.*` を含む）までに制限される。その期限までは、ハーネスは出荷済みパッケージのメタデータギャップのみを許容する。省略された private QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 派生 git フィクスチャ内の欠落したパッチファイル、欠落した永続化済み `update.channel`、レガシー Plugin インストールレコードの場所、欠落した marketplace インストールレコード永続化、および `plugins update` 中の設定メタデータ移行。`2026.4.25` より後のパッケージでは、これらのパスは厳密な失敗となる。 +- コンテナースモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:update-channel-switch`、`test:docker:upgrade-survivor`、`test:docker:published-upgrade-survivor`、`test:docker:session-runtime-context`、`test:docker:agents-delete-shared-workspace`、`test:docker:gateway-network`、`test:docker:browser-cdp-snapshot`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update`、`test:docker:plugin-lifecycle-matrix`、および `test:docker:config-reload` は、1 つ以上の実コンテナーを起動し、より高レベルの統合パスを検証する。 -ライブモデル Docker ランナーは、必要な CLI 認証ホームのみ（または実行が絞り込まれていない場合はサポート対象のすべて）も bind mount し、実行前にそれらをコンテナホームにコピーするため、外部 CLI の OAuth はホストの認証ストアを変更せずにトークンを更新できる: +live モデル Docker ランナーは、必要な CLI 認証ホームのみ（または実行が絞り込まれていない場合は対応するすべてのもの）も bind mount し、その後、外部 CLI OAuth がホストの認証ストアを変更せずにトークンを更新できるように、実行前にそれらをコンテナーホームへコピーする: - 直接モデル: `pnpm test:docker:live-models` (スクリプト: `scripts/test-live-models-docker.sh`) -- ACP バインドスモーク: `pnpm test:docker:live-acp-bind` (スクリプト: `scripts/test-live-acp-bind-docker.sh`; 既定で Claude、Codex、Gemini をカバーし、`pnpm test:docker:live-acp-bind:droid` と `pnpm test:docker:live-acp-bind:opencode` で厳密な Droid/OpenCode カバレッジを提供) +- ACP バインドスモーク: `pnpm test:docker:live-acp-bind` (スクリプト: `scripts/test-live-acp-bind-docker.sh`; デフォルトで Claude、Codex、Gemini を対象にし、`pnpm test:docker:live-acp-bind:droid` と `pnpm test:docker:live-acp-bind:opencode` によって Droid/OpenCode の厳密なカバレッジを含む) - CLI バックエンドスモーク: `pnpm test:docker:live-cli-backend` (スクリプト: `scripts/test-live-cli-backend-docker.sh`) -- Codex アプリサーバーハーネススモーク: `pnpm test:docker:live-codex-harness` (スクリプト: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + dev エージェント: `pnpm test:docker:live-gateway` (スクリプト: `scripts/test-live-gateway-models-docker.sh`) -- オブザーバビリティスモーク: `pnpm qa:otel:smoke` はプライベートな QA ソースチェックアウトレーンです。npm tarball では QA Lab が省略されるため、意図的にパッケージ Docker リリースレーンには含めていません。 +- Codex app-server ハーネススモーク: `pnpm test:docker:live-codex-harness` (スクリプト: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + 開発エージェント: `pnpm test:docker:live-gateway` (スクリプト: `scripts/test-live-gateway-models-docker.sh`) +- オブザーバビリティスモーク: `pnpm qa:otel:smoke` は非公開 QA ソースチェックアウトレーン。npm tarball には QA Lab が含まれないため、意図的にパッケージ Docker リリースレーンには含めていない。 - Open WebUI ライブスモーク: `pnpm test:docker:openwebui` (スクリプト: `scripts/e2e/openwebui-docker.sh`) - オンボーディングウィザード (TTY、完全なスキャフォールディング): `pnpm test:docker:onboard` (スクリプト: `scripts/e2e/onboard-docker.sh`) -- Npm tarball オンボーディング/チャンネル/エージェントスモーク: `pnpm test:docker:npm-onboard-channel-agent` は、パックされた OpenClaw tarball を Docker 内にグローバルインストールし、env-ref オンボーディングで OpenAI を設定し、既定で Telegram も設定し、doctor を実行して、モックされた OpenAI エージェントターンを 1 回実行します。事前ビルド済み tarball を再利用するには `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` を使い、ホスト再ビルドをスキップするには `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` を使い、チャンネルを切り替えるには `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` を使います。 -- 更新チャンネル切り替えスモーク: `pnpm test:docker:update-channel-switch` は、パックされた OpenClaw tarball を Docker 内にグローバルインストールし、パッケージ `stable` から git `dev` に切り替え、永続化されたチャンネルと更新後の Plugin 動作を検証し、その後パッケージ `stable` に戻して更新ステータスを確認します。 -- アップグレードサバイバースモーク: `pnpm test:docker:upgrade-survivor` は、エージェント、チャンネル設定、Plugin 許可リスト、古い Plugin 依存関係状態、既存のワークスペース/セッションファイルを含む汚れた旧ユーザーフィクスチャの上に、パックされた OpenClaw tarball をインストールします。ライブプロバイダーやチャンネルキーなしでパッケージ更新と非対話型 doctor を実行し、その後ループバック Gateway を起動して、設定/状態の保持に加えて起動/ステータス予算を確認します。 -- 公開済みアップグレードサバイバースモーク: `pnpm test:docker:published-upgrade-survivor` は既定で `openclaw@latest` をインストールし、現実的な既存ユーザーファイルをシードし、組み込みのコマンドレシピでそのベースラインを設定し、結果の設定を検証し、その公開済みインストールを候補 tarball に更新し、非対話型 doctor を実行し、`.artifacts/upgrade-survivor/summary.json` を書き込み、その後ループバック Gateway を起動して、設定済みインテント、状態保持、起動、`/healthz`、`/readyz`、RPC ステータス予算を確認します。1 つのベースラインを上書きするには `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` を使い、集約スケジューラに正確なベースライン展開を求めるには `all-since-2026.4.23` のような `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` を使い、issue 形状のフィクスチャを展開するには `reported-issues` のような `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` を使います。reported-issues セットには、外部 OpenClaw Plugin インストールの自動修復用に `configured-plugin-installs` が含まれます。Package Acceptance では、これらは `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines`、`published_upgrade_survivor_scenarios` として公開されます。 -- セッションランタイムコンテキストスモーク: `pnpm test:docker:session-runtime-context` は、隠しランタイムコンテキストのトランスクリプト永続化に加え、影響を受けた重複プロンプト書き換えブランチの doctor 修復を検証します。 -- Bun グローバルインストールスモーク: `bash scripts/e2e/bun-global-install-smoke.sh` は現在のツリーをパックし、隔離されたホームで `bun install -g` によりインストールし、`openclaw infer image providers --json` がハングせずにバンドル済み画像プロバイダーを返すことを検証します。事前ビルド済み tarball を再利用するには `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` を使い、ホストビルドをスキップするには `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` を使い、ビルド済み Docker イメージから `dist/` をコピーするには `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` を使います。 -- インストーラー Docker スモーク: `bash scripts/test-install-sh-docker.sh` は、root、更新、direct-npm の各コンテナ間で 1 つの npm キャッシュを共有します。更新スモークは、候補 tarball にアップグレードする前の stable ベースラインとして、既定で npm `latest` を使います。ローカルでは `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` で、GitHub では Install Smoke ワークフローの `update_baseline_version` 入力で上書きします。非 root インストーラーチェックは、root 所有のキャッシュエントリがユーザーローカルのインストール動作を隠さないように、隔離された npm キャッシュを保持します。ローカル再実行間で root/update/direct-npm キャッシュを再利用するには `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` を設定します。 -- Install Smoke CI は `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` で重複する direct-npm グローバル更新をスキップします。直接の `npm install -g` カバレッジが必要な場合は、その env なしでローカルにスクリプトを実行してください。 -- エージェント削除共有ワークスペース CLI スモーク: `pnpm test:docker:agents-delete-shared-workspace` (スクリプト: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) は既定でルート Dockerfile イメージをビルドし、隔離されたコンテナホームに 1 つのワークスペースを持つ 2 つのエージェントをシードし、`agents delete --json` を実行して、有効な JSON と保持されたワークスペース動作を検証します。install-smoke イメージを再利用するには `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` を使います。 +- Npm tarball オンボーディング/チャネル/エージェントスモーク: `pnpm test:docker:npm-onboard-channel-agent` は、パック済みの OpenClaw tarball を Docker 内でグローバルにインストールし、env-ref オンボーディングとデフォルトの Telegram を使って OpenAI を設定し、doctor を実行し、モックされた OpenAI エージェントターンを 1 回実行する。事前ビルド済み tarball を `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` で再利用するか、`OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` でホストの再ビルドをスキップするか、`OPENCLAW_NPM_ONBOARD_CHANNEL=discord` でチャネルを切り替える。 +- 更新チャネル切り替えスモーク: `pnpm test:docker:update-channel-switch` は、パック済みの OpenClaw tarball を Docker 内でグローバルにインストールし、パッケージ `stable` から git `dev` に切り替え、永続化されたチャネルと更新後の Plugin 動作を検証してから、パッケージ `stable` に戻して更新ステータスを確認する。 +- アップグレード生存スモーク: `pnpm test:docker:upgrade-survivor` は、エージェント、チャネル設定、Plugin allowlist、古い Plugin 依存関係状態、既存のワークスペース/セッションファイルを含む、汚れた旧ユーザーフィクスチャの上に、パック済みの OpenClaw tarball をインストールする。ライブプロバイダーやチャネルキーなしでパッケージ更新と非対話型 doctor を実行し、その後 loopback Gateway を起動して、設定/状態の保持と起動/ステータスのバジェットを確認する。 +- 公開済みアップグレード生存スモーク: `pnpm test:docker:published-upgrade-survivor` はデフォルトで `openclaw@latest` をインストールし、現実的な既存ユーザーファイルをシードし、組み込みのコマンドレシピでそのベースラインを設定し、結果の設定を検証し、その公開済みインストールを候補 tarball に更新し、非対話型 doctor を実行し、`.artifacts/upgrade-survivor/summary.json` を書き込み、その後 loopback Gateway を起動して、設定済み intent、状態保持、起動、`/healthz`、`/readyz`、RPC ステータスバジェットを確認する。`OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` で 1 つのベースラインを上書きし、`all-since-2026.4.23` のような `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` で集約スケジューラーに正確なベースラインを展開させ、`reported-issues` のような `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` で issue 形式のフィクスチャを展開する。reported-issues セットには、外部 OpenClaw Plugin インストールの自動修復用に `configured-plugin-installs` が含まれる。Package Acceptance はそれらを `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines`、`published_upgrade_survivor_scenarios` として公開する。 +- セッションランタイムコンテキストスモーク: `pnpm test:docker:session-runtime-context` は、非表示ランタイムコンテキストのトランスクリプト永続化と、影響を受ける重複したプロンプト再書き込みブランチの doctor 修復を検証する。 +- Bun グローバルインストールスモーク: `bash scripts/e2e/bun-global-install-smoke.sh` は現在のツリーをパックし、分離されたホームに `bun install -g` でインストールし、`openclaw infer image providers --json` がハングせずにバンドル画像プロバイダーを返すことを検証する。事前ビルド済み tarball を `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` で再利用するか、`OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` でホストビルドをスキップするか、`OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` でビルド済み Docker イメージから `dist/` をコピーする。 +- インストーラー Docker スモーク: `bash scripts/test-install-sh-docker.sh` は、root、update、direct-npm の各コンテナ間で 1 つの npm キャッシュを共有する。更新スモークは、候補 tarball にアップグレードする前の stable ベースラインとして、デフォルトで npm `latest` を使う。ローカルでは `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` で、GitHub では Install Smoke ワークフローの `update_baseline_version` 入力で上書きする。非 root インストーラーチェックでは、root 所有のキャッシュエントリがユーザーローカルのインストール動作を隠さないように、分離された npm キャッシュを維持する。ローカル再実行間で root/update/direct-npm キャッシュを再利用するには、`OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` を設定する。 +- Install Smoke CI は `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` で重複する direct-npm グローバル更新をスキップする。直接 `npm install -g` のカバレッジが必要な場合は、その env なしでローカルにスクリプトを実行する。 +- 共有ワークスペース削除エージェント CLI スモーク: `pnpm test:docker:agents-delete-shared-workspace` (スクリプト: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) はデフォルトで root Dockerfile イメージをビルドし、分離されたコンテナホーム内に 1 つのワークスペースを持つ 2 つのエージェントをシードし、`agents delete --json` を実行し、有効な JSON と保持されたワークスペース動作を検証する。`OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` で install-smoke イメージを再利用する。 - Gateway ネットワーキング (2 コンテナ、WS 認証 + ヘルス): `pnpm test:docker:gateway-network` (スクリプト: `scripts/e2e/gateway-network-docker.sh`) -- ブラウザー CDP スナップショットスモーク: `pnpm test:docker:browser-cdp-snapshot` (スクリプト: `scripts/e2e/browser-cdp-snapshot-docker.sh`) はソース E2E イメージと Chromium レイヤーをビルドし、生の CDP で Chromium を起動し、`browser doctor --deep` を実行して、CDP ロールスナップショットがリンク URL、カーソル昇格されたクリック可能要素、iframe 参照、フレームメタデータをカバーすることを検証します。 -- OpenAI Responses web_search 最小推論リグレッション: `pnpm test:docker:openai-web-search-minimal` (スクリプト: `scripts/e2e/openai-web-search-minimal-docker.sh`) はモックされた OpenAI サーバーを Gateway 経由で実行し、`web_search` が `reasoning.effort` を `minimal` から `low` に引き上げることを検証し、その後プロバイダースキーマ拒否を強制して、生の詳細が Gateway ログに現れることを確認します。 -- MCP チャンネルブリッジ (シード済み Gateway + stdio ブリッジ + 生の Claude 通知フレームスモーク): `pnpm test:docker:mcp-channels` (スクリプト: `scripts/e2e/mcp-channels-docker.sh`) -- Pi バンドル MCP ツール (実際の stdio MCP サーバー + 埋め込み Pi プロファイルの allow/deny スモーク): `pnpm test:docker:pi-bundle-mcp-tools` (スクリプト: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Cron/サブエージェント MCP クリーンアップ (実際の Gateway + 隔離された cron とワンショットサブエージェント実行後の stdio MCP 子プロセス終了): `pnpm test:docker:cron-mcp-cleanup` (スクリプト: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugin (ローカルパス、`file:`、hoisted 依存関係を持つ npm レジストリ、git moving refs、ClawHub kitchen-sink、マーケットプレイス更新、Claude バンドル enable/inspect のインストール/更新スモーク): `pnpm test:docker:plugins` (スクリプト: `scripts/e2e/plugins-docker.sh`) - ClawHub ブロックをスキップするには `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` を設定し、既定の kitchen-sink パッケージ/ランタイムペアを上書きするには `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` と `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` を使います。`OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` がない場合、このテストは hermetic なローカル ClawHub フィクスチャサーバーを使用します。 -- Plugin 更新未変更スモーク: `pnpm test:docker:plugin-update` (スクリプト: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Plugin ライフサイクルマトリックススモーク: `pnpm test:docker:plugin-lifecycle-matrix` は、裸のコンテナにパックされた OpenClaw tarball をインストールし、npm Plugin をインストールし、enable/disable を切り替え、ローカル npm レジストリ経由でアップグレードおよびダウングレードし、インストール済みコードを削除し、その後アンインストールが古い状態を引き続き削除することを検証しながら、各ライフサイクルフェーズの RSS/CPU メトリクスをログに記録します。 +- ブラウザー CDP スナップショットスモーク: `pnpm test:docker:browser-cdp-snapshot` (スクリプト: `scripts/e2e/browser-cdp-snapshot-docker.sh`) はソース E2E イメージと Chromium レイヤーをビルドし、生の CDP で Chromium を起動し、`browser doctor --deep` を実行し、CDP ロールスナップショットがリンク URL、カーソルで昇格されたクリック可能要素、iframe 参照、フレームメタデータを網羅していることを検証する。 +- OpenAI Responses web_search 最小 reasoning リグレッション: `pnpm test:docker:openai-web-search-minimal` (スクリプト: `scripts/e2e/openai-web-search-minimal-docker.sh`) は、モックされた OpenAI サーバーを Gateway 経由で実行し、`web_search` が `reasoning.effort` を `minimal` から `low` に上げることを検証し、その後プロバイダースキーマを強制的に拒否させ、生の詳細が Gateway ログに出現することを確認する。 +- MCP チャネルブリッジ (シード済み Gateway + stdio ブリッジ + 生の Claude 通知フレームスモーク): `pnpm test:docker:mcp-channels` (スクリプト: `scripts/e2e/mcp-channels-docker.sh`) +- Pi バンドル MCP ツール (実 stdio MCP サーバー + 埋め込み Pi プロファイル allow/deny スモーク): `pnpm test:docker:pi-bundle-mcp-tools` (スクリプト: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Cron/サブエージェント MCP クリーンアップ (実 Gateway + 分離 cron と 1 回限りのサブエージェント実行後の stdio MCP 子プロセス終了): `pnpm test:docker:cron-mcp-cleanup` (スクリプト: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (ローカルパス、`file:`、巻き上げられた依存関係を持つ npm レジストリ、git moving refs、ClawHub kitchen-sink、マーケットプレイス更新、Claude バンドルの有効化/検査のインストール/更新スモーク): `pnpm test:docker:plugins` (スクリプト: `scripts/e2e/plugins-docker.sh`) + ClawHub ブロックをスキップするには `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` を設定するか、デフォルトの kitchen-sink パッケージ/ランタイムペアを `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` と `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` で上書きする。`OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` がない場合、テストは hermetic なローカル ClawHub フィクスチャサーバーを使う。 +- Plugin 更新変更なしスモーク: `pnpm test:docker:plugin-update` (スクリプト: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Plugin ライフサイクルマトリックススモーク: `pnpm test:docker:plugin-lifecycle-matrix` は、パック済みの OpenClaw tarball を空のコンテナにインストールし、npm Plugin をインストールし、有効/無効を切り替え、ローカル npm レジストリ経由でアップグレードとダウングレードを行い、インストール済みコードを削除し、その後、各ライフサイクルフェーズの RSS/CPU メトリクスをログに記録しながら、アンインストールが古い状態を引き続き削除することを検証する。 - 設定リロードメタデータスモーク: `pnpm test:docker:config-reload` (スクリプト: `scripts/e2e/config-reload-source-docker.sh`) -- Plugin: `pnpm test:docker:plugins` は、ローカルパス、`file:`、hoisted 依存関係を持つ npm レジストリ、git moving refs、ClawHub フィクスチャ、マーケットプレイス更新、Claude バンドル enable/inspect のインストール/更新スモークをカバーします。`pnpm test:docker:plugin-update` は、インストール済み Plugin の未変更更新動作をカバーします。`pnpm test:docker:plugin-lifecycle-matrix` は、リソース追跡付き npm Plugin のインストール、enable、disable、アップグレード、ダウングレード、欠落コードのアンインストールをカバーします。 +- Plugins: `pnpm test:docker:plugins` は、ローカルパス、`file:`、巻き上げられた依存関係を持つ npm レジストリ、git moving refs、ClawHub フィクスチャ、マーケットプレイス更新、Claude バンドルの有効化/検査のインストール/更新スモークを対象にする。`pnpm test:docker:plugin-update` は、インストール済み Plugin の変更なし更新動作を対象にする。`pnpm test:docker:plugin-lifecycle-matrix` は、リソース追跡付きの npm Plugin のインストール、有効化、無効化、アップグレード、ダウングレード、コード欠落時のアンインストールを対象にする。 共有機能イメージを手動で事前ビルドして再利用するには: @@ -545,98 +562,137 @@ OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker: OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -`OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` のようなスイート固有のイメージ上書きは、設定されている場合は引き続き優先されます。`OPENCLAW_SKIP_DOCKER_BUILD=1` がリモート共有イメージを指している場合、スクリプトはそれがまだローカルにない場合に pull します。QR とインストーラーの Docker テストは、共有ビルド済みアプリランタイムではなくパッケージ/インストール動作を検証するため、独自の Dockerfile を保持します。 +`OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` のようなスイート固有のイメージ上書きは、設定されている場合は引き続き優先される。`OPENCLAW_SKIP_DOCKER_BUILD=1` がリモート共有イメージを指している場合、スクリプトはそれがまだローカルにないときに pull する。QR とインストーラーの Docker テストは、共有ビルド済みアプリランタイムではなく、パッケージ/インストール動作を検証するため、独自の Dockerfile を維持している。 -ライブモデル用の Docker ランナーは、現在のチェックアウトも読み取り専用で bind mount し、コンテナ内の一時 workdir にステージします。これにより、ランタイムイメージを小さく保ちながら、正確なローカルソース/設定に対して Vitest を実行できます。ステージング手順では、`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、アプリローカルの `.build` や Gradle 出力ディレクトリなど、大きなローカル専用キャッシュやアプリのビルド出力をスキップするため、Docker のライブ実行がマシン固有の成果物のコピーに何分も費やすことはありません。また、コンテナ内で Gateway のライブプローブが実際の Telegram/Discord などのチャネルワーカーを起動しないように、`OPENCLAW_SKIP_CHANNELS=1` も設定します。`test:docker:live-models` は引き続き `pnpm test:live` を実行するため、その Docker レーンから Gateway ライブカバレッジを絞り込む、または除外する必要がある場合は、`OPENCLAW_LIVE_GATEWAY_*` も渡してください。`test:docker:openwebui` は、より高レベルの互換性スモークです。OpenAI 互換 HTTP エンドポイントを有効にした OpenClaw Gateway コンテナを起動し、その Gateway に対して固定された Open WebUI コンテナを起動し、Open WebUI 経由でサインインし、`/api/models` が `openclaw/default` を公開していることを確認してから、Open WebUI の `/api/chat/completions` プロキシ経由で実際のチャットリクエストを送信します。初回実行は、Docker が Open WebUI イメージを pull する必要があったり、Open WebUI が自身のコールドスタート設定を完了する必要があったりするため、目に見えて遅くなることがあります。このレーンは使用可能なライブモデルキーを前提としており、Docker 化された実行でそれを提供する主な方法は `OPENCLAW_PROFILE_FILE`（デフォルトは `~/.profile`）です。成功した実行では、`{ "ok": true, "model": "openclaw/default", ... }` のような小さな JSON ペイロードが出力されます。`test:docker:mcp-channels` は意図的に決定論的であり、実際の Telegram、Discord、iMessage アカウントは必要ありません。シード済みの Gateway コンテナを起動し、`openclaw mcp serve` を生成する 2 つ目のコンテナを起動してから、実際の stdio MCP ブリッジ上で、ルーティングされた会話検出、トランスクリプト読み取り、添付ファイルメタデータ、ライブイベントキューの動作、送信ルーティング、Claude 形式のチャネル + 権限通知を検証します。通知チェックは生の stdio MCP フレームを直接検査するため、スモークは特定のクライアント SDK がたまたま表面化するものだけでなく、ブリッジが実際に出力する内容を検証します。`test:docker:pi-bundle-mcp-tools` は決定論的であり、ライブモデルキーは必要ありません。リポジトリの Docker イメージをビルドし、コンテナ内で実際の stdio MCP プローブサーバーを起動し、埋め込み Pi バンドル MCP ランタイムを通じてそのサーバーを具現化し、ツールを実行してから、`coding` と `messaging` は `bundle-mcp` ツールを保持し、`minimal` と `tools.deny: ["bundle-mcp"]` はそれらをフィルターすることを検証します。`test:docker:cron-mcp-cleanup` は決定論的であり、ライブモデルキーは必要ありません。実際の stdio MCP プローブサーバーを備えたシード済み Gateway を起動し、隔離された cron ターンと `/subagents spawn` の 1 回限りの子ターンを実行してから、各実行後に MCP 子プロセスが終了することを検証します。 +ライブモデル Docker ランナーは、現在のチェックアウトも読み取り専用で bind mount し、 +コンテナ内の一時作業ディレクトリにステージングします。これにより、ランタイム +イメージをスリムに保ちながら、正確なローカルソース/設定に対して Vitest を実行できます。 +ステージング手順では、`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、アプリローカルの `.build` や +Gradle 出力ディレクトリなど、大きなローカル専用キャッシュやアプリのビルド出力をスキップするため、 +Docker ライブ実行がマシン固有の成果物のコピーに何分も費やすことはありません。 +また、`OPENCLAW_SKIP_CHANNELS=1` も設定するため、Gateway ライブプローブが +コンテナ内で実際の Telegram/Discord などのチャネルワーカーを開始しません。 +`test:docker:live-models` は引き続き `pnpm test:live` を実行するため、その Docker レーンで +Gateway ライブカバレッジを絞り込む、または除外する必要がある場合は +`OPENCLAW_LIVE_GATEWAY_*` も渡してください。 +`test:docker:openwebui` は、より高レベルの互換性スモークです。OpenAI 互換 HTTP エンドポイントを有効にした +OpenClaw Gateway コンテナを起動し、その Gateway に対して固定された Open WebUI コンテナを起動し、 +Open WebUI 経由でサインインし、`/api/models` が `openclaw/default` を公開していることを検証してから、 +Open WebUI の `/api/chat/completions` プロキシ経由で実際のチャットリクエストを送信します。 +初回実行は、Docker が Open WebUI イメージを pull する必要があり、Open WebUI が自身のコールドスタート設定を完了する必要があるため、 +目に見えて遅くなる場合があります。 +このレーンでは使用可能なライブモデルキーが必要で、`OPENCLAW_PROFILE_FILE` +(デフォルトは `~/.profile`) が Docker 化された実行でそれを提供する主な方法です。 +成功した実行では `{ "ok": true, "model": +"openclaw/default", ... }` のような小さな JSON ペイロードが出力されます。 +`test:docker:mcp-channels` は意図的に決定的であり、実際の +Telegram、Discord、iMessage アカウントは不要です。シード済みの Gateway +コンテナを起動し、`openclaw mcp serve` を生成する 2 つ目のコンテナを開始してから、 +ルーティングされた会話の検出、トランスクリプト読み取り、添付ファイルメタデータ、 +ライブイベントキューの動作、送信ルーティング、および実際の stdio MCP ブリッジ上の Claude 形式のチャネル + +権限通知を検証します。通知チェックは raw stdio MCP フレームを直接検査するため、 +スモークは特定のクライアント SDK がたまたま公開する内容だけでなく、 +ブリッジが実際に発行する内容を検証します。 +`test:docker:pi-bundle-mcp-tools` は決定的であり、ライブモデルキーは不要です。リポジトリの Docker イメージをビルドし、 +コンテナ内で実際の stdio MCP プローブサーバーを起動し、埋め込み Pi bundle +MCP ランタイムを通じてそのサーバーを具現化し、ツールを実行してから、`coding` と `messaging` が +`bundle-mcp` ツールを保持し、`minimal` と `tools.deny: ["bundle-mcp"]` がそれらをフィルターすることを検証します。 +`test:docker:cron-mcp-cleanup` は決定的であり、ライブモデルキーは不要です。実際の stdio MCP プローブサーバーを持つシード済み Gateway を起動し、 +分離された Cron ターンと `/subagents spawn` の 1 回限りの子ターンを実行してから、 +各実行後に MCP 子プロセスが終了することを検証します。 -手動 ACP 平易文スレッドスモーク（CI ではありません）: +手動 ACP 平易言語スレッドスモーク (CI ではありません): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` - このスクリプトは回帰/デバッグワークフロー用に保持してください。ACP スレッドルーティング検証で再び必要になる可能性があるため、削除しないでください。 有用な環境変数: -- `OPENCLAW_CONFIG_DIR=...`（デフォルト: `~/.openclaw`）は `/home/node/.openclaw` にマウントされます -- `OPENCLAW_WORKSPACE_DIR=...`（デフォルト: `~/.openclaw/workspace`）は `/home/node/.openclaw/workspace` にマウントされます -- `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`）は `/home/node/.profile` にマウントされ、テスト実行前に source されます -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` は、一時的な設定/ワークスペースディレクトリを使い、外部 CLI 認証マウントなしで、`OPENCLAW_PROFILE_FILE` から source された環境変数のみを検証します -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）は、Docker 内でのキャッシュ済み CLI インストール用に `/home/node/.npm-global` にマウントされます -- `$HOME` 配下の外部 CLI 認証ディレクトリ/ファイルは `/host-auth...` 配下に読み取り専用でマウントされ、テスト開始前に `/home/node/...` にコピーされます - - デフォルトのディレクトリ: `.minimax` - - デフォルトのファイル: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 絞り込まれたプロバイダー実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推定される必要なディレクトリ/ファイルのみをマウントします - - `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストで手動上書きできます -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` で実行を絞り込みます -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` でコンテナ内のプロバイダーをフィルターします -- `OPENCLAW_SKIP_DOCKER_BUILD=1` は、再ビルドを必要としない再実行で既存の `openclaw:local-live` イメージを再利用します -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` は、認証情報が（env ではなく）プロファイルストアから取得されることを保証します -- `OPENCLAW_OPENWEBUI_MODEL=...` は、Open WebUI スモーク用に Gateway が公開するモデルを選択します -- `OPENCLAW_OPENWEBUI_PROMPT=...` は、Open WebUI スモークで使う nonce チェックプロンプトを上書きします -- `OPENWEBUI_IMAGE=...` は、固定された Open WebUI イメージタグを上書きします +- `OPENCLAW_CONFIG_DIR=...` (デフォルト: `~/.openclaw`) は `/home/node/.openclaw` にマウントされます +- `OPENCLAW_WORKSPACE_DIR=...` (デフォルト: `~/.openclaw/workspace`) は `/home/node/.openclaw/workspace` にマウントされます +- `OPENCLAW_PROFILE_FILE=...` (デフォルト: `~/.profile`) は `/home/node/.profile` にマウントされ、テスト実行前に source されます +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` は、一時的な設定/ワークスペースディレクトリを使用し、外部 CLI 認証マウントなしで、`OPENCLAW_PROFILE_FILE` から source された環境変数だけを検証します +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (デフォルト: `~/.cache/openclaw/docker-cli-tools`) は Docker 内のキャッシュ済み CLI インストール用に `/home/node/.npm-global` にマウントされます +- `$HOME` 配下の外部 CLI 認証ディレクトリ/ファイルは `/host-auth...` 配下に読み取り専用でマウントされ、その後テスト開始前に `/home/node/...` へコピーされます + - デフォルトディレクトリ: `.minimax` + - デフォルトファイル: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` + - 絞り込まれたプロバイダー実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推定された必要なディレクトリ/ファイルのみをマウントします + - `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマリストで手動上書きします +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` は実行を絞り込みます +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` はコンテナ内のプロバイダーをフィルターします +- `OPENCLAW_SKIP_DOCKER_BUILD=1` は、再ビルドが不要な再実行で既存の `openclaw:local-live` イメージを再利用します +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` は、認証情報がプロファイルストアから来ることを保証します (env ではありません) +- `OPENCLAW_OPENWEBUI_MODEL=...` は Open WebUI スモーク用に Gateway が公開するモデルを選択します +- `OPENCLAW_OPENWEBUI_PROMPT=...` は Open WebUI スモークで使用する nonce チェックプロンプトを上書きします +- `OPENWEBUI_IMAGE=...` は固定された Open WebUI イメージタグを上書きします ## ドキュメント健全性 ドキュメント編集後にドキュメントチェックを実行します: `pnpm check:docs`。 -ページ内見出しチェックも必要な場合は、Mintlify の完全なアンカー検証を実行します: `pnpm docs:check-links:anchors`。 +ページ内見出しチェックも必要な場合は、完全な Mintlify アンカー検証を実行します: `pnpm docs:check-links:anchors`。 -## オフライン回帰（CI 安全） +## オフライン回帰 (CI セーフ) -これらは実プロバイダーなしの「実パイプライン」回帰です: +これらは実プロバイダーなしの「実際のパイプライン」回帰です: -- Gateway ツール呼び出し（モック OpenAI、実 Gateway + エージェントループ）: `src/gateway/gateway.test.ts`（ケース: "runs a mock OpenAI tool call end-to-end via gateway agent loop"） -- Gateway ウィザード（WS `wizard.start`/`wizard.next`、設定を書き込み + 認証を強制）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） +- Gateway ツール呼び出し (モック OpenAI、実 Gateway + エージェントループ): `src/gateway/gateway.test.ts` (ケース: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway ウィザード (WS `wizard.start`/`wizard.next`、設定を書き込み + 認証を強制): `src/gateway/gateway.test.ts` (ケース: "runs wizard over ws and writes auth token config") -## エージェント信頼性評価（Skills） +## エージェント信頼性 eval (Skills) -「エージェント信頼性評価」のように振る舞う CI 安全なテストはすでにいくつかあります: +「エージェント信頼性 eval」のように振る舞う CI セーフなテストはすでにいくつかあります: -- 実 Gateway + エージェントループを通したモックツール呼び出し（`src/gateway/gateway.test.ts`）。 -- セッション配線と設定効果を検証するエンドツーエンドのウィザードフロー（`src/gateway/gateway.test.ts`）。 +- 実 Gateway + エージェントループを通じたモックツール呼び出し (`src/gateway/gateway.test.ts`)。 +- セッション配線と設定効果を検証するエンドツーエンドのウィザードフロー (`src/gateway/gateway.test.ts`)。 -Skills でまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: +Skills でまだ不足しているもの ([Skills](/ja-JP/tools/skills) を参照): -- **判断:** Skills がプロンプトに列挙されているとき、エージェントは正しい Skills を選ぶか（または無関係なものを避けるか）？ -- **準拠:** エージェントは使用前に `SKILL.md` を読み、必要な手順/引数に従うか？ +- **意思決定:** プロンプトに Skills が列挙されているとき、エージェントは正しい skill を選ぶか (または無関係なものを避けるか)? +- **準拠:** エージェントは使用前に `SKILL.md` を読み、必須の手順/引数に従うか? - **ワークフロー契約:** ツール順序、セッション履歴の引き継ぎ、サンドボックス境界をアサートするマルチターンシナリオ。 -将来の評価は、まず決定論的であるべきです: +将来の eval は、まず決定的であるべきです: -- モックプロバイダーを使い、ツール呼び出し + 順序、スキルファイル読み取り、セッション配線をアサートするシナリオランナー。 -- スキルに焦点を当てた小さなシナリオスイート（使用 vs 回避、ゲーティング、プロンプトインジェクション）。 -- オプションのライブ評価（オプトイン、env ゲート）は、CI 安全なスイートが整ってからのみ。 +- ツール呼び出し + 順序、skill ファイル読み取り、セッション配線をアサートする、モックプロバイダーを使用したシナリオランナー。 +- skill に焦点を当てた小さなシナリオスイート (使用 vs 回避、ゲート、プロンプトインジェクション)。 +- CI セーフなスイートが整ってからの、任意のライブ eval (オプトイン、env ゲート付き)。 -## 契約テスト（Plugin とチャネル形状） +## 契約テスト (plugin と channel の形状) -契約テストは、登録されたすべての Plugin とチャネルがそれぞれのインターフェース契約に準拠していることを検証します。検出されたすべての Plugin を反復処理し、形状と動作のアサーションスイートを実行します。デフォルトの `pnpm test` ユニットレーンは、これらの共有シームとスモークファイルを意図的にスキップします。共有チャネルまたはプロバイダーのサーフェスに触れた場合は、契約コマンドを明示的に実行してください。 +契約テストは、登録済みのすべての plugin と channel がそれぞれの +インターフェイス契約に準拠していることを検証します。検出されたすべての plugin を反復処理し、 +形状と動作のアサーションスイートを実行します。デフォルトの `pnpm test` unit レーンは、これらの共有境界およびスモークファイルを意図的に +スキップします。共有 channel または provider サーフェスに触れる場合は、契約コマンドを明示的に +実行してください。 ### コマンド - すべての契約: `pnpm test:contracts` -- チャネル契約のみ: `pnpm test:contracts:channels` -- プロバイダー契約のみ: `pnpm test:contracts:plugins` +- Channel 契約のみ: `pnpm test:contracts:channels` +- Provider 契約のみ: `pnpm test:contracts:plugins` -### チャネル契約 +### Channel 契約 `src/channels/plugins/contracts/*.contract.test.ts` にあります: -- **plugin** - 基本的な Plugin 形状（id、name、capabilities） +- **plugin** - 基本的な plugin 形状 (id, name, capabilities) - **setup** - セットアップウィザード契約 - **session-binding** - セッションバインディング動作 - **outbound-payload** - メッセージペイロード構造 - **inbound** - 受信メッセージ処理 -- **actions** - チャネルアクションハンドラー +- **actions** - Channel アクションハンドラー - **threading** - スレッド ID 処理 - **directory** - ディレクトリ/roster API - **group-policy** - グループポリシー強制 -### プロバイダーステータス契約 +### Provider ステータス契約 `src/plugins/contracts/*.contract.test.ts` にあります。 -- **status** - チャネルステータスプローブ +- **status** - Channel ステータスプローブ - **registry** - Plugin レジストリ形状 -### プロバイダー契約 +### Provider 契約 `src/plugins/contracts/*.contract.test.ts` にあります: @@ -645,33 +701,33 @@ Skills でまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参 - **catalog** - モデルカタログ API - **discovery** - Plugin 検出 - **loader** - Plugin 読み込み -- **runtime** - プロバイダーランタイム -- **shape** - Plugin 形状/インターフェース +- **runtime** - Provider ランタイム +- **shape** - Plugin 形状/インターフェイス - **wizard** - セットアップウィザード -### 実行するタイミング +### 実行タイミング -- plugin-sdk の exports または subpaths を変更した後 -- チャネルまたはプロバイダー Plugin を追加または変更した後 -- Plugin 登録または検出をリファクタリングした後 +- plugin-sdk の export または subpath を変更した後 +- channel または provider plugin を追加または変更した後 +- plugin の登録または検出をリファクタリングした後 -契約テストは CI で実行され、実際の API キーは必要ありません。 +契約テストは CI で実行され、実際の API キーは不要です。 -## 回帰の追加（ガイダンス） +## 回帰の追加 (ガイダンス) -ライブで見つかったプロバイダー/モデル問題を修正するとき: +ライブで見つかった provider/model の問題を修正する場合: -- 可能であれば CI 安全な回帰を追加します（モック/スタブプロバイダー、または正確なリクエスト形状変換をキャプチャ） -- 本質的にライブ専用（レート制限、認証ポリシー）の場合は、ライブテストを狭く保ち、env vars 経由のオプトインにします -- バグを検出する最小のレイヤーを対象にすることを優先します: - - プロバイダーリクエスト変換/再生バグ → 直接の models テスト - - Gateway セッション/履歴/ツールパイプラインのバグ → Gateway ライブスモークまたは CI 安全な Gateway モックテスト +- 可能であれば CI セーフな回帰を追加します (モック/スタブ provider、または正確なリクエスト形状変換のキャプチャ) +- 本質的にライブ専用の場合 (レート制限、認証ポリシー)、ライブテストを狭く保ち、環境変数経由のオプトインにします +- バグを捕捉する最小レイヤーを優先して対象にします: + - provider リクエスト変換/リプレイのバグ → 直接の models テスト + - gateway セッション/履歴/ツールパイプラインのバグ → gateway ライブスモークまたは CI セーフな gateway モックテスト - SecretRef トラバーサルガードレール: - - `src/secrets/exec-secret-ref-id-parity.test.ts` は、レジストリメタデータ（`listSecretTargetRegistryEntries()`）から SecretRef クラスごとにサンプリングされたターゲットを 1 つ導出し、トラバーサルセグメントの exec id が拒否されることをアサートします。 - - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef ターゲットファミリーを追加する場合は、そのテストの `classifyTargetClass` を更新してください。新しいクラスが静かにスキップされないように、このテストは未分類のターゲット id で意図的に失敗します。 + - `src/secrets/exec-secret-ref-id-parity.test.ts` は、レジストリメタデータ (`listSecretTargetRegistryEntries()`) から SecretRef クラスごとに 1 つのサンプルターゲットを導出し、トラバーサルセグメント exec id が拒否されることをアサートします。 + - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef ターゲットファミリーを追加する場合は、そのテストの `classifyTargetClass` を更新してください。このテストは未分類のターゲット ID で意図的に失敗するため、新しいクラスを黙ってスキップできません。 ## 関連 - [ライブテスト](/ja-JP/help/testing-live) -- [更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins) +- [更新とプラグインのテスト](/ja-JP/help/testing-updates-plugins) - [CI](/ja-JP/ci) diff --git a/docs/ja-JP/install/updating.md b/docs/ja-JP/install/updating.md index 3efd1bf09..98bce18c8 100644 --- a/docs/ja-JP/install/updating.md +++ b/docs/ja-JP/install/updating.md @@ -1,63 +1,63 @@ --- read_when: - - OpenClawを更新する + - OpenClaw の更新 - 更新後に問題が発生する -summary: OpenClaw を安全に更新する方法（グローバルインストールまたはソースから）とロールバック戦略 +summary: OpenClaw を安全に更新する（グローバルインストールまたはソースから）方法とロールバック戦略 title: 更新 x-i18n: - generated_at: "2026-05-03T21:35:33Z" + generated_at: "2026-05-04T07:03:01Z" model: gpt-5.5 provider: openai - source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1 + source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714 source_path: install/updating.md workflow: 16 --- -OpenClawを最新の状態に保ちます。 +OpenClaw を最新の状態に保ちます。 ## 推奨: `openclaw update` -更新する最速の方法です。インストール種別（npm または git）を検出し、最新バージョンを取得し、`openclaw doctor` を実行して、Gatewayを再起動します。 +更新する最速の方法です。インストール種別 (npm または git) を検出し、最新バージョンを取得し、`openclaw doctor` を実行して、gateway を再起動します。 ```bash openclaw update ``` -チャネルを切り替える、または特定のバージョンを対象にするには: +チャンネルを切り替える、または特定のバージョンを対象にするには: ```bash openclaw update --channel beta openclaw update --channel dev openclaw update --tag main -openclaw update --dry-run # preview without applying +openclaw update --dry-run # 適用せずにプレビュー ``` -`openclaw update` は `--verbose` を受け付けません。更新診断には、予定されている操作をプレビューする `--dry-run`、構造化された結果を得る `--json`、またはチャネルと利用可能状態を確認する `openclaw update status --json` を使用します。インストーラーには独自の `--verbose` フラグがありますが、そのフラグは `openclaw update` の一部ではありません。 +`openclaw update` は `--verbose` を受け付けません。更新診断には、予定されている操作をプレビューする `--dry-run`、構造化された結果を得る `--json`、またはチャンネルと利用可能状態を確認する `openclaw update status --json` を使用してください。インストーラーには独自の `--verbose` フラグがありますが、そのフラグは `openclaw update` の一部ではありません。 -`--channel beta` は beta を優先しますが、beta タグが存在しない場合、または最新の stable リリースより古い場合、ランタイムは stable/latest にフォールバックします。1回限りのパッケージ更新で npm の未加工の beta dist-tag を使いたい場合は、`--tag beta` を使用します。 +`--channel beta` は beta を優先しますが、beta タグがない場合、または最新の安定版リリースより古い場合、runtime は stable/latest にフォールバックします。1 回限りのパッケージ更新で生の npm beta dist-tag を使いたい場合は、`--tag beta` を使用してください。 -チャネルの意味については、[開発チャネル](/ja-JP/install/development-channels)を参照してください。 +チャンネルの意味については、[開発チャンネル](/ja-JP/install/development-channels)を参照してください。 ## npm インストールと git インストールを切り替える -インストール種別を変更したい場合はチャネルを使用します。アップデーターは `~/.openclaw` 内の状態、設定、認証情報、ワークスペースを保持します。変更されるのは、CLI と Gateway が使用する OpenClaw コードのインストールだけです。 +インストール種別を変更したい場合はチャンネルを使用します。アップデーターは `~/.openclaw` 内の状態、設定、認証情報、ワークスペースを保持します。変更するのは、CLI と gateway が使用する OpenClaw コードのインストール先だけです。 ```bash -# npm package install -> editable git checkout +# npm パッケージインストール -> 編集可能な git checkout openclaw update --channel dev -# git checkout -> npm package install +# git checkout -> npm パッケージインストール openclaw update --channel stable ``` -まず `--dry-run` で実行して、正確なインストールモード切り替えをプレビューします。 +正確なインストールモード切り替えをプレビューするには、まず `--dry-run` 付きで実行します: ```bash openclaw update --channel dev --dry-run openclaw update --channel stable --dry-run ``` -`dev` チャネルは git チェックアウトを用意し、それをビルドして、そのチェックアウトからグローバル CLI をインストールします。`stable` と `beta` チャネルはパッケージインストールを使用します。Gateway がすでにインストールされている場合、`--no-restart` を渡さない限り、`openclaw update` はサービスメタデータを更新して再起動します。 +`dev` チャンネルは git checkout を確保し、それをビルドして、その checkout からグローバル CLI をインストールします。`stable` と `beta` チャンネルはパッケージインストールを使用します。gateway がすでにインストールされている場合、`openclaw update` はサービスメタデータを更新し、`--no-restart` を渡さない限り再起動します。 ## 代替: インストーラーを再実行する @@ -67,25 +67,27 @@ curl -fsSL https://openclaw.ai/install.sh | bash オンボーディングをスキップするには `--no-onboard` を追加します。インストーラー経由で特定のインストール種別を強制するには、`--install-method git --no-onboard` または `--install-method npm --no-onboard` を渡します。 -npm パッケージのインストール段階の後に `openclaw update` が失敗した場合は、インストーラーを再実行します。インストーラーは古いアップデーターを呼び出しません。グローバルパッケージのインストールを直接実行し、部分的に更新された npm インストールを復旧できます。 +npm パッケージインストール段階の後で `openclaw update` が失敗した場合は、インストーラーを再実行してください。インストーラーは古いアップデーターを呼び出しません。グローバルパッケージインストールを直接実行し、部分的に更新された npm インストールを復旧できます。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm ``` -復旧を特定のバージョンまたは dist-tag に固定するには、`--version` を追加します。 +復旧を特定のバージョンまたは dist-tag に固定するには、`--version` を追加します: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version ``` -## 代替: 手動の npm、pnpm、または bun +## 代替: 手動で npm、pnpm、または bun を使う ```bash npm i -g openclaw@latest ``` -`openclaw update` がグローバル npm インストールを管理する場合、まず一時的な npm prefix に対象をインストールし、パッケージ化された `dist` インベントリを検証してから、クリーンなパッケージツリーを実際のグローバル prefix に入れ替えます。これにより、npm が古いパッケージの古いファイルの上に新しいパッケージを重ねてしまうことを避けられます。インストールコマンドが失敗した場合、OpenClaw は `--omit=optional` を付けて1回再試行します。この再試行は、ネイティブの任意依存関係をコンパイルできないホストで役立ちます。一方で、フォールバックも失敗した場合は元の失敗が見える状態を保ちます。 +管理下のインストールでは `openclaw update` を推奨します。実行中の Gateway サービスとパッケージ入れ替えを調整できるためです。管理下の Gateway が実行中の状態で手動更新する場合は、パッケージマネージャーの完了直後に Gateway を再起動してください。古いプロセスが置き換え済みのパッケージファイルから提供し続けないようにするためです。 + +`openclaw update` がグローバル npm インストールを管理する場合、まず対象を一時的な npm prefix にインストールし、パッケージ化された `dist` インベントリを検証してから、クリーンなパッケージツリーを実際のグローバル prefix に入れ替えます。これにより、npm が古いパッケージ由来の古いファイルの上に新しいパッケージを重ねることを避けられます。インストールコマンドが失敗した場合、OpenClaw は `--omit=optional` 付きで 1 回再試行します。この再試行は、ネイティブのオプション依存関係をコンパイルできないホストで役立ちます。一方で、フォールバックも失敗した場合は元の失敗が見えるままになります。 ```bash pnpm add -g openclaw@latest @@ -95,17 +97,17 @@ pnpm add -g openclaw@latest bun add -g openclaw@latest ``` -### npm インストールの高度なトピック +### 高度な npm インストールのトピック - OpenClaw は、現在のユーザーがグローバルパッケージディレクトリに書き込める場合でも、パッケージ化されたグローバルインストールを実行時には読み取り専用として扱います。Plugin パッケージのインストール先は、ユーザー設定ディレクトリ配下にある OpenClaw 所有の npm/git ルートです。Gateway の起動時に OpenClaw パッケージツリーは変更されません。 + OpenClaw は、グローバルパッケージディレクトリが現在のユーザーによって書き込み可能な場合でも、パッケージ化されたグローバルインストールを runtime では読み取り専用として扱います。Plugin パッケージインストールは、ユーザー設定ディレクトリ配下の OpenClaw 所有の npm/git ルートに配置され、Gateway 起動時に OpenClaw パッケージツリーは変更されません。 - 一部の Linux npm セットアップでは、`/usr/lib/node_modules/openclaw` など root 所有のディレクトリ配下にグローバルパッケージをインストールします。Plugin のインストール/更新コマンドはそのグローバルパッケージディレクトリの外へ書き込むため、OpenClaw はそのレイアウトをサポートします。 + 一部の Linux npm セットアップでは、`/usr/lib/node_modules/openclaw` のような root 所有ディレクトリ配下にグローバルパッケージをインストールします。Plugin のインストール/更新コマンドはそのグローバルパッケージディレクトリの外側に書き込むため、OpenClaw はそのレイアウトをサポートします。 - 明示的な Plugin インストール、Plugin 更新、doctor クリーンアップが変更を永続化できるように、OpenClaw の設定/状態ルートへの書き込みアクセスを付与します。 + 明示的な Plugin インストール、Plugin 更新、doctor クリーンアップが変更を永続化できるように、OpenClaw に設定/状態ルートへの書き込みアクセス権を与えます: ```ini ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp @@ -113,13 +115,13 @@ bun add -g openclaw@latest - パッケージ更新と明示的な Plugin インストールの前に、OpenClaw は対象ボリュームのディスク容量をベストエフォートで確認しようとします。容量不足の場合は確認されたパスを含む警告が表示されますが、ファイルシステムのクォータ、スナップショット、ネットワークボリュームは確認後に変化する可能性があるため、更新はブロックされません。実際のパッケージマネージャーによるインストールとインストール後の検証が引き続き信頼できる基準です。 + パッケージ更新と明示的な Plugin インストールの前に、OpenClaw は対象ボリュームのディスク容量をベストエフォートで確認しようとします。容量不足の場合は確認したパスとともに警告が出ますが、更新はブロックされません。ファイルシステムのクォータ、スナップショット、ネットワークボリュームは確認後に変わる可能性があるためです。実際のパッケージマネージャーによるインストールとインストール後の検証が引き続き信頼できる根拠です。 ## 自動アップデーター -自動アップデーターはデフォルトではオフです。`~/.openclaw/openclaw.json` で有効にします。 +自動アップデーターはデフォルトではオフです。`~/.openclaw/openclaw.json` で有効にします: ```json5 { @@ -135,16 +137,16 @@ bun add -g openclaw@latest } ``` -| チャネル | 動作 | -| -------- | ------------------------------------------------------------------------------------------------------------- | -| `stable` | `stableDelayHours` 待機し、その後 `stableJitterHours` にわたる決定的ジッター（分散ロールアウト）で適用します。 | -| `beta` | `betaCheckIntervalHours` ごと（デフォルト: 1時間ごと）に確認し、すぐに適用します。 | -| `dev` | 自動適用はありません。`openclaw update` を手動で使用します。 | +| チャンネル | 動作 | +| -------- | ------------------------------------------------------------------------------------------------------------------- | +| `stable` | `stableDelayHours` 待機した後、`stableJitterHours` 全体にわたる決定的なジッターで適用します (段階的ロールアウト)。 | +| `beta` | `betaCheckIntervalHours` ごと (デフォルト: 1 時間ごと) に確認し、即座に適用します。 | +| `dev` | 自動適用はありません。`openclaw update` を手動で使用してください。 | -Gateway は起動時にも更新ヒントをログに出力します（`update.checkOnStart: false` で無効化）。 -ダウングレードやインシデント復旧では、Gateway 環境で `OPENCLAW_NO_AUTO_UPDATE=1` を設定すると、`update.auto.enabled` が設定されていても自動適用をブロックできます。`update.checkOnStart` も無効化されていない限り、起動時の更新ヒントは引き続き実行される可能性があります。 +gateway は起動時にも更新ヒントをログ出力します (`update.checkOnStart: false` で無効化)。 +ダウングレードまたはインシデント復旧では、Gateway 環境で `OPENCLAW_NO_AUTO_UPDATE=1` を設定して、`update.auto.enabled` が設定されている場合でも自動適用をブロックします。`update.checkOnStart` も無効化しない限り、起動時の更新ヒントは引き続き実行できます。 -ライブ Gateway コントロールプレーンハンドラー経由で要求されたパッケージマネージャー更新では、パッケージ入れ替え後に、延期なし、クールダウンなしの更新再起動が強制されます。これにより、すでに置き換え済みのパッケージツリーからチャンクを遅延読み込みするほど古いインメモリプロセスが残ることを避けられます。監督下のインストールでは、更新の前後でサービスを停止および再起動できるため、シェルの `openclaw update` が推奨される経路です。 +稼働中の Gateway コントロールプレーンハンドラー経由で要求されたパッケージマネージャー更新は、パッケージ入れ替え後に、遅延なし、クールダウンなしの更新再起動を強制します。これにより、すでに置き換えられたパッケージツリーからチャンクを遅延読み込みできるほど長く、古いインメモリプロセスが残ることを避けます。Shell の `openclaw update` は、更新の前後でサービスを停止して再起動できるため、管理下のインストールでは引き続き推奨される経路です。 ## 更新後 @@ -156,9 +158,9 @@ Gateway は起動時にも更新ヒントをログに出力します（`update.c openclaw doctor ``` -設定を移行し、DM ポリシーを監査し、Gateway の健全性を確認します。詳細: [Doctor](/ja-JP/gateway/doctor) +設定を移行し、DM ポリシーを監査し、gateway の健全性を確認します。詳細: [Doctor](/ja-JP/gateway/doctor) -### Gateway を再起動する +### gateway を再起動する ```bash openclaw gateway restart @@ -174,7 +176,7 @@ openclaw health ## ロールバック -### バージョンを固定する（npm） +### バージョンを固定する (npm) ```bash npm i -g openclaw@ @@ -186,7 +188,7 @@ openclaw gateway restart `npm view openclaw version` は現在公開されているバージョンを表示します。 -### コミットを固定する（ソース） +### コミットを固定する (source) ```bash git fetch origin @@ -195,17 +197,17 @@ pnpm install && pnpm build openclaw gateway restart ``` -最新へ戻すには: `git checkout main && git pull`。 +最新に戻すには: `git checkout main && git pull`。 ## 行き詰まった場合 -- もう一度 `openclaw doctor` を実行し、出力を注意深く読んでください。 -- ソースチェックアウト上で `openclaw update --channel dev` を実行する場合、必要に応じてアップデーターが `pnpm` を自動ブートストラップします。pnpm/corepack のブートストラップエラーが表示された場合は、`pnpm` を手動でインストールする（または `corepack` を再有効化する）してから、更新を再実行してください。 +- `openclaw doctor` をもう一度実行し、出力を注意深く読んでください。 +- ソース checkout 上で `openclaw update --channel dev` を実行する場合、必要に応じてアップデーターが `pnpm` を自動ブートストラップします。pnpm/corepack のブートストラップエラーが表示された場合は、`pnpm` を手動でインストールする (または `corepack` を再度有効化する) して、更新を再実行してください。 - 確認: [トラブルシューティング](/ja-JP/gateway/troubleshooting) -- Discord で質問する: [https://discord.gg/clawd](https://discord.gg/clawd) +- Discord で質問: [https://discord.gg/clawd](https://discord.gg/clawd) ## 関連 - [インストール概要](/ja-JP/install): すべてのインストール方法。 -- [Doctor](/ja-JP/gateway/doctor): 更新後の健全性チェック。 +- [Doctor](/ja-JP/gateway/doctor): 更新後の健全性確認。 - [移行](/ja-JP/install/migrating): メジャーバージョン移行ガイド。 diff --git a/docs/ja-JP/plugins/google-meet.md b/docs/ja-JP/plugins/google-meet.md index 5bf6afcd0..550e9e9da 100644 --- a/docs/ja-JP/plugins/google-meet.md +++ b/docs/ja-JP/plugins/google-meet.md @@ -1,36 +1,36 @@ --- read_when: - OpenClaw エージェントを Google Meet の通話に参加させたい - - OpenClaw エージェントに新しい Google Meet 通話を作成してほしい場合 - - Chrome、Chrome ノード、または Twilio を Google Meet トランスポートとして設定しています -summary: 'Google Meet Plugin: 明示的な Meet URL に Chrome または Twilio で参加し、エージェントのトークバック既定値を使用' + - OpenClaw エージェントに新しい Google Meet 通話を作成させたい + - Google Meet トランスポートとして Chrome、Chrome ノード、または Twilio を設定しています +summary: 'Google Meet Plugin: 明示的な Meet URL に Chrome または Twilio 経由で参加し、エージェントの音声応答の既定値を使用' title: Google Meet Plugin x-i18n: - generated_at: "2026-05-04T05:00:58Z" + generated_at: "2026-05-04T07:03:52Z" model: gpt-5.5 provider: openai - source_hash: 9caeb2d4540b833c75cd0f3b5f61a99f0a6bb16ca71a96011d25e4ea103a4601 + source_hash: 4268ad895bbf83d649b9571c0888c27eb982ad9710dfb408f22f7818cdc5dbcb source_path: plugins/google-meet.md workflow: 16 --- -Google Meet 参加者サポートの OpenClaw 対応は、Plugin が設計上明示的になっています。 +Google Meet 参加者サポート for OpenClaw — この Plugin は設計上、明示的に動作します。 - 明示的な `https://meet.google.com/...` URL にのみ参加します。 -- Google Meet API を通じて新しい Meet スペースを作成し、その後、返された URL に参加できます。 -- `agent` がデフォルトのトークバックモードです。リアルタイム文字起こしが聞き取り、設定済みの OpenClaw エージェントが応答し、通常の OpenClaw TTS が Meet 内で発話します。 +- Google Meet API を通じて新しい Meet スペースを作成し、返された URL に参加できます。 +- `agent` はデフォルトの応答モードです。リアルタイム文字起こしが聞き取り、設定済みの OpenClaw エージェントが応答し、通常の OpenClaw TTS が Meet に音声を送ります。 - `bidi` は、フォールバックの直接リアルタイム音声モデルモードとして引き続き利用できます。 -- エージェントは `mode` で参加動作を選びます。ライブの聞き取り/トークバックには `agent`、直接リアルタイム音声フォールバックには `bidi`、トークバックブリッジなしでブラウザーに参加/制御するには `transcribe` を使用します。 -- 認証は個人の Google OAuth、またはすでにログイン済みの Chrome プロファイルから始まります。 +- エージェントは `mode` で参加動作を選びます。ライブの聞き取り/応答には `agent`、直接リアルタイム音声フォールバックには `bidi`、応答ブリッジなしでブラウザに参加/制御するには `transcribe` を使います。 +- 認証は個人の Google OAuth、またはすでにサインイン済みの Chrome プロファイルから始まります。 - 自動の同意アナウンスはありません。 - デフォルトの Chrome 音声バックエンドは `BlackHole 2ch` です。 -- Chrome はローカル、またはペアリング済みのノードホスト上で実行できます。 -- Twilio はダイヤルイン番号に加えて、任意の PIN または DTMF シーケンスを受け付けます。Meet URL に直接発信することはできません。 -- CLI コマンドは `googlemeet` です。`meet` はより広いエージェントの電話会議ワークフロー用に予約されています。 +- Chrome はローカルでも、ペアリング済みの Node ホスト上でも実行できます。 +- Twilio はダイヤルイン番号に加えて任意の PIN または DTMF シーケンスを受け付けます。Meet URL に直接ダイヤルすることはできません。 +- CLI コマンドは `googlemeet` です。`meet` は、より広範なエージェントの電話会議ワークフロー用に予約されています。 ## クイックスタート -ローカル音声依存関係をインストールし、リアルタイム文字起こしプロバイダーと通常の OpenClaw TTS を設定します。OpenAI はデフォルトの文字起こしプロバイダーです。Google Gemini Live も、`realtime.voiceProvider: "google"` を使う別の `bidi` 音声フォールバックとして動作します。 +ローカル音声依存関係をインストールし、リアルタイム文字起こしプロバイダーと通常の OpenClaw TTS を設定します。OpenAI はデフォルトの文字起こしプロバイダーです。Google Gemini Live も、`realtime.voiceProvider: "google"` を使う別個の `bidi` 音声フォールバックとして動作します。 ```bash brew install blackhole-2ch sox @@ -52,7 +52,7 @@ system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Plugin を有効化します。 +Plugin を有効にします。 ```json5 { @@ -73,13 +73,13 @@ Plugin を有効化します。 openclaw googlemeet setup ``` -セットアップ出力は、エージェントが読み取れる形式で、モードを認識するようになっています。Chrome プロファイル、ノード固定、そしてリアルタイム Chrome 参加の場合は BlackHole/SoX 音声ブリッジと遅延リアルタイム導入チェックを報告します。観察専用の参加では、同じトランスポートを `--mode transcribe` で確認します。このモードは、ブリッジ経由で聞き取ったり発話したりしないため、リアルタイム音声の前提条件をスキップします。 +セットアップ出力は、エージェントが読める形式で、モードを考慮するようになっています。Chrome プロファイル、Node の固定、そしてリアルタイム Chrome 参加では BlackHole/SoX 音声ブリッジと遅延リアルタイム導入チェックを報告します。観察専用の参加では、同じトランスポートを `--mode transcribe` で確認してください。このモードはブリッジを通じて聞いたり話したりしないため、リアルタイム音声の前提条件をスキップします。 ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` -Twilio 委任が設定されている場合、セットアップは `voice-call` Plugin、Twilio 認証情報、公開 Webhook 公開が準備できているかどうかも報告します。エージェントに参加を依頼する前に、`ok: false` のチェックはすべて、チェック対象のトランスポートとモードに対するブロッカーとして扱います。スクリプトや機械可読出力には `openclaw googlemeet setup --json` を使用します。エージェントが試行する前に特定のトランスポートを事前確認するには、`--transport chrome`、`--transport chrome-node`、または `--transport twilio` を使用します。 +Twilio 委任が設定されている場合、セットアップは `voice-call` Plugin、Twilio 認証情報、公開 Webhook 露出が準備できているかも報告します。エージェントに参加を依頼する前に、`ok: false` のチェックは、そのチェック対象のトランスポートとモードに対するブロッカーとして扱ってください。スクリプトや機械可読出力には `openclaw googlemeet setup --json` を使います。エージェントが試行する前に特定のトランスポートを事前確認するには、`--transport chrome`、`--transport chrome-node`、または `--transport twilio` を使います。 Twilio では、デフォルトトランスポートが Chrome の場合、必ずトランスポートを明示的に事前確認します。 @@ -87,15 +87,15 @@ Twilio では、デフォルトトランスポートが Chrome の場合、必 openclaw googlemeet setup --transport twilio ``` -これにより、エージェントがミーティングに発信しようとする前に、欠落している `voice-call` 接続、Twilio 認証情報、または到達不能な Webhook 公開を検出できます。 +これにより、エージェントが会議にダイヤルしようとする前に、不足している `voice-call` 配線、Twilio 認証情報、または到達不能な Webhook 露出を検出できます。 -ミーティングに参加します。 +会議に参加します。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -または、`google_meet` ツールを通じてエージェントに参加させます。 +または、エージェントに `google_meet` ツール経由で参加させます。 ```json { @@ -106,23 +106,23 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij } ``` -エージェント向けの `google_meet` ツールは、macOS 以外のホストでも、アーティファクト、カレンダー、セットアップ、文字起こし、Twilio、`chrome-node` フロー用に引き続き利用できます。ローカル Chrome のトークバック操作は、バンドルされた Chrome 音声パスが現在 macOS の `BlackHole 2ch` に依存しているため、そこでブロックされます。Linux では、Chrome トークバック参加に `mode: "transcribe"`、Twilio ダイヤルイン、または macOS の `chrome-node` ホストを使用します。 +エージェント向けの `google_meet` ツールは、macOS 以外のホストでも、成果物、カレンダー、セットアップ、文字起こし、Twilio、`chrome-node` フローで引き続き利用できます。ローカル Chrome の応答アクションは、同梱の Chrome 音声パスが現在 macOS の `BlackHole 2ch` に依存しているため、そこではブロックされます。Linux では、Chrome の応答参加に `mode: "transcribe"`、Twilio ダイヤルイン、または macOS の `chrome-node` ホストを使ってください。 -新しいミーティングを作成して参加します。 +新しい会議を作成して参加します。 ```bash openclaw googlemeet create --transport chrome-node --mode agent ``` -API で作成するルームでは、Google アカウントのデフォルトから継承するのではなく、ルームのノック不要ポリシーを明示したい場合に Google Meet `SpaceConfig.accessType` を使用します。 +API で作成したルームについて、Google アカウントのデフォルトから継承するのではなく、ルームのノック不要ポリシーを明示したい場合は Google Meet `SpaceConfig.accessType` を使います。 ```bash openclaw googlemeet create --access-type OPEN --transport chrome-node --mode agent ``` -`OPEN` は Meet URL を持つ誰でもノックなしで参加できるようにします。`TRUSTED` は、ホスト組織の信頼済みユーザー、招待された外部ユーザー、ダイヤルインユーザーがノックなしで参加できるようにします。`RESTRICTED` は、ノックなしの入室を招待者に制限します。これらの設定は公式 Google Meet API 作成パスにのみ適用されるため、OAuth 認証情報を設定する必要があります。 +`OPEN` では、Meet URL を持つ誰でもノックなしで参加できます。`TRUSTED` では、ホスト組織の信頼済みユーザー、招待済みの外部ユーザー、ダイヤルインユーザーがノックなしで参加できます。`RESTRICTED` では、ノック不要の入室が招待者に限定されます。これらの設定は公式の Google Meet API 作成パスにのみ適用されるため、OAuth 認証情報を設定する必要があります。 -このオプションが利用可能になる前に Google Meet を認証していた場合は、Google OAuth 同意画面に `meetings.space.settings` スコープを追加した後、`openclaw googlemeet auth login --json` を再実行してください。 +このオプションが利用可能になる前に Google Meet を認証した場合は、Google OAuth 同意画面に `meetings.space.settings` スコープを追加した後で `openclaw googlemeet auth login --json` を再実行してください。 参加せずに URL だけを作成します。 @@ -132,13 +132,13 @@ openclaw googlemeet create --no-join `googlemeet create` には 2 つのパスがあります。 -- API 作成: Google Meet OAuth 認証情報が設定されている場合に使用されます。これは最も決定的なパスであり、ブラウザー UI の状態に依存しません。 -- ブラウザーフォールバック: OAuth 認証情報がない場合に使用されます。OpenClaw は固定された Chrome ノードを使用し、`https://meet.google.com/new` を開き、Google が実際のミーティングコード URL にリダイレクトするのを待ってから、その URL を返します。このパスでは、ノード上の OpenClaw Chrome プロファイルがすでに Google にログインしている必要があります。ブラウザー自動化は Meet 独自の初回マイクプロンプトを処理します。そのプロンプトは Google ログイン失敗として扱われません。 - 参加フローと作成フローは、新しいタブを開く前に既存の Meet タブの再利用も試みます。照合では `authuser` のような無害な URL クエリ文字列を無視するため、エージェントの再試行では 2 つ目の Chrome タブを作成するのではなく、すでに開いているミーティングにフォーカスするはずです。 +- API 作成: Google Meet OAuth 認証情報が設定されている場合に使われます。これは最も決定的なパスで、ブラウザ UI 状態に依存しません。 +- ブラウザフォールバック: OAuth 認証情報がない場合に使われます。OpenClaw は固定された Chrome Node を使い、`https://meet.google.com/new` を開き、Google が実際の会議コード URL にリダイレクトするのを待ってから、その URL を返します。このパスでは、Node 上の OpenClaw Chrome プロファイルがすでに Google にサインインしている必要があります。ブラウザ自動化は Meet 自体の初回マイクプロンプトを処理します。そのプロンプトは Google ログイン失敗として扱われません。 + 参加フローと作成フローは、新しいタブを開く前に既存の Meet タブの再利用も試みます。照合では `authuser` などの無害な URL クエリ文字列を無視するため、エージェントの再試行は 2 つ目の Chrome タブを作成するのではなく、すでに開いている会議にフォーカスするはずです。 -コマンド/ツール出力には、使用されたパスをエージェントが説明できるように `source` フィールド（`api` または `browser`）が含まれます。`create` はデフォルトで新しいミーティングに参加し、`joined: true` と参加セッションを返します。URL だけを発行するには、CLI で `create --no-join` を使用するか、ツールに `"join": false` を渡します。 +コマンド/ツール出力には `source` フィールド（`api` または `browser`）が含まれるため、エージェントはどちらのパスが使われたかを説明できます。`create` はデフォルトで新しい会議に参加し、`joined: true` と参加セッションを返します。URL だけを発行するには、CLI で `create --no-join` を使うか、ツールに `"join": false` を渡します。 -または、エージェントに「Google Meet を作成し、エージェントのトークバックモードで参加して、リンクを送って」と伝えます。エージェントは `action: "create"` で `google_meet` を呼び出し、返された `meetingUri` を共有する必要があります。 +または、エージェントに「Google Meet を作成し、エージェント応答モードで参加して、リンクを送って」と伝えます。エージェントは `action: "create"` で `google_meet` を呼び出し、返された `meetingUri` を共有する必要があります。 ```json { @@ -148,24 +148,24 @@ openclaw googlemeet create --no-join } ``` -観察専用/ブラウザー制御の参加では、`"mode": "transcribe"` を設定します。これは双方向リアルタイム音声ブリッジを開始せず、BlackHole や SoX を必要とせず、ミーティング内でトークバックしません。このモードの Chrome 参加では、OpenClaw のマイク/カメラ権限付与も回避し、Meet の **マイクを使用** パスも回避します。Meet が音声選択インタースティシャルを表示した場合、自動化はマイクなしのパスを試み、それ以外の場合はローカルマイクを開くのではなく手動操作を報告します。文字起こしモードでは、管理対象 Chrome トランスポートもベストエフォートの Meet キャプション監視をインストールします。`googlemeet status --json` と `googlemeet doctor` は、`captioning`、`captionsEnabledAttempted`、`transcriptLines`、`lastCaptionAt`、`lastCaptionSpeaker`、`lastCaptionText`、短い `recentTranscript` 末尾を表示するため、オペレーターはブラウザーが通話に参加したかどうか、Meet キャプションがテキストを生成しているかどうかを判断できます。 -はい/いいえのプローブが必要な場合は、`openclaw googlemeet test-listen --transport chrome-node` を使用します。これは文字起こしモードで参加し、新しいキャプションまたは文字起こしの動きを待ち、`listenVerified`、`listenTimedOut`、手動操作フィールド、最新のキャプション健全性を返します。 +観察専用/ブラウザ制御の参加では、`"mode": "transcribe"` を設定します。これは双方向リアルタイム音声ブリッジを開始せず、BlackHole や SoX を必要とせず、会議に応答音声を返しません。このモードでの Chrome 参加は、OpenClaw のマイク/カメラ権限付与と Meet の **マイクを使用** パスも回避します。Meet が音声選択インタースティシャルを表示した場合、自動化はマイクなしパスを試み、それができない場合はローカルマイクを開くのではなく手動操作を報告します。transcribe モードでは、管理対象 Chrome トランスポートもベストエフォートの Meet キャプション監視をインストールします。`googlemeet status --json` と `googlemeet doctor` は、`captioning`、`captionsEnabledAttempted`、`transcriptLines`、`lastCaptionAt`、`lastCaptionSpeaker`、`lastCaptionText`、短い `recentTranscript` 末尾を表示するため、オペレーターはブラウザが通話に参加したか、Meet キャプションがテキストを生成しているかを判断できます。 +はい/いいえのプローブが必要な場合は、`openclaw googlemeet test-listen --transport chrome-node` を使ってください。これは transcribe モードで参加し、新しいキャプションまたは文字起こしの動きを待ち、`listenVerified`、`listenTimedOut`、手動操作フィールド、最新のキャプション健全性を返します。 -リアルタイムセッション中、`google_meet` のステータスには、`inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最終入力/出力タイムスタンプ、バイトカウンター、ブリッジ終了状態など、ブラウザーと音声ブリッジの健全性が含まれます。安全な Meet ページプロンプトが表示された場合、ブラウザー自動化は可能なときにそれを処理します。ログイン、ホスト承認、ブラウザー/OS 権限プロンプトは、エージェントが中継するための理由とメッセージ付きで手動操作として報告されます。管理対象 Chrome セッションは、ブラウザーの健全性が `inCall: true` を報告した後にのみ導入文またはテストフレーズを送出します。それ以外の場合、ステータスは `speechReady: false` を報告し、エージェントがミーティング内で発話したふりをするのではなく、発話試行をブロックします。 +リアルタイムセッション中、`google_meet` のステータスには、`inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最後の入力/出力タイムスタンプ、バイトカウンター、ブリッジのクローズ状態など、ブラウザと音声ブリッジの健全性が含まれます。安全な Meet ページプロンプトが表示された場合、ブラウザ自動化は可能なときにそれを処理します。ログイン、ホスト承認、ブラウザ/OS 権限プロンプトは、エージェントが伝えられる理由とメッセージ付きの手動操作として報告されます。管理対象 Chrome セッションは、ブラウザの健全性が `inCall: true` を報告した後にのみ導入文やテストフレーズを出力します。それ以外の場合、ステータスは `speechReady: false` を報告し、エージェントが会議に話したふりをするのではなく発話試行をブロックします。 -ローカル Chrome 参加は、ログイン済みの OpenClaw ブラウザープロファイルを通じて行われます。リアルタイムモードでは、OpenClaw が使用するマイク/スピーカーパスに `BlackHole 2ch` が必要です。クリーンな双方向音声には、別々の仮想デバイス、または Loopback 形式のグラフを使用します。単一の BlackHole デバイスでも最初のスモークテストには十分ですが、エコーが発生する場合があります。 +ローカル Chrome は、サインイン済みの OpenClaw ブラウザプロファイルを通じて参加します。リアルタイムモードでは、OpenClaw が使うマイク/スピーカーパスに `BlackHole 2ch` が必要です。クリーンな双方向音声には、別々の仮想デバイスまたは Loopback スタイルのグラフを使います。最初のスモークテストには単一の BlackHole デバイスで十分ですが、エコーする可能性があります。 ### ローカル Gateway + Parallels Chrome -VM に Chrome を所有させるだけなら、macOS VM 内に完全な OpenClaw Gateway やモデル API キーは必要ありません。Gateway とエージェントはローカルで実行し、VM ではノードホストを実行します。VM 上でバンドル Plugin を一度有効化し、ノードが Chrome コマンドを広告するようにします。 +VM に Chrome を所有させるだけなら、macOS VM 内に完全な OpenClaw Gateway やモデル API キーは必要ありません。Gateway とエージェントはローカルで実行し、VM 内で Node ホストを実行します。VM 上で同梱 Plugin を一度有効にして、Node が Chrome コマンドを広告するようにします。 どこで何を実行するか: - Gateway ホスト: OpenClaw Gateway、エージェントワークスペース、モデル/API キー、リアルタイムプロバイダー、Google Meet Plugin 設定。 -- Parallels macOS VM: OpenClaw CLI/ノードホスト、Google Chrome、SoX、BlackHole 2ch、Google にログイン済みの Chrome プロファイル。 +- Parallels macOS VM: OpenClaw CLI/Node ホスト、Google Chrome、SoX、BlackHole 2ch、Google にサインイン済みの Chrome プロファイル。 - VM で不要なもの: Gateway サービス、エージェント設定、OpenAI/GPT キー、モデルプロバイダー設定。 -VM の依存関係をインストールします。 +VM 依存関係をインストールします。 ```bash brew install blackhole-2ch sox @@ -184,26 +184,26 @@ system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -VM に OpenClaw をインストールまたは更新し、そこでバンドル Plugin を有効化します。 +VM に OpenClaw をインストールまたは更新し、そこで同梱 Plugin を有効にします。 ```bash openclaw plugins enable google-meet ``` -VM でノードホストを開始します。 +VM 内で Node ホストを起動します。 ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -`` が LAN IP で、TLS を使用していない場合、その信頼済みプライベートネットワークに明示的にオプトインしない限り、ノードは平文 WebSocket を拒否します。 +`` が LAN IP で TLS を使っていない場合、その信頼済みプライベートネットワークにオプトインしない限り、Node は平文 WebSocket を拒否します。 ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -ノードを LaunchAgent としてインストールする場合も、同じ環境変数を使用します。 +Node を LaunchAgent としてインストールするときも同じ環境変数を使います。 ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -211,22 +211,22 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` はプロセス環境であり、`openclaw.json` 設定ではありません。`openclaw node install` は、インストールコマンド上に存在する場合、それを LaunchAgent 環境に保存します。 +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` はプロセス環境であり、`openclaw.json` 設定ではありません。`openclaw node install` は、インストールコマンドに存在する場合、それを LaunchAgent 環境に保存します。 -Gateway ホストからノードを承認します。 +Gateway ホストから Node を承認します。 ```bash openclaw devices list openclaw devices approve ``` -Gateway がノードを認識し、`googlemeet.chrome` とブラウザー機能/`browser.proxy` の両方を広告していることを確認します。 +Gateway が Node を認識し、`googlemeet.chrome` とブラウザ機能/`browser.proxy` の両方を広告していることを確認します。 ```bash openclaw nodes status ``` -Gateway ホストで、そのノード経由に Meet をルーティングします。 +Gateway ホストで、その Node 経由に Meet をルーティングします。 ```json5 { @@ -256,110 +256,108 @@ Gateway ホストで、そのノード経由に Meet をルーティングしま } ``` -これで Gateway ホストから通常どおり参加します。 +これで Gateway ホストから通常どおり参加できます。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -または、`transport: "chrome-node"` で `google_meet` ツールを使用するようエージェントに依頼します。 +または、エージェントに `transport: "chrome-node"` で `google_meet` ツールを使うよう依頼します。 -セッションを作成または再利用し、既知のフレーズを発話し、セッションの健全性を出力する 1 コマンドのスモークテストは次のとおりです。 +セッションを作成または再利用し、既知のフレーズを話し、セッション健全性を表示するワンコマンドのスモークテストは次のとおりです。 ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -リアルタイム参加時、OpenClaw のブラウザー自動化はゲスト名を入力し、 -Join/Ask to join をクリックし、そのプロンプトが表示された場合は Meet の初回実行時の -「Use microphone」選択を受け入れます。観察専用の参加またはブラウザーのみでのミーティング作成時は、 -同じプロンプトで、利用可能な場合はマイクなしの選択を使って先へ進みます。 +リアルタイム参加中、OpenClaw ブラウザー自動化はゲスト名を入力し、 +「参加」/「参加をリクエスト」をクリックし、そのプロンプトが表示された場合は +Meet の初回実行時の「マイクを使用」選択を受け入れます。観察のみの参加またはブラウザーのみの会議作成中は、 +同じプロンプトで、マイクなしの選択肢が利用可能な場合にそれを選んで続行します。 ブラウザープロファイルがサインインしていない、Meet がホストの承認を待っている、 -リアルタイム参加のために Chrome がマイク/カメラ権限を必要としている、または -Meet が自動化で解決できないプロンプトで停止している場合、参加/test-speech の結果は +リアルタイム参加のために Chrome がマイク/カメラ権限を必要としている、または Meet が +自動化で解決できないプロンプトで停止している場合、参加/test-speech の結果は `manualActionRequired: true` を `manualActionReason` および `manualActionMessage` とともに報告します。エージェントは参加の再試行を停止し、 -その正確なメッセージに現在の `browserUrl`/`browserTitle` を添えて報告し、 -手動のブラウザー操作が完了した後にのみ再試行する必要があります。 +その正確なメッセージと現在の `browserUrl`/`browserTitle` を報告し、手動のブラウザー操作が完了した後にのみ再試行する必要があります。 -`chromeNode.node` が省略されている場合、OpenClaw は、接続済みノードのうち -`googlemeet.chrome` とブラウザー制御の両方を公開しているものがちょうど1つだけの場合にのみ自動選択します。 -対応可能なノードが複数接続されている場合は、`chromeNode.node` にノード ID、 -表示名、またはリモート IP を設定します。 +`chromeNode.node` が省略された場合、OpenClaw は、接続済みノードがちょうど 1 つだけ +`googlemeet.chrome` とブラウザー制御の両方を広告している場合にのみ自動選択します。 +対応可能なノードが複数接続されている場合は、`chromeNode.node` をノード ID、 +表示名、またはリモート IP に設定します。 一般的な失敗チェック: - `Configured Google Meet node ... is not usable: offline`: 固定されたノードは Gateway に認識されていますが利用できません。エージェントはそのノードを - 使用可能な Chrome ホストではなく診断状態として扱い、ユーザーが求めていない限り - 別のトランスポートへフォールバックせず、セットアップ上のブロッカーを報告する必要があります。 -- `No connected Google Meet-capable node`: VM 内で `openclaw node run` を起動し、 + 利用可能な Chrome ホストではなく診断状態として扱い、ユーザーが要求していない限り + 別のトランスポートへフォールバックせずにセットアップのブロッカーを報告する必要があります。 +- `No connected Google Meet-capable node`: VM 内で `openclaw node run` を開始し、 ペアリングを承認し、VM 内で `openclaw plugins enable google-meet` と `openclaw plugins enable browser` が実行済みであることを確認します。また、 Gateway ホストが `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` - によって両方のノードコマンドを許可していることも確認します。 + で両方のノードコマンドを許可していることも確認します。 - `BlackHole 2ch audio device not found`: チェック対象のホストに `blackhole-2ch` - をインストールし、ローカル Chrome 音声を使用する前に再起動します。 + をインストールし、ローカル Chrome 音声を使う前に再起動します。 - `BlackHole 2ch audio device not found on the node`: VM 内に `blackhole-2ch` をインストールし、VM を再起動します。 - Chrome は開くが参加できない: VM 内のブラウザープロファイルにサインインするか、 - ゲスト参加用に `chrome.guestName` を設定したままにします。ゲスト自動参加は、 - ノードのブラウザープロキシを通じて OpenClaw のブラウザー自動化を使用します。 - ノードのブラウザー設定が目的のプロファイルを指していることを確認してください。たとえば - `browser.defaultProfile: "user"`、または名前付きの既存セッションプロファイルです。 -- Meet タブの重複: `chrome.reuseExistingTab: true` を有効にしたままにします。OpenClaw は - 新しいタブを開く前に同じ Meet URL の既存タブをアクティブ化し、 - ブラウザーでのミーティング作成では、別のタブを開く前に進行中の - `https://meet.google.com/new` または Google アカウントプロンプトのタブを再利用します。 + ゲスト参加用に `chrome.guestName` を設定したままにします。ゲストの自動参加は、 + ノードのブラウザープロキシ経由で OpenClaw ブラウザー自動化を使用します。ノードのブラウザー設定が、 + 目的のプロファイルを指していることを確認してください。例: + `browser.defaultProfile: "user"` または名前付きの既存セッションプロファイル。 +- Meet タブが重複する: `chrome.reuseExistingTab: true` を有効のままにします。OpenClaw は + 新しいタブを開く前に同じ Meet URL の既存タブをアクティブ化し、ブラウザーによる会議作成では、 + 別のタブを開く前に進行中の `https://meet.google.com/new` + または Google アカウントプロンプトのタブを再利用します。 - 音声がない: Meet で、マイク/スピーカーを OpenClaw が使用する仮想音声デバイスパスにルーティングします。 - クリーンな双方向音声には、別々の仮想デバイスまたは Loopback 形式のルーティングを使用します。 + クリーンな双方向音声には、個別の仮想デバイスまたは Loopback 形式のルーティングを使用します。 -## インストールの注意事項 +## インストールメモ -Chrome のトークバックのデフォルトは、2つの外部ツールを使用します。 +Chrome のトークバック既定値は 2 つの外部ツールを使用します: -- `sox`: コマンドライン音声ユーティリティ。この Plugin は、デフォルトの 24 kHz PCM16 音声ブリッジに対して - 明示的な CoreAudio デバイスコマンドを使用します。 -- `blackhole-2ch`: macOS 仮想音声ドライバー。Chrome/Meet がルーティングに使用できる - `BlackHole 2ch` 音声デバイスを作成します。 +- `sox`: コマンドライン音声ユーティリティ。Plugin は、既定の 24 kHz PCM16 音声ブリッジに明示的な CoreAudio デバイスコマンドを使用します。 +- `blackhole-2ch`: macOS 仮想音声ドライバー。Chrome/Meet が経由してルーティングできる `BlackHole 2ch` + 音声デバイスを作成します。 -OpenClaw はどちらのパッケージもバンドルまたは再配布しません。ドキュメントでは、 -ユーザーに Homebrew 経由でホスト依存関係としてインストールするよう案内しています。SoX は -`LGPL-2.0-only AND GPL-2.0-only` としてライセンスされており、BlackHole は GPL-3.0 です。 -BlackHole を OpenClaw と一緒にバンドルするインストーラーまたはアプライアンスを構築する場合は、 -BlackHole の上流ライセンス条件を確認するか、Existential Audio から別途ライセンスを取得してください。 +OpenClaw はどちらのパッケージもバンドルまたは再配布しません。ドキュメントでは、ユーザーに +Homebrew 経由でホスト依存関係としてインストールするよう案内しています。SoX は +`LGPL-2.0-only AND GPL-2.0-only` としてライセンスされ、BlackHole は GPL-3.0 です。BlackHole を OpenClaw と一緒にバンドルする +インストーラーまたはアプライアンスを構築する場合は、BlackHole のアップストリームライセンス条件を確認するか、 +Existential Audio から別途ライセンスを取得してください。 ## トランスポート ### Chrome -Chrome トランスポートは、OpenClaw のブラウザー制御を通じて Meet URL を開き、 -サインイン済みの OpenClaw ブラウザープロファイルとして参加します。macOS では、この Plugin は -起動前に `BlackHole 2ch` を確認します。設定されている場合は、Chrome を開く前に -音声ブリッジのヘルスコマンドと起動コマンドも実行します。Chrome/音声が Gateway ホスト上にある場合は -`chrome` を使用し、Chrome/音声が Parallels macOS VM などのペアリング済みノード上にある場合は -`chrome-node` を使用します。ローカル Chrome では、`browser.defaultProfile` で -プロファイルを選択します。`chrome.browserProfile` は `chrome-node` ホストに渡されます。 +Chrome トランスポートは、OpenClaw ブラウザー制御を通じて Meet URL を開き、 +サインイン済みの OpenClaw ブラウザープロファイルとして参加します。macOS では、Plugin は起動前に +`BlackHole 2ch` を確認します。設定されている場合、Chrome を開く前に音声ブリッジの +ヘルスコマンドと起動コマンドも実行します。Chrome/音声が Gateway ホスト上にある場合は `chrome` を使用し、 +Chrome/音声が Parallels macOS VM などのペアリング済みノード上にある場合は `chrome-node` を使用します。 +ローカル Chrome では `browser.defaultProfile` でプロファイルを選択します。 +`chrome.browserProfile` は `chrome-node` ホストに渡されます。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Chrome のマイクとスピーカー音声を、ローカルの OpenClaw 音声ブリッジ経由でルーティングします。 +Chrome のマイクおよびスピーカー音声をローカル OpenClaw 音声ブリッジ経由でルーティングします。 `BlackHole 2ch` がインストールされていない場合、音声パスなしで黙って参加するのではなく、 -参加はセットアップエラーで失敗します。 +セットアップエラーで参加が失敗します。 ### Twilio -Twilio トランスポートは、Voice Call Plugin に委任される厳格なダイヤルプランです。 -Meet ページから電話番号を解析しません。 +Twilio トランスポートは、Voice Call Plugin に委譲される厳密なダイヤルプランです。 +電話番号を取得するために Meet ページを解析しません。 -Chrome での参加が利用できない場合、または電話ダイヤルインのフォールバックが必要な場合に使用します。 -Google Meet はそのミーティング用の電話ダイヤルイン番号と PIN を公開している必要があります。 +Chrome 参加が利用できない場合、または電話ダイヤルインのフォールバックが必要な場合に使用します。 +Google Meet は、その会議用の電話ダイヤルイン番号と PIN を公開している必要があります。 OpenClaw は Meet ページからそれらを検出しません。 -Voice Call Plugin は Chrome ノードではなく Gateway ホストで有効にします。 +Voice Call Plugin は Chrome ノードではなく Gateway ホストで有効化します: ```json5 { @@ -400,8 +398,8 @@ Voice Call Plugin は Chrome ノードではなく Gateway ホストで有効に } ``` -Twilio の認証情報は環境または設定で提供します。環境を使うと、シークレットを -`openclaw.json` の外に保てます。 +Twilio 認証情報は環境または設定を通じて提供します。環境を使うと、シークレットを +`openclaw.json` の外に保てます: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -410,13 +408,13 @@ export TWILIO_FROM_NUMBER=+15550001234 export GEMINI_API_KEY=... ``` -リアルタイム音声プロバイダーがそれである場合は、代わりに OpenAI provider Plugin と -`OPENAI_API_KEY` を使用して `realtime.provider: "openai"` を使います。 +リアルタイム音声プロバイダーが OpenAI の場合は、代わりに OpenAI provider Plugin と +`OPENAI_API_KEY` で `realtime.provider: "openai"` を使用します。 -`voice-call` を有効にした後は Gateway を再起動またはリロードします。Plugin 設定の変更は、 -リロードされるまで、すでに実行中の Gateway プロセスには反映されません。 +`voice-call` を有効化した後は Gateway を再起動または再読み込みしてください。Plugin 設定の変更は、 +再読み込みされるまで、すでに実行中の Gateway プロセスには反映されません。 -次に確認します。 +次に検証します: ```bash openclaw config validate @@ -424,7 +422,7 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -Twilio 委任が配線されると、`googlemeet setup` には成功した +Twilio 委譲が接続されている場合、`googlemeet setup` には成功した `twilio-voice-call-plugin`、`twilio-voice-call-credentials`、および `twilio-voice-call-webhook` チェックが含まれます。 @@ -435,7 +433,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -ミーティングでカスタムシーケンスが必要な場合は `--dtmf-sequence` を使用します。 +会議にカスタムシーケンスが必要な場合は `--dtmf-sequence` を使用します: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -446,36 +444,35 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth と事前確認 -`googlemeet create` はブラウザー自動化にフォールバックできるため、Meet リンクの作成に -OAuth は任意です。公式 API での作成、スペース解決、または Meet Media API の事前確認が必要な場合に -OAuth を設定します。 +OAuth は `googlemeet create` がブラウザー自動化にフォールバックできるため、Meet リンク作成には任意です。 +公式 API による作成、スペース解決、または Meet Media API の事前確認が必要な場合に OAuth を設定します。 Google Meet API アクセスはユーザー OAuth を使用します。Google Cloud OAuth クライアントを作成し、 -必要なスコープを要求し、Google アカウントを承認してから、得られたリフレッシュトークンを +必要なスコープを要求し、Google アカウントを承認してから、結果のリフレッシュトークンを Google Meet Plugin 設定に保存するか、`OPENCLAW_GOOGLE_MEET_*` 環境変数を提供します。 -OAuth は Chrome 参加パスを置き換えません。ブラウザー参加を使用する場合、Chrome および -Chrome-node トランスポートは引き続き、サインイン済み Chrome プロファイル、BlackHole/SoX、 -および接続済みノードを通じて参加します。OAuth は公式 Google Meet API パス専用です。 -ミーティングスペースの作成、スペース解決、Meet Media API 事前確認の実行に使います。 +OAuth は Chrome 参加パスを置き換えるものではありません。Chrome および Chrome-node トランスポートは、 +ブラウザー参加を使用する場合、引き続きサインイン済み Chrome プロファイル、BlackHole/SoX、 +接続済みノードを通じて参加します。OAuth は公式 Google Meet API パス専用です: +会議スペースの作成、スペースの解決、Meet Media API 事前確認の実行。 ### Google 認証情報を作成する Google Cloud Console で: 1. Google Cloud プロジェクトを作成または選択します。 -2. そのプロジェクトで **Google Meet REST API** を有効にします。 +2. そのプロジェクトで **Google Meet REST API** を有効化します。 3. OAuth 同意画面を設定します。 - **Internal** は Google Workspace 組織では最も簡単です。 - - **External** は個人/テスト用セットアップで機能します。アプリが Testing の間は、 + - **External** は個人/テストセットアップで機能します。アプリが Testing の間は、 アプリを承認する各 Google アカウントをテストユーザーとして追加します。 -4. OpenClaw が要求するスコープを追加します。 +4. OpenClaw が要求するスコープを追加します: - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.space.settings` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` 5. OAuth クライアント ID を作成します。 - - アプリケーションタイプ: **Web application**。 + - アプリケーションの種類: **Web application**。 - 承認済みリダイレクト URI: ```text @@ -485,25 +482,23 @@ Google Cloud Console で: 6. クライアント ID とクライアントシークレットをコピーします。 `meetings.space.created` は Google Meet `spaces.create` に必要です。 -`meetings.space.readonly` により、OpenClaw は Meet URL/コードをスペースへ解決できます。 -`meetings.space.settings` により、OpenClaw は API でのルーム作成時に -`accessType` などの `SpaceConfig` 設定を渡せます。 +`meetings.space.readonly` により、OpenClaw は Meet URL/コードをスペースに解決できます。 +`meetings.space.settings` により、OpenClaw は API ルーム作成時に `accessType` などの +`SpaceConfig` 設定を渡せます。 `meetings.conference.media.readonly` は Meet Media API の事前確認とメディア作業用です。 -実際の Media API 使用には、Google が Developer Preview 登録を要求する場合があります。 -ブラウザーベースの Chrome 参加だけが必要な場合は、OAuth を完全にスキップします。 +実際の Media API 使用には、Google が Developer Preview への登録を要求する場合があります。 +ブラウザーベースの Chrome 参加だけが必要な場合は、OAuth を完全に省略してください。 ### リフレッシュトークンを発行する -`oauth.clientId` と、必要に応じて `oauth.clientSecret` を設定するか、環境変数として渡してから、 -次を実行します。 +`oauth.clientId` と必要に応じて `oauth.clientSecret` を設定するか、環境変数として渡してから実行します: ```bash openclaw googlemeet auth login --json ``` このコマンドは、リフレッシュトークンを含む `oauth` 設定ブロックを出力します。PKCE、 -`http://localhost:8085/oauth2callback` の localhost コールバック、および `--manual` -による手動コピー/貼り付けフローを使用します。 +`http://localhost:8085/oauth2callback` の localhost コールバック、および `--manual` による手動コピー/貼り付けフローを使用します。 例: @@ -513,7 +508,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -ブラウザーがローカルコールバックに到達できない場合は手動モードを使用します。 +ブラウザーがローカルコールバックに到達できない場合は手動モードを使用します: ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -521,7 +516,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json --manual ``` -JSON 出力には次が含まれます。 +JSON 出力には次が含まれます: ```json { @@ -536,7 +531,7 @@ JSON 出力には次が含まれます。 } ``` -`oauth` オブジェクトを Google Meet Plugin 設定の下に保存します。 +`oauth` オブジェクトを Google Meet Plugin 設定の下に保存します: ```json5 { @@ -557,37 +552,38 @@ JSON 出力には次が含まれます。 } ``` -リフレッシュトークンを設定に入れたくない場合は、環境変数を優先します。 -設定値と環境値の両方が存在する場合、この Plugin はまず設定を解決し、その後に環境へフォールバックします。 +リフレッシュトークンを設定に入れたくない場合は、環境変数を優先してください。 +設定値と環境値の両方が存在する場合、Plugin はまず設定を解決し、その後に環境へフォールバックします。 -OAuth 同意には、Meet スペース作成、Meet スペース読み取りアクセス、Meet 会議メディア読み取りアクセスが含まれます。 -ミーティング作成サポートが存在する前に認証していた場合は、 -リフレッシュトークンが `meetings.space.created` スコープを持つように -`openclaw googlemeet auth login --json` を再実行します。 +OAuth 同意には、Meet スペース作成、Meet スペース読み取りアクセス、および Meet +会議メディア読み取りアクセスが含まれます。会議作成サポートが存在する前に認証した場合は、 +リフレッシュトークンに `meetings.space.created` スコープを持たせるため、 +`openclaw googlemeet auth login --json` を再実行してください。 -### doctor で OAuth を確認する +### doctor で OAuth を検証する -高速な、シークレットを含まないヘルスチェックが必要な場合は OAuth doctor を実行します。 +高速でシークレットを出力しないヘルスチェックが必要な場合は OAuth doctor を実行します: ```bash openclaw googlemeet doctor --oauth --json ``` -これは Chrome ランタイムをロードせず、接続済み Chrome ノードも必要としません。 -OAuth 設定が存在すること、およびリフレッシュトークンがアクセストークンを発行できることを確認します。 -JSON レポートには `ok`、`configured`、`tokenSource`、`expiresAt`、チェックメッセージなどの -ステータスフィールドのみが含まれます。アクセストークン、リフレッシュトークン、クライアントシークレットは出力されません。 +これは Chrome ランタイムを読み込まず、接続済み Chrome ノードも必要としません。 +OAuth 設定が存在すること、およびリフレッシュトークンでアクセストークンを発行できることを確認します。 +JSON レポートには `ok`、`configured`、`tokenSource`、`expiresAt`、 +チェックメッセージなどのステータスフィールドのみが含まれ、アクセストークン、 +リフレッシュトークン、クライアントシークレットは出力されません。 一般的な結果: -| チェック | 意味 | -| -------------------- | ------------------------------------------------------------------------------------------ | -| `oauth-config` | `oauth.clientId` に加えて `oauth.refreshToken`、またはキャッシュされたアクセストークンが存在します。 | -| `oauth-token` | キャッシュされたアクセストークンがまだ有効か、リフレッシュトークンによって新しいアクセストークンが発行されました。 | -| `meet-spaces-get` | 任意の `--meeting` チェックが既存の Meet スペースを解決しました。 | -| `meet-spaces-create` | 任意の `--create-space` チェックが新しい Meet スペースを作成しました。 | +| チェック | 意味 | +| -------------------- | --------------------------------------------------------------------------------------- | +| `oauth-config` | `oauth.clientId` に加えて `oauth.refreshToken`、またはキャッシュ済みアクセス トークンが存在します。 | +| `oauth-token` | キャッシュ済みアクセス トークンがまだ有効であるか、リフレッシュ トークンが新しいアクセス トークンを発行しました。 | +| `meet-spaces-get` | 任意の `--meeting` チェックが既存の Meet スペースを解決しました。 | +| `meet-spaces-create` | 任意の `--create-space` チェックが新しい Meet スペースを作成しました。 | -Google Meet API の有効化と `spaces.create` スコープも証明するには、副作用を伴う作成チェックを実行します。 +Google Meet API の有効化と `spaces.create` スコープも証明するには、副作用のある作成チェックを実行します。 ```bash openclaw googlemeet doctor --oauth --create-space --json @@ -596,17 +592,16 @@ openclaw googlemeet create --no-join --json `--create-space` は使い捨ての Meet URL を作成します。Google Cloud プロジェクトで Meet API が有効になっていること、および認可済みアカウントに `meetings.space.created` スコープがあることを確認する必要がある場合に使用します。 -既存のミーティングスペースへの読み取りアクセスを証明するには、次を実行します。 +既存の会議スペースへの読み取りアクセスを証明するには: ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` と `resolve-space` は、認可済みの Google アカウントがアクセスできる既存スペースへの読み取りアクセスを証明します。これらのチェックで `403` が返る場合、通常は Google Meet REST API が無効、同意済みのリフレッシュトークンに必要なスコープがない、または Google アカウントがその Meet スペースにアクセスできないことを意味します。リフレッシュトークンエラーの場合は、`openclaw googlemeet auth login ---json` を再実行し、新しい `oauth` ブロックを保存します。 +`doctor --oauth --meeting` と `resolve-space` は、認可済み Google アカウントがアクセスできる既存スペースへの読み取りアクセスを証明します。これらのチェックで `403` が返る場合、通常は Google Meet REST API が無効になっている、同意済みリフレッシュ トークンに必要なスコープがない、または Google アカウントがその Meet スペースにアクセスできないことを意味します。リフレッシュ トークン エラーは、`openclaw googlemeet auth login --json` を再実行して新しい `oauth` ブロックを保存する必要があることを意味します。 -ブラウザフォールバックには OAuth 認証情報は不要です。そのモードでは、Google 認証は OpenClaw 設定ではなく、選択したノード上でサインイン済みの Chrome プロファイルから取得されます。 +ブラウザー フォールバックには OAuth 認証情報は不要です。このモードでは、Google 認証は OpenClaw config ではなく、選択したノードでサインイン済みの Chrome プロファイルから取得されます。 これらの環境変数はフォールバックとして受け付けられます。 @@ -619,19 +614,19 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij - `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` または `GOOGLE_MEET_DEFAULT_MEETING` - `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` または `GOOGLE_MEET_PREVIEW_ACK` -Meet URL、コード、または `spaces/{id}` を `spaces.get` で解決します。 +Meet URL、コード、または `spaces/{id}` を `spaces.get` 経由で解決します。 ```bash openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -メディア作業の前にプリフライトを実行します。 +メディア作業の前に preflight を実行します。 ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -Meet が会議レコードを作成した後で、ミーティングの成果物と出席状況を一覧表示します。 +Meet が conference record を作成した後に、会議アーティファクトと出席状況を一覧表示します。 ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij @@ -639,9 +634,9 @@ openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export ``` -`--meeting` を指定すると、`artifacts` と `attendance` はデフォルトで最新の会議レコードを使用します。そのミーティングで保持されているすべてのレコードが必要な場合は、`--all-conference-records` を渡します。 +`--meeting` を指定すると、`artifacts` と `attendance` は既定で最新の conference record を使用します。その会議の保持されているすべての record が必要な場合は `--all-conference-records` を渡します。 -Calendar ルックアップは、Meet の成果物を読み取る前に Google Calendar からミーティング URL を解決できます。 +Calendar lookup は、Meet アーティファクトを読み取る前に Google Calendar から会議 URL を解決できます。 ```bash openclaw googlemeet latest --today @@ -650,10 +645,10 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` は今日の `primary` カレンダーから Google Meet リンクを持つ Calendar イベントを検索します。一致するイベントテキストを検索するには `--event ` を使用し、非プライマリカレンダーには `--calendar ` を使用します。Calendar ルックアップには、Calendar events readonly スコープを含む新しい OAuth ログインが必要です。 +`--today` は、Google Meet リンクを持つ Calendar イベントを今日の `primary` カレンダーから検索します。イベント テキストの一致を検索するには `--event ` を、非プライマリ カレンダーには `--calendar ` を使用します。Calendar lookup には、Calendar events readonly スコープを含む新しい OAuth ログインが必要です。 `calendar-events` は一致する Meet イベントをプレビューし、`latest`、`artifacts`、`attendance`、または `export` が選択するイベントを示します。 -会議レコード ID がすでに分かっている場合は、直接指定します。 +conference record id がすでに分かっている場合は、直接指定します。 ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -661,14 +656,14 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -API で作成したスペースのアクティブな会議を、通話後にルームを閉じたい場合に終了します。 +通話後に room を閉じたい場合は、API で作成されたスペースのアクティブな conference を終了します。 ```bash openclaw googlemeet end-active-conference https://meet.google.com/abc-defg-hij ``` -これは Google Meet `spaces.endActiveConference` を呼び出し、認可済みアカウントが管理できるスペースに対する `meetings.space.created` スコープ付き OAuth を必要とします。OpenClaw は Meet URL、ミーティングコード、または `spaces/{id}` 入力を受け付け、アクティブな会議を終了する前に API スペースリソースへ解決します。 -これは `googlemeet leave` とは別です。`leave` は OpenClaw のローカル/セッション参加を停止しますが、`end-active-conference` は Google Meet に対して、そのスペースのアクティブな会議を終了するよう要求します。 +これは Google Meet `spaces.endActiveConference` を呼び出し、認可済みアカウントが管理できるスペースに対して `meetings.space.created` スコープを持つ OAuth が必要です。OpenClaw は Meet URL、会議コード、または `spaces/{id}` 入力を受け付け、アクティブな conference を終了する前に API スペース リソースへ解決します。 +これは `googlemeet leave` とは別です。`leave` は OpenClaw のローカル/セッション参加を停止しますが、`end-active-conference` は Google Meet にそのスペースのアクティブな conference の終了を依頼します。 読みやすいレポートを書き出します。 @@ -685,13 +680,13 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ --include-doc-bodies --dry-run ``` -`artifacts` は、Google がそのミーティングについて公開している場合、会議レコードのメタデータに加えて、参加者、録画、文字起こし、構造化された文字起こしエントリ、スマートノートのリソースメタデータを返します。大規模なミーティングでエントリ検索をスキップするには `--no-transcript-entries` を使用します。`attendance` は、参加者を参加者セッション行に展開し、最初/最後に確認された時刻、合計セッション時間、遅刻/早退フラグ、サインイン済みユーザーまたは表示名でマージされた重複参加者リソースを含めます。生の参加者リソースを分けたままにするには `--no-merge-duplicates`、遅刻判定を調整するには `--late-after-minutes`、早退判定を調整するには `--early-before-minutes` を渡します。 +`artifacts` は、Google がその会議に対して公開している場合、conference record メタデータに加えて、参加者、録画、文字起こし、構造化された transcript-entry、smart-note リソース メタデータを返します。大規模な会議で entry lookup をスキップするには `--no-transcript-entries` を使用します。`attendance` は参加者を participant-session 行に展開し、初回/最終表示時刻、合計セッション時間、遅刻/早退フラグ、およびサインイン ユーザーまたは表示名でマージされた重複参加者リソースを含めます。生の参加者リソースを分離したままにするには `--no-merge-duplicates` を、遅刻検出を調整するには `--late-after-minutes` を、早退検出を調整するには `--early-before-minutes` を渡します。 -`export` は、`summary.md`、`attendance.csv`、`transcript.md`、`artifacts.json`、`attendance.json`、`manifest.json` を含むフォルダを書き込みます。 -`manifest.json` には、選択された入力、エクスポートオプション、会議レコード、出力ファイル、件数、トークンソース、使用された場合の Calendar イベント、および部分的な取得警告が記録されます。フォルダの隣にポータブルアーカイブも書き込むには `--zip` を渡します。リンクされた文字起こしとスマートノートの Google Docs テキストを Google Drive `files.export` 経由でエクスポートするには `--include-doc-bodies` を渡します。これには Drive Meet readonly スコープを含む新しい OAuth ログインが必要です。`--include-doc-bodies` を指定しない場合、エクスポートには Meet メタデータと構造化された文字起こしエントリのみが含まれます。スマートノート一覧、文字起こしエントリ、Drive ドキュメント本文エラーなど、Google が部分的な成果物失敗を返した場合、エクスポート全体を失敗させるのではなく、サマリーとマニフェストに警告を保持します。 -同じ成果物/出席データを取得し、フォルダや ZIP を作成せずにマニフェスト JSON を出力するには `--dry-run` を使用します。これは、大きなエクスポートを書き込む前や、エージェントが件数、選択されたレコード、警告だけを必要とする場合に便利です。 +`export` は `summary.md`、`attendance.csv`、`transcript.md`、`artifacts.json`、`attendance.json`、`manifest.json` を含むフォルダーを書き出します。 +`manifest.json` は、選択された入力、エクスポート オプション、conference record、出力ファイル、件数、トークン ソース、使用された場合の Calendar イベント、および部分的な取得警告を記録します。フォルダーの横にポータブル アーカイブも書き出すには `--zip` を渡します。リンクされた文字起こしと smart-note Google Docs テキストを Google Drive `files.export` 経由でエクスポートするには `--include-doc-bodies` を渡します。これには Drive Meet readonly スコープを含む新しい OAuth ログインが必要です。`--include-doc-bodies` なしの場合、エクスポートには Meet メタデータと構造化された transcript entry のみが含まれます。Google が smart-note listing、transcript-entry、Drive document-body エラーなどの部分的なアーティファクト失敗を返した場合、summary と manifest はエクスポート全体を失敗させずに警告を保持します。 +フォルダーや ZIP を作成せずに同じ artifact/attendance データを取得し、manifest JSON を出力するには `--dry-run` を使用します。これは、大きなエクスポートを書き出す前や、エージェントが件数、選択された record、警告のみを必要とする場合に便利です。 -エージェントは `google_meet` ツールを使って同じバンドルを作成することもできます。 +エージェントは `google_meet` ツール経由でも同じバンドルを作成できます。 ```json { @@ -703,9 +698,9 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ } ``` -ファイル書き込みをスキップしてエクスポートマニフェストのみを返すには、`"dryRun": true` を設定します。 +エクスポート manifest のみを返し、ファイル書き込みをスキップするには `"dryRun": true` を設定します。 -エージェントは明示的なアクセスポリシーを持つ API バックのルームを作成することもできます。 +エージェントは明示的なアクセス ポリシーを持つ API-backed room も作成できます。 ```json { @@ -716,7 +711,7 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ } ``` -また、既知のルームのアクティブな会議を終了できます。 +また、既知の room のアクティブな conference を終了できます。 ```json { @@ -725,7 +720,7 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ } ``` -まず聞く検証では、ミーティングが有用だと主張する前に、エージェントは `test_listen` を使用する必要があります。 +listen-first 検証では、エージェントは会議が有用だと主張する前に `test_listen` を使用する必要があります。 ```json { @@ -736,7 +731,7 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ } ``` -実際に保持されているミーティングに対して、ガード付きライブスモークを実行します。 +実際に保持されている会議に対して、ガード付き live smoke を実行します。 ```bash OPENCLAW_LIVE_TEST=1 \ @@ -744,27 +739,29 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -Meet のキャプションが利用可能で、誰かが発話するミーティングに対して、まず聞くライブブラウザプローブを実行します。 +Meet captions が利用可能で、誰かが発話する会議に対して、live listen-first ブラウザー probe を実行します。 ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport chrome-node --timeout-ms 30000 ``` -ライブスモーク環境: +Live smoke 環境: -- `OPENCLAW_LIVE_TEST=1` はガード付きライブテストを有効にします。 +- `OPENCLAW_LIVE_TEST=1` はガード付き live tests を有効にします。 - `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` は保持されている Meet URL、コード、または `spaces/{id}` を指します。 -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` または `GOOGLE_MEET_CLIENT_ID` は OAuth クライアント ID を提供します。 -- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` または `GOOGLE_MEET_REFRESH_TOKEN` はリフレッシュトークンを提供します。 +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` または `GOOGLE_MEET_CLIENT_ID` は OAuth + client id を提供します。 +- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` または `GOOGLE_MEET_REFRESH_TOKEN` は + refresh token を提供します。 - 任意: `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`、 `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN`、および - `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` は、`OPENCLAW_` プレフィックスなしの同じフォールバック名を使用します。 + `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` は `OPENCLAW_` prefix なしの同じフォールバック名を使用します。 -基本の成果物/出席ライブスモークには、 +基本の artifact/attendance live smoke には `https://www.googleapis.com/auth/meetings.space.readonly` と -`https://www.googleapis.com/auth/meetings.conference.media.readonly` が必要です。Calendar ルックアップには `https://www.googleapis.com/auth/calendar.events.readonly` が必要です。Drive ドキュメント本文のエクスポートには +`https://www.googleapis.com/auth/meetings.conference.media.readonly` が必要です。Calendar lookup には `https://www.googleapis.com/auth/calendar.events.readonly` が必要です。Drive document-body export には `https://www.googleapis.com/auth/drive.meet.readonly` が必要です。 新しい Meet スペースを作成します。 @@ -773,9 +770,9 @@ openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport openclaw googlemeet create ``` -このコマンドは新しい `meeting uri`、ソース、参加セッションを出力します。OAuth 認証情報がある場合は公式の Google Meet API を使用します。OAuth 認証情報がない場合は、固定された Chrome ノードのサインイン済みブラウザプロファイルをフォールバックとして使用します。エージェントは `action: "create"` を指定して `google_meet` ツールを使用し、作成と参加を 1 ステップで実行できます。URL の作成のみを行う場合は、`"join": false` を渡します。 +このコマンドは新しい `meeting uri`、ソース、join session を出力します。OAuth 認証情報がある場合は、公式の Google Meet API を使用します。OAuth 認証情報がない場合は、ピン留めされた Chrome ノードのサインイン済みブラウザー プロファイルをフォールバックとして使用します。エージェントは `action: "create"` を指定した `google_meet` ツールを使用して、1 ステップで作成して参加できます。URL の作成のみを行う場合は、`"join": false` を渡します。 -ブラウザフォールバックからの JSON 出力例: +ブラウザー フォールバックからの JSON 出力例: ```json { @@ -795,7 +792,7 @@ openclaw googlemeet create } ``` -ブラウザフォールバックが URL を作成できる前に Google ログインまたは Meet 権限ブロッカーに遭遇した場合、Gateway メソッドは失敗レスポンスを返し、`google_meet` ツールはプレーン文字列ではなく構造化された詳細を返します。 +ブラウザー フォールバックが URL を作成する前に Google ログインまたは Meet 権限ブロッカーに遭遇した場合、Gateway メソッドは失敗したレスポンスを返し、`google_meet` ツールはプレーンな文字列ではなく構造化された詳細を返します。 ```json { @@ -813,9 +810,9 @@ openclaw googlemeet create } ``` -エージェントが `manualActionRequired: true` を見た場合、`manualActionMessage` に加えてブラウザのノード/タブコンテキストを報告し、オペレーターがブラウザ手順を完了するまで新しい Meet タブを開くのを停止する必要があります。 +エージェントが `manualActionRequired: true` を確認した場合は、`manualActionMessage` とブラウザーの node/tab コンテキストを報告し、オペレーターがブラウザー手順を完了するまで新しい Meet タブを開くのを停止する必要があります。 -API 作成からの JSON 出力例: +API create からの JSON 出力例: ```json { @@ -836,13 +833,13 @@ API 作成からの JSON 出力例: } ``` -Meet を作成すると、デフォルトで参加します。Chrome または Chrome-node トランスポートでブラウザから参加するには、サインイン済みの Google Chrome プロファイルが引き続き必要です。プロファイルがサインアウト状態の場合、OpenClaw は `manualActionRequired: true` またはブラウザのフォールバックエラーを報告し、再試行する前にオペレーターへ Google ログインを完了するよう求めます。 +Meet を作成すると、デフォルトで参加します。Chrome または Chrome-node トランスポートでブラウザー経由で参加するには、ログイン済みの Google Chrome プロファイルが引き続き必要です。プロファイルがログアウト状態の場合、OpenClaw は `manualActionRequired: true` またはブラウザーのフォールバックエラーを報告し、再試行する前にオペレーターへ Google ログインの完了を求めます。 -Cloud プロジェクト、OAuth プリンシパル、会議参加者が Google Workspace Developer Preview Program for Meet media APIs に登録済みであることを確認した後にのみ、`preview.enrollmentAcknowledged: true` を設定してください。 +Cloud プロジェクト、OAuth プリンシパル、会議参加者が Meet media APIs 向け Google Workspace Developer Preview Program に登録されていることを確認した後でのみ、`preview.enrollmentAcknowledged: true` を設定してください。 ## 設定 -共通の Chrome エージェントパスで必要なのは、Plugin を有効にすること、BlackHole、SoX、リアルタイム文字起こしプロバイダーキー、および設定済みの OpenClaw TTS プロバイダーだけです。OpenAI がデフォルトの文字起こしプロバイダーです。デフォルトのエージェントモード文字起こしプロバイダーを変更せずに `bidi` モードで Google Gemini Live を使用するには、`realtime.voiceProvider` を `"google"` に設定し、`realtime.model` を設定します。 +共通の Chrome エージェントパスに必要なのは、Plugin の有効化、BlackHole、SoX、リアルタイム文字起こしプロバイダーキー、設定済みの OpenClaw TTS プロバイダーだけです。OpenAI がデフォルトの文字起こしプロバイダーです。デフォルトのエージェントモード文字起こしプロバイダーを変更せずに、`bidi` モードで Google Gemini Live を使用するには、`realtime.voiceProvider` を `"google"` に、`realtime.model` を設定します。 ```bash brew install blackhole-2ch sox @@ -869,33 +866,33 @@ Plugin 設定を `plugins.entries.google-meet.config` の下に設定します デフォルト: - `defaultTransport: "chrome"` -- `defaultMode: "agent"`（`"realtime"` は `"agent"` のレガシー互換エイリアスとしてのみ受け入れられます。新しいツール呼び出しでは `"agent"` を指定してください） -- `chromeNode.node`: `chrome-node` 用の任意のノード ID/名前/IP +- `defaultMode: "agent"`（`"realtime"` は `"agent"` のレガシー互換エイリアスとしてのみ受け付けられます。新しいツール呼び出しでは `"agent"` と指定してください） +- `chromeNode.node`: `chrome-node` 用の任意のノード id/名前/IP - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`: サインアウト状態の Meet ゲスト画面で使用される名前 -- `chrome.autoJoin: true`: `chrome-node` 上の OpenClaw ブラウザ自動化による、ベストエフォートのゲスト名入力と「今すぐ参加」クリック -- `chrome.reuseExistingTab: true`: 重複して開く代わりに既存の Meet タブをアクティブ化します -- `chrome.waitForInCallMs: 20000`: 応答音声イントロがトリガーされる前に、Meet タブが通話中を報告するまで待機します -- `chrome.audioFormat: "pcm16-24khz"`: コマンドペア音声形式。現在も電話音声を出力するレガシー/カスタムのコマンドペアにのみ `"g711-ulaw-8khz"` を使用してください。 -- `chrome.audioBufferBytes: 4096`: 生成された Chrome コマンドペア音声コマンド用の SoX 処理バッファです。これは SoX のデフォルト 8192 バイトバッファの半分であり、デフォルトのパイプレイテンシを削減しつつ、負荷の高いホストで引き上げる余地を残します。SoX の最小値を下回る値は 17 バイトにクランプされます。 -- `chrome.audioInputCommand`: CoreAudio `BlackHole 2ch` から読み取り、`chrome.audioFormat` の音声を書き込む SoX コマンド -- `chrome.audioOutputCommand`: `chrome.audioFormat` の音声を読み取り、CoreAudio `BlackHole 2ch` に書き込む SoX コマンド -- `chrome.bargeInInputCommand`: アシスタント再生が有効な間、人間の割り込み発話検出のために signed 16-bit little-endian mono PCM を書き込む任意のローカルマイクコマンドです。これは現在、Gateway でホストされる `chrome` コマンドペアブリッジに適用されます。 -- `chrome.bargeInRmsThreshold: 650`: `chrome.bargeInInputCommand` で人間による割り込みとして扱われる RMS レベル -- `chrome.bargeInPeakThreshold: 2500`: `chrome.bargeInInputCommand` で人間による割り込みとして扱われるピークレベル -- `chrome.bargeInCooldownMs: 900`: 繰り返される人間による割り込みクリアの最小間隔 -- `mode: "agent"`: デフォルトの応答音声モードです。参加者の発話は、設定済みのリアルタイム文字起こしプロバイダーによって文字起こしされ、会議ごとのサブエージェントセッション内の設定済み OpenClaw エージェントへ送信され、通常の OpenClaw TTS ランタイムを通じて読み上げられます。 -- `mode: "bidi"`: フォールバック用の直接双方向リアルタイムモデルモードです。リアルタイム音声プロバイダーが参加者の発話に直接応答し、より深い/ツールに支えられた回答のために `openclaw_agent_consult` を呼び出す場合があります。 -- `mode: "transcribe"`: 応答音声ブリッジなしの観察専用モードです。 -- `realtime.provider: "openai"`: 以下のスコープ付きプロバイダーフィールドが未設定の場合に使用される互換性フォールバックです。 -- `realtime.transcriptionProvider: "openai"`: `agent` モードでリアルタイム文字起こしに使用されるプロバイダー ID です。 -- `realtime.voiceProvider`: `bidi` モードで直接リアルタイム音声に使用されるプロバイダー ID です。エージェントモードの文字起こしを OpenAI のままにしながら Gemini Live を使用するには、これを `"google"` に設定します。 +- `chrome.guestName: "OpenClaw Agent"`: ログアウト状態の Meet ゲスト画面で使われる名前 +- `chrome.autoJoin: true`: `chrome-node` 上の OpenClaw ブラウザー自動化による、ベストエフォートのゲスト名入力と Join Now クリック +- `chrome.reuseExistingTab: true`: 重複して開く代わりに、既存の Meet タブをアクティブ化します +- `chrome.waitForInCallMs: 20000`: トークバックのイントロがトリガーされる前に、Meet タブが通話中を報告するまで待機します +- `chrome.audioFormat: "pcm16-24khz"`: コマンドペアの音声形式。まだ電話音声を出力するレガシー/カスタムのコマンドペアでのみ `"g711-ulaw-8khz"` を使用してください。 +- `chrome.audioBufferBytes: 4096`: 生成された Chrome コマンドペア音声コマンド用の SoX 処理バッファーです。これは SoX のデフォルト 8192 バイトバッファーの半分で、ビジーなホストで増やす余地を残しつつ、デフォルトのパイプレイテンシーを減らします。SoX の最小値を下回る値は 17 バイトにクランプされます。 +- `chrome.audioInputCommand`: CoreAudio `BlackHole 2ch` から読み取り、`chrome.audioFormat` で音声を書き込む SoX コマンド +- `chrome.audioOutputCommand`: `chrome.audioFormat` で音声を読み取り、CoreAudio `BlackHole 2ch` に書き込む SoX コマンド +- `chrome.bargeInInputCommand`: アシスタント再生がアクティブな間の人間による割り込み検出のために、符号付き 16 ビットリトルエンディアンのモノラル PCM を書き込む任意のローカルマイクコマンドです。これは現在、Gateway でホストされる `chrome` コマンドペアブリッジに適用されます。 +- `chrome.bargeInRmsThreshold: 650`: `chrome.bargeInInputCommand` で人間の割り込みとして扱う RMS レベル +- `chrome.bargeInPeakThreshold: 2500`: `chrome.bargeInInputCommand` で人間の割り込みとして扱うピークレベル +- `chrome.bargeInCooldownMs: 900`: 繰り返される人間の割り込みクリア間の最小遅延 +- `mode: "agent"`: デフォルトのトークバックモードです。参加者の発話は、設定済みのリアルタイム文字起こしプロバイダーによって文字起こしされ、会議ごとのサブエージェントセッション内の設定済み OpenClaw エージェントに送信され、通常の OpenClaw TTS ランタイムを通じて読み上げられます。 +- `mode: "bidi"`: フォールバックの直接双方向リアルタイムモデルモードです。リアルタイム音声プロバイダーが参加者の発話に直接応答し、より深い/ツール支援の回答には `openclaw_agent_consult` を呼び出すことがあります。 +- `mode: "transcribe"`: トークバックブリッジなしの観察専用モードです。 +- `realtime.provider: "openai"`: 下記のスコープ付きプロバイダーフィールドが未設定の場合に使われる互換フォールバックです。 +- `realtime.transcriptionProvider: "openai"`: `agent` モードがリアルタイム文字起こしに使うプロバイダー id です。 +- `realtime.voiceProvider`: `bidi` モードが直接リアルタイム音声に使うプロバイダー id です。エージェントモードの文字起こしを OpenAI のままにしながら Gemini Live を使用するには、これを `"google"` に設定します。 - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`: 簡潔な音声応答。より深い回答には `openclaw_agent_consult` を使用します -- `realtime.introMessage`: リアルタイムブリッジ接続時の短い音声による準備完了チェック。無言で参加するには `""` に設定します -- `realtime.agentId`: `openclaw_agent_consult` 用の任意の OpenClaw エージェント ID。デフォルトは `main` です +- `realtime.instructions`: 短い音声応答。より深い回答には `openclaw_agent_consult` を使用します +- `realtime.introMessage`: リアルタイムブリッジ接続時の短い音声準備確認。無音で参加するには `""` に設定します +- `realtime.agentId`: `openclaw_agent_consult` 用の任意の OpenClaw エージェント id。デフォルトは `main` -任意のオーバーライド: +任意の上書き: ```json5 { @@ -948,6 +945,45 @@ Plugin 設定を `plugins.entries.google-meet.config` の下に設定します } ``` +エージェントモードのリスニングと発話の両方に ElevenLabs を使う場合: + +```json5 +{ + messages: { + tts: { + provider: "elevenlabs", + providers: { + elevenlabs: { + modelId: "eleven_v3", + voiceId: "pMsXgVXv3BLzUgSXRplE", + }, + }, + }, + }, + plugins: { + entries: { + "google-meet": { + config: { + realtime: { + transcriptionProvider: "elevenlabs", + providers: { + elevenlabs: { + modelId: "scribe_v2_realtime", + audioFormat: "ulaw_8000", + sampleRate: 8000, + commitStrategy: "vad", + }, + }, + }, + }, + }, + }, + }, +} +``` + +永続的な Meet 音声は `messages.tts.providers.elevenlabs.voiceId` から取得されます。TTS モデルの上書きが有効な場合、エージェント応答では返信ごとの `[[tts:voiceId=... model=eleven_v3]]` ディレクティブも使用できますが、会議では設定が決定的なデフォルトです。参加時には、ログに `transcriptionProvider=elevenlabs` が表示され、読み上げられた各応答で `provider=elevenlabs model=eleven_v3 voice=` がログ出力されるはずです。 + Twilio 専用設定: ```json5 @@ -963,7 +999,7 @@ Twilio 専用設定: } ``` -`voiceCall.enabled` のデフォルトは `true` です。Twilio トランスポートでは、実際の PSTN 通話、DTMF、イントロ挨拶を Voice Call Plugin に委譲します。Voice Call はリアルタイムメディアストリームを開く前に DTMF シーケンスを再生し、その後、保存されたイントロテキストを初期リアルタイム挨拶として使用します。`voice-call` が有効でない場合でも、Google Meet はダイヤルプランを検証して記録できますが、Twilio 通話は発信できません。 +`voiceCall.enabled` のデフォルトは `true` です。Twilio トランスポートでは、実際の PSTN 通話、DTMF、イントロ挨拶を Voice Call Plugin に委譲します。Voice Call はリアルタイムメディアストリームを開く前に DTMF シーケンスを再生し、その後、保存されたイントロテキストを最初のリアルタイム挨拶として使用します。`voice-call` が有効でない場合でも、Google Meet はダイヤルプランを検証して記録できますが、Twilio 通話を発信することはできません。 ## ツール @@ -978,20 +1014,20 @@ Twilio 専用設定: } ``` -Chrome が Gateway ホスト上で実行される場合は `transport: "chrome"` を使用します。Chrome が Parallels VM などのペアリング済みノード上で実行される場合は `transport: "chrome-node"` を使用します。どちらの場合も、モデルプロバイダーと `openclaw_agent_consult` は Gateway ホスト上で実行されるため、モデル認証情報はそこに留まります。デフォルトの `mode: "agent"` では、リアルタイム文字起こしプロバイダーが聞き取りを処理し、設定済みの OpenClaw エージェントが回答を生成し、通常の OpenClaw TTS がそれを Meet に読み上げます。リアルタイム音声モデルに直接回答させたい場合は `mode: "bidi"` を使用します。生の `mode: "realtime"` は、`mode: "agent"` のレガシー互換エイリアスとして引き続き受け入れられますが、エージェントツールスキーマではもう告知されません。 +Chrome が Gateway ホスト上で実行される場合は `transport: "chrome"` を使用します。Chrome が Parallels VM などのペアリング済みノード上で実行される場合は `transport: "chrome-node"` を使用します。どちらの場合も、モデルプロバイダーと `openclaw_agent_consult` は Gateway ホスト上で実行されるため、モデル認証情報はそこに保持されます。デフォルトの `mode: "agent"` では、リアルタイム文字起こしプロバイダーがリスニングを処理し、設定済みの OpenClaw エージェントが回答を生成し、通常の OpenClaw TTS がそれを Meet に読み上げます。リアルタイム音声モデルに直接回答させたい場合は `mode: "bidi"` を使用します。生の `mode: "realtime"` は `mode: "agent"` のレガシー互換エイリアスとして引き続き受け付けられますが、エージェントツールスキーマではもう公開されていません。エージェントモードのログには、ブリッジ起動時に解決された文字起こしプロバイダー/モデルと、合成された各応答後の TTS プロバイダー、モデル、音声、出力形式、サンプルレートが含まれます。 -アクティブなセッションを一覧表示するか、セッション ID を調べるには `action: "status"` を使用します。リアルタイムエージェントに即座に発話させるには、`sessionId` と `message` を指定して `action: "speak"` を使用します。セッションを作成または再利用し、既知のフレーズをトリガーし、Chrome ホストが報告できる場合に `inCall` の健全性を返すには、`action: "test_speech"` を使用します。`test_speech` は常に `mode: "agent"` を強制し、`mode: "transcribe"` で実行するよう求められると失敗します。観察専用セッションは意図的に発話を出力できないためです。その `speechOutputVerified` 結果は、このテスト呼び出し中にリアルタイム音声出力バイトが増加したかどうかに基づくため、古い音声を持つ再利用セッションは、新規の成功した発話チェックとしては扱われません。セッションを終了済みとしてマークするには `action: "leave"` を使用します。 +アクティブなセッション一覧を表示する、またはセッション ID を調べるには `action: "status"` を使用します。リアルタイムエージェントに即座に発話させるには、`sessionId` と `message` を指定して `action: "speak"` を使用します。セッションを作成または再利用し、既知のフレーズをトリガーし、Chrome ホストが報告できる場合に `inCall` ヘルスを返すには `action: "test_speech"` を使用します。`test_speech` は常に `mode: "agent"` を強制し、観察専用セッションは意図的に発話を出力できないため、`mode: "transcribe"` で実行するよう求められると失敗します。その `speechOutputVerified` 結果は、このテスト呼び出し中にリアルタイム音声出力バイト数が増加したかどうかに基づくため、古い音声がある再利用セッションは新しい発話成功チェックとしては数えられません。セッションを終了済みとしてマークするには `action: "leave"` を使用します。 -`status` には利用可能な場合 Chrome の健全性が含まれます。 +利用可能な場合、`status` には Chrome ヘルスが含まれます。 - `inCall`: Chrome が Meet 通話内にいるように見えます - `micMuted`: ベストエフォートの Meet マイク状態 -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: 音声が機能する前に、ブラウザプロファイルで手動ログイン、Meet ホストによる入室許可、権限、またはブラウザ制御の修復が必要です -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: 管理対象 Chrome の発話が現在許可されているかどうか。`speechReady: false` は、OpenClaw がイントロ/テストフレーズを音声ブリッジに送信しなかったことを意味します。 +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: 発話を機能させる前に、ブラウザープロファイルに手動ログイン、Meet ホストの承認、権限、またはブラウザー制御の修復が必要です +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: 管理対象 Chrome 発話が現在許可されているかどうか。`speechReady: false` は、OpenClaw がイントロ/テストフレーズを音声ブリッジへ送信しなかったことを意味します。 - `providerConnected` / `realtimeReady`: リアルタイム音声ブリッジの状態 -- `lastInputAt` / `lastOutputAt`: ブリッジから最後に検出した音声、またはブリッジへ最後に送信した音声 -- `audioOutputRouted` / `audioOutputDeviceLabel`: Meet タブのメディア出力が、ブリッジで使用される BlackHole デバイスにアクティブにルーティングされていたかどうか -- `lastSuppressedInputAt` / `suppressedInputBytes`: アシスタント再生が有効な間に無視されたループバック入力 +- `lastInputAt` / `lastOutputAt`: ブリッジから最後に見られた、またはブリッジへ送信された音声 +- `audioOutputRouted` / `audioOutputDeviceLabel`: Meet タブのメディア出力が、ブリッジで使われる BlackHole デバイスへ能動的にルーティングされたかどうか +- `lastSuppressedInputAt` / `suppressedInputBytes`: アシスタント再生がアクティブな間に無視されたループバック入力 ```json { @@ -1003,37 +1039,36 @@ Chrome が Gateway ホスト上で実行される場合は `transport: "chrome"` ## エージェントと Bidi モード -Chrome `agent` モードは、「自分のエージェントが会議に参加している」挙動向けに最適化されています。リアルタイム文字起こしプロバイダーが会議音声を聞き取り、確定した参加者の文字起こしは設定済みの OpenClaw エージェントへルーティングされ、回答は通常の OpenClaw TTS ランタイムを通じて読み上げられます。リアルタイム音声モデルに直接回答させたい場合は `mode: "bidi"` を設定します。 -近接する確定文字起こし断片は相談前に結合されるため、1 つの発話ターンから複数の古い部分回答が生成されません。キューに入ったアシスタント音声がまだ再生中の間はリアルタイム入力も抑制され、エージェント相談の前に最近のアシスタントらしい文字起こしエコーが無視されるため、BlackHole ループバックによってエージェントが自分自身の発話に回答することはありません。 +Chrome `agent` モードは、「自分のエージェントが会議にいる」動作に最適化されています。リアルタイム文字起こしプロバイダーが会議音声を聞き取り、参加者の最終トランスクリプトは設定済みの OpenClaw エージェントへルーティングされ、回答は通常の OpenClaw TTS ランタイムを通じて読み上げられます。リアルタイム音声モデルに直接回答させたい場合は `mode: "bidi"` を設定します。近接した最終トランスクリプト断片は consult の前に結合されるため、1 つの発話ターンが複数の古い部分回答を生むことはありません。キューされたアシスタント音声がまだ再生中の間はリアルタイム入力も抑制され、エージェント consult の前には最近のアシスタントらしいトランスクリプトエコーが無視されるため、BlackHole ループバックによってエージェントが自分自身の発話に回答することはありません。 -| モード | 回答を決める主体 | 音声出力パス | 使う場面 | -| ------- | ----------------------------- | -------------------------------------- | ----------------------------------------------------- | -| `agent` | 設定済みの OpenClaw エージェント | 通常の OpenClaw TTS ランタイム | 「自分のエージェントが会議に参加している」挙動が必要な場合 | -| `bidi` | リアルタイム音声モデル | リアルタイム音声プロバイダーの音声応答 | 最小レイテンシの会話音声ループが必要な場合 | +| モード | 誰が回答を決めるか | 音声出力パス | 使用する場面 | +| ------- | ------------------------------- | ------------------------------------ | ----------------------------------------------------------- | +| `agent` | 設定済みの OpenClaw エージェント | 通常の OpenClaw TTS ランタイム | 「自分のエージェントが会議にいる」動作が必要な場合 | +| `bidi` | リアルタイム音声モデル | リアルタイム音声プロバイダーの音声応答 | 最低レイテンシーの会話型音声ループが必要な場合 | -`bidi` モードでは、リアルタイムモデルがより深い推論、現在の情報、または通常の OpenClaw ツールを必要とする場合、`openclaw_agent_consult` を呼び出せます。 +`bidi` モードでは、リアルタイムモデルがより深い推論、現在の情報、または通常の OpenClaw ツールを必要とする場合、`openclaw_agent_consult` を呼び出すことができます。 -相談ツールは、最近の会議文字起こしコンテキストを使って背後で通常の OpenClaw エージェントを実行し、簡潔な音声回答を返します。`agent` モードでは、OpenClaw がその回答を TTS ランタイムへ直接送信します。`bidi` モードでは、リアルタイム音声モデルが相談結果を会議内で読み上げられます。これは Voice Call と同じ共有相談の仕組みを使用します。 +consult ツールは、最近の会議文字起こしコンテキストを使って通常の OpenClaw エージェントを背後で実行し、簡潔な音声回答を返します。`agent` モードでは、OpenClaw はその回答を TTS ランタイムへ直接送信します。`bidi` モードでは、リアルタイム音声モデルが consult 結果を会議内で読み上げられます。Voice Call と同じ共有 consult 機構を使用します。 -デフォルトでは、相談は `main` エージェントに対して実行されます。Meet レーンが専用の OpenClaw エージェントワークスペース、モデルデフォルト、ツールポリシー、メモリ、セッション履歴に相談する必要がある場合は、`realtime.agentId` を設定します。 +デフォルトでは、consult は `main` エージェントに対して実行されます。Meet レーンが専用の OpenClaw エージェントワークスペース、モデルのデフォルト、ツールポリシー、メモリ、セッション履歴を consult する必要がある場合は、`realtime.agentId` を設定します。 -エージェントモードの相談は、会議ごとの `agent::subagent:google-meet:` セッションキーを使用するため、フォローアップの質問は、設定済みエージェントから通常のエージェントポリシーを継承しつつ、会議コンテキストを維持できます。 +エージェントモードの consult は、会議ごとの `agent::subagent:google-meet:` セッションキーを使用するため、フォローアップ質問は会議コンテキストを維持しながら、設定済みエージェントの通常のエージェントポリシーを継承します。 -`realtime.toolPolicy` は相談実行を制御します。 +`realtime.toolPolicy` は consult 実行を制御します。 -- `safe-read-only`: 相談ツールを公開し、通常のエージェントを `read`、`web_search`、`web_fetch`、`x_search`、`memory_search`、`memory_get` に制限します。 -- `owner`: 相談ツールを公開し、通常のエージェントが通常のエージェントツールポリシーを使用できるようにします。 -- `none`: リアルタイム音声モデルに相談ツールを公開しません。 +- `safe-read-only`: consult ツールを公開し、通常のエージェントを `read`、`web_search`、`web_fetch`、`x_search`、`memory_search`、`memory_get` に制限します。 +- `owner`: consult ツールを公開し、通常のエージェントに通常のエージェントツールポリシーを使用させます。 +- `none`: consult ツールをリアルタイム音声モデルに公開しません。 -相談セッションキーは Meet セッションごとにスコープされているため、同じ会議中のフォローアップ相談呼び出しで以前の相談コンテキストを再利用できます。 +consult セッションキーは Meet セッションごとにスコープされるため、フォローアップの consult 呼び出しは同じ会議中に以前の consult コンテキストを再利用できます。 -Chrome が通話に完全に参加した後で、音声による準備完了チェックを強制するには: +Chrome が通話に完全に参加した後、音声の準備完了チェックを強制するには: ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -完全な参加および発話のスモークには: +完全な参加して発話する smoke には: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -1041,9 +1076,9 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: I'm here and listening." ``` -## ライブテストのチェックリスト +## ライブテストチェックリスト -無人エージェントにミーティングを渡す前に、この手順を使用します: +会議を無人エージェントに引き渡す前に、この手順を使用します。 ```bash openclaw googlemeet setup @@ -1056,14 +1091,12 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ 想定される Chrome-node の状態: - `googlemeet setup` がすべて緑です。 -- Chrome-node がデフォルトのトランスポートであるか、ノードが固定されている場合、 - `googlemeet setup` に `chrome-node-connected` が含まれます。 -- `nodes status` に、選択されたノードが接続済みとして表示されます。 -- 選択されたノードが `googlemeet.chrome` と `browser.proxy` の両方を公開します。 -- Meet タブが通話に参加し、`test-speech` が `inCall: true` を含む Chrome の健全性を返します。 +- Chrome-node がデフォルト transport であるか node が固定されている場合、`googlemeet setup` に `chrome-node-connected` が含まれます。 +- `nodes status` に、選択された node が接続済みとして表示されます。 +- 選択された node が `googlemeet.chrome` と `browser.proxy` の両方を通知します。 +- Meet タブが通話に参加し、`test-speech` が `inCall: true` を含む Chrome ヘルスを返します。 -Parallels macOS VM のようなリモート Chrome ホストでは、Gateway または VM を更新した後の -最短で安全な確認は次のとおりです: +Parallels macOS VM などのリモート Chrome ホストでは、Gateway または VM を更新した後の最短で安全なチェックは次のとおりです。 ```bash openclaw googlemeet setup @@ -1074,10 +1107,9 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -これにより、Gateway Plugin が読み込まれていること、VM ノードが現在のトークンで接続されていること、 -エージェントが実際のミーティングタブを開く前に Meet 音声ブリッジが利用可能であることを証明できます。 +これにより、Gateway Plugin が読み込まれていること、VM node が現在のトークンで接続されていること、エージェントが実際の会議タブを開く前に Meet 音声ブリッジが利用可能であることを確認できます。 -Twilio のスモークには、電話ダイヤルイン詳細を公開するミーティングを使用します: +Twilio smoke には、電話ダイヤルイン詳細を公開する会議を使用します。 ```bash openclaw googlemeet setup @@ -1089,37 +1121,30 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ 想定される Twilio の状態: -- `googlemeet setup` に、緑の `twilio-voice-call-plugin`、 - `twilio-voice-call-credentials`、`twilio-voice-call-webhook` チェックが含まれます。 -- Gateway の再読み込み後、CLI で `voicecall` が利用可能です。 +- `googlemeet setup` に、緑の `twilio-voice-call-plugin`、`twilio-voice-call-credentials`、`twilio-voice-call-webhook` チェックが含まれます。 +- Gateway のリロード後、CLI で `voicecall` を利用できます。 - 返されたセッションに `transport: "twilio"` と `twilio.voiceCallId` があります。 -- `openclaw logs --follow` には、リアルタイム TwiML の前に DTMF TwiML が提供され、その後、 - 初期の挨拶がキューに入ったリアルタイムブリッジが表示されます。 -- `googlemeet leave ` は委任された音声通話を切断します。 +- `openclaw logs --follow` に、リアルタイム TwiML の前に DTMF TwiML が提供され、その後、初期グリーティングがキューに入ったリアルタイムブリッジが表示されます。 +- `googlemeet leave ` が委任された音声通話を切断します。 ## トラブルシューティング -### エージェントに Google Meet ツールが表示されない +### エージェントが Google Meet ツールを認識できない -Gateway 設定で Plugin が有効になっていることを確認し、Gateway を再読み込みします: +Plugin が Gateway 設定で有効化されていることを確認し、Gateway をリロードします。 ```bash openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -`plugins.entries.google-meet` を編集したばかりの場合は、Gateway を再起動または再読み込みします。 -実行中のエージェントには、現在の Gateway プロセスによって登録された Plugin ツールだけが表示されます。 +`plugins.entries.google-meet` を編集したばかりの場合は、Gateway を再起動またはリロードします。実行中のエージェントは、現在の Gateway プロセスによって登録された Plugin ツールのみを認識します。 -macOS 以外の Gateway ホストでは、エージェント向けの `google_meet` ツールは表示されたままですが、 -ローカル Chrome のトークバック操作は音声ブリッジに到達する前にブロックされます。 -ローカル Chrome のトークバック音声は現在 macOS の `BlackHole 2ch` に依存しているため、 -Linux エージェントはデフォルトのローカル Chrome エージェントパスではなく、`mode: "transcribe"`、 -Twilio ダイヤルイン、または macOS の `chrome-node` ホストを使用してください。 +macOS 以外の Gateway ホストでは、エージェント向けの `google_meet` ツールは表示されたままですが、ローカル Chrome のトークバックアクションは音声ブリッジに到達する前にブロックされます。ローカル Chrome のトークバック音声は現在 macOS の `BlackHole 2ch` に依存しているため、Linux エージェントはデフォルトのローカル Chrome エージェントパスではなく、`mode: "transcribe"`、Twilio ダイヤルイン、または macOS の `chrome-node` ホストを使用する必要があります。 -### Google Meet 対応ノードが接続されていない +### 接続済みの Google Meet 対応 node がない -ノードホストで次を実行します: +node ホストで実行します。 ```bash openclaw plugins enable google-meet @@ -1128,7 +1153,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Gateway ホストで、ノードを承認し、コマンドを確認します: +Gateway ホストで、node を承認し、コマンドを確認します。 ```bash openclaw devices list @@ -1136,8 +1161,7 @@ openclaw devices approve openclaw nodes status ``` -ノードは接続済みで、`googlemeet.chrome` と `browser.proxy` を一覧表示している必要があります。 -Gateway 設定では、これらのノードコマンドを許可する必要があります: +node は接続済みで、`googlemeet.chrome` と `browser.proxy` を一覧表示している必要があります。Gateway 設定では、それらの node コマンドを許可する必要があります。 ```json5 { @@ -1149,9 +1173,7 @@ Gateway 設定では、これらのノードコマンドを許可する必要が } ``` -`googlemeet setup` が `chrome-node-connected` で失敗する、または Gateway ログが -`gateway token mismatch` を報告する場合は、現在の Gateway トークンでノードを再インストールまたは再起動します。 -LAN Gateway の場合、通常は次を意味します: +`googlemeet setup` が `chrome-node-connected` で失敗する場合、または Gateway ログに `gateway token mismatch` が報告される場合は、現在の Gateway トークンで node を再インストールまたは再起動します。LAN Gateway では通常、これは次を意味します。 ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -1162,7 +1184,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -その後、ノードサービスを再読み込みし、再実行します: +その後、node サービスをリロードし、再実行します。 ```bash openclaw googlemeet setup @@ -1171,102 +1193,65 @@ openclaw nodes status --connected ### ブラウザは開くがエージェントが参加できない -観察のみの参加には `googlemeet test-listen`、リアルタイム参加には `googlemeet test-speech` を実行し、 -返された Chrome の健全性を確認します。どちらかのプローブが `manualActionRequired: true` を報告した場合は、 -オペレーターに `manualActionMessage` を表示し、ブラウザ操作が完了するまで再試行を停止します。 +観察専用の参加には `googlemeet test-listen` を、リアルタイム参加には `googlemeet test-speech` を実行し、その後返された Chrome ヘルスを確認します。どちらかのプローブが `manualActionRequired: true` を報告した場合は、`manualActionMessage` をオペレーターに表示し、ブラウザ操作が完了するまで再試行を停止します。 一般的な手動操作: - Chrome プロファイルにサインインします。 -- Meet ホストアカウントからゲストを承認します。 -- Chrome のネイティブ権限プロンプトが表示されたときに、Chrome のマイク/カメラ権限を付与します。 +- Meet ホストアカウントからゲストを許可します。 +- Chrome のネイティブ権限プロンプトが表示されたら、Chrome のマイク/カメラ権限を付与します。 - 固まった Meet 権限ダイアログを閉じるか修復します。 -Meet に「Do you want people to hear you in the meeting?」と表示されるだけで -「not signed in」と報告しないでください。これは Meet の音声選択インタースティシャルです。 -OpenClaw は利用可能な場合、ブラウザ自動化で **Use microphone** をクリックし、 -実際のミーティング状態を待ち続けます。作成のみのブラウザフォールバックでは、URL の作成に -リアルタイム音声パスは不要なため、OpenClaw が **Continue without microphone** をクリックすることがあります。 +Meet に「Do you want people to hear you in the meeting?」と表示されているだけで、「サインインしていない」と報告しないでください。これは Meet の音声選択インタースティシャルです。OpenClaw は利用可能な場合、ブラウザ自動化を通じて **Use microphone** をクリックし、実際の会議状態を待ち続けます。作成専用のブラウザフォールバックでは、URL 作成にリアルタイム音声パスは不要なため、OpenClaw は **Continue without microphone** をクリックすることがあります。 -### ミーティング作成に失敗する +### 会議作成が失敗する -`googlemeet create` は、OAuth 認証情報が設定されている場合、最初に Google Meet API の -`spaces.create` エンドポイントを使用します。OAuth 認証情報がない場合は、固定された Chrome ノードブラウザにフォールバックします。次を確認します: +`googlemeet create` は、OAuth 認証情報が設定されている場合、まず Google Meet API の `spaces.create` エンドポイントを使用します。OAuth 認証情報がない場合は、固定された Chrome node ブラウザにフォールバックします。確認事項: -- API 作成の場合: `oauth.clientId` と `oauth.refreshToken` が設定されているか、 - 対応する `OPENCLAW_GOOGLE_MEET_*` 環境変数が存在します。 -- API 作成の場合: 更新トークンは作成サポートが追加された後に発行されています。 - 古いトークンには `meetings.space.created` スコープがない場合があります。`openclaw googlemeet auth login --json` を再実行し、Plugin 設定を更新します。 -- ブラウザフォールバックの場合: `defaultTransport: "chrome-node"` と - `chromeNode.node` が、`browser.proxy` と `googlemeet.chrome` を持つ接続済みノードを指しています。 -- ブラウザフォールバックの場合: そのノード上の OpenClaw Chrome プロファイルが Google にサインイン済みで、 - `https://meet.google.com/new` を開けます。 -- ブラウザフォールバックの場合: 再試行では、新しいタブを開く前に既存の `https://meet.google.com/new` - または Google アカウントプロンプトタブを再利用します。エージェントがタイムアウトした場合は、 - 別の Meet タブを手動で開くのではなく、ツール呼び出しを再試行します。 -- ブラウザフォールバックの場合: ツールが `manualActionRequired: true` を返した場合は、 - 返された `browser.nodeId`、`browser.targetId`、`browserUrl`、`manualActionMessage` を使用して - オペレーターを案内します。その操作が完了するまでループで再試行しないでください。 -- ブラウザフォールバックの場合: Meet に「Do you want people to hear you in the - meeting?」と表示されたら、タブを開いたままにします。OpenClaw はブラウザ自動化で **Use microphone**、 - または作成のみのフォールバックでは **Continue without microphone** をクリックし、生成された Meet URL を待ち続ける必要があります。 - それができない場合、エラーは `google-login-required` ではなく `meet-audio-choice-required` に言及する必要があります。 +- API 作成の場合: `oauth.clientId` と `oauth.refreshToken` が設定されているか、一致する `OPENCLAW_GOOGLE_MEET_*` 環境変数が存在します。 +- API 作成の場合: refresh token は作成サポートが追加された後に発行されたものです。古いトークンには `meetings.space.created` スコープがない場合があります。`openclaw googlemeet auth login --json` を再実行し、Plugin 設定を更新します。 +- ブラウザフォールバックの場合: `defaultTransport: "chrome-node"` と `chromeNode.node` が、`browser.proxy` と `googlemeet.chrome` を持つ接続済み node を指しています。 +- ブラウザフォールバックの場合: その node 上の OpenClaw Chrome プロファイルが Google にサインインしており、`https://meet.google.com/new` を開けます。 +- ブラウザフォールバックの場合: 再試行は、新しいタブを開く前に既存の `https://meet.google.com/new` または Google アカウントプロンプトタブを再利用します。エージェントがタイムアウトした場合は、別の Meet タブを手動で開くのではなく、ツール呼び出しを再試行します。 +- ブラウザフォールバックの場合: ツールが `manualActionRequired: true` を返した場合は、返された `browser.nodeId`、`browser.targetId`、`browserUrl`、`manualActionMessage` を使用してオペレーターを案内します。その操作が完了するまでループで再試行しないでください。 +- ブラウザフォールバックの場合: Meet に「Do you want people to hear you in the meeting?」と表示されたら、タブを開いたままにします。OpenClaw はブラウザ自動化を通じて **Use microphone**、または作成専用フォールバックでは **Continue without microphone** をクリックし、生成された Meet URL を待ち続ける必要があります。それができない場合、エラーは `google-login-required` ではなく `meet-audio-choice-required` に言及する必要があります。 ### エージェントは参加するが話さない -リアルタイムパスを確認します: +リアルタイムパスを確認します。 ```bash openclaw googlemeet setup openclaw googlemeet doctor ``` -通常の STT -> OpenClaw エージェント -> TTS トークバックパスには `mode: "agent"` を使用し、 -直接リアルタイム音声フォールバックには `mode: "bidi"` を使用します。`mode: "transcribe"` は意図的に -トークバックブリッジを開始しません。観察のみのデバッグでは、参加者が話した後に -`openclaw googlemeet status --json ` を実行し、`captioning`、`transcriptLines`、 -`lastCaptionText` を確認します。`inCall` が true でも `transcriptLines` が `0` のままの場合、 -Meet の字幕が無効である、オブザーバーがインストールされてから誰も話していない、Meet UI が変更された、 -またはミーティングの言語/アカウントでライブ字幕を利用できない可能性があります。 +通常の STT -> OpenClaw エージェント -> TTS トークバックパスには `mode: "agent"` を使用し、直接リアルタイム音声フォールバックには `mode: "bidi"` を使用します。`mode: "transcribe"` は意図的にトークバックブリッジを開始しません。観察専用のデバッグでは、参加者が話した後に `openclaw googlemeet status --json ` を実行し、`captioning`、`transcriptLines`、`lastCaptionText` を確認します。`inCall` が true なのに `transcriptLines` が `0` のままの場合、Meet の字幕が無効になっている、オブザーバーがインストールされてから誰も話していない、Meet UI が変更された、または会議の言語/アカウントでライブ字幕を利用できない可能性があります。 -`googlemeet test-speech` は常にリアルタイムパスを確認し、その呼び出しでブリッジ出力バイトが観測されたかどうかを報告します。 -`speechOutputVerified` が false で `speechOutputTimedOut` が true の場合、リアルタイムプロバイダーは発話を受け入れた可能性がありますが、 -OpenClaw は Chrome 音声ブリッジに到達する新しい出力バイトを確認できていません。 +`googlemeet test-speech` は常にリアルタイムパスを確認し、その呼び出しでブリッジ出力バイトが観測されたかどうかを報告します。`speechOutputVerified` が false で `speechOutputTimedOut` が true の場合、リアルタイムプロバイダーは発話を受け付けた可能性がありますが、OpenClaw は新しい出力バイトが Chrome 音声ブリッジに到達するのを確認できませんでした。 -次も確認します: +次も確認します。 -- Gateway ホストで `OPENAI_API_KEY` や `GEMINI_API_KEY` などのリアルタイムプロバイダーキーが利用可能です。 -- Chrome ホストで `BlackHole 2ch` が表示されています。 -- Chrome ホストに `sox` が存在します。 -- Meet のマイクとスピーカーが、OpenClaw が使用する仮想音声パスを経由するようにルーティングされています。 - ローカル Chrome のリアルタイム参加では、`doctor` に `meet output routed: yes` が表示される必要があります。 +- `OPENAI_API_KEY` や `GEMINI_API_KEY` などのリアルタイムプロバイダーキーが Gateway ホストで利用可能です。 +- `BlackHole 2ch` が Chrome ホストで表示されています。 +- `sox` が Chrome ホストに存在します。 +- Meet のマイクとスピーカーが OpenClaw で使用される仮想音声パスを通るようにルーティングされています。ローカル Chrome のリアルタイム参加では、`doctor` に `meet output routed: yes` が表示される必要があります。 -`googlemeet doctor [session-id]` は、セッション、ノード、通話中状態、手動操作の理由、 -リアルタイムプロバイダー接続、`realtimeReady`、音声入力/出力アクティビティ、最後の音声タイムスタンプ、 -バイトカウンター、ブラウザ URL を出力します。生の JSON が必要な場合は -`googlemeet status [session-id] --json` を使用します。トークンを公開せずに Google Meet OAuth 更新を確認する必要がある場合は -`googlemeet doctor --oauth` を使用します。Google Meet API の証明も必要な場合は `--meeting` または `--create-space` を追加します。 +`googlemeet doctor [session-id]` は、セッション、node、通話中状態、手動操作理由、リアルタイムプロバイダー接続、`realtimeReady`、音声入出力アクティビティ、最後の音声タイムスタンプ、バイトカウンター、ブラウザ URL を出力します。生の JSON が必要な場合は `googlemeet status [session-id] --json` を使用します。トークンを露出せずに Google Meet OAuth refresh を検証する必要がある場合は `googlemeet doctor --oauth` を使用します。Google Meet API の証明も必要な場合は `--meeting` または `--create-space` を追加します。 -エージェントがタイムアウトし、Meet タブがすでに開いていることが見える場合は、別のタブを開かずにそのタブを調査します: +エージェントがタイムアウトし、Meet タブがすでに開いているのが見える場合は、別のタブを開かずにそのタブを確認します。 ```bash openclaw googlemeet recover-tab openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` -同等のツール操作は `recover_current_tab` です。これは選択されたトランスポートの既存の Meet タブにフォーカスし、調査します。 -`chrome` では Gateway を通じたローカルブラウザ制御を使用し、`chrome-node` では設定された Chrome ノードを使用します。 -新しいタブを開いたり、新しいセッションを作成したりしません。ログイン、承認、権限、音声選択状態など、現在のブロッカーを報告します。 -CLI コマンドは設定された Gateway と通信するため、Gateway が実行中である必要があります。 -`chrome-node` では Chrome ノードも接続されている必要があります。 +同等のツールアクションは `recover_current_tab` です。選択された transport の既存の Meet タブにフォーカスして検査します。`chrome` では、Gateway 経由のローカルブラウザ制御を使用します。`chrome-node` では、設定済みの Chrome node を使用します。新しいタブを開いたり新しいセッションを作成したりはしません。ログイン、入室許可、権限、音声選択状態など、現在のブロッカーを報告します。CLI コマンドは設定済み Gateway と通信するため、Gateway が実行中である必要があります。`chrome-node` では Chrome node も接続されている必要があります。 ### Twilio セットアップチェックが失敗する -`voice-call` が許可または有効化されていない場合、`twilio-voice-call-plugin` は失敗します。 -`plugins.allow` に追加し、`plugins.entries.voice-call` を有効にして、Gateway を再読み込みします。 +`voice-call` が許可されていない、または有効化されていない場合、`twilio-voice-call-plugin` は失敗します。`plugins.allow` に追加し、`plugins.entries.voice-call` を有効化して、Gateway をリロードします。 -Twilio バックエンドにアカウント SID、認証トークン、または発信者番号がない場合、 -`twilio-voice-call-credentials` は失敗します。Gateway ホストでこれらを設定します: +Twilio バックエンドに account SID、auth token、または caller number がない場合、`twilio-voice-call-credentials` は失敗します。Gateway ホストでこれらを設定します。 ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1274,16 +1259,11 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -`voice-call` に公開 Webhook 露出がない場合、または `publicUrl` がループバックまたはプライベートネットワーク空間を指している場合、 -`twilio-voice-call-webhook` は失敗します。 -`plugins.entries.voice-call.config.publicUrl` を公開プロバイダー URL に設定するか、 -`voice-call` トンネル/Tailscale 露出を設定します。 +`voice-call` に公開 Webhook 露出がない場合、または `publicUrl` がループバックやプライベートネットワーク空間を指している場合、`twilio-voice-call-webhook` は失敗します。`plugins.entries.voice-call.config.publicUrl` を公開プロバイダー URL に設定するか、`voice-call` トンネル/Tailscale 露出を設定します。 -ループバック URL とプライベート URL は通信事業者コールバックには無効です。 -`publicUrl` として `localhost`、`127.0.0.1`、`0.0.0.0`、`10.x`、`172.16.x`-`172.31.x`、 -`192.168.x`、`169.254.x`、`fc00::/7`、または `fd00::/8` を使用しないでください。 +ループバック URL とプライベート URL は、キャリア callback には有効ではありません。`publicUrl` として `localhost`、`127.0.0.1`、`0.0.0.0`、`10.x`、`172.16.x`-`172.31.x`、`192.168.x`、`169.254.x`、`fc00::/7`、`fd00::/8` を使用しないでください。 -安定した公開 URL の場合: +安定した公開 URL には: ```json5 { @@ -1302,7 +1282,7 @@ export TWILIO_FROM_NUMBER=+15550001234 } ``` -ローカル開発では、プライベートホスト URL ではなく、トンネルまたは Tailscale 露出を使用します: +ローカル開発では、プライベートホスト URL ではなく、トンネルまたは Tailscale 公開を使用します。 ```json5 { @@ -1320,7 +1300,7 @@ export TWILIO_FROM_NUMBER=+15550001234 } ``` -その後、Gateway を再起動または再読み込みし、次を実行します: +その後、Gateway を再起動または再読み込みして、次を実行します。 ```bash openclaw googlemeet setup --transport twilio @@ -1328,21 +1308,21 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` はデフォルトで準備状況のみを確認します。特定の番号でドライランするには: +`voicecall smoke` はデフォルトでは準備状況のみを確認します。特定の番号でドライランするには、次を実行します。 ```bash openclaw voicecall smoke --to "+15555550123" ``` -ライブのアウトバウンド通知通話を意図的に発信したい場合にのみ、`--yes` を追加します: +ライブのアウトバウンド通知通話を発信する意図がある場合にのみ、`--yes` を追加します。 ```bash openclaw voicecall smoke --to "+15555550123" --yes ``` -### Twilio 通話は開始するがミーティングに入らない +### Twilio 通話は開始するが、ミーティングに参加しない -Meet イベントが電話ダイヤルイン詳細を公開していることを確認します。正確なダイヤルイン番号と PIN、またはカスタム DTMF シーケンスを渡します: +Meet イベントで電話ダイヤルイン情報が公開されていることを確認します。正確なダイヤルイン番号と PIN、またはカスタム DTMF シーケンスを渡します。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1351,35 +1331,37 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -プロバイダーが PIN を入力する前に一時停止を必要とする場合は、`--dtmf-sequence` で先頭の `w` またはカンマを使用します。 +プロバイダーが PIN 入力前の一時停止を必要とする場合は、`--dtmf-sequence` で先頭の `w` またはカンマを使用します。 -電話通話は作成されたものの、Meet の参加者一覧にダイヤルイン参加者が表示されない場合: +電話通話は作成されているのに Meet の参加者一覧にダイヤルイン参加者が表示されない場合: -- `openclaw googlemeet doctor ` を実行して、委任された Twilio の通話 ID、DTMF がキューに入ったかどうか、イントロのあいさつが要求されたかどうかを確認します。 +- `openclaw googlemeet doctor ` を実行し、委任された Twilio 通話 ID、DTMF がキューに入ったかどうか、イントロのあいさつがリクエストされたかどうかを確認します。 - `openclaw voicecall status --call-id ` を実行し、通話がまだアクティブであることを確認します。 -- `openclaw voicecall tail` を実行し、Twilio の Webhook が Gateway に到達していることを確認します。 -- `openclaw logs --follow` を実行し、Twilio Meet シーケンスを探します。Google Meet が参加を委任し、Voice Call が電話レッグを開始し、Google Meet が `voiceCall.dtmfDelayMs` だけ待機し、`voicecall.dtmf` で DTMF を送信し、`voiceCall.postDtmfSpeechDelayMs` だけ待機してから、`voicecall.speak` でイントロ音声を要求します。 -- `openclaw googlemeet setup --transport twilio` を再実行します。緑のセットアップチェックは必須ですが、会議 PIN シーケンスが正しいことの証明にはなりません。 +- `openclaw voicecall tail` を実行し、Twilio Webhook が Gateway に届いていることを確認します。 +- `openclaw logs --follow` を実行し、Twilio Meet シーケンスを探します。Google Meet が参加を委任し、Voice Call が電話レッグを開始し、Google Meet が `voiceCall.dtmfDelayMs` 待機し、`voicecall.dtmf` で DTMF を送信し、`voiceCall.postDtmfSpeechDelayMs` 待機してから、`voicecall.speak` でイントロ音声をリクエストします。 +- `openclaw googlemeet setup --transport twilio` を再実行します。セットアップチェックが緑であることは必須ですが、ミーティング PIN シーケンスが正しいことを証明するものではありません。 - ダイヤルイン番号が、PIN と同じ Meet 招待およびリージョンに属していることを確認します。 -- Meet の応答が遅い場合、または DTMF 送信後も通話トランスクリプトに PIN の入力を求めるプロンプトが表示される場合は、`voiceCall.dtmfDelayMs` を増やします。 -- 参加者は参加しているのにあいさつが聞こえない場合は、`openclaw logs --follow` で DTMF 後の `voicecall.speak` 要求と、メディアストリーム TTS 再生または Twilio の `` フォールバックを確認します。通話トランスクリプトにまだ「enter the meeting PIN」が含まれている場合、電話レッグはまだ Meet ルームに参加していないため、会議参加者には音声が聞こえません。 +- Meet の応答が遅い場合、または DTMF 送信後も通話トランスクリプトに PIN を求めるプロンプトが表示される場合は、`voiceCall.dtmfDelayMs` を増やします。 +- 参加者は参加しているのにあいさつが聞こえない場合は、`openclaw logs --follow` で DTMF 後の `voicecall.speak` リクエストと、メディアストリーム TTS 再生または Twilio `` フォールバックを確認します。通話トランスクリプトにまだ「enter the meeting PIN」が含まれている場合、電話レッグはまだ Meet ルームに参加していないため、ミーティング参加者には音声が聞こえません。 -Webhook が到達しない場合は、まず Voice Call Plugin をデバッグします。プロバイダーは `plugins.entries.voice-call.config.publicUrl` または構成済みトンネルに到達できる必要があります。[Voice Call のトラブルシューティング](/ja-JP/plugins/voice-call#troubleshooting)を参照してください。 +Webhook が届かない場合は、まず Voice Call Plugin をデバッグします。プロバイダーが `plugins.entries.voice-call.config.publicUrl` または設定済みトンネルに到達できる必要があります。[Voice Call のトラブルシューティング](/ja-JP/plugins/voice-call#troubleshooting)を参照してください。 -## 注記 +## メモ -Google Meet の公式メディア API は受信指向であるため、Meet 通話で発話するには引き続き参加者パスが必要です。この Plugin はその境界を明示したままにします。Chrome はブラウザー参加とローカル音声ルーティングを処理し、Twilio は電話ダイヤルイン参加を処理します。 +Google Meet の公式メディア API は受信指向であるため、Meet 通話で発話するには引き続き参加者経路が必要です。この Plugin はその境界を見える形に保ちます。Chrome はブラウザー参加とローカル音声ルーティングを処理し、Twilio は電話ダイヤルイン参加を処理します。 -Chrome のトークバックモードには `BlackHole 2ch` に加えて、次のいずれかが必要です。 +Chrome のトークバックモードには `BlackHole 2ch` と、次のいずれかが必要です。 -- `chrome.audioInputCommand` と `chrome.audioOutputCommand`: OpenClaw がブリッジを所有し、`chrome.audioFormat` の音声をこれらのコマンドと選択されたプロバイダーの間でパイプします。agent モードはリアルタイム文字起こしと通常の TTS を使用し、bidi モードはリアルタイム音声プロバイダーを使用します。デフォルトの Chrome パスは 24 kHz PCM16、`chrome.audioBufferBytes: 4096` です。8 kHz G.711 mu-law は、レガシーのコマンドペア向けに引き続き使用できます。 -- `chrome.audioBridgeCommand`: 外部ブリッジコマンドがローカル音声パス全体を所有し、デーモンの起動または検証後に終了する必要があります。これは `bidi` でのみ有効です。`agent` モードでは TTS 用にコマンドペアへの直接アクセスが必要なためです。 +- `chrome.audioInputCommand` と `chrome.audioOutputCommand`: OpenClaw がブリッジを所有し、`chrome.audioFormat` の音声をそれらのコマンドと選択されたプロバイダーの間でパイプします。エージェントモードはリアルタイム文字起こしと通常の TTS を使用し、bidi モードはリアルタイム音声プロバイダーを使用します。デフォルトの Chrome パスは、`chrome.audioBufferBytes: 4096` の 24 kHz PCM16 です。8 kHz G.711 mu-law は、レガシーのコマンドペア向けに引き続き使用できます。 +- `chrome.audioBridgeCommand`: 外部ブリッジコマンドがローカル音声パス全体を所有し、そのデーモンの起動または検証後に終了する必要があります。これは `bidi` でのみ有効です。`agent` モードでは TTS のためにコマンドペアへの直接アクセスが必要なためです。 -クリーンなデュプレックス音声を得るには、Meet の出力と Meet のマイクを別々の仮想デバイス、または Loopback 形式の仮想デバイスグラフにルーティングします。単一の共有 BlackHole デバイスでは、他の参加者の音声が通話にエコーバックされる可能性があります。 +エージェントモードでエージェントが `google_meet` ツールを呼び出すと、ミーティングコンサルタントセッションは参加者の発話に応答する前に、呼び出し元の現在のトランスクリプトをフォークします。Meet セッションは引き続き別個のままです (`agent::subagent:google-meet:`)。そのため、ミーティングのフォローアップが呼び出し元のトランスクリプトを直接変更することはありません。 -コマンドペアの Chrome ブリッジでは、`chrome.bargeInInputCommand` が別のローカルマイクをリッスンし、人間が話し始めたときにアシスタントの再生をクリアできます。これにより、共有 BlackHole ループバック入力がアシスタント再生中に一時的に抑制されていても、人間の発話がアシスタント出力より優先されます。`chrome.audioInputCommand` や `chrome.audioOutputCommand` と同様に、これはオペレーターが構成するローカルコマンドです。明示的に信頼されたコマンドパスまたは引数リストを使用し、信頼できない場所のスクリプトを指さないでください。 +クリーンな双方向音声のために、Meet の出力と Meet のマイクを別々の仮想デバイス、または Loopback スタイルの仮想デバイスグラフ経由でルーティングします。単一の共有 BlackHole デバイスでは、他の参加者の音声が通話にエコーバックされる可能性があります。 -`googlemeet speak` は Chrome セッションのアクティブなトークバック音声ブリッジをトリガーします。`googlemeet leave` はそのブリッジを停止します。Voice Call Plugin を介して委任された Twilio セッションでは、`leave` は基盤となる音声通話も切断します。API 管理スペースのアクティブな Google Meet 会議も閉じたい場合は、`googlemeet end-active-conference` を使用します。 +コマンドペアの Chrome ブリッジでは、`chrome.bargeInInputCommand` が別のローカルマイクをリッスンし、人間が話し始めたときにアシスタントの再生をクリアできます。これにより、アシスタント再生中に共有 BlackHole ループバック入力が一時的に抑制されている場合でも、人間の発話をアシスタント出力より優先できます。`chrome.audioInputCommand` および `chrome.audioOutputCommand` と同様に、これはオペレーター設定のローカルコマンドです。明示的に信頼されたコマンドパスまたは引数リストを使用し、信頼できない場所のスクリプトを指さないでください。 + +`googlemeet speak` は、Chrome セッションのアクティブなトークバック音声ブリッジをトリガーします。`googlemeet leave` はそのブリッジを停止します。Voice Call Plugin 経由で委任された Twilio セッションでは、`leave` は基礎となる音声通話も切断します。API 管理スペースのアクティブな Google Meet 会議も閉じたい場合は、`googlemeet end-active-conference` を使用します。 ## 関連 diff --git a/docs/ja-JP/providers/elevenlabs.md b/docs/ja-JP/providers/elevenlabs.md index 43d045e8e..56cc3c8a0 100644 --- a/docs/ja-JP/providers/elevenlabs.md +++ b/docs/ja-JP/providers/elevenlabs.md @@ -1,38 +1,38 @@ --- read_when: - - OpenClaw で ElevenLabs の text-to-speech を使いたい場合 - - 音声添付ファイルに ElevenLabs Scribe speech-to-text を使いたい場合 - - Voice Call に ElevenLabs の realtime transcription を使いたい場合 -summary: OpenClaw で ElevenLabs の speech、Scribe STT、Realtime transcription を使う + - OpenClawでElevenLabsのテキスト読み上げを使いたい + - 音声添付ファイルに ElevenLabs Scribe の音声テキスト変換を使いたい + - 音声通話または Google Meet で ElevenLabs のリアルタイム文字起こしを使用したい場合 +summary: OpenClawでElevenLabs音声、Scribe STT、リアルタイム文字起こしを使う title: ElevenLabs x-i18n: - generated_at: "2026-04-25T13:57:09Z" - model: gpt-5.4 + generated_at: "2026-05-04T07:04:03Z" + model: gpt-5.5 provider: openai - source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a + source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b source_path: providers/elevenlabs.md - workflow: 15 + workflow: 16 --- -OpenClaw は、text-to-speech、Scribe -v2 によるバッチ speech-to-text、そして Scribe v2 Realtime による Voice Call ストリーミング STT に ElevenLabs を使います。 +OpenClaw は、テキスト読み上げに ElevenLabs、Scribe +v2 によるバッチ音声テキスト化、Scribe v2 Realtime によるストリーミング STT を使用します。 -| Capability | OpenClaw 画面 | デフォルト | -| ------------------------ | ----------------------------------------------- | -------------------------- | -| Text-to-speech | `messages.tts` / `talk` | `eleven_multilingual_v2` | -| Batch speech-to-text | `tools.media.audio` | `scribe_v2` | -| Streaming speech-to-text | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` | +| 機能 | OpenClaw のサーフェス | デフォルト | +| ------------------------ | -------------------------------------------------------------------- | ------------------------ | +| テキスト読み上げ | `messages.tts` / `talk` | `eleven_multilingual_v2` | +| バッチ音声テキスト化 | `tools.media.audio` | `scribe_v2` | +| ストリーミング音声テキスト化 | Voice Call ストリーミングまたは Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` | ## 認証 -環境変数に `ELEVENLABS_API_KEY` を設定してください。既存の ElevenLabs ツールとの -互換性のため、`XI_API_KEY` も受け付けられます。 +環境で `ELEVENLABS_API_KEY` を設定します。既存の ElevenLabs ツールとの互換性のため、 +`XI_API_KEY` も受け付けられます。 ```bash export ELEVENLABS_API_KEY="..." ``` -## Text-to-speech +## テキスト読み上げ ```json5 { @@ -50,12 +50,12 @@ export ELEVENLABS_API_KEY="..." } ``` -ElevenLabs v3 TTS を使うには `modelId` を `eleven_v3` に設定してください。OpenClaw は既存インストール向けのデフォルトとして -`eleven_multilingual_v2` を維持しています。 +ElevenLabs v3 TTS を使用するには、`modelId` を `eleven_v3` に設定します。OpenClaw は既存のインストール向けに、 +`eleven_multilingual_v2` をデフォルトのままにします。 -## Speech-to-text +## 音声テキスト化 -受信音声添付ファイルや短い録音音声セグメントには Scribe v2 を使います。 +受信音声添付ファイルと短い録音音声セグメントには Scribe v2 を使用します。 ```json5 { @@ -70,22 +70,21 @@ ElevenLabs v3 TTS を使うには `modelId` を `eleven_v3` に設定してく } ``` -OpenClaw は multipart 音声を ElevenLabs の `/v1/speech-to-text` に -`model_id: "scribe_v2"` 付きで送信します。言語ヒントがある場合は `language_code` にマッピングされます。 +OpenClaw は、`model_id: "scribe_v2"` を指定してマルチパート音声を ElevenLabs `/v1/speech-to-text` に送信します。言語ヒントがある場合は `language_code` にマッピングされます。 -## Voice Call ストリーミング STT +## ストリーミング STT -バンドルされた `elevenlabs` Plugin は、Voice Call -ストリーミング文字起こし用に Scribe v2 Realtime を登録します。 +同梱の `elevenlabs` Plugin は、Voice Call と +Google Meet エージェントモードのストリーミング文字起こし向けに Scribe v2 Realtime を登録します。 -| Setting | Config path | デフォルト | -| --------------- | ------------------------------------------------------------------------- | --------------------------------------------------- | -| API key | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | `ELEVENLABS_API_KEY` / `XI_API_KEY` にフォールバック | -| Model | `...elevenlabs.modelId` | `scribe_v2_realtime` | -| Audio format | `...elevenlabs.audioFormat` | `ulaw_8000` | -| Sample rate | `...elevenlabs.sampleRate` | `8000` | -| Commit strategy | `...elevenlabs.commitStrategy` | `vad` | -| Language | `...elevenlabs.languageCode` | （未設定） | +| 設定 | 設定パス | デフォルト | +| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | +| API キー | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | `ELEVENLABS_API_KEY` / `XI_API_KEY` にフォールバック | +| モデル | `...elevenlabs.modelId` | `scribe_v2_realtime` | +| 音声形式 | `...elevenlabs.audioFormat` | `ulaw_8000` | +| サンプルレート | `...elevenlabs.sampleRate` | `8000` | +| コミット戦略 | `...elevenlabs.commitStrategy` | `vad` | +| 言語 | `...elevenlabs.languageCode` | (未設定) | ```json5 { @@ -113,12 +112,16 @@ OpenClaw は multipart 音声を ElevenLabs の `/v1/speech-to-text` に ``` -Voice Call は、Twilio メディアを 8 kHz G.711 u-law として受信します。ElevenLabs の realtime -provider はデフォルトで `ulaw_8000` を使うため、電話音声フレームは -トランスコードなしで転送できます。 +Voice Call は Twilio メディアを 8 kHz G.711 u-law として受信します。ElevenLabs リアルタイムプロバイダーのデフォルトは `ulaw_8000` のため、電話フレームはトランスコードなしで転送できます。 +Google Meet エージェントモードでは、 +`plugins.entries.google-meet.config.realtime.transcriptionProvider` を +`"elevenlabs"` に設定し、同じプロバイダーブロックを +`plugins.entries.google-meet.config.realtime.providers.elevenlabs` の下に設定します。 + ## 関連 -- [Text-to-speech](/ja-JP/tools/tts) -- [Model selection](/ja-JP/concepts/model-providers) +- [テキスト読み上げ](/ja-JP/tools/tts) +- [Google Meet](/ja-JP/plugins/google-meet) +- [モデル選択](/ja-JP/concepts/model-providers) diff --git a/docs/ja-JP/reference/RELEASING.md b/docs/ja-JP/reference/RELEASING.md index a970a429a..d8ecee818 100644 --- a/docs/ja-JP/reference/RELEASING.md +++ b/docs/ja-JP/reference/RELEASING.md @@ -2,19 +2,19 @@ read_when: - 公開リリースチャネルの定義を探しています - リリース検証またはパッケージ受け入れの実行 - - バージョン命名とリリース頻度を確認しています -summary: リリースレーン、オペレーター用チェックリスト、検証ボックス、バージョン命名、リリース周期 + - バージョン命名とリリース周期を確認する +summary: リリースレーン、オペレーターチェックリスト、検証ボックス、バージョン命名、リリース周期 title: リリースポリシー x-i18n: - generated_at: "2026-05-03T21:37:51Z" + generated_at: "2026-05-04T07:04:11Z" model: gpt-5.5 provider: openai - source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba + source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw には 3 つの公開リリースレーンがあります: +OpenClaw には 3 つの公開リリースレーンがあります。 - stable: デフォルトでは npm `beta` に公開され、明示的に要求された場合は npm `latest` に公開されるタグ付きリリース - beta: npm `beta` に公開されるプレリリースタグ @@ -22,128 +22,158 @@ OpenClaw には 3 つの公開リリースレーンがあります: ## バージョン命名 -- Stable リリースバージョン: `YYYY.M.D` +- 安定版リリースバージョン: `YYYY.M.D` - Git タグ: `vYYYY.M.D` -- Stable 修正リリースバージョン: `YYYY.M.D-N` +- 安定版修正リリースバージョン: `YYYY.M.D-N` - Git タグ: `vYYYY.M.D-N` - Beta プレリリースバージョン: `YYYY.M.D-beta.N` - Git タグ: `vYYYY.M.D-beta.N` - 月または日をゼロ埋めしない -- `latest` は現在昇格済みの stable npm リリースを意味する +- `latest` は現在昇格済みの安定版 npm リリースを意味する - `beta` は現在の beta インストール対象を意味する -- Stable および stable 修正リリースは、デフォルトでは npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みの beta ビルドを後から昇格することもできる -- すべての stable OpenClaw リリースは npm パッケージと macOS アプリを一緒に出荷する。 - beta リリースでは通常、npm/パッケージ経路を先に検証して公開し、mac アプリのビルド/署名/公証は明示的に要求されない限り stable 用に確保する +- 安定版と安定版修正リリースは、デフォルトでは npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みの beta ビルドを後で昇格することもできる +- すべての安定版 OpenClaw リリースは npm パッケージと macOS アプリを一緒に出荷する。 + beta リリースは通常、まず npm/パッケージ経路を検証して公開し、 + mac アプリのビルド/署名/公証は明示的に要求されない限り安定版用に予約される ## リリース周期 -- リリースは beta を先行して進む -- Stable は最新の beta が検証された後にのみ続く -- メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを作成するため、リリース検証と修正が `main` 上の新規開発をブロックしない -- beta タグがプッシュまたは公開済みで修正が必要な場合、メンテナーは古い beta タグを削除または再作成するのではなく、次の `-beta.N` タグを作成する -- 詳細なリリース手順、承認、認証情報、復旧メモはメンテナー専用 +- リリースは beta 優先で進める +- 安定版は最新の beta が検証された後にのみ続く +- メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを切る。 + これにより、リリース検証と修正が `main` 上の新規開発をブロックしない +- beta タグが push または公開された後に修正が必要になった場合、メンテナーは古い beta タグを削除または再作成するのではなく、 + 次の `-beta.N` タグを切る +- 詳細なリリース手順、承認、認証情報、復旧メモは + メンテナー専用 ## リリース担当者チェックリスト -このチェックリストは、リリースフローの公開されている形を示すものです。非公開の認証情報、 -署名、公証、dist-tag 復旧、緊急ロールバックの詳細は、 +このチェックリストはリリースフローの公開上の形です。非公開の認証情報、 +署名、公証、dist-tag 復旧、緊急ロールバックの詳細は メンテナー専用のリリース runbook に残します。 -1. 現在の `main` から開始する: 最新を pull し、対象コミットがプッシュ済みであることを確認し、 - 現在の `main` CI がブランチ作成に十分な程度に green であることを確認する。 -2. 実際のコミット履歴から `/changelog` で `CHANGELOG.md` の先頭セクションを書き直し、 - エントリをユーザー向けに保ち、コミットしてプッシュし、ブランチ作成前にもう一度 rebase/pull する。 +1. 現在の `main` から開始する: 最新を pull し、対象コミットが push 済みであることを確認し、 + 現在の `main` CI がブランチ作成元として十分に green であることを確認する。 +2. 実際のコミット履歴から `/changelog` で `CHANGELOG.md` の最上位セクションを書き直し、 + エントリをユーザー向けに保ち、commit して push し、ブランチ作成前にもう一度 rebase/pull する。 3. `src/plugins/compat/registry.ts` と - `src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性記録をレビューする。アップグレード経路が引き続きカバーされる場合にのみ期限切れの互換性を削除するか、意図的に保持する理由を記録する。 + `src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性レコードをレビューする。期限切れの + 互換性は、アップグレード経路が引き続きカバーされる場合のみ削除する。そうでない場合は、 + 意図的に保持する理由を記録する。 4. 現在の `main` から `release/YYYY.M.D` を作成する。通常のリリース作業を - `main` で直接行わない。 -5. 目的のタグに必要なすべてのバージョン箇所を更新し、 - `pnpm plugins:sync` を実行して公開可能な Plugin パッケージがリリースバージョンと互換性メタデータを共有するようにしてから、ローカルの決定的 preflight を実行する: + `main` 上で直接行わない。 +5. 予定タグに必要なすべてのバージョン箇所を更新し、 + `pnpm plugins:sync` を実行して公開可能な Plugin パッケージがリリース + バージョンと互換性メタデータを共有するようにする。その後、ローカルの決定的な事前確認を実行する: `pnpm check:test-types`, `pnpm check:architecture`, - `pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, および + `pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, and `pnpm release:check`。 -6. `OpenClaw NPM Release` を `preflight_only=true` で実行する。タグが存在する前は、 - 検証専用 preflight に完全な 40 文字のリリースブランチ SHA を使用できる。成功した `preflight_run_id` を保存する。 -7. リリースブランチ、タグ、または完全なコミット SHA に対して `Full Release Validation` ですべてのプレリリーステストを開始する。これは 4 つの大きなリリーステストボックス、Vitest、Docker、QA Lab、Package のための単一の手動エントリポイントである。 -8. 検証に失敗した場合は、リリースブランチ上で修正し、その修正を証明する最小の失敗ファイル、レーン、workflow job、パッケージプロファイル、プロバイダー、またはモデル allowlist を再実行する。変更された表面により以前の証拠が古くなる場合にのみ、umbrella 全体を再実行する。 -9. beta の場合、`vYYYY.M.D-beta.N` にタグ付けし、一致する `release/YYYY.M.D` ブランチから `OpenClaw Release Publish` を実行する。これは `pnpm plugins:sync:check` を検証し、すべての公開可能な Plugin パッケージを最初に npm に公開し、次に同じセットを ClawPack npm-pack tarball として ClawHub に公開し、その後一致する dist-tag で準備済みの OpenClaw npm preflight artifact を昇格する。公開後、公開済みの `openclaw@YYYY.M.D-beta.N` または - `openclaw@beta` パッケージに対して公開後パッケージ - acceptance を実行する。プッシュ済みまたは公開済みのプレリリースに修正が必要な場合は、 - 次の一致するプレリリース番号を作成する。古いプレリリースを削除したり書き換えたりしない。 -10. stable の場合、検証済みの beta またはリリース候補に必要な検証証拠がある場合にのみ続行する。Stable npm 公開も `OpenClaw Release Publish` を通じて行い、 - `preflight_run_id` 経由で成功した preflight artifact を再利用する。stable macOS リリース準備には、 - パッケージ化された `.zip`, `.dmg`, `.dSYM.zip` と、`main` 上で更新された `appcast.xml` も必要である。 -11. 公開後、npm 公開後 verifier、公開後のチャンネル証明が必要な場合の任意のスタンドアロン公開済み npm Telegram E2E、 - 必要時の dist-tag 昇格、一致する完全な `CHANGELOG.md` セクションからの GitHub release/prerelease notes、そしてリリース告知手順を実行する。 +6. `preflight_only=true` で `OpenClaw NPM Release` を実行する。タグが存在する前は、 + 検証専用の事前確認として、40 文字の完全なリリースブランチ SHA を使用できる。 + 成功した `preflight_run_id` を保存する。 +7. リリースブランチ、タグ、または完全なコミット SHA を対象に `Full Release Validation` で + すべてのプレリリーステストを開始する。これは 4 つの大きなリリーステストボックス、 + Vitest、Docker、QA Lab、Package の単一の手動エントリポイントです。 +8. 検証に失敗した場合は、リリースブランチ上で修正し、修正を証明する最小の失敗 + ファイル、レーン、ワークフロージョブ、パッケージプロファイル、プロバイダー、またはモデル allowlist を再実行する。 + 変更範囲によって以前の証拠が古くなる場合のみ、全体の umbrella を再実行する。 +9. beta の場合は `vYYYY.M.D-beta.N` をタグ付けし、その後、一致する + `release/YYYY.M.D` ブランチから `OpenClaw Release Publish` を実行する。これは `pnpm plugins:sync:check` を検証し、 + すべての公開可能な Plugin パッケージをまず npm に公開し、同じ + セットを ClawPack npm-pack tarball として次に ClawHub へ公開し、その後、一致する dist-tag で + 準備済みの OpenClaw npm 事前確認アーティファクトを昇格する。公開後、 + 公開済みの `openclaw@YYYY.M.D-beta.N` または + `openclaw@beta` パッケージに対して、公開後パッケージ + 受け入れを実行する。push または公開済みのプレリリースに修正が必要な場合は、 + 次の一致するプレリリース番号を切る。古い + プレリリースを削除または書き換えない。 +10. 安定版の場合は、検証済みの beta またはリリース候補に必要な + 検証証拠がある場合のみ続行する。安定版 npm 公開も + `OpenClaw Release Publish` を通し、`preflight_run_id` で + 成功済みの事前確認アーティファクトを再利用する。安定版 macOS リリース準備には、 + パッケージ化された `.zip`, `.dmg`, `.dSYM.zip` と、`main` 上で更新済みの `appcast.xml` も必要です。 +11. 公開後、npm 公開後 verifier、公開後チャンネル証拠が必要な場合の任意のスタンドアロン + published-npm Telegram E2E、必要に応じた dist-tag 昇格、 + 一致する完全な `CHANGELOG.md` セクションからの GitHub リリース/プレリリースノート、 + そしてリリース告知 + 手順を実行する。 -## リリース preflight +## リリース事前確認 -- リリースのプリフライト前に `pnpm check:test-types` を実行し、テストの TypeScript が高速なローカル `pnpm check` ゲートの外でもカバーされるようにする -- リリースのプリフライト前に `pnpm check:architecture` を実行し、より広範な import サイクルとアーキテクチャ境界チェックが高速なローカルゲートの外でもグリーンになるようにする -- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行し、想定される `dist/*` リリース成果物と Control UI バンドルがパック検証ステップ用に存在するようにする -- ルートのバージョンバンプ後、タグ付け前に `pnpm plugins:sync` を実行する。これは公開可能な plugin パッケージバージョン、OpenClaw ピア/API 互換性メタデータ、ビルドメタデータ、plugin changelog スタブをコアのリリースバージョンに合わせて更新する。`pnpm plugins:sync:check` は変更を行わないリリースガードであり、このステップを忘れていた場合、publish ワークフローは registry の変更前に失敗する。 -- リリース承認前に手動の `Full Release Validation` ワークフローを実行し、すべてのプレリリース test box を単一のエントリポイントから開始する。ブランチ、タグ、または完全なコミット SHA を受け取り、手動の `CI` をディスパッチし、install smoke、package acceptance、Docker リリースパススイート、live/E2E、OpenWebUI、QA Lab parity、Matrix、Telegram レーン向けに `OpenClaw Release Checks` をディスパッチする。`release_profile=full` と `rerun_group=all` を指定すると、リリースチェックの `release-package-under-test` 成果物に対して package Telegram E2E も実行する。公開後、同じ Telegram E2E で公開済み npm パッケージも検証する必要がある場合は `npm_telegram_package_spec` を指定する。公開後、Package Acceptance で SHA からビルドした成果物ではなく出荷済み npm パッケージに対して package/update matrix を実行する必要がある場合は `package_acceptance_package_spec` を指定する。Telegram E2E を強制せずに、検証が公開済み npm パッケージと一致することを private evidence report で証明する場合は `evidence_package_spec` を指定する。例: +- リリースの事前確認前に `pnpm check:test-types` を実行して、テストの TypeScript がより高速なローカルの `pnpm check` ゲートの外でも対象になるようにする +- リリースの事前確認前に `pnpm check:architecture` を実行して、より広範な import cycle とアーキテクチャ境界チェックが、より高速なローカルゲートの外でもグリーンになるようにする +- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行して、pack 検証ステップに必要な `dist/*` リリース成果物と Control UI バンドルが存在するようにする +- ルートのバージョン bump 後、タグ付け前に `pnpm plugins:sync` を実行する。これは publish 可能な Plugin パッケージのバージョン、OpenClaw peer/API 互換性メタデータ、build メタデータ、Plugin changelog スタブを core リリースバージョンに合わせて更新する。`pnpm plugins:sync:check` は変更を加えないリリースガードであり、このステップを忘れていると publish ワークフローは registry を変更する前に失敗する。 +- リリース承認前に手動の `Full Release Validation` ワークフローを実行して、すべてのリリース前テストボックスを単一のエントリポイントから起動する。これは branch、tag、または完全な commit SHA を受け取り、手動 `CI` を dispatch し、install smoke、package acceptance、Docker リリースパス suite、live/E2E、OpenWebUI、QA Lab parity、Matrix、Telegram lane 用に `OpenClaw Release Checks` を dispatch する。`release_profile=full` と `rerun_group=all` では、release checks からの `release-package-under-test` artifact に対して package Telegram E2E も実行する。同じ Telegram E2E で publish 済み npm パッケージも証明する必要がある場合は、publish 後に `npm_telegram_package_spec` を指定する。Package Acceptance が SHA から build された artifact ではなく出荷済み npm パッケージに対して package/update matrix を実行する必要がある場合は、publish 後に `package_acceptance_package_spec` を指定する。Telegram E2E を強制せずに、private evidence report で検証が publish 済み npm パッケージに一致することを証明する必要がある場合は、`evidence_package_spec` を指定する。例: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- リリース作業を継続しながらパッケージ候補のサイドチャネル証跡が必要な場合は、手動の `Package Acceptance` ワークフローを実行する。`openclaw@beta`、`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使う。現在の `workflow_ref` ハーネスで信頼済みの `package_ref` ブランチ/タグ/SHA を pack するには `source=ref` を使う。必須の SHA-256 付き HTTPS tarball には `source=url` を使う。または別の GitHub Actions run がアップロードした tarball には `source=artifact` を使う。このワークフローは候補を `package-under-test` に解決し、その tarball に対して Docker E2E リリーススケジューラを再利用し、`telegram_mode=mock-openai` または `telegram_mode=live-frontier` で同じ tarball に対して Telegram QA を実行できる。選択した Docker レーンに `published-upgrade-survivor` が含まれる場合、package 成果物が候補となり、`published_upgrade_survivor_baseline` が公開済み baseline を選択する。 +- リリース作業を続けながら package candidate の side-channel 証明が必要な場合は、手動の `Package Acceptance` ワークフローを実行する。`openclaw@beta`、`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使う。現在の `workflow_ref` harness で信頼済みの `package_ref` branch/tag/SHA を pack するには `source=ref` を使う。必須 SHA-256 付きの HTTPS tarball には `source=url` を使う。別の GitHub Actions run が upload した tarball には `source=artifact` を使う。このワークフローは candidate を `package-under-test` に解決し、その tarball に対して Docker E2E release scheduler を再利用し、`telegram_mode=mock-openai` または `telegram_mode=live-frontier` で同じ tarball に対する Telegram QA も実行できる。選択された Docker lane に `published-upgrade-survivor` が含まれる場合、package artifact が candidate になり、`published_upgrade_survivor_baseline` が publish 済み baseline を選択する。 例: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` - 一般的なプロファイル: - - `smoke`: install/channel/agent、Gateway network、config reload レーン - - `package`: OpenWebUI または live ClawHub を含まない、成果物ネイティブの package/update/plugin レーン - - `product`: package プロファイルに加えて MCP channel、cron/subagent cleanup、OpenAI web search、OpenWebUI - - `full`: OpenWebUI を含む Docker リリースパスチャンク - - `custom`: 焦点を絞った再実行用の正確な `docker_lanes` 選択 -- リリース候補に対する通常の完全な CI カバレッジだけが必要な場合は、手動の `CI` ワークフローを直接実行する。手動 CI ディスパッチは changed スコープをバイパスし、Linux Node shards、bundled-plugin shards、channel contracts、Node 22 compatibility、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android、Control UI i18n レーンを強制する。 + 一般的な profile: + - `smoke`: install/channel/agent、gateway network、config reload lane + - `package`: OpenWebUI や live ClawHub を含まない artifact-native package/update/plugin lane + - `product`: package profile に MCP channel、cron/subagent cleanup、OpenAI web search、OpenWebUI を加えたもの + - `full`: OpenWebUI 付きの Docker リリースパス chunk + - `custom`: focused rerun 用の正確な `docker_lanes` 選択 +- リリース candidate に対する通常の full CI coverage だけが必要な場合は、手動の `CI` ワークフローを直接実行する。手動 CI dispatch は changed scoping を bypass し、Linux Node shard、bundled-plugin shard、channel contract、Node 22 互換性、`check`、`check-additional`、build smoke、docs check、Python skills、Windows、macOS、Android、Control UI i18n lane を強制する。 例: `gh workflow run ci.yml --ref release/YYYY.M.D` -- リリースの telemetry を検証する場合は `pnpm qa:otel:smoke` を実行する。これはローカル OTLP/HTTP receiver を通じて QA-lab を実行し、Opik、Langfuse、その他の外部 collector を必要とせずに、export された trace span 名、制限付き attributes、content/identifier redaction を検証する。 -- タグ付きリリースのたびに、事前に `pnpm release:check` を実行する -- タグが存在した後、変更を伴う publish sequence には `OpenClaw Release Publish` を実行する。`release/YYYY.M.D` からディスパッチする（main から到達可能なタグを公開する場合は `main`）。リリースタグと成功した OpenClaw npm `preflight_run_id` を渡し、意図的に焦点を絞った修復を行う場合を除き、デフォルトの plugin publish scope `all-publishable` を維持する。このワークフローは plugin npm publish、plugin ClawHub publish、OpenClaw npm publish を直列化し、外部化された plugins より前にコアパッケージが公開されないようにする。 -- リリースチェックは現在、別の手動ワークフローで実行される: +- リリース telemetry を検証するときは `pnpm qa:otel:smoke` を実行する。これは local OTLP/HTTP receiver 経由で QA-lab を実行し、Opik、Langfuse、その他の外部 collector を必要とせずに、export された trace span name、bounded attribute、content/identifier redaction を検証する。 +- タグ付きリリースのたびに `pnpm release:check` を実行する +- tag が存在した後、変更を伴う publish sequence には `OpenClaw Release Publish` を実行する。`release/YYYY.M.D` から dispatch し（main から到達可能な tag を publish する場合は `main`）、release tag と成功した OpenClaw npm `preflight_run_id` を渡し、意図的に focused repair を実行している場合を除き、default Plugin publish scope の `all-publishable` を維持する。このワークフローは Plugin npm publish、Plugin ClawHub publish、OpenClaw npm publish を直列化し、外部化された plugins より先に core パッケージが publish されないようにする。 +- Release checks は現在、別の手動ワークフローで実行される: `OpenClaw Release Checks` -- `OpenClaw Release Checks` は、リリース承認前に QA Lab mock parity レーンに加えて、高速な live Matrix プロファイルと Telegram QA レーンも実行する。live レーンは `qa-live-shared` environment を使用する。Telegram は Convex CI credential lease も使用する。Matrix transport、media、E2EE inventory 全体を並列で実行したい場合は、`matrix_profile=all` と `matrix_shards=true` を指定して手動の `QA-Lab - All Lanes` ワークフローを実行する。 -- クロス OS の install と upgrade runtime 検証は、公開の `OpenClaw Release Checks` と `Full Release Validation` の一部であり、reusable workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す -- この分割は意図的なもの。実際の npm リリースパスは短く、決定的で、成果物中心に保ち、時間のかかる live check は publish を停滞またはブロックしないように独自のレーンに置く -- secrets を持つリリースチェックは、`Full Release Validation` 経由、または `main`/release workflow ref からディスパッチし、workflow logic と secrets が制御された状態を保つ -- `OpenClaw Release Checks` は、解決されたコミットが OpenClaw のブランチまたはリリースタグから到達可能である限り、ブランチ、タグ、または完全なコミット SHA を受け付ける -- `OpenClaw NPM Release` の検証専用 preflight も、push 済みタグを要求せずに、現在の完全な 40 文字の workflow-branch commit SHA を受け付ける -- その SHA パスは検証専用であり、実際の publish に昇格できない -- SHA モードでは、ワークフローは package metadata check のためだけに `v` を合成する。実際の publish には引き続き実際のリリースタグが必要 -- どちらのワークフローも実際の publish と promotion パスを GitHub-hosted runner 上に保ち、変更を伴わない検証パスではより大きな Blacksmith Linux runner を使用できる -- そのワークフローは `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` を、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方の workflow secrets を使って実行する -- npm release preflight は、別の release checks レーンを待機しなくなった -- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（または対応する beta/correction タグ）を実行する -- npm publish 後、公開済み registry install パスを新しい一時 prefix で検証するために `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（または対応する beta/correction バージョン）を実行する -- beta publish 後、共有の貸与 Telegram credential pool を使い、公開済み npm パッケージに対して installed-package onboarding、Telegram setup、実際の Telegram E2E を検証するために、`OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` を実行する。ローカル maintainer の単発実行では Convex vars を省略し、3 つの `OPENCLAW_QA_TELEGRAM_*` env credentials を直接渡してもよい。 -- Maintainers は、手動の `NPM Telegram Beta E2E` ワークフローを通じて、GitHub Actions から同じ post-publish check を実行できる。これは意図的に manual-only であり、すべての merge で実行されるわけではない。 -- Maintainer release automation は現在、preflight-then-promote を使用する: - - 実際の npm publish は、成功した npm `preflight_run_id` を通過している必要がある - - 実際の npm publish は、成功した preflight run と同じ `main` または `release/YYYY.M.D` ブランチからディスパッチされている必要がある - - 安定版 npm リリースのデフォルトは `beta` - - 安定版 npm publish は、workflow input で明示的に `latest` を対象にできる - - token ベースの npm dist-tag mutation は現在、セキュリティ上の理由から `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` にある。これは、公開リポジトリが OIDC-only publish を維持する一方で、`npm dist-tag add` には依然として `NPM_TOKEN` が必要なため - - 公開 `macOS Release` は validation-only。タグが release branch のみに存在し、workflow が `main` からディスパッチされる場合は、`public_release_branch=release/YYYY.M.D` を設定する - - 実際の private mac publish は、成功した private mac `preflight_run_id` と `validate_run_id` を通過している必要がある - - 実際の publish パスは、準備済み成果物を再ビルドするのではなく昇格する -- `YYYY.M.D-N` のような安定版 correction release では、post-publish verifier は同じ temp-prefix upgrade path で `YYYY.M.D` から `YYYY.M.D-N` への検証も行い、release correction が古い global install を base stable payload のまま静かに残さないようにする +- `OpenClaw Release Checks` は、リリース承認前に QA Lab mock parity lane に加えて、高速な live Matrix profile と Telegram QA lane も実行する。live lane は `qa-live-shared` environment を使い、Telegram は Convex CI credential lease も使う。full Matrix transport、media、E2EE inventory を並列で実行したい場合は、手動の `QA-Lab - All Lanes` ワークフローを `matrix_profile=all` と `matrix_shards=true` で実行する。 +- Cross-OS install と upgrade runtime validation は、再利用可能ワークフロー `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す public `OpenClaw Release Checks` と `Full Release Validation` の一部である +- この分割は意図的なもの: 実際の npm release path は短く、決定的で、artifact-focused に保ち、遅い live check は専用の lane に置くことで、publish を停滞またはブロックしないようにする +- secret を含む release check は、ワークフロー logic と secrets を制御された状態に保つため、`Full Release Validation` 経由または `main`/release workflow ref から dispatch する +- `OpenClaw Release Checks` は、resolved commit が OpenClaw branch または release tag から到達可能である限り、branch、tag、または完全な commit SHA を受け取る +- `OpenClaw NPM Release` の validation-only preflight は、push 済み tag を要求せず、現在の完全な 40 文字 workflow-branch commit SHA も受け取る +- その SHA path は validation-only であり、実際の publish に昇格できない +- SHA mode では、workflow は package metadata check のためだけに `v` を合成する。実際の publish には引き続き実際の release tag が必要である +- どちらのワークフローも実際の publish と promotion path は GitHub-hosted runner 上に保ち、変更を伴わない validation path ではより大きな Blacksmith Linux runner を使える +- そのワークフローは、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方の workflow secret を使って + `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` + を実行する +- npm release preflight は、別の release checks lane を待たなくなった +- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` + （または対応する beta/correction tag）を実行する +- npm publish 後に + `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` + （または対応する beta/correction version）を実行して、fresh temp prefix で publish 済み registry install path を検証する +- beta publish 後に `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` + を実行して、共有の lease 済み Telegram credential pool を使い、publish 済み npm パッケージに対して installed-package onboarding、Telegram setup、実際の Telegram E2E を検証する。ローカル maintainer の単発実行では Convex vars を省略し、3 つの `OPENCLAW_QA_TELEGRAM_*` env credentials を直接渡してもよい。 +- maintainer machine から full post-publish beta smoke を実行するには、`pnpm release:beta-smoke -- --beta betaN` を使う。この helper は Parallels npm update/fresh-target validation を実行し、`NPM Telegram Beta E2E` を dispatch し、正確な workflow run を poll し、artifact を download して Telegram report を出力する。 +- Maintainer は、GitHub Actions から手動の `NPM Telegram Beta E2E` ワークフロー経由で同じ post-publish check を実行できる。これは意図的に manual-only であり、すべての merge で実行されるわけではない。 +- Maintainer release automation は現在 preflight-then-promote を使う: + - 実際の npm publish には成功した npm `preflight_run_id` が必要 + - 実際の npm publish は、成功した preflight run と同じ `main` または `release/YYYY.M.D` branch から dispatch する必要がある + - stable npm release の default は `beta` + - stable npm publish は workflow input で明示的に `latest` を target にできる + - token-based npm dist-tag mutation は現在、security のため `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` にある。`npm dist-tag add` には引き続き `NPM_TOKEN` が必要であり、public repo は OIDC-only publish を維持するためである + - public `macOS Release` は validation-only である。tag が release branch 上にのみ存在し、workflow を `main` から dispatch する場合は、`public_release_branch=release/YYYY.M.D` を設定する + - 実際の private mac publish には、成功した private mac `preflight_run_id` と `validate_run_id` が必要 + - 実際の publish path は、準備済み artifact を再 build せずに promote する +- `YYYY.M.D-N` のような stable correction release では、post-publish verifier は `YYYY.M.D` から `YYYY.M.D-N` への同じ temp-prefix upgrade path も check し、release correction が古い global install を base stable payload のまま静かに残さないようにする - npm release preflight は、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` payload の両方が含まれていない限り fail closed するため、空の browser dashboard を再び出荷しない -- Post-publish verification は、公開済み plugin entrypoint と package metadata がインストール済み registry layout に存在することも確認する。plugin runtime payload が欠落したリリースは postpublish verifier に失敗し、`latest` に昇格できない。 -- `pnpm test:install:smoke` は candidate update tarball に対して npm pack `unpackedSize` budget も強制するため、installer e2e は accidental pack bloat を release publish path の前に検出する -- リリース作業で CI planning、extension timing manifest、または extension test matrix に触れた場合は、承認前に `.github/workflows/plugin-prerelease.yml` から planner-owned の `plugin-prerelease-extension-shard` matrix outputs を再生成してレビューし、リリースノートが古い CI layout を説明しないようにする -- 安定版 macOS リリース readiness には updater surfaces も含まれる: - - GitHub release には packaged `.zip`、`.dmg`、`.dSYM.zip` が最終的に含まれている必要がある - - publish 後、`main` の `appcast.xml` は新しい安定版 zip を指している必要がある - - packaged app は non-debug bundle id、空でない Sparkle feed URL、そのリリースバージョンの canonical Sparkle build floor 以上の `CFBundleVersion` を維持している必要がある +- Post-publish verification は、publish 済み Plugin entrypoint と package metadata が installed registry layout に存在することも check する。Plugin runtime payload が欠落したまま出荷される release は postpublish verifier に失敗し、`latest` に promote できない。 +- `pnpm test:install:smoke` は candidate update tarball に対して npm pack `unpackedSize` budget も強制するため、installer e2e は release publish path の前に偶発的な pack bloat を検出できる +- release 作業で CI planning、extension timing manifest、または extension test matrix に触れた場合は、承認前に `.github/workflows/plugin-prerelease.yml` から planner-owned の `plugin-prerelease-extension-shard` matrix output を regenerate して review し、release note が古い CI layout を説明しないようにする +- Stable macOS release readiness には updater surface も含まれる: + - GitHub release には最終的に package された `.zip`、`.dmg`、`.dSYM.zip` が含まれる必要がある + - publish 後、`main` 上の `appcast.xml` は新しい stable zip を指す必要がある + - package された app は、non-debug bundle id、空でない Sparkle feed URL、その release version の canonical Sparkle build floor 以上の `CFBundleVersion` を維持する必要がある ## リリーステストボックス -`Full Release Validation` は、operator がすべてのプレリリーステストを単一のエントリポイントから開始する方法である。動きの速いブランチで pinned commit proof を取得するには、helper を使ってすべての子ワークフローを対象 SHA に固定された一時ブランチから実行する: +`Full Release Validation` は、operator がすべてのリリース前テストを単一のエントリポイントから起動する方法である。動きの速い branch 上で pinned commit proof が必要な場合は、すべての child workflow が target SHA に固定された temporary branch から実行されるように helper を使う: ```bash pnpm ci:full-release --sha ``` -この helper は `release-ci/-...` を push し、そのブランチから `ref=` で `Full Release Validation` をディスパッチし、すべての子ワークフローの `headSha` が対象と一致することを検証してから、一時ブランチを削除する。これにより、誤って新しい `main` の子 run を証明してしまうことを防ぐ。 +この helper は `release-ci/-...` を push し、その branch から `ref=` で `Full Release Validation` を dispatch し、すべての child workflow の `headSha` が target に一致することを検証した後、temporary branch を削除する。これにより、誤って新しい `main` child run を証明することを避けられる。 -リリースブランチまたはタグの検証では、信頼済みの `main` workflow ref から実行し、リリースブランチまたはタグを `ref` として渡す: +release branch または tag validation では、信頼済みの `main` workflow ref から実行し、release branch または tag を `ref` として渡す: ```bash gh workflow run full-release-validation.yml \ @@ -155,19 +185,25 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -このワークフローはターゲット ref を解決し、`target_ref=` 付きで手動 `CI` をディスパッチし、`OpenClaw Release Checks` をディスパッチし、パッケージ向けチェック用の親 `release-package-under-test` アーティファクトを準備し、`release_profile=full` かつ `rerun_group=all` の場合、または `npm_telegram_package_spec` が設定されている場合に、スタンドアロンのパッケージ Telegram E2E をディスパッチします。その後 `OpenClaw Release Checks` は、インストールスモーク、クロス OS リリースチェック、live/E2E Docker リリースパスのカバレッジ、Telegram パッケージ QA 付きの Package Acceptance、QA Lab パリティ、live Matrix、live Telegram に展開します。フル実行が許容されるのは、`Full Release Validation` のサマリーで `normal_ci` と `release_checks` が成功として表示される場合のみです。full/all モードでは、`npm_telegram` 子も成功している必要があります。full/all 以外では、公開済みの `npm_telegram_package_spec` が指定されていない限りスキップされます。最終の検証サマリーには各子実行の最も遅いジョブの表が含まれるため、リリースマネージャーはログをダウンロードせずに現在のクリティカルパスを確認できます。 -完全なステージマトリクス、正確なワークフロージョブ名、stable プロファイルと full プロファイルの違い、アーティファクト、重点的な再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation)を参照してください。 -子ワークフローは、ターゲット `ref` が古いリリースブランチやタグを指している場合でも、`Full Release Validation` を実行する信頼された ref、通常は `--ref main` からディスパッチされます。別個の Full Release Validation workflow-ref 入力はありません。ワークフロー実行 ref を選択することで、信頼されたハーネスを選択します。移動する `main` 上で正確なコミット証拠を得るために `--ref main -f ref=` を使用しないでください。生のコミット SHA はワークフローディスパッチ ref にできないため、`pnpm ci:full-release --sha ` を使用してピン留めされた一時ブランチを作成します。 +ワークフローはターゲット ref を解決し、手動 `CI` を +`target_ref=` 付きでディスパッチし、`OpenClaw Release Checks` をディスパッチし、パッケージ向けチェック用の親 `release-package-under-test` アーティファクトを準備し、`release_profile=full` かつ `rerun_group=all` の場合、または `npm_telegram_package_spec` が設定されている場合に、スタンドアロンのパッケージ Telegram E2E をディスパッチします。その後、`OpenClaw Release +Checks` は、インストールスモーク、クロス OS リリースチェック、ライブ/E2E Docker リリースパスカバレッジ、Telegram パッケージ QA 付き Package Acceptance、QA Lab パリティ、ライブ Matrix、ライブ Telegram に展開します。完全実行が許容されるのは、`Full Release Validation` +サマリーで `normal_ci` と `release_checks` が成功と表示されている場合だけです。full/all モードでは、`npm_telegram` 子ワークフローも成功している必要があります。full/all 以外では、公開済みの `npm_telegram_package_spec` が指定されていない限りスキップされます。最終 verifier サマリーには各子実行の最遅ジョブテーブルが含まれるため、リリースマネージャーはログをダウンロードせずに現在のクリティカルパスを確認できます。 +完全なステージマトリクス、正確なワークフロージョブ名、stable プロファイルと full プロファイルの違い、アーティファクト、集中的な再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation)を参照してください。 +子ワークフローは、`Full Release +Validation` を実行する信頼済み ref、通常は `--ref main` からディスパッチされます。これはターゲット `ref` が古いリリースブランチやタグを指している場合も同じです。Full Release Validation 用の別個の workflow-ref 入力はありません。ワークフロー実行 ref を選ぶことで、信頼済みハーネスを選択します。 +移動する `main` 上で正確なコミット証跡を得るために `--ref main -f ref=` を使用しないでください。生のコミット SHA は workflow dispatch ref にできないため、固定された一時ブランチを作成するには `pnpm ci:full-release --sha ` を使用します。 -live/provider の広さを選択するには `release_profile` を使用します。 +ライブ/プロバイダーの範囲を選択するには `release_profile` を使用します。 -- `minimum`: 最速のリリースクリティカルな OpenAI/core live と Docker パス -- `stable`: minimum に加えて、リリース承認用の stable provider/backend カバレッジ -- `full`: stable に加えて、広範な advisory provider/media カバレッジ +- `minimum`: 最速のリリースクリティカルな OpenAI/コアのライブおよび Docker パス +- `stable`: リリース承認向けに minimum に stable プロバイダー/バックエンドカバレッジを追加 +- `full`: stable に幅広い advisory プロバイダー/メディアカバレッジを追加 -`OpenClaw Release Checks` は、信頼されたワークフロー ref を使用してターゲット ref を `release-package-under-test` として一度だけ解決し、そのアーティファクトをリリースパス Docker チェックと Package Acceptance の両方で再利用します。これにより、すべてのパッケージ向けボックスが同じバイト列を使用し、パッケージビルドの繰り返しを避けられます。クロス OS OpenAI インストールスモークは、repo/org 変数が設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` を使用し、それ以外は `openai/gpt-5.4` を使用します。このレーンは、最も遅いデフォルトモデルのベンチマークではなく、パッケージインストール、オンボーディング、Gateway 起動、1 回の live agent ターンを証明するためです。より広範な live provider マトリクスは、引き続きモデル固有のカバレッジの場です。 +`OpenClaw Release Checks` は、信頼済みワークフロー ref を使用してターゲット ref を一度だけ `release-package-under-test` として解決し、そのアーティファクトをリリースパス Docker チェックと Package Acceptance の両方で再利用します。これにより、すべてのパッケージ向けボックスが同じバイト列を使用し、パッケージビルドの繰り返しを避けられます。 +クロス OS OpenAI インストールスモークは、repo/org 変数が設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` を使用し、そうでない場合は `openai/gpt-5.4` を使用します。このレーンは最も遅いデフォルトモデルをベンチマークするのではなく、パッケージインストール、オンボーディング、Gateway 起動、ライブエージェント 1 ターンを証明するものだからです。より広範なライブプロバイダーマトリクスは、引き続きモデル固有カバレッジの場所です。 -リリース段階に応じて、次のバリアントを使用します。 +リリース段階に応じて、これらのバリアントを使用します。 ```bash # Validate an unpublished release candidate branch. @@ -197,22 +233,23 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -重点修正後の最初の再実行として、フルの統合ワークフローを使用しないでください。1 つのボックスが失敗した場合は、次の証明に失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデル provider、または QA レーンを使用します。フルの統合ワークフローを再実行するのは、修正が共有リリースオーケストレーションを変更した場合、または以前の全ボックス証拠が古くなった場合のみにしてください。統合ワークフローの最終検証は、記録された子ワークフロー実行 ID を再チェックするため、子ワークフローが正常に再実行された後は、失敗した親ジョブ `Verify full validation` のみを再実行します。 +集中的な修正後の最初の再実行として、完全な包括ワークフローを使用しないでください。1 つのボックスが失敗した場合は、次の証跡として、失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデルプロバイダー、または QA レーンを使用します。完全な包括ワークフローを再度実行するのは、その修正が共有リリースオーケストレーションを変更した場合、または以前の全ボックス証跡を古くした場合だけです。包括ワークフローの最終 verifier は記録された子ワークフロー実行 ID を再チェックするため、子ワークフローの再実行が成功した後は、失敗した親ジョブ `Verify full validation` だけを再実行します。 -範囲を限定した復旧には、統合ワークフローに `rerun_group` を渡します。`all` は実際のリリース候補実行、`ci` は通常 CI 子のみ、`plugin-prerelease` はリリース専用 Plugin 子のみ、`release-checks` はすべてのリリースボックスを実行し、より狭いリリースグループは `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` です。重点的な `npm-telegram` 再実行には `npm_telegram_package_spec` が必要です。`release_profile=full` の full/all 実行では、release-checks パッケージアーティファクトを使用します。 +範囲を限定した復旧には、包括ワークフローに `rerun_group` を渡します。`all` は実際のリリース候補実行、`ci` は通常の CI 子ワークフローのみ、`plugin-prerelease` はリリース専用 Plugin 子ワークフローのみ、`release-checks` はすべてのリリースボックスを実行し、より狭いリリースグループは `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` です。 +集中的な `npm-telegram` 再実行には `npm_telegram_package_spec` が必要です。`release_profile=full` の full/all 実行では、release-checks パッケージアーティファクトを使用します。 ### Vitest -Vitest ボックスは手動 `CI` 子ワークフローです。手動 CI は意図的に changed スコープを迂回し、リリース候補に対して通常のテストグラフを強制します。Linux Node shard、バンドル Plugin shard、チャンネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Android、Control UI i18n が対象です。 +Vitest ボックスは手動 `CI` 子ワークフローです。手動 CI は意図的に変更スコープをバイパスし、リリース候補に対して通常のテストグラフを強制します。対象は、Linux Node シャード、バンドル Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、docs チェック、Python Skills、Windows、macOS、Android、Control UI i18n です。 -このボックスは、「ソースツリーが通常のフルテストスイートに合格したか」に答えるために使用します。これはリリースパスの製品検証と同じではありません。保持すべき証拠: +このボックスは「ソースツリーは通常のフルテストスイートを通過したか」に答えるために使用します。リリースパスのプロダクト検証とは同じではありません。保持する証跡: - ディスパッチされた `CI` 実行 URL を示す `Full Release Validation` サマリー -- 正確なターゲット SHA で green になった `CI` 実行 -- リグレッション調査時の CI ジョブからの失敗または低速 shard 名 +- 正確なターゲット SHA で緑の `CI` 実行 +- リグレッションを調査する際の CI ジョブからの失敗または低速シャード名 - 実行にパフォーマンス分析が必要な場合の `.artifacts/vitest-shard-timings.json` などの Vitest タイミングアーティファクト -リリースで決定論的な通常 CI が必要だが、Docker、QA Lab、live、クロス OS、またはパッケージボックスが不要な場合のみ、手動 CI を直接実行します。 +リリースで決定的な通常 CI は必要だが、Docker、QA Lab、ライブ、クロス OS、パッケージボックスが不要な場合のみ、手動 CI を直接実行します。 ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -220,51 +257,64 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker ボックスは、`openclaw-live-and-e2e-checks-reusable.yml` とリリースモードの `install-smoke` ワークフローを通じて `OpenClaw Release Checks` 内にあります。ソースレベルのテストだけでなく、パッケージ化された Docker 環境を通じてリリース候補を検証します。 +Docker ボックスは、`openclaw-live-and-e2e-checks-reusable.yml` を通じて `OpenClaw Release Checks` 内にあり、さらにリリースモードの `install-smoke` ワークフローにもあります。これはソースレベルのテストだけではなく、パッケージ化された Docker 環境を通じてリリース候補を検証します。 -リリース Docker カバレッジには次が含まれます。 +リリース Docker カバレッジには以下が含まれます。 -- 低速な Bun グローバルインストールスモークを有効にした完全なインストールスモーク -- ターゲット SHA による root Dockerfile スモークイメージの準備/再利用。QR、root/Gateway、installer/Bun スモークジョブは個別の install-smoke shard として実行 +- 低速な Bun グローバルインストールスモークを有効にしたフルインストールスモーク +- ターゲット SHA ごとのルート Dockerfile スモークイメージ準備/再利用。QR、root/gateway、installer/Bun スモークジョブは個別の install-smoke シャードとして実行 - リポジトリ E2E レーン -- リリースパス Docker チャンク: `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h` +- リリースパス Docker チャンク: `core`、`package-update-openai`、 + `package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、 + `plugins-runtime-services`、 + `plugins-runtime-install-a`、`plugins-runtime-install-b`、 + `plugins-runtime-install-c`、`plugins-runtime-install-d`、 + `plugins-runtime-install-e`、`plugins-runtime-install-f`、 + `plugins-runtime-install-g`、`plugins-runtime-install-h` - 要求された場合の `plugins-runtime-services` チャンク内の OpenWebUI カバレッジ -- 分割されたバンドル Plugin install/uninstall レーン `bundled-plugin-install-uninstall-0` から `bundled-plugin-install-uninstall-23` -- リリースチェックに live スイートが含まれる場合の live/E2E provider スイートと Docker live モデルカバレッジ +- 分割されたバンドル Plugin インストール/アンインストールレーン + `bundled-plugin-install-uninstall-0` から + `bundled-plugin-install-uninstall-23` +- リリースチェックにライブスイートが含まれる場合のライブ/E2E プロバイダースイートと Docker ライブモデルカバレッジ -再実行前に Docker アーティファクトを使用します。リリースパススケジューラーは、レーンログ、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。重点復旧には、すべてのリリースチャンクを再実行するのではなく、再利用可能な live/E2E ワークフローで `docker_lanes=` を使用します。生成される再実行コマンドには、利用可能な場合、以前の `package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、失敗したレーンは同じ tarball と GHCR イメージを再利用できます。 +再実行の前に Docker アーティファクトを使用します。リリースパススケジューラーは、レーンログ、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。集中的な復旧には、すべてのリリースチャンクを再実行する代わりに、再利用可能な live/E2E ワークフローで `docker_lanes=` を使用します。生成された再実行コマンドには、利用可能な場合、以前の `package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、失敗したレーンは同じ tarball と GHCR イメージを再利用できます。 ### QA Lab -QA Lab ボックスも `OpenClaw Release Checks` の一部です。これは agentic behavior とチャンネルレベルのリリースゲートであり、Vitest や Docker パッケージ機構とは別です。 +QA Lab ボックスも `OpenClaw Release Checks` の一部です。これは agentic な挙動とチャネルレベルのリリースゲートであり、Vitest や Docker パッケージ機構とは別です。 -リリース QA Lab カバレッジには次が含まれます。 +リリース QA Lab カバレッジには以下が含まれます。 -- agentic parity pack を使用し、OpenAI candidate レーンを Opus 4.6 ベースラインと比較する mock parity レーン -- `qa-live-shared` 環境を使用する高速 live Matrix QA プロファイル -- Convex CI credential lease を使用する live Telegram QA レーン -- リリース telemetry に明示的なローカル証明が必要な場合の `pnpm qa:otel:smoke` +- agentic parity pack を使用して OpenAI 候補レーンを Opus 4.6 ベースラインと比較する mock パリティレーン +- `qa-live-shared` 環境を使用する高速ライブ Matrix QA プロファイル +- Convex CI credential lease を使用するライブ Telegram QA レーン +- リリーステレメトリに明示的なローカル証跡が必要な場合の `pnpm qa:otel:smoke` -このボックスは、「リリースが QA シナリオと live チャンネルフローで正しく動作するか」に答えるために使用します。リリース承認時には、parity、Matrix、Telegram レーンのアーティファクト URL を保持します。完全な Matrix カバレッジは、デフォルトのリリースクリティカルレーンではなく、手動の sharded QA-Lab 実行として引き続き利用できます。 +このボックスは「リリースは QA シナリオとライブチャネルフローで正しく動作するか」に答えるために使用します。リリースを承認する際は、パリティ、Matrix、Telegram レーンのアーティファクト URL を保持します。完全な Matrix カバレッジは、デフォルトのリリースクリティカルレーンではなく、手動のシャード化された QA-Lab 実行として引き続き利用できます。 ### パッケージ -パッケージボックスは、インストール可能な製品ゲートです。これは `Package Acceptance` とリゾルバー `scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。リゾルバーは候補を Docker E2E が消費する `package-under-test` tarball に正規化し、パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、ワークフローハーネス ref をパッケージソース ref から分離したままにします。 +パッケージボックスは、インストール可能プロダクトのゲートです。これは `Package Acceptance` とリゾルバー `scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。リゾルバーは候補を Docker E2E が消費する `package-under-test` tarball に正規化し、パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、ワークフローハーネス ref をパッケージソース ref とは別に保ちます。 サポートされる候補ソース: - `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な OpenClaw リリースバージョン -- `source=ref`: 選択された `workflow_ref` ハーネスで、信頼された `package_ref` ブランチ、タグ、または完全なコミット SHA を pack +- `source=ref`: 選択された `workflow_ref` ハーネスで、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパック - `source=url`: 必須の `package_sha256` 付きで HTTPS `.tgz` をダウンロード - `source=artifact`: 別の GitHub Actions 実行によってアップロードされた `.tgz` を再利用 -`OpenClaw Release Checks` は、準備済みリリースパッケージアーティファクトを使って Package Acceptance を `source=artifact`、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues`、`telegram_mode=mock-openai` で実行します。Package Acceptance は、同じ解決済み tarball に対して、migration、update、古い Plugin 依存関係クリーンアップ、offline Plugin fixtures、Plugin update、Telegram package QA を維持します。upgrade マトリクスは、`2026.4.23` から `latest` までのすべての stable npm 公開済みベースラインを対象にします。すでに出荷済みの候補には `source=npm` の Package Acceptance を使用し、公開前の SHA 裏付けのローカル npm tarball には `source=ref`/`source=artifact` を使用します。これは、以前は Parallels が必要だったパッケージ/update カバレッジの大半を置き換える GitHub ネイティブな手段です。クロス OS リリースチェックは、OS 固有のオンボーディング、installer、プラットフォーム動作のために引き続き重要ですが、パッケージ/update 製品検証では Package Acceptance を優先してください。 +`OpenClaw Release Checks` は、`source=artifact`、準備済みリリースパッケージアーティファクト、`suite_profile=custom`、 +`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、 +`published_upgrade_survivor_baselines=all-since-2026.4.23`、 +`published_upgrade_survivor_scenarios=reported-issues`、および +`telegram_mode=mock-openai` で Package Acceptance を実行します。Package Acceptance は、同じ解決済み tarball に対して、マイグレーション、更新、古い Plugin 依存関係のクリーンアップ、オフライン Plugin フィクスチャ、Plugin 更新、Telegram パッケージ QA を維持します。アップグレードマトリクスは、`2026.4.23` から `latest` までのすべての stable npm 公開済みベースラインをカバーします。すでに出荷済みの候補には `source=npm` で Package Acceptance を使用し、公開前の SHA 裏付けのあるローカル npm tarball には `source=ref`/`source=artifact` を使用します。これは、以前 Parallels を必要としていたパッケージ/更新カバレッジの大半に対する GitHub ネイティブな置き換えです。クロス OS リリースチェックは、OS 固有のオンボーディング、インストーラー、プラットフォーム挙動に引き続き重要ですが、パッケージ/更新のプロダクト検証では Package Acceptance を優先すべきです。 -update と Plugin 検証の正規チェックリストは、[update と Plugin のテスト](/ja-JP/help/testing-updates-plugins)です。Plugin install/update、doctor cleanup、または公開済みパッケージ migration の変更を、どのローカル、Docker、Package Acceptance、または release-check レーンで証明するかを決めるときに使用します。すべての stable `2026.4.23+` パッケージからの網羅的な公開済み update migration は、Full Release CI の一部ではなく、別個の手動 `Update Migration` ワークフローです。 +更新と Plugin 検証の正規チェックリストは[更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins)です。Plugin のインストール/更新、doctor クリーンアップ、または公開パッケージマイグレーション変更を証明するローカル、Docker、Package Acceptance、またはリリースチェックレーンを決める際に使用します。 +すべての stable `2026.4.23+` パッケージからの網羅的な公開済み更新マイグレーションは、Full Release CI の一部ではなく、別個の手動 `Update Migration` ワークフローです。 -レガシー package-acceptance の寛容さは、意図的に期間限定です。`2026.4.25` までのパッケージは、すでに npm に公開されたメタデータの欠落に対して互換性パスを使用できます。tarball にない private QA inventory entries、欠落した `gateway install --wrapper`、tarball 由来の git fixture にない patch files、永続化されていない `update.channel`、レガシー Plugin install-record locations、marketplace install-record persistence の欠落、`plugins update` 中の config metadata migration が該当します。公開済みの `2026.4.26` パッケージは、すでに出荷されたローカルビルドメタデータスタンプファイルについて警告する場合があります。それ以降のパッケージは、現代的なパッケージ契約を満たす必要があります。同じ欠落はリリース検証で失敗します。 +レガシー package-acceptance の緩和は、意図的に期限付きです。`2026.4.25` までのパッケージは、すでに npm に公開されたメタデータギャップについて互換パスを使用できます。対象は、tarball にない private QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャ内の欠落したパッチファイル、永続化されていない `update.channel`、レガシー Plugin インストールレコードの場所、マーケットプレイスインストールレコード永続化の欠落、`plugins update` 中の設定メタデータマイグレーションです。公開済みの `2026.4.26` パッケージは、すでに出荷されたローカルビルドメタデータスタンプファイルについて警告する場合があります。それ以降のパッケージは、現代的なパッケージ契約を満たす必要があります。同じギャップはリリース検証で失敗します。 -リリースの論点が実際にインストール可能なパッケージに関する場合は、より広範な Package Acceptance プロファイルを使用します。 +リリース上の問いが実際のインストール可能パッケージに関するものである場合は、より広範な Package Acceptance プロファイルを使用します。 ```bash gh workflow run package-acceptance.yml \ @@ -278,20 +328,24 @@ gh workflow run package-acceptance.yml \ 一般的なパッケージプロファイル: -- `smoke`: クイックなパッケージインストール/チャンネル/エージェント、Gateway ネットワーク、設定リロードのレーン -- `package`: live ClawHub なしのインストール/更新/Plugin パッケージ契約。これはリリースチェックのデフォルト -- `product`: `package` に加えて MCP チャンネル、cron/サブエージェントのクリーンアップ、OpenAI web検索、OpenWebUI +- `smoke`: パッケージのクイックインストール/チャネル/エージェント、Gateway ネットワーク、設定 + リロードのレーン +- `package`: ライブ ClawHub なしでのインストール/更新/Plugin パッケージ契約。これは release-check の + デフォルト +- `product`: `package` に加えて、MCP チャネル、cron/サブエージェントのクリーンアップ、OpenAI web + search、OpenWebUI - `full`: OpenWebUI を含む Docker リリースパスのチャンク -- `custom`: 焦点を絞った再実行用の正確な `docker_lanes` リスト +- `custom`: 集中的な再実行用の正確な `docker_lanes` リスト -パッケージ候補の Telegram 証明には、Package Acceptance で `telegram_mode=mock-openai` または +パッケージ候補の Telegram 証明では、Package Acceptance で `telegram_mode=mock-openai` または `telegram_mode=live-frontier` を有効にします。このワークフローは、解決済みの `package-under-test` tarball を Telegram レーンに渡します。スタンドアロンの -Telegram ワークフローは、公開後チェック用に公開済み npm 仕様を引き続き受け付けます。 +Telegram ワークフローは、公開後チェック用に公開済み npm spec も引き続き受け付けます。 -## リリース公開の自動化 +## リリース公開自動化 -`OpenClaw Release Publish` は通常の変更を伴う公開エントリーポイントです。リリースに必要な順序で、信頼済み公開者ワークフローをオーケストレーションします。 +`OpenClaw Release Publish` は通常の変更を伴う公開エントリポイントです。これは、 +リリースに必要な順序で trusted-publisher ワークフローをオーケストレーションします。 1. リリースタグをチェックアウトし、そのコミット SHA を解決します。 2. タグが `main` または `release/*` から到達可能であることを検証します。 @@ -320,7 +374,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -`latest` へ直接安定版を昇格する場合は明示的に指定します: +`latest` へ直接行う安定版昇格は明示的です。 ```bash gh workflow run openclaw-release-publish.yml \ @@ -330,59 +384,70 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=latest ``` -低レベルの `Plugin NPM Release` と `Plugin ClawHub Release` ワークフローは、焦点を絞った修復または再公開作業にのみ使用してください。選択した Plugin 修復では、`OpenClaw Release Publish` に `plugin_publish_scope=selected` と `plugins=@openclaw/name` を渡すか、OpenClaw パッケージを公開してはならない場合は子ワークフローを直接ディスパッチします。 +下位レベルの `Plugin NPM Release` と `Plugin ClawHub Release` ワークフローは、 +集中的な修復または再公開作業にのみ使用します。選択した Plugin の修復では、 +`plugin_publish_scope=selected` と `plugins=@openclaw/name` を +`OpenClaw Release Publish` に渡すか、OpenClaw パッケージを公開してはいけない場合は +子ワークフローを直接ディスパッチします。 ## NPM ワークフロー入力 -`OpenClaw NPM Release` は、次のオペレーター制御入力を受け付けます: +`OpenClaw NPM Release` は、オペレーターが制御する次の入力を受け付けます。 -- `tag`: 必須のリリースタグ。例: `v2026.4.2`、`v2026.4.2-1`、`v2026.4.2-beta.1`。`preflight_only=true` の場合は、検証専用プリフライト用に現在の完全な 40 文字のワークフローブランチコミット SHA も使用できます +- `tag`: `v2026.4.2`、`v2026.4.2-1`、または + `v2026.4.2-beta.1` のような必須のリリースタグ。`preflight_only=true` の場合は、 + 検証専用プリフライト用に現在の完全な 40 文字のワークフローブランチコミット SHA も使用できます - `preflight_only`: 検証/ビルド/パッケージのみの場合は `true`、実際の公開パスの場合は `false` -- `preflight_run_id`: 実際の公開パスで必須。ワークフローが成功したプリフライト実行から準備済み tarball を再利用するために使用します +- `preflight_run_id`: 実際の公開パスで必須。ワークフローが成功したプリフライト実行から準備済み tarball を再利用するために使います - `npm_dist_tag`: 公開パスの npm ターゲットタグ。デフォルトは `beta` -`OpenClaw Release Publish` は、次のオペレーター制御入力を受け付けます: +`OpenClaw Release Publish` は、オペレーターが制御する次の入力を受け付けます。 - `tag`: 必須のリリースタグ。すでに存在している必要があります -- `preflight_run_id`: 成功した `OpenClaw NPM Release` プリフライト実行 ID。`publish_openclaw_npm=true` の場合は必須 +- `preflight_run_id`: 成功した `OpenClaw NPM Release` プリフライト実行 id。 + `publish_openclaw_npm=true` の場合に必須です - `npm_dist_tag`: OpenClaw パッケージの npm ターゲットタグ -- `plugin_publish_scope`: デフォルトは `all-publishable`。焦点を絞った修復作業の場合のみ `selected` を使用します -- `plugins`: `plugin_publish_scope=selected` の場合のカンマ区切りの `@openclaw/*` パッケージ名 -- `publish_openclaw_npm`: デフォルトは `true`。ワークフローを Plugin のみの修復オーケストレーターとして使用する場合のみ `false` に設定します +- `plugin_publish_scope`: デフォルトは `all-publishable`。集中的な修復作業にのみ `selected` を使用します +- `plugins`: `plugin_publish_scope=selected` の場合の、カンマ区切りの `@openclaw/*` パッケージ名 +- `publish_openclaw_npm`: デフォルトは `true`。ワークフローを Plugin のみの修復オーケストレーターとして使用する場合にのみ `false` を設定します -`OpenClaw Release Checks` は、次のオペレーター制御入力を受け付けます: +`OpenClaw Release Checks` は、オペレーターが制御する次の入力を受け付けます。 -- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを伴うチェックでは、解決済みコミットが OpenClaw ブランチまたはリリースタグから到達可能である必要があります。 +- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを伴うチェックでは、 + 解決済みコミットが OpenClaw ブランチまたはリリースタグから到達可能である必要があります。 ルール: -- 安定版タグと修正タグは `beta` または `latest` のどちらにも公開できます -- ベータのプレリリースタグは `beta` にのみ公開できます +- 安定版タグと修正タグは `beta` または `latest` のいずれかへ公開できます +- ベータプレリリースタグは `beta` にのみ公開できます - `OpenClaw NPM Release` では、完全なコミット SHA 入力は `preflight_only=true` の場合にのみ許可されます - `OpenClaw Release Checks` と `Full Release Validation` は常に検証専用です -- 実際の公開パスでは、プリフライト時に使用したものと同じ `npm_dist_tag` を使用する必要があります。ワークフローは公開を続行する前にそのメタデータを検証します +- 実際の公開パスでは、プリフライト中に使用したものと同じ `npm_dist_tag` を使う必要があります。 + ワークフローは、公開前にそのメタデータが継続していることを検証します ## 安定版 npm リリース手順 安定版 npm リリースを切る場合: 1. `preflight_only=true` で `OpenClaw NPM Release` を実行します - - タグが存在する前は、プリフライトワークフローの検証専用ドライランに現在の完全なワークフローブランチコミット SHA を使用できます -2. 通常のベータ優先フローでは `npm_dist_tag=beta` を選択し、意図的に直接安定版を公開したい場合のみ `latest` を選択します -3. 1 つの手動ワークフローから通常の CI に加えて live プロンプトキャッシュ、Docker、QA Lab、Matrix、Telegram のカバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全なコミット SHA で `Full Release Validation` を実行します -4. 意図的に決定的な通常のテストグラフだけが必要な場合は、代わりにリリース ref で手動の `CI` ワークフローを実行します + - タグが存在する前は、プリフライトワークフローの検証専用ドライランとして、現在の完全なワークフローブランチコミット SHA を使用できます +2. 通常の beta-first フローでは `npm_dist_tag=beta` を選択します。直接の安定版公開を意図している場合にのみ `latest` を選択します +3. 1 つの手動ワークフローから通常の CI に加えて、ライブプロンプトキャッシュ、Docker、QA Lab、Matrix、Telegram のカバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全なコミット SHA で `Full Release Validation` を実行します +4. 決定的な通常テストグラフだけが必要な場合は、代わりにリリース ref で手動の `CI` ワークフローを実行します 5. 成功した `preflight_run_id` を保存します -6. 同じ `tag`、同じ `npm_dist_tag`、保存済みの `preflight_run_id` で `OpenClaw Release Publish` を実行します。OpenClaw npm パッケージを昇格する前に、外部化された Plugin を npm と ClawHub に公開します -7. リリースが `beta` に着地した場合は、非公開の `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` ワークフローを使用して、その安定版を `beta` から `latest` へ昇格します -8. リリースを意図的に `latest` に直接公開し、`beta` も同じ安定版ビルドをすぐに指す必要がある場合は、同じ非公開ワークフローを使用して両方の dist-tag を安定版に向けるか、スケジュールされた自己修復同期で後から `beta` を移動させます +6. 同じ `tag`、同じ `npm_dist_tag`、保存済みの `preflight_run_id` で `OpenClaw Release Publish` を実行します。これは OpenClaw npm パッケージを昇格する前に、外部化された Plugin を npm と ClawHub に公開します +7. リリースが `beta` に着地した場合は、非公開の + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + ワークフローを使用して、その安定版を `beta` から `latest` へ昇格します +8. リリースを意図的に直接 `latest` へ公開し、`beta` もすぐに同じ安定版ビルドを指すべき場合は、同じ非公開ワークフローを使用して両方の dist-tag を安定版に向けるか、スケジュールされた自己修復同期によって後で `beta` が移動するようにします -dist-tag の変更は、引き続き `NPM_TOKEN` を必要とするため、セキュリティ上の理由で非公開リポジトリに置かれています。一方、公開リポジトリは OIDC のみの公開を維持します。 +dist-tag の変更は、引き続き `NPM_TOKEN` を必要とするため、セキュリティ上の理由で非公開リポジトリにあります。一方、公開リポジトリは OIDC のみの公開を維持します。 -これにより、直接公開パスとベータ優先の昇格パスの両方が文書化され、オペレーターから見える状態になります。 +これにより、直接公開パスと beta-first 昇格パスの両方が文書化され、オペレーターから見える状態になります。 -メンテナーがローカル npm 認証へフォールバックする必要がある場合は、1Password CLI (`op`) コマンドを専用の tmux セッション内でのみ実行してください。メインのエージェントシェルから `op` を直接呼び出さないでください。tmux 内に閉じ込めることで、プロンプト、アラート、OTP 処理を観察可能にし、ホストアラートの繰り返しを防げます。 +メンテナーがローカル npm 認証にフォールバックする必要がある場合は、1Password CLI（`op`）コマンドを専用の tmux セッション内でのみ実行します。メインエージェントシェルから `op` を直接呼び出さないでください。tmux 内に保つことで、プロンプト、アラート、OTP 処理を観測可能にし、ホストアラートの繰り返しを防げます。 -## 公開リファレンス +## 公開参照 - [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml) - [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml) @@ -394,10 +459,10 @@ dist-tag の変更は、引き続き `NPM_TOKEN` を必要とするため、セ - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -メンテナーは、実際のランブックとして非公開リリースドキュメント +メンテナーは、実際のランブックには非公開のリリースドキュメント [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) を使用します。 ## 関連 -- [リリースチャンネル](/ja-JP/install/development-channels) +- [リリースチャネル](/ja-JP/install/development-channels) diff --git a/docs/ja-JP/tools/subagents.md b/docs/ja-JP/tools/subagents.md index 7d7d32533..0f3392ecd 100644 --- a/docs/ja-JP/tools/subagents.md +++ b/docs/ja-JP/tools/subagents.md @@ -1,48 +1,40 @@ --- read_when: - エージェント経由でバックグラウンド作業または並列作業を行いたい場合 - - sessions_spawn またはサブエージェントツールのポリシーを変更しています + - sessions_spawn またはサブエージェントツールポリシーを変更しています - スレッドに紐づくサブエージェントセッションを実装またはトラブルシューティングしている sidebarTitle: Sub-agents -summary: 依頼者のチャットへ結果を通知する、隔離されたバックグラウンドエージェント実行を起動する +summary: 結果を依頼者のチャットへ通知する、分離されたバックグラウンドエージェント実行を起動します title: サブエージェント x-i18n: - generated_at: "2026-05-04T05:03:09Z" + generated_at: "2026-05-04T07:04:34Z" model: gpt-5.5 provider: openai - source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37 + source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8 source_path: tools/subagents.md workflow: 16 --- サブエージェントは、既存のエージェント実行から生成されるバックグラウンドのエージェント実行です。 -各サブエージェントは独自のセッション (`agent::subagent:`) で実行され、 -完了すると、その結果をリクエスト元のチャット -チャンネルに**通知**します。各サブエージェント実行は +それらは独自のセッション（`agent::subagent:`）で実行され、 +完了すると、その結果をリクエスト元のチャットチャネルへ**通知**します。 +各サブエージェント実行は [バックグラウンドタスク](/ja-JP/automation/tasks)として追跡されます。 -主な目的: +主な目標: -- メイン実行をブロックせずに「調査 / 長時間タスク / 遅いツール」の作業を並列化する。 -- サブエージェントをデフォルトで分離しておく（セッション分離 + 任意のサンドボックス化）。 -- ツール面を誤用しにくく保つ: サブエージェントにはデフォルトでセッションツールを与えない。 +- メイン実行をブロックせずに、「調査 / 長時間タスク / 遅いツール」の作業を並列化する。 +- サブエージェントをデフォルトで分離したままにする（セッション分離 + 任意のサンドボックス化）。 +- ツール面を誤用しにくく保つ: サブエージェントはデフォルトではセッションツールを取得しない。 - オーケストレーターパターン向けに、設定可能なネスト深度をサポートする。 -**コストに関する注記:** 各サブエージェントはデフォルトで独自のコンテキストとトークン使用量を持ちます。 -重いタスクや反復的なタスクでは、サブエージェントに安価なモデルを設定し、 -メインエージェントは高品質なモデルのままにしてください。 -`agents.defaults.subagents.model` またはエージェントごとの上書きで設定します。子が - リクエスト元の現在のトランスクリプトを本当に必要とする場合、その生成に限って - `context: "fork"` を要求できます。スレッドに紐付いたサブエージェントセッションは、 - 現在の会話をフォローアップスレッドへ分岐するため、デフォルトで - `context: "fork"` になります。 +**コストに関する注意:** 各サブエージェントは、デフォルトで独自のコンテキストとトークン使用量を持ちます。重いタスクや反復的なタスクでは、サブエージェントにより安価なモデルを設定し、メインエージェントは高品質なモデルのままにしてください。`agents.defaults.subagents.model` またはエージェントごとの上書きで設定します。子がリクエスト元の現在のトランスクリプトを本当に必要とする場合、エージェントはその 1 回の生成で `context: "fork"` をリクエストできます。スレッドに紐づくサブエージェントセッションは、現在の会話をフォローアップスレッドへ分岐するため、デフォルトで `context: "fork"` になります。 ## スラッシュコマンド -**現在の -セッション**のサブエージェント実行を確認または制御するには、`/subagents` を使用します。 +**現在のセッション**のサブエージェント実行を確認または制御するには、`/subagents` を使用します。 ```text /subagents list @@ -54,17 +46,13 @@ x-i18n: /subagents spawn [--model ] [--thinking ] ``` -現在のリクエスト元セッションのアクティブな実行を誘導するには、トップレベルの [`/steer `](/ja-JP/tools/steer) を使用します。対象が子の実行である場合は、`/subagents steer ` を使用します。 +現在のリクエスト元セッションのアクティブな実行を誘導するには、トップレベルの [`/steer `](/ja-JP/tools/steer) を使用します。対象が子実行の場合は、`/subagents steer ` を使用します。 -`/subagents info` は実行メタデータ（ステータス、タイムスタンプ、セッション id、 -トランスクリプトパス、クリーンアップ）を表示します。境界付きで -安全性フィルター済みの呼び出しビューには `sessions_history` を使用し、 -未加工の完全なトランスクリプトが必要な場合は、ディスク上のトランスクリプトパスを確認します。 +`/subagents info` は実行メタデータ（ステータス、タイムスタンプ、セッション ID、トランスクリプトパス、クリーンアップ）を表示します。境界付きで安全性フィルター済みの想起ビューには `sessions_history` を使用し、生の完全なトランスクリプトが必要な場合はディスク上のトランスクリプトパスを確認してください。 -### スレッド紐付け制御 +### スレッド紐づけ制御 -これらのコマンドは、永続的なスレッド紐付けをサポートするチャンネルで機能します。 -下記の[スレッドをサポートするチャンネル](#thread-supporting-channels)を参照してください。 +これらのコマンドは、永続的なスレッド紐づけをサポートするチャネルで機能します。下の[スレッド対応チャネル](#thread-supporting-channels)を参照してください。 ```text /focus @@ -74,76 +62,67 @@ x-i18n: /session max-age ``` -### 生成動作 +### 生成時の動作 -`/subagents spawn` は、内部リレーではなくユーザーコマンドとしてバックグラウンドサブエージェントを開始し、 -実行が完了すると、リクエスト元チャットへ最終的な完了更新を 1 件送信します。 +`/subagents spawn` は、バックグラウンドのサブエージェントを（内部リレーではなく）ユーザーコマンドとして開始し、実行が完了したときにリクエスト元チャットへ最後の完了更新を 1 回送信します。 - - - 生成コマンドは非ブロッキングで、実行 id を即座に返します。 - - 完了時に、サブエージェントはリクエスト元チャットチャンネルへ要約/結果メッセージを通知します。 - - 完了はプッシュ型です。生成後は、完了を待つためだけに `/subagents list`、`sessions_list`、`sessions_history` をループでポーリングしないでください。デバッグや介入のために必要な場合のみ、オンデマンドでステータスを確認します。 - - 完了時に、OpenClaw は通知のクリーンアップフローが続く前に、そのサブエージェントセッションが開いた追跡対象のブラウザータブ/プロセスをベストエフォートで閉じます。 + + - spawn コマンドは非ブロッキングで、実行 ID を即座に返します。 + - 完了時に、サブエージェントは要約/結果メッセージをリクエスト元のチャットチャネルへ通知します。 + - 完了はプッシュベースです。生成後は、完了を待つためだけに `/subagents list`、`sessions_list`、`sessions_history` をループでポーリングしないでください。ステータス確認は、デバッグや介入が必要な場合にオンデマンドでのみ行ってください。 + - 完了時に、OpenClaw は通知クリーンアップフローが続行される前に、そのサブエージェントセッションが開いた追跡対象のブラウザータブ/プロセスをベストエフォートで閉じます。 - - - OpenClaw はまず、安定した冪等性キーで直接 `agent` 配信を試みます。 - - 直接配信に失敗した場合、キュールーティングへフォールバックします。 - - キュールーティングもまだ利用できない場合、最終的に諦める前に、短い指数バックオフで通知を再試行します。 - - 完了配信は、解決済みのリクエスト元ルートを保持します。利用可能な場合は、スレッドに紐付いた完了ルートまたは会話に紐付いた完了ルートが優先されます。完了元がチャンネルのみを提供する場合、OpenClaw はリクエスト元セッションの解決済みルート（`lastChannel` / `lastTo` / `lastAccountId`）から不足している対象/アカウントを補完し、直接配信が引き続き機能するようにします。 + + - OpenClaw はまず、安定した冪等性キーを使って直接 `agent` 配信を試行します。 + - リクエスト元エージェントの完了ターンが失敗する、可視出力を生成しない、またはキャプチャされた子の結果の明らかに不完全な接頭部分を返す場合、OpenClaw はキャプチャされた子の結果から直接完了配信するフォールバックを行います。 + - 直接配信を使用できない場合は、キュールーティングへフォールバックします。 + - キュールーティングもまだ利用できない場合、最終的に諦める前に、通知は短い指数バックオフで再試行されます。 + - 完了配信は、解決済みのリクエスト元ルートを維持します。スレッド紐づけまたは会話紐づけの完了ルートが利用可能な場合はそれらが優先されます。完了の起点がチャネルしか提供しない場合、OpenClaw はリクエスト元セッションの解決済みルート（`lastChannel` / `lastTo` / `lastAccountId`）から不足している対象/アカウントを補完し、直接配信が引き続き機能するようにします。 - - リクエスト元セッションへの完了引き渡しは、実行時に生成される - 内部コンテキスト（ユーザーが作成したテキストではありません）で、次を含みます。 + + リクエスト元セッションへの完了ハンドオフは、ランタイム生成の内部コンテキスト（ユーザーが作成したテキストではありません）であり、以下を含みます。 - - `Result` — 最新の可視 `assistant` 返信テキスト。それがない場合は、サニタイズ済みの最新ツール/ツール結果テキスト。終端で失敗した実行は、取得済みの返信テキストを再利用しません。 + - `Result` — 最新の可視 `assistant` 返信テキスト。なければ、サニタイズ済みの最新 tool/toolResult テキスト。終了済みの失敗実行では、キャプチャされた返信テキストは再利用されません。 - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`。 - - コンパクトな実行時/トークン統計。 - - リクエスト元エージェントに、未加工の内部メタデータを転送せず、通常のアシスタントの声で書き直すよう伝える配信指示。 + - コンパクトなランタイム/トークン統計。 + - リクエスト元エージェントに、通常のアシスタントの声で書き直す（生の内部メタデータを転送しない）よう指示する配信指示。 - + - `--model` と `--thinking` は、その特定の実行のデフォルトを上書きします。 - - 完了後に詳細と出力を確認するには、`info`/`log` を使用します。 - - `/subagents spawn` はワンショットモード（`mode: "run"`）です。永続的なスレッド紐付きセッションには、`thread: true` と `mode: "session"` を指定して `sessions_spawn` を使用します。 - - ACP ハーネスセッション（Claude Code、Gemini CLI、OpenCode、または明示的な Codex ACP/acpx）では、ツールがそのランタイムを公開している場合に `runtime: "acp"` を指定して `sessions_spawn` を使用します。完了やエージェント間ループをデバッグするときは、[ACP 配信モデル](/ja-JP/tools/acp-agents#delivery-model)を参照してください。`codex` plugin が有効な場合、Codex のチャット/スレッド制御では、ユーザーが ACP/acpx を明示的に求めない限り、ACP より `/codex ...` を優先してください。 - - OpenClaw は、ACP が有効で、リクエスト元がサンドボックス化されておらず、`acpx` などのバックエンド plugin が読み込まれるまで、`runtime: "acp"` を隠します。`runtime: "acp"` は、外部 ACP ハーネス id、または `runtime.type="acp"` を持つ `agents.list[]` エントリを想定します。`agents_list` の通常の OpenClaw 設定エージェントには、デフォルトのサブエージェントランタイムを使用してください。 + - 完了後に詳細と出力を調べるには `info`/`log` を使用します。 + - `/subagents spawn` はワンショットモード（`mode: "run"`）です。永続的なスレッド紐付けセッションには、`thread: true` と `mode: "session"` を指定して `sessions_spawn` を使用します。 + - ACP ハーネスセッション（Claude Code、Gemini CLI、OpenCode、または明示的な Codex ACP/acpx）では、ツールがそのランタイムを通知している場合に `runtime: "acp"` を指定して `sessions_spawn` を使用します。完了やエージェント間ループをデバッグする場合は、[ACP 配信モデル](/ja-JP/tools/acp-agents#delivery-model) を参照してください。`codex` plugin が有効な場合、ユーザーが明示的に ACP/acpx を求めない限り、Codex のチャット/スレッド制御では ACP より `/codex ...` を優先してください。 + - OpenClaw は、ACP が有効で、リクエスターがサンドボックス化されておらず、`acpx` などのバックエンド plugin が読み込まれるまで、`runtime: "acp"` を非表示にします。`runtime: "acp"` は外部 ACP ハーネス ID、または `runtime.type="acp"` を持つ `agents.list[]` エントリを想定します。`agents_list` の通常の OpenClaw 設定エージェントには、デフォルトのサブエージェントランタイムを使用します。 ## コンテキストモード -ネイティブサブエージェントは、呼び出し元が現在のトランスクリプトのフォークを明示的に要求しない限り、分離状態で開始します。 +ネイティブサブエージェントは、呼び出し元が現在のトランスクリプトのフォークを明示的に要求しない限り、分離された状態で開始します。 | モード | 使用する場面 | 動作 | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `isolated` | 新規調査、独立した実装、遅いツール作業、またはタスク本文で説明できるあらゆる作業 | クリーンな子トランスクリプトを作成します。これがデフォルトで、トークン使用量を低く保ちます。 | -| `fork` | 現在の会話、以前のツール結果、またはリクエスト元トランスクリプトにすでに存在する微妙な指示に依存する作業 | 子の開始前に、リクエスト元トランスクリプトを子セッションへ分岐します。 | +| `isolated` | 新規調査、独立した実装、時間のかかるツール作業、またはタスク本文で説明できるもの | クリーンな子トランスクリプトを作成します。これがデフォルトで、トークン使用量を抑えます。 | +| `fork` | 現在の会話、以前のツール結果、またはリクエスターのトランスクリプトにすでに存在する細かな指示に依存する作業 | 子が開始する前に、リクエスターのトランスクリプトを子セッションへ分岐します。 | -`fork` は控えめに使用してください。これはコンテキストに敏感な委任のためのものであり、 -明確なタスクプロンプトを書くことの代替ではありません。 +`fork` は控えめに使用してください。これはコンテキスト依存の委任のためのものであり、明確なタスクプロンプトを書くことの代替ではありません。 ## ツール: `sessions_spawn` -グローバルな `subagent` レーンで `deliver: false` のサブエージェント実行を開始し、 -その後に通知ステップを実行して、通知返信をリクエスト元チャットチャンネルへ投稿します。 +グローバル `subagent` レーンで `deliver: false` のサブエージェント実行を開始し、その後アナウンス手順を実行して、アナウンスの返信をリクエスターのチャットチャネルに投稿します。 -利用可否は、呼び出し元の有効なツールポリシーに依存します。`coding` と -`full` プロファイルは、デフォルトで `sessions_spawn` を公開します。`messaging` プロファイルは -公開しません。作業を委任する必要があるエージェントには、`tools.alsoAllow: ["sessions_spawn", "sessions_yield", -"subagents"]` を追加するか、`tools.profile: "coding"` を使用します。 -チャンネル/グループ、プロバイダー、サンドボックス、エージェントごとの許可/拒否ポリシーは、 -プロファイル段階の後でもツールを削除できます。同じ -セッションから `/tools` を使用して、有効なツール一覧を確認してください。 +利用可否は、呼び出し元の実効ツールポリシーによって異なります。`coding` と `full` プロファイルは、デフォルトで `sessions_spawn` を公開します。`messaging` プロファイルは公開しません。作業を委任すべきエージェントには、`tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]` を追加するか、`tools.profile: "coding"` を使用します。チャネル/グループ、プロバイダー、サンドボックス、エージェントごとの許可/拒否ポリシーによって、プロファイル段階の後でもツールが削除されることがあります。同じセッションから `/tools` を使用して、実効ツール一覧を確認してください。 **デフォルト:** -- **モデル:** `agents.defaults.subagents.model`（またはエージェントごとの `agents.list[].subagents.model`）を設定しない限り、呼び出し元を継承します。明示的な `sessions_spawn.model` がある場合は、そちらが引き続き優先されます。 -- **Thinking:** `agents.defaults.subagents.thinking`（またはエージェントごとの `agents.list[].subagents.thinking`）を設定しない限り、呼び出し元を継承します。明示的な `sessions_spawn.thinking` がある場合は、そちらが引き続き優先されます。 -- **実行タイムアウト:** `sessions_spawn.runTimeoutSeconds` が省略された場合、設定されていれば OpenClaw は `agents.defaults.subagents.runTimeoutSeconds` を使用します。そうでなければ `0`（タイムアウトなし）へフォールバックします。 +- **モデル:** `agents.defaults.subagents.model`（またはエージェントごとの `agents.list[].subagents.model`）を設定しない限り、呼び出し元を継承します。明示的な `sessions_spawn.model` は引き続き優先されます。 +- **Thinking:** `agents.defaults.subagents.thinking`（またはエージェントごとの `agents.list[].subagents.thinking`）を設定しない限り、呼び出し元を継承します。明示的な `sessions_spawn.thinking` は引き続き優先されます。 +- **実行タイムアウト:** `sessions_spawn.runTimeoutSeconds` が省略された場合、OpenClaw は設定されていれば `agents.defaults.subagents.runTimeoutSeconds` を使用します。それ以外の場合は `0`（タイムアウトなし）にフォールバックします。 ### ツールパラメーター @@ -154,135 +133,128 @@ x-i18n: 任意の人間が読めるラベル。 - `subagents.allowAgents` で許可されている場合、別のエージェント id の下で生成します。 + `subagents.allowAgents` で許可されている場合、別のエージェント ID の下でスポーンします。 - `acp` は外部 ACP ハーネス（`claude`、`droid`、`gemini`、`opencode`、または明示的に要求された Codex ACP/acpx）、および `runtime.type` が `acp` の `agents.list[]` エントリ専用です。 + `acp` は、外部 ACP ハーネス（`claude`、`droid`、`gemini`、`opencode`、または明示的に要求された Codex ACP/acpx）と、`runtime.type` が `acp` の `agents.list[]` エントリ専用です。 - ACP のみ。`runtime: "acp"` の場合に既存の ACP ハーネスセッションを再開します。ネイティブサブエージェント生成では無視されます。 + ACP 専用。`runtime: "acp"` の場合に既存の ACP ハーネスセッションを再開します。ネイティブサブエージェントのスポーンでは無視されます。 - ACP のみ。`runtime: "acp"` の場合に ACP 実行出力を親セッションへストリーミングします。ネイティブサブエージェント生成では省略します。 + ACP 専用。`runtime: "acp"` の場合に ACP 実行出力を親セッションにストリーミングします。ネイティブサブエージェントのスポーンでは省略します。 - サブエージェントモデルを上書きします。無効な値はスキップされ、サブエージェントはデフォルトモデルで実行され、ツール結果に警告が表示されます。 + サブエージェントのモデルを上書きします。無効な値はスキップされ、サブエージェントはデフォルトモデルで実行され、ツール結果に警告が表示されます。 - サブエージェント実行の Thinking レベルを上書きします。 + サブエージェント実行の thinking レベルを上書きします。 - 設定されている場合は `agents.defaults.subagents.runTimeoutSeconds` がデフォルトになり、そうでなければ `0` になります。設定すると、サブエージェント実行は N 秒後に中止されます。 + 設定されている場合は `agents.defaults.subagents.runTimeoutSeconds` がデフォルトになり、それ以外の場合は `0` です。設定すると、サブエージェント実行は N 秒後に中止されます。 - `true` の場合、このサブエージェントセッションにチャンネルスレッド紐付けを要求します。 + `true` の場合、このサブエージェントセッションにチャネルスレッド紐付けを要求します。 - `thread: true` で `mode` が省略された場合、デフォルトは `session` になります。`mode: "session"` には `thread: true` が必要です。 + `thread: true` で `mode` が省略されている場合、デフォルトは `session` になります。`mode: "session"` には `thread: true` が必要です。 - `"delete"` は通知後すぐにアーカイブします（リネームによりトランスクリプトは保持します）。 + `"delete"` はアナウンス直後にアーカイブします（リネームによりトランスクリプトは保持されます）。 - `require` は、対象の子ランタイムがサンドボックス化されていない限り生成を拒否します。 + `require` は、対象の子ランタイムがサンドボックス化されていない限りスポーンを拒否します。 - `fork` は、リクエスト元の現在のトランスクリプトを子セッションへ分岐します。ネイティブサブエージェントのみ。スレッドに紐付いた生成はデフォルトで `fork`、非スレッド生成はデフォルトで `isolated` です。 + `fork` は、リクエスターの現在のトランスクリプトを子セッションへ分岐します。ネイティブサブエージェント専用です。スレッド紐付けスポーンはデフォルトで `fork`、非スレッドスポーンはデフォルトで `isolated` になります。 -`sessions_spawn` はチャンネル配信パラメーター（`target`、 -`channel`、`to`、`threadId`、`replyTo`、`transport`）を受け付けません。配信には、 -生成された実行から `message`/`sessions_send` を使用します。 +`sessions_spawn` は、チャネル配信パラメーター（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）を受け付けません。配信には、スポーンされた実行から `message`/`sessions_send` を使用します。 -## スレッド紐付きセッション +## スレッド紐付けセッション -チャンネルでスレッド紐付けが有効な場合、サブエージェントはスレッドに紐付いたままでいられるため、 -そのスレッド内のフォローアップユーザーメッセージは同じサブエージェントセッションへルーティングされ続けます。 +チャネルでスレッド紐付けが有効な場合、サブエージェントはスレッドに紐付いたままでいられるため、そのスレッド内の後続ユーザーメッセージは同じサブエージェントセッションにルーティングされ続けます。 -### スレッドをサポートするチャンネル +### スレッド対応チャネル -**Discord** は現在、唯一サポートされているチャンネルです。これは -永続的なスレッド紐付きサブエージェントセッション（`thread: true` を指定した `sessions_spawn`）、 -手動スレッド制御（`/focus`、`/unfocus`、`/agents`、 -`/session idle`、`/session max-age`）、およびアダプターキー -`channels.discord.threadBindings.enabled`、 -`channels.discord.threadBindings.idleHours`、 -`channels.discord.threadBindings.maxAgeHours`、および -`channels.discord.threadBindings.spawnSessions` をサポートします。 +**Discord** は現在唯一の対応チャネルです。永続的なスレッド紐付けサブエージェントセッション（`thread: true` を指定した `sessions_spawn`）、手動スレッド制御（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）、およびアダプターキー `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`、`channels.discord.threadBindings.spawnSessions` をサポートします。 ### クイックフロー - - `thread: true`（任意で `mode: "session"`）を指定して `sessions_spawn`。 + + `sessions_spawn` を `thread: true`（および任意で `mode: "session"`）付きで使用します。 - - OpenClaw は、そのセッション対象に対してアクティブなチャンネル内でスレッドを作成または紐付けます。 + + OpenClaw はアクティブなチャネル内で、そのセッションターゲットにスレッドを作成またはバインドします。 - - そのスレッド内の返信とフォローアップメッセージは、紐付いたセッションへルーティングされます。 + + そのスレッド内の返信とフォローアップメッセージは、バインドされたセッションにルーティングされます。 - - 非アクティブ時の自動フォーカス解除を確認/更新するには `/session idle` を使用し、 - ハード上限を制御するには `/session max-age` を使用します。 + + `/session idle` を使用して、非アクティブ時の自動アンフォーカスを確認/更新し、 + `/session max-age` でハード上限を制御します。 - - 手動で切り離すには `/unfocus` を使用します。 + + `/unfocus` を使用して手動で切り離します。 ### 手動制御 -| コマンド | 効果 | +| コマンド | 効果 | | ------------------ | --------------------------------------------------------------------- | -| `/focus ` | 現在のスレッドをサブエージェント/セッションターゲットにバインドする（または作成する） | -| `/unfocus` | 現在バインドされているスレッドのバインドを削除する | -| `/agents` | アクティブな実行とバインド状態（`thread:` または `unbound`）を一覧表示する | -| `/session idle` | アイドル時の自動アンフォーカスを確認/更新する（フォーカス中のバインド済みスレッドのみ） | -| `/session max-age` | ハード上限を確認/更新する（フォーカス中のバインド済みスレッドのみ） | +| `/focus ` | 現在のスレッドをサブエージェント/セッションターゲットにバインドします（または作成します） | +| `/unfocus` | 現在バインドされているスレッドのバインドを削除します | +| `/agents` | アクティブな実行とバインド状態（`thread:` または `unbound`）を一覧表示します | +| `/session idle` | アイドル時の自動アンフォーカスを確認/更新します（フォーカス中のバインド済みスレッドのみ） | +| `/session max-age` | ハード上限を確認/更新します（フォーカス中のバインド済みスレッドのみ） | ### 設定スイッチ - **グローバル既定値:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. -- **チャンネルのオーバーライドとスポーン時の自動バインドキー**はアダプター固有です。上記の[スレッド対応チャンネル](#thread-supporting-channels)を参照してください。 +- **チャネルのオーバーライドとスポーン時の自動バインドキー** はアダプター固有です。上記の [スレッド対応チャネル](#thread-supporting-channels) を参照してください。 -現在のアダプター詳細については、[設定リファレンス](/ja-JP/gateway/configuration-reference)と -[スラッシュコマンド](/ja-JP/tools/slash-commands)を参照してください。 +現在のアダプター詳細については、[設定リファレンス](/ja-JP/gateway/configuration-reference) と +[スラッシュコマンド](/ja-JP/tools/slash-commands) を参照してください。 ### 許可リスト - 明示的な `agentId`（`["*"]` は任意を許可）でターゲットにできるエージェント ID の一覧。既定値: リクエスト元エージェントのみ。一覧を設定し、リクエスト元が `agentId` で自身をスポーンできるようにもしたい場合は、リクエスト元 ID を一覧に含めます。 + 明示的な `agentId`（`["*"]` は任意を許可）でターゲットにできるエージェント ID の一覧です。既定値: リクエスターエージェントのみ。一覧を設定し、それでもリクエスターが `agentId` で自分自身をスポーンできるようにしたい場合は、リクエスター ID を一覧に含めます。 - リクエスト元エージェントが独自の `subagents.allowAgents` を設定していない場合に使われる、既定のターゲットエージェント許可リスト。 + リクエスターエージェントが独自の `subagents.allowAgents` を設定していない場合に使用される、既定のターゲットエージェント許可リストです。 - `agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制します）。エージェントごとのオーバーライド: `agents.list[].subagents.requireAgentId`。 + `agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制します）。エージェント単位のオーバーライド: `agents.list[].subagents.requireAgentId`. -リクエスト元セッションがサンドボックス化されている場合、`sessions_spawn` はサンドボックス外で実行されるターゲットを拒否します。 +リクエスターセッションがサンドボックス化されている場合、`sessions_spawn` は +サンドボックスなしで実行されるターゲットを拒否します。 ### 検出 -`sessions_spawn` で現在許可されているエージェント ID を確認するには、`agents_list` を使用します。レスポンスには、一覧に含まれる各エージェントの有効なモデルと埋め込みランタイムメタデータが含まれるため、呼び出し元は PI、Codex app-server、その他の設定済みネイティブランタイムを区別できます。 +`sessions_spawn` に現在許可されているエージェント ID を確認するには、`agents_list` を使用します。レスポンスには、一覧に含まれる各エージェントの有効な +モデルと埋め込みランタイムメタデータが含まれるため、呼び出し元は PI、Codex +アプリサーバー、その他の設定済みネイティブランタイムを区別できます。 ### 自動アーカイブ -- サブエージェントセッションは、`agents.defaults.subagents.archiveAfterMinutes`（既定値 `60`）後に自動的にアーカイブされます。 -- アーカイブでは `sessions.delete` を使用し、トランスクリプトの名前を `*.deleted.`（同じフォルダー）に変更します。 +- サブエージェントセッションは、`agents.defaults.subagents.archiveAfterMinutes`（既定値 `60`）の後に自動的にアーカイブされます。 +- アーカイブは `sessions.delete` を使用し、トランスクリプトを `*.deleted.` にリネームします（同じフォルダー）。 - `cleanup: "delete"` は announce の直後にアーカイブします（リネームによってトランスクリプトは保持されます）。 -- 自動アーカイブはベストエフォートです。Gateway が再起動すると、保留中のタイマーは失われます。 +- 自動アーカイブはベストエフォートです。Gateway が再起動すると保留中のタイマーは失われます。 - `runTimeoutSeconds` は自動アーカイブしません。実行を停止するだけです。セッションは自動アーカイブまで残ります。 -- 自動アーカイブは深さ 1 と深さ 2 のセッションに同じように適用されます。 -- ブラウザーのクリーンアップはアーカイブのクリーンアップとは別です。追跡されたブラウザータブ/プロセスは、トランスクリプト/セッションレコードを保持する場合でも、実行終了時にベストエフォートで閉じられます。 +- 自動アーカイブは depth-1 と depth-2 のセッションに同様に適用されます。 +- ブラウザーのクリーンアップはアーカイブのクリーンアップとは別です。追跡されているブラウザータブ/プロセスは、トランスクリプト/セッションレコードが保持される場合でも、実行終了時にベストエフォートで閉じられます。 ## ネストされたサブエージェント -既定では、サブエージェントは自身のサブエージェントをスポーンできません -（`maxSpawnDepth: 1`）。1 レベルのネストを有効にするには `maxSpawnDepth: 2` を設定します。これは**オーケストレーターパターン**です: メイン → オーケストレーターサブエージェント → +既定では、サブエージェントは自分自身のサブエージェントをスポーンできません +（`maxSpawnDepth: 1`）。1 レベルのネストを有効にするには `maxSpawnDepth: 2` を設定します — **オーケストレーターパターン**: メイン → オーケストレーターサブエージェント → ワーカーサブサブエージェント。 ```json5 @@ -302,131 +274,136 @@ x-i18n: ### 深さレベル -| 深さ | セッションキーの形状 | ロール | スポーン可能か | +| 深さ | セッションキーの形式 | 役割 | スポーン可能か | | ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | メインエージェント | 常に可能 | +| 0 | `agent::main` | メインエージェント | 常に可能 | | 1 | `agent::subagent:` | サブエージェント（深さ 2 が許可されている場合はオーケストレーター） | `maxSpawnDepth >= 2` の場合のみ | -| 2 | `agent::subagent::subagent:` | サブサブエージェント（リーフワーカー） | 不可 | +| 2 | `agent::subagent::subagent:` | サブサブエージェント（リーフワーカー） | 不可 | -### Announce チェーン +### announce チェーン -結果はチェーンをさかのぼって流れます。 +結果はチェーンを上方向に戻ります。 -1. 深さ 2 のワーカーが完了 → 親（深さ 1 のオーケストレーター）に announce します。 -2. 深さ 1 のオーケストレーターが announce を受け取り、結果を合成し、完了 → メインに announce します。 -3. メインエージェントが announce を受け取り、ユーザーに届けます。 +1. depth-2 ワーカーが完了 → 親（depth-1 オーケストレーター）に announce します。 +2. depth-1 オーケストレーターが announce を受け取り、結果を統合して完了 → メインに announce します。 +3. メインエージェントが announce を受け取り、ユーザーに配信します。 -各レベルは、直接の子からの announce のみを参照します。 +各レベルは、直接の子からの announce のみを確認します。 -**運用ガイダンス:** `sessions_list`、 -`sessions_history`、`/subagents list`、または `exec` の sleep コマンドを中心にポーリングループを構築するのではなく、子の作業を一度開始して完了イベントを待ちます。 -`sessions_list` と `/subagents list` は子セッション関係をライブ作業に集中させます。ライブの子は関連付けられたままになり、終了済みの子は短い recent ウィンドウの間だけ表示され、古いストアのみの子リンクは鮮度ウィンドウ後に無視されます。これにより、再起動後に古い `spawnedBy` / -`parentSessionKey` メタデータがゴーストの子を復活させることを防ぎます。最終回答を送信した後に子の完了イベントが届いた場合、正しいフォローアップは正確なサイレントトークン +**運用ガイダンス:** 子の作業は一度だけ開始し、`sessions_list`、 +`sessions_history`、`/subagents list`、または `exec` の sleep コマンドの周りにポーリングループを構築するのではなく、完了イベントを待ちます。 +`sessions_list` と `/subagents list` は、子セッションの関係を +ライブ作業に集中させます。ライブの子は接続されたまま、終了した子は短い最近のウィンドウ内で表示されたままになり、古いストア専用の子リンクは鮮度ウィンドウ後に無視されます。これにより、再起動後に古い `spawnedBy` / +`parentSessionKey` メタデータがゴーストの子を復活させることを防ぎます。最終回答を送信した後に子の完了イベントが到着した場合、正しいフォローアップは正確なサイレントトークン `NO_REPLY` / `no_reply` です。 -### 深さ別ツールポリシー +### 深さごとのツールポリシー -- ロールと制御スコープはスポーン時にセッションメタデータへ書き込まれます。これにより、フラットなセッションキーや復元されたセッションキーが誤ってオーケストレーター権限を取り戻すことを防ぎます。 +- 役割と制御スコープはスポーン時にセッションメタデータへ書き込まれます。これにより、フラットまたは復元されたセッションキーが誤ってオーケストレーター権限を取り戻すことを防ぎます。 - **深さ 1（`maxSpawnDepth >= 2` の場合のオーケストレーター）:** 子を管理できるように、`sessions_spawn`、`subagents`、`sessions_list`、`sessions_history` を取得します。その他のセッション/システムツールは拒否されたままです。 -- **深さ 1（`maxSpawnDepth == 1` の場合のリーフ）:** セッションツールなし（現在の既定の動作）。 -- **深さ 2（リーフワーカー）:** セッションツールなし。`sessions_spawn` は深さ 2 では常に拒否されます。それ以上の子はスポーンできません。 +- **深さ 1（`maxSpawnDepth == 1` の場合のリーフ）:** セッションツールはありません（現在の既定動作）。 +- **深さ 2（リーフワーカー）:** セッションツールはありません — `sessions_spawn` は深さ 2 では常に拒否されます。それ以上の子をスポーンすることはできません。 -### エージェントごとのスポーン上限 +### エージェント単位のスポーン上限 -各エージェントセッション（どの深さでも）は、同時に最大 `maxChildrenPerAgent` -（既定値 `5`）個のアクティブな子を持てます。これにより、単一のオーケストレーターからの制御不能なファンアウトを防ぎます。 +各エージェントセッション（任意の深さ）は、同時に最大 `maxChildrenPerAgent` +（既定値 `5`）個のアクティブな子を持つことができます。これにより、単一のオーケストレーターからの制御不能なファンアウトを防ぎます。 ### カスケード停止 -深さ 1 のオーケストレーターを停止すると、そのすべての深さ 2 の子も自動的に停止します。 +depth-1 オーケストレーターを停止すると、そのすべての depth-2 +の子が自動的に停止します。 -- メインチャットの `/stop` はすべての深さ 1 エージェントを停止し、その深さ 2 の子にカスケードします。 -- `/subagents kill ` は特定のサブエージェントを停止し、その子にカスケードします。 -- `/subagents kill all` はリクエスト元のすべてのサブエージェントを停止し、カスケードします。 +- メインチャットで `/stop` を実行すると、すべての depth-1 エージェントが停止し、その depth-2 の子へカスケードします。 +- `/subagents kill ` は特定のサブエージェントを停止し、その子へカスケードします。 +- `/subagents kill all` はリクエスターのすべてのサブエージェントを停止し、カスケードします。 ## 認証 -サブエージェントの認証は、セッションタイプではなく**エージェント ID**で解決されます。 +サブエージェントの認証はセッションタイプではなく **エージェント ID** によって解決されます。 - サブエージェントセッションキーは `agent::subagent:` です。 - 認証ストアはそのエージェントの `agentDir` から読み込まれます。 -- メインエージェントの認証プロファイルは**フォールバック**としてマージされます。競合時はエージェントプロファイルがメインプロファイルをオーバーライドします。 +- メインエージェントの認証プロファイルは **フォールバック** としてマージされます。競合時にはエージェントプロファイルがメインプロファイルを上書きします。 -マージは加算的なので、メインプロファイルは常にフォールバックとして利用できます。エージェントごとに完全に分離された認証は、まだサポートされていません。 +マージは加算的であるため、メインプロファイルは常にフォールバックとして利用できます。エージェント単位で完全に分離された認証はまだサポートされていません。 ## Announce -サブエージェントは announce ステップを通じて報告します。 +サブエージェントは announce ステップを介して報告します。 -- announce ステップは、リクエスト元セッションではなくサブエージェントセッション内で実行されます。 +- announce ステップは（リクエスターセッションではなく）サブエージェントセッション内で実行されます。 - サブエージェントが正確に `ANNOUNCE_SKIP` と返信した場合、何も投稿されません。 -- 最新のアシスタントテキストが正確なサイレントトークン `NO_REPLY` / `no_reply` の場合、それ以前に表示される進捗が存在していても announce 出力は抑制されます。 +- 最新のアシスタントテキストが正確なサイレントトークン `NO_REPLY` / `no_reply` の場合、それ以前に表示される進捗があっても announce 出力は抑制されます。 -配信はリクエスト元の深さによって異なります。 +配信はリクエスターの深さによって異なります。 -- トップレベルのリクエスト元セッションは、外部配信（`deliver=true`）付きのフォローアップ `agent` 呼び出しを使用します。 -- ネストされたリクエスト元サブエージェントセッションは内部フォローアップ注入（`deliver=false`）を受け取るため、オーケストレーターは子の結果をセッション内で合成できます。 -- ネストされたリクエスト元サブエージェントセッションが存在しない場合、OpenClaw は利用可能であればそのセッションのリクエスト元にフォールバックします。 +- トップレベルのリクエスターセッションは、外部配信（`deliver=true`）付きのフォローアップ `agent` 呼び出しを使用します。 +- ネストされたリクエスターサブエージェントセッションは、内部フォローアップ注入（`deliver=false`）を受け取り、オーケストレーターが子の結果をセッション内で統合できるようにします。 +- ネストされたリクエスターサブエージェントセッションが存在しない場合、OpenClaw は利用可能であればそのセッションのリクエスターにフォールバックします。 -トップレベルのリクエスト元セッションでは、完了モードの直接配信はまず、バインドされた会話/スレッドルートとフックオーバーライドを解決し、その後、リクエスト元セッションに保存されたルートから不足しているチャンネルターゲットフィールドを埋めます。これにより、完了の発信元がチャンネルのみを識別している場合でも、完了は正しいチャット/トピックに留まります。 +トップレベルのリクエスターセッションでは、完了モードの直接配信はまず +バインド済みの会話/スレッドルートとフックのオーバーライドを解決し、その後 +リクエスターセッションに保存されたルートから不足しているチャネルターゲットフィールドを埋めます。 +これにより、完了元がチャネルのみを識別する場合でも、完了が正しいチャット/トピックに保持されます。 -ネストされた完了結果を構築するとき、子の完了集約は現在のリクエスト元実行にスコープされ、古い以前の実行の子出力が現在の announce に漏れ込むことを防ぎます。announce 返信は、チャンネルアダプターで利用可能な場合、スレッド/トピックルーティングを保持します。 +ネストされた完了の所見を構築するとき、子の完了集約は現在のリクエスター実行にスコープされるため、以前の実行の古い子出力が現在の announce に漏れ込むことを防ぎます。announce の返信は、チャネルアダプターで利用可能な場合、スレッド/トピックのルーティングを保持します。 ### Announce コンテキスト -Announce コンテキストは安定した内部イベントブロックに正規化されます。 +Announce コンテキストは、安定した内部イベントブロックに正規化されます。 | フィールド | ソース | | -------------- | ------------------------------------------------------------------------------------------------------------- | | ソース | `subagent` または `cron` | -| セッション ID | 子セッションキー/id | -| タイプ | Announce タイプ + タスクラベル | -| ステータス | ランタイム結果（`success`、`error`、`timeout`、または `unknown`）から派生。モデルテキストからは推測**されません** | -| 結果コンテンツ | 最新の表示可能なアシスタントテキスト。それがなければサニタイズ済みの最新 tool/toolResult テキスト | -| フォローアップ | 返信する場合と沈黙を保つ場合を説明する指示 | +| セッション ID | 子セッションキー/ID | +| タイプ | announce タイプ + タスクラベル | +| ステータス | ランタイム結果（`success`、`error`、`timeout`、または `unknown`）から派生 — モデルテキストからは推定**しません** | +| 結果コンテンツ | 最新の表示可能なアシスタントテキスト。なければ、サニタイズされた最新のツール/toolResult テキスト | +| フォローアップ | いつ返信し、いつサイレントのままでいるかを説明する指示 | -終端で失敗した実行は、キャプチャされた返信テキストを再生せずに失敗ステータスを報告します。タイムアウト時に子がツール呼び出しまでしか進まなかった場合、announce は生のツール出力を再生する代わりに、その履歴を短い部分進捗サマリーへ圧縮できます。 +端末の失敗した実行は、キャプチャされた返信テキストを再生せずに +失敗ステータスを報告します。タイムアウト時に子がツール呼び出しまでしか進んでいない場合、announce は生のツール出力を再生する代わりに、その履歴を短い部分進捗サマリーに折りたたむことができます。 ### 統計行 -Announce ペイロードには末尾に統計行が含まれます（折り返されている場合でも）。 +Announce ペイロードには、末尾に統計行が含まれます（折り返されている場合でも）。 - ランタイム（例: `runtime 5m12s`）。 - トークン使用量（入力/出力/合計）。 - モデル価格が設定されている場合の推定コスト（`models.providers.*.models[].cost`）。 -- `sessionKey`、`sessionId`、およびトランスクリプトパス。メインエージェントが `sessions_history` で履歴を取得したり、ディスク上のファイルを検査したりできます。 +- メインエージェントが `sessions_history` で履歴を取得したり、ディスク上のファイルを調べたりできるようにするための、`sessionKey`、`sessionId`、トランスクリプトパス。 -内部メタデータはオーケストレーション専用です。ユーザー向けの返信は通常のアシスタントの声に書き直す必要があります。 +内部メタデータはオーケストレーション専用です。ユーザー向けの返信は通常のアシスタントの声に書き直すべきです。 ### `sessions_history` を推奨する理由 `sessions_history` はより安全なオーケストレーション経路です。 -- アシスタントの recall は最初に正規化されます。thinking タグを除去し、`` / `` の足場を除去し、プレーンテキストのツール呼び出し XML ペイロードブロック（``、``、``、``）を、正しく閉じていない切り詰められたペイロードも含めて除去し、ダウングレードされたツール呼び出し/結果の足場と履歴コンテキストマーカーを除去し、漏洩したモデル制御トークン（`<|assistant|>`、その他の ASCII `<|...|>`、全角 `<｜...｜>`）を除去し、不正な MiniMax ツール呼び出し XML を除去します。 +- アシスタントのリコールは最初に正規化されます。thinking タグが削除され、`` / `` の足場が削除され、プレーンテキストのツール呼び出し XML ペイロードブロック（``、``、``、``）が、正常に閉じていない切り詰められたペイロードを含めて削除され、ダウングレードされたツール呼び出し/結果の足場と履歴コンテキストマーカーが削除され、漏えいしたモデル制御トークン（`<|assistant|>`、その他の ASCII `<|...|>`、全角 `<｜...｜>`）が削除され、不正な MiniMax ツール呼び出し XML が削除されます。 - 認証情報/トークンのようなテキストはリダクトされます。 -- 長いブロックは切り詰められる場合があります。 -- 非常に大きな履歴では、古い行が削除されたり、サイズが過大な行が `[sessions_history omitted: message too large]` に置き換えられたりする場合があります。 -- 完全なバイト単位のトランスクリプトが必要な場合、ディスク上の生トランスクリプト検査がフォールバックです。 +- 長いブロックは切り詰められることがあります。 +- 非常に大きな履歴では、古い行を削除したり、過大な行を `[sessions_history omitted: message too large]` に置き換えたりできます。 +- バイト単位で完全なトランスクリプトが必要な場合は、ディスク上の生トランスクリプト検査がフォールバックです。 ## ツールポリシー -サブエージェントはまず、親またはターゲットエージェントと同じプロファイルとツールポリシーパイプラインを使用します。その後、OpenClaw がサブエージェント制限レイヤーを適用します。 +サブエージェントは、まず親または対象エージェントと同じプロファイルおよびツールポリシーパイプラインを使用します。その後、OpenClaw がサブエージェント制限レイヤーを適用します。 -制限的な `tools.profile` がない場合、サブエージェントは**セッションツール**とシステムツールを除くすべてのツールを取得します。 +制限的な `tools.profile` がない場合、サブエージェントは**セッションツールを除くすべてのツール**とシステムツールを取得します。 - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -ここでも `sessions_history` は、境界のあるサニタイズ済み recall ビューのままです。生のトランスクリプトダンプではありません。 +`sessions_history` はここでも境界付きでサニタイズされた想起ビューのままです。生のトランスクリプトダンプではありません。 -`maxSpawnDepth >= 2` の場合、深さ 1 のオーケストレーターサブエージェントは、子を管理できるように `sessions_spawn`、`subagents`、`sessions_list`、および -`sessions_history` も受け取ります。 +`maxSpawnDepth >= 2` の場合、深さ 1 のオーケストレーターサブエージェントは、子を管理できるように `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history` も追加で受け取ります。 -### 設定によるオーバーライド +### 設定による上書き ```json5 { @@ -450,7 +427,7 @@ Announce ペイロードには末尾に統計行が含まれます（折り返 } ``` -`tools.subagents.tools.allow` は最終的な許可専用フィルターです。すでに解決済みのツールセットを絞り込むことはできますが、`tools.profile` によって削除されたツールを**追加し直す**ことはできません。たとえば、`tools.profile: "coding"` には `web_search`/`web_fetch` が含まれますが、`browser` ツールは含まれません。coding プロファイルのサブエージェントでブラウザ自動化を使えるようにするには、プロファイル段階で browser を追加します。 +`tools.subagents.tools.allow` は最終的な許可専用フィルターです。すでに解決済みのツールセットを狭めることはできますが、`tools.profile` によって削除されたツールを**追加し直す**ことはできません。たとえば、`tools.profile: "coding"` には `web_search`/`web_fetch` が含まれますが、`browser` ツールは含まれません。coding プロファイルのサブエージェントにブラウザー自動化を使わせるには、プロファイル段階で browser を追加します。 ```json5 { @@ -461,40 +438,40 @@ Announce ペイロードには末尾に統計行が含まれます（折り返 } ``` -1 つのエージェントだけにブラウザ自動化を許可する場合は、エージェントごとの `agents.list[].tools.alsoAllow: ["browser"]` を使用します。 +1 つのエージェントだけにブラウザー自動化を与える場合は、エージェント単位の `agents.list[].tools.alsoAllow: ["browser"]` を使用します。 -## 並行実行 +## 並行処理 サブエージェントは専用のインプロセスキューレーンを使用します。 - **レーン名:** `subagent` -- **並行数:** `agents.defaults.subagents.maxConcurrent` (デフォルト `8`) +- **並行数:** `agents.defaults.subagents.maxConcurrent`（既定値 `8`） -## 生存確認と復旧 +## ライブネスと復旧 -OpenClaw は `endedAt` が存在しないことを、サブエージェントがまだ生きている恒久的な証拠として扱いません。stale-run ウィンドウより古い未終了の実行は、`/subagents list`、ステータス要約、子孫完了ゲート、およびセッションごとの並行実行チェックで active/pending としてカウントされなくなります。 +OpenClaw は、`endedAt` が存在しないことを、サブエージェントがまだ生存している恒久的な証拠として扱いません。stale-run ウィンドウより古い未終了の実行は、`/subagents list`、ステータス要約、子孫の完了ゲート、セッション単位の並行処理チェックで active/pending として数えられなくなります。 -Gateway 再起動後、古くなった未終了の復元済み実行は、その子セッションが `abortedLastRun: true` としてマークされていない限り剪定されます。これらの再起動により中断された子セッションは、サブエージェントの孤立復旧フローを通じて復旧可能なままです。このフローは、中断マーカーをクリアする前に合成 resume メッセージを送信します。 +Gateway の再起動後、古い未終了の復元済み実行は、その子セッションが `abortedLastRun: true` とマークされていない限り、削除されます。これらの再起動で中断された子セッションは、サブエージェントの孤立復旧フローを通じて復旧可能なままです。このフローは、中断マーカーをクリアする前に合成 resume メッセージを送信します。 -自動再起動復旧は子セッションごとに制限されます。同じサブエージェントの子が rapid re-wedge ウィンドウ内で繰り返し孤立復旧に受け入れられた場合、OpenClaw はそのセッションに復旧 tombstone を永続化し、以降の再起動で自動再開を停止します。タスクレコードを整合させるには `openclaw tasks maintenance --apply` を実行し、tombstone 化されたセッション上の古い中断済み復旧フラグをクリアするには `openclaw doctor --fix` を実行します。 +自動再起動復旧は子セッションごとに制限されます。同じサブエージェントの子が rapid re-wedge ウィンドウ内で繰り返し孤立復旧として受け入れられた場合、OpenClaw はそのセッションに復旧 tombstone を永続化し、以後の再起動では自動 resume を停止します。タスクレコードを調整するには `openclaw tasks maintenance --apply` を実行し、tombstone 付きセッションの古い中断復旧フラグをクリアするには `openclaw doctor --fix` を実行します。 -サブエージェントの spawn が Gateway `PAIRING_REQUIRED` / `scope-upgrade` で失敗する場合は、ペアリング状態を編集する前に RPC 呼び出し元を確認してください。内部の `sessions_spawn` 調整は、直接 loopback の共有トークン/パスワード認証を介して、`client.id: "gateway-client"` と `client.mode: "backend"` で接続する必要があります。この経路は、CLI のペアリング済みデバイスのスコープベースラインには依存しません。リモート呼び出し元、明示的な `deviceIdentity`、明示的なデバイストークン経路、およびブラウザ/node クライアントでは、スコープアップグレードに通常のデバイス承認が引き続き必要です。 +サブエージェントの spawn が Gateway `PAIRING_REQUIRED` / `scope-upgrade` で失敗する場合は、ペアリング状態を編集する前に RPC 呼び出し元を確認してください。内部の `sessions_spawn` 調整は、直接 local loopback の共有トークン/パスワード認証を介して `client.id: "gateway-client"`、`client.mode: "backend"` として接続する必要があります。このパスは CLI のペアリング済みデバイススコープベースラインに依存しません。リモート呼び出し元、明示的な `deviceIdentity`、明示的なデバイストークンパス、browser/node クライアントでは、スコープアップグレードに通常のデバイス承認が引き続き必要です。 ## 停止 -- リクエスターのチャットで `/stop` を送信すると、リクエスターセッションが中断され、そこから spawn されたアクティブなサブエージェント実行がすべて停止され、ネストされた子にもカスケードされます。 +- リクエスターのチャットで `/stop` を送信すると、リクエスターセッションが中断され、そこから spawn されたアクティブなサブエージェント実行がすべて停止し、ネストされた子にもカスケードします。 - `/subagents kill ` は特定のサブエージェントを停止し、その子にもカスケードします。 ## 制限事項 -- サブエージェントの announce は**ベストエフォート**です。Gateway が再起動すると、保留中の「announce back」作業は失われます。 -- サブエージェントは同じ Gateway プロセスリソースを引き続き共有します。`maxConcurrent` は安全弁として扱ってください。 -- `sessions_spawn` は常に非ブロッキングです。即座に `{ status: "accepted", runId, childSessionKey }` を返します。 -- サブエージェントコンテキストは `AGENTS.md` + `TOOLS.md` のみを注入します (`SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` は注入しません)。 -- 最大ネスト深度は 5 です (`maxSpawnDepth` の範囲: 1–5)。ほとんどのユースケースでは深度 2 を推奨します。 -- `maxChildrenPerAgent` はセッションごとのアクティブな子の数を制限します (デフォルト `5`、範囲 `1–20`)。 +- サブエージェントの通知は**ベストエフォート**です。Gateway が再起動すると、保留中の「announce back」作業は失われます。 +- サブエージェントは引き続き同じ Gateway プロセスリソースを共有します。`maxConcurrent` は安全弁として扱ってください。 +- `sessions_spawn` は常にノンブロッキングです。即座に `{ status: "accepted", runId, childSessionKey }` を返します。 +- サブエージェントコンテキストは `AGENTS.md` + `TOOLS.md` のみを注入します（`SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` は含みません）。 +- 最大ネスト深さは 5 です（`maxSpawnDepth` の範囲: 1–5）。ほとんどのユースケースでは深さ 2 が推奨されます。 +- `maxChildrenPerAgent` はセッションごとのアクティブな子の上限を設定します（既定値 `5`、範囲 `1–20`）。 ## 関連 diff --git a/docs/ja-JP/web/control-ui.md b/docs/ja-JP/web/control-ui.md index 0860ca900..e4df189ac 100644 --- a/docs/ja-JP/web/control-ui.md +++ b/docs/ja-JP/web/control-ui.md @@ -1,20 +1,20 @@ --- read_when: - ブラウザから Gateway を操作したい場合 - - SSH トンネルなしで Tailnet アクセスを使いたい場合 + - SSH トンネルなしで Tailnet アクセスを利用したい sidebarTitle: Control UI -summary: ブラウザベースの Gateway 用コントロール UI（チャット、ノード、設定） -title: コントロール UI +summary: Gateway のブラウザベースの制御 UI（チャット、ノード、設定） +title: 制御 UI x-i18n: - generated_at: "2026-05-04T05:03:12Z" + generated_at: "2026-05-04T07:04:41Z" model: gpt-5.5 provider: openai - source_hash: 99a40ab77276fbc3180aefb103c2dd46804829c7b1b6966a8456ed35b85ed644 + source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5 source_path: web/control-ui.md workflow: 16 --- -コントロール UI は、Gateway によって配信される小さな **Vite + Lit** シングルページアプリです。 +Control UI は、Gateway によって配信される小さな **Vite + Lit** のシングルページアプリです。 - デフォルト: `http://:18789/` - 任意のプレフィックス: `gateway.controlUi.basePath` を設定します (例: `/openclaw`) @@ -29,18 +29,18 @@ Gateway が同じコンピューターで実行されている場合は、次を ページの読み込みに失敗する場合は、先に Gateway を起動します: `openclaw gateway`。 -認証は、WebSocket ハンドシェイク中に次の方法で提供されます。 +認証は、WebSocket ハンドシェイク中に次を介して提供されます。 - `connect.params.auth.token` - `connect.params.auth.password` - `gateway.auth.allowTailscale: true` の場合の Tailscale Serve アイデンティティヘッダー - `gateway.auth.mode: "trusted-proxy"` の場合の信頼済みプロキシアイデンティティヘッダー -ダッシュボードの設定パネルは、現在のブラウザータブセッションと選択中の Gateway URL 用のトークンを保持します。パスワードは永続化されません。オンボーディングでは通常、初回接続時に共有シークレット認証用の Gateway トークンが生成されますが、`gateway.auth.mode` が `"password"` の場合はパスワード認証も機能します。 +ダッシュボード設定パネルは、現在のブラウザータブセッションと選択された gateway URL のトークンを保持します。パスワードは永続化されません。オンボーディングは通常、初回接続時に共有シークレット認証用の gateway トークンを生成しますが、`gateway.auth.mode` が `"password"` の場合はパスワード認証も機能します。 -## デバイスペアリング (初回接続) +## デバイスのペアリング (初回接続) -新しいブラウザーまたはデバイスからコントロール UI に接続すると、Gateway は通常、**一回限りのペアリング承認**を要求します。これは不正アクセスを防ぐためのセキュリティ対策です。 +新しいブラウザーまたはデバイスから Control UI に接続すると、Gateway は通常、**1回限りのペアリング承認**を要求します。これは不正アクセスを防ぐためのセキュリティ対策です。 **表示される内容:** 「disconnected (1008): pairing required」 @@ -59,13 +59,13 @@ Gateway が同じコンピューターで実行されている場合は、次を ブラウザーが変更された認証詳細 (ロール/スコープ/公開鍵) でペアリングを再試行すると、以前の保留中リクエストは置き換えられ、新しい `requestId` が作成されます。承認前に `openclaw devices list` を再実行してください。 -ブラウザーがすでにペアリング済みで、読み取りアクセスから書き込み/管理者アクセスへ変更する場合、これはサイレント再接続ではなく承認のアップグレードとして扱われます。OpenClaw は古い承認を有効なまま保持し、より広い再接続をブロックし、新しいスコープセットを明示的に承認するよう求めます。 +ブラウザーがすでにペアリング済みで、読み取りアクセスから書き込み/管理者アクセスへ変更する場合、これはサイレントな再接続ではなく承認アップグレードとして扱われます。OpenClaw は古い承認を有効なまま保持し、より広い権限での再接続をブロックし、新しいスコープセットを明示的に承認するよう求めます。 -承認されるとデバイスは記憶され、`openclaw devices revoke --device --role ` で取り消さない限り再承認は不要です。トークンローテーションと取り消しについては、[デバイス CLI](/ja-JP/cli/devices) を参照してください。 +承認されるとデバイスは記憶され、`openclaw devices revoke --device --role ` で取り消さない限り再承認は不要です。トークンローテーションと取り消しについては [デバイス CLI](/ja-JP/cli/devices) を参照してください。 - 直接の local loopback ブラウザー接続 (`127.0.0.1` / `localhost`) は自動承認されます。 -- `gateway.auth.allowTailscale: true` で、Tailscale アイデンティティが検証され、ブラウザーがデバイスアイデンティティを提示する場合、Tailscale Serve はコントロール UI オペレーターセッションのペアリング往復を省略できます。 +- `gateway.auth.allowTailscale: true` で、Tailscale アイデンティティが検証され、ブラウザーが自身のデバイスアイデンティティを提示する場合、Tailscale Serve は Control UI オペレーターセッションのペアリング往復を省略できます。 - 直接の Tailnet バインド、LAN ブラウザー接続、デバイスアイデンティティのないブラウザープロファイルでは、引き続き明示的な承認が必要です。 - 各ブラウザープロファイルは一意のデバイス ID を生成するため、ブラウザーを切り替えたりブラウザーデータを消去したりすると、再ペアリングが必要になります。 @@ -73,80 +73,80 @@ Gateway が同じコンピューターで実行されている場合は、次を ## 個人アイデンティティ (ブラウザーローカル) -コントロール UI は、共有セッションでの帰属表示のために送信メッセージへ付与される、ブラウザーごとの個人アイデンティティ (表示名とアバター) をサポートします。これはブラウザーストレージに存在し、現在のブラウザープロファイルにスコープされ、他のデバイスには同期されません。また、実際に送信したメッセージ上の通常のトランスクリプト作成者メタデータを除き、サーバー側に永続化されません。サイトデータを消去したりブラウザーを切り替えたりすると、空にリセットされます。 +Control UI は、共有セッションでの帰属表示のため、送信メッセージに付加されるブラウザーごとの個人アイデンティティ (表示名とアバター) をサポートします。これはブラウザーストレージに保存され、現在のブラウザープロファイルにスコープされ、実際に送信したメッセージ上の通常のトランスクリプト著者メタデータを除き、他のデバイスへ同期されたりサーバー側に永続化されたりしません。サイトデータを消去するかブラウザーを切り替えると空にリセットされます。 -同じブラウザーローカルのパターンは、アシスタントアバターの上書きにも適用されます。アップロードされたアシスタントアバターは、ローカルブラウザー上でのみ Gateway が解決したアイデンティティに重ねられ、`config.patch` を通じて往復することはありません。共有 `ui.assistant.avatar` 設定フィールドは、このフィールドへ直接書き込む非 UI クライアント (スクリプト化された Gateway やカスタムダッシュボードなど) 向けに引き続き利用できます。 +同じブラウザーローカルのパターンは、アシスタントアバターの上書きにも適用されます。アップロードされたアシスタントアバターは、ローカルブラウザー上でのみ gateway が解決したアイデンティティに重ねられ、`config.patch` を介して往復することはありません。共有の `ui.assistant.avatar` 設定フィールドは、スクリプト化された gateway やカスタムダッシュボードなど、このフィールドを直接書き込む非 UI クライアント向けに引き続き利用できます。 ## ランタイム設定エンドポイント -コントロール UI は、実行時設定を `/__openclaw/control-ui-config.json` から取得します。このエンドポイントは、HTTP サーフェスの残りと同じ Gateway 認証で制御されます。未認証のブラウザーは取得できず、取得に成功するには、すでに有効な Gateway トークン/パスワード、Tailscale Serve アイデンティティ、または信頼済みプロキシアイデンティティのいずれかが必要です。 +Control UI は、ランタイム設定を `/__openclaw/control-ui-config.json` から取得します。そのエンドポイントは、HTTP サーフェスの残り部分と同じ gateway 認証で保護されています。未認証のブラウザーは取得できず、取得に成功するには、すでに有効な gateway トークン/パスワード、Tailscale Serve アイデンティティ、または信頼済みプロキシアイデンティティのいずれかが必要です。 ## 言語サポート -コントロール UI は、初回読み込み時にブラウザーのロケールに基づいてローカライズできます。後で上書きするには、**概要 -> Gateway アクセス -> 言語** を開きます。ロケールピッカーは外観ではなく、Gateway アクセスカードにあります。 +Control UI は、初回読み込み時にブラウザーのロケールに基づいて自身をローカライズできます。後で上書きするには、**概要 -> Gateway アクセス -> 言語**を開きます。ロケールピッカーは外観ではなく、Gateway アクセスカードにあります。 -- サポートされるロケール: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` -- 英語以外の翻訳はブラウザーで遅延読み込みされます。 -- 選択したロケールはブラウザーストレージに保存され、以後の訪問で再利用されます。 -- 不足している翻訳キーは英語にフォールバックします。 +- サポートされているロケール: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` +- 英語以外の翻訳はブラウザー内で遅延読み込みされます。 +- 選択されたロケールはブラウザーストレージに保存され、以後の訪問で再利用されます。 +- 欠落している翻訳キーは英語にフォールバックします。 -ドキュメント翻訳は同じ英語以外のロケールセット向けに生成されますが、ドキュメントサイトに組み込まれた Mintlify の言語ピッカーは、Mintlify が受け入れるロケールコードに制限されています。タイ語 (`th`) とペルシア語 (`fa`) のドキュメントは公開リポジトリで引き続き生成されますが、Mintlify がこれらのコードをサポートするまで、そのピッカーには表示されない場合があります。 +Docs 翻訳は同じ英語以外のロケールセット向けに生成されますが、docs サイト組み込みの Mintlify 言語ピッカーは、Mintlify が受け付けるロケールコードに制限されています。タイ語 (`th`) とペルシア語 (`fa`) の docs は公開リポジトリで引き続き生成されますが、Mintlify がこれらのコードをサポートするまで、そのピッカーには表示されない場合があります。 ## 外観テーマ -外観パネルには、組み込みの Claw、Knot、Dash テーマに加え、ブラウザーローカルの tweakcn インポートスロットが 1 つあります。テーマをインポートするには、[tweakcn editor](https://tweakcn.com/editor/theme) を開き、テーマを選択または作成し、**共有** をクリックして、コピーしたテーマリンクを外観に貼り付けます。インポーターは `https://tweakcn.com/r/themes/` レジストリ URL、`https://tweakcn.com/editor/theme?theme=amethyst-haze` のようなエディター URL、相対 `/themes/` パス、生のテーマ ID、`amethyst-haze` などのデフォルトテーマ名も受け入れます。 +外観パネルは、組み込みの Claw、Knot、Dash テーマに加え、ブラウザーローカルの tweakcn インポートスロットを1つ保持します。テーマをインポートするには、[tweakcn エディター](https://tweakcn.com/editor/theme) を開き、テーマを選択または作成して **共有** をクリックし、コピーしたテーマリンクを外観に貼り付けます。インポーターは、`https://tweakcn.com/r/themes/` レジストリ URL、`https://tweakcn.com/editor/theme?theme=amethyst-haze` のようなエディター URL、相対 `/themes/` パス、生のテーマ ID、`amethyst-haze` などのデフォルトテーマ名も受け付けます。 -インポートされたテーマは現在のブラウザープロファイルにのみ保存されます。Gateway 設定には書き込まれず、デバイス間で同期されません。インポート済みテーマを置き換えると、1 つのローカルスロットが更新されます。消去すると、インポート済みテーマが選択されていた場合、アクティブテーマは Claw に戻ります。 +インポートされたテーマは、現在のブラウザープロファイルにのみ保存されます。gateway 設定には書き込まれず、デバイス間で同期されません。インポート済みテーマを置き換えると、その1つのローカルスロットが更新されます。クリアすると、インポート済みテーマが選択されていた場合はアクティブテーマが Claw に戻ります。 -## できること (現在) +## できること (現時点) - Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`) 経由でモデルとチャットします。 - - ブラウザーのリアルタイムセッションで通話します。OpenAI は直接 WebRTC を使用し、Google Live は WebSocket 経由の制約付き一回限りブラウザートークンを使用し、バックエンド専用リアルタイム音声 Plugin は Gateway リレートランスポートを使用します。リレーはプロバイダー資格情報を Gateway 上に保持し、ブラウザーは `talk.realtime.relay*` RPC を通じてマイク PCM をストリーミングし、より大きな設定済み OpenClaw モデル用の `openclaw_agent_consult` ツール呼び出しを `chat.send` 経由で送り返します。 - - チャットでツール呼び出しとライブツール出力カードをストリーミングします (エージェントイベント)。 + - ブラウザーのリアルタイムセッションを通じて通話します。OpenAI は直接 WebRTC を使用し、Google Live は WebSocket 上の制限付き1回使用ブラウザートークンを使用し、バックエンド専用リアルタイム音声 plugins は Gateway リレートランスポートを使用します。リレーはプロバイダー認証情報を Gateway に保持し、ブラウザーは `talk.realtime.relay*` RPC を通じてマイク PCM をストリーミングし、より大きな設定済み OpenClaw モデル用に `openclaw_agent_consult` ツール呼び出しを `chat.send` 経由で送り返します。 + - チャット内でツール呼び出しとライブツール出力カードをストリーミングします (エージェントイベント)。 - - - チャンネル: 組み込みおよび同梱/外部 Plugin チャンネルのステータス、QR ログイン、チャンネルごとの設定 (`channels.status`, `web.login.*`, `config.patch`)。 + + - チャンネル: 組み込みおよびバンドル/外部 plugin チャンネルのステータス、QR ログイン、チャンネルごとの設定 (`channels.status`, `web.login.*`, `config.patch`)。 - インスタンス: プレゼンス一覧と更新 (`system-presence`)。 - - セッション: 一覧とセッションごとのモデル/思考/高速/詳細/トレース/推論の上書き (`sessions.list`, `sessions.patch`)。 - - Dream: Dreaming ステータス、有効/無効トグル、Dream Diary リーダー (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)。 + - セッション: 一覧とセッションごとのモデル/思考/高速/詳細/トレース/reasoning 上書き (`sessions.list`, `sessions.patch`)。 + - Dream: Dreaming ステータス、有効化/無効化トグル、Dream Diary リーダー (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)。 - + - Cron ジョブ: 一覧/追加/編集/実行/有効化/無効化と実行履歴 (`cron.*`)。 - Skills: ステータス、有効化/無効化、インストール、API キー更新 (`skills.*`)。 - ノード: 一覧と機能 (`node.list`)。 - - exec 承認: Gateway またはノードの許可リストと `exec host=gateway/node` の確認ポリシーを編集します (`exec.approvals.*`)。 + - Exec 承認: `exec host=gateway/node` の gateway またはノードの許可リストと確認ポリシーを編集 (`exec.approvals.*`)。 - `~/.openclaw/openclaw.json` を表示/編集します (`config.get`, `config.set`)。 - - 検証付きで適用して再起動し (`config.apply`)、最後にアクティブだったセッションを起こします。 - - 書き込みには、同時編集による上書きを防ぐためのベースハッシュガードが含まれます。 - - 書き込み (`config.set`/`config.apply`/`config.patch`) は、送信された設定ペイロード内の参照について、アクティブな SecretRef 解決を事前確認します。送信された未解決のアクティブ参照は、書き込み前に拒否されます。 - - スキーマとフォームレンダリング (`config.schema` / `config.schema.lookup`。フィールド `title` / `description`、一致した UI ヒント、直下の子要素サマリー、ネストされたオブジェクト/ワイルドカード/配列/合成ノード上のドキュメントメタデータ、利用可能な場合は Plugin とチャンネルのスキーマを含む)。Raw JSON エディターは、スナップショットが安全に raw 往復できる場合にのみ利用できます。 - - スナップショットが raw テキストを安全に往復できない場合、コントロール UI はフォームモードを強制し、そのスナップショットの Raw モードを無効にします。 - - Raw JSON エディターの「保存済みにリセット」は、フラット化されたスナップショットを再レンダリングする代わりに、raw で作成された形状 (書式、コメント、`$include` レイアウト) を保持するため、スナップショットが安全に往復できる場合は外部編集がリセット後も残ります。 - - 構造化された SecretRef オブジェクト値は、誤ってオブジェクトから文字列へ破損することを防ぐため、フォームのテキスト入力では読み取り専用でレンダリングされます。 + - 検証付きで適用と再起動を行い (`config.apply`)、最後にアクティブだったセッションを起動します。 + - 書き込みには、同時編集を上書きしないためのベースハッシュガードが含まれます。 + - 書き込み (`config.set`/`config.apply`/`config.patch`) は、送信された設定ペイロード内の参照について、アクティブな SecretRef 解決を事前チェックします。未解決のアクティブな送信済み参照は、書き込み前に拒否されます。 + - スキーマとフォームレンダリング (`config.schema` / `config.schema.lookup`。フィールド `title` / `description`、一致した UI ヒント、直下の子要約、ネストされた object/wildcard/array/composition ノード上の docs メタデータ、利用可能な場合は plugin とチャンネルスキーマを含む)。Raw JSON エディターは、スナップショットが安全な raw 往復を持つ場合にのみ利用できます。 + - スナップショットが raw テキストを安全に往復できない場合、Control UI はフォームモードを強制し、そのスナップショットの Raw モードを無効にします。 + - Raw JSON エディターの「保存済みにリセット」は、平坦化されたスナップショットを再レンダリングするのではなく、raw で作成された形状 (フォーマット、コメント、`$include` レイアウト) を保持するため、スナップショットが安全に往復できる場合、外部編集はリセット後も維持されます。 + - 構造化された SecretRef object 値は、誤って object から文字列へ破損するのを防ぐため、フォームのテキスト入力では読み取り専用で表示されます。 - デバッグ: ステータス/ヘルス/モデルのスナップショット、イベントログ、手動 RPC 呼び出し (`status`, `health`, `models.list`)。 - - ログ: Gateway ファイルログのライブテール、フィルター/エクスポート付き (`logs.tail`)。 - - 更新: 再起動レポート付きでパッケージ/git 更新と再起動を実行し (`update.run`)、再接続後に `update.status` をポーリングして実行中の Gateway バージョンを検証します。 + - ログ: gateway ファイルログのライブテールとフィルター/エクスポート (`logs.tail`)。 + - 更新: パッケージ/git 更新と再起動を実行し (`update.run`)、再起動レポートを取得した後、再接続後に `update.status` をポーリングして実行中の gateway バージョンを検証します。 - - 分離ジョブでは、配信のデフォルトはサマリーのアナウンスです。内部専用の実行にしたい場合は、なしに切り替えられます。 - - アナウンスが選択されている場合、チャンネル/ターゲットフィールドが表示されます。 - - Webhook モードは、有効な HTTP(S) Webhook URL に設定された `delivery.to` とともに `delivery.mode = "webhook"` を使用します。 - - メインセッションジョブでは、Webhook と配信なしモードを利用できます。 - - 詳細編集コントロールには、実行後削除、エージェント上書きのクリア、Cron の厳密/分散オプション、エージェントのモデル/思考の上書き、ベストエフォート配信トグルが含まれます。 - - フォーム検証はフィールドレベルのエラーとしてインライン表示されます。無効な値がある場合、修正されるまで保存ボタンは無効になります。 - - 専用の bearer トークンを送信するには `cron.webhookToken` を設定します。省略した場合、Webhook は認証ヘッダーなしで送信されます。 - - 非推奨のフォールバック: `notify: true` を持つ保存済みの従来ジョブは、移行されるまで引き続き `cron.webhook` を使用できます。 + - 分離ジョブでは、配信のデフォルトは要約の告知です。内部専用の実行にしたい場合は none に切り替えられます。 + - announce が選択されている場合、チャンネル/ターゲットフィールドが表示されます。 + - Webhook モードは、有効な HTTP(S) webhook URL に設定された `delivery.to` とともに `delivery.mode = "webhook"` を使用します。 + - メインセッションジョブでは、webhook と none の配信モードを利用できます。 + - 詳細編集コントロールには、実行後削除、エージェント上書きのクリア、cron exact/stagger オプション、エージェントモデル/思考上書き、ベストエフォート配信トグルが含まれます。 + - フォーム検証はフィールドレベルのエラーとしてインライン表示されます。無効な値があると、修正されるまで保存ボタンが無効になります。 + - 専用 bearer トークンを送信するには `cron.webhookToken` を設定します。省略した場合、webhook は認証ヘッダーなしで送信されます。 + - 非推奨のフォールバック: `notify: true` を持つ保存済みのレガシージョブは、移行されるまで `cron.webhook` を引き続き使用できます。 @@ -155,62 +155,62 @@ Gateway が同じコンピューターで実行されている場合は、次を - - `chat.send` は**非ブロッキング**です。`{ runId, status: "started" }` ですぐに ACK し、応答は `chat` イベント経由でストリーミングされます。 - - チャットアップロードは画像と動画以外のファイルを受け付けます。画像はネイティブの画像パスを保持し、その他のファイルは管理対象メディアとして保存され、履歴には添付リンクとして表示されます。 - - 同じ `idempotencyKey` で再送信すると、実行中は `{ status: "in_flight" }`、完了後は `{ status: "ok" }` が返ります。 - - `chat.history` の応答は UI の安全性のためサイズ制限されています。トランスクリプトエントリが大きすぎる場合、Gateway は長いテキストフィールドを切り詰め、重いメタデータブロックを省略し、サイズ超過メッセージをプレースホルダー（`[chat.history omitted: message too large]`）に置き換えることがあります。 - - アシスタントまたは生成された画像は管理対象メディア参照として永続化され、認証済み Gateway メディア URL 経由で返されます。そのため、再読み込みは生の base64 画像ペイロードがチャット履歴応答に残っていることに依存しません。 - - `chat.history` は、表示専用のインラインディレクティブタグ（たとえば `[[reply_to_*]]` と `[[audio_as_voice]]`）、プレーンテキストのツール呼び出し XML ペイロード（`...`、`...`、`...`、`...`、切り詰められたツール呼び出しブロックを含む）、漏えいした ASCII/全角のモデル制御トークンも、表示されるアシスタントテキストから除去し、表示テキスト全体が正確なサイレントトークン `NO_REPLY` / `no_reply` だけであるアシスタントエントリを省略します。 - - アクティブな送信中と最終的な履歴更新中、`chat.history` が一時的に古いスナップショットを返した場合でも、チャットビューはローカルの楽観的なユーザー/アシスタントメッセージを表示し続けます。Gateway 履歴が追いつくと、正規のトランスクリプトがそれらのローカルメッセージを置き換えます。 - - ライブの `chat` イベントは配信状態であり、`chat.history` は永続セッショントランスクリプトから再構築されます。ツール最終イベントの後、Control UI は履歴を再読み込みし、小さな楽観的末尾だけをマージします。トランスクリプト境界は [WebChat](/ja-JP/web/webchat) に記載されています。 - - `chat.inject` はアシスタントメモをセッショントランスクリプトに追加し、UI のみの更新として `chat` イベントをブロードキャストします（エージェント実行なし、チャンネル配信なし）。 - - チャットヘッダーのモデルおよび思考ピッカーは、`sessions.patch` 経由でアクティブセッションに即座にパッチを適用します。これらは永続的なセッションオーバーライドであり、1 ターン限定の送信オプションではありません。 - - Control UI で `/new` と入力すると、New Chat と同じ新しいダッシュボードセッションが作成され、そのセッションに切り替わります。`/reset` と入力すると、現在のセッションに対する Gateway の明示的なインプレースリセットが維持されます。 - - チャットモデルピッカーは、Gateway に設定されたモデルビューを要求します。`agents.defaults.models` が存在する場合、その許可リストがピッカーを制御します。それ以外の場合、ピッカーには明示的な `models.providers.*.models` エントリと、使用可能な認証を持つプロバイダーが表示されます。完全なカタログは、デバッグ用の `models.list` RPC で `view: "all"` を指定すると引き続き利用できます。 - - 新しい Gateway セッション使用状況レポートが高いコンテキスト圧力を示す場合、チャットコンポーザー領域にはコンテキスト通知が表示され、推奨 Compaction レベルでは通常のセッション Compaction パスを実行するコンパクトボタンが表示されます。古いトークンスナップショットは、Gateway が新しい使用状況を再度報告するまで非表示になります。 + - `chat.send` は **非ブロッキング** です。`{ runId, status: "started" }` ですぐに ack し、応答は `chat` イベント経由でストリーミングされます。 + - チャットのアップロードは画像と動画以外のファイルを受け付けます。画像はネイティブの画像パスを保持し、それ以外のファイルは管理対象メディアとして保存され、履歴には添付リンクとして表示されます。 + - 同じ `idempotencyKey` で再送信すると、実行中は `{ status: "in_flight" }` が返り、完了後は `{ status: "ok" }` が返ります。 + - `chat.history` の応答は UI の安全性のためサイズ制限されます。トランスクリプト項目が大きすぎる場合、Gateway は長いテキストフィールドを切り詰め、重いメタデータブロックを省略し、過大なメッセージをプレースホルダー（`[chat.history omitted: message too large]`）に置き換えることがあります。 + - アシスタント/生成画像は管理対象メディア参照として永続化され、認証済み Gateway メディア URL 経由で返されるため、再読み込みは生の base64 画像ペイロードがチャット履歴応答に残っていることに依存しません。 + - `chat.history` は、表示用のインラインディレクティブタグ（例: `[[reply_to_*]]` と `[[audio_as_voice]]`）、プレーンテキストのツール呼び出し XML ペイロード（`...`、`...`、`...`、`...`、切り詰められたツール呼び出しブロックを含む）、漏洩した ASCII/全角のモデル制御トークンも、表示されるアシスタントテキストから取り除き、表示テキスト全体が正確なサイレントトークン `NO_REPLY` / `no_reply` だけのアシスタント項目を省略します。 + - アクティブな送信中と最終的な履歴更新中に、`chat.history` が一時的に古いスナップショットを返した場合でも、チャットビューはローカルの楽観的なユーザー/アシスタントメッセージを表示したままにします。Gateway 履歴が追いつくと、正規のトランスクリプトがそれらのローカルメッセージを置き換えます。 + - ライブ `chat` イベントは配信状態であり、`chat.history` は永続的なセッショントランスクリプトから再構築されます。ツール最終イベントの後、Control UI は履歴を再読み込みし、小さな楽観的テールだけをマージします。トランスクリプト境界は [WebChat](/ja-JP/web/webchat) に記載されています。 + - `chat.inject` はアシスタントメモをセッショントランスクリプトに追加し、UI のみの更新のために `chat` イベントをブロードキャストします（エージェント実行なし、チャネル配信なし）。 + - チャットヘッダーのモデルと思考ピッカーは、`sessions.patch` 経由でアクティブセッションに即座にパッチします。これらは永続的なセッションオーバーライドであり、1 ターン限りの送信オプションではありません。 + - Control UI で `/new` と入力すると、New Chat と同じ新しいダッシュボードセッションが作成され、そこに切り替わります。`/reset` と入力すると、現在のセッションに対する Gateway の明示的なインプレースリセットが維持されます。 + - チャットモデルピッカーは Gateway の設定済みモデルビューを要求します。`agents.defaults.models` が存在する場合、その許可リストがピッカーを駆動します。それ以外の場合、ピッカーは明示的な `models.providers.*.models` 項目と、利用可能な認証を持つプロバイダーを表示します。完全なカタログは、デバッグ用の `models.list` RPC で `view: "all"` を指定すると引き続き利用できます。 + - 新しい Gateway セッション使用状況レポートで高いコンテキスト圧力が示されると、チャットコンポーザー領域にコンテキスト通知が表示され、推奨 Compaction レベルでは通常のセッション Compaction パスを実行するコンパクトボタンが表示されます。古いトークンスナップショットは、Gateway が再び新しい使用状況を報告するまで非表示になります。 - トークモードは、登録済みのリアルタイム音声プロバイダーを使用します。OpenAI を設定するには `talk.provider: "openai"` と `talk.providers.openai.apiKey` を指定し、Google を設定するには `talk.provider: "google"` と `talk.providers.google.apiKey` を指定します。Voice Call のリアルタイムプロバイダー設定は、フォールバックとして引き続き再利用できます。ブラウザーが標準プロバイダー API キーを受け取ることはありません。OpenAI は WebRTC 用の一時的な Realtime クライアントシークレットを受け取ります。Google Live は、ブラウザー WebSocket セッション用の 1 回限りの制約付き Live API 認証トークンを受け取り、指示とツール宣言は Gateway によってトークン内に固定されます。バックエンドのリアルタイムブリッジのみを公開するプロバイダーは Gateway リレートランスポート経由で実行されるため、認証情報とベンダーソケットはサーバー側に留まり、ブラウザー音声は認証済み Gateway RPC 経由で移動します。Realtime セッションプロンプトは Gateway によって組み立てられます。`talk.realtime.session` は呼び出し元が提供する指示オーバーライドを受け付けません。 + トークモードは登録済みのリアルタイム音声プロバイダーを使用します。OpenAI は `talk.provider: "openai"` と `talk.providers.openai.apiKey` で設定するか、Google は `talk.provider: "google"` と `talk.providers.google.apiKey` で設定します。Voice Call リアルタイムプロバイダー設定はフォールバックとして引き続き再利用できます。ブラウザーが標準のプロバイダー API キーを受け取ることはありません。OpenAI は WebRTC 用の一時的な Realtime クライアントシークレットを受け取ります。Google Live は、ブラウザー WebSocket セッション用の 1 回限りの制約付き Live API 認証トークンを受け取り、指示とツール宣言は Gateway によってそのトークン内にロックされます。バックエンドのリアルタイムブリッジだけを公開するプロバイダーは Gateway リレートランスポートを経由するため、認証情報とベンダーソケットはサーバー側に留まり、ブラウザー音声は認証済み Gateway RPC 経由で移動します。Realtime セッションプロンプトは Gateway によって組み立てられます。`talk.realtime.session` は呼び出し元が指定する指示オーバーライドを受け付けません。 - Chat コンポーザーでは、Talk コントロールはマイクのディクテーションボタンの横にある波形ボタンです。Talk が開始されると、コンポーザーのステータス行には、音声接続中は `Connecting Talk...`、接続後は `Talk live`、リアルタイムツール呼び出しが `chat.send` 経由で設定済みのより大きなモデルに問い合わせている間は `Asking OpenClaw...` が表示されます。 + Chat コンポーザーでは、Talk コントロールはマイクディクテーションボタンの隣にある波形ボタンです。Talk が開始すると、コンポーザーのステータス行には `Connecting Talk...` が表示され、その後、音声が接続されている間は `Talk live`、またはリアルタイムツール呼び出しが `chat.send` 経由で設定済みのより大きなモデルに問い合わせている間は `Asking OpenClaw...` が表示されます。 - メンテナー向けライブスモーク: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` は、OpenAI ブラウザー WebRTC SDP 交換、Google Live の制約付きトークンによるブラウザー WebSocket セットアップ、偽のマイクメディアを使った Gateway リレーブラウザーアダプターを検証します。このコマンドはプロバイダーのステータスのみを出力し、シークレットはログに記録しません。 + メンテナー向けライブスモーク: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` は、OpenAI ブラウザー WebRTC SDP 交換、Google Live の制約付きトークンによるブラウザー WebSocket セットアップ、偽のマイクメディアを使用した Gateway リレーブラウザーアダプターを検証します。このコマンドはプロバイダーステータスのみを出力し、シークレットはログに記録しません。 - - **Stop** をクリックします（`chat.abort` を呼び出します）。 - - 実行がアクティブな間、通常のフォローアップはキューに入ります。キュー内のメッセージで **Steer** をクリックすると、そのフォローアップを実行中のターンに注入できます。 + - **停止** をクリックします（`chat.abort` を呼び出します）。 + - 実行がアクティブな間、通常のフォローアップはキューに入ります。キュー内のメッセージで **誘導** をクリックすると、そのフォローアップが実行中のターンに注入されます。 - `/stop`（または `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop` のような単独の中止フレーズ）を入力すると、帯域外で中止します。 - - `chat.abort` は、そのセッションのすべてのアクティブな実行を中止するために `{ sessionKey }`（`runId` なし）をサポートします。 + - `chat.abort` は `{ sessionKey }`（`runId` なし）をサポートし、そのセッションのすべてのアクティブな実行を中止できます。 - - 実行が中止された場合でも、部分的なアシスタントテキストが UI に表示されることがあります。 - - Gateway は、バッファーされた出力が存在する場合、中止された部分的なアシスタントテキストをトランスクリプト履歴に永続化します。 - - 永続化されたエントリには中止メタデータが含まれるため、トランスクリプト利用側は中止された部分出力と通常の完了出力を区別できます。 + - 実行が中止された場合でも、部分的なアシスタントテキストを UI に表示できます。 + - Gateway は、バッファリングされた出力が存在する場合、中止された部分的なアシスタントテキストをトランスクリプト履歴に永続化します。 + - 永続化された項目には中止メタデータが含まれるため、トランスクリプト利用者は中止された部分出力と通常の完了出力を区別できます。 -## PWA のインストールと Web Push +## PWA インストールと Web Push -Control UI には `manifest.webmanifest` とサービスワーカーが同梱されているため、最新のブラウザーではスタンドアロン PWA としてインストールできます。Web Push により、タブやブラウザーウィンドウが開いていない場合でも、Gateway は通知でインストール済み PWA を起動できます。 +Control UI には `manifest.webmanifest` とサービスワーカーが同梱されているため、最新のブラウザーはスタンドアロン PWA としてインストールできます。Web Push により、タブやブラウザーウィンドウが開いていない場合でも、Gateway は通知でインストール済み PWA を起動できます。 -| サーフェス | 動作 | +| サーフェス | 機能 | | ----------------------------------------------------- | ------------------------------------------------------------------ | | `ui/public/manifest.webmanifest` | PWA マニフェスト。到達可能になると、ブラウザーは「アプリをインストール」を提示します。 | | `ui/public/sw.js` | `push` イベントと通知クリックを処理するサービスワーカー。 | -| `push/vapid-keys.json`（OpenClaw 状態ディレクトリ配下） | Web Push ペイロードの署名に使用される、自動生成された VAPID キーペア。 | +| `push/vapid-keys.json`（OpenClaw 状態ディレクトリ配下） | Web Push ペイロードの署名に使用される、自動生成された VAPID 鍵ペア。 | | `push/web-push-subscriptions.json` | 永続化されたブラウザーサブスクリプションエンドポイント。 | -キーを固定したい場合（マルチホストデプロイ、シークレットローテーション、テストなど）は、Gateway プロセスの環境変数で VAPID キーペアをオーバーライドします。 +キーを固定したい場合（マルチホストデプロイ、シークレットローテーション、テストなど）は、Gateway プロセス上の環境変数で VAPID 鍵ペアをオーバーライドします。 - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT`（デフォルトは `mailto:openclaw@localhost`） -Control UI は、ブラウザーサブスクリプションを登録およびテストするために、これらのスコープ制限付き Gateway メソッドを使用します。 +Control UI は、ブラウザーサブスクリプションの登録とテストに、次のスコープ制限付き Gateway メソッドを使用します。 - `push.web.vapidPublicKey` — アクティブな VAPID 公開鍵を取得します。 - `push.web.subscribe` — `endpoint` と `keys.p256dh`/`keys.auth` を登録します。 @@ -218,22 +218,22 @@ Control UI は、ブラウザーサブスクリプションを登録およびテ - `push.web.test` — 呼び出し元のサブスクリプションにテスト通知を送信します。 -Web Push は、iOS APNS リレーパス（リレー backed push については [設定](/ja-JP/gateway/configuration) を参照）および既存の `push.test` メソッドとは独立しています。これらはネイティブモバイルペアリングを対象とします。 +Web Push は iOS APNS リレーパス（リレー支援 push については [設定](/ja-JP/gateway/configuration) を参照）および既存の `push.test` メソッドとは独立しています。これらはネイティブモバイルペアリングを対象にします。 -## ホストされた埋め込み +## ホスト型埋め込み -アシスタントメッセージは、`[embed ...]` ショートコードを使ってホストされた Web コンテンツをインラインでレンダリングできます。iframe サンドボックスポリシーは `gateway.controlUi.embedSandbox` によって制御されます。 +アシスタントメッセージは `[embed ...]` ショートコードでホスト型 Web コンテンツをインライン表示できます。iframe サンドボックスポリシーは `gateway.controlUi.embedSandbox` によって制御されます。 - ホストされた埋め込み内でのスクリプト実行を無効にします。 + ホスト型埋め込み内でのスクリプト実行を無効にします。 - - オリジン分離を維持しながらインタラクティブな埋め込みを許可します。これがデフォルトであり、通常は自己完結型のブラウザーゲーム/ウィジェットには十分です。 + + オリジン分離を維持しながらインタラクティブな埋め込みを許可します。これはデフォルトであり、通常は自己完結型のブラウザーゲーム/ウィジェットには十分です。 - より強い権限を意図的に必要とする同一サイトドキュメントのために、`allow-scripts` に加えて `allow-same-origin` を追加します。 + 意図的により強い権限を必要とする同一サイトドキュメント向けに、`allow-scripts` に加えて `allow-same-origin` を追加します。 @@ -253,11 +253,11 @@ Web Push は、iOS APNS リレーパス（リレー backed push については 埋め込みドキュメントが本当に同一オリジンの動作を必要とする場合にのみ、`trusted` を使用してください。ほとんどのエージェント生成ゲームやインタラクティブキャンバスでは、`scripts` の方が安全な選択です。 -絶対外部 `http(s)` 埋め込み URL は、デフォルトでは引き続きブロックされます。`[embed url="https://..."]` でサードパーティページを読み込ませたいことが意図的にある場合は、`gateway.controlUi.allowExternalEmbedUrls: true` を設定してください。 +絶対外部 `http(s)` 埋め込み URL はデフォルトでブロックされたままです。意図的に `[embed url="https://..."]` でサードパーティページを読み込みたい場合は、`gateway.controlUi.allowExternalEmbedUrls: true` を設定します。 ## チャットメッセージ幅 -グループ化されたチャットメッセージには、読みやすいデフォルトの最大幅が使用されます。ワイドモニターのデプロイでは、`gateway.controlUi.chatMessageMaxWidth` を設定することで、同梱 CSS にパッチを当てずにこれをオーバーライドできます。 +グループ化されたチャットメッセージには、読みやすいデフォルトの最大幅が使用されます。ワイドモニター環境では、`gateway.controlUi.chatMessageMaxWidth` を設定することで、同梱 CSS にパッチせずに上書きできます。 ```json5 { @@ -275,7 +275,7 @@ Web Push は、iOS APNS リレーパス（リレー backed push については - Gateway をループバックに保持し、Tailscale Serve に HTTPS でプロキシさせます。 + Gateway をループバックに維持し、Tailscale Serve で HTTPS プロキシさせます。 ```bash openclaw gateway --tailscale serve @@ -285,12 +285,12 @@ Web Push は、iOS APNS リレーパス（リレー backed push については - `https:///`（または設定済みの `gateway.controlUi.basePath`） - デフォルトでは、`gateway.auth.allowTailscale` が `true` の場合、Control UI/WebSocket Serve リクエストは Tailscale ID ヘッダー（`tailscale-user-login`）経由で認証できます。OpenClaw は、`x-forwarded-for` アドレスを `tailscale whois` で解決してヘッダーと照合することで ID を検証し、リクエストが Tailscale の `x-forwarded-*` ヘッダー付きで local loopback に到達した場合にのみ受け入れます。ブラウザーデバイス ID を持つ Control UI オペレーターセッションでは、この検証済み Serve パスはデバイスペアリングの往復もスキップします。デバイスなしのブラウザーとノードロール接続は、通常のデバイスチェックに従います。Serve トラフィックであっても明示的な共有シークレット認証情報を要求したい場合は、`gateway.auth.allowTailscale: false` を設定してください。そのうえで `gateway.auth.mode: "token"` または `"password"` を使用します。 + デフォルトでは、`gateway.auth.allowTailscale` が `true` の場合、Control UI/WebSocket Serve リクエストは Tailscale ID ヘッダー（`tailscale-user-login`）経由で認証できます。OpenClaw は `x-forwarded-for` アドレスを `tailscale whois` で解決してヘッダーと照合することで ID を検証し、リクエストが Tailscale の `x-forwarded-*` ヘッダー付きでループバックに到達した場合にのみ受け付けます。ブラウザーデバイス ID を持つ Control UI オペレーターセッションでは、この検証済み Serve パスはデバイスペアリングの往復もスキップします。デバイスなしのブラウザーとノードロール接続は、通常のデバイスチェックに従います。Serve トラフィックでも明示的な共有シークレット認証情報を要求したい場合は、`gateway.auth.allowTailscale: false` を設定します。その後、`gateway.auth.mode: "token"` または `"password"` を使用します。 - その非同期 Serve ID パスでは、同じクライアント IP と認証スコープに対する認証失敗の試行は、レート制限の書き込み前に直列化されます。そのため、同じブラウザーからの同時の不正リトライでは、2 つの単純な不一致が並行して競合する代わりに、2 番目のリクエストで `retry later` が表示されることがあります。 + その非同期 Serve ID パスでは、同じクライアント IP と認証スコープの失敗した認証試行は、レート制限の書き込み前に直列化されます。そのため、同じブラウザーからの同時の不正な再試行では、2 つの単純な不一致が並列に競合する代わりに、2 回目のリクエストで `retry later` が表示されることがあります。 - トークンなしの Serve 認証は、Gateway ホストが信頼されていることを前提とします。そのホスト上で信頼できないローカルコードが実行される可能性がある場合は、トークン/パスワード認証を要求してください。 + トークンなしの Serve 認証は、gateway ホストが信頼されていることを前提にします。そのホスト上で信頼できないローカルコードが実行される可能性がある場合は、トークン/パスワード認証を要求してください。 @@ -299,7 +299,7 @@ Web Push は、iOS APNS リレーパス（リレー backed push については openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` - 次に開きます。 + 次に開く: - `http://:18789/`（または設定済みの `gateway.controlUi.basePath`） @@ -310,13 +310,13 @@ Web Push は、iOS APNS リレーパス（リレー backed push については ## 安全でない HTTP -プレーン HTTP（`http://` または `http://`）でダッシュボードを開くと、ブラウザーは**非セキュアコンテキスト**で実行され、WebCrypto をブロックします。デフォルトでは、OpenClaw はデバイス ID のない Control UI 接続を**ブロック**します。 +プレーン HTTP（`http://` または `http://`）でダッシュボードを開くと、ブラウザーは **非セキュアコンテキスト** で実行され、WebCrypto をブロックします。デフォルトでは、OpenClaw はデバイス ID のない Control UI 接続を **ブロック** します。 -文書化された例外: +記載されている例外: -- `gateway.controlUi.allowInsecureAuth=true` による localhost 限定の安全でない HTTP 互換性 -- `gateway.auth.mode: "trusted-proxy"` 経由でのオペレーター Control UI 認証の成功 -- 緊急時用の `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- `gateway.controlUi.allowInsecureAuth=true` による localhost のみの安全でない HTTP 互換性 +- `gateway.auth.mode: "trusted-proxy"` 経由で成功したオペレーター Control UI 認証 +- 緊急用の `gateway.controlUi.dangerouslyDisableDeviceAuth=true` **推奨される修正:** HTTPS (Tailscale Serve) を使うか、UI をローカルで開きます。 @@ -335,11 +335,11 @@ Web Push は、iOS APNS リレーパス（リレー backed push については } ``` - `allowInsecureAuth` はローカル互換性用のトグルにすぎません。 + `allowInsecureAuth` はローカル互換性トグルのみです。 - 非セキュアな HTTP コンテキストで、localhost の Control UI セッションがデバイス ID なしで続行できるようにします。 - ペアリングチェックはバイパスしません。 - - リモート (localhost 以外) のデバイス ID 要件は緩和しません。 + - リモート (非 localhost) のデバイス ID 要件は緩和しません。 @@ -354,43 +354,53 @@ Web Push は、iOS APNS リレーパス（リレー backed push については ``` - `dangerouslyDisableDeviceAuth` は Control UI のデバイス ID チェックを無効化し、重大なセキュリティ低下を招きます。緊急使用後は速やかに元に戻してください。 + `dangerouslyDisableDeviceAuth` は Control UI のデバイス ID チェックを無効化し、深刻なセキュリティ低下を招きます。緊急使用後は速やかに元に戻してください。 - - - 信頼済みプロキシ認証に成功すると、デバイス ID なしで **operator** Control UI セッションを許可できます。 - - これは node-role Control UI セッションには適用されません。 - - 同一ホストのループバックリバースプロキシでも、信頼済みプロキシ認証の条件は満たされません。[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth) を参照してください。 + + - 信頼済みプロキシ認証に成功すると、デバイス ID なしで **オペレーター** Control UI セッションを許可できます。 + - これはノードロールの Control UI セッションには適用されません。 + - 同一ホストのループバックリバースプロキシでも、信頼済みプロキシ認証は満たしません。[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth)を参照してください。 -HTTPS セットアップのガイダンスについては [Tailscale](/ja-JP/gateway/tailscale) を参照してください。 +HTTPS セットアップのガイダンスについては、[Tailscale](/ja-JP/gateway/tailscale) を参照してください。 ## コンテンツセキュリティポリシー -Control UI には厳格な `img-src` ポリシーが含まれています。許可されるのは **同一オリジン** のアセット、`data:` URL、ローカルで生成された `blob:` URL のみです。リモートの `http(s)` およびプロトコル相対の画像 URL はブラウザによって拒否され、ネットワークフェッチは発生しません。 +Control UI には厳格な `img-src` ポリシーが同梱されています。許可されるのは、**同一オリジン** のアセット、`data:` URL、ローカルで生成された `blob:` URL のみです。リモートの `http(s)` およびプロトコル相対の画像 URL はブラウザーによって拒否され、ネットワーク取得は発生しません。 -実際には、これは次を意味します。 +実際には、これは次のことを意味します。 -- 相対パス配下で提供されるアバターや画像 (例: `/avatars/`) は引き続き表示されます。UI がフェッチしてローカルの `blob:` URL に変換する、認証付きアバタールートも含まれます。 +- 相対パス (たとえば `/avatars/`) で提供されるアバターや画像は引き続き表示されます。UI が取得してローカルの `blob:` URL に変換する、認証付きアバタールートも含まれます。 - インラインの `data:image/...` URL は引き続き表示されます (プロトコル内ペイロードに便利です)。 - Control UI によって作成されたローカルの `blob:` URL は引き続き表示されます。 -- チャネルメタデータから出力されたリモートアバター URL は、Control UI のアバターヘルパーで取り除かれ、組み込みのロゴ/バッジに置き換えられます。そのため、侵害された、または悪意のあるチャネルがオペレーターのブラウザから任意のリモート画像フェッチを強制することはできません。 +- チャンネルメタデータが出力するリモートアバター URL は、Control UI のアバターヘルパーで取り除かれ、組み込みのロゴ/バッジに置き換えられます。そのため、侵害された、または悪意のあるチャンネルが、オペレーターのブラウザーから任意のリモート画像取得を強制することはできません。 -この動作を得るために変更は不要です。常に有効で、設定変更はできません。 +この動作を得るために変更は不要です。常に有効で、設定はできません。 ## アバタールート認証 Gateway 認証が設定されている場合、Control UI のアバターエンドポイントには API の他の部分と同じ Gateway トークンが必要です。 -- `GET /avatar/` は認証済みの呼び出し元にのみアバター画像を返します。`GET /avatar/?meta=1` は同じルールでアバターメタデータを返します。 -- どちらのルートへの未認証リクエストも拒否されます (兄弟の assistant-media ルートと同様です)。これにより、他の部分では保護されているホストで、アバタールートからエージェント ID が漏れることを防ぎます。 -- Control UI 自体はアバターをフェッチするときに Gateway トークンを bearer ヘッダーとして転送し、認証済みの blob URL を使うため、画像はダッシュボード内で引き続き表示されます。 +- `GET /avatar/` は認証済み呼び出し元にのみアバター画像を返します。`GET /avatar/?meta=1` は同じルールでアバターメタデータを返します。 +- どちらのルートへの未認証リクエストも拒否されます (隣接するアシスタントメディアルートと同じです)。これにより、それ以外は保護されているホストで、アバタールートがエージェント ID を漏らすことを防ぎます。 +- Control UI 自体は、アバター取得時に Gateway トークンを bearer ヘッダーとして転送し、認証済みの blob URL を使うため、画像はダッシュボードで引き続き表示されます。 Gateway 認証を無効化した場合 (共有ホストでは非推奨)、Gateway の他の部分と同様に、アバタールートも未認証になります。 +## アシスタントメディアルート認証 + +Gateway 認証が設定されている場合、アシスタントのローカルメディアプレビューは 2 段階のルートを使用します。 + +- `GET /__openclaw__/assistant-media?meta=1&source=` には通常の Control UI オペレーター認証が必要です。ブラウザーは可用性を確認するとき、Gateway トークンを bearer ヘッダーとして送信します。 +- 成功したメタデータレスポンスには、その正確なソースパスにスコープされた短命の `mediaTicket` が含まれます。 +- ブラウザーでレンダリングされる画像、音声、動画、ドキュメントの URL は、有効な Gateway トークンやパスワードの代わりに `mediaTicket=` を使用します。チケットはすぐに期限切れになり、別のソースを認可することはできません。 + +これにより、再利用可能な Gateway 認証情報を可視のメディア URL に入れずに、通常のメディアレンダリングとブラウザー標準のメディア要素との互換性を保てます。 + ## UI のビルド Gateway は `dist/control-ui` から静的ファイルを提供します。次でビルドします。 @@ -399,7 +409,7 @@ Gateway は `dist/control-ui` から静的ファイルを提供します。次 pnpm ui:build ``` -任意の絶対ベース (固定アセット URL を使いたい場合): +任意の絶対ベース (固定アセット URL が必要な場合): ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build @@ -411,11 +421,11 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build pnpm ui:dev ``` -その後、UI を Gateway の WS URL (例: `ws://127.0.0.1:18789`) に向けます。 +その後、UI に Gateway WS URL (例: `ws://127.0.0.1:18789`) を指定します。 ## デバッグ/テスト: 開発サーバー + リモート Gateway -Control UI は静的ファイルです。WebSocket ターゲットは設定可能で、HTTP オリジンとは異なる場所にできます。これは、Vite 開発サーバーをローカルで使い、Gateway を別の場所で実行したい場合に便利です。 +Control UI は静的ファイルです。WebSocket ターゲットは設定可能で、HTTP オリジンと異なっていてもかまいません。ローカルでは Vite 開発サーバーを使い、Gateway は別の場所で実行したい場合に便利です。 @@ -428,7 +438,7 @@ Control UI は静的ファイルです。WebSocket ターゲットは設定可 http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` - 任意の一回限りの認証 (必要な場合): + 任意の 1 回限りの認証 (必要な場合): ```text http://localhost:5173/?gatewayUrl=wss%3A%2F%2F%3A18789#token= @@ -438,18 +448,18 @@ Control UI は静的ファイルです。WebSocket ターゲットは設定可 - + - `gatewayUrl` は読み込み後に localStorage に保存され、URL から削除されます。 - - `gatewayUrl` 経由で完全な `ws://` または `wss://` エンドポイントを渡す場合は、ブラウザがクエリ文字列を正しく解析できるように `gatewayUrl` の値を URL エンコードしてください。 - - 可能な限り、`token` は URL フラグメント (`#token=...`) 経由で渡してください。フラグメントはサーバーに送信されないため、リクエストログや Referer への漏えいを避けられます。従来の `?token=` クエリパラメータも互換性のために一度だけ取り込まれますが、フォールバックとしてのみ使われ、ブートストラップ直後に取り除かれます。 + - `gatewayUrl` で完全な `ws://` または `wss://` エンドポイントを渡す場合は、ブラウザーがクエリ文字列を正しく解析できるように `gatewayUrl` の値を URL エンコードしてください。 + - `token` は可能な限り URL フラグメント (`#token=...`) で渡してください。フラグメントはサーバーに送信されないため、リクエストログや Referer からの漏えいを避けられます。従来の `?token=` クエリパラメーターも互換性のために一度だけ取り込まれますが、フォールバックとしてのみ扱われ、ブートストラップ直後に削除されます。 - `password` はメモリ内にのみ保持されます。 - `gatewayUrl` が設定されている場合、UI は設定や環境の認証情報にフォールバックしません。`token` (または `password`) を明示的に指定してください。明示的な認証情報がない場合はエラーです。 - - Gateway が TLS (Tailscale Serve、HTTPS プロキシなど) の背後にある場合は `wss://` を使用してください。 - - `gatewayUrl` はクリックジャッキングを防ぐため、トップレベルウィンドウ (埋め込みではない) でのみ受け付けられます。 + - Gateway が TLS の背後にある場合 (Tailscale Serve、HTTPS プロキシなど) は `wss://` を使用してください。 + - `gatewayUrl` は、クリックジャッキングを防ぐため、トップレベルウィンドウ (埋め込みではない) でのみ受け付けられます。 - 非ループバックの Control UI デプロイでは、`gateway.controlUi.allowedOrigins` を明示的に設定する必要があります (完全なオリジン)。これにはリモート開発セットアップも含まれます。 - - Gateway の起動時に、有効な実行時の bind と port から `http://localhost:` や `http://127.0.0.1:` などのローカルオリジンがシードされる場合がありますが、リモートブラウザのオリジンには引き続き明示的なエントリが必要です。 - - 厳密に管理されたローカルテストを除き、`gateway.controlUi.allowedOrigins: ["*"]` は使用しないでください。これは任意のブラウザオリジンを許可するという意味であり、「現在使用しているホストに一致させる」という意味ではありません。 - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` は Host ヘッダーのオリジンフォールバックモードを有効化しますが、危険なセキュリティモードです。 + - Gateway の起動時に、有効なランタイムのバインドとポートから `http://localhost:` や `http://127.0.0.1:` などのローカルオリジンがシードされる場合がありますが、リモートブラウザーのオリジンには引き続き明示的なエントリが必要です。 + - 厳密に制御されたローカルテストを除き、`gateway.controlUi.allowedOrigins: ["*"]` は使用しないでください。これは「使用中のホストに一致させる」ではなく、任意のブラウザーオリジンを許可することを意味します。 + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` は Host ヘッダーオリジンフォールバックモードを有効にしますが、危険なセキュリティモードです。 @@ -466,11 +476,11 @@ Control UI は静的ファイルです。WebSocket ターゲットは設定可 } ``` -リモートアクセスセットアップの詳細: [リモートアクセス](/ja-JP/gateway/remote)。 +リモートアクセスのセットアップ詳細: [リモートアクセス](/ja-JP/gateway/remote)。 ## 関連 - [ダッシュボード](/ja-JP/web/dashboard) — Gateway ダッシュボード -- [ヘルスチェック](/ja-JP/gateway/health) — Gateway ヘルスモニタリング +- [ヘルスチェック](/ja-JP/gateway/health) — Gateway ヘルス監視 - [TUI](/ja-JP/web/tui) — ターミナルユーザーインターフェイス -- [WebChat](/ja-JP/web/webchat) — ブラウザベースのチャットインターフェイス +- [WebChat](/ja-JP/web/webchat) — ブラウザーベースのチャットインターフェイス