diff --git a/docs/ja-JP/channels/telegram.md b/docs/ja-JP/channels/telegram.md index 766628707..ae7046f20 100644 --- a/docs/ja-JP/channels/telegram.md +++ b/docs/ja-JP/channels/telegram.md @@ -1,29 +1,29 @@ --- read_when: - - Telegram 機能または webhook に取り組むとき -summary: Telegram ボットのサポート状況、機能、設定 + - Telegramの機能またはWebhookに取り組んでいる場合 +summary: Telegramボットのサポート状況、機能、および設定 title: Telegram x-i18n: - generated_at: "2026-04-05T12:38:43Z" + generated_at: "2026-04-20T04:46:31Z" model: gpt-5.4 provider: openai - source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e + source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477 source_path: channels/telegram.md workflow: 15 --- # Telegram（Bot API） -ステータス: grammY による bot の DM とグループ向けに本番運用対応済みです。long polling がデフォルトモードで、webhook モードは任意です。 +ステータス: grammY経由でのボットDMおよびグループ向けに本番運用対応済み。デフォルトモードはロングポーリングで、Webhookモードは任意です。 - - Telegram のデフォルト DM ポリシーは pairing です。 + + TelegramのデフォルトDMポリシーはペアリングです。 - - チャネル横断の診断と修復プレイブック。 + + クロスチャネルの診断と修復プレイブック。 - + 完全なチャネル設定パターンと例。 @@ -31,14 +31,14 @@ x-i18n: ## クイックセットアップ - - Telegram を開いて **@BotFather** とチャットしてください（ハンドルが正確に `@BotFather` であることを確認してください）。 + + Telegramを開き、**@BotFather**とチャットします（ハンドルが正確に`@BotFather`であることを確認してください）。 - `/newbot` を実行し、案内に従ってトークンを保存します。 + `/newbot`を実行し、案内に従って、トークンを保存します。 - + ```json5 { @@ -53,12 +53,12 @@ x-i18n: } ``` - env フォールバック: `TELEGRAM_BOT_TOKEN=...`（デフォルトアカウントのみ）。 - Telegram では `openclaw channels login telegram` は使いません。config/env にトークンを設定してから Gateway を起動してください。 + 環境変数のフォールバック: `TELEGRAM_BOT_TOKEN=...`（デフォルトアカウントのみ）。 + Telegramでは`openclaw channels login telegram`は使用しません。config/envでトークンを設定してから、gatewayを起動してください。 - + ```bash openclaw gateway @@ -66,115 +66,115 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - pairing コードは 1 時間で期限切れになります。 + ペアリングコードは1時間で期限切れになります。 - - bot をグループに追加し、その後 `channels.telegram.groups` と `groupPolicy` をアクセスモデルに合わせて設定します。 + + ボットをグループに追加し、その後`channels.telegram.groups`と`groupPolicy`をアクセスモデルに合わせて設定します。 -トークン解決順はアカウント認識型です。実際には、config 値が env フォールバックより優先され、`TELEGRAM_BOT_TOKEN` はデフォルトアカウントにのみ適用されます。 +トークン解決順はアカウント対応です。実際には、configの値が環境変数フォールバックより優先され、`TELEGRAM_BOT_TOKEN`はデフォルトアカウントにのみ適用されます。 -## Telegram 側の設定 +## Telegram側の設定 - - Telegram bot はデフォルトで **Privacy Mode** になっており、グループ内で受信できるメッセージが制限されます。 + + Telegramボットはデフォルトで**プライバシーモード**になっており、受信できるグループメッセージが制限されます。 - bot がすべてのグループメッセージを見る必要がある場合は、次のいずれかを行ってください。 + ボットがすべてのグループメッセージを見る必要がある場合は、次のいずれかを行ってください。 - - `/setprivacy` で privacy mode を無効にする - - bot をグループ管理者にする + - `/setprivacy`でプライバシーモードを無効にする + - ボットをグループ管理者にする - privacy mode を切り替えたときは、Telegram が変更を適用するよう、各グループで bot を削除して再追加してください。 + プライバシーモードを切り替えたときは、Telegramが変更を適用するよう、各グループでボットを削除して再追加してください。 - 管理者ステータスは Telegram のグループ設定で管理されます。 + 管理者ステータスはTelegramのグループ設定で制御されます。 - 管理者 bot はすべてのグループメッセージを受信でき、常時動作するグループ挙動に便利です。 + 管理者ボットはすべてのグループメッセージを受信するため、常時有効なグループ動作に便利です。 - + - - `/setjoingroups` でグループ追加の許可/拒否 - - `/setprivacy` でグループ可視性の挙動を設定 + - グループ追加の許可/拒否を行う`/setjoingroups` + - グループ可視性の動作を設定する`/setprivacy` -## アクセス制御と activation +## アクセス制御と有効化 - - `channels.telegram.dmPolicy` はダイレクトメッセージアクセスを制御します。 + + `channels.telegram.dmPolicy`はダイレクトメッセージアクセスを制御します。 - `pairing`（デフォルト） - - `allowlist`（`allowFrom` に少なくとも 1 つの送信者 ID が必要） - - `open`（`allowFrom` に `"*"` を含める必要あり） + - `allowlist`（`allowFrom`に少なくとも1つの送信者IDが必要） + - `open`（`allowFrom`に`"*"`を含める必要あり） - `disabled` - `channels.telegram.allowFrom` には数値の Telegram ユーザー ID を指定します。`telegram:` / `tg:` プレフィックスは受け付けられ、正規化されます。 - 空の `allowFrom` で `dmPolicy: "allowlist"` を設定すると、すべての DM がブロックされ、config 検証で拒否されます。 - オンボーディングでは `@username` 入力を受け付け、数値 ID に解決します。 - アップグレード後の config に `@username` の allowlist エントリが含まれている場合は、`openclaw doctor --fix` を実行して解決してください（ベストエフォートです。Telegram bot トークンが必要です）。 - 以前に pairing-store の allowlist ファイルに依存していた場合、`openclaw doctor --fix` は allowlist フローでそのエントリを `channels.telegram.allowFrom` に復元できます（たとえば `dmPolicy: "allowlist"` にまだ明示的な ID がない場合）。 + `channels.telegram.allowFrom`は数値のTelegramユーザーIDを受け付けます。`telegram:` / `tg:`プレフィックスは受け入れられ、正規化されます。 + 空の`allowFrom`での`dmPolicy: "allowlist"`はすべてのDMをブロックし、config検証で拒否されます。 + セットアップでは数値のユーザーIDのみを求めます。 + アップグレード後にconfigに`@username`のallowlistエントリが含まれている場合は、`openclaw doctor --fix`を実行して解決してください（ベストエフォートです。Telegramボットトークンが必要です）。 + 以前にペアリングストアのallowlistファイルに依存していた場合は、allowlistフローで`openclaw doctor --fix`によりエントリを`channels.telegram.allowFrom`へ復元できます（たとえば、`dmPolicy: "allowlist"`にまだ明示的なIDがない場合）。 - 1 オーナー bot では、以前の pairing 承認に依存するのではなく、アクセスポリシーを config に永続的に保持するために、明示的な数値 `allowFrom` ID を持つ `dmPolicy: "allowlist"` を推奨します。 + 単一オーナーのボットでは、アクセスポリシーをconfig内で永続的に保つため、以前のペアリング承認に依存するのではなく、明示的な数値`allowFrom` IDを指定した`dmPolicy: "allowlist"`を推奨します。 - よくある誤解: DM pairing 承認は「この送信者がどこでも認可される」ことを意味しません。 - pairing が与えるのは DM アクセスのみです。グループ送信者認可は引き続き明示的な config allowlist から行われます。 - 「一度認可すれば DM とグループコマンドの両方が使える」状態にしたい場合は、自分の数値 Telegram ユーザー ID を `channels.telegram.allowFrom` に入れてください。 + よくある混乱: DMペアリング承認は「この送信者がどこでも認可される」という意味ではありません。 + ペアリングが付与するのはDMアクセスのみです。グループ送信者の認可は依然として明示的なconfigのallowlistから行われます。 + 「一度認可されれば、DMもグループコマンドも両方使える」状態にしたい場合は、数値のTelegramユーザーIDを`channels.telegram.allowFrom`に入れてください。 - ### Telegram ユーザー ID を見つける + ### TelegramユーザーIDを見つける - より安全な方法（サードパーティ bot なし）: + より安全な方法（サードパーティボット不要）: - 1. bot に DM を送る。 - 2. `openclaw logs --follow` を実行する。 - 3. `from.id` を読む。 + 1. ボットにDMを送る。 + 2. `openclaw logs --follow`を実行する。 + 3. `from.id`を読む。 - 公式 Bot API の方法: + 公式Bot APIの方法: ```bash curl "https://api.telegram.org/bot/getUpdates" ``` - サードパーティの方法（プライバシー性は低い）: `@userinfobot` または `@getidsbot`。 + サードパーティの方法（プライバシーはやや低い）: `@userinfobot`または`@getidsbot`。 - - 次の 2 つの制御が一緒に適用されます。 + + 2つの制御が一緒に適用されます。 - 1. **どのグループが許可されるか**（`channels.telegram.groups`） - - `groups` config がない: - - `groupPolicy: "open"` の場合: どのグループも group-ID チェックを通過可能 - - `groupPolicy: "allowlist"`（デフォルト）の場合: `groups` エントリ（または `"*"`）を追加するまでグループはブロックされる - - `groups` が設定されている: allowlist として機能する（明示的な ID または `"*"`） + 1. **どのグループを許可するか**（`channels.telegram.groups`） + - `groups` configなし: + - `groupPolicy: "open"`の場合: どのグループでもgroup-IDチェックを通過できます + - `groupPolicy: "allowlist"`（デフォルト）の場合: `groups`エントリ（または`"*"`）を追加するまでグループはブロックされます + - `groups`が設定されている場合: allowlistとして機能します（明示的なIDまたは`"*"`） - 2. **グループ内でどの送信者が許可されるか**（`channels.telegram.groupPolicy`） + 2. **グループ内でどの送信者を許可するか**（`channels.telegram.groupPolicy`） - `open` - `allowlist`（デフォルト） - `disabled` - `groupAllowFrom` はグループ送信者のフィルタリングに使われます。設定されていない場合、Telegram は `allowFrom` にフォールバックします。 - `groupAllowFrom` エントリは数値の Telegram ユーザー ID である必要があります（`telegram:` / `tg:` プレフィックスは正規化されます）。 - Telegram のグループまたは supergroup の chat ID を `groupAllowFrom` に入れないでください。負の chat ID は `channels.telegram.groups` に入れる必要があります。 - 数値でないエントリは送信者認可では無視されます。 - セキュリティ境界（`2026.2.25+`）: グループ送信者認可は DM pairing-store 承認を継承しません。 - pairing は DM 専用のままです。グループについては `groupAllowFrom` またはグループごと/トピックごとの `allowFrom` を設定してください。 - `groupAllowFrom` が未設定の場合、Telegram は pairing store ではなく config の `allowFrom` にフォールバックします。 - 1 オーナー bot の実用パターン: あなたのユーザー ID を `channels.telegram.allowFrom` に設定し、`groupAllowFrom` は未設定のままにし、対象グループを `channels.telegram.groups` で許可します。 - ランタイム注記: `channels.telegram` が完全に欠けている場合、`channels.defaults.groupPolicy` が明示的に設定されていない限り、ランタイムはフェイルクローズドの `groupPolicy="allowlist"` をデフォルトにします。 + `groupAllowFrom`はグループ送信者のフィルタリングに使用されます。設定されていない場合、Telegramは`allowFrom`にフォールバックします。 + `groupAllowFrom`のエントリは数値のTelegramユーザーIDである必要があります（`telegram:` / `tg:`プレフィックスは正規化されます）。 + TelegramのグループまたはスーパーグループのチャットIDを`groupAllowFrom`に入れないでください。負のチャットIDは`channels.telegram.groups`に属します。 + 数値でないエントリは送信者認可で無視されます。 + セキュリティ境界（`2026.2.25+`）: グループ送信者認証はDMペアリングストアの承認を継承しません。 + ペアリングはDM専用のままです。グループ向けには、`groupAllowFrom`またはグループ単位/トピック単位の`allowFrom`を設定してください。 + `groupAllowFrom`が未設定の場合、Telegramはペアリングストアではなくconfigの`allowFrom`にフォールバックします。 + 単一オーナーのボット向けの実用的なパターン: ユーザーIDを`channels.telegram.allowFrom`に設定し、`groupAllowFrom`は未設定のままにして、対象グループを`channels.telegram.groups`で許可します。 + ランタイム注記: `channels.telegram`が完全に欠けている場合、`channels.defaults.groupPolicy`が明示的に設定されていない限り、ランタイムのデフォルトはフェイルクローズの`groupPolicy="allowlist"`です。 - 例: 特定の 1 グループで任意のメンバーを許可する + 例: 特定の1つのグループで任意のメンバーを許可する: ```json5 { @@ -191,7 +191,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 例: 特定の 1 グループ内で特定ユーザーのみ許可する + 例: 特定の1つのグループ内で特定ユーザーのみを許可する: ```json5 { @@ -209,22 +209,22 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - よくある間違い: `groupAllowFrom` は Telegram グループ allowlist ではありません。 + よくある誤り: `groupAllowFrom`はTelegramグループのallowlistではありません。 - - `-1001234567890` のような負の Telegram グループまたは supergroup chat ID は `channels.telegram.groups` に入れてください。 - - 許可されたグループ内で、どの人が bot を起動できるかを制限したいときは、`8734062810` のような Telegram ユーザー ID を `groupAllowFrom` に入れてください。 - - 許可されたグループの任意のメンバーが bot と会話できるようにしたい場合のみ、`groupAllowFrom: ["*"]` を使ってください。 + - `-1001234567890`のような負のTelegramグループまたはスーパーグループのチャットIDは`channels.telegram.groups`に入れてください。 + - 許可されたグループ内で、どの人がボットをトリガーできるかを制限したい場合は、`8734062810`のようなTelegramユーザーIDを`groupAllowFrom`に入れてください。 + - `groupAllowFrom: ["*"]`は、許可されたグループの任意のメンバーがボットと会話できるようにしたい場合にのみ使用してください。 - - グループ返信ではデフォルトでメンションが必要です。 + + グループ返信はデフォルトでメンションが必要です。 - メンションは次のいずれかから得られます。 + メンションは次のいずれかで行えます。 - - ネイティブの `@botusername` メンション - - 次の場所の mention pattern: + - ネイティブの`@botusername`メンション + - 次のメンションパターン: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -233,9 +233,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - これらはセッション状態のみを更新します。永続化には config を使ってください。 + これらはセッション状態のみを更新します。永続化にはconfigを使用してください。 - 永続 config の例: + 永続的なconfigの例: ```json5 { @@ -249,84 +249,84 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - グループ chat ID を取得する方法: + グループチャットIDを取得する方法: - - グループメッセージを `@userinfobot` / `@getidsbot` に転送する - - または `openclaw logs --follow` で `chat.id` を読む - - または Bot API の `getUpdates` を確認する + - グループメッセージを`@userinfobot` / `@getidsbot`に転送する + - または`openclaw logs --follow`で`chat.id`を読む + - またはBot APIの`getUpdates`を確認する -## ランタイムの挙動 +## ランタイム動作 -- Telegram は Gateway プロセスによって所有されます。 -- ルーティングは決定的です。Telegram からの受信メッセージへの返信は Telegram に返されます（モデルがチャネルを選ぶことはありません）。 -- 受信メッセージは、返信メタデータとメディアプレースホルダーを含む共有チャネル envelope に正規化されます。 -- グループセッションはグループ ID ごとに分離されます。フォーラムトピックでは、トピック分離のために `:topic:` が付加されます。 -- DM メッセージは `message_thread_id` を持てます。OpenClaw はそれを thread 認識型のセッションキーでルーティングし、返信時も thread ID を保持します。 -- long polling は、チャットごと / thread ごとの順序制御を備えた grammY runner を使います。全体の runner sink concurrency には `agents.defaults.maxConcurrent` を使います。 -- Telegram Bot API には既読通知のサポートがありません（`sendReadReceipts` は適用されません）。 +- Telegramはgatewayプロセスによって管理されます。 +- ルーティングは決定的です: Telegramの受信返信はTelegramへ返信されます（モデルがチャネルを選ぶことはありません）。 +- 受信メッセージは、返信メタデータとメディアプレースホルダーを含む共有チャネルエンベロープへ正規化されます。 +- グループセッションはグループIDごとに分離されます。フォーラムトピックはトピックを分離するために`:topic:`を追加します。 +- DMメッセージは`message_thread_id`を含めることができます。OpenClawはスレッド対応のセッションキーでそれらをルーティングし、返信用にスレッドIDを保持します。 +- ロングポーリングは、チャット単位/スレッド単位のシーケンシングを備えたgrammY runnerを使用します。runner sink全体の並行性には`agents.defaults.maxConcurrent`を使用します。 +- Telegram Bot APIには既読受信機能がありません（`sendReadReceipts`は適用されません）。 ## 機能リファレンス - OpenClaw は部分返信をリアルタイムでストリーミングできます。 + OpenClawは部分的な返信をリアルタイムでストリーミングできます。 - ダイレクトチャット: プレビューメッセージ + `editMessageText` - グループ/トピック: プレビューメッセージ + `editMessageText` 要件: - - `channels.telegram.streaming` は `off | partial | block | progress` です（デフォルト: `partial`） - - `progress` は Telegram では `partial` にマップされます（チャネル横断の命名互換性のため） - - レガシーな `channels.telegram.streamMode` と boolean の `streaming` 値は自動マッピングされます + - `channels.telegram.streaming`が`off | partial | block | progress`であること（デフォルト: `partial`） + - `progress`はTelegram上では`partial`にマップされます（クロスチャネル命名との互換性のため） + - 旧来の`channels.telegram.streamMode`と真偽値の`streaming`は自動的にマッピングされます テキストのみの返信の場合: - - DM: OpenClaw は同じプレビューメッセージを保持し、最後にその場で編集します（2 通目のメッセージは送信しません） - - グループ/トピック: OpenClaw は同じプレビューメッセージを保持し、最後にその場で編集します（2 通目のメッセージは送信しません） + - DM: OpenClawは同じプレビューメッセージを保持し、最後にその場で編集します（2つ目のメッセージは送信しません） + - グループ/トピック: OpenClawは同じプレビューメッセージを保持し、最後にその場で編集します（2つ目のメッセージは送信しません） - 複雑な返信（たとえばメディアペイロード）の場合、OpenClaw は通常の最終配信にフォールバックし、その後プレビューメッセージをクリーンアップします。 + 複雑な返信（たとえばメディアペイロード）の場合、OpenClawは通常の最終配信にフォールバックし、その後プレビューメッセージをクリーンアップします。 - プレビューストリーミングは block streaming とは別です。Telegram で block streaming が明示的に有効な場合、OpenClaw は二重ストリーミングを避けるためプレビューストリームをスキップします。 + プレビューのストリーミングはブロックストリーミングとは別です。Telegram向けにブロックストリーミングが明示的に有効になっている場合、OpenClawは二重ストリーミングを避けるためプレビューストリームをスキップします。 - ネイティブの draft transport が利用できないか拒否された場合、OpenClaw は自動的に `sendMessage` + `editMessageText` にフォールバックします。 + ネイティブのドラフト転送が利用できない、または拒否された場合、OpenClawは自動的に`sendMessage` + `editMessageText`へフォールバックします。 - Telegram 専用の reasoning ストリーム: + Telegram専用のreasoningストリーム: - - `/reasoning stream` は、生成中の reasoning をライブプレビューに送信します - - 最終回答は reasoning テキストなしで送信されます + - `/reasoning stream`は生成中のreasoningをライブプレビューに送信します + - 最終回答はreasoningテキストなしで送信されます - - 送信テキストは Telegram の `parse_mode: "HTML"` を使います。 + + 送信テキストはTelegramの`parse_mode: "HTML"`を使用します。 - - Markdown 風テキストは Telegram 安全な HTML にレンダリングされます。 - - 生のモデル HTML は Telegram の解析失敗を減らすためエスケープされます。 - - Telegram が解析済み HTML を拒否した場合、OpenClaw はプレーンテキストとして再試行します。 + - Markdown風のテキストはTelegramで安全なHTMLへレンダリングされます。 + - 生のモデルHTMLは、Telegramの解析失敗を減らすためにエスケープされます。 + - Telegramが解析済みHTMLを拒否した場合、OpenClawはプレーンテキストとして再試行します。 - リンクプレビューはデフォルトで有効で、`channels.telegram.linkPreview: false` で無効化できます。 + リンクプレビューはデフォルトで有効で、`channels.telegram.linkPreview: false`で無効化できます。 - Telegram のコマンドメニュー登録は起動時に `setMyCommands` で処理されます。 + Telegramコマンドメニューの登録は起動時に`setMyCommands`で処理されます。 ネイティブコマンドのデフォルト: - - `commands.native: "auto"` は Telegram のネイティブコマンドを有効にします + - `commands.native: "auto"`はTelegram向けのネイティブコマンドを有効にします - カスタムコマンドメニュー項目を追加する: + カスタムコマンドメニュー項目を追加するには: ```json5 { channels: { telegram: { customCommands: [ - { command: "backup", description: "Git バックアップ" }, + { command: "backup", description: "Gitバックアップ" }, { command: "generate", description: "画像を作成" }, ], }, @@ -336,45 +336,45 @@ curl "https://api.telegram.org/bot/getUpdates" ルール: - - 名前は正規化されます（先頭の `/` を削除し、小文字化） - - 有効パターン: `a-z`、`0-9`、`_`、長さ `1..32` + - 名前は正規化されます（先頭の`/`を除去し、小文字化） + - 有効なパターン: `a-z`, `0-9`, `_`、長さ`1..32` - カスタムコマンドはネイティブコマンドを上書きできません - 競合/重複はスキップされ、ログに記録されます 注記: - - カスタムコマンドはメニュー項目のみです。動作は自動実装されません - - Telegram メニューに表示されなくても、plugin/skill コマンドは手入力で動作できます + - カスタムコマンドはメニュー項目のみであり、動作を自動実装するものではありません + - plugin/skillコマンドは、Telegramメニューに表示されていなくても、入力すれば動作する場合があります - ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。設定されていれば、カスタム/plugin コマンドは引き続き登録されることがあります。 + ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。設定されていれば、カスタム/pluginコマンドは引き続き登録される場合があります。 よくあるセットアップ失敗: - - `setMyCommands failed` で `BOT_COMMANDS_TOO_MUCH` が出る場合、削減後でも Telegram メニューが多すぎることを意味します。plugin/skill/custom コマンドを減らすか、`channels.telegram.commands.native` を無効にしてください。 - - `setMyCommands failed` で network/fetch エラーが出る場合、通常は `api.telegram.org` への outbound DNS/HTTPS がブロックされています。 + - `setMyCommands failed`で`BOT_COMMANDS_TOO_MUCH`が出る場合、削減後でもTelegramメニューがまだあふれています。plugin/skill/カスタムコマンドを減らすか、`channels.telegram.commands.native`を無効にしてください。 + - `setMyCommands failed`でnetwork/fetchエラーが出る場合、通常は`api.telegram.org`への外向きDNS/HTTPSがブロックされていることを意味します。 - ### デバイスペアリングコマンド（`device-pair` plugin） + ### デバイスペアリングコマンド（`device-pair` Plugin） - `device-pair` plugin がインストールされている場合: + `device-pair` Pluginがインストールされている場合: - 1. `/pair` でセットアップコードを生成します - 2. iOS アプリにコードを貼り付けます - 3. `/pair pending` で保留中リクエストを一覧表示します（role/scopes を含む） + 1. `/pair`でセットアップコードを生成します + 2. iOSアプリにコードを貼り付けます + 3. `/pair pending`で保留中のリクエストを一覧表示します（role/scopesを含む） 4. リクエストを承認します: - - 明示的に承認するには `/pair approve ` - - 保留中リクエストが 1 件だけなら `/pair approve` - - 最新のものなら `/pair approve latest` + - 明示的な承認には`/pair approve ` + - 保留中が1件だけの場合は`/pair approve` + - 最新のものには`/pair approve latest` - セットアップコードには短命の bootstrap トークンが含まれます。組み込みの bootstrap handoff では、主要な node トークンは `scopes: []` のまま維持されます。引き渡される operator トークンは `operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write` に制限されたままです。bootstrap の scope チェックは role 接頭辞付きなので、その operator allowlist は operator リクエストにのみ有効であり、operator 以外の role では引き続き自分の role 接頭辞の下の scope が必要です。 + セットアップコードには短命のブートストラップトークンが含まれます。組み込みのブートストラップ引き継ぎでは、プライマリNodeトークンは`scopes: []`のまま維持されます。引き継がれたoperatorトークンは、`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`の範囲内に制限されます。ブートストラップのスコープチェックはroleプレフィックス付きなので、そのoperator allowlistはoperatorリクエストだけを満たします。operator以外のroleでは、引き続きそれぞれのroleプレフィックス配下のscopesが必要です。 - デバイスが変更された認証詳細（たとえば role/scopes/public key）で再試行した場合、以前の保留中リクエストは置き換えられ、新しいリクエストは別の `requestId` を使います。承認前に `/pair pending` を再実行してください。 + デバイスが変更された認証詳細（たとえばrole/scopes/public key）で再試行した場合、以前の保留中リクエストは置き換えられ、新しいリクエストは異なる`requestId`を使用します。承認前に`/pair pending`を再実行してください。 - 詳細: [ペアリング](/channels/pairing#pair-via-telegram-recommended-for-ios)。 + 詳細: [ペアリング](/ja-JP/channels/pairing#pair-via-telegram-recommended-for-ios)。 - インラインキーボードのスコープを設定します。 + インラインキーボードのスコープを設定します: ```json5 { @@ -388,7 +388,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - アカウントごとの上書き: + アカウント単位の上書き: ```json5 { @@ -414,7 +414,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist`（デフォルト） - レガシーな `capabilities: ["inlineButtons"]` は `inlineButtons: "all"` にマップされます。 + 旧来の`capabilities: ["inlineButtons"]`は`inlineButtons: "all"`にマップされます。 メッセージアクションの例: @@ -434,21 +434,21 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - callback クリックは、次のテキストとしてエージェントに渡されます: + コールバッククリックはテキストとしてagentに渡されます: `callback_data: ` - - Telegram ツールアクションには次が含まれます。 + + Telegramのツールアクションには次が含まれます: - - `sendMessage`（`to`, `content`, optional `mediaUrl`, `replyToMessageId`, `messageThreadId`） + - `sendMessage`（`to`, `content`, 省略可能: `mediaUrl`, `replyToMessageId`, `messageThreadId`） - `react`（`chatId`, `messageId`, `emoji`） - `deleteMessage`（`chatId`, `messageId`） - `editMessage`（`chatId`, `messageId`, `content`） - - `createForumTopic`（`chatId`, `name`, optional `iconColor`, `iconCustomEmojiId`） + - `createForumTopic`（`chatId`, `name`, 省略可能: `iconColor`, `iconCustomEmojiId`） - チャネルメッセージアクションは使いやすいエイリアスを公開します（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。 + チャネルメッセージアクションは使いやすいエイリアスを公開しています（`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`）。 ゲーティング制御: @@ -457,46 +457,46 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker`（デフォルト: 無効） - 注記: `edit` と `topic-create` は現在デフォルトで有効で、個別の `channels.telegram.actions.*` トグルはありません。 - ランタイム送信は、アクティブな config/secrets スナップショット（起動/再読み込み時）を使うため、アクションパスでは送信ごとに ad-hoc な SecretRef 再解決は行いません。 + 注: `edit`と`topic-create`は現在デフォルトで有効で、個別の`channels.telegram.actions.*`切り替えはありません。 + ランタイム送信はアクティブなconfig/secretsスナップショット（起動時/リロード時）を使用するため、アクション経路では送信ごとにSecretRefをアドホックに再解決しません。 - リアクション削除の意味論: [/tools/reactions](/tools/reactions) + リアクション削除のセマンティクス: [/tools/reactions](/ja-JP/tools/reactions) - - Telegram は生成出力内で明示的な返信 thread タグをサポートします。 + + Telegramは生成出力内で明示的な返信スレッディングタグをサポートします: - - `[[reply_to_current]]` は起動元メッセージに返信します - - `[[reply_to:]]` は特定の Telegram message ID に返信します + - `[[reply_to_current]]`はトリガー元メッセージに返信します + - `[[reply_to:]]`は特定のTelegramメッセージIDに返信します - `channels.telegram.replyToMode` は処理方法を制御します。 + `channels.telegram.replyToMode`が処理方法を制御します: - `off`（デフォルト） - `first` - `all` - 注記: `off` は暗黙の返信 thread 化を無効にします。明示的な `[[reply_to_*]]` タグは引き続き尊重されます。 + 注: `off`は暗黙的な返信スレッディングを無効にします。明示的な`[[reply_to_*]]`タグは引き続き尊重されます。 - - forum supergroup では: + + フォーラムスーパーグループ: - - トピックのセッションキーに `:topic:` が追加されます - - 返信と typing はそのトピック thread を対象にします - - トピック config パス: + - トピックのセッションキーは`:topic:`を追加します + - 返信と入力中表示はそのトピックスレッドを対象にします + - トピックconfigパス: `channels.telegram.groups..topics.` 一般トピック（`threadId=1`）の特別扱い: - - メッセージ送信では `message_thread_id` を省略します（Telegram は `sendMessage(...thread_id=1)` を拒否します） - - typing アクションでは引き続き `message_thread_id` を含めます + - メッセージ送信では`message_thread_id`を省略します（Telegramは`sendMessage(...thread_id=1)`を拒否します） + - 入力中アクションには引き続き`message_thread_id`を含めます - トピック継承: トピックエントリは、上書きされない限りグループ設定を継承します（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 - `agentId` はトピック専用で、グループデフォルトからは継承されません。 + トピック継承: トピックエントリは、上書きされない限りグループ設定を継承します（`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`）。 + `agentId`はトピック専用で、グループデフォルトからは継承されません。 - **トピックごとのエージェントルーティング**: 各トピックは、トピック config に `agentId` を設定することで別のエージェントにルーティングできます。これにより、各トピックが独自の分離された workspace、memory、session を持てます。例: + **トピック単位のagentルーティング**: 各トピックは、トピックconfigで`agentId`を設定することで別々のagentにルーティングできます。これにより、各トピックは独自に分離されたworkspace、memory、sessionを持てます。例: ```json5 { @@ -516,11 +516,11 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - その場合、各トピックは独自のセッションキーを持ちます: `agent:zu:telegram:group:-1001234567890:topic:3` + 各トピックはそれぞれ独自のセッションキーを持ちます: `agent:zu:telegram:group:-1001234567890:topic:3` - **永続 ACP トピックバインディング**: forum topic は、トップレベルの型付き ACP binding を通じて ACP harness session を固定できます。 + **永続的なACPトピックバインディング**: フォーラムトピックは、トップレベルの型付きACPバインディングを通じてACPハーネスセッションを固定できます: - - `type: "acp"` と `match.channel: "telegram"` を持つ `bindings[]` + - `bindings[]`に`type: "acp"`と`match.channel: "telegram"`を指定 例: @@ -569,33 +569,33 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - これは現在、グループおよび supergroup 内の forum topic に限定されています。 + これは現在、グループおよびスーパーグループ内のフォーラムトピックに限定されています。 - **チャットからの thread 固定 ACP 起動**: + **チャットからのスレッドバインドACP起動**: - - `/acp spawn --thread here|auto` で、現在の Telegram トピックを新しい ACP session にバインドできます。 - - 後続のトピックメッセージは、バインドされた ACP session に直接ルーティングされます（`/acp steer` は不要）。 - - OpenClaw は、バインド成功後に起動確認メッセージをそのトピック内に pin します。 - - `channels.telegram.threadBindings.spawnAcpSessions=true` が必要です。 + - `/acp spawn --thread here|auto`で、現在のTelegramトピックを新しいACPセッションにバインドできます。 + - 以降のトピックメッセージは、バインドされたACPセッションへ直接ルーティングされます（`/acp steer`は不要）。 + - OpenClawは、バインド成功後に起動確認メッセージをそのトピック内に固定します。 + - `channels.telegram.threadBindings.spawnAcpSessions=true`が必要です。 - テンプレートコンテキストには次が含まれます。 + テンプレートコンテキストには次が含まれます: - `MessageThreadId` - `IsForum` - DM thread の挙動: + DMスレッド動作: - - `message_thread_id` を持つプライベートチャットでは、DM ルーティングを維持しつつ、thread 認識型の session key / reply target を使います。 + - `message_thread_id`を持つプライベートチャットは、DMルーティングを維持しつつ、スレッド対応のセッションキー/返信先を使用します。 - + ### 音声メッセージ - Telegram はボイスノートと音声ファイルを区別します。 + Telegramはボイスノートと音声ファイルを区別します。 - - デフォルト: 音声ファイルとしての挙動 - - エージェント返信に `[[audio_as_voice]]` タグを付けると、ボイスノート送信を強制 + - デフォルト: 音声ファイル動作 + - agent返信内のタグ`[[audio_as_voice]]`でボイスノート送信を強制 メッセージアクションの例: @@ -611,7 +611,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### 動画メッセージ - Telegram は動画ファイルと video note を区別します。 + Telegramは動画ファイルとビデオノートを区別します。 メッセージアクションの例: @@ -625,17 +625,17 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - video note はキャプションをサポートしません。指定したメッセージテキストは別送されます。 + ビデオノートはキャプションをサポートしません。指定されたメッセージテキストは別送されます。 ### ステッカー 受信ステッカー処理: - - 静的 WEBP: ダウンロードして処理（プレースホルダー ``） - - アニメーション TGS: スキップ - - 動画 WEBM: スキップ + - 静的WEBP: ダウンロードして処理（プレースホルダー``） + - アニメーションTGS: スキップ + - 動画WEBM: スキップ - ステッカーコンテキストフィールド: + ステッカーのコンテキストフィールド: - `Sticker.emoji` - `Sticker.setName` @@ -647,9 +647,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - ステッカーは、繰り返しの vision 呼び出しを減らすため、一度説明可能な場合に説明されてキャッシュされます。 + ステッカーは可能な場合に一度だけ説明生成され、繰り返しのvision呼び出しを減らすためキャッシュされます。 - ステッカーアクションを有効化: + ステッカーアクションを有効にする: ```json5 { @@ -674,13 +674,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - キャッシュ済みステッカーを検索: + キャッシュ済みステッカーを検索する: ```json5 { action: "sticker-search", channel: "telegram", - query: "cat waving", + query: "手を振る猫", limit: 5, } ``` @@ -688,9 +688,9 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram のリアクションは `message_reaction` 更新として届きます（メッセージペイロードとは別です）。 + Telegramのリアクションは`message_reaction`更新として届きます（メッセージpayloadとは別です）。 - 有効時、OpenClaw は次のようなシステムイベントをキューに入れます。 + 有効時、OpenClawは次のようなシステムイベントをキューに入れます: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` @@ -699,42 +699,42 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.reactionNotifications`: `off | own | all`（デフォルト: `own`） - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（デフォルト: `minimal`） - 注記: + 注: - - `own` は bot 送信メッセージへのユーザーリアクションのみを意味します（送信メッセージキャッシュを使ったベストエフォート）。 - - リアクションイベントも Telegram のアクセス制御（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）に従います。認可されていない送信者は破棄されます。 - - Telegram はリアクション更新に thread ID を含めません。 - - forum でないグループではグループ chat session にルーティングされます - - forum グループでは、正確な元トピックではなく、グループ一般トピック session（`:topic:1`）にルーティングされます + - `own`は、ボットが送信したメッセージに対するユーザーリアクションのみを意味します（送信メッセージキャッシュによるベストエフォート）。 + - リアクションイベントもTelegramのアクセス制御（`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`）に従います。未認可の送信者は破棄されます。 + - Telegramはリアクション更新でスレッドIDを提供しません。 + - フォーラムでないグループはグループチャットセッションにルーティングされます + - フォーラムグループは、正確な発生元トピックではなく、グループの一般トピックセッション（`:topic:1`）にルーティングされます - polling/webhook の `allowed_updates` には `message_reaction` が自動的に含まれます。 + ポーリング/Webhookの`allowed_updates`には自動的に`message_reaction`が含まれます。 - - `ackReaction` は、OpenClaw が受信メッセージを処理中であることを示す確認用絵文字を送ります。 + + `ackReaction`は、OpenClawが受信メッセージを処理中に確認用emojiを送信します。 - 解決順: + 解決順序: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - エージェント identity 絵文字へのフォールバック（`agents.list[].identity.emoji`、なければ `"👀"`） + - agent identity emojiフォールバック（`agents.list[].identity.emoji`、なければ`"👀"`） - 注記: + 注: - - Telegram は unicode 絵文字を期待します（たとえば `"👀"`）。 - - チャネルまたはアカウントでリアクションを無効にするには `""` を使ってください。 + - Telegramはunicode emojiを想定します（たとえば`"👀"`）。 + - チャネルまたはアカウントでリアクションを無効にするには`""`を使用してください。 - - チャネル config 書き込みはデフォルトで有効です（`configWrites !== false`）。 + + チャネルconfig書き込みはデフォルトで有効です（`configWrites !== false`）。 - Telegram 起点の書き込みには次が含まれます。 + Telegramトリガーの書き込みには次が含まれます: - - `channels.telegram.groups` を更新するためのグループ migration イベント（`migrate_to_chat_id`） - - `/config set` と `/config unset`（コマンド有効化が必要） + - `channels.telegram.groups`を更新するためのグループ移行イベント（`migrate_to_chat_id`） + - `/config set`および`/config unset`（コマンド有効化が必要） 無効化するには: @@ -750,45 +750,45 @@ curl "https://api.telegram.org/bot/getUpdates" - - デフォルト: long polling。 + + デフォルト: ロングポーリング。 - webhook モード: + Webhookモード: - - `channels.telegram.webhookUrl` を設定 - - `channels.telegram.webhookSecret` を設定（webhook URL を設定した場合は必須） - - 任意で `channels.telegram.webhookPath`（デフォルト `/telegram-webhook`） - - 任意で `channels.telegram.webhookHost`（デフォルト `127.0.0.1`） - - 任意で `channels.telegram.webhookPort`（デフォルト `8787`） + - `channels.telegram.webhookUrl`を設定 + - `channels.telegram.webhookSecret`を設定（webhook URL設定時は必須） + - 任意で`channels.telegram.webhookPath`（デフォルト`/telegram-webhook`） + - 任意で`channels.telegram.webhookHost`（デフォルト`127.0.0.1`） + - 任意で`channels.telegram.webhookPort`（デフォルト`8787`） - webhook モードのデフォルトのローカルリスナーは `127.0.0.1:8787` に bind します。 + Webhookモードのデフォルトローカルリスナーは`127.0.0.1:8787`にバインドされます。 - 公開エンドポイントが異なる場合は、その前段に reverse proxy を置き、`webhookUrl` を公開 URL に向けてください。 - 意図的に外部 ingress が必要な場合は、`webhookHost`（たとえば `0.0.0.0`）を設定してください。 + 公開エンドポイントが異なる場合は、前段にリバースプロキシを置き、`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` で無効化します。 - - reply/quote/forward の補助コンテキストは、現在は受信したまま渡されます。 - - Telegram の allowlist は主に誰がエージェントを起動できるかを制御するものであり、補助コンテキスト全体のマスキング境界ではありません。 - - DM 履歴制御: + + - `channels.telegram.textChunkLimit`のデフォルトは4000です。 + - `channels.telegram.chunkMode="newline"`は、長さで分割する前に段落境界（空行）を優先します。 + - `channels.telegram.mediaMaxMb`（デフォルト100）は、Telegramメディアの受信および送信サイズ上限を設定します。 + - `channels.telegram.timeoutSeconds`はTelegram APIクライアントのタイムアウトを上書きします（未設定の場合はgrammYのデフォルトが適用されます）。 + - グループコンテキスト履歴は`channels.telegram.historyLimit`または`messages.groupChat.historyLimit`（デフォルト50）を使用します。`0`で無効化されます。 + - reply/quote/forwardの補足コンテキストは現在、受信したまま渡されます。 + - Telegramのallowlistは主に、誰がagentをトリガーできるかを制御するものであり、補足コンテキストの完全な秘匿境界ではありません。 + - DM履歴の制御: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` config は、回復可能な outbound API エラーに対する Telegram 送信ヘルパー（CLI/tools/actions）に適用されます。 + - `channels.telegram.retry` configは、回復可能な送信APIエラーに対するTelegram送信ヘルパー（CLI/tools/actions）に適用されます。 - CLI の送信ターゲットには数値 chat ID または username を使えます: + CLIの送信ターゲットには数値のchat IDまたはusernameを指定できます: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Telegram の poll には `openclaw message poll` を使い、forum topic もサポートします: + Telegramのpollは`openclaw message poll`を使用し、フォーラムトピックもサポートします: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -798,74 +798,79 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Telegram 専用の poll フラグ: + Telegram専用のpollフラグ: - `--poll-duration-seconds`（5-600） - `--poll-anonymous` - `--poll-public` - - forum topic 用の `--thread-id`（または `:topic:` ターゲットを使用） + - フォーラムトピック用の`--thread-id`（または`:topic:`ターゲットを使用） - Telegram 送信では次もサポートします: + Telegramのsendは次もサポートします: - - `channels.telegram.capabilities.inlineButtons` が許可している場合の、インラインキーボード用 `--buttons` - - 送信画像や GIF を圧縮された写真やアニメーションメディアアップロードではなく document として送る `--force-document` + - `channels.telegram.capabilities.inlineButtons`が許可している場合の、インラインキーボード用`--buttons` + - 送信画像やGIFを圧縮写真やアニメーションメディアアップロードではなく、ドキュメントとして送信する`--force-document` - アクションゲーティング: + アクションのゲーティング: - - `channels.telegram.actions.sendMessage=false` は、poll を含む outbound Telegram メッセージを無効化します - - `channels.telegram.actions.poll=false` は、通常送信は有効のまま Telegram poll 作成を無効化します + - `channels.telegram.actions.sendMessage=false`は、pollを含む送信Telegramメッセージを無効にします + - `channels.telegram.actions.poll=false`は、通常送信を有効のままにしてTelegram poll作成を無効にします - - Telegram は approver DM 内で exec 承認をサポートし、任意で元のチャットまたはトピックに承認プロンプトを投稿できます。 + + Telegramは承認者DM内でexec承認をサポートし、必要に応じて元のchatまたはtopicにも承認プロンプトを投稿できます。 - config パス: + configパス: - `channels.telegram.execApprovals.enabled` - - `channels.telegram.execApprovals.approvers`（任意。可能な場合は `allowFrom` とダイレクトメッセージの `defaultTo` から推測される数値 owner ID にフォールバック） + - `channels.telegram.execApprovals.approvers`（任意。可能な場合は`allowFrom`および直接の`defaultTo`から推定される数値owner IDにフォールバック） - `channels.telegram.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`） - - `agentFilter`、`sessionFilter` + - `agentFilter`, `sessionFilter` - approver は数値の Telegram ユーザー ID である必要があります。`enabled` が未設定または `"auto"` で、`execApprovals.approvers` またはアカウントの数値 owner config（`allowFrom` とダイレクトメッセージの `defaultTo`）から少なくとも 1 人の approver を解決できる場合、Telegram はネイティブ exec 承認を自動有効化します。Telegram をネイティブ承認クライアントとして明示的に無効にするには `enabled: false` を設定してください。そうでない場合、承認リクエストは他の設定済み承認ルートまたは exec 承認フォールバックポリシーにフォールバックします。 + approverは数値のTelegramユーザーIDである必要があります。Telegramは、`enabled`が未設定または`"auto"`で、`execApprovals.approvers`またはアカウントの数値owner config（`allowFrom`およびダイレクトメッセージの`defaultTo`）から少なくとも1人のapproverを解決できる場合、ネイティブexec承認を自動有効化します。ネイティブ承認クライアントとしてのTelegramを明示的に無効にするには、`enabled: false`を設定してください。それ以外の場合、承認リクエストは他の設定済み承認ルートまたはexec承認のフォールバックポリシーにフォールバックします。 - Telegram は、他のチャットチャネルで使われる共有承認ボタンもレンダリングします。ネイティブ Telegram アダプターが主に追加するのは、approver DM へのルーティング、チャネル/トピックへのファンアウト、配信前の typing ヒントです。 - それらのボタンがある場合、それが主要な承認 UX です。OpenClaw は、ツール結果でチャット承認が利用不可と示される場合、または手動承認が唯一の手段である場合にのみ、手動の `/approve` コマンドを含めるべきです。 + Telegramは、他のチャットチャネルで使われる共有承認ボタンも表示します。ネイティブTelegramアダプターは主に、承認者DMルーティング、チャネル/topicへのファンアウト、および配信前の入力中ヒントを追加します。 + それらのボタンが存在する場合、それが主要な承認UXです。OpenClaw + は、tool結果が + チャット承認を利用できないと示す場合、または手動承認のみが唯一の手段である場合にのみ、手動の`/approve`コマンドを含めるべきです。 配信ルール: - - `target: "dm"` は、解決された approver DM にのみ承認プロンプトを送信します - - `target: "channel"` は、元の Telegram chat/topic にプロンプトを送り返します - - `target: "both"` は、approver DM と元の chat/topic の両方に送信します + - `target: "dm"`は、解決済みapproverのDMにのみ承認プロンプトを送信します + - `target: "channel"`は、元のTelegram chat/topicにプロンプトを返送します + - `target: "both"`は、approverのDMと元のchat/topicの両方に送信します - 解決された approver のみが承認または拒否できます。approver でない人は `/approve` も Telegram 承認ボタンも使えません。 + 解決済みapproverだけが承認または拒否できます。非approverは`/approve`を使えず、Telegram承認ボタンも使えません。 - 承認解決の挙動: + 承認解決の動作: - - `plugin:` で始まる承認 ID は常に plugin 承認を通じて解決されます。 - - それ以外の承認 ID は最初に `exec.approval.resolve` を試します。 - - Telegram も plugin 承認用に認可されており、かつ Gateway が exec 承認を unknown/expired と返した場合、Telegram は `plugin.approval.resolve` で 1 回だけ再試行します。 - - 実際の exec 承認拒否/エラーは、黙って plugin 承認解決にフォールスルーしません。 + - `plugin:`プレフィックス付きIDは常にplugin承認を通じて解決されます。 + - それ以外の承認IDは、まず`exec.approval.resolve`を試します。 + - Telegramもplugin承認用に認可されており、gatewayが + exec承認は不明または期限切れだと返した場合、Telegramは + `plugin.approval.resolve`を通じて一度だけ再試行します。 + - 実際のexec承認拒否/エラーは、黙ってplugin + 承認解決にフォールスルーしません。 - チャネル配信ではコマンドテキストが chat に表示されるため、`channel` または `both` は信頼できるグループ/トピックでのみ有効化してください。forum topic にプロンプトが届いた場合、OpenClaw は承認プロンプトと承認後フォローアップの両方でそのトピックを維持します。exec 承認のデフォルト有効期限は 30 分です。 + チャネル配信ではchatにコマンドテキストが表示されるため、`channel`または`both`は信頼できるグループ/topicでのみ有効にしてください。プロンプトがフォーラムトピックに届いた場合、OpenClawは承認プロンプトと承認後フォローアップの両方でそのトピックを保持します。exec承認のデフォルト有効期限は30分です。 - インライン承認ボタンも、`channels.telegram.capabilities.inlineButtons` が対象サーフェス（`dm`、`group`、または `all`）を許可している必要があります。 + インライン承認ボタンも、`channels.telegram.capabilities.inlineButtons`が対象サーフェス（`dm`、`group`、または`all`）を許可していることに依存します。 - 関連ドキュメント: [Exec approvals](/tools/exec-approvals) + 関連ドキュメント: [Exec承認](/ja-JP/tools/exec-approvals) -## エラー返信制御 +## エラー返信の制御 -エージェントが配信エラーまたはプロバイダーエラーに遭遇したとき、Telegram はそのエラーテキストを返信するか、抑制するかを選べます。この挙動は 2 つの config キーで制御されます。 +agentが配信エラーまたはproviderエラーに遭遇したとき、Telegramではエラーテキストで返信するか、抑制するかを選べます。この動作は2つのconfigキーで制御されます。 -| キー | 値 | デフォルト | 説明 | -| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` は chat にわかりやすいエラーメッセージを送ります。`silent` はエラー返信を完全に抑制します。 | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 同じ chat へのエラー返信の最小間隔。障害時のエラースパムを防ぎます。 | +| Key | Values | Default | 説明 | +| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply`はchatに親しみやすいエラーメッセージを送信します。`silent`はエラー返信を完全に抑制します。 | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 同じchatへのエラー返信間の最小時間。障害中のエラースパムを防ぎます。 | -アカウントごと、グループごと、トピックごとの上書きがサポートされます（他の Telegram config キーと同じ継承）。 +アカウント単位、グループ単位、およびトピック単位の上書きをサポートしています（他のTelegram configキーと同じ継承）。 ```json5 { @@ -886,40 +891,40 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## トラブルシューティング - + - - `requireMention=false` の場合、Telegram privacy mode が完全可視性を許可している必要があります。 - - BotFather: `/setprivacy` -> Disable - - その後、グループから bot を削除して再追加 - - `openclaw channels status` は、config がメンションなしのグループメッセージを想定している場合に警告します。 - - `openclaw channels status --probe` は明示的な数値グループ ID を確認できます。ワイルドカード `"*"` は membership probe できません。 + - `requireMention=false`の場合、Telegramプライバシーモードで完全可視性が許可されている必要があります。 + - BotFather: `/setprivacy` -> 無効化 + - その後、グループからボットを削除して再追加 + - `openclaw channels status`は、configがメンションなしのグループメッセージを想定していると警告します。 + - `openclaw channels status --probe`は明示的な数値グループIDを確認できます。ワイルドカード`"*"`のメンバーシップはprobeできません。 - 手早いセッションテスト: `/activation always`。 - + - - `channels.telegram.groups` が存在する場合、グループはそこに列挙されている必要があります（または `"*"` を含める） - - グループ内の bot メンバーシップを確認 - - スキップ理由は `openclaw logs --follow` でログを確認 + - `channels.telegram.groups`が存在する場合、そのグループが列挙されている必要があります（または`"*"`を含める） + - グループ内でのボットメンバーシップを確認する + - ログを確認する: スキップ理由は`openclaw logs --follow` - + - - 送信者 ID を認可する（pairing および/または数値 `allowFrom`） - - グループポリシーが `open` でも、コマンド認可は引き続き適用されます - - `setMyCommands failed` で `BOT_COMMANDS_TOO_MUCH` が出る場合、ネイティブメニューの項目が多すぎます。plugin/skill/custom コマンドを減らすか、ネイティブメニューを無効化してください - - `setMyCommands failed` で network/fetch エラーが出る場合、通常は `api.telegram.org` への DNS/HTTPS 到達性の問題です + - 送信者IDを認可する（ペアリングおよび/または数値`allowFrom`） + - グループポリシーが`open`でも、コマンド認可は引き続き適用されます + - `setMyCommands failed`で`BOT_COMMANDS_TOO_MUCH`が出る場合、ネイティブメニューの項目数が多すぎます。plugin/skill/カスタムコマンドを減らすか、ネイティブメニューを無効にしてください + - `setMyCommands failed`でnetwork/fetchエラーが出る場合、通常は`api.telegram.org`へのDNS/HTTPS到達性の問題を示します - + - - Node 22+ とカスタム fetch/proxy の組み合わせでは、AbortSignal 型の不一致により即時 abort 挙動が発生することがあります。 - - 一部ホストでは `api.telegram.org` がまず IPv6 に解決され、IPv6 outbound が壊れていると Telegram API 障害が断続的に発生することがあります。 - - ログに `TypeError: fetch failed` または `Network request for 'getUpdates' failed!` が含まれている場合、OpenClaw は現在これらを回復可能なネットワークエラーとして再試行します。 - - 直接 outbound/TLS が不安定な VPS ホストでは、Telegram API 呼び出しを `channels.telegram.proxy` 経由にしてください: + - Node 22+ + カスタムfetch/proxyでは、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 channels: @@ -927,8 +932,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ では `autoSelectFamily=true`（WSL2 を除く）と `dnsResultOrder=ipv4first` がデフォルトです。 - - ホストが WSL2 である、または明示的に IPv4-only のほうがうまく動作する場合は、family selection を強制してください: + - Node 22+のデフォルトは`autoSelectFamily=true`（WSL2を除く）および`dnsResultOrder=ipv4first`です。 + - ホストがWSL2である場合、または明示的にIPv4専用動作のほうが良い場合は、family選択を強制してください: ```yaml channels: @@ -937,7 +942,11 @@ channels: autoSelectFamily: false ``` - - RFC 2544 の benchmark-range 応答（`198.18.0.0/15`）は、Telegram メディアダウンロードでデフォルト許可されています。信頼できる fake-IP または transparent proxy がメディアダウンロード中に `api.telegram.org` を別の private/internal/special-use アドレスへ書き換える場合は、Telegram 専用バイパスを opt-in できます: + - RFC 2544ベンチマーク範囲の応答（`198.18.0.0/15`）は、Telegramメディアダウンロードに対してデフォルトで + すでに許可されています。信頼できる偽IPまたは + 透過プロキシが、メディアダウンロード中に`api.telegram.org`を + それ以外のプライベート/内部/特別用途アドレスへ書き換える場合は、 + Telegram専用バイパスを明示的に有効化できます: ```yaml channels: @@ -946,20 +955,23 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 同じ opt-in はアカウントごとにも利用できます: - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`。 - - proxy が Telegram メディアホストを `198.18.x.x` に解決する場合は、まず dangerous フラグをオフのままにしてください。Telegram メディアは RFC 2544 benchmark range をすでにデフォルト許可しています。 + - 同じ明示的有効化はアカウント単位でも + `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`で利用できます。 + - プロキシがTelegramメディアホストを`198.18.x.x`に解決する場合は、まず + dangerousフラグをオフのままにしてください。TelegramメディアはすでにRFC 2544 + ベンチマーク範囲をデフォルトで許可しています。 - `channels.telegram.network.dangerouslyAllowPrivateNetwork` は Telegram - メディアの SSRF 保護を弱めます。Clash、Mihomo、Surge の fake-IP ルーティングのように、信頼できる operator 管理の proxy 環境が RFC 2544 benchmark range 外の private または special-use 応答を合成する場合にのみ使ってください。通常のパブリックインターネット経由の Telegram アクセスではオフのままにしてください。 + `channels.telegram.network.dangerouslyAllowPrivateNetwork`はTelegram + メディアSSRF保護を弱めます。これは、Clash、Mihomo、またはSurgeの偽IPルーティングのような、オペレーターが信頼して制御するプロキシ環境で、 + RFC 2544ベンチマーク範囲外のプライベートまたは特別用途応答を生成する場合にのみ使用してください。通常の公開インターネットでのTelegramアクセスではオフのままにしてください。 - - 一時的な環境変数上書き: + - 環境変数による上書き（一時的）: - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - DNS 応答を検証する: + - DNS応答を確認する: ```bash dig +short api.telegram.org A @@ -969,87 +981,87 @@ dig +short api.telegram.org AAAA -さらに詳しく: [チャネルのトラブルシューティング](/channels/troubleshooting)。 +詳細: [チャネルのトラブルシューティング](/ja-JP/channels/troubleshooting)。 -## Telegram config リファレンスのポイント +## Telegram設定リファレンスへのポインター 主なリファレンス: - `channels.telegram.enabled`: チャネル起動の有効/無効。 -- `channels.telegram.botToken`: bot トークン（BotFather）。 -- `channels.telegram.tokenFile`: 通常ファイルのパスからトークンを読み取ります。symlink は拒否されます。 +- `channels.telegram.botToken`: ボットトークン（BotFather）。 +- `channels.telegram.tokenFile`: 通常ファイルパスからトークンを読み取ります。シンボリックリンクは拒否されます。 - `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled`（デフォルト: pairing）。 -- `channels.telegram.allowFrom`: DM allowlist（数値 Telegram ユーザー ID）。`allowlist` には少なくとも 1 つの送信者 ID が必要です。`open` には `"*"` が必要です。`openclaw doctor --fix` はレガシー `@username` エントリを ID に解決し、allowlist 移行フローで pairing-store ファイルから allowlist エントリを復元できます。 -- `channels.telegram.actions.poll`: Telegram poll 作成を有効化または無効化します（デフォルト: 有効。引き続き `sendMessage` が必要）。 -- `channels.telegram.defaultTo`: CLI `--deliver` が明示的な `--reply-to` なしで使うデフォルトの Telegram ターゲット。 +- `channels.telegram.allowFrom`: DM allowlist（数値のTelegramユーザーID）。`allowlist`には少なくとも1つの送信者IDが必要です。`open`には`"*"`が必要です。`openclaw doctor --fix`は旧来の`@username`エントリをIDに解決でき、allowlist移行フローではペアリングストアファイルからallowlistエントリを復元することもできます。 +- `channels.telegram.actions.poll`: Telegram poll作成を有効または無効にします（デフォルト: 有効。引き続き`sendMessage`が必要です）。 +- `channels.telegram.defaultTo`: 明示的な`--reply-to`が指定されていない場合にCLIの`--deliver`で使われるデフォルトのTelegramターゲット。 - `channels.telegram.groupPolicy`: `open | allowlist | disabled`（デフォルト: allowlist）。 -- `channels.telegram.groupAllowFrom`: グループ送信者 allowlist（数値 Telegram ユーザー ID）。`openclaw doctor --fix` はレガシー `@username` エントリを ID に解決できます。数値でないエントリは認可時に無視されます。グループ認可では DM pairing-store フォールバックを使いません（`2026.2.25+`）。 +- `channels.telegram.groupAllowFrom`: グループ送信者allowlist（数値のTelegramユーザーID）。`openclaw doctor --fix`は旧来の`@username`エントリをIDに解決できます。数値でないエントリは認可時に無視されます。グループ認証ではDMペアリングストアのフォールバックは使用されません（`2026.2.25+`）。 - マルチアカウントの優先順位: - - 2 つ以上の account ID が設定されている場合、デフォルトルーティングを明示するために `channels.telegram.defaultAccount` を設定するか、`channels.telegram.accounts.default` を含めてください。 - - どちらも設定されていない場合、OpenClaw は最初に正規化された account ID にフォールバックし、`openclaw doctor` が警告します。 - - `channels.telegram.accounts.default.allowFrom` と `channels.telegram.accounts.default.groupAllowFrom` は `default` アカウントにのみ適用されます。 - - 名前付きアカウントは、アカウントレベルの値が未設定の場合、`channels.telegram.allowFrom` と `channels.telegram.groupAllowFrom` を継承します。 - - 名前付きアカウントは `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom` を継承しません。 -- `channels.telegram.groups`: グループごとのデフォルト + allowlist（グローバルデフォルトには `"*"` を使用）。 - - `channels.telegram.groups..groupPolicy`: groupPolicy のグループごとの上書き（`open | allowlist | disabled`）。 - - `channels.telegram.groups..requireMention`: メンションゲーティングのデフォルト。 - - `channels.telegram.groups..skills`: skill フィルター（省略 = すべての Skills、空 = なし）。 - - `channels.telegram.groups..allowFrom`: グループごとの送信者 allowlist 上書き。 - - `channels.telegram.groups..systemPrompt`: グループ用の追加 system prompt。 - - `channels.telegram.groups..enabled`: `false` のときグループを無効化。 - - `channels.telegram.groups..topics..*`: トピックごとの上書き（グループフィールド + トピック専用 `agentId`）。 - - `channels.telegram.groups..topics..agentId`: このトピックを特定のエージェントにルーティングします（グループレベルと binding ルーティングを上書き）。 -- `channels.telegram.groups..topics..groupPolicy`: groupPolicy のトピックごとの上書き（`open | allowlist | disabled`）。 -- `channels.telegram.groups..topics..requireMention`: トピックごとのメンションゲーティング上書き。 -- `type: "acp"` と `match.peer.id` に正規のトピック ID `chatId:topic:topicId` を持つトップレベル `bindings[]`: 永続 ACP トピック binding フィールド（[ACP Agents](/tools/acp-agents#channel-specific-settings)を参照）。 -- `channels.telegram.direct..topics..agentId`: DM トピックを特定のエージェントにルーティングします（forum topic と同じ挙動）。 -- `channels.telegram.execApprovals.enabled`: このアカウントで Telegram をチャットベースの exec 承認クライアントとして有効化。 -- `channels.telegram.execApprovals.approvers`: exec リクエストを承認または拒否できる Telegram ユーザー ID。`channels.telegram.allowFrom` またはダイレクトな `channels.telegram.defaultTo` で owner がすでに識別されている場合は任意です。 -- `channels.telegram.execApprovals.target`: `dm | channel | both`（デフォルト: `dm`）。`channel` と `both` は、存在する場合に元の Telegram トピックを維持します。 -- `channels.telegram.execApprovals.agentFilter`: 転送される承認プロンプト向けの任意のエージェント ID フィルター。 -- `channels.telegram.execApprovals.sessionFilter`: 転送される承認プロンプト向けの任意の session key フィルター（substring または regex）。 -- `channels.telegram.accounts..execApprovals`: Telegram exec 承認ルーティングと approver 認可のアカウントごとの上書き。 + - 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`: グループ単位のデフォルト + allowlist（グローバルデフォルトには`"*"`を使用）。 + - `channels.telegram.groups..groupPolicy`: groupPolicyのグループ単位上書き（`open | allowlist | disabled`）。 + - `channels.telegram.groups..requireMention`: メンション制御のデフォルト。 + - `channels.telegram.groups..skills`: Skillsフィルター（省略 = すべてのSkills、空 = なし）。 + - `channels.telegram.groups..allowFrom`: グループ単位の送信者allowlist上書き。 + - `channels.telegram.groups..systemPrompt`: そのグループ向けの追加system prompt。 + - `channels.telegram.groups..enabled`: `false`の場合、そのグループを無効化。 + - `channels.telegram.groups..topics..*`: トピック単位の上書き（グループフィールド + トピック専用の`agentId`）。 + - `channels.telegram.groups..topics..agentId`: このトピックを特定のagentにルーティングします（グループレベルおよびbindingルーティングを上書き）。 +- `channels.telegram.groups..topics..groupPolicy`: groupPolicyのトピック単位上書き（`open | allowlist | disabled`）。 +- `channels.telegram.groups..topics..requireMention`: トピック単位のメンション制御上書き。 +- `match.peer.id`に`type: "acp"`と正規のトピックID `chatId:topic:topicId`を持つトップレベルの`bindings[]`: 永続的なACPトピックバインディングフィールド（[ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)を参照）。 +- `channels.telegram.direct..topics..agentId`: DMトピックを特定のagentにルーティングします（フォーラムトピックと同じ動作）。 +- `channels.telegram.execApprovals.enabled`: このアカウントでTelegramをチャットベースのexec承認クライアントとして有効にします。 +- `channels.telegram.execApprovals.approvers`: execリクエストの承認または拒否を許可されたTelegramユーザーID。`channels.telegram.allowFrom`または直接の`channels.telegram.defaultTo`ですでにownerが特定されている場合は任意です。 +- `channels.telegram.execApprovals.target`: `dm | channel | both`（デフォルト: `dm`）。`channel`と`both`は、存在する場合、元のTelegramトピックを保持します。 +- `channels.telegram.execApprovals.agentFilter`: 転送される承認プロンプト用の任意のagent IDフィルター。 +- `channels.telegram.execApprovals.sessionFilter`: 転送される承認プロンプト用の任意のsession keyフィルター（部分文字列またはregex）。 +- `channels.telegram.accounts..execApprovals`: Telegram exec承認ルーティングおよび承認者認可のアカウント単位上書き。 - `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist`（デフォルト: allowlist）。 -- `channels.telegram.accounts..capabilities.inlineButtons`: アカウントごとの上書き。 -- `channels.telegram.commands.nativeSkills`: Telegram ネイティブ skills コマンドの有効/無効。 +- `channels.telegram.accounts..capabilities.inlineButtons`: アカウント単位の上書き。 +- `channels.telegram.commands.nativeSkills`: TelegramネイティブSkillsコマンドの有効/無効。 - `channels.telegram.replyToMode`: `off | first | all`（デフォルト: `off`）。 - `channels.telegram.textChunkLimit`: 送信チャンクサイズ（文字数）。 -- `channels.telegram.chunkMode`: `length`（デフォルト）または `newline`。length chunking の前に空行で分割します（段落境界）。 -- `channels.telegram.linkPreview`: 送信メッセージのリンクプレビュー切り替え（デフォルト: true）。 -- `channels.telegram.streaming`: `off | partial | block | progress`（ライブストリームプレビュー。デフォルト: `partial`。`progress` は `partial` にマップ。`block` はレガシーなプレビューモード互換）。Telegram のプレビューストリーミングは、1 つのプレビューメッセージをその場で編集します。 -- `channels.telegram.mediaMaxMb`: 受信/送信 Telegram メディア上限（MB、デフォルト: 100）。 -- `channels.telegram.retry`: 回復可能な outbound API エラーに対する Telegram 送信ヘルパー（CLI/tools/actions）の再試行ポリシー（attempts、minDelayMs、maxDelayMs、jitter）。 -- `channels.telegram.network.autoSelectFamily`: Node の autoSelectFamily を上書き（true=有効、false=無効）。デフォルトでは Node 22+ で有効、WSL2 ではデフォルトで無効。 -- `channels.telegram.network.dnsResultOrder`: DNS 結果順序を上書き（`ipv4first` または `verbatim`）。デフォルトでは Node 22+ で `ipv4first`。 -- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: 信頼できる fake-IP または transparent-proxy 環境で、Telegram メディアダウンロードがデフォルトの RFC 2544 benchmark-range 許可外の private/internal/special-use アドレスに `api.telegram.org` を解決する場合の危険な opt-in。 -- `channels.telegram.proxy`: Bot API 呼び出し用の proxy URL（SOCKS/HTTP）。 -- `channels.telegram.webhookUrl`: webhook モードを有効化（`channels.telegram.webhookSecret` が必要）。 -- `channels.telegram.webhookSecret`: webhook secret（webhookUrl が設定されている場合は必須）。 -- `channels.telegram.webhookPath`: ローカル webhook パス（デフォルト `/telegram-webhook`）。 -- `channels.telegram.webhookHost`: ローカル webhook bind ホスト（デフォルト `127.0.0.1`）。 -- `channels.telegram.webhookPort`: ローカル webhook bind ポート（デフォルト `8787`）。 -- `channels.telegram.actions.reactions`: Telegram ツールリアクションのゲート。 -- `channels.telegram.actions.sendMessage`: Telegram ツールメッセージ送信のゲート。 -- `channels.telegram.actions.deleteMessage`: Telegram ツールメッセージ削除のゲート。 -- `channels.telegram.actions.sticker`: Telegram ステッカーアクションのゲート — 送信と検索（デフォルト: false）。 -- `channels.telegram.reactionNotifications`: `off | own | all` — どのリアクションがシステムイベントを発生させるかを制御（未設定時のデフォルト: `own`）。 -- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — エージェントのリアクション機能を制御（未設定時のデフォルト: `minimal`）。 -- `channels.telegram.errorPolicy`: `reply | silent` — エラー返信挙動を制御（デフォルト: `reply`）。アカウント/グループ/トピックごとの上書き対応。 -- `channels.telegram.errorCooldownMs`: 同じ chat へのエラー返信間の最小 ms（デフォルト: `60000`）。障害時のエラースパムを防ぎます。 +- `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エラーに対するTelegram送信ヘルパー（CLI/tools/actions）のリトライポリシー（attempts、minDelayMs、maxDelayMs、jitter）。 +- `channels.telegram.network.autoSelectFamily`: NodeのautoSelectFamilyを上書きします（true=有効、false=無効）。デフォルトではNode 22+で有効で、WSL2ではデフォルト無効です。 +- `channels.telegram.network.dnsResultOrder`: DNS結果順を上書きします（`ipv4first`または`verbatim`）。デフォルトではNode 22+で`ipv4first`です。 +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: 信頼できる偽IPまたは透過プロキシ環境で、Telegramメディアダウンロード時に`api.telegram.org`がデフォルトのRFC 2544ベンチマーク範囲許可外のプライベート/内部/特別用途アドレスへ解決される場合の危険な明示的有効化。 +- `channels.telegram.proxy`: Bot 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`: Telegramツールメッセージ送信のゲート。 +- `channels.telegram.actions.deleteMessage`: Telegramツールメッセージ削除のゲート。 +- `channels.telegram.actions.sticker`: Telegramステッカーアクション（送信と検索）のゲート（デフォルト: false）。 +- `channels.telegram.reactionNotifications`: `off | own | all` — どのリアクションがシステムイベントをトリガーするかを制御します（未設定時のデフォルト: `own`）。 +- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — agentのリアクション機能を制御します（未設定時のデフォルト: `minimal`）。 +- `channels.telegram.errorPolicy`: `reply | silent` — エラー返信動作を制御します（デフォルト: `reply`）。アカウント単位/グループ単位/トピック単位の上書きをサポートします。 +- `channels.telegram.errorCooldownMs`: 同じchatへのエラー返信間の最小ミリ秒数（デフォルト: `60000`）。障害中のエラースパムを防ぎます。 -- [Configuration reference - Telegram](/gateway/configuration-reference#telegram) +- [設定リファレンス - Telegram](/ja-JP/gateway/configuration-reference#telegram) -Telegram 固有の重要フィールド: +Telegram固有の重要フィールド: -- 起動/認証: `enabled`, `botToken`, `tokenFile`, `accounts.*`（`tokenFile` は通常ファイルを指す必要があり、symlink は拒否されます） -- アクセス制御: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, トップレベル `bindings[]`（`type: "acp"`） -- exec 承認: `execApprovals`, `accounts.*.execApprovals` +- 起動/認証: `enabled`, `botToken`, `tokenFile`, `accounts.*`（`tokenFile`は通常ファイルを指している必要があります。シンボリックリンクは拒否されます） +- アクセス制御: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, トップレベルの`bindings[]`（`type: "acp"`） +- exec承認: `execApprovals`, `accounts.*.execApprovals` - コマンド/メニュー: `commands.native`, `commands.nativeSkills`, `customCommands` -- thread/返信: `replyToMode` +- スレッディング/返信: `replyToMode` - ストリーミング: `streaming`（プレビュー）、`blockStreaming` - 書式設定/配信: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - メディア/ネットワーク: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - アクション/機能: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - リアクション: `reactionNotifications`, `reactionLevel` - エラー: `errorPolicy`, `errorCooldownMs` @@ -1057,9 +1069,9 @@ Telegram 固有の重要フィールド: ## 関連 -- [ペアリング](/channels/pairing) -- [グループ](/channels/groups) -- [Security](/gateway/security) -- [チャネルルーティング](/channels/channel-routing) -- [マルチエージェントルーティング](/concepts/multi-agent) -- [トラブルシューティング](/channels/troubleshooting) +- [ペアリング](/ja-JP/channels/pairing) +- [グループ](/ja-JP/channels/groups) +- [セキュリティ](/ja-JP/gateway/security) +- [チャネルルーティング](/ja-JP/channels/channel-routing) +- [マルチagentルーティング](/ja-JP/concepts/multi-agent) +- [トラブルシューティング](/ja-JP/channels/troubleshooting) diff --git a/docs/ja-JP/concepts/qa-e2e-automation.md b/docs/ja-JP/concepts/qa-e2e-automation.md index 6e309bb23..68bc2e81d 100644 --- a/docs/ja-JP/concepts/qa-e2e-automation.md +++ b/docs/ja-JP/concepts/qa-e2e-automation.md @@ -1,38 +1,37 @@ --- read_when: - qa-labまたはqa-channelの拡張 - - リポジトリ連動のQAシナリオの追加 - - Gatewayダッシュボードを中心に、より現実に近いQA自動化を構築する -summary: qa-lab、qa-channel、シード済みシナリオ、プロトコルレポート向けの非公開QA自動化の構成 + - リポジトリに裏付けられたQAシナリオの追加 + - Gatewayダッシュボードを中心に、より現実に即したQA自動化を構築する +summary: qa-lab、qa-channel、シード済みシナリオ、およびプロトコルレポート向けの非公開QA自動化の構成 title: QA E2E自動化 x-i18n: - generated_at: "2026-04-18T04:40:10Z" + generated_at: "2026-04-20T04:46:32Z" model: gpt-5.4 provider: openai - source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 + source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # QA E2E自動化 -非公開のQAスタックは、単一のユニットテストよりも現実的で、 -チャネルに近い形でOpenClawを検証することを目的としています。 +非公開QAスタックは、単一のユニットテストよりも、より現実的で +チャネルに即した形でOpenClawを検証することを目的としています。 現在の構成要素: - `extensions/qa-channel`: DM、チャネル、スレッド、 - リアクション、編集、削除の各操作面を備えた合成メッセージチャネル。 -- `extensions/qa-lab`: トランスクリプトの観測、 - 受信メッセージの注入、Markdownレポートのエクスポートを行うための - デバッガーUIとQAバス。 + リアクション、編集、削除の各サーフェスを備えた合成メッセージチャネル。 +- `extensions/qa-lab`: トランスクリプトの観察、 + 受信メッセージの注入、Markdownレポートのエクスポートを行うためのデバッガUIとQAバス。 - `qa/`: キックオフタスクとベースラインQA - シナリオ向けの、リポジトリ連動のシードアセット。 + シナリオ向けの、リポジトリに裏付けられたシードアセット。 -現在のQAオペレーターのフローは、2ペイン構成のQAサイトです: +現在のQAオペレーターフローは、2ペインのQAサイトです: -- 左: エージェントを表示するGatewayダッシュボード（Control UI）。 -- 右: Slack風のトランスクリプトとシナリオプランを表示するQA Lab。 +- 左: エージェントを備えたGatewayダッシュボード（Control UI）。 +- 右: Slack風のトランスクリプトとシナリオ計画を表示するQA Lab。 次のコマンドで実行します: @@ -41,13 +40,12 @@ pnpm qa:lab:up ``` これによりQAサイトがビルドされ、Dockerベースのgatewayレーンが起動し、 -オペレーターまたは自動化ループがエージェントにQA -ミッションを与え、実際のチャネル動作を観察し、何が機能したか、 -何が失敗したか、何がブロックされたままだったかを記録できる -QA Labページが公開されます。 +オペレーターまたは自動化ループがエージェントにQAミッションを与え、 +実際のチャネル動作を観察し、何が機能したか、何が失敗したか、 +何がブロックされたままだったかを記録できるQA Labページが公開されます。 -Dockerイメージを毎回再ビルドせずにQA Lab UIをより高速に反復開発するには、 -バインドマウントされたQA Labバンドルでスタックを起動します: +Dockerイメージを毎回再ビルドせずに、より高速にQA Lab UIを反復するには、 +bind mountしたQA Labバンドルでスタックを起動します: ```bash pnpm openclaw qa docker-build-image @@ -56,60 +54,61 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` は事前ビルド済みイメージ上でDockerサービスを維持し、 -`extensions/qa-lab/web/dist` を `qa-lab` コンテナにバインドマウントします。`qa:lab:watch` +`qa:lab:up:fast` は、Dockerサービスを事前ビルド済みイメージ上で維持し、 +`extensions/qa-lab/web/dist` を `qa-lab` コンテナにbind mountします。`qa:lab:watch` は変更時にそのバンドルを再ビルドし、QA Labアセットのハッシュが変わると -ブラウザは自動的にリロードされます。 +ブラウザは自動リロードされます。 -実際のトランスポートを使うMatrixスモークレーンを実行するには、次を使います: +トランスポート実体のあるMatrixスモークレーンを実行するには、次を実行します: ```bash pnpm openclaw qa matrix ``` -このレーンは、使い捨てのTuwunel homeserverをDockerで用意し、 +このレーンは、Docker内に使い捨てのTuwunel homeserverをプロビジョニングし、 一時的なdriver、SUT、observerユーザーを登録し、1つのプライベートルームを作成してから、 -実際のMatrix pluginをQA gateway child内で実行します。ライブトランスポートレーンは、 -child設定をテスト対象のトランスポートに限定して保つため、 -child設定内では `qa-channel` なしでMatrixが動作します。構造化レポートアーティファクトと、 -stdout/stderrをまとめたログを、選択したMatrix QA出力ディレクトリに書き出します。 +QA gateway child内で実際のMatrix pluginを実行します。ライブトランスポートレーンは、 +テスト対象のトランスポートにchild configのスコープを限定するため、Matrixは +child config内で`qa-channel`なしに実行されます。構造化レポートアーティファクトと、 +結合されたstdout/stderrログを、選択されたMatrix QA出力ディレクトリに書き込みます。 外側の `scripts/run-node.mjs` のビルド/ランチャー出力も取得するには、 -`OPENCLAW_RUN_NODE_OUTPUT_LOG=` をリポジトリ内のログファイルに設定します。 +`OPENCLAW_RUN_NODE_OUTPUT_LOG=` をリポジトリ内のログファイルに設定してください。 -実際のトランスポートを使うTelegramスモークレーンを実行するには、次を使います: +トランスポート実体のあるTelegramスモークレーンを実行するには、次を実行します: ```bash pnpm openclaw qa telegram ``` -このレーンは、使い捨てサーバーを用意する代わりに、 -実際の1つのプライベートTelegramグループを対象にします。必要なのは +このレーンは、使い捨てサーバーをプロビジョニングする代わりに、 +実在する1つのプライベートTelegramグループを対象にします。 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、 `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、 -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` と、 -同じプライベートグループ内にいる2つの異なるボットです。 -SUTボットにはTelegramユーザー名が必要で、 -ボット同士の観測は、両方のボットで -`@BotFather` の Bot-to-Bot Communication Mode が有効になっていると -最も安定して動作します。 +`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` +が必要で、さらに同じプライベートグループ内に2つの異なるbotが必要です。 +SUT botにはTelegramユーザー名が必要で、bot同士の観察は、 +両方のbotで `@BotFather` 内の Bot-to-Bot Communication Mode を +有効にしていると最もうまく機能します。 +いずれかのシナリオが失敗すると、このコマンドはゼロ以外の終了コードで終了します。 +終了コードを失敗にせずアーティファクトを取得したい場合は、`--allow-failures` を使用してください。 -ライブトランスポートレーンは現在、それぞれが独自のシナリオ一覧形式を発明する代わりに、 -より小さな1つの共通コントラクトを共有しています: +ライブトランスポートレーンは現在、各レーンが独自のシナリオリスト形式を +考案するのではなく、1つのより小さな共通コントラクトを共有しています: -`qa-channel` は依然として広範な合成プロダクト動作スイートであり、 +`qa-channel` は依然として幅広い合成プロダクト動作スイートであり、 ライブトランスポートのカバレッジマトリクスには含まれません。 -| レーン | Canary | メンションゲーティング | 許可リストブロック | トップレベル返信 | 再起動後の再開 | スレッドフォローアップ | スレッド分離 | リアクション観測 | ヘルプコマンド | -| -------- | ------ | ---------------------- | ------------------ | ---------------- | -------------- | ---------------------- | ------------ | ---------------- | -------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| レーン | Canary | メンションゲーティング | Allowlistブロック | トップレベル返信 | 再起動後の再開 | スレッド追従 | スレッド分離 | リアクション観察 | ヘルプコマンド | +| -------- | ------ | ---------------------- | ----------------- | ---------------- | -------------- | ------------ | ------------ | ---------------- | -------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -これにより、`qa-channel` は広範なプロダクト動作スイートとして維持されつつ、 -Matrix、Telegram、将来のライブトランスポートが、 -明示的な1つのトランスポートコントラクトのチェックリストを共有できます。 +これにより、`qa-channel` は幅広いプロダクト動作スイートとして維持される一方で、 +Matrix、Telegram、および今後のライブトランスポートは、明示的な +トランスポートコントラクトのチェックリストを共有します。 -QAパスにDockerを持ち込まずに、使い捨てのLinux VMレーンを実行するには、 -次を使います: +QAパスにDockerを持ち込まずに使い捨てのLinux VMレーンを実行するには、 +次を実行します: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline @@ -117,111 +116,107 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline これにより新しいMultipass guestが起動し、依存関係をインストールし、 guest内でOpenClawをビルドし、`qa suite` を実行してから、 -通常のQAレポートとサマリーをホスト上の `.artifacts/qa-e2e/...` にコピーして戻します。 +通常のQAレポートとサマリーをホスト上の `.artifacts/qa-e2e/...` に +コピーし戻します。 ホスト上の `qa suite` と同じシナリオ選択動作を再利用します。 -ホストとMultipassのsuite実行は、デフォルトで分離されたgateway workerを使って、 -選択された複数のシナリオを並列実行し、 -最大64 workerまたは選択シナリオ数のいずれか少ない方まで動作します。 -worker数を調整するには `--concurrency ` を使い、 -直列実行するには `--concurrency 1` を使います。 -ライブ実行では、guestに対して実用的なサポート済みQA認証入力が転送されます: -envベースのprovider key、QA live provider設定パス、 -および存在する場合は `CODEX_HOME` です。guestが -マウントされたワークスペース経由で書き戻せるように、 -`--output-dir` はリポジトリルート配下に保ってください。 +ホスト実行とMultipass suite実行はどちらも、選択された複数のシナリオを、 +分離されたgateway workerでデフォルトで並列実行します。`qa-channel` のデフォルト同時実行数は4で、 +選択されたシナリオ数を上限とします。worker数を調整するには +`--concurrency ` を使用し、直列実行には `--concurrency 1` を使用してください。 +いずれかのシナリオが失敗すると、このコマンドはゼロ以外の終了コードで終了します。 +終了コードを失敗にせずアーティファクトを取得したい場合は、`--allow-failures` を使用してください。 +ライブ実行では、guestで実用的なサポート対象のQA認証入力を転送します: +envベースのprovider key、QA live provider config path、そして +存在する場合は `CODEX_HOME` です。guestがマウントされたworkspace経由で +書き戻せるように、`--output-dir` はリポジトリルート配下に維持してください。 -## リポジトリ連動のシード +## リポジトリに裏付けられたシード シードアセットは `qa/` にあります: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -これらは意図的にgitに置かれており、QAプランが人間にも -エージェントにも見えるようになっています。 +これらは意図的にgitに置かれており、QA計画を人間と +エージェントの両方から可視にしています。 -`qa-lab` は汎用的なmarkdownランナーとして維持するべきです。各シナリオmarkdownファイルは -1回のテスト実行における信頼できる唯一の情報源であり、次を定義する必要があります: +`qa-lab` は汎用的なmarkdownランナーのままであるべきです。各シナリオmarkdownファイルは +1回のテスト実行における唯一の信頼できる情報源であり、次を定義する必要があります: - シナリオメタデータ -- 任意のカテゴリ、ケイパビリティ、レーン、リスクのメタデータ -- docsとcodeの参照 +- 任意のcategory、capability、lane、riskメタデータ +- docs参照とcode参照 - 任意のplugin要件 -- 任意のgateway設定パッチ +- 任意のgateway config patch - 実行可能な `qa-flow` -`qa-flow` を支える再利用可能なランタイム面は、 -汎用的かつ横断的なままで構いません。たとえば、markdownシナリオは、 -埋め込みControl UIをGatewayの `browser.request` seam経由で駆動する -ブラウザ側ヘルパーと、トランスポート側ヘルパーを組み合わせてもよく、 -そのために特別扱いのランナーを追加する必要はありません。 +`qa-flow` を支える再利用可能なランタイムサーフェスは、 +汎用的かつ横断的なままでかまいません。たとえば、markdownシナリオは、 +特別扱いのランナーを追加せずに、トランスポート側ヘルパーと、 +Gatewayの `browser.request` シームを通じて埋め込みControl UIを操作する +ブラウザ側ヘルパーを組み合わせることができます。 シナリオファイルは、ソースツリーのフォルダではなく、 -プロダクト機能ごとにグループ化するべきです。ファイルを移動しても -シナリオIDは安定したままにし、実装トレーサビリティには -`docsRefs` と `codeRefs` を使ってください。 +プロダクト機能ごとにグループ化するべきです。ファイルが移動してもシナリオIDは安定させ、 +実装のトレーサビリティには `docsRefs` と `codeRefs` を使用してください。 -ベースライン一覧は、次をカバーできる程度に広く保つべきです: +ベースライン一覧は、次をカバーできる程度に十分広く保つべきです: - DMとチャネルチャット - スレッド動作 - メッセージアクションのライフサイクル - Cronコールバック -- メモリの想起 +- メモリー再呼び出し - モデル切り替え - subagent handoff - リポジトリ読み取りとdocs読み取り -- Lobster Invadersのような小さなビルドタスク1件 +- Lobster Invadersのような小さなビルドタスク1つ ## Providerモックレーン `qa suite` には2つのローカルproviderモックレーンがあります: -- `mock-openai` はシナリオ認識型のOpenClawモックです。 - リポジトリ連動QAとパリティゲート向けの、 - デフォルトの決定的モックレーンのままです。 -- `aimock` は実験的なプロトコル、 - フィクスチャ、record/replay、chaosカバレッジ向けに - AIMockベースのproviderサーバーを起動します。これは追加的なものであり、 - `mock-openai` シナリオディスパッチャーを置き換えるものではありません。 +- `mock-openai` は、シナリオ認識型のOpenClawモックです。これは引き続き、 + リポジトリに裏付けられたQAとパリティゲート向けのデフォルトの決定的モックレーンです。 +- `aimock` は、実験的なプロトコル、 + フィクスチャ、record/replay、chaosカバレッジ向けに、AIMockベースのprovider serverを起動します。 + これは追加的なものであり、`mock-openai` のシナリオディスパッチャを置き換えるものではありません。 Providerレーン実装は `extensions/qa-lab/src/providers/` 配下にあります。 -各providerは、自身のデフォルト値、ローカルサーバー起動、 -gateway model設定、auth-profileステージング要件、 -およびlive/mockケイパビリティフラグを管理します。 +各providerは、それぞれのデフォルト、ローカルserver起動、gateway model config、 +auth-profileステージング要件、およびlive/mock capability flagsを所有します。 共有suiteコードとgatewayコードは、provider名で分岐するのではなく、 provider registryを経由してルーティングするべきです。 ## トランスポートアダプター -`qa-lab` はmarkdown QAシナリオ向けの汎用トランスポートseamを所有します。 -`qa-channel` はそのseam上の最初のアダプターですが、 -設計目標はより広いものです: -将来の実チャネルまたは合成チャネルは、 -トランスポート固有のQAランナーを追加するのではなく、 -同じsuite runnerに接続できるようにするべきです。 +`qa-lab` は、markdown QAシナリオ向けの汎用トランスポートシームを所有します。 +`qa-channel` はそのシーム上の最初のアダプターですが、設計対象はより広く、 +将来の実チャネルまたは合成チャネルも、トランスポート固有のQAランナーを追加するのではなく、 +同じsuite runnerに接続できるようにすることです。 -アーキテクチャレベルでの分担は次のとおりです: +アーキテクチャレベルでは、分担は次のとおりです: -- `qa-lab` は汎用シナリオ実行、worker並列性、アーティファクト書き出し、レポートを所有します。 -- トランスポートアダプターはgateway設定、readiness、受信および送信の観測、トランスポートアクション、正規化されたトランスポート状態を所有します。 -- `qa/scenarios/` 配下のmarkdownシナリオファイルがテスト実行を定義し、それを実行する再利用可能なランタイム面は `qa-lab` が提供します。 +- `qa-lab` は、汎用シナリオ実行、worker並列実行、アーティファクト書き込み、レポート作成を所有します。 +- トランスポートアダプターは、gateway config、readiness、受信と送信の観察、トランスポートアクション、正規化されたトランスポート状態を所有します。 +- `qa/scenarios/` 配下のmarkdownシナリオファイルがテスト実行を定義し、`qa-lab` はそれを実行するための再利用可能なランタイムサーフェスを提供します。 -新しいチャネルアダプター向けのメンテナー向け導入ガイダンスは +新しいチャネルアダプター向けの、メンテナー向け採用ガイダンスは [Testing](/ja-JP/help/testing#adding-a-channel-to-qa) にあります。 ## レポート -`qa-lab` は、観測されたバスタイムラインからMarkdownのプロトコルレポートを -エクスポートします。レポートは次に答えるべきです: +`qa-lab` は、観察されたバスタイムラインからMarkdownのプロトコルレポートを +エクスポートします。 +レポートは次の問いに答えるべきです: - 何が機能したか - 何が失敗したか - 何がブロックされたままだったか -- どのフォローアップシナリオを追加する価値があるか +- 追加する価値のあるフォローアップシナリオは何か -文字やスタイルのチェックについては、同じシナリオを複数のライブモデル参照で実行し、 -判定付きMarkdownレポートを書き出します: +キャラクターとスタイルのチェックでは、同じシナリオを複数のlive model参照に対して実行し、 +評価済みMarkdownレポートを書き出します: ```bash pnpm openclaw qa character-eval \ @@ -241,41 +236,37 @@ pnpm openclaw qa character-eval \ ``` このコマンドはDockerではなく、ローカルのQA gateway child processを実行します。 -character evalシナリオでは `SOUL.md` を通じてペルソナを設定し、 -その後チャット、ワークスペース支援、小さなファイルタスクのような -通常のユーザーターンを実行するべきです。 -候補モデルには、それが評価対象であることを伝えてはいけません。 -このコマンドは各完全トランスクリプトを保持し、基本的な実行統計を記録したうえで、 -judge modelにfast modeと `xhigh` reasoningで、 -自然さ、雰囲気、ユーモアに基づいて実行結果を順位付けさせます。 -providerを比較する際は `--blind-judge-models` を使ってください: -judgeプロンプトには依然としてすべてのトランスクリプトと実行ステータスが渡されますが、 -候補参照は `candidate-01` のような中立ラベルに置き換えられます。 -レポートは、解析後に順位を実際の参照へ対応付けて戻します。 -候補実行はデフォルトで `high` thinking、 -それをサポートするOpenAIモデルでは `xhigh` になります。 -特定の候補を上書きするには -`--model provider/model,thinking=` をインラインで使います。 -`--thinking ` は引き続きグローバルなフォールバックを設定し、 -古い `--model-thinking ` 形式も -互換性のため保持されています。 -OpenAI候補参照はデフォルトでfast modeとなるため、 -providerが対応している場合はpriority processingが使われます。 -単一の候補またはjudgeに上書きが必要な場合は、 +character evalシナリオでは、`SOUL.md` を通じてペルソナを設定し、その後にチャット、 +workspaceヘルプ、小さなファイルタスクなどの通常のユーザーターンを実行するべきです。 +候補modelには、評価されていることを伝えてはいけません。このコマンドは、 +各完全トランスクリプトを保持し、基本的な実行統計を記録し、その後judge modelに対して、 +`xhigh` 推論を伴うfast modeで、自然さ、雰囲気、ユーモアに基づいて +実行結果を順位付けするよう求めます。 +providerを比較する際は、`--blind-judge-models` を使用してください: +judgeプロンプトには引き続きすべてのトランスクリプトと実行ステータスが渡されますが、 +候補参照は `candidate-01` のような中立ラベルに置き換えられ、 +レポートは解析後にランキングを実際の参照へマッピングし戻します。 +候補実行のthinkingはデフォルトで `high` であり、対応するOpenAI modelでは `xhigh` になります。 +特定の候補をインラインで上書きするには、 +`--model provider/model,thinking=` を使用してください。`--thinking ` は +引き続きグローバルなフォールバックを設定し、従来の +`--model-thinking ` 形式も互換性のため維持されています。 +OpenAI候補参照はデフォルトでfast modeとなり、providerが対応している場合は +優先処理が使われます。単一の候補またはjudgeに対して上書きが必要な場合は、 `,fast`、`,no-fast`、または `,fast=false` をインラインで追加してください。 -すべての候補モデルに対してfast modeを強制的に有効にしたい場合にのみ -`--fast` を渡します。候補とjudgeの所要時間は -ベンチマーク分析のためレポートに記録されますが、 -judgeプロンプトでは速度で順位付けしないよう明示されています。 -候補実行とjudge model実行はどちらもデフォルトで並列数16です。 -providerの制限やローカルgatewayの負荷で実行が不安定になる場合は、 +すべての候補modelでfast modeを強制的にオンにしたい場合にのみ、`--fast` を渡してください。 +候補とjudgeの所要時間はベンチマーク分析のためレポートに記録されますが、 +judgeプロンプトでは、速度で順位付けしないよう明示しています。 +候補実行とjudge model実行は、どちらもデフォルトで同時実行数16です。 +provider制限やローカルgatewayの負荷によって実行が不安定になる場合は、 `--concurrency` または `--judge-concurrency` を下げてください。 -候補 `--model` が指定されない場合、character evalのデフォルトは +候補 `--model` が渡されない場合、character evalはデフォルトで `openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、 `anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、 `moonshot/kimi-k2.5`、 -`google/gemini-3.1-pro-preview` になります。 -judge `--judge-model` が指定されない場合、judgeのデフォルトは +`google/gemini-3.1-pro-preview` を使用します。 +候補 `--model` が渡されない場合に使用されます。 +`--judge-model` が渡されない場合、judgeのデフォルトは `openai/gpt-5.4,thinking=xhigh,fast` と `anthropic/claude-opus-4-6,thinking=high` です。 diff --git a/docs/ja-JP/gateway/configuration-reference.md b/docs/ja-JP/gateway/configuration-reference.md index 01c9c5fed..ee824a3b3 100644 --- a/docs/ja-JP/gateway/configuration-reference.md +++ b/docs/ja-JP/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - - 正確なフィールドレベルの設定の意味やデフォルト値が必要です - - channel、model、gateway、またはtoolの設定ブロックを検証しています -summary: core OpenClaw キー、デフォルト、および専用サブシステム参照へのリンクのための Gateway 設定リファレンス + - 正確なフィールドレベルの設定の意味またはデフォルト値が必要な場合 + - channel、model、gateway、または tool の設定ブロックを検証している場合 +summary: core OpenClaw のキー、デフォルト値、および専用サブシステム参照へのリンクのための Gateway 設定リファレンス title: 設定リファレンス x-i18n: - generated_at: "2026-04-18T04:40:12Z" + generated_at: "2026-04-20T04:46:30Z" model: gpt-5.4 provider: openai - source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f + source_hash: 22b10f1f133374cd29ef4a5ec4fb9c9938eb51184ad82e1aa2e5f6f7af58585e source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,54 +17,54 @@ x-i18n: `~/.openclaw/openclaw.json` のコア設定リファレンスです。タスク指向の概要については、[Configuration](/ja-JP/gateway/configuration) を参照してください。 -このページでは、主要な OpenClaw の設定サーフェスを扱い、サブシステムごとにさらに詳細な専用リファレンスがある場合はそちらへリンクします。このページでは、すべての channel/plugin が所有するコマンドカタログや、すべての詳細な memory/QMD ノブを 1 ページにインライン展開することは**意図していません**。 +このページでは、OpenClaw の主要な設定サーフェスを扱い、サブシステムごとにより詳細な専用リファレンスがある場合はそちらへのリンクを示します。1 つのページに、すべての channel/plugin 所有のコマンドカタログや、すべての詳細な memory/QMD のノブをインライン展開することは**目的としていません**。 -コード上の正となる情報: +コード上の真実: -- `openclaw config schema` は、検証と Control UI に使用されるライブ JSON Schema を出力し、利用可能な場合は bundled/plugin/channel メタデータもマージされます -- `config.schema.lookup` は、ドリルダウン用ツール向けに、パスでスコープされた 1 つのスキーマノードを返します -- `pnpm config:docs:check` / `pnpm config:docs:gen` は、設定ドキュメントのベースラインハッシュを現在のスキーマサーフェスと照合して検証します +- `openclaw config schema` は、検証と Control UI に使用されるライブ JSON Schema を出力し、利用可能な場合は bundled/plugin/channel のメタデータもマージされます +- `config.schema.lookup` は、ドリルダウン用ツール向けに、パスでスコープされた単一のスキーマノードを返します +- `pnpm config:docs:check` / `pnpm config:docs:gen` は、設定ドキュメントのベースラインハッシュを現在のスキーマサーフェスに対して検証します 専用の詳細リファレンス: - `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`、および `plugins.entries.memory-core.config.dreaming` 配下の dreaming 設定については [Memory configuration reference](/ja-JP/reference/memory-config) - 現在の built-in + bundled コマンドカタログについては [Slash Commands](/ja-JP/tools/slash-commands) -- channel 固有のコマンドサーフェスについては、それぞれの channel/plugin ページ +- channel 固有のコマンドサーフェスについては各 channel/plugin ページ -設定形式は **JSON5** です（コメントと末尾カンマを使用可能）。すべてのフィールドは任意です — OpenClaw は省略時に安全なデフォルトを使用します。 +設定形式は **JSON5** です（コメント + 末尾カンマ可）。すべてのフィールドは省略可能です — OpenClaw は省略時に安全なデフォルトを使用します。 --- ## Channels -各 channel は、その設定セクションが存在すると自動的に開始されます（`enabled: false` の場合を除く）。 +各 channel は、その設定セクションが存在すると自動的に起動します（`enabled: false` の場合を除く）。 -### DM とグループアクセス +### DM とグループのアクセス すべての channel は DM ポリシーとグループポリシーをサポートします: -| DM ポリシー | 動作 | -| -------------------- | -------------------------------------------------------------- | -| `pairing` (デフォルト) | 未知の送信者には 1 回限りのペアリングコードが送られ、owner の承認が必要 | -| `allowlist` | `allowFrom` 内の送信者のみ（またはペアリング済み許可ストア） | -| `open` | すべての受信 DM を許可（`allowFrom: ["*"]` が必要） | -| `disabled` | すべての受信 DM を無視 | +| DM ポリシー | 動作 | +| ------------------- | --------------------------------------------------------------- | +| `pairing` (デフォルト) | 不明な送信者には 1 回限りのペアリングコードが送られ、owner が承認する必要があります | +| `allowlist` | `allowFrom` 内の送信者のみ（またはペア済み allow ストア） | +| `open` | すべての受信 DM を許可（`allowFrom: ["*"]` が必要） | +| `disabled` | すべての受信 DM を無視 | -| グループポリシー | 動作 | -| ----------------------- | ------------------------------------------------------ | +| グループポリシー | 動作 | +| ------------------------ | ------------------------------------------------------ | | `allowlist` (デフォルト) | 設定済み allowlist に一致するグループのみ | -| `open` | グループ allowlist をバイパス（mention-gating は引き続き適用） | -| `disabled` | すべてのグループ/room メッセージをブロック | +| `open` | グループ allowlist をバイパス（mention-gating は引き続き適用） | +| `disabled` | すべてのグループ/room メッセージをブロック | `channels.defaults.groupPolicy` は、provider の `groupPolicy` が未設定のときのデフォルトを設定します。 -ペアリングコードの有効期限は 1 時間です。保留中の DM ペアリング要求は **channel ごとに 3 件** までです。 -provider ブロックが完全に存在しない場合（`channels.` がない場合）、実行時のグループポリシーは起動時警告付きで `allowlist`（fail-closed）にフォールバックします。 +ペアリングコードは 1 時間で期限切れになります。保留中の DM ペアリングリクエストは **channel ごとに 3 件**までです。 +provider ブロック自体が完全に欠落している場合（`channels.` が存在しない）、ランタイムのグループポリシーは起動時警告付きで `allowlist`（フェイルクローズ）にフォールバックします。 -### Channel model オーバーライド +### Channel model のオーバーライド -特定の channel ID を model に固定するには `channels.modelByChannel` を使用します。値には `provider/model` または設定済み model エイリアスを指定できます。この channel マッピングは、セッションに既に model オーバーライドがない場合（たとえば `/model` で設定された場合など）に適用されます。 +特定の channel ID を model に固定するには `channels.modelByChannel` を使用します。値には `provider/model` または設定済み model エイリアスを指定できます。この channel マッピングは、session にすでに model オーバーライドがない場合（たとえば `/model` で設定されたもの）に適用されます。 ```json5 { @@ -87,7 +87,7 @@ provider ブロックが完全に存在しない場合（`channels.` ### Channel のデフォルトと Heartbeat -provider 間で共有されるグループポリシーと Heartbeat の動作には `channels.defaults` を使用します: +provider 間で共有するグループポリシーおよび Heartbeat の動作には `channels.defaults` を使用します: ```json5 { @@ -106,14 +106,14 @@ provider 間で共有されるグループポリシーと Heartbeat の動作に ``` - `channels.defaults.groupPolicy`: provider レベルの `groupPolicy` が未設定のときのフォールバック用グループポリシー。 -- `channels.defaults.contextVisibility`: すべての channel に対するデフォルトの補足コンテキスト可視性モード。値: `all`（デフォルト、引用/スレッド/履歴コンテキストをすべて含む）、`allowlist`（allowlist に含まれる送信者からのコンテキストのみ含む）、`allowlist_quote`（allowlist と同じだが、明示的な quote/reply コンテキストは保持）。channel ごとのオーバーライド: `channels..contextVisibility`。 +- `channels.defaults.contextVisibility`: すべての channel に対するデフォルトの補足コンテキスト可視性モード。値: `all`（デフォルト、引用/スレッド/履歴のすべてのコンテキストを含める）、`allowlist`（allowlist 済み送信者からのコンテキストのみ含める）、`allowlist_quote`（allowlist と同じだが、明示的な quote/reply コンテキストは保持する）。channel ごとのオーバーライド: `channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`: 正常な channel ステータスを Heartbeat 出力に含めます。 - `channels.defaults.heartbeat.showAlerts`: 劣化/エラー状態のステータスを Heartbeat 出力に含めます。 -- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケータ形式の Heartbeat 出力を表示します。 +- `channels.defaults.heartbeat.useIndicator`: コンパクトなインジケーター形式の Heartbeat 出力を表示します。 ### WhatsApp -WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。リンク済みセッションが存在する場合、自動的に開始されます。 +WhatsApp は gateway の web channel（Baileys Web）経由で動作します。リンク済み session が存在すると自動的に起動します。 ```json5 { @@ -146,7 +146,7 @@ WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。 } ``` - + ```json5 { @@ -164,9 +164,9 @@ WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。 } ``` -- 送信コマンドは、`default` アカウントが存在する場合はデフォルトでそのアカウントを使用し、存在しない場合は設定済みアカウント id のうち最初のもの（ソート順）を使用します。 -- 任意の `channels.whatsapp.defaultAccount` は、設定済みアカウント id と一致する場合に、このフォールバックのデフォルトアカウント選択を上書きします。 -- 従来の単一アカウント Baileys auth dir は、`openclaw doctor` により `whatsapp/default` へ移行されます。 +- 送信コマンドは、`default` アカウントが存在する場合はそのアカウントをデフォルトで使用し、そうでない場合は最初に設定されたアカウント ID（ソート順）を使用します。 +- オプションの `channels.whatsapp.defaultAccount` は、設定済みアカウント ID と一致する場合、このフォールバックのデフォルトアカウント選択を上書きします。 +- 従来の単一アカウント Baileys auth dir は、`openclaw doctor` によって `whatsapp/default` に移行されます。 - アカウントごとのオーバーライド: `channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -225,13 +225,13 @@ WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。 } ``` -- Bot token: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。symlink は拒否されます）。デフォルトアカウントについては `TELEGRAM_BOT_TOKEN` がフォールバックです。 -- 任意の `channels.telegram.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 -- マルチアカウント構成（2 個以上のアカウント id）では、フォールバックルーティングを避けるため明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定してください。これが欠落または無効な場合、`openclaw doctor` が警告します。 -- `configWrites: false` は、Telegram から開始される設定書き込み（supergroup ID 移行、`/config set|unset`）をブロックします。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、forum topic 用の永続的な ACP bindings を設定します（`match.peer.id` には正規の `chatId:topic:topicId` を使用）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 +- Bot token: `channels.telegram.botToken` または `channels.telegram.tokenFile`（通常ファイルのみ。シンボリックリンクは拒否されます）。デフォルトアカウントについては `TELEGRAM_BOT_TOKEN` がフォールバックです。 +- オプションの `channels.telegram.defaultAccount` は、設定済みアカウント ID と一致する場合、デフォルトアカウント選択を上書きします。 +- 複数アカウント構成（2 つ以上のアカウント ID）では、フォールバックルーティングを避けるために明示的なデフォルト（`channels.telegram.defaultAccount` または `channels.telegram.accounts.default`）を設定してください。これが欠落または無効な場合、`openclaw doctor` が警告します。 +- `configWrites: false` は、Telegram 起点の設定書き込み（supergroup ID の移行、`/config set|unset`）をブロックします。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、forum topic 用の永続 ACP バインディングを設定します（`match.peer.id` では正規の `chatId:topic:topicId` を使用します）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) で共通です。 - Telegram のストリームプレビューは `sendMessage` + `editMessageText` を使用します（ダイレクトチャットとグループチャットの両方で動作）。 -- リトライポリシー: [Retry policy](/ja-JP/concepts/retry) を参照。 +- リトライポリシー: [Retry policy](/ja-JP/concepts/retry) を参照してください。 ### Discord @@ -334,35 +334,35 @@ WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。 ``` - Token: `channels.discord.token`。デフォルトアカウントのフォールバックとして `DISCORD_BOT_TOKEN` を使用します。 -- 明示的な Discord `token` を指定する直接の送信呼び出しでは、その呼び出しに対してその token を使用します。アカウントの retry/policy 設定は、アクティブな runtime snapshot で選択されたアカウントから引き続き取得されます。 -- 任意の `channels.discord.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 -- 配信ターゲットには `user:`（DM）または `channel:`（guild channel）を使用します。数値 ID 単体は拒否されます。 -- Guild slug は小文字で、空白は `-` に置き換えられます。channel キーには slug 化された名前を使用します（`#` なし）。guild ID を推奨します。 -- bot 自身が作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効化されます。bot へのメンションを含む bot メッセージのみ受け入れるには `allowBots: "mentions"` を使用します（自身のメッセージは引き続きフィルタされます）。 -- `channels.discord.guilds..ignoreOtherMentions`（および channel オーバーライド）は、別の user または role へのメンションはあるが bot へのメンションがないメッセージを破棄します（@everyone/@here は除く）。 +- 明示的な Discord `token` を指定して行う直接の送信呼び出しでは、その呼び出しにその token が使用されます。アカウントの retry/policy 設定は、アクティブなランタイムスナップショットで選択されたアカウントから引き続き取得されます。 +- オプションの `channels.discord.defaultAccount` は、設定済みアカウント ID と一致する場合、デフォルトアカウント選択を上書きします。 +- 配信先には `user:`（DM）または `channel:`（guild channel）を使用します。数値 ID 単体は拒否されます。 +- Guild slug は小文字で、スペースは `-` に置き換えられます。channel キーには slug 化された名前（`#` なし）を使用します。guild ID を優先してください。 +- bot が作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効になります。bot をメンションした bot メッセージのみ受け付けるには `allowBots: "mentions"` を使用します（自分自身のメッセージは引き続き除外されます）。 +- `channels.discord.guilds..ignoreOtherMentions`（および channel オーバーライド）は、他のユーザーまたは role をメンションしているが bot をメンションしていないメッセージを破棄します（@everyone/@here は除く）。 - `maxLinesPerMessage`（デフォルト 17）は、2000 文字未満でも縦に長いメッセージを分割します。 -- `channels.discord.threadBindings` は Discord の thread-bound ルーティングを制御します: - - `enabled`: thread-bound セッション機能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインドされた配信/ルーティング）に対する Discord オーバーライド +- `channels.discord.threadBindings` は Discord のスレッドバインドされたルーティングを制御します: + - `enabled`: スレッドバインドされた session 機能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインドされた配信/ルーティング）に対する Discord オーバーライド - `idleHours`: 非アクティブ時の自動 unfocus を時間単位で指定する Discord オーバーライド（`0` で無効） - `maxAgeHours`: ハードな最大経過時間を時間単位で指定する Discord オーバーライド（`0` で無効） - - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` の自動 thread 作成/バインドを有効にするオプトインスイッチ -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、channel と thread の永続的な ACP bindings を設定します（`match.peer.id` には channel/thread id を使用）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 + - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` の自動スレッド作成/バインドのオプトインスイッチ +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、channel とスレッドの永続 ACP バインディングを設定します（`match.peer.id` には channel/thread id を使用します）。フィールドの意味は [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) で共通です。 - `channels.discord.ui.components.accentColor` は、Discord components v2 コンテナのアクセントカラーを設定します。 -- `channels.discord.voice` は、Discord voice channel での会話と、任意の自動参加 + TTS オーバーライドを有効にします。 +- `channels.discord.voice` は、Discord voice channel での会話と、オプションの自動参加 + TTS オーバーライドを有効にします。 - `channels.discord.voice.daveEncryption` と `channels.discord.voice.decryptionFailureTolerance` は、`@discordjs/voice` の DAVE オプションにそのまま渡されます（デフォルトは `true` と `24`）。 -- OpenClaw はさらに、復号失敗が繰り返された後に voice セッションから退出して再参加することで、voice receive の回復も試みます。 -- `channels.discord.streaming` は正規の stream mode キーです。従来の `streamMode` と真偽値の `streaming` は自動移行されます。 -- `channels.discord.autoPresence` は runtime の可用性を bot presence にマッピングし（healthy => online、degraded => idle、exhausted => dnd）、任意のステータステキスト上書きも可能にします。 -- `channels.discord.dangerouslyAllowNameMatching` は、変更可能な name/tag マッチングを再有効化します（break-glass 互換モード）。 -- `channels.discord.execApprovals`: Discord ネイティブな exec 承認の配信と approver 認可。 +- OpenClaw はさらに、復号失敗が繰り返された後に voice session から退出して再参加することで、voice receive の回復も試みます。 +- `channels.discord.streaming` は正規のストリームモードキーです。従来の `streamMode` と真偽値の `streaming` は自動移行されます。 +- `channels.discord.autoPresence` はランタイムの可用性を bot presence にマッピングし（healthy => online、degraded => idle、exhausted => dnd）、オプションのステータステキスト上書きを許可します。 +- `channels.discord.dangerouslyAllowNameMatching` は、変更可能な name/tag マッチングを再有効化します（緊急用の互換モード）。 +- `channels.discord.execApprovals`: Discord ネイティブの exec 承認配信と approver 認可。 - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。auto モードでは、`approvers` または `commands.ownerAllowFrom` から approver を解決できる場合に exec 承認が有効になります。 - `approvers`: exec リクエストを承認できる Discord user ID。省略時は `commands.ownerAllowFrom` にフォールバックします。 - - `agentFilter`: 任意の agent ID allowlist。省略すると、すべての agent の承認を転送します。 - - `sessionFilter`: 任意の session キーパターン（部分文字列または regex）。 + - `agentFilter`: オプションの agent ID allowlist。省略するとすべての agent の承認を転送します。 + - `sessionFilter`: オプションの session キーパターン（部分文字列または regex）。 - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）は approver の DM に送信し、`"channel"` は元の channel に送信し、`"both"` は両方に送信します。target に `"channel"` が含まれる場合、ボタンを使用できるのは解決済み approver のみです。 - - `cleanupAfterResolve`: `true` の場合、承認、拒否、またはタイムアウト後に承認 DM を削除します。 + - `cleanupAfterResolve`: `true` の場合、承認・拒否・タイムアウト後に承認 DM を削除します。 -**リアクション通知モード:** `off`（なし）、`own`（bot 自身のメッセージ、デフォルト）、`all`（すべてのメッセージ）、`allowlist`（すべてのメッセージに対して `guilds..users` から）。 +**Reaction notification モード:** `off`（なし）、`own`（bot 自身のメッセージ、デフォルト）、`all`（すべてのメッセージ）、`allowlist`（すべてのメッセージのうち `guilds..users` に含まれるもの）。 ### Google Chat @@ -393,11 +393,11 @@ WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。 } ``` -- サービスアカウント JSON: インライン（`serviceAccount`）またはファイルベース（`serviceAccountFile`）。 -- サービスアカウント SecretRef（`serviceAccountRef`）もサポートされます。 -- 環境変数フォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 配信ターゲットには `spaces/` または `users/` を使用します。 -- `channels.googlechat.dangerouslyAllowNameMatching` は、変更可能な email principal マッチングを再有効化します（break-glass 互換モード）。 +- Service account JSON: インライン（`serviceAccount`）またはファイルベース（`serviceAccountFile`）。 +- Service account SecretRef（`serviceAccountRef`）もサポートされています。 +- 環境変数のフォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 +- 配信先には `spaces/` または `users/` を使用します。 +- `channels.googlechat.dangerouslyAllowNameMatching` は、変更可能な email principal マッチングを再有効化します（緊急用の互換モード）。 ### Slack @@ -467,27 +467,27 @@ WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。 - **Socket mode** には `botToken` と `appToken` の両方が必要です（デフォルトアカウントの環境変数フォールバックは `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 - **HTTP mode** には `botToken` と `signingSecret`（ルートまたはアカウントごと）が必要です。 - `botToken`、`appToken`、`signingSecret`、`userToken` は平文文字列または SecretRef オブジェクトを受け付けます。 -- Slack アカウント snapshot は、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、HTTP mode では `signingSecretStatus` などの資格情報ごとの source/status フィールドを公開します。`configured_unavailable` は、そのアカウントが SecretRef で設定されているが、現在の command/runtime パスでは secret 値を解決できなかったことを意味します。 -- `configWrites: false` は、Slack から開始される設定書き込みをブロックします。 -- 任意の `channels.slack.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 -- `channels.slack.streaming.mode` は正規の Slack stream mode キーです。`channels.slack.streaming.nativeTransport` は Slack のネイティブストリーミング転送を制御します。従来の `streamMode`、真偽値の `streaming`、および `nativeStreaming` は自動移行されます。 -- 配信ターゲットには `user:`（DM）または `channel:` を使用します。 +- Slack アカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、および HTTP mode では `signingSecretStatus` などの資格情報ごとの source/status フィールドを公開します。`configured_unavailable` は、そのアカウントが SecretRef によって設定されているが、現在の command/runtime パスでは secret 値を解決できなかったことを意味します。 +- `configWrites: false` は、Slack 起点の設定書き込みをブロックします。 +- オプションの `channels.slack.defaultAccount` は、設定済みアカウント ID と一致する場合、デフォルトアカウント選択を上書きします。 +- `channels.slack.streaming.mode` は正規の Slack ストリームモードキーです。`channels.slack.streaming.nativeTransport` は Slack のネイティブストリーミング転送を制御します。従来の `streamMode`、真偽値の `streaming`、および `nativeStreaming` は自動移行されます。 +- 配信先には `user:`（DM）または `channel:` を使用します。 -**リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 +**Reaction notification モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 -**スレッドセッション分離:** `thread.historyScope` はスレッド単位（デフォルト）または channel 共有です。`thread.inheritParent` は親 channel の transcript を新しいスレッドにコピーします。 +**Thread session 分離:** `thread.historyScope` はスレッドごと（デフォルト）または channel 全体で共有されます。`thread.inheritParent` は親 channel の transcript を新しいスレッドにコピーします。 -- Slack のネイティブストリーミングと Slack assistant スタイルの「is typing...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベル DM はデフォルトでスレッド外のままなので、スレッド形式のプレビューではなく `typingReaction` または通常配信を使用します。 -- `typingReaction` は、返信実行中に受信した Slack メッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` のような Slack 絵文字ショートコードを使用してください。 -- `channels.slack.execApprovals`: Slack ネイティブな exec 承認の配信と approver 認可。スキーマは Discord と同じです: `enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack user ID）、`agentFilter`、`sessionFilter`、`target`（`"dm"`、`"channel"`、または `"both"`）。 +- Slack ネイティブストリーミングと Slack assistant 風の「is typing...」スレッドステータスには reply thread のターゲットが必要です。トップレベル DM はデフォルトでスレッド外のままなので、スレッド風プレビューではなく `typingReaction` または通常配信を使用します。 +- `typingReaction` は、返信の実行中に受信した Slack メッセージへ一時的な reaction を追加し、完了時にそれを削除します。`"hourglass_flowing_sand"` のような Slack 絵文字ショートコードを使用してください。 +- `channels.slack.execApprovals`: Slack ネイティブの exec 承認配信と approver 認可。スキーマは Discord と同じです: `enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack user ID）、`agentFilter`、`sessionFilter`、および `target`（`"dm"`、`"channel"`、または `"both"`）。 -| アクショングループ | デフォルト | メモ | -| ------------------ | ---------- | ------------------------ | -| reactions | 有効 | リアクション + リアクション一覧 | -| messages | 有効 | 読み取り/送信/編集/削除 | -| pins | 有効 | ピン留め/解除/一覧 | -| memberInfo | 有効 | メンバー情報 | -| emojiList | 有効 | カスタム絵文字一覧 | +| Action group | デフォルト | 備考 | +| ------------ | ---------- | ---------------------- | +| reactions | 有効 | reaction の追加 + 一覧 | +| messages | 有効 | 読み取り/送信/編集/削除 | +| pins | 有効 | ピン留め/解除/一覧 | +| memberInfo | 有効 | メンバー情報 | +| emojiList | 有効 | カスタム絵文字一覧 | ### Mattermost @@ -511,7 +511,7 @@ Mattermost は Plugin として提供されます: `openclaw plugins install @op native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // リバースプロキシ/公開デプロイ用のオプションの明示 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,20 +521,18 @@ Mattermost は Plugin として提供されます: `openclaw plugins install @op } ``` -チャットモード: `oncall`（@-mention で応答、デフォルト）、`onmessage`（すべてのメッセージ）、`onchar`（トリガープレフィックスで始まるメッセージ）。 +Chat mode: `oncall`（@-mention に応答、デフォルト）、`onmessage`（すべてのメッセージ）、`onchar`（トリガープレフィックスで始まるメッセージ）。 Mattermost ネイティブコマンドが有効な場合: -- `commands.callbackPath` はフル URL ではなく、パスである必要があります（たとえば `/api/channels/mattermost/command`）。 -- `commands.callbackUrl` は OpenClaw Gateway エンドポイントに解決され、Mattermost サーバーから到達可能である必要があります。 -- ネイティブ slash callback は、slash command 登録時に Mattermost から返されるコマンドごとの token で認証されます。登録に失敗した場合、または有効化されたコマンドがない場合、OpenClaw は callback を次のエラーで拒否します: - `Unauthorized: invalid command token.` -- プライベート/tailnet/internal callback host の場合、Mattermost では `ServiceSettings.AllowedUntrustedInternalConnections` に callback host/domain を含める必要がある場合があります。 - フル URL ではなく host/domain 値を使用してください。 -- `channels.mattermost.configWrites`: Mattermost から開始される設定書き込みを許可または拒否します。 -- `channels.mattermost.requireMention`: channels で返信する前に `@mention` を必須にします。 -- `channels.mattermost.groups..requireMention`: channel ごとの mention-gating オーバーライド（デフォルトは `"*"`）。 -- 任意の `channels.mattermost.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 +- `commands.callbackPath` は完全な URL ではなくパスでなければなりません（例: `/api/channels/mattermost/command`）。 +- `commands.callbackUrl` は OpenClaw gateway エンドポイントを解決し、Mattermost サーバーから到達可能でなければなりません。 +- ネイティブ slash callback は、slash command 登録時に Mattermost から返されるコマンドごとの token で認証されます。登録に失敗した場合、または有効化されたコマンドがない場合、OpenClaw は callback を `Unauthorized: invalid command token.` で拒否します。 +- プライベート/tailnet/internal の callback host では、Mattermost が `ServiceSettings.AllowedUntrustedInternalConnections` に callback host/domain を含めることを要求する場合があります。完全な URL ではなく host/domain 値を使用してください。 +- `channels.mattermost.configWrites`: Mattermost 起点の設定書き込みを許可または拒否します。 +- `channels.mattermost.requireMention`: channel で返信する前に `@mention` を必要にします。 +- `channels.mattermost.groups..requireMention`: channel ごとの mention-gating オーバーライド（デフォルトには `"*"` を使用）。 +- オプションの `channels.mattermost.defaultAccount` は、設定済みアカウント ID と一致する場合、デフォルトアカウント選択を上書きします。 ### Signal @@ -543,7 +541,7 @@ Mattermost ネイティブコマンドが有効な場合: channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // オプションのアカウントバインディング dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -555,15 +553,15 @@ Mattermost ネイティブコマンドが有効な場合: } ``` -**リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 +**Reaction notification モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 - `channels.signal.account`: channel の起動を特定の Signal アカウント ID に固定します。 -- `channels.signal.configWrites`: Signal から開始される設定書き込みを許可または拒否します。 -- 任意の `channels.signal.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 +- `channels.signal.configWrites`: Signal 起点の設定書き込みを許可または拒否します。 +- オプションの `channels.signal.defaultAccount` は、設定済みアカウント ID と一致する場合、デフォルトアカウント選択を上書きします。 ### BlueBubbles -BlueBubbles は推奨される iMessage 経路です（Plugin ベースで、`channels.bluebubbles` 配下に設定します）。 +BlueBubbles は推奨される iMessage パスです（Plugin バックで、`channels.bluebubbles` 配下に設定します）。 ```json5 { @@ -579,13 +577,13 @@ BlueBubbles は推奨される iMessage 経路です（Plugin ベースで、`ch ``` - ここで扱うコアキーパス: `channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 任意の `channels.bluebubbles.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続的な ACP セッションにバインドできます。`match.peer.id` には BlueBubbles handle または target 文字列（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共通のフィールド意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 -- BlueBubbles channel の完全な設定は [BlueBubbles](/ja-JP/channels/bluebubbles) に記載されています。 +- オプションの `channels.bluebubbles.defaultAccount` は、設定済みアカウント ID と一致する場合、デフォルトアカウント選択を上書きします。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続 ACP session にバインドできます。`match.peer.id` には BlueBubbles handle またはターゲット文字列（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共有フィールドの意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 +- 完全な BlueBubbles channel 設定は [BlueBubbles](/ja-JP/channels/bluebubbles) に記載されています。 ### iMessage -OpenClaw は `imsg rpc`（stdio 上の JSON-RPC）を起動します。daemon や port は不要です。 +OpenClaw は `imsg rpc`（stdio 上の JSON-RPC）を起動します。デーモンやポートは不要です。 ```json5 { @@ -609,15 +607,15 @@ OpenClaw は `imsg rpc`（stdio 上の JSON-RPC）を起動します。daemon } ``` -- 任意の `channels.imessage.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 +- オプションの `channels.imessage.defaultAccount` は、設定済みアカウント ID と一致する場合、デフォルトアカウント選択を上書きします。 - Messages DB へのフルディスクアクセスが必要です。 -- `chat_id:` ターゲットを推奨します。チャット一覧は `imsg chats --limit 20` を使用してください。 -- `cliPath` は SSH ラッパーを指すことができます。添付ファイルを SCP で取得するには `remoteHost`（`host` または `user@host`）を設定してください。 +- `chat_id:` ターゲットを推奨します。チャット一覧を表示するには `imsg chats --limit 20` を使用してください。 +- `cliPath` は SSH ラッパーを指すことができます。SCP で添付ファイルを取得するには `remoteHost`（`host` または `user@host`）を設定します。 - `attachmentRoots` と `remoteAttachmentRoots` は受信添付ファイルのパスを制限します（デフォルト: `/Users/*/Library/Messages/Attachments`）。 -- SCP は厳格な host-key 検証を使用するため、relay host key がすでに `~/.ssh/known_hosts` に存在していることを確認してください。 -- `channels.imessage.configWrites`: iMessage から開始される設定書き込みを許可または拒否します。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続的な ACP セッションにバインドできます。`match.peer.id` には正規化された handle または明示的な chat target（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共通のフィールド意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 +- SCP は厳格な host-key チェックを使用するため、relay host key がすでに `~/.ssh/known_hosts` に存在することを確認してください。 +- `channels.imessage.configWrites`: iMessage 起点の設定書き込みを許可または拒否します。 +- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続 ACP session にバインドできます。`match.peer.id` には正規化された handle または明示的な chat ターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共有フィールドの意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 @@ -630,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix は extension ベースで、`channels.matrix` 配下に設定します。 +Matrix は extension バックで、`channels.matrix` 配下に設定します。 ```json5 { @@ -660,25 +658,25 @@ Matrix は extension ベースで、`channels.matrix` 配下に設定します } ``` -- token 認証は `accessToken` を使用し、password 認証は `userId` + `password` を使用します。 -- `channels.matrix.proxy` は Matrix の HTTP トラフィックを明示的な HTTP(S) プロキシ経由にルーティングします。名前付きアカウントでは `channels.matrix.accounts..proxy` で上書きできます。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` は private/internal homeserver を許可します。`proxy` とこの network オプトインは独立した制御です。 -- `channels.matrix.defaultAccount` は、マルチアカウント構成で優先アカウントを選択します。 -- `channels.matrix.autoJoin` のデフォルトは `off` であるため、招待された room と新しい DM 形式の招待は、`autoJoin: "allowlist"` と `autoJoinAllowlist` を設定するか、`autoJoin: "always"` を設定するまで無視されます。 -- `channels.matrix.execApprovals`: Matrix ネイティブな exec 承認の配信と approver 認可。 +- Token 認証は `accessToken` を使用します。password 認証は `userId` + `password` を使用します。 +- `channels.matrix.proxy` は Matrix HTTP トラフィックを明示的な HTTP(S) proxy 経由にします。名前付きアカウントは `channels.matrix.accounts..proxy` でこれを上書きできます。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` はプライベート/内部 homeserver を許可します。`proxy` とこの network オプトインは独立した制御です。 +- `channels.matrix.defaultAccount` は、複数アカウント構成で優先アカウントを選択します。 +- `channels.matrix.autoJoin` のデフォルトは `off` なので、`autoJoin: "allowlist"` と `autoJoinAllowlist`、または `autoJoin: "always"` を設定するまで、招待された room や新しい DM 形式の招待は無視されます。 +- `channels.matrix.execApprovals`: Matrix ネイティブの exec 承認配信と approver 認可。 - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。auto モードでは、`approvers` または `commands.ownerAllowFrom` から approver を解決できる場合に exec 承認が有効になります。 - `approvers`: exec リクエストを承認できる Matrix user ID（例: `@owner:example.org`）。 - - `agentFilter`: 任意の agent ID allowlist。省略すると、すべての agent の承認を転送します。 - - `sessionFilter`: 任意の session キーパターン（部分文字列または regex）。 - - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）、`"channel"`（送信元 room）、または `"both"`。 + - `agentFilter`: オプションの agent ID allowlist。省略するとすべての agent の承認を転送します。 + - `sessionFilter`: オプションの session キーパターン（部分文字列または regex）。 + - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）、`"channel"`（元の room）、または `"both"`。 - アカウントごとのオーバーライド: `channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` は、Matrix DM をどのようにセッションにまとめるかを制御します: `per-user`（デフォルト）はルーティングされた peer ごとに共有し、`per-room` は各 DM room を分離します。 -- Matrix のステータス probe とライブ directory lookup は、runtime トラフィックと同じ proxy ポリシーを使用します。 -- Matrix の完全な設定、ターゲティングルール、セットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 +- `channels.matrix.dm.sessionScope` は Matrix DM がどのように session にまとまるかを制御します: `per-user`（デフォルト）はルーティングされた peer ごとに共有し、`per-room` は各 DM room を分離します。 +- Matrix のステータス probe とライブディレクトリ検索は、ランタイムトラフィックと同じ proxy ポリシーを使用します。 +- 完全な Matrix 設定、ターゲティングルール、およびセットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 ### Microsoft Teams -Microsoft Teams は extension ベースで、`channels.msteams` 配下に設定します。 +Microsoft Teams は extension バックで、`channels.msteams` 配下に設定します。 ```json5 { @@ -694,11 +692,11 @@ Microsoft Teams は extension ベースで、`channels.msteams` 配下に設定 ``` - ここで扱うコアキーパス: `channels.msteams`、`channels.msteams.configWrites`。 -- Teams の完全な設定（資格情報、webhook、DM/グループポリシー、team ごと/channel ごとのオーバーライド）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 +- 完全な Teams 設定（資格情報、webhook、DM/グループポリシー、team/channel ごとのオーバーライド）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 ### IRC -IRC は extension ベースで、`channels.irc` 配下に設定します。 +IRC は extension バックで、`channels.irc` 配下に設定します。 ```json5 { @@ -720,12 +718,12 @@ IRC は extension ベースで、`channels.irc` 配下に設定します。 ``` - ここで扱うコアキーパス: `channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 任意の `channels.irc.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 -- IRC channel の完全な設定（host/port/TLS/channels/allowlists/mention gating）は [IRC](/ja-JP/channels/irc) に記載されています。 +- オプションの `channels.irc.defaultAccount` は、設定済みアカウント ID と一致する場合、デフォルトアカウント選択を上書きします。 +- 完全な IRC channel 設定（host/port/TLS/channels/allowlist/mention gating）は [IRC](/ja-JP/channels/irc) に記載されています。 -### マルチアカウント（すべての channels） +### 複数アカウント（すべての channel） -channel ごとに複数のアカウントを実行できます（それぞれに独自の `accountId` を持ちます）: +channel ごとに複数のアカウントを実行できます（各アカウントは独自の `accountId` を持ちます）: ```json5 { @@ -746,28 +744,28 @@ channel ごとに複数のアカウントを実行できます（それぞれに } ``` -- `accountId` が省略された場合は `default` が使用されます（CLI + routing）。 -- 環境変数 token は **default** アカウントにのみ適用されます。 +- `default` は `accountId` が省略された場合に使用されます（CLI + ルーティング）。 +- 環境変数の token は **default** アカウントにのみ適用されます。 - ベース channel 設定は、アカウントごとに上書きされない限り、すべてのアカウントに適用されます。 - 各アカウントを別の agent にルーティングするには `bindings[].match.accountId` を使用します。 -- まだ単一アカウントのトップレベル channel 設定のまま `openclaw channels add`（または channel オンボーディング）で非デフォルトアカウントを追加すると、OpenClaw はまずアカウントスコープのトップレベル単一アカウント値を channel の account map に昇格させ、元のアカウントが引き続き動作するようにします。多くの channels ではそれらを `channels..accounts.default` に移動しますが、Matrix は既存の一致する named/default target を代わりに保持できます。 -- 既存の channel のみ対象の bindings（`accountId` なし）は引き続きデフォルトアカウントにマッチします。アカウントスコープの bindings は引き続き任意です。 -- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値をその channel 用に選ばれた昇格先アカウントへ移動することで、混在した形状を修復します。多くの channels では `accounts.default` を使用しますが、Matrix は既存の一致する named/default target を代わりに保持できます。 +- まだ単一アカウントのトップレベル channel 設定のままで `openclaw channels add`（または channel オンボーディング）を使って非 default アカウントを追加すると、OpenClaw は元のアカウントが引き続き動作するよう、まずアカウントスコープのトップレベル単一アカウント値を channel のアカウントマップへ昇格させます。ほとんどの channel ではこれらを `channels..accounts.default` に移動します。Matrix は代わりに既存の一致する named/default ターゲットを保持できます。 +- 既存の channel のみの binding（`accountId` なし）は default アカウントに引き続き一致します。アカウントスコープの binding は引き続きオプションです。 +- `openclaw doctor --fix` も、各 channel に対して選ばれた昇格先アカウントにアカウントスコープのトップレベル単一アカウント値を移動することで、混在した形状を修復します。ほとんどの channel では `accounts.default` を使います。Matrix は代わりに既存の一致する named/default ターゲットを保持できます。 -### その他の extension channels +### その他の extension channel -多くの extension channel は `channels.` として設定され、専用の channel ページに記載されています（たとえば Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 -完全な channel 一覧は [Channels](/ja-JP/channels) を参照してください。 +多くの extension channel は `channels.` として設定され、専用の channel ページに記載されています（例: Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 +完全な channel インデックスは [Channels](/ja-JP/channels) を参照してください。 -### グループチャットの mention gating +### グループチャットのメンションゲーティング -グループメッセージはデフォルトで **mention 必須** です（メタデータ mention または安全な regex パターン）。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。 +グループメッセージはデフォルトで **メンション必須** です（メタデータメンションまたは安全な regex パターン）。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。 -**mention の種類:** +**メンションの種類:** -- **メタデータ mention**: ネイティブプラットフォームの @-mention。WhatsApp の self-chat mode では無視されます。 -- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` 内の安全な regex パターン。無効なパターンや安全でないネスト反復は無視されます。 -- mention gating は、検出が可能な場合にのみ適用されます（ネイティブ mention または少なくとも 1 つのパターンがある場合）。 +- **メタデータメンション**: ネイティブのプラットフォーム @-mention。WhatsApp の self-chat mode では無視されます。 +- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` にある安全な regex パターン。無効なパターンや安全でないネスト反復は無視されます。 +- メンションゲーティングは、検出が可能な場合にのみ適用されます（ネイティブメンションまたは少なくとも 1 つのパターンがある場合）。 ```json5 { @@ -780,7 +778,7 @@ channel ごとに複数のアカウントを実行できます（それぞれに } ``` -`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。channels は `channels..historyLimit`（またはアカウントごと）で上書きできます。無効にするには `0` を設定してください。 +`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。channel は `channels..historyLimit`（またはアカウントごと）で上書きできます。無効にするには `0` を設定します。 #### DM 履歴制限 @@ -797,13 +795,13 @@ channel ごとに複数のアカウントを実行できます（それぞれに } ``` -解決順序: DM ごとのオーバーライド → provider デフォルト → 制限なし（すべて保持）。 +解決順: DM ごとのオーバーライド → provider デフォルト → 制限なし（すべて保持）。 -対応: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 +サポート対象: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### Self-chat mode -自分の電話番号を `allowFrom` に含めると self-chat mode が有効になります（ネイティブ @-mention を無視し、テキストパターンにのみ応答します）: +自分の番号を `allowFrom` に含めると self-chat mode が有効になります（ネイティブの @-mention を無視し、テキストパターンにのみ応答します）: ```json5 { @@ -829,16 +827,16 @@ channel ごとに複数のアカウントを実行できます（それぞれに ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // supported の場合はネイティブコマンドを登録 + nativeSkills: "auto", // supported の場合はネイティブ skill コマンドを登録 + text: true, // チャットメッセージ内の /commands を解析 + bash: false, // ! を許可（別名: /bash） bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // /config を許可 + mcp: false, // /mcp を許可 + plugins: false, // /plugins を許可 + debug: false, // /debug を許可 + restart: true, // /restart + gateway restart tool を許可 ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -853,28 +851,28 @@ channel ごとに複数のアカウントを実行できます（それぞれに -- このブロックはコマンドサーフェスを設定します。現在の built-in + bundled コマンドカタログについては [Slash Commands](/ja-JP/tools/slash-commands) を参照してください。 -- このページは**設定キーのリファレンス**であり、完全なコマンドカタログではありません。QQ Bot の `/bot-ping` `/bot-help` `/bot-logs`、LINE の `/card`、device-pair の `/pair`、memory の `/dreaming`、phone-control の `/phone`、Talk の `/voice` など、channel/plugin が所有するコマンドは、それぞれの channel/plugin ページと [Slash Commands](/ja-JP/tools/slash-commands) に記載されています。 -- テキストコマンドは、先頭に `/` が付いた**単独の**メッセージである必要があります。 -- `native: "auto"` は Discord/Telegram のネイティブコマンドを有効にし、Slack は無効のままにします。 -- `nativeSkills: "auto"` は Discord/Telegram のネイティブ Skills コマンドを有効にし、Slack は無効のままにします。 -- channel ごとの上書き: `channels.discord.commands.native`（bool または `"auto"`）。`false` は以前に登録されたコマンドをクリアします。 -- ネイティブ Skills 登録は `channels..commands.nativeSkills` で channel ごとに上書きできます。 -- `channels.telegram.customCommands` は追加の Telegram bot メニュー項目を追加します。 -- `bash: true` はホストシェル向けの `! ` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.` に含まれていることが必要です。 -- `config: true` は `/config` を有効にします（`openclaw.json` を読み書きします）。Gateway の `chat.send` クライアントでは、永続的な `/config set|unset` 書き込みには `operator.admin` も必要です。読み取り専用の `/config show` は通常の write スコープ operator クライアントでも引き続き利用できます。 -- `mcp: true` は、`mcp.servers` 配下の OpenClaw 管理 MCP サーバー設定向けに `/mcp` を有効にします。 -- `plugins: true` は、Plugin の検出、インストール、有効化/無効化制御のための `/plugins` を有効にします。 -- `channels..configWrites` は、channel ごとの設定変更を制御します（デフォルト: true）。 -- マルチアカウント channels では、`channels..accounts..configWrites` も、そのアカウントを対象とする書き込み（たとえば `/allowlist --config --account ` や `/config set channels..accounts....`）を制御します。 -- `restart: false` は `/restart` と Gateway 再起動 tool アクションを無効にします。デフォルト: `true`。 -- `ownerAllowFrom` は、owner 専用コマンド/tool 用の明示的な owner allowlist です。`allowFrom` とは別です。 -- `ownerDisplay: "hash"` は system prompt 内の owner id をハッシュ化します。ハッシュ化の制御には `ownerDisplaySecret` を設定してください。 -- `allowFrom` は provider ごとです。設定すると、それが**唯一の**認可ソースになります（channel allowlist/pairing と `useAccessGroups` は無視されます）。 -- `useAccessGroups: false` は、`allowFrom` が設定されていない場合に、コマンドが access-group ポリシーをバイパスできるようにします。 -- コマンドドキュメントの対応先: +- このブロックは command サーフェスを設定します。現在の built-in + bundled コマンドカタログについては [Slash Commands](/ja-JP/tools/slash-commands) を参照してください。 +- このページは**設定キーのリファレンス**であり、完全なコマンドカタログではありません。QQ Bot の `/bot-ping` `/bot-help` `/bot-logs`、LINE の `/card`、device-pair の `/pair`、memory の `/dreaming`、phone-control の `/phone`、Talk の `/voice` などの channel/plugin 所有コマンドは、それぞれの channel/plugin ページおよび [Slash Commands](/ja-JP/tools/slash-commands) に記載されています。 +- テキストコマンドは、先頭に `/` が付いた**単独の**メッセージでなければなりません。 +- `native: "auto"` は Discord/Telegram ではネイティブコマンドを有効にし、Slack では無効のままにします。 +- `nativeSkills: "auto"` は Discord/Telegram ではネイティブ skill コマンドを有効にし、Slack では無効のままにします。 +- channel ごとのオーバーライド: `channels.discord.commands.native`（bool または `"auto"`）。`false` は以前に登録されたコマンドをクリアします。 +- ネイティブ skill 登録は `channels..commands.nativeSkills` で channel ごとにオーバーライドできます。 +- `channels.telegram.customCommands` は Telegram bot メニューに追加エントリを加えます。 +- `bash: true` は host shell に対する `! ` を有効にします。`tools.elevated.enabled` と、送信者が `tools.elevated.allowFrom.` に含まれていることが必要です。 +- `config: true` は `/config` を有効にします（`openclaw.json` を読み書きします）。gateway `chat.send` クライアントでは、永続的な `/config set|unset` 書き込みには `operator.admin` も必要です。読み取り専用の `/config show` は通常の書き込みスコープを持つ operator クライアントでも引き続き利用できます。 +- `mcp: true` は `mcp.servers` 配下の OpenClaw 管理 MCP server 設定用の `/mcp` を有効にします。 +- `plugins: true` は Plugin の検出、インストール、有効化/無効化の制御用の `/plugins` を有効にします。 +- `channels..configWrites` は channel ごとの設定変更を制御します（デフォルト: true）。 +- 複数アカウント channel では、`channels..accounts..configWrites` も、そのアカウントを対象とする書き込み（たとえば `/allowlist --config --account ` や `/config set channels..accounts....`）を制御します。 +- `restart: false` は `/restart` と gateway restart tool のアクションを無効にします。デフォルト: `true`。 +- `ownerAllowFrom` は、owner 専用 command/tool のための明示的な owner allowlist です。`allowFrom` とは別です。 +- `ownerDisplay: "hash"` は system prompt 内の owner ID をハッシュ化します。ハッシュ化を制御するには `ownerDisplaySecret` を設定します。 +- `allowFrom` は provider ごとです。設定されている場合、それが**唯一の**認可ソースになります（channel allowlist/pairing と `useAccessGroups` は無視されます）。 +- `useAccessGroups: false` は、`allowFrom` が設定されていない場合に command が access-group ポリシーをバイパスできるようにします。 +- コマンドドキュメントの対応: - built-in + bundled カタログ: [Slash Commands](/ja-JP/tools/slash-commands) - - channel 固有のコマンドサーフェス: [Channels](/ja-JP/channels) + - channel 固有の command サーフェス: [Channels](/ja-JP/channels) - QQ Bot コマンド: [QQ Bot](/ja-JP/channels/qqbot) - pairing コマンド: [Pairing](/ja-JP/channels/pairing) - LINE card コマンド: [LINE](/ja-JP/channels/line) @@ -898,7 +896,7 @@ channel ごとに複数のアカウントを実行できます（それぞれに ### `agents.defaults.repoRoot` -system prompt の Runtime 行に表示される任意のリポジトリルートです。未設定の場合、OpenClaw は workspace から上方向にたどって自動検出します。 +system prompt の Runtime 行に表示されるオプションのリポジトリルートです。未設定の場合、OpenClaw は workspace から上位へたどって自動検出します。 ```json5 { @@ -908,7 +906,7 @@ system prompt の Runtime 行に表示される任意のリポジトリルート ### `agents.defaults.skills` -`agents.list[].skills` を設定していない agent 向けの、任意のデフォルト Skills allowlist です。 +`agents.list[].skills` を設定していない agent に対する、オプションのデフォルト skill allowlist です。 ```json5 { @@ -916,17 +914,17 @@ system prompt の Runtime 行に表示される任意のリポジトリルート defaults: { skills: ["github", "weather"] }, list: [ { id: "writer" }, // github, weather を継承 - { id: "docs", skills: ["docs-search"] }, // デフォルトを置き換え - { id: "locked-down", skills: [] }, // Skills なし + { id: "docs", skills: ["docs-search"] }, // デフォルトを置き換える + { id: "locked-down", skills: [] }, // skills なし ], }, } ``` -- デフォルトで Skills を無制限にするには `agents.defaults.skills` を省略します。 +- デフォルトで無制限の skills にするには `agents.defaults.skills` を省略します。 - デフォルトを継承するには `agents.list[].skills` を省略します。 -- Skills なしにするには `agents.list[].skills: []` を設定します。 -- 空でない `agents.list[].skills` リストは、その agent の最終セットです。デフォルトとはマージされません。 +- skills をなしにするには `agents.list[].skills: []` を設定します。 +- 空でない `agents.list[].skills` リストはその agent の最終セットであり、デフォルトとはマージされません。 ### `agents.defaults.skipBootstrap` @@ -940,9 +938,9 @@ workspace bootstrap ファイル（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENT ### `agents.defaults.contextInjection` -workspace bootstrap ファイルを system prompt に注入するタイミングを制御します。デフォルト: `"always"`。 +workspace bootstrap ファイルをいつ system prompt に注入するかを制御します。デフォルト: `"always"`。 -- `"continuation-skip"`: 安全な継続ターン（assistant の応答完了後）では workspace bootstrap の再注入をスキップし、prompt サイズを削減します。Heartbeat 実行と post-Compaction リトライでは引き続きコンテキストを再構築します。 +- `"continuation-skip"`: 安全な継続ターン（assistant の応答完了後）では workspace bootstrap の再注入をスキップし、prompt サイズを削減します。Heartbeat 実行と Compaction 後の再試行では引き続きコンテキストを再構築します。 ```json5 { @@ -952,7 +950,7 @@ workspace bootstrap ファイルを system prompt に注入するタイミング ### `agents.defaults.bootstrapMaxChars` -切り詰め前の、workspace bootstrap ファイルごとの最大文字数。デフォルト: `12000`。 +切り詰め前の workspace bootstrap ファイルごとの最大文字数です。デフォルト: `12000`。 ```json5 { @@ -962,7 +960,7 @@ workspace bootstrap ファイルを system prompt に注入するタイミング ### `agents.defaults.bootstrapTotalMaxChars` -すべての workspace bootstrap ファイルで注入される合計最大文字数。デフォルト: `60000`。 +すべての workspace bootstrap ファイルにまたがって注入される総文字数の上限です。デフォルト: `60000`。 ```json5 { @@ -972,12 +970,12 @@ workspace bootstrap ファイルを system prompt に注入するタイミング ### `agents.defaults.bootstrapPromptTruncationWarning` -bootstrap コンテキストが切り詰められたときの、agent に見える警告テキストを制御します。 +bootstrap コンテキストが切り詰められたときに agent に見える警告テキストを制御します。 デフォルト: `"once"`。 -- `"off"`: 警告テキストを system prompt に一切注入しません。 +- `"off"`: system prompt に警告テキストを一切注入しません。 - `"once"`: 一意の切り詰めシグネチャごとに 1 回だけ警告を注入します（推奨）。 -- `"always"`: 切り詰めが存在する場合は毎回警告を注入します。 +- `"always"`: 切り詰めが存在する場合、毎回の実行で警告を注入します。 ```json5 { @@ -987,28 +985,28 @@ bootstrap コンテキストが切り詰められたときの、agent に見え ### コンテキスト予算の所有マップ -OpenClaw には複数の大容量 prompt/context 予算があり、それらは 1 つの汎用ノブにすべて流し込むのではなく、意図的にサブシステムごとに分割されています。 +OpenClaw には大量の prompt/context 予算が複数あり、すべてを 1 つの汎用ノブに流し込むのではなく、意図的にサブシステムごとに分割されています。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: 通常の workspace bootstrap 注入。 - `agents.defaults.startupContext.*`: - 最近の daily `memory/*.md` ファイルを含む、単発の `/new` および `/reset` 起動プレリュード。 + 最近の `memory/*.md` ファイルを含む、1 回限りの `/new` と `/reset` の起動プレリュード。 - `skills.limits.*`: - system prompt に注入されるコンパクトな Skills 一覧。 + system prompt に注入されるコンパクトな Skills リスト。 - `agents.defaults.contextLimits.*`: - 制限付き runtime 抜粋と、runtime が所有する注入ブロック。 + 上限付きのランタイム抜粋と、注入されるランタイム所有ブロック。 - `memory.qmd.limits.*`: - インデックス化された memory-search スニペットと注入サイズ。 + インデックス済み memory-search スニペットと注入サイズ。 -1 つの agent だけ異なる予算を必要とする場合にのみ、対応する agent ごとのオーバーライドを使用してください: +異なる予算が必要な agent が 1 つだけある場合にのみ、対応する agent ごとのオーバーライドを使用してください: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -素の `/new` および `/reset` 実行時に注入される最初のターンの起動プレリュードを制御します。 +素の `/new` と `/reset` 実行時に注入される最初のターンの起動プレリュードを制御します。 ```json5 { @@ -1029,7 +1027,7 @@ OpenClaw には複数の大容量 prompt/context 予算があり、それらは #### `agents.defaults.contextLimits` -制限付き runtime コンテキストサーフェスの共有デフォルトです。 +上限付きランタイムコンテキストサーフェスの共有デフォルトです。 ```json5 { @@ -1048,12 +1046,12 @@ OpenClaw には複数の大容量 prompt/context 予算があり、それらは - `memoryGetMaxChars`: 切り詰めメタデータと継続通知が追加される前の、デフォルトの `memory_get` 抜粋上限。 - `memoryGetDefaultLines`: `lines` が省略された場合のデフォルトの `memory_get` 行ウィンドウ。 -- `toolResultMaxChars`: 永続化された結果とオーバーフロー回復に使用される、ライブ tool 結果の上限。 -- `postCompactionMaxChars`: post-Compaction の再注入時に使用される AGENTS.md 抜粋上限。 +- `toolResultMaxChars`: 永続化された結果とオーバーフロー回復に使用される、ライブ tool-result の上限。 +- `postCompactionMaxChars`: Compaction 後の再注入時に使用される AGENTS.md 抜粋上限。 #### `agents.list[].contextLimits` -共有 `contextLimits` ノブの agent ごとのオーバーライドです。省略されたフィールドは `agents.defaults.contextLimits` を継承します。 +共有 `contextLimits` ノブに対する agent ごとのオーバーライドです。省略されたフィールドは `agents.defaults.contextLimits` を継承します。 ```json5 { @@ -1079,8 +1077,8 @@ OpenClaw には複数の大容量 prompt/context 予算があり、それらは #### `skills.limits.maxSkillsPromptChars` -system prompt に注入されるコンパクトな Skills 一覧のグローバル上限です。 -これはオンデマンドでの `SKILL.md` ファイル読み込みには影響しません。 +system prompt に注入されるコンパクトな Skills リストのグローバル上限です。 +これは、必要に応じて `SKILL.md` ファイルを読み込む動作には影響しません。 ```json5 { @@ -1094,7 +1092,7 @@ system prompt に注入されるコンパクトな Skills 一覧のグローバ #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills prompt 予算の agent ごとのオーバーライドです。 +skills prompt 予算に対する agent ごとのオーバーライドです。 ```json5 { @@ -1113,11 +1111,11 @@ Skills prompt 予算の agent ごとのオーバーライドです。 ### `agents.defaults.imageMaxDimensionPx` -provider 呼び出し前に、transcript/tool の画像ブロックで最長辺に許可される最大ピクセルサイズです。 +provider 呼び出し前に transcript/tool の画像ブロックで使用される、画像の長辺の最大ピクセルサイズです。 デフォルト: `1200`。 -低い値では通常、スクリーンショットが多い実行時の vision-token 使用量とリクエスト payload サイズが減ります。 -高い値では、より多くの視覚的詳細が保持されます。 +低い値は通常、スクリーンショットが多い実行で vision-token 使用量とリクエスト payload サイズを減らします。 +高い値は、より多くの視覚的詳細を保持します。 ```json5 { @@ -1127,7 +1125,7 @@ provider 呼び出し前に、transcript/tool の画像ブロックで最長辺 ### `agents.defaults.userTimezone` -system prompt コンテキスト用のタイムゾーンです（メッセージタイムスタンプではありません）。ホストのタイムゾーンにフォールバックします。 +system prompt コンテキスト用のタイムゾーンです（メッセージタイムスタンプではありません）。host のタイムゾーンにフォールバックします。 ```json5 { @@ -1137,7 +1135,7 @@ system prompt コンテキスト用のタイムゾーンです（メッセージ ### `agents.defaults.timeFormat` -system prompt の時刻形式です。デフォルト: `auto`（OS 設定）。 +system prompt 内の時刻形式です。デフォルト: `auto`（OS の設定）。 ```json5 { @@ -1175,9 +1173,9 @@ system prompt の時刻形式です。デフォルト: `auto`（OS 設定）。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // グローバルデフォルト provider params embeddedHarness: { - runtime: "auto", // auto | pi | registered harness id, e.g. codex + runtime: "auto", // auto | pi | 登録済み harness id（例: codex） fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1194,48 +1192,48 @@ system prompt の時刻形式です。デフォルト: `auto`（OS 設定）。 } ``` -- `model`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 +- `model`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - 文字列形式は primary model のみを設定します。 - - オブジェクト形式は primary と順序付き failover model を設定します。 -- `imageModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - `image` tool パスの vision-model 設定として使用されます。 - - 選択済み/デフォルトの model が画像入力を受け付けられない場合のフォールバックルーティングにも使用されます。 -- `imageGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - 共通の画像生成 capability と、今後追加される画像生成 tool/plugin サーフェスで使用されます。 - - 代表的な値: Gemini ネイティブ画像生成には `google/gemini-3.1-flash-image-preview`、fal には `fal/fal-ai/flux/dev`、OpenAI Images には `openai/gpt-image-1`。 - - provider/model を直接選択する場合は、対応する provider の認証/API キーも設定してください（たとえば `google/*` には `GEMINI_API_KEY` または `GOOGLE_API_KEY`、`openai/*` には `OPENAI_API_KEY`、`fal/*` には `FAL_KEY`）。 - - 省略した場合でも、`image_generate` は認証済み provider デフォルトを推論できます。まず現在のデフォルト provider を試し、その後に残りの登録済み画像生成 provider を provider-id 順で試します。 -- `musicGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - 共通の音楽生成 capability と組み込みの `music_generate` tool で使用されます。 - - 代表的な値: `google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`、`minimax/music-2.5+`。 - - 省略した場合でも、`music_generate` は認証済み provider デフォルトを推論できます。まず現在のデフォルト provider を試し、その後に残りの登録済み音楽生成 provider を provider-id 順で試します。 - - provider/model を直接選択する場合は、対応する provider の認証/API キーも設定してください。 -- `videoGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - 共通の動画生成 capability と組み込みの `video_generate` tool で使用されます。 - - 代表的な値: `qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`、`qwen/wan2.7-r2v`。 - - 省略した場合でも、`video_generate` は認証済み provider デフォルトを推論できます。まず現在のデフォルト provider を試し、その後に残りの登録済み動画生成 provider を provider-id 順で試します。 - - provider/model を直接選択する場合は、対応する provider の認証/API キーも設定してください。 - - bundled Qwen 動画生成 provider は、最大 1 本の出力動画、1 枚の入力画像、4 本の入力動画、10 秒の長さ、および provider レベルの `size`、`aspectRatio`、`resolution`、`audio`、`watermark` オプションをサポートします。 -- `pdfModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）のいずれかを受け付けます。 - - `pdf` tool の model ルーティングに使用されます。 - - 省略した場合、PDF tool は `imageModel` にフォールバックし、その後に解決済みの session/デフォルト model にフォールバックします。 -- `pdfMaxBytesMb`: 呼び出し時に `maxBytesMb` が渡されない場合の、`pdf` tool 用デフォルト PDF サイズ上限。 -- `pdfMaxPages`: `pdf` tool の抽出フォールバックモードで考慮するデフォルト最大ページ数。 + - オブジェクト形式は primary と順序付きのフェイルオーバー model を設定します。 +- `imageModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 + - `image` tool パスで、その vision-model 設定として使用されます。 + - 選択された/デフォルトの model が画像入力を受け付けられない場合のフォールバックルーティングにも使用されます。 +- `imageGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 + - 共有の画像生成機能と、将来の画像を生成するあらゆる tool/plugin サーフェスで使用されます。 + - 一般的な値: Gemini ネイティブ画像生成には `google/gemini-3.1-flash-image-preview`、fal には `fal/fal-ai/flux/dev`、OpenAI Images には `openai/gpt-image-1`。 + - provider/model を直接選択する場合は、対応する provider の auth/API key も設定してください（たとえば `google/*` には `GEMINI_API_KEY` または `GOOGLE_API_KEY`、`openai/*` には `OPENAI_API_KEY`、`fal/*` には `FAL_KEY`）。 + - 省略した場合でも、`image_generate` は auth がある provider デフォルトを推測できます。まず現在のデフォルト provider を試し、次に残りの登録済み画像生成 provider を provider-id 順で試します。 +- `musicGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 + - 共有の音楽生成機能と、built-in の `music_generate` tool で使用されます。 + - 一般的な値: `google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`、または `minimax/music-2.5+`。 + - 省略した場合でも、`music_generate` は auth がある provider デフォルトを推測できます。まず現在のデフォルト provider を試し、次に残りの登録済み音楽生成 provider を provider-id 順で試します。 + - provider/model を直接選択する場合は、対応する provider の auth/API key も設定してください。 +- `videoGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 + - 共有の動画生成機能と、built-in の `video_generate` tool で使用されます。 + - 一般的な値: `qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`、または `qwen/wan2.7-r2v`。 + - 省略した場合でも、`video_generate` は auth がある provider デフォルトを推測できます。まず現在のデフォルト provider を試し、次に残りの登録済み動画生成 provider を provider-id 順で試します。 + - provider/model を直接選択する場合は、対応する provider の auth/API key も設定してください。 + - bundled の Qwen 動画生成 provider は、最大 1 本の出力動画、1 枚の入力画像、4 本の入力動画、10 秒の長さ、および provider レベルの `size`、`aspectRatio`、`resolution`、`audio`、`watermark` オプションをサポートします。 +- `pdfModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 + - `pdf` tool の model ルーティングで使用されます。 + - 省略した場合、PDF tool は `imageModel` にフォールバックし、さらに解決済みの session/デフォルト model にフォールバックします。 +- `pdfMaxBytesMb`: 呼び出し時に `maxBytesMb` が渡されない場合の、`pdf` tool のデフォルト PDF サイズ上限。 +- `pdfMaxPages`: `pdf` tool の抽出フォールバックモードで考慮されるデフォルトの最大ページ数。 - `verboseDefault`: agent のデフォルト verbose レベル。値: `"off"`、`"on"`、`"full"`。デフォルト: `"off"`。 - `elevatedDefault`: agent のデフォルト elevated-output レベル。値: `"off"`、`"on"`、`"ask"`、`"full"`。デフォルト: `"on"`。 -- `model.primary`: 形式は `provider/model`（例: `openai/gpt-5.4`）。provider を省略すると、OpenClaw はまず alias を試し、次にその正確な model id に対する一意の configured-provider 一致を試し、それでもだめなら設定済みのデフォルト provider にフォールバックします（非推奨の互換動作なので、明示的な `provider/model` を推奨します）。その provider が設定済みのデフォルト model をもう提供していない場合、OpenClaw は古くなった削除済み provider のデフォルトを表面化する代わりに、最初の configured provider/model にフォールバックします。 -- `models`: `/model` 用に設定される model カタログおよび allowlist。各エントリには `alias`（ショートカット）と `params`（provider 固有。例: `temperature`、`maxTokens`、`cacheRetention`、`context1m`）を含められます。 -- `params`: すべての model に適用されるグローバルなデフォルト provider パラメータ。`agents.defaults.params` に設定します（例: `{ cacheRetention: "long" }`）。 -- `params` のマージ優先順位（config）: `agents.defaults.params`（グローバルベース）が `agents.defaults.models["provider/model"].params`（model ごと）で上書きされ、さらに `agents.list[].params`（一致する agent id）がキーごとに上書きします。詳細は [Prompt Caching](/ja-JP/reference/prompt-caching) を参照してください。 -- `embeddedHarness`: デフォルトの低レベル embedded agent runtime ポリシー。`runtime: "auto"` を使うと、登録済み plugin harness がサポート対象 model を引き受けられるようになります。`runtime: "pi"` は組み込み PI harness を強制し、`runtime: "codex"` のように登録済み harness id も指定できます。自動 PI フォールバックを無効にするには `fallback: "none"` を設定します。 -- これらのフィールドを書き換える config writer（例: `/models set`、`/models set-image`、fallback の追加/削除コマンド）は、正規のオブジェクト形式で保存し、可能な場合は既存の fallback リストを保持します。 -- `maxConcurrent`: session をまたいで並列実行できる agent 実行の最大数（各 session 自体は引き続き直列化されます）。デフォルト: 4。 +- `model.primary`: 形式は `provider/model`（例: `openai/gpt-5.4`）。provider を省略した場合、OpenClaw はまずエイリアスを試し、次にその正確な model id に対する一意の configured-provider 一致を試し、それでもだめなら設定されたデフォルト provider にフォールバックします（これは非推奨の互換動作なので、明示的な `provider/model` を推奨します）。その provider が設定済みデフォルト model をもう公開していない場合、OpenClaw は古くなって削除された provider デフォルトを表面化する代わりに、最初の configured provider/model にフォールバックします。 +- `models`: `/model` 用の設定済み model カタログ兼 allowlist。各エントリには `alias`（ショートカット）と `params`（provider 固有。例: `temperature`、`maxTokens`、`cacheRetention`、`context1m`）を含められます。 +- `params`: すべての model に適用されるグローバルデフォルトの provider パラメータ。`agents.defaults.params` に設定します（例: `{ cacheRetention: "long" }`）。 +- `params` のマージ優先順位（設定）: `agents.defaults.params`（グローバルベース）は `agents.defaults.models["provider/model"].params`（model ごと）で上書きされ、さらに `agents.list[].params`（一致する agent id）がキーごとに上書きします。詳細は [Prompt Caching](/ja-JP/reference/prompt-caching) を参照してください。 +- `embeddedHarness`: デフォルトの低レベル組み込み agent ランタイムポリシー。`runtime: "auto"` を使うと、登録済み plugin harness がサポートする model を引き受けられるようにし、`runtime: "pi"` を使うと built-in の Pi harness を強制し、`runtime: "codex"` のような登録済み harness id も指定できます。自動の Pi フォールバックを無効にするには `fallback: "none"` を設定します。 +- これらのフィールドを変更する config writer（たとえば `/models set`、`/models set-image`、および fallback の追加/削除コマンド）は、正規のオブジェクト形式で保存し、可能な限り既存の fallback リストを保持します。 +- `maxConcurrent`: session をまたいだ agent 実行の最大並列数です（各 session 自体は引き続き直列化されます）。デフォルト: 4。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` は、どの低レベル executor が embedded agent turn を実行するかを制御します。 +`embeddedHarness` は、どの低レベル executor が組み込み agent ターンを実行するかを制御します。 ほとんどのデプロイでは、デフォルトの `{ runtime: "auto", fallback: "pi" }` のままで問題ありません。 -bundled Codex app-server harness のように、信頼できる plugin がネイティブ harness を提供する場合に使用してください。 +bundled の Codex app-server harness のように、信頼できる plugin がネイティブ harness を提供する場合に使用します。 ```json5 { @@ -1251,13 +1249,13 @@ bundled Codex app-server harness のように、信頼できる plugin がネイ } ``` -- `runtime`: `"auto"`、`"pi"`、または登録済み plugin harness id。bundled Codex Plugin は `codex` を登録します。 -- `fallback`: `"pi"` または `"none"`。`"pi"` は組み込み PI harness を互換用フォールバックとして維持します。`"none"` は、不足している、または未対応の plugin harness 選択時に、PI を黙って使う代わりに失敗させます。 -- 環境変数オーバーライド: `OPENCLAW_AGENT_RUNTIME=` は `runtime` を上書きします。`OPENCLAW_AGENT_HARNESS_FALLBACK=none` はそのプロセスで PI フォールバックを無効にします。 +- `runtime`: `"auto"`、`"pi"`、または登録済み plugin harness id。bundled の Codex Plugin は `codex` を登録します。 +- `fallback`: `"pi"` または `"none"`。`"pi"` は built-in の Pi harness を互換性用フォールバックとして維持します。`"none"` は、plugin harness の選択が欠落しているか未対応の場合に、黙って Pi を使うのではなく失敗させます。 +- 環境変数によるオーバーライド: `OPENCLAW_AGENT_RUNTIME=` は `runtime` を上書きします。`OPENCLAW_AGENT_HARNESS_FALLBACK=none` はそのプロセスでの Pi フォールバックを無効にします。 - Codex 専用デプロイでは、`model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"`、`embeddedHarness.fallback: "none"` を設定してください。 -- これは embedded chat harness のみを制御します。メディア生成、vision、PDF、音楽、動画、TTS は引き続きそれぞれの provider/model 設定を使用します。 +- これは組み込み chat harness のみを制御します。メディア生成、vision、PDF、音楽、動画、および TTS は引き続きそれぞれの provider/model 設定を使用します。 -**組み込み alias ショートハンド**（model が `agents.defaults.models` にある場合のみ適用）: +**Built-in の短縮 alias**（model が `agents.defaults.models` にある場合のみ適用）: | Alias | Model | | ------------------- | -------------------------------------- | @@ -1272,13 +1270,13 @@ bundled Codex app-server harness のように、信頼できる plugin がネイ 設定した alias は常にデフォルトより優先されます。 -Z.AI GLM-4.x model は、`--thinking off` を設定するか、自分で `agents.defaults.models["zai/"].params.thinking` を定義しない限り、自動的に thinking mode を有効にします。 -Z.AI model は、tool 呼び出しストリーミングのためにデフォルトで `tool_stream` を有効にします。無効にするには `agents.defaults.models["zai/"].params.tool_stream` を `false` に設定してください。 +Z.AI の GLM-4.x model は、`--thinking off` を設定するか、`agents.defaults.models["zai/"].params.thinking` を自分で定義しない限り、自動的に thinking mode を有効にします。 +Z.AI model は tool call ストリーミングのためにデフォルトで `tool_stream` を有効にします。無効にするには `agents.defaults.models["zai/"].params.tool_stream` を `false` に設定してください。 Anthropic Claude 4.6 model は、明示的な thinking レベルが設定されていない場合、デフォルトで `adaptive` thinking を使用します。 ### `agents.defaults.cliBackends` -テキスト専用のフォールバック実行用の任意 CLI backend です（tool 呼び出しなし）。API provider が失敗したときのバックアップとして便利です。 +テキストのみのフォールバック実行用のオプションの CLI バックエンドです（tool call なし）。API provider が失敗したときのバックアップとして便利です。 ```json5 { @@ -1306,9 +1304,9 @@ Anthropic Claude 4.6 model は、明示的な thinking レベルが設定され } ``` -- CLI backend は text-first です。tools は常に無効です。 -- `sessionArg` が設定されている場合は session がサポートされます。 -- `imageArg` がファイルパスを受け付ける場合は画像パススルーがサポートされます。 +- CLI バックエンドはテキスト優先です。tools は常に無効です。 +- `sessionArg` が設定されている場合、session をサポートします。 +- `imageArg` がファイルパスを受け付ける場合、画像のパススルーをサポートします。 ### `agents.defaults.systemPromptOverride` @@ -1333,16 +1331,16 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m で無効 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // デフォルト: true。false の場合、system prompt から Heartbeat セクションを省略 + lightContext: false, // デフォルト: false。true の場合、workspace bootstrap ファイルから HEARTBEAT.md のみ保持 + isolatedSession: false, // デフォルト: false。true の場合、各 Heartbeat を新しい session で実行（会話履歴なし） session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow（デフォルト）| block + target: "none", // デフォルト: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1353,15 +1351,15 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 } ``` -- `every`: 期間文字列（ms/s/m/h）。デフォルト: `30m`（API キー認証）または `1h`（OAuth 認証）。無効にするには `0m` を設定します。 -- `includeSystemPromptSection`: false の場合、system prompt から Heartbeat セクションを省略し、bootstrap コンテキストへの `HEARTBEAT.md` 注入もスキップします。デフォルト: `true`。 +- `every`: 期間文字列（ms/s/m/h）。デフォルト: `30m`（API-key 認証）または `1h`（OAuth 認証）。無効にするには `0m` を設定します。 +- `includeSystemPromptSection`: false の場合、system prompt から Heartbeat セクションを省略し、bootstrap コンテキストへの `HEARTBEAT.md` 注入をスキップします。デフォルト: `true`。 - `suppressToolErrorWarnings`: true の場合、Heartbeat 実行中の tool エラー警告 payload を抑制します。 -- `timeoutSeconds`: 中断される前に Heartbeat agent turn に許可される最大秒数。未設定の場合は `agents.defaults.timeoutSeconds` を使用します。 -- `directPolicy`: direct/DM 配信ポリシー。`allow`（デフォルト）は direct-target 配信を許可します。`block` は direct-target 配信を抑制し、`reason=dm-blocked` を出力します。 -- `lightContext`: true の場合、Heartbeat 実行は軽量 bootstrap コンテキストを使用し、workspace bootstrap ファイルからは `HEARTBEAT.md` のみを保持します。 -- `isolatedSession`: true の場合、各 Heartbeat は過去の会話履歴なしの新しい session で実行されます。Cron の `sessionTarget: "isolated"` と同じ分離パターンです。Heartbeat あたりの token コストを約 100K から約 2-5K token に削減します。 -- agent ごと: `agents.list[].heartbeat` を設定します。いずれかの agent が `heartbeat` を定義した場合、Heartbeat を実行するのは**それらの agent のみ**です。 -- Heartbeat は完全な agent turn を実行するため、間隔を短くすると token 消費が増えます。 +- `timeoutSeconds`: 中断されるまでの Heartbeat agent ターンの最大許容秒数。未設定の場合は `agents.defaults.timeoutSeconds` を使用します。 +- `directPolicy`: direct/DM 配信ポリシー。`allow`（デフォルト）は direct ターゲットへの配信を許可します。`block` は direct ターゲットへの配信を抑止し、`reason=dm-blocked` を出力します。 +- `lightContext`: true の場合、Heartbeat 実行は軽量な bootstrap コンテキストを使用し、workspace bootstrap ファイルから `HEARTBEAT.md` のみを保持します。 +- `isolatedSession`: true の場合、各 Heartbeat は以前の会話履歴を持たない新しい session で実行されます。Cron の `sessionTarget: "isolated"` と同じ分離パターンです。Heartbeat ごとの token コストを約 100K から約 2-5K token に削減します。 +- agent ごと: `agents.list[].heartbeat` を設定します。いずれかの agent が `heartbeat` を定義すると、Heartbeat を実行するのは**その agent だけ**になります。 +- Heartbeat は完全な agent ターンを実行します。間隔を短くすると token 消費が増えます。 ### `agents.defaults.compaction` @@ -1371,14 +1369,14 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // 登録済み compaction provider plugin の id（オプション） timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // identifierPolicy=custom のときに使用 + postCompactionSections: ["Session Startup", "Red Lines"], // [] で再注入を無効化 + model: "openrouter/anthropic/claude-sonnet-4-6", // compaction 専用のオプションの model オーバーライド + notifyUser: true, // compaction 開始時に短い通知を送信（デフォルト: false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1392,18 +1390,18 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 ``` - `mode`: `default` または `safeguard`（長い履歴向けのチャンク化要約）。[Compaction](/ja-JP/concepts/compaction) を参照してください。 -- `provider`: 登録済み compaction provider Plugin の id。設定されている場合、組み込みの LLM 要約の代わりにその provider の `summarize()` が呼び出されます。失敗時は組み込みへフォールバックします。provider を設定すると `mode: "safeguard"` が強制されます。[Compaction](/ja-JP/concepts/compaction) を参照してください。 -- `timeoutSeconds`: 1 回の compaction 処理に対して OpenClaw が中断するまで許容する最大秒数。デフォルト: `900`。 -- `identifierPolicy`: `strict`（デフォルト）、`off`、または `custom`。`strict` は compaction 要約時に、組み込みの不透明識別子保持ガイダンスを先頭に追加します。 -- `identifierInstructions`: `identifierPolicy=custom` のときに使用される、任意のカスタム識別子保持テキスト。 -- `postCompactionSections`: compaction 後に再注入する任意の AGENTS.md H2/H3 セクション名。デフォルトは `["Session Startup", "Red Lines"]` で、再注入を無効にするには `[]` を設定します。未設定、または明示的にそのデフォルトの組み合わせに設定されている場合は、従来の `Every Session`/`Safety` 見出しもレガシーフォールバックとして受け付けます。 -- `model`: compaction 要約専用の任意の `provider/model-id` オーバーライドです。メインセッションでは 1 つの model を維持しつつ、compaction 要約だけ別の model で実行したい場合に使用します。未設定の場合、compaction はセッションの primary model を使用します。 -- `notifyUser`: `true` の場合、compaction 開始時にユーザーへ短い通知を送信します（例: 「コンテキストを Compaction 中...」）。compaction を無言で行うため、デフォルトでは無効です。 -- `memoryFlush`: durable memory を保存するための、自動 compaction 前のサイレントな agent turn。workspace が読み取り専用の場合はスキップされます。 +- `provider`: 登録済み compaction provider plugin の id。設定されている場合、built-in の LLM 要約の代わりに、その provider の `summarize()` が呼び出されます。失敗時は built-in にフォールバックします。provider を設定すると `mode: "safeguard"` が強制されます。[Compaction](/ja-JP/concepts/compaction) を参照してください。 +- `timeoutSeconds`: OpenClaw が中断するまでに 1 回の compaction 操作に許可される最大秒数。デフォルト: `900`。 +- `identifierPolicy`: `strict`（デフォルト）、`off`、または `custom`。`strict` は、compaction 要約時に built-in の不透明な識別子保持ガイダンスを先頭に追加します。 +- `identifierInstructions`: `identifierPolicy=custom` のときに使用される、識別子保持に関するオプションのカスタムテキスト。 +- `postCompactionSections`: compaction 後に再注入するオプションの AGENTS.md H2/H3 セクション名。デフォルトは `["Session Startup", "Red Lines"]` です。再注入を無効にするには `[]` を設定します。未設定の場合、または明示的にそのデフォルトのペアを設定した場合、従来の互換フォールバックとして古い `Every Session`/`Safety` 見出しも受け入れられます。 +- `model`: compaction 要約専用のオプションの `provider/model-id` オーバーライド。メイン session では 1 つの model を維持しつつ、compaction 要約は別の model で実行したい場合に使用します。未設定の場合、compaction は session の primary model を使用します。 +- `notifyUser`: `true` の場合、compaction 開始時にユーザーへ短い通知を送ります（例: 「Compacting context...」）。compaction を静かに保つため、デフォルトでは無効です。 +- `memoryFlush`: 耐久的な memory を保存するための、自動 compaction 前の無言の agent ターン。workspace が読み取り専用の場合はスキップされます。 ### `agents.defaults.contextPruning` -LLM に送信する前に、メモリ内コンテキストから**古い tool 結果**を剪定します。ディスク上のセッション履歴は**変更しません**。 +LLM に送信する前に、メモリ内コンテキストから**古い tool 結果**を剪定します。ディスク上の session 履歴は**変更しません**。 ```json5 { @@ -1411,7 +1409,7 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // 期間（ms/s/m/h）、デフォルト単位: 分 keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1428,18 +1426,18 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool - `mode: "cache-ttl"` は剪定パスを有効にします。 -- `ttl` は、最後のキャッシュタッチ後に、いつ再び剪定を実行できるかを制御します。 -- 剪定はまず大きすぎる tool 結果をソフトトリムし、必要ならさらに古い tool 結果をハードクリアします。 +- `ttl` は、最後のキャッシュタッチ後にどのくらいの間隔で再び剪定を実行できるかを制御します。 +- 剪定はまず大きすぎる tool 結果を soft-trim し、その後必要に応じて古い tool 結果を hard-clear します。 -**ソフトトリム**は先頭と末尾を保持し、中間に `...` を挿入します。 +**Soft-trim** は先頭 + 末尾を保持し、中間に `...` を挿入します。 -**ハードクリア**は tool 結果全体をプレースホルダーに置き換えます。 +**Hard-clear** は tool 結果全体をプレースホルダーで置き換えます。 注意: - 画像ブロックは切り詰めもクリアもされません。 -- 比率はトークン数の厳密値ではなく、文字数ベースの概算です。 -- `keepLastAssistants` 個未満の assistant メッセージしか存在しない場合、剪定はスキップされます。 +- ratio は文字数ベース（概算）であり、正確な token 数ではありません。 +- `keepLastAssistants` より少ない assistant メッセージしか存在しない場合、剪定はスキップされます。 @@ -1455,13 +1453,13 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom（minMs/maxMs を使用） }, }, } ``` -- Telegram 以外の channel では、ブロック返信を有効にするには明示的に `*.blockStreaming: true` が必要です。 +- Telegram 以外の channel では、ブロック返信を有効にするには明示的な `*.blockStreaming: true` が必要です。 - channel ごとのオーバーライド: `channels..blockStreamingCoalesce`（およびアカウントごとのバリアント）。Signal/Slack/Discord/Google Chat のデフォルトは `minChars: 1500` です。 - `humanDelay`: ブロック返信間のランダムな待機。`natural` = 800–2500ms。agent ごとのオーバーライド: `agents.list[].humanDelay`。 @@ -1480,8 +1478,8 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool } ``` -- デフォルト: ダイレクトチャット/mention では `instant`、mention されていないグループチャットでは `message`。 -- セッションごとのオーバーライド: `session.typingMode`、`session.typingIntervalSeconds`。 +- デフォルト: direct chat/メンションでは `instant`、メンションされていないグループチャットでは `message`。 +- session ごとのオーバーライド: `session.typingMode`、`session.typingIntervalSeconds`。 [Typing Indicators](/ja-JP/concepts/typing-indicators) を参照してください。 @@ -1489,7 +1487,7 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool ### `agents.defaults.sandbox` -embedded agent 用の任意の sandbox 化です。完全なガイドは [Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。 +組み込み agent 用のオプションの sandboxing です。完全なガイドは [Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。 ```json5 { @@ -1535,7 +1533,7 @@ embedded agent 用の任意の sandbox 化です。完全なガイドは [Sandbo identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // SecretRef / インライン内容もサポート: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1588,48 +1586,48 @@ embedded agent 用の任意の sandbox 化です。完全なガイドは [Sandbo **Backend:** -- `docker`: ローカル Docker runtime（デフォルト） -- `ssh`: 汎用 SSH ベースのリモート runtime -- `openshell`: OpenShell runtime +- `docker`: ローカル Docker ランタイム（デフォルト） +- `ssh`: 汎用 SSH バックのリモートランタイム +- `openshell`: OpenShell ランタイム -`backend: "openshell"` を選択した場合、runtime 固有の設定は +`backend: "openshell"` が選択されている場合、ランタイム固有の設定は `plugins.entries.openshell.config` に移動します。 **SSH backend 設定:** - `target`: `user@host[:port]` 形式の SSH ターゲット - `command`: SSH クライアントコマンド（デフォルト: `ssh`） -- `workspaceRoot`: スコープごとの workspace に使用する絶対リモートルート +- `workspaceRoot`: スコープごとの workspace に使われる絶対リモートルート - `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSH に渡される既存のローカルファイル -- `identityData` / `certificateData` / `knownHostsData`: runtime 時に OpenClaw が一時ファイルへ実体化するインライン内容または SecretRef +- `identityData` / `certificateData` / `knownHostsData`: OpenClaw がランタイム時に一時ファイルへ具現化するインライン内容または SecretRef - `strictHostKeyChecking` / `updateHostKeys`: OpenSSH の host-key ポリシーノブ **SSH 認証の優先順位:** -- `identityData` は `identityFile` より優先 -- `certificateData` は `certificateFile` より優先 -- `knownHostsData` は `knownHostsFile` より優先 -- SecretRef ベースの `*Data` 値は、sandbox セッション開始前にアクティブな secrets runtime snapshot から解決されます +- `identityData` は `identityFile` より優先されます +- `certificateData` は `certificateFile` より優先されます +- `knownHostsData` は `knownHostsFile` より優先されます +- SecretRef バックの `*Data` 値は、sandbox session が開始される前にアクティブな secrets ランタイムスナップショットから解決されます **SSH backend の動作:** - 作成または再作成後にリモート workspace を 1 回シードします -- その後はリモート SSH workspace を正本として維持します +- その後はリモート SSH workspace を正規とみなします - `exec`、ファイル tools、メディアパスを SSH 経由でルーティングします -- リモート変更を自動的にホストへ同期しません -- sandbox browser コンテナはサポートしません +- リモートでの変更を自動的に host へ同期しません +- sandbox browser コンテナをサポートしません **Workspace アクセス:** - `none`: `~/.openclaw/sandboxes` 配下のスコープごとの sandbox workspace -- `ro`: `/workspace` の sandbox workspace と、`/agent` に読み取り専用でマウントされた agent workspace -- `rw`: `/workspace` に読み書きでマウントされた agent workspace +- `ro`: `/workspace` に sandbox workspace、`/agent` に agent workspace を読み取り専用でマウント +- `rw`: `/workspace` に agent workspace を読み書き可能でマウント **Scope:** -- `session`: セッションごとのコンテナ + workspace +- `session`: session ごとのコンテナ + workspace - `agent`: agent ごとに 1 つのコンテナ + workspace（デフォルト） -- `shared`: 共有コンテナと共有 workspace（セッション間分離なし） +- `shared`: 共有コンテナと共有 workspace（session 間分離なし） **OpenShell Plugin 設定:** @@ -1644,10 +1642,10 @@ embedded agent 用の任意の sandbox 化です。完全なガイドは [Sandbo from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // オプション + gatewayEndpoint: "https://lab.example", // オプション + policy: "strict", // オプションの OpenShell policy id + providers: ["openai"], // オプション autoProviders: true, timeoutSeconds: 120, }, @@ -1659,29 +1657,29 @@ embedded agent 用の任意の sandbox 化です。完全なガイドは [Sandbo **OpenShell モード:** -- `mirror`: 実行前にローカルからリモートへシードし、実行後に同期を戻します。ローカル workspace が正本のままです -- `remote`: sandbox 作成時に 1 回だけリモートへシードし、その後はリモート workspace を正本として維持します +- `mirror`: `exec` 前にローカルからリモートへシードし、`exec` 後に同期を戻します。ローカル workspace が正規のままです +- `remote`: sandbox 作成時にリモートへ 1 回シードし、その後はリモート workspace を正規とみなします -`remote` モードでは、OpenClaw の外で行われたホストローカル編集は、シード後に自動では sandbox に同期されません。 -転送は OpenShell sandbox への SSH ですが、sandbox のライフサイクルと任意の mirror 同期は Plugin が所有します。 +`remote` モードでは、seed ステップ後に OpenClaw の外で行われた host ローカル編集は、自動的には sandbox に同期されません。 +転送は OpenShell sandbox への SSH ですが、sandbox のライフサイクルとオプションの mirror 同期は Plugin が管理します。 -**`setupCommand`** はコンテナ作成後に 1 回だけ実行されます（`sh -lc` 経由）。ネットワーク外向き通信、書き込み可能なルート、root ユーザーが必要です。 +**`setupCommand`** はコンテナ作成後に 1 回だけ実行されます（`sh -lc` 経由）。network egress、書き込み可能な root、root user が必要です。 -**コンテナのデフォルトは `network: "none"`** です — agent が外向きアクセスを必要とする場合は `"bridge"`（またはカスタム bridge network）に設定してください。 -`"host"` はブロックされます。`"container:"` も、`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` を明示的に設定しない限り（break-glass）、デフォルトでブロックされます。 +**コンテナのデフォルトは `network: "none"`** です — agent に外向きアクセスが必要なら `"bridge"`（またはカスタム bridge network）に設定してください。 +`"host"` はブロックされます。`"container:"` は、`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` を明示的に設定しない限り、デフォルトでブロックされます（緊急用）。 -**受信添付ファイル** は、アクティブ workspace 内の `media/inbound/*` にステージされます。 +**受信添付ファイル** は、アクティブ workspace の `media/inbound/*` にステージングされます。 -**`docker.binds`** は追加のホストディレクトリをマウントします。グローバルと agent ごとの bind はマージされます。 +**`docker.binds`** は追加の host ディレクトリをマウントします。グローバルと agent ごとの bind はマージされます。 -**Sandbox 化された browser**（`sandbox.browser.enabled`）: コンテナ内の Chromium + CDP。noVNC URL は system prompt に注入されます。`openclaw.json` で `browser.enabled` を必要としません。 -noVNC の observer アクセスはデフォルトで VNC 認証を使用し、OpenClaw は共有 URL に password を露出する代わりに短命 token URL を発行します。 +**Sandboxed browser**（`sandbox.browser.enabled`）: コンテナ内の Chromium + CDP。noVNC URL が system prompt に注入されます。`openclaw.json` で `browser.enabled` は不要です。 +noVNC のオブザーバーアクセスはデフォルトで VNC 認証を使用し、OpenClaw は共有 URL にパスワードを露出する代わりに短命な token URL を発行します。 -- `allowHostControl: false`（デフォルト）は、sandbox 化されたセッションがホスト browser を対象にすることをブロックします。 -- `network` のデフォルトは `openclaw-sandbox-browser`（専用 bridge network）です。グローバル bridge 接続が明示的に必要な場合にのみ `bridge` を設定してください。 -- `cdpSourceRange` は、コンテナ境界での CDP 受信を CIDR 範囲（たとえば `172.21.0.1/32`）に任意で制限します。 -- `sandbox.browser.binds` は、追加のホストディレクトリを sandbox browser コンテナにのみマウントします。設定されている場合（`[]` を含む）、browser コンテナでは `docker.binds` を置き換えます。 -- 起動デフォルトは `scripts/sandbox-browser-entrypoint.sh` で定義されており、コンテナホスト向けに調整されています: +- `allowHostControl: false`（デフォルト）は、sandbox 化された session から host browser を対象にすることをブロックします。 +- `network` のデフォルトは `openclaw-sandbox-browser`（専用の bridge network）です。グローバル bridge 接続を明示的に望む場合にのみ `bridge` に設定してください。 +- `cdpSourceRange` は、CDP の ingress をコンテナ境界で CIDR 範囲（例: `172.21.0.1/32`）にオプションで制限します。 +- `sandbox.browser.binds` は追加の host ディレクトリを sandbox browser コンテナのみにマウントします。設定されている場合（`[]` を含む）、browser コンテナでは `docker.binds` を置き換えます。 +- 起動デフォルトは `scripts/sandbox-browser-entrypoint.sh` で定義され、コンテナ host 向けに調整されています: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1700,15 +1698,15 @@ noVNC の observer アクセスはデフォルトで VNC 認証を使用し、Op - `--metrics-recording-only` - `--disable-extensions`（デフォルトで有効） - `--disable-3d-apis`、`--disable-software-rasterizer`、`--disable-gpu` は - デフォルトで有効であり、WebGL/3D 利用で必要な場合は - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` で無効にできます。 + デフォルトで有効であり、WebGL/3D の使用で必要な場合は + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` で無効化できます。 - ワークフローが extension に依存する場合は、 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` で extension を再有効化できます。 + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` で extension を再有効化します。 - `--renderer-process-limit=2` は `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` で変更できます。Chromium の - デフォルトの process 上限を使用するには `0` を設定してください。 + デフォルトの process 制限を使うには `0` を設定します。 - さらに、`noSandbox` が有効な場合は `--no-sandbox` と `--disable-setuid-sandbox`。 - - デフォルトはコンテナ image のベースラインです。コンテナデフォルトを変更するには、 + - デフォルトはコンテナ image のベースラインです。コンテナのデフォルトを変更するには、 カスタム browser image とカスタム entrypoint を使用してください。 @@ -1718,8 +1716,8 @@ browser sandboxing と `sandbox.docker.binds` は Docker 専用です。 image をビルド: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # メイン sandbox image +scripts/sandbox-browser-setup.sh # オプションの browser image ``` ### `agents.list`（agent ごとのオーバーライド） @@ -1734,13 +1732,13 @@ scripts/sandbox-browser-setup.sh # optional browser image name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override + model: "anthropic/claude-opus-4-6", // または { primary, fallbacks } + thinkingDefault: "high", // agent ごとの thinking レベルオーバーライド + reasoningDefault: "on", // agent ごとの reasoning 可視性オーバーライド + fastModeDefault: false, // agent ごとの fast mode オーバーライド embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + params: { cacheRetention: "none" }, // 一致する defaults.models params をキーごとに上書き + skills: ["docs-search"], // 設定時は agents.defaults.skills を置き換える identity: { name: "Samantha", theme: "helpful sloth", @@ -1772,24 +1770,24 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: 安定した agent id（必須）。 -- `default`: 複数設定されている場合は最初のものが優先されます（警告がログ出力されます）。何も設定されていない場合、最初のリスト項目がデフォルトです。 -- `model`: 文字列形式は `primary` のみを上書きし、オブジェクト形式 `{ primary, fallbacks }` は両方を上書きします（`[]` はグローバル fallback を無効化）。`primary` だけを上書きする Cron ジョブは、`fallbacks: []` を設定しない限り、引き続きデフォルト fallback を継承します。 -- `params`: `agents.defaults.models` 内の選択された model エントリにマージされる agent ごとの stream params。model カタログ全体を重複させずに、`cacheRetention`、`temperature`、`maxTokens` など agent 固有の上書きに使います。 -- `skills`: 任意の agent ごとの Skills allowlist。省略すると、その agent は設定されている場合に `agents.defaults.skills` を継承します。明示的なリストはデフォルトをマージせずに置き換え、`[]` は Skills なしを意味します。 -- `thinkingDefault`: 任意の agent ごとのデフォルト thinking レベル（`off | minimal | low | medium | high | xhigh | adaptive`）。メッセージごとまたは session のオーバーライドが設定されていない場合、この agent では `agents.defaults.thinkingDefault` を上書きします。 -- `reasoningDefault`: 任意の agent ごとのデフォルト reasoning 可視性（`on | off | stream`）。メッセージごとまたは session の reasoning オーバーライドが設定されていない場合に適用されます。 -- `fastModeDefault`: 任意の agent ごとの fast mode デフォルト（`true | false`）。メッセージごとまたは session の fast-mode オーバーライドが設定されていない場合に適用されます。 -- `embeddedHarness`: 任意の agent ごとの低レベル harness ポリシーオーバーライド。ある agent だけを Codex 専用にし、他の agent はデフォルトの PI フォールバックを維持するには `{ runtime: "codex", fallback: "none" }` を使用します。 -- `runtime`: 任意の agent ごとの runtime 記述子。agent がデフォルトで ACP harness session を使用すべき場合は、`type: "acp"` と `runtime.acp` デフォルト（`agent`、`backend`、`mode`、`cwd`）を使います。 +- `default`: 複数設定されている場合は最初のものが優先されます（警告を記録）。何も設定されていない場合は、最初の list エントリがデフォルトです。 +- `model`: 文字列形式は `primary` のみを上書きし、オブジェクト形式 `{ primary, fallbacks }` は両方を上書きします（`[]` はグローバル fallback を無効化）。`primary` のみを上書きする Cron ジョブでも、`fallbacks: []` を設定しない限り、デフォルトの fallback を継承します。 +- `params`: `agents.defaults.models` 内の選択された model エントリにマージされる agent ごとの stream params。model カタログ全体を複製せずに、`cacheRetention`、`temperature`、`maxTokens` などの agent 固有オーバーライドに使用します。 +- `skills`: オプションの agent ごとの skill allowlist。省略すると、`agents.defaults.skills` が設定されていれば agent はそれを継承します。明示的なリストはデフォルトをマージせずに置き換え、`[]` は skills なしを意味します。 +- `thinkingDefault`: オプションの agent ごとのデフォルト thinking レベル（`off | minimal | low | medium | high | xhigh | adaptive`）。メッセージごとまたは session のオーバーライドが設定されていない場合、この agent では `agents.defaults.thinkingDefault` を上書きします。 +- `reasoningDefault`: オプションの agent ごとのデフォルト reasoning 可視性（`on | off | stream`）。メッセージごとまたは session の reasoning オーバーライドが設定されていない場合に適用されます。 +- `fastModeDefault`: オプションの agent ごとの fast mode デフォルト（`true | false`）。メッセージごとまたは session の fast-mode オーバーライドが設定されていない場合に適用されます。 +- `embeddedHarness`: オプションの agent ごとの低レベル harness ポリシーオーバーライド。1 つの agent だけを Codex 専用にし、他の agent はデフォルトの Pi フォールバックを維持するには `{ runtime: "codex", fallback: "none" }` を使用します。 +- `runtime`: オプションの agent ごとのランタイム記述子。agent が ACP harness session をデフォルトにすべき場合は、`type: "acp"` と `runtime.acp` のデフォルト（`agent`、`backend`、`mode`、`cwd`）を使用します。 - `identity.avatar`: workspace 相対パス、`http(s)` URL、または `data:` URI。 - `identity` はデフォルトを導出します: `emoji` から `ackReaction`、`name`/`emoji` から `mentionPatterns`。 - `subagents.allowAgents`: `sessions_spawn` 用の agent id allowlist（`["*"]` = 任意、デフォルト: 同じ agent のみ）。 -- sandbox 継承ガード: 要求元 session が sandbox 化されている場合、`sessions_spawn` は sandbox なしで実行されるターゲットを拒否します。 -- `subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制、デフォルト: false）。 +- Sandbox 継承ガード: 要求元 session が sandbox 化されている場合、`sessions_spawn` は sandbox なしで実行されるターゲットを拒否します。 +- `subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制。デフォルト: false）。 --- -## マルチエージェントルーティング +## マルチ agent ルーティング 1 つの Gateway 内で複数の分離された agent を実行します。[Multi-Agent](/ja-JP/concepts/multi-agent) を参照してください。 @@ -1810,19 +1808,19 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Binding の match フィールド -- `type`（任意）: 通常のルーティングには `route`（type 省略時も route）、永続的な ACP 会話 binding には `acp` +- `type`（オプション）: 通常のルーティングには `route`（type 未指定も route 扱い）、永続 ACP 会話 binding には `acp` - `match.channel`（必須） -- `match.accountId`（任意。`*` = 任意のアカウント、省略 = デフォルトアカウント） -- `match.peer`（任意。`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（任意。channel 固有） -- `acp`（任意。`type: "acp"` のみ）: `{ mode, label, cwd, backend }` +- `match.accountId`（オプション。`*` = 任意のアカウント、省略 = デフォルトアカウント） +- `match.peer`（オプション。`{ kind: direct|group|channel, id }`） +- `match.guildId` / `match.teamId`（オプション。channel 固有） +- `acp`（オプション。`type: "acp"` の場合のみ）: `{ mode, label, cwd, backend }` **決定的な match 順序:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（peer/guild/team なしの完全一致） +4. `match.accountId`（完全一致、peer/guild/team なし） 5. `match.accountId: "*"`（channel 全体） 6. デフォルト agent @@ -1951,22 +1949,22 @@ scripts/sandbox-browser-setup.sh # optional browser image }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // この token 数を超える親スレッド fork はスキップ（0 で無効） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // duration または false + maxDiskBytes: "500mb", // オプションのハード予算 + highWaterBytes: "400mb", // オプションのクリーンアップ目標 }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // デフォルトの非アクティブ時自動 unfocus 時間（`0` で無効） + maxAgeHours: 0, // デフォルトのハード最大経過時間（`0` で無効） }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // legacy（ランタイムは常に "main" を使用） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1978,35 +1976,35 @@ scripts/sandbox-browser-setup.sh # optional browser image -- **`scope`**: グループチャット文脈向けの基本 session グループ化戦略。 - - `per-sender`（デフォルト）: channel 文脈内で、各送信者ごとに分離された session を使用します。 - - `global`: channel 文脈内のすべての参加者が 1 つの session を共有します（共有コンテキストを意図する場合にのみ使用してください）。 -- **`dmScope`**: DM のグループ化方法。 +- **`scope`**: グループチャットコンテキストに対する基本の session グループ化戦略です。 + - `per-sender`（デフォルト）: channel コンテキスト内で、各送信者が分離された session を持ちます。 + - `global`: channel コンテキスト内のすべての参加者が 1 つの session を共有します（共有コンテキストを意図する場合にのみ使用してください）。 +- **`dmScope`**: DM をどのようにグループ化するかです。 - `main`: すべての DM が main session を共有します。 - `per-peer`: channel をまたいで送信者 id ごとに分離します。 - - `per-channel-peer`: channel + 送信者ごとに分離します（複数ユーザーの inbox に推奨）。 - - `per-account-channel-peer`: account + channel + 送信者ごとに分離します（マルチアカウントに推奨）。 -- **`identityLinks`**: channel をまたぐ session 共有のために、正規 id を provider プレフィックス付き peer にマッピングします。 -- **`reset`**: 基本 reset ポリシー。`daily` はローカル時刻の `atHour` に reset し、`idle` は `idleMinutes` 経過後に reset します。両方が設定されている場合、先に期限切れになる方が優先されます。 -- **`resetByType`**: type ごとのオーバーライド（`direct`、`group`、`thread`）。従来の `dm` は `direct` の alias として受け付けます。 -- **`parentForkMaxTokens`**: fork された thread session を作成する際に許容される親 session の最大 `totalTokens`（デフォルト `100000`）。 - - 親の `totalTokens` がこの値を超える場合、OpenClaw は親 transcript 履歴を継承する代わりに新しい thread session を開始します。 + - `per-channel-peer`: channel + 送信者ごとに分離します（複数ユーザー inbox に推奨）。 + - `per-account-channel-peer`: account + channel + 送信者ごとに分離します（複数アカウントに推奨）。 +- **`identityLinks`**: channel をまたいだ session 共有のために、正規 id を provider 接頭辞付き peer にマップします。 +- **`reset`**: 主たるリセットポリシー。`daily` はローカル時刻の `atHour` にリセットし、`idle` は `idleMinutes` 後にリセットします。両方が設定されている場合は、先に期限切れになるほうが優先されます。 +- **`resetByType`**: タイプごとのオーバーライド（`direct`、`group`、`thread`）。従来の `dm` は `direct` のエイリアスとして受け付けられます。 +- **`parentForkMaxTokens`**: fork された thread session を作成するときに許可される親 session の `totalTokens` 上限（デフォルト `100000`）。 + - 親の `totalTokens` がこの値を超える場合、OpenClaw は親の transcript 履歴を継承する代わりに、新しい thread session を開始します。 - このガードを無効にして常に親 fork を許可するには `0` を設定します。 -- **`mainKey`**: 従来のフィールドです。runtime は main の direct-chat バケットに常に `"main"` を使用します。 -- **`agentToAgent.maxPingPongTurns`**: agent 間やり取り中の返信の往復回数の最大値（整数、範囲: `0`–`5`）。`0` は ping-pong 連鎖を無効にします。 -- **`sendPolicy`**: `channel`、`chatType`（`direct|group|channel`、従来の `dm` alias を含む）、`keyPrefix`、または `rawKeyPrefix` でマッチします。最初の deny が優先されます。 -- **`maintenance`**: session ストアのクリーンアップ + 保持制御。 - - `mode`: `warn` は警告のみ出力し、`enforce` はクリーンアップを適用します。 - - `pruneAfter`: 古いエントリの期限 cutoff（デフォルト `30d`）。 +- **`mainKey`**: legacy フィールドです。ランタイムは main の direct-chat バケットに常に `"main"` を使用します。 +- **`agentToAgent.maxPingPongTurns`**: agent 間のやり取りにおける agent 同士の返信往復の最大ターン数です（整数、範囲: `0`–`5`）。`0` は ping-pong チェーンを無効にします。 +- **`sendPolicy`**: `channel`、`chatType`（`direct|group|channel`。legacy の `dm` エイリアスあり）、`keyPrefix`、または `rawKeyPrefix` でマッチします。最初に一致した deny が優先されます。 +- **`maintenance`**: session ストアのクリーンアップ + 保持制御です。 + - `mode`: `warn` は警告のみを出し、`enforce` はクリーンアップを適用します。 + - `pruneAfter`: 古いエントリに対する経過時間のしきい値（デフォルト `30d`）。 - `maxEntries`: `sessions.json` 内の最大エントリ数（デフォルト `500`）。 - `rotateBytes`: `sessions.json` がこのサイズを超えたらローテーションします（デフォルト `10mb`）。 - - `resetArchiveRetention`: `*.reset.` transcript アーカイブの保持期間。デフォルトは `pruneAfter`。無効にするには `false` を設定します。 - - `maxDiskBytes`: 任意の sessions ディレクトリのディスク予算。`warn` モードでは警告をログ出力し、`enforce` モードでは最も古い artifact/session から削除します。 - - `highWaterBytes`: 予算クリーンアップ後の任意の目標値。デフォルトは `maxDiskBytes` の `80%` です。 -- **`threadBindings`**: thread-bound session 機能のグローバルデフォルト。 - - `enabled`: マスターのデフォルトスイッチ（provider ごとに上書き可能。Discord は `channels.discord.threadBindings.enabled` を使用） - - `idleHours`: 非アクティブ時の自動 unfocus を時間単位で指定するデフォルト（`0` で無効。provider ごとに上書き可能） - - `maxAgeHours`: ハードな最大経過時間を時間単位で指定するデフォルト（`0` で無効。provider ごとに上書き可能） + - `resetArchiveRetention`: `*.reset.` transcript アーカイブの保持期間。デフォルトでは `pruneAfter` に従います。無効にするには `false` を設定します。 + - `maxDiskBytes`: オプションの sessions ディレクトリのディスク予算。`warn` モードでは警告を記録し、`enforce` モードでは最も古い artifact/session から削除します。 + - `highWaterBytes`: 予算クリーンアップ後のオプションの目標値。デフォルトは `maxDiskBytes` の `80%` です。 +- **`threadBindings`**: スレッドバインドされた session 機能のグローバルデフォルトです。 + - `enabled`: マスターのデフォルトスイッチ（provider はオーバーライド可能。Discord は `channels.discord.threadBindings.enabled` を使用） + - `idleHours`: 非アクティブ時の自動 unfocus のデフォルト時間数（`0` で無効。provider はオーバーライド可能） + - `maxAgeHours`: ハードな最大経過時間のデフォルト時間数（`0` で無効。provider はオーバーライド可能） @@ -2017,7 +2015,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // または "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -2032,7 +2030,7 @@ scripts/sandbox-browser-setup.sh # optional browser image }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 で無効 byChannel: { whatsapp: 5000, slack: 1500, @@ -2042,38 +2040,38 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### レスポンスプレフィックス +### Response prefix channel/account ごとのオーバーライド: `channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解決順序（最も具体的なものが優先）: account → channel → global。`""` は無効化し、カスケードも停止します。`"auto"` は `[{identity.name}]` を導出します。 +解決順（最も具体的なものが優先）: account → channel → global。`""` は無効化し、カスケードも停止します。`"auto"` は `[{identity.name}]` を導出します。 **テンプレート変数:** -| 変数 | 説明 | 例 | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | 短い model 名 | `claude-opus-4-6` | -| `{modelFull}` | 完全な model 識別子 | `anthropic/claude-opus-4-6` | -| `{provider}` | provider 名 | `anthropic` | -| `{thinkingLevel}` | 現在の thinking レベル | `high`, `low`, `off` | -| `{identity.name}` | agent identity 名 | （`"auto"` と同じ） | +| Variable | 説明 | Example | +| ----------------- | ------------------------ | --------------------------- | +| `{model}` | 短い model 名 | `claude-opus-4-6` | +| `{modelFull}` | 完全な model 識別子 | `anthropic/claude-opus-4-6` | +| `{provider}` | provider 名 | `anthropic` | +| `{thinkingLevel}` | 現在の thinking レベル | `high`, `low`, `off` | +| `{identity.name}` | agent identity 名 | （`"auto"` と同じ） | -変数は大文字小文字を区別しません。`{think}` は `{thinkingLevel}` の alias です。 +変数は大文字小文字を区別しません。`{think}` は `{thinkingLevel}` のエイリアスです。 ### Ack reaction -- デフォルトはアクティブ agent の `identity.emoji`、それ以外は `"👀"` です。無効にするには `""` を設定します。 +- デフォルトはアクティブ agent の `identity.emoji`、それ以外の場合は `"👀"` です。無効にするには `""` を設定します。 - channel ごとのオーバーライド: `channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解決順序: account → channel → `messages.ackReaction` → identity フォールバック。 +- 解決順: account → channel → `messages.ackReaction` → identity フォールバック。 - スコープ: `group-mentions`（デフォルト）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`: Slack、Discord、Telegram で返信後に ack を削除します。 +- `removeAckAfterReply`: Slack、Discord、Telegram では返信後に ack を削除します。 - `messages.statusReactions.enabled`: Slack、Discord、Telegram でライフサイクル status reaction を有効にします。 - Slack と Discord では、未設定の場合、ack reaction が有効なら status reaction も有効のままになります。 + Slack と Discord では、未設定の場合、ack reaction がアクティブなとき status reaction は有効のままです。 Telegram では、ライフサイクル status reaction を有効にするには明示的に `true` を設定してください。 -### 受信 debounce +### Inbound debounce -同じ送信者からの短時間のテキストのみのメッセージを、1 回の agent turn にまとめます。media/attachments は即座に flush されます。制御コマンドは debouncing をバイパスします。 +同じ送信者からの短時間のテキストのみメッセージをまとめて 1 つの agent ターンにします。メディア/添付ファイルは即座にフラッシュされます。制御コマンドは debouncing をバイパスします。 ### TTS（text-to-speech） @@ -2116,12 +2114,12 @@ channel/account ごとのオーバーライド: `channels..responsePref } ``` -- `auto` はデフォルトの自動 TTS モードを制御します: `off`、`always`、`inbound`、または `tagged`。`/tts on|off` はローカル設定を上書きでき、`/tts status` は実効状態を表示します。 +- `auto` はデフォルトの自動 TTS モードを制御します: `off`、`always`、`inbound`、または `tagged`。`/tts on|off` はローカル設定を上書きでき、`/tts status` は有効状態を表示します。 - `summaryModel` は自動要約用に `agents.defaults.model.primary` を上書きします。 - `modelOverrides` はデフォルトで有効です。`modelOverrides.allowProvider` のデフォルトは `false`（オプトイン）です。 -- API キーは `ELEVENLABS_API_KEY`/`XI_API_KEY` および `OPENAI_API_KEY` にフォールバックします。 -- `openai.baseUrl` は OpenAI TTS エンドポイントを上書きします。解決順序は config、その次に `OPENAI_TTS_BASE_URL`、その次に `https://api.openai.com/v1` です。 -- `openai.baseUrl` が OpenAI 以外のエンドポイントを指している場合、OpenClaw はそれを OpenAI 互換 TTS サーバーとして扱い、model/voice の検証を緩和します。 +- API key は `ELEVENLABS_API_KEY`/`XI_API_KEY` および `OPENAI_API_KEY` にフォールバックします。 +- `openai.baseUrl` は OpenAI TTS エンドポイントを上書きします。解決順は config、次に `OPENAI_TTS_BASE_URL`、次に `https://api.openai.com/v1` です。 +- `openai.baseUrl` が OpenAI 以外のエンドポイントを指している場合、OpenClaw はそれを OpenAI 互換の TTS server として扱い、model/voice の検証を緩和します。 --- @@ -2151,51 +2149,51 @@ Talk mode（macOS/iOS/Android）のデフォルトです。 } ``` -- 複数の Talk provider を設定する場合、`talk.provider` は `talk.providers` 内のキーと一致する必要があります。 +- `talk.provider` は、複数の Talk provider が設定されている場合、`talk.providers` 内のキーと一致していなければなりません。 - 従来のフラットな Talk キー（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）は互換性専用であり、自動的に `talk.providers.` に移行されます。 - Voice ID は `ELEVENLABS_VOICE_ID` または `SAG_VOICE_ID` にフォールバックします。 - `providers.*.apiKey` は平文文字列または SecretRef オブジェクトを受け付けます。 -- `ELEVENLABS_API_KEY` のフォールバックは、Talk API キーが設定されていない場合にのみ適用されます。 -- `providers.*.voiceAliases` により、Talk ディレクティブでフレンドリー名を使用できます。 -- `silenceTimeoutMs` は、ユーザーが無言になってから transcript を送信するまで Talk mode が待機する時間を制御します。未設定の場合はプラットフォームのデフォルトの待機時間を使用します（`macOS と Android では 700 ms、iOS では 900 ms`）。 +- `ELEVENLABS_API_KEY` のフォールバックは、Talk API key が設定されていない場合にのみ適用されます。 +- `providers.*.voiceAliases` により、Talk ディレクティブでわかりやすい名前を使用できます。 +- `silenceTimeoutMs` は、Talk mode がユーザーの無音後どのくらい待ってから transcript を送信するかを制御します。未設定の場合はプラットフォームのデフォルトの待機時間を維持します（`macOS と Android では 700 ms、iOS では 900 ms`）。 --- ## Tools -### Tool profile +### tool profile -`tools.profile` は、`tools.allow`/`tools.deny` より前に基本 allowlist を設定します: +`tools.profile` は、`tools.allow`/`tools.deny` より前にベース allowlist を設定します: -ローカルのオンボーディングでは、未設定の場合に新しいローカル設定をデフォルトで `tools.profile: "coding"` にします（既存の明示的な profile は保持されます）。 +ローカルオンボーディングでは、未設定の新しいローカル設定に対して `tools.profile: "coding"` がデフォルト設定されます（既存の明示的な profile は保持されます）。 -| Profile | 含まれるもの | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `minimal` | `session_status` のみ | +| Profile | 含まれるもの | +| ----------- | ------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | `session_status` のみ | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | 制限なし（未設定と同じ） | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | 制限なし（未設定と同じ） | -### Tool group +### tool group -| Group | Tools | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`, `process`, `code_execution`（`bash` は `exec` の alias として受け付けます） | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Group | Tools | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution`（`bash` は `exec` のエイリアスとして受け付けられます） | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | すべての built-in tools（provider Plugin は除く） | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | すべての built-in tools（provider Plugin は除く） | ### `tools.allow` / `tools.deny` -グローバルな tool の allow/deny ポリシーです（deny が優先）。大文字小文字を区別せず、`*` ワイルドカードをサポートします。Docker sandbox が無効でも適用されます。 +グローバルな tool の allow/deny ポリシーです（deny が優先）。大文字小文字を区別せず、`*` ワイルドカードをサポートします。Docker sandbox がオフでも適用されます。 ```json5 { @@ -2205,7 +2203,7 @@ Talk mode（macOS/iOS/Android）のデフォルトです。 ### `tools.byProvider` -特定の provider または model に対してさらに tools を制限します。順序: 基本 profile → provider profile → allow/deny。 +特定の provider または model に対して tools をさらに制限します。順序: ベース profile → provider profile → allow/deny。 ```json5 { @@ -2221,7 +2219,7 @@ Talk mode（macOS/iOS/Android）のデフォルトです。 ### `tools.elevated` -sandbox 外での elevated `exec` アクセスを制御します: +sandbox 外での elevated exec アクセスを制御します: ```json5 { @@ -2238,8 +2236,8 @@ sandbox 外での elevated `exec` アクセスを制御します: ``` - agent ごとのオーバーライド（`agents.list[].tools.elevated`）は、さらに制限することしかできません。 -- `/elevated on|off|ask|full` は状態を session ごとに保存します。インライン directive は単一メッセージにのみ適用されます。 -- elevated `exec` は sandbox 化をバイパスし、設定された escape path（デフォルトは `gateway`、`exec` のターゲットが `node` の場合は `node`）を使用します。 +- `/elevated on|off|ask|full` は状態を session ごとに保存します。インラインディレクティブは単一メッセージに適用されます。 +- elevated `exec` は sandboxing をバイパスし、設定された escape path を使用します（デフォルトは `gateway`、exec ターゲットが `node` の場合は `node`）。 ### `tools.exec` @@ -2263,8 +2261,8 @@ sandbox 外での elevated `exec` アクセスを制御します: ### `tools.loopDetection` -tool ループ安全チェックはデフォルトでは**無効**です。検出を有効にするには `enabled: true` を設定してください。 -設定はグローバルの `tools.loopDetection` で定義でき、agent ごとに `agents.list[].tools.loopDetection` で上書きできます。 +tool ループ安全チェックはデフォルトで**無効**です。検出を有効にするには `enabled: true` を設定します。 +設定は `tools.loopDetection` でグローバルに定義でき、`agents.list[].tools.loopDetection` で agent ごとに上書きできます。 ```json5 { @@ -2285,13 +2283,13 @@ tool ループ安全チェックはデフォルトでは**無効**です。検 } ``` -- `historySize`: ループ解析用に保持する tool 呼び出し履歴の最大数。 -- `warningThreshold`: 警告を出す、進捗なしの繰り返しパターンのしきい値。 +- `historySize`: ループ分析のために保持される tool-call 履歴の最大数。 +- `warningThreshold`: 警告を出す、進捗のない繰り返しパターンのしきい値。 - `criticalThreshold`: 重大なループをブロックするための、より高い繰り返ししきい値。 -- `globalCircuitBreakerThreshold`: あらゆる進捗なし実行に対するハードストップしきい値。 -- `detectors.genericRepeat`: 同じ tool/同じ引数の呼び出し繰り返しで警告します。 +- `globalCircuitBreakerThreshold`: 進捗のない実行に対するハード停止しきい値。 +- `detectors.genericRepeat`: 同じ tool/同じ引数の繰り返し呼び出しで警告します。 - `detectors.knownPollNoProgress`: 既知の poll tool（`process.poll`、`command_status` など）で進捗がない場合に警告/ブロックします。 -- `detectors.pingPong`: 進捗なしの交互ペアパターンに対して警告/ブロックします。 +- `detectors.pingPong`: 進捗のない交互ペアパターンで警告/ブロックします。 - `warningThreshold >= criticalThreshold` または `criticalThreshold >= globalCircuitBreakerThreshold` の場合、検証は失敗します。 ### `tools.web` @@ -2302,14 +2300,14 @@ tool ループ安全チェックはデフォルトでは**無効**です。検 web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // または BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // オプション。自動検出するには省略 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2326,7 +2324,7 @@ tool ループ安全チェックはデフォルトでは**無効**です。検 ### `tools.media` -受信 media 理解（image/audio/video）を設定します: +受信メディア理解（画像/音声/動画）を設定します: ```json5 { @@ -2334,7 +2332,7 @@ tool ループ安全チェックはデフォルトでは**無効**です。検 media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // オプトイン: 完了した async 音楽/動画を channel に直接送信 }, audio: { enabled: true, @@ -2358,7 +2356,7 @@ tool ループ安全チェックはデフォルトでは**無効**です。検 } ``` - + **Provider エントリ**（`type: "provider"` または省略）: @@ -2368,21 +2366,21 @@ tool ループ安全チェックはデフォルトでは**無効**です。検 **CLI エントリ**（`type: "cli"`）: -- `command`: 実行する実行ファイル +- `command`: 実行する executable - `args`: テンプレート化された引数（`{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` などをサポート） **共通フィールド:** -- `capabilities`: 任意のリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → image、`google` → image+audio+video、`groq` → audio。 +- `capabilities`: オプションのリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → image、`google` → image+audio+video、`groq` → audio。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリごとのオーバーライド。 - 失敗時は次のエントリにフォールバックします。 -provider 認証は標準順序に従います: `auth-profiles.json` → 環境変数 → `models.providers.*.apiKey`。 +provider の auth は標準順に従います: `auth-profiles.json` → env vars → `models.providers.*.apiKey`。 -**非同期完了フィールド:** +**Async completion フィールド:** -- `asyncCompletion.directSend`: `true` の場合、完了した非同期 `music_generate` - と `video_generate` タスクは、まず direct な channel 配信を試みます。デフォルト: `false` +- `asyncCompletion.directSend`: `true` の場合、完了した async `music_generate` + および `video_generate` タスクはまず direct channel 配信を試みます。デフォルト: `false` （従来の requester-session wake/model-delivery パス）。 @@ -2402,9 +2400,9 @@ provider 認証は標準順序に従います: `auth-profiles.json` → 環境 ### `tools.sessions` -session tool（`sessions_list`、`sessions_history`、`sessions_send`）で、どの session を対象にできるかを制御します。 +session tools（`sessions_list`、`sessions_history`、`sessions_send`）でどの session を対象にできるかを制御します。 -デフォルト: `tree`（現在の session + そこから spawn された session、たとえば subagent）。 +デフォルト: `tree`（現在の session + そこから spawn された session。subagent など）。 ```json5 { @@ -2420,25 +2418,25 @@ session tool（`sessions_list`、`sessions_history`、`sessions_send`）で、 注意: - `self`: 現在の session key のみ。 -- `tree`: 現在の session + 現在の session が spawn した session（subagent）。 -- `agent`: 現在の agent id に属する任意の session（同じ agent id 配下で per-sender session を実行している場合は他のユーザーも含むことがあります）。 +- `tree`: 現在の session + 現在の session から spawn された session（subagent）。 +- `agent`: 現在の agent id に属する任意の session（同じ agent id の下で per-sender session を実行している場合、他のユーザーを含むことがあります）。 - `all`: 任意の session。agent をまたぐターゲティングには引き続き `tools.agentToAgent` が必要です。 -- sandbox clamp: 現在の session が sandbox 化されており、`agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` であっても visibility は `tree` に強制されます。 +- Sandbox clamp: 現在の session が sandbox 化されていて、`agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` でも visibility は `tree` に強制されます。 ### `tools.sessions_spawn` -`sessions_spawn` のインライン attachment サポートを制御します。 +`sessions_spawn` のインライン添付ファイルサポートを制御します。 ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // オプトイン: インラインファイル添付を許可するには true + maxTotalBytes: 5242880, // 全ファイル合計で 5 MB maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // ファイルごとに 1 MB + retainOnSessionKeep: false, // cleanup="keep" のときに添付ファイルを保持 }, }, }, @@ -2447,22 +2445,22 @@ session tool（`sessions_list`、`sessions_history`、`sessions_send`）で、 注意: -- attachment は `runtime: "subagent"` でのみサポートされます。ACP runtime はそれらを拒否します。 -- ファイルは子 workspace の `.openclaw/attachments//` に `.manifest.json` とともに実体化されます。 -- attachment 内容は transcript 永続化から自動的に redaction されます。 -- Base64 入力は、厳格な alphabet/padding チェックと、デコード前サイズガードで検証されます。 +- 添付ファイルは `runtime: "subagent"` でのみサポートされます。ACP runtime はこれを拒否します。 +- ファイルは子 workspace の `.openclaw/attachments//` に `.manifest.json` とともに具現化されます。 +- 添付ファイルの内容は transcript の永続化から自動的に秘匿化されます。 +- Base64 入力は、厳格な alphabet/padding チェックとデコード前サイズガードで検証されます。 - ファイル権限は、ディレクトリが `0700`、ファイルが `0600` です。 -- クリーンアップは `cleanup` ポリシーに従います: `delete` は常に attachment を削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 +- クリーンアップは `cleanup` ポリシーに従います: `delete` は常に添付ファイルを削除し、`keep` は `retainOnSessionKeep: true` のときのみ保持します。 ### `tools.experimental` -実験的な built-in tool フラグです。strict-agentic GPT-5 の自動有効化ルールが適用される場合を除き、デフォルトは off です。 +実験的な built-in tool フラグです。strict-agentic GPT-5 の自動有効化ルールが適用される場合を除き、デフォルトではオフです。 ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // 実験的な update_plan を有効化 }, }, } @@ -2470,9 +2468,9 @@ session tool（`sessions_list`、`sessions_history`、`sessions_send`）で、 注意: -- `planTool`: 自明でない複数ステップ作業の追跡のために、構造化された `update_plan` tool を有効にします。 -- デフォルト: `false`。ただし、`agents.defaults.embeddedPi.executionContract`（または agent ごとのオーバーライド）が OpenAI または OpenAI Codex の GPT-5 ファミリー実行に対して `"strict-agentic"` に設定されている場合は除きます。その範囲外でも強制的に有効にするには `true` を設定し、strict-agentic GPT-5 実行でも無効のままにするには `false` を設定します。 -- 有効な場合、system prompt にも使用ガイダンスが追加され、model はそれを実質的な作業にのみ使い、`in_progress` のステップを最大 1 つに保ちます。 +- `planTool`: 自明でない複数ステップ作業の追跡のための、構造化された `update_plan` tool を有効にします。 +- デフォルト: `false`。ただし `agents.defaults.embeddedPi.executionContract`（または agent ごとのオーバーライド）が OpenAI または OpenAI Codex の GPT-5 ファミリー実行で `"strict-agentic"` に設定されている場合を除きます。この範囲外でも tool を強制的に有効にするには `true` を設定し、strict-agentic GPT-5 実行でも無効のままにするには `false` を設定します。 +- 有効にすると、system prompt にも使用ガイダンスが追加され、model はこれを重要な作業にのみ使用し、`in_progress` のステップは常に最大 1 つまでに保ちます。 ### `agents.defaults.subagents` @@ -2493,20 +2491,20 @@ session tool（`sessions_list`、`sessions_history`、`sessions_send`）で、 ``` - `model`: spawn される sub-agent のデフォルト model。省略した場合、sub-agent は呼び出し元の model を継承します。 -- `allowAgents`: 要求元 agent が独自の `subagents.allowAgents` を設定していない場合の、`sessions_spawn` で対象にできる agent id のデフォルト allowlist（`["*"]` = 任意、デフォルト: 同じ agent のみ）。 -- `runTimeoutSeconds`: tool 呼び出しで `runTimeoutSeconds` が省略された場合の、`sessions_spawn` のデフォルト timeout（秒）。`0` は timeout なしを意味します。 +- `allowAgents`: 要求元 agent が独自の `subagents.allowAgents` を設定していない場合の、`sessions_spawn` 用ターゲット agent id のデフォルト allowlist（`["*"]` = 任意、デフォルト: 同じ agent のみ）。 +- `runTimeoutSeconds`: tool 呼び出しで `runTimeoutSeconds` が省略された場合の、`sessions_spawn` のデフォルトタイムアウト（秒）。`0` はタイムアウトなしを意味します。 - subagent ごとの tool ポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## カスタム provider と base URL -OpenClaw は組み込み model カタログを使用します。カスタム provider は config 内の `models.providers` または `~/.openclaw/agents//agent/models.json` を通じて追加します。 +OpenClaw は built-in の model カタログを使用します。カスタム provider は config の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加します。 ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge（デフォルト）| replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2530,48 +2528,48 @@ OpenClaw は組み込み model カタログを使用します。カスタム pro } ``` -- カスタム認証が必要な場合は `authHeader: true` + `headers` を使用します。 -- agent 設定ルートは `OPENCLAW_AGENT_DIR`（または従来の環境変数 alias である `PI_CODING_AGENT_DIR`）で上書きできます。 +- カスタム認証が必要な場合は `authHeader: true` + `headers` を使用してください。 +- agent 設定ルートは `OPENCLAW_AGENT_DIR`（または legacy の環境変数エイリアス `PI_CODING_AGENT_DIR`）で上書きします。 - 一致する provider ID に対するマージ優先順位: - 空でない agent `models.json` の `baseUrl` 値が優先されます。 - - 空でない agent の `apiKey` 値は、その provider が現在の config/auth-profile 文脈で SecretRef 管理されていない場合にのみ優先されます。 - - SecretRef 管理された provider の `apiKey` 値は、解決済み secret を永続化する代わりに、ソースマーカー（env ref では `ENV_VAR_NAME`、file/exec ref では `secretref-managed`）から再取得されます。 - - SecretRef 管理された provider header 値も、ソースマーカー（env ref では `secretref-env:ENV_VAR_NAME`、file/exec ref では `secretref-managed`）から再取得されます。 - - 空、または欠落した agent `apiKey`/`baseUrl` は、config の `models.providers` にフォールバックします。 - - 一致する model の `contextWindow`/`maxTokens` は、明示的な config 値と暗黙のカタログ値のうち高い方を使用します。 - - 一致する model の `contextTokens` は、存在する場合に明示的な runtime 上限を保持します。ネイティブ model メタデータを変更せずに有効コンテキストを制限するにはこれを使用してください。 + - 空でない agent `apiKey` 値は、その provider が現在の config/auth-profile コンテキストで SecretRef 管理されていない場合にのみ優先されます。 + - SecretRef 管理の provider `apiKey` 値は、解決済み secret を永続化する代わりに、ソースマーカー（env ref なら `ENV_VAR_NAME`、file/exec ref なら `secretref-managed`）から再取得されます。 + - SecretRef 管理の provider header 値は、ソースマーカー（env ref なら `secretref-env:ENV_VAR_NAME`、file/exec ref なら `secretref-managed`）から再取得されます。 + - 空または欠落した agent `apiKey`/`baseUrl` は、config の `models.providers` にフォールバックします。 + - 一致する model の `contextWindow`/`maxTokens` は、明示的な config 値と暗黙のカタログ値の高いほうを使用します。 + - 一致する model の `contextTokens` は、明示的なランタイム上限が存在する場合はそれを保持します。ネイティブ model メタデータを変更せずに有効コンテキストを制限するために使用してください。 - config で `models.json` を完全に上書きしたい場合は `models.mode: "replace"` を使用します。 - - マーカーの永続化はソースを正として行われます。マーカーは、解決済み runtime secret 値からではなく、アクティブなソース config snapshot（解決前）から書き込まれます。 + - マーカーの永続化はソースを正とします: マーカーは、解決済みランタイム secret 値ではなく、アクティブなソース config スナップショット（解決前）から書き込まれます。 ### Provider フィールドの詳細 - `models.mode`: provider カタログの動作（`merge` または `replace`）。 -- `models.providers`: provider id をキーにしたカスタム provider マップ。 -- `models.providers.*.api`: リクエストアダプター（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。 -- `models.providers.*.apiKey`: provider 資格情報（SecretRef/環境変数置換を推奨）。 -- `models.providers.*.auth`: 認証戦略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` 向けに、リクエストへ `options.num_ctx` を注入します（デフォルト: `true`）。 -- `models.providers.*.authHeader`: 必要な場合に、資格情報を `Authorization` ヘッダーで送るよう強制します。 +- `models.providers`: provider id をキーとするカスタム provider マップ。 +- `models.providers.*.api`: リクエストアダプタ（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` など）。 +- `models.providers.*.apiKey`: provider 資格情報（SecretRef/env 置換を推奨）。 +- `models.providers.*.auth`: auth 戦略（`api-key`、`token`、`oauth`、`aws-sdk`）。 +- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions` 用で、リクエストに `options.num_ctx` を注入します（デフォルト: `true`）。 +- `models.providers.*.authHeader`: 必要な場合に `Authorization` ヘッダーでの資格情報送信を強制します。 - `models.providers.*.baseUrl`: 上流 API の base URL。 -- `models.providers.*.headers`: proxy/tenant ルーティング用の追加静的ヘッダー。 +- `models.providers.*.headers`: proxy/tenant ルーティング用の追加の静的ヘッダー。 - `models.providers.*.request`: model-provider HTTP リクエスト用の転送オーバーライド。 - - `request.headers`: 追加ヘッダー（provider デフォルトとマージ）。値には SecretRef を指定できます。 - - `request.auth`: 認証戦略オーバーライド。モード: `"provider-default"`（provider 組み込み認証を使用）、`"authorization-bearer"`（`token` と併用）、`"header"`（`headerName`、`value`、任意の `prefix` と併用）。 - - `request.proxy`: HTTP proxy オーバーライド。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` 環境変数を使用）、`"explicit-proxy"`（`url` と併用）。どちらのモードでも任意の `tls` サブオブジェクトを受け付けます。 - - `request.tls`: 直接接続向けの TLS オーバーライド。フィールド: `ca`、`cert`、`key`、`passphrase`（すべて SecretRef を受け付けます）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`: `true` の場合、DNS 解決先が private、CGNAT、または類似の範囲であっても、provider HTTP fetch ガード経由で `baseUrl` への HTTPS を許可します（信頼できるセルフホスト OpenAI 互換エンドポイント向けの operator オプトイン）。WebSocket はヘッダー/TLS に同じ `request` を使用しますが、その fetch SSRF ガードは使用しません。デフォルトは `false`。 + - `request.headers`: 追加ヘッダー（provider デフォルトとマージされます）。値は SecretRef を受け付けます。 + - `request.auth`: auth 戦略のオーバーライド。モード: `"provider-default"`（provider の built-in auth を使用）、`"authorization-bearer"`（`token` を使用）、`"header"`（`headerName`、`value`、オプションの `prefix` を使用）。 + - `request.proxy`: HTTP proxy のオーバーライド。モード: `"env-proxy"`（`HTTP_PROXY`/`HTTPS_PROXY` env vars を使用）、`"explicit-proxy"`（`url` を使用）。どちらのモードでもオプションの `tls` サブオブジェクトを受け付けます。 + - `request.tls`: 直接接続用の TLS オーバーライド。フィールド: `ca`、`cert`、`key`、`passphrase`（すべて SecretRef を受け付けます）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`: `true` の場合、provider HTTP fetch ガード経由で、DNS が private、CGNAT、または類似の範囲に解決される `baseUrl` への HTTPS を許可します（信頼できる self-hosted OpenAI 互換エンドポイントに対する operator のオプトイン）。WebSocket はヘッダー/TLS に同じ `request` を使用しますが、その fetch SSRF ガードは使用しません。デフォルトは `false`。 - `models.providers.*.models`: 明示的な provider model カタログエントリ。 - `models.providers.*.models.*.contextWindow`: ネイティブ model のコンテキストウィンドウメタデータ。 -- `models.providers.*.models.*.contextTokens`: 任意の runtime コンテキスト上限。model のネイティブ `contextWindow` より小さい有効コンテキスト予算を使いたい場合に使用します。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`: 任意の互換性ヒント。`api: "openai-completions"` で `baseUrl` が空でなく、かつ非ネイティブ（host が `api.openai.com` ではない）場合、OpenClaw は runtime でこれを `false` に強制します。`baseUrl` が空または省略されている場合は、デフォルトの OpenAI 動作を維持します。 -- `models.providers.*.models.*.compat.requiresStringContent`: 文字列のみを受け付ける OpenAI 互換 chat エンドポイント向けの任意の互換性ヒント。`true` の場合、OpenClaw はリクエスト送信前に、純テキストの `messages[].content` 配列をプレーン文字列へ平坦化します。 +- `models.providers.*.models.*.contextTokens`: オプションのランタイムコンテキスト上限。model のネイティブ `contextWindow` より小さい有効コンテキスト予算にしたい場合に使用します。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`: オプションの互換性ヒント。`api: "openai-completions"` で空でない非ネイティブ `baseUrl`（host が `api.openai.com` ではない）の場合、OpenClaw はランタイムでこれを `false` に強制します。空または省略された `baseUrl` はデフォルトの OpenAI 動作を維持します。 +- `models.providers.*.models.*.compat.requiresStringContent`: 文字列のみを受け付ける OpenAI 互換 chat エンドポイント向けのオプションの互換性ヒント。`true` の場合、OpenClaw はリクエスト送信前に純テキストの `messages[].content` 配列を平文文字列へフラット化します。 - `plugins.entries.amazon-bedrock.config.discovery`: Bedrock 自動検出設定のルート。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙の検出を有効/無効にします。 -- `plugins.entries.amazon-bedrock.config.discovery.region`: 検出用の AWS region。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 対象を絞った検出用の任意の provider-id フィルター。 +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙的な検出をオン/オフします。 +- `plugins.entries.amazon-bedrock.config.discovery.region`: 検出用の AWS リージョン。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: ターゲットを絞った検出用のオプションの provider-id フィルター。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: 検出更新のポーリング間隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出された model 用のフォールバック context window。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出された model 用のフォールバック最大出力 token 数。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出された model のフォールバックコンテキストウィンドウ。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出された model のフォールバック最大出力 token 数。 ### Provider の例 @@ -2609,7 +2607,7 @@ OpenClaw は組み込み model カタログを使用します。カスタム pro } ``` -Cerebras には `cerebras/zai-glm-4.7` を使用してください。Z.AI 直接接続には `zai/glm-4.7` を使用します。 +Cerebras には `cerebras/zai-glm-4.7` を使用し、Z.AI 直結には `zai/glm-4.7` を使用します。 @@ -2626,7 +2624,7 @@ Cerebras には `cerebras/zai-glm-4.7` を使用してください。Z.AI 直接 } ``` -`OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`）を設定してください。Zen カタログには `opencode/...` 参照を、Go カタログには `opencode-go/...` 参照を使用します。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。 +`OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`）を設定します。Zen カタログには `opencode/...` 参照を使い、Go カタログには `opencode-go/...` 参照を使います。ショートカット: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go`。 @@ -2643,11 +2641,11 @@ Cerebras には `cerebras/zai-glm-4.7` を使用してください。Z.AI 直接 } ``` -`ZAI_API_KEY` を設定してください。`z.ai/*` と `z-ai/*` はどちらも alias として受け付けられます。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 +`ZAI_API_KEY` を設定します。`z.ai/*` と `z-ai/*` は受け付けられるエイリアスです。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 - 一般エンドポイント: `https://api.z.ai/api/paas/v4` - コーディングエンドポイント（デフォルト）: `https://api.z.ai/api/coding/paas/v4` -- 一般エンドポイントを使う場合は、base URL オーバーライド付きのカスタム provider を定義してください。 +- 一般エンドポイント用には、base URL オーバーライド付きのカスタム provider を定義します。 @@ -2686,11 +2684,9 @@ Cerebras には `cerebras/zai-glm-4.7` を使用してください。Z.AI 直接 } ``` -China エンドポイント用: `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn`。 +中国エンドポイントには `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn` を使用します。 -ネイティブ Moonshot エンドポイントは、共有の -`openai-completions` 転送上でストリーミング利用互換性を公開しており、OpenClaw は -組み込み provider id だけでなく、そのエンドポイント capability に基づいてこれを判定します。 +ネイティブ Moonshot エンドポイントは、共有 `openai-completions` 転送上でストリーミング利用互換性を通知し、OpenClaw は built-in provider id 単独ではなく、そのエンドポイント機能に基づいてこれを判断します。 @@ -2708,7 +2704,7 @@ China エンドポイント用: `baseUrl: "https://api.moonshot.cn/v1"` また } ``` -Anthropic 互換の組み込み provider です。ショートカット: `openclaw onboard --auth-choice kimi-code-api-key`。 +Anthropic 互換の built-in provider です。ショートカット: `openclaw onboard --auth-choice kimi-code-api-key`。 @@ -2751,7 +2747,7 @@ base URL には `/v1` を含めないでください（Anthropic クライアン - + ```json5 { @@ -2787,12 +2783,12 @@ base URL には `/v1` を含めないでください（Anthropic クライアン } ``` -`MINIMAX_API_KEY` を設定してください。ショートカット: +`MINIMAX_API_KEY` を設定します。ショートカット: `openclaw onboard --auth-choice minimax-global-api` または `openclaw onboard --auth-choice minimax-cn-api`。 model カタログのデフォルトは M2.7 のみです。 -Anthropic 互換ストリーミングパスでは、OpenClaw は -明示的に `thinking` を設定しない限り、MiniMax thinking をデフォルトで無効にします。`/fast on` または +Anthropic 互換ストリーミングパスでは、OpenClaw は明示的に `thinking` を設定しない限り、 +デフォルトで MiniMax の thinking を無効にします。`/fast on` または `params.fastMode: true` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。 @@ -2800,7 +2796,7 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は -[Local Models](/ja-JP/gateway/local-models) を参照してください。要点: 十分なハードウェア上で LM Studio Responses API を使って大きなローカル model を実行し、フォールバック用にホスト型 model はマージしたままにしてください。 +[Local Models](/ja-JP/gateway/local-models) を参照してください。要点: 十分なハードウェア上の LM Studio Responses API 経由で大きなローカル model を実行し、フォールバックのためにホスト型 model はマージしたままにしてください。 @@ -2821,7 +2817,7 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // または平文文字列 env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2831,14 +2827,12 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は } ``` -- `allowBundled`: bundled Skills のみを対象にした任意の allowlist です（managed/workspace Skills には影響しません）。 +- `allowBundled`: bundled Skills のみを対象とするオプションの allowlist です（managed/workspace Skills には影響しません）。 - `load.extraDirs`: 追加の共有 skill ルート（最も低い優先順位）。 -- `install.preferBrew`: true の場合、`brew` が利用可能なら - 他の installer 種類にフォールバックする前に Homebrew installer を優先します。 -- `install.nodeManager`: `metadata.openclaw.install` - spec 用の node installer 優先設定（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false` は、bundled/installed されていても skill を無効にします。 -- `entries..apiKey`: プライマリ環境変数を宣言する Skills 向けの簡易設定です（平文文字列または SecretRef オブジェクト）。 +- `install.preferBrew`: `true` の場合、`brew` が利用可能であれば他の installer 種別にフォールバックする前に Homebrew installer を優先します。 +- `install.nodeManager`: `metadata.openclaw.install` 指定に対する node installer の優先設定（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false` は、bundled/installed であってもその skill を無効にします。 +- `entries..apiKey`: プライマリ env var を宣言する skill 用の簡易設定です（平文文字列または SecretRef オブジェクト）。 --- @@ -2867,40 +2861,40 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は ``` - `~/.openclaw/extensions`、`/.openclaw/extensions`、および `plugins.load.paths` から読み込まれます。 -- 検出は、ネイティブ OpenClaw Plugin に加え、互換性のある Codex bundle と Claude bundle も受け付けます。manifest のない Claude デフォルトレイアウト bundle も含まれます。 -- **設定変更には Gateway の再起動が必要です。** -- `allow`: 任意の allowlist（リストされた Plugin のみ読み込まれます）。`deny` が優先されます。 -- `plugins.entries..apiKey`: Plugin レベルの API キー簡易フィールド（Plugin がサポートしている場合）。 -- `plugins.entries..env`: Plugin スコープの環境変数マップ。 -- `plugins.entries..hooks.allowPromptInjection`: `false` の場合、core は `before_prompt_build` をブロックし、従来の `before_agent_start` 由来の prompt 変更フィールドを無視します。一方で、従来の `modelOverride` と `providerOverride` は保持されます。これはネイティブ Plugin hook と、サポートされている bundle 提供 hook ディレクトリに適用されます。 -- `plugins.entries..subagent.allowModelOverride`: この Plugin がバックグラウンド subagent 実行に対して、実行ごとの `provider` と `model` オーバーライドを要求できるよう明示的に信頼します。 -- `plugins.entries..subagent.allowedModels`: 信頼された subagent オーバーライドに対する、正規の `provider/model` ターゲットの任意 allowlist。任意の model を許可したい意図がある場合にのみ `"*"` を使用してください。 +- 検出はネイティブ OpenClaw Plugin に加え、互換性のある Codex bundle と Claude bundle を受け付けます。これには manifest なしの Claude デフォルトレイアウト bundle も含まれます。 +- **設定変更には gateway の再起動が必要です。** +- `allow`: オプションの allowlist（一覧にある Plugin のみ読み込まれます）。`deny` が優先されます。 +- `plugins.entries..apiKey`: Plugin レベルの API key 簡易フィールド（Plugin がサポートしている場合）。 +- `plugins.entries..env`: Plugin スコープの env var マップ。 +- `plugins.entries..hooks.allowPromptInjection`: `false` の場合、core は `before_prompt_build` をブロックし、legacy の `before_agent_start` からの prompt 変更フィールドを無視します。一方で legacy の `modelOverride` と `providerOverride` は保持されます。ネイティブ Plugin hook と、サポートされる bundle 提供 hook ディレクトリに適用されます。 +- `plugins.entries..subagent.allowModelOverride`: この Plugin がバックグラウンド subagent 実行に対して実行ごとの `provider` と `model` のオーバーライドを要求することを明示的に信頼します。 +- `plugins.entries..subagent.allowedModels`: 信頼された subagent オーバーライド向けの、正規 `provider/model` ターゲットのオプションの allowlist。任意の model を許可したいことを意図している場合にのみ `"*"` を使用してください。 - `plugins.entries..config`: Plugin 定義の設定オブジェクト（利用可能な場合はネイティブ OpenClaw Plugin schema で検証されます）。 -- `plugins.entries.firecrawl.config.webFetch`: Firecrawl web-fetch provider 設定。 - - `apiKey`: Firecrawl API キー（SecretRef を受け付けます）。`plugins.entries.firecrawl.config.webSearch.apiKey`、従来の `tools.web.fetch.firecrawl.apiKey`、または `FIRECRAWL_API_KEY` 環境変数にフォールバックします。 - - `baseUrl`: Firecrawl API の base URL（デフォルト: `https://api.firecrawl.dev`）。 +- `plugins.entries.firecrawl.config.webFetch`: Firecrawl の web-fetch provider 設定。 + - `apiKey`: Firecrawl API key（SecretRef を受け付けます）。`plugins.entries.firecrawl.config.webSearch.apiKey`、legacy の `tools.web.fetch.firecrawl.apiKey`、または `FIRECRAWL_API_KEY` env var にフォールバックします。 + - `baseUrl`: Firecrawl API base URL（デフォルト: `https://api.firecrawl.dev`）。 - `onlyMainContent`: ページからメインコンテンツのみを抽出します（デフォルト: `true`）。 - - `maxAgeMs`: キャッシュの最大有効期間（ミリ秒、デフォルト: `172800000` / 2 日）。 - - `timeoutSeconds`: スクレイプ要求の timeout（秒、デフォルト: `60`）。 + - `maxAgeMs`: キャッシュの最大経過時間（ミリ秒）（デフォルト: `172800000` / 2 日）。 + - `timeoutSeconds`: scrape リクエストのタイムアウト秒数（デフォルト: `60`）。 - `plugins.entries.xai.config.xSearch`: xAI X Search（Grok web search）設定。 - `enabled`: X Search provider を有効にします。 - `model`: 検索に使用する Grok model（例: `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`: memory dreaming 設定。フェーズとしきい値は [Dreaming](/ja-JP/concepts/dreaming) を参照してください。 - - `enabled`: dreaming のマスタースイッチ（デフォルト `false`）。 - - `frequency`: 各 dreaming フルスイープの Cron 間隔（デフォルト `"0 3 * * *"`）。 - - phase ポリシーとしきい値は実装詳細であり、ユーザー向け設定キーではありません。 -- memory の完全な設定は [Memory configuration reference](/ja-JP/reference/memory-config) にあります: +- `plugins.entries.memory-core.config.dreaming`: memory Dreaming 設定。フェーズとしきい値については [Dreaming](/ja-JP/concepts/dreaming) を参照してください。 + - `enabled`: Dreaming のマスタースイッチ（デフォルト `false`）。 + - `frequency`: 各フル Dreaming スイープの Cron 間隔（デフォルトは `"0 3 * * *"`）。 + - フェーズポリシーとしきい値は実装詳細です（ユーザー向け設定キーではありません）。 +- 完全な memory 設定は [Memory configuration reference](/ja-JP/reference/memory-config) にあります: - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 有効な Claude bundle Plugin は、`settings.json` から embedded Pi デフォルトを提供することもできます。OpenClaw はそれらを生の OpenClaw config patch としてではなく、サニタイズされた agent 設定として適用します。 -- `plugins.slots.memory`: アクティブな memory Plugin id を選択します。memory Plugin を無効にするには `"none"` を指定します。 +- 有効な Claude bundle Plugin は、`settings.json` から組み込み Pi デフォルトを提供することもできます。OpenClaw はそれらを生の OpenClaw 設定パッチとしてではなく、サニタイズされた agent 設定として適用します。 +- `plugins.slots.memory`: アクティブな memory Plugin id を選択するか、memory Plugin を無効にするには `"none"` を指定します。 - `plugins.slots.contextEngine`: アクティブな context engine Plugin id を選択します。別の engine をインストールして選択しない限り、デフォルトは `"legacy"` です。 -- `plugins.installs`: `openclaw plugins update` が使用する CLI 管理インストールメタデータ。 +- `plugins.installs`: `openclaw plugins update` で使用される CLI 管理のインストールメタデータ。 - `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt` を含みます。 - - `plugins.installs.*` は管理状態として扱い、手動編集よりも CLI コマンドを優先してください。 + - `plugins.installs.*` は管理状態として扱い、手動編集より CLI コマンドを優先してください。 [Plugins](/ja-JP/tools/plugin) を参照してください。 @@ -2915,8 +2909,8 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // 信頼できる private-network アクセスでのみオプトイン + // allowPrivateNetwork: true, // legacy エイリアス // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2943,28 +2937,30 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は ``` - `evaluateEnabled: false` は `act:evaluate` と `wait --fn` を無効にします。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定時には無効であるため、browser ナビゲーションはデフォルトで strict のままです。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定時は無効なので、browser ナビゲーションはデフォルトで strict のままです。 - `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` は、private-network browser ナビゲーションを意図的に信頼する場合にのみ設定してください。 -- strict mode では、リモート CDP profile エンドポイント（`profiles.*.cdpUrl`）も、到達性/検出チェック中に同じ private-network ブロックの対象になります。 -- `ssrfPolicy.allowPrivateNetwork` は従来の alias として引き続きサポートされます。 -- strict mode では、明示的な例外に `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使用してください。 +- strict モードでは、リモート CDP profile エンドポイント（`profiles.*.cdpUrl`）にも、到達性/検出チェック時に同じ private-network ブロックが適用されます。 +- `ssrfPolicy.allowPrivateNetwork` は legacy エイリアスとして引き続きサポートされます。 +- strict モードでは、明示的な例外のために `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使用します。 - リモート profile は attach-only です（start/stop/reset は無効）。 - `profiles.*.cdpUrl` は `http://`、`https://`、`ws://`、`wss://` を受け付けます。 - provider に直接の DevTools WebSocket URL がある場合は WS(S) を、 + provider が直接の DevTools WebSocket URL を提供する場合は WS(S) を、 OpenClaw に `/json/version` を検出させたい場合は HTTP(S) を使用してください。 -- `existing-session` profile はホスト専用で、CDP の代わりに Chrome MCP を使用します。 -- `existing-session` profile は、Brave や Edge のような特定の +- `existing-session` profile は CDP の代わりに Chrome MCP を使用し、 + 選択された host 上、または接続された browser Node を通じて attach できます。 +- `existing-session` profile では、Brave や Edge のような特定の Chromium ベース browser profile を対象にするために `userDataDir` を設定できます。 - `existing-session` profile は、現在の Chrome MCP ルート制限を維持します: - CSS セレクター指定ではなく snapshot/ref ベースのアクション、単一ファイルのアップロード - hook、dialog timeout オーバーライドなし、`wait --load networkidle` なし、 - `responsebody`、PDF export、download interception、batch action なし。 -- ローカル管理の `openclaw` profile は `cdpPort` と `cdpUrl` を自動割り当てします。明示的に - `cdpUrl` を設定するのはリモート CDP の場合だけにしてください。 -- 自動検出順序: デフォルト browser が Chromium ベースならそれを優先 → Chrome → Brave → Edge → Chromium → Chrome Canary。 + CSS セレクターターゲティングではなく snapshot/ref ベースのアクション、 + 単一ファイルのアップロード hook、dialog タイムアウトオーバーライドなし、 + `wait --load networkidle` なし、そして `responsebody`、PDF エクスポート、 + ダウンロードのインターセプト、batch アクションもありません。 +- ローカル管理の `openclaw` profile は `cdpPort` と `cdpUrl` を自動割り当てします。 + 明示的に `cdpUrl` を設定するのはリモート CDP の場合だけにしてください。 +- 自動検出順: デフォルト browser が Chromium ベースならそれを優先 → Chrome → Brave → Edge → Chromium → Chrome Canary。 - Control service: loopback のみ（port は `gateway.port` から導出、デフォルト `18791`）。 -- `extraArgs` は、ローカル Chromium 起動に追加の launch フラグを付加します（たとえば - `--disable-gpu`、ウィンドウサイズ指定、デバッグフラグなど）。 +- `extraArgs` は、ローカル Chromium 起動に追加の起動フラグを付加します（たとえば + `--disable-gpu`、ウィンドウサイズ指定、またはデバッグフラグ）。 --- @@ -2976,14 +2972,14 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji、短いテキスト、画像 URL、または data URI }, }, } ``` -- `seamColor`: ネイティブ app UI chrome のアクセントカラー（Talk Mode のバブル色など）。 -- `assistant`: Control UI の identity オーバーライド。アクティブ agent identity にフォールバックします。 +- `seamColor`: ネイティブアプリ UI chrome のアクセントカラー（Talk Mode のバブル色など）。 +- `assistant`: Control UI の identity オーバーライド。アクティブ agent の identity にフォールバックします。 --- @@ -2998,8 +2994,8 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // または OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // mode=trusted-proxy 用。/gateway/trusted-proxy-auth を参照 allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3017,9 +3013,9 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowExternalEmbedUrls: false, // 危険: 絶対外部 http(s) 埋め込み URL を許可 + // allowedOrigins: ["https://control.example.com"], // loopback 以外の Control UI に必須 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危険な Host-header origin フォールバックモード // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3030,12 +3026,12 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // オプション。デフォルト false。 allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // 追加の /tools/invoke HTTP deny deny: ["browser"], - // Remove tools from the default HTTP deny list + // デフォルトの HTTP deny リストから tool を削除 allow: ["gateway"], }, push: { @@ -3052,51 +3048,51 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は -- `mode`: `local`（Gateway を実行）または `remote`（リモート Gateway に接続）。Gateway は `local` でない限り起動を拒否します。 -- `port`: WS + HTTP 用の単一多重化ポート。優先順位: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`: `local`（gateway を実行）または `remote`（リモート gateway に接続）。gateway は `local` でない限り起動を拒否します。 +- `port`: WS + HTTP 用の単一の多重化 port。優先順位: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`: `auto`、`loopback`（デフォルト）、`lan`（`0.0.0.0`）、`tailnet`（Tailscale IP のみ）、または `custom`。 -- **従来の bind alias**: `gateway.bind` には host alias（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）ではなく、bind mode 値（`auto`、`loopback`、`lan`、`tailnet`、`custom`）を使用してください。 -- **Docker 注記**: デフォルトの `loopback` bind はコンテナ内の `127.0.0.1` で待ち受けます。Docker bridge ネットワーク（`-p 18789:18789`）では、トラフィックは `eth0` に到着するため、Gateway は到達不能になります。`--network host` を使用するか、すべてのインターフェイスで待ち受けるために `bind: "lan"`（または `bind: "custom"` と `customBindHost: "0.0.0.0"`）を設定してください。 -- **認証**: デフォルトで必須です。loopback 以外の bind では Gateway 認証が必要です。実際には、共有 token/password、または `gateway.auth.mode: "trusted-proxy"` を持つ identity-aware リバースプロキシを意味します。オンボーディングウィザードはデフォルトで token を生成します。 -- `gateway.auth.token` と `gateway.auth.password` の両方が設定されている場合（SecretRef を含む）、`gateway.auth.mode` を `token` または `password` に明示的に設定してください。両方が設定され mode が未設定の場合、起動および service の install/repair フローは失敗します。 -- `gateway.auth.mode: "none"`: 明示的な認証なしモード。信頼できる local loopback 構成でのみ使用してください。これは意図的にオンボーディング prompt では提供されません。 -- `gateway.auth.mode: "trusted-proxy"`: 認証を identity-aware リバースプロキシに委譲し、`gateway.trustedProxies` からの ID ヘッダーを信頼します（[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照）。このモードは **非 loopback** のプロキシソースを前提とします。同一ホストの loopback リバースプロキシは trusted-proxy 認証の条件を満たしません。 -- `gateway.auth.allowTailscale`: `true` の場合、Tailscale Serve の ID ヘッダーが Control UI/WebSocket 認証を満たせます（`tailscale whois` で検証）。HTTP API エンドポイントではその Tailscale ヘッダー認証は使用されません。HTTP API は代わりに Gateway の通常の HTTP 認証モードに従います。この token なしフローは Gateway ホストが信頼されている前提です。`tailscale.mode = "serve"` の場合、デフォルトは `true` です。 -- `gateway.auth.rateLimit`: 任意の認証失敗リミッター。クライアント IP ごと、および認証スコープごとに適用されます（共有 secret と device-token は独立して追跡されます）。ブロックされた試行は `429` + `Retry-After` を返します。 - - 非同期の Tailscale Serve Control UI パスでは、同じ `{scope, clientIp}` に対する失敗試行は、失敗書き込みの前に直列化されます。そのため、同じクライアントからの同時な不正試行は、両方が単なる不一致として通過して競合するのではなく、2 回目のリクエストでリミッターに達することがあります。 - - `gateway.auth.rateLimit.exemptLoopback` のデフォルトは `true` です。localhost トラフィックも意図的に rate-limit したい場合（テスト構成や厳格なプロキシデプロイなど）は `false` を設定してください。 -- browser 発の WS 認証試行は、loopback 免除を無効にした状態で常にスロットリングされます（browser ベースの localhost 総当たりに対する多層防御）。 -- loopback では、これらの browser 発 lockout は正規化された `Origin` - 値ごとに分離されるため、ある localhost origin からの繰り返し失敗が - 別の origin を自動的にロックアウトすることはありません。 -- `tailscale.mode`: `serve`（tailnet のみ、loopback bind）または `funnel`（公開、認証必須）。 -- `controlUi.allowedOrigins`: Gateway WebSocket 接続用の明示的な browser-origin allowlist。browser クライアントが loopback 以外の origin から接続する場合に必須です。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host ヘッダー由来の origin ポリシーに意図的に依存するデプロイ向けに、Host ヘッダー origin フォールバックを有効にする危険なモードです。 +- **legacy の bind エイリアス**: `gateway.bind` には host エイリアス（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）ではなく、bind mode の値（`auto`、`loopback`、`lan`、`tailnet`、`custom`）を使用してください。 +- **Docker の注意**: デフォルトの `loopback` bind は、コンテナ内で `127.0.0.1` に listen します。Docker bridge ネットワーク（`-p 18789:18789`）では、トラフィックは `eth0` に到着するため、gateway へ到達できません。`--network host` を使うか、すべてのインターフェースで listen するように `bind: "lan"`（または `customBindHost: "0.0.0.0"` を伴う `bind: "custom"`）を設定してください。 +- **Auth**: デフォルトで必須です。loopback 以外の bind では gateway auth が必要です。実際には、共有 token/password または `gateway.auth.mode: "trusted-proxy"` を持つ identity-aware なリバース proxy を意味します。オンボーディングウィザードはデフォルトで token を生成します。 +- `gateway.auth.token` と `gateway.auth.password` の両方が設定されている場合（SecretRef を含む）、`gateway.auth.mode` を `token` または `password` に明示設定してください。両方が設定されていて mode が未設定の場合、起動と service の install/repair フローは失敗します。 +- `gateway.auth.mode: "none"`: 明示的な no-auth モード。信頼できるローカル local loopback 構成でのみ使用してください。これは意図的にオンボーディングプロンプトでは提供されません。 +- `gateway.auth.mode: "trusted-proxy"`: auth を identity-aware なリバース proxy に委譲し、`gateway.trustedProxies` からの identity ヘッダーを信頼します（[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照）。このモードは**非 loopback** の proxy ソースを想定しています。同一 host の loopback リバース proxy は trusted-proxy auth の条件を満たしません。 +- `gateway.auth.allowTailscale`: `true` の場合、Tailscale Serve の identity ヘッダーが Control UI/WebSocket auth を満たせます（`tailscale whois` で検証）。HTTP API エンドポイントはその Tailscale ヘッダー auth を使用しません。代わりに、gateway の通常の HTTP auth mode に従います。この token なしフローは gateway host が信頼されていることを前提とします。`tailscale.mode = "serve"` の場合のデフォルトは `true` です。 +- `gateway.auth.rateLimit`: オプションの認証失敗リミッターです。クライアント IP ごと、かつ auth スコープごとに適用されます（共有 secret と device-token は独立して追跡されます）。ブロックされた試行は `429` + `Retry-After` を返します。 + - 非同期 Tailscale Serve Control UI パスでは、同じ `{scope, clientIp}` に対する失敗試行は失敗書き込み前に直列化されます。そのため、同じクライアントからの同時の不正試行は、両方が通常の不一致として通るのではなく、2 番目のリクエストでリミッターに引っかかることがあります。 + - `gateway.auth.rateLimit.exemptLoopback` のデフォルトは `true` です。localhost トラフィックも意図的に rate limit したい場合（テスト構成や厳格な proxy デプロイなど）は `false` に設定してください。 +- browser 由来の WS auth 試行は、loopback 免除を無効にした状態で常にスロットリングされます（browser ベースの localhost 総当たりに対する多層防御）。 +- loopback 上では、それらの browser 由来 lockout は正規化された `Origin` + 値ごとに分離されるため、ある localhost origin からの繰り返し失敗が、 + 別の origin を自動的に lock out することはありません。 +- `tailscale.mode`: `serve`（tailnet のみ、loopback bind）または `funnel`（公開、auth 必須）。 +- `controlUi.allowedOrigins`: Gateway WebSocket 接続用の明示的な browser-origin allowlist。browser クライアントを loopback 以外の origin から受け付ける場合に必須です。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host-header origin ポリシーに意図的に依存するデプロイ用の、危険な Host-header origin フォールバックモードを有効にします。 - `remote.transport`: `ssh`（デフォルト）または `direct`（ws/wss）。`direct` の場合、`remote.url` は `ws://` または `wss://` でなければなりません。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: 信頼された private-network IP への平文 `ws://` を許可するクライアント側の break-glass オーバーライドです。デフォルトでは平文は loopback のみに制限されます。 -- `gateway.remote.token` / `.password` はリモートクライアントの資格情報フィールドです。これ自体では Gateway 認証を設定しません。 -- `gateway.push.apns.relay.baseUrl`: 公式/TestFlight iOS ビルドが relay ベースの登録を Gateway に公開した後に使用する、外部 APNs relay の base HTTPS URL。この URL は iOS ビルドにコンパイルされた relay URL と一致している必要があります。 -- `gateway.push.apns.relay.timeoutMs`: Gateway から relay への送信 timeout（ミリ秒）。デフォルトは `10000`。 -- relay ベースの登録は特定の Gateway identity に委譲されます。ペアリングされた iOS app は `gateway.identity.get` を取得し、その identity を relay 登録に含め、登録スコープの送信権限を Gateway に転送します。別の Gateway はその保存済み登録を再利用できません。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 上記 relay 設定の一時的な環境変数オーバーライドです。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTP relay URL 用の開発専用 escape hatch。production の relay URL は HTTPS のままにしてください。 -- `gateway.channelHealthCheckMinutes`: channel health-monitor の間隔（分）。グローバルに health-monitor 再起動を無効にするには `0` を設定します。デフォルト: `5`。 -- `gateway.channelStaleEventThresholdMinutes`: stale-socket のしきい値（分）。これは `gateway.channelHealthCheckMinutes` 以上にしてください。デフォルト: `30`。 -- `gateway.channelMaxRestartsPerHour`: 各 channel/account について、1 時間のローリングウィンドウ内で許可される health-monitor 再起動の最大数。デフォルト: `10`。 -- `channels..healthMonitor.enabled`: グローバル monitor を有効のまま、channel ごとに health-monitor 再起動をオプトアウトします。 -- `channels..accounts..healthMonitor.enabled`: マルチアカウント channel 用のアカウント単位オーバーライド。設定されている場合、channel レベルのオーバーライドより優先されます。 -- ローカル Gateway 呼び出しパスでは、`gateway.auth.*` が未設定のときにのみ `gateway.remote.*` をフォールバックとして使用できます。 -- `gateway.auth.token` / `gateway.auth.password` が SecretRef 経由で明示的に設定され、かつ未解決の場合、解決は fail-closed になります（リモートフォールバックで隠蔽されません）。 -- `trustedProxies`: TLS を終端する、または転送クライアントヘッダーを注入するリバースプロキシの IP。自分で制御しているプロキシのみを列挙してください。loopback エントリは同一ホストの proxy/local 検出構成（たとえば Tailscale Serve やローカルリバースプロキシ）では引き続き有効ですが、loopback リクエストが `gateway.auth.mode: "trusted-proxy"` の対象になるわけでは**ありません**。 -- `allowRealIpFallback`: `true` の場合、`X-Forwarded-For` がないときに Gateway は `X-Real-IP` を受け入れます。デフォルトは fail-closed 動作のため `false`。 -- `gateway.tools.deny`: HTTP `POST /tools/invoke` 用に追加でブロックする tool 名（デフォルト deny リストを拡張）。 -- `gateway.tools.allow`: デフォルト HTTP deny リストから tool 名を除外します。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: 信頼できる private-network IP への平文 `ws://` を許可するクライアント側の緊急用オーバーライドです。デフォルトでは、平文許可は loopback のみに留まります。 +- `gateway.remote.token` / `.password` は remote-client の資格情報フィールドです。それ自体では gateway auth を設定しません。 +- `gateway.push.apns.relay.baseUrl`: relay バック登録を gateway に公開した後、公式/TestFlight iOS ビルドが使用する外部 APNs relay のベース HTTPS URL。この URL は iOS ビルドにコンパイルされた relay URL と一致していなければなりません。 +- `gateway.push.apns.relay.timeoutMs`: gateway から relay への送信タイムアウト（ミリ秒）。デフォルトは `10000`。 +- relay バック登録は特定の gateway identity に委譲されます。ペアリングされた iOS app は `gateway.identity.get` を取得し、その identity を relay 登録に含め、登録スコープの send grant を gateway に転送します。別の gateway はその保存済み登録を再利用できません。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 上記 relay 設定の一時的な env オーバーライドです。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTP relay URL 用の開発専用 escape hatch。本番 relay URL は HTTPS のままにしてください。 +- `gateway.channelHealthCheckMinutes`: channel health-monitor の間隔（分）。health-monitor による再起動をグローバルに無効にするには `0` を設定します。デフォルト: `5`。 +- `gateway.channelStaleEventThresholdMinutes`: 古い socket とみなすしきい値（分）。これは `gateway.channelHealthCheckMinutes` 以上にしてください。デフォルト: `30`。 +- `gateway.channelMaxRestartsPerHour`: 1 時間のローリングウィンドウ内で、channel/account ごとに health-monitor が行える最大再起動回数。デフォルト: `10`。 +- `channels..healthMonitor.enabled`: グローバル monitor を有効のまま維持しつつ、channel ごとに health-monitor 再起動をオプトアウトします。 +- `channels..accounts..healthMonitor.enabled`: 複数アカウント channel 用のアカウントごとのオーバーライド。設定されている場合、channel レベルのオーバーライドより優先されます。 +- ローカル gateway の呼び出しパスは、`gateway.auth.*` が未設定の場合にのみ、`gateway.remote.*` をフォールバックとして使えます。 +- `gateway.auth.token` / `gateway.auth.password` が SecretRef 経由で明示的に設定されていて未解決の場合、解決はフェイルクローズします（remote フォールバックで覆い隠されません）。 +- `trustedProxies`: TLS を終端するか、転送された client ヘッダーを注入するリバース proxy の IP。自分が管理する proxy のみを一覧に入れてください。loopback エントリは同一 host の proxy/ローカル検出構成（例: Tailscale Serve やローカル reverse proxy）では引き続き有効ですが、loopback リクエストが `gateway.auth.mode: "trusted-proxy"` の対象になるわけでは**ありません**。 +- `allowRealIpFallback`: `true` の場合、`X-Forwarded-For` がないときに gateway は `X-Real-IP` を受け付けます。フェイルクローズ動作のためデフォルトは `false`。 +- `gateway.tools.deny`: HTTP `POST /tools/invoke` に対して追加でブロックする tool 名（デフォルト deny リストを拡張）。 +- `gateway.tools.allow`: デフォルトの HTTP deny リストから削除する tool 名。 ### OpenAI 互換エンドポイント -- Chat Completions: デフォルトでは無効です。`gateway.http.endpoints.chatCompletions.enabled: true` で有効化します。 +- Chat Completions: デフォルトでは無効です。`gateway.http.endpoints.chatCompletions.enabled: true` で有効にします。 - Responses API: `gateway.http.endpoints.responses.enabled`。 - Responses の URL 入力ハードニング: - `gateway.http.endpoints.responses.maxUrlParts` @@ -3105,12 +3101,12 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は 空の allowlist は未設定として扱われます。URL 取得を無効にするには `gateway.http.endpoints.responses.files.allowUrl=false` および/または `gateway.http.endpoints.responses.images.allowUrl=false` を使用してください。 -- 任意のレスポンスハードニングヘッダー: - - `gateway.http.securityHeaders.strictTransportSecurity`（自分で制御する HTTPS origin に対してのみ設定してください。詳細は [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts)） +- オプションのレスポンスハードニングヘッダー: + - `gateway.http.securityHeaders.strictTransportSecurity`（自分で管理する HTTPS origin に対してのみ設定してください。詳細は [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts)） -### マルチインスタンス分離 +### 複数インスタンスの分離 -一意の port と state dir を使って、1 台のホストで複数の Gateway を実行します: +1 台の host で、固有の port と state dir を使って複数の gateway を実行します: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3138,11 +3134,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: Gateway リスナーでの TLS 終端（HTTPS/WSS）を有効にします（デフォルト: `false`）。 -- `autoGenerate`: 明示的なファイルが設定されていない場合に、ローカルの自己署名 cert/key ペアを自動生成します。ローカル/開発用途専用です。 +- `enabled`: gateway リスナーで TLS 終端（HTTPS/WSS）を有効にします（デフォルト: `false`）。 +- `autoGenerate`: 明示的なファイルが設定されていない場合に、ローカル/開発用途専用として自己署名の cert/key ペアを自動生成します。 - `certPath`: TLS 証明書ファイルへのファイルシステムパス。 -- `keyPath`: TLS 秘密鍵ファイルへのファイルシステムパス。権限制限をかけてください。 -- `caPath`: クライアント検証またはカスタム信頼チェーン用の任意の CA bundle パス。 +- `keyPath`: TLS 秘密鍵ファイルへのファイルシステムパス。権限を制限して保持してください。 +- `caPath`: クライアント検証またはカスタム信頼チェーン用のオプションの CA bundle パス。 ### `gateway.reload` @@ -3158,13 +3154,13 @@ openclaw gateway --port 19001 } ``` -- `mode`: config 編集を runtime 中にどのように適用するかを制御します。 +- `mode`: 設定編集をランタイムでどう適用するかを制御します。 - `"off"`: ライブ編集を無視します。変更には明示的な再起動が必要です。 - - `"restart"`: config 変更時に常に Gateway プロセスを再起動します。 + - `"restart"`: 設定変更時に常に gateway プロセスを再起動します。 - `"hot"`: 再起動せずにプロセス内で変更を適用します。 - - `"hybrid"`（デフォルト）: まず hot reload を試し、必要に応じて再起動にフォールバックします。 -- `debounceMs`: config 変更を適用する前の debounce ウィンドウ（ms、非負整数）。 -- `deferralTimeoutMs`: 進行中処理を待ってから再起動を強制するまでの最大時間（ms、デフォルト: `300000` = 5 分）。 + - `"hybrid"`（デフォルト）: まず hot reload を試し、必要なら再起動にフォールバックします。 +- `debounceMs`: 設定変更を適用する前の debounce ウィンドウ（ms）（非負整数）。 +- `deferralTimeoutMs`: 再起動を強制する前に、進行中の操作を待つ最大時間（ms）（デフォルト: `300000` = 5 分）。 --- @@ -3207,35 +3203,35 @@ openclaw gateway --port 19001 検証と安全性に関する注意: - `hooks.enabled=true` には空でない `hooks.token` が必要です。 -- `hooks.token` は `gateway.auth.token` と**異なる**必要があります。Gateway token の再利用は拒否されます。 -- `hooks.path` は `/` にできません。`/hooks` のような専用サブパスを使用してください。 -- `hooks.allowRequestSessionKey=true` の場合は、`hooks.allowedSessionKeyPrefixes` を制約してください（たとえば `["hook:"]`）。 +- `hooks.token` は `gateway.auth.token` と**異なっていなければなりません**。Gateway token の再利用は拒否されます。 +- `hooks.path` は `/` にはできません。`/hooks` のような専用サブパスを使用してください。 +- `hooks.allowRequestSessionKey=true` の場合は、`hooks.allowedSessionKeyPrefixes` を制限してください（例: `["hook:"]`）。 **エンドポイント:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - リクエスト payload の `sessionKey` は、`hooks.allowRequestSessionKey=true` の場合にのみ受け付けられます（デフォルト: `false`）。 -- `POST /hooks/` → `hooks.mappings` により解決されます +- `POST /hooks/` → `hooks.mappings` で解決されます - + -- `match.path` は `/hooks` の後のサブパスにマッチします（例: `/hooks/gmail` → `gmail`）。 -- `match.source` は汎用パス用の payload フィールドにマッチします。 +- `match.path` は `/hooks` の後ろのサブパスに一致します（例: `/hooks/gmail` → `gmail`）。 +- `match.source` は汎用パス用の payload フィールドに一致します。 - `{{messages[0].subject}}` のようなテンプレートは payload から読み取ります。 -- `transform` には hook action を返す JS/TS モジュールを指定できます。 - - `transform.module` は相対パスでなければならず、`hooks.transformsDir` 内に留まる必要があります（絶対パスと path traversal は拒否されます）。 -- `agentId` は特定の agent にルーティングします。不明な ID はデフォルトにフォールバックします。 -- `allowedAgentIds`: 明示的なルーティングを制限します（`*` または省略 = すべて許可、`[]` = すべて拒否）。 -- `defaultSessionKey`: 明示的な `sessionKey` のない hook agent 実行用の任意の固定 session key。 +- `transform` は hook action を返す JS/TS module を指せます。 + - `transform.module` は相対パスでなければならず、`hooks.transformsDir` 内に留まります（絶対パスや traversal は拒否されます）。 +- `agentId` は特定の agent へルーティングします。不明な ID はデフォルトにフォールバックします。 +- `allowedAgentIds`: 明示的ルーティングを制限します（`*` または省略 = すべて許可、`[]` = すべて拒否）。 +- `defaultSessionKey`: 明示的な `sessionKey` がない hook agent 実行用のオプションの固定 session key。 - `allowRequestSessionKey`: `/hooks/agent` 呼び出し元が `sessionKey` を設定できるようにします（デフォルト: `false`）。 -- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（request + mapping）向けの任意のプレフィックス allowlist。例: `["hook:"]`。 +- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（request + mapping）向けのオプションのプレフィックス allowlist。例: `["hook:"]`。 - `deliver: true` は最終返信を channel に送信します。`channel` のデフォルトは `last` です。 - `model` はこの hook 実行用の LLM を上書きします（model カタログが設定されている場合は許可されている必要があります）。 -### Gmail 統合 +### Gmail 連携 ```json5 { @@ -3258,7 +3254,7 @@ openclaw gateway --port 19001 } ``` -- 設定されている場合、Gateway は起動時に `gog gmail watch serve` を自動起動します。無効にするには `OPENCLAW_SKIP_GMAIL_WATCHER=1` を設定してください。 +- 設定されている場合、gateway は起動時に `gog gmail watch serve` を自動起動します。無効にするには `OPENCLAW_SKIP_GMAIL_WATCHER=1` を設定します。 - Gateway と並行して別の `gog gmail watch serve` を実行しないでください。 --- @@ -3270,22 +3266,22 @@ openclaw gateway --port 19001 canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // または OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- Gateway port 配下の HTTP で、agent が編集可能な HTML/CSS/JS と A2UI を配信します: +- agent が編集可能な HTML/CSS/JS と A2UI を Gateway port 配下で HTTP 提供します: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- ローカル専用: `gateway.bind: "loopback"`（デフォルト）のままにしてください。 -- loopback 以外の bind では、canvas ルートは他の Gateway HTTP サーフェスと同様に Gateway 認証（token/password/trusted-proxy）を必要とします。 -- Node WebView は通常 auth ヘッダーを送信しません。node がペアリングされて接続されると、Gateway は canvas/A2UI アクセス用の node スコープ capability URL を広告します。 -- capability URL はアクティブな node WS session に結び付けられ、短時間で期限切れになります。IP ベースのフォールバックは使用されません。 -- 配信される HTML に live-reload クライアントを注入します。 -- 空の場合は starter `index.html` を自動作成します。 -- `/__openclaw__/a2ui/` でも A2UI を配信します。 -- 変更には Gateway の再起動が必要です。 +- ローカル専用: `gateway.bind: "loopback"`（デフォルト）を維持してください。 +- loopback 以外の bind では、canvas ルートにも他の Gateway HTTP サーフェスと同様に Gateway auth（token/password/trusted-proxy）が必要です。 +- Node WebView は通常 auth ヘッダーを送信しません。Node がペアリングされて接続されると、Gateway は canvas/A2UI アクセス用の Node スコープ capability URL を通知します。 +- capability URL はアクティブな Node WS session にバインドされ、短時間で期限切れになります。IP ベースのフォールバックは使用されません。 +- 配信する HTML に live-reload client を注入します。 +- 空の場合はスターター `index.html` を自動作成します。 +- A2UI も `/__openclaw__/a2ui/` で提供します。 +- 変更には gateway の再起動が必要です。 - 大きなディレクトリや `EMFILE` エラーの場合は live reload を無効にしてください。 --- @@ -3306,7 +3302,7 @@ openclaw gateway --port 19001 - `minimal`（デフォルト）: TXT レコードから `cliPath` + `sshPort` を省略します。 - `full`: `cliPath` + `sshPort` を含めます。 -- hostname のデフォルトは `openclaw` です。`OPENCLAW_MDNS_HOSTNAME` で上書きできます。 +- hostname のデフォルトは `openclaw` です。`OPENCLAW_MDNS_HOSTNAME` で上書きします。 ### 広域（DNS-SD） @@ -3326,7 +3322,7 @@ openclaw gateway --port 19001 ## Environment -### `env`（インライン環境変数） +### `env`（インライン env vars） ```json5 { @@ -3343,14 +3339,14 @@ openclaw gateway --port 19001 } ``` -- インライン環境変数は、プロセス環境にそのキーが存在しない場合にのみ適用されます。 -- `.env` ファイル: CWD の `.env` + `~/.openclaw/.env`（どちらも既存の変数を上書きしません）。 -- `shellEnv`: login shell profile から不足している想定キーを取り込みます。 +- インライン env vars は、process env にそのキーが存在しない場合にのみ適用されます。 +- `.env` ファイル: CWD の `.env` + `~/.openclaw/.env`（どちらも既存の var を上書きしません）。 +- `shellEnv`: ログイン shell の profile から、期待される不足キーを取り込みます。 - 完全な優先順位は [Environment](/ja-JP/help/environment) を参照してください。 -### 環境変数置換 +### Env var 置換 -任意の config 文字列内で `${VAR_NAME}` により環境変数を参照できます: +任意の config 文字列で `${VAR_NAME}` を使って env vars を参照できます: ```json5 { @@ -3360,16 +3356,16 @@ openclaw gateway --port 19001 } ``` -- 一致するのは大文字名のみ: `[A-Z_][A-Z0-9_]*`。 -- 欠落または空の変数は config 読み込み時にエラーになります。 -- リテラルの `${VAR}` にするには `$${VAR}` でエスケープします。 +- 一致するのは大文字名のみです: `[A-Z_][A-Z0-9_]*`。 +- 存在しない/空の var は config 読み込み時にエラーになります。 +- リテラルの `${VAR}` には `$${VAR}` でエスケープします。 - `$include` でも動作します。 --- ## Secrets -SecretRef は追加的です。平文値も引き続き使用できます。 +SecretRef は加算的です: 平文値も引き続き動作します。 ### `SecretRef` @@ -3385,13 +3381,13 @@ SecretRef は追加的です。平文値も引き続き使用できます。 - `source: "env"` の id パターン: `^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` の id: 絶対 JSON pointer（例: `"/providers/openai/apiKey"`） - `source: "exec"` の id パターン: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` の id には、`.` または `..` のスラッシュ区切り path セグメントを含めてはいけません（例: `a/../b` は拒否されます） +- `source: "exec"` の id には、`.` や `..` のような slash 区切りパスセグメントを含めてはいけません（例: `a/../b` は拒否されます） -### 対応する資格情報サーフェス +### サポートされる資格情報サーフェス -- 正規の対応表: [SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface) -- `secrets apply` は、対応する `openclaw.json` 資格情報パスを対象にします。 -- `auth-profiles.json` の ref も runtime 解決と audit 対象に含まれます。 +- 正規マトリクス: [SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface) +- `secrets apply` はサポートされる `openclaw.json` の資格情報パスを対象にします。 +- `auth-profiles.json` の ref もランタイム解決と監査対象に含まれます。 ### Secret provider 設定 @@ -3399,7 +3395,7 @@ SecretRef は追加的です。平文値も引き続き使用できます。 { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // オプションの明示的 env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3423,17 +3419,17 @@ SecretRef は追加的です。平文値も引き続き使用できます。 注意: -- `file` provider は `mode: "json"` と `mode: "singleValue"` をサポートします（singleValue mode では `id` は `"value"` でなければなりません）。 -- `exec` provider には絶対 `command` パスが必要で、stdin/stdout 上のプロトコル payload を使用します。 -- デフォルトでは symlink command path は拒否されます。解決後のターゲットパスを検証しつつ symlink path を許可するには `allowSymlinkCommand: true` を設定してください。 +- `file` provider は `mode: "json"` と `mode: "singleValue"` をサポートします（singleValue モードでは `id` は `"value"` でなければなりません）。 +- `exec` provider には絶対 `command` パスが必要で、stdin/stdout 上の protocol payload を使用します。 +- デフォルトでは、シンボリックリンクの command パスは拒否されます。解決後のターゲットパスを検証したうえでシンボリックリンクパスを許可するには `allowSymlinkCommand: true` を設定します。 - `trustedDirs` が設定されている場合、trusted-dir チェックは解決後のターゲットパスに適用されます。 - `exec` 子環境はデフォルトで最小限です。必要な変数は `passEnv` で明示的に渡してください。 -- Secret ref は有効化時にメモリ内 snapshot へ解決され、その後の request パスは snapshot のみを読み取ります。 -- 有効サーフェスのフィルタリングは有効化中に適用されます。有効なサーフェス上の未解決 ref は起動/reload を失敗させ、非アクティブなサーフェスは diagnostics 付きでスキップされます。 +- Secret ref はアクティベーション時にメモリ内スナップショットへ解決され、その後の request パスはそのスナップショットのみを読みます。 +- アクティベーション中に active-surface フィルタリングが適用されます: 有効サーフェス上の未解決 ref は起動/再読み込みを失敗させ、非アクティブサーフェスは診断付きでスキップされます。 --- -## Auth ストレージ +## Auth storage ```json5 { @@ -3452,12 +3448,12 @@ SecretRef は追加的です。平文値も引き続き使用できます。 ``` - agent ごとの profile は `/auth-profiles.json` に保存されます。 -- `auth-profiles.json` は、静的資格情報モード用の値レベル ref（`api_key` 用の `keyRef`、`token` 用の `tokenRef`）をサポートします。 -- OAuth mode profile（`auth.profiles..mode = "oauth"`）は、SecretRef ベースの auth-profile 資格情報をサポートしません。 -- 静的 runtime 資格情報は、メモリ内の解決済み snapshot から取得されます。従来の静的 `auth.json` エントリは、見つかったときに scrub されます。 -- 従来の OAuth は `~/.openclaw/credentials/oauth.json` から import されます。 +- `auth-profiles.json` は、静的資格情報モード向けに値レベルの ref（`api_key` には `keyRef`、`token` には `tokenRef`）をサポートします。 +- OAuth モードの profile（`auth.profiles..mode = "oauth"`）は SecretRef バックの auth-profile 資格情報をサポートしません。 +- 静的ランタイム資格情報はメモリ内の解決済みスナップショットから取得され、legacy の静的 `auth.json` エントリは発見時に除去されます。 +- legacy の OAuth は `~/.openclaw/credentials/oauth.json` から取り込まれます。 - [OAuth](/ja-JP/concepts/oauth) を参照してください。 -- Secrets runtime の動作と `audit/configure/apply` ツール: [Secrets Management](/ja-JP/gateway/secrets)。 +- secrets ランタイムの動作と `audit/configure/apply` ツール: [Secrets Management](/ja-JP/gateway/secrets)。 ### `auth.cooldowns` @@ -3479,21 +3475,15 @@ SecretRef は追加的です。平文値も引き続き使用できます。 } ``` -- `billingBackoffHours`: 真の - billing/クレジット不足エラーにより profile が失敗したときの、時間単位の基本バックオフ - （デフォルト: `5`）。`401`/`403` 応答でも明示的な billing 文言があれば - ここに分類されることがありますが、provider 固有の文言 - マッチャーは引き続きその provider に限定されます（たとえば OpenRouter の - `Key limit exceeded`）。再試行可能な HTTP `402` の使用量ウィンドウや - organization/workspace の支出上限メッセージは、代わりに `rate_limit` パスに留まります。 -- `billingBackoffHoursByProvider`: billing バックオフ時間の任意の provider ごとの上書き。 -- `billingMaxHours`: billing バックオフ指数成長の上限時間（デフォルト: `24`）。 -- `authPermanentBackoffMinutes`: 高信頼の `auth_permanent` 失敗に対する分単位の基本バックオフ（デフォルト: `10`）。 -- `authPermanentMaxMinutes`: `auth_permanent` バックオフ成長の分単位上限（デフォルト: `60`）。 -- `failureWindowHours`: バックオフカウンターに使用するローリングウィンドウ（時間、デフォルト: `24`）。 -- `overloadedProfileRotations`: 過負荷エラー時に model fallback へ切り替える前に行う、同一 provider 内 auth-profile ローテーションの最大回数（デフォルト: `1`）。`ModelNotReadyException` のような provider-busy 形状はここに分類されます。 -- `overloadedBackoffMs`: 過負荷の provider/profile ローテーションを再試行する前の固定遅延（ms、デフォルト: `0`）。 -- `rateLimitedProfileRotations`: rate-limit エラー時に model fallback へ切り替える前に行う、同一 provider 内 auth-profile ローテーションの最大回数（デフォルト: `1`）。その rate-limit バケットには、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` のような provider 形状の文言も含まれます。 +- `billingBackoffHours`: profile が真の請求/残高不足エラーで失敗したときの基本 backoff 時間（時間）（デフォルト: `5`）。明示的な請求テキストは `401`/`403` 応答でもここに入ることがありますが、provider 固有のテキストマッチャーは引き続きその provider にのみ適用されます（例: OpenRouter の `Key limit exceeded`）。再試行可能な HTTP `402` の usage-window や organization/workspace の spend-limit メッセージは、代わりに `rate_limit` パスに留まります。 +- `billingBackoffHoursByProvider`: 請求 backoff 時間に対するオプションの provider ごとのオーバーライド。 +- `billingMaxHours`: 請求 backoff の指数的増加の上限時間（デフォルト: `24`）。 +- `authPermanentBackoffMinutes`: 高信頼の `auth_permanent` 失敗に対する基本 backoff 時間（分）（デフォルト: `10`）。 +- `authPermanentMaxMinutes`: `auth_permanent` backoff 増加の上限分数（デフォルト: `60`）。 +- `failureWindowHours`: backoff カウンタに使われるローリングウィンドウ（時間）（デフォルト: `24`）。 +- `overloadedProfileRotations`: 過負荷エラー時に model fallback へ切り替える前の、同一 provider の auth-profile ローテーション最大回数（デフォルト: `1`）。`ModelNotReadyException` のような provider-busy 形状はここに入ります。 +- `overloadedBackoffMs`: 過負荷 provider/profile ローテーション再試行前の固定待機時間（デフォルト: `0`）。 +- `rateLimitedProfileRotations`: rate-limit エラー時に model fallback へ切り替える前の、同一 provider の auth-profile ローテーション最大回数（デフォルト: `1`）。この rate-limit バケットには `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` のような provider 形状テキストも含まれます。 --- @@ -3514,8 +3504,8 @@ SecretRef は追加的です。平文値も引き続き使用できます。 - デフォルトのログファイル: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 安定したパスにするには `logging.file` を設定してください。 -- `consoleLevel` は `--verbose` 時に `debug` へ上がります。 -- `maxFileBytes`: 書き込みを抑止する前の最大ログファイルサイズ（バイト、正の整数、デフォルト: `524288000` = 500 MB）。production デプロイでは外部ログローテーションを使用してください。 +- `consoleLevel` は `--verbose` で `debug` に上がります。 +- `maxFileBytes`: 書き込み抑止前のログファイル最大サイズ（バイト）（正の整数、デフォルト: `524288000` = 500 MB）。本番デプロイでは外部ログローテーションを使用してください。 --- @@ -3552,18 +3542,18 @@ SecretRef は追加的です。平文値も引き続き使用できます。 } ``` -- `enabled`: instrumentation 出力のマスタートグルです（デフォルト: `true`）。 -- `flags`: 対象を絞ったログ出力を有効にするフラグ文字列の配列です（`"telegram.*"` や `"*"` のようなワイルドカードをサポート）。 -- `stuckSessionWarnMs`: session が processing 状態のままの間に stuck-session 警告を出すための経過しきい値（ms）。 -- `otel.enabled`: OpenTelemetry エクスポートパイプラインを有効にします（デフォルト: `false`）。 -- `otel.endpoint`: OTel エクスポート先 collector の URL。 +- `enabled`: 計測出力のマスタートグルです（デフォルト: `true`）。 +- `flags`: ターゲットを絞ったログ出力を有効にするフラグ文字列の配列です（`"telegram.*"` や `"*"` のようなワイルドカードをサポート）。 +- `stuckSessionWarnMs`: session が processing 状態のままである間に stuck-session 警告を出すための経過時間しきい値（ms）。 +- `otel.enabled`: OpenTelemetry のエクスポートパイプラインを有効にします（デフォルト: `false`）。 +- `otel.endpoint`: OTel エクスポート用の collector URL。 - `otel.protocol`: `"http/protobuf"`（デフォルト）または `"grpc"`。 -- `otel.headers`: OTel エクスポート要求とともに送られる追加の HTTP/gRPC メタデータヘッダー。 -- `otel.serviceName`: resource 属性用の service 名。 -- `otel.traces` / `otel.metrics` / `otel.logs`: trace、metrics、または log のエクスポートを有効にします。 +- `otel.headers`: OTel エクスポートリクエストとともに送信される追加の HTTP/gRPC メタデータヘッダー。 +- `otel.serviceName`: resource attribute 用の service 名。 +- `otel.traces` / `otel.metrics` / `otel.logs`: trace、metrics、または log エクスポートを有効にします。 - `otel.sampleRate`: trace サンプリング率 `0`–`1`。 - `otel.flushIntervalMs`: 定期的な telemetry flush 間隔（ms）。 -- `cacheTrace.enabled`: embedded 実行用の cache trace snapshot をログに出力します（デフォルト: `false`）。 +- `cacheTrace.enabled`: 組み込み実行用の cache trace スナップショットをログ出力します（デフォルト: `false`）。 - `cacheTrace.filePath`: cache trace JSONL の出力パス（デフォルト: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: cache trace 出力に何を含めるかを制御します（すべてデフォルト: `true`）。 @@ -3587,12 +3577,12 @@ SecretRef は追加的です。平文値も引き続き使用できます。 } ``` -- `channel`: npm/git install 用のリリース channel — `"stable"`、`"beta"`、または `"dev"`。 -- `checkOnStart`: Gateway 起動時に npm 更新を確認します（デフォルト: `true`）。 -- `auto.enabled`: package install 向けバックグラウンド自動更新を有効にします（デフォルト: `false`）。 -- `auto.stableDelayHours`: stable channel の自動適用までの最小遅延時間（デフォルト: `6`、最大: `168`）。 -- `auto.stableJitterHours`: stable channel のロールアウト分散用の追加時間ウィンドウ（デフォルト: `12`、最大: `168`）。 -- `auto.betaCheckIntervalHours`: beta channel の確認を行う間隔（時間、デフォルト: `1`、最大: `24`）。 +- `channel`: npm/git インストール用のリリースチャネル — `"stable"`、`"beta"`、または `"dev"`。 +- `checkOnStart`: gateway 起動時に npm 更新を確認します（デフォルト: `true`）。 +- `auto.enabled`: package インストール用のバックグラウンド自動更新を有効にします（デフォルト: `false`）。 +- `auto.stableDelayHours`: stable channel の自動適用前の最小遅延時間（時間）（デフォルト: `6`、最大: `168`）。 +- `auto.stableJitterHours`: stable channel の追加ロールアウト分散ウィンドウ（時間）（デフォルト: `12`、最大: `168`）。 +- `auto.betaCheckIntervalHours`: beta channel の確認実行間隔（時間）（デフォルト: `1`、最大: `24`）。 --- @@ -3625,22 +3615,22 @@ SecretRef は追加的です。平文値も引き続き使用できます。 } ``` -- `enabled`: グローバル ACP 機能ゲート（デフォルト: `false`）。 -- `dispatch.enabled`: ACP session turn dispatch 用の独立ゲートです（デフォルト: `true`）。ACP コマンドは利用可能なまま実行だけをブロックしたい場合は `false` を設定します。 -- `backend`: デフォルト ACP runtime backend id（登録済み ACP runtime Plugin に一致する必要があります）。 -- `defaultAgent`: spawn が明示的なターゲットを指定しない場合のフォールバック ACP ターゲット agent id。 -- `allowedAgents`: ACP runtime session で許可される agent id の allowlist。空は追加制限なしを意味します。 +- `enabled`: グローバル ACP 機能ゲートです（デフォルト: `false`）。 +- `dispatch.enabled`: ACP session ターン dispatch 用の独立ゲートです（デフォルト: `true`）。ACP command を利用可能なまま実行をブロックするには `false` を設定します。 +- `backend`: デフォルトの ACP ランタイム backend id（登録済み ACP ランタイム Plugin と一致している必要があります）。 +- `defaultAgent`: spawn が明示的ターゲットを指定しない場合のフォールバック ACP 対象 agent id。 +- `allowedAgents`: ACP ランタイム session に許可される agent id の allowlist。空の場合は追加制限なしを意味します。 - `maxConcurrentSessions`: 同時にアクティブにできる ACP session の最大数。 -- `stream.coalesceIdleMs`: ストリームされたテキスト用のアイドル flush ウィンドウ（ms）。 -- `stream.maxChunkChars`: ストリームされた block projection を分割する前の最大 chunk サイズ。 -- `stream.repeatSuppression`: turn ごとに繰り返される status/tool 行を抑制します（デフォルト: `true`）。 -- `stream.deliveryMode`: `"live"` は増分でストリームし、`"final_only"` は turn の終端イベントまでバッファします。 -- `stream.hiddenBoundarySeparator`: 非表示 tool イベント後、可視テキストの前に入る区切り（デフォルト: `"paragraph"`）。 -- `stream.maxOutputChars`: ACP turn ごとに投影される assistant 出力文字数の最大値。 +- `stream.coalesceIdleMs`: ストリーミングテキスト用のアイドル flush ウィンドウ（ms）。 +- `stream.maxChunkChars`: ストリーミングされるブロック投影を分割する前の最大チャンクサイズ。 +- `stream.repeatSuppression`: ターンごとの繰り返し status/tool 行を抑制します（デフォルト: `true`）。 +- `stream.deliveryMode`: `"live"` は段階的にストリーミングし、`"final_only"` はターン終端イベントまでバッファします。 +- `stream.hiddenBoundarySeparator`: 非表示 tool イベントの後に可視テキストの前へ挿入する区切り文字（デフォルト: `"paragraph"`）。 +- `stream.maxOutputChars`: ACP ターンごとに投影される assistant 出力文字数の最大値。 - `stream.maxSessionUpdateChars`: 投影される ACP status/update 行の最大文字数。 -- `stream.tagVisibility`: ストリームイベント用のタグ名から boolean 可視性オーバーライドへの記録。 +- `stream.tagVisibility`: ストリーミングイベント用の、タグ名から真偽値可視性オーバーライドへの記録。 - `runtime.ttlMinutes`: ACP session worker がクリーンアップ対象になるまでのアイドル TTL（分）。 -- `runtime.installCommand`: ACP runtime 環境を bootstrap する際に実行する任意の install コマンド。 +- `runtime.installCommand`: ACP ランタイム環境の bootstrap 時に実行するオプションの install command。 --- @@ -3656,15 +3646,15 @@ SecretRef は追加的です。平文値も引き続き使用できます。 } ``` -- `cli.banner.taglineMode` は banner の tagline スタイルを制御します: - - `"random"`（デフォルト）: ローテーションする面白い/季節ネタの tagline。 - - `"default"`: 固定の中立な tagline（`All your chats, one OpenClaw.`）。 - - `"off"`: tagline テキストなし（banner のタイトル/バージョンは引き続き表示）。 -- banner 全体を隠すには（tagline だけでなく）、環境変数 `OPENCLAW_HIDE_BANNER=1` を設定してください。 +- `cli.banner.taglineMode` はバナーのタグラインスタイルを制御します: + - `"random"`（デフォルト）: ローテーションする面白い/季節のタグライン。 + - `"default"`: 固定の中立的なタグライン（`All your chats, one OpenClaw.`）。 + - `"off"`: タグラインテキストなし（バナーのタイトル/バージョンは引き続き表示）。 +- バナー全体を隠すには（タグラインだけでなく）、env `OPENCLAW_HIDE_BANNER=1` を設定します。 --- -## Wizard +## ウィザード CLI のガイド付きセットアップフロー（`onboard`、`configure`、`doctor`）によって書き込まれるメタデータ: @@ -3688,11 +3678,11 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d --- -## Bridge（従来、削除済み） +## Bridge（legacy、削除済み） -現在の build には TCP bridge は含まれていません。Node は Gateway WebSocket 経由で接続します。`bridge.*` キーはもはや config schema の一部ではありません（削除するまで検証は失敗します。`openclaw doctor --fix` で未知キーを除去できます）。 +現在のビルドには TCP bridge は含まれていません。Node は Gateway WebSocket 経由で接続します。`bridge.*` キーはもはや config schema の一部ではありません（削除されるまで検証は失敗します。`openclaw doctor --fix` で未知のキーを除去できます）。 - + ```json { @@ -3719,22 +3709,22 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // 非推奨。保存済みの notify:true job 用フォールバック + webhookToken: "replace-with-dedicated-token", // オプション。送信 webhook auth 用 bearer token + sessionRetention: "24h", // duration 文字列または false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // デフォルト 2_000_000 bytes + keepLines: 2000, // デフォルト 2000 }, }, } ``` -- `sessionRetention`: 完了した分離 cron 実行 session を `sessions.json` から剪定するまで保持する期間です。削除済み cron transcript のアーカイブ cleanup も制御します。デフォルト: `24h`。無効にするには `false` を設定します。 -- `runLog.maxBytes`: 剪定前の run log ファイルごとの最大サイズ（`cron/runs/.jsonl`）。デフォルト: `2_000_000` バイト。 -- `runLog.keepLines`: run-log 剪定が発生したときに保持される最新行数。デフォルト: `2000`。 -- `webhookToken`: Cron webhook POST 配信（`delivery.mode = "webhook"`）に使用する bearer token です。省略した場合、auth ヘッダーは送信されません。 -- `webhook`: 非推奨の従来 fallback webhook URL（http/https）で、まだ `notify: true` を持つ保存済みジョブにのみ使用されます。 +- `sessionRetention`: 完了した分離 cron 実行 session を `sessions.json` から剪定するまで保持する期間。アーカイブされた削除済み cron transcript のクリーンアップも制御します。デフォルト: `24h`。無効にするには `false` を設定します。 +- `runLog.maxBytes`: 剪定前の実行ログファイル（`cron/runs/.jsonl`）ごとの最大サイズ。デフォルト: `2_000_000` bytes。 +- `runLog.keepLines`: 実行ログ剪定が発動したときに保持される最新行数。デフォルト: `2000`。 +- `webhookToken`: cron webhook POST 配信（`delivery.mode = "webhook"`）に使われる bearer token。省略時は auth ヘッダーを送信しません。 +- `webhook`: 非推奨の legacy フォールバック webhook URL（http/https）。`notify: true` をまだ持つ保存済み job に対してのみ使用されます。 ### `cron.retry` @@ -3750,11 +3740,11 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d } ``` -- `maxAttempts`: 一過性エラー時に one-shot ジョブで行う最大リトライ回数（デフォルト: `3`、範囲: `0`–`10`）。 -- `backoffMs`: 各リトライ試行のバックオフ遅延（ms）の配列（デフォルト: `[30000, 60000, 300000]`、1–10 エントリ）。 -- `retryOn`: リトライを引き起こすエラー種別 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略すると、すべての一過性種別をリトライします。 +- `maxAttempts`: 一時的エラー時の one-shot job の最大 retry 回数（デフォルト: `3`、範囲: `0`–`10`）。 +- `backoffMs`: 各 retry 試行に対する backoff 遅延（ms）の配列（デフォルト: `[30000, 60000, 300000]`、1–10 エントリ）。 +- `retryOn`: retry を引き起こすエラータイプ — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略すると、すべての一時的タイプを retry します。 -これは one-shot cron ジョブにのみ適用されます。定期実行ジョブでは別の失敗処理を使用します。 +one-shot cron job にのみ適用されます。定期 job は別の失敗処理を使用します。 ### `cron.failureAlert` @@ -3772,11 +3762,11 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d } ``` -- `enabled`: cron ジョブの failure alert を有効にします（デフォルト: `false`）。 -- `after`: alert が発火するまでの連続失敗回数（正の整数、最小: `1`）。 -- `cooldownMs`: 同じジョブに対する alert の再送までの最小間隔（ms、非負整数）。 -- `mode`: 配信モード — `"announce"` は channel メッセージで送信し、`"webhook"` は設定済み webhook に POST します。 -- `accountId`: alert 配信先のスコープを限定する任意の account または channel id。 +- `enabled`: cron job の失敗アラートを有効にします（デフォルト: `false`）。 +- `after`: アラート発火前の連続失敗回数（正の整数、最小: `1`）。 +- `cooldownMs`: 同じ job に対する繰り返しアラート間の最小ミリ秒数（非負整数）。 +- `mode`: 配信モード — `"announce"` は channel メッセージで送信し、`"webhook"` は設定された webhook に POST します。 +- `accountId`: アラート配信をスコープするためのオプションの account または channel id。 ### `cron.failureDestination` @@ -3793,14 +3783,14 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d } ``` -- すべてのジョブに共通する、cron failure 通知のデフォルト送信先です。 -- `mode`: `"announce"` または `"webhook"`。十分なターゲットデータが存在する場合、デフォルトは `"announce"` です。 -- `channel`: announce 配信時の channel オーバーライド。`"last"` は最後にわかっている配信 channel を再利用します。 +- すべての job に共通する cron 失敗通知のデフォルト送信先です。 +- `mode`: `"announce"` または `"webhook"`。十分なターゲット情報が存在する場合のデフォルトは `"announce"` です。 +- `channel`: announce 配信用の channel オーバーライド。`"last"` は最後に使われた配信 channel を再利用します。 - `to`: 明示的な announce ターゲットまたは webhook URL。webhook mode では必須です。 -- `accountId`: 配信の任意 account オーバーライド。 -- ジョブごとの `delivery.failureDestination` は、このグローバルデフォルトを上書きします。 -- グローバルにもジョブごとにも failure destination が設定されていない場合、すでに `announce` で配信しているジョブは、失敗時にその primary announce ターゲットへフォールバックします。 -- `delivery.failureDestination` は、ジョブの primary `delivery.mode` が `"webhook"` である場合を除き、`sessionTarget="isolated"` ジョブでのみサポートされます。 +- `accountId`: 配信用のオプションの account オーバーライド。 +- job ごとの `delivery.failureDestination` はこのグローバルデフォルトを上書きします。 +- グローバルにも job ごとにも failure destination が設定されていない場合、すでに `announce` 経由で配信する job は、失敗時にその primary announce ターゲットへフォールバックします。 +- `delivery.failureDestination` は、job の primary `delivery.mode` が `"webhook"` でない限り、`sessionTarget="isolated"` job でのみサポートされます。 [Cron Jobs](/ja-JP/automation/cron-jobs) を参照してください。分離された cron 実行は [background tasks](/ja-JP/automation/tasks) として追跡されます。 @@ -3810,34 +3800,34 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d `tools.media.models[].args` で展開されるテンプレートプレースホルダー: -| 変数 | 説明 | -| ------------------ | ---------------------------------------------- | -| `{{Body}}` | 受信メッセージ本文全体 | -| `{{RawBody}}` | 生本文（履歴/送信者ラッパーなし） | -| `{{BodyStripped}}` | グループ mention を除去した本文 | -| `{{From}}` | 送信者識別子 | -| `{{To}}` | 宛先識別子 | -| `{{MessageSid}}` | channel メッセージ id | -| `{{SessionId}}` | 現在の session UUID | -| `{{IsNewSession}}` | 新しい session が作成されたとき `"true"` | -| `{{MediaUrl}}` | 受信 media の疑似 URL | -| `{{MediaPath}}` | ローカル media パス | -| `{{MediaType}}` | media 種別（image/audio/document/…） | -| `{{Transcript}}` | 音声 transcript | -| `{{Prompt}}` | CLI エントリ用に解決された media prompt | -| `{{MaxChars}}` | CLI エントリ用に解決された最大出力文字数 | -| `{{ChatType}}` | `"direct"` または `"group"` | -| `{{GroupSubject}}` | グループ件名（best effort） | -| `{{GroupMembers}}` | グループメンバーのプレビュー（best effort） | -| `{{SenderName}}` | 送信者表示名（best effort） | -| `{{SenderE164}}` | 送信者電話番号（best effort） | +| Variable | 説明 | +| ------------------ | -------------------------------------------- | +| `{{Body}}` | 完全な受信メッセージ本文 | +| `{{RawBody}}` | 生の本文（履歴/送信者ラッパーなし） | +| `{{BodyStripped}}` | グループメンションを除去した本文 | +| `{{From}}` | 送信者識別子 | +| `{{To}}` | 送信先識別子 | +| `{{MessageSid}}` | channel メッセージ id | +| `{{SessionId}}` | 現在の session UUID | +| `{{IsNewSession}}` | 新しい session が作成されたとき `"true"` | +| `{{MediaUrl}}` | 受信メディアの疑似 URL | +| `{{MediaPath}}` | ローカルメディアパス | +| `{{MediaType}}` | メディアタイプ（image/audio/document/…） | +| `{{Transcript}}` | 音声 transcript | +| `{{Prompt}}` | CLI エントリ用に解決されたメディア prompt | +| `{{MaxChars}}` | CLI エントリ用に解決された最大出力文字数 | +| `{{ChatType}}` | `"direct"` または `"group"` | +| `{{GroupSubject}}` | グループ subject（ベストエフォート） | +| `{{GroupMembers}}` | グループメンバーのプレビュー（ベストエフォート） | +| `{{SenderName}}` | 送信者表示名（ベストエフォート） | +| `{{SenderE164}}` | 送信者電話番号（ベストエフォート） | | `{{Provider}}` | provider ヒント（whatsapp、telegram、discord など） | --- ## Config include（`$include`） -config を複数ファイルに分割します: +config を複数ファイルに分割できます: ```json5 // ~/.openclaw/openclaw.json @@ -3853,11 +3843,11 @@ config を複数ファイルに分割します: **マージ動作:** - 単一ファイル: そのオブジェクト全体を置き換えます。 -- ファイル配列: 順番に deep-merge されます（後のものが前のものを上書き）。 -- sibling キー: include 後にマージされます（include された値を上書き）。 +- ファイル配列: 順番に deep-merge されます（後のものが前を上書き）。 +- 兄弟キー: include の後でマージされます（include された値を上書き）。 - ネストした include: 最大 10 レベルまで。 -- パス: include 元ファイルを基準に解決されますが、トップレベル config ディレクトリ（`openclaw.json` の `dirname`）の内側に留まる必要があります。絶対パス/`../` 形式も、その境界内に解決される場合にのみ許可されます。 -- エラー: 欠落ファイル、parse エラー、循環 include に対して明確なメッセージが出ます。 +- パス: include 元のファイルからの相対で解決されますが、トップレベル config ディレクトリ（`openclaw.json` の `dirname`）内に留まらなければなりません。絶対パスや `../` 形式も、その境界内に解決される場合にのみ許可されます。 +- エラー: ファイル欠如、parse エラー、循環 include に対して明確なメッセージを出します。 --- diff --git a/docs/ja-JP/help/faq.md b/docs/ja-JP/help/faq.md index 6b4a185b8..42e78d543 100644 --- a/docs/ja-JP/help/faq.md +++ b/docs/ja-JP/help/faq.md @@ -1,23 +1,23 @@ --- read_when: - - 一般的なセットアップ、インストール、オンボーディング、またはランタイムサポートに関する質問への回答 - - より深いデバッグに進む前に、ユーザーから報告された問題をトリアージすること -summary: OpenClaw のセットアップ、設定、使用方法に関するよくある質問 + - 一般的なセットアップ、インストール、オンボーディング、またはランタイムのサポートに関する質問への回答 + - より詳細なデバッグの前に、ユーザーから報告された問題をトリアージすること +summary: OpenClawのセットアップ、設定、使用法に関するよくある質問 title: よくある質問 x-i18n: - generated_at: "2026-04-12T23:28:29Z" + generated_at: "2026-04-20T04:46:31Z" model: gpt-5.4 provider: openai - source_hash: d2a78d0fea9596625cc2753e6dc8cc42c2379a3a0c91729265eee0261fe53eaa + source_hash: 6bdb17fc4d8c61a36f3a9fc3ca4a20f723cfa6c9bbbc92f963d6e313181f3451 source_path: help/faq.md workflow: 15 --- # よくある質問 -実環境でのセットアップに関する簡潔な回答と、より詳しいトラブルシューティング（ローカル開発、VPS、マルチエージェント、OAuth/API キー、モデルフェイルオーバー）。ランタイム診断については [トラブルシューティング](/ja-JP/gateway/troubleshooting) を参照してください。完全な設定リファレンスについては [設定](/ja-JP/gateway/configuration) を参照してください。 +実際のセットアップ（ローカル開発、VPS、マルチエージェント、OAuth/APIキー、モデルフェイルオーバー）向けの簡潔な回答と、より詳しいトラブルシューティングです。ランタイム診断については、[トラブルシューティング](/ja-JP/gateway/troubleshooting)を参照してください。完全な設定リファレンスについては、[設定](/ja-JP/gateway/configuration)を参照してください。 -## 何か壊れているときの最初の 60 秒 +## 何かが壊れているときの最初の60秒 1. **クイックステータス（最初の確認）** @@ -25,7 +25,7 @@ x-i18n: openclaw status ``` - 高速なローカル要約: OS + 更新、gateway/service の到達性、agents/sessions、provider 設定 + ランタイムの問題（gateway に到達できる場合）。 + 高速なローカル要約: OS + アップデート、Gateway/サービス到達可能性、エージェント/セッション、プロバイダー設定 + ランタイム問題（Gatewayに到達可能な場合）。 2. **共有しやすいレポート（安全に共有可能）** @@ -33,15 +33,15 @@ x-i18n: openclaw status --all ``` - ログ末尾付きの読み取り専用診断（トークンはマスク済み）。 + ログ末尾付きの読み取り専用診断（トークンは秘匿化）。 -3. **デーモン + ポート状態** +3. **デーモン + ポートの状態** ```bash openclaw gateway status ``` - supervisor ランタイムと RPC 到達性、プローブ対象 URL、サービスが使用した可能性の高い設定を表示します。 + スーパーバイザーのランタイムとRPC到達可能性、プローブ対象URL、このサービスがおそらく使用した設定を表示します。 4. **詳細プローブ** @@ -49,8 +49,8 @@ x-i18n: openclaw status --deep ``` - サポートされている場合はチャネルプローブを含む、ライブの gateway ヘルスプローブを実行します - （到達可能な gateway が必要です）。[Health](/ja-JP/gateway/health) を参照してください。 + サポートされている場合はチャネルプローブを含む、ライブGatewayヘルスプローブを実行します + （到達可能なGatewayが必要です）。[Health](/ja-JP/gateway/health)を参照してください。 5. **最新ログを追跡** @@ -58,55 +58,59 @@ x-i18n: openclaw logs --follow ``` - RPC がダウンしている場合は、代わりに次を使用します。 + RPCが停止している場合は、代わりに次を使用します: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - ファイルログは service ログとは別です。[Logging](/ja-JP/logging) と [トラブルシューティング](/ja-JP/gateway/troubleshooting) を参照してください。 + ファイルログはサービスログとは別です。[Logging](/ja-JP/logging)と[トラブルシューティング](/ja-JP/gateway/troubleshooting)を参照してください。 -6. **Doctor を実行（修復）** +6. **doctorを実行（修復）** ```bash openclaw doctor ``` - 設定/状態を修復・移行し、ヘルスチェックを実行します。[Doctor](/ja-JP/gateway/doctor) を参照してください。 + 設定/状態を修復・移行し、ヘルスチェックを実行します。[Doctor](/ja-JP/gateway/doctor)を参照してください。 -7. **Gateway スナップショット** +7. **Gatewayスナップショット** ```bash openclaw health --json - openclaw health --verbose # エラー時に対象 URL + 設定パスを表示 + openclaw health --verbose # エラー時に対象URL + 設定パスを表示 ``` - 実行中の gateway に完全なスナップショットを要求します（WS 専用）。[Health](/ja-JP/gateway/health) を参照してください。 + 実行中のGatewayに完全なスナップショットを要求します（WSのみ）。[Health](/ja-JP/gateway/health)を参照してください。 ## クイックスタートと初回セットアップ - **あなたのマシンを見られる** ローカル AI エージェントを使ってください。これは Discord で質問するよりはるかに効果的です。なぜなら、「行き詰まった」というケースの多くは、リモートの支援者には確認できない **ローカルの設定や環境の問題** だからです。 + **あなたのマシンを見られる**ローカルAIエージェントを使ってください。これはDiscordで尋ねるよりはるかに効果的です。というのも、「行き詰まった」というケースの大半は、リモートの支援者には確認できない**ローカル設定や環境の問題**だからです。 - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - これらのツールは、リポジトリの読み取り、コマンド実行、ログ確認、そしてマシンレベルのセットアップ（PATH、services、permissions、auth files）の修正支援ができます。ハッカブルな（git）インストールを使って、**完全なソースチェックアウト** を渡してください。 + これらのツールは、リポジトリの読み取り、コマンド実行、ログ確認、そしてマシンレベルの + セットアップ（PATH、サービス、権限、認証ファイル）の修正支援ができます。ハッカブルな（git） + インストールを使って、**完全なソースチェックアウト**を渡してください: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - これにより OpenClaw は **git チェックアウトから** インストールされるため、エージェントがコードとドキュメントを読み、実行中の正確なバージョンをもとに判断できます。後でインストーラーを `--install-method git` なしで再実行すれば、いつでも stable に戻せます。 + これはgitチェックアウト**から**OpenClawをインストールするため、エージェントがコード + ドキュメントを読み、 + 実行中の正確なバージョンについて推論できます。後でいつでも `--install-method git` なしで + インストーラーを再実行すれば、stableに戻せます。 - ヒント: エージェントには、必要なコマンドだけを実行する前提で、修正を **計画して監督**（ステップごと）してもらってください。そうすれば変更を小さく保てて、監査もしやすくなります。 + ヒント: エージェントには、まず修正を**計画して監督**させ（段階的に）、その後で必要なコマンドだけを実行させてください。そうすることで変更が小さくなり、監査もしやすくなります。 - 実際のバグや修正を見つけたら、GitHub issue を作成するか PR を送ってください: + 実際のバグや修正を見つけた場合は、GitHub issueを作成するかPRを送ってください: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - 助けを求めるときは、まず次のコマンドから始めてください（出力を共有してください）: + まずは次のコマンドから始めてください（助けを求めるときは出力を共有してください）: ```bash openclaw status @@ -114,44 +118,44 @@ x-i18n: openclaw doctor ``` - それぞれの役割: + これらが行うこと: - - `openclaw status`: gateway/agent の健全性 + 基本設定のクイックスナップショット。 - - `openclaw models status`: provider 認証 + モデルの利用可能性を確認します。 - - `openclaw doctor`: よくある設定/状態の問題を検証し、修復します。 + - `openclaw status`: Gateway/エージェントの健全性 + 基本設定のクイックスナップショット。 + - `openclaw models status`: プロバイダー認証 + モデル可用性を確認します。 + - `openclaw doctor`: 一般的な設定/状態の問題を検証して修復します。 - その他の便利な CLI 確認コマンド: `openclaw status --all`, `openclaw logs --follow`, + そのほかに有用なCLIチェック: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`。 - クイックデバッグループ: [何か壊れているときの最初の 60 秒](#何か壊れているときの最初の-60-秒)。 + クイックデバッグループ: [何かが壊れているときの最初の60秒](#何かが壊れているときの最初の60秒)。 インストールドキュメント: [Install](/ja-JP/install), [Installer flags](/ja-JP/install/installer), [Updating](/ja-JP/install/updating)。 - - よくある Heartbeat のスキップ理由: + + 一般的なHeartbeatのスキップ理由: - `quiet-hours`: 設定された active-hours の時間帯外 - - `empty-heartbeat-file`: `HEARTBEAT.md` は存在するが、空白またはヘッダーだけのひな形しか含まれていない - - `no-tasks-due`: `HEARTBEAT.md` の task モードが有効だが、どのタスク間隔もまだ期限に達していない - - `alerts-disabled`: heartbeat の可視性がすべて無効（`showOk`、`showAlerts`、`useIndicator` がすべてオフ） + - `empty-heartbeat-file`: `HEARTBEAT.md` は存在するが、空白またはヘッダーだけの足場しか含まれていない + - `no-tasks-due`: `HEARTBEAT.md` のタスクモードが有効だが、どのタスク間隔もまだ期限に達していない + - `alerts-disabled`: Heartbeatの表示がすべて無効（`showOk`、`showAlerts`、`useIndicator` がすべてオフ） - task モードでは、期限タイムスタンプは実際の heartbeat 実行が完了した後にのみ進みます。 - スキップされた実行ではタスクは完了扱いになりません。 + タスクモードでは、期限タイムスタンプは実際のHeartbeat実行が + 完了した後にのみ進められます。スキップされた実行では、タスクは完了として記録されません。 ドキュメント: [Heartbeat](/ja-JP/gateway/heartbeat), [Automation & Tasks](/ja-JP/automation)。 - - リポジトリでは、ソースから実行し、オンボーディングを使うことを推奨しています。 + + このリポジトリでは、ソースから実行してオンボーディングを使うことを推奨しています: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - ウィザードは UI アセットも自動でビルドできます。オンボーディング後は、通常 port **18789** で Gateway を実行します。 + ウィザードはUIアセットも自動でビルドできます。オンボーディング後は、通常 **18789** 番ポートでGatewayを実行します。 ソースから（コントリビューター/開発者向け）: @@ -160,94 +164,96 @@ x-i18n: cd openclaw pnpm install pnpm build - pnpm ui:build # 初回実行時に UI の依存関係を自動インストール + pnpm ui:build openclaw onboard ``` - まだグローバルインストールしていない場合は、`pnpm openclaw onboard` で実行してください。 + まだグローバルインストールがない場合は、`pnpm openclaw onboard` で実行してください。 - ウィザードは、オンボーディング直後にクリーンな（トークン化されていない）ダッシュボード URL でブラウザを開き、概要にもそのリンクを表示します。そのタブは開いたままにしてください。起動しなかった場合は、同じマシン上で表示された URL をコピーして貼り付けてください。 + ウィザードはオンボーディング直後にクリーンな（トークン化されていない）ダッシュボードURLでブラウザーを開き、概要にもそのリンクを表示します。そのタブは開いたままにしてください。起動しなかった場合は、同じマシンで表示されたURLをコピー&ペーストしてください。 - + **Localhost（同じマシン）:** - `http://127.0.0.1:18789/` を開きます。 - - shared-secret auth を求められた場合は、設定済みの token または password を Control UI の設定に貼り付けます。 - - token の取得元: `gateway.auth.token`（または `OPENCLAW_GATEWAY_TOKEN`）。 - - password の取得元: `gateway.auth.password`（または `OPENCLAW_GATEWAY_PASSWORD`）。 - - まだ shared secret が設定されていない場合は、`openclaw doctor --generate-gateway-token` で token を生成します。 + - 共有シークレット認証を求められた場合は、設定されたトークンまたはパスワードをControl UI設定に貼り付けます。 + - トークンの取得元: `gateway.auth.token`（または `OPENCLAW_GATEWAY_TOKEN`）。 + - パスワードの取得元: `gateway.auth.password`（または `OPENCLAW_GATEWAY_PASSWORD`）。 + - 共有シークレットがまだ設定されていない場合は、`openclaw doctor --generate-gateway-token` でトークンを生成します。 - **localhost ではない場合:** + **localhostではない場合:** - - **Tailscale Serve**（推奨）: bind loopback のまま `openclaw gateway --tailscale serve` を実行し、`https:///` を開きます。`gateway.auth.allowTailscale` が `true` なら、identity headers が Control UI/WebSocket auth を満たします（shared secret を貼り付ける必要はありません。信頼された gateway host を前提とします）。ただし、HTTP API は private-ingress `none` または trusted-proxy HTTP auth を意図的に使わない限り、引き続き shared-secret auth が必要です。 - 同じクライアントからの不正な同時 Serve 認証試行は、failed-auth limiter が記録する前に直列化されるため、2 回目の不正な再試行ではすでに `retry later` が表示されることがあります。 - - **Tailnet bind**: `openclaw gateway --bind tailnet --token ""` を実行する（または password auth を設定する）→ `http://:18789/` を開く → ダッシュボード設定に対応する shared secret を貼り付ける。 - - **Identity-aware reverse proxy**: Gateway を非 loopback の trusted proxy の背後に置いたまま、`gateway.auth.mode: "trusted-proxy"` を設定してから、proxy URL を開きます。 - - **SSH トンネル**: `ssh -N -L 18789:127.0.0.1:18789 user@host` の後に `http://127.0.0.1:18789/` を開きます。トンネル経由でも shared-secret auth は適用されるので、求められたら設定済みの token または password を貼り付けてください。 + - **Tailscale Serve**（推奨）: bind loopback のままにして、`openclaw gateway --tailscale serve` を実行し、`https:///` を開きます。`gateway.auth.allowTailscale` が `true` の場合、IDヘッダーがControl UI/WebSocket認証を満たします（共有シークレットを貼り付ける必要はなく、信頼されたGatewayホストを前提とします）。HTTP APIでは、private-ingress の `none` または trusted-proxy HTTP auth を意図的に使わない限り、引き続き共有シークレット認証が必要です。 + 同一クライアントからの不正な同時Serve認証試行は、失敗認証リミッターが記録する前に直列化されるため、2回目の不正リトライではすでに `retry later` が表示されることがあります。 + - **Tailnet bind**: `openclaw gateway --bind tailnet --token ""` を実行する（またはパスワード認証を設定する）と、`http://:18789/` を開けるようになり、その後ダッシュボード設定に一致する共有シークレットを貼り付けます。 + - **ID認識型リバースプロキシ**: Gatewayを非loopbackのtrusted proxyの背後に置いたままにし、`gateway.auth.mode: "trusted-proxy"` を設定してから、プロキシURLを開きます。 + - **SSHトンネル**: `ssh -N -L 18789:127.0.0.1:18789 user@host` を実行し、その後 `http://127.0.0.1:18789/` を開きます。トンネル経由でも共有シークレット認証は適用されます。求められたら、設定済みのトークンまたはパスワードを貼り付けてください。 - bind モードと認証の詳細は [Dashboard](/web/dashboard) と [Web surfaces](/web) を参照してください。 + bindモードと認証の詳細については、[Dashboard](/web/dashboard) と [Web surfaces](/web) を参照してください。 - - それぞれ制御する層が異なります。 + + それぞれ異なるレイヤーを制御しています: - - `approvals.exec`: 承認プロンプトをチャット宛先へ転送します - - `channels..execApprovals`: そのチャネルを exec approvals 用のネイティブ承認クライアントとして動作させます + - `approvals.exec`: 承認プロンプトをチャット送信先に転送する + - `channels..execApprovals`: そのチャネルをexec approvals用のネイティブ承認クライアントとして動作させる - ホストの exec policy が引き続き実際の承認ゲートです。チャット設定は、承認プロンプトをどこに表示するか、そして人がどう応答できるかを制御するだけです。 + ホストのexecポリシーが、実際の承認ゲートであることに変わりはありません。チャット設定は、承認 + プロンプトをどこに表示するか、そしてユーザーがどう応答できるかを制御するだけです。 - 多くのセットアップでは、**両方は不要** です。 + ほとんどのセットアップでは、**両方は必要ありません**: - - チャットがすでに commands と replies をサポートしているなら、同じチャットでの `/approve` は共有パスを通じて機能します。 - - サポートされたネイティブチャネルが approver を安全に推測できる場合、OpenClaw は `channels..execApprovals.enabled` が未設定または `"auto"` のときに、DM-first のネイティブ承認を自動有効化します。 - - ネイティブの承認カード/ボタンが利用可能な場合、そのネイティブ UI が主要な経路です。ツール結果がチャット承認を利用できない、または手動承認だけが唯一の手段だと示した場合にのみ、エージェントは手動の `/approve` コマンドを含めるべきです。 - - `approvals.exec` は、プロンプトを他のチャットや明示的な運用ルームにも転送する必要がある場合にのみ使用してください。 - - `channels..execApprovals.target: "channel"` または `"both"` は、承認プロンプトを元のルーム/トピックにも明示的に投稿したい場合にのみ使用してください。 - - Plugin approvals はさらに別です。デフォルトでは同じチャットでの `/approve` を使い、任意で `approvals.plugin` 転送があり、一部のネイティブチャネルだけがその上に plugin-approval-native の処理を維持します。 + - そのチャットがすでにコマンドと返信をサポートしていれば、同じチャット内の `/approve` は共有パス経由で動作します。 + - サポートされたネイティブチャネルが承認者を安全に推定できる場合、OpenClawは `channels..execApprovals.enabled` が未設定または `"auto"` のとき、DM優先のネイティブ承認を自動有効化します。 + - ネイティブ承認カード/ボタンが使えるときは、そのネイティブUIが主要な経路です。ツール結果がチャット承認を利用できない、または手動承認のみが唯一の経路であると示した場合にのみ、エージェントは手動の `/approve` コマンドを含めるべきです。 + - `approvals.exec` は、プロンプトを他のチャットや明示的なopsルームにも転送する必要がある場合にのみ使用してください。 + - `channels..execApprovals.target: "channel"` または `"both"` は、承認プロンプトを発生元のルーム/トピックに明示的に投稿し返したい場合にのみ使用してください。 + - Plugin approvals はさらに別です。デフォルトでは同じチャット内の `/approve` を使い、任意で `approvals.plugin` 転送を行い、一部のネイティブチャネルだけがその上にplugin approvalのネイティブ処理を維持します。 - 要するに、転送はルーティング用、ネイティブクライアント設定はチャネル固有のより豊かな UX 用です。 - [Exec Approvals](/ja-JP/tools/exec-approvals) を参照してください。 + 要するに、転送はルーティング用、ネイティブクライアント設定はよりリッチなチャネル固有UX用です。 + [Exec Approvals](/ja-JP/tools/exec-approvals)を参照してください。 - Node **>= 22** が必要です。`pnpm` を推奨します。Gateway には Bun は **推奨されません**。 + Node **>= 22** が必要です。`pnpm` を推奨します。Gatewayに Bun は**推奨されません**。 - - はい。Gateway は軽量です。ドキュメントでは、個人利用なら **512MB-1GB RAM**、**1 core**、約 **500MB** のディスクで十分とされており、**Raspberry Pi 4 で動作可能** と明記されています。 + + はい。Gatewayは軽量です。ドキュメントでは個人利用に **512MB-1GB RAM**、**1コア**、約 **500MB** + のディスクで十分とされており、**Raspberry Pi 4でも動作する**と明記されています。 - もう少し余裕がほしい場合（ログ、メディア、他のサービス）、**2GB を推奨** しますが、 - これは厳密な最小要件ではありません。 + 余裕（ログ、メディア、他のサービス）が欲しい場合は、**2GBを推奨**しますが、 + 必須の最小値ではありません。 - ヒント: 小型の Pi/VPS で Gateway をホストし、ノート PC やスマートフォン上の **Node** をペアリングして、 - ローカルの screen/camera/canvas やコマンド実行を行えます。[Nodes](/ja-JP/nodes) を参照してください。 + ヒント: 小型のPi/VPSでGatewayをホストし、ノートPC/スマートフォン上の + ローカル画面/カメラ/canvasやコマンド実行のために **nodes** をペアリングできます。[Nodes](/ja-JP/nodes)を参照してください。 - - 短く言うと、動きますが、多少の粗さはあります。 + + 短く言うと、動作はしますが、多少の粗さは想定してください。 - - **64-bit** OS を使い、Node >= 22 を維持してください。 - - ログを確認しやすく、すばやく更新できるように、**ハッカブルな（git）インストール** を優先してください。 - - channels/Skills なしで始め、1 つずつ追加してください。 - - 変なバイナリ問題に当たった場合、通常は **ARM compatibility** の問題です。 + - **64-bit** OSを使い、Node >= 22 を維持してください。 + - **ハッカブルな（git）インストール**を推奨します。ログ確認や高速な更新がしやすくなります。 + - channels/Skills なしで始めて、その後1つずつ追加してください。 + - 奇妙なバイナリ問題に遭遇した場合、たいていは **ARM互換性** の問題です。 ドキュメント: [Linux](/ja-JP/platforms/linux), [Install](/ja-JP/install)。 - - この画面は、Gateway に到達できて認証済みであることに依存します。TUI は初回 hatch 時に - 「Wake up, my friend!」も自動送信します。この行が表示されて **応答がなく**、 - トークンが 0 のままなら、agent は一度も実行されていません。 + + この画面は、Gatewayに到達できて認証が通ることに依存しています。TUIは最初のhatch時に + 「Wake up, my friend!」も自動送信します。この行が表示されても**応答がなく**、 + トークンが0のままなら、エージェントは実行されていません。 - 1. Gateway を再起動します: + 1. Gatewayを再起動します: ```bash openclaw gateway restart @@ -261,78 +267,82 @@ x-i18n: openclaw logs --follow ``` - 3. それでも止まる場合は、次を実行します: + 3. まだ止まる場合は、次を実行します: ```bash openclaw doctor ``` - Gateway がリモートにある場合は、トンネル/Tailscale 接続が有効であり、 - UI が正しい Gateway を指していることを確認してください。[Remote access](/ja-JP/gateway/remote) を参照してください。 + Gatewayがリモートにある場合は、トンネル/Tailscale接続が有効であり、UIが + 正しいGatewayを指していることを確認してください。[Remote access](/ja-JP/gateway/remote)を参照してください。 - - はい。**state directory** と **workspace** をコピーしてから、Doctor を 1 回実行してください。これにより、 - **両方の場所** をコピーする限り、ボットを「まったく同じ状態」（memory、session history、auth、channel - state）に保てます。 + + はい。**state directory** と **workspace** をコピーしてから、Doctorを一度実行してください。これにより + **両方の**場所をコピーしている限り、botを「まったく同じ状態」（メモリ、セッション履歴、認証、チャネル + 状態）で維持できます: - 1. 新しいマシンに OpenClaw をインストールします。 + 1. 新しいマシンにOpenClawをインストールします。 2. 古いマシンから `$OPENCLAW_STATE_DIR`（デフォルト: `~/.openclaw`）をコピーします。 3. workspace（デフォルト: `~/.openclaw/workspace`）をコピーします。 - 4. `openclaw doctor` を実行し、Gateway service を再起動します。 + 4. `openclaw doctor` を実行し、Gatewayサービスを再起動します。 - これにより、設定、認証プロファイル、WhatsApp の認証情報、セッション、メモリが保持されます。remote mode の場合は、gateway host がセッションストアとワークスペースを保持することを忘れないでください。 + これにより、設定、auth profiles、WhatsApp認証情報、セッション、メモリが保持されます。 + remote mode を使用している場合は、gateway host が session store と workspace を所有していることを + 忘れないでください。 - **重要:** workspace だけを GitHub に commit/push している場合、バックアップしているのは **memory + bootstrap files** だけであり、**セッション履歴や認証** は含まれません。これらは `~/.openclaw/` 配下にあります（たとえば `~/.openclaw/agents//sessions/`）。 + **重要:** workspace だけをGitHubにcommit/pushしている場合、バックアップしているのは + **メモリ + bootstrapファイル** ですが、**セッション履歴や認証** は含まれません。これらは + `~/.openclaw/` 配下にあります（たとえば `~/.openclaw/agents//sessions/`）。 - 関連: [Migrating](/ja-JP/install/migrating), [ディスク上の保存場所](#ディスク上の保存場所), + 関連: [移行](/ja-JP/install/migrating), [ディスク上の保存場所](#where-things-live-on-disk), [Agent workspace](/ja-JP/concepts/agent-workspace), [Doctor](/ja-JP/gateway/doctor), - [Remote mode](/ja-JP/gateway/remote)。 + [Remote mode](/ja-JP/gateway/remote). - GitHub changelog を確認してください: + GitHub changelogを確認してください: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 最新の項目は先頭にあります。先頭のセクションに **Unreleased** とある場合、その次の日付付き - セクションが最新のリリース版です。項目は **Highlights**、**Changes**、および - **Fixes** ごとに分類されています（必要に応じて docs/other セクションもあります）。 + 最新の項目は先頭にあります。先頭セクションが **Unreleased** と表示されている場合、 + 次の日付付きセクションが最新のリリース済みバージョンです。項目は **Highlights**、**Changes**、および + **Fixes** ごとにグループ化されています（必要に応じて docs/その他のセクションもあります）。 - - 一部の Comcast/Xfinity 接続では、Xfinity - Advanced Security により `docs.openclaw.ai` が誤ってブロックされます。無効化するか `docs.openclaw.ai` を許可リストに追加してから再試行してください。 - 解除に協力するには、こちらから報告してください: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 + + 一部のComcast/Xfinity接続では、Xfinity + Advanced Security によって `docs.openclaw.ai` が誤ってブロックされます。これを無効化するか、`docs.openclaw.ai` を許可リストに追加してから再試行してください。 + 次の場所から報告して、ブロック解除にご協力ください: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 - それでもサイトにアクセスできない場合、ドキュメントは GitHub にもミラーされています: + それでもサイトにアクセスできない場合、ドキュメントはGitHubにもミラーされています: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - - **Stable** と **beta** は別のコードラインではなく、**npm dist-tags** です。 + + **Stable** と **beta** は別々のコードラインではなく、**npm dist-tags** です: - `latest` = stable - - `beta` = テスト用の早期ビルド + - `beta` = テスト用の先行ビルド - 通常、stable リリースはまず **beta** に入り、その後、明示的な + 通常、stableリリースはまず **beta** に入り、その後、明示的な 昇格ステップによって同じバージョンが `latest` に移されます。メンテナーは必要に応じて - 直接 `latest` に公開することもできます。そのため、昇格後は beta と stable が + 直接 `latest` に公開することもできます。そのため、昇格後にはbetaとstableが **同じバージョン** を指すことがあります。 変更内容はこちらで確認できます: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - インストール用ワンライナーと beta と dev の違いについては、下のアコーディオンを参照してください。 + インストール用ワンライナーと、betaとdevの違いについては、下のaccordionを参照してください。 - - **Beta** は npm dist-tag の `beta` です（昇格後は `latest` と同じになる場合があります）。 - **Dev** は `main` の先頭が移動し続けるもの（git）で、公開時には npm dist-tag の `dev` が使われます。 + + **Beta** は npm dist-tag の `beta` です（昇格後は `latest` と同じ場合があります）。 + **Dev** は `main` の移動する先端（git）で、公開される場合は npm dist-tag の `dev` を使用します。 ワンライナー（macOS/Linux）: @@ -344,15 +354,15 @@ x-i18n: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Windows インストーラー（PowerShell）: + Windowsインストーラー（PowerShell）: [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) 詳細: [Development channels](/ja-JP/install/development-channels) と [Installer flags](/ja-JP/install/installer)。 - - 方法は 2 つあります。 + + 方法は2つあります: 1. **Dev channel（git checkout）:** @@ -362,15 +372,15 @@ x-i18n: これにより `main` ブランチに切り替わり、ソースから更新されます。 - 2. **Hackable install（インストーラーサイトから）:** + 2. **ハッカブルなインストール（インストーラーサイトから）:** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - これにより編集可能なローカルリポジトリが手に入り、その後は git 経由で更新できます。 + これにより、編集可能なローカルリポジトリが得られ、その後はgit経由で更新できます。 - 手動でクリーンに clone したい場合は、次を使ってください: + 手動でクリーンなcloneを行いたい場合は、次を使用してください: ```bash git clone https://github.com/openclaw/openclaw.git @@ -387,22 +397,22 @@ x-i18n: おおよその目安: - - **Install:** 2〜5 分 - - **Onboarding:** 設定する channels/models の数に応じて 5〜15 分 + - **Install:** 2〜5分 + - **オンボーディング:** 設定するchannels/modelsの数に応じて5〜15分 - 固まる場合は [Installer stuck](#クイックスタートと初回セットアップ) - と [行き詰まりました。最速で抜け出す方法は？](#クイックスタートと初回セットアップ) の高速デバッグループを参照してください。 + 途中で止まる場合は、[Installer stuck](#quick-start-and-first-run-setup) + と [I am stuck](#quick-start-and-first-run-setup) の高速デバッグループを使ってください。 - - **詳細出力** 付きでインストーラーを再実行してください: + + **詳細出力** を付けてインストーラーを再実行してください: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - verbose 付きの beta インストール: + verbose付きのbetaインストール: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -414,7 +424,7 @@ x-i18n: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` - Windows（PowerShell）での相当手順: + Windows（PowerShell）での同等手順: ```powershell # install.ps1 にはまだ専用の -Verbose フラグはありません。 @@ -427,40 +437,40 @@ x-i18n: - - Windows でよくある問題は 2 つあります。 + + Windowsでよくある問題は2つあります: **1) npm error spawn git / git not found** - - **Git for Windows** をインストールし、`git` が PATH 上にあることを確認してください。 - - PowerShell を閉じて再度開き、インストーラーを再実行してください。 + - **Git for Windows** をインストールし、`git` がPATHにあることを確認してください。 + - PowerShellを閉じて再度開いてから、インストーラーを再実行してください。 **2) インストール後に openclaw is not recognized と表示される** - - npm のグローバル bin フォルダーが PATH にありません。 - - パスを確認します: + - npmのグローバルbinフォルダーがPATHにありません。 + - パスを確認してください: ```powershell npm config get prefix ``` - - そのディレクトリをユーザー PATH に追加してください（Windows では `\bin` サフィックスは不要です。多くの環境では `%AppData%\npm` です）。 - - PATH 更新後に PowerShell を閉じて再度開いてください。 + - そのディレクトリをユーザーPATHに追加してください（Windowsでは `\bin` 接尾辞は不要です。多くのシステムでは `%AppData%\npm` です）。 + - PATH更新後はPowerShellを閉じて再度開いてください。 - 最もスムーズな Windows セットアップを望む場合は、ネイティブ Windows ではなく **WSL2** を使ってください。 + Windowsで最もスムーズにセットアップしたい場合は、ネイティブWindowsではなく **WSL2** を使用してください。 ドキュメント: [Windows](/ja-JP/platforms/windows)。 - - これは通常、ネイティブ Windows シェルでのコンソールコードページ不一致です。 + + これは通常、ネイティブWindowsシェルでのコンソールコードページ不一致が原因です。 症状: - `system.run`/`exec` の出力で中国語が文字化けする - - 同じコマンドが別のターミナルプロファイルでは正しく表示される + - 同じコマンドが別のターミナルプロファイルでは正常に見える - PowerShell での簡単な回避策: + PowerShellでの一時的な回避策: ```powershell chcp 65001 @@ -469,22 +479,21 @@ x-i18n: $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - その後、Gateway を再起動してコマンドを再試行してください: + その後、Gatewayを再起動してコマンドを再試行してください: ```powershell openclaw gateway restart ``` - 最新の OpenClaw でも再現する場合は、以下で追跡/報告してください: + 最新のOpenClawでも引き続き再現する場合は、次で追跡・報告してください: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - **ハッカブルな（git）インストール** を使って、完全なソースとドキュメントをローカルに置いてから、 - そのフォルダー内でボット（または Claude/Codex）に質問してください。そうすればリポジトリを読み、 - 正確に回答できます。 + + **ハッカブルな（git）インストール** を使ってソースとドキュメント一式をローカルに置き、そのフォルダーから + bot（または Claude/Codex）に質問してください。そうすればリポジトリを読んで正確に答えられます。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -494,50 +503,50 @@ x-i18n: - - 簡単に言うと、Linux ガイドに従ってからオンボーディングを実行してください。 + + 短い答え: Linuxガイドに従ってから、オンボーディングを実行してください。 - - Linux の最短手順 + service インストール: [Linux](/ja-JP/platforms/linux)。 + - Linuxのクイックパス + サービスインストール: [Linux](/ja-JP/platforms/linux)。 - 完全な手順: [はじめに](/ja-JP/start/getting-started)。 - - インストーラー + 更新: [Install & updates](/ja-JP/install/updating)。 + - インストーラー + アップデート: [Install & updates](/ja-JP/install/updating)。 - - どの Linux VPS でも動作します。サーバーにインストールし、その後 SSH/Tailscale で Gateway にアクセスしてください。 + + どのLinux VPSでも動作します。サーバーにインストールし、その後SSH/TailscaleでGatewayにアクセスしてください。 ガイド: [exe.dev](/ja-JP/install/exe-dev), [Hetzner](/ja-JP/install/hetzner), [Fly.io](/ja-JP/install/fly)。 リモートアクセス: [Gateway remote](/ja-JP/gateway/remote)。 - - よく使われるプロバイダーをまとめた **hosting hub** があります。1 つ選んでガイドに従ってください。 + + 一般的なプロバイダーをまとめた **hosting hub** があります。1つ選んでガイドに従ってください: - - [VPS hosting](/ja-JP/vps)（すべてのプロバイダーを 1 か所に集約） + - [VPS hosting](/ja-JP/vps)（すべてのプロバイダーを1か所に集約） - [Fly.io](/ja-JP/install/fly) - [Hetzner](/ja-JP/install/hetzner) - [exe.dev](/ja-JP/install/exe-dev) - クラウドでの動作方法: **Gateway はサーバー上で実行され**、Control UI（または Tailscale/SSH）を通じて - ノート PC やスマートフォンからアクセスします。state + workspace はサーバー上に - あるため、ホストを信頼できる保存元として扱い、バックアップしてください。 + クラウドでの動作方法: **Gatewayはサーバー上で実行** され、Control UI（またはTailscale/SSH）経由で + ノートPC/スマートフォンからアクセスします。state + workspace はサーバー上に + あるため、ホストを信頼できる唯一の情報源として扱い、バックアップしてください。 - そのクラウド Gateway に **Node**（Mac/iOS/Android/headless）をペアリングして、 - Gateway はクラウドに置いたまま、ノート PC 上のローカル screen/camera/canvas へのアクセスや - コマンド実行を行うこともできます。 + そのクラウドGatewayに **nodes**（Mac/iOS/Android/headless）をペアリングして、 + Gatewayをクラウドに置いたまま、ローカル画面/カメラ/canvasへのアクセスや + ノートPC上でのコマンド実行を行えます。 ハブ: [Platforms](/ja-JP/platforms)。リモートアクセス: [Gateway remote](/ja-JP/gateway/remote)。 Nodes: [Nodes](/ja-JP/nodes), [Nodes CLI](/cli/nodes)。 - - 簡単に言うと、**可能ですが推奨はしません**。更新フローでは - Gateway が再起動されることがあり（アクティブセッションが切断されます）、クリーンな git checkout が必要になる場合があり、 - 確認を求めることもあります。より安全なのは、オペレーターとしてシェルから更新を実行することです。 + + 短い答え: **可能ですが、推奨はしません**。更新フローによって + Gatewayが再起動し（アクティブセッションが切断される）、クリーンなgit checkoutが必要になることがあり、 + 確認プロンプトが出る場合もあります。より安全なのは、オペレーターとしてシェルから更新を実行することです。 - CLI を使用します: + CLIを使用してください: ```bash openclaw update @@ -558,229 +567,238 @@ x-i18n: - - `openclaw onboard` は推奨されるセットアップ手順です。**local mode** では次の項目を案内します。 + + `openclaw onboard` は推奨されるセットアップ手順です。**local mode** では、次の設定を案内します: - - **モデル/認証設定**（provider OAuth、API keys、Anthropic setup-token、LM Studio などのローカルモデルオプション） - - **Workspace** の場所 + bootstrap files - - **Gateway settings**（bind/port/auth/tailscale） - - **Channels**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage、および QQ Bot のようなバンドル済み channel plugins） - - **デーモンのインストール**（macOS の LaunchAgent、Linux/WSL2 の systemd user unit） + - **モデル/認証設定**（プロバイダーOAuth、APIキー、Anthropic setup-token、および LM Studio などのローカルモデルオプション） + - **Workspace** の場所 + bootstrapファイル + - **Gateway設定**（bind/port/auth/tailscale） + - **Channels**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage、および QQ Bot のようなバンドル済みchannel plugins） + - **デーモンのインストール**（macOSではLaunchAgent、Linux/WSL2ではsystemd user unit） - **ヘルスチェック** と **Skills** の選択 - また、設定されたモデルが不明または認証不足の場合に警告も表示します。 + また、設定されたモデルが不明または認証不足の場合には警告します。 - - いいえ。OpenClaw は **API keys**（Anthropic/OpenAI/others）でも、 - **ローカル専用モデル** でも実行できるため、データをデバイス上に保持できます。サブスクリプション（Claude - Pro/Max または OpenAI Codex）は、それらの provider を認証するための任意の方法です。 + + いいえ。OpenClawは **APIキー**（Anthropic/OpenAI/その他）または + **ローカル専用モデル** で実行できるため、データをデバイス上に保持できます。サブスクリプション（Claude + Pro/Max または OpenAI Codex）は、それらのプロバイダーを認証する任意の方法です。 - OpenClaw における Anthropic では、実用上の区分は次のとおりです。 + OpenClawでのAnthropicについて、実用上の区分は次のとおりです: - - **Anthropic API key**: 通常の Anthropic API 課金 - - **OpenClaw における Claude CLI / Claude subscription auth**: Anthropic のスタッフから、 - この利用方法は再び許可されていると伝えられており、Anthropic が新しい - ポリシーを公開しない限り、OpenClaw はこの統合における `claude -p` - の利用を認可されたものとして扱っています + - **Anthropic APIキー**: 通常のAnthropic API課金 + - **OpenClawでのClaude CLI / Claudeサブスクリプション認証**: Anthropicのスタッフから、 + この利用法は再び許可されていると伝えられており、Anthropicが新しい + ポリシーを公開しない限り、OpenClawではこの統合に対する `claude -p` + の使用を公認されたものとして扱っています - 長期間動作する gateway host では、Anthropic API keys の方が依然として - より予測しやすいセットアップです。OpenAI Codex OAuth は、OpenClaw のような外部 + 長期間稼働するgateway hostでは、Anthropic APIキーの方が依然として + より予測しやすいセットアップです。OpenAI Codex OAuthは、OpenClawのような外部 ツール向けに明示的にサポートされています。 - OpenClaw はそのほかに、次のようなホスト型のサブスクリプション方式もサポートしています。 + OpenClawはそのほかにも、次のようなホスト型サブスクリプション形式の選択肢をサポートしています: **Qwen Cloud Coding Plan**、**MiniMax Coding Plan**、および **Z.AI / GLM Coding Plan**。 ドキュメント: [Anthropic](/ja-JP/providers/anthropic), [OpenAI](/ja-JP/providers/openai), [Qwen Cloud](/ja-JP/providers/qwen), [MiniMax](/ja-JP/providers/minimax), [GLM Models](/ja-JP/providers/glm), - [Local models](/ja-JP/gateway/local-models), [Models](/ja-JP/concepts/models)。 + [ローカルモデル](/ja-JP/gateway/local-models), [Models](/ja-JP/concepts/models)。 - + はい。 - Anthropic のスタッフから、OpenClaw 形式の Claude CLI 利用は再び許可されていると伝えられているため、Anthropic が新しいポリシーを公開しない限り、OpenClaw は Claude subscription auth と `claude -p` の利用をこの統合で認可されたものとして扱います。最も予測しやすいサーバー側セットアップを望む場合は、代わりに Anthropic API key を使ってください。 + Anthropicのスタッフから、OpenClawスタイルのClaude CLI利用は再び許可されていると伝えられているため、 + Anthropicが新しいポリシーを公開しない限り、OpenClawではClaudeサブスクリプション認証と + `claude -p` の使用をこの統合において公認されたものとして扱っています。最も予測しやすい + サーバー側セットアップを求める場合は、代わりにAnthropic APIキーを使用してください。 - + はい。 - Anthropic のスタッフから、この利用方法は再び許可されていると伝えられているため、Anthropic が新しいポリシーを公開しない限り、OpenClaw は - Claude CLI の再利用と `claude -p` の利用をこの統合で認可されたものとして扱います。 + Anthropicのスタッフから、この利用法は再び許可されていると伝えられているため、OpenClawでは + Anthropicが新しいポリシーを公開しない限り、この統合におけるClaude CLIの再利用と + `claude -p` の使用を公認されたものとして扱っています。 - Anthropic setup-token も引き続き OpenClaw でサポートされるトークン経路として利用できますが、OpenClaw は現在、利用可能な場合は Claude CLI の再利用と `claude -p` を優先します。 - 本番環境やマルチユーザーワークロードでは、Anthropic API key auth の方が依然として - より安全で予測しやすい選択です。OpenClaw の他のサブスクリプション方式のホスト型 - オプションについては、[OpenAI](/ja-JP/providers/openai)、[Qwen / Model + Anthropic setup-token は引き続きサポートされるOpenClawのトークン経路として利用可能ですが、OpenClawは現在、利用可能な場合はClaude CLIの再利用と `claude -p` を優先します。 + 本番環境またはマルチユーザーのワークロードでは、Anthropic APIキー認証の方が依然として + より安全で予測しやすい選択です。OpenClawでそのほかのサブスクリプション形式のホスト型 + オプションを使いたい場合は、[OpenAI](/ja-JP/providers/openai)、[Qwen / Model Cloud](/ja-JP/providers/qwen)、[MiniMax](/ja-JP/providers/minimax)、および [GLM Models](/ja-JP/providers/glm) を参照してください。 - -これは、現在のウィンドウで **Anthropic の quota/rate limit** を使い切っていることを意味します。**Claude CLI** を使用している場合は、ウィンドウがリセットされるまで待つか、プランをアップグレードしてください。**Anthropic API key** を使用している場合は、Anthropic Console で使用量/課金を確認し、必要に応じて上限を引き上げてください。 + +これは、現在のウィンドウにおける **Anthropicのクォータ/レート制限** を使い切ったことを意味します。**Claude CLI** を +使用している場合は、ウィンドウがリセットされるまで待つか、プランをアップグレードしてください。**Anthropic APIキー** を +使用している場合は、Anthropic Console で +使用状況/課金を確認し、必要に応じて制限を引き上げてください。 メッセージが具体的に次の場合: `Extra usage is required for long context requests`、そのリクエストは - Anthropic の 1M context beta（`context1m: true`）を使おうとしています。これは、あなたの - 認証情報が long-context 課金の対象である場合にのみ動作します（API key 課金、または - Extra Usage を有効にした OpenClaw Claude-login 経路）。 + Anthropicの1Mコンテキストベータ（`context1m: true`）を使おうとしています。これは、 + 使用中の認証情報が長いコンテキスト課金に対応している場合にのみ機能します（APIキー課金、または + Extra Usage が有効なOpenClawのClaudeログイン経路）。 - ヒント: **fallback model** を設定すると、provider が rate-limited でも OpenClaw が応答を続けられます。 - [Models](/cli/models)、[OAuth](/ja-JP/concepts/oauth)、および + ヒント: **フォールバックモデル** を設定しておくと、プロバイダーがレート制限中でもOpenClawが + 応答を続けられます。[Models](/cli/models)、[OAuth](/ja-JP/concepts/oauth)、および [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/ja-JP/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context) を参照してください。 - - はい。OpenClaw にはバンドル済みの **Amazon Bedrock (Converse)** provider があります。AWS の env マーカーが存在する場合、OpenClaw はストリーミング/テキスト Bedrock カタログを自動検出し、それを暗黙的な `amazon-bedrock` provider としてマージできます。そうでない場合は、`plugins.entries.amazon-bedrock.config.discovery.enabled` を明示的に有効にするか、手動で provider エントリを追加できます。[Amazon Bedrock](/ja-JP/providers/bedrock) と [Model providers](/ja-JP/providers/models) を参照してください。管理されたキーのフローを好む場合は、Bedrock の前段に OpenAI 互換プロキシを置く方法も引き続き有効です。 + + はい。OpenClawにはバンドル済みの **Amazon Bedrock (Converse)** プロバイダーがあります。AWS env markers が存在する場合、OpenClawはストリーミング/テキストのBedrockカタログを自動検出し、暗黙的な `amazon-bedrock` プロバイダーとしてマージできます。それ以外の場合は、`plugins.entries.amazon-bedrock.config.discovery.enabled` を明示的に有効化するか、手動のプロバイダーエントリーを追加できます。[Amazon Bedrock](/ja-JP/providers/bedrock) と [Model providers](/ja-JP/providers/models) を参照してください。マネージドキーのフローを望む場合は、Bedrockの前段にOpenAI互換プロキシを置く方法も引き続き有効です。 - - OpenClaw は **OpenAI Code (Codex)** を OAuth（ChatGPT サインイン）経由でサポートします。オンボーディングは OAuth フローを実行でき、適切な場合はデフォルトモデルを `openai-codex/gpt-5.4` に設定します。[Model providers](/ja-JP/concepts/model-providers) と [Onboarding (CLI)](/ja-JP/start/wizard) を参照してください。 + + OpenClawは、OAuth（ChatGPTサインイン）経由で **OpenAI Code (Codex)** をサポートしています。オンボーディングではOAuthフローを実行でき、適切な場合はデフォルトモデルを `openai-codex/gpt-5.4` に設定します。[Model providers](/ja-JP/concepts/model-providers) と [Onboarding (CLI)](/ja-JP/start/wizard) を参照してください。 - - OpenClaw はこの 2 つの経路を別々に扱います。 + + OpenClawでは、この2つの経路を別々に扱います: - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth - - `openai/gpt-5.4` = 直接の OpenAI Platform API + - `openai/gpt-5.4` = 直接のOpenAI Platform API - OpenClaw では、ChatGPT/Codex サインインは `openai-codex/*` 経路に接続されており、 - 直接の `openai/*` 経路には接続されていません。OpenClaw で直接 API 経路を使いたい場合は、 - `OPENAI_API_KEY`（または同等の OpenAI provider 設定）を設定してください。 - OpenClaw で ChatGPT/Codex サインインを使いたい場合は、`openai-codex/*` を使ってください。 + OpenClawでは、ChatGPT/Codexサインインは `openai-codex/*` 経路に接続されており、 + 直接の `openai/*` 経路には接続されていません。OpenClawで直接API経路を使いたい場合は、 + `OPENAI_API_KEY`（または同等のOpenAIプロバイダー設定）を設定してください。 + OpenClawでChatGPT/Codexサインインを使いたい場合は、`openai-codex/*` を使ってください。 - - `openai-codex/*` は Codex OAuth 経路を使用しており、利用可能な quota window は - OpenAI によって管理され、プランに依存します。実際には、両方が同じアカウントに紐づいていても、 - その上限は ChatGPT の Web サイト/アプリでの体験と異なることがあります。 + + `openai-codex/*` はCodex OAuth経路を使用しており、利用可能なクォータウィンドウは + OpenAI側で管理され、プランにも依存します。実際には、両方が同じアカウントに紐づいていても、 + それらの制限はChatGPTのWebサイト/アプリでの体験と異なることがあります。 - OpenClaw は現在見えている provider の usage/quota window を - `openclaw models status` に表示できますが、ChatGPT Web の - entitlement を直接 API アクセスに変換したり正規化したりはしません。OpenAI Platform の直接 - 課金/上限経路を使いたい場合は、API key とともに `openai/*` を使用してください。 + OpenClawは `openclaw models status` で、現在見えているプロバイダーの使用状況/クォータウィンドウを表示できますが、 + ChatGPT Webの権限を直接APIアクセスへと捏造または正規化することはありません。直接のOpenAI Platform + の課金/制限経路を使いたい場合は、APIキー付きの `openai/*` を使用してください。 - - はい。OpenClaw は **OpenAI Code (Codex) subscription OAuth** を完全にサポートしています。 - OpenAI は、OpenClaw のような外部ツール/ワークフローでの subscription OAuth 利用を - 明示的に許可しています。オンボーディングで OAuth フローを実行できます。 + + はい。OpenClawは **OpenAI Code (Codex) subscription OAuth** を完全にサポートしています。 + OpenAIは、OpenClawのような外部ツール/ワークフローでのサブスクリプションOAuth利用を + 明示的に許可しています。オンボーディングでOAuthフローを実行できます。 [OAuth](/ja-JP/concepts/oauth)、[Model providers](/ja-JP/concepts/model-providers)、および [Onboarding (CLI)](/ja-JP/start/wizard) を参照してください。 - - Gemini CLI は、`openclaw.json` 内の client id や secret ではなく、**plugin auth flow** を使います。 + + Gemini CLIは、`openclaw.json` 内のclient idやsecretではなく、**plugin auth flow** を使用します。 手順: - 1. `gemini` が `PATH` 上に来るように Gemini CLI をローカルにインストールします + 1. `gemini` が `PATH` に入るようにGemini CLIをローカルにインストールする - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` - 2. Plugin を有効にします: `openclaw plugins enable google` - 3. ログインします: `openclaw models auth login --provider google-gemini-cli --set-default` + 2. Pluginを有効化する: `openclaw plugins enable google` + 3. ログインする: `openclaw models auth login --provider google-gemini-cli --set-default` 4. ログイン後のデフォルトモデル: `google-gemini-cli/gemini-3-flash-preview` - 5. リクエストが失敗する場合は、gateway host に `GOOGLE_CLOUD_PROJECT` または `GOOGLE_CLOUD_PROJECT_ID` を設定します + 5. リクエストが失敗する場合は、gateway host で `GOOGLE_CLOUD_PROJECT` または `GOOGLE_CLOUD_PROJECT_ID` を設定する - これにより、OAuth トークンは gateway host 上の auth profiles に保存されます。詳細: [Model providers](/ja-JP/concepts/model-providers)。 + これにより、OAuthトークンはgateway host 上のauth profilesに保存されます。詳細: [Model providers](/ja-JP/concepts/model-providers)。 - - 通常は適していません。OpenClaw には大きなコンテキストと強い安全性が必要であり、小さなモデルでは切り詰めや漏れが発生します。どうしても使う場合は、ローカルで実行できる **できるだけ大きな** モデルビルド（LM Studio）を使用し、[/gateway/local-models](/ja-JP/gateway/local-models) を参照してください。より小さい/量子化されたモデルは prompt-injection リスクを高めます。詳細は [Security](/ja-JP/gateway/security) を参照してください。 + + 通常はいいえ。OpenClawには大きなコンテキストと強い安全性が必要であり、小さなカードでは切り詰めや漏洩が起こります。どうしても使う必要がある場合は、ローカルで実行できる**最大の**モデルビルド（LM Studio）を使い、[/gateway/local-models](/ja-JP/gateway/local-models) を参照してください。より小さい/量子化されたモデルはプロンプトインジェクションのリスクを高めます。詳しくは [Security](/ja-JP/gateway/security) を参照してください。 - - リージョン固定のエンドポイントを選んでください。OpenRouter は MiniMax、Kimi、GLM 向けに米国内ホストのオプションを提供しているため、データをそのリージョン内に保持したい場合は米国内ホスト版を選択してください。`models.mode: "merge"` を使えば、Anthropic/OpenAI をこれらと並べて一覧表示できるため、選択したリージョン固定 provider を尊重しつつ fallback も利用できます。 + + リージョン固定のエンドポイントを選んでください。OpenRouterはMiniMax、Kimi、GLM向けにUSホストのオプションを提供しているため、データをそのリージョン内に保つにはUSホスト版を選択してください。それでも `models.mode: "merge"` を使えばAnthropic/OpenAIを併記できるため、選択したリージョン固定プロバイダーを尊重しながらフォールバックも利用できます。 - - いいえ。OpenClaw は macOS または Linux で動作します（Windows は WSL2 経由）。Mac mini は任意です。常時稼働ホストとして購入する人もいますが、小型の VPS、ホームサーバー、または Raspberry Pi クラスのマシンでも動作します。 + + いいえ。OpenClawはmacOSまたはLinuxで動作します（WindowsはWSL2経由）。Mac miniは任意です。一部の人は常時稼働ホストとして + 購入しますが、小型VPS、ホームサーバー、またはRaspberry Piクラスのマシンでも動作します。 - Mac が必要なのは **macOS 専用ツール** の場合だけです。iMessage には [BlueBubbles](/ja-JP/channels/bluebubbles)（推奨）を使ってください。BlueBubbles サーバーは任意の Mac で動作し、Gateway は Linux など別の場所で動作できます。ほかの macOS 専用ツールを使いたい場合は、Gateway を Mac 上で動かすか、macOS の Node をペアリングしてください。 + Macが必要なのは **macOS専用ツール** の場合だけです。iMessageには [BlueBubbles](/ja-JP/channels/bluebubbles)（推奨）を使用してください。BlueBubblesサーバーは任意のMac上で動作し、GatewayはLinuxやその他の場所で動かせます。ほかのmacOS専用ツールを使いたい場合は、GatewayをMac上で動かすか、macOS node をペアリングしてください。 ドキュメント: [BlueBubbles](/ja-JP/channels/bluebubbles), [Nodes](/ja-JP/nodes), [Mac remote mode](/ja-JP/platforms/mac/remote)。 - - Messages にサインインした **何らかの macOS デバイス** が必要です。Mac mini である必要は **ありません**。iMessage には **[BlueBubbles](/ja-JP/channels/bluebubbles)**（推奨）を使ってください。BlueBubbles サーバーは macOS 上で動作し、Gateway は Linux など別の場所で動かせます。 + + Messagesにサインインした **何らかのmacOSデバイス** が必要です。**Mac miniである必要はありません**。 + iMessageには **[BlueBubbles](/ja-JP/channels/bluebubbles)**（推奨）を使用してください。BlueBubblesサーバーはmacOS上で動作し、GatewayはLinuxやその他の場所で動かせます。 - よくある構成: + 一般的なセットアップ: - - Gateway は Linux/VPS で動かし、BlueBubbles サーバーは Messages にサインインした任意の Mac で動かす。 - - 最もシンプルな 1 台構成を望むなら、すべてをその Mac 上で動かす。 + - GatewayはLinux/VPS上で実行し、BlueBubblesサーバーはMessagesにサインインした任意のMac上で実行する。 + - 最もシンプルな単一マシン構成にしたい場合は、すべてをMac上で実行する。 ドキュメント: [BlueBubbles](/ja-JP/channels/bluebubbles), [Nodes](/ja-JP/nodes), [Mac remote mode](/ja-JP/platforms/mac/remote)。 - - はい。**Mac mini が Gateway を実行** し、MacBook Pro は - **Node**（コンパニオンデバイス）として接続できます。Node は Gateway を実行せず、 - そのデバイス上の screen/camera/canvas や `system.run` などの追加機能を提供します。 + + はい。**Mac miniでGatewayを実行** し、MacBook Proを + **node**（コンパニオンデバイス）として接続できます。NodesはGatewayを実行しません。代わりに、そのデバイス上の + 画面/カメラ/canvas や `system.run` のような追加機能を提供します。 - よくあるパターン: + 一般的なパターン: - - Gateway は Mac mini 上（常時稼働）。 - - MacBook Pro では macOS アプリまたは Node ホストを実行し、Gateway にペアリングする。 + - GatewayはMac mini上（常時稼働）。 + - MacBook ProはmacOSアプリまたはnode hostを実行し、Gatewayとペアリングする。 - 確認には `openclaw nodes status` / `openclaw nodes list` を使う。 ドキュメント: [Nodes](/ja-JP/nodes), [Nodes CLI](/cli/nodes)。 - - Bun は **推奨されません**。特に WhatsApp と Telegram でランタイムバグが見られます。 - 安定した gateway には **Node** を使ってください。 + + Bunは**推奨されません**。特にWhatsAppとTelegramでランタイムバグが見られます。 + 安定したGatewayには **Node** を使用してください。 - それでも Bun を試したい場合は、WhatsApp/Telegram なしの非本番 gateway で行ってください。 + それでもBunを試したい場合は、WhatsApp/Telegramなしの非本番Gatewayで + 試してください。 - - `channels.telegram.allowFrom` は **人間の送信者の Telegram user ID**（数値）です。ボットのユーザー名ではありません。 + + `channels.telegram.allowFrom` は、**人間の送信者のTelegramユーザーID**（数値）です。botのユーザー名ではありません。 - オンボーディングでは `@username` 入力を受け付けて数値 ID に解決しますが、OpenClaw の認可では数値 ID のみを使用します。 + セットアップでは数値のユーザーIDのみを受け付けます。設定に古い `@username` エントリーがすでにある場合は、`openclaw doctor --fix` で解決を試みることができます。 - より安全な方法（サードパーティ bot なし）: + より安全な方法（サードパーティbot不要）: - - bot に DM を送り、その後 `openclaw logs --follow` を実行して `from.id` を確認します。 + - botにDMを送ってから、`openclaw logs --follow` を実行し、`from.id` を確認する。 - 公式 Bot API: + 公式Bot API: - - bot に DM を送り、その後 `https://api.telegram.org/bot/getUpdates` を呼び出して `message.from.id` を確認します。 + - botにDMを送ってから、`https://api.telegram.org/bot/getUpdates` を呼び出し、`message.from.id` を確認する。 - サードパーティ（プライバシー性は低い）: + サードパーティ（プライバシーはやや低い）: - - `@userinfobot` または `@getidsbot` に DM を送ります。 + - `@userinfobot` または `@getidsbot` にDMする。 [/channels/telegram](/ja-JP/channels/telegram#access-control-and-activation) を参照してください。 - - はい。**マルチエージェントルーティング** を使います。各送信者の WhatsApp **DM**（peer `kind: "direct"`、送信者 E.164 形式 `+15551234567` のようなもの）を別々の `agentId` にバインドすれば、各人が専用の workspace と session store を持てます。返信は引き続き **同じ WhatsApp アカウント** から送られ、DM アクセス制御（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）は WhatsApp アカウントごとにグローバルです。[Multi-Agent Routing](/ja-JP/concepts/multi-agent) と [WhatsApp](/ja-JP/channels/whatsapp) を参照してください。 + + はい。**multi-agent routing** で可能です。各送信者のWhatsApp **DM**（peer `kind: "direct"`、送信者E.164 形式の `+15551234567` など）を別々の `agentId` にバインドすれば、各人が自分専用のworkspaceとsession storeを持てます。返信は引き続き**同じWhatsAppアカウント**から送られ、DMアクセス制御（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）はWhatsAppアカウントごとにグローバルです。[Multi-Agent Routing](/ja-JP/concepts/multi-agent) と [WhatsApp](/ja-JP/channels/whatsapp) を参照してください。 - - はい。マルチエージェントルーティングを使います。各エージェントに独自のデフォルトモデルを割り当て、その後、受信ルート（provider アカウントまたは特定の peer）を各エージェントにバインドしてください。設定例は [Multi-Agent Routing](/ja-JP/concepts/multi-agent) にあります。あわせて [Models](/ja-JP/concepts/models) と [Configuration](/ja-JP/gateway/configuration) も参照してください。 + + はい。multi-agent routing を使ってください。各エージェントに独自のデフォルトモデルを割り当て、その後、各エージェントに受信ルート（プロバイダーアカウントまたは特定のpeer）をバインドします。設定例は [Multi-Agent Routing](/ja-JP/concepts/multi-agent) にあります。あわせて [Models](/ja-JP/concepts/models) と [Configuration](/ja-JP/gateway/configuration) も参照してください。 - - はい。Homebrew は Linux（Linuxbrew）をサポートしています。簡単なセットアップ: + + はい。HomebrewはLinux（Linuxbrew）をサポートしています。クイックセットアップ: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -789,25 +807,25 @@ x-i18n: brew install ``` - OpenClaw を systemd 経由で実行する場合は、service の PATH に `/home/linuxbrew/.linuxbrew/bin`（またはあなたの brew prefix）が含まれていることを確認し、非ログインシェルでも `brew` でインストールしたツールが解決されるようにしてください。 - 最近のビルドでは、Linux の systemd services で一般的なユーザー bin ディレクトリ（たとえば `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`）も先頭に追加され、`PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR`、`FNM_DIR` が設定されている場合はそれらも尊重されます。 + OpenClawをsystemd経由で実行する場合は、サービスのPATHに `/home/linuxbrew/.linuxbrew/bin`（またはあなたのbrew prefix）を含めて、非ログインシェルでも `brew` でインストールしたツールが解決されるようにしてください。 + 最近のビルドでは、Linuxのsystemdサービスで一般的なユーザーbinディレクトリ（たとえば `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`）も先頭に追加され、`PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR`、`FNM_DIR` が設定されている場合はそれらも尊重されます。 - - - **ハッカブルな（git）インストール:** 完全なソースチェックアウトで、編集可能、コントリビューターに最適です。 - ローカルでビルドを実行でき、コードやドキュメントにパッチを当てられます。 - - **npm install:** グローバル CLI インストールで、リポジトリはなく、「とにかく動かしたい」場合に最適です。 - 更新は npm dist-tags から取得されます。 + + - **ハッカブルな（git）インストール:** フルソースチェックアウトで、編集可能、コントリビューターに最適です。 + ローカルでビルドを実行でき、コード/ドキュメントにパッチを当てられます。 + - **npm install:** グローバルCLIインストールで、リポジトリは含まれず、「とにかく動かしたい」場合に最適です。 + 更新はnpm dist-tagsから取得されます。 ドキュメント: [はじめに](/ja-JP/start/getting-started), [Updating](/ja-JP/install/updating)。 - はい。もう一方の方式をインストールしてから、gateway service が新しい entrypoint を指すように Doctor を実行してください。 - これで **データは削除されません**。変更されるのは OpenClaw のコードインストールだけです。state - （`~/.openclaw`）と workspace（`~/.openclaw/workspace`）はそのまま残ります。 + はい。もう一方の方式をインストールしてから、gateway service が新しいentrypointを指すようにDoctorを実行してください。 + これは**データを削除しません**。変更されるのはOpenClawコードのインストールだけです。state + （`~/.openclaw`）とworkspace（`~/.openclaw/workspace`）はそのまま残ります。 npm から git へ: @@ -828,66 +846,66 @@ x-i18n: openclaw gateway restart ``` - Doctor は gateway service の entrypoint の不一致を検出し、現在のインストールに合うように service 設定の書き換えを提案します（自動化では `--repair` を使用）。 + Doctor は gateway service のentrypoint不一致を検出し、現在のインストールに一致するようにservice設定を書き換えることを提案します（自動化では `--repair` を使用してください）。 - バックアップのヒント: [バックアップ戦略](#ディスク上の保存場所) を参照してください。 + バックアップのヒント: [バックアップ戦略](#where-things-live-on-disk) を参照してください。 - - 簡単に言うと、**24 時間 365 日の信頼性が欲しいなら VPS を使ってください**。最小限の手間を求め、スリープや再起動を許容できるなら、ローカルで実行してください。 + + 短い答え: **24時間365日の信頼性が欲しいなら、VPS を使ってください**。最小の手間を優先し、スリープや再起動を許容できるなら、ローカルで実行してください。 - **ノート PC（ローカル Gateway）** + **ノートPC（local Gateway）** - - **長所:** サーバー費用が不要、ローカルファイルへ直接アクセスできる、ブラウザー画面が見える。 - - **短所:** スリープ/ネットワーク切断 = 切断、OS 更新/再起動で中断、常に起動状態を保つ必要がある。 + - **利点:** サーバー費用なし、ローカルファイルへ直接アクセスできる、ブラウザーウィンドウを表示したまま使える。 + - **欠点:** スリープ/ネットワーク切断 = 接続断、OS更新/再起動で中断、起動したままにしておく必要がある。 **VPS / クラウド** - - **長所:** 常時稼働、安定したネットワーク、ノート PC のスリープ問題がない、稼働し続けやすい。 - - **短所:** 多くは headless で動く（スクリーンショットを使用）、ファイルアクセスはリモートのみ、更新には SSH が必要。 + - **利点:** 常時稼働、安定したネットワーク、ノートPCのスリープ問題がない、動かし続けやすい。 + - **欠点:** 多くの場合 headless で動作する（スクリーンショットを使う）、ファイルアクセスはリモートのみ、更新には SSH が必要。 - **OpenClaw 固有の注意:** WhatsApp/Telegram/Slack/Mattermost/Discord はいずれも VPS で問題なく動作します。実際のトレードオフは **headless browser** か可視ブラウザー画面か、という点です。[Browser](/ja-JP/tools/browser) を参照してください。 + **OpenClaw固有の注意:** WhatsApp/Telegram/Slack/Mattermost/Discord はどれも VPS から問題なく動作します。実際のトレードオフは **headless browser** か表示付きウィンドウか、という点だけです。[Browser](/ja-JP/tools/browser) を参照してください。 - **推奨デフォルト:** 以前に gateway の切断を経験したなら VPS。Mac を積極的に使っていて、ローカルファイルアクセスや可視ブラウザーでの UI 自動化が欲しいときはローカルが最適です。 + **推奨されるデフォルト:** 以前に gateway の切断があったなら VPS。Mac をアクティブに使っていて、ローカルファイルアクセスや表示付きブラウザーでのUI自動化が欲しい場合はローカルが最適です。 - 必須ではありませんが、**信頼性と分離のために推奨** します。 + 必須ではありませんが、**信頼性と分離性のために推奨** します。 - - **専用ホスト（VPS/Mac mini/Pi）:** 常時稼働、スリープ/再起動による中断が少ない、権限がクリーン、稼働し続けやすい。 - - **共有ノート PC/デスクトップ:** テストやアクティブな利用にはまったく問題ありませんが、マシンがスリープしたり更新したりすると一時停止が発生します。 + - **専用ホスト（VPS/Mac mini/Pi）:** 常時稼働、スリープ/再起動による中断が少ない、権限が整理しやすい、動かし続けやすい。 + - **共用ノートPC/デスクトップ:** テストやアクティブ利用にはまったく問題ありませんが、マシンのスリープや更新で一時停止が起こることは想定してください。 - 両方の利点を取りたい場合は、Gateway を専用ホストに置き、ノート PC をローカルの screen/camera/exec ツール用 **Node** としてペアリングしてください。[Nodes](/ja-JP/nodes) を参照してください。 - セキュリティガイダンスについては [Security](/ja-JP/gateway/security) を読んでください。 + 両方の利点を得たい場合は、Gateway は専用ホストに置き、ローカル画面/カメラ/exec ツール用にノートPCを **node** としてペアリングしてください。[Nodes](/ja-JP/nodes) を参照してください。 + セキュリティガイダンスについては、[Security](/ja-JP/gateway/security) を参照してください。 - OpenClaw は軽量です。基本的な Gateway + 1 つのチャットチャネルなら: + OpenClaw は軽量です。基本的な Gateway + 1つのチャットチャネルなら: - - **絶対的な最小要件:** 1 vCPU、1GB RAM、約 500MB のディスク。 - - **推奨:** 1〜2 vCPU、2GB RAM 以上で余裕を確保（ログ、メディア、複数チャネル）。Node ツールやブラウザー自動化はリソースを多く消費することがあります。 + - **絶対最小:** 1 vCPU、1GB RAM、約500MBのディスク。 + - **推奨:** 1〜2 vCPU、2GB RAM 以上の余裕（ログ、メディア、複数チャネル用）。Node ツールやブラウザー自動化はリソースを多く消費することがあります。 - OS: **Ubuntu LTS**（または最近の Debian/Ubuntu）を使ってください。Linux のインストール手順はそこで最もよくテストされています。 + OS: **Ubuntu LTS**（または最新の Debian/Ubuntu 系）を使用してください。Linux のインストール経路ではこれが最もよく検証されています。 ドキュメント: [Linux](/ja-JP/platforms/linux), [VPS hosting](/ja-JP/vps)。 - + はい。VM は VPS と同じように扱ってください。常時稼働し、到達可能で、Gateway と有効化するチャネルに十分な RAM が必要です。 基本的な目安: - - **絶対的な最小要件:** 1 vCPU、1GB RAM。 + - **絶対最小:** 1 vCPU、1GB RAM。 - **推奨:** 複数チャネル、ブラウザー自動化、またはメディアツールを実行するなら 2GB RAM 以上。 - - **OS:** Ubuntu LTS または最近の Debian/Ubuntu。 + - **OS:** Ubuntu LTS または他の最新の Debian/Ubuntu。 - Windows の場合、**WSL2 が最も簡単な VM スタイルのセットアップ** であり、ツール互換性も最も高いです。[Windows](/ja-JP/platforms/windows), [VPS hosting](/ja-JP/vps) を参照してください。 - VM で macOS を実行する場合は、[macOS VM](/ja-JP/install/macos-vm) を参照してください。 + Windows の場合、**WSL2 が最も簡単なVM風セットアップ** で、ツール互換性も最も高いです。[Windows](/ja-JP/platforms/windows), [VPS hosting](/ja-JP/vps) を参照してください。 + macOS を VM 上で実行している場合は、[macOS VM](/ja-JP/install/macos-vm) を参照してください。 @@ -895,84 +913,84 @@ x-i18n: ## OpenClaw とは？ - - OpenClaw は、自分のデバイス上で実行するパーソナル AI アシスタントです。すでに使っているメッセージング画面（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat、および QQ Bot のようなバンドル済み channel plugins）で応答でき、対応プラットフォームでは音声 + ライブ Canvas も利用できます。**Gateway** は常時稼働のコントロールプレーンであり、アシスタントが製品そのものです。 + + OpenClaw は、あなた自身のデバイス上で実行する個人用AIアシスタントです。すでに使っているメッセージング画面（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat、および QQ Bot のようなバンドル済みchannel plugins）で応答し、サポート対象プラットフォームでは音声 + ライブ Canvas も利用できます。**Gateway** は常時稼働のコントロールプレーンであり、アシスタントこそが製品です。 - OpenClaw は「単なる Claude ラッパー」ではありません。これは、**自分のハードウェア** 上で - 高機能なアシスタントを動かし、すでに使っているチャットアプリからアクセスでき、状態を持つ - セッション、メモリ、ツールを備えつつ、ワークフローの制御をホスト型 - SaaS に委ねなくて済む **ローカルファーストのコントロールプレーン** です。 + OpenClaw は「ただのClaudeラッパー」ではありません。**ローカルファーストのコントロールプレーン** であり、 + すでに使っているチャットアプリからアクセスできる高機能なアシスタントを、**自分のハードウェア上で** 実行でき、 + 状態を持つセッション、メモリ、ツールを備えながら、ワークフローの主導権をホスト型 + SaaS に渡さずに済みます。 - 主な特徴: + 特長: - - **あなたのデバイス、あなたのデータ:** Gateway を好きな場所（Mac、Linux、VPS）で動かし、 - workspace + session history をローカルに保持できます。 - - **Web サンドボックスではなく実際のチャネル:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage など、 - 加えて対応プラットフォームではモバイル音声と Canvas。 + - **あなたのデバイス、あなたのデータ:** Gateway を好きな場所（Mac、Linux、VPS）で実行でき、 + workspace + セッション履歴をローカルに保持できます。 + - **Webサンドボックスではなく実際のチャネル:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage など、 + 加えてサポート対象プラットフォームではモバイル音声と Canvas。 - **モデル非依存:** Anthropic、OpenAI、MiniMax、OpenRouter などを、エージェントごとのルーティング - とフェイルオーバー付きで利用できます。 - - **ローカル専用オプション:** ローカルモデルを実行して、必要なら **すべてのデータをデバイス上に保持** できます。 - - **マルチエージェントルーティング:** チャネル、アカウント、またはタスクごとに個別の - エージェントを分け、それぞれ独自の workspace とデフォルト設定を持てます。 - - **オープンソースでハック可能:** ベンダーロックインなしで、調査、拡張、セルフホストができます。 + とフェイルオーバー付きで使用できます。 + - **ローカル専用オプション:** **すべてのデータをデバイス上に保持したまま** ローカルモデルを実行できます。 + - **multi-agent routing:** チャネル、アカウント、またはタスクごとにエージェントを分けられ、それぞれが独自の + workspace とデフォルトを持ちます。 + - **オープンソースでハック可能:** ベンダーロックインなしで確認、拡張、セルフホストできます。 ドキュメント: [Gateway](/ja-JP/gateway), [Channels](/ja-JP/channels), [Multi-agent](/ja-JP/concepts/multi-agent), [Memory](/ja-JP/concepts/memory)。 - - 最初のプロジェクトとしておすすめなのは: + + 最初のプロジェクトとしておすすめなのは次のようなものです: - - Web サイトを作る（WordPress、Shopify、またはシンプルな静的サイト）。 - - モバイルアプリを試作する（概要、画面、API 計画）。 + - Webサイトを作る（WordPress、Shopify、またはシンプルな静的サイト）。 + - モバイルアプリを試作する（概要、画面、API計画）。 - ファイルとフォルダーを整理する（クリーンアップ、命名、タグ付け）。 - - Gmail を接続して要約やフォローアップを自動化する。 + - Gmail を接続して、要約やフォローアップを自動化する。 - 大きなタスクにも対応できますが、フェーズに分けて - サブエージェントで並列作業すると最もうまく機能します。 + 大きなタスクも扱えますが、フェーズに分割して + sub agents を使って並列に進めると最も効果的です。 - - 日常で効果を感じやすい使い方は、たいてい次のようなものです。 + + 日常的に効果が出やすい使い方は、たとえば次のようなものです: - - **個人向けブリーフィング:** 受信箱、カレンダー、気になるニュースの要約。 - - **調査と下書き作成:** すばやい調査、要約、メールや文書の初稿作成。 + - **パーソナルブリーフィング:** 受信箱、カレンダー、気になるニュースの要約。 + - **調査と下書き:** 素早い調査、要約、メールやドキュメントの初稿作成。 - **リマインダーとフォローアップ:** Cron や Heartbeat による通知やチェックリスト。 - - **ブラウザー自動化:** フォーム入力、データ収集、Web タスクの繰り返し。 - - **デバイス横断の連携:** スマートフォンからタスクを送り、Gateway にサーバー上で実行させ、結果をチャットで受け取る。 + - **ブラウザー自動化:** フォーム入力、データ収集、Webタスクの繰り返し実行。 + - **デバイス間連携:** スマートフォンからタスクを送り、Gateway にサーバー上で実行させ、結果をチャットで受け取る。 - - **調査、選別、下書き作成** には役立ちます。サイトをスキャンし、ショートリストを作り、 - 見込み客を要約し、アウトリーチ文面や広告コピーの下書きを書けます。 + + **調査、選別、下書き** には有効です。サイトを巡回し、候補リストを作成し、 + 見込み客を要約し、営業文面や広告コピーの下書きを作成できます。 - **アウトリーチや広告配信** については、人を必ず関与させてください。スパムを避け、現地の法律や - プラットフォームポリシーに従い、送信前に必ず内容を確認してください。最も安全なパターンは、 - OpenClaw に下書きさせてあなたが承認することです。 + **営業活動や広告配信** については、人間を必ず関与させてください。スパムを避け、各地の法律や + プラットフォームポリシーに従い、送信前に必ず確認してください。最も安全なパターンは、 + OpenClaw に下書きさせて、あなたが承認することです。 ドキュメント: [Security](/ja-JP/gateway/security)。 - OpenClaw は IDE の置き換えではなく、**パーソナルアシスタント** および連携レイヤーです。リポジトリ内で - 最速の直接コーディングループが必要なら Claude Code や Codex を使ってください。永続的なメモリ、 - デバイス横断アクセス、ツールオーケストレーションが欲しいなら OpenClaw を使ってください。 + OpenClaw は **個人アシスタント** 兼オーケストレーション層であり、IDE の代替ではありません。リポジトリ内で最速の直接コーディングループが欲しいなら + Claude Code または Codex を使ってください。耐久性のあるメモリ、デバイス横断アクセス、ツールオーケストレーションが + 欲しいときは OpenClaw を使ってください。 利点: - - セッションをまたいだ **永続的なメモリ + workspace** + - セッションをまたいだ **永続メモリ + workspace** - **マルチプラットフォームアクセス**（WhatsApp、Telegram、TUI、WebChat） - **ツールオーケストレーション**（browser、files、scheduling、hooks） - - **常時稼働 Gateway**（VPS 上で動かし、どこからでも操作可能） + - **常時稼働の Gateway**（VPS 上で動かし、どこからでも操作可能） - ローカル browser/screen/camera/exec 用の **Nodes** - 紹介ページ: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) + 紹介: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -981,68 +999,68 @@ x-i18n: - リポジトリ内のコピーを直接編集するのではなく、管理された override を使ってください。変更内容は `~/.openclaw/skills//SKILL.md` に置くか、`~/.openclaw/openclaw.json` の `skills.load.extraDirs` でフォルダーを追加します。優先順位は `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs` なので、git に触れなくても管理 override が bundled Skills より優先されます。Skills をグローバルにインストールしつつ一部のエージェントにだけ見せたい場合は、共有コピーを `~/.openclaw/skills` に置き、`agents.defaults.skills` と `agents.list[].skills` で表示範囲を制御してください。上流に入れる価値のある変更だけをリポジトリに入れ、PR として送ってください。 + リポジトリ内のコピーを編集する代わりに、管理されたオーバーライドを使ってください。変更は `~/.openclaw/skills//SKILL.md` に置くか、`~/.openclaw/openclaw.json` の `skills.load.extraDirs` でフォルダーを追加します。優先順位は `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → バンドル済み → `skills.load.extraDirs` なので、管理されたオーバーライドは git に触れずにバンドル済み Skills より優先されます。Skill をグローバルにインストールしつつ、一部のエージェントにだけ見せたい場合は、共有コピーを `~/.openclaw/skills` に置き、`agents.defaults.skills` と `agents.list[].skills` で可視性を制御してください。上流に送る価値のある変更だけをリポジトリに置き、PR として送ってください。 - はい。`~/.openclaw/openclaw.json` の `skills.load.extraDirs` で追加ディレクトリを指定できます（最も低い優先順位）。デフォルトの優先順位は `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs` です。`clawhub` はデフォルトで `./skills` にインストールし、OpenClaw は次のセッションでこれを `/skills` として扱います。Skills を特定のエージェントにだけ見せたい場合は、`agents.defaults.skills` または `agents.list[].skills` と組み合わせてください。 + はい。`~/.openclaw/openclaw.json` の `skills.load.extraDirs` で追加ディレクトリを指定できます（最も低い優先順位）。デフォルトの優先順位は `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → バンドル済み → `skills.load.extraDirs` です。`clawhub` はデフォルトで `./skills` にインストールされ、OpenClaw は次のセッションでこれを `/skills` として扱います。Skill を特定のエージェントにだけ表示したい場合は、`agents.defaults.skills` または `agents.list[].skills` と組み合わせてください。 - 現在サポートされているパターンは次のとおりです。 + 現在サポートされているパターンは次のとおりです: - - **Cron jobs**: 分離されたジョブごとに `model` override を設定できます。 - - **サブエージェント**: 異なるデフォルトモデルを持つ別エージェントにタスクをルーティングします。 + - **Cron jobs**: 分離されたジョブごとに `model` オーバーライドを設定できます。 + - **Sub-agents**: 異なるデフォルトモデルを持つ別エージェントにタスクを振り分けます。 - **オンデマンド切り替え**: `/model` を使って現在のセッションモデルをいつでも切り替えます。 [Cron jobs](/ja-JP/automation/cron-jobs)、[Multi-Agent Routing](/ja-JP/concepts/multi-agent)、[Slash commands](/ja-JP/tools/slash-commands) を参照してください。 - - 長時間または並列のタスクには **サブエージェント** を使ってください。サブエージェントは独自のセッションで動作し、 + + 長時間または並列のタスクには **sub-agents** を使ってください。sub-agents は独自のセッションで実行され、 要約を返し、メインチャットの応答性を保ちます。 - ボットに「このタスク用にサブエージェントを起動して」と頼むか、`/subagents` を使ってください。 - チャット内で `/status` を使うと、Gateway が今何をしているか（そしてビジーかどうか）を確認できます。 + bot に「このタスク用にsub-agentを起動して」と依頼するか、`/subagents` を使ってください。 + チャット内で `/status` を使うと、Gateway が今何をしているか（そして忙しいかどうか）を確認できます。 - トークンのヒント: 長時間タスクもサブエージェントもトークンを消費します。コストが気になる場合は、 - `agents.defaults.subagents.model` でサブエージェント用により安価なモデルを設定してください。 + トークンのヒント: 長いタスクも sub-agents もどちらもトークンを消費します。コストが気になる場合は、 + `agents.defaults.subagents.model` で sub-agents 用により安価なモデルを設定してください。 ドキュメント: [Sub-agents](/ja-JP/tools/subagents), [Background Tasks](/ja-JP/automation/tasks)。 - - スレッドバインディングを使います。Discord スレッドをサブエージェントまたはセッションターゲットにバインドすると、そのスレッド内の後続メッセージは、そのバインドされたセッション上で継続されます。 + + thread bindings を使います。Discord thread を subagent または session target にバインドできるため、そのthread内の後続メッセージはそのバインドされたsession上に留まります。 基本フロー: - - `sessions_spawn` を `thread: true` 付きで実行して起動します（永続的なフォローアップには任意で `mode: "session"` も指定）。 - - または `/focus ` で手動バインドします。 - - `/agents` でバインディング状態を確認します。 - - `/session idle ` と `/session max-age ` で自動 unfocus を制御します。 - - `/unfocus` でスレッドを切り離します。 + - `sessions_spawn` を `thread: true`（必要に応じて永続的なフォローアップ用に `mode: "session"` も）付きで実行して起動する。 + - または `/focus ` で手動バインドする。 + - `/agents` を使って binding の状態を確認する。 + - `/session idle ` と `/session max-age ` を使って自動unfocusを制御する。 + - `/unfocus` を使って thread を切り離す。 必要な設定: - グローバルデフォルト: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`。 - - Discord override: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`。 - - 起動時に自動バインド: `channels.discord.threadBindings.spawnSubagentSessions: true` を設定します。 + - Discord オーバーライド: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`。 + - spawn 時の自動バインド: `channels.discord.threadBindings.spawnSubagentSessions: true` を設定する。 ドキュメント: [Sub-agents](/ja-JP/tools/subagents), [Discord](/ja-JP/channels/discord), [Configuration Reference](/ja-JP/gateway/configuration-reference), [Slash commands](/ja-JP/tools/slash-commands)。 - - まず解決済みの requester route を確認してください。 + + まず解決済みの requester route を確認してください: - - 完了モードのサブエージェント配信では、バインドされたスレッドまたは会話ルートが存在する場合、それが優先されます。 - - 完了元がチャネル情報しか持っていない場合、OpenClaw は requester セッションに保存されたルート（`lastChannel` / `lastTo` / `lastAccountId`）にフォールバックするため、ダイレクト配信が引き続き成功することがあります。 - - バインド済みルートも使用可能な保存ルートも存在しない場合、ダイレクト配信は失敗する可能性があり、その結果はチャットに即時投稿される代わりに、キューされたセッション配信へフォールバックします。 - - 無効または古いターゲットでは、引き続きキューフォールバックや最終配信失敗が発生することがあります。 - - 子の最後に見える assistant 応答が正確に無音トークン `NO_REPLY` / `no_reply`、または正確に `ANNOUNCE_SKIP` である場合、OpenClaw は古い進捗を投稿しないよう、通知を意図的に抑制します。 - - 子がツール呼び出しだけの状態でタイムアウトした場合、通知では生のツール出力を再表示する代わりに、それを短い部分進捗サマリーにまとめることがあります。 + - 完了モードのsubagent配信では、バインドされたthreadまたはconversation routeが存在する場合、それが優先されます。 + - 完了元がchannelしか持っていない場合、OpenClawは requester session に保存された route（`lastChannel` / `lastTo` / `lastAccountId`）にフォールバックするため、直接配信が引き続き成功する可能性があります。 + - バインドされたrouteも使用可能な保存済みrouteも存在しない場合、直接配信は失敗し得て、結果はチャットへ即時投稿される代わりに queued session delivery にフォールバックします。 + - 無効または古いtargetは、依然として queue fallback や最終配信失敗の原因になることがあります。 + - 子の最後に可視だったassistant replyが、正確にサイレントトークン `NO_REPLY` / `no_reply`、または正確に `ANNOUNCE_SKIP` だった場合、OpenClawは古い進捗を投稿しないように意図的に通知を抑制します。 + - 子がツール呼び出しだけでタイムアウトした場合、通知では生のツール出力をそのまま再生せず、短い部分進捗サマリーにまとめられることがあります。 デバッグ: @@ -1055,14 +1073,14 @@ x-i18n: - Cron は Gateway プロセス内で実行されます。Gateway が継続的に実行されていない場合、 + Cron は Gateway process の内部で実行されます。Gateway が継続的に動作していない場合、 スケジュールされたジョブは実行されません。 チェックリスト: - - cron が有効（`cron.enabled`）で、`OPENCLAW_SKIP_CRON` が設定されていないことを確認してください。 - - Gateway が 24 時間 365 日稼働していることを確認してください（スリープ/再起動なし）。 - - ジョブのタイムゾーン設定（`--tz` とホストのタイムゾーン）を確認してください。 + - cron が有効であること（`cron.enabled`）と、`OPENCLAW_SKIP_CRON` が設定されていないことを確認する。 + - Gateway が24時間365日動作していることを確認する（スリープ/再起動なし）。 + - ジョブのタイムゾーン設定（`--tz` とホストのタイムゾーン）を確認する。 デバッグ: @@ -1075,18 +1093,18 @@ x-i18n: - - まず配信モードを確認してください。 + + まず配信モードを確認してください: - - `--no-deliver` / `delivery.mode: "none"` は、外部メッセージが送られないことを意味します。 - - 通知ターゲット（`channel` / `to`）が欠落している、または無効な場合、runner は外部配信をスキップします。 - - チャネル認証の失敗（`unauthorized`、`Forbidden`）は、runner が配信を試みたが資格情報によってブロックされたことを意味します。 - - 無音の isolated 結果（`NO_REPLY` / `no_reply` のみ）は、意図的に配信不可として扱われるため、runner はキューフォールバック配信も抑制します。 + - `--no-deliver` / `delivery.mode: "none"` は、外部メッセージが送信されないことを意味します。 + - announce target（`channel` / `to`）が欠落しているか無効な場合、runner は送信配信をスキップします。 + - チャネル認証失敗（`unauthorized`, `Forbidden`）は、runner が配信を試みたものの認証情報によってブロックされたことを意味します。 + - サイレントな isolated result（`NO_REPLY` / `no_reply` のみ）は意図的に配信不可として扱われるため、runner は queued fallback delivery も抑制します。 - isolated cron jobs では、runner が最終配信を担当します。agent は - runner が送信するためのプレーンテキストの要約を返すことが期待されています。`--no-deliver` は - その結果を内部に留めるものであり、代わりに agent が - message tool で直接送信できるようにするものではありません。 + isolated cron jobs では、最終配信は runner が担います。agent は + runner が送信できるプレーンテキストの要約を返すことが期待されます。`--no-deliver` は + その結果を内部のまま保持します。message tool を使ってagentが直接送る + ことを許可するものではありません。 デバッグ: @@ -1099,23 +1117,23 @@ x-i18n: - - これは通常、重複スケジューリングではなく、ライブのモデル切り替え経路です。 + + それは通常、重複スケジューリングではなく live model-switch path です。 - isolated cron は、アクティブな実行が `LiveSessionModelSwitchError` を投げたときに、 - ランタイムのモデル引き継ぎを永続化して再試行できます。再試行では切り替えられた + isolated cron では、アクティブな実行が `LiveSessionModelSwitchError` を投げたときに、 + ランタイムのモデル引き継ぎを永続化してリトライできます。リトライでは切り替え後の provider/model が維持され、その切り替えに新しい auth profile override が含まれていた場合は、 - cron は再試行前にそれも永続化します。 + cron はそれも永続化してからリトライします。 関連する選択ルール: - - 該当する場合、まず Gmail hook model override が優先されます。 + - 該当する場合は、Gmail hook のモデルoverrideが最優先。 - 次にジョブごとの `model`。 - - 次に保存済みの cron-session model override。 - - その後で通常の agent/default model selection。 + - 次に保存済みの cron-session モデルoverride。 + - その後に通常の agent/default モデル選択。 - 再試行ループには上限があります。初回試行 + 2 回の切り替え再試行の後は、 - cron は無限ループせず中止します。 + リトライループには上限があります。初回試行に加えて2回のswitch retryの後、 + cron は無限ループせずに中止します。 デバッグ: @@ -1129,8 +1147,8 @@ x-i18n: - ネイティブの `openclaw skills` コマンドを使うか、Skills を workspace に配置してください。macOS の Skills UI は Linux では利用できません。 - Skills は [https://clawhub.ai](https://clawhub.ai) で探せます。 + ネイティブの `openclaw skills` コマンドを使うか、skills をworkspaceに配置してください。macOS の Skills UI は Linux では利用できません。 + Skills は [https://clawhub.ai](https://clawhub.ai) で参照できます。 ```bash openclaw skills search "calendar" @@ -1143,20 +1161,20 @@ x-i18n: openclaw skills check ``` - ネイティブの `openclaw skills install` は、アクティブな workspace の `skills/` - ディレクトリに書き込みます。別個の `clawhub` CLI は、自分の Skills を公開または - 同期したい場合にのみインストールしてください。エージェント間で共有インストールしたい場合は、Skills を - `~/.openclaw/skills` 配下に置き、どのエージェントに見せるかを絞りたい場合は - `agents.defaults.skills` または `agents.list[].skills` を使ってください。 + ネイティブの `openclaw skills install` は、アクティブなworkspaceの `skills/` + ディレクトリに書き込みます。別個の `clawhub` CLI のインストールが必要なのは、 + 自分のskillsを公開または同期したい場合だけです。エージェント間で共有するインストールには、skill を + `~/.openclaw/skills` 配下に置き、表示できるエージェントを限定したい場合は `agents.defaults.skills` または + `agents.list[].skills` を使用してください。 - - はい。Gateway scheduler を使ってください。 + + はい。Gateway scheduler を使用してください: - - **Cron jobs**: スケジュール実行または繰り返しタスク用（再起動後も保持されます）。 - - **Heartbeat**: 「メインセッション」の定期チェック用。 - - **Isolated jobs**: 要約を投稿したりチャットに配信したりする自律エージェント用。 + - スケジュールまたは繰り返しタスクには **Cron jobs**（再起動後も維持される）。 + - 「main session」の定期チェックには **Heartbeat**。 + - 要約を投稿したりチャットに配信したりする自律エージェントには **Isolated jobs**。 ドキュメント: [Cron jobs](/ja-JP/automation/cron-jobs), [Automation & Tasks](/ja-JP/automation), [Heartbeat](/ja-JP/gateway/heartbeat). @@ -1164,18 +1182,18 @@ x-i18n: - 直接にはできません。macOS Skills は `metadata.openclaw.os` と必要なバイナリによって制御され、Skills は **Gateway host** 上で適格な場合にのみ system prompt に表示されます。Linux では、`darwin` 専用の Skills（`apple-notes`、`apple-reminders`、`things-mac` など）は、その制御を上書きしない限りロードされません。 + 直接はできません。macOS skills は `metadata.openclaw.os` と必要なバイナリによって制御され、skills は **Gateway host** 上で利用可能な場合にのみ system prompt に表示されます。Linux では、`darwin` 専用のskills（`apple-notes`、`apple-reminders`、`things-mac` など）は、その制御を上書きしない限り読み込まれません。 - サポートされるパターンは 3 つあります。 + サポートされているパターンは3つあります: - **オプション A - Gateway を Mac 上で実行する（最も簡単）。** - macOS のバイナリが存在する場所で Gateway を実行し、その後 [remote mode](#gateway-ports-already-running-and-remote-mode) または Tailscale 経由で Linux から接続します。Gateway host が macOS なので、Skills は通常どおりロードされます。 + **Option A - Gateway を Mac で実行する（最も簡単）。** + macOS バイナリが存在する場所で Gateway を実行し、その後 Linux から [remote mode](#gateway-ports-already-running-and-remote-mode) または Tailscale 経由で接続します。Gateway host が macOS のため、skills は通常どおり読み込まれます。 - **オプション B - macOS Node を使う（SSH なし）。** - Gateway を Linux 上で実行し、macOS Node（メニューバーアプリ）をペアリングして、Mac 上の **Node Run Commands** を「Always Ask」または「Always Allow」に設定します。必要なバイナリが Node 上に存在する場合、OpenClaw は macOS 専用 Skills を適格として扱えます。agent はそれらの Skills を `nodes` tool 経由で実行します。「Always Ask」を選んだ場合、プロンプトで「Always Allow」を承認すると、そのコマンドが allowlist に追加されます。 + **Option B - macOS node を使う（SSH なし）。** + Gateway は Linux で実行し、macOS node（メニューバーアプリ）をペアリングして、Mac 側で **Node Run Commands** を 「Always Ask」 または 「Always Allow」 に設定します。必要なバイナリが node 上に存在する場合、OpenClaw は macOS 専用 skills を利用可能として扱えます。agent は `nodes` tool を通じてそれらのskillsを実行します。「Always Ask」を選んだ場合、プロンプトで 「Always Allow」 を承認すると、そのコマンドが allowlist に追加されます。 - **オプション C - SSH 経由で macOS バイナリをプロキシする（上級者向け）。** - Gateway は Linux 上のままにしつつ、必要な CLI バイナリが Mac 上で実行される SSH ラッパーに解決されるようにします。その後、Skill を上書きして Linux を許可し、適格なままにします。 + **Option C - macOS バイナリを SSH 経由でプロキシする（上級者向け）。** + Gateway は Linux 上に置いたまま、必要な CLI バイナリを Mac 上で実行する SSH ラッパーで解決されるようにします。その後、skill を上書きして Linux を許可すれば、利用可能なままにできます。 1. バイナリ用の SSH ラッパーを作成します（例: Apple Notes 用の `memo`）: @@ -1185,18 +1203,18 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. ラッパーを Linux ホストの `PATH` 上に置きます（例 `~/bin/memo`）。 - 3. Skill metadata を上書きして Linux を許可します（workspace または `~/.openclaw/skills`）: + 2. そのラッパーを Linux host の `PATH` 上に配置します（例: `~/bin/memo`）。 + 3. skill metadata を上書きして Linux を許可します（workspace または `~/.openclaw/skills`）: ```markdown --- name: apple-notes - description: memo CLI を介して macOS 上の Apple Notes を管理します。 + description: macOS 上の memo CLI を通じて Apple Notes を管理します。 metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` - 4. Skills snapshot が更新されるように、新しいセッションを開始します。 + 4. 新しいsessionを開始して、skills snapshot を更新します。 @@ -1205,50 +1223,50 @@ x-i18n: 選択肢: - - **カスタム Skill / Plugin:** 信頼性の高い API アクセスに最適です（Notion/HeyGen はどちらも API を持っています）。 - - **ブラウザー自動化:** コード不要で動きますが、遅くて壊れやすくなります。 + - **カスタムskill / Plugin:** 信頼性の高いAPIアクセスに最適です（Notion/HeyGen はどちらもAPIがあります）。 + - **ブラウザー自動化:** コードなしで使えますが、より遅く壊れやすいです。 - クライアントごとにコンテキストを維持したい場合（代理店ワークフローなど）のシンプルなパターンは次のとおりです。 + クライアントごとにコンテキストを維持したい場合（代理店ワークフローなど）は、シンプルなパターンとして次があります: - - クライアントごとに 1 つの Notion ページ（コンテキスト + 設定 + 進行中の作業）。 - - セッション開始時にそのページを取得するよう agent に指示します。 + - クライアントごとに1つのNotionページ（コンテキスト + 設定 + 進行中の作業）。 + - セッション開始時にそのページを取得するようagentに指示する。 - ネイティブ連携が欲しい場合は、機能リクエストを作成するか、それらの API を対象とした Skill - を作成してください。 + ネイティブ統合が欲しい場合は、機能要望を作成するか、それらのAPIを対象にしたskillを + 作成してください。 - Skills をインストール: + Skills のインストール: ```bash openclaw skills install openclaw skills update --all ``` - ネイティブインストール先はアクティブな workspace の `skills/` ディレクトリです。エージェント間で共有する Skills は `~/.openclaw/skills//SKILL.md` に配置してください。共有インストールを一部のエージェントにだけ見せたい場合は、`agents.defaults.skills` または `agents.list[].skills` を設定します。一部の Skills では Homebrew 経由でインストールされたバイナリが必要であり、Linux では Linuxbrew を意味します（上の Homebrew Linux FAQ 項目を参照）。[Skills](/ja-JP/tools/skills), [Skills config](/ja-JP/tools/skills-config), [ClawHub](/ja-JP/tools/clawhub) を参照してください。 + ネイティブインストールはアクティブなworkspaceの `skills/` ディレクトリに配置されます。エージェント間で共有するSkillsは、`~/.openclaw/skills//SKILL.md` に配置してください。共有インストールを一部のエージェントにだけ見せたい場合は、`agents.defaults.skills` または `agents.list[].skills` を設定してください。一部のskillsは Homebrew でインストールされたバイナリを前提としています。Linux ではこれは Linuxbrew を意味します（上記の Homebrew Linux FAQ 項目を参照）。[Skills](/ja-JP/tools/skills), [Skills config](/ja-JP/tools/skills-config), [ClawHub](/ja-JP/tools/clawhub) を参照してください。 - Chrome DevTools MCP 経由で接続する組み込みの `user` browser profile を使ってください。 + 組み込みの `user` browser profile を使ってください。これは Chrome DevTools MCP 経由で接続します: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - カスタム名を使いたい場合は、明示的な MCP profile を作成します。 + カスタム名を使いたい場合は、明示的な MCP profile を作成してください: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - この経路はホストローカルです。Gateway が別の場所で動作している場合は、browser マシン上で Node host を動かすか、代わりにリモート CDP を使ってください。 + この経路では、ローカルホストのbrowserまたは接続されたbrowser node を使用できます。Gateway が別の場所で動作している場合は、browser マシン上で node host を実行するか、代わりに remote CDP を使用してください。 `existing-session` / `user` の現在の制限: - - アクションは CSS selector ベースではなく ref ベースです - - アップロードには `ref` / `inputRef` が必要で、現在は 1 回に 1 ファイルのみサポートします - - `responsebody`、PDF エクスポート、ダウンロードのインターセプト、バッチアクションは、引き続き managed browser または生の CDP profile が必要です + - actions は CSS selector ベースではなく ref ベース + - アップロードには `ref` / `inputRef` が必要で、現在は一度に1ファイルのみ対応 + - `responsebody`、PDF export、download interception、batch actions には、引き続き managed browser または raw CDP profile が必要 @@ -1257,27 +1275,27 @@ x-i18n: - はい。[Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。Docker 固有のセットアップ（Docker 上での完全な gateway、または sandbox イメージ）については、[Docker](/ja-JP/install/docker) を参照してください。 + はい。[Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。Docker 固有のセットアップ（Docker での完全な gateway または sandbox image）については、[Docker](/ja-JP/install/docker) を参照してください。 - - デフォルトイメージはセキュリティ優先で `node` ユーザーとして実行されるため、 - system packages、Homebrew、バンドル済みブラウザーは含まれていません。より完全なセットアップにするには: + + デフォルトイメージはセキュリティ優先で、`node` ユーザーとして実行されるため、 + system packages、Homebrew、バンドル済みbrowser は含まれていません。より完全なセットアップにするには: - - キャッシュが維持されるように `/home/node` を `OPENCLAW_HOME_VOLUME` で永続化します。 - - `OPENCLAW_DOCKER_APT_PACKAGES` で system deps をイメージに組み込みます。 - - バンドル済み CLI で Playwright ブラウザーをインストールします: + - `/home/node` を `OPENCLAW_HOME_VOLUME` で永続化し、キャッシュを保持する。 + - `OPENCLAW_DOCKER_APT_PACKAGES` で system deps をイメージに焼き込む。 + - バンドル済みCLI経由で Playwright browsers をインストールする: `node /app/node_modules/playwright-core/cli.js install chromium` - - `PLAYWRIGHT_BROWSERS_PATH` を設定し、そのパスが永続化されるようにします。 + - `PLAYWRIGHT_BROWSERS_PATH` を設定し、そのパスが永続化されるようにする。 ドキュメント: [Docker](/ja-JP/install/docker), [Browser](/ja-JP/tools/browser). - - はい。プライベートな通信が **DM** で、公開の通信が **グループ** である場合に可能です。 + + はい。プライベートトラフィックが **DM** で、公開トラフィックが **groups** である場合に可能です。 - `agents.defaults.sandbox.mode: "non-main"` を使うと、グループ/チャネルセッション（non-main keys）は Docker 内で実行され、メインの DM セッションはホスト上に残ります。その後、サンドボックス化されたセッションで利用可能なツールを `tools.sandbox.tools` で制限してください。 + `agents.defaults.sandbox.mode: "non-main"` を使うと、group/channel sessions（non-main keys）は Docker 内で実行され、main DM session はホスト上のままになります。その後、`tools.sandbox.tools` を使ってサンドボックス化されたsessionsで利用可能なツールを制限してください。 セットアップ手順 + 設定例: [Groups: personal DMs + public groups](/ja-JP/channels/groups#pattern-personal-dms-public-groups-single-agent) @@ -1285,69 +1303,69 @@ x-i18n: - - `agents.defaults.sandbox.docker.binds` を `["host:path:mode"]` に設定してください（例: `"/home/user/src:/src:ro"`）。グローバル + エージェント単位の bind はマージされます。`scope: "shared"` の場合、エージェント単位の bind は無視されます。機密性の高いものには `:ro` を使い、bind はサンドボックスのファイルシステム境界を迂回することを忘れないでください。 + + `agents.defaults.sandbox.docker.binds` を `["host:path:mode"]` に設定してください（例: `"/home/user/src:/src:ro"`）。グローバルとエージェントごとの binds はマージされます。`scope: "shared"` の場合、エージェントごとの binds は無視されます。機密性の高いものには `:ro` を使い、bind はサンドボックスのファイルシステム境界を迂回することを忘れないでください。 - OpenClaw は、正規化されたパスと、最も深い既存の祖先を通じて解決された canonical path の両方に対して bind source を検証します。つまり、最後のパスセグメントがまだ存在しない場合でも symlink-parent escape は安全側で失敗し、許可されたルートのチェックも symlink 解決後に引き続き適用されます。 + OpenClaw は bind source を、正規化されたパスと、最も深い既存の祖先を通じて解決された canonical path の両方に対して検証します。つまり、最後のパスセグメントがまだ存在しない場合でも、symlink 親を使ったエスケープは fail closed になり、許可されたルートのチェックも symlink 解決後に引き続き適用されます。 - 例と安全上の注意については [Sandboxing](/ja-JP/gateway/sandboxing#custom-bind-mounts) と [Sandbox vs Tool Policy vs Elevated](/ja-JP/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) を参照してください。 + 例と安全上の注意については、[Sandboxing](/ja-JP/gateway/sandboxing#custom-bind-mounts) と [Sandbox vs Tool Policy vs Elevated](/ja-JP/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) を参照してください。 - OpenClaw のメモリは、agent workspace 内の Markdown ファイルにすぎません。 + OpenClaw のメモリは、agent workspace 内の単なる Markdown ファイルです: - - `memory/YYYY-MM-DD.md` の日次ノート - - `MEMORY.md` の整理された長期ノート（main/private sessions のみ） + - `memory/YYYY-MM-DD.md` に日次ノート + - `MEMORY.md` に厳選された長期ノート（main/private sessions のみ） - OpenClaw はまた、**無音の pre-Compaction メモリフラッシュ** を実行し、 - auto-Compaction の前に永続的なノートを書き込むようモデルに促します。これは workspace が - 書き込み可能な場合にのみ実行されます（読み取り専用サンドボックスではスキップされます）。[Memory](/ja-JP/concepts/memory) を参照してください。 + OpenClaw はまた、モデルに対して自動 Compaction 前に永続的なノートを書き込むよう促す + **サイレントな pre-compaction memory flush** も実行します。これは workspace が + 書き込み可能な場合にのみ動作します（読み取り専用サンドボックスではスキップされます）。[Memory](/ja-JP/concepts/memory) を参照してください。 - - ボットに **その事実をメモリに書く** よう依頼してください。長期ノートは `MEMORY.md` に、 + + bot に **その事実をメモリに書き込む** よう依頼してください。長期ノートは `MEMORY.md` に、 短期コンテキストは `memory/YYYY-MM-DD.md` に入ります。 - これはまだ改善を進めている領域です。モデルにメモリを保存するよう促すと効果があります。 - モデルは何をすべきか理解しています。それでも忘れ続ける場合は、Gateway が毎回同じ + これはまだ改善中の領域です。モデルにメモリを保存するよう促すと効果があります。 + そうすれば何をすべきか理解できます。それでも忘れ続ける場合は、Gateway が毎回同じ workspace を使っていることを確認してください。 ドキュメント: [Memory](/ja-JP/concepts/memory), [Agent workspace](/ja-JP/concepts/agent-workspace). - - メモリファイルはディスク上に保存され、削除するまで保持されます。制限は - モデルではなくストレージです。ただし **session context** は依然としてモデルの - context window に制限されるため、長い会話では Compaction や切り詰めが起こることがあります。だからこそ - memory search が存在します。関連する部分だけを再びコンテキストに戻します。 + + メモリファイルはディスク上に保存され、削除するまで残ります。制限はモデルではなく + ストレージです。ただし **session context** は依然としてモデルの + context window に制限されるため、長い会話では Compaction や切り詰めが発生することがあります。そのため + memory search が存在します。関連部分だけをコンテキストに戻します。 ドキュメント: [Memory](/ja-JP/concepts/memory), [Context](/ja-JP/concepts/context). - - **OpenAI embeddings** を使う場合にのみ必要です。Codex OAuth は chat/completions を対象としており、 - embeddings へのアクセスは **付与しません**。そのため、**Codex でサインインしても（OAuth または - Codex CLI login でも）** セマンティックメモリ検索の助けにはなりません。OpenAI embeddings には - 引き続き実際の API key（`OPENAI_API_KEY` または `models.providers.openai.apiKey`）が必要です。 + + **OpenAI embeddings** を使う場合に限ります。Codex OAuth は chat/completions を対象としており、 + embeddings へのアクセスは付与しません。そのため **Codex でサインインしても（OAuth でも + Codex CLI login でも）** セマンティックな memory search には役立ちません。OpenAI embeddings には + 引き続き実際の APIキー（`OPENAI_API_KEY` または `models.providers.openai.apiKey`）が必要です。 - provider を明示的に設定しない場合、OpenClaw は API key を解決できたときに - 自動的に provider を選択します（auth profiles、`models.providers.*.apiKey`、または env vars）。 - OpenAI key が解決できれば OpenAI を優先し、そうでなければ Gemini、次に - Voyage、次に Mistral を優先します。利用可能なリモートキーがない場合、 - memory search は設定するまで無効のままです。ローカルモデルのパスが + provider を明示的に設定しない場合、OpenClaw は APIキーを解決できたときに + 自動で provider を選択します（auth profiles、`models.providers.*.apiKey`、または env vars）。 + OpenAI キーが解決できれば OpenAI を優先し、それ以外では Gemini キーが + 解決できれば Gemini、次に Voyage、次に Mistral を選びます。リモートキーが利用できない場合、 + 設定するまで memory search は無効のままです。ローカルモデル経路が 設定済みで存在する場合、OpenClaw は `local` を優先します。Ollama は - `memorySearch.provider = "ollama"` を明示的に設定した場合にサポートされます。 + `memorySearch.provider = "ollama"` を明示設定した場合にサポートされます。 - ローカルのままにしたい場合は、`memorySearch.provider = "local"` を設定してください（必要に応じて - `memorySearch.fallback = "none"` も指定できます）。Gemini embeddings を使いたい場合は、 + ローカルのままにしたい場合は、`memorySearch.provider = "local"`（必要に応じて + `memorySearch.fallback = "none"` も）を設定してください。Gemini embeddings を使いたい場合は、 `memorySearch.provider = "gemini"` を設定し、`GEMINI_API_KEY`（または - `memorySearch.remote.apiKey`）を指定してください。サポートしている embedding - モデルは **OpenAI、Gemini、Voyage、Mistral、Ollama、または local** です。セットアップの詳細は [Memory](/ja-JP/concepts/memory) を参照してください。 + `memorySearch.remote.apiKey`）を指定してください。**OpenAI、Gemini、Voyage、Mistral、Ollama、または local** の embedding + モデルをサポートしています。セットアップの詳細は [Memory](/ja-JP/concepts/memory) を参照してください。 @@ -1355,39 +1373,39 @@ x-i18n: ## ディスク上の保存場所 - - いいえ。**OpenClaw の state はローカル** ですが、**外部サービスは依然として送信した内容を受け取ります**。 + + いいえ。**OpenClaw の状態はローカル** ですが、**外部サービスには送信した内容が引き続き見えます**。 - - **デフォルトでローカル:** sessions、メモリファイル、config、workspace は Gateway host 上に保存されます + - **デフォルトではローカル:** sessions、memory files、config、workspace は Gateway host 上にあります （`~/.openclaw` + あなたの workspace ディレクトリ）。 - - **必要上リモート:** model providers（Anthropic/OpenAI など）に送るメッセージは - それらの API に送信され、chat platforms（WhatsApp/Telegram/Slack など）はメッセージデータを - 自身のサーバーに保存します。 - - **フットプリントは自分で制御可能:** ローカルモデルを使えばプロンプトは自分のマシン上に残りますが、channel - トラフィックは依然としてそのチャネルのサーバーを経由します。 + - **必要上リモート:** モデルプロバイダー（Anthropic/OpenAI など）に送るメッセージは + それらの API に送信され、チャットプラットフォーム（WhatsApp/Telegram/Slack など）はメッセージデータを + 自社サーバーに保存します。 + - **フットプリントは自分で制御可能:** ローカルモデルを使えばプロンプトは自分のマシン上に留まりますが、channel + トラフィックは引き続きその channel のサーバーを通過します。 関連: [Agent workspace](/ja-JP/concepts/agent-workspace), [Memory](/ja-JP/concepts/memory). - すべては `$OPENCLAW_STATE_DIR`（デフォルト: `~/.openclaw`）配下にあります。 + すべては `$OPENCLAW_STATE_DIR`（デフォルト: `~/.openclaw`）配下にあります: - | Path | 用途 | - | --------------------------------------------------------------- | -------------------------------------------------------------------- | - | `$OPENCLAW_STATE_DIR/openclaw.json` | メイン設定（JSON5） | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | レガシー OAuth インポート（初回使用時に auth profiles へコピー） | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles（OAuth、API keys、および任意の `keyRef`/`tokenRef`） | - | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef provider 用の任意のファイルベース secret payload | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | レガシー互換ファイル（静的な `api_key` エントリは除去済み） | - | `$OPENCLAW_STATE_DIR/credentials/` | Provider state（例: `whatsapp//creds.json`） | - | `$OPENCLAW_STATE_DIR/agents/` | エージェントごとの state（agentDir + sessions） | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | 会話履歴と state（エージェントごと） | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session metadata（エージェントごと） | + | Path | 用途 | + | --------------------------------------------------------------- | ------------------------------------------------------------------ | + | `$OPENCLAW_STATE_DIR/openclaw.json` | メイン設定（JSON5） | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 従来のOAuthインポート（初回使用時にauth profilesへコピーされる） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles（OAuth、APIキー、および任意の `keyRef`/`tokenRef`） | + | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef provider 用の任意のファイルベースsecret payload | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 従来互換ファイル（静的な `api_key` エントリーは除去される） | + | `$OPENCLAW_STATE_DIR/credentials/` | Provider state（例: `whatsapp//creds.json`） | + | `$OPENCLAW_STATE_DIR/agents/` | エージェントごとの状態（agentDir + sessions） | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 会話履歴と状態（エージェントごと） | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session metadata（エージェントごと） | - レガシーの単一エージェントパス: `~/.openclaw/agent/*`（`openclaw doctor` により移行）。 + 従来の単一エージェントパス: `~/.openclaw/agent/*`（`openclaw doctor` により移行されます）。 - **workspace**（AGENTS.md、メモリファイル、skills など）は別で、`agents.defaults.workspace` 経由で設定します（デフォルト: `~/.openclaw/workspace`）。 + **workspace**（AGENTS.md、memory files、Skills など）は別で、`agents.defaults.workspace` によって設定されます（デフォルト: `~/.openclaw/workspace`）。 @@ -1395,12 +1413,12 @@ x-i18n: これらのファイルは `~/.openclaw` ではなく、**agent workspace** に置きます。 - **Workspace（エージェントごと）**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md`（`MEMORY.md` がない場合はレガシーフォールバックの `memory.md`）、 + `MEMORY.md`（`MEMORY.md` がない場合は従来のフォールバック `memory.md`）、 `memory/YYYY-MM-DD.md`, 任意の `HEARTBEAT.md`。 - **State dir（`~/.openclaw`）**: config、channel/provider state、auth profiles、sessions、logs、 - および共有 skills（`~/.openclaw/skills`）。 + および共有 Skills（`~/.openclaw/skills`）。 - デフォルトの workspace は `~/.openclaw/workspace` で、以下で設定できます。 + デフォルトの workspace は `~/.openclaw/workspace` で、次のように設定できます: ```json5 { @@ -1408,23 +1426,23 @@ x-i18n: } ``` - 再起動後にボットが「忘れる」場合は、Gateway が起動のたびに同じ - workspace を使っていることを確認してください（そして忘れないでください: remote mode では **gateway host の** - workspace が使われ、ローカルのノート PC のものではありません）。 + 再起動後に bot が「忘れる」場合は、Gateway が毎回同じ + workspace を使用して起動していることを確認してください（また、remote mode では **gateway host 側の** + workspace が使われるので、ローカルのノートPC側ではないことにも注意してください）。 - ヒント: 永続的なふるまいや設定を残したい場合は、チャット履歴に頼るのではなく、 - ボットに **AGENTS.md または MEMORY.md に書き込む** よう依頼してください。 + ヒント: 永続的な振る舞いや設定を持たせたい場合は、チャット履歴に頼るのではなく、 + bot に **AGENTS.md または MEMORY.md に書き込む** よう依頼してください。 [Agent workspace](/ja-JP/concepts/agent-workspace) と [Memory](/ja-JP/concepts/memory) を参照してください。 - **agent workspace** を **private** git repo に入れ、どこか非公開の場所 - （たとえば GitHub private）にバックアップしてください。これにより memory + AGENTS/SOUL/USER - ファイルが保存され、後でアシスタントの「心」を復元できます。 + **agent workspace** は **private** な git リポジトリに置き、どこか + 非公開の場所（たとえば GitHub private）にバックアップしてください。これによりメモリ + AGENTS/SOUL/USER + ファイルが保存され、後からアシスタントの「心」を復元できます。 - `~/.openclaw` 配下のもの（credentials、sessions、tokens、または暗号化された secrets payload）は **絶対に** commit しないでください。 + `~/.openclaw` 配下のもの（認証情報、sessions、tokens、または暗号化された secrets payload）を commit しては**いけません**。 完全な復元が必要な場合は、workspace と state directory の両方を 別々にバックアップしてください（上の移行に関する質問を参照）。 @@ -1436,16 +1454,15 @@ x-i18n: 専用ガイドを参照してください: [Uninstall](/ja-JP/install/uninstall)。 - - はい。workspace は **デフォルトの cwd** およびメモリアンカーであり、厳密なサンドボックスではありません。 - 相対パスは workspace 内で解決されますが、absolute paths は他の - ホスト上の場所にもアクセスできます。ただしサンドボックス化が有効な場合は除きます。分離が必要なら、 - [`agents.defaults.sandbox`](/ja-JP/gateway/sandboxing) またはエージェント単位のサンドボックス設定を使ってください。repo を - デフォルトの作業ディレクトリにしたい場合は、そのエージェントの - `workspace` を repo root に向けてください。OpenClaw repo は単なるソースコードです。意図的にその中でエージェントを作業させたいのでない限り、 - workspace は分けておいてください。 + + はい。workspace は **デフォルトの cwd** とメモリアンカーであり、厳密なサンドボックスではありません。 + 相対パスは workspace 内で解決されますが、絶対パスでは他の + ホスト上の場所にもアクセスできます。分離が必要な場合は、 + [`agents.defaults.sandbox`](/ja-JP/gateway/sandboxing) またはエージェントごとの sandbox 設定を使用してください。リポジトリをデフォルト作業ディレクトリにしたい場合は、その agent の + `workspace` をリポジトリルートに向けてください。OpenClaw リポジトリは単なるソースコードであり、 + 意図的にそこで agent を作業させたい場合を除いて、workspace は別に保ってください。 - 例（repo をデフォルトの cwd にする）: + 例（リポジトリをデフォルト cwd にする場合）: ```json5 { @@ -1459,30 +1476,31 @@ x-i18n: - - Session state は **gateway host** が保持します。remote mode の場合、重要な session store はローカルのノート PC ではなくリモートマシン上にあります。[Session management](/ja-JP/concepts/session) を参照してください。 + + Session state は **gateway host** が保持します。remote mode の場合、重要なのはローカルのノートPCではなく、リモートマシン上の session store です。[Session management](/ja-JP/concepts/session) を参照してください。 ## 設定の基本 - - OpenClaw は `$OPENCLAW_CONFIG_PATH`（デフォルト: `~/.openclaw/openclaw.json`）から、任意の **JSON5** 設定を読み込みます。 + + OpenClaw は `$OPENCLAW_CONFIG_PATH`（デフォルト: `~/.openclaw/openclaw.json`）から + 任意の **JSON5** 設定を読み込みます: ``` $OPENCLAW_CONFIG_PATH ``` - ファイルが存在しない場合は、安全寄りのデフォルト値が使われます（デフォルト workspace は `~/.openclaw/workspace`）。 + ファイルが存在しない場合は、安全寄りのデフォルト値（`~/.openclaw/workspace` をデフォルト workspace に含む）を使用します。 - non-loopback bind では **有効な gateway auth 経路が必須** です。実際には次のいずれかを意味します。 + non-loopback bind では **有効な gateway auth path が必須** です。実際には次のいずれかを意味します: - shared-secret auth: token または password - - `gateway.auth.mode: "trusted-proxy"` を、正しく設定された non-loopback の identity-aware reverse proxy の背後で使う + - 正しく設定された non-loopback の ID認識型 reverse proxy の背後にある `gateway.auth.mode: "trusted-proxy"` ```json5 { @@ -1496,34 +1514,34 @@ x-i18n: } ``` - 注意: + 注意点: - `gateway.remote.token` / `.password` だけではローカル gateway auth は有効になりません。 - - ローカルの呼び出し経路では、`gateway.auth.*` が未設定の場合に限り `gateway.remote.*` をフォールバックとして使えます。 - - password auth では、代わりに `gateway.auth.mode: "password"` と `gateway.auth.password`（または `OPENCLAW_GATEWAY_PASSWORD`）を設定してください。 - - `gateway.auth.token` / `gateway.auth.password` が SecretRef 経由で明示的に設定されていて未解決の場合、解決は安全側で失敗します（remote フォールバックで隠蔽されることはありません）。 - - shared-secret の Control UI セットアップでは、`connect.params.auth.token` または `connect.params.auth.password`（app/UI 設定に保存）で認証します。Tailscale Serve や `trusted-proxy` のような identity-bearing モードでは、代わりに request headers を使います。shared secrets を URL に入れないでください。 - - `gateway.auth.mode: "trusted-proxy"` では、同一ホストの loopback reverse proxy は依然として trusted-proxy auth を満たしません。trusted proxy は、設定済みの non-loopback source である必要があります。 + - ローカルの call path では、`gateway.auth.*` が未設定のときに限って `gateway.remote.*` をフォールバックとして使用できます。 + - password auth を使う場合は、代わりに `gateway.auth.mode: "password"` と `gateway.auth.password`（または `OPENCLAW_GATEWAY_PASSWORD`）を設定してください。 + - `gateway.auth.token` / `gateway.auth.password` が SecretRef 経由で明示設定されていて未解決の場合、解決は fail closed になります（remote fallback によるマスクはされません）。 + - shared-secret を使う Control UI セットアップでは、`connect.params.auth.token` または `connect.params.auth.password`（アプリ/UI設定に保存される）で認証します。Tailscale Serve や `trusted-proxy` のような ID を持つモードでは、代わりに request headers を使用します。shared secrets を URL に入れないでください。 + - `gateway.auth.mode: "trusted-proxy"` の場合、同一ホスト上の loopback reverse proxy では依然として trusted-proxy auth を満たしません。trusted proxy は設定済みの non-loopback source である必要があります。 - - OpenClaw はデフォルトで gateway auth を強制しており、loopback も含まれます。通常のデフォルト経路では token auth を意味します。明示的な auth 経路が設定されていない場合、gateway 起動時に token mode に解決されて自動生成され、それが `gateway.auth.token` に保存されるため、**ローカルの WS クライアントも認証が必要** になります。これにより、他のローカルプロセスが Gateway を呼び出すのを防ぎます。 + + OpenClaw は loopback を含め、デフォルトで gateway auth を強制します。通常のデフォルト経路では、これは token auth を意味します。明示的な auth path が設定されていない場合、gateway 起動時に token mode に解決されて自動生成され、`gateway.auth.token` に保存されるため、**ローカルの WS clients は認証が必要** になります。これにより、他のローカルプロセスが Gateway を呼び出すことを防ぎます。 - 別の auth 経路を望む場合は、password mode（または non-loopback の identity-aware reverse proxies 向けに `trusted-proxy`）を明示的に選べます。**本当に** open loopback にしたい場合は、設定で `gateway.auth.mode: "none"` を明示的に指定してください。Doctor はいつでも token を生成できます: `openclaw doctor --generate-gateway-token`。 + 別の auth path を望む場合は、password mode（または、non-loopback の ID認識型 reverse proxy では `trusted-proxy`）を明示的に選択できます。**本当に** open loopback にしたい場合は、設定で明示的に `gateway.auth.mode: "none"` を指定してください。Doctor はいつでも token を生成できます: `openclaw doctor --generate-gateway-token`。 - - Gateway は設定を監視しており、ホットリロードをサポートしています。 + + Gateway は設定ファイルを監視しており、hot-reload をサポートしています: - - `gateway.reload.mode: "hybrid"`（デフォルト）: 安全な変更はホット適用し、重要な変更では再起動します - - `hot`、`restart`、`off` もサポートされています + - `gateway.reload.mode: "hybrid"`（デフォルト）: 安全な変更は hot-apply、重要な変更は再起動 + - `hot`, `restart`, `off` もサポートされています - - 設定で `cli.banner.taglineMode` を設定します。 + + 設定で `cli.banner.taglineMode` を指定してください: ```json5 { @@ -1537,22 +1555,22 @@ x-i18n: - `off`: タグラインのテキストを非表示にしますが、バナーのタイトル/バージョン行は残します。 - `default`: 毎回 `All your chats, one OpenClaw.` を使用します。 - - `random`: 面白い/季節もののタグラインをローテーションします（デフォルト動作）。 - - バナー自体を完全に消したい場合は、env `OPENCLAW_HIDE_BANNER=1` を設定してください。 + - `random`: おもしろい/季節ごとのタグラインをローテーションします（デフォルト動作）。 + - バナー自体を表示したくない場合は、env `OPENCLAW_HIDE_BANNER=1` を設定してください。 - - `web_fetch` は API key なしで動作します。`web_search` は、選択した - provider に依存します。 + + `web_fetch` は APIキーなしで動作します。`web_search` は選択した + provider に依存します: - - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity、Tavily のような API ベースの provider では、通常どおり API key の設定が必要です。 - - Ollama Web Search はキー不要ですが、設定済みの Ollama host を使い、`ollama signin` が必要です。 + - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity、Tavily などの API ベース provider は、通常どおり APIキーの設定が必要です。 + - Ollama Web Search はキー不要ですが、設定済みの Ollama host を使用し、`ollama signin` が必要です。 - DuckDuckGo はキー不要ですが、非公式の HTML ベース統合です。 - SearXNG はキー不要/セルフホスト型です。`SEARXNG_BASE_URL` または `plugins.entries.searxng.config.webSearch.baseUrl` を設定してください。 **推奨:** `openclaw configure --section web` を実行して provider を選択してください。 - 環境変数での代替設定: + 環境変数による代替: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1587,7 +1605,7 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // 任意。自動検出するなら省略 + provider: "firecrawl", // 任意; 自動検出にする場合は省略 }, }, }, @@ -1595,17 +1613,17 @@ x-i18n: ``` provider 固有の web-search 設定は現在 `plugins.entries..config.webSearch.*` 配下にあります。 - レガシーの `tools.web.search.*` provider パスも互換性のため一時的に読み込まれますが、新しい設定では使わないでください。 - Firecrawl の web-fetch フォールバック設定は `plugins.entries.firecrawl.config.webFetch.*` 配下にあります。 + 従来の `tools.web.search.*` provider path も一時的に互換性のため読み込まれますが、新しい設定では使用すべきではありません。 + Firecrawl の web-fetch fallback 設定は `plugins.entries.firecrawl.config.webFetch.*` 配下にあります。 - 注意: + 注意点: - allowlist を使っている場合は、`web_search`/`web_fetch`/`x_search` または `group:web` を追加してください。 - `web_fetch` はデフォルトで有効です（明示的に無効化していない限り）。 - - `tools.web.fetch.provider` を省略すると、OpenClaw は利用可能な資格情報から最初に準備できた fetch フォールバック provider を自動検出します。現時点でのバンドル済み provider は Firecrawl です。 + - `tools.web.fetch.provider` を省略した場合、OpenClaw は利用可能な認証情報から最初に準備完了した fetch fallback provider を自動検出します。現時点でのバンドル済み provider は Firecrawl です。 - デーモンは `~/.openclaw/.env`（または service environment）から env vars を読み込みます。 - ドキュメント: [Web tools](/ja-JP/tools/web)。 + ドキュメント: [Web tools](/ja-JP/tools/web). @@ -1615,38 +1633,38 @@ x-i18n: 復旧方法: - - バックアップ（git またはコピーしておいた `~/.openclaw/openclaw.json`）から復元してください。 - - バックアップがない場合は、`openclaw doctor` を再実行して channels/models を再設定してください。 - - 想定外だった場合は、バグを報告し、最後に分かっている設定またはバックアップを添えてください。 - - ローカルのコーディングエージェントなら、ログや履歴から動作する設定を再構築できることがよくあります。 + - バックアップ（git またはコピーしておいた `~/.openclaw/openclaw.json`）から復元する。 + - バックアップがない場合は、`openclaw doctor` を再実行して channels/models を再設定する。 + - 予期しない動作だった場合は、バグを報告し、直前の設定またはバックアップを含める。 + - ローカルのコーディングエージェントであれば、ログや履歴から動作する設定を再構築できることが多いです。 防ぐ方法: - - 小さな変更には `openclaw config set` を使ってください。 - - 対話的な編集には `openclaw configure` を使ってください。 - - 正確なパスやフィールド形状に自信がない場合は、まず `config.schema.lookup` を使ってください。浅いスキーマノードと直下の子要約が返るので、段階的に掘り下げられます。 - - 部分的な RPC 編集には `config.patch` を使い、`config.apply` は完全な設定置換にだけ使ってください。 - - エージェント実行から owner-only の `gateway` tool を使っている場合でも、`tools.exec.ask` / `tools.exec.security` への書き込みは引き続き拒否されます（同じ保護された exec パスに正規化されるレガシー `tools.bash.*` エイリアスを含みます）。 + - 小さな変更には `openclaw config set` を使う。 + - 対話的な編集には `openclaw configure` を使う。 + - 正確な path や field shape に自信がない場合は、まず `config.schema.lookup` を使う。浅い schema node と、掘り下げ用の直下の子要約が返されます。 + - 部分的な RPC 編集には `config.patch` を使い、`config.apply` は完全な設定置換にのみ使う。 + - エージェント実行から owner-only の `gateway` tool を使っている場合でも、`tools.exec.ask` / `tools.exec.security` への書き込みは引き続き拒否されます（同じ保護された exec path に正規化される従来の `tools.bash.*` エイリアスを含む）。 - ドキュメント: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/ja-JP/gateway/doctor)。 + ドキュメント: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/ja-JP/gateway/doctor). - - 一般的なパターンは **1 つの Gateway**（例: Raspberry Pi）と **Nodes**、**agents** の組み合わせです。 + + 一般的なパターンは、**1つの Gateway**（例: Raspberry Pi）に **nodes** と **agents** を組み合わせる構成です: - - **Gateway（中央）:** channels（Signal/WhatsApp）とルーティング、sessions を管理します。 - - **Nodes（デバイス）:** Mac/iOS/Android が周辺機器として接続し、ローカルツール（`system.run`、`canvas`、`camera`）を公開します。 - - **Agents（worker）:** 特殊な役割（例: 「Hetzner ops」「個人データ」）向けの別々の頭脳/workspaces です。 - - **サブエージェント:** 並列性が欲しいときに、メインエージェントからバックグラウンド作業を起動します。 - - **TUI:** Gateway に接続し、agents/sessions を切り替えます。 + - **Gateway（中央）:** channels（Signal/WhatsApp）、routing、sessions を保持する。 + - **Nodes（デバイス）:** Mac/iOS/Android が周辺機器として接続し、ローカルツール（`system.run`, `canvas`, `camera`）を公開する。 + - **Agents（ワーカー）:** 特定の役割（例: 「Hetzner ops」、「個人データ」）向けの別々の頭脳/workspaces。 + - **Sub-agents:** 並列化したいときに、main agent からバックグラウンド作業を起動する。 + - **TUI:** Gateway に接続し、agents/sessions を切り替える。 - ドキュメント: [Nodes](/ja-JP/nodes), [Remote access](/ja-JP/gateway/remote), [Multi-Agent Routing](/ja-JP/concepts/multi-agent), [Sub-agents](/ja-JP/tools/subagents), [TUI](/web/tui)。 + ドキュメント: [Nodes](/ja-JP/nodes), [Remote access](/ja-JP/gateway/remote), [Multi-Agent Routing](/ja-JP/concepts/multi-agent), [Sub-agents](/ja-JP/tools/subagents), [TUI](/web/tui). - はい。設定オプションです。 + はい。設定オプションです: ```json5 { @@ -1659,137 +1677,137 @@ x-i18n: } ``` - デフォルトは `false`（headful）です。headless は一部のサイトで bot 対策チェックを引き起こしやすくなります。[Browser](/ja-JP/tools/browser) を参照してください。 + デフォルトは `false`（headful）です。headless は一部のサイトで anti-bot チェックを誘発しやすくなります。[Browser](/ja-JP/tools/browser) を参照してください。 - headless でも **同じ Chromium エンジン** を使い、ほとんどの自動化（フォーム、クリック、スクレイピング、ログイン）で動作します。主な違いは次のとおりです。 + headless は **同じ Chromium engine** を使用し、ほとんどの自動化（フォーム、クリック、スクレイピング、ログイン）で動作します。主な違いは次のとおりです: - - ブラウザーウィンドウが表示されない（視覚情報が必要な場合はスクリーンショットを使用）。 - - 一部のサイトは headless モードでの自動化により厳格です（CAPTCHA、bot 対策）。 - たとえば、X/Twitter は headless セッションをブロックすることがよくあります。 + - 表示されるブラウザーウィンドウがない（視覚情報が必要ならスクリーンショットを使う）。 + - 一部のサイトは headless mode の自動化に対してより厳格です（CAPTCHA、anti-bot）。 + たとえば、X/Twitter はしばしば headless session をブロックします。 - - `browser.executablePath` を Brave のバイナリ（または任意の Chromium ベースブラウザー）に設定し、Gateway を再起動してください。 + + `browser.executablePath` を Brave のバイナリ（または任意の Chromium ベース browser）に設定し、Gateway を再起動してください。 完全な設定例は [Browser](/ja-JP/tools/browser#use-brave-or-another-chromium-based-browser) を参照してください。 -## リモート Gateway と Nodes +## リモート Gateway と nodes - - Telegram メッセージは **gateway** によって処理されます。gateway は agent を実行し、 - Node tool が必要なときにだけ **Gateway WebSocket** 経由で Nodes を呼び出します。 + + Telegram メッセージは **gateway** が処理します。gateway は agent を実行し、 + node tool が必要な場合に限り **Gateway WebSocket** 経由で nodes を呼び出します: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes は受信した provider トラフィックを見ることはなく、受け取るのは node RPC 呼び出しだけです。 + Nodes は受信する provider traffic を見ることはありません。受け取るのは node RPC 呼び出しだけです。 - 簡単に言うと、**自分のコンピューターを Node としてペアリング** してください。Gateway は別の場所で動作しますが、 + 短い答え: **コンピューターを node としてペアリング** してください。Gateway は別の場所で動作していても、 Gateway WebSocket 経由でローカルマシン上の `node.*` tools（screen、camera、system）を 呼び出せます。 一般的なセットアップ: - 1. 常時稼働ホスト（VPS/ホームサーバー）で Gateway を実行します。 - 2. Gateway host と自分のコンピューターを同じ tailnet に入れます。 - 3. Gateway WS に到達できることを確認します（tailnet bind または SSH tunnel）。 - 4. ローカルで macOS アプリを開き、**Remote over SSH** モード（または direct tailnet） - で接続し、Node として登録できるようにします。 - 5. Gateway 上で Node を承認します: + 1. Gateway を常時稼働ホスト（VPS/ホームサーバー）で実行する。 + 2. Gateway host と自分のコンピューターを同じ tailnet に置く。 + 3. Gateway WS に到達できることを確認する（tailnet bind または SSH tunnel）。 + 4. macOS app をローカルで開き、**Remote over SSH** mode（または直接 tailnet） + で接続し、node として登録できるようにする。 + 5. Gateway 上で node を承認する: ```bash openclaw devices list openclaw devices approve ``` - 別個の TCP bridge は不要です。Nodes は Gateway WebSocket 経由で接続します。 + 別個の TCP bridge は不要です。nodes は Gateway WebSocket 経由で接続します。 - セキュリティの注意: macOS Node をペアリングすると、そのマシンで `system.run` が可能になります。信頼できるデバイスだけを + セキュリティ上の注意: macOS node をペアリングすると、そのマシン上で `system.run` が可能になります。信頼できるデバイスだけを ペアリングし、[Security](/ja-JP/gateway/security) を確認してください。 - ドキュメント: [Nodes](/ja-JP/nodes), [Gateway protocol](/ja-JP/gateway/protocol), [macOS remote mode](/ja-JP/platforms/mac/remote), [Security](/ja-JP/gateway/security)。 + ドキュメント: [Nodes](/ja-JP/nodes), [Gateway protocol](/ja-JP/gateway/protocol), [macOS remote mode](/ja-JP/platforms/mac/remote), [Security](/ja-JP/gateway/security). - - まず基本を確認してください。 + + まず基本を確認してください: - - Gateway が動作している: `openclaw gateway status` - - Gateway の健全性: `openclaw status` - - Channel の健全性: `openclaw channels status` + - Gateway が動作中か: `openclaw gateway status` + - Gateway health: `openclaw status` + - Channel health: `openclaw channels status` - 次に認証とルーティングを確認します。 + 次に認証とルーティングを確認します: - Tailscale Serve を使っている場合は、`gateway.auth.allowTailscale` が正しく設定されていることを確認してください。 - - SSH tunnel 経由で接続している場合は、ローカル tunnel が有効で、正しいポートを指していることを確認してください。 + - SSH tunnel 経由で接続している場合は、ローカル tunnel が起動していて正しいポートを向いていることを確認してください。 - allowlist（DM または group）に自分のアカウントが含まれていることを確認してください。 - ドキュメント: [Tailscale](/ja-JP/gateway/tailscale), [Remote access](/ja-JP/gateway/remote), [Channels](/ja-JP/channels)。 + ドキュメント: [Tailscale](/ja-JP/gateway/tailscale), [Remote access](/ja-JP/gateway/remote), [Channels](/ja-JP/channels). - + はい。組み込みの「bot-to-bot」bridge はありませんが、いくつかの - 信頼できる方法で接続できます。 + 信頼できる方法で構成できます: - **最も簡単:** 両方のボットがアクセスできる通常の chat channel（Telegram/Slack/WhatsApp）を使います。 - Bot A が Bot B にメッセージを送り、その後は Bot B が通常どおり返信するようにします。 + **最も簡単:** 両方の bot がアクセスできる通常のチャットチャネル（Telegram/Slack/WhatsApp）を使います。 + Bot A に Bot B へメッセージを送らせ、その後 Bot B が通常どおり返信します。 - **CLI bridge（汎用）:** スクリプトを実行して、他方の Gateway に - `openclaw agent --message ... --deliver` を呼び出し、相手のボットが - listen しているチャットをターゲットにします。片方のボットがリモート VPS 上にある場合は、そのリモート Gateway に届くよう - SSH/Tailscale 経由で CLI を向けてください（[Remote access](/ja-JP/gateway/remote) を参照）。 + **CLI bridge（汎用）:** スクリプトで相手の Gateway に + `openclaw agent --message ... --deliver` を実行し、相手の bot が + 監視しているチャットを対象にします。片方の bot がリモート VPS 上にある場合は、そのリモート Gateway を + SSH/Tailscale 経由で CLI から指すようにします（[Remote access](/ja-JP/gateway/remote) を参照）。 - 例のパターン（対象 Gateway に到達できるマシンから実行）: + 例のパターン（対象 Gateway に到達できるマシン上で実行）: ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - ヒント: 2 つのボットが無限ループしないようガードレールを入れてください（メンション時のみ、channel - allowlists、または「bot メッセージには返信しない」ルール）。 + ヒント: 2つの bot が無限にループしないようにガードレールを追加してください（mention のみ、 + channel allowlists、または「bot メッセージには返信しない」ルール）。 - ドキュメント: [Remote access](/ja-JP/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/ja-JP/tools/agent-send)。 + ドキュメント: [Remote access](/ja-JP/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/ja-JP/tools/agent-send). - - いいえ。1 つの Gateway で複数の agents をホストでき、それぞれが独自の workspace、モデルのデフォルト、 - ルーティングを持てます。これが通常の構成であり、エージェントごとに - 1 台ずつ VPS を動かすよりもずっと安価で簡単です。 + + いいえ。1つの Gateway で複数の agents をホストでき、それぞれが独自の workspace、モデルデフォルト、 + および routing を持てます。これが通常のセットアップであり、 + agent ごとに1つの VPS を動かすよりもずっと安価で簡単です。 - 別々の VPS を使うのは、厳格な分離（セキュリティ境界）や、 - 共有したくない大きく異なる設定が必要な場合だけです。それ以外は、1 つの Gateway にして、 - 複数の agents またはサブエージェントを使ってください。 + 別々の VPS が必要になるのは、強い分離（セキュリティ境界）が必要な場合、または + 共有したくない大きく異なる設定が必要な場合だけです。それ以外は、1つの Gateway を維持し、 + 複数の agents または sub-agents を使ってください。 - - はい。リモート Gateway からノート PC に到達する第一級の方法が Nodes であり、 + + はい。リモート Gateway からノートPCに到達する第一級の方法が nodes であり、 シェルアクセス以上のことができます。Gateway は macOS/Linux（Windows は WSL2 経由）で動作し、 - 軽量です（小型の VPS や Raspberry Pi クラスのマシンで十分で、4 GB RAM あれば余裕があります）。そのため、常時稼働ホスト + ノート PC を Node にする構成が一般的です。 + 軽量です（小型 VPS や Raspberry Pi クラスのマシンで十分で、4 GB RAM あれば余裕があります）。そのため、常時稼働ホスト + ノートPC を node とする構成が一般的です。 - - **受信 SSH が不要。** Nodes は Gateway WebSocket に対して外向き接続し、デバイスペアリングを使います。 - - **より安全な実行制御。** `system.run` はそのノート PC 上の Node allowlists/approvals によって制御されます。 + - **受信 SSH 不要。** Nodes は Gateway WebSocket へ外向き接続し、デバイスペアリングを使います。 + - **より安全な実行制御。** `system.run` はそのノートPC上の node allowlists/approvals によって制御されます。 - **より多くのデバイスツール。** Nodes は `system.run` に加えて `canvas`、`camera`、`screen` を公開します。 - - **ローカルブラウザー自動化。** Gateway は VPS 上に置きつつ、Chrome はノート PC 上の Node host 経由でローカル実行するか、Chrome MCP 経由でホスト上のローカル Chrome に接続できます。 + - **ローカル browser 自動化。** Gateway は VPS 上に置いたまま、ノートPC上の node host を通じてローカル Chrome を動かしたり、Chrome MCP 経由でホスト上のローカル Chrome に接続したりできます。 - SSH は臨時のシェルアクセスには問題ありませんが、継続的な agent ワークフローや - デバイス自動化には Nodes の方が簡単です。 + SSH はその場限りのシェルアクセスには問題ありませんが、継続的な agent ワークフローや + デバイス自動化には nodes の方が簡単です。 - ドキュメント: [Nodes](/ja-JP/nodes), [Nodes CLI](/cli/nodes), [Browser](/ja-JP/tools/browser)。 + ドキュメント: [Nodes](/ja-JP/nodes), [Nodes CLI](/cli/nodes), [Browser](/ja-JP/tools/browser). - - いいえ。意図的に分離されたプロファイルを実行する場合（[Multiple gateways](/ja-JP/gateway/multiple-gateways) を参照）を除き、ホストごとに実行すべき gateway は **1 つだけ** です。Nodes は gateway に接続する周辺機器です - （iOS/Android Nodes、またはメニューバーアプリの macOS「node mode」）。headless の node - host と CLI 制御については、[Node host CLI](/cli/node) を参照してください。 + + いいえ。意図的に分離されたprofileを動かす場合（[Multiple gateways](/ja-JP/gateway/multiple-gateways) を参照）を除き、ホストごとに実行する gateway は **1つだけ** にすべきです。Nodes は gateway に接続する周辺機器です + （iOS/Android nodes、またはメニューバーアプリの macOS 「node mode」）。headless な node + hosts と CLI 制御については、[Node host CLI](/cli/node) を参照してください。 `gateway`、`discovery`、`canvasHost` の変更には完全な再起動が必要です。 @@ -1798,11 +1816,11 @@ x-i18n: はい。 - - `config.schema.lookup`: 書き込む前に、1 つの設定サブツリーについて、浅いスキーマノード、一致した UI ヒント、直下の子要約を確認します - - `config.get`: 現在のスナップショット + hash を取得します - - `config.patch`: 安全な部分更新（ほとんどの RPC 編集で推奨）。可能ならホットリロードし、必要なら再起動します - - `config.apply`: 検証して完全な設定を置換します。可能ならホットリロードし、必要なら再起動します - - owner-only の `gateway` runtime tool は、引き続き `tools.exec.ask` / `tools.exec.security` の書き換えを拒否します。レガシーの `tools.bash.*` エイリアスは同じ保護された exec パスに正規化されます + - `config.schema.lookup`: 書き込む前に、1つの設定サブツリーについて浅い schema node、対応する UI ヒント、直下の子要約を確認する + - `config.get`: 現在のスナップショット + hash を取得する + - `config.patch`: 安全な部分更新（ほとんどの RPC 編集では推奨）。可能なら hot-reload し、必要なら再起動する + - `config.apply`: 設定全体を検証して置き換える。可能なら hot-reload し、必要なら再起動する + - owner-only の `gateway` runtime tool は、引き続き `tools.exec.ask` / `tools.exec.security` の書き換えを拒否します。従来の `tools.bash.*` エイリアスは同じ保護された exec path に正規化されます @@ -1814,65 +1832,65 @@ x-i18n: } ``` - これで workspace を設定し、誰がボットをトリガーできるかを制限します。 + これにより workspace を設定し、誰が bot をトリガーできるかを制限します。 最小手順: - 1. **VPS でインストールしてログイン** + 1. **VPS にインストールしてログイン** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Mac でインストールしてログイン** + 2. **Mac にインストールしてログイン** - Tailscale アプリを使い、同じ tailnet にサインインします。 - 3. **MagicDNS を有効化（推奨）** + 3. **MagicDNS を有効にする（推奨）** - Tailscale 管理コンソールで MagicDNS を有効にし、VPS に安定した名前を付けます。 - 4. **tailnet のホスト名を使う** + 4. **tailnet ホスト名を使う** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` - SSH なしで Control UI を使いたい場合は、VPS で Tailscale Serve を使います。 + SSH なしで Control UI を使いたい場合は、VPS 上で Tailscale Serve を使用してください: ```bash openclaw gateway --tailscale serve ``` - これにより gateway は loopback に bind したままになり、Tailscale 経由で HTTPS が公開されます。[Tailscale](/ja-JP/gateway/tailscale) を参照してください。 + これにより gateway は loopback に bind されたままとなり、Tailscale 経由で HTTPS が公開されます。[Tailscale](/ja-JP/gateway/tailscale) を参照してください。 - - Serve は **Gateway Control UI + WS** を公開します。Nodes は同じ Gateway WS エンドポイント経由で接続します。 + + Serve は **Gateway Control UI + WS** を公開します。Nodes は同じ Gateway WS endpoint 経由で接続します。 推奨セットアップ: - 1. **VPS と Mac が同じ tailnet にあることを確認** します。 - 2. **macOS アプリを Remote mode で使います**（SSH ターゲットには tailnet のホスト名を使えます）。 - アプリは Gateway ポートをトンネルし、Node として接続します。 - 3. gateway 上で Node を承認します: + 1. **VPS と Mac が同じ tailnet 上にあることを確認する**。 + 2. **macOS アプリを Remote mode で使う**（SSH target には tailnet hostname を指定できます）。 + アプリが Gateway port をトンネルし、node として接続します。 + 3. gateway 上で node を承認する: ```bash openclaw devices list openclaw devices approve ``` - ドキュメント: [Gateway protocol](/ja-JP/gateway/protocol), [Discovery](/ja-JP/gateway/discovery), [macOS remote mode](/ja-JP/platforms/mac/remote). + ドキュメント: [Gateway protocol](/ja-JP/gateway/protocol), [Discovery](/ja-JP/gateway/discovery), [macOS remote mode](/ja-JP/platforms/mac/remote)。 - - 2 台目のノート PC で必要なのが **ローカルツール**（screen/camera/exec）だけなら、 - **Node** として追加してください。これなら Gateway を 1 つに保てて、設定の重複も避けられます。ローカルの Node tools は - 現在 macOS 専用ですが、今後ほかの OS にも拡張する予定です。 + + 2台目のノートPCで必要なのが **ローカルツール**（screen/camera/exec）だけなら、 + **node** として追加してください。そうすれば Gateway は1つのままで、設定の重複を避けられます。ローカル node tools は + 現時点では macOS のみ対応ですが、今後ほかの OS にも拡張する予定です。 - 2 台目の Gateway をインストールするのは、**厳格な分離** または完全に別々のボットが必要な場合だけです。 + 2つ目の Gateway をインストールするのは、**強い分離** が必要な場合、または完全に別々の bot が2つ必要な場合だけです。 - ドキュメント: [Nodes](/ja-JP/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/ja-JP/gateway/multiple-gateways). + ドキュメント: [Nodes](/ja-JP/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/ja-JP/gateway/multiple-gateways)。 @@ -1881,14 +1899,14 @@ x-i18n: - OpenClaw は親プロセス（shell、launchd/systemd、CI など）から env vars を読み取り、さらに次も読み込みます。 + OpenClaw は親プロセス（shell、launchd/systemd、CI など）から env vars を読み取り、さらに次も読み込みます: - 現在の作業ディレクトリの `.env` - `~/.openclaw/.env`（別名 `$OPENCLAW_STATE_DIR/.env`）のグローバルフォールバック `.env` どちらの `.env` ファイルも、既存の env vars を上書きしません。 - 設定内でインライン env vars を定義することもできます（プロセス env に存在しない場合のみ適用）。 + 設定内でインライン env vars を定義することもできます（プロセス env に存在しない場合にのみ適用）: ```json5 { @@ -1899,15 +1917,15 @@ x-i18n: } ``` - 完全な優先順位と読み込み元については [/environment](/ja-JP/help/environment) を参照してください。 + 完全な優先順位と読み込み元については、[/environment](/ja-JP/help/environment) を参照してください。 - よくある修正方法は 2 つあります。 + よくある修正方法は2つあります: - 1. `~/.openclaw/.env` に不足しているキーを入れてください。そうすれば、service がシェルの env を継承しなくても読み込まれます。 - 2. shell import を有効にします（任意の利便機能）。 + 1. 不足しているキーを `~/.openclaw/.env` に入れる。そうすれば service が shell env を継承しない場合でも読み込まれます。 + 2. shell import を有効にする（オプトインの利便機能）: ```json5 { @@ -1920,52 +1938,52 @@ x-i18n: } ``` - これにより login shell が実行され、想定される不足キーだけが取り込まれます（上書きはしません）。環境変数での同等設定: + これにより login shell が実行され、想定される不足キーだけが取り込まれます（上書きはしません）。対応する env var: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`。 - - `openclaw models status` は **shell env import** が有効かどうかを報告します。「Shell env: off」は、 - env vars が不足していることを意味するのではなく、OpenClaw が - login shell を自動読み込みしないことを意味します。 + + `openclaw models status` は、**shell env import** が有効かどうかを報告します。"Shell env: off" + は、env vars が不足していることを意味するのではなく、OpenClaw が + login shell を自動では読み込まないことを意味します。 - Gateway が service（launchd/systemd）として動いている場合、シェルの - 環境は継承されません。次のいずれかで修正してください。 + Gateway が service（launchd/systemd）として動作している場合、shell + environment は継承されません。次のいずれかで修正してください: - 1. token を `~/.openclaw/.env` に入れる: + 1. トークンを `~/.openclaw/.env` に入れる: ``` COPILOT_GITHUB_TOKEN=... ``` 2. または shell import（`env.shellEnv.enabled: true`）を有効にする。 - 3. または設定の `env` ブロックに追加する（不足時のみ適用）。 + 3. または config の `env` ブロックに追加する（不足時のみ適用）。 - その後、gateway を再起動して再確認してください。 + その後 gateway を再起動して再確認します: ```bash openclaw models status ``` - Copilot token は `COPILOT_GITHUB_TOKEN` から読み取られます（`GH_TOKEN` / `GITHUB_TOKEN` も可）。 + Copilot tokens は `COPILOT_GITHUB_TOKEN`（および `GH_TOKEN` / `GITHUB_TOKEN`）から読み取られます。 [/concepts/model-providers](/ja-JP/concepts/model-providers) と [/environment](/ja-JP/help/environment) を参照してください。 -## セッションと複数チャット +## Sessions と複数チャット - `/new` または `/reset` を単独のメッセージとして送信してください。[Session management](/ja-JP/concepts/session) を参照してください。 + 単独メッセージとして `/new` または `/reset` を送信してください。[Session management](/ja-JP/concepts/session) を参照してください。 - - セッションは `session.idleMinutes` 経過後に期限切れにできますが、これは **デフォルトでは無効** です（デフォルト **0**）。 - アイドル期限切れを有効にするには正の値を設定してください。有効時は、アイドル期間後の **次の** - メッセージで、その chat key に対する新しい session id が開始されます。 - これは transcript を削除するのではなく、新しいセッションを開始するだけです。 + + Sessions は `session.idleMinutes` の後に期限切れにできますが、これは **デフォルトでは無効**（デフォルト **0**）です。 + 有効にするには正の値を設定してください。有効時は、アイドル期間の**次の** + メッセージで、そのチャットキーに対する新しい session id が開始されます。 + これは transcript を削除するのではなく、新しい session を開始するだけです。 ```json5 { @@ -1977,72 +1995,72 @@ x-i18n: - - はい。**マルチエージェントルーティング** と **サブエージェント** を使います。1 つのコーディネーター - agent と、独自の workspaces とモデルを持つ複数の worker agents を作れます。 + + はい。**multi-agent routing** と **sub-agents** を使います。1つの coordinator + agent と、独自の workspaces と models を持つ複数の worker agents を作成できます。 - とはいえ、これは **楽しい実験** として捉えるのが最適です。トークン消費が大きく、 - 多くの場合、セッションを分けた 1 つのボットを使うより非効率です。私たちが - 想定している一般的なモデルは、1 つのボットに話しかけ、並列作業には異なるセッションを使うことです。その - ボットは必要に応じてサブエージェントも起動できます。 + ただし、これは **楽しい実験** として捉えるのが最適です。トークン消費が多く、 + 1つの bot を別々の sessions で使うより効率が落ちることもあります。私たちが + 想定している典型的なモデルは、あなたが会話する bot は1つで、並列作業用に + 別セッションを使う形です。その bot は必要に応じて sub-agents も起動できます。 - ドキュメント: [Multi-agent routing](/ja-JP/concepts/multi-agent), [Sub-agents](/ja-JP/tools/subagents), [Agents CLI](/cli/agents). + ドキュメント: [Multi-agent routing](/ja-JP/concepts/multi-agent), [Sub-agents](/ja-JP/tools/subagents), [Agents CLI](/cli/agents)。 - - Session context はモデルの window に制限されます。長いチャット、大きなツール出力、または多数の - ファイルによって Compaction や切り詰めが発生することがあります。 + + Session context はモデルのウィンドウによって制限されます。長いチャット、大きなツール出力、多数の + ファイルは Compaction や切り詰めを引き起こすことがあります。 - 効果のある方法: + 効果的な対策: - - ボットに現在の状態を要約してファイルに書くよう頼む。 - - 長いタスクの前に `/compact` を使い、話題を切り替えるときは `/new` を使う。 - - 重要なコンテキストは workspace に保持し、ボットにそれを再読させる。 - - 長時間または並列の作業にはサブエージェントを使い、メインチャットを小さく保つ。 - - これが頻繁に起きるなら、より大きい context window を持つモデルを選ぶ。 + - bot に現在の状態を要約してファイルに書くよう依頼する。 + - 長いタスクの前に `/compact` を使い、話題を変えるときは `/new` を使う。 + - 重要なコンテキストは workspace に置き、bot に再読込させる。 + - 長時間または並列の作業には sub-agents を使い、メインチャットを小さく保つ。 + - これが頻繁に起きるなら、より大きな context window を持つモデルを選ぶ。 - - reset コマンドを使ってください。 + + reset コマンドを使用してください: ```bash openclaw reset ``` - 非対話の完全リセット: + 非対話型の完全リセット: ```bash openclaw reset --scope full --yes --non-interactive ``` - その後、セットアップを再実行します。 + その後、セットアップを再実行してください: ```bash openclaw onboard --install-daemon ``` - 注意: + 注意点: - - 既存の設定を検出すると、オンボーディングでも **Reset** を提案します。[Onboarding (CLI)](/ja-JP/start/wizard) を参照してください。 + - 既存の設定を検出した場合、オンボーディングでも **Reset** が提示されます。[Onboarding (CLI)](/ja-JP/start/wizard) を参照してください。 - profiles（`--profile` / `OPENCLAW_PROFILE`）を使っていた場合は、各 state dir をリセットしてください（デフォルトは `~/.openclaw-`）。 - - dev reset: `openclaw gateway --dev --reset`（dev 専用。dev config + credentials + sessions + workspace を消去します）。 + - 開発用リセット: `openclaw gateway --dev --reset`（dev 専用。dev config + credentials + sessions + workspace を消去します）。 - 次のいずれかを使ってください。 + 次のいずれかを使ってください: - - **Compact**（会話は維持しつつ、古いターンを要約します）: + - **Compact**（会話は維持しつつ古いターンを要約）: ``` /compact ``` - または、要約内容を指定するには `/compact `。 + または `/compact ` で要約の方針を指定します。 - - **Reset**（同じ chat key に対して新しい session ID を開始）: + - **Reset**（同じチャットキーに対して新しい session ID を開始）: ``` /new @@ -2051,50 +2069,50 @@ x-i18n: それでも繰り返し起きる場合: - - **session pruning**（`agents.defaults.contextPruning`）を有効化または調整して、古いツール出力を削減してください。 - - より大きい context window を持つモデルを使ってください。 + - **session pruning**（`agents.defaults.contextPruning`）を有効化または調整して、古いツール出力を削減する。 + - より大きな context window を持つモデルを使う。 - ドキュメント: [Compaction](/ja-JP/concepts/compaction), [Session pruning](/ja-JP/concepts/session-pruning), [Session management](/ja-JP/concepts/session). + ドキュメント: [Compaction](/ja-JP/concepts/compaction), [Session pruning](/ja-JP/concepts/session-pruning), [Session management](/ja-JP/concepts/session)。 - - これは provider のバリデーションエラーです。モデルが必要な - `input` なしで `tool_use` ブロックを出力しました。通常はセッション履歴が古いか壊れていることを意味し（長いスレッドや - tool/schema 変更の後によく起こります）。 + + これは provider の検証エラーです。モデルが、必須の + `input` を持たない `tool_use` ブロックを出力しました。通常は、session history が古いか破損していることを意味します + （長い thread や tool/schema の変更後によく起こります）。 - 修正方法: `/new`（単独メッセージ）で新しいセッションを開始してください。 + 対処法: 単独メッセージで `/new` を送って、新しい session を開始してください。 - - Heartbeat はデフォルトで **30m** ごとに実行されます（OAuth auth 使用時は **1h**）。調整または無効化するには: + + Heartbeat はデフォルトで **30分** ごと（OAuth auth 使用時は **1時間** ごと）に実行されます。調整または無効化するには: ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // または "0m" で無効化 + every: "2h", // または無効化するなら "0m" }, }, }, } ``` - `HEARTBEAT.md` が存在していても、実質的に空（空行と `# Heading` のような markdown - ヘッダーのみ）の場合、OpenClaw は API 呼び出しを節約するため heartbeat 実行をスキップします。 - ファイルが存在しない場合、heartbeat は引き続き実行され、モデルが何をするかを判断します。 + `HEARTBEAT.md` が存在しても実質的に空（空行と + `# Heading` のような markdown header だけ）なら、OpenClaw は API 呼び出しを節約するため heartbeat 実行をスキップします。 + ファイルが存在しない場合でも heartbeat は実行され、何をするかはモデルが判断します。 - エージェント単位の override には `agents.list[].heartbeat` を使います。ドキュメント: [Heartbeat](/ja-JP/gateway/heartbeat)。 + エージェントごとの override には `agents.list[].heartbeat` を使います。ドキュメント: [Heartbeat](/ja-JP/gateway/heartbeat)。 - - いいえ。OpenClaw は **自分自身のアカウント** で動作するため、自分がそのグループにいれば、OpenClaw はそれを見られます。 - デフォルトでは、送信者を許可するまでグループ返信はブロックされます（`groupPolicy: "allowlist"`）。 + + いいえ。OpenClaw は **あなた自身のアカウント** で動作するため、あなたがグループにいれば OpenClaw もそれを見られます。 + デフォルトでは、送信者を許可するまで group replies はブロックされます（`groupPolicy: "allowlist"`）。 - グループ返信を **自分だけ** がトリガーできるようにしたい場合: + グループ返信をトリガーできるのを **自分だけ** にしたい場合: ```json5 { @@ -2110,68 +2128,68 @@ x-i18n: - 方法 1（最速）: ログを追いながら、グループにテストメッセージを送信します。 + 方法1（最速）: ログを追跡し、グループでテストメッセージを送信します: ```bash openclaw logs --follow --json ``` - `@g.us` で終わる `chatId`（または `from`）を探してください。例: + `@g.us` で終わる `chatId`（または `from`）を探してください。たとえば: `1234567890-1234567890@g.us`。 - 方法 2（すでに設定/allowlist 済みの場合）: 設定からグループを一覧表示します。 + 方法2（すでに設定済み/allowlist 済みの場合）: 設定からグループを一覧表示します: ```bash openclaw directory groups list --channel whatsapp ``` - ドキュメント: [WhatsApp](/ja-JP/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs)。 + ドキュメント: [WhatsApp](/ja-JP/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). - - よくある原因は 2 つあります。 + + よくある原因は2つあります: - - mention gating がオンです（デフォルト）。ボットを @mention する必要があります（または `mentionPatterns` に一致させる必要があります）。 - - `channels.whatsapp.groups` を `"*"` なしで設定していて、そのグループが allowlist に入っていません。 + - mention gating が有効です（デフォルト）。bot を @mention する必要があります（または `mentionPatterns` に一致させる必要があります）。 + - `channels.whatsapp.groups` を `"*"` なしで設定していて、そのグループが allowlist に含まれていません。 [Groups](/ja-JP/channels/groups) と [Group messages](/ja-JP/channels/group-messages) を参照してください。 - - ダイレクトチャットはデフォルトでメインセッションに集約されます。グループ/チャネルは独自の session key を持ち、Telegram topics / Discord threads も別セッションです。[Groups](/ja-JP/channels/groups) と [Group messages](/ja-JP/channels/group-messages) を参照してください。 + + 直接チャットはデフォルトで main session に集約されます。groups/channels は独自の session key を持ち、Telegram topics / Discord threads も別々の sessions です。[Groups](/ja-JP/channels/groups) と [Group messages](/ja-JP/channels/group-messages) を参照してください。 - - 厳密な上限はありません。数十個（場合によっては数百個）でも問題ありませんが、次の点には注意してください。 + + 厳密な上限はありません。数十個（あるいは数百個）でも問題ありませんが、次には注意してください: - - **ディスク使用量の増加:** sessions + transcripts は `~/.openclaw/agents//sessions/` 配下に保存されます。 - - **トークンコスト:** エージェントが増えるほど、同時モデル利用も増えます。 - - **運用負荷:** エージェントごとの auth profiles、workspaces、channel routing が必要です。 + - **ディスク増加:** sessions + transcripts は `~/.openclaw/agents//sessions/` 配下に保存されます。 + - **トークンコスト:** agents が増えるほど、同時モデル使用も増えます。 + - **運用負荷:** エージェントごとの auth profiles、workspaces、channel routing。 ヒント: - - エージェントごとに **アクティブな** workspace を 1 つ保ちます（`agents.defaults.workspace`）。 - - ディスクが増えてきたら、古い sessions を整理してください（JSONL や store entries を削除）。 - - `openclaw doctor` を使って、不要な workspaces や profile の不一致を見つけてください。 + - agent ごとに **アクティブな** workspace を1つ維持する（`agents.defaults.workspace`）。 + - ディスクが増えてきたら古い sessions を pruning する（JSONL または store entries を削除する）。 + - `openclaw doctor` を使って、取り残された workspaces や profile の不一致を見つける。 - - はい。**Multi-Agent Routing** を使って複数の分離されたエージェントを実行し、 - channel/account/peer ごとに受信メッセージをルーティングしてください。Slack はチャネルとしてサポートされており、特定のエージェントにバインドできます。 + + はい。**Multi-Agent Routing** を使って複数の分離された agents を実行し、 + 受信メッセージを channel/account/peer ごとにルーティングできます。Slack は channel としてサポートされており、特定の agents にバインドできます。 - browser アクセスは強力ですが、「人間にできることは何でもできる」わけではありません。bot 対策、CAPTCHA、MFA によって - 自動化がブロックされることはあります。最も信頼性の高い browser 制御を行うには、ホスト上でローカル Chrome MCP を使うか、 - 実際に browser を実行しているマシン上で CDP を使ってください。 + browser アクセスは強力ですが、「人間にできることなら何でもできる」わけではありません。anti-bot、CAPTCHA、MFA は + 依然として自動化をブロックすることがあります。最も信頼性の高い browser 制御を行うには、ホスト上のローカル Chrome MCP を使うか、 + browser を実際に動かしているマシン上で CDP を使ってください。 ベストプラクティスのセットアップ: - 常時稼働の Gateway host（VPS/Mac mini）。 - - 役割ごとに 1 つのエージェント（bindings）。 - - それらのエージェントにバインドされた Slack channel。 - - 必要に応じて、Chrome MCP または Node を介したローカル browser。 + - 役割ごとに1 agent（bindings）。 + - それらの agents にバインドされた Slack channel(s)。 + - 必要に応じて、Chrome MCP または node 経由のローカル browser。 ドキュメント: [Multi-Agent Routing](/ja-JP/concepts/multi-agent), [Slack](/ja-JP/channels/slack), [Browser](/ja-JP/tools/browser), [Nodes](/ja-JP/nodes). @@ -2179,37 +2197,38 @@ x-i18n: -## モデル: デフォルト、選択、エイリアス、切り替え +## Models: デフォルト、選択、aliases、切り替え - - OpenClaw のデフォルトモデルは、次で設定したものです。 + + OpenClaw のデフォルトモデルは、次に設定したものです: ``` agents.defaults.model.primary ``` - モデルは `provider/model` として参照されます（例: `openai/gpt-5.4`）。provider を省略した場合、OpenClaw はまずエイリアスを試し、次にその正確な model id に対する一意の設定済み provider 一致を試し、それでもだめなら非推奨の互換経路として設定済みのデフォルト provider にフォールバックします。その provider が設定済みのデフォルトモデルをもはや提供していない場合、OpenClaw は古い削除済み provider のデフォルトを表示する代わりに、最初の設定済み provider/model にフォールバックします。それでも、**明示的に** `provider/model` を設定するべきです。 + Models は `provider/model`（例: `openai/gpt-5.4`）として参照されます。provider を省略した場合、OpenClaw はまず alias を試し、次にその正確な model id に対する一意の configured-provider match を試し、それでもなければ非推奨の互換経路として configured default provider にフォールバックします。その provider が設定済みの default model をもう公開していない場合、古い削除済み provider のデフォルトを出す代わりに、最初に設定された provider/model にフォールバックします。それでも **明示的に** `provider/model` を設定するべきです。 - **推奨デフォルト:** 利用中の provider スタックで使える、最新世代の最も強力なモデルを使ってください。 - **tool 対応または信頼できない入力を扱うエージェント向け:** コストよりモデル性能を優先してください。 - **日常的/低リスクのチャット向け:** より安価な fallback models を使い、エージェントの役割ごとにルーティングしてください。 + **推奨デフォルト:** あなたの provider stack で利用可能な、最新世代の最も強力なモデルを使ってください。 + **tools 対応または信頼できない入力を扱う agents 向け:** コストよりモデル性能を優先してください。 + **日常的/低リスクなチャット向け:** より安価なフォールバックモデルを使い、agent の役割ごとにルーティングしてください。 MiniMax には専用ドキュメントがあります: [MiniMax](/ja-JP/providers/minimax) と - [Local models](/ja-JP/gateway/local-models)。 + [ローカルモデル](/ja-JP/gateway/local-models)。 - 経験則として、高リスクな作業には **払える範囲で最高のモデル** を使い、日常チャットや要約にはより安価な - モデルを使ってください。モデルはエージェントごとにルーティングでき、長いタスクはサブエージェントで - 並列化できます（各サブエージェントはトークンを消費します）。[Models](/ja-JP/concepts/models) と + 経験則として、高リスクな作業には **支払える範囲で最高のモデル** を使い、 + 日常的なチャットや要約にはより安価な + モデルを使ってください。モデルは agent ごとにルーティングでき、sub-agents を使って + 長いタスクを並列化できます（各 sub-agent はトークンを消費します）。[Models](/ja-JP/concepts/models) と [Sub-agents](/ja-JP/tools/subagents) を参照してください。 - 強い警告: 弱いモデルや過度に量子化されたモデルは、prompt + 強い警告: 弱い/過度に量子化されたモデルは、prompt injection や危険な挙動に対してより脆弱です。[Security](/ja-JP/gateway/security) を参照してください。 - 詳しくは: [Models](/ja-JP/concepts/models)。 + より詳しい情報: [Models](/ja-JP/concepts/models)。 @@ -2218,55 +2237,55 @@ x-i18n: 安全な方法: - - チャット内で `/model`（簡単、セッション単位） - - `openclaw models set ...`（モデル設定だけを更新） + - チャット内の `/model`（手軽、セッション単位） + - `openclaw models set ...`（model 設定だけを更新） - `openclaw configure --section model`（対話式） - `~/.openclaw/openclaw.json` の `agents.defaults.model` を編集 設定全体を置き換える意図がない限り、部分オブジェクトで `config.apply` を使わないでください。 - RPC 編集では、まず `config.schema.lookup` で確認し、`config.patch` を優先してください。lookup のペイロードには、正規化されたパス、浅いスキーマのドキュメント/制約、直下の子要約が含まれます。 - 部分更新用です。 - もし設定を上書きしてしまった場合は、バックアップから復元するか、`openclaw doctor` を再実行して修復してください。 + RPC 編集では、まず `config.schema.lookup` で確認し、`config.patch` を優先してください。lookup payload には、正規化された path、浅い schema docs/constraints、直下の子要約が含まれます。 + 部分更新に使ってください。 + 設定を上書きしてしまった場合は、バックアップから復元するか、`openclaw doctor` を再実行して修復してください。 ドキュメント: [Models](/ja-JP/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/ja-JP/gateway/doctor). - - はい。ローカルモデルへの最も簡単な経路は Ollama です。 + + はい。ローカルモデルでは Ollama が最も簡単な経路です。 最短セットアップ: 1. `https://ollama.com/download` から Ollama をインストール 2. `ollama pull gemma4` のようにローカルモデルを取得 - 3. クラウドモデルも使いたい場合は `ollama signin` を実行 + 3. クラウドモデルも使いたい場合は、`ollama signin` を実行 4. `openclaw onboard` を実行して `Ollama` を選択 - 5. `Local` または `Cloud + Local` を選択 + 5. `Local` または `Cloud + Local` を選ぶ - 注意: + 注意点: - `Cloud + Local` ではクラウドモデルに加えてローカルの Ollama モデルも使えます - - `kimi-k2.5:cloud` のようなクラウドモデルはローカルでの pull は不要です + - `kimi-k2.5:cloud` のようなクラウドモデルにはローカル pull は不要です - 手動で切り替える場合は、`openclaw models list` と `openclaw models set ollama/` を使ってください - セキュリティ注意: 小さいモデルや大きく量子化されたモデルは、prompt - injection に対してより脆弱です。tools を使えるボットには **大きなモデル** を強く推奨します。 - それでも小さなモデルを使いたい場合は、サンドボックス化と厳格な tool allowlists を有効にしてください。 + セキュリティ上の注意: より小さいモデルや強く量子化されたモデルは、prompt + injection に対してより脆弱です。tools を使用できる bot には **大規模モデル** を強く推奨します。 + それでも小さいモデルを使いたい場合は、sandboxing と厳格な tool allowlists を有効にしてください。 - ドキュメント: [Ollama](/ja-JP/providers/ollama), [Local models](/ja-JP/gateway/local-models), + ドキュメント: [Ollama](/ja-JP/providers/ollama), [ローカルモデル](/ja-JP/gateway/local-models), [Model providers](/ja-JP/concepts/model-providers), [Security](/ja-JP/gateway/security), [Sandboxing](/ja-JP/gateway/sandboxing). - - - これらのデプロイは異なる場合があり、時間とともに変わることがあります。固定の provider 推奨はありません。 + + - これらのデプロイはそれぞれ異なることがあり、時間とともに変わる可能性もあります。固定の provider 推奨はありません。 - 各 gateway の現在のランタイム設定は `openclaw models status` で確認してください。 - - セキュリティ重視/tool 対応エージェントには、利用可能な最新世代で最も強力なモデルを使ってください。 + - セキュリティ重視/ツール対応の agents には、利用可能な最新世代で最も強力なモデルを使ってください。 - 単独メッセージとして `/model` コマンドを使ってください。 + 単独メッセージとして `/model` コマンドを使ってください: ``` /model sonnet @@ -2278,56 +2297,56 @@ x-i18n: /model gemini-flash-lite ``` - これらは組み込みのエイリアスです。カスタムエイリアスは `agents.defaults.models` で追加できます。 + これらは組み込み aliases です。カスタム aliases は `agents.defaults.models` で追加できます。 利用可能なモデルは `/model`、`/model list`、または `/model status` で一覧表示できます。 - `/model`（および `/model list`）は、コンパクトな番号付きピッカーを表示します。番号で選択します。 + `/model`（および `/model list`）は、コンパクトな番号付き picker を表示します。番号で選択できます: ``` /model 3 ``` - provider に対して特定の auth profile を強制することもできます（セッション単位）。 + provider に対して特定の auth profile を強制することもできます（セッション単位）: ``` /model opus@anthropic:default /model opus@anthropic:work ``` - ヒント: `/model status` では、どのエージェントが有効か、どの `auth-profiles.json` ファイルが使われているか、次にどの auth profile が試されるかが表示されます。 - また、利用可能な場合は設定済み provider endpoint（`baseUrl`）と API mode（`api`）も表示されます。 + ヒント: `/model status` では、どの agent がアクティブか、どの `auth-profiles.json` ファイルが使われているか、次にどの auth profile が試されるかが表示されます。 + 利用可能な場合は、設定済みの provider endpoint（`baseUrl`）と API mode（`api`）も表示されます。 - **`@profile` で設定した profile の固定を解除するにはどうすればよいですか？** + **`@profile` で設定した profile の固定を解除するには？** - `@profile` サフィックス **なし** で `/model` を再実行してください。 + `@profile` 接尾辞なしで `/model` を再実行してください: ``` /model anthropic/claude-opus-4-6 ``` - デフォルトに戻したい場合は、`/model` から選ぶか（または `/model ` を送ってください）。 - どの auth profile が有効かは `/model status` で確認してください。 + デフォルトに戻したい場合は、`/model` から選択するか（または `/model ` を送信してください）。 + どの auth profile がアクティブかは `/model status` で確認してください。 - - はい。1 つをデフォルトに設定し、必要に応じて切り替えてください。 + + はい。1つをデフォルトに設定し、必要に応じて切り替えてください: - - **簡単な切り替え（セッション単位）:** 日常タスクには `/model gpt-5.4`、Codex OAuth でのコーディングには `/model openai-codex/gpt-5.4`。 - - **デフォルト + 切り替え:** `agents.defaults.model.primary` を `openai/gpt-5.4` に設定し、コーディング時に `openai-codex/gpt-5.4` に切り替えます（またはその逆）。 - - **サブエージェント:** コーディングタスクを、別のデフォルトモデルを持つサブエージェントにルーティングします。 + - **クイック切り替え（セッション単位）:** 日常タスクには `/model gpt-5.4`、Codex OAuth でのコーディングには `/model openai-codex/gpt-5.4`。 + - **デフォルト + 切り替え:** `agents.defaults.model.primary` を `openai/gpt-5.4` に設定し、コーディング時に `openai-codex/gpt-5.4` に切り替える（または逆でも可）。 + - **Sub-agents:** コーディングタスクを、異なるデフォルトモデルを持つ sub-agents にルーティングする。 [Models](/ja-JP/concepts/models) と [Slash commands](/ja-JP/tools/slash-commands) を参照してください。 - セッショントグルまたは設定デフォルトのどちらかを使います。 + セッショントグルまたは設定デフォルトのいずれかを使ってください: - - **セッション単位:** セッションが `openai/gpt-5.4` または `openai-codex/gpt-5.4` を使っている間に `/fast on` を送信します。 - - **モデル単位のデフォルト:** `agents.defaults.models["openai/gpt-5.4"].params.fastMode` を `true` に設定します。 - - **Codex OAuth にも:** `openai-codex/gpt-5.4` も使う場合は、そちらにも同じフラグを設定します。 + - **セッション単位:** セッションが `openai/gpt-5.4` または `openai-codex/gpt-5.4` を使っている間に `/fast on` を送信する。 + - **モデルごとのデフォルト:** `agents.defaults.models["openai/gpt-5.4"].params.fastMode` を `true` に設定する。 + - **Codex OAuth も:** `openai-codex/gpt-5.4` も使うなら、同じフラグをそこにも設定する。 例: @@ -2352,57 +2371,58 @@ x-i18n: } ``` - OpenAI では、fast mode はサポートされているネイティブ Responses リクエスト上で `service_tier = "priority"` に対応します。セッションの `/fast` override は設定デフォルトより優先されます。 + OpenAI では、fast mode はサポートされているネイティブ Responses request で `service_tier = "priority"` に対応します。セッションの `/fast` override は設定デフォルトより優先されます。 [Thinking and fast mode](/ja-JP/tools/thinking) と [OpenAI fast mode](/ja-JP/providers/openai#openai-fast-mode) を参照してください。 - - `agents.defaults.models` が設定されている場合、それは `/model` とあらゆる - セッション override の **allowlist** になります。その一覧にないモデルを選ぶと、次が返されます。 + + `agents.defaults.models` が設定されている場合、それは `/model` とすべての + session override に対する **allowlist** になります。 + その一覧にないモデルを選ぶと、次が返されます: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - このエラーは通常の返信の **代わりに** 返されます。修正方法: そのモデルを - `agents.defaults.models` に追加するか、allowlist を削除するか、`/model list` からモデルを選んでください。 + このエラーは、通常の返信の**代わりに**返されます。対処法: モデルを + `agents.defaults.models` に追加する、allowlist を削除する、または `/model list` からモデルを選んでください。 - - これは **provider が設定されていない** ことを意味します（MiniMax provider 設定または auth - profile が見つからなかったため）、そのモデルを解決できません。 + + これは **provider が設定されていない** ことを意味します（MiniMax provider の設定または auth + profile が見つからなかったため）、モデルを解決できません。 - 修正チェックリスト: + 確認項目: - 1. 現在の OpenClaw リリースに更新する（またはソースの `main` から実行する）その後 gateway を再起動する。 - 2. MiniMax が設定されていること（ウィザードまたは JSON）、または一致する provider を注入できるよう - env/auth profiles に MiniMax auth が存在することを確認する - （`minimax` には `MINIMAX_API_KEY`、`minimax-portal` には `MINIMAX_OAUTH_TOKEN` または保存済み MiniMax + 1. 現在の OpenClaw リリースへアップグレードする（またはソースの `main` から実行する）してから、gateway を再起動する。 + 2. MiniMax が設定されていること（ウィザードまたは JSON）、または MiniMax の auth が + env/auth profiles に存在し、対応する provider を注入できることを確認する + （`minimax` には `MINIMAX_API_KEY`、`minimax-portal` には `MINIMAX_OAUTH_TOKEN` または保存済みの MiniMax OAuth）。 - 3. 自分の auth 経路に対して正確な model id（大文字小文字を区別）を使う: - API key 構成なら `minimax/MiniMax-M2.7` または `minimax/MiniMax-M2.7-highspeed`、 - OAuth 構成なら `minimax-portal/MiniMax-M2.7` / + 3. auth path に対して大文字小文字を区別する正確な model id を使う: + APIキー設定なら `minimax/MiniMax-M2.7` または `minimax/MiniMax-M2.7-highspeed`、 + OAuth 設定なら `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`。 - 4. 次を実行します: + 4. 次を実行する: ```bash openclaw models list ``` - そして一覧から選んでください（またはチャット内で `/model list`）。 + そして一覧から選ぶ（またはチャットで `/model list`）。 [MiniMax](/ja-JP/providers/minimax) と [Models](/ja-JP/concepts/models) を参照してください。 - - はい。**MiniMax をデフォルト** にして、必要なときに **セッション単位** でモデルを切り替えてください。 - fallbacks は **エラー** 用であり、「難しいタスク」用ではないため、`/model` または別エージェントを使ってください。 + + はい。**MiniMax をデフォルト** にし、必要に応じて **セッション単位** でモデルを切り替えてください。 + Fallbacks は **エラー用** であり、「難しいタスク」用ではないため、`/model` または別の agent を使ってください。 - **オプション A: セッション単位で切り替え** + **Option A: セッション単位で切り替える** ```json5 { @@ -2425,18 +2445,18 @@ x-i18n: /model gpt ``` - **オプション B: 別エージェント** + **Option B: agents を分ける** - Agent A のデフォルト: MiniMax - Agent B のデフォルト: OpenAI - - エージェントごとにルーティングするか、`/agent` で切り替える + - agent ごとにルーティングするか、`/agent` で切り替える ドキュメント: [Models](/ja-JP/concepts/models), [Multi-Agent Routing](/ja-JP/concepts/multi-agent), [MiniMax](/ja-JP/providers/minimax), [OpenAI](/ja-JP/providers/openai). - はい。OpenClaw にはいくつかのデフォルト shorthand が含まれています（`agents.defaults.models` にそのモデルが存在する場合にのみ適用されます）。 + はい。OpenClaw にはいくつかのデフォルト shorthand があります（`agents.defaults.models` にそのモデルが存在する場合にのみ適用されます）: - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2451,8 +2471,8 @@ x-i18n: - - エイリアスは `agents.defaults.models..alias` から取得されます。例: + + Aliases は `agents.defaults.models..alias` から取得されます。例: ```json5 { @@ -2469,11 +2489,11 @@ x-i18n: } ``` - その後、`/model sonnet`（またはサポートされている場合は `/`）でその model ID に解決されます。 + これで `/model sonnet`（またはサポートされている場合は `/`）がその model ID に解決されます。 - + OpenRouter（従量課金、多数のモデル）: ```json5 @@ -2502,119 +2522,120 @@ x-i18n: } ``` - provider/model を参照していても、必要な provider key がない場合は、ランタイム認証エラーになります（例: `No API key found for provider "zai"`）。 + provider/model を参照していても必要な provider key が欠けている場合、ランタイム auth エラーが発生します（例: `No API key found for provider "zai"`）。 - **新しいエージェントを追加したあとに「No API key found for provider」が表示される** + **新しい agent を追加した後に「No API key found for provider」と表示される場合** - これは通常、**新しいエージェント** の auth store が空であることを意味します。auth はエージェントごとで、 - 次に保存されます。 + 通常、これは **新しい agent** の auth store が空であることを意味します。auth はエージェントごとであり、 + 次に保存されます: ``` ~/.openclaw/agents//agent/auth-profiles.json ``` - 修正方法: + 対処方法: - `openclaw agents add ` を実行し、ウィザード中に auth を設定する。 - - または、メインエージェントの `agentDir` から `auth-profiles.json` を新しいエージェントの `agentDir` にコピーする。 + - または、main agent の `agentDir` にある `auth-profiles.json` を新しい agent の `agentDir` にコピーする。 - エージェント間で `agentDir` を使い回しては **いけません**。auth/session の衝突が発生します。 + agents 間で `agentDir` を共有しては**いけません**。auth/session の競合が起こります。 -## モデルのフェイルオーバーと「All models failed」 +## モデルフェイルオーバーと「All models failed」 - フェイルオーバーは 2 段階で発生します。 + フェイルオーバーは2段階で発生します: - 1. 同じ provider 内での **auth profile rotation**。 - 2. `agents.defaults.model.fallbacks` 内の次のモデルへの **model fallback**。 + 1. 同一 provider 内での **auth profile rotation**。 + 2. `agents.defaults.model.fallbacks` にある次のモデルへの **model fallback**。 - 失敗した profiles にはクールダウンが適用されます（指数バックオフ）。そのため、provider がレート制限中または一時的に失敗していても、OpenClaw は応答を継続できます。 + 失敗した profiles にはクールダウン（指数バックオフ）が適用されるため、provider がレート制限中や一時的に失敗している場合でも、OpenClaw は応答を続けられます。 - rate-limit bucket には単純な `429` レスポンス以上のものが含まれます。OpenClaw は + レート制限バケットには、単純な `429` 応答以上のものが含まれます。OpenClaw は `Too many concurrent requests`、 `ThrottlingException`、`concurrency limit reached`、 - `workers_ai ... quota limit exceeded`、`resource exhausted`、および定期的な - usage-window 制限（`weekly/monthly limit reached`）のようなメッセージも - フェイルオーバーに値するレート制限として扱います。 + `workers_ai ... quota limit exceeded`、`resource exhausted`、および周期的な + 使用量ウィンドウ制限（`weekly/monthly limit reached`）のようなメッセージも + フェイルオーバー対象のレート制限として扱います。 - 一見課金関連に見える応答でも `402` ではないことがあり、HTTP `402` - 応答の一部もこの一時的 bucket に留まります。provider が - `401` または `403` で明示的な課金テキストを返した場合、OpenClaw はそれを - 課金レーンに維持できますが、provider 固有のテキストマッチャーはその - provider に限定されたままです（たとえば OpenRouter の `Key limit exceeded`）。`402` - メッセージが、代わりに再試行可能な usage-window や - organization/workspace の利用上限（`daily limit reached, resets tomorrow`、 - `organization spending limit exceeded`）のように見える場合、OpenClaw はそれを - 長期の課金停止ではなく `rate_limit` として扱います。 + 一部の課金っぽい応答は `402` ではなく、一部の HTTP `402` + 応答もその一時的バケットに残ります。provider が + `401` または `403` で明示的な課金テキストを返す場合、OpenClaw はそれを引き続き + billing lane に置くことがありますが、provider 固有のテキストマッチャーは + その provider の範囲内に限定されます（たとえば OpenRouter の `Key limit exceeded`）。`402` + メッセージが代わりに再試行可能な usage-window や + organization/workspace の支出制限（`daily limit reached, resets tomorrow`、 + `organization spending limit exceeded`）に見える場合、OpenClaw はそれを + 長期的な billing disable ではなく `rate_limit` として扱います。 - context overflow エラーは異なります。たとえば + context overflow エラーは別です。たとえば `request_too_large`、`input exceeds the maximum number of tokens`、 `input token count exceeds the maximum number of input tokens`、 `input is too long for the model`、または `ollama error: context length exceeded` といったシグネチャは、model - fallback を進めるのではなく、Compaction/retry 経路に留まります。 + fallback を進める代わりに compaction/retry path に留まります。 - 汎用的な server error テキストは、「unknown/error を含むものすべて」よりも意図的に狭くされています。 - OpenClaw は、Anthropic の素の `An unknown error occurred`、OpenRouter の素の + 一般的なサーバーエラーテキストは、「unknown/error を含むものなら何でも」というほど広くはありません。OpenClaw は + Anthropic の素の `An unknown error occurred`、OpenRouter の素の `Provider returned error`、`Unhandled stop reason: - error` のような stop-reason エラー、JSON の `api_error` ペイロードと一時的なサーバーテキスト + error` のような stop-reason エラー、JSON の `api_error` payload に含まれる一時的サーバーテキスト （`internal server error`、`unknown error, 520`、`upstream error`、`backend error`）、および `ModelNotReadyException` のような provider-busy エラーを、 - provider コンテキストが一致する場合にはフェイルオーバーに値する timeout/overloaded シグナルとして扱います。 + provider context が一致する場合にフェイルオーバー対象の timeout/overloaded シグナルとして扱います。 `LLM request failed with an unknown - error.` のような汎用内部 fallback テキストは慎重に扱われ、それ単体では model fallback を引き起こしません。 + error.` のような一般的な内部 fallback テキストは保守的に扱われ、それ単体では model fallback を引き起こしません。 - - これは、システムが auth profile ID `anthropic:default` を使おうとしたが、想定される auth store 内でその資格情報を見つけられなかったことを意味します。 + + これは、システムが auth profile ID `anthropic:default` を使おうとしたものの、想定される auth store にその認証情報を見つけられなかったことを意味します。 - **修正チェックリスト:** + **確認項目:** - - **auth profiles の保存場所を確認する**（新旧パス） - - 現行: `~/.openclaw/agents//agent/auth-profiles.json` - - レガシー: `~/.openclaw/agent/*`（`openclaw doctor` により移行） + - **auth profiles がどこにあるか確認する**（新旧パス） + - 現在: `~/.openclaw/agents//agent/auth-profiles.json` + - 従来: `~/.openclaw/agent/*`（`openclaw doctor` により移行） - **env var が Gateway に読み込まれていることを確認する** - - `ANTHROPIC_API_KEY` をシェルに設定していても、Gateway を systemd/launchd 経由で動かしている場合は継承されないことがあります。`~/.openclaw/.env` に入れるか、`env.shellEnv` を有効にしてください。 - - **正しいエージェントを編集していることを確認する** - - マルチエージェント構成では、複数の `auth-profiles.json` ファイルが存在し得ます。 - - **model/auth status を健全性確認する** - - `openclaw models status` を使って、設定済みモデルと provider の認証状態を確認してください。 + - `ANTHROPIC_API_KEY` を shell に設定していても、Gateway を systemd/launchd 経由で実行している場合、それを継承しないことがあります。`~/.openclaw/.env` に入れるか `env.shellEnv` を有効にしてください。 + - **正しい agent を編集していることを確認する** + - multi-agent 構成では、複数の `auth-profiles.json` ファイルがあり得ます。 + - **model/auth status を簡易確認する** + - `openclaw models status` を使って、設定済みモデルと provider が認証済みかどうかを確認してください。 - **「No credentials found for profile anthropic」の修正チェックリスト** + **「No credentials found for profile anthropic」の確認項目** - これは、その実行が Anthropic auth profile に固定されているが、Gateway が - 自分の auth store でそれを見つけられないことを意味します。 + これは、その実行が Anthropic の auth profile に固定されているのに、Gateway + が auth store にそれを見つけられないことを意味します。 - **Claude CLI を使う** - - gateway host 上で `openclaw models auth login --provider anthropic --method cli --set-default` を実行してください。 - - **代わりに API key を使いたい場合** - - **gateway host** 上の `~/.openclaw/.env` に `ANTHROPIC_API_KEY` を入れてください。 - - 不足している profile を強制する固定順序をクリアします: + - gateway host 上で `openclaw models auth login --provider anthropic --method cli --set-default` を実行する。 + - **代わりに APIキーを使いたい場合** + - **gateway host** 上の `~/.openclaw/.env` に `ANTHROPIC_API_KEY` を入れる。 + - 存在しない profile を強制する固定順序を解除する: ```bash openclaw models auth order clear --provider anthropic ``` - - **gateway host 上でコマンドを実行していることを確認する** - - remote mode では、auth profiles はローカルノート PC ではなく gateway マシン上にあります。 + - **commands を gateway host 上で実行していることを確認する** + - remote mode では、auth profiles はローカルのノートPCではなく gateway マシン上にあります。 - - モデル設定に Google Gemini が fallback として含まれている場合（または Gemini の shorthand に切り替えた場合）、OpenClaw は model fallback 中にそれも試します。Google の資格情報を設定していないと、`No API key found for provider "google"` が表示されます。 + + model 設定に Google Gemini が fallback として含まれている場合（または Gemini shorthand に切り替えた場合）、OpenClaw は model fallback 中にそれを試します。Google の認証情報を設定していないと、`No API key found for provider "google"` が表示されます。 - 修正方法: Google auth を提供するか、fallback がそこへルーティングしないように `agents.defaults.model.fallbacks` / aliases から Google モデルを削除または回避してください。 + 対処法: Google auth を用意するか、`agents.defaults.model.fallbacks` / aliases から Google models を削除/回避して、fallback がそちらへルーティングしないようにしてください。 - **LLM request rejected: thinking signature required（Google Antigravity）** + **LLM request rejected: thinking signature required (Google Antigravity)** - 原因: セッション履歴に **署名のない thinking blocks** が含まれています（中断された/部分的な stream に由来することが多いです）。Google Antigravity は thinking blocks に署名を要求します。 + 原因: session history に **署名のない thinking blocks** が含まれています（多くは + 中断/部分ストリーム由来）。Google Antigravity では thinking blocks に署名が必要です。 - 修正方法: OpenClaw は現在、Google Antigravity Claude 用に署名のない thinking blocks を除去します。それでも表示される場合は、**新しいセッション** を開始するか、そのエージェントで `/thinking off` を設定してください。 + 対処法: OpenClaw は現在、Google Antigravity Claude 向けに署名なし thinking blocks を除去します。それでも表示される場合は、**新しい session** を開始するか、その agent で `/thinking off` を設定してください。 @@ -2625,7 +2646,7 @@ x-i18n: - auth profile は、provider に紐づく名前付きの資格情報レコード（OAuth または API key）です。profiles は次に保存されます。 + auth profile は、provider に紐づく名前付き認証情報レコード（OAuth または APIキー）です。Profiles は次に保存されます: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2633,62 +2654,64 @@ x-i18n: - - OpenClaw は、次のような provider 接頭辞付き ID を使います。 + + OpenClaw は provider 接頭辞付きの ID を使います。たとえば: - - `anthropic:default`（メールアドレスの識別情報がない場合によく使われる） - - OAuth アイデンティティ用の `anthropic:` - - 自分で選ぶカスタム ID（例: `anthropic:work`） + - `anthropic:default`（メール ID が存在しない場合によく使われる） + - OAuth ID 用の `anthropic:` + - 自分で選んだカスタム ID（例: `anthropic:work`） - はい。設定では、profiles 用の任意メタデータと provider ごとの順序（`auth.order.`）をサポートしています。これは secrets を保存するものではなく、ID を provider/mode に対応付け、rotation 順序を設定します。 + はい。設定では、profiles の任意メタデータと provider ごとの順序（`auth.order.`）をサポートしています。これに secrets は保存されません。ID を provider/mode に対応付け、rotation order を設定するだけです。 - OpenClaw は、その profile が短い **cooldown**（rate limits/timeouts/auth failures）またはより長い **disabled** 状態（billing/insufficient credits）にある場合、一時的にスキップすることがあります。これを確認するには、`openclaw models status --json` を実行して `auth.unusableProfiles` を確認してください。調整項目: `auth.cooldowns.billingBackoffHours*`。 + OpenClaw は、その profile が短い **cooldown**（レート制限/タイムアウト/auth failure）または長めの **disabled** 状態（課金/残高不足）にある場合、一時的にスキップすることがあります。確認するには `openclaw models status --json` を実行し、`auth.unusableProfiles` を見てください。調整項目: `auth.cooldowns.billingBackoffHours*`。 - rate-limit cooldowns はモデル単位になることがあります。あるモデルで cooldown 中の profile でも、同じ provider の兄弟モデルでは利用可能なことがありますが、billing/disabled の期間は profile 全体をブロックします。 + レート制限の cooldown は model 単位になることがあります。ある model で + cooldown 中の profile でも、同じ provider 上の兄弟 model では使用可能なことがあり、 + billing/disabled ウィンドウは引き続き profile 全体をブロックします。 - CLI では、**エージェント単位** の順序 override（そのエージェントの `auth-state.json` に保存）も設定できます。 + CLI では、**エージェント単位** の順序 override（その agent の `auth-state.json` に保存）も設定できます: ```bash - # 設定済みデフォルトエージェントを対象にします（--agent を省略） + # 設定されたデフォルト agent が対象（--agent を省略） openclaw models auth order get --provider anthropic - # rotation を 1 つの profile に固定（これだけを試す） + # rotation を1つの profile に固定（これだけを試す） openclaw models auth order set --provider anthropic anthropic:default - # または明示的な順序を設定（provider 内で fallback） + # または明示的な順序を設定（provider 内 fallback） openclaw models auth order set --provider anthropic anthropic:work anthropic:default # override をクリア（config auth.order / round-robin に戻す） openclaw models auth order clear --provider anthropic ``` - 特定のエージェントを対象にするには: + 特定の agent を対象にするには: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - 実際に何が試されるかを確認するには、次を使ってください。 + 実際に何が試されるか確認するには、次を使ってください: ```bash openclaw models status --probe ``` - 保存済み profile が明示的な順序から省かれている場合、probe は - その profile を黙って試す代わりに `excluded_by_auth_order` を報告します。 + 保存済み profile が明示的順序から外れている場合、probe は + その profile を黙って試すのではなく `excluded_by_auth_order` として報告します。 - - OpenClaw は両方をサポートしています。 + + OpenClaw は両方をサポートしています: - - **OAuth** は、多くの場合サブスクリプションアクセスを活用します（該当する場合）。 - - **API keys** は従量課金を使います。 + - **OAuth** は多くの場合、サブスクリプションアクセスを活用します（該当する場合）。 + - **API keys** は従量課金です。 - ウィザードは Anthropic Claude CLI、OpenAI Codex OAuth、API keys を明示的にサポートしています。 + ウィザードでは Anthropic Claude CLI、OpenAI Codex OAuth、API keys を明示的にサポートしています。 @@ -2697,49 +2720,49 @@ x-i18n: - `gateway.port` は、WebSocket + HTTP（Control UI、hooks など）の単一多重化ポートを制御します。 + `gateway.port` が、WebSocket + HTTP（Control UI、hooks など）の単一多重化ポートを制御します。 優先順位: ``` - --port > OPENCLAW_GATEWAY_PORT > gateway.port > デフォルト 18789 + --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 ``` - - これは、「running」が **supervisor**（launchd/systemd/schtasks）の視点だからです。一方、RPC probe は CLI が実際に gateway WebSocket に接続して `status` を呼び出している結果です。 + + 「running」は **supervisor** の見方（launchd/systemd/schtasks）だからです。RPC probe は、CLI が実際に gateway WebSocket へ接続して `status` を呼び出した結果です。 - `openclaw gateway status` を使い、次の行を信頼してください。 + `openclaw gateway status` を使い、次の行を信頼してください: - `Probe target:`（probe が実際に使った URL） - - `Listening:`（実際にそのポートで bind されているもの） + - `Listening:`（実際にそのポートで bind しているもの） - `Last gateway error:`（プロセスは生きているがポートが listen していないときの一般的な根本原因） - + 編集している設定ファイルと、service が実行している設定ファイルが異なっています（多くは `--profile` / `OPENCLAW_STATE_DIR` の不一致です）。 - 修正: + 対処法: ```bash openclaw gateway install --force ``` - これを、service に使わせたい同じ `--profile` / 環境で実行してください。 + service に使わせたいのと同じ `--profile` / environment でこれを実行してください。 - - OpenClaw は、起動時に即座に WebSocket listener を bind することでランタイムロックを強制します（デフォルト `ws://127.0.0.1:18789`）。`EADDRINUSE` で bind に失敗した場合、別のインスタンスがすでに listen していることを示す `GatewayLockError` を投げます。 + + OpenClaw は、起動時にただちに WebSocket listener を bind することでランタイムロックを強制します（デフォルトは `ws://127.0.0.1:18789`）。この bind が `EADDRINUSE` で失敗すると、別のインスタンスがすでに listen していることを示す `GatewayLockError` を投げます。 - 修正: 他のインスタンスを停止する、ポートを解放する、または `openclaw gateway --port ` で実行してください。 + 対処法: 他方のインスタンスを停止する、ポートを解放する、または `openclaw gateway --port ` で実行してください。 - - `gateway.mode: "remote"` を設定し、リモートの WebSocket URL を指定します。必要に応じて shared-secret のリモート資格情報も指定できます。 + + `gateway.mode: "remote"` を設定し、必要に応じて shared-secret remote credentials とともに remote WebSocket URL を指定してください: ```json5 { @@ -2754,100 +2777,100 @@ x-i18n: } ``` - 注意: + 注意点: - - `openclaw gateway` は `gateway.mode` が `local` のときにのみ起動します（または override フラグを渡した場合）。 - - macOS アプリは設定ファイルを監視しており、これらの値が変わるとモードをライブで切り替えます。 - - `gateway.remote.token` / `.password` はクライアント側のリモート資格情報専用であり、それ自体でローカル gateway auth を有効にするものではありません。 + - `openclaw gateway` が起動するのは `gateway.mode` が `local` のときだけです（または override flag を渡した場合）。 + - macOS アプリは設定ファイルを監視しており、これらの値が変わると live でモードを切り替えます。 + - `gateway.remote.token` / `.password` はクライアント側の remote credentials のみであり、それ自体では local gateway auth を有効にしません。 - - gateway の auth 経路と UI の auth 方法が一致していません。 + + gateway の auth path と UI の auth method が一致していません。 - 事実（コード上の挙動）: + 事実（コードベース）: - - Control UI は、現在のブラウザータブセッションと選択中の gateway URL に対して token を `sessionStorage` に保持するため、同一タブ内の再読み込みは長期的な `localStorage` token 永続化を復元しなくても動作し続けます。 - - `AUTH_TOKEN_MISMATCH` 時には、gateway が再試行ヒント（`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`）を返した場合、信頼済みクライアントはキャッシュ済み device token で 1 回だけ制限付き再試行を行えます。 - - そのキャッシュトークン再試行では、device token とともに保存されたキャッシュ済みの承認 scopes も再利用されます。明示的な `deviceToken` / 明示的な `scopes` 呼び出し元は、キャッシュ scope を継承せず、要求した scope セットを維持します。 - - その再試行経路以外では、connect auth の優先順位は、明示的な shared token/password が最優先で、その次に明示的な `deviceToken`、次に保存済み device token、最後に bootstrap token です。 - - bootstrap token の scope チェックは role 接頭辞付きです。組み込みの bootstrap operator allowlist は operator 要求にしか対応せず、Node やその他の非 operator ロールでは、それぞれの role 接頭辞配下の scopes が依然として必要です。 + - Control UI は、現在のブラウザータブの session と選択された gateway URL に対して token を `sessionStorage` に保持するため、同じタブ内でのリフレッシュは、長期的な localStorage token 永続化を復元しなくても機能し続けます。 + - `AUTH_TOKEN_MISMATCH` の場合、trusted clients は、gateway が retry hint（`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`）を返したとき、キャッシュされた device token で1回だけ制限付きリトライを試みることができます。 + - その cached-token retry は、現在では device token とともに保存されたキャッシュ済みの approved scopes を再利用します。明示的な `deviceToken` / 明示的な `scopes` の呼び出し側は、キャッシュされた scopes を継承せず、自身が要求した scope set を維持します。 + - その retry path の外では、connect auth の優先順位は、明示的な shared token/password、次に明示的な `deviceToken`、次に保存済み device token、最後に bootstrap token です。 + - Bootstrap token の scope チェックは role 接頭辞付きです。組み込みの bootstrap operator allowlist は operator request にしか適用されず、node や他の non-operator roles には、自身の role prefix 配下の scopes が引き続き必要です。 - 修正方法: + 対処法: - - 最速: `openclaw dashboard`（ダッシュボード URL を表示 + コピーし、開こうとします。headless なら SSH ヒントも表示）。 + - 最速: `openclaw dashboard`（dashboard URL を表示 + コピーし、開こうとします。headless なら SSH ヒントを表示）。 - まだ token がない場合: `openclaw doctor --generate-gateway-token`。 - - remote の場合は、まずトンネルします: `ssh -N -L 18789:127.0.0.1:18789 user@host` のあと `http://127.0.0.1:18789/` を開いてください。 - - shared-secret mode: `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` または `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` を設定し、その一致する secret を Control UI 設定に貼り付けてください。 - - Tailscale Serve mode: `gateway.auth.allowTailscale` が有効であること、そして Tailscale の identity headers を迂回する生の loopback/tailnet URL ではなく Serve URL を開いていることを確認してください。 - - trusted-proxy mode: 同一ホストの loopback proxy や生の gateway URL ではなく、設定済みの non-loopback identity-aware proxy を経由していることを確認してください。 - - 1 回の再試行後も不一致が続く場合は、ペアリング済み device token をローテーション/再承認します: + - remote の場合は、まずトンネルします: `ssh -N -L 18789:127.0.0.1:18789 user@host` を実行してから `http://127.0.0.1:18789/` を開く。 + - shared-secret mode: `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` または `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` を設定し、その matching secret を Control UI settings に貼り付ける。 + - Tailscale Serve mode: `gateway.auth.allowTailscale` が有効であり、Tailscale identity headers を迂回する raw loopback/tailnet URL ではなく Serve URL を開いていることを確認する。 + - trusted-proxy mode: same-host loopback proxy や raw gateway URL ではなく、設定された non-loopback の identity-aware proxy を通っていることを確認する。 + - 1回の retry 後も不一致が続く場合は、paired device token を rotate/re-approve する: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - その rotate 呼び出しが拒否されたと言う場合は、次の 2 点を確認してください: - - ペアリング済みデバイスセッションは、自分自身のデバイスだけをローテーションできます（`operator.admin` も持っている場合を除く） - - 明示的な `--scope` 値は、呼び出し元の現在の operator scopes を超えられません - - それでもだめなら、`openclaw status --all` を実行して [Troubleshooting](/ja-JP/gateway/troubleshooting) に従ってください。auth の詳細は [Dashboard](/web/dashboard) を参照してください。 + - その rotate call が denied だった場合は、次の2点を確認する: + - paired-device sessions が rotate できるのは、自分自身の device のみです。ただし `operator.admin` を持つ場合は別です + - 明示的な `--scope` 値は、呼び出し元の現在の operator scopes を超えることはできません + - まだ解決しない場合は、`openclaw status --all` を実行し、[トラブルシューティング](/ja-JP/gateway/troubleshooting) に従ってください。auth の詳細は [Dashboard](/web/dashboard) を参照してください。 - - `tailnet` bind は、ネットワークインターフェースから Tailscale IP（100.64.0.0/10）を選びます。マシンが Tailscale に参加していない（またはインターフェースがダウンしている）場合、bind 先がありません。 + + `tailnet` bind は、ネットワークインターフェイスから Tailscale IP（100.64.0.0/10）を選びます。マシンが Tailscale に参加していない（またはインターフェイスが down している）場合、bind 先がありません。 - 修正: + 対処法: - そのホストで Tailscale を起動する（100.x アドレスを持つようにする）、または - `gateway.bind: "loopback"` / `"lan"` に切り替える。 - 注意: `tailnet` は明示指定です。`auto` は loopback を優先します。tailnet のみに bind したい場合は `gateway.bind: "tailnet"` を使ってください。 + 注意: `tailnet` は明示的です。`auto` は loopback を優先します。tailnet 専用 bind にしたい場合は `gateway.bind: "tailnet"` を使ってください。 - 通常はできません。1 つの Gateway で複数のメッセージングチャネルとエージェントを実行できます。複数の Gateways を使うのは、冗長性（例: rescue bot）や厳格な分離が必要な場合だけです。 + 通常はできません。1つの Gateway で複数のメッセージングチャネルと agents を実行できます。複数の Gateways を使うのは、冗長性（例: rescue bot）または強い分離が必要な場合だけです。 - 可能ではありますが、次を分離する必要があります。 + ただし、次を分離すれば可能です: - `OPENCLAW_CONFIG_PATH`（インスタンスごとの設定） - - `OPENCLAW_STATE_DIR`（インスタンスごとの state） + - `OPENCLAW_STATE_DIR`（インスタンスごとの状態） - `agents.defaults.workspace`（workspace の分離） - - `gateway.port`（一意のポート） + - `gateway.port`（一意なポート） クイックセットアップ（推奨）: - インスタンスごとに `openclaw --profile ...` を使う（`~/.openclaw-` を自動作成）。 - - 各 profile 設定で一意の `gateway.port` を設定する（または手動実行なら `--port` を渡す）。 + - 各 profile 設定で一意の `gateway.port` を設定する（または手動実行時に `--port` を渡す）。 - profile ごとの service をインストールする: `openclaw --profile gateway install`。 - Profiles は service 名にも suffix を付けます（`ai.openclaw.`、レガシーの `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 + Profiles は service 名にも接尾辞を付けます（`ai.openclaw.`、従来の `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`）。 完全なガイド: [Multiple gateways](/ja-JP/gateway/multiple-gateways)。 - - Gateway は **WebSocket サーバー** であり、最初のメッセージが - `connect` フレームであることを期待しています。これ以外を受け取ると、接続を - **code 1008**（ポリシー違反）で閉じます。 + + Gateway は **WebSocket server** であり、最初のメッセージとして + `connect` frame が来ることを期待しています。それ以外を受信すると、 + **code 1008**（policy violation）で接続を閉じます。 よくある原因: - - ブラウザーで **HTTP** URL（`http://...`）を開いた。WS クライアントではない。 - - ポートまたはパスが間違っている。 - - proxy や tunnel が auth headers を削除した、または非 Gateway リクエストを送信した。 + - ブラウザーで **HTTP** URL（`http://...`）を開いたが、WS client ではなかった。 + - 間違ったポートまたは path を使った。 + - proxy や tunnel が auth headers を取り除いた、または非Gateway request を送った。 - すぐできる修正: + すぐできる対処法: - 1. WS URL を使う: `ws://:18789`（HTTPS なら `wss://...`）。 - 2. WS ポートを通常のブラウザータブで開かない。 - 3. auth が有効なら、`connect` フレームに token/password を含める。 + 1. WS URL を使う: `ws://:18789`（HTTPS の場合は `wss://...`）。 + 2. 通常のブラウザータブで WS ポートを開かない。 + 3. auth が有効なら、`connect` frame に token/password を含める。 - CLI または TUI を使っている場合、URL は次のようになります。 + CLI または TUI を使っている場合、URL は次のようになります: ``` openclaw tui --url ws://:18789 --token ``` - プロトコル詳細: [Gateway protocol](/ja-JP/gateway/protocol)。 + プロトコルの詳細: [Gateway protocol](/ja-JP/gateway/protocol)。 @@ -2862,7 +2885,7 @@ x-i18n: /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - 安定したパスは `logging.file` で設定できます。ファイルログレベルは `logging.level` で制御します。コンソールの詳細度は `--verbose` と `logging.consoleLevel` で制御します。 + 安定したパスは `logging.file` で設定できます。ファイルログレベルは `logging.level` で制御されます。コンソールの詳細度は `--verbose` と `logging.consoleLevel` で制御されます。 最速のログ追跡: @@ -2870,18 +2893,18 @@ x-i18n: openclaw logs --follow ``` - service/supervisor ログ（gateway が launchd/systemd 経由で動いている場合）: + service/supervisor ログ（gateway が launchd/systemd 経由で動作している場合）: - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` と `gateway.err.log`（デフォルト: `~/.openclaw/logs/...`、profiles では `~/.openclaw-/logs/...`） - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - 詳しくは [Troubleshooting](/ja-JP/gateway/troubleshooting) を参照してください。 + 詳しくは [トラブルシューティング](/ja-JP/gateway/troubleshooting) を参照してください。 - - gateway ヘルパーを使ってください。 + + gateway helper を使用してください: ```bash openclaw gateway status @@ -2893,11 +2916,11 @@ x-i18n: - Windows には **2 つのインストールモード** があります。 + Windows には **2つのインストールモード** があります: **1) WSL2（推奨）:** Gateway は Linux 内で動作します。 - PowerShell を開いて WSL に入り、その後再起動します: + PowerShell を開き、WSL に入ってから再起動します: ```powershell wsl @@ -2905,7 +2928,7 @@ x-i18n: openclaw gateway restart ``` - service をインストールしていない場合は、フォアグラウンドで起動します。 + service を一度もインストールしていない場合は、foreground で起動します: ```bash openclaw gateway run @@ -2920,7 +2943,7 @@ x-i18n: openclaw gateway restart ``` - 手動で実行している場合（service なし）は、次を使います。 + 手動実行（service なし）の場合は、次を使います: ```powershell openclaw gateway run @@ -2931,7 +2954,7 @@ x-i18n: - まず簡単な健全性チェックから始めてください。 + まず簡単なヘルス確認から始めてください: ```bash openclaw status @@ -2942,56 +2965,56 @@ x-i18n: よくある原因: - - **gateway host** 上で model auth が読み込まれていない（`models status` を確認）。 - - channel pairing/allowlist により返信がブロックされている（channel 設定 + ログを確認）。 + - **gateway host** で model auth が読み込まれていない（`models status` を確認）。 + - channel pairing/allowlist が返信をブロックしている（channel 設定 + ログを確認）。 - WebChat/Dashboard が正しい token なしで開かれている。 remote の場合は、tunnel/Tailscale 接続が有効であり、 Gateway WebSocket に到達できることを確認してください。 - ドキュメント: [Channels](/ja-JP/channels), [Troubleshooting](/ja-JP/gateway/troubleshooting), [Remote access](/ja-JP/gateway/remote)。 + ドキュメント: [Channels](/ja-JP/channels), [トラブルシューティング](/ja-JP/gateway/troubleshooting), [Remote access](/ja-JP/gateway/remote)。 - - これは通常、UI が WebSocket 接続を失ったことを意味します。次を確認してください。 + + これは通常、UI が WebSocket 接続を失ったことを意味します。次を確認してください: 1. Gateway は動作していますか？ `openclaw gateway status` - 2. Gateway は健全ですか？ `openclaw status` + 2. Gateway は正常ですか？ `openclaw status` 3. UI は正しい token を持っていますか？ `openclaw dashboard` 4. remote の場合、tunnel/Tailscale 接続は有効ですか？ - その後、ログを追跡してください。 + その後、ログを追跡してください: ```bash openclaw logs --follow ``` - ドキュメント: [Dashboard](/web/dashboard), [Remote access](/ja-JP/gateway/remote), [Troubleshooting](/ja-JP/gateway/troubleshooting)。 + ドキュメント: [Dashboard](/web/dashboard), [Remote access](/ja-JP/gateway/remote), [トラブルシューティング](/ja-JP/gateway/troubleshooting)。 - まずログと channel status を確認してください。 + まずログと channel status を確認してください: ```bash openclaw channels status openclaw channels logs --channel telegram ``` - その後、エラーに応じて確認します。 + その後、エラーに対応してください: - - `BOT_COMMANDS_TOO_MUCH`: Telegram メニューのエントリが多すぎます。OpenClaw はすでに Telegram の上限まで削って少ないコマンドで再試行しますが、それでも一部のメニュー項目は削除が必要です。plugin/skill/custom commands を減らすか、メニューが不要なら `channels.telegram.commands.native` を無効にしてください。 - - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!`、または類似のネットワークエラー: VPS 上または proxy の背後にいる場合は、外向き HTTPS が許可されていて `api.telegram.org` の DNS が正しく動くことを確認してください。 + - `BOT_COMMANDS_TOO_MUCH`: Telegram メニューの項目数が多すぎます。OpenClaw はすでに Telegram の上限に合わせて削減し、より少ないコマンドで再試行しますが、それでもいくつかのメニュー項目は削除が必要です。plugin/skill/custom commands を減らすか、メニューが不要なら `channels.telegram.commands.native` を無効にしてください。 + - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!`、または類似のネットワークエラー: VPS 上または proxy の背後にいる場合は、`api.telegram.org` への外向き HTTPS が許可されていて DNS が機能していることを確認してください。 - Gateway がリモートにある場合は、Gateway host 上のログを見ていることを確認してください。 + Gateway が remote の場合は、Gateway host 上のログを見ていることを確認してください。 ドキュメント: [Telegram](/ja-JP/channels/telegram), [Channel troubleshooting](/ja-JP/channels/troubleshooting)。 - - まず Gateway に到達でき、agent が実行できることを確認してください。 + + まず Gateway に到達でき、agent が実行できることを確認してください: ```bash openclaw status @@ -2999,14 +3022,14 @@ x-i18n: openclaw logs --follow ``` - TUI では `/status` を使って現在の状態を確認します。chat - channel で返信を期待している場合は、配信が有効になっていること（`/deliver on`）を確認してください。 + TUI では、`/status` を使って現在の状態を確認します。チャット + channel に返信が届くことを期待している場合は、配信が有効（`/deliver on`）であることを確認してください。 ドキュメント: [TUI](/web/tui), [Slash commands](/ja-JP/tools/slash-commands)。 - + service をインストールしている場合: ```bash @@ -3014,38 +3037,38 @@ x-i18n: openclaw gateway start ``` - これは **監視付き service**（macOS では launchd、Linux では systemd）を停止/開始します。 - Gateway がデーモンとしてバックグラウンド実行されている場合に使ってください。 + これにより **supervised service**（macOS では launchd、Linux では systemd）を停止/起動します。 + Gateway をバックグラウンドのデーモンとして動かしている場合に使ってください。 - フォアグラウンドで実行している場合は、Ctrl-C で停止してから次を実行します。 + foreground で実行している場合は、Ctrl-C で停止してから次を実行してください: ```bash openclaw gateway run ``` - ドキュメント: [Gateway service runbook](/ja-JP/gateway)。 + ドキュメント: [Gateway service runbook](/ja-JP/gateway). - + - `openclaw gateway restart`: **バックグラウンド service**（launchd/systemd）を再起動します。 - - `openclaw gateway`: このターミナルセッションで gateway を **フォアグラウンド** 実行します。 + - `openclaw gateway`: このターミナル session 用に gateway を **foreground** で実行します。 - service をインストールしている場合は gateway コマンド群を使ってください。`openclaw gateway` は - 一時的にフォアグラウンド実行したいときに使います。 + service をインストールしている場合は gateway commands を使ってください。一時的に foreground で実行したいときは + `openclaw gateway` を使ってください。 - - より詳しいコンソール出力を得るには、Gateway を `--verbose` 付きで起動してください。その後、ログファイルを確認して channel auth、model routing、RPC エラーを調べてください。 + + Gateway を `--verbose` 付きで起動すると、コンソールにより詳しい情報が出ます。その後、ログファイルを確認して channel auth、model routing、RPC errors を調べてください。 ## メディアと添付ファイル - - agent からの送信添付ファイルには、`MEDIA:` 行（単独行）が必要です。[OpenClaw assistant setup](/ja-JP/start/openclaw) と [Agent send](/ja-JP/tools/agent-send) を参照してください。 + + agent からの送信添付ファイルには、`MEDIA:` 行を含める必要があります（単独の行として）。[OpenClaw assistant setup](/ja-JP/start/openclaw) と [Agent send](/ja-JP/tools/agent-send) を参照してください。 CLI で送信する場合: @@ -3053,12 +3076,12 @@ x-i18n: openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png ``` - あわせて次も確認してください。 + 次も確認してください: - - 対象 channel が送信メディアをサポートしており、allowlist によってブロックされていないこと。 - - ファイルが provider のサイズ上限内であること（画像は最大 2048px にリサイズされます）。 - - `tools.fs.workspaceOnly=true` の場合、ローカルパス送信は workspace、temp/media-store、および sandbox 検証済みファイルに制限されます。 - - `tools.fs.workspaceOnly=false` の場合、agent がすでに読めるホストローカルファイルを `MEDIA:` で送信できますが、対象はメディア + 安全な文書タイプ（画像、音声、動画、PDF、Office 文書）に限られます。プレーンテキストや secret のようなファイルは引き続きブロックされます。 + - 対象 channel が送信メディアをサポートしており、allowlists によってブロックされていないこと。 + - ファイルが provider のサイズ制限内であること（画像は最大 2048px にリサイズされます）。 + - `tools.fs.workspaceOnly=true` では、ローカルパス送信は workspace、temp/media-store、および sandbox で検証済みのファイルに制限されます。 + - `tools.fs.workspaceOnly=false` では、agent がすでに読めるホストローカルファイルを `MEDIA:` で送信できますが、対象はメディアと安全なドキュメント型（画像、音声、動画、PDF、Office ドキュメント）に限られます。プレーンテキストや secret らしいファイルは引き続きブロックされます。 [Images](/ja-JP/nodes/images) を参照してください。 @@ -3069,71 +3092,72 @@ x-i18n: - 受信 DM は信頼できない入力として扱ってください。デフォルトはリスク低減を意図したものです。 + 受信 DM は信頼できない入力として扱ってください。デフォルトはリスク低減を意図しています: - - DM 対応チャネルでのデフォルト動作は **pairing** です: - - 未知の送信者には pairing code が送られ、ボットはそのメッセージを処理しません。 + - DM 対応 channels のデフォルト動作は **pairing** です: + - 未知の送信者には pairing code が返され、bot はそのメッセージを処理しません。 - 承認方法: `openclaw pairing approve --channel [--account ] ` - - 保留中リクエストは **チャネルごとに 3 件** までです。コードが届かない場合は `openclaw pairing list --channel [--account ]` を確認してください。 - - DM を公開で開放するには、明示的な opt-in（`dmPolicy: "open"` と allowlist `"*"`）が必要です。 + - 保留中リクエストは **1チャネルあたり3件** までです。コードが届かなかった場合は `openclaw pairing list --channel [--account ]` を確認してください。 + - DM を公に開放するには、明示的なオプトインが必要です（`dmPolicy: "open"` と allowlist `"*"`）。 - 危険な DM ポリシーを見つけるには `openclaw doctor` を実行してください。 + リスクの高い DM policies を確認するには `openclaw doctor` を実行してください。 - - いいえ。prompt injection は、誰がボットに DM できるかではなく、**信頼できないコンテンツ** の問題です。 - アシスタントが外部コンテンツ（web search/fetch、browser ページ、メール、 - ドキュメント、添付ファイル、貼り付けられたログ）を読む場合、その内容には - モデルを乗っ取ろうとする指示が含まれている可能性があります。これは **送信者が自分だけ** の場合でも起こり得ます。 + + いいえ。prompt injection は **信頼できないコンテンツ** に関する問題であり、bot に DM できる相手だけの問題ではありません。 + assistant が外部コンテンツ（web search/fetch、browser pages、emails、 + docs、attachments、貼り付けられた logs）を読むなら、そのコンテンツには + モデルを乗っ取ろうとする命令が含まれている可能性があります。これは **送信者が自分だけの場合でも** + 起こり得ます。 最大のリスクは tools が有効なときです。モデルがだまされて - コンテキストを流出させたり、自分の代わりに tools を呼び出したりする可能性があります。影響範囲を減らすには: + コンテキストを持ち出したり、あなたの代わりに tools を呼び出したりする可能性があります。影響範囲を減らすには: - - 信頼できないコンテンツを要約するために、読み取り専用または tool 無効の「reader」agent を使う - - tool 対応エージェントでは `web_search` / `web_fetch` / `browser` をオフに保つ - - デコードされたファイル/文書テキストも信頼しないこと: OpenResponses の - `input_file` とメディア添付の抽出はどちらも、生のファイルテキストを渡す代わりに、 - 抽出テキストを明示的な外部コンテンツ境界マーカーで囲みます - - サンドボックス化と厳格な tool allowlists + - 信頼できないコンテンツを要約するために、読み取り専用または tools 無効の「reader」agent を使う + - tools 対応 agents では `web_search` / `web_fetch` / `browser` を無効にする + - デコード済みファイル/ドキュメントテキストも信頼できないものとして扱う: OpenResponses + `input_file` と media-attachment extraction はどちらも、抽出テキストを生のファイルテキストとして渡す代わりに、 + 明示的な external-content boundary markers で包みます + - sandboxing と厳格な tool allowlists を使う 詳細: [Security](/ja-JP/gateway/security)。 - - はい。ほとんどのセットアップではそうすべきです。ボットを別アカウントや別番号で分離すると、 - 何か問題が起きたときの影響範囲を減らせます。また、個人アカウントに影響を与えずに - 資格情報のローテーションやアクセス取り消しもしやすくなります。 + + はい。多くのセットアップではその方がよいです。bot を別アカウントや別番号で分離すると、 + 何か問題が起きたときの影響範囲を減らせます。これにより、 + 個人アカウントに影響を与えずに認証情報をローテーションしたり、アクセスを取り消したりしやすくなります。 - まずは小さく始めてください。実際に必要な tools とアカウントにだけアクセスを与え、 + 小さく始めてください。本当に必要な tools と accounts にだけアクセスを与え、 必要に応じて後から拡張してください。 ドキュメント: [Security](/ja-JP/gateway/security), [Pairing](/ja-JP/channels/pairing)。 - - 個人メッセージに対する完全な自律性は **推奨しません**。最も安全なパターンは次のとおりです。 + + 個人メッセージに対する完全な自律性は**推奨しません**。最も安全なパターンは次のとおりです: - - DM は **pairing mode** または厳しい allowlist に保つ。 - - 代わりに送信させたいなら、**別の番号またはアカウント** を使う。 - - 下書きさせてから、**送信前に承認する**。 + - DM は **pairing mode** または厳格な allowlist に保つ。 + - 代理送信させたいなら **別の番号またはアカウント** を使う。 + - 下書きはさせても、**送信前に承認する**。 - 試したい場合は、専用アカウントで行い、分離を保ってください。[Security](/ja-JP/gateway/security) を参照してください。 + 試したい場合は、専用アカウントで行い、分離を維持してください。[Security](/ja-JP/gateway/security) を参照してください。 - - はい。ただし、エージェントがチャット専用で、入力が信頼できる場合に限ります。小さいティアは - 指示の乗っ取りを受けやすいため、tool 対応エージェントや + + はい。agent がチャット専用で、入力が信頼できるなら **可能** です。より小さい tier は + 命令乗っ取りを受けやすいため、tools 対応 agents や 信頼できないコンテンツを読む場合には避けてください。どうしても小さいモデルを使うなら、 - tools を厳しく制限し、サンドボックス内で実行してください。[Security](/ja-JP/gateway/security) を参照してください。 + tools を厳格に制限し、sandbox 内で実行してください。[Security](/ja-JP/gateway/security) を参照してください。 - pairing code は、未知の送信者がボットにメッセージを送り、 - `dmPolicy: "pairing"` が有効な場合に **のみ** 送られます。`/start` だけではコードは生成されません。 + pairing code は、未知の送信者が bot にメッセージを送り、 + `dmPolicy: "pairing"` が有効な場合に**のみ**送信されます。`/start` だけではコードは生成されません。 保留中リクエストを確認してください: @@ -3141,27 +3165,26 @@ x-i18n: openclaw pairing list telegram ``` - すぐにアクセスしたい場合は、自分の sender id を allowlist に入れるか、そのアカウントの `dmPolicy: "open"` - を設定してください。 + すぐにアクセスしたい場合は、自分の sender id を allowlist に追加するか、その account の `dmPolicy: "open"` を設定してください。 - - いいえ。WhatsApp DM のデフォルトポリシーは **pairing** です。未知の送信者には pairing code だけが送られ、そのメッセージは **処理されません**。OpenClaw は、受信したチャットか、自分が明示的にトリガーした送信にしか返信しません。 + + いいえ。デフォルトの WhatsApp DM policy は **pairing** です。未知の送信者には pairing code だけが返され、そのメッセージは **処理されません**。OpenClaw が返信するのは、受信したチャットまたはあなたが明示的にトリガーした送信だけです。 - pairing の承認方法: + pairing を承認するには: ```bash openclaw pairing approve whatsapp ``` - 保留中リクエストの一覧: + 保留中リクエストを一覧表示するには: ```bash openclaw pairing list whatsapp ``` - ウィザードの電話番号プロンプトは、自分自身の **allowlist/owner** を設定するために使われます。自動送信用ではありません。個人の WhatsApp 番号で動かす場合は、その番号を使い、`channels.whatsapp.selfChatMode` を有効にしてください。 + ウィザードの電話番号プロンプトは、あなた自身の **allowlist/owner** を設定して自分の DM を許可するために使われます。自動送信用ではありません。個人の WhatsApp 番号で運用する場合は、その番号を使い、`channels.whatsapp.selfChatMode` を有効にしてください。 @@ -3170,7 +3193,8 @@ x-i18n: - 内部メッセージや tool メッセージのほとんどは、そのセッションで **verbose**、**trace**、または **reasoning** が有効な場合にのみ表示されます。 + ほとんどの内部メッセージや tool メッセージは、その session で **verbose**、**trace**、または **reasoning** が有効な場合にのみ + 表示されます。 表示されているチャットで次を実行してください: @@ -3180,16 +3204,16 @@ x-i18n: /reasoning off ``` - それでもうるさい場合は、Control UI のセッション設定を確認して verbose を - **inherit** にしてください。また、設定で `verboseDefault` が - `on` に設定された bot profile を使っていないことも確認してください。 + それでもうるさい場合は、Control UI の session settings を確認し、verbose を + **inherit** にしてください。また、config の bot profile で `verboseDefault` が + `on` に設定されていないことも確認してください。 - ドキュメント: [Thinking and verbose](/ja-JP/tools/thinking), [Security](/ja-JP/gateway/security#reasoning-verbose-output-in-groups). + ドキュメント: [Thinking and verbose](/ja-JP/tools/thinking), [Security](/ja-JP/gateway/security#reasoning-verbose-output-in-groups)。 - - 次のいずれかを **単独メッセージとして** 送信してください（スラッシュなし）。 + + 次のいずれかを **単独メッセージ** として送信してください（スラッシュなし）: ``` stop @@ -3213,25 +3237,25 @@ x-i18n: interrupt ``` - これらは中断トリガーです（スラッシュコマンドではありません）。 + これらは abort trigger です（slash command ではありません）。 - バックグラウンドプロセス（exec tool 由来）の場合、agent に次の実行を依頼できます。 + バックグラウンドプロセス（exec tool 由来）の場合は、agent に次を実行するよう依頼できます: ``` process action:kill sessionId:XXX ``` - スラッシュコマンド概要: [Slash commands](/ja-JP/tools/slash-commands) を参照してください。 + Slash commands の概要: [Slash commands](/ja-JP/tools/slash-commands) を参照してください。 - 多くのコマンドは `/` で始まる **単独メッセージ** として送信する必要がありますが、一部のショートカット（`/status` など）は allowlist 済み送信者なら文中でも機能します。 + ほとんどのコマンドは `/` で始まる **単独メッセージ** として送る必要がありますが、一部のショートカット（`/status` など）は allowlisted senders に対してはインラインでも動作します。 - - OpenClaw はデフォルトで **クロスプロバイダ** メッセージングをブロックします。tool 呼び出しが + + OpenClaw はデフォルトで **cross-provider** messaging をブロックします。tool call が Telegram にバインドされている場合、明示的に許可しない限り Discord には送信されません。 - エージェントでクロスプロバイダメッセージングを有効にします。 + agent に対して cross-provider messaging を有効にしてください: ```json5 { @@ -3246,20 +3270,20 @@ x-i18n: } ``` - 設定編集後に gateway を再起動してください。 + config を編集したら gateway を再起動してください。 - - queue mode は、新しいメッセージが進行中の実行とどう相互作用するかを制御します。モード変更には `/queue` を使ってください。 + + queue mode が、新しいメッセージと進行中の run の相互作用を制御します。mode の変更には `/queue` を使ってください: - `steer` - 新しいメッセージが現在のタスクを方向転換する - - `followup` - メッセージを 1 つずつ順に実行する - - `collect` - メッセージをまとめて 1 回だけ返信する（デフォルト） - - `steer-backlog` - 今すぐ方向転換し、その後バックログを処理する - - `interrupt` - 現在の実行を中断して新規開始する + - `followup` - メッセージを1つずつ実行する + - `collect` - メッセージをまとめて1回返信する（デフォルト） + - `steer-backlog` - 今すぐ方向転換し、その後 backlog を処理する + - `interrupt` - 現在の run を中断して新しく開始する - followup モードでは `debounce:2s cap:25 drop:summarize` のようなオプションも追加できます。 + followup modes では `debounce:2s cap:25 drop:summarize` のようなオプションも追加できます。 @@ -3267,8 +3291,8 @@ x-i18n: ## その他 - - OpenClaw では、資格情報とモデル選択は別です。`ANTHROPIC_API_KEY` を設定する（または auth profiles に Anthropic API key を保存する）と認証は有効になりますが、実際のデフォルトモデルは `agents.defaults.model.primary` に設定したものです（たとえば `anthropic/claude-sonnet-4-6` または `anthropic/claude-opus-4-6`）。`No credentials found for profile "anthropic:default"` と表示される場合、それは実行中のエージェントに対する想定 `auth-profiles.json` に Anthropic 資格情報を Gateway が見つけられなかったことを意味します。 + + OpenClaw では、認証情報とモデル選択は別です。`ANTHROPIC_API_KEY` を設定する（または auth profiles に Anthropic APIキーを保存する）と認証は有効になりますが、実際のデフォルトモデルは `agents.defaults.model.primary` に設定したものです（たとえば `anthropic/claude-sonnet-4-6` や `anthropic/claude-opus-4-6`）。`No credentials found for profile "anthropic:default"` と表示される場合は、その agent に対する想定 `auth-profiles.json` 内で Anthropic 認証情報を Gateway が見つけられなかったことを意味します。 diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index 22c5a315c..005928a73 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -1,118 +1,119 @@ --- read_when: - - ローカルまたはCIでテストを実行する + - ローカルまたは CI でテストを実行する - モデル/プロバイダーのバグに対するリグレッションテストを追加する - - Gateway + agentの動作をデバッグする -summary: 'テストキット: unit/e2e/liveスイート、Dockerランナー、および各テストがカバーする内容' + - Gateway + agent の挙動をデバッグする +summary: 'テストキット: unit/e2e/live スイート、Docker ランナー、および各テストがカバーする内容' title: テスト x-i18n: - generated_at: "2026-04-18T04:40:08Z" + generated_at: "2026-04-20T04:46:32Z" model: gpt-5.4 provider: openai - source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a + source_hash: 88457038e2e2c7940d0348762d0ece187111a8c61fa9bad54b39eade4217ddbc source_path: help/testing.md workflow: 15 --- # テスト -OpenClawには3つのVitestスイート（unit/integration、e2e、live）と、少数のDockerランナーがあります。 +OpenClaw には 3 つの Vitest スイート（unit/integration、e2e、live）と、小規模な Docker ランナー群があります。 -このドキュメントは「OpenClawでどのようにテストするか」のガイドです。 +このドキュメントは「どのようにテストするか」のガイドです。 -- 各スイートが何をカバーするか（そして意図的に _何をカバーしないか_） -- 一般的なワークフロー（ローカル、push前、デバッグ）でどのコマンドを実行するか -- liveテストがどのように認証情報を見つけ、モデル/プロバイダーを選択するか -- 実際のモデル/プロバイダーの問題に対するリグレッションをどのように追加するか +- 各スイートが何をカバーするか（そして意図的に _カバーしない_ ものは何か） +- 一般的なワークフロー（ローカル、push 前、デバッグ）でどのコマンドを実行するか +- live テストがどのように認証情報を見つけ、モデル/プロバイダーを選択するか +- 実運用で発生したモデル/プロバイダーの問題に対するリグレッションを追加する方法 ## クイックスタート -たいていの日は次のとおりです。 +多くの日では: -- フルゲート（push前に期待される）: `pnpm build && pnpm check && pnpm test` -- 余裕のあるマシンでの、より高速なローカル全スイート実行: `pnpm test:max` -- 直接のVitest watchループ: `pnpm test:watch` -- 直接のファイル指定は、extension/channelパスも対象になりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 単一の失敗を反復修正しているときは、まず対象を絞った実行を優先してください。 -- DockerベースのQAサイト: `pnpm qa:lab:up` -- Linux VMベースのQAレーン: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- フルゲート（push 前に想定）: `pnpm build && pnpm check && pnpm test` +- 余裕のあるマシンでの高速なローカル全スイート実行: `pnpm test:max` +- 直接の Vitest watch ループ: `pnpm test:watch` +- 直接のファイル指定は extension/channel のパスにも対応するようになりました: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 単一の失敗を反復的に修正しているときは、まず対象を絞った実行を優先してください。 +- Docker ベースの QA サイト: `pnpm qa:lab:up` +- Linux VM ベースの QA レーン: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -テストに変更を加えたとき、または追加の確信がほしいとき: +テストに触れたときや、より高い確信が欲しいときは: - カバレッジゲート: `pnpm test:coverage` -- E2Eスイート: `pnpm test:e2e` +- E2E スイート: `pnpm test:e2e` 実際のプロバイダー/モデルをデバッグするとき（実際の認証情報が必要）: -- Liveスイート（モデル + Gatewayのtool/imageプローブ）: `pnpm test:live` -- 1つのliveファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- live スイート（models + Gateway の tool/image プローブ）: `pnpm test:live` +- 1 つの live ファイルを静かに対象指定: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -ヒント: 失敗している1ケースだけが必要な場合は、後述のallowlist環境変数を使ってliveテストを絞り込むことを優先してください。 +ヒント: 必要なのが 1 つの失敗ケースだけなら、以下で説明する allowlist 環境変数を使って live テストを絞り込むことを優先してください。 -## QA専用ランナー +## QA 専用ランナー -これらのコマンドは、QA-labの現実性が必要なときに、メインのテストスイートと並んで使います。 +これらのコマンドは、QA-lab に近い現実性が必要なときに、メインのテストスイートに並んで使います。 - `pnpm openclaw qa suite` - - リポジトリベースのQAシナリオをホスト上で直接実行します。 - - デフォルトでは、分離されたgatewayワーカーを使って複数の選択シナリオを並列実行し、最大64ワーカーまたは選択シナリオ数まで使用します。`--concurrency `でワーカー数を調整するか、古い直列レーンには`--concurrency 1`を使います。 - - プロバイダーモード `live-frontier`、`mock-openai`、`aimock` をサポートします。`aimock`は、シナリオ対応の `mock-openai` レーンを置き換えることなく、実験的なフィクスチャおよびプロトコルモックのカバレッジのためにローカルのAIMockベースプロバイダーサーバーを起動します。 + - リポジトリベースの QA シナリオをホスト上で直接実行します。 + - デフォルトでは、分離された Gateway ワーカーを使って複数の選択シナリオを並列実行します。`qa-channel` のデフォルト同時実行数は 4 です（選択したシナリオ数により上限あり）。ワーカー数を調整するには `--concurrency ` を使用し、従来の直列レーンにするには `--concurrency 1` を使います。 + - いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしで成果物だけ欲しい場合は `--allow-failures` を使ってください。 + - プロバイダーモードとして `live-frontier`、`mock-openai`、`aimock` をサポートします。`aimock` は、シナリオ認識型の `mock-openai` レーンを置き換えることなく、実験的なフィクスチャおよびプロトコルモックのカバレッジのために、ローカルの AIMock ベースのプロバイダーサーバーを起動します。 - `pnpm openclaw qa suite --runner multipass` - - 同じQAスイートを使い捨てのMultipass Linux VM内で実行します。 + - 同じ QA スイートを使い捨ての Multipass Linux VM 内で実行します。 - ホスト上の `qa suite` と同じシナリオ選択動作を維持します。 - `qa suite` と同じプロバイダー/モデル選択フラグを再利用します。 - - live実行では、ゲストにとって実用的な対応済みQA認証入力を転送します: - 環境変数ベースのプロバイダーキー、QA live provider configパス、および存在する場合は `CODEX_HOME`。 + - live 実行では、ゲストで実用的なサポート対象 QA 認証入力を転送します: + 環境変数ベースのプロバイダーキー、QA live provider config パス、存在する場合の `CODEX_HOME`。 - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に置く必要があります。 - - 通常のQAレポート + サマリーに加えて、Multipassログを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - 通常の QA レポート + サマリーに加え、Multipass ログを `.artifacts/qa-e2e/...` 配下に書き出します。 - `pnpm qa:lab:up` - - オペレーター形式のQA作業のために、DockerベースのQAサイトを起動します。 + - オペレーター形式の QA 作業向けに、Docker ベースの QA サイトを起動します。 - `pnpm openclaw qa aimock` - - 直接のプロトコルスモークテストのために、ローカルのAIMockプロバイダーサーバーのみを起動します。 + - 直接のプロトコルスモークテスト用に、ローカルの AIMock プロバイダーサーバーのみを起動します。 - `pnpm openclaw qa matrix` - - 使い捨てのDockerベースTuwunel homeserverに対して、Matrix live QAレーンを実行します。 - - このQAホストは現時点ではrepo/dev専用です。パッケージ化されたOpenClawインストールには `qa-lab` が含まれないため、`openclaw qa` は公開されません。 - - リポジトリのチェックアウトでは、同梱ランナーを直接読み込みます。別個のPluginインストール手順は不要です。 - - 3人の一時的なMatrixユーザー（`driver`、`sut`、`observer`）と1つのプライベートルームをプロビジョニングし、その後で実際のMatrix PluginをSUTトランスポートとして使うQA gateway子プロセスを起動します。 - - デフォルトでは、固定された安定版Tuwunelイメージ `ghcr.io/matrix-construct/tuwunel:v1.5.1` を使用します。別のイメージをテストする必要がある場合は `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` で上書きしてください。 - - Matrixは、レーンがローカルで使い捨てユーザーをプロビジョニングするため、共有credential-sourceフラグを公開しません。 - - Matrix QAレポート、サマリー、observed-eventsアーティファクト、および結合されたstdout/stderr出力ログを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - Matrix live QA レーンを、使い捨ての Docker ベース Tuwunel homeserver に対して実行します。 + - この QA ホストは現時点では repo/dev 専用です。パッケージ化された OpenClaw インストールには `qa-lab` が同梱されないため、`openclaw qa` は公開されません。 + - リポジトリチェックアウトでは、バンドルされたランナーを直接読み込みます。別個の Plugin インストール手順は不要です。 + - 3 つの一時 Matrix ユーザー（`driver`、`sut`、`observer`）と 1 つのプライベートルームをプロビジョニングし、その後、実際の Matrix Plugin を SUT トランスポートとして使う QA Gateway 子プロセスを起動します。 + - デフォルトでは、固定された安定版 Tuwunel イメージ `ghcr.io/matrix-construct/tuwunel:v1.5.1` を使用します。別のイメージをテストする必要がある場合は `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` で上書きしてください。 + - Matrix は使い捨てユーザーをローカルでプロビジョニングするため、共有 credential-source フラグは公開しません。 + - Matrix QA レポート、サマリー、observed-events 成果物、および結合された stdout/stderr 出力ログを `.artifacts/qa-e2e/...` 配下に書き出します。 - `pnpm openclaw qa telegram` - - env内のdriverおよびSUT botトークンを使って、実際のプライベートグループに対するTelegram live QAレーンを実行します。 - - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。group idは数値のTelegram chat idである必要があります。 - - 共有プール認証情報向けに `--credential-source convex` をサポートします。通常はenvモードを使い、プール済みリースを使う場合は `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定してください。 - - 同じプライベートグループ内にある2つの異なるbotが必要で、SUT botはTelegram usernameを公開している必要があります。 - - bot同士の安定した観測のため、両方のbotで `@BotFather` のBot-to-Bot Communication Modeを有効にし、driver botがグループ内のbotトラフィックを観測できることを確認してください。 - - Telegram QAレポート、サマリー、およびobserved-messagesアーティファクトを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - env の driver および SUT bot token を使い、実際のプライベートグループに対して Telegram live QA レーンを実行します。 + - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。group id は数値の Telegram chat id である必要があります。 + - 共有プール認証情報には `--credential-source convex` をサポートします。デフォルトでは env モードを使い、プール済みリースを使いたい場合は `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定してください。 + - いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしで成果物だけ欲しい場合は `--allow-failures` を使ってください。 + - 同じプライベートグループ内に 2 つの別々の bot が必要であり、SUT bot は Telegram username を公開している必要があります。 + - 安定した bot 間観測のために、両方の bot について `@BotFather` で Bot-to-Bot Communication Mode を有効にし、driver bot がグループ内 bot トラフィックを観測できるようにしてください。 + - Telegram QA レポート、サマリー、および observed-messages 成果物を `.artifacts/qa-e2e/...` 配下に書き出します。 -liveトランスポートレーンは、追加される新しいトランスポートが逸脱しないよう、1つの標準契約を共有します。 +live トランスポートレーンは 1 つの標準契約を共有しているため、新しいトランスポートで挙動がずれることはありません。 -`qa-channel` は引き続き広範な合成QAスイートであり、live -transport coverage matrixには含まれません。 +`qa-channel` は引き続き広範な合成 QA スイートであり、live +トランスポートカバレッジ行列の一部ではありません。 -| Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | -| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | +| レーン | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | +| ------ | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | | Matrix | x | x | x | x | x | x | x | x | | | Telegram | x | | | | | | | | x | -### Convex経由の共有Telegram認証情報（v1） +### Convex を使った共有 Telegram 認証情報（v1） -`openclaw qa telegram` に対して `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）が有効な場合、 -QA labはConvexベースのプールから排他的リースを取得し、レーン実行中はそのリースにHeartbeatを送り、終了時にリースを解放します。 +`openclaw qa telegram` で `--credential-source convex`（または `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）を有効にすると、QA lab は Convex ベースのプールから排他的リースを取得し、レーンの実行中はそのリースに Heartbeat を送り、終了時にリースを解放します。 -参照用Convexプロジェクトスキャフォールド: +参照用 Convex プロジェクトひな形: - `qa/convex-credential-broker/` -必須の環境変数: +必須環境変数: - `OPENCLAW_QA_CONVEX_SITE_URL`（例: `https://your-deployment.convex.site`） -- 選択したロールに応じた1つのシークレット: +- 選択したロール用のシークレット 1 つ: - `maintainer` 用の `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` - `ci` 用の `OPENCLAW_QA_CONVEX_SECRET_CI` -- credentialロール選択: +- credential ロール選択: - CLI: `--credential-role maintainer|ci` - - 環境変数のデフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（デフォルトは `maintainer`） + - 環境変数のデフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（CI ではデフォルト `ci`、それ以外では `maintainer`） 任意の環境変数: @@ -121,15 +122,15 @@ QA labはConvexベースのプールから排他的リースを取得し、レ - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（デフォルト `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（デフォルト `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（デフォルト `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意のトレースid） -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` は、ローカル専用開発のためにloopback `http://` Convex URLを許可します。 +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（任意のトレース ID） +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` を設定すると、ローカル専用開発向けに loopback の `http://` Convex URL を許可します。 -通常運用では `OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使う必要があります。 +通常運用では、`OPENCLAW_QA_CONVEX_SITE_URL` は `https://` を使う必要があります。 -maintainer用の管理コマンド（pool add/remove/list）には、 -特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 +管理者用コマンド（プール add/remove/list）では、必ず +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 -maintainer向けCLIヘルパー: +管理者向け CLI ヘルパー: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -137,7 +138,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -スクリプトやCIユーティリティで機械可読な出力が必要な場合は `--json` を使用してください。 +スクリプトや CI ユーティリティで機械可読出力が必要な場合は `--json` を使用してください。 デフォルトのエンドポイント契約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）: @@ -151,73 +152,73 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - リクエスト: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - 成功: `{ status: "ok" }`（または空の `2xx`） -- `POST /admin/add`（maintainerシークレットのみ） +- `POST /admin/add`（maintainer シークレット専用） - リクエスト: `{ kind, actorId, payload, note?, status? }` - 成功: `{ status: "ok", credential }` -- `POST /admin/remove`（maintainerシークレットのみ） +- `POST /admin/remove`（maintainer シークレット専用） - リクエスト: `{ credentialId, actorId }` - 成功: `{ status: "ok", changed, credential }` - - アクティブリース保護: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（maintainerシークレットのみ） + - アクティブリースガード: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list`（maintainer シークレット専用） - リクエスト: `{ kind?, status?, includePayload?, limit? }` - 成功: `{ status: "ok", credentials, count }` -Telegram kind用のペイロード形式: +Telegram kind の payload 形式: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` は数値のTelegram chat id文字列である必要があります。 -- `admin/add` は `kind: "telegram"` に対してこの形式を検証し、不正なペイロードを拒否します。 +- `groupId` は数値の Telegram chat id 文字列である必要があります。 +- `admin/add` は `kind: "telegram"` に対してこの形式を検証し、不正な payload を拒否します。 -### QAにchannelを追加する +### QA への channel 追加 -markdown QAシステムにchannelを追加するには、必要なものは正確に2つだけです。 +Markdown QA システムに channel を追加するには、必要なのは正確に 2 つだけです。 -1. そのchannel用のtransport adapter。 -2. channel契約を検証するscenario pack。 +1. その channel 用のトランスポートアダプター。 +2. channel 契約を検証するシナリオパック。 -共有 `qa-lab` ホストがフローを管理できる場合、新しいトップレベルQAコマンドrootを追加しないでください。 +共有 `qa-lab` ホストがフローを管理できる場合、新しいトップレベル QA コマンドルートは追加しないでください。 -`qa-lab` は共有ホストの仕組みを管理します: +`qa-lab` は共有ホストメカニクスを管理します: -- `openclaw qa` コマンドroot -- スイートの起動と終了 -- ワーカー並列数 -- アーティファクト書き込み +- `openclaw qa` コマンドルート +- スイートの起動と終了処理 +- ワーカー並列性 +- 成果物の書き出し - レポート生成 - シナリオ実行 -- 古い `qa-channel` シナリオ向けの互換エイリアス +- 旧 `qa-channel` シナリオ向けの互換エイリアス -runner Pluginはtransport契約を管理します: +ランナー Plugin はトランスポート契約を管理します: -- `openclaw qa ` が共有 `qa` root配下でどのようにマウントされるか -- そのtransport向けにgatewayがどのように設定されるか -- readinessをどのように確認するか -- inbound eventをどのように注入するか -- outbound messageをどのように観測するか -- transcriptおよび正規化されたtransport stateをどのように公開するか -- transportを使ったactionをどのように実行するか -- transport固有のリセットまたはクリーンアップをどのように処理するか +- `openclaw qa ` が共有 `qa` ルートの配下にどのようにマウントされるか +- そのトランスポート向けに Gateway がどのように設定されるか +- readiness がどのように確認されるか +- inbound event がどのように注入されるか +- outbound message がどのように観測されるか +- transcript と正規化済みトランスポート状態がどのように公開されるか +- トランスポートベースのアクションがどのように実行されるか +- トランスポート固有の reset または cleanup がどのように処理されるか -新しいchannelを採用するための最小基準は次のとおりです。 +新しい channel に必要な最低採用基準は次のとおりです。 -1. 共有 `qa` rootの管理者は `qa-lab` のままにする。 -2. 共有 `qa-lab` ホスト境界上にtransport runnerを実装する。 -3. transport固有の仕組みはrunner Pluginまたはchannel harness内に保持する。 -4. 競合するrootコマンドを登録するのではなく、runnerを `openclaw qa ` としてマウントする。 - runner Pluginは `openclaw.plugin.json` で `qaRunners` を宣言し、`runtime-api.ts` から対応する `qaRunnerCliRegistrations` 配列をエクスポートする必要があります。 - `runtime-api.ts` は軽量に保ってください。遅延CLIおよびrunner実行は、別個のentrypointの背後に置く必要があります。 -5. テーマ化された `qa/scenarios/` ディレクトリ配下にmarkdownシナリオを作成または適応する。 -6. 新しいシナリオには汎用scenario helperを使用する。 -7. リポジトリが意図的な移行を行っている場合を除き、既存の互換エイリアスは動作したままにする。 +1. 共有 `qa` ルートの管理者は `qa-lab` のままにする。 +2. 共有 `qa-lab` ホストシーム上にトランスポートランナーを実装する。 +3. トランスポート固有のメカニクスは、そのランナー Plugin または channel harness の中に閉じ込める。 +4. 競合するルートコマンドを登録するのではなく、ランナーを `openclaw qa ` としてマウントする。 + ランナー Plugin は `openclaw.plugin.json` に `qaRunners` を宣言し、`runtime-api.ts` から対応する `qaRunnerCliRegistrations` 配列を export する必要があります。 + `runtime-api.ts` は軽量に保ってください。遅延 CLI およびランナー実行は別の entrypoint の背後に置くべきです。 +5. テーマ別の `qa/scenarios/` ディレクトリ配下で Markdown シナリオを作成または適応する。 +6. 新しいシナリオには汎用シナリオヘルパーを使う。 +7. リポジトリで意図的な移行を行っている場合を除き、既存の互換エイリアスを動作したままにする。 判断ルールは厳格です。 -- 振る舞いを `qa-lab` で一度だけ表現できるなら、`qa-lab` に置く。 -- 振る舞いが1つのchannel transportに依存するなら、そのrunner Pluginまたはplugin harness内に保持する。 -- シナリオが複数のchannelで使える新しい機能を必要とするなら、`suite.ts` にchannel固有の分岐を追加するのではなく、汎用helperを追加する。 -- 振る舞いが1つのtransportにしか意味を持たないなら、そのシナリオをtransport固有のものとして保持し、それをシナリオ契約で明示する。 +- 挙動を `qa-lab` に 1 回だけ表現できるなら、`qa-lab` に置いてください。 +- 挙動が 1 つの channel トランスポートに依存するなら、そのランナー Plugin または Plugin harness に留めてください。 +- シナリオに複数の channel で使える新しい capability が必要な場合は、`suite.ts` に channel 固有の分岐を追加する代わりに、汎用ヘルパーを追加してください。 +- 挙動が 1 つのトランスポートにしか意味を持たない場合は、そのシナリオをトランスポート固有のものとして維持し、そのことをシナリオ契約で明示してください。 -新しいシナリオ向けの推奨汎用helper名は次のとおりです。 +新しいシナリオに推奨される汎用ヘルパー名は次のとおりです。 - `waitForTransportReady` - `waitForChannelReady` @@ -232,7 +233,7 @@ runner Pluginはtransport契約を管理します: - `formatTransportTranscript` - `resetTransport` -既存シナリオ向けには、次を含む互換エイリアスが引き続き利用できます。 +既存シナリオ向けの互換エイリアスは引き続き利用可能です。これには次が含まれます: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -240,99 +241,100 @@ runner Pluginはtransport契約を管理します: - `formatConversationTranscript` - `resetBus` -新しいchannel作業では、汎用helper名を使用する必要があります。 -互換エイリアスは一斉移行を避けるために存在しており、 +新しい channel の作業では、汎用ヘルパー名を使用する必要があります。 +互換エイリアスは、一斉移行を避けるために存在しているのであって、 新しいシナリオ作成のモデルではありません。 ## テストスイート（どこで何が実行されるか） -スイートは「現実性が増していくもの」（そして不安定さ/コストも増していくもの）として考えてください。 +スイートは「現実性が増していくもの」（それに伴い flaky さ/コストも増えるもの）として捉えてください。 ### Unit / integration（デフォルト） - コマンド: `pnpm test` -- 設定: 既存のスコープ付きVitest projectに対する10個の逐次shard実行（`vitest.full-*.config.ts`） -- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下のcore/unitインベントリと、`vitest.unit.config.ts` でカバーされる許可済み `ui` nodeテスト +- 設定: 既存のスコープ済み Vitest project に対する 10 個の順次 shard 実行（`vitest.full-*.config.ts`） +- ファイル: `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 配下の core/unit インベントリ、および `vitest.unit.config.ts` でカバーされる許可済みの `ui` node テスト - 範囲: - - 純粋なunitテスト - - プロセス内integrationテスト（gateway auth、routing、tooling、parsing、config） + - 純粋な unit テスト + - プロセス内 integration テスト（Gateway auth、routing、tooling、parsing、config） - 既知のバグに対する決定的なリグレッション -- 想定: - - CIで実行される +- 期待値: + - CI で実行される - 実際のキーは不要 - - 高速で安定しているべき -- Projectsメモ: - - 対象指定なしの `pnpm test` は、1つの巨大なネイティブroot-projectプロセスではなく、11個のより小さいshard設定（`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`）を実行するようになりました。これにより、負荷の高いマシンでのピークRSSが削減され、auto-reply/extensionの処理が無関係なスイートを圧迫するのを防ぎます。 - - `pnpm test --watch` は引き続きネイティブrootの `vitest.config.ts` project graphを使用します。multi-shardのwatchループは現実的ではないためです。 - - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリ指定をまずスコープ付きレーン経由にルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` は完全なroot project起動コストを払わずに済みます。 - - `pnpm test:changed` は、差分がルーティング可能なsource/testファイルだけに触れている場合、変更されたgitパスを同じスコープ付きレーンに展開します。config/setupの編集は引き続き広いroot-project再実行にフォールバックします。 - - agents、commands、plugins、auto-reply helper、`plugin-sdk`、および同様の純粋なutility領域からのimportが軽いunitテストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーン経由にルーティングされます。stateful/runtime-heavyなファイルは既存レーンに残ります。 - - 一部の `plugin-sdk` と `commands` helper sourceファイルも、changed-mode実行をこれらの軽量レーン内の明示的な隣接テストへマップするため、helper編集時にそのディレクトリ全体の重いスイートを再実行せずに済みます。 - - `auto-reply` は現在、3つの専用バケットを持ちます: トップレベルcore helper、トップレベル `reply.*` integrationテスト、および `src/auto-reply/reply/**` サブツリーです。これにより、最も重いreply harness処理が軽量なstatus/chunk/tokenテストに乗らないようにしています。 -- Embedded runnerメモ: - - message-tool discovery入力またはCompaction runtime contextを変更する場合は、両レベルのカバレッジを維持してください。 - - 純粋なrouting/normalization境界に対して、焦点を絞ったhelperリグレッションを追加してください。 - - さらに、embedded runner integrationスイートも健全な状態に保ってください: + - 高速かつ安定しているべき +- Project に関する補足: + - 対象未指定の `pnpm test` は、1 つの巨大なネイティブルート project プロセスではなく、11 個の小さな shard 設定（`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`）を実行するようになりました。これにより、負荷の高いマシンでのピーク RSS を抑え、auto-reply/extension の処理が無関係なスイートを圧迫するのを防ぎます。 + - `pnpm test --watch` は、複数 shard の watch ループが実用的ではないため、引き続きネイティブルートの `vitest.config.ts` project graph を使用します。 + - `pnpm test`、`pnpm test:watch`、`pnpm test:perf:imports` は、明示的なファイル/ディレクトリ指定をまずスコープ済みレーンにルーティングするため、`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` のような実行では、完全なルート project 起動コストを支払わずに済みます。 + - `pnpm test:changed` は、差分がルーティング可能な source/test ファイルのみに触れている場合、変更された git パスを同じスコープ済みレーンに展開します。config/setup の編集は、引き続き広いルート project の再実行にフォールバックします。 + - agents、commands、plugins、auto-reply helper、`plugin-sdk`、および同様の純粋な utility 領域からの import の軽い unit テストは、`test/setup-openclaw-runtime.ts` をスキップする `unit-fast` レーンにルーティングされます。stateful/runtime-heavy なファイルは既存のレーンに残ります。 + - 選択された `plugin-sdk` と `commands` の helper source ファイルも、changed モードの実行をこれらの軽量レーン内の明示的な兄弟テストにマップするため、helper の編集でそのディレクトリ全体の重いスイートを再実行せずに済みます。 + - `auto-reply` には、トップレベル core helper、トップレベル `reply.*` integration テスト、そして `src/auto-reply/reply/**` サブツリーという 3 つの専用バケットが追加されました。これにより、最も重い reply harness の処理が、軽量な status/chunk/token テストに乗らないようにしています。 +- Embedded runner に関する補足: + - message-tool の discovery input や compaction の runtime context を変更するときは、 + 両方のレベルのカバレッジを維持してください。 + - 純粋な routing/normalization 境界については、焦点を絞った helper リグレッションを追加してください。 + - また、embedded runner の integration スイートも健全に保ってください: `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`、および `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - これらのスイートは、スコープ付きidとCompactionの振る舞いが実際の `run.ts` / `compact.ts` パスを通って引き続き流れることを検証します。helperのみのテストは、これらのintegrationパスの十分な代替にはなりません。 -- Poolメモ: - - ベースVitest設定は現在デフォルトで `threads` を使用します。 - - 共有Vitest設定は `isolate: false` も固定し、root projects、e2e、live設定全体で非分離runnerを使用します。 - - root UIレーンは `jsdom` setupとoptimizerを維持していますが、現在は共有の非分離runner上で実行されます。 - - 各 `pnpm test` shardは、共有Vitest設定から同じ `threads` + `isolate: false` のデフォルトを継承します。 - - 共有 `scripts/run-vitest.mjs` launcherは、Vitest子Nodeプロセスに対してデフォルトで `--no-maglev` も追加するようになり、大規模なローカル実行時のV8コンパイル負荷を減らします。標準のV8挙動と比較したい場合は `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 -- Fast-local iterationメモ: - - `pnpm test:changed` は、変更パスがより小さいスイートにきれいにマップされる場合、スコープ付きレーン経由にルーティングされます。 - - `pnpm test:max` と `pnpm test:changed:max` も同じルーティング挙動を維持しつつ、より高いworker上限を使います。 - - ローカルworkerの自動スケーリングは現在意図的に保守的で、ホストのload averageがすでに高い場合にも抑制されるため、複数のVitest実行が同時に走ってもデフォルトで与える影響が小さくなります。 - - ベースVitest設定は、テスト配線が変わったときにchanged-mode再実行の正しさを保つため、projects/configファイルを `forceRerunTriggers` としてマークします。 - - この設定は、対応ホスト上では `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効のままにします。直接プロファイリング用に明示的なキャッシュ場所を1つ使いたい場合は `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 -- Perf-debugメモ: - - `pnpm test:perf:imports` は、Vitestのimport所要時間レポートとimport-breakdown出力を有効にします。 - - `pnpm test:perf:imports:changed` は、同じプロファイリング表示を `origin/main` 以降に変更されたファイルに絞ります。 -- `pnpm test:perf:changed:bench -- --ref ` は、そのコミット済み差分について、ルーティングされた `test:changed` とネイティブroot-projectパスを比較し、wall timeとmacOS max RSSを出力します。 -- `pnpm test:perf:changed:bench -- --worktree` は、変更済みファイル一覧を `scripts/test-projects.mjs` とroot Vitest設定に通して、現在のdirty treeをベンチマークします。 - - `pnpm test:perf:profile:main` は、Vitest/Viteの起動およびtransformオーバーヘッドのmain-thread CPU profileを書き出します。 - - `pnpm test:perf:profile:runner` は、unitスイートに対してファイル並列を無効化したrunner CPU+heap profileを書き出します。 + - これらのスイートは、scoped id と compaction の挙動が実際の `run.ts` / `compact.ts` パスを通って引き続き流れることを検証します。helper のみのテストは、これらの integration パスの十分な代替にはなりません。 +- Pool に関する補足: + - ベースの Vitest 設定は現在デフォルトで `threads` を使用します。 + - 共有 Vitest 設定では、`isolate: false` も固定され、ルート projects、e2e、live 設定全体で非分離ランナーを使用します。 + - ルート UI レーンは `jsdom` の setup と optimizer を維持しつつ、共有の非分離ランナーでも実行されるようになりました。 + - 各 `pnpm test` shard は、共有 Vitest 設定から同じ `threads` + `isolate: false` のデフォルトを継承します。 + - 共有の `scripts/run-vitest.mjs` launcher は、大きなローカル実行中の V8 コンパイル churn を減らすため、Vitest 子 Node プロセスにデフォルトで `--no-maglev` も追加するようになりました。標準の V8 挙動と比較したい場合は `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 +- 高速なローカル反復に関する補足: + - `pnpm test:changed` は、変更パスがより小さなスイートにきれいにマップされる場合、スコープ済みレーンを経由します。 + - `pnpm test:max` と `pnpm test:changed:max` も同じルーティング挙動を維持しつつ、worker 上限だけを高くしています。 + - ローカル worker の自動スケーリングは現在意図的に保守的で、ホストの load average がすでに高い場合にも抑制されるため、複数の同時 Vitest 実行がデフォルトで与える悪影響が小さくなっています。 + - ベース Vitest 設定では、changed モードの再実行がテスト配線変更時にも正しくなるよう、projects/config ファイルを `forceRerunTriggers` としてマークしています。 + - この設定では、サポート対象ホスト上で `OPENCLAW_VITEST_FS_MODULE_CACHE` を有効に保ちます。直接 profiling のために明示的なキャッシュ場所を 1 つ指定したい場合は、`OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` を設定してください。 +- Perf-debug に関する補足: + - `pnpm test:perf:imports` は、Vitest の import 所要時間レポートと import 内訳出力を有効にします。 + - `pnpm test:perf:imports:changed` は、同じ profiling 表示を `origin/main` 以降で変更されたファイルに限定します。 +- `pnpm test:perf:changed:bench -- --ref ` は、そのコミット済み差分に対して、ルーティングされた `test:changed` とネイティブルート project パスを比較し、wall time と macOS の最大 RSS を出力します。 +- `pnpm test:perf:changed:bench -- --worktree` は、変更ファイル一覧を `scripts/test-projects.mjs` とルート Vitest 設定に通すことで、現在の dirty tree をベンチマークします。 + - `pnpm test:perf:profile:main` は、Vitest/Vite の起動と transform オーバーヘッドに対するメインスレッド CPU profile を書き出します。 + - `pnpm test:perf:profile:runner` は、unit スイートに対してファイル並列を無効化した runner CPU+heap profile を書き出します。 -### E2E（gateway smoke） +### E2E（Gateway スモーク） - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` - ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts` -- Runtimeのデフォルト: - - リポジトリの他の部分と同様に、Vitest `threads` を `isolate: false` で使用します。 - - 適応的workerを使用します（CI: 最大2、ローカル: デフォルト1）。 - - console I/Oオーバーヘッドを減らすため、デフォルトでsilent modeで実行します。 +- runtime のデフォルト: + - リポジトリの他の部分と同様に、Vitest `threads` と `isolate: false` を使用します。 + - 適応型 worker を使用します（CI: 最大 2、ローカル: デフォルト 1）。 + - コンソール I/O オーバーヘッドを減らすため、デフォルトで silent モードで実行されます。 - 便利な上書き: - - worker数を強制する `OPENCLAW_E2E_WORKERS=`（上限16） - - 詳細なconsole出力を再有効化する `OPENCLAW_E2E_VERBOSE=1` + - worker 数を強制する `OPENCLAW_E2E_WORKERS=`（上限 16）。 + - 詳細なコンソール出力を再有効化する `OPENCLAW_E2E_VERBOSE=1`。 - 範囲: - - 複数インスタンスgatewayのエンドツーエンド動作 + - 複数インスタンス Gateway の end-to-end 挙動 - WebSocket/HTTP surface、node pairing、およびより重いネットワーキング -- 想定: - - CIで実行される（パイプラインで有効な場合） +- 期待値: + - CI で実行される（パイプラインで有効な場合） - 実際のキーは不要 - - unitテストよりも可動部分が多い（遅くなることがある） + - unit テストより可動部分が多い（遅くなる場合がある） -### E2E: OpenShell backend smoke +### E2E: OpenShell バックエンドスモーク - コマンド: `pnpm test:e2e:openshell` - ファイル: `test/openshell-sandbox.e2e.test.ts` - 範囲: - - Docker経由でホスト上に分離されたOpenShell gatewayを起動する - - 一時的なローカルDockerfileからsandboxを作成する - - 実際の `sandbox ssh-config` + SSH execを介してOpenClawのOpenShell backendを検証する - - sandbox fs bridgeを通じてremote-canonical filesystemの挙動を検証する -- 想定: - - オプトインのみ。デフォルトの `pnpm test:e2e` 実行には含まれない - - ローカルの `openshell` CLIと動作するDocker daemonが必要 - - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テストgatewayとsandboxを破棄する + - Docker 経由でホスト上に分離された OpenShell Gateway を起動する + - 一時的なローカル Dockerfile から sandbox を作成する + - 実際の `sandbox ssh-config` + SSH exec を介して OpenClaw の OpenShell バックエンドを実行する + - sandbox fs bridge を通じて remote-canonical filesystem の挙動を検証する +- 期待値: + - オプトイン専用であり、デフォルトの `pnpm test:e2e` 実行には含まれない + - ローカルの `openshell` CLI と動作する Docker daemon が必要 + - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テスト Gateway と sandbox を破棄する - 便利な上書き: - - より広いe2eスイートを手動実行する際にこのテストを有効化する `OPENCLAW_E2E_OPENSHELL=1` - - デフォルト以外のCLIバイナリまたはwrapper scriptを指す `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` + - 広い e2e スイートを手動実行するときにこのテストを有効化する `OPENCLAW_E2E_OPENSHELL=1` + - デフォルト以外の CLI バイナリまたは wrapper script を指す `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` ### Live（実際のプロバイダー + 実際のモデル） @@ -341,141 +343,141 @@ runner Pluginはtransport契約を管理します: - ファイル: `src/**/*.live.test.ts` - デフォルト: `pnpm test:live` により **有効**（`OPENCLAW_LIVE_TEST=1` を設定） - 範囲: - - 「このプロバイダー/モデルは、実際の認証情報で _今日_ 本当に動くか？」 - - プロバイダー形式変更、tool-callingの癖、authの問題、rate limitの挙動を検出する -- 想定: - - 設計上CIで安定しない（実ネットワーク、実プロバイダーポリシー、quota、障害） - - 費用がかかる / rate limitを消費する - - 「全部」よりも、絞り込んだサブセットを実行することを推奨 -- live実行は、不足しているAPIキーを拾うために `~/.profile` を読み込みます。 -- デフォルトでは、live実行は依然として `HOME` を分離し、config/auth素材を一時的なテストhomeにコピーするため、unit fixtureが実際の `~/.openclaw` を変更できません。 -- liveテストに意図的に実際のhome directoryを使わせたい場合にのみ `OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 -- `pnpm test:live` は現在、より静かなモードがデフォルトです。`[live] ...` の進捗出力は維持しつつ、追加の `~/.profile` 通知を抑制し、gateway bootstrapログやBonjourの雑音をミュートします。完全な起動ログを再表示したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 -- APIキーのローテーション（プロバイダー別）: カンマ/セミコロン形式の `*_API_KEYS`、または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）、あるいはlive専用の上書きとして `OPENCLAW_LIVE_*_KEY` を設定します。テストはrate limit応答時に再試行します。 -- 進捗/Heartbeat出力: - - liveスイートは現在、長いプロバイダー呼び出し中でもVitestのconsole captureが静かなときに動作中であることが見えるよう、進捗行をstderrに出力します。 - - `vitest.live.config.ts` はVitestのconsole interceptionを無効にするため、プロバイダー/gatewayの進捗行がlive実行中に即座にストリームされます。 - - 直接モデルのHeartbeatは `OPENCLAW_LIVE_HEARTBEAT_MS` で調整します。 - - gateway/probeのHeartbeatは `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 + - 「このプロバイダー/モデルは _今日_、実際の認証情報で本当に動くか？」 + - プロバイダーの形式変更、tool-calling の癖、auth 問題、rate limit 挙動を検出する +- 期待値: + - 設計上、CI 安定ではない（実際のネットワーク、実際のプロバイダーポリシー、quota、outage） + - コストがかかる / rate limit を消費する + - 「すべて」ではなく絞り込んだサブセットの実行を優先する +- Live 実行では、不足している API キーを取得するために `~/.profile` を読み込みます。 +- デフォルトでは、live 実行は引き続き `HOME` を分離し、config/auth の素材を一時的な test home にコピーするため、unit fixture が実際の `~/.openclaw` を変更できません。 +- live テストに意図的に実際の home directory を使わせる必要がある場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 +- `pnpm test:live` は現在、より静かなモードをデフォルトにしています。`[live] ...` の進行出力は維持しつつ、追加の `~/.profile` 通知を抑制し、Gateway bootstrap ログ/Bonjour の雑音をミュートします。完全な起動ログを再表示したい場合は `OPENCLAW_LIVE_TEST_QUIET=0` を設定してください。 +- API キーのローテーション（プロバイダー別）: カンマ/セミコロン形式の `*_API_KEYS`、または `*_API_KEY_1`、`*_API_KEY_2`（例: `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`）を設定するか、live 専用上書きとして `OPENCLAW_LIVE_*_KEY` を使用します。テストは rate limit 応答時に再試行します。 +- 進行状況/Heartbeat 出力: + - Live スイートは現在、長時間のプロバイダー呼び出しが、Vitest のコンソールキャプチャが静かな場合でも可視状態であるよう、進行行を stderr に出力します。 + - `vitest.live.config.ts` は Vitest のコンソールインターセプトを無効にしているため、プロバイダー/Gateway の進行行は live 実行中に即時ストリームされます。 + - 直接モデルの Heartbeat は `OPENCLAW_LIVE_HEARTBEAT_MS` で調整します。 + - Gateway/プローブの Heartbeat は `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 ## どのスイートを実行すべきか？ -この判断表を使ってください。 +次の判断表を使ってください。 -- ロジック/テストを編集している: `pnpm test` を実行する（大きく変更したなら `pnpm test:coverage` も） -- gateway networking / WS protocol / pairingに触れている: `pnpm test:e2e` も追加する -- 「自分のbotが落ちている」/ プロバイダー固有の失敗 / tool callingをデバッグしている: 絞り込んだ `pnpm test:live` を実行する +- ロジック/テストを編集している: `pnpm test` を実行（大きく変更した場合は `pnpm test:coverage` も） +- Gateway ネットワーキング / WS protocol / pairing に触れる: `pnpm test:e2e` も追加 +- 「bot が落ちている」/ プロバイダー固有の失敗 / tool calling をデバッグしている: 絞り込んだ `pnpm test:live` を実行 -## Live: Android Node capability sweep +## Live: Android node capability sweep - テスト: `src/gateway/android-node.capabilities.live.test.ts` - スクリプト: `pnpm android:test:integration` -- 目的: 接続されたAndroid Nodeが現在通知している **すべてのコマンド** を呼び出し、コマンド契約の挙動を検証する。 +- 目的: 接続済み Android node が現在公開している **すべてのコマンド** を呼び出し、コマンド契約の挙動を検証すること。 - 範囲: - - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/実行/ペアリングを行いません）。 - - 選択したAndroid Nodeに対するコマンド単位のgateway `node.invoke` 検証。 -- 必須の事前セットアップ: - - Androidアプリがすでにgatewayに接続済みかつペアリング済みであること。 - - アプリがフォアグラウンドに維持されていること。 - - 成功を期待するcapabilityに必要な権限/キャプチャ同意が付与されていること。 -- 任意の対象上書き: + - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/実行/pairing は行いません）。 + - 選択した Android node に対するコマンドごとの Gateway `node.invoke` 検証。 +- 必要な事前セットアップ: + - Android アプリがすでに Gateway に接続済みかつ paired 済みであること。 + - アプリをフォアグラウンドに維持すること。 + - 成功を期待する capability に対して、権限/キャプチャ同意が付与されていること。 +- 任意のターゲット上書き: - `OPENCLAW_ANDROID_NODE_ID` または `OPENCLAW_ANDROID_NODE_NAME`。 - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。 -- Androidの完全なセットアップ詳細: [Android App](/ja-JP/platforms/android) +- Android の完全なセットアップ詳細: [Android アプリ](/ja-JP/platforms/android) ## Live: model smoke（profile keys） -liveテストは、失敗を切り分けられるよう2つの層に分かれています。 +Live テストは、失敗を切り分けられるよう 2 層に分かれています。 -- 「Direct model」は、そのキーでプロバイダー/モデルが少なくとも応答できることを示します。 -- 「Gateway smoke」は、そのモデルに対してgateway+agentパイプライン全体（sessions、history、tools、sandbox policyなど）が機能することを示します。 +- 「直接モデル」は、そのキーでプロバイダー/モデルが少なくとも応答できるかを示します。 +- 「Gateway スモーク」は、そのモデルに対して Gateway+agent パイプライン全体（session、history、tools、sandbox policy など）が動作するかを示します。 -### レイヤー1: 直接モデル完了（gatewayなし） +### 第 1 層: 直接モデル completion（Gateway なし） - テスト: `src/agents/models.profiles.live.test.ts` - 目的: - 検出されたモデルを列挙する - `getApiKeyForModel` を使って、認証情報を持っているモデルを選択する - - モデルごとに小さなcompletionを実行する（必要に応じて対象を絞ったリグレッションも実行する） + - モデルごとに小さな completion を実行する（必要に応じて対象を絞ったリグレッションも） - 有効化方法: - - `pnpm test:live`（またはVitestを直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） -- 実際にこのスイートを実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、`modern` のエイリアス）を設定します。そうしない場合、このスイートはskipされ、`pnpm test:live` はgateway smokeに集中したままになります。 + - `pnpm test:live`（または Vitest を直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） +- このスイートを実際に実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、`modern` のエイリアス）を設定してください。そうしない場合、`pnpm test:live` を Gateway スモークに集中させるため、このスイートは skip されます。 - モデルの選択方法: - - `OPENCLAW_LIVE_MODELS=modern` でmodern allowlistを実行する（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - - `OPENCLAW_LIVE_MODELS=all` はmodern allowlistのエイリアス - - または `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（カンマ区切りallowlist） - - modern/allスイープはデフォルトで厳選された高シグナル上限を使います。網羅的なmodernスイープには `OPENCLAW_LIVE_MAX_MODELS=0` を、より小さい上限には正の数を設定してください。 + - モダン allowlist を実行するには `OPENCLAW_LIVE_MODELS=modern`（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） + - `OPENCLAW_LIVE_MODELS=all` はモダン allowlist のエイリアスです + - または `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（カンマ区切り allowlist） + - modern/all スイープはデフォルトで、厳選された高シグナルの上限を使用します。網羅的な modern スイープには `OPENCLAW_LIVE_MAX_MODELS=0` を設定し、より小さい上限にしたい場合は正の数を設定してください。 - プロバイダーの選択方法: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（カンマ区切りallowlist） + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（カンマ区切り allowlist） - キーの取得元: - - デフォルト: profile storeとenvフォールバック - - **profile store** のみを強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` を設定する + - デフォルト: profile store と env fallback + - **profile store** のみを強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` を設定 - これが存在する理由: - - 「provider APIが壊れている / キーが無効である」と「gateway agentパイプラインが壊れている」を切り分けるため - - 小さく分離されたリグレッションを収めるため（例: OpenAI Responses/Codex Responsesのreasoning replay + tool-callフロー） + - 「provider API が壊れている / キーが無効」と「Gateway agent パイプラインが壊れている」を分離する + - 小さく独立したリグレッションを収容する（例: OpenAI Responses/Codex Responses の reasoning replay + tool-call フロー） -### レイヤー2: Gateway + dev agent smoke（`@openclaw` が実際に行うこと） +### 第 2 層: Gateway + dev agent スモーク（`@openclaw` が実際に行うこと） - テスト: `src/gateway/gateway-models.profiles.live.test.ts` - 目的: - - プロセス内gatewayを起動する - - `agent:dev:*` sessionを作成/patchする（実行ごとにモデル上書き） - - キーを持つモデルを反復し、次を検証する: - - 「意味のある」応答（toolsなし） - - 実際のtool呼び出しが機能すること（read probe） - - 任意の追加tool probe（exec+read probe） - - OpenAIのリグレッションパス（tool-call-only → follow-up）が引き続き機能すること -- Probeの詳細（失敗を素早く説明できるようにするため）: - - `read` probe: テストはworkspaceにnonceファイルを書き込み、agentにそれを `read` してnonceを返答でそのまま返すよう求めます。 - - `exec+read` probe: テストはagentに `exec` でnonceを一時ファイルに書かせ、その後それを `read` で読み返させます。 - - image probe: テストは生成したPNG（cat + ランダム化コード）を添付し、モデルが `cat ` を返すことを期待します。 - - 実装参照: `src/gateway/gateway-models.profiles.live.test.ts` および `src/gateway/live-image-probe.ts`。 + - プロセス内 Gateway を起動する + - `agent:dev:*` session を作成/patch する（実行ごとに model override） + - キー付きモデルを反復し、次を検証する: + - 「意味のある」応答（tools なし） + - 実際の tool 呼び出しが動作する（read probe） + - 任意の追加 tool probe（exec+read probe） + - OpenAI のリグレッション経路（tool-call-only → follow-up）が引き続き動作する +- Probe の詳細（失敗をすばやく説明できるように）: + - `read` probe: テストはワークスペースに nonce ファイルを書き込み、agent にそれを `read` して nonce をそのまま返すよう要求します。 + - `exec+read` probe: テストは agent に、一時ファイルへ `exec` で nonce を書き込み、その後それを `read` で読み戻すよう要求します。 + - image probe: テストは生成した PNG（cat + ランダムコード）を添付し、モデルが `cat ` を返すことを期待します。 + - 実装参照: `src/gateway/gateway-models.profiles.live.test.ts` と `src/gateway/live-image-probe.ts`。 - 有効化方法: - - `pnpm test:live`（またはVitestを直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） + - `pnpm test:live`（または Vitest を直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） - モデルの選択方法: - - デフォルト: modern allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` はmodern allowlistのエイリアス - - または `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（またはカンマ区切りリスト）で絞り込む - - modern/allのgatewayスイープはデフォルトで厳選された高シグナル上限を使います。網羅的なmodernスイープには `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` を、より小さい上限には正の数を設定してください。 -- プロバイダーの選択方法（「OpenRouterの全部」を避ける）: - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（カンマ区切りallowlist） -- Tool + image probeはこのliveテストでは常に有効です: - - `read` probe + `exec+read` probe（toolストレス） - - image入力サポートをモデルが通知している場合はimage probeが実行されます + - デフォルト: モダン allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` はモダン allowlist のエイリアスです + - または `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（またはカンマ区切りリスト）を設定して絞り込む + - modern/all の Gateway スイープはデフォルトで、厳選された高シグナルの上限を使用します。網羅的な modern スイープには `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` を設定し、より小さい上限にしたい場合は正の数を設定してください。 +- プロバイダーの選択方法（「OpenRouter ですべて」を避ける）: + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（カンマ区切り allowlist） +- tool + image probe はこの live テストで常に有効です: + - `read` probe + `exec+read` probe（tool ストレス） + - image probe は、モデルが image input support を公開している場合に実行されます - フロー（高レベル）: - - テストは「CAT」+ ランダムコードを含む小さなPNGを生成します（`src/gateway/live-image-probe.ts`） - - それを `agent` `attachments: [{ mimeType: "image/png", content: "" }]` 経由で送信します - - Gatewayはattachmentを `images[]` に解析します（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） - - embedded agentはmultimodal user messageをモデルに転送します - - 検証: 返答に `cat` + そのコードが含まれること（OCRの許容: 軽微な誤りは可） + - テストは「CAT」+ ランダムコードを含む小さな PNG を生成します（`src/gateway/live-image-probe.ts`） + - それを `agent` の `attachments: [{ mimeType: "image/png", content: "" }]` 経由で送信します + - Gateway は添付を `images[]` に解析します（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） + - Embedded agent は multimodal なユーザーメッセージをモデルへ転送します + - 検証: 返信に `cat` + そのコードが含まれること（OCR 許容: 軽微な誤りは許可） -ヒント: 自分のマシンで何をテストできるか（および正確な `provider/model` id）を確認するには、次を実行してください。 +ヒント: 手元のマシンで何がテストできるか（および正確な `provider/model` id）を確認するには、次を実行してください。 ```bash openclaw models list openclaw models list --json ``` -## Live: CLI backend smoke（Claude、Codex、Gemini、またはその他のローカルCLI） +## Live: CLI バックエンドスモーク（Claude、Codex、Gemini、または他のローカル CLI） - テスト: `src/gateway/gateway-cli-backend.live.test.ts` -- 目的: デフォルトconfigに触れずに、ローカルCLI backendを使ってGateway + agentパイプラインを検証する。 -- backend固有のsmokeデフォルトは、所有するextensionの `cli-backend.ts` 定義にあります。 +- 目的: デフォルト config に触れずに、ローカル CLI バックエンドを使って Gateway + agent パイプラインを検証する。 +- バックエンド固有のスモークデフォルトは、所有 extension の `cli-backend.ts` 定義内にあります。 - 有効化: - - `pnpm test:live`（またはVitestを直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） + - `pnpm test:live`（または Vitest を直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） - `OPENCLAW_LIVE_CLI_BACKEND=1` - デフォルト: - - デフォルトのprovider/model: `claude-cli/claude-sonnet-4-6` - - command/args/imageの挙動は、所有するCLI backend Plugin metadataから取得します。 + - デフォルトの provider/model: `claude-cli/claude-sonnet-4-6` + - command/args/image の挙動は、所有 CLI バックエンド Plugin メタデータに由来します。 - 上書き（任意）: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - 実際のimage attachmentを送るには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`（パスはpromptに注入されます）。 - - prompt注入の代わりにimage file pathをCLI引数として渡すには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`。 - - `IMAGE_ARG` が設定されているときにimage引数の渡し方を制御するには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または `"list"`）。 - - 2ターン目を送信してresumeフローを検証するには `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`。 - - デフォルトのClaude Sonnet -> Opus同一session継続probeを無効化するには `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択したモデルがswitch targetをサポートしているときに強制的に有効化するには `1` を設定）。 + - 実際の image 添付を送信するには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`（パスはプロンプトに注入されます）。 + - プロンプト注入の代わりに image ファイルパスを CLI 引数として渡すには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`。 + - `IMAGE_ARG` が設定されているときに image 引数の渡し方を制御するには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（または `"list"`）。 + - 2 回目のターンを送って resume フローを検証するには `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`。 + - デフォルトの Claude Sonnet -> Opus 同一 session 継続性 probe を無効にするには `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`（選択したモデルが switch target をサポートしている場合に強制的に有効にするには `1` を設定）。 例: @@ -485,13 +487,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Dockerレシピ: +Docker レシピ: ```bash pnpm test:docker:live-cli-backend ``` -単一プロバイダーのDockerレシピ: +単一プロバイダー Docker レシピ: ```bash pnpm test:docker:live-cli-backend:claude @@ -500,40 +502,40 @@ pnpm test:docker:live-cli-backend:codex pnpm test:docker:live-cli-backend:gemini ``` -メモ: +注意: -- Dockerランナーは `scripts/test-live-cli-backend-docker.sh` にあります。 -- これは、リポジトリのDocker image内で、非rootの `node` ユーザーとしてlive CLI-backend smokeを実行します。 -- 所有するextensionからCLI smoke metadataを解決し、その後、一致するLinux CLIパッケージ（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）を、キャッシュ可能で書き込み可能なprefix `OPENCLAW_DOCKER_CLI_TOOLS_DIR`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）にインストールします。 -- `pnpm test:docker:live-cli-backend:claude-subscription` では、`~/.claude/.credentials.json` に `claudeAiOauth.subscriptionType` があるか、または `claude setup-token` 由来の `CLAUDE_CODE_OAUTH_TOKEN` を通じたポータブルClaude Code subscription OAuthが必要です。まずDocker内で直接 `claude -p` を検証し、その後、Anthropic API-key env varsを保持せずに2つのGateway CLI-backendターンを実行します。このsubscriptionレーンでは、Claudeが現在、通常のsubscription plan制限ではなく追加利用課金経由でサードパーティアプリ利用をルーティングするため、Claude MCP/toolおよびimage probeがデフォルトで無効になります。 -- live CLI-backend smokeは現在、Claude、Codex、Geminiに対して同じエンドツーエンドフローを実行します: テキストターン、image classificationターン、その後gateway CLI経由で検証されるMCP `cron` tool呼び出し。 -- Claudeのデフォルトsmokeでは、sessionをSonnetからOpusにpatchし、resumeしたsessionが以前のメモを引き続き覚えていることも検証します。 +- Docker ランナーは `scripts/test-live-cli-backend-docker.sh` にあります。 +- これは、live CLI-backend スモークをリポジトリ Docker イメージ内で非 root の `node` ユーザーとして実行します。 +- 所有 extension から CLI スモークメタデータを解決し、一致する Linux CLI パッケージ（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）を、`OPENCLAW_DOCKER_CLI_TOOLS_DIR`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）にあるキャッシュ可能で書き込み可能な prefix にインストールします。 +- `pnpm test:docker:live-cli-backend:claude-subscription` は、`~/.claude/.credentials.json` と `claudeAiOauth.subscriptionType` の組み合わせ、または `claude setup-token` の `CLAUDE_CODE_OAUTH_TOKEN` のいずれかによる、ポータブルな Claude Code subscription OAuth を必要とします。まず Docker 内で直接 `claude -p` を検証し、その後 Anthropic API-key env vars を保持せずに 2 回の Gateway CLI-backend ターンを実行します。この subscription レーンでは、Claude が現在、通常の subscription plan 制限ではなく追加使用量課金を通じてサードパーティアプリ利用をルーティングするため、Claude MCP/tool および image probe はデフォルトで無効化されます。 +- live CLI-backend スモークは現在、Claude、Codex、Gemini に対して同じ end-to-end フローを実行します: テキストターン、画像分類ターン、その後 Gateway CLI 経由で検証される MCP `cron` tool call。 +- Claude のデフォルトスモークでは、session を Sonnet から Opus に patch し、再開した session が以前のメモを引き続き記憶していることも検証します。 -## Live: ACP bind smoke（`/acp spawn ... --bind here`） +## Live: ACP bind スモーク（`/acp spawn ... --bind here`） - テスト: `src/gateway/gateway-acp-bind.live.test.ts` -- 目的: live ACP agentを使った実際のACP conversation-bindフローを検証する: +- 目的: live ACP agent に対する実際の ACP conversation-bind フローを検証する: - `/acp spawn --bind here` を送信する - - 合成message-channel conversationをその場でbindする - - 同じconversation上で通常のfollow-upを送信する - - そのfollow-upがbind済みACP session transcriptに到達することを検証する + - 合成された message-channel conversation をその場で bind する + - 同じ conversation 上で通常の follow-up を送信する + - follow-up が bind された ACP session transcript に届くことを検証する - 有効化: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - デフォルト: - - Docker内のACP agent: `claude,codex,gemini` - - 直接の `pnpm test:live ...` 用ACP agent: `claude` - - 合成channel: Slack DM形式のconversation context - - ACP backend: `acpx` + - Docker 内の ACP agent: `claude,codex,gemini` + - 直接 `pnpm test:live ...` 用の ACP agent: `claude` + - 合成 channel: Slack DM 形式の conversation context + - ACP バックエンド: `acpx` - 上書き: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` -- メモ: - - このレーンは、admin専用の合成originating-routeフィールドを持つgateway `chat.send` surfaceを使うため、外部配信を装わずにmessage-channel contextをテストが付与できます。 - - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、テストは選択したACP harness agentに対して、組み込み `acpx` Pluginの内蔵agent registryを使用します。 +- 注意: + - このレーンは、テストが外部配信を装わずに message-channel context を添付できるよう、admin 専用の synthetic originating-route field を使って Gateway `chat.send` surface を使用します。 + - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、テストは選択された ACP harness agent に対して、組み込み `acpx` Plugin の内蔵 agent registry を使用します。 例: @@ -543,13 +545,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Dockerレシピ: +Docker レシピ: ```bash pnpm test:docker:live-acp-bind ``` -単一agentのDockerレシピ: +単一 agent Docker レシピ: ```bash pnpm test:docker:live-acp-bind:claude @@ -557,34 +559,34 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Dockerメモ: +Docker に関する注意: -- Dockerランナーは `scripts/test-live-acp-bind-docker.sh` にあります。 -- デフォルトでは、対応するすべてのlive CLI agentに対してACP bind smokeを順に実行します: `claude`、`codex`、次に `gemini`。 -- マトリクスを絞るには `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使用してください。 -- これは `~/.profile` を読み込み、一致するCLI auth素材をコンテナに配置し、`acpx` を書き込み可能なnpm prefixにインストールしてから、必要なら要求されたlive CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）をインストールします。 -- Docker内では、ランナーは `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` を設定し、`acpx` が読み込んだprofile由来のprovider env varsを子harness CLIで使えるようにします。 +- Docker ランナーは `scripts/test-live-acp-bind-docker.sh` にあります。 +- デフォルトでは、サポートされるすべての live CLI agent に対して順番に ACP bind スモークを実行します: `claude`、`codex`、その後 `gemini`。 +- 行列を絞り込むには `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使用してください。 +- これは `~/.profile` を読み込み、一致する CLI auth 素材をコンテナにステージし、`acpx` を書き込み可能な npm prefix にインストールし、その後必要であれば要求された live CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）をインストールします。 +- Docker 内では、`acpx` が読み込まれた profile の provider env vars を子 harness CLI で引き続き利用できるよう、ランナーは `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` を設定します。 -## Live: Codex app-server harness smoke +## Live: Codex app-server harness スモーク -- 目的: 通常のgateway - `agent` メソッドを通じて、Plugin所有のCodex harnessを検証する: - - 同梱の `codex` Pluginを読み込む +- 目的: Plugin 所有の Codex harness を通常の Gateway + `agent` メソッド経由で検証する: + - バンドルされた `codex` Plugin を読み込む - `OPENCLAW_AGENT_RUNTIME=codex` を選択する - - `codex/gpt-5.4` に対して最初のgateway agentターンを送信する - - 同じOpenClaw sessionに2ターン目を送信し、app-server - threadがresumeできることを検証する - - 同じgateway command - パスを通して `/codex status` と `/codex models` を実行する + - `codex/gpt-5.4` に最初の Gateway agent ターンを送信する + - 同じ OpenClaw session に 2 回目のターンを送信し、app-server + thread が resume できることを検証する + - 同じ Gateway command + path を通して `/codex status` と `/codex models` を実行する - テスト: `src/gateway/gateway-codex-harness.live.test.ts` - 有効化: `OPENCLAW_LIVE_CODEX_HARNESS=1` - デフォルトモデル: `codex/gpt-5.4` -- 任意のimage probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- 任意のMCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- このsmokeは `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を設定するため、壊れたCodex - harnessがPIへのサイレントフォールバックで通過することはできません。 -- 認証: shell/profile由来の `OPENAI_API_KEY` と、任意でコピーされる - `~/.codex/auth.json` および `~/.codex/config.toml` +- 任意の image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- 任意の MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- このスモークは `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を設定するため、壊れた Codex + harness が PI へ暗黙にフォールバックして通過することはできません。 +- Auth: シェル/profile の `OPENAI_API_KEY`、および任意でコピーされた + `~/.codex/auth.json` と `~/.codex/config.toml` ローカルレシピ: @@ -597,74 +599,74 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Dockerレシピ: +Docker レシピ: ```bash source ~/.profile pnpm test:docker:live-codex-harness ``` -Dockerメモ: +Docker に関する注意: -- Dockerランナーは `scripts/test-live-codex-harness-docker.sh` にあります。 -- これはマウントされた `~/.profile` を読み込み、`OPENAI_API_KEY` を渡し、存在する場合はCodex CLIの - authファイルをコピーし、`@openai/codex` を書き込み可能でマウントされたnpm - prefixにインストールし、source treeを配置した後、Codex-harness liveテストのみを実行します。 -- DockerではimageおよびMCP/tool probeがデフォルトで有効です。より狭いデバッグ実行が必要な場合は +- Docker ランナーは `scripts/test-live-codex-harness-docker.sh` にあります。 +- これはマウントされた `~/.profile` を読み込み、`OPENAI_API_KEY` を渡し、存在する場合は Codex CLI + 認証ファイルをコピーし、`@openai/codex` を書き込み可能なマウント済み npm + prefix にインストールし、ソースツリーをステージしてから、Codex-harness live テストのみを実行します。 +- Docker では image probe と MCP/tool probe がデフォルトで有効です。より狭いデバッグ実行が必要な場合は `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` または `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` を設定してください。 -- Dockerは `OPENCLAW_AGENT_HARNESS_FALLBACK=none` もエクスポートし、live - テスト設定に合わせるため、`openai-codex/*` やPIへのフォールバックでCodex harness - のリグレッションが隠れることはありません。 +- Docker は `OPENCLAW_AGENT_HARNESS_FALLBACK=none` も export します。これは live + テスト設定と一致しており、`openai-codex/*` や PI へのフォールバックが Codex harness + のリグレッションを隠すことができないようにします。 -### 推奨liveレシピ +### 推奨される live レシピ -狭く明示的なallowlistが、最も高速で不安定さも最小です。 +狭く明示的な allowlist が、最も高速で flaky さも最小です。 -- 単一モデル、direct（gatewayなし）: +- 単一モデル、直接実行（Gateway なし）: - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- 単一モデル、gateway smoke: +- 単一モデル、Gateway スモーク: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 複数プロバイダーにまたがるtool calling: +- 複数プロバイダーにまたがる tool calling: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Google重視（Gemini APIキー + Antigravity）: - - Gemini（APIキー）: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Google に集中する場合（Gemini API key + Antigravity）: + - Gemini（API key）: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity（OAuth）: `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -メモ: +注意: -- `google/...` はGemini API（APIキー）を使用します。 -- `google-antigravity/...` はAntigravity OAuth bridge（Cloud Code Assist形式のagent endpoint）を使用します。 -- `google-gemini-cli/...` はマシン上のローカルGemini CLIを使用します（別個のauth + toolingの癖があります）。 -- Gemini APIとGemini CLI: - - API: OpenClawはGoogleのホスト型Gemini APIをHTTP経由で呼び出します（APIキー / profile auth）。大半のユーザーが「Gemini」と言うときはこれを指します。 - - CLI: OpenClawはローカルの `gemini` バイナリをshell実行します。独自のauthがあり、挙動も異なることがあります（streaming/tool support/version skew）。 +- `google/...` は Gemini API（API key）を使います。 +- `google-antigravity/...` は Antigravity OAuth bridge（Cloud Code Assist 形式の agent endpoint）を使います。 +- `google-gemini-cli/...` は手元のマシン上のローカル Gemini CLI を使います（認証も tooling の癖も別です）。 +- Gemini API と Gemini CLI の違い: + - API: OpenClaw が Google のホストされた Gemini API を HTTP 経由で呼び出します（API key / profile auth）。これは多くのユーザーが「Gemini」と言うときに意味しているものです。 + - CLI: OpenClaw はローカルの `gemini` バイナリをシェル実行します。独自の認証を持ち、挙動も異なる場合があります（streaming/tool support/version skew）。 ## Live: model matrix（何をカバーするか） -固定の「CI model list」はありません（liveはオプトイン）が、キーを持つ開発マシンで定期的にカバーすることを**推奨**するモデルは次のとおりです。 +固定の「CI model list」はありません（live はオプトインです）が、開発マシン上でキーがある場合に、定期的にカバーすることを **推奨** するモデルは次のとおりです。 -### Modern smoke set（tool calling + image） +### Modern スモークセット（tool calling + image） -これは、動作を維持することが期待される「一般的なモデル」実行です。 +これは、動作し続けることを期待する「一般的なモデル」実行です。 -- OpenAI（非Codex）: `openai/gpt-5.4`（任意: `openai/gpt-5.4-mini`） +- OpenAI（非 Codex）: `openai/gpt-5.4`（任意: `openai/gpt-5.4-mini`） - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6`（または `anthropic/claude-sonnet-4-6`） -- Google（Gemini API）: `google/gemini-3.1-pro-preview` および `google/gemini-3-flash-preview`（古いGemini 2.xモデルは避ける） -- Google（Antigravity）: `google-antigravity/claude-opus-4-6-thinking` および `google-antigravity/gemini-3-flash` +- Google（Gemini API）: `google/gemini-3.1-pro-preview` と `google/gemini-3-flash-preview`（古い Gemini 2.x モデルは避けてください） +- Google（Antigravity）: `google-antigravity/claude-opus-4-6-thinking` と `google-antigravity/gemini-3-flash` - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -tools + image付きでgateway smokeを実行: +tools + image を使った Gateway スモークの実行: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### ベースライン: tool calling（Read + 任意のExec） +### ベースライン: tool calling（Read + 任意の Exec） -少なくともプロバイダーファミリーごとに1つ選んでください。 +少なくとも各プロバイダーファミリーごとに 1 つは選んでください。 - OpenAI: `openai/gpt-5.4`（または `openai/gpt-5.4-mini`） - Anthropic: `anthropic/claude-opus-4-6`（または `anthropic/claude-sonnet-4-6`） @@ -672,44 +674,44 @@ tools + image付きでgateway smokeを実行: - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -任意の追加カバレッジ（あると望ましい）: +任意の追加カバレッジ（あるとよいもの）: -- xAI: `xai/grok-4`（または利用可能な最新版） -- Mistral: `mistral/`…（有効化済みの「tools」対応モデルを1つ選ぶ） -- Cerebras: `cerebras/`…（アクセスがある場合） -- LM Studio: `lmstudio/`…（ローカル。tool callingはAPI modeに依存） +- xAI: `xai/grok-4`（または利用可能な最新） +- Mistral: `mistral/`…（有効化している「tools」対応モデルを 1 つ選ぶ） +- Cerebras: `cerebras/`…（アクセス権がある場合） +- LM Studio: `lmstudio/`…（ローカル。tool calling は API mode に依存） -### Vision: image send（attachment → multimodal message） +### Vision: 画像送信（attachment → multimodal message） -image probeを実行するために、少なくとも1つのimage対応モデルを `OPENCLAW_LIVE_GATEWAY_MODELS` に含めてください（Claude/Gemini/OpenAIのvision対応バリアントなど）。 +image probe を実行するには、少なくとも 1 つ、画像対応モデルを `OPENCLAW_LIVE_GATEWAY_MODELS` に含めてください（Claude/Gemini/OpenAI の vision 対応バリアントなど）。 -### Aggregators / alternate gateways +### Aggregator / 代替 Gateway -キーが有効であれば、次経由のテストもサポートしています。 +キーが有効であれば、次経由でのテストもサポートしています。 -- OpenRouter: `openrouter/...`（数百のモデル。tool+image対応候補を見つけるには `openclaw models scan` を使ってください） -- OpenCode: Zen向けの `opencode/...` とGo向けの `opencode-go/...`（authは `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`） +- OpenRouter: `openrouter/...`（数百のモデル。tools+image 対応候補を見つけるには `openclaw models scan` を使用） +- OpenCode: Zen 用の `opencode/...` と Go 用の `opencode-go/...`（認証は `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`） -live matrixに含められる他のプロバイダー（認証情報/configがある場合）: +live matrix に含められる追加プロバイダー（認証情報/config がある場合）: - 組み込み: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- `models.providers` 経由（custom endpoint）: `minimax`（cloud/API）、および任意のOpenAI/Anthropic互換proxy（LM Studio、vLLM、LiteLLMなど） +- `models.providers` 経由（カスタム endpoint）: `minimax`（cloud/API）、および OpenAI/Anthropic 互換の任意の proxy（LM Studio、vLLM、LiteLLM など） -ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。権威ある一覧は、あなたのマシン上で `discoverModels(...)` が返すものと、利用可能なキーの組み合わせです。 +ヒント: ドキュメントに「全モデル」をハードコードしようとしないでください。信頼できる一覧は、そのマシン上で `discoverModels(...)` が返すものと、利用可能なキーの組み合わせです。 -## 認証情報（絶対にコミットしない） +## 認証情報（絶対に commit しないこと） -liveテストは、CLIと同じ方法で認証情報を検出します。実用上の意味は次のとおりです。 +live テストは、CLI と同じ方法で認証情報を見つけます。実際上の意味は次のとおりです。 -- CLIが動くなら、liveテストも同じキーを見つけられるはずです。 -- liveテストが「認証情報なし」と言うなら、`openclaw models list` / モデル選択をデバッグするときと同じ方法でデバッグしてください。 +- CLI が動作するなら、live テストも同じキーを見つけられるはずです。 +- live テストで「認証情報なし」と出るなら、`openclaw models list` / モデル選択をデバッグするときと同じ方法でデバッグしてください。 -- エージェントごとのauth profile: `~/.openclaw/agents//agent/auth-profiles.json`（liveテストで「profile keys」と呼んでいるのはこれです） +- エージェントごとの auth profile: `~/.openclaw/agents//agent/auth-profiles.json`（これが live テストでいう「profile keys」です） - Config: `~/.openclaw/openclaw.json`（または `OPENCLAW_CONFIG_PATH`） -- レガシーstateディレクトリ: `~/.openclaw/credentials/`（存在する場合はstaged live homeにコピーされますが、メインのprofile-key storeではありません） -- ローカルlive実行は、デフォルトで有効なconfig、エージェントごとの `auth-profiles.json` ファイル、レガシー `credentials/`、およびサポートされている外部CLI authディレクトリを一時的なテストhomeにコピーします。staged live homeでは `workspace/` と `sandboxes/` はスキップされ、`agents.*.workspace` / `agentDir` のパス上書きは除去されるため、probeが実際のホストworkspaceに触れません。 +- 旧 state ディレクトリ: `~/.openclaw/credentials/`（存在する場合、ステージ済み live home にコピーされますが、メインの profile-key store ではありません） +- ローカル live 実行では、デフォルトで現在の config、エージェントごとの `auth-profiles.json` ファイル、旧 `credentials/`、およびサポート対象の外部 CLI auth ディレクトリを一時 test home にコピーします。ステージ済み live home では `workspace/` と `sandboxes/` をスキップし、`agents.*.workspace` / `agentDir` のパス上書きも削除されるため、probe が実際のホスト workspace に触れません。 -envキー（たとえば `~/.profile` にexportされたもの）に依存したい場合は、`source ~/.profile` の後にローカルテストを実行するか、以下のDockerランナーを使ってください（これらは `~/.profile` をコンテナにマウントできます）。 +env キー（たとえば `~/.profile` で export したもの）に依存したい場合は、`source ~/.profile` の後にローカルテストを実行するか、以下の Docker ランナーを使ってください（これらは `~/.profile` をコンテナにマウントできます）。 ## Deepgram live（音声文字起こし） @@ -727,290 +729,286 @@ envキー（たとえば `~/.profile` にexportされたもの）に依存した - テスト: `extensions/comfy/comfy.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - 範囲: - - 同梱comfyのimage、video、および `music_generate` パスを検証する - - `models.providers.comfy.` が設定されていない場合は各capabilityをskipする - - comfy workflow送信、polling、download、またはPlugin登録を変更した後に有用 + - バンドルされた comfy の image、video、`music_generate` パスを実行する + - `models.providers.comfy.` が設定されていない場合、各 capability を skip する + - comfy の workflow 提出、polling、download、または Plugin 登録を変更した後に有用 -## Image generation live +## 画像生成 live - テスト: `src/image-generation/runtime.live.test.ts` - コマンド: `pnpm test:live src/image-generation/runtime.live.test.ts` -- Harness: `pnpm test:live:media image` +- ハーネス: `pnpm test:live:media image` - 範囲: - - 登録されているすべてのimage-generation provider Pluginを列挙する - - probe前にlogin shell（`~/.profile`）から不足しているprovider env varsを読み込む - - デフォルトでは保存済みauth profileよりもlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠しません - - 使用可能なauth/profile/modelがないプロバイダーはskipする - - 共有runtime capabilityを通じて、標準のimage-generationバリアントを実行する: + - 登録済みのすべての画像生成 provider Plugin を列挙する + - probe 前に login shell（`~/.profile`）から不足している provider env vars を読み込む + - デフォルトでは保存済み auth profile より live/env API キーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 利用可能な auth/profile/model がない provider は skip する + - 共有 runtime capability を通じて標準の画像生成バリアントを実行する: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- 現在カバーされている同梱プロバイダー: +- 現在カバーされるバンドル済み provider: - `openai` - `google` - 任意の絞り込み: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- 任意のauth挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でprofile-store authを強制し、envのみの上書きを無視する +- 任意の auth 動作: + - profile-store auth を強制し、env-only 上書きを無視する `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Music generation live +## 音楽生成 live - テスト: `extensions/music-generation-providers.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- Harness: `pnpm test:live:media music` +- ハーネス: `pnpm test:live:media music` - 範囲: - - 共有の同梱music-generation providerパスを検証する - - 現在はGoogleとMiniMaxをカバーする - - probe前にlogin shell（`~/.profile`）からprovider env varsを読み込む - - デフォルトでは保存済みauth profileよりもlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠しません - - 使用可能なauth/profile/modelがないプロバイダーはskipする - - 利用可能な場合は、宣言された両方のruntime modeを実行する: - - prompt-only入力による `generate` - - プロバイダーが `capabilities.edit.enabled` を宣言している場合の `edit` - - 現在の共有レーンカバレッジ: - - `google`: `generate`、`edit` + - 共有のバンドル済み音楽生成 provider パスを実行する + - 現在は Google と MiniMax をカバー + - probe 前に login shell（`~/.profile`）から provider env vars を読み込む + - デフォルトでは保存済み auth profile より live/env API キーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 利用可能な auth/profile/model がない provider は skip する + - 利用可能な場合は、宣言された両方の runtime mode を実行する: + - プロンプトのみの入力による `generate` + - provider が `capabilities.edit.enabled` を宣言している場合の `edit` + - 現在の共有レーンのカバレッジ: + - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: 別個のComfy liveファイルであり、この共有スイープではない + - `comfy`: 別の Comfy live ファイルであり、この共有スイープではない - 任意の絞り込み: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- 任意のauth挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でprofile-store authを強制し、envのみの上書きを無視する +- 任意の auth 動作: + - profile-store auth を強制し、env-only 上書きを無視する `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Video generation live +## 動画生成 live - テスト: `extensions/video-generation-providers.live.test.ts` - 有効化: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- Harness: `pnpm test:live:media video` +- ハーネス: `pnpm test:live:media video` - 範囲: - - 共有の同梱video-generation providerパスを検証する - - デフォルトでは、release-safeなsmokeパスを使用する: FAL以外のプロバイダー、プロバイダーごとに1件のtext-to-videoリクエスト、1秒のlobster prompt、そして `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 由来のプロバイダーごとの操作上限（デフォルト `180000`） - - プロバイダー側のキュー待ち遅延がrelease時間を支配することがあるため、FALはデフォルトでskipされる。明示的に実行するには `--video-providers fal` または `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` を指定する - - probe前にlogin shell（`~/.profile`）からprovider env varsを読み込む - - デフォルトでは保存済みauth profileよりもlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠さない - - 使用可能なauth/profile/modelがないプロバイダーはskipする + - 共有のバンドル済み動画生成 provider パスを実行する + - デフォルトでは、リリースで安全なスモークパスを使用します: 非 FAL provider、provider ごとに 1 回の text-to-video リクエスト、1 秒の lobster プロンプト、そして `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`（デフォルト `180000`）に基づく provider ごとの操作上限 + - FAL は、provider 側のキュー遅延がリリース時間を大きく左右しうるため、デフォルトで skip されます。明示的に実行するには `--video-providers fal` または `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` を渡してください + - probe 前に login shell（`~/.profile`）から provider env vars を読み込む + - デフォルトでは保存済み auth profile より live/env API キーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のシェル認証情報を覆い隠しません + - 利用可能な auth/profile/model がない provider は skip する - デフォルトでは `generate` のみを実行する - - 利用可能な場合に宣言済みtransform modeも実行するには `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定する: - - プロバイダーが `capabilities.imageToVideo.enabled` を宣言し、選択したプロバイダー/モデルが共有スイープ内でbuffer-backedなローカルimage入力を受け付ける場合の `imageToVideo` - - プロバイダーが `capabilities.videoToVideo.enabled` を宣言し、選択したプロバイダー/モデルが共有スイープ内でbuffer-backedなローカルvideo入力を受け付ける場合の `videoToVideo` - - 共有スイープで現在は宣言済みだがskipされる `imageToVideo` プロバイダー: - - `vydra`。同梱の `veo3` はtext-onlyであり、同梱の `kling` はリモートimage URLを必要とするため - - プロバイダー固有のVydraカバレッジ: + - 利用可能な場合に宣言済み transform mode も実行するには `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定: + - provider が `capabilities.imageToVideo.enabled` を宣言し、選択された provider/model が共有スイープ内で buffer ベースのローカル画像入力を受け付ける場合の `imageToVideo` + - provider が `capabilities.videoToVideo.enabled` を宣言し、選択された provider/model が共有スイープ内で buffer ベースのローカル動画入力を受け付ける場合の `videoToVideo` + - 共有スイープで現在「宣言済みだが skip される」`imageToVideo` provider: + - `vydra`。バンドル済み `veo3` は text 専用で、バンドル済み `kling` はリモート画像 URL を必要とするため + - provider 固有の Vydra カバレッジ: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - このファイルは、`veo3` のtext-to-videoと、デフォルトでリモートimage URL fixtureを使う `kling` レーンを実行する - - 現在の `videoToVideo` liveカバレッジ: - - 選択したモデルが `runway/gen4_aleph` のときのみ `runway` - - 共有スイープで現在は宣言済みだがskipされる `videoToVideo` プロバイダー: - - `alibaba`、`qwen`、`xai`。これらのパスは現在リモート `http(s)` / MP4 reference URLを必要とするため - - `google`。現在の共有Gemini/Veoレーンはローカルのbuffer-backed入力を使っており、そのパスは共有スイープでは受け付けられないため - - `openai`。現在の共有レーンには組織固有のvideo inpaint/remixアクセス保証がないため + - このファイルは `veo3` の text-to-video と、デフォルトでリモート画像 URL fixture を使う `kling` レーンを実行します + - 現在の `videoToVideo` live カバレッジ: + - 選択されたモデルが `runway/gen4_aleph` の場合のみ `runway` + - 共有スイープで現在「宣言済みだが skip される」`videoToVideo` provider: + - `alibaba`、`qwen`、`xai`。これらのパスは現在、リモートの `http(s)` / MP4 参照 URL を必要とするため + - `google`。現在の共有 Gemini/Veo レーンはローカルの buffer ベース入力を使っており、そのパスは共有スイープでは受け付けられないため + - `openai`。現在の共有レーンには org 固有の video inpaint/remix アクセス保証がないため - 任意の絞り込み: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - FALを含むデフォルトスイープ内のすべてのプロバイダーを含めるには `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` - - 攻めたsmoke実行のために各プロバイダーの操作上限を短くするには `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` -- 任意のauth挙動: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でprofile-store authを強制し、envのみの上書きを無視する + - デフォルトスイープ内のすべての provider（FAL を含む）を含めるには `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` + - より攻めたスモーク実行のために、各 provider の操作上限を縮めるには `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` +- 任意の auth 動作: + - profile-store auth を強制し、env-only 上書きを無視する `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## Media live harness +## Media live ハーネス - コマンド: `pnpm test:live:media` - 目的: - - 共有のimage、music、video liveスイートを、1つのリポジトリネイティブentrypoint経由で実行する - - `~/.profile` から不足しているprovider env varsを自動読み込みする - - デフォルトで、現在使用可能なauthを持つプロバイダーに各スイートを自動で絞り込む - - `scripts/test-live.mjs` を再利用するため、Heartbeatおよびquiet-modeの挙動が一貫する + - 共有の画像、音楽、動画 live スイートを、リポジトリ標準の 1 つの entrypoint から実行する + - `~/.profile` から不足している provider env vars を自動読み込みする + - デフォルトで、現在利用可能な auth を持つ provider に各スイートを自動的に絞り込む + - `scripts/test-live.mjs` を再利用するため、Heartbeat と quiet-mode の挙動が一貫する - 例: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Dockerランナー（任意の「Linuxで動く」チェック） +## Docker ランナー（任意の「Linux でも動く」チェック） -これらのDockerランナーは2つのバケットに分かれます。 +これらの Docker ランナーは 2 つのバケットに分かれます。 -- Live-modelランナー: `test:docker:live-models` と `test:docker:live-gateway` は、対応するprofile-key liveファイルのみをリポジトリDocker image内で実行します（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）。ローカルconfigディレクトリとworkspaceをマウントし（マウントされていれば `~/.profile` も読み込みます）。対応するローカルentrypointは `test:live:models-profiles` と `test:live:gateway-profiles` です。 -- Docker liveランナーは、完全なDockerスイープを現実的に保つため、デフォルトでより小さいsmoke上限を使います: - `test:docker:live-models` はデフォルトで `OPENCLAW_LIVE_MAX_MODELS=12`、および +- Live-model ランナー: `test:docker:live-models` と `test:docker:live-gateway` は、リポジトリ Docker イメージ内で対応する profile-key live ファイルだけを実行します（`src/agents/models.profiles.live.test.ts` と `src/gateway/gateway-models.profiles.live.test.ts`）。ローカル config dir と workspace をマウントし（マウントされている場合は `~/.profile` も読み込みます）。対応するローカル entrypoint は `test:live:models-profiles` と `test:live:gateway-profiles` です。 +- Docker live ランナーは、完全な Docker スイープを実用的に保つため、デフォルトでより小さなスモーク上限を使用します: + `test:docker:live-models` はデフォルトで `OPENCLAW_LIVE_MAX_MODELS=12`、そして `test:docker:live-gateway` はデフォルトで `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`、および - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` を使用します。より大きい網羅スキャンを明示的に行いたい場合は、これらのenv varを上書きしてください。 -- `test:docker:all` は、まず `test:docker:live-build` 経由でlive Docker imageを一度ビルドし、その後2つのlive Dockerレーンでそれを再利用します。 -- Container smokeランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels`、および `test:docker:plugins` は、1つ以上の実コンテナを起動し、より高レベルのintegrationパスを検証します。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` を設定します。より大きな網羅スキャンを明示的に行いたい場合は、これらの env var を上書きしてください。 +- `test:docker:all` は、まず `test:docker:live-build` で live Docker イメージを 1 回だけビルドし、その後 2 つの live Docker レーンでそれを再利用します。 +- Container スモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:plugins` は、1 つ以上の実際のコンテナを起動し、より高レベルな integration パスを検証します。 -live-model Dockerランナーは、必要なCLI auth homeだけをbind-mountし（実行が絞り込まれていない場合はサポート対象すべて）、その後、外部CLI OAuthがホストauth storeを変更せずにトークンを更新できるよう、実行前にそれらをコンテナhomeにコピーします。 +Live-model Docker ランナーは、必要な CLI auth home のみ（実行が絞り込まれていない場合はサポート対象すべて）も bind-mount し、実行前にそれらをコンテナ home にコピーするため、外部 CLI OAuth がホスト auth store を変更せずに token を更新できます。 -- Direct models: `pnpm test:docker:live-models`（スクリプト: `scripts/test-live-models-docker.sh`） -- ACP bind smoke: `pnpm test:docker:live-acp-bind`（スクリプト: `scripts/test-live-acp-bind-docker.sh`） -- CLI backend smoke: `pnpm test:docker:live-cli-backend`（スクリプト: `scripts/test-live-cli-backend-docker.sh`） -- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness`（スクリプト: `scripts/test-live-codex-harness-docker.sh`） +- 直接モデル: `pnpm test:docker:live-models`（スクリプト: `scripts/test-live-models-docker.sh`） +- ACP bind スモーク: `pnpm test:docker:live-acp-bind`（スクリプト: `scripts/test-live-acp-bind-docker.sh`） +- CLI バックエンドスモーク: `pnpm test:docker:live-cli-backend`（スクリプト: `scripts/test-live-cli-backend-docker.sh`） +- Codex app-server harness スモーク: `pnpm test:docker:live-codex-harness`（スクリプト: `scripts/test-live-codex-harness-docker.sh`） - Gateway + dev agent: `pnpm test:docker:live-gateway`（スクリプト: `scripts/test-live-gateway-models-docker.sh`） -- Open WebUI live smoke: `pnpm test:docker:openwebui`（スクリプト: `scripts/e2e/openwebui-docker.sh`） -- オンボーディングウィザード（TTY、完全なscaffolding）: `pnpm test:docker:onboard`（スクリプト: `scripts/e2e/onboard-docker.sh`） -- Gateway networking（2コンテナ、WS auth + health）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） -- MCP channel bridge（seed済みGateway + stdio bridge + 生のClaude notification-frame smoke）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） -- Plugins（install smoke + `/plugin` エイリアス + Claude-bundle restart semantics）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） +- Open WebUI live スモーク: `pnpm test:docker:openwebui`（スクリプト: `scripts/e2e/openwebui-docker.sh`） +- オンボーディング ウィザード（TTY、完全な scaffolding）: `pnpm test:docker:onboard`（スクリプト: `scripts/e2e/onboard-docker.sh`） +- Gateway networking（2 コンテナ、WS auth + health）: `pnpm test:docker:gateway-network`（スクリプト: `scripts/e2e/gateway-network-docker.sh`） +- MCP channel bridge（seed 済み Gateway + stdio bridge + 生の Claude notification-frame スモーク）: `pnpm test:docker:mcp-channels`（スクリプト: `scripts/e2e/mcp-channels-docker.sh`） +- Plugins（インストールスモーク + `/plugin` エイリアス + Claude バンドルの再起動セマンティクス）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-docker.sh`） -live-model Dockerランナーは、現在のcheckoutもread-onlyでbind-mountし、 -コンテナ内の一時workdirにそれを配置します。これによりruntime -imageをスリムに保ちつつ、正確にあなたのローカルsource/configに対してVitestを実行できます。 -この配置ステップでは、大きなローカル専用キャッシュやアプリbuild出力、たとえば +Live-model Docker ランナーは、現在の checkout を read-only で bind-mount し、 +コンテナ内の一時 workdir にステージもします。これにより、runtime +イメージをスリムに保ちながら、正確にその手元の source/config に対して Vitest を実行できます。 +このステージング手順では、大きなローカル専用キャッシュやアプリ build 出力、たとえば `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの `.build` や -Gradle出力ディレクトリをskipするため、Docker live実行が -マシン固有アーティファクトのコピーに何分も費やしません。 -また、`OPENCLAW_SKIP_CHANNELS=1` も設定するため、gateway live probeが -コンテナ内で実際のTelegram/Discordなどのchannel workerを起動しません。 +Gradle 出力ディレクトリをスキップするため、Docker live 実行が +マシン固有の成果物をコピーするのに何分も費やすことがありません。 +また、Gateway live probe がコンテナ内で実際の Telegram/Discord などの channel worker を起動しないよう、 +`OPENCLAW_SKIP_CHANNELS=1` も設定します。 `test:docker:live-models` は引き続き `pnpm test:live` を実行するため、 -そのDockerレーンでgateway liveカバレッジを絞り込んだり除外したりする必要がある場合は +その Docker レーンで Gateway live カバレッジを絞り込む、または除外したい場合は `OPENCLAW_LIVE_GATEWAY_*` も渡してください。 -`test:docker:openwebui` はより高レベルの互換smokeです。これは、 -OpenAI互換HTTP endpointを有効にしたOpenClaw gatewayコンテナを起動し、 -そのgatewayに対して固定版Open WebUIコンテナを起動し、 -Open WebUI経由でサインインし、 -`/api/models` が `openclaw/default` を公開していることを検証し、その後 -Open WebUIの `/api/chat/completions` proxyを通して実際のchatリクエストを送信します。 -初回実行は、Dockerが -Open WebUI imageをpullする必要がある場合や、Open WebUI自身のcold-start setupを完了する必要がある場合があるため、目に見えて遅くなることがあります。 -このレーンは使用可能なlive modelキーを必要とし、Docker化された実行では -`OPENCLAW_PROFILE_FILE` -（デフォルト `~/.profile`）がそれを提供する主な方法です。 -成功した実行では `{ "ok": true, "model": -"openclaw/default", ... }` のような小さなJSON payloadが出力されます。 +`test:docker:openwebui` は、より高レベルな互換性スモークです。これは +OpenAI 互換 HTTP endpoint を有効にした OpenClaw Gateway コンテナを起動し、 +その Gateway に対して固定版の Open WebUI コンテナを起動し、Open WebUI 経由でサインインし、 +`/api/models` が `openclaw/default` を公開していることを確認した後、 +Open WebUI の `/api/chat/completions` proxy を通じて実際の chat リクエストを送信します。 +初回実行は目立って遅くなることがあります。Docker が +Open WebUI イメージを pull する必要がある場合があり、さらに Open WebUI 自身のコールドスタートセットアップ完了を待つ必要があるためです。 +このレーンは利用可能な live model key を前提としており、 +Docker 化実行でそれを提供する主要な方法は `OPENCLAW_PROFILE_FILE` +（デフォルト `~/.profile`）です。 +成功した実行では、`{ "ok": true, "model": +"openclaw/default", ... }` のような小さな JSON payload が出力されます。 `test:docker:mcp-channels` は意図的に決定的であり、実際の -Telegram、Discord、または iMessage アカウントを必要としません。これはseed済みGateway -コンテナを起動し、次に `openclaw mcp serve` を起動する2つ目のコンテナを開始し、 -その後、実際のstdio MCP bridge上で、ルーティングされたconversation discovery、transcript読み取り、attachment metadata、 -live event queueの挙動、outbound send routing、そしてClaude形式のchannel + -permission notificationを検証します。notificationチェックでは -生のstdio MCP frameを直接検査するため、このsmokeは -特定のclient SDKがたまたま表面化するものだけでなく、bridgeが実際に何を出力するかを検証します。 +Telegram、Discord、または iMessage アカウントを必要としません。これは seed 済み Gateway +コンテナを起動し、続いて `openclaw mcp serve` を起動する 2 つ目のコンテナを開始し、 +ルーティングされた conversation discovery、transcript 読み取り、attachment metadata、 +live event queue の挙動、outbound send ルーティング、さらに Claude 形式の channel + +permission notification を、実際の stdio MCP bridge 上で検証します。notification チェックは +生の stdio MCP frame を直接検査するため、このスモークは特定の client SDK がたまたま表面化するものだけでなく、 +bridge が実際に出力するものを検証します。 -手動ACP平文thread smoke（CIではない）: +手動の ACP プレーンランゲージ thread スモーク（CI ではない）: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- このスクリプトはリグレッション/デバッグワークフロー用に保持してください。ACP thread routing検証で再度必要になる可能性があるため、削除しないでください。 +- このスクリプトはリグレッション/デバッグワークフロー用として保持してください。ACP thread ルーティング検証のために再び必要になる可能性があるので、削除しないでください。 -便利なenv var: +便利な env vars: -- `OPENCLAW_CONFIG_DIR=...`（デフォルト: `~/.openclaw`）を `/home/node/.openclaw` にマウント -- `OPENCLAW_WORKSPACE_DIR=...`（デフォルト: `~/.openclaw/workspace`）を `/home/node/.openclaw/workspace` にマウント -- `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`）を `/home/node/.profile` にマウントし、テスト実行前に読み込む -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` で、`OPENCLAW_PROFILE_FILE` から読み込まれたenv varのみを検証し、一時的なconfig/workspaceディレクトリを使い、外部CLI authマウントは行わない -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`）を `/home/node/.npm-global` にマウントし、Docker内のCLI installキャッシュに使う -- `$HOME` 配下の外部CLI authディレクトリ/ファイルは `/host-auth...` 配下にread-onlyでマウントされ、その後テスト開始前に `/home/node/...` にコピーされる +- `/home/node/.openclaw` にマウントされる `OPENCLAW_CONFIG_DIR=...`（デフォルト: `~/.openclaw`） +- `/home/node/.openclaw/workspace` にマウントされる `OPENCLAW_WORKSPACE_DIR=...`（デフォルト: `~/.openclaw/workspace`） +- `/home/node/.profile` にマウントされ、テスト実行前に読み込まれる `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`） +- `OPENCLAW_PROFILE_FILE` から読み込んだ env vars のみを検証し、一時 config/workspace dir を使い、外部 CLI auth mount を使わない `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` +- Docker 内でキャッシュされた CLI インストール用に `/home/node/.npm-global` にマウントされる `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（デフォルト: `~/.cache/openclaw/docker-cli-tools`） +- `$HOME` 配下の外部 CLI auth ディレクトリ/ファイルは `/host-auth...` 配下に read-only でマウントされ、その後テスト開始前に `/home/node/...` にコピーされます - デフォルトディレクトリ: `.minimax` - - デフォルトファイル: `~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 絞り込み済みプロバイダー実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推定された必要なディレクトリ/ファイルのみをマウントする - - 手動で上書きするには `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストを使う -- 実行を絞るには `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` -- コンテナ内でプロバイダーを絞り込むには `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` -- rebuildが不要な再実行で既存の `openclaw:local-live` imageを再利用するには `OPENCLAW_SKIP_DOCKER_BUILD=1` -- 認証情報がprofile store由来であることを保証するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`（envではない） -- Open WebUI smoke向けにgatewayが公開するモデルを選ぶには `OPENCLAW_OPENWEBUI_MODEL=...` -- Open WebUI smokeで使うnonce-check promptを上書きするには `OPENCLAW_OPENWEBUI_PROMPT=...` -- 固定されたOpen WebUI image tagを上書きするには `OPENWEBUI_IMAGE=...` + - デフォルトファイル: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` + - 絞り込まれた provider 実行では、`OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` から推論された必要なディレクトリ/ファイルのみをマウントします + - `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`、または `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` のようなカンマ区切りリストで手動上書きできます +- 実行を絞り込む `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` +- コンテナ内で provider を絞り込む `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` +- 再ビルド不要の再実行で既存の `openclaw:local-live` イメージを再利用する `OPENCLAW_SKIP_DOCKER_BUILD=1` +- 認証情報が profile store から来ることを保証する `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`（env ではない） +- Open WebUI スモークで Gateway が公開するモデルを選ぶ `OPENCLAW_OPENWEBUI_MODEL=...` +- Open WebUI スモークで使う nonce チェックプロンプトを上書きする `OPENCLAW_OPENWEBUI_PROMPT=...` +- 固定された Open WebUI イメージタグを上書きする `OPENWEBUI_IMAGE=...` -## ドキュメントの健全性確認 +## ドキュメント健全性チェック -ドキュメント編集後はdocsチェックを実行してください: `pnpm check:docs`。 -ページ内見出しチェックも必要な場合は、完全なMintlify anchor検証を実行してください: `pnpm docs:check-links:anchors`。 +ドキュメント編集後は `pnpm check:docs` を実行してください。 +インページ見出しチェックも必要な場合は、完全な Mintlify アンカー検証として `pnpm docs:check-links:anchors` を実行してください。 -## オフラインリグレッション（CI-safe） +## オフラインリグレッション（CI 安全） -これらは、実際のプロバイダーなしでの「実際のパイプライン」リグレッションです。 +これらは、実際のプロバイダーなしでの「実パイプライン」リグレッションです。 -- Gateway tool calling（mock OpenAI、実際のgateway + agent loop）: `src/gateway/gateway.test.ts`（ケース: "runs a mock OpenAI tool call end-to-end via gateway agent loop"） -- Gatewayウィザード（WS `wizard.start`/`wizard.next`、config + auth enforcedを書き込む）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） +- Gateway tool calling（mock OpenAI、実際の Gateway + agent loop）: `src/gateway/gateway.test.ts`（ケース: 「runs a mock OpenAI tool call end-to-end via gateway agent loop」） +- Gateway ウィザード（WS `wizard.start`/`wizard.next`、config + auth 書き込みを強制）: `src/gateway/gateway.test.ts`（ケース: 「runs wizard over ws and writes auth token config」） -## Agent reliability evals（Skills） +## agent 信頼性 evals（Skills） -すでに、次のようなCI-safeテストがいくつかあり、「agent reliability evals」のように振る舞います。 +すでに、いくつかの CI 安全なテストが「agent 信頼性 evals」のように振る舞います。 -- 実際のgateway + agent loopを通したmock tool-calling（`src/gateway/gateway.test.ts`）。 -- session wiringとconfig効果を検証するend-to-endウィザードフロー（`src/gateway/gateway.test.ts`）。 +- 実際の Gateway + agent loop を通じた mock tool-calling（`src/gateway/gateway.test.ts`）。 +- session 配線と config の効果を検証する end-to-end のウィザードフロー（`src/gateway/gateway.test.ts`）。 -Skillsに関してまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: +Skills に関してまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: -- **Decisioning:** promptにSkillsが列挙されているとき、agentは適切なskillを選ぶか（または無関係なものを避けるか）？ -- **Compliance:** agentは使用前に `SKILL.md` を読み、必要な手順/引数に従うか？ -- **Workflow contracts:** tool順序、session履歴の引き継ぎ、sandbox境界を検証するマルチターンシナリオ。 +- **Decisioning:** prompt に Skills が列挙されているとき、agent は正しい skill を選ぶか（または無関係なものを避けるか）？ +- **Compliance:** agent は使用前に `SKILL.md` を読み、必要な手順/args に従うか？ +- **Workflow contracts:** tool の順序、session history の引き継ぎ、sandbox 境界を検証する複数ターンのシナリオ。 -将来のevalは、まず決定的であることを維持すべきです。 +今後の eval は、まず決定的であることを優先すべきです。 -- mock providerを使ってtool呼び出し + 順序、skillファイル読み取り、session配線を検証するscenario runner。 -- skillに焦点を当てた小規模シナリオスイート（使う vs 使わない、gating、prompt injection）。 -- CI-safeスイートが整った後にのみ、任意のlive eval（オプトイン、env-gated）。 +- mock provider を使って tool call + 順序、skill file の読み取り、session 配線を検証するシナリオランナー。 +- skill に焦点を当てた小規模シナリオスイート（使う vs 避ける、gating、prompt injection）。 +- CI 安全なスイートを整備した後にのみ、任意の live eval（オプトイン、env-gated）。 -## 契約テスト（Pluginおよびchannelの形状） +## Contract テスト（Plugin と channel の形状） -契約テストは、登録されたすべてのPluginおよびchannelが、それぞれの -interface契約に準拠していることを検証します。検出されたすべてのPluginを反復し、 -形状と振る舞いに関する一連の検証を実行します。デフォルトの `pnpm test` unitレーンは、 -これらの共有seamおよびsmokeファイルを意図的にskipします。共有channelまたはprovider surfaceに触れた場合は、 -契約コマンドを明示的に実行してください。 +Contract テストは、登録されたすべての Plugin と channel がその +interface 契約に適合していることを検証します。これらは検出されたすべての Plugin を走査し、形状と挙動に関する一連の検証を実行します。デフォルトの `pnpm test` unit レーンでは、これらの共有シームおよびスモークファイルは意図的にスキップされます。共有 channel または provider surface に触れる場合は、contract コマンドを明示的に実行してください。 ### コマンド -- すべての契約: `pnpm test:contracts` -- channel契約のみ: `pnpm test:contracts:channels` -- provider契約のみ: `pnpm test:contracts:plugins` +- すべての contract: `pnpm test:contracts` +- channel contract のみ: `pnpm test:contracts:channels` +- provider contract のみ: `pnpm test:contracts:plugins` -### Channel契約 +### Channel contract `src/channels/plugins/contracts/*.contract.test.ts` にあります: -- **plugin** - 基本的なPlugin形状（id、name、capabilities） -- **setup** - セットアップウィザード契約 -- **session-binding** - session bindingの挙動 -- **outbound-payload** - message payload構造 -- **inbound** - inbound message処理 +- **plugin** - 基本的な Plugin 形状（id、name、capabilities） +- **setup** - セットアップ ウィザード契約 +- **session-binding** - session binding の挙動 +- **outbound-payload** - message payload 構造 +- **inbound** - inbound message の処理 - **actions** - channel action handler -- **threading** - thread ID処理 +- **threading** - thread ID の処理 - **directory** - directory/roster API -- **group-policy** - group policyの強制 +- **group-policy** - group policy の強制 -### Provider status契約 +### Provider status contract `src/plugins/contracts/*.contract.test.ts` にあります。 - **status** - channel status probe -- **registry** - Plugin registry形状 +- **registry** - Plugin registry の形状 -### Provider契約 +### Provider contract `src/plugins/contracts/*.contract.test.ts` にあります: -- **auth** - auth flow契約 -- **auth-choice** - auth choice/selection +- **auth** - auth フロー契約 +- **auth-choice** - auth の選択/selection - **catalog** - model catalog API - **discovery** - Plugin discovery - **loader** - Plugin loading - **runtime** - provider runtime -- **shape** - Plugin shape/interface -- **wizard** - セットアップウィザード +- **shape** - Plugin の形状/interface +- **wizard** - セットアップ ウィザード ### 実行するタイミング -- plugin-sdkのexportまたはsubpathを変更した後 -- channelまたはprovider Pluginを追加または変更した後 -- Plugin登録またはdiscoveryをリファクタリングした後 +- plugin-sdk の export または subpath を変更した後 +- channel または provider Plugin を追加または変更した後 +- Plugin 登録または discovery をリファクタリングした後 -契約テストはCIで実行され、実際のAPIキーは不要です。 +Contract テストは CI で実行され、実際の API キーは必要ありません。 ## リグレッションを追加する（ガイダンス） -liveで見つかったprovider/modelの問題を修正するとき: +live で見つかった provider/model の問題を修正するとき: -- 可能ならCI-safeなリグレッションを追加する（mock/stub provider、または正確なrequest-shape変換をキャプチャする） -- 本質的にlive-onlyな場合（rate limit、auth policy）は、liveテストを狭く保ち、env var経由のオプトインにする -- バグを捕捉できる最小の層を対象にすることを優先する: - - provider request conversion/replay bug → direct modelsテスト - - gateway session/history/tool pipeline bug → gateway live smokeまたはCI-safeなgateway mockテスト -- SecretRef traversal guardrail: - - `src/secrets/exec-secret-ref-id-parity.test.ts` は、registry metadata（`listSecretTargetRegistryEntries()`）からSecretRefクラスごとに1つのサンプルtargetを導出し、その後、traversal-segment exec idが拒否されることを検証します。 - - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef targetファミリーを追加した場合は、そのテスト内の `classifyTargetClass` を更新してください。このテストは、未分類のtarget idに対して意図的に失敗するため、新しいクラスが黙ってskipされることはありません。 +- 可能であれば、CI 安全なリグレッションを追加してください（mock/stub provider、または正確な request-shape 変換をキャプチャ） +- 本質的に live 専用の問題（rate limit、auth policy）なら、live テストは狭く保ち、env vars 経由のオプトインにしてください +- バグを検出できる最小レイヤーを狙うことを優先してください: + - provider request conversion/replay のバグ → 直接モデルテスト + - Gateway session/history/tool パイプラインのバグ → Gateway live スモークまたは CI 安全な Gateway mock テスト +- SecretRef 走査ガードレール: + - `src/secrets/exec-secret-ref-id-parity.test.ts` は、registry metadata（`listSecretTargetRegistryEntries()`）から SecretRef class ごとに 1 つのサンプル target を導出し、その後 traversal-segment exec id が拒否されることを検証します。 + - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef target family を追加する場合は、そのテスト内の `classifyTargetClass` を更新してください。このテストは、分類されていない target id に対して意図的に失敗するため、新しい class が黙ってスキップされることはありません。 diff --git a/docs/ja-JP/install/index.md b/docs/ja-JP/install/index.md index 40d2151e1..44a8a4435 100644 --- a/docs/ja-JP/install/index.md +++ b/docs/ja-JP/install/index.md @@ -1,15 +1,15 @@ --- read_when: - - はじめにのクイックスタート以外のインストール方法が必要な場合 + - 「はじめに」のクイックスタート以外のインストール方法が必要です - クラウドプラットフォームにデプロイしたい場合 - - 更新、移行、またはアンインストールが必要な場合 -summary: OpenClawのインストール — インストーラースクリプト、npm/pnpm/bun、ソースから、Dockerなど + - 更新、移行、またはアンインストールを行う必要がある場合 +summary: OpenClawをインストール — インストーラースクリプト、npm/pnpm/bun、ソースから、Docker、その他 title: インストール x-i18n: - generated_at: "2026-04-05T12:48:23Z" + generated_at: "2026-04-20T04:46:34Z" model: gpt-5.4 provider: openai - source_hash: eca17c76a2a66166b3d8cda9dc3144ab920d30ad0ed2a220eb9389d7a383ba5d + source_hash: ad0a5fdbbf13dcaf2fed6840f35aa22b2e9e458509509f98303c8d87c2556a6f source_path: install/index.md workflow: 15 --- @@ -18,7 +18,7 @@ x-i18n: ## 推奨: インストーラースクリプト -最も速いインストール方法です。OSを検出し、必要に応じてNodeをインストールし、OpenClawをインストールして、オンボーディングを開始します。 +最も速くインストールする方法です。OSを検出し、必要に応じてNodeをインストールし、OpenClawをインストールして、オンボーディングを開始します。 @@ -48,29 +48,27 @@ x-i18n: -すべてのフラグとCI/自動化オプションについては、[Installer internals](/install/installer) を参照してください。 +すべてのフラグとCI/自動化オプションについては、[インストーラーの内部](/ja-JP/install/installer)を参照してください。 ## システム要件 -- **Node 24**（推奨）または Node 22.14+ — インストーラースクリプトがこれを自動で処理します -- **macOS、Linux、またはWindows** — ネイティブWindowsとWSL2の両方をサポートしています。WSL2のほうがより安定しています。[Windows](/platforms/windows) を参照してください。 -- `pnpm` はソースからビルドする場合にのみ必要です +- **Node 24**（推奨）またはNode 22.14+ — インストーラースクリプトがこれを自動的に処理します +- **macOS、Linux、またはWindows** — ネイティブWindowsとWSL2の両方をサポートしています。WSL2のほうがより安定しています。[Windows](/ja-JP/platforms/windows)を参照してください。 +- ソースからビルドする場合にのみ`pnpm`が必要です -## 別のインストール方法 +## 代替のインストール方法 ### ローカルプレフィックスインストーラー（`install-cli.sh`） -システム全体のNodeインストールに依存せず、 -`~/.openclaw` のようなローカルプレフィックス配下にOpenClawとNodeを保持したい場合に使用します: +システム全体のNodeインストールに依存せず、`~/.openclaw`のようなローカルプレフィックス配下にOpenClawとNodeを保持したい場合に使用します: ```bash curl -fsSL https://openclaw.ai/install-cli.sh | bash ``` -デフォルトでnpmインストールをサポートし、同じ -プレフィックスフローでgit checkoutインストールにも対応しています。完全なリファレンス: [Installer internals](/install/installer#install-clish)。 +デフォルトでnpmインストールをサポートし、同じプレフィックスフロー内でgitチェックアウトからのインストールにも対応しています。完全なリファレンス: [インストーラーの内部](/ja-JP/install/installer#install-clish)。 -### npm、pnpm、または bun +### npm、pnpm、またはbun すでに自分でNodeを管理している場合: @@ -89,7 +87,7 @@ curl -fsSL https://openclaw.ai/install-cli.sh | bash ``` - pnpmでは、ビルドスクリプトを持つパッケージに明示的な承認が必要です。最初のインストール後に `pnpm approve-builds -g` を実行してください。 + pnpmでは、ビルドスクリプトを含むパッケージに対して明示的な承認が必要です。最初のインストール後に`pnpm approve-builds -g`を実行してください。 @@ -100,14 +98,14 @@ curl -fsSL https://openclaw.ai/install-cli.sh | bash ``` - BunはグローバルCLIインストール経路でサポートされています。Gatewayランタイムについては、引き続きNodeが推奨デーモンランタイムです。 + BunはグローバルCLIインストール経路でサポートされています。Gatewayランタイムについては、引き続きNodeが推奨のデーモンランタイムです。 - - グローバルにインストールされたlibvipsが原因で `sharp` が失敗する場合: + + グローバルにインストールされたlibvipsが原因で`sharp`が失敗する場合: ```bash SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest @@ -117,19 +115,19 @@ SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest ### ソースから -コントリビューターや、ローカルcheckoutから実行したい人向け: +コントリビューターや、ローカルのチェックアウトから実行したい人向け: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw -pnpm install && pnpm ui:build && pnpm build +pnpm install && pnpm build && pnpm ui:build pnpm link --global openclaw onboard --install-daemon ``` -または、linkをスキップしてリポジトリ内から `pnpm openclaw ...` を使用することもできます。完全な開発ワークフローについては [Setup](/start/setup) を参照してください。 +または、linkをスキップして、リポジトリ内で`pnpm openclaw ...`を使用してください。完全な開発ワークフローについては、[セットアップ](/ja-JP/start/setup)を参照してください。 -### GitHub main からインストール +### GitHub mainからインストール ```bash npm install -g github:openclaw/openclaw#main @@ -138,20 +136,20 @@ npm install -g github:openclaw/openclaw#main ### コンテナとパッケージマネージャー - - コンテナ化またはヘッドレスのデプロイ。 + + コンテナ化またはヘッドレスデプロイ。 - - Dockerのrootlessコンテナ代替。 + + Dockerのrootlessなコンテナ代替手段。 - + Nix flakeによる宣言的インストール。 - + 自動化されたフリートプロビジョニング。 - - BunランタイムによるCLI専用利用。 + + Bunランタイム経由のCLI専用利用。 @@ -160,60 +158,60 @@ npm install -g github:openclaw/openclaw#main ```bash openclaw --version # CLIが利用可能であることを確認 openclaw doctor # 設定の問題を確認 -openclaw gateway status # Gatewayが動作していることを確認 +openclaw gateway status # Gatewayが実行中であることを確認 ``` -インストール後に管理された起動を使いたい場合: +インストール後に管理された起動を使用したい場合: -- macOS: `openclaw onboard --install-daemon` または `openclaw gateway install` によるLaunchAgent -- Linux/WSL2: 同じコマンドによるsystemd user service -- ネイティブWindows: まずScheduled Task、タスク作成が拒否された場合はユーザーごとのStartup-folderログイン項目へフォールバック +- macOS: `openclaw onboard --install-daemon`または`openclaw gateway install`によるLaunchAgent +- Linux/WSL2: 同じコマンドによるsystemdユーザーサービス +- ネイティブWindows: まずScheduled Task、タスク作成が拒否された場合はユーザーごとのStartupフォルダーのログイン項目にフォールバック ## ホスティングとデプロイ クラウドサーバーまたはVPSにOpenClawをデプロイします: - 任意のLinux VPS - 共通のDocker手順 - K8s - Fly.io - Hetzner - Google Cloud - Azure - Railway - Render - Northflank + 任意のLinux VPS + 共通のDocker手順 + K8s + Fly.io + Hetzner + Google Cloud + Azure + Railway + Render + Northflank ## 更新、移行、またはアンインストール - - OpenClawを最新に保ちます。 + + OpenClawを最新の状態に保ちます。 - - 新しいマシンへ移行します。 + + 新しいマシンに移動します。 - + OpenClawを完全に削除します。 -## トラブルシューティング: `openclaw` が見つからない +## トラブルシューティング: `openclaw`が見つからない -インストールは成功したのに、ターミナルで `openclaw` が見つからない場合: +インストールは成功したのに、ターミナルで`openclaw`が見つからない場合: ```bash -node -v # Nodeはインストール済み? -npm prefix -g # グローバルパッケージはどこにある? -echo "$PATH" # グローバルbinディレクトリはPATHに入っている? +node -v # Nodeはインストール済みですか？ +npm prefix -g # グローバルパッケージはどこにありますか？ +echo "$PATH" # グローバルbinディレクトリはPATHに含まれていますか？ ``` -`$(npm prefix -g)/bin` が `$PATH` にない場合は、シェル起動ファイル（`~/.zshrc` または `~/.bashrc`）に追加してください: +`$(npm prefix -g)/bin`が`$PATH`に含まれていない場合は、シェルの起動ファイル（`~/.zshrc`または`~/.bashrc`）に追加してください: ```bash export PATH="$(npm prefix -g)/bin:$PATH" ``` -その後、新しいターミナルを開いてください。詳細は [Node setup](/install/node) を参照してください。 +その後、新しいターミナルを開いてください。詳細は[Nodeセットアップ](/ja-JP/install/node)を参照してください。 diff --git a/docs/ja-JP/platforms/windows.md b/docs/ja-JP/platforms/windows.md index 91f832b95..9dcd0f0fb 100644 --- a/docs/ja-JP/platforms/windows.md +++ b/docs/ja-JP/platforms/windows.md @@ -1,57 +1,54 @@ --- read_when: - - WindowsにOpenClawをインストールする - - ネイティブWindowsとWSL2のどちらを選ぶか検討している - - Windows companion appの状況を知りたい -summary: 'Windowsサポート: ネイティブ環境とWSL2のインストール経路、daemon、現在の注意点' + - WindowsへのOpenClawのインストール + - ネイティブWindowsとWSL2の選び方 + - Windowsコンパニオンアプリの状況を確認する +summary: 'Windowsサポート: ネイティブおよびWSL2のインストールパス、デーモン、現在の注意事項' title: Windows x-i18n: - generated_at: "2026-04-05T12:51:27Z" + generated_at: "2026-04-20T04:46:33Z" model: gpt-5.4 provider: openai - source_hash: 7d9819206bdd65cf03519c1bc73ed0c7889b0ab842215ea94343262300adfd14 + source_hash: 1e7451c785a1d75c809522ad93e2c44a00b211f77f14c5c489fd0b01840d3fe2 source_path: platforms/windows.md workflow: 15 --- # Windows -OpenClawは**ネイティブWindows**と**WSL2**の両方をサポートしています。WSL2のほうが -より安定した経路であり、完全な体験には推奨されます。CLI、Gateway、toolingは -Linux内で動作し、完全な互換性があります。ネイティブWindowsでも -コアのCLIとGatewayは利用できますが、以下の注意点があります。 +OpenClawは**ネイティブWindows**と**WSL2**の両方をサポートしています。WSL2のほうがより安定したパスであり、フル体験には推奨されています。CLI、Gateway、各種ツールはLinux内で完全な互換性をもって動作します。ネイティブWindowsでも中核となるCLIとGatewayの利用は可能ですが、以下に記載するいくつかの注意事項があります。 -ネイティブWindows companion appは計画中です。 +ネイティブWindows向けコンパニオンアプリは計画中です。 ## WSL2（推奨） - [はじめに](/ja-JP/start/getting-started)（WSL内で使用） -- [インストールと更新](/install/updating) +- [インストールと更新](/ja-JP/install/updating) - 公式WSL2ガイド（Microsoft）: [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install) ## ネイティブWindowsの現状 -ネイティブWindowsのCLIフローは改善が進んでいますが、依然としてWSL2が推奨経路です。 +ネイティブWindowsでのCLIフローは改善が進んでいますが、依然としてWSL2が推奨パスです。 -現在ネイティブWindowsでうまく動作するもの: +現在ネイティブWindowsで問題なく動作するもの: -- `install.ps1` によるwebsite installer +- `install.ps1` を使ったWebサイト経由のインストーラー - `openclaw --version`、`openclaw doctor`、`openclaw plugins list --json` などのローカルCLI利用 -- 次のような埋め込みlocal-agent/provider smoke: +- 次のような組み込みのlocal-agent/providerスモークテスト: ```powershell openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK." ``` -現在の注意点: +現在の注意事項: -- `openclaw onboard --non-interactive` は、`--skip-health` を渡さない限り、到達可能なローカルGatewayを引き続き前提とします -- `openclaw onboard --non-interactive --install-daemon` と `openclaw gateway install` は、まずWindows Scheduled Tasksを試します -- Scheduled Taskの作成が拒否された場合、OpenClawはユーザーごとのStartupフォルダーのlogin itemにフォールバックし、すぐにGatewayを起動します -- `schtasks` 自体がハングしたり応答しなくなったりした場合、OpenClawは永遠に待機する代わりに、その経路をすばやく中止してフォールバックします -- より良いsupervisor statusを提供するため、利用可能な場合は引き続きScheduled Tasksが優先されます +- `openclaw onboard --non-interactive` は、`--skip-health` を渡さない限り、到達可能なローカルGatewayを引き続き必要とします +- `openclaw onboard --non-interactive --install-daemon` と `openclaw gateway install` は、まずWindowsのScheduled Tasksを試します +- Scheduled Taskの作成が拒否された場合、OpenClawはユーザーごとのStartupフォルダー内ログイン項目にフォールバックし、ただちにGatewayを起動します +- `schtasks` 自体がハングしたり応答しなくなった場合、OpenClawはそのパスをすばやく中止し、無限に待機するのではなくフォールバックするようになりました +- 利用可能な場合でも、より良い supervisor の状態確認を提供できるため、引き続きScheduled Tasksが優先されます -ネイティブCLIのみを使い、Gateway service installを行わない場合は、次のいずれかを使ってください。 +ネイティブCLIのみを使いたい場合で、Gatewayサービスのインストールが不要なら、次のいずれかを使ってください: ```powershell openclaw onboard --non-interactive --skip-health @@ -65,14 +62,14 @@ openclaw gateway install openclaw gateway status --json ``` -Scheduled Taskの作成がブロックされる場合でも、フォールバックservice modeは現在のユーザーのStartupフォルダーを通じてログイン後に自動起動します。 +Scheduled Taskの作成がブロックされる場合でも、フォールバックのサービスモードは現在のユーザーのStartupフォルダー経由で、ログイン後に自動起動します。 ## Gateway -- [Gateway runbook](/gateway) -- [Configuration](/gateway/configuration) +- [Gatewayランブック](/ja-JP/gateway) +- [設定](/ja-JP/gateway/configuration) -## Gateway service install（CLI） +## Gatewayサービスのインストール（CLI） WSL2内では: @@ -92,9 +89,9 @@ openclaw gateway install openclaw configure ``` -プロンプトが表示されたら **Gateway service** を選択してください。 +プロンプトが表示されたら、**Gateway service** を選択してください。 -修復/移行: +修復／移行: ``` openclaw doctor @@ -102,10 +99,9 @@ openclaw doctor ## Windowsログイン前にGatewayを自動起動する -ヘッドレス構成では、誰も -Windowsへログインしていなくても、完全な起動チェーンが動作するようにしてください。 +ヘッドレス構成では、誰もWindowsにログインしなくても、起動チェーン全体が実行されるようにしてください。 -### 1) ログインなしでもユーザーserviceを動かし続ける +### 1) ログインなしでもユーザーサービスを動かし続ける WSL内で: @@ -113,7 +109,7 @@ WSL内で: sudo loginctl enable-linger "$(whoami)" ``` -### 2) OpenClaw Gateway user serviceをインストールする +### 2) OpenClaw Gatewayユーザーサービスをインストールする WSL内で: @@ -123,13 +119,13 @@ openclaw gateway install ### 3) Windows起動時にWSLを自動起動する -PowerShellをAdministratorとして開いて実行: +管理者としてPowerShellで: ```powershell schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM ``` -`Ubuntu` は次のコマンドで確認できるdistro名に置き換えてください。 +`Ubuntu` は、次のコマンドで表示されるディストリビューション名に置き換えてください: ```powershell wsl --list --verbose @@ -137,21 +133,18 @@ wsl --list --verbose ### 起動チェーンを確認する -再起動後（Windowsサインイン前）、WSLから次を確認します。 +再起動後（Windowsサインイン前）、WSLから次を確認してください: ```bash systemctl --user is-enabled openclaw-gateway.service systemctl --user status openclaw-gateway.service --no-pager ``` -## 高度な設定: WSL serviceをLANへ公開する（portproxy） +## 高度な設定: WSLのサービスをLAN上に公開する（portproxy） -WSLには独自の仮想ネットワークがあります。別のマシンから -**WSL内で**動作するservice（SSH、ローカルTTS server、またはGateway）へ到達する必要がある場合、 -Windowsのportを現在のWSL IPへ転送する必要があります。WSL IPは再起動後に変わるため、 -転送ルールを更新する必要がある場合があります。 +WSLは独自の仮想ネットワークを持っています。別のマシンから**WSL内**で動作しているサービス（SSH、ローカルTTSサーバー、またはGateway）に到達する必要がある場合、Windowsのポートを現在のWSL IPへ転送しなければなりません。WSL IPは再起動後に変わるため、転送ルールを更新する必要がある場合があります。 -例（PowerShellを**Administratorとして**実行）: +例（**管理者として**PowerShellで実行）: ```powershell $Distro = "Ubuntu-24.04" @@ -165,7 +158,7 @@ netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPor connectaddress=$WslIp connectport=$TargetPort ``` -そのportをWindows Firewallで許可します（1回のみ）: +Windows Firewallでそのポートを許可します（1回だけ）: ```powershell New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound ` @@ -182,28 +175,27 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0. 注意: -- 別のマシンからのSSHは**Windows host IP**を対象にします（例: `ssh user@windows-host -p 2222`）。 -- リモートnodeは、到達可能なGateway URL（`127.0.0.1` ではない）を指す必要があります。 - 確認には `openclaw status --all` を使ってください。 -- LANアクセスには `listenaddress=0.0.0.0` を使ってください。`127.0.0.1` ならローカル専用です。 +- 別のマシンからのSSHは**WindowsホストのIP**を対象にします（例: `ssh user@windows-host -p 2222`）。 +- リモートNodeは、**到達可能な** Gateway URL（`127.0.0.1` ではない）を指す必要があります。確認には `openclaw status --all` を使ってください。 +- LANアクセスには `listenaddress=0.0.0.0` を使います。`127.0.0.1` ならローカル専用のままです。 - これを自動化したい場合は、ログイン時に更新手順を実行するScheduled Taskを登録してください。 -## WSL2インストール手順 +## WSL2のステップ別インストール ### 1) WSL2 + Ubuntuをインストールする -PowerShellをAdminで開きます: +PowerShell（管理者）を開きます: ```powershell wsl --install -# または、distroを明示的に選択: +# または、ディストリビューションを明示的に選択: wsl --list --online wsl --install -d Ubuntu-24.04 ``` -Windowsから求められたら再起動してください。 +Windowsに求められたら再起動してください。 -### 2) systemdを有効にする（Gateway installに必須） +### 2) systemdを有効にする（Gatewayのインストールに必須） WSLターミナルで: @@ -214,13 +206,13 @@ systemd=true EOF ``` -その後PowerShellから: +その後、PowerShellから: ```powershell wsl --shutdown ``` -Ubuntuを再度開き、次で確認します: +Ubuntuを再度開いて、次を確認します: ```bash systemctl --user status @@ -228,20 +220,28 @@ systemctl --user status ### 3) OpenClawをインストールする（WSL内） -WSL内でLinux向けのはじめにフローに従ってください: +WSL内で通常の初回セットアップを行う場合は、Linux向けの「はじめに」フローに従ってください: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install -pnpm ui:build # 初回実行時にUI依存関係を自動インストール pnpm build -openclaw onboard +pnpm ui:build +pnpm openclaw onboard --install-daemon +``` + +初回オンボーディングではなくソースから開発する場合は、[Setup](/ja-JP/start/setup) のソース開発ループを使ってください: + +```bash +pnpm install +# 初回実行時のみ（またはローカルのOpenClaw config/workspaceをリセットした後） +pnpm openclaw setup +pnpm gateway:watch ``` 完全なガイド: [はじめに](/ja-JP/start/getting-started) -## Windows companion app +## Windowsコンパニオンアプリ -まだWindows companion appはありません。実現したい場合は、 -コントリビューションを歓迎します。 +まだWindowsコンパニオンアプリはありません。実現に向けた貢献をしたい場合は、コントリビューションを歓迎します。 diff --git a/docs/ja-JP/start/setup.md b/docs/ja-JP/start/setup.md index 4e26aa761..a408dbb00 100644 --- a/docs/ja-JP/start/setup.md +++ b/docs/ja-JP/start/setup.md @@ -1,14 +1,14 @@ --- read_when: - - 新しいマシンをセットアップするとき - - 個人設定を壊さずに「最新かつ最高」の状態を使いたいとき -summary: OpenClaw の高度なセットアップと開発ワークフロー + - 新しいマシンのセットアップ + - 個人のセットアップを壊さずに「最新かつ最高」の状態を使いたい場合 +summary: OpenClawの高度なセットアップと開発ワークフロー title: セットアップ x-i18n: - generated_at: "2026-04-05T12:57:39Z" + generated_at: "2026-04-20T04:46:31Z" model: gpt-5.4 provider: openai - source_hash: be4e280dde7f3a224345ca557ef2fb35a9c9db8520454ff63794ac6f8d4e71e7 + source_hash: 773cdbef5f38b069303b5e13fca5fcdc28f082746869f17b8b92aab1610b95a8 source_path: start/setup.md workflow: 15 --- @@ -16,36 +16,36 @@ x-i18n: # セットアップ -初めてセットアップする場合は、[はじめに](/ja-JP/start/getting-started) から始めてください。 -オンボーディングの詳細は、[Onboarding (CLI)](/ja-JP/start/wizard) を参照してください。 +初めてセットアップする場合は、[はじめに](/ja-JP/start/getting-started)から始めてください。 +オンボーディングの詳細は、[オンボーディング (CLI)](/ja-JP/start/wizard)を参照してください。 ## 要点 -- **カスタマイズはリポジトリの外に置きます:** `~/.openclaw/workspace`（workspace）+ `~/.openclaw/openclaw.json`（config）。 +- **カスタマイズはリポジトリの外にあります:** `~/.openclaw/workspace`（workspace）+ `~/.openclaw/openclaw.json`（config）。 - **安定したワークフロー:** macOSアプリをインストールし、同梱のGatewayを実行させます。 -- **最先端ワークフロー:** `pnpm gateway:watch` で自分でGatewayを実行し、その後macOSアプリをローカルモードで接続させます。 +- **最先端のワークフロー:** `pnpm gateway:watch` で自分でGatewayを実行し、その後macOSアプリをLocalモードで接続させます。 -## 前提条件（ソースから実行する場合） +## 前提条件（ソースから） -- Node 24を推奨（Node 22 LTS、現在は `22.14+`、も引き続きサポート） -- `pnpm` を推奨（または意図的に [Bun workflow](/ja-JP/install/bun) を使う場合はBun） -- Docker（任意。コンテナ化されたセットアップ/e2e専用。詳細は [Docker](/ja-JP/install/docker) を参照） +- Node 24推奨（Node 22 LTS、現在は `22.14+`、引き続きサポートされています） +- `pnpm` 推奨（または、意図的に[Bun workflow](/ja-JP/install/bun)を使う場合はBun） +- Docker（任意。コンテナ化されたセットアップ/e2eの場合のみ — [Docker](/ja-JP/install/docker)を参照） ## カスタマイズ戦略（アップデートで困らないように） -「自分向けに100%カスタマイズ」 _かつ_ アップデートも簡単にしたい場合は、カスタマイズを次に保存してください。 +「自分向けに100%カスタマイズ」しつつ簡単にアップデートしたい場合は、カスタマイズ内容を次に保持してください。 - **Config:** `~/.openclaw/openclaw.json`（JSON/JSON5風） - **Workspace:** `~/.openclaw/workspace`（skills、prompts、memories。プライベートなgitリポジトリにしてください） -一度だけブートストラップします: +一度だけ初期化します。 ```bash openclaw setup ``` -このリポジトリ内からは、ローカルCLIエントリを使います: +このリポジトリ内からは、ローカルCLIエントリを使います。 ```bash openclaw setup @@ -55,7 +55,7 @@ openclaw setup ## このリポジトリからGatewayを実行する -`pnpm build` の後、パッケージ化されたCLIを直接実行できます: +`pnpm build` の後、パッケージ化されたCLIを直接実行できます。 ```bash node openclaw.mjs gateway --port 18789 --verbose @@ -65,30 +65,30 @@ node openclaw.mjs gateway --port 18789 --verbose 1. **OpenClaw.app**（メニューバー）をインストールして起動します。 2. オンボーディング/権限チェックリスト（TCCプロンプト）を完了します。 -3. Gateway が **Local** で実行中であることを確認します（アプリが管理します）。 -4. 接続先をリンクします（例: WhatsApp）: +3. Gatewayが**Local**で実行中であることを確認します（アプリが管理します）。 +4. サーフェスをリンクします（例: WhatsApp）。 ```bash openclaw channels login ``` -5. 動作確認: +5. 正常性を確認します。 ```bash openclaw health ``` -使用中のビルドでオンボーディングが利用できない場合: +お使いのビルドでオンボーディングが利用できない場合: -- `openclaw setup` を実行し、その後 `openclaw channels login` を実行してから、Gatewayを手動で起動してください（`openclaw gateway`）。 +- `openclaw setup` を実行し、次に `openclaw channels login` を実行して、その後Gatewayを手動で起動します（`openclaw gateway`）。 -## 最先端ワークフロー（ターミナルでGatewayを実行） +## 最先端のワークフロー（ターミナルでGatewayを実行） -目的: TypeScript Gateway を開発し、ホットリロードを得ながら、macOSアプリUIを接続したままにすることです。 +目的: TypeScript Gatewayで作業し、ホットリロードを使い、macOSアプリのUIは接続したままにします。 ### 0) （任意）macOSアプリもソースから実行する -macOSアプリも最先端版にしたい場合: +macOSアプリも最先端で使いたい場合: ```bash ./scripts/restart-mac.sh @@ -98,30 +98,36 @@ macOSアプリも最先端版にしたい場合: ```bash pnpm install +# 初回のみ（またはローカルのOpenClaw config/workspaceをリセットした後） +pnpm openclaw setup pnpm gateway:watch ``` `gateway:watch` はwatchモードでgatewayを実行し、関連するソース、 -config、および同梱pluginメタデータの変更時に再読み込みします。 +config、およびbundled-plugin metadataの変更時に再読み込みします。 +`pnpm openclaw setup` は、新しいチェックアウト向けの一度限りのローカルconfig/workspace初期化手順です。 +`pnpm gateway:watch` は `dist/control-ui` を再ビルドしないため、`ui/` を変更した後は `pnpm ui:build` を再実行するか、Control UIの開発中は `pnpm ui:dev` を使用してください。 -意図的にBun workflowを使っている場合、対応するコマンドは次のとおりです: +意図的にBun workflowを使っている場合、対応するコマンドは次のとおりです。 ```bash bun install +# 初回のみ（またはローカルのOpenClaw config/workspaceをリセットした後） +bun run openclaw setup bun run gateway:watch ``` -### 2) 実行中のGatewayをmacOSアプリに向ける +### 2) 実行中のGatewayにmacOSアプリを向ける **OpenClaw.app** で: -- 接続モード: **Local** - アプリは設定されたポート上の実行中gatewayに接続します。 +- Connection Mode: **Local** + アプリは、設定されたポートで実行中のgatewayに接続します。 -### 3) 確認 +### 3) 確認する -- アプリ内のGatewayステータスは **「Using existing gateway …」** と表示されるはずです -- またはCLI経由で: +- アプリ内のGatewayステータスが**「Using existing gateway …」**と表示されるはずです +- またはCLIから: ```bash openclaw health @@ -129,51 +135,51 @@ openclaw health ### よくある落とし穴 -- **ポートが違う:** Gateway WSのデフォルトは `ws://127.0.0.1:18789` です。アプリとCLIで同じポートを使ってください。 +- **ポート違い:** Gateway WSのデフォルトは `ws://127.0.0.1:18789` です。アプリとCLIで同じポートを使ってください。 - **状態が保存される場所:** - - チャネル/プロバイダーの状態: `~/.openclaw/credentials/` + - チャンネル/プロバイダーの状態: `~/.openclaw/credentials/` - モデル認証プロファイル: `~/.openclaw/agents//agent/auth-profiles.json` - セッション: `~/.openclaw/agents//sessions/` - ログ: `/tmp/openclaw/` -## 認証情報ストレージ対応表 +## 認証情報ストレージの対応表 -認証のデバッグや、何をバックアップすべきか判断するときに使ってください: +認証のデバッグや、何をバックアップすべきかを判断するときに使ってください。 - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Telegram bot token**: config/env または `channels.telegram.tokenFile`（通常ファイルのみ。symlinkは拒否） -- **Discord bot token**: config/env または SecretRef（env/file/exec プロバイダー） +- **Telegram bot token**: config/env または `channels.telegram.tokenFile`（通常のファイルのみ。symlinkは拒否されます） +- **Discord bot token**: config/env または SecretRef（env/file/exec providers） - **Slack tokens**: config/env（`channels.slack.*`） -- **ペアリングallowlist**: +- **ペアリング許可リスト**: - `~/.openclaw/credentials/-allowFrom.json`（デフォルトアカウント） - `~/.openclaw/credentials/--allowFrom.json`（デフォルト以外のアカウント） - **モデル認証プロファイル**: `~/.openclaw/agents//agent/auth-profiles.json` - **ファイルベースのシークレットペイロード（任意）**: `~/.openclaw/secrets.json` -- **レガシーOAuthインポート**: `~/.openclaw/credentials/oauth.json` +- **従来のOAuthインポート**: `~/.openclaw/credentials/oauth.json` 詳細: [Security](/ja-JP/gateway/security#credential-storage-map)。 -## 更新（セットアップを壊さずに） +## 更新する（セットアップを壊さずに） -- `~/.openclaw/workspace` と `~/.openclaw/` を「自分のもの」として扱ってください。個人的なprompts/configを `openclaw` リポジトリに置かないでください。 -- ソースの更新: `git pull` + 選択したパッケージマネージャーのインストール手順（デフォルトは `pnpm install`、Bun workflowでは `bun install`）+ 引き続き対応する `gateway:watch` コマンドを使います。 +- `~/.openclaw/workspace` と `~/.openclaw/` を「自分のもの」として扱ってください。個人用のprompts/configを `openclaw` リポジトリに入れないでください。 +- ソースの更新: `git pull` + 選択したパッケージマネージャーのインストール手順（デフォルトは `pnpm install`、Bun workflowでは `bun install`）+ 引き続き対応する `gateway:watch` コマンドを使用します。 ## Linux（systemdユーザーサービス） -Linuxインストールでは systemd **ユーザー**サービスを使用します。デフォルトでは、systemdはログアウト時やアイドル時にユーザー -サービスを停止するため、Gatewayも停止します。オンボーディングは -自動で lingering を有効にしようとします（sudoを求める場合があります）。まだ無効なら、次を実行してください: +Linuxインストールではsystemdの**ユーザー**サービスを使います。デフォルトでは、systemdはログアウト/アイドル時にユーザー +サービスを停止するため、Gatewayも停止します。オンボーディングでは +自動的にlingeringを有効にしようとします（sudoを求められる場合があります）。それでも無効な場合は、次を実行してください。 ```bash sudo loginctl enable-linger $USER ``` -常時稼働や複数ユーザーのサーバーでは、ユーザーサービスではなく -**system** サービスの利用を検討してください（lingeringは不要です）。systemdの注意点については [Gateway runbook](/ja-JP/gateway) を参照してください。 +常時稼働または複数ユーザーのサーバーでは、ユーザーサービスではなく +**システム**サービスを検討してください（lingeringは不要です）。systemdに関する注意は[Gateway runbook](/ja-JP/gateway)を参照してください。 ## 関連ドキュメント -- [Gateway runbook](/ja-JP/gateway)（フラグ、supervision、ポート） -- [Gateway configuration](/ja-JP/gateway/configuration)（configスキーマ + 例） -- [Discord](/ja-JP/channels/discord) と [Telegram](/ja-JP/channels/telegram)（reply tags + replyToMode設定） -- [OpenClaw assistant setup](/start/openclaw) +- [Gateway runbook](/ja-JP/gateway)（フラグ、監視、ポート） +- [Gateway configuration](/ja-JP/gateway/configuration)（config schema + examples） +- [Discord](/ja-JP/channels/discord) と [Telegram](/ja-JP/channels/telegram)（返信タグ + replyToMode設定） +- [OpenClaw assistant setup](/ja-JP/start/openclaw) - [macOS app](/ja-JP/platforms/macos)（gatewayライフサイクル） diff --git a/docs/ja-JP/tools/browser.md b/docs/ja-JP/tools/browser.md index 04b276fb0..2aa20e909 100644 --- a/docs/ja-JP/tools/browser.md +++ b/docs/ja-JP/tools/browser.md @@ -1,41 +1,41 @@ --- read_when: - エージェント制御のブラウザ自動化を追加する - - openclaw が自分の Chrome に干渉している理由をデバッグする - - macOSアプリでブラウザ設定 + ライフサイクルを実装する + - openclawが自分のChromeに干渉している理由をデバッグする + - macOSアプリでブラウザ設定とライフサイクルを実装する summary: 統合ブラウザ制御サービス + アクションコマンド title: ブラウザ（OpenClaw管理） x-i18n: - generated_at: "2026-04-14T13:04:29Z" + generated_at: "2026-04-20T04:47:04Z" model: gpt-5.4 provider: openai - source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 + source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b source_path: tools/browser.md workflow: 15 --- # ブラウザ（openclaw管理） -OpenClaw は、エージェントが制御する**専用の Chrome/Brave/Edge/Chromium プロファイル**を実行できます。 -これは個人用ブラウザから分離されており、Gateway 内の小さなローカル -制御サービス（loopback のみ）を通じて管理されます。 +OpenClawは、エージェントが制御する**専用のChrome/Brave/Edge/Chromiumプロファイル**を実行できます。 +これは個人用ブラウザから分離されており、Gateway内の小さなローカル +制御サービス（loopbackのみ）を通じて管理されます。 初心者向けの見方: - これは**エージェント専用の別ブラウザ**だと考えてください。 - `openclaw` プロファイルは、個人用ブラウザプロファイルには**触れません**。 -- エージェントは安全なレーンで**タブを開き、ページを読み取り、クリックし、入力**できます。 -- 組み込みの `user` プロファイルは、Chrome MCP 経由で実際のサインイン済み Chrome セッションに接続します。 +- エージェントは安全なレーンで**タブを開き、ページを読み、クリックし、入力**できます。 +- 組み込みの `user` プロファイルは、Chrome MCP経由で実際にサインイン済みのChromeセッションに接続します。 -## 利用できるもの +## 得られるもの - **openclaw** という名前の別ブラウザプロファイル（デフォルトではオレンジのアクセント）。 -- 決定的なタブ制御（一覧表示/開く/フォーカス/閉じる）。 +- 決定的なタブ制御（一覧/開く/フォーカス/閉じる）。 - エージェントアクション（クリック/入力/ドラッグ/選択）、スナップショット、スクリーンショット、PDF。 -- オプションのマルチプロファイル対応（`openclaw`、`work`、`remote`、...）。 +- 任意のマルチプロファイル対応（`openclaw`、`work`、`remote`、...）。 -このブラウザは日常使いのメインブラウザでは**ありません**。これは -エージェントの自動化と検証のための、安全で分離された画面です。 +このブラウザは日常使いのブラウザ**ではありません**。これは +エージェント自動化と検証のための、安全で分離されたサーフェスです。 ## クイックスタート @@ -46,16 +46,17 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -「Browser disabled」と表示される場合は、config で有効にし（下記参照）、Gateway を +「Browser disabled」と表示された場合は、configで有効化して（下記参照）、Gatewayを 再起動してください。 -`openclaw browser` 自体が見つからない場合、またはエージェントがブラウザツール -を利用できないと言う場合は、[ブラウザコマンドまたはツールが見つからない](/ja-JP/tools/browser#missing-browser-command-or-tool) に進んでください。 +`openclaw browser` 自体が存在しない場合、またはエージェントがブラウザツール +を利用できないと言う場合は、[Missing browser command or tool](/ja-JP/tools/browser#missing-browser-command-or-tool)に進んでください。 -## Plugin 制御 +## Plugin制御 -デフォルトの `browser` ツールは、現在はデフォルトで有効になっているバンドル済み Plugin です。 -つまり、OpenClaw の残りの Plugin システムを削除せずに、これを無効化または置き換えできます: +デフォルトの `browser` ツールは現在、デフォルトで有効な状態で同梱されるbundled pluginです。 +つまり、OpenClawの残りのpluginシステムを削除しなくても、 +これを無効化または置き換えできます。 ```json5 { @@ -69,32 +70,31 @@ openclaw browser --browser-profile openclaw snapshot } ``` -同じ `browser` ツール名を提供する別の Plugin をインストールする前に、バンドル済み Plugin を無効化してください。デフォルトのブラウザ体験には次の両方が必要です: +同じ `browser` ツール名を提供する別のpluginをインストールする前に、 +同梱pluginを無効にしてください。デフォルトのブラウザ体験には次の両方が必要です。 -- `plugins.entries.browser.enabled` が無効化されていないこと +- `plugins.entries.browser.enabled` が無効になっていないこと - `browser.enabled=true` -Plugin だけをオフにすると、バンドル済みブラウザ CLI（`openclaw browser`）、 -Gateway メソッド（`browser.request`）、エージェントツール、デフォルトのブラウザ制御 -サービスはすべてまとめて消えます。置き換え用 Plugin が再利用できるように、 -`browser.*` config はそのまま保持されます。 +pluginだけをオフにすると、同梱ブラウザCLI（`openclaw browser`）、 +gatewayメソッド（`browser.request`）、エージェントツール、およびデフォルトのブラウザ制御 +サービスはすべてまとめて消えます。`browser.*` configは、置き換えpluginが再利用できるようにそのまま残ります。 -バンドル済みブラウザ Plugin は、現在ブラウザランタイム実装も所有しています。 -core には共有の Plugin SDK ヘルパーと、古い内部 import パス向けの互換性 -re-export だけが残ります。実際には、ブラウザ Plugin パッケージを削除または -置き換えると、core が所有する 2 つ目のランタイムが残るのではなく、ブラウザ機能 -一式が削除されます。 +同梱ブラウザpluginは、現在ブラウザruntime実装も所有しています。 +coreには、共有のPlugin SDKヘルパーと、古い内部importパス向けの互換 +re-exportだけが残ります。実際には、ブラウザplugin packageを削除または置き換えると、 +2つ目のcore所有runtimeが残るのではなく、ブラウザ機能セット自体がなくなります。 -ブラウザ config の変更では、バンドル済み Plugin が新しい設定でブラウザサービスを -再登録できるように、引き続き Gateway の再起動が必要です。 +ブラウザconfigの変更では、同梱pluginが新しい設定でブラウザサービスを再登録できるようにするため、 +引き続きGatewayの再起動が必要です。 ## ブラウザコマンドまたはツールが見つからない -アップグレード後に `openclaw browser` が突然 unknown command になった場合、 -またはエージェントがブラウザツールが見つからないと報告する場合、最も一般的な -原因は `browser` を含まない制限的な `plugins.allow` リストです。 +アップグレード後に `openclaw browser` が突然未知のコマンドになった場合、 +またはエージェントがブラウザツールが見つからないと報告する場合、最も一般的な原因は、 +`browser` を含まない制限的な `plugins.allow` リストです。 -壊れた config の例: +壊れたconfigの例: ```json5 { @@ -104,7 +104,7 @@ re-export だけが残ります。実際には、ブラウザ Plugin パッケ } ``` -Plugin allowlist に `browser` を追加して修正してください: +plugin許可リストに `browser` を追加して修正してください。 ```json5 { @@ -116,29 +116,29 @@ Plugin allowlist に `browser` を追加して修正してください: 重要な注意点: -- `browser.enabled=true` だけでは、`plugins.allow` が設定されている場合は不十分です。 -- `plugins.entries.browser.enabled=true` だけでも、`plugins.allow` が設定されている場合は不十分です。 -- `tools.alsoAllow: ["browser"]` はバンドル済みブラウザ Plugin を読み込み**ません**。これは、Plugin がすでに読み込まれた後にツールポリシーを調整するだけです。 -- 制限的な Plugin allowlist が不要であれば、`plugins.allow` を削除することでもデフォルトのバンドル済みブラウザ動作が復元されます。 +- `plugins.allow` が設定されている場合、`browser.enabled=true` だけでは不十分です。 +- `plugins.allow` が設定されている場合、`plugins.entries.browser.enabled=true` だけでも不十分です。 +- `tools.alsoAllow: ["browser"]` は同梱ブラウザpluginをロード**しません**。これは、pluginがすでにロードされた後にツールポリシーを調整するだけです。 +- 制限的なplugin許可リストが不要な場合は、`plugins.allow` を削除してもデフォルトの同梱ブラウザ動作に戻ります。 典型的な症状: -- `openclaw browser` が unknown command になる。 -- `browser.request` が見つからない。 +- `openclaw browser` が未知のコマンドになる。 +- `browser.request` が存在しない。 - エージェントがブラウザツールを利用不可または未検出として報告する。 ## プロファイル: `openclaw` と `user` - `openclaw`: 管理された分離ブラウザ（拡張機能不要）。 -- `user`: 実際の**サインイン済み Chrome** セッションに接続する組み込み Chrome MCP アタッチプロファイル。 +- `user`: あなたの**実際にサインイン済みのChrome**セッション用の組み込みChrome MCP接続プロファイル。 -エージェントのブラウザツール呼び出しでは: +エージェントのブラウザツール呼び出しについて: - デフォルト: 分離された `openclaw` ブラウザを使用します。 -- 既存のログイン済みセッションが重要で、ユーザーが PC の前にいてアタッチプロンプトをクリック/承認できる場合は `profile="user"` を優先します。 -- `profile` は、特定のブラウザモードを使いたいときの明示的なオーバーライドです。 +- 既存のログイン済みセッションが重要で、ユーザーがコンピューターの前にいて接続プロンプトをクリック/承認できる場合は、`profile="user"` を優先してください。 +- `profile` は、特定のブラウザモードを使いたいときの明示的な上書きです。 -デフォルトで managed モードを使いたい場合は `browser.defaultProfile: "openclaw"` を設定してください。 +デフォルトで管理モードを使いたい場合は、`browser.defaultProfile: "openclaw"` を設定してください。 ## 設定 @@ -185,34 +185,33 @@ Plugin allowlist に `browser` を追加して修正してください: 注意: -- ブラウザ制御サービスは `gateway.port` から導出されたポートで loopback にバインドされます - （デフォルト: `18791`、つまり gateway + 2）。 -- Gateway ポート（`gateway.port` または `OPENCLAW_GATEWAY_PORT`）をオーバーライドすると、 - 同じ「ファミリー」を保つために導出ブラウザポートもずれます。 -- `cdpUrl` が未設定の場合は、managed なローカル CDP ポートがデフォルトになります。 -- `remoteCdpTimeoutMs` は remote（非 loopback）CDP 到達性チェックに適用されます。 -- `remoteCdpHandshakeTimeoutMs` は remote CDP WebSocket 到達性チェックに適用されます。 -- ブラウザのナビゲーション/タブを開く処理は、ナビゲーション前に SSRF ガードされ、ナビゲーション後の最終 `http(s)` URL に対してベストエフォートで再チェックされます。 -- strict SSRF モードでは、remote CDP エンドポイントの検出/プローブ（`cdpUrl`、`/json/version` 参照を含む）もチェックされます。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` はデフォルトで無効です。意図的に private-network ブラウザアクセスを信頼する場合にのみ `true` に設定してください。 -- `browser.ssrfPolicy.allowPrivateNetwork` は互換性のための legacy alias として引き続きサポートされています。 -- `attachOnly: true` は「ローカルブラウザを決して起動せず、すでに実行中の場合のみ接続する」ことを意味します。 -- `color` とプロファイルごとの `color` はブラウザ UI を色付けし、どのプロファイルがアクティブかを見分けられるようにします。 -- デフォルトプロファイルは `openclaw`（OpenClaw 管理のスタンドアロンブラウザ）です。サインイン済みユーザーブラウザを使うには `defaultProfile: "user"` を指定してください。 -- 自動検出順序: システムのデフォルトブラウザが Chromium ベースならそれを使用し、そうでなければ Chrome → Brave → Edge → Chromium → Chrome Canary の順です。 -- ローカル `openclaw` プロファイルは `cdpPort`/`cdpUrl` を自動割り当てします。これらは remote CDP に対してのみ設定してください。 -- `driver: "existing-session"` は raw CDP の代わりに Chrome DevTools MCP を使用します。この - driver には `cdpUrl` を設定しないでください。 -- `browser.profiles..userDataDir` は、existing-session プロファイルを - Brave や Edge などの非デフォルト Chromium ユーザープロファイルに接続させたい場合に設定してください。 +- ブラウザ制御サービスは、`gateway.port` から派生したポートでloopbackにバインドされます + （デフォルト: `18791`、gateway + 2）。 +- Gatewayポート（`gateway.port` または `OPENCLAW_GATEWAY_PORT`）を上書きすると、 + 派生ブラウザポートも同じ「ファミリー」に収まるようにずれます。 +- `cdpUrl` は未設定時、管理されたローカルCDPポートがデフォルトになります。 +- `remoteCdpTimeoutMs` はremote（non-loopback）CDP到達性チェックに適用されます。 +- `remoteCdpHandshakeTimeoutMs` はremote CDP WebSocket到達性チェックに適用されます。 +- ブラウザのナビゲーション/タブを開く操作には、ナビゲーション前にSSRFガードがかかり、ナビゲーション後の最終 `http(s)` URL に対してもベストエフォートで再確認されます。 +- strict SSRFモードでは、remote CDPエンドポイントの検出/プローブ（`cdpUrl`、`/json/version` 参照を含む）もチェックされます。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` はデフォルトで無効です。private-networkのブラウザアクセスを意図的に信頼する場合にのみ `true` に設定してください。 +- `browser.ssrfPolicy.allowPrivateNetwork` は、互換性のために引き続き従来のaliasとしてサポートされます。 +- `attachOnly: true` は「ローカルブラウザを決して起動せず、すでに実行中の場合のみ接続する」という意味です。 +- `color` とプロファイルごとの `color` はブラウザUIに色を付け、どのプロファイルがアクティブか分かるようにします。 +- デフォルトプロファイルは `openclaw`（OpenClaw管理のスタンドアロンブラウザ）です。サインイン済みユーザーブラウザを使うには `defaultProfile: "user"` を使用してください。 +- 自動検出順: システムデフォルトブラウザがChromium系ならそれを使用し、そうでなければ Chrome → Brave → Edge → Chromium → Chrome Canary の順です。 +- ローカル `openclaw` プロファイルでは `cdpPort`/`cdpUrl` は自動割り当てされるため、それらはremote CDP用にのみ設定してください。 +- `driver: "existing-session"` は生のCDPではなくChrome DevTools MCPを使います。この + driverには `cdpUrl` を設定しないでください。 +- 既存セッションプロファイルをBraveやEdgeのようなデフォルト以外のChromiumユーザープロファイルに接続する場合は、`browser.profiles..userDataDir` を設定してください。 -## Brave（または別の Chromium ベースブラウザ）を使う +## Brave（または別のChromium系ブラウザ）を使う -**システムのデフォルト**ブラウザが Chromium ベース（Chrome/Brave/Edge など）の場合、 -OpenClaw は自動的にそれを使用します。自動検出をオーバーライドするには -`browser.executablePath` を設定してください: +**システムデフォルト**ブラウザがChromium系（Chrome/Brave/Edgeなど）の場合、 +OpenClawは自動的にそれを使用します。自動検出を上書きするには +`browser.executablePath` を設定してください。 -CLI の例: +CLI例: ```bash openclaw config set browser.executablePath "/usr/bin/google-chrome" @@ -243,51 +242,50 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## ローカル制御とリモート制御 -- **ローカル制御（デフォルト）:** Gateway が loopback 制御サービスを起動し、ローカルブラウザを起動できます。 -- **リモート制御（node host）:** ブラウザを持つマシン上で node host を実行すると、Gateway がブラウザアクションをそこへプロキシします。 -- **remote CDP:** `browser.profiles..cdpUrl`（または `browser.cdpUrl`）を設定すると、 - remote の Chromium ベースブラウザに接続できます。この場合、OpenClaw はローカルブラウザを起動しません。 +- **ローカル制御（デフォルト）:** Gatewayがloopback制御サービスを起動し、ローカルブラウザを起動できます。 +- **リモート制御（node host）:** ブラウザがあるマシンでnode hostを実行すると、Gatewayがブラウザアクションをそこにプロキシします。 +- **Remote CDP:** `browser.profiles..cdpUrl`（または `browser.cdpUrl`）を設定して、 + remote Chromium系ブラウザに接続します。この場合、OpenClawはローカルブラウザを起動しません。 -停止時の動作はプロファイルモードによって異なります: +停止動作はプロファイルモードによって異なります: -- ローカル managed プロファイル: `openclaw browser stop` は - OpenClaw が起動したブラウザプロセスを停止します -- attach-only および remote CDP プロファイル: `openclaw browser stop` はアクティブな - 制御セッションを閉じ、Playwright/CDP のエミュレーションオーバーライド（ビューポート、 - カラースキーム、ロケール、タイムゾーン、オフラインモード、その他同様の状態）を解除します。 - OpenClaw がブラウザプロセスを起動していない場合でも同様です +- ローカル管理プロファイル: `openclaw browser stop` は、OpenClawが起動したブラウザプロセスを停止します +- attach-onlyおよびremote CDPプロファイル: `openclaw browser stop` は、アクティブな + 制御セッションを閉じ、Playwright/CDPのエミュレーション上書き（ビューポート、 + カラースキーム、ロケール、タイムゾーン、オフラインモード、および類似の状態）を解放します。 + OpenClawがブラウザプロセスを起動していない場合でも同様です -remote CDP URL には auth を含めることができます: +Remote CDP URLには認証を含められます: - クエリトークン（例: `https://provider.example?token=`） -- HTTP Basic auth（例: `https://user:pass@provider.example`） +- HTTP Basic認証（例: `https://user:pass@provider.example`） -OpenClaw は `/json/*` エンドポイントを呼び出すときも、CDP WebSocket に接続するときも -その auth を保持します。トークンは config ファイルにコミットするのではなく、 -環境変数や secrets manager を使うことを推奨します。 +OpenClawは `/json/*` エンドポイント呼び出し時と、CDP WebSocket接続時の両方で +認証情報を保持します。configファイルにコミットするのではなく、 +トークンには環境変数またはシークレットマネージャーを使うことを推奨します。 -## Node ブラウザプロキシ（ゼロ設定デフォルト） +## Node browser proxy（デフォルトのゼロ設定） -ブラウザがあるマシンで **node host** を実行している場合、OpenClaw は -追加のブラウザ設定なしでブラウザツール呼び出しをその node に自動ルーティングできます。 -これは remote gateway のデフォルト経路です。 +ブラウザのあるマシンで**node host**を実行している場合、OpenClawは +追加のブラウザ設定なしで、ブラウザツール呼び出しをそのnodeに自動ルーティングできます。 +これはremote gatewayのデフォルト経路です。 注意: -- node host はそのローカルブラウザ制御サーバーを**プロキシコマンド**として公開します。 -- プロファイルは node 自身の `browser.profiles` config から取得されます（ローカルと同じ）。 -- `nodeHost.browserProxy.allowProfiles` はオプションです。空のままにすると legacy/default の動作になり、プロファイル作成/削除ルートを含め、設定済みのすべてのプロファイルがプロキシ経由で到達可能なままになります。 -- `nodeHost.browserProxy.allowProfiles` を設定すると、OpenClaw はそれを最小権限境界として扱います。allowlist に載ったプロファイルだけを対象にでき、永続プロファイルの作成/削除ルートはプロキシ画面でブロックされます。 -- 不要であれば無効化してください: - - node 側: `nodeHost.browserProxy.enabled=false` - - gateway 側: `gateway.nodes.browser.mode="off"` +- node hostは、そのローカルブラウザ制御サーバーを**proxy command**経由で公開します。 +- プロファイルはnode自身の `browser.profiles` configから取得されます（ローカルと同じ）。 +- `nodeHost.browserProxy.allowProfiles` は任意です。従来どおり/デフォルト動作にするには空のままにしてください: 設定済みのすべてのプロファイルが、プロファイル作成/削除ルートを含め、proxy経由で引き続き到達可能です。 +- `nodeHost.browserProxy.allowProfiles` を設定すると、OpenClawはそれを最小権限境界として扱います: 許可リストにあるプロファイルのみを対象にでき、永続プロファイルの作成/削除ルートはproxyサーフェスでブロックされます。 +- 不要な場合は無効化してください: + - node側: `nodeHost.browserProxy.enabled=false` + - gateway側: `gateway.nodes.browser.mode="off"` -## Browserless（ホスト型 remote CDP） +## Browserless（ホスト型remote CDP） -[Browserless](https://browserless.io) は、HTTPS と WebSocket 経由で -CDP 接続 URL を公開するホスト型 Chromium サービスです。OpenClaw はどちらの形式も使用できますが、 -remote ブラウザプロファイルでは、最も簡単な方法は Browserless の接続ドキュメントにある -直接 WebSocket URL を使うことです。 +[Browserless](https://browserless.io) は、HTTPSおよびWebSocket経由で +CDP接続URLを公開するホスト型Chromiumサービスです。OpenClawはどちらの形式も使用できますが、 +remote browser profileでは、最も簡単な選択肢はBrowserlessの接続ドキュメントにある +直接のWebSocket URLです。 例: @@ -310,29 +308,44 @@ remote ブラウザプロファイルでは、最も簡単な方法は Browserle 注意: -- `` は実際の Browserless トークンに置き換えてください。 -- Browserless アカウントに対応するリージョンエンドポイントを選んでください（詳細は各種ドキュメントを参照）。 -- Browserless から HTTPS ベース URL が提供される場合は、それを - 直接 CDP 接続用の `wss://` に変換するか、HTTPS URL のままにして OpenClaw に +- `` は実際のBrowserlessトークンに置き換えてください。 +- Browserlessアカウントに対応するリージョンエンドポイントを選んでください（詳細はドキュメントを参照）。 +- BrowserlessからHTTPSベースURLが提供される場合は、それを + 直接CDP接続用の `wss://` に変換するか、HTTPS URLのままにしてOpenClawに `/json/version` を検出させることができます。 -## 直接 WebSocket CDP プロバイダー +## 直接WebSocket CDPプロバイダー -一部のホスト型ブラウザサービスは、標準の HTTP ベース CDP 検出（`/json/version`）ではなく -**直接 WebSocket** エンドポイントを公開しています。OpenClaw は両方をサポートします: +一部のホスト型ブラウザサービスは、標準のHTTPベースCDP検出（`/json/version`）ではなく +**直接WebSocket**エンドポイントを公開します。OpenClawは3つの +CDP URL形式を受け入れ、適切な接続戦略を自動的に選びます: -- **HTTP(S) エンドポイント** — OpenClaw は `/json/version` を呼び出して - WebSocket デバッガー URL を検出し、その後接続します。 -- **WebSocket エンドポイント**（`ws://` / `wss://`）— OpenClaw は直接接続し、 - `/json/version` をスキップします。これは - [Browserless](https://browserless.io)、 - [Browserbase](https://www.browserbase.com)、または WebSocket URL を渡す - 任意のプロバイダーのようなサービスに使用してください。 +- **HTTP(S)検出** — `http://host[:port]` または `https://host[:port]`。 + OpenClawは `/json/version` を呼び出してWebSocketデバッガーURLを検出し、その後 + 接続します。WebSocketフォールバックはありません。 +- **直接WebSocketエンドポイント** — `ws://host[:port]/devtools//` または + `/devtools/browser|page|worker|shared_worker|service_worker/` パス付きの `wss://...`。 + OpenClawはWebSocketハンドシェイクで直接接続し、 + `/json/version` は完全にスキップします。 +- **パスなしのWebSocketルート** — `/devtools/...` パスなしの `ws://host[:port]` または `wss://host[:port]` + （例: [Browserless](https://browserless.io)、 + [Browserbase](https://www.browserbase.com)）。OpenClawはまずHTTP + `/json/version` 検出を試み（スキームは `http`/`https` に正規化されます）、 + 検出で `webSocketDebuggerUrl` が返された場合はそれを使用し、そうでない場合はOpenClawが + パスなしルートへの直接WebSocketハンドシェイクにフォールバックします。これにより、 + Chromeスタイルのremote debugポートとWebSocket専用プロバイダーの + 両方をカバーします。 + +`/devtools/...` パスなしのプレーンな `ws://host:port` / `wss://host:port` を +ローカルChromeインスタンスに向ける使い方は、検出優先の +フォールバックによってサポートされます。Chromeは、`/json/version` が返すブラウザ単位 +またはターゲット単位の特定パスでのみWebSocketアップグレードを受け付けるため、 +パスなしルートへのハンドシェイク単体では失敗します。 ### Browserbase -[Browserbase](https://www.browserbase.com) は、組み込みの CAPTCHA 解決、ステルスモード、 -住宅用プロキシを備えた headless ブラウザ実行用のクラウドプラットフォームです。 +[Browserbase](https://www.browserbase.com) は、組み込みのCAPTCHA解決、stealth mode、およびresidential +proxyを備えたheadless browser実行用クラウドプラットフォームです。 ```json5 { @@ -353,62 +366,63 @@ remote ブラウザプロファイルでは、最も簡単な方法は Browserle 注意: -- [登録](https://www.browserbase.com/sign-up) して、[Overview ダッシュボード](https://www.browserbase.com/overview)から **API Key** - をコピーしてください。 -- `` は実際の Browserbase API キーに置き換えてください。 -- Browserbase は WebSocket 接続時にブラウザセッションを自動作成するため、 - 手動のセッション作成ステップは不要です。 -- 無料プランでは、同時セッション 1 つ、月あたり 1 ブラウザ時間まで利用できます。 - 有料プランの上限は [pricing](https://www.browserbase.com/pricing) を参照してください。 -- 完全な API リファレンス、SDK ガイド、統合例については - [Browserbase docs](https://docs.browserbase.com) を参照してください。 +- [Sign up](https://www.browserbase.com/sign-up) して、[Overview dashboard](https://www.browserbase.com/overview)から + **API Key** をコピーしてください。 +- `` は実際のBrowserbase API keyに置き換えてください。 +- BrowserbaseはWebSocket接続時にブラウザセッションを自動作成するため、 + 手動のセッション作成手順は不要です。 +- 無料プランでは、同時セッション1つ、月あたりブラウザ1時間まで利用できます。 + 有料プランの制限については[pricing](https://www.browserbase.com/pricing)を参照してください。 +- 完全なAPI + リファレンス、SDKガイド、統合例については、[Browserbase docs](https://docs.browserbase.com)を参照してください。 ## セキュリティ -重要な考え方: +主な考え方: -- ブラウザ制御は loopback 専用です。アクセスは Gateway の auth または node ペアリングを通ります。 -- スタンドアロンの loopback ブラウザ HTTP API は**shared-secret auth のみ**を使用します: +- ブラウザ制御はloopback専用です。アクセスはGatewayの認証またはnodeペアリングを通ります。 +- スタンドアロンのloopback browser HTTP APIは、**shared-secret authのみ**を使用します: gateway token bearer auth、`x-openclaw-password`、または - 設定済み gateway password を使う HTTP Basic auth です。 -- Tailscale Serve の identity header と `gateway.auth.mode: "trusted-proxy"` は - このスタンドアロン loopback ブラウザ API を**認証しません**。 -- ブラウザ制御が有効で、shared-secret auth が未設定の場合、OpenClaw は - 起動時に `gateway.auth.token` を自動生成して config に永続化します。 -- `gateway.auth.mode` がすでに - `password`、`none`、または `trusted-proxy` の場合、OpenClaw はその token を自動生成**しません**。 -- Gateway と node host は private network（Tailscale）上に維持し、public に公開しないでください。 -- remote CDP URL/token は secrets として扱い、環境変数や secrets manager を優先してください。 + 設定されたgateway passwordを使うHTTP Basic authです。 +- Tailscale Serveのidentity headerおよび `gateway.auth.mode: "trusted-proxy"` は、 + このスタンドアロンloopback browser APIの認証には**使用されません**。 +- ブラウザ制御が有効で、shared-secret authが設定されていない場合、OpenClawは + 起動時に `gateway.auth.token` を自動生成し、configに永続化します。 +- `gateway.auth.mode` が + すでに `password`、`none`、または `trusted-proxy` の場合、OpenClawはそのtokenを自動生成**しません**。 +- Gatewayおよびすべてのnode hostはプライベートネットワーク（Tailscale）上に置き、公開しないでください。 +- Remote CDP URL/tokenはシークレットとして扱い、環境変数またはsecrets managerを優先してください。 -remote CDP のヒント: +Remote CDPのヒント: -- 可能であれば暗号化されたエンドポイント（HTTPS または WSS）と短命トークンを優先してください。 -- 長期間有効なトークンを config ファイルに直接埋め込むのは避けてください。 +- 可能な場合は、暗号化されたエンドポイント（HTTPSまたはWSS）と短寿命トークンを優先してください。 +- 長寿命トークンをconfigファイルに直接埋め込まないでください。 ## プロファイル（マルチブラウザ） -OpenClaw は複数の名前付きプロファイル（ルーティング設定）をサポートしています。プロファイルには次の種類があります: +OpenClawは複数の名前付きプロファイル（ルーティングconfig）をサポートします。プロファイルには次の種類があります。 -- **openclaw-managed**: 専用の user data directory + CDP port を持つ、専用の Chromium ベースブラウザインスタンス -- **remote**: 明示的な CDP URL（別の場所で実行中の Chromium ベースブラウザ） -- **existing session**: Chrome DevTools MCP 自動接続経由の、既存の Chrome プロファイル +- **openclaw-managed**: 専用のChromium系ブラウザインスタンス。独自のuser data directory + CDPポートを持ちます +- **remote**: 明示的なCDP URL（別の場所で動作しているChromium系ブラウザ） +- **existing session**: Chrome DevTools MCP自動接続を介した既存のChromeプロファイル デフォルト: -- `openclaw` プロファイルは、存在しない場合は自動作成されます。 -- `user` プロファイルは、Chrome MCP existing-session 接続用に組み込まれています。 -- existing-session プロファイルは `user` 以外ではオプトインです。`--driver existing-session` で作成してください。 -- ローカル CDP ポートはデフォルトで **18800–18899** から割り当てられます。 -- プロファイルを削除すると、そのローカル data directory は Trash に移動されます。 +- `openclaw` プロファイルは、存在しない場合に自動作成されます。 +- `user` プロファイルは、Chrome MCP existing-session接続用に組み込まれています。 +- existing-sessionプロファイルは `user` 以外ではオプトインです。`--driver existing-session` で作成してください。 +- ローカルCDPポートはデフォルトで **18800–18899** から割り当てられます。 +- プロファイルを削除すると、そのローカルdata directoryはゴミ箱に移動されます。 -すべての制御エンドポイントは `?profile=` を受け付けます。CLI は `--browser-profile` を使用します。 +すべての制御エンドポイントは `?profile=` を受け付けます。CLIでは `--browser-profile` を使用します。 -## Chrome DevTools MCP 経由の existing-session +## Chrome DevTools MCP経由のexisting-session -OpenClaw は、公式の Chrome DevTools MCP サーバーを通じて、実行中の Chromium ベースブラウザプロファイルにも接続できます。 -これにより、そのブラウザプロファイルですでに開かれているタブとログイン状態を再利用できます。 +OpenClawは、公式のChrome DevTools MCPサーバーを通じて、 +実行中のChromium系ブラウザプロファイルにも接続できます。これにより、そのブラウザプロファイルですでに +開かれているタブとログイン状態を再利用できます。 -公式の背景情報とセットアップ参照: +公式の背景情報とセットアップ参照先: - [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) @@ -417,15 +431,15 @@ OpenClaw は、公式の Chrome DevTools MCP サーバーを通じて、実行 - `user` -オプション: 別の名前、色、または browser data directory を使いたい場合は、 -独自の custom existing-session プロファイルを作成できます。 +任意: 別の名前、色、またはbrowser data directoryを使いたい場合は、 +独自のexisting-sessionプロファイルを作成できます。 デフォルト動作: -- 組み込みの `user` プロファイルは Chrome MCP auto-connect を使用し、 - ローカルのデフォルト Google Chrome プロファイルを対象にします。 +- 組み込みの `user` プロファイルはChrome MCP自動接続を使い、 + デフォルトのローカルGoogle Chromeプロファイルを対象にします。 -Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファイルには `userDataDir` を使ってください: +Brave、Edge、Chromium、またはデフォルト以外のChromeプロファイルには `userDataDir` を使用します。 ```json5 { @@ -442,19 +456,19 @@ Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファ } ``` -次に、対応するブラウザで以下を行います: +その後、対応するブラウザで次の操作を行います。 -1. そのブラウザのリモートデバッグ用 inspect page を開きます。 -2. リモートデバッグを有効にします。 -3. ブラウザを起動したままにし、OpenClaw が接続するときに接続確認プロンプトを承認します。 +1. そのブラウザのremote debugging用inspectページを開きます。 +2. remote debuggingを有効にします。 +3. ブラウザを実行したままにし、OpenClaw接続時に表示される接続確認プロンプトを承認します。 -一般的な inspect page: +一般的なinspectページ: - Chrome: `chrome://inspect/#remote-debugging` - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -ライブ接続のスモークテスト: +ライブ接続スモークテスト: ```bash openclaw browser --browser-profile user start @@ -463,71 +477,76 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -成功時の状態: +成功時の見え方: -- `status` に `driver: existing-session` が表示される -- `status` に `transport: chrome-mcp` が表示される -- `status` に `running: true` が表示される +- `status` に `driver: existing-session` と表示される +- `status` に `transport: chrome-mcp` と表示される +- `status` に `running: true` と表示される - `tabs` に、すでに開いているブラウザタブが一覧表示される -- `snapshot` が選択中のライブタブから refs を返す +- `snapshot` が、選択されたライブタブからrefを返す -接続できない場合に確認すること: +接続できない場合の確認項目: -- 対象の Chromium ベースブラウザがバージョン `144+` である -- そのブラウザの inspect page でリモートデバッグが有効になっている -- ブラウザに接続確認プロンプトが表示され、それを承認した -- `openclaw doctor` は古い拡張機能ベースのブラウザ config を移行し、 - デフォルト auto-connect プロファイル用に Chrome がローカルにインストールされているかを確認しますが、 - ブラウザ側のリモートデバッグを代わりに有効化することはできません +- 対象のChromium系ブラウザがバージョン `144+` である +- そのブラウザのinspectページでremote debuggingが有効になっている +- ブラウザが接続確認プロンプトを表示し、それを承認した +- `openclaw doctor` は古い拡張機能ベースのブラウザconfigを移行し、 + デフォルトの自動接続プロファイル向けにChromeがローカルにインストールされているかを確認しますが、 + ブラウザ側のremote debuggingを代わりに有効化することはできません -エージェントでの使用: +エージェント利用: -- ユーザーのログイン済みブラウザ状態が必要な場合は `profile="user"` を使用します。 -- custom existing-session プロファイルを使う場合は、その明示的なプロファイル名を渡します。 -- このモードは、ユーザーが PC の前にいて接続確認プロンプトを承認できる場合にのみ選択してください。 -- Gateway または node host は `npx chrome-devtools-mcp@latest --autoConnect` を起動できます +- ユーザーのログイン済みブラウザ状態が必要な場合は `profile="user"` を使ってください。 +- カスタムexisting-sessionプロファイルを使う場合は、その明示的なプロファイル名を渡してください。 +- このモードは、ユーザーがコンピューターの前にいて接続確認 + プロンプトを承認できるときにのみ選択してください。 +- Gatewayまたはnode hostは `npx chrome-devtools-mcp@latest --autoConnect` を起動できます 注意: -- この経路は分離された `openclaw` プロファイルより高リスクです。サインイン済みブラウザセッション内で操作できるためです。 -- この driver では OpenClaw はブラウザを起動しません。既存セッションにのみ接続します。 -- OpenClaw はここで公式の Chrome DevTools MCP `--autoConnect` フローを使用します。 - `userDataDir` が設定されている場合、OpenClaw はそれを渡して、その明示的な - Chromium user data directory を対象にします。 -- existing-session のスクリーンショットは、ページキャプチャとスナップショットからの `--ref` 要素 +- この経路は、サインイン済みブラウザセッション内で + 動作できるため、分離された `openclaw` プロファイルより高リスクです。 +- OpenClawはこのdriver用にブラウザを起動しません。既存の + セッションにのみ接続します。 +- OpenClawはここで公式のChrome DevTools MCP `--autoConnect` フローを使用します。 + `userDataDir` が設定されている場合、OpenClawはそれを渡して、その明示的な + Chromium user data directoryを対象にします。 +- Existing-sessionのスクリーンショットは、ページキャプチャとスナップショットからの `--ref` 要素 キャプチャをサポートしますが、CSS `--element` セレクターはサポートしません。 -- existing-session のページスクリーンショットは、Chrome MCP 経由で Playwright なしでも動作します。 - ref ベースの要素スクリーンショット（`--ref`）も同様に動作しますが、`--full-page` +- Existing-sessionのページスクリーンショットは、Chrome MCP経由でPlaywrightなしでも動作します。 + refベースの要素スクリーンショット（`--ref`）もそこで動作しますが、`--full-page` は `--ref` や `--element` と組み合わせられません。 -- existing-session のアクションは、managed browser の - 経路よりもまだ制限があります: - - `click`、`type`、`hover`、`scrollIntoView`、`drag`、`select` は - CSS セレクターではなく snapshot refs を必要とします - - `click` は左ボタンのみです（ボタンオーバーライドや修飾キーは不可） - - `type` は `slowly=true` をサポートしません。`fill` または `press` を使用してください +- Existing-sessionのアクションは、管理ブラウザ + 経路よりも依然として制限があります: + - `click`、`type`、`hover`、`scrollIntoView`、`drag`、`select` には、 + CSSセレクターではなくsnapshot refが必要です + - `click` は左ボタンのみです（ボタン上書きやmodifierは不可） + - `type` は `slowly=true` をサポートしません。`fill` または `press` + を使用してください - `press` は `delayMs` をサポートしません - - `hover`、`scrollIntoView`、`drag`、`select`、`fill`、`evaluate` は - 呼び出しごとの timeout オーバーライドをサポートしません - - `select` は現在 1 つの値のみサポートします -- existing-session の `wait --url` は、他の browser driver と同様に exact、substring、 - glob パターンをサポートします。`wait --load networkidle` はまだサポートされていません。 -- existing-session の upload hook は `ref` または `inputRef` を必要とし、 - 1 度に 1 ファイルのみサポートし、CSS `element` ターゲティングはサポートしません。 -- existing-session の dialog hook は timeout オーバーライドをサポートしません。 -- 一部の機能は依然として managed browser の経路が必要です。これには batch - actions、PDF export、download interception、`responsebody` が含まれます。 -- existing-session は host-local です。Chrome が別のマシン上にあるか、 - 別の network namespace にある場合は、代わりに remote CDP または node host を使用してください。 + - `hover`、`scrollIntoView`、`drag`、`select`、`fill`、`evaluate` は、 + 呼び出しごとのtimeout上書きをサポートしません + - `select` は現在、単一の値のみサポートします +- Existing-sessionの `wait --url` は、他のブラウザdriverと同様に完全一致、部分一致、globパターンを + サポートします。`wait --load networkidle` はまだサポートされていません。 +- Existing-sessionのアップロードhookでは `ref` または `inputRef` が必要で、一度に1ファイルのみサポートし、 + CSS `element` ターゲティングはサポートしません。 +- Existing-sessionのdialog hookはtimeout上書きをサポートしません。 +- バッチ + アクション、PDFエクスポート、ダウンロードインターセプト、`responsebody` など、一部の機能は依然として管理ブラウザ経路が必要です。 +- Existing-sessionは、選択したhost上、または接続された + browser node経由で接続できます。Chromeが別の場所にあり、browser nodeが接続されていない場合は、 + 代わりにremote CDPまたはnode hostを使用してください。 -## 分離の保証 +## 分離保証 -- **専用 user data dir**: 個人用ブラウザプロファイルには一切触れません。 -- **専用ポート**: 開発ワークフローとの衝突を避けるため `9222` を使用しません。 -- **決定的なタブ制御**: 「最後のタブ」ではなく `targetId` でタブを対象指定します。 +- **専用user data dir**: 個人用ブラウザプロファイルには一切触れません。 +- **専用ポート**: 開発ワークフローとの衝突を避けるため `9222` を回避します。 +- **決定的なタブ制御**: 「最後のタブ」ではなく `targetId` でタブを指定します。 -## ブラウザの選択 +## ブラウザ選択 -ローカルで起動する場合、OpenClaw は利用可能な最初のものを選びます: +ローカル起動時、OpenClawは最初に利用可能なものを選びます。 1. Chrome 2. Brave @@ -535,49 +554,49 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -`browser.executablePath` でオーバーライドできます。 +`browser.executablePath` で上書きできます。 プラットフォーム: - macOS: `/Applications` と `~/Applications` を確認します。 - Linux: `google-chrome`、`brave`、`microsoft-edge`、`chromium` などを探します。 -- Windows: 一般的なインストール場所を確認します。 +- Windows: 一般的なインストール先を確認します。 -## 制御 API（オプション） +## Control API（任意） -ローカル統合専用として、Gateway は小さな loopback HTTP API を公開します: +ローカル統合専用として、Gatewayは小さなloopback HTTP APIを公開します。 -- Status/start/stop: `GET /`、`POST /start`、`POST /stop` -- Tabs: `GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId` -- Snapshot/screenshot: `GET /snapshot`、`POST /screenshot` -- Actions: `POST /navigate`、`POST /act` -- Hooks: `POST /hooks/file-chooser`、`POST /hooks/dialog` -- Downloads: `POST /download`、`POST /wait/download` -- Debugging: `GET /console`、`POST /pdf` -- Debugging: `GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight` +- Status/start/stop: `GET /`, `POST /start`, `POST /stop` +- Tabs: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` +- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot` +- Actions: `POST /navigate`, `POST /act` +- Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog` +- Downloads: `POST /download`, `POST /wait/download` +- Debugging: `GET /console`, `POST /pdf` +- Debugging: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight` - Network: `POST /response/body` -- State: `GET /cookies`、`POST /cookies/set`、`POST /cookies/clear` -- State: `GET /storage/:kind`、`POST /storage/:kind/set`、`POST /storage/:kind/clear` -- Settings: `POST /set/offline`、`POST /set/headers`、`POST /set/credentials`、`POST /set/geolocation`、`POST /set/media`、`POST /set/timezone`、`POST /set/locale`、`POST /set/device` +- State: `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear` +- State: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear` +- Settings: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device` すべてのエンドポイントは `?profile=` を受け付けます。 -shared-secret gateway auth が設定されている場合、ブラウザ HTTP ルートにも auth が必要です: +shared-secret gateway authが設定されている場合、browser HTTPルートにも認証が必要です。 - `Authorization: Bearer ` -- `x-openclaw-password: ` またはその password を使う HTTP Basic auth +- `x-openclaw-password: ` またはそのpasswordを使うHTTP Basic auth 注意: -- このスタンドアロン loopback ブラウザ API は `trusted-proxy` や - Tailscale Serve の identity header を使用しません。 -- `gateway.auth.mode` が `none` または `trusted-proxy` の場合、これらの loopback browser - ルートはそれらの identity-bearing モードを継承しません。loopback 専用のままにしてください。 +- このスタンドアロンloopback browser APIは、trusted-proxyや + Tailscale Serveのidentity headerを**使用しません**。 +- `gateway.auth.mode` が `none` または `trusted-proxy` の場合、これらのloopback browser + ルートはそうしたidentity-bearing modeを継承しません。loopback専用のままにしてください。 ### `/act` エラー契約 -`POST /act` は、ルートレベルのバリデーションと -ポリシー失敗に対して構造化されたエラーレスポンスを使用します: +`POST /act` は、ルートレベルの検証および +ポリシー失敗に対して構造化エラーレスポンスを使用します。 ```json { "error": "", "code": "ACT_*" } @@ -585,76 +604,76 @@ shared-secret gateway auth が設定されている場合、ブラウザ HTTP 現在の `code` 値: -- `ACT_KIND_REQUIRED`（HTTP 400）: `kind` が欠落しているか認識されません。 -- `ACT_INVALID_REQUEST`（HTTP 400）: アクションペイロードの正規化またはバリデーションに失敗しました。 -- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）: 未対応のアクション種別で `selector` が使われました。 -- `ACT_EVALUATE_DISABLED`（HTTP 403）: config により `evaluate`（または `wait --fn`）が無効です。 +- `ACT_KIND_REQUIRED`（HTTP 400）: `kind` が欠落しているか、認識されません。 +- `ACT_INVALID_REQUEST`（HTTP 400）: アクションpayloadの正規化または検証に失敗しました。 +- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）: サポートされていないアクションkindで `selector` が使用されました。 +- `ACT_EVALUATE_DISABLED`（HTTP 403）: `evaluate`（または `wait --fn`）はconfigで無効です。 - `ACT_TARGET_ID_MISMATCH`（HTTP 403）: トップレベルまたはバッチ化された `targetId` がリクエスト対象と競合しています。 -- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）: このアクションは existing-session プロファイルではサポートされません。 +- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）: existing-sessionプロファイルではそのアクションはサポートされていません。 -その他のランタイム失敗では、依然として -`code` フィールドなしの `{ "error": "" }` が返る場合があります。 +その他のruntime失敗では、`code` フィールドなしの `{ "error": "" }` が +返ることもあります。 -### Playwright 要件 +### Playwright要件 一部の機能（navigate/act/AI snapshot/role snapshot、要素スクリーンショット、 -PDF）には Playwright が必要です。Playwright がインストールされていない場合、 -それらのエンドポイントは明確な 501 エラーを返します。 +PDF）にはPlaywrightが必要です。Playwrightがインストールされていない場合、それらのエンドポイントは +分かりやすい501エラーを返します。 -Playwright なしでも引き続き動作するもの: +Playwrightなしでも動作するもの: -- ARIA snapshots -- タブごとの CDP WebSocket が利用可能な場合の、managed `openclaw` browser のページ - スクリーンショット -- `existing-session` / Chrome MCP プロファイルのページスクリーンショット -- snapshot 出力からの `existing-session` の ref ベーススクリーンショット（`--ref`） +- ARIAスナップショット +- 管理された `openclaw` ブラウザで、タブごとのCDP + WebSocketが利用可能な場合のページスクリーンショット +- `existing-session` / Chrome MCPプロファイルのページスクリーンショット +- スナップショット出力からの `existing-session` refベーススクリーンショット（`--ref`） -引き続き Playwright が必要なもの: +引き続きPlaywrightが必要なもの: - `navigate` - `act` -- AI snapshots / role snapshots -- CSS セレクター要素スクリーンショット（`--element`） -- 完全な browser PDF export +- AIスナップショット / role snapshot +- CSSセレクター要素スクリーンショット（`--element`） +- ブラウザ全体のPDFエクスポート -要素スクリーンショットでは `--full-page` も拒否されます。このルートは `fullPage is +要素スクリーンショットでは `--full-page` も拒否されます。ルートは `fullPage is not supported for element screenshots` を返します。 `Playwright is not available in this gateway build` と表示された場合は、完全な -Playwright パッケージ（`playwright-core` ではなく）をインストールして gateway を再起動するか、 -ブラウザサポート付きで OpenClaw を再インストールしてください。 +Playwright package（`playwright-core` ではなく）をインストールしてgatewayを再起動するか、 +ブラウザサポート付きでOpenClawを再インストールしてください。 -#### Docker での Playwright インストール +#### DockerでのPlaywrightインストール -Gateway が Docker 上で動作している場合は、`npx playwright` を避けてください（npm の override 競合が発生します）。 -代わりに、バンドル済み CLI を使用してください: +GatewayをDockerで実行している場合は、`npx playwright` は使わないでください（npm overrideの競合）。 +代わりに、同梱CLIを使います。 ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -ブラウザダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH`（例: -`/home/node/.cache/ms-playwright`）を設定し、`OPENCLAW_HOME_VOLUME` または bind mount によって -`/home/node` が永続化されるようにしてください。[Docker](/ja-JP/install/docker) を参照してください。 +ブラウザダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH`（たとえば +`/home/node/.cache/ms-playwright`）を設定し、`/home/node` が +`OPENCLAW_HOME_VOLUME` またはbind mount経由で永続化されるようにしてください。[Docker](/ja-JP/install/docker)を参照してください。 ## 仕組み（内部） 高レベルのフロー: -- 小さな**制御サーバー**が HTTP リクエストを受け付けます。 -- **CDP** 経由で Chromium ベースブラウザ（Chrome/Brave/Edge/Chromium）に接続します。 -- 高度なアクション（クリック/入力/スナップショット/PDF）には、CDP の上に +- 小さな**control server**がHTTPリクエストを受け付けます。 +- **CDP** 経由でChromium系ブラウザ（Chrome/Brave/Edge/Chromium）に接続します。 +- 高度なアクション（クリック/入力/スナップショット/PDF）には、CDPの上に **Playwright** を使用します。 -- Playwright がない場合は、Playwright を必要としない操作のみ利用できます。 +- Playwrightがない場合、Playwright非依存の操作のみ利用可能です。 -この設計により、エージェントは安定した決定的インターフェース上で動作しつつ、 -ローカル/リモートのブラウザやプロファイルを切り替えられます。 +この設計により、ローカル/リモートのブラウザやプロファイルを入れ替えつつ、 +エージェント側は安定した決定的インターフェースを維持できます。 -## CLI クイックリファレンス +## CLIクイックリファレンス すべてのコマンドは、特定のプロファイルを対象にするために `--browser-profile ` を受け付けます。 -また、すべてのコマンドは machine-readable な出力（安定したペイロード）のために `--json` も受け付けます。 +また、すべてのコマンドは機械可読出力（安定したpayload）のために `--json` も受け付けます。 基本: @@ -687,10 +706,10 @@ docker compose run --rm openclaw-cli \ ライフサイクルに関する注意: -- attach-only および remote CDP プロファイルでは、テスト後の適切なクリーンアップコマンドは - 引き続き `openclaw browser stop` です。これは、基盤となる - ブラウザを終了する代わりに、アクティブな制御セッションを閉じて - 一時的なエミュレーションオーバーライドをクリアします。 +- attach-onlyおよびremote CDPプロファイルでは、テスト後の + 正しいクリーンアップコマンドは引き続き `openclaw browser stop` です。これは、基になる + ブラウザを終了する代わりに、アクティブな制御セッションを閉じ、 + 一時的なエミュレーション上書きをクリアします。 - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` @@ -741,60 +760,60 @@ docker compose run --rm openclaw-cli \ 注意: -- `upload` と `dialog` は**事前準備**の呼び出しです。ファイル選択ダイアログ/ダイアログを - 発生させる click/press の前に実行してください。 -- ダウンロードと trace の出力パスは OpenClaw の temp ルートに制限されています: +- `upload` と `dialog` は**事前待機**の呼び出しです。chooser/dialogを発生させる + click/pressの前に実行してください。 +- ダウンロードおよびtraceの出力パスは、OpenClawの一時ルートに制限されます: - traces: `/tmp/openclaw`（フォールバック: `${os.tmpdir()}/openclaw`） - downloads: `/tmp/openclaw/downloads`（フォールバック: `${os.tmpdir()}/openclaw/downloads`） -- upload パスは OpenClaw の temp uploads ルートに制限されています: +- アップロードパスは、OpenClawの一時uploadsルートに制限されます: - uploads: `/tmp/openclaw/uploads`（フォールバック: `${os.tmpdir()}/openclaw/uploads`） -- `upload` は `--input-ref` または `--element` を使って file input を直接設定することもできます。 +- `upload` は `--input-ref` または `--element` でファイル入力を直接設定することもできます。 - `snapshot`: - - `--format ai`（Playwright インストール時のデフォルト）: 数値 refs（`aria-ref=""`）を含む AI snapshot を返します。 - - `--format aria`: アクセシビリティツリーを返します（refs なし、検査専用）。 - - `--efficient`（または `--mode efficient`）: compact role snapshot プリセット（interactive + compact + depth + 低めの maxChars）。 - - config デフォルト（tool/CLI のみ）: 呼び出し元が mode を渡さない場合に efficient snapshots を使うには `browser.snapshotDefaults.mode: "efficient"` を設定してください（[Gateway configuration](/ja-JP/gateway/configuration-reference#browser) を参照）。 - - Role snapshot オプション（`--interactive`、`--compact`、`--depth`、`--selector`）は、`ref=e12` のような refs を持つ role-based snapshot を強制します。 - - `--frame "