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

chore(i18n): refresh ja-JP translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-05 13:02:00 +00:00
parent 051ca43b21
commit 6010b2df0a
401 changed files with 88774 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/.i18n/ja-JP.tm.jsonl
View File

@ -1 +0,0 @@

81
docs/ja-JP/.i18n/README.md Normal file
View File

@ -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.<lang>.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 のロケールピッカーブロック。
- `<lang>.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.<lang>.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 <locale>` ワークフローを確認してください。

79
docs/ja-JP/auth-credential-semantics.md Normal file
View File

@ -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.<provider>`または認証ストアの順序オーバーライドが設定されている場合、`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.<id>.mode`が`"oauth"`である場合、そのプロファイルに対するSecretRefベースの`keyRef`/`tokenRef`入力は拒否されます。
- 違反は、起動時またはリロード時の認証解決パスでハードエラーになります。
## レガシー互換メッセージ
スクリプト互換性のため、プローブエラーではこの1行目を変更せずに維持します。
`Auth profile credentials are missing or expired.`
人間にわかりやすい詳細および安定した理由コードは、後続の行に追加できます。

15
docs/ja-JP/automation/auth-monitoring.md Normal file
View File

@ -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)を参照してください。

15
docs/ja-JP/automation/clawflow.md Normal file
View File

@ -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) を参照してください。

385
docs/ja-JP/automation/cron-jobs.md Normal file
View File

@ -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 <job-id>
```
## cronの仕組み
- Cronは**Gatewayプロセス内**で実行されます（モデル内ではありません）。
- ジョブは`~/.openclaw/cron/jobs.json`に永続化されるため、再起動してもスケジュールは失われません。
- すべてのcron実行では[バックグラウンドタスク](/automation/tasks)レコードが作成されます。
- 1回限りのジョブ（`--at`）は、デフォルトで成功後に自動削除されます。
- 分離されたcron実行では、実行完了時にその`cron:<jobId>`セッション用に追跡されているブラウザータブやプロセスをベストエフォートで閉じるため、切り離されたブラウザー自動化によって孤立プロセスが残ることを防ぎます。
- 分離された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:<jobId>` | レポート、バックグラウンド作業 |
| 現在のセッション | `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:<id>`、`user:<id>`）を使用する必要があります。
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 <token>`（推奨）
- `x-openclaw-token: <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/\<name\>）
カスタムフック名は、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 <project-id>
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/<project-id>/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 <jobId> --message "Updated prompt" --model "opus"
# ジョブを今すぐ強制実行
openclaw cron run <jobId>
# 期限到来時のみ実行
openclaw cron run <jobId> --due
# 実行履歴を表示
openclaw cron runs --id <jobId> --limit 50
# ジョブを削除
openclaw cron remove <jobId>
# Agent選択（マルチagentセットアップ）
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent
```
モデルオーバーライドに関する注意:
- `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 <jobId> --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 <jobId> --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) — タイムゾーン設定

15
docs/ja-JP/automation/cron-vs-heartbeat.md Normal file
View File

@ -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)を参照してください。

15
docs/ja-JP/automation/gmail-pubsub.md Normal file
View File

@ -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) を参照してください。

310
docs/ja-JP/automation/hooks.md Normal file
View File

@ -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**: `<workspace>/hooks/`（エージェントごと。明示的に有効化するまでデフォルトでは無効）
Workspace hooksは新しいhook名を追加できますが、同じ名前の同梱、managed、またはplugin提供hookを上書きすることはできません。
### hookパック
hookパックは、`package.json`内の`openclaw.hooks`を通じてhooksを公開するnpmパッケージです。次のようにインストールします。
```bash
openclaw plugins install <path-or-spec>
```
npm specはレジストリ専用です（パッケージ名 + 任意の正確なバージョンまたはdist-tag）。Git/URL/file specおよびsemver rangeは拒否されます。
## 同梱hooks
| Hook | Events | 動作内容 |
| --------------------- | ------------------------------ | ----------------------------------------------------- |
| session-memory | `command:new`, `command:reset` | セッションコンテキストを`<workspace>/memory/`に保存 |
| bootstrap-extra-files | `agent:bootstrap` | globパターンから追加のbootstrapファイルを注入 |
| command-logger | `command` | すべてのコマンドを`~/.openclaw/logs/commands.log`に記録 |
| boot-md | `gateway:startup` | gatewayの起動時に`BOOT.md`を実行 |
任意の同梱hookを有効化するには、次を実行します。
```bash
openclaw hooks enable <hook-name>
```
### session-memoryの詳細
直近15件のユーザー/assistantメッセージを抽出し、LLMで説明的なファイル名スラッグを生成して、`<workspace>/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"]
}
}
}
}
```
<Note>
従来の`hooks.internal.handlers`配列設定形式も後方互換性のため引き続きサポートされていますが、新しいhooksでは検出ベースのシステムを使用してください。
</Note>
## CLIリファレンス
```bash
# すべてのhooksを一覧表示（--eligible、--verbose、または--jsonを追加可能）
openclaw hooks list
# hookの詳細情報を表示
openclaw hooks info <hook-name>
# 適格性の概要を表示
openclaw hooks check
# 有効化/無効化
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>
```
## ベストプラクティス
- **ハンドラーは高速に保つ。** 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)

122
docs/ja-JP/automation/index.md Normal file
View File

@ -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) — すべての設定キー

15
docs/ja-JP/automation/poll.md Normal file
View File

@ -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)を参照してください。

261
docs/ja-JP/automation/standing-orders.md Normal file
View File

@ -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) と組み合わせて動作します。
<Tip>
常設命令は `AGENTS.md` に記載して、毎セッション必ず読み込まれるようにしてください。ワークスペースのブートストラップでは `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md` は自動注入されますが、サブディレクトリ内の任意のファイルは自動注入されません。
</Tip>
## 常設命令の構成要素
```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 など）を含む

89
docs/ja-JP/automation/taskflow.md Normal file
View File

@ -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 <lookup>
# Cancel a running flow and its active tasks
openclaw tasks flow cancel <lookup>
```
| コマンド | 説明 |
| --------------------------------- | --------------------------------------------- |
| `openclaw tasks flow list` | 追跡中のフローをステータスと同期モード付きで表示 |
| `openclaw tasks flow show <id>` | フロー ID または lookup key で 1 つのフローを調査 |
| `openclaw tasks flow cancel <id>` | 実行中のフローとそのアクティブなタスクをキャンセル |
## フローとタスクの関係
フローはタスクを調整するものであり、置き換えるものではありません。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) — フローへの入力元になり得るスケジュール済みジョブ

317
docs/ja-JP/automation/tasks.md Normal file
View File

@ -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 を置き換えるものではありません。これは、どのような切り離された作業が、いつ発生し、成功したかどうかを記録する**アクティビティ台帳**です。
<Note>
すべてのエージェント実行でタスクが作成されるわけではありません。heartbeat ターンと通常の対話チャットでは作成されません。すべての cron 実行、ACP 起動、サブエージェント起動、CLI エージェントコマンドでは作成されます。
</Note>
## 要点
- タスクはスケジューラではなく**記録**です。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 <lookup>
# 実行中のタスクをキャンセル（子セッションを終了）
openclaw tasks cancel <lookup>
# タスクの通知ポリシーを変更
openclaw tasks notify <lookup> state_changes
# ヘルス監査を実行
openclaw tasks audit
# メンテナンスのプレビューまたは適用
openclaw tasks maintenance
openclaw tasks maintenance --apply
# TaskFlow の状態を確認
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
```
## タスクを作成するもの
| ソース | ランタイム種別 | タスクレコードが作成されるタイミング | デフォルトの通知ポリシー |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| 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 で表示されます。
<Tip>
タスク完了は即時の heartbeat wake を引き起こすため、結果をすぐに確認できます。次に予定された heartbeat tick を待つ必要はありません。
</Tip>
つまり、通常のワークフローはプッシュベースです。切り離された作業を一度開始したら、完了時の wake または通知はランタイムに任せます。タスク状態をポーリングするのは、デバッグ、介入、または明示的な監査が必要な場合だけにしてください。
### 通知ポリシー
各タスクについてどの程度通知を受けるかを制御します。
| ポリシー | 配信される内容 |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (default) | 終端状態のみ（succeeded、failed など）— **これがデフォルトです** |
| `state_changes` | すべての状態遷移と進捗更新 |
| `silent` | 何も配信しない |
タスクの実行中にポリシーを変更できます。
```bash
openclaw tasks notify <lookup> state_changes
```
## CLI リファレンス
### `tasks list`
```bash
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
出力列: Task ID、Kind、Status、Delivery、Run ID、Child Session、Summary。
### `tasks show`
```bash
openclaw tasks show <lookup>
```
lookup トークンには task ID、run ID、または session key を指定できます。タイミング、配信状態、エラー、終端サマリーを含む完全なレコードを表示します。
### `tasks cancel`
```bash
openclaw tasks cancel <lookup>
```
ACP タスクとサブエージェントタスクでは、これにより子セッションを終了します。ステータスは `cancelled` に遷移し、配信通知が送信されます。
### `tasks notify`
```bash
openclaw tasks notify <lookup> <done_only|state_changes|silent>
```
### `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 <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
個々のバックグラウンドタスクレコードではなく、オーケストレーションを行う 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 コマンドリファレンス

15
docs/ja-JP/automation/troubleshooting.md Normal file
View File

@ -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)を参照してください。

15
docs/ja-JP/automation/webhook.md Normal file
View File

@ -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) を参照してください。

110
docs/ja-JP/brave-search.md Normal file
View File

@ -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)を参照してください。

442
docs/ja-JP/channels/bluebubbles.md Normal file
View File

@ -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=<password>`）。
5. Gateway を起動します。Webhook ハンドラーが登録され、ペアリングが開始されます。
セキュリティに関する注意:
- 必ず Webhook パスワードを設定してください。
- Webhook 認証は常に必須です。OpenClaw は、BlueBubbles の Webhook リクエストに `channels.bluebubbles.password` と一致する password/guid が含まれていない限り（たとえば `?password=<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
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.poke-messages</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>-lc</string>
<string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StartInterval</key>
<integer>300</integer>
<key>StandardOutPath</key>
<string>/tmp/poke-messages.log</string>
<key>StandardErrorPath</key>
<string>/tmp/poke-messages.err</string>
</dict>
</plist>
```
注意:
- これは **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 <password>
```
## アクセス制御（DM + グループ）
DM:
- デフォルト: `channels.bluebubbles.dmPolicy = "pairing"`。
- 未知の送信者にはペアリングコードが送られ、承認されるまでメッセージは無視されます（コードの有効期限は 1 時間です）。
- 承認方法:
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- ペアリングはデフォルトのトークン交換です。詳細: [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:<id>`
- `chat_guid:<guid>`
- `chat_identifier:<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.<accountId>.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 <code>` を使ってください。
- リアクションには BlueBubbles private API（`POST /api/v1/message/react`）が必要です。サーバーバージョンがこれを提供していることを確認してください。
- 編集 / 送信取り消しには macOS 13+ と互換性のある BlueBubbles サーバーバージョンが必要です。macOS 26 (Tahoe) では、private API の変更により現在編集は壊れています。
- グループアイコンの更新は macOS 26 (Tahoe) で不安定な場合があります。API は成功を返しても、新しいアイコンが同期されないことがあります。
- OpenClaw は BlueBubbles サーバーの macOS バージョンに基づいて、既知の不具合があるアクションを自動的に非表示にします。macOS 26 (Tahoe) で 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) — アクセスモデルとハードニング

449
docs/ja-JP/channels/broadcast-groups.md Normal file
View File

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

138
docs/ja-JP/channels/channel-routing.md Normal file
View File

@ -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.<channel>.defaultAccount` は、送信先パスで `accountId` が指定されていない場合に使用するアカウントを選択します。
- マルチアカウント構成では、2 つ以上のアカウントが設定されている場合、明示的な既定値（`defaultAccount` または `accounts.default`）を設定してください。これがない場合、フォールバックルーティングによって最初に正規化されたアカウント ID が選ばれることがあります。
- **AgentId**: 分離されたワークスペース + セッションストア（「頭脳」）。
- **SessionKey**: コンテキストの保存と同時実行制御に使われるバケットキー。
## SessionKey の形式（例）
ダイレクトメッセージは、エージェントの**メイン**セッションに集約されます。
- `agent:<agentId>:<mainKey>`（既定: `agent:main:main`）
グループとチャネルは、チャネルごとに分離されたままです。
- グループ: `agent:<agentId>:<channel>:group:<id>`
- チャネル/ルーム: `agent:<agentId>:<channel>:channel:<id>`
スレッド:
- Slack/Discord のスレッドでは、ベースキーの末尾に `:thread:<threadId>` が追加されます。
- Telegram のフォーラムトピックでは、グループキーに `:topic:<topicId>` が埋め込まれます。
例:
- `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/<agentId>/sessions/sessions.json`
- JSONL トランスクリプトはストアと同じ場所に保存されます
`session.store` と `{agentId}` テンプレートを使って、ストアパスを上書きできます。
Gateway と ACP のセッション検出では、既定の `agents/` ルート配下、およびテンプレート化された `session.store` ルート配下のディスクベースのエージェントストアもスキャンします。検出されるストアは、解決されたエージェントルート内にとどまり、通常の `sessions.json` ファイルを使っている必要があります。シンボリックリンクやルート外のパスは無視されます。
## WebChat の動作
WebChat は**選択されたエージェント**に接続し、既定ではそのエージェントのメインセッションを使います。
このため、WebChat では、そのエージェントのチャネル横断コンテキストを 1 か所で確認できます。
## 返信コンテキスト
受信した返信には次が含まれます。
- 利用可能な場合は `ReplyToId`、`ReplyToBody`、`ReplyToSender`。
- 引用コンテキストは `[Replying to ...]` ブロックとして `Body` に追加されます。
これはすべてのチャネルで一貫しています。

1259
docs/ja-JP/channels/discord.md Normal file
View File

File diff suppressed because it is too large Load Diff

794
docs/ja-JP/channels/feishu.md Normal file
View File

@ -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.<id>.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 <CODE>
```
承認後は通常どおりチャットできます。
---
## 概要
- **Feishuボットチャンネル**: Gatewayによって管理されるFeishuボット
- **決定論的ルーティング**: 返信は常にFeishuに戻る
- **セッション分離**: DMはメインセッションを共有し、グループは分離される
- **WebSocket接続**: Feishu SDKによる長期接続で、公開URLは不要
---
## アクセス制御
### ダイレクトメッセージ
- **デフォルト**: `dmPolicy: "pairing"`（不明なユーザーにはペアリングコードを返す）
- **ペアリングを承認する**:
```bash
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>
```
- **許可リストモード**: 許可されたOpen IDで`channels.feishu.allowFrom`を設定する
### グループチャット
**1. グループポリシー**（`channels.feishu.groupPolicy`）:
- `"open"` = グループ内の全員を許可
- `"allowlist"` = `groupAllowFrom`のみ許可
- `"disabled"` = グループメッセージを無効化
デフォルト: `allowlist`
**2. メンション要件**（`channels.feishu.requireMention`、`channels.feishu.groups.<chat_id>.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.<chat_id>.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"],
},
},
},
},
}
```
---
<a id="get-groupuser-ids"></a>
## グループ/ユーザー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.<id>.appId` | App ID | - |
| `channels.feishu.accounts.<id>.appSecret` | App Secret | - |
| `channels.feishu.accounts.<id>.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.<chat_id>.requireMention` | グループごとの@mention必須上書き | inherited |
| `channels.feishu.groups.<chat_id>.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) — アクセスモデルとハードニング

277
docs/ja-JP/channels/googlechat.md Normal file
View File

@ -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 &lt;Your Domain&gt;** にチェックを入れます。
- テキストボックスに自分のメールアドレス（例: `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://<node-name>.<tailnet>.ts.net/googlechat`
プライベートダッシュボードは tailnet 専用のままです。
`https://<node-name>.<tailnet>.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 <token>` ヘッダーが含まれます。
- 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:<agentId>:googlechat:direct:<spaceId>` を使います。
- スペースはセッションキー `agent:<agentId>:googlechat:group:<spaceId>` を使います。
4. DM アクセスはデフォルトで pairing です。未知の送信者には pairing code が送られ、次で承認します。
- `openclaw pairing approve googlechat <code>`
5. グループスペースでは、デフォルトで @-mention が必要です。mention 検出にアプリの user 名が必要な場合は `botUser` を使用してください。
## ターゲット
配信と allowlist には、次の識別子を使用します。
- ダイレクトメッセージ: `users/<userId>`（推奨）。
- 生のメールアドレス `name@example.com` は変更可能であり、`channels.googlechat.dangerouslyAllowNameMatching: true` の場合にのみ、ダイレクト allowlist 一致に使われます。
- 非推奨: `users/<email>` はメール allowlist ではなく user id として扱われます。
- スペース: `spaces/<spaceId>`。
## 主な設定
```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.<id>.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) — アクセスモデルとハードニング

91
docs/ja-JP/channels/group-messages.md Normal file
View File

@ -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:<agentId>:whatsapp:group:<jid>` のようになるため、`/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 "<subject>". 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: <groupJid>` を示す `inbound web message` エントリと `[from: …]` サフィックスを確認します。
## 既知の考慮事項
- heartbeat は、ノイズの多いブロードキャストを避けるため、意図的にグループではスキップされます。
- エコー抑制は結合されたバッチ文字列を使います。同一テキストをメンションなしで 2 回送信した場合、返信されるのは最初の 1 回だけです。
- セッションストアのエントリは、セッションストア（既定では `~/.openclaw/agents/<agentId>/sessions/sessions.json`）内で `agent:<agentId>:whatsapp:group:<jid>` として表示されます。エントリがない場合は、そのグループがまだ実行をトリガーしていないことを意味するだけです。
- グループでの入力中インジケーターは `agents.defaults.typingMode` に従います（既定: メンションされていない場合は `message`）。

417
docs/ja-JP/channels/groups.md Normal file
View File

@ -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: { "<group-id>": { ... } }`（`"*"` キーなし） |
| グループ内で起動できるのを自分だけにする | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
## セッションキー
- グループセッションは `agent:<agentId>:<channel>:group:<id>` セッションキーを使います（room/channel は `agent:<agentId>:<channel>:channel:<id>` を使います）。
- Telegram フォーラムトピックでは、各トピックが独自のセッションを持つように、グループ ID に `:topic:<threadId>` が追加されます。
- ダイレクトチャットはメインセッションを使います（設定されていれば送信者ごとのセッション）。
- グループセッションでは heartbeat はスキップされます。
<a id="pattern-personal-dms-public-groups-single-agent"></a>
## パターン: 個人 DM + 公開グループ（単一エージェント）
はい。あなたの「個人」トラフィックが **DM** で、「公開」トラフィックが **グループ** なら、これはうまく機能します。
理由: 単一エージェントモードでは、DM は通常 **main** セッションキー（`agent:main:main`）に入り、グループは常に **非 main** セッションキー（`agent:main:<channel>:group:<id>`）を使います。`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` を使い、`<channel>:<token>` の形式で表示されます。
- `#room` は room/channel 用に予約されています。グループチャットは `g-<slug>` を使います（小文字、スペースは `-` に変換し、`#@+._-` は維持）。
## グループポリシー
チャネルごとに、グループ/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.<id>.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.<provider>` が存在しない場合）、グループポリシーは `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.<channel>.historyLimit`（または `channels.<channel>.accounts.*.historyLimit`）を使います。無効化するには `0` を設定してください。
## グループ/channel ツール制限（任意）
一部のチャネル設定では、**特定のグループ/room/channel 内**で利用可能なツールを制限できます。
- `tools`: グループ全体に対するツールの allow/deny。
- `toolsBySender`: グループ内の送信者ごとの上書き。
明示的なキープレフィックスを使ってください:
`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`、および `"*"` ワイルドカード。
旧来のプレフィックスなしキーも引き続き受け付けられ、`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:<id>` を優先してください。
- チャット一覧: `imsg chats --limit 20`
- グループ返信は常に同じ `chat_id` に戻ります。
## WhatsApp の詳細
WhatsApp 固有の動作（履歴注入、メンション処理の詳細）については、[Group messages](/channels/group-messages)を参照してください。

434
docs/ja-JP/channels/imessage.md Normal file
View File

@ -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）
<Warning>
新しいiMessageデプロイでは、<a href="/channels/bluebubbles">BlueBubbles</a>を使用してください。
`imsg`統合はレガシーであり、将来のリリースで削除される可能性があります。
</Warning>
ステータス: レガシーな外部CLI統合。Gatewayは`imsg rpc`を起動し、stdio上のJSON-RPCで通信します（別個のデーモンやポートはありません）。
<CardGroup cols={3}>
<Card title="BlueBubbles (recommended)" icon="message-circle" href="/channels/bluebubbles">
新しいセットアップ向けの推奨iMessage経路です。
</Card>
<Card title="Pairing" icon="link" href="/channels/pairing">
iMessageのDMはデフォルトでpairingモードです。
</Card>
<Card title="Configuration reference" icon="settings" href="/gateway/configuration-reference#imessage">
iMessageフィールドの完全なリファレンスです。
</Card>
</CardGroup>
## クイックセットアップ
<Tabs>
<Tab title="Local Mac (fast path)">
<Steps>
<Step title="Install and verify imsg">
```bash
brew install steipete/tap/imsg
imsg rpc --help
```
</Step>
<Step title="Configure OpenClaw">
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "/usr/local/bin/imsg",
dbPath: "/Users/<you>/Library/Messages/chat.db",
},
},
}
```
</Step>
<Step title="Start gateway">
```bash
openclaw gateway
```
</Step>
<Step title="Approve first DM pairing (default dmPolicy)">
```bash
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
```
Pairingリクエストは1時間後に期限切れになります。
</Step>
</Steps>
</Tab>
<Tab title="Remote Mac over SSH">
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`）に対して検証されます。
</Tab>
</Tabs>
## 要件と権限（macOS）
- `imsg`を実行するMacでMessagesにサインインしている必要があります。
- OpenClaw/`imsg`を実行するプロセスコンテキストにはフルディスクアクセスが必要です（Messages DBアクセス）。
- Messages.app経由でメッセージを送信するにはAutomation権限が必要です。
<Tip>
権限はプロセスコンテキストごとに付与されます。gatewayがヘッドレスで実行される場合（LaunchAgent/SSH）、同じコンテキストで一度だけ対話型コマンドを実行してプロンプトを表示させてください。
```bash
imsg chats --limit 1
# または
imsg send <handle> "test"
```
</Tip>
## アクセス制御とルーティング
<Tabs>
<Tab title="DM policy">
`channels.imessage.dmPolicy`はダイレクトメッセージを制御します。
- `pairing`（デフォルト）
- `allowlist`
- `open`（`allowFrom`に`"*"`を含める必要があります）
- `disabled`
allowlistフィールド: `channels.imessage.allowFrom`。
allowlistエントリーには、ハンドルまたはチャットターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用できます。
</Tab>
<Tab title="Group policy + mentions">
`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ゲーティングをバイパスできます。
</Tab>
<Tab title="Sessions and deterministic replies">
- DMはダイレクトルーティングを使用し、グループはグループルーティングを使用します。
- デフォルトの`session.dmScope=main`では、iMessageのDMはagentのメインセッションに統合されます。
- グループセッションは分離されます（`agent:<agentId>:imessage:group:<chat_id>`）。
- 返信は、発信元のチャンネル／ターゲットメタデータを使ってiMessageに戻されます。
グループ風スレッドの動作:
一部の複数参加者iMessageスレッドは`is_group=false`で届くことがあります。
その`chat_id`が`channels.imessage.groups`で明示的に設定されている場合、OpenClawはそれをグループトラフィックとして扱います（グループゲーティング + グループセッション分離）。
</Tab>
</Tabs>
## 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:<id>`（安定したグループバインディングに推奨）
- `chat_guid:<guid>`
- `chat_identifier:<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)を参照してください。
## デプロイパターン
<AccordionGroup>
<Accordion title="Dedicated bot macOS user (separate iMessage identity)">
専用のApple IDとmacOSユーザーを使い、botトラフィックを個人のMessagesプロフィールから分離します。
一般的なフロー:
1. 専用のmacOSユーザーを作成してサインインします。
2. そのユーザーでbot用Apple IDを使ってMessagesにサインインします。
3. そのユーザーに`imsg`をインストールします。
4. OpenClawがそのユーザーコンテキストで`imsg`を実行できるようにSSHラッパーを作成します。
5. `channels.imessage.accounts.<id>.cliPath`と`.dbPath`をそのユーザープロファイルに向けます。
初回実行では、そのbotユーザーセッションでGUI承認（Automation + フルディスクアクセス）が必要になる場合があります。
</Accordion>
<Accordion title="Remote Mac over Tailscale (example)">
一般的なトポロジー:
- 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`が設定されます。
</Accordion>
<Accordion title="Multi-account pattern">
iMessageは`channels.imessage.accounts`配下のアカウント単位configをサポートします。
各アカウントは、`cliPath`、`dbPath`、`allowFrom`、`groupPolicy`、`mediaMaxMb`、履歴設定、添付ファイルルートallowlistなどのフィールドを上書きできます。
</Accordion>
</AccordionGroup>
## メディア、チャンク化、配信ターゲット
<AccordionGroup>
<Accordion title="Attachments and media">
- 受信添付ファイルの取り込みは任意です: `channels.imessage.includeAttachments`
- `remoteHost`が設定されている場合、リモート添付ファイルパスはSCP経由で取得できます
- 添付ファイルパスは許可されたルートに一致する必要があります:
- `channels.imessage.attachmentRoots`（ローカル）
- `channels.imessage.remoteAttachmentRoots`（リモートSCPモード）
- デフォルトのルートパターン: `/Users/*/Library/Messages/Attachments`
- SCPは厳格なホストキー検証を使用します（`StrictHostKeyChecking=yes`）
- 送信メディアサイズには`channels.imessage.mediaMaxMb`（デフォルト16 MB）を使用します
</Accordion>
<Accordion title="Outbound chunking">
- テキストチャンク上限: `channels.imessage.textChunkLimit`（デフォルト4000）
- チャンクモード: `channels.imessage.chunkMode`
- `length`（デフォルト）
- `newline`（段落優先分割）
</Accordion>
<Accordion title="Addressing formats">
推奨される明示的ターゲット:
- `chat_id:123`（安定したルーティングに推奨）
- `chat_guid:...`
- `chat_identifier:...`
ハンドルターゲットもサポートされます:
- `imessage:+1555...`
- `sms:+1555...`
- `user@example.com`
```bash
imsg chats --limit 20
```
</Accordion>
</AccordionGroup>
## config書き込み
iMessageでは、デフォルトでチャンネル起点のconfig書き込みが許可されています（`commands.config: true`のときの`/config set|unset`用）。
無効化する場合:
```json5
{
channels: {
imessage: {
configWrites: false,
},
},
}
```
## トラブルシューティング
<AccordionGroup>
<Accordion title="imsg not found or RPC unsupported">
バイナリとRPCサポートを検証します。
```bash
imsg rpc --help
openclaw channels status --probe
```
probeでRPC未対応と表示された場合は、`imsg`を更新してください。
</Accordion>
<Accordion title="DMs are ignored">
次を確認してください。
- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- pairing承認（`openclaw pairing list imessage`）
</Accordion>
<Accordion title="Group messages are ignored">
次を確認してください。
- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups`のallowlist動作
- mentionパターン設定（`agents.list[].groupChat.mentionPatterns`）
</Accordion>
<Accordion title="Remote attachments fail">
次を確認してください。
- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- gatewayホストからのSSH/SCPキー認証
- gatewayホスト上の`~/.ssh/known_hosts`にホストキーが存在すること
- Messagesを実行しているMac上でのリモートパスの可読性
</Accordion>
<Accordion title="macOS permission prompts were missed">
同じユーザー／セッションコンテキストの対話型GUIターミナルで再実行し、プロンプトを承認してください。
```bash
imsg chats --limit 1
imsg send <handle> "test"
```
OpenClaw/`imsg`を実行するプロセスコンテキストに、フルディスクアクセスとAutomationが付与されていることを確認してください。
</Accordion>
</AccordionGroup>
## 設定リファレンスへのポインター
- [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) — アクセスモデルとハードニング

56
docs/ja-JP/channels/index.md Normal file
View File

@ -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) を参照してください。

259
docs/ja-JP/channels/irc.md Normal file
View File

@ -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) — アクセスモデルとハードニング

231
docs/ja-JP/channels/line.md Normal file
View File

@ -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.<id>.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 <CODE>
```
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.<groupId>.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 <agent> --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) — アクセスモデルとハードニング

63
docs/ja-JP/channels/location.md Normal file
View File

@ -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 です。

870
docs/ja-JP/channels/matrix.md Normal file
View File

@ -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-<account>.json` を使います。
対応する環境変数（config キーが設定されていない場合に使用）:
- `MATRIX_HOMESERVER`
- `MATRIX_ACCESS_TOKEN`
- `MATRIX_USER_ID`
- `MATRIX_PASSWORD`
- `MATRIX_DEVICE_ID`
- `MATRIX_DEVICE_NAME`
デフォルト以外のアカウントでは、アカウントスコープ付き環境変数を使います。
- `MATRIX_<ACCOUNT_ID>_HOMESERVER`
- `MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN`
- `MATRIX_<ACCOUNT_ID>_USER_ID`
- `MATRIX_<ACCOUNT_ID>_PASSWORD`
- `MATRIX_<ACCOUNT_ID>_DEVICE_ID`
- `MATRIX_<ACCOUNT_ID>_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.<room>.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 "<your-recovery-key>"
```
デバイス検証の詳細:
```bash
openclaw matrix verify device "<your-recovery-key>" --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 <id>` を渡さない限り、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 <id>` を追加してください。
### 起動時の挙動
`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/<account>/<homeserver>__<user>/<token-hash>/`
配下に整理されます。
そのディレクトリには、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 <id>` を追加してください。
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.<accountId>.ackReaction`
- `channels["matrix"].ackReaction`
- `messages.ackReaction`
- エージェント ID の絵文字フォールバック
ack リアクションスコープは次の順で解決されます。
- `channels["matrix"].accounts.<accountId>.ackReactionScope`
- `channels["matrix"].ackReactionScope`
- `messages.ackReactionScope`
リアクション通知モードは次の順で解決されます。
- `channels["matrix"].accounts.<accountId>.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 <CODE>
```
未承認の 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 <id> allow-once`、`/approve <id> allow-always`、または `/approve <id> deny` で処理します。
承認または拒否できるのは解決済み承認者だけです。チャネル配信ではコマンドテキストも含まれるため、`channel` または `both` は信頼できるルームでのみ有効にしてください。
Matrix 承認プロンプトは共通のコア承認プランナーを再利用します。Matrix 固有のネイティブ画面は exec 承認のトランスポートのみです。つまり、ルーム / DM ルーティングとメッセージ送信 / 更新 / 削除の挙動だけを担当します。
アカウントごとの上書き:
- `channels.matrix.accounts.<account>.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.<room>.account`（またはレガシーの `rooms.<room>.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 <id>` を渡してください。
その暗黙選択を 1 つのコマンドだけで上書きしたい場合は、`openclaw matrix verify ...` と `openclaw matrix devices ...` に `--account <id>` を渡してください。
## プライベート / 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.<id>.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.<id>.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.<room>.account`: マルチアカウント構成で、継承された 1 つのルームエントリーを特定の Matrix アカウントに限定します。
- `groups.<room>.allowBots`: 設定済み bot 送信者に対するルームレベル上書き（`true` または `"mentions"`）。
- `groups.<room>.users`: ルームごとの送信者 allowlist。
- `groups.<room>.tools`: ルームごとのツール許可 / 拒否上書き。
- `groups.<room>.autoReply`: ルームレベルのメンションゲート上書き。`true` はそのルームのメンション要件を無効化し、`false` は再び強制的に有効化します。
- `groups.<room>.skills`: 任意のルームレベル skill フィルター。
- `groups.<room>.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) — アクセスモデルとハードニング

484
docs/ja-JP/channels/mattermost.md Normal file
View File

@ -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.<id>.commands` の下に設定できます（アカウント値が最上位フィールドを上書きします）。
- コマンドコールバックは、OpenClaw が `oc_*` コマンドを登録した際に Mattermost から返される
コマンドごとのトークンで検証されます。
- スラッシュコールバックは、登録に失敗した場合、起動が部分的にしか完了しなかった場合、
またはコールバックトークンが登録済みコマンドのいずれにも一致しない場合にフェイルクローズします。
- 到達可能性の要件: コールバックエンドポイントは Mattermost サーバーから到達可能である必要があります。
- Mattermost が OpenClaw と同じホスト/ネットワーク名前空間で動作していない限り、`callbackUrl` に `localhost` を設定しないでください。
- その URL が `/api/channels/mattermost/command` を OpenClaw にリバースプロキシしていない限り、`callbackUrl` に Mattermost の base URL を設定しないでください。
- 簡単な確認方法は `curl https://<gateway-host>/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 <CODE>`
- 公開 DM: `channels.mattermost.dmPolicy="open"` と `channels.mattermost.allowFrom=["*"]`。
## チャネル（グループ）
- デフォルト: `channels.mattermost.groupPolicy = "allowlist"`（メンションゲートあり）。
- `channels.mattermost.groupAllowFrom` で送信者を許可リストに追加します（ユーザー ID 推奨）。
- チャネルごとのメンション上書きは `channels.mattermost.groups.<channelId>.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:<id>`
- DM には `user:<id>`
- DM には `@username` も使用可能です（Mattermost API 経由で解決されます）
プレフィックスのない不透明 ID（`64ifufp...` のようなもの）は、Mattermost では **曖昧** です（ユーザー ID かチャネル ID か）。
OpenClaw はこれを **ユーザー優先** で解決します。
- その ID がユーザーとして存在する場合（`GET /api/v4/users/<id>` が成功）、OpenClaw は
`/api/v4/channels/direct` でダイレクトチャネルを解決して **DM** を送信します。
- それ以外の場合、その ID は **チャネル ID** として扱われます。
決定的な動作が必要な場合は、必ず明示的なプレフィックス（`user:<id>` / `channel:<id>`）を使用してください。
## DM チャネル再試行
OpenClaw が Mattermost の DM ターゲットに送信し、最初にダイレクトチャネルを解決する必要がある場合、
デフォルトで一時的なダイレクトチャネル作成失敗を再試行します。
この挙動を Mattermost プラグイン全体で調整するには `channels.mattermost.dmChannelRetry` を、
1 つのアカウントだけに適用するには `channels.mattermost.accounts.<id>.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:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true
```
設定:
- `channels.mattermost.actions.reactions`: リアクション操作を有効/無効にします（デフォルトは true）。
- アカウントごとの上書き: `channels.mattermost.accounts.<id>.actions.reactions`。
## インタラクティブボタン（message ツール）
クリック可能なボタン付きメッセージを送信します。ユーザーがボタンをクリックすると、エージェントが
選択内容を受け取り、応答できます。
チャネル機能に `inlineButtons` を追加してボタンを有効化します。
```json5
{
channels: {
mattermost: {
capabilities: ["inlineButtons"],
},
},
}
```
`buttons` パラメータ付きで `message action=send` を使用します。ボタンは 2 次元配列（ボタンの行）です。
```
message action=send channel=mattermost target=channel:<channelId> 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.<id>.interactions.callbackBaseUrl` に設定することもできます。
- `interactions.callbackBaseUrl` を省略した場合、OpenClaw は
`gateway.customBindHost` + `gateway.port` からコールバック URL を導出し、その後 `http://localhost:<port>` にフォールバックします。
- 到達可能性ルール: ボタンコールバック URL は Mattermost サーバーから到達可能である必要があります。
`localhost` が機能するのは、Mattermost と OpenClaw が同じホスト/ネットワーク名前空間で動作している場合だけです。
- コールバック対象がプライベート/Tailnet/内部の場合は、そのホスト/ドメインを Mattermost の
`ServiceSettings.AllowedUntrustedInternalConnections` に追加してください。
### 直接 API 統合（外部スクリプト）
外部スクリプトや webhook は、エージェントの `message` ツールを経由せず、
Mattermost REST API 経由でボタンを直接投稿できます。可能であれば拡張機能の
`buildButtonAttachments()` を使用してください。生の JSON を投稿する場合は、次のルールに従ってください。
**ペイロード構造:**
```json5
{
channel_id: "<channelId>",
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>", // 下記の 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) — アクセスモデルとハードニング

812
docs/ja-JP/channels/msteams.md Normal file
View File

@ -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: "<APP_ID>",
appPassword: "<APP_PASSWORD>",
tenantId: "<TENANT_ID>",
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 = <App ID>` を含めます。
- スコープ: `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: "<APP_ID>",
appPassword: "<APP_PASSWORD>",
tenantId: "<TENANT_ID>",
webhook: { port: 3978, path: "/api/messages" },
},
},
}
```
設定キーの代わりに環境変数も使えます:
- `MSTEAMS_APP_ID`
- `MSTEAMS_APP_PASSWORD`
- `MSTEAMS_TENANT_ID`
5. **ボット endpoint**
- Azure Bot Messaging Endpoint を次のように設定します:
- `https://<host>: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["<user_id>"].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.<teamId>.replyStyle`: team ごとの上書き。
- `channels.msteams.teams.<teamId>.requireMention`: team ごとの上書き。
- `channels.msteams.teams.<teamId>.tools`: team ごとの既定ツールポリシー上書き（`allow`/`deny`/`alsoAllow`）。チャネル上書きがない場合に使われます。
- `channels.msteams.teams.<teamId>.toolsBySender`: team ごとの送信者別ツールポリシー上書き（`"*"` ワイルドカード対応）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: チャネルごとの上書き。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: チャネルごとの上書き。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: チャネルごとのツールポリシー上書き（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.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:<agentId>:<mainKey>`）。
- チャネル/グループメッセージは conversation id を使います:
- `agent:<agentId>:msteams:channel:<conversationId>`
- `agent:<agentId>:msteams:group:<conversationId>`
## 返信スタイル: スレッド 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:<id> ...`
- 投票は 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:<id>",
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:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
| ユーザー（名前指定） | `user:<display-name>` | `user:John Smith`（Graph API が必要） |
| グループ/チャネル | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
| グループ/チャネル（生値） | `<conversation-id>` | `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) — アクセスモデルとハードニング

154
docs/ja-JP/channels/nextcloud-talk.md Normal file
View File

@ -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" "<shared-secret>" "<webhook-url>" --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 <CODE>`
- 公開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) — アクセスモデルとハードニング

257
docs/ja-JP/channels/nostr.md Normal file
View File

@ -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 <path-to-local-nostr-plugin>
```
プラグインをインストールまたは有効化した後は 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) — アクセスモデルとハードニング

129
docs/ja-JP/channels/pairing.md Normal file
View File

@ -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 <CODE>
```
サポートされるチャネル: `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/` の下に保存されます。
- 保留中リクエスト: `<channel>-pairing.json`
- 承認済み allowlist ストア:
- デフォルトアカウント: `<channel>-allowFrom.json`
- 非デフォルトアカウント: `<channel>-<accountId>-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 <requestId>
openclaw devices reject <requestId>
```
同じデバイスが異なる認証詳細（たとえば異なる 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)

199
docs/ja-JP/channels/qqbot.md Normal file
View File

@ -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が設定されており、プロバイダーに到達可能であることを確認してください。

344
docs/ja-JP/channels/signal.md Normal file
View File

@ -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 <CODE>`）。
最小構成:
```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:<id>`値 |
## これは何か
- `signal-cli`経由のSignalチャンネルです（埋め込みlibsignalではありません）。
- 決定的なルーティング: 返信は常にSignalへ戻ります。
- DMはagentのメインセッションを共有し、グループは分離されます（`agent:<agentId>:signal:group:<groupId>`）。
## 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 +<BOT_PHONE_NUMBER> register
```
captchaが必要な場合:
1. `https://signalcaptchas.org/registration/generate.html`を開きます。
2. captchaを完了し、「Open Signal」から`signalcaptcha://...`リンク先をコピーします。
3. 可能であれば、ブラウザーセッションと同じ外部IPから実行してください。
4. すぐに再度登録を実行します（captchaトークンはすぐに期限切れになります）。
```bash
signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
```
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 <PAIRING_CODE>`。
- 「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 <CODE>`
- PairingはSignal DMのデフォルトのトークン交換です。詳細: [Pairing](/channels/pairing)
- UUIDのみの送信者（`sourceUuid`由来）は、`channels.signal.allowFrom`に`uuid:<id>`として保存されます。
グループ:
- `channels.signal.groupPolicy = open | allowlist | disabled`。
- `channels.signal.groupAllowFrom`は、`allowlist`設定時にグループ内で誰がトリガーできるかを制御します。
- `channels.signal.groups["<group-id>" | "*"]`では、`requireMention`、`tools`、`toolsBySender`を使ってグループ動作を上書きできます。
- マルチアカウント構成では、アカウントごとの上書きに`channels.signal.accounts.<id>.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:<id>`を使用します。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:<groupId> targetAuthor=uuid:<sender-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.<id>.actions.reactions`、`channels.signal.accounts.<id>.reactionLevel`。
## 配信ターゲット（CLI/cron）
- DM: `signal:+15551234567`（またはプレーンなE.164）。
- UUID DM: `uuid:<id>`（またはUUID単体）。
- グループ: `signal:group:<groupId>`。
- ユーザー名: `username:<name>`（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:<id>`）。`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.<id>.groups`: マルチアカウント構成向けの`channels.signal.groups`のアカウント別版。
- `channels.signal.historyLimit`: コンテキストに含めるグループメッセージの最大数（0で無効）。
- `channels.signal.dmHistoryLimit`: ユーザーターン単位のDM履歴上限。ユーザー単位の上書き: `channels.signal.dms["<phone_or_uuid>"].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) — アクセスモデルとハードニング

676
docs/ja-JP/channels/slack.md Normal file
View File

@ -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 モードもサポートされています。
<CardGroup cols={3}>
<Card title="ペアリング" icon="link" href="/channels/pairing">
Slack DM はデフォルトでペアリングモードです。
</Card>
<Card title="スラッシュコマンド" icon="terminal" href="/tools/slash-commands">
ネイティブコマンド動作とコマンドカタログ。
</Card>
<Card title="チャネルのトラブルシューティング" icon="wrench" href="/channels/troubleshooting">
チャネル横断の診断と修復プレイブック。
</Card>
</CardGroup>
## クイックセットアップ
<Tabs>
<Tab title="Socket Mode（デフォルト）">
<Steps>
<Step title="Slack アプリとトークンを作成">
Slack アプリ設定で次を行います。
- **Socket Mode** を有効化
- `connections:write` を持つ **App Token**（`xapp-...`）を作成
- アプリをインストールし、**Bot Token**（`xoxb-...`）をコピー
</Step>
<Step title="OpenClaw を設定">
```json5
{
channels: {
slack: {
enabled: true,
mode: "socket",
appToken: "xapp-...",
botToken: "xoxb-...",
},
},
}
```
環境変数フォールバック（デフォルトアカウントのみ）:
```bash
SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...
```
</Step>
<Step title="アプリイベントを購読">
次の 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** を有効にします。
</Step>
<Step title="gateway を起動">
```bash
openclaw gateway
```
</Step>
</Steps>
</Tab>
<Tab title="HTTP Events API モード">
<Steps>
<Step title="HTTP 用に Slack アプリを設定">
- モードを HTTP に設定（`channels.slack.mode="http"`）
- Slack の **Signing Secret** をコピー
- Event Subscriptions、Interactivity、Slash command の Request URL を同じ webhook path（デフォルトは `/slack/events`）に設定
</Step>
<Step title="OpenClaw の HTTP モードを設定">
```json5
{
channels: {
slack: {
enabled: true,
mode: "http",
botToken: "xoxb-...",
signingSecret: "your-signing-secret",
webhookPath: "/slack/events",
},
},
}
```
</Step>
<Step title="複数アカウントの HTTP では一意の webhook path を使う">
アカウントごとの HTTP モードをサポートしています。
登録が衝突しないよう、各アカウントに異なる `webhookPath` を設定してください。
</Step>
</Steps>
</Tab>
</Tabs>
## マニフェストとスコープのチェックリスト
<AccordionGroup>
<Accordion title="Slack アプリマニフェストの例" defaultOpen>
```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"
]
}
}
}
```
</Accordion>
<Accordion title="オプションの user-token スコープ（読み取り操作）">
`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 検索の読み取りに依存する場合）
</Accordion>
</AccordionGroup>
## トークンモデル
- 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` です。
<Tip>
アクションやディレクトリ読み取りでは、設定されていれば user token が優先されることがあります。書き込みでは bot token が引き続き優先されます。user token による書き込みは、`userTokenReadOnly: false` かつ bot token が利用できない場合にのみ許可されます。
</Tip>
## アクションとゲート
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` が含まれます。
## アクセス制御とルーティング
<Tabs>
<Tab title="DM ポリシー">
`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 <code>` を使います。
</Tab>
<Tab title="チャネルポリシー">
`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` が必要です
</Tab>
<Tab title="メンションとチャネルユーザー">
チャネルメッセージはデフォルトで mention ゲートが有効です。
mention ソース:
- 明示的な app mention（`<@botId>`）
- mention 正規表現パターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは `messages.groupChat.mentionPatterns`）
- bot への返信スレッドの暗黙的動作
チャネルごとの制御（`channels.slack.channels.<id>`。名前は起動時解決または `dangerouslyAllowNameMatching` 経由のみ）:
- `requireMention`
- `users`（allowlist）
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- `toolsBySender` のキー形式: `id:`、`e164:`、`username:`、`name:`、または `"*"` ワイルドカード
（旧来のプレフィックスなしキーも引き続き `id:` のみにマップされます）
</Tab>
</Tabs>
## スレッド、セッション、返信タグ
- DM は `direct`、チャネルは `channel`、MPIM は `group` としてルーティングされます。
- デフォルトの `session.dmScope=main` では、Slack DM はエージェントのメインセッションに統合されます。
- チャネルセッション: `agent:<agentId>:slack:channel:<channelId>`。
- スレッド返信では、必要に応じてスレッドセッション接尾辞（`:thread:<threadTs>`）が作成されます。
- `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:<id>]]`
注: `replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含む **すべての** Slack 返信スレッドを無効化します。これは Telegram と異なり、Telegram では `"off"` モードでも明示タグが尊重されます。この違いはプラットフォームのスレッドモデルを反映しています。Slack スレッドはメッセージをチャネルから隠しますが、Telegram の返信はメインチャットフロー内で可視のままです。
## 確認リアクション
`ackReaction` は、OpenClaw が受信メッセージを処理中であることを示す確認絵文字を送信します。
解決順序:
- `channels.slack.accounts.<accountId>.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.<accountId>.typingReaction`
- `channels.slack.typingReaction`
注:
- Slack では shortcode（例: `"hourglass_flowing_sand"`）が必要です。
- このリアクションはベストエフォートで、返信または失敗経路の完了後に自動クリーンアップが試行されます。
## メディア、分割、配信
<AccordionGroup>
<Accordion title="受信添付ファイル">
Slack ファイル添付は、Slack ホストのプライベート URL からダウンロードされ（トークン認証付きリクエストフロー）、取得に成功しサイズ制限内であればメディアストアに書き込まれます。
ランタイムの受信サイズ上限は、`channels.slack.mediaMaxMb` で上書きしない限りデフォルトで `20MB` です。
</Accordion>
<Accordion title="送信テキストとファイル">
- テキスト分割には `channels.slack.textChunkLimit`（デフォルト 4000）を使います
- `channels.slack.chunkMode="newline"` は段落優先の分割を有効化します
- ファイル送信には Slack の upload API を使い、スレッド返信（`thread_ts`）を含められます
- 送信メディア上限は、設定されていれば `channels.slack.mediaMaxMb` に従います。未設定の場合、チャネル送信では media pipeline の MIME 種別デフォルトが使われます
</Accordion>
<Accordion title="配信先">
推奨される明示的なターゲット:
- DM には `user:<id>`
- チャネルには `channel:<id>`
Slack DM は、user ターゲットへ送信する際に Slack 会話 API を通じて開かれます。
</Accordion>
</AccordionGroup>
## コマンドとスラッシュ動作
- Slack のネイティブコマンド自動モードは **オフ** です（`commands.native: "auto"` では Slack ネイティブコマンドは有効になりません）。
- Slack ネイティブコマンドハンドラーを有効にするには `channels.slack.commands.native: true`（またはグローバルの `commands.native: true`）を設定してください。
- ネイティブコマンドが有効な場合は、対応するスラッシュコマンドを Slack に登録してください（`/<command>` 名）。ただし 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:<agentId>:slack:slash:<userId>`
また、コマンド実行は対象会話セッション（`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`
## トラブルシューティング
<AccordionGroup>
<Accordion title="チャネルで返信がない">
次の順で確認してください。
- `groupPolicy`
- チャネル allowlist（`channels.slack.channels`）
- `requireMention`
- チャネルごとの `users` allowlist
便利なコマンド:
```bash
openclaw channels status --probe
openclaw logs --follow
openclaw doctor
```
</Accordion>
<Accordion title="DM メッセージが無視される">
次を確認してください。
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy`（または旧形式の `channels.slack.dm.policy`）
- pairing 承認 / allowlist エントリ
```bash
openclaw pairing list slack
```
</Accordion>
<Accordion title="Socket mode が接続しない">
bot token と app token、および Slack アプリ設定での Socket Mode 有効化を確認してください。
`openclaw channels status --probe --json` で `botTokenStatus` または
`appTokenStatus: "configured_unavailable"` が表示される場合、その Slack アカウントは
設定されていますが、現在のランタイムでは SecretRef ベースの
値を解決できませんでした。
</Accordion>
<Accordion title="HTTP mode でイベントを受信しない">
次を確認してください。
- signing secret
- webhook path
- Slack Request URL（Events + Interactivity + Slash Commands）
- HTTP アカウントごとの一意な `webhookPath`
アカウントスナップショットに `signingSecretStatus: "configured_unavailable"` が
表示される場合、その HTTP アカウントは設定されていますが、現在のランタイムでは
SecretRef ベースの signing secret を解決できませんでした。
</Accordion>
<Accordion title="ネイティブ/スラッシュコマンドが動作しない">
意図したものがどちらかを確認してください。
- ネイティブコマンドモード（`channels.slack.commands.native: true`）で、対応するスラッシュコマンドを Slack に登録している
- または単一スラッシュコマンドモード（`channels.slack.slashCommand.enabled: true`）
あわせて `commands.useAccessGroups` とチャネル/ユーザー allowlist も確認してください。
</Accordion>
</AccordionGroup>
## 関連
- [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)

190
docs/ja-JP/channels/synology-chat.md Normal file
View File

@ -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 <token> --url <incoming-webhook-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 <token> --url <incoming-webhook-url>`
5. Gatewayを再起動し、Synology ChatボットにDMを送信します。
Webhook認証の詳細:
- OpenClawは、まず`body.token`、次に
`?token=...`、最後にヘッダーから送信webhookトークンを受け付けます。
- 受け付けるヘッダー形式:
- `x-synology-token`
- `x-webhook-token`
- `x-openclaw-token`
- `Authorization: Bearer <token>`
- 空または欠落したトークンは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 <CODE>`
## 送信配信
送信先には数値の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) — アクセスモデルとハードニング

1065
docs/ja-JP/channels/telegram.md Normal file
View File

File diff suppressed because it is too large Load Diff

297
docs/ja-JP/channels/tlon.md Normal file
View File

@ -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) — アクセスモデルとハードニング

140
docs/ja-JP/channels/troubleshooting.md Normal file
View File

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

401
docs/ja-JP/channels/twitch.md Normal file
View File

@ -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:<agentId>:twitch:<accountName>` に対応します。
- `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.<accountName>` - マルチ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) — アクセスモデルとハードニング

493
docs/ja-JP/channels/whatsapp.md Normal file
View File

@ -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
```
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/channels/pairing">
未知の送信者に対するデフォルトのDMポリシーはpairingです。
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/channels/troubleshooting">
チャンネル横断の診断と修復プレイブックです。
</Card>
<Card title="Gateway configuration" icon="settings" href="/gateway/configuration">
完全なチャンネル設定パターンと例です。
</Card>
</CardGroup>
## クイックセットアップ
<Steps>
<Step title="Configure WhatsApp access policy">
```json5
{
channels: {
whatsapp: {
dmPolicy: "pairing",
allowFrom: ["+15551234567"],
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}
```
</Step>
<Step title="Link WhatsApp (QR)">
```bash
openclaw channels login --channel whatsapp
```
特定のアカウントの場合:
```bash
openclaw channels login --channel whatsapp --account work
```
</Step>
<Step title="Start the gateway">
```bash
openclaw gateway
```
</Step>
<Step title="Approve first pairing request (if using pairing mode)">
```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
```
Pairingリクエストは1時間後に期限切れになります。保留中のリクエストはチャンネルごとに3件までです。
</Step>
</Steps>
<Note>
OpenClawでは、可能であればWhatsAppを別の番号で運用することを推奨しています。（チャンネルメタデータとセットアップフローはその構成向けに最適化されていますが、個人番号での構成もサポートされています。）
</Note>
## デプロイパターン
<AccordionGroup>
<Accordion title="Dedicated number (recommended)">
これは最も運用しやすいモードです。
- OpenClaw用に分離されたWhatsApp ID
- より明確なDM allowlistとルーティング境界
- 自分とのチャット混乱が起きる可能性が低い
最小ポリシーパターン:
```json5
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
},
},
}
```
</Accordion>
<Accordion title="Personal-number fallback">
オンボーディングは個人番号モードをサポートしており、自分とのチャットに適したベースラインを書き込みます。
- `dmPolicy: "allowlist"`
- `allowFrom`に自分の個人番号を含める
- `selfChatMode: true`
ランタイムでは、自分とのチャット保護はリンク済みの自分の番号と`allowFrom`をもとに動作します。
</Accordion>
<Accordion title="WhatsApp Web-only channel scope">
現在のOpenClawチャンネルアーキテクチャでは、メッセージングプラットフォームチャンネルはWhatsApp Webベース（`Baileys`）です。
組み込みのチャットチャンネルレジストリには、別個のTwilio WhatsAppメッセージングチャンネルはありません。
</Accordion>
</AccordionGroup>
## ランタイムモデル
- GatewayがWhatsAppソケットと再接続ループを管理します。
- 送信には、対象アカウントに対するアクティブなWhatsAppリスナーが必要です。
- ステータスチャットとブロードキャストチャットは無視されます（`@status`、`@broadcast`）。
- ダイレクトチャットではDMセッションルール（`session.dmScope`）が使われます。デフォルトの`main`ではDMはagentのメインセッションに統合されます。
- グループセッションは分離されます（`agent:<agentId>:whatsapp:group:<jid>`）。
## アクセス制御と有効化
<Tabs>
<Tab title="DM policy">
`channels.whatsapp.dmPolicy`はダイレクトチャットアクセスを制御します。
- `pairing`（デフォルト）
- `allowlist`
- `open`（`allowFrom`に`"*"`を含める必要があります）
- `disabled`
`allowFrom`はE.164形式の番号を受け付けます（内部で正規化されます）。
マルチアカウント上書き: `channels.whatsapp.accounts.<id>.dmPolicy`（および`allowFrom`）は、そのアカウントに対してチャンネルレベルのデフォルトより優先されます。
ランタイム動作の詳細:
- pairingsはチャンネルallow-storeに永続化され、設定済みの`allowFrom`とマージされます
- allowlistが設定されていない場合、リンク済みの自分の番号はデフォルトで許可されます
- 送信元が`fromMe`のDMは自動pairingされません
</Tab>
<Tab title="Group policy + allowlists">
グループアクセスには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`が設定されていても同様です。
</Tab>
<Tab title="Mentions + /activation">
グループ返信はデフォルトで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です。
</Tab>
</Tabs>
## 個人番号と自分とのチャット動作
リンク済みの自分の番号が`allowFrom`にも含まれている場合、WhatsAppの自分とのチャット保護が有効になります。
- 自分とのチャットターンでは既読通知をスキップ
- 本来なら自分自身にpingするmention-JID自動トリガー動作を無視
- `messages.responsePrefix`が未設定の場合、自分とのチャット返信のデフォルトは`[{identity.name}]`または`[openclaw]`
## メッセージ正規化とコンテキスト
<AccordionGroup>
<Accordion title="Inbound envelope + reply context">
受信したWhatsAppメッセージは共有の受信エンベロープでラップされます。
引用返信が存在する場合、コンテキストは次の形式で追加されます。
```text
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
```
返信メタデータフィールドも、利用可能な場合は設定されます（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、sender JID/E.164）。
</Accordion>
<Accordion title="Media placeholders and location/contact extraction">
メディアのみの受信メッセージは、次のようなプレースホルダーで正規化されます。
- `<media:image>`
- `<media:video>`
- `<media:audio>`
- `<media:document>`
- `<media:sticker>`
位置情報および連絡先ペイロードは、ルーティング前にテキストコンテキストへ正規化されます。
</Accordion>
<Accordion title="Pending group history injection">
グループでは、未処理メッセージをバッファリングし、botが最終的にトリガーされたときにコンテキストとして注入できます。
- デフォルト上限: `50`
- config: `channels.whatsapp.historyLimit`
- フォールバック: `messages.groupChat.historyLimit`
- `0`で無効化
注入マーカー:
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
</Accordion>
<Accordion title="Read receipts">
既読通知は、受け付けられた受信WhatsAppメッセージに対してデフォルトで有効です。
グローバルに無効化する場合:
```json5
{
channels: {
whatsapp: {
sendReadReceipts: false,
},
},
}
```
アカウントごとの上書き:
```json5
{
channels: {
whatsapp: {
accounts: {
work: {
sendReadReceipts: false,
},
},
},
},
}
```
自分とのチャットターンでは、グローバルに有効でも既読通知はスキップされます。
</Accordion>
</AccordionGroup>
## 配信、チャンク化、メディア
<AccordionGroup>
<Accordion title="Text chunking">
- デフォルトのチャンク上限: `channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- `newline`モードでは段落境界（空行）を優先し、その後で長さ安全なチャンク化にフォールバックします
</Accordion>
<Accordion title="Outbound media behavior">
- 画像、動画、音声（PTTボイスノート）、ドキュメントのペイロードをサポート
- `audio/ogg`は、ボイスノート互換性のため`audio/ogg; codecs=opus`に書き換えられます
- アニメーションGIF再生は、動画送信時の`gifPlayback: true`でサポートされます
- 複数メディア返信ペイロードを送信する際、キャプションは最初のメディア項目に適用されます
- メディアソースにはHTTP(S)、`file://`、ローカルパスを使用できます
</Accordion>
<Accordion title="Media size limits and fallback behavior">
- 受信メディア保存上限: `channels.whatsapp.mediaMaxMb`（デフォルト`50`）
- 送信メディア送信上限: `channels.whatsapp.mediaMaxMb`（デフォルト`50`）
- アカウントごとの上書きには`channels.whatsapp.accounts.<accountId>.mediaMaxMb`を使用します
- 画像は制限内に収めるため自動最適化されます（リサイズ/品質スイープ）
- メディア送信失敗時には、先頭項目フォールバックとしてテキスト警告を送信し、応答が黙って失われることを防ぎます
</Accordion>
</AccordionGroup>
## リアクションレベル
`channels.whatsapp.reactionLevel`は、agentがWhatsAppで絵文字リアクションをどの程度広く使用するかを制御します。
| レベル | Ackリアクション | agent起点リアクション | 説明 |
| ------------- | --------------- | ------------------------- | ------------------------------------------------ |
| `"off"` | いいえ | いいえ | リアクションを一切行いません |
| `"ack"` | はい | いいえ | Ackリアクションのみ（返信前の受領） |
| `"minimal"` | はい | はい（保守的） | Ack + 保守的ガイダンス付きagentリアクション |
| `"extensive"` | はい | はい（推奨） | Ack + 推奨ガイダンス付きagentリアクション |
デフォルト: `"minimal"`。
アカウントごとの上書きには`channels.whatsapp.accounts.<id>.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`はここでは使用しません）
## マルチアカウントと認証情報
<AccordionGroup>
<Accordion title="Account selection and defaults">
- アカウントIDは`channels.whatsapp.accounts`から取得されます
- デフォルトアカウント選択: `default`があればそれ、なければ最初に設定されたアカウントID（ソート順）
- アカウントIDは内部でルックアップ用に正規化されます
</Accordion>
<Accordion title="Credential paths and legacy compatibility">
- 現在の認証パス: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- バックアップファイル: `creds.json.bak`
- `~/.openclaw/credentials/`内のlegacyデフォルト認証も、デフォルトアカウントフローでは引き続き認識/移行されます
</Accordion>
<Accordion title="Logout behavior">
`openclaw channels logout --channel whatsapp [--account <id>]`は、そのアカウントのWhatsApp認証状態を消去します。
legacy認証ディレクトリでは、Baileys認証ファイルは削除されますが`oauth.json`は保持されます。
</Accordion>
</AccordionGroup>
## ツール、アクション、config書き込み
- AgentツールサポートにはWhatsAppリアクションアクション（`react`）が含まれます。
- アクションゲート:
- `channels.whatsapp.actions.reactions`
- `channels.whatsapp.actions.polls`
- チャンネル起点のconfig書き込みはデフォルトで有効です（`channels.whatsapp.configWrites=false`で無効化）。
## トラブルシューティング
<AccordionGroup>
<Accordion title="Not linked (QR required)">
症状: チャンネルステータスが未リンクと表示されます。
修正:
```bash
openclaw channels login --channel whatsapp
openclaw channels status
```
</Accordion>
<Accordion title="Linked but disconnected / reconnect loop">
症状: アカウントはリンク済みだが、切断や再接続試行が繰り返されます。
修正:
```bash
openclaw doctor
openclaw logs --follow
```
必要に応じて、`channels login`で再リンクしてください。
</Accordion>
<Accordion title="No active listener when sending">
対象アカウントに対するアクティブなgatewayリスナーが存在しない場合、送信は即座に失敗します。
Gatewayが動作中で、アカウントがリンク済みであることを確認してください。
</Accordion>
<Accordion title="Group messages unexpectedly ignored">
次の順序で確認してください。
- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
- `groups` allowlistエントリー
- mentionゲーティング（`requireMention` + mention patterns）
- `openclaw.json`（JSON5）内の重複キー: 後ろのエントリーが前のものを上書きするため、スコープごとに`groupPolicy`は1つだけにしてください
</Accordion>
<Accordion title="Bun runtime warning">
WhatsApp gatewayランタイムではNodeを使用してください。Bunは、安定したWhatsApp/Telegram gateway運用と互換性がないとして扱われます。
</Accordion>
</AccordionGroup>
## 設定リファレンスへのポインター
主要リファレンス:
- [Configuration reference - WhatsApp](/gateway/configuration-reference#whatsapp)
重要なWhatsAppフィールド:
- アクセス: `dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`
- 配信: `textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel`
- マルチアカウント: `accounts.<id>.enabled`、`accounts.<id>.authDir`、アカウントレベル上書き
- 運用: `configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*`
- セッション動作: `session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms.<id>.historyLimit`
## 関連
- [Pairing](/channels/pairing)
- [Groups](/channels/groups)
- [Security](/gateway/security)
- [Channel routing](/channels/channel-routing)
- [Multi-agent routing](/concepts/multi-agent)
- [Troubleshooting](/channels/troubleshooting)

261
docs/ja-JP/channels/zalo.md Normal file
View File

@ -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 <CODE>`
- ペアリングがデフォルトのトークン交換です。詳細: [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.<id>.*`を推奨します。両方の形式はスキーマ内に存在するため、ここでも引き続き文書化しています。
プロバイダーオプション:
- `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.<id>.botToken`: アカウントごとのトークン。
- `channels.zalo.accounts.<id>.tokenFile`: アカウントごとの通常のトークンファイル。symlinkは拒否されます。
- `channels.zalo.accounts.<id>.name`: 表示名。
- `channels.zalo.accounts.<id>.enabled`: アカウントを有効化/無効化します。
- `channels.zalo.accounts.<id>.dmPolicy`: アカウントごとのDMポリシー。
- `channels.zalo.accounts.<id>.allowFrom`: アカウントごとの許可リスト。
- `channels.zalo.accounts.<id>.groupPolicy`: アカウントごとのグループポリシー。設定には存在します。現在のMarketplaceボットの挙動については、[機能](#capabilities)および[アクセス制御（グループ）](#access-control-groups)を参照してください。
- `channels.zalo.accounts.<id>.groupAllowFrom`: アカウントごとのグループ送信者許可リスト。
- `channels.zalo.accounts.<id>.webhookUrl`: アカウントごとのwebhook URL。
- `channels.zalo.accounts.<id>.webhookSecret`: アカウントごとのwebhookシークレット。
- `channels.zalo.accounts.<id>.webhookPath`: アカウントごとのwebhookパス。
- `channels.zalo.accounts.<id>.proxy`: アカウントごとのプロキシURL。
## 関連
- [Channels Overview](/channels) — サポートされるすべてのチャンネル
- [Pairing](/channels/pairing) — DM認証とペアリングフロー
- [Groups](/channels/groups) — グループチャットの挙動とメンション制御
- [Channel Routing](/channels/channel-routing) — メッセージのセッションルーティング
- [Security](/gateway/security) — アクセスモデルとハードニング

202
docs/ja-JP/channels/zalouser.md Normal file
View File

@ -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 <code>`
## グループアクセス（省略可）
- デフォルト: `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.<group>.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) — アクセスモデルとハードニング

73
docs/ja-JP/ci.md Normal file
View File

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

323
docs/ja-JP/cli/acp.md Normal file
View File

@ -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:<uuid>` セッションを
推奨します。
- 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 <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 <token>
```
直接実行の例（設定は書き込まない）:
```bash
openclaw acp --url wss://gateway-host:18789 --token <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:<uuid>` セッションを使います。
ブリッジモードではセッションごとの `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",
"<token>",
"--session",
"agent:design:main"
],
"env": {}
}
}
}
```
Zed では、Agent パネルを開いて「OpenClaw ACP」を選択するとスレッドを開始できます。
## セッション対応付け
既定では、ACP セッションには `acp:` 接頭辞付きの分離された Gateway セッションキーが割り当てられます。
既知のセッションを再利用するには、セッションキーまたはラベルを渡します。
- `--session <key>`: 特定の Gateway セッションキーを使います。
- `--session-label <label>`: 既存のセッションをラベルで解決します。
- `--reset-session`: そのキーに対して新しいセッション id を発行します（同じキー、新しい transcript）。
ACP クライアントがメタデータをサポートしている場合は、セッションごとに上書きできます。
```json
{
"_meta": {
"sessionKey": "agent:main:main",
"sessionLabel": "support inbox",
"resetSession": true
}
}
```
セッションキーの詳細は [/concepts/session](/concepts/session) を参照してください。
## オプション
- `--url <url>`: Gateway WebSocket URL（設定されている場合は gateway.remote.url が既定）。
- `--token <token>`: Gateway 認証 token。
- `--token-file <path>`: Gateway 認証 token をファイルから読み取ります。
- `--password <password>`: Gateway 認証 password。
- `--password-file <path>`: Gateway 認証 password をファイルから読み取ります。
- `--session <key>`: 既定のセッションキー。
- `--session-label <label>`: 解決する既定のセッションラベル。
- `--require-existing`: セッションキー/ラベルが存在しない場合は失敗します。
- `--reset-session`: 最初の使用前にセッションキーをリセットします。
- `--no-prefix-cwd`: プロンプトの先頭に作業ディレクトリを付けません。
- `--provenance <off|meta|meta+receipt>`: ACP provenance メタデータまたは receipt を含めます。
- `--verbose, -v`: stderr へ詳細ログを出力します。
セキュリティに関する注意:
- `--token` と `--password` は、一部のシステムではローカルプロセス一覧に見えることがあります。
- `--token-file` / `--password-file` または環境変数（`OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`）を推奨します。
- Gateway 認証の解決は、他の Gateway クライアントと共有される契約に従います:
- local mode: env（`OPENCLAW_GATEWAY_*`）-> `gateway.auth.*` -> `gateway.remote.*` へのフォールバックは `gateway.auth.*` が未設定の場合のみ（設定済みだが未解決の local SecretRef は fail closed）
- remote mode: `gateway.remote.*`。env/config のフォールバックは remote の優先順位ルールに従います
- `--url` は override-safe で、暗黙の config/env 認証情報を再利用しません。明示的な `--token` / `--password`（またはファイル版）を渡してください
- ACP ランタイムバックエンドの子プロセスには `OPENCLAW_SHELL=acp` が渡され、コンテキスト固有の shell/profile ルールに利用できます。
- `openclaw acp client` は、起動したブリッジプロセスに `OPENCLAW_SHELL=acp-client` を設定します。
### `acp client` のオプション
- `--cwd <dir>`: ACP セッションの作業ディレクトリ。
- `--server <command>`: ACP サーバーコマンド（既定: `openclaw`）。
- `--server-args <args...>`: ACP サーバーへ渡す追加引数。
- `--server-verbose`: ACP サーバーで詳細ログを有効にします。
- `--verbose, -v`: 詳細なクライアントログ。

64
docs/ja-JP/cli/agent.md Normal file
View File

@ -0,0 +1,64 @@
---
read_when:
- スクリプトから 1 回のエージェントターンを実行したいとき（必要に応じて返信も配信）
summary: '`openclaw agent` の CLI リファレンス（Gateway 経由で 1 回のエージェントターンを送信）'
title: agent
x-i18n:
generated_at: "2026-04-05T12:37:43Z"
model: gpt-5.4
provider: openai
source_hash: 0627f943bc7f3556318008f76dc6150788cf06927dccdc7d2681acb98f257d56
source_path: cli/agent.md
workflow: 15
---
# `openclaw agent`
Gateway 経由でエージェントターンを実行します（埋め込み実行には `--local` を使用）。
設定済みエージェントを直接対象にするには `--agent <id>` を使用します。
少なくとも 1 つのセッションセレクターを指定してください。
- `--to <dest>`
- `--session-id <id>`
- `--agent <id>`
関連:
- Agent send tool: [Agent send](/tools/agent-send)
## オプション
- `-m, --message <text>`: 必須のメッセージ本文
- `-t, --to <dest>`: セッションキーの導出に使われる受信者
- `--session-id <id>`: 明示的な session id
- `--agent <id>`: agent id。ルーティングバインディングを上書きします
- `--thinking <off|minimal|low|medium|high|xhigh>`: エージェントの thinking レベル
- `--verbose <on|off>`: セッションの verbose レベルを永続化します
- `--channel <channel>`: 配信チャネル。省略時はメインセッションチャネルを使用
- `--reply-to <target>`: 配信先ターゲットの上書き
- `--reply-channel <channel>`: 配信チャネルの上書き
- `--reply-account <id>`: 配信アカウントの上書き
- `--local`: 埋め込みエージェントを直接実行します（plugin registry の事前読み込み後）
- `--deliver`: 選択したチャネル/ターゲットに返信を送り返します
- `--timeout <seconds>`: エージェントタイムアウトを上書きします（デフォルトは 600 または config 値）
- `--json`: JSON を出力します
## 例
```bash
openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
openclaw agent --agent ops --message "Run locally" --local
```
## 注記
- Gateway モードでは、Gateway リクエストが失敗すると埋め込みエージェントにフォールバックします。最初から埋め込み実行を強制するには `--local` を使用してください。
- `--local` でも最初に plugin registry を事前読み込みするため、埋め込み実行中もプラグイン提供の provider、tool、channel を利用できます。
- `--channel`、`--reply-channel`、`--reply-account` はセッションルーティングではなく返信配信に影響します。
- このコマンドが `models.json` の再生成を引き起こした場合、SecretRef 管理の provider 認証情報は、解決済みのシークレット平文ではなく、非シークレットのマーカー（たとえば env var 名、`secretref-env:ENV_VAR_NAME`、または `secretref-managed`）として永続化されます。
- マーカーの書き込みはソース権威です。OpenClaw は、解決済みランタイムシークレット値からではなく、アクティブなソース config スナップショットからマーカーを永続化します。

227
docs/ja-JP/cli/agents.md Normal file
View File

@ -0,0 +1,227 @@
---
read_when:
- 複数の分離されたagent（workspace + routing + auth）が必要な場合
summary: '`openclaw agents`のCLIリファレンス（list/add/delete/bindings/bind/unbind/set identity）'
title: agents
x-i18n:
generated_at: "2026-04-05T12:37:57Z"
model: gpt-5.4
provider: openai
source_hash: 90b90c4915993bd8af322c0590d4cb59baabb8940598ce741315f8f95ef43179
source_path: cli/agents.md
workflow: 15
---
# `openclaw agents`
分離されたagent（workspace + auth + routing）を管理します。
関連:
- マルチagentルーティング: [Multi-Agent Routing](/concepts/multi-agent)
- Agent workspace: [Agent workspace](/concepts/agent-workspace)
- Skills可視性設定: [Skills config](/tools/skills-config)
## 例
```bash
openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work
```
## ルーティングbinding
受信channelトラフィックを特定のagentに固定するには、ルーティングbindingを使用します。
agentごとに表示されるSkillsも変えたい場合は、
`openclaw.json`で`agents.defaults.skills`と`agents.list[].skills`を
設定してください。詳細は[Skills config](/tools/skills-config)および
[Configuration Reference](/gateway/configuration-reference#agentsdefaultsskills)を参照してください。
bindingを一覧表示するには:
```bash
openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json
```
bindingを追加するには:
```bash
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
```
`accountId`（`--bind <channel>`）を省略すると、OpenClawは利用可能な場合、channelデフォルトとpluginセットアップhookからそれを解決します。
`bind`または`unbind`で`--agent`を省略すると、OpenClawは現在のdefault agentを対象にします。
### bindingスコープの挙動
- `accountId`なしのbindingは、そのchannelのdefault accountにのみ一致します。
- `accountId: "*"`はchannel全体のフォールバック（すべてのaccounts）であり、明示的なaccount bindingより具体性が低くなります。
- 同じagentに対して`accountId`なしの一致するchannel bindingがすでに存在し、後から明示的または解決済みの`accountId`でbindingした場合、OpenClawは重複を追加する代わりに既存のbindingをその場でアップグレードします。
例:
```bash
# 初期のchannelのみbinding
openclaw agents bind --agent work --bind telegram
# 後でaccountスコープbindingにアップグレード
openclaw agents bind --agent work --bind telegram:ops
```
アップグレード後、そのbindingのルーティングは`telegram:ops`にスコープされます。default accountのルーティングも必要な場合は、明示的に追加してください（たとえば`--bind telegram:default`）。
bindingを削除するには:
```bash
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all
```
`unbind`は`--all`または1つ以上の`--bind`値のいずれかを受け付けます。両方は指定できません。
## コマンドサーフェス
### `agents`
サブコマンドなしで`openclaw agents`を実行することは、`openclaw agents list`と同等です。
### `agents list`
オプション:
- `--json`
- `--bindings`: agentごとの件数/要約だけでなく、完全なルーティングルールを含める
### `agents add [name]`
オプション:
- `--workspace <dir>`
- `--model <id>`
- `--agent-dir <dir>`
- `--bind <channel[:accountId]>`（繰り返し可）
- `--non-interactive`
- `--json`
注:
- 明示的なaddフラグを1つでも渡すと、コマンドは非対話パスに切り替わります。
- 非対話モードでは、agent名と`--workspace`の両方が必要です。
- `main`は予約済みで、新しいagent idとしては使用できません。
### `agents bindings`
オプション:
- `--agent <id>`
- `--json`
### `agents bind`
オプション:
- `--agent <id>`（デフォルトは現在のdefault agent）
- `--bind <channel[:accountId]>`（繰り返し可）
- `--json`
### `agents unbind`
オプション:
- `--agent <id>`（デフォルトは現在のdefault agent）
- `--bind <channel[:accountId]>`（繰り返し可）
- `--all`
- `--json`
### `agents delete <id>`
オプション:
- `--force`
- `--json`
注:
- `main`は削除できません。
- `--force`がない場合、対話的な確認が必要です。
- Workspace、agent state、およびsession transcriptディレクトリは、完全削除ではなくTrashに移動されます。
## Identityファイル
各agent workspaceには、workspaceルートに`IDENTITY.md`を含めることができます。
- 例のパス: `~/.openclaw/workspace/IDENTITY.md`
- `set-identity --from-identity`はworkspaceルートから読み取ります（または明示的な`--identity-file`）
avatarパスはworkspaceルートからの相対パスとして解決されます。
## identityを設定する
`set-identity`は、`agents.list[].identity`に次のフィールドを書き込みます。
- `name`
- `theme`
- `emoji`
- `avatar`（workspace相対パス、http(s) URL、またはdata URI）
オプション:
- `--agent <id>`
- `--workspace <dir>`
- `--identity-file <path>`
- `--from-identity`
- `--name <name>`
- `--theme <theme>`
- `--emoji <emoji>`
- `--avatar <value>`
- `--json`
注:
- 対象agentの選択には`--agent`または`--workspace`を使用できます。
- `--workspace`に依存していて、複数のagentsがそのworkspaceを共有している場合、コマンドは失敗し、`--agent`を渡すよう求められます。
- 明示的なidentityフィールドが指定されていない場合、コマンドは`IDENTITY.md`からidentityデータを読み取ります。
`IDENTITY.md`から読み込むには:
```bash
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
```
フィールドを明示的に上書きするには:
```bash
openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png
```
Configサンプル:
```json5
{
agents: {
list: [
{
id: "main",
identity: {
name: "OpenClaw",
theme: "space lobster",
emoji: "🦞",
avatar: "avatars/openclaw.png",
},
},
],
},
}
```

143
docs/ja-JP/cli/approvals.md Normal file
View File

@ -0,0 +1,143 @@
---
read_when:
- CLIからexec承認を編集したいとき
- Gatewayまたはnodeホストでallowlistを管理する必要があるとき
summary: '`openclaw approvals`のCLIリファレンス（Gatewayまたはnodeホスト向けのexec承認）'
title: approvals
x-i18n:
generated_at: "2026-04-05T12:38:00Z"
model: gpt-5.4
provider: openai
source_hash: 7b2532bfd3e6e6ce43c96a2807df2dd00cb7b4320b77a7dfd09bee0531da610e
source_path: cli/approvals.md
workflow: 15
---
# `openclaw approvals`
**ローカルホスト**、**Gatewayホスト**、または**nodeホスト**のexec承認を管理します。
デフォルトでは、コマンドはディスク上のローカル承認ファイルを対象にします。Gatewayを対象にするには`--gateway`を、特定のnodeを対象にするには`--node`を使用します。
エイリアス: `openclaw exec-approvals`
関連:
- Exec approvals: [Exec approvals](/tools/exec-approvals)
- Nodes: [Nodes](/nodes)
## 一般的なコマンド
```bash
openclaw approvals get
openclaw approvals get --node <id|name|ip>
openclaw approvals get --gateway
```
`openclaw approvals get`は、ローカル、Gateway、nodeターゲットの有効なexecポリシーを表示するようになりました。
- 要求された`tools.exec`ポリシー
- ホスト承認ファイルのポリシー
- 優先順位ルール適用後の有効結果
優先順位は意図的なものです。
- ホスト承認ファイルは、強制可能な信頼できる唯一の情報源です
- 要求された`tools.exec`ポリシーは意図を狭めたり広げたりできますが、有効結果は依然としてホストルールから導出されます
- `--node`はnodeホストの承認ファイルとGatewayの`tools.exec`ポリシーを組み合わせます。実行時にはその両方が引き続き適用されるためです
- Gateway configが利用できない場合、CLIはnode承認スナップショットにフォールバックし、最終的な実行時ポリシーを計算できなかったことを注記します
## ファイルから承認を置き換える
```bash
openclaw approvals set --file ./exec-approvals.json
openclaw approvals set --stdin <<'EOF'
{ version: 1, defaults: { security: "full", ask: "off" } }
EOF
openclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
openclaw approvals set --gateway --file ./exec-approvals.json
```
`set`は厳密なJSONだけでなくJSON5も受け付けます。`--file`または`--stdin`のどちらかを使ってください。両方は使用できません。
## 「確認を一切出さない」 / YOLOの例
exec承認で停止させたくないホストでは、ホスト承認のデフォルトを`full` + `off`に設定します。
```bash
openclaw approvals set --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
node版:
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
これで変更されるのは**ホスト承認ファイル**のみです。要求されるOpenClawポリシーも揃えるには、次も設定してください。
```bash
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
```
この例で`tools.exec.host=gateway`とする理由:
- `host=auto`は引き続き「sandboxが使える場合はsandbox、それ以外はGateway」を意味します。
- YOLOはルーティングではなく承認に関するものです。
- sandboxが設定されている場合でもホストexecを使いたいなら、`gateway`または`/exec host=gateway`でホスト選択を明示してください。
これは現在のホストデフォルトYOLO動作に一致します。承認を厳しくしたい場合は、より制限してください。
## allowlistヘルパー
```bash
openclaw approvals allowlist add "~/Projects/**/bin/rg"
openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
openclaw approvals allowlist add --agent "*" "/usr/bin/uname"
openclaw approvals allowlist remove "~/Projects/**/bin/rg"
```
## 一般的なオプション
`get`、`set`、`allowlist add|remove`はすべて次をサポートします。
- `--node <id|name|ip>`
- `--gateway`
- 共通のnode RPCオプション: `--url`, `--token`, `--timeout`, `--json`
ターゲット指定に関する注記:
- ターゲットフラグなしの場合は、ディスク上のローカル承認ファイルが対象です
- `--gateway`はGatewayホスト承認ファイルを対象にします
- `--node`は、id、name、IP、またはidプレフィックスを解決した後、そのnodeホストを対象にします
`allowlist add|remove`は次もサポートします。
- `--agent <id>`（デフォルトは`*`）
## 注記
- `--node`は`openclaw nodes`と同じリゾルバーを使用します（id、name、ip、またはidプレフィックス）。
- `--agent`のデフォルトは`"*"`で、すべてのagentに適用されます。
- nodeホストは`system.execApprovals.get/set`を通知する必要があります（macOSアプリまたはヘッドレスnodeホスト）。
- 承認ファイルはホストごとに`~/.openclaw/exec-approvals.json`へ保存されます。

90
docs/ja-JP/cli/backup.md Normal file
View File

@ -0,0 +1,90 @@
---
read_when:
- ローカルの OpenClaw 状態に対する正式なバックアップアーカイブが欲しいとき
- リセットやアンインストールの前に、どのパスが含まれるかを事前確認したいとき
summary: '`openclaw backup` の CLI リファレンス（ローカルバックアップアーカイブの作成）'
title: backup
x-i18n:
generated_at: "2026-04-05T12:38:02Z"
model: gpt-5.4
provider: openai
source_hash: 700eda8f9eac1cc93a854fa579f128e5e97d4e6dfc0da75b437c0fb2a898a37d
source_path: cli/backup.md
workflow: 15
---
# `openclaw backup`
OpenClaw の状態、config、認証プロファイル、チャネル/プロバイダー認証情報、セッション、および必要に応じてワークスペースのためのローカルバックアップアーカイブを作成します。
```bash
openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz
```
## 注記
- アーカイブには、解決済みのソースパスとアーカイブレイアウトを含む `manifest.json` ファイルが含まれます。
- デフォルト出力は、現在の作業ディレクトリに作成されるタイムスタンプ付きの `.tar.gz` アーカイブです。
- 現在の作業ディレクトリがバックアップ対象のソースツリー内にある場合、OpenClaw はデフォルトのアーカイブ保存先としてホームディレクトリにフォールバックします。
- 既存のアーカイブファイルは上書きされません。
- ソースの state/workspace ツリー内にある出力パスは、自己包含を避けるため拒否されます。
- `openclaw backup verify <archive>` は、アーカイブにルート manifest がちょうど 1 つ含まれていることを検証し、トラバーサル形式のアーカイブパスを拒否し、manifest で宣言されたすべてのペイロードが tarball 内に存在することを確認します。
- `openclaw backup create --verify` は、アーカイブ書き込み直後にその検証を実行します。
- `openclaw backup create --only-config` は、アクティブな JSON config ファイルだけをバックアップします。
## バックアップされる内容
`openclaw backup create` は、ローカルの OpenClaw インストールからバックアップ対象のソースを計画します。
- OpenClaw のローカル state resolver が返す状態ディレクトリ（通常は `~/.openclaw`）
- アクティブな config ファイルパス
- 状態ディレクトリの外に存在する場合の、解決済み `credentials/` ディレクトリ
- 現在の config から見つかったワークスペースディレクトリ（`--no-include-workspace` を渡さない限り）
モデル認証プロファイルは、すでに状態ディレクトリ内の
`agents/<agentId>/agent/auth-profiles.json` に含まれているため、通常は
state バックアップ項目でカバーされます。
`--only-config` を使う場合、OpenClaw は状態、認証情報ディレクトリ、ワークスペース検出をスキップし、アクティブな config ファイルパスのみをアーカイブします。
OpenClaw は、アーカイブ構築前にパスを正規化します。config、
認証情報ディレクトリ、またはワークスペースがすでに状態ディレクトリ内にある場合、
それらは別個のトップレベルバックアップソースとして重複しません。存在しないパスは
スキップされます。
アーカイブのペイロードには、それらのソースツリーからのファイル内容が保存され、埋め込まれた `manifest.json` には、解決済みの絶対ソースパスと各アセットに使用されたアーカイブレイアウトが記録されます。
## 無効な config の動作
`openclaw backup` は、復旧時にも役立つように、通常の config 事前チェックを意図的にバイパスします。ただし、ワークスペース検出は有効な config に依存するため、config ファイルが存在していて無効であり、かつワークスペースバックアップが有効のままである場合、`openclaw backup create` は即座に失敗します。
その状況でも部分バックアップを行いたい場合は、次を再実行してください。
```bash
openclaw backup create --no-include-workspace
```
これにより、ワークスペース検出全体をスキップしつつ、state、config、および外部認証情報ディレクトリは対象に含まれます。
config ファイル自体のコピーだけが必要であれば、`--only-config` も config が不正な場合に使えます。これはワークスペース検出のために config の解析に依存しないためです。
## サイズとパフォーマンス
OpenClaw は、組み込みのバックアップ最大サイズやファイルごとのサイズ上限を強制しません。
実際の制限は、ローカルマシンと保存先ファイルシステムによって決まります。
- 一時アーカイブ書き込みと最終アーカイブのための空き容量
- 大きなワークスペースツリーを走査して `.tar.gz` に圧縮する時間
- `openclaw backup create --verify` を使う場合、または `openclaw backup verify` を実行する場合にアーカイブを再走査する時間
- 保存先パスのファイルシステム挙動。OpenClaw は上書きしないハードリンク公開ステップを優先し、ハードリンクがサポートされない場合は排他的コピーにフォールバックします
大きなワークスペースは通常、アーカイブサイズの主な要因です。より小さい、またはより高速なバックアップが必要な場合は、`--no-include-workspace` を使用してください。
最小のアーカイブが必要な場合は、`--only-config` を使用してください。

242
docs/ja-JP/cli/browser.md Normal file
View File

@ -0,0 +1,242 @@
---
read_when:
- '`openclaw browser` を使っていて、一般的なタスクの例がほしい'
- node host 経由で別のマシン上で動作しているブラウザーを制御したい
- Chrome MCP 経由でローカルのサインイン済み Chrome に接続したい
summary: '`openclaw browser` の CLI リファレンス（ライフサイクル、プロファイル、タブ、アクション、状態、デバッグ）'
title: browser
x-i18n:
generated_at: "2026-04-05T12:38:22Z"
model: gpt-5.4
provider: openai
source_hash: c89a7483dd733863dd8ebd47a14fbb411808ad07daaed515c1270978de9157e7
source_path: cli/browser.md
workflow: 15
---
# `openclaw browser`
OpenClaw のブラウザー制御サーフェスを管理し、ブラウザー操作を実行します（ライフサイクル、プロファイル、タブ、スナップショット、スクリーンショット、ナビゲーション、入力、状態エミュレーション、デバッグ）。
関連:
- ブラウザーツール + API: [Browser tool](/tools/browser)
## 共通フラグ
- `--url <gatewayWsUrl>`: Gateway WebSocket URL（デフォルトは設定値）。
- `--token <token>`: Gateway トークン（必要な場合）。
- `--timeout <ms>`: リクエストタイムアウト（ms）。
- `--expect-final`: 最終的な Gateway 応答を待機します。
- `--browser-profile <name>`: ブラウザープロファイルを選択します（デフォルトは設定値）。
- `--json`: 機械可読な出力（サポートされる場合）。
## クイックスタート（ローカル）
```bash
openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
## ライフサイクル
```bash
openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile
```
注意:
- `attachOnly` およびリモート CDP プロファイルでは、`openclaw browser stop` は、
OpenClaw 自身がブラウザープロセスを起動していない場合でも、アクティブな
制御セッションを閉じ、一時的なエミュレーション上書きをクリアします。
- ローカル管理プロファイルでは、`openclaw browser stop` は起動されたブラウザー
プロセスを停止します。
## コマンドが存在しない場合
`openclaw browser` が不明なコマンドである場合は、
`~/.openclaw/openclaw.json` の `plugins.allow` を確認してください。
`plugins.allow` が存在する場合、バンドルされた browser プラグインを明示的に
一覧に含める必要があります。
```json5
{
plugins: {
allow: ["telegram", "browser"],
},
}
```
プラグイン許可リストから `browser` が除外されている場合、`browser.enabled=true` を設定しても
CLI サブコマンドは復元されません。
関連: [Browser tool](/tools/browser#missing-browser-command-or-tool)
## プロファイル
プロファイルは名前付きのブラウザールーティング設定です。実際には次の意味になります。
- `openclaw`: 専用の OpenClaw 管理 Chrome インスタンスを起動または接続します（分離された user data dir）。
- `user`: Chrome DevTools MCP 経由で、既存のサインイン済み Chrome セッションを制御します。
- カスタム CDP プロファイル: ローカルまたはリモートの CDP エンドポイントを指します。
```bash
openclaw browser profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
```
特定のプロファイルを使うには:
```bash
openclaw browser --browser-profile work tabs
```
## タブ
```bash
openclaw browser tabs
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai
openclaw browser focus <targetId>
openclaw browser close <targetId>
```
## スナップショット / スクリーンショット / アクション
スナップショット:
```bash
openclaw browser snapshot
```
スクリーンショット:
```bash
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
```
注意:
- `--full-page` はページ全体のキャプチャ専用で、`--ref`
や `--element` とは併用できません。
- `existing-session` / `user` プロファイルは、ページスクリーンショットと、
スナップショット出力からの `--ref` スクリーンショットをサポートしますが、
CSS `--element` スクリーンショットはサポートしません。
ナビゲーション/クリック/入力（ref ベースの UI 自動化）:
```bash
openclaw browser navigate https://example.com
openclaw browser click <ref>
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'
openclaw browser wait --text "Done"
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
```
ファイル + ダイアログ補助:
```bash
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
```
## 状態とストレージ
ビューポート + エミュレーション:
```bash
openclaw browser resize 1280 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
```
Cookies + ストレージ:
```bash
openclaw browser cookies
openclaw browser cookies set session abc123 --url https://example.com
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set token abc123
openclaw browser storage session clear
```
## デバッグ
```bash
openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip
```
## MCP 経由の既存 Chrome
組み込みの `user` プロファイルを使うか、自分で `existing-session` プロファイルを作成します。
```bash
openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
openclaw browser --browser-profile chrome-live tabs
```
この経路はホスト専用です。Docker、ヘッドレスサーバー、Browserless、またはその他のリモート構成では、代わりに CDP プロファイルを使用してください。
現在の existing-session の制限:
- スナップショット駆動の操作は CSS セレクターではなく ref を使用します
- `click` は左クリックのみです
- `type` は `slowly=true` をサポートしません
- `press` は `delayMs` をサポートしません
- `hover`、`scrollintoview`、`drag`、`select`、`fill`、`evaluate` は
呼び出しごとのタイムアウト上書きを拒否します
- `select` は 1 つの値のみサポートします
- `wait --load networkidle` はサポートされません
- ファイルアップロードには `--ref` / `--input-ref` が必要で、CSS
`--element` はサポートせず、現在は一度に 1 ファイルのみサポートします
- ダイアログフックは `--timeout` をサポートしません
- スクリーンショットはページキャプチャと `--ref` をサポートしますが、CSS `--element`
はサポートしません
- `responsebody`、ダウンロードインターセプト、PDF エクスポート、バッチ操作は依然として
管理ブラウザーまたは生の CDP プロファイルが必要です
## リモートブラウザー制御（node host プロキシ）
Gateway がブラウザーとは別のマシンで動作している場合は、Chrome/Brave/Edge/Chromium があるマシン上で **node host** を実行してください。Gateway はブラウザー操作をそのノードにプロキシします（別個のブラウザー制御サーバーは不要です）。
自動ルーティングを制御するには `gateway.nodes.browser.mode` を使用し、複数ノードが接続されている場合に特定ノードへ固定するには `gateway.nodes.browser.node` を使用します。
セキュリティ + リモートセットアップ: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)

138
docs/ja-JP/cli/channels.md Normal file
View File

@ -0,0 +1,138 @@
---
read_when:
- channel accounts（WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix）を追加/削除したい場合
- channel statusを確認したい、またはchannel logsをtailしたい場合
summary: '`openclaw channels`のCLIリファレンス（accounts、status、login/logout、logs）'
title: channels
x-i18n:
generated_at: "2026-04-05T12:38:19Z"
model: gpt-5.4
provider: openai
source_hash: d0f558fdb5f6ec54e7fdb7a88e5c24c9d2567174341bd3ea87848bce4cba5d29
source_path: cli/channels.md
workflow: 15
---
# `openclaw channels`
Gateway上のchat channel accountsとそのruntime statusを管理します。
関連ドキュメント:
- Channelガイド: [Channels](/channels/index)
- Gateway設定: [Configuration](/gateway/configuration)
## よく使うコマンド
```bash
openclaw channels list
openclaw channels status
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all
```
## Status / capabilities / resolve / logs
- `channels status`: `--probe`, `--timeout <ms>`, `--json`
- `channels capabilities`: `--channel <name>`, `--account <id>`（`--channel`指定時のみ）, `--target <dest>`, `--timeout <ms>`, `--json`
- `channels resolve`: `<entries...>`, `--channel <name>`, `--account <id>`, `--kind <auto|user|group>`, `--json`
- `channels logs`: `--channel <name|all>`, `--lines <n>`, `--json`
`channels status --probe`はライブパスです。到達可能なgatewayに対しては、accountごとの
`probeAccount`と任意の`auditAccount`チェックを実行するため、出力にはtransport
stateに加えて、`works`、`probe failed`、`audit ok`、`audit failed`のようなprobe結果を含めることができます。
gatewayに到達できない場合、`channels status`はライブprobe出力の代わりに
configのみの要約へフォールバックします。
## accountsの追加 / 削除
```bash
openclaw channels add --channel telegram --token <bot-token>
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels remove --channel telegram --delete
```
ヒント: `openclaw channels add --help`はchannelごとのフラグ（token、private key、app token、signal-cliパスなど）を表示します。
よく使われる非対話型のaddサーフェスには次が含まれます。
- bot-token channels: `--token`, `--bot-token`, `--app-token`, `--token-file`
- Signal/iMessage transportフィールド: `--signal-number`, `--cli-path`, `--http-url`, `--http-host`, `--http-port`, `--db-path`, `--service`, `--region`
- Google Chatフィールド: `--webhook-path`, `--webhook-url`, `--audience-type`, `--audience`
- Matrixフィールド: `--homeserver`, `--user-id`, `--access-token`, `--password`, `--device-name`, `--initial-sync-limit`
- Nostrフィールド: `--private-key`, `--relay-urls`
- Tlonフィールド: `--ship`, `--url`, `--code`, `--group-channels`, `--dm-allowlist`, `--auto-discover-channels`
- サポートされている場合は、default accountのenvバック認証に`--use-env`
フラグなしで`openclaw channels add`を実行すると、対話型ウィザードで次を尋ねられる場合があります。
- 選択したchannelごとのaccount id
- それらのaccountsの任意の表示名
- `Bind configured channel accounts to agents now?`
ここで「今すぐbindする」を確認すると、ウィザードは、設定済みの各channel accountをどのagentに所有させるかを尋ね、accountスコープのルーティングbindingを書き込みます。
同じルーティングルールは、後で`openclaw agents bindings`、`openclaw agents bind`、`openclaw agents unbind`でも管理できます（[agents](/cli/agents)を参照）。
single-accountのトップレベル設定をまだ使っているchannelに対してnon-default accountを追加すると、OpenClawは新しいaccountを書き込む前に、そのaccountスコープのトップレベル値をchannelのaccount mapへ昇格させます。ほとんどのchannelsでは、それらの値は`channels.<channel>.accounts.default`に配置されますが、同梱channelsでは既存の一致する昇格accountを保持する場合があります。現在の例はMatrixです。名前付きaccountがすでに1つ存在する場合、または`defaultAccount`が既存の名前付きaccountを指している場合、昇格では新しい`accounts.default`を作成せず、そのaccountを保持します。
ルーティングの挙動は一貫したままです。
- 既存のchannelのみのbinding（`accountId`なし）は、引き続きdefault accountに一致します。
- `channels add`は、非対話モードではbindingを自動作成も書き換えもしません。
- 対話型セットアップでは、任意でaccountスコープbindingを追加できます。
configがすでに混在状態（名前付きaccountsが存在し、なおかつトップレベルのsingle-account値も設定済み）になっている場合は、`openclaw doctor --fix`を実行して、そのchannel用に選ばれた昇格accountへaccountスコープ値を移動してください。ほとんどのchannelsは`accounts.default`へ昇格しますが、Matrixは既存の名前付き/default targetを保持できます。
## Login / logout（対話型）
```bash
openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp
```
注:
- `channels login`は`--verbose`をサポートしています。
- `channels login` / `logout`は、サポートされるlogin targetが1つだけ設定されている場合、channelを推測できます。
## トラブルシューティング
- 広範なprobeには`openclaw status --deep`を実行してください。
- ガイド付き修正には`openclaw doctor`を使ってください。
- `openclaw channels list`が`Claude: HTTP 403 ... user:profile`を表示する場合、usage snapshotには`user:profile`スコープが必要です。`--no-usage`を使うか、claude.aiのsession key（`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`）を指定するか、Claude CLIで再認証してください。
- `openclaw channels status`は、gatewayに到達できない場合、configのみの要約にフォールバックします。サポートされているchannel credentialがSecretRef経由で設定されていても、現在のコマンドパスでそのcredentialを利用できない場合、そのaccountは未設定としてではなく、degraded notes付きの設定済みとして報告されます。
## Capabilities probe
provider capabilityヒント（利用可能な場合はintents/scopes）と静的な機能サポートを取得します。
```bash
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
```
注:
- `--channel`は任意です。省略すると、すべてのchannel（extensionsを含む）を一覧表示します。
- `--account`は`--channel`と一緒の場合のみ有効です。
- `--target`は`channel:<id>`または生の数値channel idを受け付け、Discordにのみ適用されます。
- probesはprovider固有です。Discord intents + 任意のchannel権限、Slack bot + user scopes、Telegram botフラグ + webhook、Signal daemon version、Microsoft Teams app token + Graph roles/scopes（既知の場合は注記付き）を扱います。probeのないchannelsは`Probe: unavailable`を報告します。
## 名前をIDに解決する
provider directoryを使ってchannel/user名をIDに解決します。
```bash
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels resolve --channel discord "My Server/#support" "@someone"
openclaw channels resolve --channel matrix "Project Room"
```
注:
- target typeを強制するには`--kind user|group|auto`を使用します。
- 同名のエントリが複数ある場合、解決はアクティブな一致を優先します。
- `channels resolve`は読み取り専用です。選択したaccountがSecretRef経由で設定されていても、そのcredentialが現在のコマンドパスで利用できない場合、コマンド全体を中断する代わりに、notes付きのdegraded unresolved結果を返します。

28
docs/ja-JP/cli/clawbot.md Normal file
View File

@ -0,0 +1,28 @@
---
read_when:
- '`openclaw clawbot ...`を使う古いスクリプトを保守しているとき'
- 現在のコマンドへの移行ガイダンスが必要なとき
summary: '`openclaw clawbot`のCLIリファレンス（レガシーなエイリアス名前空間）'
title: clawbot
x-i18n:
generated_at: "2026-04-05T12:38:04Z"
model: gpt-5.4
provider: openai
source_hash: 1db82065ecb0107d1ab1a2c6ddaee9df1dd02b983ca1f759974c9d73f0ee3bde
source_path: cli/clawbot.md
workflow: 15
---
# `openclaw clawbot`
後方互換性のために維持されているレガシーなエイリアス名前空間です。
現在サポートされているエイリアス:
- `openclaw clawbot qr`（[`openclaw qr`](/cli/qr)と同じ動作）
## 移行
最新のトップレベルコマンドを直接使用してください。
- `openclaw clawbot qr` -> `openclaw qr`

42
docs/ja-JP/cli/completion.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- zsh/bash/fish/PowerShell 用のシェル補完が必要なとき
- OpenClaw の状態ディレクトリ配下に補完スクリプトをキャッシュする必要があるとき
summary: '`openclaw completion` の CLI リファレンス（シェル補完スクリプトの生成 / インストール）'
title: completion
x-i18n:
generated_at: "2026-04-05T12:38:09Z"
model: gpt-5.4
provider: openai
source_hash: 7bbf140a880bafdb7140149f85465d66d0d46e5a3da6a1e41fb78be2fd2bd4d0
source_path: cli/completion.md
workflow: 15
---
# `openclaw completion`
シェル補完スクリプトを生成し、必要に応じてシェルプロファイルにインストールします。
## 使用方法
```bash
openclaw completion
openclaw completion --shell zsh
openclaw completion --install
openclaw completion --shell fish --install
openclaw completion --write-state
openclaw completion --shell bash --write-state
```
## オプション
- `-s, --shell <shell>`: 対象シェル（`zsh`, `bash`, `powershell`, `fish`; デフォルト: `zsh`）
- `-i, --install`: source 行をシェルプロファイルに追加して補完をインストール
- `--write-state`: 補完スクリプトを stdout に出力せずに `$OPENCLAW_STATE_DIR/completions` へ書き込む
- `-y, --yes`: インストール確認プロンプトをスキップ
## 注意
- `--install` は、シェルプロファイルに小さな「OpenClaw Completion」ブロックを書き込み、キャッシュされたスクリプトを参照するようにします。
- `--install` も `--write-state` も指定しない場合、このコマンドはスクリプトを stdout に出力します。
- 補完生成ではコマンドツリーを事前に読み込むため、ネストされたサブコマンドも含まれます。

359
docs/ja-JP/cli/config.md Normal file
View File

@ -0,0 +1,359 @@
---
read_when:
- 非対話的に config を読み取ったり編集したりしたいとき
summary: '`openclaw config` の CLI リファレンス（get/set/unset/file/schema/validate）'
title: config
x-i18n:
generated_at: "2026-04-05T12:38:40Z"
model: gpt-5.4
provider: openai
source_hash: e4de30f41e15297019151ad1a5b306cb331fd5c2beefd5ce5b98fcc51e95f0de
source_path: cli/config.md
workflow: 15
---
# `openclaw config`
`openclaw.json` を非対話的に編集するための config ヘルパーです。パスを指定して
値の get/set/unset/file/schema/validate を行い、アクティブな config ファイルを表示します。サブコマンドなしで実行すると、
configure ウィザードを開きます（`openclaw configure` と同じ）。
ルートオプション:
- `--section <section>`: サブコマンドなしで `openclaw config` を実行するときに使う、繰り返し指定可能なガイド付きセットアップのセクションフィルター
サポートされるガイド付きセクション:
- `workspace`
- `model`
- `web`
- `gateway`
- `daemon`
- `channels`
- `plugins`
- `skills`
- `health`
## 例
```bash
openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json
```
### `config schema`
生成された `openclaw.json` 用 JSON schema を JSON として stdout に出力します。
含まれる内容:
- 現在のルート config schema と、エディター支援用のルート `$schema` 文字列フィールド
- Control UI で使われるフィールド `title` と `description` のドキュメントメタデータ
- 対応するフィールドドキュメントが存在する場合、ネストされたオブジェクト、ワイルドカード（`*`）、配列要素（`[]`）ノードも同じ `title` / `description` メタデータを継承
- 対応するフィールドドキュメントが存在する場合、`anyOf` / `oneOf` / `allOf` 分岐も同じドキュメントメタデータを継承
- ランタイム manifest を読み込める場合、ベストエフォートの live plugin + channel schema メタデータ
- 現在の config が無効でも利用できるクリーンなフォールバック schema
関連ランタイム RPC:
- `config.schema.lookup` は、正規化済み config パス 1 件について、浅い
schema ノード（`title`、`description`、`type`、`enum`、`const`、一般的な境界）、
一致した UI ヒントメタデータ、および直下の子要約を返します。Control UI やカスタムクライアントで
パス単位のドリルダウンに使用してください。
```bash
openclaw config schema
```
他のツールで調べたり検証したりしたい場合は、ファイルにパイプしてください。
```bash
openclaw config schema > openclaw.schema.json
```
### パス
パスにはドット記法またはブラケット記法を使います。
```bash
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id
```
特定の agent を対象にするには、agent list のインデックスを使います。
```bash
openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
```
## 値
値は、可能であれば JSON5 として解析され、そうでなければ文字列として扱われます。
JSON5 解析を必須にするには `--strict-json` を使用してください。旧来のエイリアスとして `--json` も引き続きサポートされています。
```bash
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
```
`config get <path> --json` は、ターミナル整形済みテキストではなく生の値を JSON として出力します。
## `config set` のモード
`openclaw config set` は 4 つの代入スタイルをサポートしています。
1. 値モード: `openclaw config set <path> <value>`
2. SecretRef builder モード:
```bash
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN
```
3. Provider builder モード（`secrets.providers.<alias>` パスのみ）:
```bash
openclaw config set secrets.providers.vault \
--provider-source exec \
--provider-command /usr/local/bin/openclaw-vault \
--provider-arg read \
--provider-arg openai/api-key \
--provider-timeout-ms 5000
```
4. バッチモード（`--batch-json` または `--batch-file`）:
```bash
openclaw config set --batch-json '[
{
"path": "secrets.providers.default",
"provider": { "source": "env" }
},
{
"path": "channels.discord.token",
"ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
}
]'
```
```bash
openclaw config set --batch-file ./config-set.batch.json --dry-run
```
ポリシーに関する注記:
- サポートされていないランタイム可変サーフェス（たとえば `hooks.token`、`commands.ownerDisplaySecret`、Discord の thread-binding webhook token、WhatsApp の creds JSON）では、SecretRef の代入は拒否されます。詳細は [SecretRef Credential Surface](/reference/secretref-credential-surface) を参照してください。
バッチ解析では常にバッチペイロード（`--batch-json`/`--batch-file`）を信頼できる情報源として使います。
`--strict-json` / `--json` はバッチ解析の動作を変更しません。
JSON パス/値モードは、SecretRef と provider の両方で引き続きサポートされます。
```bash
openclaw config set channels.discord.token \
'{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
--strict-json
openclaw config set secrets.providers.vaultfile \
'{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
--strict-json
```
## Provider Builder Flags
Provider builder の対象は、パスに `secrets.providers.<alias>` を使う必要があります。
共通フラグ:
- `--provider-source <env|file|exec>`
- `--provider-timeout-ms <ms>`（`file`, `exec`）
Env provider（`--provider-source env`）:
- `--provider-allowlist <ENV_VAR>`（繰り返し指定可能）
File provider（`--provider-source file`）:
- `--provider-path <path>`（必須）
- `--provider-mode <singleValue|json>`
- `--provider-max-bytes <bytes>`
Exec provider（`--provider-source exec`）:
- `--provider-command <path>`（必須）
- `--provider-arg <arg>`（繰り返し指定可能）
- `--provider-no-output-timeout-ms <ms>`
- `--provider-max-output-bytes <bytes>`
- `--provider-json-only`
- `--provider-env <KEY=VALUE>`（繰り返し指定可能）
- `--provider-pass-env <ENV_VAR>`（繰り返し指定可能）
- `--provider-trusted-dir <path>`（繰り返し指定可能）
- `--provider-allow-insecure-path`
- `--provider-allow-symlink-command`
ハードニングされた exec provider の例:
```bash
openclaw config set secrets.providers.vault \
--provider-source exec \
--provider-command /usr/local/bin/openclaw-vault \
--provider-arg read \
--provider-arg openai/api-key \
--provider-json-only \
--provider-pass-env VAULT_TOKEN \
--provider-trusted-dir /usr/local/bin \
--provider-timeout-ms 5000
```
## ドライラン
`openclaw.json` に書き込まずに変更を検証するには `--dry-run` を使用します。
```bash
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 \
--dry-run \
--json
openclaw config set channels.discord.token \
--ref-provider vault \
--ref-source exec \
--ref-id discord/token \
--dry-run \
--allow-exec
```
ドライランの動作:
- Builder モード: 変更された ref/provider に対して SecretRef の解決可能性チェックを実行します。
- JSON モード（`--strict-json`、`--json`、またはバッチモード）: schema 検証と SecretRef の解決可能性チェックを実行します。
- 既知の非対応 SecretRef 対象サーフェスに対するポリシー検証も実行されます。
- ポリシーチェックは変更後の完全な config を評価するため、親オブジェクト書き込み（たとえば `hooks` をオブジェクトとして設定すること）では非対応サーフェス検証を回避できません。
- exec SecretRef チェックは、コマンドの副作用を避けるため、ドライラン時にはデフォルトでスキップされます。
- exec SecretRef チェックを有効にするには、`--dry-run` と一緒に `--allow-exec` を使用してください（これにより provider コマンドが実行される場合があります）。
- `--allow-exec` はドライラン専用であり、`--dry-run` なしで使うとエラーになります。
`--dry-run --json` は機械可読なレポートを出力します。
- `ok`: ドライランが成功したかどうか
- `operations`: 評価した代入数
- `checks`: schema/解決可能性チェックが実行されたかどうか
- `checks.resolvabilityComplete`: 解決可能性チェックが最後まで実行されたかどうか（exec ref がスキップされた場合は false）
- `refsChecked`: ドライラン中に実際に解決された ref 数
- `skippedExecRefs`: `--allow-exec` が設定されていないためスキップされた exec ref 数
- `errors`: `ok=false` の場合の構造化された schema/解決可能性エラー
### JSON 出力形式
```json5
{
ok: boolean,
operations: number,
configPath: string,
inputModes: ["value" | "json" | "builder", ...],
checks: {
schema: boolean,
resolvability: boolean,
resolvabilityComplete: boolean,
},
refsChecked: number,
skippedExecRefs: number,
errors?: [
{
kind: "schema" | "resolvability",
message: string,
ref?: string, // resolvability エラーのときに存在
},
],
}
```
成功例:
```json
{
"ok": true,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0
}
```
失敗例:
```json
{
"ok": false,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0,
"errors": [
{
"kind": "resolvability",
"message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
"ref": "env:default:MISSING_TEST_SECRET"
}
]
}
```
ドライランが失敗した場合:
- `config schema validation failed`: 変更後の config 形状が無効です。パス/値、または provider/ref オブジェクト形状を修正してください。
- `Config policy validation failed: unsupported SecretRef usage`: その認証情報を平文/文字列入力に戻し、SecretRef はサポートされるサーフェスでのみ使ってください。
- `SecretRef assignment(s) could not be resolved`: 参照先の provider/ref が現在解決できません（環境変数不足、無効なファイル参照、exec provider の失敗、または provider/source の不一致）。
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: ドライランで exec ref がスキップされました。exec の解決可能性検証が必要なら `--allow-exec` を付けて再実行してください。
- バッチモードでは、失敗したエントリを修正し、書き込む前に `--dry-run` を再実行してください。
## サブコマンド
- `config file`: アクティブな config ファイルパスを表示します（`OPENCLAW_CONFIG_PATH` またはデフォルト位置から解決）。
編集後は gateway を再起動してください。
## Validate
gateway を起動せずに、現在の config をアクティブな schema に対して検証します。
```bash
openclaw config validate
openclaw config validate --json
```

66
docs/ja-JP/cli/configure.md Normal file
View File

@ -0,0 +1,66 @@
---
read_when:
- 認証情報、デバイス、またはagentデフォルトを対話的に調整したいとき
summary: '`openclaw configure`のCLIリファレンス（対話型設定プロンプト）'
title: configure
x-i18n:
generated_at: "2026-04-05T12:38:18Z"
model: gpt-5.4
provider: openai
source_hash: 989569fdb8e1b31ce3438756b3ed9bf18e0c8baf611c5981643ba5925459c98f
source_path: cli/configure.md
workflow: 15
---
# `openclaw configure`
認証情報、デバイス、agentデフォルトを設定するための対話型プロンプトです。
注記: **Model**セクションには、`agents.defaults.models` allowlist（`/model`とモデルピッカーに表示されるもの）用の複数選択が含まれるようになりました。
configureがプロバイダー認証の選択から開始された場合、デフォルトモデルとallowlistのピッカーは自動的にそのプロバイダーを優先します。Volcengine/BytePlusのようなペアのプロバイダーでは、同じ優先設定がそのcoding-planバリアント（`volcengine-plan/*`、`byteplus-plan/*`）にも一致します。優先プロバイダーフィルターによって空のリストになる場合、configureは空白のピッカーを表示する代わりに、フィルターなしのカタログへフォールバックします。
ヒント: サブコマンドなしで`openclaw config`を実行すると、同じウィザードが開きます。非対話型で編集するには`openclaw config get|set|unset`を使用してください。
Web検索については、`openclaw configure --section web`でプロバイダーを選択し、その認証情報を設定できます。一部のプロバイダーでは、プロバイダー固有の追加プロンプトも表示されます。
- **Grok**では、同じ`XAI_API_KEY`を使った任意の`x_search`セットアップを提案し、`x_search`モデルを選択できます。
- **Kimi**では、Moonshot APIリージョン（`api.moonshot.ai`または`api.moonshot.cn`）とデフォルトのKimi Web検索モデルを尋ねる場合があります。
関連:
- Gateway設定リファレンス: [Configuration](/gateway/configuration)
- Config CLI: [Config](/cli/config)
## オプション
- `--section <section>`: 繰り返し指定可能なセクションフィルター
利用可能なセクション:
- `workspace`
- `model`
- `web`
- `gateway`
- `daemon`
- `channels`
- `plugins`
- `skills`
- `health`
注記:
- Gatewayの実行場所を選ぶと、常に`gateway.mode`が更新されます。それだけが必要な場合は、他のセクションを選ばずに「Continue」を選択できます。
- チャンネル指向のサービス（Slack/Discord/Matrix/Microsoft Teams）では、セットアップ時にチャンネル/ルームのallowlist入力を求められます。名前またはIDを入力でき、可能な場合はウィザードが名前をIDに解決します。
- daemonインストール手順を実行する場合、トークン認証にはトークンが必要であり、`gateway.auth.token`はSecretRef管理されるため、configureはSecretRefを検証しますが、解決されたプレーンテキストのトークン値をsupervisorサービス環境メタデータへ永続化しません。
- トークン認証でトークンが必要で、設定されたトークンSecretRefが未解決の場合、configureは実行可能な対処ガイダンスを示してdaemonインストールをブロックします。
- `gateway.auth.token`と`gateway.auth.password`の両方が設定されていて、`gateway.auth.mode`が未設定の場合、configureはmodeが明示的に設定されるまでdaemonインストールをブロックします。
## 例
```bash
openclaw configure
openclaw configure --section web
openclaw configure --section model --section channels
openclaw configure --section gateway --section daemon
```

164
docs/ja-JP/cli/cron.md Normal file
View File

@ -0,0 +1,164 @@
---
read_when:
- スケジュールされたジョブやウェイクアップを使いたいとき
- cronの実行とログをデバッグしているとき
summary: '`openclaw cron`のCLIリファレンス（バックグラウンドジョブのスケジュールと実行）'
title: cron
x-i18n:
generated_at: "2026-04-05T12:38:38Z"
model: gpt-5.4
provider: openai
source_hash: f74ec8847835f24b3970f1b260feeb69c7ab6c6ec7e41615cbb73f37f14a8112
source_path: cli/cron.md
workflow: 15
---
# `openclaw cron`
Gatewayスケジューラーのcronジョブを管理します。
関連:
- Cronジョブ: [Cron jobs](/automation/cron-jobs)
ヒント: 完全なコマンド一覧については`openclaw cron --help`を実行してください。
注: 分離された`cron add`ジョブは、デフォルトで`--announce`配信を使用します。出力を内部のみに保つには`--no-deliver`を使用してください。
`--deliver`は引き続き`--announce`の非推奨エイリアスとして残っています。
注: cronが所有する分離実行はプレーンテキストの要約を想定しており、最終送信経路はランナーが管理します。
`--no-deliver`は実行を内部のみに保ちますが、配信をエージェントのメッセージツールへ戻すわけではありません。
注: one-shot（`--at`）ジョブは、デフォルトで成功後に削除されます。保持するには`--keep-after-run`を使用してください。
注: `--session`は`main`、`isolated`、`current`、`session:<id>`をサポートします。
作成時点のアクティブセッションにバインドするには`current`を使用し、
明示的な永続セッションキーには`session:<id>`を使用してください。
注: one-shot CLIジョブでは、オフセットなしの`--at`日時は、`--tz <iana>`も渡さない限りUTCとして扱われます。
`--tz <iana>`を渡すと、そのローカル壁時計時刻を指定タイムゾーンで解釈します。
注: 定期ジョブは、連続エラー後に指数バックオフによる再試行を使用するようになりました（30秒 → 1分 → 5分 → 15分 → 60分）。次に成功すると通常スケジュールに戻ります。
注: `openclaw cron run`は、手動実行がキューに入った時点ですぐに返るようになりました。成功レスポンスには`{ ok: true, enqueued: true, runId }`が含まれます。最終結果を追跡するには`openclaw cron runs --id <job-id>`を使用してください。
注: `openclaw cron run <job-id>`はデフォルトで強制実行します。
従来の「期限が来ている場合のみ実行」動作を維持するには`--due`を使用してください。
注: 分離されたcronターンでは、古くなった確認のみの返信は抑制されます。最初の結果が単なる中間ステータス更新であり、最終回答に責任を持つ子孫subagent実行がない場合、cronは配信前に実際の結果を得るため一度だけ再プロンプトします。
注: 分離実行がサイレントトークンのみ（`NO_REPLY` /
`no_reply`）を返した場合、cronは直接の送信配信とフォールバックのキュー要約経路の両方を抑制するため、チャットには何も投稿されません。
注: `cron add|edit --model ...`は、そのジョブに対して選択された許可済みモデルを使用します。
モデルが許可されていない場合、cronは警告を出し、代わりにジョブのエージェント/デフォルトの
モデル選択へフォールバックします。設定済みのフォールバックチェーンは引き続き適用されますが、明示的なジョブごとのフォールバックリストのない単純なモデル上書きでは、エージェントのプライマリが隠れた追加再試行ターゲットとして付与されなくなりました。
注: 分離cronのモデル優先順位は、Gmail-hook上書きが最優先で、その次にジョブごとの
`--model`、その次に保存されたcronセッションのモデル上書き、最後に通常の
エージェント/デフォルト選択です。
注: 分離cronのfast modeは、解決されたライブモデル選択に従います。モデル設定の
`params.fastMode`はデフォルトで適用されますが、保存されたセッションの`fastMode`
上書きは引き続き設定より優先されます。
注: 分離実行が`LiveSessionModelSwitchError`を投げた場合、cronは
再試行前に切り替え後のprovider/model（および存在する場合は切り替え後のauth profile上書き）を永続化します。外側の再試行ループは、初回試行後に最大2回の切り替え再試行に制限され、それ以降は無限ループせず中止します。
注: 失敗通知は、まず`delivery.failureDestination`、次に
グローバルの`cron.failureDestination`を使用し、明示的な失敗通知先が設定されていない場合は、最後にジョブのプライマリ
announceターゲットへフォールバックします。
注: 保持/剪定は設定で制御されます。
- `cron.sessionRetention`（デフォルト`24h`）は、完了した分離実行セッションを剪定します。
- `cron.runLog.maxBytes` + `cron.runLog.keepLines`は`~/.openclaw/cron/runs/<jobId>.jsonl`を剪定します。
アップグレード注記: 現在の配信/保存形式より前の古いcronジョブがある場合は、
`openclaw doctor --fix`を実行してください。Doctorは現在、レガシーなcronフィールド（`jobId`、`schedule.cron`、
トップレベルの配信フィールド（レガシーな`threadId`を含む）、ペイロードの`provider`配信エイリアス）を正規化し、
`cron.webhook`が設定されている場合は、単純な`notify: true` webhookフォールバックジョブを
明示的なwebhook配信へ移行します。
## よくある編集
メッセージを変更せずに配信設定を更新する:
```bash
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
```
分離ジョブの配信を無効にする:
```bash
openclaw cron edit <job-id> --no-deliver
```
分離ジョブで軽量なブートストラップコンテキストを有効にする:
```bash
openclaw cron edit <job-id> --light-context
```
特定のチャンネルへannounceする:
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
```
軽量なブートストラップコンテキスト付きの分離ジョブを作成する:
```bash
openclaw cron add \
--name "Lightweight morning brief" \
--cron "0 7 * * *" \
--session isolated \
--message "Summarize overnight updates." \
--light-context \
--no-deliver
```
`--light-context`は分離されたagent-turnジョブにのみ適用されます。cron実行では、軽量モードは完全なワークスペースのブートストラップセットを注入する代わりに、ブートストラップコンテキストを空に保ちます。
配信所有権に関する注記:
- cronが所有する分離ジョブは、最終的にユーザーに見える配信を常に
cronランナー（`announce`、`webhook`、または内部専用の`none`）経由でルーティングします。
- タスクが何らかの外部受信者へのメッセージ送信に言及している場合、エージェントは
それを直接送信しようとせず、結果の中で意図した送信先を説明するべきです。
## よくある管理コマンド
手動実行:
```bash
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50
```
エージェント/セッションの再ターゲット:
```bash
openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"
```
配信の調整:
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --best-effort-deliver
openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver
```
失敗時配信に関する注記:
- `delivery.failureDestination`は分離ジョブでサポートされています。
- メインセッションジョブでは、プライマリ
配信モードが`webhook`の場合にのみ`delivery.failureDestination`を使用できます。
- 失敗通知先を何も設定せず、ジョブがすでにある
チャンネルにannounceしている場合、失敗通知は同じannounceターゲットを再利用します。

64
docs/ja-JP/cli/daemon.md Normal file
View File

@ -0,0 +1,64 @@
---
read_when:
- スクリプト内でまだ `openclaw daemon ...` を使っているとき
- サービスのライフサイクルコマンド（install/start/stop/restart/status）が必要なとき
summary: '`openclaw daemon` の CLI リファレンス（Gateway サービス管理用のレガシーエイリアス）'
title: daemon
x-i18n:
generated_at: "2026-04-05T12:38:24Z"
model: gpt-5.4
provider: openai
source_hash: 91fdaf3c4f3e7dd4dff86f9b74a653dcba2674573698cf51efc4890077994169
source_path: cli/daemon.md
workflow: 15
---
# `openclaw daemon`
Gateway サービス管理コマンド用のレガシーエイリアスです。
`openclaw daemon ...` は、`openclaw gateway ...` のサービスコマンドと同じサービス制御画面にマッピングされます。
## 使用方法
```bash
openclaw daemon status
openclaw daemon install
openclaw daemon start
openclaw daemon stop
openclaw daemon restart
openclaw daemon uninstall
```
## サブコマンド
- `status`: サービスのインストール状態を表示し、Gateway のヘルスをプローブ
- `install`: サービスをインストール（`launchd`/`systemd`/`schtasks`）
- `uninstall`: サービスを削除
- `start`: サービスを起動
- `stop`: サービスを停止
- `restart`: サービスを再起動
## 共通オプション
- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
- ライフサイクル（`uninstall|start|stop|restart`）: `--json`
注意:
- `status` は、可能な場合、プローブ認証用に設定済みの auth SecretRef を解決します。
- このコマンド経路で必須の auth SecretRef が未解決の場合、プローブ接続 / 認証に失敗すると `daemon status --json` は `rpc.authWarning` を報告します。`--token` / `--password` を明示的に渡すか、先にシークレットソースを解決してください。
- プローブが成功した場合、未解決の auth-ref 警告は誤検知を避けるため抑制されます。
- `status --deep` は、ベストエフォートのシステムレベルサービススキャンを追加します。他の gateway 類似サービスを検出した場合、人間向け出力ではクリーンアップのヒントを表示し、1 台のマシンにつき 1 つの gateway が依然として通常の推奨であることを警告します。
- Linux の systemd インストールでは、`status` のトークンドリフトチェックに `Environment=` と `EnvironmentFile=` の両方の unit ソースが含まれます。
- ドリフトチェックは、マージされたランタイム env（まずサービスコマンド env、その後 process env へのフォールバック）を使って `gateway.auth.token` SecretRef を解決します。
- トークン認証が実質的に有効でない場合（`gateway.auth.mode` が明示的に `password` / `none` / `trusted-proxy`、または mode 未設定で password が優先され得て、かつ有効になり得るトークン候補がない場合）、トークンドリフトチェックは config トークン解決をスキップします。
- トークン認証にトークンが必要で、`gateway.auth.token` が SecretRef 管理されている場合、`install` はその SecretRef が解決可能であることを検証しますが、解決済みトークンをサービス環境メタデータには永続化しません。
- トークン認証にトークンが必要で、設定済みトークン SecretRef が未解決の場合、インストールは fail closed します。
- `gateway.auth.token` と `gateway.auth.password` の両方が設定されていて `gateway.auth.mode` が未設定の場合、mode が明示的に設定されるまで install はブロックされます。
- 1 台のホストで意図的に複数の gateway を実行する場合は、ポート、config/state、workspace を分離してください。[/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host) を参照してください。
## 推奨
現在のドキュメントと例については [`openclaw gateway`](/cli/gateway) を使用してください。

29
docs/ja-JP/cli/dashboard.md Normal file
View File

@ -0,0 +1,29 @@
---
read_when:
- 現在の token を使って Control UI を開きたいとき
- ブラウザを起動せずに URL を表示したいとき
summary: '`openclaw dashboard` の CLI リファレンス（Control UI を開く）'
title: dashboard
x-i18n:
generated_at: "2026-04-05T12:38:20Z"
model: gpt-5.4
provider: openai
source_hash: a34cd109a3803e2910fcb4d32f2588aa205a4933819829ef5598f0780f586c94
source_path: cli/dashboard.md
workflow: 15
---
# `openclaw dashboard`
現在の認証を使って Control UI を開きます。
```bash
openclaw dashboard
openclaw dashboard --no-open
```
注意:
- `dashboard` は、可能な場合は設定済みの `gateway.auth.token` SecretRefs を解決します。
- SecretRef 管理の token（解決済みまたは未解決）の場合、`dashboard` は、外部シークレットが端末出力、クリップボード履歴、またはブラウザ起動引数で露出しないように、token なしの URL を表示/コピー/オープンします。
- `gateway.auth.token` が SecretRef 管理だがこのコマンド経路では未解決の場合、このコマンドは無効な token プレースホルダーを埋め込む代わりに、token なしの URL と明示的な対処ガイダンスを表示します。

160
docs/ja-JP/cli/devices.md Normal file
View File

@ -0,0 +1,160 @@
---
read_when:
- デバイスのpairingリクエストを承認しているとき
- デバイストークンをローテーションまたは失効する必要があるとき
summary: '`openclaw devices`のCLIリファレンス（デバイスpairing + トークンのローテーション/失効）'
title: devices
x-i18n:
generated_at: "2026-04-05T12:38:46Z"
model: gpt-5.4
provider: openai
source_hash: e2f9fcb8e3508a703590f87caaafd953a5d3557e11c958cbb2be1d67bb8720f4
source_path: cli/devices.md
workflow: 15
---
# `openclaw devices`
デバイスのpairingリクエストと、デバイス単位のトークンを管理します。
## コマンド
### `openclaw devices list`
保留中のpairingリクエストと、pairing済みデバイスを一覧表示します。
```
openclaw devices list
openclaw devices list --json
```
保留中リクエストの出力には、要求されたroleとscopesが含まれるため、承認前に内容を確認できます。
### `openclaw devices remove <deviceId>`
pairing済みデバイスのエントリーを1つ削除します。
pairing済みデバイストークンで認証されている場合、adminでない呼び出し元は**自分自身**のデバイスエントリーのみ削除できます。他のデバイスを削除するには`operator.admin`が必要です。
```
openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json
```
### `openclaw devices clear --yes [--pending]`
pairing済みデバイスを一括削除します。
```
openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json
```
### `openclaw devices approve [requestId] [--latest]`
保留中のデバイスpairingリクエストを承認します。`requestId`を省略した場合、OpenClawは最新の保留中リクエストを自動承認します。
注記: デバイスが変更された認証詳細（role/scopes/public key）でpairingを再試行すると、OpenClawは以前の保留中エントリーを置き換え、新しい`requestId`を発行します。現在のIDを使うため、承認直前に`openclaw devices list`を実行してください。
```
openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest
```
### `openclaw devices reject <requestId>`
保留中のデバイスpairingリクエストを拒否します。
```
openclaw devices reject <requestId>
```
### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
特定のroleに対するデバイストークンをローテーションします（必要に応じてscopesも更新します）。
対象roleは、そのデバイスの承認済みpairing契約内にすでに存在している必要があります。ローテーションで新しい未承認roleを発行することはできません。
`--scope`を省略すると、保存済みのローテーション後トークンで後から再接続した際に、そのトークンのキャッシュ済み承認scopesが再利用されます。明示的な`--scope`値を渡した場合、それらが今後のキャッシュ済みトークン再接続用の保存scopeセットになります。
adminでないpairing済みデバイスの呼び出し元は、**自分自身**のデバイストークンのみローテーションできます。また、明示的な`--scope`値はすべて、呼び出し元セッション自身のoperator scopes内に収まっている必要があります。ローテーションによって、呼び出し元がすでに持っているより広いoperatorトークンを発行することはできません。
```
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
```
新しいトークンpayloadをJSONで返します。
### `openclaw devices revoke --device <id> --role <role>`
特定のroleに対するデバイストークンを失効します。
adminでないpairing済みデバイスの呼び出し元は、**自分自身**のデバイストークンのみ失効できます。他のデバイスのトークンを失効するには`operator.admin`が必要です。
```
openclaw devices revoke --device <deviceId> --role node
```
失効結果をJSONで返します。
## 共通オプション
- `--url <url>`: Gateway WebSocket URL（設定されている場合はデフォルトで`gateway.remote.url`）。
- `--token <token>`: Gatewayトークン（必要な場合）。
- `--password <password>`: Gatewayパスワード（パスワード認証）。
- `--timeout <ms>`: RPCタイムアウト。
- `--json`: JSON出力（スクリプト向けに推奨）。
注記: `--url`を設定した場合、CLIはconfigや環境の認証情報にはフォールバックしません。
`--token`または`--password`を明示的に渡してください。明示的な認証情報がない場合はエラーになります。
## 注記
- トークンローテーションは新しいトークンを返します（機微情報）。シークレットとして扱ってください。
- これらのコマンドには`operator.pairing`（または`operator.admin`）scopeが必要です。
- トークンローテーションは、そのデバイスに対して承認されたpairing roleセットと承認済みscopeベースラインの範囲内にとどまります。迷い込んだキャッシュ済みトークンエントリーが新しいローテーション対象を付与することはありません。
- pairing済みデバイストークンセッションでは、デバイス横断の管理はadmin専用です。`remove`、`rotate`、`revoke`は、呼び出し元に`operator.admin`がない限り自分自身にのみ許可されます。
- `devices clear`は意図的に`--yes`でゲートされています。
- local loopbackでpairing scopeが利用できない場合（かつ明示的な`--url`が渡されていない場合）、list/approveはローカルpairingフォールバックを使用できます。
- `devices approve`は、`requestId`を省略した場合または`--latest`を渡した場合に、最新の保留中リクエストを自動選択します。
## トークンドリフト回復チェックリスト
Control UIや他のクライアントが`AUTH_TOKEN_MISMATCH`または`AUTH_DEVICE_TOKEN_MISMATCH`で失敗し続ける場合に使用してください。
1. 現在のGatewayトークンソースを確認します。
```bash
openclaw config get gateway.auth.token
```
2. pairing済みデバイスを一覧表示し、影響を受けているdevice idを特定します。
```bash
openclaw devices list
```
3. 影響を受けているデバイスのoperatorトークンをローテーションします。
```bash
openclaw devices rotate --device <deviceId> --role operator
```
4. ローテーションだけでは不十分な場合は、古いpairingを削除して再承認します。
```bash
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>
```
5. 現在の共有トークン/パスワードでクライアント接続を再試行します。
注記:
- 通常の再接続認証の優先順位は、明示的な共有トークン/パスワード、次に明示的な`deviceToken`、次に保存済みデバイストークン、最後にブートストラップトークンです。
- 信頼済みの`AUTH_TOKEN_MISMATCH`回復では、1回に限った制限付き再試行のために、共有トークンと保存済みデバイストークンの両方を一時的に一緒に送信できます。
関連:
- [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
- [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)

70
docs/ja-JP/cli/directory.md Normal file
View File

@ -0,0 +1,70 @@
---
read_when:
- channelの連絡先/group/self IDを調べたい場合
- channel directory adapterを開発している場合
summary: '`openclaw directory`のCLIリファレンス（self、peers、groups）'
title: directory
x-i18n:
generated_at: "2026-04-05T12:38:28Z"
model: gpt-5.4
provider: openai
source_hash: 6a81a037e0a33f77c24b1adabbc4be16ed4d03c419873f3cbdd63f2ce84a1064
source_path: cli/directory.md
workflow: 15
---
# `openclaw directory`
対応しているchannels向けのdirectory検索（連絡先/peer、group、「自分」）。
## よく使うフラグ
- `--channel <name>`: channel id/alias（複数のchannelsが設定されている場合は必須。1つだけ設定されている場合は自動）
- `--account <id>`: account id（デフォルト: channel default）
- `--json`: JSONを出力
## 注
- `directory`は、他のコマンドに貼り付けられるIDを見つけるためのものです（特に`openclaw message send --target ...`）。
- 多くのchannelsでは、結果はライブprovider directoryではなく、configベース（allowlist / 設定済みgroups）です。
- デフォルト出力は`id`（場合によっては`name`も）をタブ区切りで表示します。スクリプト用途では`--json`を使用してください。
## `message send`で結果を使う
```bash
openclaw directory peers list --channel slack --query "U0"
openclaw message send --channel slack --target user:U012ABCDEF --message "hello"
```
## ID形式（channel別）
- WhatsApp: `+15551234567`（DM）、`1234567890-1234567890@g.us`（group）
- Telegram: `@username`または数値chat id。groupsは数値id
- Slack: `user:U…` および `channel:C…`
- Discord: `user:<id>` および `channel:<id>`
- Matrix (plugin): `user:@user:server`、`room:!roomId:server`、または`#alias:server`
- Microsoft Teams (plugin): `user:<id>` および `conversation:<id>`
- Zalo (plugin): user id（Bot API）
- Zalo Personal / `zalouser` (plugin): `zca`のthread id（DM/group）（`me`、`friend list`、`group list`）
## Self（「自分」）
```bash
openclaw directory self --channel zalouser
```
## Peers（連絡先/users）
```bash
openclaw directory peers list --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory peers list --channel zalouser --limit 50
```
## Groups
```bash
openclaw directory groups list --channel zalouser
openclaw directory groups list --channel zalouser --query "work"
openclaw directory groups members --channel zalouser --group-id <id>
```

55
docs/ja-JP/cli/dns.md Normal file
View File

@ -0,0 +1,55 @@
---
read_when:
- Tailscale + CoreDNS 経由で広域ディスカバリー（DNS-SD）を使いたいとき
- You’re setting up split DNS for a custom discovery domain (example: openclaw.internal)
summary: '`openclaw dns` の CLI リファレンス（広域ディスカバリーヘルパー）'
title: dns
x-i18n:
generated_at: "2026-04-05T12:38:28Z"
model: gpt-5.4
provider: openai
source_hash: 4831fbb7791adfed5195bc4ba36bb248d2bc8830958334211d3c96f824617927
source_path: cli/dns.md
workflow: 15
---
# `openclaw dns`
広域ディスカバリー（Tailscale + CoreDNS）用の DNS ヘルパーです。現在は macOS + Homebrew CoreDNS に主に対応しています。
関連:
- Gateway ディスカバリー: [ディスカバリー](/gateway/discovery)
- 広域ディスカバリー設定: [設定](/gateway/configuration)
## セットアップ
```bash
openclaw dns setup
openclaw dns setup --domain openclaw.internal
openclaw dns setup --apply
```
## `dns setup`
ユニキャスト DNS-SD ディスカバリー向けの CoreDNS セットアップを計画または適用します。
オプション:
- `--domain <domain>`: 広域ディスカバリードメイン（例 `openclaw.internal`）
- `--apply`: CoreDNS 設定をインストールまたは更新し、サービスを再起動します（sudo が必要。macOS のみ）
表示内容:
- 解決されたディスカバリードメイン
- ゾーンファイルのパス
- 現在の tailnet IP
- 推奨される `openclaw.json` ディスカバリー設定
- 設定すべき Tailscale Split DNS の nameserver/domain 値
注意:
- `--apply` を付けない場合、このコマンドは計画用ヘルパーのみとして動作し、推奨セットアップを表示します。
- `--domain` を省略した場合、OpenClaw は設定の `discovery.wideArea.domain` を使います。
- `--apply` は現在 macOS のみ対応で、Homebrew CoreDNS を前提としています。
- `--apply` は必要に応じてゾーンファイルを初期化し、CoreDNS の import stanza が存在することを保証し、`coredns` の brew service を再起動します。

35
docs/ja-JP/cli/docs.md Normal file
View File

@ -0,0 +1,35 @@
---
read_when:
- ターミナルから OpenClaw のライブドキュメントを検索したい
summary: '`openclaw docs` の CLI リファレンス（ライブドキュメントインデックスを検索）'
title: docs
x-i18n:
generated_at: "2026-04-05T12:38:26Z"
model: gpt-5.4
provider: openai
source_hash: cfcceed872d7509b9843af3fae733a136bc5e26ded55c2ac47a16489a1636989
source_path: cli/docs.md
workflow: 15
---
# `openclaw docs`
ライブドキュメントインデックスを検索します。
引数:
- `[query...]`: ライブドキュメントインデックスに送信する検索語
例:
```bash
openclaw docs
openclaw docs browser existing-session
openclaw docs sandbox allowHostControl
openclaw docs gateway token secretref
```
注意:
- クエリなしの場合、`openclaw docs` はライブドキュメント検索のエントリーポイントを開きます。
- 複数語のクエリは 1 つの検索リクエストとしてそのまま渡されます。

70
docs/ja-JP/cli/doctor.md Normal file
View File

@ -0,0 +1,70 @@
---
read_when:
- 接続 / 認証の問題があり、ガイド付きの修正を行いたいとき
- 更新後に健全性確認をしたいとき
summary: '`openclaw doctor` の CLI リファレンス（ヘルスチェック + ガイド付き修復）'
title: doctor
x-i18n:
generated_at: "2026-04-05T12:38:40Z"
model: gpt-5.4
provider: openai
source_hash: d257a9e2797b4b0b50c1020165c8a1cd6a2342381bf9c351645ca37494c881e1
source_path: cli/doctor.md
workflow: 15
---
# `openclaw doctor`
Gateway とチャネルのヘルスチェック + クイック修復です。
関連:
- トラブルシューティング: [Troubleshooting](/gateway/troubleshooting)
- セキュリティ監査: [Security](/gateway/security)
## 例
```bash
openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
openclaw doctor --repair --non-interactive
openclaw doctor --generate-gateway-token
```
## オプション
- `--no-workspace-suggestions`: workspace のメモリ / 検索に関する提案を無効化
- `--yes`: プロンプトなしでデフォルトを受け入れる
- `--repair`: 推奨される修復をプロンプトなしで適用
- `--fix`: `--repair` のエイリアス
- `--force`: 必要に応じてカスタムサービス設定の上書きを含む、強力な修復を適用
- `--non-interactive`: プロンプトなしで実行; 安全な移行のみ
- `--generate-gateway-token`: Gateway トークンを生成して設定
- `--deep`: 追加の gateway インストールを検出するためにシステムサービスをスキャン
注意:
- 対話型プロンプト（キーチェーン / OAuth 修復など）は、stdin が TTY であり、かつ `--non-interactive` が**設定されていない**場合にのみ実行されます。ヘッドレス実行（cron、Telegram、ターミナルなし）ではプロンプトはスキップされます。
- `--fix`（`--repair` のエイリアス）は、バックアップを `~/.openclaw/openclaw.json.bak` に書き出し、不明な config キーを削除して、各削除項目を一覧表示します。
- 状態整合性チェックは、現在 sessions ディレクトリ内の孤立した transcript ファイルを検出し、安全に容量を回収するためにそれらを `.deleted.<timestamp>` としてアーカイブできます。
- doctor は `~/.openclaw/cron/jobs.json`（または `cron.store`）もスキャンしてレガシーな cron ジョブ形式を検出し、スケジューラーがランタイムで自動正規化する前にその場で書き換えることができます。
- doctor は、レガシーなフラット Talk 設定（`talk.voiceId`、`talk.modelId` など）を `talk.provider` + `talk.providers.<provider>` に自動移行します。
- 差分がオブジェクトキー順序だけの場合、`doctor --fix` の繰り返し実行では Talk 正規化を報告 / 適用しなくなりました。
- doctor にはメモリ検索準備状況チェックが含まれており、embedding 認証情報がない場合は `openclaw configure --section model` を推奨できます。
- sandbox mode が有効なのに Docker が利用できない場合、doctor は高シグナルな警告と修正方法（`install Docker` または `openclaw config set agents.defaults.sandbox.mode off`）を報告します。
- `gateway.auth.token` / `gateway.auth.password` が SecretRef 管理で、現在のコマンド経路から利用できない場合、doctor は読み取り専用の警告を報告し、平文のフォールバック認証情報は書き込みません。
- fix パスでチャネル SecretRef の検査に失敗しても、doctor は途中終了せず、警告を報告して続行します。
- Telegram の `allowFrom` ユーザー名自動解決（`doctor --fix`）には、現在のコマンド経路で解決可能な Telegram トークンが必要です。トークン検査が利用できない場合、doctor は警告を報告し、その回の自動解決をスキップします。
## macOS: `launchctl` env 上書き
以前に `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（または `...PASSWORD`）を実行していた場合、その値は config ファイルを上書きし、継続的な「unauthorized」エラーの原因になることがあります。
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```

25
docs/ja-JP/cli/flows.md Normal file
View File

@ -0,0 +1,25 @@
---
read_when:
- 古いドキュメントやリリースノートで openclaw flows を見かけた
summary: 'リダイレクト: フローコマンドは `openclaw tasks flow` 配下にあります'
title: flows（リダイレクト）
x-i18n:
generated_at: "2026-04-05T12:38:32Z"
model: gpt-5.4
provider: openai
source_hash: f4b9acefdb4e8dedde08d96986fe9b1ca7f91293281850b68ff9fa28f0516a61
source_path: cli/flows.md
workflow: 15
---
# `openclaw tasks flow`
フローコマンドは独立した `flows` コマンドではなく、`openclaw tasks` のサブコマンドです。
```bash
openclaw tasks flow list [--json]
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
```
完全なドキュメントについては、[Task Flow](/automation/taskflow) と [tasks CLI リファレンス](/cli/index#tasks) を参照してください。

314
docs/ja-JP/cli/gateway.md Normal file
View File

@ -0,0 +1,314 @@
---
read_when:
- CLIからGatewayを実行する場合（開発またはサーバー）
- Gateway auth、bind mode、接続性をデバッグする場合
- Bonjour経由でGatewayを検出する場合（ローカル + 広域DNS-SD）
summary: OpenClaw Gateway CLI（`openclaw gateway`）— Gatewayの実行、照会、検出
title: gateway
x-i18n:
generated_at: "2026-04-05T12:39:15Z"
model: gpt-5.4
provider: openai
source_hash: e311ded0dbad84b8212f0968f3563998d49c5e0eb292a0dc4b3bd3c22d4fa7f2
source_path: cli/gateway.md
workflow: 15
---
# Gateway CLI
GatewayはOpenClawのWebSocketサーバーです（channels、nodes、sessions、hooks）。
このページのサブコマンドは`openclaw gateway …`配下にあります。
関連ドキュメント:
- [/gateway/bonjour](/gateway/bonjour)
- [/gateway/discovery](/gateway/discovery)
- [/gateway/configuration](/gateway/configuration)
## Gatewayを実行する
ローカルGatewayプロセスを実行します:
```bash
openclaw gateway
```
フォアグラウンドalias:
```bash
openclaw gateway run
```
注:
- デフォルトでは、`~/.openclaw/openclaw.json`に`gateway.mode=local`が設定されていない限り、Gatewayは起動を拒否します。アドホック/開発実行には`--allow-unconfigured`を使ってください。
- `openclaw onboard --mode local`と`openclaw setup`は、`gateway.mode=local`を書き込むことが想定されています。ファイルが存在するのに`gateway.mode`が欠けている場合は、それを暗黙にlocal modeとみなすのではなく、壊れているか上書きされたconfigとして扱い、修復してください。
- ファイルが存在し、`gateway.mode`が欠けている場合、Gatewayはそれを疑わしいconfig破損として扱い、勝手に「localと推測」することを拒否します。
- authなしでloopbackを超えてbindすることはブロックされます（安全ガードレール）。
- `SIGUSR1`は、認可されている場合にプロセス内再起動をトリガーします（`commands.restart`はデフォルトで有効です。手動再起動をブロックするには`commands.restart: false`を設定してください。ただしgateway tool/config apply/updateは引き続き許可されます）。
- `SIGINT`/`SIGTERM`ハンドラーはgatewayプロセスを停止しますが、カスタムterminal stateは復元しません。CLIをTUIやraw-mode入力でラップしている場合は、終了前にterminalを復元してください。
### オプション
- `--port <port>`: WebSocketポート（デフォルトはconfig/envから取得。通常は`18789`）。
- `--bind <loopback|lan|tailnet|auto|custom>`: listener bind mode。
- `--auth <token|password>`: auth mode上書き。
- `--token <token>`: token上書き（プロセスに対して`OPENCLAW_GATEWAY_TOKEN`も設定）。
- `--password <password>`: password上書き。警告: インラインpasswordはローカルのプロセス一覧に露出する可能性があります。
- `--password-file <path>`: ファイルからgateway passwordを読み込みます。
- `--tailscale <off|serve|funnel>`: Tailscale経由でGatewayを公開します。
- `--tailscale-reset-on-exit`: 終了時にTailscale serve/funnel設定をリセットします。
- `--allow-unconfigured`: config内に`gateway.mode=local`がなくてもgateway起動を許可します。これはアドホック/開発bootstrap専用の起動ガード回避であり、configファイルの書き込みや修復は行いません。
- `--dev`: dev config + workspaceがなければ作成します（`BOOTSTRAP.md`はスキップ）。
- `--reset`: dev config + credentials + sessions + workspaceをリセットします（`--dev`が必要）。
- `--force`: 起動前に、選択したポート上の既存listenerをkillします。
- `--verbose`: 詳細ログ。
- `--cli-backend-logs`: consoleにはCLI backend logsのみ表示します（stdout/stderrも有効化）。
- `--claude-cli-logs`: `--cli-backend-logs`の非推奨alias。
- `--ws-log <auto|full|compact>`: websocketログスタイル（デフォルト`auto`）。
- `--compact`: `--ws-log compact`のalias。
- `--raw-stream`: 生のmodel streamイベントをjsonlに記録します。
- `--raw-stream-path <path>`: 生のstream jsonlパス。
## 実行中のGatewayを照会する
すべての照会コマンドはWebSocket RPCを使います。
出力モード:
- デフォルト: 人間が読みやすい形式（TTYでは色付き）。
- `--json`: 機械可読JSON（スタイル/スピナーなし）。
- `--no-color`（または`NO_COLOR=1`）: 人間向けレイアウトは維持したままANSIを無効化。
共通オプション（対応している場合）:
- `--url <url>`: Gateway WebSocket URL。
- `--token <token>`: Gateway token。
- `--password <password>`: Gateway password。
- `--timeout <ms>`: timeout/budget（コマンドごとに異なります）。
- `--expect-final`: 「final」レスポンスを待機します（agent呼び出し）。
注: `--url`を設定すると、CLIはconfigや環境のcredentialsへフォールバックしません。
`--token`または`--password`を明示的に渡してください。明示的credentialsが欠けている場合はエラーです。
### `gateway health`
```bash
openclaw gateway health --url ws://127.0.0.1:18789
```
### `gateway usage-cost`
session logsからusage-costの要約を取得します。
```bash
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json
```
オプション:
- `--days <days>`: 含める日数（デフォルト`30`）。
### `gateway status`
`gateway status`は、Gateway service（launchd/systemd/schtasks）と任意のRPC probeを表示します。
```bash
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
```
オプション:
- `--url <url>`: 明示的なprobe targetを追加します。設定済みremote + localhostも引き続きprobeされます。
- `--token <token>`: probe用token auth。
- `--password <password>`: probe用password auth。
- `--timeout <ms>`: probe timeout（デフォルト`10000`）。
- `--no-probe`: RPC probeをスキップします（serviceのみの表示）。
- `--deep`: systemレベルserviceもスキャンします。
- `--require-rpc`: RPC probeが失敗したら非ゼロで終了します。`--no-probe`とは併用できません。
注:
- `gateway status`は、ローカルCLI configが欠落または無効でも、診断のために引き続き利用可能です。
- `gateway status`は、可能な場合probe authのために設定済みauth SecretRefを解決します。
- 必須auth SecretRefがこのコマンドパスで未解決の場合、`gateway status --json`は、probe接続/authが失敗したときに`rpc.authWarning`を報告します。`--token`/`--password`を明示的に渡すか、先にsecret sourceを解決してください。
- probeが成功した場合、誤検知を避けるため未解決auth-ref警告は抑制されます。
- scriptやautomationで、listenerが存在するだけでは不十分でGateway RPC自体の健全性が必要な場合は、`--require-rpc`を使ってください。
- `--deep`は、追加のlaunchd/systemd/schtasksインストールをベストエフォートでスキャンします。複数のgateway風serviceが検出された場合、人間向け出力にはcleanupヒントが表示され、ほとんどのセットアップでは1台のマシンにつき1つのgatewayを実行するべきだと警告されます。
- 人間向け出力には、profileやstate-dirのずれの診断に役立つよう、解決されたファイルログパスとCLI対serviceのconfigパス/妥当性スナップショットが含まれます。
- Linux systemdインストールでは、service auth driftチェックはunit内の`Environment=`と`EnvironmentFile=`の両方の値を読み取ります（`%h`、引用付きパス、複数ファイル、任意の`-`ファイルを含む）。
- driftチェックは、マージされたruntime env（service command env優先、次にprocess envフォールバック）を使って`gateway.auth.token` SecretRefを解決します。
- token authが実効的に有効でない場合（明示的な`gateway.auth.mode`が`password`/`none`/`trusted-proxy`、またはmode未設定でpasswordが優先されうる上に勝てるtoken候補がない場合）、token-driftチェックはconfig token解決をスキップします。
### `gateway probe`
`gateway probe`は「すべてをデバッグする」コマンドです。常に次をprobeします。
- 設定済みのremote gateway（設定されている場合）、および
- localhost（loopback）**remoteが設定されていても**。
`--url`を渡した場合、その明示的targetは両方より先に追加されます。人間向け出力では
targetに次のラベルが付きます。
- `URL (explicit)`
- `Remote (configured)` または `Remote (configured, inactive)`
- `Local loopback`
複数のgatewayに到達できる場合は、すべて表示されます。分離されたprofile/port（たとえばrescue bot）を使う場合、複数gatewayはサポートされますが、ほとんどのインストールでは依然として単一gatewayを実行します。
```bash
openclaw gateway probe
openclaw gateway probe --json
```
解釈:
- `Reachable: yes`は、少なくとも1つのtargetがWebSocket接続を受け入れたことを意味します。
- `RPC: ok`は、詳細RPC呼び出し（`health`/`status`/`system-presence`/`config.get`）も成功したことを意味します。
- `RPC: limited - missing scope: operator.read`は、接続は成功したが詳細RPCがscope制限されていることを意味します。これは完全な失敗ではなく**degraded**な到達性として報告されます。
- 終了コードが非ゼロになるのは、probeしたtargetのどれにも到達できなかった場合だけです。
JSONの注記（`--json`）:
- トップレベル:
- `ok`: 少なくとも1つのtargetに到達可能。
- `degraded`: 少なくとも1つのtargetでscope制限された詳細RPCがあった。
- `primaryTargetId`: アクティブな勝者として扱うべき最良のtarget。この順序です: 明示的URL、SSH tunnel、設定済みremote、次にlocal loopback。
- `warnings[]`: `code`、`message`、および任意の`targetIds`を持つベストエフォートの警告レコード。
- `network`: 現在のconfigとホストネットワークから導出されたlocal loopback/tailnet URLヒント。
- `discovery.timeoutMs`と`discovery.count`: このprobeパスで使われた実際のdiscovery budget/result count。
- targetごと（`targets[].connect`）:
- `ok`: 接続後の到達性 + degraded分類。
- `rpcOk`: 完全な詳細RPC成功。
- `scopeLimited`: 詳細RPCが`operator.read` scope不足で失敗。
よくある警告コード:
- `ssh_tunnel_failed`: SSH tunnelセットアップに失敗し、コマンドは直接probeへフォールバックしました。
- `multiple_gateways`: 複数のtargetに到達可能でした。これは、rescue botのように意図的に分離profileを動かしている場合を除き、通常ではありません。
- `auth_secretref_unresolved`: 設定済みauth SecretRefを失敗したtarget用に解決できませんでした。
- `probe_scope_limited`: WebSocket接続は成功しましたが、詳細RPCは`operator.read`不足により制限されました。
#### SSH経由のremote（Mac app同等）
macOS appの「Remote over SSH」modeは、ローカルポートフォワードを使うことで、loopbackのみにbindされている可能性があるremote gatewayを`ws://127.0.0.1:<port>`で到達可能にします。
CLI相当:
```bash
openclaw gateway probe --ssh user@gateway-host
```
オプション:
- `--ssh <target>`: `user@host`または`user@host:port`（portのデフォルトは`22`）。
- `--ssh-identity <path>`: identityファイル。
- `--ssh-auto`: 解決済み
discovery endpoint（`local.`と、設定されている場合は構成済み広域domain）から、最初に発見されたgateway hostをSSH targetとして選択します。TXTのみの
ヒントは無視されます。
Config（任意、デフォルトとして使用）:
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
### `gateway call <method>`
低レベルRPCヘルパー。
```bash
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
オプション:
- `--params <json>`: params用JSON object文字列（デフォルト`{}`）
- `--url <url>`
- `--token <token>`
- `--password <password>`
- `--timeout <ms>`
- `--expect-final`
- `--json`
注:
- `--params`は有効なJSONでなければなりません。
- `--expect-final`は主に、中間イベントをstreamした後にfinal payloadを返すagent風RPC向けです。
## Gateway serviceを管理する
```bash
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall
```
コマンドオプション:
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
- `gateway uninstall|start|stop|restart`: `--json`
注:
- `gateway install`は`--port`、`--runtime`、`--token`、`--force`、`--json`をサポートしています。
- token authにtokenが必要で、`gateway.auth.token`がSecretRef管理されている場合、`gateway install`はそのSecretRefが解決可能であることを検証しますが、解決したtokenをservice環境メタデータに永続化しません。
- token authにtokenが必要で、設定済みtoken SecretRefが未解決の場合、installはフォールバックのプレーンテキストを永続化せず、fail closedします。
- `gateway run`でpassword authを使う場合は、インライン`--password`よりも`OPENCLAW_GATEWAY_PASSWORD`、`--password-file`、またはSecretRef対応の`gateway.auth.password`を推奨します。
- 推測auth modeでは、shellのみの`OPENCLAW_GATEWAY_PASSWORD`はinstall時のtoken要件を緩和しません。管理serviceをインストールする場合は、永続的なconfig（`gateway.auth.password`またはconfig `env`）を使ってください。
- `gateway.auth.token`と`gateway.auth.password`の両方が設定され、`gateway.auth.mode`が未設定の場合、modeを明示的に設定するまでinstallはブロックされます。
- ライフサイクルコマンドはスクリプト用途に`--json`を受け付けます。
## Gatewayを検出する（Bonjour）
`gateway discover`はGateway beacon（`_openclaw-gw._tcp`）をスキャンします。
- マルチキャストDNS-SD: `local.`
- ユニキャストDNS-SD（広域Bonjour）: domain（例: `openclaw.internal.`）を選び、split DNS + DNS serverを設定します。詳細は[/gateway/bonjour](/gateway/bonjour)を参照してください
Bonjour discoveryが有効なGatewayのみ（デフォルトで有効）がbeaconを広告します。
広域discoveryレコードには次のTXTが含まれます:
- `role`（gateway roleヒント）
- `transport`（transportヒント、例: `gateway`）
- `gatewayPort`（WebSocketポート。通常`18789`）
- `sshPort`（任意。これがない場合、clientsはSSH targetのデフォルトを`22`にします）
- `tailnetDns`（利用可能な場合のMagicDNS hostname）
- `gatewayTls` / `gatewayTlsSha256`（TLS有効化 + 証明書フィンガープリント）
- `cliPath`（広域zoneに書き込まれるremote-installヒント）
### `gateway discover`
```bash
openclaw gateway discover
```
オプション:
- `--timeout <ms>`: コマンドごとのtimeout（browse/resolve）。デフォルト`2000`。
- `--json`: 機械可読出力（スタイル/スピナーも無効化）。
例:
```bash
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
注:
- CLIは、広域domainが有効な場合、`local.`と設定済み広域domainをスキャンします。
- JSON出力の`wsUrl`は、TXTのみの
ヒント（`lanHost`や`tailnetDns`など）ではなく、解決されたservice endpointから導出されます。
- `local.` mDNSでは、`sshPort`と`cliPath`は
`discovery.mdns.mode`が`full`の場合のみブロードキャストされます。広域DNS-SDでは引き続き`cliPath`が書き込まれ、`sshPort`
も同様に任意です。

40
docs/ja-JP/cli/health.md Normal file
View File

@ -0,0 +1,40 @@
---
read_when:
- 実行中の Gateway のヘルスをすばやく確認したいとき
summary: '`openclaw health` の CLI リファレンス（RPC 経由の Gateway ヘルススナップショット）'
title: health
x-i18n:
generated_at: "2026-04-05T12:38:34Z"
model: gpt-5.4
provider: openai
source_hash: 4ed2b9ceefee6159cabaae9172d2d88174626456e7503d5d2bcd142634188ff0
source_path: cli/health.md
workflow: 15
---
# `openclaw health`
実行中の Gateway からヘルス情報を取得します。
オプション:
- `--json`: 機械可読な出力
- `--timeout <ms>`: 接続タイムアウト（ミリ秒、既定 `10000`）
- `--verbose`: 詳細ログ
- `--debug`: `--verbose` のエイリアス
例:
```bash
openclaw health
openclaw health --json
openclaw health --timeout 2500
openclaw health --verbose
openclaw health --debug
```
注意:
- 既定の `openclaw health` は、実行中の gateway にヘルススナップショットを問い合わせます。gateway にすでに新しいキャッシュ済みスナップショットがある場合、そのキャッシュ済みペイロードを返し、バックグラウンドで更新できます。
- `--verbose` はライブプローブを強制し、gateway 接続の詳細を表示し、人間が読める出力を設定済みのすべてのアカウントとエージェントにわたって展開します。
- 複数のエージェントが設定されている場合、出力にはエージェントごとのセッションストアが含まれます。

344
docs/ja-JP/cli/hooks.md Normal file
View File

@ -0,0 +1,344 @@
---
read_when:
- エージェントフックを管理したい
- フックの利用可否を確認したい、またはワークスペースフックを有効化したい
summary: '`openclaw hooks` の CLI リファレンス（エージェントフック）'
title: hooks
x-i18n:
generated_at: "2026-04-05T12:39:06Z"
model: gpt-5.4
provider: openai
source_hash: 8dc9144e9844e9c3cdef2514098eb170543746fcc55ca5a1cc746c12d80209e7
source_path: cli/hooks.md
workflow: 15
---
# `openclaw hooks`
エージェントフックを管理します（`/new`、`/reset`、Gateway 起動などのコマンドに対するイベント駆動の自動化）。
サブコマンドなしで `openclaw hooks` を実行すると、`openclaw hooks list` と同等です。
関連:
- フック: [Hooks](/automation/hooks)
- プラグインフック: [Plugin hooks](/plugins/architecture#provider-runtime-hooks)
## すべてのフックを一覧表示
```bash
openclaw hooks list
```
workspace、managed、extra、bundled ディレクトリから検出されたすべてのフックを一覧表示します。
**オプション:**
- `--eligible`: 利用可能なフックのみを表示します（要件を満たしているもの）
- `--json`: JSON として出力します
- `-v, --verbose`: 不足している要件を含む詳細情報を表示します
**出力例:**
```
Hooks (4/4 ready)
Ready:
🚀 boot-md ✓ - Run BOOT.md on gateway startup
📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
📝 command-logger ✓ - Log all command events to a centralized audit file
💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued
```
**例（verbose）:**
```bash
openclaw hooks list --verbose
```
利用可能でないフックについて、不足している要件を表示します。
**例（JSON）:**
```bash
openclaw hooks list --json
```
プログラムで利用できる構造化 JSON を返します。
## フック情報を取得
```bash
openclaw hooks info <name>
```
特定のフックの詳細情報を表示します。
**引数:**
- `<name>`: フック名またはフックキー（例: `session-memory`）
**オプション:**
- `--json`: JSON として出力します
**例:**
```bash
openclaw hooks info session-memory
```
**出力:**
```
💾 session-memory ✓ Ready
Save session context to memory when /new or /reset command is issued
Details:
Source: openclaw-bundled
Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
Events: command:new, command:reset
Requirements:
Config: ✓ workspace.dir
```
## フックの利用可否を確認
```bash
openclaw hooks check
```
フックの利用可否ステータスの概要（利用可能な数と利用不可の数）を表示します。
**オプション:**
- `--json`: JSON として出力します
**出力例:**
```
Hooks Status
Total hooks: 4
Ready: 4
Not ready: 0
```
## フックを有効化
```bash
openclaw hooks enable <name>
```
特定のフックを設定に追加して有効化します（デフォルトでは `~/.openclaw/openclaw.json`）。
**注意:** ワークスペースフックは、ここまたは設定で有効化するまでデフォルトで無効です。プラグインが管理するフックは `openclaw hooks list` に `plugin:<id>` と表示され、ここでは有効化/無効化できません。代わりにプラグイン自体を有効化/無効化してください。
**引数:**
- `<name>`: フック名（例: `session-memory`）
**例:**
```bash
openclaw hooks enable session-memory
```
**出力:**
```
✓ Enabled hook: 💾 session-memory
```
**動作:**
- フックが存在し、利用可能であることを確認します
- 設定内の `hooks.internal.entries.<name>.enabled = true` を更新します
- 設定をディスクに保存します
フックが `<workspace>/hooks/` から来ている場合、このオプトイン手順は
Gateway がそれを読み込む前に必須です。
**有効化後:**
- フックを再読み込みするために Gateway を再起動してください（macOS ではメニューバーアプリを再起動、開発環境では Gateway プロセスを再起動）。
## フックを無効化
```bash
openclaw hooks disable <name>
```
特定のフックを設定更新によって無効化します。
**引数:**
- `<name>`: フック名（例: `command-logger`）
**例:**
```bash
openclaw hooks disable command-logger
```
**出力:**
```
⏸ Disabled hook: 📝 command-logger
```
**無効化後:**
- フックを再読み込みするために Gateway を再起動してください
## 注意事項
- `openclaw hooks list --json`、`info --json`、`check --json` は、構造化 JSON を直接 stdout に書き出します。
- プラグイン管理のフックはここでは有効化または無効化できません。代わりに所有しているプラグインを有効化または無効化してください。
## フックパックをインストール
```bash
openclaw plugins install <package> # まず ClawHub、次に npm
openclaw plugins install <package> --pin # バージョン固定
openclaw plugins install <path> # ローカルパス
```
統一された plugins インストーラーを通じてフックパックをインストールします。
`openclaw hooks install` も互換エイリアスとして引き続き動作しますが、非推奨警告を表示し、
`openclaw plugins install` に転送されます。
npm spec は **レジストリ専用** です（パッケージ名 + オプションで **正確なバージョン** または
**dist-tag**）。Git/URL/file spec と semver 範囲は拒否されます。依存関係の
インストールは安全のため `--ignore-scripts` 付きで実行されます。
プレーン spec と `@latest` は安定トラックのままです。npm がこれらのいずれかを
プレリリースに解決した場合、OpenClaw は停止し、`@beta`/`@rc` のような
プレリリースタグまたは正確なプレリリースバージョンで明示的にオプトインするよう求めます。
**動作:**
- フックパックを `~/.openclaw/hooks/<id>` にコピーします
- インストールされたフックを `hooks.internal.entries.*` で有効化します
- インストールを `hooks.internal.installs` に記録します
**オプション:**
- `-l, --link`: コピーの代わりにローカルディレクトリをリンクします（`hooks.internal.load.extraDirs` に追加します）
- `--pin`: npm インストールを、解決済みの正確な `name@version` として `hooks.internal.installs` に記録します
**サポートされるアーカイブ:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
**例:**
```bash
# ローカルディレクトリ
openclaw plugins install ./my-hook-pack
# ローカルアーカイブ
openclaw plugins install ./my-hook-pack.zip
# NPM パッケージ
openclaw plugins install @openclaw/my-hook-pack
# コピーせずにローカルディレクトリをリンク
openclaw plugins install -l ./my-hook-pack
```
リンクされたフックパックは、ワークスペースフックではなく、
オペレーター設定ディレクトリからの managed フックとして扱われます。
## フックパックを更新
```bash
openclaw plugins update <id>
openclaw plugins update --all
```
統一された plugins アップデーターを通じて、追跡対象の npm ベースのフックパックを更新します。
`openclaw hooks update` も互換エイリアスとして引き続き動作しますが、非推奨警告を表示し、
`openclaw plugins update` に転送されます。
**オプション:**
- `--all`: 追跡対象のすべてのフックパックを更新します
- `--dry-run`: 書き込みを行わず、何が変わるかを表示します
保存済みの整合性ハッシュが存在し、取得したアーティファクトハッシュが変化している場合、
OpenClaw は警告を表示し、続行前に確認を求めます。CI/非対話実行でプロンプトを回避するには、
グローバル `--yes` を使用してください。
## バンドルされたフック
### session-memory
`/new` または `/reset` を実行したときに、セッションコンテキストをメモリに保存します。
**有効化:**
```bash
openclaw hooks enable session-memory
```
**出力:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
**参照:** [session-memory documentation](/automation/hooks#session-memory)
### bootstrap-extra-files
`agent:bootstrap` 中に追加の bootstrap ファイル（たとえばモノレポローカルの `AGENTS.md` / `TOOLS.md`）を注入します。
**有効化:**
```bash
openclaw hooks enable bootstrap-extra-files
```
**参照:** [bootstrap-extra-files documentation](/automation/hooks#bootstrap-extra-files)
### command-logger
すべてのコマンドイベントを一元化された監査ファイルに記録します。
**有効化:**
```bash
openclaw hooks enable command-logger
```
**出力:** `~/.openclaw/logs/commands.log`
**ログの表示:**
```bash
# 最近のコマンド
tail -n 20 ~/.openclaw/logs/commands.log
# 整形表示
cat ~/.openclaw/logs/commands.log | jq .
# アクションでフィルター
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
```
**参照:** [command-logger documentation](/automation/hooks#command-logger)
### boot-md
Gateway 起動時（チャネル起動後）に `BOOT.md` を実行します。
**イベント**: `gateway:startup`
**有効化**:
```bash
openclaw hooks enable boot-md
```
**参照:** [boot-md documentation](/automation/hooks#boot-md)

1843
docs/ja-JP/cli/index.md Normal file
View File

File diff suppressed because it is too large Load Diff

66
docs/ja-JP/cli/logs.md Normal file
View File

@ -0,0 +1,66 @@
---
read_when:
- Gatewayログをリモートで追跡したいとき（SSHなしで）
- ツール用にJSONログ行が必要なとき
summary: '`openclaw logs`のCLIリファレンス（RPC経由でGatewayログを追跡）'
title: logs
x-i18n:
generated_at: "2026-04-05T12:38:47Z"
model: gpt-5.4
provider: openai
source_hash: 238a52e31a9a332cab513ced049e92d032b03c50376895ce57dffa2ee7d1e4b4
source_path: cli/logs.md
workflow: 15
---
# `openclaw logs`
RPC経由でGatewayファイルログを追跡します（リモートモードで動作します）。
関連:
- ロギング概要: [Logging](/logging)
- Gateway CLI: [gateway](/cli/gateway)
## オプション
- `--limit <n>`: 返すログ行の最大数（デフォルト`200`）
- `--max-bytes <n>`: ログファイルから読み取る最大バイト数（デフォルト`250000`）
- `--follow`: ログストリームを追跡する
- `--interval <ms>`: 追跡中のポーリング間隔（デフォルト`1000`）
- `--json`: 行区切りJSONイベントを出力する
- `--plain`: スタイル付き書式なしのプレーンテキスト出力
- `--no-color`: ANSIカラーを無効にする
- `--local-time`: タイムスタンプをローカルタイムゾーンで表示する
## 共有Gateway RPCオプション
`openclaw logs`は標準のGatewayクライアントフラグも受け付けます。
- `--url <url>`: Gateway WebSocket URL
- `--token <token>`: Gatewayトークン
- `--timeout <ms>`: タイムアウト（ミリ秒、デフォルト`30000`）
- `--expect-final`: Gateway呼び出しがagent-backedの場合、最終応答を待機する
`--url`を渡す場合、CLIは設定や環境認証情報を自動適用しません。対象Gatewayで認証が必要な場合は、`--token`を明示的に含めてください。
## 例
```bash
openclaw logs
openclaw logs --follow
openclaw logs --follow --interval 2000
openclaw logs --limit 500 --max-bytes 500000
openclaw logs --json
openclaw logs --plain
openclaw logs --no-color
openclaw logs --limit 500
openclaw logs --local-time
openclaw logs --follow --local-time
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
```
## 注記
- タイムスタンプをローカルタイムゾーンで表示するには`--local-time`を使用してください。
- local loopback Gatewayがペアリングを要求した場合、`openclaw logs`は自動的に設定済みのローカルログファイルへフォールバックします。明示的な`--url`ターゲットでは、このフォールバックは使用されません。

508
docs/ja-JP/cli/mcp.md Normal file
View File

@ -0,0 +1,508 @@
---
read_when:
- Codex、Claude Code、または別の MCP クライアントを OpenClaw ベースのチャネルに接続するとき
- '`openclaw mcp serve` を実行するとき'
- OpenClaw に保存された MCP サーバー定義を管理するとき
summary: OpenClaw のチャネル会話を MCP 経由で公開し、保存済みの MCP サーバー定義を管理する
title: mcp
x-i18n:
generated_at: "2026-04-05T12:39:43Z"
model: gpt-5.4
provider: openai
source_hash: b35de9e14f96666eeca2f93c06cb214e691152f911d45ee778efe9cf5bf96cc2
source_path: cli/mcp.md
workflow: 15
---
# mcp
`openclaw mcp` には 2 つの役割があります。
- `openclaw mcp serve` で OpenClaw を MCP サーバーとして実行する
- `list`、`show`、
`set`、`unset` で、OpenClaw が所有する送信先 MCP サーバー定義を管理する
つまり:
- `serve` は、OpenClaw が MCP サーバーとして動作する経路です
- `list` / `show` / `set` / `unset` は、OpenClaw が MCP クライアント側の
レジストリとして動作し、後でそのランタイムが利用する可能性のある他の MCP サーバーを管理する経路です
OpenClaw がコーディングハーネス
セッション自体をホストし、そのランタイムを ACP 経由でルーティングする必要がある場合は、[`openclaw acp`](/cli/acp) を使ってください。
## OpenClaw を MCP サーバーとして使う
これは `openclaw mcp serve` の経路です。
## `serve` を使うべきとき
以下の場合は `openclaw mcp serve` を使ってください。
- Codex、Claude Code、または別の MCP クライアントが、
OpenClaw ベースのチャネル会話と直接やり取りする必要がある
- すでにローカルまたはリモートの OpenClaw Gateway があり、セッションがルーティングされている
- チャネルごとに別々のブリッジを実行するのではなく、
OpenClaw の各チャネルバックエンドを横断して動作する 1 つの MCP サーバーが欲しい
OpenClaw がコーディング
ランタイム自体をホストし、エージェントセッションを OpenClaw 内に保持する必要がある場合は、代わりに [`openclaw acp`](/cli/acp) を使ってください。
## 仕組み
`openclaw mcp serve` は stdio MCP サーバーを起動します。この
プロセスは MCP クライアントが所有します。クライアントが stdio セッションを開いている間、
ブリッジはローカルまたはリモートの OpenClaw Gateway に WebSocket で接続し、ルーティングされたチャネル
会話を MCP 経由で公開します。
ライフサイクル:
1. MCP クライアントが `openclaw mcp serve` を起動する
2. ブリッジが Gateway に接続する
3. ルーティングされたセッションが MCP の会話および transcript/history ツールとして利用可能になる
4. ブリッジ接続中はライブイベントがメモリ内にキューされる
5. Claude チャネルモードが有効な場合、同じセッションで
Claude 固有のプッシュ通知も受け取れる
重要な挙動:
- ライブキューの状態はブリッジ接続時点から始まる
- それ以前の transcript 履歴は `messages_read` で読み出す
- Claude のプッシュ通知は MCP セッションが生きている間だけ存在する
- クライアントが切断すると、ブリッジは終了し、ライブキューも消える
## クライアントモードを選ぶ
同じブリッジを 2 通りの方法で使えます。
- 汎用 MCP クライアント: 標準 MCP ツールのみ。`conversations_list`、
`messages_read`、`events_poll`、`events_wait`、`messages_send`、および
承認ツールを使います。
- Claude Code: 標準 MCP ツールに加えて Claude 固有のチャネルアダプターも使います。
`--claude-channel-mode on` を有効にするか、デフォルトの `auto` のままにします。
現時点では、`auto` は `on` と同じ動作です。まだクライアント機能検出は
ありません。
## `serve` が公開するもの
このブリッジは、既存の Gateway セッションルートメタデータを使って、チャネルに裏打ちされた
会話を公開します。OpenClaw がすでに次のような既知のルートを持つセッション状態を
保持している場合に、会話が表示されます。
- `channel`
- recipient または destination メタデータ
- 任意の `accountId`
- 任意の `threadId`
これにより、MCP クライアントは次のことを 1 か所で行えます。
- 最近のルーティング済み会話を一覧表示する
- 最近の transcript 履歴を読む
- 新しい受信イベントを待機する
- 同じルートを通じて返信を送る
- ブリッジ接続中に到着した承認要求を確認する
## 使用方法
```bash
# ローカル Gateway
openclaw mcp serve
# リモート Gateway
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# パスワード認証付きリモート Gateway
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
# 詳細なブリッジログを有効化
openclaw mcp serve --verbose
# Claude 固有のプッシュ通知を無効化
openclaw mcp serve --claude-channel-mode off
```
## ブリッジツール
現在のブリッジは以下の MCP ツールを公開します。
- `conversations_list`
- `conversation_get`
- `messages_read`
- `attachments_fetch`
- `events_poll`
- `events_wait`
- `messages_send`
- `permissions_list_open`
- `permissions_respond`
### `conversations_list`
Gateway セッション状態にすでにルートメタデータを持つ、最近のセッション裏打ち会話を一覧表示します。
便利なフィルター:
- `limit`
- `search`
- `channel`
- `includeDerivedTitles`
- `includeLastMessage`
### `conversation_get`
`session_key` によって 1 件の会話を返します。
### `messages_read`
1 件のセッション裏打ち会話に対する最近の transcript メッセージを読みます。
### `attachments_fetch`
1 件の transcript メッセージから非テキストのメッセージコンテンツブロックを抽出します。これは
transcript コンテンツ上のメタデータビューであり、独立した永続的な添付 blob ストアでは
ありません。
### `events_poll`
数値カーソル以降のキュー済みライブイベントを読み取ります。
### `events_wait`
次に一致するキュー済みイベントが到着するか、タイムアウトするまでロングポーリングします。
これは、Claude 固有のプッシュプロトコルなしで、汎用 MCP クライアントが
ほぼリアルタイムの配信を必要とする場合に使います。
### `messages_send`
セッションにすでに記録されている同じルートを通じてテキストを送信します。
現在の挙動:
- 既存の会話ルートが必要
- セッションの channel、recipient、account id、thread id を使う
- テキストのみ送信する
### `permissions_list_open`
ブリッジが Gateway に接続して以降に観測した、保留中の exec/plugin 承認要求を一覧表示します。
### `permissions_respond`
保留中の exec/plugin 承認要求 1 件を次のいずれかで処理します。
- `allow-once`
- `allow-always`
- `deny`
## イベントモデル
このブリッジは、接続中の間、メモリ内イベントキューを保持します。
現在のイベント型:
- `message`
- `exec_approval_requested`
- `exec_approval_resolved`
- `plugin_approval_requested`
- `plugin_approval_resolved`
- `claude_permission_request`
重要な制限:
- キューはライブ専用であり、MCP ブリッジ開始時点から始まる
- `events_poll` と `events_wait` は、それ自体では古い Gateway 履歴を
再生しない
- 永続的なバックログは `messages_read` で読む必要がある
## Claude チャネル通知
このブリッジは Claude 固有のチャネル通知も公開できます。これは
Claude Code チャネルアダプターに相当する OpenClaw 側の機能です。標準 MCP ツールは引き続き利用可能ですが、
ライブ受信メッセージは Claude 固有の MCP 通知としても到着できます。
フラグ:
- `--claude-channel-mode off`: 標準 MCP ツールのみ
- `--claude-channel-mode on`: Claude チャネル通知を有効化
- `--claude-channel-mode auto`: 現在のデフォルト。`on` と同じブリッジ動作
Claude チャネルモードが有効な場合、サーバーは Claude の experimental
capabilities を広告し、次を発行できます。
- `notifications/claude/channel`
- `notifications/claude/channel/permission`
現在のブリッジ挙動:
- 受信 `user` transcript メッセージは
`notifications/claude/channel` として転送される
- MCP 経由で受け取った Claude の権限要求はメモリ内で追跡される
- 後で関連会話が `yes abcde` または `no abcde` を送ると、ブリッジは
それを `notifications/claude/channel/permission` に変換する
- これらの通知はライブセッション専用であり、MCP クライアントが切断すると、
プッシュ先はなくなる
これは意図的にクライアント固有です。汎用 MCP クライアントは標準の
ポーリングツールに依存してください。
## MCP クライアント設定
stdio クライアント設定例:
```json
{
"mcpServers": {
"openclaw": {
"command": "openclaw",
"args": [
"mcp",
"serve",
"--url",
"wss://gateway-host:18789",
"--token-file",
"/path/to/gateway.token"
]
}
}
}
```
ほとんどの汎用 MCP クライアントでは、まず標準ツール画面から始め、
Claude モードは無視してください。Claude 固有の通知メソッドを実際に理解できる
クライアントに対してのみ Claude モードを有効にしてください。
## オプション
`openclaw mcp serve` がサポートするもの:
- `--url <url>`: Gateway WebSocket URL
- `--token <token>`: Gateway トークン
- `--token-file <path>`: ファイルからトークンを読み取る
- `--password <password>`: Gateway パスワード
- `--password-file <path>`: ファイルからパスワードを読み取る
- `--claude-channel-mode <auto|on|off>`: Claude 通知モード
- `-v`, `--verbose`: stderr に詳細ログを出す
可能であれば、インラインシークレットより `--token-file` または `--password-file` を推奨します。
## セキュリティと信頼境界
このブリッジはルーティングを新規作成しません。Gateway が
すでにルーティング方法を知っている会話だけを公開します。
つまり:
- 送信者 allowlist、ペアリング、チャネルレベルの信頼は、引き続き
基盤となる OpenClaw チャネル設定に属する
- `messages_send` は既存の保存済みルートを通じてのみ返信できる
- 承認状態は現在のブリッジセッションに対してのみライブ / メモリ内
- ブリッジ認証には、他のリモート Gateway クライアントと同様に
信頼できる Gateway トークンまたはパスワード制御を使うべき
`conversations_list` に会話が表示されない場合、通常の原因は
MCP 設定ではありません。基盤となる
Gateway セッションにルートメタデータがない、または不完全であることです。
## テスト
OpenClaw には、このブリッジ用の決定論的 Docker スモークが用意されています。
```bash
pnpm test:docker:mcp-channels
```
このスモークでは次を行います。
- シード済み Gateway コンテナーを起動する
- `openclaw mcp serve` を起動する 2 つ目のコンテナーを起動する
- 会話検出、transcript 読み取り、添付メタデータ読み取り、
ライブイベントキューの挙動、送信ルーティングを検証する
- 実際の stdio MCP ブリッジ上で Claude スタイルのチャネル通知と権限通知を検証する
これは、実際の
Telegram、Discord、または iMessage アカウントをテスト実行に接続せずに、ブリッジが動作することを証明するもっとも高速な方法です。
より広いテスト文脈については、[Testing](/help/testing) を参照してください。
## トラブルシューティング
### 会話が返ってこない
通常は、Gateway セッションがまだルーティング可能でないことを意味します。基盤となる
セッションに channel/provider、recipient、および任意の
account/thread ルートメタデータが保存されていることを確認してください。
### `events_poll` または `events_wait` が古いメッセージを取りこぼす
想定どおりです。ライブキューはブリッジ接続時点から始まります。古い transcript
履歴は `messages_read` で読んでください。
### Claude 通知が表示されない
以下をすべて確認してください。
- クライアントが stdio MCP セッションを開いたままにしていた
- `--claude-channel-mode` が `on` または `auto`
- クライアントが実際に Claude 固有の通知メソッドを理解できる
- 受信メッセージがブリッジ接続後に発生した
### 承認が表示されない
`permissions_list_open` が表示するのは、ブリッジ接続中に観測された承認要求のみです。これは
永続的な承認履歴 API ではありません。
## OpenClaw を MCP クライアントレジストリとして使う
これは `openclaw mcp list`、`show`、`set`、`unset` の経路です。
これらのコマンドは OpenClaw を MCP 経由で公開しません。OpenClaw config の
`mcp.servers` 配下にある、OpenClaw 所有の MCP
サーバー定義を管理します。
これらの保存済み定義は、後で OpenClaw が起動または設定するランタイム向けです。
たとえば組み込み Pi やその他のランタイムアダプターです。OpenClaw は定義を
中央に保存することで、それらのランタイムが独自に重複した
MCP サーバー一覧を保持しなくて済むようにします。
重要な挙動:
- これらのコマンドは OpenClaw config の読み書きだけを行う
- 対象の MCP サーバーには接続しない
- コマンド、URL、またはリモートトランスポートが
現時点で到達可能かどうかは検証しない
- ランタイムアダプターは、実行時に実際にサポートするトランスポート形状を決定する
## 保存済み MCP サーバー定義
OpenClaw は、OpenClaw 管理の MCP 定義を必要とする画面向けに、
config 内に軽量な MCP サーバーレジストリも保存します。
コマンド:
- `openclaw mcp list`
- `openclaw mcp show [name]`
- `openclaw mcp set <name> <json>`
- `openclaw mcp unset <name>`
注意:
- `list` はサーバー名をソートします。
- `show` は名前なしの場合、設定済みの MCP サーバーオブジェクト全体を出力します。
- `set` はコマンドライン上で 1 つの JSON オブジェクト値を受け取ります。
- `unset` は、指定したサーバーが存在しない場合に失敗します。
例:
```bash
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7
```
設定形状の例:
```json
{
"mcp": {
"servers": {
"context7": {
"command": "uvx",
"args": ["context7-mcp"]
},
"docs": {
"url": "https://mcp.example.com"
}
}
}
}
```
### Stdio トランスポート
ローカルの子プロセスを起動し、stdin/stdout 経由で通信します。
| Field | Description |
| -------------------------- | ----------------------------- |
| `command` | 起動する実行ファイル（必須） |
| `args` | コマンドライン引数の配列 |
| `env` | 追加の環境変数 |
| `cwd` / `workingDirectory` | プロセスの作業ディレクトリ |
### SSE / HTTP トランスポート
HTTP Server-Sent Events 経由でリモート MCP サーバーに接続します。
| Field | Description |
| --------------------- | ----------------------------------------------------- |
| `url` | リモートサーバーの HTTP または HTTPS URL（必須） |
| `headers` | 任意の HTTP ヘッダのキー・値マップ（例: 認証トークン） |
| `connectionTimeoutMs` | サーバーごとの接続タイムアウト（ミリ秒、任意） |
例:
```json
{
"mcp": {
"servers": {
"remote-tools": {
"url": "https://mcp.example.com",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
```
`url` 内の機微値（userinfo）と `headers` は、ログと
ステータス出力でマスクされます。
### Streamable HTTP トランスポート
`streamable-http` は、`sse` および `stdio` に加わる追加のトランスポートオプションです。リモート MCP サーバーとの双方向通信に HTTP ストリーミングを使用します。
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `url` | リモートサーバーの HTTP または HTTPS URL（必須） |
| `transport` | このトランスポートを選ぶには `"streamable-http"` を設定します。省略時は OpenClaw は `sse` を使います |
| `headers` | 任意の HTTP ヘッダのキー・値マップ（例: 認証トークン） |
| `connectionTimeoutMs` | サーバーごとの接続タイムアウト（ミリ秒、任意） |
例:
```json
{
"mcp": {
"servers": {
"streaming-tools": {
"url": "https://mcp.example.com/stream",
"transport": "streamable-http",
"connectionTimeoutMs": 10000,
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
```
これらのコマンドが管理するのは保存済み config のみです。チャネルブリッジを起動したり、
ライブ MCP クライアントセッションを開いたり、対象サーバーが到達可能であることを証明したりはしません。
## 現在の制限
このページは、現時点で出荷されているブリッジを説明しています。
現在の制限:
- 会話検出は既存の Gateway セッションルートメタデータに依存する
- Claude 固有アダプター以外に汎用プッシュプロトコルはない
- まだメッセージ編集ツールやリアクションツールはない
- HTTP/SSE/streamable-http トランスポートは単一のリモートサーバーに接続する。まだ upstream の多重化はない
- `permissions_list_open` には、ブリッジ接続中に
観測された承認のみが含まれる

142
docs/ja-JP/cli/memory.md Normal file
View File

@ -0,0 +1,142 @@
---
read_when:
- セマンティックメモリをインデックス化または検索したいとき
- メモリの利用可否やインデックス化をデバッグしているとき
- 想起された短期メモリを `MEMORY.md` に昇格したいとき
summary: '`openclaw memory` の CLI リファレンス（status/index/search/promote）'
title: memory
x-i18n:
generated_at: "2026-04-05T12:39:05Z"
model: gpt-5.4
provider: openai
source_hash: a89e3a819737bb63521128ae63d9e25b5cd9db35c3ea4606d087a8ad48b41eab
source_path: cli/memory.md
workflow: 15
---
# `openclaw memory`
セマンティックメモリのインデックス化と検索を管理します。
アクティブなメモリプラグインによって提供されます（デフォルト: `memory-core`; 無効化するには `plugins.slots.memory = "none"` を設定）。
関連:
- メモリの概念: [Memory](/concepts/memory)
- プラグイン: [Plugins](/tools/plugin)
## 例
```bash
openclaw memory status
openclaw memory status --deep
openclaw memory status --fix
openclaw memory index --force
openclaw memory search "meeting notes"
openclaw memory search --query "deployment" --max-results 20
openclaw memory promote --limit 10 --min-score 0.75
openclaw memory promote --apply
openclaw memory promote --json --min-recall-count 0 --min-unique-queries 0
openclaw memory status --json
openclaw memory status --deep --index
openclaw memory status --deep --index --verbose
openclaw memory status --agent main
openclaw memory index --agent main --verbose
```
## オプション
`memory status` と `memory index`:
- `--agent <id>`: 単一の agent に限定します。これを指定しない場合、これらのコマンドは設定された各 agent に対して実行されます。agent list が設定されていない場合は、デフォルト agent にフォールバックします。
- `--verbose`: プローブおよびインデックス化中に詳細ログを出力します。
`memory status`:
- `--deep`: ベクトル + 埋め込みの利用可否をプローブします。
- `--index`: ストアが dirty の場合に再インデックス化を実行します（`--deep` を暗黙的に含みます）。
- `--fix`: 古い recall lock を修復し、promotion metadata を正規化します。
- `--json`: JSON 出力を表示します。
`memory index`:
- `--force`: 完全な再インデックス化を強制します。
`memory search`:
- クエリ入力: 位置引数の `[query]` または `--query <text>` のいずれかを渡します。
- 両方が指定された場合は、`--query` が優先されます。
- どちらも指定されていない場合、コマンドはエラーで終了します。
- `--agent <id>`: 単一の agent に限定します（デフォルト: デフォルト agent）。
- `--max-results <n>`: 返す結果数を制限します。
- `--min-score <n>`: 低スコアの一致を除外します。
- `--json`: JSON 結果を表示します。
`memory promote`:
短期メモリの昇格をプレビューして適用します。
```bash
openclaw memory promote [--apply] [--limit <n>] [--include-promoted]
```
- `--apply` -- `MEMORY.md` に昇格内容を書き込みます（デフォルト: プレビューのみ）。
- `--limit <n>` -- 表示する候補数の上限を設定します。
- `--include-promoted` -- 以前のサイクルですでに昇格済みのエントリも含めます。
完全なオプション:
- `memory/YYYY-MM-DD.md` から短期候補をランク付けします。使用するのは重み付き recall シグナル（`frequency`、`relevance`、`query diversity`、`recency`）です。
- `memory_search` が daily-memory ヒットを返したときに記録された recall event を使用します。
- オプションの自動 dreaming モード: `plugins.entries.memory-core.config.dreaming.mode` が `core`、`deep`、または `rem` の場合、`memory-core` はバックグラウンドで promotion をトリガーする cron job を自動管理します（手動の `openclaw cron add` は不要）。
- `--agent <id>`: 単一の agent に限定します（デフォルト: デフォルト agent）。
- `--limit <n>`: 返す/適用する候補数の上限。
- `--min-score <n>`: 重み付き promotion スコアの最小値。
- `--min-recall-count <n>`: 候補に必要な recall count の最小値。
- `--min-unique-queries <n>`: 候補に必要な異なるクエリ数の最小値。
- `--apply`: 選択した候補を `MEMORY.md` に追記し、promoted としてマークします。
- `--include-promoted`: すでに promoted 済みの候補も出力に含めます。
- `--json`: JSON 出力を表示します。
## Dreaming（実験的）
Dreaming は、メモリに対する夜間の振り返り処理です。システムが日中に想起された内容を見直し、長期的に保持する価値があるものを判断することから、「dreaming」と呼ばれています。
- オプトイン方式で、デフォルトでは無効です。
- `plugins.entries.memory-core.config.dreaming.mode` で有効化します。
- チャットから `/dreaming off|core|rem|deep` でモードを切り替えられます。各モードの動作を見るには `/dreaming`（または `/dreaming options`）を実行してください。
- 有効化すると、`memory-core` は管理対象の cron job を自動的に作成して維持します。
- dreaming を有効のまま自動 promotion を事実上停止したい場合は、`dreaming.limit` を `0` に設定してください。
- ランキングには重み付きシグナルを使用します: recall frequency、retrieval relevance、query diversity、temporal recency（最近の recall は時間とともに減衰します）。
- `MEMORY.md` への promotion は品質しきい値を満たした場合にのみ行われるため、長期メモリは単発の詳細を蓄積するのではなく、高シグナルな状態を保てます。
デフォルトモードのプリセット:
- `core`: 毎日 `0 3 * * *`、`minScore=0.75`、`minRecallCount=3`、`minUniqueQueries=2`
- `deep`: 12 時間ごと（`0 */12 * * *`）、`minScore=0.8`、`minRecallCount=3`、`minUniqueQueries=3`
- `rem`: 6 時間ごと（`0 */6 * * *`）、`minScore=0.85`、`minRecallCount=4`、`minUniqueQueries=3`
例:
```json
{
"plugins": {
"entries": {
"memory-core": {
"config": {
"dreaming": {
"mode": "core"
}
}
}
}
}
}
```
注記:
- `memory index --verbose` はフェーズごとの詳細（provider、model、source、batch activity）を出力します。
- `memory status` には、`memorySearch.extraPaths` で設定された追加パスも含まれます。
- 実質的にアクティブなメモリのリモート API key フィールドが SecretRef として設定されている場合、このコマンドはアクティブな gateway スナップショットからそれらの値を解決します。gateway が利用できない場合、コマンドは即座に失敗します。
- Gateway バージョン差異に関する注記: このコマンド経路には `secrets.resolve` をサポートする gateway が必要です。古い gateway は unknown-method エラーを返します。
- dreaming の実行頻度はデフォルトで各モードのプリセットスケジュールに従います。`plugins.entries.memory-core.config.dreaming.frequency` を cron 式（例: `0 3 * * *`）として設定することで頻度を上書きし、`timezone`、`limit`、`minScore`、`minRecallCount`、`minUniqueQueries` で微調整できます。

307
docs/ja-JP/cli/message.md Normal file
View File

@ -0,0 +1,307 @@
---
read_when:
- message CLI アクションを追加または変更するとき
- 送信チャネルの動作を変更するとき
summary: '`openclaw message` の CLI リファレンス（send + チャネルアクション）'
title: message
x-i18n:
generated_at: "2026-04-05T12:39:18Z"
model: gpt-5.4
provider: openai
source_hash: b70f36189d028d59db25cd8b39d7c67883eaea71bea2358ee6314eec6cd2fa51
source_path: cli/message.md
workflow: 15
---
# `openclaw message`
メッセージ送信とチャネルアクションのための単一の送信コマンド
（Discord/Google Chat/iMessage/Matrix/Mattermost（plugin）/Microsoft Teams/Signal/Slack/Telegram/WhatsApp）。
## 使用方法
```
openclaw message <subcommand> [flags]
```
チャネル選択:
- 2 つ以上のチャネルが設定されている場合、`--channel` が必須です。
- ちょうど 1 つのチャネルだけが設定されている場合、それがデフォルトになります。
- 値: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp`（Mattermost には plugin が必要）
ターゲット形式（`--target`）:
- WhatsApp: E.164 または group JID
- Telegram: chat id または `@username`
- Discord: `channel:<id>` または `user:<id>`（または `<@id>` メンション。生の数値 id はチャネルとして扱われます）
- Google Chat: `spaces/<spaceId>` または `users/<userId>`
- Slack: `channel:<id>` または `user:<id>`（生の channel id も受け付けます）
- Mattermost（plugin）: `channel:<id>`、`user:<id>`、または `@username`（プレフィックスなし id はチャネルとして扱われます）
- Signal: `+E.164`、`group:<id>`、`signal:+E.164`、`signal:group:<id>`、または `username:<name>`/`u:<name>`
- iMessage: handle、`chat_id:<id>`、`chat_guid:<guid>`、または `chat_identifier:<id>`
- Matrix: `@user:server`、`!room:server`、または `#alias:server`
- Microsoft Teams: conversation id（`19:...@thread.tacv2`）または `conversation:<id>` または `user:<aad-object-id>`
名前解決:
- サポート対象プロバイダー（Discord/Slack など）では、`Help` や `#help` のようなチャネル名は directory cache 経由で解決されます。
- cache miss の場合、プロバイダーが対応していれば、OpenClaw は live directory lookup を試行します。
## 共通フラグ
- `--channel <name>`
- `--account <id>`
- `--target <dest>`（send/poll/read などのターゲットチャネルまたはユーザー）
- `--targets <name>`（繰り返し指定。broadcast のみ）
- `--json`
- `--dry-run`
- `--verbose`
## SecretRef の挙動
- `openclaw message` は、選択したアクションを実行する前に、サポート対象チャネルの SecretRef を解決します。
- 解決は可能な限りアクティブなアクションターゲットにスコープされます:
- `--channel` が設定されている場合のチャネルスコープ（または `discord:...` のようなプレフィックス付きターゲットから推定される場合）
- `--account` が設定されている場合のアカウントスコープ（チャネル globals + 選択したアカウント surface）
- `--account` が省略されている場合、OpenClaw は `default` アカウントの SecretRef スコープを強制しません
- 関連のないチャネル上の未解決 SecretRef は、ターゲット指定されたメッセージアクションを妨げません。
- 選択したチャネル/アカウントの SecretRef が未解決の場合、そのアクションではコマンドは fail-closed します。
## アクション
### コア
- `send`
- チャネル: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（plugin）/Signal/iMessage/Matrix/Microsoft Teams
- 必須: `--target`、および `--message` または `--media`
- 任意: `--media`、`--interactive`、`--buttons`、`--components`、`--card`、`--reply-to`、`--thread-id`、`--gif-playback`、`--force-document`、`--silent`
- 共通 interactive payload: `--interactive` は、対応している場合にチャネルネイティブの interactive JSON payload を送信します
- Telegram のみ: `--buttons`（`channels.telegram.capabilities.inlineButtons` で許可されている必要があります）
- Telegram のみ: `--force-document`（Telegram の圧縮を避けるために画像と GIF を document として送信）
- Telegram のみ: `--thread-id`（forum topic id）
- Slack のみ: `--thread-id`（thread timestamp。`--reply-to` は同じフィールドを使います）
- Discord のみ: `--components` JSON payload
- Adaptive Card 対応チャネル: 対応している場合の `--card` JSON payload
- Telegram + Discord: `--silent`
- WhatsApp のみ: `--gif-playback`
- `poll`
- チャネル: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
- 必須: `--target`、`--poll-question`、`--poll-option`（繰り返し）
- 任意: `--poll-multi`
- Discord のみ: `--poll-duration-hours`、`--silent`、`--message`
- Telegram のみ: `--poll-duration-seconds`（5-600）、`--silent`、`--poll-anonymous` / `--poll-public`、`--thread-id`
- `react`
- チャネル: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
- 必須: `--message-id`、`--target`
- 任意: `--emoji`、`--remove`、`--participant`、`--from-me`、`--target-author`、`--target-author-uuid`
- 注記: `--remove` には `--emoji` が必要です（対応している場合に自分のリアクションを消去するには `--emoji` を省略します。詳細は /tools/reactions を参照）
- WhatsApp のみ: `--participant`、`--from-me`
- Signal グループリアクション: `--target-author` または `--target-author-uuid` が必須
- `reactions`
- チャネル: Discord/Google Chat/Slack/Matrix
- 必須: `--message-id`、`--target`
- 任意: `--limit`
- `read`
- チャネル: Discord/Slack/Matrix
- 必須: `--target`
- 任意: `--limit`、`--before`、`--after`
- Discord のみ: `--around`
- `edit`
- チャネル: Discord/Slack/Matrix
- 必須: `--message-id`、`--message`、`--target`
- `delete`
- チャネル: Discord/Slack/Telegram/Matrix
- 必須: `--message-id`、`--target`
- `pin` / `unpin`
- チャネル: Discord/Slack/Matrix
- 必須: `--message-id`、`--target`
- `pins`（一覧）
- チャネル: Discord/Slack/Matrix
- 必須: `--target`
- `permissions`
- チャネル: Discord/Matrix
- 必須: `--target`
- Matrix のみ: Matrix encryption が有効で verification action が許可されている場合に利用可能
- `search`
- チャネル: Discord
- 必須: `--guild-id`、`--query`
- 任意: `--channel-id`、`--channel-ids`（繰り返し）、`--author-id`、`--author-ids`（繰り返し）、`--limit`
### スレッド
- `thread create`
- チャネル: Discord
- 必須: `--thread-name`、`--target`（channel id）
- 任意: `--message-id`、`--message`、`--auto-archive-min`
- `thread list`
- チャネル: Discord
- 必須: `--guild-id`
- 任意: `--channel-id`、`--include-archived`、`--before`、`--limit`
- `thread reply`
- チャネル: Discord
- 必須: `--target`（thread id）、`--message`
- 任意: `--media`、`--reply-to`
### 絵文字
- `emoji list`
- Discord: `--guild-id`
- Slack: 追加フラグなし
- `emoji upload`
- チャネル: Discord
- 必須: `--guild-id`、`--emoji-name`、`--media`
- 任意: `--role-ids`（繰り返し）
### ステッカー
- `sticker send`
- チャネル: Discord
- 必須: `--target`、`--sticker-id`（繰り返し）
- 任意: `--message`
- `sticker upload`
- チャネル: Discord
- 必須: `--guild-id`、`--sticker-name`、`--sticker-desc`、`--sticker-tags`、`--media`
### ロール / チャネル / メンバー / Voice
- `role info`（Discord）: `--guild-id`
- `role add` / `role remove`（Discord）: `--guild-id`、`--user-id`、`--role-id`
- `channel info`（Discord）: `--target`
- `channel list`（Discord）: `--guild-id`
- `member info`（Discord/Slack）: `--user-id`（Discord ではさらに `--guild-id`）
- `voice status`（Discord）: `--guild-id`、`--user-id`
### イベント
- `event list`（Discord）: `--guild-id`
- `event create`（Discord）: `--guild-id`、`--event-name`、`--start-time`
- 任意: `--end-time`、`--desc`、`--channel-id`、`--location`、`--event-type`
### モデレーション（Discord）
- `timeout`: `--guild-id`、`--user-id`（任意で `--duration-min` または `--until`。どちらも省略すると timeout を解除）
- `kick`: `--guild-id`、`--user-id`（+ `--reason`）
- `ban`: `--guild-id`、`--user-id`（+ `--delete-days`、`--reason`）
- `timeout` でも `--reason` をサポートします
### Broadcast
- `broadcast`
- チャネル: 設定済みの任意のチャネル。すべてのプロバイダーを対象にするには `--channel all` を使います
- 必須: `--targets <target...>`
- 任意: `--message`、`--media`、`--dry-run`
## 例
Discord で返信を送信する:
```
openclaw message send --channel discord \
--target channel:123 --message "hi" --reply-to 456
```
components 付きの Discord メッセージを送信する:
```
openclaw message send --channel discord \
--target channel:123 --message "Choose:" \
--components '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve","style":"success"},{"label":"Decline","style":"danger"}]}]}'
```
完全な schema については [Discord components](/channels/discord#interactive-components) を参照してください。
共通 interactive payload を送信する:
```bash
openclaw message send --channel googlechat --target spaces/AAA... \
--message "Choose:" \
--interactive '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve"},{"label":"Decline"}]}]}'
```
Discord poll を作成する:
```
openclaw message poll --channel discord \
--target channel:123 \
--poll-question "Snack?" \
--poll-option Pizza --poll-option Sushi \
--poll-multi --poll-duration-hours 48
```
Telegram poll を作成する（2 分後に自動終了）:
```
openclaw message poll --channel telegram \
--target @mychat \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi \
--poll-duration-seconds 120 --silent
```
Teams の proactive message を送信する:
```
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 --message "hi"
```
Teams poll を作成する:
```
openclaw message poll --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi
```
Slack でリアクションする:
```
openclaw message react --channel slack \
--target C123 --message-id 456 --emoji "✅"
```
Signal グループでリアクションする:
```
openclaw message react --channel signal \
--target signal:group:abc123 --message-id 1737630212345 \
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
```
Telegram のインラインボタンを送信する:
```
openclaw message send --channel telegram --target @mychat --message "Choose:" \
--buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
```
Teams Adaptive Card を送信する:
```bash
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Status update"}]}'
```
Telegram の画像を圧縮回避のため document として送信する:
```bash
openclaw message send --channel telegram --target @mychat \
--media ./diagram.png --force-document
```

127
docs/ja-JP/cli/models.md Normal file
View File

@ -0,0 +1,127 @@
---
read_when:
- デフォルトモデルを変更したい、またはプロバイダーの認証ステータスを確認したいとき
- 利用可能なモデル/プロバイダーをスキャンし、認証プロファイルをデバッグしたいとき
summary: '`openclaw models`のCLIリファレンス（status/list/set/scan、alias、fallback、auth）'
title: models
x-i18n:
generated_at: "2026-04-05T12:39:14Z"
model: gpt-5.4
provider: openai
source_hash: 04ba33181d49b6bbf3b5d5fa413aa6b388c9f29fb9d4952055d68c79f7bcfea0
source_path: cli/models.md
workflow: 15
---
# `openclaw models`
モデルの検出、スキャン、設定（デフォルトモデル、fallback、認証プロファイル）。
関連:
- Providers + models: [Models](/providers/models)
- プロバイダー認証セットアップ: [はじめに](/ja-JP/start/getting-started)
## 一般的なコマンド
```bash
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status`は、解決済みのデフォルト/fallbackに加えて認証の概要を表示します。
プロバイダー使用量スナップショットが利用可能な場合、OAuth/APIキーのステータスセクションには
プロバイダーの使用ウィンドウとクォータスナップショットが含まれます。
現在の使用ウィンドウ対応プロバイダー: Anthropic、GitHub Copilot、Gemini CLI、OpenAI
Codex、MiniMax、Xiaomi、z.ai。使用量認証は、利用可能な場合はプロバイダー固有のフックから取得されます。利用できない場合、OpenClawはauth profiles、env、またはconfigに一致するOAuth/APIキー認証情報へフォールバックします。
各設定済みプロバイダープロファイルに対して実際の認証probeを実行するには`--probe`を追加します。
probeは実際のリクエストです（トークンを消費し、レート制限を引き起こす可能性があります）。
設定済みagentのモデル/認証状態を確認するには`--agent <id>`を使用します。省略時は、
設定されていれば`OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`を使用し、そうでなければ
設定済みのデフォルトagentを使用します。
Probe行は、auth profiles、env認証情報、または`models.json`から取得される場合があります。
注記:
- `models set <model-or-alias>`は`provider/model`またはaliasを受け付けます。
- モデル参照は**最初の**`/`で分割して解析されます。モデルID自体に`/`が含まれる場合（OpenRouter形式）、プロバイダープレフィックスを含めてください（例: `openrouter/moonshotai/kimi-k2`）。
- プロバイダーを省略した場合、OpenClawはまず入力をaliasとして解決し、次にその正確なモデルIDに対する一意なconfigured-provider一致として解決し、それでもだめなら非推奨警告付きで設定済みのデフォルトプロバイダーにフォールバックします。
そのプロバイダーが設定済みのデフォルトモデルをもう公開していない場合、OpenClawは古くなった削除済みプロバイダーデフォルトを表示する代わりに、最初の設定済みprovider/modelへフォールバックします。
- `models status`の認証出力では、秘密としてマスクする代わりに、機密でないプレースホルダーに対して`marker(<value>)`が表示される場合があります（例: `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`）。
### `models status`
オプション:
- `--json`
- `--plain`
- `--check`（終了コード 1=期限切れ/不足、2=期限間近）
- `--probe`（設定済みauth profilesのライブprobe）
- `--probe-provider <name>`（1つのプロバイダーをprobe）
- `--probe-profile <id>`（繰り返し指定またはカンマ区切りのprofile id）
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>`（設定済みagent id。`OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`を上書き）
Probeステータスの分類:
- `ok`
- `auth`
- `rate_limit`
- `billing`
- `timeout`
- `format`
- `unknown`
- `no_model`
想定されるprobe詳細/理由コード:
- `excluded_by_auth_order`: 保存済みprofileは存在するが、明示的な
`auth.order.<provider>`に含まれていないため、probeは試行せず除外を報告します。
- `missing_credential`、`invalid_expires`、`expired`、`unresolved_ref`:
profileは存在するが、対象外または解決不能です。
- `no_model`: プロバイダー認証は存在するが、そのプロバイダーに対してprobe可能なモデル候補をOpenClawが解決できませんでした。
## Alias + fallback
```bash
openclaw models aliases list
openclaw models fallbacks list
```
## 認証プロファイル
```bash
openclaw models auth add
openclaw models auth login --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```
`models auth add`は対話型の認証ヘルパーです。選択したプロバイダーに応じて、
プロバイダー認証フロー（OAuth/APIキー）を起動することも、手動トークン貼り付けへ案内することもできます。
`models auth login`はプロバイダーpluginの認証フロー（OAuth/APIキー）を実行します。どのプロバイダーがインストールされているかは`openclaw plugins list`で確認できます。
例:
```bash
openclaw models auth login --provider anthropic --method cli --set-default
openclaw models auth login --provider openai-codex --set-default
```
注記:
- `login --provider anthropic --method cli --set-default`はローカルのClaude
CLIログインを再利用し、Anthropicのメインデフォルトモデル経路を正規の
`claude-cli/claude-*`参照に書き換えます。
- `setup-token`および`paste-token`は、トークン認証メソッドを公開しているプロバイダー向けの汎用トークンコマンドとして引き続き利用できます。
- `setup-token`には対話型TTYが必要で、そのプロバイダーのトークン認証メソッドを実行します（プロバイダーが公開している場合は、その`setup-token`メソッドがデフォルト）。
- `paste-token`は、別の場所または自動化から生成されたトークン文字列を受け付けます。
- `paste-token`には`--provider`が必要で、トークン値の入力を求め、`--profile-id`を渡さない限り、デフォルトprofile idの`<provider>:manual`へ書き込みます。
- `paste-token --expires-in <duration>`は、`365d`や`12h`のような相対期間から絶対的なトークン有効期限を保存します。
- Anthropic課金に関する注記: Anthropicの公開CLIドキュメントに基づき、Claude Code CLI fallbackはローカルのユーザー管理自動化であれば許可されている可能性が高いと私たちは考えています。ただし、Anthropicのサードパーティーハーネスポリシーには、外部製品でのサブスクリプション裏付け利用に関して十分な曖昧さがあるため、本番環境には推奨しません。Anthropicはさらに、**2026年4月4日 午後12:00 PT / 午後8:00 BST**にOpenClawユーザーへ、**OpenClaw**のClaudeログイン経路はサードパーティーハーネス利用として扱われ、サブスクリプションとは別請求の**Extra Usage**が必要であると通知しました。
- Anthropicの`setup-token` / `paste-token`は、レガシー/手動のOpenClaw経路として再び利用可能です。この経路には**Extra Usage**が必要であるとAnthropicがOpenClawユーザーに通知したことを前提に使用してください。

141
docs/ja-JP/cli/node.md Normal file
View File

@ -0,0 +1,141 @@
---
read_when:
- ヘッドレスノードホストを実行しているとき
- '`system.run`のためにmacOS以外のノードをペアリングしているとき'
summary: '`openclaw node`のCLIリファレンス（ヘッドレスノードホスト）'
title: node
x-i18n:
generated_at: "2026-04-05T12:39:10Z"
model: gpt-5.4
provider: openai
source_hash: 6123b33ec46f2b85f2c815947435ac91bbe84456165ff0e504453356da55b46d
source_path: cli/node.md
workflow: 15
---
# `openclaw node`
Gateway WebSocketに接続し、このマシン上で
`system.run` / `system.which`を公開する**ヘッドレスノードホスト**を実行します。
## なぜノードホストを使うのか
ノードホストは、ネットワーク内の**他のマシンでコマンドを実行**したいが、
そのマシンに完全なmacOSコンパニオンアプリをインストールしたくない場合に使用します。
よくある使用例:
- リモートのLinux/Windowsマシン（ビルドサーバー、ラボマシン、NAS）でコマンドを実行する。
- execをGateway上で**サンドボックス化**したまま、承認済みの実行を他のホストへ委譲する。
- 自動化やCIノード向けに、軽量でヘッドレスな実行ターゲットを提供する。
実行は引き続き、ノードホスト上の**exec承認**およびエージェントごとの許可リストで保護されるため、
コマンドアクセスを限定的かつ明示的に維持できます。
## ブラウザープロキシ（ゼロ設定）
ノード上で`browser.enabled`が無効化されていない場合、ノードホストは自動的にブラウザープロキシを公開します。これにより、追加設定なしでエージェントがそのノード上のブラウザー自動化を利用できます。
デフォルトでは、このプロキシはノードの通常のブラウザープロファイルサーフェスを公開します。`nodeHost.browserProxy.allowProfiles`を設定すると、プロキシは制限的になります。
許可リストにないプロファイル指定は拒否され、永続プロファイルの
作成/削除ルートはプロキシ経由でブロックされます。
必要に応じてノード側で無効化してください。
```json5
{
nodeHost: {
browserProxy: {
enabled: false,
},
},
}
```
## 実行（フォアグラウンド）
```bash
openclaw node run --host <gateway-host> --port 18789
```
オプション:
- `--host <host>`: Gateway WebSocketホスト（デフォルト: `127.0.0.1`）
- `--port <port>`: Gateway WebSocketポート（デフォルト: `18789`）
- `--tls`: Gateway接続にTLSを使用する
- `--tls-fingerprint <sha256>`: 期待されるTLS証明書フィンガープリント（sha256）
- `--node-id <id>`: ノードIDを上書きする（ペアリングトークンをクリア）
- `--display-name <name>`: ノード表示名を上書きする
## ノードホスト用Gateway認証
`openclaw node run`および`openclaw node install`は、設定/環境変数からGateway認証を解決します（ノードコマンドには`--token`/`--password`フラグはありません）。
- 最初に`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`を確認します。
- 次にローカル設定のフォールバック: `gateway.auth.token` / `gateway.auth.password`。
- ローカルモードでは、ノードホストは意図的に`gateway.remote.token` / `gateway.remote.password`を継承しません。
- `gateway.auth.token` / `gateway.auth.password`がSecretRef経由で明示的に設定されていて未解決の場合、ノード認証解決はfail-closedになります（リモートフォールバックによるマスキングなし）。
- `gateway.mode=remote`では、remoteクライアントフィールド（`gateway.remote.token` / `gateway.remote.password`）もremote優先順位ルールに従って対象になります。
- ノードホスト認証解決は`OPENCLAW_GATEWAY_*`環境変数のみを尊重します。
## サービス（バックグラウンド）
ヘッドレスノードホストをユーザーサービスとしてインストールします。
```bash
openclaw node install --host <gateway-host> --port 18789
```
オプション:
- `--host <host>`: Gateway WebSocketホスト（デフォルト: `127.0.0.1`）
- `--port <port>`: Gateway WebSocketポート（デフォルト: `18789`）
- `--tls`: Gateway接続にTLSを使用する
- `--tls-fingerprint <sha256>`: 期待されるTLS証明書フィンガープリント（sha256）
- `--node-id <id>`: ノードIDを上書きする（ペアリングトークンをクリア）
- `--display-name <name>`: ノード表示名を上書きする
- `--runtime <runtime>`: サービスランタイム（`node`または`bun`）
- `--force`: すでにインストール済みの場合は再インストール/上書きする
サービス管理:
```bash
openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall
```
フォアグラウンドのノードホスト（サービスなし）には`openclaw node run`を使用してください。
サービスコマンドは、機械可読な出力のために`--json`を受け付けます。
## ペアリング
最初の接続では、Gateway上に保留中のデバイスペアリング要求（`role: node`）が作成されます。
次のコマンドで承認してください。
```bash
openclaw devices list
openclaw devices approve <requestId>
```
ノードが変更された認証詳細（role/scopes/public key）でペアリングを再試行すると、
以前の保留要求は置き換えられ、新しい`requestId`が作成されます。
承認前にもう一度`openclaw devices list`を実行してください。
ノードホストは、ノードID、トークン、表示名、Gateway接続情報を
`~/.openclaw/node.json`に保存します。
## Exec承認
`system.run`はローカルのexec承認によって制御されます。
- `~/.openclaw/exec-approvals.json`
- [Exec approvals](/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>`（Gatewayから編集）
承認済みの非同期ノードexecでは、OpenClawはプロンプト前に正規の`systemRunPlan`
を準備します。その後の承認済み`system.run`転送では、その保存済み
planを再利用するため、承認要求作成後に`command`/`cwd`/`session`フィールドを編集しても、
ノードが実行する内容を変更するのではなく拒否されます。

72
docs/ja-JP/cli/nodes.md Normal file
View File

@ -0,0 +1,72 @@
---
read_when:
- ペアリング済みノード（camera、screen、canvas）を管理しているとき
- リクエストを承認したりノードコマンドを呼び出したりする必要があるとき
summary: '`openclaw nodes` の CLI リファレンス（status、pairing、invoke、camera/canvas/screen）'
title: nodes
x-i18n:
generated_at: "2026-04-05T12:39:18Z"
model: gpt-5.4
provider: openai
source_hash: 1ce3095591c4623ad18e3eca8d8083e5c10266fbf94afea2d025f0ba8093a175
source_path: cli/nodes.md
workflow: 15
---
# `openclaw nodes`
ペアリング済みノード（デバイス）を管理し、ノード機能を呼び出します。
関連:
- ノード概要: [Nodes](/nodes)
- Camera: [Camera nodes](/nodes/camera)
- 画像: [Image nodes](/nodes/images)
共通オプション:
- `--url`, `--token`, `--timeout`, `--json`
## よく使うコマンド
```bash
openclaw nodes list
openclaw nodes list --connected
openclaw nodes list --last-connected 24h
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes rename --node <id|name|ip> --name <displayName>
openclaw nodes status
openclaw nodes status --connected
openclaw nodes status --last-connected 24h
```
`nodes list` は pending/paired のテーブルを表示します。paired の行には、直近の接続からの経過時間（Last Connect）が含まれます。
現在接続中のノードだけを表示するには `--connected` を使います。`--last-connected <duration>` を使うと、
指定した期間内に接続したノードに絞り込めます（例: `24h`、`7d`）。
承認に関する注記:
- `openclaw nodes pending` に必要なのは pairing スコープのみです。
- `openclaw nodes approve <requestId>` は、保留中リクエストに応じて追加のスコープ要件を継承します。
- コマンドなしのリクエスト: pairing のみ
- exec 以外のノードコマンド: pairing + write
- `system.run` / `system.run.prepare` / `system.which`: pairing + admin
## 呼び出し
```bash
openclaw nodes invoke --node <id|name|ip> --command <command> --params <json>
```
呼び出しフラグ:
- `--params <json>`: JSON オブジェクト文字列（デフォルト `{}`）。
- `--invoke-timeout <ms>`: ノード呼び出しタイムアウト（デフォルト `15000`）。
- `--idempotency-key <key>`: 任意の idempotency key。
- `system.run` と `system.run.prepare` はここではブロックされます。シェル実行には `host=node` を指定した `exec` tool を使用してください。
ノード上でシェル実行を行うには、`openclaw nodes run` ではなく `host=node` を指定した `exec` tool を使ってください。
`nodes` CLI は現在、機能中心になっています。直接 RPC を行う `nodes invoke` に加え、pairing、camera、
screen、location、canvas、notification を扱います。

177
docs/ja-JP/cli/onboard.md Normal file
View File

@ -0,0 +1,177 @@
---
read_when:
- Gateway、workspace、認証、チャネル、Skills のガイド付きセットアップを使いたい
summary: '`openclaw onboard` の CLI リファレンス（対話型オンボーディング）'
title: onboard
x-i18n:
generated_at: "2026-04-05T12:39:39Z"
model: gpt-5.4
provider: openai
source_hash: 6db61c8002c9e82e48ff44f72e176b58ad85fad5cb8434687455ed40add8cc2a
source_path: cli/onboard.md
workflow: 15
---
# `openclaw onboard`
ローカルまたはリモートの Gateway セットアップ向けの対話型オンボーディングです。
## 関連ガイド
- CLI オンボーディングハブ: [Onboarding (CLI)](/ja-JP/start/wizard)
- オンボーディング概要: [Onboarding Overview](/start/onboarding-overview)
- CLI オンボーディングリファレンス: [CLI Setup Reference](/start/wizard-cli-reference)
- CLI 自動化: [CLI Automation](/start/wizard-cli-automation)
- macOS オンボーディング: [Onboarding (macOS App)](/start/onboarding)
## 例
```bash
openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
平文のプライベートネットワーク `ws://` ターゲット（信頼できるネットワークのみ）については、
オンボーディングプロセス環境で `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` を設定してください。
非対話型のカスタムプロバイダー:
```bash
openclaw onboard --non-interactive \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--custom-api-key "$CUSTOM_API_KEY" \
--secret-input-mode plaintext \
--custom-compatibility openai
```
`--custom-api-key` は非対話モードでは省略可能です。省略した場合、オンボーディングは `CUSTOM_API_KEY` を確認します。
非対話型 Ollama:
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
`--custom-base-url` のデフォルトは `http://127.0.0.1:11434` です。`--custom-model-id` は省略可能で、省略した場合はオンボーディングが Ollama の推奨デフォルトを使用します。`kimi-k2.5:cloud` のようなクラウドモデル ID もここで使用できます。
プロバイダーキーを平文ではなく ref として保存するには:
```bash
openclaw onboard --non-interactive \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
`--secret-input-mode ref` を使うと、オンボーディングは平文のキー値ではなく env ベースの ref を書き込みます。
auth-profile ベースのプロバイダーでは `keyRef` エントリを書き込みます。カスタムプロバイダーでは `models.providers.<id>.apiKey` を env ref として書き込みます（例: `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`）。
非対話型 `ref` モードの契約:
- オンボーディングプロセス環境でプロバイダーの env var を設定してください（例: `OPENAI_API_KEY`）。
- その env var も設定されていない限り、インラインキー用フラグ（例: `--openai-api-key`）を渡さないでください。
- 必要な env var がない状態でインラインキー用フラグが渡された場合、オンボーディングはガイダンス付きですぐに失敗します。
非対話モードでの Gateway トークンオプション:
- `--gateway-auth token --gateway-token <token>` は平文トークンを保存します。
- `--gateway-auth token --gateway-token-ref-env <name>` は `gateway.auth.token` を env SecretRef として保存します。
- `--gateway-token` と `--gateway-token-ref-env` は同時に使用できません。
- `--gateway-token-ref-env` には、オンボーディングプロセス環境内の空でない env var が必要です。
- `--install-daemon` 使用時に、トークン認証でトークンが必要な場合、SecretRef 管理の Gateway トークンは検証されますが、supervisor サービス環境メタデータには解決済み平文として保存されません。
- `--install-daemon` 使用時に、トークンモードでトークンが必要で、設定されたトークン SecretRef が未解決の場合、オンボーディングは対処方法の案内とともにフェイルクローズします。
- `--install-daemon` 使用時に、`gateway.auth.token` と `gateway.auth.password` の両方が設定されていて `gateway.auth.mode` が未設定の場合、オンボーディングは mode が明示的に設定されるまでインストールをブロックします。
- ローカルオンボーディングは設定に `gateway.mode="local"` を書き込みます。後で設定ファイルから `gateway.mode` が欠けている場合、それは設定破損または不完全な手動編集として扱ってください。有効な local モードのショートカットではありません。
- `--allow-unconfigured` は別個の Gateway ランタイム用エスケープハッチです。これはオンボーディングが `gateway.mode` を省略してよいことを意味しません。
例:
```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice skip \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--accept-risk
```
非対話型ローカル Gateway ヘルス:
- `--skip-health` を渡さない限り、オンボーディングは到達可能なローカル Gateway を確認してから正常終了します。
- `--install-daemon` はまず管理対象 Gateway のインストール経路を開始します。これを使わない場合、たとえば `openclaw gateway run` のように、すでにローカル Gateway が起動している必要があります。
- 自動化で config/workspace/bootstrap の書き込みだけを行いたい場合は、`--skip-health` を使ってください。
- ネイティブ Windows では、`--install-daemon` はまず Scheduled Tasks を試し、タスク作成が拒否された場合はユーザーごとの Startup フォルダーのログイン項目にフォールバックします。
参照モードでの対話型オンボーディングの挙動:
- プロンプトが出たら **Use secret reference** を選択します。
- 次に以下のいずれかを選択します:
- Environment variable
- Configured secret provider（`file` または `exec`）
- オンボーディングは保存前に高速な事前検証を実行します。
- 検証に失敗した場合、オンボーディングはエラーを表示し、再試行できます。
非対話型 Z.AI エンドポイント選択:
注: `--auth-choice zai-api-key` は、キーに最適な Z.AI エンドポイントを自動検出するようになりました（`zai/glm-5` を使う一般 API を優先します）。
GLM Coding Plan エンドポイントを明示的に使いたい場合は、`zai-coding-global` または `zai-coding-cn` を選択してください。
```bash
# プロンプトなしのエンドポイント選択
openclaw onboard --non-interactive \
--auth-choice zai-coding-global \
--zai-api-key "$ZAI_API_KEY"
# 他の Z.AI エンドポイント選択:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn
```
非対話型 Mistral の例:
```bash
openclaw onboard --non-interactive \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY"
```
フローメモ:
- `quickstart`: 最小限のプロンプトで、Gateway トークンを自動生成します。
- `manual`: port/bind/auth の完全なプロンプトを表示します（`advanced` のエイリアス）。
- 認証選択が優先プロバイダーを示唆する場合、オンボーディングは
デフォルトモデルと allowlist の picker をそのプロバイダーに事前フィルターします。Volcengine と
BytePlus では、coding-plan バリアント
（`volcengine-plan/*`、`byteplus-plan/*`）にも一致します。
- 優先プロバイダーフィルターで、まだ読み込まれているモデルが 1 つもない場合、オンボーディングは
picker を空のままにせず、フィルターなしカタログにフォールバックします。
- web-search ステップでは、一部のプロバイダーがプロバイダー固有の
フォローアッププロンプトをトリガーすることがあります:
- **Grok** では、同じ `XAI_API_KEY` を使った任意の `x_search` セットアップと、
`x_search` モデル選択を提示できます。
- **Kimi** では、Moonshot API リージョン（`api.moonshot.ai` と
`api.moonshot.cn`）およびデフォルトの Kimi web-search モデルを質問することがあります。
- ローカルオンボーディングの DM スコープ動作: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals)。
- 最速で最初のチャットを始める方法: `openclaw dashboard`（Control UI、チャネル設定不要）。
- Custom Provider: 一覧にないホスト型プロバイダーを含む、任意の OpenAI または Anthropic 互換エンドポイントに接続できます。自動検出するには Unknown を使ってください。
## よく使う後続コマンド
```bash
openclaw configure
openclaw agents add <name>
```
<Note>
`--json` は非対話モードを意味しません。スクリプトでは `--non-interactive` を使用してください。
</Note>

72
docs/ja-JP/cli/pairing.md Normal file
View File

@ -0,0 +1,72 @@
---
read_when:
- ペアリングモードのDMを使っていて送信者を承認する必要があるとき
summary: '`openclaw pairing`のCLIリファレンス（ペアリング要求の承認/一覧表示）'
title: pairing
x-i18n:
generated_at: "2026-04-05T12:39:19Z"
model: gpt-5.4
provider: openai
source_hash: 122a608ef83ec2b1011fdfd1b59b94950a4dcc8b598335b0956e2eedece4958f
source_path: cli/pairing.md
workflow: 15
---
# `openclaw pairing`
DMペアリング要求を承認または確認します（ペアリングをサポートするチャンネル向け）。
関連:
- ペアリングフロー: [Pairing](/channels/pairing)
## コマンド
```bash
openclaw pairing list telegram
openclaw pairing list --channel telegram --account work
openclaw pairing list telegram --json
openclaw pairing approve <code>
openclaw pairing approve telegram <code>
openclaw pairing approve --channel telegram --account work <code> --notify
```
## `pairing list`
1つのチャンネルに対する保留中のペアリング要求を一覧表示します。
オプション:
- `[channel]`: 位置指定のチャンネルID
- `--channel <channel>`: 明示的なチャンネルID
- `--account <accountId>`: 複数アカウント対応チャンネル用のアカウントID
- `--json`: 機械可読な出力
注記:
- ペアリング対応チャンネルが複数設定されている場合は、位置指定または`--channel`のいずれかでチャンネルを指定する必要があります。
- チャンネルIDが有効であれば、拡張チャンネルも使用できます。
## `pairing approve`
保留中のペアリングコードを承認し、その送信者を許可します。
使用方法:
- `openclaw pairing approve <channel> <code>`
- `openclaw pairing approve --channel <channel> <code>`
- ペアリング対応チャンネルが1つだけ設定されている場合は`openclaw pairing approve <code>`
オプション:
- `--channel <channel>`: 明示的なチャンネルID
- `--account <accountId>`: 複数アカウント対応チャンネル用のアカウントID
- `--notify`: 同じチャンネル上で要求元に確認メッセージを返す
## 注記
- チャンネル入力は、位置指定（`pairing list telegram`）または`--channel <channel>`で渡します。
- `pairing list`は、複数アカウント対応チャンネル向けに`--account <accountId>`をサポートします。
- `pairing approve`は、`--account <accountId>`と`--notify`をサポートします。
- ペアリング対応チャンネルが1つだけ設定されている場合は、`pairing approve <code>`を使用できます。

237
docs/ja-JP/cli/plugins.md Normal file
View File

@ -0,0 +1,237 @@
---
read_when:
- Gatewayプラグインまたは互換バンドルをインストールまたは管理したい場合
- プラグインの読み込み失敗をデバッグしたい場合
summary: '`openclaw plugins`のCLIリファレンス（list、install、marketplace、uninstall、enable/disable、doctor）'
title: plugins
x-i18n:
generated_at: "2026-04-05T12:40:48Z"
model: gpt-5.4
provider: openai
source_hash: 8c35ccf68cd7be1af5fee175bd1ce7de88b81c625a05a23887e5780e790df925
source_path: cli/plugins.md
workflow: 15
---
# `openclaw plugins`
Gatewayプラグイン/拡張機能、フックパック、および互換バンドルを管理します。
関連:
- プラグインシステム: [Plugins](/tools/plugin)
- バンドル互換性: [プラグインバンドル](/plugins/bundles)
- プラグインマニフェスト + スキーマ: [プラグインマニフェスト](/plugins/manifest)
- セキュリティ強化: [セキュリティ](/gateway/security)
## コマンド
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
バンドル済みプラグインはOpenClawに同梱されています。一部はデフォルトで有効です（たとえば、バンドル済みのモデルプロバイダー、バンドル済みの音声プロバイダー、バンドル済みのブラウザプラグイン）。それ以外は`plugins enable`が必要です。
ネイティブOpenClawプラグインは、インラインJSON Schema（空でも`configSchema`）を含む`openclaw.plugin.json`を同梱する必要があります。互換バンドルは、代わりに独自のバンドルマニフェストを使用します。
`plugins list`には`Format: openclaw`または`Format: bundle`が表示されます。詳細なlist/info出力では、バンドルのサブタイプ（`codex`、`claude`、または`cursor`）と、検出されたバンドル機能も表示されます。
### インストール
```bash
openclaw plugins install <package> # 最初にClawHub、次にnpm
openclaw plugins install clawhub:<package> # ClawHubのみ
openclaw plugins install <package> --force # 既存のインストールを上書き
openclaw plugins install <package> --pin # バージョンを固定
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # ローカルパス
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace（明示指定）
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
パッケージ名のみの指定は、最初にClawHub、次にnpmで確認されます。セキュリティ上の注意: プラグインのインストールはコードを実行するのと同様に扱ってください。固定バージョンを推奨します。
設定が無効な場合、`plugins install`は通常フェイルクローズし、先に`openclaw doctor --fix`を実行するよう案内します。文書化されている唯一の例外は、`openclaw.install.allowInvalidConfigRecovery`を明示的にオプトインしているプラグイン向けの、限定的なバンドル済みプラグイン復旧パスです。
`--force`は既存のインストール先を再利用し、すでにインストール済みのプラグインまたはフックパックをその場で上書きします。新しいローカルパス、アーカイブ、ClawHubパッケージ、またはnpmアーティファクトから同じidを意図的に再インストールする場合に使用します。
`--pin`はnpmインストールにのみ適用されます。marketplaceインストールではサポートされません。これは、marketplaceインストールではnpm specではなくmarketplaceソースメタデータが保存されるためです。
`--dangerously-force-unsafe-install`は、組み込みの危険コードスキャナーで誤検知が発生した場合の非常手段オプションです。組み込みスキャナーが`critical`の検出結果を報告してもインストールを続行できますが、プラグインの`before_install`フックによるポリシーブロックを回避するものではなく、スキャン失敗も回避しません。
このCLIフラグは、プラグインのインストール/更新フローに適用されます。Gateway経由のSkills依存関係インストールでは、対応する`dangerouslyForceUnsafeInstall`リクエストオーバーライドを使用します。一方、`openclaw skills install`は別個のClawHub Skillsダウンロード/インストールフローのままです。
`plugins install`は、`package.json`で`openclaw.hooks`を公開するフックパックのインストール画面でもあります。フックの絞り込み表示やフック単位の有効化には`openclaw hooks`を使用し、パッケージのインストールには使用しないでください。
npm specは**レジストリ専用**です（パッケージ名 + 任意の**完全一致バージョン**または**dist-tag**）。Git/URL/file specおよびsemver rangeは拒否されます。依存関係のインストールは安全のため`--ignore-scripts`付きで実行されます。
specのみの指定と`@latest`は安定トラックに留まります。npmがそれらのいずれかをプレリリースに解決した場合、OpenClawは停止し、`@beta`/`@rc`のようなプレリリースタグや、`@1.2.3-beta.4`のような完全一致のプレリリースバージョンで明示的にオプトインするよう求めます。
インストールspecのみの指定がバンドル済みプラグインid（たとえば`diffs`）に一致する場合、OpenClawはそのバンドル済みプラグインを直接インストールします。同名のnpmパッケージをインストールするには、明示的なスコープ付きspec（たとえば`@scope/diffs`）を使用してください。
サポートされるアーカイブ: `.zip`、`.tgz`、`.tar.gz`、`.tar`。
Claude marketplaceインストールもサポートされています。
ClawHubインストールでは、明示的な`clawhub:<package>`ロケーターを使用します:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
OpenClawは現在、npmで安全なプラグインspecのみの指定に対してもClawHubを優先します。ClawHubにそのパッケージまたはバージョンがない場合のみ、npmにフォールバックします:
```bash
openclaw plugins install openclaw-codex-app-server
```
OpenClawはClawHubからパッケージアーカイブをダウンロードし、告知されたプラグインAPI/最小Gateway互換性を確認してから、通常のアーカイブパスでインストールします。記録されたインストールには、後続の更新のためにClawHubソースメタデータが保持されます。
marketplace名がClaudeのローカルレジストリキャッシュ`~/.claude/plugins/known_marketplaces.json`に存在する場合は、`plugin@marketplace`の短縮記法を使用します:
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
marketplaceソースを明示的に渡したい場合は`--marketplace`を使用します:
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
marketplaceソースには次のものを使用できます:
- `~/.claude/plugins/known_marketplaces.json`のClaude既知marketplace名
- ローカルmarketplaceルートまたは`marketplace.json`のパス
- `owner/repo`のようなGitHubリポジトリ短縮記法
- `https://github.com/owner/repo`のようなGitHubリポジトリURL
- git URL
GitHubまたはgitから読み込まれたリモートmarketplaceでは、プラグインエントリはクローンされたmarketplaceリポジトリ内に留まる必要があります。OpenClawはそのリポジトリからの相対パスソースを受け入れ、リモートマニフェスト内のHTTP(S)、絶対パス、git、GitHub、およびその他の非パスのプラグインソースを拒否します。
ローカルパスおよびアーカイブでは、OpenClawは次を自動検出します:
- ネイティブOpenClawプラグイン（`openclaw.plugin.json`）
- Codex互換バンドル（`.codex-plugin/plugin.json`）
- Claude互換バンドル（`.claude-plugin/plugin.json`またはデフォルトのClaudeコンポーネントレイアウト）
- Cursor互換バンドル（`.cursor-plugin/plugin.json`）
互換バンドルは通常の拡張機能ルートにインストールされ、同じlist/info/enable/disableフローに参加します。現在は、バンドルSkills、Claude command-skills、Claude `settings.json`デフォルト、Claude `.lsp.json` / マニフェストで宣言された`lspServers`デフォルト、Cursor command-skills、および互換Codexフックディレクトリがサポートされています。その他の検出されたバンドル機能はdiagnostics/infoに表示されますが、まだランタイム実行には配線されていません。
### 一覧表示
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
```
`--enabled`を使用すると、読み込み済みプラグインのみを表示します。`--verbose`を使用すると、テーブル表示から、ソース/オリジン/バージョン/アクティベーションメタデータを含むプラグインごとの詳細行に切り替わります。機械可読なインベントリとレジストリdiagnosticsには`--json`を使用してください。
ローカルディレクトリをコピーしないようにするには`--link`を使用します（`plugins.load.paths`に追加されます）:
```bash
openclaw plugins install -l ./my-plugin
```
リンクされたインストールでは管理対象のインストール先にコピーする代わりにソースパスを再利用するため、`--link`では`--force`はサポートされません。
npmインストールで`--pin`を使用すると、デフォルト動作を非固定のまま維持しつつ、解決された完全一致spec（`name@version`）を`plugins.installs`に保存します。
### アンインストール
```bash
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall`は、該当する場合、`plugins.entries`、`plugins.installs`、プラグイン許可リスト、およびリンクされた`plugins.load.paths`エントリからプラグイン記録を削除します。アクティブなメモリプラグインでは、メモリスロットは`memory-core`にリセットされます。
デフォルトでは、アンインストール時にアクティブなstate-dirプラグインルート配下のプラグインインストールディレクトリも削除されます。ディスク上のファイルを保持するには、`--keep-files`を使用してください。
`--keep-config`は、`--keep-files`の非推奨エイリアスとしてサポートされています。
### 更新
```bash
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
更新は、`plugins.installs`内で追跡されているインストールと、`hooks.internal.installs`内で追跡されているフックパックインストールに適用されます。
プラグインidを渡すと、OpenClawはそのプラグインに記録されているインストールspecを再利用します。つまり、以前保存された`@beta`のようなdist-tagや、固定された完全一致バージョンは、後続の`update <id>`実行でも引き続き使用されます。
npmインストールでは、dist-tagまたは完全一致バージョン付きの明示的なnpmパッケージspecを渡すこともできます。OpenClawはそのパッケージ名を追跡対象のプラグイン記録に対応付け直し、そのインストール済みプラグインを更新し、今後のidベース更新のために新しいnpm specを記録します。
保存済みのintegrityハッシュが存在し、取得したアーティファクトのハッシュが変更されている場合、OpenClawは警告を表示し、続行前に確認を求めます。CIや非対話環境でプロンプトを回避するには、グローバル`--yes`を使用してください。
`--dangerously-force-unsafe-install`は、プラグイン更新中に組み込み危険コードスキャンで誤検知が発生した場合の非常手段オーバーライドとして、`plugins update`でも使用できます。それでも、プラグインの`before_install`ポリシーブロックやスキャン失敗によるブロックは回避せず、プラグイン更新にのみ適用され、フックパック更新には適用されません。
### Inspect
```bash
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
単一プラグインの詳細な内部検査です。識別情報、読み込み状態、ソース、登録済み機能、フック、ツール、コマンド、サービス、Gatewayメソッド、HTTPルート、ポリシーフラグ、diagnostics、インストールメタデータ、バンドル機能、および検出されたMCPまたはLSPサーバーサポートを表示します。
各プラグインは、実際にランタイムで何を登録するかによって次のように分類されます:
- **plain-capability** — 1つの機能タイプ（例: プロバイダー専用プラグイン）
- **hybrid-capability** — 複数の機能タイプ（例: テキスト + 音声 + 画像）
- **hook-only** — フックのみで、機能やサーフェスなし
- **non-capability** — ツール/コマンド/サービスはあるが機能なし
機能モデルの詳細については、[プラグイン形状](/plugins/architecture#plugin-shapes)を参照してください。
`--json`フラグは、スクリプト処理や監査に適した機械可読レポートを出力します。
`inspect --all`は、形状、機能種別、互換性通知、バンドル機能、およびフック概要列を含む、フリート全体のテーブルを表示します。
`info`は`inspect`のエイリアスです。
### Doctor
```bash
openclaw plugins doctor
```
`doctor`は、プラグインの読み込みエラー、マニフェスト/ディスカバリーdiagnostics、および互換性通知を報告します。問題がなければ、`No plugin issues detected.`と表示されます。
### Marketplace
```bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Marketplace listでは、ローカルmarketplaceパス、`marketplace.json`パス、`owner/repo`のようなGitHub短縮記法、GitHubリポジトリURL、またはgit URLを受け付けます。`--json`は、解決されたソースラベルと、解析されたmarketplaceマニフェストおよびプラグインエントリを出力します。

59
docs/ja-JP/cli/qr.md Normal file
View File

@ -0,0 +1,59 @@
---
read_when:
- モバイルnode appをgatewayとすばやくペアリングしたい場合
- リモート/手動共有用のsetup-code出力が必要な場合
summary: '`openclaw qr`のCLIリファレンス（モバイルペアリングQR + セットアップコードの生成）'
title: qr
x-i18n:
generated_at: "2026-04-05T12:39:29Z"
model: gpt-5.4
provider: openai
source_hash: ee6469334ad09037318f938c7ac609b7d5e3385c0988562501bb02a1bfa411ff
source_path: cli/qr.md
workflow: 15
---
# `openclaw qr`
現在のGateway設定から、モバイルペアリング用のQRとsetup codeを生成します。
## 使用方法
```bash
openclaw qr
openclaw qr --setup-code-only
openclaw qr --json
openclaw qr --remote
openclaw qr --url wss://gateway.example/ws
```
## オプション
- `--remote`: `gateway.remote.url`を優先します。これが未設定でも、`gateway.tailscale.mode=serve|funnel`がリモート公開URLを提供できる場合があります
- `--url <url>`: payloadで使うgateway URLを上書き
- `--public-url <url>`: payloadで使う公開URLを上書き
- `--token <token>`: bootstrapフローが認証に使うgateway tokenを上書き
- `--password <password>`: bootstrapフローが認証に使うgateway passwordを上書き
- `--setup-code-only`: setup codeのみを出力
- `--no-ascii`: ASCII QRレンダリングをスキップ
- `--json`: JSONを出力（`setupCode`、`gatewayUrl`、`auth`、`urlSource`）
## 注
- `--token`と`--password`は同時に指定できません。
- setup code自体には、共有gateway token/passwordではなく、不透明で短命な`bootstrapToken`が含まれるようになりました。
- 組み込みのnode/operator bootstrapフローでは、primary node tokenは引き続き`scopes: []`で発行されます。
- bootstrap handoffがoperator tokenも発行する場合、そのtokenはbootstrap allowlistに制限されたままです: `operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`。
- Bootstrap scopeチェックはroleプレフィックス付きです。そのoperator allowlistはoperatorリクエストだけを満たします。operator以外のroleでは、各roleプレフィックス配下のscopeが引き続き必要です。
- Tailscale/publicな`ws://` gateway URLでは、モバイルペアリングはfail closedします。プライベートLANの`ws://`は引き続きサポートされますが、Tailscale/publicなモバイル経路ではTailscale Serve/Funnelまたは`wss://` gateway URLを使う必要があります。
- `--remote`を使う場合、OpenClawは`gateway.remote.url`または
`gateway.tailscale.mode=serve|funnel`のいずれかを必要とします。
- `--remote`を使う場合、実効的に有効なremote credentialsがSecretRefとして設定されていて、`--token`または`--password`を渡さないときは、コマンドはアクティブなgateway snapshotからそれらを解決します。gatewayが利用できない場合、コマンドは即座に失敗します。
- `--remote`を使わない場合、CLI auth overrideが渡されていなければ、ローカルgateway auth SecretRefsが解決されます:
- token authが有効になりうる場合、`gateway.auth.token`が解決されます（明示的な`gateway.auth.mode="token"`、またはpassword sourceが勝たない推測モード）。
- password authが有効になりうる場合、`gateway.auth.password`が解決されます（明示的な`gateway.auth.mode="password"`、またはauth/envから勝つtokenがない推測モード）。
- `gateway.auth.token`と`gateway.auth.password`の両方が設定されていて（SecretRefsを含む）、`gateway.auth.mode`が未設定の場合、modeを明示的に設定するまでsetup-code解決は失敗します。
- Gatewayのバージョン差異に関する注記: このコマンドパスには`secrets.resolve`をサポートするgatewayが必要です。古いgatewayではunknown-methodエラーが返ります。
- スキャン後、デバイスペアリングを承認するには次を使います:
- `openclaw devices list`
- `openclaw devices approve <requestId>`

42
docs/ja-JP/cli/reset.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- CLI をインストールしたままローカル state を消去したいとき
- 削除対象の dry-run を確認したいとき
summary: '`openclaw reset` の CLI リファレンス（ローカル state/config をリセット）'
title: reset
x-i18n:
generated_at: "2026-04-05T12:39:23Z"
model: gpt-5.4
provider: openai
source_hash: ad464700f948bebe741ec309f25150714f0b280834084d4f531327418a42c79b
source_path: cli/reset.md
workflow: 15
---
# `openclaw reset`
ローカル config/state をリセットします（CLI はインストールされたままです）。
オプション:
- `--scope <scope>`: `config`、`config+creds+sessions`、または `full`
- `--yes`: 確認プロンプトをスキップ
- `--non-interactive`: プロンプトを無効化。`--scope` と `--yes` が必要です
- `--dry-run`: ファイルを削除せずに実行内容を表示
例:
```bash
openclaw backup create
openclaw reset
openclaw reset --dry-run
openclaw reset --scope config --yes --non-interactive
openclaw reset --scope config+creds+sessions --yes --non-interactive
openclaw reset --scope full --yes --non-interactive
```
注記:
- ローカル state を削除する前に復元可能なスナップショットが必要なら、まず `openclaw backup create` を実行してください。
- `--scope` を省略した場合、`openclaw reset` は対話プロンプトを使って削除内容を選択します。
- `--non-interactive` は `--scope` と `--yes` の両方が設定されている場合にのみ有効です。

202
docs/ja-JP/cli/sandbox.md Normal file
View File

@ -0,0 +1,202 @@
---
read_when: You are managing sandbox runtimes or debugging sandbox/tool-policy behavior.
status: active
summary: 隔離されたエージェント実行のための sandbox ランタイムを管理し、有効な sandbox ポリシーを確認する
title: Sandbox CLI
x-i18n:
generated_at: "2026-04-05T12:39:39Z"
model: gpt-5.4
provider: openai
source_hash: fa2783037da2901316108d35e04bb319d5d57963c2764b9146786b3c6474b48a
source_path: cli/sandbox.md
workflow: 15
---
# Sandbox CLI
隔離されたエージェント実行のための sandbox ランタイムを管理します。
## 概要
OpenClaw は、セキュリティのために隔離された sandbox ランタイム内でエージェントを実行できます。`sandbox` コマンドは、更新や設定変更の後にそれらのランタイムを確認し、再作成するのに役立ちます。
現在、通常これに該当するものは次のとおりです。
- Docker sandbox コンテナ
- `agents.defaults.sandbox.backend = "ssh"` の場合の SSH sandbox ランタイム
- `agents.defaults.sandbox.backend = "openshell"` の場合の OpenShell sandbox ランタイム
`ssh` と OpenShell `remote` では、再作成は Docker より重要です。
- 初回シード後は、リモートワークスペースが正規のものになります
- `openclaw sandbox recreate` は、選択したスコープに対するその正規のリモートワークスペースを削除します
- 次回使用時に、現在のローカルワークスペースから再度シードされます
## コマンド
### `openclaw sandbox explain`
**有効な** sandbox の mode/scope/workspace access、sandbox tool policy、および昇格ゲートを確認します（修正用の config キーパス付き）。
```bash
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```
### `openclaw sandbox list`
すべての sandbox ランタイムを、そのステータスと設定とともに一覧表示します。
```bash
openclaw sandbox list
openclaw sandbox list --browser # browser コンテナのみを一覧表示
openclaw sandbox list --json # JSON 出力
```
**出力に含まれる内容:**
- ランタイム名とステータス
- バックエンド（`docker`、`openshell` など）
- config ラベルと、現在の config に一致しているかどうか
- 経過時間（作成からの時間）
- アイドル時間（最後の使用からの時間）
- 関連する session/agent
### `openclaw sandbox recreate`
sandbox ランタイムを削除して、更新された config で再作成を強制します。
```bash
openclaw sandbox recreate --all # すべてのコンテナを再作成
openclaw sandbox recreate --session main # 特定の session
openclaw sandbox recreate --agent mybot # 特定の agent
openclaw sandbox recreate --browser # browser コンテナのみ
openclaw sandbox recreate --all --force # 確認をスキップ
```
**オプション:**
- `--all`: すべての sandbox コンテナを再作成
- `--session <key>`: 特定の session のコンテナを再作成
- `--agent <id>`: 特定の agent のコンテナを再作成
- `--browser`: browser コンテナのみを再作成
- `--force`: 確認プロンプトをスキップ
**重要:** ランタイムは、次回エージェントが使用されるときに自動的に再作成されます。
## ユースケース
### Docker イメージ更新後
```bash
# 新しいイメージを取得
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim
# 新しいイメージを使うように config を更新
# config を編集: agents.defaults.sandbox.docker.image（または agents.list[].sandbox.docker.image）
# コンテナを再作成
openclaw sandbox recreate --all
```
### sandbox 設定変更後
```bash
# config を編集: agents.defaults.sandbox.*（または agents.list[].sandbox.*）
# 新しい config を適用するために再作成
openclaw sandbox recreate --all
```
### SSH ターゲットまたは SSH 認証情報を変更した後
```bash
# config を編集:
# - agents.defaults.sandbox.backend
# - agents.defaults.sandbox.ssh.target
# - agents.defaults.sandbox.ssh.workspaceRoot
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData
openclaw sandbox recreate --all
```
コアの `ssh` バックエンドでは、再作成により SSH ターゲット上のスコープごとのリモートワークスペースルートが削除されます。次回実行時にローカルワークスペースから再度シードされます。
### OpenShell の source、policy、または mode を変更した後
```bash
# config を編集:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy
openclaw sandbox recreate --all
```
OpenShell `remote` モードでは、再作成によりそのスコープの正規リモートワークスペースが削除されます。次回実行時にローカルワークスペースから再度シードされます。
### setupCommand 変更後
```bash
openclaw sandbox recreate --all
# または 1 つの agent のみ:
openclaw sandbox recreate --agent family
```
### 特定の agent のみ
```bash
# 1 つの agent のコンテナだけを更新
openclaw sandbox recreate --agent alfred
```
## なぜこれが必要なのか
**問題:** sandbox 設定を更新しても:
- 既存のランタイムは古い設定のまま動作し続ける
- ランタイムは 24 時間非アクティブになって初めて削除される
- 定期的に使用されるエージェントは、古いランタイムを無期限に生かし続ける
**解決策:** `openclaw sandbox recreate` を使って古いランタイムの削除を強制します。次回必要になったとき、現在の設定で自動的に再作成されます。
ヒント: 手動のバックエンド固有クリーンアップよりも `openclaw sandbox recreate` を優先してください。
これは Gateway のランタイムレジストリを使用するため、scope/session key が変わったときの不整合を避けられます。
## 設定
sandbox 設定は `~/.openclaw/openclaw.json` の `agents.defaults.sandbox` 配下にあります（agent ごとの上書きは `agents.list[].sandbox`）:
```jsonc
{
"agents": {
"defaults": {
"sandbox": {
"mode": "all", // off, non-main, all
"backend": "docker", // docker, ssh, openshell
"scope": "agent", // session, agent, shared
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"containerPrefix": "openclaw-sbx-",
// ... more Docker options
},
"prune": {
"idleHours": 24, // 24 時間アイドルで自動削除
"maxAgeDays": 7, // 7 日後に自動削除
},
},
},
},
}
```
## 関連項目
- [Sandbox Documentation](/gateway/sandboxing)
- [Agent Configuration](/concepts/agent-workspace)
- [Doctor Command](/gateway/doctor) - sandbox セットアップを確認

204
docs/ja-JP/cli/secrets.md Normal file
View File

@ -0,0 +1,204 @@
---
read_when:
- 実行時に secret ref を再解決する場合
- 平文の残留物と未解決の ref を監査する場合
- SecretRef を設定し、一方向のスクラブ変更を適用する場合
summary: '`openclaw secrets` のCLIリファレンス（reload、audit、configure、apply）'
title: secrets
x-i18n:
generated_at: "2026-04-05T12:40:33Z"
model: gpt-5.4
provider: openai
source_hash: f436ba089d752edb766c0a3ce746ee6bca1097b22c9b30e3d9715cb0bb50bf47
source_path: cli/secrets.md
workflow: 15
---
# `openclaw secrets`
`openclaw secrets` を使用して SecretRef を管理し、アクティブな実行時スナップショットを健全な状態に保ちます。
コマンドの役割:
- `reload`: ref を再解決し、完全に成功した場合にのみ実行時スナップショットを切り替える Gateway RPC（`secrets.reload`）（config の書き込みは行いません）。
- `audit`: 平文、未解決の ref、優先順位のずれについて、設定 / auth / 生成済みモデルストアとレガシーの残留物を読み取り専用でスキャンします（`--allow-exec` が設定されていない限り、exec ref はスキップされます）。
- `configure`: プロバイダー設定、ターゲットマッピング、事前チェックのための対話型プランナーです（TTY が必要です）。
- `apply`: 保存済みプランを実行します（`--dry-run` は検証専用です。dry-run はデフォルトで exec チェックをスキップし、書き込みモードでは `--allow-exec` が設定されていない限り exec を含むプランを拒否します）。その後、対象の平文の残留物をスクラブします。
推奨される運用ループ:
```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload
```
プランに `exec` SecretRef / プロバイダーが含まれている場合は、dry-run と書き込み apply の両方のコマンドで `--allow-exec` を渡してください。
CI / ゲート向けの終了コードに関する注意:
- `audit --check` は検出事項があると `1` を返します。
- 未解決の ref は `2` を返します。
関連:
- Secrets ガイド: [Secrets Management](/gateway/secrets)
- 認証情報サーフェス: [SecretRef Credential Surface](/reference/secretref-credential-surface)
- セキュリティガイド: [Security](/gateway/security)
## 実行時スナップショットを再読み込みする
secret ref を再解決し、実行時スナップショットをアトミックに切り替えます。
```bash
openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>
```
注意:
- Gateway RPC メソッド `secrets.reload` を使用します。
- 解決に失敗した場合、Gateway は最後に正常だったスナップショットを維持し、エラーを返します（部分的な有効化は行われません）。
- JSON レスポンスには `warningCount` が含まれます。
オプション:
- `--url <url>`
- `--token <token>`
- `--timeout <ms>`
- `--json`
## 監査
OpenClaw の状態をスキャンして以下を検出します:
- 平文のシークレット保存
- 未解決の ref
- 優先順位のずれ（`auth-profiles.json` の認証情報が `openclaw.json` の ref を覆い隠している状態）
- 生成された `agents/*/agent/models.json` の残留物（プロバイダーの `apiKey` 値と機密性のあるプロバイダーヘッダー）
- レガシーの残留物（レガシー auth ストアのエントリー、OAuth リマインダー）
ヘッダー残留物に関する注意:
- 機密性のあるプロバイダーヘッダーの検出は名前ヒューリスティックに基づいています（一般的な auth / credential ヘッダー名および `authorization`、`x-api-key`、`token`、`secret`、`password`、`credential` などの断片）。
```bash
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec
```
終了時の動作:
- `--check` は検出事項があると非ゼロで終了します。
- 未解決の ref は、より優先度の高い非ゼロコードで終了します。
レポート形式の主な項目:
- `status`: `clean | findings | unresolved`
- `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`
- `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
- 検出コード:
- `PLAINTEXT_FOUND`
- `REF_UNRESOLVED`
- `REF_SHADOWED`
- `LEGACY_RESIDUE`
## Configure（対話型ヘルパー）
プロバイダーと SecretRef の変更を対話的に構築し、事前チェックを実行し、必要に応じて適用します:
```bash
openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json
```
フロー:
- 最初にプロバイダー設定（`secrets.providers` エイリアスの `add/edit/remove`）。
- 次に認証情報マッピング（フィールドを選択し、`{source, provider, id}` ref を割り当てます）。
- 最後に事前チェックと任意の apply。
フラグ:
- `--providers-only`: `secrets.providers` のみを設定し、認証情報マッピングをスキップします。
- `--skip-provider-setup`: プロバイダー設定をスキップし、認証情報を既存のプロバイダーにマッピングします。
- `--agent <id>`: `auth-profiles.json` のターゲット検出と書き込みのスコープを 1 つのエージェントストアに限定します。
- `--allow-exec`: 事前チェック / apply 中に exec SecretRef チェックを許可します（プロバイダーコマンドを実行する場合があります）。
注意:
- 対話型 TTY が必要です。
- `--providers-only` と `--skip-provider-setup` は組み合わせられません。
- `configure` は、`openclaw.json` 内のシークレットを保持するフィールドと、選択したエージェントスコープの `auth-profiles.json` を対象にします。
- `configure` は、picker フロー内で新しい `auth-profiles.json` マッピングを直接作成することをサポートしています。
- 正式にサポートされる対象サーフェス: [SecretRef Credential Surface](/reference/secretref-credential-surface)
- apply の前に事前解決を実行します。
- 事前チェック / apply に exec ref が含まれる場合は、両方のステップで `--allow-exec` を設定したままにしてください。
- 生成されるプランでは、スクラブオプション（`scrubEnv`、`scrubAuthProfilesForProviderTargets`、`scrubLegacyAuthJson` がすべて有効）がデフォルトです。
- スクラブされた平文の値に対して、apply パスは一方向です。
- `--apply` を付けない場合でも、事前チェック後に CLI は `Apply this plan now?` と確認します。
- `--apply` を付けた場合（かつ `--yes` なし）、CLI は取り消し不能な追加確認を表示します。
- `--json` はプランと事前チェックレポートを出力しますが、このコマンドには依然として対話型 TTY が必要です。
exec プロバイダーの安全性に関する注意:
- Homebrew のインストールでは、`/opt/homebrew/bin/*` 配下にシンボリックリンクされたバイナリが公開されることがよくあります。
- `allowSymlinkCommand: true` は、信頼できるパッケージマネージャーのパスで必要な場合にのみ設定し、`trustedDirs`（例: `["/opt/homebrew"]`）と組み合わせてください。
- Windows では、プロバイダーパスの ACL 検証が利用できない場合、OpenClaw は安全側に倒して失敗します。信頼できるパスに限り、そのプロバイダーで `allowInsecurePath: true` を設定すると、パスのセキュリティチェックをバイパスできます。
## 保存済みプランを適用する
以前に生成されたプランを適用または事前チェックします:
```bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
```
exec の動作:
- `--dry-run` はファイルを書き込まずに事前チェックを検証します。
- dry-run では、exec SecretRef チェックはデフォルトでスキップされます。
- 書き込みモードでは、`--allow-exec` が設定されていない限り、exec SecretRef / プロバイダーを含むプランを拒否します。
- どちらのモードでも、exec プロバイダーチェック / 実行を有効にするには `--allow-exec` を使用します。
プラン契約の詳細（許可されるターゲットパス、検証ルール、失敗時のセマンティクス）:
- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
`apply` が更新する可能性のあるもの:
- `openclaw.json`（SecretRef ターゲット + プロバイダーの upsert / delete）
- `auth-profiles.json`（プロバイダーターゲットのスクラブ）
- レガシー `auth.json` の残留物
- 値が移行された `~/.openclaw/.env` の既知のシークレットキー
## ロールバック用バックアップがない理由
`secrets apply` は、古い平文の値を含むロールバック用バックアップを意図的に書き込みません。
安全性は、厳密な事前チェックと、失敗時のベストエフォートなインメモリ復元を伴う、ほぼアトミックな apply によって確保されます。
## 例
```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
```
`audit --check` がまだ平文の検出事項を報告する場合は、残っている報告済みターゲットパスを更新し、再度 audit を実行してください。

91
docs/ja-JP/cli/security.md Normal file
View File

@ -0,0 +1,91 @@
---
read_when:
- config/state に対して簡単なセキュリティ監査を実行したいとき
- 安全な「修正」提案（権限、デフォルトの強化）を適用したいとき
summary: '`openclaw security` の CLI リファレンス（一般的なセキュリティ上の落とし穴を監査して修正）'
title: security
x-i18n:
generated_at: "2026-04-05T12:39:45Z"
model: gpt-5.4
provider: openai
source_hash: e5a3e4ab8e0dfb6c10763097cb4483be2431985f16de877523eb53e2122239ae
source_path: cli/security.md
workflow: 15
---
# `openclaw security`
セキュリティツール（監査 + 任意の修正）。
関連:
- セキュリティガイド: [Security](/gateway/security)
## 監査
```bash
openclaw security audit
openclaw security audit --deep
openclaw security audit --deep --password <password>
openclaw security audit --deep --token <token>
openclaw security audit --fix
openclaw security audit --json
```
この監査は、複数の DM 送信者が main session を共有している場合に警告し、**secure DM mode** を推奨します: `session.dmScope="per-channel-peer"`（マルチアカウントチャネルでは `per-account-channel-peer`）。
これは、協調利用または共有 inbox のハードニング向けです。相互に信頼していない、または敵対的な operator 間で 1 つの Gateway を共有する構成は推奨されません。別々の Gateway（または別々の OS ユーザー/ホスト）で信頼境界を分離してください。
また、config が共有ユーザー ingress の可能性を示唆する場合（たとえば open DM/group policy、設定済みグループターゲット、または wildcard 送信者ルール）は `security.trust_model.multi_user_heuristic` を出力し、OpenClaw のデフォルトが個人アシスタントの trust model であることを再通知します。
意図的に共有ユーザー構成を使う場合、監査ガイダンスでは、すべての session を sandbox 化し、filesystem アクセスを workspace スコープに保ち、個人/プライベートな identity や認証情報をその runtime から外しておくことを推奨します。
また、小さいモデル（`<=300B`）が sandbox なしで使われ、かつ web/browser ツールが有効な場合にも警告します。
webhook ingress については、`hooks.token` が Gateway token を使い回している場合、`hooks.token` が短い場合、`hooks.path="/"` の場合、`hooks.defaultSessionKey` が未設定の場合、`hooks.allowedAgentIds` が無制限の場合、リクエスト `sessionKey` override が有効な場合、および override が有効なのに `hooks.allowedSessionKeyPrefixes` がない場合に警告します。
また、sandbox mode がオフなのに sandbox Docker 設定がある場合、`gateway.nodes.denyCommands` に効果のないパターン風/未知のエントリがある場合（ノードコマンド名の完全一致のみで、shell テキストフィルタではありません）、`gateway.nodes.allowCommands` が危険なノードコマンドを明示的に有効化している場合、グローバル `tools.profile="minimal"` が agent tool profile で上書きされている場合、open groups が sandbox/workspace ガードなしで runtime/filesystem ツールを公開している場合、およびインストール済み extension plugin ツールが緩い tool policy で到達可能な場合にも警告します。
さらに、`gateway.allowRealIpFallback=true`（proxy 設定ミス時の header spoofing リスク）と `discovery.mdns.mode="full"`（mDNS TXT record によるメタデータ漏えい）も警告対象です。
また、sandbox browser が Docker `bridge` network を使っているのに `sandbox.browser.cdpSourceRange` がない場合にも警告します。
さらに、危険な sandbox Docker network mode（`host` や `container:*` namespace join を含む）も検出します。
また、既存の sandbox browser Docker container に hash label の欠落や古さがある場合（たとえば `openclaw.browserConfigEpoch` がない移行前 container）にも警告し、`openclaw sandbox recreate --browser --all` を推奨します。
さらに、npm ベースの plugin/hook install record がバージョン固定されていない、integrity metadata がない、または現在インストールされている package version とずれている場合にも警告します。
チャネル allowlist が安定した ID ではなく、変更可能な名前/メール/タグに依存している場合にも警告します（該当する場合の Discord、Slack、Google Chat、Microsoft Teams、Mattermost、IRC スコープ）。
また、`gateway.auth.mode="none"` により、共有 secret なしで Gateway HTTP API（`/tools/invoke` と有効な任意の `/v1/*` endpoint）へ到達できる場合にも警告します。
`dangerous`/`dangerously` で始まる設定は、明示的な緊急回避用の operator override です。これらの 1 つを有効にしていること自体は、単独ではセキュリティ脆弱性報告にはなりません。
危険なパラメーターの完全な一覧については、[Security](/gateway/security) の「Insecure or dangerous flags summary」セクションを参照してください。
SecretRef の挙動:
- `security audit` は、対象パスに対してサポート対象の SecretRef を読み取り専用モードで解決します。
- 現在のコマンドパスで SecretRef が利用できない場合でも、監査は継続し、クラッシュする代わりに `secretDiagnostics` を報告します。
- `--token` と `--password` は、そのコマンド実行時の deep-probe 認証だけを上書きします。config や SecretRef mapping は書き換えません。
## JSON 出力
CI/policy チェックには `--json` を使ってください:
```bash
openclaw security audit --json | jq '.summary'
openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
```
`--fix` と `--json` を組み合わせた場合、出力には修正アクションと最終レポートの両方が含まれます:
```bash
openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
```
## `--fix` で変更される内容
`--fix` は、安全で決定的な修正を適用します:
- 一般的な `groupPolicy="open"` を `groupPolicy="allowlist"` に切り替える（サポート対象チャネルの account variant を含む）
- WhatsApp の group policy が `allowlist` に切り替わるとき、保存済み `allowFrom` ファイルにその一覧があり、かつ config にまだ `allowFrom` が定義されていない場合は、そこから `groupAllowFrom` を初期投入する
- `logging.redactSensitive` を `"off"` から `"tools"` に設定する
- state/config と一般的な機密ファイルの権限を厳格化する
（`credentials/*.json`、`auth-profiles.json`、`sessions.json`、session
`*.jsonl`）
- `openclaw.json` から参照されている config include file も同様に厳格化する
- POSIX ホストでは `chmod`、Windows では `icacls` reset を使う
`--fix` では**変更しない**もの:
- token/password/API key のローテーション
- ツールの無効化（`gateway`、`cron`、`exec` など）
- gateway の bind/auth/network 公開設定の変更
- plugin/Skills の削除または書き換え

120
docs/ja-JP/cli/sessions.md Normal file
View File

@ -0,0 +1,120 @@
---
read_when:
- 保存されたsessionsを一覧表示して最近のアクティビティを確認したい場合
summary: '`openclaw sessions`のCLIリファレンス（保存されたsessionsと使用状況の一覧）'
title: sessions
x-i18n:
generated_at: "2026-04-05T12:39:44Z"
model: gpt-5.4
provider: openai
source_hash: 47eb55d90bd0681676283310cfa50dcacc95dff7d9a39bf2bb188788c6e5e5ba
source_path: cli/sessions.md
workflow: 15
---
# `openclaw sessions`
保存された会話sessionを一覧表示します。
```bash
openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --verbose
openclaw sessions --json
```
スコープ選択:
- デフォルト: 設定されたdefault agent store
- `--verbose`: 詳細ログ
- `--agent <id>`: 1つの設定済みagent store
- `--all-agents`: すべての設定済みagent storesを集約
- `--store <path>`: 明示的なstoreパス（`--agent`または`--all-agents`とは併用不可）
`openclaw sessions --all-agents`は設定済みagent storesを読み取ります。GatewayとACPの
session discoveryはこれより広く、デフォルトの`agents/`ルートまたは
テンプレート化された`session.store`ルート配下で見つかったディスク上のみのstoresも含みます。これらの
検出されたstoresは、agentルート内の通常の`sessions.json`ファイルに解決される必要があります。
symlinkおよびルート外パスはスキップされます。
JSON例:
`openclaw sessions --all-agents --json`:
```json
{
"path": null,
"stores": [
{ "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },
{ "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }
],
"allAgents": true,
"count": 2,
"activeMinutes": null,
"sessions": [
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
{ "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
]
}
```
## Cleanupメンテナンス
次の書き込みサイクルを待たずに、今すぐメンテナンスを実行します:
```bash
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --agent work --dry-run
openclaw sessions cleanup --all-agents --dry-run
openclaw sessions cleanup --enforce
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
openclaw sessions cleanup --json
```
`openclaw sessions cleanup`はconfigの`session.maintenance`設定を使用します。
- スコープに関する注記: `openclaw sessions cleanup`がメンテナンスするのはsession stores/transcriptsのみです。cron実行ログ（`cron/runs/<jobId>.jsonl`）は削除しません。これらは[cron設定](/automation/cron-jobs#configuration)の`cron.runLog.maxBytes`および`cron.runLog.keepLines`で管理され、[Cronメンテナンス](/automation/cron-jobs#maintenance)で説明されています。
- `--dry-run`: 書き込みを行わずに、何件のエントリがprune/capされるかをプレビューします。
- テキストモードでは、dry-runはsessionごとのアクションテーブル（`Action`、`Key`、`Age`、`Model`、`Flags`）を表示するため、何が保持され、何が削除されるかを確認できます。
- `--enforce`: `session.maintenance.mode`が`warn`でもメンテナンスを適用します。
- `--fix-missing`: transcriptファイルが存在しないエントリを削除します。通常であればage/count条件で対象外であっても削除します。
- `--active-key <key>`: 特定のアクティブkeyをディスク予算によるevictionから保護します。
- `--agent <id>`: 1つの設定済みagent storeに対してcleanupを実行します。
- `--all-agents`: すべての設定済みagent storesに対してcleanupを実行します。
- `--store <path>`: 特定の`sessions.json`ファイルに対して実行します。
- `--json`: JSON要約を出力します。`--all-agents`では、storeごとに1つの要約が出力されます。
`openclaw sessions cleanup --all-agents --dry-run --json`:
```json
{
"allAgents": true,
"mode": "warn",
"dryRun": true,
"stores": [
{
"agentId": "main",
"storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
"beforeCount": 120,
"afterCount": 80,
"pruned": 40,
"capped": 0
},
{
"agentId": "work",
"storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
"beforeCount": 18,
"afterCount": 18,
"pruned": 0,
"capped": 0
}
]
}
```
関連:
- Session設定: [Configuration reference](/gateway/configuration-reference#session)

52
docs/ja-JP/cli/setup.md Normal file
View File

@ -0,0 +1,52 @@
---
read_when:
- 完全な CLI オンボーディングなしで初回セットアップを行っている
- デフォルトの workspace パスを設定したい
summary: '`openclaw setup` の CLI リファレンス（config + workspace を初期化）'
title: setup
x-i18n:
generated_at: "2026-04-05T12:39:49Z"
model: gpt-5.4
provider: openai
source_hash: f538aac341c749043ad959e35f2ed99c844ab8c3500ff59aa159d940bd301792
source_path: cli/setup.md
workflow: 15
---
# `openclaw setup`
`~/.openclaw/openclaw.json` とエージェント workspace を初期化します。
関連:
- はじめに: [はじめに](/ja-JP/start/getting-started)
- CLI オンボーディング: [Onboarding (CLI)](/ja-JP/start/wizard)
## 例
```bash
openclaw setup
openclaw setup --workspace ~/.openclaw/workspace
openclaw setup --wizard
openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
```
## オプション
- `--workspace <dir>`: エージェント workspace ディレクトリ（`agents.defaults.workspace` として保存）
- `--wizard`: オンボーディングを実行
- `--non-interactive`: プロンプトなしでオンボーディングを実行
- `--mode <local|remote>`: オンボーディングモード
- `--remote-url <url>`: リモート Gateway WebSocket URL
- `--remote-token <token>`: リモート Gateway トークン
setup 経由でオンボーディングを実行するには:
```bash
openclaw setup --wizard
```
注意:
- 単純な `openclaw setup` は、完全なオンボーディングフローなしで config + workspace を初期化します。
- オンボーディング用フラグ（`--wizard`、`--non-interactive`、`--mode`、`--remote-url`、`--remote-token`）のいずれかが存在すると、オンボーディングが自動実行されます。

65
docs/ja-JP/cli/skills.md Normal file
View File

@ -0,0 +1,65 @@
---
read_when:
- 利用可能で実行準備が整っている Skills を確認したいとき
- ClawHub から Skills を検索、インストール、または更新したいとき
- Skills に必要な不足バイナリ / env / config をデバッグしたいとき
summary: '`openclaw skills` の CLI リファレンス（search/install/update/list/info/check）'
title: skills
x-i18n:
generated_at: "2026-04-05T12:39:49Z"
model: gpt-5.4
provider: openai
source_hash: 11af59b1b6bff19cc043acd8d67bdd4303201d3f75f23c948b83bf14882c7bb1
source_path: cli/skills.md
workflow: 15
---
# `openclaw skills`
ローカルの Skills を確認し、ClawHub から Skills をインストール/更新します。
関連:
- Skills システム: [Skills](/tools/skills)
- Skills 設定: [Skills config](/tools/skills-config)
- ClawHub インストール: [ClawHub](/tools/clawhub)
## コマンド
```bash
openclaw skills search "calendar"
openclaw skills search --limit 20 --json
openclaw skills install <slug>
openclaw skills install <slug> --version <version>
openclaw skills install <slug> --force
openclaw skills update <slug>
openclaw skills update --all
openclaw skills list
openclaw skills list --eligible
openclaw skills list --json
openclaw skills list --verbose
openclaw skills info <name>
openclaw skills info <name> --json
openclaw skills check
openclaw skills check --json
```
`search` / `install` / `update` は ClawHub を直接使用し、アクティブな
ワークスペースの `skills/` ディレクトリにインストールします。`list` / `info` / `check` は引き続き、現在のワークスペースと config から見えるローカルの
Skills を確認します。
この CLI の `install` コマンドは、ClawHub から skill フォルダーをダウンロードします。オンボーディングや Skills 設定から Gateway 経由でトリガーされる
skill 依存関係のインストールでは、代わりに別の
`skills.install` リクエスト経路が使われます。
注記:
- `search [query...]` は任意のクエリを受け取ります。省略すると、デフォルトの
ClawHub 検索フィードを閲覧します。
- `search --limit <n>` は返される結果数の上限を設定します。
- `install --force` は、同じ
slug の既存ワークスペース skill フォルダーを上書きします。
- `update --all` は、アクティブなワークスペース内の追跡対象 ClawHub インストールのみを更新します。
- サブコマンドを指定しない場合、デフォルト動作は `list` です。
- `list`、`info`、`check` はレンダリング済み出力を stdout に書き出します。
`--json` を使うと、機械可読なペイロードはパイプやスクリプト向けに stdout に維持されます。

42
docs/ja-JP/cli/status.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- チャンネルの正常性と最近のセッション受信者をすばやく診断したい
- デバッグ用の貼り付け可能な「all」ステータスが必要
summary: '`openclaw status` のCLIリファレンス（診断、プローブ、使用状況スナップショット）'
title: status
x-i18n:
generated_at: "2026-04-05T12:40:15Z"
model: gpt-5.4
provider: openai
source_hash: fbe9d94fbe9938cd946ee6f293b5bd3b464b75e1ade2eacdd851788c3bffe94e
source_path: cli/status.md
workflow: 15
---
# `openclaw status`
チャンネルとセッションの診断。
```bash
openclaw status
openclaw status --all
openclaw status --deep
openclaw status --usage
```
注意:
- `--deep` はライブプローブ（WhatsApp Web + Telegram + Discord + Slack + Signal）を実行します。
- `--usage` は正規化されたプロバイダー使用状況ウィンドウを `X% left` として表示します。
- MiniMax の生の `usage_percent` / `usagePercent` フィールドは残りクォータを示すため、OpenClaw は表示前にそれらを反転します。件数ベースのフィールドが存在する場合はそちらが優先されます。`model_remains` のレスポンスではチャットモデルのエントリーが優先され、必要に応じてタイムスタンプからウィンドウラベルを導出し、プランラベルにモデル名を含めます。
- 現在のセッションスナップショットの情報が少ない場合、`/status` は最新のトランスクリプト使用状況ログからトークン数とキャッシュカウンターを補完できます。既存のゼロ以外のライブ値は引き続きトランスクリプトのフォールバック値より優先されます。
- トランスクリプトのフォールバックは、ライブセッションエントリーに存在しない場合に、アクティブなランタイムモデルラベルも復元できます。そのトランスクリプトモデルが選択されたモデルと異なる場合、status は選択されたモデルではなく、復元されたランタイムモデルに対してコンテキストウィンドウを解決します。
- プロンプトサイズの集計では、セッションメタデータが存在しないかより小さい場合、トランスクリプトのフォールバックはより大きいプロンプト指向の合計を優先するため、カスタムプロバイダーのセッションが `0` トークン表示に縮退しません。
- 複数のエージェントが設定されている場合、出力にはエージェントごとのセッションストアが含まれます。
- 概要には、利用可能な場合に Gateway とノードホストサービスのインストール / 実行状況が含まれます。
- 概要には、更新チャンネルと git SHA（ソースチェックアウト用）が含まれます。
- 更新情報は概要に表示されます。更新が利用可能な場合、status は `openclaw update` を実行するヒントを表示します（[更新](/install/updating) を参照）。
- 読み取り専用のステータス表示（`status`、`status --json`、`status --all`）は、可能な場合に対象の設定パスに対してサポートされている SecretRef を解決します。
- サポートされているチャンネルの SecretRef が設定されていても、現在のコマンドパスで利用できない場合、status は読み取り専用のままとなり、クラッシュせずに劣化した出力を報告します。人間向け出力には「configured token unavailable in this command path」のような警告が表示され、JSON 出力には `secretDiagnostics` が含まれます。
- コマンドローカルの SecretRef 解決が成功した場合、status は解決済みスナップショットを優先し、最終出力から一時的な「secret unavailable」チャンネルマーカーを消去します。
- `status --all` には Secrets の概要行と、シークレット診断を要約する診断セクション（読みやすさのために切り詰められます）が含まれ、レポート生成は停止しません。

78
docs/ja-JP/cli/system.md Normal file
View File

@ -0,0 +1,78 @@
---
read_when:
- cronジョブを作成せずにシステムイベントをキューに追加したい場合
- heartbeatを有効または無効にする必要がある場合
- システムpresenceエントリを確認したい場合
summary: '`openclaw system` のCLIリファレンス（システムイベント、heartbeat、presence）'
title: system
x-i18n:
generated_at: "2026-04-05T12:40:12Z"
model: gpt-5.4
provider: openai
source_hash: a7d19afde9d9cde8a79b0bb8cec6e5673466f4cb9b575fb40111fc32f4eee5d7
source_path: cli/system.md
workflow: 15
---
# `openclaw system`
Gateway用のシステムレベルのヘルパーです。システムイベントをキューに追加し、heartbeatを制御し、
presenceを表示します。
すべての `system` サブコマンドはGateway RPCを使用し、共通のクライアントフラグを受け付けます。
- `--url <url>`
- `--token <token>`
- `--timeout <ms>`
- `--expect-final`
## 一般的なコマンド
```bash
openclaw system event --text "Check for urgent follow-ups" --mode now
openclaw system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
openclaw system heartbeat enable
openclaw system heartbeat last
openclaw system presence
```
## `system event`
**main** セッションでシステムイベントをキューに追加します。次のheartbeatで、
プロンプトに `System:` 行として挿入されます。`--mode now` を使うとheartbeatが
即座にトリガーされ、`next-heartbeat` は次回のスケジュール済みティックまで待機します。
フラグ:
- `--text <text>`: 必須のシステムイベントテキスト。
- `--mode <mode>`: `now` または `next-heartbeat`（デフォルト）。
- `--json`: マシン可読な出力。
- `--url`, `--token`, `--timeout`, `--expect-final`: 共通のGateway RPCフラグ。
## `system heartbeat last|enable|disable`
heartbeatの制御:
- `last`: 最後のheartbeatイベントを表示します。
- `enable`: heartbeatを再び有効にします（無効にされていた場合に使用します）。
- `disable`: heartbeatを一時停止します。
フラグ:
- `--json`: マシン可読な出力。
- `--url`, `--token`, `--timeout`, `--expect-final`: 共通のGateway RPCフラグ。
## `system presence`
Gatewayが認識している現在のシステムpresenceエントリ（ノード、
インスタンス、その他の同様のステータス行）を一覧表示します。
フラグ:
- `--json`: マシン可読な出力。
- `--url`, `--token`, `--timeout`, `--expect-final`: 共通のGateway RPCフラグ。
## 注意
- 現在の設定で到達可能な、実行中のGatewayが必要です（ローカルまたはリモート）。
- システムイベントは一時的なもので、再起動後も保持されません。

37
docs/ja-JP/cli/tui.md Normal file
View File

@ -0,0 +1,37 @@
---
read_when:
- Gateway 用のターミナル UI が必要なとき（リモート向け）
- スクリプトから url/token/session を渡したいとき
summary: '`openclaw tui` の CLI リファレンス（Gateway に接続するターミナル UI）'
title: tui
x-i18n:
generated_at: "2026-04-05T12:39:50Z"
model: gpt-5.4
provider: openai
source_hash: 60e35062c0551f85ce0da604a915b3e1ca2514d00d840afe3b94c529304c2c1a
source_path: cli/tui.md
workflow: 15
---
# `openclaw tui`
Gateway に接続するターミナル UI を開きます。
関連:
- TUI ガイド: [TUI](/web/tui)
注記:
- `tui` は、可能な場合に token/password 認証向けの設定済み Gateway auth SecretRef を解決します（`env`/`file`/`exec` provider）。
- 設定済みエージェント workspace directory 内から起動した場合、TUI はそのエージェントを session key のデフォルトとして自動選択します（`--session` が明示的に `agent:<id>:...` の場合を除く）。
## 例
```bash
openclaw tui
openclaw tui --url ws://127.0.0.1:18789 --token <token>
openclaw tui --session main --deliver
# when run inside an agent workspace, infers that agent automatically
openclaw tui --session bugfix
```

46
docs/ja-JP/cli/uninstall.md Normal file
View File

@ -0,0 +1,46 @@
---
read_when:
- Gatewayサービスやローカル状態を削除したい場合
- まずドライランを実行したい場合
summary: '`openclaw uninstall` のCLIリファレンス（Gatewayサービス + ローカルデータを削除）'
title: uninstall
x-i18n:
generated_at: "2026-04-05T12:40:09Z"
model: gpt-5.4
provider: openai
source_hash: 2123a4f9c7a070ef7e13c60dafc189053ef61ce189fa4f29449dd50987c1894c
source_path: cli/uninstall.md
workflow: 15
---
# `openclaw uninstall`
Gatewayサービス + ローカルデータをアンインストールします（CLIは残ります）。
オプション:
- `--service`: Gatewayサービスを削除
- `--state`: 状態と設定を削除
- `--workspace`: ワークスペースディレクトリを削除
- `--app`: macOSアプリを削除
- `--all`: サービス、状態、ワークスペース、アプリを削除
- `--yes`: 確認プロンプトをスキップ
- `--non-interactive`: プロンプトを無効化します。`--yes` が必要です
- `--dry-run`: ファイルを削除せずに実行内容を表示
例:
```bash
openclaw backup create
openclaw uninstall
openclaw uninstall --service --yes --non-interactive
openclaw uninstall --state --workspace --yes --non-interactive
openclaw uninstall --all --yes
openclaw uninstall --dry-run
```
注意:
- 状態またはワークスペースを削除する前に復元可能なスナップショットが必要な場合は、まず `openclaw backup create` を実行してください。
- `--all` は、サービス、状態、ワークスペース、アプリをまとめて削除するための短縮指定です。
- `--non-interactive` には `--yes` が必要です。

118
docs/ja-JP/cli/update.md Normal file
View File

@ -0,0 +1,118 @@
---
read_when:
- ソースチェックアウトを安全に更新したい
- '`--update` の短縮動作を理解する必要がある'
summary: '`openclaw update` のCLIリファレンス（比較的安全なソース更新 + Gateway自動再起動）'
title: update
x-i18n:
generated_at: "2026-04-05T12:40:19Z"
model: gpt-5.4
provider: openai
source_hash: 12c8098654b644c3666981d379f6c018e84fde56a5420f295d78052f9001bdad
source_path: cli/update.md
workflow: 15
---
# `openclaw update`
OpenClawを安全に更新し、stable/beta/devチャンネルを切り替えます。
**npm/pnpm/bun**経由でインストールした場合（グローバルインストール、gitメタデータなし）、更新は[Updating](/install/updating)のパッケージマネージャーフローで行われます。
## 使用方法
```bash
openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update
```
## オプション
- `--no-restart`: 更新成功後にGatewayサービスを再起動しません。
- `--channel <stable|beta|dev>`: 更新チャンネルを設定します（git + npm。設定に永続化されます）。
- `--tag <dist-tag|version|spec>`: 今回の更新に限ってパッケージターゲットを上書きします。パッケージインストールでは、`main` は `github:openclaw/openclaw#main` にマッピングされます。
- `--dry-run`: 設定の書き込み、インストール、プラグイン同期、再起動を行わずに、予定されている更新アクション（チャンネル/タグ/ターゲット/再起動フロー）をプレビューします。
- `--json`: 機械可読な `UpdateRunResult` JSONを出力します。
- `--timeout <seconds>`: 各ステップのタイムアウト（デフォルトは1200秒）。
- `--yes`: 確認プロンプトをスキップします（たとえばダウングレード確認）。
注: 古いバージョンでは設定が壊れる可能性があるため、ダウングレードには確認が必要です。
## `update status`
現在の更新チャンネルと git タグ/ブランチ/SHA（ソースチェックアウトの場合）、および更新の可用性を表示します。
```bash
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
```
オプション:
- `--json`: 機械可読なステータスJSONを出力します。
- `--timeout <seconds>`: チェックのタイムアウト（デフォルトは3秒）。
## `update wizard`
更新チャンネルを選択し、更新後にGatewayを再起動するかどうかを確認する対話フローです
（デフォルトでは再起動します）。gitチェックアウトなしで `dev` を選択した場合は、
それを作成する提案が表示されます。
オプション:
- `--timeout <seconds>`: 各更新ステップのタイムアウト（デフォルトは `1200`）
## 実行内容
明示的にチャンネルを切り替えると（`--channel ...`）、OpenClawは
インストール方法もそれに合わせて維持します。
- `dev` → gitチェックアウトを確保し（デフォルト: `~/openclaw`、`OPENCLAW_GIT_DIR` で上書き可能）、
それを更新して、そのチェックアウトからグローバルCLIをインストールします。
- `stable` → `latest` を使ってnpmからインストールします。
- `beta` → npm dist-tag `beta` を優先しますが、betaが存在しないか現在のstableリリースより古い場合は
`latest` にフォールバックします。
Gatewayコアの自動アップデーター（設定で有効な場合）は、この同じ更新パスを再利用します。
## Gitチェックアウトフロー
チャンネル:
- `stable`: 最新の非betaタグをチェックアウトしてから、build + doctorを実行します。
- `beta`: 最新の `-beta` タグを優先しますが、betaが存在しないか古い場合は最新のstableタグにフォールバックします。
- `dev`: `main` をチェックアウトしてから、fetch + rebaseを実行します。
概要:
1. クリーンなworktreeが必要です（コミットされていない変更なし）。
2. 選択したチャンネル（タグまたはブランチ）に切り替えます。
3. upstreamをfetchします（devのみ）。
4. devのみ: 一時worktreeで事前のlint + TypeScript buildを実行します。先端のコミットが失敗した場合は、最大10コミットさかのぼって、正常にbuildできる最新のコミットを探します。
5. 選択したコミットへrebaseします（devのみ）。
6. 依存関係をインストールします（`pnpm` を優先し、`npm` にフォールバック、`bun` は二次的な互換性フォールバックとして引き続き利用可能です）。
7. buildを実行し、Control UIもbuildします。
8. 最終的な「安全な更新」チェックとして `openclaw doctor` を実行します。
9. プラグインを現在のチャンネルに同期します（devはバンドルされた拡張機能を使用し、stable/betaはnpmを使用）し、npmインストール済みプラグインを更新します。
## `--update` の短縮形
`openclaw --update` は `openclaw update` に書き換えられます（シェルやランチャースクリプトで便利です）。
## 関連項目
- `openclaw doctor`（gitチェックアウトでは先にupdateを実行することを提案します）
- [Development channels](/install/development-channels)
- [Updating](/install/updating)
- [CLI reference](/cli)

41
docs/ja-JP/cli/voicecall.md Normal file
View File

@ -0,0 +1,41 @@
---
read_when:
- 音声通話プラグインを使用していて、CLIのエントリーポイントを知りたい場合
- '`voicecall call|continue|status|tail|expose` のクイック例を知りたい場合'
summary: '`openclaw voicecall` のCLIリファレンス（音声通話プラグインのコマンドインターフェース）'
title: voicecall
x-i18n:
generated_at: "2026-04-05T12:40:07Z"
model: gpt-5.4
provider: openai
source_hash: 2c99e7a3d256e1c74a0f07faba9675cc5a88b1eb2fc6e22993caf3874d4f340a
source_path: cli/voicecall.md
workflow: 15
---
# `openclaw voicecall`
`voicecall` はプラグインによって提供されるコマンドです。音声通話プラグインがインストールされ、有効になっている場合にのみ表示されます。
主要ドキュメント:
- 音声通話プラグイン: [Voice Call](/plugins/voice-call)
## 一般的なコマンド
```bash
openclaw voicecall status --call-id <id>
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall end --call-id <id>
```
## Webhookの公開（Tailscale）
```bash
openclaw voicecall expose --mode serve
openclaw voicecall expose --mode funnel
openclaw voicecall expose --mode off
```
セキュリティに関する注意: webhookエンドポイントは、信頼できるネットワークにのみ公開してください。可能であれば、Funnel よりも Tailscale Serve を優先してください。

98
docs/ja-JP/cli/webhooks.md Normal file
View File

@ -0,0 +1,98 @@
---
read_when:
- Gmail Pub/SubイベントをOpenClawに接続したい場合
- Webhookヘルパーコマンドを使いたい場合
summary: '`openclaw webhooks` のCLIリファレンス（Webhookヘルパー + Gmail Pub/Sub）'
title: webhooks
x-i18n:
generated_at: "2026-04-05T12:40:15Z"
model: gpt-5.4
provider: openai
source_hash: 2b22ce879c3a94557be57919b4d2b3e92ff4d41fbae7bc88d2ab07cd4bbeac83
source_path: cli/webhooks.md
workflow: 15
---
# `openclaw webhooks`
Webhookヘルパーと連携機能（Gmail Pub/Sub、Webhookヘルパー）。
関連:
- Webhooks: [Webhooks](/ja-JP/automation/cron-jobs#webhooks)
- Gmail Pub/Sub: [Gmail Pub/Sub](/ja-JP/automation/cron-jobs#gmail-pubsub-integration)
## Gmail
```bash
openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail run
```
### `webhooks gmail setup`
Gmail watch、Pub/Sub、およびOpenClawへのWebhook配信を設定します。
必須:
- `--account <email>`
オプション:
- `--project <id>`
- `--topic <name>`
- `--subscription <name>`
- `--label <label>`
- `--hook-url <url>`
- `--hook-token <token>`
- `--push-token <token>`
- `--bind <host>`
- `--port <port>`
- `--path <path>`
- `--include-body`
- `--max-bytes <n>`
- `--renew-minutes <n>`
- `--tailscale <funnel|serve|off>`
- `--tailscale-path <path>`
- `--tailscale-target <target>`
- `--push-endpoint <url>`
- `--json`
例:
```bash
openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail setup --account you@example.com --project my-gcp-project --json
openclaw webhooks gmail setup --account you@example.com --hook-url https://gateway.example.com/hooks/gmail
```
### `webhooks gmail run`
`gog watch serve` と watch の自動更新ループを実行します。
オプション:
- `--account <email>`
- `--topic <topic>`
- `--subscription <name>`
- `--label <label>`
- `--hook-url <url>`
- `--hook-token <token>`
- `--push-token <token>`
- `--bind <host>`
- `--port <port>`
- `--path <path>`
- `--include-body`
- `--max-bytes <n>`
- `--renew-minutes <n>`
- `--tailscale <funnel|serve|off>`
- `--tailscale-path <path>`
- `--tailscale-target <target>`
例:
```bash
openclaw webhooks gmail run --account you@example.com
```
エンドツーエンドのセットアップ手順と運用の詳細については、[Gmail Pub/Sub documentation](/ja-JP/automation/cron-jobs#gmail-pubsub-integration) を参照してください。

175
docs/ja-JP/concepts/agent-loop.md Normal file
View File

@ -0,0 +1,175 @@
---
read_when:
- エージェントループまたはライフサイクルイベントの正確なウォークスルーが必要な場合
summary: エージェントループのライフサイクル、ストリーム、待機セマンティクス
title: Agent Loop
x-i18n:
generated_at: "2026-04-05T12:40:49Z"
model: gpt-5.4
provider: openai
source_hash: 8e562e63c494881e9c345efcb93c5f972d69aaec61445afc3d4ad026b2d26883
source_path: concepts/agent-loop.md
workflow: 15
---
# Agent Loop (OpenClaw)
エージェントループとは、エージェントの完全な「実際の」実行全体を指します: 取り込み → コンテキストの組み立て → モデル推論 →
ツール実行 → 返信のストリーミング → 永続化。これは、セッション状態の一貫性を保ちながら、
メッセージをアクションと最終返信に変換する正式な経路です。
OpenClawでは、ループはセッションごとに単一の直列化された実行であり、モデルが思考し、ツールを呼び出し、出力をストリーミングする間、
ライフサイクルイベントとストリームイベントを発行します。このドキュメントでは、その実際のループがエンドツーエンドでどのように接続されているかを説明します。
## エントリポイント
- Gateway RPC: `agent` と `agent.wait`。
- CLI: `agent` コマンド。
## 動作のしくみ（概要）
1. `agent` RPC はパラメータを検証し、セッション（sessionKey/sessionId）を解決し、セッションメタデータを永続化して、即座に `{ runId, acceptedAt }` を返します。
2. `agentCommand` がエージェントを実行します:
- モデル + thinking/verbose のデフォルトを解決
- Skillsスナップショットを読み込み
- `runEmbeddedPiAgent` を呼び出す（pi-agent-core ランタイム）
- 埋め込みループが発行しない場合は **lifecycle end/error** を発行
3. `runEmbeddedPiAgent`:
- セッションごと + グローバルキューごとに実行を直列化
- モデル + auth profile を解決し、pi セッションを構築
- pi イベントを購読し、assistant/tool の差分をストリーミング
- タイムアウトを強制し、超過した場合は実行を中止
- ペイロード + 使用量メタデータを返す
4. `subscribeEmbeddedPiSession` は pi-agent-core イベントを OpenClaw の `agent` ストリームへブリッジします:
- ツールイベント => `stream: "tool"`
- assistant の差分 => `stream: "assistant"`
- ライフサイクルイベント => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
5. `agent.wait` は `waitForAgentRun` を使用します:
- `runId` に対する **lifecycle end/error** を待機
- `{ status: ok|error|timeout, startedAt, endedAt, error? }` を返す
## キューイング + 並行性
- 実行はセッションキーごと（セッションレーン）に直列化され、必要に応じてグローバルレーンも通ります。
- これによりツール/セッションの競合を防ぎ、セッション履歴の一貫性を保ちます。
- メッセージングチャネルは、このレーンシステムに流し込まれるキューモード（collect/steer/followup）を選択できます。
詳しくは [Command Queue](/concepts/queue) を参照してください。
## セッション + ワークスペースの準備
- ワークスペースが解決および作成されます。サンドボックス化された実行では、サンドボックスワークスペースルートにリダイレクトされることがあります。
- Skills が読み込まれ（またはスナップショットから再利用され）、env とプロンプトに注入されます。
- Bootstrap/context ファイルが解決され、システムプロンプトレポートに注入されます。
- セッション書き込みロックが取得され、`SessionManager` が開かれてストリーミング前に準備されます。
## プロンプトの組み立て + システムプロンプト
- システムプロンプトは、OpenClaw のベースプロンプト、Skills プロンプト、bootstrap context、および実行ごとのオーバーライドから構築されます。
- モデル固有の制限と compaction のための予約トークンが適用されます。
- モデルが何を見るかについては、[System prompt](/concepts/system-prompt) を参照してください。
## フックポイント（介入できる場所）
OpenClaw には 2 つのフックシステムがあります:
- **内部フック**（Gatewayフック）: コマンドおよびライフサイクルイベント用のイベント駆動スクリプト。
- **プラグインフック**: エージェント/ツールのライフサイクルおよび Gateway パイプライン内の拡張ポイント。
### 内部フック（Gatewayフック）
- **`agent:bootstrap`**: システムプロンプトが確定する前に bootstrap ファイルを構築している間に実行されます。
これを使って bootstrap context ファイルを追加/削除します。
- **コマンドフック**: `/new`、`/reset`、`/stop`、およびその他のコマンドイベント（Hooks ドキュメントを参照）。
セットアップと例については、[Hooks](/ja-JP/automation/hooks) を参照してください。
### プラグインフック（エージェント + Gateway ライフサイクル）
これらはエージェントループ内または Gateway パイプライン内で実行されます:
- **`before_model_resolve`**: モデル解決前に、provider/model を決定的にオーバーライドするために、セッション前（`messages` なし）で実行されます。
- **`before_prompt_build`**: セッション読み込み後（`messages` あり）に実行され、プロンプト送信前に `prependContext`、`systemPrompt`、`prependSystemContext`、または `appendSystemContext` を注入します。ターンごとの動的テキストには `prependContext` を使い、システムプロンプト空間に置くべき安定したガイダンスには system-context フィールドを使ってください。
- **`before_agent_start`**: 旧来の互換性フックで、どちらのフェーズでも実行される可能性があります。上記の明示的なフックを優先してください。
- **`before_agent_reply`**: インラインアクションの後、LLM 呼び出しの前に実行され、プラグインがそのターンを引き受けて合成返信を返したり、そのターンを完全に無音化したりできます。
- **`agent_end`**: 完了後に最終メッセージリストと実行メタデータを検査します。
- **`before_compaction` / `after_compaction`**: compaction サイクルを観察または注釈付けします。
- **`before_tool_call` / `after_tool_call`**: ツールのパラメータ/結果をインターセプトします。
- **`before_install`**: 組み込みスキャンの検出結果を検査し、必要に応じて Skill またはプラグインのインストールをブロックします。
- **`tool_result_persist`**: ツール結果がセッショントランスクリプトに書き込まれる前に、同期的に変換します。
- **`message_received` / `message_sending` / `message_sent`**: 受信 + 送信メッセージフック。
- **`session_start` / `session_end`**: セッションライフサイクルの境界。
- **`gateway_start` / `gateway_stop`**: Gateway ライフサイクルイベント。
送信/ツールガードのためのフック判断ルール:
- `before_tool_call`: `{ block: true }` は終端であり、より低い優先度のハンドラーを停止します。
- `before_tool_call`: `{ block: false }` は no-op であり、以前のブロックを解除しません。
- `before_install`: `{ block: true }` は終端であり、より低い優先度のハンドラーを停止します。
- `before_install`: `{ block: false }` は no-op であり、以前のブロックを解除しません。
- `message_sending`: `{ cancel: true }` は終端であり、より低い優先度のハンドラーを停止します。
- `message_sending`: `{ cancel: false }` は no-op であり、以前のキャンセルを解除しません。
フック API と登録の詳細については、[Plugin hooks](/plugins/architecture#provider-runtime-hooks) を参照してください。
## ストリーミング + 部分返信
- assistant の差分は pi-agent-core からストリーミングされ、`assistant` イベントとして発行されます。
- ブロックストリーミングは、`text_end` または `message_end` で部分返信を発行できます。
- reasoning ストリーミングは、別ストリームとして、またはブロック返信として発行できます。
- チャンク化とブロック返信の動作については、[Streaming](/concepts/streaming) を参照してください。
## ツール実行 + メッセージングツール
- ツール開始/更新/終了イベントは `tool` ストリームで発行されます。
- ツール結果は、ログ記録/発行前に、サイズと画像ペイロードについてサニタイズされます。
- 重複する assistant 確認を抑制するために、メッセージングツール送信は追跡されます。
## 返信の整形 + 抑制
- 最終ペイロードは、以下から組み立てられます:
- assistant テキスト（および任意の reasoning）
- インラインツール要約（verbose が有効で許可されている場合）
- モデルエラー時の assistant エラーテキスト
- 完全一致の無音トークン `NO_REPLY` / `no_reply` は、送信ペイロードから
フィルタリングされます。
- メッセージングツールの重複は、最終ペイロードリストから削除されます。
- 描画可能なペイロードが残っておらず、かつツールがエラーになった場合は、
フォールバックのツールエラー返信が発行されます
（ただし、メッセージングツールがすでにユーザーに見える返信を送信している場合を除きます）。
## compaction + リトライ
- 自動 compaction は `compaction` ストリームイベントを発行し、リトライをトリガーすることがあります。
- リトライ時には、出力の重複を避けるために、インメモリバッファとツール要約がリセットされます。
- compaction パイプラインについては、[Compaction](/concepts/compaction) を参照してください。
## イベントストリーム（現時点）
- `lifecycle`: `subscribeEmbeddedPiSession` によって発行されます（およびフォールバックとして `agentCommand` からも発行されます）
- `assistant`: pi-agent-core からのストリーミング差分
- `tool`: pi-agent-core からのストリーミングツールイベント
## チャットチャネルの処理
- assistant の差分はチャットの `delta` メッセージにバッファされます。
- チャットの `final` は **lifecycle end/error** で発行されます。
## タイムアウト
- `agent.wait` のデフォルト: 30 秒（待機のみ）。`timeoutMs` パラメータで上書きします。
- エージェント実行時間: `agents.defaults.timeoutSeconds` のデフォルトは 172800 秒（48 時間）で、`runEmbeddedPiAgent` の abort timer で強制されます。
## 途中で早期終了する可能性がある場所
- エージェントのタイムアウト（abort）
- AbortSignal（キャンセル）
- Gateway の切断または RPC タイムアウト
- `agent.wait` タイムアウト（待機のみで、エージェントは停止しません）
## 関連
- [Tools](/tools) — 利用可能なエージェントツール
- [Hooks](/ja-JP/automation/hooks) — エージェントライフサイクルイベントでトリガーされるイベント駆動スクリプト
- [Compaction](/concepts/compaction) — 長い会話がどのように要約されるか
- [Exec Approvals](/tools/exec-approvals) — シェルコマンドの承認ゲート
- [Thinking](/tools/thinking) — thinking/reasoning レベルの設定

250
docs/ja-JP/concepts/agent-workspace.md Normal file
View File

@ -0,0 +1,250 @@
---
read_when:
- エージェントワークスペースまたはそのファイルレイアウトを説明する必要がある場合
- エージェントワークスペースをバックアップまたは移行したい場合
summary: 'エージェントワークスペース: 場所、レイアウト、バックアップ戦略'
title: Agent Workspace
x-i18n:
generated_at: "2026-04-05T12:40:45Z"
model: gpt-5.4
provider: openai
source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a
source_path: concepts/agent-workspace.md
workflow: 15
---
# Agent Workspace
ワークスペースはエージェントのホームです。これはファイルツールとワークスペースコンテキストで使用される唯一の作業ディレクトリです。
これを非公開に保ち、メモリとして扱ってください。
これは `~/.openclaw/` とは別で、そちらには設定、認証情報、セッションが保存されます。
**重要:** ワークスペースは**デフォルトのcwd**であり、厳格なサンドボックスではありません。ツールは
相対パスをワークスペース基準で解決しますが、サンドボックス化が有効でない限り、絶対パスは引き続きホスト上の
他の場所に到達できます。分離が必要な場合は、
[`agents.defaults.sandbox`](/gateway/sandboxing)（および必要に応じてエージェントごとのサンドボックス設定）を使用してください。
サンドボックス化が有効で、`workspaceAccess` が `"rw"` でない場合、ツールはホストワークスペースではなく、
`~/.openclaw/sandboxes` 配下のサンドボックスワークスペース内で動作します。
## デフォルトの場所
- デフォルト: `~/.openclaw/workspace`
- `OPENCLAW_PROFILE` が設定されていて `"default"` でない場合、デフォルトは
`~/.openclaw/workspace-<profile>` になります。
- `~/.openclaw/openclaw.json` で上書きできます:
```json5
{
agent: {
workspace: "~/.openclaw/workspace",
},
}
```
`openclaw onboard`、`openclaw configure`、または `openclaw setup` は、ワークスペースが存在しない場合に
それを作成し、bootstrapファイルを初期投入します。
サンドボックス用のseedコピーは、ワークスペース内の通常ファイルのみを受け付けます。ソースワークスペース外を
指すsymlink/hardlinkエイリアスは無視されます。
すでにワークスペースファイルを自分で管理している場合は、bootstrapファイルの作成を無効にできます:
```json5
{ agent: { skipBootstrap: true } }
```
## 追加のワークスペースフォルダー
古いインストールでは `~/openclaw` が作成されていることがあります。
複数のワークスペースディレクトリを残しておくと、同時にアクティブなのは1つだけであるため、認証や状態のずれで
混乱を招く可能性があります。
**推奨:** アクティブなワークスペースは1つだけにしてください。追加のフォルダーをもう使っていない場合は、
アーカイブするかゴミ箱に移動してください（例: `trash ~/openclaw`）。
意図的に複数のワークスペースを維持する場合は、
`agents.defaults.workspace` がアクティブなものを指していることを確認してください。
`openclaw doctor` は、追加のワークスペースディレクトリを検出すると警告します。
## ワークスペースファイルマップ（各ファイルの意味）
これらは、OpenClawがワークスペース内にあることを想定している標準ファイルです:
- `AGENTS.md`
- エージェント向けの運用指示と、メモリの使い方。
- 毎セッションの開始時に読み込まれます。
- ルール、優先順位、「どう振る舞うか」の詳細を書くのに適しています。
- `SOUL.md`
- ペルソナ、トーン、境界。
- 毎セッションで読み込まれます。
- ガイド: [SOUL.md Personality Guide](/concepts/soul)
- `USER.md`
- ユーザーが誰で、どう呼びかけるか。
- 毎セッションで読み込まれます。
- `IDENTITY.md`
- エージェントの名前、雰囲気、絵文字。
- bootstrap ritualの間に作成または更新されます。
- `TOOLS.md`
- ローカルツールと慣習に関するメモ。
- ツールの可用性は制御せず、ガイダンスにすぎません。
- `HEARTBEAT.md`
- heartbeat実行用の任意の小さなチェックリスト。
- トークン消費を避けるため、短く保ってください。
- `BOOT.md`
- internal hooksが有効な場合に、Gateway再起動時に実行される任意の起動チェックリスト。
- 短く保ち、外向きの送信にはmessageツールを使ってください。
- `BOOTSTRAP.md`
- 初回実行時の一度きりのritual。
- 新規ワークスペースに対してのみ作成されます。
- ritualが完了したら削除してください。
- `memory/YYYY-MM-DD.md`
- 日次メモリログ（1日1ファイル）。
- セッション開始時に今日分と昨日分を読むことを推奨します。
- `MEMORY.md`（任意）
- キュレーションされた長期メモリ。
- mainの非公開セッションでのみ読み込んでください（共有/グループコンテキストでは読み込まないでください）。
ワークフローと自動メモリフラッシュについては [Memory](/concepts/memory) を参照してください。
- `skills/`（任意）
- ワークスペース固有のSkills。
- そのワークスペースにおける最優先のSkill配置場所です。
- 名前が衝突した場合、project agent skills、personal agent skills、managed skills、bundled skills、
および `skills.load.extraDirs` より優先されます。
- `canvas/`（任意）
- ノード表示用のCanvas UIファイル（例: `canvas/index.html`）。
bootstrapファイルが欠けている場合、OpenClawはセッションに「missing file」マーカーを挿入して継続します。
大きなbootstrapファイルは挿入時に切り詰められます。
上限は `agents.defaults.bootstrapMaxChars`（デフォルト: 20000）および
`agents.defaults.bootstrapTotalMaxChars`（デフォルト: 150000）で調整してください。
`openclaw setup` は、既存ファイルを上書きせずに不足しているデフォルトを再作成できます。
## ワークスペースに含まれないもの
これらは `~/.openclaw/` 配下にあり、ワークスペースrepoにはコミットすべきではありません:
- `~/.openclaw/openclaw.json`（設定）
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（モデル認証プロファイル: OAuth + API keys）
- `~/.openclaw/credentials/`（channel/provider状態とレガシーOAuthインポートデータ）
- `~/.openclaw/agents/<agentId>/sessions/`（セッショントランスクリプト + メタデータ）
- `~/.openclaw/skills/`（managed skills）
セッションや設定を移行する必要がある場合は、それらを別途コピーし、
バージョン管理の対象外にしてください。
## Gitバックアップ（推奨、非公開）
ワークスペースは非公開のメモリとして扱ってください。バックアップと復旧ができるように、
**非公開**のgit repoに入れてください。
これらの手順は、Gatewayが動作しているマシン上で実行してください（ワークスペースはそこにあります）。
### 1) repoを初期化する
gitがインストールされていれば、新規ワークスペースは自動的に初期化されます。
このワークスペースがまだrepoでない場合は、次を実行してください:
```bash
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
```
### 2) 非公開のremoteを追加する（初心者向けオプション）
オプションA: GitHub web UI
1. GitHubで新しい**非公開**リポジトリを作成します。
2. READMEで初期化しないでください（マージ競合を避けるため）。
3. HTTPSのremote URLをコピーします。
4. remoteを追加してpushします:
```bash
git branch -M main
git remote add origin <https-url>
git push -u origin main
```
オプションB: GitHub CLI（`gh`）
```bash
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
```
オプションC: GitLab web UI
1. GitLabで新しい**非公開**リポジトリを作成します。
2. READMEで初期化しないでください（マージ競合を避けるため）。
3. HTTPSのremote URLをコピーします。
4. remoteを追加してpushします:
```bash
git branch -M main
git remote add origin <https-url>
git push -u origin main
```
### 3) 継続的な更新
```bash
git status
git add .
git commit -m "Update memory"
git push
```
## シークレットをコミットしないでください
非公開repoであっても、ワークスペースにシークレットを保存しないでください:
- API keys、OAuth tokens、passwords、または非公開の認証情報。
- `~/.openclaw/` 配下のあらゆるもの。
- チャットや機密添付ファイルの生ダンプ。
機密参照をどうしても保存する必要がある場合は、プレースホルダーを使い、実際の
シークレットは別の場所に保管してください（パスワードマネージャー、環境変数、または `~/.openclaw/`）。
推奨される `.gitignore` の開始例:
```gitignore
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
```
## ワークスペースを新しいマシンに移す
1. 目的のパスにrepoをcloneします（デフォルトは `~/.openclaw/workspace`）。
2. `~/.openclaw/openclaw.json` で `agents.defaults.workspace` をそのパスに設定します。
3. `openclaw setup --workspace <path>` を実行して、不足しているファイルを初期投入します。
4. セッションが必要な場合は、古いマシンから `~/.openclaw/agents/<agentId>/sessions/` を
別途コピーしてください。
## 高度な注意事項
- マルチエージェントルーティングでは、エージェントごとに異なるワークスペースを使用できます。
ルーティング設定については [Channel routing](/ja-JP/channels/channel-routing) を参照してください。
- `agents.defaults.sandbox` が有効な場合、main以外のセッションは
`agents.defaults.sandbox.workspaceRoot` 配下のセッションごとのサンドボックスワークスペースを使用できます。
## 関連
- [Standing Orders](/ja-JP/automation/standing-orders) — ワークスペースファイル内の永続的な指示
- [Heartbeat](/gateway/heartbeat) — HEARTBEAT.mdワークスペースファイル
- [Session](/concepts/session) — セッション保存パス
- [Sandboxing](/gateway/sandboxing) — サンドボックス環境でのワークスペースアクセス

120
docs/ja-JP/concepts/agent.md Normal file
View File

@ -0,0 +1,120 @@
---
read_when:
- エージェントランタイム、ワークスペースのブートストラップ、またはセッション動作を変更する場合
summary: エージェントランタイム、ワークスペース契約、セッションブートストラップ
title: Agent Runtime
x-i18n:
generated_at: "2026-04-05T12:40:39Z"
model: gpt-5.4
provider: openai
source_hash: e2ff39f4114f009e5b1f86894ea4bb29b1c9512563b70d063f09ca7cde5e8948
source_path: concepts/agent.md
workflow: 15
---
# Agent Runtime
OpenClaw は単一の埋め込みエージェントランタイムを実行します。
## ワークスペース（必須）
OpenClaw は単一のエージェントワークスペースディレクトリ（`agents.defaults.workspace`）を、ツールおよびコンテキストのためのエージェントの**唯一の**作業ディレクトリ（`cwd`）として使用します。
推奨: `openclaw setup` を使用して、`~/.openclaw/openclaw.json` が存在しない場合は作成し、ワークスペースファイルを初期化します。
完全なワークスペースレイアウトとバックアップガイド: [Agent workspace](/concepts/agent-workspace)
`agents.defaults.sandbox` が有効な場合、メイン以外のセッションはこれを
`agents.defaults.sandbox.workspaceRoot` 配下のセッションごとのワークスペースで上書きできます（[Gateway configuration](/gateway/configuration) を参照）。
## ブートストラップファイル（注入されるもの）
`agents.defaults.workspace` 内で、OpenClaw は次のユーザー編集可能なファイルを想定しています。
- `AGENTS.md` — 操作手順 + 「記憶」
- `SOUL.md` — ペルソナ、境界、トーン
- `TOOLS.md` — ユーザー管理のツールメモ（例: `imsg`、`sag`、慣例）
- `BOOTSTRAP.md` — 初回実行時の一度きりの儀式（完了後に削除されます）
- `IDENTITY.md` — エージェント名 / 雰囲気 / 絵文字
- `USER.md` — ユーザープロフィール + 希望する呼ばれ方
新しいセッションの最初のターンで、OpenClaw はこれらのファイルの内容をエージェントコンテキストに直接注入します。
空のファイルはスキップされます。大きなファイルは、プロンプトを軽量に保つためにマーカー付きで切り詰め・省略されます（完全な内容はファイルを読んでください）。
ファイルが存在しない場合、OpenClaw は単一の「missing file」マーカー行を注入します（また、`openclaw setup` は安全なデフォルトテンプレートを作成します）。
`BOOTSTRAP.md` は**完全に新しいワークスペース**でのみ作成されます（ほかのブートストラップファイルが存在しない場合）。儀式の完了後にこれを削除した場合、以後の再起動時に再作成されることはありません。
ブートストラップファイルの作成を完全に無効にするには（事前投入済みワークスペース向け）、次を設定します。
```json5
{ agent: { skipBootstrap: true } }
```
## 組み込みツール
コアツール（read / exec / edit / write および関連システムツール）は、ツールポリシーに従って常に利用可能です。`apply_patch` は任意で、`tools.exec.applyPatch` によって制御されます。`TOOLS.md` は存在するツールの種類を制御しません。これは、それらを_どのように_使いたいかについてのガイダンスです。
## Skills
OpenClaw は次の場所から Skills を読み込みます（優先順位の高い順）。
- ワークスペース: `<workspace>/skills`
- プロジェクトエージェント Skills: `<workspace>/.agents/skills`
- 個人エージェント Skills: `~/.agents/skills`
- 管理対象 / ローカル: `~/.openclaw/skills`
- バンドル済み（インストールに同梱）
- 追加のスキルフォルダー: `skills.load.extraDirs`
Skills は設定 / 環境変数で制御できます（[Gateway configuration](/gateway/configuration) の `skills` を参照）。
## ランタイム境界
埋め込みエージェントランタイムは Pi エージェントコア（モデル、ツール、プロンプトパイプライン）上に構築されています。セッション管理、検出、ツール配線、チャンネル配信は、そのコアの上にある OpenClaw 所有のレイヤーです。
## セッション
セッショントランスクリプトは、次の場所に JSONL として保存されます。
- `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
セッション ID は安定しており、OpenClaw によって選択されます。
他のツールのレガシーセッションフォルダーは読み込まれません。
## ストリーミング中のステアリング
キューモードが `steer` の場合、受信メッセージは現在の実行に注入されます。
キューされたステアリングは、**現在のアシスタントターンがツール呼び出しの実行を完了した後**、次の LLM 呼び出しの前に配信されます。ステアリングは現在のアシスタントメッセージに残っているツール呼び出しをもはやスキップしません。代わりに、次のモデル境界でキューされたメッセージを注入します。
キューモードが `followup` または `collect` の場合、受信メッセージは現在のターンが終了するまで保持され、その後キューされたペイロードで新しいエージェントターンが開始されます。モード + デバウンス / 上限の動作については [Queue](/concepts/queue) を参照してください。
ブロックストリーミングは、完了したアシスタントブロックを終了し次第すぐに送信します。これは**デフォルトでオフ**です（`agents.defaults.blockStreamingDefault: "off"`）。
境界は `agents.defaults.blockStreamingBreak`（`text_end` または `message_end`、デフォルトは text_end）で調整します。
ソフトなブロック分割は `agents.defaults.blockStreamingChunk` で制御します（デフォルトは
800〜1200 文字。段落区切りを優先し、次に改行、最後に文を優先します）。
ストリーミングされたチャンクは `agents.defaults.blockStreamingCoalesce` で結合して
単一行のスパムを減らせます（送信前にアイドル時間ベースで結合）。Telegram 以外のチャンネルでは、
ブロック返信を有効にするために明示的な `*.blockStreaming: true` が必要です。
詳細なツールサマリーはツール開始時に出力されます（デバウンスなし）。Control UI は、
利用可能な場合にエージェントイベントを通じてツール出力をストリーミングします。
詳細: [Streaming + chunking](/concepts/streaming)。
## モデル参照
設定内のモデル参照（たとえば `agents.defaults.model` および `agents.defaults.models`）は、**最初の** `/` で分割して解析されます。
- モデルを設定するときは `provider/model` を使用します。
- モデル ID 自体に `/` が含まれる場合（OpenRouter スタイル）、プロバイダー接頭辞を含めてください（例: `openrouter/moonshotai/kimi-k2`）。
- プロバイダーを省略した場合、OpenClaw は最初にエイリアスを試し、その後、その正確なモデル ID に対する一意の設定済みプロバイダーマッチを試し、それでも見つからない場合にのみ設定済みのデフォルトプロバイダーにフォールバックします。そのプロバイダーが設定済みのデフォルトモデルを提供しなくなっている場合、OpenClaw は古い削除済みプロバイダーのデフォルトを表示する代わりに、最初に設定された provider/model にフォールバックします。
## 設定（最小限）
最低限、次を設定してください。
- `agents.defaults.workspace`
- `channels.whatsapp.allowFrom`（強く推奨）
---
_次へ: [Group Chats](/ja-JP/channels/group-messages)_ 🦞

Some files were not shown because too many files have changed in this diff Show More