chore(i18n): refresh ja-JP translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
f23885d712
commit
db5fd72cb8
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- BlueBubbles チャンネルの設定
|
||||
- BlueBubbles チャネルの設定
|
||||
- Webhook ペアリングのトラブルシューティング
|
||||
- macOSでiMessageを設定する
|
||||
- macOS で iMessage を設定する
|
||||
sidebarTitle: BlueBubbles
|
||||
summary: BlueBubbles macOSサーバー経由のiMessage（RESTでの送受信、入力中表示、リアクション、ペアリング、高度なアクション）。
|
||||
summary: BlueBubbles macOS サーバー経由の iMessage（REST による送受信、入力中表示、リアクション、ペアリング、高度なアクション）。
|
||||
title: BlueBubbles
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T04:48:35Z"
|
||||
generated_at: "2026-05-04T02:21:51Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 499cc2a46db6e0eddfb897e96ec4b3e4a39ba9f2f6da8e7485c1c46562de4145
|
||||
source_hash: 78a054da0c7c32b161997acd05914896259dd1a050e736a4c9e438a452ab6a51
|
||||
source_path: channels/bluebubbles.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
ステータス: HTTP 経由で BlueBubbles macOS サーバーと通信するバンドル済み Plugin。レガシーの imsg チャネルと比べて API が豊富でセットアップが簡単なため、**iMessage 連携に推奨**されます。
|
||||
ステータス: HTTP 経由で BlueBubbles macOS サーバーと通信するバンドル済み Plugin。従来の imsg チャンネルと比べて API が充実しており設定も簡単なため、**iMessage 統合に推奨**されます。
|
||||
|
||||
<Note>
|
||||
現在の OpenClaw リリースには BlueBubbles がバンドルされているため、通常のパッケージ版ビルドでは別途 `openclaw plugins install` 手順は不要です。
|
||||
@ -23,27 +23,27 @@ x-i18n:
|
||||
|
||||
## 概要
|
||||
|
||||
- BlueBubbles ヘルパーアプリ ([bluebubbles.app](https://bluebubbles.app)) を介して macOS 上で動作します。
|
||||
- 推奨/テスト済み: macOS Sequoia (15)。macOS Tahoe (26) でも動作します。ただし Tahoe では現在、編集が壊れており、グループアイコンの更新は成功と報告されても同期されないことがあります。
|
||||
- OpenClaw は REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`) を通じて通信します。
|
||||
- 受信メッセージは Webhook 経由で届きます。返信の送信、入力中インジケーター、開封確認、タップバックは REST 呼び出しです。
|
||||
- 添付ファイルとステッカーは受信メディアとして取り込まれます (可能な場合はエージェントに公開されます)。
|
||||
- MP3 または CAF 音声を合成する Auto-TTS 返信は、通常のファイル添付ではなく iMessage のボイスメモ吹き出しとして配信されます。
|
||||
- ペアリング/許可リストは他のチャネルと同じように機能します (`/channels/pairing` など)。`channels.bluebubbles.allowFrom` + ペアリングコードを使います。
|
||||
- リアクションは Slack/Telegram と同様にシステムイベントとして公開されるため、エージェントは返信前にそれらを「メンション」できます。
|
||||
- 高度な機能: 編集、送信取り消し、返信スレッド化、メッセージエフェクト、グループ管理。
|
||||
- BlueBubbles ヘルパーアプリ（[bluebubbles.app](https://bluebubbles.app)）を介して macOS 上で動作します。
|
||||
- 推奨/テスト済み: macOS Sequoia (15)。macOS Tahoe (26) でも動作しますが、Tahoe では現在編集が壊れており、グループアイコンの更新は成功と報告されても同期されない場合があります。
|
||||
- OpenClaw は REST API（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）を通じて通信します。
|
||||
- 受信メッセージは Webhook 経由で届きます。送信返信、入力中インジケーター、既読通知、tapback は REST 呼び出しです。
|
||||
- 添付ファイルとステッカーは受信メディアとして取り込まれます（可能な場合はエージェントにも公開されます）。
|
||||
- MP3 または CAF 音声を合成する自動 TTS 返信は、通常のファイル添付ではなく iMessage のボイスメモバブルとして配信されます。
|
||||
- ペアリング/許可リストは他のチャンネル（`/channels/pairing` など）と同じように動作し、`channels.bluebubbles.allowFrom` + ペアリングコードを使用します。
|
||||
- リアクションは Slack/Telegram と同様にシステムイベントとして公開されるため、エージェントは返信前にそれらに「言及」できます。
|
||||
- 高度な機能: 編集、送信取り消し、返信スレッド、メッセージエフェクト、グループ管理。
|
||||
|
||||
## クイックスタート
|
||||
|
||||
<Steps>
|
||||
<Step title="BlueBubbles をインストールする">
|
||||
Mac に BlueBubbles サーバーをインストールします ([bluebubbles.app/install](https://bluebubbles.app/install) の手順に従ってください)。
|
||||
<Step title="Install BlueBubbles">
|
||||
Mac に BlueBubbles サーバーをインストールします（[bluebubbles.app/install](https://bluebubbles.app/install) の手順に従ってください）。
|
||||
</Step>
|
||||
<Step title="Web API を有効にする">
|
||||
<Step title="Enable the web API">
|
||||
BlueBubbles 設定で Web API を有効にし、パスワードを設定します。
|
||||
</Step>
|
||||
<Step title="OpenClaw を設定する">
|
||||
`openclaw onboard` を実行して BlueBubbles を選択するか、手動で設定します:
|
||||
<Step title="Configure OpenClaw">
|
||||
`openclaw onboard` を実行して BlueBubbles を選択するか、手動で設定します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -59,30 +59,30 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Webhook を Gateway に向ける">
|
||||
BlueBubbles Webhook を自分の Gateway に向けます (例: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`)。
|
||||
<Step title="Point webhooks at the gateway">
|
||||
BlueBubbles Webhook を Gateway に向けます（例: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）。
|
||||
</Step>
|
||||
<Step title="Gateway を起動する">
|
||||
Gateway を起動します。Gateway は Webhook ハンドラーを登録し、ペアリングを開始します。
|
||||
<Step title="Start the gateway">
|
||||
Gateway を起動します。Webhook ハンドラーが登録され、ペアリングが開始されます。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
**セキュリティ**
|
||||
|
||||
- Webhook パスワードを常に設定してください。
|
||||
- Webhook 認証は常に必須です。OpenClaw は、`channels.bluebubbles.password` に一致する password/guid (たとえば `?password=<password>` または `x-password`) を含まない BlueBubbles Webhook リクエストを、loopback/プロキシ構成に関係なく拒否します。
|
||||
- 必ず Webhook パスワードを設定してください。
|
||||
- Webhook 認証は常に必須です。OpenClaw は、local loopback/プロキシのトポロジに関係なく、`channels.bluebubbles.password` と一致する password/guid（例: `?password=<password>` または `x-password`）が含まれていない BlueBubbles Webhook リクエストを拒否します。
|
||||
- パスワード認証は、Webhook 本文全体を読み取り/解析する前にチェックされます。
|
||||
|
||||
</Warning>
|
||||
|
||||
## Messages.app を稼働状態に保つ (VM / ヘッドレス構成)
|
||||
## Messages.app を生存させる（VM / ヘッドレス構成）
|
||||
|
||||
一部の macOS VM / 常時稼働構成では、Messages.app が「アイドル」状態になり、アプリを開くかフォアグラウンドにするまで受信イベントが停止することがあります。簡単な回避策は、AppleScript + LaunchAgent を使って **5 分ごとに Messages を起こす**ことです。
|
||||
一部の macOS VM / 常時稼働構成では、Messages.app が「アイドル」状態になることがあります（アプリを開く/前面に出すまで受信イベントが停止します）。簡単な回避策は、AppleScript + LaunchAgent を使って **5 分ごとに Messages を刺激する**ことです。
|
||||
|
||||
<Steps>
|
||||
<Step title="AppleScript を保存する">
|
||||
これを `~/Scripts/poke-messages.scpt` として保存します:
|
||||
<Step title="Save the AppleScript">
|
||||
これを `~/Scripts/poke-messages.scpt` として保存します。
|
||||
|
||||
```applescript
|
||||
try
|
||||
@ -100,8 +100,8 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="LaunchAgent をインストールする">
|
||||
これを `~/Library/LaunchAgents/com.user.poke-messages.plist` として保存します:
|
||||
<Step title="Install a LaunchAgent">
|
||||
これを `~/Library/LaunchAgents/com.user.poke-messages.plist` として保存します。
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
@ -132,10 +132,10 @@ x-i18n:
|
||||
</plist>
|
||||
```
|
||||
|
||||
これは **300 秒ごと**および**ログイン時**に実行されます。初回実行時に macOS の **Automation** プロンプト (`osascript` → Messages) が表示されることがあります。LaunchAgent を実行している同じユーザーセッションで許可します。
|
||||
これは **300 秒ごと**、および**ログイン時**に実行されます。初回実行時に macOS の **Automation** プロンプト（`osascript` → Messages）が表示される場合があります。LaunchAgent を実行する同じユーザーセッションで承認してください。
|
||||
|
||||
</Step>
|
||||
<Step title="読み込む">
|
||||
<Step title="Load it">
|
||||
```bash
|
||||
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
|
||||
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
|
||||
@ -145,62 +145,62 @@ x-i18n:
|
||||
|
||||
## オンボーディング
|
||||
|
||||
BlueBubbles は対話型オンボーディングで利用できます:
|
||||
BlueBubbles は対話型オンボーディングで利用できます。
|
||||
|
||||
```
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
ウィザードは次の項目を尋ねます:
|
||||
ウィザードでは次の入力を求められます。
|
||||
|
||||
<ParamField path="サーバー URL" type="string" required>
|
||||
BlueBubbles サーバーのアドレス (例: `http://192.168.1.100:1234`)。
|
||||
<ParamField path="Server URL" type="string" required>
|
||||
BlueBubbles サーバーのアドレス（例: `http://192.168.1.100:1234`）。
|
||||
</ParamField>
|
||||
<ParamField path="パスワード" type="string" required>
|
||||
<ParamField path="Password" type="string" required>
|
||||
BlueBubbles Server 設定の API パスワード。
|
||||
</ParamField>
|
||||
<ParamField path="Webhook パス" type="string" default="/bluebubbles-webhook">
|
||||
Webhook エンドポイントのパス。
|
||||
<ParamField path="Webhook path" type="string" default="/bluebubbles-webhook">
|
||||
Webhook エンドポイントパス。
|
||||
</ParamField>
|
||||
<ParamField path="DM ポリシー" type="string">
|
||||
`pairing`, `allowlist`, `open`, または `disabled`。
|
||||
<ParamField path="DM policy" type="string">
|
||||
`pairing`、`allowlist`、`open`、または `disabled`。
|
||||
</ParamField>
|
||||
<ParamField path="許可リスト" type="string[]">
|
||||
<ParamField path="Allow list" type="string[]">
|
||||
電話番号、メールアドレス、またはチャットターゲット。
|
||||
</ParamField>
|
||||
|
||||
CLI から BlueBubbles を追加することもできます:
|
||||
CLI 経由で BlueBubbles を追加することもできます。
|
||||
|
||||
```
|
||||
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
|
||||
```
|
||||
|
||||
## アクセス制御 (DM + グループ)
|
||||
## アクセス制御（DM + グループ）
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM">
|
||||
<Tab title="DMs">
|
||||
- デフォルト: `channels.bluebubbles.dmPolicy = "pairing"`。
|
||||
- 不明な送信者にはペアリングコードが送られます。承認されるまでメッセージは無視されます (コードは 1 時間後に期限切れになります)。
|
||||
- 次で承認します:
|
||||
- 不明な送信者にはペアリングコードが送信されます。承認されるまでメッセージは無視されます（コードは 1 時間後に期限切れになります）。
|
||||
- 承認方法:
|
||||
- `openclaw pairing list bluebubbles`
|
||||
- `openclaw pairing approve bluebubbles <CODE>`
|
||||
- ペアリングはデフォルトのトークン交換方式です。詳細: [ペアリング](/ja-JP/channels/pairing)
|
||||
- ペアリングはデフォルトのトークン交換です。詳細: [ペアリング](/ja-JP/channels/pairing)
|
||||
|
||||
</Tab>
|
||||
<Tab title="グループ">
|
||||
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (デフォルト: `allowlist`)。
|
||||
- `channels.bluebubbles.groupAllowFrom` は、`allowlist` が設定されている場合にグループで誰がトリガーできるかを制御します。
|
||||
<Tab title="Groups">
|
||||
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled`（デフォルト: `allowlist`）。
|
||||
- `channels.bluebubbles.groupAllowFrom` は、`allowlist` が設定されている場合にグループ内で誰がトリガーできるかを制御します。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 連絡先名の補完 (macOS、任意)
|
||||
### 連絡先名の補完（macOS、任意）
|
||||
|
||||
BlueBubbles のグループ Webhook には、多くの場合、生の参加者アドレスだけが含まれます。`GroupMembers` コンテキストにローカルの連絡先名を表示したい場合は、macOS でローカルの連絡先による補完を有効にできます:
|
||||
BlueBubbles のグループ Webhook には、多くの場合、生の参加者アドレスしか含まれません。`GroupMembers` コンテキストに代わりにローカルの連絡先名を表示したい場合は、macOS 上でローカルの連絡先補完を有効化できます。
|
||||
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` で検索を有効にします。デフォルト: `false`。
|
||||
- 検索は、グループアクセス、コマンド認可、メンションゲーティングがメッセージの通過を許可した後にのみ実行されます。
|
||||
- 名前のない電話番号参加者だけが補完されます。
|
||||
- 検索は、グループアクセス、コマンド認可、メンションゲートによってメッセージの通過が許可された後にのみ実行されます。
|
||||
- 名前のない電話番号参加者のみが補完されます。
|
||||
- ローカル一致が見つからない場合は、生の電話番号がフォールバックとして残ります。
|
||||
|
||||
```json5
|
||||
@ -213,15 +213,15 @@ BlueBubbles のグループ Webhook には、多くの場合、生の参加者
|
||||
}
|
||||
```
|
||||
|
||||
### メンションゲーティング (グループ)
|
||||
### メンションゲート（グループ）
|
||||
|
||||
BlueBubbles はグループチャット向けに、iMessage/WhatsApp の動作に合わせたメンションゲーティングをサポートします:
|
||||
BlueBubbles は、iMessage/WhatsApp の挙動に合わせたグループチャットのメンションゲートをサポートします。
|
||||
|
||||
- メンションの検出には `agents.list[].groupChat.mentionPatterns` (または `messages.groupChat.mentionPatterns`) を使います。
|
||||
- メンション検出には `agents.list[].groupChat.mentionPatterns`（または `messages.groupChat.mentionPatterns`）を使用します。
|
||||
- グループで `requireMention` が有効な場合、エージェントはメンションされたときだけ応答します。
|
||||
- 許可された送信者からの制御コマンドは、メンションゲーティングをバイパスします。
|
||||
- 認可済み送信者からの制御コマンドはメンションゲートを迂回します。
|
||||
|
||||
グループ単位の設定:
|
||||
グループごとの設定:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -238,15 +238,15 @@ BlueBubbles はグループチャット向けに、iMessage/WhatsApp の動作
|
||||
}
|
||||
```
|
||||
|
||||
### コマンドゲーティング
|
||||
### コマンドゲート
|
||||
|
||||
- 制御コマンド (例: `/config`, `/model`) には認可が必要です。
|
||||
- コマンド認可の判定には `allowFrom` と `groupAllowFrom` を使います。
|
||||
- 許可された送信者は、グループでメンションしなくても制御コマンドを実行できます。
|
||||
- 制御コマンド（例: `/config`、`/model`）には認可が必要です。
|
||||
- コマンド認可の判定には `allowFrom` と `groupAllowFrom` を使用します。
|
||||
- 認可済み送信者は、グループ内でメンションしなくても制御コマンドを実行できます。
|
||||
|
||||
### グループ単位のシステムプロンプト
|
||||
### グループごとのシステムプロンプト
|
||||
|
||||
`channels.bluebubbles.groups.*` 配下の各エントリは、任意の `systemPrompt` 文字列を受け入れます。この値は、そのグループ内のメッセージを処理するすべてのターンでエージェントのシステムプロンプトに注入されるため、エージェントのプロンプトを編集せずにグループ単位のペルソナや振る舞いのルールを設定できます:
|
||||
`channels.bluebubbles.groups.*` 配下の各エントリは任意の `systemPrompt` 文字列を受け付けます。この値は、そのグループのメッセージを処理する各ターンでエージェントのシステムプロンプトに注入されるため、エージェントプロンプトを編集せずに、グループごとのペルソナや動作ルールを設定できます。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -262,11 +262,11 @@ BlueBubbles はグループチャット向けに、iMessage/WhatsApp の動作
|
||||
}
|
||||
```
|
||||
|
||||
キーは、BlueBubbles がグループに対して報告する `chatGuid` / `chatIdentifier` / 数値の `chatId` のいずれかに一致します。また、`"*"` ワイルドカードエントリは、完全一致のないすべてのグループにデフォルトを提供します (`requireMention` やグループ単位のツールポリシーと同じパターン)。完全一致は常にワイルドカードより優先されます。DM はこのフィールドを無視します。代わりに、エージェントレベルまたはアカウントレベルのプロンプトカスタマイズを使ってください。
|
||||
キーは、BlueBubbles がグループについて報告する `chatGuid` / `chatIdentifier` / 数値 `chatId` のいずれかと一致します。また `"*"` ワイルドカードエントリは、完全一致がないすべてのグループにデフォルトを提供します（`requireMention` およびグループごとのツールポリシーと同じパターンです）。完全一致は常にワイルドカードより優先されます。DM はこのフィールドを無視します。代わりにエージェントレベルまたはアカウントレベルのプロンプトカスタマイズを使用してください。
|
||||
|
||||
#### 実例: スレッド返信とタップバックリアクション (Private API)
|
||||
#### 実例: スレッド返信と tapback リアクション（Private API）
|
||||
|
||||
BlueBubbles Private API が有効な場合、受信メッセージには短いメッセージ ID (たとえば `[[reply_to:5]]`) が付き、エージェントは `action=reply` を呼び出して特定のメッセージにスレッド返信したり、`action=react` でタップバックを付けたりできます。グループ単位の `systemPrompt` は、エージェントに適切なツールを選ばせ続ける確実な方法です:
|
||||
BlueBubbles Private API を有効にすると、受信メッセージには短いメッセージ ID（例: `[[reply_to:5]]`）が付き、エージェントは `action=reply` を呼び出して特定メッセージにスレッド返信したり、`action=react` を呼び出して tapback を付けたりできます。グループごとの `systemPrompt` は、エージェントに適切なツールを選ばせるための信頼性の高い方法です。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -274,15 +274,7 @@ BlueBubbles Private API が有効な場合、受信メッセージには短い
|
||||
bluebubbles: {
|
||||
groups: {
|
||||
"iMessage;+;chat-family": {
|
||||
systemPrompt: [
|
||||
"When replying in this group, always call action=reply with the",
|
||||
"[[reply_to:N]] messageId from context so your response threads",
|
||||
"under the triggering message. Never send a new unlinked message.",
|
||||
"",
|
||||
"For short acknowledgements ('ok', 'got it', 'on it'), use",
|
||||
"action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓)",
|
||||
"instead of sending a text reply.",
|
||||
].join(" "),
|
||||
systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -290,29 +282,29 @@ BlueBubbles Private API が有効な場合、受信メッセージには短い
|
||||
}
|
||||
```
|
||||
|
||||
タップバックリアクションとスレッド返信はいずれも BlueBubbles Private API が必要です。基礎となる仕組みについては、[高度なアクション](#advanced-actions) と [メッセージ ID](#message-ids-short-vs-full) を参照してください。
|
||||
tapback リアクションとスレッド返信はいずれも BlueBubbles Private API が必要です。基盤となる仕組みについては、[高度なアクション](#advanced-actions) と [メッセージ ID](#message-ids-short-vs-full) を参照してください。
|
||||
|
||||
## ACP 会話バインディング
|
||||
|
||||
BlueBubbles チャットは、トランスポート層を変更せずに永続的な ACP ワークスペースへ変換できます。
|
||||
BlueBubbles チャットは、トランスポート層を変更せずに永続的な ACP ワークスペースに変換できます。
|
||||
|
||||
オペレーター向けの簡単な流れ:
|
||||
高速なオペレーターフロー:
|
||||
|
||||
- DM または許可されたグループチャット内で `/acp spawn codex --bind here` を実行します。
|
||||
- 以後、同じ BlueBubbles 会話内のメッセージは、生成された ACP セッションにルーティングされます。
|
||||
- DM または許可済みグループチャット内で `/acp spawn codex --bind here` を実行します。
|
||||
- 同じ BlueBubbles 会話内の以後のメッセージは、生成された ACP セッションにルーティングされます。
|
||||
- `/new` と `/reset` は、同じバインド済み ACP セッションをその場でリセットします。
|
||||
- `/acp close` は ACP セッションを閉じ、バインディングを削除します。
|
||||
|
||||
設定済みの永続バインディングも、トップレベルの `bindings[]` エントリで `type: "acp"` と `match.channel: "bluebubbles"` を指定することでサポートされます。
|
||||
設定済みの永続バインディングは、`type: "acp"` と `match.channel: "bluebubbles"` を持つトップレベルの `bindings[]` エントリでもサポートされます。
|
||||
|
||||
`match.peer.id` には、サポートされている任意の BlueBubbles ターゲット形式を使用できます:
|
||||
`match.peer.id` には、サポートされている任意の BlueBubbles ターゲット形式を使用できます。
|
||||
|
||||
- `+15555550123` や `user@example.com` などの正規化された DM ハンドル
|
||||
- `chat_id:<id>`
|
||||
- `chat_guid:<guid>`
|
||||
- `chat_identifier:<identifier>`
|
||||
|
||||
安定したグループバインディングには、`chat_id:*` または `chat_identifier:*` を優先してください。
|
||||
安定したグループバインディングには、`chat_id:*` または `chat_identifier:*` を推奨します。
|
||||
|
||||
例:
|
||||
|
||||
@ -344,12 +336,12 @@ BlueBubbles チャットは、トランスポート層を変更せずに永続
|
||||
}
|
||||
```
|
||||
|
||||
共有の ACP バインディング動作については、[ACP エージェント](/ja-JP/tools/acp-agents) を参照してください。
|
||||
共有 ACP バインディングの挙動については、[ACP エージェント](/ja-JP/tools/acp-agents) を参照してください。
|
||||
|
||||
## 入力中表示 + 開封確認
|
||||
## 入力中 + 既読通知
|
||||
|
||||
- **入力中インジケーター**: 応答生成の前と生成中に自動送信されます。
|
||||
- **既読通知**: `channels.bluebubbles.sendReadReceipts` によって制御されます（デフォルト: `true`）。
|
||||
- **入力中インジケーター**: 応答生成前および応答生成中に自動送信されます。
|
||||
- **既読通知**: `channels.bluebubbles.sendReadReceipts` で制御されます（デフォルト: `true`）。
|
||||
- **入力中インジケーター**: OpenClaw は入力開始イベントを送信します。BlueBubbles は送信時またはタイムアウト時に入力中状態を自動的にクリアします（DELETE による手動停止は信頼できません）。
|
||||
|
||||
```json5
|
||||
@ -364,7 +356,7 @@ BlueBubbles チャットは、トランスポート層を変更せずに永続
|
||||
|
||||
## 高度なアクション
|
||||
|
||||
BlueBubbles は、設定で有効にすると高度なメッセージアクションをサポートします。
|
||||
BlueBubbles は、設定で有効化されている場合、高度なメッセージアクションをサポートします。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -390,64 +382,64 @@ BlueBubbles は、設定で有効にすると高度なメッセージアクシ
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="利用可能なアクション">
|
||||
- **react**: Tapback リアクションを追加または削除します（`messageId`, `emoji`, `remove`）。iMessage のネイティブ Tapback セットは `love`, `like`, `dislike`, `laugh`, `emphasize`, `question` です。エージェントがそのセット外の絵文字（例: `👀`）を選択した場合、リアクションツールは `love` にフォールバックするため、リクエスト全体を失敗させずに Tapback が表示されます。設定済みの ack リアクションは引き続き厳密に検証され、不明な値ではエラーになります。
|
||||
- **edit**: 送信済みメッセージを編集します（`messageId`, `text`）。
|
||||
- **react**: Tapback リアクションを追加または削除します（`messageId`、`emoji`、`remove`）。iMessage のネイティブ Tapback セットは `love`、`like`、`dislike`、`laugh`、`emphasize`、`question` です。エージェントがそのセット外の絵文字（例: `👀`）を選んだ場合、リアクションツールは `love` にフォールバックするため、リクエスト全体を失敗させる代わりに Tapback は引き続き表示されます。設定済みの ack リアクションは引き続き厳密に検証され、不明な値ではエラーになります。
|
||||
- **edit**: 送信済みメッセージを編集します（`messageId`、`text`）。
|
||||
- **unsend**: メッセージの送信を取り消します（`messageId`）。
|
||||
- **reply**: 特定のメッセージに返信します（`messageId`, `text`, `to`）。
|
||||
- **sendWithEffect**: iMessage エフェクト付きで送信します（`text`, `to`, `effectId`）。
|
||||
- **renameGroup**: グループチャット名を変更します（`chatGuid`, `displayName`）。
|
||||
- **setGroupIcon**: グループチャットのアイコン/写真を設定します（`chatGuid`, `media`）— macOS 26 Tahoe では不安定です（API が成功を返してもアイコンが同期されないことがあります）。
|
||||
- **addParticipant**: グループに参加者を追加します（`chatGuid`, `address`）。
|
||||
- **removeParticipant**: グループから参加者を削除します（`chatGuid`, `address`）。
|
||||
- **reply**: 特定のメッセージに返信します（`messageId`、`text`、`to`）。
|
||||
- **sendWithEffect**: iMessage エフェクト付きで送信します（`text`、`to`、`effectId`）。
|
||||
- **renameGroup**: グループチャットの名前を変更します（`chatGuid`、`displayName`）。
|
||||
- **setGroupIcon**: グループチャットのアイコン/写真を設定します（`chatGuid`、`media`）— macOS 26 Tahoe では不安定です（API が成功を返しても、アイコンが同期されない場合があります）。
|
||||
- **addParticipant**: グループに誰かを追加します（`chatGuid`、`address`）。
|
||||
- **removeParticipant**: グループから誰かを削除します（`chatGuid`、`address`）。
|
||||
- **leaveGroup**: グループチャットから退出します（`chatGuid`）。
|
||||
- **upload-file**: メディア/ファイルを送信します（`to`, `buffer`, `filename`, `asVoice`）。
|
||||
- 音声メモ: iMessage の音声メッセージとして送信するには、**MP3** または **CAF** 音声で `asVoice: true` を設定します。BlueBubbles は音声メモ送信時に MP3 → CAF に変換します。
|
||||
- レガシーエイリアス: `sendAttachment` は引き続き動作しますが、正式なアクション名は `upload-file` です。
|
||||
- **upload-file**: メディア/ファイルを送信します（`to`、`buffer`、`filename`、`asVoice`）。
|
||||
- ボイスメモ: iMessage の音声メッセージとして送信するには、**MP3** または **CAF** 音声で `asVoice: true` を設定します。BlueBubbles はボイスメモ送信時に MP3 → CAF に変換します。
|
||||
- レガシーエイリアス: `sendAttachment` は引き続き動作しますが、`upload-file` が正規のアクション名です。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### メッセージ ID（短縮と完全）
|
||||
|
||||
OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例: `1`, `2`）を表示することがあります。
|
||||
OpenClaw はトークンを節約するために、_短縮_ メッセージ ID（例: `1`、`2`）を表示する場合があります。
|
||||
|
||||
- `MessageSid` / `ReplyToId` は短縮 ID の場合があります。
|
||||
- `MessageSidFull` / `ReplyToIdFull` にはプロバイダーの完全な ID が含まれます。
|
||||
- 短縮 ID はメモリ内にあります。再起動やキャッシュ削除で期限切れになることがあります。
|
||||
- `MessageSid` / `ReplyToId` には短縮 ID を指定できます。
|
||||
- `MessageSidFull` / `ReplyToIdFull` にはプロバイダーの完全 ID が含まれます。
|
||||
- 短縮 ID はメモリ内にあります。再起動またはキャッシュ退避で期限切れになることがあります。
|
||||
- アクションは短縮または完全な `messageId` を受け付けますが、短縮 ID が利用できなくなっている場合はエラーになります。
|
||||
|
||||
永続的な自動化や保存には完全な ID を使用してください。
|
||||
耐久性のある自動化や保存には完全 ID を使用してください。
|
||||
|
||||
- テンプレート: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
|
||||
- テンプレート: `{{MessageSidFull}}`、`{{ReplyToIdFull}}`
|
||||
- コンテキスト: 受信ペイロード内の `MessageSidFull` / `ReplyToIdFull`
|
||||
|
||||
テンプレート変数については [設定](/ja-JP/gateway/configuration) を参照してください。
|
||||
|
||||
<a id="coalescing-split-send-dms-command--url-in-one-composition"></a>
|
||||
|
||||
## 分割送信 DM の結合（1 回の作成でコマンド + URL）
|
||||
## 分割送信 DM の統合（1 回の入力内のコマンド + URL）
|
||||
|
||||
ユーザーが iMessage でコマンドと URL を一緒に入力した場合（例: `Dump https://example.com/article`）、Apple は送信を **2 つの個別の webhook 配信** に分割します。
|
||||
ユーザーが iMessage でコマンドと URL を一緒に入力した場合（例: `Dump https://example.com/article`）、Apple は送信を**2 つの別々の Webhook 配信**に分割します。
|
||||
|
||||
1. テキストメッセージ（`"Dump"`）。
|
||||
2. OG プレビュー画像を添付として含む URL プレビューバルーン（`"https://..."`）。
|
||||
2. URL プレビュー吹き出し（`"https://..."`）。OG プレビュー画像が添付されます。
|
||||
|
||||
ほとんどのセットアップでは、2 つの webhook は約 0.8〜2.0 秒間隔で OpenClaw に到着します。結合しない場合、エージェントはターン 1 でコマンドだけを受け取り、返信し（多くの場合「URL を送ってください」）、ターン 2 でようやく URL を認識します。その時点ではコマンドのコンテキストはすでに失われています。
|
||||
ほとんどのセットアップでは、2 つの Webhook は約 0.8〜2.0 秒差で OpenClaw に到着します。統合しない場合、エージェントは 1 ターン目でコマンドだけを受け取り、返信し（多くの場合「URL を送って」）、2 ターン目でようやく URL を見ることになります。その時点では、コマンドのコンテキストはすでに失われています。
|
||||
|
||||
`channels.bluebubbles.coalesceSameSenderDms` は、DM で連続する同一送信者の webhook を 1 つのエージェントターンにマージするようにします。グループチャットは引き続きメッセージごとにキー化されるため、複数ユーザーのターン構造が維持されます。
|
||||
`channels.bluebubbles.coalesceSameSenderDms` は、連続する同一送信者の Webhook を 1 つのエージェントターンにマージするよう DM をオプトインします。グループチャットは引き続きメッセージごとにキー付けされるため、複数ユーザーのターン構造は保持されます。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="有効にする場合">
|
||||
次の場合に有効にします。
|
||||
<Tab title="有効化する場合">
|
||||
次の場合に有効化します。
|
||||
|
||||
- 1 つのメッセージ内に `command + payload` を期待する Skills（dump、paste、save、queue など）を提供している。
|
||||
- ユーザーがコマンドと一緒に URL、画像、長いコンテンツを貼り付ける。
|
||||
- ユーザーが URL、画像、または長いコンテンツをコマンドと一緒に貼り付ける。
|
||||
- 追加される DM ターン遅延を許容できる（下記参照）。
|
||||
|
||||
次の場合は無効のままにします。
|
||||
|
||||
- 1 語の DM トリガーで最小のコマンド遅延が必要。
|
||||
- すべてのフローが、後続ペイロードなしの単発コマンドである。
|
||||
- 単語 1 つの DM トリガーで最小のコマンド遅延が必要。
|
||||
- すべてのフローがペイロード追従のない 1 回限りのコマンド。
|
||||
|
||||
</Tab>
|
||||
<Tab title="有効化">
|
||||
@ -461,7 +453,7 @@ OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例:
|
||||
}
|
||||
```
|
||||
|
||||
フラグがオンで、明示的な `messages.inbound.byChannel.bluebubbles` がない場合、デバウンスウィンドウは **2500 ms** に広がります（非結合時のデフォルトは 500 ms）。この広いウィンドウが必要です。Apple の分割送信の間隔である 0.8〜2.0 秒は、より短いデフォルトには収まりません。
|
||||
フラグがオンで、明示的な `messages.inbound.byChannel.bluebubbles` がない場合、デバウンスウィンドウは **2500 ms** に広がります（非統合時のデフォルトは 500 ms）。この広いウィンドウが必要です。Apple の分割送信間隔 0.8〜2.0 秒は、より短いデフォルトには収まりません。
|
||||
|
||||
ウィンドウを自分で調整するには:
|
||||
|
||||
@ -481,27 +473,27 @@ OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例:
|
||||
|
||||
</Tab>
|
||||
<Tab title="トレードオフ">
|
||||
- **DM 制御コマンドに遅延が追加されます。** フラグがオンの場合、DM 制御コマンドメッセージ（`Dump`, `Save` など）は、ペイロード webhook が来る可能性に備えて、ディスパッチ前にデバウンスウィンドウまで待機するようになります。グループチャットのコマンドは即時ディスパッチのままです。
|
||||
- **マージされた出力には上限があります** — マージ後のテキストは明示的な `…[truncated]` マーカー付きで 4000 文字に制限されます。添付は 20 件まで、ソースエントリは 10 件までです（それを超える場合は最初と最新が保持されます）。個々のイベントが後で MessagePoller によって再生されても重複として認識されるよう、各ソースの `messageId` は引き続き受信重複排除に到達します。
|
||||
- **オプトインで、チャンネルごとの設定です。** 他のチャンネル（Telegram, WhatsApp, Slack, …）には影響しません。
|
||||
- **DM 制御コマンドの遅延が追加されます。** フラグがオンの場合、DM 制御コマンドメッセージ（`Dump`、`Save` など）は、ペイロード Webhook が来る可能性があるため、ディスパッチ前に最大でデバウンスウィンドウまで待機するようになります。グループチャットのコマンドは即時ディスパッチのままです。
|
||||
- **マージされた出力には上限があります** — マージされたテキストは明示的な `…[truncated]` マーカー付きで 4000 文字まで、添付は 20 件まで、ソースエントリは 10 件までです（それを超える場合は最初と最新が保持されます）。各ソースの `messageId` は引き続き受信重複排除に到達するため、後から MessagePoller が個別イベントを再生しても重複として認識されます。
|
||||
- **チャンネルごとのオプトインです。** 他のチャンネル（Telegram、WhatsApp、Slack、…）には影響しません。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### シナリオとエージェントが見る内容
|
||||
|
||||
| ユーザーの作成内容 | Apple の配信 | フラグオフ（デフォルト） | フラグオン + 2500 ms ウィンドウ |
|
||||
| ユーザーの入力 | Apple の配信 | フラグオフ（デフォルト） | フラグオン + 2500 ms ウィンドウ |
|
||||
| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `Dump https://example.com`（1 回の送信） | 約 1 秒間隔の 2 webhook | 2 つのエージェントターン: 「Dump」だけ、その後 URL | 1 つのターン: マージされたテキスト `Dump https://example.com` |
|
||||
| `Save this 📎image.jpg caption`（添付 + テキスト） | 2 webhook | 2 つのターン | 1 つのターン: テキスト + 画像 |
|
||||
| `/status`（単独コマンド） | 1 webhook | 即時ディスパッチ | **ウィンドウまで待機してからディスパッチ** |
|
||||
| URL だけを貼り付け | 1 webhook | 即時ディスパッチ | 即時ディスパッチ（バケット内のエントリが 1 つだけ） |
|
||||
| テキスト + URL を意図的に別々のメッセージとして数分空けて送信 | ウィンドウ外の 2 webhook | 2 つのターン | 2 つのターン（その間にウィンドウが期限切れ） |
|
||||
| 急速な大量送信（ウィンドウ内に >10 件の小さな DM） | N webhook | N ターン | 1 つのターン、上限付き出力（最初 + 最新、テキスト/添付の上限を適用） |
|
||||
| `Dump https://example.com`（1 回の送信） | 約 1 秒差の 2 Webhook | 2 つのエージェントターン: "Dump" のみ、その後 URL | 1 ターン: マージされたテキスト `Dump https://example.com` |
|
||||
| `Save this 📎image.jpg caption`（添付 + テキスト） | 2 Webhook | 2 ターン | 1 ターン: テキスト + 画像 |
|
||||
| `/status`（単独コマンド） | 1 Webhook | 即時ディスパッチ | **最大でウィンドウまで待機してからディスパッチ** |
|
||||
| URL のみを貼り付け | 1 Webhook | 即時ディスパッチ | 即時ディスパッチ（バケット内に 1 エントリのみ） |
|
||||
| テキスト + URL を意図的に別々のメッセージとして数分差で送信 | ウィンドウ外の 2 Webhook | 2 ターン | 2 ターン（間でウィンドウが期限切れ） |
|
||||
| 短時間の大量送信（ウィンドウ内で 10 件超の小さい DM） | N Webhook | N ターン | 1 ターン、上限付き出力（最初 + 最新、テキスト/添付上限を適用） |
|
||||
|
||||
### 分割送信結合のトラブルシューティング
|
||||
### 分割送信統合のトラブルシューティング
|
||||
|
||||
フラグがオンでも分割送信が 2 つのターンとして到着する場合は、各レイヤーを確認してください。
|
||||
フラグがオンでも分割送信が 2 ターンとして届く場合は、各レイヤーを確認してください。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="設定が実際に読み込まれている">
|
||||
@ -509,33 +501,33 @@ OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例:
|
||||
grep coalesceSameSenderDms ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
その後 `openclaw gateway restart` を実行します。このフラグはデバウンサーレジストリ作成時に読み取られます。
|
||||
その後 `openclaw gateway restart` を実行します。このフラグは debouncer-registry 作成時に読み込まれます。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="セットアップに対してデバウンスウィンドウが十分広い">
|
||||
<Accordion title="デバウンスウィンドウがセットアップに対して十分広い">
|
||||
`~/Library/Logs/bluebubbles-server/main.log` にある BlueBubbles サーバーログを確認します。
|
||||
|
||||
```
|
||||
grep -E "Dispatching event to webhook" main.log | tail -20
|
||||
```
|
||||
|
||||
`"Dump"` のようなテキストディスパッチと、その後に続く `"https://..."; Attachments:` ディスパッチとの間隔を測定します。その間隔を十分にカバーできるように `messages.inbound.byChannel.bluebubbles` を引き上げます。
|
||||
`"Dump"` のようなテキストディスパッチと、その後に続く `"https://..."; Attachments:` ディスパッチの間隔を測定します。その間隔を十分にカバーできるように `messages.inbound.byChannel.bluebubbles` を増やします。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="セッション JSONL タイムスタンプ ≠ webhook 到着">
|
||||
セッションイベントのタイムスタンプ（`~/.openclaw/agents/<id>/sessions/*.jsonl`）は、Gateway がメッセージをエージェントに渡した時刻を反映しており、webhook が到着した時刻では**ありません**。`[Queued messages while agent was busy]` とタグ付けされたキュー済みの 2 通目のメッセージは、2 つ目の webhook が到着した時点で最初のターンがまだ実行中だったことを意味します。結合バケットはすでにフラッシュされていました。セッションログではなく、BB サーバーログに合わせてウィンドウを調整してください。
|
||||
<Accordion title="セッション JSONL タイムスタンプ ≠ Webhook 到着">
|
||||
セッションイベントのタイムスタンプ（`~/.openclaw/agents/<id>/sessions/*.jsonl`）は、Gateway がメッセージをエージェントへ渡した時刻を反映します。Webhook が到着した時刻では**ありません**。`[Queued messages while agent was busy]` とタグ付けされたキュー済みの 2 番目のメッセージは、2 番目の Webhook が到着した時点で 1 ターン目がまだ実行中だったことを意味します。統合バケットはすでにフラッシュ済みでした。セッションログではなく BB サーバーログに合わせてウィンドウを調整してください。
|
||||
</Accordion>
|
||||
<Accordion title="メモリ圧迫により返信ディスパッチが遅くなる">
|
||||
小さめのマシン（8 GB）では、エージェントターンに十分な時間がかかり、返信が完了する前に結合バケットがフラッシュされ、URL がキュー済みの 2 ターン目として到着することがあります。`memory_pressure` と `ps -o rss -p $(pgrep openclaw-gateway)` を確認してください。Gateway が約 500 MB RSS を超えていてコンプレッサーがアクティブな場合は、他の重いプロセスを閉じるか、より大きいホストに増強してください。
|
||||
<Accordion title="メモリ圧迫により返信ディスパッチが遅い">
|
||||
小さめのマシン（8 GB）では、エージェントターンに時間がかかり、返信完了前に統合バケットがフラッシュされ、URL がキュー済みの 2 番目のターンとして入ることがあります。`memory_pressure` と `ps -o rss -p $(pgrep openclaw-gateway)` を確認してください。Gateway が約 500 MB RSS を超えていてコンプレッサーがアクティブな場合は、他の重いプロセスを閉じるか、より大きなホストに変更してください。
|
||||
</Accordion>
|
||||
<Accordion title="返信引用送信は別経路">
|
||||
ユーザーが既存の URL バルーンへの**返信**として `Dump` をタップした場合（iMessage では Dump バブルに「1 Reply」バッジが表示されます）、URL は 2 つ目の webhook ではなく `replyToBody` に存在します。結合は適用されません。これはデバウンサーの問題ではなく、skill/prompt の問題です。
|
||||
<Accordion title="返信引用送信は別の経路">
|
||||
ユーザーが既存の URL 吹き出しへの**返信**として `Dump` をタップした場合（iMessage では Dump の吹き出しに「1 Reply」バッジが表示されます）、URL は 2 番目の Webhook ではなく `replyToBody` にあります。統合は適用されません。これはデバウンサーの関心事ではなく、Skill/プロンプトの関心事です。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## ブロックストリーミング
|
||||
|
||||
応答を単一のメッセージとして送信するか、ブロック単位でストリーミングするかを制御します。
|
||||
応答を単一メッセージとして送信するか、ブロックでストリーミングするかを制御します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -550,7 +542,7 @@ OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例:
|
||||
## メディア + 制限
|
||||
|
||||
- 受信添付ファイルはダウンロードされ、メディアキャッシュに保存されます。
|
||||
- 受信および送信メディアの上限は `channels.bluebubbles.mediaMaxMb` で設定します（デフォルト: 8 MB）。
|
||||
- 受信および送信メディアには `channels.bluebubbles.mediaMaxMb` によるメディア上限があります（デフォルト: 8 MB）。
|
||||
- 送信テキストは `channels.bluebubbles.textChunkLimit` に分割されます（デフォルト: 4000 文字）。
|
||||
|
||||
## 設定リファレンス
|
||||
@ -558,7 +550,7 @@ OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例:
|
||||
完全な設定: [設定](/ja-JP/gateway/configuration)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="接続と webhook">
|
||||
<Accordion title="接続と Webhook">
|
||||
- `channels.bluebubbles.enabled`: チャンネルを有効/無効にします。
|
||||
- `channels.bluebubbles.serverUrl`: BlueBubbles REST API ベース URL。
|
||||
- `channels.bluebubbles.password`: API パスワード。
|
||||
@ -567,33 +559,33 @@ OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例:
|
||||
</Accordion>
|
||||
<Accordion title="アクセスポリシー">
|
||||
- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled`（デフォルト: `pairing`）。
|
||||
- `channels.bluebubbles.allowFrom`: DM 許可リスト（ハンドル、メール、E.164 番号、`chat_id:*`, `chat_guid:*`）。
|
||||
- `channels.bluebubbles.allowFrom`: DM 許可リスト（ハンドル、メール、E.164 番号、`chat_id:*`、`chat_guid:*`）。
|
||||
- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled`（デフォルト: `allowlist`）。
|
||||
- `channels.bluebubbles.groupAllowFrom`: グループ送信者許可リスト。
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: macOS では、ゲート通過後に名前のないグループ参加者をローカルの連絡先から任意で補完します。デフォルト: `false`。
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: macOS では、ゲート通過後にローカルの連絡先から名前のないグループ参加者を任意で補完します。デフォルト: `false`。
|
||||
- `channels.bluebubbles.groups`: グループごとの設定（`requireMention` など）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="配信とチャンク化">
|
||||
- `channels.bluebubbles.sendReadReceipts`: 既読通知を送信します (デフォルト: `true`)。
|
||||
- `channels.bluebubbles.blockStreaming`: ブロックストリーミングを有効にします (デフォルト: `false`、ストリーミング返信に必要)。
|
||||
- `channels.bluebubbles.textChunkLimit`: 送信チャンクサイズ (文字数、デフォルト: 4000)。
|
||||
- `channels.bluebubbles.sendTimeoutMs`: `/api/v1/message/text` 経由の送信テキスト送信に対するリクエストごとのタイムアウト (ms、デフォルト: 30000)。Private API の iMessage 送信が iMessage フレームワーク内で 60 秒以上停止することがある macOS 26 環境では、たとえば `45000` や `60000` に引き上げます。プローブ、チャット検索、リアクション、編集、ヘルスチェックは現在も短い 10 秒のデフォルトを維持します。リアクションと編集への対象拡大はフォローアップとして予定されています。アカウントごとの上書き: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`。
|
||||
- `channels.bluebubbles.chunkMode`: `length` (デフォルト) は `textChunkLimit` を超えた場合にのみ分割します。`newline` は長さによるチャンク化の前に空行 (段落境界) で分割します。
|
||||
<Accordion title="配信とチャンク分割">
|
||||
- `channels.bluebubbles.sendReadReceipts`: 開封確認を送信します (デフォルト: `true`)。
|
||||
- `channels.bluebubbles.blockStreaming`: ブロックストリーミングを有効にします (デフォルト: `false`; ストリーミング返信に必要)。
|
||||
- `channels.bluebubbles.textChunkLimit`: 送信チャンクサイズを文字数で指定します (デフォルト: 4000)。
|
||||
- `channels.bluebubbles.sendTimeoutMs`: `/api/v1/message/text` 経由の送信テキスト送信に対するリクエストごとのタイムアウトをミリ秒で指定します (デフォルト: 30000)。macOS 26 環境で、Private API による iMessage 送信が iMessage フレームワーク内で 60 秒以上停止する場合は、例えば `45000` や `60000` に引き上げてください。プローブ、チャット検索、リアクション、編集、ヘルスチェックは現在、より短いデフォルトの 10 秒を維持しています。リアクションと編集への対象拡大はフォローアップとして計画されています。アカウントごとの上書き: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`。
|
||||
- `channels.bluebubbles.chunkMode`: `length` (デフォルト) は `textChunkLimit` を超えた場合にのみ分割します。`newline` は長さによるチャンク分割の前に空行 (段落境界) で分割します。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="メディアと履歴">
|
||||
- `channels.bluebubbles.mediaMaxMb`: 受信/送信メディアの上限 (MB、デフォルト: 8)。
|
||||
- `channels.bluebubbles.mediaLocalRoots`: 送信ローカルメディアパスに許可される絶対ローカルディレクトリの明示的な許可リスト。これが設定されていない限り、ローカルパス送信はデフォルトで拒否されます。アカウントごとの上書き: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`。
|
||||
- `channels.bluebubbles.coalesceSameSenderDms`: 同じ送信者から連続する DM Webhook を 1 つのエージェントターンに統合し、Apple のテキスト+URL 分割送信を単一メッセージとして到着させます (デフォルト: `false`)。シナリオ、ウィンドウ調整、トレードオフについては [分割送信 DM の統合](#coalescing-split-send-dms-command--url-in-one-composition) を参照してください。明示的な `messages.inbound.byChannel.bluebubbles` なしで有効にすると、デフォルトの受信デバウンスウィンドウが 500 ms から 2500 ms に広がります。
|
||||
- `channels.bluebubbles.historyLimit`: コンテキスト用の最大グループメッセージ数 (0 で無効)。
|
||||
- `channels.bluebubbles.dmHistoryLimit`: DM 履歴の上限。
|
||||
- `channels.bluebubbles.replyContextApiFallback`: 受信返信に `replyToBody`/`replyToSender` がなく、メモリ内の返信コンテキストキャッシュもミスした場合、ベストエフォートのフォールバックとして BlueBubbles HTTP API から元メッセージを取得します (デフォルト: `false`)。1 つの BlueBubbles アカウントを共有する複数インスタンス構成、プロセス再起動後、または長期間の TTL/LRU キャッシュ退避後に有用です。この取得は他のすべての BlueBubbles クライアントリクエストと同じポリシーで SSRF から保護され、例外を投げず、キャッシュを埋めるため後続の返信で償却されます。アカウントごとの上書き: `channels.bluebubbles.accounts.<accountId>.replyContextApiFallback`。チャンネルレベルの設定は、このフラグを省略したアカウントへ伝播します。
|
||||
- `channels.bluebubbles.mediaMaxMb`: 受信/送信メディアの上限を MB で指定します (デフォルト: 8)。
|
||||
- `channels.bluebubbles.mediaLocalRoots`: 送信用ローカルメディアパスとして許可する絶対ローカルディレクトリの明示的な許可リストです。これが設定されていない限り、ローカルパス送信はデフォルトで拒否されます。アカウントごとの上書き: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`。
|
||||
- `channels.bluebubbles.coalesceSameSenderDms`: 同じ送信者から連続して届く DM Webhook を 1 つのエージェントターンにまとめ、Apple のテキスト+URL 分割送信が 1 件のメッセージとして届くようにします (デフォルト: `false`)。シナリオ、ウィンドウ調整、トレードオフについては [分割送信 DM の結合](#coalescing-split-send-dms-command--url-in-one-composition) を参照してください。明示的な `messages.inbound.byChannel.bluebubbles` なしで有効化すると、デフォルトの受信デバウンスウィンドウが 500 ms から 2500 ms に広がります。
|
||||
- `channels.bluebubbles.historyLimit`: コンテキスト用のグループメッセージ最大数です (0 で無効化)。
|
||||
- `channels.bluebubbles.dmHistoryLimit`: DM 履歴の上限です。
|
||||
- `channels.bluebubbles.replyContextApiFallback`: 受信返信に `replyToBody`/`replyToSender` がなく、メモリ内の返信コンテキストキャッシュもミスした場合に、ベストエフォートのフォールバックとして BlueBubbles HTTP API から元メッセージを取得します (デフォルト: `false`)。1 つの BlueBubbles アカウントを共有する複数インスタンスのデプロイ、プロセス再起動後、または長寿命の TTL/LRU キャッシュ退避後に有用です。この取得は、他のすべての BlueBubbles クライアントリクエストと同じポリシーで SSRF から保護され、例外を投げず、キャッシュを埋めるため後続の返信でコストをならせます。アカウントごとの上書き: `channels.bluebubbles.accounts.<accountId>.replyContextApiFallback`。チャンネルレベルの設定は、このフラグを省略したアカウントに伝播します。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="アクションとアカウント">
|
||||
- `channels.bluebubbles.actions`: 特定のアクションを有効化/無効化します。
|
||||
- `channels.bluebubbles.accounts`: 複数アカウント構成。
|
||||
- `channels.bluebubbles.accounts`: 複数アカウント設定です。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -605,37 +597,37 @@ OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例:
|
||||
|
||||
## アドレス指定 / 配信先
|
||||
|
||||
安定したルーティングには `chat_guid` を推奨します:
|
||||
安定したルーティングには `chat_guid` を優先してください:
|
||||
|
||||
- `chat_guid:iMessage;-;+15555550123` (グループに推奨)
|
||||
- `chat_id:123`
|
||||
- `chat_identifier:...`
|
||||
- 直接ハンドル: `+15555550123`, `user@example.com`
|
||||
- 直接ハンドルに既存の DM チャットがない場合、OpenClaw は `POST /api/v1/chat/new` 経由で作成します。これには BlueBubbles Private API が有効である必要があります。
|
||||
- 直接ハンドルに既存の DM チャットがない場合、OpenClaw は `POST /api/v1/chat/new` で作成します。これには BlueBubbles Private API が有効である必要があります。
|
||||
|
||||
### iMessage と SMS のルーティング
|
||||
|
||||
同じハンドルに Mac 上で iMessage と SMS の両方のチャットがある場合 (たとえば、iMessage に登録されているが緑の吹き出しのフォールバックも受信したことがある電話番号)、OpenClaw は iMessage チャットを優先し、暗黙に SMS へダウングレードすることはありません。SMS チャットを強制するには、明示的な `sms:` ターゲット接頭辞を使用します (例: `sms:+15555550123`)。一致する iMessage チャットがないハンドルは、BlueBubbles が報告する任意のチャット経由で送信されます。
|
||||
同じハンドルに、Mac 上で iMessage チャットと SMS チャットの両方がある場合 (例えば iMessage に登録済みの電話番号が、緑の吹き出しのフォールバックも受信している場合)、OpenClaw は iMessage チャットを優先し、黙って SMS にダウングレードすることはありません。SMS チャットを強制するには、明示的な `sms:` ターゲットプレフィックスを使用してください (例: `sms:+15555550123`)。一致する iMessage チャットがないハンドルは、BlueBubbles が報告する任意のチャット経由で送信されます。
|
||||
|
||||
## セキュリティ
|
||||
|
||||
- Webhook リクエストは、`guid`/`password` クエリパラメータまたはヘッダーを `channels.bluebubbles.password` と比較して認証されます。
|
||||
- API パスワードと Webhook エンドポイントは秘密にしてください (認証情報と同様に扱ってください)。
|
||||
- BlueBubbles Webhook 認証には localhost バイパスはありません。Webhook トラフィックをプロキシする場合、リクエストのエンドツーエンドで BlueBubbles パスワードを保持してください。ここでは `gateway.trustedProxies` は `channels.bluebubbles.password` を置き換えません。[Gateway セキュリティ](/ja-JP/gateway/security#reverse-proxy-configuration) を参照してください。
|
||||
- LAN 外に公開する場合は、BlueBubbles サーバーで HTTPS とファイアウォールルールを有効にしてください。
|
||||
- BlueBubbles Webhook 認証に localhost バイパスはありません。Webhook トラフィックをプロキシする場合は、リクエストのエンドツーエンドで BlueBubbles パスワードを保持してください。ここでは `gateway.trustedProxies` は `channels.bluebubbles.password` の代わりにはなりません。[Gateway セキュリティ](/ja-JP/gateway/security#reverse-proxy-configuration) を参照してください。
|
||||
- BlueBubbles サーバーを LAN 外に公開する場合は、HTTPS とファイアウォールルールを有効にしてください。
|
||||
|
||||
## トラブルシューティング
|
||||
|
||||
- 入力中/既読イベントが動作しなくなった場合は、BlueBubbles Webhook ログを確認し、Gateway パスが `channels.bluebubbles.webhookPath` と一致していることを検証してください。
|
||||
- 入力中/既読イベントが動作しなくなった場合は、BlueBubbles Webhook ログを確認し、Gateway パスが `channels.bluebubbles.webhookPath` と一致していることを確認してください。
|
||||
- ペアリングコードは 1 時間後に期限切れになります。`openclaw pairing list bluebubbles` と `openclaw pairing approve bluebubbles <code>` を使用してください。
|
||||
- リアクションには BlueBubbles private API (`POST /api/v1/message/react`) が必要です。サーバーバージョンがそれを公開していることを確認してください。
|
||||
- 編集/送信取り消しには macOS 13+ と互換性のある BlueBubbles サーバーバージョンが必要です。macOS 26 (Tahoe) では、private API の変更により編集は現在壊れています。
|
||||
- グループアイコン更新は macOS 26 (Tahoe) で不安定な場合があります。API は成功を返しても、新しいアイコンが同期されないことがあります。
|
||||
- OpenClaw は、BlueBubbles サーバーの macOS バージョンに基づいて、既知の壊れたアクションを自動的に非表示にします。macOS 26 (Tahoe) でも編集が表示される場合は、`channels.bluebubbles.actions.edit=false` で手動で無効化してください。
|
||||
- `coalesceSameSenderDms` を有効にしているのに分割送信 (例: `Dump` + URL) がまだ 2 ターンとして到着する場合は、[分割送信統合のトラブルシューティング](#split-send-coalescing-troubleshooting) チェックリストを参照してください。よくある原因は、デバウンスウィンドウが短すぎる、セッションログのタイムスタンプを Webhook 到着時刻として読み間違えている、または返信引用送信 (`replyToBody` を使用し、2 つ目の Webhook ではない) です。
|
||||
- グループアイコンの更新は macOS 26 (Tahoe) で不安定になることがあります。API が成功を返しても、新しいアイコンが同期されない場合があります。
|
||||
- OpenClaw は、BlueBubbles サーバーの macOS バージョンに基づいて、既知の壊れているアクションを自動的に非表示にします。macOS 26 (Tahoe) で編集がまだ表示される場合は、`channels.bluebubbles.actions.edit=false` で手動で無効化してください。
|
||||
- `coalesceSameSenderDms` が有効でも分割送信 (例: `Dump` + URL) が 2 つのターンとして届く場合は、[分割送信結合のトラブルシューティング](#split-send-coalescing-troubleshooting) チェックリストを参照してください。一般的な原因は、デバウンスウィンドウが短すぎる、セッションログのタイムスタンプを Webhook 到着時刻と誤読している、または返信引用送信 (`replyToBody` を使用し、2 つ目の Webhook ではない) です。
|
||||
- ステータス/ヘルス情報: `openclaw status --all` または `openclaw status --deep`。
|
||||
|
||||
一般的なチャンネルワークフローのリファレンスについては、[Channels](/ja-JP/channels) と [Plugins](/ja-JP/tools/plugin) ガイドを参照してください。
|
||||
一般的なチャンネルワークフローのリファレンスについては、[チャンネル](/ja-JP/channels) と [Plugins](/ja-JP/tools/plugin) ガイドを参照してください。
|
||||
|
||||
## 関連
|
||||
|
||||
@ -643,4 +635,4 @@ OpenClaw は、トークン節約のために _短縮_ メッセージ ID（例:
|
||||
- [チャンネル概要](/ja-JP/channels) — 対応するすべてのチャンネル
|
||||
- [グループ](/ja-JP/channels/groups) — グループチャットの動作とメンションゲート
|
||||
- [ペアリング](/ja-JP/channels/pairing) — DM 認証とペアリングフロー
|
||||
- [セキュリティ](/ja-JP/gateway/security) — アクセスモデルと強化
|
||||
- [セキュリティ](/ja-JP/gateway/security) — アクセスモデルと堅牢化
|
||||
|
||||
@ -1,37 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- ブロードキャストグループの設定
|
||||
- WhatsAppでのマルチエージェント返信のデバッグ
|
||||
- WhatsApp でのマルチエージェント返信のデバッグ
|
||||
sidebarTitle: Broadcast groups
|
||||
status: experimental
|
||||
summary: WhatsApp メッセージを複数のエージェントにブロードキャストする
|
||||
summary: 複数のエージェントに WhatsApp メッセージをブロードキャストする
|
||||
title: ブロードキャストグループ
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T04:57:48Z"
|
||||
generated_at: "2026-05-04T02:21:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b0de4ccc85bf79e2ceb1dddd60db067309b15b7f876c92e7d591ff0b4b4315ec
|
||||
source_hash: eab43d3c3ffddb360340469433d74a380fbab98e662b2463a54f62eafc375b55
|
||||
source_path: channels/broadcast-groups.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
<Note>
|
||||
**ステータス:** 実験的。2026.1.9で追加。
|
||||
**ステータス:** 実験的。2026.1.9 で追加。
|
||||
</Note>
|
||||
|
||||
## 概要
|
||||
|
||||
ブロードキャストグループを使うと、複数のエージェントが同じメッセージを同時に処理し、応答できます。これにより、1つの電話番号だけを使って、1つのWhatsAppグループまたはダイレクトメッセージ内で連携する、専門化されたエージェントチームを作成できます。
|
||||
ブロードキャストグループを使うと、複数のエージェントが同じメッセージを同時に処理し、応答できます。これにより、1 つの WhatsApp グループまたは DM 内で連携する専用エージェントチームを、1 つの電話番号だけで作成できます。
|
||||
|
||||
現在の対象範囲: **WhatsAppのみ**（Webチャネル）。
|
||||
現在のスコープ: **WhatsApp のみ**（Web チャネル）。
|
||||
|
||||
ブロードキャストグループは、チャネル許可リストとグループ有効化ルールの後に評価されます。WhatsAppグループでは、これはOpenClawが通常応答する場合（例: メンション時。グループ設定による）にブロードキャストが発生することを意味します。
|
||||
ブロードキャストグループは、チャネルの許可リストとグループ有効化ルールの後に評価されます。WhatsApp グループでは、これは OpenClaw が通常応答する場合にブロードキャストが発生することを意味します（例: グループ設定に応じたメンション時など）。
|
||||
|
||||
## ユースケース
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="1. 専門化されたエージェントチーム">
|
||||
原子的で焦点を絞った責任を持つ複数のエージェントをデプロイします。
|
||||
<Accordion title="1. 専用エージェントチーム">
|
||||
原子的で集中的な責務を持つ複数のエージェントをデプロイします。
|
||||
|
||||
```
|
||||
Group: "Development Team"
|
||||
@ -42,7 +42,7 @@ x-i18n:
|
||||
- TestGenerator (suggests test cases)
|
||||
```
|
||||
|
||||
各エージェントは同じメッセージを処理し、それぞれの専門的な視点を提供します。
|
||||
各エージェントは同じメッセージを処理し、それぞれの専門的な観点を提供します。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. 多言語サポート">
|
||||
@ -75,12 +75,12 @@ x-i18n:
|
||||
|
||||
## 設定
|
||||
|
||||
### 基本セットアップ
|
||||
### 基本設定
|
||||
|
||||
トップレベルの`broadcast`セクションを追加します（`bindings`の隣）。キーはWhatsAppのピアIDです。
|
||||
トップレベルの `broadcast` セクションを追加します（`bindings` の隣）。キーは WhatsApp ピア ID です。
|
||||
|
||||
- グループチャット: グループJID（例: `120363403215116621@g.us`）
|
||||
- ダイレクトメッセージ: E.164電話番号（例: `+15551234567`）
|
||||
- グループチャット: グループ JID（例: `120363403215116621@g.us`）
|
||||
- DM: E.164 電話番号（例: `+15551234567`）
|
||||
|
||||
```json
|
||||
{
|
||||
@ -90,7 +90,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
**結果:** OpenClawがこのチャットで応答する場合、3つすべてのエージェントを実行します。
|
||||
**結果:** OpenClaw がこのチャットで応答する場合、3 つすべてのエージェントを実行します。
|
||||
|
||||
### 処理戦略
|
||||
|
||||
@ -111,7 +111,7 @@ x-i18n:
|
||||
|
||||
</Tab>
|
||||
<Tab title="sequential">
|
||||
エージェントは順番に処理します（1つ前の完了を待ちます）。
|
||||
エージェントが順番に処理します（1 つが前の処理完了を待ちます）。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -165,14 +165,14 @@ x-i18n:
|
||||
### メッセージフロー
|
||||
|
||||
<Steps>
|
||||
<Step title="受信メッセージが到着する">
|
||||
WhatsAppグループまたはダイレクトメッセージが到着します。
|
||||
<Step title="受信メッセージが到着">
|
||||
WhatsApp グループまたは DM のメッセージが到着します。
|
||||
</Step>
|
||||
<Step title="ブロードキャストチェック">
|
||||
システムはピアIDが`broadcast`に含まれているか確認します。
|
||||
<Step title="ブロードキャスト確認">
|
||||
システムはピア ID が `broadcast` に含まれているかを確認します。
|
||||
</Step>
|
||||
<Step title="ブロードキャストリストに含まれる場合">
|
||||
- 記載されたすべてのエージェントがメッセージを処理します。
|
||||
- 一覧にあるすべてのエージェントがメッセージを処理します。
|
||||
- 各エージェントは独自のセッションキーと分離されたコンテキストを持ちます。
|
||||
- エージェントは並列（デフォルト）または順次に処理します。
|
||||
|
||||
@ -183,7 +183,7 @@ x-i18n:
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
ブロードキャストグループは、チャネル許可リストやグループ有効化ルール（メンション/コマンドなど）を迂回しません。メッセージが処理対象になったときに、_どのエージェントが実行されるか_だけを変更します。
|
||||
ブロードキャストグループは、チャネルの許可リストやグループ有効化ルール（メンション/コマンドなど）をバイパスしません。メッセージが処理対象になったときに、_どのエージェントを実行するか_ だけを変更します。
|
||||
</Note>
|
||||
|
||||
### セッション分離
|
||||
@ -194,22 +194,22 @@ x-i18n:
|
||||
- **会話履歴**（エージェントは他のエージェントのメッセージを見ません）
|
||||
- **ワークスペース**（設定されている場合は別々のサンドボックス）
|
||||
- **ツールアクセス**（異なる許可/拒否リスト）
|
||||
- **メモリ/コンテキスト**（別々のIDENTITY.md、SOUL.mdなど）
|
||||
- **グループコンテキストバッファ**（コンテキストに使われる最近のグループメッセージ）はピアごとに共有されるため、すべてのブロードキャストエージェントはトリガー時に同じコンテキストを参照します
|
||||
- **メモリ/コンテキスト**（別々の IDENTITY.md、SOUL.md など）
|
||||
- **グループコンテキストバッファ**（コンテキストに使われる最近のグループメッセージ）はピアごとに共有されるため、すべてのブロードキャストエージェントはトリガー時に同じコンテキストを見ます
|
||||
|
||||
これにより、各エージェントに次を持たせることができます。
|
||||
|
||||
- 異なる人格
|
||||
- 異なるパーソナリティ
|
||||
- 異なるツールアクセス（例: 読み取り専用と読み書き）
|
||||
- 異なるモデル（例: opusとsonnet）
|
||||
- インストール済みの異なるSkills
|
||||
- 異なるモデル（例: opus と sonnet）
|
||||
- 異なる Skills のインストール
|
||||
|
||||
### 例: 分離されたセッション
|
||||
|
||||
エージェント`["alfred", "baerbel"]`がいるグループ`120363403215116621@g.us`の場合:
|
||||
エージェント `["alfred", "baerbel"]` を持つグループ `120363403215116621@g.us` の場合:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Alfredのコンテキスト">
|
||||
<Tab title="Alfred のコンテキスト">
|
||||
```
|
||||
Session: agent:alfred:whatsapp:group:120363403215116621@g.us
|
||||
History: [user message, alfred's previous responses]
|
||||
@ -217,7 +217,7 @@ x-i18n:
|
||||
Tools: read, write, exec
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Bärbelのコンテキスト">
|
||||
<Tab title="Bärbel のコンテキスト">
|
||||
```
|
||||
Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
|
||||
History: [user message, baerbel's previous responses]
|
||||
@ -230,8 +230,8 @@ x-i18n:
|
||||
## ベストプラクティス
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="1. エージェントの焦点を絞る">
|
||||
各エージェントは、単一で明確な責任を持つように設計します。
|
||||
<Accordion title="1. エージェントの責務を絞る">
|
||||
各エージェントは、単一で明確な責務を持つように設計します。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -241,11 +241,11 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
✅ **良い例:** 各エージェントに1つの仕事があります。❌ **悪い例:** 1つの汎用的な「dev-helper」エージェント。
|
||||
✅ **良い例:** 各エージェントが 1 つの役割を持つ。❌ **悪い例:** 汎用的な "dev-helper" エージェント 1 つ。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. 説明的な名前を使う">
|
||||
各エージェントが何をするか明確にします。
|
||||
各エージェントが何をするのか明確にします。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -259,32 +259,34 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. 異なるツールアクセスを設定する">
|
||||
エージェントには必要なツールだけを与えます。
|
||||
エージェントには必要なツールだけを付与します。
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"reviewer": {
|
||||
"tools": { "allow": ["read", "exec"] } // Read-only
|
||||
"tools": { "allow": ["read", "exec"] }
|
||||
},
|
||||
"fixer": {
|
||||
"tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write
|
||||
"tools": { "allow": ["read", "write", "edit", "exec"] }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`reviewer` は読み取り専用です。`fixer` は読み取りと書き込みができます。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="4. パフォーマンスを監視する">
|
||||
多数のエージェントがある場合は、次を検討してください。
|
||||
エージェントが多い場合は、次を検討します。
|
||||
|
||||
- 速度のために`"strategy": "parallel"`（デフォルト）を使用する
|
||||
- ブロードキャストグループを5〜10エージェントに制限する
|
||||
- より単純なエージェントには高速なモデルを使用する
|
||||
- 速度のために `"strategy": "parallel"`（デフォルト）を使う
|
||||
- ブロードキャストグループを 5〜10 エージェントに制限する
|
||||
- より単純なエージェントには高速なモデルを使う
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. 障害を適切に処理する">
|
||||
エージェントは独立して失敗します。1つのエージェントのエラーが他をブロックすることはありません。
|
||||
<Accordion title="5. 失敗を適切に処理する">
|
||||
エージェントは独立して失敗します。1 つのエージェントのエラーが他をブロックすることはありません。
|
||||
|
||||
```
|
||||
Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
|
||||
@ -323,11 +325,11 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
- `GROUP_A`: alfredのみが応答します（通常のルーティング）。
|
||||
- `GROUP_B`: agent1とagent2が応答します（ブロードキャスト）。
|
||||
- `GROUP_A`: alfred のみが応答します（通常のルーティング）。
|
||||
- `GROUP_B`: agent1 と agent2 が応答します（ブロードキャスト）。
|
||||
|
||||
<Note>
|
||||
**優先順位:** `broadcast`は`bindings`より優先されます。
|
||||
**優先順位:** `broadcast` は `bindings` より優先されます。
|
||||
</Note>
|
||||
|
||||
## トラブルシューティング
|
||||
@ -336,9 +338,9 @@ x-i18n:
|
||||
<Accordion title="エージェントが応答しない">
|
||||
**確認:**
|
||||
|
||||
1. エージェントIDが`agents.list`に存在する。
|
||||
2. ピアID形式が正しい（例: `120363403215116621@g.us`）。
|
||||
3. エージェントが拒否リストに含まれていない。
|
||||
1. エージェント ID が `agents.list` に存在する。
|
||||
2. ピア ID の形式が正しい（例: `120363403215116621@g.us`）。
|
||||
3. エージェントが拒否リストに入っていない。
|
||||
|
||||
**デバッグ:**
|
||||
|
||||
@ -347,17 +349,17 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="1つのエージェントだけが応答する">
|
||||
**原因:** ピアIDが`bindings`には含まれているが、`broadcast`には含まれていない可能性があります。
|
||||
<Accordion title="1 つのエージェントだけが応答する">
|
||||
**原因:** ピア ID が `bindings` に含まれているが、`broadcast` には含まれていない可能性があります。
|
||||
|
||||
**修正:** ブロードキャスト設定に追加するか、バインディングから削除します。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="パフォーマンスの問題">
|
||||
多数のエージェントで遅い場合:
|
||||
エージェントが多くて遅い場合:
|
||||
|
||||
- グループあたりのエージェント数を減らします。
|
||||
- より軽量なモデルを使用します（opusではなくsonnet）。
|
||||
- 軽量なモデルを使います（opus ではなく sonnet）。
|
||||
- サンドボックスの起動時間を確認します。
|
||||
|
||||
</Accordion>
|
||||
@ -366,7 +368,7 @@ x-i18n:
|
||||
## 例
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="例1: コードレビューチーム">
|
||||
<Accordion title="例 1: コードレビューチーム">
|
||||
```json
|
||||
{
|
||||
"broadcast": {
|
||||
@ -401,17 +403,17 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
**ユーザーの送信内容:** コードスニペット。
|
||||
**ユーザーが送信:** コードスニペット。
|
||||
|
||||
**応答:**
|
||||
|
||||
- code-formatter: 「インデントを修正し、型ヒントを追加しました」
|
||||
- security-scanner: 「⚠️ 12行目にSQLインジェクション脆弱性があります」
|
||||
- test-coverage: 「カバレッジは45%で、エラーケースのテストが不足しています」
|
||||
- docs-checker: 「関数`process_data`のdocstringがありません」
|
||||
- security-scanner: 「⚠️ 12 行目に SQL インジェクション脆弱性があります」
|
||||
- test-coverage: 「カバレッジは 45% で、エラーケースのテストが不足しています」
|
||||
- docs-checker: 「関数 `process_data` の docstring がありません」
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="例2: 多言語サポート">
|
||||
<Accordion title="例 2: 多言語サポート">
|
||||
```json
|
||||
{
|
||||
"broadcast": {
|
||||
@ -430,7 +432,7 @@ x-i18n:
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## APIリファレンス
|
||||
## API リファレンス
|
||||
|
||||
### 設定スキーマ
|
||||
|
||||
@ -446,27 +448,27 @@ interface OpenClawConfig {
|
||||
### フィールド
|
||||
|
||||
<ParamField path="strategy" type='"parallel" | "sequential"' default='"parallel"'>
|
||||
エージェントを処理する方法。`parallel`はすべてのエージェントを同時に実行し、`sequential`は配列の順序で実行します。
|
||||
エージェントを処理する方法です。`parallel` はすべてのエージェントを同時に実行し、`sequential` は配列の順序で実行します。
|
||||
</ParamField>
|
||||
<ParamField path="[peerId]" type="string[]">
|
||||
WhatsAppグループJID、E.164番号、またはその他のピアID。値はメッセージを処理するエージェントIDの配列です。
|
||||
WhatsApp グループ JID、E.164 番号、またはその他のピア ID。値は、メッセージを処理するエージェント ID の配列です。
|
||||
</ParamField>
|
||||
|
||||
## 制限事項
|
||||
|
||||
1. **最大エージェント数:** ハードリミットはありませんが、10以上のエージェントでは遅くなる可能性があります。
|
||||
2. **共有コンテキスト:** エージェントは互いの応答を見ません（設計上）。
|
||||
1. **最大エージェント数:** ハードリミットはありませんが、10 以上のエージェントでは遅くなる可能性があります。
|
||||
2. **共有コンテキスト:** エージェントは互いの応答を見ません（意図された設計です）。
|
||||
3. **メッセージ順序:** 並列応答は任意の順序で到着する可能性があります。
|
||||
4. **レート制限:** すべてのエージェントがWhatsAppのレート制限にカウントされます。
|
||||
4. **レート制限:** すべてのエージェントが WhatsApp のレート制限にカウントされます。
|
||||
|
||||
## 今後の拡張
|
||||
|
||||
予定されている機能:
|
||||
|
||||
- [ ] 共有コンテキストモード（エージェントが互いの応答を見る）
|
||||
- [ ] エージェント調整（エージェントが互いにシグナルを送れる）
|
||||
- [ ] エージェントの調整（エージェントが互いにシグナルを送れる）
|
||||
- [ ] 動的なエージェント選択（メッセージ内容に基づいてエージェントを選ぶ）
|
||||
- [ ] エージェント優先度（一部のエージェントが他より先に応答する）
|
||||
- [ ] エージェントの優先度（一部のエージェントが他より先に応答する）
|
||||
|
||||
## 関連
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,102 +1,102 @@
|
||||
---
|
||||
read_when:
|
||||
- Google Chat チャンネル機能に取り組んでいます
|
||||
- Google Chat のチャンネル機能に取り組む
|
||||
summary: Google Chat アプリのサポート状況、機能、設定
|
||||
title: Google Chat
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:41:18Z"
|
||||
generated_at: "2026-05-04T02:21:38Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fdb8dcf651602e92801d7107646d853871ea6cef188a8733a831695a1243740e
|
||||
source_hash: afa2ca4d9673396aa24a55ca5855a34ad26a4640c3a1f6928dbf7246e403cb04
|
||||
source_path: channels/googlechat.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
ステータス: Google Chat API Webhook 経由の DM + スペース向けダウンロード可能 Plugin（HTTP のみ）。
|
||||
ステータス: Google Chat API webhooks (HTTP のみ) 経由で DM + スペースに対応するダウンロード可能な Plugin。
|
||||
|
||||
## インストール
|
||||
|
||||
チャンネルを設定する前に Google Chat をインストールします。
|
||||
チャネルを設定する前に Google Chat をインストールします。
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/googlechat
|
||||
```
|
||||
|
||||
ローカルチェックアウト（git リポジトリから実行する場合）:
|
||||
ローカルチェックアウト (git リポジトリから実行する場合):
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/googlechat-plugin
|
||||
```
|
||||
|
||||
## クイックセットアップ（初心者向け）
|
||||
## クイックセットアップ (初心者向け)
|
||||
|
||||
1. Google Cloud プロジェクトを作成し、**Google Chat API** を有効化します。
|
||||
1. Google Cloud プロジェクトを作成し、**Google Chat API** を有効にします。
|
||||
- 移動先: [Google Chat API 認証情報](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
|
||||
- API がまだ有効化されていない場合は有効化します。
|
||||
- API がまだ有効になっていない場合は有効にします。
|
||||
2. **Service Account** を作成します。
|
||||
- **Create Credentials** > **Service Account** を押します。
|
||||
- 任意の名前を付けます（例: `openclaw-chat`）。
|
||||
- 権限は空のままにします（**Continue** を押します）。
|
||||
- アクセス権を持つプリンシパルは空のままにします（**Done** を押します）。
|
||||
- 任意の名前を付けます (例: `openclaw-chat`)。
|
||||
- 権限は空のままにします (**Continue** を押します)。
|
||||
- アクセス権を持つプリンシパルは空のままにします (**Done** を押します)。
|
||||
3. **JSON Key** を作成してダウンロードします。
|
||||
- サービスアカウントの一覧で、作成したアカウントをクリックします。
|
||||
- サービスアカウントの一覧で、作成したばかりのアカウントをクリックします。
|
||||
- **Keys** タブに移動します。
|
||||
- **Add Key** > **Create new key** をクリックします。
|
||||
- **JSON** を選択し、**Create** を押します。
|
||||
4. ダウンロードした JSON ファイルを Gateway ホストに保存します（例: `~/.openclaw/googlechat-service-account.json`）。
|
||||
5. [Google Cloud Console Chat 設定](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)で Google Chat アプリを作成します。
|
||||
4. ダウンロードした JSON ファイルを Gateway ホストに保存します (例: `~/.openclaw/googlechat-service-account.json`)。
|
||||
5. [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) で Google Chat アプリを作成します。
|
||||
- **Application info** を入力します。
|
||||
- **App name**: （例: `OpenClaw`）
|
||||
- **Avatar URL**: （例: `https://openclaw.ai/logo.png`）
|
||||
- **Description**: （例: `Personal AI Assistant`）
|
||||
- **Interactive features** を有効化します。
|
||||
- **App name**: (例: `OpenClaw`)
|
||||
- **Avatar URL**: (例: `https://openclaw.ai/logo.png`)
|
||||
- **Description**: (例: `Personal AI Assistant`)
|
||||
- **Interactive features** を有効にします。
|
||||
- **Functionality** で、**Join spaces and group conversations** にチェックを入れます。
|
||||
- **Connection settings** で、**HTTP endpoint URL** を選択します。
|
||||
- **Triggers** で、**Use a common HTTP endpoint URL for all triggers** を選択し、Gateway の公開 URL に `/googlechat` を付けた値を設定します。
|
||||
- _ヒント: Gateway の公開 URL を見つけるには `openclaw status` を実行します。_
|
||||
- **Triggers** で、**Use a common HTTP endpoint URL for all triggers** を選択し、Gateway の公開 URL に `/googlechat` を付けたものを設定します。
|
||||
- _ヒント: `openclaw status` を実行して Gateway の公開 URL を確認します。_
|
||||
- **Visibility** で、**Make this Chat app available to specific people and groups in `<Your Domain>`** にチェックを入れます。
|
||||
- テキストボックスにメールアドレス（例: `user@example.com`）を入力します。
|
||||
- テキストボックスにメールアドレス (例: `user@example.com`) を入力します。
|
||||
- 下部の **Save** をクリックします。
|
||||
6. **アプリのステータスを有効化**します。
|
||||
6. **アプリのステータスを有効化します**。
|
||||
- 保存後、**ページを更新**します。
|
||||
- **App status** セクションを探します（通常、保存後に上部または下部付近にあります）。
|
||||
- **App status** セクションを探します (通常、保存後はページの上部または下部付近にあります)。
|
||||
- ステータスを **Live - available to users** に変更します。
|
||||
- もう一度 **Save** をクリックします。
|
||||
7. サービスアカウントのパス + Webhook オーディエンスで OpenClaw を設定します。
|
||||
- Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
|
||||
- または config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`。
|
||||
8. Webhook オーディエンスタイプ + 値を設定します（Chat アプリ設定と一致させます）。
|
||||
9. Gateway を起動します。Google Chat は Webhook パスに POST します。
|
||||
7. サービスアカウントのパス + Webhook audience を指定して OpenClaw を設定します。
|
||||
- 環境変数: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
|
||||
- または設定: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`。
|
||||
8. Webhook audience type + value を設定します (Chat アプリ設定と一致させます)。
|
||||
9. Gateway を起動します。Google Chat が Webhook パスに POST します。
|
||||
|
||||
## Google Chat に追加
|
||||
|
||||
Gateway が実行中で、メールアドレスが可視性リストに追加されている場合:
|
||||
Gateway が実行中で、メールアドレスが公開範囲リストに追加されている場合:
|
||||
|
||||
1. [Google Chat](https://chat.google.com/) に移動します。
|
||||
2. **Direct Messages** の横にある **+**（プラス）アイコンをクリックします。
|
||||
3. 検索バー（通常ユーザーを追加する場所）に、Google Cloud Console で設定した **App name** を入力します。
|
||||
- **注**: これは非公開アプリのため、ボットは「Marketplace」の閲覧リストには表示されません。名前で検索する必要があります。
|
||||
2. **Direct Messages** の横にある **+** (プラス) アイコンをクリックします。
|
||||
3. 検索バー (通常、人を追加する場所) に、Google Cloud Console で設定した **App name** を入力します。
|
||||
- **注**: これは非公開アプリのため、ボットは "Marketplace" の閲覧リストには表示されません。名前で検索する必要があります。
|
||||
4. 結果からボットを選択します。
|
||||
5. **Add** または **Chat** をクリックして 1:1 の会話を開始します。
|
||||
6. アシスタントを起動するために「Hello」を送信します。
|
||||
6. "Hello" を送信してアシスタントをトリガーします。
|
||||
|
||||
## 公開 URL（Webhook のみ）
|
||||
## 公開 URL (Webhook のみ)
|
||||
|
||||
Google Chat Webhook には公開 HTTPS エンドポイントが必要です。セキュリティのため、インターネットには **`/googlechat` パスのみを公開**してください。OpenClaw ダッシュボードとその他の機密エンドポイントはプライベートネットワーク上に保ちます。
|
||||
Google Chat webhooks には公開 HTTPS エンドポイントが必要です。セキュリティのため、インターネットに公開するのは **`/googlechat` パスのみ**にしてください。OpenClaw ダッシュボードやその他の機密エンドポイントはプライベートネットワークに保持します。
|
||||
|
||||
### オプション A: Tailscale Funnel（推奨）
|
||||
### オプション A: Tailscale Funnel (推奨)
|
||||
|
||||
プライベートダッシュボードには Tailscale Serve を使用し、公開 Webhook パスには Funnel を使用します。これにより、`/` はプライベートのまま、`/googlechat` のみを公開できます。
|
||||
プライベートダッシュボードには Tailscale Serve を使用し、公開 Webhook パスには Funnel を使用します。これにより `/` はプライベートのまま、`/googlechat` のみを公開できます。
|
||||
|
||||
1. **Gateway がどのアドレスにバインドされているかを確認します。**
|
||||
1. **Gateway がバインドされているアドレスを確認します。**
|
||||
|
||||
```bash
|
||||
ss -tlnp | grep 18789
|
||||
```
|
||||
|
||||
IP アドレスを確認します（例: `127.0.0.1`、`0.0.0.0`、または `100.x.x.x` のような Tailscale IP）。
|
||||
IP アドレスを確認します (例: `127.0.0.1`、`0.0.0.0`、または `100.x.x.x` のような Tailscale IP)。
|
||||
|
||||
2. **ダッシュボードを tailnet のみに公開します（ポート 8443）。**
|
||||
2. **ダッシュボードを tailnet のみに公開します (ポート 8443)。**
|
||||
|
||||
```bash
|
||||
# If bound to localhost (127.0.0.1 or 0.0.0.0):
|
||||
@ -116,10 +116,10 @@ Google Chat Webhook には公開 HTTPS エンドポイントが必要です。
|
||||
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
|
||||
```
|
||||
|
||||
4. **Funnel アクセス用にノードを承認します。**
|
||||
プロンプトが表示された場合は、出力に表示された承認 URL にアクセスし、tailnet ポリシーでこのノードの Funnel を有効化します。
|
||||
4. **Funnel アクセス用にノードを認可します。**
|
||||
プロンプトが表示された場合は、出力に表示された認可 URL にアクセスして、このノードの Funnel を tailnet ポリシーで有効にします。
|
||||
|
||||
5. **設定を検証します。**
|
||||
5. **設定を確認します。**
|
||||
|
||||
```bash
|
||||
tailscale serve status
|
||||
@ -129,14 +129,14 @@ Google Chat Webhook には公開 HTTPS エンドポイントが必要です。
|
||||
公開 Webhook URL は次のようになります。
|
||||
`https://<node-name>.<tailnet>.ts.net/googlechat`
|
||||
|
||||
プライベートダッシュボードは tailnet のみに留まります。
|
||||
プライベートダッシュボードは tailnet 専用のままです。
|
||||
`https://<node-name>.<tailnet>.ts.net:8443/`
|
||||
|
||||
Google Chat アプリ設定では公開 URL（`:8443` なし）を使用します。
|
||||
Google Chat アプリ設定では、公開 URL (`:8443` なし) を使用します。
|
||||
|
||||
> 注: この設定は再起動後も維持されます。後で削除するには、`tailscale funnel reset` と `tailscale serve reset` を実行します。
|
||||
> 注: この設定は再起動後も保持されます。後で削除するには、`tailscale funnel reset` と `tailscale serve reset` を実行します。
|
||||
|
||||
### オプション B: リバースプロキシ（Caddy）
|
||||
### オプション B: リバースプロキシ (Caddy)
|
||||
|
||||
Caddy のようなリバースプロキシを使用する場合は、特定のパスのみをプロキシします。
|
||||
|
||||
@ -146,37 +146,37 @@ your-domain.com {
|
||||
}
|
||||
```
|
||||
|
||||
この設定では、`your-domain.com/` へのリクエストは無視されるか 404 として返され、`your-domain.com/googlechat` は安全に OpenClaw にルーティングされます。
|
||||
この設定では、`your-domain.com/` へのリクエストは無視されるか 404 として返され、`your-domain.com/googlechat` は安全に OpenClaw へルーティングされます。
|
||||
|
||||
### オプション C: Cloudflare Tunnel
|
||||
|
||||
トンネルの ingress ルールを設定し、Webhook パスのみをルーティングします。
|
||||
トンネルの ingress ルールを、Webhook パスのみをルーティングするように設定します。
|
||||
|
||||
- **Path**: `/googlechat` -> `http://localhost:18789/googlechat`
|
||||
- **Default Rule**: HTTP 404（Not Found）
|
||||
- **パス**: `/googlechat` -> `http://localhost:18789/googlechat`
|
||||
- **デフォルトルール**: HTTP 404 (Not Found)
|
||||
|
||||
## 仕組み
|
||||
|
||||
1. Google Chat は Webhook POST を Gateway に送信します。各リクエストには `Authorization: Bearer <token>` ヘッダーが含まれます。
|
||||
- OpenClaw はヘッダーが存在する場合、Webhook 本文全体を読み取り/解析する前にベアラー認証を検証します。
|
||||
- 本文内に `authorizationEventObject.systemIdToken` を含む Google Workspace Add-on リクエストは、より厳格な事前認証本文バジェットでサポートされます。
|
||||
1. Google Chat は Gateway に Webhook POST を送信します。各リクエストには `Authorization: Bearer <token>` ヘッダーが含まれます。
|
||||
- OpenClaw は、ヘッダーが存在する場合、Webhook 本文全体を読み取り/解析する前に bearer auth を検証します。
|
||||
- 本文に `authorizationEventObject.systemIdToken` を含む Google Workspace Add-on リクエストは、より厳格な事前認証本文予算でサポートされます。
|
||||
2. OpenClaw は、設定された `audienceType` + `audience` に対してトークンを検証します。
|
||||
- `audienceType: "app-url"` → オーディエンスは HTTPS Webhook URL です。
|
||||
- `audienceType: "project-number"` → オーディエンスは Cloud プロジェクト番号です。
|
||||
- `audienceType: "app-url"` → audience は HTTPS Webhook URL です。
|
||||
- `audienceType: "project-number"` → audience は Cloud プロジェクト番号です。
|
||||
3. メッセージはスペースごとにルーティングされます。
|
||||
- DM はセッションキー `agent:<agentId>:googlechat:direct:<spaceId>` を使用します。
|
||||
- スペースはセッションキー `agent:<agentId>:googlechat:group:<spaceId>` を使用します。
|
||||
4. DM アクセスはデフォルトでペアリングです。不明な送信者にはペアリングコードが送信されます。次で承認します。
|
||||
4. DM アクセスはデフォルトでペアリングです。不明な送信者にはペアリングコードが届きます。次で承認します。
|
||||
- `openclaw pairing approve googlechat <code>`
|
||||
5. グループスペースでは、デフォルトで @メンションが必要です。メンション検出にアプリのユーザー名が必要な場合は `botUser` を使用します。
|
||||
|
||||
## ターゲット
|
||||
|
||||
配信と許可リストにはこれらの識別子を使用します。
|
||||
配信と許可リストには、これらの識別子を使用します。
|
||||
|
||||
- ダイレクトメッセージ: `users/<userId>`（推奨）。
|
||||
- 生のメールアドレス `name@example.com` は変更可能であり、`channels.googlechat.dangerouslyAllowNameMatching: true` の場合にのみダイレクト許可リストの照合に使用されます。
|
||||
- 非推奨: `users/<email>` はメール許可リストではなくユーザー ID として扱われます。
|
||||
- ダイレクトメッセージ: `users/<userId>` (推奨)。
|
||||
- 生のメール `name@example.com` は変更可能であり、`channels.googlechat.dangerouslyAllowNameMatching: true` の場合にのみ直接許可リスト照合に使用されます。
|
||||
- 非推奨: `users/<email>` はメール許可リストではなく、ユーザー ID として扱われます。
|
||||
- スペース: `spaces/<spaceId>`。
|
||||
|
||||
## 設定の要点
|
||||
@ -199,7 +199,7 @@ your-domain.com {
|
||||
groupPolicy: "allowlist",
|
||||
groups: {
|
||||
"spaces/AAAA": {
|
||||
allow: true,
|
||||
enabled: true,
|
||||
requireMention: true,
|
||||
users: ["users/1234567890"],
|
||||
systemPrompt: "Short answers only.",
|
||||
@ -215,14 +215,14 @@ your-domain.com {
|
||||
|
||||
注:
|
||||
|
||||
- サービスアカウント認証情報は `serviceAccount`（JSON 文字列）でインライン渡しすることもできます。
|
||||
- `serviceAccountRef` もサポートされています（env/file SecretRef）。`channels.googlechat.accounts.<id>.serviceAccountRef` 配下のアカウント別 ref も含まれます。
|
||||
- サービスアカウント認証情報は、`serviceAccount` (JSON 文字列) でインライン渡しすることもできます。
|
||||
- `serviceAccountRef` もサポートされています (env/file SecretRef)。`channels.googlechat.accounts.<id>.serviceAccountRef` 配下のアカウント別 ref も含みます。
|
||||
- `webhookPath` が設定されていない場合、デフォルトの Webhook パスは `/googlechat` です。
|
||||
- `dangerouslyAllowNameMatching` は、許可リスト用の変更可能なメールプリンシパル照合を再有効化します（緊急互換モード）。
|
||||
- `actions.reactions` が有効な場合、リアクションは `reactions` ツールと `channels action` で利用できます。
|
||||
- メッセージアクションは、テキスト用の `send` と明示的な添付送信用の `upload-file` を公開します。`upload-file` は `media` / `filePath` / `path` に加えて、任意の `message`、`filename`、スレッドターゲットを受け付けます。
|
||||
- `typingIndicator` は `none`、`message`（デフォルト）、`reaction` をサポートします（リアクションにはユーザー OAuth が必要です）。
|
||||
- 添付ファイルは Chat API 経由でダウンロードされ、メディアパイプラインに保存されます（サイズは `mediaMaxMb` により制限）。
|
||||
- `dangerouslyAllowNameMatching` は、許可リスト向けに変更可能なメールプリンシパル照合を再有効化します (緊急時互換モード)。
|
||||
- リアクションは、`actions.reactions` が有効な場合に `reactions` ツールと `channels action` で利用できます。
|
||||
- メッセージアクションは、テキスト用の `send` と、明示的な添付送信用の `upload-file` を公開します。`upload-file` は `media` / `filePath` / `path` に加え、任意の `message`、`filename`、スレッドターゲットを受け付けます。
|
||||
- `typingIndicator` は `none`、`message` (デフォルト)、`reaction` をサポートします (`reaction` にはユーザー OAuth が必要です)。
|
||||
- 添付ファイルは Chat API 経由でダウンロードされ、メディアパイプラインに保存されます (サイズは `mediaMaxMb` で上限設定)。
|
||||
|
||||
シークレット参照の詳細: [シークレット管理](/ja-JP/gateway/secrets)。
|
||||
|
||||
@ -238,21 +238,21 @@ status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Al
|
||||
|
||||
これは Webhook ハンドラーが登録されていないことを意味します。一般的な原因:
|
||||
|
||||
1. **チャンネルが設定されていない**: 設定に `channels.googlechat` セクションがありません。次で確認します。
|
||||
1. **チャネルが設定されていない**: 設定に `channels.googlechat` セクションがありません。次で確認します。
|
||||
|
||||
```bash
|
||||
openclaw config get channels.googlechat
|
||||
```
|
||||
|
||||
「Config path not found」が返る場合は、設定を追加します（[設定の要点](#config-highlights)を参照）。
|
||||
"Config path not found" が返る場合は、設定を追加します ([設定の要点](#config-highlights) を参照)。
|
||||
|
||||
2. **Plugin が有効化されていない**: Plugin ステータスを確認します。
|
||||
2. **Plugin が有効化されていない**: Plugin のステータスを確認します。
|
||||
|
||||
```bash
|
||||
openclaw plugins list | grep googlechat
|
||||
```
|
||||
|
||||
「disabled」と表示される場合は、設定に `plugins.entries.googlechat.enabled: true` を追加します。
|
||||
"disabled" と表示される場合は、設定に `plugins.entries.googlechat.enabled: true` を追加します。
|
||||
|
||||
3. **Gateway が再起動されていない**: 設定を追加した後、Gateway を再起動します。
|
||||
|
||||
@ -260,7 +260,7 @@ status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Al
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
チャンネルが実行中であることを確認します。
|
||||
チャネルが実行中であることを確認します。
|
||||
|
||||
```bash
|
||||
openclaw channels status
|
||||
@ -269,10 +269,10 @@ openclaw channels status
|
||||
|
||||
### その他の問題
|
||||
|
||||
- 認証エラーやオーディエンス設定の不足を確認するには、`openclaw channels status --probe` を確認します。
|
||||
- 認証エラーや audience 設定の欠落を確認するには、`openclaw channels status --probe` を確認します。
|
||||
- メッセージが届かない場合は、Chat アプリの Webhook URL + イベントサブスクリプションを確認します。
|
||||
- メンションゲートにより返信がブロックされる場合は、`botUser` をアプリのユーザーリソース名に設定し、`requireMention` を確認します。
|
||||
- テストメッセージの送信中に `openclaw logs --follow` を使用し、リクエストが Gateway に到達しているか確認します。
|
||||
- テストメッセージを送信しながら `openclaw logs --follow` を使用して、リクエストが Gateway に到達しているか確認します。
|
||||
|
||||
関連ドキュメント:
|
||||
|
||||
@ -282,8 +282,8 @@ openclaw channels status
|
||||
|
||||
## 関連
|
||||
|
||||
- [チャンネル概要](/ja-JP/channels) — サポートされているすべてのチャンネル
|
||||
- [チャネル概要](/ja-JP/channels) — サポートされているすべてのチャネル
|
||||
- [ペアリング](/ja-JP/channels/pairing) — DM 認証とペアリングフロー
|
||||
- [グループ](/ja-JP/channels/groups) — グループチャットの動作とメンションゲート
|
||||
- [チャンネルルーティング](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング
|
||||
- [セキュリティ](/ja-JP/gateway/security) — アクセスモデルと強化
|
||||
- [チャネルルーティング](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング
|
||||
- [セキュリティ](/ja-JP/gateway/security) — アクセスモデルと堅牢化
|
||||
|
||||
@ -2,37 +2,37 @@
|
||||
read_when:
|
||||
- グループチャットの動作またはメンションゲーティングの変更
|
||||
sidebarTitle: Groups
|
||||
summary: 各サーフェスでのグループチャット動作 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
|
||||
summary: 各サーフェスにおけるグループチャットの動作 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
|
||||
title: グループ
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:16Z"
|
||||
generated_at: "2026-05-04T02:21:35Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6fd4fcaa8335f1dc4b4b1a719d6654ab0c10530f74284269ed6205dd5f87c116
|
||||
source_hash: dea506c011a5d8f6155b2f56aacb236482cb8c5b7457001cb2171fd45932443d
|
||||
source_path: channels/groups.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw は、Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo の各サーフェスでグループチャットを一貫して扱います。
|
||||
OpenClaw は、Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo の各サーフェスで、グループチャットを一貫して扱います。
|
||||
|
||||
## 初心者向けイントロ（2分）
|
||||
## 初心者向けイントロ（2 分）
|
||||
|
||||
OpenClaw は自分のメッセージングアカウント上に「存在」します。独立した WhatsApp bot ユーザーはありません。**あなた**がグループに参加していれば、OpenClaw はそのグループを確認し、そこで応答できます。
|
||||
OpenClaw は、自分のメッセージングアカウント上に「存在」します。別個の WhatsApp ボットユーザーはありません。**あなた**がグループに参加していれば、OpenClaw はそのグループを認識し、そこで応答できます。
|
||||
|
||||
デフォルトの動作:
|
||||
|
||||
- グループは制限されます（`groupPolicy: "allowlist"`）。
|
||||
- mention gating を明示的に無効にしない限り、返信にはメンションが必要です。
|
||||
- グループ/チャンネルでの通常の最終返信は、デフォルトでは非公開です。ルームに表示される出力には `message` ツールを使います。
|
||||
- 明示的にメンションゲートを無効化しない限り、返信にはメンションが必要です。
|
||||
- グループ/チャンネルでの通常の最終返信は、デフォルトでは非公開です。ルームに見える出力には `message` ツールを使います。
|
||||
|
||||
つまり、allowlist に登録された送信者は、OpenClaw にメンションすることで起動できます。
|
||||
つまり、許可リストに登録された送信者は、OpenClaw にメンションすることでトリガーできます。
|
||||
|
||||
<Note>
|
||||
**要約**
|
||||
|
||||
- **DM アクセス**は `*.allowFrom` で制御されます。
|
||||
- **グループアクセス**は `*.groupPolicy` + allowlist（`*.groups`、`*.groupAllowFrom`）で制御されます。
|
||||
- **返信のトリガー**は mention gating（`requireMention`、`/activation`）で制御されます。
|
||||
- **グループアクセス**は `*.groupPolicy` + 許可リスト（`*.groups`、`*.groupAllowFrom`）で制御されます。
|
||||
- **返信のトリガー**はメンションゲート（`requireMention`、`/activation`）で制御されます。
|
||||
|
||||
</Note>
|
||||
|
||||
@ -45,22 +45,24 @@ requireMention? yes -> mentioned? no -> store for context only
|
||||
otherwise -> reply
|
||||
```
|
||||
|
||||
## 表示される返信
|
||||
## 見える返信
|
||||
|
||||
グループ/チャンネルのルームでは、OpenClaw のデフォルトは `messages.groupChat.visibleReplies: "message_tool"` です。
|
||||
グループ/チャンネルルームでは、OpenClaw のデフォルトは `messages.groupChat.visibleReplies: "message_tool"` です。
|
||||
`openclaw doctor --fix` は、これを省略している設定済みチャンネル設定にこのデフォルトを書き込みます。
|
||||
つまり、エージェントは引き続きターンを処理してメモリ/セッション状態を更新できますが、通常の最終回答は自動的にはルームに投稿されません。表示される形で発言するには、エージェントは `message(action=send)` を使います。
|
||||
つまり、エージェントは引き続きターンを処理し、メモリ/セッション状態を更新できますが、通常の最終回答はルームに自動投稿されません。見える形で発言するには、エージェントが `message(action=send)` を使います。
|
||||
|
||||
有効なツールポリシーの下で message ツールが利用できない場合、OpenClaw は応答を黙って抑制するのではなく、自動の表示返信にフォールバックします。
|
||||
このデフォルトは、ツールを確実に呼び出すモデル/ランタイムに依存します。ログにアシスタントテキストが表示されているのに `didSendViaMessagingTool: false` の場合、モデルはメッセージツールを呼び出さず、非公開で回答しています。これは Discord/Slack/Telegram の送信失敗ではありません。グループ/チャンネルセッションにはツール呼び出しが信頼できるモデルを使うか、`messages.groupChat.visibleReplies: "automatic"` を設定して、従来の見える最終返信を復元してください。
|
||||
|
||||
アクティブなツールポリシーでメッセージツールが利用できない場合、OpenClaw は応答を黙って抑制するのではなく、自動の見える返信にフォールバックします。
|
||||
`openclaw doctor` はこの不一致について警告します。
|
||||
|
||||
ダイレクトチャットやその他のソースターンでは、同じツール専用の表示返信動作をグローバルに適用するために `messages.visibleReplies: "message_tool"` を使います。ハーネスも、未設定時のデフォルトとしてこれを選択できます。Codex ハーネスは、Codex モードのダイレクトチャットでこれを行います。`messages.groupChat.visibleReplies` は、グループ/チャンネルのルーム向けのより具体的なオーバーライドとして残ります。
|
||||
ダイレクトチャットおよびその他の送信元ターンでは、`messages.visibleReplies: "message_tool"` を使って、同じツール専用の見える返信動作をグローバルに適用します。ハーネスもこれを未設定時のデフォルトとして選べます。Codex ハーネスは、Codex モードのダイレクトチャットでこれを行います。`messages.groupChat.visibleReplies` は、グループ/チャンネルルーム向けのより具体的なオーバーライドとして残ります。
|
||||
|
||||
これは、ほとんどの lurk モードのターンでモデルに `NO_REPLY` と答えさせる古いパターンを置き換えます。ツール専用モードでは、表示される処理を何もしないことは、単に message ツールを呼び出さないことを意味します。
|
||||
これは、ほとんどの潜伏モードのターンでモデルに `NO_REPLY` と回答させる古いパターンを置き換えます。ツール専用モードでは、見える動作を何もしないことは、単にメッセージツールを呼び出さないことを意味します。
|
||||
|
||||
ツール専用モードでエージェントが作業している間も、入力中インジケーターは送信されます。これらのターンでは、エージェントが message ツールを呼び出すかどうかを決める前に通常のアシスタントメッセージテキストが存在しない可能性があるため、デフォルトのグループ入力中モードは "message" から "instant" にアップグレードされます。明示的な入力中モード設定がある場合は、引き続きそれが優先されます。
|
||||
エージェントがツール専用モードで作業している間も、入力中インジケーターは送信されます。これらのターンでは、エージェントがメッセージツールを呼び出すかどうかを決める前に通常のアシスタントメッセージテキストが一切存在しない可能性があるため、デフォルトのグループ入力中モードは "message" から "instant" にアップグレードされます。明示的な入力中モード設定は引き続き優先されます。
|
||||
|
||||
グループ/チャンネルのルームで従来の自動最終返信を復元するには:
|
||||
グループ/チャンネルルームで従来の自動最終返信を復元するには:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -72,9 +74,9 @@ otherwise -> reply
|
||||
}
|
||||
```
|
||||
|
||||
Gateway はファイル保存後に `messages` 設定をホットリロードします。ファイル監視または設定リロードがデプロイで無効になっている場合のみ、再起動してください。
|
||||
Gateway はファイル保存後に `messages` 設定をホットリロードします。再起動が必要なのは、デプロイでファイル監視または設定リロードが無効になっている場合だけです。
|
||||
|
||||
すべてのソースチャットで表示出力を message ツール経由にするには:
|
||||
すべての送信元チャットで、見える出力にメッセージツールの経由を必須にするには:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -84,29 +86,29 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
}
|
||||
```
|
||||
|
||||
ネイティブスラッシュコマンド（Discord、Telegram、およびネイティブコマンド対応のその他のサーフェス）は `visibleReplies: "message_tool"` を迂回し、チャンネルネイティブのコマンド UI が期待する応答を受け取れるよう常に表示返信します。これは検証済みのネイティブコマンドターンにのみ適用されます。テキスト入力された `/...` コマンドや通常のチャットターンは、引き続き設定されたグループデフォルトに従います。
|
||||
ネイティブスラッシュコマンド（Discord、Telegram、およびネイティブコマンド対応のその他のサーフェス）は `visibleReplies: "message_tool"` をバイパスし、チャンネルネイティブのコマンド UI が期待する応答を受け取れるよう、常に見える形で返信します。これは検証済みのネイティブコマンドターンにのみ適用されます。テキスト入力された `/...` コマンドと通常のチャットターンは、引き続き設定済みのグループデフォルトに従います。
|
||||
|
||||
## コンテキストの可視性と allowlist
|
||||
## コンテキストの可視性と許可リスト
|
||||
|
||||
グループの安全性には、2種類の異なる制御が関係します。
|
||||
グループの安全性には、2 つの異なる制御が関係します。
|
||||
|
||||
- **トリガー認可**: 誰がエージェントを起動できるか（`groupPolicy`、`groups`、`groupAllowFrom`、チャンネル固有の allowlist）。
|
||||
- **コンテキストの可視性**: モデルに注入される補足コンテキスト（返信テキスト、引用、スレッド履歴、転送メタデータ）。
|
||||
- **トリガー認可**: 誰がエージェントをトリガーできるか（`groupPolicy`、`groups`、`groupAllowFrom`、チャンネル固有の許可リスト）。
|
||||
- **コンテキストの可視性**: どの補足コンテキストがモデルに注入されるか（返信テキスト、引用、スレッド履歴、転送メタデータ）。
|
||||
|
||||
デフォルトでは、OpenClaw は通常のチャット動作を優先し、コンテキストをほぼ受信したまま保持します。つまり、allowlist は主に誰がアクションを起動できるかを決めるものであり、すべての引用や履歴スニペットに対する普遍的な秘匿境界ではありません。
|
||||
デフォルトでは、OpenClaw は通常のチャット動作を優先し、コンテキストをほぼ受信時のまま保ちます。つまり、許可リストは主に誰がアクションをトリガーできるかを決めるものであり、引用や履歴のあらゆるスニペットに対する普遍的な墨消し境界ではありません。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="現在の動作はチャンネル固有です">
|
||||
- 一部のチャンネルでは、特定のパスで補足コンテキストに送信者ベースのフィルタリングをすでに適用しています（たとえば Slack スレッドのシード、Matrix の返信/スレッド検索）。
|
||||
- その他のチャンネルでは、引用/返信/転送コンテキストを受信したまま渡します。
|
||||
<Accordion title="Current behavior is channel-specific">
|
||||
- 一部のチャンネルでは、特定のパスで補足コンテキストに対して送信者ベースのフィルタリングがすでに適用されています（たとえば Slack のスレッドシード、Matrix の返信/スレッド検索）。
|
||||
- 他のチャンネルでは、引用/返信/転送コンテキストを受信時のまま渡しています。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="強化の方向性（計画中）">
|
||||
- `contextVisibility: "all"`（デフォルト）は、現在の受信したままの動作を維持します。
|
||||
- `contextVisibility: "allowlist"` は、補足コンテキストを allowlist に登録された送信者に絞り込みます。
|
||||
- `contextVisibility: "allowlist_quote"` は `allowlist` に加えて、1つの明示的な引用/返信の例外を許可します。
|
||||
<Accordion title="Hardening direction (planned)">
|
||||
- `contextVisibility: "all"`（デフォルト）は、現在の受信時のままの動作を維持します。
|
||||
- `contextVisibility: "allowlist"` は、補足コンテキストを許可リストに登録された送信者に絞り込みます。
|
||||
- `contextVisibility: "allowlist_quote"` は `allowlist` に、1 つの明示的な引用/返信例外を加えたものです。
|
||||
|
||||
この強化モデルがチャンネル全体で一貫して実装されるまでは、サーフェスごとの差異があるものと考えてください。
|
||||
この強化モデルがチャンネル全体で一貫して実装されるまでは、サーフェスごとの差異があると考えてください。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -117,40 +119,40 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
|
||||
| 目的 | 設定する内容 |
|
||||
| -------------------------------------------- | ---------------------------------------------------------- |
|
||||
| すべてのグループを許可し、@メンション時のみ返信する | `groups: { "*": { requireMention: true } }` |
|
||||
| すべてのグループ返信を無効にする | `groupPolicy: "disabled"` |
|
||||
| 特定のグループのみ | `groups: { "<group-id>": { ... } }`（`"*"` キーなし） |
|
||||
| グループ内で自分だけが起動できる | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
|
||||
| チャンネル間で1つの信頼済み送信者セットを再利用する | `groupAllowFrom: ["accessGroup:operators"]` |
|
||||
| すべてのグループを許可するが @メンションでのみ返信する | `groups: { "*": { requireMention: true } }` |
|
||||
| すべてのグループ返信を無効化する | `groupPolicy: "disabled"` |
|
||||
| 特定のグループのみ | `groups: { "<group-id>": { ... } }`（`"*"` キーなし） |
|
||||
| グループでトリガーできるのを自分だけにする | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
|
||||
| チャンネル間で 1 つの信頼済み送信者セットを再利用する | `groupAllowFrom: ["accessGroup:operators"]` |
|
||||
|
||||
再利用可能な送信者 allowlist については、[アクセスグループ](/ja-JP/channels/access-groups)を参照してください。
|
||||
再利用可能な送信者許可リストについては、[アクセスグループ](/ja-JP/channels/access-groups)を参照してください。
|
||||
|
||||
## セッションキー
|
||||
|
||||
- グループセッションは `agent:<agentId>:<channel>:group:<id>` セッションキーを使います（ルーム/チャンネルは `agent:<agentId>:<channel>:channel:<id>` を使います）。
|
||||
- Telegram フォーラムトピックは、各トピックが独自のセッションを持つように、グループ ID に `:topic:<threadId>` を追加します。
|
||||
- ダイレクトチャットはメインセッション（または設定されている場合は送信者ごと）を使います。
|
||||
- グループセッションでは Heartbeat はスキップされます。
|
||||
- Telegram フォーラムトピックはグループ ID に `:topic:<threadId>` を追加するため、各トピックが独自のセッションを持ちます。
|
||||
- ダイレクトチャットはメインセッションを使います（設定されている場合は送信者ごと）。
|
||||
- Heartbeat はグループセッションではスキップされます。
|
||||
|
||||
<a id="pattern-personal-dms-public-groups-single-agent"></a>
|
||||
|
||||
## パターン: 個人 DM + 公開グループ（単一エージェント）
|
||||
|
||||
はい。「個人」トラフィックが **DM** で、「公開」トラフィックが **グループ** であれば、これはうまく機能します。
|
||||
はい。この構成は、「個人」トラフィックが **DM** で、「公開」トラフィックが **グループ** の場合にうまく機能します。
|
||||
|
||||
理由: 単一エージェントモードでは、DM は通常 **メイン** セッションキー（`agent:main:main`）に入り、グループは常に **非メイン** セッションキー（`agent:main:<channel>:group:<id>`）を使います。`mode: "non-main"` でサンドボックスを有効にすると、これらのグループセッションは設定されたサンドボックスバックエンドで実行され、メインの DM セッションはホスト上に残ります。バックエンドを選択しない場合、Docker がデフォルトです。
|
||||
理由: 単一エージェントモードでは、DM は通常 **main** セッションキー（`agent:main:main`）に到達します。一方、グループは常に **non-main** セッションキー（`agent:main:<channel>:group:<id>`）を使います。`mode: "non-main"` でサンドボックス化を有効にすると、それらのグループセッションは設定されたサンドボックスバックエンド内で実行され、メインの DM セッションはホスト上に残ります。バックエンドを選択しない場合、Docker がデフォルトです。
|
||||
|
||||
これにより、1つのエージェントの「脳」（共有ワークスペース + メモリ）を持ちながら、2つの実行姿勢を使えます。
|
||||
これにより、1 つのエージェント「頭脳」（共有ワークスペース + メモリ）で、2 つの実行姿勢を持てます。
|
||||
|
||||
- **DM**: フルツール（ホスト）
|
||||
- **グループ**: サンドボックス + 制限付きツール
|
||||
|
||||
<Note>
|
||||
本当に分離されたワークスペース/ペルソナ（「個人」と「公開」を絶対に混在させてはならない）が必要な場合は、2つ目のエージェント + バインディングを使ってください。[マルチエージェントルーティング](/ja-JP/concepts/multi-agent)を参照してください。
|
||||
本当に分離されたワークスペース/ペルソナが必要な場合（「個人」と「公開」を決して混在させてはならない場合）は、2 つ目のエージェント + バインディングを使ってください。[マルチエージェントルーティング](/ja-JP/concepts/multi-agent)を参照してください。
|
||||
</Note>
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM はホスト上、グループはサンドボックス化">
|
||||
<Tab title="DMs on host, groups sandboxed">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -174,8 +176,8 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="グループには allowlist に登録されたフォルダーのみを表示">
|
||||
「ホストアクセスなし」ではなく「グループはフォルダー X だけを見られる」ようにしたい場合は、`workspaceAccess: "none"` を維持し、allowlist に登録したパスだけをサンドボックスにマウントします。
|
||||
<Tab title="Groups see only an allowlisted folder">
|
||||
「グループはホストにアクセスできない」ではなく「グループはフォルダー X のみ見える」にしたい場合は、`workspaceAccess: "none"` を維持し、許可リストに登録されたパスだけをサンドボックスへマウントしてください。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -200,20 +202,20 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
関連:
|
||||
関連情報:
|
||||
|
||||
- 設定キーとデフォルト: [Gateway 設定](/ja-JP/gateway/config-agents#agentsdefaultssandbox)
|
||||
- ツールがブロックされた理由のデバッグ: [サンドボックス vs ツールポリシー vs 昇格](/ja-JP/gateway/sandbox-vs-tool-policy-vs-elevated)
|
||||
- ツールがブロックされる理由のデバッグ: [サンドボックス vs ツールポリシー vs 昇格](/ja-JP/gateway/sandbox-vs-tool-policy-vs-elevated)
|
||||
- バインドマウントの詳細: [サンドボックス化](/ja-JP/gateway/sandboxing#custom-bind-mounts)
|
||||
|
||||
## 表示ラベル
|
||||
|
||||
- UI ラベルは、利用可能な場合は `displayName` を使い、`<channel>:<token>` としてフォーマットされます。
|
||||
- `#room` はルーム/チャンネル用に予約されています。グループチャットは `g-<slug>` を使います（小文字、スペース -> `-`、`#@+._-` は保持）。
|
||||
- UI ラベルは、利用可能な場合 `displayName` を使い、`<channel>:<token>` としてフォーマットされます。
|
||||
- `#room` はルーム/チャンネル用に予約されています。グループチャットは `g-<slug>`（小文字、スペース -> `-`、`#@+._-` は保持）を使います。
|
||||
|
||||
## グループポリシー
|
||||
|
||||
チャンネルごとにグループ/ルームメッセージの扱いを制御します。
|
||||
チャンネルごとに、グループ/ルームメッセージの扱いを制御します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -260,48 +262,48 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
}
|
||||
```
|
||||
|
||||
| ポリシー | 動作 |
|
||||
| ポリシー | 動作 |
|
||||
| ------------- | ------------------------------------------------------------ |
|
||||
| `"open"` | グループは allowlist を迂回します。mention gating は引き続き適用されます。 |
|
||||
| `"disabled"` | すべてのグループメッセージを完全にブロックします。 |
|
||||
| `"allowlist"` | 設定された allowlist に一致するグループ/ルームのみを許可します。 |
|
||||
| `"open"` | グループは許可リストをバイパスします。メンションゲートは引き続き適用されます。 |
|
||||
| `"disabled"` | すべてのグループメッセージを完全にブロックします。 |
|
||||
| `"allowlist"` | 設定済みの許可リストに一致するグループ/ルームのみを許可します。 |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="チャンネルごとの注記">
|
||||
- `groupPolicy` は mention gating（@メンションを要求するもの）とは別です。
|
||||
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: `groupAllowFrom` を使います（フォールバック: 明示的な `allowFrom`）。
|
||||
- Signal: `groupAllowFrom` は、受信した Signal グループ ID または送信者の電話番号/UUID のいずれかに一致できます。
|
||||
- DM ペアリング承認（`*-allowFrom` ストアエントリ）は DM アクセスにのみ適用されます。グループ送信者の認可は、グループ allowlist に対して明示的なままです。
|
||||
- Discord: allowlist は `channels.discord.guilds.<id>.channels` を使います。
|
||||
- Slack: allowlist は `channels.slack.channels` を使います。
|
||||
- Matrix: allowlist は `channels.matrix.groups` を使います。ルーム ID またはエイリアスを推奨します。参加済みルーム名の検索はベストエフォートで、解決できない名前は実行時に無視されます。送信者を制限するには `channels.matrix.groupAllowFrom` を使います。ルームごとの `users` allowlist もサポートされています。
|
||||
- グループ DM は別個に制御されます（`channels.discord.dm.*`、`channels.slack.dm.*`）。
|
||||
- Telegram allowlist は、ユーザー ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）またはユーザー名（`"@alice"` または `"alice"`）に一致できます。プレフィックスは大文字小文字を区別しません。
|
||||
- デフォルトは `groupPolicy: "allowlist"` です。グループ allowlist が空の場合、グループメッセージはブロックされます。
|
||||
- 実行時の安全性: プロバイダーブロックが完全に欠落している場合（`channels.<provider>` が存在しない場合）、グループポリシーは `channels.defaults.groupPolicy` を継承するのではなく、fail-closed モード（通常は `allowlist`）にフォールバックします。
|
||||
<Accordion title="Per-channel notes">
|
||||
- `groupPolicy` はメンションゲート（@mentions が必要）とは別です。
|
||||
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: `groupAllowFrom` を使用します（フォールバック: 明示的な `allowFrom`）。
|
||||
- Signal: `groupAllowFrom` は、受信した Signal グループ ID または送信者の電話番号/UUID のどちらにも一致できます。
|
||||
- DM ペアリング承認（`*-allowFrom` ストアエントリ）は DM アクセスのみに適用されます。グループ送信者の認可は、グループ許可リストに明示されたままです。
|
||||
- Discord: 許可リストは `channels.discord.guilds.<id>.channels` を使用します。
|
||||
- Slack: 許可リストは `channels.slack.channels` を使用します。
|
||||
- Matrix: 許可リストは `channels.matrix.groups` を使用します。ルーム ID またはエイリアスを推奨します。参加済みルーム名のルックアップはベストエフォートであり、解決できない名前は実行時に無視されます。送信者を制限するには `channels.matrix.groupAllowFrom` を使用します。ルーム単位の `users` 許可リストもサポートされています。
|
||||
- グループ DM は別に制御されます（`channels.discord.dm.*`、`channels.slack.dm.*`）。
|
||||
- Telegram の許可リストは、ユーザー ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）またはユーザー名（`"@alice"` または `"alice"`）に一致できます。プレフィックスは大文字小文字を区別しません。
|
||||
- デフォルトは `groupPolicy: "allowlist"` です。グループ許可リストが空の場合、グループメッセージはブロックされます。
|
||||
- 実行時の安全性: プロバイダーブロックが完全に欠落している場合（`channels.<provider>` が存在しない場合）、グループポリシーは `channels.defaults.groupPolicy` を継承する代わりに、フェイルクローズモード（通常は `allowlist`）へフォールバックします。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
簡単なメンタルモデル（グループメッセージの評価順）:
|
||||
簡単なメンタルモデル（グループメッセージの評価順序）:
|
||||
|
||||
<Steps>
|
||||
<Step title="groupPolicy">
|
||||
`groupPolicy`（open/disabled/allowlist）。
|
||||
</Step>
|
||||
<Step title="グループ許可リスト">
|
||||
グループ許可リスト（`*.groups`、`*.groupAllowFrom`、チャネル固有の許可リスト）。
|
||||
グループ許可リスト（`*.groups`、`*.groupAllowFrom`、チャンネル固有の許可リスト）。
|
||||
</Step>
|
||||
<Step title="メンション制御">
|
||||
メンション制御（`requireMention`、`/activation`）。
|
||||
<Step title="メンションゲート">
|
||||
メンションゲート（`requireMention`、`/activation`）。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## メンション制御（デフォルト）
|
||||
## メンションゲート（デフォルト）
|
||||
|
||||
グループメッセージは、グループごとに上書きされていない限りメンションを必要とします。デフォルトは各サブシステムの `*.groups."*"` にあります。
|
||||
グループメッセージには、グループ単位で上書きされない限りメンションが必要です。デフォルトは各サブシステムの `*.groups."*"` 配下にあります。
|
||||
|
||||
ボットメッセージへの返信は、チャネルが返信メタデータをサポートしている場合、暗黙のメンションとして扱われます。ボットメッセージの引用も、引用メタデータを公開するチャネルでは暗黙のメンションとして扱われる場合があります。現在の組み込みケースには、Telegram、WhatsApp、Slack、Discord、Microsoft Teams、ZaloUser が含まれます。
|
||||
チャンネルが返信メタデータをサポートしている場合、ボットメッセージへの返信は暗黙のメンションとして扱われます。引用メタデータを公開するチャンネルでは、ボットメッセージの引用も暗黙のメンションとして扱われる場合があります。現在の組み込みケースには Telegram、WhatsApp、Slack、Discord、Microsoft Teams、ZaloUser が含まれます。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -340,40 +342,40 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="メンション制御の注意事項">
|
||||
- `mentionPatterns` は大文字小文字を区別しない安全な正規表現パターンです。不正なパターンや、安全でないネストされた繰り返し形式は無視されます。
|
||||
- 明示的なメンションを提供するサーフェスは引き続き通過します。パターンはフォールバックです。
|
||||
- エージェントごとの上書き: `agents.list[].groupChat.mentionPatterns`（複数のエージェントがグループを共有する場合に便利です）。
|
||||
- メンション制御は、メンション検出が可能な場合（ネイティブメンション、または `mentionPatterns` が設定されている場合）にのみ適用されます。
|
||||
- グループまたは送信者を許可リストに入れても、メンション制御は無効になりません。すべてのメッセージでトリガーする必要がある場合は、そのグループの `requireMention` を `false` に設定してください。
|
||||
- グループチャットのプロンプトコンテキストには、解決済みのサイレント返信指示が毎ターン含まれます。ワークスペースファイルで `NO_REPLY` の仕組みを重複させるべきではありません。
|
||||
- サイレント返信が許可されているグループでは、クリーンな空のモデルターン、または推論のみのモデルターンを、`NO_REPLY` と同等のサイレントとして扱います。ダイレクトチャットでも、ダイレクトのサイレント返信が明示的に許可されている場合にのみ同じ扱いになります。それ以外の場合、空の返信は失敗したエージェントターンのままです。
|
||||
- Discord のデフォルトは `channels.discord.guilds."*"` にあります（ギルド/チャネルごとに上書き可能）。
|
||||
- グループ履歴コンテキストはチャネル間で統一的にラップされ、**保留中のみ**（メンション制御によってスキップされたメッセージ）です。グローバルデフォルトには `messages.groupChat.historyLimit` を使用し、上書きには `channels.<channel>.historyLimit`（または `channels.<channel>.accounts.*.historyLimit`）を使用します。無効化するには `0` を設定します。
|
||||
<Accordion title="Mention gating notes">
|
||||
- `mentionPatterns` は大文字小文字を区別しない安全な正規表現パターンです。無効なパターンや安全でないネストされた繰り返し形式は無視されます。
|
||||
- 明示的なメンションを提供するサーフェスはそのまま通過します。パターンはフォールバックです。
|
||||
- エージェント単位の上書き: `agents.list[].groupChat.mentionPatterns`（複数のエージェントがグループを共有する場合に便利です）。
|
||||
- メンションゲートは、メンション検出が可能な場合（ネイティブメンション、または `mentionPatterns` が設定されている場合）にのみ適用されます。
|
||||
- グループまたは送信者を許可リストに入れても、メンションゲートは無効になりません。すべてのメッセージで起動する必要がある場合は、そのグループの `requireMention` を `false` に設定します。
|
||||
- グループチャットのプロンプトコンテキストは、解決済みのサイレント返信指示を毎ターン保持します。ワークスペースファイルで `NO_REPLY` の仕組みを重複させるべきではありません。
|
||||
- サイレント返信が許可されているグループでは、空のモデルターン、または推論のみのモデルターンを `NO_REPLY` と同等のサイレントとして扱います。直接チャットでも、直接のサイレント返信が明示的に許可されている場合のみ同じ扱いになります。それ以外の場合、空の返信は失敗したエージェントターンのままです。
|
||||
- Discord のデフォルトは `channels.discord.guilds."*"` にあります（ギルド/チャンネル単位で上書き可能）。
|
||||
- グループ履歴コンテキストはチャンネル全体で一律にラップされ、**保留中のみ**（メンションゲートによってスキップされたメッセージ）です。グローバルデフォルトには `messages.groupChat.historyLimit` を使用し、上書きには `channels.<channel>.historyLimit`（または `channels.<channel>.accounts.*.historyLimit`）を使用します。無効にするには `0` を設定します。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## グループ/チャネルのツール制限（任意）
|
||||
## グループ/チャンネルのツール制限（任意）
|
||||
|
||||
一部のチャネル設定では、**特定のグループ/ルーム/チャネル内**で利用できるツールを制限できます。
|
||||
一部のチャンネル設定では、**特定のグループ/ルーム/チャンネル内**で利用できるツールを制限できます。
|
||||
|
||||
- `tools`: グループ全体のツールを許可/拒否します。
|
||||
- `toolsBySender`: グループ内の送信者ごとの上書きです。明示的なキープレフィックスを使用してください: `id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`、および `"*"` ワイルドカード。従来のプレフィックスなしキーも引き続き受け入れられ、`id:` としてのみ照合されます。
|
||||
- `toolsBySender`: グループ内の送信者単位の上書きです。明示的なキープレフィックスを使用します: `id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`、および `"*"` ワイルドカード。従来のプレフィックスなしキーも引き続き受け付けられ、`id:` としてのみ照合されます。
|
||||
|
||||
解決順（最も具体的なものが優先）:
|
||||
解決順序（最も具体的なものが優先）:
|
||||
|
||||
<Steps>
|
||||
<Step title="グループ toolsBySender">
|
||||
グループ/チャネルの `toolsBySender` の一致。
|
||||
グループ/チャンネルの `toolsBySender` の一致。
|
||||
</Step>
|
||||
<Step title="グループ tools">
|
||||
グループ/チャネルの `tools`。
|
||||
<Step title="グループツール">
|
||||
グループ/チャンネルの `tools`。
|
||||
</Step>
|
||||
<Step title="デフォルト toolsBySender">
|
||||
デフォルト（`"*"`）の `toolsBySender` の一致。
|
||||
</Step>
|
||||
<Step title="デフォルト tools">
|
||||
<Step title="デフォルトツール">
|
||||
デフォルト（`"*"`）の `tools`。
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -399,15 +401,15 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
```
|
||||
|
||||
<Note>
|
||||
グループ/チャネルのツール制限は、グローバル/エージェントのツールポリシーに追加して適用されます（拒否は引き続き優先されます）。一部のチャネルでは、ルーム/チャネルに異なるネストを使用します（例: Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
|
||||
グループ/チャンネルのツール制限は、グローバル/エージェントのツールポリシーに加えて適用されます（deny は引き続き優先されます）。一部のチャンネルでは、ルーム/チャンネルに異なるネストを使用します（例: Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
|
||||
</Note>
|
||||
|
||||
## グループ許可リスト
|
||||
|
||||
`channels.whatsapp.groups`、`channels.telegram.groups`、または `channels.imessage.groups` が設定されている場合、キーはグループ許可リストとして機能します。デフォルトのメンション動作を設定しつつ、すべてのグループを許可するには `"*"` を使用します。
|
||||
`channels.whatsapp.groups`、`channels.telegram.groups`、または `channels.imessage.groups` が設定されている場合、キーはグループ許可リストとして機能します。すべてのグループを許可しつつデフォルトのメンション動作を設定するには `"*"` を使用します。
|
||||
|
||||
<Warning>
|
||||
よくある混同: DM ペアリング承認はグループ承認と同じではありません。DM ペアリングをサポートするチャネルでは、ペアリングストアが有効化するのは DM のみです。グループコマンドには、`groupAllowFrom` やそのチャネル向けに文書化された設定フォールバックなど、設定の許可リストによる明示的なグループ送信者承認が引き続き必要です。
|
||||
よくある混同: DM ペアリング承認はグループ認可と同じではありません。DM ペアリングをサポートするチャンネルでは、ペアリングストアが解除するのは DM のみです。グループコマンドには、`groupAllowFrom` やそのチャンネルで文書化された設定フォールバックなど、設定許可リストによる明示的なグループ送信者認可が引き続き必要です。
|
||||
</Warning>
|
||||
|
||||
一般的な意図（コピー/貼り付け）:
|
||||
@ -434,7 +436,7 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="すべてのグループを許可するがメンションを必須にする">
|
||||
<Tab title="すべてのグループを許可しつつメンションを必須にする">
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
@ -462,46 +464,46 @@ Gateway はファイル保存後に `messages` 設定をホットリロードし
|
||||
|
||||
## Activation（所有者のみ）
|
||||
|
||||
グループ所有者は、グループごとの Activation を切り替えられます。
|
||||
グループ所有者はグループ単位の activation を切り替えられます。
|
||||
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
所有者は `channels.whatsapp.allowFrom`（未設定の場合はボット自身の E.164）によって決定されます。コマンドは単独のメッセージとして送信してください。他のサーフェスは現在 `/activation` を無視します。
|
||||
所有者は `channels.whatsapp.allowFrom`（未設定の場合はボット自身の E.164）によって決まります。コマンドは単独のメッセージとして送信します。現在、他のサーフェスは `/activation` を無視します。
|
||||
|
||||
## コンテキストフィールド
|
||||
|
||||
グループの受信ペイロードは次を設定します。
|
||||
グループ受信ペイロードは次を設定します。
|
||||
|
||||
- `ChatType=group`
|
||||
- `GroupSubject`（既知の場合）
|
||||
- `GroupMembers`（既知の場合）
|
||||
- `WasMentioned`（メンション制御の結果）
|
||||
- Telegram のフォーラムトピックには、`MessageThreadId` と `IsForum` も含まれます。
|
||||
- `WasMentioned`（メンションゲートの結果）
|
||||
- Telegram フォーラムトピックには `MessageThreadId` と `IsForum` も含まれます。
|
||||
|
||||
チャネル固有の注意事項:
|
||||
チャンネル固有の注記:
|
||||
|
||||
- BlueBubbles は、`GroupMembers` を設定する前に、名前のない macOS グループ参加者をローカルの連絡先データベースから任意で補完できます。これはデフォルトでオフであり、通常のグループ制御を通過した後にのみ実行されます。
|
||||
- BlueBubbles は、`GroupMembers` を設定する前に、名前のない macOS グループ参加者をローカルの連絡先データベースから任意で補強できます。これはデフォルトでオフであり、通常のグループゲートを通過した後にのみ実行されます。
|
||||
|
||||
エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループ導入が含まれます。モデルに、人間のように応答し、Markdown テーブルを避け、空行を最小限にし通常のチャット間隔に従い、リテラルの `\n` シーケンスを入力しないよう促します。チャネル由来のグループ名と参加者ラベルは、インラインのシステム指示ではなく、フェンスされた信頼されていないメタデータとしてレンダリングされます。
|
||||
エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループ導入が含まれます。これは、モデルに人間のように応答すること、Markdown テーブルを避けること、空行を最小限にして通常のチャット間隔に従うこと、リテラルの `\n` シーケンスを入力しないことを促します。チャンネル由来のグループ名と参加者ラベルは、インラインのシステム指示ではなく、フェンスされた信頼できないメタデータとしてレンダリングされます。
|
||||
|
||||
## iMessage 固有事項
|
||||
|
||||
- ルーティングまたは許可リストでは `chat_id:<id>` を優先してください。
|
||||
- ルーティングまたは許可リスト設定では `chat_id:<id>` を推奨します。
|
||||
- チャット一覧: `imsg chats --limit 20`。
|
||||
- グループ返信は常に同じ `chat_id` に戻ります。
|
||||
- グループ返信は常に同じ `chat_id` に返されます。
|
||||
|
||||
## WhatsApp システムプロンプト
|
||||
|
||||
グループおよびダイレクトのプロンプト解決、ワイルドカード動作、アカウント上書きセマンティクスを含む、正規の WhatsApp システムプロンプトルールについては、[WhatsApp](/ja-JP/channels/whatsapp#system-prompts) を参照してください。
|
||||
グループおよび直接プロンプトの解決、ワイルドカード動作、アカウント上書きセマンティクスを含む、正準の WhatsApp システムプロンプト規則については [WhatsApp](/ja-JP/channels/whatsapp#system-prompts) を参照してください。
|
||||
|
||||
## WhatsApp 固有事項
|
||||
|
||||
WhatsApp のみの動作（履歴挿入、メンション処理の詳細）については、[グループメッセージ](/ja-JP/channels/group-messages) を参照してください。
|
||||
WhatsApp のみの動作（履歴注入、メンション処理の詳細）については [グループメッセージ](/ja-JP/channels/group-messages) を参照してください。
|
||||
|
||||
## 関連
|
||||
|
||||
- [ブロードキャストグループ](/ja-JP/channels/broadcast-groups)
|
||||
- [チャネルルーティング](/ja-JP/channels/channel-routing)
|
||||
- [チャンネルルーティング](/ja-JP/channels/channel-routing)
|
||||
- [グループメッセージ](/ja-JP/channels/group-messages)
|
||||
- [ペアリング](/ja-JP/channels/pairing)
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw を IRC チャネルまたは DM に接続したい場合
|
||||
- IRC の許可リスト、グループポリシー、またはメンションゲーティングを設定している場合
|
||||
summary: IRC Plugin のセットアップ、アクセス制御、およびトラブルシューティング
|
||||
- OpenClaw を IRC チャンネルまたはダイレクトメッセージに接続したい場合
|
||||
- IRC の許可リスト、グループポリシー、またはメンション制御を設定しています
|
||||
summary: IRC Plugin のセットアップ、アクセス制御、トラブルシューティング
|
||||
title: IRC
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T04:46:13Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-04T02:21:46Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 76f316c0f026d0387a97dc5dcb6d8967f6e4841d94b95b36e42f6f6284882a69
|
||||
source_hash: 43c3098fe49a5e7405443df73e1bf752a579460dc0b2070c3d07f43b512bb555
|
||||
source_path: channels/irc.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw を IRC チャネルまたは DM に接続したい場合は IRC を使います。
|
||||
IRC は同梱 Plugin として提供されますが、設定はメイン設定の `channels.irc` で行います。
|
||||
クラシックなチャンネル（`#room`）とダイレクトメッセージで OpenClaw を使いたい場合は IRC を使用します。
|
||||
IRC はバンドルされた Plugin として提供されますが、設定はメイン設定の `channels.irc` で行います。
|
||||
|
||||
## クイックスタート
|
||||
|
||||
1. `~/.openclaw/openclaw.json` で IRC 設定を有効にします。
|
||||
2. 少なくとも次を設定します:
|
||||
2. 少なくとも次を設定します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -36,50 +36,51 @@ IRC は同梱 Plugin として提供されますが、設定はメイン設定
|
||||
}
|
||||
```
|
||||
|
||||
ボット連携にはプライベートな IRC サーバーを推奨します。意図的にパブリック IRC ネットワークを使う場合、一般的な選択肢には Libera.Chat、OFTC、Snoonet があります。ボットや swarm のバックチャネル通信には、予測しやすい公開チャネルを避けてください。
|
||||
bot の調整にはプライベート IRC サーバーを推奨します。意図的に公開 IRC ネットワークを使用する場合、一般的な選択肢には Libera.Chat、OFTC、Snoonet があります。bot や swarm のバックチャネル通信には、予測しやすい公開チャンネルを避けてください。
|
||||
|
||||
3. Gateway を起動または再起動します:
|
||||
3. Gateway を開始または再起動します。
|
||||
|
||||
```bash
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
## デフォルトのセキュリティ設定
|
||||
## セキュリティのデフォルト
|
||||
|
||||
- IRC は、OpenClaw オペレーター管理の転送プロキシルーティングの外側で raw TCP/TLS ソケットを使用します。すべての外向き通信をその転送プロキシ経由にする必要があるデプロイでは、直接の IRC 外向き通信が明示的に承認されていない限り、`channels.irc.enabled=false` を設定してください。
|
||||
- `channels.irc.dmPolicy` のデフォルトは `"pairing"` です。
|
||||
- `channels.irc.groupPolicy` のデフォルトは `"allowlist"` です。
|
||||
- `groupPolicy="allowlist"` の場合、許可するチャネルを定義するために `channels.irc.groups` を設定してください。
|
||||
- 意図的に平文トランスポートを受け入れる場合を除き、TLS（`channels.irc.tls=true`）を使用してください。
|
||||
- `groupPolicy="allowlist"` の場合、許可するチャンネルを定義するために `channels.irc.groups` を設定します。
|
||||
- 平文トランスポートを意図的に受け入れる場合を除き、TLS（`channels.irc.tls=true`）を使用してください。
|
||||
|
||||
## アクセス制御
|
||||
|
||||
IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
IRC チャンネルには 2 つの別々の「ゲート」があります。
|
||||
|
||||
1. **チャネルアクセス**（`groupPolicy` + `groups`）: ボットがそのチャネルからのメッセージをそもそも受け付けるかどうか。
|
||||
2. **送信者アクセス**（`groupAllowFrom` / チャネルごとの `groups["#channel"].allowFrom`）: そのチャネル内で誰がボットをトリガーできるか。
|
||||
1. **チャンネルアクセス**（`groupPolicy` + `groups`）：bot がそのチャンネルからのメッセージを受け入れるかどうか。
|
||||
2. **送信者アクセス**（`groupAllowFrom` / チャンネルごとの `groups["#channel"].allowFrom`）：そのチャンネル内で誰が bot を起動できるか。
|
||||
|
||||
設定キー:
|
||||
|
||||
- DM 許可リスト（DM 送信者アクセス）: `channels.irc.allowFrom`
|
||||
- グループ送信者許可リスト（チャネル送信者アクセス）: `channels.irc.groupAllowFrom`
|
||||
- チャネルごとの制御（チャネル + 送信者 + メンションルール）: `channels.irc.groups["#channel"]`
|
||||
- `channels.irc.groupPolicy="open"` は未設定のチャネルを許可します（**それでもデフォルトではメンションゲートあり**）
|
||||
- グループ送信者許可リスト（チャンネル送信者アクセス）: `channels.irc.groupAllowFrom`
|
||||
- チャンネルごとの制御（チャンネル + 送信者 + メンションルール）: `channels.irc.groups["#channel"]`
|
||||
- `channels.irc.groupPolicy="open"` は未設定のチャンネルを許可します（**ただしデフォルトでは引き続きメンションゲートが適用されます**）
|
||||
|
||||
許可リストのエントリには、安定した送信者 ID（`nick!user@host`）を使ってください。
|
||||
ニックネームのみのマッチングは変更可能であり、`channels.irc.dangerouslyAllowNameMatching: true` の場合にのみ有効です。
|
||||
許可リストのエントリには、安定した送信者 ID（`nick!user@host`）を使用してください。
|
||||
素の nick による照合は変更可能であり、`channels.irc.dangerouslyAllowNameMatching: true` の場合にのみ有効です。
|
||||
|
||||
### よくある落とし穴: `allowFrom` は DM 用であり、チャネル用ではない
|
||||
### よくある落とし穴: `allowFrom` は DM 用であり、チャンネル用ではありません
|
||||
|
||||
次のようなログが表示される場合:
|
||||
|
||||
- `irc: drop group sender alice!ident@host (policy=allowlist)`
|
||||
|
||||
これは、その送信者が**グループ/チャネル**メッセージで許可されていないことを意味します。次のいずれかで修正してください。
|
||||
…これは、送信者が **グループ/チャンネル** メッセージで許可されていなかったことを意味します。次のいずれかで修正します。
|
||||
|
||||
- `channels.irc.groupAllowFrom` を設定する（全チャネル共通のグローバル設定）、または
|
||||
- チャネルごとの送信者許可リストを設定する: `channels.irc.groups["#channel"].allowFrom`
|
||||
- `channels.irc.groupAllowFrom` を設定する（すべてのチャンネルに対してグローバル）、または
|
||||
- チャンネルごとの送信者許可リストを設定する: `channels.irc.groups["#channel"].allowFrom`
|
||||
|
||||
例（`#tuirc-dev` では誰でもボットに話しかけられるようにする）:
|
||||
例（`#tuirc-dev` の全員が bot に話しかけられるようにする）:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -94,13 +95,13 @@ IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
}
|
||||
```
|
||||
|
||||
## 返信トリガー（メンション）
|
||||
## 返信のトリガー（メンション）
|
||||
|
||||
チャネルが許可されていて（`groupPolicy` + `groups`）、送信者も許可されていても、OpenClaw はグループコンテキストではデフォルトで**メンションゲート**を使います。
|
||||
チャンネルが（`groupPolicy` + `groups` によって）許可され、送信者も許可されている場合でも、OpenClaw はグループコンテキストではデフォルトで **メンションゲート** を適用します。
|
||||
|
||||
つまり、メッセージにボットに一致するメンションパターンが含まれていない限り、`drop channel … (missing-mention)` のようなログが表示されることがあります。
|
||||
つまり、メッセージに bot と一致するメンションパターンが含まれていない限り、`drop channel … (missing-mention)` のようなログが表示されることがあります。
|
||||
|
||||
メンションを必要とせずに IRC チャネルでボットを返信させるには、そのチャネルのメンションゲートを無効にします:
|
||||
IRC チャンネルで **メンションを必要とせずに** bot に返信させるには、そのチャンネルのメンションゲートを無効にします。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -118,7 +119,7 @@ IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
}
|
||||
```
|
||||
|
||||
または、**すべての** IRC チャネルを許可し（チャネルごとの許可リストなし）、なおかつメンションなしで返信させるには:
|
||||
または、**すべての** IRC チャンネルを許可し（チャンネルごとの許可リストなし）、それでもメンションなしで返信させるには:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -133,12 +134,12 @@ IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
}
|
||||
```
|
||||
|
||||
## セキュリティ上の注意（公開チャネルでは推奨）
|
||||
## セキュリティメモ（公開チャンネルで推奨）
|
||||
|
||||
公開チャネルで `allowFrom: ["*"]` を許可すると、誰でもボットにプロンプトを送れるようになります。
|
||||
リスクを減らすには、そのチャネルで使えるツールを制限してください。
|
||||
公開チャンネルで `allowFrom: ["*"]` を許可すると、誰でも bot にプロンプトを送信できます。
|
||||
リスクを減らすには、そのチャンネルのツールを制限してください。
|
||||
|
||||
### チャネル内の全員に同じツールを適用する
|
||||
### チャンネル内の全員に同じツールを適用する
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -157,9 +158,9 @@ IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
}
|
||||
```
|
||||
|
||||
### 送信者ごとに異なるツールを適用する（所有者はより強い権限を持つ）
|
||||
### 送信者ごとに異なるツールを適用する（所有者にはより強い権限を付与）
|
||||
|
||||
`toolsBySender` を使うと、`"*"` にはより厳しいポリシーを、あなたのニックにはより緩いポリシーを適用できます:
|
||||
`toolsBySender` を使用して、`"*"` にはより厳しいポリシーを、自分の nick にはより緩いポリシーを適用します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -183,18 +184,18 @@ IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
}
|
||||
```
|
||||
|
||||
注記:
|
||||
メモ:
|
||||
|
||||
- `toolsBySender` のキーには、IRC 送信者 ID 値のために `id:` を使う必要があります:
|
||||
より強い一致には `id:eigen` または `id:eigen!~eigen@174.127.248.171` を使います。
|
||||
- 従来のプレフィックスなしキーも引き続き受け付けられ、`id:` としてのみ一致します。
|
||||
- `toolsBySender` のキーは、IRC 送信者 ID 値に対して `id:` を使用してください。
|
||||
より強い照合には `id:eigen` または `id:eigen!~eigen@174.127.248.171` を使用します。
|
||||
- 従来のプレフィックスなしキーも引き続き受け入れられ、`id:` としてのみ照合されます。
|
||||
- 最初に一致した送信者ポリシーが優先されます。`"*"` はワイルドカードのフォールバックです。
|
||||
|
||||
グループアクセスとメンションゲートの違い（およびその相互作用）について詳しくは、[/channels/groups](/ja-JP/channels/groups) を参照してください。
|
||||
グループアクセスとメンションゲートの詳細（および相互作用）については、[/channels/groups](/ja-JP/channels/groups) を参照してください。
|
||||
|
||||
## NickServ
|
||||
|
||||
接続後に NickServ で認証するには:
|
||||
接続後に NickServ で識別するには:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -210,7 +211,7 @@ IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
}
|
||||
```
|
||||
|
||||
接続時に任意の 1 回限り登録を行うには:
|
||||
接続時の任意の一度きりの登録:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -225,11 +226,11 @@ IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
}
|
||||
```
|
||||
|
||||
ニックネームの登録後は、繰り返し REGISTER が試行されるのを避けるために `register` を無効にしてください。
|
||||
nick が登録された後は、REGISTER の繰り返し試行を避けるために `register` を無効にしてください。
|
||||
|
||||
## 環境変数
|
||||
|
||||
デフォルトアカウントでは次をサポートします:
|
||||
デフォルトアカウントは次をサポートします。
|
||||
|
||||
- `IRC_HOST`
|
||||
- `IRC_PORT`
|
||||
@ -242,18 +243,18 @@ IRC チャネルには、別々の「ゲート」が 2 つあります。
|
||||
- `IRC_NICKSERV_PASSWORD`
|
||||
- `IRC_NICKSERV_REGISTER_EMAIL`
|
||||
|
||||
`IRC_HOST` はワークスペースの `.env` からは設定できません。[Workspace `.env` files](/ja-JP/gateway/security) を参照してください。
|
||||
`IRC_HOST` はワークスペースの `.env` から設定できません。[Workspace `.env` files](/ja-JP/gateway/security) を参照してください。
|
||||
|
||||
## トラブルシューティング
|
||||
|
||||
- ボットが接続してもチャネルでまったく返信しない場合は、`channels.irc.groups` **と** メンションゲートによってメッセージが落とされていないか（`missing-mention`）を確認してください。ping なしで返信させたい場合は、そのチャネルに `requireMention:false` を設定してください。
|
||||
- ログインに失敗する場合は、ニックネームの可用性とサーバーパスワードを確認してください。
|
||||
- カスタムネットワークで TLS に失敗する場合は、host/port と証明書設定を確認してください。
|
||||
- bot が接続するもののチャンネルで一切返信しない場合は、`channels.irc.groups` **および** メンションゲートがメッセージをドロップしているかどうか（`missing-mention`）を確認してください。ping なしで返信させたい場合は、そのチャンネルに `requireMention:false` を設定します。
|
||||
- ログインに失敗する場合は、nick の空き状況とサーバーパスワードを確認してください。
|
||||
- カスタムネットワークで TLS が失敗する場合は、ホスト/ポートと証明書設定を確認してください。
|
||||
|
||||
## 関連
|
||||
|
||||
- [チャネル概要](/ja-JP/channels) — サポートされているすべてのチャネル
|
||||
- [チャンネル概要](/ja-JP/channels) — サポートされているすべてのチャンネル
|
||||
- [ペアリング](/ja-JP/channels/pairing) — DM 認証とペアリングフロー
|
||||
- [グループ](/ja-JP/channels/groups) — グループチャットの動作とメンションゲート
|
||||
- [チャネルルーティング](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング
|
||||
- [セキュリティ](/ja-JP/gateway/security) — アクセスモデルとハードニング
|
||||
- [グループ](/ja-JP/channels/groups) — グループチャットの挙動とメンションゲート
|
||||
- [チャンネルルーティング](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング
|
||||
- [セキュリティ](/ja-JP/gateway/security) — アクセスモデルと強化
|
||||
|
||||
@ -1,43 +1,43 @@
|
||||
---
|
||||
read_when:
|
||||
- DMアクセス制御の設定
|
||||
- 新しい iOS/Android ノードのペアリング
|
||||
- OpenClaw のセキュリティ態勢をレビューする
|
||||
summary: 'ペアリングの概要: 誰があなたにDMを送れるか + どのノードが参加できるかを承認する'
|
||||
- 新しいiOS/Androidノードのペアリング
|
||||
- OpenClawのセキュリティ態勢をレビューする
|
||||
summary: 'ペアリングの概要: あなたにダイレクトメッセージを送れる相手 + 参加できるノードを承認する'
|
||||
title: ペアリング
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T04:49:14Z"
|
||||
generated_at: "2026-05-04T02:21:54Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: bb68d87c0e1dfe7c9a6a6d9415f4c63625755fb43a2e22a1d1374ff0a63e49c4
|
||||
source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874
|
||||
source_path: channels/pairing.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
「ペアリング」は OpenClaw の明示的なアクセス承認ステップです。
|
||||
これは 2 つの場所で使われます。
|
||||
これは 2 か所で使われます。
|
||||
|
||||
1. **DM ペアリング** (ボットとの会話を許可される相手)
|
||||
2. **Node ペアリング** (Gateway ネットワークへの参加を許可されるデバイス/Node)
|
||||
1. **DMペアリング**（bot と会話できるユーザー）
|
||||
2. **Nodeペアリング**（Gateway ネットワークへの参加を許可されるデバイス/Node）
|
||||
|
||||
セキュリティコンテキスト: [セキュリティ](/ja-JP/gateway/security)
|
||||
|
||||
## 1) DM ペアリング (インバウンドチャットアクセス)
|
||||
## 1) DMペアリング（受信チャットアクセス）
|
||||
|
||||
チャンネルが DM ポリシー `pairing` で設定されている場合、不明な送信者には短いコードが届き、承認するまでそのメッセージは**処理されません**。
|
||||
チャネルが DM ポリシー `pairing` で構成されている場合、不明な送信者には短いコードが届き、承認するまでそのメッセージは**処理されません**。
|
||||
|
||||
デフォルトの DM ポリシーは次に記載されています: [セキュリティ](/ja-JP/gateway/security)
|
||||
|
||||
`dmPolicy: "open"` が公開状態になるのは、有効な DM 許可リストに `"*"` が含まれる場合だけです。
|
||||
公開オープン設定では、セットアップと検証にこのワイルドカードが必要です。既存の
|
||||
状態に具体的な `allowFrom` エントリ付きの `open` が含まれる場合、ランタイムは引き続き
|
||||
その送信者だけを許可し、ペアリングストアの承認によって `open` アクセスが広がることはありません。
|
||||
`dmPolicy: "open"` が公開になるのは、有効な DM 許可リストに `"*"` が含まれている場合だけです。
|
||||
セットアップと検証では、公開オープン構成にこのワイルドカードが必要です。既存の
|
||||
状態に具体的な `allowFrom` エントリを持つ `open` が含まれている場合でも、ランタイムは
|
||||
それらの送信者だけを許可し、ペアリングストアの承認によって `open` アクセスが広がることはありません。
|
||||
|
||||
ペアリングコード:
|
||||
|
||||
- 8 文字、大文字、紛らわしい文字 (`0O1I`) なし。
|
||||
- **1 時間後に期限切れ**。ボットは新しいリクエストが作成されたときだけペアリングメッセージを送信します (送信者ごとにおおよそ 1 時間に 1 回)。
|
||||
- 保留中の DM ペアリングリクエストは、デフォルトで**チャンネルあたり 3 件**に制限されます。追加のリクエストは、いずれかが期限切れになるか承認されるまで無視されます。
|
||||
- 8 文字、大文字、紛らわしい文字（`0O1I`）なし。
|
||||
- **1 時間後に期限切れ**。bot は新しいリクエストが作成されたときだけペアリングメッセージを送信します（送信者ごとにおおよそ 1 時間に 1 回）。
|
||||
- 保留中の DM ペアリングリクエストはデフォルトで**チャネルあたり 3 件**に制限されます。追加のリクエストは、いずれかが期限切れになるか承認されるまで無視されます。
|
||||
|
||||
### 送信者を承認する
|
||||
|
||||
@ -46,20 +46,20 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
コマンド所有者がまだ設定されていない場合、DM ペアリングコードを承認すると、
|
||||
`commands.ownerAllowFrom` も `telegram:123456789` のような承認済み送信者でブートストラップされます。
|
||||
コマンド所有者がまだ構成されていない場合、DM ペアリングコードを承認すると、
|
||||
`commands.ownerAllowFrom` も、`telegram:123456789` のような承認済み送信者でブートストラップされます。
|
||||
これにより、初回セットアップでは特権コマンドと exec
|
||||
承認プロンプトの明示的な所有者が設定されます。所有者が存在した後は、以降のペアリング承認は DM
|
||||
アクセスのみを付与し、所有者を追加しません。
|
||||
承認プロンプトのための明示的な所有者が設定されます。所有者が存在した後は、以後のペアリング承認は DM
|
||||
アクセスだけを付与し、所有者を追加しません。
|
||||
|
||||
対応チャンネル: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`.
|
||||
対応チャネル: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`。
|
||||
|
||||
### 再利用可能な送信者グループ
|
||||
|
||||
同じ信頼済み送信者セットを複数のメッセージチャンネル、または DM とグループ許可リストの両方に適用する必要がある場合は、トップレベルの `accessGroups` を使います。
|
||||
同じ信頼済み送信者セットを複数のメッセージチャネル、または DM とグループの両方の許可リストに適用する場合は、トップレベルの `accessGroups` を使用します。
|
||||
|
||||
静的グループは `type: "message.senders"` を使い、チャンネル許可リストから
|
||||
`accessGroup:<name>` で参照します。
|
||||
静的グループは `type: "message.senders"` を使用し、チャネル許可リストから
|
||||
`accessGroup:<name>` で参照します:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -80,11 +80,11 @@ openclaw pairing approve telegram <CODE>
|
||||
}
|
||||
```
|
||||
|
||||
アクセスグループの詳細はこちらに記載されています: [アクセスグループ](/ja-JP/channels/access-groups)
|
||||
アクセスグループの詳細はここに記載されています: [アクセスグループ](/ja-JP/channels/access-groups)
|
||||
|
||||
### 状態の保存場所
|
||||
|
||||
`~/.openclaw/credentials/` 配下に保存されます。
|
||||
`~/.openclaw/credentials/` 配下に保存されます:
|
||||
|
||||
- 保留中のリクエスト: `<channel>-pairing.json`
|
||||
- 承認済み許可リストストア:
|
||||
@ -93,54 +93,54 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
アカウントスコープの動作:
|
||||
|
||||
- 非デフォルトアカウントは、スコープ付きの許可リストファイルのみを読み書きします。
|
||||
- デフォルトアカウントは、チャンネルスコープのスコープなし許可リストファイルを使います。
|
||||
- 非デフォルトアカウントは、スコープ付き許可リストファイルだけを読み書きします。
|
||||
- デフォルトアカウントは、チャネルスコープでスコープなしの許可リストファイルを使用します。
|
||||
|
||||
これらは機密として扱ってください (アシスタントへのアクセスを制御します)。
|
||||
これらは機密として扱ってください（アシスタントへのアクセスを制御します）。
|
||||
|
||||
<Note>
|
||||
ペアリング許可リストストアは DM アクセス用です。グループ承認は別です。
|
||||
ペアリング許可リストストアは DM アクセス用です。グループ認可は別です。
|
||||
DM ペアリングコードを承認しても、その送信者がグループで
|
||||
コマンドを実行したりボットを制御したりできるようにはなりません。初回所有者のブートストラップは `commands.ownerAllowFrom` の別の設定
|
||||
状態であり、グループチャット配信は引き続きチャンネルの
|
||||
グループ許可リストに従います (たとえば `groupAllowFrom`, `groups`, またはチャンネルに応じたグループ単位
|
||||
またはトピック単位のオーバーライド)。
|
||||
コマンドを実行したり bot を制御したりできるようには自動的になりません。初回所有者のブートストラップは
|
||||
`commands.ownerAllowFrom` 内の別の構成状態であり、グループチャット配信は引き続き
|
||||
チャネルのグループ許可リスト（たとえば `groupAllowFrom`、`groups`、またはチャネルに応じたグループ単位
|
||||
やトピック単位のオーバーライド）に従います。
|
||||
</Note>
|
||||
|
||||
## 2) Node デバイスペアリング (iOS/Android/macOS/ヘッドレス Node)
|
||||
## 2) Nodeデバイスペアリング（iOS/Android/macOS/ヘッドレスNode）
|
||||
|
||||
Node は `role: node` を持つ**デバイス**として Gateway に接続します。Gateway
|
||||
は承認が必要なデバイスペアリングリクエストを作成します。
|
||||
Node は `role: node` の**デバイス**として Gateway に接続します。Gateway は
|
||||
承認が必要なデバイスペアリングリクエストを作成します。
|
||||
|
||||
### Telegram 経由でペアリングする (iOS で推奨)
|
||||
### Telegram 経由でペアリングする（iOS に推奨）
|
||||
|
||||
`device-pair` plugin を使う場合、初回デバイスペアリングを Telegram だけで完了できます。
|
||||
`device-pair` Plugin を使用すると、初回のデバイスペアリングを Telegram だけで完結できます:
|
||||
|
||||
1. Telegram でボットにメッセージを送ります: `/pair`
|
||||
2. ボットは 2 通のメッセージを返信します。手順メッセージと、別の**セットアップコード**メッセージです (Telegram でコピー/貼り付けしやすい形式)。
|
||||
3. スマートフォンで OpenClaw iOS アプリを開きます → Settings → Gateway。
|
||||
1. Telegram で bot にメッセージを送ります: `/pair`
|
||||
2. bot は 2 つのメッセージで返信します。手順メッセージと、別の**セットアップコード**メッセージ（Telegram でコピー/貼り付けしやすい形式）です。
|
||||
3. 電話で OpenClaw iOS アプリを開きます → 設定 → Gateway。
|
||||
4. セットアップコードを貼り付けて接続します。
|
||||
5. Telegram に戻ります: `/pair pending` (リクエスト ID、ロール、スコープを確認)、その後承認します。
|
||||
5. Telegram に戻ります: `/pair pending`（リクエスト ID、ロール、スコープを確認）、その後承認します。
|
||||
|
||||
セットアップコードは base64 エンコードされた JSON ペイロードで、次を含みます。
|
||||
セットアップコードは base64 エンコードされた JSON ペイロードで、次を含みます:
|
||||
|
||||
- `url`: Gateway WebSocket URL (`ws://...` または `wss://...`)
|
||||
- `bootstrapToken`: 初回ペアリングハンドシェイクに使う、短命の単一デバイス用ブートストラップトークン
|
||||
- `url`: Gateway WebSocket URL（`ws://...` または `wss://...`）
|
||||
- `bootstrapToken`: 初回ペアリングハンドシェイクに使用される、短命の単一デバイス用ブートストラップトークン
|
||||
|
||||
そのブートストラップトークンには、組み込みのペアリングブートストラッププロファイルがあります。
|
||||
そのブートストラップトークンには、組み込みのペアリングブートストラッププロファイルが含まれます:
|
||||
|
||||
- 引き渡されるプライマリ `node` トークンは `scopes: []` のままです
|
||||
- 引き渡される `operator` トークンは、ブートストラップ許可リストに制限されたままです:
|
||||
- 引き渡される主要な `node` トークンは `scopes: []` のまま
|
||||
- 引き渡されるすべての `operator` トークンは、ブートストラップ許可リストに制限されたまま:
|
||||
`operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
|
||||
- ブートストラップスコープチェックはロールプレフィックス付きであり、単一のフラットなスコーププールではありません:
|
||||
- ブートストラップのスコープチェックはロール接頭辞付きであり、単一のフラットなスコーププールではありません:
|
||||
operator スコープエントリは operator リクエストだけを満たし、非 operator ロールは
|
||||
それぞれ自身のロールプレフィックス配下でスコープをリクエストする必要があります
|
||||
- 以降のトークンローテーション/失効は、デバイスの承認済み
|
||||
ロール契約と呼び出し元セッションの operator スコープの両方によって引き続き制限されます
|
||||
引き続き自身のロール接頭辞配下のスコープをリクエストする必要があります
|
||||
- 以後のトークンローテーション/失効は、デバイスの承認済み
|
||||
ロール契約と呼び出し元セッションの operator スコープの両方によって制限されたままです
|
||||
|
||||
セットアップコードは、有効な間はパスワードのように扱ってください。
|
||||
セットアップコードは有効な間、パスワードのように扱ってください。
|
||||
|
||||
### Node デバイスを承認する
|
||||
### Nodeデバイスを承認する
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
@ -148,18 +148,25 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
同じデバイスが異なる認証詳細 (たとえば異なる
|
||||
ロール/スコープ/公開鍵) で再試行した場合、以前の保留中リクエストは置き換えられ、新しい
|
||||
承認するペアリング済みデバイスセッションがペアリング専用スコープで
|
||||
開かれていたために明示的な承認が拒否された場合、CLI は同じリクエストを
|
||||
`operator.admin` で再試行します。これにより、既存の admin 対応ペアリング済みデバイスは、
|
||||
`devices/paired.json` を手動編集せずに新しい
|
||||
Control UI/ブラウザペアリングを復旧できます。Gateway は再試行された接続を引き続き検証します。
|
||||
`operator.admin` で認証できないトークンはブロックされたままです。
|
||||
|
||||
同じデバイスが異なる認証詳細（たとえば異なる
|
||||
ロール/スコープ/公開鍵）で再試行した場合、以前の保留リクエストは置き換えられ、新しい
|
||||
`requestId` が作成されます。
|
||||
|
||||
<Note>
|
||||
すでにペアリング済みのデバイスが、黙ってより広いアクセスを得ることはありません。より多くのスコープやより広いロールを要求して再接続した場合、OpenClaw は既存の承認をそのまま維持し、新しい保留中アップグレードリクエストを作成します。承認する前に `openclaw devices list` を使って、現在承認済みのアクセスと新しくリクエストされたアクセスを比較してください。
|
||||
すでにペアリング済みのデバイスが、密かにより広いアクセスを得ることはありません。より多くのスコープやより広いロールを要求して再接続した場合、OpenClaw は既存の承認をそのまま保持し、新しい保留中のアップグレードリクエストを作成します。承認する前に、`openclaw devices list` を使用して、現在承認されているアクセスと新しく要求されたアクセスを比較してください。
|
||||
</Note>
|
||||
|
||||
### 任意の信頼済み CIDR Node 自動承認
|
||||
### 任意の信頼済みCIDRによるNode自動承認
|
||||
|
||||
デバイスペアリングはデフォルトでは手動のままです。厳密に制御された Node ネットワークでは、
|
||||
明示的な CIDR または正確な IP で、初回 Node 自動承認をオプトインできます。
|
||||
明示的な CIDR または正確な IP による初回 Node 自動承認をオプトインできます:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -173,32 +180,34 @@ openclaw devices reject <requestId>
|
||||
}
|
||||
```
|
||||
|
||||
これは、リクエストされたスコープがない新規の `role: node` ペアリングリクエストにのみ適用されます。Operator、ブラウザ、Control UI、WebChat クライアントは引き続き手動承認が必要です。ロール、スコープ、メタデータ、公開鍵の変更も引き続き手動承認が必要です。
|
||||
これは、要求スコープのない新規の `role: node` ペアリングリクエストにのみ適用されます。
|
||||
Operator、ブラウザ、Control UI、WebChat クライアントは引き続き手動承認が必要です。
|
||||
ロール、スコープ、メタデータ、公開鍵の変更も引き続き手動承認が必要です。
|
||||
|
||||
### Node ペアリング状態の保存
|
||||
### Nodeペアリング状態のストレージ
|
||||
|
||||
`~/.openclaw/devices/` 配下に保存されます。
|
||||
`~/.openclaw/devices/` 配下に保存されます:
|
||||
|
||||
- `pending.json` (短命。保留中のリクエストは期限切れになります)
|
||||
- `paired.json` (ペアリング済みデバイス + トークン)
|
||||
- `pending.json`（短命。保留中のリクエストは期限切れになります）
|
||||
- `paired.json`（ペアリング済みデバイス + トークン）
|
||||
|
||||
### 注記
|
||||
|
||||
- レガシーの `node.pair.*` API (CLI: `openclaw nodes pending|approve|reject|remove|rename`) は、
|
||||
Gateway 所有の別のペアリングストアです。WS Node には引き続きデバイスペアリングが必要です。
|
||||
- レガシーの `node.pair.*` API（CLI: `openclaw nodes pending|approve|reject|remove|rename`）は、
|
||||
Gateway 所有の別個のペアリングストアです。WS Node には引き続きデバイスペアリングが必要です。
|
||||
- ペアリングレコードは、承認済みロールの永続的な信頼できる情報源です。アクティブな
|
||||
デバイストークンは、その承認済みロールセットに引き続き制限されます。承認済みロールの外にある迷い込んだトークンエントリが
|
||||
デバイストークンは、その承認済みロールセットに制限されたままです。承認済みロール外の stray token エントリが
|
||||
新しいアクセスを作成することはありません。
|
||||
|
||||
## 関連ドキュメント
|
||||
|
||||
- セキュリティモデル + プロンプトインジェクション: [セキュリティ](/ja-JP/gateway/security)
|
||||
- 安全な更新 (doctor を実行): [更新](/ja-JP/install/updating)
|
||||
- チャンネル設定:
|
||||
- 安全な更新（doctor を実行）: [更新](/ja-JP/install/updating)
|
||||
- チャネル構成:
|
||||
- Telegram: [Telegram](/ja-JP/channels/telegram)
|
||||
- WhatsApp: [WhatsApp](/ja-JP/channels/whatsapp)
|
||||
- Signal: [Signal](/ja-JP/channels/signal)
|
||||
- BlueBubbles (iMessage): [BlueBubbles](/ja-JP/channels/bluebubbles)
|
||||
- iMessage (レガシー): [iMessage](/ja-JP/channels/imessage)
|
||||
- BlueBubbles（iMessage）: [BlueBubbles](/ja-JP/channels/bluebubbles)
|
||||
- iMessage（レガシー）: [iMessage](/ja-JP/channels/imessage)
|
||||
- Discord: [Discord](/ja-JP/channels/discord)
|
||||
- Slack: [Slack](/ja-JP/channels/slack)
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw を QQ に接続したい場合
|
||||
- OpenClawをQQに接続したい場合
|
||||
- QQ Bot の認証情報の設定が必要です
|
||||
- QQ Bot のグループチャットまたはプライベートチャットのサポートが必要です
|
||||
- QQ Bot のグループチャットまたはプライベートチャットのサポートが必要な場合
|
||||
summary: QQ Bot のセットアップ、設定、使用方法
|
||||
title: QQボット
|
||||
title: QQ ボット
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:30Z"
|
||||
generated_at: "2026-05-04T02:21:53Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 471c24110bf0ab8896d22f5bb5932ac4e03ff5169560c99ba6b9d1ca4025d9a8
|
||||
source_hash: e17fa0da2f6939ed28cac5f13b3e37e6c63b87a10250ff213f7a86685a6141d6
|
||||
source_path: channels/qqbot.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
QQ Bot は公式 QQ Bot API（WebSocket gateway）経由で OpenClaw に接続します。この
|
||||
Plugin は C2C プライベートチャット、グループ @messages、ギルドチャンネルメッセージを、
|
||||
QQ Bot は公式 QQ Bot API（WebSocket Gateway）経由で OpenClaw に接続します。この
|
||||
plugin は C2C プライベートチャット、グループ @メッセージ、ギルドチャンネルメッセージを
|
||||
リッチメディア（画像、音声、動画、ファイル）付きでサポートします。
|
||||
|
||||
ステータス: ダウンロード可能な Plugin。ダイレクトメッセージ、グループチャット、ギルドチャンネル、
|
||||
ステータス: ダウンロード可能な plugin。ダイレクトメッセージ、グループチャット、ギルドチャンネル、
|
||||
メディアがサポートされています。リアクションとスレッドはサポートされていません。
|
||||
|
||||
## インストール
|
||||
|
||||
セットアップ前に QQ Bot をインストールします:
|
||||
セットアップ前に QQ Bot をインストールします。
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/qqbot
|
||||
@ -34,12 +34,12 @@ openclaw plugins install @openclaw/qqbot
|
||||
1. [QQ Open Platform](https://q.qq.com/) に移動し、スマートフォンの QQ で QR コードをスキャンして
|
||||
登録 / ログインします。
|
||||
2. **Create Bot** をクリックして新しい QQ bot を作成します。
|
||||
3. bot の設定ページで **AppID** と **AppSecret** を見つけ、コピーします。
|
||||
3. bot の設定ページで **AppID** と **AppSecret** を見つけてコピーします。
|
||||
|
||||
> AppSecret は平文では保存されません。保存せずにページを離れると、
|
||||
> AppSecret はプレーンテキストでは保存されません。保存せずにページを離れると、
|
||||
> 新しいものを再生成する必要があります。
|
||||
|
||||
4. チャンネルを追加します:
|
||||
4. チャンネルを追加します。
|
||||
|
||||
```bash
|
||||
openclaw channels add --channel qqbot --token "AppID:AppSecret"
|
||||
@ -75,7 +75,7 @@ openclaw configure --section channels
|
||||
- `QQBOT_APP_ID`
|
||||
- `QQBOT_CLIENT_SECRET`
|
||||
|
||||
ファイルで保持する AppSecret:
|
||||
ファイルベースの AppSecret:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -89,7 +89,7 @@ openclaw configure --section channels
|
||||
}
|
||||
```
|
||||
|
||||
環境変数 SecretRef の AppSecret:
|
||||
環境変数 SecretRef AppSecret:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -105,16 +105,16 @@ openclaw configure --section channels
|
||||
|
||||
注記:
|
||||
|
||||
- 環境変数フォールバックは、デフォルトの QQ Bot アカウントにのみ適用されます。
|
||||
- 環境変数フォールバックはデフォルトの QQ Bot アカウントにのみ適用されます。
|
||||
- `openclaw channels add --channel qqbot --token-file ...` は
|
||||
AppSecret のみを提供します。AppID は config または `QQBOT_APP_ID` に既に設定されている必要があります。
|
||||
- `clientSecret` は平文文字列だけでなく、SecretRef 入力も受け付けます。
|
||||
AppSecret のみを提供します。AppID は config または `QQBOT_APP_ID` にすでに設定されている必要があります。
|
||||
- `clientSecret` はプレーンテキスト文字列だけでなく、SecretRef 入力も受け付けます。
|
||||
- 従来の `secretref:/...` マーカー文字列は有効な `clientSecret` 値ではありません。
|
||||
上記の例のような構造化 SecretRef オブジェクトを使用してください。
|
||||
上記の例のような構造化された SecretRef オブジェクトを使用してください。
|
||||
|
||||
### マルチアカウントセットアップ
|
||||
### 複数アカウントのセットアップ
|
||||
|
||||
単一の OpenClaw インスタンスで複数の QQ bot を実行します:
|
||||
単一の OpenClaw インスタンスで複数の QQ bot を実行します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -136,9 +136,9 @@ openclaw configure --section channels
|
||||
```
|
||||
|
||||
各アカウントは独自の WebSocket 接続を起動し、独立した
|
||||
トークンキャッシュ（`appId` で分離）を維持します。
|
||||
トークンキャッシュ（`appId` で分離）を保持します。
|
||||
|
||||
CLI で 2 つ目の bot を追加します:
|
||||
CLI で 2 つ目の bot を追加します。
|
||||
|
||||
```bash
|
||||
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"
|
||||
@ -147,7 +147,7 @@ openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-o
|
||||
### グループチャット
|
||||
|
||||
QQ Bot のグループチャットサポートは、表示名ではなく QQ グループ OpenID を使用します。bot を
|
||||
グループに追加してから、メンションするか、メンションなしで実行するようにグループを設定します。
|
||||
グループに追加し、メンションするか、メンションなしで実行するようにグループを設定します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -176,10 +176,10 @@ QQ Bot のグループチャットサポートは、表示名ではなく QQ グ
|
||||
|
||||
`groups["*"]` はすべてのグループのデフォルトを設定し、具体的な
|
||||
`groups.GROUP_OPENID` エントリは 1 つのグループについてそれらのデフォルトを上書きします。グループ
|
||||
設定には次が含まれます:
|
||||
設定には次が含まれます。
|
||||
|
||||
- `requireMention`: bot が返信する前に @mention を要求します。デフォルト: `true`。
|
||||
- `ignoreOtherMentions`: 他の誰かにメンションしているが bot にはメンションしていないメッセージを破棄します。
|
||||
- `ignoreOtherMentions`: 他の誰かをメンションしているが bot をメンションしていないメッセージを破棄します。
|
||||
- `historyLimit`: 次にメンションされたターンのコンテキストとして、最近の非メンショングループメッセージを保持します。無効にするには `0` を設定します。
|
||||
- `toolPolicy`: グループスコープのツールに対する `full`、`restricted`、または `none`。
|
||||
- `name`: ログとグループコンテキストで使用されるわかりやすいラベル。
|
||||
@ -189,17 +189,18 @@ QQ Bot のグループチャットサポートは、表示名ではなく QQ グ
|
||||
`mention` に対応し、`requireMention: false` は `always` に対応します。セッションレベルのアクティベーション
|
||||
上書きが存在する場合は、config より優先されます。
|
||||
|
||||
受信キューはピアごとです。グループピアにはより大きなキュー上限があり、満杯時は bot 作成の雑談より人間の
|
||||
メッセージを優先し、通常のグループメッセージのバーストを 1 つの送信者付きターンにマージします。スラッシュコマンドは引き続き 1 つずつ実行されます。
|
||||
インバウンドキューはピアごとです。グループピアにはより大きなキュー上限があり、いっぱいになったときは bot が作成した雑談よりも人間の
|
||||
メッセージを優先し、通常の
|
||||
グループメッセージのバーストを 1 つの帰属付きターンにマージします。スラッシュコマンドは引き続き 1 つずつ実行されます。
|
||||
|
||||
### 音声（STT / TTS）
|
||||
|
||||
STT と TTS は、優先フォールバック付きの 2 レベル設定をサポートします:
|
||||
STT と TTS は、優先フォールバック付きの 2 レベル設定をサポートします。
|
||||
|
||||
| 設定 | Plugin 固有 | フレームワークのフォールバック |
|
||||
| ---- | ------------------------------------------------------ | ------------------------------- |
|
||||
| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` |
|
||||
| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts.<id>.tts` | `messages.tts` |
|
||||
| 設定 | Plugin 固有 | フレームワークフォールバック |
|
||||
| ------- | -------------------------------------------------------- | ----------------------------- |
|
||||
| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` |
|
||||
| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts.<id>.tts` | `messages.tts` |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -215,7 +216,7 @@ STT と TTS は、優先フォールバック付きの 2 レベル設定をサ
|
||||
voice: "your-voice",
|
||||
},
|
||||
accounts: {
|
||||
qq-main: {
|
||||
"qq-main": {
|
||||
tts: {
|
||||
providers: {
|
||||
openai: { voice: "shimmer" },
|
||||
@ -228,15 +229,15 @@ STT と TTS は、優先フォールバック付きの 2 レベル設定をサ
|
||||
}
|
||||
```
|
||||
|
||||
どちらも無効にするには `enabled: false` を設定します。
|
||||
アカウントレベルの TTS 上書きは `messages.tts` と同じ形を使用し、チャンネル/グローバルの TTS config の上にディープマージされます。
|
||||
いずれかを無効にするには `enabled: false` を設定します。
|
||||
アカウントレベルの TTS 上書きは `messages.tts` と同じ形状を使用し、チャンネル / グローバル TTS config の上にディープマージされます。
|
||||
|
||||
受信 QQ 音声添付ファイルは、汎用 `MediaPaths` から生の音声ファイルを除外したまま、
|
||||
音声メディアメタデータとしてエージェントに公開されます。TTS が
|
||||
設定されている場合、`[[audio_as_voice]]` の平文返信は TTS を合成し、ネイティブ QQ 音声メッセージを送信します。
|
||||
インバウンドの QQ 音声添付ファイルは、raw 音声ファイルを汎用 `MediaPaths` の外に保ちながら、
|
||||
音声メディアメタデータとしてエージェントに公開されます。`[[audio_as_voice]]` プレーン
|
||||
テキスト返信は、TTS が設定されている場合に TTS を合成し、ネイティブ QQ 音声メッセージを送信します。
|
||||
|
||||
送信音声のアップロード/トランスコード動作は
|
||||
`channels.qqbot.audioFormatPolicy` でも調整できます:
|
||||
アウトバウンド音声のアップロード / トランスコード動作も
|
||||
`channels.qqbot.audioFormatPolicy` で調整できます。
|
||||
|
||||
- `sttDirectFormats`
|
||||
- `uploadDirectFormats`
|
||||
@ -244,65 +245,64 @@ STT と TTS は、優先フォールバック付きの 2 レベル設定をサ
|
||||
|
||||
## ターゲット形式
|
||||
|
||||
| 形式 | 説明 |
|
||||
| -------------------------- | ---------------------- |
|
||||
| 形式 | 説明 |
|
||||
| -------------------------- | ------------------ |
|
||||
| `qqbot:c2c:OPENID` | プライベートチャット（C2C） |
|
||||
| `qqbot:group:GROUP_OPENID` | グループチャット |
|
||||
| `qqbot:group:GROUP_OPENID` | グループチャット |
|
||||
| `qqbot:channel:CHANNEL_ID` | ギルドチャンネル |
|
||||
|
||||
> 各 bot には独自のユーザー OpenID セットがあります。Bot A が受信した OpenID は、
|
||||
> Bot B 経由でメッセージを送信するためには使用できません。
|
||||
> Bot B 経由でメッセージを送信するために使用することは**できません**。
|
||||
|
||||
## スラッシュコマンド
|
||||
|
||||
AI キューの前にインターセプトされる組み込みコマンド:
|
||||
|
||||
| コマンド | 説明 |
|
||||
| コマンド | 説明 |
|
||||
| -------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `/bot-ping` | レイテンシーテスト |
|
||||
| `/bot-version` | OpenClaw フレームワークのバージョンを表示 |
|
||||
| `/bot-help` | すべてのコマンドを一覧表示 |
|
||||
| `/bot-me` | `allowFrom`/`groupAllowFrom` セットアップ用に送信者の QQ ユーザー ID（openid）を表示 |
|
||||
| `/bot-me` | `allowFrom`/`groupAllowFrom` セットアップ用に送信者の QQ ユーザー ID（openid）を表示 |
|
||||
| `/bot-upgrade` | QQBot アップグレードガイドのリンクを表示 |
|
||||
| `/bot-logs` | 最近の gateway ログをファイルとしてエクスポート |
|
||||
| `/bot-approve` | 保留中の QQ Bot アクション（例: C2C またはグループアップロードの確認）をネイティブフローで承認します。 |
|
||||
| `/bot-logs` | 最近の Gateway ログをファイルとしてエクスポート |
|
||||
| `/bot-approve` | ネイティブフローを通じて保留中の QQ Bot アクション（例: C2C またはグループアップロードの確認）を承認します。 |
|
||||
|
||||
使用方法のヘルプを表示するには、任意のコマンドに `?` を追加します（例: `/bot-upgrade ?`）。
|
||||
|
||||
管理コマンド（`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`）はダイレクトメッセージ専用で、送信者の openid が明示的な非ワイルドカードの `allowFrom` リストに含まれている必要があります。ワイルドカード `allowFrom: ["*"]` はチャットを許可しますが、管理コマンドアクセスは付与しません。グループメッセージはまず `groupAllowFrom` と照合され、その後 `allowFrom` にフォールバックします。グループで管理コマンドを実行すると、黙って破棄するのではなくヒントが返されます。
|
||||
管理者コマンド（`/bot-me`、`/bot-upgrade`、`/bot-logs`、`/bot-clear-storage`、`/bot-streaming`、`/bot-approve`）はダイレクトメッセージ専用であり、送信者の openid が明示的な非ワイルドカードの `allowFrom` リストに含まれている必要があります。ワイルドカード `allowFrom: ["*"]` はチャットを許可しますが、管理者コマンドアクセスは付与しません。グループメッセージはまず `groupAllowFrom` と照合され、次に `allowFrom` にフォールバックします。グループで管理者コマンドを実行すると、黙って破棄されるのではなくヒントが返されます。
|
||||
|
||||
## エンジンアーキテクチャ
|
||||
|
||||
QQ Bot は Plugin 内の自己完結型エンジンとして提供されます:
|
||||
QQ Bot は plugin 内の自己完結型エンジンとして提供されます。
|
||||
|
||||
- 各アカウントは `appId` をキーとする分離されたリソーススタック（WebSocket 接続、API クライアント、トークンキャッシュ、メディアストレージルート）を所有します。アカウント間で受信/送信状態が共有されることはありません。
|
||||
- マルチアカウントロガーはログ行に所有アカウントをタグ付けするため、1 つの gateway で複数の bot を実行している場合でも診断を分離できます。
|
||||
- 受信、送信、gateway ブリッジの各パスは `~/.openclaw/media` 配下の単一メディアペイロードルートを共有するため、アップロード、ダウンロード、トランスコードキャッシュはサブシステムごとのツリーではなく、1 つの保護されたディレクトリに配置されます。
|
||||
- リッチメディア配信は、C2C とグループターゲットの両方で 1 つの `sendMedia` パスを通ります。大きなファイルのしきい値を超えるローカルファイルとバッファーは QQ のチャンクアップロードエンドポイントを使用し、小さいペイロードはワンショットメディア API を使用します。
|
||||
- 認証情報は標準の OpenClaw 認証情報スナップショットの一部としてバックアップおよび復元できます。エンジンは復元時に、QR コードペアを新たに要求せずに各アカウントのリソーススタックを再アタッチします。
|
||||
- 各アカウントは、`appId` でキー付けされた分離リソーススタック（WebSocket 接続、API クライアント、トークンキャッシュ、メディアストレージルート）を所有します。アカウントがインバウンド / アウトバウンド状態を共有することはありません。
|
||||
- 複数アカウントロガーは、所有アカウントでログ行にタグ付けするため、1 つの Gateway で複数の bot を実行しても診断を分離したままにできます。
|
||||
- インバウンド、アウトバウンド、Gateway ブリッジのパスは、`~/.openclaw/media` 配下の単一のメディアペイロードルートを共有するため、アップロード、ダウンロード、トランスコードキャッシュはサブシステムごとのツリーではなく、1 つの保護されたディレクトリ配下に配置されます。
|
||||
- リッチメディア配信は、C2C とグループターゲット向けに 1 つの `sendMedia` パスを通ります。大きなファイルのしきい値を超えるローカルファイルとバッファは QQ のチャンク分割アップロードエンドポイントを使用し、小さなペイロードはワンショットメディア API を使用します。
|
||||
- 認証情報は標準の OpenClaw 認証情報スナップショットの一部としてバックアップおよび復元できます。エンジンは復元時に、新しい QR コードペアを要求せずに各アカウントのリソーススタックを再アタッチします。
|
||||
|
||||
## QR コードオンボーディング
|
||||
|
||||
`AppID:AppSecret` を手動で貼り付ける代替として、このエンジンは QQ Bot を OpenClaw にリンクするための QR コードオンボーディングフローをサポートします:
|
||||
`AppID:AppSecret` を手動で貼り付ける代替として、エンジンは QQ Bot を OpenClaw にリンクするための QR コードオンボーディングフローをサポートします。
|
||||
|
||||
1. QQ Bot セットアップパス（例: `openclaw channels add --channel qqbot`）を実行し、プロンプトで QR コードフローを選択します。
|
||||
2. ターゲット QQ Bot に紐付いたスマートフォンアプリで、生成された QR コードをスキャンします。
|
||||
3. スマートフォンでペアリングを承認します。OpenClaw は返された認証情報を、適切なアカウントスコープの `credentials/` に永続化します。
|
||||
1. QQ Bot セットアップパス（例: `openclaw channels add --channel qqbot`）を実行し、プロンプトが表示されたら QR コードフローを選択します。
|
||||
2. 対象の QQ Bot に紐づいたスマートフォンアプリで、生成された QR コードをスキャンします。
|
||||
3. スマートフォンでペアリングを承認します。OpenClaw は返された認証情報を、正しいアカウントスコープ配下の `credentials/` に永続化します。
|
||||
|
||||
bot 自体によって生成された承認プロンプト（例: QQ Bot API が公開する「このアクションを許可しますか?」フロー）は、raw QQ クライアントで返信するのではなく `/bot-approve` で受け入れられるネイティブ OpenClaw プロンプトとして表示されます。
|
||||
bot 自体によって生成される承認プロンプト（例: QQ Bot API によって公開される「このアクションを許可しますか?」フロー）は、raw QQ クライアントで返信する代わりに `/bot-approve` で承認できるネイティブ OpenClaw プロンプトとして表示されます。
|
||||
|
||||
## トラブルシューティング
|
||||
|
||||
- **Bot が「gone to Mars」と返信する:** 認証情報が設定されていないか、Gateway が起動していません。
|
||||
- **受信メッセージがない:** `appId` と `clientSecret` が正しいこと、および
|
||||
bot が QQ Open Platform で有効になっていることを確認してください。
|
||||
- **自己返信が繰り返される:** OpenClaw は QQ の送信 ref インデックスを
|
||||
bot 作成として記録し、現在の `msgIdx` が同じ bot アカウントと一致する受信イベントを無視します。
|
||||
これにより、ユーザーが以前の bot メッセージを引用または返信することは許可しつつ、プラットフォームのエコーループを防ぎます。
|
||||
- **インバウンドメッセージがない:** `appId` と `clientSecret` が正しく、bot が QQ Open Platform で有効になっていることを確認してください。
|
||||
- **自己返信が繰り返される:** OpenClaw は QQ アウトバウンド参照インデックスを
|
||||
bot 作成として記録し、現在の `msgIdx` が同じ
|
||||
bot アカウントと一致するインバウンドイベントを無視します。これにより、プラットフォームのエコーループを防ぎつつ、ユーザーが以前の bot メッセージを引用または返信することは引き続き可能になります。
|
||||
- **`--token-file` でセットアップしても未設定と表示される:** `--token-file` は
|
||||
AppSecret のみを設定します。config または `QQBOT_APP_ID` に `appId` も必要です。
|
||||
- **プロアクティブメッセージが届かない:** ユーザーが最近やり取りしていない場合、QQ が bot 主導のメッセージをインターセプトすることがあります。
|
||||
- **音声が文字起こしされない:** STT が設定されていて、プロバイダーに到達できることを確認してください。
|
||||
- **プロアクティブメッセージが届かない:** ユーザーが最近操作していない場合、QQ が bot 起点のメッセージをインターセプトすることがあります。
|
||||
- **音声が文字起こしされない:** STT が設定され、プロバイダーに到達できることを確認してください。
|
||||
|
||||
## 関連
|
||||
|
||||
|
||||
@ -1,57 +1,57 @@
|
||||
---
|
||||
read_when:
|
||||
- Tlon/Urbit チャンネル機能の作業中
|
||||
- Tlon/Urbit チャネル機能に取り組む
|
||||
summary: Tlon/Urbit のサポート状況、機能、設定
|
||||
title: Tlon
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:16:34Z"
|
||||
generated_at: "2026-05-04T02:22:34Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 30915170786fc1ee8b84fb8be2ea42280262923064cfa9ca7107036096a13add
|
||||
source_hash: 1718044541b431ff2437508e7e6659c14206f4aa84ab8b207e0d791dea2a48c5
|
||||
source_path: channels/tlon.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Tlon は Urbit 上に構築された分散型メッセンジャーです。OpenClaw はあなたの Urbit ship に接続し、
|
||||
DM とグループチャットメッセージに応答できます。グループ返信にはデフォルトで @ メンションが必要で、
|
||||
allowlist でさらに制限できます。
|
||||
DM とグループチャットメッセージに応答できます。グループ返信ではデフォルトで @ メンションが必要で、
|
||||
allowlist によってさらに制限できます。
|
||||
|
||||
ステータス: バンドル済みPlugin。DM、グループメンション、スレッド返信、リッチテキスト書式、
|
||||
ステータス: バンドル済み Plugin。DM、グループメンション、スレッド返信、リッチテキスト書式設定、
|
||||
画像アップロードがサポートされています。リアクションと投票はまだサポートされていません。
|
||||
|
||||
## バンドル済みPlugin
|
||||
## バンドル済み Plugin
|
||||
|
||||
Tlon は現在の OpenClaw リリースではバンドル済みPluginとして同梱されるため、通常のパッケージ版
|
||||
ビルドでは別途インストールは不要です。
|
||||
Tlon は現在の OpenClaw リリースにバンドル済み Plugin として同梱されているため、通常のパッケージ済み
|
||||
ビルドでは個別のインストールは不要です。
|
||||
|
||||
古いビルド、または Tlon を除外したカスタムインストールを使っている場合は、現在の
|
||||
npm パッケージをインストールします。
|
||||
古いビルドを使用している場合や、Tlon を除外したカスタムインストールの場合は、
|
||||
現在の npm パッケージをインストールしてください。
|
||||
|
||||
CLI でインストール (npm registry):
|
||||
CLI 経由でインストール (npm registry):
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/tlon
|
||||
```
|
||||
|
||||
現在の公式リリースタグに追従するには、素のパッケージを使用してください。再現可能な
|
||||
インストールが必要な場合にのみ正確なバージョンに固定します。
|
||||
現在の公式リリースタグに追従するには、bare パッケージを使用します。再現可能な
|
||||
インストールが必要な場合にのみ、正確なバージョンを固定してください。
|
||||
|
||||
ローカルチェックアウト (git repo から実行する場合):
|
||||
ローカル checkout (git repo から実行する場合):
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/tlon-plugin
|
||||
```
|
||||
|
||||
詳細: [Plugin](/ja-JP/tools/plugin)
|
||||
詳細: [Plugins](/ja-JP/tools/plugin)
|
||||
|
||||
## セットアップ
|
||||
|
||||
1. Tlon Plugin が利用可能であることを確認します。
|
||||
- 現在のパッケージ版 OpenClaw リリースにはすでにバンドルされています。
|
||||
- 現在のパッケージ済み OpenClaw リリースにはすでにバンドルされています。
|
||||
- 古い/カスタムインストールでは、上記のコマンドで手動追加できます。
|
||||
2. ship URL とログインコードを用意します。
|
||||
3. `channels.tlon` を設定します。
|
||||
4. gateway を再起動します。
|
||||
4. Gateway を再起動します。
|
||||
5. bot に DM するか、グループチャンネルでメンションします。
|
||||
|
||||
最小設定 (単一アカウント):
|
||||
@ -72,8 +72,8 @@ openclaw plugins install ./path/to/local/tlon-plugin
|
||||
|
||||
## プライベート/LAN ship
|
||||
|
||||
デフォルトでは、OpenClaw は SSRF 保護のためプライベート/内部ホスト名と IP 範囲をブロックします。
|
||||
あなたの ship がプライベートネットワーク (localhost、LAN IP、または内部ホスト名) で動作している場合、
|
||||
デフォルトでは、OpenClaw は SSRF 保護のためにプライベート/内部ホスト名と IP 範囲をブロックします。
|
||||
ship がプライベートネットワーク (localhost、LAN IP、または内部ホスト名) で実行されている場合は、
|
||||
明示的にオプトインする必要があります。
|
||||
|
||||
```json5
|
||||
@ -93,7 +93,7 @@ openclaw plugins install ./path/to/local/tlon-plugin
|
||||
- `http://192.168.x.x:8080`
|
||||
- `http://my-ship.local:8080`
|
||||
|
||||
⚠️ ローカルネットワークを信頼している場合にのみ有効にしてください。この設定は、
|
||||
⚠️ これはローカルネットワークを信頼している場合にのみ有効にしてください。この設定は、
|
||||
ship URL へのリクエストに対する SSRF 保護を無効にします。
|
||||
|
||||
## グループチャンネル
|
||||
@ -110,7 +110,7 @@ ship URL へのリクエストに対する SSRF 保護を無効にします。
|
||||
}
|
||||
```
|
||||
|
||||
自動検出を無効化します。
|
||||
自動検出を無効にします。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -136,7 +136,7 @@ DM allowlist (空 = DM は許可されません。承認フローには `ownerSh
|
||||
}
|
||||
```
|
||||
|
||||
グループ認可 (デフォルトでは制限あり):
|
||||
グループ認可 (デフォルトで制限):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,7 +159,7 @@ DM allowlist (空 = DM は許可されません。承認フローには `ownerSh
|
||||
}
|
||||
```
|
||||
|
||||
## オーナーと承認システム
|
||||
## owner と承認システム
|
||||
|
||||
未認可ユーザーが操作しようとしたときに承認リクエストを受け取る owner ship を設定します。
|
||||
|
||||
@ -173,19 +173,19 @@ DM allowlist (空 = DM は許可されません。承認フローには `ownerSh
|
||||
}
|
||||
```
|
||||
|
||||
owner ship は **どこでも自動的に認可されます** — DM 招待は自動承認され、
|
||||
チャンネルメッセージは常に許可されます。owner を `dmAllowlist` または
|
||||
owner ship は **すべての場所で自動的に認可されます** — DM 招待は自動承認され、
|
||||
チャンネルメッセージは常に許可されます。owner を `dmAllowlist` や
|
||||
`defaultAuthorizedShips` に追加する必要はありません。
|
||||
|
||||
設定すると、owner は次について DM 通知を受け取ります。
|
||||
設定すると、owner は次の DM 通知を受け取ります。
|
||||
|
||||
- allowlist に含まれない ship からの DM リクエスト
|
||||
- 認可のないチャンネルでのメンション
|
||||
- allowlist にない ship からの DM リクエスト
|
||||
- 認可なしのチャンネルでのメンション
|
||||
- グループ招待リクエスト
|
||||
|
||||
## 自動承認設定
|
||||
|
||||
DM 招待を自動承認します (`dmAllowlist` 内の ship 向け):
|
||||
DM 招待を自動承認します (`dmAllowlist` 内の ship の場合):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -197,56 +197,59 @@ DM 招待を自動承認します (`dmAllowlist` 内の ship 向け):
|
||||
}
|
||||
```
|
||||
|
||||
グループ招待を自動承認します。
|
||||
信頼済み ship からのグループ招待を自動承認します。
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
tlon: {
|
||||
autoAcceptGroupInvites: true,
|
||||
groupInviteAllowlist: ["~zod"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 配信先 (CLI/Cron)
|
||||
`autoAcceptGroupInvites` は `groupInviteAllowlist` が空の場合、fail closed になります。
|
||||
自動的に承認するグループ招待元の ship を allowlist に設定してください。
|
||||
|
||||
`openclaw message send` または Cron 配信でこれらを使用します。
|
||||
## 配信先 (CLI/cron)
|
||||
|
||||
`openclaw message send` または cron 配信でこれらを使用します。
|
||||
|
||||
- DM: `~sampel-palnet` または `dm/~sampel-palnet`
|
||||
- グループ: `chat/~host-ship/channel` または `group:~host-ship/channel`
|
||||
|
||||
## バンドル済みスキル
|
||||
## バンドル済み skill
|
||||
|
||||
Tlon Plugin には、Tlon 操作への CLI アクセスを提供するバンドル済みスキル
|
||||
([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill))
|
||||
Tlon Plugin には、Tlon 操作への CLI アクセスを提供するバンドル済み skill ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill))
|
||||
が含まれています。
|
||||
|
||||
- **連絡先**: プロフィールの取得/更新、連絡先一覧
|
||||
- **チャンネル**: 一覧、作成、メッセージ投稿、履歴取得
|
||||
- **グループ**: 一覧、作成、メンバー管理
|
||||
- **チャンネル**: 一覧表示、作成、メッセージ投稿、履歴取得
|
||||
- **グループ**: 一覧表示、作成、メンバー管理
|
||||
- **DM**: メッセージ送信、メッセージへのリアクション
|
||||
- **リアクション**: 投稿と DM への絵文字リアクションの追加/削除
|
||||
- **設定**: スラッシュコマンドによるPlugin権限の管理
|
||||
- **リアクション**: 投稿と DM に emoji リアクションを追加/削除
|
||||
- **設定**: slash command 経由で Plugin 権限を管理
|
||||
|
||||
このスキルは、Plugin がインストールされると自動的に利用可能になります。
|
||||
この skill は Plugin がインストールされると自動的に利用可能になります。
|
||||
|
||||
## 機能
|
||||
|
||||
| 機能 | ステータス |
|
||||
| --------------- | --------------------------------------- |
|
||||
| ダイレクトメッセージ | ✅ サポートされています |
|
||||
| グループ/チャンネル | ✅ サポートされています (デフォルトではメンション制御) |
|
||||
| スレッド | ✅ サポートされています (スレッド内で自動返信) |
|
||||
| リッチテキスト | ✅ Markdown を Tlon 形式に変換します |
|
||||
| 画像 | ✅ Tlon ストレージにアップロードします |
|
||||
| リアクション | ✅ [バンドル済みスキル](#bundled-skill) 経由 |
|
||||
| 投票 | ❌ まだサポートされていません |
|
||||
| ネイティブコマンド | ✅ サポートされています (デフォルトでは owner のみ) |
|
||||
| 機能 | ステータス |
|
||||
| --------------------- | ----------------------------------------------- |
|
||||
| ダイレクトメッセージ | ✅ サポート済み |
|
||||
| グループ/チャンネル | ✅ サポート済み (デフォルトでメンション必須) |
|
||||
| スレッド | ✅ サポート済み (スレッド内で自動返信) |
|
||||
| リッチテキスト | ✅ Markdown を Tlon 形式に変換 |
|
||||
| 画像 | ✅ Tlon ストレージにアップロード |
|
||||
| リアクション | ✅ [バンドル済み skill](#bundled-skill) 経由 |
|
||||
| 投票 | ❌ まだサポートされていません |
|
||||
| ネイティブコマンド | ✅ サポート済み (デフォルトで owner のみ) |
|
||||
|
||||
## トラブルシューティング
|
||||
|
||||
まずこの手順を実行します。
|
||||
まずこの手順を実行してください。
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -259,8 +262,8 @@ openclaw doctor
|
||||
|
||||
- **DM が無視される**: 送信者が `dmAllowlist` に含まれておらず、承認フロー用の `ownerShip` も設定されていません。
|
||||
- **グループメッセージが無視される**: チャンネルが検出されていないか、送信者が認可されていません。
|
||||
- **接続エラー**: ship URL に到達可能か確認してください。ローカル ship では `allowPrivateNetwork` を有効にしてください。
|
||||
- **認証エラー**: ログインコードが現在のものか確認してください (コードはローテーションされます)。
|
||||
- **接続エラー**: ship URL に到達できることを確認してください。ローカル ship には `allowPrivateNetwork` を有効にしてください。
|
||||
- **認証エラー**: ログインコードが現在有効であることを確認してください (コードはローテーションされます)。
|
||||
|
||||
## 設定リファレンス
|
||||
|
||||
@ -272,13 +275,14 @@ openclaw doctor
|
||||
- `channels.tlon.ship`: bot の Urbit ship 名 (例: `~sampel-palnet`)。
|
||||
- `channels.tlon.url`: ship URL (例: `https://sampel-palnet.tlon.network`)。
|
||||
- `channels.tlon.code`: ship ログインコード。
|
||||
- `channels.tlon.allowPrivateNetwork`: localhost/LAN URL を許可します (SSRF バイパス)。
|
||||
- `channels.tlon.ownerShip`: 承認システム用の owner ship (常に認可)。
|
||||
- `channels.tlon.allowPrivateNetwork`: localhost/LAN URL を許可します (SSRF bypass)。
|
||||
- `channels.tlon.ownerShip`: 承認システム用の owner ship (常に認可済み)。
|
||||
- `channels.tlon.dmAllowlist`: DM を許可された ship (空 = なし)。
|
||||
- `channels.tlon.autoAcceptDmInvites`: allowlist に含まれる ship からの DM を自動承認します。
|
||||
- `channels.tlon.autoAcceptGroupInvites`: すべてのグループ招待を自動承認します。
|
||||
- `channels.tlon.autoAcceptGroupInvites`: allowlist に含まれる ship からのグループ招待を自動承認します。
|
||||
- `channels.tlon.groupInviteAllowlist`: グループ招待を自動承認できる ship。
|
||||
- `channels.tlon.autoDiscoverChannels`: グループチャンネルを自動検出します (デフォルト: true)。
|
||||
- `channels.tlon.groupChannels`: 手動で固定したチャンネル nest。
|
||||
- `channels.tlon.groupChannels`: 手動で固定されたチャンネル nest。
|
||||
- `channels.tlon.defaultAuthorizedShips`: すべてのチャンネルで認可される ship。
|
||||
- `channels.tlon.authorization.channelRules`: チャンネルごとの認可ルール。
|
||||
- `channels.tlon.showModelSignature`: メッセージにモデル名を追加します。
|
||||
@ -287,13 +291,13 @@ openclaw doctor
|
||||
|
||||
- グループ返信では、応答するためにメンション (例: `~your-bot-ship`) が必要です。
|
||||
- スレッド返信: 受信メッセージがスレッド内にある場合、OpenClaw はスレッド内で返信します。
|
||||
- リッチテキスト: Markdown 書式 (太字、斜体、コード、ヘッダー、リスト) は Tlon のネイティブ形式に変換されます。
|
||||
- リッチテキスト: Markdown 書式 (太字、斜体、コード、見出し、リスト) は Tlon のネイティブ形式に変換されます。
|
||||
- 画像: URL は Tlon ストレージにアップロードされ、画像ブロックとして埋め込まれます。
|
||||
|
||||
## 関連
|
||||
|
||||
- [チャンネル概要](/ja-JP/channels) — サポートされているすべてのチャンネル
|
||||
- [ペアリング](/ja-JP/channels/pairing) — DM 認証とペアリングフロー
|
||||
- [グループ](/ja-JP/channels/groups) — グループチャットの動作とメンション制御
|
||||
- [グループ](/ja-JP/channels/groups) — グループチャットの動作とメンションゲート
|
||||
- [チャンネルルーティング](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング
|
||||
- [セキュリティ](/ja-JP/gateway/security) — アクセスモデルと強化
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
read_when:
|
||||
- チャネルのトランスポートは接続済みと表示されるが、返信に失敗する
|
||||
- 詳細なプロバイダードキュメントを読む前に、チャネル固有のチェックが必要です
|
||||
summary: チャネルごとの障害シグネチャと修正による、迅速なチャネルレベルのトラブルシューティング
|
||||
- 詳細なプロバイダードキュメントに進む前に、チャネル固有のチェックが必要です。
|
||||
summary: チャンネル別の失敗シグネチャと修正策を使った迅速なチャンネルレベルのトラブルシューティング
|
||||
title: チャンネルのトラブルシューティング
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T05:01:36Z"
|
||||
generated_at: "2026-05-04T02:22:42Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6024f2ae0a058b2296758c237c912a5cd8ea6bbafea33cc201690cc081efcbee
|
||||
source_hash: a3a0737156ae83897c44d18505e0355a5d8e5700106b984496d94874c270deb2
|
||||
source_path: channels/troubleshooting.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
チャネルが接続されているのに動作が誤っている場合は、このページを使用してください。
|
||||
チャンネルは接続されるが、動作が正しくない場合にこのページを使用します。
|
||||
|
||||
## コマンド手順
|
||||
|
||||
まず、次を順番に実行します。
|
||||
まず次を順に実行します。
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -27,23 +27,23 @@ openclaw doctor
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
正常なベースライン:
|
||||
正常な基準状態:
|
||||
|
||||
- `Runtime: running`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`、`write-capable`、または `admin-capable`
|
||||
- チャネルのプローブでトランスポートが接続済みと表示され、サポートされている場合は `works` または `audit ok` と表示される
|
||||
- チャンネルプローブでトランスポートが接続済みであり、対応している場合は `works` または `audit ok` が表示される
|
||||
|
||||
## WhatsApp
|
||||
|
||||
### WhatsApp の障害シグネチャ
|
||||
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 接続済みだが DM に返信しない | `openclaw pairing list whatsapp` | 送信者を承認するか、DM ポリシー/許可リストを切り替えます。 |
|
||||
| グループメッセージが無視される | 設定の `requireMention` + メンションパターンを確認 | ボットにメンションするか、そのグループのメンションポリシーを緩和します。 |
|
||||
| QR ログインが 408 でタイムアウトする | Gateway の `HTTPS_PROXY` / `HTTP_PROXY` env を確認 | 到達可能なプロキシを設定します。`NO_PROXY` はバイパスのみに使用します。 |
|
||||
| ランダムな切断/再ログインループ | `openclaw channels status --probe` + ログ | 現在接続されていても、最近の再接続はフラグ付けされます。ログを監視し、Gateway を再起動してから、フラッピングが続く場合は再リンクします。 |
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 接続済みだが DM 返信がない | `openclaw pairing list whatsapp` | 送信者を承認するか、DM ポリシー/許可リストを切り替えます。 |
|
||||
| グループメッセージが無視される | config の `requireMention` とメンションパターンを確認 | bot をメンションするか、そのグループのメンションポリシーを緩和します。 |
|
||||
| QR ログインが 408 でタイムアウトする | Gateway の `HTTPS_PROXY` / `HTTP_PROXY` env を確認 | 到達可能なプロキシを設定します。`NO_PROXY` はバイパスにのみ使用します。 |
|
||||
| ランダムな切断/再ログインループ | `openclaw channels status --probe` + ログ | 現在接続中でも最近の再接続はフラグ付けされます。ログを監視し、Gateway を再起動してから、フラッピングが続く場合は再リンクします。 |
|
||||
|
||||
完全なトラブルシューティング: [WhatsApp のトラブルシューティング](/ja-JP/channels/whatsapp#troubleshooting)
|
||||
|
||||
@ -51,15 +51,15 @@ openclaw channels status --probe
|
||||
|
||||
### Telegram の障害シグネチャ
|
||||
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/start` したが利用可能な返信フローがない | `openclaw pairing list telegram` | ペアリングを承認するか、DM ポリシーを変更します。 |
|
||||
| ボットはオンラインだがグループが沈黙したまま | メンション要件とボットのプライバシーモードを確認 | グループでの可視性のためにプライバシーモードを無効にするか、ボットにメンションします。 |
|
||||
| ネットワークエラーで送信に失敗する | Telegram API 呼び出し失敗のログを調査する | `api.telegram.org` への DNS/IPv6/プロキシルーティングを修正します。 |
|
||||
| 起動時に `getMe returned 401` と報告される | 設定済みトークンソースを確認する | BotFather トークンを再コピーまたは再生成し、`botToken`、`tokenFile`、またはデフォルトアカウントの `TELEGRAM_BOT_TOKEN` を更新します。 |
|
||||
| ポーリングが停止する、または再接続が遅い | ポーリング診断について `openclaw logs --follow` を確認 | アップグレードします。再起動が誤検出の場合は、`pollingStallThresholdMs` を調整します。停止が継続する場合は、依然としてプロキシ/DNS/IPv6 が原因です。 |
|
||||
| 起動時に `setMyCommands` が拒否される | `BOT_COMMANDS_TOO_MUCH` のログを調査する | Plugin/skill/カスタム Telegram コマンドを減らすか、ネイティブメニューを無効にします。 |
|
||||
| アップグレード後に許可リストでブロックされる | `openclaw security audit` と設定の許可リスト | `openclaw doctor --fix` を実行するか、`@username` を数値の送信者 ID に置き換えます。 |
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| -------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/start` しても使用可能な返信フローがない | `openclaw pairing list telegram` | ペアリングを承認するか、DM ポリシーを変更します。 |
|
||||
| bot はオンラインだがグループが沈黙したまま | メンション要件と bot のプライバシーモードを確認 | グループで表示できるようにプライバシーモードを無効にするか、bot をメンションします。 |
|
||||
| ネットワークエラーで送信に失敗する | Telegram API 呼び出しの失敗をログで調査 | `api.telegram.org` への DNS/IPv6/プロキシルーティングを修正します。 |
|
||||
| 起動時に `getMe returned 401` が報告される | 設定済みのトークンソースを確認 | BotFather トークンを再コピーまたは再生成し、`botToken`、`tokenFile`、またはデフォルトアカウントの `TELEGRAM_BOT_TOKEN` を更新します。 |
|
||||
| ポーリングが停止する、または再接続が遅い | ポーリング診断のために `openclaw logs --follow` | アップグレードします。再起動が誤検知の場合は `pollingStallThresholdMs` を調整します。永続的な停止は引き続きプロキシ/DNS/IPv6 を示します。 |
|
||||
| 起動時に `setMyCommands` が拒否される | `BOT_COMMANDS_TOO_MUCH` をログで調査 | Plugin/skill/custom Telegram コマンドを減らすか、ネイティブメニューを無効にします。 |
|
||||
| アップグレード後に許可リストでブロックされる | `openclaw security audit` と config の許可リスト | `openclaw doctor --fix` を実行するか、`@username` を数値の送信者 ID に置き換えます。 |
|
||||
|
||||
完全なトラブルシューティング: [Telegram のトラブルシューティング](/ja-JP/channels/telegram#troubleshooting)
|
||||
|
||||
@ -67,11 +67,12 @@ openclaw channels status --probe
|
||||
|
||||
### Discord の障害シグネチャ
|
||||
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ------------------------------- | ----------------------------------- | --------------------------------------------------------- |
|
||||
| ボットはオンラインだがギルドで返信しない | `openclaw channels status --probe` | ギルド/チャネルを許可し、メッセージコンテンツインテントを確認します。 |
|
||||
| グループメッセージが無視される | メンションゲートによるドロップのログを確認 | ボットにメンションするか、ギルド/チャネルの `requireMention: false` を設定します。 |
|
||||
| DM 返信がない | `openclaw pairing list discord` | DM ペアリングを承認するか、DM ポリシーを調整します。 |
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ----------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| bot はオンラインだが guild で返信がない | `openclaw channels status --probe` | guild/channel を許可し、メッセージコンテンツ intent を確認します。 |
|
||||
| グループメッセージが無視される | メンションゲートによるドロップをログで確認 | bot をメンションするか、guild/channel の `requireMention: false` を設定します。 |
|
||||
| 入力中/トークン使用はあるが Discord メッセージがない | セッションログに `didSendViaMessagingTool: false` の assistant text が表示される | モデルが message tool を呼ばずに非公開で回答しています。ツール呼び出しが信頼できるモデルを使用するか、`messages.groupChat.visibleReplies: "automatic"` を設定して自動投稿します。 |
|
||||
| DM 返信がない | `openclaw pairing list discord` | DM ペアリングを承認するか、DM ポリシーを調整します。 |
|
||||
|
||||
完全なトラブルシューティング: [Discord のトラブルシューティング](/ja-JP/channels/discord#troubleshooting)
|
||||
|
||||
@ -79,11 +80,11 @@ openclaw channels status --probe
|
||||
|
||||
### Slack の障害シグネチャ
|
||||
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Socket mode は接続済みだが応答がない | `openclaw channels status --probe` | アプリトークン + ボットトークンと必要なスコープを確認します。SecretRef ベースのセットアップでは `botTokenStatus` / `appTokenStatus = configured_unavailable` に注意します。 |
|
||||
| DM がブロックされる | `openclaw pairing list slack` | ペアリングを承認するか、DM ポリシーを緩和します。 |
|
||||
| チャネルメッセージが無視される | `groupPolicy` とチャネル許可リストを確認 | チャネルを許可するか、ポリシーを `open` に切り替えます。 |
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Socket mode は接続済みだが応答がない | `openclaw channels status --probe` | app token + bot token と必要な scopes を確認します。SecretRef に基づくセットアップでは `botTokenStatus` / `appTokenStatus = configured_unavailable` に注意します。 |
|
||||
| DM がブロックされる | `openclaw pairing list slack` | ペアリングを承認するか、DM ポリシーを緩和します。 |
|
||||
| チャンネルメッセージが無視される | `groupPolicy` とチャンネル許可リストを確認 | チャンネルを許可するか、ポリシーを `open` に切り替えます。 |
|
||||
|
||||
完全なトラブルシューティング: [Slack のトラブルシューティング](/ja-JP/channels/slack#troubleshooting)
|
||||
|
||||
@ -91,11 +92,11 @@ openclaw channels status --probe
|
||||
|
||||
### iMessage と BlueBubbles の障害シグネチャ
|
||||
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| 受信イベントがない | Webhook/サーバーの到達性とアプリ権限を確認 | Webhook URL または BlueBubbles サーバー状態を修正します。 |
|
||||
| macOS で送信はできるが受信できない | Messages 自動化の macOS プライバシー権限を確認 | TCC 権限を再付与し、チャネルプロセスを再起動します。 |
|
||||
| DM 送信者がブロックされる | `openclaw pairing list imessage` または `openclaw pairing list bluebubbles` | ペアリングを承認するか、許可リストを更新します。 |
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| --------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| 受信イベントがない | Webhook/サーバーの到達性とアプリ権限を確認 | Webhook URL または BlueBubbles サーバー状態を修正します。 |
|
||||
| macOS で送信はできるが受信できない | Messages automation の macOS プライバシー権限を確認 | TCC 権限を再付与し、チャンネルプロセスを再起動します。 |
|
||||
| DM 送信者がブロックされる | `openclaw pairing list imessage` または `openclaw pairing list bluebubbles` | ペアリングを承認するか、許可リストを更新します。 |
|
||||
|
||||
完全なトラブルシューティング:
|
||||
|
||||
@ -106,11 +107,11 @@ openclaw channels status --probe
|
||||
|
||||
### Signal の障害シグネチャ
|
||||
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
|
||||
| デーモンには到達可能だがボットが沈黙する | `openclaw channels status --probe` | `signal-cli` デーモン URL/アカウントと受信モードを確認します。 |
|
||||
| DM がブロックされる | `openclaw pairing list signal` | 送信者を承認するか、DM ポリシーを調整します。 |
|
||||
| グループ返信がトリガーされない | グループ許可リストとメンションパターンを確認 | 送信者/グループを追加するか、ゲートを緩和します。 |
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| --------------------------------- | ------------------------------------------- | ---------------------------------------------------------- |
|
||||
| daemon は到達可能だが bot が沈黙する | `openclaw channels status --probe` | `signal-cli` daemon URL/account と受信モードを確認します。 |
|
||||
| DM がブロックされる | `openclaw pairing list signal` | 送信者を承認するか、DM ポリシーを調整します。 |
|
||||
| グループ返信がトリガーされない | グループ許可リストとメンションパターンを確認 | 送信者/グループを追加するか、ゲートを緩和します。 |
|
||||
|
||||
完全なトラブルシューティング: [Signal のトラブルシューティング](/ja-JP/channels/signal#troubleshooting)
|
||||
|
||||
@ -118,12 +119,12 @@ openclaw channels status --probe
|
||||
|
||||
### QQ Bot の障害シグネチャ
|
||||
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
|
||||
| ボットが "gone to Mars" と返信する | 設定の `appId` と `clientSecret` を確認 | 認証情報を設定するか、Gateway を再起動します。 |
|
||||
| 受信メッセージがない | `openclaw channels status --probe` | QQ Open Platform の認証情報を確認します。 |
|
||||
| 音声が文字起こしされない | STT プロバイダー設定を確認 | `channels.qqbot.stt` または `tools.media.audio` を設定します。 |
|
||||
| プロアクティブメッセージが届かない | QQ プラットフォームのインタラクション要件を確認 | 最近のインタラクションがない場合、QQ がボット起点のメッセージをブロックする可能性があります。 |
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ----------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| bot が「gone to Mars」と返信する | config の `appId` と `clientSecret` を確認 | 認証情報を設定するか、Gateway を再起動します。 |
|
||||
| 受信メッセージがない | `openclaw channels status --probe` | QQ Open Platform で認証情報を確認します。 |
|
||||
| 音声が文字起こしされない | STT プロバイダー config を確認 | `channels.qqbot.stt` または `tools.media.audio` を設定します。 |
|
||||
| プロアクティブメッセージが届かない | QQ platform のインタラクション要件を確認 | 直近のインタラクションがない場合、QQ は bot 起点のメッセージをブロックすることがあります。 |
|
||||
|
||||
完全なトラブルシューティング: [QQ Bot のトラブルシューティング](/ja-JP/channels/qqbot#troubleshooting)
|
||||
|
||||
@ -131,18 +132,18 @@ openclaw channels status --probe
|
||||
|
||||
### Matrix の障害シグネチャ
|
||||
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| ログイン済みだがルームメッセージを無視する | `openclaw channels status --probe` | `groupPolicy`、ルーム許可リスト、メンションゲートを確認します。 |
|
||||
| DM が処理されない | `openclaw pairing list matrix` | 送信者を承認するか、DM ポリシーを調整します。 |
|
||||
| 暗号化ルームが失敗する | `openclaw matrix verify status` | デバイスを再確認し、その後 `openclaw matrix verify backup status` を確認します。 |
|
||||
| バックアップ復元が保留中/壊れている | `openclaw matrix verify backup status` | `openclaw matrix verify backup restore` を実行するか、リカバリキーを使って再実行します。 |
|
||||
| クロス署名/ブートストラップが誤って見える | `openclaw matrix verify bootstrap` | シークレットストレージ、クロス署名、バックアップ状態を 1 回で修復します。 |
|
||||
| 症状 | 最速の確認 | 修正 |
|
||||
| ----------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| ログイン済みだがルームメッセージを無視する | `openclaw channels status --probe` | `groupPolicy`、ルーム許可リスト、メンションゲートを確認します。 |
|
||||
| DM が処理されない | `openclaw pairing list matrix` | 送信者を承認するか、DM ポリシーを調整します。 |
|
||||
| 暗号化ルームが失敗する | `openclaw matrix verify status` | デバイスを再検証し、その後 `openclaw matrix verify backup status` を確認します。 |
|
||||
| バックアップ復元が保留中/壊れている | `openclaw matrix verify backup status` | `openclaw matrix verify backup restore` を実行するか、リカバリーキーを使って再実行します。 |
|
||||
| クロス署名/bootstrap が正しく見えない | `openclaw matrix verify bootstrap` | secret storage、クロス署名、バックアップ状態を 1 回で修復します。 |
|
||||
|
||||
完全なセットアップと設定: [Matrix](/ja-JP/channels/matrix)
|
||||
完全なセットアップと config: [Matrix](/ja-JP/channels/matrix)
|
||||
|
||||
## 関連
|
||||
|
||||
- [ペアリング](/ja-JP/channels/pairing)
|
||||
- [チャネルルーティング](/ja-JP/channels/channel-routing)
|
||||
- [チャンネルルーティング](/ja-JP/channels/channel-routing)
|
||||
- [Gateway のトラブルシューティング](/ja-JP/gateway/troubleshooting)
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 接続/認証の問題があり、ガイド付きの修正を行いたい
|
||||
- 更新後にサニティチェックを行いたい場合
|
||||
summary: '`openclaw doctor` の CLI リファレンス（ヘルスチェック + ガイド付き修復）'
|
||||
- 接続や認証の問題があり、ガイド付きの修正を利用したい場合
|
||||
- 更新後に健全性チェックをしたい場合
|
||||
summary: '`openclaw doctor` の CLI リファレンス (ヘルスチェック + ガイド付き修復)'
|
||||
title: 診断
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:28:36Z"
|
||||
generated_at: "2026-05-04T02:22:48Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d4baab5b0cd4d046d12ae5bd14ccf05224115856d45e630a57e77a2be15e5db0
|
||||
source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905
|
||||
source_path: cli/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -34,45 +34,45 @@ openclaw doctor --generate-gateway-token
|
||||
|
||||
## オプション
|
||||
|
||||
- `--no-workspace-suggestions`: ワークスペースメモリ/検索の提案を無効にする
|
||||
- `--yes`: 確認なしでデフォルトを受け入れる
|
||||
- `--repair`: 確認なしで推奨される非サービス修復を適用する。Gateway サービスのインストールと書き換えには、引き続き対話的な確認または明示的な Gateway コマンドが必要
|
||||
- `--fix`: `--repair` のエイリアス
|
||||
- `--force`: 必要に応じてカスタムサービス設定の上書きを含む、積極的な修復を適用する
|
||||
- `--non-interactive`: プロンプトなしで実行する。安全なマイグレーションと非サービス修復のみ
|
||||
- `--no-workspace-suggestions`: ワークスペースのメモリ/検索候補を無効にする
|
||||
- `--yes`: プロンプトなしでデフォルトを受け入れる
|
||||
- `--repair`: プロンプトなしで推奨される非サービス修復を適用する。Gateway サービスのインストールと書き換えには、引き続き対話的な確認または明示的な Gateway コマンドが必要
|
||||
- `--fix`: `--repair` の別名
|
||||
- `--force`: 必要に応じてカスタムサービス設定の上書きを含む、強力な修復を適用する
|
||||
- `--non-interactive`: プロンプトなしで実行する。安全な移行と非サービス修復のみ
|
||||
- `--generate-gateway-token`: Gateway トークンを生成して設定する
|
||||
- `--deep`: 追加の Gateway インストールがないかシステムサービスをスキャンする
|
||||
|
||||
注:
|
||||
注記:
|
||||
|
||||
- 対話型プロンプト（keychain/OAuth 修復など）は、stdin が TTY で、`--non-interactive` が設定されて**いない**場合にのみ実行されます。ヘッドレス実行（cron、Telegram、ターミナルなし）ではプロンプトはスキップされます。
|
||||
- パフォーマンス: 非対話型の `doctor` 実行では、ヘッドレスのヘルスチェックを高速に保つため、先行 Plugin 読み込みをスキップします。対話型セッションでは、チェックで Plugin の寄与が必要な場合、引き続き Plugin を完全に読み込みます。
|
||||
- `--fix`（`--repair` のエイリアス）は、バックアップを `~/.openclaw/openclaw.json.bak` に書き込み、不明な設定キーを削除し、削除ごとに一覧表示します。
|
||||
- `doctor --fix --non-interactive` は、Gateway サービス定義の欠落または古さを報告しますが、更新修復モード以外ではインストールや書き換えを行いません。サービスがない場合は `openclaw gateway install` を実行し、ランチャーを意図的に置き換える場合は `openclaw gateway install --force` を実行します。
|
||||
- 状態整合性チェックは、sessions ディレクトリ内の孤立したトランスクリプトファイルを検出するようになりました。それらを `.deleted.<timestamp>` としてアーカイブするには対話的な確認が必要です。`--fix`、`--yes`、ヘッドレス実行ではそのまま残します。
|
||||
- Doctor は `~/.openclaw/cron/jobs.json`（または `cron.store`）もスキャンして、レガシー cron ジョブ形状を検出し、スケジューラが実行時に自動正規化する前に、その場で書き換えることができます。
|
||||
- Linux では、ユーザーの crontab がまだレガシーの `~/.openclaw/bin/ensure-whatsapp.sh` を実行している場合、doctor が警告します。このスクリプトはもう保守されておらず、cron に systemd ユーザーバス環境がない場合、誤った WhatsApp Gateway 障害をログに出力する可能性があります。
|
||||
- Doctor は古い OpenClaw バージョンで作成されたレガシー Plugin 依存関係のステージング状態をクリーンアップします。また、レジストリで解決できる場合は、設定済みで欠落しているダウンロード可能 Plugin を修復します。さらに 2026.5.2 の doctor パスでは、古い設定がすでに使用しているダウンロード可能 Plugin を自動的にインストールしてから、そのリリース向けに設定を変更済みとしてマークします。
|
||||
- Doctor は、Plugin 検出が正常な場合に、`plugins.allow`/`plugins.entries` から欠落している Plugin ID を削除し、一致する未参照のチャンネル設定、Heartbeat ターゲット、チャンネルモデルオーバーライドも削除することで、古い Plugin 設定を修復します。
|
||||
- Doctor は、影響を受けた `plugins.entries.<id>` エントリを無効化し、無効な `config` ペイロードを削除することで、無効な Plugin 設定を隔離します。Gateway 起動時にはすでに、その問題のある Plugin だけをスキップするため、他の Plugin とチャンネルは実行を継続できます。
|
||||
- 別のスーパーバイザーが Gateway ライフサイクルを所有している場合は、`OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。Doctor は引き続き Gateway/サービスの健全性を報告し、非サービス修復を適用しますが、サービスの install/start/restart/bootstrap とレガシーサービスのクリーンアップはスキップします。
|
||||
- Linux では、doctor は非アクティブな追加の Gateway 風 systemd ユニットを無視し、修復中に実行中の systemd Gateway サービスの command/entrypoint メタデータを書き換えません。アクティブなランチャーを意図的に置き換える場合は、まずサービスを停止するか、`openclaw gateway install --force` を使用してください。
|
||||
- Doctor はレガシーのフラットな Talk 設定（`talk.voiceId`、`talk.modelId` など）を `talk.provider` + `talk.providers.<provider>` に自動移行します。
|
||||
- `doctor --fix` を繰り返し実行しても、唯一の差分がオブジェクトキー順序だけの場合、Talk 正規化を報告/適用しなくなりました。
|
||||
- Doctor にはメモリ検索準備チェックが含まれており、埋め込み認証情報がない場合は `openclaw configure --section model` を推奨できます。
|
||||
- Doctor はコマンド所有者が設定されていない場合に警告します。コマンド所有者は、所有者専用コマンドの実行と危険な操作の承認を許可された人間のオペレーターアカウントです。DM ペアリングは、誰かがボットと会話できるようにするだけです。初回所有者の bootstrap が存在する前に送信者を承認していた場合は、`commands.ownerAllowFrom` を明示的に設定してください。
|
||||
- Doctor は、Codex モードのエージェントが設定され、個人の Codex CLI アセットがオペレーターの Codex ホームに存在する場合に警告します。ローカルの Codex アプリサーバー起動では、エージェントごとに分離されたホームを使用するため、意図的に昇格すべきアセットを棚卸しするには `openclaw migrate codex --dry-run` を使用してください。
|
||||
- Doctor は、デフォルトエージェントに許可されている Skills が、bin、環境変数、設定、または OS 要件の不足により現在のランタイム環境で利用できない場合に警告します。`doctor --fix` は、`skills.entries.<skill>.enabled=false` でそれらの利用不可 Skills を無効化できます。Skill を有効なままにしたい場合は、不足している要件を代わりにインストール/設定してください。
|
||||
- サンドボックスモードが有効でも Docker が利用できない場合、doctor は修復方法（`install Docker` または `openclaw config set agents.defaults.sandbox.mode off`）を含む高シグナルの警告を報告します。
|
||||
- レガシーサンドボックスレジストリファイル（`~/.openclaw/sandbox/containers.json` または `~/.openclaw/sandbox/browsers.json`）が存在する場合、doctor はそれらを報告します。`openclaw doctor --fix` は、有効なエントリをシャーディングされたレジストリディレクトリに移行し、無効なレガシーファイルを隔離します。
|
||||
- `gateway.auth.token`/`gateway.auth.password` が SecretRef 管理で、現在のコマンドパスで利用できない場合、doctor は読み取り専用の警告を報告し、平文のフォールバック認証情報を書き込みません。
|
||||
- 修復パスでチャンネル SecretRef 検査に失敗した場合、doctor は早期終了せずに続行し、警告を報告します。
|
||||
- 状態ディレクトリの移行後、doctor は、有効なデフォルト Telegram または Discord アカウントが環境フォールバックに依存していて、`TELEGRAM_BOT_TOKEN` または `DISCORD_BOT_TOKEN` が doctor プロセスで利用できない場合に警告します。
|
||||
- Telegram の `allowFrom` ユーザー名自動解決（`doctor --fix`）には、現在のコマンドパスで解決可能な Telegram トークンが必要です。トークン検査が利用できない場合、doctor は警告を報告し、そのパスの自動解決をスキップします。
|
||||
- 対話的プロンプト（keychain/OAuth 修正など）は、stdin が TTY で、かつ `--non-interactive` が設定されて**いない**場合にのみ実行されます。ヘッドレス実行（cron、Telegram、ターミナルなし）ではプロンプトはスキップされます。
|
||||
- パフォーマンス: 非対話型の `doctor` 実行では、ヘッドレスのヘルスチェックを高速に保つため、積極的な Plugin 読み込みをスキップします。対話型セッションでは、チェックで Plugin の寄与が必要な場合、引き続き Plugin を完全に読み込みます。
|
||||
- `--fix`（`--repair` の別名）はバックアップを `~/.openclaw/openclaw.json.bak` に書き込み、不明な設定キーを削除して、各削除を一覧表示します。
|
||||
- `doctor --fix --non-interactive` は、Gateway サービス定義の欠落または古さを報告しますが、更新修復モード以外ではインストールや書き換えは行いません。サービスがない場合は `openclaw gateway install` を実行し、ランチャーを意図的に置き換えたい場合は `openclaw gateway install --force` を実行します。
|
||||
- 状態整合性チェックは、sessions ディレクトリ内の孤立した transcript ファイルを検出するようになりました。それらを `.deleted.<timestamp>` としてアーカイブするには対話的な確認が必要です。`--fix`、`--yes`、ヘッドレス実行ではそのまま残します。
|
||||
- Doctor は `~/.openclaw/cron/jobs.json`（または `cron.store`）もスキャンして、レガシーな Cron ジョブ形状を検出し、スケジューラが実行時に自動正規化する前にその場で書き換えることができます。
|
||||
- Linux では、ユーザーの crontab がまだレガシーな `~/.openclaw/bin/ensure-whatsapp.sh` を実行している場合、doctor が警告します。このスクリプトは保守されておらず、cron に systemd ユーザーバス環境がない場合に誤った WhatsApp Gateway 障害をログに記録する可能性があります。
|
||||
- Doctor は、古い OpenClaw バージョンで作成されたレガシー Plugin 依存関係のステージング状態をクリーンアップします。また、レジストリで解決できる場合は、設定済みで欠落しているダウンロード可能 Plugin も修復します。2026.5.2 の doctor パスでは、そのリリース用に設定を変更済みとしてマークする前に、古い設定ですでに使用されているダウンロード可能 Plugin を自動的にインストールします。ダウンロードに失敗した場合、doctor はインストールエラーを報告し、次回の修復試行のために設定済み Plugin エントリを保持します。
|
||||
- Doctor は、Plugin 検出が正常な場合に、欠落している Plugin ID を `plugins.allow`/`plugins.entries` から削除し、対応する不要なチャンネル設定、Heartbeat ターゲット、チャンネルモデル上書きも削除して、古い Plugin 設定を修復します。
|
||||
- Doctor は、影響を受ける `plugins.entries.<id>` エントリを無効化し、その無効な `config` ペイロードを削除することで、無効な Plugin 設定を隔離します。Gateway 起動時はすでに、その不正な Plugin だけをスキップするため、他の Plugin とチャンネルは実行を継続できます。
|
||||
- 別のスーパーバイザーが Gateway ライフサイクルを所有している場合は、`OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。Doctor は引き続き Gateway/サービスのヘルスを報告し、非サービス修復を適用しますが、サービスのインストール/開始/再起動/ブートストラップとレガシーサービスのクリーンアップはスキップします。
|
||||
- Linux では、doctor は非アクティブな追加の Gateway 風 systemd ユニットを無視し、修復中に実行中の systemd Gateway サービスのコマンド/エントリポイントメタデータを書き換えません。アクティブなランチャーを意図的に置き換えたい場合は、先にサービスを停止するか、`openclaw gateway install --force` を使用します。
|
||||
- Doctor は、レガシーなフラット Talk 設定（`talk.voiceId`、`talk.modelId` など）を `talk.provider` + `talk.providers.<provider>` に自動移行します。
|
||||
- `doctor --fix` の繰り返し実行では、差分がオブジェクトキー順序だけの場合、Talk 正規化の報告/適用を行わなくなりました。
|
||||
- Doctor にはメモリ検索の準備状況チェックが含まれ、埋め込み認証情報が欠落している場合に `openclaw configure --section model` を推奨できます。
|
||||
- Doctor は、コマンド所有者が設定されていない場合に警告します。コマンド所有者とは、所有者専用コマンドの実行と危険な操作の承認を許可された人間のオペレーターアカウントです。DM ペアリングは誰かが bot と会話できるようにするだけです。最初の所有者ブートストラップが存在する前に送信者を承認していた場合は、`commands.ownerAllowFrom` を明示的に設定してください。
|
||||
- Doctor は、Codex モードのエージェントが設定され、オペレーターの Codex ホームに個人用 Codex CLI アセットが存在する場合に警告します。ローカルの Codex app-server 起動では、エージェントごとに分離されたホームが使用されるため、意図的に昇格すべきアセットを棚卸しするには `openclaw migrate codex --dry-run` を使用してください。
|
||||
- Doctor は、デフォルトエージェントに許可された Skills が、bin、環境変数、設定、OS 要件の不足により現在の実行環境で利用できない場合に警告します。`doctor --fix` は、それらの利用できない Skills を `skills.entries.<skill>.enabled=false` で無効化できます。Skills を有効なままにしたい場合は、代わりに不足している要件をインストール/設定してください。
|
||||
- サンドボックスモードが有効だが Docker が利用できない場合、doctor は修復方法（`install Docker` または `openclaw config set agents.defaults.sandbox.mode off`）を含む高シグナルな警告を報告します。
|
||||
- レガシーなサンドボックスレジストリファイル（`~/.openclaw/sandbox/containers.json` または `~/.openclaw/sandbox/browsers.json`）が存在する場合、doctor はそれらを報告します。`openclaw doctor --fix` は、有効なエントリをシャード化されたレジストリディレクトリに移行し、無効なレガシーファイルを隔離します。
|
||||
- `gateway.auth.token`/`gateway.auth.password` が SecretRef 管理で、現在のコマンドパスで利用できない場合、doctor は読み取り専用の警告を報告し、プレーンテキストのフォールバック認証情報を書き込みません。
|
||||
- 修復パスでチャンネル SecretRef 検査が失敗した場合、doctor は早期終了せずに続行し、警告を報告します。
|
||||
- 状態ディレクトリ移行後、doctor プロセスから `TELEGRAM_BOT_TOKEN` または `DISCORD_BOT_TOKEN` が利用できず、有効化されたデフォルトの Telegram または Discord アカウントが環境変数フォールバックに依存している場合、doctor は警告します。
|
||||
- Telegram `allowFrom` ユーザー名の自動解決（`doctor --fix`）には、現在のコマンドパスで解決可能な Telegram トークンが必要です。トークン検査を利用できない場合、doctor は警告を報告し、そのパスでは自動解決をスキップします。
|
||||
|
||||
## macOS: `launchctl` 環境上書き
|
||||
|
||||
以前に `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（または `...PASSWORD`）を実行していた場合、その値が設定ファイルを上書きし、永続的な「unauthorized」エラーを引き起こす可能性があります。
|
||||
以前に `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（または `...PASSWORD`）を実行していた場合、その値が設定ファイルを上書きし、永続的な「unauthorized」エラーの原因になることがあります。
|
||||
|
||||
```bash
|
||||
launchctl getenv OPENCLAW_GATEWAY_TOKEN
|
||||
|
||||
@ -1,49 +1,49 @@
|
||||
---
|
||||
read_when:
|
||||
- エージェントランタイム、ワークスペースのブートストラップ、またはセッション動作の変更
|
||||
summary: エージェントランタイム、ワークスペース契約、セッションブートストラップ
|
||||
- エージェントランタイム、ワークスペースブートストラップ、またはセッションの動作を変更する
|
||||
summary: エージェントランタイム、ワークスペースコントラクト、セッションブートストラップ
|
||||
title: エージェントランタイム
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T05:06:53Z"
|
||||
generated_at: "2026-05-04T02:22:44Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f4d65ee96cece296251d7d3a0512f12d2dfa900db0e5ffc0f37dcddae7ea55ad
|
||||
source_hash: 89bbbd05a9bf2054d3a1f24aeed005a05b61152a047b593addfb46817baae05a
|
||||
source_path: concepts/agent.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw は **単一の組み込みエージェントランタイム** を実行します。つまり、Gateway ごとに 1 つのエージェントプロセスがあり、それぞれに独自のワークスペース、ブートストラップファイル、セッションストアがあります。このページでは、そのランタイム契約、すなわちワークスペースに何が必要か、どのファイルが注入されるか、セッションがそれに対してどのようにブートストラップされるかを扱います。
|
||||
OpenClaw は **単一の組み込みエージェントランタイム** を実行します。つまり、Gateway ごとに 1 つのエージェントプロセスがあり、それぞれ独自のワークスペース、ブートストラップファイル、セッションストアを持ちます。このページでは、そのランタイム契約について説明します。ワークスペースに何を含める必要があるか、どのファイルが注入されるか、セッションがそれに対してどのようにブートストラップするかを扱います。
|
||||
|
||||
## ワークスペース（必須）
|
||||
|
||||
OpenClaw は、単一のエージェントワークスペースディレクトリ（`agents.defaults.workspace`）を、ツールとコンテキスト用のエージェントの **唯一の** 作業ディレクトリ（`cwd`）として使用します。
|
||||
OpenClaw は、単一のエージェントワークスペースディレクトリ（`agents.defaults.workspace`）を、ツールとコンテキストにおけるエージェントの **唯一の** 作業ディレクトリ（`cwd`）として使用します。
|
||||
|
||||
推奨: `~/.openclaw/openclaw.json` がない場合は、`openclaw setup` を使用して作成し、ワークスペースファイルを初期化してください。
|
||||
推奨: `~/.openclaw/openclaw.json` がない場合は、`openclaw setup` を使用して作成し、ワークスペースファイルを初期化します。
|
||||
|
||||
完全なワークスペース構成 + バックアップガイド: [エージェントワークスペース](/ja-JP/concepts/agent-workspace)
|
||||
|
||||
`agents.defaults.sandbox` が有効な場合、main 以外のセッションは、`agents.defaults.sandbox.workspaceRoot` 配下のセッションごとのワークスペースでこれを上書きできます（[Gateway 設定](/ja-JP/gateway/configuration) を参照）。
|
||||
`agents.defaults.sandbox` が有効な場合、main 以外のセッションは、`agents.defaults.sandbox.workspaceRoot` 配下のセッションごとのワークスペースでこれを上書きできます（[Gateway 設定](/ja-JP/gateway/configuration)を参照）。
|
||||
|
||||
## ブートストラップファイル（注入）
|
||||
|
||||
`agents.defaults.workspace` 内で、OpenClaw は次のユーザー編集可能ファイルを想定します。
|
||||
`agents.defaults.workspace` の中で、OpenClaw は以下のユーザー編集可能なファイルを想定します。
|
||||
|
||||
- `AGENTS.md` — 運用指示 + 「メモリ」
|
||||
- `AGENTS.md` — 操作指示 + 「メモリ」
|
||||
- `SOUL.md` — ペルソナ、境界、トーン
|
||||
- `TOOLS.md` — ユーザーが管理するツールメモ（例: `imsg`、`sag`、規約）
|
||||
- `BOOTSTRAP.md` — 初回実行時のみの儀式（完了後に削除）
|
||||
- `TOOLS.md` — ユーザー管理のツールメモ（例: `imsg`、`sag`、規約）
|
||||
- `BOOTSTRAP.md` — 初回実行時の一度きりの儀式（完了後に削除）
|
||||
- `IDENTITY.md` — エージェント名/雰囲気/絵文字
|
||||
- `USER.md` — ユーザープロファイル + 希望する呼び名
|
||||
- `USER.md` — ユーザープロフィール + 好みの呼び名
|
||||
|
||||
新しいセッションの最初のターンで、OpenClaw はこれらのファイルの内容をエージェントコンテキストに直接注入します。
|
||||
新しいセッションの最初のターンで、OpenClaw はこれらのファイルの内容をシステムプロンプトのプロジェクトコンテキストに注入します。
|
||||
|
||||
空のファイルはスキップされます。大きなファイルはプロンプトを軽量に保つため、マーカー付きで切り詰められます（全文を確認するにはファイルを読んでください）。
|
||||
空のファイルはスキップされます。大きいファイルは、プロンプトを軽量に保つため、マーカー付きで短縮および切り詰められます（全文はファイルを読んでください）。
|
||||
|
||||
ファイルがない場合、OpenClaw は単一の「ファイルが見つからない」マーカー行を注入します（また、`openclaw setup` は安全なデフォルトテンプレートを作成します）。
|
||||
ファイルがない場合、OpenClaw は単一の「ファイル欠落」マーカー行を注入します（また、`openclaw setup` は安全なデフォルトテンプレートを作成します）。
|
||||
|
||||
`BOOTSTRAP.md` は **完全に新しいワークスペース**（他のブートストラップファイルが存在しない場合）にのみ作成されます。儀式の完了後に削除した場合、以後の再起動時に再作成されるべきではありません。
|
||||
`BOOTSTRAP.md` は **まったく新しいワークスペース**（他のブートストラップファイルが存在しない）に対してのみ作成されます。保留中の間、OpenClaw はこれをプロジェクトコンテキストに保持し、ユーザーメッセージにコピーする代わりに、初回儀式用のシステムプロンプトブートストラップガイダンスを追加します。儀式の完了後にこれを削除した場合、以降の再起動で再作成されるべきではありません。
|
||||
|
||||
事前に用意したワークスペース向けに、ブートストラップファイルの作成を完全に無効化するには、次を設定します。
|
||||
ブートストラップファイル作成を完全に無効化するには（事前投入済みワークスペース向け）、次を設定します。
|
||||
|
||||
```json5
|
||||
{ agents: { defaults: { skipBootstrap: true } } }
|
||||
@ -51,28 +51,28 @@ OpenClaw は、単一のエージェントワークスペースディレクト
|
||||
|
||||
## 組み込みツール
|
||||
|
||||
コアツール（read/exec/edit/write および関連するシステムツール）は、ツールポリシーの範囲内で常に利用できます。`apply_patch` は任意で、`tools.exec.applyPatch` によって制御されます。`TOOLS.md` は、どのツールが存在するかを制御しません。これは、それらを _あなたが_ どのように使ってほしいかのガイダンスです。
|
||||
コアツール（read/exec/edit/write および関連するシステムツール）は、ツールポリシーに従う範囲で常に利用できます。`apply_patch` は任意であり、`tools.exec.applyPatch` によって制御されます。`TOOLS.md` はどのツールが存在するかを制御しません。これは、_あなた_ がそれらをどのように使ってほしいかについてのガイダンスです。
|
||||
|
||||
## Skills
|
||||
|
||||
OpenClaw は次の場所から Skills を読み込みます（優先順位が高い順）。
|
||||
OpenClaw は以下の場所から Skills を読み込みます（上ほど優先度が高い）。
|
||||
|
||||
- ワークスペース: `<workspace>/skills`
|
||||
- プロジェクトエージェント Skills: `<workspace>/.agents/skills`
|
||||
- 個人エージェント Skills: `~/.agents/skills`
|
||||
- 管理/ローカル: `~/.openclaw/skills`
|
||||
- バンドル済み（インストールに同梱）
|
||||
- 管理/local: `~/.openclaw/skills`
|
||||
- 同梱（インストールに含まれるもの）
|
||||
- 追加 Skills フォルダー: `skills.load.extraDirs`
|
||||
|
||||
Skills は設定/env によって制御できます（[Gateway 設定](/ja-JP/gateway/configuration) の `skills` を参照）。
|
||||
Skills は設定/env によって制御できます（[Gateway 設定](/ja-JP/gateway/configuration)の `skills` を参照）。
|
||||
|
||||
## ランタイム境界
|
||||
|
||||
組み込みエージェントランタイムは、Pi エージェントコア（モデル、ツール、プロンプトパイプライン）上に構築されています。セッション管理、検出、ツール配線、チャネル配信は、そのコアの上にある OpenClaw 所有のレイヤーです。
|
||||
組み込みエージェントランタイムは、Pi エージェントコア（モデル、ツール、プロンプトパイプライン）の上に構築されています。セッション管理、検出、ツール配線、チャネル配信は、そのコア上にある OpenClaw 所有のレイヤーです。
|
||||
|
||||
## セッション
|
||||
|
||||
セッショントランスクリプトは、JSONL として次に保存されます。
|
||||
セッショントランスクリプトは JSONL として次の場所に保存されます。
|
||||
|
||||
- `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
|
||||
|
||||
@ -81,24 +81,24 @@ Skills は設定/env によって制御できます（[Gateway 設定](/ja-JP/ga
|
||||
|
||||
## ストリーミング中のステアリング
|
||||
|
||||
キューモードが `steer` の場合、受信メッセージは現在の実行に注入されます。キューされたステアリングは、**現在のアシスタントターンがツール呼び出しの実行を完了した後**、次の LLM 呼び出しの前に配信されます。Pi は `steer` について保留中のステアリングメッセージをすべてまとめて排出します。レガシーの `queue` はモデル境界ごとに 1 件のメッセージを排出します。ステアリングは、現在のアシスタントメッセージ内の残りのツール呼び出しをスキップしなくなりました。
|
||||
キューモードが `steer` の場合、受信メッセージは現在の実行に注入されます。キューされたステアリングは、**現在のアシスタントターンがツール呼び出しの実行を終えた後**、次の LLM 呼び出しの前に配信されます。Pi は `steer` では保留中のすべてのステアリングメッセージをまとめて排出します。レガシーの `queue` はモデル境界ごとに 1 件のメッセージを排出します。ステアリングは、現在のアシスタントメッセージから残りのツール呼び出しをスキップしなくなりました。
|
||||
|
||||
キューモードが `followup` または `collect` の場合、受信メッセージは現在のターンが終了するまで保持され、その後、キューされたペイロードで新しいエージェントターンが開始されます。モードと境界の動作については、[キュー](/ja-JP/concepts/queue) と [ステアリングキュー](/ja-JP/concepts/queue-steering) を参照してください。
|
||||
キューモードが `followup` または `collect` の場合、受信メッセージは現在のターンが終了するまで保持され、その後、キューされたペイロードで新しいエージェントターンが開始されます。モードと境界の挙動については、[キュー](/ja-JP/concepts/queue)と[ステアリングキュー](/ja-JP/concepts/queue-steering)を参照してください。
|
||||
|
||||
ブロックストリーミングは、完了したアシスタントブロックを終了次第送信します。これは **デフォルトでオフ** です（`agents.defaults.blockStreamingDefault: "off"`）。
|
||||
ブロックストリーミングは、完了したアシスタントブロックを完了次第送信します。これは **デフォルトでオフ** です（`agents.defaults.blockStreamingDefault: "off"`）。
|
||||
境界は `agents.defaults.blockStreamingBreak` で調整します（`text_end` と `message_end`。デフォルトは text_end）。
|
||||
ソフトブロックのチャンク化は `agents.defaults.blockStreamingChunk` で制御します（デフォルトは 800〜1200 文字。段落区切りを優先し、次に改行、最後に文）。
|
||||
ストリーミングされたチャンクを `agents.defaults.blockStreamingCoalesce` で結合し、単一行の大量送信を減らします（送信前にアイドルベースでマージ）。Telegram 以外のチャネルでは、ブロック返信を有効化するために明示的な `*.blockStreaming: true` が必要です。
|
||||
詳細なツール要約はツール開始時に出力されます（デバウンスなし）。Control UI は、利用可能な場合にエージェントイベント経由でツール出力をストリーミングします。
|
||||
ソフトブロックのチャンク化は `agents.defaults.blockStreamingChunk` で制御します（デフォルトは 800～1200 文字。段落区切りを優先し、次に改行、最後に文）。
|
||||
ストリーミングされたチャンクを `agents.defaults.blockStreamingCoalesce` で結合し、1 行スパムを減らします（送信前にアイドルベースでマージ）。Telegram 以外のチャネルでは、ブロック返信を有効化するために明示的な `*.blockStreaming: true` が必要です。
|
||||
詳細なツール要約はツール開始時に出力されます（デバウンスなし）。Control UI は、利用可能な場合、エージェントイベント経由でツール出力をストリーミングします。
|
||||
詳細: [ストリーミング + チャンク化](/ja-JP/concepts/streaming)。
|
||||
|
||||
## モデル参照
|
||||
|
||||
設定内のモデル参照（例: `agents.defaults.model` と `agents.defaults.models`）は、**最初の** `/` で分割して解析されます。
|
||||
|
||||
- モデルを設定する場合は `provider/model` を使用します。
|
||||
- モデル ID 自体に `/` が含まれる場合（OpenRouter スタイル）、プロバイダープレフィックスを含めます（例: `openrouter/moonshotai/kimi-k2`）。
|
||||
- プロバイダーを省略した場合、OpenClaw はまずエイリアスを試し、次にその正確なモデル ID に一致する一意の設定済みプロバイダーを試し、その後にのみ設定済みのデフォルトプロバイダーへフォールバックします。そのプロバイダーが設定済みのデフォルトモデルを公開しなくなった場合、OpenClaw は古い削除済みプロバイダーのデフォルトを表面化するのではなく、最初の設定済み provider/model にフォールバックします。
|
||||
- モデルを設定するときは `provider/model` を使用します。
|
||||
- モデル ID 自体に `/` が含まれる場合（OpenRouter 形式）、プロバイダープレフィックスを含めます（例: `openrouter/moonshotai/kimi-k2`）。
|
||||
- プロバイダーを省略した場合、OpenClaw はまずエイリアスを試し、次にその正確なモデル ID に一致する一意の設定済みプロバイダーを試し、その後で設定済みのデフォルトプロバイダーにフォールバックします。そのプロバイダーが設定済みのデフォルトモデルをもう公開していない場合、OpenClaw は古い削除済みプロバイダーのデフォルトを表示する代わりに、最初に設定されたプロバイダー/モデルへフォールバックします。
|
||||
|
||||
## 設定（最小）
|
||||
|
||||
@ -109,7 +109,7 @@ Skills は設定/env によって制御できます（[Gateway 設定](/ja-JP/ga
|
||||
|
||||
---
|
||||
|
||||
_次: [グループチャット](/ja-JP/channels/group-messages)_ 🦞
|
||||
_次へ: [グループチャット](/ja-JP/channels/group-messages)_ 🦞
|
||||
|
||||
## 関連
|
||||
|
||||
|
||||
@ -1,65 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw のバグに対するライブビジュアル QA の構築または実行
|
||||
- プルリクエストの事前検証と事後検証を追加する
|
||||
- OpenClaw のバグ向けライブビジュアル QA の構築または実行
|
||||
- プルリクエストの変更前後の検証を追加する
|
||||
- Discord、Slack、WhatsApp、またはその他のライブトランスポートシナリオを追加する
|
||||
- スクリーンショット、ブラウザー自動化、または VNC アクセスが必要な QA 実行のデバッグ
|
||||
summary: Mantis は、ライブトランスポート上で OpenClaw のバグを再現し、修正前後の証拠をキャプチャし、アーティファクトを PR に添付するための視覚的なエンドツーエンド検証システムです。
|
||||
summary: Mantis は、ライブトランスポート上で OpenClaw のバグを再現し、修正前後の証拠をキャプチャし、成果物を PR に添付するための視覚的なエンドツーエンド検証システムです。
|
||||
title: カマキリ
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:30:20Z"
|
||||
generated_at: "2026-05-04T02:23:16Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 3463882b01a7941f6d758c509d6cd70e099aa8352053347fa9c37a80e5b256ce
|
||||
source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d
|
||||
source_path: concepts/mantis.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Mantis は、実際のランタイム、実際のトランスポート、目に見える証拠が必要なバグのための OpenClaw エンドツーエンド検証システムです。既知の不良 ref に対してシナリオを実行して証拠を取得し、同じシナリオを候補 ref に対して実行し、その比較を、メンテナーが PR またはローカルコマンドから確認できる成果物として公開します。
|
||||
Mantis は、実際のランタイム、実際のトランスポート、可視の証拠を必要とするバグのための OpenClaw エンドツーエンド検証システムです。既知の不良 ref に対してシナリオを実行して証拠を取得し、同じシナリオを候補 ref に対して実行して、その比較を PR やローカルコマンドからメンテナーが確認できるアーティファクトとして公開します。
|
||||
|
||||
Mantis は Discord から開始します。Discord は、実際の bot 認証、実際のギルドチャンネル、リアクション、スレッド、ネイティブコマンド、人間がトランスポートに表示された内容を視覚的に確認できるブラウザー UI という、価値の高い最初のレーンを提供するためです。
|
||||
Mantis は Discord から始めます。Discord は、実際のボット認証、実際のギルドチャンネル、リアクション、スレッド、ネイティブコマンド、そしてトランスポートが表示した内容を人間が視覚的に確認できるブラウザー UI という、高価値な最初のレーンを提供するためです。
|
||||
|
||||
## 目標
|
||||
|
||||
- GitHub issue または PR のバグを、ユーザーが見るものと同じトランスポート形状で再現する。
|
||||
- 修正を適用する前に、ベースライン ref で **before** 成果物を取得する。
|
||||
- 修正を適用した後に、候補 ref で **after** 成果物を取得する。
|
||||
- 可能な場合は、Discord REST リアクション読み取りやチャンネルのトランスクリプト確認など、決定論的なオラクルを使用する。
|
||||
- 修正を適用する前に、ベースライン ref で **before** アーティファクトを取得する。
|
||||
- 修正を適用した後に、候補 ref で **after** アーティファクトを取得する。
|
||||
- 可能な場合は、Discord REST のリアクション読み取りやチャンネル transcript チェックなど、決定的な oracle を使用する。
|
||||
- バグに可視 UI サーフェスがある場合はスクリーンショットを取得する。
|
||||
- エージェント制御の CLI からローカルで、また GitHub からリモートで実行する。
|
||||
- ログイン、ブラウザー自動化、またはプロバイダー認証が詰まったときの VNC レスキューのために十分なマシン状態を保持する。
|
||||
- 実行がブロックされた場合、手動 VNC 支援が必要な場合、または完了した場合に、オペレーターの Discord チャンネルへ簡潔なステータスを投稿する。
|
||||
- エージェント制御の CLI からローカルで、GitHub からリモートで実行する。
|
||||
- ログイン、ブラウザー自動化、またはプロバイダー認証が詰まったときに VNC レスキューできるだけのマシン状態を保持する。
|
||||
- 実行がブロックされた、手動 VNC 支援が必要になった、または完了したときに、オペレーターの Discord チャンネルへ簡潔なステータスを投稿する。
|
||||
|
||||
## 非目標
|
||||
|
||||
- Mantis はユニットテストの代替ではありません。Mantis 実行は通常、修正が理解された後に、より小さなリグレッションテストになるべきです。
|
||||
- Mantis はユニットテストの代替ではありません。通常、Mantis の実行は、修正が理解された後でより小さな回帰テストになるべきです。
|
||||
- Mantis は通常の高速 CI ゲートではありません。より遅く、ライブ認証情報を使用し、ライブ環境が重要なバグに限定されます。
|
||||
- Mantis は通常動作で人間を必要とするべきではありません。手動 VNC はレスキューパスであり、正常系ではありません。
|
||||
- Mantis は生のシークレットを成果物、ログ、スクリーンショット、Markdown レポート、PR コメントに保存しません。
|
||||
- Mantis は通常運用で人間を必要とするべきではありません。手動 VNC はレスキューパスであり、正常系ではありません。
|
||||
- Mantis はアーティファクト、ログ、スクリーンショット、Markdown レポート、PR コメントに生のシークレットを保存しません。
|
||||
|
||||
## 所有範囲
|
||||
|
||||
Mantis は OpenClaw QA スタック内にあります。
|
||||
|
||||
- OpenClaw は、シナリオランタイム、トランスポートアダプター、証拠スキーマ、`pnpm openclaw qa mantis` 配下のローカル CLI を所有します。
|
||||
- QA Lab は、ライブトランスポートハーネス部品、ブラウザー取得ヘルパー、成果物ライターを所有します。
|
||||
- Crabbox は、リモート VM が必要な場合に、ウォーム済み Linux マシンを所有します。
|
||||
- GitHub Actions は、リモートワークフローのエントリポイントと成果物保持を所有します。
|
||||
- ClawSweeper は GitHub コメントルーティングを所有します。つまり、メンテナーコマンドの解析、ワークフローのディスパッチ、最終 PR コメントの投稿です。
|
||||
- OpenClaw エージェントは、シナリオでエージェント的なセットアップ、デバッグ、または詰まった状態の報告が必要な場合に、Codex を通じて Mantis を駆動します。
|
||||
- OpenClaw は、`pnpm openclaw qa mantis` 配下のシナリオランタイム、トランスポートアダプター、証拠スキーマ、ローカル CLI を所有します。
|
||||
- QA Lab は、ライブトランスポートハーネス部品、ブラウザー取得ヘルパー、アーティファクトライターを所有します。
|
||||
- Crabbox は、リモート VM が必要な場合のウォーム済み Linux マシンを所有します。
|
||||
- GitHub Actions は、リモートワークフローのエントリーポイントとアーティファクト保持を所有します。
|
||||
- ClawSweeper は、GitHub コメントのルーティングを所有します。つまり、メンテナーコマンドの解析、ワークフローのディスパッチ、最終 PR コメントの投稿です。
|
||||
- OpenClaw エージェントは、シナリオにエージェント的なセットアップ、デバッグ、または詰まり状態の報告が必要な場合に、Codex を通じて Mantis を駆動します。
|
||||
|
||||
この境界により、トランスポート知識は OpenClaw に、マシンスケジューリングは Crabbox に、メンテナーワークフローの接着部分は ClawSweeper に保たれます。
|
||||
この境界により、トランスポート知識は OpenClaw に、マシンスケジューリングは Crabbox に、メンテナーワークフローの接着部分は ClawSweeper に保持されます。
|
||||
|
||||
## コマンド形式
|
||||
## コマンド形状
|
||||
|
||||
最初のローカルコマンドは、Discord bot、ギルド、チャンネル、メッセージ送信、リアクション送信、成果物パスを検証します。
|
||||
最初のローカルコマンドは、Discord ボット、ギルド、チャンネル、メッセージ送信、リアクション送信、アーティファクトパスを検証します。
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis discord-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-smoke
|
||||
```
|
||||
|
||||
ローカルの before/after ランナーはこの形式を受け付けます。
|
||||
ローカルの before / after ランナーは、この形状を受け取ります。
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis run \
|
||||
@ -70,14 +70,31 @@ pnpm openclaw qa mantis run \
|
||||
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
|
||||
```
|
||||
|
||||
ランナーは、出力ディレクトリ配下に分離されたベースラインおよび候補ワークツリーを作成し、依存関係をインストールし、各 ref をビルドし、`--allow-failures` 付きでシナリオを実行してから、`baseline/`、`candidate/`、`comparison.json`、`mantis-report.md` を書き込みます。最初の Discord シナリオでは、検証成功とは、ベースラインステータスが `fail` で候補ステータスが `pass` であることを意味します。
|
||||
ランナーは出力ディレクトリ配下に分離されたベースラインと候補の worktree を作成し、依存関係をインストールし、各 ref をビルドし、`--allow-failures` 付きでシナリオを実行してから、`baseline/`、`candidate/`、`comparison.json`、`mantis-report.md` を書き込みます。最初の Discord シナリオでは、検証成功とは、ベースラインのステータスが `fail` で候補のステータスが `pass` であることを意味します。
|
||||
|
||||
GitHub スモークワークフローは `Mantis Discord Smoke` です。最初の実シナリオの before/after GitHub ワークフローは `Mantis Discord Status Reactions` です。これは次を受け付けます。
|
||||
最初の VM/ブラウザープリミティブはデスクトップ smoke です。
|
||||
|
||||
- `baseline_ref`: キューのみの挙動を再現することが期待される ref。
|
||||
```bash
|
||||
pnpm openclaw qa mantis desktop-browser-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/desktop-browser
|
||||
```
|
||||
|
||||
これは Crabbox デスクトップマシンをリースまたは再利用し、VNC セッション内で可視ブラウザーを起動し、デスクトップをキャプチャし、アーティファクトをローカル出力ディレクトリへ取り戻し、再接続コマンドをレポートに書き込みます。このコマンドは、Mantis レーンで動作するデスクトップ/VNC カバレッジを持つ最初のプロバイダーであるため、デフォルトで Hetzner プロバイダーを使用します。別の Crabbox fleet に対して実行する場合は、`--provider`、`--crabbox-bin`、または `OPENCLAW_MANTIS_CRABBOX_PROVIDER` で上書きします。
|
||||
|
||||
便利なデスクトップ smoke フラグ:
|
||||
|
||||
- `--lease-id <cbx_...>` または `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` は、ウォーム済みデスクトップを再利用します。
|
||||
- `--browser-url <url>` は、可視ブラウザーで開くページを変更します。
|
||||
- `--html-file <path>` は、repo ローカルの HTML アーティファクトを可視ブラウザーでレンダリングします。Mantis はこれを使って、生成された Discord ステータスリアクションタイムラインを実際の Crabbox デスクトップ経由でキャプチャします。
|
||||
- `--keep-lease` または `OPENCLAW_MANTIS_KEEP_VM=1` は、新規作成されて成功したリースを VNC 検査のために開いたままにします。失敗した実行では、オペレーターが再接続できるように、リースが作成されていた場合はデフォルトで保持します。
|
||||
- `--class`、`--idle-timeout`、`--ttl` は、マシンサイズとリース有効期間を調整します。
|
||||
|
||||
GitHub smoke ワークフローは `Mantis Discord Smoke` です。最初の実シナリオ用の before / after GitHub ワークフローは `Mantis Discord Status Reactions` です。次を受け取ります。
|
||||
|
||||
- `baseline_ref`: queued-only の挙動を再現することが期待される ref。
|
||||
- `candidate_ref`: `queued -> thinking -> done` を示すことが期待される ref。
|
||||
|
||||
ワークフローハーネス ref をチェックアウトし、別々のベースラインおよび候補ワークツリーをビルドし、各ワークツリーに対して `discord-status-reactions-tool-only` を実行し、`baseline/`、`candidate/`、`comparison.json`、`mantis-report.md` を Actions 成果物としてアップロードします。
|
||||
これはワークフローハーネス ref をチェックアウトし、ベースラインと候補の worktree を別々にビルドし、各 worktree に対して `discord-status-reactions-tool-only` を実行し、`baseline/`、`candidate/`、`comparison.json`、`mantis-report.md` を Actions アーティファクトとしてアップロードします。また、各レーンのタイムライン HTML を Crabbox デスクトップブラウザーでレンダリングし、それらの VNC スクリーンショットを決定的なタイムライン PNG と並べて PR コメントに公開します。このワークフローは、次の Crabbox バイナリリリースが切られる前に現在のデスクトップ/ブラウザーリースフラグを使用できるよう、`openclaw/crabbox` main から Crabbox CLI をビルドします。
|
||||
|
||||
ステータスリアクション実行は、PR コメントから直接トリガーすることもできます。
|
||||
|
||||
@ -85,7 +102,7 @@ GitHub スモークワークフローは `Mantis Discord Smoke` です。最初
|
||||
@Mantis discord status reactions
|
||||
```
|
||||
|
||||
コメントトリガーは意図的に狭くしています。pull request コメントのうち、write、maintain、または admin 権限を持つユーザーからのものだけで実行され、Discord ステータスリアクション要求だけを認識します。デフォルトでは、既知の不良ベースライン ref と現在の PR head SHA を候補として使用します。メンテナーはいずれの ref も上書きできます。
|
||||
コメントトリガーは意図的に狭くしています。pull request コメント上で、write、maintain、または admin アクセスを持つユーザーからのものだけを実行し、Discord ステータスリアクションのリクエストだけを認識します。デフォルトでは、既知の不良ベースライン ref と現在の PR head SHA を候補として使用します。メンテナーはどちらの ref も上書きできます。
|
||||
|
||||
```text
|
||||
@Mantis discord status reactions baseline=origin/main candidate=HEAD
|
||||
@ -98,44 +115,45 @@ ClawSweeper コマンド例:
|
||||
@clawsweeper verify e2e discord
|
||||
```
|
||||
|
||||
最初のコマンドは明示的で、シナリオに焦点を当てています。2 つ目は将来的に、ラベル、変更ファイル、ClawSweeper レビュー所見から、PR または issue を推奨 Mantis シナリオへ対応付けられます。
|
||||
最初のコマンドは明示的で、シナリオに焦点を当てています。2 番目は後で、ラベル、変更ファイル、ClawSweeper レビュー所見から、PR または issue を推奨 Mantis シナリオへマッピングできます。
|
||||
|
||||
## 実行ライフサイクル
|
||||
|
||||
1. 認証情報を取得する。
|
||||
2. VM を割り当てる、または再利用する。
|
||||
3. ベースライン ref 用のクリーンなチェックアウトを準備する。
|
||||
4. 依存関係をインストールし、シナリオが必要とするものだけをビルドする。
|
||||
5. 分離された状態ディレクトリで子 OpenClaw Gateway を開始する。
|
||||
6. ライブトランスポート、プロバイダー、モデル、ブラウザープロファイルを設定する。
|
||||
7. シナリオを実行し、ベースライン証拠を取得する。
|
||||
8. Gateway を停止し、ログを保持する。
|
||||
9. 同じ VM 内で候補 ref を準備する。
|
||||
10. 同じシナリオを実行し、候補証拠を取得する。
|
||||
11. オラクル結果と視覚的証拠を比較する。
|
||||
12. Markdown、JSON、ログ、スクリーンショット、任意のトレース成果物を書き込む。
|
||||
13. GitHub Actions 成果物をアップロードする。
|
||||
14. 簡潔な PR または Discord ステータスメッセージを投稿する。
|
||||
3. シナリオに UI 証拠が必要な場合、デスクトップ/ブラウザープロファイルを準備する。
|
||||
4. ベースライン ref 用のクリーンな checkout を準備する。
|
||||
5. 依存関係をインストールし、シナリオが必要とするものだけをビルドする。
|
||||
6. 分離された状態ディレクトリで子 OpenClaw Gateway を起動する。
|
||||
7. ライブトランスポート、プロバイダー、モデル、ブラウザープロファイルを設定する。
|
||||
8. シナリオを実行し、ベースライン証拠を取得する。
|
||||
9. Gateway を停止し、ログを保持する。
|
||||
10. 同じ VM 内で候補 ref を準備する。
|
||||
11. 同じシナリオを実行し、候補証拠を取得する。
|
||||
12. oracle 結果と視覚的証拠を比較する。
|
||||
13. Markdown、JSON、ログ、スクリーンショット、任意の trace アーティファクトを書き込む。
|
||||
14. GitHub Actions アーティファクトをアップロードする。
|
||||
15. 簡潔な PR または Discord ステータスメッセージを投稿する。
|
||||
|
||||
シナリオは、2 つの異なる方法で失敗できるべきです。
|
||||
シナリオは 2 つの異なる方法で失敗できるべきです。
|
||||
|
||||
- **バグ再現**: ベースラインが期待された形で失敗した。
|
||||
- **ハーネス失敗**: 環境セットアップ、認証情報、Discord API、ブラウザー、またはプロバイダーが、バグオラクルに意味が出る前に失敗した。
|
||||
- **ハーネス失敗**: バグ oracle が意味を持つ前に、環境セットアップ、認証情報、Discord API、ブラウザー、またはプロバイダーが失敗した。
|
||||
|
||||
最終レポートは、メンテナーが不安定な環境と製品挙動を混同しないように、これらのケースを分離する必要があります。
|
||||
最終レポートでは、メンテナーが不安定な環境をプロダクト挙動と混同しないよう、これらのケースを分離する必要があります。
|
||||
|
||||
## Discord MVP
|
||||
|
||||
最初のシナリオは、ソース返信配信モードが `message_tool_only` であるギルドチャンネル内の Discord ステータスリアクションを対象にするべきです。
|
||||
|
||||
これが良い Mantis の種になる理由:
|
||||
これが Mantis の良い種である理由:
|
||||
|
||||
- トリガーメッセージ上のリアクションとして Discord で見える。
|
||||
- Discord メッセージリアクション状態を通じた強い REST オラクルがある。
|
||||
- 実際の OpenClaw Gateway、Discord bot 認証、メッセージディスパッチ、ソース返信配信モード、ステータスリアクション状態、モデルターンライフサイクルを実行する。
|
||||
- 最初の実装を正直に保てるだけ十分に狭い。
|
||||
- トリガーメッセージ上のリアクションとして Discord で可視です。
|
||||
- Discord メッセージリアクション状態を通じて、強力な REST oracle があります。
|
||||
- 実際の OpenClaw Gateway、Discord ボット認証、メッセージ dispatch、ソース返信配信モード、ステータスリアクション状態、モデル turn ライフサイクルを実行します。
|
||||
- 最初の実装を正直に保てるだけ十分に狭いです。
|
||||
|
||||
想定されるシナリオ形式:
|
||||
想定されるシナリオ形状:
|
||||
|
||||
```yaml
|
||||
id: discord-status-reactions-tool-only
|
||||
@ -166,9 +184,9 @@ evidence:
|
||||
screenshotMessageRow: true
|
||||
```
|
||||
|
||||
ベースライン証拠は、キュー済みの確認リアクションは表示するが、ツールのみモードでライフサイクル遷移は表示しないべきです。候補証拠は、`messages.statusReactions.enabled` が明示的に true のときにライフサイクルステータスリアクションが実行されることを示すべきです。
|
||||
ベースライン証拠では、queued の確認リアクションは表示されるが、tool-only モードでライフサイクル遷移がないことを示すべきです。候補証拠では、`messages.statusReactions.enabled` が明示的に true の場合にライフサイクルステータスリアクションが実行されることを示すべきです。
|
||||
|
||||
実行可能な最初のスライスは、オプトインの Discord ライブ QA シナリオです。
|
||||
実行可能な最初のスライスは、opt-in の Discord live QA シナリオです。
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa discord \
|
||||
@ -180,23 +198,24 @@ pnpm openclaw qa discord \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
|
||||
```
|
||||
|
||||
これは SUT を、常時オンのギルド処理、`visibleReplies: "message_tool"`、`ackReaction: "👀"`、明示的なステータスリアクションで設定します。オラクルは実際の Discord トリガーメッセージをポーリングし、観測シーケンス `👀 -> 🤔 -> 👍` を期待します。成果物には `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html`、`discord-status-reactions-tool-only-timeline.png` が含まれます。
|
||||
これは SUT を、常時オンのギルド処理、`visibleReplies:
|
||||
"message_tool"`、`ackReaction: "👀"`、明示的なステータスリアクションで設定します。oracle は実際の Discord トリガーメッセージをポーリングし、観測シーケンス `👀 -> 🤔 -> 👍` を期待します。アーティファクトには `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html`、`discord-status-reactions-tool-only-timeline.png` が含まれます。
|
||||
|
||||
## 既存の QA 要素
|
||||
## 既存の QA 部品
|
||||
|
||||
Mantis はゼロから始めるのではなく、既存のプライベート QA スタックの上に構築するべきです。
|
||||
Mantis は、ゼロから始めるのではなく、既存の private QA スタック上に構築するべきです。
|
||||
|
||||
- `pnpm openclaw qa discord` は、すでにドライバー bot と SUT bot を含むライブ Discord レーンを実行します。
|
||||
- ライブトランスポートランナーは、すでに `.artifacts/qa-e2e/` 配下にレポートと観測メッセージ成果物を書き込みます。
|
||||
- `pnpm openclaw qa discord` は、driver と SUT ボットを使ったライブ Discord レーンをすでに実行しています。
|
||||
- ライブトランスポートランナーは、`.artifacts/qa-e2e/` 配下にレポートと観測メッセージアーティファクトをすでに書き込みます。
|
||||
- Convex 認証情報リースは、共有ライブトランスポート認証情報への排他的アクセスをすでに提供しています。
|
||||
- ブラウザー制御サービスは、すでにスクリーンショット、スナップショット、ヘッドレス管理プロファイル、リモート CDP プロファイルをサポートしています。
|
||||
- QA Lab には、トランスポート形状のテスト用のデバッガー UI とバスがすでにあります。
|
||||
- ブラウザー制御サービスは、スクリーンショット、スナップショット、headless 管理プロファイル、リモート CDP プロファイルをすでにサポートしています。
|
||||
- QA Lab には、トランスポート形状のテスト用のデバッガー UI と bus がすでにあります。
|
||||
|
||||
最初の Mantis 実装は、これらの要素の上に置く薄い before/after ランナーと、1 つの視覚的証拠レイヤーにできます。
|
||||
最初の Mantis 実装は、これらの部品に薄い before/after ランナーと 1 つの視覚的証拠レイヤーを足したものにできます。
|
||||
|
||||
## 証拠モデル
|
||||
|
||||
すべての実行は、安定した成果物ディレクトリを書き込みます。
|
||||
各実行は、安定したアーティファクトディレクトリを書き込みます。
|
||||
|
||||
```text
|
||||
.artifacts/qa-e2e/mantis/<run-id>/
|
||||
@ -216,65 +235,65 @@ Mantis はゼロから始めるのではなく、既存のプライベート QA
|
||||
run.log
|
||||
```
|
||||
|
||||
`mantis-summary.json` は、機械可読な信頼できる情報源であるべきです。Markdown レポートは PR コメントと人間のレビュー用です。
|
||||
`mantis-summary.json` は、機械可読な信頼できる情報源であるべきです。Markdown レポートは PR コメントと人間によるレビュー用です。
|
||||
|
||||
サマリーには次を含める必要があります。
|
||||
summary には次を含める必要があります。
|
||||
|
||||
- テストされた ref と SHA
|
||||
- トランスポートとシナリオ ID
|
||||
- マシンプロバイダーとマシン ID またはリース ID
|
||||
- トランスポートとシナリオ id
|
||||
- マシンプロバイダーとマシン id またはリース id
|
||||
- シークレット値を含まない認証情報ソース
|
||||
- ベースライン結果
|
||||
- 候補結果
|
||||
- バグがベースラインで再現したかどうか
|
||||
- バグがベースラインで再現されたかどうか
|
||||
- 候補がそれを修正したかどうか
|
||||
- 成果物パス
|
||||
- サニタイズされたセットアップまたはクリーンアップの問題
|
||||
- アーティファクトパス
|
||||
- サニタイズ済みのセットアップまたはクリーンアップ問題
|
||||
|
||||
スクリーンショットは証拠であり、シークレットではありません。それでも、リダクションの規律は必要です。プライベートチャンネル名、ユーザー名、またはメッセージ内容が表示される場合があります。公開 PR では、リダクション方針がより強固になるまで、インライン画像よりも GitHub Actions 成果物リンクを優先してください。
|
||||
スクリーンショットは証拠であり、シークレットではありません。それでも redaction の規律は必要です。private チャンネル名、ユーザー名、またはメッセージ内容が表示される可能性があります。public PR では、redaction のストーリーがより強くなるまで、インライン画像より GitHub Actions アーティファクトリンクを優先してください。
|
||||
|
||||
## ブラウザーと VNC
|
||||
|
||||
ブラウザーレーンには 2 つのモードがあります。
|
||||
|
||||
- **ヘッドレス自動化**: CI のデフォルト。Chrome は CDP 有効で実行され、Playwright または OpenClaw ブラウザー制御がスクリーンショットを取得します。
|
||||
- **VNC レスキュー**: ログイン、MFA、Discord の自動化対策、または視覚的なデバッグで人間が必要な場合に、同じ VM 上で有効化されます。
|
||||
- **Headless automation**: CI のデフォルトです。Chrome は CDP 有効で実行され、Playwright または OpenClaw ブラウザー制御がスクリーンショットを取得します。
|
||||
- **VNC rescue**: ログイン、MFA、Discord anti-automation、または視覚的デバッグで人間が必要な場合に、同じ VM 上で有効にされます。
|
||||
|
||||
Discord オブザーバーブラウザープロファイルは、毎回ログインしなくて済む程度に永続的であるべきですが、個人のブラウザー状態からは分離されるべきです。プロファイルは Mantis マシンプールに属し、開発者のラップトップには属しません。
|
||||
Discord オブザーバーのブラウザープロファイルは、実行のたびにログインしなくて済む程度に永続的であるべきですが、個人用ブラウザー状態からは分離されている必要があります。プロファイルは開発者のラップトップではなく、Mantis マシンプールに属します。
|
||||
|
||||
Mantis が詰まったときは、次を含む Discord ステータスメッセージを投稿します。
|
||||
Mantis が停止状態になった場合、次を含む Discord ステータスメッセージを投稿します。
|
||||
|
||||
- 実行 ID
|
||||
- シナリオ ID
|
||||
- マシンプロバイダー
|
||||
- 成果物ディレクトリ
|
||||
- 利用可能な場合は VNC または noVNC 接続手順
|
||||
- 短いブロッカー文
|
||||
- アーティファクトディレクトリ
|
||||
- 利用可能な場合は VNC または noVNC の接続手順
|
||||
- 短いブロッカー説明
|
||||
|
||||
最初のプライベートデプロイでは、これらのメッセージを既存のオペレーターチャンネルに投稿し、後で専用の Mantis チャンネルへ移行できます。
|
||||
|
||||
## マシン
|
||||
|
||||
Mantis は、最初のリモート実装では Crabbox 経由の AWS を優先するべきです。Crabbox は、ウォーム済みマシン、リース追跡、ハイドレーション、ログ、結果、クリーンアップを提供します。AWS 容量が遅すぎる、または利用できない場合は、同じマシンインターフェースの背後に Hetzner プロバイダーを追加します。
|
||||
Mantis は最初のリモート実装では Crabbox 経由の AWS を優先するべきです。Crabbox はウォーム済みマシン、リース追跡、ハイドレーション、ログ、結果、クリーンアップを提供します。AWS のキャパシティが遅すぎるか利用できない場合は、同じマシンインターフェイスの背後に Hetzner プロバイダーを追加します。
|
||||
|
||||
最小 VM 要件:
|
||||
|
||||
- デスクトップ対応の Chrome または Chromium がインストールされた Linux
|
||||
- ブラウザー自動化のための CDP アクセス
|
||||
- レスキュー用の VNC または noVNC
|
||||
- ブラウザー自動化用の CDP アクセス
|
||||
- 復旧用の VNC または noVNC
|
||||
- Node 22 と pnpm
|
||||
- OpenClaw チェックアウトと依存関係キャッシュ
|
||||
- Playwright が使用される場合は Playwright Chromium ブラウザーキャッシュ
|
||||
- 1 つの OpenClaw Gateway、1 つのブラウザー、1 回のモデル実行に十分な CPU とメモリ
|
||||
- OpenClaw のチェックアウトと依存関係キャッシュ
|
||||
- Playwright を使用する場合の Playwright Chromium ブラウザーキャッシュ
|
||||
- 1つの OpenClaw Gateway、1つのブラウザー、1つのモデル実行に十分な CPU とメモリ
|
||||
- Discord、GitHub、モデルプロバイダー、認証情報ブローカーへのアウトバウンドアクセス
|
||||
|
||||
VM は、想定される認証情報ストアまたはブラウザープロファイルストア以外に、長期間有効な生のシークレットを保持するべきではありません。
|
||||
VM は、想定される認証情報ストアまたはブラウザープロファイルストア以外に、長期間有効な生シークレットを保持してはいけません。
|
||||
|
||||
## シークレット
|
||||
|
||||
シークレットは、リモート実行では GitHub organization または repository secrets に、ローカル実行ではローカルのオペレーター制御シークレットファイルに置きます。
|
||||
リモート実行のシークレットは GitHub organization またはリポジトリシークレットに置き、ローカル実行のシークレットはローカルのオペレーター管理シークレットファイルに置きます。
|
||||
|
||||
推奨されるシークレット名:
|
||||
推奨シークレット名:
|
||||
|
||||
- `OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
|
||||
@ -285,29 +304,31 @@ VM は、想定される認証情報ストアまたはブラウザープロフ
|
||||
- 公開 GitHub アーティファクトアップロード用の `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`
|
||||
- `OPENCLAW_QA_CONVEX_SITE_URL`
|
||||
- `OPENCLAW_QA_CONVEX_SECRET_CI`
|
||||
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR`
|
||||
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN`
|
||||
|
||||
長期的には、Convex 認証情報プールをライブのトランスポート認証情報の通常のソースとして維持する必要があります。GitHub secrets はブローカーとフォールバックレーンをブートストラップします。
|
||||
長期的には、Convex 認証情報プールをライブトランスポート認証情報の通常のソースとして維持するべきです。GitHub シークレットは、ブローカーとフォールバックレーンをブートストラップします。Discord ステータスリアクションワークフローは、Mantis Crabbox シークレットを Crabbox CLI が期待する `CRABBOX_COORDINATOR` および `CRABBOX_COORDINATOR_TOKEN` 環境変数へ対応付けます。互換性フォールバックとして、プレーンな `CRABBOX_*` GitHub シークレット名も引き続き受け付けられます。
|
||||
|
||||
Mantis ランナーは次を絶対に出力してはいけません。
|
||||
|
||||
- Discord bot トークン
|
||||
- Discord ボットトークン
|
||||
- プロバイダー API キー
|
||||
- ブラウザー Cookie
|
||||
- ブラウザークッキー
|
||||
- 認証プロファイルの内容
|
||||
- VNC パスワード
|
||||
- 生の認証情報ペイロード
|
||||
|
||||
公開アーティファクトのアップロードでも、bot、guild、channel、message id などの Discord ターゲットメタデータを編集して秘匿する必要があります。GitHub smoke ワークフローはこの理由で `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` を有効にしています。
|
||||
公開アーティファクトアップロードでは、ボット、ギルド、チャンネル、メッセージ ID などの Discord ターゲットメタデータも編集するべきです。このため、GitHub スモークワークフローは `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` を有効にします。
|
||||
|
||||
トークンを issue、PR、チャット、ログに誤って貼り付けた場合は、新しい secret を保存した後にローテーションしてください。
|
||||
トークンが誤って issue、PR、チャット、ログに貼り付けられた場合は、新しいシークレットを保存した後でローテーションします。
|
||||
|
||||
## GitHub アーティファクトと PR コメント
|
||||
|
||||
Mantis ワークフローは、完全な証拠バンドルを短期間保持される Actions アーティファクトとしてアップロードする必要があります。バグ報告または修正 PR のためにワークフローを実行する場合は、秘匿済みの PNG スクリーンショットを `qa-artifacts` ブランチにも公開し、そのバグまたは修正 PR に before/after スクリーンショットをインラインで含むコメントを upsert する必要があります。主な証拠を汎用の QA 自動化 PR だけに投稿しないでください。生ログ、観測されたメッセージ、その他の大きな証拠は Actions アーティファクトに残します。
|
||||
Mantis ワークフローは、完全な証拠バンドルを短期間有効な Actions アーティファクトとしてアップロードするべきです。バグレポートまたは修正 PR に対してワークフローを実行する場合は、編集済み PNG スクリーンショットも `qa-artifacts` ブランチへ公開し、そのバグまたは修正 PR にインラインの before/after スクリーンショット付きコメントを upsert するべきです。主要な証拠を汎用 QA 自動化 PR だけに投稿してはいけません。生ログ、観測されたメッセージ、その他の大きな証拠は Actions アーティファクトに残します。
|
||||
|
||||
本番ワークフローでは、それらのコメントを `github-actions[bot]` ではなく Mantis GitHub App で投稿する必要があります。app id と private key は `MANTIS_GITHUB_APP_ID` および `MANTIS_GITHUB_APP_PRIVATE_KEY` の GitHub Actions secrets として保存してください。ワークフローは hidden marker を upsert キーとして使用し、トークンで編集できる場合はそのコメントを更新し、古い bot 所有の marker を編集できない場合は Mantis 所有の新しいコメントを作成します。
|
||||
本番ワークフローは、`github-actions[bot]` ではなく Mantis GitHub App でそれらのコメントを投稿するべきです。app ID と秘密鍵は `MANTIS_GITHUB_APP_ID` および `MANTIS_GITHUB_APP_PRIVATE_KEY` GitHub Actions シークレットとして保存します。ワークフローは非表示マーカーを upsert キーとして使用し、トークンで編集できる場合はそのコメントを更新し、古いボット所有のマーカーを編集できない場合は新しい Mantis 所有コメントを作成します。
|
||||
|
||||
PR コメントは短く視覚的にする必要があります。
|
||||
PR コメントは短く視覚的であるべきです。
|
||||
|
||||
```md
|
||||
Mantis Discord Status Reactions QA
|
||||
@ -327,60 +348,60 @@ candidate showed the expected queued -> thinking -> done sequence.
|
||||
| <inline screenshot> | <inline screenshot> |
|
||||
```
|
||||
|
||||
ハーネスの失敗が原因で実行が失敗した場合、コメントでは candidate が失敗したと示唆するのではなく、その旨を記載する必要があります。
|
||||
ハーネスの失敗が原因で実行が失敗した場合、コメントは候補が失敗したと示唆するのではなく、そのことを明記する必要があります。
|
||||
|
||||
## プライベートデプロイのメモ
|
||||
## プライベートデプロイメモ
|
||||
|
||||
プライベートデプロイには、すでに Mantis Discord アプリケーションがある場合があります。適切な bot 権限があり、安全にローテーションできる場合は、別のアプリを作成するのではなくそのアプリケーションを再利用してください。
|
||||
プライベートデプロイには、すでに Mantis Discord アプリケーションがある場合があります。適切なボット権限があり、安全にローテーションできる場合は、別のアプリを作成するのではなく、そのアプリケーションを再利用します。
|
||||
|
||||
初期のオペレーター通知 channel は secrets またはデプロイ設定で指定します。最初は既存のメンテナーまたは運用 channel を指すようにし、専用の Mantis channel が存在するようになったらそこへ移動できます。
|
||||
最初のオペレーター通知チャンネルは、シークレットまたはデプロイ設定で設定します。最初は既存のメンテナーまたは運用チャンネルを指し、専用の Mantis チャンネルが存在するようになったらそこへ移行できます。
|
||||
|
||||
guild id、channel id、bot トークン、ブラウザー Cookie、VNC パスワードをこのドキュメントに記載しないでください。GitHub secrets、認証情報ブローカー、またはオペレーターのローカル secret ストアに保存してください。
|
||||
ギルド ID、チャンネル ID、ボットトークン、ブラウザークッキー、VNC パスワードをこのドキュメントに記載してはいけません。それらは GitHub シークレット、認証情報ブローカー、またはオペレーターのローカルシークレットストアに保存します。
|
||||
|
||||
## シナリオの追加
|
||||
|
||||
Mantis シナリオでは次を宣言する必要があります。
|
||||
Mantis シナリオでは次を宣言するべきです。
|
||||
|
||||
- id とタイトル
|
||||
- ID とタイトル
|
||||
- トランスポート
|
||||
- 必要な認証情報
|
||||
- baseline ref ポリシー
|
||||
- candidate ref ポリシー
|
||||
- OpenClaw config パッチ
|
||||
- ベースライン ref ポリシー
|
||||
- 候補 ref ポリシー
|
||||
- OpenClaw 設定パッチ
|
||||
- セットアップ手順
|
||||
- 刺激
|
||||
- 期待される baseline oracle
|
||||
- 期待される candidate oracle
|
||||
- ビジュアルキャプチャターゲット
|
||||
- 期待されるベースラインオラクル
|
||||
- 期待される候補オラクル
|
||||
- 視覚キャプチャターゲット
|
||||
- タイムアウト予算
|
||||
- クリーンアップ手順
|
||||
|
||||
シナリオでは、小さく型付けされた oracle を優先する必要があります。
|
||||
シナリオでは、小さく型付けされたオラクルを優先するべきです。
|
||||
|
||||
- リアクションのバグには Discord リアクション状態
|
||||
- スレッド化のバグには Discord メッセージ参照
|
||||
- Slack のバグには Slack thread ts とリアクション API 状態
|
||||
- メールのバグにはメール message id と header
|
||||
- UI が唯一の信頼できる観測対象である場合はブラウザースクリーンショット
|
||||
- リアクションバグ用の Discord リアクション状態
|
||||
- スレッドバグ用の Discord メッセージ参照
|
||||
- Slack バグ用の Slack スレッド ts とリアクション API 状態
|
||||
- メールバグ用のメールメッセージ ID とヘッダー
|
||||
- UI が唯一の信頼できる観測対象である場合のブラウザースクリーンショット
|
||||
|
||||
ビジョンチェックは追加的にする必要があります。プラットフォーム API でバグを証明できる場合は、その API を pass/fail oracle として使用し、スクリーンショットは人間の確認用に残してください。
|
||||
ビジョンチェックは追加的であるべきです。プラットフォーム API でバグを証明できる場合は、その API を合否オラクルとして使用し、スクリーンショットは人間の確信のために保持します。
|
||||
|
||||
## プロバイダー拡張
|
||||
|
||||
Discord の後、同じランナーで次を追加できます。
|
||||
|
||||
- Slack: リアクション、スレッド、app mentions、modals、ファイルアップロード。
|
||||
- メール: connector だけでは不十分な場合の `gog` を使った Gmail 認証とメッセージスレッド化。
|
||||
- Slack: リアクション、スレッド、アプリメンション、モーダル、ファイルアップロード。
|
||||
- メール: コネクターだけでは不十分な場合の `gog` を使った Gmail 認証とメッセージスレッド。
|
||||
- WhatsApp: QR ログイン、再識別、メッセージ配信、メディア、リアクション。
|
||||
- Telegram: group mention gating、コマンド、利用可能な場合はリアクション。
|
||||
- Matrix: 暗号化 rooms、thread または reply relations、再起動後の再開。
|
||||
- Telegram: グループメンションゲーティング、コマンド、利用可能な場合のリアクション。
|
||||
- Matrix: 暗号化ルーム、スレッドまたは返信関係、再起動後の再開。
|
||||
|
||||
各トランスポートには、低コストな smoke シナリオを 1 つと、1 つ以上のバグクラスシナリオを用意する必要があります。高コストなビジュアルシナリオは opt-in のままにしてください。
|
||||
各トランスポートには、1つの低コストなスモークシナリオと、1つ以上のバグクラスシナリオを用意するべきです。高コストな視覚シナリオはオプトインのままにするべきです。
|
||||
|
||||
## 未解決の質問
|
||||
|
||||
- 既存の Mantis bot を再利用する場合、どの Discord bot を driver にし、どれを SUT にするべきですか？
|
||||
- observer ブラウザーログインは、最初のフェーズで人間の Discord アカウント、テストアカウント、または bot で読み取り可能な REST 証拠のみのどれを使用するべきですか？
|
||||
- GitHub は PR の Mantis アーティファクトをどのくらいの期間保持するべきですか？
|
||||
- ClawSweeper は、メンテナーコマンドを待つのではなく、いつ Mantis を自動的に推奨するべきですか？
|
||||
- 公開 PR では、アップロード前にスクリーンショットを秘匿またはクロップするべきですか？
|
||||
- 既存の Mantis ボットを再利用する場合、どの Discord ボットをドライバーにし、どれを SUT にするべきか?
|
||||
- オブザーバーブラウザーのログインは、最初のフェーズで人間の Discord アカウント、テストアカウント、またはボットが読める REST 証拠のみのどれを使用するべきか?
|
||||
- GitHub は PR 用の Mantis アーティファクトをどのくらい保持するべきか?
|
||||
- ClawSweeper は、メンテナーコマンドを待つ代わりに、いつ Mantis を自動的に推奨するべきか?
|
||||
- 公開 PR 用に、アップロード前のスクリーンショットを編集またはクロップするべきか?
|
||||
|
||||
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- 長時間実行されるチャットターンで表示される進捗更新を設定する
|
||||
- partial、block、progress ストリーミングモードの選択
|
||||
- OpenClaw が作業の進行中に 1 つのチャンネルメッセージを更新する方法の説明
|
||||
- 進捗下書き、スタンドアロンの進捗メッセージ、または最終化フォールバックのトラブルシューティング
|
||||
summary: '進捗ドラフト: エージェントの実行中に更新される、表示中の作業中メッセージ 1 件'
|
||||
title: 進捗の下書き
|
||||
- 部分、ブロック、進行状況のストリーミングモードの選択
|
||||
- 作業中に OpenClaw が1つのチャンネルメッセージを更新する仕組みの説明
|
||||
- 進行状況ドラフト、単独の進行状況メッセージ、または最終化フォールバックのトラブルシューティング
|
||||
summary: '進行状況の下書き: エージェントの実行中に更新される、表示中の作業中メッセージ1件'
|
||||
title: 進行中の下書き
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:31:05Z"
|
||||
generated_at: "2026-05-04T02:23:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0fc0dff38232228b49872d66f4498f065675cdd3abf3a0f4003cb34fcbb7de8c
|
||||
source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe
|
||||
source_path: concepts/progress-drafts.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
進行状況の下書きは、長時間実行されるエージェントのターンを、会話を一時的なステータス返信の積み重ねにすることなく、チャット内で動いているように感じさせます。
|
||||
進行状況ドラフトは、長時間実行されるエージェントのターンをチャット内で動いているように見せつつ、会話を一時的なステータス返信の山にしません。
|
||||
|
||||
進行状況の下書きが有効な場合、OpenClaw は表示される作業中メッセージを 1 つ作成し、エージェントが読んだり、計画したり、ツールを呼び出したり、承認を待ったりしている間にそれを更新します。その後、チャンネルが安全に実行できる場合は、その下書きを最終回答に変えます。
|
||||
進行状況ドラフトが有効な場合、OpenClaw はターンが実際に作業していることを示した後にだけ、表示される作業中メッセージを 1 つ作成し、エージェントが読み取り、計画し、ツールを呼び出し、または承認を待つ間にそれを更新し、チャンネルが安全に実行できる場合はそのドラフトを最終回答に変換します。
|
||||
|
||||
```text
|
||||
Shelling
|
||||
- reading recent channel context
|
||||
- checking matching issues
|
||||
- preparing reply
|
||||
Shelling...
|
||||
📖 Read: from docs/concepts/progress-drafts.md
|
||||
🔎 Web Search: for "discord edit message"
|
||||
🛠️ Exec: run tests
|
||||
```
|
||||
|
||||
ツールを多用する作業中に整理されたステータスメッセージを 1 つ表示し、ターンが完了したら最終回答を表示したい場合は、進行状況の下書きを使用します。
|
||||
ツールを多用する作業中に整ったステータスメッセージを 1 つ表示し、ターンが完了したら最終回答を表示したい場合は、進行状況ドラフトを使用します。
|
||||
|
||||
## クイックスタート
|
||||
|
||||
チャンネルごとに `streaming.mode: "progress"` で進行状況の下書きを有効にします。
|
||||
チャンネルごとに `streaming.mode: "progress"` で進行状況ドラフトを有効にします。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -44,63 +44,64 @@ Shelling
|
||||
}
|
||||
```
|
||||
|
||||
通常はこれで十分です。OpenClaw は自動的に 1 語のラベルを選び、有用な作業が発生している間はコンパクトな進行状況行を追加し、そのターンでは重複する単独の進行状況メッセージを抑制します。
|
||||
通常はこれで十分です。OpenClaw は自動的に 1 語のラベルを選び、作業が少なくとも 5 秒続くか、2 つ目の作業イベントが発生するまで待ち、有用な作業が発生している間はコンパクトな進行状況行を追加し、そのターンの重複する単独の進行状況チャットを抑制します。
|
||||
|
||||
## ユーザーに表示される内容
|
||||
|
||||
進行状況の下書きには 2 つの部分があります。
|
||||
進行状況ドラフトには 2 つの部分があります。
|
||||
|
||||
| 部分 | 目的 |
|
||||
| -------------- | ----------------------------------------------------------------- |
|
||||
| ラベル | `Thinking` や `Shelling` などの短いタイトル。 |
|
||||
| 進行状況行 | ツール呼び出し、タスク手順、承認などのコンパクトな実行更新。 |
|
||||
| 部分 | 目的 |
|
||||
| -------------- | --------------------------------------------------------------------------- |
|
||||
| ラベル | `Thinking...` や `Shelling...` のような短いタイトル。 |
|
||||
| 進行状況行 | 詳細出力と同じツールラベルとアイコンを使ったコンパクトな実行更新。 |
|
||||
|
||||
ラベルは、エージェントが返信を開始するとすぐに表示されます。進行状況行は、エージェントが有用な作業更新を出した場合にのみ追加されます。可能な場合、最終回答は下書きを置き換えます。それ以外の場合、OpenClaw は通常どおり最終回答を送信し、チャンネルのトランスポートに応じて下書きを片付けるか、更新を停止します。
|
||||
ラベルは、エージェントが意味のある作業を開始し、5 秒間ビジーのままであるか、2 つ目の作業イベントを発生させた後に表示されます。プレーンテキストのみの返信では進行状況ドラフトは表示されません。進行状況行は、エージェントが有用な作業更新を発生させた場合にのみ追加されます。たとえば `🛠️ Exec`、`🔎 Web Search`、`✍️ Write: to /tmp/file` などです。デフォルトでは `/verbose` と同じコンパクトな説明モードを使用します。デバッグ時に生のコマンドや詳細も追加したい場合は、`agents.defaults.toolProgressDetail: "raw"` を設定します。
|
||||
可能な場合、最終回答はドラフトを置き換えます。それ以外の場合、OpenClaw は通常どおり最終回答を送信し、チャンネルのトランスポートに応じてドラフトをクリーンアップするか、更新を停止します。
|
||||
|
||||
## モードを選択する
|
||||
## モードを選ぶ
|
||||
|
||||
`channels.<channel>.streaming.mode` は、表示される進行中の動作を制御します。
|
||||
|
||||
| モード | 最適な用途 | チャットに表示される内容 |
|
||||
| ---------- | -------------------------------- | ------------------------------------------------- |
|
||||
| `off` | 静かなチャンネル | 最終回答のみ。 |
|
||||
| `partial` | 回答テキストが表示される様子を見る | 最新の回答テキストで編集される 1 つの下書き。 |
|
||||
| `block` | 大きめの回答プレビューのチャンク | 大きめのチャンクで更新または追記される 1 つのプレビュー。 |
|
||||
| `progress` | ツールを多用する、または長時間実行されるターン | 1 つのステータス下書き、その後に最終回答。 |
|
||||
| `partial` | 回答テキストが表示されていく様子を見る場合 | 最新の回答テキストで編集される 1 つのドラフト。 |
|
||||
| `block` | より大きな回答プレビューのチャンク | より大きなチャンクで更新または追加される 1 つのプレビュー。 |
|
||||
| `progress` | ツールを多用する、または長時間実行されるターン | 1 つのステータスドラフト、その後に最終回答。 |
|
||||
|
||||
回答テキストがトークンごとにストリーミングされる様子を見ることよりも、「何が起きているか」をユーザーが重視する場合は、`progress` を選択します。
|
||||
ユーザーが回答テキストをトークン単位でストリーミング表示することよりも、「何が起きているか」を重視する場合は、`progress` を選びます。
|
||||
|
||||
回答そのものが進行状況のシグナルである場合は、`partial` を選択します。
|
||||
回答そのものが進行状況のシグナルである場合は、`partial` を選びます。
|
||||
|
||||
大きめのテキストチャンクで下書きプレビューを更新したい場合は、`block` を選択します。Discord と Telegram では、`streaming.mode: "block"` は引き続きプレビューストリーミングであり、通常のブロック配信ではありません。通常のブロック返信が必要な場合は、`streaming.block.enabled` またはレガシーの `blockStreaming` を使用してください。
|
||||
より大きなテキストチャンクでドラフトプレビューを更新したい場合は、`block` を選びます。Discord と Telegram では、`streaming.mode: "block"` は引き続きプレビューストリーミングであり、通常のブロック配信ではありません。通常のブロック返信が必要な場合は、`streaming.block.enabled` または従来の `blockStreaming` を使用します。
|
||||
|
||||
## ラベルを設定する
|
||||
|
||||
進行状況ラベルは `channels.<channel>.streaming.progress` の下にあります。
|
||||
|
||||
デフォルトのラベルは `auto` で、OpenClaw の組み込みの 1 語ラベルプールから選択します。
|
||||
デフォルトのラベルは `auto` で、OpenClaw の組み込みの省略記号付き 1 語ラベルプールから選択します。
|
||||
|
||||
```text
|
||||
Thinking
|
||||
Shelling
|
||||
Scuttling
|
||||
Clawing
|
||||
Pinching
|
||||
Molting
|
||||
Bubbling
|
||||
Tiding
|
||||
Reefing
|
||||
Cracking
|
||||
Sifting
|
||||
Brining
|
||||
Nautiling
|
||||
Krilling
|
||||
Barnacling
|
||||
Lobstering
|
||||
Tidepooling
|
||||
Pearling
|
||||
Snapping
|
||||
Surfacing
|
||||
Thinking...
|
||||
Shelling...
|
||||
Scuttling...
|
||||
Clawing...
|
||||
Pinching...
|
||||
Molting...
|
||||
Bubbling...
|
||||
Tiding...
|
||||
Reefing...
|
||||
Cracking...
|
||||
Sifting...
|
||||
Brining...
|
||||
Nautiling...
|
||||
Krilling...
|
||||
Barnacling...
|
||||
Lobstering...
|
||||
Tidepooling...
|
||||
Pearling...
|
||||
Snapping...
|
||||
Surfacing...
|
||||
```
|
||||
|
||||
固定ラベルを使用します。
|
||||
@ -138,7 +139,7 @@ Surfacing
|
||||
}
|
||||
```
|
||||
|
||||
ラベルを非表示にし、進行状況行のみを表示します。
|
||||
ラベルを非表示にし、進行状況行だけを表示します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -157,9 +158,30 @@ Surfacing
|
||||
|
||||
## 進行状況行を制御する
|
||||
|
||||
進行状況行は、進行状況モードではデフォルトで有効です。これらは実際の実行イベント、つまりツール開始、項目更新、タスク計画、承認、コマンド出力、パッチ要約、類似のエージェント活動から生成されます。
|
||||
進行状況行は、進行状況モードでデフォルトで有効です。これは実際の実行イベントから発生します。ツール開始、項目更新、タスク計画、承認、コマンド出力、パッチ要約、および同様のエージェント活動です。
|
||||
|
||||
表示され続ける行数を制限します。
|
||||
OpenClaw は進行状況ドラフトと `/verbose` に同じフォーマッターを使用します。
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
toolProgressDetail: "explain", // explain | raw
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`"explain"` がデフォルトで、`🛠️ Exec: check JS syntax for /tmp/app.js` のような簡潔なラベルでドラフトを安定させます。`"raw"` は利用可能な場合に基礎となるコマンドや詳細を追加します。デバッグ中には有用ですが、チャットではノイズが多くなります。
|
||||
|
||||
たとえば、同じコマンドでも詳細モードによって表示が異なります。
|
||||
|
||||
| モード | 進行状況行 |
|
||||
| --------- | -------------------------------------------------------------------- |
|
||||
| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` |
|
||||
| `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` |
|
||||
|
||||
表示される行数を制限します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -176,7 +198,7 @@ Surfacing
|
||||
}
|
||||
```
|
||||
|
||||
単一の進行状況下書きを維持しつつ、ツール行とタスク行を非表示にします。
|
||||
1 つの進行状況ドラフトは維持しつつ、ツール行とタスク行を非表示にします。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -197,50 +219,50 @@ Surfacing
|
||||
|
||||
## チャンネルの動作
|
||||
|
||||
各チャンネルは、対応している中で最もきれいなトランスポートを使用します。
|
||||
各チャンネルは、サポートする最もクリーンなトランスポートを使用します。
|
||||
|
||||
| チャンネル | 進行状況トランスポート | 注記 |
|
||||
| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
|
||||
| Discord | 1 つのメッセージを送信し、その後編集します。 | 最終テキストは、安全なプレビューメッセージ 1 つに収まる場合、その場で編集されます。 |
|
||||
| Matrix | 1 つのイベントを送信し、その後編集します。 | アカウントレベルのストリーミング設定が、アカウントレベルの下書きを制御します。 |
|
||||
| Microsoft Teams | 個人チャット内のネイティブ Teams ストリーム。 | `streaming.mode: "block"` は Teams のブロック配信に対応します。 |
|
||||
| Slack | ネイティブストリームまたは編集可能な下書き投稿。 | スレッドの利用可否は、ネイティブストリーミングを使用できるかに影響します。 |
|
||||
| Telegram | 1 つのメッセージを送信し、その後編集します。 | 最終タイムスタンプが有用なままになるよう、古い表示下書きが置き換えられる場合があります。 |
|
||||
| Mattermost | 編集可能な下書き投稿。 | ツール活動は同じ下書き形式の投稿に折り込まれます。 |
|
||||
| Discord | メッセージを 1 つ送信し、その後編集します。 | 最終テキストは、安全なプレビューメッセージ 1 つに収まる場合、その場で編集されます。 |
|
||||
| Matrix | イベントを 1 つ送信し、その後編集します。 | アカウントレベルのストリーミング設定が、アカウントレベルのドラフトを制御します。 |
|
||||
| Microsoft Teams | 個人チャットでネイティブ Teams ストリームを使用します。 | `streaming.mode: "block"` は Teams のブロック配信にマップされます。 |
|
||||
| Slack | ネイティブストリームまたは編集可能なドラフト投稿。 | スレッドの可用性は、ネイティブストリーミングを使用できるかどうかに影響します。 |
|
||||
| Telegram | メッセージを 1 つ送信し、その後編集します。 | 最終タイムスタンプを有用に保つため、古い表示済みドラフトが置き換えられる場合があります。 |
|
||||
| Mattermost | 編集可能なドラフト投稿。 | ツール活動は同じドラフト形式の投稿に折り込まれます。 |
|
||||
|
||||
安全な編集サポートのないチャンネルでは、通常、入力中インジケーターまたは最終回答のみの配信にフォールバックします。
|
||||
安全な編集サポートがないチャンネルは通常、入力中インジケーターまたは最終回答のみの配信にフォールバックします。
|
||||
|
||||
## 最終化
|
||||
|
||||
最終回答の準備ができると、OpenClaw はチャットをきれいに保とうとします。
|
||||
最終回答の準備ができると、OpenClaw はチャットをクリーンに保とうとします。
|
||||
|
||||
- 下書きを安全に最終回答にできる場合、OpenClaw はそれをその場で編集します。
|
||||
- ドラフトを安全に最終回答にできる場合、OpenClaw はその場で編集します。
|
||||
- チャンネルがネイティブの進行状況ストリーミングを使用している場合、ネイティブトランスポートが最終テキストを受け付けると、OpenClaw はそのストリームを最終化します。
|
||||
- 最終回答にメディア、承認プロンプト、明示的な返信先、多すぎるチャンク、または編集/送信の失敗がある場合、OpenClaw は通常のチャンネル配信パスで最終回答を送信します。
|
||||
- 最終回答にメディア、承認プロンプト、明示的な返信先、過剰なチャンク、または失敗した編集や送信がある場合、OpenClaw は通常のチャンネル配信パスで最終回答を送信します。
|
||||
|
||||
フォールバックパスは意図的なものです。テキストを失ったり、返信先スレッドを誤ったり、チャンネルが安全に表現できないペイロードで下書きを上書きしたりするよりも、新しい最終回答を送信する方が適切です。
|
||||
フォールバックパスは意図的なものです。テキストを失ったり、返信のスレッドを誤ったり、チャンネルが安全に表現できないペイロードでドラフトを上書きしたりするよりも、新しい最終回答を送信する方が適切です。
|
||||
|
||||
## トラブルシューティング
|
||||
|
||||
**最終回答しか表示されません。**
|
||||
|
||||
メッセージを処理したアカウントまたはチャンネルで、`channels.<channel>.streaming.mode` が `progress` に設定されていることを確認してください。一部のグループまたは引用返信のパスでは、チャンネルが正しいメッセージを安全に編集できない場合、そのターンの下書きプレビューが無効になることがあります。
|
||||
メッセージを処理したアカウントまたはチャンネルで、`channels.<channel>.streaming.mode` が `progress` に設定されていることを確認してください。一部のグループまたは引用返信パスでは、チャンネルが適切なメッセージを安全に編集できない場合、そのターンのドラフトプレビューが無効になることがあります。
|
||||
|
||||
**ラベルは表示されますが、ツール行がありません。**
|
||||
**ラベルは表示されますが、ツール行が表示されません。**
|
||||
|
||||
`streaming.progress.toolProgress` を確認してください。`false` の場合、OpenClaw は単一の下書き動作を維持しますが、ツールとタスクの進行状況行を非表示にします。
|
||||
`streaming.progress.toolProgress` を確認してください。`false` の場合、OpenClaw は 1 つのドラフト動作を維持しますが、ツールとタスクの進行状況行を非表示にします。
|
||||
|
||||
**編集された下書きではなく、新しい最終メッセージが表示されます。**
|
||||
**編集されたドラフトではなく、新しい最終メッセージが表示されます。**
|
||||
|
||||
これは安全のためのフォールバックです。メディア返信、長い回答、明示的な返信先、古い Telegram 下書き、見つからない Slack スレッド対象、削除されたプレビューメッセージ、またはネイティブストリームの最終化失敗で発生することがあります。
|
||||
これは安全のためのフォールバックです。メディア返信、長い回答、明示的な返信先、古い Telegram ドラフト、欠落した Slack スレッドターゲット、削除されたプレビューメッセージ、またはネイティブストリームの最終化失敗で発生することがあります。
|
||||
|
||||
**単独の進行状況メッセージがまだ表示されます。**
|
||||
|
||||
進行状況モードでは、下書きがアクティブな場合、デフォルトの単独のツール進行状況メッセージが抑制されます。単独メッセージがまだ表示される場合は、そのターンが実際に進行状況モードを使用しており、`streaming.mode: "off"` や、そのメッセージに下書きを作成できないチャンネルパスではないことを確認してください。
|
||||
進行状況モードでは、ドラフトがアクティブなときにデフォルトの単独ツール進行状況メッセージを抑制します。単独メッセージがまだ表示される場合は、そのターンが実際に進行状況モードを使用しており、`streaming.mode: "off"` や、そのメッセージのドラフトを作成できないチャンネルパスを使用していないことを確認してください。
|
||||
|
||||
**Teams は Discord や Telegram と異なる動作をします。**
|
||||
**Teams の動作が Discord や Telegram と異なります。**
|
||||
|
||||
Microsoft Teams は、汎用の送信して編集するプレビュートランスポートではなく、個人チャット内でネイティブストリームを使用します。また、Teams には Discord や Telegram で使用される同じ下書きプレビューのブロックモードがないため、`streaming.mode: "block"` は Teams のブロック配信として扱われます。
|
||||
Microsoft Teams は、汎用の送信後編集プレビュートランスポートではなく、個人チャットでネイティブストリームを使用します。また、Teams は `streaming.mode: "block"` を Teams のブロック配信として扱います。これは Discord と Telegram で使用される同じドラフトプレビューのブロックモードがないためです。
|
||||
|
||||
## 関連
|
||||
|
||||
|
||||
@ -1,72 +1,98 @@
|
||||
---
|
||||
read_when:
|
||||
- エージェントがツールを使用している間に steer がどのように動作するかを説明する
|
||||
- エージェントがツールを使用している間に誘導がどのように動作するかを説明する
|
||||
- アクティブ実行キューの動作またはランタイムステアリング統合の変更
|
||||
- steer、queue、collect、followup モードの比較
|
||||
summary: アクティブ実行のステアリングがランタイム境界でメッセージをキューに入れる仕組み
|
||||
- steer、queue、collect、followup の各モードの比較
|
||||
summary: アクティブ実行ステアリングがランタイム境界でメッセージをキューに入れる仕組み
|
||||
title: ステアリングキュー
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T05:10:18Z"
|
||||
generated_at: "2026-05-04T02:23:50Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 560390c8c26bcce95e0137f4336ad6e62bc3e2344cb15fd12ca3cfe4a85a8acc
|
||||
source_hash: c8df35b127ae0c1e1b3b684a1f63ce33874eb3d0b7bf9d0df7cb9dfce093090a
|
||||
source_path: concepts/queue-steering.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
セッション実行がすでにストリーミング中にメッセージが届いた場合、OpenClaw は同じセッションに対して別の実行を開始する代わりに、そのメッセージをアクティブなランタイムへ送信できます。公開モードはランタイム中立です。Pi とネイティブの Codex app-server ハーネスでは、配信の詳細が異なる方法で実装されています。
|
||||
実行中のセッションがすでにストリーミングしている間にメッセージが届いた場合、OpenClaw は
|
||||
同じセッションに対して別の実行を開始する代わりに、そのメッセージをアクティブなランタイムへ
|
||||
送信できます。公開モードはランタイムに依存しません。Pi とネイティブ Codex
|
||||
app-server ハーネスは、配信の詳細を異なる方法で実装しています。
|
||||
|
||||
## ランタイム境界
|
||||
|
||||
ステアリングは、すでに実行中のツール呼び出しを中断しません。Pi はモデル境界でキュー内のステアリングメッセージを確認します。
|
||||
ステアリングは、すでに実行中のツール呼び出しを中断しません。Pi はモデル境界で
|
||||
キューに入ったステアリングメッセージを確認します。
|
||||
|
||||
1. アシスタントがツール呼び出しを要求します。
|
||||
2. Pi が現在のアシスタントメッセージのツール呼び出しバッチを実行します。
|
||||
3. Pi がターン終了イベントを発行します。
|
||||
4. Pi がキュー内のステアリングメッセージを排出します。
|
||||
4. Pi がキューに入ったステアリングメッセージを排出します。
|
||||
5. Pi が次の LLM 呼び出しの前に、それらのメッセージをユーザーメッセージとして追加します。
|
||||
|
||||
これにより、ツール結果はそれを要求したアシスタントメッセージと対応付けられたままになり、次のモデル呼び出しが最新のユーザー入力を参照できるようになります。
|
||||
これにより、ツール結果はそれを要求したアシスタントメッセージと対応したままになり、
|
||||
次のモデル呼び出しが最新のユーザー入力を確認できます。
|
||||
|
||||
ネイティブの Codex app-server ハーネスは、Pi の内部ステアリングキューの代わりに `turn/steer` を公開します。OpenClaw はそこで同じモードを次のように適用します。
|
||||
ネイティブ Codex app-server ハーネスは、Pi の内部ステアリングキューの代わりに
|
||||
`turn/steer` を公開します。OpenClaw はそこで同じモードを適用します。
|
||||
|
||||
- `steer` は、設定された静止時間枠の間にキュー内のメッセージをまとめ、その後、収集したすべてのユーザー入力を到着順に含む単一の `turn/steer` リクエストを送信します。
|
||||
- `queue` は、個別の `turn/steer` リクエストを送信することで従来のシリアライズされた形を維持します。
|
||||
- `followup`、`collect`、`steer-backlog`、`interrupt` は、アクティブな Codex ターンの周囲で OpenClaw が所有するキュー動作のままです。
|
||||
- `steer` は、設定された静音ウィンドウの間キューに入ったメッセージをまとめてから、
|
||||
収集したすべてのユーザー入力を到着順に含む単一の `turn/steer` リクエストを送信します。
|
||||
- `queue` は、個別の `turn/steer` リクエストを送信することで、従来の直列化された形を維持します。
|
||||
- `followup`、`collect`、`steer-backlog`、`interrupt` は、アクティブな Codex ターンの周囲で
|
||||
OpenClaw が所有するキュー動作のままです。
|
||||
|
||||
Codex レビューと手動 Compaction ターンは、同一ターンのステアリングを拒否します。ランタイムがステアリングを受け入れられない場合、OpenClaw はそのモードで許可されている場合にフォローアップキューへフォールバックします。
|
||||
Codex レビューと手動 Compaction ターンは、同一ターンのステアリングを拒否します。ランタイムが
|
||||
ステアリングを受け入れられない場合、OpenClaw はそのモードで許可されている範囲でフォローアップキューに
|
||||
フォールバックします。
|
||||
|
||||
このページでは、通常の受信メッセージ向けのキューモードステアリングについて説明します。明示的な
|
||||
`/steer <message>` コマンドについては、[ステア](/tools/steer)を参照してください。
|
||||
|
||||
## モード
|
||||
|
||||
| モード | アクティブ実行時の動作 | 後続フォローアップの動作 |
|
||||
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| `steer` | 次のランタイム境界で、キュー内のすべてのステアリングメッセージをまとめて注入します。これがデフォルトです。 | ステアリングが利用できない場合にのみフォローアップへフォールバックします。 |
|
||||
| `queue` | 従来の1件ずつのステアリングです。Pi はモデル境界ごとにキュー内のメッセージを1件注入し、Codex は個別の `turn/steer` リクエストを送信します。 | ステアリングが利用できない場合にのみフォローアップへフォールバックします。 |
|
||||
| `steer-backlog` | `steer` と同じアクティブ実行時のステアリング動作です。 | 後続のフォローアップターン用にも同じメッセージを保持します。 |
|
||||
| `followup` | 現在の実行をステアリングしません。 | キュー内のメッセージを後で実行します。 |
|
||||
| `collect` | 現在の実行をステアリングしません。 | デバウンス時間枠の後、互換性のあるキュー内のメッセージを1つの後続ターンにまとめます。 |
|
||||
| `interrupt` | アクティブな実行を中止し、その後で最新のメッセージを開始します。 | なし。 |
|
||||
| モード | アクティブ実行の動作 | 後続フォローアップの動作 |
|
||||
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| `steer` | 次のランタイム境界で、キューに入ったすべてのステアリングメッセージをまとめて注入します。これがデフォルトです。 | ステアリングを利用できない場合にのみフォローアップへフォールバックします。 |
|
||||
| `queue` | 従来の 1 件ずつのステアリングです。Pi はモデル境界ごとにキュー内のメッセージを 1 件注入し、Codex は個別の `turn/steer` リクエストを送信します。 | ステアリングを利用できない場合にのみフォローアップへフォールバックします。 |
|
||||
| `steer-backlog` | アクティブ実行のステアリング動作は `steer` と同じです。 | 同じメッセージを後続のフォローアップターン用にも保持します。 |
|
||||
| `followup` | 現在の実行をステアリングしません。 | キューに入ったメッセージを後で実行します。 |
|
||||
| `collect` | 現在の実行をステアリングしません。 | デバウンスウィンドウ後に、互換性のあるキュー内メッセージを 1 つの後続ターンに結合します。 |
|
||||
| `interrupt` | アクティブな実行を中止し、その後で最新のメッセージを開始します。 | ありません。 |
|
||||
|
||||
## バースト例
|
||||
|
||||
エージェントがツール呼び出しを実行している間に4人のユーザーがメッセージを送信した場合:
|
||||
エージェントがツール呼び出しを実行している間に 4 人のユーザーがメッセージを送信した場合:
|
||||
|
||||
- `steer`: アクティブなランタイムは、次のモデル判断の前に4件すべてのメッセージを到着順に受け取ります。Pi は次のモデル境界でそれらを排出し、Codex は1つにバッチ化された `turn/steer` としてそれらを受け取ります。
|
||||
- `queue`: 従来のシリアライズされたステアリングです。Pi はキュー内のメッセージを1件ずつ注入し、Codex は個別の `turn/steer` リクエストを受け取ります。
|
||||
- `collect`: OpenClaw はアクティブな実行が終了するまで待ち、その後、デバウンス時間枠の後に互換性のあるキュー内のメッセージを含むフォローアップターンを作成します。
|
||||
- `steer`: アクティブなランタイムは、次のモデル判断の前に 4 件すべてのメッセージを到着順で受け取ります。
|
||||
Pi は次のモデル境界でそれらを排出し、Codex は 1 つにまとめられた `turn/steer` として受け取ります。
|
||||
- `queue`: 従来の直列化されたステアリングです。Pi はキュー内のメッセージを 1 件ずつ注入し、
|
||||
Codex は個別の `turn/steer` リクエストを受け取ります。
|
||||
- `collect`: OpenClaw はアクティブな実行が終了するまで待機し、その後デバウンスウィンドウ後に
|
||||
互換性のあるキュー内メッセージを含むフォローアップターンを作成します。
|
||||
|
||||
## スコープ
|
||||
|
||||
ステアリングは常に現在のアクティブなセッション実行を対象にします。新しいセッションを作成したり、アクティブな実行のツールポリシーを変更したり、送信者ごとにメッセージを分割したりすることはありません。マルチユーザーチャンネルでは、受信プロンプトにすでに送信者とルートのコンテキストが含まれているため、次のモデル呼び出しは各メッセージを誰が送信したかを確認できます。
|
||||
ステアリングは常に現在のアクティブなセッション実行を対象にします。新しいセッションを作成したり、
|
||||
アクティブな実行のツールポリシーを変更したり、送信者ごとにメッセージを分割したりしません。
|
||||
複数ユーザーのチャンネルでは、受信プロンプトに送信者とルートのコンテキストがすでに含まれているため、
|
||||
次のモデル呼び出しは各メッセージの送信者を確認できます。
|
||||
|
||||
OpenClaw に、互換性のあるメッセージをまとめ、フォローアップキューのドロップポリシーを保持できる後続のフォローアップターンを構築させたい場合は、`collect` を使用してください。古い1件ずつのステアリング動作が必要な場合にのみ、`queue` を使用してください。
|
||||
互換性のあるメッセージを結合し、フォローアップキューのドロップポリシーを保持できる後続の
|
||||
フォローアップターンを OpenClaw に構築させたい場合は、`collect` を使用します。以前の 1 件ずつの
|
||||
ステアリング動作が必要な場合にのみ `queue` を使用します。
|
||||
|
||||
## デバウンス
|
||||
|
||||
`messages.queue.debounceMs` は、`collect`、`followup`、`steer-backlog`、およびアクティブ実行時のステアリングが利用できない場合の `steer` フォールバックを含む、フォローアップ配信に適用されます。Pi では、アクティブな `steer` 自体はデバウンスタイマーを使用しません。Pi は次のモデル境界まで自然にメッセージをバッチ化するためです。ネイティブの Codex ハーネスでは、OpenClaw はバッチ化された `turn/steer` を送信する前の静止時間枠として同じデバウンス値を使用します。
|
||||
`messages.queue.debounceMs` は、`collect`、`followup`、`steer-backlog`、およびアクティブ実行の
|
||||
ステアリングを利用できない場合の `steer` フォールバックを含む、フォローアップ配信に適用されます。
|
||||
Pi では、アクティブな `steer` 自体はデバウンスタイマーを使用しません。Pi は次のモデル境界まで
|
||||
自然にメッセージをまとめるためです。ネイティブ Codex ハーネスでは、OpenClaw はバッチ化された
|
||||
`turn/steer` を送信する前の静音ウィンドウとして、同じデバウンス値を使用します。
|
||||
|
||||
## 関連
|
||||
|
||||
- [コマンドキュー](/ja-JP/concepts/queue)
|
||||
- [ステア](/tools/steer)
|
||||
- [メッセージ](/ja-JP/concepts/messages)
|
||||
- [エージェントループ](/ja-JP/concepts/agent-loop)
|
||||
|
||||
@ -1,60 +1,60 @@
|
||||
---
|
||||
read_when:
|
||||
- 自動返信の実行または同時実行の変更
|
||||
- /queue モードまたはメッセージステアリングの動作の説明
|
||||
- 自動返信の実行または同時実行数を変更する
|
||||
- /queue モードまたはメッセージの振り分け動作の説明
|
||||
summary: 自動返信キューのモード、デフォルト、セッションごとのオーバーライド
|
||||
title: コマンドキュー
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T04:53:57Z"
|
||||
generated_at: "2026-05-04T02:23:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: c59ea6802d8bf526f4005db3b1baa87d96a23d561c916f91520e8e641fbaf74f
|
||||
source_hash: 085aebe7059020f027eb08bb382cce2d253ea117eed0ca77d6ffd208f295acb1
|
||||
source_path: concepts/queue.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
受信自動返信実行（すべてのチャンネル）は、小さなプロセス内キューを通してシリアライズし、複数のエージェント実行が衝突しないようにしつつ、セッション間では安全な並列性を維持します。
|
||||
インバウンドの自動返信実行（すべてのチャンネル）を小さなインプロセスキューで直列化し、複数のエージェント実行が衝突しないようにしつつ、セッション間では安全な並列性を維持します。
|
||||
|
||||
## 理由
|
||||
|
||||
- 自動返信実行は高コストになることがあり（LLM 呼び出し）、複数の受信メッセージが近いタイミングで届くと衝突する可能性があります。
|
||||
- シリアライズすることで、共有リソース（セッションファイル、ログ、CLI stdin）の競合を避け、上流のレート制限に達する可能性を下げます。
|
||||
- 自動返信実行は高コスト（LLM 呼び出し）になることがあり、複数のインバウンドメッセージが近いタイミングで届くと衝突する可能性があります。
|
||||
- 直列化により、共有リソース（セッションファイル、ログ、CLI stdin）の競合を避け、上流のレート制限に達する可能性を下げます。
|
||||
|
||||
## 仕組み
|
||||
|
||||
- レーン対応 FIFO キューが、設定可能な同時実行上限（未設定レーンのデフォルトは 1、main のデフォルトは 4、subagent は 8）で各レーンを処理します。
|
||||
- `runEmbeddedPiAgent` は **セッションキー**（レーン `session:<key>`）ごとにキューへ追加し、セッションごとにアクティブな実行が 1 つだけになることを保証します。
|
||||
- 各セッション実行はその後 **グローバルレーン**（デフォルトは `main`）にキューイングされるため、全体の並列性は `agents.defaults.maxConcurrent` によって上限が設定されます。
|
||||
- 詳細ログが有効な場合、キュー内の実行は開始前に約 2 秒以上待機すると短い通知を出力します。
|
||||
- 入力中インジケーターは、（チャンネルが対応している場合）キュー追加時に即座に発火するため、順番待ちの間もユーザー体験は変わりません。
|
||||
- レーン対応の FIFO キューが、設定可能な同時実行上限（未設定レーンのデフォルトは 1、main のデフォルトは 4、subagent は 8）で各レーンを処理します。
|
||||
- `runEmbeddedPiAgent` は **セッションキー**（レーン `session:<key>`）ごとにキューへ入れ、セッションごとにアクティブな実行が 1 つだけになることを保証します。
|
||||
- 各セッション実行はその後 **グローバルレーン**（デフォルトは `main`）にキューされるため、全体の並列性は `agents.defaults.maxConcurrent` によって制限されます。
|
||||
- 詳細ログが有効な場合、キューされた実行は開始までに約 2 秒以上待機すると短い通知を出力します。
|
||||
- 入力中インジケーターは（チャンネルが対応している場合）キュー投入時にすぐ発火するため、順番待ち中もユーザー体験は変わりません。
|
||||
|
||||
## デフォルト
|
||||
|
||||
未設定の場合、すべての受信チャンネルサーフェスは次を使用します。
|
||||
未設定の場合、すべてのインバウンドチャンネルサーフェスは次を使用します。
|
||||
|
||||
- `mode: "steer"`
|
||||
- `debounceMs: 500`
|
||||
- `cap: 20`
|
||||
- `drop: "summarize"`
|
||||
|
||||
`steer` がデフォルトなのは、2 つ目のセッション実行を開始せずに、アクティブなモデルターンの応答性を保てるためです。次のモデル境界より前に届いたすべてのステアリングメッセージを処理します。現在の実行がステアリングを受け付けられない場合、OpenClaw はフォローアップキューエントリにフォールバックします。
|
||||
`steer` がデフォルトなのは、2 つ目のセッション実行を開始せずに、アクティブなモデルターンの応答性を保てるためです。次のモデル境界の前に到着したすべてのステアリングメッセージを処理します。現在の実行がステアリングを受け付けられない場合、OpenClaw はフォローアップのキュー項目にフォールバックします。
|
||||
|
||||
## キューモード
|
||||
|
||||
受信メッセージは、現在の実行をステアリングするか、フォローアップターンを待つか、またはその両方を行えます。
|
||||
インバウンドメッセージは現在の実行をステアリングするか、フォローアップターンを待つか、またはその両方を行えます。
|
||||
|
||||
- `steer`: ステアリングメッセージをアクティブなランタイムにキューイングします。Pi は保留中のすべてのステアリングメッセージを、**現在のアシスタントターンがツール呼び出しの実行を終えた後**、次の LLM 呼び出しの前に配送します。Codex app-server はバッチ化された 1 つの `turn/steer` を受信します。実行がアクティブにストリーミングしていない場合、またはステアリングを利用できない場合、OpenClaw はフォローアップキューエントリにフォールバックします。
|
||||
- `queue`（レガシー）: 以前の 1 件ずつのステアリングです。Pi は各モデル境界で、キューに入ったステアリングメッセージを 1 件配送します。Codex app-server は個別の `turn/steer` リクエストを受信します。以前のシリアライズされた動作が必要な場合を除き、`steer` を優先してください。
|
||||
- `followup`: 現在の実行が終了した後の後続エージェントターン用に、各メッセージをキューに追加します。
|
||||
- `collect`: 静穏ウィンドウ後に、キュー内のメッセージを **単一の** フォローアップターンへまとめます。メッセージが異なるチャンネル/スレッドを対象にしている場合、ルーティングを維持するため個別に処理されます。
|
||||
- `steer`: アクティブなランタイムへステアリングメッセージをキューします。Pi は保留中のすべてのステアリングメッセージを、**現在のアシスタントターンがツール呼び出しの実行を終えた後**、次の LLM 呼び出しの前に配信します。Codex app-server はバッチ化された 1 件の `turn/steer` を受け取ります。実行がアクティブにストリーミングしていない場合、またはステアリングを利用できない場合、OpenClaw はフォローアップのキュー項目にフォールバックします。
|
||||
- `queue`（レガシー）: 以前の 1 件ずつのステアリングです。Pi は各モデル境界でキュー済みのステアリングメッセージを 1 件配信します。Codex app-server は個別の `turn/steer` リクエストを受け取ります。以前の直列化された動作が必要な場合を除き、`steer` を推奨します。
|
||||
- `followup`: 現在の実行が終了した後の後続エージェントターン用に、各メッセージをキューに入れます。
|
||||
- `collect`: 静止ウィンドウの後、キュー済みメッセージを **単一** のフォローアップターンにまとめます。メッセージの対象チャンネルやスレッドが異なる場合は、ルーティングを保つため個別に処理されます。
|
||||
- `steer-backlog`（別名 `steer+backlog`）: 今すぐステアリングし、**かつ** 同じメッセージをフォローアップターン用に保持します。
|
||||
- `interrupt`（レガシー）: そのセッションのアクティブな実行を中止し、最新のメッセージを実行します。
|
||||
- `interrupt`（レガシー）: そのセッションのアクティブな実行を中止し、その後で最新のメッセージを実行します。
|
||||
|
||||
Steer-backlog では、ステアリングされた実行の後にフォローアップ応答を受け取ることがあるため、ストリーミングサーフェスでは重複のように見える場合があります。受信メッセージごとに応答を 1 つにしたい場合は、`collect`/`steer` を優先してください。
|
||||
Steer-backlog では、ステアリングされた実行の後にフォローアップ応答を得ることがあるため、ストリーミングサーフェスでは重複のように見える場合があります。インバウンドメッセージ 1 件につき 1 つの応答にしたい場合は、`collect`/`steer` を推奨します。
|
||||
|
||||
ランタイム固有のタイミングと依存関係の動作については、[ステアリングキュー](/ja-JP/concepts/queue-steering)を参照してください。
|
||||
ランタイム固有のタイミングと依存関係の動作については、[ステアリングキュー](/ja-JP/concepts/queue-steering)を参照してください。明示的な `/steer <message>` コマンドについては、[ステア](/tools/steer)を参照してください。
|
||||
|
||||
`messages.queue` でグローバルまたはチャンネルごとに設定します。
|
||||
`messages.queue` を使ってグローバルまたはチャンネルごとに設定します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -72,12 +72,12 @@ Steer-backlog では、ステアリングされた実行の後にフォローア
|
||||
|
||||
## キューオプション
|
||||
|
||||
オプションは `followup`、`collect`、`steer-backlog` に適用されます（ステアリングがフォローアップにフォールバックする場合は、`steer` またはレガシー `queue` にも適用されます）。
|
||||
オプションは `followup`、`collect`、`steer-backlog` に適用されます（ステアリングがフォローアップにフォールバックする場合は、`steer` またはレガシーの `queue` にも適用されます）。
|
||||
|
||||
- `debounceMs`: キュー内のフォローアップを処理する前の静穏ウィンドウです。裸の数値はミリ秒です。`/queue` オプションでは単位 `ms`、`s`、`m`、`h`、`d` を使用できます。
|
||||
- `cap`: セッションごとの最大キュー済みメッセージ数です。`1` 未満の値は無視されます。
|
||||
- `drop: "summarize"`: デフォルトです。必要に応じて最も古いキューエントリを削除し、コンパクトな要約を保持して、それらを合成フォローアッププロンプトとして注入します。
|
||||
- `drop: "old"`: 必要に応じて最も古いキューエントリを削除します。要約は保持しません。
|
||||
- `debounceMs`: キュー済みフォローアップを処理する前の静止ウィンドウ。単位なしの数値はミリ秒です。`/queue` オプションでは単位 `ms`、`s`、`m`、`h`、`d` を使用できます。
|
||||
- `cap`: セッションごとの最大キュー済みメッセージ数。`1` 未満の値は無視されます。
|
||||
- `drop: "summarize"`: デフォルトです。必要に応じて最も古いキュー項目を削除し、コンパクトな要約を保持して、それらを合成フォローアッププロンプトとして注入します。
|
||||
- `drop: "old"`: 必要に応じて最も古いキュー項目を削除しますが、要約は保持しません。
|
||||
- `drop: "new"`: キューがすでに満杯の場合、最新のメッセージを拒否します。
|
||||
|
||||
デフォルト: `debounceMs: 500`、`cap: 20`、`drop: summarize`。
|
||||
@ -86,36 +86,37 @@ Steer-backlog では、ステアリングされた実行の後にフォローア
|
||||
|
||||
モード選択では、OpenClaw は次の順で解決します。
|
||||
|
||||
1. インラインまたは保存済みのセッション別 `/queue` オーバーライド。
|
||||
1. インラインまたは保存済みのセッションごとの `/queue` オーバーライド。
|
||||
2. `messages.queue.byChannel.<channel>`。
|
||||
3. `messages.queue.mode`。
|
||||
4. デフォルトの `steer`。
|
||||
|
||||
オプションでは、インラインまたは保存済みの `/queue` オプションが設定より優先されます。その後、チャンネル固有のデバウンス（`messages.queue.debounceMsByChannel`）、Plugin のデバウンスデフォルト、グローバル `messages.queue` オプション、組み込みデフォルトが適用されます。`cap` と `drop` はグローバル/セッションオプションであり、チャンネル別の設定キーではありません。
|
||||
オプションでは、インラインまたは保存済みの `/queue` オプションが設定より優先されます。その後、チャンネル固有のデバウンス（`messages.queue.debounceMsByChannel`）、Plugin のデバウンスデフォルト、グローバルな `messages.queue` オプション、組み込みデフォルトが適用されます。`cap` と `drop` はグローバル/セッションオプションであり、チャンネルごとの設定キーではありません。
|
||||
|
||||
## セッション別オーバーライド
|
||||
## セッションごとのオーバーライド
|
||||
|
||||
- 現在のセッションのモードを保存するには、`/queue <mode>` を単独のコマンドとして送信します。
|
||||
- 現在のセッションのモードを保存するには、`/queue <mode>` を単独コマンドとして送信します。
|
||||
- オプションは組み合わせられます: `/queue collect debounce:0.5s cap:25 drop:summarize`
|
||||
- `/queue default` または `/queue reset` はセッションオーバーライドをクリアします。
|
||||
|
||||
## スコープと保証
|
||||
|
||||
- Gateway 返信パイプラインを使用するすべての受信チャンネル（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat など）で、自動返信エージェント実行に適用されます。
|
||||
- デフォルトレーン（`main`）は、受信 + main Heartbeat に対してプロセス全体で共有されます。複数セッションを並列に許可するには `agents.defaults.maxConcurrent` を設定します。
|
||||
- 追加のレーン（例: `cron`、`cron-nested`、`nested`、`subagent`）が存在する場合があるため、バックグラウンドジョブは受信返信をブロックせずに並列実行できます。分離された cron エージェントターンは、内側のエージェント実行が `cron-nested` を使用する間、`cron` スロットを保持します。どちらも `cron.maxConcurrentRuns` を使用します。共有の非 cron `nested` フローは独自のレーン動作を維持します。これらのデタッチされた実行は[バックグラウンドタスク](/ja-JP/automation/tasks)として追跡されます。
|
||||
- セッション別レーンにより、特定のセッションに同時に触れるエージェント実行が 1 つだけであることを保証します。
|
||||
- 外部依存関係やバックグラウンドワーカースレッドはありません。純粋な TypeScript + promise です。
|
||||
- Gateway 返信パイプラインを使うすべてのインバウンドチャンネル（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat など）にまたがる自動返信エージェント実行に適用されます。
|
||||
- デフォルトレーン（`main`）は、インバウンドとメイン Heartbeat に対してプロセス全体で共有されます。複数セッションを並列に許可するには `agents.defaults.maxConcurrent` を設定します。
|
||||
- 追加レーン（例: `cron`、`cron-nested`、`nested`、`subagent`）が存在する場合があり、バックグラウンドジョブはインバウンド返信をブロックせずに並列実行できます。分離された Cron エージェントターンは、内側のエージェント実行が `cron-nested` を使う間、`cron` スロットを保持します。どちらも `cron.maxConcurrentRuns` を使用します。共有される非Cronの `nested` フローは独自のレーン動作を維持します。これらの切り離された実行は[バックグラウンドタスク](/ja-JP/automation/tasks)として追跡されます。
|
||||
- セッションごとのレーンにより、特定のセッションに同時に触れるエージェント実行が 1 つだけであることを保証します。
|
||||
- 外部依存関係やバックグラウンドワーカースレッドはありません。純粋な TypeScript と Promise だけです。
|
||||
|
||||
## トラブルシューティング
|
||||
|
||||
- コマンドが止まっているように見える場合は、詳細ログを有効にし、「queued for …ms」行を探してキューが処理されていることを確認してください。
|
||||
- キュー深度が必要な場合は、詳細ログを有効にし、キュータイミング行を確認してください。
|
||||
- ターンを受け付けた後に進捗の出力を停止した Codex app-server 実行は、外側の実行タイムアウトを待つ代わりにアクティブなセッションレーンを解放できるよう、Codex アダプターによって割り込まれます。
|
||||
- 診断が有効な場合、`diagnostics.stuckSessionWarnMs` を超えて `processing` のままで、観測された返信、ツール、ステータス、ブロック、ACP 進捗がないセッションは、現在のアクティビティによって分類されます。アクティブな作業は `session.long_running` としてログに記録されます。最近の進捗がないアクティブな作業は `session.stalled` としてログに記録されます。`session.stuck` は、アクティブな作業がない古いセッション管理状態用に予約されており、その経路だけが影響を受けたセッションレーンを解放して、キュー済みの作業を処理できるようにします。繰り返される `session.stuck` 診断は、セッションが変更されない間バックオフします。
|
||||
- コマンドが止まっているように見える場合は、詳細ログを有効にし、「queued for …ms」の行を探してキューが処理されていることを確認してください。
|
||||
- キュー深度が必要な場合は、詳細ログを有効にしてキューのタイミング行を監視してください。
|
||||
- ターンを受け付けた後に進捗を出力しなくなった Codex app-server の実行は、外側の実行タイムアウトを待たずにアクティブなセッションレーンを解放できるよう、Codex アダプターによって中断されます。
|
||||
- 診断が有効な場合、`processing` のまま `diagnostics.stuckSessionWarnMs` を超え、返信、ツール、ステータス、ブロック、または ACP 進捗が観測されないセッションは、現在のアクティビティに基づいて分類されます。アクティブな作業は `session.long_running` として記録されます。最近の進捗がないアクティブな作業は `session.stalled` として記録されます。`session.stuck` は、アクティブな作業がない古いセッション管理情報のために予約されており、その経路だけが影響を受けたセッションレーンを解放してキュー済み作業を処理できます。繰り返し発生する `session.stuck` 診断は、セッションが変わらない間はバックオフします。
|
||||
|
||||
## 関連
|
||||
|
||||
- [セッション管理](/ja-JP/concepts/session)
|
||||
- [ステアリングキュー](/ja-JP/concepts/queue-steering)
|
||||
- [リトライポリシー](/ja-JP/concepts/retry)
|
||||
- [ステア](/tools/steer)
|
||||
- [再試行ポリシー](/ja-JP/concepts/retry)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user