diff --git a/docs/.i18n/ja-JP.tm.jsonl b/docs/.i18n/ja-JP.tm.jsonl index 8b1378917..e69de29bb 100644 --- a/docs/.i18n/ja-JP.tm.jsonl +++ b/docs/.i18n/ja-JP.tm.jsonl @@ -1 +0,0 @@ - diff --git a/docs/ja-JP/.i18n/README.md b/docs/ja-JP/.i18n/README.md new file mode 100644 index 000000000..68370dc1c --- /dev/null +++ b/docs/ja-JP/.i18n/README.md @@ -0,0 +1,81 @@ +--- +x-i18n: + generated_at: "2026-04-05T12:34:13Z" + model: gpt-5.4 + provider: openai + source_hash: adff26fa8858af2759b231ea48bfc01f89c110cd9b3774a8f783e282c16f77fb + source_path: .i18n/README.md + workflow: 15 +--- + +# OpenClaw ドキュメント i18n アセット + +このフォルダーには、ソースドキュメントリポジトリ用の翻訳設定が保存されています。 + +生成されたロケールツリーとライブ翻訳メモリは現在、公開リポジトリにあります。 + +- リポジトリ: `openclaw/docs` +- ローカルチェックアウト: `~/Projects/openclaw-docs` + +## 信頼できる唯一の情報源 + +- 英語ドキュメントは `openclaw/openclaw` で作成されます。 +- ソースドキュメントツリーは `docs/` 配下にあります。 +- ソースリポジトリには、`docs/zh-CN/**`、`docs/ja-JP/**`、`docs/es/**`、`docs/pt-BR/**`、`docs/ko/**`、`docs/de/**`、`docs/fr/**`、`docs/ar/**` などの生成済みロケールツリーは、もはやコミットされた状態では保持されていません。 + +## エンドツーエンドのフロー + +1. `openclaw/openclaw` で英語ドキュメントを編集します。 +2. `main` にプッシュします。 +3. `openclaw/openclaw/.github/workflows/docs-sync-publish.yml` がドキュメントツリーを `openclaw/docs` にミラーリングします。 +4. sync スクリプトは公開側の `docs/docs.json` を書き換え、ソースリポジトリにはもはやコミットされていなくても、そこで生成されたロケールピッカーブロックが存在するようにします。 +5. `openclaw/docs/.github/workflows/translate-zh-cn.yml` は、`docs/zh-CN/**` を 1 日 1 回、オンデマンド、およびソースリポジトリのリリース dispatch 後に更新します。 +6. `openclaw/docs/.github/workflows/translate-ja-jp.yml` も `docs/ja-JP/**` に対して同じことを行います。 +7. `openclaw/docs/.github/workflows/translate-es.yml`、`translate-pt-br.yml`、`translate-ko.yml`、`translate-de.yml`、`translate-fr.yml`、`translate-ar.yml` も、`docs/es/**`、`docs/pt-BR/**`、`docs/ko/**`、`docs/de/**`、`docs/fr/**`、`docs/ar/**` に対して同じことを行います。 + +## この分割が存在する理由 + +- 生成されたロケール出力をメインの製品リポジトリの外に出しておくため。 +- Mintlify を単一の公開ドキュメントツリー上で維持するため。 +- 公開リポジトリに生成済みロケールツリーを管理させることで、組み込みの言語スイッチャーを維持するため。 + +## このフォルダー内のファイル + +- `glossary..json` — プロンプトガイダンスとして使われる推奨用語マッピング。 +- `ar-navigation.json`、`de-navigation.json`、`es-navigation.json`、`fr-navigation.json`、`ja-navigation.json`、`ko-navigation.json`、`pt-BR-navigation.json`、`zh-Hans-navigation.json` — sync 中に公開リポジトリへ再挿入される Mintlify のロケールピッカーブロック。 +- `.tm.jsonl` — ワークフロー + モデル + テキストハッシュをキーにした翻訳メモリ。 + +このリポジトリでは、`docs/.i18n/zh-CN.tm.jsonl`、`docs/.i18n/ja-JP.tm.jsonl`、`docs/.i18n/es.tm.jsonl`、`docs/.i18n/pt-BR.tm.jsonl`、`docs/.i18n/ko.tm.jsonl`、`docs/.i18n/de.tm.jsonl`、`docs/.i18n/fr.tm.jsonl`、`docs/.i18n/ar.tm.jsonl` などの生成済みロケール TM ファイルは、意図的にもはやコミットされていません。 + +## 用語集の形式 + +`glossary..json` は、エントリーの配列です。 + +```json +{ + "source": "troubleshooting", + "target": "故障排除" +} +``` + +フィールド: + +- `source`: 優先したい英語（またはソース）フレーズ。 +- `target`: 優先する翻訳出力。 + +## 翻訳の仕組み + +- `scripts/docs-i18n` は引き続き翻訳生成を管理します。 +- ドキュメントモードでは、各翻訳ページに `x-i18n.source_hash` が書き込まれます。 +- 各公開ワークフローは、現在の英語ソースハッシュと保存されているロケールの `x-i18n.source_hash` を比較して、保留ファイルリストを事前計算します。 +- 保留件数が `0` の場合、高コストな翻訳ステップは完全にスキップされます。 +- 保留ファイルがある場合、ワークフローはそのファイルだけを翻訳します。 +- 公開ワークフローは一時的なモデル形式の失敗を再試行しますが、同じハッシュチェックが再試行ごとに実行されるため、変更のないファイルは引き続きスキップされます。 +- ソースリポジトリは、公開済み GitHub リリースの後に zh-CN、ja-JP、es、pt-BR、ko、de、fr、ar の更新も dispatch するため、リリースドキュメントは毎日の cron を待たずに追従できます。 + +## 運用メモ + +- sync メタデータは、公開リポジトリの `.openclaw-sync/source.json` に書き込まれます。 +- ソースリポジトリのシークレット: `OPENCLAW_DOCS_SYNC_TOKEN` +- 公開リポジトリのシークレット: `OPENCLAW_DOCS_I18N_OPENAI_API_KEY` +- ロケール出力が古く見える場合は、まず `openclaw/docs` の対応する `Translate ` ワークフローを確認してください。 diff --git a/docs/ja-JP/auth-credential-semantics.md b/docs/ja-JP/auth-credential-semantics.md new file mode 100644 index 000000000..6234b8651 --- /dev/null +++ b/docs/ja-JP/auth-credential-semantics.md @@ -0,0 +1,79 @@ +--- +read_when: + - 認証プロファイルの解決や認証情報ルーティングに取り組んでいるとき + - モデル認証の失敗やプロファイル順序をデバッグしているとき +summary: 認証プロファイルにおける認証情報の適格性と解決セマンティクスの正規仕様 +title: 認証情報の認証セマンティクス +x-i18n: + generated_at: "2026-04-05T12:34:10Z" + model: gpt-5.4 + provider: openai + source_hash: a4cd3e16cd25eb22c5e707311d06a19df1a59747ee3261c2d32c534a245fd7fb + source_path: auth-credential-semantics.md + workflow: 15 +--- + +# 認証情報の認証セマンティクス + +このドキュメントでは、以下で共通して使用される認証情報の適格性および解決セマンティクスの正規仕様を定義します。 + +- `resolveAuthProfileOrder` +- `resolveApiKeyForProfile` +- `models status --probe` +- `doctor-auth` + +目的は、選択時の動作と実行時の動作を一致させることです。 + +## 安定したプローブ理由コード + +- `ok` +- `excluded_by_auth_order` +- `missing_credential` +- `invalid_expires` +- `expired` +- `unresolved_ref` +- `no_model` + +## トークン認証情報 + +トークン認証情報（`type: "token"`）は、インラインの`token`および/または`tokenRef`をサポートします。 + +### 適格性ルール + +1. `token`と`tokenRef`の両方が存在しない場合、トークンプロファイルは不適格です。 +2. `expires`は任意です。 +3. `expires`が存在する場合、それは`0`より大きい有限数でなければなりません。 +4. `expires`が無効な場合（`NaN`、`0`、負数、非有限、または型が不正）、そのプロファイルは`invalid_expires`で不適格になります。 +5. `expires`が過去の時刻である場合、そのプロファイルは`expired`で不適格になります。 +6. `tokenRef`は`expires`の検証を回避しません。 + +### 解決ルール + +1. リゾルバーのセマンティクスは、`expires`に関して適格性セマンティクスと一致します。 +2. 適格なプロファイルでは、トークンの内容はインライン値または`tokenRef`から解決される場合があります。 +3. 解決できない参照は、`models status --probe`の出力で`unresolved_ref`になります。 + +## 明示的な認証順序フィルタリング + +- あるプロバイダーに対して`auth.order.`または認証ストアの順序オーバーライドが設定されている場合、`models status --probe`は、そのプロバイダーに対して解決された認証順序に残っているプロファイルIDのみをプローブします。 +- そのプロバイダー用に保存されているプロファイルで、明示的な順序から除外されているものは、後で暗黙的に試行されません。プローブ出力では、それは`reasonCode: excluded_by_auth_order`および詳細`Excluded by auth.order for this provider.`として報告されます。 + +## プローブ対象の解決 + +- プローブ対象は、認証プロファイル、環境認証情報、または`models.json`から取得される場合があります。 +- あるプロバイダーに認証情報があっても、OpenClawがそのプロバイダーに対してプローブ可能なモデル候補を解決できない場合、`models status --probe`は`reasonCode: no_model`を伴う`status: no_model`を報告します。 + +## OAuth SecretRef ポリシーガード + +- SecretRef入力は静的な認証情報専用です。 +- プロファイル認証情報が`type: "oauth"`である場合、そのプロファイル認証情報の内容についてはSecretRefオブジェクトはサポートされません。 +- `auth.profiles..mode`が`"oauth"`である場合、そのプロファイルに対するSecretRefベースの`keyRef`/`tokenRef`入力は拒否されます。 +- 違反は、起動時またはリロード時の認証解決パスでハードエラーになります。 + +## レガシー互換メッセージ + +スクリプト互換性のため、プローブエラーではこの1行目を変更せずに維持します。 + +`Auth profile credentials are missing or expired.` + +人間にわかりやすい詳細および安定した理由コードは、後続の行に追加できます。 diff --git a/docs/ja-JP/automation/auth-monitoring.md b/docs/ja-JP/automation/auth-monitoring.md new file mode 100644 index 000000000..3422decc2 --- /dev/null +++ b/docs/ja-JP/automation/auth-monitoring.md @@ -0,0 +1,15 @@ +--- +summary: /gateway/authentication にリダイレクト +title: 認証の監視 +x-i18n: + generated_at: "2026-04-05T12:33:57Z" + model: gpt-5.4 + provider: openai + source_hash: 42aa1b4aa76201b20e07d8ad77231607855e7e7421fa032830055144ccd8819a + source_path: automation/auth-monitoring.md + workflow: 15 +--- + +# 認証の監視 + +このページは[認証](/gateway/authentication)に移動しました。認証の監視に関するドキュメントは[認証](/gateway/authentication)を参照してください。 diff --git a/docs/ja-JP/automation/clawflow.md b/docs/ja-JP/automation/clawflow.md new file mode 100644 index 000000000..ef45a5c6d --- /dev/null +++ b/docs/ja-JP/automation/clawflow.md @@ -0,0 +1,15 @@ +--- +summary: Task Flow にリダイレクト +title: ClawFlow +x-i18n: + generated_at: "2026-04-05T12:33:58Z" + model: gpt-5.4 + provider: openai + source_hash: e644237e0812f25b46a06ff125c8858dbc69a499aa43cfd73cf7cb37572e78e6 + source_path: automation/clawflow.md + workflow: 15 +--- + +# ClawFlow + +ClawFlow は [Task Flow](/automation/taskflow) に名称変更されました。現在のドキュメントについては、[Task Flow](/automation/taskflow) を参照してください。 diff --git a/docs/ja-JP/automation/cron-jobs.md b/docs/ja-JP/automation/cron-jobs.md new file mode 100644 index 000000000..582114745 --- /dev/null +++ b/docs/ja-JP/automation/cron-jobs.md @@ -0,0 +1,385 @@ +--- +read_when: + - バックグラウンドジョブやウェイクアップをスケジューリングするとき + - 外部トリガー（Webhook、Gmail）をOpenClawに接続するとき + - スケジュール済みタスクでheartbeatとcronのどちらを使うか判断するとき +summary: Gatewayスケジューラ向けのスケジュール済みジョブ、Webhook、Gmail PubSubトリガー +title: スケジュール済みタスク +x-i18n: + generated_at: "2026-04-05T12:34:53Z" + model: gpt-5.4 + provider: openai + source_hash: 43b906914461aba9af327e7e8c22aa856f65802ec2da37ed0c4f872d229cfde6 + source_path: automation/cron-jobs.md + workflow: 15 +--- + +# スケジュール済みタスク（Cron） + +CronはGatewayに組み込まれたスケジューラです。ジョブを永続化し、適切なタイミングでエージェントを起動し、出力をチャットチャンネルやWebhookエンドポイントに返送できます。 + +## クイックスタート + +```bash +# 1回限りのリマインダーを追加 +openclaw cron add \ + --name "Reminder" \ + --at "2026-02-01T16:00:00Z" \ + --session main \ + --system-event "Reminder: check the cron docs draft" \ + --wake now \ + --delete-after-run + +# ジョブを確認 +openclaw cron list + +# 実行履歴を確認 +openclaw cron runs --id +``` + +## cronの仕組み + +- Cronは**Gatewayプロセス内**で実行されます（モデル内ではありません）。 +- ジョブは`~/.openclaw/cron/jobs.json`に永続化されるため、再起動してもスケジュールは失われません。 +- すべてのcron実行では[バックグラウンドタスク](/automation/tasks)レコードが作成されます。 +- 1回限りのジョブ（`--at`）は、デフォルトで成功後に自動削除されます。 +- 分離されたcron実行では、実行完了時にその`cron:`セッション用に追跡されているブラウザータブやプロセスをベストエフォートで閉じるため、切り離されたブラウザー自動化によって孤立プロセスが残ることを防ぎます。 +- 分離されたcron実行では、古い確認応答の返信も防ぎます。最初の結果が単なる中間ステータス更新（`on it`、`pulling everything together`、および類似のヒント）であり、最終回答を担当する子孫subagent実行がまだ存在しない場合、OpenClawは配信前に実際の結果を得るためにもう一度プロンプトを送ります。 + +cronのタスク照合はランタイムが管理します。古い子セッション行がまだ存在していても、cronランタイムがそのジョブを実行中として追跡している間は、アクティブなcronタスクは有効なままです。ランタイムがそのジョブの所有を終了し、5分間の猶予時間が過ぎると、メンテナンスによってタスクは`lost`としてマークされる場合があります。 + +## スケジュールの種類 + +| 種類 | CLIフラグ | 説明 | +| ------- | --------- | ------------------------------------------------------ | +| `at` | `--at` | 1回限りのタイムスタンプ（ISO 8601、または`20m`のような相対指定） | +| `every` | `--every` | 固定間隔 | +| `cron` | `--cron` | オプションの`--tz`付き5フィールドまたは6フィールドのcron式 | + +タイムゾーンなしのタイムスタンプはUTCとして扱われます。ローカルの壁時計時刻でスケジュールするには`--tz America/New_York`を追加してください。 + +毎時ちょうどに実行される定期式は、負荷の急増を減らすために最大5分まで自動的にずらされます。正確なタイミングを強制するには`--exact`を、明示的なウィンドウを指定するには`--stagger 30s`を使用してください。 + +## 実行スタイル + +| スタイル | `--session`値 | 実行場所 | 最適な用途 | +| --------------- | ------------------- | ------------------------ | ------------------------------ | +| メインセッション | `main` | 次のheartbeatターン | リマインダー、システムイベント | +| 分離 | `isolated` | 専用の`cron:` | レポート、バックグラウンド作業 | +| 現在のセッション | `current` | 作成時にバインド | コンテキストを意識した定期作業 | +| カスタムセッション | `session:custom-id` | 永続的な名前付きセッション | 履歴を活用するワークフロー | + +**メインセッション**ジョブはシステムイベントをキューに追加し、必要に応じてheartbeatを起動します（`--wake now`または`--wake next-heartbeat`）。**分離**ジョブは新しいセッションで専用のエージェントターンを実行します。**カスタムセッション**（`session:xxx`）は実行間でコンテキストを保持するため、以前の要約をもとに構築する日次スタンドアップのようなワークフローを実現できます。 + +分離ジョブでは、ランタイムのティアダウンにそのcronセッションのベストエフォートなブラウザークリーンアップが含まれるようになりました。クリーンアップ失敗は無視されるため、実際のcron結果が優先されます。 + +分離されたcron実行でsubagentをオーケストレーションする場合、配信では古い親の中間テキストよりも最終的な子孫出力が優先されます。子孫がまだ実行中の場合、OpenClawはその部分的な親更新を通知せず抑制します。 + +### 分離ジョブのペイロードオプション + +- `--message`: プロンプトテキスト（分離では必須） +- `--model` / `--thinking`: モデルおよび思考レベルのオーバーライド +- `--light-context`: ワークスペースのブートストラップファイル注入をスキップ +- `--tools exec,read`: ジョブで使用できるツールを制限 + +`--model`は、そのジョブに対して選択された許可済みモデルを使用します。要求されたモデルが許可されていない場合、cronは警告を記録し、代わりにジョブのagent/defaultモデル選択にフォールバックします。設定済みのフォールバックチェーンは引き続き適用されますが、明示的なジョブ単位のフォールバックリストがない単純なモデルオーバーライドでは、agent primaryが隠れた追加再試行先として付加されなくなりました。 + +分離ジョブのモデル選択優先順位は次のとおりです。 + +1. Gmailフックのモデルオーバーライド（実行がGmail由来で、そのオーバーライドが許可されている場合） +2. ジョブ単位ペイロードの`model` +3. 保存済みcronセッションのモデルオーバーライド +4. Agent/defaultモデル選択 + +Fast modeも解決された実際の選択に従います。選択されたモデル設定に`params.fastMode`がある場合、分離cronはデフォルトでそれを使用します。保存済みセッションの`fastMode`オーバーライドは、どちらの方向でも設定より優先されます。 + +分離実行がライブのモデル切り替えハンドオフに遭遇した場合、cronは切り替え後のprovider/modelで再試行し、そのライブ選択を再試行前に永続化します。切り替えに新しい認証プロファイルも含まれる場合、cronはその認証プロファイルのオーバーライドも永続化します。再試行回数には上限があります。初回試行に加えて切り替え再試行を2回行った後は、無限ループを避けるためcronは中止します。 + +## 配信と出力 + +| モード | 動作 | +| ----------- | -------------------------------------------------------- | +| `announce` | ターゲットチャンネルに要約を配信（分離のデフォルト） | +| `webhook` | 完了イベントのペイロードをURLにPOST | +| `none` | 内部のみ、配信なし | + +チャンネル配信には`--announce --channel telegram --to "-1001234567890"`を使用します。Telegramフォーラムトピックでは`-1001234567890:topic:123`を使用してください。Slack/Discord/Mattermostターゲットでは明示的なプレフィックス（`channel:`、`user:`）を使用する必要があります。 + +cronが所有する分離ジョブでは、runnerが最終配信経路を管理します。agentにはプレーンテキストの要約を返すようプロンプトが与えられ、その要約が`announce`、`webhook`を通じて送信されるか、`none`の場合は内部に保持されます。`--no-deliver`は配信をagentに戻しません。実行を内部のみのままにします。 + +元のタスクで明示的に外部の受信者へメッセージ送信するよう指定されている場合、agentは直接送信を試みるのではなく、そのメッセージを誰に／どこへ送るべきかを出力内に記す必要があります。 + +失敗通知は別の宛先経路に従います。 + +- `cron.failureDestination`は失敗通知のグローバルデフォルトを設定します。 +- `job.delivery.failureDestination`はジョブ単位でそれを上書きします。 +- どちらも設定されておらず、かつジョブがすでに`announce`で配信している場合、失敗通知はそのプライマリのannounceターゲットにフォールバックするようになりました。 +- `delivery.failureDestination`は、プライマリ配信モードが`webhook`でない限り、`sessionTarget="isolated"`ジョブでのみサポートされます。 + +## CLIの例 + +1回限りのリマインダー（メインセッション）: + +```bash +openclaw cron add \ + --name "Calendar check" \ + --at "20m" \ + --session main \ + --system-event "Next heartbeat: check calendar." \ + --wake now +``` + +配信付きの定期分離ジョブ: + +```bash +openclaw cron add \ + --name "Morning brief" \ + --cron "0 7 * * *" \ + --tz "America/Los_Angeles" \ + --session isolated \ + --message "Summarize overnight updates." \ + --announce \ + --channel slack \ + --to "channel:C1234567890" +``` + +モデルおよびthinkingオーバーライド付きの分離ジョブ: + +```bash +openclaw cron add \ + --name "Deep analysis" \ + --cron "0 6 * * 1" \ + --tz "America/Los_Angeles" \ + --session isolated \ + --message "Weekly deep analysis of project progress." \ + --model "opus" \ + --thinking high \ + --announce +``` + +## Webhook + +Gatewayは外部トリガー向けにHTTP Webhookエンドポイントを公開できます。configで有効にします。 + +```json5 +{ + hooks: { + enabled: true, + token: "shared-secret", + path: "/hooks", + }, +} +``` + +### 認証 + +すべてのリクエストには、ヘッダー経由でフックトークンを含める必要があります。 + +- `Authorization: Bearer `（推奨） +- `x-openclaw-token: ` + +クエリ文字列トークンは拒否されます。 + +### POST /hooks/wake + +メインセッション向けにシステムイベントをキューに追加します。 + +```bash +curl -X POST http://127.0.0.1:18789/hooks/wake \ + -H 'Authorization: Bearer SECRET' \ + -H 'Content-Type: application/json' \ + -d '{"text":"New email received","mode":"now"}' +``` + +- `text`（必須）: イベントの説明 +- `mode`（任意）: `now`（デフォルト）または`next-heartbeat` + +### POST /hooks/agent + +分離されたagentターンを実行します。 + +```bash +curl -X POST http://127.0.0.1:18789/hooks/agent \ + -H 'Authorization: Bearer SECRET' \ + -H 'Content-Type: application/json' \ + -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}' +``` + +フィールド: `message`（必須）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`thinking`、`timeoutSeconds`。 + +### マップされたフック（POST /hooks/\） + +カスタムフック名は、config内の`hooks.mappings`によって解決されます。マッピングはテンプレートやコード変換を使って、任意のペイロードを`wake`または`agent`アクションに変換できます。 + +### セキュリティ + +- フックエンドポイントはloopback、tailnet、または信頼できるリバースプロキシの背後に置いてください。 +- 専用のフックトークンを使用し、Gateway認証トークンを再利用しないでください。 +- `hooks.path`は専用のサブパスにしてください。`/`は拒否されます。 +- 明示的な`agentId`ルーティングを制限するには`hooks.allowedAgentIds`を設定してください。 +- 呼び出し元がセッションを選択する必要がない限り、`hooks.allowRequestSessionKey=false`のままにしてください。 +- `hooks.allowRequestSessionKey`を有効にする場合は、許可されるセッションキー形状を制約するために`hooks.allowedSessionKeyPrefixes`も設定してください。 +- フックペイロードはデフォルトで安全境界でラップされます。 + +## Gmail PubSub統合 + +Google PubSubを通じてGmail受信トリガーをOpenClawに接続します。 + +**前提条件**: `gcloud` CLI、`gog`（gogcli）、OpenClaw hooksが有効、公開HTTPSエンドポイント用のTailscale。 + +### ウィザードセットアップ（推奨） + +```bash +openclaw webhooks gmail setup --account openclaw@gmail.com +``` + +これにより`hooks.gmail` configが書き込まれ、Gmailプリセットが有効化され、プッシュエンドポイントにはTailscale Funnelが使用されます。 + +### Gateway自動起動 + +`hooks.enabled=true`かつ`hooks.gmail.account`が設定されている場合、Gatewayは起動時に`gog gmail watch serve`を開始し、watchを自動更新します。無効にするには`OPENCLAW_SKIP_GMAIL_WATCHER=1`を設定してください。 + +### 手動による1回限りのセットアップ + +1. `gog`で使用されるOAuthクライアントを所有するGCPプロジェクトを選択します。 + +```bash +gcloud auth login +gcloud config set project +gcloud services enable gmail.googleapis.com pubsub.googleapis.com +``` + +2. トピックを作成し、Gmailのpushアクセス権を付与します。 + +```bash +gcloud pubsub topics create gog-gmail-watch +gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \ + --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \ + --role=roles/pubsub.publisher +``` + +3. watchを開始します。 + +```bash +gog gmail watch start \ + --account openclaw@gmail.com \ + --label INBOX \ + --topic projects//topics/gog-gmail-watch +``` + +### Gmailモデルオーバーライド + +```json5 +{ + hooks: { + gmail: { + model: "openrouter/meta-llama/llama-3.3-70b-instruct:free", + thinking: "off", + }, + }, +} +``` + +## ジョブの管理 + +```bash +# すべてのジョブを一覧表示 +openclaw cron list + +# ジョブを編集 +openclaw cron edit --message "Updated prompt" --model "opus" + +# ジョブを今すぐ強制実行 +openclaw cron run + +# 期限到来時のみ実行 +openclaw cron run --due + +# 実行履歴を表示 +openclaw cron runs --id --limit 50 + +# ジョブを削除 +openclaw cron remove + +# Agent選択（マルチagentセットアップ） +openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops +openclaw cron edit --clear-agent +``` + +モデルオーバーライドに関する注意: + +- `openclaw cron add|edit --model ...`はジョブの選択モデルを変更します。 +- モデルが許可されている場合、その正確なprovider/modelが分離agent実行に渡されます。 +- 許可されていない場合、cronは警告を出し、ジョブのagent/defaultモデル選択にフォールバックします。 +- 設定済みのフォールバックチェーンは引き続き適用されますが、明示的なジョブ単位のフォールバックリストがない単純な`--model`オーバーライドでは、agent primaryに暗黙の追加再試行先としてフォールスルーしなくなりました。 + +## 設定 + +```json5 +{ + cron: { + enabled: true, + store: "~/.openclaw/cron/jobs.json", + maxConcurrentRuns: 1, + retry: { + maxAttempts: 3, + backoffMs: [60000, 120000, 300000], + retryOn: ["rate_limit", "overloaded", "network", "server_error"], + }, + webhookToken: "replace-with-dedicated-webhook-token", + sessionRetention: "24h", + runLog: { maxBytes: "2mb", keepLines: 2000 }, + }, +} +``` + +cronを無効化するには: `cron.enabled: false`または`OPENCLAW_SKIP_CRON=1`。 + +**1回限りの再試行**: 一時的なエラー（レート制限、過負荷、ネットワーク、サーバーエラー）は指数バックオフで最大3回まで再試行されます。永続的なエラーは即座に無効化されます。 + +**定期実行の再試行**: 再試行間には指数バックオフ（30秒〜60分）が適用されます。次に成功した実行の後でバックオフはリセットされます。 + +**メンテナンス**: `cron.sessionRetention`（デフォルト`24h`）は分離実行セッションエントリーを剪定します。`cron.runLog.maxBytes` / `cron.runLog.keepLines`は実行ログファイルを自動的に剪定します。 + +## トラブルシューティング + +### コマンド一覧 + +```bash +openclaw status +openclaw gateway status +openclaw cron status +openclaw cron list +openclaw cron runs --id --limit 20 +openclaw system heartbeat last +openclaw logs --follow +openclaw doctor +``` + +### cronが実行されない + +- `cron.enabled`と`OPENCLAW_SKIP_CRON`環境変数を確認してください。 +- Gatewayが継続的に実行中であることを確認してください。 +- `cron`スケジュールでは、タイムゾーン（`--tz`）とホストのタイムゾーンの違いを確認してください。 +- 実行出力の`reason: not-due`は、手動実行が`openclaw cron run --due`で確認され、そのジョブがまだ期限前だったことを意味します。 + +### cronは実行されたが配信されない + +- 配信モードが`none`の場合、外部メッセージは送信されません。 +- 配信ターゲットが欠落または無効（`channel`/`to`）な場合、送信はスキップされます。 +- チャンネル認証エラー（`unauthorized`、`Forbidden`）は、認証情報によって配信がブロックされたことを意味します。 +- 分離実行がサイレントトークン（`NO_REPLY` / `no_reply`）のみを返した場合、OpenClawは直接の外向き配信を抑制し、フォールバックのキュー要約経路も抑制するため、チャットには何も投稿されません。 +- cronが所有する分離ジョブでは、agentがフォールバックとしてmessageツールを使うことは想定しないでください。runnerが最終配信を管理します。`--no-deliver`は直接送信を許可するのではなく、内部のまま保持します。 + +### タイムゾーンの注意点 + +- `--tz`なしのcronはGatewayホストのタイムゾーンを使用します。 +- タイムゾーンなしの`at`スケジュールはUTCとして扱われます。 +- Heartbeatの`activeHours`は設定済みタイムゾーン解決を使用します。 + +## 関連 + +- [Automation & Tasks](/automation) — すべての自動化メカニズムの概要 +- [Background Tasks](/automation/tasks) — cron実行のタスク台帳 +- [Heartbeat](/gateway/heartbeat) — 定期的なメインセッションターン +- [Timezone](/concepts/timezone) — タイムゾーン設定 diff --git a/docs/ja-JP/automation/cron-vs-heartbeat.md b/docs/ja-JP/automation/cron-vs-heartbeat.md new file mode 100644 index 000000000..518a4121f --- /dev/null +++ b/docs/ja-JP/automation/cron-vs-heartbeat.md @@ -0,0 +1,15 @@ +--- +summary: /automation にリダイレクト +title: Cron と Heartbeat の比較 +x-i18n: + generated_at: "2026-04-05T12:33:57Z" + model: gpt-5.4 + provider: openai + source_hash: 579c6618108ad7e2a71f53d5d6aa6550956fa0fdb2fe64ecdb7e8a0ce1366e33 + source_path: automation/cron-vs-heartbeat.md + workflow: 15 +--- + +# Cron と Heartbeat の比較 + +このページは[Automation & Tasks](/automation)に移動しました。cron と heartbeat を比較する判断ガイドについては、[Automation & Tasks](/automation)を参照してください。 diff --git a/docs/ja-JP/automation/gmail-pubsub.md b/docs/ja-JP/automation/gmail-pubsub.md new file mode 100644 index 000000000..ac92d8da3 --- /dev/null +++ b/docs/ja-JP/automation/gmail-pubsub.md @@ -0,0 +1,15 @@ +--- +summary: /automation/cron-jobs にリダイレクト +title: Gmail PubSub +x-i18n: + generated_at: "2026-04-05T12:33:58Z" + model: gpt-5.4 + provider: openai + source_hash: c2e17fdc8c09d52b6dc9fb6c44053446f07d02c65a0ab725d4ea038bd035d889 + source_path: automation/gmail-pubsub.md + workflow: 15 +--- + +# Gmail PubSub + +このページは [Scheduled Tasks](/automation/cron-jobs#gmail-pubsub-integration) に移動しました。Gmail PubSub のドキュメントについては、[Scheduled Tasks](/automation/cron-jobs#gmail-pubsub-integration) を参照してください。 diff --git a/docs/ja-JP/automation/hooks.md b/docs/ja-JP/automation/hooks.md new file mode 100644 index 000000000..443fe173a --- /dev/null +++ b/docs/ja-JP/automation/hooks.md @@ -0,0 +1,310 @@ +--- +read_when: + - '`/new`、`/reset`、`/stop`、およびエージェントのライフサイクルイベント向けのイベント駆動型自動化が必要な場合' + - hooksの構築、インストール、またはデバッグを行いたい場合 +summary: Hooks：コマンドとライフサイクルイベントのためのイベント駆動型自動化 +title: Hooks +x-i18n: + generated_at: "2026-04-05T12:34:32Z" + model: gpt-5.4 + provider: openai + source_hash: 66eb75bb2b3b2ad229bf3da24fdb0fe021ed08f812fd1d13c69b3bd9df0218e5 + source_path: automation/hooks.md + workflow: 15 +--- + +# Hooks + +Hooksは、Gateway内で何かが起きたときに実行される小さなスクリプトです。ディレクトリから自動的に検出され、`openclaw hooks`で確認できます。 + +OpenClawには2種類のhooksがあります。 + +- **内部hooks**（このページ）: `/new`、`/reset`、`/stop`、またはライフサイクルイベントのようなエージェントイベントが発生したときにGateway内で実行されます。 +- **Webhooks**: 他のシステムがOpenClaw内で処理をトリガーできるようにする外部HTTPエンドポイントです。[Webhooks](/automation/cron-jobs#webhooks)を参照してください。 + +Hooksはplugins内に同梱することもできます。`openclaw hooks list`には、スタンドアロンhooksとplugin管理hooksの両方が表示されます。 + +## クイックスタート + +```bash +# 利用可能なhooksを一覧表示 +openclaw hooks list + +# hookを有効化 +openclaw hooks enable session-memory + +# hookのステータスを確認 +openclaw hooks check + +# 詳細情報を取得 +openclaw hooks info session-memory +``` + +## イベントの種類 + +| Event | 発火するタイミング | +| ------------------------ | -------------------------------------- | +| `command:new` | `/new`コマンドが実行されたとき | +| `command:reset` | `/reset`コマンドが実行されたとき | +| `command:stop` | `/stop`コマンドが実行されたとき | +| `command` | 任意のコマンドイベント（汎用リスナー） | +| `session:compact:before` | compactionが履歴を要約する前 | +| `session:compact:after` | compactionの完了後 | +| `session:patch` | セッションのプロパティが変更されたとき | +| `agent:bootstrap` | ワークスペースのbootstrapファイルが注入される前 | +| `gateway:startup` | channelsが起動し、hooksが読み込まれた後 | +| `message:received` | 任意のchannelから受信した受信メッセージ | +| `message:transcribed` | 音声文字起こしの完了後 | +| `message:preprocessed` | すべてのメディア処理とリンク理解の完了後 | +| `message:sent` | 送信メッセージが配信されたとき | + +## hooksの作成 + +### hookの構成 + +各hookは、2つのファイルを含むディレクトリです。 + +``` +my-hook/ +├── HOOK.md # メタデータ + ドキュメント +└── handler.ts # ハンドラー実装 +``` + +### HOOK.md形式 + +```markdown +--- +name: my-hook +description: "このhookが行うことの短い説明" +metadata: + { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } +--- + +# My Hook + +詳細なドキュメントをここに記述します。 +``` + +**メタデータフィールド**（`metadata.openclaw`）: + +| Field | 説明 | +| ---------- | ---------------------------------------------------- | +| `emoji` | CLIに表示する絵文字 | +| `events` | 監視するイベントの配列 | +| `export` | 使用する名前付きexport（デフォルトは`"default"`） | +| `os` | 必要なプラットフォーム（例: `["darwin", "linux"]`） | +| `requires` | 必須の`bins`、`anyBins`、`env`、または`config`パス | +| `always` | 適格性チェックをバイパスするかどうか（boolean） | +| `install` | インストール方法 | + +### ハンドラー実装 + +```typescript +const handler = async (event) => { + if (event.type !== "command" || event.action !== "new") { + return; + } + + console.log(`[my-hook] New command triggered`); + // Your logic here + + // Optionally send message to user + event.messages.push("Hook executed!"); +}; + +export default handler; +``` + +各イベントには次が含まれます: `type`、`action`、`sessionKey`、`timestamp`、`messages`（ユーザーに送信するにはpush）、および`context`（イベント固有のデータ）。 + +### イベントコンテキストの主な項目 + +**コマンドイベント**（`command:new`、`command:reset`）: `context.sessionEntry`、`context.previousSessionEntry`、`context.commandSource`、`context.workspaceDir`、`context.cfg`。 + +**メッセージイベント**（`message:received`）: `context.from`、`context.content`、`context.channelId`、`context.metadata`（`senderId`、`senderName`、`guildId`を含むプロバイダー固有データ）。 + +**メッセージイベント**（`message:sent`）: `context.to`、`context.content`、`context.success`、`context.channelId`。 + +**メッセージイベント**（`message:transcribed`）: `context.transcript`、`context.from`、`context.channelId`、`context.mediaPath`。 + +**メッセージイベント**（`message:preprocessed`）: `context.bodyForAgent`（最終的に拡張された本文）、`context.from`、`context.channelId`。 + +**Bootstrapイベント**（`agent:bootstrap`）: `context.bootstrapFiles`（変更可能な配列）、`context.agentId`。 + +**セッションpatchイベント**（`session:patch`）: `context.sessionEntry`、`context.patch`（変更されたフィールドのみ）、`context.cfg`。patchイベントをトリガーできるのは特権クライアントのみです。 + +**Compactionイベント**: `session:compact:before`には`messageCount`、`tokenCount`が含まれます。`session:compact:after`にはさらに`compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`が追加されます。 + +## hookの検出 + +Hooksは、上書き優先度が低い順から高い順に、次のディレクトリから検出されます。 + +1. **同梱hooks**: OpenClawに同梱されるもの +2. **Plugin hooks**: インストール済みplugins内に同梱されるhooks +3. **Managed hooks**: `~/.openclaw/hooks/`（ユーザーがインストールし、ワークスペース間で共有されるもの）。`hooks.internal.load.extraDirs`の追加ディレクトリもこの優先度を共有します。 +4. **Workspace hooks**: `/hooks/`（エージェントごと。明示的に有効化するまでデフォルトでは無効） + +Workspace hooksは新しいhook名を追加できますが、同じ名前の同梱、managed、またはplugin提供hookを上書きすることはできません。 + +### hookパック + +hookパックは、`package.json`内の`openclaw.hooks`を通じてhooksを公開するnpmパッケージです。次のようにインストールします。 + +```bash +openclaw plugins install +``` + +npm specはレジストリ専用です（パッケージ名 + 任意の正確なバージョンまたはdist-tag）。Git/URL/file specおよびsemver rangeは拒否されます。 + +## 同梱hooks + +| Hook | Events | 動作内容 | +| --------------------- | ------------------------------ | ----------------------------------------------------- | +| session-memory | `command:new`, `command:reset` | セッションコンテキストを`/memory/`に保存 | +| bootstrap-extra-files | `agent:bootstrap` | globパターンから追加のbootstrapファイルを注入 | +| command-logger | `command` | すべてのコマンドを`~/.openclaw/logs/commands.log`に記録 | +| boot-md | `gateway:startup` | gatewayの起動時に`BOOT.md`を実行 | + +任意の同梱hookを有効化するには、次を実行します。 + +```bash +openclaw hooks enable +``` + +### session-memoryの詳細 + +直近15件のユーザー/assistantメッセージを抽出し、LLMで説明的なファイル名スラッグを生成して、`/memory/YYYY-MM-DD-slug.md`に保存します。`workspace.dir`が設定されている必要があります。 + +### bootstrap-extra-filesの設定 + +```json +{ + "hooks": { + "internal": { + "entries": { + "bootstrap-extra-files": { + "enabled": true, + "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"] + } + } + } + } +} +``` + +パスはワークスペースを基準に解決されます。認識されるbootstrap basenameのみが読み込まれます（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 + +## Plugin hooks + +Pluginsは、より深い統合のためにPlugin SDKを通じてhooksを登録できます。これには、ツール呼び出しのインターセプト、プロンプトの変更、メッセージフローの制御などが含まれます。Plugin SDKは、モデル解決、エージェントライフサイクル、メッセージフロー、ツール実行、subagent協調、gatewayライフサイクルをカバーする28個のhooksを公開しています。 + +`before_tool_call`、`before_agent_reply`、`before_install`、およびその他すべてのplugin hooksを含む完全なplugin hookリファレンスについては、[Plugin Architecture](/plugins/architecture#provider-runtime-hooks)を参照してください。 + +## 設定 + +```json +{ + "hooks": { + "internal": { + "enabled": true, + "entries": { + "session-memory": { "enabled": true }, + "command-logger": { "enabled": false } + } + } + } +} +``` + +hookごとの環境変数: + +```json +{ + "hooks": { + "internal": { + "entries": { + "my-hook": { + "enabled": true, + "env": { "MY_CUSTOM_VAR": "value" } + } + } + } + } +} +``` + +追加のhookディレクトリ: + +```json +{ + "hooks": { + "internal": { + "load": { + "extraDirs": ["/path/to/more/hooks"] + } + } + } +} +``` + + +従来の`hooks.internal.handlers`配列設定形式も後方互換性のため引き続きサポートされていますが、新しいhooksでは検出ベースのシステムを使用してください。 + + +## CLIリファレンス + +```bash +# すべてのhooksを一覧表示（--eligible、--verbose、または--jsonを追加可能） +openclaw hooks list + +# hookの詳細情報を表示 +openclaw hooks info + +# 適格性の概要を表示 +openclaw hooks check + +# 有効化/無効化 +openclaw hooks enable +openclaw hooks disable +``` + +## ベストプラクティス + +- **ハンドラーは高速に保つ。** Hooksはコマンド処理中に実行されます。重い処理は`void processInBackground(event)`でfire-and-forgetにしてください。 +- **エラーは適切に処理する。** 危険な処理はtry/catchで囲み、他のハンドラーが実行できるようにthrowしないでください。 +- **早い段階でイベントを絞り込む。** イベントのtype/actionが関係ない場合はすぐにreturnしてください。 +- **具体的なイベントキーを使う。** オーバーヘッドを減らすため、`"events": ["command"]`より`"events": ["command:new"]`を優先してください。 + +## トラブルシューティング + +### hookが検出されない + +```bash +# ディレクトリ構造を確認 +ls -la ~/.openclaw/hooks/my-hook/ +# 表示されるべきもの: HOOK.md, handler.ts + +# 検出されたすべてのhooksを一覧表示 +openclaw hooks list +``` + +### hookが適格でない + +```bash +openclaw hooks info my-hook +``` + +不足しているバイナリ（PATH）、環境変数、設定値、またはOS互換性を確認してください。 + +### hookが実行されない + +1. hookが有効になっていることを確認します: `openclaw hooks list` +2. hooksが再読み込みされるようにgatewayプロセスを再起動します。 +3. gatewayログを確認します: `./scripts/clawlog.sh | grep hook` + +## 関連 + +- [CLI Reference: hooks](/cli/hooks) +- [Webhooks](/automation/cron-jobs#webhooks) +- [Plugin Architecture](/plugins/architecture#provider-runtime-hooks) — 完全なplugin hookリファレンス +- [Configuration](/gateway/configuration-reference#hooks) diff --git a/docs/ja-JP/automation/index.md b/docs/ja-JP/automation/index.md new file mode 100644 index 000000000..d41b084f2 --- /dev/null +++ b/docs/ja-JP/automation/index.md @@ -0,0 +1,122 @@ +--- +read_when: + - OpenClaw で作業をどのように自動化するかを決めるとき + - heartbeat、cron、フック、常設指示のどれを使うか選ぶとき + - 適切な自動化の起点を探しているとき +summary: タスク、cron、フック、常設指示、タスクフローなどのオートメーションの仕組みの概要 +title: オートメーションとタスク +x-i18n: + generated_at: "2026-04-05T12:34:27Z" + model: gpt-5.4 + provider: openai + source_hash: 13cd05dcd2f38737f7bb19243ad1136978bfd727006fd65226daa3590f823afe + source_path: automation/index.md + workflow: 15 +--- + +# オートメーションとタスク + +OpenClaw は、タスク、スケジュール済みジョブ、イベントフック、常設指示を通じてバックグラウンドで作業を実行します。このページでは、適切な仕組みを選び、それらがどのように連携するかを理解できるようにします。 + +## クイック判断ガイド + +```mermaid +flowchart TD + START([What do you need?]) --> Q1{Schedule work?} + START --> Q2{Track detached work?} + START --> Q3{Orchestrate multi-step flows?} + START --> Q4{React to lifecycle events?} + START --> Q5{Give the agent persistent instructions?} + + Q1 -->|Yes| Q1a{Exact timing or flexible?} + Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"] + Q1a -->|Flexible| HEARTBEAT[Heartbeat] + + Q2 -->|Yes| TASKS[Background Tasks] + Q3 -->|Yes| FLOW[Task Flow] + Q4 -->|Yes| HOOKS[Hooks] + Q5 -->|Yes| SO[Standing Orders] +``` + +| ユースケース | 推奨 | 理由 | +| --------------------------------------- | ---------------------- | ------------------------------------------------ | +| 毎日午前 9 時ちょうどにレポートを送信する | スケジュール済みタスク（cron） | 正確な時刻指定、分離された実行 | +| 20 分後にリマインドする | スケジュール済みタスク（cron） | 正確な時刻を指定した一回限りの実行（`--at`） | +| 毎週詳細な分析を実行する | スケジュール済みタスク（cron） | 独立したタスクで、別のモデルも使える | +| 30 分ごとに受信箱を確認する | heartbeat | ほかの確認とまとめて処理され、コンテキストを認識できる | +| 今後の予定についてカレンダーを監視する | heartbeat | 定期的な状況把握に自然に適している | +| サブエージェントまたは ACP 実行の状態を確認する | バックグラウンドタスク | タスク台帳がすべての分離された作業を追跡する | +| 何がいつ実行されたかを監査する | バックグラウンドタスク | `openclaw tasks list` と `openclaw tasks audit` | +| 複数段階の調査を行ってから要約する | タスクフロー | リビジョン追跡付きの永続的なオーケストレーション | +| セッションのリセット時にスクリプトを実行する | フック | イベント駆動で、ライフサイクルイベント時に実行される | +| すべてのツール呼び出しでコードを実行する | フック | フックはイベント種別で絞り込める | +| 返信前に常にコンプライアンスを確認する | 常設指示 | すべてのセッションに自動的に注入される | + +### スケジュール済みタスク（cron）と heartbeat の比較 + +| 観点 | スケジュール済みタスク（cron） | heartbeat | +| --------------- | ----------------------------------- | ------------------------------------- | +| タイミング | 正確（cron 式、一回限りの実行） | おおよそ（既定では 30 分ごと） | +| セッションコンテキスト | 新規（分離）または共有 | メインセッションの完全なコンテキスト | +| タスク記録 | 常に作成される | 作成されない | +| 配信 | チャネル、webhook、または無通知 | メインセッション内にインラインで表示 | +| 最適な用途 | レポート、リマインダー、バックグラウンドジョブ | 受信箱確認、カレンダー、通知 | + +正確な時刻指定や分離された実行が必要な場合は、スケジュール済みタスク（cron）を使ってください。作業が完全なセッションコンテキストの恩恵を受け、おおよそのタイミングで十分な場合は、heartbeat を使ってください。 + +## コア概念 + +### スケジュール済みタスク（cron） + +cron は、正確な時刻指定のための Gateway 組み込みスケジューラーです。ジョブを永続化し、適切な時刻にエージェントを起動し、出力をチャットチャネルまたは webhook エンドポイントに配信できます。一回限りのリマインダー、繰り返し式、受信 webhook トリガーをサポートします。 + +[スケジュール済みタスク](/automation/cron-jobs)を参照してください。 + +### タスク + +バックグラウンドタスク台帳は、ACP 実行、サブエージェント起動、分離された cron 実行、CLI 操作など、すべての分離された作業を追跡します。タスクはスケジューラーではなく記録です。確認には `openclaw tasks list` と `openclaw tasks audit` を使います。 + +[バックグラウンドタスク](/automation/tasks)を参照してください。 + +### タスクフロー + +タスクフローは、バックグラウンドタスクの上にあるフローオーケストレーション基盤です。管理同期モードとミラー同期モード、リビジョン追跡、確認用の `openclaw tasks flow list|show|cancel` によって、永続的な複数段階フローを管理します。 + +[タスクフロー](/automation/taskflow)を参照してください。 + +### 常設指示 + +常設指示は、定義されたプログラムに対する永続的な実行権限をエージェントに付与します。これらはワークスペースファイル（通常は `AGENTS.md`）に存在し、すべてのセッションに注入されます。時間ベースの適用には cron と組み合わせてください。 + +[常設指示](/automation/standing-orders)を参照してください。 + +### フック + +フックは、エージェントのライフサイクルイベント（`/new`、`/reset`、`/stop`）、セッション圧縮、Gateway 起動、メッセージフロー、ツール呼び出しによってトリガーされるイベント駆動スクリプトです。フックはディレクトリから自動検出され、`openclaw hooks` で管理できます。 + +[フック](/automation/hooks)を参照してください。 + +### Heartbeat + +heartbeat は、定期的に実行されるメインセッションのターンです（既定では 30 分ごと）。複数の確認事項（受信箱、カレンダー、通知）を、完全なセッションコンテキストを持つ 1 回のエージェントターンにまとめます。heartbeat のターンではタスク記録は作成されません。小さなチェックリストには `HEARTBEAT.md` を使い、heartbeat 自体の中で期限到来時のみの定期チェックを行いたい場合は `tasks:` ブロックを使います。heartbeat ファイルが空の場合は `empty-heartbeat-file` としてスキップされ、期限到来時のみのタスクモードでは `no-tasks-due` としてスキップされます。 + +[Heartbeat](/gateway/heartbeat)を参照してください。 + +## それぞれの連携方法 + +- **cron** は、正確なスケジュール（日次レポート、週次レビュー）と一回限りのリマインダーを扱います。すべての cron 実行でタスク記録が作成されます。 +- **heartbeat** は、受信箱、カレンダー、通知などの日常的な監視を、30 分ごとの 1 回のまとめたターンで処理します。 +- **フック** は、特定のイベント（ツール呼び出し、セッションリセット、圧縮）に対してカスタムスクリプトで反応します。 +- **常設指示** は、永続的なコンテキストと権限の境界をエージェントに与えます。 +- **タスクフロー** は、個々のタスクの上位で複数段階のフローを調整します。 +- **タスク** は、すべての分離された作業を自動的に追跡し、確認や監査を可能にします。 + +## 関連 + +- [スケジュール済みタスク](/automation/cron-jobs) — 正確なスケジューリングと一回限りのリマインダー +- [バックグラウンドタスク](/automation/tasks) — すべての分離された作業のタスク台帳 +- [タスクフロー](/automation/taskflow) — 永続的な複数段階フローのオーケストレーション +- [フック](/automation/hooks) — イベント駆動のライフサイクルスクリプト +- [常設指示](/automation/standing-orders) — 永続的なエージェント指示 +- [Heartbeat](/gateway/heartbeat) — 定期的なメインセッションターン +- [設定リファレンス](/gateway/configuration-reference) — すべての設定キー diff --git a/docs/ja-JP/automation/poll.md b/docs/ja-JP/automation/poll.md new file mode 100644 index 000000000..640b7e0a0 --- /dev/null +++ b/docs/ja-JP/automation/poll.md @@ -0,0 +1,15 @@ +--- +summary: /tools/message にリダイレクト +title: 投票 +x-i18n: + generated_at: "2026-04-05T12:33:59Z" + model: gpt-5.4 + provider: openai + source_hash: 8d69432ad8ba5fd80b59f8df779a1105ce0a2ff767d7dd5dc9d8e3ac1cb1ff1f + source_path: automation/poll.md + workflow: 15 +--- + +# 投票 + +このページは[Message tool](/cli/message)に移動しました。投票に関するドキュメントは[Message tool](/cli/message)を参照してください。 diff --git a/docs/ja-JP/automation/standing-orders.md b/docs/ja-JP/automation/standing-orders.md new file mode 100644 index 000000000..1970187a0 --- /dev/null +++ b/docs/ja-JP/automation/standing-orders.md @@ -0,0 +1,261 @@ +--- +read_when: + - タスクごとのプロンプトなしで実行される自律エージェントワークフローを設定するとき + - エージェントが独立して実行できることと、人間の承認が必要なことを定義するとき + - 明確な境界とエスカレーションルールを持つマルチプログラムエージェントを構成するとき +summary: 自律エージェントプログラムの恒久的な運用権限を定義する +title: 常設命令 +x-i18n: + generated_at: "2026-04-05T12:34:33Z" + model: gpt-5.4 + provider: openai + source_hash: 81347d7a51a6ce20e6493277afee92073770f69a91a2e6b3bf87b99bb586d038 + source_path: automation/standing-orders.md + workflow: 15 +--- + +# 常設命令 + +常設命令は、定義されたプログラムに対してエージェントに**恒久的な運用権限**を付与します。毎回個別のタスク指示を与える代わりに、明確なスコープ、トリガー、エスカレーションルールを持つプログラムを定義し、エージェントはその境界内で自律的に実行します。 + +これは、毎週金曜日にアシスタントへ「週次レポートを送って」と伝えるのと、次のような常設権限を与えることの違いです。「週次レポートはあなたの担当です。毎週金曜日に作成して送信し、何かおかしい場合にのみエスカレーションしてください。」 + +## 常設命令を使う理由 + +**常設命令がない場合:** + +- すべてのタスクでエージェントにプロンプトを送る必要がある +- エージェントはリクエストの合間に待機したままになる +- 定型業務が忘れられたり遅れたりする +- あなた自身がボトルネックになる + +**常設命令がある場合:** + +- エージェントは定義された境界内で自律的に実行する +- 定型業務がプロンプトなしで予定どおりに実行される +- あなたが関与するのは例外対応と承認だけになる +- エージェントが待機時間を生産的に埋める + +## 仕組み + +常設命令は、[agent workspace](/concepts/agent-workspace) のファイルで定義します。推奨される方法は、毎セッション自動注入される `AGENTS.md` に直接含めることです。これにより、エージェントは常にそれらをコンテキストとして持てます。より大きな構成では、`standing-orders.md` のような専用ファイルに置き、`AGENTS.md` から参照することもできます。 + +各プログラムでは次を指定します。 + +1. **スコープ** — エージェントが実行を認可されていること +2. **トリガー** — いつ実行するか（スケジュール、イベント、または条件） +3. **承認ゲート** — 実行前に人間の承認が必要なこと +4. **エスカレーションルール** — いつ停止して助けを求めるか + +エージェントは、ワークスペースのブートストラップファイルを通じて毎セッションこれらの指示を読み込み（自動注入されるファイルの完全な一覧は [Agent Workspace](/concepts/agent-workspace) を参照）、時間ベースの強制実行には [cron jobs](/automation/cron-jobs) と組み合わせて動作します。 + + +常設命令は `AGENTS.md` に記載して、毎セッション必ず読み込まれるようにしてください。ワークスペースのブートストラップでは `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md` は自動注入されますが、サブディレクトリ内の任意のファイルは自動注入されません。 + + +## 常設命令の構成要素 + +```markdown +## Program: Weekly Status Report + +**Authority:** Compile data, generate report, deliver to stakeholders +**Trigger:** Every Friday at 4 PM (enforced via cron job) +**Approval gate:** None for standard reports. Flag anomalies for human review. +**Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm) + +### Execution Steps + +1. Pull metrics from configured sources +2. Compare to prior week and targets +3. Generate report in Reports/weekly/YYYY-MM-DD.md +4. Deliver summary via configured channel +5. Log completion to Agent/Logs/ + +### What NOT to Do + +- Do not send reports to external parties +- Do not modify source data +- Do not skip delivery if metrics look bad — report accurately +``` + +## 常設命令 + Cron Jobs + +常設命令は、エージェントに何をする権限があるかという**何を**定義します。[Cron jobs](/automation/cron-jobs) は、**いつ**それが起こるかを定義します。両者は次のように連携します。 + +``` +Standing Order: "You own the daily inbox triage" + ↓ +Cron Job (8 AM daily): "Execute inbox triage per standing orders" + ↓ +Agent: Reads standing orders → executes steps → reports results +``` + +cronジョブのプロンプトでは、内容を重複記載するのではなく、常設命令を参照するようにしてください。 + +```bash +openclaw cron add \ + --name daily-inbox-triage \ + --cron "0 8 * * 1-5" \ + --tz America/New_York \ + --timeout-seconds 300 \ + --announce \ + --channel bluebubbles \ + --to "+1XXXXXXXXXX" \ + --message "Execute daily inbox triage per standing orders. Check mail for new alerts. Parse, categorize, and persist each item. Report summary to owner. Escalate unknowns." +``` + +## 例 + +### 例 1: コンテンツとソーシャルメディア（週次サイクル） + +```markdown +## Program: Content & Social Media + +**Authority:** Draft content, schedule posts, compile engagement reports +**Approval gate:** All posts require owner review for first 30 days, then standing approval +**Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief) + +### Weekly Cycle + +- **Monday:** Review platform metrics and audience engagement +- **Tuesday–Thursday:** Draft social posts, create blog content +- **Friday:** Compile weekly marketing brief → deliver to owner + +### Content Rules + +- Voice must match the brand (see SOUL.md or brand voice guide) +- Never identify as AI in public-facing content +- Include metrics when available +- Focus on value to audience, not self-promotion +``` + +### 例 2: 財務オペレーション（イベントトリガー） + +```markdown +## Program: Financial Processing + +**Authority:** Process transaction data, generate reports, send summaries +**Approval gate:** None for analysis. Recommendations require owner approval. +**Trigger:** New data file detected OR scheduled monthly cycle + +### When New Data Arrives + +1. Detect new file in designated input directory +2. Parse and categorize all transactions +3. Compare against budget targets +4. Flag: unusual items, threshold breaches, new recurring charges +5. Generate report in designated output directory +6. Deliver summary to owner via configured channel + +### Escalation Rules + +- Single item > $500: immediate alert +- Category > budget by 20%: flag in report +- Unrecognizable transaction: ask owner for categorization +- Failed processing after 2 retries: report failure, do not guess +``` + +### 例 3: 監視とアラート（継続実行） + +```markdown +## Program: System Monitoring + +**Authority:** Check system health, restart services, send alerts +**Approval gate:** Restart services automatically. Escalate if restart fails twice. +**Trigger:** Every heartbeat cycle + +### Checks + +- Service health endpoints responding +- Disk space above threshold +- Pending tasks not stale (>24 hours) +- Delivery channels operational + +### Response Matrix + +| Condition | Action | Escalate? | +| ---------------- | ------------------------ | ------------------------ | +| Service down | Restart automatically | Only if restart fails 2x | +| Disk space < 10% | Alert owner | Yes | +| Stale task > 24h | Remind owner | No | +| Channel offline | Log and retry next cycle | If offline > 2 hours | +``` + +## Execute-Verify-Report パターン + +常設命令は、厳格な実行規律と組み合わせると最もうまく機能します。常設命令内のすべてのタスクは、次のループに従うべきです。 + +1. **Execute** — 実際の作業を行う（指示を確認するだけではない） +2. **Verify** — 結果が正しいことを確認する（ファイルが存在する、メッセージが送信された、データが解析された、など） +3. **Report** — 何を行い、何を検証したかをオーナーに伝える + +```markdown +### Execution Rules + +- Every task follows Execute-Verify-Report. No exceptions. +- "I'll do that" is not execution. Do it, then report. +- "Done" without verification is not acceptable. Prove it. +- If execution fails: retry once with adjusted approach. +- If still fails: report failure with diagnosis. Never silently fail. +- Never retry indefinitely — 3 attempts max, then escalate. +``` + +このパターンは、エージェントで最も一般的な失敗モード、つまりタスクを完了せずに了承だけしてしまうことを防ぎます。 + +## マルチプログラムアーキテクチャ + +複数の関心領域を管理するエージェントでは、明確な境界を持つ個別のプログラムとして常設命令を整理してください。 + +```markdown +# Standing Orders + +## Program 1: [Domain A] (Weekly) + +... + +## Program 2: [Domain B] (Monthly + On-Demand) + +... + +## Program 3: [Domain C] (As-Needed) + +... + +## Escalation Rules (All Programs) + +- [Common escalation criteria] +- [Approval gates that apply across programs] +``` + +各プログラムには次があるべきです。 + +- 独自の**トリガー頻度**（週次、月次、イベント駆動、継続実行） +- 独自の**承認ゲート**（他よりも厳しい監督が必要なプログラムもある） +- 明確な**境界**（どこで1つのプログラムが終わり、別のプログラムが始まるかをエージェントが理解できること） + +## ベストプラクティス + +### 推奨 + +- 権限は狭い範囲から始め、信頼の構築に応じて拡大する +- 高リスクの操作には明示的な承認ゲートを定義する +- 「してはいけないこと」セクションを含める — 境界は権限と同じくらい重要 +- 信頼できる時間ベース実行のために cron jobs と組み合わせる +- 常設命令が守られていることを確認するために、エージェントログを毎週見直す +- ニーズの変化に合わせて常設命令を更新する — これは生きたドキュメント + +### 避けるべきこと + +- 初日から広い権限を与える（「最善だと思うことを何でもして」） +- エスカレーションルールを省略する — すべてのプログラムに「いつ停止して尋ねるか」の条項が必要 +- エージェントが口頭の指示を覚えていると想定する — すべてファイルに書く +- 1つのプログラムに複数の関心事を混在させる — 領域ごとにプログラムを分ける +- cron jobs での強制実行を忘れる — トリガーのない常設命令は提案にすぎない + +## 関連 + +- [Automation & Tasks](/automation) — すべての自動化メカニズムの概要 +- [Cron Jobs](/automation/cron-jobs) — 常設命令のスケジュール強制実行 +- [Hooks](/automation/hooks) — エージェントのライフサイクルイベント向けイベント駆動スクリプト +- [Webhooks](/automation/cron-jobs#webhooks) — 受信HTTPイベントトリガー +- [Agent Workspace](/concepts/agent-workspace) — 常設命令の保存場所。自動注入されるブートストラップファイルの完全な一覧（AGENTS.md、SOUL.md など）を含む diff --git a/docs/ja-JP/automation/taskflow.md b/docs/ja-JP/automation/taskflow.md new file mode 100644 index 000000000..73e55c2e5 --- /dev/null +++ b/docs/ja-JP/automation/taskflow.md @@ -0,0 +1,89 @@ +--- +read_when: + - Task Flow がバックグラウンドタスクとどう関係するかを理解したい + - リリースノートやドキュメントで Task Flow または openclaw tasks flow を見かけた + - 永続的なフロー状態を調査または管理したい +summary: バックグラウンドタスクの上にある Task Flow のフローオーケストレーション層 +title: Task Flow +x-i18n: + generated_at: "2026-04-05T12:34:20Z" + model: gpt-5.4 + provider: openai + source_hash: 172871206b839845db807d9c627015890f7733b862e276853d5dbfbe29e03883 + source_path: automation/taskflow.md + workflow: 15 +--- + +# Task Flow + +Task Flow は、[バックグラウンドタスク](/automation/tasks) の上位にあるフローオーケストレーション基盤です。個々のタスクは切り離された作業の単位のままでありながら、独自の状態、リビジョン追跡、同期セマンティクスを持つ永続的な複数ステップのフローを管理します。 + +## Task Flow を使うタイミング + +作業が複数の連続したステップまたは分岐ステップにまたがり、Gateway の再起動をまたいで永続的な進捗追跡が必要な場合は、Task Flow を使用します。単一のバックグラウンド操作であれば、通常の [task](/automation/tasks) で十分です。 + +| シナリオ | 使用するもの | +| ------------------------------------- | -------------------- | +| 単一のバックグラウンドジョブ | 通常のタスク | +| 複数ステップのパイプライン（A→B→C） | Task Flow（管理型） | +| 外部で作成されたタスクを監視する | Task Flow（ミラー型） | +| 単発のリマインダー | Cron ジョブ | + +## 同期モード + +### 管理型モード + +Task Flow はライフサイクル全体をエンドツーエンドで所有します。フローステップとしてタスクを作成し、それらを完了まで進め、フロー状態を自動的に前進させます。 + +例: 毎週のレポートフローでは、(1) データを収集し、(2) レポートを生成し、(3) 配信します。Task Flow は各ステップをバックグラウンドタスクとして作成し、完了を待ってから次のステップに進みます。 + +``` +Flow: weekly-report + Step 1: gather-data → task created → succeeded + Step 2: generate-report → task created → succeeded + Step 3: deliver → task created → running +``` + +### ミラー型モード + +Task Flow は外部で作成されたタスクを監視し、タスク作成の所有権を持たずにフロー状態を同期させます。これは、タスクが Cron ジョブ、CLI コマンド、またはその他のソースから発生し、それらの進捗をフローとして統合的に把握したい場合に役立ちます。 + +例: 3 つの独立した Cron ジョブが一緒になって「morning ops」ルーチンを構成している場合です。ミラー型フローは、それらがいつどのように実行されるかを制御せずに、集合的な進捗を追跡します。 + +## 永続状態とリビジョン追跡 + +各フローは独自の状態を永続化し、進捗が Gateway の再起動をまたいでも維持されるようにリビジョンを追跡します。リビジョン追跡により、複数のソースが同じフローを同時に進めようとしたときの競合検出が可能になります。 + +## キャンセル動作 + +`openclaw tasks flow cancel` は、フローに対して持続的なキャンセル意図を設定します。フロー内のアクティブなタスクはキャンセルされ、新しいステップは開始されません。キャンセル意図は再起動をまたいで保持されるため、すべての子タスクが終了する前に Gateway が再起動しても、キャンセルされたフローはキャンセルされたままです。 + +## CLI コマンド + +```bash +# List active and recent flows +openclaw tasks flow list + +# Show details for a specific flow +openclaw tasks flow show + +# Cancel a running flow and its active tasks +openclaw tasks flow cancel +``` + +| コマンド | 説明 | +| --------------------------------- | --------------------------------------------- | +| `openclaw tasks flow list` | 追跡中のフローをステータスと同期モード付きで表示 | +| `openclaw tasks flow show ` | フロー ID または lookup key で 1 つのフローを調査 | +| `openclaw tasks flow cancel ` | 実行中のフローとそのアクティブなタスクをキャンセル | + +## フローとタスクの関係 + +フローはタスクを調整するものであり、置き換えるものではありません。1 つのフローがそのライフタイムの間に複数のバックグラウンドタスクを動かすことがあります。個々のタスクレコードを調べるには `openclaw tasks` を使用し、オーケストレーションを行うフローを調べるには `openclaw tasks flow` を使用してください。 + +## 関連 + +- [Background Tasks](/automation/tasks) — フローが調整する、切り離された作業の台帳 +- [CLI: tasks](/cli/index#tasks) — `openclaw tasks flow` の CLI コマンドリファレンス +- [Automation Overview](/automation) — すべての自動化メカニズムの概要 +- [Cron Jobs](/automation/cron-jobs) — フローへの入力元になり得るスケジュール済みジョブ diff --git a/docs/ja-JP/automation/tasks.md b/docs/ja-JP/automation/tasks.md new file mode 100644 index 000000000..2a782bb8c --- /dev/null +++ b/docs/ja-JP/automation/tasks.md @@ -0,0 +1,317 @@ +--- +read_when: + - 進行中または最近完了したバックグラウンド作業を確認するとき + - 切り離されたエージェント実行の配信失敗をデバッグするとき + - バックグラウンド実行がセッション、cron、heartbeat とどう関係するかを理解するとき +summary: ACP 実行、サブエージェント、分離された cron ジョブ、CLI 操作向けのバックグラウンドタスク追跡 +title: バックグラウンドタスク +x-i18n: + generated_at: "2026-04-05T12:34:51Z" + model: gpt-5.4 + provider: openai + source_hash: 6c95ccf4388d07e60a7bb68746b161793f4bb5ff2ba3d5ce9e51f2225dab2c4d + source_path: automation/tasks.md + workflow: 15 +--- + +# バックグラウンドタスク + +> **スケジュール設定を探していますか？** 適切な仕組みを選ぶには、[Automation & Tasks](/automation)を参照してください。このページで扱うのはバックグラウンド作業の**追跡**であり、スケジュール設定ではありません。 + +バックグラウンドタスクは、**メインの会話セッションの外側**で実行される作業を追跡します。 +ACP 実行、サブエージェントの起動、分離された cron ジョブの実行、CLI から開始された操作が対象です。 + +タスクはセッション、cron ジョブ、heartbeat を置き換えるものではありません。これは、どのような切り離された作業が、いつ発生し、成功したかどうかを記録する**アクティビティ台帳**です。 + + +すべてのエージェント実行でタスクが作成されるわけではありません。heartbeat ターンと通常の対話チャットでは作成されません。すべての cron 実行、ACP 起動、サブエージェント起動、CLI エージェントコマンドでは作成されます。 + + +## 要点 + +- タスクはスケジューラではなく**記録**です。cron と heartbeat が作業を _いつ_ 実行するかを決め、タスクは _何が起きたか_ を追跡します。 +- ACP、サブエージェント、すべての cron ジョブ、CLI 操作はタスクを作成します。heartbeat ターンでは作成されません。 +- 各タスクは `queued → running → terminal`（succeeded、failed、timed_out、cancelled、または lost）を遷移します。 +- cron タスクは、cron ランタイムがそのジョブを所有している間は有効なままです。チャットをバックエンドに持つ CLI タスクは、その所有元の実行コンテキストがまだアクティブな間だけ有効です。 +- 完了はプッシュ駆動です。切り離された作業は、完了時に直接通知するか、要求元のセッション/heartbeat を起こせるため、通常はステータスをポーリングするループは適切ではありません。 +- 分離された cron 実行とサブエージェント完了では、最終的なクリーンアップ記録処理の前に、子セッション向けに追跡中のブラウザータブ/プロセスのベストエフォートなクリーンアップが行われます。 +- 分離された cron 配信では、子孫サブエージェント作業の排出が続いている間は古い中間親返信を抑制し、配信前に最終的な子孫出力が到着した場合はそれを優先します。 +- 完了通知は、チャネルへ直接配信されるか、次の heartbeat 用にキューに入れられます。 +- `openclaw tasks list` はすべてのタスクを表示し、`openclaw tasks audit` は問題を検出します。 +- 終端状態の記録は 7 日間保持され、その後自動的に削除されます。 + +## クイックスタート + +```bash +# すべてのタスクを一覧表示（新しい順） +openclaw tasks list + +# ランタイムまたはステータスで絞り込む +openclaw tasks list --runtime acp +openclaw tasks list --status running + +# 特定のタスクの詳細を表示（ID、run ID、または session key） +openclaw tasks show + +# 実行中のタスクをキャンセル（子セッションを終了） +openclaw tasks cancel + +# タスクの通知ポリシーを変更 +openclaw tasks notify state_changes + +# ヘルス監査を実行 +openclaw tasks audit + +# メンテナンスのプレビューまたは適用 +openclaw tasks maintenance +openclaw tasks maintenance --apply + +# TaskFlow の状態を確認 +openclaw tasks flow list +openclaw tasks flow show +openclaw tasks flow cancel +``` + +## タスクを作成するもの + +| ソース | ランタイム種別 | タスクレコードが作成されるタイミング | デフォルトの通知ポリシー | +| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | +| ACP バックグラウンド実行 | `acp` | 子 ACP セッションを起動したとき | `done_only` | +| サブエージェントオーケストレーション | `subagent` | `sessions_spawn` 経由でサブエージェントを起動したとき | `done_only` | +| cron ジョブ（全種類） | `cron` | cron 実行のたびに（メインセッションと分離の両方） | `silent` | +| CLI 操作 | `cli` | Gateway 経由で実行される `openclaw agent` コマンド | `silent` | + +メインセッションの cron タスクは、デフォルトで `silent` 通知ポリシーを使います。追跡用のレコードは作成しますが、通知は生成しません。分離された cron タスクもデフォルトは `silent` ですが、独自のセッションで実行されるため、より目立ちます。 + +**タスクを作成しないもの:** + +- heartbeat ターン — メインセッション。詳細は[Heartbeat](/gateway/heartbeat)を参照 +- 通常の対話チャットターン +- 直接の `/command` 応答 + +## タスクのライフサイクル + +```mermaid +stateDiagram-v2 + [*] --> queued + queued --> running : agent starts + running --> succeeded : completes ok + running --> failed : error + running --> timed_out : timeout exceeded + running --> cancelled : operator cancels + queued --> lost : session gone > 5 min + running --> lost : session gone > 5 min +``` + +| ステータス | 意味 | +| ----------- | -------------------------------------------------------------------------- | +| `queued` | 作成済みで、エージェントの開始を待っている状態 | +| `running` | エージェントターンが現在実行中 | +| `succeeded` | 正常に完了した状態 | +| `failed` | エラーで完了した状態 | +| `timed_out` | 設定されたタイムアウトを超過した状態 | +| `cancelled` | オペレーターが `openclaw tasks cancel` で停止した状態 | +| `lost` | 5 分の猶予期間後に、ランタイムが権威あるバックエンド状態を失った状態 | + +遷移は自動で行われます。関連するエージェント実行が終了すると、タスクステータスはそれに合わせて更新されます。 + +`lost` はランタイム認識型です。 + +- ACP タスク: バックエンドの ACP 子セッションメタデータが消失した。 +- サブエージェントタスク: バックエンドの子セッションが対象エージェントストアから消失した。 +- cron タスク: cron ランタイムがそのジョブをアクティブとして追跡しなくなった。 +- CLI タスク: 分離された子セッションタスクは子セッションを使い、チャットをバックエンドに持つ CLI タスクは代わりにライブ実行コンテキストを使うため、チャネル/グループ/直接セッションの行が残っていてもそれだけでは有効状態は維持されません。 + +## 配信と通知 + +タスクが終端状態に達すると、OpenClaw が通知します。配信経路は 2 つあります。 + +**直接配信** — タスクにチャネル宛先（`requesterOrigin`）がある場合、完了メッセージはそのチャネル（Telegram、Discord、Slack など）へ直接送られます。サブエージェント完了では、利用可能な場合は紐付いたスレッド/トピックのルーティングも保持され、直接配信を諦める前に、要求元セッションに保存されたルート（`lastChannel` / `lastTo` / `lastAccountId`）から欠けている `to` / アカウントを補完できます。 + +**セッションキュー配信** — 直接配信に失敗した場合、または origin が設定されていない場合、更新は要求元セッションのシステムイベントとしてキューに入り、次の heartbeat で表示されます。 + + +タスク完了は即時の heartbeat wake を引き起こすため、結果をすぐに確認できます。次に予定された heartbeat tick を待つ必要はありません。 + + +つまり、通常のワークフローはプッシュベースです。切り離された作業を一度開始したら、完了時の wake または通知はランタイムに任せます。タスク状態をポーリングするのは、デバッグ、介入、または明示的な監査が必要な場合だけにしてください。 + +### 通知ポリシー + +各タスクについてどの程度通知を受けるかを制御します。 + +| ポリシー | 配信される内容 | +| --------------------- | ----------------------------------------------------------------------- | +| `done_only` (default) | 終端状態のみ（succeeded、failed など）— **これがデフォルトです** | +| `state_changes` | すべての状態遷移と進捗更新 | +| `silent` | 何も配信しない | + +タスクの実行中にポリシーを変更できます。 + +```bash +openclaw tasks notify state_changes +``` + +## CLI リファレンス + +### `tasks list` + +```bash +openclaw tasks list [--runtime ] [--status ] [--json] +``` + +出力列: Task ID、Kind、Status、Delivery、Run ID、Child Session、Summary。 + +### `tasks show` + +```bash +openclaw tasks show +``` + +lookup トークンには task ID、run ID、または session key を指定できます。タイミング、配信状態、エラー、終端サマリーを含む完全なレコードを表示します。 + +### `tasks cancel` + +```bash +openclaw tasks cancel +``` + +ACP タスクとサブエージェントタスクでは、これにより子セッションを終了します。ステータスは `cancelled` に遷移し、配信通知が送信されます。 + +### `tasks notify` + +```bash +openclaw tasks notify +``` + +### `tasks audit` + +```bash +openclaw tasks audit [--json] +``` + +運用上の問題を検出します。問題が検出された場合は、`openclaw status` にも表示されます。 + +| 検出項目 | 重大度 | トリガー | +| ------------------------- | -------- | ----------------------------------------------------- | +| `stale_queued` | warn | 10 分を超えて queued のまま | +| `stale_running` | error | 30 分を超えて running のまま | +| `lost` | error | ランタイムに裏付けられたタスク所有権が消失した | +| `delivery_failed` | warn | 配信に失敗し、通知ポリシーが `silent` ではない | +| `missing_cleanup` | warn | 終端タスクに cleanup timestamp がない | +| `inconsistent_timestamps` | warn | タイムライン違反（たとえば started より前に ended） | + +### `tasks maintenance` + +```bash +openclaw tasks maintenance [--json] +openclaw tasks maintenance --apply [--json] +``` + +これを使うと、タスクおよび Task Flow 状態の照合、クリーンアップ刻印、削除のプレビューまたは適用ができます。 + +照合はランタイム認識型です。 + +- ACP/サブエージェントタスクはバックエンドの子セッションを確認します。 +- cron タスクは、cron ランタイムがまだそのジョブを所有しているかを確認します。 +- チャットをバックエンドに持つ CLI タスクは、チャットセッション行だけでなく、所有元のライブ実行コンテキストを確認します。 + +完了クリーンアップもランタイム認識型です。 + +- サブエージェント完了時は、通知クリーンアップの継続前に、子セッション向けに追跡中のブラウザータブ/プロセスをベストエフォートで閉じます。 +- 分離された cron 完了時は、実行が完全に終了する前に、cron セッション向けに追跡中のブラウザータブ/プロセスをベストエフォートで閉じます。 +- 分離された cron 配信では、必要に応じて子孫サブエージェントの後続処理が完了するまで待機し、古い親確認テキストを通知せずに抑制します。 +- サブエージェント完了配信では、最新の表示可能な assistant テキストを優先します。これが空の場合は、サニタイズ済みの最新 tool/toolResult テキストにフォールバックし、タイムアウトのみの tool-call 実行は短い部分進捗サマリーにまとめられることがあります。 +- クリーンアップ失敗によって、本来のタスク結果が隠されることはありません。 + +### `tasks flow list|show|cancel` + +```bash +openclaw tasks flow list [--status ] [--json] +openclaw tasks flow show [--json] +openclaw tasks flow cancel +``` + +個々のバックグラウンドタスクレコードではなく、オーケストレーションを行う Task Flow 自体を確認したい場合に使います。 + +## チャットタスクボード（`/tasks`） + +任意のチャットセッションで `/tasks` を使うと、そのセッションにリンクされたバックグラウンドタスクを確認できます。ボードには、アクティブなタスクと最近完了したタスクが、ランタイム、ステータス、タイミング、進捗またはエラー詳細とともに表示されます。 + +現在のセッションに表示可能なリンク済みタスクがない場合、`/tasks` はエージェントローカルのタスク数にフォールバックするため、他セッションの詳細を漏らさずに概要を確認できます。 + +完全なオペレーター台帳については、CLI の `openclaw tasks list` を使ってください。 + +## ステータス統合（task pressure） + +`openclaw status` には、ひと目でわかるタスクサマリーが含まれます。 + +``` +Tasks: 3 queued · 2 running · 1 issues +``` + +サマリーが報告する内容: + +- **active** — `queued` + `running` の件数 +- **failures** — `failed` + `timed_out` + `lost` の件数 +- **byRuntime** — `acp`、`subagent`、`cron`、`cli` ごとの内訳 + +`/status` と `session_status` ツールはどちらも、クリーンアップ認識型のタスクスナップショットを使用します。アクティブなタスクが優先され、古い完了行は隠され、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは今重要なことに集中できます。 + +## ストレージとメンテナンス + +### タスクの保存場所 + +タスクレコードは、次の SQLite に永続化されます。 + +``` +$OPENCLAW_STATE_DIR/tasks/runs.sqlite +``` + +レジストリは Gateway 起動時にメモリへ読み込まれ、再起動をまたいで耐久性を保つために書き込みは SQLite に同期されます。 + +### 自動メンテナンス + +スイーパーは **60 秒**ごとに実行され、次の 3 つを処理します。 + +1. **照合** — アクティブなタスクに、まだ権威あるランタイムの裏付けがあるかを確認します。ACP/サブエージェントタスクは子セッション状態を使い、cron タスクはアクティブジョブ所有権を使い、チャットをバックエンドに持つ CLI タスクは所有元の実行コンテキストを使います。その裏付け状態が 5 分を超えて消失している場合、タスクは `lost` としてマークされます。 +2. **クリーンアップ刻印** — 終端タスクに `cleanupAfter` タイムスタンプ（endedAt + 7 日）を設定します。 +3. **削除** — `cleanupAfter` 日付を過ぎたレコードを削除します。 + +**保持期間**: 終端タスクレコードは **7 日間**保持され、その後自動的に削除されます。設定は不要です。 + +## タスクと他システムの関係 + +### タスクと Task Flow + +[Task Flow](/automation/taskflow)は、バックグラウンドタスクの上位にあるフローオーケストレーション層です。1 つのフローが、その生存期間中に managed または mirrored の sync モードを使って複数のタスクを調整することがあります。個々のタスクレコードを確認するには `openclaw tasks` を、オーケストレーションフローを確認するには `openclaw tasks flow` を使います。 + +詳細は[Task Flow](/automation/taskflow)を参照してください。 + +### タスクと cron + +cron ジョブの**定義**は `~/.openclaw/cron/jobs.json` に保存されます。**すべての** cron 実行でタスクレコードが作成されます。メインセッションと分離型の両方が対象です。メインセッションの cron タスクはデフォルトで `silent` 通知ポリシーを使うため、通知を生成せずに追跡だけを行います。 + +[cron ジョブ](/automation/cron-jobs)を参照してください。 + +### タスクと heartbeat + +heartbeat 実行はメインセッションのターンです。タスクレコードは作成されません。タスクが完了すると、すぐに結果を確認できるように heartbeat wake を引き起こすことがあります。 + +[Heartbeat](/gateway/heartbeat)を参照してください。 + +### タスクとセッション + +タスクは `childSessionKey`（作業が実行される場所）と `requesterSessionKey`（それを開始した人）を参照することがあります。セッションは会話コンテキストであり、タスクはその上にあるアクティビティ追跡です。 + +### タスクとエージェント実行 + +タスクの `runId` は、その作業を行うエージェント実行にリンクしています。エージェントのライフサイクルイベント（開始、終了、エラー）は、自動的にタスクステータスを更新します。ライフサイクルを手動で管理する必要はありません。 + +## 関連 + +- [Automation & Tasks](/automation) — すべての自動化メカニズムの概要 +- [Task Flow](/automation/taskflow) — タスクの上位にあるフローオーケストレーション +- [Scheduled Tasks](/automation/cron-jobs) — バックグラウンド作業のスケジュール設定 +- [Heartbeat](/gateway/heartbeat) — 定期的なメインセッションターン +- [CLI: Tasks](/cli/index#tasks) — CLI コマンドリファレンス diff --git a/docs/ja-JP/automation/troubleshooting.md b/docs/ja-JP/automation/troubleshooting.md new file mode 100644 index 000000000..8fccaf642 --- /dev/null +++ b/docs/ja-JP/automation/troubleshooting.md @@ -0,0 +1,15 @@ +--- +summary: /automation/cron-jobs にリダイレクト +title: 自動化のトラブルシューティング +x-i18n: + generated_at: "2026-04-05T12:34:13Z" + model: gpt-5.4 + provider: openai + source_hash: 6621342754fb56234b89e71167f73bad6c070273ff0b8d12dbb20854e32e7980 + source_path: automation/troubleshooting.md + workflow: 15 +--- + +# 自動化のトラブルシューティング + +このページは[スケジュールされたタスク](/automation/cron-jobs#troubleshooting)に移動しました。トラブルシューティングのドキュメントについては、[スケジュールされたタスク](/automation/cron-jobs#troubleshooting)を参照してください。 diff --git a/docs/ja-JP/automation/webhook.md b/docs/ja-JP/automation/webhook.md new file mode 100644 index 000000000..80cd31f84 --- /dev/null +++ b/docs/ja-JP/automation/webhook.md @@ -0,0 +1,15 @@ +--- +summary: /automation/cron-jobs にリダイレクト +title: Webhooks +x-i18n: + generated_at: "2026-04-05T12:34:14Z" + model: gpt-5.4 + provider: openai + source_hash: 7511f6bc28e7f13ee1d9313bb5551825afb5706019068079603a44668c4dda34 + source_path: automation/webhook.md + workflow: 15 +--- + +# Webhooks + +このページは [Scheduled Tasks](/automation/cron-jobs#webhooks) に移動しました。Webhook のドキュメントについては [Scheduled Tasks](/automation/cron-jobs#webhooks) を参照してください。 diff --git a/docs/ja-JP/brave-search.md b/docs/ja-JP/brave-search.md new file mode 100644 index 000000000..aca56a6b2 --- /dev/null +++ b/docs/ja-JP/brave-search.md @@ -0,0 +1,110 @@ +--- +read_when: + - web_search でBrave Searchを使いたいとき + - BRAVE_API_KEY またはプランの詳細が必要なとき +summary: web_search 向けのBrave Search APIセットアップ +title: Brave Search（レガシーパス） +x-i18n: + generated_at: "2026-04-05T12:34:32Z" + model: gpt-5.4 + provider: openai + source_hash: 7788e4cee7dc460819e55095c87df8cea29ba3a8bd3cef4c0e98ac601b45b651 + source_path: brave-search.md + workflow: 15 +--- + +# Brave Search API + +OpenClawは、`web_search`プロバイダーとしてBrave Search APIをサポートしています。 + +## APIキーを取得する + +1. [https://brave.com/search/api/](https://brave.com/search/api/)でBrave Search APIアカウントを作成します +2. ダッシュボードで**Search**プランを選択し、APIキーを生成します。 +3. キーを設定に保存するか、Gateway環境で`BRAVE_API_KEY`を設定します。 + +## 設定例 + +```json5 +{ + plugins: { + entries: { + brave: { + config: { + webSearch: { + apiKey: "BRAVE_API_KEY_HERE", + mode: "web", // or "llm-context" + }, + }, + }, + }, + }, + tools: { + web: { + search: { + provider: "brave", + maxResults: 5, + timeoutSeconds: 30, + }, + }, + }, +} +``` + +Brave固有の検索設定は、現在`plugins.entries.brave.config.webSearch.*`の下にあります。 +レガシーの`tools.web.search.apiKey`も互換性シムを通じて引き続き読み込まれますが、正規の設定パスではなくなりました。 + +`webSearch.mode`はBraveの転送方式を制御します。 + +- `web`（デフォルト）: タイトル、URL、スニペットを含む通常のBraveウェブ検索 +- `llm-context`: グラウンディング用に事前抽出されたテキストチャンクとソースを含むBrave LLM Context API + +## ツールパラメーター + +| パラメーター | 説明 | +| ------------- | ------------------------------------------------------------------- | +| `query` | 検索クエリ（必須） | +| `count` | 返す結果数（1～10、デフォルト: 5） | +| `country` | 2文字のISO国コード（例: "US"、"DE"） | +| `language` | 検索結果用のISO 639-1言語コード（例: "en"、"de"、"fr"） | +| `search_lang` | Braveの検索言語コード（例: `en`、`en-gb`、`zh-hans`） | +| `ui_lang` | UI要素用のISO言語コード | +| `freshness` | 時間フィルター: `day`（24時間）、`week`、`month`、または`year` | +| `date_after` | この日付以降に公開された結果のみ（YYYY-MM-DD） | +| `date_before` | この日付以前に公開された結果のみ（YYYY-MM-DD） | + +**例:** + +```javascript +// Country and language-specific search +await web_search({ + query: "renewable energy", + country: "DE", + language: "de", +}); + +// Recent results (past week) +await web_search({ + query: "AI news", + freshness: "week", +}); + +// Date range search +await web_search({ + query: "AI developments", + date_after: "2024-01-01", + date_before: "2024-06-30", +}); +``` + +## 注意事項 + +- OpenClawはBraveの**Search**プランを使用します。レガシーサブスクリプション（例: 月2,000クエリの旧Freeプラン）がある場合でも引き続き有効ですが、LLM Contextやより高いレート制限などの新しい機能は含まれません。 +- 各Braveプランには、更新される**月額\$5の無料クレジット**が含まれます。Searchプランの料金は1,000リクエストあたり\$5なので、このクレジットで月1,000クエリをカバーできます。予期しない課金を避けるため、Braveダッシュボードで使用量上限を設定してください。現在のプランについては、[Brave APIポータル](https://brave.com/search/api/)を参照してください。 +- Searchプランには、LLM ContextエンドポイントとAI推論権が含まれます。結果を保存してモデルの学習や調整に使うには、明示的な保存権を含むプランが必要です。Braveの[利用規約](https://api-dashboard.search.brave.com/terms-of-service)を参照してください。 +- `llm-context`モードは、通常のウェブ検索スニペット形式の代わりに、グラウンディングされたソースエントリーを返します。 +- `llm-context`モードは、`ui_lang`、`freshness`、`date_after`、`date_before`をサポートしません。 +- `ui_lang`には、`en-US`のような地域サブタグを含める必要があります。 +- 結果はデフォルトで15分間キャッシュされます（`cacheTtlMinutes`で設定可能）。 + +完全なweb_search設定については、[Web tools](/tools/web)を参照してください。 diff --git a/docs/ja-JP/channels/bluebubbles.md b/docs/ja-JP/channels/bluebubbles.md new file mode 100644 index 000000000..6bf713bcd --- /dev/null +++ b/docs/ja-JP/channels/bluebubbles.md @@ -0,0 +1,442 @@ +--- +read_when: + - BlueBubbles チャネルをセットアップするとき + - Webhook ペアリングのトラブルシューティング + - macOS で iMessage を設定するとき +summary: BlueBubbles macOS サーバー経由の iMessage（REST 送受信、入力中表示、リアクション、ペアリング、高度なアクション）。 +title: BlueBubbles +x-i18n: + generated_at: "2026-04-05T12:35:18Z" + model: gpt-5.4 + provider: openai + source_hash: ed8e59a165bdfb8fd794ee2ad6e4dacd44aa02d512312c5f2fd7d15f863380bb + source_path: channels/bluebubbles.md + workflow: 15 +--- + +# BlueBubbles (macOS REST) + +ステータス: HTTP 経由で BlueBubbles macOS サーバーと通信するバンドル済みプラグインです。従来の imsg チャネルと比べて API がより豊富でセットアップが簡単なため、**iMessage 連携にはこちらを推奨**します。 + +## バンドル済みプラグイン + +現在の OpenClaw リリースには BlueBubbles が同梱されているため、通常のパッケージ済みビルドでは +別途 `openclaw plugins install` を実行する必要はありません。 + +## 概要 + +- 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 呼び出しです。 +- 添付ファイルとステッカーは受信メディアとして取り込まれ、可能な場合はエージェントにも渡されます。 +- ペアリング / allowlist は、`channels.bluebubbles.allowFrom` + ペアリングコードを使い、他のチャネル（`/channels/pairing` など）と同じように動作します。 +- リアクションは、Slack や Telegram と同様にシステムイベントとして渡されるため、エージェントは返信前にそれらに「言及」できます。 +- 高度な機能: 編集、送信取り消し、返信スレッド、メッセージエフェクト、グループ管理。 + +## クイックスタート + +1. Mac に BlueBubbles サーバーをインストールします（[bluebubbles.app/install](https://bluebubbles.app/install) の手順に従ってください）。 +2. BlueBubbles の設定で Web API を有効にし、パスワードを設定します。 +3. `openclaw onboard` を実行して BlueBubbles を選択するか、手動で設定します。 + + ```json5 + { + channels: { + bluebubbles: { + enabled: true, + serverUrl: "http://192.168.1.100:1234", + password: "example-password", + webhookPath: "/bluebubbles-webhook", + }, + }, + } + ``` + +4. BlueBubbles の Webhook を Gateway に向けます（例: `https://your-gateway-host:3000/bluebubbles-webhook?password=`）。 +5. Gateway を起動します。Webhook ハンドラーが登録され、ペアリングが開始されます。 + +セキュリティに関する注意: + +- 必ず Webhook パスワードを設定してください。 +- Webhook 認証は常に必須です。OpenClaw は、BlueBubbles の Webhook リクエストに `channels.bluebubbles.password` と一致する password/guid が含まれていない限り（たとえば `?password=` や `x-password`）、loopback/proxy の構成に関係なく拒否します。 +- パスワード認証は、Webhook ボディ全体を読み取り / 解析する前に確認されます。 + +## Messages.app を生かしておく（VM / ヘッドレス環境） + +一部の macOS VM / 常時稼働環境では、Messages.app が「アイドル」状態になり（アプリを開く / フォアグラウンドにするまで受信イベントが止まる）、問題になることがあります。簡単な回避策として、AppleScript + LaunchAgent を使って **5 分ごとに Messages をつつく** 方法があります。 + +### 1) AppleScript を保存する + +以下の場所に保存します。 + +- `~/Scripts/poke-messages.scpt` + +スクリプト例（非対話型、フォーカスを奪わない）: + +```applescript +try + tell application "Messages" + if not running then + launch + end if + + -- Touch the scripting interface to keep the process responsive. + set _chatCount to (count of chats) + end tell +on error + -- Ignore transient failures (first-run prompts, locked session, etc). +end try +``` + +### 2) LaunchAgent をインストールする + +以下の場所に保存します。 + +- `~/Library/LaunchAgents/com.user.poke-messages.plist` + +```xml + + + + + Label + com.user.poke-messages + + ProgramArguments + + /bin/bash + -lc + /usr/bin/osascript "$HOME/Scripts/poke-messages.scpt" + + + RunAtLoad + + + StartInterval + 300 + + StandardOutPath + /tmp/poke-messages.log + StandardErrorPath + /tmp/poke-messages.err + + +``` + +注意: + +- これは **300 秒ごと** と **ログイン時** に実行されます。 +- 初回実行時に macOS の **Automation** プロンプト（`osascript` → Messages）が表示される場合があります。LaunchAgent を実行する同じユーザーセッションで承認してください。 + +読み込むには: + +```bash +launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true +launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist +``` + +## オンボーディング + +BlueBubbles は対話型オンボーディングで利用できます。 + +``` +openclaw onboard +``` + +ウィザードが尋ねる内容: + +- **Server URL**（必須）: BlueBubbles サーバーのアドレス（例: `http://192.168.1.100:1234`） +- **Password**（必須）: BlueBubbles Server 設定内の API パスワード +- **Webhook path**（任意）: デフォルトは `/bluebubbles-webhook` +- **DM policy**: pairing、allowlist、open、または disabled +- **Allow list**: 電話番号、メールアドレス、またはチャットターゲット + +CLI から BlueBubbles を追加することもできます。 + +``` +openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password +``` + +## アクセス制御（DM + グループ） + +DM: + +- デフォルト: `channels.bluebubbles.dmPolicy = "pairing"`。 +- 未知の送信者にはペアリングコードが送られ、承認されるまでメッセージは無視されます（コードの有効期限は 1 時間です）。 +- 承認方法: + - `openclaw pairing list bluebubbles` + - `openclaw pairing approve bluebubbles ` +- ペアリングはデフォルトのトークン交換です。詳細: [Pairing](/channels/pairing) + +グループ: + +- `channels.bluebubbles.groupPolicy = open | allowlist | disabled`（デフォルト: `allowlist`）。 +- `channels.bluebubbles.groupAllowFrom` は、`allowlist` 設定時にグループ内で誰がトリガーできるかを制御します。 + +### 連絡先名の補完（macOS、任意） + +BlueBubbles のグループ Webhook には、生の参加者アドレスしか含まれないことがよくあります。`GroupMembers` コンテキストにローカルの連絡先名を表示したい場合は、macOS 上でローカル Contacts による補完を有効にできます。 + +- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` で参照を有効にします。デフォルト: `false`。 +- 参照は、グループアクセス、コマンド認可、メンションゲートによってメッセージが通過可能と判断された後にのみ実行されます。 +- 補完対象は、名前のない電話番号参加者のみです。 +- ローカル一致が見つからない場合は、生の電話番号がフォールバックとして残ります。 + +```json5 +{ + channels: { + bluebubbles: { + enrichGroupParticipantsFromContacts: true, + }, + }, +} +``` + +### メンションゲート（グループ） + +BlueBubbles はグループチャットでのメンションゲートに対応しており、iMessage / WhatsApp の動作に一致します。 + +- `agents.list[].groupChat.mentionPatterns`（または `messages.groupChat.mentionPatterns`）を使ってメンションを検出します。 +- グループで `requireMention` が有効な場合、エージェントはメンションされたときだけ応答します。 +- 認可された送信者からの制御コマンドは、メンションゲートをバイパスします。 + +グループごとの設定: + +```json5 +{ + channels: { + bluebubbles: { + groupPolicy: "allowlist", + groupAllowFrom: ["+15555550123"], + groups: { + "*": { requireMention: true }, // すべてのグループのデフォルト + "iMessage;-;chat123": { requireMention: false }, // 特定グループ向けの上書き + }, + }, + }, +} +``` + +### コマンドゲート + +- 制御コマンド（例: `/config`, `/model`）には認可が必要です。 +- コマンド認可の判定には `allowFrom` と `groupAllowFrom` が使われます。 +- 認可された送信者は、グループ内でメンションしなくても制御コマンドを実行できます。 + +## ACP 会話バインディング + +BlueBubbles のチャットは、トランスポート層を変えずに永続的な ACP ワークスペースへ変換できます。 + +すばやいオペレーターフロー: + +- DM または許可されたグループチャット内で `/acp spawn codex --bind here` を実行します。 +- 以後、その同じ BlueBubbles 会話内のメッセージは、起動された ACP セッションへルーティングされます。 +- `/new` と `/reset` は、同じバインド済み ACP セッションをその場でリセットします。 +- `/acp close` は ACP セッションを閉じ、バインディングを削除します。 + +設定済みの永続バインディングは、`type: "acp"` と `match.channel: "bluebubbles"` を持つトップレベルの `bindings[]` エントリーでもサポートされます。 + +`match.peer.id` には、サポートされている任意の BlueBubbles ターゲット形式を使えます。 + +- `+15555550123` や `user@example.com` のような正規化された DM ハンドル +- `chat_id:` +- `chat_guid:` +- `chat_identifier:` + +安定したグループバインディングには、`chat_id:*` または `chat_identifier:*` を推奨します。 + +例: + +```json5 +{ + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { agent: "codex", backend: "acpx", mode: "persistent" }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "bluebubbles", + accountId: "default", + peer: { kind: "dm", id: "+15555550123" }, + }, + acp: { label: "codex-imessage" }, + }, + ], +} +``` + +共有の ACP バインディング動作については [ACP Agents](/tools/acp-agents) を参照してください。 + +## 入力中表示 + 開封通知 + +- **入力中インジケーター**: 応答生成の前および生成中に自動送信されます。 +- **開封通知**: `channels.bluebubbles.sendReadReceipts` で制御されます（デフォルト: `true`）。 +- **入力中インジケーター**: OpenClaw は入力開始イベントを送信します。BlueBubbles は送信時またはタイムアウト時に自動で入力中状態を解除します（DELETE による手動停止は不安定です）。 + +```json5 +{ + channels: { + bluebubbles: { + sendReadReceipts: false, // 開封通知を無効化 + }, + }, +} +``` + +## 高度なアクション + +BlueBubbles は、設定で有効化されている場合に高度なメッセージアクションをサポートします。 + +```json5 +{ + channels: { + bluebubbles: { + actions: { + reactions: true, // tapback（デフォルト: true） + edit: true, // 送信済みメッセージを編集（macOS 13+、macOS 26 Tahoe では壊れている） + unsend: true, // メッセージ送信取り消し（macOS 13+） + reply: true, // メッセージ GUID による返信スレッド + sendWithEffect: true, // メッセージエフェクト（slam、loud など） + renameGroup: true, // グループチャット名を変更 + setGroupIcon: true, // グループチャットのアイコン / 写真を設定（macOS 26 Tahoe では不安定） + addParticipant: true, // グループに参加者を追加 + removeParticipant: true, // グループから参加者を削除 + leaveGroup: true, // グループチャットから退出 + sendAttachment: true, // 添付ファイル / メディアを送信 + }, + }, + }, +} +``` + +利用可能なアクション: + +- **react**: Tapback リアクションを追加 / 削除（`messageId`, `emoji`, `remove`） +- **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`） +- **leaveGroup**: グループチャットから退出（`chatGuid`） +- **upload-file**: メディア / ファイルを送信（`to`, `buffer`, `filename`, `asVoice`） + - ボイスメモ: **MP3** または **CAF** 音声に `asVoice: true` を設定すると、iMessage のボイスメッセージとして送信できます。BlueBubbles はボイスメモ送信時に MP3 → CAF へ変換します。 +- 旧エイリアス: `sendAttachment` も引き続き動作しますが、正式なアクション名は `upload-file` です。 + +### メッセージ ID（短縮版と完全版） + +OpenClaw はトークン節約のために、_短縮_ メッセージ ID（例: `1`, `2`）を表示する場合があります。 + +- `MessageSid` / `ReplyToId` には短縮 ID が入ることがあります。 +- `MessageSidFull` / `ReplyToIdFull` にはプロバイダーの完全 ID が入ります。 +- 短縮 ID はメモリ内だけです。再起動やキャッシュ削除で失効することがあります。 +- アクションは短縮 / 完全のどちらの `messageId` も受け付けますが、短縮 ID は利用できなくなっているとエラーになります。 + +永続的な自動化や保存には完全 ID を使ってください。 + +- テンプレート: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` +- コンテキスト: 受信ペイロード内の `MessageSidFull` / `ReplyToIdFull` + +テンプレート変数については [Configuration](/gateway/configuration) を参照してください。 + +## ブロックストリーミング + +応答を単一メッセージとして送るか、ブロック単位でストリーミングするかを制御します。 + +```json5 +{ + channels: { + bluebubbles: { + blockStreaming: true, // ブロックストリーミングを有効化（デフォルトではオフ） + }, + }, +} +``` + +## メディア + 制限 + +- 受信添付ファイルはダウンロードされ、メディアキャッシュに保存されます。 +- 受信 / 送信メディアの上限は `channels.bluebubbles.mediaMaxMb` で制御します（デフォルト: 8 MB）。 +- 送信テキストは `channels.bluebubbles.textChunkLimit`（デフォルト: 4000 文字）で分割されます。 + +## 設定リファレンス + +完全な設定: [Configuration](/gateway/configuration) + +プロバイダーオプション: + +- `channels.bluebubbles.enabled`: チャネルの有効 / 無効。 +- `channels.bluebubbles.serverUrl`: BlueBubbles REST API ベース URL。 +- `channels.bluebubbles.password`: API パスワード。 +- `channels.bluebubbles.webhookPath`: Webhook エンドポイントパス（デフォルト: `/bluebubbles-webhook`）。 +- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled`（デフォルト: `pairing`）。 +- `channels.bluebubbles.allowFrom`: DM allowlist（ハンドル、メール、E.164 番号、`chat_id:*`、`chat_guid:*`）。 +- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled`（デフォルト: `allowlist`）。 +- `channels.bluebubbles.groupAllowFrom`: グループ送信者 allowlist。 +- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: macOS 上で、ゲート通過後に名前のないグループ参加者をローカル Contacts から任意で補完します。デフォルト: `false`。 +- `channels.bluebubbles.groups`: グループごとの設定（`requireMention` など）。 +- `channels.bluebubbles.sendReadReceipts`: 開封通知を送信します（デフォルト: `true`）。 +- `channels.bluebubbles.blockStreaming`: ブロックストリーミングを有効化します（デフォルト: `false`。ストリーミング返信に必要）。 +- `channels.bluebubbles.textChunkLimit`: 送信チャンクサイズ（文字数、デフォルト: 4000）。 +- `channels.bluebubbles.chunkMode`: `length`（デフォルト）は `textChunkLimit` 超過時のみ分割します。`newline` は長さベースの分割前に空行（段落境界）で分割します。 +- `channels.bluebubbles.mediaMaxMb`: 受信 / 送信メディア上限（MB、デフォルト: 8）。 +- `channels.bluebubbles.mediaLocalRoots`: 送信ローカルメディアパスとして許可される絶対ローカルディレクトリの明示的 allowlist。これが設定されていない場合、ローカルパス送信はデフォルトで拒否されます。アカウント単位の上書き: `channels.bluebubbles.accounts..mediaLocalRoots`。 +- `channels.bluebubbles.historyLimit`: コンテキスト用のグループメッセージ最大数（0 で無効）。 +- `channels.bluebubbles.dmHistoryLimit`: DM 履歴上限。 +- `channels.bluebubbles.actions`: 個別アクションの有効 / 無効。 +- `channels.bluebubbles.accounts`: マルチアカウント設定。 + +関連するグローバルオプション: + +- `agents.list[].groupChat.mentionPatterns`（または `messages.groupChat.mentionPatterns`）。 +- `messages.responsePrefix`. + +## アドレッシング / 配信ターゲット + +安定したルーティングには `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 を有効にしておく必要があります。 + +## セキュリティ + +- Webhook リクエストは、`guid` / `password` のクエリパラメータまたはヘッダーを `channels.bluebubbles.password` と比較して認証されます。 +- API パスワードと Webhook エンドポイントは秘密にしてください（認証情報として扱ってください）。 +- BlueBubbles の Webhook 認証には localhost バイパスはありません。Webhook トラフィックをプロキシする場合も、リクエストのエンドツーエンドで BlueBubbles パスワードを保持してください。ここでは `gateway.trustedProxies` は `channels.bluebubbles.password` の代わりになりません。[Gateway security](/gateway/security#reverse-proxy-configuration) を参照してください。 +- LAN の外に公開する場合は、BlueBubbles サーバーで HTTPS + ファイアウォールルールを有効にしてください。 + +## トラブルシューティング + +- 入力中 / 開封イベントが動かなくなった場合は、BlueBubbles の Webhook ログを確認し、Gateway パスが `channels.bluebubbles.webhookPath` と一致していることを確認してください。 +- ペアリングコードの有効期限は 1 時間です。`openclaw pairing list bluebubbles` と `openclaw pairing approve bluebubbles ` を使ってください。 +- リアクションには 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) で edit がまだ表示される場合は、`channels.bluebubbles.actions.edit=false` で手動無効化してください。 +- ステータス / ヘルス情報: `openclaw status --all` または `openclaw status --deep`。 + +一般的なチャネルワークフローの参考として、[Channels](/channels) と [Plugins](/tools/plugin) ガイドを参照してください。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャネル +- [Pairing](/channels/pairing) — DM 認証とペアリングフロー +- [Groups](/channels/groups) — グループチャットの動作とメンションゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/broadcast-groups.md b/docs/ja-JP/channels/broadcast-groups.md new file mode 100644 index 000000000..79f1ae0ea --- /dev/null +++ b/docs/ja-JP/channels/broadcast-groups.md @@ -0,0 +1,449 @@ +--- +read_when: + - ブロードキャストグループを設定している + - WhatsApp での複数エージェントの返信をデバッグしている +status: experimental +summary: WhatsApp メッセージを複数のエージェントにブロードキャストする +title: ブロードキャストグループ +x-i18n: + generated_at: "2026-04-05T12:35:06Z" + model: gpt-5.4 + provider: openai + source_hash: 1d117ae65ec3b63c2bd4b3c215d96f32d7eafa0f99a9cd7378e502c15e56ca56 + source_path: channels/broadcast-groups.md + workflow: 15 +--- + +# ブロードキャストグループ + +**ステータス:** 実験的 +**バージョン:** 2026.1.9 で追加 + +## 概要 + +ブロードキャストグループを使うと、複数のエージェントが同じメッセージを同時に処理して返信できます。これにより、1 つの電話番号だけを使って、1 つの WhatsApp グループまたは DM 内で連携する専門エージェントチームを作成できます。 + +現在の対象範囲: **WhatsApp のみ**（web チャネル）。 + +ブロードキャストグループは、チャネルの許可リストとグループ有効化ルールの後に評価されます。WhatsApp グループでは、これは OpenClaw が通常返信する場合にブロードキャストが発生することを意味します（たとえば、グループ設定に応じてメンション時など）。 + +## ユースケース + +### 1. 専門エージェントチーム + +責務が明確で集約された複数のエージェントを配置します。 + +``` +Group: "Development Team" +Agents: + - CodeReviewer (reviews code snippets) + - DocumentationBot (generates docs) + - SecurityAuditor (checks for vulnerabilities) + - TestGenerator (suggests test cases) +``` + +各エージェントは同じメッセージを処理し、それぞれの専門的な観点から応答します。 + +### 2. 多言語サポート + +``` +Group: "International Support" +Agents: + - Agent_EN (responds in English) + - Agent_DE (responds in German) + - Agent_ES (responds in Spanish) +``` + +### 3. 品質保証ワークフロー + +``` +Group: "Customer Support" +Agents: + - SupportAgent (provides answer) + - QAAgent (reviews quality, only responds if issues found) +``` + +### 4. タスク自動化 + +``` +Group: "Project Management" +Agents: + - TaskTracker (updates task database) + - TimeLogger (logs time spent) + - ReportGenerator (creates summaries) +``` + +## 設定 + +### 基本設定 + +最上位レベルに `broadcast` セクションを追加します（`bindings` と同じ階層）。キーには WhatsApp のピア ID を指定します。 + +- グループチャット: グループ JID（例: `120363403215116621@g.us`） +- DM: E.164 電話番号（例: `+15551234567`） + +```json +{ + "broadcast": { + "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"] + } +} +``` + +**結果:** OpenClaw がこのチャットで返信する場合、3 つのエージェントすべてを実行します。 + +### 処理戦略 + +エージェントがメッセージをどう処理するかを制御します。 + +#### 並列（デフォルト） + +すべてのエージェントを同時に処理します。 + +```json +{ + "broadcast": { + "strategy": "parallel", + "120363403215116621@g.us": ["alfred", "baerbel"] + } +} +``` + +#### 逐次 + +エージェントを順番に処理します（前の処理が終わるまで次は待機）。 + +```json +{ + "broadcast": { + "strategy": "sequential", + "120363403215116621@g.us": ["alfred", "baerbel"] + } +} +``` + +### 完全な例 + +```json +{ + "agents": { + "list": [ + { + "id": "code-reviewer", + "name": "Code Reviewer", + "workspace": "/path/to/code-reviewer", + "sandbox": { "mode": "all" } + }, + { + "id": "security-auditor", + "name": "Security Auditor", + "workspace": "/path/to/security-auditor", + "sandbox": { "mode": "all" } + }, + { + "id": "docs-generator", + "name": "Documentation Generator", + "workspace": "/path/to/docs-generator", + "sandbox": { "mode": "all" } + } + ] + }, + "broadcast": { + "strategy": "parallel", + "120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"], + "120363424282127706@g.us": ["support-en", "support-de"], + "+15555550123": ["assistant", "logger"] + } +} +``` + +## 仕組み + +### メッセージフロー + +1. **受信メッセージ** が WhatsApp グループに届く +2. **ブロードキャスト確認**: システムがピア ID が `broadcast` にあるか確認する +3. **ブロードキャスト一覧に含まれる場合**: + - 一覧にあるすべてのエージェントがメッセージを処理する + - 各エージェントは独自のセッションキーと分離されたコンテキストを持つ + - エージェントは並列（デフォルト）または逐次で処理される +4. **ブロードキャスト一覧に含まれない場合**: + - 通常のルーティングが適用される（最初に一致したバインディング） + +注: ブロードキャストグループは、チャネルの許可リストやグループ有効化ルール（メンション、コマンドなど）をバイパスしません。変更されるのは、メッセージが処理対象となったときに _どのエージェントを実行するか_ だけです。 + +### セッション分離 + +ブロードキャストグループ内の各エージェントは、以下を完全に分離して維持します。 + +- **セッションキー**（`agent:alfred:whatsapp:group:120363...` と `agent:baerbel:whatsapp:group:120363...` など） +- **会話履歴**（エージェントは他のエージェントのメッセージを見ない） +- **ワークスペース**（設定されていれば個別のサンドボックス） +- **ツールアクセス**（異なる allow/deny リスト） +- **メモリ/コンテキスト**（個別の IDENTITY.md、SOUL.md など） +- **グループコンテキストバッファー**（コンテキスト用に使われる最近のグループメッセージ）はピアごとに共有されるため、トリガー時にはすべてのブロードキャストエージェントが同じコンテキストを見る + +これにより、各エージェントに次のような違いを持たせられます。 + +- 異なる人格 +- 異なるツールアクセス（例: 読み取り専用と読み書き可能） +- 異なるモデル（例: opus と sonnet） +- インストールされている異なる Skills + +### 例: 分離されたセッション + +グループ `120363403215116621@g.us` にエージェント `["alfred", "baerbel"]` がある場合: + +**Alfred のコンテキスト:** + +``` +Session: agent:alfred:whatsapp:group:120363403215116621@g.us +History: [user message, alfred's previous responses] +Workspace: /Users/user/openclaw-alfred/ +Tools: read, write, exec +``` + +**Bärbel のコンテキスト:** + +``` +Session: agent:baerbel:whatsapp:group:120363403215116621@g.us +History: [user message, baerbel's previous responses] +Workspace: /Users/user/openclaw-baerbel/ +Tools: read only +``` + +## ベストプラクティス + +### 1. エージェントの責務を絞る + +各エージェントは 1 つの明確な責務で設計します。 + +```json +{ + "broadcast": { + "DEV_GROUP": ["formatter", "linter", "tester"] + } +} +``` + +✅ **良い例:** 各エージェントに 1 つの役割がある +❌ **悪い例:** 汎用的な 1 つの「dev-helper」エージェント + +### 2. 説明的な名前を使う + +各エージェントが何をするかを明確にします。 + +```json +{ + "agents": { + "security-scanner": { "name": "Security Scanner" }, + "code-formatter": { "name": "Code Formatter" }, + "test-generator": { "name": "Test Generator" } + } +} +``` + +### 3. ツールアクセスを分けて設定する + +各エージェントには必要なツールだけを与えます。 + +```json +{ + "agents": { + "reviewer": { + "tools": { "allow": ["read", "exec"] } // Read-only + }, + "fixer": { + "tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write + } + } +} +``` + +### 4. パフォーマンスを監視する + +多数のエージェントを使う場合は、次を検討してください。 + +- 速度のために `"strategy": "parallel"`（デフォルト）を使う +- 1 グループあたりのブロードキャストエージェント数を 5～10 に制限する +- 単純なエージェントにはより高速なモデルを使う + +### 5. 障害を適切に扱う + +エージェントは独立して失敗します。1 つのエージェントのエラーが他を妨げることはありません。 + +``` +Message → [Agent A ✓, Agent B ✗ error, Agent C ✓] +Result: Agent A and C respond, Agent B logs error +``` + +## 互換性 + +### プロバイダー + +ブロードキャストグループは現在、次で動作します。 + +- ✅ WhatsApp（実装済み） +- 🚧 Telegram（予定） +- 🚧 Discord（予定） +- 🚧 Slack（予定） + +### ルーティング + +ブロードキャストグループは既存のルーティングと併用できます。 + +```json +{ + "bindings": [ + { + "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } }, + "agentId": "alfred" + } + ], + "broadcast": { + "GROUP_B": ["agent1", "agent2"] + } +} +``` + +- `GROUP_A`: alfred のみが応答する（通常のルーティング） +- `GROUP_B`: agent1 と agent2 の両方が応答する（ブロードキャスト） + +**優先順位:** `broadcast` は `bindings` より優先されます。 + +## トラブルシューティング + +### エージェントが応答しない + +**確認事項:** + +1. エージェント ID が `agents.list` に存在する +2. ピア ID の形式が正しい（例: `120363403215116621@g.us`） +3. エージェントが deny リストに入っていない + +**デバッグ:** + +```bash +tail -f ~/.openclaw/logs/gateway.log | grep broadcast +``` + +### 1 つのエージェントしか応答しない + +**原因:** ピア ID が `bindings` にはあるが `broadcast` にはない可能性があります。 + +**対処:** ブロードキャスト設定に追加するか、bindings から削除してください。 + +### パフォーマンスの問題 + +**多数のエージェントで遅い場合:** + +- グループごとのエージェント数を減らす +- より軽いモデルを使う（opus ではなく sonnet） +- サンドボックスの起動時間を確認する + +## 例 + +### 例 1: コードレビューチーム + +```json +{ + "broadcast": { + "strategy": "parallel", + "120363403215116621@g.us": [ + "code-formatter", + "security-scanner", + "test-coverage", + "docs-checker" + ] + }, + "agents": { + "list": [ + { + "id": "code-formatter", + "workspace": "~/agents/formatter", + "tools": { "allow": ["read", "write"] } + }, + { + "id": "security-scanner", + "workspace": "~/agents/security", + "tools": { "allow": ["read", "exec"] } + }, + { + "id": "test-coverage", + "workspace": "~/agents/testing", + "tools": { "allow": ["read", "exec"] } + }, + { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } } + ] + } +} +``` + +**ユーザー送信:** コードスニペット +**応答:** + +- code-formatter: 「インデントを修正し、型ヒントを追加しました」 +- security-scanner: 「⚠️ 12 行目に SQL インジェクションの脆弱性があります」 +- test-coverage: 「カバレッジは 45% です。エラーケースのテストが不足しています」 +- docs-checker: 「関数 `process_data` の docstring がありません」 + +### 例 2: 多言語サポート + +```json +{ + "broadcast": { + "strategy": "sequential", + "+15555550123": ["detect-language", "translator-en", "translator-de"] + }, + "agents": { + "list": [ + { "id": "detect-language", "workspace": "~/agents/lang-detect" }, + { "id": "translator-en", "workspace": "~/agents/translate-en" }, + { "id": "translator-de", "workspace": "~/agents/translate-de" } + ] + } +} +``` + +## API リファレンス + +### 設定スキーマ + +```typescript +interface OpenClawConfig { + broadcast?: { + strategy?: "parallel" | "sequential"; + [peerId: string]: string[]; + }; +} +``` + +### フィールド + +- `strategy`（省略可）: エージェントの処理方法 + - `"parallel"`（デフォルト）: すべてのエージェントを同時に処理 + - `"sequential"`: 配列順にエージェントを処理 +- `[peerId]`: WhatsApp グループ JID、E.164 番号、またはその他のピア ID + - 値: メッセージを処理するエージェント ID の配列 + +## 制限事項 + +1. **最大エージェント数:** 厳密な上限はありませんが、10 以上のエージェントでは遅くなる場合があります +2. **共有コンテキスト:** エージェントは互いの応答を見ません（仕様です） +3. **メッセージ順序:** 並列応答はどの順番で届くか分かりません +4. **レート制限:** すべてのエージェントが WhatsApp のレート制限の対象になります + +## 今後の拡張 + +予定されている機能: + +- [ ] 共有コンテキストモード（エージェントが互いの応答を見る） +- [ ] エージェント連携（エージェント同士でシグナルを送れる） +- [ ] 動的エージェント選択（メッセージ内容に基づいてエージェントを選ぶ） +- [ ] エージェント優先順位（一部のエージェントが他より先に応答する） + +## 関連 + +- [マルチエージェント設定](/tools/multi-agent-sandbox-tools) +- [ルーティング設定](/channels/channel-routing) +- [セッション管理](/concepts/session) diff --git a/docs/ja-JP/channels/channel-routing.md b/docs/ja-JP/channels/channel-routing.md new file mode 100644 index 000000000..ee4fbefb9 --- /dev/null +++ b/docs/ja-JP/channels/channel-routing.md @@ -0,0 +1,138 @@ +--- +read_when: + - チャネルルーティングまたは受信箱の動作を変更するとき +summary: チャネルごとのルーティングルール（WhatsApp、Telegram、Discord、Slack）と共有コンテキスト +title: チャネルルーティング +x-i18n: + generated_at: "2026-04-05T12:34:48Z" + model: gpt-5.4 + provider: openai + source_hash: 63916c4dd0af5fc9bbd12581a9eb15fea14a380c5ade09323ca0c237db61e537 + source_path: channels/channel-routing.md + workflow: 15 +--- + +# チャネルとルーティング + +OpenClaw は、返信を**メッセージの送信元チャネルに戻して**ルーティングします。 +モデルがチャネルを選ぶことはありません。ルーティングは決定的であり、ホスト設定によって制御されます。 + +## 主要な用語 + +- **チャネル**: `telegram`、`whatsapp`、`discord`、`irc`、`googlechat`、`slack`、`signal`、`imessage`、`line`、および拡張チャネル。`webchat` は内部 WebChat UI チャネルであり、設定可能な送信先チャネルではありません。 +- **AccountId**: チャネルごとのアカウントインスタンス（サポートされている場合）。 +- オプションのチャネル既定アカウント: `channels..defaultAccount` は、送信先パスで `accountId` が指定されていない場合に使用するアカウントを選択します。 + - マルチアカウント構成では、2 つ以上のアカウントが設定されている場合、明示的な既定値（`defaultAccount` または `accounts.default`）を設定してください。これがない場合、フォールバックルーティングによって最初に正規化されたアカウント ID が選ばれることがあります。 +- **AgentId**: 分離されたワークスペース + セッションストア（「頭脳」）。 +- **SessionKey**: コンテキストの保存と同時実行制御に使われるバケットキー。 + +## SessionKey の形式（例） + +ダイレクトメッセージは、エージェントの**メイン**セッションに集約されます。 + +- `agent::`（既定: `agent:main:main`） + +グループとチャネルは、チャネルごとに分離されたままです。 + +- グループ: `agent:::group:` +- チャネル/ルーム: `agent:::channel:` + +スレッド: + +- Slack/Discord のスレッドでは、ベースキーの末尾に `:thread:` が追加されます。 +- Telegram のフォーラムトピックでは、グループキーに `:topic:` が埋め込まれます。 + +例: + +- `agent:main:telegram:group:-1001234567890:topic:42` +- `agent:main:discord:channel:123456:thread:987654` + +## メイン DM ルートの固定 + +`session.dmScope` が `main` の場合、ダイレクトメッセージは 1 つのメインセッションを共有することがあります。 +非オーナーの DM によってセッションの `lastRoute` が上書きされるのを防ぐため、OpenClaw は次のすべてが真である場合に `allowFrom` から固定オーナーを推論します。 + +- `allowFrom` にワイルドカードでないエントリがちょうど 1 つある。 +- そのエントリを、そのチャネルの具体的な送信者 ID に正規化できる。 +- 受信した DM の送信者が、その固定オーナーと一致しない。 + +この不一致の場合でも、OpenClaw は受信セッションメタデータを記録しますが、メインセッションの `lastRoute` の更新はスキップします。 + +## ルーティングルール（エージェントの選択方法） + +ルーティングでは、受信メッセージごとに**1 つのエージェント**が選択されます。 + +1. **完全なピア一致**（`peer.kind` + `peer.id` を持つ `bindings`）。 +2. **親ピア一致**（スレッド継承）。 +3. **Guild + ロール一致**（Discord）`guildId` + `roles` による。 +4. **Guild 一致**（Discord）`guildId` による。 +5. **Team 一致**（Slack）`teamId` による。 +6. **アカウント一致**（チャネル上の `accountId`）。 +7. **チャネル一致**（そのチャネル上の任意のアカウント、`accountId: "*"`）。 +8. **既定のエージェント**（`agents.list[].default`、それ以外は最初のリスト項目、フォールバックは `main`）。 + +バインディングに複数の一致フィールド（`peer`、`guildId`、`teamId`、`roles`）が含まれる場合、そのバインディングが適用されるには**指定されたすべてのフィールドが一致する必要があります**。 + +一致したエージェントによって、どのワークスペースとセッションストアを使うかが決まります。 + +## ブロードキャストグループ（複数のエージェントを実行） + +ブロードキャストグループを使うと、**通常 OpenClaw が返信する状況**（たとえば WhatsApp のグループで、メンション/アクティベーションのゲートを通過した後）で、同じピアに対して**複数のエージェント**を実行できます。 + +設定: + +```json5 +{ + broadcast: { + strategy: "parallel", + "120363403215116621@g.us": ["alfred", "baerbel"], + "+15555550123": ["support", "logger"], + }, +} +``` + +参照: [ブロードキャストグループ](/channels/broadcast-groups)。 + +## 設定の概要 + +- `agents.list`: 名前付きエージェント定義（ワークスペース、モデルなど）。 +- `bindings`: 受信チャネル/アカウント/ピアをエージェントに対応付けるマップ。 + +例: + +```json5 +{ + agents: { + list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }], + }, + bindings: [ + { match: { channel: "slack", teamId: "T123" }, agentId: "support" }, + { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" }, + ], +} +``` + +## セッションストレージ + +セッションストアは状態ディレクトリ（既定では `~/.openclaw`）の下にあります。 + +- `~/.openclaw/agents//sessions/sessions.json` +- JSONL トランスクリプトはストアと同じ場所に保存されます + +`session.store` と `{agentId}` テンプレートを使って、ストアパスを上書きできます。 + +Gateway と ACP のセッション検出では、既定の `agents/` ルート配下、およびテンプレート化された `session.store` ルート配下のディスクベースのエージェントストアもスキャンします。検出されるストアは、解決されたエージェントルート内にとどまり、通常の `sessions.json` ファイルを使っている必要があります。シンボリックリンクやルート外のパスは無視されます。 + +## WebChat の動作 + +WebChat は**選択されたエージェント**に接続し、既定ではそのエージェントのメインセッションを使います。 +このため、WebChat では、そのエージェントのチャネル横断コンテキストを 1 か所で確認できます。 + +## 返信コンテキスト + +受信した返信には次が含まれます。 + +- 利用可能な場合は `ReplyToId`、`ReplyToBody`、`ReplyToSender`。 +- 引用コンテキストは `[Replying to ...]` ブロックとして `Body` に追加されます。 + +これはすべてのチャネルで一貫しています。 diff --git a/docs/ja-JP/channels/discord.md b/docs/ja-JP/channels/discord.md new file mode 100644 index 000000000..b79234c96 --- /dev/null +++ b/docs/ja-JP/channels/discord.md @@ -0,0 +1,1259 @@ +--- +read_when: + - Discord channel機能に取り組んでいる場合 +summary: Discordボットのサポート状況、機能、設定 +title: Discord +x-i18n: + generated_at: "2026-04-05T12:36:43Z" + model: gpt-5.4 + provider: openai + source_hash: e757d321d80d05642cd9e24b51fb47897bacaf8db19df83bd61a49a8ce51ed3a + source_path: channels/discord.md + workflow: 15 +--- + +# Discord (Bot API) + +ステータス: 公式Discord Gateway経由のDMおよびguild channelに対応済みです。 + + + + Discord DMはデフォルトでペアリングモードになります。 + + + ネイティブコマンドの動作とコマンドカタログ。 + + + channel横断の診断と修復フロー。 + + + +## クイックセットアップ + +新しいアプリケーションとbotを作成し、そのbotをサーバーに追加して、OpenClawとペアリングする必要があります。botは自分専用のプライベートサーバーに追加することをおすすめします。まだ持っていない場合は、まず[作成してください](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（**Create My Own > For me and my friends**を選択）。 + + + + [Discord Developer Portal](https://discord.com/developers/applications)にアクセスして、**New Application**をクリックします。「OpenClaw」のような名前を付けてください。 + + サイドバーの**Bot**をクリックします。**Username**を、自分のOpenClaw agentの呼び名に設定します。 + + + + + 引き続き**Bot**ページで、下にスクロールして**Privileged Gateway Intents**に移動し、次を有効にします。 + + - **Message Content Intent**（必須） + - **Server Members Intent**（推奨。role allowlistと名前からIDへの照合に必要） + - **Presence Intent**（任意。presence更新が必要な場合のみ） + + + + + **Bot**ページの上部に戻り、**Reset Token**をクリックします。 + + + 名前に反して、これは最初のtokenを生成します。何かが「reset」されるわけではありません。 + + + tokenをコピーして、どこかに保存してください。これが**Bot Token**で、すぐ後で必要になります。 + + + + + サイドバーの**OAuth2**をクリックします。サーバーにbotを追加するために、適切な権限を持つ招待URLを生成します。 + + 下にスクロールして**OAuth2 URL Generator**で次を有効にします。 + + - `bot` + - `applications.commands` + + 下に**Bot Permissions**セクションが表示されます。次を有効にしてください。 + + - View Channels + - Send Messages + - Read Message History + - Embed Links + - Attach Files + - Add Reactions（任意） + + 下部で生成されたURLをコピーしてブラウザに貼り付け、サーバーを選択し、**Continue**をクリックして接続します。これでDiscordサーバーにbotが表示されるはずです。 + + + + + Discordアプリに戻り、内部IDをコピーできるようにDeveloper Modeを有効にする必要があります。 + + 1. **User Settings**（アバター横の歯車アイコン）→ **Advanced** → **Developer Mode**をオンにする + 2. サイドバーの**server icon**を右クリック → **Copy Server ID** + 3. 自分の**avatar**を右クリック → **Copy User ID** + + **Server ID**と**User ID**をBot Tokenと一緒に保存してください。次の手順で、この3つすべてをOpenClawに送ります。 + + + + + ペアリングを機能させるには、Discordでbotから自分へのDMを許可する必要があります。**server icon**を右クリック → **Privacy Settings** → **Direct Messages**をオンにします。 + + これにより、サーバーメンバー（botを含む）が自分にDMを送れるようになります。OpenClawでDiscord DMを使いたい場合は、これを有効のままにしてください。guild channelsだけを使う予定なら、ペアリング後にDMを無効にしてもかまいません。 + + + + + Discord bot tokenはシークレットです（パスワードのようなものです）。agentにメッセージを送る前に、OpenClawを実行しているマシンで設定してください。 + +```bash +export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" +openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run +openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN +openclaw config set channels.discord.enabled true --strict-json +openclaw gateway +``` + + OpenClawがすでにバックグラウンドサービスとして動作している場合は、OpenClaw Mac appから、または`openclaw gateway run`プロセスを停止して再起動してください。 + + + + + + + + 既存の任意のchannel（例: Telegram）でOpenClaw agentと会話し、設定を依頼してください。Discordが最初のchannelである場合は、代わりにCLI / configタブを使用してください。 + + > 「Discord bot tokenはすでにconfigに設定しました。User ID `` と Server ID `` を使ってDiscordのセットアップを完了してください。」 + + + ファイルベースのconfigを使いたい場合は、次のように設定します。 + +```json5 +{ + channels: { + discord: { + enabled: true, + token: { + source: "env", + provider: "default", + id: "DISCORD_BOT_TOKEN", + }, + }, + }, +} +``` + + デフォルトaccount用のenvフォールバック: + +```bash +DISCORD_BOT_TOKEN=... +``` + + プレーンテキストの`token`値もサポートされています。`channels.discord.token`では、env/file/exec provider全体でSecretRef値もサポートされます。詳細は[Secrets Management](/gateway/secrets)を参照してください。 + + + + + + + + Gatewayが実行中になるまで待ってから、DiscordでbotにDMしてください。botがペアリングコードを返します。 + + + + 既存のchannel上のagentにペアリングコードを送信します。 + + > 「このDiscordペアリングコードを承認してください: ``」 + + + +```bash +openclaw pairing list discord +openclaw pairing approve discord +``` + + + + + ペアリングコードの有効期限は1時間です。 + + これでDiscord上でDM経由でagentと会話できるようになります。 + + + + + +token解決はaccount対応です。config内のtoken値がenvフォールバックより優先されます。`DISCORD_BOT_TOKEN`はdefault accountでのみ使われます。 +高度な送信呼び出し（message tool/channel action）では、呼び出しごとの明示的な`token`がその呼び出しに使用されます。これはsendおよびread/probe系action（たとえばread/search/fetch/thread/pins/permissions）に適用されます。account policy/retry設定は、アクティブなruntime snapshot内で選択されたaccountから引き続き取得されます。 + + +## 推奨: guild workspaceを設定する + +DMが機能したら、Discordサーバーを完全なworkspaceとして設定できます。各channelが独自のコンテキストを持つ独立したagent sessionになります。これは、自分とbotだけのプライベートサーバーにおすすめです。 + + + + これにより、agentはDMだけでなく、サーバー上の任意のchannelで応答できるようになります。 + + + + > 「私のDiscord Server ID `` をguild allowlistに追加してください」 + + + +```json5 +{ + channels: { + discord: { + groupPolicy: "allowlist", + guilds: { + YOUR_SERVER_ID: { + requireMention: true, + users: ["YOUR_USER_ID"], + }, + }, + }, + }, +} +``` + + + + + + + + デフォルトでは、agentはguild channelsでは@mentionされたときだけ応答します。プライベートサーバーなら、おそらくすべてのメッセージに応答させたいはずです。 + + + + > 「このサーバーでは、@mentionしなくてもagentが応答できるようにしてください」 + + + guild configで`requireMention: false`を設定します。 + +```json5 +{ + channels: { + discord: { + guilds: { + YOUR_SERVER_ID: { + requireMention: false, + }, + }, + }, + }, +} +``` + + + + + + + + デフォルトでは、長期memory（`MEMORY.md`）はDM sessionでのみ読み込まれます。guild channelsでは`MEMORY.md`は自動読み込みされません。 + + + + > 「Discord channelsで質問するとき、`MEMORY.md`の長期コンテキストが必要ならmemory_searchまたはmemory_getを使ってください。」 + + + すべてのchannelで共有コンテキストが必要なら、安定した指示は`AGENTS.md`または`USER.md`に入れてください（これらはすべてのsessionに注入されます）。長期メモは`MEMORY.md`に保持し、必要に応じてmemory toolsでアクセスしてください。 + + + + + + +次に、Discordサーバーにいくつかchannelsを作成して会話を始めてください。agentはchannel名を見ることができ、各channelは独立したsessionを持ちます。そのため、`#coding`、`#home`、`#research`など、ワークフローに合ったものを設定できます。 + +## Runtime model + +- GatewayがDiscord接続を所有します。 +- 返信ルーティングは決定的です。Discordからの受信への返信はDiscordに返されます。 +- デフォルト（`session.dmScope=main`）では、ダイレクトchatはagentのメインsession（`agent:main:main`）を共有します。 +- Guild channelsは分離されたsession key（`agent::discord:channel:`）です。 +- Group DMはデフォルトで無視されます（`channels.discord.dm.groupEnabled=false`）。 +- ネイティブスラッシュコマンドは分離されたコマンドsession（`agent::discord:slash:`）で実行されつつ、ルーティング先の会話sessionには`CommandTargetSessionKey`が保持されます。 + +## Forum channels + +Discord forumおよびmedia channelsはthread投稿のみ受け付けます。OpenClawはそれらを作成する2つの方法をサポートしています。 + +- forum親（`channel:`）にメッセージを送信してthreadを自動作成します。thread titleには、メッセージ内の最初の空でない行が使われます。 +- `openclaw message thread create`を使って直接threadを作成します。forum channelsでは`--message-id`を渡さないでください。 + +例: forum親に送信してthreadを作成する + +```bash +openclaw message send --channel discord --target channel: \ + --message "Topic title\nBody of the post" +``` + +例: forum threadを明示的に作成する + +```bash +openclaw message thread create --channel discord --target channel: \ + --thread-name "Topic title" --message "Body of the post" +``` + +forum親はDiscord componentsを受け付けません。componentsが必要な場合は、thread自体（`channel:`）に送信してください。 + +## Interactive components + +OpenClawは、agentメッセージ向けにDiscord components v2コンテナをサポートしています。`components`ペイロード付きでmessage toolを使用してください。interaction結果は通常の受信メッセージとしてagentに返送され、既存のDiscord `replyToMode`設定に従います。 + +サポートされるblock: + +- `text`、`section`、`separator`、`actions`、`media-gallery`、`file` +- action rowでは最大5個のbutton、または単一のselect menuを使用可能 +- select type: `string`、`user`、`role`、`mentionable`、`channel` + +デフォルトでは、componentsは単回使用です。`components.reusable=true`を設定すると、button、select、formを有効期限が切れるまで複数回使用できます。 + +buttonをクリックできるユーザーを制限するには、そのbuttonに`allowedUsers`を設定します（Discord user ID、tag、または`*`）。設定されている場合、一致しないユーザーにはephemeralの拒否応答が返されます。 + +`/model`および`/models`スラッシュコマンドは、providerとmodelのドロップダウン、およびSubmitステップを備えたinteractive model pickerを開きます。pickerの返信はephemeralで、呼び出したユーザーのみが使用できます。 + +ファイル添付: + +- `file` blockは添付参照（`attachment://`）を指している必要があります +- 添付は`media`/`path`/`filePath`（単一ファイル）で指定します。複数ファイルには`media-gallery`を使用してください +- アップロード名を添付参照と一致させたい場合は、`filename`を使って上書きします + +Modal form: + +- 最大5フィールドの`components.modal`を追加します +- フィールドtype: `text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` +- OpenClawが自動的にトリガーbuttonを追加します + +例: + +```json5 +{ + channel: "discord", + action: "send", + to: "channel:123456789012345678", + message: "Optional fallback text", + components: { + reusable: true, + text: "Choose a path", + blocks: [ + { + type: "actions", + buttons: [ + { + label: "Approve", + style: "success", + allowedUsers: ["123456789012345678"], + }, + { label: "Decline", style: "danger" }, + ], + }, + { + type: "actions", + select: { + type: "string", + placeholder: "Pick an option", + options: [ + { label: "Option A", value: "a" }, + { label: "Option B", value: "b" }, + ], + }, + }, + ], + modal: { + title: "Details", + triggerLabel: "Open form", + fields: [ + { type: "text", label: "Requester" }, + { + type: "select", + label: "Priority", + options: [ + { label: "Low", value: "low" }, + { label: "High", value: "high" }, + ], + }, + ], + }, + }, +} +``` + +## アクセス制御とルーティング + + + + `channels.discord.dmPolicy`がDMアクセスを制御します（レガシー: `channels.discord.dm.policy`）。 + + - `pairing`（デフォルト） + - `allowlist` + - `open`（`channels.discord.allowFrom`に`"*"`を含める必要があります。レガシー: `channels.discord.dm.allowFrom`） + - `disabled` + + DMポリシーがopenでない場合、未知のユーザーはブロックされます（`pairing`モードではペアリングを促されます）。 + + マルチaccountの優先順位: + + - `channels.discord.accounts.default.allowFrom`は`default` accountにのみ適用されます。 + - 名前付きaccountsは、自身の`allowFrom`が未設定の場合、`channels.discord.allowFrom`を継承します。 + - 名前付きaccountsは`channels.discord.accounts.default.allowFrom`を継承しません。 + + 配信時のDM target形式: + + - `user:` + - `<@id>` mention + + 数字だけのIDは曖昧であり、明示的なuser/channel target種別が指定されていない限り拒否されます。 + + + + + Guild処理は`channels.discord.groupPolicy`によって制御されます。 + + - `open` + - `allowlist` + - `disabled` + + `channels.discord`が存在する場合の安全なベースラインは`allowlist`です。 + + `allowlist`の挙動: + + - guildは`channels.discord.guilds`に一致する必要があります（`id`推奨、slugも可） + - 任意の送信者allowlist: `users`（安定したID推奨）および`roles`（role IDのみ）。どちらかが設定されている場合、送信者は`users`または`roles`に一致すれば許可されます + - 直接の名前/tag照合はデフォルトで無効です。`channels.discord.dangerouslyAllowNameMatching: true`は、緊急互換モードとしてのみ有効化してください + - `users`では名前/tagもサポートされますが、IDのほうが安全です。名前/tagエントリが使われていると`openclaw security audit`が警告します + - guildに`channels`が設定されている場合、一覧にないchannelは拒否されます + - guildに`channels`ブロックがない場合、そのallowlist化されたguild内のすべてのchannelsが許可されます + + 例: + +```json5 +{ + channels: { + discord: { + groupPolicy: "allowlist", + guilds: { + "123456789012345678": { + requireMention: true, + ignoreOtherMentions: true, + users: ["987654321098765432"], + roles: ["123456789012345678"], + channels: { + general: { allow: true }, + help: { allow: true, requireMention: true }, + }, + }, + }, + }, + }, +} +``` + + `DISCORD_BOT_TOKEN`だけを設定し、`channels.discord`ブロックを作成していない場合、runtime fallbackは`groupPolicy="allowlist"`になります（ログに警告が出ます）。`channels.defaults.groupPolicy`が`open`でも同様です。 + + + + + Guildメッセージはデフォルトでmentionゲート付きです。 + + mention検出には次が含まれます。 + + - 明示的なbot mention + - 設定されたmentionパターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは`messages.groupChat.mentionPatterns`） + - サポートされるケースでの暗黙的な返信先bot動作 + + `requireMention`はguild/channelごとに設定します（`channels.discord.guilds...`）。 + `ignoreOtherMentions`は、他のuser/roleにはmentionしているがbotにはmentionしていないメッセージを任意で破棄します（@everyone/@hereは除く）。 + + Group DM: + + - デフォルト: 無視（`dm.groupEnabled=false`） + - 任意のallowlist: `dm.groupChannels`（channel IDまたはslug） + + + + +### roleベースのagentルーティング + +`bindings[].match.roles`を使うと、Discord guild memberをrole IDごとに異なるagentへルーティングできます。roleベースのbindingはrole IDのみ受け付け、peerまたはparent-peer bindingの後、guildのみのbindingの前に評価されます。bindingに他のmatchフィールド（たとえば`peer` + `guildId` + `roles`）も設定されている場合、設定されたすべてのフィールドが一致する必要があります。 + +```json5 +{ + bindings: [ + { + agentId: "opus", + match: { + channel: "discord", + guildId: "123456789012345678", + roles: ["111111111111111111"], + }, + }, + { + agentId: "sonnet", + match: { + channel: "discord", + guildId: "123456789012345678", + }, + }, + ], +} +``` + +## Developer Portalセットアップ + + + + + 1. Discord Developer Portal -> **Applications** -> **New Application** + 2. **Bot** -> **Add Bot** + 3. bot tokenをコピー + + + + + **Bot -> Privileged Gateway Intents**で、次を有効にします。 + + - Message Content Intent + - Server Members Intent（推奨） + + Presence intentは任意で、presence更新を受け取りたい場合にのみ必要です。bot presence（`setPresence`）の設定自体には、メンバーのpresence更新を有効にする必要はありません。 + + + + + OAuth URL generator: + + - scope: `bot`、`applications.commands` + + 一般的なベースライン権限: + + - View Channels + - Send Messages + - Read Message History + - Embed Links + - Attach Files + - Add Reactions（任意） + + 明示的に必要でない限り、`Administrator`は避けてください。 + + + + + Discord Developer Modeを有効にしてから、次をコピーします。 + + - server ID + - channel ID + - user ID + + OpenClaw configでは、信頼性の高いauditとprobeのために数値IDを推奨します。 + + + + +## ネイティブコマンドとコマンド認証 + +- `commands.native`のデフォルトは`"auto"`で、Discordでは有効です。 +- channelごとの上書き: `channels.discord.commands.native` +- `commands.native=false`は、以前登録されたDiscordネイティブコマンドを明示的にクリアします。 +- ネイティブコマンド認証は、通常のメッセージ処理と同じDiscord allowlist/policyを使用します。 +- 権限のないユーザーにもDiscord UI上ではコマンドが表示されることがありますが、実行時には引き続きOpenClaw認証が適用され、「not authorized」が返されます。 + +コマンドカタログと挙動については、[Slash commands](/tools/slash-commands)を参照してください。 + +デフォルトのスラッシュコマンド設定: + +- `ephemeral: true` + +## 機能の詳細 + + + + Discordはagent出力内の返信タグをサポートします。 + + - `[[reply_to_current]]` + - `[[reply_to:]]` + + 制御するのは`channels.discord.replyToMode`です。 + + - `off`（デフォルト） + - `first` + - `all` + + 注: `off`は暗黙的な返信threadingを無効にします。明示的な`[[reply_to_*]]`タグは引き続き尊重されます。 + + message IDはcontext/historyに含まれるため、agentは特定のメッセージをターゲットにできます。 + + + + + OpenClawは、一時メッセージを送信し、テキストの到着に応じて編集することで返信ドラフトをストリーミングできます。 + + - `channels.discord.streaming`がプレビューのストリーミングを制御します（`off` | `partial` | `block` | `progress`、デフォルト: `off`）。 + - Discordのプレビュー編集はすぐにレート制限に達する可能性があるため、特に複数のbotsやgatewaysが同じaccountやguildトラフィックを共有する場合、デフォルトは`off`のままです。 + - `progress`はchannel間の一貫性のために受け付けられ、Discordでは`partial`にマップされます。 + - `channels.discord.streamMode`はレガシーaliasで、自動移行されます。 + - `partial`は、token到着に合わせて単一のプレビューメッセージを編集します。 + - `block`は、ドラフトサイズのチャンクを出力します（サイズと改行位置は`draftChunk`で調整します）。 + + 例: + +```json5 +{ + channels: { + discord: { + streaming: "partial", + }, + }, +} +``` + + `block`モードのチャンク分割デフォルト（`channels.discord.textChunkLimit`でクランプされます）: + +```json5 +{ + channels: { + discord: { + streaming: "block", + draftChunk: { + minChars: 200, + maxChars: 800, + breakPreference: "paragraph", + }, + }, + }, +} +``` + + プレビューのストリーミングはテキスト専用で、メディア返信は通常の配信にフォールバックします。 + + 注: プレビューのストリーミングはblock streamingとは別です。Discordでblock streamingが明示的に + 有効になっている場合、OpenClawは二重ストリーミングを避けるためプレビューストリームをスキップします。 + + + + + Guild履歴コンテキスト: + + - `channels.discord.historyLimit` デフォルト `20` + - フォールバック: `messages.groupChat.historyLimit` + - `0`で無効化 + + DM履歴の制御: + + - `channels.discord.dmHistoryLimit` + - `channels.discord.dms[""].historyLimit` + + Threadの挙動: + + - Discord threadsはchannel sessionとしてルーティングされます + - 親threadメタデータは親sessionリンクに使用できます + - thread固有のエントリがない限り、thread configは親channel configを継承します + + channel topicは**信頼されていない**コンテキストとして注入されます（system promptとしてではありません）。 + 返信および引用メッセージのコンテキストは、現在のところ受信時のまま保持されます。 + Discord allowlistは主に、誰がagentをトリガーできるかを制御するものであり、完全な補助コンテキストの秘匿境界ではありません。 + + + + + Discordはthreadをsession targetにバインドできるため、そのthread内の後続メッセージは同じsession（subagent sessionを含む）にルーティングされ続けます。 + + コマンド: + + - `/focus ` 現在または新規threadをsubagent/session targetにバインド + - `/unfocus` 現在のthread bindingを削除 + - `/agents` アクティブな実行とbinding状態を表示 + - `/session idle ` フォーカスされたbindingの非アクティブ時自動unfocusを確認/更新 + - `/session max-age ` フォーカスされたbindingのハード最大期間を確認/更新 + + Config: + +```json5 +{ + session: { + threadBindings: { + enabled: true, + idleHours: 24, + maxAgeHours: 0, + }, + }, + channels: { + discord: { + threadBindings: { + enabled: true, + idleHours: 24, + maxAgeHours: 0, + spawnSubagentSessions: false, // opt-in + }, + }, + }, +} +``` + + 注: + + - `session.threadBindings.*`がグローバルデフォルトを設定します。 + - `channels.discord.threadBindings.*`がDiscordの挙動を上書きします。 + - `sessions_spawn({ thread: true })`でthreadを自動作成/バインドするには、`spawnSubagentSessions`をtrueにする必要があります。 + - ACP（`/acp spawn ... --thread ...`または`sessions_spawn({ runtime: "acp", thread: true })`）でthreadを自動作成/バインドするには、`spawnAcpSessions`をtrueにする必要があります。 + - accountでthread bindingが無効になっている場合、`/focus`および関連するthread binding操作は利用できません。 + + 詳細は[Sub-agents](/tools/subagents)、[ACP Agents](/tools/acp-agents)、および[Configuration Reference](/gateway/configuration-reference)を参照してください。 + + + + + 安定した「常時稼働」ACP workspaceには、Discord会話を対象とするトップレベルの型付きACP bindingを設定します。 + + Configパス: + + - `bindings[]` に `type: "acp"` と `match.channel: "discord"` + + 例: + +```json5 +{ + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { + agent: "codex", + backend: "acpx", + mode: "persistent", + cwd: "/workspace/openclaw", + }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "discord", + accountId: "default", + peer: { kind: "channel", id: "222222222222222222" }, + }, + acp: { label: "codex-main" }, + }, + ], + channels: { + discord: { + guilds: { + "111111111111111111": { + channels: { + "222222222222222222": { + requireMention: false, + }, + }, + }, + }, + }, + }, +} +``` + + 注: + + - `/acp spawn codex --bind here`は、現在のDiscord channelまたはthreadをその場でバインドし、以後のメッセージを同じACP sessionにルーティングし続けます。 + - これは「新しいCodex ACP sessionを開始する」を意味することもありますが、それ自体で新しいDiscord threadを作成するわけではありません。既存のchannelがchat surfaceのままです。 + - Codexは引き続き、ディスク上の独自の`cwd`またはbackend workspaceで実行される場合があります。そのworkspaceはruntime stateであり、Discord threadではありません。 + - threadメッセージは親channel ACP bindingを継承できます。 + - バインドされたchannelまたはthreadでは、`/new`と`/reset`は同じACP sessionをその場でリセットします。 + - 一時的なthread bindingも引き続き機能し、有効な間はtarget解決を上書きできます。 + - `spawnAcpSessions`が必要なのは、OpenClawが`--thread auto|here`経由で子threadを作成/バインドする必要がある場合だけです。現在のchannelでの`/acp spawn ... --bind here`には不要です。 + + binding動作の詳細は[ACP Agents](/tools/acp-agents)を参照してください。 + + + + + guildごとのリアクション通知モード: + + - `off` + - `own`（デフォルト） + - `all` + - `allowlist`（`guilds..users`を使用） + + リアクションイベントはsystem eventに変換され、ルーティング先のDiscord sessionに付加されます。 + + + + + `ackReaction`は、OpenClawが受信メッセージを処理している間、確認用の絵文字リアクションを送信します。 + + 解決順序: + + - `channels.discord.accounts..ackReaction` + - `channels.discord.ackReaction` + - `messages.ackReaction` + - agent identity絵文字へのフォールバック（`agents.list[].identity.emoji`、なければ`"👀"`） + + 注: + + - Discordはunicode絵文字またはカスタム絵文字名を受け付けます。 + - channelまたはaccountでリアクションを無効にするには`""`を使います。 + + + + + channel起点のconfig書き込みはデフォルトで有効です。 + + これは`/config set|unset`フローに影響します（コマンド機能が有効な場合）。 + + 無効にするには: + +```json5 +{ + channels: { + discord: { + configWrites: false, + }, + }, +} +``` + + + + + `channels.discord.proxy`を使うと、Discord GatewayのWebSocketトラフィックと、起動時REST参照（application ID + allowlist解決）をHTTP(S)プロキシ経由でルーティングできます。 + +```json5 +{ + channels: { + discord: { + proxy: "http://proxy.example:8080", + }, + }, +} +``` + + accountごとの上書き: + +```json5 +{ + channels: { + discord: { + accounts: { + primary: { + proxy: "http://proxy.example:8080", + }, + }, + }, + }, +} +``` + + + + + proxied messageをsystem member identityにマッピングするPluralKit解決を有効にするには: + +```json5 +{ + channels: { + discord: { + pluralkit: { + enabled: true, + token: "pk_live_...", // 任意。プライベートsystemに必要 + }, + }, + }, +} +``` + + 注: + + - allowlistでは`pk:`を使用できます + - member display nameは、`channels.discord.dangerouslyAllowNameMatching: true`の場合にのみ名前/slugで照合されます + - lookupは元のmessage IDを使い、時間窓制約があります + - lookupに失敗すると、proxied messageはbot messageとして扱われ、`allowBots=true`でない限り破棄されます + + + + + presence更新は、statusまたはactivityフィールドを設定したとき、またはauto presenceを有効にしたときに適用されます。 + + statusのみの例: + +```json5 +{ + channels: { + discord: { + status: "idle", + }, + }, +} +``` + + activityの例（custom statusがデフォルトのactivity typeです）: + +```json5 +{ + channels: { + discord: { + activity: "Focus time", + activityType: 4, + }, + }, +} +``` + + streamingの例: + +```json5 +{ + channels: { + discord: { + activity: "Live coding", + activityType: 1, + activityUrl: "https://twitch.tv/openclaw", + }, + }, +} +``` + + activity typeマップ: + + - 0: Playing + - 1: Streaming（`activityUrl`が必要） + - 2: Listening + - 3: Watching + - 4: Custom（activityテキストをstatus stateとして使用。絵文字は任意） + - 5: Competing + + auto presenceの例（runtime正常性シグナル）: + +```json5 +{ + channels: { + discord: { + autoPresence: { + enabled: true, + intervalMs: 30000, + minUpdateIntervalMs: 15000, + exhaustedText: "token exhausted", + }, + }, + }, +} +``` + + auto presenceはruntime可用性をDiscord statusにマッピングします: healthy => online、degradedまたはunknown => idle、exhaustedまたはunavailable => dnd。任意のテキスト上書き: + + - `autoPresence.healthyText` + - `autoPresence.degradedText` + - `autoPresence.exhaustedText`（`{reason}`プレースホルダーをサポート） + + + + + DiscordはDMでのbuttonベース承認処理をサポートし、必要に応じて元のchannelに承認プロンプトを投稿することもできます。 + + Configパス: + + - `channels.discord.execApprovals.enabled` + - `channels.discord.execApprovals.approvers`（任意。可能な場合は`commands.ownerAllowFrom`にフォールバック） + - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） + - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` + + Discordは、`enabled`が未設定または`"auto"`で、`execApprovals.approvers`または`commands.ownerAllowFrom`から少なくとも1人の承認者を解決できる場合、ネイティブexec approvalsを自動有効化します。Discordは、channel `allowFrom`、レガシー`dm.allowFrom`、またはダイレクトメッセージ`defaultTo`からexec approverを推論しません。Discordをネイティブ承認clientとして明示的に無効にするには、`enabled: false`を設定してください。 + + `target`が`channel`または`both`の場合、承認プロンプトはそのchannelに表示されます。buttonを使用できるのは解決済みの承認者のみで、その他のユーザーにはephemeralの拒否応答が返されます。承認プロンプトにはコマンドテキストが含まれるため、channel配信は信頼できるchannelsでのみ有効にしてください。session keyからchannel IDを導出できない場合、OpenClawはDM配信にフォールバックします。 + + Discordは、他のchat channelsで使われる共有承認buttonも描画します。ネイティブDiscord adapterは主に、承認者DMルーティングとchannel fanoutを追加します。 + それらのbuttonが存在する場合、それが主要な承認UXです。OpenClaw + は、tool resultがchat approvalsを利用できないと示す場合、または + 手動承認しか手段がない場合にのみ、手動の`/approve`コマンドを含めるべきです。 + + このハンドラーのGateway認証は、他のGateway clientsと同じ共有認証情報解決契約を使います。 + + - env優先のローカル認証（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`、次に`gateway.auth.*`） + - ローカルモードでは、`gateway.auth.*`が未設定の場合に限り`gateway.remote.*`をフォールバックとして使用可能。設定済みだが未解決のローカルSecretRefはfail closedします + - 該当する場合は`gateway.remote.*`経由のリモートモードサポート + - URL overrideは安全に上書きされます。CLI overrideは暗黙的な認証情報を再利用せず、env overrideはenv認証情報のみを使用します + + 承認解決の挙動: + + - `plugin:`で始まるIDは`plugin.approval.resolve`経由で解決されます。 + - それ以外のIDは`exec.approval.resolve`経由で解決されます。 + - Discordはここで追加のexec-to-pluginフォールバックを行いません。id + のprefixが、どのgateway methodを呼ぶかを決定します。 + + Exec approvalsのデフォルト有効期限は30分です。unknown approval IDで承認に失敗する場合は、承認者の解決、機能の有効化、および配信されたapproval id種別が保留中リクエストと一致していることを確認してください。 + + 関連ドキュメント: [Exec approvals](/tools/exec-approvals) + + + + +## Toolsとaction gate + +Discord message actionsには、メッセージ送信、channel管理、モデレーション、presence、メタデータactionが含まれます。 + +主な例: + +- messaging: `sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` +- reactions: `react`、`reactions`、`emojiList` +- moderation: `timeout`、`kick`、`ban` +- presence: `setPresence` + +action gateは`channels.discord.actions.*`配下にあります。 + +デフォルトのgate挙動: + +| Action group | デフォルト | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | enabled | +| roles | disabled | +| moderation | disabled | +| presence | disabled | + +## Components v2 UI + +OpenClawは、exec approvalsおよびクロスコンテキストマーカーにDiscord components v2を使用します。Discord message actionsは、カスタムUI用の`components`も受け付けます（高度な用途。discord tool経由でcomponent payloadを構築する必要があります）。一方、レガシー`embeds`も引き続き利用可能ですが、推奨されません。 + +- `channels.discord.ui.components.accentColor`は、Discord componentコンテナで使用されるアクセントカラー（16進数）を設定します。 +- accountごとの設定は`channels.discord.accounts..ui.components.accentColor`。 +- components v2が存在する場合、`embeds`は無視されます。 + +例: + +```json5 +{ + channels: { + discord: { + ui: { + components: { + accentColor: "#5865F2", + }, + }, + }, + }, +} +``` + +## Voice channels + +OpenClawはDiscord voice channelsに参加して、リアルタイムで継続的な会話を行えます。これはvoice message添付とは別機能です。 + +要件: + +- ネイティブコマンド（`commands.native`または`channels.discord.commands.native`）を有効にする +- `channels.discord.voice`を設定する +- botには対象voice channelでのConnect + Speak権限が必要 + +セッション制御にはDiscord専用ネイティブコマンド`/vc join|leave|status`を使用します。このコマンドはaccountのdefault agentを使用し、他のDiscordコマンドと同じallowlistおよびgroup policyルールに従います。 + +自動参加の例: + +```json5 +{ + channels: { + discord: { + voice: { + enabled: true, + autoJoin: [ + { + guildId: "123456789012345678", + channelId: "234567890123456789", + }, + ], + daveEncryption: true, + decryptionFailureTolerance: 24, + tts: { + provider: "openai", + openai: { voice: "alloy" }, + }, + }, + }, + }, +} +``` + +注: + +- `voice.tts`はvoice再生に限って`messages.tts`を上書きします。 +- voice transcript turnはDiscord `allowFrom`（または`dm.allowFrom`）からowner statusを導出します。ownerでない話者はowner専用tool（たとえば`gateway`や`cron`）にアクセスできません。 +- voiceはデフォルトで有効です。無効にするには`channels.discord.voice.enabled=false`を設定してください。 +- `voice.daveEncryption`と`voice.decryptionFailureTolerance`は`@discordjs/voice`のjoin optionにそのまま渡されます。 +- `@discordjs/voice`のデフォルトは、未設定時に`daveEncryption=true`および`decryptionFailureTolerance=24`です。 +- OpenClawは受信時のdecrypt failureも監視し、短時間に繰り返し失敗した場合はvoice channelから離脱・再参加して自動復旧します。 +- 受信ログに`DecryptionFailed(UnencryptedWhenPassthroughDisabled)`が繰り返し表示される場合、これは[discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)で追跡されている上流の`@discordjs/voice`受信バグの可能性があります。 + +## Voice messages + +Discordのvoice messageは波形プレビューを表示し、OGG/Opus音声とメタデータが必要です。OpenClawは波形を自動生成しますが、音声ファイルの検査と変換のためにGateway host上で`ffmpeg`と`ffprobe`が利用可能である必要があります。 + +要件と制約: + +- **ローカルファイルパス**を指定してください（URLは拒否されます）。 +- テキスト内容は省略してください（Discordは同一payloadでテキスト + voice messageを許可していません）。 +- 任意の音声形式を受け付けます。必要に応じてOpenClawがOGG/Opusに変換します。 + +例: + +```bash +message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) +``` + +## トラブルシューティング + + + + + - Message Content Intentを有効にする + - user/member解決に依存する場合はServer Members Intentを有効にする + - intent変更後はgatewayを再起動する + + + + + + - `groupPolicy`を確認する + - `channels.discord.guilds`配下のguild allowlistを確認する + - guildに`channels`マップがある場合、一覧にあるchannelsのみ許可される + - `requireMention`の挙動とmentionパターンを確認する + + 便利な確認コマンド: + +```bash +openclaw doctor +openclaw channels status --probe +openclaw logs --follow +``` + + + + + よくある原因: + + - guild/channel allowlistに一致しないまま`groupPolicy="allowlist"`になっている + - `requireMention`の設定場所が誤っている（`channels.discord.guilds`またはchannel entryの配下である必要があります） + - 送信者がguild/channel `users` allowlistでブロックされている + + + + + + 典型的なログ: + + - `Listener DiscordMessageListener timed out after 30000ms for event MESSAGE_CREATE` + - `Slow listener detected ...` + - `discord inbound worker timed out after ...` + + Listener予算のノブ: + + - 単一account: `channels.discord.eventQueue.listenerTimeout` + - マルチaccount: `channels.discord.accounts..eventQueue.listenerTimeout` + + Worker実行タイムアウトのノブ: + + - 単一account: `channels.discord.inboundWorker.runTimeoutMs` + - マルチaccount: `channels.discord.accounts..inboundWorker.runTimeoutMs` + - デフォルト: `1800000`（30分）。無効にするには`0`を設定 + + 推奨ベースライン: + +```json5 +{ + channels: { + discord: { + accounts: { + default: { + eventQueue: { + listenerTimeout: 120000, + }, + inboundWorker: { + runTimeoutMs: 1800000, + }, + }, + }, + }, + }, +} +``` + + `eventQueue.listenerTimeout`はlistenerセットアップが遅い場合に使い、`inboundWorker.runTimeoutMs` + は、キューに入ったagent turnに対する別の安全弁が必要な場合にのみ使ってください。 + + + + + `channels status --probe`の権限チェックは、数値channel IDでのみ機能します。 + + slug keyを使っている場合でもruntime照合は動作しますが、probeでは権限を完全には検証できません。 + + + + + + - DM無効: `channels.discord.dm.enabled=false` + - DMポリシー無効: `channels.discord.dmPolicy="disabled"`（レガシー: `channels.discord.dm.policy`） + - `pairing`モードでペアリング承認待ち + + + + + デフォルトでは、bot作成メッセージは無視されます。 + + `channels.discord.allowBots=true`を設定する場合は、ループ動作を避けるため、厳格なmentionおよびallowlistルールを使用してください。 + botをmentionしたbot messageのみ受け入れるには、`channels.discord.allowBots="mentions"`を推奨します。 + + + + + + - Discord voice受信の復旧ロジックが含まれるよう、OpenClawを最新に保つ（`openclaw update`） + - `channels.discord.voice.daveEncryption=true`（デフォルト）を確認する + - `channels.discord.voice.decryptionFailureTolerance=24`（上流デフォルト）から開始し、必要な場合のみ調整する + - 次のログを監視する: + - `discord voice: DAVE decrypt failures detected` + - `discord voice: repeated decrypt failures; attempting rejoin` + - 自動再参加後も失敗が続く場合は、ログを収集し、[discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)と比較してください + + + + +## 設定リファレンスへのポインタ + +主要リファレンス: + +- [Configuration reference - Discord](/gateway/configuration-reference#discord) + +シグナルの強いDiscordフィールド: + +- startup/auth: `enabled`、`token`、`accounts.*`、`allowBots` +- policy: `groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` +- command: `commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` +- event queue: `eventQueue.listenerTimeout`（listener予算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` +- inbound worker: `inboundWorker.runTimeoutMs` +- reply/history: `replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` +- delivery: `textChunkLimit`、`chunkMode`、`maxLinesPerMessage` +- streaming: `streaming`（レガシーalias: `streamMode`）、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` +- media/retry: `mediaMaxMb`、`retry` + - `mediaMaxMb`は送信するDiscordアップロードの上限を設定します（デフォルト: `8MB`） +- actions: `actions.*` +- presence: `activity`、`status`、`activityType`、`activityUrl` +- UI: `ui.components.accentColor` +- features: `threadBindings`、トップレベル`bindings[]`（`type: "acp"`）、`pluralkit`、`execApprovals`、`intents`、`agentComponents`、`heartbeat`、`responsePrefix` + +## 安全性と運用 + +- bot tokenはシークレットとして扱ってください（監視付き環境では`DISCORD_BOT_TOKEN`推奨）。 +- Discord権限は最小権限で付与してください。 +- コマンドのデプロイ/状態が古い場合は、gatewayを再起動し、`openclaw channels status --probe`で再確認してください。 + +## 関連 + +- [Pairing](/channels/pairing) +- [Groups](/channels/groups) +- [Channel routing](/channels/channel-routing) +- [Security](/gateway/security) +- [Multi-agent routing](/concepts/multi-agent) +- [Troubleshooting](/channels/troubleshooting) +- [Slash commands](/tools/slash-commands) diff --git a/docs/ja-JP/channels/feishu.md b/docs/ja-JP/channels/feishu.md new file mode 100644 index 000000000..d5a6d011d --- /dev/null +++ b/docs/ja-JP/channels/feishu.md @@ -0,0 +1,794 @@ +--- +read_when: + - Feishu/Larkボットを接続したいとき + - Feishuチャンネルを設定しているとき +summary: Feishuボットの概要、機能、設定 +title: Feishu +x-i18n: + generated_at: "2026-04-05T12:35:53Z" + model: gpt-5.4 + provider: openai + source_hash: 4e39b6dfe3a3aa4ebbdb992975e570e4f1b5e79f3b400a555fc373a0d1889952 + source_path: channels/feishu.md + workflow: 15 +--- + +# Feishuボット + +Feishu（Lark）は、企業でメッセージングやコラボレーションに使われるチームチャットプラットフォームです。このプラグインは、プラットフォームのWebSocketイベントサブスクリプションを使用してOpenClawをFeishu/Larkボットに接続し、公開Webhook URLを公開せずにメッセージを受信できるようにします。 + +--- + +## バンドル済みプラグイン + +Feishuは現在のOpenClawリリースにバンドルされているため、別途プラグインをインストールする必要はありません。 + +バンドル済みFeishuを含まない古いビルドまたはカスタムインストールを使用している場合は、手動でインストールしてください。 + +```bash +openclaw plugins install @openclaw/feishu +``` + +--- + +## クイックスタート + +Feishuチャンネルを追加する方法は2つあります。 + +### 方法1: オンボーディング（推奨） + +OpenClawをインストールしたばかりなら、オンボーディングを実行します。 + +```bash +openclaw onboard +``` + +ウィザードでは次の手順を案内します。 + +1. Feishuアプリを作成し、認証情報を収集する +2. OpenClawでアプリ認証情報を設定する +3. Gatewayを起動する + +✅ **設定後**、Gatewayステータスを確認します。 + +- `openclaw gateway status` +- `openclaw logs --follow` + +### 方法2: CLIセットアップ + +初回インストールをすでに完了している場合は、CLI経由でチャンネルを追加します。 + +```bash +openclaw channels add +``` + +**Feishu**を選択し、App IDとApp Secretを入力します。 + +✅ **設定後**、Gatewayを管理します。 + +- `openclaw gateway status` +- `openclaw gateway restart` +- `openclaw logs --follow` + +--- + +## ステップ1: Feishuアプリを作成する + +### 1. Feishu Open Platformを開く + +[Feishu Open Platform](https://open.feishu.cn/app)にアクセスしてサインインします。 + +Lark（グローバル）テナントは[https://open.larksuite.com/app](https://open.larksuite.com/app)を使用し、Feishu設定で`domain: "lark"`を設定してください。 + +### 2. アプリを作成する + +1. **Create enterprise app**をクリックします +2. アプリ名と説明を入力します +3. アプリアイコンを選択します + +![Create enterprise app](/images/feishu-step2-create-app.png) + +### 3. 認証情報をコピーする + +**Credentials & Basic Info**から、次をコピーします。 + +- **App ID**（形式: `cli_xxx`） +- **App Secret** + +❗ **重要:** App Secretは非公開にしてください。 + +![Get credentials](/images/feishu-step3-credentials.png) + +### 4. 権限を設定する + +**Permissions**で**Batch import**をクリックし、以下を貼り付けます。 + +```json +{ + "scopes": { + "tenant": [ + "aily:file:read", + "aily:file:write", + "application:application.app_message_stats.overview:readonly", + "application:application:self_manage", + "application:bot.menu:write", + "cardkit:card:read", + "cardkit:card:write", + "contact:user.employee_id:readonly", + "corehr:file:download", + "event:ip_list", + "im:chat.access_event.bot_p2p_chat:read", + "im:chat.members:bot_access", + "im:message", + "im:message.group_at_msg:readonly", + "im:message.p2p_msg:readonly", + "im:message:readonly", + "im:message:send_as_bot", + "im:resource" + ], + "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"] + } +} +``` + +![Configure permissions](/images/feishu-step4-permissions.png) + +### 5. ボット機能を有効にする + +**App Capability** > **Bot**で次を行います。 + +1. ボット機能を有効にする +2. ボット名を設定する + +![Enable bot capability](/images/feishu-step5-bot-capability.png) + +### 6. イベントサブスクリプションを設定する + +⚠️ **重要:** イベントサブスクリプションを設定する前に、以下を確認してください。 + +1. Feishuに対してすでに`openclaw channels add`を実行している +2. Gatewayが実行中である（`openclaw gateway status`） + +**Event Subscription**で次を行います。 + +1. **Use long connection to receive events**（WebSocket）を選択する +2. イベント`im.message.receive_v1`を追加する +3. （任意）Driveコメントワークフロー用に、`drive.notice.comment_add_v1`も追加する + +⚠️ Gatewayが実行されていない場合、長期接続の設定は保存に失敗する可能性があります。 + +![Configure event subscription](/images/feishu-step6-event-subscription.png) + +### 7. アプリを公開する + +1. **Version Management & Release**でバージョンを作成する +2. 審査に提出して公開する +3. 管理者の承認を待つ（通常、企業アプリは自動承認されます） + +--- + +## ステップ2: OpenClawを設定する + +### ウィザードで設定する（推奨） + +```bash +openclaw channels add +``` + +**Feishu**を選択し、App IDとApp Secretを貼り付けます。 + +### 設定ファイルで設定する + +`~/.openclaw/openclaw.json`を編集します。 + +```json5 +{ + channels: { + feishu: { + enabled: true, + dmPolicy: "pairing", + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + name: "My AI assistant", + }, + }, + }, + }, +} +``` + +`connectionMode: "webhook"`を使用する場合は、`verificationToken`と`encryptKey`の両方を設定してください。Feishu webhookサーバーはデフォルトで`127.0.0.1`にバインドされます。別のバインドアドレスが意図的に必要な場合にのみ`webhookHost`を設定してください。 + +#### Verification TokenとEncrypt Key（webhookモード） + +webhookモードを使用する場合は、設定で`channels.feishu.verificationToken`と`channels.feishu.encryptKey`の両方を設定してください。値を取得するには、次の手順を実行します。 + +1. Feishu Open Platformでアプリを開く +2. **Development** → **Events & Callbacks**（开发配置 → 事件与回调）に移動する +3. **Encryption**タブ（加密策略）を開く +4. **Verification Token**と**Encrypt Key**をコピーする + +以下のスクリーンショットは、**Verification Token**の場所を示しています。**Encrypt Key**は同じ**Encryption**セクションに表示されます。 + +![Verification Token location](/images/feishu-verification-token.png) + +### 環境変数で設定する + +```bash +export FEISHU_APP_ID="cli_xxx" +export FEISHU_APP_SECRET="xxx" +``` + +### Lark（グローバル）ドメイン + +テナントがLark（国際版）上にある場合は、ドメインを`lark`（または完全なドメイン文字列）に設定してください。`channels.feishu.domain`またはアカウントごと（`channels.feishu.accounts..domain`）に設定できます。 + +```json5 +{ + channels: { + feishu: { + domain: "lark", + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + }, + }, + }, + }, +} +``` + +### クォータ最適化フラグ + +2つの任意フラグでFeishu APIの使用量を減らせます。 + +- `typingIndicator`（デフォルト`true`）: `false`の場合、入力中リアクションの呼び出しをスキップします。 +- `resolveSenderNames`（デフォルト`true`）: `false`の場合、送信者プロファイル参照の呼び出しをスキップします。 + +トップレベルまたはアカウントごとに設定します。 + +```json5 +{ + channels: { + feishu: { + typingIndicator: false, + resolveSenderNames: false, + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + typingIndicator: true, + resolveSenderNames: false, + }, + }, + }, + }, +} +``` + +--- + +## ステップ3: 起動してテストする + +### 1. Gatewayを起動する + +```bash +openclaw gateway +``` + +### 2. テストメッセージを送信する + +Feishuでボットを見つけてメッセージを送信します。 + +### 3. ペアリングを承認する + +デフォルトでは、ボットはペアリングコードを返信します。次のように承認してください。 + +```bash +openclaw pairing approve feishu +``` + +承認後は通常どおりチャットできます。 + +--- + +## 概要 + +- **Feishuボットチャンネル**: Gatewayによって管理されるFeishuボット +- **決定論的ルーティング**: 返信は常にFeishuに戻る +- **セッション分離**: DMはメインセッションを共有し、グループは分離される +- **WebSocket接続**: Feishu SDKによる長期接続で、公開URLは不要 + +--- + +## アクセス制御 + +### ダイレクトメッセージ + +- **デフォルト**: `dmPolicy: "pairing"`（不明なユーザーにはペアリングコードを返す） +- **ペアリングを承認する**: + + ```bash + openclaw pairing list feishu + openclaw pairing approve feishu + ``` + +- **許可リストモード**: 許可されたOpen IDで`channels.feishu.allowFrom`を設定する + +### グループチャット + +**1. グループポリシー**（`channels.feishu.groupPolicy`）: + +- `"open"` = グループ内の全員を許可 +- `"allowlist"` = `groupAllowFrom`のみ許可 +- `"disabled"` = グループメッセージを無効化 + +デフォルト: `allowlist` + +**2. メンション要件**（`channels.feishu.requireMention`、`channels.feishu.groups..requireMention`で上書き可能）: + +- 明示的に`true` = @mentionが必要 +- 明示的に`false` = メンションなしで応答 +- 未設定かつ`groupPolicy: "open"`の場合 = デフォルトで`false` +- 未設定かつ`groupPolicy`が`"open"`でない場合 = デフォルトで`true` + +--- + +## グループ設定例 + +### すべてのグループを許可し、@mention不要にする（openグループのデフォルト） + +```json5 +{ + channels: { + feishu: { + groupPolicy: "open", + }, + }, +} +``` + +### すべてのグループを許可するが、引き続き@mentionを必須にする + +```json5 +{ + channels: { + feishu: { + groupPolicy: "open", + requireMention: true, + }, + }, +} +``` + +### 特定のグループのみ許可する + +```json5 +{ + channels: { + feishu: { + groupPolicy: "allowlist", + // FeishuのグループID（chat_id）は oc_xxx のようになります + groupAllowFrom: ["oc_xxx", "oc_yyy"], + }, + }, +} +``` + +### グループ内でメッセージを送れる送信者を制限する（送信者許可リスト） + +グループ自体を許可することに加えて、そのグループ内の**すべてのメッセージ**は送信者のopen_idによって制御されます。`groups..allowFrom`に列挙されたユーザーだけがメッセージを処理され、他のメンバーからのメッセージは無視されます（これは`/reset`や`/new`のような制御コマンドだけでなく、送信者レベル全体の制御です）。 + +```json5 +{ + channels: { + feishu: { + groupPolicy: "allowlist", + groupAllowFrom: ["oc_xxx"], + groups: { + oc_xxx: { + // FeishuのユーザーID（open_id）は ou_xxx のようになります + allowFrom: ["ou_user1", "ou_user2"], + }, + }, + }, + }, +} +``` + +--- + + + +## グループ/ユーザーIDを取得する + +### グループID（chat_id） + +グループIDは`oc_xxx`のようになります。 + +**方法1（推奨）** + +1. Gatewayを起動し、グループ内でボットに@mentionする +2. `openclaw logs --follow`を実行し、`chat_id`を探す + +**方法2** + +Feishu APIデバッガーを使ってグループチャットを一覧表示します。 + +### ユーザーID（open_id） + +ユーザーIDは`ou_xxx`のようになります。 + +**方法1（推奨）** + +1. Gatewayを起動し、ボットにDMする +2. `openclaw logs --follow`を実行し、`open_id`を探す + +**方法2** + +ペアリング要求でユーザーOpen IDを確認します。 + +```bash +openclaw pairing list feishu +``` + +--- + +## よく使うコマンド + +| コマンド | 説明 | +| --------- | ----------------- | +| `/status` | ボットのステータスを表示 | +| `/reset` | セッションをリセット | +| `/model` | モデルを表示/切り替え | + +> 注: Feishuはまだネイティブのコマンドメニューをサポートしていないため、コマンドはテキストとして送信する必要があります。 + +## Gateway管理コマンド + +| コマンド | 説明 | +| -------------------------- | ----------------------------- | +| `openclaw gateway status` | Gatewayステータスを表示 | +| `openclaw gateway install` | Gatewayサービスをインストール/起動 | +| `openclaw gateway stop` | Gatewayサービスを停止 | +| `openclaw gateway restart` | Gatewayサービスを再起動 | +| `openclaw logs --follow` | Gatewayログを追跡 | + +--- + +## トラブルシューティング + +### グループチャットでボットが応答しない + +1. ボットがグループに追加されていることを確認する +2. ボットに@mentionしていることを確認する（デフォルト動作） +3. `groupPolicy`が`"disabled"`に設定されていないことを確認する +4. ログを確認する: `openclaw logs --follow` + +### ボットがメッセージを受信しない + +1. アプリが公開され、承認されていることを確認する +2. イベントサブスクリプションに`im.message.receive_v1`が含まれていることを確認する +3. **long connection**が有効になっていることを確認する +4. アプリ権限が完全であることを確認する +5. Gatewayが実行中であることを確認する: `openclaw gateway status` +6. ログを確認する: `openclaw logs --follow` + +### App Secretの漏えい + +1. Feishu Open PlatformでApp Secretをリセットする +2. 設定内のApp Secretを更新する +3. Gatewayを再起動する + +### メッセージ送信失敗 + +1. アプリに`im:message:send_as_bot`権限があることを確認する +2. アプリが公開されていることを確認する +3. 詳細なエラーについてログを確認する + +--- + +## 高度な設定 + +### 複数アカウント + +```json5 +{ + channels: { + feishu: { + defaultAccount: "main", + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + name: "Primary bot", + }, + backup: { + appId: "cli_yyy", + appSecret: "yyy", + name: "Backup bot", + enabled: false, + }, + }, + }, + }, +} +``` + +`defaultAccount`は、送信APIが`accountId`を明示的に指定しない場合に、どのFeishuアカウントを使うかを制御します。 + +### メッセージ制限 + +- `textChunkLimit`: 送信テキストのチャンクサイズ（デフォルト: 2000文字） +- `mediaMaxMb`: メディアのアップロード/ダウンロード制限（デフォルト: 30MB） + +### ストリーミング + +Feishuは、インタラクティブカードによるストリーミング返信をサポートしています。有効にすると、ボットはテキスト生成中にカードを更新します。 + +```json5 +{ + channels: { + feishu: { + streaming: true, // ストリーミングカード出力を有効化（デフォルト true） + blockStreaming: true, // ブロックレベルストリーミングを有効化（デフォルト true） + }, + }, +} +``` + +`streaming: false`に設定すると、全文の返信が完成するまで待ってから送信します。 + +### ACPセッション + +Feishuは以下に対してACPをサポートしています。 + +- DM +- グループのトピック会話 + +Feishu ACPはテキストコマンド駆動です。ネイティブのスラッシュコマンドメニューはないため、会話内で直接`/acp ...`メッセージを使用してください。 + +#### 永続的なACPバインディング + +トップレベルの型付きACPバインディングを使って、FeishuのDMまたはトピック会話を永続的なACPセッションに固定します。 + +```json5 +{ + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { + agent: "codex", + backend: "acpx", + mode: "persistent", + cwd: "/workspace/openclaw", + }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "feishu", + accountId: "default", + peer: { kind: "direct", id: "ou_1234567890" }, + }, + }, + { + type: "acp", + agentId: "codex", + match: { + channel: "feishu", + accountId: "default", + peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" }, + }, + acp: { label: "codex-feishu-topic" }, + }, + ], +} +``` + +#### チャットからスレッドに紐づくACPを起動する + +FeishuのDMまたはトピック会話では、その場でACPセッションを起動してバインドできます。 + +```text +/acp spawn codex --thread here +``` + +注: + +- `--thread here`はDMとFeishuトピックで動作します。 +- バインドされたDM/トピック内の後続メッセージは、そのACPセッションへ直接ルーティングされます。 +- v1では、一般的な非トピックのグループチャットは対象にしていません。 + +### マルチエージェントルーティング + +`bindings`を使用して、FeishuのDMまたはグループを別々のエージェントへルーティングします。 + +```json5 +{ + agents: { + list: [ + { id: "main" }, + { + id: "clawd-fan", + workspace: "/home/user/clawd-fan", + agentDir: "/home/user/.openclaw/agents/clawd-fan/agent", + }, + { + id: "clawd-xi", + workspace: "/home/user/clawd-xi", + agentDir: "/home/user/.openclaw/agents/clawd-xi/agent", + }, + ], + }, + bindings: [ + { + agentId: "main", + match: { + channel: "feishu", + peer: { kind: "direct", id: "ou_xxx" }, + }, + }, + { + agentId: "clawd-fan", + match: { + channel: "feishu", + peer: { kind: "direct", id: "ou_yyy" }, + }, + }, + { + agentId: "clawd-xi", + match: { + channel: "feishu", + peer: { kind: "group", id: "oc_zzz" }, + }, + }, + ], +} +``` + +ルーティングフィールド: + +- `match.channel`: `"feishu"` +- `match.peer.kind`: `"direct"`または`"group"` +- `match.peer.id`: ユーザーOpen ID（`ou_xxx`）またはグループID（`oc_xxx`） + +参照方法については、[グループ/ユーザーIDを取得する](#get-groupuser-ids)を参照してください。 + +--- + +## 設定リファレンス + +完全な設定: [Gateway configuration](/gateway/configuration) + +主なオプション: + +| 設定 | 説明 | デフォルト | +| ------------------------------------------------- | --------------------------------------- | ---------------- | +| `channels.feishu.enabled` | チャンネルを有効化/無効化 | `true` | +| `channels.feishu.domain` | APIドメイン（`feishu`または`lark`） | `feishu` | +| `channels.feishu.connectionMode` | イベント転送モード | `websocket` | +| `channels.feishu.defaultAccount` | 送信ルーティング用のデフォルトアカウントID | `default` | +| `channels.feishu.verificationToken` | webhookモードで必須 | - | +| `channels.feishu.encryptKey` | webhookモードで必須 | - | +| `channels.feishu.webhookPath` | Webhookルートパス | `/feishu/events` | +| `channels.feishu.webhookHost` | Webhookバインドホスト | `127.0.0.1` | +| `channels.feishu.webhookPort` | Webhookバインドポート | `3000` | +| `channels.feishu.accounts..appId` | App ID | - | +| `channels.feishu.accounts..appSecret` | App Secret | - | +| `channels.feishu.accounts..domain` | アカウントごとのAPIドメイン上書き | `feishu` | +| `channels.feishu.dmPolicy` | DMポリシー | `pairing` | +| `channels.feishu.allowFrom` | DM許可リスト（open_id一覧） | - | +| `channels.feishu.groupPolicy` | グループポリシー | `allowlist` | +| `channels.feishu.groupAllowFrom` | グループ許可リスト | - | +| `channels.feishu.requireMention` | デフォルトで@mention必須 | conditional | +| `channels.feishu.groups..requireMention` | グループごとの@mention必須上書き | inherited | +| `channels.feishu.groups..enabled` | グループを有効化 | `true` | +| `channels.feishu.textChunkLimit` | メッセージチャンクサイズ | `2000` | +| `channels.feishu.mediaMaxMb` | メディアサイズ上限 | `30` | +| `channels.feishu.streaming` | ストリーミングカード出力を有効化 | `true` | +| `channels.feishu.blockStreaming` | ブロックストリーミングを有効化 | `true` | + +--- + +## dmPolicyリファレンス + +| 値 | 動作 | +| ------------- | --------------------------------------------------------------- | +| `"pairing"` | **デフォルト。** 不明なユーザーにペアリングコードを返し、承認が必要 | +| `"allowlist"` | `allowFrom`内のユーザーのみチャット可能 | +| `"open"` | すべてのユーザーを許可（`allowFrom`に`"*"`が必要） | +| `"disabled"` | DMを無効化 | + +--- + +## サポートされるメッセージタイプ + +### 受信 + +- ✅ テキスト +- ✅ リッチテキスト（post） +- ✅ 画像 +- ✅ ファイル +- ✅ 音声 +- ✅ 動画/メディア +- ✅ ステッカー + +### 送信 + +- ✅ テキスト +- ✅ 画像 +- ✅ ファイル +- ✅ 音声 +- ✅ 動画/メディア +- ✅ インタラクティブカード +- ⚠️ リッチテキスト（post形式の書式設定とカード。任意のFeishuオーサリング機能ではありません） + +### スレッドと返信 + +- ✅ インライン返信 +- ✅ Feishuが`reply_in_thread`を公開するトピックスレッド返信 +- ✅ メディア返信は、スレッド/トピックメッセージへの返信時にもスレッド認識を維持 + +## Driveコメント + +Feishuでは、誰かがFeishu Driveドキュメント（Docs、Sheetsなど）にコメントを追加したときに、エージェントを起動できます。エージェントはコメントテキスト、ドキュメントコンテキスト、コメントスレッドを受け取り、スレッド内で応答したりドキュメントを編集したりできます。 + +要件: + +- Feishuアプリのイベントサブスクリプション設定で`drive.notice.comment_add_v1`を購読する + （既存の`im.message.receive_v1`とあわせて） +- Driveツールはデフォルトで有効です。`channels.feishu.tools.drive: false`で無効化できます + +`feishu_drive`ツールは次のコメントアクションを公開します。 + +| アクション | 説明 | +| ---------------------- | ----------------------------------- | +| `list_comments` | ドキュメント上のコメントを一覧表示 | +| `list_comment_replies` | コメントスレッド内の返信を一覧表示 | +| `add_comment` | 新しいトップレベルコメントを追加 | +| `reply_comment` | 既存のコメントスレッドに返信 | + +エージェントがDriveコメントイベントを処理するとき、次を受け取ります。 + +- コメントテキストと送信者 +- ドキュメントメタデータ（タイトル、種類、URL） +- スレッド内返信のためのコメントスレッドコンテキスト + +ドキュメント編集後、エージェントにはコメント投稿者へ通知するために`feishu_drive.reply_comment`を使い、その後で重複送信を避けるために正確なサイレントトークン`NO_REPLY` / `no_reply`を出力するよう案内されます。 + +## ランタイムアクションサーフェス + +Feishuは現在、次のランタイムアクションを公開しています。 + +- `send` +- `read` +- `edit` +- `thread-reply` +- `pin` +- `list-pins` +- `unpin` +- `member-info` +- `channel-info` +- `channel-list` +- リアクションが設定で有効な場合の`react`と`reactions` +- `feishu_drive`コメントアクション: `list_comments`、`list_comment_replies`、`add_comment`、`reply_comment` + +## 関連 + +- [Channels Overview](/channels) — サポートされるすべてのチャンネル +- [Pairing](/channels/pairing) — DM認証とペアリングフロー +- [Groups](/channels/groups) — グループチャットの挙動とメンション制御 +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/googlechat.md b/docs/ja-JP/channels/googlechat.md new file mode 100644 index 000000000..e9279ec5b --- /dev/null +++ b/docs/ja-JP/channels/googlechat.md @@ -0,0 +1,277 @@ +--- +read_when: + - Google Chat チャネル機能に取り組むとき +summary: Google Chat アプリのサポート状況、機能、および設定 +title: Google Chat +x-i18n: + generated_at: "2026-04-05T12:35:13Z" + model: gpt-5.4 + provider: openai + source_hash: 570894ed798dd0b9ba42806b050927216379a1228fcd2f96de565bc8a4ac7c2c + source_path: channels/googlechat.md + workflow: 15 +--- + +# Google Chat (Chat API) + +ステータス: Google Chat API webhook 経由の DM とスペースに対応済み（HTTP のみ）。 + +## クイックセットアップ（初級者向け） + +1. Google Cloud プロジェクトを作成し、**Google Chat API** を有効にします。 + - 移動先: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) + - まだ有効になっていない場合は API を有効にします。 +2. **Service Account** を作成します。 + - **Create Credentials** > **Service Account** を押します。 + - 任意の名前を付けます（例: `openclaw-chat`）。 + - 権限は空欄のままにします（**Continue** を押します）。 + - アクセス権を持つ principal も空欄のままにします（**Done** を押します）。 +3. **JSON Key** を作成してダウンロードします。 + - Service Account の一覧で、先ほど作成したものをクリックします。 + - **Keys** タブに移動します。 + - **Add Key** > **Create new key** をクリックします。 + - **JSON** を選択して **Create** を押します。 +4. ダウンロードした JSON ファイルを gateway host に保存します（例: `~/.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** を有効にします。 + - **Functionality** で **Join spaces and group conversations** にチェックを入れます。 + - **Connection settings** で **HTTP endpoint URL** を選択します。 + - **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`）を入力します。 + - 下部の **Save** をクリックします。 +6. **アプリのステータスを有効化**します。 + - 保存後、**ページを更新**します。 + - **App status** セクションを探します（通常は保存後に上部または下部に表示されます）。 + - ステータスを **Live - available to users** に変更します。 + - もう一度 **Save** をクリックします。 +7. Service Account のパスと webhook audience を使って OpenClaw を設定します。 + - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json` + - または config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`。 +8. webhook audience のタイプと値を設定します（Chat アプリ設定と一致させます）。 +9. gateway を起動します。Google Chat が webhook パスに POST します。 + +## Google Chat に追加する + +gateway が実行中で、あなたのメールアドレスが visibility list に追加されていれば、次の手順を行います。 + +1. [Google Chat](https://chat.google.com/) にアクセスします。 +2. **Direct Messages** の横にある **+**（プラス）アイコンをクリックします。 +3. 検索バー（通常は人を追加する場所）に、Google Cloud Console で設定した **App name** を入力します。 + - **注**: この bot はプライベートアプリのため、「Marketplace」の参照一覧には _表示されません_。名前で検索する必要があります。 +4. 結果から bot を選択します。 +5. **Add** または **Chat** をクリックして 1 対 1 の会話を開始します。 +6. 「Hello」を送ってアシスタントを起動します。 + +## 公開 URL（webhook のみ） + +Google Chat webhook には公開 HTTPS エンドポイントが必要です。セキュリティのため、**`/googlechat` パスのみを**インターネットに公開してください。OpenClaw ダッシュボードやその他の機密エンドポイントはプライベートネットワーク内に維持してください。 + +### オプション A: Tailscale Funnel（推奨） + +プライベートなダッシュボードには Tailscale Serve を使い、公開 webhook パスには Funnel を使います。これにより、`/` は非公開のまま、`/googlechat` のみを公開できます。 + +1. **gateway がどのアドレスに bind されているか確認します。** + + ```bash + ss -tlnp | grep 18789 + ``` + + IP アドレス（例: `127.0.0.1`、`0.0.0.0`、または `100.x.x.x` のような Tailscale IP）を確認してください。 + +2. **ダッシュボードを tailnet のみに公開します（ポート 8443）。** + + ```bash + # localhost に bind されている場合（127.0.0.1 または 0.0.0.0）: + tailscale serve --bg --https 8443 http://127.0.0.1:18789 + + # Tailscale IP のみに bind されている場合（例: 100.106.161.80）: + tailscale serve --bg --https 8443 http://100.106.161.80:18789 + ``` + +3. **webhook パスのみを公開します。** + + ```bash + # localhost に bind されている場合（127.0.0.1 または 0.0.0.0）: + tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat + + # Tailscale IP のみに bind されている場合（例: 100.106.161.80）: + tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat + ``` + +4. **Funnel アクセス用にノードを認可します。** + 求められた場合は、出力に表示される認可 URL にアクセスして、tailnet policy でこのノードの Funnel を有効にしてください。 + +5. **設定を確認します。** + + ```bash + tailscale serve status + tailscale funnel status + ``` + +公開 webhook URL は次のようになります。 +`https://..ts.net/googlechat` + +プライベートダッシュボードは tailnet 専用のままです。 +`https://..ts.net:8443/` + +Google Chat アプリ設定では、公開 URL（`:8443` なし）を使用してください。 + +> 注: この設定は再起動後も保持されます。後で削除するには、`tailscale funnel reset` と `tailscale serve reset` を実行してください。 + +### オプション B: リバースプロキシ（Caddy） + +Caddy のようなリバースプロキシを使う場合は、特定のパスのみをプロキシしてください。 + +```caddy +your-domain.com { + reverse_proxy /googlechat* localhost:18789 +} +``` + +この設定では、`your-domain.com/` へのリクエストは無視されるか 404 を返し、`your-domain.com/googlechat` は安全に OpenClaw にルーティングされます。 + +### オプション C: Cloudflare Tunnel + +tunnel の ingress ルールで、webhook パスのみをルーティングするよう設定します。 + +- **Path**: `/googlechat` -> `http://localhost:18789/googlechat` +- **Default Rule**: HTTP 404（Not Found） + +## 仕組み + +1. Google Chat が gateway に webhook POST を送信します。各リクエストには `Authorization: Bearer ` ヘッダーが含まれます。 + - OpenClaw は、そのヘッダーが存在する場合、webhook body 全体を読み取り・解析する前に bearer 認証を検証します。 + - body 内に `authorizationEventObject.systemIdToken` を含む Google Workspace Add-on リクエストは、より厳格な事前認証 body 予算を通じてサポートされます。 +2. OpenClaw は、設定された `audienceType` + `audience` に対して token を検証します。 + - `audienceType: "app-url"` → audience は HTTPS webhook URL です。 + - `audienceType: "project-number"` → audience は Cloud project number です。 +3. メッセージはスペースごとにルーティングされます。 + - DM はセッションキー `agent::googlechat:direct:` を使います。 + - スペースはセッションキー `agent::googlechat:group:` を使います。 +4. DM アクセスはデフォルトで pairing です。未知の送信者には pairing code が送られ、次で承認します。 + - `openclaw pairing approve googlechat ` +5. グループスペースでは、デフォルトで @-mention が必要です。mention 検出にアプリの user 名が必要な場合は `botUser` を使用してください。 + +## ターゲット + +配信と allowlist には、次の識別子を使用します。 + +- ダイレクトメッセージ: `users/`（推奨）。 +- 生のメールアドレス `name@example.com` は変更可能であり、`channels.googlechat.dangerouslyAllowNameMatching: true` の場合にのみ、ダイレクト allowlist 一致に使われます。 +- 非推奨: `users/` はメール allowlist ではなく user id として扱われます。 +- スペース: `spaces/`。 + +## 主な設定 + +```json5 +{ + channels: { + googlechat: { + enabled: true, + serviceAccountFile: "/path/to/service-account.json", + // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" } + audienceType: "app-url", + audience: "https://gateway.example.com/googlechat", + webhookPath: "/googlechat", + botUser: "users/1234567890", // optional; helps mention detection + dm: { + policy: "pairing", + allowFrom: ["users/1234567890"], + }, + groupPolicy: "allowlist", + groups: { + "spaces/AAAA": { + allow: true, + requireMention: true, + users: ["users/1234567890"], + systemPrompt: "Short answers only.", + }, + }, + actions: { reactions: true }, + typingIndicator: "message", + mediaMaxMb: 20, + }, + }, +} +``` + +注: + +- Service Account 認証情報は `serviceAccount`（JSON 文字列）としてインラインで渡すこともできます。 +- `serviceAccountRef` もサポートされています（env/file SecretRef）。`channels.googlechat.accounts..serviceAccountRef` 配下のアカウント単位の ref も含みます。 +- `webhookPath` が設定されていない場合、デフォルトの webhook path は `/googlechat` です。 +- `dangerouslyAllowNameMatching` は、allowlist 用の変更可能なメール principal 一致を再有効化します（緊急時の互換モード）。 +- `actions.reactions` が有効な場合、リアクションは `reactions` tool と `channels action` から利用できます。 +- メッセージアクションでは、テキスト用の `send` と、明示的な添付送信用の `upload-file` が提供されます。`upload-file` は `media` / `filePath` / `path` と、任意の `message`、`filename`、スレッド指定を受け取ります。 +- `typingIndicator` は `none`、`message`（デフォルト）、`reaction` をサポートします（reaction には user OAuth が必要です）。 +- 添付ファイルは Chat API 経由でダウンロードされ、media pipeline に保存されます（サイズ上限は `mediaMaxMb`）。 + +シークレット参照の詳細: [Secrets Management](/gateway/secrets)。 + +## トラブルシューティング + +### 405 Method Not Allowed + +Google Cloud Logs Explorer に次のようなエラーが表示される場合: + +``` +status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed +``` + +これは webhook handler が登録されていないことを意味します。一般的な原因は次のとおりです。 + +1. **チャネルが設定されていない**: config に `channels.googlechat` セクションがありません。次で確認します。 + + ```bash + openclaw config get channels.googlechat + ``` + + これが「Config path not found」を返す場合は、設定を追加してください（[主な設定](#主な設定) を参照）。 + +2. **プラグインが有効になっていない**: plugin の状態を確認します。 + + ```bash + openclaw plugins list | grep googlechat + ``` + + 「disabled」と表示される場合は、config に `plugins.entries.googlechat.enabled: true` を追加してください。 + +3. **gateway が再起動されていない**: config を追加した後、gateway を再起動します。 + + ```bash + openclaw gateway restart + ``` + +チャネルが実行中であることを確認します。 + +```bash +openclaw channels status +# Should show: Google Chat default: enabled, configured, ... +``` + +### その他の問題 + +- 認証エラーや audience 設定不足については `openclaw channels status --probe` を確認してください。 +- メッセージが届かない場合は、Chat アプリの webhook URL とイベント購読を確認してください。 +- mention ゲートによって返信がブロックされる場合は、`botUser` をアプリの user resource name に設定し、`requireMention` を確認してください。 +- テストメッセージ送信中に `openclaw logs --follow` を使うと、リクエストが gateway に到達しているか確認できます。 + +関連ドキュメント: + +- [Gateway configuration](/gateway/configuration) +- [Security](/gateway/security) +- [Reactions](/tools/reactions) + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャネル +- [Pairing](/channels/pairing) — DM 認証と pairing フロー +- [Groups](/channels/groups) — グループチャットの動作と mention ゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/group-messages.md b/docs/ja-JP/channels/group-messages.md new file mode 100644 index 000000000..deaa045af --- /dev/null +++ b/docs/ja-JP/channels/group-messages.md @@ -0,0 +1,91 @@ +--- +read_when: + - グループメッセージのルールやメンションを変更するとき +summary: WhatsApp グループメッセージ処理の動作と設定（mentionPatterns は各サーフェスで共有されます） +title: グループメッセージ +x-i18n: + generated_at: "2026-04-05T12:35:09Z" + model: gpt-5.4 + provider: openai + source_hash: 2543be5bc4c6f188f955df580a6fef585ecbfc1be36ade5d34b1a9157e021bc5 + source_path: channels/group-messages.md + workflow: 15 +--- + +# グループメッセージ（WhatsApp web チャネル） + +目的: Clawd を WhatsApp グループに参加させ、ping されたときだけ反応させ、そのスレッドを個人 DM セッションとは分離したままにすることです。 + +注: `agents.list[].groupChat.mentionPatterns` は現在 Telegram/Discord/Slack/iMessage でも使われています。このドキュメントは WhatsApp 固有の動作に焦点を当てています。マルチエージェント構成では、エージェントごとに `agents.list[].groupChat.mentionPatterns` を設定してください（またはグローバルなフォールバックとして `messages.groupChat.mentionPatterns` を使ってください）。 + +## 現在の実装（2025-12-03） + +- アクティベーションモード: `mention`（既定）または `always`。`mention` では ping が必要です（`mentionedJids` による実際の WhatsApp の @メンション、安全な正規表現パターン、またはテキスト中の任意位置にあるボットの E.164）。`always` ではすべてのメッセージでエージェントが起動しますが、意味のある価値を提供できる場合にのみ返信し、それ以外の場合は正確に無言トークン `NO_REPLY` / `no_reply` を返す必要があります。既定値は設定の `channels.whatsapp.groups` で設定でき、グループごとに `/activation` で上書きできます。`channels.whatsapp.groups` が設定されている場合、これはグループの許可リストとしても機能します（すべて許可するには `"*"` を含めます）。 +- グループポリシー: `channels.whatsapp.groupPolicy` は、グループメッセージを受け付けるかどうかを制御します（`open|disabled|allowlist`）。`allowlist` では `channels.whatsapp.groupAllowFrom` を使います（フォールバック: 明示的な `channels.whatsapp.allowFrom`）。既定は `allowlist` です（送信者を追加するまでブロックされます）。 +- グループ単位のセッション: セッションキーは `agent::whatsapp:group:` のようになるため、`/verbose on` や `/think high` のようなコマンド（単独メッセージとして送信）はそのグループに限定されます。個人 DM の状態には影響しません。heartbeat はグループスレッドではスキップされます。 +- コンテキスト注入: 実行をトリガーしなかった**保留中のみ**のグループメッセージ（既定 50 件）は、`[Chat messages since your last reply - for context]` の下にプレフィックスとして追加され、トリガーとなった行は `[Current message - respond to this]` の下に追加されます。すでにセッション内にあるメッセージは再注入されません。 +- 送信者表示: すべてのグループバッチの末尾に `[from: Sender Name (+E164)]` が追加されるため、Pi は誰が話しているかを把握できます。 +- 一時表示/view-once: テキストやメンションを抽出する前にこれらをアンラップするため、その中の ping でもトリガーされます。 +- グループシステムプロンプト: グループセッションの最初のターン時（および `/activation` でモードが変更されるたび）に、`You are replying inside the WhatsApp group "". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` のような短い説明をシステムプロンプトに注入します。メタデータが利用できない場合でも、グループチャットであることはエージェントに伝えます。 + +## 設定例（WhatsApp） + +WhatsApp が本文テキスト内の視覚的な `@` を取り除く場合でも表示名による ping が機能するように、`~/.openclaw/openclaw.json` に `groupChat` ブロックを追加します。 + +```json5 +{ + channels: { + whatsapp: { + groups: { + "*": { requireMention: true }, + }, + }, + }, + agents: { + list: [ + { + id: "main", + groupChat: { + historyLimit: 50, + mentionPatterns: ["@?openclaw", "\\+?15555550123"], + }, + }, + ], + }, +} +``` + +注意: + +- これらの正規表現は大文字小文字を区別せず、ほかの設定用正規表現サーフェスと同じ safe-regex ガードレールを使います。無効なパターンや安全でないネストした繰り返しは無視されます。 +- WhatsApp は、連絡先をタップしたときには引き続き `mentionedJids` 経由で正規のメンションを送信するため、番号によるフォールバックが必要になることはまれですが、有用な安全策です。 + +### アクティベーションコマンド（オーナーのみ） + +グループチャットコマンドを使います。 + +- `/activation mention` +- `/activation always` + +これを変更できるのは、オーナーの番号（`channels.whatsapp.allowFrom` から取得し、未設定の場合はボット自身の E.164）だけです。現在のアクティベーションモードを確認するには、グループで `/status` を単独メッセージとして送信してください。 + +## 使い方 + +1. OpenClaw を実行している WhatsApp アカウントをグループに追加します。 +2. `@openclaw …` と送信します（または番号を含めます）。`groupPolicy: "open"` を設定していない限り、許可リストにある送信者だけがこれをトリガーできます。 +3. エージェントプロンプトには、最近のグループコンテキストと末尾の `[from: …]` マーカーが含まれるため、適切な相手に応答できます。 +4. セッションレベルのディレクティブ（`/verbose on`、`/think high`、`/new` または `/reset`、`/compact`）は、そのグループのセッションにのみ適用されます。認識されるよう、単独メッセージとして送信してください。個人 DM セッションは独立したままです。 + +## テスト / 検証 + +- 手動スモークテスト: + - グループで `@openclaw` の ping を送信し、送信者名に言及した返信があることを確認します。 + - 2 回目の ping を送信し、履歴ブロックが含まれ、その次のターンでクリアされることを確認します。 +- Gateway ログ（`--verbose` 付きで実行）を確認し、`from: ` を示す `inbound web message` エントリと `[from: …]` サフィックスを確認します。 + +## 既知の考慮事項 + +- heartbeat は、ノイズの多いブロードキャストを避けるため、意図的にグループではスキップされます。 +- エコー抑制は結合されたバッチ文字列を使います。同一テキストをメンションなしで 2 回送信した場合、返信されるのは最初の 1 回だけです。 +- セッションストアのエントリは、セッションストア（既定では `~/.openclaw/agents//sessions/sessions.json`）内で `agent::whatsapp:group:` として表示されます。エントリがない場合は、そのグループがまだ実行をトリガーしていないことを意味するだけです。 +- グループでの入力中インジケーターは `agents.defaults.typingMode` に従います（既定: メンションされていない場合は `message`）。 diff --git a/docs/ja-JP/channels/groups.md b/docs/ja-JP/channels/groups.md new file mode 100644 index 000000000..3c041764d --- /dev/null +++ b/docs/ja-JP/channels/groups.md @@ -0,0 +1,417 @@ +--- +read_when: + - グループチャット動作またはメンションゲーティングを変更するとき +summary: 各サーフェスでのグループチャット動作（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo） +title: グループ +x-i18n: + generated_at: "2026-04-05T12:35:46Z" + model: gpt-5.4 + provider: openai + source_hash: 39d066e0542b468c6f8b384b463e2316590ea09a00ecb2065053e1e2ce55bd5f + source_path: channels/groups.md + workflow: 15 +--- + +# グループ + +OpenClaw は、Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo の各サーフェスで、一貫した方法でグループチャットを扱います。 + +## 初心者向けイントロ（2 分） + +OpenClaw は、あなた自身のメッセージングアカウント上で「動作」します。別個の WhatsApp bot ユーザーは存在しません。 +**あなた**がグループに参加していれば、OpenClaw はそのグループを認識し、そこで返信できます。 + +デフォルトの動作: + +- グループは制限されています（`groupPolicy: "allowlist"`）。 +- 明示的にメンションゲーティングを無効にしない限り、返信にはメンションが必要です。 + +つまり、allowlist に登録された送信者は、OpenClaw にメンションすることで起動できます。 + +> 要点 +> +> - **DM アクセス**は `*.allowFrom` で制御されます。 +> - **グループアクセス**は `*.groupPolicy` と allowlist（`*.groups`、`*.groupAllowFrom`）で制御されます。 +> - **返信トリガー**はメンションゲーティング（`requireMention`、`/activation`）で制御されます。 + +クイックフロー（グループメッセージに対して何が起きるか）: + +``` +groupPolicy? disabled -> drop +groupPolicy? allowlist -> group allowed? no -> drop +requireMention? yes -> mentioned? no -> store for context only +otherwise -> reply +``` + +## コンテキスト可視性と allowlist + +グループの安全性には、異なる 2 つの制御が関わります。 + +- **トリガー認可**: 誰がエージェントを起動できるか（`groupPolicy`、`groups`、`groupAllowFrom`、チャネル固有の allowlist）。 +- **コンテキスト可視性**: モデルに注入される補助コンテキストの内容（返信テキスト、引用、スレッド履歴、転送メタデータ）。 + +デフォルトでは、OpenClaw は通常のチャット動作を優先し、コンテキストをほぼ受信したまま保持します。つまり、allowlist は主に誰がアクションを起動できるかを決めるものであり、引用や履歴スニペットのすべてに対する普遍的なマスキング境界ではありません。 + +現在の動作はチャネルごとに異なります。 + +- 一部のチャネルでは、特定のパスですでに送信者ベースの補助コンテキストフィルタリングが適用されています（たとえば Slack のスレッドシード、Matrix の返信/スレッド参照）。 +- 他のチャネルでは、引用/返信/転送コンテキストは受信したまま渡されます。 + +ハードニングの方向性（計画中）: + +- `contextVisibility: "all"`（デフォルト）は、現在の受信どおりの動作を維持します。 +- `contextVisibility: "allowlist"` は、補助コンテキストを allowlist に登録された送信者に限定します。 +- `contextVisibility: "allowlist_quote"` は `allowlist` に加えて、明示的な 1 つの引用/返信例外を認めます。 + +このハードニングモデルがすべてのチャネルで一貫して実装されるまでは、サーフェスごとの差異があることを想定してください。 + +![グループメッセージフロー](/images/groups-flow.svg) + +やりたいことが次のいずれかなら... + +| 目的 | 設定内容 | +| -------------------------------------------- | ---------------------------------------------------------- | +| すべてのグループを許可しつつ、@メンション時のみ返信 | `groups: { "*": { requireMention: true } }` | +| すべてのグループ返信を無効化 | `groupPolicy: "disabled"` | +| 特定のグループのみ | `groups: { "": { ... } }`（`"*"` キーなし） | +| グループ内で起動できるのを自分だけにする | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | + +## セッションキー + +- グループセッションは `agent:::group:` セッションキーを使います（room/channel は `agent:::channel:` を使います）。 +- Telegram フォーラムトピックでは、各トピックが独自のセッションを持つように、グループ ID に `:topic:` が追加されます。 +- ダイレクトチャットはメインセッションを使います（設定されていれば送信者ごとのセッション）。 +- グループセッションでは heartbeat はスキップされます。 + + + +## パターン: 個人 DM + 公開グループ（単一エージェント） + +はい。あなたの「個人」トラフィックが **DM** で、「公開」トラフィックが **グループ** なら、これはうまく機能します。 + +理由: 単一エージェントモードでは、DM は通常 **main** セッションキー（`agent:main:main`）に入り、グループは常に **非 main** セッションキー（`agent:main::group:`）を使います。`mode: "non-main"` でサンドボックスを有効にすると、それらのグループセッションは Docker 内で実行され、メインの DM セッションはホスト上に残ります。 + +これにより、1 つのエージェント「頭脳」（共有ワークスペース + メモリ）で、2 つの実行態勢を持てます。 + +- **DM**: フルツール（ホスト） +- **グループ**: サンドボックス + 制限付きツール（Docker） + +> ワークスペースやペルソナを本当に分離する必要がある場合（「個人」と「公開」が決して混ざってはならない場合）は、2 つ目のエージェント + バインディングを使ってください。[Multi-Agent Routing](/concepts/multi-agent)を参照してください。 + +例（DM はホスト、グループはサンドボックス + メッセージング専用ツール）: + +```json5 +{ + agents: { + defaults: { + sandbox: { + mode: "non-main", // groups/channels are non-main -> sandboxed + scope: "session", // strongest isolation (one container per group/channel) + workspaceAccess: "none", + }, + }, + }, + tools: { + sandbox: { + tools: { + // If allow is non-empty, everything else is blocked (deny still wins). + allow: ["group:messaging", "group:sessions"], + deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"], + }, + }, + }, +} +``` + +「ホストアクセスなし」ではなく「グループがフォルダー X だけ見られるように」したい場合は、`workspaceAccess: "none"` のままにして、allowlist に登録したパスだけをサンドボックスにマウントします。 + +```json5 +{ + agents: { + defaults: { + sandbox: { + mode: "non-main", + scope: "session", + workspaceAccess: "none", + docker: { + binds: [ + // hostPath:containerPath:mode + "/home/user/FriendsShared:/data:ro", + ], + }, + }, + }, + }, +} +``` + +関連: + +- 設定キーとデフォルト: [Gateway configuration](/gateway/configuration-reference#agentsdefaultssandbox) +- ツールがブロックされる理由のデバッグ: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) +- バインドマウントの詳細: [Sandboxing](/gateway/sandboxing#custom-bind-mounts) + +## 表示ラベル + +- UI ラベルは、利用可能な場合は `displayName` を使い、`:` の形式で表示されます。 +- `#room` は room/channel 用に予約されています。グループチャットは `g-` を使います（小文字、スペースは `-` に変換し、`#@+._-` は維持）。 + +## グループポリシー + +チャネルごとに、グループ/room メッセージの扱いを制御します。 + +```json5 +{ + channels: { + whatsapp: { + groupPolicy: "disabled", // "open" | "disabled" | "allowlist" + groupAllowFrom: ["+15551234567"], + }, + telegram: { + groupPolicy: "disabled", + groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username) + }, + signal: { + groupPolicy: "disabled", + groupAllowFrom: ["+15551234567"], + }, + imessage: { + groupPolicy: "disabled", + groupAllowFrom: ["chat_id:123"], + }, + msteams: { + groupPolicy: "disabled", + groupAllowFrom: ["user@org.com"], + }, + discord: { + groupPolicy: "allowlist", + guilds: { + GUILD_ID: { channels: { help: { allow: true } } }, + }, + }, + slack: { + groupPolicy: "allowlist", + channels: { "#general": { allow: true } }, + }, + matrix: { + groupPolicy: "allowlist", + groupAllowFrom: ["@owner:example.org"], + groups: { + "!roomId:example.org": { allow: true }, + "#alias:example.org": { allow: true }, + }, + }, + }, +} +``` + +| ポリシー | 動作 | +| ------------- | ------------------------------------------------------------ | +| `"open"` | グループは allowlist をバイパスします。メンションゲーティングは引き続き適用されます。 | +| `"disabled"` | すべてのグループメッセージを完全にブロックします。 | +| `"allowlist"` | 設定済みの allowlist に一致するグループ/room のみ許可します。 | + +注記: + +- `groupPolicy` は、@メンションを必須にするメンションゲーティングとは別物です。 +- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: `groupAllowFrom` を使います（フォールバック: 明示的な `allowFrom`）。 +- DM ペアリング承認（`*-allowFrom` ストアエントリ）は DM アクセスにのみ適用されます。グループ送信者認可は、グループ allowlist で引き続き明示的に行います。 +- Discord: allowlist は `channels.discord.guilds..channels` を使います。 +- Slack: allowlist は `channels.slack.channels` を使います。 +- Matrix: allowlist は `channels.matrix.groups` を使います。room ID または alias を優先してください。参加済み room 名の参照はベストエフォートで、解決できない名前は実行時に無視されます。送信者を制限するには `channels.matrix.groupAllowFrom` を使います。room ごとの `users` allowlist もサポートされています。 +- グループ DM は別個に制御されます（`channels.discord.dm.*`、`channels.slack.dm.*`）。 +- Telegram allowlist は、ユーザー ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）またはユーザー名（`"@alice"` または `"alice"`）に一致できます。プレフィックスは大文字小文字を区別しません。 +- デフォルトは `groupPolicy: "allowlist"` です。グループ allowlist が空の場合、グループメッセージはブロックされます。 +- ランタイム安全性: プロバイダーブロック全体が欠けている場合（`channels.` が存在しない場合）、グループポリシーは `channels.defaults.groupPolicy` を継承せず、フェイルクローズドモード（通常は `allowlist`）にフォールバックします。 + +クイックな考え方（グループメッセージの評価順）: + +1. `groupPolicy`（open/disabled/allowlist） +2. グループ allowlist（`*.groups`、`*.groupAllowFrom`、チャネル固有の allowlist） +3. メンションゲーティング（`requireMention`、`/activation`） + +## メンションゲーティング（デフォルト） + +グループメッセージでは、グループごとに上書きしない限り、メンションが必要です。デフォルトは各サブシステムの `*.groups."*"` にあります。 + +bot メッセージへの返信は、暗黙のメンションとして扱われます（チャネルが返信メタデータをサポートしている場合）。これは Telegram、WhatsApp、Slack、Discord、Microsoft Teams に適用されます。 + +```json5 +{ + channels: { + whatsapp: { + groups: { + "*": { requireMention: true }, + "123@g.us": { requireMention: false }, + }, + }, + telegram: { + groups: { + "*": { requireMention: true }, + "123456789": { requireMention: false }, + }, + }, + imessage: { + groups: { + "*": { requireMention: true }, + "123": { requireMention: false }, + }, + }, + }, + agents: { + list: [ + { + id: "main", + groupChat: { + mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"], + historyLimit: 50, + }, + }, + ], + }, +} +``` + +注記: + +- `mentionPatterns` は大文字小文字を区別しない安全な regex パターンです。無効なパターンや危険なネスト反復形式は無視されます。 +- 明示的なメンションを提供するサーフェスでは、それが引き続き通ります。パターンはフォールバックです。 +- エージェントごとの上書き: `agents.list[].groupChat.mentionPatterns`（複数のエージェントが同じグループを共有する場合に便利です）。 +- メンションゲーティングは、メンション検出が可能な場合にのみ適用されます（ネイティブメンションがあるか、`mentionPatterns` が設定されている場合）。 +- Discord のデフォルトは `channels.discord.guilds."*"` にあります（guild/channel ごとに上書き可能）。 +- グループ履歴コンテキストはチャネルをまたいで統一的にラップされ、**pending-only** です（メンションゲーティングのためにスキップされたメッセージのみ）。グローバルデフォルトには `messages.groupChat.historyLimit` を使い、上書きには `channels..historyLimit`（または `channels..accounts.*.historyLimit`）を使います。無効化するには `0` を設定してください。 + +## グループ/channel ツール制限（任意） + +一部のチャネル設定では、**特定のグループ/room/channel 内**で利用可能なツールを制限できます。 + +- `tools`: グループ全体に対するツールの allow/deny。 +- `toolsBySender`: グループ内の送信者ごとの上書き。 + 明示的なキープレフィックスを使ってください: + `id:`、`e164:`、`username:`、`name:`、および `"*"` ワイルドカード。 + 旧来のプレフィックスなしキーも引き続き受け付けられ、`id:` のみとして一致します。 + +解決順（最も具体的なものが優先）: + +1. グループ/channel の `toolsBySender` 一致 +2. グループ/channel の `tools` +3. デフォルト（`"*"`）の `toolsBySender` 一致 +4. デフォルト（`"*"`）の `tools` + +例（Telegram）: + +```json5 +{ + channels: { + telegram: { + groups: { + "*": { tools: { deny: ["exec"] } }, + "-1001234567890": { + tools: { deny: ["exec", "read", "write"] }, + toolsBySender: { + "id:123456789": { alsoAllow: ["exec"] }, + }, + }, + }, + }, + }, +} +``` + +注記: + +- グループ/channel のツール制限は、グローバル/エージェントのツールポリシーに加えて適用されます（deny が引き続き優先されます）。 +- 一部のチャネルでは、room/channel に対して異なるネスト構造を使います（例: Discord の `guilds.*.channels.*`、Slack の `channels.*`、Microsoft Teams の `teams.*.channels.*`）。 + +## グループ allowlist + +`channels.whatsapp.groups`、`channels.telegram.groups`、または `channels.imessage.groups` が設定されている場合、そのキーはグループ allowlist として機能します。すべてのグループを許可しつつデフォルトのメンション動作を設定したい場合は、`"*"` を使います。 + +よくある混乱: DM ペアリング承認はグループ認可とは同じではありません。 +DM ペアリングをサポートするチャネルでは、ペアリングストアは DM のみを解放します。グループコマンドには、`groupAllowFrom` やそのチャネルでドキュメント化された設定フォールバックなど、設定 allowlist からの明示的なグループ送信者認可が引き続き必要です。 + +よくある意図（コピー&ペースト用）: + +1. すべてのグループ返信を無効化 + +```json5 +{ + channels: { whatsapp: { groupPolicy: "disabled" } }, +} +``` + +2. 特定のグループのみ許可（WhatsApp） + +```json5 +{ + channels: { + whatsapp: { + groups: { + "123@g.us": { requireMention: true }, + "456@g.us": { requireMention: false }, + }, + }, + }, +} +``` + +3. すべてのグループを許可するがメンション必須（明示的） + +```json5 +{ + channels: { + whatsapp: { + groups: { "*": { requireMention: true } }, + }, + }, +} +``` + +4. グループ内で起動できるのをオーナーだけにする（WhatsApp） + +```json5 +{ + channels: { + whatsapp: { + groupPolicy: "allowlist", + groupAllowFrom: ["+15551234567"], + groups: { "*": { requireMention: true } }, + }, + }, +} +``` + +## Activation（owner-only） + +グループオーナーは、グループごとの activation を切り替えられます。 + +- `/activation mention` +- `/activation always` + +owner は `channels.whatsapp.allowFrom`（未設定の場合は bot 自身の self E.164）で決まります。このコマンドは単独のメッセージとして送信してください。現在、他のサーフェスでは `/activation` は無視されます。 + +## コンテキストフィールド + +グループの受信ペイロードでは次が設定されます。 + +- `ChatType=group` +- `GroupSubject`（判明している場合） +- `GroupMembers`（判明している場合） +- `WasMentioned`（メンションゲーティングの結果） +- Telegram フォーラムトピックでは、さらに `MessageThreadId` と `IsForum` も含まれます。 + +チャネル固有の注記: + +- BlueBubbles は、名前のない macOS グループ参加者について、`GroupMembers` を設定する前にローカル Contacts データベースから任意で情報を補完できます。これはデフォルトでオフであり、通常のグループゲーティングに通過した後にのみ実行されます。 + +エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループ向けイントロが含まれます。これは、モデルに人間のように応答すること、Markdown テーブルを避けること、リテラルな `\n` シーケンスを入力しないことを促します。 + +## iMessage の詳細 + +- ルーティングまたは allowlist には `chat_id:` を優先してください。 +- チャット一覧: `imsg chats --limit 20` +- グループ返信は常に同じ `chat_id` に戻ります。 + +## WhatsApp の詳細 + +WhatsApp 固有の動作（履歴注入、メンション処理の詳細）については、[Group messages](/channels/group-messages)を参照してください。 diff --git a/docs/ja-JP/channels/imessage.md b/docs/ja-JP/channels/imessage.md new file mode 100644 index 000000000..40b8ec155 --- /dev/null +++ b/docs/ja-JP/channels/imessage.md @@ -0,0 +1,434 @@ +--- +read_when: + - iMessageサポートをセットアップするとき + - iMessageの送受信をデバッグするとき +summary: imsg経由の従来のiMessageサポート（stdio上のJSON-RPC）。新しいセットアップではBlueBubblesを使用してください。 +title: iMessage +x-i18n: + generated_at: "2026-04-05T12:35:35Z" + model: gpt-5.4 + provider: openai + source_hash: 086d85bead49f75d12ae6b14ac917af52375b6afd28f6af1a0dcbbc7fcb628a0 + source_path: channels/imessage.md + workflow: 15 +--- + +# iMessage（legacy: imsg） + + +新しいiMessageデプロイでは、BlueBubblesを使用してください。 + +`imsg`統合はレガシーであり、将来のリリースで削除される可能性があります。 + + +ステータス: レガシーな外部CLI統合。Gatewayは`imsg rpc`を起動し、stdio上のJSON-RPCで通信します（別個のデーモンやポートはありません）。 + + + + 新しいセットアップ向けの推奨iMessage経路です。 + + + iMessageのDMはデフォルトでpairingモードです。 + + + iMessageフィールドの完全なリファレンスです。 + + + +## クイックセットアップ + + + + + + +```bash +brew install steipete/tap/imsg +imsg rpc --help +``` + + + + + +```json5 +{ + channels: { + imessage: { + enabled: true, + cliPath: "/usr/local/bin/imsg", + dbPath: "/Users//Library/Messages/chat.db", + }, + }, +} +``` + + + + + +```bash +openclaw gateway +``` + + + + + +```bash +openclaw pairing list imessage +openclaw pairing approve imessage +``` + + Pairingリクエストは1時間後に期限切れになります。 + + + + + + + OpenClawはstdio互換の`cliPath`だけを必要とするため、`cliPath`をリモートMacにSSHして`imsg`を実行するラッパースクリプトに向けることができます。 + +```bash +#!/usr/bin/env bash +exec ssh -T gateway-host imsg "$@" +``` + + 添付ファイルを有効にする場合の推奨config: + +```json5 +{ + channels: { + imessage: { + enabled: true, + cliPath: "~/.openclaw/scripts/imsg-ssh", + remoteHost: "user@gateway-host", // SCP添付ファイル取得に使用 + includeAttachments: true, + // 任意: 許可する添付ファイルルートを上書きします。 + // デフォルトには /Users/*/Library/Messages/Attachments が含まれます + attachmentRoots: ["/Users/*/Library/Messages/Attachments"], + remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"], + }, + }, +} +``` + + `remoteHost`が設定されていない場合、OpenClawはSSHラッパースクリプトを解析して自動検出を試みます。 + `remoteHost`は`host`または`user@host`である必要があります（空白やSSHオプションは不可）。 + OpenClawはSCPに厳格なホストキー検証を使用するため、リレーホストのホストキーがすでに`~/.ssh/known_hosts`に存在している必要があります。 + 添付ファイルパスは許可されたルート（`attachmentRoots` / `remoteAttachmentRoots`）に対して検証されます。 + + + + +## 要件と権限（macOS） + +- `imsg`を実行するMacでMessagesにサインインしている必要があります。 +- OpenClaw/`imsg`を実行するプロセスコンテキストにはフルディスクアクセスが必要です（Messages DBアクセス）。 +- Messages.app経由でメッセージを送信するにはAutomation権限が必要です。 + + +権限はプロセスコンテキストごとに付与されます。gatewayがヘッドレスで実行される場合（LaunchAgent/SSH）、同じコンテキストで一度だけ対話型コマンドを実行してプロンプトを表示させてください。 + +```bash +imsg chats --limit 1 +# または +imsg send "test" +``` + + + +## アクセス制御とルーティング + + + + `channels.imessage.dmPolicy`はダイレクトメッセージを制御します。 + + - `pairing`（デフォルト） + - `allowlist` + - `open`（`allowFrom`に`"*"`を含める必要があります） + - `disabled` + + allowlistフィールド: `channels.imessage.allowFrom`。 + + allowlistエントリーには、ハンドルまたはチャットターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用できます。 + + + + + `channels.imessage.groupPolicy`はグループ処理を制御します。 + + - `allowlist`（設定されている場合のデフォルト） + - `open` + - `disabled` + + グループ送信者allowlist: `channels.imessage.groupAllowFrom`。 + + ランタイムフォールバック: `groupAllowFrom`が未設定の場合、利用可能であればiMessageのグループ送信者チェックは`allowFrom`にフォールバックします。 + ランタイム注記: `channels.imessage`が完全に欠けている場合、ランタイムは`groupPolicy="allowlist"`にフォールバックし、警告を記録します（`channels.defaults.groupPolicy`が設定されていても同様です）。 + + グループ向けのmentionゲーティング: + + - iMessageにはネイティブのmentionメタデータがありません + - mention検出では正規表現パターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは`messages.groupChat.mentionPatterns`）を使用します + - パターンが設定されていない場合、mentionゲーティングは適用できません + + 認可された送信者からの制御コマンドは、グループでmentionゲーティングをバイパスできます。 + + + + + - DMはダイレクトルーティングを使用し、グループはグループルーティングを使用します。 + - デフォルトの`session.dmScope=main`では、iMessageのDMはagentのメインセッションに統合されます。 + - グループセッションは分離されます（`agent::imessage:group:`）。 + - 返信は、発信元のチャンネル／ターゲットメタデータを使ってiMessageに戻されます。 + + グループ風スレッドの動作: + + 一部の複数参加者iMessageスレッドは`is_group=false`で届くことがあります。 + その`chat_id`が`channels.imessage.groups`で明示的に設定されている場合、OpenClawはそれをグループトラフィックとして扱います（グループゲーティング + グループセッション分離）。 + + + + +## ACP会話バインディング + +レガシーiMessageチャットはACPセッションにもバインドできます。 + +高速なオペレーターフロー: + +- DMまたは許可されたグループチャット内で`/acp spawn codex --bind here`を実行します。 +- 以後、同じiMessage会話内のメッセージは、生成されたACPセッションにルーティングされます。 +- `/new`および`/reset`は、同じバインド済みACPセッションをその場でリセットします。 +- `/acp close`はACPセッションを閉じ、バインディングを削除します。 + +設定済みの永続的バインディングは、トップレベルの`bindings[]`エントリーで`type: "acp"`および`match.channel: "imessage"`を使ってサポートされます。 + +`match.peer.id`には次を使用できます。 + +- `+15555550123`や`user@example.com`のような正規化済みDMハンドル +- `chat_id:`（安定したグループバインディングに推奨） +- `chat_guid:` +- `chat_identifier:` + +例: + +```json5 +{ + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { agent: "codex", backend: "acpx", mode: "persistent" }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "imessage", + accountId: "default", + peer: { kind: "group", id: "chat_id:123" }, + }, + acp: { label: "codex-group" }, + }, + ], +} +``` + +共有ACPバインディング動作については[ACP Agents](/tools/acp-agents)を参照してください。 + +## デプロイパターン + + + + 専用のApple IDとmacOSユーザーを使い、botトラフィックを個人のMessagesプロフィールから分離します。 + + 一般的なフロー: + + 1. 専用のmacOSユーザーを作成してサインインします。 + 2. そのユーザーでbot用Apple IDを使ってMessagesにサインインします。 + 3. そのユーザーに`imsg`をインストールします。 + 4. OpenClawがそのユーザーコンテキストで`imsg`を実行できるようにSSHラッパーを作成します。 + 5. `channels.imessage.accounts..cliPath`と`.dbPath`をそのユーザープロファイルに向けます。 + + 初回実行では、そのbotユーザーセッションでGUI承認（Automation + フルディスクアクセス）が必要になる場合があります。 + + + + + 一般的なトポロジー: + + - gatewayはLinux/VMで実行 + - iMessage + `imsg`はtailnet内のMacで実行 + - `cliPath`ラッパーはSSHを使用して`imsg`を実行 + - `remoteHost`はSCP添付ファイル取得を有効化 + + 例: + +```json5 +{ + channels: { + imessage: { + enabled: true, + cliPath: "~/.openclaw/scripts/imsg-ssh", + remoteHost: "bot@mac-mini.tailnet-1234.ts.net", + includeAttachments: true, + dbPath: "/Users/bot/Library/Messages/chat.db", + }, + }, +} +``` + +```bash +#!/usr/bin/env bash +exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@" +``` + + SSHキーを使用して、SSHとSCPの両方を非対話型にしてください。 + まずホストキーが信頼されていることを確認してください（例: `ssh bot@mac-mini.tailnet-1234.ts.net`）。これにより`known_hosts`が設定されます。 + + + + + iMessageは`channels.imessage.accounts`配下のアカウント単位configをサポートします。 + + 各アカウントは、`cliPath`、`dbPath`、`allowFrom`、`groupPolicy`、`mediaMaxMb`、履歴設定、添付ファイルルートallowlistなどのフィールドを上書きできます。 + + + + +## メディア、チャンク化、配信ターゲット + + + + - 受信添付ファイルの取り込みは任意です: `channels.imessage.includeAttachments` + - `remoteHost`が設定されている場合、リモート添付ファイルパスはSCP経由で取得できます + - 添付ファイルパスは許可されたルートに一致する必要があります: + - `channels.imessage.attachmentRoots`（ローカル） + - `channels.imessage.remoteAttachmentRoots`（リモートSCPモード） + - デフォルトのルートパターン: `/Users/*/Library/Messages/Attachments` + - SCPは厳格なホストキー検証を使用します（`StrictHostKeyChecking=yes`） + - 送信メディアサイズには`channels.imessage.mediaMaxMb`（デフォルト16 MB）を使用します + + + + - テキストチャンク上限: `channels.imessage.textChunkLimit`（デフォルト4000） + - チャンクモード: `channels.imessage.chunkMode` + - `length`（デフォルト） + - `newline`（段落優先分割） + + + + 推奨される明示的ターゲット: + + - `chat_id:123`（安定したルーティングに推奨） + - `chat_guid:...` + - `chat_identifier:...` + + ハンドルターゲットもサポートされます: + + - `imessage:+1555...` + - `sms:+1555...` + - `user@example.com` + +```bash +imsg chats --limit 20 +``` + + + + +## config書き込み + +iMessageでは、デフォルトでチャンネル起点のconfig書き込みが許可されています（`commands.config: true`のときの`/config set|unset`用）。 + +無効化する場合: + +```json5 +{ + channels: { + imessage: { + configWrites: false, + }, + }, +} +``` + +## トラブルシューティング + + + + バイナリとRPCサポートを検証します。 + +```bash +imsg rpc --help +openclaw channels status --probe +``` + + probeでRPC未対応と表示された場合は、`imsg`を更新してください。 + + + + + 次を確認してください。 + + - `channels.imessage.dmPolicy` + - `channels.imessage.allowFrom` + - pairing承認（`openclaw pairing list imessage`） + + + + + 次を確認してください。 + + - `channels.imessage.groupPolicy` + - `channels.imessage.groupAllowFrom` + - `channels.imessage.groups`のallowlist動作 + - mentionパターン設定（`agents.list[].groupChat.mentionPatterns`） + + + + + 次を確認してください。 + + - `channels.imessage.remoteHost` + - `channels.imessage.remoteAttachmentRoots` + - gatewayホストからのSSH/SCPキー認証 + - gatewayホスト上の`~/.ssh/known_hosts`にホストキーが存在すること + - Messagesを実行しているMac上でのリモートパスの可読性 + + + + + 同じユーザー／セッションコンテキストの対話型GUIターミナルで再実行し、プロンプトを承認してください。 + +```bash +imsg chats --limit 1 +imsg send "test" +``` + + OpenClaw/`imsg`を実行するプロセスコンテキストに、フルディスクアクセスとAutomationが付与されていることを確認してください。 + + + + +## 設定リファレンスへのポインター + +- [Configuration reference - iMessage](/gateway/configuration-reference#imessage) +- [Gateway configuration](/gateway/configuration) +- [Pairing](/channels/pairing) +- [BlueBubbles](/channels/bluebubbles) + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャンネル +- [Pairing](/channels/pairing) — DM認証とpairingフロー +- [Groups](/channels/groups) — グループチャットの動作とmentionゲーティング +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/index.md b/docs/ja-JP/channels/index.md new file mode 100644 index 000000000..1591de476 --- /dev/null +++ b/docs/ja-JP/channels/index.md @@ -0,0 +1,56 @@ +--- +read_when: + - OpenClaw 用のチャットチャネルを選びたい + - サポートされているメッセージングプラットフォームの概要を手早く知りたい +summary: OpenClaw が接続できるメッセージングプラットフォーム +title: チャットチャネル +x-i18n: + generated_at: "2026-04-05T12:35:27Z" + model: gpt-5.4 + provider: openai + source_hash: 246ee6f16aebe751241f00102bb435978ed21f6158385aff5d8e222e30567416 + source_path: channels/index.md + workflow: 15 +--- + +# チャットチャネル + +OpenClaw は、あなたがすでに使っているどのチャットアプリでもやり取りできます。各チャネルは Gateway 経由で接続します。 +テキストはどこでもサポートされますが、メディアとリアクションはチャネルごとに異なります。 + +## サポートされているチャネル + +- [BlueBubbles](/channels/bluebubbles) — **iMessage に推奨**。BlueBubbles macOS サーバー REST API を使用し、完全な機能サポートを提供します（バンドルされたプラグイン。編集、送信取り消し、エフェクト、リアクション、グループ管理。編集は現在 macOS 26 Tahoe では壊れています）。 +- [Discord](/channels/discord) — Discord Bot API + Gateway。サーバー、チャネル、DM をサポートします。 +- [Feishu](/channels/feishu) — WebSocket 経由の Feishu/Lark ボット（バンドルされたプラグイン）。 +- [Google Chat](/channels/googlechat) — HTTP webhook 経由の Google Chat API アプリ。 +- [iMessage (legacy)](/channels/imessage) — imsg CLI 経由の従来の macOS 統合（非推奨。新しいセットアップでは BlueBubbles を使用してください）。 +- [IRC](/channels/irc) — 従来型の IRC サーバー。ペアリング/許可リスト制御付きのチャネル + DM。 +- [LINE](/channels/line) — LINE Messaging API ボット（バンドルされたプラグイン）。 +- [Matrix](/channels/matrix) — Matrix プロトコル（バンドルされたプラグイン）。 +- [Mattermost](/channels/mattermost) — Bot API + WebSocket。チャネル、グループ、DM（バンドルされたプラグイン）。 +- [Microsoft Teams](/channels/msteams) — Bot Framework。エンタープライズ対応（バンドルされたプラグイン）。 +- [Nextcloud Talk](/channels/nextcloud-talk) — Nextcloud Talk 経由のセルフホスト型チャット（バンドルされたプラグイン）。 +- [Nostr](/channels/nostr) — NIP-04 経由の分散型 DM（バンドルされたプラグイン）。 +- [QQ Bot](/channels/qqbot) — QQ Bot API。プライベートチャット、グループチャット、リッチメディア（バンドルされたプラグイン）。 +- [Signal](/channels/signal) — signal-cli。プライバシー重視。 +- [Slack](/channels/slack) — Bolt SDK。ワークスペースアプリ。 +- [Synology Chat](/channels/synology-chat) — 送信 + 受信 webhook 経由の Synology NAS Chat（バンドルされたプラグイン）。 +- [Telegram](/channels/telegram) — grammY 経由の Bot API。グループをサポートします。 +- [Tlon](/channels/tlon) — Urbit ベースのメッセンジャー（バンドルされたプラグイン）。 +- [Twitch](/channels/twitch) — IRC 接続経由の Twitch チャット（バンドルされたプラグイン）。 +- [Voice Call](/plugins/voice-call) — Plivo または Twilio 経由の電話機能（プラグイン。別途インストールが必要）。 +- [WebChat](/web/webchat) — WebSocket 経由の Gateway WebChat UI。 +- [WeChat](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — QR ログイン経由の Tencent iLink Bot プラグイン。プライベートチャットのみ。 +- [WhatsApp](/channels/whatsapp) — 最も人気があります。Baileys を使用し、QR ペアリングが必要です。 +- [Zalo](/channels/zalo) — Zalo Bot API。ベトナムで人気のメッセンジャー（バンドルされたプラグイン）。 +- [Zalo Personal](/channels/zalouser) — QR ログイン経由の Zalo 個人アカウント（バンドルされたプラグイン）。 + +## 注意事項 + +- チャネルは同時に実行できます。複数を設定すると、OpenClaw がチャットごとにルーティングします。 +- 最も素早くセットアップできるのは通常 **Telegram** です（シンプルなボットトークン）。WhatsApp では QR ペアリングが必要で、より多くの状態がディスクに保存されます。 +- グループの挙動はチャネルごとに異なります。詳しくは [Groups](/channels/groups) を参照してください。 +- 安全のため、DM のペアリングと許可リストが適用されます。詳しくは [Security](/gateway/security) を参照してください。 +- トラブルシューティング: [チャネルのトラブルシューティング](/channels/troubleshooting)。 +- モデルプロバイダーは別途ドキュメント化されています。詳しくは [Model Providers](/providers/models) を参照してください。 diff --git a/docs/ja-JP/channels/irc.md b/docs/ja-JP/channels/irc.md new file mode 100644 index 000000000..d7a45a714 --- /dev/null +++ b/docs/ja-JP/channels/irc.md @@ -0,0 +1,259 @@ +--- +read_when: + - OpenClaw を IRC チャネルまたは DM に接続したいとき + - IRC の許可リスト、グループポリシー、またはメンションゲートを設定しているとき +summary: IRC プラグインのセットアップ、アクセス制御、トラブルシューティング +title: IRC +x-i18n: + generated_at: "2026-04-05T12:35:35Z" + model: gpt-5.4 + provider: openai + source_hash: fceab2979db72116689c6c774d6736a8a2eee3559e3f3cf8969e673d317edd94 + source_path: channels/irc.md + workflow: 15 +--- + +# IRC + +クラシックなチャネル（`#room`）やダイレクトメッセージで OpenClaw を使いたい場合は IRC を使用します。 +IRC は拡張プラグインとして提供されますが、設定はメイン設定の `channels.irc` で行います。 + +## クイックスタート + +1. `~/.openclaw/openclaw.json` で IRC 設定を有効にします。 +2. 少なくとも次を設定します。 + +```json5 +{ + channels: { + irc: { + enabled: true, + host: "irc.example.com", + port: 6697, + tls: true, + nick: "openclaw-bot", + channels: ["#openclaw"], + }, + }, +} +``` + +ボット連携には、プライベートな IRC サーバーを推奨します。意図的に公開 IRC ネットワークを使う場合、一般的な選択肢には Libera.Chat、OFTC、Snoonet があります。ボットや swarm のバックチャネル通信には、予測しやすい公開チャネルを避けてください。 + +3. Gateway を起動または再起動します。 + +```bash +openclaw gateway run +``` + +## 既定のセキュリティ設定 + +- `channels.irc.dmPolicy` の既定値は `"pairing"` です。 +- `channels.irc.groupPolicy` の既定値は `"allowlist"` です。 +- `groupPolicy="allowlist"` の場合は、許可するチャネルを定義するために `channels.irc.groups` を設定します。 +- 平文転送を意図的に許可するのでない限り、TLS（`channels.irc.tls=true`）を使用してください。 + +## アクセス制御 + +IRC チャネルには、2 つの独立した「ゲート」があります。 + +1. **チャネルアクセス**（`groupPolicy` + `groups`）: そのチャネルからのメッセージをボットが受け付けるかどうか。 +2. **送信者アクセス**（`groupAllowFrom` / チャネルごとの `groups["#channel"].allowFrom`）: そのチャネル内で誰がボットをトリガーできるか。 + +設定キー: + +- DM 許可リスト（DM 送信者アクセス）: `channels.irc.allowFrom` +- グループ送信者許可リスト（チャネル送信者アクセス）: `channels.irc.groupAllowFrom` +- チャネルごとの制御（チャネル + 送信者 + メンションルール）: `channels.irc.groups["#channel"]` +- `channels.irc.groupPolicy="open"` は未設定のチャネルを許可します（**それでも既定ではメンションゲートが有効です**） + +許可リストのエントリには、安定した送信者 ID（`nick!user@host`）を使用してください。 +ニックネームだけの一致は変更可能であり、`channels.irc.dangerouslyAllowNameMatching: true` の場合にのみ有効になります。 + +### よくある落とし穴: `allowFrom` は DM 用であり、チャネル用ではない + +次のようなログが表示される場合: + +- `irc: drop group sender alice!ident@host (policy=allowlist)` + +これは、その送信者が**グループ/チャネル**メッセージとしては許可されていないことを意味します。次のいずれかで修正してください。 + +- `channels.irc.groupAllowFrom` を設定する（すべてのチャネルに対するグローバル設定） +- チャネルごとの送信者許可リストを設定する: `channels.irc.groups["#channel"].allowFrom` + +例（`#tuirc-dev` 内の誰でもボットに話しかけられるようにする）: + +```json5 +{ + channels: { + irc: { + groupPolicy: "allowlist", + groups: { + "#tuirc-dev": { allowFrom: ["*"] }, + }, + }, + }, +} +``` + +## 返信トリガー（メンション） + +チャネルが許可されていて（`groupPolicy` + `groups`）、送信者も許可されていても、OpenClaw はグループコンテキストでは既定で**メンションゲート**を使います。 + +つまり、メッセージにボットへ一致するメンションパターンが含まれていない限り、`drop channel … (missing-mention)` のようなログが表示されることがあります。 + +IRC チャネルで**メンションなしで**ボットに返信させたい場合は、そのチャネルのメンションゲートを無効にします。 + +```json5 +{ + channels: { + irc: { + groupPolicy: "allowlist", + groups: { + "#tuirc-dev": { + requireMention: false, + allowFrom: ["*"], + }, + }, + }, + }, +} +``` + +または、**すべての** IRC チャネルを許可し（チャネルごとの許可リストなし）、なおかつメンションなしで返信させるには: + +```json5 +{ + channels: { + irc: { + groupPolicy: "open", + groups: { + "*": { requireMention: false, allowFrom: ["*"] }, + }, + }, + }, +} +``` + +## セキュリティに関する注意（公開チャネルで推奨） + +公開チャネルで `allowFrom: ["*"]` を許可すると、誰でもボットをプロンプトできます。 +リスクを減らすには、そのチャネルで使えるツールを制限してください。 + +### チャネル内の全員に同じツールを適用する + +```json5 +{ + channels: { + irc: { + groups: { + "#tuirc-dev": { + allowFrom: ["*"], + tools: { + deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"], + }, + }, + }, + }, + }, +} +``` + +### 送信者ごとに異なるツールを適用する（オーナーにはより強い権限を付与） + +`toolsBySender` を使うと、`"*"` にはより厳しいポリシーを適用し、自分のニックにはより緩いポリシーを適用できます。 + +```json5 +{ + channels: { + irc: { + groups: { + "#tuirc-dev": { + allowFrom: ["*"], + toolsBySender: { + "*": { + deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"], + }, + "id:eigen": { + deny: ["gateway", "nodes", "cron"], + }, + }, + }, + }, + }, + }, +} +``` + +注意: + +- `toolsBySender` のキーには、IRC 送信者 ID 値として `id:` を使用してください: + `id:eigen`、またはより強い一致には `id:eigen!~eigen@174.127.248.171` を使います。 +- 従来の接頭辞なしキーも引き続き受け付けられますが、`id:` としてのみ一致します。 +- 最初に一致した送信者ポリシーが優先され、`"*"` はワイルドカードのフォールバックです。 + +グループアクセスとメンションゲート（およびそれらの相互作用）の詳細は、[/channels/groups](/channels/groups)を参照してください。 + +## NickServ + +接続後に NickServ で認証するには: + +```json5 +{ + channels: { + irc: { + nickserv: { + enabled: true, + service: "NickServ", + password: "your-nickserv-password", + }, + }, + }, +} +``` + +接続時の任意の 1 回限りの登録: + +```json5 +{ + channels: { + irc: { + nickserv: { + register: true, + registerEmail: "bot@example.com", + }, + }, + }, +} +``` + +ニックネームの登録後は、`register` を無効にして、`REGISTER` の繰り返し試行を避けてください。 + +## 環境変数 + +既定のアカウントで次をサポートします。 + +- `IRC_HOST` +- `IRC_PORT` +- `IRC_TLS` +- `IRC_NICK` +- `IRC_USERNAME` +- `IRC_REALNAME` +- `IRC_PASSWORD` +- `IRC_CHANNELS`（カンマ区切り） +- `IRC_NICKSERV_PASSWORD` +- `IRC_NICKSERV_REGISTER_EMAIL` + +## トラブルシューティング + +- ボットは接続するのにチャネルでまったく返信しない場合は、`channels.irc.groups` **と** メンションゲートによってメッセージが落とされていないか（`missing-mention`）を確認してください。ping なしで返信させたい場合は、そのチャネルに `requireMention:false` を設定します。 +- ログインに失敗する場合は、ニックネームの利用可否とサーバーパスワードを確認してください。 +- カスタムネットワークで TLS に失敗する場合は、ホスト/ポートと証明書設定を確認してください。 + +## 関連 + +- [チャネル概要](/channels) — サポートされているすべてのチャネル +- [ペアリング](/channels/pairing) — DM 認証とペアリングフロー +- [グループ](/channels/groups) — グループチャットの動作とメンションゲート +- [チャネルルーティング](/channels/channel-routing) — メッセージのセッションルーティング +- [セキュリティ](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/line.md b/docs/ja-JP/channels/line.md new file mode 100644 index 000000000..d74610208 --- /dev/null +++ b/docs/ja-JP/channels/line.md @@ -0,0 +1,231 @@ +--- +read_when: + - OpenClaw を LINE に接続したいとき + - LINE webhook と認証情報のセットアップが必要なとき + - LINE 固有のメッセージオプションを使いたいとき +summary: LINE Messaging API プラグインのセットアップ、設定、および使用方法 +title: LINE +x-i18n: + generated_at: "2026-04-05T12:35:39Z" + model: gpt-5.4 + provider: openai + source_hash: b4782b2aa3e8654505d7f1fd6fc112adf125b5010fc84d655d033688ded37414 + source_path: channels/line.md + workflow: 15 +--- + +# LINE + +LINE は LINE Messaging API を介して OpenClaw に接続します。このプラグインは gateway 上で webhook +レシーバーとして動作し、認証には Channel access token と Channel secret を使用します。 + +ステータス: バンドル済みプラグイン。ダイレクトメッセージ、グループチャット、メディア、位置情報、Flex +メッセージ、template message、quick reply をサポートしています。reaction と thread +はサポートされていません。 + +## バンドル済みプラグイン + +LINE は現在の OpenClaw リリースではバンドル済みプラグインとして提供されているため、通常の +パッケージ版ビルドでは個別のインストールは不要です。 + +古いビルド、または LINE を含まないカスタムインストールを使っている場合は、手動で +インストールしてください。 + +```bash +openclaw plugins install @openclaw/line +``` + +ローカルチェックアウト（git リポジトリから実行している場合）: + +```bash +openclaw plugins install ./path/to/local/line-plugin +``` + +## セットアップ + +1. LINE Developers アカウントを作成し、Console を開きます: + [https://developers.line.biz/console/](https://developers.line.biz/console/) +2. Provider を作成（または選択）し、**Messaging API** チャネルを追加します。 +3. チャネル設定から **Channel access token** と **Channel secret** をコピーします。 +4. Messaging API 設定で **Use webhook** を有効にします。 +5. webhook URL を gateway エンドポイントに設定します（HTTPS 必須）: + +``` +https://gateway-host/line/webhook +``` + +gateway は LINE の webhook 検証（GET）および受信イベント（POST）に応答します。 +カスタムパスが必要な場合は、`channels.line.webhookPath` または +`channels.line.accounts..webhookPath` を設定し、それに合わせて URL を更新してください。 + +セキュリティに関する注意: + +- LINE の署名検証は body に依存します（生の body に対する HMAC）ので、OpenClaw は検証前に厳格な事前認証 body 制限とタイムアウトを適用します。 +- OpenClaw は、検証済みの生リクエストバイト列から webhook イベントを処理します。署名整合性の安全性のため、上流 middleware により変換された `req.body` の値は無視されます。 + +## 設定 + +最小構成: + +```json5 +{ + channels: { + line: { + enabled: true, + channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN", + channelSecret: "LINE_CHANNEL_SECRET", + dmPolicy: "pairing", + }, + }, +} +``` + +環境変数（デフォルトアカウントのみ）: + +- `LINE_CHANNEL_ACCESS_TOKEN` +- `LINE_CHANNEL_SECRET` + +token/secret ファイル: + +```json5 +{ + channels: { + line: { + tokenFile: "/path/to/line-token.txt", + secretFile: "/path/to/line-secret.txt", + }, + }, +} +``` + +`tokenFile` と `secretFile` は通常ファイルを指している必要があります。symlink は拒否されます。 + +複数アカウント: + +```json5 +{ + channels: { + line: { + accounts: { + marketing: { + channelAccessToken: "...", + channelSecret: "...", + webhookPath: "/line/marketing", + }, + }, + }, + }, +} +``` + +## アクセス制御 + +ダイレクトメッセージはデフォルトで pairing です。未知の送信者には pairing code が送られ、 +承認されるまでそのメッセージは無視されます。 + +```bash +openclaw pairing list line +openclaw pairing approve line +``` + +allowlist とポリシー: + +- `channels.line.dmPolicy`: `pairing | allowlist | open | disabled` +- `channels.line.allowFrom`: DM 用に allowlist された LINE user ID +- `channels.line.groupPolicy`: `allowlist | open | disabled` +- `channels.line.groupAllowFrom`: グループ用に allowlist された LINE user ID +- グループごとの上書き: `channels.line.groups..allowFrom` +- ランタイムに関する注意: `channels.line` が完全に存在しない場合、グループチェックではランタイムが `groupPolicy="allowlist"` にフォールバックします（`channels.defaults.groupPolicy` が設定されていても同様）。 + +LINE ID は大文字小文字を区別します。有効な ID の形式は次のとおりです。 + +- ユーザー: `U` + 32 桁の 16 進文字 +- グループ: `C` + 32 桁の 16 進文字 +- ルーム: `R` + 32 桁の 16 進文字 + +## メッセージ動作 + +- テキストは 5000 文字ごとに分割されます。 +- Markdown の書式は除去されます。code block と table は可能な場合 Flex + card に変換されます。 +- ストリーミング応答はバッファされます。エージェントの処理中、LINE には loading + animation とともに完全なチャンクが送信されます。 +- メディアのダウンロードは `channels.line.mediaMaxMb`（デフォルト 10）で上限が設定されます。 + +## チャネルデータ（リッチメッセージ） + +`channelData.line` を使うと、quick reply、位置情報、Flex card、template +message を送信できます。 + +```json5 +{ + text: "Here you go", + channelData: { + line: { + quickReplies: ["Status", "Help"], + location: { + title: "Office", + address: "123 Main St", + latitude: 35.681236, + longitude: 139.767125, + }, + flexMessage: { + altText: "Status card", + contents: { + /* Flex payload */ + }, + }, + templateMessage: { + type: "confirm", + text: "Proceed?", + confirmLabel: "Yes", + confirmData: "yes", + cancelLabel: "No", + cancelData: "no", + }, + }, + }, +} +``` + +LINE プラグインには、Flex message プリセット用の `/card` コマンドも含まれています。 + +``` +/card info "Welcome" "Thanks for joining!" +``` + +## ACP サポート + +LINE は ACP（Agent Communication Protocol）の会話バインディングをサポートします。 + +- `/acp spawn --bind here` は、子 thread を作成せずに現在の LINE チャットを ACP セッションにバインドします。 +- 設定済みの ACP バインディングと、会話にバインドされたアクティブな ACP セッションは、他の会話チャネルと同様に LINE 上で動作します。 + +詳細は [ACP agents](/tools/acp-agents) を参照してください。 + +## 送信メディア + +LINE プラグインは、agent message tool を通じた画像、動画、音声ファイルの送信をサポートしています。メディアは、適切なプレビューおよびトラッキング処理を伴う LINE 固有の配信経路を通じて送信されます。 + +- **画像**: 自動プレビュー生成付きの LINE 画像メッセージとして送信されます。 +- **動画**: 明示的なプレビューおよび content-type 処理付きで送信されます。 +- **音声**: LINE 音声メッセージとして送信されます。 + +汎用メディア送信では、LINE 固有の経路が利用できない場合、既存の画像専用経路にフォールバックします。 + +## トラブルシューティング + +- **webhook 検証に失敗する:** webhook URL が HTTPS であり、 + `channelSecret` が LINE Console の値と一致していることを確認してください。 +- **受信イベントが来ない:** webhook path が `channels.line.webhookPath` + と一致しており、gateway に LINE から到達可能であることを確認してください。 +- **メディアダウンロードエラー:** メディアがデフォルト制限を超える場合は + `channels.line.mediaMaxMb` を引き上げてください。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャネル +- [Pairing](/channels/pairing) — DM 認証と pairing フロー +- [Groups](/channels/groups) — グループチャットの動作と mention ゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/location.md b/docs/ja-JP/channels/location.md new file mode 100644 index 000000000..0281ba305 --- /dev/null +++ b/docs/ja-JP/channels/location.md @@ -0,0 +1,63 @@ +--- +read_when: + - チャネル位置情報解析を追加または変更するとき + - エージェントプロンプトやツールで位置情報コンテキストフィールドを使用するとき +summary: 受信チャネルの位置情報解析（Telegram/WhatsApp/Matrix）とコンテキストフィールド +title: チャネル位置情報解析 +x-i18n: + generated_at: "2026-04-05T12:35:25Z" + model: gpt-5.4 + provider: openai + source_hash: 10061f0c109240a9e0bcab649b17f03b674e8bdf410debf3669b7b6da8189d96 + source_path: channels/location.md + workflow: 15 +--- + +# チャネル位置情報解析 + +OpenClaw は、チャットチャネルから共有された位置情報を次の形式に正規化します。 + +- 受信本文に追加される人間が読みやすいテキスト +- 自動返信コンテキストペイロード内の構造化フィールド + +現在サポートされているもの: + +- **Telegram**（位置ピン + venue + live location） +- **WhatsApp**（`locationMessage` + `liveLocationMessage`） +- **Matrix**（`geo_uri` を持つ `m.location`） + +## テキスト形式 + +位置情報は、角括弧なしの読みやすい行としてレンダリングされます。 + +- ピン: + - `📍 48.858844, 2.294351 ±12m` +- 名前付きの場所: + - `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)` +- ライブ共有: + - `🛰 ライブ位置情報: 48.858844, 2.294351 ±12m` + +チャネルにキャプション / コメントが含まれている場合は、次の行に追加されます。 + +``` +📍 48.858844, 2.294351 ±12m +ここで会いましょう +``` + +## コンテキストフィールド + +位置情報がある場合、これらのフィールドが `ctx` に追加されます。 + +- `LocationLat`（数値） +- `LocationLon`（数値） +- `LocationAccuracy`（数値、メートル; 任意） +- `LocationName`（文字列; 任意） +- `LocationAddress`（文字列; 任意） +- `LocationSource`（`pin | place | live`） +- `LocationIsLive`（真偽値） + +## チャネルごとの注意点 + +- **Telegram**: venue は `LocationName/LocationAddress` に対応し、live location は `live_period` を使用します。 +- **WhatsApp**: `locationMessage.comment` と `liveLocationMessage.caption` はキャプション行として追加されます。 +- **Matrix**: `geo_uri` はピン位置情報として解析され、高度は無視され、`LocationIsLive` は常に false です。 diff --git a/docs/ja-JP/channels/matrix.md b/docs/ja-JP/channels/matrix.md new file mode 100644 index 000000000..aa50c46f6 --- /dev/null +++ b/docs/ja-JP/channels/matrix.md @@ -0,0 +1,870 @@ +--- +read_when: + - OpenClaw で Matrix をセットアップするとき + - Matrix の E2EE と検証を設定するとき +summary: Matrix のサポート状況、セットアップ、設定例 +title: Matrix +x-i18n: + generated_at: "2026-04-05T12:38:02Z" + model: gpt-5.4 + provider: openai + source_hash: ba5c49ad2125d97adf66b5517f8409567eff8b86e20224a32fcb940a02cb0659 + source_path: channels/matrix.md + workflow: 15 +--- + +# Matrix + +Matrix は OpenClaw 用の Matrix バンドル済みチャネルプラグインです。 +公式の `matrix-js-sdk` を使用し、DM、ルーム、スレッド、メディア、リアクション、投票、位置情報、E2EE をサポートします。 + +## バンドル済みプラグイン + +Matrix は現在の OpenClaw リリースではバンドル済みプラグインとして提供されるため、通常の +パッケージ済みビルドでは別途インストールは不要です。 + +古いビルド、または Matrix を含まないカスタムインストールを使用している場合は、手動で +インストールしてください。 + +npm からインストール: + +```bash +openclaw plugins install @openclaw/matrix +``` + +ローカルチェックアウトからインストール: + +```bash +openclaw plugins install ./path/to/local/matrix-plugin +``` + +プラグインの動作とインストールルールについては [Plugins](/tools/plugin) を参照してください。 + +## セットアップ + +1. Matrix プラグインが利用可能であることを確認します。 + - 現在のパッケージ済み OpenClaw リリースにはすでに同梱されています。 + - 古い / カスタムインストールでは、上記のコマンドで手動追加できます。 +2. homeserver 上で Matrix アカウントを作成します。 +3. `channels.matrix` を以下のいずれかで設定します。 + - `homeserver` + `accessToken` + - `homeserver` + `userId` + `password` +4. Gateway を再起動します。 +5. ボットとの DM を開始するか、ルームに招待します。 + +対話型セットアップ手順: + +```bash +openclaw channels add +openclaw configure --section channels +``` + +Matrix ウィザードが実際に尋ねる内容: + +- homeserver URL +- 認証方式: アクセストークンまたはパスワード +- パスワード認証を選んだ場合のみユーザー ID +- 任意のデバイス名 +- E2EE を有効にするかどうか +- Matrix ルームアクセスを今すぐ設定するかどうか + +重要なウィザードの挙動: + +- 選択したアカウントに対応する Matrix 認証環境変数がすでに存在し、そのアカウントの認証情報がまだ config に保存されていない場合、ウィザードは環境変数ショートカットを提示し、そのアカウントには `enabled: true` だけを書き込みます。 +- 別の Matrix アカウントを対話的に追加すると、入力したアカウント名は config と env vars で使われるアカウント ID に正規化されます。たとえば、`Ops Bot` は `ops-bot` になります。 +- DM allowlist のプロンプトでは、完全な `@user:server` 値をそのまま受け付けます。表示名が使えるのは、ライブディレクトリ参照で 1 件だけ完全一致した場合のみです。それ以外では、完全な Matrix ID を使って再入力するようウィザードが求めます。 +- ルーム allowlist のプロンプトでは、ルーム ID とエイリアスをそのまま受け付けます。また、参加済みルーム名をライブで解決することもできますが、解決できなかった名前はセットアップ中に入力された文字列のまま保持されるだけで、後でランタイムの allowlist 解決では無視されます。`!room:server` または `#alias:server` を推奨します。 +- ランタイムのルーム / セッション識別には安定した Matrix ルーム ID を使います。ルームに定義されたエイリアスは参照入力としてのみ使われ、長期的なセッションキーや安定したグループ識別子としては使われません。 +- 保存前にルーム名を解決するには、`openclaw channels resolve --channel matrix "Project Room"` を使ってください。 + +トークンベースの最小構成: + +```json5 +{ + channels: { + matrix: { + enabled: true, + homeserver: "https://matrix.example.org", + accessToken: "syt_xxx", + dm: { policy: "pairing" }, + }, + }, +} +``` + +パスワードベースのセットアップ（ログイン後にトークンがキャッシュされます）: + +```json5 +{ + channels: { + matrix: { + enabled: true, + homeserver: "https://matrix.example.org", + userId: "@bot:example.org", + password: "replace-me", // pragma: allowlist secret + deviceName: "OpenClaw Gateway", + }, + }, +} +``` + +Matrix はキャッシュされた認証情報を `~/.openclaw/credentials/matrix/` に保存します。 +デフォルトアカウントは `credentials.json` を使い、名前付きアカウントは `credentials-.json` を使います。 + +対応する環境変数（config キーが設定されていない場合に使用）: + +- `MATRIX_HOMESERVER` +- `MATRIX_ACCESS_TOKEN` +- `MATRIX_USER_ID` +- `MATRIX_PASSWORD` +- `MATRIX_DEVICE_ID` +- `MATRIX_DEVICE_NAME` + +デフォルト以外のアカウントでは、アカウントスコープ付き環境変数を使います。 + +- `MATRIX__HOMESERVER` +- `MATRIX__ACCESS_TOKEN` +- `MATRIX__USER_ID` +- `MATRIX__PASSWORD` +- `MATRIX__DEVICE_ID` +- `MATRIX__DEVICE_NAME` + +アカウント `ops` の例: + +- `MATRIX_OPS_HOMESERVER` +- `MATRIX_OPS_ACCESS_TOKEN` + +正規化されたアカウント ID `ops-bot` では、以下を使います。 + +- `MATRIX_OPS_X2D_BOT_HOMESERVER` +- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` + +Matrix は、アカウント ID 内の記号をエスケープして、スコープ付き env vars の衝突を防ぎます。 +たとえば `-` は `_X2D_` になるため、`ops-prod` は `MATRIX_OPS_X2D_PROD_*` に対応します。 + +対話型ウィザードは、それらの認証環境変数がすでに存在し、かつ選択されたアカウントに Matrix 認証がまだ config に保存されていない場合にのみ、env-var ショートカットを提示します。 + +## 設定例 + +これは DM ペアリング、ルーム allowlist、E2EE 有効化を含む実用的なベースライン設定です。 + +```json5 +{ + channels: { + matrix: { + enabled: true, + homeserver: "https://matrix.example.org", + accessToken: "syt_xxx", + encryption: true, + + dm: { + policy: "pairing", + threadReplies: "off", + }, + + groupPolicy: "allowlist", + groupAllowFrom: ["@admin:example.org"], + groups: { + "!roomid:example.org": { + requireMention: true, + }, + }, + + autoJoin: "allowlist", + autoJoinAllowlist: ["!roomid:example.org"], + threadReplies: "inbound", + replyToMode: "off", + streaming: "partial", + }, + }, +} +``` + +## ストリーミングプレビュー + +Matrix の返信ストリーミングはオプトインです。 + +`channels.matrix.streaming` を `"partial"` に設定すると、OpenClaw は 1 つの下書き返信を送信し、 +モデルがテキストを生成している間はその下書きをその場で編集し、返信が +完了したら最終化します。 + +```json5 +{ + channels: { + matrix: { + streaming: "partial", + }, + }, +} +``` + +- `streaming: "off"` がデフォルトです。OpenClaw は最終返信を待って 1 回だけ送信します。 +- `streaming: "partial"` は、複数の部分メッセージを送る代わりに、現在の assistant ブロック用の編集可能なプレビューメッセージを 1 つ作成します。 +- `blockStreaming: true` を指定すると、Matrix で別個の進行メッセージを有効にします。`streaming: "partial"` と組み合わせると、Matrix は現在のブロック用のライブ下書きを維持しつつ、完了済みブロックを別メッセージとして残します。 +- `streaming: "partial"` かつ `blockStreaming` がオフの場合、Matrix はライブ下書きだけを編集し、そのブロックまたはターンが終了した時点で完了済み返信を 1 回送信します。 +- プレビューが 1 つの Matrix イベントに収まらなくなった場合、OpenClaw はプレビューのストリーミングを停止し、通常の最終配信にフォールバックします。 +- メディア返信は通常どおり添付ファイルを送信します。古いプレビューを安全に再利用できなくなった場合、OpenClaw は最終メディア返信を送る前にそれを redact します。 +- プレビュー編集には追加の Matrix API 呼び出しが必要です。もっとも保守的なレート制限挙動を望む場合は、ストリーミングをオフのままにしてください。 + +`blockStreaming` だけでは下書きプレビューは有効になりません。 +プレビュー編集には `streaming: "partial"` を使い、完了した assistant ブロックも別々の進行メッセージとして見せたい場合にのみ、さらに `blockStreaming: true` を追加してください。 + +## 暗号化と検証 + +暗号化された（E2EE）ルームでは、送信画像イベントは `thumbnail_file` を使用するため、画像プレビューは完全な添付ファイルと一緒に暗号化されます。暗号化されていないルームでは引き続き通常の `thumbnail_url` を使います。設定は不要です。プラグインが E2EE 状態を自動検出します。 + +### Bot 間ルーム + +デフォルトでは、他の設定済み OpenClaw Matrix アカウントからの Matrix メッセージは無視されます。 + +エージェント間 Matrix トラフィックを意図的に許可したい場合は `allowBots` を使ってください。 + +```json5 +{ + channels: { + matrix: { + allowBots: "mentions", // true | "mentions" + groups: { + "!roomid:example.org": { + requireMention: true, + }, + }, + }, + }, +} +``` + +- `allowBots: true` は、許可されたルームおよび DM 内で、他の設定済み Matrix bot アカウントからのメッセージを受け入れます。 +- `allowBots: "mentions"` は、ルーム内ではそのようなメッセージがこの bot に明示的にメンションしている場合にのみ受け入れます。DM は引き続き許可されます。 +- `groups..allowBots` は、1 つのルームに対してアカウントレベル設定を上書きします。 +- OpenClaw は自己返信ループを避けるため、同じ Matrix user ID からのメッセージは引き続き無視します。 +- Matrix にはここで使えるネイティブの bot フラグはありません。OpenClaw は「bot-authored」を「この OpenClaw Gateway 上の別の設定済み Matrix アカウントによって送信されたもの」として扱います。 + +共有ルームで bot 間トラフィックを有効にする場合は、厳格なルーム allowlist とメンション要件を使ってください。 + +暗号化を有効にするには: + +```json5 +{ + channels: { + matrix: { + enabled: true, + homeserver: "https://matrix.example.org", + accessToken: "syt_xxx", + encryption: true, + dm: { policy: "pairing" }, + }, + }, +} +``` + +検証状態を確認: + +```bash +openclaw matrix verify status +``` + +詳細ステータス（完全な診断）: + +```bash +openclaw matrix verify status --verbose +``` + +保存済み recovery key を機械可読出力に含める: + +```bash +openclaw matrix verify status --include-recovery-key --json +``` + +クロスサイニングと検証状態を bootstrap する: + +```bash +openclaw matrix verify bootstrap +``` + +マルチアカウント対応: `channels.matrix.accounts` を使用し、アカウントごとの認証情報と任意の `name` を設定します。共通パターンについては [Configuration reference](/gateway/configuration-reference#multi-account-all-channels) を参照してください。 + +bootstrap の詳細診断: + +```bash +openclaw matrix verify bootstrap --verbose +``` + +bootstrap 前に新しいクロスサイニング ID を強制的にリセットする: + +```bash +openclaw matrix verify bootstrap --force-reset-cross-signing +``` + +recovery key でこのデバイスを検証する: + +```bash +openclaw matrix verify device "" +``` + +デバイス検証の詳細: + +```bash +openclaw matrix verify device "" --verbose +``` + +ルームキーバックアップの健全性を確認: + +```bash +openclaw matrix verify backup status +``` + +バックアップ健全性の詳細診断: + +```bash +openclaw matrix verify backup status --verbose +``` + +サーバーバックアップからルームキーを復元: + +```bash +openclaw matrix verify backup restore +``` + +復元の詳細診断: + +```bash +openclaw matrix verify backup restore --verbose +``` + +現在のサーバーバックアップを削除し、新しいバックアップベースラインを作成します。保存済みの +バックアップキーを正常に読み込めない場合、このリセットは secret storage も再作成し、 +将来のコールドスタートで新しいバックアップキーを読み込めるようにすることがあります。 + +```bash +openclaw matrix verify backup reset --yes +``` + +すべての `verify` コマンドはデフォルトで簡潔な出力です（内部 SDK ログも quiet を含む）であり、詳細診断は `--verbose` を付けた場合のみ表示されます。 +スクリプトで使う場合は、完全な機械可読出力のために `--json` を使ってください。 + +マルチアカウント構成では、`--account ` を渡さない限り、Matrix CLI コマンドは暗黙の Matrix デフォルトアカウントを使います。 +複数の名前付きアカウントを設定している場合、まず `channels.matrix.defaultAccount` を設定してください。そうしないと、そのような暗黙の CLI 操作は停止してアカウントを明示選択するよう求めます。 +検証やデバイス操作を明示的に名前付きアカウントに向けたい場合は、`--account` を使ってください。 + +```bash +openclaw matrix verify status --account assistant +openclaw matrix verify backup restore --account assistant +openclaw matrix devices list --account assistant +``` + +名前付きアカウントで暗号化が無効または利用不可の場合、Matrix の警告と検証エラーは、そのアカウントの config キー、たとえば `channels.matrix.accounts.assistant.encryption` を指します。 + +### 「verified」の意味 + +OpenClaw は、この Matrix デバイスが自分自身のクロスサイニング ID によって検証されている場合にのみ、verified として扱います。 +実際には、`openclaw matrix verify status --verbose` は 3 つの信頼シグナルを表示します。 + +- `Locally trusted`: このデバイスは現在のクライアントでのみ信頼されています +- `Cross-signing verified`: SDK が、このデバイスがクロスサイニングによって検証されたと報告しています +- `Signed by owner`: このデバイスが自分自身の self-signing key によって署名されています + +`Verified by owner` は、クロスサイニング検証または owner-signing がある場合にのみ `yes` になります。 +ローカル信頼だけでは、OpenClaw はそのデバイスを完全に検証済みとは扱いません。 + +### bootstrap が行うこと + +`openclaw matrix verify bootstrap` は、暗号化された Matrix アカウントの修復とセットアップを行うコマンドです。 +以下を順番に実行します。 + +- 可能であれば既存の recovery key を再利用しながら secret storage を bootstrap +- クロスサイニングを bootstrap し、不足している公開クロスサイニングキーをアップロード +- 現在のデバイスにマークを付け、クロスサインすることを試行 +- サーバー側のルームキーバックアップがまだ存在しない場合は新規作成 + +homeserver がクロスサイニングキーのアップロードに対話的認証を要求する場合、OpenClaw はまず認証なしでアップロードを試し、その後 `m.login.dummy`、さらに `channels.matrix.password` が設定されている場合は `m.login.password` を試します。 + +現在のクロスサイニング ID を破棄して新しく作り直したい場合にのみ、`--force-reset-cross-signing` を使ってください。 + +現在のルームキーバックアップを意図的に破棄し、今後のメッセージ向けに新しい +バックアップベースラインを開始したい場合は、`openclaw matrix verify backup reset --yes` を使ってください。 +これは、復元不能な古い暗号化履歴が引き続き利用不可のままになることと、 +現在のバックアップ secret を安全に読み込めない場合に OpenClaw が secret storage を再作成する可能性があることを受け入れる場合にのみ実行してください。 + +### 新しいバックアップベースライン + +今後の暗号化メッセージを正常に保ちつつ、復元不能な古い履歴を失うことを受け入れる場合は、以下のコマンドを順に実行してください。 + +```bash +openclaw matrix verify backup reset --yes +openclaw matrix verify backup status --verbose +openclaw matrix verify status +``` + +特定の名前付き Matrix アカウントを明示的に対象にしたい場合は、各コマンドに `--account ` を追加してください。 + +### 起動時の挙動 + +`encryption: true` の場合、Matrix は `startupVerification` のデフォルトを `"if-unverified"` にします。 +起動時、このデバイスがまだ未検証であれば、Matrix は別の Matrix クライアントで自己検証を要求し、 +すでに保留中の要求がある間は重複要求をスキップし、再起動後の再試行前にローカルクールダウンを適用します。 +要求作成に成功した場合よりも、要求試行の失敗のほうがデフォルトでは早く再試行されます。 +起動時の自動要求を無効にするには `startupVerification: "off"` を設定するか、より短い / 長い再試行間隔が必要な場合は `startupVerificationCooldownHours` +を調整してください。 + +起動時には保守的な crypto bootstrap パスも自動実行されます。 +このパスはまず現在の secret storage とクロスサイニング ID の再利用を試み、明示的な bootstrap 修復フローを実行しない限りクロスサイニングのリセットを避けます。 + +起動時に壊れた bootstrap 状態が見つかり、`channels.matrix.password` が設定されている場合、OpenClaw はより厳格な修復パスを試行できます。 +現在のデバイスがすでに owner-signed であれば、OpenClaw はそれを自動リセットせず、その ID を保持します。 + +以前の公開 Matrix プラグインからのアップグレード: + +- OpenClaw は、可能であれば同じ Matrix アカウント、アクセストークン、デバイス ID を自動で再利用します。 +- 実行可能な Matrix 移行変更が走る前に、OpenClaw は `~/Backups/openclaw-migrations/` 配下に recovery snapshot を作成または再利用します。 +- 複数の Matrix アカウントを使っている場合、古いフラットストア構成からアップグレードする前に `channels.matrix.defaultAccount` を設定してください。これにより、その共有されたレガシー状態をどのアカウントが受け取るべきか OpenClaw が判断できます。 +- 以前のプラグインが Matrix のルームキーバックアップ復号キーをローカル保存していた場合、起動時または `openclaw doctor --fix` がそれを新しい recovery-key フローへ自動インポートします。 +- 移行準備後に Matrix アクセストークンが変更された場合、起動時は自動バックアップ復元を諦める前に、保留中のレガシー復元状態を探すために兄弟のトークンハッシュ保存ルートをスキャンします。 +- 同じアカウント、homeserver、ユーザーに対して後で Matrix アクセストークンが変わった場合、OpenClaw は空の Matrix 状態ディレクトリから始めるのではなく、もっとも完全な既存のトークンハッシュ保存ルートの再利用を優先します。 +- 次回 Gateway 起動時に、バックアップされたルームキーが新しい crypto store へ自動復元されます。 +- 古いプラグインにローカル専用で未バックアップのルームキーがあった場合、OpenClaw は明確に警告します。それらのキーは以前の rust crypto store から自動エクスポートできないため、一部の古い暗号化履歴は手動回復されるまで利用不可のままになる可能性があります。 +- 完全なアップグレード手順、制限、回復コマンド、一般的な移行メッセージについては [Matrix migration](/install/migrating-matrix) を参照してください。 + +暗号化されたランタイム状態は、アカウントごと、ユーザーごと、トークンハッシュごとのルートとして +`~/.openclaw/matrix/accounts//__//` +配下に整理されます。 +そのディレクトリには、sync store（`bot-storage.json`）、crypto store（`crypto/`）、 +recovery key ファイル（`recovery-key.json`）、IndexedDB スナップショット（`crypto-idb-snapshot.json`）、 +thread bindings（`thread-bindings.json`）、起動時検証状態（`startup-verification.json`） +が、それらの機能使用時に含まれます。 +トークンが変わってもアカウント ID が同じであれば、OpenClaw はそのアカウント / homeserver / ユーザー組み合わせに対して最良の既存 +ルートを再利用するため、以前の sync 状態、crypto 状態、thread bindings、 +起動時検証状態はそのまま見える状態で保たれます。 + +### Node crypto store モデル + +このプラグインの Matrix E2EE は、Node 上で公式 `matrix-js-sdk` の Rust crypto パスを使います。 +このパスでは、crypto 状態を再起動後も保持したい場合、IndexedDB ベースの永続化が必要です。 + +OpenClaw は現在、Node 上でこれを以下の方法で提供しています。 + +- SDK が期待する IndexedDB API shim として `fake-indexeddb` を使用 +- `initRustCrypto` の前に `crypto-idb-snapshot.json` から Rust crypto IndexedDB の内容を復元 +- init 後およびランタイム中に、更新された IndexedDB 内容を `crypto-idb-snapshot.json` へ永続化 +- Gateway ランタイムの永続化と CLI メンテナンスが同じスナップショットファイル上で競合しないよう、advisory file lock を使って `crypto-idb-snapshot.json` に対するスナップショット復元と永続化を直列化 + +これは互換性 / ストレージの配線であり、独自の crypto 実装ではありません。 +このスナップショットファイルは機微なランタイム状態であり、制限的なファイル権限で保存されます。 +OpenClaw のセキュリティモデルでは、Gateway ホストとローカル OpenClaw 状態ディレクトリはすでに信頼されたオペレーター境界の内側にあるため、これは主に別個のリモート信頼境界ではなく運用上の耐久性の問題です。 + +予定されている改善: + +- 永続的な Matrix キーマテリアルに対する SecretRef サポートを追加し、recovery key や関連する store 暗号化シークレットを、ローカルファイルだけでなく OpenClaw シークレットプロバイダーから供給できるようにする + +## プロフィール管理 + +選択したアカウントの Matrix 自己プロフィールを更新するには、以下を使用します。 + +```bash +openclaw matrix profile set --name "OpenClaw Assistant" +openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png +``` + +明示的に名前付きアカウントを対象にしたい場合は `--account ` を追加してください。 + +Matrix は `mxc://` アバター URL を直接受け付けます。`http://` または `https://` のアバター URL を渡した場合、OpenClaw はまずそれを Matrix にアップロードし、解決済みの `mxc://` URL を `channels.matrix.avatarUrl`（または選択したアカウントの上書き設定）に保存します。 + +## 自動検証通知 + +Matrix は現在、検証ライフサイクル通知を厳格な DM 検証ルームへ `m.notice` メッセージとして直接投稿します。 +これには以下が含まれます。 + +- 検証要求通知 +- 検証準備完了通知（明示的な「絵文字で検証」ガイダンス付き） +- 検証開始および完了通知 +- 利用可能な場合の SAS 詳細（絵文字と 10 進数） + +別の Matrix クライアントからの受信検証要求は OpenClaw によって追跡され、自動承認されます。 +自己検証フローでは、OpenClaw は絵文字検証が利用可能になると自動で SAS フローも開始し、自分側を確認します。 +別の Matrix ユーザー / デバイスからの検証要求では、OpenClaw は要求を自動承認したうえで、SAS フローが通常どおり進むのを待ちます。 +検証を完了するには、引き続き Matrix クライアント側で絵文字または 10 進 SAS を比較し、「一致する」を確認する必要があります。 + +OpenClaw は、自分で開始した重複フローを無条件に自動承認しません。起動時は、自己検証要求がすでに保留中であれば新規要求の作成をスキップします。 + +検証プロトコル / システム通知はエージェントチャットパイプラインには転送されないため、`NO_REPLY` は生成されません。 + +### デバイス衛生 + +OpenClaw が管理する古い Matrix デバイスがアカウントに蓄積し、暗号化ルームの信頼性が把握しにくくなることがあります。 +一覧表示するには: + +```bash +openclaw matrix devices list +``` + +古い OpenClaw 管理デバイスを削除するには: + +```bash +openclaw matrix devices prune-stale +``` + +### ダイレクトルーム修復 + +ダイレクトメッセージ状態の同期が崩れると、OpenClaw に古い 1 対 1 ルームを指す古い `m.direct` マッピングが残り、ライブ DM を指さなくなることがあります。特定の peer に対する現在のマッピングを確認するには: + +```bash +openclaw matrix direct inspect --user-id @alice:example.org +``` + +修復するには: + +```bash +openclaw matrix direct repair --user-id @alice:example.org +``` + +修復では Matrix 固有ロジックをプラグイン内に閉じ込めています。 + +- まず `m.direct` にすでにマッピングされている厳密な 1:1 DM を優先します +- それがなければ、そのユーザーとの現在参加中の厳密な 1:1 DM にフォールバックします +- 健全な DM が存在しなければ、新しいダイレクトルームを作成し、`m.direct` を書き換えてそこを指すようにします + +修復フローは古いルームを自動削除しません。健全な DM を選択し、マッピングを更新して、新しい Matrix 送信、検証通知、その他のダイレクトメッセージフローが再び正しいルームを対象にするようにするだけです。 + +## スレッド + +Matrix は、自動返信とメッセージツール送信の両方でネイティブ Matrix スレッドをサポートします。 + +- `threadReplies: "off"` は返信をトップレベルに維持し、受信したスレッド付きメッセージも親セッション上に維持します。 +- `threadReplies: "inbound"` は、受信メッセージがすでにそのスレッド内にあった場合にのみ、そのスレッド内で返信します。 +- `threadReplies: "always"` は、ルーム返信をトリガーメッセージをルートとするスレッド内に保持し、その会話を最初のトリガーメッセージから対応するスレッドスコープのセッションにルーティングします。 +- `dm.threadReplies` は DM 専用でトップレベル設定を上書きします。たとえば、ルームスレッドは分離したまま、DM はフラットに保つことができます。 +- 受信スレッドメッセージには、追加のエージェントコンテキストとしてスレッドルートメッセージが含まれます。 +- メッセージツール送信は、ターゲットが同じルームまたは同じ DM ユーザーターゲットであれば、明示的な `threadId` が指定されない限り、現在の Matrix スレッドを自動継承するようになりました。 +- Matrix ではランタイム thread bindings がサポートされます。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびスレッドにバインドされた `/acp spawn` が Matrix ルームと DM で動作するようになりました。 +- トップレベルの Matrix ルーム / DM で `/focus` を実行すると、`threadBindings.spawnSubagentSessions=true` の場合、新しい Matrix スレッドを作成し、それを対象セッションへバインドします。 +- 既存の Matrix スレッド内で `/focus` または `/acp spawn --thread here` を実行した場合は、その現在のスレッドが代わりにバインドされます。 + +## ACP 会話バインディング + +Matrix のルーム、DM、既存の Matrix スレッドは、チャット画面を変えずに永続的な ACP ワークスペースへ変換できます。 + +すばやいオペレーターフロー: + +- 使い続けたい Matrix DM、ルーム、または既存スレッド内で `/acp spawn codex --bind here` を実行します。 +- トップレベルの Matrix DM またはルームでは、現在の DM / ルームがそのままチャット画面として維持され、今後のメッセージは起動された ACP セッションへルーティングされます。 +- 既存の Matrix スレッド内では、`--bind here` はその現在のスレッドをその場でバインドします。 +- `/new` と `/reset` は、同じバインド済み ACP セッションをその場でリセットします。 +- `/acp close` は ACP セッションを閉じ、バインディングを削除します。 + +注意: + +- `--bind here` は子 Matrix スレッドを作成しません。 +- `threadBindings.spawnAcpSessions` は、OpenClaw が子 Matrix スレッドを作成またはバインドする必要がある `/acp spawn --thread auto|here` の場合にのみ必要です。 + +### スレッドバインディング設定 + +Matrix は `session.threadBindings` からグローバルデフォルトを継承し、チャネルごとの上書きもサポートします。 + +- `threadBindings.enabled` +- `threadBindings.idleHours` +- `threadBindings.maxAgeHours` +- `threadBindings.spawnSubagentSessions` +- `threadBindings.spawnAcpSessions` + +Matrix のスレッドバインド付き spawn フラグはオプトインです。 + +- トップレベルの `/focus` が新しい Matrix スレッドを作成してバインドできるようにするには、`threadBindings.spawnSubagentSessions: true` を設定します。 +- `/acp spawn --thread auto|here` が ACP セッションを Matrix スレッドへバインドできるようにするには、`threadBindings.spawnAcpSessions: true` を設定します。 + +## リアクション + +Matrix は、送信リアクションアクション、受信リアクション通知、受信 ack リアクションをサポートします。 + +- 送信リアクションツールは `channels["matrix"].actions.reactions` によって制御されます。 +- `react` は特定の Matrix イベントにリアクションを追加します。 +- `reactions` は特定の Matrix イベントに対する現在のリアクション要約を一覧表示します。 +- `emoji=""` は、そのイベント上の bot アカウント自身のリアクションを削除します。 +- `remove: true` は、bot アカウントの指定された絵文字リアクションだけを削除します。 + +ack リアクションは、標準の OpenClaw 解決順序を使います。 + +- `channels["matrix"].accounts..ackReaction` +- `channels["matrix"].ackReaction` +- `messages.ackReaction` +- エージェント ID の絵文字フォールバック + +ack リアクションスコープは次の順で解決されます。 + +- `channels["matrix"].accounts..ackReactionScope` +- `channels["matrix"].ackReactionScope` +- `messages.ackReactionScope` + +リアクション通知モードは次の順で解決されます。 + +- `channels["matrix"].accounts..reactionNotifications` +- `channels["matrix"].reactionNotifications` +- デフォルト: `own` + +現在の挙動: + +- `reactionNotifications: "own"` は、bot-authored の Matrix メッセージを対象にした追加済み `m.reaction` イベントを転送します。 +- `reactionNotifications: "off"` はリアクションシステムイベントを無効にします。 +- リアクション削除は、Matrix では独立した `m.reaction` 削除ではなく redaction として表現されるため、依然としてシステムイベントには合成されません。 + +## 履歴コンテキスト + +- `channels.matrix.historyLimit` は、Matrix ルームメッセージがエージェントをトリガーしたときに `InboundHistory` として含める最近のルームメッセージ数を制御します。 +- これは `messages.groupChat.historyLimit` にフォールバックします。無効にするには `0` を設定します。 +- Matrix ルーム履歴はルーム専用です。DM は通常のセッション履歴を使い続けます。 +- Matrix ルーム履歴は pending-only です。OpenClaw はまだ返信をトリガーしていないルームメッセージをバッファし、メンションやその他のトリガーが到着したときにそのウィンドウをスナップショットします。 +- 現在のトリガーメッセージは `InboundHistory` には含まれず、そのターンのメイン受信本文に残ります。 +- 同じ Matrix イベントの再試行では、新しいルームメッセージへ前進してずれるのではなく、元の履歴スナップショットが再利用されます。 + +## コンテキスト可視性 + +Matrix は、取得した返信テキスト、スレッドルート、pending 履歴などの補足ルームコンテキストに対して、共通の `contextVisibility` 制御をサポートします。 + +- `contextVisibility: "all"` がデフォルトです。補足コンテキストは受信したまま保持されます。 +- `contextVisibility: "allowlist"` は、補足コンテキストを、現在有効なルーム / ユーザー allowlist チェックで許可された送信者に限定します。 +- `contextVisibility: "allowlist_quote"` は `allowlist` と同様ですが、1 つの明示的な引用返信は保持します。 + +この設定が影響するのは補足コンテキストの可視性であり、受信メッセージ自体が返信をトリガーできるかどうかではありません。 +トリガー認可は引き続き `groupPolicy`、`groups`、`groupAllowFrom`、DM policy 設定から決まります。 + +## DM とルームポリシーの例 + +```json5 +{ + channels: { + matrix: { + dm: { + policy: "allowlist", + allowFrom: ["@admin:example.org"], + threadReplies: "off", + }, + groupPolicy: "allowlist", + groupAllowFrom: ["@admin:example.org"], + groups: { + "!roomid:example.org": { + requireMention: true, + }, + }, + }, + }, +} +``` + +メンションゲートと allowlist の挙動については [Groups](/channels/groups) を参照してください。 + +Matrix DM のペアリング例: + +```bash +openclaw pairing list matrix +openclaw pairing approve matrix +``` + +未承認の Matrix ユーザーが承認前に繰り返しメッセージを送ってきた場合、OpenClaw は同じ保留中のペアリングコードを再利用し、新しいコードを発行する代わりに、短いクールダウン後にリマインダー返信を再送することがあります。 + +共通の DM ペアリングフローと保存レイアウトについては [Pairing](/channels/pairing) を参照してください。 + +## Exec 承認 + +Matrix は Matrix アカウント用の exec 承認クライアントとして動作できます。 + +- `channels.matrix.execApprovals.enabled` +- `channels.matrix.execApprovals.approvers`（任意。`channels.matrix.dm.allowFrom` にフォールバック） +- `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） +- `channels.matrix.execApprovals.agentFilter` +- `channels.matrix.execApprovals.sessionFilter` + +承認者は `@owner:example.org` のような Matrix user ID である必要があります。`enabled` が未設定または `"auto"` で、`execApprovals.approvers` または `channels.matrix.dm.allowFrom` から少なくとも 1 人の承認者を解決できる場合、Matrix はネイティブ exec 承認を自動有効化します。Matrix をネイティブ承認クライアントとして明示的に無効にするには `enabled: false` を設定してください。それ以外では、承認要求は他の設定済み承認ルートまたは exec 承認フォールバックポリシーへフォールバックします。 + +ネイティブ Matrix ルーティングは現在 exec 専用です。 + +- `channels.matrix.execApprovals.*` は、exec 承認専用のネイティブ DM / チャネルルーティングを制御します。 +- プラグイン承認は引き続き共通の同一チャット `/approve` と、設定済みなら `approvals.plugin` 転送を使います。 +- Matrix は、承認者を安全に推測できる場合には、プラグイン承認認可のために `channels.matrix.dm.allowFrom` を再利用できますが、ネイティブのプラグイン承認 DM / チャネル配信パスは別途公開しません。 + +配信ルール: + +- `target: "dm"` は承認プロンプトを承認者 DM に送信します +- `target: "channel"` はプロンプトを発信元の Matrix ルームまたは DM に送り返します +- `target: "both"` は承認者 DM と発信元の Matrix ルームまたは DM の両方に送信します + +Matrix は現在テキスト承認プロンプトを使います。承認者は `/approve allow-once`、`/approve allow-always`、または `/approve deny` で処理します。 + +承認または拒否できるのは解決済み承認者だけです。チャネル配信ではコマンドテキストも含まれるため、`channel` または `both` は信頼できるルームでのみ有効にしてください。 + +Matrix 承認プロンプトは共通のコア承認プランナーを再利用します。Matrix 固有のネイティブ画面は exec 承認のトランスポートのみです。つまり、ルーム / DM ルーティングとメッセージ送信 / 更新 / 削除の挙動だけを担当します。 + +アカウントごとの上書き: + +- `channels.matrix.accounts..execApprovals` + +関連ドキュメント: [Exec approvals](/tools/exec-approvals) + +## マルチアカウントの例 + +```json5 +{ + channels: { + matrix: { + enabled: true, + defaultAccount: "assistant", + dm: { policy: "pairing" }, + accounts: { + assistant: { + homeserver: "https://matrix.example.org", + accessToken: "syt_assistant_xxx", + encryption: true, + }, + alerts: { + homeserver: "https://matrix.example.org", + accessToken: "syt_alerts_xxx", + dm: { + policy: "allowlist", + allowFrom: ["@ops:example.org"], + threadReplies: "off", + }, + }, + }, + }, + }, +} +``` + +トップレベルの `channels.matrix` 値は、アカウント側で上書きされない限り、名前付きアカウントのデフォルトとして機能します。 +継承されたルームエントリーを 1 つの Matrix アカウントに限定するには、`groups..account`（またはレガシーの `rooms..account`）を使えます。 +`account` を持たないエントリーはすべての Matrix アカウントで共有され、`account: "default"` を持つエントリーも、デフォルトアカウントがトップレベル `channels.matrix.*` で直接設定されている場合には引き続き動作します。 +部分的な共有認証デフォルトだけでは、それ自体で別個の暗黙的デフォルトアカウントは作成されません。OpenClaw は、そのデフォルトに新しい認証情報（`homeserver` + `accessToken`、または `homeserver` + `userId` と `password`）がある場合にのみ、トップレベルの `default` アカウントを合成します。名前付きアカウントは、後でキャッシュ済み認証情報が認証要件を満たす場合、`homeserver` + `userId` から引き続き検出可能です。 +Matrix にすでにちょうど 1 つの名前付きアカウントがある場合、または `defaultAccount` が既存の名前付きアカウントキーを指している場合、単一アカウントからマルチアカウントへの修復 / セットアップ昇格では、新しい `accounts.default` エントリーを作らず、そのアカウントを維持します。昇格先アカウントへ移動するのは Matrix 認証 / bootstrap キーだけであり、共有配信ポリシーキーはトップレベルに残ります。 +OpenClaw に暗黙ルーティング、プローブ、CLI 操作で優先する名前付き Matrix アカウントを持たせたい場合は、`defaultAccount` を設定してください。 +複数の名前付きアカウントを設定している場合は、暗黙のアカウント選択に依存する CLI コマンドで `defaultAccount` を設定するか、`--account ` を渡してください。 +その暗黙選択を 1 つのコマンドだけで上書きしたい場合は、`openclaw matrix verify ...` と `openclaw matrix devices ...` に `--account ` を渡してください。 + +## プライベート / LAN homeserver + +デフォルトでは、SSRF 保護のため、OpenClaw はプライベート / 内部 Matrix homeserver への接続をブロックします。ただし、 +アカウント単位で明示的にオプトインした場合は除きます。 + +homeserver が localhost、LAN/Tailscale IP、または内部ホスト名で動作している場合は、 +その Matrix アカウントに対して `allowPrivateNetwork` を有効にしてください。 + +```json5 +{ + channels: { + matrix: { + homeserver: "http://matrix-synapse:8008", + allowPrivateNetwork: true, + accessToken: "syt_internal_xxx", + }, + }, +} +``` + +CLI セットアップ例: + +```bash +openclaw matrix account add \ + --account ops \ + --homeserver http://matrix-synapse:8008 \ + --allow-private-network \ + --access-token syt_ops_xxx +``` + +このオプトインは、信頼されたプライベート / 内部ターゲットのみを許可します。`http://matrix.example.org:8008` のような +公開クリアテキスト homeserver は引き続きブロックされます。可能であれば `https://` を推奨します。 + +## Matrix トラフィックのプロキシ + +Matrix デプロイメントで明示的な送信 HTTP(S) プロキシが必要な場合は、`channels.matrix.proxy` を設定してください。 + +```json5 +{ + channels: { + matrix: { + homeserver: "https://matrix.example.org", + accessToken: "syt_bot_xxx", + proxy: "http://127.0.0.1:7890", + }, + }, +} +``` + +名前付きアカウントでは、`channels.matrix.accounts..proxy` でトップレベルデフォルトを上書きできます。 +OpenClaw は、ランタイム Matrix トラフィックとアカウント状態プローブの両方に同じプロキシ設定を使います。 + +## ターゲット解決 + +Matrix は、OpenClaw がルームまたはユーザーターゲットを求めるあらゆる場面で、以下のターゲット形式を受け付けます。 + +- ユーザー: `@user:server`, `user:@user:server`, または `matrix:user:@user:server` +- ルーム: `!room:server`, `room:!room:server`, または `matrix:room:!room:server` +- エイリアス: `#alias:server`, `channel:#alias:server`, または `matrix:channel:#alias:server` + +ライブディレクトリ参照はログイン済み Matrix アカウントを使います。 + +- ユーザー参照は、その homeserver の Matrix ユーザーディレクトリに問い合わせます。 +- ルーム参照は、明示的なルーム ID とエイリアスを直接受け付けたうえで、そのアカウントで参加中のルーム名検索にフォールバックします。 +- 参加済みルーム名検索はベストエフォートです。ルーム名を ID またはエイリアスに解決できない場合、その名前はランタイム allowlist 解決で無視されます。 + +## 設定リファレンス + +- `enabled`: チャネルを有効または無効にします。 +- `name`: アカウントの任意ラベル。 +- `defaultAccount`: 複数の Matrix アカウントが設定されているときの優先アカウント ID。 +- `homeserver`: homeserver URL。例: `https://matrix.example.org`。 +- `allowPrivateNetwork`: この Matrix アカウントがプライベート / 内部 homeserver に接続できるようにします。homeserver が `localhost`、LAN/Tailscale IP、または `matrix-synapse` のような内部ホストに解決される場合に有効にしてください。 +- `proxy`: Matrix トラフィック用の任意の HTTP(S) プロキシ URL。名前付きアカウントは独自の `proxy` でトップレベルデフォルトを上書きできます。 +- `userId`: 完全な Matrix user ID。例: `@bot:example.org`。 +- `accessToken`: トークンベース認証用のアクセストークン。平文値と SecretRef 値の両方が、`channels.matrix.accessToken` と `channels.matrix.accounts..accessToken` に対して env/file/exec プロバイダー全体でサポートされます。[Secrets Management](/gateway/secrets) を参照してください。 +- `password`: パスワードベースログイン用パスワード。平文値と SecretRef 値の両方がサポートされます。 +- `deviceId`: 明示的な Matrix device ID。 +- `deviceName`: パスワードログイン用のデバイス表示名。 +- `avatarUrl`: プロフィール同期および `set-profile` 更新用に保存される自己アバター URL。 +- `initialSyncLimit`: 起動時の同期イベント上限。 +- `encryption`: E2EE を有効化します。 +- `allowlistOnly`: DM とルームに対して allowlist-only の挙動を強制します。 +- `allowBots`: 他の設定済み OpenClaw Matrix アカウントからのメッセージを許可します（`true` または `"mentions"`）。 +- `groupPolicy`: `open`、`allowlist`、または `disabled`。 +- `contextVisibility`: 補足ルームコンテキストの可視性モード（`all`, `allowlist`, `allowlist_quote`）。 +- `groupAllowFrom`: ルームトラフィック用の user ID allowlist。 +- `groupAllowFrom` エントリーは完全な Matrix user ID にしてください。解決できない名前はランタイムで無視されます。 +- `historyLimit`: グループ履歴コンテキストとして含めるルームメッセージ最大数。`messages.groupChat.historyLimit` にフォールバックします。無効にするには `0` を設定します。 +- `replyToMode`: `off`、`first`、または `all`。 +- `markdown`: 送信 Matrix テキスト用の任意の Markdown レンダリング設定。 +- `streaming`: `off`（デフォルト）、`partial`、`true`、または `false`。`partial` と `true` は、その場で編集更新する単一メッセージ下書きプレビューを有効にします。 +- `blockStreaming`: `true` は、下書きプレビューストリーミングが有効な間、完了済み assistant ブロック用の別個の進行メッセージを有効にします。 +- `threadReplies`: `off`、`inbound`、または `always`。 +- `threadBindings`: スレッドバインドセッションのルーティングとライフサイクルに対するチャネル単位の上書き。 +- `startupVerification`: 起動時の自動自己検証要求モード（`if-unverified`, `off`）。 +- `startupVerificationCooldownHours`: 起動時の自動検証要求を再試行する前のクールダウン。 +- `textChunkLimit`: 送信メッセージのチャンクサイズ。 +- `chunkMode`: `length` または `newline`。 +- `responsePrefix`: 送信返信用の任意のメッセージプレフィックス。 +- `ackReaction`: このチャネル / アカウント用の任意の ack リアクション上書き。 +- `ackReactionScope`: 任意の ack リアクションスコープ上書き（`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`）。 +- `reactionNotifications`: 受信リアクション通知モード（`own`, `off`）。 +- `mediaMaxMb`: Matrix メディア処理におけるメディアサイズ上限（MB）。送信と受信メディア処理の両方に適用されます。 +- `autoJoin`: 招待時の自動参加ポリシー（`always`, `allowlist`, `off`）。デフォルト: `off`。 +- `autoJoinAllowlist`: `autoJoin` が `allowlist` の場合に許可されるルーム / エイリアス。エイリアスエントリーは招待処理時にルーム ID に解決されます。OpenClaw は、招待されたルームが主張するエイリアス状態を信頼しません。 +- `dm`: DM ポリシーブロック（`enabled`, `policy`, `allowFrom`, `threadReplies`）。 +- `dm.allowFrom` エントリーは、ライブディレクトリ参照ですでに解決済みでない限り、完全な Matrix user ID にしてください。 +- `dm.threadReplies`: DM 専用のスレッドポリシー上書き（`off`, `inbound`, `always`）。これは、返信配置と DM におけるセッション分離の両方についてトップレベル `threadReplies` 設定を上書きします。 +- `execApprovals`: Matrix ネイティブ exec 承認配信（`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`）。 +- `execApprovals.approvers`: exec 要求を承認できる Matrix user ID。`dm.allowFrom` がすでに承認者を特定している場合は任意です。 +- `execApprovals.target`: `dm | channel | both`（デフォルト: `dm`）。 +- `accounts`: 名前付きアカウントごとの上書き。トップレベル `channels.matrix` 値がこれらのエントリーのデフォルトとして機能します。 +- `groups`: ルームごとのポリシーマップ。ルーム ID またはエイリアスを推奨します。解決できないルーム名はランタイムで無視されます。セッション / グループ ID は解決後の安定したルーム ID を使い、人間向けラベルは引き続きルーム名から取得されます。 +- `groups..account`: マルチアカウント構成で、継承された 1 つのルームエントリーを特定の Matrix アカウントに限定します。 +- `groups..allowBots`: 設定済み bot 送信者に対するルームレベル上書き（`true` または `"mentions"`）。 +- `groups..users`: ルームごとの送信者 allowlist。 +- `groups..tools`: ルームごとのツール許可 / 拒否上書き。 +- `groups..autoReply`: ルームレベルのメンションゲート上書き。`true` はそのルームのメンション要件を無効化し、`false` は再び強制的に有効化します。 +- `groups..skills`: 任意のルームレベル skill フィルター。 +- `groups..systemPrompt`: 任意のルームレベル system prompt スニペット。 +- `rooms`: `groups` のレガシーエイリアス。 +- `actions`: アクションごとのツールゲート（`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`）。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャネル +- [Pairing](/channels/pairing) — DM 認証とペアリングフロー +- [Groups](/channels/groups) — グループチャットの挙動とメンションゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/mattermost.md b/docs/ja-JP/channels/mattermost.md new file mode 100644 index 000000000..c85ef2d5f --- /dev/null +++ b/docs/ja-JP/channels/mattermost.md @@ -0,0 +1,484 @@ +--- +read_when: + - Mattermost をセットアップしている + - Mattermost のルーティングをデバッグしている +summary: Mattermost ボットのセットアップと OpenClaw の設定 +title: Mattermost +x-i18n: + generated_at: "2026-04-05T12:36:41Z" + model: gpt-5.4 + provider: openai + source_hash: f21dc7543176fda0b38b00fab60f0daae38dffcf68fa1cf7930a9f14ec57cb5a + source_path: channels/mattermost.md + workflow: 15 +--- + +# Mattermost + +ステータス: バンドルされたプラグイン（ボットトークン + WebSocket イベント）。チャネル、グループ、DM をサポートしています。 +Mattermost はセルフホスト可能なチーム向けメッセージングプラットフォームです。製品の詳細とダウンロードについては、公式サイト +[mattermost.com](https://mattermost.com) を参照してください。 + +## バンドルされたプラグイン + +Mattermost は現在の OpenClaw リリースではバンドルされたプラグインとして同梱されているため、通常の +パッケージ版ビルドでは別途インストールは不要です。 + +古いビルドまたは Mattermost を含まないカスタムインストールを使用している場合は、 +手動でインストールしてください。 + +CLI でインストール（npm レジストリ）: + +```bash +openclaw plugins install @openclaw/mattermost +``` + +ローカルチェックアウト（git リポジトリから実行している場合）: + +```bash +openclaw plugins install ./path/to/local/mattermost-plugin +``` + +詳細: [Plugins](/tools/plugin) + +## クイックセットアップ + +1. Mattermost プラグインが利用可能であることを確認します。 + - 現在のパッケージ版 OpenClaw リリースにはすでに同梱されています。 + - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 +2. Mattermost のボットアカウントを作成し、**bot token** をコピーします。 +3. Mattermost の **base URL** をコピーします（例: `https://chat.example.com`）。 +4. OpenClaw を設定して Gateway を起動します。 + +最小設定: + +```json5 +{ + channels: { + mattermost: { + enabled: true, + botToken: "mm-token", + baseUrl: "https://chat.example.com", + dmPolicy: "pairing", + }, + }, +} +``` + +## ネイティブスラッシュコマンド + +ネイティブスラッシュコマンドはオプトインです。有効にすると、OpenClaw は +Mattermost API 経由で `oc_*` スラッシュコマンドを登録し、Gateway HTTP サーバー上で +コールバック POST を受信します。 + +```json5 +{ + channels: { + mattermost: { + commands: { + native: true, + nativeSkills: true, + callbackPath: "/api/channels/mattermost/command", + // Mattermost から Gateway に直接到達できない場合に使用します（リバースプロキシ/公開 URL）。 + callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", + }, + }, + }, +} +``` + +注意: + +- `native: "auto"` は Mattermost ではデフォルトで無効です。有効にするには `native: true` を設定してください。 +- `callbackUrl` を省略した場合、OpenClaw は Gateway の host/port と `callbackPath` から導出します。 +- マルチアカウント構成では、`commands` は最上位または + `channels.mattermost.accounts..commands` の下に設定できます（アカウント値が最上位フィールドを上書きします）。 +- コマンドコールバックは、OpenClaw が `oc_*` コマンドを登録した際に Mattermost から返される + コマンドごとのトークンで検証されます。 +- スラッシュコールバックは、登録に失敗した場合、起動が部分的にしか完了しなかった場合、 + またはコールバックトークンが登録済みコマンドのいずれにも一致しない場合にフェイルクローズします。 +- 到達可能性の要件: コールバックエンドポイントは Mattermost サーバーから到達可能である必要があります。 + - Mattermost が OpenClaw と同じホスト/ネットワーク名前空間で動作していない限り、`callbackUrl` に `localhost` を設定しないでください。 + - その URL が `/api/channels/mattermost/command` を OpenClaw にリバースプロキシしていない限り、`callbackUrl` に Mattermost の base URL を設定しないでください。 + - 簡単な確認方法は `curl https:///api/channels/mattermost/command` です。GET は `404` ではなく OpenClaw から `405 Method Not Allowed` を返す必要があります。 +- Mattermost の送信先許可リスト要件: + - コールバックがプライベート/Tailnet/内部アドレスを対象にする場合は、Mattermost の + `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含めてください。 + - 完全な URL ではなく、ホスト/ドメインのエントリを使用してください。 + - 良い例: `gateway.tailnet-name.ts.net` + - 悪い例: `https://gateway.tailnet-name.ts.net` + +## 環境変数（デフォルトアカウント） + +環境変数を使いたい場合は、Gateway ホストで次を設定します。 + +- `MATTERMOST_BOT_TOKEN=...` +- `MATTERMOST_URL=https://chat.example.com` + +環境変数は **default** アカウント（`default`）にのみ適用されます。他のアカウントでは設定値を使用する必要があります。 + +## チャットモード + +Mattermost は DM には自動で応答します。チャネルでの挙動は `chatmode` で制御されます。 + +- `oncall`（デフォルト）: チャネルでは @メンションされたときだけ応答します。 +- `onmessage`: すべてのチャネルメッセージに応答します。 +- `onchar`: メッセージがトリガープレフィックスで始まると応答します。 + +設定例: + +```json5 +{ + channels: { + mattermost: { + chatmode: "onchar", + oncharPrefixes: [">", "!"], + }, + }, +} +``` + +注意: + +- `onchar` は明示的な @メンションにも引き続き応答します。 +- `channels.mattermost.requireMention` は従来の設定との互換性のために尊重されますが、`chatmode` の使用が推奨されます。 + +## スレッド化とセッション + +`channels.mattermost.replyToMode` を使用すると、チャネルおよびグループへの返信を +メインチャネルに保持するか、トリガーとなった投稿の下でスレッドを開始するかを制御できます。 + +- `off`（デフォルト）: 受信した投稿がすでにスレッド内にある場合にのみスレッドで返信します。 +- `first`: 最上位のチャネル/グループ投稿に対して、その投稿の下にスレッドを開始し、 + 会話をスレッドスコープのセッションにルーティングします。 +- `all`: 現在の Mattermost では `first` と同じ動作です。 +- ダイレクトメッセージはこの設定を無視し、スレッド化されません。 + +設定例: + +```json5 +{ + channels: { + mattermost: { + replyToMode: "all", + }, + }, +} +``` + +注意: + +- スレッドスコープのセッションは、トリガーとなった投稿 ID をスレッドルートとして使用します。 +- `first` と `all` は現在同等です。Mattermost にスレッドルートが一度できると、 + 後続のチャンクとメディアは同じスレッド内で継続されるためです。 + +## アクセス制御（DM） + +- デフォルト: `channels.mattermost.dmPolicy = "pairing"`（未知の送信者にはペアリングコードが渡されます）。 +- 承認方法: + - `openclaw pairing list mattermost` + - `openclaw pairing approve mattermost ` +- 公開 DM: `channels.mattermost.dmPolicy="open"` と `channels.mattermost.allowFrom=["*"]`。 + +## チャネル（グループ） + +- デフォルト: `channels.mattermost.groupPolicy = "allowlist"`（メンションゲートあり）。 +- `channels.mattermost.groupAllowFrom` で送信者を許可リストに追加します（ユーザー ID 推奨）。 +- チャネルごとのメンション上書きは `channels.mattermost.groups..requireMention` + またはデフォルト用の `channels.mattermost.groups["*"].requireMention` にあります。 +- `@username` のマッチングは可変であり、`channels.mattermost.dangerouslyAllowNameMatching: true` のときだけ有効です。 +- オープンチャネル: `channels.mattermost.groupPolicy="open"`（メンションゲートあり）。 +- ランタイム上の注意: `channels.mattermost` が完全に存在しない場合、ランタイムはグループチェックで + `groupPolicy="allowlist"` にフォールバックします（`channels.defaults.groupPolicy` が設定されていても同様です）。 + +例: + +```json5 +{ + channels: { + mattermost: { + groupPolicy: "open", + groups: { + "*": { requireMention: true }, + "team-channel-id": { requireMention: false }, + }, + }, + }, +} +``` + +## 送信配信のターゲット + +`openclaw message send` または cron/webhook では、次のターゲット形式を使用します。 + +- チャネルには `channel:` +- DM には `user:` +- DM には `@username` も使用可能です（Mattermost API 経由で解決されます） + +プレフィックスのない不透明 ID（`64ifufp...` のようなもの）は、Mattermost では **曖昧** です（ユーザー ID かチャネル ID か）。 + +OpenClaw はこれを **ユーザー優先** で解決します。 + +- その ID がユーザーとして存在する場合（`GET /api/v4/users/` が成功）、OpenClaw は + `/api/v4/channels/direct` でダイレクトチャネルを解決して **DM** を送信します。 +- それ以外の場合、その ID は **チャネル ID** として扱われます。 + +決定的な動作が必要な場合は、必ず明示的なプレフィックス（`user:` / `channel:`）を使用してください。 + +## DM チャネル再試行 + +OpenClaw が Mattermost の DM ターゲットに送信し、最初にダイレクトチャネルを解決する必要がある場合、 +デフォルトで一時的なダイレクトチャネル作成失敗を再試行します。 + +この挙動を Mattermost プラグイン全体で調整するには `channels.mattermost.dmChannelRetry` を、 +1 つのアカウントだけに適用するには `channels.mattermost.accounts..dmChannelRetry` を使います。 + +```json5 +{ + channels: { + mattermost: { + dmChannelRetry: { + maxRetries: 3, + initialDelayMs: 1000, + maxDelayMs: 10000, + timeoutMs: 30000, + }, + }, + }, +} +``` + +注意: + +- これはすべての Mattermost API 呼び出しではなく、DM チャネル作成（`/api/v4/channels/direct`）にのみ適用されます。 +- 再試行は、レート制限、5xx 応答、ネットワークエラー、タイムアウトエラーなどの一時的失敗に適用されます。 +- `429` 以外の 4xx クライアントエラーは恒久的な失敗として扱われ、再試行されません。 + +## リアクション（message ツール） + +- `channel=mattermost` とともに `message action=react` を使用します。 +- `messageId` は Mattermost の投稿 ID です。 +- `emoji` は `thumbsup` や `:+1:` のような名前を受け付けます（コロンは省略可能です）。 +- リアクションを削除するには `remove=true`（boolean）を設定します。 +- リアクションの追加/削除イベントは、ルーティングされたエージェントセッションにシステムイベントとして転送されます。 + +例: + +``` +message action=react channel=mattermost target=channel: messageId= emoji=thumbsup +message action=react channel=mattermost target=channel: messageId= emoji=thumbsup remove=true +``` + +設定: + +- `channels.mattermost.actions.reactions`: リアクション操作を有効/無効にします（デフォルトは true）。 +- アカウントごとの上書き: `channels.mattermost.accounts..actions.reactions`。 + +## インタラクティブボタン（message ツール） + +クリック可能なボタン付きメッセージを送信します。ユーザーがボタンをクリックすると、エージェントが +選択内容を受け取り、応答できます。 + +チャネル機能に `inlineButtons` を追加してボタンを有効化します。 + +```json5 +{ + channels: { + mattermost: { + capabilities: ["inlineButtons"], + }, + }, +} +``` + +`buttons` パラメータ付きで `message action=send` を使用します。ボタンは 2 次元配列（ボタンの行）です。 + +``` +message action=send channel=mattermost target=channel: buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]] +``` + +ボタンフィールド: + +- `text`（必須）: 表示ラベル。 +- `callback_data`（必須）: クリック時に送り返される値（アクション ID として使用）。 +- `style`（省略可）: `"default"`、`"primary"`、または `"danger"`。 + +ユーザーがボタンをクリックすると: + +1. すべてのボタンが確認行に置き換えられます（例: 「✓ **Yes** selected by @user」）。 +2. エージェントが選択内容を受信メッセージとして受け取り、応答します。 + +注意: + +- ボタンコールバックは HMAC-SHA256 検証を使用します（自動、設定不要）。 +- Mattermost は API 応答から callback data を削除するため（セキュリティ機能）、 + クリック時にはすべてのボタンが削除されます。部分削除はできません。 +- ハイフンやアンダースコアを含むアクション ID は自動的にサニタイズされます + （Mattermost のルーティング制限）。 + +設定: + +- `channels.mattermost.capabilities`: 機能文字列の配列。ボタンツールの説明をエージェントのシステムプロンプトで有効にするには + `"inlineButtons"` を追加します。 +- `channels.mattermost.interactions.callbackBaseUrl`: ボタンコールバック用の省略可能な外部 base URL + （例: `https://gateway.example.com`）。Mattermost が + bind host 上の Gateway に直接到達できない場合に使用します。 +- マルチアカウント構成では、同じフィールドを + `channels.mattermost.accounts..interactions.callbackBaseUrl` に設定することもできます。 +- `interactions.callbackBaseUrl` を省略した場合、OpenClaw は + `gateway.customBindHost` + `gateway.port` からコールバック URL を導出し、その後 `http://localhost:` にフォールバックします。 +- 到達可能性ルール: ボタンコールバック URL は Mattermost サーバーから到達可能である必要があります。 + `localhost` が機能するのは、Mattermost と OpenClaw が同じホスト/ネットワーク名前空間で動作している場合だけです。 +- コールバック対象がプライベート/Tailnet/内部の場合は、そのホスト/ドメインを Mattermost の + `ServiceSettings.AllowedUntrustedInternalConnections` に追加してください。 + +### 直接 API 統合（外部スクリプト） + +外部スクリプトや webhook は、エージェントの `message` ツールを経由せず、 +Mattermost REST API 経由でボタンを直接投稿できます。可能であれば拡張機能の +`buildButtonAttachments()` を使用してください。生の JSON を投稿する場合は、次のルールに従ってください。 + +**ペイロード構造:** + +```json5 +{ + channel_id: "", + message: "Choose an option:", + props: { + attachments: [ + { + actions: [ + { + id: "mybutton01", // 英数字のみ — 下記参照 + type: "button", // 必須。これがないとクリックは黙って無視される + name: "Approve", // 表示ラベル + style: "primary", // 省略可: "default", "primary", "danger" + integration: { + url: "https://gateway.example.com/mattermost/interactions/default", + context: { + action_id: "mybutton01", // ボタン id と一致する必要がある（名前参照のため） + action: "approve", + // ... 任意のカスタムフィールド ... + _token: "", // 下記の HMAC セクションを参照 + }, + }, + }, + ], + }, + ], + }, +} +``` + +**重要なルール:** + +1. attachments は最上位の `attachments` ではなく `props.attachments` に入れます（そうしないと黙って無視されます）。 +2. すべての action に `type: "button"` が必要です。これがないとクリックは黙って飲み込まれます。 +3. すべての action に `id` フィールドが必要です。Mattermost は ID のない action を無視します。 +4. action の `id` は **英数字のみ**（`[a-zA-Z0-9]`）でなければなりません。ハイフンとアンダースコアは + Mattermost のサーバー側 action ルーティングを壊します（404 を返します）。使用前に除去してください。 +5. 確認メッセージに生の ID ではなくボタン名（例: 「Approve」）を表示するには、 + `context.action_id` をボタンの `id` と一致させる必要があります。 +6. `context.action_id` は必須です。これがないと interaction handler は 400 を返します。 + +**HMAC トークン生成:** + +Gateway は HMAC-SHA256 でボタンクリックを検証します。外部スクリプトは、 +Gateway の検証ロジックに一致するトークンを生成する必要があります。 + +1. ボットトークンからシークレットを導出します: + `HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)` +2. `_token` を除くすべてのフィールドを含む context オブジェクトを構築します。 +3. **キーをソート**し、**スペースなし**でシリアライズします（Gateway は + キーをソートした `JSON.stringify` を使用し、コンパクトな出力を生成します）。 +4. 署名します: `HMAC-SHA256(key=secret, data=serializedContext)` +5. 結果の 16 進ダイジェストを `_token` として context に追加します。 + +Python の例: + +```python +import hmac, hashlib, json + +secret = hmac.new( + b"openclaw-mattermost-interactions", + bot_token.encode(), hashlib.sha256 +).hexdigest() + +ctx = {"action_id": "mybutton01", "action": "approve"} +payload = json.dumps(ctx, sort_keys=True, separators=(",", ":")) +token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() + +context = {**ctx, "_token": token} +``` + +よくある HMAC の落とし穴: + +- Python の `json.dumps` はデフォルトでスペースを追加します（`{"key": "val"}`）。 + JavaScript のコンパクトな出力（`{"key":"val"}`）に合わせるには + `separators=(",", ":")` を使用してください。 +- 必ず **すべて** の context フィールド（`_token` を除く）に署名してください。Gateway は `_token` を取り除いた後、 + 残りすべてに署名します。一部だけに署名すると検証は黙って失敗します。 +- `sort_keys=True` を使ってください。Gateway は署名前にキーをソートし、Mattermost は + ペイロード保存時に context フィールドを並べ替える場合があります。 +- ランダムバイトではなく、ボットトークンからシークレットを導出してください（決定的です）。シークレットは、 + ボタンを作成するプロセスと Gateway 側で検証するプロセスで同一でなければなりません。 + +## ディレクトリアダプター + +Mattermost プラグインには、Mattermost API 経由でチャネル名とユーザー名を解決する +ディレクトリアダプターが含まれています。これにより、 +`openclaw message send` や cron/webhook 配信で `#channel-name` と `@username` ターゲットを使用できます。 + +設定は不要です。このアダプターはアカウント設定のボットトークンを使用します。 + +## マルチアカウント + +Mattermost は `channels.mattermost.accounts` 配下で複数アカウントをサポートします。 + +```json5 +{ + channels: { + mattermost: { + accounts: { + default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" }, + alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" }, + }, + }, + }, +} +``` + +## トラブルシューティング + +- チャネルで返信がない: ボットがチャネルに参加していることを確認し、メンションする（oncall）、トリガープレフィックスを使う（onchar）、または `chatmode: "onmessage"` を設定してください。 +- 認証エラー: ボットトークン、base URL、アカウントが有効かどうかを確認してください。 +- マルチアカウントの問題: 環境変数は `default` アカウントにのみ適用されます。 +- ネイティブスラッシュコマンドが `Unauthorized: invalid command token.` を返す: OpenClaw が + コールバックトークンを受け入れませんでした。典型的な原因: + - スラッシュコマンド登録が失敗した、または起動時に部分的にしか完了しなかった + - コールバックが誤った Gateway/アカウントに到達している + - Mattermost に以前のコールバックターゲットを指す古いコマンドが残っている + - Gateway がスラッシュコマンドを再有効化せずに再起動した +- ネイティブスラッシュコマンドが動かなくなった場合は、ログで + `mattermost: failed to register slash commands` または + `mattermost: native slash commands enabled but no commands could be registered` + を確認してください。 +- `callbackUrl` を省略し、ログにコールバックが + `http://127.0.0.1:18789/...` に解決されたという警告が出る場合、その URL は + Mattermost が OpenClaw と同じホスト/ネットワーク名前空間で動作している場合にのみ到達可能である可能性が高いです。 + 外部から到達可能な `commands.callbackUrl` を明示的に設定してください。 +- ボタンが白いボックスとして表示される: エージェントが不正なボタンデータを送っている可能性があります。各ボタンに `text` と `callback_data` の両方があることを確認してください。 +- ボタンは表示されるがクリックしても何も起きない: Mattermost サーバー設定の `AllowedUntrustedInternalConnections` に `127.0.0.1 localhost` が含まれていること、および ServiceSettings の `EnablePostActionIntegration` が `true` であることを確認してください。 +- クリック時にボタンが 404 を返す: ボタンの `id` にハイフンまたはアンダースコアが含まれている可能性があります。Mattermost の action router は英数字以外の ID で壊れます。`[a-zA-Z0-9]` のみを使用してください。 +- Gateway ログに `invalid _token` が出る: HMAC 不一致です。すべての context フィールドに署名していること（一部ではない）、キーをソートしていること、コンパクトな JSON（スペースなし）を使っていることを確認してください。上記の HMAC セクションを参照してください。 +- Gateway ログに `missing _token in context` が出る: `_token` フィールドがボタンの context にありません。integration ペイロード構築時に含めていることを確認してください。 +- 確認表示にボタン名ではなく生の ID が出る: `context.action_id` がボタンの `id` と一致していません。両方に同じサニタイズ済みの値を設定してください。 +- エージェントがボタンを認識しない: Mattermost チャネル設定に `capabilities: ["inlineButtons"]` を追加してください。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャネル +- [Pairing](/channels/pairing) — DM 認証とペアリングフロー +- [Groups](/channels/groups) — グループチャットの挙動とメンションゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/msteams.md b/docs/ja-JP/channels/msteams.md new file mode 100644 index 000000000..9f453f309 --- /dev/null +++ b/docs/ja-JP/channels/msteams.md @@ -0,0 +1,812 @@ +--- +read_when: + - Microsoft Teams チャネル機能に取り組んでいるとき +summary: Microsoft Teams ボットサポートのステータス、機能、設定 +title: Microsoft Teams +x-i18n: + generated_at: "2026-04-05T12:37:26Z" + model: gpt-5.4 + provider: openai + source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf + source_path: channels/msteams.md + workflow: 15 +--- + +# Microsoft Teams + +> 「ここに入る者は一切の希望を捨てよ。」 + +更新日: 2026-01-21 + +ステータス: テキスト + DM 添付ファイルをサポートしています。チャネル/グループでのファイル送信には `sharePointSiteId` + Graph 権限が必要です（[グループチャットでのファイル送信](#sending-files-in-group-chats)を参照）。投票は Adaptive Cards 経由で送信されます。メッセージアクションでは、ファイル優先送信のための明示的な `upload-file` が公開されています。 + +## バンドル済みプラグイン + +Microsoft Teams は現在の OpenClaw リリースではバンドル済みプラグインとして提供されているため、通常のパッケージビルドでは +別途インストールは不要です。 + +古いビルドや、バンドル済み Teams を含まないカスタムインストールを使っている場合は、 +手動でインストールしてください。 + +```bash +openclaw plugins install @openclaw/msteams +``` + +ローカルチェックアウト（git リポジトリから実行している場合）: + +```bash +openclaw plugins install ./path/to/local/msteams-plugin +``` + +詳細: [プラグイン](/tools/plugin) + +## クイックセットアップ（初級者向け） + +1. Microsoft Teams プラグインが利用可能であることを確認します。 + - 現在のパッケージ版 OpenClaw リリースには、すでにバンドルされています。 + - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 +2. **Azure Bot** を作成します（App ID + client secret + tenant ID）。 +3. それらの認証情報で OpenClaw を設定します。 +4. 公開 URL またはトンネル経由で `/api/messages`（既定ではポート 3978）を公開します。 +5. Teams アプリパッケージをインストールし、Gateway を起動します。 + +最小設定: + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + appPassword: "", + tenantId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +注: グループチャットは既定でブロックされます（`channels.msteams.groupPolicy: "allowlist"`）。グループ返信を許可するには、`channels.msteams.groupAllowFrom` を設定してください（または `groupPolicy: "open"` を使って任意のメンバーを許可し、メンションゲート付きにします）。 + +## 目的 + +- Teams の DM、グループチャット、またはチャネル経由で OpenClaw とやり取りする。 +- ルーティングを決定的に保つ: 返信は常に受信したチャネルに戻る。 +- チャネルでの安全な動作を既定にする（設定しない限りメンションが必要）。 + +## 設定の書き込み + +既定では、Microsoft Teams は `/config set|unset` によってトリガーされる設定更新の書き込みを許可されています（`commands.config: true` が必要です）。 + +無効にするには: + +```json5 +{ + channels: { msteams: { configWrites: false } }, +} +``` + +## アクセス制御（DM + グループ） + +**DM アクセス** + +- 既定値: `channels.msteams.dmPolicy = "pairing"`。未知の送信者は承認されるまで無視されます。 +- `channels.msteams.allowFrom` には安定した AAD オブジェクト ID を使うべきです。 +- UPN/表示名は変更可能です。直接一致は既定で無効であり、`channels.msteams.dangerouslyAllowNameMatching: true` でのみ有効になります。 +- 認証情報に十分な権限があれば、ウィザードは Microsoft Graph 経由で名前を ID に解決できます。 + +**グループアクセス** + +- 既定値: `channels.msteams.groupPolicy = "allowlist"`（`groupAllowFrom` を追加するまでブロック）。未設定時の既定値を上書きするには `channels.defaults.groupPolicy` を使います。 +- `channels.msteams.groupAllowFrom` は、グループチャット/チャネルでどの送信者がトリガーできるかを制御します（`channels.msteams.allowFrom` にフォールバックします）。 +- `groupPolicy: "open"` を設定すると任意のメンバーを許可します（それでも既定ではメンションゲート付きです）。 +- **チャネルを一切許可しない**場合は、`channels.msteams.groupPolicy: "disabled"` を設定します。 + +例: + +```json5 +{ + channels: { + msteams: { + groupPolicy: "allowlist", + groupAllowFrom: ["user@org.com"], + }, + }, +} +``` + +**Teams + チャネル許可リスト** + +- `channels.msteams.teams` の下に teams と channels を列挙することで、グループ/チャネル返信の範囲を制限します。 +- キーには安定した team ID と channel conversation ID を使うべきです。 +- `groupPolicy="allowlist"` で teams 許可リストが存在する場合、列挙された teams/channels のみが受け付けられます（メンションゲート付き）。 +- 設定ウィザードは `Team/Channel` エントリを受け付け、それらを保存します。 +- 起動時に、OpenClaw は team/channel とユーザーの許可リスト名を ID に解決し（Graph 権限があれば）、 + その対応をログに出力します。未解決の team/channel 名は入力されたまま保持されますが、既定ではルーティングでは無視されます。`channels.msteams.dangerouslyAllowNameMatching: true` が有効な場合を除きます。 + +例: + +```json5 +{ + channels: { + msteams: { + groupPolicy: "allowlist", + teams: { + "My Team": { + channels: { + General: { requireMention: true }, + }, + }, + }, + }, + }, +} +``` + +## 動作の仕組み + +1. Microsoft Teams プラグインが利用可能であることを確認します。 + - 現在のパッケージ版 OpenClaw リリースには、すでにバンドルされています。 + - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 +2. **Azure Bot** を作成します（App ID + secret + tenant ID）。 +3. ボットを参照し、以下の RSC 権限を含む **Teams app package** を作成します。 +4. Teams アプリを team にアップロード/インストールします（または DM 用に personal スコープ）。 +5. `~/.openclaw/openclaw.json`（または環境変数）で `msteams` を設定し、Gateway を起動します。 +6. Gateway は既定で `/api/messages` 上の Bot Framework webhook トラフィックを待ち受けます。 + +## Azure Bot セットアップ（前提条件） + +OpenClaw を設定する前に、Azure Bot リソースを作成する必要があります。 + +### ステップ 1: Azure Bot を作成する + +1. [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) に移動します +2. **Basics** タブに入力します: + + | フィールド | 値 | + | ------------------ | -------------------------------------------------------- | + | **Bot handle** | ボット名。例: `openclaw-msteams`（一意である必要があります） | + | **Subscription** | Azure サブスクリプションを選択 | + | **Resource group** | 新規作成または既存を使用 | + | **Pricing tier** | 開発/テスト用は **Free** | + | **Type of App** | **Single Tenant**（推奨。以下の注を参照） | + | **Creation type** | **Create new Microsoft App ID** | + +> **非推奨に関する通知:** 新しい multi-tenant bot の作成は 2025-07-31 以降非推奨になりました。新しいボットでは **Single Tenant** を使用してください。 + +3. **Review + create** → **Create** をクリックします（1〜2 分ほど待ちます） + +### ステップ 2: 認証情報を取得する + +1. Azure Bot リソース → **Configuration** に移動します +2. **Microsoft App ID** をコピーします → これが `appId` です +3. **Manage Password** をクリックします → App Registration に移動します +4. **Certificates & secrets** → **New client secret** → **Value** をコピーします → これが `appPassword` です +5. **Overview** に移動します → **Directory (tenant) ID** をコピーします → これが `tenantId` です + +### ステップ 3: Messaging Endpoint を設定する + +1. Azure Bot → **Configuration** +2. **Messaging endpoint** に webhook URL を設定します: + - 本番環境: `https://your-domain.com/api/messages` + - ローカル開発: トンネルを使用します（以下の[ローカル開発](#local-development-tunneling)を参照） + +### ステップ 4: Teams チャネルを有効にする + +1. Azure Bot → **Channels** +2. **Microsoft Teams** → Configure → Save をクリックします +3. 利用規約に同意します + +## ローカル開発（トンネリング） + +Teams は `localhost` に到達できません。ローカル開発ではトンネルを使います。 + +**オプション A: ngrok** + +```bash +ngrok http 3978 +# https URL をコピーします。例: https://abc123.ngrok.io +# Messaging endpoint を次に設定します: https://abc123.ngrok.io/api/messages +``` + +**オプション B: Tailscale Funnel** + +```bash +tailscale funnel 3978 +# Messaging endpoint として Tailscale funnel URL を使います +``` + +## Teams Developer Portal（代替手段） + +manifest ZIP を手作業で作成する代わりに、[Teams Developer Portal](https://dev.teams.microsoft.com/apps) を使用できます。 + +1. **+ New app** をクリックします +2. 基本情報（名前、説明、開発者情報）を入力します +3. **App features** → **Bot** に移動します +4. **Enter a bot ID manually** を選択し、Azure Bot App ID を貼り付けます +5. スコープをチェックします: **Personal**、**Team**、**Group Chat** +6. **Distribute** → **Download app package** をクリックします +7. Teams で: **Apps** → **Manage your apps** → **Upload a custom app** → ZIP を選択します + +これは JSON manifest を手作業で編集するより簡単なことが多いです。 + +## ボットのテスト + +**オプション A: Azure Web Chat（先に webhook を確認する）** + +1. Azure Portal → Azure Bot リソース → **Test in Web Chat** +2. メッセージを送信します。応答が表示されるはずです +3. これにより、Teams セットアップ前に webhook endpoint が機能していることを確認できます + +**オプション B: Teams（アプリインストール後）** + +1. Teams アプリをインストールします（サイドロードまたは組織カタログ） +2. Teams でボットを見つけ、DM を送信します +3. 受信アクティビティについて Gateway ログを確認します + +## セットアップ（最小のテキスト専用） + +1. **Microsoft Teams プラグインが利用可能であることを確認する** + - 現在のパッケージ版 OpenClaw リリースには、すでにバンドルされています。 + - 古い/カスタムインストールでは、手動追加できます: + - npm から: `openclaw plugins install @openclaw/msteams` + - ローカルチェックアウトから: `openclaw plugins install ./path/to/local/msteams-plugin` + +2. **ボット登録** + - Azure Bot を作成し（上記参照）、以下を控えます: + - App ID + - Client secret（App password） + - Tenant ID（single-tenant） + +3. **Teams app manifest** + - `bot` エントリに `botId = ` を含めます。 + - スコープ: `personal`、`team`、`groupChat`。 + - `supportsFiles: true`（personal スコープでのファイル処理に必要）。 + - RSC 権限を追加します（下記）。 + - アイコンを作成します: `outline.png`（32x32）と `color.png`（192x192）。 + - 3 つのファイルを一緒に zip 化します: `manifest.json`、`outline.png`、`color.png`。 + +4. **OpenClaw を設定する** + + ```json5 + { + channels: { + msteams: { + enabled: true, + appId: "", + appPassword: "", + tenantId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, + } + ``` + + 設定キーの代わりに環境変数も使えます: + - `MSTEAMS_APP_ID` + - `MSTEAMS_APP_PASSWORD` + - `MSTEAMS_TENANT_ID` + +5. **ボット endpoint** + - Azure Bot Messaging Endpoint を次のように設定します: + - `https://:3978/api/messages`（または選択したパス/ポート）。 + +6. **Gateway を実行する** + - Teams チャネルは、バンドル済みまたは手動インストールされたプラグインが利用可能で、認証情報を含む `msteams` 設定が存在すれば自動的に起動します。 + +## メンバー情報アクション + +OpenClaw は Microsoft Teams 向けに Graph ベースの `member-info` アクションを公開しており、エージェントやオートメーションが Microsoft Graph から直接チャネルメンバーの詳細（表示名、メールアドレス、ロール）を解決できます。 + +要件: + +- `Member.Read.Group` RSC 権限（推奨 manifest にすでに含まれています） +- team をまたぐ検索の場合: 管理者同意付きの `User.Read.All` Graph Application 権限 + +このアクションは `channels.msteams.actions.memberInfo` で制御されます（既定: Graph 認証情報が利用可能な場合は有効）。 + +## 履歴コンテキスト + +- `channels.msteams.historyLimit` は、プロンプトに含める最近のチャネル/グループメッセージ数を制御します。 +- `messages.groupChat.historyLimit` にフォールバックします。`0` を設定すると無効になります（既定 50）。 +- 取得したスレッド履歴は送信者許可リスト（`allowFrom` / `groupAllowFrom`）でフィルタリングされるため、スレッドコンテキストのシードには許可された送信者からのメッセージのみが含まれます。 +- 引用された添付ファイルコンテキスト（Teams の返信 HTML 由来の `ReplyTo*`）は、現在は受信したまま渡されます。 +- つまり、許可リストは誰がエージェントをトリガーできるかを制御し、現在フィルタリングされるのは特定の補助的なコンテキスト経路のみです。 +- DM 履歴は `channels.msteams.dmHistoryLimit`（ユーザーターン）で制限できます。ユーザーごとの上書き: `channels.msteams.dms[""].historyLimit`。 + +## 現在の Teams RSC 権限（Manifest） + +これらは Teams app manifest 内の**既存の resourceSpecific permissions** です。これらはアプリがインストールされている team/chat 内でのみ適用されます。 + +**チャネル用（team スコープ）:** + +- `ChannelMessage.Read.Group`（Application）- @メンションなしで全チャネルメッセージを受信 +- `ChannelMessage.Send.Group`（Application） +- `Member.Read.Group`（Application） +- `Owner.Read.Group`（Application） +- `ChannelSettings.Read.Group`（Application） +- `TeamMember.Read.Group`（Application） +- `TeamSettings.Read.Group`（Application） + +**グループチャット用:** + +- `ChatMessage.Read.Chat`（Application）- @メンションなしで全グループチャットメッセージを受信 + +## Teams Manifest の例（機密情報削除済み） + +必要なフィールドを含む最小で有効な例です。ID と URL は置き換えてください。 + +```json5 +{ + $schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json", + manifestVersion: "1.23", + version: "1.0.0", + id: "00000000-0000-0000-0000-000000000000", + name: { short: "OpenClaw" }, + developer: { + name: "Your Org", + websiteUrl: "https://example.com", + privacyUrl: "https://example.com/privacy", + termsOfUseUrl: "https://example.com/terms", + }, + description: { short: "OpenClaw in Teams", full: "OpenClaw in Teams" }, + icons: { outline: "outline.png", color: "color.png" }, + accentColor: "#5B6DEF", + bots: [ + { + botId: "11111111-1111-1111-1111-111111111111", + scopes: ["personal", "team", "groupChat"], + isNotificationOnly: false, + supportsCalling: false, + supportsVideo: false, + supportsFiles: true, + }, + ], + webApplicationInfo: { + id: "11111111-1111-1111-1111-111111111111", + }, + authorization: { + permissions: { + resourceSpecific: [ + { name: "ChannelMessage.Read.Group", type: "Application" }, + { name: "ChannelMessage.Send.Group", type: "Application" }, + { name: "Member.Read.Group", type: "Application" }, + { name: "Owner.Read.Group", type: "Application" }, + { name: "ChannelSettings.Read.Group", type: "Application" }, + { name: "TeamMember.Read.Group", type: "Application" }, + { name: "TeamSettings.Read.Group", type: "Application" }, + { name: "ChatMessage.Read.Chat", type: "Application" }, + ], + }, + }, +} +``` + +### Manifest の注意点（必須フィールド） + +- `bots[].botId` は Azure Bot App ID と**一致している必要があります**。 +- `webApplicationInfo.id` は Azure Bot App ID と**一致している必要があります**。 +- `bots[].scopes` には、使用する予定のサーフェス（`personal`、`team`、`groupChat`）を含める必要があります。 +- `bots[].supportsFiles: true` は personal スコープでのファイル処理に必要です。 +- `authorization.permissions.resourceSpecific` には、チャネルトラフィックが必要ならチャネルの読み取り/送信を含める必要があります。 + +### 既存アプリの更新 + +すでにインストール済みの Teams アプリを更新するには（たとえば RSC 権限を追加する場合）: + +1. `manifest.json` を新しい設定で更新します +2. **`version` フィールドをインクリメント**します（例: `1.0.0` → `1.1.0`） +3. アイコン付きで manifest を**再 zip 化**します（`manifest.json`、`outline.png`、`color.png`） +4. 新しい zip をアップロードします: + - **オプション A（Teams Admin Center）:** Teams Admin Center → Teams apps → Manage apps → 対象アプリを見つける → Upload new version + - **オプション B（サイドロード）:** Teams → Apps → Manage your apps → Upload a custom app +5. **team チャネルの場合:** 新しい権限を有効にするには、各 team でアプリを再インストールします +6. キャッシュされたアプリメタデータをクリアするため、**Teams を完全終了して再起動**します（ウィンドウを閉じるだけでは不十分です） + +## 機能: RSC のみ vs Graph + +### **Teams RSC のみ**の場合（アプリはインストール済み、Graph API 権限なし） + +動作するもの: + +- チャネルメッセージの**テキスト**内容の読み取り。 +- チャネルメッセージの**テキスト**送信。 +- **personal（DM）** のファイル添付の受信。 + +動作しないもの: + +- チャネル/グループの**画像またはファイル内容**（ペイロードには HTML スタブしか含まれません）。 +- SharePoint/OneDrive に保存された添付ファイルのダウンロード。 +- メッセージ履歴の読み取り（ライブ webhook イベントを超えるもの）。 + +### **Teams RSC + Microsoft Graph Application permissions** の場合 + +追加されるもの: + +- ホストされたコンテンツのダウンロード（メッセージに貼り付けられた画像）。 +- SharePoint/OneDrive に保存されたファイル添付のダウンロード。 +- Graph 経由のチャネル/チャットメッセージ履歴の読み取り。 + +### RSC と Graph API の比較 + +| 機能 | RSC 権限 | Graph API | +| ----------------------- | -------------------- | ----------------------------------- | +| **リアルタイムメッセージ** | はい（webhook 経由） | いいえ（ポーリングのみ） | +| **過去メッセージ** | いいえ | はい（履歴を問い合わせ可能） | +| **セットアップの複雑さ** | アプリ manifest のみ | 管理者同意 + トークンフローが必要 | +| **オフライン動作** | いいえ（実行中である必要あり） | はい（いつでも問い合わせ可能） | + +**要点:** RSC はリアルタイムの受信向けであり、Graph API は過去のアクセス向けです。オフライン中に見逃したメッセージを取り込むには、`ChannelMessage.Read.All` を持つ Graph API が必要です（管理者同意が必要）。 + +## Graph 対応メディア + 履歴（チャネルでは必須） + +**チャネル**内で画像/ファイルが必要な場合、または**メッセージ履歴**を取得したい場合は、Microsoft Graph 権限を有効にして管理者同意を与える必要があります。 + +1. Entra ID（Azure AD）の **App Registration** で、Microsoft Graph の **Application permissions** を追加します: + - `ChannelMessage.Read.All`（チャネル添付 + 履歴） + - `Chat.Read.All` または `ChatMessage.Read.All`（グループチャット） +2. テナントに対して**管理者同意を付与**します。 +3. Teams アプリの **manifest version** を更新し、再アップロードして、**Teams 内でアプリを再インストール**します。 +4. キャッシュされたアプリメタデータをクリアするため、**Teams を完全終了して再起動**します。 + +**ユーザーメンション向け追加権限:** 会話内のユーザーに対する @mentions は、そのままで動作します。ただし、**現在の会話にいない**ユーザーを動的に検索してメンションしたい場合は、`User.Read.All`（Application）権限を追加し、管理者同意を付与してください。 + +## 既知の制限 + +### Webhook タイムアウト + +Teams は HTTP webhook 経由でメッセージを配信します。処理に時間がかかりすぎる場合（たとえば LLM 応答が遅い場合）、次のような問題が起こることがあります。 + +- Gateway のタイムアウト +- Teams によるメッセージの再試行（重複の原因） +- 返信の欠落 + +OpenClaw は、すばやく応答を返し、その後で proactive に返信を送ることでこれに対処していますが、非常に遅い応答では依然として問題が発生することがあります。 + +### 書式設定 + +Teams の markdown は Slack や Discord より制限があります。 + +- 基本的な書式は動作します: **太字**、_斜体_、`code`、リンク +- 複雑な markdown（表、ネストしたリスト）は正しくレンダリングされないことがあります +- 投票や任意のカード送信には Adaptive Cards をサポートしています（以下参照） + +## 設定 + +主要な設定（共有チャネルパターンについては `/gateway/configuration` を参照）: + +- `channels.msteams.enabled`: チャネルの有効/無効。 +- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`: ボット認証情報。 +- `channels.msteams.webhook.port`（既定 `3978`） +- `channels.msteams.webhook.path`（既定 `/api/messages`） +- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled`（既定: pairing） +- `channels.msteams.allowFrom`: DM 許可リスト（AAD オブジェクト ID 推奨）。Graph アクセスが利用可能な場合、ウィザードはセットアップ中に名前を ID に解決します。 +- `channels.msteams.dangerouslyAllowNameMatching`: 変更可能な UPN/表示名一致と、team/channel 名による直接ルーティングを再有効化するための非常用トグル。 +- `channels.msteams.textChunkLimit`: 送信テキストのチャンクサイズ。 +- `channels.msteams.chunkMode`: `length`（既定）または `newline`。長さでのチャンク化の前に、空行（段落境界）で分割します。 +- `channels.msteams.mediaAllowHosts`: 受信添付ファイルホストの許可リスト（既定は Microsoft/Teams ドメイン）。 +- `channels.msteams.mediaAuthAllowHosts`: メディア再試行時に Authorization ヘッダーを付けるホストの許可リスト（既定は Graph + Bot Framework ホスト）。 +- `channels.msteams.requireMention`: チャネル/グループで @mention を必須にする（既定 true）。 +- `channels.msteams.replyStyle`: `thread | top-level`（[返信スタイル](#reply-style-threads-vs-posts)を参照）。 +- `channels.msteams.teams..replyStyle`: team ごとの上書き。 +- `channels.msteams.teams..requireMention`: team ごとの上書き。 +- `channels.msteams.teams..tools`: team ごとの既定ツールポリシー上書き（`allow`/`deny`/`alsoAllow`）。チャネル上書きがない場合に使われます。 +- `channels.msteams.teams..toolsBySender`: team ごとの送信者別ツールポリシー上書き（`"*"` ワイルドカード対応）。 +- `channels.msteams.teams..channels..replyStyle`: チャネルごとの上書き。 +- `channels.msteams.teams..channels..requireMention`: チャネルごとの上書き。 +- `channels.msteams.teams..channels..tools`: チャネルごとのツールポリシー上書き（`allow`/`deny`/`alsoAllow`）。 +- `channels.msteams.teams..channels..toolsBySender`: チャネルごとの送信者別ツールポリシー上書き（`"*"` ワイルドカード対応）。 +- `toolsBySender` のキーには明示的な接頭辞を使うべきです: + `id:`、`e164:`、`username:`、`name:`（従来の接頭辞なしキーも引き続き `id:` にのみマップされます）。 +- `channels.msteams.actions.memberInfo`: Graph ベースの member info アクションを有効または無効にする（既定: Graph 認証情報がある場合は有効）。 +- `channels.msteams.sharePointSiteId`: グループチャット/チャネルでのファイルアップロード用 SharePoint site ID（[グループチャットでのファイル送信](#sending-files-in-group-chats)を参照）。 + +## ルーティングとセッション + +- セッションキーは標準のエージェント形式に従います（[/concepts/session](/concepts/session)を参照）: + - ダイレクトメッセージはメインセッションを共有します（`agent::`）。 + - チャネル/グループメッセージは conversation id を使います: + - `agent::msteams:channel:` + - `agent::msteams:group:` + +## 返信スタイル: スレッド vs 投稿 + +Teams は最近、同じ基盤データモデルの上で 2 種類のチャネル UI スタイルを導入しました。 + +| スタイル | 説明 | 推奨 `replyStyle` | +| ------------------------ | --------------------------------------------------------- | ------------------------ | +| **投稿**（クラシック） | メッセージはカードとして表示され、その下にスレッド返信が並ぶ | `thread`（既定） | +| **スレッド**（Slack 風） | メッセージが Slack のように直線的に流れる | `top-level` | + +**問題:** Teams API は、チャネルがどの UI スタイルを使っているかを公開しません。誤った `replyStyle` を使うと: + +- Threads スタイルのチャネルで `thread` → 返信が不自然にネストされて表示される +- Posts スタイルのチャネルで `top-level` → 返信がスレッド内ではなく独立したトップレベル投稿として表示される + +**解決策:** チャネルの設定に基づいて、チャネルごとに `replyStyle` を設定します。 + +```json5 +{ + channels: { + msteams: { + replyStyle: "thread", + teams: { + "19:abc...@thread.tacv2": { + channels: { + "19:xyz...@thread.tacv2": { + replyStyle: "top-level", + }, + }, + }, + }, + }, + }, +} +``` + +## 添付ファイルと画像 + +**現在の制限:** + +- **DM:** 画像とファイル添付は Teams ボットのファイル API 経由で動作します。 +- **チャネル/グループ:** 添付ファイルは M365 ストレージ（SharePoint/OneDrive）に存在します。webhook ペイロードには実際のファイルバイトではなく HTML スタブしか含まれません。チャネル添付をダウンロードするには **Graph API 権限が必要** です。 +- 明示的なファイル優先送信には、`media` / `filePath` / `path` とともに `action=upload-file` を使います。任意の `message` は付随するテキスト/コメントになり、`filename` はアップロード名を上書きします。 + +Graph 権限がない場合、画像付きのチャネルメッセージはテキストのみとして受信されます（画像内容にはボットからアクセスできません）。 +既定では、OpenClaw は Microsoft/Teams ホスト名からのみメディアをダウンロードします。`channels.msteams.mediaAllowHosts` で上書きできます（任意のホストを許可するには `["*"]` を使います）。 +Authorization ヘッダーは `channels.msteams.mediaAuthAllowHosts` に含まれるホストに対してのみ付与されます（既定は Graph + Bot Framework ホスト）。このリストは厳格に保ってください（multi-tenant サフィックスは避けてください）。 + +## グループチャットでのファイル送信 + +ボットは DM では FileConsentCard フロー（組み込み）を使ってファイルを送信できます。しかし、**グループチャット/チャネルでのファイル送信**には追加設定が必要です。 + +| コンテキスト | ファイル送信方法 | 必要なセットアップ | +| ------------------------ | -------------------------------------------- | ----------------------------------------------- | +| **DM** | FileConsentCard → ユーザーが承認 → ボットがアップロード | そのままで動作 | +| **グループチャット/チャネル** | SharePoint にアップロード → 共有リンク | `sharePointSiteId` + Graph 権限が必要 | +| **画像（任意のコンテキスト）** | Base64 エンコードされたインライン | そのままで動作 | + +### グループチャットで SharePoint が必要な理由 + +ボットには personal OneDrive ドライブがありません（`/me/drive` Graph API endpoint は application identity では動作しません）。グループチャット/チャネルでファイルを送るには、ボットは **SharePoint site** にアップロードし、共有リンクを作成します。 + +### セットアップ + +1. Entra ID（Azure AD）→ App Registration で **Graph API 権限** を追加します: + - `Sites.ReadWrite.All`（Application）- SharePoint へファイルをアップロード + - `Chat.Read.All`（Application）- 任意。ユーザーごとの共有リンクを有効化 + +2. テナントに対して**管理者同意を付与**します。 + +3. **SharePoint site ID を取得します:** + + ```bash + # Graph Explorer または有効なトークン付き curl 経由: + curl -H "Authorization: Bearer $TOKEN" \ + "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}" + + # 例: "contoso.sharepoint.com/sites/BotFiles" にある site の場合 + curl -H "Authorization: Bearer $TOKEN" \ + "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles" + + # 応答には次が含まれます: "id": "contoso.sharepoint.com,guid1,guid2" + ``` + +4. **OpenClaw を設定します:** + + ```json5 + { + channels: { + msteams: { + // ... other config ... + sharePointSiteId: "contoso.sharepoint.com,guid1,guid2", + }, + }, + } + ``` + +### 共有動作 + +| 権限 | 共有動作 | +| --------------------------------------- | --------------------------------------------------------- | +| `Sites.ReadWrite.All` のみ | 組織全体の共有リンク（組織内の誰でもアクセス可能） | +| `Sites.ReadWrite.All` + `Chat.Read.All` | ユーザーごとの共有リンク（チャットメンバーのみアクセス可能） | + +ユーザーごとの共有の方が、チャット参加者のみがファイルにアクセスできるため、より安全です。`Chat.Read.All` 権限がない場合、ボットは組織全体共有にフォールバックします。 + +### フォールバック動作 + +| シナリオ | 結果 | +| ------------------------------------------------- | -------------------------------------------------- | +| グループチャット + ファイル + `sharePointSiteId` 設定済み | SharePoint にアップロードし、共有リンクを送信 | +| グループチャット + ファイル + `sharePointSiteId` なし | OneDrive アップロードを試行（失敗する場合あり）、テキストのみ送信 | +| personal チャット + ファイル | FileConsentCard フロー（SharePoint なしで動作） | +| 任意のコンテキスト + 画像 | Base64 エンコードされたインライン（SharePoint なしで動作） | + +### ファイルの保存場所 + +アップロードされたファイルは、設定された SharePoint site の既定ドキュメントライブラリ内の `/OpenClawShared/` フォルダに保存されます。 + +## 投票（Adaptive Cards） + +OpenClaw は Teams の投票を Adaptive Cards として送信します（Teams ネイティブの poll API はありません）。 + +- CLI: `openclaw message poll --channel msteams --target conversation: ...` +- 投票は Gateway によって `~/.openclaw/msteams-polls.json` に記録されます。 +- 投票を記録するには Gateway がオンラインのままである必要があります。 +- 投票結果の要約はまだ自動投稿されません（必要に応じてストアファイルを確認してください）。 + +## Adaptive Cards（任意） + +`message` ツールまたは CLI を使って、任意の Adaptive Card JSON を Teams ユーザーまたは会話に送信できます。 + +`card` パラメータは Adaptive Card JSON オブジェクトを受け取ります。`card` が指定されている場合、メッセージテキストは任意です。 + +**エージェントツール:** + +```json5 +{ + action: "send", + channel: "msteams", + target: "user:", + card: { + type: "AdaptiveCard", + version: "1.5", + body: [{ type: "TextBlock", text: "Hello!" }], + }, +} +``` + +**CLI:** + +```bash +openclaw message send --channel msteams \ + --target "conversation:19:abc...@thread.tacv2" \ + --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}' +``` + +カードスキーマと例については、[Adaptive Cards documentation](https://adaptivecards.io/) を参照してください。target 形式の詳細については、以下の[ターゲット形式](#target-formats)を参照してください。 + +## ターゲット形式 + +MSTeams の target では、ユーザーと会話を区別するために接頭辞を使います。 + +| ターゲット種別 | 形式 | 例 | +| ------------------- | -------------------------------- | --------------------------------------------------- | +| ユーザー（ID 指定） | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | +| ユーザー（名前指定） | `user:` | `user:John Smith`（Graph API が必要） | +| グループ/チャネル | `conversation:` | `conversation:19:abc123...@thread.tacv2` | +| グループ/チャネル（生値） | `` | `19:abc123...@thread.tacv2`（`@thread` を含む場合） | + +**CLI の例:** + +```bash +# ID でユーザーに送信 +openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello" + +# 表示名でユーザーに送信（Graph API 検索をトリガー） +openclaw message send --channel msteams --target "user:John Smith" --message "Hello" + +# グループチャットまたはチャネルに送信 +openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello" + +# 会話に Adaptive Card を送信 +openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \ + --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}' +``` + +**エージェントツールの例:** + +```json5 +{ + action: "send", + channel: "msteams", + target: "user:John Smith", + message: "Hello!", +} +``` + +```json5 +{ + action: "send", + channel: "msteams", + target: "conversation:19:abc...@thread.tacv2", + card: { + type: "AdaptiveCard", + version: "1.5", + body: [{ type: "TextBlock", text: "Hello" }], + }, +} +``` + +注: `user:` 接頭辞がない場合、名前は既定でグループ/team 解決になります。表示名で人を指定する場合は、必ず `user:` を使ってください。 + +## Proactive メッセージング + +- Proactive メッセージは、会話参照をその時点で保存するため、ユーザーがやり取りした**後でのみ**可能です。 +- `dmPolicy` と許可リストゲートについては `/gateway/configuration` を参照してください。 + +## Team と Channel ID（よくある落とし穴） + +Teams URL の `groupId` クエリパラメータは、設定に使う team ID **ではありません**。代わりに URL パスから ID を抽出してください。 + +**Team URL:** + +``` +https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=... + └────────────────────────────┘ + Team ID（これを URL デコードします） +``` + +**Channel URL:** + +``` +https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=... + └─────────────────────────┘ + Channel ID（これを URL デコードします） +``` + +**設定用:** + +- Team ID = `/team/` の後のパスセグメント（URL デコードしたもの。例: `19:Bk4j...@thread.tacv2`） +- Channel ID = `/channel/` の後のパスセグメント（URL デコードしたもの） +- `groupId` クエリパラメータは**無視**します + +## プライベートチャネル + +ボットはプライベートチャネルではサポートが限定的です。 + +| 機能 | 標準チャネル | プライベートチャネル | +| ---------------------------- | ----------------- | ---------------------- | +| ボットインストール | はい | 限定的 | +| リアルタイムメッセージ（webhook） | はい | 動作しない場合あり | +| RSC 権限 | はい | 動作が異なる場合あり | +| @mentions | はい | ボットにアクセスできる場合 | +| Graph API 履歴 | はい（権限あり） | はい（権限あり） | + +**プライベートチャネルで動作しない場合の回避策:** + +1. ボットとのやり取りには標準チャネルを使う +2. DM を使う - ユーザーは常にボットへ直接メッセージできます +3. 過去アクセスには Graph API を使う（`ChannelMessage.Read.All` が必要） + +## トラブルシューティング + +### よくある問題 + +- **チャネルで画像が表示されない:** Graph 権限または管理者同意が不足しています。Teams アプリを再インストールし、Teams を完全終了して再起動してください。 +- **チャネルで応答がない:** 既定ではメンションが必要です。`channels.msteams.requireMention=false` を設定するか、team/channel ごとに設定してください。 +- **バージョン不一致（Teams に古い manifest が表示される）:** アプリを削除して再追加し、Teams を完全終了して更新してください。 +- **webhook から 401 Unauthorized:** Azure JWT なしで手動テストした場合は想定内です。endpoint には到達しているが認証に失敗したことを意味します。正しくテストするには Azure Web Chat を使ってください。 + +### Manifest のアップロードエラー + +- **「Icon file cannot be empty」:** manifest が 0 バイトのアイコンファイルを参照しています。有効な PNG アイコンを作成してください（`outline.png` は 32x32、`color.png` は 192x192）。 +- **「webApplicationInfo.Id already in use」:** アプリが別の team/chat にまだインストールされています。先に見つけてアンインストールするか、反映まで 5〜10 分待ってください。 +- **アップロード時に「Something went wrong」:** 代わりに [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) 経由でアップロードし、ブラウザ DevTools（F12）→ Network タブを開いて、レスポンス本文の実際のエラーを確認してください。 +- **サイドロードに失敗する:** 「Upload a custom app」ではなく、「Upload an app to your org's app catalog」を試してください。こちらの方が sideload 制限を回避できることがよくあります。 + +### RSC 権限が動作しない + +1. `webApplicationInfo.id` がボットの App ID と完全一致していることを確認します +2. アプリを再アップロードし、team/chat に再インストールします +3. 組織管理者が RSC 権限をブロックしていないか確認します +4. 正しいスコープを使っていることを確認します: teams には `ChannelMessage.Read.Group`、グループチャットには `ChatMessage.Read.Chat` + +## 参考資料 + +- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - Azure Bot セットアップガイド +- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - Teams アプリの作成/管理 +- [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) +- [Receive channel messages with RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) +- [RSC permissions reference](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) +- [Teams bot file handling](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4)（チャネル/グループでは Graph が必要） +- [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) + +## 関連 + +- [チャネル概要](/channels) — サポートされているすべてのチャネル +- [ペアリング](/channels/pairing) — DM 認証とペアリングフロー +- [グループ](/channels/groups) — グループチャットの動作とメンションゲート +- [チャネルルーティング](/channels/channel-routing) — メッセージのセッションルーティング +- [セキュリティ](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/nextcloud-talk.md b/docs/ja-JP/channels/nextcloud-talk.md new file mode 100644 index 000000000..02f6541fd --- /dev/null +++ b/docs/ja-JP/channels/nextcloud-talk.md @@ -0,0 +1,154 @@ +--- +read_when: + - Nextcloud Talkチャンネル機能に取り組むとき +summary: Nextcloud Talkサポートのステータス、機能、設定 +title: Nextcloud Talk +x-i18n: + generated_at: "2026-04-05T12:35:56Z" + model: gpt-5.4 + provider: openai + source_hash: 900402afe67cf3ce96103d55158eb28cffb29c9845b77248e70d7653b12ae810 + source_path: channels/nextcloud-talk.md + workflow: 15 +--- + +# Nextcloud Talk + +ステータス: バンドル済みplugin（Webhook bot）。ダイレクトメッセージ、ルーム、リアクション、Markdownメッセージがサポートされています。 + +## バンドル済みplugin + +Nextcloud Talkは現在のOpenClawリリースではバンドル済みpluginとして提供されるため、通常のパッケージ済みビルドでは別途インストールは不要です。 + +古いビルドまたはNextcloud Talkを除外したカスタムインストールを使用している場合は、手動でインストールしてください。 + +CLI経由でインストール（npmレジストリ）: + +```bash +openclaw plugins install @openclaw/nextcloud-talk +``` + +ローカルチェックアウト（gitリポジトリから実行している場合）: + +```bash +openclaw plugins install ./path/to/local/nextcloud-talk-plugin +``` + +詳細: [Plugins](/tools/plugin) + +## クイックセットアップ（初級者向け） + +1. Nextcloud Talk pluginが利用可能であることを確認します。 + - 現在のパッケージ済みOpenClawリリースには、すでにバンドルされています。 + - 古いインストールやカスタムインストールでは、上記コマンドで手動追加できます。 +2. Nextcloudサーバーでbotを作成します。 + + ```bash + ./occ talk:bot:install "OpenClaw" "" "" --feature reaction + ``` + +3. 対象ルームの設定でbotを有効にします。 +4. OpenClawを設定します。 + - Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret` + - またはenv: `NEXTCLOUD_TALK_BOT_SECRET`（デフォルトアカウントのみ） +5. Gatewayを再起動します（またはセットアップを完了します）。 + +最小構成: + +```json5 +{ + channels: { + "nextcloud-talk": { + enabled: true, + baseUrl: "https://cloud.example.com", + botSecret: "shared-secret", + dmPolicy: "pairing", + }, + }, +} +``` + +## 注意点 + +- botはDMを開始できません。ユーザー側から先にbotへメッセージを送る必要があります。 +- Webhook URLはGatewayから到達可能である必要があります。プロキシの背後にある場合は`webhookPublicUrl`を設定してください。 +- bot APIではメディアアップロードはサポートされていません。メディアはURLとして送信されます。 +- WebhookペイロードではDMとルームを区別できません。ルーム種別のルックアップを有効にするには`apiUser` + `apiPassword`を設定してください（設定しない場合、DMはルームとして扱われます）。 + +## アクセス制御（DM） + +- デフォルト: `channels.nextcloud-talk.dmPolicy = "pairing"`。未知の送信者にはpairingコードが送られます。 +- 承認方法: + - `openclaw pairing list nextcloud-talk` + - `openclaw pairing approve nextcloud-talk ` +- 公開DM: `channels.nextcloud-talk.dmPolicy="open"`に加えて`channels.nextcloud-talk.allowFrom=["*"]`。 +- `allowFrom`はNextcloudユーザーIDのみに一致します。表示名は無視されます。 + +## ルーム（グループ） + +- デフォルト: `channels.nextcloud-talk.groupPolicy = "allowlist"`（mentionゲートあり）。 +- `channels.nextcloud-talk.rooms`でルームをallowlistに追加します。 + +```json5 +{ + channels: { + "nextcloud-talk": { + rooms: { + "room-token": { requireMention: true }, + }, + }, + }, +} +``` + +- ルームを一切許可しない場合は、allowlistを空のままにするか、`channels.nextcloud-talk.groupPolicy="disabled"`を設定してください。 + +## 機能 + +| 機能 | ステータス | +| ------------------ | --------------- | +| ダイレクトメッセージ | サポート済み | +| ルーム | サポート済み | +| スレッド | 未サポート | +| メディア | URLのみ | +| リアクション | サポート済み | +| ネイティブコマンド | 未サポート | + +## 設定リファレンス（Nextcloud Talk） + +完全な設定: [Configuration](/gateway/configuration) + +プロバイダーオプション: + +- `channels.nextcloud-talk.enabled`: チャンネル起動の有効化/無効化。 +- `channels.nextcloud-talk.baseUrl`: NextcloudインスタンスURL。 +- `channels.nextcloud-talk.botSecret`: bot共有シークレット。 +- `channels.nextcloud-talk.botSecretFile`: 通常ファイルのシークレットパス。シンボリックリンクは拒否されます。 +- `channels.nextcloud-talk.apiUser`: ルームルックアップ用APIユーザー（DM検出）。 +- `channels.nextcloud-talk.apiPassword`: ルームルックアップ用API/アプリパスワード。 +- `channels.nextcloud-talk.apiPasswordFile`: APIパスワードファイルのパス。 +- `channels.nextcloud-talk.webhookPort`: Webhookリスナーポート（デフォルト: 8788）。 +- `channels.nextcloud-talk.webhookHost`: Webhookホスト（デフォルト: 0.0.0.0）。 +- `channels.nextcloud-talk.webhookPath`: Webhookパス（デフォルト: /nextcloud-talk-webhook）。 +- `channels.nextcloud-talk.webhookPublicUrl`: 外部から到達可能なWebhook URL。 +- `channels.nextcloud-talk.dmPolicy`: `pairing | allowlist | open | disabled`。 +- `channels.nextcloud-talk.allowFrom`: DM allowlist（ユーザーID）。`open`には`"*"`が必要です。 +- `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`。 +- `channels.nextcloud-talk.groupAllowFrom`: グループallowlist（ユーザーID）。 +- `channels.nextcloud-talk.rooms`: ルームごとの設定とallowlist。 +- `channels.nextcloud-talk.historyLimit`: グループ履歴の上限（0で無効）。 +- `channels.nextcloud-talk.dmHistoryLimit`: DM履歴の上限（0で無効。 +- `channels.nextcloud-talk.dms`: DMごとのオーバーライド（`historyLimit`）。 +- `channels.nextcloud-talk.textChunkLimit`: 送信テキストのチャンクサイズ（文字数）。 +- `channels.nextcloud-talk.chunkMode`: `length`（デフォルト）または`newline`。長さで分割する前に空行（段落境界）で分割します。 +- `channels.nextcloud-talk.blockStreaming`: このチャンネルのブロックストリーミングを無効化。 +- `channels.nextcloud-talk.blockStreamingCoalesce`: ブロックストリーミングのcoalesce調整。 +- `channels.nextcloud-talk.mediaMaxMb`: 受信メディア上限（MB）。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャンネル +- [Pairing](/channels/pairing) — DM認証とpairingフロー +- [Groups](/channels/groups) — グループチャットの動作とmentionゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/nostr.md b/docs/ja-JP/channels/nostr.md new file mode 100644 index 000000000..b60b724a0 --- /dev/null +++ b/docs/ja-JP/channels/nostr.md @@ -0,0 +1,257 @@ +--- +read_when: + - OpenClaw が Nostr 経由で DM を受信できるようにしたいとき + - 分散型メッセージングを設定しているとき +summary: NIP-04 暗号化メッセージ経由の Nostr DM チャネル +title: Nostr +x-i18n: + generated_at: "2026-04-05T12:36:05Z" + model: gpt-5.4 + provider: openai + source_hash: f82829ee66fbeb3367007af343797140049ea49f2e842a695fa56acea0c80728 + source_path: channels/nostr.md + workflow: 15 +--- + +# Nostr + +**ステータス:** オプションのバンドル済みプラグイン（設定されるまでデフォルトでは無効）。 + +Nostr はソーシャルネットワーキングのための分散型プロトコルです。このチャネルにより、OpenClaw は NIP-04 を介した暗号化ダイレクトメッセージ（DM）を受信して返信できるようになります。 + +## バンドル済みプラグイン + +現在の OpenClaw リリースでは、Nostr はバンドル済みプラグインとして提供されているため、通常のパッケージ版ビルドでは個別のインストールは不要です。 + +### 古いインストール / カスタムインストール + +- オンボーディング（`openclaw onboard`）と `openclaw channels add` では、共有チャネルカタログから引き続き Nostr が表示されます。 +- 使用中のビルドにバンドル済み Nostr が含まれていない場合は、手動でインストールしてください。 + +```bash +openclaw plugins install @openclaw/nostr +``` + +ローカルチェックアウトを使用する場合（開発ワークフロー）: + +```bash +openclaw plugins install --link +``` + +プラグインをインストールまたは有効化した後は Gateway を再起動してください。 + +### 非対話型セットアップ + +```bash +openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" +openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net" +``` + +鍵を config に保存せず環境変数に保持するには、`--use-env` を使用してください。 + +## クイックセットアップ + +1. Nostr のキーペアを生成します（必要な場合）。 + +```bash +# nak を使用 +nak key generate +``` + +2. config に追加します。 + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + }, + }, +} +``` + +3. 鍵を export します。 + +```bash +export NOSTR_PRIVATE_KEY="nsec1..." +``` + +4. Gateway を再起動します。 + +## 設定リファレンス + +| Key | Type | Default | Description | +| ------------ | -------- | ------------------------------------------- | ----------------------------------- | +| `privateKey` | string | 必須 | `nsec` または hex 形式の秘密鍵 | +| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | Relay URL（WebSocket） | +| `dmPolicy` | string | `pairing` | DM アクセスポリシー | +| `allowFrom` | string[] | `[]` | 許可する送信者 pubkey | +| `enabled` | boolean | `true` | チャネルの有効化 / 無効化 | +| `name` | string | - | 表示名 | +| `profile` | object | - | NIP-01 profile metadata | + +## プロファイルメタデータ + +プロファイルデータは NIP-01 `kind:0` イベントとして公開されます。Control UI（Channels -> Nostr -> Profile）から管理するか、config に直接設定できます。 + +例: + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + profile: { + name: "openclaw", + displayName: "OpenClaw", + about: "Personal assistant DM bot", + picture: "https://example.com/avatar.png", + banner: "https://example.com/banner.png", + website: "https://example.com", + nip05: "openclaw@example.com", + lud16: "openclaw@example.com", + }, + }, + }, +} +``` + +注: + +- プロファイル URL には `https://` を使用する必要があります。 +- relay からのインポートではフィールドがマージされ、ローカルの上書きが保持されます。 + +## アクセス制御 + +### DM ポリシー + +- **pairing**（デフォルト）: 未知の送信者には pairing code が送られます。 +- **allowlist**: `allowFrom` にある pubkey のみが DM を送信できます。 +- **open**: 公開の受信 DM（`allowFrom: ["*"]` が必要）。 +- **disabled**: 受信 DM を無視します。 + +適用に関する注記: + +- 受信イベントの署名は、送信者ポリシーと NIP-04 復号の前に検証されるため、偽造イベントは早期に拒否されます。 +- pairing の返信は、元の DM body を処理せずに送信されます。 +- 受信 DM にはレート制限が適用され、サイズ超過のペイロードは復号前に破棄されます。 + +### allowlist の例 + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + dmPolicy: "allowlist", + allowFrom: ["npub1abc...", "npub1xyz..."], + }, + }, +} +``` + +## 鍵形式 + +受け入れられる形式: + +- **秘密鍵:** `nsec...` または 64 文字の hex +- **Pubkey (`allowFrom`):** `npub...` または hex + +## Relay + +デフォルト: `relay.damus.io` と `nos.lol`。 + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + relays: ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"], + }, + }, +} +``` + +ヒント: + +- 冗長性のために 2〜3 個の relay を使用してください。 +- relay を増やしすぎないでください（遅延、重複）。 +- 有料 relay により信頼性が向上する場合があります。 +- テストにはローカル relay も使えます（`ws://localhost:7777`）。 + +## プロトコルサポート + +| NIP | Status | Description | +| ------ | ---------- | ---------------------------------- | +| NIP-01 | サポート済み | 基本イベント形式 + プロファイルメタデータ | +| NIP-04 | サポート済み | 暗号化 DM（`kind:4`） | +| NIP-17 | 計画中 | Gift-wrapped DM | +| NIP-44 | 計画中 | バージョン付き暗号化 | + +## テスト + +### ローカル relay + +```bash +# strfry を起動 +docker run -p 7777:7777 ghcr.io/hoytech/strfry +``` + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + relays: ["ws://localhost:7777"], + }, + }, +} +``` + +### 手動テスト + +1. ログから bot の pubkey（npub）を確認します。 +2. Nostr クライアント（Damus、Amethyst など）を開きます。 +3. bot の pubkey に DM を送ります。 +4. 返信を確認します。 + +## トラブルシューティング + +### メッセージを受信できない + +- 秘密鍵が有効であることを確認してください。 +- relay URL に到達可能で、`wss://`（ローカルでは `ws://`）を使っていることを確認してください。 +- `enabled` が `false` ではないことを確認してください。 +- relay 接続エラーについて Gateway ログを確認してください。 + +### 返信を送信できない + +- relay が書き込みを受け付けていることを確認してください。 +- 外向き接続を確認してください。 +- relay のレート制限に注意してください。 + +### 重複返信 + +- 複数の relay を使用している場合は想定内です。 +- メッセージはイベント ID で重複排除され、最初の配信のみが返信を引き起こします。 + +## セキュリティ + +- 秘密鍵は絶対にコミットしないでください。 +- 鍵には環境変数を使用してください。 +- 本番 bot では `allowlist` を検討してください。 +- 署名は送信者ポリシーの前に検証され、送信者ポリシーは復号の前に適用されるため、偽造イベントは早期に拒否され、未知の送信者が完全な暗号処理を強制することはできません。 + +## 制限事項（MVP） + +- ダイレクトメッセージのみ（グループチャットなし）。 +- メディア添付なし。 +- NIP-04 のみ（NIP-17 gift-wrap は計画中）。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャネル +- [Pairing](/channels/pairing) — DM 認証と pairing フロー +- [Groups](/channels/groups) — グループチャットの動作と mention ゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/pairing.md b/docs/ja-JP/channels/pairing.md new file mode 100644 index 000000000..b5fa6948a --- /dev/null +++ b/docs/ja-JP/channels/pairing.md @@ -0,0 +1,129 @@ +--- +read_when: + - DM アクセス制御を設定するとき + - 新しい iOS/Android ノードをペアリングするとき + - OpenClaw のセキュリティ体制を確認するとき +summary: 'ペアリングの概要: 誰があなたに DM できるかと、どのノードが参加できるかを承認' +title: ペアリング +x-i18n: + generated_at: "2026-04-05T12:36:14Z" + model: gpt-5.4 + provider: openai + source_hash: 2bd99240b3530def23c05a26915d07cf8b730565c2822c6338437f8fb3f285c9 + source_path: channels/pairing.md + workflow: 15 +--- + +# ペアリング + +「ペアリング」は、OpenClaw における明示的な**オーナー承認**ステップです。 +これは次の 2 つの場面で使われます。 + +1. **DM ペアリング**（誰が bot と会話できるか） +2. **ノードペアリング**（どのデバイス/ノードが Gateway ネットワークに参加できるか） + +セキュリティの背景: [Security](/gateway/security) + +## 1) DM ペアリング（受信チャットアクセス） + +チャネルで DM ポリシー `pairing` が設定されている場合、未知の送信者には短いコードが送られ、そのメッセージはあなたが承認するまで**処理されません**。 + +デフォルトの DM ポリシーは次に記載されています: [Security](/gateway/security) + +ペアリングコード: + +- 8 文字、大文字、紛らわしい文字なし（`0O1I`）。 +- **1 時間で期限切れ**になります。bot は、新しいリクエストが作成されたときにのみペアリングメッセージを送信します（送信者ごとにチャネルあたりおよそ 1 時間に 1 回）。 +- 保留中の DM ペアリングリクエストは、デフォルトで**チャネルごとに 3 件**までです。1 件が期限切れになるか承認されるまで、それ以上のリクエストは無視されます。 + +### 送信者を承認する + +```bash +openclaw pairing list telegram +openclaw pairing approve telegram +``` + +サポートされるチャネル: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`. + +### 状態の保存場所 + +`~/.openclaw/credentials/` の下に保存されます。 + +- 保留中リクエスト: `-pairing.json` +- 承認済み allowlist ストア: + - デフォルトアカウント: `-allowFrom.json` + - 非デフォルトアカウント: `--allowFrom.json` + +アカウントスコープの動作: + +- 非デフォルトアカウントは、そのスコープ付き allowlist ファイルのみを読み書きします。 +- デフォルトアカウントは、チャネルスコープのスコープなし allowlist ファイルを使います。 + +これらは機密情報として扱ってください（アシスタントへのアクセスを制御します）。 + +重要: このストアは DM アクセス用です。グループ認可は別です。 +DM ペアリングコードを承認しても、その送信者がグループコマンドを実行したり、グループ内で bot を操作したりできるようになるわけではありません。グループアクセスについては、そのチャネルの明示的なグループ allowlist（たとえば `groupAllowFrom`、`groups`、またはチャネルに応じたグループごと/トピックごとの上書き）を設定してください。 + +## 2) ノードデバイスのペアリング（iOS/Android/macOS/ヘッドレスノード） + +ノードは `role: node` を持つ**デバイス**として Gateway に接続します。Gateway は、承認が必要なデバイスペアリングリクエストを作成します。 + +### Telegram 経由でペアリングする（iOS 推奨） + +`device-pair` plugin を使っている場合、初回のデバイスペアリングは Telegram だけで完結できます。 + +1. Telegram で bot にメッセージを送信します: `/pair` +2. bot は 2 つのメッセージで返信します。1 つは説明メッセージ、もう 1 つは別送の**セットアップコード**メッセージです（Telegram で簡単にコピー&ペーストできます）。 +3. 電話で OpenClaw iOS アプリを開き、Settings → Gateway に進みます。 +4. セットアップコードを貼り付けて接続します。 +5. Telegram に戻って `/pair pending` を実行し、リクエスト ID、role、scope を確認してから承認します。 + +セットアップコードは base64 エンコードされた JSON ペイロードで、次を含みます。 + +- `url`: Gateway の WebSocket URL（`ws://...` または `wss://...`） +- `bootstrapToken`: 初期ペアリングハンドシェイクで使う、単一デバイス向けの短命な bootstrap トークン + +その bootstrap トークンには、組み込みのペアリング bootstrap プロファイルが含まれます。 + +- 引き渡される主要な `node` トークンは `scopes: []` のままです +- 引き渡される `operator` トークンは、bootstrap allowlist に制限されたままです: + `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` +- bootstrap の scope チェックは、1 つのフラットな scope プールではなく role 接頭辞付きです: + operator の scope エントリは operator リクエストに対してのみ有効であり、operator 以外の role は引き続き自分自身の role 接頭辞の下で scope を要求する必要があります + +セットアップコードが有効な間は、パスワードのように扱ってください。 + +### ノードデバイスを承認する + +```bash +openclaw devices list +openclaw devices approve +openclaw devices reject +``` + +同じデバイスが異なる認証詳細（たとえば異なる role/scope/public key）で再試行した場合、以前の保留中リクエストは置き換えられ、新しい `requestId` が作成されます。 + +### ノードペアリング状態の保存場所 + +`~/.openclaw/devices/` の下に保存されます。 + +- `pending.json`（短命。保留中リクエストは期限切れになります） +- `paired.json`（ペアリング済みデバイス + トークン） + +### 注記 + +- レガシーな `node.pair.*` API（CLI: `openclaw nodes pending|approve|reject|rename`）は、別個の Gateway 所有ペアリングストアです。WS ノードでは引き続きデバイスペアリングが必要です。 +- ペアリングレコードは、承認済み role の耐久的な正規ソースです。アクティブなデバイストークンは、その承認済み role セットに制限されたままです。承認済み role の外側にある余分なトークンエントリが、新しいアクセスを生み出すことはありません。 + +## 関連ドキュメント + +- セキュリティモデル + プロンプトインジェクション: [Security](/gateway/security) +- 安全な更新（doctor を実行）: [Updating](/install/updating) +- チャネル設定: + - Telegram: [Telegram](/channels/telegram) + - WhatsApp: [WhatsApp](/channels/whatsapp) + - Signal: [Signal](/channels/signal) + - BlueBubbles（iMessage）: [BlueBubbles](/channels/bluebubbles) + - iMessage（レガシー）: [iMessage](/channels/imessage) + - Discord: [Discord](/channels/discord) + - Slack: [Slack](/channels/slack) diff --git a/docs/ja-JP/channels/qqbot.md b/docs/ja-JP/channels/qqbot.md new file mode 100644 index 000000000..503ac616d --- /dev/null +++ b/docs/ja-JP/channels/qqbot.md @@ -0,0 +1,199 @@ +--- +read_when: + - OpenClawをQQに接続したいとき + - QQ Botの認証情報セットアップが必要なとき + - QQ Botのグループまたはプライベートチャット対応を使いたいとき +summary: QQ Botのセットアップ、設定、使用方法 +title: QQ Bot +x-i18n: + generated_at: "2026-04-05T12:36:13Z" + model: gpt-5.4 + provider: openai + source_hash: 0e58fb7b07c59ecbf80a1276368c4a007b45d84e296ed40cffe9845e0953696c + source_path: channels/qqbot.md + workflow: 15 +--- + +# QQ Bot + +QQ Botは、公式のQQ Bot API（WebSocket Gateway）を介してOpenClawに接続します。 +このプラグインは、C2Cプライベートチャット、グループの@メッセージ、ギルドチャンネルメッセージと、 +リッチメディア（画像、音声、動画、ファイル）をサポートします。 + +ステータス: バンドル済みプラグイン。ダイレクトメッセージ、グループチャット、ギルドチャンネル、 +メディアをサポートしています。リアクションとスレッドはサポートしていません。 + +## バンドル済みプラグイン + +現在のOpenClawリリースにはQQ Botがバンドルされているため、通常のパッケージ済みビルドでは +別途`openclaw plugins install`手順は不要です。 + +## セットアップ + +1. [QQ Open Platform](https://q.qq.com/)にアクセスし、 + スマートフォンのQQでQRコードをスキャンして登録またはログインします。 +2. **Create Bot**をクリックして、新しいQQボットを作成します。 +3. ボットの設定ページで**AppID**と**AppSecret**を見つけてコピーします。 + +> AppSecretは平文では保存されません。保存せずにページを離れると、 +> 新しいものを再生成する必要があります。 + +4. チャンネルを追加します。 + +```bash +openclaw channels add --channel qqbot --token "AppID:AppSecret" +``` + +5. Gatewayを再起動します。 + +対話型セットアップ手順: + +```bash +openclaw channels add +openclaw configure --section channels +``` + +## 設定 + +最小構成: + +```json5 +{ + channels: { + qqbot: { + enabled: true, + appId: "YOUR_APP_ID", + clientSecret: "YOUR_APP_SECRET", + }, + }, +} +``` + +デフォルトアカウント用環境変数: + +- `QQBOT_APP_ID` +- `QQBOT_CLIENT_SECRET` + +ファイルベースのAppSecret: + +```json5 +{ + channels: { + qqbot: { + enabled: true, + appId: "YOUR_APP_ID", + clientSecretFile: "/path/to/qqbot-secret.txt", + }, + }, +} +``` + +注意事項: + +- 環境変数のフォールバックは、デフォルトのQQ Botアカウントにのみ適用されます。 +- `openclaw channels add --channel qqbot --token-file ...`は + AppSecretのみを提供します。AppIDは設定または`QQBOT_APP_ID`ですでに設定されている必要があります。 +- `clientSecret`は平文文字列だけでなく、SecretRef入力も受け付けます。 + +### 複数アカウント設定 + +1つのOpenClawインスタンスで複数のQQボットを実行します。 + +```json5 +{ + channels: { + qqbot: { + enabled: true, + appId: "111111111", + clientSecret: "secret-of-bot-1", + accounts: { + bot2: { + enabled: true, + appId: "222222222", + clientSecret: "secret-of-bot-2", + }, + }, + }, + }, +} +``` + +各アカウントは独自のWebSocket接続を起動し、 +独立したトークンキャッシュ（`appId`ごとに分離）を維持します。 + +CLIで2つ目のボットを追加する: + +```bash +openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2" +``` + +### 音声（STT / TTS） + +STTとTTSは、優先度付きフォールバックを持つ2段階設定をサポートします。 + +| 設定 | プラグイン固有 | フレームワークのフォールバック | +| ------- | -------------------- | ----------------------------- | +| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | +| TTS | `channels.qqbot.tts` | `messages.tts` | + +```json5 +{ + channels: { + qqbot: { + stt: { + provider: "your-provider", + model: "your-stt-model", + }, + tts: { + provider: "your-provider", + model: "your-tts-model", + voice: "your-voice", + }, + }, + }, +} +``` + +無効化するには、いずれかに`enabled: false`を設定します。 + +送信音声のアップロード/トランスコード動作は、 +`channels.qqbot.audioFormatPolicy`でも調整できます。 + +- `sttDirectFormats` +- `uploadDirectFormats` +- `transcodeEnabled` + +## 対象フォーマット + +| フォーマット | 説明 | +| -------------------------- | ------------------ | +| `qqbot:c2c:OPENID` | プライベートチャット（C2C） | +| `qqbot:group:GROUP_OPENID` | グループチャット | +| `qqbot:channel:CHANNEL_ID` | ギルドチャンネル | + +> 各ボットは独自のユーザーOpenIDセットを持ちます。Bot Aで受信したOpenIDは、Bot B経由でメッセージ送信に**使用できません**。 + +## スラッシュコマンド + +AIキューより前にインターセプトされる組み込みコマンド: + +| コマンド | 説明 | +| -------------- | ------------------------------------ | +| `/bot-ping` | レイテンシーテスト | +| `/bot-version` | OpenClawフレームワークのバージョンを表示 | +| `/bot-help` | すべてのコマンドを一覧表示 | +| `/bot-upgrade` | QQBotアップグレードガイドのリンクを表示 | +| `/bot-logs` | 最近のGatewayログをファイルとしてエクスポート | + +使用方法のヘルプを見るには、任意のコマンドに`?`を付けます（例: `/bot-upgrade ?`）。 + +## トラブルシューティング + +- **ボットが「gone to Mars」と返信する:** 認証情報が設定されていないか、Gatewayが起動していません。 +- **受信メッセージがない:** `appId`と`clientSecret`が正しいこと、および + QQ Open Platformでボットが有効になっていることを確認してください。 +- **`--token-file`でセットアップしても未設定と表示される:** `--token-file`は + AppSecretのみを設定します。`appId`は設定または`QQBOT_APP_ID`で別途必要です。 +- **プロアクティブメッセージが届かない:** ユーザーが最近やり取りしていない場合、 + QQがボット主導メッセージを遮断することがあります。 +- **音声が文字起こしされない:** STTが設定されており、プロバイダーに到達可能であることを確認してください。 diff --git a/docs/ja-JP/channels/signal.md b/docs/ja-JP/channels/signal.md new file mode 100644 index 000000000..bf52cedcc --- /dev/null +++ b/docs/ja-JP/channels/signal.md @@ -0,0 +1,344 @@ +--- +read_when: + - Signalサポートをセットアップするとき + - Signalの送受信をデバッグするとき +summary: signal-cli（JSON-RPC + SSE）経由のSignalサポート、セットアップ経路、番号モデル +title: Signal +x-i18n: + generated_at: "2026-04-05T12:36:49Z" + model: gpt-5.4 + provider: openai + source_hash: cdd855eb353aca6a1c2b04d14af0e3da079349297b54fa8243562c52b29118d9 + source_path: channels/signal.md + workflow: 15 +--- + +# Signal（signal-cli） + +ステータス: 外部CLI統合。GatewayはHTTP JSON-RPC + SSE経由で`signal-cli`と通信します。 + +## 前提条件 + +- サーバーにOpenClawがインストールされていること（以下のLinuxフローはUbuntu 24でテスト済み）。 +- Gatewayを実行するホストで`signal-cli`が利用可能であること。 +- 1回の認証SMSを受信できる電話番号（SMS登録経路の場合）。 +- 登録時にSignal captcha（`signalcaptchas.org`）へアクセスするためのブラウザー。 + +## クイックセットアップ（初級者向け） + +1. botには**別のSignal番号**を使用します（推奨）。 +2. `signal-cli`をインストールします（JVMビルドを使う場合はJavaが必要です）。 +3. セットアップ経路を1つ選びます。 + - **経路A（QRリンク）:** `signal-cli link -n "OpenClaw"`を実行し、Signalでスキャンします。 + - **経路B（SMS登録）:** captcha + SMS認証で専用番号を登録します。 +4. OpenClawを設定してGatewayを再起動します。 +5. 最初のDMを送信し、pairingを承認します（`openclaw pairing approve signal `）。 + +最小構成: + +```json5 +{ + channels: { + signal: { + enabled: true, + account: "+15551234567", + cliPath: "signal-cli", + dmPolicy: "pairing", + allowFrom: ["+15557654321"], + }, + }, +} +``` + +フィールドリファレンス: + +| フィールド | 説明 | +| ----------- | ------------------------------------------------------ | +| `account` | E.164形式のbot電話番号（`+15551234567`） | +| `cliPath` | `signal-cli`へのパス（`PATH`上にあるなら`signal-cli`） | +| `dmPolicy` | DMアクセス方針（`pairing`推奨） | +| `allowFrom` | DMを許可する電話番号または`uuid:`値 | + +## これは何か + +- `signal-cli`経由のSignalチャンネルです（埋め込みlibsignalではありません）。 +- 決定的なルーティング: 返信は常にSignalへ戻ります。 +- DMはagentのメインセッションを共有し、グループは分離されます（`agent::signal:group:`）。 + +## config書き込み + +デフォルトでは、Signalは`/config set|unset`によってトリガーされたconfig更新の書き込みを許可されています（`commands.config: true`が必要）。 + +無効化するには次を使用します。 + +```json5 +{ + channels: { signal: { configWrites: false } }, +} +``` + +## 番号モデル（重要） + +- Gatewayは**Signalデバイス**（`signal-cli`アカウント）に接続します。 +- botを**個人のSignalアカウント**で実行すると、自分自身のメッセージは無視されます（ループ保護）。 +- 「自分がbotにテキストを送り、botが返信する」動作にするには、**別のbot番号**を使用してください。 + +## セットアップ経路A: 既存のSignalアカウントをリンクする（QR） + +1. `signal-cli`をインストールします（JVMまたはネイティブビルド）。 +2. botアカウントをリンクします。 + - `signal-cli link -n "OpenClaw"`を実行し、SignalでQRをスキャンします。 +3. Signalを設定してGatewayを起動します。 + +例: + +```json5 +{ + channels: { + signal: { + enabled: true, + account: "+15551234567", + cliPath: "signal-cli", + dmPolicy: "pairing", + allowFrom: ["+15557654321"], + }, + }, +} +``` + +マルチアカウント対応: `channels.signal.accounts`を使用すると、アカウントごとのconfigと任意の`name`を設定できます。共有パターンについては[`gateway/configuration`](/gateway/configuration-reference#multi-account-all-channels)を参照してください。 + +## セットアップ経路B: 専用のbot番号を登録する（SMS、Linux） + +既存のSignalアプリのアカウントをリンクする代わりに、専用のbot番号を使いたい場合はこちらを使用します。 + +1. SMSを受信できる番号を用意します（固定電話の場合は音声認証でも可）。 + - アカウントやセッションの競合を避けるため、専用のbot番号を使用してください。 +2. Gatewayホストに`signal-cli`をインストールします。 + +```bash +VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//') +curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz" +sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt +sudo ln -sf /opt/signal-cli /usr/local/bin/ +signal-cli --version +``` + +JVMビルド（`signal-cli-${VERSION}.tar.gz`）を使用する場合は、最初にJRE 25+をインストールしてください。 +`signal-cli`は最新の状態に保ってください。上流では、SignalサーバーAPIの変更により古いリリースが動作しなくなる可能性があると案内しています。 + +3. 番号を登録して認証します。 + +```bash +signal-cli -a + register +``` + +captchaが必要な場合: + +1. `https://signalcaptchas.org/registration/generate.html`を開きます。 +2. captchaを完了し、「Open Signal」から`signalcaptcha://...`リンク先をコピーします。 +3. 可能であれば、ブラウザーセッションと同じ外部IPから実行してください。 +4. すぐに再度登録を実行します（captchaトークンはすぐに期限切れになります）。 + +```bash +signal-cli -a + register --captcha '' +signal-cli -a + verify +``` + +4. OpenClawを設定し、Gatewayを再起動して、チャンネルを確認します。 + +```bash +# Gatewayをuser systemdサービスとして実行している場合: +systemctl --user restart openclaw-gateway.service + +# その後、確認: +openclaw doctor +openclaw channels status --probe +``` + +5. DM送信者をpairingします。 + - bot番号に何らかのメッセージを送信します。 + - サーバー上でコードを承認します: `openclaw pairing approve signal `。 + - 「Unknown contact」を避けるため、bot番号を電話の連絡先に保存します。 + +重要: `signal-cli`で電話番号アカウントを登録すると、その番号のメインSignalアプリセッションが認証解除される場合があります。専用のbot番号を推奨します。既存の電話アプリ構成を維持する必要がある場合は、QRリンクモードを使用してください。 + +上流リファレンス: + +- `signal-cli` README: `https://github.com/AsamK/signal-cli` +- Captchaフロー: `https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha` +- リンクフロー: `https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)` + +## 外部デーモンモード（httpUrl） + +`signal-cli`を自分で管理したい場合（JVMのコールドスタートが遅い、コンテナー初期化、共有CPUなど）、デーモンを別に実行してOpenClawからそこを参照します。 + +```json5 +{ + channels: { + signal: { + httpUrl: "http://127.0.0.1:8080", + autoStart: false, + }, + }, +} +``` + +これにより、OpenClaw内での自動起動と起動待機がスキップされます。自動起動時に起動が遅い場合は、`channels.signal.startupTimeoutMs`を設定してください。 + +## アクセス制御（DM + グループ） + +DM: + +- デフォルト: `channels.signal.dmPolicy = "pairing"`。 +- 未知の送信者にはpairingコードが送られ、承認されるまでメッセージは無視されます（コードは1時間で期限切れ）。 +- 承認方法: + - `openclaw pairing list signal` + - `openclaw pairing approve signal ` +- PairingはSignal DMのデフォルトのトークン交換です。詳細: [Pairing](/channels/pairing) +- UUIDのみの送信者（`sourceUuid`由来）は、`channels.signal.allowFrom`に`uuid:`として保存されます。 + +グループ: + +- `channels.signal.groupPolicy = open | allowlist | disabled`。 +- `channels.signal.groupAllowFrom`は、`allowlist`設定時にグループ内で誰がトリガーできるかを制御します。 +- `channels.signal.groups["" | "*"]`では、`requireMention`、`tools`、`toolsBySender`を使ってグループ動作を上書きできます。 +- マルチアカウント構成では、アカウントごとの上書きに`channels.signal.accounts..groups`を使用します。 +- ランタイム注記: `channels.signal`が完全に欠けている場合、ランタイムはグループチェックで`groupPolicy="allowlist"`にフォールバックします（`channels.defaults.groupPolicy`が設定されていても同様です）。 + +## 仕組み（動作） + +- `signal-cli`はデーモンとして動作し、GatewayはSSE経由でイベントを読み取ります。 +- 受信メッセージは共有チャンネルエンベロープに正規化されます。 +- 返信は常に同じ番号またはグループにルーティングされます。 + +## メディア + 制限 + +- 送信テキストは`channels.signal.textChunkLimit`（デフォルト4000）に分割されます。 +- 任意の改行チャンク化: `channels.signal.chunkMode="newline"`を設定すると、長さで分割する前に空行（段落境界）で分割します。 +- 添付ファイルをサポートします（`signal-cli`から取得したbase64）。 +- デフォルトのメディア上限: `channels.signal.mediaMaxMb`（デフォルト8）。 +- メディアのダウンロードをスキップするには`channels.signal.ignoreAttachments`を使用します。 +- グループ履歴コンテキストでは`channels.signal.historyLimit`（または`channels.signal.accounts.*.historyLimit`）を使用し、`messages.groupChat.historyLimit`にフォールバックします。無効にするには`0`を設定します（デフォルト50）。 + +## 入力中表示 + 既読通知 + +- **入力中インジケーター**: OpenClawは`signal-cli sendTyping`経由で入力中シグナルを送信し、返信処理中は更新を継続します。 +- **既読通知**: `channels.signal.sendReadReceipts`がtrueの場合、OpenClawは許可されたDMの既読通知を転送します。 +- Signal-cliはグループの既読通知を公開していません。 + +## リアクション（messageツール） + +- `channel=signal`で`message action=react`を使用します。 +- ターゲット: 送信者のE.164またはUUID（pairing出力の`uuid:`を使用します。UUID単体でも動作します）。 +- `messageId`は、リアクション対象メッセージのSignalタイムスタンプです。 +- グループリアクションでは`targetAuthor`または`targetAuthorUuid`が必要です。 + +例: + +``` +message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥 +message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true +message action=react channel=signal target=signal:group: targetAuthor=uuid: messageId=1737630212345 emoji=✅ +``` + +config: + +- `channels.signal.actions.reactions`: リアクションアクションの有効化/無効化（デフォルトtrue）。 +- `channels.signal.reactionLevel`: `off | ack | minimal | extensive`。 + - `off`/`ack`ではagentリアクションが無効になります（messageツールの`react`はエラーになります）。 + - `minimal`/`extensive`ではagentリアクションが有効になり、ガイダンスレベルが設定されます。 +- アカウントごとの上書き: `channels.signal.accounts..actions.reactions`、`channels.signal.accounts..reactionLevel`。 + +## 配信ターゲット（CLI/cron） + +- DM: `signal:+15551234567`（またはプレーンなE.164）。 +- UUID DM: `uuid:`（またはUUID単体）。 +- グループ: `signal:group:`。 +- ユーザー名: `username:`（Signalアカウントでサポートされている場合）。 + +## トラブルシューティング + +まず次の手順を実行してください。 + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +必要に応じて、その後にDMのpairing状態を確認します。 + +```bash +openclaw pairing list signal +``` + +よくある障害: + +- デーモンには到達できるが返信がない: アカウント/デーモン設定（`httpUrl`、`account`）と受信モードを確認してください。 +- DMが無視される: 送信者のpairing承認待ちです。 +- グループメッセージが無視される: グループ送信者/mentionゲーティングが配信をブロックしています。 +- 編集後にconfig検証エラーが出る: `openclaw doctor --fix`を実行してください。 +- 診断にSignalが表示されない: `channels.signal.enabled: true`を確認してください。 + +追加チェック: + +```bash +openclaw pairing list signal +pgrep -af signal-cli +grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20 +``` + +トリアージフロー: [/channels/troubleshooting](/channels/troubleshooting)。 + +## セキュリティに関する注意 + +- `signal-cli`はアカウントキーをローカルに保存します（通常は`~/.local/share/signal-cli/data/`）。 +- サーバー移行や再構築の前にSignalアカウント状態をバックアップしてください。 +- より広いDMアクセスを明示的に望まない限り、`channels.signal.dmPolicy: "pairing"`を維持してください。 +- SMS認証は登録またはリカバリーフローでのみ必要ですが、番号/アカウントの制御を失うと再登録が複雑になる場合があります。 + +## 設定リファレンス（Signal） + +完全な設定: [Configuration](/gateway/configuration) + +プロバイダーオプション: + +- `channels.signal.enabled`: チャンネル起動の有効化/無効化。 +- `channels.signal.account`: botアカウント用のE.164。 +- `channels.signal.cliPath`: `signal-cli`へのパス。 +- `channels.signal.httpUrl`: 完全なデーモンURL（host/portより優先）。 +- `channels.signal.httpHost`, `channels.signal.httpPort`: デーモンのbind先（デフォルト127.0.0.1:8080）。 +- `channels.signal.autoStart`: デーモンを自動起動（`httpUrl`未設定時のデフォルトはtrue）。 +- `channels.signal.startupTimeoutMs`: 起動待機タイムアウト（ms、上限120000）。 +- `channels.signal.receiveMode`: `on-start | manual`。 +- `channels.signal.ignoreAttachments`: 添付ファイルのダウンロードをスキップ。 +- `channels.signal.ignoreStories`: デーモンからのストーリーを無視。 +- `channels.signal.sendReadReceipts`: 既読通知を転送。 +- `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled`（デフォルト: pairing）。 +- `channels.signal.allowFrom`: DM allowlist（E.164または`uuid:`）。`open`には`"*"`が必要です。Signalにはユーザー名がないため、電話番号/UUID IDを使用してください。 +- `channels.signal.groupPolicy`: `open | allowlist | disabled`（デフォルト: allowlist）。 +- `channels.signal.groupAllowFrom`: グループ送信者allowlist。 +- `channels.signal.groups`: SignalグループID（または`"*"`）をキーにしたグループごとの上書き。サポートフィールド: `requireMention`、`tools`、`toolsBySender`。 +- `channels.signal.accounts..groups`: マルチアカウント構成向けの`channels.signal.groups`のアカウント別版。 +- `channels.signal.historyLimit`: コンテキストに含めるグループメッセージの最大数（0で無効）。 +- `channels.signal.dmHistoryLimit`: ユーザーターン単位のDM履歴上限。ユーザー単位の上書き: `channels.signal.dms[""].historyLimit`。 +- `channels.signal.textChunkLimit`: 送信チャンクサイズ（文字数）。 +- `channels.signal.chunkMode`: `length`（デフォルト）または`newline`。長さで分割する前に空行（段落境界）で分割します。 +- `channels.signal.mediaMaxMb`: 受信/送信メディア上限（MB）。 + +関連するグローバルオプション: + +- `agents.list[].groupChat.mentionPatterns`（Signalはネイティブmentionをサポートしません）。 +- `messages.groupChat.mentionPatterns`（グローバルフォールバック）。 +- `messages.responsePrefix`。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャンネル +- [Pairing](/channels/pairing) — DM認証とpairingフロー +- [Groups](/channels/groups) — グループチャットの動作とmentionゲーティング +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/slack.md b/docs/ja-JP/channels/slack.md new file mode 100644 index 000000000..c727e4f4c --- /dev/null +++ b/docs/ja-JP/channels/slack.md @@ -0,0 +1,676 @@ +--- +read_when: + - Slack を設定するとき、または Slack の socket/HTTP モードをデバッグするとき +summary: Slack のセットアップとランタイム動作（Socket Mode + HTTP Events API） +title: Slack +x-i18n: + generated_at: "2026-04-05T12:37:31Z" + model: gpt-5.4 + provider: openai + source_hash: efb37e1f04e1ac8ac3786c36ffc20013dacdc654bfa61e7f6e8df89c4902d2ab + source_path: channels/slack.md + workflow: 15 +--- + +# Slack + +ステータス: Slack アプリ統合を介した DM とチャネルに対して本番運用対応。デフォルトモードは Socket Mode で、HTTP Events API モードもサポートされています。 + + + + Slack DM はデフォルトでペアリングモードです。 + + + ネイティブコマンド動作とコマンドカタログ。 + + + チャネル横断の診断と修復プレイブック。 + + + +## クイックセットアップ + + + + + + Slack アプリ設定で次を行います。 + + - **Socket Mode** を有効化 + - `connections:write` を持つ **App Token**（`xapp-...`）を作成 + - アプリをインストールし、**Bot Token**（`xoxb-...`）をコピー + + + + +```json5 +{ + channels: { + slack: { + enabled: true, + mode: "socket", + appToken: "xapp-...", + botToken: "xoxb-...", + }, + }, +} +``` + + 環境変数フォールバック（デフォルトアカウントのみ）: + +```bash +SLACK_APP_TOKEN=xapp-... +SLACK_BOT_TOKEN=xoxb-... +``` + + + + + 次の bot イベントを購読します。 + + - `app_mention` + - `message.channels`, `message.groups`, `message.im`, `message.mpim` + - `reaction_added`, `reaction_removed` + - `member_joined_channel`, `member_left_channel` + - `channel_rename` + - `pin_added`, `pin_removed` + + さらに、DM 用に App Home の **Messages Tab** を有効にします。 + + + + +```bash +openclaw gateway +``` + + + + + + + + + + + - モードを HTTP に設定（`channels.slack.mode="http"`） + - Slack の **Signing Secret** をコピー + - Event Subscriptions、Interactivity、Slash command の Request URL を同じ webhook path（デフォルトは `/slack/events`）に設定 + + + + + +```json5 +{ + channels: { + slack: { + enabled: true, + mode: "http", + botToken: "xoxb-...", + signingSecret: "your-signing-secret", + webhookPath: "/slack/events", + }, + }, +} +``` + + + + + アカウントごとの HTTP モードをサポートしています。 + + 登録が衝突しないよう、各アカウントに異なる `webhookPath` を設定してください。 + + + + + + +## マニフェストとスコープのチェックリスト + + + + +```json +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw", + "always_online": true + }, + "app_home": { + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + + + + + `channels.slack.userToken` を設定する場合、一般的な読み取りスコープは次のとおりです。 + + - `channels:history`, `groups:history`, `im:history`, `mpim:history` + - `channels:read`, `groups:read`, `im:read`, `mpim:read` + - `users:read` + - `reactions:read` + - `pins:read` + - `emoji:read` + - `search:read`（Slack 検索の読み取りに依存する場合） + + + + +## トークンモデル + +- Socket Mode には `botToken` + `appToken` が必要です。 +- HTTP モードには `botToken` + `signingSecret` が必要です。 +- `botToken`、`appToken`、`signingSecret`、`userToken` はプレーンテキスト文字列または SecretRef オブジェクトを受け付けます。 +- config のトークンは環境変数フォールバックより優先されます。 +- 環境変数フォールバック `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` はデフォルトアカウントにのみ適用されます。 +- `userToken`（`xoxp-...`）は config 専用です（環境変数フォールバックなし）。デフォルトでは読み取り専用動作（`userTokenReadOnly: true`）です。 +- オプション: 送信メッセージでアクティブなエージェントの identity（カスタム `username` と icon）を使いたい場合は `chat:write.customize` を追加してください。`icon_emoji` には `:emoji_name:` 形式を使います。 + +ステータススナップショットの動作: + +- Slack アカウント検査では、認証情報ごとの `*Source` と `*Status` フィールド（`botToken`、`appToken`、`signingSecret`、`userToken`）を追跡します。 +- ステータスは `available`、`configured_unavailable`、`missing` です。 +- `configured_unavailable` は、そのアカウントが SecretRef または別の非インラインなシークレットソースで設定されているが、現在のコマンド/ランタイム経路では実際の値を解決できなかったことを意味します。 +- HTTP モードでは `signingSecretStatus` が含まれます。Socket Mode では必要な組み合わせは `botTokenStatus` + `appTokenStatus` です。 + + +アクションやディレクトリ読み取りでは、設定されていれば user token が優先されることがあります。書き込みでは bot token が引き続き優先されます。user token による書き込みは、`userTokenReadOnly: false` かつ bot token が利用できない場合にのみ許可されます。 + + +## アクションとゲート + +Slack アクションは `channels.slack.actions.*` で制御されます。 + +現在の Slack ツールで利用可能なアクショングループ: + +| Group | Default | +| ---------- | ------- | +| messages | enabled | +| reactions | enabled | +| pins | enabled | +| memberInfo | enabled | +| emojiList | enabled | + +現在の Slack メッセージアクションには `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info`、`emoji-list` が含まれます。 + +## アクセス制御とルーティング + + + + `channels.slack.dmPolicy` は DM アクセスを制御します（旧形式: `channels.slack.dm.policy`）。 + + - `pairing`（デフォルト） + - `allowlist` + - `open`（`channels.slack.allowFrom` に `"*"` を含める必要があります。旧形式: `channels.slack.dm.allowFrom`） + - `disabled` + + DM フラグ: + + - `dm.enabled`（デフォルト true） + - `channels.slack.allowFrom`（推奨） + - `dm.allowFrom`（旧形式） + - `dm.groupEnabled`（グループ DM はデフォルト false） + - `dm.groupChannels`（任意の MPIM allowlist） + + 複数アカウントの優先順位: + + - `channels.slack.accounts.default.allowFrom` は `default` アカウントにのみ適用されます。 + - 名前付きアカウントは、自身の `allowFrom` が未設定の場合に `channels.slack.allowFrom` を継承します。 + - 名前付きアカウントは `channels.slack.accounts.default.allowFrom` を継承しません。 + + DM でのペアリングには `openclaw pairing approve slack ` を使います。 + + + + + `channels.slack.groupPolicy` はチャネル処理を制御します。 + + - `open` + - `allowlist` + - `disabled` + + チャネル allowlist は `channels.slack.channels` 配下にあり、安定したチャネル ID を使うべきです。 + + ランタイムに関する注意: `channels.slack` が完全に存在しない場合（環境変数のみのセットアップ）、ランタイムは `groupPolicy="allowlist"` にフォールバックし、警告を記録します（`channels.defaults.groupPolicy` が設定されていても同様です）。 + + 名前/ID 解決: + + - チャネル allowlist エントリと DM allowlist エントリは、トークンアクセスが許可される場合、起動時に解決されます + - 解決できなかったチャネル名エントリは設定されたまま保持されますが、デフォルトではルーティングで無視されます + - 受信認可とチャネルルーティングはデフォルトで ID 優先です。直接の username/slug 一致には `channels.slack.dangerouslyAllowNameMatching: true` が必要です + + + + + チャネルメッセージはデフォルトで mention ゲートが有効です。 + + mention ソース: + + - 明示的な app mention（`<@botId>`） + - mention 正規表現パターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは `messages.groupChat.mentionPatterns`） + - bot への返信スレッドの暗黙的動作 + + チャネルごとの制御（`channels.slack.channels.`。名前は起動時解決または `dangerouslyAllowNameMatching` 経由のみ）: + + - `requireMention` + - `users`（allowlist） + - `allowBots` + - `skills` + - `systemPrompt` + - `tools`, `toolsBySender` + - `toolsBySender` のキー形式: `id:`、`e164:`、`username:`、`name:`、または `"*"` ワイルドカード + （旧来のプレフィックスなしキーも引き続き `id:` のみにマップされます） + + + + +## スレッド、セッション、返信タグ + +- DM は `direct`、チャネルは `channel`、MPIM は `group` としてルーティングされます。 +- デフォルトの `session.dmScope=main` では、Slack DM はエージェントのメインセッションに統合されます。 +- チャネルセッション: `agent::slack:channel:`。 +- スレッド返信では、必要に応じてスレッドセッション接尾辞（`:thread:`）が作成されます。 +- `channels.slack.thread.historyScope` のデフォルトは `thread`、`thread.inheritParent` のデフォルトは `false` です。 +- `channels.slack.thread.initialHistoryLimit` は、新しいスレッドセッション開始時に取得する既存スレッドメッセージ数を制御します（デフォルト `20`。無効化するには `0` に設定）。 + +返信スレッド制御: + +- `channels.slack.replyToMode`: `off|first|all`（デフォルト `off`） +- `channels.slack.replyToModeByChatType`: `direct|group|channel` ごと +- ダイレクトチャット向け旧形式フォールバック: `channels.slack.dm.replyToMode` + +手動返信タグをサポートしています。 + +- `[[reply_to_current]]` +- `[[reply_to:]]` + +注: `replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含む **すべての** Slack 返信スレッドを無効化します。これは Telegram と異なり、Telegram では `"off"` モードでも明示タグが尊重されます。この違いはプラットフォームのスレッドモデルを反映しています。Slack スレッドはメッセージをチャネルから隠しますが、Telegram の返信はメインチャットフロー内で可視のままです。 + +## 確認リアクション + +`ackReaction` は、OpenClaw が受信メッセージを処理中であることを示す確認絵文字を送信します。 + +解決順序: + +- `channels.slack.accounts..ackReaction` +- `channels.slack.ackReaction` +- `messages.ackReaction` +- エージェント identity の絵文字フォールバック（`agents.list[].identity.emoji`、なければ `"👀"`） + +注: + +- Slack では shortcode（例: `"eyes"`）が必要です。 +- Slack アカウント単位またはグローバルでリアクションを無効化するには `""` を使います。 + +## テキストストリーミング + +`channels.slack.streaming` はライブプレビュー動作を制御します。 + +- `off`: ライブプレビューのストリーミングを無効化。 +- `partial`（デフォルト）: プレビュー文字列を最新の部分出力で置き換えます。 +- `block`: チャンク化されたプレビュー更新を追加します。 +- `progress`: 生成中は進捗ステータステキストを表示し、その後で最終テキストを送信します。 + +`channels.slack.nativeStreaming` は、`streaming` が `partial` のときに Slack ネイティブのテキストストリーミングを制御します（デフォルト: `true`）。 + +- Slack ネイティブのテキストストリーミングを表示するには返信スレッドが利用可能である必要があります。スレッド選択は引き続き `replyToMode` に従います。利用できない場合は通常のドラフトプレビューが使われます。 +- メディアおよび非テキストのペイロードは通常配信にフォールバックします。 +- ストリーミングが返信の途中で失敗した場合、OpenClaw は残りのペイロードを通常配信にフォールバックします。 + +Slack ネイティブのテキストストリーミングの代わりにドラフトプレビューを使うには: + +```json5 +{ + channels: { + slack: { + streaming: "partial", + nativeStreaming: false, + }, + }, +} +``` + +旧形式キー: + +- `channels.slack.streamMode`（`replace | status_final | append`）は自動的に `channels.slack.streaming` へ移行されます。 +- 真偽値の `channels.slack.streaming` は自動的に `channels.slack.nativeStreaming` へ移行されます。 + +## typing reaction フォールバック + +`typingReaction` は、OpenClaw が返信を処理している間、受信した Slack メッセージに一時的なリアクションを追加し、実行終了時に削除します。これは特に、デフォルトの「入力中...」ステータス表示を使うスレッド返信以外で有用です。 + +解決順序: + +- `channels.slack.accounts..typingReaction` +- `channels.slack.typingReaction` + +注: + +- Slack では shortcode（例: `"hourglass_flowing_sand"`）が必要です。 +- このリアクションはベストエフォートで、返信または失敗経路の完了後に自動クリーンアップが試行されます。 + +## メディア、分割、配信 + + + + Slack ファイル添付は、Slack ホストのプライベート URL からダウンロードされ（トークン認証付きリクエストフロー）、取得に成功しサイズ制限内であればメディアストアに書き込まれます。 + + ランタイムの受信サイズ上限は、`channels.slack.mediaMaxMb` で上書きしない限りデフォルトで `20MB` です。 + + + + + - テキスト分割には `channels.slack.textChunkLimit`（デフォルト 4000）を使います + - `channels.slack.chunkMode="newline"` は段落優先の分割を有効化します + - ファイル送信には Slack の upload API を使い、スレッド返信（`thread_ts`）を含められます + - 送信メディア上限は、設定されていれば `channels.slack.mediaMaxMb` に従います。未設定の場合、チャネル送信では media pipeline の MIME 種別デフォルトが使われます + + + + 推奨される明示的なターゲット: + + - DM には `user:` + - チャネルには `channel:` + + Slack DM は、user ターゲットへ送信する際に Slack 会話 API を通じて開かれます。 + + + + +## コマンドとスラッシュ動作 + +- Slack のネイティブコマンド自動モードは **オフ** です（`commands.native: "auto"` では Slack ネイティブコマンドは有効になりません）。 +- Slack ネイティブコマンドハンドラーを有効にするには `channels.slack.commands.native: true`（またはグローバルの `commands.native: true`）を設定してください。 +- ネイティブコマンドが有効な場合は、対応するスラッシュコマンドを Slack に登録してください（`/` 名）。ただし 1 つ例外があります。 + - ステータスコマンドには `/agentstatus` を登録してください（Slack は `/status` を予約しています） +- ネイティブコマンドが有効でない場合は、`channels.slack.slashCommand` により 1 つの設定済みスラッシュコマンドを実行できます。 +- ネイティブ引数メニューは、表示戦略を自動調整するようになりました。 + - 最大 5 個の選択肢: button block + - 6〜100 個の選択肢: static select menu + - 100 個超の選択肢: interactivity options handler が利用可能な場合は、非同期オプションフィルタ付き external select + - エンコードされた選択肢の値が Slack 制限を超える場合、フローは button にフォールバックします +- 長い選択肢ペイロードでは、スラッシュコマンド引数メニューは選択値を送信する前に確認ダイアログを使います。 + +デフォルトのスラッシュコマンド設定: + +- `enabled: false` +- `name: "openclaw"` +- `sessionPrefix: "slack:slash"` +- `ephemeral: true` + +スラッシュセッションは分離されたキーを使います。 + +- `agent::slack:slash:` + +また、コマンド実行は対象会話セッション（`CommandTargetSessionKey`）に対して引き続きルーティングされます。 + +## インタラクティブ返信 + +Slack はエージェント作成のインタラクティブ返信コントロールを表示できますが、この機能はデフォルトで無効です。 + +グローバルに有効化するには: + +```json5 +{ + channels: { + slack: { + capabilities: { + interactiveReplies: true, + }, + }, + }, +} +``` + +または 1 つの Slack アカウントだけで有効化するには: + +```json5 +{ + channels: { + slack: { + accounts: { + ops: { + capabilities: { + interactiveReplies: true, + }, + }, + }, + }, + }, +} +``` + +有効にすると、エージェントは Slack 専用の返信ディレクティブを出力できます。 + +- `[[slack_buttons: Approve:approve, Reject:reject]]` +- `[[slack_select: Choose a target | Canary:canary, Production:production]]` + +これらのディレクティブは Slack Block Kit にコンパイルされ、クリックや選択を既存の Slack interaction event 経路へ戻します。 + +注: + +- これは Slack 固有の UI です。他のチャネルでは Slack Block Kit ディレクティブを独自のボタンシステムに変換しません。 +- インタラクティブコールバック値は、エージェントが生で記述した値ではなく、OpenClaw が生成した不透明トークンです。 +- 生成されたインタラクティブ block が Slack Block Kit の制限を超える場合、OpenClaw は無効な block ペイロードを送信する代わりに元のテキスト返信へフォールバックします。 + +## Slack での exec 承認 + +Slack は、Web UI やターミナルにフォールバックする代わりに、インタラクティブボタンと interaction を備えたネイティブ承認クライアントとして動作できます。 + +- exec 承認はネイティブ DM/チャネルルーティングに `channels.slack.execApprovals.*` を使います。 +- plugin 承認も、リクエストがすでに Slack に届いていて承認 ID 種別が `plugin:` の場合、同じ Slack ネイティブのボタン UI で解決できます。 +- 承認者の認可は引き続き強制されます。承認または拒否できるのは承認者として識別されたユーザーのみです。 + +これは他のチャネルと同じ共有承認ボタン UI を使います。Slack アプリ設定で `interactivity` が有効な場合、承認プロンプトは会話内に直接 Block Kit ボタンとして表示されます。 +それらのボタンが存在する場合、それが主要な承認 UX です。OpenClaw は、tool result がチャット承認を利用できないと示す場合、または手動承認のみが唯一の経路である場合にのみ、手動の `/approve` コマンドを含めるべきです。 + +config path: + +- `channels.slack.execApprovals.enabled` +- `channels.slack.execApprovals.approvers`（任意。可能な場合は `commands.ownerAllowFrom` にフォールバック） +- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） +- `agentFilter`, `sessionFilter` + +Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人の承認者が解決される場合、ネイティブ exec 承認を自動で有効化します。Slack をネイティブ承認クライアントとして明示的に無効化するには `enabled: false` を設定してください。 +承認者が解決されるときにネイティブ承認を強制的にオンにするには `enabled: true` を設定してください。 + +明示的な Slack exec 承認設定がない場合のデフォルト動作: + +```json5 +{ + commands: { + ownerAllowFrom: ["slack:U12345678"], + }, +} +``` + +承認者の上書き、フィルター追加、または origin-chat 配信への切り替えをしたい場合にのみ、明示的な Slack ネイティブ設定が必要です。 + +```json5 +{ + channels: { + slack: { + execApprovals: { + enabled: true, + approvers: ["U12345678"], + target: "both", + }, + }, + }, +} +``` + +共有の `approvals.exec` 転送は別機能です。exec 承認プロンプトも他のチャットまたは明示的な帯域外ターゲットへルーティングする必要がある場合にのみ使用してください。共有の `approvals.plugin` 転送も別機能です。Slack ネイティブボタンは、それらのリクエストがすでに Slack に届いている場合、引き続き plugin 承認を解決できます。 + +同一チャット内の `/approve` も、すでにコマンドをサポートしている Slack チャネルと DM で動作します。完全な承認転送モデルについては [Exec approvals](/tools/exec-approvals) を参照してください。 + +## イベントと運用動作 + +- メッセージ編集/削除/スレッドブロードキャストは system event にマップされます。 +- reaction の追加/削除イベントは system event にマップされます。 +- メンバー参加/離脱、チャネル作成/名称変更、pin 追加/削除イベントは system event にマップされます。 +- `channel_id_changed` は、`configWrites` が有効な場合にチャネル config キーを移行できます。 +- チャネルトピック/目的メタデータは信頼されないコンテキストとして扱われ、ルーティングコンテキストに注入できます。 +- スレッド開始メッセージと初期スレッド履歴コンテキストのシーディングは、適用可能な場合、設定済み送信者 allowlist によってフィルタされます。 +- Block action と modal interaction は、豊富なペイロードフィールドを持つ構造化された `Slack interaction: ...` system event を出力します。 + - block action: 選択値、ラベル、picker 値、`workflow_*` メタデータ + - modal の `view_submission` および `view_closed` イベントと、ルーティングされたチャネルメタデータおよびフォーム入力 + +## 設定リファレンスへのポインタ + +主なリファレンス: + +- [Configuration reference - Slack](/gateway/configuration-reference#slack) + + 重要な Slack フィールド: + - モード/認証: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` + - DM アクセス: `dm.enabled`, `dmPolicy`, `allowFrom`（旧形式: `dm.policy`, `dm.allowFrom`）, `dm.groupEnabled`, `dm.groupChannels` + - 互換性トグル: `dangerouslyAllowNameMatching`（緊急用。必要な場合を除きオフのままにしてください） + - チャネルアクセス: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` + - スレッド/履歴: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` + - 配信: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming` + - 運用/機能: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` + +## トラブルシューティング + + + + 次の順で確認してください。 + + - `groupPolicy` + - チャネル allowlist（`channels.slack.channels`） + - `requireMention` + - チャネルごとの `users` allowlist + + 便利なコマンド: + +```bash +openclaw channels status --probe +openclaw logs --follow +openclaw doctor +``` + + + + + 次を確認してください。 + + - `channels.slack.dm.enabled` + - `channels.slack.dmPolicy`（または旧形式の `channels.slack.dm.policy`） + - pairing 承認 / allowlist エントリ + +```bash +openclaw pairing list slack +``` + + + + + bot token と app token、および Slack アプリ設定での Socket Mode 有効化を確認してください。 + + `openclaw channels status --probe --json` で `botTokenStatus` または + `appTokenStatus: "configured_unavailable"` が表示される場合、その Slack アカウントは + 設定されていますが、現在のランタイムでは SecretRef ベースの + 値を解決できませんでした。 + + + + + 次を確認してください。 + + - signing secret + - webhook path + - Slack Request URL（Events + Interactivity + Slash Commands） + - HTTP アカウントごとの一意な `webhookPath` + + アカウントスナップショットに `signingSecretStatus: "configured_unavailable"` が + 表示される場合、その HTTP アカウントは設定されていますが、現在のランタイムでは + SecretRef ベースの signing secret を解決できませんでした。 + + + + + 意図したものがどちらかを確認してください。 + + - ネイティブコマンドモード（`channels.slack.commands.native: true`）で、対応するスラッシュコマンドを Slack に登録している + - または単一スラッシュコマンドモード（`channels.slack.slashCommand.enabled: true`） + + あわせて `commands.useAccessGroups` とチャネル/ユーザー allowlist も確認してください。 + + + + +## 関連 + +- [Pairing](/channels/pairing) +- [Groups](/channels/groups) +- [Security](/gateway/security) +- [Channel routing](/channels/channel-routing) +- [Troubleshooting](/channels/troubleshooting) +- [Configuration](/gateway/configuration) +- [Slash commands](/tools/slash-commands) diff --git a/docs/ja-JP/channels/synology-chat.md b/docs/ja-JP/channels/synology-chat.md new file mode 100644 index 000000000..63a2c58e4 --- /dev/null +++ b/docs/ja-JP/channels/synology-chat.md @@ -0,0 +1,190 @@ +--- +read_when: + - OpenClawでSynology Chatをセットアップしているとき + - Synology Chat webhookルーティングをデバッグしているとき +summary: Synology Chat webhookのセットアップとOpenClaw設定 +title: Synology Chat +x-i18n: + generated_at: "2026-04-05T12:36:42Z" + model: gpt-5.4 + provider: openai + source_hash: ddb25fc6b53f896f15f43b4936d69ea071a29a91838a5b662819377271e89d81 + source_path: channels/synology-chat.md + workflow: 15 +--- + +# Synology Chat + +ステータス: Synology Chat webhookを使用するバンドル済みプラグインのダイレクトメッセージチャンネルです。 +このプラグインは、Synology Chatの送信webhookから受信メッセージを受け取り、 +Synology Chatの受信webhookを通じて返信を送信します。 + +## バンドル済みプラグイン + +Synology Chatは現在のOpenClawリリースにバンドル済みプラグインとして含まれているため、通常の +パッケージ済みビルドでは別途インストールは不要です。 + +古いビルドまたはSynology Chatを含まないカスタムインストールを使用している場合は、 +手動でインストールしてください。 + +ローカルチェックアウトからインストールするには: + +```bash +openclaw plugins install ./path/to/local/synology-chat-plugin +``` + +詳細: [Plugins](/tools/plugin) + +## クイックセットアップ + +1. Synology Chatプラグインが利用可能であることを確認します。 + - 現在のパッケージ版OpenClawリリースには、すでにバンドルされています。 + - 古い/カスタムインストールでは、上記コマンドでソースチェックアウトから手動追加できます。 + - `openclaw onboard`では、`openclaw channels add`と同じチャンネルセットアップ一覧にSynology Chatが表示されるようになりました。 + - 非対話型セットアップ: `openclaw channels add --channel synology-chat --token --url ` +2. Synology Chatの統合設定で以下を行います。 + - 受信webhookを作成し、そのURLをコピーします。 + - 送信webhookを作成し、そのシークレットトークンを設定します。 +3. 送信webhookのURLをOpenClaw Gatewayに向けます。 + - デフォルトでは`https://gateway-host/webhook/synology` + - またはカスタムの`channels.synology-chat.webhookPath` +4. OpenClawでセットアップを完了します。 + - ガイド付き: `openclaw onboard` + - 直接指定: `openclaw channels add --channel synology-chat --token --url ` +5. Gatewayを再起動し、Synology ChatボットにDMを送信します。 + +Webhook認証の詳細: + +- OpenClawは、まず`body.token`、次に + `?token=...`、最後にヘッダーから送信webhookトークンを受け付けます。 +- 受け付けるヘッダー形式: + - `x-synology-token` + - `x-webhook-token` + - `x-openclaw-token` + - `Authorization: Bearer ` +- 空または欠落したトークンはfail-closedになります。 + +最小構成: + +```json5 +{ + channels: { + "synology-chat": { + enabled: true, + token: "synology-outgoing-token", + incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...", + webhookPath: "/webhook/synology", + dmPolicy: "allowlist", + allowedUserIds: ["123456"], + rateLimitPerMinute: 30, + allowInsecureSsl: false, + }, + }, +} +``` + +## 環境変数 + +デフォルトアカウントでは、以下の環境変数を使用できます。 + +- `SYNOLOGY_CHAT_TOKEN` +- `SYNOLOGY_CHAT_INCOMING_URL` +- `SYNOLOGY_NAS_HOST` +- `SYNOLOGY_ALLOWED_USER_IDS`（カンマ区切り） +- `SYNOLOGY_RATE_LIMIT` +- `OPENCLAW_BOT_NAME` + +設定値は環境変数より優先されます。 + +## DMポリシーとアクセス制御 + +- `dmPolicy: "allowlist"`が推奨されるデフォルトです。 +- `allowedUserIds`は、SynologyユーザーIDのリスト（またはカンマ区切り文字列）を受け付けます。 +- `allowlist`モードでは、`allowedUserIds`リストが空だと設定ミスとして扱われ、webhookルートは起動しません（全員許可にするには`dmPolicy: "open"`を使用してください）。 +- `dmPolicy: "open"`は任意の送信者を許可します。 +- `dmPolicy: "disabled"`はDMをブロックします。 +- 返信先バインディングは、デフォルトで安定した数値の`user_id`に基づきます。`channels.synology-chat.dangerouslyAllowNameMatching: true`は、返信配信で可変なusername/nickname参照を再有効化する非常用の互換モードです。 +- ペアリング承認は次で行えます。 + - `openclaw pairing list synology-chat` + - `openclaw pairing approve synology-chat ` + +## 送信配信 + +送信先には数値のSynology ChatユーザーIDを使用します。 + +例: + +```bash +openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw" +openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again" +``` + +メディア送信は、URLベースのファイル配信でサポートされています。 + +## 複数アカウント + +複数のSynology Chatアカウントは`channels.synology-chat.accounts`配下でサポートされています。 +各アカウントは、token、incoming URL、webhook path、DMポリシー、制限を上書きできます。 +ダイレクトメッセージのセッションはアカウントごと・ユーザーごとに分離されるため、異なる2つのSynologyアカウントで同じ数値の`user_id`を使ってもトランスクリプト状態は共有されません。 +有効な各アカウントには、異なる`webhookPath`を設定してください。OpenClawは現在、完全一致する重複パスを拒否し、複数アカウント構成で共有されたwebhook pathだけを継承する名前付きアカウントの起動を拒否します。 +意図的に名前付きアカウントでレガシー継承が必要な場合は、 +そのアカウントまたは`channels.synology-chat`に`dangerouslyAllowInheritedWebhookPath: true`を設定してください。 +ただし、完全一致する重複パスは引き続きfail-closedで拒否されます。明示的なアカウントごとのパスを推奨します。 + +```json5 +{ + channels: { + "synology-chat": { + enabled: true, + accounts: { + default: { + token: "token-a", + incomingUrl: "https://nas-a.example.com/...token=...", + }, + alerts: { + token: "token-b", + incomingUrl: "https://nas-b.example.com/...token=...", + webhookPath: "/webhook/synology-alerts", + dmPolicy: "allowlist", + allowedUserIds: ["987654"], + }, + }, + }, + }, +} +``` + +## セキュリティに関する注意 + +- `token`は秘密に保ち、漏えいした場合はローテーションしてください。 +- 自己署名のローカルNAS証明書を明示的に信頼している場合を除き、`allowInsecureSsl: false`を維持してください。 +- 受信webhookリクエストはトークン検証され、送信者ごとにレート制限されます。 +- 無効なトークンチェックでは定数時間のシークレット比較を使用し、fail-closedになります。 +- 本番環境では`dmPolicy: "allowlist"`を推奨します。 +- レガシーのusernameベース返信配信が明示的に必要な場合を除き、`dangerouslyAllowNameMatching`は無効のままにしてください。 +- 複数アカウント構成で共有パスのルーティングリスクを明示的に受け入れる場合を除き、`dangerouslyAllowInheritedWebhookPath`は無効のままにしてください。 + +## トラブルシューティング + +- `Missing required fields (token, user_id, text)`: + - 送信webhookペイロードに必要フィールドのいずれかが欠けています + - Synologyがトークンをヘッダーで送信している場合、Gateway/プロキシがそのヘッダーを保持していることを確認してください +- `Invalid token`: + - 送信webhookのシークレットが`channels.synology-chat.token`と一致していません + - リクエストが誤ったアカウント/webhook pathに到達しています + - リバースプロキシが、リクエストがOpenClawに届く前にトークンヘッダーを削除しました +- `Rate limit exceeded`: + - 同じ送信元からの無効トークン試行が多すぎると、その送信元が一時的にロックアウトされることがあります + - 認証済み送信者にも、別途ユーザーごとのメッセージレート制限があります +- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`: + - `dmPolicy="allowlist"`が有効ですが、ユーザーが設定されていません +- `User not authorized`: + - 送信者の数値`user_id`が`allowedUserIds`に含まれていません + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャンネル +- [Pairing](/channels/pairing) — DM認証とペアリングフロー +- [Groups](/channels/groups) — グループチャットの挙動とメンション制御 +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/telegram.md b/docs/ja-JP/channels/telegram.md new file mode 100644 index 000000000..766628707 --- /dev/null +++ b/docs/ja-JP/channels/telegram.md @@ -0,0 +1,1065 @@ +--- +read_when: + - Telegram 機能または webhook に取り組むとき +summary: Telegram ボットのサポート状況、機能、設定 +title: Telegram +x-i18n: + generated_at: "2026-04-05T12:38:43Z" + model: gpt-5.4 + provider: openai + source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e + source_path: channels/telegram.md + workflow: 15 +--- + +# Telegram（Bot API） + +ステータス: grammY による bot の DM とグループ向けに本番運用対応済みです。long polling がデフォルトモードで、webhook モードは任意です。 + + + + Telegram のデフォルト DM ポリシーは pairing です。 + + + チャネル横断の診断と修復プレイブック。 + + + 完全なチャネル設定パターンと例。 + + + +## クイックセットアップ + + + + Telegram を開いて **@BotFather** とチャットしてください（ハンドルが正確に `@BotFather` であることを確認してください）。 + + `/newbot` を実行し、案内に従ってトークンを保存します。 + + + + + +```json5 +{ + channels: { + telegram: { + enabled: true, + botToken: "123:abc", + dmPolicy: "pairing", + groups: { "*": { requireMention: true } }, + }, + }, +} +``` + + env フォールバック: `TELEGRAM_BOT_TOKEN=...`（デフォルトアカウントのみ）。 + Telegram では `openclaw channels login telegram` は使いません。config/env にトークンを設定してから Gateway を起動してください。 + + + + + +```bash +openclaw gateway +openclaw pairing list telegram +openclaw pairing approve telegram +``` + + pairing コードは 1 時間で期限切れになります。 + + + + + bot をグループに追加し、その後 `channels.telegram.groups` と `groupPolicy` をアクセスモデルに合わせて設定します。 + + + + +トークン解決順はアカウント認識型です。実際には、config 値が env フォールバックより優先され、`TELEGRAM_BOT_TOKEN` はデフォルトアカウントにのみ適用されます。 + + +## Telegram 側の設定 + + + + Telegram bot はデフォルトで **Privacy Mode** になっており、グループ内で受信できるメッセージが制限されます。 + + bot がすべてのグループメッセージを見る必要がある場合は、次のいずれかを行ってください。 + + - `/setprivacy` で privacy mode を無効にする + - bot をグループ管理者にする + + privacy mode を切り替えたときは、Telegram が変更を適用するよう、各グループで bot を削除して再追加してください。 + + + + + 管理者ステータスは Telegram のグループ設定で管理されます。 + + 管理者 bot はすべてのグループメッセージを受信でき、常時動作するグループ挙動に便利です。 + + + + + + - `/setjoingroups` でグループ追加の許可/拒否 + - `/setprivacy` でグループ可視性の挙動を設定 + + + + +## アクセス制御と activation + + + + `channels.telegram.dmPolicy` はダイレクトメッセージアクセスを制御します。 + + - `pairing`（デフォルト） + - `allowlist`（`allowFrom` に少なくとも 1 つの送信者 ID が必要） + - `open`（`allowFrom` に `"*"` を含める必要あり） + - `disabled` + + `channels.telegram.allowFrom` には数値の Telegram ユーザー ID を指定します。`telegram:` / `tg:` プレフィックスは受け付けられ、正規化されます。 + 空の `allowFrom` で `dmPolicy: "allowlist"` を設定すると、すべての DM がブロックされ、config 検証で拒否されます。 + オンボーディングでは `@username` 入力を受け付け、数値 ID に解決します。 + アップグレード後の config に `@username` の allowlist エントリが含まれている場合は、`openclaw doctor --fix` を実行して解決してください（ベストエフォートです。Telegram bot トークンが必要です）。 + 以前に pairing-store の allowlist ファイルに依存していた場合、`openclaw doctor --fix` は allowlist フローでそのエントリを `channels.telegram.allowFrom` に復元できます（たとえば `dmPolicy: "allowlist"` にまだ明示的な ID がない場合）。 + + 1 オーナー bot では、以前の pairing 承認に依存するのではなく、アクセスポリシーを config に永続的に保持するために、明示的な数値 `allowFrom` ID を持つ `dmPolicy: "allowlist"` を推奨します。 + + よくある誤解: DM pairing 承認は「この送信者がどこでも認可される」ことを意味しません。 + pairing が与えるのは DM アクセスのみです。グループ送信者認可は引き続き明示的な config allowlist から行われます。 + 「一度認可すれば DM とグループコマンドの両方が使える」状態にしたい場合は、自分の数値 Telegram ユーザー ID を `channels.telegram.allowFrom` に入れてください。 + + ### Telegram ユーザー ID を見つける + + より安全な方法（サードパーティ bot なし）: + + 1. bot に DM を送る。 + 2. `openclaw logs --follow` を実行する。 + 3. `from.id` を読む。 + + 公式 Bot API の方法: + +```bash +curl "https://api.telegram.org/bot/getUpdates" +``` + + サードパーティの方法（プライバシー性は低い）: `@userinfobot` または `@getidsbot`。 + + + + + 次の 2 つの制御が一緒に適用されます。 + + 1. **どのグループが許可されるか**（`channels.telegram.groups`） + - `groups` config がない: + - `groupPolicy: "open"` の場合: どのグループも group-ID チェックを通過可能 + - `groupPolicy: "allowlist"`（デフォルト）の場合: `groups` エントリ（または `"*"`）を追加するまでグループはブロックされる + - `groups` が設定されている: allowlist として機能する（明示的な ID または `"*"`） + + 2. **グループ内でどの送信者が許可されるか**（`channels.telegram.groupPolicy`） + - `open` + - `allowlist`（デフォルト） + - `disabled` + + `groupAllowFrom` はグループ送信者のフィルタリングに使われます。設定されていない場合、Telegram は `allowFrom` にフォールバックします。 + `groupAllowFrom` エントリは数値の Telegram ユーザー ID である必要があります（`telegram:` / `tg:` プレフィックスは正規化されます）。 + Telegram のグループまたは supergroup の chat ID を `groupAllowFrom` に入れないでください。負の chat ID は `channels.telegram.groups` に入れる必要があります。 + 数値でないエントリは送信者認可では無視されます。 + セキュリティ境界（`2026.2.25+`）: グループ送信者認可は DM pairing-store 承認を継承しません。 + pairing は DM 専用のままです。グループについては `groupAllowFrom` またはグループごと/トピックごとの `allowFrom` を設定してください。 + `groupAllowFrom` が未設定の場合、Telegram は pairing store ではなく config の `allowFrom` にフォールバックします。 + 1 オーナー bot の実用パターン: あなたのユーザー ID を `channels.telegram.allowFrom` に設定し、`groupAllowFrom` は未設定のままにし、対象グループを `channels.telegram.groups` で許可します。 + ランタイム注記: `channels.telegram` が完全に欠けている場合、`channels.defaults.groupPolicy` が明示的に設定されていない限り、ランタイムはフェイルクローズドの `groupPolicy="allowlist"` をデフォルトにします。 + + 例: 特定の 1 グループで任意のメンバーを許可する + +```json5 +{ + channels: { + telegram: { + groups: { + "-1001234567890": { + groupPolicy: "open", + requireMention: false, + }, + }, + }, + }, +} +``` + + 例: 特定の 1 グループ内で特定ユーザーのみ許可する + +```json5 +{ + channels: { + telegram: { + groups: { + "-1001234567890": { + requireMention: true, + allowFrom: ["8734062810", "745123456"], + }, + }, + }, + }, +} +``` + + + よくある間違い: `groupAllowFrom` は Telegram グループ allowlist ではありません。 + + - `-1001234567890` のような負の Telegram グループまたは supergroup chat ID は `channels.telegram.groups` に入れてください。 + - 許可されたグループ内で、どの人が bot を起動できるかを制限したいときは、`8734062810` のような Telegram ユーザー ID を `groupAllowFrom` に入れてください。 + - 許可されたグループの任意のメンバーが bot と会話できるようにしたい場合のみ、`groupAllowFrom: ["*"]` を使ってください。 + + + + + + グループ返信ではデフォルトでメンションが必要です。 + + メンションは次のいずれかから得られます。 + + - ネイティブの `@botusername` メンション + - 次の場所の mention pattern: + - `agents.list[].groupChat.mentionPatterns` + - `messages.groupChat.mentionPatterns` + + セッションレベルのコマンド切り替え: + + - `/activation always` + - `/activation mention` + + これらはセッション状態のみを更新します。永続化には config を使ってください。 + + 永続 config の例: + +```json5 +{ + channels: { + telegram: { + groups: { + "*": { requireMention: false }, + }, + }, + }, +} +``` + + グループ chat ID を取得する方法: + + - グループメッセージを `@userinfobot` / `@getidsbot` に転送する + - または `openclaw logs --follow` で `chat.id` を読む + - または Bot API の `getUpdates` を確認する + + + + +## ランタイムの挙動 + +- Telegram は Gateway プロセスによって所有されます。 +- ルーティングは決定的です。Telegram からの受信メッセージへの返信は Telegram に返されます（モデルがチャネルを選ぶことはありません）。 +- 受信メッセージは、返信メタデータとメディアプレースホルダーを含む共有チャネル envelope に正規化されます。 +- グループセッションはグループ ID ごとに分離されます。フォーラムトピックでは、トピック分離のために `:topic:` が付加されます。 +- DM メッセージは `message_thread_id` を持てます。OpenClaw はそれを thread 認識型のセッションキーでルーティングし、返信時も thread ID を保持します。 +- long polling は、チャットごと / thread ごとの順序制御を備えた grammY runner を使います。全体の runner sink concurrency には `agents.defaults.maxConcurrent` を使います。 +- Telegram Bot API には既読通知のサポートがありません（`sendReadReceipts` は適用されません）。 + +## 機能リファレンス + + + + OpenClaw は部分返信をリアルタイムでストリーミングできます。 + + - ダイレクトチャット: プレビューメッセージ + `editMessageText` + - グループ/トピック: プレビューメッセージ + `editMessageText` + + 要件: + + - `channels.telegram.streaming` は `off | partial | block | progress` です（デフォルト: `partial`） + - `progress` は Telegram では `partial` にマップされます（チャネル横断の命名互換性のため） + - レガシーな `channels.telegram.streamMode` と boolean の `streaming` 値は自動マッピングされます + + テキストのみの返信の場合: + + - DM: OpenClaw は同じプレビューメッセージを保持し、最後にその場で編集します（2 通目のメッセージは送信しません） + - グループ/トピック: OpenClaw は同じプレビューメッセージを保持し、最後にその場で編集します（2 通目のメッセージは送信しません） + + 複雑な返信（たとえばメディアペイロード）の場合、OpenClaw は通常の最終配信にフォールバックし、その後プレビューメッセージをクリーンアップします。 + + プレビューストリーミングは block streaming とは別です。Telegram で block streaming が明示的に有効な場合、OpenClaw は二重ストリーミングを避けるためプレビューストリームをスキップします。 + + ネイティブの draft transport が利用できないか拒否された場合、OpenClaw は自動的に `sendMessage` + `editMessageText` にフォールバックします。 + + Telegram 専用の reasoning ストリーム: + + - `/reasoning stream` は、生成中の reasoning をライブプレビューに送信します + - 最終回答は reasoning テキストなしで送信されます + + + + + 送信テキストは Telegram の `parse_mode: "HTML"` を使います。 + + - Markdown 風テキストは Telegram 安全な HTML にレンダリングされます。 + - 生のモデル HTML は Telegram の解析失敗を減らすためエスケープされます。 + - Telegram が解析済み HTML を拒否した場合、OpenClaw はプレーンテキストとして再試行します。 + + リンクプレビューはデフォルトで有効で、`channels.telegram.linkPreview: false` で無効化できます。 + + + + + Telegram のコマンドメニュー登録は起動時に `setMyCommands` で処理されます。 + + ネイティブコマンドのデフォルト: + + - `commands.native: "auto"` は Telegram のネイティブコマンドを有効にします + + カスタムコマンドメニュー項目を追加する: + +```json5 +{ + channels: { + telegram: { + customCommands: [ + { command: "backup", description: "Git バックアップ" }, + { command: "generate", description: "画像を作成" }, + ], + }, + }, +} +``` + + ルール: + + - 名前は正規化されます（先頭の `/` を削除し、小文字化） + - 有効パターン: `a-z`、`0-9`、`_`、長さ `1..32` + - カスタムコマンドはネイティブコマンドを上書きできません + - 競合/重複はスキップされ、ログに記録されます + + 注記: + + - カスタムコマンドはメニュー項目のみです。動作は自動実装されません + - Telegram メニューに表示されなくても、plugin/skill コマンドは手入力で動作できます + + ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。設定されていれば、カスタム/plugin コマンドは引き続き登録されることがあります。 + + よくあるセットアップ失敗: + + - `setMyCommands failed` で `BOT_COMMANDS_TOO_MUCH` が出る場合、削減後でも Telegram メニューが多すぎることを意味します。plugin/skill/custom コマンドを減らすか、`channels.telegram.commands.native` を無効にしてください。 + - `setMyCommands failed` で network/fetch エラーが出る場合、通常は `api.telegram.org` への outbound DNS/HTTPS がブロックされています。 + + ### デバイスペアリングコマンド（`device-pair` plugin） + + `device-pair` plugin がインストールされている場合: + + 1. `/pair` でセットアップコードを生成します + 2. iOS アプリにコードを貼り付けます + 3. `/pair pending` で保留中リクエストを一覧表示します（role/scopes を含む） + 4. リクエストを承認します: + - 明示的に承認するには `/pair approve ` + - 保留中リクエストが 1 件だけなら `/pair approve` + - 最新のものなら `/pair approve latest` + + セットアップコードには短命の bootstrap トークンが含まれます。組み込みの bootstrap handoff では、主要な node トークンは `scopes: []` のまま維持されます。引き渡される operator トークンは `operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write` に制限されたままです。bootstrap の scope チェックは role 接頭辞付きなので、その operator allowlist は operator リクエストにのみ有効であり、operator 以外の role では引き続き自分の role 接頭辞の下の scope が必要です。 + + デバイスが変更された認証詳細（たとえば role/scopes/public key）で再試行した場合、以前の保留中リクエストは置き換えられ、新しいリクエストは別の `requestId` を使います。承認前に `/pair pending` を再実行してください。 + + 詳細: [ペアリング](/channels/pairing#pair-via-telegram-recommended-for-ios)。 + + + + + インラインキーボードのスコープを設定します。 + +```json5 +{ + channels: { + telegram: { + capabilities: { + inlineButtons: "allowlist", + }, + }, + }, +} +``` + + アカウントごとの上書き: + +```json5 +{ + channels: { + telegram: { + accounts: { + main: { + capabilities: { + inlineButtons: "allowlist", + }, + }, + }, + }, + }, +} +``` + + スコープ: + + - `off` + - `dm` + - `group` + - `all` + - `allowlist`（デフォルト） + + レガシーな `capabilities: ["inlineButtons"]` は `inlineButtons: "all"` にマップされます。 + + メッセージアクションの例: + +```json5 +{ + action: "send", + channel: "telegram", + to: "123456789", + message: "Choose an option:", + buttons: [ + [ + { text: "Yes", callback_data: "yes" }, + { text: "No", callback_data: "no" }, + ], + [{ text: "Cancel", callback_data: "cancel" }], + ], +} +``` + + callback クリックは、次のテキストとしてエージェントに渡されます: + `callback_data: ` + + + + + Telegram ツールアクションには次が含まれます。 + + - `sendMessage`（`to`, `content`, optional `mediaUrl`, `replyToMessageId`, `messageThreadId`） + - `react`（`chatId`, `messageId`, `emoji`） + - `deleteMessage`（`chatId`, `messageId`） + - `editMessage`（`chatId`, `messageId`, `content`） + - `createForumTopic`（`chatId`, `name`, optional `iconColor`, `iconCustomEmojiId`） + + チャネルメッセージアクションは使いやすいエイリアスを公開します（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。 + + ゲーティング制御: + + - `channels.telegram.actions.sendMessage` + - `channels.telegram.actions.deleteMessage` + - `channels.telegram.actions.reactions` + - `channels.telegram.actions.sticker`（デフォルト: 無効） + + 注記: `edit` と `topic-create` は現在デフォルトで有効で、個別の `channels.telegram.actions.*` トグルはありません。 + ランタイム送信は、アクティブな config/secrets スナップショット（起動/再読み込み時）を使うため、アクションパスでは送信ごとに ad-hoc な SecretRef 再解決は行いません。 + + リアクション削除の意味論: [/tools/reactions](/tools/reactions) + + + + + Telegram は生成出力内で明示的な返信 thread タグをサポートします。 + + - `[[reply_to_current]]` は起動元メッセージに返信します + - `[[reply_to:]]` は特定の Telegram message ID に返信します + + `channels.telegram.replyToMode` は処理方法を制御します。 + + - `off`（デフォルト） + - `first` + - `all` + + 注記: `off` は暗黙の返信 thread 化を無効にします。明示的な `[[reply_to_*]]` タグは引き続き尊重されます。 + + + + + forum supergroup では: + + - トピックのセッションキーに `:topic:` が追加されます + - 返信と typing はそのトピック thread を対象にします + - トピック config パス: + `channels.telegram.groups..topics.` + + 一般トピック（`threadId=1`）の特別扱い: + + - メッセージ送信では `message_thread_id` を省略します（Telegram は `sendMessage(...thread_id=1)` を拒否します） + - typing アクションでは引き続き `message_thread_id` を含めます + + トピック継承: トピックエントリは、上書きされない限りグループ設定を継承します（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 + `agentId` はトピック専用で、グループデフォルトからは継承されません。 + + **トピックごとのエージェントルーティング**: 各トピックは、トピック config に `agentId` を設定することで別のエージェントにルーティングできます。これにより、各トピックが独自の分離された workspace、memory、session を持てます。例: + + ```json5 + { + channels: { + telegram: { + groups: { + "-1001234567890": { + topics: { + "1": { agentId: "main" }, // General topic → main agent + "3": { agentId: "zu" }, // Dev topic → zu agent + "5": { agentId: "coder" } // Code review → coder agent + } + } + } + } + } + } + ``` + + その場合、各トピックは独自のセッションキーを持ちます: `agent:zu:telegram:group:-1001234567890:topic:3` + + **永続 ACP トピックバインディング**: forum topic は、トップレベルの型付き ACP binding を通じて ACP harness session を固定できます。 + + - `type: "acp"` と `match.channel: "telegram"` を持つ `bindings[]` + + 例: + + ```json5 + { + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { + agent: "codex", + backend: "acpx", + mode: "persistent", + cwd: "/workspace/openclaw", + }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "telegram", + accountId: "default", + peer: { kind: "group", id: "-1001234567890:topic:42" }, + }, + }, + ], + channels: { + telegram: { + groups: { + "-1001234567890": { + topics: { + "42": { + requireMention: false, + }, + }, + }, + }, + }, + }, + } + ``` + + これは現在、グループおよび supergroup 内の forum topic に限定されています。 + + **チャットからの thread 固定 ACP 起動**: + + - `/acp spawn --thread here|auto` で、現在の Telegram トピックを新しい ACP session にバインドできます。 + - 後続のトピックメッセージは、バインドされた ACP session に直接ルーティングされます（`/acp steer` は不要）。 + - OpenClaw は、バインド成功後に起動確認メッセージをそのトピック内に pin します。 + - `channels.telegram.threadBindings.spawnAcpSessions=true` が必要です。 + + テンプレートコンテキストには次が含まれます。 + + - `MessageThreadId` + - `IsForum` + + DM thread の挙動: + + - `message_thread_id` を持つプライベートチャットでは、DM ルーティングを維持しつつ、thread 認識型の session key / reply target を使います。 + + + + + ### 音声メッセージ + + Telegram はボイスノートと音声ファイルを区別します。 + + - デフォルト: 音声ファイルとしての挙動 + - エージェント返信に `[[audio_as_voice]]` タグを付けると、ボイスノート送信を強制 + + メッセージアクションの例: + +```json5 +{ + action: "send", + channel: "telegram", + to: "123456789", + media: "https://example.com/voice.ogg", + asVoice: true, +} +``` + + ### 動画メッセージ + + Telegram は動画ファイルと video note を区別します。 + + メッセージアクションの例: + +```json5 +{ + action: "send", + channel: "telegram", + to: "123456789", + media: "https://example.com/video.mp4", + asVideoNote: true, +} +``` + + video note はキャプションをサポートしません。指定したメッセージテキストは別送されます。 + + ### ステッカー + + 受信ステッカー処理: + + - 静的 WEBP: ダウンロードして処理（プレースホルダー ``） + - アニメーション TGS: スキップ + - 動画 WEBM: スキップ + + ステッカーコンテキストフィールド: + + - `Sticker.emoji` + - `Sticker.setName` + - `Sticker.fileId` + - `Sticker.fileUniqueId` + - `Sticker.cachedDescription` + + ステッカーキャッシュファイル: + + - `~/.openclaw/telegram/sticker-cache.json` + + ステッカーは、繰り返しの vision 呼び出しを減らすため、一度説明可能な場合に説明されてキャッシュされます。 + + ステッカーアクションを有効化: + +```json5 +{ + channels: { + telegram: { + actions: { + sticker: true, + }, + }, + }, +} +``` + + ステッカー送信アクション: + +```json5 +{ + action: "sticker", + channel: "telegram", + to: "123456789", + fileId: "CAACAgIAAxkBAAI...", +} +``` + + キャッシュ済みステッカーを検索: + +```json5 +{ + action: "sticker-search", + channel: "telegram", + query: "cat waving", + limit: 5, +} +``` + + + + + Telegram のリアクションは `message_reaction` 更新として届きます（メッセージペイロードとは別です）。 + + 有効時、OpenClaw は次のようなシステムイベントをキューに入れます。 + + - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` + + config: + + - `channels.telegram.reactionNotifications`: `off | own | all`（デフォルト: `own`） + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（デフォルト: `minimal`） + + 注記: + + - `own` は bot 送信メッセージへのユーザーリアクションのみを意味します（送信メッセージキャッシュを使ったベストエフォート）。 + - リアクションイベントも Telegram のアクセス制御（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）に従います。認可されていない送信者は破棄されます。 + - Telegram はリアクション更新に thread ID を含めません。 + - forum でないグループではグループ chat session にルーティングされます + - forum グループでは、正確な元トピックではなく、グループ一般トピック session（`:topic:1`）にルーティングされます + + polling/webhook の `allowed_updates` には `message_reaction` が自動的に含まれます。 + + + + + `ackReaction` は、OpenClaw が受信メッセージを処理中であることを示す確認用絵文字を送ります。 + + 解決順: + + - `channels.telegram.accounts..ackReaction` + - `channels.telegram.ackReaction` + - `messages.ackReaction` + - エージェント identity 絵文字へのフォールバック（`agents.list[].identity.emoji`、なければ `"👀"`） + + 注記: + + - Telegram は unicode 絵文字を期待します（たとえば `"👀"`）。 + - チャネルまたはアカウントでリアクションを無効にするには `""` を使ってください。 + + + + + チャネル config 書き込みはデフォルトで有効です（`configWrites !== false`）。 + + Telegram 起点の書き込みには次が含まれます。 + + - `channels.telegram.groups` を更新するためのグループ migration イベント（`migrate_to_chat_id`） + - `/config set` と `/config unset`（コマンド有効化が必要） + + 無効化するには: + +```json5 +{ + channels: { + telegram: { + configWrites: false, + }, + }, +} +``` + + + + + デフォルト: long polling。 + + webhook モード: + + - `channels.telegram.webhookUrl` を設定 + - `channels.telegram.webhookSecret` を設定（webhook URL を設定した場合は必須） + - 任意で `channels.telegram.webhookPath`（デフォルト `/telegram-webhook`） + - 任意で `channels.telegram.webhookHost`（デフォルト `127.0.0.1`） + - 任意で `channels.telegram.webhookPort`（デフォルト `8787`） + + webhook モードのデフォルトのローカルリスナーは `127.0.0.1:8787` に bind します。 + + 公開エンドポイントが異なる場合は、その前段に reverse proxy を置き、`webhookUrl` を公開 URL に向けてください。 + 意図的に外部 ingress が必要な場合は、`webhookHost`（たとえば `0.0.0.0`）を設定してください。 + + + + + - `channels.telegram.textChunkLimit` のデフォルトは 4000 です。 + - `channels.telegram.chunkMode="newline"` は、長さ分割の前に段落境界（空行）を優先します。 + - `channels.telegram.mediaMaxMb`（デフォルト 100）は、受信・送信両方の Telegram メディアサイズ上限です。 + - `channels.telegram.timeoutSeconds` は Telegram API クライアントのタイムアウトを上書きします（未設定時は grammY デフォルト）。 + - グループコンテキスト履歴は `channels.telegram.historyLimit` または `messages.groupChat.historyLimit`（デフォルト 50）を使います。`0` で無効化します。 + - reply/quote/forward の補助コンテキストは、現在は受信したまま渡されます。 + - Telegram の allowlist は主に誰がエージェントを起動できるかを制御するものであり、補助コンテキスト全体のマスキング境界ではありません。 + - DM 履歴制御: + - `channels.telegram.dmHistoryLimit` + - `channels.telegram.dms[""].historyLimit` + - `channels.telegram.retry` config は、回復可能な outbound API エラーに対する Telegram 送信ヘルパー（CLI/tools/actions）に適用されます。 + + CLI の送信ターゲットには数値 chat ID または username を使えます: + +```bash +openclaw message send --channel telegram --target 123456789 --message "hi" +openclaw message send --channel telegram --target @name --message "hi" +``` + + Telegram の poll には `openclaw message poll` を使い、forum topic もサポートします: + +```bash +openclaw message poll --channel telegram --target 123456789 \ + --poll-question "Ship it?" --poll-option "Yes" --poll-option "No" +openclaw message poll --channel telegram --target -1001234567890:topic:42 \ + --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \ + --poll-duration-seconds 300 --poll-public +``` + + Telegram 専用の poll フラグ: + + - `--poll-duration-seconds`（5-600） + - `--poll-anonymous` + - `--poll-public` + - forum topic 用の `--thread-id`（または `:topic:` ターゲットを使用） + + Telegram 送信では次もサポートします: + + - `channels.telegram.capabilities.inlineButtons` が許可している場合の、インラインキーボード用 `--buttons` + - 送信画像や GIF を圧縮された写真やアニメーションメディアアップロードではなく document として送る `--force-document` + + アクションゲーティング: + + - `channels.telegram.actions.sendMessage=false` は、poll を含む outbound Telegram メッセージを無効化します + - `channels.telegram.actions.poll=false` は、通常送信は有効のまま Telegram poll 作成を無効化します + + + + + Telegram は approver DM 内で exec 承認をサポートし、任意で元のチャットまたはトピックに承認プロンプトを投稿できます。 + + config パス: + + - `channels.telegram.execApprovals.enabled` + - `channels.telegram.execApprovals.approvers`（任意。可能な場合は `allowFrom` とダイレクトメッセージの `defaultTo` から推測される数値 owner ID にフォールバック） + - `channels.telegram.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） + - `agentFilter`、`sessionFilter` + + approver は数値の Telegram ユーザー ID である必要があります。`enabled` が未設定または `"auto"` で、`execApprovals.approvers` またはアカウントの数値 owner config（`allowFrom` とダイレクトメッセージの `defaultTo`）から少なくとも 1 人の approver を解決できる場合、Telegram はネイティブ exec 承認を自動有効化します。Telegram をネイティブ承認クライアントとして明示的に無効にするには `enabled: false` を設定してください。そうでない場合、承認リクエストは他の設定済み承認ルートまたは exec 承認フォールバックポリシーにフォールバックします。 + + Telegram は、他のチャットチャネルで使われる共有承認ボタンもレンダリングします。ネイティブ Telegram アダプターが主に追加するのは、approver DM へのルーティング、チャネル/トピックへのファンアウト、配信前の typing ヒントです。 + それらのボタンがある場合、それが主要な承認 UX です。OpenClaw は、ツール結果でチャット承認が利用不可と示される場合、または手動承認が唯一の手段である場合にのみ、手動の `/approve` コマンドを含めるべきです。 + + 配信ルール: + + - `target: "dm"` は、解決された approver DM にのみ承認プロンプトを送信します + - `target: "channel"` は、元の Telegram chat/topic にプロンプトを送り返します + - `target: "both"` は、approver DM と元の chat/topic の両方に送信します + + 解決された approver のみが承認または拒否できます。approver でない人は `/approve` も Telegram 承認ボタンも使えません。 + + 承認解決の挙動: + + - `plugin:` で始まる承認 ID は常に plugin 承認を通じて解決されます。 + - それ以外の承認 ID は最初に `exec.approval.resolve` を試します。 + - Telegram も plugin 承認用に認可されており、かつ Gateway が exec 承認を unknown/expired と返した場合、Telegram は `plugin.approval.resolve` で 1 回だけ再試行します。 + - 実際の exec 承認拒否/エラーは、黙って plugin 承認解決にフォールスルーしません。 + + チャネル配信ではコマンドテキストが chat に表示されるため、`channel` または `both` は信頼できるグループ/トピックでのみ有効化してください。forum topic にプロンプトが届いた場合、OpenClaw は承認プロンプトと承認後フォローアップの両方でそのトピックを維持します。exec 承認のデフォルト有効期限は 30 分です。 + + インライン承認ボタンも、`channels.telegram.capabilities.inlineButtons` が対象サーフェス（`dm`、`group`、または `all`）を許可している必要があります。 + + 関連ドキュメント: [Exec approvals](/tools/exec-approvals) + + + + +## エラー返信制御 + +エージェントが配信エラーまたはプロバイダーエラーに遭遇したとき、Telegram はそのエラーテキストを返信するか、抑制するかを選べます。この挙動は 2 つの config キーで制御されます。 + +| キー | 値 | デフォルト | 説明 | +| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` は chat にわかりやすいエラーメッセージを送ります。`silent` はエラー返信を完全に抑制します。 | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 同じ chat へのエラー返信の最小間隔。障害時のエラースパムを防ぎます。 | + +アカウントごと、グループごと、トピックごとの上書きがサポートされます（他の Telegram config キーと同じ継承）。 + +```json5 +{ + channels: { + telegram: { + errorPolicy: "reply", + errorCooldownMs: 120000, + groups: { + "-1001234567890": { + errorPolicy: "silent", // このグループではエラーを抑制 + }, + }, + }, + }, +} +``` + +## トラブルシューティング + + + + + - `requireMention=false` の場合、Telegram privacy mode が完全可視性を許可している必要があります。 + - BotFather: `/setprivacy` -> Disable + - その後、グループから bot を削除して再追加 + - `openclaw channels status` は、config がメンションなしのグループメッセージを想定している場合に警告します。 + - `openclaw channels status --probe` は明示的な数値グループ ID を確認できます。ワイルドカード `"*"` は membership probe できません。 + - 手早いセッションテスト: `/activation always`。 + + + + + + - `channels.telegram.groups` が存在する場合、グループはそこに列挙されている必要があります（または `"*"` を含める） + - グループ内の bot メンバーシップを確認 + - スキップ理由は `openclaw logs --follow` でログを確認 + + + + + + - 送信者 ID を認可する（pairing および/または数値 `allowFrom`） + - グループポリシーが `open` でも、コマンド認可は引き続き適用されます + - `setMyCommands failed` で `BOT_COMMANDS_TOO_MUCH` が出る場合、ネイティブメニューの項目が多すぎます。plugin/skill/custom コマンドを減らすか、ネイティブメニューを無効化してください + - `setMyCommands failed` で network/fetch エラーが出る場合、通常は `api.telegram.org` への DNS/HTTPS 到達性の問題です + + + + + + - Node 22+ とカスタム fetch/proxy の組み合わせでは、AbortSignal 型の不一致により即時 abort 挙動が発生することがあります。 + - 一部ホストでは `api.telegram.org` がまず IPv6 に解決され、IPv6 outbound が壊れていると Telegram API 障害が断続的に発生することがあります。 + - ログに `TypeError: fetch failed` または `Network request for 'getUpdates' failed!` が含まれている場合、OpenClaw は現在これらを回復可能なネットワークエラーとして再試行します。 + - 直接 outbound/TLS が不安定な VPS ホストでは、Telegram API 呼び出しを `channels.telegram.proxy` 経由にしてください: + +```yaml +channels: + telegram: + proxy: socks5://:@proxy-host:1080 +``` + + - Node 22+ では `autoSelectFamily=true`（WSL2 を除く）と `dnsResultOrder=ipv4first` がデフォルトです。 + - ホストが WSL2 である、または明示的に IPv4-only のほうがうまく動作する場合は、family selection を強制してください: + +```yaml +channels: + telegram: + network: + autoSelectFamily: false +``` + + - RFC 2544 の benchmark-range 応答（`198.18.0.0/15`）は、Telegram メディアダウンロードでデフォルト許可されています。信頼できる fake-IP または transparent proxy がメディアダウンロード中に `api.telegram.org` を別の private/internal/special-use アドレスへ書き換える場合は、Telegram 専用バイパスを opt-in できます: + +```yaml +channels: + telegram: + network: + dangerouslyAllowPrivateNetwork: true +``` + + - 同じ opt-in はアカウントごとにも利用できます: + `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`。 + - proxy が Telegram メディアホストを `198.18.x.x` に解決する場合は、まず dangerous フラグをオフのままにしてください。Telegram メディアは RFC 2544 benchmark range をすでにデフォルト許可しています。 + + + `channels.telegram.network.dangerouslyAllowPrivateNetwork` は Telegram + メディアの SSRF 保護を弱めます。Clash、Mihomo、Surge の fake-IP ルーティングのように、信頼できる operator 管理の proxy 環境が RFC 2544 benchmark range 外の private または special-use 応答を合成する場合にのみ使ってください。通常のパブリックインターネット経由の Telegram アクセスではオフのままにしてください。 + + + - 一時的な環境変数上書き: + - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` + - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` + - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` + - DNS 応答を検証する: + +```bash +dig +short api.telegram.org A +dig +short api.telegram.org AAAA +``` + + + + +さらに詳しく: [チャネルのトラブルシューティング](/channels/troubleshooting)。 + +## Telegram config リファレンスのポイント + +主なリファレンス: + +- `channels.telegram.enabled`: チャネル起動の有効/無効。 +- `channels.telegram.botToken`: bot トークン（BotFather）。 +- `channels.telegram.tokenFile`: 通常ファイルのパスからトークンを読み取ります。symlink は拒否されます。 +- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled`（デフォルト: pairing）。 +- `channels.telegram.allowFrom`: DM allowlist（数値 Telegram ユーザー ID）。`allowlist` には少なくとも 1 つの送信者 ID が必要です。`open` には `"*"` が必要です。`openclaw doctor --fix` はレガシー `@username` エントリを ID に解決し、allowlist 移行フローで pairing-store ファイルから allowlist エントリを復元できます。 +- `channels.telegram.actions.poll`: Telegram poll 作成を有効化または無効化します（デフォルト: 有効。引き続き `sendMessage` が必要）。 +- `channels.telegram.defaultTo`: CLI `--deliver` が明示的な `--reply-to` なしで使うデフォルトの Telegram ターゲット。 +- `channels.telegram.groupPolicy`: `open | allowlist | disabled`（デフォルト: allowlist）。 +- `channels.telegram.groupAllowFrom`: グループ送信者 allowlist（数値 Telegram ユーザー ID）。`openclaw doctor --fix` はレガシー `@username` エントリを ID に解決できます。数値でないエントリは認可時に無視されます。グループ認可では DM pairing-store フォールバックを使いません（`2026.2.25+`）。 +- マルチアカウントの優先順位: + - 2 つ以上の account ID が設定されている場合、デフォルトルーティングを明示するために `channels.telegram.defaultAccount` を設定するか、`channels.telegram.accounts.default` を含めてください。 + - どちらも設定されていない場合、OpenClaw は最初に正規化された account ID にフォールバックし、`openclaw doctor` が警告します。 + - `channels.telegram.accounts.default.allowFrom` と `channels.telegram.accounts.default.groupAllowFrom` は `default` アカウントにのみ適用されます。 + - 名前付きアカウントは、アカウントレベルの値が未設定の場合、`channels.telegram.allowFrom` と `channels.telegram.groupAllowFrom` を継承します。 + - 名前付きアカウントは `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom` を継承しません。 +- `channels.telegram.groups`: グループごとのデフォルト + allowlist（グローバルデフォルトには `"*"` を使用）。 + - `channels.telegram.groups..groupPolicy`: groupPolicy のグループごとの上書き（`open | allowlist | disabled`）。 + - `channels.telegram.groups..requireMention`: メンションゲーティングのデフォルト。 + - `channels.telegram.groups..skills`: skill フィルター（省略 = すべての Skills、空 = なし）。 + - `channels.telegram.groups..allowFrom`: グループごとの送信者 allowlist 上書き。 + - `channels.telegram.groups..systemPrompt`: グループ用の追加 system prompt。 + - `channels.telegram.groups..enabled`: `false` のときグループを無効化。 + - `channels.telegram.groups..topics..*`: トピックごとの上書き（グループフィールド + トピック専用 `agentId`）。 + - `channels.telegram.groups..topics..agentId`: このトピックを特定のエージェントにルーティングします（グループレベルと binding ルーティングを上書き）。 +- `channels.telegram.groups..topics..groupPolicy`: groupPolicy のトピックごとの上書き（`open | allowlist | disabled`）。 +- `channels.telegram.groups..topics..requireMention`: トピックごとのメンションゲーティング上書き。 +- `type: "acp"` と `match.peer.id` に正規のトピック ID `chatId:topic:topicId` を持つトップレベル `bindings[]`: 永続 ACP トピック binding フィールド（[ACP Agents](/tools/acp-agents#channel-specific-settings)を参照）。 +- `channels.telegram.direct..topics..agentId`: DM トピックを特定のエージェントにルーティングします（forum topic と同じ挙動）。 +- `channels.telegram.execApprovals.enabled`: このアカウントで Telegram をチャットベースの exec 承認クライアントとして有効化。 +- `channels.telegram.execApprovals.approvers`: exec リクエストを承認または拒否できる Telegram ユーザー ID。`channels.telegram.allowFrom` またはダイレクトな `channels.telegram.defaultTo` で owner がすでに識別されている場合は任意です。 +- `channels.telegram.execApprovals.target`: `dm | channel | both`（デフォルト: `dm`）。`channel` と `both` は、存在する場合に元の Telegram トピックを維持します。 +- `channels.telegram.execApprovals.agentFilter`: 転送される承認プロンプト向けの任意のエージェント ID フィルター。 +- `channels.telegram.execApprovals.sessionFilter`: 転送される承認プロンプト向けの任意の session key フィルター（substring または regex）。 +- `channels.telegram.accounts..execApprovals`: Telegram exec 承認ルーティングと approver 認可のアカウントごとの上書き。 +- `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist`（デフォルト: allowlist）。 +- `channels.telegram.accounts..capabilities.inlineButtons`: アカウントごとの上書き。 +- `channels.telegram.commands.nativeSkills`: Telegram ネイティブ skills コマンドの有効/無効。 +- `channels.telegram.replyToMode`: `off | first | all`（デフォルト: `off`）。 +- `channels.telegram.textChunkLimit`: 送信チャンクサイズ（文字数）。 +- `channels.telegram.chunkMode`: `length`（デフォルト）または `newline`。length chunking の前に空行で分割します（段落境界）。 +- `channels.telegram.linkPreview`: 送信メッセージのリンクプレビュー切り替え（デフォルト: true）。 +- `channels.telegram.streaming`: `off | partial | block | progress`（ライブストリームプレビュー。デフォルト: `partial`。`progress` は `partial` にマップ。`block` はレガシーなプレビューモード互換）。Telegram のプレビューストリーミングは、1 つのプレビューメッセージをその場で編集します。 +- `channels.telegram.mediaMaxMb`: 受信/送信 Telegram メディア上限（MB、デフォルト: 100）。 +- `channels.telegram.retry`: 回復可能な outbound API エラーに対する Telegram 送信ヘルパー（CLI/tools/actions）の再試行ポリシー（attempts、minDelayMs、maxDelayMs、jitter）。 +- `channels.telegram.network.autoSelectFamily`: Node の autoSelectFamily を上書き（true=有効、false=無効）。デフォルトでは Node 22+ で有効、WSL2 ではデフォルトで無効。 +- `channels.telegram.network.dnsResultOrder`: DNS 結果順序を上書き（`ipv4first` または `verbatim`）。デフォルトでは Node 22+ で `ipv4first`。 +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: 信頼できる fake-IP または transparent-proxy 環境で、Telegram メディアダウンロードがデフォルトの RFC 2544 benchmark-range 許可外の private/internal/special-use アドレスに `api.telegram.org` を解決する場合の危険な opt-in。 +- `channels.telegram.proxy`: Bot API 呼び出し用の proxy URL（SOCKS/HTTP）。 +- `channels.telegram.webhookUrl`: webhook モードを有効化（`channels.telegram.webhookSecret` が必要）。 +- `channels.telegram.webhookSecret`: webhook secret（webhookUrl が設定されている場合は必須）。 +- `channels.telegram.webhookPath`: ローカル webhook パス（デフォルト `/telegram-webhook`）。 +- `channels.telegram.webhookHost`: ローカル webhook bind ホスト（デフォルト `127.0.0.1`）。 +- `channels.telegram.webhookPort`: ローカル webhook bind ポート（デフォルト `8787`）。 +- `channels.telegram.actions.reactions`: Telegram ツールリアクションのゲート。 +- `channels.telegram.actions.sendMessage`: Telegram ツールメッセージ送信のゲート。 +- `channels.telegram.actions.deleteMessage`: Telegram ツールメッセージ削除のゲート。 +- `channels.telegram.actions.sticker`: Telegram ステッカーアクションのゲート — 送信と検索（デフォルト: false）。 +- `channels.telegram.reactionNotifications`: `off | own | all` — どのリアクションがシステムイベントを発生させるかを制御（未設定時のデフォルト: `own`）。 +- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — エージェントのリアクション機能を制御（未設定時のデフォルト: `minimal`）。 +- `channels.telegram.errorPolicy`: `reply | silent` — エラー返信挙動を制御（デフォルト: `reply`）。アカウント/グループ/トピックごとの上書き対応。 +- `channels.telegram.errorCooldownMs`: 同じ chat へのエラー返信間の最小 ms（デフォルト: `60000`）。障害時のエラースパムを防ぎます。 + +- [Configuration reference - Telegram](/gateway/configuration-reference#telegram) + +Telegram 固有の重要フィールド: + +- 起動/認証: `enabled`, `botToken`, `tokenFile`, `accounts.*`（`tokenFile` は通常ファイルを指す必要があり、symlink は拒否されます） +- アクセス制御: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, トップレベル `bindings[]`（`type: "acp"`） +- exec 承認: `execApprovals`, `accounts.*.execApprovals` +- コマンド/メニュー: `commands.native`, `commands.nativeSkills`, `customCommands` +- thread/返信: `replyToMode` +- ストリーミング: `streaming`（プレビュー）、`blockStreaming` +- 書式設定/配信: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` +- メディア/ネットワーク: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- アクション/機能: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` +- リアクション: `reactionNotifications`, `reactionLevel` +- エラー: `errorPolicy`, `errorCooldownMs` +- 書き込み/履歴: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` + +## 関連 + +- [ペアリング](/channels/pairing) +- [グループ](/channels/groups) +- [Security](/gateway/security) +- [チャネルルーティング](/channels/channel-routing) +- [マルチエージェントルーティング](/concepts/multi-agent) +- [トラブルシューティング](/channels/troubleshooting) diff --git a/docs/ja-JP/channels/tlon.md b/docs/ja-JP/channels/tlon.md new file mode 100644 index 000000000..557866e64 --- /dev/null +++ b/docs/ja-JP/channels/tlon.md @@ -0,0 +1,297 @@ +--- +read_when: + - Tlon/Urbit チャネル機能に取り組んでいる +summary: Tlon/Urbit のサポート状況、機能、設定 +title: Tlon +x-i18n: + generated_at: "2026-04-05T12:37:15Z" + model: gpt-5.4 + provider: openai + source_hash: 289cffb3c1b2d450a5f41e0d67117dfb5c192cec956d82039caac9df9f07496d + source_path: channels/tlon.md + workflow: 15 +--- + +# Tlon + +Tlon は Urbit 上に構築された分散型メッセンジャーです。OpenClaw はあなたの Urbit ship に接続し、 +DM とグループチャットメッセージに応答できます。グループ返信はデフォルトで @ メンションが必要で、 +許可リストによってさらに制限することもできます。 + +ステータス: バンドルされたプラグイン。DM、グループメンション、スレッド返信、リッチテキスト整形、 +画像アップロードをサポートしています。リアクションと Polls はまだサポートされていません。 + +## バンドルされたプラグイン + +Tlon は現在の OpenClaw リリースではバンドルされたプラグインとして同梱されているため、通常のパッケージ版 +ビルドでは別途インストールは不要です。 + +古いビルドまたは Tlon を含まないカスタムインストールを使用している場合は、手動で +インストールしてください。 + +CLI でインストール（npm レジストリ）: + +```bash +openclaw plugins install @openclaw/tlon +``` + +ローカルチェックアウト（git リポジトリから実行している場合）: + +```bash +openclaw plugins install ./path/to/local/tlon-plugin +``` + +詳細: [Plugins](/tools/plugin) + +## セットアップ + +1. Tlon プラグインが利用可能であることを確認します。 + - 現在のパッケージ版 OpenClaw リリースにはすでに同梱されています。 + - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 +2. ship URL とログインコードを用意します。 +3. `channels.tlon` を設定します。 +4. Gateway を再起動します。 +5. ボットに DM を送るか、グループチャネルでメンションします。 + +最小設定（単一アカウント）: + +```json5 +{ + channels: { + tlon: { + enabled: true, + ship: "~sampel-palnet", + url: "https://your-ship-host", + code: "lidlut-tabwed-pillex-ridrup", + ownerShip: "~your-main-ship", // 推奨: あなたの ship。常に許可されます + }, + }, +} +``` + +## プライベート/LAN ship + +デフォルトでは、OpenClaw は SSRF 保護のためにプライベート/内部ホスト名と IP 範囲をブロックします。 +ship がプライベートネットワーク（localhost、LAN IP、または内部ホスト名）で動作している場合は、 +明示的にオプトインする必要があります。 + +```json5 +{ + channels: { + tlon: { + url: "http://localhost:8080", + allowPrivateNetwork: true, + }, + }, +} +``` + +これは次のような URL に適用されます。 + +- `http://localhost:8080` +- `http://192.168.x.x:8080` +- `http://my-ship.local:8080` + +⚠️ これはローカルネットワークを信頼している場合にのみ有効にしてください。この設定は、 +ship URL へのリクエストに対する SSRF 保護を無効にします。 + +## グループチャネル + +自動検出はデフォルトで有効です。チャネルを手動で固定することもできます。 + +```json5 +{ + channels: { + tlon: { + groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"], + }, + }, +} +``` + +自動検出を無効化: + +```json5 +{ + channels: { + tlon: { + autoDiscoverChannels: false, + }, + }, +} +``` + +## アクセス制御 + +DM 許可リスト（空 = DM は許可されません。承認フローには `ownerShip` を使用）: + +```json5 +{ + channels: { + tlon: { + dmAllowlist: ["~zod", "~nec"], + }, + }, +} +``` + +グループ認可（デフォルトでは制限あり）: + +```json5 +{ + channels: { + tlon: { + defaultAuthorizedShips: ["~zod"], + authorization: { + channelRules: { + "chat/~host-ship/general": { + mode: "restricted", + allowedShips: ["~zod", "~nec"], + }, + "chat/~host-ship/announcements": { + mode: "open", + }, + }, + }, + }, + }, +} +``` + +## オーナーと承認システム + +未承認ユーザーが操作しようとしたときに承認リクエストを受け取るオーナー ship を設定します。 + +```json5 +{ + channels: { + tlon: { + ownerShip: "~your-main-ship", + }, + }, +} +``` + +オーナー ship は **あらゆる場所で自動的に認可** されます。DM 招待は自動承諾され、 +チャネルメッセージは常に許可されます。オーナーを `dmAllowlist` や +`defaultAuthorizedShips` に追加する必要はありません。 + +設定すると、オーナーは次について DM 通知を受け取ります。 + +- 許可リストにない ship からの DM リクエスト +- 認可のないチャネルでのメンション +- グループ招待リクエスト + +## 自動承諾設定 + +DM 招待を自動承諾（`dmAllowlist` 内の ship に対して）: + +```json5 +{ + channels: { + tlon: { + autoAcceptDmInvites: true, + }, + }, +} +``` + +グループ招待を自動承諾: + +```json5 +{ + channels: { + tlon: { + autoAcceptGroupInvites: true, + }, + }, +} +``` + +## 配信ターゲット（CLI/cron） + +`openclaw message send` または cron 配信では、次を使用します。 + +- DM: `~sampel-palnet` または `dm/~sampel-palnet` +- グループ: `chat/~host-ship/channel` または `group:~host-ship/channel` + +## バンドルされた Skills + +Tlon プラグインには、Tlon 操作への CLI アクセスを提供する +バンドルされた Skills（[`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)）が含まれています。 + +- **連絡先**: プロフィールの取得/更新、連絡先一覧 +- **チャネル**: 一覧、作成、メッセージ投稿、履歴取得 +- **グループ**: 一覧、作成、メンバー管理 +- **DM**: メッセージ送信、メッセージへのリアクション +- **リアクション**: 投稿と DM への絵文字リアクションの追加/削除 +- **設定**: スラッシュコマンド経由でのプラグイン権限管理 + +この Skills は、プラグインがインストールされると自動的に利用可能になります。 + +## 機能 + +| 機能 | ステータス | +| ---------------- | --------------------------------------- | +| ダイレクトメッセージ | ✅ サポート済み | +| グループ/チャネル | ✅ サポート済み（デフォルトでメンションゲートあり） | +| スレッド | ✅ サポート済み（スレッド内に自動返信） | +| リッチテキスト | ✅ Markdown を Tlon 形式に変換 | +| 画像 | ✅ Tlon ストレージにアップロード | +| リアクション | ✅ [バンドルされた Skills](#バンドルされた-skills) 経由 | +| Polls | ❌ 未対応 | +| ネイティブコマンド | ✅ サポート済み（デフォルトで owner のみ） | + +## トラブルシューティング + +まず次の手順を実行してください。 + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +``` + +よくある失敗: + +- **DM が無視される**: 送信者が `dmAllowlist` におらず、承認フロー用の `ownerShip` も設定されていません。 +- **グループメッセージが無視される**: チャネルが検出されていないか、送信者が認可されていません。 +- **接続エラー**: ship URL に到達可能か確認してください。ローカル ship の場合は `allowPrivateNetwork` を有効にしてください。 +- **認証エラー**: ログインコードが現在有効であることを確認してください（コードはローテーションされます）。 + +## 設定リファレンス + +完全な設定: [Configuration](/gateway/configuration) + +プロバイダーオプション: + +- `channels.tlon.enabled`: チャネル起動を有効/無効にします。 +- `channels.tlon.ship`: ボットの 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`: 承認システム用のオーナー ship（常に認可される）。 +- `channels.tlon.dmAllowlist`: DM を許可する ship（空 = なし）。 +- `channels.tlon.autoAcceptDmInvites`: 許可リスト登録済みの ship からの DM を自動承諾します。 +- `channels.tlon.autoAcceptGroupInvites`: すべてのグループ招待を自動承諾します。 +- `channels.tlon.autoDiscoverChannels`: グループチャネルを自動検出します（デフォルト: true）。 +- `channels.tlon.groupChannels`: 手動で固定したチャネル nest。 +- `channels.tlon.defaultAuthorizedShips`: すべてのチャネルで認可される ship。 +- `channels.tlon.authorization.channelRules`: チャネルごとの認可ルール。 +- `channels.tlon.showModelSignature`: メッセージにモデル名を付加します。 + +## 注意事項 + +- グループ返信には応答するためにメンション（例: `~your-bot-ship`）が必要です。 +- スレッド返信: 受信メッセージがスレッド内にある場合、OpenClaw はスレッド内で返信します。 +- リッチテキスト: Markdown の書式（太字、斜体、コード、見出し、リスト）は Tlon ネイティブ形式に変換されます。 +- 画像: URL は Tlon ストレージにアップロードされ、画像ブロックとして埋め込まれます。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャネル +- [Pairing](/channels/pairing) — DM 認証とペアリングフロー +- [Groups](/channels/groups) — グループチャットの挙動とメンションゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/troubleshooting.md b/docs/ja-JP/channels/troubleshooting.md new file mode 100644 index 000000000..17e69e411 --- /dev/null +++ b/docs/ja-JP/channels/troubleshooting.md @@ -0,0 +1,140 @@ +--- +read_when: + - チャンネル転送は接続済みと表示されるが返信が失敗するとき + - 詳細なプロバイダードキュメントに進む前にチャンネル固有の確認が必要なとき +summary: チャンネルごとの障害シグネチャと修正方法による高速なチャンネルレベルのトラブルシューティング +title: チャンネルのトラブルシューティング +x-i18n: + generated_at: "2026-04-05T12:37:10Z" + model: gpt-5.4 + provider: openai + source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f + source_path: channels/troubleshooting.md + workflow: 15 +--- + +# チャンネルのトラブルシューティング + +チャンネルは接続できているが動作がおかしい場合は、このページを使用してください。 + +## コマンドの段階的確認 + +まず次の順に実行してください。 + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +正常なベースライン: + +- `Runtime: running` +- `RPC probe: ok` +- チャンネルプローブで転送が接続済みと表示され、サポートされる場合は`works`または`audit ok`も表示される + +## WhatsApp + +### WhatsAppの障害シグネチャ + +| 症状 | 最速の確認方法 | 修正 | +| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- | +| 接続済みだがDMに返信しない | `openclaw pairing list whatsapp` | 送信者を承認するか、DMポリシー/許可リストを変更する。 | +| グループメッセージが無視される | 設定内の`requireMention`とメンションパターンを確認 | ボットにメンションするか、そのグループのメンションポリシーを緩和する。 | +| ランダムな切断/再ログインループ | `openclaw channels status --probe`とログ | 再ログインし、認証情報ディレクトリが正常か確認する。 | + +完全なトラブルシューティング: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting) + +## Telegram + +### Telegramの障害シグネチャ + +| 症状 | 最速の確認方法 | 修正 | +| ----------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | +| `/start`はあるが使える返信フローがない | `openclaw pairing list telegram` | ペアリングを承認するか、DMポリシーを変更する。 | +| ボットはオンラインだがグループで無反応 | メンション要件とボットのprivacy modeを確認 | グループで見えるようにprivacy modeを無効にするか、ボットにメンションする。 | +| ネットワークエラーで送信に失敗する | Telegram API呼び出し失敗のログを確認 | `api.telegram.org`へのDNS/IPv6/プロキシルーティングを修正する。 | +| 起動時に`setMyCommands`が拒否される | `BOT_COMMANDS_TOO_MUCH`のログを確認 | プラグイン/Skill/カスタムTelegramコマンドを減らすか、ネイティブメニューを無効にする。 | +| アップグレード後に許可リストでブロックされる | `openclaw security audit`と設定の許可リスト | `openclaw doctor --fix`を実行するか、`@username`を数値の送信者IDに置き換える。 | + +完全なトラブルシューティング: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) + +## Discord + +### Discordの障害シグネチャ + +| 症状 | 最速の確認方法 | 修正 | +| ------------------------------- | ----------------------------------- | --------------------------------------------------------- | +| ボットはオンラインだがguildで返信しない | `openclaw channels status --probe` | guild/channelを許可し、message content intentを確認する。 | +| グループメッセージが無視される | メンション制御による破棄のログを確認 | ボットにメンションするか、guild/channelの`requireMention: false`を設定する。 | +| DM返信がない | `openclaw pairing list discord` | DMペアリングを承認するか、DMポリシーを調整する。 | + +完全なトラブルシューティング: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) + +## Slack + +### Slackの障害シグネチャ + +| 症状 | 最速の確認方法 | 修正 | +| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| Socket modeは接続済みだが応答しない | `openclaw channels status --probe` | アプリトークン、ボットトークン、必要なスコープを確認する。SecretRefベースのセットアップでは`botTokenStatus` / `appTokenStatus = configured_unavailable`に注意する。 | +| DMがブロックされる | `openclaw pairing list slack` | ペアリングを承認するか、DMポリシーを緩和する。 | +| チャンネルメッセージが無視される | `groupPolicy`とチャンネル許可リストを確認 | チャンネルを許可するか、ポリシーを`open`に切り替える。 | + +完全なトラブルシューティング: [/channels/slack#troubleshooting](/channels/slack#troubleshooting) + +## iMessageとBlueBubbles + +### iMessageとBlueBubblesの障害シグネチャ + +| 症状 | 最速の確認方法 | 修正 | +| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- | +| 受信イベントがない | webhook/サーバー到達性とアプリ権限を確認 | webhook URLまたはBlueBubblesサーバー状態を修正する。 | +| 送信はできるがmacOSで受信できない | Messages automationのmacOSプライバシー権限を確認 | TCC権限を再付与し、チャンネルプロセスを再起動する。 | +| DM送信者がブロックされる | `openclaw pairing list imessage`または`openclaw pairing list bluebubbles` | ペアリングを承認するか、許可リストを更新する。 | + +完全なトラブルシューティング: + +- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting) +- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting) + +## Signal + +### Signalの障害シグネチャ + +| 症状 | 最速の確認方法 | 修正 | +| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- | +| デーモンには到達できるがボットが無反応 | `openclaw channels status --probe` | `signal-cli`デーモンのURL/アカウントと受信モードを確認する。 | +| DMがブロックされる | `openclaw pairing list signal` | 送信者を承認するか、DMポリシーを調整する。 | +| グループ返信がトリガーされない | グループ許可リストとメンションパターンを確認 | 送信者/グループを追加するか、制御を緩和する。 | + +完全なトラブルシューティング: [/channels/signal#troubleshooting](/channels/signal#troubleshooting) + +## QQ Bot + +### QQ Botの障害シグネチャ + +| 症状 | 最速の確認方法 | 修正 | +| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- | +| ボットが「gone to Mars」と返信する | 設定内の`appId`と`clientSecret`を確認 | 認証情報を設定するか、Gatewayを再起動する。 | +| 受信メッセージがない | `openclaw channels status --probe` | QQ Open Platformで認証情報を確認する。 | +| 音声が文字起こしされない | STTプロバイダー設定を確認 | `channels.qqbot.stt`または`tools.media.audio`を設定する。 | +| プロアクティブメッセージが届かない | QQプラットフォームのインタラクション要件を確認 | 最近のやり取りがないと、QQがボット主導メッセージをブロックすることがある。 | + +完全なトラブルシューティング: [/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting) + +## Matrix + +### 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`を実行するか、リカバリーキーを使って再実行する。 | +| cross-signing/bootstrapが不正に見える | `openclaw matrix verify bootstrap` | シークレットストレージ、cross-signing、バックアップ状態を一括で修復する。 | + +完全なセットアップと設定: [Matrix](/channels/matrix) diff --git a/docs/ja-JP/channels/twitch.md b/docs/ja-JP/channels/twitch.md new file mode 100644 index 000000000..cd709676c --- /dev/null +++ b/docs/ja-JP/channels/twitch.md @@ -0,0 +1,401 @@ +--- +read_when: + - OpenClaw向けにTwitch chat連携をセットアップする場合 +summary: Twitch chat botの設定とセットアップ +title: Twitch +x-i18n: + generated_at: "2026-04-05T12:37:17Z" + model: gpt-5.4 + provider: openai + source_hash: 47af9fb6edb1f462c5919850ee9d05e500a1914ddd0d64a41608fbe960e77cd6 + source_path: channels/twitch.md + workflow: 15 +--- + +# Twitch + +IRC接続によるTwitch chatサポート。OpenClawはTwitchユーザー（bot account）として接続し、channelsでメッセージを受信・送信します。 + +## 同梱plugin + +Twitchは現在のOpenClawリリースでは同梱pluginとして提供されるため、通常の +パッケージ済みビルドでは別途インストールは不要です。 + +古いビルド、またはTwitchを除外したカスタムインストールを使っている場合は、 +手動でインストールしてください。 + +CLI経由でインストール（npm registry）: + +```bash +openclaw plugins install @openclaw/twitch +``` + +ローカルcheckout（git repoから実行している場合）: + +```bash +openclaw plugins install ./path/to/local/twitch-plugin +``` + +詳細: [Plugins](/tools/plugin) + +## クイックセットアップ（初心者向け） + +1. Twitch pluginが利用可能であることを確認します。 + - 現在のパッケージ版OpenClawリリースにはすでに同梱されています。 + - 古い/カスタムインストールでは、上記コマンドで手動追加できます。 +2. bot専用のTwitch accountを作成します（または既存のaccountを使います）。 +3. 認証情報を生成します: [Twitch Token Generator](https://twitchtokengenerator.com/) + - **Bot Token**を選択 + - `chat:read`と`chat:write`のscopeが選択されていることを確認 + - **Client ID**と**Access Token**をコピー +4. Twitch user IDを調べます: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) +5. tokenを設定します: + - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...`（default accountのみ） + - またはconfig: `channels.twitch.accessToken` + - 両方設定されている場合は、configが優先されます（envフォールバックはdefault accountのみ）。 +6. Gatewayを起動します。 + +**⚠️ 重要:** 未承認ユーザーがbotをトリガーできないように、アクセス制御（`allowFrom`または`allowedRoles`）を追加してください。`requireMention`のデフォルトは`true`です。 + +最小構成: + +```json5 +{ + channels: { + twitch: { + enabled: true, + username: "openclaw", // BotのTwitch account + accessToken: "oauth:abc123...", // OAuth Access Token（または OPENCLAW_TWITCH_ACCESS_TOKEN env var を使用） + clientId: "xyz789...", // Token GeneratorのClient ID + channel: "vevisk", // 参加するTwitch channelのchat（必須） + allowFrom: ["123456789"], // （推奨）自分のTwitch user IDのみ - https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ で取得 + }, + }, +} +``` + +## 概要 + +- Gatewayが所有するTwitch channelです。 +- 決定的ルーティング: 返信は常にTwitchへ戻ります。 +- 各accountは独立したsession key `agent::twitch:` に対応します。 +- `username`はbotのaccount（認証する主体）、`channel`は参加するchat roomです。 + +## セットアップ（詳細） + +### 認証情報を生成する + +[Twitch Token Generator](https://twitchtokengenerator.com/)を使用します。 + +- **Bot Token**を選択 +- `chat:read`と`chat:write`のscopeが選択されていることを確認 +- **Client ID**と**Access Token**をコピー + +手動のapp登録は不要です。tokenは数時間後に期限切れになります。 + +### botを設定する + +**Env var（default accountのみ）:** + +```bash +OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... +``` + +**またはconfig:** + +```json5 +{ + channels: { + twitch: { + enabled: true, + username: "openclaw", + accessToken: "oauth:abc123...", + clientId: "xyz789...", + channel: "vevisk", + }, + }, +} +``` + +envとconfigの両方が設定されている場合は、configが優先されます。 + +### アクセス制御（推奨） + +```json5 +{ + channels: { + twitch: { + allowFrom: ["123456789"], // （推奨）自分のTwitch user IDのみ + }, + }, +} +``` + +厳格なallowlistには`allowFrom`を推奨します。roleベースのアクセスにしたい場合は、代わりに`allowedRoles`を使ってください。 + +**利用可能なroles:** `"moderator"`、`"owner"`、`"vip"`、`"subscriber"`、`"all"`。 + +**なぜuser IDなのか?** usernameは変更できるため、なりすましが可能になります。user IDは恒久的です。 + +Twitch user IDを調べる: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)（Twitch usernameをIDに変換） + +## token更新（任意） + +[Twitch Token Generator](https://twitchtokengenerator.com/)のtokenは自動更新できません。期限切れになったら再生成してください。 + +tokenを自動更新したい場合は、[Twitch Developer Console](https://dev.twitch.tv/console)で独自のTwitch applicationを作成し、configに次を追加します。 + +```json5 +{ + channels: { + twitch: { + clientSecret: "your_client_secret", + refreshToken: "your_refresh_token", + }, + }, +} +``` + +botは有効期限前に自動でtokenを更新し、更新イベントをログに記録します。 + +## マルチaccountサポート + +accountごとのtokenには`channels.twitch.accounts`を使用します。共有パターンについては[`gateway/configuration`](/gateway/configuration)を参照してください。 + +例（1つのbot accountを2つのchannelsで使用）: + +```json5 +{ + channels: { + twitch: { + accounts: { + channel1: { + username: "openclaw", + accessToken: "oauth:abc123...", + clientId: "xyz789...", + channel: "vevisk", + }, + channel2: { + username: "openclaw", + accessToken: "oauth:def456...", + clientId: "uvw012...", + channel: "secondchannel", + }, + }, + }, + }, +} +``` + +**注:** 各accountには独自のtokenが必要です（channelごとに1つのtoken）。 + +## アクセス制御 + +### roleベースの制限 + +```json5 +{ + channels: { + twitch: { + accounts: { + default: { + allowedRoles: ["moderator", "vip"], + }, + }, + }, + }, +} +``` + +### User IDによるallowlist（最も安全） + +```json5 +{ + channels: { + twitch: { + accounts: { + default: { + allowFrom: ["123456789", "987654321"], + }, + }, + }, + }, +} +``` + +### roleベースのアクセス（代替） + +`allowFrom`は厳格なallowlistです。設定されている場合、それらのuser IDのみが許可されます。 +roleベースのアクセスにしたい場合は、`allowFrom`を未設定のままにして、代わりに`allowedRoles`を設定してください。 + +```json5 +{ + channels: { + twitch: { + accounts: { + default: { + allowedRoles: ["moderator"], + }, + }, + }, + }, +} +``` + +### @mention必須を無効にする + +デフォルトでは`requireMention`は`true`です。無効にしてすべてのメッセージに応答するには: + +```json5 +{ + channels: { + twitch: { + accounts: { + default: { + requireMention: false, + }, + }, + }, + }, +} +``` + +## トラブルシューティング + +まず、診断コマンドを実行します。 + +```bash +openclaw doctor +openclaw channels status --probe +``` + +### botがメッセージに応答しない + +**アクセス制御を確認:** 自分のuser IDが`allowFrom`に含まれていることを確認するか、テストのために一時的に +`allowFrom`を外して`allowedRoles: ["all"]`を設定してください。 + +**botがchannelに入っていることを確認:** botは`channel`で指定されたchannelに参加している必要があります。 + +### tokenの問題 + +**「Failed to connect」または認証エラー:** + +- `accessToken`がOAuth access tokenの値であることを確認してください（通常は`oauth:`プレフィックスで始まります） +- tokenに`chat:read`と`chat:write`のscopeがあることを確認してください +- token更新を使っている場合は、`clientSecret`と`refreshToken`が設定されていることを確認してください + +### token更新が機能しない + +**更新イベントのログを確認:** + +``` +Using env token source for mybot +Access token refreshed for user 123456 (expires in 14400s) +``` + +「token refresh disabled (no refresh token)」と表示される場合: + +- `clientSecret`が提供されていることを確認してください +- `refreshToken`が提供されていることを確認してください + +## Config + +**Account config:** + +- `username` - Bot username +- `accessToken` - `chat:read`と`chat:write`を持つOAuth access token +- `clientId` - Twitch Client ID（Token Generatorまたは独自appから） +- `channel` - 参加するchannel（必須） +- `enabled` - このaccountを有効化（デフォルト: `true`） +- `clientSecret` - 任意: token自動更新用 +- `refreshToken` - 任意: token自動更新用 +- `expiresIn` - tokenの有効期限（秒） +- `obtainmentTimestamp` - token取得タイムスタンプ +- `allowFrom` - user ID allowlist +- `allowedRoles` - roleベースのアクセス制御（`"moderator" | "owner" | "vip" | "subscriber" | "all"`） +- `requireMention` - @mention必須（デフォルト: `true`） + +**Provider options:** + +- `channels.twitch.enabled` - channel起動の有効/無効 +- `channels.twitch.username` - Bot username（簡略化された単一account config） +- `channels.twitch.accessToken` - OAuth access token（簡略化された単一account config） +- `channels.twitch.clientId` - Twitch Client ID（簡略化された単一account config） +- `channels.twitch.channel` - 参加するchannel（簡略化された単一account config） +- `channels.twitch.accounts.` - マルチaccount config（上記のすべてのaccountフィールド） + +完全な例: + +```json5 +{ + channels: { + twitch: { + enabled: true, + username: "openclaw", + accessToken: "oauth:abc123...", + clientId: "xyz789...", + channel: "vevisk", + clientSecret: "secret123...", + refreshToken: "refresh456...", + allowFrom: ["123456789"], + allowedRoles: ["moderator", "vip"], + accounts: { + default: { + username: "mybot", + accessToken: "oauth:abc123...", + clientId: "xyz789...", + channel: "your_channel", + enabled: true, + clientSecret: "secret123...", + refreshToken: "refresh456...", + expiresIn: 14400, + obtainmentTimestamp: 1706092800000, + allowFrom: ["123456789", "987654321"], + allowedRoles: ["moderator"], + }, + }, + }, + }, +} +``` + +## Tool actions + +agentは次のactionで`twitch`を呼び出せます。 + +- `send` - channelにメッセージを送信 + +例: + +```json5 +{ + action: "twitch", + params: { + message: "Hello Twitch!", + to: "#mychannel", + }, +} +``` + +## 安全性と運用 + +- **tokenはパスワードとして扱う** - tokenをgitにコミットしないでください +- **長時間動作するbotには自動token更新を使う** +- **アクセス制御にはusernameではなくuser ID allowlistを使う** +- **ログを監視する** - token更新イベントと接続状態を確認してください +- **tokenのscopeは最小限にする** - `chat:read`と`chat:write`のみを要求してください +- **行き詰まった場合**: 他のプロセスがsessionを所有していないことを確認してからGatewayを再起動してください + +## 制限 + +- **1メッセージあたり500文字**（単語境界で自動分割） +- chunking前にMarkdownは除去されます +- レート制限なし（Twitch組み込みのレート制限を使用） + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのchannels +- [Pairing](/channels/pairing) — DM認証とペアリングフロー +- [Groups](/channels/groups) — グループchatの挙動とmentionゲート +- [Channel Routing](/channels/channel-routing) — メッセージのsessionルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/whatsapp.md b/docs/ja-JP/channels/whatsapp.md new file mode 100644 index 000000000..449b2773f --- /dev/null +++ b/docs/ja-JP/channels/whatsapp.md @@ -0,0 +1,493 @@ +--- +read_when: + - WhatsApp/webチャンネルの動作や受信トレイルーティングに取り組むとき +summary: WhatsAppチャンネルのサポート、アクセス制御、配信動作、運用 +title: WhatsApp +x-i18n: + generated_at: "2026-04-05T12:37:43Z" + model: gpt-5.4 + provider: openai + source_hash: c16a468b3f47fdf7e4fc3fd745b5c49c7ccebb7af0e8c87c632b78b04c583e49 + source_path: channels/whatsapp.md + workflow: 15 +--- + +# WhatsApp（Webチャンネル） + +ステータス: WhatsApp Web（Baileys）経由で本番運用対応。Gatewayがリンク済みセッションを管理します。 + +## インストール（必要時） + +- オンボーディング（`openclaw onboard`）および`openclaw channels add --channel whatsapp`では、初めて選択したときにWhatsApp pluginのインストールを促します。 +- `openclaw channels login --channel whatsapp`でも、pluginがまだ存在しない場合はインストールフローが提示されます。 +- Devチャンネル + gitチェックアウトでは、デフォルトでローカルpluginパスが使用されます。 +- Stable/Betaでは、デフォルトでnpmパッケージ`@openclaw/whatsapp`が使用されます。 + +手動インストールも引き続き利用できます。 + +```bash +openclaw plugins install @openclaw/whatsapp +``` + + + + 未知の送信者に対するデフォルトのDMポリシーはpairingです。 + + + チャンネル横断の診断と修復プレイブックです。 + + + 完全なチャンネル設定パターンと例です。 + + + +## クイックセットアップ + + + + +```json5 +{ + channels: { + whatsapp: { + dmPolicy: "pairing", + allowFrom: ["+15551234567"], + groupPolicy: "allowlist", + groupAllowFrom: ["+15551234567"], + }, + }, +} +``` + + + + + +```bash +openclaw channels login --channel whatsapp +``` + + 特定のアカウントの場合: + +```bash +openclaw channels login --channel whatsapp --account work +``` + + + + + +```bash +openclaw gateway +``` + + + + + +```bash +openclaw pairing list whatsapp +openclaw pairing approve whatsapp +``` + + Pairingリクエストは1時間後に期限切れになります。保留中のリクエストはチャンネルごとに3件までです。 + + + + + +OpenClawでは、可能であればWhatsAppを別の番号で運用することを推奨しています。（チャンネルメタデータとセットアップフローはその構成向けに最適化されていますが、個人番号での構成もサポートされています。） + + +## デプロイパターン + + + + これは最も運用しやすいモードです。 + + - OpenClaw用に分離されたWhatsApp ID + - より明確なDM allowlistとルーティング境界 + - 自分とのチャット混乱が起きる可能性が低い + + 最小ポリシーパターン: + + ```json5 + { + channels: { + whatsapp: { + dmPolicy: "allowlist", + allowFrom: ["+15551234567"], + }, + }, + } + ``` + + + + + オンボーディングは個人番号モードをサポートしており、自分とのチャットに適したベースラインを書き込みます。 + + - `dmPolicy: "allowlist"` + - `allowFrom`に自分の個人番号を含める + - `selfChatMode: true` + + ランタイムでは、自分とのチャット保護はリンク済みの自分の番号と`allowFrom`をもとに動作します。 + + + + + 現在のOpenClawチャンネルアーキテクチャでは、メッセージングプラットフォームチャンネルはWhatsApp Webベース（`Baileys`）です。 + + 組み込みのチャットチャンネルレジストリには、別個のTwilio WhatsAppメッセージングチャンネルはありません。 + + + + +## ランタイムモデル + +- GatewayがWhatsAppソケットと再接続ループを管理します。 +- 送信には、対象アカウントに対するアクティブなWhatsAppリスナーが必要です。 +- ステータスチャットとブロードキャストチャットは無視されます（`@status`、`@broadcast`）。 +- ダイレクトチャットではDMセッションルール（`session.dmScope`）が使われます。デフォルトの`main`ではDMはagentのメインセッションに統合されます。 +- グループセッションは分離されます（`agent::whatsapp:group:`）。 + +## アクセス制御と有効化 + + + + `channels.whatsapp.dmPolicy`はダイレクトチャットアクセスを制御します。 + + - `pairing`（デフォルト） + - `allowlist` + - `open`（`allowFrom`に`"*"`を含める必要があります） + - `disabled` + + `allowFrom`はE.164形式の番号を受け付けます（内部で正規化されます）。 + + マルチアカウント上書き: `channels.whatsapp.accounts..dmPolicy`（および`allowFrom`）は、そのアカウントに対してチャンネルレベルのデフォルトより優先されます。 + + ランタイム動作の詳細: + + - pairingsはチャンネルallow-storeに永続化され、設定済みの`allowFrom`とマージされます + - allowlistが設定されていない場合、リンク済みの自分の番号はデフォルトで許可されます + - 送信元が`fromMe`のDMは自動pairingされません + + + + + グループアクセスには2つのレイヤーがあります。 + + 1. **グループメンバーシップallowlist**（`channels.whatsapp.groups`） + - `groups`が省略されている場合、すべてのグループが対象になります + - `groups`が存在する場合、それはグループallowlistとして動作します（`"*"`可） + + 2. **グループ送信者ポリシー**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`） + - `open`: 送信者allowlistをバイパス + - `allowlist`: 送信者は`groupAllowFrom`（または`*`）に一致する必要があります + - `disabled`: すべてのグループ受信をブロック + + 送信者allowlistのフォールバック: + + - `groupAllowFrom`が未設定の場合、利用可能であればランタイムは`allowFrom`にフォールバックします + - 送信者allowlistはmention/返信による有効化の前に評価されます + + 注記: `channels.whatsapp`ブロック自体がまったく存在しない場合、ランタイムのグループポリシーフォールバックは`allowlist`です（警告ログあり）。`channels.defaults.groupPolicy`が設定されていても同様です。 + + + + + グループ返信はデフォルトでmentionを必要とします。 + + Mention検出には次が含まれます。 + + - bot IDに対する明示的なWhatsApp mention + - 設定済みmention正規表現パターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは`messages.groupChat.mentionPatterns`） + - bot IDに一致する返信送信者による暗黙のreply-to-bot検出 + + セキュリティ注記: + + - 引用/返信はmentionゲーティングを満たすだけであり、送信者認可は付与しません + - `groupPolicy: "allowlist"`では、allowlistにない送信者は、allowlist済みユーザーのメッセージに返信していてもブロックされます + + セッションレベルの有効化コマンド: + + - `/activation mention` + - `/activation always` + + `activation`はセッション状態を更新します（グローバルconfigではありません）。owner-gatedです。 + + + + +## 個人番号と自分とのチャット動作 + +リンク済みの自分の番号が`allowFrom`にも含まれている場合、WhatsAppの自分とのチャット保護が有効になります。 + +- 自分とのチャットターンでは既読通知をスキップ +- 本来なら自分自身にpingするmention-JID自動トリガー動作を無視 +- `messages.responsePrefix`が未設定の場合、自分とのチャット返信のデフォルトは`[{identity.name}]`または`[openclaw]` + +## メッセージ正規化とコンテキスト + + + + 受信したWhatsAppメッセージは共有の受信エンベロープでラップされます。 + + 引用返信が存在する場合、コンテキストは次の形式で追加されます。 + + ```text + [Replying to id:] + + [/Replying] + ``` + + 返信メタデータフィールドも、利用可能な場合は設定されます（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、sender JID/E.164）。 + + + + + メディアのみの受信メッセージは、次のようなプレースホルダーで正規化されます。 + + - `` + - `` + - `` + - `` + - `` + + 位置情報および連絡先ペイロードは、ルーティング前にテキストコンテキストへ正規化されます。 + + + + + グループでは、未処理メッセージをバッファリングし、botが最終的にトリガーされたときにコンテキストとして注入できます。 + + - デフォルト上限: `50` + - config: `channels.whatsapp.historyLimit` + - フォールバック: `messages.groupChat.historyLimit` + - `0`で無効化 + + 注入マーカー: + + - `[Chat messages since your last reply - for context]` + - `[Current message - respond to this]` + + + + + 既読通知は、受け付けられた受信WhatsAppメッセージに対してデフォルトで有効です。 + + グローバルに無効化する場合: + + ```json5 + { + channels: { + whatsapp: { + sendReadReceipts: false, + }, + }, + } + ``` + + アカウントごとの上書き: + + ```json5 + { + channels: { + whatsapp: { + accounts: { + work: { + sendReadReceipts: false, + }, + }, + }, + }, + } + ``` + + 自分とのチャットターンでは、グローバルに有効でも既読通知はスキップされます。 + + + + +## 配信、チャンク化、メディア + + + + - デフォルトのチャンク上限: `channels.whatsapp.textChunkLimit = 4000` + - `channels.whatsapp.chunkMode = "length" | "newline"` + - `newline`モードでは段落境界（空行）を優先し、その後で長さ安全なチャンク化にフォールバックします + + + + - 画像、動画、音声（PTTボイスノート）、ドキュメントのペイロードをサポート + - `audio/ogg`は、ボイスノート互換性のため`audio/ogg; codecs=opus`に書き換えられます + - アニメーションGIF再生は、動画送信時の`gifPlayback: true`でサポートされます + - 複数メディア返信ペイロードを送信する際、キャプションは最初のメディア項目に適用されます + - メディアソースにはHTTP(S)、`file://`、ローカルパスを使用できます + + + + - 受信メディア保存上限: `channels.whatsapp.mediaMaxMb`（デフォルト`50`） + - 送信メディア送信上限: `channels.whatsapp.mediaMaxMb`（デフォルト`50`） + - アカウントごとの上書きには`channels.whatsapp.accounts..mediaMaxMb`を使用します + - 画像は制限内に収めるため自動最適化されます（リサイズ/品質スイープ） + - メディア送信失敗時には、先頭項目フォールバックとしてテキスト警告を送信し、応答が黙って失われることを防ぎます + + + +## リアクションレベル + +`channels.whatsapp.reactionLevel`は、agentがWhatsAppで絵文字リアクションをどの程度広く使用するかを制御します。 + +| レベル | Ackリアクション | agent起点リアクション | 説明 | +| ------------- | --------------- | ------------------------- | ------------------------------------------------ | +| `"off"` | いいえ | いいえ | リアクションを一切行いません | +| `"ack"` | はい | いいえ | Ackリアクションのみ（返信前の受領） | +| `"minimal"` | はい | はい（保守的） | Ack + 保守的ガイダンス付きagentリアクション | +| `"extensive"` | はい | はい（推奨） | Ack + 推奨ガイダンス付きagentリアクション | + +デフォルト: `"minimal"`。 + +アカウントごとの上書きには`channels.whatsapp.accounts..reactionLevel`を使用します。 + +```json5 +{ + channels: { + whatsapp: { + reactionLevel: "ack", + }, + }, +} +``` + +## 確認応答リアクション + +WhatsAppは、`channels.whatsapp.ackReaction`を介して受信時の即時ackリアクションをサポートします。 +Ackリアクションは`reactionLevel`で制御され、`reactionLevel`が`"off"`のときは抑制されます。 + +```json5 +{ + channels: { + whatsapp: { + ackReaction: { + emoji: "👀", + direct: true, + group: "mentions", // always | mentions | never + }, + }, + }, +} +``` + +動作上の注意: + +- 受信が受理された直後に送信されます（返信前） +- 失敗はログに記録されますが、通常の返信配信は妨げません +- グループモード`mentions`では、mentionトリガーのターンにリアクションします。グループ有効化`always`はこのチェックをバイパスします +- WhatsAppでは`channels.whatsapp.ackReaction`を使用します（legacyの`messages.ackReaction`はここでは使用しません） + +## マルチアカウントと認証情報 + + + + - アカウントIDは`channels.whatsapp.accounts`から取得されます + - デフォルトアカウント選択: `default`があればそれ、なければ最初に設定されたアカウントID（ソート順） + - アカウントIDは内部でルックアップ用に正規化されます + + + + - 現在の認証パス: `~/.openclaw/credentials/whatsapp//creds.json` + - バックアップファイル: `creds.json.bak` + - `~/.openclaw/credentials/`内のlegacyデフォルト認証も、デフォルトアカウントフローでは引き続き認識/移行されます + + + + `openclaw channels logout --channel whatsapp [--account ]`は、そのアカウントのWhatsApp認証状態を消去します。 + + legacy認証ディレクトリでは、Baileys認証ファイルは削除されますが`oauth.json`は保持されます。 + + + + +## ツール、アクション、config書き込み + +- AgentツールサポートにはWhatsAppリアクションアクション（`react`）が含まれます。 +- アクションゲート: + - `channels.whatsapp.actions.reactions` + - `channels.whatsapp.actions.polls` +- チャンネル起点のconfig書き込みはデフォルトで有効です（`channels.whatsapp.configWrites=false`で無効化）。 + +## トラブルシューティング + + + + 症状: チャンネルステータスが未リンクと表示されます。 + + 修正: + + ```bash + openclaw channels login --channel whatsapp + openclaw channels status + ``` + + + + + 症状: アカウントはリンク済みだが、切断や再接続試行が繰り返されます。 + + 修正: + + ```bash + openclaw doctor + openclaw logs --follow + ``` + + 必要に応じて、`channels login`で再リンクしてください。 + + + + + 対象アカウントに対するアクティブなgatewayリスナーが存在しない場合、送信は即座に失敗します。 + + Gatewayが動作中で、アカウントがリンク済みであることを確認してください。 + + + + + 次の順序で確認してください。 + + - `groupPolicy` + - `groupAllowFrom` / `allowFrom` + - `groups` allowlistエントリー + - mentionゲーティング（`requireMention` + mention patterns） + - `openclaw.json`（JSON5）内の重複キー: 後ろのエントリーが前のものを上書きするため、スコープごとに`groupPolicy`は1つだけにしてください + + + + + WhatsApp gatewayランタイムではNodeを使用してください。Bunは、安定したWhatsApp/Telegram gateway運用と互換性がないとして扱われます。 + + + +## 設定リファレンスへのポインター + +主要リファレンス: + +- [Configuration reference - WhatsApp](/gateway/configuration-reference#whatsapp) + +重要なWhatsAppフィールド: + +- アクセス: `dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` +- 配信: `textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel` +- マルチアカウント: `accounts..enabled`、`accounts..authDir`、アカウントレベル上書き +- 運用: `configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*` +- セッション動作: `session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms..historyLimit` + +## 関連 + +- [Pairing](/channels/pairing) +- [Groups](/channels/groups) +- [Security](/gateway/security) +- [Channel routing](/channels/channel-routing) +- [Multi-agent routing](/concepts/multi-agent) +- [Troubleshooting](/channels/troubleshooting) diff --git a/docs/ja-JP/channels/zalo.md b/docs/ja-JP/channels/zalo.md new file mode 100644 index 000000000..f5a62b16e --- /dev/null +++ b/docs/ja-JP/channels/zalo.md @@ -0,0 +1,261 @@ +--- +read_when: + - Zaloの機能やwebhookに取り組んでいるとき +summary: Zaloボットのサポート状況、機能、設定 +title: Zalo +x-i18n: + generated_at: "2026-04-05T12:38:06Z" + model: gpt-5.4 + provider: openai + source_hash: ab94642ba28e79605b67586af8f71c18bc10e0af60343a7df508e6823b6f4119 + source_path: channels/zalo.md + workflow: 15 +--- + +# Zalo (Bot API) + +ステータス: 実験的。DMはサポートされています。以下の[機能](#capabilities)セクションには、現在のMarketplaceボットの挙動が反映されています。 + +## バンドル済みプラグイン + +Zaloは現在のOpenClawリリースにバンドル済みプラグインとして含まれているため、通常のパッケージ済み +ビルドでは別途インストールは不要です。 + +古いビルドまたはZaloを含まないカスタムインストールを使用している場合は、 +手動でインストールしてください。 + +- CLIでインストール: `openclaw plugins install @openclaw/zalo` +- またはソースチェックアウトから: `openclaw plugins install ./path/to/local/zalo-plugin` +- 詳細: [Plugins](/tools/plugin) + +## クイックセットアップ（初級者向け） + +1. Zaloプラグインが利用可能であることを確認します。 + - 現在のパッケージ版OpenClawリリースには、すでにバンドルされています。 + - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 +2. トークンを設定します。 + - 環境変数: `ZALO_BOT_TOKEN=...` + - または設定: `channels.zalo.accounts.default.botToken: "..."`。 +3. Gatewayを再起動します（またはセットアップを完了します）。 +4. DMアクセスはデフォルトでペアリングです。初回接触時にペアリングコードを承認してください。 + +最小構成: + +```json5 +{ + channels: { + zalo: { + enabled: true, + accounts: { + default: { + botToken: "12345689:abc-xyz", + dmPolicy: "pairing", + }, + }, + }, + }, +} +``` + +## これは何か + +Zaloはベトナムで広く使われているメッセージングアプリです。そのBot APIにより、Gatewayは1対1の会話用ボットを実行できます。 +Zaloへの決定論的な返信ルーティングが必要なサポートや通知に適しています。 + +このページは、**Zalo Bot Creator / Marketplace bots**に対する現在のOpenClawの挙動を反映しています。 +**Zalo Official Account (OA) bots**は別のZalo製品サーフェスであり、挙動が異なる場合があります。 + +- Gatewayが所有するZalo Bot APIチャンネル。 +- 決定論的ルーティング: 返信はZaloに戻り、モデルがチャンネルを選ぶことはありません。 +- DMはエージェントのメインセッションを共有します。 +- 以下の[機能](#capabilities)セクションに、現在のMarketplaceボットのサポート状況を示しています。 + +## セットアップ（短縮手順） + +### 1) ボットトークンを作成する（Zalo Bot Platform） + +1. [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com)にアクセスしてサインインします。 +2. 新しいボットを作成し、その設定を行います。 +3. 完全なボットトークン（通常は`numeric_id:secret`）をコピーします。Marketplaceボットでは、利用可能なランタイムトークンが作成後のボット歓迎メッセージ内に表示されることがあります。 + +### 2) トークンを設定する（環境変数または設定） + +例: + +```json5 +{ + channels: { + zalo: { + enabled: true, + accounts: { + default: { + botToken: "12345689:abc-xyz", + dmPolicy: "pairing", + }, + }, + }, + }, +} +``` + +後でグループが利用可能なZaloボットサーフェスへ移行する場合は、`groupPolicy`や`groupAllowFrom`のようなグループ固有設定を明示的に追加できます。現在のMarketplaceボットの挙動については、[機能](#capabilities)を参照してください。 + +環境変数オプション: `ZALO_BOT_TOKEN=...`（デフォルトアカウントでのみ動作）。 + +複数アカウント対応: `channels.zalo.accounts`を使用し、アカウントごとのトークンと任意の`name`を設定します。 + +3. Gatewayを再起動します。Zaloはトークンが解決されると起動します（環境変数または設定）。 +4. DMアクセスはデフォルトでペアリングです。ボットに初めて接触したときにコードを承認してください。 + +## 仕組み（動作） + +- 受信メッセージは、メディアプレースホルダー付きの共有チャンネルエンベロープに正規化されます。 +- 返信は常に同じZaloチャットにルーティングされます。 +- デフォルトはlong-pollingで、`channels.zalo.webhookUrl`を使うとwebhookモードも利用できます。 + +## 制限 + +- 送信テキストは2000文字単位に分割されます（Zalo API制限）。 +- メディアのダウンロード/アップロードは`channels.zalo.mediaMaxMb`で制限されます（デフォルト5）。 +- 2000文字制限によりストリーミングの有用性が低いため、デフォルトでストリーミングはブロックされます。 + +## アクセス制御（DM） + +### DMアクセス + +- デフォルト: `channels.zalo.dmPolicy = "pairing"`。不明な送信者にはペアリングコードが返され、承認されるまでメッセージは無視されます（コードは1時間で期限切れ）。 +- 承認方法: + - `openclaw pairing list zalo` + - `openclaw pairing approve zalo ` +- ペアリングがデフォルトのトークン交換です。詳細: [Pairing](/channels/pairing) +- `channels.zalo.allowFrom`は数値のユーザーIDを受け付けます（ユーザー名参照は利用不可）。 + +## アクセス制御（グループ） + +**Zalo Bot Creator / Marketplace bots**では、実際にはボットをグループに追加できなかったため、グループサポートは利用できませんでした。 + +つまり、以下のグループ関連設定キーはスキーマには存在しますが、Marketplaceボットでは使用できませんでした。 + +- `channels.zalo.groupPolicy`は、グループ受信処理を制御します: `open | allowlist | disabled`。 +- `channels.zalo.groupAllowFrom`は、グループ内でどの送信者IDがボットをトリガーできるかを制限します。 +- `groupAllowFrom`が未設定の場合、Zaloは送信者チェックに`allowFrom`へフォールバックします。 +- ランタイム注記: `channels.zalo`自体が完全に欠落している場合でも、安全のためランタイムは引き続き`groupPolicy="allowlist"`へフォールバックします。 + +グループポリシーの値（利用しているボットサーフェスでグループアクセスが可能な場合）は次のとおりです。 + +- `groupPolicy: "disabled"` — すべてのグループメッセージをブロックします。 +- `groupPolicy: "open"` — 任意のグループメンバーを許可します（メンション制御あり）。 +- `groupPolicy: "allowlist"` — fail-closedのデフォルトで、許可された送信者のみ受け付けます。 + +異なるZaloボット製品サーフェスを使用しており、グループ挙動が動作することを確認している場合は、Marketplaceボットのフローと同じだと仮定せず、別途文書化してください。 + +## Long-polling と webhook + +- デフォルト: long-polling（公開URL不要）。 +- webhookモード: `channels.zalo.webhookUrl`と`channels.zalo.webhookSecret`を設定します。 + - webhookシークレットは8～256文字である必要があります。 + - webhook URLはHTTPSを使用する必要があります。 + - Zaloは検証用に`X-Bot-Api-Secret-Token`ヘッダー付きでイベントを送信します。 + - Gateway HTTPは`channels.zalo.webhookPath`でwebhookリクエストを処理します（デフォルトはwebhook URLのパス）。 + - リクエストは`Content-Type: application/json`（または`+json`メディアタイプ）を使用する必要があります。 + - 重複イベント（`event_name + message_id`）は短いリプレイウィンドウの間、無視されます。 + - バーストトラフィックはパス/送信元ごとにレート制限され、HTTP 429が返る場合があります。 + +**注:** Zalo APIドキュメントによると、getUpdates（polling）とwebhookは相互排他的です。 + +## サポートされるメッセージタイプ + +簡単なサポート状況は[機能](#capabilities)を参照してください。以下の注記では、追加の文脈が必要な挙動を補足しています。 + +- **テキストメッセージ**: 2000文字分割付きで完全サポート。 +- **テキスト内のプレーンURL**: 通常のテキスト入力と同様に動作します。 +- **リンクプレビュー / リッチリンクカード**: [機能](#capabilities)のMarketplaceボット状況を参照してください。安定して返信をトリガーしませんでした。 +- **画像メッセージ**: [機能](#capabilities)のMarketplaceボット状況を参照してください。受信画像処理は不安定でした（入力中表示は出るが最終返信なし）。 +- **ステッカー**: [機能](#capabilities)のMarketplaceボット状況を参照してください。 +- **ボイスノート / 音声ファイル / 動画 / 汎用ファイル添付**: [機能](#capabilities)のMarketplaceボット状況を参照してください。 +- **未対応タイプ**: ログ出力されます（例: 保護されたユーザーからのメッセージ）。 + +## 機能 + +この表は、OpenClawにおける現在の**Zalo Bot Creator / Marketplace bot**の挙動をまとめたものです。 + +| 機能 | ステータス | +| --------------------------- | --------------------------------------- | +| ダイレクトメッセージ | ✅ サポート | +| グループ | ❌ Marketplaceボットでは利用不可 | +| メディア（受信画像） | ⚠️ 限定的 / 環境で要確認 | +| メディア（送信画像） | ⚠️ Marketplaceボットでは未再検証 | +| テキスト内のプレーンURL | ✅ サポート | +| リンクプレビュー | ⚠️ Marketplaceボットでは不安定 | +| リアクション | ❌ 未サポート | +| ステッカー | ⚠️ Marketplaceボットではエージェント返信なし | +| ボイスノート / 音声 / 動画 | ⚠️ Marketplaceボットではエージェント返信なし | +| ファイル添付 | ⚠️ Marketplaceボットではエージェント返信なし | +| スレッド | ❌ 未サポート | +| Polls | ❌ 未サポート | +| ネイティブコマンド | ❌ 未サポート | +| ストリーミング | ⚠️ ブロック済み（2000文字制限） | + +## 配信先ターゲット（CLI/cron） + +- ターゲットにはchat idを使用します。 +- 例: `openclaw message send --channel zalo --target 123456789 --message "hi"`。 + +## トラブルシューティング + +**ボットが応答しない:** + +- トークンが有効か確認する: `openclaw channels status --probe` +- 送信者が承認済みであることを確認する（ペアリングまたはallowFrom） +- Gatewayログを確認する: `openclaw logs --follow` + +**webhookでイベントを受信しない:** + +- webhook URLがHTTPSを使用していることを確認する +- シークレットトークンが8～256文字であることを確認する +- 設定されたパスでGateway HTTPエンドポイントに到達できることを確認する +- getUpdates pollingが実行中でないことを確認する（相互排他的です） + +## 設定リファレンス（Zalo） + +完全な設定: [Configuration](/gateway/configuration) + +フラットなトップレベルキー（`channels.zalo.botToken`、`channels.zalo.dmPolicy`など）は、レガシーな単一アカウント用ショートハンドです。新しい設定では`channels.zalo.accounts..*`を推奨します。両方の形式はスキーマ内に存在するため、ここでも引き続き文書化しています。 + +プロバイダーオプション: + +- `channels.zalo.enabled`: チャンネル起動を有効化/無効化します。 +- `channels.zalo.botToken`: Zalo Bot Platformのボットトークン。 +- `channels.zalo.tokenFile`: 通常のファイルパスからトークンを読み取ります。symlinkは拒否されます。 +- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled`（デフォルト: pairing）。 +- `channels.zalo.allowFrom`: DM許可リスト（ユーザーID）。`open`には`"*"`が必要です。ウィザードでは数値IDを尋ねます。 +- `channels.zalo.groupPolicy`: `open | allowlist | disabled`（デフォルト: allowlist）。設定には存在します。現在のMarketplaceボットの挙動については、[機能](#capabilities)および[アクセス制御（グループ）](#access-control-groups)を参照してください。 +- `channels.zalo.groupAllowFrom`: グループ送信者許可リスト（ユーザーID）。未設定時は`allowFrom`へフォールバックします。 +- `channels.zalo.mediaMaxMb`: 受信/送信メディア上限（MB、デフォルト5）。 +- `channels.zalo.webhookUrl`: webhookモードを有効化します（HTTPS必須）。 +- `channels.zalo.webhookSecret`: webhookシークレット（8～256文字）。 +- `channels.zalo.webhookPath`: Gateway HTTPサーバー上のwebhookパス。 +- `channels.zalo.proxy`: APIリクエスト用プロキシURL。 + +複数アカウントオプション: + +- `channels.zalo.accounts..botToken`: アカウントごとのトークン。 +- `channels.zalo.accounts..tokenFile`: アカウントごとの通常のトークンファイル。symlinkは拒否されます。 +- `channels.zalo.accounts..name`: 表示名。 +- `channels.zalo.accounts..enabled`: アカウントを有効化/無効化します。 +- `channels.zalo.accounts..dmPolicy`: アカウントごとのDMポリシー。 +- `channels.zalo.accounts..allowFrom`: アカウントごとの許可リスト。 +- `channels.zalo.accounts..groupPolicy`: アカウントごとのグループポリシー。設定には存在します。現在のMarketplaceボットの挙動については、[機能](#capabilities)および[アクセス制御（グループ）](#access-control-groups)を参照してください。 +- `channels.zalo.accounts..groupAllowFrom`: アカウントごとのグループ送信者許可リスト。 +- `channels.zalo.accounts..webhookUrl`: アカウントごとのwebhook URL。 +- `channels.zalo.accounts..webhookSecret`: アカウントごとのwebhookシークレット。 +- `channels.zalo.accounts..webhookPath`: アカウントごとのwebhookパス。 +- `channels.zalo.accounts..proxy`: アカウントごとのプロキシURL。 + +## 関連 + +- [Channels Overview](/channels) — サポートされるすべてのチャンネル +- [Pairing](/channels/pairing) — DM認証とペアリングフロー +- [Groups](/channels/groups) — グループチャットの挙動とメンション制御 +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/channels/zalouser.md b/docs/ja-JP/channels/zalouser.md new file mode 100644 index 000000000..7c2a296fb --- /dev/null +++ b/docs/ja-JP/channels/zalouser.md @@ -0,0 +1,202 @@ +--- +read_when: + - OpenClaw 用に Zalo Personal をセットアップしている + - Zalo Personal のログインまたはメッセージフローをデバッグしている +summary: ネイティブ `zca-js`（QR ログイン）による Zalo 個人アカウントのサポート、機能、設定 +title: Zalo Personal +x-i18n: + generated_at: "2026-04-05T12:37:53Z" + model: gpt-5.4 + provider: openai + source_hash: 331b95041463185472d242cb0a944972f0a8e99df8120bda6350eca86ad5963f + source_path: channels/zalouser.md + workflow: 15 +--- + +# Zalo Personal（非公式） + +ステータス: 実験的。この統合は、OpenClaw 内でネイティブ `zca-js` を使って **個人の Zalo アカウント** を自動化します。 + +> **警告:** これは非公式の統合であり、アカウントの停止や BAN につながる可能性があります。自己責任で使用してください。 + +## バンドルされたプラグイン + +Zalo Personal は現在の OpenClaw リリースではバンドルされたプラグインとして同梱されているため、通常の +パッケージ版ビルドでは別途インストールは不要です。 + +古いビルドまたは Zalo Personal を含まないカスタムインストールを使用している場合は、 +手動でインストールしてください。 + +- CLI でインストール: `openclaw plugins install @openclaw/zalouser` +- またはソースチェックアウトから: `openclaw plugins install ./path/to/local/zalouser-plugin` +- 詳細: [Plugins](/tools/plugin) + +外部の `zca`/`openzca` CLI バイナリは不要です。 + +## クイックセットアップ（初心者向け） + +1. Zalo Personal プラグインが利用可能であることを確認します。 + - 現在のパッケージ版 OpenClaw リリースにはすでに同梱されています。 + - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 +2. ログインします（Gateway マシン上で QR を使用）: + - `openclaw channels login --channel zalouser` + - Zalo モバイルアプリで QR コードをスキャンします。 +3. チャネルを有効にします: + +```json5 +{ + channels: { + zalouser: { + enabled: true, + dmPolicy: "pairing", + }, + }, +} +``` + +4. Gateway を再起動します（またはセットアップを完了します）。 +5. DM アクセスはデフォルトで pairing です。最初の接触時にペアリングコードを承認してください。 + +## これは何か + +- 完全に `zca-js` を使ってインプロセスで動作します。 +- ネイティブのイベントリスナーを使って受信メッセージを受け取ります。 +- JS API を通じて返信を直接送信します（テキスト/メディア/リンク）。 +- Zalo Bot API が利用できない「個人アカウント」用途向けに設計されています。 + +## 命名 + +チャネル ID は `zalouser` です。これは **個人の Zalo ユーザーアカウント**（非公式）を自動化することを明示するためです。`zalo` は、将来の公式 Zalo API 統合のために予約されたままになっています。 + +## ID の見つけ方（directory） + +directory CLI を使って peers/groups とその ID を確認します。 + +```bash +openclaw directory self --channel zalouser +openclaw directory peers list --channel zalouser --query "name" +openclaw directory groups list --channel zalouser --query "work" +``` + +## 制限 + +- 送信テキストは約 2000 文字ごとに分割されます（Zalo クライアントの制限）。 +- ストリーミングはデフォルトでブロックされます。 + +## アクセス制御（DM） + +`channels.zalouser.dmPolicy` では次をサポートします: `pairing | allowlist | open | disabled`（デフォルト: `pairing`）。 + +`channels.zalouser.allowFrom` にはユーザー ID または名前を指定できます。セットアップ中に、名前はプラグインのインプロセス連絡先検索を使って ID に解決されます。 + +承認方法: + +- `openclaw pairing list zalouser` +- `openclaw pairing approve zalouser ` + +## グループアクセス（省略可） + +- デフォルト: `channels.zalouser.groupPolicy = "open"`（グループを許可）。未設定時のデフォルトを上書きするには `channels.defaults.groupPolicy` を使用します。 +- 許可リストで制限するには: + - `channels.zalouser.groupPolicy = "allowlist"` + - `channels.zalouser.groups`（キーには安定したグループ ID を使うべきです。可能な場合、名前は起動時に ID に解決されます） + - `channels.zalouser.groupAllowFrom`（許可されたグループ内でどの送信者がボットをトリガーできるかを制御します） +- すべてのグループをブロックする: `channels.zalouser.groupPolicy = "disabled"`。 +- 設定ウィザードではグループ許可リストを尋ねることができます。 +- 起動時に、OpenClaw は許可リスト内のグループ名/ユーザー名を ID に解決し、その対応をログに記録します。 +- グループ許可リストの照合はデフォルトで ID のみです。未解決の名前は、`channels.zalouser.dangerouslyAllowNameMatching: true` が有効でない限り、認証では無視されます。 +- `channels.zalouser.dangerouslyAllowNameMatching: true` は、変更可能なグループ名照合を再有効化する緊急用の互換モードです。 +- `groupAllowFrom` が未設定の場合、ランタイムはグループ送信者チェックに `allowFrom` へフォールバックします。 +- 送信者チェックは通常のグループメッセージと制御コマンド（たとえば `/new`、`/reset`）の両方に適用されます。 + +例: + +```json5 +{ + channels: { + zalouser: { + groupPolicy: "allowlist", + groupAllowFrom: ["1471383327500481391"], + groups: { + "123456789": { allow: true }, + "Work Chat": { allow: true }, + }, + }, + }, +} +``` + +### グループメンションゲート + +- `channels.zalouser.groups..requireMention` は、グループ返信にメンションが必要かどうかを制御します。 +- 解決順序: 正確なグループ id/名前 -> 正規化されたグループ slug -> `*` -> デフォルト（`true`）。 +- これは許可リスト対象のグループと open グループモードの両方に適用されます。 +- 認可された制御コマンド（たとえば `/new`）はメンションゲートをバイパスできます。 +- メンションが必要なためにグループメッセージがスキップされた場合、OpenClaw はそれを保留中のグループ履歴として保存し、次に処理されるグループメッセージに含めます。 +- グループ履歴の上限はデフォルトで `messages.groupChat.historyLimit`（フォールバック `50`）です。アカウントごとに `channels.zalouser.historyLimit` で上書きできます。 + +例: + +```json5 +{ + channels: { + zalouser: { + groupPolicy: "allowlist", + groups: { + "*": { allow: true, requireMention: true }, + "Work Chat": { allow: true, requireMention: false }, + }, + }, + }, +} +``` + +## マルチアカウント + +アカウントは OpenClaw の状態内の `zalouser` プロファイルに対応します。例: + +```json5 +{ + channels: { + zalouser: { + enabled: true, + defaultAccount: "default", + accounts: { + work: { enabled: true, profile: "work" }, + }, + }, + }, +} +``` + +## 入力中表示、リアクション、配信確認 + +- OpenClaw は返信を送信する前に入力中イベントを送ります（ベストエフォート）。 +- メッセージリアクション操作 `react` は、チャネルアクションで `zalouser` をサポートしています。 + - メッセージから特定のリアクション絵文字を削除するには `remove: true` を使用します。 + - リアクションの仕様: [Reactions](/tools/reactions) +- イベントメタデータを含む受信メッセージに対して、OpenClaw は delivered + seen の確認応答を送ります（ベストエフォート）。 + +## トラブルシューティング + +**ログイン状態が保持されない:** + +- `openclaw channels status --probe` +- 再ログイン: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser` + +**許可リスト/グループ名が解決されなかった:** + +- `allowFrom`/`groupAllowFrom`/`groups` では数値 ID を使うか、正確な友だち名/グループ名を使ってください。 + +**古い CLI ベースのセットアップからアップグレードした:** + +- 古い外部 `zca` プロセス前提は削除してください。 +- このチャネルは現在、外部 CLI バイナリなしで完全に OpenClaw 内で動作します。 + +## 関連 + +- [Channels Overview](/channels) — サポートされているすべてのチャネル +- [Pairing](/channels/pairing) — DM 認証とペアリングフロー +- [Groups](/channels/groups) — グループチャットの挙動とメンションゲート +- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング +- [Security](/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/ci.md b/docs/ja-JP/ci.md new file mode 100644 index 000000000..ebe9c6f9d --- /dev/null +++ b/docs/ja-JP/ci.md @@ -0,0 +1,73 @@ +--- +read_when: + - CIジョブが実行された、または実行されなかった理由を理解する必要がある場合 + - 失敗しているGitHub Actionsチェックをデバッグしている場合 +summary: CIジョブグラフ、スコープゲート、ローカルコマンドの対応関係 +title: CI Pipeline +x-i18n: + generated_at: "2026-04-05T12:37:36Z" + model: gpt-5.4 + provider: openai + source_hash: 5a95b6e584b4309bc249866ea436b4dfe30e0298ab8916eadbc344edae3d1194 + source_path: ci.md + workflow: 15 +--- + +# CI Pipeline + +CIは`main`へのすべてのpushと、すべてのpull requestで実行されます。スマートなスコープ判定を使って、変更が無関係な領域だけの場合は高コストなジョブをスキップします。 + +## ジョブ概要 + +| Job | 目的 | 実行されるタイミング | +| ------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------- | +| `preflight` | docsのみの変更、変更されたスコープ、変更されたextensionsを検出し、CI manifestを構築 | draftではないpushとPRで常に実行 | +| `security-fast` | 秘密鍵検出、`zizmor`によるworkflow監査、本番依存関係の監査 | draftではないpushとPRで常に実行 | +| `build-artifacts` | `dist/`とControl UIを一度ビルドし、下流ジョブ向けの再利用可能artifactsをアップロード | Node関連の変更 | +| `checks-fast-core` | bundled/plugin-contract/protocolチェックなどの高速Linux正当性レーン | Node関連の変更 | +| `checks-fast-extensions` | `checks-fast-extensions-shard`完了後にextension shardレーンを集約 | Node関連の変更 | +| `extension-fast` | 変更されたbundled pluginsのみを対象にした集中テスト | extensionの変更が検出された場合 | +| `check` | CIにおけるメインのローカルgate: `pnpm check` と `pnpm build:strict-smoke` | Node関連の変更 | +| `check-additional` | アーキテクチャおよび境界ガードと、gateway watch回帰ハーネス | Node関連の変更 | +| `build-smoke` | ビルド済みCLIのスモークテストと起動時メモリスモーク | Node関連の変更 | +| `checks` | より重いLinux Nodeレーン: フルテスト、channelテスト、およびpush専用のNode 22互換性 | Node関連の変更 | +| `check-docs` | docsのフォーマット、lint、broken-linkチェック | docsが変更された場合 | +| `skills-python` | PythonベースのSkills向けRuff + pytest | Python-skill関連の変更 | +| `checks-windows` | Windows固有のテストレーン | Windows関連の変更 | +| `macos-node` | 共有のビルド済みartifactsを使用するmacOS TypeScriptテストレーン | macOS関連の変更 | +| `macos-swift` | macOS app向けのSwift lint、build、tests | macOS関連の変更 | +| `android` | Androidのbuildおよびtest matrix | Android関連の変更 | + +## Fail-Fastの順序 + +ジョブは、高コストなものが走る前に低コストなチェックが失敗するように順序付けされています。 + +1. `preflight`が、どのレーンをそもそも存在させるかを決定します。`docs-scope`と`changed-scope`のロジックは、このジョブ内のstepであり、独立したジョブではありません。 +2. `security-fast`、`check`、`check-additional`、`check-docs`、`skills-python`は、より重いartifactおよびplatform matrixジョブを待たずに素早く失敗します。 +3. `build-artifacts`は高速Linuxレーンと並行して実行されるため、下流の利用側は共有buildの準備ができ次第開始できます。 +4. その後、より重いplatformおよびruntimeレーンが分岐します: `checks-fast-core`、`checks-fast-extensions`、`extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、`android`。 + +スコープロジックは`scripts/ci-changed-scope.mjs`にあり、`src/scripts/ci-changed-scope.test.ts`のunit testsでカバーされています。 +別の`install-smoke` workflowは、独自の`preflight`ジョブを通じて同じスコープスクリプトを再利用します。これは、より狭いchanged-smokeシグナルから`run_install_smoke`を計算するため、Docker/install smokeはinstall、packaging、container関連の変更に対してのみ実行されます。 + +pushでは、`checks` matrixにpush専用の`compat-node22`レーンが追加されます。pull requestではこのレーンはスキップされ、matrixは通常のtest/channelレーンに集中したままになります。 + +## Runners + +| Runner | Jobs | +| -------------------------------- | -------------------------------------------------------------------------------------------------- | +| `blacksmith-16vcpu-ubuntu-2404` | `preflight`、`security-fast`、`build-artifacts`、Linux checks、docs checks、Python skills、`android` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `macos-latest` | `macos-node`、`macos-swift` | + +## ローカルでの対応コマンド + +```bash +pnpm check # types + lint + format +pnpm build:strict-smoke +pnpm test:gateway:watch-regression +pnpm test # vitest tests +pnpm test:channels +pnpm check:docs # docs format + lint + broken links +pnpm build # CI artifact/build-smokeレーンが関係する場合にdistをbuild +``` diff --git a/docs/ja-JP/cli/acp.md b/docs/ja-JP/cli/acp.md new file mode 100644 index 000000000..7dd09280b --- /dev/null +++ b/docs/ja-JP/cli/acp.md @@ -0,0 +1,323 @@ +--- +read_when: + - ACP ベースの IDE 統合をセットアップしているとき + - Gateway への ACP セッションルーティングをデバッグしているとき +summary: IDE 統合向けに ACP ブリッジを実行する +title: acp +x-i18n: + generated_at: "2026-04-05T12:38:15Z" + model: gpt-5.4 + provider: openai + source_hash: 2461b181e4a97dd84580581e9436ca1947a224decce8044132dbcf7fb2b7502c + source_path: cli/acp.md + workflow: 15 +--- + +# acp + +OpenClaw Gateway と通信する [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) ブリッジを実行します。 + +このコマンドは IDE 向けに stdio 経由で ACP を話し、プロンプトを WebSocket 経由で Gateway に転送します。 +ACP セッションは Gateway のセッションキーに対応付けられたまま維持されます。 + +`openclaw acp` は Gateway をバックエンドとする ACP ブリッジであり、完全な ACP ネイティブのエディター +ランタイムではありません。主眼は、セッションルーティング、プロンプト配信、基本的なストリーミング +更新にあります。 + +ACP ハーネスセッションをホストする代わりに、外部 MCP クライアントから OpenClaw のチャネル +会話へ直接接続したい場合は、 +[`openclaw mcp serve`](/cli/mcp) を使ってください。 + +## これは何ではないか + +このページは ACP ハーネスセッションと混同されることがよくあります。 + +`openclaw acp` の意味は次のとおりです。 + +- OpenClaw が ACP サーバーとして動作する +- IDE または ACP クライアントが OpenClaw に接続する +- OpenClaw がその作業を Gateway セッションに転送する + +これは [ACP Agents](/tools/acp-agents) とは異なります。そちらでは OpenClaw が +`acpx` を通じて Codex や Claude Code のような外部ハーネスを実行します。 + +簡単なルール: + +- エディター/クライアントが ACP で OpenClaw とやり取りしたい: `openclaw acp` を使う +- OpenClaw が Codex/Claude/Gemini を ACP ハーネスとして起動すべき: `/acp spawn` と [ACP Agents](/tools/acp-agents) を使う + +## 互換性マトリクス + +| ACP 領域 | ステータス | 注記 | +| --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `initialize`, `newSession`, `prompt`, `cancel` | 実装済み | stdio から Gateway の chat/send + abort へのコアブリッジフロー。 | +| `listSessions`, slash commands | 実装済み | セッション一覧は Gateway セッション状態に対して動作します。コマンドは `available_commands_update` を通じて通知されます。 | +| `loadSession` | 一部対応 | ACP セッションを Gateway セッションキーに再バインドし、保存済みの user/assistant テキスト履歴を再生します。tool/system 履歴はまだ再構築されません。 | +| プロンプト内容（`text`、埋め込み `resource`、画像） | 一部対応 | テキスト/リソースは chat 入力にフラット化され、画像は Gateway 添付ファイルになります。 | +| セッションモード | 一部対応 | `session/set_mode` はサポートされています。ブリッジは初期の Gateway バックドなセッション制御として、thought level、tool verbosity、reasoning、usage detail、elevated actions を公開します。より広い ACP ネイティブの mode/config サーフェスはまだ対象外です。 | +| セッション情報と使用量の更新 | 一部対応 | ブリッジは、キャッシュされた Gateway セッションスナップショットから `session_info_update` とベストエフォートの `usage_update` 通知を出します。使用量は概算であり、Gateway のトークン合計が fresh とマークされている場合にのみ送信されます。 | +| ツールストリーミング | 一部対応 | `tool_call` / `tool_call_update` イベントには、Gateway のツール引数/結果がそれらを公開している場合に、生の I/O、テキスト内容、ベストエフォートのファイル位置が含まれます。埋め込み端末や、より豊かな diff ネイティブ出力はまだ公開されません。 | +| セッションごとの MCP サーバー（`mcpServers`） | 未対応 | ブリッジモードではセッションごとの MCP サーバー要求を拒否します。代わりに OpenClaw gateway または agent 側で MCP を設定してください。 | +| クライアントのファイルシステムメソッド（`fs/read_text_file`, `fs/write_text_file`） | 未対応 | ブリッジは ACP クライアントのファイルシステムメソッドを呼び出しません。 | +| クライアントの端末メソッド（`terminal/*`） | 未対応 | ブリッジは ACP クライアント端末を作成せず、tool call を通じて terminal id もストリームしません。 | +| セッション計画 / thought ストリーミング | 未対応 | 現在のブリッジは出力テキストとツール状態を出力しますが、ACP の plan や thought 更新は出力しません。 | + +## 既知の制限 + +- `loadSession` は保存済みの user と assistant のテキスト履歴を再生しますが、 + 過去の tool call、system 通知、より豊かな ACP ネイティブイベント + 種別は再構築しません。 +- 複数の ACP クライアントが同じ Gateway セッションキーを共有する場合、イベントと cancel の + ルーティングはクライアントごとに厳密に分離されるのではなくベストエフォートになります。エディター + ローカルでクリーンなターンが必要な場合は、既定の分離された `acp:` セッションを + 推奨します。 +- Gateway の stop 状態は ACP の stop reason に変換されますが、その対応付けは + 完全な ACP ネイティブランタイムほど表現力がありません。 +- 初期セッション制御で現在公開されているのは、Gateway ノブのうち絞られた一部です: + thought level、tool verbosity、reasoning、usage detail、elevated + actions。model 選択や exec-host 制御はまだ ACP の + config オプションとしては公開されていません。 +- `session_info_update` と `usage_update` は Gateway セッション + スナップショットから導出されるものであり、ライブの ACP ネイティブなランタイム会計ではありません。使用量は概算で、 + コストデータは含まず、Gateway が合計トークン + データを fresh とマークした場合にのみ送信されます。 +- ツール追従データはベストエフォートです。ブリッジは、既知のツール引数/結果に + 現れるファイルパスを公開できますが、ACP の端末や構造化されたファイル diff はまだ出力しません。 + +## 使い方 + +```bash +openclaw acp + +# リモート Gateway +openclaw acp --url wss://gateway-host:18789 --token + +# リモート Gateway（ファイルから token を取得） +openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token + +# 既存のセッションキーに接続 +openclaw acp --session agent:main:main + +# ラベルで接続（すでに存在している必要があります） +openclaw acp --session-label "support inbox" + +# 最初のプロンプトの前にセッションキーをリセット +openclaw acp --session agent:main:main --reset-session +``` + +## ACP クライアント（デバッグ） + +IDE なしでブリッジを簡易確認するには、組み込みの ACP クライアントを使います。 +ACP ブリッジを起動し、対話的にプロンプトを入力できます。 + +```bash +openclaw acp client + +# 起動したブリッジをリモート Gateway に向ける +openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token + +# サーバーコマンドを上書き（既定: openclaw） +openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001 +``` + +権限モデル（クライアントデバッグモード）: + +- 自動承認は許可リストベースで、信頼できるコア tool ID にのみ適用されます。 +- `read` の自動承認は現在の作業ディレクトリ（設定時は `--cwd`）に限定されます。 +- ACP が自動承認するのは、アクティブな cwd 配下の限定的な読み取り専用 `read` 呼び出しと、読み取り専用の検索ツール（`search`, `web_search`, `memory_search`）だけです。未知の/コアでないツール、範囲外の読み取り、実行可能なツール、コントロールプレーンツール、変更を伴うツール、対話フローは常に明示的なプロンプト承認が必要です。 +- サーバー提供の `toolCall.kind` は信頼できないメタデータとして扱われます（認可の根拠にはなりません）。 +- この ACP ブリッジポリシーは ACPX ハーネス権限とは別です。`acpx` バックエンド経由で OpenClaw を実行する場合、`plugins.entries.acpx.config.permissionMode=approve-all` がそのハーネスセッション用の非常用「yolo」スイッチです。 + +## これを使う場面 + +IDE（または他のクライアント）が Agent Client Protocol を話し、 +それに OpenClaw Gateway セッションを操作させたい場合に ACP を使います。 + +1. Gateway が実行中であることを確認します（ローカルまたはリモート）。 +2. Gateway の接続先を設定します（設定またはフラグ）。 +3. IDE が stdio 経由で `openclaw acp` を実行するように設定します。 + +設定例（永続化）: + +```bash +openclaw config set gateway.remote.url wss://gateway-host:18789 +openclaw config set gateway.remote.token +``` + +直接実行の例（設定は書き込まない）: + +```bash +openclaw acp --url wss://gateway-host:18789 --token +# ローカルプロセスの安全性のため推奨 +openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token +``` + +## エージェントの選択 + +ACP はエージェントを直接選びません。Gateway のセッションキーによってルーティングします。 + +特定のエージェントを対象にするには、エージェントスコープのセッションキーを使います。 + +```bash +openclaw acp --session agent:main:main +openclaw acp --session agent:design:main +openclaw acp --session agent:qa:bug-123 +``` + +各 ACP セッションは 1 つの Gateway セッションキーに対応します。1 つのエージェントは複数の +セッションを持てます。ACP は、キーまたはラベルを上書きしない限り、既定で分離された +`acp:` セッションを使います。 + +ブリッジモードではセッションごとの `mcpServers` はサポートされません。ACP クライアントが +`newSession` または `loadSession` 中にそれらを送信した場合、ブリッジは黙って無視するのではなく +明確なエラーを返します。 + +ACPX バックドなセッションから OpenClaw plugin tools を見せたい場合は、 +セッションごとの `mcpServers` を渡そうとするのではなく、gateway 側の ACPX plugin bridge を有効にしてください。 +詳細は [ACP Agents](/tools/acp-agents#plugin-tools-mcp-bridge) を参照してください。 + +## `acpx` から使う（Codex、Claude、その他の ACP クライアント） + +Codex や Claude Code のようなコーディングエージェントを ACP 経由で +OpenClaw ボットと接続したい場合は、組み込みの `openclaw` target を持つ `acpx` を使います。 + +一般的な流れ: + +1. Gateway を実行し、ACP ブリッジがそこへ到達できることを確認します。 +2. `acpx openclaw` が `openclaw acp` を指すようにします。 +3. コーディングエージェントに使わせたい OpenClaw セッションキーを指定します。 + +例: + +```bash +# 既定の OpenClaw ACP セッションへの単発リクエスト +acpx openclaw exec "アクティブな OpenClaw セッション状態を要約して。" + +# 後続ターンのための永続的な名前付きセッション +acpx openclaw sessions ensure --name codex-bridge +acpx openclaw -s codex-bridge --cwd /path/to/repo \ + "このリポジトリに関連する最近のコンテキストを、私の OpenClaw 作業エージェントに尋ねて。" +``` + +`acpx openclaw` が毎回特定の Gateway とセッションキーを対象にするようにしたい場合は、 +`~/.acpx/config.json` で `openclaw` agent command を上書きします。 + +```json +{ + "agents": { + "openclaw": { + "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main" + } + } +} +``` + +リポジトリローカルの OpenClaw チェックアウトでは、ACP ストリームをクリーンに保つため、 +dev runner ではなく直接 CLI エントリポイントを使ってください。たとえば: + +```bash +env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ... +``` + +これは、Codex、Claude Code、または他の ACP 対応クライアントに、 +端末をスクレイピングさせることなく OpenClaw エージェントからコンテキスト情報を +取得させる最も簡単な方法です。 + +## Zed エディターのセットアップ + +`~/.config/zed/settings.json` にカスタム ACP agent を追加します（または Zed の Settings UI を使います）: + +```json +{ + "agent_servers": { + "OpenClaw ACP": { + "type": "custom", + "command": "openclaw", + "args": ["acp"], + "env": {} + } + } +} +``` + +特定の Gateway またはエージェントを対象にするには: + +```json +{ + "agent_servers": { + "OpenClaw ACP": { + "type": "custom", + "command": "openclaw", + "args": [ + "acp", + "--url", + "wss://gateway-host:18789", + "--token", + "", + "--session", + "agent:design:main" + ], + "env": {} + } + } +} +``` + +Zed では、Agent パネルを開いて「OpenClaw ACP」を選択するとスレッドを開始できます。 + +## セッション対応付け + +既定では、ACP セッションには `acp:` 接頭辞付きの分離された Gateway セッションキーが割り当てられます。 +既知のセッションを再利用するには、セッションキーまたはラベルを渡します。 + +- `--session `: 特定の Gateway セッションキーを使います。 +- `--session-label