# Brave Search Source: https://openclawdoc.org/brave-search Brave Search API を web_search プロバイダーとして使うための設定手順、認証情報、検索結果の扱いをまとめます。 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. キーを設定に保存するか、ゲートウェイ環境で `BRAVE_API_KEY` を設定します ## 設定例 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { tools: { web: { search: { provider: "brave", apiKey: "BRAVE_API_KEY_HERE", maxResults: 5, timeoutSeconds: 30, }, }, }, } ``` ## ツールパラメータ | パラメータ | 説明 | | ------------- | ------------------------------------------------ | | `query` | 検索クエリ（必須） | | `count` | 返される結果数（1〜10、デフォルトは 5） | | `country` | 2 文字の ISO 国コード（例: `"US"`、`"DE"`） | | `language` | 検索結果に使う ISO 639-1 言語コード（例: `"en"`、`"de"`、`"fr"`） | | `ui_lang` | UI 要素に使う ISO 言語コード | | `freshness` | 期間フィルター: `day`（24 時間）、`week`、`month`、`year` | | `date_after` | この日付以降に公開された結果のみを返します（YYYY-MM-DD） | | `date_before` | この日付以前に公開された結果のみを返します（YYYY-MM-DD） | **例:** ```javascript theme={"theme":{"light":"min-light","dark":"min-dark"}} // 国と言語を指定した検索 await web_search({ query: "renewable energy", country: "DE", language: "de", }); // 最近の結果（過去1週間） await web_search({ query: "AI news", freshness: "week", }); // 日付範囲検索 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) を参照してください。 * 結果はデフォルトで 15 分間キャッシュされます。`cacheTtlMinutes` で変更できます。 web\_search の設定全体については [Web ツール](/tools/web) を参照してください。 # BlueBubbles Source: https://openclawdoc.org/channels/bluebubbles BlueBubbles 経由で iMessage を OpenClaw に接続する設定ガイドです。REST 連携の特徴、ペアリング、送受信やリアクション対応範囲を確認できます。 ステータス: HTTP 経由で BlueBubbles の macOS サーバーと通信する同梱プラグインです。レガシーな `imsg` チャンネルより API が充実しており、導入も簡単なため、**iMessage 連携にはこちらを推奨**します。 ## 概要 * 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 呼び出しで処理します。 * 添付ファイルやステッカーは受信メディアとして取り込まれ、可能であればエージェントにも渡されます。 * ペアリングや許可リストの扱いは他のチャンネル (`/channels/pairing` など) と同様で、`channels.bluebubbles.allowFrom` とペアリングコードを利用します。 * リアクションは Slack や Telegram と同様にシステムイベントとして扱われるため、エージェントは返信前にその内容へ触れられます。 * 高度な機能として、編集、送信取り消し、スレッド返信、メッセージエフェクト、グループ管理を利用できます。 ## クイックスタート 1. Mac に BlueBubbles サーバーをインストールします ([bluebubbles.app/install](https://bluebubbles.app/install) の手順に従ってください)。 2. BlueBubbles の設定で、Web API を有効にし、パスワードを設定します。 3. `openclaw onboard` を実行して BlueBubbles を選択するか、手動で設定します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { bluebubbles: { enabled: true, serverUrl: "http://192.168.1.100:1234", password: "example-password", webhookPath: "/bluebubbles-webhook", }, }, } ``` 4. BlueBubbles の webhook をゲートウェイへ向けます (例: `https://your-gateway-host:3000/bluebubbles-webhook?password=`)。 5. ゲートウェイを起動します。webhook ハンドラーが登録され、ペアリングが始まります。 セキュリティに関する注意: * webhook 用のパスワードは必ず設定してください。 * webhook 認証は常に必須です。ループバックやプロキシ構成に関係なく、`channels.bluebubbles.password` と一致するパスワードまたは GUID を含まない BlueBubbles の webhook リクエストは拒否されます (例: `?password=` または `x-password`)。 * パスワード認証は、webhook 本文を最後まで読み込んだり解析したりする前に実行されます。 ## Messages.app をアクティブに保つ (VM / ヘッドレスセットアップ) 一部の macOS VM や常時稼働の構成では、Messages.app が「アイドル」状態になり、アプリを開くかフォアグラウンドに戻すまで受信イベントが止まることがあります。簡単な回避策として、AppleScript と LaunchAgent を使って **5 分ごとに Messages を刺激する** 方法があります。 ### 1) AppleScript を保存する 次の場所に保存します。 * `~/Scripts/poke-messages.scpt` スクリプト例です。非対話型で動作し、フォーカスは奪いません。 ```applescript theme={"theme":{"light":"min-light","dark":"min-dark"}} try tell application "Messages" if not running then launch end if -- プロセスの応答性を維持するためにスクリプティングインターフェースに触れる set _chatCount to (count of chats) end tell on error -- 一時的な障害 (初回起動プロンプト、ロックされたセッションなど) を無視する end try ``` ### 2) LaunchAgent をインストールする 次の場所に保存します。 * `~/Library/LaunchAgents/com.user.poke-messages.plist` ```xml theme={"theme":{"light":"min-light","dark":"min-dark"}} Label com.user.poke-messages ProgramArguments /bin/bash -lc /usr/bin/osascript "$HOME/Scripts/poke-messages.scpt" RunAtLoad StartInterval 300 StandardOutPath /tmp/poke-messages.log StandardErrorPath /tmp/poke-messages.err ``` 注意: * この設定は **300 秒ごと** と **ログイン時** に実行されます。 * 初回実行時には macOS の **Automation** プロンプト (`osascript` → Messages) が表示されることがあります。LaunchAgent を動かすのと同じユーザーセッションで承認してください。 読み込むには、次を実行します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ``` ウィザードでは次の項目を入力します。 * **サーバー URL** (必須): BlueBubbles サーバーアドレス (例: `http://192.168.1.100:1234`) * **パスワード** (必須): BlueBubbles サーバー設定からの API パスワード * **webhook パス** (オプション): デフォルトは `/bluebubbles-webhook` * **DM ポリシー**: pairing、allowlist、open、または disabled * **許可リスト**: 電話番号、メールアドレス、またはチャットターゲット CLI から BlueBubbles を追加することもできます。 ``` openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password ``` ## アクセス制御 (DM + グループ) DM: * デフォルト: `channels.bluebubbles.dmPolicy = "pairing"`。 * 未知の送信者にはペアリングコードが返され、承認されるまでメッセージは無視されます。コードの有効期限は 1 時間です。 * 承認には次のコマンドを使います。 * `openclaw pairing list bluebubbles` * `openclaw pairing approve bluebubbles ` * ペアリングが既定のトークン交換手段です。詳細は [ペアリング](/channels/pairing) を参照してください。 グループ: * `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (デフォルト: `allowlist`)。 * `allowlist` を設定した場合、`channels.bluebubbles.groupAllowFrom` でグループ内の実行許可元を制御します。 ### メンションゲーティング (グループ) BlueBubbles は、iMessage や WhatsApp と同じ考え方で、グループチャットのメンション制御をサポートします。 * メンションの検出には `agents.list[].groupChat.mentionPatterns` または `messages.groupChat.mentionPatterns` を使います。 * グループで `requireMention` が有効な場合、エージェントはメンションされたときだけ返信します。 * 認可済み送信者からの制御コマンドは、この制約を迂回できます。 グループ単位の設定例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { bluebubbles: { groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, // すべてのグループのデフォルト "iMessage;-;chat123": { requireMention: false }, // 特定のグループの上書き }, }, }, } ``` ### コマンドゲーティング * 制御コマンド (例: `/config`, `/model`) の実行には認可が必要です。 * コマンド実行の可否は `allowFrom` と `groupAllowFrom` で判定されます。 * 認可済み送信者は、グループ内でメンションがなくても制御コマンドを実行できます。 ## タイピング + 既読確認 * **タイピングインジケーター**: 応答生成の前後および生成中に自動送信されます。 * **既読通知**: `channels.bluebubbles.sendReadReceipts` で制御します (デフォルトは `true`)。 * **タイピングの終了**: OpenClaw はタイピング開始イベントを送信し、BlueBubbles 側で送信時またはタイムアウト時に自動解除されます。DELETE による手動停止は信頼できません。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { bluebubbles: { sendReadReceipts: false, // 既読確認を無効にする }, }, } ``` ## 高度なアクション 設定で有効にすると、BlueBubbles は高度なメッセージ操作をサポートします。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { bluebubbles: { actions: { reactions: true, // tapbacks (デフォルト: true) edit: true, // 送信済みメッセージの編集 (macOS 13+、macOS 26 Tahoe では壊れています) unsend: true, // メッセージの送信取り消し (macOS 13+) reply: true, // メッセージ GUID による返信スレッド sendWithEffect: true, // メッセージエフェクト (スラム、ラウドなど) 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`) * **sendAttachment**: メディア/ファイルの送信 (`to`, `buffer`, `filename`, `asVoice`) * ボイスメモ: **MP3** または **CAF** の音声を iMessage のボイスメッセージとして送るには `asVoice: true` を設定します。BlueBubbles は送信時に MP3 を CAF へ変換します。 ### メッセージ ID (短い vs 完全) OpenClaw はトークン節約のために *短い* メッセージ ID (例: `1`, `2`) を表示することがあります。 * `MessageSid` と `ReplyToId` には短い ID が入ることがあります。 * `MessageSidFull` / `ReplyToIdFull` にはプロバイダーの完全な ID が含まれています。 * 短い ID はメモリ上にのみ保持されるため、再起動やキャッシュ削除で失効する可能性があります。 * 各アクションは短い `messageId` と完全な `messageId` の両方を受け付けますが、短い ID が失効している場合はエラーになります。 永続的な自動化や保存用途では完全な ID を使ってください。 * テンプレート: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` * コンテキスト: 受信ペイロード内の `MessageSidFull` / `ReplyToIdFull` テンプレート変数の詳細は [設定](/gateway/configuration) を参照してください。 ## ブロックストリーミング 応答を 1 件のメッセージとして送るか、複数ブロックに分けてストリーミングするかを制御します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { bluebubbles: { blockStreaming: true, // ブロックストリーミングを有効にする (デフォルトはオフ) }, }, } ``` ## メディア + 制限 * 受信した添付ファイルはダウンロードされ、メディアキャッシュに保存されます。 * 受信と送信のメディア上限は `channels.bluebubbles.mediaMaxMb` で指定します (デフォルトは 8 MB)。 * 送信テキストは `channels.bluebubbles.textChunkLimit` に従って分割されます (デフォルトは 4000 文字)。 ## 設定リファレンス 完全な設定一覧は [設定](/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 許可リスト (ハンドル、メールアドレス、E.164 番号、`chat_id:*`, `chat_guid:*`)。 * `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (デフォルト: `allowlist`)。 * `channels.bluebubbles.groupAllowFrom`: グループ送信者許可リスト。 * `channels.bluebubbles.groups`: グループごとの設定 (`requireMention` など)。 * `channels.bluebubbles.sendReadReceipts`: 既読通知を送信するかどうか (デフォルトは `true`)。 * `channels.bluebubbles.blockStreaming`: ブロックストリーミングを有効にするかどうか (デフォルトは `false`。ストリーミング返信に必要)。 * `channels.bluebubbles.textChunkLimit`: 送信時のチャンクサイズ上限。単位は文字数です (デフォルトは 4000)。 * `channels.bluebubbles.chunkMode`: `length` (デフォルト) は `textChunkLimit` を超えたときだけ分割します。`newline` は文字数ベースの分割前に空行、つまり段落境界で区切ります。 * `channels.bluebubbles.mediaMaxMb`: 受信および送信メディアの上限。単位は MB です (デフォルトは 8)。 * `channels.bluebubbles.mediaLocalRoots`: 送信時に使えるローカルメディアパスとして許可する絶対ディレクトリの明示的な allowlist です。これを設定しない限り、ローカルパスからの送信は既定で拒否されます。アカウント単位で上書きする場合は `channels.bluebubbles.accounts..mediaLocalRoots` を使います。 * `channels.bluebubbles.historyLimit`: コンテキストに含めるグループメッセージの最大数 (`0` で無効化)。 * `channels.bluebubbles.dmHistoryLimit`: DM 履歴の制限。 * `channels.bluebubbles.actions`: 特定のアクションの有効化/無効化。 * `channels.bluebubbles.accounts`: マルチアカウント設定。 関連するグローバル設定: * `agents.list[].groupChat.mentionPatterns` (または `messages.groupChat.mentionPatterns`)。 * `messages.responsePrefix`。 ## 宛先指定 / 配信ターゲット 安定したルーティングには `chat_guid` の使用を推奨します。 * `chat_guid:iMessage;-;+15555550123` (グループに推奨) * `chat_id:123` * `chat_identifier:...` * ダイレクトハンドル: `+15555550123`, `user@example.com` * ダイレクトハンドルに既存の DM チャットがない場合、OpenClaw は `POST /api/v1/chat/new` を使って新規作成します。この操作には BlueBubbles Private API を有効にしておく必要があります。 ## セキュリティ * webhook リクエストは、クエリパラメーターまたはヘッダーの `guid` / `password` を `channels.bluebubbles.password` と照合して認証します。`localhost` からのリクエストも受け入れられます。 * API パスワードと webhook エンドポイントは秘密として扱ってください。認証情報と同じ水準で保護する必要があります。 * `localhost` を信頼する構成では、同一ホスト上のリバースプロキシが意図せずパスワードを回避してしまう可能性があります。ゲートウェイをプロキシ越しに公開する場合は、プロキシ側でも認証を必須にし、`gateway.trustedProxies` を設定してください。詳細は [ゲートウェイのセキュリティ](/gateway/security#reverse-proxy-configuration) を参照してください。 * BlueBubbles サーバーを LAN の外部に公開する場合は、HTTPS + ファイアウォールルールを有効にしてください。 ## トラブルシューティング * タイピングや既読イベントが止まった場合は、BlueBubbles の webhook ログを確認し、ゲートウェイのパスが `channels.bluebubbles.webhookPath` と一致していることを確認してください。 * ペアリングコードの有効期限は 1 時間です。`openclaw pairing list bluebubbles` と `openclaw pairing approve bluebubbles ` を利用してください。 * リアクションには BlueBubbles Private API (`POST /api/v1/message/react`) が必要です。利用中のサーバーバージョンで公開されているか確認してください。 * 編集/送信取り消しには、macOS 13+ および互換性のある BlueBubbles サーバーバージョンが必要です。macOS 26 (Tahoe) では、プライベート API の変更により、編集は現在壊れています。 * macOS 26 (Tahoe) ではグループアイコン更新も不安定で、API が成功を返しても新しいアイコンが同期されないことがあります。 * OpenClaw は BlueBubbles サーバーの macOS バージョンに基づいて、既知の不具合があるアクションを自動的に隠します。macOS 26 (Tahoe) で編集がまだ表示される場合は、`channels.bluebubbles.actions.edit=false` を設定して手動で無効化してください。 * ステータスやヘルス情報は `openclaw status --all` または `openclaw status --deep` で確認できます。 チャンネル全般の運用フローについては、[チャンネル](/channels) と [プラグイン](/tools/plugin) を参照してください。 # Broadcast Groups Source: https://openclawdoc.org/channels/broadcast-groups WhatsApp の Broadcast Groups を使って複数エージェントへ配信する方法をまとめます。実験的機能の前提、設定手順、運用上の注意点を確認できます。 **ステータス:** 実験的
**バージョン:** 2026.1.9 で追加 ## 概要 ブロードキャストグループを使うと、複数のエージェントが同じメッセージを同時に処理し、それぞれ応答できます。これにより、1 つの WhatsApp グループまたは DM の中で、役割ごとに分担したエージェントチームを 1 つの電話番号で運用できます。 現在対応しているのは **WhatsApp のみ** です (`web` チャンネル)。 ブロードキャストグループは、チャンネルの allowlist とグループの有効化ルールを評価したあとに適用されます。WhatsApp グループでは、OpenClaw が通常なら返信する場面でのみブロードキャストが実行されます。たとえば、グループ設定によってはメンション時にだけ反応します。 ## ユースケース ### 1. 特化したエージェントチーム 責務を小さく分けた複数のエージェントを配置できます。 ``` グループ: "開発チーム" エージェント: - CodeReviewer (コードスニペットをレビュー) - DocumentationBot (ドキュメントを生成) - SecurityAuditor (脆弱性をチェック) - TestGenerator (テストケースを提案) ``` 各エージェントは同じメッセージを処理し、それぞれの専門領域から応答します。 ### 2. 多言語サポート ``` グループ: "国際サポート" エージェント: - Agent_EN (英語で応答) - Agent_DE (ドイツ語で応答) - Agent_ES (スペイン語で応答) ``` ### 3. 品質保証ワークフロー ``` グループ: "カスタマーサポート" エージェント: - SupportAgent (回答を提供) - QAAgent (品質をレビュー、問題が見つかった場合のみ応答) ``` ### 4. タスク自動化 ``` グループ: "プロジェクト管理" エージェント: - TaskTracker (タスクデータベースを更新) - TimeLogger (費やした時間を記録) - ReportGenerator (要約を作成) ``` ## 設定 ### 基本設定 トップレベルに `broadcast` セクションを追加します (`bindings` と同じ階層です)。キーには WhatsApp の peer ID を使います。 * グループチャット: グループ JID (例: `120363403215116621@g.us`) * DM: E.164 形式の電話番号 (例: `+15551234567`) ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "broadcast": { "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"] } } ``` **結果:** OpenClaw がこのチャットで返信対象になったとき、3 つのエージェントすべてが実行されます。 ### 処理戦略 メッセージ処理の進め方も指定できます。 #### Parallel (並列、デフォルト) すべてのエージェントが同時に処理します。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "broadcast": { "strategy": "parallel", "120363403215116621@g.us": ["alfred", "baerbel"] } } ``` #### Sequential (順次) エージェントを順番に処理します。後続のエージェントは、前のエージェントの完了を待ちます。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "broadcast": { "strategy": "sequential", "120363403215116621@g.us": ["alfred", "baerbel"] } } ``` ### 完全な例 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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. **ブロードキャスト判定**: システムが peer ID が `broadcast` に含まれているか確認します。 3. **ブロードキャストリストにある場合**: * 指定されたすべてのエージェントがメッセージを処理します。 * 各エージェントは固有のセッションキーと独立したコンテキストを持ちます。 * 処理方式は並列 (デフォルト) または順次です。 4. **ブロードキャストリストにない場合**: * 通常のルーティングが適用されます (最初に一致した binding が使われます)。 注意: ブロードキャストグループは、チャンネル allowlist やグループの有効化ルール (メンション、コマンドなど) を迂回しません。変更されるのは、メッセージが処理対象になったときに **どのエージェントを実行するか** だけです。 ### セッションの分離 ブロードキャストグループ内の各エージェントは、次の要素をそれぞれ独立して持ちます。 * **セッションキー** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`) * **会話履歴** (ほかのエージェントの発言は見えません) * **ワークスペース** (設定されている場合は別々のサンドボックス) * **ツールアクセス** (異なる許可 / 拒否リスト) * **メモリ/コンテキスト** (別々の IDENTITY.md、SOUL.md など) * **グループコンテキストバッファ** (直近のグループメッセージに基づくコンテキスト) は peer ごとに共有されるため、トリガー時にはすべてのブロードキャストエージェントが同じ入力コンテキストを参照します。 この構成により、各エージェントごとに次の要素を変えられます。 * 異なる性格や役割 * 異なるツールアクセス (例: 読み取り専用と読み書き可能) * 異なるモデル (例: `opus` と `sonnet`) * 異なるインストール済みスキル ### 例: セッション分離 グループ `120363403215116621@g.us` に `["alfred", "baerbel"]` を割り当てた場合の例です。 **Alfred のコンテキスト** ``` Session: agent:alfred:whatsapp:group:120363403215116621@g.us History: [ユーザーメッセージ, alfred の過去の応答] Workspace: /Users/pascal/openclaw-alfred/ Tools: read, write, exec ``` **Bärbel のコンテキスト** ``` Session: agent:baerbel:whatsapp:group:120363403215116621@g.us History: [ユーザーメッセージ, baerbel の過去の応答] Workspace: /Users/pascal/openclaw-baerbel/ Tools: read only ``` ## ベストプラクティス ### 1. エージェントの焦点を絞る 各エージェントは 1 つの明確な責務に絞って設計してください。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "broadcast": { "DEV_GROUP": ["formatter", "linter", "tester"] } } ``` ✅ **良い例:** 各エージェントが 1 つの仕事を持つ ❌ **悪い例:** 1 つの汎用的な「dev-helper」エージェント ### 2. 役割が分かる名前を付ける エージェント名から役割が分かるようにします。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "agents": { "security-scanner": { "name": "Security Scanner" }, "code-formatter": { "name": "Code Formatter" }, "test-generator": { "name": "Test Generator" } } } ``` ### 3. 必要なツールだけ許可する 各エージェントには必要最小限のツールだけを与えます。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "agents": { "reviewer": { "tools": { "allow": ["read", "exec"] } // 読み取り専用 }, "fixer": { "tools": { "allow": ["read", "write", "edit", "exec"] } // 読み書き可能 } } } ``` ### 4. パフォーマンスを意識する エージェント数が多い場合は、次の点を検討してください。 * 速度重視なら `"strategy": "parallel"` (デフォルト) を使う * ブロードキャストグループの規模を 5〜10 エージェント程度に抑える * 単純な役割のエージェントには高速なモデルを使う ### 5. 障害は個別に扱う 各エージェントは独立して失敗します。1 つのエージェントのエラーが、ほかのエージェントを止めることはありません。 ``` メッセージ → [Agent A ✓, Agent B ✗ エラー, Agent C ✓] 結果: Agent A と C は応答し、Agent B はエラーをログに記録する ``` ## 互換性 ### プロバイダー 現時点でブロードキャストグループが動作するのは次のプロバイダーです。 * ✅ WhatsApp (実装済み) * 🚧 Telegram (予定) * 🚧 Discord (予定) * 🚧 Slack (予定) ### ルーティング ブロードキャストグループは既存のルーティング設定と併用できます。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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. peer ID の形式が正しい (例: `120363403215116621@g.us`) 3. エージェントが denylist に入っていない **デバッグ:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} tail -f ~/.openclaw/logs/gateway.log | grep broadcast ``` ### 1 つのエージェントしか応答しない場合 **原因:** peer ID が `bindings` には存在するものの、`broadcast` に入っていない可能性があります。 **対処:** `broadcast` 設定へ追加するか、`bindings` から削除してください。 ### パフォーマンスに問題がある場合 **多数のエージェントで遅いとき** * 1 グループあたりのエージェント数を減らす * より軽量なモデルを使う (`opus` の代わりに `sonnet`) * サンドボックスの起動時間を確認する ## 例 ### 例 1: コードレビューチーム ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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 リファレンス ### Config Schema ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} interface OpenClawConfig { broadcast?: { strategy?: "parallel" | "sequential"; [peerId: string]: string[]; }; } ``` ### フィールド * `strategy` (オプション): エージェントの処理方法 * `"parallel"` (デフォルト): すべてのエージェントを同時に実行します * `"sequential"`: 配列の順序でエージェントを実行します * `[peerId]`: WhatsApp グループ JID、E.164 番号、またはその他の peer ID * 値: その peer のメッセージを処理するエージェント ID の配列 ## 制限事項 1. **最大エージェント数:** 厳密な上限はありませんが、10 個を超えると遅くなる可能性があります。 2. **共有コンテキスト:** エージェント同士は互いの応答を見ません。これは設計上の仕様です。 3. **メッセージ順序:** 並列実行時は応答順が保証されません。 4. **レート制限:** すべてのエージェント実行が WhatsApp のレート制限にカウントされます。 ## 今後の機能強化 予定されている機能: * [ ] 共有コンテキストモード (エージェント同士が互いの応答を参照できる) * [ ] エージェント間の連携 (エージェント同士でシグナルを送れる) * [ ] 動的なエージェント選択 (メッセージ内容に応じて実行対象を決める) * [ ] エージェント優先順位 (一部のエージェントを先に応答させる) ## 関連項目 * [マルチエージェント設定](/tools/multi-agent-sandbox-tools) * [ルーティング設定](/channels/channel-routing) * [セッション管理](/concepts/session) # Channel Routing Source: https://openclawdoc.org/channels/channel-routing チャンネル別のルーティング規則を整理したガイドです。共有コンテキストの扱い、アカウント単位の振り分け、受信時の動作を確認できます。 OpenClaw は、メッセージを受信した **同じチャンネルへ返信** します。モデルが返信先チャンネルを選ぶことはなく、ルーティングは決定的で、ホスト側の設定によって制御されます。 ## 主要な用語 * **Channel**: `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `webchat` * **AccountId**: チャンネルごとのアカウントインスタンスです。対応しているチャンネルで使用されます。 * チャンネルごとの既定アカウント: `channels..defaultAccount` を使うと、送信時のパスで `accountId` を明示していない場合に使うアカウントを指定できます。 * マルチアカウント構成では、2 つ以上のアカウントがある場合に明示的な既定値 (`defaultAccount` または `accounts.default`) を設定してください。設定しないと、フォールバックルーティングで最初に正規化されたアカウント ID が選ばれることがあります。 * **AgentId**: 分離されたワークスペースとセッションストアを持つエージェント識別子です。 * **SessionKey**: コンテキスト保存と同時実行制御に使うキーです。 ## セッションキーの形式(例) ダイレクトメッセージはエージェントの **main** セッションに集約されます。 * `agent::` (デフォルト: `agent:main:main`) グループとチャンネルは、チャンネル単位で分離されたまま保持されます。 * グループ: `agent:::group:` * チャンネル/ルーム: `agent:::channel:` スレッド: * Slack / Discord のスレッドでは、ベースキーに `:thread:` が追加されます。 * Telegram のフォーラムトピックでは、グループキーに `:topic:` が含まれます。 例: * `agent:main:telegram:group:-1001234567890:topic:42` * `agent:main:discord:channel:123456:thread:987654` ## メインDMルートのピン留め `session.dmScope` が `main` の場合、ダイレクトメッセージは 1 つのメインセッションを共有することがあります。所有者以外の DM によってセッションの `lastRoute` が上書きされるのを防ぐため、OpenClaw は次の条件をすべて満たす場合に、`allowFrom` から固定対象の所有者を推定します。 * `allowFrom` にワイルドカード以外のエントリが 1 つだけある * そのエントリを、当該チャンネルの具体的な送信者 ID に正規化できる * 受信した DM の送信者が、その固定された所有者と一致しない この不一致が起きた場合でも、OpenClaw は受信セッションのメタデータは記録しますが、メインセッションの `lastRoute` は更新しません。 ## ルーティングルール(エージェントの選択方法) ルーティングでは、各受信メッセージに対して **1 つのエージェント** が選ばれます。 1. **完全一致する peer** (`peer.kind` + `peer.id` を持つ `bindings`) 2. **親 peer 一致** (スレッド継承) 3. **ギルド + ロール一致** (Discord、`guildId` + `roles`) 4. **ギルド一致** (Discord、`guildId`) 5. **チーム一致** (Slack、`teamId`) 6. **アカウント一致** (チャンネル上の `accountId`) 7. **チャンネル一致** (そのチャンネル上の任意アカウント、`accountId: "*"`) 8. **既定エージェント** (`agents.list[].default`、なければ最初のリスト項目、さらにフォールバックとして `main`) 1 つのバインディングに複数の一致条件 (`peer`、`guildId`、`teamId`、`roles`) が含まれている場合は、**指定されたすべての条件が一致したときだけ** そのバインディングが適用されます。 どのワークスペースとセッションストアを使うかは、最終的に一致したエージェントによって決まります。 ## ブロードキャストグループ(複数エージェントの実行) ブロードキャストグループを使うと、**OpenClaw が通常返信する場面** で、同じ peer に対して **複数のエージェント** を実行できます。たとえば WhatsApp グループでは、メンションやアクティベーションの条件を通過したあとに適用されます。 設定: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { broadcast: { strategy: "parallel", "120363403215116621@g.us": ["alfred", "baerbel"], "+15555550123": ["support", "logger"], }, } ``` 詳しくは [ブロードキャストグループ](/channels/broadcast-groups) を参照してください。 ## 設定の概要 * `agents.list`: 名前付きエージェントの定義です。ワークスペースやモデルなどを指定します。 * `bindings`: 受信したチャンネル、アカウント、peer をどのエージェントへ割り当てるかを定義します。 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }], }, bindings: [ { match: { channel: "slack", teamId: "T123" }, agentId: "support" }, { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" }, ], } ``` ## セッションストレージ セッションストアは、状態ディレクトリ (デフォルトは `~/.openclaw`) の下に配置されます。 * `~/.openclaw/agents//sessions/sessions.json` * JSONL 形式のトランスクリプトは、ストアと同じ場所に保存されます。 `session.store` と `{agentId}` テンプレートを使って保存先パスを上書きできます。 ## WebChatの動作 WebChat は **選択したエージェント** に接続され、既定ではそのエージェントのメインセッションを使います。そのため、同じエージェントが持つクロスチャンネルのコンテキストを 1 か所から確認できます。 ## 返信コンテキスト 受信した返信には、次の情報が含まれます。 * 利用可能な場合は `ReplyToId`、`ReplyToBody`、`ReplyToSender` * 引用コンテキストは `[Replying to ...]` ブロックとして `Body` に追加されます。 この挙動は、どのチャンネルでも共通です。 # Discord Source: https://openclawdoc.org/channels/discord Discord ボットを OpenClaw に接続する設定と運用ガイドです。DM・ギルドチャンネル対応、権限設定、ペアリング、主要な診断手順を確認できます。 ステータス: 公式 Discord ゲートウェイ経由で、DM とギルドチャンネルに対応しています。 Discord の DM はデフォルトでペアリングモードです。 ネイティブコマンドの挙動とコマンド一覧を確認できます。 チャンネル横断の診断手順と修復フローを確認できます。 ## クイックセットアップ 新しいアプリケーションとボットを作成し、ボットを Discord サーバーに追加したうえで、OpenClaw とペアリングする必要があります。ボットは、自分専用のプライベートサーバーに追加する構成を推奨します。まだサーバーがない場合は、先に [作成してください](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（**Create My Own > For me and my friends** を選択します）。 [Discord Developer Portal](https://discord.com/developers/applications) に移動し、**New Application** をクリックします。名前は「OpenClaw」などで構いません。 左側の **Bot** を開き、**Username** を OpenClaw エージェントとして使いたい名前に設定します。 引き続き **Bot** ページで、**Privileged Gateway Intents** までスクロールし、次を有効にします。 * **Message Content Intent**（必須） * **Server Members Intent**（推奨。ロール allowlist と名前から ID への解決に必要です） * **Presence Intent**（任意。プレゼンス更新を受信する場合のみ必要です） **Bot** ページ上部に戻り、**Reset Token** をクリックします。 名前に反して、ここでは最初のトークンが生成されます。既存の何かが「リセット」されるわけではありません。 表示されたトークンをコピーして安全な場所に保存します。これは **Bot Token** であり、後続の設定で使用します。 左側の **OAuth2** を開き、ボットをサーバーに追加するための招待 URL を生成します。 **OAuth2 URL Generator** までスクロールし、次を有効にします。 * `bot` * `applications.commands` その下に **Bot Permissions** が表示されるので、次を有効にします。 * View Channels * Send Messages * Read Message History * Embed Links * Attach Files * Add Reactions（任意） 下部に表示された URL をコピーしてブラウザで開き、対象サーバーを選択して **Continue** を押します。完了すると、Discord サーバーにボットが追加されます。 Discord アプリ側で Developer Mode を有効にし、内部 ID をコピーできるようにします。 1. **User Settings**（アバター横の歯車）→ **Advanced** → **Developer Mode** をオンにする 2. サイドバーの **サーバーアイコン** を右クリックして **Copy Server ID** 3. **自分のアバター** を右クリックして **Copy User ID** **Server ID** と **User ID** は、Bot Token とあわせて保存しておきます。次の手順でこの 3 つを使います。 ペアリングを成立させるには、Discord 側でボットから DM を受け取れる必要があります。**サーバーアイコン** を右クリックし、**Privacy Settings** を開いて **Direct Messages** をオンにします。 これにより、サーバーメンバー（ボットを含む）から DM を受信できます。OpenClaw で Discord DM を使う場合は、この設定を有効のままにしてください。ギルドチャンネルだけを使う予定であれば、ペアリング完了後に無効化しても構いません。 Discord のボットトークンは、パスワードと同様に機密情報です。エージェントへメッセージを送る前に、OpenClaw を動かしているマシンに設定してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json openclaw config set channels.discord.enabled true --json openclaw gateway ``` すでに OpenClaw をバックグラウンドサービスとして実行している場合は、`openclaw gateway restart` を使います。 既存のチャンネル（例: Telegram）で OpenClaw エージェントに次のように伝えます。Discord が最初のチャンネルである場合は、CLI / config タブを使ってください。 > 「Discord の bot token はすでに config に設定済みです。User ID `` と Server ID `` を使って Discord のセットアップを完了してください。」 ファイルベースで設定する場合は、次のように指定します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { enabled: true, token: "YOUR_BOT_TOKEN", }, }, } ``` デフォルトアカウントでは、環境変数によるフォールバックも使用できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} DISCORD_BOT_TOKEN=... ``` `channels.discord.token` には SecretRef（env/file/exec プロバイダー）も利用できます。詳しくは [Secrets Management](/gateway/secrets) を参照してください。 ゲートウェイが起動していることを確認したうえで、Discord からボットへ DM を送ります。ボットからペアリングコードが返されます。 既存のチャンネル上でエージェントにペアリングコードを送ります。 > 「この Discord のペアリングコードを承認してください: ``」 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list discord openclaw pairing approve discord ``` ペアリングコードの有効期限は 1 時間です。 これで Discord の DM からエージェントと会話できるようになります。 トークン解決はアカウント単位で行われます。config に設定されたトークンが環境変数より優先されます。`DISCORD_BOT_TOKEN` が使われるのはデフォルトアカウントだけです。 ## 推奨: ギルドワークスペースを用意する DM が動作したら、Discord サーバー全体をワークスペースとして構成できます。各チャンネルは独自のコンテキストを持つ個別のエージェントセッションになり、プライベートサーバーではこの構成が特に有効です。 これにより、エージェントは DM だけでなく、サーバー内のチャンネルにも応答できるようになります。 > 「Discord Server ID `` を guild allowlist に追加してください」 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { groupPolicy: "allowlist", guilds: { YOUR_SERVER_ID: { requireMention: true, users: ["YOUR_USER_ID"], }, }, }, }, } ``` デフォルトでは、ギルドチャンネルではエージェントへの @mention がある場合だけ応答します。プライベートサーバーでは、すべてのメッセージに応答させたいケースが多くあります。 > 「このサーバーでは、@mention なしでもエージェントが応答できるようにしてください」 ギルド設定で `requireMention: false` を指定します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { guilds: { YOUR_SERVER_ID: { requireMention: false, }, }, }, }, } ``` デフォルトでは、長期メモリ（`MEMORY.md`）は DM セッションでのみ自動読み込みされます。ギルドチャンネルでは自動では読み込まれません。 > 「Discord チャンネルで質問したとき、`MEMORY.md` の長期コンテキストが必要なら `memory_search` または `memory_get` を使ってください」 すべてのチャンネルで共通コンテキストを使いたい場合は、安定した指示を `AGENTS.md` や `USER.md` に置きます。これらはすべてのセッションに注入されます。長期メモは `MEMORY.md` に保持し、必要なときだけメモリツールで参照する運用を推奨します。 ここまで完了したら、Discord サーバー上にいくつかチャンネルを作成して会話を始めてください。エージェントはチャンネル名を認識でき、各チャンネルには独立したセッションキーが割り当てられます。`#coding`、`#home`、`#research` など、用途ごとに分けて運用できます。 ## ランタイムモデル * ゲートウェイが Discord 接続を保持します。 * 応答ルーティングは決定的です。Discord から入った返信は Discord に返ります。 * デフォルトでは（`session.dmScope=main`）、DM はエージェントのメインセッション（`agent:main:main`）を共有します。 * ギルドチャンネルは独立したセッションキー（`agent::discord:channel:`）として扱われます。 * グループ DM はデフォルトで無視されます（`channels.discord.dm.groupEnabled=false`）。 * ネイティブスラッシュコマンドは独立したコマンドセッション（`agent::discord:slash:`）で実行されますが、ルーティング先の会話セッションに対する `CommandTargetSessionKey` は保持されます。 ## フォーラムチャンネル Discord の forum チャンネルと media チャンネルでは、投稿はスレッド形式のみ受け付けられます。OpenClaw では、次の 2 通りの作成方法に対応しています。 * forum 親（`channel:`）にメッセージを送信してスレッドを自動作成する * `openclaw message thread create` でスレッドを直接作成する。forum チャンネルでは `--message-id` を渡さないでください 例: forum 親に送信してスレッドを作成する ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` 例: forum スレッドを明示的に作成する ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` forum 親では Discord コンポーネントを受け付けません。コンポーネントが必要な場合は、スレッド本体（`channel:`）に送信してください。 ## インタラクティブコンポーネント OpenClaw は、エージェントメッセージ向けに Discord components v2 コンテナをサポートしています。`components` ペイロードを含む message ツールを使用してください。インタラクション結果は通常の受信メッセージとしてエージェントへ戻り、既存の Discord `replyToMode` 設定に従って処理されます。 サポートされるブロック: * `text`、`section`、`separator`、`actions`、`media-gallery`、`file` * action row では最大 5 個のボタン、または 1 個の select menu を使用できます * select の型は `string`、`user`、`role`、`mentionable`、`channel` です デフォルトでは、コンポーネントは 1 回限りの利用です。`components.reusable=true` を指定すると、有効期限が切れるまでボタン、select、フォームを複数回利用できます。 ボタンを押せるユーザーを制限するには、そのボタンに `allowedUsers` を設定します（Discord ユーザー ID、タグ、または `*`）。設定されている場合、一致しないユーザーには一時的な拒否メッセージが返されます。 `/model` と `/models` スラッシュコマンドでは、プロバイダーとモデルのドロップダウン、および Submit ステップを持つ対話型モデルピッカーが開きます。ピッカーの応答は ephemeral で、実行したユーザーだけが利用できます。 ファイル添付: * `file` ブロックは、添付参照（`attachment://`）を指している必要があります * 添付ファイルは `media` / `path` / `filePath`（単一ファイル）で渡します。複数ファイルには `media-gallery` を使用してください * 添付参照名とアップロード名を一致させたい場合は、`filename` でアップロード名を上書きします モーダルフォーム: * 最大 5 フィールドまで持てる `components.modal` を追加できます * フィールド型は `text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` です * OpenClaw がトリガーボタンを自動で追加します 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channel: "discord", action: "send", to: "channel:123456789012345678", message: "Optional fallback text", components: { reusable: true, text: "Choose a path", blocks: [ { type: "actions", buttons: [ { label: "Approve", style: "success", allowedUsers: ["123456789012345678"], }, { label: "Decline", style: "danger" }, ], }, { type: "actions", select: { type: "string", placeholder: "Pick an option", options: [ { label: "Option A", value: "a" }, { label: "Option B", value: "b" }, ], }, }, ], modal: { title: "Details", triggerLabel: "Open form", fields: [ { type: "text", label: "Requester" }, { type: "select", label: "Priority", options: [ { label: "Low", value: "low" }, { label: "High", value: "high" }, ], }, ], }, }, } ``` ## アクセス制御とルーティング `channels.discord.dmPolicy` は DM へのアクセスを制御します（旧設定: `channels.discord.dm.policy`）。 * `pairing`（デフォルト） * `allowlist` * `open`（`channels.discord.allowFrom` に `"*"` を含める必要があります。旧設定: `channels.discord.dm.allowFrom`） * `disabled` DM ポリシーが `open` でない場合、不明なユーザーはブロックされます。`pairing` モードではペアリングが要求されます。 マルチアカウント時の優先順位: * `channels.discord.accounts.default.allowFrom` は `default` アカウントにのみ適用されます * 名前付きアカウントは、自身の `allowFrom` が未設定なら `channels.discord.allowFrom` を継承します * 名前付きアカウントは `channels.discord.accounts.default.allowFrom` を継承しません DM 配信時のターゲット形式: * `user:` * `<@id>` 形式の mention 数値 ID を裸で渡すと曖昧になるため、明示的な user/channel ターゲット種別がない限り拒否されます。 ギルドの処理は `channels.discord.groupPolicy` で制御されます。 * `open` * `allowlist` * `disabled` `channels.discord` ブロックが存在する場合の安全なベースラインは `allowlist` です。 `allowlist` の挙動: * ギルドは `channels.discord.guilds` に一致する必要があります（`id` 推奨、slug も可） * 送信者 allowlist として `users` と `roles` を任意で指定できます。どちらかが設定されている場合、送信者は `users` または `roles` のどちらかに一致すれば許可されます * 直接の名前／タグ一致はデフォルトで無効です。互換性維持のための緊急措置としてのみ `channels.discord.dangerouslyAllowNameMatching: true` を使ってください * `users` には名前やタグも指定できますが、監査の安定性を考えると ID の使用を推奨します。`openclaw security audit` は名前／タグ指定に対して警告を出します * ギルドに `channels` が設定されている場合、列挙されていないチャンネルは拒否されます * ギルドに `channels` ブロックがなければ、その allowlist 対象ギルド内の全チャンネルが許可されます 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { groupPolicy: "allowlist", guilds: { "123456789012345678": { requireMention: true, ignoreOtherMentions: true, users: ["987654321098765432"], roles: ["123456789012345678"], channels: { general: { allow: true }, help: { allow: true, requireMention: true }, }, }, }, }, }, } ``` `DISCORD_BOT_TOKEN` だけを設定し、`channels.discord` ブロックを作成していない場合でも、ランタイムのフォールバックは `groupPolicy="allowlist"` です（ログに警告が出ます）。`channels.defaults.groupPolicy` が `open` でも同様です。 ギルドメッセージはデフォルトで mention によるゲート制御が有効です。 mention 検出には次が含まれます。 * ボットへの明示的な mention * 設定済みの mention パターン（`agents.list[].groupChat.mentionPatterns`、未設定時は `messages.groupChat.mentionPatterns`） * 対応ケースにおける、ボット宛て返信の暗黙的判定 `requireMention` はギルドまたはチャンネル単位（`channels.discord.guilds...`）で設定します。 `ignoreOtherMentions` を有効にすると、ボットに言及せず別のユーザーやロールだけを mention しているメッセージを無視できます（`@everyone` / `@here` は除外されます）。 グループ DM: * デフォルトでは無視されます（`dm.groupEnabled=false`） * 必要であれば `dm.groupChannels` で allowlist 指定できます（チャンネル ID または slug） ### ロールベースのエージェントルーティング `bindings[].match.roles` を使うと、Discord ギルドメンバーをロール ID に応じて別のエージェントへ振り分けられます。ロールベースの binding はロール ID のみを受け付け、評価順は peer / parent-peer binding の後、guild 単位 binding の前です。binding に `peer`、`guildId`、`roles` など複数の条件がある場合は、設定されたすべての条件に一致する必要があります。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { bindings: [ { agentId: "opus", match: { channel: "discord", guildId: "123456789012345678", roles: ["111111111111111111"], }, }, { agentId: "sonnet", match: { channel: "discord", guildId: "123456789012345678", }, }, ], } ``` ## Developer Portal の設定 1. Discord Developer Portal → **Applications** → **New Application** 2. **Bot** → **Add Bot** 3. ボットトークンをコピーする **Bot → Privileged Gateway Intents** で次を有効にします。 * Message Content Intent * Server Members Intent（推奨） Presence Intent は任意で、メンバーのプレゼンス更新を受信したい場合にのみ必要です。ボット自身のプレゼンス設定（`setPresence`）だけであれば、メンバー向けの presence updates を有効化する必要はありません。 OAuth URL generator: * scopes: `bot`, `applications.commands` 一般的な最小権限: * View Channels * Send Messages * Read Message History * Embed Links * Attach Files * Add Reactions（任意） 明示的に必要な場合を除き、`Administrator` は付与しないでください。 Discord の Developer Mode を有効にしたうえで、次の ID をコピーします。 * server ID * channel ID * user ID OpenClaw の設定では、監査や probe の信頼性のため、数値 ID の使用を推奨します。 ## ネイティブコマンドとコマンド認可 * `commands.native` のデフォルトは `"auto"` で、Discord では有効になります * チャンネル単位の上書きは `channels.discord.commands.native` です * `commands.native=false` を指定すると、以前に登録された Discord ネイティブコマンドを明示的に削除します * ネイティブコマンドの認可には、通常メッセージ処理と同じ Discord allowlist / policy が使われます * 権限のないユーザーにも Discord UI 上でコマンドが見えることがありますが、実行時には OpenClaw の認可が適用され、"not authorized" が返ります コマンド一覧と挙動は [Slash commands](/tools/slash-commands) を参照してください。 デフォルトのスラッシュコマンド設定: * `ephemeral: true` ## 機能の詳細 Discord は、エージェント出力に含まれる返信タグをサポートします。 * `[[reply_to_current]]` * `[[reply_to:]]` これらは `channels.discord.replyToMode` で制御されます。 * `off`（デフォルト） * `first` * `all` 注: `off` は暗黙的な reply threading を無効にしますが、明示的な `[[reply_to_*]]` タグは引き続き有効です。 メッセージ ID はコンテキストや履歴にも現れるため、エージェントは特定のメッセージを対象にできます。 OpenClaw は、一時メッセージを送信し、テキストの到着にあわせて編集することで、返信ドラフトをストリーミング表示できます。 * `channels.discord.streaming` はプレビュー配信を制御します（`off` | `partial` | `block` | `progress`、デフォルト: `off`） * `progress` はチャンネル間の一貫性のために受け付けられ、Discord では `partial` にマッピングされます * `channels.discord.streamMode` は旧エイリアスで、自動移行されます * `partial` では、トークン到着に応じて 1 つのプレビューメッセージを編集します * `block` では、ドラフトサイズのチャンク単位で出力します。サイズや分割位置は `draftChunk` で調整できます 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { streaming: "partial", }, }, } ``` `block` モードのデフォルトチャンク設定（`channels.discord.textChunkLimit` の範囲内に丸められます）: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { streaming: "block", draftChunk: { minChars: 200, maxChars: 800, breakPreference: "paragraph", }, }, }, } ``` プレビュー配信はテキストのみが対象で、メディア返信は通常の配信にフォールバックします。 注: preview streaming と block streaming は別機能です。Discord で block streaming が明示的に有効になっている場合、OpenClaw は二重配信を避けるため preview stream をスキップします。 ギルド履歴コンテキスト: * `channels.discord.historyLimit` のデフォルトは `20` * フォールバックは `messages.groupChat.historyLimit` * `0` を指定すると無効になります DM 履歴の制御: * `channels.discord.dmHistoryLimit` * `channels.discord.dms[""].historyLimit` スレッド挙動: * Discord スレッドはチャンネルセッションとしてルーティングされます * 親スレッドのメタデータは、親セッションとの関連付けに利用できます * スレッド固有の設定がない場合、スレッド設定は親チャンネル設定を継承します チャンネルトピックは **信頼されない** コンテキストとして注入されます。システムプロンプトとしては扱われません。 Discord では、スレッドを特定のセッションターゲットに固定できます。これにより、そのスレッドでの後続メッセージは同じセッション（サブエージェントセッションを含む）へ継続してルーティングされます。 コマンド: * `/focus ` 現在または新規スレッドをサブエージェント / セッションターゲットへ固定する * `/unfocus` 現在のスレッド固定を解除する * `/agents` アクティブな実行と binding 状態を表示する * `/session idle ` 固定中セッションの無操作による自動 unfocus 設定を確認 / 更新する * `/session max-age ` 固定中セッションの最大寿命を確認 / 更新する 設定: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { session: { threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0, }, }, channels: { discord: { threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0, spawnSubagentSessions: false, // opt-in }, }, }, } ``` 注意: * `session.threadBindings.*` はグローバルデフォルトを設定します * `channels.discord.threadBindings.*` は Discord 用の挙動を上書きします * `sessions_spawn({ thread: true })` に対してスレッドを自動作成 / 固定するには `spawnSubagentSessions` を true にする必要があります * ACP（`/acp spawn ... --thread ...` または `sessions_spawn({ runtime: "acp", thread: true })`）でスレッドを自動作成 / 固定するには `spawnAcpSessions` を true にする必要があります * アカウントで thread binding が無効化されている場合、`/focus` および関連操作は利用できません 詳しくは [Sub-agents](/tools/subagents)、[ACP Agents](/tools/acp-agents)、[Configuration Reference](/gateway/configuration-reference) を参照してください。 安定した「常時接続」型の ACP ワークスペースを実現するには、Discord 会話を対象にしたトップレベルの型付き ACP binding を設定します。 設定パス: * `bindings[]` に `type: "acp"` と `match.channel: "discord"` を指定します 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "codex", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/workspace/openclaw", }, }, }, ], }, bindings: [ { type: "acp", agentId: "codex", match: { channel: "discord", accountId: "default", peer: { kind: "channel", id: "222222222222222222" }, }, acp: { label: "codex-main" }, }, ], channels: { discord: { guilds: { "111111111111111111": { channels: { "222222222222222222": { requireMention: false, }, }, }, }, }, }, } ``` 注意: * スレッドメッセージは親チャンネルの ACP binding を継承できます * binding 済みのチャンネルまたはスレッドでは、`/new` と `/reset` は同じ ACP セッションをその場でリセットします * 一時的な thread binding も引き続き利用でき、アクティブな間はターゲット解決を上書きできます binding の詳細は [ACP Agents](/tools/acp-agents) を参照してください。 ギルド単位のリアクション通知モード: * `off` * `own`（デフォルト） * `all` * `allowlist`（`guilds..users` を使用） リアクションイベントはシステムイベントへ変換され、ルーティング済みの Discord セッションに付与されます。 `ackReaction` は、OpenClaw が受信メッセージを処理中であることを示す絵文字リアクションを送ります。 解決順序: * `channels.discord.accounts..ackReaction` * `channels.discord.ackReaction` * `messages.ackReaction` * エージェント identity の絵文字フォールバック（`agents.list[].identity.emoji`、未設定時は `"👀"`） 注意: * Discord は Unicode 絵文字とカスタム絵文字名の両方を受け付けます * チャンネルまたはアカウント単位で無効化するには `""` を使います チャンネル起点の設定書き込みは、デフォルトで有効です。 これは `/config set|unset` のフローに影響します（コマンド機能が有効な場合）。 無効化: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { configWrites: false, }, }, } ``` `channels.discord.proxy` を使うと、Discord ゲートウェイの WebSocket 通信と起動時の REST 参照（application ID と allowlist 解決）を HTTP(S) プロキシ経由にできます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { proxy: "http://proxy.example:8080", }, }, } ``` アカウント単位の上書き: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { accounts: { primary: { proxy: "http://proxy.example:8080", }, }, }, }, } ``` PluralKit 解決を有効にすると、プロキシされたメッセージをシステムメンバーの identity にマッピングできます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { pluralkit: { enabled: true, token: "pk_live_...", // optional; needed for private systems }, }, }, } ``` 注意: * allowlist では `pk:` を使用できます * メンバー表示名の名前 / slug 一致は、`channels.discord.dangerouslyAllowNameMatching: true` のときだけ有効です * 参照には元のメッセージ ID が使われ、時間窓の制約があります * 解決に失敗した場合、プロキシメッセージは bot メッセージとして扱われ、`allowBots=true` でない限り破棄されます プレゼンス更新は、status または activity を設定したとき、あるいは auto presence を有効にしたときに適用されます。 status のみを設定する例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { status: "idle", }, }, } ``` activity を設定する例（デフォルトの activity type は custom status）: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { activity: "Focus time", activityType: 4, }, }, } ``` streaming の例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { activity: "Live coding", activityType: 1, activityUrl: "https://twitch.tv/openclaw", }, }, } ``` activity type の対応: * 0: Playing * 1: Streaming（`activityUrl` 必須） * 2: Listening * 3: Watching * 4: Custom（activity テキストを status state として使います。絵文字は任意です） * 5: Competing auto presence の例（ランタイム健全性シグナル）: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { autoPresence: { enabled: true, intervalMs: 30000, minUpdateIntervalMs: 15000, exhaustedText: "token exhausted", }, }, }, } ``` auto presence は、ランタイム可用性を Discord status にマッピングします。healthy は online、degraded または unknown は idle、exhausted または unavailable は dnd になります。テキスト上書き: * `autoPresence.healthyText` * `autoPresence.degradedText` * `autoPresence.exhaustedText`（`{reason}` プレースホルダー対応） Discord は、DM 内でのボタンベース exec 承認に対応しており、必要に応じて元のチャンネルに承認プロンプトを投稿することもできます。 設定パス: * `channels.discord.execApprovals.enabled` * `channels.discord.execApprovals.approvers` * `channels.discord.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） * `agentFilter`、`sessionFilter`、`cleanupAfterResolve` `target` が `channel` または `both` の場合、承認プロンプトはチャンネルにも表示されます。ボタンを使えるのは設定された承認者だけで、その他のユーザーには ephemeral の拒否が返されます。承認プロンプトにはコマンド本文が含まれるため、チャンネル配信は信頼できるチャンネルにだけ有効化してください。セッションキーからチャンネル ID を導出できない場合、OpenClaw は DM 配信へフォールバックします。 このハンドラーのゲートウェイ認可には、他のゲートウェイクライアントと同じ共有認証情報解決契約が使われます。 * env 優先のローカル認可（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`、次に `gateway.auth.*`） * ローカルモードでは、`gateway.auth.*` が未設定なら `gateway.remote.*` をフォールバックとして使用可能 * 必要に応じて `gateway.remote.*` によるリモートモードをサポート * URL override は override-safe です。CLI override は暗黙の認証情報を再利用せず、env override は env の認証情報だけを使います 承認時に unknown approval ID エラーが出る場合は、承認者一覧と機能の有効化状態を確認してください。 関連ドキュメント: [Exec approvals](/tools/exec-approvals) ## ツールとアクションゲート Discord の message action には、メッセージ送受信、チャンネル管理、モデレーション、プレゼンス、メタデータ関連のアクションが含まれます。 代表例: * messaging: `sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` * reactions: `react`、`reactions`、`emojiList` * moderation: `timeout`、`kick`、`ban` * presence: `setPresence` action gate は `channels.discord.actions.*` 配下にあります。 デフォルトの gate 挙動: | Action group | Default | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | enabled | | roles | disabled | | moderation | disabled | | presence | disabled | ## コンポーネント v2 UI OpenClaw は、exec 承認と cross-context marker に Discord components v2 を使用します。Discord の message action では、カスタム UI 用の `components` も受け付けられます（高度な用途。Carbon component instance が必要です）。従来の `embeds` も引き続き利用できますが、推奨はされません。 * `channels.discord.ui.components.accentColor` は、Discord component container で使用するアクセントカラー（16 進数）を設定します * アカウント単位では `channels.discord.accounts..ui.components.accentColor` で設定します * components v2 が存在する場合、`embeds` は無視されます 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { ui: { components: { accentColor: "#5865F2", }, }, }, }, } ``` ## 音声チャンネル OpenClaw は Discord の音声チャンネルに参加し、リアルタイムで継続的な会話を行えます。これは音声メッセージ添付とは別機能です。 要件: * ネイティブコマンド（`commands.native` または `channels.discord.commands.native`）を有効にする * `channels.discord.voice` を設定する * ボットに対象音声チャンネルでの Connect と Speak 権限を付与する セッション制御には Discord 専用のネイティブコマンド `/vc join|leave|status` を使います。このコマンドはアカウントのデフォルトエージェントを使い、他の Discord コマンドと同じ allowlist と group policy ルールに従います。 自動参加の例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { voice: { enabled: true, autoJoin: [ { guildId: "123456789012345678", channelId: "234567890123456789", }, ], daveEncryption: true, decryptionFailureTolerance: 24, tts: { provider: "openai", openai: { voice: "alloy" }, }, }, }, }, } ``` 注意: * `voice.tts` は音声再生に限って `messages.tts` を上書きします * 音声 transcript turn の owner 判定は Discord の `allowFrom`（または `dm.allowFrom`）から導かれます。owner でない発話者は、`gateway` や `cron` などの owner 限定ツールにアクセスできません * 音声機能はデフォルトで有効です。無効化するには `channels.discord.voice.enabled=false` を設定します * `voice.daveEncryption` と `voice.decryptionFailureTolerance` は `@discordjs/voice` の join option にそのまま渡されます * `@discordjs/voice` 側のデフォルトは、未設定時に `daveEncryption=true` および `decryptionFailureTolerance=24` です * OpenClaw は受信時の復号失敗も監視し、短時間に繰り返し失敗した場合は音声チャンネルから一度離脱して再参加することで自動回復を試みます * 受信ログに `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` が繰り返し出る場合は、上流の `@discordjs/voice` 受信バグである [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) に該当している可能性があります ## 音声メッセージ Discord の音声メッセージでは波形プレビューが表示され、OGG/Opus 音声とメタデータが必要です。OpenClaw は波形を自動生成しますが、音声ファイルを検査して変換するために、ゲートウェイホスト上で `ffmpeg` と `ffprobe` が利用可能である必要があります。 要件と制約: * **ローカルファイルパス** を指定してください（URL は拒否されます） * テキスト本文は省略してください（Discord は同じペイロード内でテキストと音声メッセージを同時に送れません） * 音声形式は任意です。必要に応じて OpenClaw が OGG/Opus に変換します 例: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) ``` ## トラブルシューティング * Message Content Intent を有効にする * ユーザー / メンバー解決に依存する場合は Server Members Intent も有効にする * intent を変更したあとはゲートウェイを再起動する * `groupPolicy` を確認する * `channels.discord.guilds` 配下の guild allowlist を確認する * guild の `channels` マップが存在する場合、列挙されたチャンネルだけが許可される * `requireMention` の挙動と mention パターンを確認する 便利な確認コマンド: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw doctor openclaw channels status --probe openclaw logs --follow ``` よくある原因: * `groupPolicy="allowlist"` だが、一致する guild / channel allowlist がない * `requireMention` の設定場所が誤っている（`channels.discord.guilds` または channel entry の下である必要があります） * 送信者が guild / channel の `users` allowlist によってブロックされている 典型的なログ: * `Listener DiscordMessageListener timed out after 30000ms for event MESSAGE_CREATE` * `Slow listener detected ...` * `discord inbound worker timed out after ...` listener budget の設定: * 単一アカウント: `channels.discord.eventQueue.listenerTimeout` * マルチアカウント: `channels.discord.accounts..eventQueue.listenerTimeout` worker 実行タイムアウトの設定: * 単一アカウント: `channels.discord.inboundWorker.runTimeoutMs` * マルチアカウント: `channels.discord.accounts..inboundWorker.runTimeoutMs` * デフォルト: `1800000`（30 分）。無効化するには `0` を指定します 推奨ベースライン: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { discord: { accounts: { default: { eventQueue: { listenerTimeout: 120000, }, inboundWorker: { runTimeoutMs: 1800000, }, }, }, }, }, } ``` 遅い listener のための余裕を増やしたい場合は `eventQueue.listenerTimeout` を使います。キュー済みエージェントターンに別の安全弁が必要な場合にだけ `inboundWorker.runTimeoutMs` を調整してください。 `channels status --probe` の権限チェックは、数値チャンネル ID に対してのみ完全に機能します。 slug キーを使用していても、ランタイム上のマッチング自体は可能ですが、probe では権限を完全には検証できません。 * DM が無効化されている: `channels.discord.dm.enabled=false` * DM policy が無効化されている: `channels.discord.dmPolicy="disabled"`（旧設定: `channels.discord.dm.policy`） * `pairing` モードでペアリング承認待ちになっている デフォルトでは、bot が投稿したメッセージは無視されます。 `channels.discord.allowBots=true` を使う場合は、ループを防ぐために厳格な mention ルールと allowlist を組み合わせてください。通常は、ボット自身への mention を含む bot メッセージだけを受け付ける `channels.discord.allowBots="mentions"` を推奨します。 * Discord 音声受信の回復ロジックが入っているよう、OpenClaw を最新に保つ（`openclaw update`） * `channels.discord.voice.daveEncryption=true`（デフォルト）を確認する * `channels.discord.voice.decryptionFailureTolerance=24`（上流デフォルト）から始め、必要な場合だけ調整する * 次のログを確認する: * `discord voice: DAVE decrypt failures detected` * `discord voice: repeated decrypt failures; attempting rejoin` * 自動再参加後も失敗が続く場合は、ログを収集して [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) と比較する ## 設定リファレンスの参照先 主な参照先: * [Configuration reference - Discord](/gateway/configuration-reference#discord) 特に確認頻度の高い Discord フィールド: * 起動 / 認可: `enabled`、`token`、`accounts.*`、`allowBots` * policy: `groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` * command: `commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` * event queue: `eventQueue.listenerTimeout`（listener budget）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` * inbound worker: `inboundWorker.runTimeoutMs` * reply / history: `replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` * delivery: `textChunkLimit`、`chunkMode`、`maxLinesPerMessage` * streaming: `streaming`（旧エイリアス: `streamMode`）、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` * media / retry: `mediaMaxMb`、`retry` * `mediaMaxMb` は Discord への送信アップロード上限です（デフォルト: `8MB`） * actions: `actions.*` * presence: `activity`、`status`、`activityType`、`activityUrl` * UI: `ui.components.accentColor` * features: `threadBindings`、トップレベルの `bindings[]`（`type: "acp"`）、`pluralkit`、`execApprovals`、`intents`、`agentComponents`、`heartbeat`、`responsePrefix` ## セーフティと運用 * ボットトークンは機密情報として扱ってください（監視付き環境では `DISCORD_BOT_TOKEN` を推奨します） * Discord 権限は最小権限で付与してください * コマンドの deploy 状態や反映状態が古い場合は、ゲートウェイを再起動し、`openclaw channels status --probe` で再確認してください ## 関連 * [Pairing](/channels/pairing) * [Channel routing](/channels/channel-routing) * [Multi-agent routing](/concepts/multi-agent) * [Troubleshooting](/channels/troubleshooting) * [Slash commands](/tools/slash-commands) # Feishu Source: https://openclawdoc.org/channels/feishu Feishu / Lark ボットを OpenClaw に接続する設定ガイドです。WebSocket イベント連携の構成、認証情報、受信フローを確認できます。 Feishu (Lark) は、企業でのメッセージングやコラボレーションに使われるチームチャットプラットフォームです。このプラグインは、Feishu / Lark の WebSocket イベントサブスクリプションを使って OpenClaw をボットへ接続します。そのため、公開 webhook URL を外部へ公開せずにメッセージを受信できます。 *** ## Bundled plugin Feishu は現在の OpenClaw リリースに同梱されているため、通常は別途プラグインをインストールする必要はありません。 ただし、同梱版を含まない古いビルドやカスタムインストールを使っている場合は、手動でインストールしてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/feishu ``` *** ## Quickstart Feishu チャンネルの追加方法は 2 つあります。 ### Method 1: onboarding wizard (recommended) OpenClaw をインストールした直後であれば、ウィザードを実行してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard ``` ウィザードでは次を順に案内します。 1. Feishu アプリを作成し、認証情報を取得する 2. OpenClaw にアプリ認証情報を設定する 3. ゲートウェイを起動する ✅ **設定後** は、ゲートウェイの状態を確認してください。 * `openclaw gateway status` * `openclaw logs --follow` ### Method 2: CLI setup 初期セットアップがすでに完了している場合は、CLI からチャンネルを追加できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels add ``` **Feishu** を選択し、App ID と App Secret を入力します。 ✅ **設定後** は、次のコマンドでゲートウェイを管理できます。 * `openclaw gateway status` * `openclaw gateway restart` * `openclaw logs --follow` *** ## Step 1: Create a Feishu app ### 1. Open 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. Create an app 1. **Create enterprise app** をクリックします。 2. アプリ名と説明を入力します。 3. アプリアイコンを選択します。 Create enterprise app ### 3. Copy credentials **Credentials & Basic Info** から次の値を控えます。 * **App ID** (形式: `cli_xxx`) * **App Secret** ❗ **Important:** App Secret は秘密として扱ってください。 Get credentials ### 4. Configure permissions **Permissions** で **Batch import** をクリックし、次の内容を貼り付けます。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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 ### 5. Enable bot capability **App Capability** > **Bot** で次を設定します。 1. ボット機能を有効にする 2. ボット名を設定する Enable bot capability ### 6. Configure event subscription ⚠️ **Important:** イベントサブスクリプションを設定する前に、次の 2 点を確認してください。 1. Feishu に対して `openclaw channels add` をすでに実行済みであること 2. ゲートウェイが起動していること (`openclaw gateway status`) **Event Subscription** では次を設定します。 1. **Use long connection to receive events** (WebSocket) を選択する 2. `im.message.receive_v1` イベントを追加する ⚠️ ゲートウェイが起動していない場合、長時間接続の設定保存に失敗することがあります。 Configure event subscription ### 7. Publish the app 1. **Version Management & Release** でバージョンを作成します。 2. レビューへ提出して公開します。 3. 管理者承認を待ちます。enterprise app では自動承認されることが一般的です。 *** ## Step 2: Configure OpenClaw ### Configure with the wizard (recommended) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels add ``` **Feishu** を選択し、App ID と App Secret を貼り付けます。 ### Configure via config file `~/.openclaw/openclaw.json` を編集します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { enabled: true, dmPolicy: "pairing", accounts: { main: { appId: "cli_xxx", appSecret: "xxx", botName: "My AI assistant", }, }, }, }, } ``` `connectionMode: "webhook"` を使う場合は `verificationToken` を設定してください。Feishu の webhook サーバーはデフォルトで `127.0.0.1` に bind されます。意図的に別の bind address が必要な場合にだけ `webhookHost` を設定してください。 #### Verification Token (webhook mode) webhook モードを使う場合は、設定で `channels.feishu.verificationToken` を指定します。取得手順は次のとおりです。 1. Feishu Open Platform で対象アプリを開きます。 2. **Development** → **Events & Callbacks** (开发配置 → 事件与回调) を開きます。 3. **Encryption** タブ (加密策略) を開きます。 4. **Verification Token** をコピーします。 Verification Token location ### Configure via environment variables ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export FEISHU_APP_ID="cli_xxx" export FEISHU_APP_SECRET="xxx" ``` ### Lark (global) domain テナントが Lark (国際版) にある場合は、domain を `lark` に設定してください。完全なドメイン文字列を指定することもできます。設定先は `channels.feishu.domain` またはアカウント単位の `channels.feishu.accounts..domain` です。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { domain: "lark", accounts: { main: { appId: "cli_xxx", appSecret: "xxx", }, }, }, }, } ``` ### Quota optimization flags Feishu API の利用量を減らしたい場合は、次の 2 つのオプションフラグを使えます。 * `typingIndicator` (デフォルト `true`): `false` にすると、入力中リアクションの API 呼び出しを省略します。 * `resolveSenderNames` (デフォルト `true`): `false` にすると、送信者プロフィール解決の API 呼び出しを省略します。 これらはトップレベル、またはアカウント単位で設定できます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { typingIndicator: false, resolveSenderNames: false, accounts: { main: { appId: "cli_xxx", appSecret: "xxx", typingIndicator: true, resolveSenderNames: false, }, }, }, }, } ``` *** ## Step 3: Start + test ### 1. Start the gateway ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway ``` ### 2. Send a test message Feishu 上でボットを探し、テストメッセージを送信します。 ### 3. Approve pairing デフォルトでは、ボットはペアリングコードを返します。次のコマンドで承認します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing approve feishu ``` 承認後は通常どおりチャットできます。 *** ## Overview * **Feishu bot channel**: ゲートウェイが管理する Feishu ボットチャンネルです。 * **Deterministic routing**: 返信は常に Feishu へ戻ります。 * **Session isolation**: DM は main session を共有し、グループは分離されます。 * **WebSocket connection**: Feishu SDK を使う長時間接続で動作し、公開 URL は不要です。 *** ## Access control ### Direct messages * **デフォルト**: `dmPolicy: "pairing"`。未知のユーザーにはペアリングコードが返されます。 * **ペアリング承認**: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list feishu openclaw pairing approve feishu ``` * **allowlist モード**: `channels.feishu.allowFrom` に許可する Open ID を設定します。 ### Group chats **1. Group policy** (`channels.feishu.groupPolicy`) * `"open"` = グループ内の全員を許可します (デフォルト) * `"allowlist"` = `groupAllowFrom` に含まれるものだけを許可します * `"disabled"` = グループメッセージを無効化します **2. Mention requirement** (`channels.feishu.groups..requireMention`) * `true` = @mention 必須 (デフォルト) * `false` = メンションなしでも応答 *** ## Group configuration examples ### Allow all groups, require @mention (default) ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { groupPolicy: "open", // Default requireMention: true }, }, } ``` ### Allow all groups, no @mention required ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { groups: { oc_xxx: { requireMention: false }, }, }, }, } ``` ### Allow specific groups only ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { groupPolicy: "allowlist", // Feishu group IDs (chat_id) look like: oc_xxx groupAllowFrom: ["oc_xxx", "oc_yyy"], }, }, } ``` ### Restrict which senders can message in a group (sender allowlist) グループ自体を許可するだけでなく、そのグループ内の **すべてのメッセージ** を送信者の `open_id` で制限できます。`groups..allowFrom` に含まれるユーザーのメッセージだけが処理され、それ以外のメンバーからのメッセージは無視されます。これは `/reset` や `/new` のような制御コマンドだけでなく、通常のメッセージにも適用されます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { groupPolicy: "allowlist", groupAllowFrom: ["oc_xxx"], groups: { oc_xxx: { // Feishu user IDs (open_id) look like: ou_xxx allowFrom: ["ou_user1", "ou_user2"], }, }, }, }, } ``` *** ## Get group/user IDs ### Group IDs (chat\_id) グループ ID は `oc_xxx` のような形式です。 **Method 1 (recommended)** 1. ゲートウェイを起動し、グループ内でボットを @mention します。 2. `openclaw logs --follow` を実行し、`chat_id` を探します。 **Method 2** Feishu API debugger を使ってグループチャット一覧を確認します。 ### User IDs (open\_id) ユーザー ID は `ou_xxx` のような形式です。 **Method 1 (recommended)** 1. ゲートウェイを起動し、ボットへ DM を送ります。 2. `openclaw logs --follow` を実行し、`open_id` を探します。 **Method 2** ペアリング要求一覧からユーザーの Open ID を確認します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list feishu ``` *** ## Common commands | Command | Description | | --------- | ------------- | | `/status` | ボットの状態を表示 | | `/reset` | セッションをリセット | | `/model` | モデルの表示 / 切り替え | > Note: Feishu は現時点でネイティブなコマンドメニューをサポートしていないため、コマンドはテキストとして送信する必要があります。 ## Gateway management commands | Command | Description | | -------------------------- | ---------------------- | | `openclaw gateway status` | ゲートウェイ状態を表示 | | `openclaw gateway install` | ゲートウェイサービスをインストール / 起動 | | `openclaw gateway stop` | ゲートウェイサービスを停止 | | `openclaw gateway restart` | ゲートウェイサービスを再起動 | | `openclaw logs --follow` | ゲートウェイログを追跡 | *** ## Troubleshooting ### Bot does not respond in group chats 1. ボットがグループへ追加されていることを確認します。 2. デフォルト挙動では @mention が必要です。メンションしているか確認します。 3. `groupPolicy` が `"disabled"` になっていないことを確認します。 4. `openclaw logs --follow` でログを確認します。 ### Bot does not receive messages 1. アプリが公開済みかつ承認済みであることを確認します。 2. イベントサブスクリプションに `im.message.receive_v1` が含まれていることを確認します。 3. **long connection** が有効であることを確認します。 4. アプリ権限が不足していないことを確認します。 5. ゲートウェイが起動していることを確認します: `openclaw gateway status` 6. `openclaw logs --follow` でログを確認します。 ### App Secret leak 1. Feishu Open Platform 上で App Secret をリセットします。 2. 設定内の App Secret を更新します。 3. ゲートウェイを再起動します。 ### Message send failures 1. アプリに `im:message:send_as_bot` 権限があることを確認します。 2. アプリが公開済みであることを確認します。 3. ログで詳細エラーを確認します。 *** ## Advanced configuration ### Multiple accounts ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { defaultAccount: "main", accounts: { main: { appId: "cli_xxx", appSecret: "xxx", botName: "Primary bot", }, backup: { appId: "cli_yyy", appSecret: "yyy", botName: "Backup bot", enabled: false, }, }, }, }, } ``` `defaultAccount` は、送信 API で `accountId` を明示しない場合に、どの Feishu アカウントを使うかを決めます。 ### Message limits * `textChunkLimit`: 送信テキストのチャンクサイズ (デフォルト 2000 文字) * `mediaMaxMb`: メディアのアップロード / ダウンロード上限 (デフォルト 30 MB) ### Streaming Feishu は interactive card を使ったストリーミング返信に対応しています。有効にすると、ボットはテキスト生成中にカードを更新します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { feishu: { streaming: true, // enable streaming card output (default true) blockStreaming: true, // enable block-level streaming (default true) }, }, } ``` 送信前に完全な返信が揃うまで待たせたい場合は、`streaming: false` を設定してください。 ### Multi-agent routing `bindings` を使うと、Feishu の DM やグループを別のエージェントへルーティングできます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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`) 取得方法のヒントは [Get group/user IDs](#get-groupuser-ids) を参照してください。 *** ## Configuration reference 完全な設定一覧: [Gateway configuration](/gateway/configuration) | Setting | Description | Default | | ------------------------------------------------- | ------------------------------ | ---------------- | | `channels.feishu.enabled` | チャンネルの有効 / 無効 | `true` | | `channels.feishu.domain` | API ドメイン (`feishu` または `lark`) | `feishu` | | `channels.feishu.connectionMode` | イベント転送モード | `websocket` | | `channels.feishu.defaultAccount` | 送信ルーティング時のデフォルトアカウント | `default` | | `channels.feishu.verificationToken` | webhook モードで必須 | - | | `channels.feishu.webhookPath` | webhook のルートパス | `/feishu/events` | | `channels.feishu.webhookHost` | webhook の bind host | `127.0.0.1` | | `channels.feishu.webhookPort` | webhook の bind port | `3000` | | `channels.feishu.accounts..appId` | App ID | - | | `channels.feishu.accounts..appSecret` | App Secret | - | | `channels.feishu.accounts..domain` | アカウント単位の API ドメイン上書き | `feishu` | | `channels.feishu.dmPolicy` | DM ポリシー | `pairing` | | `channels.feishu.allowFrom` | DM allowlist (`open_id` 一覧) | - | | `channels.feishu.groupPolicy` | グループポリシー | `open` | | `channels.feishu.groupAllowFrom` | グループ allowlist | - | | `channels.feishu.groups..requireMention` | @mention 必須かどうか | `true` | | `channels.feishu.groups..enabled` | グループを有効にするか | `true` | | `channels.feishu.textChunkLimit` | メッセージのチャンクサイズ | `2000` | | `channels.feishu.mediaMaxMb` | メディアサイズ上限 | `30` | | `channels.feishu.streaming` | ストリーミングカード出力を有効化 | `true` | | `channels.feishu.blockStreaming` | ブロックストリーミングを有効化 | `true` | *** ## dmPolicy reference | Value | Behavior | | ------------- | ---------------------------------------- | | `"pairing"` | **デフォルト。** 未知のユーザーにはペアリングコードが返り、承認が必要です | | `"allowlist"` | `allowFrom` に含まれるユーザーだけが利用できます | | `"open"` | すべてのユーザーを許可します (`allowFrom` に `"*"` が必要) | | `"disabled"` | DM を無効化します | *** ## Supported message types ### Receive * ✅ Text * ✅ Rich text (post) * ✅ Images * ✅ Files * ✅ Audio * ✅ Video * ✅ Stickers ### Send * ✅ Text * ✅ Images * ✅ Files * ✅ Audio * ⚠️ Rich text (partial support) # Google Chat Source: https://openclawdoc.org/channels/googlechat Google Chat アプリを OpenClaw に接続する設定ガイドです。Webhook ベースの構成、DM とスペースの対応範囲、セットアップ手順を確認できます。 ステータス: Google Chat API の webhook 経由で DM とスペースに対応しています (HTTP のみ)。 ## Quick setup (beginner) 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 ファイルをゲートウェイホストへ保存します (例: `~/.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** を選び、ゲートウェイの公開 URL に `/googlechat` を付けたものを指定します。 * *Tip: `openclaw status` を実行すると、ゲートウェイの公開 URL を確認できます。* * **Visibility** で **Make this Chat app available to specific people and groups in \** を有効にします。 * テキストボックスへ利用者のメールアドレス (例: `user@example.com`) を入力します。 * 画面下部の **Save** を押します。 6. **App status** を有効にします。 * 保存後に **ページを再読み込み** します。 * **App status** セクションを探します。通常は保存後、画面上部または下部付近に表示されます。 * ステータスを **Live - available to users** に変更します。 * もう一度 **Save** を押します。 7. Service Account のパスと webhook audience を使って OpenClaw を設定します。 * 環境変数: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json` * または設定: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"` 8. webhook audience の type と value を設定します。Chat アプリ側の設定と一致させてください。 9. ゲートウェイを起動します。Google Chat は webhook パスに対して POST を送信します。 ## Add to Google Chat ゲートウェイが起動しており、利用者のメールアドレスが visibility list に追加されていれば、次の手順で使い始められます。 1. [Google Chat](https://chat.google.com/) を開きます。 2. **Direct Messages** の横にある **+** アイコンを押します。 3. 通常ユーザーを追加する検索欄に、Google Cloud Console で設定した **App name** を入力します。 * **Note**: このボットは非公開アプリのため、"Marketplace" の一覧には表示されません。名前で検索する必要があります。 4. 検索結果からボットを選択します。 5. **Add** または **Chat** を押して 1 対 1 の会話を開始します。 6. `"Hello"` を送ってアシスタントを起動します。 ## Public URL (Webhook-only) Google Chat の webhook には公開 HTTPS エンドポイントが必要です。セキュリティのため、**外部へ公開するのは `/googlechat` パスだけ** にしてください。OpenClaw のダッシュボードや、その他の機密性の高いエンドポイントはプライベートネットワーク内にとどめておくべきです。 ### Option A: Tailscale Funnel (Recommended) プライベートダッシュボードには Tailscale Serve を使い、公開する webhook パスには Funnel を使います。これにより、`/` は非公開のままにしつつ、`/googlechat` だけを外部公開できます。 1. **ゲートウェイがどのアドレスにバインドされているか確認します。** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ss -tlnp | grep 18789 ``` `127.0.0.1`、`0.0.0.0`、または `100.x.x.x` のような Tailscale IP など、表示された IP アドレスを控えます。 2. **ダッシュボードを tailnet 内だけに公開します (port 8443)。** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # If bound to localhost (127.0.0.1 or 0.0.0.0): tailscale serve --bg --https 8443 http://127.0.0.1:18789 # If bound to Tailscale IP only (e.g., 100.106.161.80): tailscale serve --bg --https 8443 http://100.106.161.80:18789 ``` 3. **webhook パスだけを公開します。** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # If bound to localhost (127.0.0.1 or 0.0.0.0): tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat # If bound to Tailscale IP only (e.g., 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} tailscale serve status tailscale funnel status ``` 公開される webhook URL は次の形になります。 `https://..ts.net/googlechat` プライベートダッシュボードは tailnet 内のままです。 `https://..ts.net:8443/` Google Chat アプリの設定には、`:8443` を含まない公開 URL を使ってください。 > Note: この設定は再起動後も維持されます。削除したい場合は `tailscale funnel reset` と `tailscale serve reset` を実行してください。 ### Option B: Reverse Proxy (Caddy) Caddy などの reverse proxy を使う場合は、該当パスだけを proxy してください。 ```caddy theme={"theme":{"light":"min-light","dark":"min-dark"}} your-domain.com { reverse_proxy /googlechat* localhost:18789 } ``` この構成では、`your-domain.com/` へのリクエストは無視されるか 404 を返し、`your-domain.com/googlechat` だけが安全に OpenClaw へルーティングされます。 ### Option C: Cloudflare Tunnel tunnel の ingress rules を、webhook パスだけに向けるよう設定します。 * **Path**: `/googlechat` -> `http://localhost:18789/googlechat` * **Default Rule**: HTTP 404 (Not Found) ## How it works 1. Google Chat が webhook POST をゲートウェイへ送信します。各リクエストには `Authorization: Bearer ` ヘッダーが含まれます。 * OpenClaw は、このヘッダーがある場合、webhook 本文を最後まで読んだり解析したりする前に bearer 認証を検証します。 * 本文に `authorizationEventObject.systemIdToken` を持つ Google Workspace Add-on リクエストも、より厳格な事前認証本文バジェットを使ってサポートされます。 2. OpenClaw は設定された `audienceType` と `audience` に対してトークンを検証します。 * `audienceType: "app-url"` の場合、audience は HTTPS の webhook URL です。 * `audienceType: "project-number"` の場合、audience は Cloud project number です。 3. メッセージは space 単位でルーティングされます。 * DM ではセッションキー `agent::googlechat:dm:` を使います。 * Space ではセッションキー `agent::googlechat:group:` を使います。 4. DM アクセスはデフォルトでペアリングです。未知の送信者にはペアリングコードが返るため、次のコマンドで承認します。 * `openclaw pairing approve googlechat ` 5. Group space では、デフォルトで @mention が必要です。アプリのユーザー名がないとメンション検出できない場合は `botUser` を設定します。 ## Targets 配信先や allowlist では、次の識別子を使います。 * Direct message: `users/` (推奨) * 生のメールアドレス `name@example.com` は変更可能であり、`channels.googlechat.dangerouslyAllowNameMatching: true` を設定した場合にだけ、DM allowlist の直接一致へ使われます。 * 非推奨: `users/` はメールアドレスの allowlist ではなく、user id として扱われます。 * Space: `spaces/` ## Config highlights ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { googlechat: { enabled: true, serviceAccountFile: "/path/to/service-account.json", // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" } audienceType: "app-url", audience: "https://gateway.example.com/googlechat", webhookPath: "/googlechat", botUser: "users/1234567890", // optional; helps mention detection dm: { policy: "pairing", allowFrom: ["users/1234567890"], }, groupPolicy: "allowlist", groups: { "spaces/AAAA": { allow: true, requireMention: true, users: ["users/1234567890"], systemPrompt: "Short answers only.", }, }, actions: { reactions: true }, typingIndicator: "message", mediaMaxMb: 20, }, }, } ``` 補足: * Service Account の認証情報は `serviceAccount` に JSON 文字列としてインライン指定することもできます。 * `serviceAccountRef` も使えます (env/file SecretRef)。`channels.googlechat.accounts..serviceAccountRef` のように、アカウント単位でも指定できます。 * `webhookPath` を設定しない場合、既定値は `/googlechat` です。 * `dangerouslyAllowNameMatching` は、変更可能なメール principal による allowlist 一致を再度有効化します。緊急互換モード向けの設定です。 * `actions.reactions` を有効にすると、リアクションは `reactions` ツールおよび `channels action` から利用できます。 * `typingIndicator` では `none`、`message` (デフォルト)、`reaction` を使えます。`reaction` には user OAuth が必要です。 * 添付ファイルは Chat API 経由でダウンロードされ、メディアパイプラインへ保存されます。サイズ上限は `mediaMaxMb` です。 SecretRef の詳細は [Secrets Management](/gateway/secrets) を参照してください。 ## Troubleshooting ### 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. **Channel not configured**: 設定に `channels.googlechat` セクションがありません。次のコマンドで確認します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config get channels.googlechat ``` `Config path not found` が返る場合は、設定を追加してください ([Config highlights](#config-highlights) を参照)。 2. **Plugin not enabled**: plugin の状態を確認します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins list | grep googlechat ``` `disabled` と表示される場合は、設定に `plugins.entries.googlechat.enabled: true` を追加してください。 3. **Gateway not restarted**: 設定追加後にゲートウェイが再起動されていません。次を実行してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway restart ``` チャンネルが動作中かどうかは次のコマンドで確認できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels status # Should show: Google Chat default: enabled, configured, ... ``` ### Other issues * `openclaw channels status --probe` を使って、認証エラーや audience 設定不足を確認してください。 * メッセージが届かない場合は、Chat app 側の webhook URL と event subscriptions を確認してください。 * メンション制御のために返信が止まっている場合は、`botUser` にアプリの user resource name を設定し、`requireMention` も確認してください。 * テストメッセージを送りながら `openclaw logs --follow` を実行すると、リクエストがゲートウェイへ届いているか確認できます。 関連ドキュメント: * [Gateway configuration](/gateway/configuration) * [Security](/gateway/security) * [Reactions](/tools/reactions) # Group Messages Source: https://openclawdoc.org/channels/group-messages WhatsApp グループメッセージの挙動を整理したガイドです。メンション制御、返信ルール、グループ内での配信動作を確認できます。 目的: Clawd を WhatsApp グループに参加させ、必要なときだけ起動し、そのスレッドを個人 DM セッションから分離して扱えるようにすることです。 注: `agents.list[].groupChat.mentionPatterns` は現在、Telegram、Discord、Slack、iMessage でも使われています。このページでは WhatsApp 固有の挙動に絞って説明します。マルチエージェント構成では、エージェントごとに `agents.list[].groupChat.mentionPatterns` を設定してください。グローバルなフォールバックとして `messages.groupChat.mentionPatterns` も利用できます。 ## 実装済みの機能 (2025-12-03) * 起動モード: `mention` (デフォルト) または `always` を使えます。`mention` では、実際の WhatsApp の @メンション (`mentionedJids`)、正規表現パターン、または本文内のボットの E.164 番号のいずれかが必要です。`always` ではすべてのメッセージでエージェントを起動しますが、意味のある応答ができる場合にのみ返信し、それ以外はサイレントトークン `NO_REPLY` を返します。既定値は `channels.whatsapp.groups` で設定でき、`/activation` でグループごとに上書きできます。`channels.whatsapp.groups` を設定した場合は、グループ allowlist としても機能します。すべてのグループを許可するには `"*"` を含めてください。 * グループポリシー: `channels.whatsapp.groupPolicy` でグループメッセージを受け付けるかどうかを制御します (`open|disabled|allowlist`)。`allowlist` では `channels.whatsapp.groupAllowFrom` を使い、未設定時は明示的な `channels.whatsapp.allowFrom` へフォールバックします。デフォルトは `allowlist` で、送信者を追加するまでブロックされます。 * グループごとのセッション: セッションキーは `agent::whatsapp:group:` の形式になります。そのため、`/verbose on` や `/think high` のようなコマンドを単独メッセージで送ると、そのグループだけに適用されます。個人 DM の状態には影響しません。ハートビートはグループスレッドでは実行されません。 * コンテキスト注入: 実行をトリガーしなかった保留中のグループメッセージだけが、`[Chat messages since your last reply - for context]` の下に付加されます (デフォルトは 50 件)。トリガーになったメッセージは `[Current message - respond to this]` の下に入ります。すでにセッションへ取り込まれたメッセージは再注入されません。 * 送信者表示: すべてのグループバッチの末尾には `[from: Sender Name (+E164)]` が付き、Pi が誰の発言か把握できるようになっています。 * エフェメラル / 1 回表示メッセージ: テキストやメンションを抽出する前にアンラップするため、その中のメンションでもトリガーできます。 * グループ用システムプロンプト: グループセッションの最初のターン、および `/activation` でモードが変わるたびに、`You are replying inside the WhatsApp group "". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` のような短い説明をシステムプロンプトへ注入します。メタデータが取れない場合でも、グループチャットであることはエージェントへ伝えられます。 ## 設定例 (WhatsApp) `~/.openclaw/openclaw.json` に `groupChat` ブロックを追加すると、WhatsApp が本文中の見た目上の `@` を取り除いた場合でも、表示名によるメンションを検出できます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { groups: { "*": { requireMention: true }, }, }, }, agents: { list: [ { id: "main", groupChat: { historyLimit: 50, mentionPatterns: ["@?openclaw", "\\+?15555550123"], }, }, ], }, } ``` 補足: * 正規表現は大文字小文字を区別しません。`@openclaw` のような表示名メンションと、`+` や空白の有無にかかわらず生の番号を拾えるようにしています。 * 誰かが連絡先をタップした場合、WhatsApp は通常 `mentionedJids` 経由で正規のメンションを送るため、番号フォールバックは必須ではありません。ただし、安全策としては有用です。 ### 起動コマンド (オーナーのみ) グループチャットで次のコマンドを使います。 * `/activation mention` * `/activation always` これを変更できるのは、オーナー番号 (`channels.whatsapp.allowFrom`、未設定の場合はボット自身の E.164) だけです。グループで `/status` を単独メッセージとして送ると、現在の起動モードを確認できます。 ## 使い方 1. OpenClaw を実行している WhatsApp アカウントをグループへ追加します。 2. `@openclaw ...` と送るか、番号を本文に含めます。`groupPolicy: "open"` にしていない限り、トリガーできるのは allowlist に登録された送信者だけです。 3. エージェントのプロンプトには最近のグループコンテキストと末尾の `[from: ...]` マーカーが入るため、誰に向けた返信か判断できます。 4. セッション単位の指示 (`/verbose on`、`/think high`、`/new`、`/reset`、`/compact`) は、そのグループのセッションにだけ適用されます。反映させるには単独メッセージで送ってください。個人 DM セッションは独立したままです。 ## テスト / 検証 * 手動スモークテスト: * グループで `@openclaw` メンションを送り、送信者名を参照した返信が返ることを確認します。 * 2 回目のメンションを送り、履歴ブロックが含まれ、次のターンで消えることを確認します。 * ゲートウェイログを `--verbose` 付きで確認し、`from: ` と `[from: ...]` のサフィックスが入った `inbound web message` エントリを確認します。 ## 注意点 * ハートビートはノイズの多いブロードキャストを避けるため、グループでは意図的に無効化されています。 * エコー抑制は結合済みのバッチ文字列に対して働きます。メンションなしで同じテキストを 2 回送ると、返信は最初の 1 回だけになることがあります。 * セッションストアには `agent::whatsapp:group:` という形式でエントリが保存されます (デフォルトの保存先は `~/.openclaw/agents//sessions/sessions.json`)。エントリがない場合は、そのグループでまだ実行が発生していないことを意味します。 * グループでのタイピングインジケーターは `agents.defaults.typingMode` に従います。デフォルトは、未メンション時に `message` です。 # Groups Source: https://openclawdoc.org/channels/groups 複数チャネルに共通するグループチャットの挙動をまとめます。メンション、アクセス制御、各プラットフォームごとの違いを確認できます。 OpenClaw は、WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams、Zalo など、複数のサーフェスにまたがってグループチャットを一貫した考え方で扱います。 ## Beginner intro (2 minutes) OpenClaw は、利用者自身のメッセージングアカウント上で動作します。WhatsApp 専用の別ボットユーザーが存在するわけではありません。利用者がグループに参加していれば、OpenClaw もそのグループを認識し、そこで応答できます。 デフォルトの挙動は次のとおりです。 * グループは制限付きです (`groupPolicy: "allowlist"`)。 * 明示的に無効化しない限り、返信にはメンションが必要です。 つまり、allowlist に登録された送信者がメンションしたときに OpenClaw が反応します。 > TL;DR > > * **DM access** は `*.allowFrom` で制御されます。 > * **Group access** は `*.groupPolicy` と allowlist (`*.groups`, `*.groupAllowFrom`) で制御されます。 > * **Reply triggering** はメンション制御 (`requireMention`, `/activation`) で制御されます。 グループメッセージは概ね次の順序で処理されます。 ``` groupPolicy? disabled -> drop groupPolicy? allowlist -> group allowed? no -> drop requireMention? yes -> mentioned? no -> store for context only otherwise -> reply ``` Group message flow よくある目的と設定例: | Goal | What to set | | -------------------------------------------- | ---------------------------------------------------------- | | Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }` | | Disable all group replies | `groupPolicy: "disabled"` | | Only specific groups | `groups: { "": { ... } }` (no `"*"` key) | | Only you can trigger in groups | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | ## Session keys * グループセッションには `agent:::group:` 形式のセッションキーを使います。ルームやチャンネルでは `agent:::channel:` を使います。 * Telegram のフォーラムトピックでは、グループ ID に `:topic:` が追加されるため、トピックごとに独立したセッションになります。 * ダイレクトチャットはメインセッションを使います。構成によっては送信者ごとに分けることもできます。 * ハートビートはグループセッションでは実行されません。 ## Pattern: personal DMs + public groups (single agent) 「個人用」は **DM**、「公開用」は **グループ** という使い分けであれば、単一エージェント構成でもうまく運用できます。 理由は、シングルエージェント構成では DM が通常 **main** セッションキー (`agent:main:main`) に入り、グループは常に **non-main** セッションキー (`agent:main::group:`) を使うためです。`mode: "non-main"` でサンドボックスを有効にすると、DM のメインセッションはホスト上に残しつつ、グループセッションだけを Docker 内で動かせます。 これにより、ワークスペースやメモリは 1 つの「頭脳」として共有しながら、実行形態だけを分けられます。 * **DMs**: フルツールをホスト上で実行 * **Groups**: 制限付きツールをサンドボックス内で実行 > 「個人用」と「公開用」を完全に分離し、ワークスペースや人格を絶対に混在させたくない場合は、2 つ目のエージェントと bindings を使ってください。詳しくは [Multi-Agent Routing](/concepts/multi-agent) を参照してください。 例: DM はホスト上、グループはサンドボックス化し、メッセージング系ツールだけを許可する構成です。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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"], }, }, }, } ``` 「ホストへ一切アクセスさせない」代わりに、「グループでは特定フォルダだけ見せたい」場合は、`workspaceAccess: "none"` を維持したまま、許可するパスだけをサンドボックスへ bind mount します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { sandbox: { mode: "non-main", scope: "session", workspaceAccess: "none", docker: { binds: [ // hostPath:containerPath:mode "/home/user/FriendsShared:/data:ro", ], }, }, }, }, } ``` 関連: * 構成キーとデフォルト: [ゲートウェイ構成](/gateway/configuration#agentsdefaultssandbox) * ツールがブロックされる理由の調査: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) * bind mount の詳細: [Sandboxing](/gateway/sandboxing#custom-bind-mounts) ## Display labels * UI ラベルでは、利用できる場合は `displayName` を使い、`:` 形式で表示します。 * `#room` はルーム / チャンネル用に予約されています。グループチャットでは `g-` を使います。小文字化し、空白は `-` に変換し、`#@+._-` は保持されます。 ## Group policy チャンネルごとに、グループ / ルームメッセージをどう扱うかを制御します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 }, }, }, }, } ``` | Policy | Behavior | | ------------- | ------------------------------------------- | | `"open"` | グループは allowlist を迂回しますが、メンション制御は引き続き適用されます。 | | `"disabled"` | すべてのグループメッセージを完全に拒否します。 | | `"allowlist"` | 設定済み allowlist に一致するグループ / ルームだけを許可します。 | 補足: * `groupPolicy` はメンション制御とは別物です。メンション制御は @メンション必須かどうかを決めます。 * WhatsApp、Telegram、Signal、iMessage、Microsoft Teams、Zalo では `groupAllowFrom` を使います。未設定時は明示的な `allowFrom` へフォールバックします。 * DM のペアリング承認 (`*-allowFrom` ストアエントリ) は DM アクセスにだけ適用されます。グループ送信者の認可は、グループ allowlist 側で明示的に管理されます。 * Discord の allowlist は `channels.discord.guilds..channels` を使います。 * Slack の allowlist は `channels.slack.channels` を使います。 * Matrix の allowlist は `channels.matrix.groups` を使います。ルーム ID、エイリアス、名前に対応します。送信者制限には `channels.matrix.groupAllowFrom` を使い、ルームごとの `users` allowlist も利用できます。 * グループ DM は別系統で制御されます (`channels.discord.dm.*`, `channels.slack.dm.*`)。 * Telegram の allowlist は、ユーザー ID (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) またはユーザー名 (`"@alice"` または `"alice"`) に一致できます。プレフィックスの大文字小文字は区別されません。 * デフォルトは `groupPolicy: "allowlist"` です。グループ allowlist が空なら、グループメッセージはブロックされます。 * 実行時の安全策として、プロバイダーブロック自体が存在しない (`channels.` がない) 場合は、`channels.defaults.groupPolicy` を継承せず、フェイルクローズ動作として通常 `allowlist` にフォールバックします。 グループメッセージの評価順序は、概ね次のとおりです。 1. `groupPolicy` (`open`, `disabled`, `allowlist`) 2. グループ allowlist (`*.groups`, `*.groupAllowFrom`, チャンネル固有の allowlist) 3. メンション制御 (`requireMention`, `/activation`) ## Mention gating (default) グループメッセージは、グループごとに上書きしない限りメンション必須です。既定値はサブシステムごとの `*.groups."*"` にあります。 チャネルが返信メタデータをサポートしている場合、ボットのメッセージへ返信することも暗黙のメンションとして扱われます。これは Telegram、WhatsApp、Slack、Discord、Microsoft Teams に適用されます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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` は大文字小文字を区別しない正規表現です。 * 明示的なメンションを提供するサーフェスでは、その仕組みが優先されます。パターンはフォールバックです。 * エージェント単位で上書きする場合は `agents.list[].groupChat.mentionPatterns` を使います。複数エージェントが同じグループを共有する場合に便利です。 * メンション制御は、ネイティブメンションまたは `mentionPatterns` によってメンション検出が可能な場合にだけ適用されます。 * Discord の既定値は `channels.discord.guilds."*"` にあります。ギルド単位やチャンネル単位で上書きできます。 * グループ履歴コンテキストはチャネル間で共通の形式に包まれ、**pending-only** です。つまり、メンション制御によってスキップされたメッセージだけが対象です。グローバル既定値には `messages.groupChat.historyLimit`、個別上書きには `channels..historyLimit` または `channels..accounts.*.historyLimit` を使います。`0` にすると無効化できます。 ## Group/channel tool restrictions (optional) 一部のチャンネル設定では、**特定のグループ / ルーム / チャンネル内** で使えるツールを制限できます。 * `tools`: グループ全体に対する allow / deny 設定です。 * `toolsBySender`: グループ内の送信者ごとの上書き設定です。 使うキーには明示的なプレフィックスを付けます。 `id:`, `e164:`, `username:`, `name:`, および `"*"` ワイルドカードです。 プレフィックスのない従来形式のキーも引き続き受け付けますが、`id:` としてのみ照合されます。 評価順序は、より具体的なものが優先されます。 1. グループ / チャンネルの `toolsBySender` 2. グループ / チャンネルの `tools` 3. デフォルト (`"*"`) の `toolsBySender` 4. デフォルト (`"*"`) の `tools` 例 (Telegram): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { groups: { "*": { tools: { deny: ["exec"] } }, "-1001234567890": { tools: { deny: ["exec", "read", "write"] }, toolsBySender: { "id:123456789": { alsoAllow: ["exec"] }, }, }, }, }, }, } ``` 補足: * グループ / チャンネル単位のツール制限は、グローバルまたはエージェント単位のツールポリシーに追加で適用されます。`deny` が競合した場合は `deny` が優先されます。 * 一部のチャンネルでは、ルームやチャンネルのネスト構造が異なります。たとえば Discord は `guilds.*.channels.*`、Slack は `channels.*`、MS Teams は `teams.*.channels.*` を使います。 ## Group allowlists `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups` を設定すると、そのキー自体がグループ allowlist として機能します。`"*"` を使えば、全グループを許可しつつ既定のメンション挙動も設定できます。 よくある設定例: 1. すべてのグループ返信を無効化する ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { groupPolicy: "disabled" } }, } ``` 2. 特定のグループだけを許可する (WhatsApp) ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { groups: { "123@g.us": { requireMention: true }, "456@g.us": { requireMention: false }, }, }, }, } ``` 3. すべてのグループを許可しつつ、メンション必須にする ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { groups: { "*": { requireMention: true } }, }, }, } ``` 4. グループ内で起動できるのをオーナーだけにする (WhatsApp) ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["+15551234567"], groups: { "*": { requireMention: true } }, }, }, } ``` ## Activation (owner-only) グループオーナーは、グループごとの起動モードを切り替えられます。 * `/activation mention` * `/activation always` オーナーは `channels.whatsapp.allowFrom` によって決まります。未設定の場合は、ボット自身の E.164 が使われます。コマンドは単独メッセージとして送ってください。現在、他のサーフェスでは `/activation` は無視されます。 ## Context fields グループの受信ペイロードでは、次のフィールドが設定されます。 * `ChatType=group` * `GroupSubject` (分かる場合) * `GroupMembers` (分かる場合) * `WasMentioned` (メンション制御の結果) * Telegram のフォーラムトピックでは `MessageThreadId` と `IsForum` も含まれます。 新しいグループセッションの最初のターンでは、エージェントのシステムプロンプトにグループ用の導入文が追加されます。そこでは、人間らしく応答すること、Markdown テーブルを避けること、リテラルの `\n` をそのまま出力しないことなどが案内されます。 ## iMessage specifics * ルーティングや allowlist では `chat_id:` を優先してください。 * チャット一覧は `imsg chats --limit 20` で確認できます。 * グループ返信は常に同じ `chat_id` へ返されます。 ## WhatsApp specifics WhatsApp 固有の挙動、たとえば履歴注入やメンション処理の詳細については [Group messages](/channels/group-messages) を参照してください。 # iMessage Source: https://openclawdoc.org/channels/imessage レガシーな imsg 経由で iMessage を連携する設定ガイドです。BlueBubbles との違い、前提条件、送受信の構成を確認できます。 新規の iMessage 構成では BlueBubbles を使ってください。 `imsg` 統合はレガシー扱いであり、将来のリリースで削除される可能性があります。 ステータス: レガシーな外部 CLI 連携です。ゲートウェイは `imsg rpc` を起動し、stdio 上の JSON-RPC で通信します。別個のデーモンや専用ポートは不要です。 新規構成ではこちらを推奨します。 iMessage の DM はデフォルトでペアリングモードです。 iMessage の設定項目一覧です。 ## Quick setup ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} brew install steipete/tap/imsg imsg rpc --help ``` ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { imessage: { enabled: true, cliPath: "/usr/local/bin/imsg", dbPath: "/Users//Library/Messages/chat.db", }, }, } ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list imessage openclaw pairing approve imessage ``` ペアリング要求の有効期限は 1 時間です。 OpenClaw が必要とするのは stdio 互換の `cliPath` だけです。そのため、`cliPath` に、リモート Mac へ SSH 接続して `imsg` を実行するラッパースクリプトを指定できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} #!/usr/bin/env bash exec ssh -T gateway-host imsg "$@" ``` 添付ファイルを有効にする場合の推奨設定: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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`) に対して検証されます。 ## Requirements and permissions (macOS) * `imsg` を実行する Mac で Messages にサインインしている必要があります。 * OpenClaw / `imsg` を実行するプロセスコンテキストには、Messages DB へアクセスするための Full Disk Access が必要です。 * Messages.app 経由でメッセージを送信するには Automation 権限が必要です。 権限はプロセスコンテキスト単位で付与されます。ゲートウェイをヘッドレス (LaunchAgent / SSH) で動かす場合は、同じコンテキストで一度だけ対話型コマンドを実行して、権限プロンプトを表示させてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} imsg chats --limit 1 # or imsg send "test" ``` ## Access control and routing `channels.imessage.dmPolicy` でダイレクトメッセージを制御します。 * `pairing` (デフォルト) * `allowlist` * `open` (`allowFrom` に `"*"` を含める必要があります) * `disabled` allowlist フィールドは `channels.imessage.allowFrom` です。 allowlist のエントリには、handle またはチャットターゲット (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) を使えます。 `channels.imessage.groupPolicy` でグループ処理を制御します。 * `allowlist` (設定されている場合のデフォルト) * `open` * `disabled` グループ送信者 allowlist は `channels.imessage.groupAllowFrom` です。 ランタイムのフォールバック挙動として、`groupAllowFrom` が未設定であれば、利用可能な場合は `allowFrom` が iMessage グループ送信者チェックに使われます。 また、`channels.imessage` 自体が存在しない場合、ランタイムは `groupPolicy="allowlist"` にフォールバックし、`channels.defaults.groupPolicy` が設定されていても警告をログへ出します。 グループでのメンション制御: * iMessage にはネイティブなメンションメタデータがありません * メンション検出には正規表現パターンを使います (`agents.list[].groupChat.mentionPatterns`、フォールバックは `messages.groupChat.mentionPatterns`) * パターンが設定されていなければ、メンション制御は強制できません 認可済み送信者からの制御コマンドは、グループ内でメンション制御を迂回できます。 * DM はダイレクトルーティング、グループはグループルーティングを使います。 * デフォルトの `session.dmScope=main` では、iMessage の DM はエージェントの main セッションへ集約されます。 * グループセッションは分離されます (`agent::imessage:group:`)。 * 返信は、元のチャンネル / ターゲットのメタデータを使って iMessage 側へ戻されます。 グループ的なスレッド挙動: 一部の複数参加者 iMessage スレッドは `is_group=false` で届くことがあります。 その `chat_id` が `channels.imessage.groups` に明示的に設定されていれば、OpenClaw はそれをグループトラフィックとして扱います。つまり、グループ制御とグループセッション分離が適用されます。 ## Deployment patterns 専用の Apple ID と macOS ユーザーを用意すると、ボット用トラフィックを個人の Messages プロファイルから分離できます。 典型的な流れ: 1. 専用の macOS ユーザーを作成し、そのユーザーでサインインします。 2. そのユーザー上で、ボット用 Apple ID を使って Messages にサインインします。 3. そのユーザーに `imsg` をインストールします。 4. OpenClaw がそのユーザーコンテキストで `imsg` を実行できるよう、SSH ラッパーを作成します。 5. `channels.imessage.accounts..cliPath` と `.dbPath` をそのユーザープロファイルに向けます。 初回実行では、そのボットユーザーの GUI セッション内で Automation と Full Disk Access の承認が必要になる場合があります。 よくある構成例: * ゲートウェイは Linux / VM 上で動作 * iMessage と `imsg` は tailnet 内の Mac で動作 * `cliPath` のラッパーが SSH で `imsg` を実行 * `remoteHost` を使って SCP による添付ファイル取得を有効化 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} #!/usr/bin/env bash exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@" ``` SSH キーを使い、SSH と SCP の両方が非対話で動作するようにしてください。 また、最初にホストキーを信頼して `known_hosts` を埋める必要があります。たとえば `ssh bot@mac-mini.tailnet-1234.ts.net` を一度実行してください。 iMessage では `channels.imessage.accounts` の下でアカウントごとの設定を行えます。 各アカウントでは、`cliPath`、`dbPath`、`allowFrom`、`groupPolicy`、`mediaMaxMb`、履歴設定、添付ファイルルート allowlist などを上書きできます。 ## Media, chunking, and delivery targets * 受信添付ファイルの取り込みはオプションです: `channels.imessage.includeAttachments` * `remoteHost` が設定されていれば、リモート添付ファイルのパスを SCP 経由で取得できます * 添付ファイルパスは、許可されたルートに一致している必要があります * `channels.imessage.attachmentRoots` (ローカル) * `channels.imessage.remoteAttachmentRoots` (リモート SCP モード) * デフォルトのルートパターン: `/Users/*/Library/Messages/Attachments` * SCP では厳密なホストキー検証を使います (`StrictHostKeyChecking=yes`) * 送信メディアのサイズ上限は `channels.imessage.mediaMaxMb` で制御します (デフォルト 16 MB) * テキストチャンクの上限: `channels.imessage.textChunkLimit` (デフォルト 4000) * チャンクモード: `channels.imessage.chunkMode` * `length` (デフォルト) * `newline` (段落優先で分割) 推奨される明示的ターゲット: * `chat_id:123` (安定したルーティングに推奨) * `chat_guid:...` * `chat_identifier:...` handle ベースのターゲットも使えます: * `imessage:+1555...` * `sms:+1555...` * `user@example.com` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} imsg chats --limit 20 ``` ## Config writes iMessage ではデフォルトで、チャンネル開始の設定書き込みを許可します (`commands.config: true` のときの `/config set|unset`)。 無効にするには: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { imessage: { configWrites: false, }, }, } ``` ## Troubleshooting バイナリと RPC サポートを確認します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} imsg rpc --help openclaw channels status --probe ``` probe が RPC 非対応を報告する場合は、`imsg` を更新してください。 確認事項: * `channels.imessage.dmPolicy` * `channels.imessage.allowFrom` * ペアリング承認 (`openclaw pairing list imessage`) 確認事項: * `channels.imessage.groupPolicy` * `channels.imessage.groupAllowFrom` * `channels.imessage.groups` の allowlist 挙動 * メンションパターン設定 (`agents.list[].groupChat.mentionPatterns`) 確認事項: * `channels.imessage.remoteHost` * `channels.imessage.remoteAttachmentRoots` * ゲートウェイホストからの SSH / SCP キー認証 * ゲートウェイホスト上の `~/.ssh/known_hosts` にホストキーがあること * Messages を実行している Mac 上で、リモートパスが読み取り可能であること 同じユーザー / セッションコンテキストの対話型 GUI ターミナルで再実行し、プロンプトを承認してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} imsg chats --limit 1 imsg send "test" ``` OpenClaw / `imsg` を実行するプロセスコンテキストに Full Disk Access と Automation が付与されていることも確認してください。 ## Configuration reference pointers * [Configuration reference - iMessage](/gateway/configuration-reference#imessage) * [Gateway configuration](/gateway/configuration) * [Pairing](/channels/pairing) * [BlueBubbles](/channels/bluebubbles) # Chat Channels Source: https://openclawdoc.org/channels/index OpenClaw が接続できるチャットチャンネルの一覧ページです。各メッセージングプラットフォームの特徴と対応範囲を比較できます。 OpenClaw は、すでに使っているチャットアプリの上で会話できます。各チャンネルはゲートウェイ経由で接続されます。テキストはすべてのチャンネルで利用できますが、メディアやリアクションの対応状況はチャンネルごとに異なります。 ## サポートされているチャンネル * [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 (レガシー)](/channels/imessage) — `imsg` CLI を使う従来の macOS 連携です。非推奨のため、新規構成では BlueBubbles の利用を推奨します。 * [IRC](/channels/irc) — 従来型の IRC サーバーに対応します。チャンネルと DM の両方を扱え、ペアリングや allowlist による制御もできます。 * [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 に対応します。プラグインとして別途インストールします。 * [Signal](/channels/signal) — `signal-cli` ベースで、プライバシー重視の運用に向いています。 * [Synology Chat](/channels/synology-chat) — 送受信 webhook を使う Synology NAS Chat 連携です。プラグインとして別途インストールします。 * [Slack](/channels/slack) — Bolt SDK ベースで、ワークスペースアプリとして動作します。 * [Telegram](/channels/telegram) — grammY 経由の Bot API を使い、グループにも対応しています。 * [Tlon](/channels/tlon) — Urbit ベースのメッセンジャーです。プラグインとして別途インストールします。 * [Twitch](/channels/twitch) — IRC 接続経由で Twitch チャットに参加します。プラグインとして別途インストールします。 * [WebChat](/web/webchat) — WebSocket 経由で動作するゲートウェイの WebChat UI です。 * [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 のペアリングと allowlist は安全のため必須です。詳しくは [Security](/gateway/security) を参照してください。 * トラブルシューティングは [Channel troubleshooting](/channels/troubleshooting) を参照してください。 * モデルプロバイダーについては別ページで説明しています。[Model Providers](/providers/models) を参照してください。 # IRC Source: https://openclawdoc.org/channels/irc IRC チャンネルとダイレクトメッセージを OpenClaw に接続する設定ガイドです。プラグイン導入、allowlist、グループ制御、運用の注意点を確認できます。 クラシックな IRC チャンネル (`#room`) やダイレクトメッセージで OpenClaw を使いたい場合は IRC を利用します。IRC は拡張プラグインとして提供されますが、設定はメイン設定ファイル内の `channels.irc` で行います。 ## Quick start 1. `~/.openclaw/openclaw.json` で IRC の設定を有効にします。 2. 最低限、次の項目を設定します。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "irc": { "enabled": true, "host": "irc.libera.chat", "port": 6697, "tls": true, "nick": "openclaw-bot", "channels": ["#openclaw"] } } } ``` 3. ゲートウェイを起動または再起動します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway run ``` ## Security defaults * `channels.irc.dmPolicy` のデフォルトは `"pairing"` です。 * `channels.irc.groupPolicy` のデフォルトは `"allowlist"` です。 * `groupPolicy="allowlist"` を使う場合は、`channels.irc.groups` で許可するチャンネルを定義します。 * 平文通信を意図的に許可する場合を除き、TLS (`channels.irc.tls=true`) を使ってください。 ## Access control IRC チャンネルには、独立した 2 つの「ゲート」があります。 1. **チャンネルアクセス** (`groupPolicy` + `groups`): そのチャンネルからのメッセージをボットが受け付けるかどうか 2. **送信者アクセス** (`groupAllowFrom` / チャンネルごとの `groups["#channel"].allowFrom`): そのチャンネル内でボットを起動できる送信者は誰か 主な設定キー: * DM allowlist (DM 送信者アクセス): `channels.irc.allowFrom` * グループ送信者 allowlist (チャンネル送信者アクセス): `channels.irc.groupAllowFrom` * チャンネルごとの制御 (チャンネル + 送信者 + メンションルール): `channels.irc.groups["#channel"]` * `channels.irc.groupPolicy="open"` を使うと、未設定のチャンネルも許可されます。ただし **デフォルトでは引き続きメンション制御が有効** です。 allowlist のエントリには、安定した送信者識別子 (`nick!user@host`) を使うことを推奨します。ニックネーム単体での照合は可変であり、`channels.irc.dangerouslyAllowNameMatching: true` を設定した場合にのみ有効になります。 ### Common gotcha: `allowFrom` is for DMs, not channels 次のようなログが出る場合があります。 * `irc: drop group sender alice!ident@host (policy=allowlist)` これは、送信者が **グループ / チャンネル** メッセージに対して許可されていないことを意味します。対処方法は次のいずれかです。 * `channels.irc.groupAllowFrom` を設定する (全チャンネル共通) * チャンネルごとの送信者 allowlist を設定する: `channels.irc.groups["#channel"].allowFrom` 例: `#tuirc-dev` 内の誰でもボットへ話しかけられるようにする設定です。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { irc: { groupPolicy: "allowlist", groups: { "#tuirc-dev": { allowFrom: ["*"] }, }, }, }, } ``` ## Reply triggering (mentions) チャンネルが許可されており (`groupPolicy` + `groups`)、かつ送信者も許可されていても、OpenClaw はグループ文脈ではデフォルトで **メンション制御** を行います。 そのため、メッセージにボットへ一致するメンションパターンが含まれていないと、`drop channel ... (missing-mention)` のようなログが出ることがあります。 IRC チャンネルで **メンションなしでも** ボットに返信させたい場合は、そのチャンネルのメンション制御を無効にします。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { irc: { groupPolicy: "allowlist", groups: { "#tuirc-dev": { requireMention: false, allowFrom: ["*"], }, }, }, }, } ``` あるいは、**すべての** IRC チャンネルを許可し、メンションなしで返信させることもできます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { irc: { groupPolicy: "open", groups: { "*": { requireMention: false, allowFrom: ["*"] }, }, }, }, } ``` ## Security note (recommended for public channels) 公開チャンネルで `allowFrom: ["*"]` を許可すると、誰でもボットへプロンプトを送れるようになります。リスクを下げるため、そのチャンネルで利用できるツールを制限してください。 ### Same tools for everyone in the channel ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { irc: { groups: { "#tuirc-dev": { allowFrom: ["*"], tools: { deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"], }, }, }, }, }, } ``` ### Different tools per sender (owner gets more power) `toolsBySender` を使うと、`"*"` に対して厳しいポリシーを適用しつつ、自分の nick だけをより緩いポリシーにできます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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:eigen` や、より強く一致させたい場合は `id:eigen!~eigen@174.127.248.171` を使います。 * 従来のプレフィックスなしキーも引き続き受け付けますが、`id:` としてのみ照合されます。 * 最初に一致した送信者ポリシーが適用されます。`"*"` はワイルドカードのフォールバックです。 グループアクセスとメンション制御の関係については [/channels/groups](/channels/groups) も参照してください。 ## NickServ 接続後に NickServ で認証するには、次のように設定します。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "irc": { "nickserv": { "enabled": true, "service": "NickServ", "password": "your-nickserv-password" } } } } ``` 接続時に一度だけ登録するオプションもあります。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "irc": { "nickserv": { "register": true, "registerEmail": "bot@example.com" } } } } ``` nick の登録が終わったら、`register` は無効にしてください。無効にしないと、毎回 REGISTER を試みる可能性があります。 ## Environment variables デフォルトアカウントでは次の環境変数を利用できます。 * `IRC_HOST` * `IRC_PORT` * `IRC_TLS` * `IRC_NICK` * `IRC_USERNAME` * `IRC_REALNAME` * `IRC_PASSWORD` * `IRC_CHANNELS` (カンマ区切り) * `IRC_NICKSERV_PASSWORD` * `IRC_NICKSERV_REGISTER_EMAIL` ## Troubleshooting * ボットが接続しているのにチャンネルで返信しない場合は、`channels.irc.groups` の設定に加え、メンション制御によって `missing-mention` で落ちていないか確認してください。メンションなしで返信させたい場合は、そのチャンネルへ `requireMention:false` を設定します。 * ログインに失敗する場合は、nick が使用可能かどうか、サーバーパスワードが正しいかどうかを確認してください。 * カスタムネットワークで TLS に失敗する場合は、host、port、証明書設定を確認してください。 # LINE Source: https://openclawdoc.org/channels/line LINE Messaging API を使って OpenClaw を接続する設定ガイドです。Webhook、認証情報、LINE 固有のメッセージオプションを確認できます。 LINE は LINE Messaging API を介して OpenClaw に接続します。このプラグインはゲートウェイ上で webhook レシーバーとして動作し、認証にはチャネルアクセストークンとチャネルシークレットを使用します。 ステータス: プラグインによりサポート。ダイレクトメッセージ、グループチャット、メディア、位置情報、Flex メッセージ、テンプレートメッセージ、クイックリプライがサポートされています。リアクションとスレッドはサポートされていません。 ## プラグインが必要 LINE プラグインをインストールします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/line ``` ローカルチェックアウト (git リポジトリから実行する場合): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/line ``` ## セットアップ 1. LINE Developers アカウントを作成し、コンソールを開きます: [https://developers.line.biz/console/](https://developers.line.biz/console/) 2. プロバイダーを作成 (または選択) し、**Messaging API** チャネルを追加します。 3. チャネル設定から**チャネルアクセストークン**と**チャネルシークレット**をコピーします。 4. Messaging API 設定で **Webhook を利用する** を有効にします。 5. webhook URL をゲートウェイのエンドポイントに設定します (HTTPS が必要): ``` https://gateway-host/line/webhook ``` ゲートウェイは LINE の webhook 検証 (GET) と受信イベント (POST) に応答します。 カスタムパスが必要な場合は、`channels.line.webhookPath` または `channels.line.accounts..webhookPath` を設定し、それに応じて URL を更新してください。 セキュリティに関する注意: * LINE の署名検証はリクエストボディに依存します (生ボディに対する HMAC)。そのため、OpenClaw は検証前に厳格な事前認証ボディ制限とタイムアウトを適用します。 ## 設定 最小限の設定: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { line: { enabled: true, channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN", channelSecret: "LINE_CHANNEL_SECRET", dmPolicy: "pairing", }, }, } ``` 環境変数 (デフォルトアカウントのみ): * `LINE_CHANNEL_ACCESS_TOKEN` * `LINE_CHANNEL_SECRET` トークン/シークレットファイル: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { line: { tokenFile: "/path/to/line-token.txt", secretFile: "/path/to/line-secret.txt", }, }, } ``` 複数アカウント: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { line: { accounts: { marketing: { channelAccessToken: "...", channelSecret: "...", webhookPath: "/line/marketing", }, }, }, }, } ``` ## アクセス制御 ダイレクトメッセージはデフォルトでペアリングになります。未知の送信者はペアリングコードを受け取り、承認されるまでメッセージは無視されます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list line openclaw pairing approve line ``` 許可リストとポリシー: * `channels.line.dmPolicy`: `pairing | allowlist | open | disabled` * `channels.line.allowFrom`: DM 用の許可された LINE ユーザー ID * `channels.line.groupPolicy`: `allowlist | open | disabled` * `channels.line.groupAllowFrom`: グループ用の許可された LINE ユーザー ID * グループごとのオーバーライド: `channels.line.groups..allowFrom` * ランタイムに関する注意: `channels.line` セクションが完全に欠落している場合、ランタイムはグループチェックのために `groupPolicy="allowlist"` にフォールバックします (`channels.defaults.groupPolicy` が設定されている場合でも)。 LINE ID は大文字小文字を区別します。有効な ID は次のようになります: * ユーザー: `U` + 32 桁の 16 進数 * グループ: `C` + 32 桁の 16 進数 * ルーム: `R` + 32 桁の 16 進数 ## メッセージの動作 * テキストは 5000 文字で分割されます。 * Markdown フォーマットは削除されます。コードブロックとテーブルは可能な場合 Flex カードに変換されます。 * ストリーミングレスポンスはバッファリングされます。エージェントが作業している間、LINE 側にはローディングアニメーションが表示され、完了後にフルチャックを受信します。 * メディアダウンロードは `channels.line.mediaMaxMb` (デフォルト 10) で制限されます。 ## チャネルデータ (リッチメッセージ) `channelData.line` を使用して、クイックリプライ、位置情報、Flex カード、またはテンプレートメッセージを送信します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { text: "どうぞ", channelData: { line: { quickReplies: ["ステータス", "ヘルプ"], location: { title: "オフィス", address: "東京都千代田区丸の内 1-2-3", latitude: 35.681236, longitude: 139.767125, }, flexMessage: { altText: "ステータスカード", contents: { /* Flex ペイロード */ }, }, templateMessage: { type: "confirm", text: "続行しますか?", confirmLabel: "はい", confirmData: "yes", cancelLabel: "いいえ", cancelData: "no", }, }, }, } ``` LINE プラグインには、Flex メッセージプリセット用の `/card` コマンドも付属しています: ``` /card info "ようこそ" "ご参加ありがとうございます!" ``` ## トラブルシューティング * **Webhook 検証が失敗する:** webhook URL が HTTPS であり、`channelSecret` が LINE コンソールと一致していることを確認してください。 * **受信イベントがない:** webhook パスが `channels.line.webhookPath` と一致し、ゲートウェイが LINE から到達可能であることを確認してください。 * **メディアダウンロードエラー:** メディアがデフォルト制限を超える場合は、`channels.line.mediaMaxMb` を増やしてください。 # Channel Location Parsing Source: https://openclawdoc.org/channels/location Telegram と WhatsApp の位置情報メッセージを OpenClaw がどう解釈するかをまとめます。抽出されるコンテキスト項目と利用方法を確認できます。 OpenClawは、チャットチャンネルから共有された位置情報を以下のように正規化します： * インバウンドボディに追加される人間が読みやすいテキスト * 自動返信コンテキストペイロード内の構造化フィールド 現在サポートされているもの： * **Telegram**（位置情報ピン + 場所 + ライブ位置情報） * **WhatsApp**（locationMessage + liveLocationMessage） * **Matrix**（`geo_uri`を含む`m.location`） ## テキストフォーマット 位置情報は括弧なしのわかりやすい行として表示されます： * ピン： * `📍 48.858844, 2.294351 ±12m` * 名前付きの場所： * `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)` * ライブ共有： * `🛰 Live location: 48.858844, 2.294351 ±12m` チャンネルにキャプション/コメントが含まれている場合、次の行に追加されます： ``` 📍 48.858844, 2.294351 ±12m Meet here ``` ## コンテキストフィールド 位置情報が存在する場合、以下のフィールドが`ctx`に追加されます： * `LocationLat`（数値） * `LocationLon`（数値） * `LocationAccuracy`（数値、メートル単位；オプション） * `LocationName`（文字列；オプション） * `LocationAddress`（文字列；オプション） * `LocationSource`（`pin | place | live`） * `LocationIsLive`（真偽値） ## チャンネルに関する注意事項 * **Telegram**：場所は`LocationName/LocationAddress`にマッピングされます；ライブ位置情報は`live_period`を使用します。 * **WhatsApp**：`locationMessage.comment`と`liveLocationMessage.caption`はキャプション行として追加されます。 * **Matrix**：`geo_uri`はピン位置情報として解析されます；高度は無視され、`LocationIsLive`は常にfalseです。 # Matrix Source: https://openclawdoc.org/channels/matrix Matrix を OpenClaw に接続する設定ガイドです。ユーザーアカウントでの接続、E2EE 対応、ルームや DM のサポート範囲を確認できます。 Matrix は、オープンな分散型メッセージングプロトコルです。OpenClaw は、任意のホームサーバー上の Matrix **ユーザー**として接続するため、ボット用の Matrix アカウントが必要です。ログイン後は、ボットに直接 DM を送信したり、ルーム（Matrix の「グループ」）に招待したりできます。Beeper も有効なクライアントオプションですが、E2EE を有効にする必要があります。 ステータス: プラグイン (@vector-im/matrix-bot-sdk) 経由でサポートされています。ダイレクトメッセージ、ルーム、スレッド、メディア、リアクション、投票（送信 + テキストとしての投票開始）、位置情報、および E2EE（暗号化サポートあり）がサポートされています。 ## プラグインが必要 Matrix はプラグインとして提供されており、コアインストールには同梱されていません。 CLI (npm レジストリ) 経由でインストールします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/matrix ``` ローカルチェックアウト (git リポジトリから実行する場合): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/matrix ``` 構成/オンボーディング中に Matrix を選択し、git チェックアウトが検出された場合、OpenClaw は自動的にローカルインストールパスを提案します。 詳細: [プラグイン](/tools/plugin) ## セットアップ 1. Matrix プラグインをインストールします。 * npm から: `openclaw plugins install @openclaw/matrix` * ローカルチェックアウトから: `openclaw plugins install ./extensions/matrix` 2. ホームサーバーで Matrix アカウントを作成します。 * [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/) でホスティングオプションを確認してください。 * または、自身でホストします。 3. ボットアカウントのアクセストークンを取得します。 * ホームサーバーで `curl` を使用して Matrix ログイン API を呼び出します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl --request POST \ --url https://matrix.example.org/_matrix/client/v3/login \ --header 'Content-Type: application/json' \ --data '{ "type": "m.login.password", "identifier": { "type": "m.id.user", "user": "your-user-name" }, "password": "your-password" }' ``` * `matrix.example.org` を自身のホームサーバーの URL に置き換えてください。 * または、`channels.matrix.userId` + `channels.matrix.password` を設定します。OpenClaw は同じログインエンドポイントを呼び出し、アクセストークンを `~/.openclaw/credentials/matrix/credentials.json` に保存し、次回の起動時に再利用します。 4. 認証情報を構成します。 * 環境変数: `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` (または `MATRIX_USER_ID` + `MATRIX_PASSWORD`) * または構成ファイル: `channels.matrix.*` * 両方が設定されている場合は、構成ファイルの設定が優先されます。 * アクセストークンを使用する場合、ユーザー ID は `/whoami` 経由で自動的に取得されます。 * `channels.matrix.userId` を設定する場合は、完全な Matrix ID（例: `@bot:example.org`）を指定してください。 5. ゲートウェイを再起動します（またはオンボーディングを完了させます）。 6. 任意の Matrix クライアント (Element, Beeper 等。 [https://matrix.org/ecosystem/clients/](https://matrix.org/ecosystem/clients/) を参照) からボットと DM を開始するか、ルームに招待します。Beeper には E2EE が必要なため、`channels.matrix.encryption: true` を設定し、デバイスを検証してください。 最小限の構成 (アクセストークン使用、ユーザー ID は自動取得): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { enabled: true, homeserver: "https://matrix.example.org", accessToken: "syt_***", dm: { policy: "pairing" }, }, }, } ``` E2EE 構成 (エンドツーエンド暗号化を有効化): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { enabled: true, homeserver: "https://matrix.example.org", accessToken: "syt_***", encryption: true, dm: { policy: "pairing" }, }, }, } ``` ## 暗号化 (E2EE) エンドツーエンド暗号化は、Rust crypto SDK を介して**サポート**されています。 `channels.matrix.encryption: true` で有効にします: * 暗号化モジュールがロードされると、暗号化されたルームは自動的に復号されます。 * 暗号化されたルームに送信する場合、送信メディアは暗号化されます。 * 初回接続時、OpenClaw は他のセッションからのデバイス検証を要求します。 * 他の Matrix クライアント (Element 等) でデバイスを承認し、キー共有を有効にしてください。 * 暗号化モジュールをロードできない場合、E2EE は無効になり、暗号化されたルームは復号されません。この場合、OpenClaw は警告をログに出力します。 * 暗号化モジュール欠落エラー（例: `@matrix-org/matrix-sdk-crypto-nodejs-*`）が表示された場合は、`@matrix-org/matrix-sdk-crypto-nodejs` のビルドスクリプトを許可して `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` を実行するか、`node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js` でバイナリを取得してください。 暗号化の状態は、アカウント + アクセストークンごとに `~/.openclaw/matrix/accounts//__//crypto/` (SQLite データベース) に保存されます。同期状態はその隣の `bot-storage.json` に保存されます。アクセストークン（デバイス）が変更されると、新しいストアが作成され、ボットは暗号化されたルームに対して再検証が必要になります。 **デバイスの検証:** E2EE が有効な場合、ボットは起動時に他のセッションからの検証を要求します。Element（または他のクライアント）を開き、検証リクエストを承認して信頼関係を確立してください。検証が完了すると、ボットは暗号化されたルームのメッセージを復号できるようになります。 ## マルチアカウント マルチアカウントのサポート: `channels.matrix.accounts` を使用して、アカウントごとの認証情報とオプションの `name` を指定します。共通パターンについては [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) を参照してください。 各アカウントは、任意のホームサーバー上で個別の Matrix ユーザーとして動作します。アカウントごとの構成は、最上位の `channels.matrix` 設定を継承し、任意のオプション（DM ポリシー、グループ、暗号化など）を上書きできます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { enabled: true, dm: { policy: "pairing" }, accounts: { assistant: { name: "メインアシスタント", homeserver: "https://matrix.example.org", accessToken: "syt_assistant_***", encryption: true, }, alerts: { name: "アラートボット", homeserver: "https://matrix.example.org", accessToken: "syt_alerts_***", dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] }, }, }, }, }, } ``` 注: * アカウントの起動は、モジュールの同時インポートによる競合状態を避けるためにシリアル化されます。 * 環境変数（`MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` など）は**デフォルト**アカウントにのみ適用されます。 * 基本的なチャネル設定（DM ポリシー、グループポリシー、メンション制限など）は、アカウントごとに上書きされない限り、すべてのアカウントに適用されます。 * `bindings[].match.accountId` を使用して、各アカウントを異なるエージェントにルーティングできます。 * 暗号化の状態はアカウント + アクセストークンごとに保存されます（アカウントごとに個別のキーストア）。 ## ルーティングモデル * 返信は常に Matrix に戻ります。 * DM はエージェントのメインセッションを共有します。ルームはグループセッションにマップされます。 ## アクセス制御 (DM) * デフォルト: `channels.matrix.dm.policy = "pairing"`。未知の送信者にはペアリングコードが送信されます。 * 承認方法: * `openclaw pairing list matrix` * `openclaw pairing approve matrix ` * パブリック DM: `channels.matrix.dm.policy="open"` かつ `channels.matrix.dm.allowFrom=["*"]`。 * `channels.matrix.dm.allowFrom` は、完全な Matrix ユーザー ID（例: `@user:server`）を受け入れます。構成ウィザードでは、ディレクトリ検索で一意の完全一致が見つかった場合に、表示名をユーザー ID に解決できます。 * 表示名やユーザー名のみ（例: `"Alice"` や `"alice"`）は使用しないでください。これらは曖昧であり、許可リストの照合では無視されます。必ず完全な `@user:server` 形式の ID を使用してください。 ## ルーム (グループ) * デフォルト: `channels.matrix.groupPolicy = "allowlist"` (メンション制限あり)。未設定時のデフォルトを上書きするには `channels.defaults.groupPolicy` を使用します。 * ランタイムに関する注意: `channels.matrix` セクションが完全に欠落している場合、ランタイムはルームチェックのために `groupPolicy="allowlist"` にフォールバックします (`channels.defaults.groupPolicy` が設定されている場合でも)。 * ルームを許可リストに追加するには `channels.matrix.groups` を使用します（ルーム ID またはエイリアス。ディレクトリ検索で一意の完全一致が見つかった場合は名前も ID に解決されます）: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { groupPolicy: "allowlist", groups: { "!roomId:example.org": { allow: true }, "#alias:example.org": { allow: true }, }, groupAllowFrom: ["@owner:example.org"], }, }, } ``` * `requireMention: false` を設定すると、そのルームでの自動応答が有効になります。 * `groups."*"` を使用して、すべてのルームにおけるメンション制限のデフォルトを設定できます。 * `groupAllowFrom` は、ルーム内でボットをトリガーできる送信者を制限します（完全な Matrix ユーザー ID）。 * ルームごとの `users` 許可リストにより、特定のルーム内の送信者をさらに制限できます（完全な Matrix ユーザー ID を使用）。 * 構成ウィザードは、ルームの許可リスト（ルーム ID、エイリアス、または名前）の入力を求め、一意に一致する場合にのみ名前を解決します。 * 起動時、OpenClaw は許可リスト内のルーム/ユーザー名を ID に解決し、そのマッピングをログに出力します。未解決のエントリは、許可リストの照合では無視されます。 * 招待はデフォルトで自動承諾されます。`channels.matrix.autoJoin` および `channels.matrix.autoJoinAllowlist` で制御可能です。 * **すべてのルームを禁止**するには、`channels.matrix.groupPolicy: "disabled"` を設定します（または許可リストを空にします）。 * レガシーキー: `channels.matrix.rooms` (`groups` と同じ形式)。 ## スレッド * 返信スレッドがサポートされています。 * `channels.matrix.threadReplies` は、返信をスレッド内に維持するかどうかを制御します: * `off`, `inbound` (デフォルト), `always` * `channels.matrix.replyToMode` は、スレッド内で返信しない場合の返信先メタデータを制御します: * `off` (デフォルト), `first`, `all` ## 機能 | 機能 | ステータス | | :--------- | :----------------------------------------------- | | ダイレクトメッセージ | ✅ サポート済み | | ルーム | ✅ サポート済み | | スレッド | ✅ サポート済み | | メディア | ✅ サポート済み | | E2EE | ✅ サポート済み (暗号化モジュールが必要) | | リアクション | ✅ サポート済み (ツール経由での送信/読み取り) | | 投票 | ✅ 送信をサポート。受信した投票開始イベントはテキストに変換されます（回答/終了は無視されます） | | 位置情報 | ✅ サポート済み (geo URI。高度は無視されます) | | ネイティブコマンド | ✅ サポート済み | ## トラブルシューティング まず以下のコマンドを順に試してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` その後、必要に応じて DM のペアリング状態を確認してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list matrix ``` よくある失敗例: * ログインしているがルームのメッセージが無視される: ルームが `groupPolicy` またはルーム許可リストによってブロックされています。 * DM が無視される: `channels.matrix.dm.policy="pairing"` の場合、送信者が承認待ちの状態です。 * 暗号化されたルームで失敗する: 暗号化のサポートまたは暗号化設定の不一致。 詳細な診断フローについては、[/channels/troubleshooting](/channels/troubleshooting) を参照してください。 ## 構成リファレンス (Matrix) 完全な構成: [構成](/gateway/configuration) プロバイダーオプション: * `channels.matrix.enabled`: チャネルの起動を有効/無効にします。 * `channels.matrix.homeserver`: ホームサーバーの URL。 * `channels.matrix.userId`: Matrix ユーザー ID (アクセストークン使用時はオプション)。 * `channels.matrix.accessToken`: アクセストークン。 * `channels.matrix.password`: ログイン用パスワード (トークンが保存されます)。 * `channels.matrix.deviceName`: デバイスの表示名。 * `channels.matrix.encryption`: E2EE を有効化 (デフォルト: false)。 * `channels.matrix.initialSyncLimit`: 初期同期の制限数。 * `channels.matrix.threadReplies`: `off | inbound | always` (デフォルト: inbound)。 * `channels.matrix.textChunkLimit`: 送信テキストのチャンクサイズ（文字数）。 * `channels.matrix.chunkMode`: `length` (デフォルト) または `newline`（長さで分割する前に、空行などの段落境界で分割）。 * `channels.matrix.dm.policy`: `pairing | allowlist | open | disabled` (デフォルト: pairing)。 * `channels.matrix.dm.allowFrom`: DM 許可リスト (完全な Matrix ユーザー ID)。`open` には `"*"` が必要です。ウィザードは可能な限り名前を ID に解決します。 * `channels.matrix.groupPolicy`: `allowlist | open | disabled` (デフォルト: allowlist)。 * `channels.matrix.groupAllowFrom`: グループメッセージの許可された送信者 (完全な Matrix ユーザー ID)。 * `channels.matrix.allowlistOnly`: DM とルームの両方で許可リストルールを強制適用します。 * `channels.matrix.groups`: グループ許可リストとルームごとの設定マップ。 * `channels.matrix.rooms`: レガシーなグループ許可リスト/構成。 * `channels.matrix.replyToMode`: スレッド/タグの返信モード。 * `channels.matrix.mediaMaxMb`: 受信/送信メディアの上限サイズ (MB)。 * `channels.matrix.autoJoin`: 招待の処理 (`always | allowlist | off`、デフォルト: always)。 * `channels.matrix.autoJoinAllowlist`: 自動承諾を許可するルーム ID/エイリアスのリスト。 * `channels.matrix.accounts`: アカウント ID をキーとするマルチアカウント構成 (各アカウントは最上位の設定を継承します)。 * `channels.matrix.actions`: アクションごとのツール制限 (reactions/messages/pins/memberInfo/channelInfo)。 # Mattermost Source: https://openclawdoc.org/channels/mattermost Mattermost ボットを OpenClaw に接続する設定ガイドです。ボットトークン、WebSocket イベント、DM・チャネル対応の構成を確認できます。 ステータス: プラグイン経由でサポートされています（ボットトークン + WebSocket イベント）。チャネル、グループ、DM がサポートされています。 Mattermost は、自己ホスト可能なチームメッセージングプラットフォームです。製品の詳細やダウンロードについては、公式サイト [mattermost.com](https://mattermost.com) をご覧ください。 ## プラグインが必要 Mattermost はプラグインとして提供されており、コアインストールには同梱されていません。 CLI (npm レジストリ) 経由でインストールします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/mattermost ``` ローカルチェックアウト (git リポジトリから実行する場合): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/mattermost ``` 構成/オンボーディング中に Mattermost を選択し、git チェックアウトが検出された場合、OpenClaw は自動的にローカルインストールパスを提案します。 詳細: [プラグイン](/tools/plugin) ## クイックセットアップ 1. Mattermost プラグインをインストールします。 2. Mattermost ボットアカウントを作成し、**ボットトークン**をコピーします。 3. Mattermost の**ベース URL**（例: `https://chat.example.com`）をコピーします。 4. OpenClaw を設定し、ゲートウェイを起動します。 最小限の構成: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { mattermost: { enabled: true, botToken: "mm-token", baseUrl: "https://chat.example.com", dmPolicy: "pairing", }, }, } ``` ## ネイティブのスラッシュコマンド ネイティブのスラッシュコマンドはオプトイン方式です。有効にすると、OpenClaw は Mattermost API を介して `oc_*` スラッシュコマンドを登録し、ゲートウェイの HTTP サーバーでコールバック POST を受信します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { mattermost: { commands: { native: true, nativeSkills: true, callbackPath: "/api/channels/mattermost/command", // Mattermost がゲートウェイに直接到達できない場合（リバースプロキシ/公開 URL など）に使用します。 callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, }, }, } ``` 注: * `native: "auto"` の場合、Mattermost ではデフォルトで無効になります。有効にするには `native: true` を設定してください。 * `callbackUrl` が省略された場合、OpenClaw はゲートウェイのホスト/ポート + `callbackPath` から自動的に導出します。 * マルチアカウント設定の場合、`commands` はトップレベル、または `channels.mattermost.accounts..commands` 配下で設定可能です（アカウントごとの値が最上位フィールドを上書きします）。 * コマンドコールバックはコマンドごとのトークンで検証され、チェックに失敗した場合は安全のために実行を拒否（フェールクローズ）します。 * 到達可能性の要件: コールバックエンドポイントは Mattermost サーバーから到達可能である必要があります。 * Mattermost が OpenClaw と同じホスト/ネットワーク名前空間で実行されていない限り、`callbackUrl` を `localhost` に設定しないでください。 * URL が OpenClaw への `/api/channels/mattermost/command` をリバースプロキシしている場合を除き、`callbackUrl` を Mattermost のベース URL と同じに設定しないでください。 * 簡単な確認方法として、`curl https:///api/channels/mattermost/command` を実行してください。OpenClaw から `404` ではなく `405 Method Not Allowed` が返ってくれば正常です。 * Mattermost の送信（Egress）許可リストの要件: * コールバック先がプライベート/Tailscale/内部アドレスの場合は、Mattermost の `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを追加してください。 * 完全な URL ではなく、ホスト/ドメインのみを指定します。 * 良い例: `gateway.tailnet-name.ts.net` * 悪い例: `https://gateway.tailnet-name.ts.net` ## 環境変数 (デフォルトアカウント) 環境変数を使用したい場合は、ゲートウェイホストで以下を設定します: * `MATTERMOST_BOT_TOKEN=...` * `MATTERMOST_URL=https://chat.example.com` 環境変数は**デフォルト**アカウント (`default`) にのみ適用されます。その他のアカウントは構成ファイルの値を使用する必要があります。 ## チャットモード Mattermost は DM に自動的に応答します。チャネルでの動作は `chatmode` で制御されます: * `oncall` (デフォルト): チャネルで @メンションされた場合にのみ応答します。 * `onmessage`: すべてのチャネルメッセージに応答します。 * `onchar`: メッセージが特定のトリガープレフィックスで始まる場合に応答します。 構成例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { mattermost: { chatmode: "onchar", oncharPrefixes: [">", "!"], }, }, } ``` 注: * `onchar` モードでも、明示的な @メンションには引き続き応答します。 * レガシーな構成では `channels.mattermost.requireMention` も尊重されますが、`chatmode` の使用を推奨します。 ## アクセス制御 (DM) * デフォルト: `channels.mattermost.dmPolicy = "pairing"`（未知の送信者にはペアリングコードが送信されます）。 * 承認方法: * `openclaw pairing list mattermost` * `openclaw pairing approve mattermost ` * パブリック DM: `channels.mattermost.dmPolicy="open"` かつ `channels.mattermost.allowFrom=["*"]`。 ## チャネル (グループ) * デフォルト: `channels.mattermost.groupPolicy = "allowlist"`（メンション制限あり）。 * `channels.mattermost.groupAllowFrom` で送信者を許可リストに登録します（ユーザー ID を推奨）。 * `@username` による照合は変更可能であり、`channels.mattermost.dangerouslyAllowNameMatching: true` が設定されている場合にのみ有効になります。 * オープンチャネル: `channels.mattermost.groupPolicy="open"`（メンション制限あり）。 * ランタイムに関する注意: `channels.mattermost` セクションが完全に欠落している場合、ランタイムはグループチェックのために `groupPolicy="allowlist"` にフォールバックします（`channels.defaults.groupPolicy` が設定されている場合でも）。 ## アウトバウンド配信のターゲット `openclaw message send` や Cron/Webhook で使用できるターゲット形式は以下の通りです: * チャネルの場合: `channel:` * DM の場合: `user:` * DM の場合: `@username` (Mattermost API 経由で解決) プレフィックスのない ID はチャネルとして扱われます。 ## リアクション (メッセージツール) * `channel=mattermost` で `message action=react` を使用します。 * `messageId` は Mattermost の投稿 ID です。 * `emoji` は `thumbsup` や `:+1:` のような名前を受け入れます（コロンは任意）。 * リアクションを削除するには `remove=true` (boolean) を設定します。 * リアクションの追加/削除イベントは、ルーティングされたエージェントセッションにシステムイベントとして転送されます。 例: ``` message action=react channel=mattermost target=channel: messageId= emoji=thumbsup message action=react channel=mattermost target=channel: messageId= emoji=thumbsup remove=true ``` 構成: * `channels.mattermost.actions.reactions`: リアクション操作を有効/無効にします（デフォルト: true）。 * アカウントごとのオーバーライド: `channels.mattermost.accounts..actions.reactions`。 ## インタラクティブボタン (メッセージツール) クリック可能なボタン付きのメッセージを送信できます。ユーザーがボタンをクリックすると、エージェントはその選択内容を受け取って応答できます。 チャネル機能に `inlineButtons` を追加してボタンを有効にします: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { mattermost: { capabilities: ["inlineButtons"], }, }, } ``` `buttons` パラメータを指定して `message action=send` を使用します。ボタンは 2 次元配列（ボタンの行）です: ``` message action=send channel=mattermost target=channel: buttons=[[{"text":"はい","callback_data":"yes"},{"text":"いいえ","callback_data":"no"}]] ``` ボタンのフィールド: * `text` (必須): 表示ラベル。 * `callback_data` (必須): クリック時に返される値（アクション ID として使用）。 * `style` (任意): `"default"`, `"primary"`, または `"danger"`。 ユーザーがボタンをクリックすると: 1. すべてのボタンが確認メッセージに置き換わります（例: 「✓ **はい** が @user によって選択されました」）。 2. エージェントは選択内容をインバウンドメッセージとして受け取り、応答します。 注: * ボタンのコールバックは HMAC-SHA256 検証を使用します（自動で行われ、設定は不要です）。 * Mattermost は API レスポンスからコールバックデータを削除するため（セキュリティ機能）、クリック時にはすべてのボタンが削除されます。部分的な削除はできません。 * ハイフンやアンダースコアを含むアクション ID は自動的にサニタイズされます（Mattermost のルーティング制限のため）。 構成: * `channels.mattermost.capabilities`: 機能文字列の配列。エージェントのシステムプロンプトでボタンツールの説明を有効にするには、`"inlineButtons"` を追加してください。 * `channels.mattermost.interactions.callbackBaseUrl`: ボタンコールバック用のオプションの外部ベース URL（例: `https://gateway.example.com`）。Mattermost がゲートウェイのバインドアドレスに直接到達できない場合に使用します。 * マルチアカウント設定では、`channels.mattermost.accounts..interactions.callbackBaseUrl` 配下でも同じフィールドを設定できます。 * `interactions.callbackBaseUrl` が省略された場合、OpenClaw は `gateway.customBindHost` + `gateway.port` から導出し、さらに `http://localhost:` にフォールバックします。 * 到達可能性ルール: ボタンのコールバック URL は Mattermost サーバーから到達可能である必要があります。`localhost` は、Mattermost と OpenClaw が同じホスト/ネットワーク名前空間で実行されている場合にのみ機能します。 * コールバック先がプライベート/Tailscale/内部アドレスの場合は、Mattermost の `ServiceSettings.AllowedUntrustedInternalConnections` にそのホスト/ドメインを追加してください。 ### 直接 API 連携 (外部スクリプト) 外部スクリプトや Webhook は、エージェントの `message` ツールを通さずに、Mattermost REST API 経由で直接ボタンを投稿できます。可能な限り拡張機能の `buildButtonAttachments()` を使用してください。生の JSON を投稿する場合は、以下のルールに従ってください: **ペイロード構造:** ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channel_id: "", message: "オプションを選択してください:", props: { attachments: [ { actions: [ { id: "mybutton01", // 英数字のみ — 下記参照 type: "button", // 必須。ないとクリックが無視されます name: "承認", // 表示ラベル style: "primary", // 任意: "default", "primary", "danger" integration: { url: "https://gateway.example.com/mattermost/interactions/default", context: { action_id: "mybutton01", // ボタン ID と一致させる必要があります（名前引き引き用） action: "approve", // ... その他のカスタムフィールド ... _token: "", // 下記の HMAC セクション参照 }, }, }, ], }, ], }, } ``` **重要なルール:** 1. アタッチメントは、トップレベルの `attachments` ではなく `props.attachments` に入れる必要があります（トップレベルは無視されます）。 2. すべてのアクションに `type: "button"` が必要です。これがないとクリックが通知されません。 3. すべてのアクションに `id` フィールドが必要です。Mattermost は ID のないアクションを無視します。 4. アクションの `id` は**英数字のみ** (`[a-zA-Z0-9]`) である必要があります。ハイフンやアンダースコアは Mattermost のサーバー側アクションルーティングを破壊します（404 が返ります）。使用前に除去してください。 5. `context.action_id` はボタンの `id` と一致させる必要があります。これにより、確認メッセージに生の ID ではなくボタン名（例: 「承認」）が表示されます。 6. `context.action_id` は必須です。これがないとインタラクションハンドラーは 400 を返します。 **HMAC トークンの生成:** ゲートウェイは HMAC-SHA256 でボタンのクリックを検証します。外部スクリプトは、ゲートウェイの検証ロジックに一致するトークンを生成する必要があります: 1. ボットトークンからシークレットを導出します: `HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)` 2. `_token` を**除く**すべてのフィールドを含むコンテキストオブジェクトを構築します。 3. **キーをソート**し、**スペースなし**でシリアル化します（ゲートウェイはソートされたキーで `JSON.stringify` を行い、コンパクトな出力を生成します）。 4. 署名します: `HMAC-SHA256(key=secret, data=serializedContext)` 5. 生成された 16 進ダイジェストを `_token` としてコンテキストに追加します。 Python の例: ```python theme={"theme":{"light":"min-light","dark":"min-dark"}} 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=(",", ":")` を使用してください。 * 常に**すべて**のコンテキストフィールド（`_token` 以外）を署名対象にしてください。ゲートウェイは `_token` を除去した後、残ったすべてを署名します。一部のフィールドのみを署名すると検証に失敗します。 * `sort_keys=True` を使用してください。ゲートウェイは署名前にキーをソートします。また、Mattermost はペイロード保存時にコンテキストフィールドの順序を変更することがあります。 * シークレットはランダムなバイトではなく、ボットトークンから（決定論的に）導出してください。ボタンを作成するプロセスと検証するゲートウェイで同じシークレットを使用する必要があります。 ## ディレクトリアダプター Mattermost プラグインには、Mattermost API 経由でチャネル名やユーザー名を解決するディレクトリアダプターが含まれています。これにより、`openclaw message send` や Cron/Webhook 配信において `#channel-name` や `@username` をターゲットとして指定できるようになります。 設定は不要です。アダプターはアカウント構成のボットトークンを自動的に使用します。 ## マルチアカウント Mattermost は `channels.mattermost.accounts` 配下で複数のアカウントをサポートしています: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { mattermost: { accounts: { default: { name: "メイン", botToken: "mm-token", baseUrl: "https://chat.example.com" }, alerts: { name: "アラート", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" }, }, }, }, } ``` ## トラブルシューティング * チャネルで返信がない: ボットがチャネルに参加していることを確認し、メンションするか（oncall モード）、プレフィックスを使用するか（onchar モード）、または `chatmode: "onmessage"` を設定してください。 * 認証エラー: ボットトークン、ベース URL、およびアカウントが有効になっているかを確認してください。 * マルチアカウントの問題: 環境変数は `default` アカウントにのみ適用されます。 * ボタンが白い箱として表示される: エージェントが不正な形式のボタンデータを送信している可能性があります。各ボタンに `text` と `callback_data` フィールドの両方が含まれているか確認してください。 * ボタンは表示されるがクリックしても何も起きない: Mattermost サーバー設定の `AllowedUntrustedInternalConnections` に `127.0.0.1 localhost` が含まれているか、また `ServiceSettings.EnablePostActionIntegration` が `true` になっているかを確認してください。 * ボタンをクリックすると 404 が返る: ボタンの `id` にハイフンやアンダースコアが含まれている可能性があります。Mattermost のアクションルーターは英数字以外の ID で動作しません。`[a-zA-Z0-9]` のみを使用してください。 * ゲートウェイログに `invalid _token` と出る: HMAC が一致していません。すべてのコンテキストフィールドを署名しているか（一部ではない）、キーをソートしているか、コンパクトな JSON（スペースなし）を使用しているかを確認してください。上記の HMAC セクションを参照してください。 * ゲートウェイログに `missing _token in context` と出る: ボタンのコンテキストに `_token` フィールドが含まれていません。連携ペイロード構築時に必ず含めるようにしてください。 * 確認メッセージにボタン名ではなく生の ID が表示される: `context.action_id` がボタンの `id` と一致していません。両方に同じサニタイズ後の値を設定してください。 * エージェントがボタンについて知らない: Mattermost チャネル構成に `capabilities: ["inlineButtons"]` を追加してください。 # Microsoft Teams Source: https://openclawdoc.org/channels/msteams Microsoft Teams ボット連携の現状と設定方法をまとめます。対応範囲、前提条件、構成手順、既知の制約を確認できます。 > 「ここに入る者よ、一切の希望を捨てよ。」 更新日: 2026-01-21 ステータス: テキストおよび DM での添付ファイルをサポート。チャネルやグループでのファイル送信には `sharePointSiteId` と Graph API の権限が必要です（[グループチャットでのファイル送信](#sending-files-in-group-chats) を参照）。投票は Adaptive Cards 経由で送信されます。 ## プラグインが必要 Microsoft Teams はプラグインとして提供されており、コアインストールには同梱されていません。 **重大な変更 (2026.1.15):** Microsoft Teams はコアから分離されました。利用する場合はプラグインをインストールする必要があります。 理由: コアインストールの軽量化と、Microsoft Teams の依存関係を個別に更新できるようにするためです。 CLI (npm レジストリ) 経由でインストールします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/msteams ``` ローカルチェックアウト (git リポジトリから実行する場合): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/msteams ``` 構成/オンボーディング中に Teams を選択し、git チェックアウトが検出された場合、OpenClaw は自動的にローカルインストールパスを提案します。 詳細: [プラグイン](/tools/plugin) ## クイックセットアップ (初心者向け) 1. Microsoft Teams プラグインをインストールします。 2. **Azure Bot** (アプリ ID + クライアントシークレット + テナント ID) を作成します。 3. これらの認証情報を使用して OpenClaw を構成します。 4. パブリック URL またはトンネル経由で `/api/messages`（デフォルトポートは 3978）を公開します。 5. Teams アプリパッケージをインストールし、ゲートウェイを起動します。 最小限の構成: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { msteams: { enabled: true, appId: "", appPassword: "", tenantId: "", webhook: { port: 3978, path: "/api/messages" }, }, }, } ``` 注: グループチャットはデフォルトでブロックされています（`channels.msteams.groupPolicy: "allowlist"`）。グループでの応答を許可するには、`channels.msteams.groupAllowFrom` を設定するか、メンション制限付きで誰でも許可する場合は `groupPolicy: "open"` を使用してください。 ## 目標 * Teams の DM、グループチャット、またはチャネル経由で OpenClaw と会話する。 * 確定的なルーティングを維持する: 返信は常にメッセージが届いたチャネルに戻されます。 * 安全なデフォルト設定: 特に設定がない限り、応答にはメンションが必要です。 ## 構成の書き込み デフォルトでは、Microsoft Teams は `/config set|unset` による構成の更新を許可しています（`commands.config: true` が必要です）。 無効にするには以下のように設定します: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { msteams: { groupPolicy: "allowlist", groupAllowFrom: ["user@org.com"], }, }, } ``` **チーム + チャネル許可リスト** * `channels.msteams.teams` 配下にチームとチャネルをリストすることで、グループやチャネルでの返信対象を制限できます。 * キーにはチーム ID または名前を指定できます。チャネルのキーには会話 ID または名前を指定できます。 * `groupPolicy="allowlist"` かつチーム許可リストが存在する場合、リストされたチーム/チャネルのみが許可されます（メンション制限あり）。 * 構成ウィザードでは `チーム名/チャネル名` 形式での入力を受け付け、自動的に保存します。 * 起動時、OpenClaw は許可リスト内のチーム/チャネル名およびユーザー名を ID に解決し（Graph 権限がある場合）、そのマッピングをログに出力します。未解決のエントリは入力された形式のまま保持されます。 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { msteams: { groupPolicy: "allowlist", teams: { "My Team": { channels: { General: { requireMention: true }, }, }, }, }, }, } ``` ## 仕組み 1. Microsoft Teams プラグインをインストールします。 2. **Azure Bot** (アプリ ID + シークレット + テナント ID) を作成します。 3. ボットを参照し、後述の RSC 権限を含む **Teams アプリパッケージ** を構築します。 4. Teams アプリをチーム（または DM 用に個人スコープ）にアップロード/インストールします。 5. `~/.openclaw/openclaw.json` (または環境変数) で `msteams` を構成し、ゲートウェイを起動します。 6. ゲートウェイはデフォルトで `/api/messages` において Bot Framework の Webhook トラフィックをリッスンします。 ## Azure Bot のセットアップ (前提条件) OpenClaw を構成する前に、Azure Bot リソースを作成する必要があります。 ### ステップ 1: Azure Bot を作成する 1. [Azure Bot の作成](https://portal.azure.com/#create/Microsoft.AzureBot) に移動します。 2. **\[基本]** タブを入力します: | フィールド | 値 | | :------------ | :---------------------------------------- | | **ボットハンドル** | ボット名。例: `openclaw-msteams` (一意である必要があります) | | **サブスクリプション** | Azure サブスクリプションを選択 | | **リソースグループ** | 新規作成または既存のものを選択 | | **価格ティア** | 開発/テスト用には **Free** | | **アプリの種類** | **Single Tenant** (推奨 - 下記の注を参照) | | **作成タイプ** | **Create new Microsoft App ID** | > **非推奨の通知:** マルチテナントボットの新規作成は 2025-07-31 以降非推奨となりました。新しいボットには **Single Tenant** を使用してください。 3. **\[確認および作成]** → **\[作成]** をクリックします（1〜2 分待ちます）。 ### ステップ 2: 認証情報を取得する 1. 作成した Azure Bot リソースの **\[構成]** に移動します。 2. **Microsoft アプリ ID** をコピーします。これが `appId` です。 3. **\[管理]** をクリックしてアプリの登録に移動します。 4. **\[証明書とシークレット]** → **\[新しいクライアントシークレット]** → 生成された **値** をコピーします。これが `appPassword` です。 5. **\[概要]** に移動し、**ディレクトリ (テナント) ID** をコピーします。これが `tenantId` です。 ### ステップ 3: メッセージングエンドポイントを構成する 1. Azure Bot の **\[構成]** に戻ります。 2. **メッセージングエンドポイント** を Webhook URL に設定します: * 本番環境: `https://your-domain.com/api/messages` * ローカル開発: トンネルを使用してください（後述の [ローカル開発](#local-development-tunneling) を参照）。 ### ステップ 4: Teams チャネルを有効にする 1. Azure Bot の **\[チャネル]** に移動します。 2. **Microsoft Teams** をクリックし、構成を保存します。 3. 利用規約に同意します。 ## ローカル開発 (トンネリング) Teams は `localhost` に直接到達できません。ローカル開発にはトンネルを使用してください。 **オプション A: ngrok** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ngrok http 3978 # 表示された https URL (例: https://abc123.ngrok.io) をコピーします。 # メッセージングエンドポイントを次のように設定します: https://abc123.ngrok.io/api/messages ``` **オプション B: Tailscale Funnel** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} tailscale funnel 3978 # Tailscale Funnel の URL をメッセージングエンドポイントとして使用します。 ``` ## Teams Developer Portal (代替方法) マニフェスト 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 のアプリ ID を貼り付けます。 5. スコープ（**Personal**, **Team**, **Group Chat**）にチェックを入れます。 6. **\[Publish]** → **\[Download app package]** をクリックします。 7. Teams で: **\[アプリ]** → **\[アプリの管理]** → **\[カスタムアプリをアップロード]** → ZIP を選択します。 これは JSON マニフェストを手動で編集するよりも簡単な場合が多いです。 ## ボットのテスト **オプション A: Azure Web チャット (最初に Webhook を確認)** 1. Azure ポータル → Azure Bot リソース → **\[Web チャットでテスト]** に移動します。 2. メッセージを送信し、応答があるか確認します。 3. これにより、Teams の設定前に Webhook エンドポイントが正常に動作していることが確認できます。 **オプション B: Teams (アプリインストール後)** 1. Teams アプリをインストールします（サイドロードまたは組織のカタログ経由）。 2. Teams でボットを探し、DM を送信します。 3. ゲートウェイのログで受信アクティビティを確認します。 ## セットアップ (テキストのみの最小構成) 1. **Microsoft Teams プラグインをインストールする** * npm から: `openclaw plugins install @openclaw/msteams` * ローカルチェックアウトから: `openclaw plugins install ./extensions/msteams` 2. **ボットの登録** * 上記の手順に従って Azure Bot を作成し、以下をメモします: * アプリ ID * クライアントシークレット (アプリパスワード) * テナント ID (Single Tenant) 3. **Teams アプリマニフェスト** * `botId = ` を含む `bot` エントリを含めます。 * スコープに `personal`, `team`, `groupChat` を含めます。 * 個人スコープでのファイル処理用に `supportsFiles: true` を設定します。 * 後述の RSC 権限を追加します。 * アイコンファイル `outline.png` (32x32) と `color.png` (192x192) を作成します。 * `manifest.json`, `outline.png`, `color.png` の 3 つを ZIP 圧縮します。 4. **OpenClaw を構成する** ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "msteams": { "enabled": true, "appId": "", "appPassword": "", "tenantId": "", "webhook": { "port": 3978, "path": "/api/messages" } } } ``` 構成ファイルのキーの代わりに環境変数を使用することもできます: * `MSTEAMS_APP_ID` * `MSTEAMS_APP_PASSWORD` * `MSTEAMS_TENANT_ID` 5. **ボットのエンドポイント** * Azure Bot のメッセージングエンドポイントを以下に設定します: * `https://:3978/api/messages` (または自身で設定したパス/ポート) 6. **ゲートウェイを実行する** * プラグインがインストールされ、認証情報を含む `msteams` 構成が存在すれば、Teams チャネルは自動的に開始されます。 ## 履歴コンテキスト * `channels.msteams.historyLimit` は、プロンプトに含まれる最近のチャネル/グループメッセージの数を制御します。 * 未設定時は `messages.groupChat.historyLimit` にフォールバックします。`0` を設定すると無効になります（デフォルトは 50）。 * DM の履歴は `channels.msteams.dmHistoryLimit` (ユーザーのターン数) で制限できます。ユーザーごとのオーバーライドは `channels.msteams.dms[""].historyLimit` です。 ## 現在の Teams RSC 権限 (マニフェスト) これらは Teams アプリマニフェストにおける **resourceSpecific 権限** です。これらはアプリがインストールされているチーム/チャット内でのみ適用されます。 **チャネル用 (チームスコープ):** * `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 マニフェストの例 (抜粋) 必須フィールドを含む最小限の有効な例です。ID と URL は適宜置き換えてください。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "$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" } ] } } } ``` ### マニフェストに関する注意点 (必須フィールド) * `bots[].botId` は Azure Bot のアプリ ID と **必ず** 一致させる必要があります。 * `webApplicationInfo.id` も Azure Bot のアプリ ID と **必ず** 一致させる必要があります。 * `bots[].scopes` には、利用予定のサーフェス（`personal`, `team`, `groupChat`）を含める必要があります。 * 個人スコープでのファイル処理には `bots[].supportsFiles: true` が必須です。 * チャネルのトラフィックを受信するには、`authorization.permissions.resourceSpecific` にチャネルの読み取り/送信権限を含める必要があります。 ### 既存のアプリの更新 インストール済みの Teams アプリを更新する場合（RSC 権限の追加など）: 1. `manifest.json` を新しい設定で更新します。 2. **`version` フィールドをインクリメント**します（例: `1.0.0` → `1.1.0`）。 3. アイコンを含めて再度 ZIP 圧縮します (`manifest.json`, `outline.png`, `color.png`)。 4. 新しい ZIP をアップロードします: * **オプション A (Teams 管理センター):** 管理センター → Teams アプリ → アプリの管理 → 対象のアプリを検索 → \[新しいバージョンのアップロード] * **オプション B (サイドロード):** Teams → アプリ → アプリの管理 → \[カスタムアプリをアップロード] 5. **チームチャネルの場合:** 新しい権限を有効にするには、各チームでアプリを再インストールしてください。 6. **Teams を完全に終了して再起動**し（ウィンドウを閉じるだけでなく）、キャッシュされたメタデータをクリアします。 ## 機能: RSC のみ vs Graph API ### **Teams RSC のみ** の場合（アプリインストールのみ、Graph API 権限なし） 可能なこと: * チャネルメッセージの **テキスト** コンテンツの読み取り。 * チャネルメッセージの **テキスト** コンテンツの送信。 * **個人 (DM)** における添付ファイルの受信。 不可能なこと: * チャネル/グループにおける **画像やファイルのコンテンツ** の取得（ペイロードには HTML のスタブのみが含まれます）。 * SharePoint/OneDrive に保存された添付ファイルのダウンロード。 * メッセージ履歴の読み取り（ライブ Webhook イベント以外のもの）。 ### **Teams RSC + Microsoft Graph アプリケーション権限** の場合 追加で可能なこと: * ホストされたコンテンツ（メッセージに貼り付けられた画像）のダウンロード。 * SharePoint/OneDrive に保存された添付ファイルのダウンロード。 * Graph 経由でのチャネル/チャットメッセージ履歴の読み取り。 ### RSC vs Graph API | 機能 | RSC 権限 | Graph API | | :-------------- | :---------------- | :------------------ | | **リアルタイムメッセージ** | ✅ 可能 (Webhook 経由) | ❌ 不可 (ポーリングのみ) | | **履歴メッセージ** | ❌ 不可 | ✅ 可能 (履歴のクエリ) | | **セットアップの複雑さ** | アプリマニフェストのみ | 管理者の同意 + トークンフローが必要 | | **オフライン動作** | ❌ 不可 (実行中である必要あり) | ✅ 可能 (いつでもクエリ可能) | **結論:** RSC はリアルタイムの監視用、Graph API は履歴アクセス用です。オフライン中に届いたメッセージを確認するには、`ChannelMessage.Read.All` 権限を持つ Graph API が必要です（管理者の同意が必要です）。 ## Graph を使用したメディア + 履歴 (チャネルで必要) **チャネル** での画像/ファイルが必要な場合、または **メッセージ履歴** を取得したい場合は、Microsoft Graph の権限を有効にして管理者の同意を得る必要があります。 1. Entra ID (Azure AD) の **\[アプリの登録]** で、以下の Microsoft Graph **アプリケーション権限** を追加します: * `ChannelMessage.Read.All` (チャネルの添付ファイル + 履歴) * `Chat.Read.All` または `ChatMessage.Read.All` (グループチャット) 2. テナントに対して **管理者の同意を付与** します。 3. Teams アプリの **マニフェストバージョンを上げ**、再アップロードして **Teams でアプリを再インストール** します。 4. **Teams を完全に終了して再起動** し、キャッシュをクリアします。 **ユーザーメンション用の追加権限:** 同じ会話内にいるユーザーへの @メンションは標準で動作します。ただし、**現在の会話に参加していない** ユーザーを動的に検索してメンションしたい場合は、`User.Read.All` (Application) 権限を追加して管理者の同意を得てください。 ## 既知の制限事項 ### Webhook のタイムアウト Teams は HTTP Webhook 経由でメッセージを配信します。処理（LLM の応答など）に時間がかかりすぎると、以下が発生する可能性があります: * ゲートウェイのタイムアウト * Teams によるメッセージの再送（重複の原因） * 返信の欠落 OpenClaw は、即座に応答を返しつつバックグラウンドで返信を送信することでこれに対処していますが、極端に応答が遅い場合には問題が発生することがあります。 ### 書式設定 Teams の Markdown は Slack や Discord よりも制限されています: * 基本的な書式は動作します: **太字**, *斜体*, `コード`, リンク * 複雑な 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/表示名による一致を再有効化する非常用スイッチ。 * `channels.msteams.textChunkLimit`: アウトバウンドテキストのチャンクサイズ。 * `channels.msteams.chunkMode`: `length` (デフォルト) または `newline`（長さで分割する前に段落境界で分割）。 * `channels.msteams.mediaAllowHosts`: 受信添付ファイルのホスト許可リスト（デフォルトは Microsoft/Teams ドメイン）。 * `channels.msteams.mediaAuthAllowHosts`: メディア再試行時に Authorization ヘッダーを付加するホストの許可リスト（デフォルトは Graph + Bot Framework ホスト）。このリストは厳密に保ってください。 * `channels.msteams.requireMention`: チャネル/グループでの @メンションを必須にする（デフォルト true）。 * `channels.msteams.replyStyle`: `thread | top-level` ([返信スタイル](#reply-style-threads-vs-posts) を参照)。 * `channels.msteams.teams..replyStyle`: チームごとの上書き。 * `channels.msteams.teams..requireMention`: チームごとの上書き。 * `channels.msteams.teams..tools`: チャネル固有の設定がない場合に使用される、チームごとのデフォルトツールポリシー (`allow`/`deny`/`alsoAllow`)。 * `channels.msteams.teams..toolsBySender`: チームごと、送信者ごとのデフォルトツールポリシー（`*` ワイルドカード対応）。 * `channels.msteams.teams..channels..replyStyle`: チャネルごとの上書き。 * `channels.msteams.teams..channels..requireMention`: チャネルごとの上書き。 * `channels.msteams.teams..channels..tools`: チャネルごとのツールポリシー (`allow`/`deny`/`alsoAllow`)。 * `channels.msteams.teams..channels..toolsBySender`: チャネルごと、送信者ごとのツールポリシー（`*` ワイルドカード対応）。 * `toolsBySender` のキーには明示的なプレフィックスを使用してください: `id:`, `e164:`, `username:`, `name:` (プレフィックスなしの古いキーは `id:` のみとして扱われます)。 * `channels.msteams.sharePointSiteId`: グループチャット/チャネルでのファイルアップロード用 SharePoint サイト ID（[グループチャットでのファイル送信](#sending-files-in-group-chats) を参照）。 ## ルーティングとセッション * セッションキーは標準のエージェント形式に従います ([/concepts/session](/concepts/session) を参照): * DM はメインセッション (`agent::`) を共有します。 * チャネル/グループメッセージは会話 ID を使用します: * `agent::msteams:channel:` * `agent::msteams:group:` ## 返信スタイル: スレッド vs 投稿 Teams では最近、同じデータモデルに対して 2 つのチャネル UI スタイルが導入されました: | スタイル | 説明 | 推奨される `replyStyle` | | :-------------------- | :-------------------------------- | :----------------- | | **Posts** (クラシック) | メッセージがカードとして表示され、その下にスレッド形式の返信が並ぶ | `thread` (デフォルト) | | **Threads** (Slack 風) | メッセージが Slack のように直線的に流れる | `top-level` | **問題点:** Teams API はチャネルがどちらの UI スタイルを使用しているかを公開していません。誤った `replyStyle` を使用すると以下のようになります: * スタイルが「Threads」のチャネルで `thread` を使用 → 返信が不自然にネストされる * スタイルが「Posts」のチャネルで `top-level` を使用 → 返信がスレッド内ではなく、新しいトップレベルの投稿として作成される **解決策:** チャネルの設定に合わせて、チャネルごとに `replyStyle` を構成してください: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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 の権限が必要** です。 Graph 権限がない場合、画像付きのチャネルメッセージはテキストのみとして受信されます（ボットは画像内容にアクセスできません）。 デフォルトでは、OpenClaw は Microsoft/Teams のホスト名からのみメディアをダウンロードします。`channels.msteams.mediaAllowHosts` で上書き可能です（`["*"]` で全ホストを許可）。 Authorization ヘッダーは、`channels.msteams.mediaAuthAllowHosts` にリストされたホストに対してのみ付加されます（デフォルトは Graph + Bot Framework ホスト）。 ## グループチャットでのファイル送信 ボットは DM においては FileConsentCard フロー（組み込み）を使用してファイルを送信できます。しかし、**グループチャットやチャネルでファイルを送信する** には追加の設定が必要です: | コンテキスト | 送信方法 | 必要な設定 | | :---------------- | :----------------------------------- | :---------------------------- | | **DM** | FileConsentCard → ユーザー承諾 → ボットアップロード | 標準で動作 | | **グループチャット/チャネル** | SharePoint へアップロード → 共有リンク送信 | `sharePointSiteId` + Graph 権限 | | **画像 (全コンテキスト)** | Base64 エンコードされたインライン送信 | 標準で動作 | ### なぜグループチャットに SharePoint が必要なのか ボットは個人の OneDrive ドライブを持っていません（`/me/drive` Graph API エンドポイントはアプリケーション ID では動作しません）。グループチャットやチャネルでファイルを送信するには、ボットは **SharePoint サイト** にアップロードして共有リンクを作成する必要があります。 ### セットアップ 1. Entra ID (Azure AD) → アプリの登録で **Graph API 権限を追加** します: * `Sites.ReadWrite.All` (Application) - SharePoint へのファイルアップロード * `Chat.Read.All` (Application) - 任意。ユーザーごとの共有リンクを有効にします。 2. テナントに対して **管理者の同意を付与** します。 3. **SharePoint サイト ID を取得します:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # Graph Explorer または有効なトークンを用いた curl で取得: curl -H "Authorization: Bearer $TOKEN" \ "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}" # 例: "contoso.sharepoint.com/sites/BotFiles" の場合 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { msteams: { // ... その他の設定 ... sharePointSiteId: "contoso.sharepoint.com,guid1,guid2", }, }, } ``` ### 共有動作 | 権限 | 共有動作 | | :-------------------------------------- | :---------------------------- | | `Sites.ReadWrite.All` のみ | 組織全体の共有リンク（組織内の誰でもアクセス可能） | | `Sites.ReadWrite.All` + `Chat.Read.All` | ユーザーごとの共有リンク（チャット参加者のみアクセス可能） | ユーザーごとの共有の方が、チャット参加者のみがファイルにアクセスできるため安全です。`Chat.Read.All` 権限がない場合、ボットは組織全体の共有にフォールバックします。 ### フォールバック動作 | シナリオ | 結果 | | :---------------------------------------- | :------------------------------------ | | グループチャット + ファイル + `sharePointSiteId` 設定あり | SharePoint へアップロードし、共有リンクを送信 | | グループチャット + ファイル + `sharePointSiteId` 設定なし | OneDrive アップロードを試行（失敗の可能性あり）、テキストのみ送信 | | 個人チャット + ファイル | FileConsentCard フロー (SharePoint 不要) | | 全コンテキスト + 画像 | Base64 インライン送信 (SharePoint 不要) | ### ファイルの保存場所 アップロードされたファイルは、構成された SharePoint サイトのデフォルトドキュメントライブラリ内の `/OpenClawShared/` フォルダに保存されます。 ## 投票 (Adaptive Cards) OpenClaw は Teams の投票を Adaptive Cards として送信します（Teams にはネイティブの投票 API がありません）。 * CLI: `openclaw message poll --channel msteams --target conversation: ...` * 投票結果はゲートウェイにより `~/.openclaw/msteams-polls.json` に記録されます。 * 投票を記録するにはゲートウェイがオンラインである必要があります。 * 現時点では結果の概要は自動投稿されません（必要に応じてストアファイルを直接確認してください）。 ## Adaptive Cards (任意形式) `message` ツールまたは CLI を使用して、任意の Adaptive Card JSON を Teams ユーザーや会話に送信できます。 `card` パラメータに Adaptive Card JSON オブジェクトを渡します。`card` を指定した場合、メッセージテキストは任意となります。 **エージェントツール:** ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "action": "send", "channel": "msteams", "target": "user:", "card": { "type": "AdaptiveCard", "version": "1.5", "body": [{ "type": "TextBlock", "text": "こんにちは！" }] } } ``` **CLI:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw message send --channel msteams \ --target "conversation:19:abc...@thread.tacv2" \ --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"こんにちは！"}]}' ``` カードのスキーマや例については [Adaptive Cards documentation](https://adaptivecards.io/) を参照してください。ターゲット形式の詳細については [ターゲット形式](#target-formats) を参照してください。 ## ターゲット形式 MSTeams のターゲットは、プレフィックスを使用してユーザーと会話を区別します: | ターゲットタイプ | 形式 | 例 | | :------------ | :------------------------------- | :-------------------------------------------- | | ユーザー (ID 指定) | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | | ユーザー (名前指定) | `user:` | `user:John Smith` (Graph API が必要) | | グループ/チャネル | `conversation:` | `conversation:19:abc123...@thread.tacv2` | | グループ/チャネル (生) | `` | `19:abc123...@thread.tacv2` (`@thread` を含む場合) | **CLI の例:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # ID でユーザーに送信 openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "こんにちは" # 表示名でユーザーに送信 (Graph API による検索をトリガー) openclaw message send --channel msteams --target "user:John Smith" --message "こんにちは" # グループチャットまたはチャネルに送信 openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "こんにちは" # 会話に Adaptive Card を送信 openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \ --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"こんにちは"}]}' ``` **エージェントツールの例:** ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "action": "send", "channel": "msteams", "target": "user:John Smith", "message": "こんにちは！" } ``` ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "action": "send", "channel": "msteams", "target": "conversation:19:abc...@thread.tacv2", "card": { "type": "AdaptiveCard", "version": "1.5", "body": [{ "type": "TextBlock", "text": "こんにちは" }] } } ``` 注: `user:` プレフィックスがない場合、名前はデフォルトでグループ/チームとして解決されます。表示名で個人を指定する場合は、必ず `user:` を使用してください。 ## プロアクティブメッセージング * プロアクティブメッセージ（ボットからの自発的な送信）は、ユーザーが一度対話した後でのみ可能です（その時点で会話の参照情報が保存されるため）。 * `dmPolicy` や許可リストによる制限については `/gateway/configuration` を参照してください。 ## チーム ID とチャネル ID (よくある間違い) Teams URL に含まれる `groupId` クエリパラメータは、構成で使用するチーム ID **ではありません**。URL パスから ID を抽出してください: **チーム URL:** ``` https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=... └────────────────────────────┘ チーム ID (これを URL デコードしてください) ``` **チャネル URL:** ``` https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=... └─────────────────────────┘ チャネル ID (これを URL デコードしてください) ``` **構成用:** * チーム ID = `/team/` の後のパスセグメント (URL デコード後。例: `19:Bk4j...@thread.tacv2`) * チャネル ID = `/channel/` の後のパスセグメント (URL デコード後) * `groupId` クエリパラメータは **無視** してください。 ## プライベートチャネル プライベートチャネルでは、ボットのサポートが制限されています: | 機能 | 標準チャネル | プライベートチャネル | | :-------------------- | :----- | :--------------- | | ボットのインストール | ✅ 可能 | ⚠️ 制限あり | | リアルタイムメッセージ (Webhook) | ✅ 可能 | ⚠️ 動作しない場合あり | | RSC 権限 | ✅ 可能 | ⚠️ 挙動が異なる場合あり | | @メンション | ✅ 可能 | ⚠️ ボットがアクセス可能な場合 | | Graph API 履歴 | ✅ 可能 | ✅ 可能 (権限が必要) | **プライベートチャネルで動作しない場合の回避策:** 1. ボットとの対話には標準チャネルを使用する。 2. DM を使用する（ユーザーは常にボットに直接メッセージを送れます）。 3. 履歴アクセスには Graph API を使用する（`ChannelMessage.Read.All` が必要）。 ## トラブルシューティング ### よくある問題 * **チャネルで画像が表示されない:** Graph 権限または管理者の同意が不足しています。Teams アプリを再インストールし、Teams を完全に終了してから開き直してください。 * **チャネルで応答がない:** デフォルトではメンションが必要です。`channels.msteams.requireMention=false` を設定するか、チーム/チャネルごとに構成してください。 * **バージョンの不一致 (Teams に古いマニフェストが残っている):** アプリを一度削除して再追加し、Teams を完全に終了して再起動してください。 * **Webhook から 401 Unauthorized が返る:** Azure JWT なしで手動テストした場合は正常な動作です（エンドポイントには到達しているが認証に失敗したことを示します）。正しくテストするには Azure Web Chat を使用してください。 ### マニフェストアップロードのエラー * **"Icon file cannot be empty":** マニフェストが 0 バイトのアイコンファイルを参照しています。有効な PNG アイコン（32x32 の `outline.png`, 192x192 の `color.png`）を作成してください。 * **"webApplicationInfo.Id already in use":** アプリがまだ他のチーム/チャットにインストールされています。アンインストールするか、反映まで 5〜10 分待ってください。 * **アップロード時に "Something went wrong":** 代わりに [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) からアップロードを試み、ブラウザの DevTools (F12) → \[Network] タブで実際の詳細なエラーを確認してください。 * **サイドロードに失敗する:** 「カスタムアプリをアップロード」ではなく「組織のアプリカタログにアプリをアップロード」を試してください。これにより制限を回避できる場合があります。 ### RSC 権限が動作しない 1. `webApplicationInfo.id` がボットのアプリ ID と完全に一致しているか確認してください。 2. アプリを再アップロードし、チーム/チャットで再インストールしてください。 3. 組織の管理者が RSC 権限をブロックしていないか確認してください。 4. 正しいスコープを使用しているか確認してください（チームには `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 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) # Nextcloud Talk Source: https://openclawdoc.org/channels/nextcloud-talk Nextcloud Talk を OpenClaw に接続する設定ガイドです。webhook ボット連携、DM とルーム対応、プラグイン導入手順を確認できます。 ステータス: プラグイン (webhook ボット) 経由でサポートされています。ダイレクトメッセージ、ルーム、リアクション、および Markdown メッセージがサポートされています。 ## プラグインが必要 Nextcloud Talk はプラグインとして提供されており、コアインストールには同梱されていません。 CLI (npm レジストリ) 経由でインストールします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/nextcloud-talk ``` ローカルチェックアウト (git リポジトリから実行する場合): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/nextcloud-talk ``` 構成/オンボーディング中に Nextcloud Talk を選択し、git チェックアウトが検出された場合、OpenClaw は自動的にローカルインストールパスを提案します。 詳細: [プラグイン](/tools/plugin) ## クイックセットアップ (初心者向け) 1. Nextcloud Talk プラグインをインストールします。 2. Nextcloud サーバーでボットを作成します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ./occ talk:bot:install "OpenClaw" "" "" --feature reaction ``` 3. 対象のルーム設定でボットを有効にします。 4. OpenClaw を構成します: * 構成ファイル: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret` * または環境変数: `NEXTCLOUD_TALK_BOT_SECRET` (デフォルトアカウントのみ) 5. ゲートウェイを再起動します (またはオンボーディングを完了させます)。 最小限の構成: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { "nextcloud-talk": { enabled: true, baseUrl: "https://cloud.example.com", botSecret: "shared-secret", dmPolicy: "pairing", }, }, } ``` ## 注意事項 * ボットから DM を開始することはできません。ユーザーが最初にボットへメッセージを送信する必要があります。 * webhook URL はゲートウェイから到達可能である必要があります。プロキシの背後にある場合は `webhookPublicUrl` を設定してください。 * ボット API ではメディアのアップロードはサポートされていません。メディアは URL として送信されます。 * webhook のペイロードでは DM とルームが区別されません。ルームタイプの検索を有効にするには `apiUser` + `apiPassword` を設定してください（設定しない場合、DM はルームとして扱われます）。 ## アクセス制御 (DM) * デフォルト: `channels.nextcloud-talk.dmPolicy = "pairing"`。未知の送信者にはペアリングコードが送信されます。 * 承認方法: * `openclaw pairing list nextcloud-talk` * `openclaw pairing approve nextcloud-talk ` * パブリック DM: `channels.nextcloud-talk.dmPolicy="open"` かつ `channels.nextcloud-talk.allowFrom=["*"]`。 * `allowFrom` は Nextcloud のユーザー ID にのみ一致します。表示名は無視されます。 ## ルーム (グループ) * デフォルト: `channels.nextcloud-talk.groupPolicy = "allowlist"` (メンション制限あり)。 * ルームを許可リストに追加するには `channels.nextcloud-talk.rooms` を使用します: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { "nextcloud-talk": { rooms: { "room-token": { requireMention: true }, }, }, }, } ``` * ルームを一切許可しない場合は、許可リストを空にするか `channels.nextcloud-talk.groupPolicy="disabled"` を設定してください。 ## 機能 | 機能 | ステータス | | :--------- | :----- | | ダイレクトメッセージ | サポート済み | | ルーム | サポート済み | | スレッド | 未サポート | | メディア | URL のみ | | リアクション | サポート済み | | ネイティブコマンド | 未サポート | ## 構成リファレンス (Nextcloud Talk) 完全な構成: [構成](/gateway/configuration) プロバイダーオプション: * `channels.nextcloud-talk.enabled`: チャネルの起動を有効/無効にします。 * `channels.nextcloud-talk.baseUrl`: Nextcloud インスタンスの URL。 * `channels.nextcloud-talk.botSecret`: ボットの共有シークレット。 * `channels.nextcloud-talk.botSecretFile`: シークレットファイルのパス。 * `channels.nextcloud-talk.apiUser`: ルーム検索（DM 検出）用の API ユーザー。 * `channels.nextcloud-talk.apiPassword`: ルーム検索用の API/アプリパスワード。 * `channels.nextcloud-talk.apiPasswordFile`: API パスワードファイルのパス。 * `channels.nextcloud-talk.webhookPort`: webhook リスナーポート (デフォルト: 8788)。 * `channels.nextcloud-talk.webhookHost`: webhook host (デフォルト: 0.0.0.0)。 * `channels.nextcloud-talk.webhookPath`: webhook path (デフォルト: /nextcloud-talk-webhook)。 * `channels.nextcloud-talk.webhookPublicUrl`: 外部から到達可能な webhook URL。 * `channels.nextcloud-talk.dmPolicy`: `pairing | allowlist | open | disabled`。 * `channels.nextcloud-talk.allowFrom`: DM 許可リスト (ユーザー ID)。`open` の場合は `"*"` が必要です。 * `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`。 * `channels.nextcloud-talk.groupAllowFrom`: グループ許可リスト (ユーザー ID)。 * `channels.nextcloud-talk.rooms`: ルームごとの設定と許可リスト。 * `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`: ブロックストリーミング結合の調整。 * `channels.nextcloud-talk.mediaMaxMb`: 受信メディアの上限サイズ (MB)。 # Nostr Source: https://openclawdoc.org/channels/nostr Nostr DM チャネルを OpenClaw に接続する設定ガイドです。NIP-04 暗号化メッセージ対応、プラグイン有効化、基本構成を確認できます。 **ステータス:** オプションのプラグイン (デフォルトでは無効)。 Nostr は、ソーシャルネットワーキング用の分散型プロトコルです。このチャネルを有効にすると、OpenClaw は NIP-04 経由で暗号化されたダイレクトメッセージ (DM) を受信し、応答できるようになります。 ## インストール (オンデマンド) ### オンボーディング (推奨) * オンボーディングウィザード (`openclaw onboard`) や `openclaw channels add` では、オプションのチャネルプラグインが一覧表示されます。 * Nostr を選択すると、必要に応じてプラグインをインストールするように求められます。 インストールのデフォルト動作: * **dev チャンネル + git チェックアウトが利用可能:** ローカルのプラグインパスを使用します。 * **stable/beta チャンネル:** npm からダウンロードします。 プロンプトでの選択はいつでも上書き可能です。 ### 手動インストール ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/nostr ``` ローカルチェックアウトを使用する場合 (開発ワークフロー): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install --link /extensions/nostr ``` プラグインをインストールまたは有効にした後は、ゲートウェイを再起動してください。 ## クイックセットアップ 1. Nostr のキーペアを生成します (必要な場合): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # nak を使用する場合 nak key generate ``` 2. 構成ファイルに追加します: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}" } } } ``` 3. キーを環境変数としてエクスポートします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export NOSTR_PRIVATE_KEY="nsec1..." ``` 4. ゲートウェイを再起動します。 ## 構成リファレンス | キー | 型 | デフォルト | 説明 | | :----------- | :-------- | :------------------------------------------ | :-------------------- | | `privateKey` | string | 必須 | `nsec` または 16 進形式の秘密鍵 | | `relays` | string\[] | `['wss://relay.damus.io', 'wss://nos.lol']` | リレー URL (WebSocket) | | `dmPolicy` | string | `pairing` | DM アクセスポリシー | | `allowFrom` | string\[] | `[]` | 許可された送信者の公開鍵 | | `enabled` | boolean | `true` | チャネルの有効/無効 | | `name` | string | - | 表示名 | | `profile` | object | - | NIP-01 プロフィールメタデータ | ## プロフィールメタデータ プロフィールデータは NIP-01 `kind:0` イベントとして公開されます。コントロール UI (Channels -> Nostr -> Profile) から管理するか、構成ファイルで直接設定できます。 構成例: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "profile": { "name": "openclaw", "displayName": "OpenClaw", "about": "パーソナルアシスタント DM ボット", "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://` を使用する必要があります。 * リレーからインポートすると、フィールドがマージされ、ローカルの上書き設定が保持されます。 ## アクセス制御 ### DM ポリシー * **pairing** (デフォルト): 未知の送信者にはペアリングコードが送信されます。 * **allowlist**: `allowFrom` に含まれる公開鍵のみが DM を送信できます。 * **open**: パブリックな受信 DM を許可します (`allowFrom: ["*"]` が必要)。 * **disabled**: 受信 DM を無視します。 ### 許可リストの例 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "dmPolicy": "allowlist", "allowFrom": ["npub1abc...", "npub1xyz..."] } } } ``` ## キーの形式 以下の形式を受け入れます: * **秘密鍵:** `nsec...` または 64 文字の 16 進数 * **公開鍵 (`allowFrom`):** `npub...` または 16 進数 ## リレー (Relays) デフォルト設定: `relay.damus.io` および `nos.lol`。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "relays": ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"] } } } ``` ヒント: * 冗長性のために 2〜3 個のリレーを使用してください。 * リレーが多すぎると遅延や重複の原因となるため避けてください。 * 有料リレーを使用すると信頼性が向上する場合があります。 * テストにはローカルリレーが適しています (`ws://localhost:7777`)。 ## プロトコルのサポート | NIP | ステータス | 説明 | | :----- | :----- | :----------------------- | | NIP-01 | サポート済み | 基本的なイベント形式 + プロフィールメタデータ | | NIP-04 | サポート済み | 暗号化 DM (`kind:4`) | | NIP-17 | 計画中 | ギフト包装 (Gift-wrapped) DM | | NIP-44 | 計画中 | バージョン管理された暗号化 | ## テスト ### ローカルリレー ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # strfry を起動 docker run -p 7777:7777 ghcr.io/hoytech/strfry ``` ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "relays": ["ws://localhost:7777"] } } } ``` ### 手動テスト 1. ログからボットの公開鍵 (npub) をメモします。 2. Nostr クライアント (Damus, Amethyst 等) を開きます。 3. ボットの公開鍵に DM を送信します。 4. 応答を確認します。 ## トラブルシューティング ### メッセージを受信できない * 秘密鍵が有効であることを確認してください。 * リレーの URL が到達可能であり、`wss://` (ローカルの場合は `ws://`) を使用していることを確認してください。 * `enabled` が `false` になっていないか確認してください。 * ゲートウェイのログでリレーの接続エラーを確認してください。 ### 応答を送信できない * リレーが書き込みを受け入れているか確認してください。 * アウトバウンドの接続性を確認してください。 * リレーのレート制限に注意してください。 ### 応答が重複する * 複数のリレーを使用している場合、重複は想定内の動作です。 * メッセージはイベント ID によって重複排除されます。最初のアクティベーションのみが応答をトリガーします。 ## セキュリティ * 秘密鍵を決してコミットしないでください。 * キーの管理には環境変数を使用してください。 * 本番用のボットには `allowlist` の使用を検討してください。 ## 制限事項 (MVP) * ダイレクトメッセージのみ (グループチャットは不可)。 * メディアの添付は未サポート。 * NIP-04 のみ (NIP-17 のギフト包装は計画中)。 # Pairing Source: https://openclawdoc.org/channels/pairing DM 送信者とノード参加を所有者承認で管理するペアリング機能のガイドです。アクセス制御の考え方と設定フローを確認できます。 「ペアリング」は、OpenClaw の明示的な **所有者の承認** ステップです。 次の 2 つの場所で使用されます。 1. **DM ペアリング** (ボットとの会話を許可されるユーザー) 2. **ノードのペアリング** (ゲートウェイ ネットワークへの参加を許可されるデバイス/ノード) セキュリティコンテキスト: [セキュリティ](/gateway/security) ## 1) DM ペアリング (インバウンド チャット アクセス) チャネルが DM ポリシー `pairing` で構成されている場合、不明な送信者はショート コードを受け取り、承認されるまでメッセージは **処理されません**。 デフォルトの DM ポリシーは、[セキュリティ](/gateway/security) に文書化されています。 ペアリングコード: * 8 文字、大文字、あいまいな文字は含まれません (`0O1I`)。 * **1 時間後に期限切れになります**。ボットは、新しいリクエストが作成されたときにのみペアリング メッセージを送信します (送信者ごとに 1 時間に 1 回程度)。 * 保留中の DM ペアリング要求は、デフォルトで **チャネルごとに 3** に制限されます。追加のリクエストは、期限が切れるか承認されるまで無視されます。 ### 送信者を承認する ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list telegram openclaw pairing approve telegram ``` サポートされているチャネル: `telegram`、`whatsapp`、`signal`、`imessage`、`discord`、`slack`、`feishu`。 ### ステータスの保存場所 `~/.openclaw/credentials/` に保存されます: * 保留中のリクエスト: `-pairing.json` * 承認された許可リスト ストア: * デフォルトのアカウント: `-allowFrom.json` * デフォルト以外のアカウント: `--allowFrom.json` アカウントのスコープ動作: * デフォルト以外のアカウントは、スコープ指定された許可リスト ファイルのみを読み取り/書き込みします。 * デフォルト アカウントは、チャネル スコープの（スコープ指定されていない）許可リスト ファイルを使用します。 これらは機密情報として扱ってください（アシスタントへのアクセスを制限するものです）。 ## 2) ノードデバイスのペアリング (iOS/Android/macOS/ヘッドレスノード) ノードは、`role: node` として **デバイス** 形式でゲートウェイに接続します。ゲートウェイは、承認が必要なデバイス ペアリング要求を作成します。 ### Telegram 経由でペアリング (iOS の場合推奨) `device-pair` プラグインを使用すると、初回のデバイス ペアリングをすべて Telegram から行うことができます。 1. Telegram で、ボットにメッセージを送信します: `/pair` 2. ボットは 2 つのメッセージで応答します。1 つは指示メッセージ、もう 1 つは個別の **セットアップ コード** メッセージ (Telegram で簡単にコピー/ペーストできます) です。 3. スマートフォンで、OpenClaw iOS アプリを開き、\[Settings] → \[Gateway] を選択します。 4. セットアップコードを貼り付けて接続します。 5. Telegram に戻り、`/pair approve` を送信します。 セットアップ コードは base64 でエンコードされた JSON ペイロードで、以下が含まれます。 * `url`: ゲートウェイの WebSocket URL (`ws://...` または `wss://...`) * `token`: 有効期間の短いペアリング トークン セットアップ コードは、有効な間はパスワードのように扱ってください。 ### ノードデバイスを承認する ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw devices list openclaw devices approve openclaw devices reject ``` ### ノードペアリング状態のストレージ `~/.openclaw/devices/` に保存されます: * `pending.json` (短命なリクエスト。保留中のリクエストは期限切れになります) * `paired.json` (ペアリング済みデバイス + トークン) ### 注記 * 従来の `node.pair.*` API (CLI: `openclaw nodes pending/approve`) は、ゲートウェイが所有する別のペアリング ストアです。WS ノードでは引き続きデバイスのペアリングが必要です。 ## 関連ドキュメント * セキュリティ モデル + プロンプト インジェクション: [セキュリティ](/gateway/security) * 安全に更新 (openclaw doctor を実行): [更新](/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) # Signal Source: https://openclawdoc.org/channels/signal signal-cli 経由で Signal を OpenClaw に接続する設定ガイドです。JSON-RPC + SSE 構成、番号モデル、前提条件を確認できます。 ステータス: 外部 CLI 連携。ゲートウェイは HTTP JSON-RPC + SSE 経由で `signal-cli` と通信します。 ## 前提条件 * OpenClaw がサーバーにインストールされていること (以下の Linux フローは Ubuntu 24 でテスト済み)。 * ゲートウェイが実行されているホストで `signal-cli` が利用可能であること。 * SMS 登録を行う場合は、認証 SMS を受信できる電話番号。 * 登録時の Signal キャプチャ (`signalcaptchas.org`) のためのブラウザアクセス。 ## クイックセットアップ (初心者向け) 1. ボット用には **個別の Signal 番号** を用意することを推奨します。 2. `signal-cli` をインストールします (JVM ビルドを使用する場合は Java が必要です)。 3. 以下のいずれかのセットアップ方法を選択します: * **方法 A (QR コード連携):** `signal-cli link -n "OpenClaw"` を実行し、既存の Signal アプリで QR コードをスキャンします。 * **方法 B (SMS 登録):** キャプチャと SMS 認証を使用して、専用の番号を登録します。 4. OpenClaw を設定し、ゲートウェイを再起動します。 5. 最初の DM を送信し、ペアリングを承認します (`openclaw pairing approve signal `)。 最小限の構成: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { signal: { enabled: true, account: "+15551234567", cliPath: "signal-cli", dmPolicy: "pairing", allowFrom: ["+15557654321"], }, }, } ``` フィールドリファレンス: | フィールド | 説明 | | :---------- | :---------------------------------------------------- | | `account` | E.164 形式のボット電話番号 (`+15551234567`) | | `cliPath` | `signal-cli` バイナリへのパス (`PATH` が通っている場合は `signal-cli`) | | `dmPolicy` | DM アクセスポリシー (`pairing` を推奨) | | `allowFrom` | DM を許可する電話番号または `uuid:` | ## Signal チャネルの概要 * `signal-cli` を介した Signal チャネルの提供 (組み込みの libsignal ではありません)。 * 確定的なルーティング: 返信は常にメッセージが届いたチャネルに戻ります。 * DM はエージェントのメインセッションを共有し、グループは個別に分離されます (`agent::signal:group:`)。 ## 構成の書き込み デフォルトでは、Signal チャネルにおいて `/config set|unset` コマンドによる構成の更新が許可されています (`commands.config: true` が必要)。 これを無効にするには以下のように設定します: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { signal: { configWrites: false } }, } ``` ## 番号モデルに関する重要な注意 * ゲートウェイは **Signal デバイス** (`signal-cli` アカウント) に接続します。 * **個人の Signal アカウント**でボットを実行した場合、ボットは自分自身のメッセージを無視します (ループ防止のため)。 * 「ユーザーがボットにメッセージを送り、ボットが返信する」という動作をさせるには、**別のボット用番号**を使用してください。 ## セットアップ方法 A: 既存の Signal アカウントと連携する (QR コード) 1. `signal-cli` (JVM またはネイティブビルド) をインストールします。 2. ボットアカウントをリンクします: * `signal-cli link -n "OpenClaw"` を実行し、Signal アプリで表示された QR コードをスキャンします。 3. Signal チャネルを構成し、ゲートウェイを起動します。 構成例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { signal: { enabled: true, account: "+15551234567", cliPath: "signal-cli", dmPolicy: "pairing", allowFrom: ["+15557654321"], }, }, } ``` マルチアカウントのサポート: `channels.signal.accounts` を使用して、アカウントごとの構成とオプションの `name` を指定できます。共通のパターンについては [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) を参照してください。 ## セットアップ方法 B: 専用のボット番号を登録する (SMS, Linux) 既存の Signal アカウントをリンクするのではなく、専用の番号を使用したい場合にこの方法を使用します。 1. SMS (または固定電話の場合は音声認証) を受信できる番号を取得します。 * アカウントやセッションの競合を避けるため、専用の番号を使用してください。 2. ゲートウェイホストに `signal-cli` をインストールします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 サーバーの API 変更により古いリリースが動作しなくなる可能性があるため、`signal-cli` は常に最新の状態に保ってください。 3. 番号を登録し、認証します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} signal-cli -a + register ``` キャプチャが必要な場合: 1. `https://signalcaptchas.org/registration/generate.html` を開きます。 2. キャプチャを完了し、「Open Signal」リンクから `signalcaptcha://...` で始まるトークンをコピーします。 3. 可能な限り、ブラウザセッションと同じ外部 IP から実行してください。 4. トークンの期限が短いため、すぐに以下のコマンドで登録を再試行してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} signal-cli -a + register --captcha '' signal-cli -a + verify ``` 4. OpenClaw を構成し、ゲートウェイを再起動してチャネルを確認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # ゲートウェイをユーザーの systemd サービスとして実行している場合: systemctl --user restart openclaw-gateway # その後、確認します: openclaw doctor openclaw channels status --probe ``` 5. 送信者をペアリングします: * ボットの番号にメッセージを送信します。 * サーバー側でコードを承認します: `openclaw pairing approve signal `。 * 「不明な連絡先」と表示されるのを避けるため、ボットの番号をスマートフォンの連絡先に保存してください。 重要: `signal-cli` で番号を登録すると、その番号を使用している他の Signal アプリのセッションが解除される場合があります。既存のアプリ設定を維持したい場合は、方法 A の QR コード連携を使用してください。 参考資料: * `signal-cli` README: `https://github.com/AsamK/signal-cli` * キャプチャフロー: `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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { signal: { httpUrl: "http://127.0.0.1:8080", autoStart: false, }, }, } ``` これにより、OpenClaw 内部での自動起動と待機がスキップされます。自動起動時に起動が遅い場合は、`channels.signal.startupTimeoutMs` を設定してください。 ## アクセス制御 (DM + グループ) DM: * デフォルト: `channels.signal.dmPolicy = "pairing"`。 * 未知の送信者にはペアリングコードが送信され、承認されるまでメッセージは無視されます（コードは 1 時間で期限切れになります）。 * 承認方法: * `openclaw pairing list signal` * `openclaw pairing approve signal ` * Signal の DM では、ペアリングが標準の認証フローとなります。詳細は [ペアリング](/channels/pairing) を参照してください。 * UUID のみの送信者 (`sourceUuid` 由来) は、`uuid:` として `channels.signal.allowFrom` に保存されます。 グループ: * `channels.signal.groupPolicy = open | allowlist | disabled`。 * `allowlist` モードでは、`channels.signal.groupAllowFrom` でボットをトリガーできるユーザーを制御します。 * 注意: `channels.signal` 構成が完全に欠落している場合、ランタイムはグループチェックのために `groupPolicy="allowlist"` にフォールバックします（`channels.defaults.groupPolicy` が設定されている場合でも）。 ## 仕組みと動作 * `signal-cli` はデーモンとして動作し、ゲートウェイは SSE を介してイベントを読み取ります。 * 受信メッセージは共通のチャネル形式に正規化されます。 * 返信は常に送信元の番号またはグループにルーティングされます。 ## メディアと制限事項 * 送信テキストは `channels.signal.textChunkLimit` (デフォルト 4000) ごとに分割されます。 * 段落単位の分割: `channels.signal.chunkMode="newline"` を設定すると、長さを基準に分割する前に空行（段落の境界）で分割を試みます。 * 添付ファイルをサポート (`signal-cli` から base64 で取得)。 * デフォルトのメディア制限: `channels.signal.mediaMaxMb` (デフォルト 8)。 * メディアのダウンロードをスキップするには `channels.signal.ignoreAttachments` を使用してください。 * グループ履歴のコンテキスト数は `channels.signal.historyLimit` (またはアカウントごとの設定) を使用し、未設定時は `messages.groupChat.historyLimit` にフォールバックします。`0` を設定すると無効になります (デフォルトは 50)。 ## タイピング中表示と既読確認 * **タイピングインジケーター**: OpenClaw は `signal-cli sendTyping` を介してタイピング信号を送信し、返信生成中に定期的に更新します。 * **既読確認**: `channels.signal.sendReadReceipts` が true の場合、許可された DM に対して既読確認を返します。 * Note: `signal-cli` はグループチャットの既読確認を公開していません。 ## リアクション (メッセージツール) * `channel=signal` を指定して `message action=react` を使用します。 * ターゲット: 送信者の E.164 番号または UUID（ペアリング出力の `uuid:` または生の UUID）。 * `messageId`: リアクション対象メッセージの Signal タイムスタンプ。 * グループチャットでのリアクションには `targetAuthor` または `targetAuthorUuid` が必要です。 例: ``` message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥 message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true message action=react channel=signal target=signal:group: targetAuthor=uuid: messageId=1737630212345 emoji=✅ ``` 構成: * `channels.signal.actions.reactions`: リアクション操作を有効/無効にします (デフォルト true)。 * `channels.signal.reactionLevel`: `off | ack | minimal | extensive`。 * `off`/`ack`: エージェントによるリアクションを無効にします (メッセージツールの `react` はエラーになります)。 * `minimal`/`extensive`: エージェントによるリアクションを有効にし、そのガイダンスレベルを設定します。 * アカウントごとのオーバーライド: `channels.signal.accounts..actions.reactions`, `channels.signal.accounts..reactionLevel`。 ## 配信ターゲット (CLI/Cron) * DM: `signal:+15551234567` (または生の E.164 番号)。 * UUID による DM: `uuid:` (または生の UUID)。 * グループ: `signal:group:`。 * ユーザー名: `username:` (お使いの Signal アカウントが対応している場合)。 ## トラブルシューティング まず以下のコマンドを順に確認してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` 必要に応じて、DM のペアリング状態を確認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list signal ``` よくある問題: * デーモンに到達できるが返信がない: アカウント/デーモンの設定 (`httpUrl`, `account`) と受信モードを確認してください。 * DM が無視される: 送信者が承認待ちの状態です。 * グループメッセージが無視される: 送信者制限またはメンション制限によって配信がブロックされています。 * 編集後の構成検証エラー: `openclaw doctor --fix` を実行してください。 * 診断結果に Signal が表示されない: `channels.signal.enabled: true` であることを確認してください。 追加のチェック: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 アカウントの状態をバックアップしてください。 * 明示的に広いアクセスを望む場合を除き、`channels.signal.dmPolicy: "pairing"` を維持してください。 * SMS 認証は登録や復旧の際にのみ必要ですが、番号やアカウントの制御を失うと再登録が困難になる場合があります。 ## 構成リファレンス (Signal) 完全な構成: [構成](/gateway/configuration) プロバイダーオプション: * `channels.signal.enabled`: チャネルの起動を有効/無効にします。 * `channels.signal.account`: ボットアカウントの E.164 番号。 * `channels.signal.cliPath`: `signal-cli` バイナリへのパス。 * `channels.signal.httpUrl`: デーモンの完全な URL (ホスト/ポートを上書き)。 * `channels.signal.httpHost`, `channels.signal.httpPort`: デーモンのバインドアドレス (デフォルト 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 許可リスト (E.164 または `uuid:`)。`open` の場合は `"*"` が必要です。Signal にはユーザー名がないため、電話番号または UUID を使用します。 * `channels.signal.groupPolicy`: `open | allowlist | disabled` (デフォルト: allowlist)。 * `channels.signal.groupAllowFrom`: グループ送信者の許可リスト。 * `channels.signal.historyLimit`: コンテキストに含めるグループメッセージの最大数 (0 で無効)。 * `channels.signal.dmHistoryLimit`: ユーザーのターン数による DM 履歴の制限。ユーザーごとのオーバーライド: `channels.signal.dms[""].historyLimit`。 * `channels.signal.textChunkLimit`: 送信テキストのチャンクサイズ (文字数)。 * `channels.signal.chunkMode`: `length` (デフォルト) または `newline` (段落境界で分割)。 * `channels.signal.mediaMaxMb`: 送受信メディアのサイズ上限 (MB)。 関連するグローバルオプション: * `agents.list[].groupChat.mentionPatterns` (Signal はネイティブのメンションをサポートしていません)。 * `messages.groupChat.mentionPatterns` (グローバルなフォールバック)。 * `messages.responsePrefix`。 # Slack Source: https://openclawdoc.org/channels/slack Slack アプリを OpenClaw に接続する設定と運用ガイドです。Socket Mode と HTTP Event API の違い、権限設定、ペアリングを確認できます。 ステータス: Slack アプリ連携を介した DM およびチャネルでの利用が可能です。デフォルトはソケットモード（Socket Mode）ですが、HTTP イベント API モードもサポートされています。 Slack の DM はデフォルトでペアリングモードになります。 ネイティブコマンドの動作とコマンドカタログ。 チャネルを横断した診断と修復の手順。 ## クイックセットアップ Slack アプリの設定で以下の操作を行います: * **Socket Mode** を有効にする。 * `connections:write` 権限を持つ **App Token** (`xapp-...`) を作成する。 * アプリをインストールし、**Bot Token** (`xoxb-...`) をコピーする。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { slack: { enabled: true, mode: "socket", appToken: "xapp-...", botToken: "xoxb-...", }, }, } ``` 環境変数によるフォールバック (デフォルトアカウントのみ): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} SLACK_APP_TOKEN=xapp-... SLACK_BOT_TOKEN=xoxb-... ``` 以下のボットイベントを購読（Subscribe）します: * `app_mention` * `message.channels`, `message.groups`, `message.im`, `message.mpim` * `reaction_added`, `reaction_removed` * `member_joined_channel`, `member_left_channel` * `channel_rename` * `pin_added`, `pin_removed` また、DM を利用するために App Home の **Messages Tab** を有効にしてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway ``` * モードを HTTP に設定 (`channels.slack.mode="http"`)。 * Slack の **Signing Secret** をコピーする。 * Event Subscriptions、Interactivity、および Slash command の Request URL をすべて同じ webhook パス（デフォルトは `/slack/events`）に設定する。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { slack: { enabled: true, mode: "http", botToken: "xoxb-...", signingSecret: "your-signing-secret", webhookPath: "/slack/events", }, }, } ``` アカウントごとの HTTP モードがサポートされています。 登録が衝突しないように、各アカウントに個別の `webhookPath` を割り当ててください。 ## トークンモデル * ソケットモードには `botToken` と `appToken` が必要です。 * HTTP モードには `botToken` と `signingSecret` が必要です。 * 構成ファイル内のトークンは、環境変数の値を上書きします。 * `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 環境変数は、デフォルトアカウントにのみ適用されます。 * `userToken` (`xoxp-...`) は構成ファイルでのみ指定可能（環境変数なし）で、デフォルトは読み取り専用 (`userTokenReadOnly: true`) です。 * オプション: 送信メッセージにアクティブなエージェントのアイデンティティ（カスタム `username` とアイコン）を使用したい場合は、`chat:write.customize` 権限を追加してください。`icon_emoji` は `:emoji_name:` 形式を使用します。 アクションやディレクトリの読み取りでは、設定されていればユーザートークンが優先されます。書き込みに関してはボットトークンが優先されます。ユーザートークンによる書き込みは、`userTokenReadOnly: false` であり、かつボットトークンが利用できない場合にのみ許可されます。 ## アクセス制御とルーティング `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 の許可リスト) マルチアカウント時の優先順位: * `channels.slack.accounts.default.allowFrom` は `default` アカウントにのみ適用されます。 * 名前付きアカウントは、自身の `allowFrom` が未設定の場合、`channels.slack.allowFrom` を継承します。 * 名前付きアカウントは `channels.slack.accounts.default.allowFrom` を継承しません。 DM でのペアリング承認には `openclaw pairing approve slack ` を使用します。 `channels.slack.groupPolicy` でチャネルの扱いを制御します: * `open` * `allowlist` * `disabled` チャネルの許可リストは `channels.slack.channels` で管理します。 注意: `channels.slack` 設定が完全に欠落している（環境変数のみのセットアップ）場合、ランタイムは `groupPolicy="allowlist"` にフォールバックし、警告をログに出力します（`channels.defaults.groupPolicy` が設定されていても同様です）。 名前/ID の解決: * トークン権限がある場合、チャネルおよび DM の許可リストのエントリは起動時に解決されます。 * 解決できなかったエントリは、設定されたままの形式で保持されます。 * インバウンドの認証一致は、デフォルトで ID が優先されます。ユーザー名やスラッグによる直接一致を有効にするには `channels.slack.dangerouslyAllowNameMatching: true` が必要です。 チャネルメッセージはデフォルトでメンション制約を受けます。 メンションの判定基準: * 明示的なアプリへのメンション (`<@botId>`) * メンション正規表現パターン (`agents.list[].groupChat.mentionPatterns`, フォールバックは `messages.groupChat.mentionPatterns`) * ボットへの返信スレッド内での暗黙的な動作 チャネルごとの制御 (`channels.slack.channels.`): * `requireMention` * `users` (許可リスト) * `allowBots` * `skills` * `systemPrompt` * `tools`, `toolsBySender` * `toolsBySender` のキー形式: `id:`, `e164:`, `username:`, `name:`, または `"*"` ワイルドカード （プレフィックスのない古いキーは引き続き `id:` のみとして扱われます） ## コマンドとスラッシュコマンドの動作 * Slack ではネイティブコマンドの自動モードは **オフ** です (`commands.native: "auto"` では Slack のネイティブコマンドは有効になりません)。 * Slack ネイティブのコマンドハンドラーを有効にするには `channels.slack.commands.native: true` (またはグローバルな `commands.native: true`) を設定してください。 * ネイティブコマンドを有効にした場合は、Slack 側で対応するスラッシュコマンド (`/` 名) を登録してください。ただし、以下の例外があります: * ステータスコマンドには `/agentstatus` を登録してください (Slack は `/status` を予約済みのため)。 * ネイティブコマンドが有効でない場合、`channels.slack.slashCommand` 経由で構成された単一のスラッシュコマンドを実行できます。 * ネイティブの引数メニューは、選択肢の数に応じてレンダリング戦略を自動調整します: * 5 つまで: ボタンブロック。 * 6〜100 個: 静的セレクトメニュー。 * 100 個超: インタラクティブオプションハンドラーが利用可能な場合、非同期フィルタリング付きの外部セレクト。 * エンコードされたオプション値が Slack の制限を超える場合はボタンにフォールバックします。 * 長いオプションペイロードの場合、スラッシュコマンド引数メニューは値を送信する前に確認ダイアログを表示します。 デフォルトのスラッシュコマンド設定: * `enabled: false` * `name: "openclaw"` * `sessionPrefix: "slack:slash"` * `ephemeral: true` スラッシュコマンドのセッションは分離されたキーを使用します: * `agent::slack:slash:` ただし、コマンドの実行自体はターゲットの会話セッション (`CommandTargetSessionKey`) に対してルーティングされます。 ## スレッド、セッション、および返信タグ * DM は `direct`、チャネルは `channel`、MPIM は `group` としてルーティングされます。 * デフォルトの `session.dmScope=main` 設定では、Slack の DM はエージェントのメインセッションに集約されます。 * チャネルセッション: `agent::slack:channel:`。 * スレッドへの返信は、適用可能な場合にスレッドセッションサフィックス (`:thread:`) を作成します。 * `channels.slack.thread.historyScope` のデフォルトは `thread` です。`thread.inheritParent` のデフォルトは `false` です。 * `channels.slack.thread.initialHistoryLimit` は、新しいスレッドセッション開始時に取得する既存メッセージの数を制御します（デフォルト `20`。`0` で無効）。 返信スレッドの制御: * `channels.slack.replyToMode`: `off|first|all` (デフォルト `off`) * `channels.slack.replyToModeByChatType`: `direct|group|channel` ごとに設定 * ダイレクトチャット用のレガシーフォールバック: `channels.slack.dm.replyToMode` 手動返信タグがサポートされています: * `[[reply_to_current]]` * `[[reply_to:]]` 注: `replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含め、Slack における **すべての** 返信スレッド化を無効にします。これは、`"off"` モードでも明示的なタグが尊重される Telegram とは異なります。この違いはプラットフォームのスレッドモデルを反映しています（Slack のスレッドはチャネルのメインフローからメッセージを隠しますが、Telegram の返信はメインフローに見えたままになります）。 ## メディア、チャンク化、配信 Slack の添付ファイルは、Slack がホストするプライベート URL（トークン認証されたリクエストフロー）からダウンロードされ、フェッチ成功時かつサイズ制限内であればメディアストアに書き込まれます。 インバウンドのサイズ上限はデフォルトで `20MB` です（`channels.slack.mediaMaxMb` で上書き可能）。 * テキストチャンクは `channels.slack.textChunkLimit` (デフォルト 4000) を使用します。 * `channels.slack.chunkMode="newline"` を設定すると段落優先の分割が有効になります。 * ファイル送信は Slack のアップロード API を使用し、スレッド返信 (`thread_ts`) を含めることができます。 * 送信メディアの上限は `channels.slack.mediaMaxMb` に従います（設定されている場合）。未設定時はメディアパイプラインの MIME タイプごとのデフォルトが使用されます。 推奨される明示的なターゲット: * DM の場合: `user:` * チャネルの場合: `channel:` ユーザーターゲットに送信する場合、Slack の conversation API を介して DM が開かれます。 ## アクションとゲート (Action Gating) Slack のアクションは `channels.slack.actions.*` で制御されます。 現在の Slack ツールで利用可能なアクショングループ: | グループ名 | デフォルト | | :----------- | :---- | | `messages` | 有効 | | `reactions` | 有効 | | `pins` | 有効 | | `memberInfo` | 有効 | | `emojiList` | 有効 | ## イベントと運用の動作 * メッセージの編集、削除、スレッド放送（Thread broadcast）はシステムイベントにマップされます。 * リアクションの追加および削除イベントはシステムイベントにマップされます。 * メンバーの参加・脱退、チャネルの作成・名前変更、およびピンの追加・削除イベントはシステムイベントにマップされます。 * アシスタントのスレッドステータス更新（スレッド内の「入力中...」インジケーター用）は `assistant.threads.setStatus` を使用し、ボットスコープ `assistant:write` を必要とします。 * `configWrites` が有効な場合、`channel_id_changed` イベントによってチャネル構成キーが移行されることがあります。 * チャネルのトピックや目的（Purpose）のメタデータは信頼できないコンテキストとして扱われ、ルーティングコンテキストに注入される場合があります。 * ブロックアクションやモーダル操作は、豊富なペイロードフィールドを持つ構造化された `Slack interaction: ...` システムイベントを発行します: * ブロックアクション: 選択された値、ラベル、ピッカーの値、および `workflow_*` メタデータ。 * モーダルの `view_submission` および `view_closed` イベント: ルーティングされたチャネルメタデータとフォーム入力。 ## 確認リアクション (Ack reactions) `ackReaction` は、OpenClaw がメッセージを処理している間、確認用の絵文字を送信します。 解決順序: * `channels.slack.accounts..ackReaction` * `channels.slack.ackReaction` * `messages.ackReaction` * エージェントのアイデンティティ絵文字 (`agents.list[].identity.emoji`, なければ "👀") 注意点: * Slack ではショートコード（例: `"eyes"`) を指定してください。 * `""` を設定すると、そのアカウントまたはグローバルでリアクションを無効にできます。 ## タイピングリアクションのフォールバック `typingReaction` は、OpenClaw が返信を生成している間、受信メッセージに一時的なリアクションを追加し、完了後に削除します。これは、Slack ネイティブのアシスタントタイピングが利用できない場合（特に DM など）に有用なフォールバックです。 解決順序: * `channels.slack.accounts..typingReaction` * `channels.slack.typingReaction` 注意点: * Slack ではショートコード（例: `"hourglass_flowing_sand"`) を指定してください。 * このリアクションはベストエフォートであり、返信の完了時または失敗時に自動的に削除が試みられます。 ## マニフェストとスコープのチェックリスト ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "display_information": { "name": "OpenClaw", "description": "Slack connector for OpenClaw" }, "features": { "bot_user": { "display_name": "OpenClaw", "always_online": false }, "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": [ "chat:write", "channels:history", "channels:read", "groups:history", "im:history", "im:read", "im:write", "mpim:history", "mpim:read", "mpim:write", "users:read", "app_mentions:read", "assistant:write", "reactions:read", "reactions:write", "pins:read", "pins:write", "emoji:read", "commands", "files:read", "files:write" ] } }, "settings": { "socket_mode_enabled": true, "event_subscriptions": { "bot_events": [ "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" ] } } } ``` `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 の検索結果を読み取る必要がある場合) ## トラブルシューティング 以下の項目を順番に確認してください: * `groupPolicy` * チャネルの許可リスト (`channels.slack.channels`) * `requireMention` * チャネルごとの `users` 許可リスト 便利なコマンド: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels status --probe openclaw logs --follow openclaw doctor ``` 以下の項目を確認してください: * `channels.slack.dm.enabled` * `channels.slack.dmPolicy` (または旧キー `channels.slack.dm.policy`) * ペアリングの承認状態、または許可リストのエントリ ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list slack ``` Slack アプリ設定で Bot トークンと App トークンが正しいか、また Socket Mode が有効になっているかを確認してください。 以下を確認してください: * Signing Secret * webhook パス * Slack の Request URL (Events, Interactivity, Slash Commands) * 各 HTTP アカウントごとに一意の `webhookPath` が設定されているか 意図したモードが正しく設定されているか確認してください: * ネイティブコマンドモード (`channels.slack.commands.native: true`) で、Slack 側に一致するスラッシュコマンドが登録されているか。 * または、単一スラッシュコマンドモード (`channels.slack.slashCommand.enabled: true`)。 また、`commands.useAccessGroups` やチャネル/ユーザーの許可リストも確認してください。 ## テキストストリーミング OpenClaw は、Agents and AI Apps API を介した Slack ネイティブのテキストストリーミングをサポートしています。 `channels.slack.streaming` でライブプレビューの動作を制御します: * `off`: ライブプレビューのストリーミングを無効にします。 * `partial` (デフォルト): プレビューテキストを最新の部分出力で置き換えます。 * `block`: チャンク化されたプレビュー更新を追記します。 * `progress`: 生成中に進行状況ステータステキストを表示し、最後に最終テキストを送信します。 `channels.slack.nativeStreaming` は、`streaming` が `partial` の場合に Slack ネイティブのストリーミング API (`chat.startStream` / `chat.appendStream` / `chat.stopStream`) を使用するかどうかを制御します (デフォルト: `true`)。 ネイティブストリーミングを無効にする（ドラフトプレビュー動作を維持する）場合: ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} channels: slack: streaming: partial nativeStreaming: false ``` レガシーなキー: * `channels.slack.streamMode` (`replace | status_final | append`) は `channels.slack.streaming` に自動移行されます。 * ブール値の `channels.slack.streaming` は `channels.slack.nativeStreaming` に自動移行されます。 ### 要件 1. Slack アプリ設定で **Agents and AI Apps** を有効にする。 2. アプリに `assistant:write` スコープが付与されていること。 3. そのメッセージに対して返信スレッドが利用可能であること（スレッドの選択は `replyToMode` に従います）。 ### 動作 * 最初のテキストチャンクでストリームが開始されます (`chat.startStream`)。 * 以降のテキストチャンクは同じストリームに追加されます (`chat.appendStream`)。 * 返信の終了時にストリームが完了します (`chat.stopStream`)。 * メディアやテキスト以外のペイロードは、通常の配信方法にフォールバックします。 * 返信の途中でストリーミングが失敗した場合、残りのペイロードは通常の配信方法で送信されます。 ## 構成リファレンスのポインタ 主要なリファレンス: * [構成リファレンス - 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` ## 関連ドキュメント * [ペアリング](/channels/pairing) * [チャネルルーティング](/channels/channel-routing) * [トラブルシューティング](/channels/troubleshooting) * [構成](/gateway/configuration) * [スラッシュコマンド](/tools/slash-commands) # Synology Chat Source: https://openclawdoc.org/channels/synology-chat Synology Chat webhook を使って OpenClaw を接続する設定ガイドです。送受信 webhook の役割、プラグイン構成、返信フローを確認できます。 ステータス: Synology Chat webhook を使用したダイレクトメッセージチャネルとして、プラグイン経由でサポートされています。 このプラグインは、Synology Chat の送信（Outgoing）webhook からのインバウンドメッセージを受け取り、Synology Chat の受信（Incoming）webhook を介して返信を送信します。 ## プラグインが必要 Synology Chat はプラグインベースであり、デフォルトのコアチャネルには含まれていません。 ローカルチェックアウトからインストールする場合: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/synology-chat ``` 詳細: [プラグイン](/tools/plugin) ## クイックセットアップ 1. Synology Chat プラグインをインストールして有効にします。 2. Synology Chat の「統合」設定で以下の操作を行います: * **受信（Incoming）webhook** を作成し、その URL をコピーします。 * **送信（Outgoing）webhook** を作成し、トークンをコピーします。 3. 送信 webhook の URL を OpenClaw ゲートウェイに向けます: * デフォルト: `https://gateway-host/webhook/synology` * または、カスタム設定した `channels.synology-chat.webhookPath`。 4. OpenClaw の `channels.synology-chat` セクションを構成します。 5. ゲートウェイを再起動し、Synology Chat ボットにメッセージを送信します。 最小限の構成: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 をブロックします。 * ペアリング承認は以下のコマンドで操作できます: * `openclaw pairing list synology-chat` * `openclaw pairing approve synology-chat ` ## アウトバウンド配信 数値形式の Synology Chat ユーザー ID をターゲットとして使用します。 例: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw message send --channel synology-chat --target 123456 --text "OpenClaw からのメッセージです" openclaw message send --channel synology-chat --target synology-chat:123456 --text "再送テスト" ``` メディア送信は、URL ベースのファイル配信としてサポートされています。 ## マルチアカウント `channels.synology-chat.accounts` 配下で、複数の Synology Chat アカウントを運用できます。 各アカウントでトークン、受信 URL、webhook パス、DM ポリシー、制限値を上書き可能です。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 リクエストはトークンで検証され、送信者ごとにレート制限が適用されます。 * 本番環境では `dmPolicy: "allowlist"` の使用を推奨します。 # Telegram Source: https://openclawdoc.org/channels/telegram Telegram ボットを OpenClaw に接続する設定と運用ガイドです。BotFather での準備、ロングポーリング / Webhook、ペアリングを確認できます。 ステータス: grammY を介したボット DM + グループの運用準備が整っています。ロングポーリングがデフォルトのモードです。 Webhook モードはオプションです。 Telegram のデフォルトの DM ポリシーはペアリングです。 クロスチャネル診断と修復プレイブック。 完全なチャネル構成パターンと例。 ## クイックセットアップ Telegram を開いて **@BotFather** とチャットします (ハンドルが正確に `@BotFather` であることを確認してください)。 `/newbot` を実行し、プロンプトに従い、トークンを保存します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` 環境フォールバック: `TELEGRAM_BOT_TOKEN=...` (デフォルト アカウントのみ)。 Telegram は `openclaw channels login telegram` を**使用しません**。 config/env でトークンを構成し、ゲートウェイを開始します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram ``` ペアリング コードは 1 時間後に期限切れになります。 ボットをグループに追加し、アクセス モデルに一致するように `channels.telegram.groups` と `groupPolicy` を設定します。 トークン解決順序はアカウントに応じて決まります。実際には、構成値は環境フォールバックよりも優先され、`TELEGRAM_BOT_TOKEN` はデフォルトのアカウントにのみ適用されます。 ## Telegram側の設定 Telegram ボットはデフォルトで **プライバシー モード** になっており、受信するグループ メッセージが制限されます。 ボットがすべてのグループ メッセージを参照する必要がある場合は、次のいずれかを実行します。 * `/setprivacy` 経由でプライバシー モードを無効にする、または * ボットをグループ管理者にします。 プライバシー モードを切り替えるときは、各グループのボットを削除して再追加し、Telegram が変更を適用できるようにします。 管理ステータスは Telegram グループ設定で制御されます。 管理ボットはすべてのグループ メッセージを受信するため、常時接続のグループ動作に役立ちます。 * `/setjoingroups` グループの追加を許可/拒否します * `/setprivacy` グループの可視性動作用 ## アクセス制御とアクティベーション `channels.telegram.dmPolicy` はダイレクト メッセージ アクセスを制御します。 * `pairing` (デフォルト) * `allowlist` (`allowFrom` には少なくとも 1 つの送信者 ID が必要です) * `open` (`"*"` を含めるには `allowFrom` が必要です) * `disabled``channels.telegram.allowFrom` は、数値の Telegram ユーザー ID を受け入れます。 `telegram:` / `tg:` プレフィックスは受け入れられ、正規化されます。 `dmPolicy: "allowlist"` と空の `allowFrom` はすべての DM をブロックし、構成検証によって拒否されます。 オンボーディング ウィザードは `@username` 入力を受け入れ、それを数値 ID に解決します。 アップグレードしていて、構成に `@username` 許可リスト エントリが含まれている場合は、`openclaw doctor --fix` を実行してそれらを解決します (ベストエフォート。Telegram ボット トークンが必要です)。 以前にペアリング ストア ホワイトリスト ファイルに依存していた場合、`openclaw doctor --fix` はホワイトリスト フロー内の `channels.telegram.allowFrom` へのエントリを回復できます (たとえば、`dmPolicy: "allowlist"` にまだ明示的な ID がない場合)。 単一所有者ボットの場合は、(以前のペアリングの承認に依存するのではなく) アクセス ポリシーを構成内で永続的に保つために、明示的な数値 `allowFrom` ID を持つ `dmPolicy: "allowlist"` を優先します。 ### Telegram ユーザー ID を見つける より安全 (サードパーティのボットなし): 1. ボットに DM を送ります。 2. `openclaw logs --follow` を実行します。 3. `from.id` を読みます。 公式ボット API メソッド: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl "https://api.telegram.org/bot/getUpdates" ``` サードパーティの方法 (非公開): `@userinfobot` または `@getidsbot`。 2 つのコントロールが一緒に適用されます。1. **許可されるグループ** (`channels.telegram.groups`) * `groups` 構成がありません: * `groupPolicy: "open"` の場合: どのグループもグループ ID チェックに合格できます * `groupPolicy: "allowlist"` の場合 (デフォルト): `groups` エントリ (または `"*"`) を追加するまで、グループはブロックされます。 * `groups` 構成済み: 許可リストとして機能します (明示的な ID または `"*"`) 2. **グループ内で許可される送信者** (`channels.telegram.groupPolicy`) * `open` * `allowlist` (デフォルト) * `disabled` `groupAllowFrom` は、グループ送信者のフィルタリングに使用されます。設定されていない場合、Telegram は `allowFrom` に戻ります。 `groupAllowFrom` エントリは、数値の Telegram ユーザー ID である必要があります (`telegram:` / `tg:` プレフィックスは正規化されます)。 数値以外のエントリは送信者の認証では無視されます。 セキュリティ境界 (`2026.2.25+`): グループ送信者の認証は、DM ペアリングとストアの承認を**継承しません**。 ペアリングはDMのみのままです。グループの場合は、`groupAllowFrom` またはグループごと/トピックごとに `allowFrom` を設定します。 ランタイムに関する注意: `channels.telegram` が完全に欠落している場合、`channels.defaults.groupPolicy` が明示的に設定されていない限り、ランタイムはデフォルトでフェールクローズされた `groupPolicy="allowlist"` になります。 例: 1 つの特定のグループ内の任意のメンバーを許可します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { groups: { "-1001234567890": { groupPolicy: "open", requireMention: false, }, }, }, }, } ``` グループ返信にはデフォルトでメンションが必要です。 言及は次のとおりです。- ネイティブ `@botusername` の言及、または * パターンについての言及: * `agents.list[].groupChat.mentionPatterns` * `messages.groupChat.mentionPatterns` セッションレベルのコマンドの切り替え： * `/activation always` * `/activation mention` これらはセッション状態のみを更新します。永続化のために config を使用します。 永続的な構成の例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { groups: { "*": { requireMention: false }, }, }, }, } ``` グループチャットIDの取得： * グループメッセージを `@userinfobot` / `@getidsbot` に転送します * または `openclaw logs --follow` から `chat.id` を読み取ります * またはボット API `getUpdates` を検査します ## 実行時の動作 * テレグラムはゲートウェイプロセスによって所有されます。 * ルーティングは決定的です: Telegram の受信応答は Telegram に返されます (モデルはチャネルを選択しません)。 * 受信メッセージは、返信メタデータとメディア プレースホルダーを使用して共有チャネル エンベロープに正規化されます。 * グループセッションはグループIDによって分離されます。トピックを分離するために、フォーラムのトピックには `:topic:` が追加されます。 * DM メッセージには `message_thread_id` を含めることができます。 OpenClaw は、スレッド対応のセッション キーを使用してそれらをルーティングし、応答用のスレッド ID を保存します。 * ロングポーリングでは、チャットごと/スレッドごとのシーケンスを持つ grammY ランナーを使用します。全体的なランナー シンクの同時実行性は `agents.defaults.maxConcurrent` を使用します。 * Telegram Bot API には読み取り受信サポートがありません (`sendReadReceipts` は適用されません)。 ## 機能リファレンス OpenClaw は部分的な応答をリアルタイムでストリーミングできます。- ダイレクト チャット: プレビュー メッセージ + `editMessageText` * グループ/トピック: プレビュー メッセージ + `editMessageText` 要件: * `channels.telegram.streaming` は `off | partial | block | progress` (デフォルト: `partial`) * `progress` は Telegram の `partial` にマップされます (クロスチャネル命名と互換) * 従来の `channels.telegram.streamMode` およびブール値 `streaming` 値は自動マッピングされます テキストのみの返信の場合: * DM: OpenClaw は同じプレビュー メッセージを保持し、その場で最終編集を実行します (2 番目のメッセージはありません) * グループ/トピック: OpenClaw は同じプレビュー メッセージを保持し、その場で最終編集を実行します (2 番目のメッセージはありません)。 複雑な応答 (メディア ペイロードなど) の場合、OpenClaw は通常の最終配信に戻り、プレビュー メッセージをクリーンアップします。 プレビュー ストリーミングはブロック ストリーミングとは別のものです。 Telegram に対してブロック ストリーミングが明示的に有効になっている場合、OpenClaw は二重ストリーミングを避けるためにプレビュー ストリームをスキップします。 ネイティブ ドラフト トランスポートが利用できないか拒否された場合、OpenClaw は自動的に `sendMessage` + `editMessageText` にフォールバックします。 テレグラムのみの推論ストリーム: * `/reasoning stream` は生成中に推論をライブ プレビューに送信します * 最終回答は推論テキストなしで送信されます 送信テキストには Telegram `parse_mode: "HTML"` が使用されます。- Markdown 風のテキストは Telegram セーフな HTML にレンダリングされます。 * 生のモデル HTML は、Telegram の解析エラーを減らすためにエスケープされます。 * Telegram が解析された HTML を拒否した場合、OpenClaw はプレーン テキストとして再試行します。 リンク プレビューはデフォルトで有効になっており、`channels.telegram.linkPreview: false` で無効にできます。 Telegram コマンド メニューの登録は、起動時に `setMyCommands` で処理されます。 ネイティブ コマンドのデフォルト: * `commands.native: "auto"` は Telegram のネイティブ コマンドを有効にします カスタム コマンド メニュー エントリを追加します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { customCommands: [ { command: "backup", description: "Git backup" }, { command: "generate", description: "Create an image" }, ], }, }, } ``` ルール: * 名前は正規化されます (先頭の `/` を削除し、小文字にします) * 有効なパターン: `a-z`、`0-9`、`_`、長さ `1..32` * カスタム コマンドはネイティブ コマンドをオーバーライドできません * 競合/重複はスキップされ、ログに記録されます 注: * カスタム コマンドはメニュー エントリのみです。動作を自動実装しない * プラグイン/スキルコマンドは、テレグラムメニューに表示されていなくても、入力すると機能します ネイティブ コマンドが無効になっている場合、組み込みは削除されます。カスタム/プラグイン コマンドが設定されている場合は、引き続き登録される可能性があります。 よくあるセットアップの失敗: * `setMyCommands failed` は通常、`api.telegram.org` へのアウトバウンド DNS/HTTPS がブロックされていることを意味します。 ### デバイス ペアリング コマンド (`device-pair` プラグイン) `device-pair` プラグインがインストールされている場合:1. `/pair` はセットアップ コードを生成します 2\. iOS アプリにコードを貼り付けます 3\. `/pair approve` が最新の保留中のリクエストを承認します 詳細: [ペアリング](/channels/pairing#pair-via-telegram-recommended-for-ios)。 インライン キーボード スコープを構成します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { capabilities: { inlineButtons: "allowlist", }, }, }, } ``` アカウントごとの上書き: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { accounts: { main: { capabilities: { inlineButtons: "allowlist", }, }, }, }, }, } ``` 範囲: * `off` * `dm` * `group` * `all` * `allowlist` (デフォルト) レガシー `capabilities: ["inlineButtons"]` は `inlineButtons: "all"` にマップされます。 メッセージアクションの例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { action: "send", channel: "telegram", to: "123456789", message: "Choose an option:", buttons: [ [ { text: "Yes", callback_data: "yes" }, { text: "No", callback_data: "no" }, ], [{ text: "Cancel", callback_data: "cancel" }], ], } ``` コールバックのクリックはテキストとしてエージェントに渡されます。 `callback_data: ` Telegram ツールのアクションには次のものが含まれます。 * `sendMessage` (`to`、`content`、オプションの `mediaUrl`、`replyToMessageId`、`messageThreadId`) * `react` (`chatId`、`messageId`、`emoji`) * `deleteMessage` (`chatId`、`messageId`) * `editMessage` (`chatId`、`messageId`、`content`) * `createForumTopic` (`chatId`、`name`、オプションの `iconColor`、`iconCustomEmojiId`) チャネル メッセージ アクションは、人間工学に基づいたエイリアス (`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`) を公開します。 ゲート制御:- `channels.telegram.actions.sendMessage` * `channels.telegram.actions.deleteMessage` * `channels.telegram.actions.reactions` * `channels.telegram.actions.sticker` (デフォルト: 無効) 注: `edit` と `topic-create` は現在デフォルトで有効になっており、個別の `channels.telegram.actions.*` 切り替えはありません。 リアクション削除セマンティクス: [/tools/reactions](/tools/reactions) Telegram は、生成された出力で明示的な応答スレッド タグをサポートしています。 * `[[reply_to_current]]` はトリガーメッセージに応答します * `[[reply_to:]]` は特定の Telegram メッセージ ID に応答します `channels.telegram.replyToMode` は次の処理を制御します。 * `off` (デフォルト) * `first` * `all` 注: `off` は、暗黙的な応答スレッドを無効にします。明示的な `[[reply_to_*]]` タグは引き続き受け入れられます。 フォーラムのスーパーグループ: * トピック セッション キーは `:topic:` を追加します * 返信と入力はトピックのスレッドをターゲットにします * トピック構成パス: `channels.telegram.groups..topics.` 一般トピック (`threadId=1`) 特殊ケース: * メッセージは `message_thread_id` を省略して送信されます (テレグラムは `sendMessage(...thread_id=1)` を拒否します) * 入力アクションには引き続き `message_thread_id` が含まれますトピックの継承: トピック エントリは、オーバーライドされない限り、グループ設定を継承します (`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`)。 `agentId` はトピックのみであり、グループのデフォルトを継承しません。 **トピックごとのエージェント ルーティング**: トピック構成で `agentId` を設定することで、各トピックを異なるエージェントにルーティングできます。これにより、各トピックに独自の分離されたワークスペース、メモリ、セッションが与えられます。例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { groups: { "-1001234567890": { topics: { "1": { agentId: "main" }, // General topic → main agent "3": { agentId: "zu" }, // Dev topic → zu agent "5": { agentId: "coder" } // Code review → coder agent } } } } } } ``` 各トピックには独自のセッション キーがあります: `agent:zu:telegram:group:-1001234567890:topic:3` **永続的な ACP トピック バインディング**: フォーラム トピックは、トップレベルの型付き ACP バインディングを通じて ACP ハーネス セッションを固定できます。 * `bindings[]` と `type: "acp"` および `match.channel: "telegram"` 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "codex", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/workspace/openclaw", }, }, }, ], }, bindings: [ { type: "acp", agentId: "codex", match: { channel: "telegram", accountId: "default", peer: { kind: "group", id: "-1001234567890:topic:42" }, }, }, ], channels: { telegram: { groups: { "-1001234567890": { topics: { "42": { requireMention: false, }, }, }, }, }, }, } ``` 現在、これはグループおよびスーパーグループのフォーラム トピックに限定されています。 **スレッドバインドされた ACP がチャットから生成**: * `/acp spawn --thread here|auto` は、現在の Telegram トピックを新しい ACP セッションにバインドできます。 * フォローアップ トピック メッセージは、バインドされた ACP セッションに直接ルーティングされます (`/acp steer` は必要ありません)。 * OpenClaw は、バインドが成功した後、トピック内に生成確認メッセージを固定します。 * `channels.telegram.threadBindings.spawnAcpSessions=true` が必要です。 テンプレートのコンテキストには次のものが含まれます。 * `MessageThreadId` * `IsForum` DM スレッドの動作:- `message_thread_id` とのプライベート チャットは DM ルーティングを維持しますが、スレッド対応のセッション キー/返信ターゲットを使用します。 ### 音声メッセージ Telegram は音声メモと音声ファイルを区別します。 * デフォルト: オーディオファイルの動作 * エージェントの応答に `[[audio_as_voice]]` タグを付けて、ボイスメモの送信を強制します メッセージアクションの例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/voice.ogg", asVoice: true, } ``` ### ビデオメッセージ Telegram はビデオ ファイルとビデオ メモを区別します。 メッセージアクションの例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/video.mp4", asVideoNote: true, } ``` ビデオノートはキャプションをサポートしていません。指定されたメッセージ テキストは別個に送信されます。 ### ステッカー インバウンドステッカーの処理: * 静的 WEBP: ダウンロードおよび処理済み (プレースホルダー ``) * アニメーション TGS: スキップされました * ビデオ WEBM: スキップされました ステッカーコンテキストフィールド: * `Sticker.emoji` * `Sticker.setName` * `Sticker.fileId` * `Sticker.fileUniqueId` * `Sticker.cachedDescription` ステッカーキャッシュファイル: * `~/.openclaw/telegram/sticker-cache.json` ステッカーは (可能な場合) 1 回記述され、ビジョン呼び出しの繰り返しを減らすためにキャッシュされます。 ステッカーアクションを有効にします。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { actions: { sticker: true, }, }, }, } ``` ステッカーを送信するアクション: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { action: "sticker", channel: "telegram", to: "123456789", fileId: "CAACAgIAAxkBAAI...", } ``` キャッシュされたステッカーを検索: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { action: "sticker-search", channel: "telegram", query: "cat waving", limit: 5, } ``` Telegram の反応は、`message_reaction` 更新として (メッセージ ペイロードとは別に) 到着します。 有効にすると、OpenClaw は次のようなシステム イベントをキューに入れます。- `Telegram reaction added: 👍 by Alice (@alice) on msg 42` 構成: * `channels.telegram.reactionNotifications`: `off | own | all` (デフォルト: `own`) * `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (デフォルト: `minimal`) 注: * `own` は、ボット送信メッセージのみに対するユーザーの反応を意味します (送信メッセージ キャッシュによるベストエフォート)。 * リアクション イベントは依然として Telegram のアクセス制御を尊重します (`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`)。不正な送信者はドロップされます。 * Telegram はリアクション更新でスレッド ID を提供しません。 * 非フォーラムグループはグループチャットセッションにルーティングされます * フォーラム グループは、正確な元のトピックではなく、グループの一般トピック セッション (`:topic:1`) にルーティングされます。 ポーリング/Webhook の `allowed_updates` には、`message_reaction` が自動的に含まれます。 `ackReaction` は、OpenClaw が受信メッセージを処理している間に、確認の絵文字を送信します。 解決順序: * `channels.telegram.accounts..ackReaction` * `channels.telegram.ackReaction` * `messages.ackReaction` * エージェント ID 絵文字フォールバック (`agents.list[].identity.emoji`、それ以外の場合は「👀」) 注: * Telegram は Unicode 絵文字 (「👀」など) を想定しています。 * `""` を使用して、チャネルまたはアカウントの反応を無効にします。 チャネル構成の書き込みはデフォルトで有効になっています (`configWrites !== false`)。 Telegram によってトリガーされる書き込みには次のものが含まれます。- `channels.telegram.groups` を更新するグループ移行イベント (`migrate_to_chat_id`) * `/config set` および `/config unset` (コマンドの有効化が必要) 無効にする: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { configWrites: false, }, }, } ``` デフォルト: ロングポーリング。 Webhook モード: * `channels.telegram.webhookUrl` を設定します * set `channels.telegram.webhookSecret` (Webhook URL を設定する場合に必要) * オプションの `channels.telegram.webhookPath` (デフォルトは `/telegram-webhook`) * オプションの `channels.telegram.webhookHost` (デフォルトは `127.0.0.1`) * オプションの `channels.telegram.webhookPort` (デフォルトは `8787`) Webhook モードのデフォルトのローカル リスナーは `127.0.0.1:8787` にバインドされます。 パブリック エンドポイントが異なる場合は、リバース プロキシを前面に配置し、`webhookUrl` をパブリック URL に指定します。 意図的に外部イングレスが必要な場合は、`webhookHost` (例: `0.0.0.0`) を設定します。 * `channels.telegram.textChunkLimit` のデフォルトは 4000 です。 * `channels.telegram.chunkMode="newline"` は、長さで分割する前に段落境界（空行）を優先します。 * `channels.telegram.mediaMaxMb`（デフォルト 100）は、受信および送信する Telegram メディアのサイズを制限します。 * `channels.telegram.timeoutSeconds` は Telegram API クライアントのタイムアウトを上書きします（未設定時は grammY の既定値が使われます）。 * グループ コンテキスト履歴は `channels.telegram.historyLimit` または `messages.groupChat.historyLimit`（デフォルト 50）を使います。`0` で無効になります。 * DM 履歴の制御項目: * `channels.telegram.dmHistoryLimit` * `channels.telegram.dms[""].historyLimit` * `channels.telegram.retry` 設定は、回復可能な送信 API エラーに対する Telegram 送信ヘルパー（CLI / ツール / アクション）へ適用されます。 CLI 送信ターゲットには、数値のチャット ID またはユーザー名を指定できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` Telegram の投票では `openclaw message poll` を使用し、フォーラム トピックもサポートします。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw message poll --channel telegram --target 123456789 \ --poll-question "Ship it?" --poll-option "Yes" --poll-option "No" openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \ --poll-duration-seconds 300 --poll-public ``` Telegram のみのポーリング フラグ: * `--poll-duration-seconds` (5-600) * `--poll-anonymous` * `--poll-public` * フォーラム トピックの場合は `--thread-id` (または `:topic:` ターゲットを使用) アクションゲート: * `channels.telegram.actions.sendMessage=false` は、投票を含むアウトバウンド Telegram メッセージを無効にします * `channels.telegram.actions.poll=false` は、定期的な送信を有効にしたまま、テレグラム投票の作成を無効にします ## トラブルシューティング * `requireMention=false` の場合、Telegram プライバシー モードでは完全な可視性を許可する必要があります。 * BotFather: `/setprivacy` -> 無効にする * その後、ボットを削除してグループに再度追加します * `openclaw channels status` は、構成で言及されていないグループ メッセージが予期される場合に警告します。 * `openclaw channels status --probe` は、明示的な数値グループ ID をチェックできます。ワイルドカード `"*"` はメンバーシップを調査できません。 * クイックセッションテスト: `/activation always`。 * `channels.telegram.groups` が存在する場合、グループをリストする必要があります (または `"*"` を含める) * グループ内のボットのメンバーシップを確認する * ログの確認: スキップ理由の `openclaw logs --follow` * 送信者の ID を認証します (ペアリングおよび/または数値 `allowFrom`) * グループ ポリシーが `open` の場合でも、コマンド認可は引き続き適用されます。 * `setMyCommands failed` は通常、`api.telegram.org` への DNS/HTTPS 到達可能性の問題を示します。 * ノード 22 以降 + カスタム フェッチ/プロキシは、AbortSignal タイプが一致しない場合に即時中止動作をトリガーできます。 * 一部のホストは、最初に `api.telegram.org` を IPv6 に解決します。壊れた IPv6 出力により、断続的な Telegram API エラーが発生する可能性があります。 * ログに `TypeError: fetch failed` または `Network request for 'getUpdates' failed!` が含まれている場合、OpenClaw はこれらを回復可能なネットワーク エラーとして再試行するようになりました。 * 不安定な直接出力/TLS を備えた VPS ホストでは、Telegram API 呼び出しを `channels.telegram.proxy` 経由でルーティングします。 ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} channels: telegram: proxy: socks5://:@proxy-host:1080 ``` * ノード 22+ のデフォルトは `autoSelectFamily=true` (WSL2 を除く) および `dnsResultOrder=ipv4first` です。 * ホストが WSL2 であるか、明示的に IPv4 のみの動作でより適切に動作する場合は、ファミリーの選択を強制します。 ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} channels: telegram: network: autoSelectFamily: false ``` * 環境の上書き (一時的): * `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` * `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` * `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` * DNS 応答を検証します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} dig +short api.telegram.org A dig +short api.telegram.org AAAA ``` その他のヘルプ: [チャネルのトラブルシューティング](/channels/troubleshooting)。 ## Telegram 構成参照ポインタ 主な参考文献:- `channels.telegram.enabled`: チャネルの起動を有効/無効にします。 * `channels.telegram.botToken`: ボット トークン (BotFather)。 * `channels.telegram.tokenFile`: ファイル パスからトークンを読み取ります。 * `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (デフォルト: ペアリング)。 * `channels.telegram.allowFrom`: DM 許可リスト (数値の Telegram ユーザー ID)。 `allowlist` には少なくとも 1 つの送信者 ID が必要です。 `open` には `"*"` が必要です。 `openclaw doctor --fix` は、レガシー `@username` エントリを ID に解決でき、ホワイトリスト移行フローのペアリング ストア ファイルからホワイトリスト エントリを回復できます。 * `channels.telegram.actions.poll`: Telegram 投票の作成を有効または無効にします (デフォルト: 有効。それでも `sendMessage` が必要です)。 * `channels.telegram.defaultTo`: 明示的な `--reply-to` が指定されていない場合に、CLI `--deliver` によって使用されるデフォルトの Telegram ターゲット。 * `channels.telegram.groupPolicy`: `open | allowlist | disabled` (デフォルト: ホワイトリスト)。 * `channels.telegram.groupAllowFrom`: グループ送信者の許可リスト (数値の Telegram ユーザー ID)。 `openclaw doctor --fix` は、従来の `@username` エントリを ID に解決できます。数値以外のエントリは認証時に無視されます。グループ認証では、DM ペアリングとストアのフォールバックは使用されません (`2026.2.25+`)。 * マルチアカウントの優先順位: * 2 つ以上のアカウント ID が設定されている場合は、`channels.telegram.defaultAccount` を設定 (または `channels.telegram.accounts.default` を含めて) デフォルトのルーティングを明示します。 * どちらも設定されていない場合、OpenClaw は最初の正規化されたアカウント ID にフォールバックし、`openclaw doctor` が警告します。- `channels.telegram.accounts.default.allowFrom` および `channels.telegram.accounts.default.groupAllowFrom` は、`default` アカウントにのみ適用されます。 * アカウントレベルの値が設定されていない場合、名前付きアカウントは `channels.telegram.allowFrom` および `channels.telegram.groupAllowFrom` を継承します。 * 名前付きアカウントは `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom` を継承しません。 * `channels.telegram.groups`: グループごとのデフォルト + ホワイトリスト (グローバルデフォルトには `"*"` を使用します)。 * `channels.telegram.groups..groupPolicy`: groupPolicy のグループごとの上書き (`open | allowlist | disabled`)。 * `channels.telegram.groups..requireMention`: ゲートのデフォルトについて言及。 * `channels.telegram.groups..skills`: スキル フィルター (省略 = すべてのスキル、空 = なし)。 * `channels.telegram.groups..allowFrom`: グループごとの送信者許可リストの上書き。 * `channels.telegram.groups..systemPrompt`: グループの追加のシステム プロンプト。 * `channels.telegram.groups..enabled`: `false` の場合はグループを無効にします。 * `channels.telegram.groups..topics..*`: トピックごとのオーバーライド (グループ フィールド + トピックのみ `agentId`)。 * `channels.telegram.groups..topics..agentId`: このトピックを特定のエージェントにルーティングします (グループ レベルおよびバインディング ルーティングをオーバーライドします)。 * `channels.telegram.groups..topics..groupPolicy`: groupPolicy のトピックごとのオーバーライド (`open | allowlist | disabled`)。 * `channels.telegram.groups..topics..requireMention`: トピックごとのメンション ゲートのオーバーライド。 * トップレベル `bindings[]` と `type: "acp"` および正規トピック ID `chatId:topic:topicId` (`match.peer.id`): 永続的な ACP トピック バインディング フィールド ([ACP エージェント](/tools/acp-agents#channel-specific-settings) を参照)。 * `channels.telegram.direct..topics..agentId`: DM トピックを特定のエージェントにルーティングします (フォーラム トピックと同じ動作)。 * `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (デフォルト: ホワイトリスト)。- `channels.telegram.accounts..capabilities.inlineButtons`: アカウントごとの上書き。 * `channels.telegram.commands.nativeSkills`: Telegram ネイティブ スキル コマンドを有効/無効にします。 * `channels.telegram.replyToMode`: `off | first | all` (デフォルト: `off`)。 * `channels.telegram.textChunkLimit`: 送信チャンク サイズ (文字数)。 * `channels.telegram.chunkMode`: `length` (デフォルト) または `newline` は、長さをチャンクする前に空白行 (段落境界) で分割します。 * `channels.telegram.linkPreview`: 送信メッセージのリンク プレビューを切り替えます (デフォルト: true)。 * `channels.telegram.streaming`: `off | partial | block | progress` (ライブ ストリーム プレビュー; デフォルト: `partial`; `progress` は `partial` にマップされます。 `block` は従来のプレビュー モードとの互換性です)。 Telegram プレビュー ストリーミングでは、その場で編集された単一のプレビュー メッセージが使用されます。 * `channels.telegram.mediaMaxMb`: インバウンド/アウトバウンド Telegram メディアの上限 (MB、デフォルト: 100)。 * `channels.telegram.retry`: 回復可能なアウトバウンド API エラー (試行、minDelayMs、maxDelayMs、ジッター) に対する Telegram 送信ヘルパー (CLI/ツール/アクション) の再試行ポリシー。 * `channels.telegram.network.autoSelectFamily`: ノード autoSelectFamily をオーバーライドします (true=有効、false=無効)。ノード 22 以降ではデフォルトで有効になり、WSL2 はデフォルトで無効になります。 * `channels.telegram.network.dnsResultOrder`: DNS 結果の順序を上書きします (`ipv4first` または `verbatim`)。ノード 22 以降のデフォルトは `ipv4first` です。 * `channels.telegram.proxy`: ボット API 呼び出しのプロキシ URL (SOCKS/HTTP)。 * `channels.telegram.webhookUrl`: Webhook モードを有効にします (`channels.telegram.webhookSecret` が必要)。- `channels.telegram.webhookSecret`: Webhook シークレット (WebhookUrl が設定されている場合に必要)。 * `channels.telegram.webhookPath`: ローカル Webhook パス (デフォルト `/telegram-webhook`)。 * `channels.telegram.webhookHost`: ローカル Webhook バインド ホスト (デフォルト `127.0.0.1`)。 * `channels.telegram.webhookPort`: ローカル Webhook バインド ポート (デフォルト `8787`)。 * `channels.telegram.actions.reactions`: ゲートTelegramツールの反応。 * `channels.telegram.actions.sendMessage`: ゲート テレグラム ツール メッセージの送信。 * `channels.telegram.actions.deleteMessage`: ゲート テレグラム ツール メッセージが削除されます。 * `channels.telegram.actions.sticker`: ゲート テレグラム ステッカー アクション — 送信および検索 (デフォルト: false)。 * `channels.telegram.reactionNotifications`: `off | own | all` — どの反応がシステム イベントをトリガーするかを制御します (設定されていない場合、デフォルト: `own`)。 * `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — 制御エージェントの反応能力 (設定されていない場合のデフォルト: `minimal`)。 * [設定リファレンス - Telegram](/gateway/configuration-reference#telegram) Telegram特有の高信号フィールド:- 起動/認証: `enabled`、`botToken`、`tokenFile`、`accounts.*` * アクセス制御: `dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、トップレベル `bindings[]` (`type: "acp"`) * コマンド/メニュー: `commands.native`、`commands.nativeSkills`、`customCommands` * スレッド化/返信: `replyToMode` * ストリーミング: `streaming` (プレビュー)、`blockStreaming` * フォーマット/配信: `textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix` * メディア/ネットワーク: `mediaMaxMb`、`timeoutSeconds`、`retry`、`network.autoSelectFamily`、`proxy` * Webhook: `webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` * アクション/機能: `capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker` * 反応: `reactionNotifications`、`reactionLevel` * 書き込み/履歴: `configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` ## 関連 * [ペアリング](/channels/pairing) * [チャンネルルーティング](/channels/channel-routing) * [マルチエージェントルーティング](/concepts/multi-agent) * [トラブルシューティング](/channels/troubleshooting) # Tlon Source: https://openclawdoc.org/channels/tlon Urbit 上の Tlon プラグインを OpenClaw に接続する設定ガイドです。DM・グループ対応、導入手順、現在の制約を確認できます。 Tlon は Urbit 上に構築された分散型メッセンジャーです。OpenClaw はお使いの Urbit ship に接続し、DM やグループチャットのメッセージに応答できます。グループでの返信には、デフォルトで @メンションが必要ですが、許可リストによってさらに制限することも可能です。 ステータス: プラグインによりサポートされています。DM、グループメンション、スレッドへの返信、リッチテキスト形式、および画像のアップロードがサポートされています。リアクションと投票はまだサポートされていません。 ## プラグインが必要 Tlon はプラグインとして提供されており、コアインストールには同梱されていません。 CLI (npm レジストリ) 経由でインストールします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/tlon ``` ローカルチェックアウト (git リポジトリから実行する場合): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/tlon ``` 詳細: [プラグイン](/tools/plugin) ## セットアップ 1. Tlon プラグインをインストールします。 2. ship の URL とログインコードを用意します。 3. `channels.tlon` を構成します。 4. ゲートウェイを再起動します。 5. ボットに DM を送信するか、グループチャネルでメンションします。 最小限の構成 (単一アカウント): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 保護を無効にします。 ## グループチャネル 自動検出はデフォルトで有効になっています。チャネルを手動で固定（Pin）することも可能です: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { tlon: { groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"], }, }, } ``` 自動検出を無効にするには: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { tlon: { autoDiscoverChannels: false, }, }, } ``` ## アクセス制御 DM 許可リスト (空の場合、DM は許可されません。承認フローには `ownerShip` を使用します): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { tlon: { dmAllowlist: ["~zod", "~nec"], }, }, } ``` グループ権限 (デフォルトで制限されています): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { tlon: { defaultAuthorizedShips: ["~zod"], authorization: { channelRules: { "chat/~host-ship/general": { mode: "restricted", allowedShips: ["~zod", "~nec"], }, "chat/~host-ship/announcements": { mode: "open", }, }, }, }, }, } ``` ## オーナーおよび承認システム 未承認のユーザーが対話を試みた際に承認リクエストを受け取るためのオーナー ship を設定します: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { tlon: { ownerShip: "~your-main-ship", }, }, } ``` オーナー ship は**どこでも自動的に承認されます**。DM の招待は自動的に承諾され、チャネルメッセージは常に許可されます。オーナーを `dmAllowlist` や `defaultAuthorizedShips` に追加する必要はありません。 設定されている場合、オーナーは以下の通知を DM で受け取ります: * 許可リストにない ship からの DM リクエスト * 未承認のチャネルでのメンション * グループへの招待リクエスト ## 自動承諾設定 DM 招待の自動承諾 (dmAllowlist に含まれる ship からの場合): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { tlon: { autoAcceptDmInvites: true, }, }, } ``` グループ招待の自動承諾: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { tlon: { autoAcceptGroupInvites: true, }, }, } ``` ## 配信ターゲット (CLI/Cron) `openclaw message send` や Cron 配信でこれらを使用します: * DM: `~sampel-palnet` または `dm/~sampel-palnet` * グループ: `chat/~host-ship/channel` または `group:~host-ship/channel` ## 同梱スキル Tlon プラグインには、Tlon 操作への CLI アクセスを提供する同梱スキル ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)) が含まれています: * **Contacts**: プロフィールの取得/更新、連絡先一覧 * **Channels**: 一覧表示、作成、メッセージ投稿、履歴取得 * **Groups**: 一覧表示、作成、メンバー管理 * **DMs**: メッセージ送信、メッセージへのリアクション * **Reactions**: 投稿や DM への絵文字リアクションの追加/削除 * **Settings**: スラッシュコマンドによるプラグイン権限の管理 このスキルは、プラグインがインストールされると自動的に利用可能になります。 ## 機能 | 機能 | ステータス | | :--------- | :--------------------------- | | ダイレクトメッセージ | ✅ サポート済み | | グループ/チャネル | ✅ サポート済み (デフォルトでメンション制約あり) | | スレッド | ✅ サポート済み (スレッド内で自動返信) | | リッチテキスト | ✅ Markdown を Tlon 形式に変換 | | 画像 | ✅ Tlon ストレージにアップロード | | リアクション | ✅ [同梱スキル](#bundled-skill) 経由 | | 投票 | ❌ 未サポート | | ネイティブコマンド | ✅ サポート済み (デフォルトではオーナーのみ) | ## トラブルシューティング まず以下のコマンドを順番に確認してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw status openclaw gateway status openclaw logs --follow openclaw doctor ``` よくある問題: * **DM が無視される**: 送信者が `dmAllowlist` に含まれておらず、承認フロー用の `ownerShip` も設定されていない。 * **グループメッセージが無視される**: チャネルが検出されていないか、送信者が承認されていない。 * **接続エラー**: ship の URL が到達可能か確認してください。ローカルの ship の場合は `allowPrivateNetwork` を有効にしてください。 * **認証エラー**: ログインコードが最新であることを確認してください（コードは更新されることがあります）。 ## 構成リファレンス 完全な構成: [構成](/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`: 手動で固定されたチャネル。 * `channels.tlon.defaultAuthorizedShips`: すべてのチャネルで承認される ship。 * `channels.tlon.authorization.channelRules`: チャネルごとの認証ルール。 * `channels.tlon.showModelSignature`: メッセージにモデル名を付加。 ## 補足事項 * グループでの返信には、応答のためにメンション (例: `~your-bot-ship`) が必要です。 * スレッドへの返信: 受信メッセージがスレッド内の場合、OpenClaw はそのスレッド内で返信します。 * リッチテキスト: Markdown 形式 (太字、斜体、コード、見出し、リスト) は Tlon のネイティブ形式に変換されます。 * 画像: URL は Tlon ストレージにアップロードされ、画像ブロックとして埋め込まれます。 # Channel Troubleshooting Source: https://openclawdoc.org/channels/troubleshooting チャネル連携で起きやすい障害の切り分けガイドです。接続済みなのに応答しない場合の診断コマンドと修正手順を確認できます。 チャネル自体は接続されているが、期待通りの動作をしない場合は、このページを確認してください。 ## 診断コマンド まず、以下のコマンドを順番に実行してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` 正常な状態の目安: * `Runtime: running` * `RPC probe: ok` * チャネルプローブの結果が `connected` または `ready` になっている ## WhatsApp ### WhatsApp の障害パターン | 症状 | 確認事項 | 解決策 | | :-------------- | :-------------------------------------- | :--------------------------------- | | 接続中だが DM の返信がない | `openclaw pairing list whatsapp` | 送信者を承認するか、DM ポリシー/許可リストを変更します。 | | グループメッセージが無視される | `requireMention` および構成内のメンションパターンを確認 | ボットにメンションするか、そのグループのメンション制限を緩和します。 | | 切断と再ログインを繰り返す | `openclaw channels status --probe` + ログ | 再ログインを行い、認証情報ディレクトリが正常であることを確認します。 | 詳細なトラブルシューティング: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick) ## Telegram ### Telegram の障害パターン | 症状 | 確認事項 | 解決策 | | :--------------------- | :---------------------------------- | :------------------------------------------------------------- | | `/start` しても返信フローが動かない | `openclaw pairing list telegram` | ペアリングを承認するか、DM ポリシーを変更します。 | | ボットは起動中だがグループで無反応 | メンション要件とボットのプライバシーモードを確認 | グループの可視性を確保するためにプライバシーモードを無効にするか、ボットにメンションします。 | | ネットワークエラーで送信に失敗する | ログで Telegram API 呼び出しの失敗を確認 | `api.telegram.org` への DNS/IPv6/プロキシのルーティングを修正します。 | | アップグレード後に許可リストでブロックされる | `openclaw security audit` と構成の許可リスト | `openclaw doctor --fix` を実行するか、`@username` を数値の送信者 ID に置き換えます。 | 詳細なトラブルシューティング: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) ## Discord ### Discord の障害パターン | 症状 | 確認事項 | 解決策 | | :---------------- | :--------------------------------- | :---------------------------------------------------------- | | ボットは起動中だがサーバーで無反応 | `openclaw channels status --probe` | サーバー/チャネルを許可リストに追加し、「Message Content Intent」が有効であることを確認します。 | | グループメッセージが無視される | ログでメンションによる破棄を確認 | ボットにメンションするか、サーバー/チャネル設定で `requireMention: false` にします。 | | DM の返信がない | `openclaw pairing list discord` | DM のペアリングを承認するか、DM ポリシーを調整します。 | 詳細なトラブルシューティング: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) ## Slack ### Slack の障害パターン | 症状 | 確認事項 | 解決策 | | :-------------------- | :--------------------------------- | :------------------------------------- | | Socket Mode で接続中だが無反応 | `openclaw channels status --probe` | App Token, Bot Token および必要なスコープを確認します。 | | DM がブロックされる | `openclaw pairing list slack` | ペアリングを承認するか、DM ポリシーを緩和します。 | | チャネルメッセージが無視される | `groupPolicy` とチャネルの許可リストを確認 | チャネルを許可リストに追加するか、ポリシーを `open` に変更します。 | 詳細なトラブルシューティング: [/channels/slack#troubleshooting](/channels/slack#troubleshooting) ## iMessage および BlueBubbles ### iMessage / BlueBubbles の障害パターン | 症状 | 確認事項 | 解決策 | | :------------------- | :--------------------------------------------------- | :----------------------------------------- | | インバウンドイベントが届かない | Webhook/サーバーの到達可能性とアプリの権限を確認 | Webhook URL または BlueBubbles サーバーの状態を修正します。 | | macOS で送信はできるが受信できない | macOS の「メッセージ」自動化に関するプライバシー権限 | TCC 権限を再付与し、チャネルプロセスを再起動します。 | | DM 送信者がブロックされる | `openclaw pairing list imessage` (または `bluebubbles`) | ペアリングを承認するか、許可リストを更新します。 | 詳細なトラブルシューティング: * [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc) * [/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) ## Matrix ### Matrix の障害パターン | 症状 | 確認事項 | 解決策 | | :------------------- | :--------------------------------- | :------------------------------ | | ログイン中だがルームメッセージを無視する | `openclaw channels status --probe` | `groupPolicy` とルームの許可リストを確認します。 | | DM が処理されない | `openclaw pairing list matrix` | 送信者を承認するか、DM ポリシーを調整します。 | | 暗号化されたルームで失敗する | 暗号化モジュールと暗号化設定を確認 | 暗号化サポートを有効にし、ルームに再参加または同期します。 | 詳細なトラブルシューティング: [/channels/matrix#troubleshooting](/channels/matrix#troubleshooting) # Twitch Source: https://openclawdoc.org/channels/twitch Twitch チャットを OpenClaw に接続する設定ガイドです。IRC 経由の構成、ボットアカウント、プラグイン導入手順を確認できます。 IRC 接続を介した Twitch チャットのサポートです。OpenClaw は Twitch ユーザー（ボットアカウント）として接続し、指定したチャネルでメッセージの送受信を行います。 ## プラグインが必要 Twitch はプラグインとして提供されており、コアインストールには同梱されていません。 CLI (npm レジストリ) 経由でインストールします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/twitch ``` ローカルチェックアウト (git リポジトリから実行する場合): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/twitch ``` 詳細: [プラグイン](/tools/plugin) ## クイックセットアップ (初心者向け) 1. ボット用の専用 Twitch アカウントを作成します（既存のアカウントを使用することも可能です）。 2. 認証情報を生成します: [Twitch Token Generator](https://twitchtokengenerator.com/) * **Bot Token** を選択します。 * スコープに `chat:read` と `chat:write` が含まれていることを確認します。 * **Client ID** と **Access Token** をコピーします。 3. Twitch ユーザー ID を確認します: [ユーザー ID 変換ツール](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) 4. トークンを構成します: * 環境変数: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (デフォルトアカウントのみ) * 構成ファイル: `channels.twitch.accessToken` * 両方が設定されている場合は構成ファイルが優先されます（環境変数はデフォルトアカウントにのみ適用されます）。 5. ゲートウェイを起動します。 **⚠️ 重要:** 未承認のユーザーがボットを操作できないよう、アクセス制御（`allowFrom` または `allowedRoles`）を設定してください。`requireMention` はデフォルトで `true` です。 最小限の構成: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { enabled: true, username: "openclaw", // ボットの Twitch アカウント名 accessToken: "oauth:abc123...", // OAuth アクセストークン（または環境変数 OPENCLAW_TWITCH_ACCESS_TOKEN を使用） clientId: "xyz789...", // Token Generator から取得した Client ID channel: "vevisk", // 参加する Twitch チャネルのチャット（必須） allowFrom: ["123456789"], // (推奨) 自身の Twitch ユーザー ID。上記ツールで確認してください。 }, }, } ``` ## Twitch チャネルの概要 * ゲートウェイが所有する Twitch チャネルです。 * 確定的なルーティング: 返信は常にメッセージが届いた Twitch チャットに送信されます。 * 各アカウントは個別のセッションキー `agent::twitch:` にマッピングされます。 * `username` は認証に使用するボットのアカウント名、`channel` は参加するチャットルーム名です。 ## 詳細セットアップ ### 認証情報の生成 [Twitch Token Generator](https://twitchtokengenerator.com/) を使用します: * **Bot Token** を選択します。 * スコープ `chat:read` および `chat:write` が選択されていることを確認します。 * **Client ID** と **Access Token** をコピーします。 手動でのアプリ登録は不要です。トークンは数時間で期限切れになります。 ### ボットの構成 **環境変数 (デフォルトアカウントのみ):** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... ``` **構成ファイル:** ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { enabled: true, username: "openclaw", accessToken: "oauth:abc123...", clientId: "xyz789...", channel: "vevisk", }, }, } ``` 環境変数と構成ファイルの両方が設定されている場合、構成ファイルが優先されます。 ### アクセス制御 (推奨) ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { allowFrom: ["123456789"], // (推奨) 特定の Twitch ユーザー ID のみを許可 }, }, } ``` 厳格な許可リストには `allowFrom` を使用してください。ロール（役割）ベースのアクセスが必要な場合は、代わりに `allowedRoles` を使用します。 **利用可能なロール:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`。 **なぜユーザー ID なのか？** ユーザー名は変更可能で、なりすましのリスクがあります。ユーザー ID は不変です。 Twitch ユーザー ID の確認: [Twitch ユーザー名を ID に変換](https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/) ## トークンの更新 (オプション) [Twitch Token Generator](https://twitchtokengenerator.com/) で生成されたトークンは自動更新できません。期限が切れたら再生成してください。 自動更新が必要な場合は、[Twitch Developer Console](https://dev.twitch.tv/console) で自身の Twitch アプリケーションを作成し、以下を構成に追加してください: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { clientSecret: "your_client_secret", refreshToken: "your_refresh_token", }, }, } ``` ボットは期限が切れる前に自動的にトークンを更新し、そのイベントをログに記録します。 ## マルチアカウントのサポート `channels.twitch.accounts` を使用して、アカウントごとにトークンを設定できます。共通のパターンについては [`gateway/configuration`](/gateway/configuration) を参照してください。 構成例 (1 つのボットアカウントで 2 つのチャネルに参加する場合): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { accounts: { channel1: { username: "openclaw", accessToken: "oauth:abc123...", clientId: "xyz789...", channel: "vevisk", }, channel2: { username: "openclaw", accessToken: "oauth:def456...", clientId: "uvw012...", channel: "secondchannel", }, }, }, }, } ``` **注意:** 各アカウント（チャネルごと）に個別のトークンが必要です。 ## アクセス制御の詳細 ### ロールベースの制限 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { accounts: { default: { allowedRoles: ["moderator", "vip"], }, }, }, }, } ``` ### ユーザー ID による許可リスト (最も安全) ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { accounts: { default: { allowFrom: ["123456789", "987654321"], }, }, }, }, } ``` ### ロールベースのアクセス (代替) `allowFrom` を設定すると、そのユーザー ID のみが許可される厳格なリストになります。 ロールベースのアクセスを行いたい場合は、`allowFrom` を未設定にし、`allowedRoles` を構成してください。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { accounts: { default: { allowedRoles: ["moderator"], }, }, }, }, } ``` ### @メンション要件の無効化 デフォルトでは `requireMention` は `true` です。これを無効にしてすべてのメッセージに応答させるには以下のように設定します: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { twitch: { accounts: { default: { requireMention: false, }, }, }, }, } ``` ## トラブルシューティング まず、以下の診断コマンドを実行してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw doctor openclaw channels status --probe ``` ### ボットがメッセージに反応しない **アクセス制御を確認:** 自身のユーザー ID が `allowFrom` に含まれているか確認してください。テストとして一時的に `allowFrom` を削除し、`allowedRoles: ["all"]` に設定してみてください。 **ボットがチャネルに参加しているか確認:** ボットは `channel` 設定で指定されたチャネルに参加している必要があります。 ### トークンの問題 **「Failed to connect」や認証エラー:** * `accessToken` が OAuth アクセストークンの値（通常 `oauth:` プレフィックスで始まる）であることを確認してください。 * トークンに `chat:read` と `chat:write` のスコープが付与されているか確認してください。 * 自動更新を使用している場合は、`clientSecret` と `refreshToken` が設定されているか確認してください。 ### トークンの更新が動作しない **ログで更新イベントを確認:** ``` Using env token source for mybot Access token refreshed for user 123456 (expires in 14400s) ``` 「token refresh disabled (no refresh token)」と表示される場合: * `clientSecret` が提供されているか確認してください。 * `refreshToken` が提供されているか確認してください。 ## 構成リファレンス **アカウント設定:** * `username` - ボットのユーザー名 * `accessToken` - `chat:read` と `chat:write` を持つ OAuth アクセストークン * `clientId` - Twitch Client ID (Token Generator または自身のアプリから) * `channel` - 参加するチャネル（必須） * `enabled` - このアカウントを有効化（デフォルト: `true`） * `clientSecret` - オプション: トークン自動更新用 * `refreshToken` - オプション: トークン自動更新用 * `expiresIn` - トークンの有効期限（秒） * `obtainmentTimestamp` - トークン取得時のタイムスタンプ * `allowFrom` - ユーザー ID の許可リスト * `allowedRoles` - ロールベースのアクセス制御 (`"moderator" | "owner" | "vip" | "subscriber" | "all"`) * `requireMention` - @メンションを必須にする（デフォルト: `true`） **プロバイダーオプション:** * `channels.twitch.enabled` - チャネルの起動を有効/無効にします。 * `channels.twitch.username` - ボットのユーザー名（単一アカウント用の簡略設定） * `channels.twitch.accessToken` - OAuth アクセストークン（単一アカウント用の簡略設定） * `channels.twitch.clientId` - Twitch Client ID（単一アカウント用の簡略設定） * `channels.twitch.channel` - 参加するチャネル（単一アカウント用の簡略設定） * `channels.twitch.accounts.` - マルチアカウント設定（上記のアカウント設定項目すべて） 完全な構成例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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"], }, }, }, }, } ``` ## ツールアクション エージェントは `twitch` を呼び出して以下の操作が可能です: * `send` - チャネルにメッセージを送信します。 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { action: "twitch", params: { message: "Hello Twitch!", to: "#mychannel", }, } ``` ## セキュリティと運用 * **トークンはパスワードと同様に扱う** - 決して Git 等にコミットしないでください。 * 長時間運用するボットには **トークンの自動更新** を使用してください。 * アクセス制御にはユーザー名ではなく **ユーザー ID の許可リスト** を使用してください。 * トークンの更新イベントや接続ステータスをログで監視してください。 * トークンのスコープは最小限（`chat:read` と `chat:write` のみ）に留めてください。 * **動作が不安定な場合**: 他のプロセスがセッションを所有していないことを確認し、ゲートウェイを再起動してください。 ## 制限事項 * 1 メッセージあたり **500 文字**（単語の境界で自動的に分割されます）。 * Markdown は分割前に除去されます。 * 独自のレート制限はありません（Twitch の組み込み制限に従います）。 # WhatsApp Source: https://openclawdoc.org/channels/whatsapp WhatsApp Web を OpenClaw に接続する設定と運用ガイドです。Baileys 構成、アクセス制御、配信動作、主要機能を確認できます。 ステータス: WhatsApp Web (Baileys) 経由で実稼働準備完了。ゲートウェイはリンクされたセッションを所有します。 デフォルトの DM ポリシーは、不明な送信者に対するペアリングです。 クロスチャネル診断と修復プレイブック。 完全なチャネル構成パターンと例。 ## クイックセットアップ ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { dmPolicy: "pairing", allowFrom: ["+15551234567"], groupPolicy: "allowlist", groupAllowFrom: ["+15551234567"], }, }, } ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels login --channel whatsapp ``` 特定のアカウントの場合: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels login --channel whatsapp --account work ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` ペアリング要求は 1 時間後に期限切れになります。保留中のリクエストはチャネルごとに 3 に制限されます。 OpenClaw では、可能な場合は別の番号で WhatsApp を実行することをお勧めします。 (チャネルのメタデータとオンボーディング フローはそのセットアップ用に最適化されていますが、個人番号のセットアップもサポートされています。) ## 導入パターン これは最もクリーンな動作モードです。 * OpenClaw 用に別の WhatsApp ID * より明確な DM ホワイトリストとルーティング境界 * セルフチャットの混乱の可能性が低くなります 最小限のポリシー パターン: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { dmPolicy: "allowlist", allowFrom: ["+15551234567"], }, }, } ``` オンボーディングは個人番号モードをサポートし、セルフチャットに適したベースラインを書き込みます。 * `dmPolicy: "allowlist"` * `allowFrom` には個人番号が含まれます * `selfChatMode: true` 実行時、セルフチャット保護により、リンクされた自己番号と `allowFrom` がキーオフされます。 メッセージング プラットフォーム チャネルは、現在の OpenClaw チャネル アーキテクチャでは WhatsApp Web ベース (`Baileys`) です。 組み込みのチャット チャネル レジストリには、個別の Twilio WhatsApp メッセージング チャネルはありません。 ## ランタイムモデル * ゲートウェイは WhatsApp ソケットと再接続ループを所有します。 * アウトバウンド送信には、ターゲット アカウントのアクティブな WhatsApp リスナーが必要です。 * ステータス チャットとブロードキャスト チャットは無視されます (`@status`、`@broadcast`)。 * ダイレクト チャットは DM セッション ルールを使用します (`session.dmScope`、デフォルトの `main` はエージェントのメイン セッションへの DM を折りたたみます)。 * グループ セッションは分離されています (`agent::whatsapp:group:`)。 ## アクセス制御とアクティベーション `channels.whatsapp.dmPolicy` は、直接チャット アクセスを制御します。 * `pairing` (デフォルト) * `allowlist` * `open` (`"*"` を含めるには `allowFrom` が必要です) * `disabled` `allowFrom` は、E.164 形式の数値 (内部で正規化されたもの) を受け入れます。マルチアカウントオーバーライド: `channels.whatsapp.accounts..dmPolicy` (および `allowFrom`) は、そのアカウントのチャネルレベルのデフォルトよりも優先されます。 実行時の動作の詳細: * ペアリングはチャネルの許可ストアに保持され、構成された `allowFrom` とマージされます。 * ホワイトリストが設定されていない場合、リンクされた自己番号はデフォルトで許可されます * 送信 `fromMe` DM は自動ペアリングされません グループ アクセスには 2 つの層があります。 1. **グループ メンバーシップ許可リスト** (`channels.whatsapp.groups`) * `groups` を省略した場合、すべてのグループが対象となります。 * `groups` が存在する場合、グループ許可リストとして機能します (`"*"` は許可されます) 2. **グループ送信者ポリシー** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) * `open`: 送信者の許可リストがバイパスされました * `allowlist`: 送信者は `groupAllowFrom` (または `*`) と一致する必要があります * `disabled`: すべてのグループ受信をブロックします 送信者許可リストのフォールバック: * `groupAllowFrom` が設定されていない場合、ランタイムは利用可能な場合は `allowFrom` に戻ります。 * 送信者の許可リストは、メンション/返信のアクティブ化の前に評価されます。 注: `channels.whatsapp` ブロックがまったく存在しない場合、`channels.defaults.groupPolicy` が設定されている場合でも、ランタイム グループ ポリシー フォールバックは `allowlist` (警告ログ付き) になります。 グループ返信にはデフォルトでメンションが必要です。メンション検出には次のものが含まれます。 * WhatsApp でボットの ID について明示的に言及する * 構成されたメンション正規表現パターン (`agents.list[].groupChat.mentionPatterns`、フォールバック `messages.groupChat.mentionPatterns`) * ボットへの暗黙的な返信検出 (返信送信者がボットの ID と一致する) セキュリティ上の注意: * 引用/返信は言及ゲートのみを満たします。送信者の承認は**されません** * `groupPolicy: "allowlist"` では、許可リストに登録されていない送信者は、許可リストに登録されているユーザーのメッセージに返信した場合でもブロックされます。 セッションレベルのアクティブ化コマンド: * `/activation mention` * `/activation always` `activation` はセッション状態を更新します (グローバル構成ではありません)。オーナーゲート型です。 ## 個人番号とセルフチャットの動作 リンクされた自己番号が `allowFrom` にも存在する場合、WhatsApp セルフチャットの保護機能が有効になります。 * セルフチャットターンの開封確認をスキップします * 自分自身に ping を実行するメンション JID 自動トリガー動作を無視します * `messages.responsePrefix` が設定されていない場合、セルフチャットの返信はデフォルトで `[{identity.name}]` または `[openclaw]` になります。 ## メッセージの正規化とコンテキスト 受信 WhatsApp メッセージは、共有受信エンベロープでラップされます。 引用された返信が存在する場合、コンテキストが次の形式で追加されます。 ````text theme={"theme":{"light":"min-light","dark":"min-dark"}} [Replying to id:] [/Replying] ```利用可能な場合は、返信メタデータ フィールドも入力されます (`ReplyToId`、`ReplyToBody`、`ReplyToSender`、送信者 JID/E.164)。 メディアのみの受信メッセージは、次のようなプレースホルダーを使用して正規化されます。 - `` - `` - `` - `` - `` 場所と連絡先のペイロードは、ルーティング前にテキスト コンテキストに正規化されます。 グループの場合、未処理のメッセージをバッファリングし、ボットが最終的にトリガーされたときにコンテキストとして挿入できます。 - デフォルトの制限: `50` - 構成: `channels.whatsapp.historyLimit` - フォールバック: `messages.groupChat.historyLimit` - `0` を無効にします 注射マーカー: - `[Chat messages since your last reply - for context]` - `[Current message - respond to this]` 開封確認は、受信された WhatsApp メッセージに対してデフォルトで有効になっています。 グローバルに無効にする: ```json5 { channels: { whatsapp: { sendReadReceipts: false, }, }, } ```` アカウントごとの上書き: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { accounts: { work: { sendReadReceipts: false, }, }, }, }, } ``` セルフチャットは、グローバルに有効になっている場合でも開封確認をスキップします。 ## 配信、チャンキング、およびメディア * デフォルトのチャンク制限: `channels.whatsapp.textChunkLimit = 4000` * `channels.whatsapp.chunkMode = "length" | "newline"` * `newline` モードは段落境界 (空白行) を優先し、その後長さ安全なチャンクに戻ります。 * 画像、ビデオ、オーディオ (PTT 音声メモ)、およびドキュメントのペイロードをサポート * ボイスノートの互換性のために、`audio/ogg` は `audio/ogg; codecs=opus` に書き換えられます * アニメーション GIF の再生は、ビデオ送信の `gifPlayback: true` 経由でサポートされます。 * マルチメディア応答ペイロードを送信するときに、キャプションが最初のメディア アイテムに適用されます。 * メディア ソースは HTTP(S)、`file://`、またはローカル パスにすることができます。 * インバウンドメディア保存キャップ: `channels.whatsapp.mediaMaxMb` (デフォルト `50`) * 送信メディア送信上限: `channels.whatsapp.mediaMaxMb` (デフォルト `50`) * アカウントごとの上書きには `channels.whatsapp.accounts..mediaMaxMb` を使用します * 画像は制限に合わせて自動的に最適化されます (サイズ変更/品質スイープ)。 * メディア送信失敗時、最初のアイテムのフォールバックは応答をサイレントにドロップする代わりにテキスト警告を送信します。 ## 肯定応答 WhatsApp は、`channels.whatsapp.ackReaction` 経由の受信受信に対する即時確認応答をサポートしています。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { ackReaction: { emoji: "👀", direct: true, group: "mentions", // always | mentions | never }, }, }, } ``` 行動メモ: * 受信が受け入れられた後すぐに送信されます (事前応答) * 失敗はログに記録されますが、通常の応答配信はブロックされません * グループモード `mentions` は言及によって引き起こされたターンに反応します。グループのアクティブ化 `always` は、このチェックのバイパスとして機能します * WhatsApp は `channels.whatsapp.ackReaction` を使用します (従来の `messages.ackReaction` はここでは使用されません) ## マルチアカウントと認証情報 * アカウント ID は `channels.whatsapp.accounts` から取得されます * デフォルトのアカウント選択: `default` (存在する場合)、それ以外の場合は最初に設定されたアカウント ID (ソート済み) * アカウント ID は検索用に内部的に正規化されます * 現在の認証パス: `~/.openclaw/credentials/whatsapp//creds.json` * バックアップ ファイル: `creds.json.bak` * `~/.openclaw/credentials/` の従来のデフォルト認証は引き続きデフォルト アカウント フローで認識/移行されます `openclaw channels logout --channel whatsapp [--account ]` は、そのアカウントの WhatsApp 認証状態をクリアします。 従来の認証ディレクトリでは、`oauth.json` は保持されますが、Baileys 認証ファイルは削除されます。 ## ツール、アクション、構成の書き込み * エージェント ツールのサポートには、WhatsApp 反応アクション (`react`) が含まれます。 * アクションゲート: * `channels.whatsapp.actions.reactions` * `channels.whatsapp.actions.polls` * チャネル開始の設定書き込みはデフォルトで有効になっています (`channels.whatsapp.configWrites=false` で無効にします)。 ## トラブルシューティング 症状: チャネルステータスレポートがリンクされていません。 修正: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels login --channel whatsapp openclaw channels status ``` 症状: リンクされたアカウントで、切断または再接続が繰り返し試行されます。 修正: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw doctor openclaw logs --follow ``` 必要に応じて、`channels login` と再リンクします。 ターゲット アカウントにアクティブなゲートウェイ リスナーが存在しない場合、アウトバウンド送信は失敗します。 ゲートウェイが実行中であり、アカウントがリンクされていることを確認してください。 次の順序で確認してください。 * `groupPolicy` * `groupAllowFrom` / `allowFrom` * `groups` ホワイトリスト エントリ * メンションゲート (`requireMention` + メンションパターン) * `openclaw.json` (JSON5) の重複キー: 後のエントリは前のエントリをオーバーライドするため、スコープごとに 1 つの `groupPolicy` を保持します。 WhatsApp ゲートウェイ ランタイムは Node を使用する必要があります。 Bun は、WhatsApp/Telegram ゲートウェイの安定した動作には互換性がないとしてフラグが立てられています。 ## 構成参照ポインタ 主な参考文献: * [設定リファレンス - WhatsApp](/gateway/configuration-reference#whatsapp) シグナルの高い WhatsApp フィールド: * アクセス: `dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` * 配送: `textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction` * マルチアカウント: `accounts..enabled`、`accounts..authDir`、アカウントレベルの上書き * 操作: `configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*` * セッションの動作: `session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms..historyLimit` ## 関連- [ペアリング](/channels/pairing) * [チャンネルルーティング](/channels/channel-routing) * [マルチエージェントルーティング](/concepts/multi-agent) * [トラブルシューティング](/channels/troubleshooting) # Zalo Source: https://openclawdoc.org/channels/zalo Zalo ボットを OpenClaw に接続する設定ガイドです。実験的サポートの範囲、Webhook 構成、DM とグループ運用を確認できます。 ステータス: 実験的。DM がサポートされており、グループ処理は明示的なポリシー制御によって利用可能です。 ## プラグインが必要 Zalo はプラグインとして提供されており、コアインストールには同梱されていません。 * CLI 経由でインストール: `openclaw plugins install @openclaw/zalo` * または、オンボーディング中に **Zalo** を選択し、インストールプロンプトに従ってください。 * 詳細: [プラグイン](/tools/plugin) ## クイックセットアップ (初心者向け) 1. Zalo プラグインをインストールします: * ソースチェックアウトから: `openclaw plugins install ./extensions/zalo` * npm から (公開されている場合): `openclaw plugins install @openclaw/zalo` * または、オンボーディングで **Zalo** を選択。 2. トークンを設定します: * 環境変数: `ZALO_BOT_TOKEN=...` * 構成ファイル: `channels.zalo.botToken: "..."`。 3. ゲートウェイを再起動します (またはオンボーディングを完了させます)。 4. DM アクセスはデフォルトでペアリングモードです。最初の連絡時にペアリングコードを承認してください。 最小限の構成: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalo: { enabled: true, botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, } ``` ## Zalo チャネルの概要 Zalo はベトナムで広く使われているメッセージングアプリです。そのボット API を使用することで、ゲートウェイは 1 対 1 の会話用ボットを運用できます。 確定的なルーティングが必要なカスタマーサポートや通知の用途に適しています。 * ゲートウェイが所有する Zalo ボット API チャネルです。 * 確定的なルーティング: 返信は常に Zalo に戻ります。モデルがチャネルを選択することはありません。 * DM はエージェントのメインセッションを共有します。 * グループはポリシー制御 (`groupPolicy` + `groupAllowFrom`) でサポートされ、デフォルトは安全のため許可リスト方式（フェールクローズ）になっています。 ## セットアップ手順 ### 1) ボットトークンの作成 (Zalo Bot Platform) 1. [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) にアクセスしてサインインします。 2. 新しいボットを作成し、設定を行います。 3. ボットトークン (形式: `12345689:abc-xyz`) をコピーします。 ### 2) トークンの構成 (環境変数または構成ファイル) 構成例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalo: { enabled: true, botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, } ``` 環境変数の場合: `ZALO_BOT_TOKEN=...` (デフォルトアカウントにのみ適用されます)。 マルチアカウントのサポート: `channels.zalo.accounts` を使用して、アカウントごとにトークンとオプションの `name` を指定できます。 3. ゲートウェイを再起動します。トークンが解決されると Zalo チャネルが開始されます。 4. ボットへ最初にメッセージを送信した際に表示されるペアリングコードを承認してください。 ## 仕組みと動作 * 受信メッセージは、メディアプレースホルダーと共に共通のチャネル形式に正規化されます。 * 返信は常に同じ Zalo チャットに送信されます。 * デフォルトはロングポーリング方式です。`channels.zalo.webhookUrl` を設定することで webhook モードも利用可能です。 ## 制限事項 * 送信テキストは Zalo API の制限により 2000 文字ごとに分割されます。 * メディアの送受信サイズは `channels.zalo.mediaMaxMb` (デフォルト 5MB) で制限されます。 * ストリーミングは、2000 文字制限のため有用性が低く、デフォルトでブロックされています。 ## アクセス制御 (DM) ### DM アクセス * デフォルト: `channels.zalo.dmPolicy = "pairing"`。未知の送信者にはペアリングコードが送信され、承認されるまでメッセージは無視されます (コードは 1 時間で期限切れになります)。 * 承認方法: * `openclaw pairing list zalo` * `openclaw pairing approve zalo ` * 詳細については [ペアリング](/channels/pairing) を参照してください。 * `channels.zalo.allowFrom` は数値のユーザー ID を受け入れます（ユーザー名の検索は利用できません）。 ## アクセス制御 (グループ) * `channels.zalo.groupPolicy` でグループのインバウンド処理を制御します: `open | allowlist | disabled`。 * デフォルトは安全のため `allowlist` (許可リスト) です。 * `channels.zalo.groupAllowFrom` で、グループ内でボットをトリガーできる送信者 ID を制限します。 * `groupAllowFrom` が未設定の場合、送信者チェックには `allowFrom` が使用されます。 * `groupPolicy: "disabled"` はすべてのグループメッセージをブロックします。 * `groupPolicy: "open"` は（メンション制約を満たせば）すべてのグループメンバーを許可します。 * 注意: `channels.zalo` 構成が完全に欠落している場合でも、安全のため `groupPolicy="allowlist"` が適用されます。 ## ロングポーリング vs webhook * デフォルト: ロングポーリング (公開 URL は不要)。 * webhook モード: `channels.zalo.webhookUrl` と `channels.zalo.webhookSecret` を設定します。 * シークレットは 8〜256 文字である必要があります。 * webhook URL は HTTPS である必要があります。 * Zalo は検証用に `X-Bot-Api-Secret-Token` ヘッダーを付けてイベントを送信します。 * ゲートウェイは `channels.zalo.webhookPath` (デフォルトは URL のパス部分) でリクエストを処理します。 * リクエストの `Content-Type` は `application/json` である必要があります。 * 重複したイベント (`event_name + message_id`) は、短期間の再送ウィンドウ内では無視されます。 * 急激なトラフィック増加にはパス/送信元ごとにレート制限が適用され、HTTP 429 を返す場合があります。 **注意:** Zalo API の仕様上、ロングポーリング（getUpdates）と webhook は排他的です。 ## サポートされているメッセージ形式 * **テキスト**: 2000 文字の分割送信を含め完全サポート。 * **画像**: 受信画像のダウンロードおよび処理、`sendPhoto` による送信をサポート。 * **ステッカー**: ログには記録されますが、エージェントによる応答は行われません。 * **未サポートの形式**: ログには記録されます（例: 保護されたユーザーからのメッセージなど）。 ## 機能一覧 | 機能 | ステータス | | :--------- | :----------------------------- | | ダイレクトメッセージ | ✅ サポート済み | | グループ | ⚠️ ポリシー制御によりサポート (デフォルトは許可リスト) | | メディア (画像) | ✅ サポート済み | | リアクション | ❌ 未サポート | | スレッド | ❌ 未サポート | | 投票 | ❌ 未サポート | | ネイティブコマンド | ❌ 未サポート | | ストリーミング | ⚠️ ブロック (2000 文字制限のため) | ## 配信ターゲット (CLI/Cron) * ターゲットとしてチャット ID を使用します。 * 例: `openclaw message send --channel zalo --target 123456789 --message "こんにちは"`。 ## トラブルシューティング **ボットが応答しない:** * トークンが有効か確認してください: `openclaw channels status --probe` * 送信者が承認されているか（ペアリングまたは allowFrom）確認してください。 * ゲートウェイのログを確認してください: `openclaw logs --follow` **webhook がイベントを受信しない:** * webhook URL が HTTPS を使用しているか確認してください。 * シークレットトークンが 8〜256 文字か確認してください。 * ゲートウェイの HTTP エンドポイントが設定されたパスで到達可能か確認してください。 * ロングポーリングが動作していないか確認してください（排他的な関係です）。 ## 構成リファレンス (Zalo) 完全な構成: [構成](/gateway/configuration) プロバイダーオプション: * `channels.zalo.enabled`: チャネルの起動を有効/無効にします。 * `channels.zalo.botToken`: Zalo Bot Platform から取得したボットトークン。 * `channels.zalo.tokenFile`: ファイルからトークンを読み取ります。 * `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (デフォルト: pairing)。 * `channels.zalo.allowFrom`: DM 許可リスト (数値ユーザー ID)。`open` には `"*"` が必要です。 * `channels.zalo.groupPolicy`: `open | allowlist | disabled` (デフォルト: allowlist)。 * `channels.zalo.groupAllowFrom`: グループ送信者の許可リスト (ユーザー ID)。未設定時は `allowFrom` にフォールバックします。 * `channels.zalo.mediaMaxMb`: 送受信メディアのサイズ上限 (MB, デフォルト 5)。 * `channels.zalo.webhookUrl`: webhook モードを有効化 (HTTPS 必須)。 * `channels.zalo.webhookSecret`: webhook シークレット (8〜256 文字)。 * `channels.zalo.webhookPath`: ゲートウェイ上の webhook 受付パス。 * `channels.zalo.proxy`: API リクエストに使用するプロキシ URL。 マルチアカウントオプション: * `channels.zalo.accounts..botToken`: アカウントごとのトークン。 * `channels.zalo.accounts..name`: 表示名。 * `channels.zalo.accounts..enabled`: アカウントの有効/無効。 * `channels.zalo.accounts..dmPolicy`: アカウントごとの DM ポリシー。 * `channels.zalo.accounts..allowFrom`: アカウントごとの許可リスト。 * `channels.zalo.accounts..groupPolicy`: アカウントごとのグループポリシー。 * `channels.zalo.accounts..webhookUrl`: アカウントごとの webhook URL。 * `channels.zalo.accounts..webhookSecret`: アカウントごとの webhook シークレット。 * `channels.zalo.accounts..webhookPath`: アカウントごとの webhook 受付パス。 * `channels.zalo.accounts..proxy`: アカウントごとのプロキシ URL。 # Zalo Personal Source: https://openclawdoc.org/channels/zalouser Zalo 個人アカウントを OpenClaw に接続する設定ガイドです。QR ログイン、非公式連携の制約、メッセージフローを確認できます。 ステータス: 実験的。この連携機能は、OpenClaw 内部でネイティブの `zca-js` を使用し、**個人の Zalo アカウント**を自動化します。 > **警告:** これは非公式の連携機能であり、アカウントの停止や凍結につながるリスクがあります。ご自身の責任において使用してください。 ## プラグインが必要 Zalo Personal はプラグインとして提供されており、コアインストールには同梱されていません。 * CLI 経由でインストール: `openclaw plugins install @openclaw/zalouser` * または、ソースチェックアウトからインストール: `openclaw plugins install ./extensions/zalouser` * 詳細: [プラグイン](/tools/plugin) 外部の `zca`/`openzca` CLI バイナリは不要です。 ## クイックセットアップ (初心者向け) 1. プラグインをインストールします（上記参照）。 2. ログイン（ゲートウェイが動作しているマシンで QR コードを使用）: * `openclaw channels login --channel zalouser` * スマートフォンの Zalo アプリで表示された QR コードをスキャンします。 3. チャネルを有効にします: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalouser: { enabled: true, dmPolicy: "pairing", }, }, } ``` 4. ゲートウェイを再起動します（またはオンボーディングを完了させます）。 5. DM アクセスはデフォルトでペアリングモードです。最初の連絡時にペアリングコードを承認してください。 ## Zalo Personal チャネルの概要 * `zca-js` を介して完全にインプロセスで動作します。 * ネイティブのイベントリスナーを使用してインバウンドメッセージを受信します。 * JS API を通じて直接返信（テキスト/メディア/リンク）を送信します。 * Zalo ボット API が利用できない「個人アカウント」の用途向けに設計されています。 ## 名称について チャネル ID は `zalouser` です。これは、**個人の Zalo ユーザーアカウント**（非公式）を自動化することを明示するためです。将来的に公式の Zalo API 連携が導入される可能性に備え、`zalo` という ID は予約されています。 ## ID の確認 (ディレクトリ) ディレクトリ CLI を使用して、相手（ピア）やグループの ID を確認できます: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw directory self --channel zalouser openclaw directory peers list --channel zalouser --query "name" openclaw directory groups list --channel zalouser --query "work" ``` ## 制限事項 * 送信テキストは、Zalo クライアントの制限により約 2000 文字ごとに分割されます。 * ストリーミング出力はデフォルトでブロックされています。 ## アクセス制御 (DM) `channels.zalouser.dmPolicy` は `pairing | allowlist | open | disabled` (デフォルト: `pairing`) をサポートします。 `channels.zalouser.allowFrom` にはユーザー ID または名前を指定できます。オンボーディング中、プラグインのインプロセス連絡先検索を使用して、名前が ID に解決されます。 承認方法: * `openclaw pairing list zalouser` * `openclaw pairing approve zalouser ` ## グループアクセス (オプション) * デフォルト: `channels.zalouser.groupPolicy = "open"` (グループを許可)。未設定時のデフォルトを上書きするには `channels.defaults.groupPolicy` を使用してください。 * 許可リストによる制限: * `channels.zalouser.groupPolicy = "allowlist"` * `channels.zalouser.groups` (キーはグループ ID または名前。どのグループを許可するかを制御) * `channels.zalouser.groupAllowFrom` (許可されたグループ内で、誰がボットをトリガーできるかを制御) * すべてのグループをブロック: `channels.zalouser.groupPolicy = "disabled"`。 * 構成ウィザードで、グループ許可リストの設定を求めることができます。 * 起動時、OpenClaw は許可リスト内のグループ名やユーザー名を ID に解決し、そのマッピングをログに出力します。解決できなかったエントリは、入力されたままの形式で保持されます。 * `groupAllowFrom` が未設定の場合、グループ送信者のチェックには `allowFrom` が使用されます。 * 送信者チェックは、通常のグループメッセージと制御コマンド（例: `/new`, `/reset`）の両方に適用されます。 構成例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalouser: { groupPolicy: "allowlist", groupAllowFrom: ["1471383327500481391"], groups: { "123456789": { allow: true }, "Work Chat": { allow: true }, }, }, }, } ``` ### グループメンション制約 * `channels.zalouser.groups..requireMention` で、グループ返信にメンションを必須にするかどうかを制御します。 * 解決順序: 正確なグループ ID/名前 -> 正規化されたグループスラッグ -> `*` -> デフォルト (`true`)。 * これは許可リストに登録されたグループとオープングループモードの両方に適用されます。 * 権限のある制御コマンド（例: `/new`）は、メンション制約をバイパスできます。 * メンションが必要なためにグループメッセージがスキップされた場合、OpenClaw はそれを保留中のグループ履歴として保存し、次に処理されるメッセージに含めます。 * グループ履歴の制限数は、デフォルトで `messages.groupChat.historyLimit` (フォールバック値は 50) です。`channels.zalouser.historyLimit` でアカウントごとに上書き可能です。 構成例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalouser: { groupPolicy: "allowlist", groups: { "*": { allow: true, requireMention: true }, "Work Chat": { allow: true, requireMention: false }, }, }, }, } ``` ## マルチアカウント 各アカウントは、OpenClaw 状態内の `zalouser` プロファイルにマップされます。構成例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalouser: { enabled: true, defaultAccount: "default", accounts: { work: { enabled: true, profile: "work" }, }, }, }, } ``` ## タイピング、リアクション、配信確認 * 返信を送信する前に、タイピング中イベントを送信します (ベストエフォート)。 * メッセージリアクションアクション `react` をサポートしています。 * `remove: true` を指定することで、特定のリアクション絵文字を削除できます。 * リアクションの仕様については [リアクション](/tools/reactions) を参照してください。 * イベントメタデータを含むインバウンドメッセージに対し、配信済みおよび既読の確認を送信します (ベストエフォート)。 ## トラブルシューティング **ログインが維持されない:** * `openclaw channels status --probe` を確認してください。 * 再ログインを試してください: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser` **許可リストやグループ名が解決されない:** * `allowFrom` / `groupAllowFrom` / `groups` には数値 ID を使用するか、正確なフレンド名・グループ名を使用してください。 **古い CLI ベースの構成からアップグレードした場合:** * 外部の `zca` プロセスに関する古い設定は削除してください。 * このチャネルは外部 CLI バイナリなしで、OpenClaw 内部で完全に動作するようになりました。 # エージェントランタイム Source: https://openclawdoc.org/concepts/agent OpenClaw は、pi-mono から派生した単一の組み込みエージェントランタイムを実行します。ワークスペース (必須)、ブートストラップファイル (自動注入)、組み込みツールを確認できます。 OpenClaw は、**pi-mono** から派生した単一の組み込みエージェントランタイムを実行します。 ## ワークスペース (必須) OpenClaw は、単一のエージェントワークスペースディレクトリ (`agents.defaults.workspace`) を、エージェントがツールを実行しコンテキストを取得するための**唯一の**作業ディレクトリ (`cwd`) として使用します。 推奨: `openclaw setup` を実行して、不足している `~/.openclaw/openclaw.json` の作成とワークスペースファイルの初期化を行ってください。 ワークスペースのレイアウトとバックアップに関する詳細: [エージェントワークスペース](/concepts/agent-workspace) `agents.defaults.sandbox` が有効な場合、メイン以外のセッションでは `agents.defaults.sandbox.workspaceRoot` 配下にあるセッションごとのワークスペースで設定を上書きできます（[ゲートウェイ構成](/gateway/configuration) を参照）。 ## ブートストラップファイル (自動注入) `agents.defaults.workspace` 内には、OpenClaw が期待する以下のユーザー編集可能なファイルが存在します: * `AGENTS.md` — 動作指示 + 「記憶」 * `SOUL.md` — ペルソナ（人格）、境界線、トーン * `TOOLS.md` — ユーザーが管理するツールに関するメモ（例: `imsg`, `sag`, 慣習など） * `BOOTSTRAP.md` — 初回実行時に一度だけ行われる「儀式」用ファイル（完了後に削除されます） * `IDENTITY.md` — エージェントの名前、雰囲気、および絵文字 * `USER.md` — ユーザープロフィール + 希望する呼び名 新しいセッションの最初のターンで、OpenClaw はこれらのファイルの内容をエージェントのコンテキストに直接注入します。 内容が空のファイルはスキップされます。巨大なファイルは、プロンプトを軽量に保つためにマーカーと共に切り詰められます（すべての内容を把握するには、エージェントがそのファイルを直接読み取る必要があります）。 ファイルが存在しない場合、OpenClaw は「欠落」を示すマーカーを注入します（`openclaw setup` を実行すれば、安全なデフォルトテンプレートが作成されます）。 `BOOTSTRAP.md` は、他のブートストラップファイルが一切存在しない**新規ワークスペース**の場合にのみ作成されます。儀式を完了した後にこのファイルを削除すれば、その後の再起動時に再作成されることはありません。 既存のワークスペースを使用する場合などで、これらのファイルの自動生成を完全に無効にしたい場合は、以下を設定してください: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agent: { skipBootstrap: true } } ``` ## 組み込みツール コアツール（read/exec/edit/write および関連するシステムツール）は、ツールポリシーに従って常に利用可能です。`apply_patch` はオプションであり、`tools.exec.applyPatch` で許可されている場合にのみ利用できます。`TOOLS.md` はツールの存在自体を制御するものではなく、それらを*どのように*使ってほしいかをエージェントに伝えるためのガイドラインです。 ## スキル (Skills) OpenClaw は以下の 3 つの場所からスキルをロードします（名前が競合した場合はワークスペース内のものが優先されます）: * **Bundled**: インストール環境に同梱されているスキル * **Managed/local**: `~/.openclaw/skills` * **Workspace**: `/skills` スキルは構成ファイルや環境変数で制限をかけることができます（[ゲートウェイ構成](/gateway/configuration) の `skills` セクションを参照）。 ## pi-mono との統合 OpenClaw は pi-mono のコードベース（モデルやツールの一部）を再利用していますが、**セッション管理、検出、ツールの接続などは OpenClaw 独自の実装**です。 * pi-coding エージェントのランタイムは使用しません。 * `~/.pi/agent` や `/.pi` の設定は参照されません。 ## セッション (Sessions) 会話の記録（トランスクリプト）は JSONL 形式で以下の場所に保存されます: * `~/.openclaw/agents//sessions/.jsonl` セッション ID は OpenClaw によって決定され、固定されます。 以前の Pi や Tau のセッションフォルダは読み込まれません。 ## ストリーミング中のステアリング (Steering) キューモードが `steer` の場合、受信メッセージは現在の実行プロセスに割り込んで注入されます。 キューのチェックは**各ツール呼び出しの直後**に行われます。キューにメッセージがある場合、現在のアシスタントメッセージに含まれる残りのツール呼び出しはスキップされ（エラー内容: "Skipped due to queued user message."）、次のアシスタント応答の前にそのユーザーメッセージが注入されます。 キューモードが `followup` または `collect` の場合、受信メッセージは現在のターンが終わるまで保持され、その後キューに溜まった内容で新しいエージェントターンが開始されます。モードやデバウンス、上限設定の詳細は [キュー](/concepts/queue) を参照してください。 ブロックストリーミング（Block streaming）は、アシスタントのブロックが完了するたびに即座に送信する機能で、**デフォルトではオフ**になっています (`agents.defaults.blockStreamingDefault: "off"`)。 送信の区切り（境界）は `agents.defaults.blockStreamingBreak` (`text_end` または `message_end`。デフォルトは `text_end`) で調整可能です。 ブロックの分割サイズは `agents.defaults.blockStreamingChunk` で制御します（デフォルトは 800〜1200 文字。段落の区切り、改行、文の終わりの順で最適な位置を判断します）。 `agents.defaults.blockStreamingCoalesce` を使用して、短期間に連続するチャンクを結合し、通知の連打を抑えることができます。Telegram 以外のチャネルでブロック返信を有効にするには、明示的に `*.blockStreaming: true` を設定する必要があります。 詳細出力（verbose）時のツールサマリーは、ツール開始時に即座に発行されます。コントロール UI では、利用可能な場合にエージェントイベントを介してツールの出力をリアルタイムで表示できます。 詳細は [ストリーミングとチャンク化](/concepts/streaming) を参照してください。 ## モデルの参照方法 構成設定（例: `agents.defaults.model`, `agents.defaults.models`）におけるモデルの参照は、**最初の** `/` で分割して解析されます。 * モデルを構成する際は `provider/model` の形式を使用してください。 * モデル ID 自体に `/` が含まれる場合（OpenRouter 形式など）は、プロバイダーのプレフィックスを含めてください（例: `openrouter/moonshotai/kimi-k2`）。 * プロバイダーを省略した場合、OpenClaw はそれをエイリアス、あるいは**デフォルトプロバイダー**のモデルとして扱います（これはモデル ID 内に `/` が含まれない場合にのみ機能します）。 ## 最小限の構成例 最低限、以下の設定が必要です: * `agents.defaults.workspace` * `channels.whatsapp.allowFrom` (強く推奨) *** *次は: [グループメッセージ](/channels/group-messages)* 🦞 # エージェントループ Source: https://openclawdoc.org/concepts/agent-loop エージェントループは、エージェントの完全な「実際の」実行プロセスです。インテーク（入力受付） → コンテキストのアセンブリ → モデル推論 → ツールの実行 → ストリーミング応答 → 永続化という一連の流れを指します。 エージェントループは、エージェントの完全な「実際の」実行プロセスです。インテーク（入力受付） → コンテキストのアセンブリ → モデル推論 → ツールの実行 → ストリーミング応答 → 永続化という一連の流れを指します。これは、セッション状態の一貫性を保ちながら、メッセージをアクションと最終的な応答に変換するための正式なパスです。 OpenClaw では、ループはセッションごとに単一のシリアル化された実行として行われ、モデルが思考し、ツールを呼び出し、出力をストリーミングする過程で、ライフサイクルイベントとストリームイベントを発行します。このドキュメントでは、このループがエンドツーエンドでどのように構成されているかを説明します。 ## エントリポイント * ゲートウェイ RPC: `agent` および `agent.wait` * CLI: `agent` コマンド ## 仕組み (概要) 1. `agent` RPC はパラメータを検証し、セッション (sessionKey/sessionId) を解決し、セッションメタデータを永続化し、すぐに `{ runId, acceptedAt }` を返します。 2. `agentCommand` はエージェントを実行します。 * モデルおよび思考プロセス/詳細出力（verbose）のデフォルト設定を解決します。 * スキルのスナップショットをロードします。 * `runEmbeddedPiAgent` を呼び出す (pi-agent-core ランタイム)。 * 埋め込みループがライフサイクル終了/エラーを発行しない場合は、**ライフサイクル終了/エラー**を発行します。 3. `runEmbeddedPiAgent`: * セッションごとおよびグローバルのキューを介して実行をシリアル化します。 * モデルおよび認証プロファイルを解決し、pi セッションを構築します。 * pi イベントを購読し、アシスタント/ツールの差分（デルタ）をストリーミングします。 * タイムアウトを監視し、超過した場合は実行を中止します。 * ペイロードおよび使用状況メタデータを返します。 4. `subscribeEmbeddedPiSession` は、pi-agent-core のイベントを OpenClaw の `agent` ストリームへと橋渡しします。 * ツールイベント => `stream: "tool"` * アシスタントの差分 => `stream: "assistant"` * ライフサイクルイベント => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` は `waitForAgentJob` を使用します。 * 指定された `runId` の **ライフサイクル終了/エラー**を待ちます。 * `{ status: ok|error|timeout, startedAt, endedAt, error? }` を返します。 ## キュー + 同時実行 * 実行はセッションキー (セッションレーン) ごとにシリアル化され、オプションでグローバルレーンを通じてもシリアル化されます。 * これにより、ツールやセッションの競合が防止され、セッション履歴の一貫性が維持されます。 * メッセージングチャネルは、このレーンシステムに供給されるキューモード (collect/steer/followup) を選択できます。詳細は [コマンドキュー](/concepts/queue) を参照してください。 ## セッション + ワークスペースの準備 * ワークスペースが解決・作成されます。サンドボックス化された実行は、サンドボックスワークスペースのルートにリダイレクトされる場合があります。 * スキルがロードされ（またはスナップショットから再利用され）、環境変数とプロンプトに挿入されます。 * ブートストラップ/コンテキストファイルが解決され、システムプロンプトのレポートに挿入されます。 * セッションの書き込みロックが取得されます。`SessionManager` がストリーミング前に開かれ、準備されます。 ## プロンプトアセンブリ + システムプロンプト * システムプロンプトは、OpenClaw のベースプロンプト、スキルプロンプト、ブートストラップコンテキスト、および実行ごとのオーバーライドから構築されます。 * モデル固有の制限と、コンパクション（圧縮）予約トークンが適用されます。 * モデルが認識する内容の詳細については、[システムプロンプト](/concepts/system-prompt) を参照してください。 ## フックポイント (インターセプト可能な場所) OpenClaw には 2 つのフックシステムがあります。 * **内部フック** (ゲートウェイフック): コマンドおよびライフサイクルイベント用のイベント駆動型スクリプト。 * **プラグインフック**: エージェント/ツールのライフサイクルおよびゲートウェイパイプライン内の拡張ポイント。 ### 内部フック (ゲートウェイフック) * **`agent:bootstrap`**: システムプロンプトが確定する前に、ブートストラップファイルを構築している最中に実行されます。これを使用して、ブートストラップコンテキストファイルを追加または削除します。 * **コマンドフック**: `/new`、`/reset`、`/stop`、およびその他のコマンドイベント (詳細はフックのドキュメントを参照)。 設定と例については、[フック](/automation/hooks) を参照してください。 ### プラグインフック (エージェント + ゲートウェイのライフサイクル) これらはエージェントループまたはゲートウェイパイプライン内で実行されます。 * **`before_model_resolve`**: セッション開始前（`messages` なし）に実行され、モデル解決前にプロバイダー/モデルを決定的にオーバーライドします。 * **`before_prompt_build`**: セッションロード後（`messages` あり）に実行され、プロンプトの送信前に `prependContext`、`systemPrompt`、`prependSystemContext`、または `appendSystemContext` を挿入します。ターンごとの動的なテキストには `prependContext` を使用し、システムプロンプト領域に配置すべき安定したガイダンスにはシステムコンテキストフィールドを使用します。 * **`before_agent_start`**: どちらのフェーズでも実行される可能性があるレガシー互換フック。上記の明示的なフックを使用することをお勧めします。 * **`agent_end`**: 完了後に最終メッセージリストと実行メタデータを検査します。 * **`before_compaction` / `after_compaction`**: コンパクションサイクルを監視または注釈を付けます。 * **`before_tool_call` / `after_tool_call`**: ツールのパラメータや結果をインターセプトします。 * **`tool_result_persist`**: ツールの結果をセッショントランスクリプトに書き込む前に同期的に変換します。 * **`message_received` / `message_sending` / `message_sent`**: 受信および送信メッセージのフック。 * **`session_start` / `session_end`**: セッションのライフサイクル境界。 * **`gateway_start` / `gateway_stop`**: ゲートウェイのライフサイクルイベント。 フック API と登録の詳細については、[プラグイン](/tools/plugin#plugin-hooks) を参照してください。 ## ストリーミング + 部分的な返信 * アシスタントの差分は pi-agent-core からストリーミングされ、`assistant` イベントとして発行されます。 * ブロックストリーミングは、`text_end` または `message_end` のいずれかのタイミングで部分的な応答を送信できます。 * 推論（Reasoning）ストリーミングは、別個のストリームまたはブロック応答として送信できます。 * チャンク化とブロック応答の動作については、[ストリーミング](/concepts/streaming) を参照してください。 ## ツール実行 + メッセージングツール * ツールの開始/更新/終了イベントは、`tool` ストリームで発行されます。 * ツールの結果は、記録や出力の前に、サイズ制限や画像ペイロードに関してサニタイズされます。 * メッセージングツールの送信は追跡され、重複したアシスタントの確認メッセージが抑制されます。 ## 応答整形 + 抑制 * 最終的なペイロードは以下から組み立てられます。 * アシスタントのテキスト (およびオプションの推論) * インラインツールの概要 (詳細出力が許可されている場合) * モデルエラー時のアシスタントエラーテキスト * `NO_REPLY` はサイレントトークンとして扱われ、送信ペイロードから除外されます。 * メッセージングツールの重複は、最終的なペイロードリストから削除されます。 * 表示可能なペイロードが残っておらず、ツールでエラーが発生した場合、フォールバックとしてツールのエラー応答が発行されます（メッセージングツールがすでにユーザーに見える応答を送信している場合を除く）。 ## 圧縮 + 再試行 * 自動圧縮（コンパクション）は `compaction` ストリームイベントを発行し、再試行をトリガーする場合があります。 * 再試行時には、出力の重複を避けるためにメモリ内のバッファとツールの概要がリセットされます。 * 詳細は [圧縮（コンパクション）](/concepts/compaction) を参照してください。 ## イベントストリーム (現在) * `lifecycle`: `subscribeEmbeddedPiSession` によって発行されます (および `agentCommand` によるフォールバックとして) * `assistant`: pi-agent-core からストリーミングされたデルタ * `tool`: pi-agent-core からストリーミングされたツールイベント ## チャットチャネルの処理 * アシスタントの差分はチャットの `delta` メッセージにバッファリングされます。 * **ライフサイクル終了/エラー**時にチャットの `final` イベントが生成されます。 ## タイムアウト * `agent.wait` デフォルト: 30 秒 (待機のみ)。 `timeoutMs` パラメータでオーバーライド可能です。 * エージェントランタイム: `agents.defaults.timeoutSeconds` デフォルトは 600 秒。 `runEmbeddedPiAgent` の中止タイマーで強制されます。 ## 早期終了の可能性があるケース * エージェントのタイムアウト (中止) * AbortSignal (キャンセル) * ゲートウェイの切断または RPC タイムアウト * `agent.wait` タイムアウト (待機のみ、エージェント自体は停止しません) # エージェントワークスペース Source: https://openclawdoc.org/concepts/agent-workspace ワークスペースはエージェントの活動拠点です。ファイル操作ツールやワークスペースコンテキストに使用される唯一の作業ディレクトリです。プライベートな空間として扱い、エージェントの「記憶」の一部として管理してください。 ワークスペースはエージェントの活動拠点です。ファイル操作ツールやワークスペースコンテキストに使用される唯一の作業ディレクトリです。プライベートな空間として扱い、エージェントの「記憶」の一部として管理してください。 これは、構成、認証情報、およびセッションを保存する `~/.openclaw/` とは別に管理されます。 **重要:** ワークスペースは**デフォルトの作業ディレクトリ (cwd)** であり、厳密なサンドボックスではありません。ツールはワークスペースを基準に相対パスを解決しますが、サンドボックスが有効でない限り、絶対パスを使用してホスト上の他の場所にアクセスできてしまいます。隔離が必要な場合は、[`agents.defaults.sandbox`](/gateway/sandboxing)（およびエージェントごとのサンドボックス構成）を使用してください。 サンドボックスが有効で、かつ `workspaceAccess` が `"rw"` 以外に設定されている場合、ツールはホスト上のワークスペースではなく、`~/.openclaw/sandboxes` 配下のサンドボックス用ワークスペース内で動作します。 ## デフォルトの場所 * デフォルト: `~/.openclaw/workspace` * `OPENCLAW_PROFILE` が設定されており、かつ `"default"` 以外の場合、デフォルトは `~/.openclaw/workspace-` になります。 * `~/.openclaw/openclaw.json` で上書き可能です: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agent: { workspace: "~/.openclaw/workspace", }, } ``` `openclaw onboard`、`openclaw configure`、または `openclaw setup` を実行すると、ワークスペースが作成され、ブートストラップファイル（初期ファイル群）が不足している場合は生成されます。 サンドボックスへの初期ファイルのコピーでは、通常のワークスペース内ファイルのみが対象となります。ワークスペース外を指すシンボリックリンクやハードリンクは無視されます。 ワークスペースファイルを自身で完全に管理している場合は、ブートストラップファイルの自動生成を無効にできます: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agent: { skipBootstrap: true } } ``` ## 余分なワークスペースフォルダについて 古いインストール環境では `~/openclaw` が作成されている場合があります。複数のワークスペースディレクトリが存在すると、認証や状態の不一致を招き混乱の原因となるため（一度にアクティブにできるワークスペースは 1 つだけです）、整理することを推奨します。 **推奨:** アクティブなワークスペースを 1 つに絞ってください。不要になった古いフォルダは、アーカイブするかゴミ箱（例: `trash ~/openclaw`）へ移動してください。 意図的に複数のワークスペースを使い分ける場合は、`agents.defaults.workspace` が常に正しい（現在使用したい）場所を指していることを確認してください。 `openclaw doctor` は、余分なワークスペースディレクトリを検出した場合に警告を表示します。 ## ワークスペース内のファイルマップ OpenClaw がワークスペース内で期待する標準的なファイルは以下の通りです: * `AGENTS.md` * エージェントの動作指示と、メモリの使用方法。 * すべてのセッション開始時にロードされます。 * ルール、優先順位、「どのように振る舞うべきか」の詳細を記述するのに適しています。 * `SOUL.md` * ペルソナ（人格）、トーン、および境界線（守るべきルール）。 * セッションごとにロードされます。 * `USER.md` * ユーザーが誰であるか、およびユーザーへの適切な呼びかけ方。 * セッションごとにロードされます。 * `IDENTITY.md` * エージェントの名前、雰囲気、および絵文字。 * セットアップ儀式中に作成または更新されます。 * `TOOLS.md` * ローカルツールや慣習に関するメモ。 * ツール自体の有効・無効を制御するものではなく、エージェントへの「ガイドライン」として機能します。 * `HEARTBEAT.md` * ハートビート実行時にエージェントが確認する、オプションの小さなチェックリスト。 * トークンの消費を抑えるため、内容は短く保ってください。 * `BOOT.md` * ゲートウェイ再起動時（内部フック有効時）に実行されるオプションの起動チェックリスト。 * 内容は短く保ち、外部への送信にはメッセージツールを使用してください。 * `BOOTSTRAP.md` * 初回実行時に一度だけ行われる「儀式」用のファイル。 * 新規ワークスペース作成時のみ生成されます。 * 儀式が完了したら削除してください。 * `memory/YYYY-MM-DD.md` * 日ごとの記憶ログ（1 日 1 ファイル）。 * セッション開始時に、今日と昨日のファイルを読み込むことが推奨されます。 * `MEMORY.md` (オプション) * 整理された長期記憶。 * プライベートなメインセッションでのみロードされます（共有チャネルやグループチャットではロードされません）。 ワークフローやメモリの自動保存については、[記憶 (Memory)](/concepts/memory) を参照してください。 * `skills/` (オプション) * ワークスペース固有のスキル。 * 同名の管理済みスキルや同梱スキルがある場合、ここにあるものが優先されます。 * `canvas/` (オプション) * ノードのディスプレイに表示するための Canvas UI 用ファイル（例: `canvas/index.html`）。 ブートストラップファイルが欠落している場合、OpenClaw はセッションに「欠落」マーカーを注入して処理を続行します。巨大なファイルは注入時に切り詰められます。制限値は `agents.defaults.bootstrapMaxChars`（デフォルト 20,000）および `agents.defaults.bootstrapTotalMaxChars`（デフォルト 150,000）で調整可能です。 `openclaw setup` を実行すると、既存のファイルを上書きせずに、不足しているデフォルトファイルを再作成できます。 ## ワークスペースに含まれないもの 以下のファイルは `~/.openclaw/` 配下にあり、ワークスペースのリポジトリには\*\*含めない（コミットしない）\*\*でください: * `~/.openclaw/openclaw.json` (構成設定) * `~/.openclaw/credentials/` (OAuth トークン、API キー) * `~/.openclaw/agents//sessions/` (会話履歴およびメタデータ) * `~/.openclaw/skills/` (管理済みのスキル) セッションや構成を移行する必要がある場合は、これらを個別にコピーし、バージョン管理の対象外として扱ってください。 ## Git によるバックアップ (推奨、プライベート) ワークスペースは「プライベートな記憶」として扱ってください。バックアップと復元を容易にするため、**プライベートな** Git リポジトリで管理することを推奨します。 以下の手順は、ゲートウェイ（ワークスペースが存在するマシン）上で実行してください。 ### 1) リポジトリの初期化 Git がインストールされていれば、新規ワークスペース作成時に自動的に初期化されます。まだリポジトリになっていない場合は、以下を実行してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} cd ~/.openclaw/workspace git init git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/ git commit -m "エージェントワークスペースを追加" ``` ### 2) プライベートなリモートリポジトリの追加 OpenClaw ユーザーに適した一般的な方法を紹介します。 **方法 A: GitHub ウェブ UI を使用する場合** 1. GitHub 上で新しい **Private** リポジトリを作成します。 2. 初期化オプション（README の作成など）はすべてオフにします（競合を避けるため）。 3. HTTPS のリモート URL をコピーします。 4. 以下のコマンドでリモートを追加し、プッシュします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} git branch -M main git remote add origin <コピーしたURL> git push -u origin main ``` **方法 B: GitHub CLI (`gh`) を使用する場合** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gh auth login gh repo create openclaw-workspace --private --source . --remote origin --push ``` ### 3) 日々の更新 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} git status git add . git commit -m "記憶を更新" git push ``` ## シークレット（機密情報）をコミットしないでください プライベートリポジトリであっても、以下の機密情報をワークスペースに保存することは避けてください: * API キー、OAuth トークン、パスワード、または個人用認証情報。 * `~/.openclaw/` 配下にあるすべてのもの。 * チャット履歴の生データや、機密性の高い添付ファイル。 機密情報の参照を記述する必要がある場合は、プレースホルダーを使用し、実際の内容は他の安全な場所（パスワードマネージャー、環境変数、または `~/.openclaw/`）に保管してください。 推奨される `.gitignore` の内容: ```gitignore theme={"theme":{"light":"min-light","dark":"min-dark"}} .DS_Store .env **/*.key **/*.pem **/secrets* ``` ## ワークスペースを新しいマシンに移動する 1. 新しいマシンの目的のパス（デフォルトは `~/.openclaw/workspace`）にリポジトリをクローンします。 2. `~/.openclaw/openclaw.json` 内の `agents.defaults.workspace` にそのパスを設定します。 3. `openclaw setup --workspace <パス>` を実行し、不足しているファイルを生成します。 4. 会話セッションが必要な場合は、古いマシンから `~/.openclaw/agents//sessions/` を個別にコピーしてください。 ## 高度な補足事項 * マルチエージェントルーティングでは、エージェントごとに異なるワークスペースを使用できます。詳細は [チャネルルーティング](/channels/channel-routing) を参照してください。 * `agents.defaults.sandbox` が有効な場合、メイン以外のセッションでは `agents.defaults.sandbox.workspaceRoot` 配下にあるセッションごとのサンドボックスワークスペースを使用することがあります。 # ゲートウェイアーキテクチャ Source: https://openclawdoc.org/concepts/architecture 単一の常駐プロセスである ゲートウェイ が、すべてのメッセージングインターフェース（Baileys による WhatsApp、grammY による Telegram、Slack、Discord、Signal、iMessage、WebChat）を管理します。 最終更新日: 2026-01-22 ## 概要 * 単一の常駐プロセスである **ゲートウェイ** が、すべてのメッセージングインターフェース（Baileys による WhatsApp、grammY による Telegram、Slack、Discord、Signal、iMessage、WebChat）を管理します。 * コントロールプレーンクライアント（macOS アプリ、CLI、Web UI、自動化ツール）は、設定されたホストとポート（デフォルトは `127.0.0.1:18789`）で動作するゲートウェイに **WebSocket** 経由で接続します。 * **ノード** (macOS/iOS/Android/ヘッドレス) も同様に **WebSocket** で接続しますが、接続時に明示的な機能やコマンドと共に `role: node` を宣言します。 * 1 つのホストにつきゲートウェイは 1 つだけ実行されます。WhatsApp セッションを開始できるのはゲートウェイのみです。 * **キャンバスホスト**は、ゲートウェイと同じポート（デフォルト `18789`）を使用して、以下のパスで HTTP 配信されます: * `/__openclaw__/canvas/` (エージェントが編集可能な HTML/CSS/JS) * `/__openclaw__/a2ui/` (A2UI ホスト) ## コンポーネントとフロー ### ゲートウェイ (デーモン) * 各プロバイダーとの接続を維持します。 * 型定義された WebSocket API (リクエスト、レスポンス、サーバープッシュイベント) を提供します。 * 受信したフレームを JSON スキーマに照らして検証します。 * `agent`, `chat`, `presence`, `health`, `heartbeat`, `cron` などのイベントを発行します。 ### クライアント (mac アプリ / CLI / Web 管理画面) * クライアントごとに 1 つの WebSocket 接続を確立します。 * リクエスト (`health`, `status`, `send`, `agent`, `system-presence`) を送信します。 * イベント (`tick`, `agent`, `presence`, `shutdown`) を購読します。 ### ノード (macOS / iOS / Android / ヘッドレス) * **同じ WebSocket サーバー**に `role: node` として接続します。 * `connect` 時にデバイスのアイデンティティを提供します。ペアリングは **デバイスベース** (role `node`) で行われ、その承認情報はデバイスペアリングストアで管理されます。 * `canvas.*`, `camera.*`, `screen.record`, `location.get` などのコマンドを公開します。 プロトコルの詳細: * [ゲートウェイプロトコル](/gateway/protocol) ### WebChat * ゲートウェイの WebSocket API を使用して会話履歴の表示や送信を行う、静的な UI です。 * リモート環境では、他のクライアントと同様に SSH や Tailscale トンネルを介して接続します。 ## 接続ライフサイクル (単一クライアント) ```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}} sequenceDiagram participant Client participant Gateway Client->>Gateway: req:connect Gateway-->>Client: res (ok) Note right of Gateway: またはエラーレスポンス + 切断 Note left of Client: payload=hello-ok
snapshot: presence + health Gateway-->>Client: event:presence Gateway-->>Client: event:tick Client->>Gateway: req:agent Gateway-->>Client: res:agent
ack {runId, status:"accepted"} Gateway-->>Client: event:agent
(ストリーミング中) Gateway-->>Client: res:agent
final {runId, status, summary} ``` ## 通信プロトコル (サマリー) * トランスポート: WebSocket。JSON ペイロードを含むテキストフレームを使用します。 * 最初のフレームは**必ず** `connect` である必要があります。 * ハンドシェイク（接続確立）後: * リクエスト: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}` * イベント: `{type:"event", event, payload, seq?, stateVersion?}` * `OPENCLAW_GATEWAY_TOKEN` (または `--token`) が設定されている場合、`connect.params.auth.token` が一致しなければソケットは即座に閉じられます。 * 副作用を伴うメソッド (`send`, `agent`) では、安全に再試行を行うために冪等（べきとう）キーが必要です。サーバーは短期間の重複排除キャッシュを維持します。 * ノードは、`connect` 時に `role: "node"` に加え、利用可能な機能、コマンド、および権限を含める必要があります。 ## ペアリングとローカルの信頼 * すべての WebSocket クライアント（オペレーターおよびノード）は、`connect` 時に **デバイスアイデンティティ** を含めます。 * 新しいデバイス ID にはペアリングの承認が必要で、ゲートウェイはそれ以降の接続のために **デバイストークン** を発行します。 * **ローカル**な接続（ループバックアドレス、またはゲートウェイホスト自身の Tailscale アドレス）は、同一ホスト内での利便性を保つため、自動的に承認される場合があります。 * すべての接続において、`connect.challenge` ノンスへの署名が必要です。 * 署名ペイロード `v3` では、`platform` (プラットフォーム) と `deviceFamily` (デバイスファミリー) も紐付けられます。ゲートウェイは再接続時にペアリング済みのメタデータを固定し、メタデータに変更があった場合にはペアリングの再実行（修復）を求めます。 * **ローカル以外**からの接続には、引き続き明示的な承認が必要です。 * ゲートウェイ認証 (`gateway.auth.*`) は、ローカルかリモートかを問わず、**すべての**接続に適用されます。 詳細: [ゲートウェイプロトコル](/gateway/protocol), [ペアリング](/channels/pairing), [セキュリティ](/gateway/security) ## プロトコルの型定義とコード生成 * プロトコルは TypeBox スキーマによって定義されています。 * これらのスキーマから JSON スキーマが生成されます。 * 生成された JSON スキーマから Swift のモデルが作成されます。 ## リモートアクセス * 推奨される方法: Tailscale または VPN。 * 代替案: SSH トンネル ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh -N -L 18789:127.0.0.1:18789 user@host ``` * トンネル越しでも、同じハンドシェイクと認証トークンが適用されます。 * リモート設定では、WebSocket に対して TLS 設定やオプションのピン留めを有効にできます。 ## 運用のスナップショット * 起動: `openclaw gateway` (フォアグラウンド実行。ログは標準出力に出力されます)。 * ヘルスチェック: WebSocket 経由の `health` リクエスト (または `hello-ok` レスポンスに含まれる情報)。 * プロセス監視: 自動再起動のために launchd または systemd を使用します。 ## 不変のルール * ホストごとに単一のゲートウェイが、単一の Baileys (WhatsApp) セッションを管理します。 * ハンドシェイクは必須です。最初のフレームが有効な JSON でない、あるいは `connect` でない場合は強制的に切断されます。 * イベントの再送（リプレイ）は行われません。通信に欠落が生じた場合、クライアント側で情報を再取得する必要があります。 # 圧縮（コンパクション） Source: https://openclawdoc.org/concepts/compaction すべての LLM モデルには コンテキストウィンドウ（一度に認識できる最大トークン数）があります。圧縮（コンパクション）とは、構成設定、自動圧縮 (デフォルトで有効)を確認できます。 すべての LLM モデルには **コンテキストウィンドウ**（一度に認識できる最大トークン数）があります。長時間にわたるチャットではメッセージやツールの実行結果が蓄積されていきますが、ウィンドウの空きが少なくなると、OpenClaw は制限内に収めるために古い履歴を **圧縮（コンパクション）** します。 ## 圧縮（コンパクション）とは 圧縮とは、**古い会話内容を短い要約エントリにまとめる** 操作です。これにより、最近のメッセージはそのまま維持しつつ、過去の文脈も要約として残すことができます。要約はセッションの履歴に保存されるため、以降のリクエストでは以下の内容がモデルに送信されます: * 圧縮された要約（サマリー） * 圧縮ポイント以降の新しいメッセージ 圧縮結果はセッションの JSONL 形式の履歴ファイルに **永続化** されます。 ## 構成設定 `openclaw.json` の `agents.defaults.compaction` 設定を使用して、圧縮の動作（モード、目標トークン数など）をカスタマイズできます。 圧縮時の要約処理では、デフォルトで ID などの固有識別子が厳格に保持されます（`identifierPolicy: "strict"`）。これを `off` にしたり、`custom` を選択して `identifierInstructions` で独自の指示を与えたりすることも可能です。 また、`agents.defaults.compaction.model` を使用して、要約処理専用に別のモデルを指定することも可能です。これは、メインで使用しているモデルがローカルモデルや小規模なもので、要約の品質を上げるためにより高性能なモデルを使いたい場合に有用です。この設定は `provider/model-id` 形式の文字列を受け入れます: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "agents": { "defaults": { "compaction": { "model": "openrouter/anthropic/claude-sonnet-4-5" } } } } ``` これはローカルモデルでも機能します。例えば、要約専用の別の Ollama モデルや、要約に特化して微調整されたモデルを指定できます: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "agents": { "defaults": { "compaction": { "model": "ollama/llama3.1:8b" } } } } ``` 未設定の場合、圧縮にはそのエージェントのメインモデルが使用されます。 ## 自動圧縮 (デフォルトで有効) セッションがモデルのコンテキストウィンドウの限界に近づくか超過すると、OpenClaw は自動的に圧縮を実行し、圧縮後のコンテキストを使用して元のリクエストを再試行する場合があります。 自動圧縮が行われると、以下の情報を確認できます: * 詳細モード（verbose）でのログ: `🧹 Auto-compaction complete` * `/status` コマンドでの表示: `🧹 Compactions: <回数>` 圧縮の直前に、OpenClaw は **サイレントなメモリフラッシュ** ターンを実行し、重要な情報を永続的なメモとしてディスクに保存することができます。詳細は [記憶 (Memory)](/concepts/memory) を参照してください。 ## 手動圧縮 `/compact` コマンド（オプションで指示を追加可能）を使用して、強制的に圧縮を実行できます: ``` /compact 決定事項と未解決の課題に焦点を当てて要約してください。 ``` ## コンテキストウィンドウのソース コンテキストウィンドウのサイズはモデルごとに異なります。OpenClaw は、構成されたプロバイダーカタログ内のモデル定義を使用して制限値を判断します。 ## 圧縮（Compaction）とプルーニング（Pruning）の違い * **圧縮（Compaction）**: 古い履歴を要約し、JSONL ファイルに **永続化** します。 * **セッションプルーニング（Session Pruning）**: 古い **ツールの実行結果** のみを、リクエストごとに **メモリ上（一時的）** でトリミングします。 プルーニングの詳細は [/concepts/session-pruning](/concepts/session-pruning) を参照してください。 ## OpenAI サーバーサイド圧縮 OpenClaw は、対応している直接接続の OpenAI モデルにおいて、OpenAI Responses のサーバーサイド圧縮ヒントもサポートしています。これは OpenClaw ローカルの圧縮とは別物であり、併用が可能です。 * **ローカル圧縮**: OpenClaw が要約を作成し、セッションの JSONL に保存します。 * **サーバーサイド圧縮**: `store` と `context_management` が有効な場合、OpenAI のプロバイダー側でコンテキストが圧縮されます。 モデルパラメータや上書き設定については [OpenAI プロバイダー](/providers/openai) を参照してください。 ## ヒント * 会話が噛み合わなくなったり、コンテキストが肥大化してきたと感じたら `/compact` を使用してください。 * 巨大なツールの出力はすでに自動で切り詰められていますが、プルーニング設定を調整することでツール結果の蓄積をさらに抑えることができます。 * 完全に履歴をリセットして新しく始めたい場合は、`/new` または `/reset` を使用して新しいセッション ID を開始してください。 # コンテキスト Source: https://openclawdoc.org/concepts/context 「コンテキスト」とは、OpenClaw が 1 回の実行（ターン）のためにモデルに送信する情報のすべて を指します。これはモデル固有の コンテキストウィンドウ（トークン制限）によって上限が決まります。 「コンテキスト」とは、**OpenClaw が 1 回の実行（ターン）のためにモデルに送信する情報のすべて** を指します。これはモデル固有の **コンテキストウィンドウ**（トークン制限）によって上限が決まります。 基本的なイメージ: * **システムプロンプト** (OpenClaw が生成): ルール、利用可能なツール、スキル一覧、現在時刻/環境情報、および注入されたワークスペースファイル。 * **会話履歴**: そのセッションにおけるユーザーとアシスタントのメッセージ。 * **ツール呼び出しと結果 + 添付ファイル**: コマンドの出力、ファイルの読み取り内容、画像や音声データなど。 コンテキストは「記憶（メモ）」とは*異なります*。記憶はディスクに保存され、後で再ロードされるものですが、コンテキストはモデルの現在の「視界」に入っている情報を指します。 ## クイックスタート (コンテキストの検査) * `/status` → ウィンドウの埋まり具合とセッション設定を素早く確認。 * `/context list` → 注入されている内容とおおよそのサイズ（ファイルごとおよび合計）を確認。 * `/context detail` → さらに詳細な内訳（ファイルごと、ツールごとのスキーマサイズ、スキルごとのエントリサイズ、システムプロンプトのサイズ）を確認。 * `/usage tokens` → 通常の返信の末尾に、その回のトークン利用状況を付加。 * `/compact` → ウィンドウの空きを増やすため、古い履歴を要約エントリに圧縮。 関連ドキュメント: [スラッシュコマンド](/tools/slash-commands), [トークン利用とコスト](/reference/token-use), [圧縮（コンパクション）](/concepts/compaction) ## 出力例 値はモデル、プロバイダー、ツールポリシー、およびワークスペースの内容によって異なります。 ### `/context list` ``` 🧠 Context breakdown Workspace: Bootstrap max/file: 20,000 chars Sandbox: mode=non-main sandboxed=false System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) Injected workspace files: - AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) - SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok) - TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) - IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok) - USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok) - HEARTBEAT.md: MISSING | raw 0 | injected 0 - BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills) Tools: read, edit, write, exec, process, browser, message, sessions_send, … Tool list (system prompt text): 1,032 chars (~258 tok) Tool schemas (JSON): 31,988 chars (~7,997 tok) (コンテキストとしてカウントされますが、テキストとしては表示されません) Tools: (上記と同じ) Session tokens (cached): 14,250 total / ctx=32,000 ``` ### `/context detail` ``` 🧠 Context breakdown (detailed) … Top skills (prompt entry size): - frontend-design: 412 chars (~103 tok) - oracle: 401 chars (~101 tok) … (+10 more skills) Top tools (schema size): - browser: 9,812 chars (~2,453 tok) - exec: 6,240 chars (~1,560 tok) … (+N more tools) ``` ## コンテキストウィンドウとしてカウントされるもの モデルが受信するすべての情報がカウント対象です: * システムプロンプト（すべてのセクション） * 会話履歴 * ツールの呼び出し内容と実行結果 * 添付ファイルやトランスクリプト（画像、音声、ドキュメントなど） * 圧縮（コンパクション）時の要約やプルーニングの痕跡 * プロバイダーによる「ラッパー」や隠しヘッダー（表示されませんが、カウントされます） ## OpenClaw によるシステムプロンプトの構築 システムプロンプトは **OpenClaw が管理** し、実行ごとに再構築されます。これには以下の内容が含まれます: * ツール一覧と短い説明 * スキル一覧（メタデータのみ。詳細は後述） * ワークスペースの場所 * 現在時刻（UTC、および設定されていればユーザー時刻に変換されたもの） * 実行時のメタデータ（ホスト、OS、モデル、思考設定） * **Project Context** として注入されたワークスペースの初期化ファイル 詳細な内訳: [システムプロンプト](/concepts/system-prompt) ## 注入されるワークスペースファイル (Project Context) デフォルトでは、OpenClaw は以下のワークスペースファイルが存在すれば注入します: * `AGENTS.md` * `SOUL.md` * `TOOLS.md` * `IDENTITY.md` * `USER.md` * `HEARTBEAT.md` * `BOOTSTRAP.md` (初回実行時のみ) 巨大なファイルは、`agents.defaults.bootstrapMaxChars`（デフォルト 20,000 文字）によってファイルごとに切り詰められます。また、すべてのファイルを合わせた合計注入量の上限として `agents.defaults.bootstrapTotalMaxChars`（デフォルト 150,000 文字）が適用されます。`/context` コマンドで、**生のサイズ vs 注入されたサイズ** と、切り詰めが発生したかどうかを確認できます。 切り詰めが発生した場合、システムプロンプトの Project Context セクションに警告ブロックが注入されます。この振る舞いは `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`。デフォルトは `once`) で設定可能です。 ## スキル: 注入されるもの vs オンデマンドでロードされるもの システムプロンプトには、スキルの名前、説明、場所を含むコンパクトな **スキル一覧** が含まれます。この一覧自体が一定のコンテキストを消費します。 スキルの詳細な指示内容は、デフォルトでは**含まれません**。モデルは **必要なときにだけ** スキルの `SKILL.md` を `read` して内容を確認するよう指示されています。 ## ツールの 2 つのコスト ツールは 2 つの形でコンテキストに影響を与えます: 1. システムプロンプト内の **ツール一覧テキスト** (「Tooling」として表示される部分)。 2. **ツールスキーマ** (JSON 形式)。これはモデルがツールを呼び出せるように送信されるデータです。プレーンテキストとしては表示されませんが、コンテキストウィンドウを消費します。 `/context detail` を使用すると、どのツールスキーマがコンテキストを多く消費しているかを確認できます。 ## コマンド、ディレクティブ、およびインラインショートカット スラッシュコマンドはゲートウェイによって処理されます。振る舞いにはいくつかの種類があります: * **スタンドアロンコマンド**: メッセージが `/...` のみの場合は、コマンドとして実行されます。 * **ディレクティブ**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` は、モデルに渡される前にメッセージから除去されます。 * ディレクティブのみのメッセージは、セッション設定を永続的に変更します。 * 通常のメッセージ内に含まれるディレクティブは、その回限りのヒントとして機能します。 * **インラインショートカット** (許可された送信者のみ): 通常のメッセージ内に含まれる特定の `/...` トークン（例: 「ねえ /status」）は即座に実行され、残りのテキストがモデルに渡される前に除去されます。 詳細は [スラッシュコマンド](/tools/slash-commands) を参照してください。 ## セッション、圧縮、およびプルーニング（何が残るか） メッセージをまたいで何が保持されるかは、その仕組みによります: * **通常の履歴**: 構成ポリシーによって圧縮・削除されるまで、セッション記録に残り続けます。 * **圧縮（Compaction）**: 古い履歴を要約し、記録（トランスクリプト）に保存します。最近のメッセージはそのまま保持されます。 * **プルーニング（Pruning）**: その回の実行のために、**メモリ上の** プロンプトから古いツール結果を削除します。記録（トランスクリプト）自体は書き換えません。 ドキュメント: [セッション](/concepts/session), [圧縮（コンパクション）](/concepts/compaction), [セッションプルーニング](/concepts/session-pruning) デフォルトでは、OpenClaw は組み込みの `legacy` コンテキストエンジンを使用して組み立てと圧縮を行います。`kind: "context-engine"` を提供するプラグインをインストールし、`plugins.slots.contextEngine` でそれを選択した場合、コンテキストの組み立て、`/compact`、および関連するサブエージェントのコンテキスト処理はそのプラグインに委任されます。 ## `/context` が報告する情報のソース `/context` は、利用可能な場合は最新の **実行時に構築された** システムプロンプトレポートを優先的に表示します: * `System prompt (run)` = 最後に埋め込みランタイム（ツール利用可能な状態）で実行された際にキャプチャされ、セッションストアに保存された内容。 * `System prompt (estimate)` = 実行レポートが存在しない場合（またはレポートを生成しない CLI バックエンド経由で実行している場合）に、その場で計算された推定値。 いずれの場合も、サイズと上位の消費要因を報告します。システムプロンプトの全文やツールスキーマの生データを出力（ダンプ）することはありません。 # 機能一覧 Source: https://openclawdoc.org/concepts/features WhatsApp, Telegram, Discord, iMessage を 1 つのゲートウェイで統合管理。拡張機能を使用して Mattermost などのチャネルを自由に追加。分離されたセッションによる高度なマルチエージェントルーティング。 ## ハイライト WhatsApp, Telegram, Discord, iMessage を 1 つのゲートウェイで統合管理。 拡張機能を使用して Mattermost などのチャネルを自由に追加。 分離されたセッションによる高度なマルチエージェントルーティング。 画像、音声、ドキュメントの送受信と解析に対応。 ウェブベースのコントロール UI と macOS 用コンパニオンアプリ。 iOS/Android ノードとのペアリング、音声/チャット、豊富なデバイスコマンド。 ## 全機能リスト * **チャネル連携**: WhatsApp Web (Baileys), Telegram (grammY), Discord (discord.js), iMessage (imsg CLI) を標準サポート。 * **拡張性**: プラグインによるチャネル追加（Mattermost 等）。 * **エージェントブリッジ**: RPC モードによる Pi (pi-mono) 連携とツールストリーミング。 * **ストリーミング**: 長い応答をリアルタイムで送信するストリーミングとチャンク化。 * **マルチエージェント**: ワークスペースや送信者ごとに分離されたセッションルーティング。 * **サブスクリプション認証**: OAuth 経由の Anthropic および OpenAI 認証。 * **セッション管理**: ダイレクトチャットは `main` セッションへ集約、グループチャットは個別に分離。 * **グループチャット**: メンション（言及）ベースの応答トリガー。 * **メディア対応**: 画像、音声、ドキュメントの双方向サポート。 * **音声メモ**: オプションの音声メッセージ書き起こしフック。 * **ユーザーインターフェース**: WebChat および macOS メニューバーアプリ。 * **iOS ノード**: ペアリング、Canvas、カメラ、画面収録、位置情報、音声通信。 * **Android ノード**: ペアリング、接続タブ、チャットセッション、音声タブ、Canvas/カメラ、およびデバイス制御（通知、連絡先、カレンダー、センサー、写真、SMS）。 レガシーな Claude, Codex, Gemini, Opencode パスは削除されました。現在は Pi が唯一のコーディングエージェントパスです。 # 記憶 (Memory) Source: https://openclawdoc.org/concepts/memory OpenClaw の記憶は、エージェントのワークスペース内にあるプレーンな Markdown ファイル です。ファイルが「真実のソース」であり、モデルはディスクに書き込まれた内容のみを「記憶」として保持し続けます。 OpenClaw の記憶は、**エージェントのワークスペース内にあるプレーンな Markdown ファイル** です。ファイルが「真実のソース」であり、モデルはディスクに書き込まれた内容のみを「記憶」として保持し続けます。 記憶検索ツールは、有効な記憶プラグイン（デフォルトは `memory-core`）によって提供されます。記憶機能を無効にする場合は、構成で `plugins.slots.memory = "none"` を設定してください。 ## 記憶ファイル (Markdown) デフォルトのワークスペース構成では、2 つの記憶レイヤーを使用します: * `memory/YYYY-MM-DD.md` * 日ごとのログ (追記専用)。 * セッション開始時に「今日」と「昨日」のファイルが読み込まれます。 * `MEMORY.md` (オプション) * 整理された長期記憶。 * **プライベートなメインセッションでのみロードされます**（グループチャットなどの共有コンテキストではロードされません）。 これらのファイルはワークスペース (`agents.defaults.workspace`、デフォルトは `~/.openclaw/workspace`) 配下に保存されます。詳細は [エージェントワークスペース](/concepts/agent-workspace) を参照してください。 ## 記憶ツール エージェント（モデル）向けに、以下の 2 つのツールが公開されています: * `memory_search`: インデックス化されたスニペットに対するセマンティック検索（意味ベースの検索）。 * `memory_get`: 特定の Markdown ファイルの指定した行範囲を直接読み取り。 `memory_get` は、**ファイルが存在しない場合でもエラーにならず適切に処理を継続** します（例：その日の最初の書き込みが行われる前の日次ログ）。組み込みのマネージャーおよび QMD バックエンドは、エラーを投げる代わりに `{ text: "", path }` を返すため、エージェントは「まだ何も記録されていない」ことを理解して処理を進めることができます。 ## いつ記憶に書き込むべきか * 決定事項、好み、不変の事実などは `MEMORY.md` へ。 * 日々のメモや進行中の文脈などは `memory/YYYY-MM-DD.md` へ。 * ユーザーが「これを覚えておいて」と言った内容は、RAM（メモリ上の一時記憶）に留めず、即座にファイルに書き留めてください。 * この分野はまだ進化の途上です。モデルに対して「記憶に保存して」と促すことで、モデルは適切に書き込み先を判断します。 * 重要な情報を確実に定着させたい場合は、**ボットに記憶へ書き込むよう明示的に依頼** してください。 ## 自動メモリフラッシュ (圧縮前の確認) セッションが **自動圧縮（コンパクション）のタイミングに近づくと**、OpenClaw はコンテキストが要約される **前に**、重要な情報を永続的な記憶として保存するようモデルに促す **サイレントな実行ターン** をトリガーします。デフォルトのプロンプトではモデルが返信を行う可能性がある旨が記載されていますが、通常は `NO_REPLY` が返されるため、ユーザーがこのターンを目にすることはありません。 この動作は `agents.defaults.compaction.memoryFlush` で制御されます: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { compaction: { reserveTokensFloor: 20000, memoryFlush: { enabled: true, softThresholdTokens: 4000, systemPrompt: "セッションが圧縮（コンパクション）に近づいています。永続化すべき記憶を今すぐ保存してください。", prompt: "重要なメモを memory/YYYY-MM-DD.md に書き込んでください。保存すべき内容がなければ NO_REPLY と返してください。", }, }, }, }, } ``` 補足: * **Soft threshold**: セッションの推定トークン数が `contextWindow - reserveTokensFloor - softThresholdTokens` を超えたときにフラッシュが発動します。 * **サイレント動作**: デフォルトのプロンプトに `NO_REPLY` に関する指示が含まれているため、ユーザーにメッセージは届きません。 * **2 つのプロンプト**: ユーザープロンプトとシステムプロンプトの両方でリマインダーが追加されます。 * **1 圧縮サイクルにつき 1 回**: このフラッシュ処理は `sessions.json` で追跡されます。 * **書き込み権限が必要**: セッションがサンドボックス内で動作し、`workspaceAccess` が `"ro"` (読み取り専用) または `"none"` の場合、フラッシュ処理はスキップされます。 圧縮のライフサイクル全体の詳細は、[セッション管理と圧縮](/reference/session-management-compaction) を参照してください。 ## ベクトル記憶検索 OpenClaw は `MEMORY.md` および `memory/*.md` に対して軽量なベクトルインデックスを構築できます。これにより、言葉の表現が異なっていても意味の近いメモを検索で見つけることが可能になります。 デフォルト設定: * デフォルトで有効。 * 記憶ファイルの変更を監視（デバウンス処理あり）。 * `agents.defaults.memorySearch` で設定します（トップレベルの `memorySearch` ではありません）。 * デフォルトでリモートの埋め込み（Embeddings）を使用します。`memorySearch.provider` が未設定の場合、OpenClaw は以下の順序で自動選択します: 1. `local`: `memorySearch.local.modelPath` が設定され、ファイルが存在する場合。 2. `openai`: OpenAI のキーが解決できる場合。 3. `gemini`: Gemini のキーが解決できる場合。 4. `voyage`: Voyage のキーが解決できる場合。 5. `mistral`: Mistral のキーが解決できる場合。 6. それ以外の場合は、設定が行われるまで記憶検索は無効化されます。 * ローカルモードは `node-llama-cpp` を使用し、環境によっては `pnpm approve-builds` が必要です。 * `sqlite-vec` (利用可能な場合) を使用して、SQLite 内でのベクトル検索を高速化します。 * `memorySearch.provider = "ollama"` による自前ホストの Ollama 埋め込み (`/api/embeddings`) もサポートしていますが、自動選択の対象外です。 リモート埋め込みを使用するには、プロバイダーの API キーが **必須** です。OpenClaw は、認証プロファイル、`models.providers.*.apiKey`、または環境変数からキーを取得します。注意点として、Codex の OAuth 認証はチャット/完了用であり、記憶検索用の埋め込みには **対応していません**。Gemini の場合は `GEMINI_API_KEY` または `models.providers.google.apiKey` を、Voyage は `VOYAGE_API_KEY` を、Mistral は `MISTRAL_API_KEY` を使用してください。Ollama は通常、実際のキーは不要です（ローカルポリシーで必要な場合は `OLLAMA_API_KEY=ollama-local` などのダミー値で十分です）。 独自の OpenAI 互換エンドポイントを使用する場合は、`memorySearch.remote.apiKey`（およびオプションで `memorySearch.remote.headers`）を設定してください。 ### QMD バックエンド (実験的) `memory.backend = "qmd"` を設定することで、組み込みの SQLite インデクサーから [QMD](https://github.com/tobi/qmd) に切り替えることができます。QMD は BM25、ベクトル検索、および再ランク付け（reranking）を組み合わせたローカル優先の検索エンジンです。Markdown ファイルが引き続き「真実のソース」であり、OpenClaw は情報の取得を QMD に委託します。 **前提条件:** * デフォルトでは無効。構成で `memory.backend = "qmd"` を指定して有効化します。 * QMD CLI を別途インストールし（`bun install -g https://github.com/tobi/qmd` など）、`qmd` バイナリにゲートウェイの `PATH` が通っている必要があります。 * QMD には、拡張機能を許可した SQLite ビルド（macOS なら `brew install sqlite`）が必要です。 * QMD は Bun と `node-llama-cpp` を介して完全にローカルで動作し、初回使用時に HuggingFace から GGUF モデルを自動ダウンロードします（別途 Ollama デーモンを起動する必要はありません）。 * ゲートウェイは、`XDG_CONFIG_HOME` と `XDG_CACHE_HOME` を設定することで、`~/.openclaw/agents//qmd/` 配下の独立した XDG ホーム環境で QMD を実行します。 * OS 対応: macOS と Linux では Bun と SQLite があればそのまま動作します。Windows は WSL2 経由での利用を推奨します。 **動作の仕組み:** * ゲートウェイは `~/.openclaw/agents//qmd/` 配下に QMD の設定・キャッシュ・DB を作成します。 * `memory.qmd.paths`（およびデフォルトのワークスペース記憶ファイル）からコレクションが作成され、起動時および設定された間隔（`memory.qmd.update.interval`、デフォルト 5 分）で `qmd update` と `qmd embed` が実行されます。 * ゲートウェイは起動時に QMD マネージャーを初期化するため、最初の検索が行われる前から定期更新タイマーが作動します。 * 起動時の同期処理はデフォルトでバックグラウンドで実行されるため、チャットの開始が待たされることはありません。以前のように同期完了を待ちたい場合は `memory.qmd.update.waitForBootSync = true` を設定してください。 * 検索は `memory.qmd.searchMode`（デフォルトは `search`。`vsearch` や `query` も指定可能）に従って実行されます。QMD が失敗したりバイナリが見つからない場合は、自動的に組み込みの SQLite マネージャーへフォールバックします。 * QMD の埋め込みバッチサイズ設定は、現在は OpenClaw からは露出されておらず、QMD 自身の制御に委ねられています。 * **初回検索は時間がかかる場合があります**: QMD は最初の `qmd query` 実行時にローカルの GGUF モデル（リランカーなど）をダウンロードすることがあるためです。 * モデルを事前に手動でダウンロードしておきたい場合は、エージェントの XDG ディレクトリ環境変数をエクスポートした状態で一度クエリを実行してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}" export XDG_CONFIG_HOME="$STATE_DIR/agents/main/qmd/xdg-config" export XDG_CACHE_HOME="$STATE_DIR/agents/main/qmd/xdg-cache" qmd update qmd embed qmd query "テスト" -c memory-root --json >/dev/null 2>&1 ``` **構成設定 (`memory.qmd.*`):** * `command` (デフォルト `qmd`): バイナリのパス。 * `searchMode`: 検索に使用するサブコマンド。 * `includeDefaultMemory`: ワークスペースの標準ファイルを自動インデックスするかどうか。 * `paths[]`: 追加のディレクトリやファイル (`path`, `pattern`, 固有の `name`)。 * `sessions`: 会話履歴（JSONL）のインデックス化設定。 * `update`: 更新の頻度やタイムアウト設定。 * `limits`: 検索結果の件数や文字数制限。 * `scope`: [`session.sendPolicy`](/gateway/configuration#session) と同じスキーマで、どのセッションで QMD 検索を許可するかを制限します。デフォルトは DM のみです。 * `match.keyPrefix`: 正規化されたセッションキー（`agent::` を除去したもの）に前方一致。例: `discord:channel:`。 * `match.rawKeyPrefix`: 生のセッションキー（`agent::` を含む）に前方一致。例: `agent:main:discord:`。 * 検索結果のスニペットには、`memory.citations` が `auto` または `on` の場合に `Source: ` というフッターが付与されます。 ### 追加の記憶パス デフォルトのワークスペース構成外にある Markdown ファイルをインデックスに含めたい場合は、パスを明示的に追加します: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} agents: { defaults: { memorySearch: { extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"] } } } ``` 補足: * 絶対パスまたはワークスペース相対パスを指定可能。 * ディレクトリは `.md` ファイルを求めて再帰的にスキャンされます。 * Markdown ファイルのみが対象です。 * シンボリックリンクは無視されます。 ### Gemini 埋め込み (ネイティブ) Gemini Embeddings API を直接使用する場合: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} agents: { defaults: { memorySearch: { provider: "gemini", model: "gemini-embedding-001", remote: { apiKey: "YOUR_GEMINI_API_KEY" } } } } ``` ### 記憶ツールの動作詳細 * `memory_search`: `MEMORY.md` および `memory/` 以下の Markdown ファイルをチャンク化（約 400 トークン単位）して意味的に検索します。スニペット（最大約 700 文字）、ファイルパス、行範囲、スコア、使用されたプロバイダー/モデルを返します。 * `memory_get`: パス指定でファイルを読み取ります。`MEMORY.md` および `memory/` 以外のパスへのアクセスは拒否されます。 * 両ツールともに、エージェントの設定で `memorySearch.enabled` が有効な場合にのみ利用可能です。 ### インデックスの作成と更新 * ファイル形式: Markdown のみ。 * 保存先: エージェントごとの SQLite ファイル `~/.openclaw/memory/.sqlite`。 * 鮮度管理: ファイル変更を監視し、セッション開始時や検索時に非同期で同期を実行します。 * 全再インデックスのトリガー: 埋め込みの **プロバイダー/モデル、エンドポイント情報、またはチャンク化パラメータ** が変更された場合、OpenClaw は自動的に既存のインデックスをリセットし、最初から作り直します。 ### ハイブリッド検索 (BM25 + ベクトル) 有効にすると、OpenClaw は以下の 2 つを組み合わせた検索を行います: * **ベクトル類似度**: 意味的な一致。言葉の揺れを許容します。 * **BM25 キーワード適合度**: ID、環境変数、コードのシンボル名など、正確な文字列一致。 プラットフォームで全文検索機能が利用できない場合、自動的にベクトル検索のみにフォールバックします。 ### 検索結果の後処理パイプライン 結果リストがエージェントに渡される前に、2 つのオプションステージで精度を高めることができます: ``` ベクトル + キーワード → 重み付けマージ → 時間的減衰 → ソート → MMR → 上位 K 件 ``` #### MMR 再ランク付け (多様性) 似たような内容のメモ（例：毎日同じことを書いている日報など）が検索結果を占領するのを防ぎ、情報の多様性を確保します。 `lambda` パラメータ（0〜1）で、関連性重視か多様性重視かを調整できます。デフォルトは `0.7`（関連性重視）です。 #### 時間的減衰 (新しさの重視) 古い情報よりも最近の情報を優先的に上位へ表示します。 デフォルトの半減期は 30 日です（30 日前のメモはスコアが 50% になります）。 ただし、`MEMORY.md` などの **Evergreen（不朽の）ファイル** や日付のないファイルは、時間の経過による減衰の対象外となり、常に一定の基準で評価されます。 構成例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} agents: { defaults: { memorySearch: { query: { hybrid: { enabled: true, vectorWeight: 0.7, textWeight: 0.3, mmr: { enabled: true, lambda: 0.7 }, temporalDecay: { enabled: true, halfLifeDays: 30 } } } } } } ``` ### 埋め込みキャッシュ インデックスの再作成時に、変更されていないテキストを再度 API で埋め込み処理するのを防ぐためのキャッシュ機能です。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} agents: { defaults: { memorySearch: { cache: { enabled: true, maxEntries: 50000 } } } } ``` ### セッション記憶の検索 (実験的) 会話履歴（セッション記録）自体をインデックス化し、記憶検索の対象に含めることができます。実験的な機能です。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} agents: { defaults: { memorySearch: { experimental: { sessionMemory: true }, sources: ["memory", "sessions"] } } } ``` * セッションの同期は、一定量のメッセージ（デフォルト 50 行）やデータ量（100KB）の増分が発生した際に、バックグラウンドで非同期に行われます。 * 履歴ファイルはディスク上に保存されているため、この機能を利用する際はホスト上のファイルアクセス権限が信頼の境界となります。 # メッセージ Source: https://openclawdoc.org/concepts/messages このページでは、OpenClaw が受信メッセージをどのように扱い、セッション管理、キューイング、ストリーミング、および推論プロセス（Reasoning）の可視化をどのように行っているかをまとめて説明します。 このページでは、OpenClaw が受信メッセージをどのように扱い、セッション管理、キューイング、ストリーミング、および推論プロセス（Reasoning）の可視化をどのように行っているかをまとめて説明します。 ## メッセージフローの概要 ``` 受信メッセージ -> ルーティング/バインディング -> セッションキーの決定 -> キューイング (実行中のエージェントがある場合) -> エージェント実行 (ストリーミング + ツール使用) -> 送信返信 (チャネル制限に合わせた分割/チャンク化) ``` 主な設定項目は構成ファイル (`openclaw.json`) 内にあります: * `messages.*`: プレフィックス、キューイング、グループチャットの挙動。 * `agents.defaults.*`: ブロックストリーミングやチャンク化のデフォルト設定。 * チャネルごとのオーバーライド (`channels.whatsapp.*`, `channels.telegram.*` など): 各プラットフォームの制限事項やストリーミングの有効・無効。 詳細は [ゲートウェイ構成](/gateway/configuration) を参照してください。 ## 受信メッセージの重複排除 (Dedupe) チャネルによっては、再接続後に同じメッセージを再度配信することがあります。OpenClaw は、チャネル、アカウント、送信者、セッション、メッセージ ID をキーとした短期間のキャッシュを保持し、同じメッセージによってエージェントが二重に実行されるのを防ぎます。 ## 入力メッセージの集約 (Debouncing) **同じ送信者** から短時間に連続して届いたテキストメッセージは、`messages.inbound` 設定により 1 つのエージェントターンにまとめて処理できます。デバウンス（集約）はチャネルと会話（conversation）ごとに適用され、返信のスレッドや ID には最新のメッセージの情報が使用されます。 構成例 (グローバルデフォルト + チャネルごとの上書き): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { messages: { inbound: { debounceMs: 2000, byChannel: { whatsapp: 5000, slack: 1500, discord: 1500, }, }, }, } ``` 補足: * デバウンスは**テキストのみ**のメッセージに適用されます。メディアや添付ファイルは即座に処理されます。 * 制御用コマンドはデバウンスをバイパスし、単独で実行されます。 ## セッションとデバイス セッションはクライアント側ではなく、ゲートウェイ側で管理されます。 * ダイレクトチャット（DM）は、エージェントのメインセッションキーに集約されます。 * グループチャットやチャネルは、それぞれ独自のセッションキーを持ちます。 * セッションのデータや記録（トランスクリプト）はゲートウェイが動作しているホスト上に保存されます。 複数のデバイスやチャネルから同じセッションにアクセスできますが、履歴がすべてのクライアントに完全に同期されるわけではありません。長い会話を行う場合は、文脈の食い違いを避けるために 1 つのメインデバイスを使用することを推奨します。コントロール UI や TUI は常にゲートウェイ側の完全な履歴を表示するため、これらが「真実のソース」となります。 詳細は [セッション管理](/concepts/session) を参照してください。 ## 受信本文と履歴コンテキスト OpenClaw は、エージェントへ送る**プロンプト用本文**と、コマンド解析用の**コマンド用本文**を分けて扱います: * `Body`: エージェントに送信されるプロンプトテキスト。チャネル固有の情報や、オプションの履歴情報が含まれる場合があります。 * `CommandBody`: ディレクティブやコマンド解析に使用される、生のユーザーテキスト。 * `RawBody`: `CommandBody` の古い別名（互換性のために保持）。 チャネルが履歴情報を付加する場合、以下の共有ラッパーを使用します: * `[Chat messages since your last reply - for context]` (前回の返信以降のメッセージ - コンテキスト用) * `[Current message - respond to this]` (現在のメッセージ - これに応答してください) **ダイレクトチャット以外**（グループ、チャネル、ルーム）では、**現在のメッセージ本文**の先頭に送信者のラベルが付与されます（履歴エントリと同じスタイル）。これにより、リアルタイムのメッセージと、キューに溜まっていたメッセージや過去の履歴が、エージェントのプロンプト内で一貫した形式になります。 履歴バッファに含まれるのは**未処理のメッセージのみ**です。具体的には、メンション（言及）制約などにより実行がトリガーされなかったグループメッセージが含まれ、すでにセッション記録に保存済みのメッセージは除外されます。 ディレクティブ（コマンド）の除去は「現在のメッセージ」セクションにのみ適用されるため、履歴内の指示はそのまま残ります。履歴をラッピングするチャネルは、`CommandBody` (または `RawBody`) に元のメッセージテキストをセットし、`Body` には結合されたプロンプトをセットする必要があります。履歴バッファの制限数は、グローバル設定の `messages.groupChat.historyLimit`、またはチャネルごとの上書き（`channels.slack.historyLimit`, `channels.telegram.accounts..historyLimit` など。`0` で無効化）で調整可能です。 ## キューイングとフォローアップ すでに実行中のエージェントがある場合、新しく届いたメッセージはキュー（待ち行列）に入れられるか、実行中のプロセスに割り込む（ステアリング）か、あるいは現在のターン終了後にまとめて処理（フォローアップ）されます。 * `messages.queue` (および `messages.queue.byChannel`) で設定します。 * モード: `interrupt`, `steer`, `followup`, `collect`、およびそれぞれのバックログ（未処理分）対応バリアント。 詳細は [キューイング](/concepts/queue) を参照してください。 ## ストリーミング、チャンク化、およびバッチ処理 ブロックストリーミング機能を使用すると、モデルがテキストを生成するそばから部分的な返信を送信できます。チャンク化（分割）の際はチャネルごとの文字数制限を遵守し、コードブロックなどが途中で途切れないよう配慮されます。 主な設定項目: * `agents.defaults.blockStreamingDefault` (`on|off`。デフォルトは off) * `agents.defaults.blockStreamingBreak` (`text_end` または `message_end`) * `agents.defaults.blockStreamingChunk` (`minChars`, `maxChars`, 分割優先度) * `agents.defaults.blockStreamingCoalesce` (アイドル時間に基づくバッチ処理) * `agents.defaults.humanDelay` (ブロックごとの返信間に挟む人間らしい一時停止) * チャネルごとの設定: `*.blockStreaming`, `*.blockStreamingCoalesce` (Telegram 以外のチャネルでブロック返信を有効にするには、明示的に `true` に設定する必要があります) 詳細は [ストリーミングとチャンク化](/concepts/streaming) を参照してください。 ## 推論プロセス（Reasoning）の可視性とトークン モデルの思考プロセス（推論内容）を表示するかどうかを制御できます: * `/reasoning on|off|stream` コマンドで切り替え可能です。 * 推論内容は表示設定にかかわらず、モデルが生成した時点でトークン消費の対象となります。 * Telegram では、ドラフト（下書き）バブル内への推論ストリーミングをサポートしています。 詳細は [思考と推論の指示](/tools/thinking) および [トークン利用](/reference/token-use) を参照してください。 ## プレフィックス、スレッド、および返信 送信メッセージの形式は `messages` セクションで一元管理されています: * `messages.responsePrefix`, `channels..responsePrefix`, `channels..accounts..responsePrefix` (送信時のプレフィックス階層)、および `channels.whatsapp.messagePrefix` (WhatsApp 受信時のプレフィックス)。 * `replyToMode` およびチャネルごとのデフォルト設定による、返信スレッドの紐付け。 詳細は [ゲートウェイ構成 - メッセージ](/gateway/configuration#messages) および各チャネルのドキュメントを参照してください。 # マルチエージェントルーティング Source: https://openclawdoc.org/concepts/multi-agent 目標: 1つの実行中のゲートウェイ内で、複数の分離されたエージェント（個別のワークスペース + agentDir + セッション）、および複数のチャネルアカウント（例: 2つの WhatsApp アカウント）を運用すること。 目標: 1つの実行中のゲートウェイ内で、複数の*分離された*エージェント（個別のワークスペース + `agentDir` + セッション）、および複数のチャネルアカウント（例: 2つの WhatsApp アカウント）を運用すること。受信メッセージはバインディングを介して適切なエージェントにルーティングされます。 ## 「1つのエージェント」とは何を指しますか？ **エージェント**は、以下の要素を独自に持つ、完全にスコープ化された「頭脳」です。 * **ワークスペース** (ファイル、AGENTS.md/SOUL.md/USER.md、ローカルメモ、ペルソナルール)。 * **状態ディレクトリ** (`agentDir`): 認証プロファイル、モデルレジストリ、およびエージェントごとの構成を保持します。 * **セッションストア** (チャット履歴 + ルーティング状態): `~/.openclaw/agents//sessions` 配下に保存されます。 認証プロファイルは**エージェントごと**に管理されます。各エージェントは自身のディレクトリから読み取ります。 ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} ~/.openclaw/agents//agent/auth-profiles.json ``` メインエージェントの認証情報は自動的には共有されません。エージェント間で `agentDir` を再利用しないでください（認証やセッションの衝突の原因となります）。認証情報を共有したい場合は、`auth-profiles.json` を別のエージェントの `agentDir` にコピーしてください。 スキルは各ワークスペースの `skills/` フォルダを介してエージェントごとに管理されます。また、`~/.openclaw/skills` から共有スキルを利用することも可能です。詳細は [スキル: エージェントごと vs 共有](/tools/skills#per-agent-vs-shared-skills) を参照してください。 ゲートウェイは、**1つのエージェント**（デフォルト）または**複数のエージェント**を並行してホストできます。 **ワークスペースに関する注意:** 各エージェントのワークスペースは**デフォルトの作業ディレクトリ (cwd)** であり、厳密なサンドボックスではありません。相対パスはワークスペース内で解決されますが、サンドボックスが有効でない限り、絶対パスを使用してホスト上の他の場所にアクセスできてしまいます。詳細は [サンドボックス](/gateway/sandboxing) を参照してください。 ## パス (クイックマップ) * 構成ファイル: `~/.openclaw/openclaw.json` (または `OPENCLAW_CONFIG_PATH`) * 状態ディレクトリ: `~/.openclaw` (または `OPENCLAW_STATE_DIR`) * ワークスペース: `~/.openclaw/workspace` (または `~/.openclaw/workspace-`) * エージェントディレクトリ: `~/.openclaw/agents//agent` (または `agents.list[].agentDir`) * セッション: `~/.openclaw/agents//sessions` ### シングルエージェントモード (デフォルト) 特に設定を行わない場合、OpenClaw は単一のエージェントを実行します。 * `agentId` のデフォルトは **`main`** です。 * セッションキーは `agent:main:` の形式になります。 * ワークスペースのデフォルトは `~/.openclaw/workspace` です（`OPENCLAW_PROFILE` が設定されている場合は `~/.openclaw/workspace-`）。 * 状態のデフォルトは `~/.openclaw/agents/main/agent` です。 ## エージェントヘルパー エージェントウィザードを使用して、新しい分離されたエージェントを追加できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw agents add work ``` その後、受信メッセージをルーティングするための `bindings` を追加します（ウィザードで自動設定することも可能です）。 以下のコマンドで確認できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw agents list --bindings ``` ## クイックスタート ウィザードを使用するか、手動でワークスペースを作成します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw agents add coding openclaw agents add social ``` 各エージェントは、`SOUL.md`、`AGENTS.md`、オプションの `USER.md` を含む独自のワークスペースと、`~/.openclaw/agents/` 配下の専用の `agentDir` およびセッションストアを取得します。 利用したいチャネルで、エージェントごとにアカウントを作成します。 * Discord: エージェントごとに 1 つのボットを作成し、「Message Content Intent」を有効にして、それぞれのトークンをコピーします。 * Telegram: BotFather を使用してエージェントごとに 1 つのボットを作成し、それぞれのトークンをコピーします。 * WhatsApp: アカウントごとに電話番号をリンクします。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels login --channel whatsapp --account work ``` 詳細はチャネルガイドを参照してください: [Discord](/channels/discord)、[Telegram](/channels/telegram)、[WhatsApp](/channels/whatsapp)。 `agents.list` にエージェントを追加し、`channels..accounts` にチャネルアカウントを追加して、それらを `bindings` で接続します（例は後述）。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway restart openclaw agents list --bindings openclaw channels status --probe ``` ## 複数のエージェント = 複数の人格、複数のキャラクター **複数のエージェント**を運用する場合、各 `agentId` は**完全に独立したペルソナ**として機能します。 * **異なる電話番号/アカウント** (チャネルごとの `accountId`)。 * **異なるキャラクター** (`AGENTS.md` や `SOUL.md` などのエージェントごとのワークスペースファイルによる設定)。 * **個別の認証とセッション** (明示的に有効にしない限り、データが混ざることはありません)。 これにより、**複数のユーザー**が 1 つのゲートウェイサーバーを共有しながら、それぞれの AI の「頭脳」とデータを分離して保持できます。 ## 1 つの WhatsApp 番号で、複数人を相手にする (DM 分割) **1 つの WhatsApp アカウント**を使用しながら、**異なる相手からの DM** をそれぞれ別々のエージェントにルーティングできます。送信者の E.164 番号（例: `+15551234567`）と `peer.kind: "direct"` で判定します。返信はすべて同じ WhatsApp 番号から送信されます（エージェントごとの送信者 ID は持てません）。 重要な詳細: ダイレクトチャットはエージェントの**メインセッションキー**に集約されるため、真の分離を実現するには**1人につき1つのエージェント**を割り当てる必要があります。 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "alex", workspace: "~/.openclaw/workspace-alex" }, { id: "mia", workspace: "~/.openclaw/workspace-mia" }, ], }, bindings: [ { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } }, }, { agentId: "mia", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } }, }, ], channels: { whatsapp: { dmPolicy: "allowlist", allowFrom: ["+15551230001", "+15551230002"], }, }, } ``` 注: * DM のアクセス制御は、エージェントごとではなく、**WhatsApp アカウント単位でグローバル**に適用されます（ペアリング/許可リスト）。 * 共有グループの場合は、グループを特定のエージェントにバインドするか、[ブロードキャストグループ](/channels/broadcast-groups) を使用してください。 ## ルーティングルール (メッセージがどのエージェントに送られるか) バインディングは**確定的**であり、**最も条件が限定されているもの（具体的なもの）が優先**されます。 1. `peer` の一致 (特定の DM/グループ/チャネル ID) 2. `parentPeer` の一致 (スレッドの継承) 3. `guildId + roles` (Discord のロールによるルーティング) 4. `guildId` (Discord) 5. `teamId` (Slack) 6. `accountId` によるチャネルの一致 7. チャネルレベルの一致 (`accountId: "*"`) 8. デフォルトエージェントへのフォールバック (`agents.list[].default`、設定がない場合はリストの最初のエントリ、デフォルトは `main`) 複数のバインディングが同じ優先度で一致した場合は、設定ファイル内で先に記述されているものが優先されます。1つのバインディングに複数の条件（例: `peer` + `guildId`）を設定した場合、それらすべての条件を満たす必要があります（AND 条件）。 アカウントスコープに関する重要な詳細: * `accountId` を省略したバインディングは、デフォルトのアカウントのみに一致します。 * すべてのアカウントにわたるチャネル全体のフォールバック設定には、`accountId: "*"` を使用します。 * 後で同じエージェントに対して特定のアカウント ID を指定したバインディングを追加すると、OpenClaw は既存のチャネルのみのバインディングを重複させるのではなく、アカウントスコープの設定にアップグレードします。 ## 複数のアカウント / 電話番号 WhatsApp のように**複数のアカウント**をサポートするチャネルでは、`accountId` を使用して各ログインを識別します。各 `accountId` を異なるエージェントにルーティングできるため、1つのサーバーでセッションを混合させることなく、複数の電話番号をホストできます。 `accountId` が省略された場合にチャネル全体のデフォルトアカウントを使用したい場合は、`channels..defaultAccount` を設定します（オプション）。設定されていない場合、OpenClaw は `default` アカウントがあればそれを、なければ最初に構成されたアカウント ID（ソート順）を使用します。 このパターンをサポートする主なチャネルは以下の通りです。 * `whatsapp`、`telegram`、`discord`、`slack`、`signal`、`imessage` * `irc`、`line`、`googlechat`、`mattermost`、`matrix`、`nextcloud-talk` * `bluebubbles`、`zalo`、`zalouser`、`nostr`、`feishu` ## コンセプト * `agentId`: 1つの「頭脳」 (ワークスペース、エージェントごとの認証、エージェントごとのセッションストア)。 * `accountId`: チャネルアカウントの 1 つのインスタンス (例: WhatsApp アカウントの `"personal"` と `"biz"`)。 * `binding`: 受信メッセージを `(channel, accountId, peer)` およびオプションでギルド/チーム ID に基づいて特定の `agentId` にルーティングします。 * ダイレクトチャットは `agent::` に集約されます。 ## プラットフォーム別の例 ### エージェントごとの Discord ボット 各 Discord ボットアカウントは、一意の `accountId` にマッピングされます。各アカウントをエージェントにバインドし、ボットごとに許可リストを管理します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "main", workspace: "~/.openclaw/workspace-main" }, { id: "coding", workspace: "~/.openclaw/workspace-coding" }, ], }, bindings: [ { agentId: "main", match: { channel: "discord", accountId: "default" } }, { agentId: "coding", match: { channel: "discord", accountId: "coding" } }, ], channels: { discord: { groupPolicy: "allowlist", accounts: { default: { token: "DISCORD_BOT_TOKEN_MAIN", guilds: { "123456789012345678": { channels: { "222222222222222222": { allow: true, requireMention: false }, }, }, }, }, coding: { token: "DISCORD_BOT_TOKEN_CODING", guilds: { "123456789012345678": { channels: { "333333333333333333": { allow: true, requireMention: false }, }, }, }, }, }, }, }, } ``` 注: * 各ボットをサーバー（ギルド）に招待し、「Message Content Intent」を有効にしてください。 * トークンは `channels.discord.accounts..token` に設定します（デフォルトアカウントでは `DISCORD_BOT_TOKEN` 環境変数も使用可能です）。 ### エージェントごとの Telegram ボット ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "main", workspace: "~/.openclaw/workspace-main" }, { id: "alerts", workspace: "~/.openclaw/workspace-alerts" }, ], }, bindings: [ { agentId: "main", match: { channel: "telegram", accountId: "default" } }, { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } }, ], channels: { telegram: { accounts: { default: { botToken: "123456:ABC...", dmPolicy: "pairing", }, alerts: { botToken: "987654:XYZ...", dmPolicy: "allowlist", allowFrom: ["tg:123456789"], }, }, }, }, } ``` 注: * BotFather を使用してエージェントごとにボットを作成し、トークンをコピーしてください。 * トークンは `channels.telegram.accounts..botToken` に設定します（デフォルトアカウントでは `TELEGRAM_BOT_TOKEN` 環境変数も使用可能です）。 ### エージェントごとの WhatsApp 番号 ゲートウェイを起動する前に、各アカウントをリンクしておきます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels login --channel whatsapp --account personal openclaw channels login --channel whatsapp --account biz ``` `~/.openclaw/openclaw.json` (JSON5): ```js theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "home", default: true, name: "Home", workspace: "~/.openclaw/workspace-home", agentDir: "~/.openclaw/agents/home/agent", }, { id: "work", name: "Work", workspace: "~/.openclaw/workspace-work", agentDir: "~/.openclaw/agents/work/agent", }, ], }, // 確定的なルーティング: 最初に一致したものが優先されます。 bindings: [ { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }, { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }, // 特定の相手（グループなど）を別のエージェントに送る例 { agentId: "work", match: { channel: "whatsapp", accountId: "personal", peer: { kind: "group", id: "1203630...@g.us" }, }, }, ], // デフォルトではオフ: エージェント間のメッセージ送信は明示的な有効化と許可が必要です。 tools: { agentToAgent: { enabled: false, allow: ["home", "work"], }, }, channels: { whatsapp: { accounts: { personal: { // オプションのオーバーライド。デフォルト: ~/.openclaw/credentials/whatsapp/personal // authDir: "~/.openclaw/credentials/whatsapp/personal", }, biz: { // オプションのオーバーライド。デフォルト: ~/.openclaw/credentials/whatsapp/biz // authDir: "~/.openclaw/credentials/whatsapp/biz", }, }, }, }, } ``` ## 例: WhatsApp は日常用 + Telegram は集中作業用 チャネルごとに分割する例: WhatsApp は日常的な高速エージェントに、Telegram は Opus エージェントにルーティングします。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "chat", name: "Everyday", workspace: "~/.openclaw/workspace-chat", model: "anthropic/claude-sonnet-4-5", }, { id: "opus", name: "Deep Work", workspace: "~/.openclaw/workspace-opus", model: "anthropic/claude-opus-4-6", }, ], }, bindings: [ { agentId: "chat", match: { channel: "whatsapp" } }, { agentId: "opus", match: { channel: "telegram" } }, ], } ``` 注: * 同一チャネルで複数のアカウントがある場合は、バインディングに `accountId` を追加してください。 * 特定の DM/グループだけを Opus に送り、残りを通常チャットに維持したい場合は、その相手に対して `match.peer` バインディングを追加してください。ピア一致は常にチャネル全体のルールよりも優先されます。 ## 例: 同一チャネルで、特定の相手だけ Opus に送る WhatsApp は高速エージェントを使用しつつ、特定の 1 人からの DM だけを Opus に送る設定です。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "chat", name: "Everyday", workspace: "~/.openclaw/workspace-chat", model: "anthropic/claude-sonnet-4-5", }, { id: "opus", name: "Deep Work", workspace: "~/.openclaw/workspace-opus", model: "anthropic/claude-opus-4-6", }, ], }, bindings: [ { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } }, }, { agentId: "chat", match: { channel: "whatsapp" } }, ], } ``` ピアバインディングが常に優先されるよう、チャネル全体のルールよりも上に記述してください。 ## WhatsApp グループに紐付けられたファミリーエージェント 特定の WhatsApp グループに専用のファミリーエージェントを割り当て、メンションによる制限と厳格なツールポリシーを適用する例です。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "family", name: "Family", workspace: "~/.openclaw/workspace-family", identity: { name: "Family Bot" }, groupChat: { mentionPatterns: ["@family", "@familybot", "@Family Bot"], }, sandbox: { mode: "all", scope: "agent", }, tools: { allow: [ "exec", "read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", ], deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"], }, }, ], }, bindings: [ { agentId: "family", match: { channel: "whatsapp", peer: { kind: "group", id: "120363999999999999@g.us" }, }, }, ], } ``` 注: * ツールの許可/拒否リストは**ツール**の設定であり、スキルの設定ではありません。スキルがバイナリを実行する必要がある場合は、`exec` が許可されており、かつバイナリがサンドボックス内に存在することを確認してください。 * ゲートをより厳密にするには、`agents.list[].groupChat.mentionPatterns` を設定し、そのチャネルのグループ許可リストを有効にしておきます。 ## エージェントごとのサンドボックスとツールの設定 v2026.1.6 以降、各エージェントは独自のサンドボックス設定とツールの制限を持つことができます。 ```js theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "personal", workspace: "~/.openclaw/workspace-personal", sandbox: { mode: "off", // パーソナルエージェントはサンドボックスなし }, // ツール制限なし - すべてのツールを利用可能 }, { id: "family", workspace: "~/.openclaw/workspace-family", sandbox: { mode: "all", // 常にサンドボックス化 scope: "agent", // エージェントごとに 1 つのコンテナ docker: { // コンテナ作成時のオプション設定 setupCommand: "apt-get update && apt-get install -y git curl", }, }, tools: { allow: ["read"], // 読み取りツールのみ許可 deny: ["exec", "write", "edit", "apply_patch"], // その他を拒否 }, }, ], }, } ``` 注: `setupCommand` は `sandbox.docker` 配下に記述し、コンテナ作成時に 1 回だけ実行されます。解決されたスコープが `"shared"` の場合、エージェントごとの `sandbox.docker.*` のオーバーライドは無視されます。 **メリット:** * **セキュリティの分離**: 信頼できないエージェントのツールを制限できます。 * **リソース管理**: 特定のエージェントだけをサンドボックス化し、他はホスト上で実行できます。 * **柔軟なポリシー**: エージェントごとに異なる権限を設定できます。 注: `tools.elevated` は**グローバル**かつ送信者ベースの設定であり、エージェントごとに構成することはできません。エージェントごとの境界を設けたい場合は、`agents.list[].tools` を使用して `exec` を拒否してください。グループ内でのターゲット指定には、`agents.list[].groupChat.mentionPatterns` を使用し、@メンションが目的のエージェントに正しくマッピングされるようにします。 詳細は [マルチエージェントサンドボックス & ツール](/tools/multi-agent-sandbox-tools) を参照してください。 # OAuth Source: https://openclawdoc.org/concepts/oauth OpenClaw は、対応しているプロバイダー（特に OpenAI Codex (ChatGPT OAuth)）において、OAuth 経由のサブスクリプション認証をサポートしています。Anthropic のサブスクリプション利用には setup-token フローを使用します。 OpenClaw は、対応しているプロバイダー（特に **OpenAI Codex (ChatGPT OAuth)**）において、OAuth 経由のサブスクリプション認証をサポートしています。Anthropic のサブスクリプション利用には **setup-token** フローを使用します。Anthropic のサブスクリプションを Claude Code 以外で利用することは、過去に一部のユーザーで制限された事例があるため、リスクを理解した上で自己責任で利用し、最新のポリシーを確認してください。OpenAI Codex OAuth は、OpenClaw のような外部ツールでの利用が明示的にサポートされています。 本番環境での Anthropic 利用においては、サブスクリプションベースの setup-token よりも、API キーによる認証の方が安全であり、推奨されるパスです。 このページでは以下の内容を説明します: * OAuth の **トークン交換** の仕組み (PKCE) * トークンの **保存場所** とその理由 * **複数アカウント** の扱い（プロファイル管理とセッションごとの上書き） OpenClaw は、独自の OAuth や API キー入力フローを持つ **プロバイダープラグイン** もサポートしています。以下のコマンドで実行できます: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw models auth login --provider ``` ## トークンシンク (情報の集約) OAuth プロバイダーは通常、ログインや更新（リフレッシュ）のたびに **新しいリフレッシュトークン** を発行します。プロバイダー（またはクライアントの実装）によっては、同じユーザー・アプリに対して新しいトークンが発行されると、古いトークンが無効化される場合があります。 よくある症状: * OpenClaw と Claude Code（または Codex CLI）の両方でログインしていると、後からどちらかがランダムにログアウト状態になる。 これを防ぐため、OpenClaw は `auth-profiles.json` を **トークンシンク（集約先）** として扱います: * 実行環境は、**常に一箇所** から認証情報を読み取ります。 * 複数のプロファイルを保持し、それらを確定的にルーティングできます。 ## 保存場所 シークレット（機密情報）は **エージェントごと** に保存されます: * **認証プロファイル** (OAuth、API キー、オプションの参照設定): `~/.openclaw/agents//agent/auth-profiles.json` * **レガシー互換ファイル**: `~/.openclaw/agents//agent/auth.json` * 静的な `api_key` エントリが検出された場合、セキュリティのため自動的に削除（スクラブ）されます。 インポート専用の古いファイル（現在はメインの保存先ではありませんが、移行用にサポートされています）: * `~/.openclaw/credentials/oauth.json` (初回使用時に `auth-profiles.json` へインポートされます) これらすべてのパスは、`$OPENCLAW_STATE_DIR` 環境変数によるディレクトリの上書き設定を尊重します。詳細は [構成リファレンス](/gateway/configuration#auth-storage-oauth--api-keys) を参照してください。 静的なシークレット参照（SecretRef）や実行時スナップショットの動作については、[シークレット管理](/gateway/secrets) を参照してください。 ## Anthropic setup-token (サブスクリプション認証) Anthropic setup-token のサポートは技術的な互換性を確保するものであり、将来にわたる利用を保証するものではありません。 Anthropic は過去に、Claude Code 以外でのサブスクリプション利用を制限したことがあります。 最新の規約を確認し、リスクを考慮した上で利用を判断してください。 任意のマシンで `claude setup-token` を実行し、表示された内容を OpenClaw に貼り付けます: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw models auth setup-token --provider anthropic ``` トークンを別の場所で既に生成済みの場合は、手動で貼り付けることも可能です: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw models auth paste-token --provider anthropic ``` 現在の状態を確認する: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw models status ``` ## OAuth 交換の仕組み (ログインフロー) OpenClaw の対話型ログインフローは、`@mariozechner/pi-ai` に実装されており、ウィザードや各種コマンドに組み込まれています。 ### Anthropic setup-token のフロー 1. `claude setup-token` を実行します。 2. トークンを OpenClaw に貼り付けます。 3. リフレッシュ機能のない「トークン認証プロファイル」として保存されます。 オンボーディング時のパス: `openclaw onboard` → 認証方法の選択で `setup-token` (Anthropic) を選択。 ### OpenAI Codex (ChatGPT OAuth) のフロー OpenAI Codex OAuth は、Codex CLI 以外の環境（OpenClaw ワークフローなど）での利用が明示的に許可されています。 フローの流れ (PKCE): 1. PKCE 検証用コード（Verifier/Challenge）とランダムな `state` 文字列を生成します。 2. ブラウザで `https://auth.openai.com/oauth/authorize?...` を開きます。 3. `http://127.0.0.1:1455/auth/callback` でコールバックの受信を待機します。 4. コールバックを受信できない場合（リモート環境やヘッドレス環境の場合）、リダイレクト先の URL またはコードを手動で貼り付けます。 5. `https://auth.openai.com/oauth/token` でトークン交換を行います。 6. アクセストークンから `accountId` を抽出し、`{ access, refresh, expires, accountId }` を保存します。 オンボーディング時のパス: `openclaw onboard` → 認証方法の選択で `openai-codex` を選択。 ## 更新 (Refresh) と有効期限 各プロファイルには `expires`（有効期限）のタイムスタンプが保存されています。 実行時の挙動: * `expires` が未来（有効）な場合 → 保存されているアクセストークンをそのまま使用します。 * 期限切れの場合 → ファイルロックをかけた状態でリフレッシュ処理を行い、新しい認証情報で上書き保存します。 この更新処理は自動的に行われるため、通常は手動でトークンを管理する必要はありません。 ## 複数アカウント (プロファイル) とルーティング 以下の 2 つの運用パターンがあります: ### 1) 推奨: エージェントを分ける 「個人用」と「仕事用」を完全に分離したい場合は、個別のエージェント（専用のセッション、認証情報、ワークスペースを持つ）を使用してください: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw agents add work openclaw agents add personal ``` その後、各エージェントに対して個別に認証設定（ウィザード）を行い、チャットを適切なエージェントにルーティングします。 ### 2) 高度な設定: 1 つのエージェントで複数のプロファイルを使い分ける `auth-profiles.json` は、同じプロバイダーに対して複数のプロファイル ID を保持できます。 使用するプロファイルの選択方法: * グローバル設定: 構成ファイル内の順序指定 (`auth.order`)。 * セッションごとの上書き: `/model ...@` コマンドを使用。 例 (セッションでの上書き): * `/model Opus@anthropic:work` 利用可能なプロファイル ID を確認する方法: * `openclaw channels list --json` を実行し、`auth[]` 配下を確認します。 関連ドキュメント: * [モデルフェイルオーバー](/concepts/model-failover) (ローテーションとクールダウンのルール) * [スラッシュコマンド](/tools/slash-commands) (コマンドのインターフェース) # プレゼンス (稼働状況) Source: https://openclawdoc.org/concepts/presence プレゼンス情報は、主に macOS アプリの Instances（インスタンス） タブでの表示や、管理者が現在の接続状況を把握するために使用されます。プレゼンスフィールド (表示される項目)、情報のソース (どこから来るか)、1) ゲートウェイ自身のセルフエントリを確認できます。 OpenClaw の「プレゼンス」は、以下の要素の稼働状況をベストエフォートで可視化したものです: * **ゲートウェイ** 自体 * **ゲートウェイに接続されているクライアント** (macOS アプリ、WebChat、CLI など) プレゼンス情報は、主に macOS アプリの **Instances（インスタンス）** タブでの表示や、管理者が現在の接続状況を把握するために使用されます。 ## プレゼンスフィールド (表示される項目) 各プレゼンスエントリは、以下のようなフィールドを持つ構造化されたオブジェクトです: * `instanceId` (任意だが強く推奨): クライアントの固定 ID（通常は `connect.client.instanceId`） * `host`: 人間が読みやすいホスト名 * `ip`: 取得可能な IP アドレス * `version`: クライアントのバージョン文字列 * `deviceFamily` / `modelIdentifier`: ハードウェアの種類に関するヒント * `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node` など * `lastInputSeconds`: ユーザーが最後に入力してからの経過秒数（取得可能な場合） * `reason`: エントリが作成された理由 (`self`, `connect`, `node-connected`, `periodic` など) * `ts`: 最終更新日時のタイムスタンプ（ミリ秒） ## 情報のソース (どこから来るか) プレゼンス情報は複数のソースから生成され、**マージ（統合）** されます。 ### 1) ゲートウェイ自身のセルフエントリ ゲートウェイは起動時に自身の情報を登録します。これにより、クライアントが 1 つも接続されていない状態でも UI にゲートウェイホストが表示されます。 ### 2) WebSocket の接続時 すべての WebSocket クライアントは `connect` リクエストから始まります。ハンドシェイク（接続確立）が成功すると、ゲートウェイはその接続に対するプレゼンスエントリを作成または更新（upsert）します。 #### CLI コマンドが表示されない理由 CLI は短時間の単発コマンドのために頻繁に接続します。インスタンス一覧が CLI で埋め尽くされるのを避けるため、`client.mode === "cli"` の接続はプレゼンスエントリとして**登録されません**。 ### 3) `system-event` による定期通知 クライアントは `system-event` メソッドを使用して、より詳細な情報を定期的に通知できます。macOS アプリはこの仕組みを利用して、ホスト名、IP、および `lastInputSeconds` を報告しています。 ### 4) ノードの接続 (role: node) ノードが `role: node` としてゲートウェイの WebSocket に接続すると、他のクライアントと同様のフローでプレゼンスエントリが作成されます。 ## マージと重複排除のルール (`instanceId` の重要性) すべてのプレゼンスエントリは、メモリ上の 1 つのマップに保存されます: * 各エントリは **プレゼンスキー** によって管理されます。 * 最も適切なキーは、再起動後も変わらない安定した `instanceId` (`connect.client.instanceId` 由来) です。 * キーの大文字・小文字は区別されません。 クライアントが固定の `instanceId` を持たずに再接続を繰り返すと、一覧に **重複した行** が表示される原因となります。 ## 有効期限 (TTL) と最大件数 プレゼンス情報は意図的に一時的なものとして扱われます: * **TTL**: 最終更新から 5 分以上経過したエントリは自動的に削除されます。 * **最大件数**: 200 件（上限を超えた場合は古いものから削除されます）。 これにより、常に最新の稼働状況が保たれ、メモリの無制限な増加を防いでいます。 ## リモート/トンネル利用時の注意 (ループバック IP) SSH トンネルやローカルポート転送を介してクライアントが接続している場合、ゲートウェイから見たリモートアドレスが `127.0.0.1` になることがあります。クライアントが報告した正しい IP アドレスを上書きしてしまわないよう、ループバックアドレスからの通知は IP 情報の更新対象から除外されます。 ## 情報の利用者 ### macOS アプリの Instances タブ macOS アプリは `system-presence` の出力を表示し、最終更新からの経過時間に基づいて「Active（アクティブ）」「Idle（アイドル）」「Stale（古い）」のステータスインジケーターを付与します。 ## デバッグのヒント * 生のリストを確認するには、ゲートウェイに対して `system-presence` メソッドを呼び出してください。 * 重複が発生している場合: * クライアントが接続時のハンドシェイクで固定の `client.instanceId` を送信しているか確認してください。 * 定期的な `system-event` 通知でも同じ `instanceId` が使われているか確認してください。 * 接続由来のエントリに `instanceId` が欠落していないか確認してください（欠落していると重複が発生しやすくなります）。 # コマンドキュー Source: https://openclawdoc.org/concepts/queue OpenClaw は、すべてのチャネルからの自動応答リクエストを軽量なインプロセス（プロセス内）キューを通じてシリアル化（直列化）します。目的、仕組み、キューモード (チャネルごとの動作)を確認できます。 OpenClaw は、すべてのチャネルからの自動応答リクエストを軽量なインプロセス（プロセス内）キューを通じてシリアル化（直列化）します。これにより、同じセッションに対して複数のエージェントが同時に実行されて競合するのを防ぎつつ、異なるセッション間では安全な並列実行を可能にしています。 ## 目的 * エージェントの実行（LLM の呼び出し）はコストが高く、短時間に複数のメッセージが届いた場合にリソースが競合する可能性があります。 * 実行を直列化することで、セッションファイル、ログ、CLI の標準入力などの共有リソースへの同時アクセスを避け、上位プロバイダーのレート制限にかかるリスクを低減します。 ## 仕組み * 「レーン（Lane）」を認識する FIFO（先入れ先出し）キューが、各レーンごとに設定された同時実行上限に従ってリクエストを処理します。 * レーンごとのデフォルト上限: 未設定のレーンは 1、メインレーン（`main`）は 4、サブエージェント（`subagent`）は 8 です。 * `runEmbeddedPiAgent` は、まず **セッションキー** ごとのレーン（`session:`）にエンキュー（待ち行列に追加）されます。これにより、1 つのセッションに対して一度に実行されるエージェントは必ず 1 つであることが保証されます。 * 次に、各セッションの実行は **グローバルレーン**（デフォルトは `main`）にエンキューされます。システム全体の並列数は、構成設定の `agents.defaults.maxConcurrent` によって制限されます。 * 詳細ログ（verbose）が有効な場合、キューでの待機時間が約 2 秒を超えた際に通知が出力されます。 * タイピング中インジケーター（対応チャネルのみ）は、キューに入った直後に作動します。そのため、順番待ちの間もユーザーにはボットが反応しているように見え、UX は損なわれません。 ## キューモード (チャネルごとの動作) 受信メッセージが届いた際、現在実行中のターンに対して「割り込む（ステアリング）」か、「終わるのを待ってから次で処理する（フォローアップ）」か、あるいはその両方を行うかを選択できます。 * `steer`: 現在の実行に直ちに割り込みます（次のツール実行のタイミングで、残りのツール呼び出しをキャンセルします）。ストリーミングが利用できない場合は `followup` モードにフォールバックします。 * `followup`: 現在の実行が終わった後、次のターンとしてキューに追加します。 * `collect` (デフォルト): 現在の実行が終わるまで待機し、キューに溜まったすべてのメッセージを **1 つの** フォローアップターンに集約して処理します。宛先のチャネルやスレッドが異なる場合は、ルーティングを維持するために個別に処理されます。 * `steer-backlog` (`steer+backlog`): 現在の実行に割り込むと同時に、そのメッセージを次回のフォローアップ用にも保持します。 * `interrupt` (レガシー): 現在の実行を強制終了（abort）させ、最新のメッセージで新しく実行を開始します。 * `queue` (レガシー別名): `steer` と同じ動作です。 `steer-backlog` を使用すると、割り込んだターンとフォローアップのターンの両方で応答が生成されるため、ストリーミング対応の UI では重複したように見えることがあります。1 つのメッセージに対して 1 つの応答を確実に返したい場合は `collect` または `steer` を推奨します。 設定方法: * セッションごとに `/queue collect` コマンドを送信する。 * 構成ファイルで `messages.queue.byChannel.discord: "collect"` のように指定する。 デフォルト設定（未設定時）: * すべてのチャネルで `collect` グローバルまたはチャネルごとの設定例 (`messages.queue`): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { messages: { queue: { mode: "collect", debounceMs: 1000, cap: 20, drop: "summarize", byChannel: { discord: "collect" }, }, }, } ``` ## キューのオプション これらのオプションは `followup`, `collect`, `steer-backlog`（および `steer` がフォールバックした場合）に適用されます。 * `debounceMs`: フォローアップを開始する前に、追記が止まるまで待機する時間（「あ、あとこれも」といった連続投稿を 1 つにまとめるため）。 * `cap`: 1 セッションあたりに蓄積できるキューの最大数。 * `drop`: 上限を超えた場合の処理ポリシー (`old`: 古い順に捨てる, `new`: 新しいものを捨てる, `summarize`: 要約する)。 `summarize` を選択すると、破棄されたメッセージの短いリストを保持し、それを合成されたフォローアッププロンプトとしてエージェントに渡します。 デフォルト値: `debounceMs: 1000`, `cap: 20`, `drop: summarize`。 ## セッションごとの上書き * `/queue ` コマンドを送信すると、現在のセッションの設定として保存されます。 * オプションの組み合わせも可能です: `/queue collect debounce:2s cap:25 drop:summarize` * `/queue default` または `/queue reset` で上書き設定を解除できます。 ## 適用範囲と保証 * ゲートウェイの返信パイプラインを使用するすべての受信チャネル（WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat など）の自動応答に適用されます。 * デフォルトレーン (`main`) は、通常の応答とメインのハートビートで共有されます。複数のセッションを並列で動かしたい場合は `agents.defaults.maxConcurrent` を増やしてください。 * `cron` や `subagent` といった追加のレーンがあり、インバウンドの応答を妨げることなくバックグラウンドジョブを並列実行できます。 * セッションごとのレーンにより、特定のセッションに対して一度にアクセスするエージェント実行は常に 1 つに制限されることが保証されます。 * 外部の依存関係やワーカースレッドは使用せず、純粋な TypeScript と Promise で実装されています。 ## トラブルシューティング * コマンドが止まっているように見える場合は、詳細ログを有効にして「queued for …ms」という行を確認し、キューが処理（排出）されているか確かめてください。 * キューの深さを知りたい場合も、詳細ログでキューのタイミング情報を確認してください。 # 再試行ポリシー Source: https://openclawdoc.org/concepts/retry 試行回数: 3 最大遅延上限: 30000 ミリ秒。目標、デフォルト、動作を確認できます。 ## 目標 * 複数ステップのフローごとではなく、HTTP リクエストごとに再試行します。 * 現在のステップのみを再試行して順序を保持します。 * 非冪等操作の重複を避けてください。 ## デフォルト * 試行回数: 3 * 最大遅延上限: 30000 ミリ秒 * ジッター: 0.1 (10%) * プロバイダーのデフォルト: * テレグラムの最小遅延: 400 ミリ秒 * Discord の最小遅延: 500 ミリ秒 ## 動作 ### 不和 * レート制限エラー (HTTP 429) の場合にのみ再試行します。 * 利用可能な場合は Discord `retry_after` を使用し、それ以外の場合は指数バックオフを使用します。 ### Telegram * 一時的なエラー (429、タイムアウト、接続/リセット/クローズ、一時的に利用不可) の場合は再試行します。 * 利用可能な場合は `retry_after` を使用し、それ以外の場合は指数バックオフを使用します。 * マークダウン解析エラーは再試行されません。プレーンテキストに戻ります。 ## 構成 `~/.openclaw/openclaw.json` でプロバイダーごとに再試行ポリシーを設定します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { retry: { attempts: 3, minDelayMs: 400, maxDelayMs: 30000, jitter: 0.1, }, }, discord: { retry: { attempts: 3, minDelayMs: 500, maxDelayMs: 30000, jitter: 0.1, }, }, }, } ``` ## 注意事項 * 再試行はリクエストごとに適用されます (メッセージ送信、メディアアップロード、反応、投票、ステッカー)。 * 複合フローは、完了したステップを再試行しません。 # セッション管理 Source: https://openclawdoc.org/concepts/session OpenClaw は、エージェントごとに 1 つのメイン（ダイレクトチャット）セッション を主要なものとして扱います。セキュア DM モード (複数人での利用時に推奨)、ゲートウェイが「真実のソース」、データの保存場所を確認できます。 OpenClaw は、**エージェントごとに 1 つのメイン（ダイレクトチャット）セッション** を主要なものとして扱います。通常のダイレクトメッセージ（DM）は `agent::` (デフォルトのメインキーは `main`) に集約されますが、グループチャットや各チャネルの固有チャットはそれぞれ独立したキーを持ちます。 `session.dmScope` 設定を使用して、**ダイレクトメッセージ** のグループ化方法を制御できます: * `main` (デフォルト): すべての DM がメインセッションを共有し、デバイスを跨いでも会話が継続されます。 * `per-peer`: 送信者 ID ごとに、チャネルを跨いでセッションを分離します。 * `per-channel-peer`: チャネル + 送信者の組み合わせごとに分離します（複数人で 1 つのボットを共有する場合に推奨）。 * `per-account-channel-peer`: アカウント + チャネル + 送信者の組み合わせごとに分離します。 `session.identityLinks` を使用して、異なるチャネルのユーザー ID を 1 つの「正規のアイデンティティ」に紐付けることができます。これにより、同じユーザーであればチャネルが変わっても同じ DM セッションを継続できるようになります。 ## セキュア DM モード (複数人での利用時に推奨) > **セキュリティ警告:** エージェントが **複数のユーザー** から DM を受け取る可能性がある場合は、セキュア DM モードの有効化を強く検討してください。無効な場合、すべてのユーザーが同じ会話コンテキストを共有することになり、プライベートな情報が他のユーザーに漏洩するリスクがあります。 **デフォルト設定で発生しうる問題の例:** 1. アリスがエージェントにプライベートな相談（例: 通院の予約）を送信します。 2. その後、ボブが同じエージェントに「さっきは何の話をしていた？」と尋ねます。 3. すべての DM が同じセッションを共有しているため、エージェントはアリスとの会話内容を元にボブに回答してしまいます。 **解決策:** `dmScope` を設定して、ユーザーごとにセッションを分離します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} // ~/.openclaw/openclaw.json { session: { // セキュア DM モード: チャネル + 送信者ごとにコンテキストを分離。 dmScope: "per-channel-peer", }, } ``` **有効にすべき状況:** * 複数の送信者に対してペアリングを承認している。 * 複数のエントリを持つ DM 許可リストを使用している。 * `dmPolicy: "open"` (誰でも許可) を設定している。 * 複数の電話番号やアカウントがエージェントにメッセージを送信できる。 補足事項: * 1 人だけで利用する場合は、継続性を重視したデフォルトの `dmScope: "main"` のままで問題ありません。 * ローカル CLI でのオンボーディング時、未設定であればデフォルトで `session.dmScope: "per-channel-peer"` が書き込まれます。 * 同じチャネルで複数のアカウントを運用している場合は、`per-account-channel-peer` が最適です。 * `openclaw security audit` コマンドで現在の DM 設定の安全性を確認できます。 ## ゲートウェイが「真実のソース」 すべてのセッション状態は **ゲートウェイが所有** します。UI クライアント（macOS アプリ、WebChat、TUI など）は、ローカルファイルを直接読み取るのではなく、ゲートウェイに問い合わせてセッション一覧やトークン数を取得します。 * **リモートモード** の場合、セッションデータはローカルの Mac ではなく、接続先のリモートホスト上に存在します。 * UI に表示されるトークン数はゲートウェイのデータに基づきます。クライアント側で JSONL 履歴を解析して計算し直すことはありません。 ## データの保存場所 * **ゲートウェイホスト上**: * 管理ファイル: `~/.openclaw/agents//sessions/sessions.json` (エージェントごと)。 * 会話履歴（JSONL）: `~/.openclaw/agents//sessions/.jsonl`。 * 管理ファイルは `sessionKey -> { sessionId, updatedAt, ... }` のマップ構造です。このファイル内のエントリを削除しても安全です（必要に応じて再作成されます）。 * 履歴ファイルには、UI での識別のために `displayName`, `channel`, `subject` などのメタデータが含まれる場合があります。 * OpenClaw は、古い Pi や Tau のセッションフォルダを読み込むことはありません。 ## メンテナンス (クリーンアップ) OpenClaw は、`sessions.json` や履歴ファイルが際限なく増え続けるのを防ぐため、自動的なメンテナンス機能を備えています。 ### デフォルト設定 * 保持期間: 30 日間 (`pruneAfter: "30d"`) * 最大件数: 500 件 (`maxEntries: 500`) * ローテーション: 10MB を超えたら `sessions.json` を新しくする (`rotateBytes: "10mb"`) * ディスク容量制限: デフォルトでは無効 (`maxDiskBytes`) ### 仕組み セッションの書き込み時にメンテナンスが実行されます。`openclaw sessions cleanup` コマンドで手動実行も可能です。 * `mode: "warn"` (デフォルト): 削除対象となるエントリを報告するだけで、実際の削除は行いません。 * `mode: "enforce"`: 以下の順序で実際にクリーンアップを行います: 1. 保持期間を過ぎた古いエントリを削除。 2. 上限件数を超える古いエントリを削除。 3. 参照されなくなった履歴ファイルをアーカイブ。 4. 構成されたディスク容量予算 (`maxDiskBytes`) を守るよう、古いものから順に削除。 ## 転送手段（トランスポート）とセッションキーの紐付け * **ダイレクトチャット**: `session.dmScope` に従います。 * `main`: `agent::`。複数の電話番号やチャネルが 1 つのメインセッションに紐付き、単一の会話として機能します。 * `per-peer`: `agent::dm:`。 * `per-channel-peer`: `agent:::dm:`。 * **グループチャット**: チャネルごとに独立した状態を持ちます。 * 形式: `agent:::group:` (ルームの場合は `...:channel:`)。 * Telegram のトピック（フォーラム）機能では、グループ ID に `:topic:` が付加され、トピックごとに分離されます。 * **その他のソース**: * Cron ジョブ: `cron:` * Webhook: `hook:` * ノード実行: `node-` ## ライフサイクルとリセット * **リセットポリシー**: セッションは有効期限が切れるまで再利用されます。期限切れの判定は、次にメッセージが届いた際に行われます。 * **日次リセット**: デフォルトは **ゲートウェイホストの現地時間で午前 4:00** です。前回の更新がこの時間を跨いでいる場合、新しいセッション ID が発行されます。 * **アイドルリセット**: `idleMinutes` を設定することで、一定時間操作がない場合にリセットできます。日次リセットと併用した場合、どちらか早い方のタイミングでリセットされます。 * **リセットトリガー**: `/new` または `/reset` メッセージを送ると、即座に新しいセッションが開始されます。`/new <モデル名>` のように指定して、新しいセッションで使用するモデルを変更することも可能です。 * **手動リセット**: `sessions.json` から特定のエントリを削除するか、JSONL ファイルを削除することで、強制的にリセットできます。 ## 送信ポリシー (Send Policy) 特定のセッションタイプ（例: Discord のグループチャットのみ等）に対して、一括で送信を制限できます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { session: { sendPolicy: { rules: [ { action: "deny", match: { channel: "discord", chatType: "group" } }, { action: "deny", match: { keyPrefix: "cron:" } }, ], default: "allow", }, }, } ``` チャット内からの上書き（所有者のみ）: * `/send on` → このセッションでの送信を許可。 * `/send off` → このセッションでの送信を拒否。 * `/send inherit` → 上書きを解除し、構成ファイルの設定に従う。 ## 検査とデバッグ * `openclaw status`: ストアのパスと最近のセッションを表示します。 * `openclaw sessions --json`: すべてのエントリをダンプします。 * チャットで `/status` を送る: エージェントの到達可能性、コンテキストの消費量、現在の設定などを確認できます。 * チャットで `/context list` を送る: システムプロンプトに含まれる内容や、消費量の多い要因を確認できます。 * チャットで `/stop` を送る: 現在の実行を中止し、キューに溜まったメッセージをクリアします。 * チャットで `/compact` を送る: 古い履歴を要約して、コンテキストウィンドウの空きを増やします。詳細は [圧縮（コンパクション）](/concepts/compaction) を参照してください。 # セッションプルーニング (削減) Source: https://openclawdoc.org/concepts/session-pruning セッションプルーニングは、LLM を呼び出す直前に、メモリ上のコンテキストから 古いツールの実行結果 をトリミング（削減）する機能です。ディスク上のセッション履歴 (*.jsonl) を書き換えることは ありません。 セッションプルーニングは、LLM を呼び出す直前に、メモリ上のコンテキストから **古いツールの実行結果** をトリミング（削減）する機能です。ディスク上のセッション履歴 (`*.jsonl`) を書き換えることは **ありません**。 ## 実行のタイミング * `mode: "cache-ttl"` が有効で、そのセッションの直前の Anthropic 呼び出しから `ttl` 以上の時間が経過している場合に実行されます。 * その回のリクエストでモデルに送信されるメッセージ群にのみ影響します。 * Anthropic API（および OpenRouter 経由の Anthropic モデル）への呼び出し時のみ有効です。 * モデルの `cacheRetention` ポリシー（`short` = 5分, `long` = 1時間）に合わせて `ttl` を設定すると、最も効果的です。 * プルーニングが実行されると TTL ウィンドウがリセットされ、再び `ttl` が経過するまでは以降のリクエストでもキャッシュが維持されます。 ## スマートデフォルト (Anthropic) * **OAuth または setup-token** プロファイルを使用する場合: `cache-ttl` プルーニングが有効になり、ハートビート間隔が `1h` に設定されます。 * **API キー** プロファイルを使用する場合: `cache-ttl` プルーニングが有効になり、ハートビート間隔が `30m`、Anthropic モデルの `cacheRetention` がデフォルトで `"short"` に設定されます。 * これらの値を構成ファイルで明示的に設定している場合、OpenClaw はそれらの値を上書きしません。 ## 導入のメリット (コストとキャッシュ挙動) * **なぜプルーニングが必要か**: Anthropic のプロンプトキャッシュは TTL（有効期間）内でのみ有効です。セッションが TTL を超えてアイドル状態になると、次にリクエストを送る際に、事前にトリミングを行わない限りプロンプト全体が再キャッシュ（課金対象）されてしまいます。 * **コスト削減効果**: TTL 経過後の最初の回において、プルーニングにより **cacheWrite** のサイズを削減できます。 * **TTL リセットの意味**: プルーニングが実行されるとキャッシュの有効期間がリセットされるため、その後の連続したリクエストでは、履歴全体を再キャッシュすることなく、新しくキャッシュされたプロンプトを再利用できます。 * **注意点**: プルーニング自体がトークンを増やしたり、コストを「二重に」発生させたりすることはありません。あくまで TTL 経過後の最初のリクエストでキャッシュされる内容を調整するだけです。 ## 削減の対象となるもの * `toolResult` メッセージ（ツールの実行結果）のみが対象です。 * ユーザーやアシスタントのメッセージが変更されることは **ありません**。 * 直近の `keepLastAssistants` 件のアシスタントメッセージは保護され、それ以降のツール結果はプルーニングされません。 * 基準を満たす十分な数のアシスタントメッセージがない場合、プルーニングはスキップされます。 * **画像ブロック** を含むツールの結果は、スキップ（トリミングや消去の対象外）されます。 ## コンテキストウィンドウの推定 プルーニングでは推定されたコンテキストウィンドウサイズ（文字数 ≈ トークン数 × 4）を使用します。基準となるウィンドウサイズは以下の優先順位で決定されます: 1. `models.providers.*.models[].contextWindow` の上書き設定。 2. モデルカタログに定義された `contextWindow`。 3. デフォルト値の `200000` トークン。 `agents.defaults.contextTokens` が設定されている場合、解決されたウィンドウサイズの上限（最小値）として扱われます。 ## モード ### cache-ttl * 直前の Anthropic 呼び出しから `ttl` (デフォルト `5m`) 以上経過している場合にのみ実行されます。 * 実行時の挙動: 後述の「ソフトトリム」と「ハードクリア」を行います。 ## ソフトプルーニング vs ハードプルーニング * **ソフトトリム (Soft-trim)**: サイズ超過したツール結果に対して行われます。 * 先頭と末尾を残して中間を `...` で置き換え、元のサイズを記した注釈を付記します。 * 画像ブロックを含む結果はスキップされます。 * **ハードクリア (Hard-clear)**: ツール結果全体を `hardClear.placeholder` に置き換えます。 ## 対象ツールの選択 * `tools.allow` / `tools.deny` では `*` ワイルドカードを使用できます。 * 拒否（deny）設定が優先されます。 * 一致判定は大文字小文字を区別しません。 * 許可リストが空の場合は、すべてのツールが対象となります。 ## 他の制限機能との関係 * 組み込みツールは既に自身の出力を切り捨てる機能を備えています。セッションプルーニングは、長時間のチャットによってモデルのコンテキストにツール出力が過剰に蓄積されるのを防ぐための追加のレイヤーです。 * 圧縮（Compaction）とは別の機能です。圧縮は内容を要約して履歴ファイルを **書き換え** ますが、プルーニングはリクエストごとの一時的な処理です。詳細は [圧縮（コンパクション）](/concepts/compaction) を参照してください。 ## デフォルト設定 (有効時) * `ttl`: `"5m"` * `keepLastAssistants`: `3` * `softTrimRatio`: `0.3` * `hardClearRatio`: `0.5` * `minPrunableToolChars`: `50000` * `softTrim`: `{ maxChars: 4000, headChars: 1500, tailChars: 1500 }` * `hardClear`: `{ enabled: true, placeholder: "[古いツールの実行結果が消去されました]" }` ## 構成例 デフォルト（オフ）: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { contextPruning: { mode: "off" } } }, } ``` TTL を考慮したプルーニングを有効化: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { contextPruning: { mode: "cache-ttl", ttl: "5m" } } }, } ``` 特定のツールに限定してプルーニングを行う: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { contextPruning: { mode: "cache-ttl", tools: { allow: ["exec", "read"], deny: ["*image*"] }, }, }, }, } ``` 構成リファレンス: [ゲートウェイ構成](/gateway/configuration) # セッションツール Source: https://openclawdoc.org/concepts/session-tool 目的: エージェントがセッションの一覧を確認し、過去の履歴を取得し、別のセッションへメッセージを送信できるようにするための、シンプルで誤用しにくいツールセットを提供することです。 目的: エージェントがセッションの一覧を確認し、過去の履歴を取得し、別のセッションへメッセージを送信できるようにするための、シンプルで誤用しにくいツールセットを提供することです。 ## ツール一覧 * `sessions_list` * `sessions_history` * `sessions_send` * `sessions_spawn` ## セッションキーのモデル * メインのダイレクトチャットは、常にリテラル（文字通り）のキー `"main"` を使用します（現在のエージェントのメインキーに解決されます）。 * グループチャットは `agent:::group:` または `agent:::channel:` の形式です（完全なキーを渡してください）。 * Cron ジョブは `cron:` です。 * Webhook は明示的に設定されていない限り `hook:` です。 * ノードセッションは明示的に設定されていない限り `node-` です。 `global` および `unknown` は予約された値であり、一覧には表示されません。`session.scope = "global"` の場合、すべてのツールにおいて `main` の別名として扱われるため、呼び出し側が `global` という値を直接目にすることはありません。 ## `sessions_list` セッションを配列形式で一覧表示します。 **パラメータ:** * `kinds?: string[]`: フィルタリング。`"main" | "group" | "cron" | "hook" | "node" | "other"` のいずれかを指定。 * `limit?: number`: 最大取得件数（デフォルトはサーバー設定に従います。例：200件）。 * `activeMinutes?: number`: 指定した分以内に更新されたセッションのみを抽出。 * `messageLimit?: number`: 履歴を含めるかどうか。`0` = 含めない（デフォルト）、`>0` = 直近 N 件のメッセージを含める。 **挙動:** * `messageLimit > 0` の場合、各セッションの `chat.history` から直近 N 件のメッセージを取得して含めます。 * 一覧出力からはツール実行結果（toolResult）は除外されます。ツールのメッセージを確認したい場合は `sessions_history` を使用してください。 * **サンドボックス化** されたエージェントセッションで実行している場合、セッションツールで見える範囲はデフォルトで **自身が生成（spawn）したもののみ** に制限されます（詳細は後述）。 **行のデータ構造 (JSON):** * `key`: セッションキー（文字列） * `kind`: `main | group | cron | hook | node | other` * `channel`: `whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown` * `displayName`: グループの表示名（利用可能な場合） * `updatedAt`: 最終更新日時（ミリ秒） * `sessionId`: セッション ID * `model`, `contextTokens`, `totalTokens`: 使用モデルとトークン統計 * `thinkingLevel`, `verboseLevel`, `systemSent`, `abortedLastRun`: 実行設定とステータス * `sendPolicy`: セッションごとの送信ポリシー上書き設定 * `lastChannel`, `lastTo`: 最終送信先情報 * `deliveryContext`: 正規化された配信コンテキスト（`{ channel, to, accountId }`） * `transcriptPath`: 履歴ファイルのパス（ベストエフォート） * `messages?`: `messageLimit > 0` の場合にのみ含まれるメッセージ配列 ## `sessions_history` 特定のセッションの会話記録（トランスクリプト）を取得します。 **パラメータ:** * `sessionKey`: 必須。セッションキー、または `sessions_list` から取得した `sessionId`。 * `limit?: number`: 最大メッセージ取得数。 * `includeTools?: boolean`: ツールメッセージを含めるかどうか（デフォルトは `false`）。 **挙動:** * `includeTools=false` の場合、`role: "toolResult"` のメッセージを除外します。 * メッセージを生の記録形式の配列で返します。 * `sessionId` が指定された場合、OpenClaw は対応するセッションキーを自動的に解決します。 ## `sessions_send` 別のセッションに対してメッセージを送信します。 **パラメータ:** * `sessionKey`: 必須。送信先のセッションキー、または `sessionId`。 * `message`: 必須。送信するメッセージ内容。 * `timeoutSeconds?: number`: 待機時間（デフォルトは 0 より大きい値。`0` は送信のみ行う fire-and-forget 方式）。 **挙動:** * `timeoutSeconds = 0`: 実行キューに追加し、即座に `{ runId, status: "accepted" }` を返します。 * `timeoutSeconds > 0`: 完了まで最大 N 秒待機し、`{ runId, status: "ok", reply }` を返します。 * タイムアウトした場合: `{ runId, status: "timeout", error }`。実行自体は継続されるため、後で `sessions_history` で結果を確認してください。 * 実行が失敗した場合: `{ runId, status: "error", error }`。 * 通知（Announce）の配信は、メインの実行完了後にベストエフォートで行われます。`status: "ok"` は通知の到達を保証するものではありません。 * ゲートウェイの `agent.wait` を介して待機するため、通信が一時的に切断されても待機状態は維持されます。 * 送信先のエージェントには、エージェント間メッセージである旨のコンテキストが注入されます。 * メッセージには `message.provenance.kind = "inter_session"` が付与されるため、履歴を確認する際にユーザー入力とエージェントからの指示を区別できます。 * メインの実行完了後、OpenClaw は **返信ループ（ピンポン）** を実行します: * 2 ターン目以降は、依頼元と送信先のエージェントが交互に応答します。 * ループを終了するには、メッセージとして正確に `REPLY_SKIP` と返します。 * 最大ターン数は `session.agentToAgent.maxPingPongTurns` (0〜5、デフォルト 5) です。 * ループ終了後、送信先エージェントのみが **アナウンスステップ** を実行します: * 何も送信したくない場合は `ANNOUNCE_SKIP` と返します。 * それ以外の場合、最終的な応答がチャネルに送信されます。 * アナウンス内容には、最初の依頼内容、1 回目の返信、および最新のやり取りが含まれます。 ## チャネルフィールドの扱い * グループの場合、セッションエントリに記録されたチャネルが `channel` となります。 * ダイレクトチャットの場合、`lastChannel` からマップされます。 * Cron/Webhook/ノードの場合、`channel` は `internal` です。 * 不明な場合は `unknown` となります。 ## セキュリティ / 送信ポリシー チャネルやチャット形式に基づいたブロック設定が可能です。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "session": { "sendPolicy": { "rules": [ { "match": { "channel": "discord", "chatType": "group" }, "action": "deny" } ], "default": "allow" } } } ``` 実行時の上書き（セッションごと）: * `sendPolicy: "allow" | "deny"` (未設定時は構成を継承) * `sessions.patch` ツール、または所有者による `/send on|off|inherit` コマンドで設定可能。 適用タイミング: * `chat.send` / `agent` (ゲートウェイ) * 自動応答の配信ロジック ## `sessions_spawn` 分離されたセッションでサブエージェントを起動し、その結果を依頼元のチャットチャネルに通知します。 **パラメータ:** * `task`: 必須。実行させるタスク内容。 * `label?`: 任意。ログや UI で使用されるラベル。 * `agentId?`: 任意。許可されていれば、別のエージェント ID として起動。 * `model?`: 任意。サブエージェントが使用するモデルを上書き。 * `thinking?`: 任意。サブエージェントの思考レベルを上書き。 * `runTimeoutSeconds?`: 実行タイムアウト秒数（デフォルトは `agents.defaults.subagents.runTimeoutSeconds`）。 * `thread?`: 任意（デフォルト `false`）。チャネルが対応している場合、スレッドに紐付いたルーティングを要求。 * `mode?`: `run | session` (デフォルト `run`)。`thread=true` の場合は `session` がデフォルト。 * `cleanup?`: `delete | keep` (デフォルト `keep`)。終了後の処理。 * `sandbox?`: `inherit | require` (デフォルト `inherit`)。`require` の場合、送信先がサンドボックス化されていないと起動を拒否。 * `attachments?`: 任意。インラインファイルの配列（サブエージェントランタイムのみ）。ファイルは `.openclaw/attachments//` に作成されます。 * `attachAs?`: 任意。将来のマウント実装用のヒント。 **許可リスト:** * `agents.list[].subagents.allowAgents`: 指定可能なエージェント ID のリスト（`["*"]` で全許可）。デフォルトは依頼元と同じ ID のみ。 * サンドボックス継承ガード: 依頼元のセッションがサンドボックス化されている場合、サンドボックスなしで実行されるターゲットへの `sessions_spawn` は拒否されます。 **挙動:** * `deliver: false` 設定で、新しい `agent::subagent:` セッションを開始します。 * サブエージェントは、デフォルトで **セッションツールを除いた** すべてのツールを利用可能です（`tools.subagents.tools` で変更可能）。 * サブエージェントがさらに `sessions_spawn` を呼び出すことはできません（入れ子の生成は不可）。 * 常に非ブロッキング（非同期）で動作し、即座に `{ status: "accepted", runId, childSessionKey }` を返します。 * 完了後、OpenClaw は **アナウンスステップ** を実行し、結果を依頼元のチャネルに投稿します。 * モデルの返信が空の場合、履歴内の最後の `toolResult` が `Result` として採用されます。 * アナウンスを行いたくない場合は、アナウンスステップ中に `ANNOUNCE_SKIP` と返してください。 * 投稿される内容は `Status`, `Result`, `Notes` に正規化されます。`Status` はモデルのテキストではなく、実際の実行結果から決定されます。 * サブエージェントのセッションは、`agents.defaults.subagents.archiveAfterMinutes`（デフォルト 60 分）経過後に自動的にアーカイブされます。 ## サンドボックスセッションの可視性 セッションツールがアクセスできる範囲を制限して、セッションを跨いだ操作を抑制できます。 **デフォルトの挙動:** * `tools.sessions.visibility` はデフォルトで `tree` (現在のセッション + 自身が生成したサブエージェント) です。 * サンドボックス化されたセッションでは、`agents.defaults.sandbox.sessionToolsVisibility` によってさらに厳格に制限できます。 **構成例:** ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { tools: { sessions: { // "self" | "tree" | "agent" | "all" visibility: "tree", }, }, agents: { defaults: { sandbox: { // デフォルト: "spawned" sessionToolsVisibility: "spawned", // または "all" }, }, }, } ``` 補足: * `self`: 現在のセッションのみ。 * `tree`: 現在のセッションと、そこから派生したすべてのセッション。 * `agent`: 現在のエージェント ID に属するすべてのセッション。 * `all`: すべてのセッション（エージェントを跨ぐ場合は `tools.agentToAgent` の許可も必要）。 * セッションがサンドボックス化され、`sessionToolsVisibility="spawned"` が設定されている場合、`tools.sessions.visibility="all"` と設定していても、OpenClaw は強制的に `tree` の範囲に制限します。 # ストリーミングとチャンク化 Source: https://openclawdoc.org/concepts/streaming 現時点では、チャネルメッセージに対する 完全なトークン単位のストリーミング はありません。プレビュー表示はメッセージベースの処理（送信、編集、追記）によって実現されています。 OpenClaw には、2 つの異なるストリーミング層があります: * **ブロックストリーミング (チャネル)**: アシスタントが回答を生成する過程で、完了した「ブロック」単位でメッセージを送信します。これらは通常のチャネルメッセージ（吹き出し）として届きます。 * **プレビュー表示 (Telegram/Discord/Slack)**: 回答の生成中に、一時的な「プレビューメッセージ」の内容をリアルタイムで更新し続けます。 現時点では、チャネルメッセージに対する **完全なトークン単位のストリーミング** はありません。プレビュー表示はメッセージベースの処理（送信、編集、追記）によって実現されています。 ## ブロックストリーミング (チャネルメッセージ) ブロックストリーミングは、アシスタントの出力が一定量まとまるたびに、粗いチャンク（塊）として送信します。 ``` モデルの出力 └─ text_delta (差分) / イベント ├─ (blockStreamingBreak=text_end の場合) │ └─ チャンカーがバッファの蓄積に合わせてブロックを発行 └─ (blockStreamingBreak=message_end の場合) └─ ターン終了時にまとめてフラッシュ (送信) └─ チャネル送信 (ブロック単位の返信) ``` **コントロール項目:** * `agents.defaults.blockStreamingDefault`: `"on"` / `"off"` (デフォルトは off)。 * チャネルごとの上書き: `*.blockStreaming` (およびアカウントごとの設定)。チャネルごとに強制的に有効・無効を切り替えられます。 * `agents.defaults.blockStreamingBreak`: `"text_end"` (文の区切りなど) または `"message_end"` (ターンの終わり)。 * `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }` (最小/最大文字数と分割優先度)。 * `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (送信前に短いチャンクを結合)。 * チャネルのハードリミット: `*.textChunkLimit` (例: WhatsApp は 4000 文字)。 * チャネルの分割モード: `*.chunkMode` (`length` (デフォルト) または `newline` (空行による段落区切りを優先))。 * Discord のソフトリミット: `channels.discord.maxLinesPerMessage` (デフォルト 17 行)。UI での表示切れを防ぐために縦に長い返信を分割します。 **区切りのセマンティクス:** * `text_end`: チャンカーがブロックを切り出した直後に送信します。各 `text_end` イベントでフラッシュされます。 * `message_end`: アシスタントの生成が完全に終了するまで待ち、バッファに溜まった内容をフラッシュします。 `message_end` を使用した場合でも、バッファ内のテキストが `maxChars` を超えている場合はチャンカーが動作し、最終的に複数の吹き出しに分かれて送信されることがあります。 ## チャンク化アルゴリズム (最小/最大範囲) ブロックの切り出しは `EmbeddedBlockChunker` によって行われます: * **最小範囲 (Low bound)**: バッファが `minChars` 以上になるまで（強制されない限り）送信しません。 * **最大範囲 (High bound)**: `maxChars` を超える前に分割することを優先しますが、適切な区切りが見つからず上限に達した場合はそこで強制的に分割します。 * **分割の優先度 (Break preference)**: 段落 (`paragraph`) → 改行 (`newline`) → 文の終わり (`sentence`) → 空白 (`whitespace`) → 強制分割。 * **コードブロック (Code fences)**: 原則としてコードブロック内で分割しません。どうしても `maxChars` で分割が必要な場合は、Markdown の整合性を保つために、一度ブロックを閉じて次のメッセージで開き直します。 `maxChars` は各チャネルの `textChunkLimit` を超えないように自動的に調整（クランプ）されます。 ## 結合 (ストリームされたブロックのマージ) ブロックストリーミングが有効な場合、OpenClaw は送信前に **連続するチャンクをマージ（結合）** することができます。これにより、短いメッセージが連投されるのを防ぎつつ、段階的な出力を提供できます。 * 結合処理は、入力が止まるまで（`idleMs`）フラッシュを待ちます。 * バッファが `maxChars` を超えた場合は、タイマーに関わらずフラッシュされます。 * `minChars` 設定により、十分なテキストが蓄積されるまで小さな断片の送信を保留します（最終的なフラッシュでは残りのテキストがすべて送信されます）。 * 結合時の繋ぎ目は `blockStreamingChunk.breakPreference` に基づきます（段落 → `\n\n`、改行 → `\n`、文末 → スペース）。 * チャネルごとの上書き設定は `*.blockStreamingCoalesce` で可能です。 * Signal, Slack, Discord では、上書きがない場合のデフォルトの結合文字数 `minChars` が 1500 に引き上げられています。 ## ブロック間の人間らしい一時停止 (Human-like pacing) ブロックストリーミングが有効な場合、複数の吹き出しを送信する間に **ランダムな一時停止** を挟むことができます。これにより、複数メッセージでの回答がより自然に感じられるようになります。 * 構成: `agents.defaults.humanDelay` (エージェントごとの上書きは `agents.list[].humanDelay`)。 * モード: `off` (デフォルト), `natural` (800〜2500ms), `custom` (`minMs`/`maxMs` を指定)。 * 対象: ブロック返信（部分的な回答）にのみ適用されます。最終的な回答やツールの要約には適用されません。 ## ストリーミングのパターン * **チャンクごとにストリーム**: `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`。Telegram 以外のチャネルでは `*.blockStreaming: true` も必要です。 * **最後にまとめて送信**: `blockStreamingBreak: "message_end"`。回答が非常に長い場合は複数の吹き出しになる可能性があります。 * **ブロックストリーミングなし**: `blockStreamingDefault: "off"`。回答が完了してから最終的なメッセージのみを送信します。 **チャネルに関する注意**: ブロックストリーミングは、`*.blockStreaming` が明示的に `true` に設定されていない限り **オフ** です。チャネル側でプレビュー表示設定 (`channels..streaming`) が有効であっても、ブロック返信が行われるとは限りません。 ## プレビュー表示モード 構成キー: `channels..streaming` モード: * `off`: プレビュー表示を無効にします。 * `partial`: 1 つのプレビューメッセージを最新のテキストで常に上書きします。 * `block`: プレビューメッセージにチャンク（塊）を追記していきます。 * `progress`: 生成中は進捗やステータスを表示し、完了後に最終的な回答に置き換えます。 ### チャネルごとの対応状況 | チャネル | `off` | `partial` | `block` | `progress` | | :------- | :---: | :-------: | :-----: | :-------------: | | Telegram | ✅ | ✅ | ✅ | `partial` として動作 | | Discord | ✅ | ✅ | ✅ | `partial` として動作 | | Slack | ✅ | ✅ | ✅ | ✅ | Slack 専用: * `channels.slack.nativeStreaming`: `streaming=partial` の場合に Slack ネイティブのストリーミング API を使用するかどうか (デフォルト: `true`)。 レガシー設定の移行: * Telegram/Discord: `streamMode` やブール値の `streaming` は、自動的に新しい enum 形式に移行されます。 * Slack: `streamMode` は新しい enum 形式に、ブール値の `streaming` は `nativeStreaming` に移行されます。 ### 実行時の挙動 **Telegram:** * DM およびグループ/トピックにおいて、`sendMessage` + `editMessageText` を使用して更新します。 * Telegram のブロックストリーミングが有効な場合、表示の重複を避けるためにプレビュー表示はスキップされます。 * `/reasoning stream` が設定されている場合、推論プロセスをプレビューに書き込むことができます。 **Discord:** * プレビューメッセージの送信と編集（edit）を使用します。 * `block` モードでは、ドラフト用のチャンク化 (`draftChunk`) が使用されます。 * Discord のブロックストリーミングが有効な場合、プレビュー表示はスキップされます。 **Slack:** * `partial` モードでは、利用可能な場合に Slack ネイティブのストリーミング API (`chat.startStream` / `append` / `stop`) を使用できます。 * `block` モードでは、追記型のドラフトプレビューを使用します。 * `progress` モードでは、ステータスを表示した後に最終回答を投稿します。 # システムプロンプト Source: https://openclawdoc.org/concepts/system-prompt OpenClaw は、エージェントを実行するたびにカスタムのシステムプロンプトを構築します。このプロンプトは OpenClaw が管理する独自のもの であり、pi-coding-agent のデフォルトプロンプトは使用されません。 OpenClaw は、エージェントを実行するたびにカスタムのシステムプロンプトを構築します。このプロンプトは **OpenClaw が管理する独自のもの** であり、pi-coding-agent のデフォルトプロンプトは使用されません。 ## プロンプトの構造 プロンプトは意図的にコンパクトに保たれており、以下の固定セクションで構成されています: * **Tooling**: 利用可能なツールの一覧と短い説明。 * **Safety**: エージェントが独断で権限を拡大したり、監視を回避したりしないようにするための、短いガードレール（指針）。 * **Skills** (利用可能な場合): 必要に応じてスキルの指示内容をロードする方法。 * **OpenClaw Self-Update**: `config.apply` や `update.run` を実行する方法。 * **Workspace**: 作業ディレクトリ (`agents.defaults.workspace`)。 * **Documentation**: ローカルの OpenClaw ドキュメントへのパスと、それらを参照すべきタイミング。 * **Workspace Files (injected)**: 下記のブートストラップファイルが含まれていることを示します。 * **Sandbox** (有効な場合): サンドボックス化された実行環境の情報、パス、および権限昇格が可能かどうか。 * **Current Date & Time**: ユーザーの現地時間、タイムゾーン、および時刻形式。 * **Reply Tags**: 対応チャネルにおけるオプションの返信タグ構文。 * **Heartbeats**: ハートビート（定期実行）時のプロンプトと確認（ack）の挙動。 * **Runtime**: ホスト名、OS、ノード、モデル、リポジトリルート（検出時）、および思考レベル（1 行）。 * **Reasoning**: 現在の推論プロセスの可視化レベルと `/reasoning` コマンドのヒント。 システムプロンプト内の安全ガードレールはあくまで「助言」です。モデルの挙動をガイドしますが、ポリシーを強制するものではありません。強制力を持たせるには、ツールポリシー、実行承認（exec approvals）、サンドボックス、およびチャネルの許可リストを使用してください。これらは設計上、管理者によって無効化することが可能です。 ## プロンプトモード OpenClaw は、サブエージェント向けにさらに小さなシステムプロンプトを生成できます。実行時に `promptMode` が設定されます（ユーザー設定項目ではありません）: * `full` (デフォルト): 上記のすべてのセクションを含みます。 * `minimal`: サブエージェントに使用されます。**Skills**, **Memory Recall**, **OpenClaw Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**, **Messaging**, **Silent Replies**, **Heartbeats** が省略されます。Tooling, **Safety**, Workspace, Sandbox, 時刻（判明している場合）, Runtime, および注入されたコンテキストは引き続き利用可能です。 * `none`: 基本的なアイデンティティ情報のみを返します。 `promptMode=minimal` の場合、追加で注入されたプロンプトのラベルは **Group Chat Context** ではなく **Subagent Context** になります。 ## ワークスペースブートストラップの注入 ブートストラップファイルは適宜切り詰められ、**Project Context** セクションの下に追加されます。これにより、モデルは明示的な `read` を行わなくても、アイデンティティやプロフィールの文脈を把握できます: * `AGENTS.md` * `SOUL.md` * `TOOLS.md` * `IDENTITY.md` * `USER.md` * `HEARTBEAT.md` * `BOOTSTRAP.md` (新規ワークスペースの場合のみ) * `MEMORY.md` および/または `memory.md` (ワークスペース内に存在する場合) これらのファイルは実行のたびに **コンテキストウィンドウ内に注入される** ため、トークンを消費します。内容は簡潔に保ってください。特に `MEMORY.md` は時間とともに肥大化しやすく、予期せぬコンテキスト消費や頻繁な圧縮（コンパクション）の原因となります。 > **注意:** `memory/*.md` の日次ログファイルは、自動的には注入 **されません**。これらは `memory_search` や `memory_get` ツールを介してオンデマンドでアクセスされるため、モデルが明示的に読み取らない限り、コンテキストウィンドウを消費することはありません。 巨大なファイルはマーカーと共に切り詰められます。ファイルごとの上限は `agents.defaults.bootstrapMaxChars`（デフォルト 20,000）で制御されます。全ファイルの合計上限は `agents.defaults.bootstrapTotalMaxChars`（デフォルト 150,000）です。ファイルが欠落している場合は「missing」マーカーが注入されます。切り詰めが発生した際に警告を注入するかどうかは `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`。デフォルトは `once`) で設定可能です。 サブエージェントのセッションでは、コンテキストを小さく保つために `AGENTS.md` と `TOOLS.md` のみが注入され、他のファイルは除外されます。 内部フック `agent:bootstrap` を使用して、注入される内容を変更したり、別のペルソナ用の `SOUL.md` に差し替えたりすることが可能です。 注入された各ファイルがどの程度コンテキストを消費しているか（生のサイズ vs 注入サイズ、切り詰め、ツールスキーマによるオーバーヘッドなど）を確認するには、`/context list` または `/context detail` を使用してください。詳細は [コンテキスト](/concepts/context) を参照してください。 ## 時刻の扱い システムプロンプトには、ユーザーのタイムゾーンが判明している場合に **Current Date & Time** セクションが含まれます。プロンプトキャッシュを安定させるため、現在は **タイムゾーン名** のみが含まれています（動的な時刻や形式は含まれません）。 エージェントが現在時刻を必要とする場合は、`session_status` ツールを使用します。このツールのステータスカードには現在のタイムスタンプ行が含まれています。 時刻関連の設定: * `agents.defaults.userTimezone` * `agents.defaults.timeFormat` (`auto` | `12` | `24`) 詳細は [日付と時刻](/date-time) を参照してください。 ## スキル (Skills) 実行条件を満たすスキルがある場合、OpenClaw は各スキルの **ファイルパス** を含むコンパクトな **利用可能なスキル一覧** (`formatSkillsForPrompt`) を注入します。プロンプト内では、必要に応じてそのパスにある `SKILL.md` を `read` ツールで読み込むようモデルに指示されます。利用可能なスキルがない場合、このセクションは省略されます。 ``` ... ... ... ``` これにより、ベースのプロンプトを小さく保ちつつ、必要になったタイミングで特定のスキルを活用させることができます。 ## ドキュメント (Documentation) 利用可能な場合、システムプロンプトには **Documentation** セクションが含まれます。これはローカルの OpenClaw ドキュメントディレクトリ（リポジトリ内の `docs/` または npm パッケージに同梱されているもの）を指し、同時に公開ミラー、ソースリポジトリ、コミュニティ Discord、およびスキルの検索場所である ClawHub ([https://clawhub.com](https://clawhub.com)) についても言及します。プロンプト内では、OpenClaw の動作、コマンド、構成、またはアーキテクチャについて不明な点がある場合は、まずこれらのローカルドキュメントを参照するようモデルに指示されます。また、可能な限り `openclaw status` を自分自身で実行して確認し、どうしてもアクセスできない場合にのみユーザーに尋ねるよう指示されています。 # OpenClaw Source: https://openclawdoc.org/index OpenClaw の役割、対応チャネル、エージェント連携、導入導線をまとめたトップレベルの概要ページです。

OpenClaw OpenClaw

> *「EXFOLIATE! EXFOLIATE!」* — たぶん宇宙ロブスター

WhatsApp、Telegram、Discord、iMessage などをまたぐ AI エージェント向けのあらゆる OS 対応 Gateway。
メッセージを送るだけで、ポケットからエージェントの応答が届きます。プラグインで Mattermost なども追加可能です。

OpenClaw をインストールし、数分で Gateway を起動できます。 `openclaw onboard` とペアリングフローによるガイド付きセットアップ。 チャット、設定、セッション管理用のブラウザダッシュボードを起動します。 ## OpenClaw とは？ OpenClaw は、お気に入りのチャットアプリ — WhatsApp、Telegram、Discord、iMessage など — を Pi のような AI コーディングエージェントに接続する**セルフホスト型 Gateway** です。自分のマシン（またはサーバー）上で単一の Gateway プロセスを実行するだけで、メッセージングアプリと常時利用可能な AI アシスタントの橋渡しになります。 **誰のためのもの？** どこからでもメッセージを送れるパーソナル AI アシスタントが欲しいけれど、データの管理権を手放したくない、ホスト型サービスに依存したくない開発者やパワーユーザー向けです。 **何が違うのか？** * **セルフホスト型**: 自分のハードウェアで動作し、自分のルールで運用 * **マルチチャンネル**: 1 つの Gateway で WhatsApp、Telegram、Discord などを同時に提供 * **エージェントネイティブ**: ツール使用、セッション、メモリ、マルチエージェントルーティングを備えたコーディングエージェント向けに構築 * **オープンソース**: MIT ライセンス、コミュニティ主導 **何が必要？** Node 22 以上、選択したプロバイダーの API キー、そして 5 分間。最高の品質とセキュリティのために、利用可能な最新世代の最も強力なモデルを使用してください。 ## 仕組み ```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}} flowchart LR A["チャットアプリ + プラグイン"] --> B["Gateway"] B --> C["Pi エージェント"] B --> D["CLI"] B --> E["Web Control UI"] B --> F["macOS アプリ"] B --> G["iOS / Android ノード"] ``` Gateway は、セッション、ルーティング、チャンネル接続の単一の信頼できる情報源です。 ## 主な機能 単一の Gateway プロセスで WhatsApp、Telegram、Discord、iMessage に対応。 拡張パッケージで Mattermost などを追加。 エージェント、ワークスペース、送信者ごとに分離されたセッション。 画像、音声、ドキュメントの送受信。 チャット、設定、セッション、ノード管理用のブラウザダッシュボード。 iOS / Android ノードをペアリングして、Canvas、カメラ、音声対応ワークフローを実現。 ## クイックスタート ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm install -g openclaw@latest ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard --install-daemon ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels login openclaw gateway --port 18789 ``` 完全なインストールと開発セットアップが必要ですか？[クイックスタート](/start/quickstart)を参照してください。 ## ダッシュボード Gateway の起動後にブラウザで Control UI を開きます。 * ローカルデフォルト: [http://127.0.0.1:18789/](http://127.0.0.1:18789/) * リモートアクセス: [Web サーフェス](/web)および [Tailscale](/gateway/tailscale)

OpenClaw

## 設定（オプション） 設定ファイルは `~/.openclaw/openclaw.json` にあります。 * **何もしなければ**、OpenClaw は送信者ごとのセッションで RPC モードのバンドル済み Pi バイナリを使用します。 * ロックダウンしたい場合は、`channels.whatsapp.allowFrom` と（グループの場合は）メンションルールから始めてください。 例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { allowFrom: ["+15555550123"], groups: { "*": { requireMention: true } }, }, }, messages: { groupChat: { mentionPatterns: ["@openclaw"] } }, } ``` ## ここから始めましょう ユースケース別に整理されたすべてのドキュメントとガイド。 Gateway のコア設定、トークン、プロバイダー設定。 SSH および tailnet アクセスパターン。 WhatsApp、Telegram、Discord などのチャンネル固有のセットアップ。 ペアリング、Canvas、カメラ、デバイスアクションを備えた iOS / Android ノード。 よくある修正方法とトラブルシューティングの入口。 ## さらに詳しく チャンネル、ルーティング、メディア機能の完全なリスト。 ワークスペースの分離とエージェントごとのセッション。 トークン、許可リスト、安全管理。 Gateway の診断とよくあるエラー。 プロジェクトの起源、コントリビューター、ライセンス。 # Ansible Source: https://openclawdoc.org/install/ansible openclaw-ansible を使って、本番サーバーへ安全に OpenClaw を自動導入する手順と運用方法をまとめます。 OpenClaw を本番サーバーへデプロイする推奨手段は、**[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** を使う方法です。これは、セキュリティを優先した設計の自動インストーラーです。 ## クイックスタート 1 コマンドでインストールできます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash ``` > **完全ガイド: [github.com/openclaw/openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** > > Ansible デプロイに関する一次情報は `openclaw-ansible` リポジトリです。このページは概要だけをまとめています。 ## 導入されるもの * **ファイアウォール優先のセキュリティ**: UFW + Docker 分離により、外部公開は SSH と Tailscale のみ * **Tailscale VPN**: サービスを公開せずに安全なリモートアクセスを確保 * **Docker**: 分離されたサンドボックスコンテナを提供し、localhost バインドを維持 * **多層防御**: 4 層のセキュリティアーキテクチャ * **1 コマンドセットアップ**: 数分で一式をデプロイ * **systemd 統合**: ハードニング付きで起動時に自動起動 ## 要件 * **OS**: Debian 11 以降、または Ubuntu 20.04 以降 * **権限**: root または sudo 権限 * **ネットワーク**: パッケージを取得できるインターネット接続 * **Ansible**: 2.14 以降 (クイックスタートスクリプトが自動で導入) ## インストールされる内容 Ansible playbook では、次をインストールして設定します。 1. **Tailscale** (安全なリモートアクセス用のメッシュ VPN) 2. **UFW firewall** (SSH + Tailscale のポートのみ許可) 3. **Docker CE + Compose V2** (エージェント用サンドボックスで使用) 4. **Node.js 22.x + pnpm** (実行に必要な依存関係) 5. **OpenClaw** (コンテナ化せず、ホスト上で実行) 6. **systemd service** (セキュリティ強化付きの自動起動) 補足: ゲートウェイ自体は **Docker ではなくホスト上で直接動作** します。一方で、エージェントのサンドボックスは Docker を使って分離します。詳細は [Sandboxing](/gateway/sandboxing) を参照してください。 ## インストール後のセットアップ インストールが完了したら、`openclaw` ユーザーへ切り替えます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo -i -u openclaw ``` post-install スクリプトの案内に従って、次を進めます。 1. **オンボーディングウィザード**: OpenClaw の基本設定 2. **プロバイダーログイン**: WhatsApp / Telegram / Discord / Signal の接続 3. **ゲートウェイテスト**: インストール結果の確認 4. **Tailscale セットアップ**: VPN メッシュへの参加 ### よく使うコマンド ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # サービス状態の確認 sudo systemctl status openclaw # ライブログの確認 sudo journalctl -u openclaw -f # ゲートウェイの再起動 sudo systemctl restart openclaw # プロバイダーログイン (openclaw ユーザーで実行) sudo -i -u openclaw openclaw channels login ``` ## セキュリティアーキテクチャ ### 4 層防御 1. **Firewall (UFW)**: 公開されるのは SSH (22) と Tailscale (41641/udp) のみ 2. **VPN (Tailscale)**: ゲートウェイには VPN メッシュ経由でのみ到達可能 3. **Docker isolation**: `DOCKER-USER` iptables チェーンで外部ポート公開を防止 4. **Systemd hardening**: `NoNewPrivileges`、`PrivateTmp`、非特権ユーザーで実行 ### 検証 外部から見える攻撃面は次で確認できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} nmap -p- YOUR_SERVER_IP ``` **開いているのは 22 番ポート (SSH) のみ** であるべきです。その他のサービス (ゲートウェイ、Docker) はすべて閉じられている想定です。 ### Docker の位置づけ Docker は **エージェント用サンドボックス** (隔離されたツール実行環境) のために導入されます。ゲートウェイ本体は Docker 上では動かず、localhost のみにバインドされ、Tailscale VPN 経由でアクセスします。 サンドボックス設定の詳細は [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) を参照してください。 ## 手動インストール 自動化ではなく、手順を手元で制御したい場合は次の流れでも導入できます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 1. 前提パッケージを導入 sudo apt update && sudo apt install -y ansible git # 2. リポジトリを clone git clone https://github.com/openclaw/openclaw-ansible.git cd openclaw-ansible # 3. Ansible collections を導入 ansible-galaxy collection install -r requirements.yml # 4. Playbook を実行 ./run-playbook.sh # あるいは直接実行 (その場合は後で /tmp/openclaw-setup.sh を手動実行) # ansible-playbook playbook.yml --ask-become-pass ``` ## OpenClaw の更新 Ansible インストーラーで構築した環境では、OpenClaw 本体の更新は手動運用になります。標準の更新手順は [Updating](/install/updating) を参照してください。 設定変更などで Ansible playbook を再実行したい場合は、次を使います。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} cd openclaw-ansible ./run-playbook.sh ``` 補足: この処理は冪等であり、複数回実行しても安全です。 ## トラブルシューティング ### Firewall によって接続できない 接続できなくなった場合は、次を確認してください。 * まず Tailscale VPN 経由で入れることを確認する * SSH (22 番ポート) は常に許可されている * ゲートウェイは設計上 **Tailscale 経由でのみ** 到達可能 ### Service が起動しない ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # ログを確認 sudo journalctl -u openclaw -n 100 # 権限を確認 sudo ls -la /opt/openclaw # 手動起動を試す sudo -i -u openclaw cd ~/openclaw pnpm start ``` ### Docker サンドボックスに問題がある ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # Docker の状態を確認 sudo systemctl status docker # サンドボックスイメージを確認 sudo docker images | grep openclaw-sandbox # イメージがなければビルド cd /opt/openclaw/openclaw sudo -u openclaw ./scripts/sandbox-setup.sh ``` ### プロバイダーログインが失敗する `openclaw` ユーザーとして実行していることを確認してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo -i -u openclaw openclaw channels login ``` ## 高度な設定 セキュリティアーキテクチャや詳細な調査手順は、次の資料を参照してください。 * [Security Architecture](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md) * [Technical Details](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md) * [Troubleshooting Guide](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md) ## 関連項目 * [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — 完全なデプロイガイド * [Docker](/install/docker) — コンテナ化したゲートウェイ構成 * [Sandboxing](/gateway/sandboxing) — エージェントサンドボックス設定 * [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) — エージェント単位の分離 # Bun (実験的) Source: https://openclawdoc.org/install/bun Bun で OpenClaw リポジトリを動かす実験的ワークフローと、pnpm との違い、注意点を説明します。 目的は、`pnpm` のワークフローから大きく外れずに、このリポジトリを **Bun** で実行できるようにすることです。Bun は任意で利用できますが、WhatsApp / Telegram 用途では推奨されません。 ⚠️ **ゲートウェイのランタイムには推奨されません**。WhatsApp / Telegram まわりで不具合があるため、本番環境では Node を使用してください。 ## ステータス * Bun は TypeScript を直接実行するための任意のローカルランタイムです（`bun run …`、`bun --watch …`）。 * ビルドの既定は `pnpm` で、引き続き完全にサポートされています。一部のドキュメント用ツールも `pnpm` を使います。 * Bun は `pnpm-lock.yaml` を利用できないため、このファイルは無視されます。 ## インストール 既定のインストール: ```sh theme={"theme":{"light":"min-light","dark":"min-dark"}} bun install ``` 補足: `bun.lock` / `bun.lockb` は `.gitignore` に含まれているため、どちらを使ってもリポジトリに余計な差分は出ません。ロックファイルを一切書き込みたくない場合は、次を使います。 ```sh theme={"theme":{"light":"min-light","dark":"min-dark"}} bun install --no-save ``` ## ビルド / テスト (Bun) ```sh theme={"theme":{"light":"min-light","dark":"min-dark"}} bun run build bun run vitest run ``` ## Bun のライフサイクルスクリプト (既定ではブロック) Bun は、依存パッケージのライフサイクルスクリプトを明示的に信頼しない限り、実行をブロックすることがあります（`bun pm untrusted` / `bun pm trust`）。 このリポジトリでは、一般にブロックされるスクリプトは通常不要です。 * `@whiskeysockets/baileys` の `preinstall`: Node のメジャーバージョンが 20 以上かを確認します。OpenClaw では Node 22+ を想定しています。 * `protobufjs` の `postinstall`: 互換性のないバージョン体系に関する警告を出すだけで、ビルド成果物は生成しません。 これらのスクリプトが本当に必要なランタイム問題に遭遇した場合のみ、明示的に信頼してください。 ```sh theme={"theme":{"light":"min-light","dark":"min-dark"}} bun pm trust @whiskeysockets/baileys protobufjs ``` ## 注意点 * 一部のスクリプトはまだ `pnpm` を前提にしています。たとえば `docs:build`、`ui:*`、`protocol:check` です。現時点では、これらは `pnpm` で実行してください。 # 開発チャネル Source: https://openclawdoc.org/install/development-channels stable、beta、dev の各配布チャネルの違い、更新タイミング、切り替え方法を整理します。 最終更新: 2026-01-21 OpenClaw には、3 つの更新チャネルがあります。 * **stable**: npm dist-tag は `latest` * **beta**: npm dist-tag は `beta`（検証中のビルド） * **dev**: `main` ブランチの最新 head（git）。npm dist-tag は `dev`（公開されている場合） OpenClaw では、まず **beta** にビルドを出し、検証が終わったものを **同じバージョン番号のまま `latest` に昇格** させます。npm install において正本になるのはバージョン番号ではなく dist-tag です。 ## チャネルの切り替え Git checkout 版: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw update --channel stable openclaw update --channel beta openclaw update --channel dev ``` * `stable` / `beta` は、条件に合う最新タグを checkout します（同じタグを指すこともよくあります） * `dev` は `main` に切り替え、upstream に対して rebase します npm / pnpm のグローバルインストール版: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw update --channel stable openclaw update --channel beta openclaw update --channel dev ``` この場合は、対応する npm dist-tag（`latest`、`beta`、`dev`）を使って更新されます。 `--channel` で **明示的に** チャネルを切り替えると、OpenClaw はインストール方式も自動で揃えます。 * `dev` は git checkout を確実に用意し（既定は `~/openclaw`、`OPENCLAW_GIT_DIR` で変更可能）、それを更新したうえで、その checkout からグローバル CLI を再インストールします * `stable` / `beta` は、対応する dist-tag を使って npm からインストールします 補足: stable と dev を並行運用したい場合は clone を 2 つ用意し、ゲートウェイは stable 側を向けると扱いやすくなります。 ## プラグインとチャネル `openclaw update` でチャネルを切り替えると、プラグインの取得元も同期されます。 * `dev` は git checkout に同梱されたプラグインを優先します * `stable` と `beta` は npm でインストールしたプラグインパッケージへ戻します ## タグ運用のベストプラクティス * Git checkout が着地すべきリリースにはタグを打ちます（stable は `vYYYY.M.D`、beta は `vYYYY.M.D-beta.N`） * 互換性のため `vYYYY.M.D.beta.N` も認識されますが、推奨は `-beta.N` です * 旧形式の `vYYYY.M.D-` タグも、引き続き stable（非 beta）として扱われます * タグは不変に保ち、移動や再利用はしないでください * npm install における正本は dist-tag のままです: * `latest` → stable * `beta` → 候補ビルド * `dev` → `main` のスナップショット（任意） ## macOS アプリの提供状況 beta や dev のビルドには、macOS アプリのリリースが **含まれない** 場合があります。これは問題ありません。 * Git tag と npm dist-tag はそのまま公開できます * リリースノートや changelog に「この beta には macOS ビルドがない」ことを明記してください # Docker Source: https://openclawdoc.org/install/docker Docker で OpenClaw を動かす方法と、コンテナ化ゲートウェイとエージェント用サンドボックスの使い分けを説明します。 Docker は **任意** です。コンテナ化したゲートウェイが必要な場合や、Docker フローを検証したい場合にのみ使ってください。 ## Docker は自分に適しているか？ * **Yes**: 分離された一時的なゲートウェイ環境が必要、またはローカルインストールなしのホストで OpenClaw を動かしたい。 * **No**: 自分のマシン上で動かしており、最速の開発ループだけが欲しい。この場合は通常のインストールフローを使ってください。 * **サンドボックスに関する補足**: エージェントのサンドボックス化にも Docker を使いますが、完全なゲートウェイ全体を Docker 内で動かす必要は **ありません**。[Sandboxing](/gateway/sandboxing) を参照してください。 このガイドでは、次の 2 つを扱います。 * コンテナ化されたゲートウェイ (Docker 内で OpenClaw 全体を実行) * セッション単位のエージェントサンドボックス (ホスト上のゲートウェイ + Docker で分離したエージェントツール) サンドボックスの詳細: [Sandboxing](/gateway/sandboxing) ## 要件 * Docker Desktop (または Docker Engine) + Docker Compose v2 * イメージビルド用に最低 2 GB RAM * 1 GB ホストでは `pnpm install` が OOM kill され、exit 137 になることがあります * イメージとログを保持できる十分なディスク容量 * VPS / 公開ホストで動かす場合は [Security hardening for network exposure](/gateway/security#04-network-exposure-bind--port--firewall) を確認してください * 特に Docker の `DOCKER-USER` firewall policy に注意してください ## コンテナ化された Gateway（Docker Compose） ### クイックスタート（推奨） ここでの Docker 既定値は、host alias ではなく bind mode（`lan` / `loopback`）を前提にしています。`gateway.bind` には `0.0.0.0` や `localhost` のような host alias ではなく、`lan` や `loopback` のような bind mode の値を使ってください。 リポジトリルートから: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ./docker-setup.sh ``` このスクリプトでは次を行います。 * ゲートウェイイメージをローカルでビルドする * `OPENCLAW_IMAGE` が設定されていれば、代わりにリモートイメージを pull します * オンボーディングウィザードを実行する * 任意のプロバイダー設定に関するヒントを表示する * Docker Compose 経由でゲートウェイを起動する * ゲートウェイトークンを生成して `.env` に書き込む 任意の環境変数: * `OPENCLAW_IMAGE` — ローカルビルドの代わりにリモートイメージを使う (例: `ghcr.io/openclaw/openclaw:latest`) * `OPENCLAW_DOCKER_APT_PACKAGES` — ビルド時に追加の apt パッケージを入れる * `OPENCLAW_EXTENSIONS` — ビルド時に extension の依存関係を事前インストールする * スペース区切りの extension 名を指定します。例: `diagnostics-otel matrix` * `OPENCLAW_EXTRA_MOUNTS` — 追加のホスト bind mount を加える * `OPENCLAW_HOME_VOLUME` — `/home/node` を named volume として永続化する * `OPENCLAW_SANDBOX` — Docker ゲートウェイ用サンドボックス設定の bootstrap を有効にする * 明示的に truthy な値 `1`、`true`、`yes`、`on` の場合のみ有効です * `OPENCLAW_INSTALL_DOCKER_CLI` — ローカルイメージビルド向けの build arg passthrough * `1` を指定するとイメージ内に Docker CLI を入れます * `docker-setup.sh` はローカルビルドで `OPENCLAW_SANDBOX=1` の場合、自動でこれを設定します * `OPENCLAW_DOCKER_SOCKET` — Docker socket path を上書きする * デフォルトは `DOCKER_HOST=unix://...` の path、そうでなければ `/var/run/docker.sock` * `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — 緊急時向け * CLI / オンボーディングクライアント経路で、信頼済み private network 上の `ws://` target を許可します * デフォルトは loopback のみです * `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` — コンテナ browser の hardening flag を無効化する * `--disable-3d-apis`、`--disable-software-rasterizer`、`--disable-gpu` を外し、WebGL / 3D 互換性が必要なときに使います * `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` — browser フローで extension が必要なときに有効のままにする * 既定ではサンドボックス側の browser で extension は無効です * `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` — Chromium の renderer process 上限を設定する * `0` にするとこのフラグを省略し、Chromium のデフォルト動作を使います 完了後: * ブラウザで `http://127.0.0.1:18789/` を開く * Control UI にトークンを貼り付ける（Settings → token） * URL が再度必要ですか？ `docker compose run --rm openclaw-cli dashboard --no-open` を実行してください。 ### Docker ゲートウェイ用の agent sandbox を有効にする（オプトイン） `docker-setup.sh` は、Docker デプロイ向けに `agents.defaults.sandbox.*` を初期設定することもできます。 有効化するには: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_SANDBOX=1 ./docker-setup.sh ``` カスタム socket path（たとえば rootless Docker）の場合: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_SANDBOX=1 export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock ./docker-setup.sh ``` 注意: * このスクリプトはサンドボックスの前提条件を満たしたあとでのみ `docker.sock` をマウントします。 * サンドボックスセットアップを完了できない場合、再実行時に古い / 壊れた設定が残らないよう `agents.defaults.sandbox.mode` を `off` に戻します。 * `Dockerfile.sandbox` がない場合は警告を出して続行します。 * 必要なら `scripts/sandbox-setup.sh` で `openclaw-sandbox:bookworm-slim` をビルドしてください。 * ローカル以外の `OPENCLAW_IMAGE` を使う場合、そのイメージにはサンドボックス実行用の Docker CLI サポートがあらかじめ含まれている必要があります。 ### 自動化 / CI（非対話、TTY ノイズなし） スクリプトや CI では、`-T` で Compose の疑似 TTY 割り当てを無効にしてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run -T --rm openclaw-cli gateway probe docker compose run -T --rm openclaw-cli devices list --json ``` 自動化環境で Claude の session 変数を export していなくても、未設定値は `docker-compose.yml` 側で空文字として解決されるため、`variable is not set` 警告が繰り返し出ないようになっています。 ### 共有ネットワークのセキュリティに関する注意（CLI + ゲートウェイ） `openclaw-cli` は `network_mode: "service:openclaw-gateway"` を使うため、CLI コマンドは Docker 内の `127.0.0.1` 経由で確実にゲートウェイへ到達できます。 これは共有された信頼境界として扱ってください。loopback bind は、この 2 つのコンテナ間の分離を意味しません。より強い分離が必要なら、同梱の `openclaw-cli` サービスではなく、別コンテナまたは別ホストのネットワーク経路からコマンドを実行してください。 CLI プロセスが侵害された場合の影響を減らすため、Compose 設定では `openclaw-cli` に対して `NET_RAW` / `NET_ADMIN` を drop し、`no-new-privileges` を有効にしています。 設定とワークスペースはホスト上の次の場所に書き込まれます。 * `~/.openclaw/` * `~/.openclaw/workspace` VPS 上で実行していますか？ [Hetzner (Docker VPS)](/install/hetzner) を参照してください。 ### リモートイメージを使う（ローカルビルドをスキップ） 公式の事前ビルド済みイメージは次で公開されています。 * [GitHub Container Registry package](https://github.com/openclaw/openclaw/pkgs/container/openclaw) イメージ名は `ghcr.io/openclaw/openclaw` を使ってください（似た名前の Docker Hub イメージではありません）。 一般的なタグ: * `main` — `main` の最新ビルド * `` — リリースタグのビルド（例: `2026.2.26`） * `latest` — 最新の安定リリースタグ ### ベースイメージのメタデータ 現在のメイン Docker イメージで使われているベースイメージは次のとおりです。 * `node:22-bookworm` 現在の Docker イメージでは OCI の base-image annotation を公開しています（sha256 は一例で、 そのタグに固定されたマルチアーキテクチャの manifest list を指します）。 * `org.opencontainers.image.base.name=docker.io/library/node:22-bookworm` * `org.opencontainers.image.base.digest=sha256:b501c082306a4f528bc4038cbf2fbb58095d583d0419a259b2114b5ac53d12e9` * `org.opencontainers.image.source=https://github.com/openclaw/openclaw` * `org.opencontainers.image.url=https://openclaw.ai` * `org.opencontainers.image.documentation=https://docs.openclaw.ai/install/docker` * `org.opencontainers.image.licenses=MIT` * `org.opencontainers.image.title=OpenClaw` * `org.opencontainers.image.description=OpenClaw gateway and CLI runtime container image` * `org.opencontainers.image.revision=` * `org.opencontainers.image.version=` * `org.opencontainers.image.created=` 参考: [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) 補足: このリポジトリのタグ付き履歴では、`v2026.2.22` と、それ以前の 2026 系タグ （例: `v2026.2.21`, `v2026.2.9`）でもすでに Bookworm を使用しています。 既定では、セットアップスクリプトはソースからイメージをビルドします。代わりに事前ビルド済み イメージを取得したい場合は、スクリプト実行前に `OPENCLAW_IMAGE` を設定してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" ./docker-setup.sh ``` スクリプトは `OPENCLAW_IMAGE` が既定の `openclaw:local` ではないことを検出すると、 `docker build` の代わりに `docker pull` を実行します。それ以外の処理 （オンボーディング、ゲートウェイ起動、トークン生成）は同じです。 `docker-setup.sh` はローカルの `docker-compose.yml` と補助ファイルを利用するため、 引き続きリポジトリルートから実行してください。`OPENCLAW_IMAGE` はローカルイメージのビルド時間を省くための設定であり、 Compose を使ったセットアップ手順そのものを置き換えるものではありません。 ### シェルヘルパー（任意） 日常的な Docker 管理を簡単にするには、`ClawDock` をインストールしてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh ``` **シェル設定に追加（zsh）:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ``` その後は `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` などを使えます。利用可能なコマンドは `clawdock-help` で確認してください。 詳しくは [`ClawDock` Helper README](https://github.com/openclaw/openclaw/blob/main/scripts/shell-helpers/README.md) を参照してください。 ### 手動手順（Compose） ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker build -t openclaw:local -f Dockerfile . docker compose run --rm openclaw-cli onboard docker compose up -d openclaw-gateway ``` 注意: `docker compose ...` はリポジトリルートから実行してください。 `OPENCLAW_EXTRA_MOUNTS` または `OPENCLAW_HOME_VOLUME` を有効にした場合、セットアップスクリプトは `docker-compose.extra.yml` を生成します。別の場所で Compose を実行するときは、 これを含めてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose -f docker-compose.yml -f docker-compose.extra.yml ``` ### Control UI のトークンとペアリング（Docker） `unauthorized` または `disconnected (1008): pairing required` と表示された場合は、 新しいダッシュボードリンクを取得して、ブラウザデバイスを承認してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli dashboard --no-open docker compose run --rm openclaw-cli devices list docker compose run --rm openclaw-cli devices approve ``` 詳細は [Dashboard](/web/dashboard) と [Devices](/cli/devices) を参照してください。 ### 追加マウント（任意） 追加のホストディレクトリをコンテナへマウントしたい場合は、 `docker-setup.sh` を実行する前に `OPENCLAW_EXTRA_MOUNTS` を設定してください。これは Docker の bind mount をカンマ区切りで指定する形式で、 `docker-compose.extra.yml` を生成して `openclaw-gateway` と `openclaw-cli` の両方に適用します。 例: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw" ./docker-setup.sh ``` 注意: * macOS / Windows では、対象パスが Docker Desktop と共有されている必要があります。 * 各項目は `source:target[:options]` 形式で、スペース、タブ、改行を含めてはいけません。 * `OPENCLAW_EXTRA_MOUNTS` を編集した場合は、 追加の Compose ファイルを再生成するために `docker-setup.sh` を再実行してください。 * `docker-compose.extra.yml` は自動生成されます。手動で編集しないでください。 ### コンテナ全体の home を永続化する（任意） コンテナを作り直したあとも `/home/node` を保持したい場合は、 `OPENCLAW_HOME_VOLUME` で named volume を指定してください。これにより Docker volume が作成され、 `/home/node` にマウントされます。同時に標準の設定 / ワークスペース用 bind mount も維持されます。ここでは bind path ではなく named volume を使ってください。bind mount が必要な場合は `OPENCLAW_EXTRA_MOUNTS` を使ってください。 例: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_HOME_VOLUME="openclaw_home" ./docker-setup.sh ``` 追加マウントと組み合わせることもできます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_HOME_VOLUME="openclaw_home" export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw" ./docker-setup.sh ``` 注意: * named volume 名は `^[A-Za-z0-9][A-Za-z0-9_.-]*$` に一致する必要があります。 * `OPENCLAW_HOME_VOLUME` を変更した場合は、 追加の Compose ファイルを再生成するために `docker-setup.sh` を再実行してください。 * named volume は `docker volume rm ` で削除するまで保持されます。 ### 追加の apt packages をインストールする（任意） イメージ内でシステムパッケージ（ビルドツールやメディア関連ライブラリなど）が必要な場合は、 `docker-setup.sh` 実行前に `OPENCLAW_DOCKER_APT_PACKAGES` を設定してください。 これによりイメージのビルド中にパッケージがインストールされるため、コンテナを削除しても保持されます。 例: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential" ./docker-setup.sh ``` 注意: * これは apt パッケージ名をスペース区切りで指定する形式です。 * `OPENCLAW_DOCKER_APT_PACKAGES` を変更した場合は、イメージを再ビルドするために `docker-setup.sh` を再実行してください。 ### extension dependencies を事前インストールする（任意） 独自の `package.json` を持つ extension（例: `diagnostics-otel`, `matrix`, `msteams`）は、初回読み込み時に npm 依存関係をインストールします。代わりにそれらの 依存関係をイメージへ組み込みたい場合は、 `docker-setup.sh` 実行前に `OPENCLAW_EXTENSIONS` を設定してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_EXTENSIONS="diagnostics-otel matrix" ./docker-setup.sh ``` あるいは直接ビルドする場合: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix" . ``` 注意: * これは `extensions/` 配下のディレクトリ名をスペース区切りで指定する形式です。 * `package.json` を持つ extension のみが対象です。これを持たない軽量プラグインは無視されます。 * `OPENCLAW_EXTENSIONS` を変更した場合は、イメージを再ビルドするために `docker-setup.sh` を再実行してください。 ### 上級者向けのフル機能コンテナ（オプトイン） 既定の Docker イメージは **セキュリティ優先** で、非 root の `node` ユーザーとして実行されます。攻撃対象領域は小さくなりますが、次の制約があります。 * 実行時にシステムパッケージを追加インストールできない * デフォルトでは Homebrew なし * Chromium / Playwright ブラウザは同梱されない より多機能なコンテナが必要な場合は、次のオプトイン設定を使ってください。 1. ブラウザのダウンロードやツールキャッシュを保持できるよう、**`/home/node` を永続化**します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_HOME_VOLUME="openclaw_home" ./docker-setup.sh ``` 2. **システム依存関係をイメージに組み込みます**（再現性があり、永続化されます）。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq" ./docker-setup.sh ``` 3. **`npx` を使わずに Playwright ブラウザをインストール**します（npm の override 競合を回避できます）。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` Playwright にシステム依存関係をインストールさせる必要がある場合は、 実行時に `--with-deps` を使う代わりに `OPENCLAW_DOCKER_APT_PACKAGES` 付きでイメージを再ビルドしてください。 4. **Playwright ブラウザのダウンロードを永続化**します。 * `docker-compose.yml` で `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright` を設定する。 * `OPENCLAW_HOME_VOLUME` で `/home/node` が永続化されていることを確認するか、 `OPENCLAW_EXTRA_MOUNTS` で `/home/node/.cache/ms-playwright` をマウントする。 ### 権限エラーと EACCES イメージは `node`（uid 1000）として実行されます。`/home/node/.openclaw` で 権限エラーが表示される場合は、ホスト側の bind mount が uid 1000 の所有になっていることを確認してください。 例（Linux host）: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace ``` 利便性のために root 実行を選ぶ場合は、その分のセキュリティ上のトレードオフを受け入れる必要があります。 ### より高速な再ビルド（推奨） 再ビルドを高速化するには、依存関係のレイヤーがキャッシュされるように Dockerfile の順序を調整してください。 これにより lockfile が変わらない限り `pnpm install` の再実行を避けられます。 ```dockerfile theme={"theme":{"light":"min-light","dark":"min-dark"}} FROM node:22-bookworm # Install Bun (required for build scripts) RUN curl -fsSL https://bun.sh/install | bash ENV PATH="/root/.bun/bin:${PATH}" RUN corepack enable WORKDIR /app # Cache dependencies unless package metadata changes COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./ COPY ui/package.json ./ui/package.json COPY scripts ./scripts RUN pnpm install --frozen-lockfile COPY . . RUN pnpm build RUN pnpm ui:install RUN pnpm ui:build ENV NODE_ENV=production CMD ["node","dist/index.js"] ``` ### チャネルのセットアップ（任意） CLI コンテナを使ってチャネルを設定し、必要に応じてゲートウェイを再起動してください。 WhatsApp（QR）: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli channels login ``` Telegram（bot トークン）: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli channels add --channel telegram --token "" ``` Discord（bot トークン）: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli channels add --channel discord --token "" ``` 関連ドキュメント: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord) ### OpenAI Codex OAuth（ヘッドレス Docker） ウィザードで OpenAI Codex OAuth を選ぶと、ブラウザ URL を開いて `http://127.0.0.1:1455/auth/callback` のコールバックを受け取ろうとします。Docker や ヘッドレス環境では、このコールバック時にブラウザでエラーが表示されることがあります。遷移先の完全なリダイレクト URL をコピーし、 認証を完了するためにウィザードへ貼り戻してください。 ### Health checks コンテナのプローブ用エンドポイント（認証不要）: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsS http://127.0.0.1:18789/healthz curl -fsS http://127.0.0.1:18789/readyz ``` エイリアスは `/health` と `/ready` です。 `/healthz` は「ゲートウェイプロセスが起動している」ことを確認する軽量な liveness probe です。 `/readyz` は起動猶予期間中も ready のままで、その後は必須の 管理対象チャネルが猶予期間後も未接続のままか、あとから切断された場合にのみ `503` を返します。 Docker イメージには、バックグラウンドで `/healthz` を監視する組み込みの `HEALTHCHECK` が含まれています。 つまり Docker は、OpenClaw が引き続き応答しているかを継続的に確認します。 チェックが失敗し続けると、Docker はコンテナを `unhealthy` とマークし、 オーケストレーションシステム（Docker Compose の再起動ポリシー、Swarm、Kubernetes など）は自動的に再起動または置き換えを行えます。 認証付きの詳細なヘルススナップショット（ゲートウェイ + チャネル）: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN" ``` ### E2E smoke test（Docker） ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} scripts/e2e/onboard-docker.sh ``` ### QR import smoke test（Docker） ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm test:docker:qr ``` ### `lan` と `loopback` の違い（Docker Compose） `docker-setup.sh` は既定で `OPENCLAW_GATEWAY_BIND=lan` を設定するため、 Docker のポート公開によりホストから `http://127.0.0.1:18789` へアクセスできます。 * `lan`（既定値）: ホストのブラウザとホスト CLI から、公開されたゲートウェイポートへ到達できます。 * `loopback`: コンテナの network namespace 内にいるプロセスだけが ゲートウェイへ直接到達できます。ホストへ公開されたポート経由のアクセスは失敗する場合があります。 セットアップスクリプトはオンボーディング後に `gateway.mode=local` も固定するため、Docker CLI コマンドは既定でローカル loopback 宛てを使います。 旧来の設定に関する注意: `gateway.bind` には bind mode の値（`lan` / `loopback` / `custom` / `tailnet` / `auto`）を使ってください。host alias（`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`）は使わないでください。 `Gateway target: ws://172.x.x.x:18789` や、Docker CLI コマンドで繰り返し `pairing required` エラーが表示される場合は、次を実行してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli config set gateway.mode local docker compose run --rm openclaw-cli config set gateway.bind lan docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789 ``` ### 注意 * ゲートウェイの bind はコンテナ利用向けに既定で `lan` です（`OPENCLAW_GATEWAY_BIND`）。 * Dockerfile の `CMD` は `--allow-unconfigured` を使います。マウントされた設定で `gateway.mode` が `local` でなくても起動します。ガードを強制したい場合は `CMD` を上書きしてください。 * ゲートウェイコンテナがセッション情報の正本です（`~/.openclaw/agents//sessions/`）。 ### ストレージモデル * **永続化されるホスト側データ:** Docker Compose は `OPENCLAW_CONFIG_DIR` を `/home/node/.openclaw` に、`OPENCLAW_WORKSPACE_DIR` を `/home/node/.openclaw/workspace` に bind mount するため、これらのパスはコンテナを置き換えても保持されます。 * **一時的なサンドボックス tmpfs:** `agents.defaults.sandbox` が有効な場合、サンドボックスコンテナは `/tmp`、`/var/tmp`、`/run` に `tmpfs` を使います。これらのマウントはトップレベルの Compose スタックとは別で、サンドボックスコンテナとともに消えます。 * **ディスク増加しやすい箇所:** `media/`、`agents//sessions/sessions.json`、transcript JSONL ファイル、`cron/runs/*.jsonl`、および `/tmp/openclaw/`（または設定した `logging.file`）配下のローテートログに注意してください。Docker 外で macOS アプリも実行している場合、そのサービスログは別管理で、`~/.openclaw/logs/gateway.log`、`~/.openclaw/logs/gateway.err.log`、`/tmp/openclaw/openclaw-gateway.log` に出力されます。 ## Agent Sandbox（ホスト上のゲートウェイ + Docker ツール） 詳細: [Sandboxing](/gateway/sandboxing) ### 概要 `agents.defaults.sandbox` が有効な場合、**main 以外のセッション** は Docker コンテナ内でツールを実行します。ゲートウェイはホスト上に残りますが、ツール実行は分離されます。 * 既定の scope は `"agent"`（agent ごとに 1 つのコンテナ + ワークスペース） * セッション単位で分離したい場合は scope に `"session"` を使います * scope ごとのワークスペースフォルダを `/workspace` にマウントします * 必要に応じて agent workspace access（`agents.defaults.sandbox.workspaceAccess`）を設定できます * ツールポリシーは allow/deny 方式で、deny が優先されます * 受信メディアは、ツールから読めるようアクティブなサンドボックスワークスペース（`media/inbound/*`）へコピーされます（`workspaceAccess: "rw"` の場合は agent ワークスペースに入ります） 警告: `scope: "shared"` はセッション間の分離を無効にします。すべてのセッションが 1 つのコンテナと 1 つのワークスペースを共有します。 ### Agent ごとのサンドボックスプロファイル（multi-agent） multi-agent routing を使う場合、各 agent はサンドボックス設定とツール設定を上書きできます。 対象は `agents.list[].sandbox` と `agents.list[].tools`（および `agents.list[].tools.sandbox.tools`）です。これにより、1 つのゲートウェイ内で 異なるアクセスレベルを混在させて運用できます。 * フルアクセス（個人用 agent） * 読み取り専用ツール + 読み取り専用ワークスペース（家族用 / 業務用 agent） * filesystem / shell ツールなし（公開 agent） 例、優先順位、トラブルシューティングは [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) を参照してください。 ### デフォルト動作 * イメージ: `openclaw-sandbox:bookworm-slim` * agent ごとに 1 つのコンテナ * Agent workspace access: `workspaceAccess: "none"`（既定値）では `~/.openclaw/sandboxes` を使います * `"ro"` ではサンドボックスワークスペースを `/workspace` のままにし、agent workspace を `/agent` へ読み取り専用でマウントします（`write` / `edit` / `apply_patch` は無効） * `"rw"` では agent workspace を `/workspace` へ読み書き可能でマウントします * 自動削除: アイドル状態が 24 時間超、または作成から 7 日超 * ネットワーク: 既定値は `none`（外向き通信が必要な場合のみ明示的にオプトイン） * `host` はブロックされます。 * `container:` も既定でブロックされます（namespace join のリスクがあるため）。 * 既定で許可: `exec`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` * 既定で拒否: `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway` ### サンドボックスを有効にする `setupCommand` でパッケージをインストールする予定がある場合は、次に注意してください。 * 既定の `docker.network` は `"none"`（外向き通信なし）です。 * `docker.network: "host"` はブロックされます。 * `docker.network: "container:"` はデフォルトでブロックされます。 * 緊急時のみの上書き設定: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` * `readOnlyRoot: true` ではパッケージインストールを実行できません。 * `apt-get` を使うには `user` が root である必要があります（`user` を省略するか、`user: "0:0"` を設定します）。 OpenClaw は `setupCommand`（または Docker 設定）が変わると自動的にコンテナを再作成しますが、 コンテナが**直近で使用されていた**（約 5 分以内）場合は除きます。稼働中のコンテナでは、 正確な `openclaw sandbox recreate ...` コマンドを含む警告が表示されます。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared (agent is default) workspaceAccess: "none", // none | ro | rw workspaceRoot: "~/.openclaw/sandboxes", docker: { image: "openclaw-sandbox:bookworm-slim", workdir: "/workspace", readOnlyRoot: true, tmpfs: ["/tmp", "/var/tmp", "/run"], network: "none", user: "1000:1000", capDrop: ["ALL"], env: { LANG: "C.UTF-8" }, setupCommand: "apt-get update && apt-get install -y git curl jq", pidsLimit: 256, memory: "1g", memorySwap: "2g", cpus: 1, ulimits: { nofile: { soft: 1024, hard: 2048 }, nproc: 256, }, seccompProfile: "/path/to/seccomp.json", apparmorProfile: "openclaw-sandbox", dns: ["1.1.1.1", "8.8.8.8"], extraHosts: ["internal.service:10.0.0.5"], }, prune: { idleHours: 24, // 0 disables idle pruning maxAgeDays: 7, // 0 disables max-age pruning }, }, }, }, tools: { sandbox: { tools: { allow: [ "exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", ], deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"], }, }, }, } ``` hardening 用の設定項目は `agents.defaults.sandbox.docker` 配下にあります。 `network`, `user`, `pidsLimit`, `memory`, `memorySwap`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`, `dns`, `extraHosts`, `dangerouslyAllowContainerNamespaceJoin`（緊急時専用）。 multi-agent では、`agents.defaults.sandbox.scope` / `agents.list[].sandbox.scope` が `"shared"` の場合を除き、agent ごとに `agents.list[].sandbox.{docker,browser,prune}.*` で `agents.defaults.sandbox.{docker,browser,prune}.*` を上書きできます （`"shared"` の場合は無視されます）。 ### 既定のサンドボックスイメージをビルドする ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} scripts/sandbox-setup.sh ``` これにより `Dockerfile.sandbox` を使って `openclaw-sandbox:bookworm-slim` がビルドされます。 ### 共通サンドボックスイメージ（任意） 一般的なビルドツール群（Node、Go、Rust など）を含むサンドボックスイメージが必要な場合は、共通イメージをビルドしてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} scripts/sandbox-common-setup.sh ``` これにより `openclaw-sandbox-common:bookworm-slim` がビルドされます。使用するには、次のように設定します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } }, }, }, } ``` ### サンドボックス用ブラウザイメージ サンドボックス内で `browser` ツールを実行するには、ブラウザイメージをビルドしてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} scripts/sandbox-browser-setup.sh ``` これにより `Dockerfile.sandbox-browser` を使って `openclaw-sandbox-browser:bookworm-slim` がビルドされます。コンテナでは CDP を有効にした Chromium と、 任意の noVNC オブザーバー（Xvfb 経由の headful モード）を実行します。 注意: * Headful（Xvfb）は headless より bot blocking を受けにくくなります。 * `agents.defaults.sandbox.browser.headless=true` を設定すれば、引き続き headless を使えます。 * フルデスクトップ環境（GNOME など）は不要で、表示は Xvfb が提供します。 * ブラウザコンテナは、グローバルな `bridge` ではなく、専用の Docker network（`openclaw-sandbox-browser`）を既定で使います。 * 必要に応じて `agents.defaults.sandbox.browser.cdpSourceRange` を使い、コンテナ境界での CDP ingress を CIDR で制限できます（例: `172.21.0.1/32`）。 * noVNC のオブザーバーアクセスは既定でパスワード保護されます。OpenClaw は短時間だけ有効な observer token URL を提供し、パスワードは URL query ではなく URL fragment に保持されるローカル bootstrap page を返します。 * ブラウザコンテナの起動時既定値は、共有環境やコンテナワークロード向けに保守的に設定されており、次のフラグを含みます。 * `--remote-debugging-address=127.0.0.1` * `--remote-debugging-port=` * `--user-data-dir=${HOME}/.chrome` * `--no-first-run` * `--no-default-browser-check` * `--disable-3d-apis` * `--disable-software-rasterizer` * `--disable-gpu` * `--disable-dev-shm-usage` * `--disable-background-networking` * `--disable-features=TranslateUI` * `--disable-breakpad` * `--disable-crash-reporter` * `--metrics-recording-only` * `--renderer-process-limit=2` * `--no-zygote` * `--disable-extensions` * `agents.defaults.sandbox.browser.noSandbox` が設定されている場合は、`--no-sandbox` と `--disable-setuid-sandbox` も追加されます。 * 上記 3 つの graphics hardening フラグは任意です。ワークロードで WebGL / 3D が必要な場合は、`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` を設定して `--disable-3d-apis`, `--disable-software-rasterizer`, `--disable-gpu` なしで実行してください。 * extension の挙動は `--disable-extensions` で制御され、extension 依存のページや extension を多用するワークフローでは `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` により無効化 （つまり extension を有効化）できます。 * `--renderer-process-limit=2` も `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT` で設定できます。ブラウザ並列数の調整が必要な場合は `0` にして、Chromium に 既定の process limit を選ばせることもできます。 これらの既定値は同梱イメージであらかじめ適用されています。別の Chromium フラグが必要な場合は、カスタムのブラウザイメージを使い、独自の entrypoint を指定してください。 設定例: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { sandbox: { browser: { enabled: true }, }, }, }, } ``` カスタムブラウザイメージ: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { sandbox: { browser: { image: "my-openclaw-browser" } }, }, }, } ``` 有効にすると、agent は次を受け取ります。 * サンドボックス用ブラウザ制御 URL（`browser` ツール用） * noVNC URL（有効かつ headless=false の場合） 注意: ツールに allowlist を使う場合は、`browser` を追加し （かつ deny から削除し）ない限り、そのツールはブロックされたままです。 prune ルール（`agents.defaults.sandbox.prune`）はブラウザコンテナにも適用されます。 ### カスタムサンドボックスイメージ 独自のイメージをビルドし、設定でそれを指定してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker build -t my-openclaw-sbx -f Dockerfile.sandbox . ``` ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { sandbox: { docker: { image: "my-openclaw-sbx" } }, }, }, } ``` ### ツールポリシー（allow/deny） * `deny` は `allow` に優先します。 * `allow` が空の場合: `deny` を除くすべてのツールが利用可能です。 * `allow` が空でない場合: `allow` にあるツールだけが利用可能です（`deny` を除く）。 ### 自動削除ポリシー 調整できる項目は 2 つあります。 * `prune.idleHours`: X 時間使われていないコンテナを削除（0 = 無効） * `prune.maxAgeDays`: X 日より古いコンテナを削除（0 = 無効） 例: * 稼働中のセッションは維持しつつ、有効期間を制限する: `idleHours: 24`, `maxAgeDays: 7` * 自動削除を一切行わない: `idleHours: 0`, `maxAgeDays: 0` ### セキュリティに関する注意 * 強い隔離が適用されるのは **tools** のみです（exec / read / write / edit / apply\_patch）。 * browser / camera / canvas のような host-only ツールは既定でブロックされます。 * サンドボックスで `browser` を許可すると **隔離が崩れます**（browser はホスト上で実行されます）。 ## トラブルシューティング * イメージがない: [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) でビルドするか、`agents.defaults.sandbox.docker.image` を設定してください。 * コンテナが起動していない: 必要になった時点で、セッションごとに自動作成されます。 * サンドボックスで権限エラーが出る: `docker.user` を マウントしたワークスペースの所有権に一致する UID:GID へ設定する （またはワークスペースフォルダを `chown` する）。 * カスタムツールが見つからない: OpenClaw は `sh -lc`（login shell）でコマンドを実行するため、 `/etc/profile` を読み込んで `PATH` をリセットすることがあります。`docker.env.PATH` を設定して カスタムツールのパス（例: `/custom/bin:/usr/local/share/npm-global/bin`）を前置するか、 Dockerfile で `/etc/profile.d/` 配下にスクリプトを追加してください。 # exe.dev Source: https://openclawdoc.org/install/exe-dev exe.dev の VM と HTTPS プロキシを使って、外部からアクセスできる OpenClaw Gateway を構築する手順です。 目的は、exe.dev の VM 上で OpenClaw ゲートウェイを動かし、手元の PC から `https://.exe.xyz` で到達できるようにすることです。 このページでは、exe.dev 既定の **exeuntu** イメージを前提にしています。別のディストリビューションを選んだ場合は、パッケージ名などを適宜読み替えてください。 ## 初心者向けの最短ルート 1. [https://exe.new/openclaw](https://exe.new/openclaw) を開く 2. 必要に応じて認証キーやトークンを入力する 3. VM の横にある「Agent」をクリックして待つ 4. ??? 5. 完了 ## 必要なもの * exe.dev アカウント * [exe.dev](https://exe.dev) 仮想マシンへ `ssh exe.dev` できる環境（任意） ## Shelley を使った自動インストール [exe.dev](https://exe.dev) のエージェントである Shelley は、次のプロンプトで OpenClaw をすぐにセットアップできます。 ``` Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw devices approve ". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be .exe.xyz, without port specification. ``` ## 手動インストール ## 1) VM を作成 手元の端末から次を実行します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh exe.dev new ``` その後、VM に接続します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh .exe.xyz ``` 補足: この VM は **stateful** のまま運用してください。OpenClaw は状態を `~/.openclaw/` と `~/.openclaw/workspace/` に保存します。 ## 2) 前提パッケージをインストール（VM 上） ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo apt-get update sudo apt-get install -y git curl jq ca-certificates openssl ``` ## 3) OpenClaw をインストール OpenClaw のインストールスクリプトを実行します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL https://openclaw.ai/install.sh | bash ``` ## 4) OpenClaw を port 8000 にプロキシする nginx を設定 `/etc/nginx/sites-enabled/default` を次の内容に編集します。 ``` server { listen 80 default_server; listen [::]:80 default_server; listen 8000; listen [::]:8000; server_name _; location / { proxy_pass http://127.0.0.1:18789; proxy_http_version 1.1; # WebSocket support proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # Standard proxy headers proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # Timeout settings for long-lived connections proxy_read_timeout 86400s; proxy_send_timeout 86400s; } } ``` ## 5) OpenClaw にアクセスして権限を付与 `https://.exe.xyz/` にアクセスします。URL はオンボーディング中に表示される Control UI の出力を参照してください。 認証を求められた場合は、VM 上の `gateway.auth.token` を貼り付けます。取得方法は次のいずれかです。 * `openclaw config get gateway.auth.token` * `openclaw doctor --generate-gateway-token` デバイス承認は `openclaw devices list` と `openclaw devices approve ` で行います。迷った場合は、ブラウザから Shelley を使う方法でも構いません。 ## リモートアクセス リモートアクセス自体は [exe.dev](https://exe.dev) 側の認証で保護されます。既定では、port 8000 に来た HTTP トラフィックが、メール認証付きで `https://.exe.xyz` へ転送されます。 ## 更新 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm i -g openclaw@latest openclaw doctor openclaw gateway restart openclaw health ``` ガイド: [Updating](/install/updating) # Fly.io Source: https://openclawdoc.org/install/fly Fly.io 上で OpenClaw を常時稼働させるためのデプロイ、永続ストレージ、HTTPS、運用手順を説明します。 **目標:** 永続ストレージ、自動 HTTPS、Discord などのチャネル接続を備えた [Fly.io](https://fly.io) マシン上で OpenClaw ゲートウェイを実行することです。 ## 必要なもの * インストール済みの [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/) * Fly.io アカウント (無料枠で機能します) * モデル認証: 使用するモデルプロバイダーの API キー * チャネル認証情報: Discord ボットトークン、Telegram トークンなど ## 初心者向けのクイックパス 1. リポジトリのクローン → `fly.toml` のカスタマイズ 2. アプリ + ボリュームの作成 → シークレットの設定 3. `fly deploy` でデプロイ 4. SSH で接続して設定を作成するか、Control UI を使用する ## 1) Fly アプリの作成 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # リポジトリのクローン git clone https://github.com/openclaw/openclaw.git cd openclaw # 新しい Fly アプリを作成します (自分の名前を選択してください) fly apps create my-openclaw # 永続ボリュームを作成します (通常は 1GB で十分です) fly volumes create openclaw_data --size 1 --region iad ``` **ヒント:** 自分に近いリージョンを選択してください。一般的なオプション: `lhr` (ロンドン)、`iad` (バージニア)、`sjc` (サンノゼ)。 ## 2) fly.toml の設定 アプリ名と要件に合わせて `fly.toml` を編集します。 **セキュリティに関する注意:** デフォルトの設定では、パブリック URL が公開されます。パブリック IP のない強化されたデプロイメントについては、[プライベートデプロイメント](#プライベートデプロイメント-強化版) を参照するか、`fly.private.toml` を使用してください。 ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} app = "my-openclaw" # あなたのアプリ名 primary_region = "iad" [build] dockerfile = "Dockerfile" [env] NODE_ENV = "production" OPENCLAW_PREFER_PNPM = "1" OPENCLAW_STATE_DIR = "/data" NODE_OPTIONS = "--max-old-space-size=1536" [processes] app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan" [http_service] internal_port = 3000 force_https = true auto_stop_machines = false auto_start_machines = true min_machines_running = 1 processes = ["app"] [[vm]] size = "shared-cpu-2x" memory = "2048mb" [mounts] source = "openclaw_data" destination = "/data" ``` **主な設定:** | 設定 | 理由 | | ------------------------------ | -------------------------------------------------------------------------- | | `--bind lan` | Fly のプロキシが Gateway に到達できるように `0.0.0.0` にバインドします | | `--allow-unconfigured` | 設定ファイルなしで起動します (後で作成します) | | `internal_port = 3000` | Fly のヘルスチェックのために `--port 3000` (または `OPENCLAW_GATEWAY_PORT`) と一致させる必要があります | | `memory = "2048mb"` | 512MB では小さすぎます。2GB を推奨します | | `OPENCLAW_STATE_DIR = "/data"` | ボリューム上に状態を永続化します | ## 3) シークレットの設定 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 必須: Gateway トークン (非ループバックバインディング用) fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32) # モデルプロバイダの API キー fly secrets set ANTHROPIC_API_KEY=sk-ant-... # オプション: その他のプロバイダ fly secrets set OPENAI_API_KEY=sk-... fly secrets set GOOGLE_API_KEY=... # チャネルトークン fly secrets set DISCORD_BOT_TOKEN=MTQ... ``` **注意:** * 非ループバックバインド (`--bind lan`) には、セキュリティのために `OPENCLAW_GATEWAY_TOKEN` が必要です。 * これらのトークンはパスワードのように扱ってください。 * すべての API キーとトークンには、**設定ファイルよりも環境変数を優先**してください。これにより、シークレットが誤って公開されたりログに記録されたりする可能性がある `openclaw.json` からシークレットを遠ざけることができます。 ## 4) デプロイ ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly deploy ``` 最初のデプロイでは Docker イメージがビルドされます (約 2〜3 分)。以降のデプロイはより高速になります。 デプロイ後、確認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly status fly logs ``` 以下のように表示されるはずです: ``` [gateway] listening on ws://0.0.0.0:3000 (PID xxx) [discord] logged in to discord as xxx ``` ## 5) 設定ファイルの作成 マシンに SSH で接続して、適切な設定を作成します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly ssh console ``` 設定ディレクトリとファイルを作成します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} mkdir -p /data cat > /data/openclaw.json << 'EOF' { "agents": { "defaults": { "model": { "primary": "anthropic/claude-opus-4-6", "fallbacks": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o"] }, "maxConcurrent": 4 }, "list": [ { "id": "main", "default": true } ] }, "auth": { "profiles": { "anthropic:default": { "mode": "token", "provider": "anthropic" }, "openai:default": { "mode": "token", "provider": "openai" } } }, "bindings": [ { "agentId": "main", "match": { "channel": "discord" } } ], "channels": { "discord": { "enabled": true, "groupPolicy": "allowlist", "guilds": { "YOUR_GUILD_ID": { "channels": { "general": { "allow": true } }, "requireMention": false } } } }, "gateway": { "mode": "local", "bind": "auto" }, "meta": { "lastTouchedVersion": "2026.1.29" } } EOF ``` **注意:** `OPENCLAW_STATE_DIR=/data` の場合、設定パスは `/data/openclaw.json` です。 **注意:** Discord トークンは次のいずれかから取得できます: * 環境変数: `DISCORD_BOT_TOKEN` (シークレットに推奨) * 設定ファイル: `channels.discord.token` 環境変数を使用する場合、設定にトークンを追加する必要はありません。Gateway は自動的に `DISCORD_BOT_TOKEN` を読み取ります。 再起動して適用します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} exit fly machine restart ``` ## 6) ゲートウェイへのアクセス ### Control UI ブラウザで開きます: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly open ``` または `https://my-openclaw.fly.dev/` にアクセスします。 ゲートウェイトークン (`OPENCLAW_GATEWAY_TOKEN` の値) を貼り付けて認証します。 ### ログ ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly logs # ライブログ fly logs --no-tail # 最近のログ ``` ### SSH コンソール ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly ssh console ``` ## トラブルシューティング ### "App is not listening on expected address" ゲートウェイが `0.0.0.0` ではなく `127.0.0.1` に bind しています。 **修正:** `fly.toml` のプロセスコマンドに `--bind lan` を追加します。 ### ヘルスチェック失敗 / connection refused Fly が設定ポート上のゲートウェイへ到達できません。 **修正:** `internal_port` が Gateway のポートと一致していることを確認します (`--port 3000` または `OPENCLAW_GATEWAY_PORT=3000` を設定します)。 ### OOM / メモリ不足 コンテナが再起動を繰り返すか、強制終了されます。兆候: `SIGABRT`、`v8::internal::Runtime_AllocateInYoungGeneration`、またはサイレントな再起動。 **修正:** `fly.toml` でメモリを増やします: ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [[vm]] memory = "2048mb" ``` または、既存のマシンを更新します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly machine update --vm-memory 2048 -y ``` **注意:** 512MB では小さすぎます。1GB でも機能する可能性がありますが、負荷がかかったり、冗長なログ記録が行われたりすると OOM になる可能性があります。**2GB を推奨します。** ### ゲートウェイのロック問題 「すでに実行中です (already running)」というエラーで Gateway が起動を拒否します。 これは、コンテナは再起動したものの、PID ロックファイルがボリューム上に残っている場合に発生します。 **修正:** ロックファイルを削除します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly ssh console --command "rm -f /data/gateway.*.lock" fly machine restart ``` ロックファイルは `/data/gateway.*.lock` にあります (サブディレクトリではありません)。 ### 設定が読み込まれない `--allow-unconfigured` を使用している場合、Gateway は最小限の設定を作成します。`/data/openclaw.json` にあるカスタム設定は、再起動時に読み込まれるはずです。 設定が存在することを確認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly ssh console --command "cat /data/openclaw.json" ``` ### SSH 経由での設定の書き込み `fly ssh console -C` コマンドはシェルのリダイレクトをサポートしていません。設定ファイルを書き込むには: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # echo + tee を使用します (ローカルからリモートへパイプします) echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json" # または sftp を使用します fly sftp shell > put /local/path/config.json /data/openclaw.json ``` **注意:** ファイルがすでに存在する場合、`fly sftp` は失敗する可能性があります。最初に削除します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly ssh console --command "rm /data/openclaw.json" ``` ### 状態が永続化されない 再起動後に認証情報やセッションが失われる場合、状態ディレクトリがコンテナのファイルシステムに書き込まれています。 **修正:** `fly.toml` で `OPENCLAW_STATE_DIR=/data` が設定されていることを確認し、再デプロイします。 ## アップデート ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 最新の変更を取得します git pull # 再デプロイします fly deploy # 正常性を確認します fly status fly logs ``` ### マシンコマンドの更新 完全な再デプロイを行わずに起動コマンドを変更する必要がある場合: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # マシン ID を取得します fly machines list # コマンドを更新します fly machine update --command "node dist/index.js gateway --port 3000 --bind lan" -y # またはメモリの増加と一緒に fly machine update --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y ``` **注意:** `fly deploy` の後、マシンコマンドは `fly.toml` にあるものにリセットされる可能性があります。手動で変更を加えた場合は、デプロイ後に再適用してください。 ## プライベートデプロイメント (強化版) デフォルトでは、Fly はパブリック IP を割り当てるため、`https://your-app.fly.dev` で Gateway にアクセスできるようになります。これは便利ですが、インターネットスキャナー (Shodan、Censys など) によってデプロイメントが発見される可能性があることを意味します。 **パブリックに公開しない**強化されたデプロイメントの場合は、プライベートテンプレートを使用してください。 ### プライベートデプロイメントを使用する場合 * **アウトバウンド**の呼び出し/メッセージのみを行う場合 (インバウンドの Webhook なし) * Webhook コールバックに **ngrok または Tailscale** トンネルを使用する場合 * ブラウザの代わりに **SSH、プロキシ、または WireGuard** 経由でゲートウェイへアクセスする場合 * **インターネットスキャナーからデプロイメントを隠したい**場合 ### セットアップ 標準の設定の代わりに `fly.private.toml` を使用します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # プライベート設定でデプロイします fly deploy -c fly.private.toml ``` または、既存のデプロイメントを変換します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 現在の IP を一覧表示します fly ips list -a my-openclaw # パブリック IP を解放します fly ips release -a my-openclaw fly ips release -a my-openclaw # 今後のデプロイでパブリック IP が再割り当てされないように、プライベート設定に切り替えます # ([http_service] を削除するか、プライベートテンプレートを使用してデプロイします) fly deploy -c fly.private.toml # プライベート専用の IPv6 を割り当てます fly ips allocate-v6 --private -a my-openclaw ``` この後、`fly ips list` は `private` タイプの IP のみを表示するはずです: ``` VERSION IP TYPE REGION v6 fdaa:x:x:x:x::x private global ``` ### プライベートデプロイメントへのアクセス パブリック URL がないため、以下のいずれかの方法を使用します: **オプション 1: ローカルプロキシ (最も簡単)** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # ローカルポート 3000 をアプリに転送します fly proxy 3000:3000 -a my-openclaw # その後、ブラウザで http://localhost:3000 を開きます ``` **オプション 2: WireGuard VPN** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # WireGuard 設定を作成します (1 回限り) fly wireguard create # WireGuard クライアントにインポートし、内部 IPv6 経由でアクセスします # 例: http://[fdaa:x:x:x:x::x]:3000 ``` **オプション 3: SSH のみ** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} fly ssh console -a my-openclaw ``` ### プライベートデプロイメントでの webhook パブリックに公開せずに Webhook コールバック (Twilio、Telnyx など) が必要な場合: 1. **ngrok トンネル** - コンテナ内またはサイドカーとして ngrok を実行します 2. **Tailscale Funnel** - Tailscale 経由で特定のパスを公開します 3. **アウトバウンドのみ** - 一部のプロバイダ (Twilio) は、Webhook なしでもアウトバウンド通話で問題なく機能します ngrok を使用した voice-call 設定の例: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "plugins": { "entries": { "voice-call": { "enabled": true, "config": { "provider": "twilio", "tunnel": { "provider": "ngrok" }, "webhookSecurity": { "allowedHosts": ["example.ngrok.app"] } } } } } } ``` ngrok トンネルはコンテナ内で実行され、Fly アプリ自体を公開することなくパブリックな Webhook URL を提供します。転送されたホストヘッダーが受け入れられるように、`webhookSecurity.allowedHosts` をパブリックなトンネルのホスト名に設定してください。 ### セキュリティ上の利点 | 側面 | パブリック | プライベート | | --------------- | ----- | -------- | | インターネットスキャナー | 発見可能 | 隠蔽 | | 直接攻撃 | 可能 | ブロック | | Control UI アクセス | ブラウザ | プロキシ/VPN | | Webhook の配信 | 直接 | トンネル経由 | ## 備考 * Fly.io は **x86 アーキテクチャ** を使用します (ARM ではありません)。 * Dockerfile は両方のアーキテクチャと互換性があります。 * WhatsApp/Telegram のオンボーディングには、`fly ssh console` を使用します。 * 永続データは `/data` のボリューム上にあります。 * Signal には Java + signal-cli が必要です。カスタムイメージを使用し、メモリを 2GB 以上に保ってください。 ## コスト 推奨される設定 (`shared-cpu-2x`、2GB RAM) の場合: * 使用量に応じて月額約 10〜15 ドル * 無料枠には一定の余裕が含まれています 詳細については、[Fly.io の価格](https://fly.io/docs/about/pricing/)を参照してください。 # GCP Source: https://openclawdoc.org/install/gcp GCP Compute Engine と Docker を使って、永続状態を保ちながら OpenClaw Gateway を常時運用する手順です。 ## 目標 永続状態、ビルド時に組み込んだバイナリ、安全な再起動挙動を備えた GCP Compute Engine VM 上で、Docker を使って OpenClaw ゲートウェイを常時稼働させます。 「月額約5〜12ドルで OpenClaw を 24 時間 365 日稼働させたい」場合、これは Google Cloud 上の信頼できるセットアップです。 価格はマシンの種類とリージョンによって異なります。ワークロードに適合する最小の VM を選択し、OOM (メモリ不足) が発生した場合はスケールアップしてください。 ## 何をするのか (簡単に) * GCP プロジェクトを作成し、課金を有効にします * Compute Engine VM を作成します * Docker (分離されたアプリランタイム) をインストールします * Docker で OpenClaw ゲートウェイを起動します * ホスト上で `~/.openclaw` + `~/.openclaw/workspace` を永続化します (再起動/再ビルド後も存続します) * SSH トンネル経由でノート PC から Control UI にアクセスします ゲートウェイへのアクセス方法は次のとおりです。 * ノート PC からの SSH ポートフォワーディング * ファイアウォールとトークンを自分で管理する場合の直接のポート公開 このガイドでは、GCP Compute Engine 上の Debian を使用します。 Ubuntu も機能します。それに応じてパッケージをマッピングしてください。 一般的な Docker フローについては、[Docker](/install/docker) を参照してください。 *** ## クイックパス (経験豊富なオペレーター向け) 1. GCP プロジェクトの作成 + Compute Engine API の有効化 2. Compute Engine VM の作成 (e2-small、Debian 12、20GB) 3. VM への SSH 接続 4. Docker のインストール 5. OpenClaw リポジトリのクローン 6. 永続的なホストディレクトリの作成 7. `.env` と `docker-compose.yml` の設定 8. 必要なバイナリの組み込み、ビルド、起動 *** ## 必要なもの * GCP アカウント (e2-micro の無料枠の対象) * インストール済みの gcloud CLI (または Cloud Console を使用) * ラップトップからの SSH アクセス * SSH + コピー/ペーストに関する基本的な知識 * 約 20〜30 分 * Docker と Docker Compose * モデルの認証情報 * オプションのプロバイダ認証情報 * WhatsApp の QR * Telegram のボットトークン * Gmail の OAuth *** ## 1) gcloud CLI をインストールする (または Console を使う) **オプション A: gcloud CLI** (自動化に推奨) [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install) からインストールします。 初期化と認証を行います: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud init gcloud auth login ``` **オプション B: Cloud Console** すべての手順は、[https://console.cloud.google.com](https://console.cloud.google.com) のウェブ UI 経由で実行できます。 *** ## 2) GCP プロジェクトを作成する **CLI:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud projects create my-openclaw-project --name="OpenClaw Gateway" gcloud config set project my-openclaw-project ``` [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) で課金を有効にします (Compute Engine に必要です)。 Compute Engine API を有効にします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud services enable compute.googleapis.com ``` **Console:** 1. IAM と管理 (IAM & Admin) > プロジェクトの作成 (Create Project) に移動します。 2. 名前を付けて作成します。 3. プロジェクトの課金を有効にします。 4. API とサービス (APIs & Services) > API を有効にする (Enable APIs) に移動し、「Compute Engine API」を検索して有効化 (Enable) します。 *** ## 3) VM の作成 **マシンの種類:** | 種類 | スペック | コスト | 備考 | | --------- | -------------------- | --------- | -------------------------------------- | | e2-medium | 2 vCPU, 4GB RAM | 月額約 25 ドル | ローカルの Docker ビルドに最も信頼性がある | | e2-small | 2 vCPU, 2GB RAM | 月額約 12 ドル | Docker ビルドに推奨される最小要件 | | e2-micro | 2 vCPU (共有), 1GB RAM | 無料枠の対象 | Docker ビルドの OOM (終了コード 137) で失敗することが多い | **CLI:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud compute instances create openclaw-gateway \ --zone=us-central1-a \ --machine-type=e2-small \ --boot-disk-size=20GB \ --image-family=debian-12 \ --image-project=debian-cloud ``` **Console:** 1. Compute Engine > VM インスタンス (VM instances) > インスタンスを作成 (Create instance) に移動します。 2. 名前 (Name): `openclaw-gateway` 3. リージョン (Region): `us-central1`、ゾーン (Zone): `us-central1-a` 4. マシンの種類 (Machine type): `e2-small` 5. ブートディスク (Boot disk): Debian 12、20GB 6. 作成 (Create) します。 *** ## 4) VM への SSH 接続 **CLI:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud compute ssh openclaw-gateway --zone=us-central1-a ``` **Console:** Compute Engine ダッシュボードで、VM の横にある「SSH」ボタンをクリックします。 注意: SSH キーの伝播には、VM の作成後 1〜2 分かかる場合があります。接続が拒否された場合は、待ってから再試行してください。 *** ## 5) Docker のインストール (VM 上) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo apt-get update sudo apt-get install -y git curl ca-certificates curl -fsSL https://get.docker.com | sudo sh sudo usermod -aG docker $USER ``` グループの変更を適用するために、ログアウトして再度ログインします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} exit ``` その後、再度 SSH で接続します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud compute ssh openclaw-gateway --zone=us-central1-a ``` 確認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker --version docker compose version ``` *** ## 6) OpenClaw リポジトリのクローン ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} git clone https://github.com/openclaw/openclaw.git cd openclaw ``` このガイドでは、バイナリの永続性を保証するためにカスタムイメージをビルドすることを前提としています。 *** ## 7) 永続的なホストディレクトリの作成 Docker コンテナは一時的なものです。 長期的な状態はすべてホスト上に置く必要があります。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} mkdir -p ~/.openclaw mkdir -p ~/.openclaw/workspace ``` *** ## 8) 環境変数の設定 リポジトリのルートに `.env` を作成します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_IMAGE=openclaw:latest OPENCLAW_GATEWAY_TOKEN=change-me-now OPENCLAW_GATEWAY_BIND=lan OPENCLAW_GATEWAY_PORT=18789 OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace GOG_KEYRING_PASSWORD=change-me-now XDG_CONFIG_HOME=/home/node/.openclaw ``` 強力なシークレットを生成します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openssl rand -hex 32 ``` **このファイルをコミットしないでください。** *** ## 9) Docker Compose の設定 `docker-compose.yml` を作成または更新します。 ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} services: openclaw-gateway: image: ${OPENCLAW_IMAGE} build: . restart: unless-stopped env_file: - .env environment: - HOME=/home/node - NODE_ENV=production - TERM=xterm-256color - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND} - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT} - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN} - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD} - XDG_CONFIG_HOME=${XDG_CONFIG_HOME} - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin volumes: - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace ports: # 推奨: VM 上では Gateway をループバックのみに保ち、SSH トンネル経由でアクセスします。 # パブリックに公開するには、`127.0.0.1:` のプレフィックスを削除し、適宜ファイアウォールを設定します。 - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789" command: [ "node", "dist/index.js", "gateway", "--bind", "${OPENCLAW_GATEWAY_BIND}", "--port", "${OPENCLAW_GATEWAY_PORT}", ] ``` *** ## 10) 必要なバイナリをイメージに組み込む (重要) 実行中のコンテナ内にバイナリをインストールするのは罠です。 実行時にインストールされたものはすべて再起動時に失われます。 スキルに必要なすべての外部バイナリは、イメージのビルド時にインストールする必要があります。 以下の例は、3 つの一般的なバイナリのみを示しています: * `gog` (Gmail アクセス用) * `goplaces` (Google プレイス用) * `wacli` (WhatsApp 用) これらは例であり、完全なリストではありません。 同じパターンを使用して、必要な数のバイナリをインストールできます。 後で追加のバイナリに依存する新しいスキルを追加する場合は、以下を行う必要があります: 1. Dockerfile の更新 2. イメージの再ビルド 3. コンテナの再起動 **Dockerfile の例** ```dockerfile theme={"theme":{"light":"min-light","dark":"min-dark"}} FROM node:22-bookworm RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/* # Example binary 1: Gmail CLI RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \ | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog # Example binary 2: Google Places CLI RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \ | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces # Example binary 3: WhatsApp CLI RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \ | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli # 同じパターンを使用して、以下にさらにバイナリを追加します WORKDIR /app COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./ COPY ui/package.json ./ui/package.json COPY scripts ./scripts RUN corepack enable RUN pnpm install --frozen-lockfile COPY . . RUN pnpm build RUN pnpm ui:install RUN pnpm ui:build ENV NODE_ENV=production CMD ["node","dist/index.js"] ``` *** ## 11) ビルドと起動 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose build docker compose up -d openclaw-gateway ``` `pnpm install --frozen-lockfile` の実行中に `Killed` / `exit code 137` でビルドが失敗した場合、VM はメモリ不足です。 最小で `e2-small`、またはより信頼性の高い最初のビルドには `e2-medium` を使用してください。 LAN にバインドする場合 (`OPENCLAW_GATEWAY_BIND=lan`) は、続行する前に信頼できるブラウザのオリジンを設定します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json ``` Gateway のポートを変更した場合は、`18789` を設定したポートに置き換えてください。 バイナリを確認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose exec openclaw-gateway which gog docker compose exec openclaw-gateway which goplaces docker compose exec openclaw-gateway which wacli ``` 予想される出力: ``` /usr/local/bin/gog /usr/local/bin/goplaces /usr/local/bin/wacli ``` *** ## 12) ゲートウェイを確認する ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose logs -f openclaw-gateway ``` 成功: ``` [gateway] listening on ws://0.0.0.0:18789 ``` *** ## 13) ノート PC からアクセスする ゲートウェイのポートを転送する SSH トンネルを作成します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789 ``` ブラウザで開きます: `http://127.0.0.1:18789/` 新しいトークン化されたダッシュボードのリンクを取得します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli dashboard --no-open ``` その URL からトークンを貼り付けます。 Control UI に `unauthorized` または `disconnected (1008): pairing required` と表示された場合は、ブラウザデバイスを承認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli devices list docker compose run --rm openclaw-cli devices approve ``` *** ## 何がどこに永続化されるか (信頼できる情報源) OpenClaw は Docker で実行されますが、Docker は信頼できる情報源ではありません。 すべての長期的な状態は、再起動、再ビルド、およびマシンの再起動後も存続する必要があります。 | コンポーネント | 場所 | 永続化メカニズム | 備考 | | -------------- | --------------------------------- | ---------------- | -------------------------- | | Gateway 設定 | `/home/node/.openclaw/` | ホストのボリュームマウント | `openclaw.json`、トークンを含む | | モデル認証プロファイル | `/home/node/.openclaw/` | ホストのボリュームマウント | OAuth トークン、API キー | | スキル設定 | `/home/node/.openclaw/skills/` | ホストのボリュームマウント | スキルレベルの状態 | | エージェントワークスペース | `/home/node/.openclaw/workspace/` | ホストのボリュームマウント | コードとエージェントのアーティファクト | | WhatsApp セッション | `/home/node/.openclaw/` | ホストのボリュームマウント | QR ログインを維持します | | Gmail キーリング | `/home/node/.openclaw/` | ホストボリューム + パスワード | `GOG_KEYRING_PASSWORD` が必要 | | 外部バイナリ | `/usr/local/bin/` | Docker イメージ | ビルド時に組み込む必要があります | | Node ランタイム | コンテナのファイルシステム | Docker イメージ | イメージのビルドごとに再構築されます | | OS パッケージ | コンテナのファイルシステム | Docker イメージ | 実行時にインストールしないでください | | Docker コンテナ | エフェメラル (一時的) | 再起動可能 | 破棄しても安全です | *** ## アップデート VM 上の OpenClaw を更新するには: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} cd ~/openclaw git pull docker compose build docker compose up -d ``` *** ## トラブルシューティング **SSH connection refused** SSH キーの伝播には、VM の作成後 1〜2 分かかる場合があります。待ってから再試行してください。 **OS Login の問題** OS Login プロファイルを確認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud compute os-login describe-profile ``` アカウントに必要な IAM 権限 (Compute OS Login または Compute OS Admin Login) があることを確認してください。 **メモリ不足 (OOM)** `pnpm install --frozen-lockfile` 中に `Killed` や `exit code 137` で Docker ビルドが失敗した場合、VM は OOM によりキルされました。e2-small (最小要件) または e2-medium (ローカルビルドの信頼性を高めるために推奨) にアップグレードしてください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # まず VM を停止します gcloud compute instances stop openclaw-gateway --zone=us-central1-a # マシンの種類を変更します gcloud compute instances set-machine-type openclaw-gateway \ --zone=us-central1-a \ --machine-type=e2-small # VM を開始します gcloud compute instances start openclaw-gateway --zone=us-central1-a ``` *** ## サービスアカウント (セキュリティのベストプラクティス) 個人での使用には、デフォルトのユーザーアカウントで問題なく機能します。 自動化または CI/CD パイプラインの場合は、最小限の権限を持つ専用のサービスアカウントを作成します。 1. サービスアカウントを作成します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud iam service-accounts create openclaw-deploy \ --display-name="OpenClaw Deployment" ``` 2. Compute インスタンス管理者ロール (またはより限定的なカスタムロール) を付与します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} gcloud projects add-iam-policy-binding my-openclaw-project \ --member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \ --role="roles/compute.instanceAdmin.v1" ``` 自動化に「オーナー」ロールを使用することは避けてください。最小特権の原則を使用します。 IAM ロールの詳細については、[https://cloud.google.com/iam/docs/understanding-roles](https://cloud.google.com/iam/docs/understanding-roles) を参照してください。 *** ## 次のステップ * メッセージングチャネルの設定: [チャネル](/channels) * ローカルデバイスをノードとしてペアリング: [ノード](/nodes) * ゲートウェイの設定: [Gateway 設定](/gateway/configuration) # Hetzner Source: https://openclawdoc.org/install/hetzner Hetzner VPS と Docker で OpenClaw を常時運用するための導入、永続化、再起動時の構成を説明します。 ## 目標 Hetzner の VPS 上で Docker を使って、状態が永続化され、必要なバイナリをビルド時に組み込み、安全に再起動できる OpenClaw ゲートウェイを常時稼働させます。 「月額およそ 5 ドルで OpenClaw を 24 時間 365 日動かしたい」場合、この構成が最もシンプルで信頼しやすい選択です。Hetzner の料金は変わることがあるため、まずは最小の Debian / Ubuntu VPS を選び、OOM が出たらスケールアップしてください。 セキュリティモデルに関する前提: * 全員が同じ信頼境界に属し、ランタイムが業務専用なら、社内共有エージェント構成でも問題ありません * 専用 VPS / 専用ランタイム / 専用アカウントを保ち、そのホストに個人用の Apple、Google、ブラウザ、パスワードマネージャープロファイルを置かないでください * 利用者同士を相互に信頼できない場合は、ゲートウェイ、ホスト、OS ユーザー単位で分離してください [Security](/gateway/security) と [VPS hosting](/vps) も参照してください。 ## 何をするのか (簡単に) * Hetzner で小さな Linux サーバーを借りる * Docker を入れて、アプリ実行環境を分離する * Docker 内で OpenClaw ゲートウェイを起動する * `~/.openclaw` と `~/.openclaw/workspace` をホスト側に永続化する * ノート PC から SSH トンネル経由で Control UI へアクセスする ゲートウェイへの到達方法は次の 2 通りです。 * ノート PC からの SSH ポートフォワーディング * ファイアウォールとトークン管理を自前で行う前提での直接ポート公開 このガイドでは、Hetzner 上の Ubuntu または Debian を前提にしています。別の Linux VPS を使う場合は、パッケージ名などを適宜読み替えてください。汎用的な Docker フローについては [Docker](/install/docker) を参照してください。 *** ## クイックパス (慣れている運用者向け) 1. Hetzner VPS を用意する 2. Docker をインストールする 3. OpenClaw リポジトリを clone する 4. 永続化用のホストディレクトリを作る 5. `.env` と `docker-compose.yml` を設定する 6. 必要なバイナリをイメージへ組み込む 7. `docker compose up -d` を実行する 8. 永続化とゲートウェイ到達性を確認する *** ## 必要なもの * root アクセス可能な Hetzner VPS * ノート PC からの SSH アクセス * SSH とコピー/ペースト操作の基本知識 * 20 分程度の作業時間 * Docker と Docker Compose * モデル用の認証情報 * 任意のプロバイダー認証情報 * WhatsApp QR * Telegram ボットトークン * Gmail OAuth *** ## 1) VPS を用意する Hetzner で Ubuntu または Debian の VPS を作成します。 root で接続します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh root@YOUR_VPS_IP ``` このガイドは、VPS を stateful に運用する前提です。使い捨てインフラとして扱わないでください。 *** ## 2) Docker をインストールする (VPS 上) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} apt-get update apt-get install -y git curl ca-certificates curl -fsSL https://get.docker.com | sh ``` 確認: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker --version docker compose version ``` *** ## 3) OpenClaw リポジトリを clone する ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} git clone https://github.com/openclaw/openclaw.git cd openclaw ``` このガイドでは、バイナリの永続性を確保するためにカスタムイメージをビルドする前提です。 *** ## 4) 永続化用のホストディレクトリを作成する Docker コンテナは一時的です。長期間残る状態はすべてホスト側に置く必要があります。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} mkdir -p /root/.openclaw/workspace # Set ownership to the container user (uid 1000): chown -R 1000:1000 /root/.openclaw ``` *** ## 5) 環境変数を設定する リポジトリルートに `.env` を作成します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_IMAGE=openclaw:latest OPENCLAW_GATEWAY_TOKEN=change-me-now OPENCLAW_GATEWAY_BIND=lan OPENCLAW_GATEWAY_PORT=18789 OPENCLAW_CONFIG_DIR=/root/.openclaw OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace GOG_KEYRING_PASSWORD=change-me-now XDG_CONFIG_HOME=/home/node/.openclaw ``` 十分に強い秘密値は次で生成してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openssl rand -hex 32 ``` **このファイルはコミットしないでください。** *** ## 6) Docker Compose を設定する `docker-compose.yml` を作成または更新します。 ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} services: openclaw-gateway: image: ${OPENCLAW_IMAGE} build: . restart: unless-stopped env_file: - .env environment: - HOME=/home/node - NODE_ENV=production - TERM=xterm-256color - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND} - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT} - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN} - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD} - XDG_CONFIG_HOME=${XDG_CONFIG_HOME} - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin volumes: - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace ports: # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel. # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly. - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789" command: [ "node", "dist/index.js", "gateway", "--bind", "${OPENCLAW_GATEWAY_BIND}", "--port", "${OPENCLAW_GATEWAY_PORT}", "--allow-unconfigured", ] ``` `--allow-unconfigured` は初回ブートストラップを簡単にするためだけの指定であり、適切なゲートウェイ設定の代わりにはなりません。`gateway.auth.token` またはパスワードによる認証は必ず設定し、デプロイ先に適した安全な bind 設定を使ってください。 *** ## 7) 必要なバイナリをイメージに組み込む (重要) 実行中コンテナの中でバイナリを追加インストールするのは避けてください。ランタイム中に入れたものは、コンテナ再起動で失われます。 skills が必要とする外部バイナリは、すべてイメージビルド時にインストールしておく必要があります。 以下は、よく使う 3 つのバイナリだけを例示しています。 * Gmail アクセス用の `gog` * Google Places 用の `goplaces` * WhatsApp 用の `wacli` これはあくまで例であり、完全な一覧ではありません。同じパターンで必要な数だけ追加できます。 後から追加した skill が別のバイナリに依存する場合は、次の対応が必要です。 1. Dockerfile を更新する 2. イメージを再ビルドする 3. コンテナを再起動する **Dockerfile の例** ```dockerfile theme={"theme":{"light":"min-light","dark":"min-dark"}} FROM node:22-bookworm RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/* # Example binary 1: Gmail CLI RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \ | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog # Example binary 2: Google Places CLI RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \ | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces # Example binary 3: WhatsApp CLI RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \ | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli # Add more binaries below using the same pattern WORKDIR /app COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./ COPY ui/package.json ./ui/package.json COPY scripts ./scripts RUN corepack enable RUN pnpm install --frozen-lockfile COPY . . RUN pnpm build RUN pnpm ui:install RUN pnpm ui:build ENV NODE_ENV=production CMD ["node","dist/index.js"] ``` *** ## 8) ビルドして起動する ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose build docker compose up -d openclaw-gateway ``` バイナリ確認: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose exec openclaw-gateway which gog docker compose exec openclaw-gateway which goplaces docker compose exec openclaw-gateway which wacli ``` 期待される出力: ``` /usr/local/bin/gog /usr/local/bin/goplaces /usr/local/bin/wacli ``` *** ## 9) ゲートウェイを確認する ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose logs -f openclaw-gateway ``` 成功時の目安: ``` [gateway] listening on ws://0.0.0.0:18789 ``` ノート PC 側では次を実行します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP ``` 開く URL: `http://127.0.0.1:18789/` ゲートウェイトークンを貼り付けて接続してください。 *** ## 何がどこに残るか (source of truth) OpenClaw 自体は Docker で動きますが、Docker 自体は source of truth ではありません。長期間残る状態は、再起動、再ビルド、再起動後も維持できる必要があります。 | Component | Location | Persistence mechanism | Notes | | ------------------- | --------------------------------- | ---------------------- | -------------------------------- | | Gateway config | `/home/node/.openclaw/` | Host volume mount | Includes `openclaw.json`, tokens | | Model auth profiles | `/home/node/.openclaw/` | Host volume mount | OAuth tokens, API keys | | Skill configs | `/home/node/.openclaw/skills/` | Host volume mount | Skill-level state | | Agent workspace | `/home/node/.openclaw/workspace/` | Host volume mount | Code and agent artifacts | | WhatsApp session | `/home/node/.openclaw/` | Host volume mount | Preserves QR login | | Gmail keyring | `/home/node/.openclaw/` | Host volume + password | Requires `GOG_KEYRING_PASSWORD` | | External binaries | `/usr/local/bin/` | Docker image | Must be baked at build time | | Node runtime | Container filesystem | Docker image | Rebuilt every image build | | OS packages | Container filesystem | Docker image | Do not install at runtime | | Docker container | Ephemeral | Restartable | Safe to destroy | *** ## Infrastructure as Code (Terraform) インフラをコードで管理したいチーム向けに、コミュニティメンテナンスの Terraform 構成もあります。内容は次のとおりです。 * リモートステート管理を含むモジュール化 Terraform 構成 * cloud-init による自動プロビジョニング * デプロイスクリプト (bootstrap、deploy、backup / restore) * セキュリティ強化 (firewall、UFW、SSH のみのアクセス) * ゲートウェイアクセス用 SSH トンネル設定 **リポジトリ:** * Infrastructure: [openclaw-terraform-hetzner](https://github.com/andreesg/openclaw-terraform-hetzner) * Docker config: [openclaw-docker-config](https://github.com/andreesg/openclaw-docker-config) この方式は、上記の Docker セットアップに対して、再現可能なデプロイ、バージョン管理されたインフラ、自動ディザスタリカバリを補完します。 > **Note:** コミュニティメンテナンスです。問題報告やコントリビュート先は上記リポジトリを参照してください。 # インストール Source: https://openclawdoc.org/install/index インストーラー以外の導入方法、プラットフォーム別手順、メンテナンス項目をまとめたインストール総合ガイドです。 すでに[導入ガイド(Getting Started)](/start/getting-started)の手順を完了していますか？ その場合は準備完了です。このページでは、代替のインストール方法、プラットフォーム固有の手順、およびメンテナンスについて説明します。 ## システム要件 * **[Node 22+](/install/node)** (見つからない場合、[インストーラースクリプト](#インストール方法)がインストールします) * macOS、Linux、または Windows * ソースからビルドする場合のみ `pnpm` が必要 Windowsでは、[WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)環境でOpenClawを実行することを強く推奨します。 ## インストール方法 OpenClawのインストールには**インストーラースクリプト**の使用が推奨されます。Nodeの検出、インストール、オンボーディングをワンステップで処理します。 VPS/クラウドホストを利用する場合、サードパーティの「1クリック」マーケットプレイスイメージは可能な限り避けてください。クリーンなベースOSイメージ（例: Ubuntu LTS）を優先し、インストーラースクリプトを使用してOpenClawをご自身でインストールしてください。 CLIをダウンロードし、npm経由でグローバルにインストールして、オンボーディングウィザードを起動します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL https://openclaw.ai/install.sh | bash ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} iwr -useb https://openclaw.ai/install.ps1 | iex ``` これだけで完了です。スクリプトがNodeの検出、インストール、およびオンボーディングを処理します。 オンボーディングをスキップしてバイナリのインストールのみを行う場合は、次のように実行します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard ``` すべてのフラグ、環境変数(env vars)、CI/自動化オプションについては、[インストーラの内部仕様(Installer internals)](/install/installer)を参照してください。 すでにNode 22+がインストールされており、ご自身でインストールを管理したい場合: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm install -g openclaw@latest openclaw onboard --install-daemon ``` libvipsがグローバルにインストールされており（macOSのHomebrew経由でよく見られます）、`sharp`のビルドに失敗する場合は、ビルド済みバイナリを強制的に使用します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest ``` `sharp: Please add node-gyp to your dependencies`というエラーが表示された場合は、ビルドツールをインストールするか（macOS: Xcode CLT + `npm install -g node-gyp`）、上記の環境変数を使用してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm add -g openclaw@latest pnpm approve-builds -g # approve openclaw, node-llama-cpp, sharp, etc. openclaw onboard --install-daemon ``` pnpmでは、ビルドスクリプトを含むパッケージに対して明示的な承認が必要です。最初のインストール時に「Ignored build scripts(ビルドスクリプトが無視されました)」という警告が表示された後、`pnpm approve-builds -g` を実行し、リストされたパッケージを選択してください。 コントリビューター、またはローカルのチェックアウトから実行したい方向けの方法です。 [OpenClawリポジトリ](https://github.com/openclaw/openclaw)をクローンしてビルドします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm ui:build pnpm build ``` `openclaw`コマンドをグローバルに利用できるようにします: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm link --global ``` または、リンクをスキップして、リポジトリ内から `pnpm openclaw ...` を経由してコマンドを実行することもできます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard --install-daemon ``` より詳細な開発ワークフローについては、[セットアップ(Setup)](/start/setup)を参照してください。 ## その他のインストール方法 コンテナ化、またはヘッドレスでのデプロイメント。 ルートレスコンテナ: 一度だけ `setup-podman.sh` を実行し、その後起動スクリプトを実行します。 Nixを使用した宣言的インストール。 自動化されたフリート(fleet)のプロビジョニング。 Bunランタイムを経由したCLIのみの利用。 ## インストール後 すべてが正常に動作しているか確認します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw doctor # check for config issues openclaw status # gateway status openclaw dashboard # open the browser UI ``` カスタムのランタイムパスが必要な場合は、以下を使用します: * `OPENCLAW_HOME` - ホームディレクトリベースの内部パス用 * `OPENCLAW_STATE_DIR` - 変更可能な状態の保存場所用 * `OPENCLAW_CONFIG_PATH` - 設定ファイルの場所用 優先順位や詳細については、[環境変数(Environment vars)](/help/environment)を参照してください。 ## トラブルシューティング: `openclaw` が見つからない 簡単な診断方法: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} node -v npm -v npm prefix -g echo "$PATH" ``` `$(npm prefix -g)/bin` (macOS/Linux) または `$(npm prefix -g)` (Windows) が `$PATH` に**含まれていない**場合、シェルはグローバルなnpmバイナリ（`openclaw` を含む）を見つけることができません。 修正方法 — シェルのスタートアップファイル（`~/.zshrc` または `~/.bashrc`）に以下を追加します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export PATH="$(npm prefix -g)/bin:$PATH" ``` Windowsの場合は、`npm prefix -g` の出力を環境変数 PATH に追加してください。 その後、新しいターミナルを開くか（またはzshの場合は `rehash`、bashの場合は `hash -r` を実行します）、設定を反映させます。 ## アップデート / アンインストール OpenClawを最新の状態に保ちます。 新しいマシンに移動します。 OpenClawを完全に削除します。 # インストーラーの内部構造 Source: https://openclawdoc.org/install/installer install.sh、install-cli.sh、install.ps1 の役割、フラグ、自動化方法をまとめたインストーラ内部ガイドです。 OpenClaw には、`openclaw.ai` から配布される 3 つのインストーラースクリプトがあります。 | スクリプト | プラットフォーム | 行うこと | | ---------------------------------- | -------------------- | --------------------------------------------------------------------------- | | [`install.sh`](#installsh) | macOS / Linux / WSL | 必要に応じて Node をインストールし、npm（デフォルト）または git 経由で OpenClaw をインストール。オンボーディングの実行も可能。 | | [`install-cli.sh`](#install-clish) | macOS / Linux / WSL | Node + OpenClaw をローカルプレフィックス（`~/.openclaw`）にインストール。ルート権限は不要。 | | [`install.ps1`](#installps1) | Windows (PowerShell) | 必要に応じて Node をインストールし、npm（デフォルト）または git 経由で OpenClaw をインストール。オンボーディングの実行も可能。 | ## クイックコマンド ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} iwr -useb https://openclaw.ai/install.ps1 | iex ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun ``` インストールに成功したものの、新しいターミナルで `openclaw` が見つからない場合は、[Node.js のトラブルシューティング](/install/node#troubleshooting) を参照してください。 *** ## install.sh macOS/Linux/WSL でのほとんどの対話型インストールに推奨されます。 ### フロー (install.sh) macOS および Linux（WSL を含む）をサポート。macOS が検出され、Homebrew がない場合はインストールします。 Node のバージョンを確認し、必要に応じて Node 22 をインストールします（macOS では Homebrew、Linux の apt/dnf/yum では NodeSource セットアップスクリプトを使用）。 Git がない場合はインストールします。 * `npm` メソッド（デフォルト）：グローバル npm インストール * `git` メソッド：リポジトリをクローン/アップデートし、pnpm で依存関係をインストールしてビルドし、`~/.local/bin/openclaw` にラッパーをインストール * アップグレード時および git インストール時には、`openclaw doctor --non-interactive` を可能な範囲で実行 * 適切な場合（TTY が利用可能、オンボーディングが無効化されていない、ブートストラップ/設定チェックに合格した場合）にオンボーディングを試行 * デフォルトで `SHARP_IGNORE_GLOBAL_LIBVIPS=1` を設定 ### ソースチェックアウトの検出 OpenClaw のチェックアウトディレクトリ（`package.json` + `pnpm-workspace.yaml`）内で実行された場合、スクリプトは以下の選択肢を提示します： * チェックアウトを使用する (`git`) * グローバルインストールを使用する (`npm`) TTY が利用できず、インストールメソッドが設定されていない場合は、デフォルトで `npm` になり、警告を表示します。 無効なメソッド選択、または無効な `--install-method` 値が指定された場合、スクリプトは終了コード `2` で終了します。 ### 例 (install.sh) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run ``` | フラグ | 説明 | | ------------------------------- | ------------------------------------------------- | | `--install-method npm\|git` | インストール方法の選択（デフォルト: `npm`）。エイリアス: `--method` | | `--npm` | npm メソッドのショートカット | | `--git` | git メソッドのショートカット。エイリアス: `--github` | | `--version ` | npm バージョンまたは dist-tag（デフォルト: `latest`） | | `--beta` | 利用可能な場合は beta dist-tag を使用。なければ `latest` | | `--git-dir ` | チェックアウトディレクトリ（デフォルト: `~/openclaw`）。エイリアス: `--dir` | | `--no-git-update` | 既存のチェックアウトに対する `git pull` をスキップ | | `--no-prompt` | プロンプトを無効化 | | `--no-onboard` | オンボーディングをスキップ | | `--onboard` | オンボーディングを有効化 | | `--dry-run` | 変更を適用せずにアクションを表示 | | `--verbose` | デバッグ出力を有効化（`set -x`、npm notice レベルのログ） | | `--help` | 使い方を表示 (`-h`) | | 変数 | 説明 | | ------------------------------------------- | ------------------------------- | | `OPENCLAW_INSTALL_METHOD=git\|npm` | インストール方法 | | `OPENCLAW_VERSION=latest\|next\|` | npm バージョンまたは dist-tag | | `OPENCLAW_BETA=0\|1` | 利用可能な場合は beta を使用 | | `OPENCLAW_GIT_DIR=` | チェックアウトディレクトリ | | `OPENCLAW_GIT_UPDATE=0\|1` | git アップデートの切り替え | | `OPENCLAW_NO_PROMPT=1` | プロンプトを無効化 | | `OPENCLAW_NO_ONBOARD=1` | オンボーディングをスキップ | | `OPENCLAW_DRY_RUN=1` | ドライランモード | | `OPENCLAW_VERBOSE=1` | デバッグモード | | `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm ログレベル | | `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | sharp/libvips の動作制御（デフォルト: `1`） | *** ## install-cli.sh すべてをローカルプレフィックス（デフォルト `~/.openclaw`）の下に置き、システム Node への依存を避けたい環境向けに設計されています。 ### フロー (install-cli.sh) Node の tarball（デフォルト `22.22.0`）を `/tools/node-v` にダウンロードし、SHA-256 を検証します。 Git がない場合は、Linux では apt/dnf/yum、macOS では Homebrew を介してインストールを試みます。 `--prefix ` を使用して npm でインストールし、`/bin/openclaw` にラッパーを書き込みます。 ### 例 (install-cli.sh) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard ``` | フラグ | 説明 | | ---------------------- | ------------------------------------------------------------- | | `--prefix ` | インストールプレフィックス（デフォルト: `~/.openclaw`） | | `--version ` | OpenClaw バージョンまたは dist-tag（デフォルト: `latest`） | | `--node-version ` | Node バージョン（デフォルト: `22.22.0`） | | `--json` | NDJSON イベントを出力 | | `--onboard` | インストール後に `openclaw onboard` を実行 | | `--no-onboard` | オンボーディングをスキップ（デフォルト） | | `--set-npm-prefix` | Linux で、現在のプレフィックスが書き込み不可の場合、npm プレフィックスを `~/.npm-global` に強制 | | `--help` | 使い方を表示 (`-h`) | | 変数 | 説明 | | ------------------------------------------- | ----------------------------------------------- | | `OPENCLAW_PREFIX=` | インストールプレフィックス | | `OPENCLAW_VERSION=` | OpenClaw バージョンまたは dist-tag | | `OPENCLAW_NODE_VERSION=` | Node バージョン | | `OPENCLAW_NO_ONBOARD=1` | オンボーディングをスキップ | | `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm ログレベル | | `OPENCLAW_GIT_DIR=` | レガシーなクリーンアップ用検索パス（古い `Peekaboo` サブモジュールの削除時に使用） | | `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | sharp/libvips の動作制御（デフォルト: `1`） | *** ## install.ps1 ### フロー (install.ps1) PowerShell 5 以上が必要。 ない場合は、winget、次に Chocolatey、次に Scoop を介してインストールを試みます。 * `npm` メソッド（デフォルト）：選択された `-Tag` を使用したグローバル npm インストール * `git` メソッド：リポジトリをクローン/アップデートし、pnpm でインストール/ビルド。`%USERPROFILE%\.local\bin\openclaw.cmd` にラッパーをインストール 必要に応じて bin ディレクトリをユーザー PATH へ追加し、アップグレード時および git インストール時には `openclaw doctor --non-interactive` を可能な範囲で実行します。 ### 例 (install.ps1) ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} iwr -useb https://openclaw.ai/install.ps1 | iex ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw" ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} # install.ps1 にはまだ専用の -Verbose フラグはありません。 Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ``` | フラグ | 説明 | | ------------------------- | ---------------------------------------------- | | `-InstallMethod npm\|git` | インストール方法（デフォルト: `npm`） | | `-Tag ` | npm dist-tag（デフォルト: `latest`） | | `-GitDir ` | チェックアウトディレクトリ（デフォルト: `%USERPROFILE%\openclaw`） | | `-NoOnboard` | オンボーディングをスキップ | | `-NoGitUpdate` | `git pull` をスキップ | | `-DryRun` | アクションのみを表示 | | 変数 | 説明 | | ---------------------------------- | ------------- | | `OPENCLAW_INSTALL_METHOD=git\|npm` | インストール方法 | | `OPENCLAW_GIT_DIR=` | チェックアウトディレクトリ | | `OPENCLAW_NO_ONBOARD=1` | オンボーディングをスキップ | | `OPENCLAW_GIT_UPDATE=0` | git pull を無効化 | | `OPENCLAW_DRY_RUN=1` | ドライランモード | `-InstallMethod git` が使用され、Git がない場合、スクリプトは終了し、Git for Windows のリンクを表示します。 *** ## CI と自動化 予測可能な実行のために、非対話型フラグ/環境変数を使用してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \ curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard ``` *** ## トラブルシューティング `git` インストール方法には Git が必要です。`npm` インストールでも、依存関係が git URL を使用している場合の `spawn git ENOENT` エラーを避けるために Git がチェック/インストールされます。 一部の Linux セットアップでは、npm のグローバルプレフィックスが root 所有のパスを指しています。`install.sh` はプレフィックスを `~/.npm-global` に切り替え、シェルの rc ファイル（存在する場合）に PATH の export を追記できます。 スクリプトは、sharp がシステムの libvips に対してビルドされるのを避けるため、デフォルトで `SHARP_IGNORE_GLOBAL_LIBVIPS=1` を設定します。これを上書きするには： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ``` Git for Windows をインストールし、PowerShell を開き直し、インストーラーを再実行してください。 `npm config get prefix` を実行し、そのディレクトリをユーザー PATH に追加し（Windows では `\bin` サフィックスは不要）、PowerShell を開き直してください。 `install.ps1` には現在 `-Verbose` スイッチはありません。 スクリプトレベルの診断には PowerShell のトレースを使用してください： ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ``` 通常は PATH の問題です。[Node.js のトラブルシューティング](/install/node#troubleshooting) を参照してください。 # macOS VMs Source: https://openclawdoc.org/install/macos-vm iMessage や分離環境が必要な場合に、macOS VM 上で OpenClaw を動かす構成と注意点を説明します。 ## 推奨されるデフォルト (ほとんどのユーザー向け) * **小規模な Linux VPS**: 低コストで常時稼働するゲートウェイを用意したい場合。[VPS hosting](/vps) を参照してください。 * **専用ハードウェア** (Mac mini または Linux マシン): ブラウザ自動化のために完全な制御と **住宅用 IP** が必要な場合。多くのサイトはデータセンター IP をブロックするため、ローカルブラウジングの方が通りやすいことがあります。 * **ハイブリッド**: ゲートウェイは安価な VPS に置き、ブラウザや UI の自動化が必要なときだけ Mac を **ノード** として接続する構成です。[Nodes](/nodes) と [Gateway remote](/gateway/remote) を参照してください。 macOS 専用機能 (iMessage / BlueBubbles) が必要な場合や、普段使いの Mac から厳密に分離したい場合に macOS VM を使います。 ## macOS VM のオプション ### Apple Silicon Mac (Lume) 上のローカル VM [Lume](https://cua.ai/docs/lume) を使用して、既存の Apple Silicon Mac 上のサンドボックス化された macOS VM で OpenClaw を実行します。 これにより、以下の利点が得られます: * 分離された完全な macOS 環境 (ホストはクリーンなまま) * BlueBubbles 経由の iMessage サポート (Linux/Windows では不可能) * VM をクローンすることによる即時リセット * 追加のハードウェアやクラウドのコストなし ### ホスト型 Mac プロバイダー (クラウド) クラウドで macOS を使用したい場合は、ホスト型 Mac プロバイダも機能します: * [MacStadium](https://www.macstadium.com/) (ホスト型 Mac) * 他のホスト型 Mac ベンダーでも構いません。各社の VM と SSH に関する手順に従ってください macOS VM への SSH アクセスを取得したら、以下のステップ 6 から続行します。 *** ## クイックパス (Lume、上級ユーザー向け) 1. Lume のインストール 2. `lume create openclaw --os macos --ipsw latest` 3. Setup Assistant を完了し、Remote Login (SSH) を有効にする 4. `lume run openclaw --no-display` 5. SSH で接続し、OpenClaw をインストールし、チャネルを設定する 6. 完了 *** ## 必要なもの (Lume) * Apple Silicon Mac (M1/M2/M3/M4) * ホスト上の macOS Sequoia 以降 * VM あたり約 60 GB の空きディスク容量 * 約 20 分 *** ## 1) Lume のインストール ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" ``` `~/.local/bin` が PATH にない場合: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc ``` 確認: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} lume --version ``` ドキュメント: [Lume のインストール](https://cua.ai/docs/lume/guide/getting-started/installation) *** ## 2) macOS VM の作成 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} lume create openclaw --os macos --ipsw latest ``` これにより macOS がダウンロードされ、VM が作成されます。 VNC ウィンドウが自動的に開きます。 注意: 接続によっては、ダウンロードに時間がかかる場合があります。 *** ## 3) Setup Assistant の完了 VNC ウィンドウで: 1. 言語と地域を選択します 2. Apple ID をスキップします (後で iMessage が必要な場合はサインインします) 3. ユーザーアカウントを作成します (ユーザー名とパスワードを覚えておいてください) 4. すべてのオプション機能をスキップします セットアップが完了したら、SSH を有効にします: 1. System Settings → General → Sharing を開きます 2. "Remote Login" を有効にします *** ## 4) VM の IP アドレスの取得 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} lume get openclaw ``` IP アドレス (通常は `192.168.64.x`) を探します。 *** ## 5) VM への SSH 接続 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh youruser@192.168.64.X ``` `youruser` を作成したアカウントに、IP を VM の IP に置き換えます。 *** ## 6) OpenClaw のインストール VM 内で: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm install -g openclaw@latest openclaw onboard --install-daemon ``` オンボーディングのプロンプトに従って、モデルプロバイダ (Anthropic、OpenAI など) を設定します。 *** ## 7) チャネルの設定 設定ファイルを編集します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} nano ~/.openclaw/openclaw.json ``` チャネルを追加します: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "whatsapp": { "dmPolicy": "allowlist", "allowFrom": ["+15551234567"] }, "telegram": { "botToken": "YOUR_BOT_TOKEN" } } } ``` 次に WhatsApp にログインします (QR をスキャン): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels login ``` *** ## 8) VM をヘッドレスで実行 VM を停止し、ディスプレイなしで再起動します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} lume stop openclaw lume run openclaw --no-display ``` VM はバックグラウンドで実行されます。 OpenClaw のデーモンは Gateway を実行し続けます。 ステータスを確認するには: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh youruser@192.168.64.X "openclaw status" ``` *** ## 補足: iMessage 統合 これは macOS で動かす大きな利点です。[BlueBubbles](https://bluebubbles.app) を使って iMessage を OpenClaw に接続できます。 VM 内で: 1. bluebubbles.app から BlueBubbles をダウンロードします 2. Apple ID でサインインします 3. Web API を有効にし、パスワードを設定します 4. BlueBubbles Webhook を Gateway に向けます (例: `https://your-gateway-host:3000/bluebubbles-webhook?password=`) OpenClaw 設定に追加します: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "channels": { "bluebubbles": { "serverUrl": "http://localhost:1234", "password": "your-api-password", "webhookPath": "/bluebubbles-webhook" } } } ``` ゲートウェイを再起動します。これでエージェントが iMessage を送受信できるようになります。 セットアップの詳細全体: [BlueBubbles チャネル](/channels/bluebubbles) *** ## ゴールデンイメージを保存する さらにカスタマイズする前に、クリーンな状態のスナップショットを作成します: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} lume stop openclaw lume clone openclaw openclaw-golden ``` いつでもリセット: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} lume stop openclaw && lume delete openclaw lume clone openclaw-golden openclaw lume run openclaw --no-display ``` *** ## 24 時間 365 日動かす 以下の方法で VM を実行し続けます: * Mac を電源に接続したままにする * System Settings → Energy Saver でスリープを無効にする * 必要に応じて `caffeinate` を使用する 真の常時稼働のためには、専用の Mac mini または小規模な VPS を検討してください。 [VPS ホスティング](/vps) を参照してください。 *** ## トラブルシューティング | 問題 | 解決策 | | ----------------------- | -------------------------------------------------------------------- | | VM に SSH 接続できない | VM の System Settings で "Remote Login" が有効になっているか確認してください | | VM の IP が表示されない | VM が完全に起動するまで待ち、再度 `lume get openclaw` を実行してください | | Lume コマンドが見つからない | PATH に `~/.local/bin` を追加してください | | WhatsApp の QR がスキャンできない | `openclaw channels login` を実行するときに (ホストではなく) VM にログインしていることを確認してください | *** ## 関連ドキュメント * [VPS hosting](/vps) * [Nodes](/nodes) * [Gateway remote](/gateway/remote) * [BlueBubbles channel](/channels/bluebubbles) * [Lume クイックスタート](https://cua.ai/docs/lume/guide/getting-started/quickstart) * [Lume CLI リファレンス](https://cua.ai/docs/lume/reference/cli-reference) * [無人 VM セットアップ](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup) (高度) * [Docker サンドボックス化](/install/docker) (代替の分離アプローチ) # 移行ガイド Source: https://openclawdoc.org/install/migrating 既存の OpenClaw Gateway をオンボーディングし直さずに別マシンへ移行する手順と確認項目をまとめます。 このガイドでは、**オンボーディングをやり直すことなく**、OpenClaw Gateway をあるマシンから別のマシンへ移行する方法を説明します。 移行のコンセプトは非常にシンプルです： * **状態ディレクトリ**（`$OPENCLAW_STATE_DIR`、デフォルト：`~/.openclaw/`）をコピーします — これには設定、認証、セッション、チャンネルの状態が含まれます。 * **ワークスペース**（デフォルト：`~/.openclaw/workspace/`）をコピーします — これにはエージェントのファイル（記憶、プロンプトなど）が含まれます。 しかし、**プロファイル**、**権限**、および**部分的なコピー**に関するよくある落とし穴があります。 ## 始める前に（何を移行するか） ### 1) 状態ディレクトリを特定する ほとんどのインストールではデフォルトが使用されます： * **状態ディレクトリ：** `~/.openclaw/` ただし、以下を使用している場合は異なる場合があります： * `--profile ` (通常は `~/.openclaw-/` になります) * `OPENCLAW_STATE_DIR=/some/path` 不明な場合は、**古い**マシンで以下を実行してください： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw status ``` 出力内の `OPENCLAW_STATE_DIR` やプロファイルに関する記述を確認してください。複数の Gateway を実行している場合は、プロファイルごとに繰り返してください。 ### 2) ワークスペースを特定する 一般的なデフォルト： * `~/.openclaw/workspace/` (推奨ワークスペース) * 自分で作成したカスタムフォルダ ワークスペースは、`MEMORY.md`、`USER.md`、`memory/*.md` などのファイルが置かれている場所です。 ### 3) 何が保持されるかを理解する 状態ディレクトリとワークスペースの**両方**をコピーすると、以下が保持されます： * ゲートウェイの構成 (`openclaw.json`) * 認証プロファイル / API キー / OAuth トークン * セッション履歴 + エージェントの状態 * チャネルの状態（例：WhatsApp のログイン/セッション） * ワークスペースのファイル（記憶、スキルのメモなど） ワークスペース**のみ**をコピーした場合（例：Git 経由）、以下は保持されません： * セッション * 認証情報 * チャネルのログイン これらは `$OPENCLAW_STATE_DIR` の下に保存されています。 ## 移行の手順（推奨） ### 手順 0 — バックアップを作成する（古いマシン） コピー中にファイルが変更されないよう、**古い**マシンで最初にゲートウェイを停止します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway stop ``` （オプションですが推奨）状態ディレクトリとワークスペースをアーカイブします： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # プロファイルやカスタムの場所を使用している場合はパスを調整してください cd ~ tar -czf openclaw-state.tgz .openclaw tar -czf openclaw-workspace.tgz .openclaw/workspace ``` 複数のプロファイル/状態ディレクトリ（例：`~/.openclaw-main`, `~/.openclaw-work`）がある場合は、それぞれをアーカイブしてください。 ### 手順 1 — 新しいマシンに OpenClaw をインストールする **新しい**マシンに CLI（および必要に応じて Node）をインストールします： * 参照：[インストール](/install) この段階で、オンボーディングによって新しい `~/.openclaw/` が作成されても問題ありません。次の手順でそれを上書きします。 ### 手順 2 — 状態ディレクトリ + ワークスペースを新しいマシンにコピーする 以下の**両方**をコピーします： * `$OPENCLAW_STATE_DIR` (デフォルト `~/.openclaw/`) * ワークスペース (デフォルト `~/.openclaw/workspace/`) 一般的な方法： * `scp` で tarball を転送して展開する * SSH 経由で `rsync -a` を使用する * 外付けドライブを使用する コピー後、以下を確認してください： * 隠しディレクトリ（例：`.openclaw/`）が含まれていること * ファイルの所有権がゲートウェイを実行するユーザーに対して正しいこと ### 手順 3 — Doctor を実行する（移行 + サービスの修復） **新しい**マシンで： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw doctor ``` Doctor は「安全で確実な」コマンドです。サービスを修復し、構成の移行を適用し、不一致について警告します。 その後： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway restart openclaw status ``` ## よくある落とし穴（とその回避策） ### 落とし穴：プロファイル / 状態ディレクトリの不一致 古いゲートウェイをプロファイル（または `OPENCLAW_STATE_DIR`）を指定して実行しており、新しいゲートウェイで別のものを使用している場合、以下のような症状が発生します： * 構成の変更が反映されない * チャネルが見つからない / ログアウトしている * セッション履歴が空 修正：移行したものと**同じ**プロファイル/状態ディレクトリを使用してゲートウェイ / サービスを実行し、その後 `openclaw doctor` を再実行してください。 ### 落とし穴：`openclaw.json` のみをコピーする `openclaw.json` だけでは不十分です。多くのプロバイダーは状態を以下の場所に保存します： * `$OPENCLAW_STATE_DIR/credentials/` * `$OPENCLAW_STATE_DIR/agents//...` 必ず `$OPENCLAW_STATE_DIR` フォルダ全体を移行してください。 ### 落とし穴：権限 / 所有権 root としてコピーしたり、ユーザーを変更したりした場合、ゲートウェイが認証情報やセッションを読み取れなくなる可能性があります。 修正：状態ディレクトリとワークスペースの所有者が、ゲートウェイを実行するユーザーであることを確認してください。 ### 落とし穴：リモートモードとローカルモード間の移行 * UI (WebUI/TUI) が**リモート**ゲートウェイを指している場合、セッションストアとワークスペースはリモートホストが所有しています。 * ラップトップを移行しても、リモートゲートウェイの状態は移動しません。 リモートモードの場合は、**ゲートウェイホスト**を移行してください。 ### 落とし穴：バックアップ内のシークレット `$OPENCLAW_STATE_DIR` には機密情報（API キー、OAuth トークン、WhatsApp 認証情報）が含まれています。バックアップは本番環境のシークレットと同様に扱ってください： * 暗号化して保存する * 安全でないチャネルでの共有を避ける * 漏洩の疑いがある場合はキーをローテーションする ## 検証チェックリスト 新しいマシンで以下を確認してください： * `openclaw status` で Gateway が実行されていることが示されている * チャンネルがまだ接続されている（例：WhatsApp の再ペアリングが不要） * ダッシュボードが開き、既存のセッションが表示される * ワークスペースのファイル（記憶、設定）が存在する ## 関連情報 * [Doctor](/gateway/doctor) * [Gateway のトラブルシューティング](/gateway/troubleshooting) * [OpenClaw はデータをどこに保存しますか？](/help/faq#where-does-openclaw-store-its-data) # Nix Source: https://openclawdoc.org/install/nix Home Manager ベースで OpenClaw を宣言的に導入する nix-openclaw の使い方を案内します。 Nix で OpenClaw を使う場合の推奨手段は、**[nix-openclaw](https://github.com/openclaw/nix-openclaw)** を利用する方法です。必要なものが一通り揃った Home Manager モジュールとして提供されています。 ## クイックスタート 次の内容を AI エージェント (Claude、Cursor など) に貼り付けてください。 ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} I want to set up nix-openclaw on my Mac. Repository: github:openclaw/nix-openclaw What I need you to do: 1. Check if Determinate Nix is installed (if not, install it) 2. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix 3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot) 4. Set up secrets (bot token, model provider API key) - plain files at ~/.secrets/ is fine 5. Fill in the template placeholders and run home-manager switch 6. Verify: launchd running, bot responds to messages Reference the nix-openclaw README for module options. ``` > **📦 完全なガイド: [github.com/openclaw/nix-openclaw](https://github.com/openclaw/nix-openclaw)** > > nix-openclaw リポジトリは、Nix インストールの信頼できる情報源です。このページは単なる概要です。 ## 得られるもの * Gateway + macOS アプリ + ツール (whisper, spotify, cameras) — すべて固定 * 再起動後も残る Launchd サービス * 宣言的設定を備えたプラグインシステム * インスタントロールバック: `home-manager switch --rollback` *** ## Nix モードのランタイムの動作 `OPENCLAW_NIX_MODE=1` が設定されている場合 (nix-openclaw では自動): OpenClaw には、設定を決定論的に保ち、自動インストール系のフローを無効にする **Nix モード** があります。次を export して有効にします。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_NIX_MODE=1 ``` macOS では、GUI アプリは自動的にシェルの環境変数を継承しません。 defaults 経由で Nix モードを有効にすることもできます: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} defaults write ai.openclaw.mac openclaw.nixMode -bool true ``` ### Config + 状態のパス OpenClaw は `OPENCLAW_CONFIG_PATH` から JSON5 設定を読み取り、`OPENCLAW_STATE_DIR` にミュータブルなデータを保存します。 必要に応じて、`OPENCLAW_HOME` を設定して、内部パス解決に使用されるベースのホームディレクトリを制御することもできます。 * `OPENCLAW_HOME` (優先順位のデフォルト: `HOME` / `USERPROFILE` / `os.homedir()`) * `OPENCLAW_STATE_DIR` (デフォルト: `~/.openclaw`) * `OPENCLAW_CONFIG_PATH` (デフォルト: `$OPENCLAW_STATE_DIR/openclaw.json`) Nix 環境で実行する場合は、ランタイム状態や設定が不変ストアの外に出るよう、これらのパスを Nix 管理下の適切な場所へ明示的に向けてください。 ### Nix モードでのランタイムの動作 * 自動インストールや自己変更系フローは無効になります * 依存関係が不足している場合、Nix 固有の修復メッセージが表示されます * 対応 UI では、読み取り専用の Nix モードバナーが表示されます ## パッケージングに関する注意 (macOS) macOS のパッケージングフローは、以下にある安定した Info.plist テンプレートを想定しています: ``` apps/macos/Sources/OpenClaw/Resources/Info.plist ``` [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) は、このテンプレートをアプリバンドルにコピーし、動的フィールド (バンドル ID、バージョン/ビルド、Git SHA、Sparkle キー) にパッチを当てます。これにより、SwiftPM パッケージングと Nix ビルド (完全な Xcode ツールチェーンに依存しない) で plist が決定論的に保たれます。 ## 関連 * [nix-openclaw](https://github.com/openclaw/nix-openclaw) — 完全なセットアップガイド * [ウィザード](/start/wizard) — Nix 以外の CLI セットアップ * [Docker](/install/docker) — コンテナ化されたセットアップ # Northflank にデプロイ Source: https://openclawdoc.org/install/northflank Northflank のワンクリックテンプレートと /setup を使って、ブラウザ中心で OpenClaw を導入する手順です。 ワンクリックテンプレートを使用して OpenClaw を Northflank にデプロイし、ブラウザでセットアップを完了します。 これは「サーバー上にターミナルがない」最も簡単な方法です: Northflank が Gateway を実行し、すべてを `/setup` ウェブウィザードで設定します。 ## はじめかた 1. [Deploy OpenClaw](https://northflank.com/stacks/deploy-openclaw) をクリックしてテンプレートを開きます。 2. まだアカウントを持っていない場合は、[Northflank でアカウントを作成](https://app.northflank.com/signup)します。 3. **Deploy OpenClaw now** をクリックします。 4. 必須の環境変数を設定します: `SETUP_PASSWORD`。 5. **Deploy stack** をクリックして、OpenClaw テンプレートをビルドして実行します。 6. デプロイが完了するのを待ち、**View resources** をクリックします。 7. OpenClaw サービスを開きます。 8. パブリックな OpenClaw URL を開き、`/setup` でセットアップを完了します。 9. `/openclaw` で Control UI を開きます。 ## 得られるもの * ホストされた OpenClaw Gateway + Control UI * `/setup` のウェブセットアップウィザード (ターミナルコマンド不要) * 設定/認証情報/ワークスペースが再デプロイ後も残る Northflank Volume (`/data`) を介した永続ストレージ ## セットアップの流れ 1. `https:///setup` にアクセスし、`SETUP_PASSWORD` を入力します。 2. モデル/認証プロバイダを選択し、キーを貼り付けます。 3. (オプション) Telegram/Discord/Slack トークンを追加します。 4. **Run setup** をクリックします。 5. `https:///openclaw` で Control UI を開きます。 Telegram DM がペアリングに設定されている場合、セットアップウィザードはペアリングコードを承認できます。 ## チャットトークンの取得 ### Telegram ボットトークン 1. Telegram で `@BotFather` にメッセージを送信します。 2. `/newbot` を実行します。 3. トークンをコピーします (`123456789:AA...` のような形式)。 4. `/setup` に貼り付けます。 ### Discord ボットトークン 1. [https://discord.com/developers/applications](https://discord.com/developers/applications) に移動します。 2. **New Application** → 名前を選択します。 3. **Bot** → **Add Bot** 4. Bot → Privileged Gateway Intents の下にある **MESSAGE CONTENT INTENT** を有効にします (起動時にボットがクラッシュしないようにするために必須です)。 5. **Bot Token** をコピーして `/setup` に貼り付けます。 6. ボットをサーバーに招待します (OAuth2 URL Generator; スコープ: `bot`, `applications.commands`)。 # Podman Source: https://openclawdoc.org/install/podman rootless Podman で OpenClaw Gateway を動かすためのイメージ利用方法、設定、運用上の注意点を説明します。 **ルートレス** Podman コンテナで OpenClaw ゲートウェイを実行します。使用するイメージは Docker と同じで、リポジトリの [Dockerfile](https://github.com/openclaw/openclaw/blob/main/Dockerfile) からビルドします。 ## 要件 * Podman (ルートレス) * 初回セットアップ用の sudo 権限 (ユーザー作成、イメージビルド) ## クイックスタート **1. 初回セットアップ** (リポジトリルートで実行。ユーザー作成、イメージビルド、起動スクリプト配置を行います): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ./setup-podman.sh ``` これにより、ウィザードを実行しなくてもゲートウェイが起動できるよう、最小構成の `~openclaw/.openclaw/openclaw.json` (`gateway.mode="local"` を設定) も作成されます。 デフォルトでは、コンテナは systemd サービスとしては **インストールされません**。起動は手動です (後述)。自動起動と再起動を含む本番向け構成にしたい場合は、代わりに systemd の Quadlet ユーザーサービスとして導入してください。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ./setup-podman.sh --quadlet ``` (`OPENCLAW_PODMAN_QUADLET=1` を設定しても同じです。コンテナと起動スクリプトだけを入れたい場合は `--container` を使います。) 任意のビルド時環境変数 (`setup-podman.sh` 実行前に設定): * `OPENCLAW_DOCKER_APT_PACKAGES` — イメージのビルド中に追加の apt パッケージをインストールします * `OPENCLAW_EXTENSIONS` — 拡張機能の依存関係を事前インストールします (スペース区切りの拡張機能名。例: `diagnostics-otel matrix`) **2. ゲートウェイを起動** (手動、簡易スモークテスト向け): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ./scripts/run-openclaw-podman.sh launch ``` **3. オンボーディングウィザード** (チャネルやプロバイダーを追加する場合など): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ./scripts/run-openclaw-podman.sh launch setup ``` その後 `http://127.0.0.1:18789/` を開き、`~openclaw/.openclaw/.env` にあるトークン、またはセットアップ時に表示された値を使ってアクセスします。 ## Systemd (Quadlet、オプション) `./setup-podman.sh --quadlet` (または `OPENCLAW_PODMAN_QUADLET=1`) を実行すると、[Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) ユニットが入り、ゲートウェイが `openclaw` ユーザーの systemd ユーザーサービスとして動作します。サービスはセットアップの最後に有効化され、そのまま起動されます。 * **開始:** `sudo systemctl --machine openclaw@ --user start openclaw.service` * **停止:** `sudo systemctl --machine openclaw@ --user stop openclaw.service` * **ステータス:** `sudo systemctl --machine openclaw@ --user status openclaw.service` * **ログ:** `sudo journalctl --machine openclaw@ --user -u openclaw.service -f` Quadlet ファイルは `~openclaw/.config/containers/systemd/openclaw.container` にあります。ポートや環境変数を変更する場合は、そのファイル、または参照元の `.env` を編集し、`sudo systemctl --machine openclaw@ --user daemon-reload` を実行してからサービスを再起動してください。起動時には、`openclaw` の lingering が有効であれば自動起動します (loginctl が使える環境ではセットアップ時に有効化されます)。 初回セットアップで Quadlet を使わなかった場合でも、後から `./setup-podman.sh --quadlet` を再実行すれば追加できます。 ## openclaw ユーザー (非ログイン) `setup-podman.sh` は、専用のシステムユーザー `openclaw` を作成します。 * **シェル:** `nologin` — 対話ログインを許可せず、攻撃面を減らします * **ホーム:** 例 `/home/openclaw` — `~/.openclaw` (設定、ワークスペース) と起動スクリプト `run-openclaw-podman.sh` を配置します * **ルートレス Podman:** ユーザーには **subuid** と **subgid** の範囲が必要です。多くのディストリビューションでは、ユーザー作成時に自動割り当てされます。セットアップで警告が出た場合は、`/etc/subuid` と `/etc/subgid` に次の行を追加してください。 ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw:100000:65536 ``` その後、そのユーザーとしてゲートウェイを起動します (cron や systemd から実行する場合など)。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo -u openclaw /home/openclaw/run-openclaw-podman.sh sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup ``` * **設定:** `/home/openclaw/.openclaw` にアクセスできるのは `openclaw` と root のみです。設定編集は、ゲートウェイ起動後に Control UI を使うか、`sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json` を実行してください。 ## 環境と設定 * **トークン:** `~openclaw/.openclaw/.env` に `OPENCLAW_GATEWAY_TOKEN` として保存されます。存在しない場合は、`setup-podman.sh` と `run-openclaw-podman.sh` が `openssl`、`python3`、または `od` を使って生成します。 * **任意設定:** 同じ `.env` で、プロバイダーキー (例: `GROQ_API_KEY`、`OLLAMA_API_KEY`) やその他の OpenClaw 環境変数を設定できます。 * **ホストポート:** デフォルトでは、スクリプトは `18789` (Gateway) と `18790` (ブリッジ) をマップします。 起動時に、 **ホスト** のポートマッピングを `OPENCLAW_PODMAN_GATEWAY_HOST_PORT` と `OPENCLAW_PODMAN_BRIDGE_HOST_PORT` で上書きします。 * **ゲートウェイの bind:** デフォルトでは、`run-openclaw-podman.sh` は安全なローカルアクセスのため `--bind loopback` で起動します。LAN に公開する場合は `OPENCLAW_GATEWAY_BIND=lan` を設定し、`openclaw.json` で `gateway.controlUi.allowedOrigins` を構成するか、明示的に host-header fallback を有効にしてください。 * **パス:** ホスト側の既定値は `~openclaw/.openclaw` と `~openclaw/.openclaw/workspace` です。必要に応じて `OPENCLAW_CONFIG_DIR` と `OPENCLAW_WORKSPACE_DIR` で上書きします。 ## ストレージモデル * **永続的なホストデータ:** `OPENCLAW_CONFIG_DIR` と `OPENCLAW_WORKSPACE_DIR` はコンテナにバインドマウントされ、ホスト上の状態を保持します。 * **一時サンドボックス tmpfs:** `agents.defaults.sandbox` を有効にすると、ツールサンドボックスコンテナは `/tmp`、`/var/tmp`、`/run` に `tmpfs` をマウントします。これらはメモリ上の一時領域で、サンドボックスコンテナ終了とともに消えます。最上位の Podman コンテナ側では独自の tmpfs は追加しません。 * **ディスク増加の主な箇所:** `media/`、`agents//sessions/sessions.json`、トランスクリプト JSONL、`cron/runs/*.jsonl`、および `/tmp/openclaw/` (または設定した `logging.file`) 配下のローテーションログに注意してください。 `setup-podman.sh` は現在、イメージ tar をプライベートな一時ディレクトリへ退避し、セットアップ時に選ばれたベースディレクトリを表示します。非 root 実行では、安全に使える場合にのみ `TMPDIR` を採用し、それ以外は `/var/tmp`、次に `/tmp` へフォールバックします。保存した tar は所有者のみが参照でき、対象ユーザーの `podman load` へストリーミングされるため、呼び出し元の private な一時ディレクトリがセットアップの妨げになることはありません。 ## 便利なコマンド * **ログ:** Quadlet の場合: `sudo journalctl --machine openclaw@ --user -u openclaw.service -f`。 スクリプトの場合: `sudo -u openclaw podman logs -f openclaw` * **停止:** Quadlet の場合: `sudo systemctl --machine openclaw@ --user stop openclaw.service`。 スクリプトの場合: `sudo -u openclaw podman stop openclaw` * **再開:** Quadlet の場合: `sudo systemctl --machine openclaw@ --user start openclaw.service`。 スクリプトの場合: 起動スクリプトまたは `podman start openclaw` を再実行します。 * **コンテナの削除:** `sudo -u openclaw podman rm -f openclaw` — ホスト上の設定とワークスペースは保持されます。 ## トラブルシューティング * **設定や auth-profiles で Permission denied (EACCES) が出る:** コンテナはデフォルトで `--userns=keep-id` を使い、スクリプトを実行したホストユーザーと同じ uid/gid で動きます。ホスト側の `OPENCLAW_CONFIG_DIR` と `OPENCLAW_WORKSPACE_DIR` がそのユーザー所有になっているか確認してください。 * **Gateway の起動がブロックされる (`gateway.mode=local` がない):** `~openclaw/.openclaw/openclaw.json` が存在し、 `gateway.mode="local"` が設定されていることを確認してください。 `setup-podman.sh` は、存在しない場合はこのファイルを作成します。 * **`openclaw` ユーザーでルートレス Podman が失敗する:** `/etc/subuid` と `/etc/subgid` に `openclaw` 用の行 (例: `openclaw:100000:65536`) があるか確認してください。なければ追加して再実行します。 * **コンテナ名が使用中:** 起動スクリプトは `podman run --replace` を使用するため、再開時に既存のコンテナが置き換えられます。 手動でクリーンアップするには: `podman rm -f openclaw`。 * **`openclaw` として実行したときにスクリプトが見つからない:** `run-openclaw-podman.sh` が `openclaw` のホーム (例: `/home/openclaw/run-openclaw-podman.sh`) にコピーされるよう、`setup-podman.sh` を実行済みか確認してください。 * **Quadlet サービスが見つからないか、起動に失敗する:** `.container` ファイルを編集した後、 `sudo systemctl --machine openclaw@ --user daemon-reload` を実行します。 Quadlet には cgroups v2 が必要です: `podman info --format '{{.Host.CgroupsVersion}}'` が `2` を表示するはずです。 ## オプション: 自分のユーザーで実行する 専用の `openclaw` ユーザーを使わず、通常ユーザーとしてゲートウェイを動かすこともできます。その場合は、イメージをビルドし、`OPENCLAW_GATEWAY_TOKEN` を含む `~/.openclaw/.env` を作成し、`--userns=keep-id` と `~/.openclaw` へのマウント付きでコンテナを起動します。起動スクリプトは `openclaw` ユーザーフロー向けなので、単一ユーザー構成ではスクリプト内の `podman run` 相当を手動実行し、設定とワークスペースを自分のホームへ向けてください。通常は、`setup-podman.sh` を使い、`openclaw` ユーザーで分離運用する方法を推奨します。 # Railway にデプロイ Source: https://openclawdoc.org/install/railway Railway のテンプレートと Volume を使って、ブラウザ中心で OpenClaw を導入する手順をまとめます。 ワンクリックテンプレートを使用して OpenClaw を Railway にデプロイし、ブラウザでセットアップを完了します。 これは「サーバー上にターミナルがない」最も簡単な方法です: Railway が Gateway を実行し、すべてを `/setup` ウェブウィザードで設定します。 ## クイックチェックリスト (新規ユーザー向け) 1. **Deploy on Railway** (以下) をクリックします。 2. `/data` にマウントされた **Volume** を追加します。 3. 必須の **Variables** (少なくとも `SETUP_PASSWORD`) を設定します。 4. ポート `8080` で **HTTP Proxy** を有効にします。 5. `https:///setup` を開き、ウィザードを完了します。 ## ワンクリックデプロイ Deploy on Railway デプロイ後、**Railway → your service → Settings → Domains** でパブリック URL を見つけます。 Railway は次のいずれかを行います: * 生成されたドメイン (多くの場合 `https://.up.railway.app`) を提供する、または * カスタムドメインを添付した場合はそれを使用する。 次に、以下を開きます: * `https:///setup` — セットアップウィザード (パスワード保護あり) * `https:///openclaw` — Control UI ## 得られるもの * ホストされた OpenClaw Gateway + Control UI * `/setup` のウェブセットアップウィザード (ターミナルコマンド不要) * 設定/認証情報/ワークスペースが再デプロイ後も残る Railway Volume (`/data`) を介した永続ストレージ * 後で Railway から移行するための `/setup/export` でのバックアップエクスポート ## 必須の Railway 設定 ### Public Networking サービスの **HTTP Proxy** を有効にします。 * Port: `8080` ### Volume (必須) 以下にマウントされたボリュームを添付します: * `/data` ### Variables サービスでこれらの変数を設定します: * `SETUP_PASSWORD` (必須) * `PORT=8080` (必須 — Public Networking のポートと一致する必要があります) * `OPENCLAW_STATE_DIR=/data/.openclaw` (推奨) * `OPENCLAW_WORKSPACE_DIR=/data/workspace` (推奨) * `OPENCLAW_GATEWAY_TOKEN` (推奨; 管理者シークレットとして扱います) ## セットアップの流れ 1. `https:///setup` にアクセスし、`SETUP_PASSWORD` を入力します。 2. モデル/認証プロバイダを選択し、キーを貼り付けます。 3. (オプション) Telegram/Discord/Slack トークンを追加します。 4. **Run setup** をクリックします。 Telegram DM がペアリングに設定されている場合、セットアップウィザードはペアリングコードを承認できます。 ## チャットトークンの取得 ### Telegram ボットトークン 1. Telegram で `@BotFather` にメッセージを送信します。 2. `/newbot` を実行します。 3. トークンをコピーします (`123456789:AA...` のような形式)。 4. `/setup` に貼り付けます。 ### Discord ボットトークン 1. [https://discord.com/developers/applications](https://discord.com/developers/applications) に移動します。 2. **New Application** → 名前を選択します。 3. **Bot** → **Add Bot** 4. Bot → Privileged Gateway Intents の下にある **MESSAGE CONTENT INTENT** を有効にします (起動時にボットがクラッシュしないようにするために必須です)。 5. **Bot Token** をコピーして `/setup` に貼り付けます。 6. ボットをサーバーに招待します (OAuth2 URL Generator; スコープ: `bot`, `applications.commands`)。 ## バックアップと移行 以下でバックアップをダウンロードします: * `https:///setup/export` これにより、設定やメモリを失うことなく別のホストに移行できるように、OpenClaw の状態 + ワークスペースがエクスポートされます。 # Render にデプロイ Source: https://openclawdoc.org/install/render Render Blueprint を使って OpenClaw のインフラを宣言的に構築し、永続ディスク付きで運用する手順です。 Infrastructure as Code を使用して OpenClaw を Render にデプロイします。同梱の `render.yaml` Blueprint は、サービス、ディスク、環境変数など、スタック全体を宣言的に定義するため、ワンクリックでデプロイでき、コードと一緒にインフラストラクチャをバージョン管理できます。 ## 前提条件 * [Render アカウント](https://render.com) (無料枠あり) * お好みの[モデルプロバイダ](/providers)の API キー ## Render Blueprint でデプロイ [Render にデプロイ](https://render.com/deploy?repo=https://github.com/openclaw/openclaw) このリンクをクリックすると: 1. このリポジトリのルートにある `render.yaml` Blueprint から新しい Render サービスが作成されます。 2. `SETUP_PASSWORD` を設定するように求められます。 3. Docker イメージをビルドしてデプロイします。 デプロイされると、サービスの URL は `https://.onrender.com` のパターンに従います。 ## Blueprint について理解する Render Blueprints は、インフラストラクチャを定義する YAML ファイルです。このリポジトリの `render.yaml` は、OpenClaw を実行するために必要なすべてを設定します: ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} services: - type: web name: openclaw runtime: docker plan: starter healthCheckPath: /health envVars: - key: PORT value: "8080" - key: SETUP_PASSWORD sync: false # deploy 時にプロンプトを表示 - key: OPENCLAW_STATE_DIR value: /data/.openclaw - key: OPENCLAW_WORKSPACE_DIR value: /data/workspace - key: OPENCLAW_GATEWAY_TOKEN generateValue: true # 安全なトークンを自動生成 disk: name: openclaw-data mountPath: /data sizeGB: 1 ``` 使用されている主な Blueprint の機能: | 機能 | 目的 | | --------------------- | ------------------------------------- | | `runtime: docker` | リポジトリの Dockerfile からビルド | | `healthCheckPath` | Render は `/health` を監視し、異常なインスタンスを再起動 | | `sync: false` | デプロイ中に値 (シークレット) の入力を求める | | `generateValue: true` | 暗号化された安全な値を自動生成 | | `disk` | 再デプロイ後も残る永続ストレージ | ## プランの選択 | プラン | スピンダウン | ディスク | 最適な用途 | | --------- | ---------- | ---- | ----------- | | Free | 15分間のアイドル後 | 利用不可 | テスト、デモ | | Starter | なし | 1GB+ | 個人利用、小規模チーム | | Standard+ | なし | 1GB+ | 本番環境、複数チャネル | Blueprint のデフォルトは `starter` です。無料枠を使用するには、フォークした `render.yaml` の `plan: free` を変更します (ただし、永続ディスクがないため、デプロイのたびに設定がリセットされることに注意してください)。 ## デプロイ後 ### セットアップウィザードの完了 1. `https://.onrender.com/setup` に移動します 2. `SETUP_PASSWORD` を入力します 3. モデルプロバイダを選択し、API キーを貼り付けます 4. (オプション) メッセージングチャネル (Telegram、Discord、Slack) を設定します 5. **Run setup** をクリックします ### Control UI へのアクセス Web ダッシュボードは `https://.onrender.com/openclaw` で利用できます。 ## Render Dashboard の機能 ### ログ **Dashboard → your service → Logs** でリアルタイムログを表示します。以下でフィルタリングできます: * Build logs (Docker イメージの作成) * Deploy logs (サービスの起動) * Runtime logs (アプリケーションの出力) ### シェルアクセス デバッグを行うには、**Dashboard → your service → Shell** からシェルセッションを開きます。永続ディスクは `/data` にマウントされています。 ### 環境変数 **Dashboard → your service → Environment** で変数を変更します。変更すると、自動再デプロイがトリガーされます。 ### 自動デプロイ 元の OpenClaw リポジトリを使用している場合、Render は OpenClaw を自動デプロイしません。更新するには、ダッシュボードから手動で Blueprint 同期を実行します。 ## カスタムドメイン 1. **Dashboard → your service → Settings → Custom Domains** に移動します 2. ドメインを追加します 3. 指示に従って DNS を構成します (`*.onrender.com` への CNAME) 4. Render は TLS 証明書を自動的にプロビジョニングします ## スケーリング Render は、水平および垂直スケーリングをサポートしています: * **垂直**: プランを変更して、より多くの CPU/RAM を取得します * **水平**: インスタンス数を増やします (Standard プラン以上) OpenClaw の場合、通常は垂直スケーリングで十分です。水平スケーリングには、スティッキーセッションまたは外部状態管理が必要です。 ## バックアップと移行 いつでも設定とワークスペースをエクスポートできます: ``` https://.onrender.com/setup/export ``` これにより、任意の OpenClaw ホストで復元できるポータブルバックアップがダウンロードされます。 ## トラブルシューティング ### サービスが開始しない Render Dashboard のデプロイログを確認してください。一般的な問題: * `SETUP_PASSWORD` の欠落 — Blueprint はこれの入力を求めますが、設定されていることを確認してください * ポートの不一致 — `PORT=8080` が Dockerfile の公開ポートと一致していることを確認してください ### コールドスタートが遅い (無料枠) 無料枠のサービスは、15分間操作がないとスピンダウンします。スピンダウン後の最初の要求は、コンテナの起動中に数秒かかります。常時オンにするには、Starter プランにアップグレードしてください。 ### 再デプロイ後のデータ損失 これは無料枠 (永続ディスクなし) で発生します。有料プランにアップグレードするか、`/setup/export` 経由で定期的に設定をエクスポートしてください。 ### ヘルスチェックの失敗 Render は、`/health` から 30 秒以内に 200 応答を期待します。ビルドは成功してもデプロイが失敗する場合、サービスの起動に時間がかかりすぎている可能性があります。以下を確認してください: * ビルドログにエラーがないか * コンテナが `docker build && docker run` でローカルに実行されるかどうか # アンインストール Source: https://openclawdoc.org/install/uninstall CLI、サービス、状態ファイル、ワークスペースを含めて OpenClaw を安全に削除する方法を説明します。 方法は 2 通りあります。 * `openclaw` がまだ入っている場合の **簡単な方法** * CLI は消えているがサービスだけ残っている場合の **手動サービス削除** ## 簡単な方法（CLI がインストールされている場合） 推奨: 組み込みのアンインストーラーを使います。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw uninstall ``` 非対話型（自動化 / npx）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw uninstall --all --yes --non-interactive npx -y openclaw uninstall --all --yes --non-interactive ``` 手動で行う場合も、結果は同じです。 1. Gateway サービスを停止します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway stop ``` 2. Gateway サービス（launchd/systemd/schtasks）をアンインストールします： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway uninstall ``` 3. 状態（state）と設定を削除します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}" ``` `OPENCLAW_CONFIG_PATH` を状態ディレクトリ以外のカスタムの場所に設定している場合は、そのファイルも削除してください。 4. ワークスペースを削除します（オプション。エージェントのファイルを削除します）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} rm -rf ~/.openclaw/workspace ``` 5. CLI のインストールを削除します（使用したものを選んでください）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm rm -g openclaw pnpm remove -g openclaw bun remove -g openclaw ``` 6. macOS アプリをインストールした場合は、以下を削除します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} rm -rf /Applications/OpenClaw.app ``` 注意： * プロファイル（`--profile` / `OPENCLAW_PROFILE`）を使用していた場合は、各状態ディレクトリ（デフォルトは `~/.openclaw-`）に対して手順 3 を繰り返してください。 * リモートモードの場合、状態ディレクトリは **Gateway ホスト** 上にあるため、そこでも手順 1〜4 を実行してください。 ## 手動でのサービス削除（CLI がインストールされていない場合） Gateway サービスは実行され続けているが `openclaw` コマンドがない場合に使用します。 ### macOS (launchd) デフォルトのラベルは `ai.openclaw.gateway` です（または `ai.openclaw.`。レガシーな `com.openclaw.*` が残っている場合もあります）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} launchctl bootout gui/$UID/ai.openclaw.gateway rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist ``` プロファイルを使用していた場合は、ラベルと plist 名を `ai.openclaw.` に置き換えてください。古い `com.openclaw.*` の plist があれば、それも削除してください。 ### Linux (systemd ユーザーユニット) デフォルトのユニット名は `openclaw-gateway.service` です（または `openclaw-gateway-.service`）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} systemctl --user disable --now openclaw-gateway.service rm -f ~/.config/systemd/user/openclaw-gateway.service systemctl --user daemon-reload ``` ### Windows (タスク スケジューラ) デフォルトのタスク名は `OpenClaw Gateway` です（または `OpenClaw Gateway ()`）。 タスクスクリプトは状態ディレクトリの下にあります。 ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} schtasks /Delete /F /TN "OpenClaw Gateway" Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd" ``` プロファイルを使用していた場合は、一致するタスク名と `~\.openclaw-\gateway.cmd` を削除してください。 ## 通常のインストール vs ソースチェックアウト ### 通常のインストール (install.sh / npm / pnpm / bun) `https://openclaw.ai/install.sh` または `install.ps1` を使用した場合、CLI は `npm install -g openclaw@latest` でインストールされています。 `npm rm -g openclaw` で削除してください（他の方法でインストールした場合は、`pnpm remove -g` または `bun remove -g` を使用してください）。 ### ソースチェックアウト (git clone) リポジトリのチェックアウト（`git clone` + `openclaw ...` / `bun run openclaw ...`）から実行している場合： 1. リポジトリを削除する **前** に、Gateway サービスをアンインストールしてください（上記の「簡単な方法」または「手動でのサービス削除」を使用）。 2. リポジトリディレクトリを削除します。 3. 上記のように状態とワークスペースを削除します。 # アップデート Source: https://openclawdoc.org/install/updating アップデート時の確認項目、再起動、ロールバック方針を含めて OpenClaw を安全に更新する方法をまとめます。 OpenClaw は急速に進化しています（「1.0」以前の状態です）。アップデートはインフラのデプロイのように扱ってください：アップデート → チェックの実行 → 再起動（または再起動を伴う `openclaw update` を使用）→ 検証。 ## 推奨：ウェブサイトのインストーラーを再実行する（インプレースアップグレード） **推奨される** アップデートパスは、ウェブサイトからインストーラーを再実行することです。既存のインストールを検出し、その場でアップグレードし、必要に応じて `openclaw doctor` を実行します。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL https://openclaw.ai/install.sh | bash ``` 注意： * オンボーディングウィザードを再度実行したくない場合は、`--no-onboard` を追加してください。 * **ソースインストール** の場合は、以下を使用します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard ``` インストーラーは、リポジトリがクリーンな場合に**のみ** `git pull --rebase` を実行します。 * **グローバルインストール** の場合、スクリプトは内部で `npm install -g openclaw@latest` を使用します。 * レガシーに関する注意：`clawdbot` は互換性のためのシム（shim）として引き続き利用可能です。 ## アップデートの前に * インストール方法を確認してください：**グローバル** (npm/pnpm) か **ソースから** (git clone) か。 * ゲートウェイの実行方法を確認してください：**フォアグラウンドのターミナル** か **管理されたサービス** (launchd/systemd) か。 * 現在の設定のスナップショット（バックアップ）を取ってください： * 構成：`~/.openclaw/openclaw.json` * 認証情報：`~/.openclaw/credentials/` * ワークスペース：`~/.openclaw/workspace` ## アップデート（グローバルインストール） グローバルインストール（いずれかを選択）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm i -g openclaw@latest ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm add -g openclaw@latest ``` ゲートウェイの実行環境として Bun は推奨しません（WhatsApp/Telegram のバグのため）。 アップデートチャンネルを切り替えるには（git または npm インストール）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw update --channel beta openclaw update --channel dev openclaw update --channel stable ``` 一度限りのインストールタグ/バージョンを指定するには、`--tag ` を使用してください。 チャンネルの意味とリリースノートについては、[開発チャンネル](/install/development-channels) を参照してください。 注意：npm インストールの場合、ゲートウェイは起動時にアップデートのヒントをログに記録します（現在のチャンネルタグを確認します）。`update.checkOnStart: false` で無効化できます。 ### コア自動アップデーター（オプション） 自動アップデーターは**デフォルトでオフ**になっており、コアゲートウェイの機能です（プラグインではありません）。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "update": { "channel": "stable", "auto": { "enabled": true, "stableDelayHours": 6, "stableJitterHours": 12, "betaCheckIntervalHours": 1 } } } ``` 動作： * `stable`：新しいバージョンがリリースされると、OpenClaw は `stableDelayHours` だけ待機し、その後 `stableJitterHours` 内でインストールごとの決定論的なジッター（ばらつき）を設けて適用します（段階的ロールアウト）。 * `beta`：`betaCheckIntervalHours`（デフォルト：1時間）おきにチェックし、アップデートがあれば適用します。 * `dev`：自動適用は行われません。手動で `openclaw update` を使用してください。 自動化を有効にする前に、`openclaw update --dry-run` を使用してアップデート内容をプレビューしてください。 その後： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw doctor openclaw gateway restart openclaw health ``` 注意： * ゲートウェイをサービスとして実行している場合は、PID を kill するよりも `openclaw gateway restart` を推奨します。 * 特定のバージョンに固定している場合は、下記の「ロールバック / バージョン固定」を参照してください。 ## アップデート (`openclaw update`) **ソースインストール**（git チェックアウト）の場合は、以下を推奨します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw update ``` これは安全性を考慮したアップデートフローを実行します： * クリーンなワークツリーが必要です。 * 選択されたチャンネル（タグまたはブランチ）に切り替えます。 * 設定されたアップストリーム（dev チャンネル）に対して fetch + rebase を行います。 * 依存関係のインストール、ビルド、コントロール UI のビルドを実行し、`openclaw doctor` を実行します。 * デフォルトでゲートウェイを再起動します（スキップするには `--no-restart` を使用）。 **npm/pnpm** 経由でインストールした場合（git メタデータがない場合）、`openclaw update` はパッケージマネージャーを介してアップデートを試みます。インストールを検出できない場合は、代わりに上記の「アップデート（グローバルインストール）」を使用してください。 ## アップデート（コントロール UI / RPC） コントロール UI には「**Update & Restart**」（RPC: `update.run`）があります。これは： 1. `openclaw update` と同じソースアップデートフローを実行します（git チェックアウトのみ）。 2. 再起動の目印（センチネル）を構造化されたレポート（stdout/stderr の末尾）と共に書き込みます。 3. ゲートウェイを再起動し、最後にアクティブだったセッションにレポートと共に通知を送ります。 rebase に失敗した場合、ゲートウェイはアップデートを適用せずに中断し、再起動します。 ## アップデート（ソースから） リポジトリのチェックアウトディレクトリから： 推奨： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw update ``` 手動（ほぼ同等）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} git pull pnpm install pnpm build pnpm ui:build # 初回実行時に UI の依存関係を自動インストール openclaw doctor openclaw health ``` 注意： * パッケージ化された `openclaw` バイナリ（[`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)）を実行する場合や、Node で `dist/` を実行する場合は `pnpm build` が重要です。 * グローバルインストールなしでリポジトリのチェックアウトから実行する場合は、CLI コマンドに `pnpm openclaw ...` を使用してください。 * TypeScript から直接実行する場合（`pnpm openclaw ...`）、再ビルドは通常不要ですが、**設定の移行は依然として適用される**ため、doctor を実行してください。 * グローバルインストールと git インストールの切り替えは簡単です：もう一方の形式をインストールし、`openclaw doctor` を実行すれば、Gateway サービスののエントリポイントが現在のインストールに書き換えられます。 ## 常に実行：`openclaw doctor` Doctor は「安全なアップデート」のためのコマンドです。意図的に退屈な内容（修復 + 移行 + 警告）になっています。 注意：**ソースインストール**（git チェックアウト）の場合、`openclaw doctor` は最初に `openclaw update` を実行することを提案します。 主な実行内容： * 非推奨の設定キー / レガシーな設定ファイルの場所を移行します。 * DM ポリシーを監査し、リスクのある「open」設定に警告を出します。 * Gateway のヘルスチェックを行い、再起動を提案できます。 * 古い Gateway サービス（launchd/systemd、レガシーな schtasks）を検出し、現在の OpenClaw サービスに移行します。 * Linux で、systemd ユーザーのリンガリング（ログアウト後も Gateway が存続すること）を確保します。 詳細：[Doctor](/gateway/doctor) ## Gateway の起動 / 停止 / 再起動 CLI（OS に依存せず動作）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway status openclaw gateway stop openclaw gateway restart openclaw gateway --port 18789 openclaw logs --follow ``` サービス管理下にある場合： * macOS launchd（アプリに同梱された LaunchAgent）：`launchctl kickstart -k gui/$UID/ai.openclaw.gateway`（`ai.openclaw.` を使用。レガシーな `com.openclaw.*` も引き続き動作します） * Linux systemd ユーザーサービス：`systemctl --user restart openclaw-gateway[-].service` * Windows (WSL2)：`systemctl --user restart openclaw-gateway[-].service` * `launchctl`/`systemctl` はサービスがインストールされている場合にのみ動作します。そうでない場合は `openclaw gateway install` を実行してください。 ランブックと正確なサービスラベル：[Gateway ランブック](/gateway) ## ロールバック / バージョン固定（何かが壊れた場合） ### バージョン固定（グローバルインストール） 既知の正常なバージョンをインストールします（`` を最後に動作していたものに置き換えてください）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm i -g openclaw@ ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm add -g openclaw@ ``` ヒント：現在公開されているバージョンを確認するには、`npm view openclaw version` を実行してください。 その後、再起動して doctor を再実行します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw doctor openclaw gateway restart ``` ### 日付による固定（ソースインストール） 特定の日付のコミットを選択します（例：「2026-01-01 時点の main の状態」）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} git fetch origin git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)" ``` その後、依存関係を再インストールして再起動します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm install pnpm build openclaw gateway restart ``` 後で最新の状態に戻したい場合： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} git checkout main git pull ``` ## 困ったときは * もう一度 `openclaw doctor` を実行し、出力を注意深く読んでください（解決策が示されていることが多いです）。 * チェック：[トラブルシューティング](/gateway/troubleshooting) * Discord で質問する：[https://discord.gg/clawd](https://discord.gg/clawd) # Perplexity Search Source: https://openclawdoc.org/perplexity Perplexity Search API を web_search プロバイダーとして使うための設定方法、返却結果、接続要件を説明します。 OpenClaw は `web_search` provider として Perplexity Search API をサポートしています。返されるのは `title`、`url`、`snippet` を含む構造化結果です。 互換性のため、OpenClaw は legacy の Perplexity Sonar / OpenRouter 構成もサポートしています。`OPENROUTER_API_KEY` を使う場合、`tools.web.search.perplexity.apiKey` に `sk-or-...` 形式の key を設定した場合、または `tools.web.search.perplexity.baseUrl` / `model` を設定した場合、provider は chat-completions 経路へ切り替わり、構造化された Search API 結果ではなく、引用付きの AI 合成回答を返します。 ## Perplexity API key の取得 1. [https://www.perplexity.ai/settings/api](https://www.perplexity.ai/settings/api) で Perplexity アカウントを作成する 2. dashboard で API key を生成する 3. key を config に保存するか、Gateway 環境で `PERPLEXITY_API_KEY` を設定する ## OpenRouter 互換 すでに Perplexity Sonar 用に OpenRouter を使っている場合は、`provider: "perplexity"` を維持したまま、Gateway 環境で `OPENROUTER_API_KEY` を設定するか、`tools.web.search.perplexity.apiKey` に `sk-or-...` key を保存してください。 任意の legacy 制御: * `tools.web.search.perplexity.baseUrl` * `tools.web.search.perplexity.model` ## 設定例 ### ネイティブ Perplexity Search API ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { tools: { web: { search: { provider: "perplexity", perplexity: { apiKey: "pplx-...", }, }, }, }, } ``` ### OpenRouter / Sonar 互換 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { tools: { web: { search: { provider: "perplexity", perplexity: { apiKey: "", baseUrl: "https://openrouter.ai/api/v1", model: "perplexity/sonar-pro", }, }, }, }, } ``` ## key の設定場所 **config 経由:** `openclaw configure --section web` を実行します。key は `~/.openclaw/openclaw.json` の `tools.web.search.perplexity.apiKey` に保存されます。 **環境変数経由:** Gateway process 環境で `PERPLEXITY_API_KEY` または `OPENROUTER_API_KEY` を設定します。Gateway を常駐インストールしている場合は `~/.openclaw/.env`（または service 環境）に配置してください。詳細は [Env vars](/help/faq#how-does-openclaw-load-environment-variables) を参照してください。 ## ツールパラメータ 以下のパラメータは、ネイティブ Perplexity Search API 経路に適用されます。 | Parameter | Description | | --------------------- | ---------------------------------------- | | `query` | 検索クエリ（必須） | | `count` | 返す結果数（1-10、デフォルト: 5） | | `country` | 2 文字の ISO 国コード（例: `"US"`、`"DE"`） | | `language` | ISO 639-1 言語コード（例: `"en"`、`"de"`、`"fr"`） | | `freshness` | 時間フィルタ: `day`（24h）、`week`、`month`、`year` | | `date_after` | この日付以降に公開された結果のみ（YYYY-MM-DD） | | `date_before` | この日付以前に公開された結果のみ（YYYY-MM-DD） | | `domain_filter` | ドメイン allowlist / denylist 配列（最大 20 件） | | `max_tokens` | 総コンテンツ予算（デフォルト: 25000、最大: 1000000） | | `max_tokens_per_page` | ページ単位のトークン上限（デフォルト: 2048） | legacy の Sonar / OpenRouter 互換経路では、`query` と `freshness` だけがサポート対象です。`country`、`language`、`date_after`、`date_before`、`domain_filter`、`max_tokens`、`max_tokens_per_page` など Search API 専用の filter は明示的な error を返します。 **例:** ```javascript theme={"theme":{"light":"min-light","dark":"min-dark"}} // 国と言語を指定した検索 await web_search({ query: "renewable energy", country: "DE", language: "de", }); // 最近1週間の結果 await web_search({ query: "AI news", freshness: "week", }); // 日付範囲検索 await web_search({ query: "AI developments", date_after: "2024-01-01", date_before: "2024-06-30", }); // ドメインフィルタ（allowlist） await web_search({ query: "climate research", domain_filter: ["nature.com", "science.org", ".edu"], }); // ドメインフィルタ（denylist: 接頭辞に - を付ける） await web_search({ query: "product reviews", domain_filter: ["-reddit.com", "-pinterest.com"], }); // より多くのコンテンツを抽出 await web_search({ query: "detailed AI research", max_tokens: 50000, max_tokens_per_page: 4096, }); ``` ### domain filter のルール * 1 リクエストあたり最大 20 ドメイン * 同じリクエスト内で allowlist と denylist を混在させることはできない * denylist entry には `-` 接頭辞を付ける（例: `["-reddit.com"]`） ## 注意点 * Perplexity Search API は構造化された Web 検索結果（`title`、`url`、`snippet`）を返します * OpenRouter または明示的な `baseUrl` / `model` を設定すると、互換性維持のため Perplexity は Sonar chat completions 経路へ切り替わります * 結果はデフォルトで 15 分間キャッシュされます（`cacheTtlMinutes` で変更可能） 完全な `web_search` 設定については [Web tools](/tools/web) を参照してください。詳細は [Perplexity Search API docs](https://docs.perplexity.ai/docs/search/quickstart) を参照してください。 # Pi 統合アーキテクチャ Source: https://openclawdoc.org/pi pi-coding-agent と関連パッケージを OpenClaw に組み込み、セッションとエージェント機能を実現する設計を解説します。 このドキュメントでは、OpenClaw が [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) と、その関連パッケージである `pi-ai`、`pi-agent-core`、`pi-tui` をどのように統合し、AI エージェント機能を実装しているかを説明します。 ## 概要 OpenClaw は pi SDK を使って、AI コーディングエージェントをメッセージング Gateway アーキテクチャへ組み込みます。pi をサブプロセスとして起動したり、RPC モードを使ったりするのではなく、`createAgentSession()` を通じて pi の `AgentSession` を直接 import し、インスタンス化します。この組み込み方式には、次の利点があります。 * セッションのライフサイクルとイベント処理を完全に制御できる * カスタムツールを注入できる（メッセージング、サンドボックス、チャンネル固有のアクションなど） * チャンネルやコンテキストごとにシステムプロンプトをカスタマイズできる * 分岐や compaction を含むセッション永続化をサポートできる * フェイルオーバー付きのマルチアカウント認証プロファイルローテーションを使える * プロバイダーに依存しないモデル切り替えができる ## パッケージ依存関係 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "@mariozechner/pi-agent-core": "0.49.3", "@mariozechner/pi-ai": "0.49.3", "@mariozechner/pi-coding-agent": "0.49.3", "@mariozechner/pi-tui": "0.49.3" } ``` | Package | Purpose | | ----------------- | ------------------------------------------------------------------------------------- | | `pi-ai` | コア LLM 抽象化: `Model`、`streamSimple`、メッセージ型、プロバイダー API | | `pi-agent-core` | エージェントループ、ツール実行、`AgentMessage` 型 | | `pi-coding-agent` | 高レベル SDK: `createAgentSession`、`SessionManager`、`AuthStorage`、`ModelRegistry`、組み込みツール | | `pi-tui` | ターミナル UI コンポーネント（OpenClaw のローカル TUI モードで使用） | ## ファイル構成 ``` src/agents/ ├── pi-embedded-runner.ts # pi-embedded-runner/ から再エクスポート ├── pi-embedded-runner/ │ ├── run.ts # メインエントリ: runEmbeddedPiAgent() │ ├── run/ │ │ ├── attempt.ts # セッションセットアップを含む単一試行のロジック │ │ ├── params.ts # RunEmbeddedPiAgentParams 型 │ │ ├── payloads.ts # 実行結果から応答ペイロードを構築 │ │ ├── images.ts # Vision モデル向け画像注入 │ │ └── types.ts # EmbeddedRunAttemptResult │ ├── abort.ts # 中断エラーの検出 │ ├── cache-ttl.ts # コンテキスト刈り込み用の Cache TTL 追跡 │ ├── compact.ts # 手動/自動 compaction ロジック │ ├── extensions.ts # 組み込み実行向けの pi 拡張を読み込む │ ├── extra-params.ts # プロバイダー固有の stream パラメーター │ ├── google.ts # Google/Gemini のターン順序修正 │ ├── history.ts # 履歴制限（DM 対グループ） │ ├── lanes.ts # セッション/グローバルのコマンドレーン │ ├── logger.ts # サブシステムロガー │ ├── model.ts # ModelRegistry 経由のモデル解決 │ ├── runs.ts # アクティブ実行の追跡、中断、キュー │ ├── sandbox-info.ts # システムプロンプト向けのサンドボックス情報 │ ├── session-manager-cache.ts # SessionManager インスタンスのキャッシュ │ ├── session-manager-init.ts # セッションファイルの初期化 │ ├── system-prompt.ts # システムプロンプトビルダー │ ├── tool-split.ts # ツールを builtIn と custom に分割 │ ├── types.ts # EmbeddedPiAgentMeta、EmbeddedPiRunResult │ └── utils.ts # ThinkLevel マッピング、エラー説明 ├── pi-embedded-subscribe.ts # セッションイベントの購読/ディスパッチ ├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams ├── pi-embedded-subscribe.handlers.ts # イベントハンドラーファクトリー ├── pi-embedded-subscribe.handlers.lifecycle.ts ├── pi-embedded-subscribe.handlers.types.ts ├── pi-embedded-block-chunker.ts # ストリーミングブロック返信のチャンク化 ├── pi-embedded-messaging.ts # メッセージングツールの送信追跡 ├── pi-embedded-helpers.ts # エラー分類、ターン検証 ├── pi-embedded-helpers/ # ヘルパーモジュール ├── pi-embedded-utils.ts # フォーマットユーティリティ ├── pi-tools.ts # createOpenClawCodingTools() ├── pi-tools.abort.ts # ツール向け AbortSignal ラップ ├── pi-tools.policy.ts # ツール allowlist/denylist ポリシー ├── pi-tools.read.ts # read ツールのカスタマイズ ├── pi-tools.schema.ts # ツールスキーマの正規化 ├── pi-tools.types.ts # AnyAgentTool 型エイリアス ├── pi-tool-definition-adapter.ts # AgentTool -> ToolDefinition アダプター ├── pi-settings.ts # 設定のオーバーライド ├── pi-extensions/ # カスタム pi 拡張 │ ├── compaction-safeguard.ts # 保護拡張 │ ├── compaction-safeguard-runtime.ts │ ├── context-pruning.ts # Cache-TTL ベースのコンテキスト刈り込み拡張 │ └── context-pruning/ ├── model-auth.ts # 認証プロファイル解決 ├── auth-profiles.ts # プロファイルストア、クールダウン、フェイルオーバー ├── model-selection.ts # デフォルトモデル解決 ├── models-config.ts # models.json の生成 ├── model-catalog.ts # モデルカタログキャッシュ ├── context-window-guard.ts # コンテキストウィンドウ検証 ├── failover-error.ts # FailoverError クラス ├── defaults.ts # DEFAULT_PROVIDER、DEFAULT_MODEL ├── system-prompt.ts # buildAgentSystemPrompt() ├── system-prompt-params.ts # システムプロンプトパラメーターの解決 ├── system-prompt-report.ts # デバッグレポートの生成 ├── tool-summaries.ts # ツール説明の要約 ├── tool-policy.ts # ツールポリシー解決 ├── transcript-policy.ts # Transcript 検証ポリシー ├── skills.ts # Skills のスナップショット/プロンプト構築 ├── skills/ # Skills サブシステム ├── sandbox.ts # サンドボックスコンテキスト解決 ├── sandbox/ # サンドボックスサブシステム ├── channel-tools.ts # チャンネル固有ツールの注入 ├── openclaw-tools.ts # OpenClaw 固有ツール ├── bash-tools.ts # exec/process ツール ├── apply-patch.ts # apply_patch ツール（OpenAI） ├── tools/ # 個別ツール実装 │ ├── browser-tool.ts │ ├── canvas-tool.ts │ ├── cron-tool.ts │ ├── discord-actions*.ts │ ├── gateway-tool.ts │ ├── image-tool.ts │ ├── message-tool.ts │ ├── nodes-tool.ts │ ├── session*.ts │ ├── slack-actions.ts │ ├── telegram-actions.ts │ ├── web-*.ts │ └── whatsapp-actions.ts └── ... ``` ## コア統合フロー ### 1. 組み込みエージェントの実行 メインエントリポイントは `pi-embedded-runner/run.ts` の `runEmbeddedPiAgent()` です。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} import { runEmbeddedPiAgent } from "./agents/pi-embedded-runner.js"; const result = await runEmbeddedPiAgent({ sessionId: "user-123", sessionKey: "main:whatsapp:+1234567890", sessionFile: "/path/to/session.jsonl", workspaceDir: "/path/to/workspace", config: openclawConfig, prompt: "Hello, how are you?", provider: "anthropic", model: "claude-sonnet-4-20250514", timeoutMs: 120_000, runId: "run-abc", onBlockReply: async (payload) => { await sendToChannel(payload.text, payload.mediaUrls); }, }); ``` ### 2. セッション作成 `runEmbeddedAttempt()`（`runEmbeddedPiAgent()` から呼び出される）の内部では、pi SDK を使用します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent"; const resourceLoader = new DefaultResourceLoader({ cwd: resolvedWorkspace, agentDir, settingsManager, additionalExtensionPaths, }); await resourceLoader.reload(); const { session } = await createAgentSession({ cwd: resolvedWorkspace, agentDir, authStorage: params.authStorage, modelRegistry: params.modelRegistry, model: params.model, thinkingLevel: mapThinkingLevel(params.thinkLevel), tools: builtInTools, customTools: allCustomTools, sessionManager, settingsManager, resourceLoader, }); applySystemPromptOverrideToSession(session, systemPromptOverride); ``` ### 3. イベント購読 `subscribeEmbeddedPiSession()` は pi の `AgentSession` イベントを購読します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const subscription = subscribeEmbeddedPiSession({ session: activeSession, runId: params.runId, verboseLevel: params.verboseLevel, reasoningMode: params.reasoningLevel, toolResultFormat: params.toolResultFormat, onToolResult: params.onToolResult, onReasoningStream: params.onReasoningStream, onBlockReply: params.onBlockReply, onPartialReply: params.onPartialReply, onAgentEvent: params.onAgentEvent, }); ``` 主に次のイベントを処理します。 * `message_start` / `message_end` / `message_update`（ストリーミング中のテキスト/思考） * `tool_execution_start` / `tool_execution_update` / `tool_execution_end` * `turn_start` / `turn_end` * `agent_start` / `agent_end` * `auto_compaction_start` / `auto_compaction_end` ### 4. プロンプト送信 セットアップ後、セッションに対してプロンプトを送ります。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} await session.prompt(effectivePrompt, { images: imageResult.images }); ``` SDK 側で、LLM への送信、tool call の実行、応答のストリーミングを含むエージェントループ全体を処理します。 画像注入はプロンプトローカルです。OpenClaw は現在のプロンプトから画像参照を読み取り、そのターンに限って `images` 経由で渡します。過去の履歴ターンを再走査して、画像ペイロードを再注入することはありません。 ## ツールアーキテクチャ ### ツールパイプライン 1. **ベースツール**: pi の `codingTools`（read、bash、edit、write） 2. **カスタム置き換え**: OpenClaw は bash を `exec` / `process` に置き換え、sandbox 向けに read / edit / write をカスタマイズ 3. **OpenClaw ツール**: messaging、browser、canvas、sessions、cron、gateway など 4. **チャンネルツール**: Discord / Telegram / Slack / WhatsApp 固有のアクションツール 5. **ポリシーフィルタリング**: profile、provider、agent、group、sandbox のポリシーでツールを絞り込む 6. **スキーマ正規化**: Gemini / OpenAI の実装上の癖に合わせてスキーマを調整 7. **AbortSignal ラップ**: 中断シグナルを尊重するようにツールをラップ ### ツール定義アダプター pi-agent-core の `AgentTool` は、pi-coding-agent の `ToolDefinition` とは異なる `execute` シグネチャを持ちます。`pi-tool-definition-adapter.ts` の adapter が、その差分を吸収します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { return tools.map((tool) => ({ name: tool.name, label: tool.label ?? name, description: tool.description ?? "", parameters: tool.parameters, execute: async (toolCallId, params, onUpdate, _ctx, signal) => { // pi-coding-agent signature differs from pi-agent-core return await tool.execute(toolCallId, params, signal, onUpdate); }, })); } ``` ### ツール分割戦略 `splitSdkTools()` はすべてのツールを `customTools` 経由で渡します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) { return { builtInTools: [], // Empty. We override everything customTools: toToolDefinitions(options.tools), }; } ``` これにより、OpenClaw の policy filtering、サンドボックス統合、拡張 toolset を provider ごとにぶらさず適用できます。 ## システムプロンプトの構築 システムプロンプトは `buildAgentSystemPrompt()`（`system-prompt.ts`）で構築されます。Tooling、Tool Call Style、安全ガードレール、OpenClaw CLI リファレンス、Skills、Docs、Workspace、Sandbox、Messaging、Reply Tags、Voice、Silent Replies、Heartbeats、ランタイムメタデータに加え、有効時には Memory と Reactions、さらに任意の context file や追加 system prompt も含めて、完全なプロンプトを組み立てます。subagent 用の minimal prompt mode では、各セクションを短縮します。 プロンプトは、セッション作成後に `applySystemPromptOverrideToSession()` を通じて適用されます。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const systemPromptOverride = createSystemPromptOverride(appendPrompt); applySystemPromptOverrideToSession(session, systemPromptOverride); ``` ## セッション管理 ### セッションファイル セッションは、ツリー構造（`id` / `parentId` のリンク）を持つ JSONL ファイルです。pi の `SessionManager` が永続化を処理します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const sessionManager = SessionManager.open(params.sessionFile); ``` OpenClaw はこれを `guardSessionManager()` でラップし、tool result の取り扱いを安全側に寄せています。 ### セッションキャッシュ `session-manager-cache.ts` は `SessionManager` instance をキャッシュし、同じファイルの再解析を避けます。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} await prewarmSessionFile(params.sessionFile); sessionManager = SessionManager.open(params.sessionFile); trackSessionManagerAccess(params.sessionFile); ``` ### 履歴制限 `limitHistoryTurns()` は、チャンネル種別（DM 対グループ）に応じて会話履歴を切り詰めます。 ### Compaction 自動 compaction はコンテキストオーバーフロー時に発動します。`compactEmbeddedPiSessionDirect()` が手動 compaction を処理します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const compactResult = await compactEmbeddedPiSessionDirect({ sessionId, sessionFile, provider, model, ... }); ``` ## 認証とモデル解決 ### 認証プロファイル OpenClaw は、provider ごとに複数の API key を持てる認証 profile store を維持します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false }); const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile }); ``` profile は、cooldown を追跡しながら失敗時にローテーションされます。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir }); const rotated = await advanceAuthProfile(); ``` ### モデル解決 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} import { resolveModel } from "./pi-embedded-runner/model.js"; const { model, error, authStorage, modelRegistry } = resolveModel( provider, modelId, agentDir, config, ); // Uses pi's ModelRegistry and AuthStorage authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); ``` ### フェイルオーバー `FailoverError` は、設定されている場合に model fallback を発動します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} if (fallbackConfigured && isFailoverErrorMessage(errorText)) { throw new FailoverError(errorText, { reason: promptFailoverReason ?? "unknown", provider, model: modelId, profileId, status: resolveFailoverStatus(promptFailoverReason), }); } ``` ## Pi 拡張 OpenClaw は、特化した挙動を実現するためにカスタムの pi extension を読み込みます。 ### Compaction Safeguard `src/agents/pi-extensions/compaction-safeguard.ts` は、適応的な token budget に加えて、tool failure と file operation の要約を含む compaction の guardrail を追加します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} if (resolveCompactionMode(params.cfg) === "safeguard") { setCompactionSafeguardRuntime(params.sessionManager, { maxHistoryShare }); paths.push(resolvePiExtensionPath("compaction-safeguard")); } ``` ### Context Pruning `src/agents/pi-extensions/context-pruning.ts` は、Cache-TTL ベースの context pruning を実装します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { setContextPruningRuntime(params.sessionManager, { settings, contextWindowTokens, isToolPrunable, lastCacheTouchAt, }); paths.push(resolvePiExtensionPath("context-pruning")); } ``` ## ストリーミングとブロック返信 ### ブロックチャンク化 `EmbeddedBlockChunker` は、ストリーミングテキストを個別の返信ブロックへ分割して管理します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null; ``` ### Thinking / Final タグの除去 ストリーミング出力は、`` / `` ブロックを除去し、`` の内容を抽出するよう処理されます。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => { // Strip ... content // If enforceFinalTag, only return ... content }; ``` ### 返信ディレクティブ `[[media:url]]`、`[[voice]]`、`[[reply:id]]` のような返信ディレクティブは、解析されて抽出されます。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk); ``` ## エラー処理 ### エラー分類 `pi-embedded-helpers.ts` は、後続処理を分岐させるために error を分類します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} isContextOverflowError(errorText) // Context too large isCompactionFailureError(errorText) // Compaction failed isAuthAssistantError(lastAssistant) // Auth failure isRateLimitAssistantError(...) // Rate limited isFailoverAssistantError(...) // Should failover classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ... ``` ### Thinking レベルのフォールバック Thinking level がサポートされていない場合は、fallback します。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const fallbackThinking = pickFallbackThinkingLevel({ message: errorText, attempted: attemptedThinking, }); if (fallbackThinking) { thinkLevel = fallbackThinking; continue; } ``` ## サンドボックス統合 サンドボックスモードが有効な場合、tool と path には制約が適用されます。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} const sandbox = await resolveSandboxContext({ config: params.config, sessionKey: sandboxSessionKey, workspaceDir: resolvedWorkspace, }); if (sandboxRoot) { // Use sandboxed read/edit/write tools // Exec runs in container // Browser uses bridge URL } ``` ## プロバイダー別の処理 ### Anthropic * Refusal の magic string 除去 * 連続する role に対するターン検証 * Claude Code のパラメーター互換性 ### Google/Gemini * ターン順序の修正（`applyGoogleTurnOrderingFix`） * ツールスキーマのサニタイズ（`sanitizeToolsForGoogle`） * セッション履歴のサニタイズ（`sanitizeSessionHistory`） ### OpenAI * Codex モデル向けの `apply_patch` ツール * Thinking レベルのダウングレード処理 ## TUI 統合 OpenClaw には、`pi-tui` の component を直接使うローカル TUI mode もあります。 ```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}} // src/tui/tui.ts import { ... } from "@mariozechner/pi-tui"; ``` これにより、pi の native mode に近い対話型 terminal 体験を提供します。 ## Pi CLI との主な違い | Aspect | Pi CLI | OpenClaw Embedded | | --------------- | ----------------------- | ---------------------------------------------------------------------------------------------- | | Invocation | `pi` command / RPC | `createAgentSession()` 経由の SDK | | Tools | Default coding tools | カスタム OpenClaw ツールスイート | | System prompt | AGENTS.md + prompts | チャンネル/コンテキストごとに動的 | | Session storage | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/`（または `$OPENCLAW_STATE_DIR/agents//sessions/`） | | Auth | Single credential | ローテーション付きマルチプロファイル | | Extensions | Loaded from disk | プログラム経由 + ディスクパス | | Event handling | TUI rendering | コールバックベース（onBlockReply など） | ## 今後の検討事項 今後の再設計候補として、次の領域があります。 1. **ツールシグネチャの整合**: 現在は pi-agent-core と pi-coding-agent のシグネチャ差分を吸収している 2. **セッションマネージャーのラップ**: `guardSessionManager` は安全性を高める一方で複雑さも増やす 3. **拡張の読み込み**: pi の `ResourceLoader` をより直接的に使える可能性がある 4. **ストリーミングハンドラーの複雑化**: `subscribeEmbeddedPiSession` が大きくなってきている 5. **プロバイダー固有の癖**: pi 側で吸収できる可能性のあるプロバイダー別コードパスが多い ## テスト Pi 統合のカバレッジは、次の test suite にまたがっています。 * `src/agents/pi-*.test.ts` * `src/agents/pi-auth-json.test.ts` * `src/agents/pi-embedded-*.test.ts` * `src/agents/pi-embedded-helpers*.test.ts` * `src/agents/pi-embedded-runner*.test.ts` * `src/agents/pi-embedded-runner/**/*.test.ts` * `src/agents/pi-embedded-subscribe*.test.ts` * `src/agents/pi-tools*.test.ts` * `src/agents/pi-tool-definition-adapter*.test.ts` * `src/agents/pi-settings.test.ts` * `src/agents/pi-extensions/**/*.test.ts` ライブ/オプトイン: * `src/agents/pi-embedded-runner-extraparams.live.test.ts`（`OPENCLAW_LIVE_TEST=1` を有効化） 現在の実行コマンドについては、[Pi 開発ワークフロー](/pi-dev)を参照してください。 # エージェントブートストラップ Source: https://openclawdoc.org/start/bootstrapping 初回起動時にワークスペースと ID 情報を整えるエージェントブートストラップ処理の流れを説明します。 ブートストラップは、エージェントワークスペースを準備し、ID情報を収集する**初回実行**時の処理です。オンボーディング後、エージェントが初めて起動するときに実行されます。 ## ブートストラップの動作 エージェントの初回実行時、OpenClawはワークスペース(デフォルトは`~/.openclaw/workspace`)をブートストラップします: * `AGENTS.md`、`BOOTSTRAP.md`、`IDENTITY.md`、`USER.md`を生成します。 * 短いQ\&A処理を実行します(一度に1つの質問)。 * IDと設定を`IDENTITY.md`、`USER.md`、`SOUL.md`に書き込みます。 * 完了後に`BOOTSTRAP.md`を削除し、一度だけ実行されるようにします。 ## 実行場所 ブートストラップは常に**Gatewayホスト**上で実行されます。macOSアプリがリモートGatewayに接続している場合、ワークスペースとブートストラップファイルはそのリモートマシン上に存在します。 Gatewayが別のマシン上で実行されている場合、Gatewayホスト上でワークスペースファイルを編集してください(例: `user@gateway-host:~/.openclaw/workspace`)。 ## 関連ドキュメント * macOSアプリのオンボーディング: [オンボーディング](/start/onboarding) * ワークスペースレイアウト: [エージェントワークスペース](/concepts/agent-workspace) # はじめに Source: https://openclawdoc.org/start/getting-started ゼロから OpenClaw を導入し、認証とチャンネル設定を済ませて最初のチャットを始める最短ガイドです。 目標: ゼロから最小限のセットアップで最初の動作するチャットまで到達します。 最速のチャット: Control UIを開きます(チャンネルセットアップは不要)。`openclaw dashboard`を実行してブラウザでチャットするか、 gatewayホストで`http://127.0.0.1:18789/`を開きます。 ドキュメント: [Dashboard](/web/dashboard)と[Control UI](/web/control-ui)。 ## 前提条件 * Node 22以降 不明な場合は`node --version`でNodeのバージョンを確認してください。 ## クイックセットアップ (CLI) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsSL https://openclaw.ai/install.sh | bash ``` Install Script Process ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} iwr -useb https://openclaw.ai/install.ps1 | iex ``` その他のインストール方法と要件: [Install](/install)。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard --install-daemon ``` ウィザードは認証、Gateway設定、およびオプションのチャンネルを構成します。 詳細は[オンボーディングウィザード](/start/wizard)を参照してください。 サービスをインストールした場合、すでに実行されているはずです: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway status ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw dashboard ``` Control UIが読み込まれれば、Gatewayは使用可能です。 ## オプションの確認と追加機能 クイックテストやトラブルシューティングに便利です。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway --port 18789 ``` 構成済みのチャンネルが必要です。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw message send --target +15555550123 --message "Hello from OpenClaw" ``` ## 便利な環境変数 OpenClawをサービスアカウントとして実行する場合や、カスタムの設定/状態の場所を指定したい場合: * `OPENCLAW_HOME`は内部パス解決に使用されるホームディレクトリを設定します。 * `OPENCLAW_STATE_DIR`は状態ディレクトリを上書きします。 * `OPENCLAW_CONFIG_PATH`は設定ファイルのパスを上書きします。 完全な環境変数リファレンス: [環境変数](/help/environment)。 ## さらに深く 完全なCLIウィザードリファレンスと高度なオプション。 macOSアプリの初回実行フロー。 ## 完了後の状態 * 実行中のGateway * 構成済みの認証 * Control UIアクセスまたは接続済みのチャンネル ## 次のステップ * DMの安全性と承認: [ペアリング](/channels/pairing) * さらにチャンネルを接続: [チャンネル](/channels) * 高度なワークフローとソースからのセットアップ: [セットアップ](/start/setup) # オンボーディング (macOS アプリ) Source: https://openclawdoc.org/start/onboarding macOS アプリを中心とした初回オンボーディング手順を説明し、Gateway、認証、ブートストラップまで案内します。 このドキュメントでは、**現在の**初回オンボーディングフローについて説明します。目標はスムーズな「1日目 (day 0)」のエクスペリエンスです。Gateway をどこで実行するかを選択し、認証を接続し、ウィザードを実行して、エージェント自体にブートストラップさせます。 オンボーディングパスの概要については、[オンボーディングの概要](/start/onboarding-overview)を参照してください。 セキュリティトラストモデル: * デフォルトでは、OpenClaw はパーソナルエージェントです。つまり、1つの信頼できるオペレーターの境界内にあります。 * 共有/マルチユーザーのセットアップでは、ロックダウンが必要です (信頼境界を分割し、ツールへのアクセスを最小限に抑え、[セキュリティ](/gateway/security)に従ってください)。 * 現在、ローカルオンボーディングでは新しい設定のデフォルトが `tools.profile: "coding"` になっているため、新規のローカルセットアップでは、無制限の `full` プロファイルを強制することなく、ファイルシステム/ランタイムツールを維持できます。 * フック/Webhook またはその他の信頼できないコンテンツフィードが有効になっている場合は、強力で最新のモデル層を使用し、厳格なツールポリシー/サンドボックス化を維持してください。 **Gateway** はどこで実行されますか？ * **この Mac (ローカルのみ):** オンボーディングで認証を設定し、資格情報をローカルに書き込むことができます。 * **リモート (SSH/Tailnet 経由):** オンボーディングではローカルの認証は**設定しません**。資格情報は Gateway ホスト上に存在する必要があります。 * **後で設定する:** セットアップをスキップし、アプリを未設定のままにします。 **Gateway 認証のヒント:** * 現在のウィザードでは、ループバック用であっても**トークン**が生成されるため、ローカルの WS クライアントは認証する必要があります。 * 認証を無効にすると、任意のローカルプロセスが接続できるようになります。これは完全に信頼できるマシンでのみ使用してください。 * 複数マシンからのアクセスや非ループバックのバインドには、**トークン**を使用してください。 オンボーディングでは、以下に必要な TCC (Transparency, Consent, and Control) 権限を要求します: * オートメーション (AppleScript) * 通知 * アクセシビリティ * 画面収録 * マイク * 音声認識 * カメラ * 位置情報 このステップはオプションです アプリは、ターミナルのワークフローや launchd タスクがすぐに機能するように、npm/pnpm を介してグローバルの `openclaw` CLI をインストールできます。 セットアップ後、アプリは専用のオンボーディングチャットセッションを開き、エージェントが自己紹介を行い、次のステップを案内できるようにします。これにより、初回起動のガイダンスと通常の会話が分離されます。最初のエージェント実行時に Gateway ホストで何が起こるかについては、[ブートストラップ](/start/bootstrapping)を参照してください。 # オンボーディング概要 Source: https://openclawdoc.org/start/onboarding-overview 実行環境や接続方法に応じた OpenClaw のオンボーディング経路を比較し、適切な始め方を案内します。 OpenClawは、Gatewayの実行場所とプロバイダーの設定方法に応じて、複数のオンボーディングパスをサポートしています。 ## オンボーディングパスの選択 * **CLIウィザード** macOS、Linux、Windows（WSL2経由）向け。 * **macOSアプリ** Apple siliconまたはIntel Mac上でのガイド付き初回実行向け。 ## CLIオンボーディングウィザード ターミナルでウィザードを実行します： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard ``` Gateway、ワークスペース、チャンネル、Skillsを完全に制御したい場合は、CLIウィザードを使用してください。ドキュメント： * [オンボーディングウィザード（CLI）](/start/wizard) * [`openclaw onboard`コマンド](/cli/onboard) ## macOSアプリオンボーディング macOS上で完全にガイドされたセットアップが必要な場合は、OpenClawアプリを使用してください。ドキュメント： * [オンボーディング（macOSアプリ）](/start/onboarding) ## カスタムプロバイダー リストにないエンドポイントが必要な場合、標準のOpenAIまたはAnthropic APIを公開するホスト型プロバイダーを含め、CLIウィザードで**カスタムプロバイダー**を選択してください。次の情報を求められます： * OpenAI互換、Anthropic互換、または**不明**（自動検出）を選択。 * ベースURLとAPIキー（プロバイダーが必要とする場合）を入力。 * モデルIDとオプションのエイリアスを提供。 * 複数のカスタムエンドポイントが共存できるようにエンドポイントIDを選択。 詳細な手順については、上記のCLIオンボーディングドキュメントに従ってください。 # パーソナルアシスタントのセットアップ Source: https://openclawdoc.org/start/openclaw OpenClaw を個人用アシスタントとして常時運用するための構成、チャンネル選択、安全上の注意をまとめます。 OpenClaw は、**Pi** エージェントのための WhatsApp + Telegram + Discord + iMessage ゲートウェイです。プラグインで Mattermost を追加できます。このガイドは「パーソナルアシスタント」のセットアップです。1つの専用の WhatsApp 番号が、常時稼働するアシスタントのように振る舞います。 ## ⚠️ 安全第一 あなたはエージェントを以下のことができる位置に置いています： * マシン上でコマンドを実行する（Pi ツールのセットアップに依存） * ワークスペース内のファイルの読み取り/書き込み * WhatsApp/Telegram/Discord/Mattermost (プラグイン) を介したメッセージの送信 保守的に始めてください： * 常に `channels.whatsapp.allowFrom` を設定してください（個人の Mac で世界中からアクセス可能な状態で実行しないでください）。 * アシスタント用に専用の WhatsApp 番号を使用してください。 * 現在、ハートビートはデフォルトで30分ごとに設定されています。セットアップを信頼できるようになるまでは、`agents.defaults.heartbeat.every: "0m"` を設定して無効にしてください。 ## 前提条件 * OpenClaw のインストールとオンボーディングの完了 — まだ行っていない場合は [はじめに](/start/getting-started) を参照してください * アシスタント用の2つ目の電話番号（SIM / eSIM / プリペイド） ## 2台のスマートフォンによるセットアップ (推奨) この構成をお勧めします： ```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}} flowchart TB A["あなたのスマートフォン (個人用)

あなたのWhatsApp
+1-555-YOU"] -- メッセージ --> B["2台目のスマートフォン (アシスタント用)

アシスタントWA
+1-555-ASSIST"] B -- QR経由でリンク --> C["あなたのMac (openclaw)

Pi エージェント"] ``` 個人の WhatsApp を OpenClaw にリンクすると、あなた宛のすべてのメッセージが「エージェントの入力」になってしまいます。それはほとんどの場合、望んでいることではありません。 ## 5分間クイックスタート 1. WhatsApp Web をペアリングします（QR が表示されるので、アシスタントのスマートフォンでスキャンします）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels login ``` 2. Gateway を起動します（実行したままにします）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway --port 18789 ``` 3. 最小限の設定を `~/.openclaw/openclaw.json` に記述します： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { whatsapp: { allowFrom: ["+15555550123"] } }, } ``` これで、許可リストに登録されたスマートフォンからアシスタントの番号にメッセージを送信できます。 オンボーディングが完了すると、自動的にダッシュボードが開き、クリーンな（トークン化されていない）リンクが表示されます。認証を求められた場合は、`gateway.auth.token` のトークンを Control UI の設定に貼り付けてください。後でもう一度開くには、`openclaw dashboard` を実行します。 ## エージェントにワークスペースを与える (AGENTS) OpenClaw は、そのワークスペースディレクトリから運用指示と「記憶」を読み取ります。 デフォルトでは、OpenClaw はエージェントのワークスペースとして `~/.openclaw/workspace` を使用し、セットアップ時やエージェントの初回実行時に自動的に作成します（スターターの `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` も一緒に作成されます）。`BOOTSTRAP.md` はワークスペースが真新しい場合にのみ作成されます（削除した後に戻ってくることはありません）。`MEMORY.md` はオプションであり（自動作成されません）、存在する場合は通常のセッション用に読み込まれます。サブエージェントのセッションでは、`AGENTS.md` と `TOOLS.md` のみが注入されます。 ヒント：このフォルダを OpenClaw の「記憶」として扱い、git リポジトリ（理想的にはプライベート）にすることで、`AGENTS.md` とメモリファイルがバックアップされるようにしてください。git がインストールされている場合、真新しいワークスペースは自動的に初期化されます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw setup ``` 完全なワークスペースのレイアウトとバックアップガイド：[エージェントワークスペース](/concepts/agent-workspace) メモリのワークフロー：[メモリ](/concepts/memory) オプション：`agents.defaults.workspace` で別のワークスペースを選択します（`~` をサポートしています）。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agent: { workspace: "~/.openclaw/workspace", }, } ``` リポジトリから独自のワークスペースファイルをすでに提供している場合は、ブートストラップファイルの作成を完全に無効にすることができます： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agent: { skipBootstrap: true, }, } ``` ## それを「アシスタント」に変える設定 OpenClaw のデフォルトは優れたアシスタントのセットアップになっていますが、通常は以下を調整することになります： * `SOUL.md` におけるペルソナ / 指示 * 思考のデフォルト（必要に応じて） * ハートビート（信頼できるようになってから） 例： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { logging: { level: "info" }, agent: { model: "anthropic/claude-opus-4-6", workspace: "~/.openclaw/workspace", thinkingDefault: "high", timeoutSeconds: 1800, // 0から始め、後で有効にします。 heartbeat: { every: "0m" }, }, channels: { whatsapp: { allowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, }, }, }, routing: { groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, }, session: { scope: "per-sender", resetTriggers: ["/new", "/reset"], reset: { mode: "daily", atHour: 4, idleMinutes: 10080, }, }, } ``` ## セッションとメモリ * セッションファイル：`~/.openclaw/agents//sessions/{{SessionId}}.jsonl` * セッションのメタデータ（トークン使用量、最後のルートなど）：`~/.openclaw/agents//sessions/sessions.json`（旧：`~/.openclaw/sessions/sessions.json`） * `/new` または `/reset` は、そのチャットの新しいセッションを開始します（`resetTriggers` 経由で設定可能）。単独で送信された場合、エージェントはリセットを確認するために短い挨拶で返信します。 * `/compact [instructions]` はセッションコンテキストを圧縮し、残りのコンテキスト予算を報告します。 ## ハートビート（プロアクティブモード） デフォルトでは、OpenClaw は30分ごとに以下のプロンプトでハートビートを実行します： `存在する場合、HEARTBEAT.mdを読み取ります（ワークスペースコンテキスト）。それに厳密に従ってください。過去のチャットから古いタスクを推測したり繰り返したりしないでください。注意が必要なことが何もない場合は、HEARTBEAT_OK と返信してください。` 無効にするには `agents.defaults.heartbeat.every: "0m"` を設定します。 * `HEARTBEAT.md` は存在するが、実質的に空である（空白行と `# Heading` のようなマークダウンヘッダーのみ）場合、OpenClaw は API 呼び出しを節約するためにハートビートの実行をスキップします。 * ファイルが欠落している場合でも、ハートビートは実行され、モデルが何をすべきかを決定します。 * エージェントが `HEARTBEAT_OK` と返信した場合（オプションで短いパディングを使用できます。`agents.defaults.heartbeat.ackMaxChars` を参照）、OpenClaw はそのハートビートの外部への配信を抑制します。 * デフォルトでは、DM スタイルの `user:` ターゲットへのハートビートの配信は許可されています。ハートビートの実行はアクティブにしたまま、ダイレクトターゲットへの配信を抑制するには、`agents.defaults.heartbeat.directPolicy: "block"` を設定します。 * ハートビートはエージェントのフルターンを実行します — 間隔を短くするとより多くのトークンを消費します。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agent: { heartbeat: { every: "30m" }, }, } ``` ## メディアの入出力 受信した添付ファイル（画像/音声/ドキュメント）は、テンプレートを介してコマンドに表示できます： * `{{MediaPath}}`（ローカルの一時ファイルパス） * `{{MediaUrl}}`（疑似URL） * `{{Transcript}}`（音声書き起こしが有効な場合） エージェントからの送信添付ファイル：その行に単独で `MEDIA:` を含めます（スペースなし）。例： ``` ここにスクリーンショットがあります。 MEDIA:https://example.com/screenshot.png ``` OpenClaw はこれらを抽出し、テキストと一緒にメディアとして送信します。 ## 運用チェックリスト ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw status # ローカルステータス（資格情報、セッション、キューに入っているイベント） openclaw status --all # 完全な診断（読み取り専用、貼り付け可能） openclaw status --deep # ゲートウェイのヘルスプローブを追加（Telegram + Discord） openclaw health --json # ゲートウェイヘルスのスナップショット（WS） ``` ログは `/tmp/openclaw/` の下に配置されます（デフォルト：`openclaw-YYYY-MM-DD.log`）。 ## 次のステップ * WebChat: [WebChat](/web/webchat) * ゲートウェイの運用: [Gateway ランブック](/gateway) * Cron + ウェイクアップ: [Cron ジョブ](/automation/cron-jobs) * macOS メニューバーコンパニオン: [OpenClaw macOS アプリ](/platforms/macos) * iOS ノードアプリ: [iOS アプリ](/platforms/ios) * Android ノードアプリ: [Android アプリ](/platforms/android) * Windows ステータス: [Windows (WSL2)](/platforms/windows) * Linux ステータス: [Linux アプリ](/platforms/linux) * セキュリティ: [セキュリティ](/gateway/security) # ショーケース Source: https://openclawdoc.org/start/showcase OpenClaw を使った実例やコミュニティプロジェクトを通じて、実運用のユースケースを紹介します。 コミュニティからの実際のプロジェクト。人々が OpenClaw で何を構築しているかをご覧ください。 **特集されたいですか？** [Discord の #showcase](https://discord.gg/clawd) でプロジェクトを共有するか、[X で @openclaw をタグ付け](https://x.com/openclaw) してください。 ## 🎥 OpenClaw in Action VelvetShark による完全なセットアップのウォークスルー (28分)。