From 1d07fbb4c0b70eb04786726d5d03d34aa95a4b95 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 18 Apr 2026 04:49:23 +0000 Subject: [PATCH] chore(i18n): refresh ja-JP translations --- docs/ja-JP/concepts/agent-workspace.md | 164 +- docs/ja-JP/concepts/context.md | 117 +- docs/ja-JP/concepts/qa-e2e-automation.md | 279 ++- docs/ja-JP/concepts/system-prompt.md | 115 +- docs/ja-JP/gateway/configuration-reference.md | 1608 +++++++++-------- docs/ja-JP/gateway/protocol.md | 388 ++-- docs/ja-JP/help/testing.md | 908 +++++----- docs/ja-JP/platforms/macos.md | 197 +- docs/ja-JP/plugins/sdk-channel-plugins.md | 280 ++- docs/ja-JP/plugins/sdk-overview.md | 682 +++---- docs/ja-JP/refactor/qa.md | 330 ++-- 11 files changed, 2535 insertions(+), 2533 deletions(-) diff --git a/docs/ja-JP/concepts/agent-workspace.md b/docs/ja-JP/concepts/agent-workspace.md index 7bd816722..eb83ec7d2 100644 --- a/docs/ja-JP/concepts/agent-workspace.md +++ b/docs/ja-JP/concepts/agent-workspace.md @@ -1,38 +1,32 @@ --- read_when: - - エージェントワークスペースまたはそのファイルレイアウトを説明する必要がある場合 - - エージェントワークスペースをバックアップまたは移行したい場合 -summary: 'エージェントワークスペース: 場所、レイアウト、バックアップ戦略' -title: Agent Workspace + - エージェントのワークスペースまたはそのファイルレイアウトを説明する必要があります + - エージェントのワークスペースをバックアップまたは移行したい場合があります +summary: 'エージェントのワークスペース: 保存場所、レイアウト、バックアップ戦略' +title: エージェントのワークスペース x-i18n: - generated_at: "2026-04-05T12:40:45Z" + generated_at: "2026-04-18T04:40:09Z" model: gpt-5.4 provider: openai - source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a + source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e source_path: concepts/agent-workspace.md workflow: 15 --- -# Agent Workspace +# エージェントのワークスペース -ワークスペースはエージェントのホームです。これはファイルツールとワークスペースコンテキストで使用される唯一の作業ディレクトリです。 +ワークスペースはエージェントのホームです。これは、ファイルツールとワークスペースコンテキストで使用される唯一の作業ディレクトリです。 これを非公開に保ち、メモリとして扱ってください。 -これは `~/.openclaw/` とは別で、そちらには設定、認証情報、セッションが保存されます。 +これは、設定、認証情報、セッションを保存する `~/.openclaw/` とは別です。 -**重要:** ワークスペースは**デフォルトのcwd**であり、厳格なサンドボックスではありません。ツールは -相対パスをワークスペース基準で解決しますが、サンドボックス化が有効でない限り、絶対パスは引き続きホスト上の -他の場所に到達できます。分離が必要な場合は、 -[`agents.defaults.sandbox`](/gateway/sandboxing)（および必要に応じてエージェントごとのサンドボックス設定）を使用してください。 -サンドボックス化が有効で、`workspaceAccess` が `"rw"` でない場合、ツールはホストワークスペースではなく、 -`~/.openclaw/sandboxes` 配下のサンドボックスワークスペース内で動作します。 +**重要:** ワークスペースは**デフォルトの cwd**であり、厳格なサンドボックスではありません。ツールはワークスペースを基準に相対パスを解決しますが、サンドボックス化が有効でない限り、絶対パスは引き続きホスト上の別の場所へ到達できます。分離が必要な場合は、[`agents.defaults.sandbox`](/ja-JP/gateway/sandboxing)（および/またはエージェントごとのサンドボックス設定）を使用してください。サンドボックス化が有効で、`workspaceAccess` が `"rw"` ではない場合、ツールはホストのワークスペースではなく、`~/.openclaw/sandboxes` 配下のサンドボックスワークスペース内で動作します。 -## デフォルトの場所 +## デフォルトの保存場所 - デフォルト: `~/.openclaw/workspace` -- `OPENCLAW_PROFILE` が設定されていて `"default"` でない場合、デフォルトは - `~/.openclaw/workspace-` になります。 -- `~/.openclaw/openclaw.json` で上書きできます: +- `OPENCLAW_PROFILE` が設定されていて `"default"` ではない場合、デフォルトは `~/.openclaw/workspace-` になります。 +- `~/.openclaw/openclaw.json` で上書きします: ```json5 { @@ -42,12 +36,10 @@ x-i18n: } ``` -`openclaw onboard`、`openclaw configure`、または `openclaw setup` は、ワークスペースが存在しない場合に -それを作成し、bootstrapファイルを初期投入します。 -サンドボックス用のseedコピーは、ワークスペース内の通常ファイルのみを受け付けます。ソースワークスペース外を -指すsymlink/hardlinkエイリアスは無視されます。 +`openclaw onboard`、`openclaw configure`、または `openclaw setup` は、ワークスペースが存在しない場合にそれを作成し、ブートストラップファイルを初期投入します。 +サンドボックスのシードコピーは、ワークスペース内の通常ファイルのみを受け入れます。ソースワークスペースの外部を指す symlink/hardlink のエイリアスは無視されます。 -すでにワークスペースファイルを自分で管理している場合は、bootstrapファイルの作成を無効にできます: +すでにワークスペースファイルを自分で管理している場合は、ブートストラップファイルの作成を無効にできます: ```json5 { agent: { skipBootstrap: true } } @@ -55,20 +47,15 @@ x-i18n: ## 追加のワークスペースフォルダー -古いインストールでは `~/openclaw` が作成されていることがあります。 -複数のワークスペースディレクトリを残しておくと、同時にアクティブなのは1つだけであるため、認証や状態のずれで -混乱を招く可能性があります。 +古いインストールでは `~/openclaw` が作成されていることがあります。複数のワークスペースディレクトリを残しておくと、同時に有効なのは1つのワークスペースだけなので、認証や状態の食い違いによって混乱を招くことがあります。 -**推奨:** アクティブなワークスペースは1つだけにしてください。追加のフォルダーをもう使っていない場合は、 -アーカイブするかゴミ箱に移動してください（例: `trash ~/openclaw`）。 -意図的に複数のワークスペースを維持する場合は、 -`agents.defaults.workspace` がアクティブなものを指していることを確認してください。 +**推奨:** 有効なワークスペースは1つだけにしてください。追加フォルダーをもう使わない場合は、アーカイブするかゴミ箱へ移動してください（例: `trash ~/openclaw`）。意図的に複数のワークスペースを保持する場合は、`agents.defaults.workspace` が有効なものを指していることを確認してください。 `openclaw doctor` は、追加のワークスペースディレクトリを検出すると警告します。 -## ワークスペースファイルマップ（各ファイルの意味） +## ワークスペースのファイルマップ（各ファイルの意味） -これらは、OpenClawがワークスペース内にあることを想定している標準ファイルです: +これらは、OpenClaw がワークスペース内にあることを想定している標準ファイルです: - `AGENTS.md` - エージェント向けの運用指示と、メモリの使い方。 @@ -78,82 +65,75 @@ x-i18n: - `SOUL.md` - ペルソナ、トーン、境界。 - 毎セッションで読み込まれます。 - - ガイド: [SOUL.md Personality Guide](/concepts/soul) + - ガイド: [SOUL.md Personality Guide](/ja-JP/concepts/soul) - `USER.md` - - ユーザーが誰で、どう呼びかけるか。 + - ユーザーが誰か、どう呼びかけるか。 - 毎セッションで読み込まれます。 - `IDENTITY.md` - エージェントの名前、雰囲気、絵文字。 - - bootstrap ritualの間に作成または更新されます。 + - ブートストラップ儀式の間に作成または更新されます。 - `TOOLS.md` - ローカルツールと慣習に関するメモ。 - - ツールの可用性は制御せず、ガイダンスにすぎません。 + - ツールの利用可否を制御するものではなく、あくまでガイダンスです。 - `HEARTBEAT.md` - - heartbeat実行用の任意の小さなチェックリスト。 + - Heartbeat 実行用の任意の小さなチェックリスト。 - トークン消費を避けるため、短く保ってください。 - `BOOT.md` - - internal hooksが有効な場合に、Gateway再起動時に実行される任意の起動チェックリスト。 - - 短く保ち、外向きの送信にはmessageツールを使ってください。 + - 内部フックが有効なとき、Gateway 再起動時に実行される任意の起動チェックリスト。 + - 短く保ち、外向き送信には message ツールを使用してください。 - `BOOTSTRAP.md` - - 初回実行時の一度きりのritual。 + - 初回実行時だけの儀式。 - 新規ワークスペースに対してのみ作成されます。 - - ritualが完了したら削除してください。 + - 儀式が完了したら削除してください。 - `memory/YYYY-MM-DD.md` - 日次メモリログ（1日1ファイル）。 - - セッション開始時に今日分と昨日分を読むことを推奨します。 + - セッション開始時に今日と昨日のファイルを読むことを推奨します。 - `MEMORY.md`（任意） - キュレーションされた長期メモリ。 - - mainの非公開セッションでのみ読み込んでください（共有/グループコンテキストでは読み込まないでください）。 + - メインの非公開セッションでのみ読み込んでください（共有/グループコンテキストではありません）。 -ワークフローと自動メモリフラッシュについては [Memory](/concepts/memory) を参照してください。 +ワークフローと自動メモリフラッシュについては [Memory](/ja-JP/concepts/memory) を参照してください。 - `skills/`（任意） - - ワークスペース固有のSkills。 - - そのワークスペースにおける最優先のSkill配置場所です。 - - 名前が衝突した場合、project agent skills、personal agent skills、managed skills、bundled skills、 - および `skills.load.extraDirs` より優先されます。 + - ワークスペース固有の Skills。 + - そのワークスペースにおける最優先の Skills 保存場所です。 + - 名前が衝突した場合、プロジェクトのエージェント Skills、個人用エージェント Skills、管理された Skills、同梱 Skills、および `skills.load.extraDirs` より優先されます。 - `canvas/`（任意） - - ノード表示用のCanvas UIファイル（例: `canvas/index.html`）。 + - Node 表示用の Canvas UI ファイル（例: `canvas/index.html`）。 -bootstrapファイルが欠けている場合、OpenClawはセッションに「missing file」マーカーを挿入して継続します。 -大きなbootstrapファイルは挿入時に切り詰められます。 -上限は `agents.defaults.bootstrapMaxChars`（デフォルト: 20000）および -`agents.defaults.bootstrapTotalMaxChars`（デフォルト: 150000）で調整してください。 +ブートストラップファイルのいずれかが欠けている場合、OpenClaw は「missing file」マーカーをセッションに注入して継続します。大きなブートストラップファイルは注入時に切り詰められます。制限は `agents.defaults.bootstrapMaxChars`（デフォルト: 12000）と `agents.defaults.bootstrapTotalMaxChars`（デフォルト: 60000）で調整してください。 `openclaw setup` は、既存ファイルを上書きせずに不足しているデフォルトを再作成できます。 ## ワークスペースに含まれないもの -これらは `~/.openclaw/` 配下にあり、ワークスペースrepoにはコミットすべきではありません: +以下は `~/.openclaw/` 配下にあり、ワークスペースのリポジトリにコミットすべきではありません: - `~/.openclaw/openclaw.json`（設定） - `~/.openclaw/agents//agent/auth-profiles.json`（モデル認証プロファイル: OAuth + API keys） -- `~/.openclaw/credentials/`（channel/provider状態とレガシーOAuthインポートデータ） +- `~/.openclaw/credentials/`（チャネル/プロバイダーの状態と旧OAuthインポートデータ） - `~/.openclaw/agents//sessions/`（セッショントランスクリプト + メタデータ） -- `~/.openclaw/skills/`（managed skills） +- `~/.openclaw/skills/`（管理された Skills） -セッションや設定を移行する必要がある場合は、それらを別途コピーし、 -バージョン管理の対象外にしてください。 +セッションや設定を移行する必要がある場合は、それらを別途コピーし、バージョン管理には含めないでください。 -## Gitバックアップ（推奨、非公開） +## Git バックアップ（推奨、非公開） -ワークスペースは非公開のメモリとして扱ってください。バックアップと復旧ができるように、 -**非公開**のgit repoに入れてください。 +ワークスペースは非公開のメモリとして扱ってください。バックアップと復旧ができるよう、**非公開**の git リポジトリに置いてください。 -これらの手順は、Gatewayが動作しているマシン上で実行してください（ワークスペースはそこにあります）。 +これらの手順は Gateway が動作しているマシン上で実行してください（ワークスペースはそこにあります）。 -### 1) repoを初期化する +### 1) リポジトリを初期化する -gitがインストールされていれば、新規ワークスペースは自動的に初期化されます。 -このワークスペースがまだrepoでない場合は、次を実行してください: +git がインストールされている場合、まったく新しいワークスペースは自動的に初期化されます。このワークスペースがまだリポジトリでない場合は、次を実行してください: ```bash cd ~/.openclaw/workspace @@ -162,14 +142,14 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/ git commit -m "Add agent workspace" ``` -### 2) 非公開のremoteを追加する（初心者向けオプション） +### 2) 非公開リモートを追加する（初心者向けオプション） オプションA: GitHub web UI -1. GitHubで新しい**非公開**リポジトリを作成します。 -2. READMEで初期化しないでください（マージ競合を避けるため）。 -3. HTTPSのremote URLをコピーします。 -4. remoteを追加してpushします: +1. GitHub で新しい**非公開**リポジトリを作成します。 +2. README で初期化しないでください（マージ競合を避けるため）。 +3. HTTPS リモートURLをコピーします。 +4. リモートを追加して push します: ```bash git branch -M main @@ -177,7 +157,7 @@ git remote add origin git push -u origin main ``` -オプションB: GitHub CLI（`gh`） +オプションB: GitHub CLI (`gh`) ```bash gh auth login @@ -186,10 +166,10 @@ gh repo create openclaw-workspace --private --source . --remote origin --push オプションC: GitLab web UI -1. GitLabで新しい**非公開**リポジトリを作成します。 -2. READMEで初期化しないでください（マージ競合を避けるため）。 -3. HTTPSのremote URLをコピーします。 -4. remoteを追加してpushします: +1. GitLab で新しい**非公開**リポジトリを作成します。 +2. README で初期化しないでください（マージ競合を避けるため）。 +3. HTTPS リモートURLをコピーします。 +4. リモートを追加して push します: ```bash git branch -M main @@ -208,16 +188,15 @@ git push ## シークレットをコミットしないでください -非公開repoであっても、ワークスペースにシークレットを保存しないでください: +非公開リポジトリであっても、ワークスペースにシークレットを保存するのは避けてください: -- API keys、OAuth tokens、passwords、または非公開の認証情報。 -- `~/.openclaw/` 配下のあらゆるもの。 +- API keys、OAuth tokens、passwords、または private credentials。 +- `~/.openclaw/` 配下のものすべて。 - チャットや機密添付ファイルの生ダンプ。 -機密参照をどうしても保存する必要がある場合は、プレースホルダーを使い、実際の -シークレットは別の場所に保管してください（パスワードマネージャー、環境変数、または `~/.openclaw/`）。 +機密参照を保存しなければならない場合は、プレースホルダーを使い、本物のシークレットは別の場所に保管してください（パスワードマネージャー、環境変数、または `~/.openclaw/`）。 -推奨される `.gitignore` の開始例: +推奨される `.gitignore` の初期例: ```gitignore .DS_Store @@ -227,24 +206,21 @@ git push **/secrets* ``` -## ワークスペースを新しいマシンに移す +## ワークスペースを新しいマシンへ移す -1. 目的のパスにrepoをcloneします（デフォルトは `~/.openclaw/workspace`）。 +1. 希望するパス（デフォルトは `~/.openclaw/workspace`）にリポジトリを clone します。 2. `~/.openclaw/openclaw.json` で `agents.defaults.workspace` をそのパスに設定します。 3. `openclaw setup --workspace ` を実行して、不足しているファイルを初期投入します。 -4. セッションが必要な場合は、古いマシンから `~/.openclaw/agents//sessions/` を - 別途コピーしてください。 +4. セッションが必要な場合は、古いマシンから `~/.openclaw/agents//sessions/` を別途コピーしてください。 -## 高度な注意事項 +## 補足 -- マルチエージェントルーティングでは、エージェントごとに異なるワークスペースを使用できます。 - ルーティング設定については [Channel routing](/ja-JP/channels/channel-routing) を参照してください。 -- `agents.defaults.sandbox` が有効な場合、main以外のセッションは - `agents.defaults.sandbox.workspaceRoot` 配下のセッションごとのサンドボックスワークスペースを使用できます。 +- マルチエージェントのルーティングでは、エージェントごとに異なるワークスペースを使えます。ルーティング設定については [Channel routing](/ja-JP/channels/channel-routing) を参照してください。 +- `agents.defaults.sandbox` が有効な場合、非メインセッションでは `agents.defaults.sandbox.workspaceRoot` 配下のセッションごとのサンドボックスワークスペースを使用できます。 ## 関連 - [Standing Orders](/ja-JP/automation/standing-orders) — ワークスペースファイル内の永続的な指示 -- [Heartbeat](/gateway/heartbeat) — HEARTBEAT.mdワークスペースファイル -- [Session](/concepts/session) — セッション保存パス -- [Sandboxing](/gateway/sandboxing) — サンドボックス環境でのワークスペースアクセス +- [Heartbeat](/ja-JP/gateway/heartbeat) — HEARTBEAT.md ワークスペースファイル +- [Session](/ja-JP/concepts/session) — セッション保存パス +- [Sandboxing](/ja-JP/gateway/sandboxing) — サンドボックス環境におけるワークスペースアクセス diff --git a/docs/ja-JP/concepts/context.md b/docs/ja-JP/concepts/context.md index 58f8db839..86899d5d1 100644 --- a/docs/ja-JP/concepts/context.md +++ b/docs/ja-JP/concepts/context.md @@ -1,51 +1,51 @@ --- read_when: - - OpenClawにおける「コンテキスト」の意味を理解したい場合 - - モデルがなぜ何かを「知っている」のか（あるいは忘れたのか）をデバッグしている場合 - - コンテキストのオーバーヘッドを減らしたい場合（`/context`、`/status`、`/compact`） -summary: 'コンテキスト: モデルが何を見るか、どのように構築されるか、そしてそれをどのように調べるか' + - OpenClawにおける「コンテキスト」が何を意味するのかを理解したい + - モデルがなぜ何かを「知っている」のか（または忘れたのか）をデバッグしている + - コンテキストのオーバーヘッドを減らしたい（`/context`、`/status`、`/compact`） +summary: コンテキスト：モデルが何を見るか、どのように構築されるか、そしてそれをどのように調べるか title: コンテキスト x-i18n: - generated_at: "2026-04-12T23:27:59Z" + generated_at: "2026-04-18T04:40:12Z" model: gpt-5.4 provider: openai - source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d + source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9 source_path: concepts/context.md workflow: 15 --- # コンテキスト -「コンテキスト」とは、**OpenClawが実行時にモデルへ送信するすべてのもの**です。これはモデルの**コンテキストウィンドウ**（トークン上限）によって制限されます。 +「コンテキスト」とは、**OpenClawが実行のためにモデルへ送信するすべて**です。これは、モデルの**コンテキストウィンドウ**（トークン上限）によって制限されます。 -初心者向けのイメージ: +初心者向けのイメージ： -- **システムプロンプト**（OpenClawが構築）: ルール、ツール、Skills リスト、時刻/ランタイム、注入されたワークスペースファイル。 -- **会話履歴**: このセッションにおけるあなたのメッセージ + アシスタントのメッセージ。 -- **ツール呼び出し/結果 + 添付**: コマンド出力、ファイル読み取り、画像/音声など。 +- **システムプロンプト**（OpenClawが構築）: ルール、ツール、Skillsの一覧、時刻/ランタイム、注入されたワークスペースファイル。 +- **会話履歴**: このセッションにおけるあなたのメッセージとアシスタントのメッセージ。 +- **ツール呼び出し/結果 + 添付ファイル**: コマンド出力、ファイル読み取り、画像/音声など。 -コンテキストは「メモリ」とは_同じではありません_。メモリはディスクに保存されて後で再読み込みできますが、コンテキストはモデルの現在のウィンドウ内に入っているものです。 +コンテキストは「メモリ」とは_同じものではありません_。メモリはディスクに保存して後で再読み込みできますが、コンテキストはモデルの現在のウィンドウ内に入っているものです。 -## クイックスタート（コンテキストを調べる） +## クイックスタート（コンテキストを確認する） -- `/status` → 「ウィンドウがどの程度埋まっているか」の簡易表示 + セッション設定。 -- `/context list` → 注入されているもの + おおよそのサイズ（ファイルごと + 合計）。 -- `/context detail` → より詳細な内訳: ファイルごと、ツールスキーマごとのサイズ、Skill エントリごとのサイズ、システムプロンプトサイズ。 -- `/usage tokens` → 通常の返信に返信ごとの使用量フッターを追加。 -- `/compact` → 古い履歴をコンパクトなエントリに要約して、ウィンドウの空きを増やす。 +- `/status` → 「ウィンドウがどれくらい埋まっているか？」のクイック表示 + セッション設定。 +- `/context list` → 何が注入されているか + おおよそのサイズ（ファイルごと + 合計）。 +- `/context detail` → より詳細な内訳: ファイルごと、ツールスキーマごとのサイズ、skillエントリごとのサイズ、システムプロンプトのサイズ。 +- `/usage tokens` → 通常の返信に、返信ごとの使用量フッターを追加。 +- `/compact` → 古い履歴を要約してコンパクトなエントリにし、ウィンドウの空きを増やす。 関連項目: [スラッシュコマンド](/ja-JP/tools/slash-commands)、[トークン使用量とコスト](/ja-JP/reference/token-use)、[Compaction](/ja-JP/concepts/compaction)。 ## 出力例 -値はモデル、プロバイダ、ツールポリシー、ワークスペース内の内容によって異なります。 +値は、モデル、プロバイダー、ツールポリシー、ワークスペース内の内容によって変わります。 ### `/context list` ``` 🧠 Context breakdown Workspace: -Bootstrap max/file: 20,000 chars +Bootstrap max/file: 12,000 chars Sandbox: mode=non-main sandboxed=false System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) @@ -85,31 +85,31 @@ Top tools (schema size): ## コンテキストウィンドウに含まれるもの -モデルが受け取るものはすべてカウントされます。これには以下が含まれます: +モデルが受け取るものはすべて含まれます。たとえば： -- システムプロンプト（すべてのセクション）。 +- システムプロンプト（全セクション）。 - 会話履歴。 - ツール呼び出し + ツール結果。 -- 添付/文字起こし（画像/音声/ファイル）。 -- Compaction の要約と pruning アーティファクト。 -- プロバイダの「ラッパー」や隠しヘッダー（見えなくてもカウントされる）。 +- 添付ファイル/文字起こし（画像/音声/ファイル）。 +- Compactionの要約と刈り込みアーティファクト。 +- プロバイダーの「ラッパー」や隠しヘッダー（見えなくてもカウントされる）。 -## OpenClawがシステムプロンプトをどのように構築するか +## OpenClawがシステムプロンプトを構築する方法 -システムプロンプトは**OpenClawが所有**しており、実行ごとに再構築されます。これには以下が含まれます: +システムプロンプトは**OpenClawが管理**しており、実行ごとに再構築されます。含まれる内容は次のとおりです： - ツール一覧 + 短い説明。 -- Skills リスト（メタデータのみ。詳細は後述）。 +- Skills一覧（メタデータのみ。詳細は後述）。 - ワークスペースの場所。 -- 時刻（UTC + 設定されていれば変換後のユーザー時刻）。 +- 時刻（UTC + 設定されている場合は変換後のユーザー時刻）。 - ランタイムメタデータ（ホスト/OS/モデル/thinking）。 -- **Project Context** 配下に注入されるワークスペースのブートストラップファイル。 +- **Project Context**配下に注入されたワークスペースのブートストラップファイル。 -完全な内訳: [System Prompt](/ja-JP/concepts/system-prompt)。 +完全な内訳: [システムプロンプト](/ja-JP/concepts/system-prompt)。 ## 注入されるワークスペースファイル（Project Context） -デフォルトでは、OpenClawは固定のワークスペースファイル群を（存在すれば）注入します: +デフォルトでは、OpenClawは固定のワークスペースファイル群を注入します（存在する場合）： - `AGENTS.md` - `SOUL.md` @@ -119,66 +119,61 @@ Top tools (schema size): - `HEARTBEAT.md` - `BOOTSTRAP.md`（初回実行時のみ） -大きなファイルは、`agents.defaults.bootstrapMaxChars`（デフォルト `20000` 文字）を使ってファイルごとに切り詰められます。OpenClawはさらに、ファイル全体をまたいだブートストラップ注入の合計上限 `agents.defaults.bootstrapTotalMaxChars`（デフォルト `150000` 文字）も適用します。`/context` では、**raw と injected** のサイズ、および切り詰めが発生したかどうかが表示されます。 +大きいファイルは、`agents.defaults.bootstrapMaxChars`（デフォルト `12000` 文字）を使ってファイルごとに切り詰められます。OpenClawはさらに、ファイル全体にまたがるブートストラップ注入の合計上限 `agents.defaults.bootstrapTotalMaxChars`（デフォルト `60000` 文字）も適用します。`/context` では、**raw と injected** のサイズ、および切り詰めが発生したかどうかが表示されます。 -切り詰めが発生すると、ランタイムは Project Context の下にプロンプト内警告ブロックを注入できます。これは `agents.defaults.bootstrapPromptTruncationWarning`（`off`、`once`、`always`。デフォルトは `once`）で設定します。 +切り詰めが発生すると、ランタイムはProject Context配下にプロンプト内警告ブロックを注入できます。これは `agents.defaults.bootstrapPromptTruncationWarning`（`off`、`once`、`always`。デフォルトは `once`）で設定します。 -## Skills: 注入されるものと必要時に読み込まれるもの +## Skills: 注入されるものと必要時ロードされるもの -システムプロンプトには、コンパクトな**Skills リスト**（名前 + 説明 + 場所）が含まれます。このリストには実際のオーバーヘッドがあります。 +システムプロンプトには、コンパクトな**Skills一覧**（名前 + 説明 + 場所）が含まれます。この一覧には実際のオーバーヘッドがあります。 -Skill の指示はデフォルトでは含まれません。モデルは必要なときにだけ、その Skill の `SKILL.md` を `read` することが想定されています。 +skillの指示内容自体は、デフォルトでは含まれません。モデルは、必要なときにだけそのskillの `SKILL.md` を `read` する想定です。 ## ツール: コストは2種類ある -ツールは2つの形でコンテキストに影響します: +ツールは、2つの形でコンテキストに影響します： 1. システムプロンプト内の**ツール一覧テキスト**（「Tooling」として見えるもの）。 -2. **ツールスキーマ**（JSON）。これらはモデルがツールを呼び出せるように送られます。プレーンテキストとして見えなくても、コンテキストにカウントされます。 +2. **ツールスキーマ**（JSON）。モデルがツールを呼び出せるように送信されます。プレーンテキストとしては見えなくても、コンテキストに含まれます。 -`/context detail` では最大のツールスキーマを内訳表示するため、どこが支配的か確認できます。 +`/context detail` では、どのツールスキーマが最も大きいかを分解して表示できるため、何が支配的かを確認できます。 ## コマンド、ディレクティブ、「インラインショートカット」 -スラッシュコマンドは Gateway によって処理されます。動作にはいくつかの種類があります: +スラッシュコマンドはGatewayによって処理されます。動作にはいくつかの種類があります： -- **スタンドアロンコマンド**: `/...` のみのメッセージはコマンドとして実行されます。 +- **スタンドアロンコマンド**: `/...` だけのメッセージは、コマンドとして実行されます。 - **ディレクティブ**: `/think`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/model`、`/queue` は、モデルがメッセージを見る前に取り除かれます。 - - ディレクティブのみのメッセージはセッション設定を保持します。 - - 通常メッセージ内のインラインディレクティブは、メッセージ単位のヒントとして機能します。 -- **インラインショートカット**（許可リストにある送信者のみ）: 通常メッセージ内の特定の `/...` トークンは即座に実行されることがあり（例: 「hey /status」）、残りのテキストをモデルが見る前に取り除かれます。 + - ディレクティブだけのメッセージは、セッション設定を保持します。 + - 通常メッセージ内のインラインディレクティブは、メッセージ単位のヒントとして動作します。 +- **インラインショートカット**（許可リストに載った送信者のみ）: 通常メッセージ内の特定の `/...` トークンは即座に実行できます（例: 「hey /status」）。その後、残りのテキストがモデルに渡される前に取り除かれます。 詳細: [スラッシュコマンド](/ja-JP/tools/slash-commands)。 -## セッション、Compaction、pruning（何が保持されるか） +## セッション、Compaction、刈り込み（何が保持されるか） -メッセージをまたいで何が保持されるかは、その仕組みによって異なります: +メッセージをまたいで何が保持されるかは、仕組みによって異なります： -- **通常の履歴**は、ポリシーによって compact/prune されるまでセッショントランスクリプトに保持されます。 -- **Compaction** は要約をトランスクリプトに保持し、最近のメッセージはそのまま残します。 -- **Pruning** は実行時の_インメモリ_プロンプトから古いツール結果を削除しますが、トランスクリプト自体は書き換えません。 +- **通常の履歴** は、ポリシーにより compact/prune されるまでセッショントランスクリプトに保持されます。 +- **Compaction** は、要約をトランスクリプト内に保持し、最近のメッセージはそのまま維持します。 +- **刈り込み** は、実行時の_メモリ内_プロンプトから古いツール結果を削除しますが、トランスクリプト自体は書き換えません。 ドキュメント: [Session](/ja-JP/concepts/session)、[Compaction](/ja-JP/concepts/compaction)、[Session pruning](/ja-JP/concepts/session-pruning)。 -デフォルトでは、OpenClawは組み立てと -compaction に組み込みの `legacy` コンテキストエンジンを使用します。`kind: "context-engine"` を提供する Plugin をインストールし、 -`plugins.slots.contextEngine` でそれを選択すると、OpenClawはコンテキストの組み立て、`/compact`、および関連するサブエージェントのコンテキストライフサイクルフックをそのエンジンに委譲します。`ownsCompaction: false` は `legacy` -エンジンへの自動フォールバックを意味しません。アクティブなエンジンは依然として `compact()` を正しく実装している必要があります。完全な -プラガブルインターフェース、ライフサイクルフック、設定については -[Context Engine](/ja-JP/concepts/context-engine) を参照してください。 +デフォルトでは、OpenClawは組み立てと compaction に組み込みの `legacy` コンテキストエンジンを使います。`kind: "context-engine"` を提供する plugin をインストールし、`plugins.slots.contextEngine` でそれを選ぶと、OpenClawは代わりにコンテキストの組み立て、`/compact`、および関連する subagent コンテキストライフサイクルフックをそのエンジンに委譲します。`ownsCompaction: false` であっても `legacy` エンジンへの自動フォールバックは行われません。アクティブなエンジンは依然として `compact()` を正しく実装している必要があります。完全なプラガブルインターフェース、ライフサイクルフック、設定については [Context Engine](/ja-JP/concepts/context-engine) を参照してください。 ## `/context` が実際に報告するもの -`/context` は、利用可能な場合は最新の**実行時構築済み**システムプロンプトレポートを優先します: +`/context` は、可能であれば最新の**実行時に構築された**システムプロンプトレポートを優先します： -- `System prompt (run)` = 最後の埋め込み（ツール使用可能）実行から取得され、セッションストアに保持されたもの。 +- `System prompt (run)` = 直近の埋め込み済み（ツール利用可能）実行から取得され、セッションストアに保存されたもの。 - `System prompt (estimate)` = 実行レポートが存在しない場合（またはそのレポートを生成しないCLIバックエンド経由で実行している場合）に、その場で計算されたもの。 -いずれの場合も、サイズと主な要因を報告しますが、完全なシステムプロンプトやツールスキーマ自体は出力しません。 +どちらの場合でも、サイズと主な寄与要因を報告しますが、システムプロンプト全体やツールスキーマそのものは出力しません。 ## 関連 -- [Context Engine](/ja-JP/concepts/context-engine) — Plugin によるカスタムコンテキスト注入 +- [Context Engine](/ja-JP/concepts/context-engine) — plugin によるカスタムコンテキスト注入 - [Compaction](/ja-JP/concepts/compaction) — 長い会話の要約 -- [System Prompt](/ja-JP/concepts/system-prompt) — システムプロンプトの構築方法 +- [システムプロンプト](/ja-JP/concepts/system-prompt) — システムプロンプトの構築方法 - [Agent Loop](/ja-JP/concepts/agent-loop) — エージェント実行サイクル全体 diff --git a/docs/ja-JP/concepts/qa-e2e-automation.md b/docs/ja-JP/concepts/qa-e2e-automation.md index d42d80a06..6e309bb23 100644 --- a/docs/ja-JP/concepts/qa-e2e-automation.md +++ b/docs/ja-JP/concepts/qa-e2e-automation.md @@ -1,15 +1,15 @@ --- read_when: - qa-labまたはqa-channelの拡張 - - リポジトリ連動のQAシナリオを追加する - - Gatewayダッシュボードを中心に、より高い現実性のQA自動化を構築する + - リポジトリ連動のQAシナリオの追加 + - Gatewayダッシュボードを中心に、より現実に近いQA自動化を構築する summary: qa-lab、qa-channel、シード済みシナリオ、プロトコルレポート向けの非公開QA自動化の構成 title: QA E2E自動化 x-i18n: - generated_at: "2026-04-17T04:43:57Z" + generated_at: "2026-04-18T04:40:10Z" model: gpt-5.4 provider: openai - source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0 + source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 source_path: concepts/qa-e2e-automation.md workflow: 15 --- @@ -22,31 +22,32 @@ x-i18n: 現在の構成要素: - `extensions/qa-channel`: DM、チャネル、スレッド、 - リアクション、編集、削除の操作面を備えた合成メッセージチャネル。 -- `extensions/qa-lab`: トランスクリプトの観察、 + リアクション、編集、削除の各操作面を備えた合成メッセージチャネル。 +- `extensions/qa-lab`: トランスクリプトの観測、 受信メッセージの注入、Markdownレポートのエクスポートを行うための - デバッガUIとQAバス。 + デバッガーUIとQAバス。 - `qa/`: キックオフタスクとベースラインQA - シナリオのための、リポジトリ連動のシードアセット。 + シナリオ向けの、リポジトリ連動のシードアセット。 -現在のQAオペレーターフローは、2ペインのQAサイトです: +現在のQAオペレーターのフローは、2ペイン構成のQAサイトです: - 左: エージェントを表示するGatewayダッシュボード（Control UI）。 -- 右: Slack風のトランスクリプトとシナリオ計画を表示するQA Lab。 +- 右: Slack風のトランスクリプトとシナリオプランを表示するQA Lab。 -実行方法: +次のコマンドで実行します: ```bash pnpm qa:lab:up ``` これによりQAサイトがビルドされ、Dockerベースのgatewayレーンが起動し、 -オペレーターまたは自動化ループがエージェントにQAミッションを与え、 -実際のチャネル動作を観察し、何が機能し、何が失敗し、 -何がブロックされたままだったかを記録できるQA Labページが公開されます。 +オペレーターまたは自動化ループがエージェントにQA +ミッションを与え、実際のチャネル動作を観察し、何が機能したか、 +何が失敗したか、何がブロックされたままだったかを記録できる +QA Labページが公開されます。 -Dockerイメージを毎回再ビルドせずにQA Lab UIをより高速に反復するには、 -QA Labバンドルをバインドマウントしてスタックを起動します: +Dockerイメージを毎回再ビルドせずにQA Lab UIをより高速に反復開発するには、 +バインドマウントされたQA Labバンドルでスタックを起動します: ```bash pnpm openclaw qa docker-build-image @@ -55,170 +56,172 @@ 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アセットのハッシュが変わるとブラウザは自動リロードされます。 +`qa:lab:up:fast` は事前ビルド済みイメージ上でDockerサービスを維持し、 +`extensions/qa-lab/web/dist` を `qa-lab` コンテナにバインドマウントします。`qa:lab:watch` +は変更時にそのバンドルを再ビルドし、QA Labアセットのハッシュが変わると +ブラウザは自動的にリロードされます。 -実際のトランスポートを使うMatrixスモークレーンを実行するには、次を使用します: +実際のトランスポートを使うMatrixスモークレーンを実行するには、次を使います: ```bash pnpm openclaw qa matrix ``` -このレーンは、Docker内に使い捨てのTuwunelホームサーバーを用意し、 +このレーンは、使い捨てのTuwunel homeserverをDockerで用意し、 一時的なdriver、SUT、observerユーザーを登録し、1つのプライベートルームを作成してから、 -QA gateway child内で実際のMatrix Pluginを実行します。ライブトランスポートレーンは、 -child configをテスト対象のトランスポートに限定した状態に保つため、 -Matrixはchild config内で`qa-channel`なしで動作します。 -構造化レポートアーティファクトと、stdout/stderrを結合したログは、 -選択したMatrix QA出力ディレクトリに書き込まれます。 +実際のMatrix pluginをQA gateway child内で実行します。ライブトランスポートレーンは、 +child設定をテスト対象のトランスポートに限定して保つため、 +child設定内では `qa-channel` なしでMatrixが動作します。構造化レポートアーティファクトと、 +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グループを対象にします。 -必要なのは `OPENCLAW_QA_TELEGRAM_GROUP_ID`、 +実際の1つのプライベートTelegramグループを対象にします。必要なのは +`OPENCLAW_QA_TELEGRAM_GROUP_ID`、 `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、 -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`、 -および同じプライベートグループ内にある2つの異なるボットです。 +`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` と、 +同じプライベートグループ内にいる2つの異なるボットです。 SUTボットにはTelegramユーザー名が必要で、 -ボット間観察は、両方のボットで `@BotFather` の -Bot-to-Bot Communication Mode を有効にしていると最も良好に動作します。 +ボット同士の観測は、両方のボットで +`@BotFather` の Bot-to-Bot Communication Mode が有効になっていると +最も安定して動作します。 -ライブトランスポートレーンは現在、それぞれが独自のシナリオリスト形状を考案するのではなく、 -より小さな1つの共通契約を共有します: +ライブトランスポートレーンは現在、それぞれが独自のシナリオ一覧形式を発明する代わりに、 +より小さな1つの共通コントラクトを共有しています: -`qa-channel` は引き続き幅広い合成プロダクト動作スイートであり、 +`qa-channel` は依然として広範な合成プロダクト動作スイートであり、 ライブトランスポートのカバレッジマトリクスには含まれません。 -| レーン | Canary | メンションゲーティング | Allowlistブロック | トップレベル返信 | 再起動後の再開 | スレッド継続返信 | スレッド分離 | リアクション観察 | ヘルプコマンド | -| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| レーン | Canary | メンションゲーティング | 許可リストブロック | トップレベル返信 | 再起動後の再開 | スレッドフォローアップ | スレッド分離 | リアクション観測 | ヘルプコマンド | +| -------- | ------ | ---------------------- | ------------------ | ---------------- | -------------- | ---------------------- | ------------ | ---------------- | -------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -これにより、`qa-channel` は幅広いプロダクト動作スイートとして維持される一方で、 -Matrix、Telegram、将来のライブトランスポートは、 -明示的なトランスポート契約チェックリストを共有できます。 +これにより、`qa-channel` は広範なプロダクト動作スイートとして維持されつつ、 +Matrix、Telegram、将来のライブトランスポートが、 +明示的な1つのトランスポートコントラクトのチェックリストを共有できます。 -DockerをQAパスに持ち込まずに、 -使い捨てLinux VMレーンを実行するには、次を使用します: +QAパスにDockerを持ち込まずに、使い捨てのLinux VMレーンを実行するには、 +次を使います: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -これにより新しいMultipassゲストが起動し、依存関係をインストールし、 -ゲスト内でOpenClawをビルドし、`qa suite` を実行したうえで、 +これにより新しいMultipass guestが起動し、依存関係をインストールし、 +guest内でOpenClawをビルドし、`qa suite` を実行してから、 通常のQAレポートとサマリーをホスト上の `.artifacts/qa-e2e/...` にコピーして戻します。 -シナリオ選択の挙動は、ホスト上の `qa suite` と同じものを再利用します。 -ホスト実行とMultipassスイート実行はどちらも、 -デフォルトで分離されたgateway workerを使って複数の選択シナリオを並列実行し、 -最大64 workerまたは選択シナリオ数のいずれか小さい方まで使用します。 +ホスト上の `qa suite` と同じシナリオ選択動作を再利用します。 +ホストとMultipassのsuite実行は、デフォルトで分離されたgateway workerを使って、 +選択された複数のシナリオを並列実行し、 +最大64 workerまたは選択シナリオ数のいずれか少ない方まで動作します。 worker数を調整するには `--concurrency ` を使い、 -直列実行には `--concurrency 1` を使ってください。 -ライブ実行では、ゲストにとって実用的なサポート対象のQA認証入力が転送されます: -envベースのプロバイダーキー、QAライブプロバイダー設定パス、 -および存在する場合の `CODEX_HOME` です。 -ゲストがマウントされたワークスペースを通じて書き戻せるよう、 -`--output-dir` はリポジトリルート配下に置いてください。 +直列実行するには `--concurrency 1` を使います。 +ライブ実行では、guestに対して実用的なサポート済みQA認証入力が転送されます: +envベースのprovider key、QA live provider設定パス、 +および存在する場合は `CODEX_HOME` です。guestが +マウントされたワークスペース経由で書き戻せるように、 +`--output-dir` はリポジトリルート配下に保ってください。 ## リポジトリ連動のシード シードアセットは `qa/` にあります: - `qa/scenarios/index.md` -- `qa/scenarios/*.md` +- `qa/scenarios//*.md` -これらは意図的にgitに置かれており、 -QA計画が人間とエージェントの両方から見えるようになっています。 +これらは意図的にgitに置かれており、QAプランが人間にも +エージェントにも見えるようになっています。 -`qa-lab` は汎用的なMarkdownランナーのままであるべきです。 -各シナリオMarkdownファイルは1回のテスト実行の信頼できる唯一の情報源であり、 -次を定義する必要があります: +`qa-lab` は汎用的なmarkdownランナーとして維持するべきです。各シナリオmarkdownファイルは +1回のテスト実行における信頼できる唯一の情報源であり、次を定義する必要があります: - シナリオメタデータ -- docsおよびコード参照 -- 任意のPlugin要件 -- 任意のgateway configパッチ +- 任意のカテゴリ、ケイパビリティ、レーン、リスクのメタデータ +- docsとcodeの参照 +- 任意のplugin要件 +- 任意のgateway設定パッチ - 実行可能な `qa-flow` `qa-flow` を支える再利用可能なランタイム面は、 -汎用的かつ横断的なままでかまいません。たとえば、 -Markdownシナリオは、埋め込みControl UIをGatewayの -`browser.request` シーム経由で操作するブラウザ側ヘルパーと、 -トランスポート側ヘルパーを組み合わせてもよく、 +汎用的かつ横断的なままで構いません。たとえば、markdownシナリオは、 +埋め込みControl UIをGatewayの `browser.request` seam経由で駆動する +ブラウザ側ヘルパーと、トランスポート側ヘルパーを組み合わせてもよく、 そのために特別扱いのランナーを追加する必要はありません。 -ベースライン一覧は、少なくとも次をカバーできるだけの広さを保つべきです: +シナリオファイルは、ソースツリーのフォルダではなく、 +プロダクト機能ごとにグループ化するべきです。ファイルを移動しても +シナリオIDは安定したままにし、実装トレーサビリティには +`docsRefs` と `codeRefs` を使ってください。 + +ベースライン一覧は、次をカバーできる程度に広く保つべきです: - DMとチャネルチャット - スレッド動作 - メッセージアクションのライフサイクル - Cronコールバック -- メモリーの再呼び出し +- メモリの想起 - モデル切り替え -- サブエージェントへのハンドオフ -- リポジトリ読解とdocs読解 +- subagent handoff +- リポジトリ読み取りとdocs読み取り - Lobster Invadersのような小さなビルドタスク1件 -## プロバイダーモックレーン +## Providerモックレーン -`qa suite` には2つのローカルプロバイダーモックレーンがあります: +`qa suite` には2つのローカルproviderモックレーンがあります: -- `mock-openai` は、シナリオ認識型のOpenClawモックです。 - これは、リポジトリ連動QAと同等性ゲート向けの、 - 既定の決定論的モックレーンのままです。 -- `aimock` は、実験的なプロトコル、 - フィクスチャ、record/replay、chaosカバレッジのために - AIMockベースのプロバイダーサーバーを起動します。 - これは追加的なものであり、`mock-openai` の - シナリオディスパッチャーを置き換えるものではありません。 +- `mock-openai` はシナリオ認識型のOpenClawモックです。 + リポジトリ連動QAとパリティゲート向けの、 + デフォルトの決定的モックレーンのままです。 +- `aimock` は実験的なプロトコル、 + フィクスチャ、record/replay、chaosカバレッジ向けに + AIMockベースのproviderサーバーを起動します。これは追加的なものであり、 + `mock-openai` シナリオディスパッチャーを置き換えるものではありません。 -プロバイダーレーンの実装は `extensions/qa-lab/src/providers/` 配下にあります。 -各プロバイダーは、自身のデフォルト値、ローカルサーバー起動、 -gateway model config、auth-profileのステージング要件、 -およびlive/mockの機能フラグを持ちます。 -共有スイートとgatewayコードは、プロバイダー名で分岐するのではなく、 -プロバイダーレジストリを経由してルーティングするべきです。 +Providerレーン実装は `extensions/qa-lab/src/providers/` 配下にあります。 +各providerは、自身のデフォルト値、ローカルサーバー起動、 +gateway model設定、auth-profileステージング要件、 +およびlive/mockケイパビリティフラグを管理します。 +共有suiteコードとgatewayコードは、provider名で分岐するのではなく、 +provider registryを経由してルーティングするべきです。 ## トランスポートアダプター -`qa-lab` はMarkdown QAシナリオ向けの汎用トランスポートシームを所有します。 -`qa-channel` はそのシーム上の最初のアダプターですが、 +`qa-lab` はmarkdown QAシナリオ向けの汎用トランスポートseamを所有します。 +`qa-channel` はそのseam上の最初のアダプターですが、 設計目標はより広いものです: -将来の実チャネルまたは合成チャネルも、 +将来の実チャネルまたは合成チャネルは、 トランスポート固有のQAランナーを追加するのではなく、 -同じスイートランナーに接続できるようにするべきです。 +同じsuite runnerに接続できるようにするべきです。 -アーキテクチャレベルでは、分担は次のとおりです: +アーキテクチャレベルでの分担は次のとおりです: -- `qa-lab` は、汎用シナリオ実行、worker並列性、アーティファクト書き込み、レポート作成を所有する。 -- トランスポートアダプターは、gateway config、準備完了、受信および送信の観察、トランスポートアクション、正規化されたトランスポート状態を所有する。 -- `qa/scenarios/` 配下のMarkdownシナリオファイルがテスト実行を定義し、`qa-lab` がそれを実行する再利用可能なランタイム面を提供する。 +- `qa-lab` は汎用シナリオ実行、worker並列性、アーティファクト書き出し、レポートを所有します。 +- トランスポートアダプターはgateway設定、readiness、受信および送信の観測、トランスポートアクション、正規化されたトランスポート状態を所有します。 +- `qa/scenarios/` 配下のmarkdownシナリオファイルがテスト実行を定義し、それを実行する再利用可能なランタイム面は `qa-lab` が提供します。 -新しいチャネルアダプター向けのメンテナー向け採用ガイダンスは、 +新しいチャネルアダプター向けのメンテナー向け導入ガイダンスは [Testing](/ja-JP/help/testing#adding-a-channel-to-qa) にあります。 ## レポート -`qa-lab` は、観察されたバスタイムラインからMarkdownのプロトコルレポートをエクスポートします。 -このレポートは次に答えるべきです: +`qa-lab` は、観測されたバスタイムラインからMarkdownのプロトコルレポートを +エクスポートします。レポートは次に答えるべきです: -- 何がうまくいったか +- 何が機能したか - 何が失敗したか - 何がブロックされたままだったか - どのフォローアップシナリオを追加する価値があるか -キャラクター性とスタイルのチェックについては、 -同じシナリオを複数のライブモデル参照で実行し、 -評価済みMarkdownレポートを書き出します: +文字やスタイルのチェックについては、同じシナリオを複数のライブモデル参照で実行し、 +判定付きMarkdownレポートを書き出します: ```bash pnpm openclaw qa character-eval \ @@ -238,45 +241,41 @@ pnpm openclaw qa character-eval \ ``` このコマンドはDockerではなく、ローカルのQA gateway child processを実行します。 -character evalシナリオは `SOUL.md` を通じてペルソナを設定し、 -その後、チャット、ワークスペースヘルプ、 -小さなファイルタスクのような通常のユーザーターンを実行するべきです。 -候補モデルには、評価中であることを知らせてはいけません。 -このコマンドは各完全トランスクリプトを保持し、 -基本的な実行統計を記録したうえで、 -judge modelに対して、fast modeかつ `xhigh` 推論で、 -自然さ、雰囲気、ユーモアによって実行結果を順位付けさせます。 -プロバイダーを比較するときは `--blind-judge-models` を使用してください: -judge promptは引き続きすべてのトランスクリプトと実行状態を受け取りますが、 +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=` をインラインで指定してください。 +レポートは、解析後に順位を実際の参照へ対応付けて戻します。 +候補実行はデフォルトで `high` thinking、 +それをサポートするOpenAIモデルでは `xhigh` になります。 +特定の候補を上書きするには +`--model provider/model,thinking=` をインラインで使います。 `--thinking ` は引き続きグローバルなフォールバックを設定し、 古い `--model-thinking ` 形式も -互換性のため維持されています。 -OpenAI候補参照はデフォルトでfast modeになっており、 -プロバイダーがサポートしている場合は優先処理が使われます。 -単一の候補またはjudgeで上書きが必要な場合は、 +互換性のため保持されています。 +OpenAI候補参照はデフォルトでfast modeとなるため、 +providerが対応している場合はpriority processingが使われます。 +単一の候補またはjudgeに上書きが必要な場合は、 `,fast`、`,no-fast`、または `,fast=false` をインラインで追加してください。 -すべての候補モデルでfast modeを強制的に有効にしたい場合にのみ、 -`--fast` を渡してください。 -候補とjudgeの実行時間はベンチマーク分析のためレポートに記録されますが、 -judge promptでは速度で順位付けしないよう明示されています。 -候補とjudgeのモデル実行は、どちらもデフォルトで並列数16です。 -プロバイダー制限またはローカルgatewayの負荷により実行のノイズが大きすぎる場合は、 +すべての候補モデルに対してfast modeを強制的に有効にしたい場合にのみ +`--fast` を渡します。候補とjudgeの所要時間は +ベンチマーク分析のためレポートに記録されますが、 +judgeプロンプトでは速度で順位付けしないよう明示されています。 +候補実行とjudge model実行はどちらもデフォルトで並列数16です。 +providerの制限やローカルgatewayの負荷で実行が不安定になる場合は、 `--concurrency` または `--judge-concurrency` を下げてください。 -候補の `--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`、 +候補 `--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` になります。 +judge `--judge-model` が指定されない場合、judgeのデフォルトは `openai/gpt-5.4,thinking=xhigh,fast` と `anthropic/claude-opus-4-6,thinking=high` です。 diff --git a/docs/ja-JP/concepts/system-prompt.md b/docs/ja-JP/concepts/system-prompt.md index 3c0580ad0..8608c56bf 100644 --- a/docs/ja-JP/concepts/system-prompt.md +++ b/docs/ja-JP/concepts/system-prompt.md @@ -1,80 +1,80 @@ --- read_when: - - システムプロンプトのテキスト、ツール一覧、または時刻／Heartbeat セクションの編集 + - システムプロンプトのテキスト、ツール一覧、または時刻/Heartbeat セクションの編集 - ワークスペースのブートストラップや Skills の注入動作の変更 -summary: OpenClawのシステムプロンプトに何が含まれているか、およびそれがどのように組み立てられるか +summary: OpenClaw のシステムプロンプトに含まれる内容と、その組み立て方法 title: システムプロンプト x-i18n: - generated_at: "2026-04-15T19:41:42Z" + generated_at: "2026-04-18T04:40:07Z" model: gpt-5.4 provider: openai - source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 + source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab source_path: concepts/system-prompt.md workflow: 15 --- # システムプロンプト -OpenClaw は、エージェントの各実行ごとにカスタムのシステムプロンプトを構築します。このプロンプトは **OpenClaw が所有** しており、pi-coding-agent のデフォルトプロンプトは使用しません。 +OpenClaw は、各エージェント実行ごとにカスタムのシステムプロンプトを構築します。このプロンプトは **OpenClaw が所有** しており、pi-coding-agent のデフォルトプロンプトは使用しません。 このプロンプトは OpenClaw によって組み立てられ、各エージェント実行に注入されます。 -プロバイダ Plugin は、完全な OpenClaw 所有のプロンプトを置き換えることなく、キャッシュを意識したプロンプトガイダンスを提供できます。プロバイダランタイムでは次のことが可能です。 +プロバイダ Plugin は、OpenClaw が所有する完全なプロンプトを置き換えることなく、キャッシュを意識したプロンプトガイダンスを提供できます。プロバイダランタイムでは次のことが可能です。 -- 少数の名前付きコアセクション（`interaction_style`、`tool_call_style`、`execution_bias`）を置き換える +- 名前付きの少数のコアセクション（`interaction_style`、 + `tool_call_style`、`execution_bias`）を置き換える - プロンプトキャッシュ境界の上に **stable prefix** を注入する - プロンプトキャッシュ境界の下に **dynamic suffix** を注入する -モデルファミリー固有のチューニングには、プロバイダ所有の寄与を使ってください。従来の -`before_prompt_build` によるプロンプト変更は、互換性維持や本当にグローバルなプロンプト変更のために残し、通常のプロバイダ動作には使わないでください。 +モデルファミリー固有のチューニングには、プロバイダ所有の貢献を使用してください。従来の +`before_prompt_build` によるプロンプト変更は、互換性のため、または本当にグローバルなプロンプト変更のために維持し、通常のプロバイダ動作には使わないでください。 ## 構造 このプロンプトは意図的にコンパクトで、固定セクションを使用します。 -- **Tooling**: 構造化ツールの source-of-truth リマインダーと、ランタイムのツール使用ガイダンス。 -- **Safety**: 権力追求的な振る舞いや監督の回避を避けるための短いガードレールリマインダー。 -- **Skills**（利用可能な場合）: 必要に応じてスキル指示を読み込む方法をモデルに伝えます。 -- **OpenClaw Self-Update**: `config.schema.lookup` を使った安全な設定確認方法、`config.patch` による設定パッチ、`config.apply` による完全設定置換、そして明示的なユーザー要求時にのみ `update.run` を実行する方法。owner-only の `gateway` ツールは、保護された exec パスに正規化される従来の `tools.bash.*` エイリアスを含め、`tools.exec.ask` / `tools.exec.security` の書き換えも拒否します。 +- **Tooling**: structured-tool の単一の正しい情報源であることのリマインダーと、ランタイムのツール使用ガイダンス。 +- **Safety**: 権力追求的な行動や監督の回避を避けるための短いガードレールのリマインダー。 +- **Skills**（利用可能な場合）: 必要に応じて skill の指示を読み込む方法をモデルに伝えます。 +- **OpenClaw Self-Update**: `config.schema.lookup` で安全に設定を確認する方法、`config.patch` で設定にパッチを適用する方法、`config.apply` で完全な設定を置き換える方法、そして明示的なユーザー要求がある場合にのみ `update.run` を実行する方法。owner-only の `gateway` ツールも、保護された exec パスに正規化される従来の `tools.bash.*` エイリアスを含め、`tools.exec.ask` / `tools.exec.security` の書き換えを拒否します。 - **Workspace**: 作業ディレクトリ（`agents.defaults.workspace`）。 - **Documentation**: OpenClaw ドキュメントへのローカルパス（リポジトリまたは npm パッケージ）と、それを読むべきタイミング。 -- **Workspace Files (injected)**: ブートストラップファイルが以下に含まれることを示します。 -- **Sandbox**（有効な場合）: サンドボックス化されたランタイム、サンドボックスのパス、昇格 exec が利用可能かどうかを示します。 -- **Current Date & Time**: ユーザーローカル時刻、タイムゾーン、時刻形式。 -- **Reply Tags**: 対応プロバイダ向けの任意の返信タグ構文。 -- **Heartbeats**: デフォルトエージェントで Heartbeat が有効な場合の Heartbeat プロンプトと ack 動作。 -- **Runtime**: ホスト、OS、node、モデル、repo ルート（検出された場合）、thinking レベル（1 行）。 -- **Reasoning**: 現在の可視性レベルと `/reasoning` 切り替えヒント。 +- **Workspace Files (injected)**: ブートストラップファイルが以下に含まれていることを示します。 +- **Sandbox**（有効な場合）: サンドボックス化されたランタイム、サンドボックスパス、昇格された exec が利用可能かどうかを示します。 +- **Current Date & Time**: ユーザーのローカル時刻、タイムゾーン、時刻形式。 +- **Reply Tags**: サポートされているプロバイダ向けの任意の返信タグ構文。 +- **Heartbeats**: デフォルトエージェントで heartbeat が有効な場合の、heartbeat プロンプトと ack 動作。 +- **Runtime**: ホスト、OS、node、モデル、リポジトリルート（検出された場合）、thinking level（1 行）。 +- **Reasoning**: 現在の可視性レベルと `/reasoning` 切り替えのヒント。 Tooling セクションには、長時間実行される作業向けのランタイムガイダンスも含まれます。 -- `exec` の sleep ループ、`yieldMs` の遅延トリック、`process` の繰り返しポーリングではなく、将来のフォローアップ（`check back later`、リマインダー、定期作業）には cron を使う +- 将来のフォローアップ（`check back later`、リマインダー、定期作業）には `exec` の sleep ループ、`yieldMs` の遅延トリック、繰り返しの `process` ポーリングではなく cron を使う - `exec` / `process` は、今すぐ開始してバックグラウンドで継続実行されるコマンドにのみ使う -- 自動完了ウェイクが有効な場合は、コマンドを一度だけ開始し、出力または失敗時の push ベースのウェイク経路に依存する -- 実行中コマンドを確認する必要があるときのログ、状態、入力、介入には `process` を使う -- タスクがより大きい場合は、`sessions_spawn` を優先する。サブエージェントの完了は push ベースで、依頼元へ自動通知される -- 完了待ちのためだけに `subagents list` / `sessions_list` をループでポーリングしない +- 自動完了 wake が有効な場合は、コマンドを一度だけ開始し、出力の発生または失敗時には push ベースの wake パスに依存する +- 実行中コマンドの確認が必要な場合は、ログ、ステータス、入力、または介入のために `process` を使う +- タスクがより大きい場合は、`sessions_spawn` を優先する。サブエージェントの完了は push ベースで、要求元に自動通知される +- 完了待ちだけのために `subagents list` / `sessions_list` をループでポーリングしない -実験的な `update_plan` ツールが有効な場合、Tooling では、それを自明でない複数ステップ作業にのみ使い、`in_progress` ステップをちょうど 1 つ維持し、各更新後に計画全体を繰り返さないようモデルに伝えます。 +実験的な `update_plan` ツールが有効な場合、Tooling では、これを自明ではない複数ステップ作業にのみ使用し、`in_progress` ステップを常にちょうど 1 つ維持し、更新のたびに計画全体を繰り返さないようモデルに指示します。 -システムプロンプト内の Safety ガードレールは助言的なものです。モデルの動作を導きますが、ポリシーを強制するものではありません。強制には、ツールポリシー、exec 承認、サンドボックス化、チャネル許可リストを使ってください。運用者は設計上これらを無効化できます。 +システムプロンプト内の Safety ガードレールは助言的なものです。これらはモデルの動作を導きますが、ポリシーを強制するものではありません。強制にはツールポリシー、exec 承認、サンドボックス化、チャネル allowlist を使用してください。オペレーターは設計上これらを無効化できます。 -ネイティブの承認カード／ボタンがあるチャネルでは、ランタイムプロンプトはエージェントに対して、まずそのネイティブ承認 UI に依存するよう伝えます。手動の -`/approve` コマンドを含めるのは、ツール結果がチャット承認を利用不可と示した場合、または手動承認のみが唯一の経路である場合だけです。 +ネイティブの承認カード/ボタンを持つチャネルでは、ランタイムプロンプトはまずそのネイティブ承認 UI に依存するようエージェントに伝えるようになりました。手動の `/approve` コマンドを含めるのは、ツール結果がチャット承認を利用できないと示す場合、または手動承認が唯一の経路である場合だけにする必要があります。 ## プロンプトモード -OpenClaw はサブエージェント向けにより小さいシステムプロンプトをレンダリングできます。ランタイムは各実行に `promptMode` を設定します（ユーザー向け設定ではありません）。 +OpenClaw はサブエージェント向けにより小さなシステムプロンプトをレンダリングできます。ランタイムは各実行に `promptMode` を設定します（ユーザー向け設定ではありません）。 -- `full`（デフォルト）: 上記の全セクションを含みます。 -- `minimal`: サブエージェントで使われ、**Skills**、**Memory Recall**、**OpenClaw Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、**Messaging**、**Silent Replies**、**Heartbeats** を省略します。Tooling、**Safety**、Workspace、Sandbox、Current Date & Time（既知の場合）、Runtime、および注入コンテキストは引き続き利用可能です。 -- `none`: ベースの識別 1 行のみを返します。 +- `full`（デフォルト）: 上記のすべてのセクションを含みます。 +- `minimal`: サブエージェント用に使われます。**Skills**、**Memory Recall**、**OpenClaw Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、**Messaging**、**Silent Replies**、**Heartbeats** を省略します。Tooling、**Safety**、Workspace、Sandbox、Current Date & Time（既知の場合）、Runtime、および注入されたコンテキストは引き続き利用可能です。 +- `none`: ベースの識別行のみを返します。 -`promptMode=minimal` の場合、追加で注入されるプロンプトは **Group Chat Context** ではなく **Subagent Context** とラベル付けされます。 +`promptMode=minimal` の場合、追加の注入プロンプトには **Group Chat Context** ではなく **Subagent Context** というラベルが付けられます。 -## ワークスペースのブートストラップ注入 +## ワークスペースブートストラップの注入 -ブートストラップファイルはトリミングされ、**Project Context** の下に追加されます。これにより、モデルは明示的に読み取らなくても識別情報やプロファイルコンテキストを把握できます。 +ブートストラップファイルはトリミングされ、**Project Context** の下に追加されます。これにより、モデルは明示的な読み取りを必要とせずに、アイデンティティとプロファイルのコンテキストを把握できます。 - `AGENTS.md` - `SOUL.md` @@ -83,34 +83,33 @@ OpenClaw はサブエージェント向けにより小さいシステムプロ - `USER.md` - `HEARTBEAT.md` - `BOOTSTRAP.md`（新規ワークスペースのみ） -- `MEMORY.md` が存在する場合はそれを、存在しない場合は小文字のフォールバックとして `memory.md` +- `MEMORY.md` が存在する場合はそれ、存在しない場合は小文字のフォールバックとして `memory.md` -これらのファイルはすべて、**ファイル固有のゲートが適用されない限り**、各ターンで **コンテキストウィンドウに注入** されます。`HEARTBEAT.md` は、通常実行では、デフォルトエージェントで Heartbeat が無効な場合、または -`agents.defaults.heartbeat.includeSystemPromptSection` が false の場合に省略されます。注入ファイルは簡潔に保ってください。特に `MEMORY.md` は時間とともに大きくなりやすく、予想外にコンテキスト使用量が増えたり、Compaction がより頻繁に発生したりする原因になります。 +これらのファイルはすべて、**ファイル固有のゲートが適用される場合を除き**、毎ターン **コンテキストウィンドウに注入** されます。通常実行時の `HEARTBEAT.md` は、デフォルトエージェントで heartbeat が無効な場合、または +`agents.defaults.heartbeat.includeSystemPromptSection` が false の場合は省略されます。注入されるファイルは簡潔に保ってください。特に `MEMORY.md` は、時間とともに肥大化して、予想外にコンテキスト使用量が増えたり、Compaction がより頻繁に発生したりする原因になります。 -> **注:** `memory/*.md` の日次ファイルは、通常のブートストラップ Project Context の一部では **ありません**。通常ターンでは、これらは -> `memory_search` と `memory_get` ツールを通じて必要時にアクセスされるため、モデルが明示的にそれらを読まない限りコンテキストウィンドウを消費しません。例外は素の `/new` および `/reset` ターンです。この最初のターンでは、ランタイムが最近の日次メモリを 1 回限りの起動コンテキストブロックとして先頭に追加することがあります。 +> **注:** `memory/*.md` の日次ファイルは、通常のブートストラップ Project Context には **含まれません**。通常のターンでは、これらは `memory_search` と `memory_get` ツールを通じて必要に応じてアクセスされるため、モデルが明示的にそれらを読まない限り、コンテキストウィンドウを消費しません。例外は素の `/new` および `/reset` ターンです。この最初のターンでは、ランタイムが最近の日次メモリをワンショットの起動コンテキストブロックとして前置できる場合があります。 大きなファイルはマーカー付きで切り詰められます。ファイルごとの最大サイズは -`agents.defaults.bootstrapMaxChars`（デフォルト: 20000）で制御されます。ファイル横断で注入されるブートストラップコンテンツ総量は -`agents.defaults.bootstrapTotalMaxChars`（デフォルト: 150000）で上限が設けられています。見つからないファイルは短い missing-file マーカーを注入します。切り詰めが発生した場合、OpenClaw は Project Context に警告ブロックを注入できます。これは +`agents.defaults.bootstrapMaxChars`（デフォルト: 12000）で制御されます。ファイル全体で注入されるブートストラップコンテンツの合計は +`agents.defaults.bootstrapTotalMaxChars`（デフォルト: 60000）で上限が設定されます。ファイルが見つからない場合は、短い missing-file マーカーが注入されます。切り詰めが発生した場合、OpenClaw は Project Context に警告ブロックを注入できます。これは `agents.defaults.bootstrapPromptTruncationWarning`（`off`、`once`、`always`； デフォルト: `once`）で制御します。 -サブエージェントセッションでは `AGENTS.md` と `TOOLS.md` のみが注入されます（サブエージェントコンテキストを小さく保つため、他のブートストラップファイルは除外されます）。 +サブエージェントセッションでは `AGENTS.md` と `TOOLS.md` のみが注入されます（サブエージェントのコンテキストを小さく保つため、他のブートストラップファイルは除外されます）。 -内部フックは `agent:bootstrap` を通じてこのステップを横取りし、注入されるブートストラップファイルを変更または置換できます（たとえば `SOUL.md` を別のペルソナに差し替えるなど）。 +内部 hook は `agent:bootstrap` を通じてこのステップに介入し、注入されるブートストラップファイルを変更または置き換えることができます（たとえば `SOUL.md` を別の persona に差し替えるなど）。 -エージェントの話し方をより generic でなくしたい場合は、まず +エージェントの話し方をより一般的でないものにしたい場合は、 [SOUL.md Personality Guide](/ja-JP/concepts/soul) から始めてください。 -各注入ファイルの寄与量（raw と injected、切り詰め、さらにツールスキーマのオーバーヘッド）を確認するには、`/context list` または `/context detail` を使ってください。[Context](/ja-JP/concepts/context) を参照してください。 +各注入ファイルの寄与量（生のサイズと注入後のサイズ、切り詰め、さらにツールスキーマのオーバーヘッド）を確認するには、`/context list` または `/context detail` を使用してください。[Context](/ja-JP/concepts/context) を参照してください。 ## 時刻処理 -ユーザーのタイムゾーンがわかっている場合、システムプロンプトには専用の **Current Date & Time** セクションが含まれます。プロンプトキャッシュを安定させるため、現在は **タイムゾーン** のみを含みます（動的な時計や時刻形式は含みません）。 +システムプロンプトには、ユーザーのタイムゾーンが既知の場合、専用の **Current Date & Time** セクションが含まれます。プロンプトキャッシュを安定させるため、ここには現在 **タイムゾーン** のみが含まれます（動的な時計や時刻形式は含みません）。 -エージェントが現在時刻を必要とする場合は `session_status` を使ってください。ステータスカードにはタイムスタンプ行が含まれます。同じツールは、セッションごとのモデル上書きも任意で設定できます（`model=default` でクリアされます）。 +エージェントが現在時刻を必要とする場合は `session_status` を使用してください。ステータスカードにはタイムスタンプ行が含まれます。同じツールでは、セッションごとのモデルオーバーライドを任意で設定することもできます（`model=default` でクリアされます）。 設定項目: @@ -121,10 +120,10 @@ OpenClaw はサブエージェント向けにより小さいシステムプロ ## Skills -条件を満たすスキルが存在する場合、OpenClaw は **利用可能なスキル一覧** をコンパクトに注入します（`formatSkillsForPrompt`）。これには各スキルの **ファイルパス** が含まれます。プロンプトは、列挙された場所（ワークスペース、managed、または bundled）にある SKILL.md を `read` で読み込むようモデルに指示します。条件を満たすスキルがない場合、Skills セクションは省略されます。 +対象となる Skills が存在する場合、OpenClaw は **利用可能な Skills 一覧**（`formatSkillsForPrompt`）を簡潔に注入し、各 skill の **ファイルパス** を含めます。プロンプトは、モデルに対して、一覧にある場所（workspace、managed、または bundled）から `read` を使って SKILL.md を読み込むよう指示します。対象となる skill がない場合、Skills セクションは省略されます。 -適格性には、スキルメタデータのゲート、ランタイム環境／設定チェック、そして `agents.defaults.skills` または -`agents.list[].skills` が設定されている場合の有効なエージェントスキル許可リストが含まれます。 +対象判定には、skill メタデータのゲート、ランタイム環境/設定チェック、および `agents.defaults.skills` または +`agents.list[].skills` が設定されている場合の有効なエージェント skill allowlist が含まれます。 ``` @@ -136,20 +135,20 @@ OpenClaw はサブエージェント向けにより小さいシステムプロ ``` -これにより、ベースプロンプトを小さく保ちながら、対象を絞ったスキル利用を可能にします。 +これにより、ベースプロンプトを小さく保ちながら、対象を絞った skill 利用を可能にします。 -スキル一覧の予算はスキルサブシステムが管理します。 +skills 一覧の予算は skills サブシステムが管理します。 - グローバルデフォルト: `skills.limits.maxSkillsPromptChars` -- エージェントごとの上書き: `agents.list[].skillsLimits.maxSkillsPromptChars` +- エージェント単位のオーバーライド: `agents.list[].skillsLimits.maxSkillsPromptChars` -一般的な境界付きランタイム抜粋は別のサーフェスを使います。 +一般的な境界付きランタイム抜粋には別のサーフェスが使われます。 - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -この分離により、スキルのサイズ設定を、`memory_get`、ライブツール結果、Compaction 後の AGENTS.md リフレッシュなどのランタイム読み取り／注入サイズから分けて扱えます。 +この分離により、skills のサイズ管理を、`memory_get`、ライブツール結果、Compaction 後の AGENTS.md 再読み込みなどのランタイム読み取り/注入サイズ管理から切り離しています。 ## Documentation -利用可能な場合、システムプロンプトには **Documentation** セクションが含まれ、ローカルの OpenClaw ドキュメントディレクトリ（リポジトリワークスペース内の `docs/` またはバンドルされた npm パッケージのドキュメント）を指し示します。さらに、公開ミラー、ソースリポジトリ、コミュニティ Discord、そしてスキル発見用の ClawHub（[https://clawhub.ai](https://clawhub.ai)）も記載されます。プロンプトは、OpenClaw の動作、コマンド、設定、またはアーキテクチャについては、まずローカルドキュメントを参照し、可能な場合は `openclaw status` を自分で実行するようモデルに指示します（アクセスできない場合にのみユーザーに尋ねます）。 +利用可能な場合、システムプロンプトには **Documentation** セクションが含まれ、ローカルの OpenClaw ドキュメントディレクトリ（リポジトリワークスペース内の `docs/` または同梱された npm パッケージの docs）を指し示します。また、公開ミラー、ソースリポジトリ、コミュニティ Discord、そして skill 発見のための ClawHub（[https://clawhub.ai](https://clawhub.ai)）についても記載します。プロンプトは、OpenClaw の動作、コマンド、設定、またはアーキテクチャについては、まずローカルドキュメントを参照するようモデルに指示し、可能であれば `openclaw status` を自分で実行し、アクセス権がない場合にのみユーザーに尋ねるようにします。 diff --git a/docs/ja-JP/gateway/configuration-reference.md b/docs/ja-JP/gateway/configuration-reference.md index c8895ee2c..01c9c5fed 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: コア OpenClaw のキー、デフォルト値、および各サブシステム専用リファレンスへのリンクのための Gateway 設定リファレンス + - 正確なフィールドレベルの設定の意味やデフォルト値が必要です + - channel、model、gateway、またはtoolの設定ブロックを検証しています +summary: core OpenClaw キー、デフォルト、および専用サブシステム参照へのリンクのための Gateway 設定リファレンス title: 設定リファレンス x-i18n: - generated_at: "2026-04-15T19:41:39Z" + generated_at: "2026-04-18T04:40:12Z" model: gpt-5.4 provider: openai - source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d + source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f 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 所有のコマンドカタログや、メモリ/QMD の詳細なノブを 1 ページにすべてインライン展開することは**意図していません**。 +このページでは、主要な OpenClaw の設定サーフェスを扱い、サブシステムごとにさらに詳細な専用リファレンスがある場合はそちらへリンクします。このページでは、すべての channel/plugin が所有するコマンドカタログや、すべての詳細な memory/QMD ノブを 1 ページにインライン展開することは**意図していません**。 -コード上の真実: +コード上の正となる情報: -- `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` は、ドリルダウン用ツール向けに、パスでスコープされた 1 つのスキーマノードを返します +- `pnpm config:docs:check` / `pnpm config:docs:gen` は、設定ドキュメントのベースラインハッシュを現在のスキーマサーフェスと照合して検証します 専用の詳細リファレンス: -- `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`、および `plugins.entries.memory-core.config.dreaming` 配下の dreaming 設定については [メモリ設定リファレンス](/ja-JP/reference/memory-config) -- 現在の組み込み + bundled コマンドカタログについては [スラッシュコマンド](/ja-JP/tools/slash-commands) -- channel 固有のコマンドサーフェスについては各 channel/plugin ページ +- `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 ページ -設定形式は **JSON5** です（コメントと末尾カンマを許可）。すべてのフィールドは省略可能です。省略された場合、OpenClaw は安全なデフォルト値を使用します。 +設定形式は **JSON5** です（コメントと末尾カンマを使用可能）。すべてのフィールドは任意です — OpenClaw は省略時に安全なデフォルトを使用します。 --- ## Channels -各 channel は、その設定セクションが存在すると自動的に起動します（`enabled: false` の場合を除く）。 +各 channel は、その設定セクションが存在すると自動的に開始されます（`enabled: false` の場合を除く）。 ### DM とグループアクセス すべての channel は DM ポリシーとグループポリシーをサポートします: -| DM ポリシー | 動作 | -| -------------------- | --------------------------------------------------------------- | +| DM ポリシー | 動作 | +| -------------------- | -------------------------------------------------------------- | | `pairing` (デフォルト) | 未知の送信者には 1 回限りのペアリングコードが送られ、owner の承認が必要 | -| `allowlist` | `allowFrom` 内の送信者のみ（またはペア済みの許可ストア） | -| `open` | すべての受信 DM を許可（`allowFrom: ["*"]` が必要） | -| `disabled` | すべての受信 DM を無視 | +| `allowlist` | `allowFrom` 内の送信者のみ（またはペアリング済み許可ストア） | +| `open` | すべての受信 DM を許可（`allowFrom: ["*"]` が必要） | +| `disabled` | すべての受信 DM を無視 | -| グループポリシー | 動作 | -| ------------------------ | ------------------------------------------------------ | -| `allowlist` (デフォルト) | 設定された許可リストに一致するグループのみ | -| `open` | グループ許可リストをバイパス（mention-gating は引き続き適用） | -| `disabled` | すべてのグループ/ルームメッセージをブロック | +| グループポリシー | 動作 | +| ----------------------- | ------------------------------------------------------ | +| `allowlist` (デフォルト) | 設定済み allowlist に一致するグループのみ | +| `open` | グループ allowlist をバイパス（mention-gating は引き続き適用） | +| `disabled` | すべてのグループ/room メッセージをブロック | -`channels.defaults.groupPolicy` は、provider の `groupPolicy` が未設定のときのデフォルト値を設定します。 -ペアリングコードは 1 時間後に期限切れになります。保留中の DM ペアリングリクエストは **channel ごとに 3 件**までです。 -provider ブロック自体が完全に欠けている場合（`channels.` がない場合）、ランタイムのグループポリシーは起動時警告とともに `allowlist`（フェイルクローズ）へフォールバックします。 +`channels.defaults.groupPolicy` は、provider の `groupPolicy` が未設定のときのデフォルトを設定します。 +ペアリングコードの有効期限は 1 時間です。保留中の DM ペアリング要求は **channel ごとに 3 件** までです。 +provider ブロックが完全に存在しない場合（`channels.` がない場合）、実行時のグループポリシーは起動時警告付きで `allowlist`（fail-closed）にフォールバックします。 -### Channel モデルのオーバーライド +### Channel model オーバーライド -特定の channel ID をモデルに固定するには `channels.modelByChannel` を使います。値には `provider/model` または設定済みのモデルエイリアスを指定できます。channel マッピングは、セッションにすでにモデルオーバーライドが存在しない場合に適用されます（たとえば `/model` で設定された場合など）。 +特定の channel ID を model に固定するには `channels.modelByChannel` を使用します。値には `provider/model` または設定済み model エイリアスを指定できます。この channel マッピングは、セッションに既に model オーバーライドがない場合（たとえば `/model` で設定された場合など）に適用されます。 ```json5 { @@ -85,9 +85,9 @@ provider ブロック自体が完全に欠けている場合（`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`: provider レベルの `groupPolicy` が未設定のときのフォールバック用グループポリシー。 +- `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）経由で動作します。リンク済みセッションが存在する場合、自動的に開始されます。 ```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 トークン: `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[]` エントリは、フォーラムトピック用の永続 ACP バインディングを設定します（`match.peer.id` には正規の `chatId:topic:topicId` を使用）。フィールドのセマンティクスは [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings) と共通です。 -- Telegram のストリームプレビューは `sendMessage` + `editMessageText` を使います（ダイレクトチャットとグループチャットの両方で動作）。 -- retry ポリシー: [Retry policy](/ja-JP/concepts/retry) を参照してください。 +- 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) と共通です。 +- Telegram のストリームプレビューは `sendMessage` + `editMessageText` を使用します（ダイレクトチャットとグループチャットの両方で動作）。 +- リトライポリシー: [Retry policy](/ja-JP/concepts/retry) を参照。 ### Discord @@ -333,36 +333,36 @@ WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。 } ``` -- トークン: `channels.discord.token`。デフォルトアカウントでは `DISCORD_BOT_TOKEN` もフォールバックとして使えます。 -- 明示的な Discord `token` を指定する直接の送信呼び出しでは、その呼び出しにそのトークンが使われます。アカウントの retry/ポリシー設定は、引き続きアクティブなランタイムスナップショット内で選択されたアカウントから取得されます。 -- 任意の `channels.discord.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 +- 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 オーバーライド）は、別のユーザーまたはロールにはメンションしているが bot にはメンションしていないメッセージを破棄します（@everyone/@here は除く）。 -- `maxLinesPerMessage`（デフォルト 17）は、2000 文字未満でも行数の多いメッセージを分割します。 -- `channels.discord.threadBindings` は Discord のスレッドバインド型ルーティングを制御します: - - `enabled`: スレッドバインドセッション機能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`、およびバインド配信/ルーティング）に対する Discord オーバーライド +- Guild slug は小文字で、空白は `-` に置き換えられます。channel キーには slug 化された名前を使用します（`#` なし）。guild ID を推奨します。 +- bot 自身が作成したメッセージはデフォルトで無視されます。`allowBots: true` で有効化されます。bot へのメンションを含む bot メッセージのみ受け入れるには `allowBots: "mentions"` を使用します（自身のメッセージは引き続きフィルタされます）。 +- `channels.discord.guilds..ignoreOtherMentions`（および channel オーバーライド）は、別の user または 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 オーバーライド - `idleHours`: 非アクティブ時の自動 unfocus を時間単位で指定する Discord オーバーライド（`0` で無効） - - `maxAgeHours`: ハード最大経過時間を時間単位で指定する Discord オーバーライド（`0` で無効） - - `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) と共通です。 + - `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) と共通です。 - `channels.discord.ui.components.accentColor` は、Discord components v2 コンテナのアクセントカラーを設定します。 -- `channels.discord.voice` は、Discord 音声 channel での会話と、任意の自動参加 + TTS オーバーライドを有効にします。 +- `channels.discord.voice` は、Discord voice channel での会話と、任意の自動参加 + TTS オーバーライドを有効にします。 - `channels.discord.voice.daveEncryption` と `channels.discord.voice.decryptionFailureTolerance` は、`@discordjs/voice` の DAVE オプションにそのまま渡されます（デフォルトは `true` と `24`）。 -- さらに OpenClaw は、復号失敗が繰り返された後に音声セッションを離脱/再参加することで、音声受信の回復も試みます。 -- `channels.discord.streaming` は正規のストリームモードキーです。従来の `streamMode` と boolean の `streaming` 値は自動移行されます。 -- `channels.discord.autoPresence` は、ランタイム可用性を bot の presence にマッピングします（healthy => online、degraded => idle、exhausted => dnd）。任意のステータステキスト上書きも可能です。 -- `channels.discord.dangerouslyAllowNameMatching` は、変更可能な name/tag マッチングを再有効化します（非常時用の互換モード）。 -- `channels.discord.execApprovals`: Discord ネイティブの exec 承認配信と承認者認可。 - - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。auto モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効化されます。 - - `approvers`: exec リクエストを承認できる Discord ユーザー ID。省略時は `commands.ownerAllowFrom` にフォールバックします。 - - `agentFilter`: 任意の agent ID 許可リスト。省略するとすべての agent の承認を転送します。 - - `sessionFilter`: 任意のセッションキーパターン（部分文字列または regex）。 - - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）は承認者 DM に送信し、`"channel"` は元の channel に送信し、`"both"` は両方に送信します。target に `"channel"` が含まれる場合、ボタンを使用できるのは解決済み承認者のみです。 +- 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 認可。 + - `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）。 + - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）は approver の DM に送信し、`"channel"` は元の channel に送信し、`"both"` は両方に送信します。target に `"channel"` が含まれる場合、ボタンを使用できるのは解決済み approver のみです。 - `cleanupAfterResolve`: `true` の場合、承認、拒否、またはタイムアウト後に承認 DM を削除します。 -**リアクション通知モード:** `off`（なし）、`own`（bot のメッセージ、デフォルト）、`all`（すべてのメッセージ）、`allowlist`（すべてのメッセージに対して `guilds..users` から）。 +**リアクション通知モード:** `off`（なし）、`own`（bot 自身のメッセージ、デフォルト）、`all`（すべてのメッセージ）、`allowlist`（すべてのメッセージに対して `guilds..users` から）。 ### Google Chat @@ -394,10 +394,10 @@ WhatsApp は Gateway の web channel（Baileys Web）経由で動作します。 ``` - サービスアカウント JSON: インライン（`serviceAccount`）またはファイルベース（`serviceAccountFile`）。 -- サービスアカウントの SecretRef（`serviceAccountRef`）もサポートされます。 +- サービスアカウント SecretRef（`serviceAccountRef`）もサポートされます。 - 環境変数フォールバック: `GOOGLE_CHAT_SERVICE_ACCOUNT` または `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 - 配信ターゲットには `spaces/` または `users/` を使用します。 -- `channels.googlechat.dangerouslyAllowNameMatching` は、変更可能なメール principal マッチングを再有効化します（非常時用の互換モード）。 +- `channels.googlechat.dangerouslyAllowNameMatching` は、変更可能な email principal マッチングを再有効化します（break-glass 互換モード）。 ### Slack @@ -464,30 +464,30 @@ 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 アカウントスナップショットは、`botTokenSource`、`botTokenStatus`、`appTokenStatus`、HTTP mode では `signingSecretStatus` など、認証情報ごとの source/status フィールドを公開します。`configured_unavailable` は、そのアカウントが SecretRef 経由で設定されているが、現在のコマンド/ランタイム経路では secret 値を解決できなかったことを意味します。 -- `configWrites: false` は、Slack 起点の設定書き込みをブロックします。 -- 任意の `channels.slack.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- `channels.slack.streaming.mode` は正規の Slack ストリームモードキーです。`channels.slack.streaming.nativeTransport` は Slack のネイティブストリーミング転送を制御します。従来の `streamMode`、boolean の `streaming`、`nativeStreaming` の値は自動移行されます。 +- **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:` を使用します。 **リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 -**スレッドセッション分離:** `thread.historyScope` はスレッド単位（デフォルト）または channel 共有です。`thread.inheritParent` は親 channel のトランスクリプトを新しいスレッドにコピーします。 +**スレッドセッション分離:** `thread.historyScope` はスレッド単位（デフォルト）または channel 共有です。`thread.inheritParent` は親 channel の transcript を新しいスレッドにコピーします。 -- Slack ネイティブストリーミングと、Slack の assistant スタイル「is typing...」スレッドステータスには、返信スレッドターゲットが必要です。トップレベル DM はデフォルトでスレッド外のままなので、スレッドスタイルのプレビューではなく `typingReaction` または通常配信を使います。 -- `typingReaction` は、返信の実行中に受信した Slack メッセージへ一時的なリアクションを追加し、完了時に削除します。`"hourglass_flowing_sand"` のような Slack 絵文字 shortcode を使用してください。 -- `channels.slack.execApprovals`: Slack ネイティブの exec 承認配信と承認者認可。スキーマは Discord と同じです: `enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack ユーザー ID）、`agentFilter`、`sessionFilter`、`target`（`"dm"`、`"channel"`、または `"both"`）。 +- 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"`）。 -| アクショングループ | デフォルト | 備考 | +| アクショングループ | デフォルト | メモ | | ------------------ | ---------- | ------------------------ | -| reactions | enabled | リアクト + リアクション一覧 | -| messages | enabled | 読み取り/送信/編集/削除 | -| pins | enabled | ピン留め/解除/一覧 | -| memberInfo | enabled | メンバー情報 | -| emojiList | enabled | カスタム絵文字一覧 | +| reactions | 有効 | リアクション + リアクション一覧 | +| messages | 有効 | 読み取り/送信/編集/削除 | +| pins | 有効 | ピン留め/解除/一覧 | +| memberInfo | 有効 | メンバー情報 | +| emojiList | 有効 | カスタム絵文字一覧 | ### Mattermost @@ -521,18 +521,20 @@ Mattermost は Plugin として提供されます: `openclaw plugins install @op } ``` -チャットモード: `oncall`（@-mention 時に応答、デフォルト）、`onmessage`（すべてのメッセージ）、`onchar`（トリガープレフィックスで始まるメッセージ）。 +チャットモード: `oncall`（@-mention で応答、デフォルト）、`onmessage`（すべてのメッセージ）、`onchar`（トリガープレフィックスで始まるメッセージ）。 Mattermost ネイティブコマンドが有効な場合: -- `commands.callbackPath` はフル URL ではなくパスである必要があります（例: `/api/channels/mattermost/command`）。 -- `commands.callbackUrl` は OpenClaw Gateway エンドポイントを指し、Mattermost サーバーから到達可能である必要があります。 -- ネイティブスラッシュコールバックは、スラッシュコマンド登録時に Mattermost が返すコマンド単位のトークンで認証されます。登録に失敗した場合、または有効化されたコマンドがない場合、OpenClaw はコールバックを `Unauthorized: invalid command token.` で拒否します。 -- 非公開/tailnet/internal のコールバックホストでは、Mattermost 側で `ServiceSettings.AllowedUntrustedInternalConnections` にコールバックホスト/ドメインを含める必要がある場合があります。フル URL ではなく、ホスト/ドメイン値を使用してください。 -- `channels.mattermost.configWrites`: Mattermost 起点の設定書き込みを許可または拒否します。 -- `channels.mattermost.requireMention`: channel で返信する前に `@mention` を必須にします。 +- `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 と一致する場合にデフォルトアカウント選択を上書きします。 +- 任意の `channels.mattermost.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 ### Signal @@ -555,13 +557,13 @@ Mattermost ネイティブコマンドが有効な場合: **リアクション通知モード:** `off`、`own`（デフォルト）、`all`、`allowlist`（`reactionAllowlist` から）。 -- `channels.signal.account`: channel の起動先を特定の Signal アカウント ID に固定します。 -- `channels.signal.configWrites`: Signal 起点の設定書き込みを許可または拒否します。 -- 任意の `channels.signal.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 +- `channels.signal.account`: channel の起動を特定の Signal アカウント ID に固定します。 +- `channels.signal.configWrites`: Signal から開始される設定書き込みを許可または拒否します。 +- 任意の `channels.signal.defaultAccount` は、設定済みアカウント id と一致する場合にデフォルトアカウント選択を上書きします。 ### BlueBubbles -BlueBubbles は推奨される iMessage 経路です（Plugin バック、`channels.bluebubbles` 配下で設定）。 +BlueBubbles は推奨される iMessage 経路です（Plugin ベースで、`channels.bluebubbles` 配下に設定します）。 ```json5 { @@ -576,10 +578,10 @@ BlueBubbles は推奨される iMessage 経路です（Plugin バック、`chann } ``` -- ここで扱うコアのキーパス: `channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 任意の `channels.bluebubbles.defaultAccount` は、設定済みアカウント ID と一致する場合にデフォルトアカウント選択を上書きします。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、BlueBubbles の会話を永続 ACP セッションにバインドできます。`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) に記載されています。 +- ここで扱うコアキーパス: `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) に記載されています。 ### iMessage @@ -607,15 +609,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 は厳格なホストキー検証を使うため、リレーホストのキーがすでに `~/.ssh/known_hosts` に存在している必要があります。 -- `channels.imessage.configWrites`: iMessage 起点の設定書き込みを許可または拒否します。 -- `type: "acp"` を持つトップレベルの `bindings[]` エントリは、iMessage の会話を永続 ACP セッションにバインドできます。`match.peer.id` には正規化済み handle または明示的な chat ターゲット（`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 セッションにバインドできます。`match.peer.id` には正規化された handle または明示的な chat target（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用します。共通のフィールド意味: [ACP Agents](/ja-JP/tools/acp-agents#channel-specific-settings)。 @@ -628,7 +630,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix は extension バックで、`channels.matrix` 配下で設定します。 +Matrix は extension ベースで、`channels.matrix` 配下に設定します。 ```json5 { @@ -658,25 +660,25 @@ Matrix は extension バックで、`channels.matrix` 配下で設定します } ``` -- トークン認証は `accessToken` を使用し、パスワード認証は `userId` + `password` を使用します。 -- `channels.matrix.proxy` は Matrix HTTP トラフィックを明示的な HTTP(S) proxy 経由にします。名前付きアカウントは `channels.matrix.accounts..proxy` で上書きできます。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` は private/internal な homeserver を許可します。`proxy` とこのネットワーク opt-in は独立した制御です。 +- 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 承認配信と承認者認可。 - - `enabled`: `true`、`false`、または `"auto"`（デフォルト）。auto モードでは、`approvers` または `commands.ownerAllowFrom` から承認者を解決できる場合に exec 承認が有効化されます。 - - `approvers`: exec リクエストを承認できる Matrix ユーザー ID（例: `@owner:example.org`）。 - - `agentFilter`: 任意の agent ID 許可リスト。省略するとすべての agent の承認を転送します。 - - `sessionFilter`: 任意のセッションキーパターン（部分文字列または regex）。 - - `target`: 承認プロンプトの送信先。`"dm"`（デフォルト）、`"channel"`（発信元 room）、または `"both"`。 +- `channels.matrix.autoJoin` のデフォルトは `off` であるため、招待された room と新しい DM 形式の招待は、`autoJoin: "allowlist"` と `autoJoinAllowlist` を設定するか、`autoJoin: "always"` を設定するまで無視されます。 +- `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"`。 - アカウントごとのオーバーライド: `channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` は、Matrix DM をどのようにセッションへグループ化するかを制御します: `per-user`（デフォルト）はルーティングされた peer 単位で共有し、`per-room` は各 DM room を分離します。 -- Matrix のステータス probe とライブディレクトリ参照は、ランタイムトラフィックと同じ proxy ポリシーを使います。 -- 完全な Matrix 設定、ターゲティングルール、セットアップ例は [Matrix](/ja-JP/channels/matrix) に記載されています。 +- `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) に記載されています。 ### Microsoft Teams -Microsoft Teams は extension バックで、`channels.msteams` 配下で設定します。 +Microsoft Teams は extension ベースで、`channels.msteams` 配下に設定します。 ```json5 { @@ -691,12 +693,12 @@ Microsoft Teams は extension バックで、`channels.msteams` 配下で設定 } ``` -- ここで扱うコアのキーパス: `channels.msteams`、`channels.msteams.configWrites`。 -- 完全な Teams 設定（資格情報、webhook、DM/グループポリシー、team/channel ごとのオーバーライド）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 +- ここで扱うコアキーパス: `channels.msteams`、`channels.msteams.configWrites`。 +- Teams の完全な設定（資格情報、webhook、DM/グループポリシー、team ごと/channel ごとのオーバーライド）は [Microsoft Teams](/ja-JP/channels/msteams) に記載されています。 ### IRC -IRC は extension バックで、`channels.irc` 配下で設定します。 +IRC は extension ベースで、`channels.irc` 配下に設定します。 ```json5 { @@ -717,13 +719,13 @@ 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`、`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） -channel ごとに複数のアカウントを実行できます（各アカウントは独自の `accountId` を持ちます）: +channel ごとに複数のアカウントを実行できます（それぞれに独自の `accountId` を持ちます）: ```json5 { @@ -744,28 +746,28 @@ channel ごとに複数のアカウントを実行できます（各アカウン } ``` -- `accountId` を省略した場合は `default` が使われます（CLI + ルーティング）。 -- 環境変数トークンは **default** アカウントにのみ適用されます。 -- ベース channel 設定は、アカウントごとに上書きしない限りすべてのアカウントに適用されます。 -- `bindings[].match.accountId` を使うと、各アカウントを異なる agent にルーティングできます。 -- 単一アカウントのトップレベル channel 設定のまま `openclaw channels add`（または channel オンボーディング）で非デフォルトアカウントを追加すると、OpenClaw はまずアカウントスコープのトップレベル単一アカウント値を channel のアカウントマップへ昇格させるため、元のアカウントはそのまま動作し続けます。ほとんどの channels ではそれらは `channels..accounts.default` に移動されますが、Matrix では既存の一致する named/default ターゲットを代わりに保持できます。 -- 既存の channel のみのバインディング（`accountId` なし）は引き続きデフォルトアカウントに一致します。アカウントスコープ付きバインディングは引き続き任意です。 -- `openclaw doctor --fix` も、アカウントスコープのトップレベル単一アカウント値をその channel 用に選ばれた昇格先アカウントへ移動することで、混在した形状を修復します。ほとんどの channels では `accounts.default` が使われますが、Matrix では既存の一致する named/default ターゲットを代わりに保持できます。 +- `accountId` が省略された場合は `default` が使用されます（CLI + routing）。 +- 環境変数 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 を代わりに保持できます。 ### その他の extension channels -多くの extension channels は `channels.` として設定され、専用の channel ページに記載されています（たとえば Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 +多くの extension channel は `channels.` として設定され、専用の channel ページに記載されています（たとえば Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 完全な channel 一覧は [Channels](/ja-JP/channels) を参照してください。 ### グループチャットの mention gating -グループメッセージでは、デフォルトで **メンション必須** です（メタデータメンションまたは安全な regex パターン）。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。 +グループメッセージはデフォルトで **mention 必須** です（メタデータ mention または安全な regex パターン）。WhatsApp、Telegram、Discord、Google Chat、iMessage のグループチャットに適用されます。 -**メンションの種類:** +**mention の種類:** -- **メタデータメンション**: ネイティブプラットフォームの @-mention。WhatsApp の self-chat mode では無視されます。 -- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` 内の安全な regex パターン。無効なパターンや安全でないネストされた繰り返しは無視されます。 -- mention gating は、検出可能な場合にのみ適用されます（ネイティブメンションまたは少なくとも 1 つのパターンがある場合）。 +- **メタデータ mention**: ネイティブプラットフォームの @-mention。WhatsApp の self-chat mode では無視されます。 +- **テキストパターン**: `agents.list[].groupChat.mentionPatterns` 内の安全な regex パターン。無効なパターンや安全でないネスト反復は無視されます。 +- mention gating は、検出が可能な場合にのみ適用されます（ネイティブ mention または少なくとも 1 つのパターンがある場合）。 ```json5 { @@ -778,7 +780,7 @@ channel ごとに複数のアカウントを実行できます（各アカウン } ``` -`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。channels は `channels..historyLimit`（またはアカウントごと）で上書きできます。無効にするには `0` を設定します。 +`messages.groupChat.historyLimit` はグローバルデフォルトを設定します。channels は `channels..historyLimit`（またはアカウントごと）で上書きできます。無効にするには `0` を設定してください。 #### DM 履歴制限 @@ -797,11 +799,11 @@ channel ごとに複数のアカウントを実行できます（各アカウン 解決順序: DM ごとのオーバーライド → provider デフォルト → 制限なし（すべて保持）。 -サポート対象: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 +対応: `telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### self-chat mode +#### Self-chat mode -自分の電話番号を `allowFrom` に含めると self-chat mode が有効になります（ネイティブ @-mention は無視し、テキストパターンのみに応答します）: +自分の電話番号を `allowFrom` に含めると self-chat mode が有効になります（ネイティブ @-mention を無視し、テキストパターンにのみ応答します）: ```json5 { @@ -827,16 +829,16 @@ channel ごとに複数のアカウントを実行できます（各アカウン ```json5 { commands: { - native: "auto", // supported の場合はネイティブコマンドを登録 - nativeSkills: "auto", // supported の場合はネイティブ skill コマンドを登録 - text: true, // チャットメッセージ内の /commands を解析 - bash: false, // ! を許可（alias: /bash） + 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) bashForegroundMs: 2000, - config: false, // /config を許可 - mcp: false, // /mcp を許可 - plugins: false, // /plugins を許可 - debug: false, // /debug を許可 - restart: true, // /restart + Gateway restart tool を許可 + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -849,29 +851,29 @@ channel ごとに複数のアカウントを実行できます（各アカウン } ``` - + -- このブロックはコマンドサーフェスを設定します。現在の組み込み + bundled コマンドカタログについては [スラッシュコマンド](/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 ページと [スラッシュコマンド](/ja-JP/tools/slash-commands) に記載されています。 -- テキストコマンドは、先頭が `/` の**単独メッセージ**である必要があります。 -- `native: "auto"` は Discord/Telegram でネイティブコマンドを有効にし、Slack では無効のままにします。 -- `nativeSkills: "auto"` は Discord/Telegram でネイティブ Skills コマンドを有効にし、Slack では無効のままにします。 -- channel ごとのオーバーライド: `channels.discord.commands.native`（bool または `"auto"`）。`false` を指定すると、以前登録されたコマンドをクリアします。 -- ネイティブ skill 登録は `channels..commands.nativeSkills` で provider ごとにオーバーライドできます。 +- このブロックはコマンドサーフェスを設定します。現在の 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` はホスト 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 サーバー設定用の `/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 専用コマンド/ツール用の明示的な owner 許可リストです。`allowFrom` とは別です。 -- `ownerDisplay: "hash"` は、system prompt 内の owner ID をハッシュ化します。ハッシュ化を制御するには `ownerDisplaySecret` を設定してください。 -- `allowFrom` は provider ごとです。設定されている場合、これが**唯一の**認可ソースになります（channel の allowlist/pairing と `useAccessGroups` は無視されます）。 +- `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 ポリシーをバイパスできるようにします。 -- コマンドドキュメントの対応表: - - 組み込み + bundled カタログ: [スラッシュコマンド](/ja-JP/tools/slash-commands) +- コマンドドキュメントの対応先: + - built-in + bundled カタログ: [Slash Commands](/ja-JP/tools/slash-commands) - channel 固有のコマンドサーフェス: [Channels](/ja-JP/channels) - QQ Bot コマンド: [QQ Bot](/ja-JP/channels/qqbot) - pairing コマンド: [Pairing](/ja-JP/channels/pairing) @@ -882,7 +884,7 @@ channel ごとに複数のアカウントを実行できます（各アカウン --- -## Agent のデフォルト設定 +## Agent のデフォルト ### `agents.defaults.workspace` @@ -906,7 +908,7 @@ system prompt の Runtime 行に表示される任意のリポジトリルート ### `agents.defaults.skills` -`agents.list[].skills` を設定していない agent 用の、任意のデフォルト Skills 許可リストです。 +`agents.list[].skills` を設定していない agent 向けの、任意のデフォルト Skills allowlist です。 ```json5 { @@ -938,9 +940,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 の再注入をスキップし、プロンプトサイズを削減します。Heartbeat 実行と Compaction 後の再試行では引き続きコンテキストが再構築されます。 +- `"continuation-skip"`: 安全な継続ターン（assistant の応答完了後）では workspace bootstrap の再注入をスキップし、prompt サイズを削減します。Heartbeat 実行と post-Compaction リトライでは引き続きコンテキストを再構築します。 ```json5 { @@ -950,32 +952,32 @@ workspace bootstrap ファイルを 언제 system prompt に注入するかを ### `agents.defaults.bootstrapMaxChars` -切り詰め前の、workspace bootstrap ファイルごとの最大文字数です。デフォルト: `20000`。 +切り詰め前の、workspace bootstrap ファイルごとの最大文字数。デフォルト: `12000`。 ```json5 { - agents: { defaults: { bootstrapMaxChars: 20000 } }, + agents: { defaults: { bootstrapMaxChars: 12000 } }, } ``` ### `agents.defaults.bootstrapTotalMaxChars` -すべての workspace bootstrap ファイルにまたがって注入される最大総文字数です。デフォルト: `150000`。 +すべての workspace bootstrap ファイルで注入される合計最大文字数。デフォルト: `60000`。 ```json5 { - agents: { defaults: { bootstrapTotalMaxChars: 150000 } }, + agents: { defaults: { bootstrapTotalMaxChars: 60000 } }, } ``` ### `agents.defaults.bootstrapPromptTruncationWarning` -bootstrap コンテキストが切り詰められたときに agent に見える警告テキストを制御します。 +bootstrap コンテキストが切り詰められたときの、agent に見える警告テキストを制御します。 デフォルト: `"once"`。 -- `"off"`: system prompt に警告テキストを一切注入しません。 +- `"off"`: 警告テキストを system prompt に一切注入しません。 - `"once"`: 一意の切り詰めシグネチャごとに 1 回だけ警告を注入します（推奨）。 -- `"always"`: 切り詰めが存在する場合、毎回の実行で警告を注入します。 +- `"always"`: 切り詰めが存在する場合は毎回警告を注入します。 ```json5 { @@ -985,29 +987,28 @@ bootstrap コンテキストが切り詰められたときに agent に見える ### コンテキスト予算の所有マップ -OpenClaw には大容量の prompt/context 予算が複数あり、それらは 1 つの汎用ノブにまとめず、サブシステムごとに意図的に分割されています。 +OpenClaw には複数の大容量 prompt/context 予算があり、それらは 1 つの汎用ノブにすべて流し込むのではなく、意図的にサブシステムごとに分割されています。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: 通常の workspace bootstrap 注入。 - `agents.defaults.startupContext.*`: - 1 回限りの `/new` と `/reset` の起動前奏コンテキスト。最近の - `memory/*.md` ファイルを含みます。 + 最近の daily `memory/*.md` ファイルを含む、単発の `/new` および `/reset` 起動プレリュード。 - `skills.limits.*`: system prompt に注入されるコンパクトな Skills 一覧。 - `agents.defaults.contextLimits.*`: - 制限付きランタイム抜粋と、注入されるランタイム所有ブロック。 + 制限付き runtime 抜粋と、runtime が所有する注入ブロック。 - `memory.qmd.limits.*`: - インデックス化された memory search スニペットと注入サイズ。 + インデックス化された memory-search スニペットと注入サイズ。 -特定の agent にのみ別の予算が必要な場合に限り、対応する agent ごとのオーバーライドを使用してください: +1 つの agent だけ異なる予算を必要とする場合にのみ、対応する agent ごとのオーバーライドを使用してください: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -素の `/new` と `/reset` 実行時に注入される、最初のターンの起動前奏コンテキストを制御します。 +素の `/new` および `/reset` 実行時に注入される最初のターンの起動プレリュードを制御します。 ```json5 { @@ -1028,7 +1029,7 @@ OpenClaw には大容量の prompt/context 予算が複数あり、それらは #### `agents.defaults.contextLimits` -制限付きランタイムコンテキストサーフェスの共有デフォルトです。 +制限付き runtime コンテキストサーフェスの共有デフォルトです。 ```json5 { @@ -1046,13 +1047,13 @@ OpenClaw には大容量の prompt/context 予算が複数あり、それらは ``` - `memoryGetMaxChars`: 切り詰めメタデータと継続通知が追加される前の、デフォルトの `memory_get` 抜粋上限。 -- `memoryGetDefaultLines`: `lines` を省略した場合の、デフォルトの `memory_get` 行ウィンドウ。 -- `toolResultMaxChars`: 永続化される結果とオーバーフロー回復に使われる、ライブ tool result 上限。 -- `postCompactionMaxChars`: Compaction 後の再注入時に使われる AGENTS.md 抜粋上限。 +- `memoryGetDefaultLines`: `lines` が省略された場合のデフォルトの `memory_get` 行ウィンドウ。 +- `toolResultMaxChars`: 永続化された結果とオーバーフロー回復に使用される、ライブ tool 結果の上限。 +- `postCompactionMaxChars`: post-Compaction の再注入時に使用される AGENTS.md 抜粋上限。 #### `agents.list[].contextLimits` -共有 `contextLimits` ノブの agent ごとのオーバーライドです。省略されたフィールドは `agents.defaults.contextLimits` から継承されます。 +共有 `contextLimits` ノブの agent ごとのオーバーライドです。省略されたフィールドは `agents.defaults.contextLimits` を継承します。 ```json5 { @@ -1079,7 +1080,7 @@ OpenClaw には大容量の prompt/context 予算が複数あり、それらは #### `skills.limits.maxSkillsPromptChars` system prompt に注入されるコンパクトな Skills 一覧のグローバル上限です。 -これは必要に応じて `SKILL.md` ファイルを読むことには影響しません。 +これはオンデマンドでの `SKILL.md` ファイル読み込みには影響しません。 ```json5 { @@ -1112,11 +1113,11 @@ Skills prompt 予算の agent ごとのオーバーライドです。 ### `agents.defaults.imageMaxDimensionPx` -provider 呼び出し前に、transcript/tool の画像ブロックで最長辺に適用される最大ピクセルサイズです。 +provider 呼び出し前に、transcript/tool の画像ブロックで最長辺に許可される最大ピクセルサイズです。 デフォルト: `1200`。 -通常、値を小さくするとスクリーンショットの多い実行で vision token 使用量とリクエスト payload サイズが減ります。 -値を大きくすると、より多くの視覚的詳細が保持されます。 +低い値では通常、スクリーンショットが多い実行時の vision-token 使用量とリクエスト payload サイズが減ります。 +高い値では、より多くの視覚的詳細が保持されます。 ```json5 { @@ -1126,7 +1127,7 @@ provider 呼び出し前に、transcript/tool の画像ブロックで最長辺 ### `agents.defaults.userTimezone` -system prompt コンテキスト用のタイムゾーンです（メッセージタイムスタンプ用ではありません）。未設定の場合はホストのタイムゾーンにフォールバックします。 +system prompt コンテキスト用のタイムゾーンです（メッセージタイムスタンプではありません）。ホストのタイムゾーンにフォールバックします。 ```json5 { @@ -1136,7 +1137,7 @@ system prompt コンテキスト用のタイムゾーンです（メッセージ ### `agents.defaults.timeFormat` -system prompt 内の時刻形式です。デフォルト: `auto`（OS の設定）。 +system prompt の時刻形式です。デフォルト: `auto`（OS 設定）。 ```json5 { @@ -1174,7 +1175,7 @@ system prompt 内の時刻形式です。デフォルト: `auto`（OS の設定 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // グローバルなデフォルト provider params + params: { cacheRetention: "long" }, // global default provider params embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1193,48 +1194,48 @@ system prompt 内の時刻形式です。デフォルト: `auto`（OS の設定 } ``` -- `model`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - 文字列形式はプライマリモデルのみを設定します。 - - オブジェクト形式は、プライマリに加えて順序付きのフェイルオーバーモデルを設定します。 -- `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 キーも設定してください（例: `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 }`）を受け付けます。 - - 共有の音楽生成機能と、組み込みの `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 キーも設定してください。 -- `videoGenerationModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - 共有の動画生成機能と、組み込みの `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 キーも設定してください。 - - bundled の Qwen 動画生成 provider は、最大 1 本の出力動画、1 枚の入力画像、4 本の入力動画、10 秒の長さ、および provider レベルの `size`、`aspectRatio`、`resolution`、`audio`、`watermark` オプションをサポートします。 -- `pdfModel`: 文字列（`"provider/model"`）またはオブジェクト（`{ primary, fallbacks }`）を受け付けます。 - - `pdf` tool で model ルーティングに使われます。 - - 省略した場合、PDF tool は `imageModel` にフォールバックし、その後、解決済みのセッション/デフォルト model にフォールバックします。 -- `pdfMaxBytesMb`: 呼び出し時に `maxBytesMb` が渡されない場合の、`pdf` tool のデフォルト PDF サイズ上限。 -- `pdfMaxPages`: `pdf` tool の抽出フォールバックモードで考慮されるページ数のデフォルト上限。 +- `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 の抽出フォールバックモードで考慮するデフォルト最大ページ数。 - `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 のデフォルトを出す代わりに、最初の設定済み provider/model にフォールバックします。 -- `models`: `/model` 用の設定済み model カタログ兼許可リスト。各エントリには `alias`（短縮名）と `params`（provider 固有。例: `temperature`、`maxTokens`、`cacheRetention`、`context1m`）を含められます。 -- `params`: すべての models に適用されるグローバルなデフォルト 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"` で組み込み PI harness を強制し、`runtime: "codex"` のような登録済み harness id も指定できます。自動 PI フォールバックを無効にするには `fallback: "none"` を設定します。 -- これらのフィールドを変更する設定ライター（たとえば `/models set`、`/models set-image`、fallback の追加/削除コマンド）は、正規のオブジェクト形式で保存し、可能な限り既存の fallback リストを保持します。 -- `maxConcurrent`: セッションをまたいで並列実行できる agent run の最大数です（各セッション自体は引き続き直列化されます）。デフォルト: 4。 +- `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。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` は、埋め込み agent ターンをどの低レベル executor で実行するかを制御します。 -ほとんどの環境では、デフォルトの `{ runtime: "auto", fallback: "pi" }` のままで構いません。 -bundled の Codex app-server harness のように、信頼できる plugin がネイティブ harness を提供する場合に使ってください。 +`embeddedHarness` は、どの低レベル executor が embedded agent turn を実行するかを制御します。 +ほとんどのデプロイでは、デフォルトの `{ runtime: "auto", fallback: "pi" }` のままで問題ありません。 +bundled Codex app-server harness のように、信頼できる plugin がネイティブ harness を提供する場合に使用してください。 ```json5 { @@ -1250,13 +1251,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 フォールバックを無効にします。 -- Codex 専用環境では、`model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"`、`embeddedHarness.fallback: "none"` を設定してください。 -- これは埋め込み chat harness のみを制御します。media generation、vision、PDF、music、video、TTS は引き続きそれぞれの provider/model 設定を使います。 +- `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 フォールバックを無効にします。 +- Codex 専用デプロイでは、`model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"`、`embeddedHarness.fallback: "none"` を設定してください。 +- これは embedded chat harness のみを制御します。メディア生成、vision、PDF、音楽、動画、TTS は引き続きそれぞれの provider/model 設定を使用します。 -**組み込み alias 短縮名**（model が `agents.defaults.models` にある場合のみ適用）: +**組み込み alias ショートハンド**（model が `agents.defaults.models` にある場合のみ適用）: | Alias | Model | | ------------------- | -------------------------------------- | @@ -1269,15 +1270,15 @@ bundled の Codex app-server harness のように、信頼できる plugin が | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -設定済みの alias は常にデフォルトより優先されます。 +設定した alias は常にデフォルトより優先されます。 -Z.AI の GLM-4.x models は、`--thinking off` を設定するか、`agents.defaults.models["zai/"].params.thinking` を自分で定義しない限り、自動的に thinking mode を有効にします。 -Z.AI models は、tool call ストリーミングのためにデフォルトで `tool_stream` を有効にします。無効にするには `agents.defaults.models["zai/"].params.tool_stream` を `false` に設定してください。 -Anthropic Claude 4.6 models は、明示的な thinking レベルが設定されていない場合、デフォルトで `adaptive` thinking を使用します。 +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` に設定してください。 +Anthropic Claude 4.6 model は、明示的な thinking レベルが設定されていない場合、デフォルトで `adaptive` thinking を使用します。 ### `agents.defaults.cliBackends` -テキスト専用のフォールバック実行用の任意の CLI バックエンドです（tool call なし）。API provider が失敗したときのバックアップとして役立ちます。 +テキスト専用のフォールバック実行用の任意 CLI backend です（tool 呼び出しなし）。API provider が失敗したときのバックアップとして便利です。 ```json5 { @@ -1305,13 +1306,13 @@ Anthropic Claude 4.6 models は、明示的な thinking レベルが設定され } ``` -- CLI バックエンドはテキスト優先です。tools は常に無効です。 -- `sessionArg` が設定されている場合はセッションをサポートします。 -- `imageArg` がファイルパスを受け付ける場合は画像パススルーをサポートします。 +- CLI backend は text-first です。tools は常に無効です。 +- `sessionArg` が設定されている場合は session がサポートされます。 +- `imageArg` がファイルパスを受け付ける場合は画像パススルーがサポートされます。 ### `agents.defaults.systemPromptOverride` -OpenClaw が組み立てた system prompt 全体を固定文字列で置き換えます。デフォルトレベル（`agents.defaults.systemPromptOverride`）または agent ごと（`agents.list[].systemPromptOverride`）で設定します。agent ごとの値が優先されます。空または空白のみの値は無視されます。制御された prompt 実験に役立ちます。 +OpenClaw が組み立てた system prompt 全体を固定文字列で置き換えます。デフォルトレベル（`agents.defaults.systemPromptOverride`）または agent ごと（`agents.list[].systemPromptOverride`）に設定します。agent ごとの値が優先されます。空文字または空白のみの値は無視されます。制御された prompt 実験に便利です。 ```json5 { @@ -1352,15 +1353,15 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 } ``` -- `every`: 期間文字列（ms/s/m/h）。デフォルト: `30m`（API-key auth）または `1h`（OAuth auth）。無効にするには `0m` を設定します。 +- `every`: 期間文字列（ms/s/m/h）。デフォルト: `30m`（API キー認証）または `1h`（OAuth 認証）。無効にするには `0m` を設定します。 - `includeSystemPromptSection`: false の場合、system prompt から Heartbeat セクションを省略し、bootstrap コンテキストへの `HEARTBEAT.md` 注入もスキップします。デフォルト: `true`。 -- `suppressToolErrorWarnings`: true の場合、Heartbeat 実行中の tool error 警告 payload を抑制します。 -- `timeoutSeconds`: 中断されるまでに Heartbeat agent ターンに許可される最大秒数。未設定の場合は `agents.defaults.timeoutSeconds` を使います。 +- `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 は以前の会話履歴がない新しいセッションで実行されます。Cron の `sessionTarget: "isolated"` と同じ分離パターンです。Heartbeat あたりの token コストを約 100K から約 2〜5K token に削減します。 -- agent ごと: `agents.list[].heartbeat` を設定します。いずれかの agent が `heartbeat` を定義している場合、Heartbeat を実行するのは**その agent だけ**です。 -- Heartbeat は完全な agent ターンを実行するため、間隔を短くするとより多くの token を消費します。 +- `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 消費が増えます。 ### `agents.defaults.compaction` @@ -1370,19 +1371,19 @@ OpenClaw が組み立てた system prompt 全体を固定文字列で置き換 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 登録済み Compaction provider Plugin の id（任意） + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "デプロイ ID、チケット ID、host:port の組み合わせを正確に保持してください。", // identifierPolicy=custom のときに使用 - postCompactionSections: ["Session Startup", "Red Lines"], // [] で再注入を無効化 - model: "openrouter/anthropic/claude-sonnet-4-6", // Compaction 専用の model オーバーライド（任意） - notifyUser: true, // Compaction 開始時に簡単な通知を送信（デフォルト: false） + 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) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "セッションはまもなく Compaction に入ります。永続的な記憶を今すぐ保存してください。", - prompt: "持続的に残すべきメモがあれば memory/YYYY-MM-DD.md に書き込んでください。保存するものがなければ、正確なサイレントトークン NO_REPLY で応答してください。", + systemPrompt: "Session nearing compaction. Store durable memories now.", + prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, @@ -1390,19 +1391,19 @@ 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`: OpenClaw が中断するまでに、1 回の Compaction 操作に許可される最大秒数。デフォルト: `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 はセッションのプライマリ model を使います。 -- `notifyUser`: `true` の場合、Compaction 開始時にユーザーへ短い通知を送ります（例: 「コンテキストを Compaction 中...」）。デフォルトでは、Compaction をサイレントに保つため無効です。 -- `memoryFlush`: 自動 Compaction 前に永続メモリを保存するサイレントな agent ターンです。workspace が読み取り専用の場合はスキップされます。 +- `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 が読み取り専用の場合はスキップされます。 ### `agents.defaults.contextPruning` -LLM に送信する前に、メモリ内コンテキストから**古い tool result** を削減します。ディスク上のセッション履歴は**変更しません**。 +LLM に送信する前に、メモリ内コンテキストから**古い tool 結果**を剪定します。ディスク上のセッション履歴は**変更しません**。 ```json5 { @@ -1416,7 +1417,7 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool re hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[古い tool result の内容は削除されました]" }, + hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1426,19 +1427,19 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool re -- `mode: "cache-ttl"` は pruning パスを有効にします。 -- `ttl` は、最後のキャッシュ更新後に pruning を再実行できる頻度を制御します。 -- pruning は、まず大きすぎる tool result をソフトトリムし、その後必要に応じて古い tool result を完全クリアします。 +- `mode: "cache-ttl"` は剪定パスを有効にします。 +- `ttl` は、最後のキャッシュタッチ後に、いつ再び剪定を実行できるかを制御します。 +- 剪定はまず大きすぎる tool 結果をソフトトリムし、必要ならさらに古い tool 結果をハードクリアします。 -**soft-trim** は先頭と末尾を保持し、中間に `...` を挿入します。 +**ソフトトリム**は先頭と末尾を保持し、中間に `...` を挿入します。 -**hard-clear** は tool result 全体をプレースホルダーに置き換えます。 +**ハードクリア**は tool 結果全体をプレースホルダーに置き換えます。 注意: -- 画像ブロックは切り詰め/クリアされません。 -- 比率は文字数ベース（概算）であり、正確な token 数ではありません。 -- assistant メッセージが `keepLastAssistants` 未満の場合、pruning はスキップされます。 +- 画像ブロックは切り詰めもクリアもされません。 +- 比率はトークン数の厳密値ではなく、文字数ベースの概算です。 +- `keepLastAssistants` 個未満の assistant メッセージしか存在しない場合、剪定はスキップされます。 @@ -1460,13 +1461,13 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool re } ``` -- 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`。 +- `humanDelay`: ブロック返信間のランダムな待機。`natural` = 800–2500ms。agent ごとのオーバーライド: `agents.list[].humanDelay`。 動作とチャンク化の詳細は [Streaming](/ja-JP/concepts/streaming) を参照してください。 -### タイピングインジケーター +### Typing indicators ```json5 { @@ -1479,7 +1480,7 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool re } ``` -- デフォルト: ダイレクトチャット/メンションでは `instant`、メンションされていないグループチャットでは `message`。 +- デフォルト: ダイレクトチャット/mention では `instant`、mention されていないグループチャットでは `message`。 - セッションごとのオーバーライド: `session.typingMode`、`session.typingIntervalSeconds`。 [Typing Indicators](/ja-JP/concepts/typing-indicators) を参照してください。 @@ -1488,7 +1489,7 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool re ### `agents.defaults.sandbox` -埋め込み agent 用の任意の sandbox 化です。完全なガイドは [Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。 +embedded agent 用の任意の sandbox 化です。完全なガイドは [Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。 ```json5 { @@ -1534,7 +1535,7 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool re identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRef / インライン内容もサポート: + // SecretRefs / inline contents also supported: // 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" }, @@ -1583,48 +1584,48 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool re } ``` - + -**バックエンド:** +**Backend:** -- `docker`: ローカル Docker ランタイム（デフォルト） -- `ssh`: 汎用 SSH バックのリモートランタイム -- `openshell`: OpenShell ランタイム +- `docker`: ローカル Docker runtime（デフォルト） +- `ssh`: 汎用 SSH ベースのリモート runtime +- `openshell`: OpenShell runtime -`backend: "openshell"` を選択した場合、ランタイム固有の設定は -`plugins.entries.openshell.config` に移ります。 +`backend: "openshell"` を選択した場合、runtime 固有の設定は +`plugins.entries.openshell.config` に移動します。 -**SSH バックエンド設定:** +**SSH backend 設定:** - `target`: `user@host[:port]` 形式の SSH ターゲット - `command`: SSH クライアントコマンド（デフォルト: `ssh`） -- `workspaceRoot`: スコープごとの workspace に使う絶対リモートルート +- `workspaceRoot`: スコープごとの workspace に使用する絶対リモートルート - `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSH に渡される既存のローカルファイル -- `identityData` / `certificateData` / `knownHostsData`: OpenClaw がランタイム時に一時ファイルへ実体化するインライン内容または SecretRef -- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH のホストキー方針ノブ +- `identityData` / `certificateData` / `knownHostsData`: runtime 時に OpenClaw が一時ファイルへ実体化するインライン内容または SecretRef +- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH の host-key ポリシーノブ **SSH 認証の優先順位:** - `identityData` は `identityFile` より優先 - `certificateData` は `certificateFile` より優先 - `knownHostsData` は `knownHostsFile` より優先 -- SecretRef バックの `*Data` 値は、sandbox セッション開始前にアクティブな secrets ランタイムスナップショットから解決されます +- SecretRef ベースの `*Data` 値は、sandbox セッション開始前にアクティブな secrets runtime snapshot から解決されます -**SSH バックエンドの動作:** +**SSH backend の動作:** -- 作成または再作成後に、リモート workspace を 1 回だけシードします -- その後はリモート SSH workspace を正規の状態として維持します -- `exec`、ファイル tools、media パスを SSH 経由でルーティングします -- リモート変更は自動ではホストへ同期されません +- 作成または再作成後にリモート workspace を 1 回シードします +- その後はリモート SSH workspace を正本として維持します +- `exec`、ファイル tools、メディアパスを SSH 経由でルーティングします +- リモート変更を自動的にホストへ同期しません - sandbox browser コンテナはサポートしません -**workspace アクセス:** +**Workspace アクセス:** - `none`: `~/.openclaw/sandboxes` 配下のスコープごとの sandbox workspace -- `ro`: `/workspace` に sandbox workspace、`/agent` に agent workspace を読み取り専用でマウント -- `rw`: agent workspace を `/workspace` に読み書き可能でマウント +- `ro`: `/workspace` の sandbox workspace と、`/agent` に読み取り専用でマウントされた agent workspace +- `rw`: `/workspace` に読み書きでマウントされた agent workspace -**スコープ:** +**Scope:** - `session`: セッションごとのコンテナ + workspace - `agent`: agent ごとに 1 つのコンテナ + workspace（デフォルト） @@ -1658,32 +1659,31 @@ LLM に送信する前に、メモリ内コンテキストから**古い tool re **OpenShell モード:** -- `mirror`: 実行前にローカルからリモートへシードし、実行後に同期し戻します。ローカル workspace が正規状態のまま維持されます -- `remote`: sandbox 作成時に 1 回だけリモートをシードし、その後はリモート workspace を正規状態として維持します +- `mirror`: 実行前にローカルからリモートへシードし、実行後に同期を戻します。ローカル workspace が正本のままです +- `remote`: sandbox 作成時に 1 回だけリモートへシードし、その後はリモート workspace を正本として維持します -`remote` モードでは、シード後に OpenClaw 外で行われたホストローカル編集は、自動では sandbox に同期されません。 -転送は OpenShell sandbox への SSH ですが、sandbox のライフサイクルと任意の mirror 同期は Plugin が管理します。 +`remote` モードでは、OpenClaw の外で行われたホストローカル編集は、シード後に自動では sandbox に同期されません。 +転送は OpenShell sandbox への SSH ですが、sandbox のライフサイクルと任意の mirror 同期は Plugin が所有します。 **`setupCommand`** はコンテナ作成後に 1 回だけ実行されます（`sh -lc` 経由）。ネットワーク外向き通信、書き込み可能なルート、root ユーザーが必要です。 -**コンテナのデフォルトは `network: "none"`** です。agent に外向きアクセスが必要な場合は `"bridge"`（またはカスタム bridge network）に設定してください。 -`"host"` はブロックされます。`"container:"` は、明示的に -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` を設定しない限り（非常時用）デフォルトでブロックされます。 +**コンテナのデフォルトは `network: "none"`** です — agent が外向きアクセスを必要とする場合は `"bridge"`（またはカスタム bridge network）に設定してください。 +`"host"` はブロックされます。`"container:"` も、`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` を明示的に設定しない限り（break-glass）、デフォルトでブロックされます。 -**受信添付ファイル** は、アクティブな workspace の `media/inbound/*` にステージされます。 +**受信添付ファイル** は、アクティブ workspace 内の `media/inbound/*` にステージされます。 -**`docker.binds`** は追加のホストディレクトリをマウントします。グローバルと agent ごとの binds はマージされます。 +**`docker.binds`** は追加のホストディレクトリをマウントします。グローバルと agent ごとの bind はマージされます。 -**sandbox 化された browser**（`sandbox.browser.enabled`）: コンテナ内の Chromium + CDP。noVNC URL は system prompt に注入されます。`openclaw.json` で `browser.enabled` は不要です。 -noVNC の閲覧専用アクセスはデフォルトで VNC 認証を使用し、OpenClaw は共有 URL にパスワードを露出させる代わりに短命トークン URL を発行します。 +**Sandbox 化された browser**（`sandbox.browser.enabled`）: コンテナ内の Chromium + CDP。noVNC URL は system prompt に注入されます。`openclaw.json` で `browser.enabled` を必要としません。 +noVNC の observer アクセスはデフォルトで VNC 認証を使用し、OpenClaw は共有 URL に password を露出する代わりに短命 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` で定義され、コンテナホスト向けに調整されています: +- `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` で定義されており、コンテナホスト向けに調整されています: - `--remote-debugging-address=127.0.0.1` - - `--remote-debugging-port=` + - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` @@ -1700,25 +1700,26 @@ noVNC の閲覧専用アクセスはデフォルトで VNC 認証を使用し、 - `--metrics-recording-only` - `--disable-extensions`（デフォルトで有効） - `--disable-3d-apis`、`--disable-software-rasterizer`、`--disable-gpu` は - デフォルトで有効であり、WebGL/3D の使用で必要な場合は - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` で無効化できます。 - - ワークフローで extensions が必要な場合は - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` で再有効化できます。 + デフォルトで有効であり、WebGL/3D 利用で必要な場合は + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` で無効にできます。 + - ワークフローが extension に依存する場合は、 + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` で extension を再有効化できます。 - `--renderer-process-limit=2` は `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` で変更できます。Chromium の - デフォルトプロセス上限を使うには `0` を設定してください。 + デフォルトの process 上限を使用するには `0` を設定してください。 - さらに、`noSandbox` が有効な場合は `--no-sandbox` と `--disable-setuid-sandbox`。 - - これらのデフォルトはコンテナイメージのベースラインです。コンテナのデフォルトを変更するには、カスタム entrypoint を持つカスタム browser イメージを使用してください。 + - デフォルトはコンテナ image のベースラインです。コンテナデフォルトを変更するには、 + カスタム browser image とカスタム entrypoint を使用してください。 -browser sandbox 化と `sandbox.docker.binds` は Docker 専用です。 +browser sandboxing と `sandbox.docker.binds` は Docker 専用です。 -イメージをビルド: +image をビルド: ```bash -scripts/sandbox-setup.sh # メイン sandbox イメージ -scripts/sandbox-browser-setup.sh # 任意の browser イメージ +scripts/sandbox-setup.sh # main sandbox image +scripts/sandbox-browser-setup.sh # optional browser image ``` ### `agents.list`（agent ごとのオーバーライド） @@ -1733,13 +1734,13 @@ scripts/sandbox-browser-setup.sh # 任意の browser イメージ name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // または { primary, fallbacks } - thinkingDefault: "high", // agent ごとの thinking レベル上書き - reasoningDefault: "on", // agent ごとの reasoning 可視性上書き - fastModeDefault: false, // agent ごとの fast mode 上書き + 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 embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 一致する defaults.models params をキーごとに上書き - skills: ["docs-search"], // 設定時は agents.defaults.skills を置き換え + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -1771,24 +1772,24 @@ scripts/sandbox-browser-setup.sh # 任意の browser イメージ ``` - `id`: 安定した agent id（必須）。 -- `default`: 複数設定されている場合は最初のものが優先されます（警告を記録）。どれも設定されていない場合は、リストの最初のエントリがデフォルトです。 -- `model`: 文字列形式は `primary` のみを上書きし、オブジェクト形式 `{ primary, fallbacks }` は両方を上書きします（`[]` はグローバル fallbacks を無効化）。`primary` のみを上書きする Cron ジョブは、`fallbacks: []` を設定しない限りデフォルトの fallbacks を引き続き継承します。 -- `params`: `agents.defaults.models` の選択された model エントリにマージされる agent ごとの stream params。model カタログ全体を複製せずに、`cacheRetention`、`temperature`、`maxTokens` などの agent 固有オーバーライドに使います。 -- `skills`: 任意の agent ごとの Skills 許可リスト。省略した場合、その agent は `agents.defaults.skills` が設定されていればそれを継承します。明示的なリストはデフォルトとマージせず置き換え、`[]` は Skills なしを意味します。 -- `thinkingDefault`: 任意の agent ごとのデフォルト thinking レベル（`off | minimal | low | medium | high | xhigh | adaptive`）。メッセージごとまたはセッションごとの上書きがない場合、この agent では `agents.defaults.thinkingDefault` を上書きします。 -- `reasoningDefault`: 任意の agent ごとのデフォルト reasoning 可視性（`on | off | stream`）。メッセージごとまたはセッションごとの reasoning 上書きがない場合に適用されます。 -- `fastModeDefault`: 任意の agent ごとの fast mode デフォルト（`true | false`）。メッセージごとまたはセッションごとの fast-mode 上書きがない場合に適用されます。 -- `embeddedHarness`: 任意の agent ごとの低レベル harness ポリシー上書き。ある 1 つの agent だけを Codex 専用にし、他の agents はデフォルトの PI フォールバックを維持するには `{ runtime: "codex", fallback: "none" }` を使います。 -- `runtime`: 任意の agent ごとのランタイム記述子。agent をデフォルトで ACP harness セッションにしたい場合は、`type: "acp"` と `runtime.acp` のデフォルト（`agent`、`backend`、`mode`、`cwd`）を使います。 +- `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`）を使います。 - `identity.avatar`: workspace 相対パス、`http(s)` URL、または `data:` URI。 -- `identity` はデフォルト値を導出します: `emoji` から `ackReaction`、`name`/`emoji` から `mentionPatterns`。 -- `subagents.allowAgents`: `sessions_spawn` 用の agent id 許可リスト（`["*"]` = 任意、デフォルト: 同じ agent のみ）。 -- sandbox 継承ガード: 要求元セッションが sandbox 化されている場合、`sessions_spawn` は sandbox なしで実行されるターゲットを拒否します。 -- `subagents.requireAgentId`: true の場合、`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制。デフォルト: false）。 +- `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）。 --- -## マルチ agent ルーティング +## マルチエージェントルーティング 1 つの Gateway 内で複数の分離された agent を実行します。[Multi-Agent](/ja-JP/concepts/multi-agent) を参照してください。 @@ -1807,27 +1808,27 @@ scripts/sandbox-browser-setup.sh # 任意の browser イメージ } ``` -### バインディング一致フィールド +### Binding の match フィールド -- `type`（任意）: 通常のルーティングには `route`（type 省略時も route）、永続 ACP 会話バインディングには `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 順序:** 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 各 tier 内では、最初に一致した `bindings` エントリが優先されます。 -`type: "acp"` エントリについては、OpenClaw は正確な会話 ID（`match.channel` + account + `match.peer.id`）で解決し、上記の route バインディング tier 順序は使用しません。 +`type: "acp"` エントリでは、OpenClaw は正確な会話 ID（`match.channel` + account + `match.peer.id`）で解決し、上記の route binding tier 順序は使用しません。 ### agent ごとのアクセスプロファイル @@ -1950,22 +1951,22 @@ scripts/sandbox-browser-setup.sh # 任意の browser イメージ }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // この token 数を超える親スレッド fork はスキップ（0 で無効） + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration または false - maxDiskBytes: "500mb", // 任意のハード予算 - highWaterBytes: "400mb", // 任意のクリーンアップ目標 + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // 非アクティブ時の自動 unfocus のデフォルト時間（`0` で無効） - maxAgeHours: 0, // ハード最大経過時間のデフォルト時間（`0` で無効） + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // legacy（ランタイムは常に "main" を使用） + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1975,37 +1976,37 @@ scripts/sandbox-browser-setup.sh # 任意の browser イメージ } ``` - + -- **`scope`**: グループチャット文脈における基本の session グループ化戦略。 - - `per-sender`（デフォルト）: channel 文脈内で、各送信者ごとに分離された session を使います。 +- **`scope`**: グループチャット文脈向けの基本 session グループ化戦略。 + - `per-sender`（デフォルト）: channel 文脈内で、各送信者ごとに分離された session を使用します。 - `global`: channel 文脈内のすべての参加者が 1 つの session を共有します（共有コンテキストを意図する場合にのみ使用してください）。 - **`dmScope`**: DM のグループ化方法。 - - `main`: すべての DM がメイン session を共有します。 - - `per-peer`: channels をまたいで送信者 id ごとに分離します。 - - `per-channel-peer`: channel + 送信者ごとに分離します（マルチユーザー受信箱に推奨）。 + - `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`**: 基本のリセットポリシー。`daily` はローカル時刻の `atHour` にリセットし、`idle` は `idleMinutes` 後にリセットします。両方が設定されている場合、先に期限を迎えた方が優先されます。 -- **`resetByType`**: タイプごとのオーバーライド（`direct`、`group`、`thread`）。従来の `dm` も `direct` の alias として受け付けます。 -- **`parentForkMaxTokens`**: fork されたスレッド session を作成するときに許可される親 session の `totalTokens` 上限（デフォルト `100000`）。 - - 親の `totalTokens` がこの値を超える場合、OpenClaw は親 transcript 履歴を継承せず、新しいスレッド session を開始します。 +- **`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 を開始します。 - このガードを無効にして常に親 fork を許可するには `0` を設定します。 -- **`mainKey`**: legacy フィールドです。ランタイムはメインのダイレクトチャットバケットに常に `"main"` を使います。 -- **`agentToAgent.maxPingPongTurns`**: agent 間のやり取り中に許可される agent 間の返信往復ターン数の上限（整数、範囲: `0`–`5`）。`0` は ping-pong 連鎖を無効にします。 -- **`sendPolicy`**: `channel`、`chatType`（`direct|group|channel`、従来の `dm` alias あり）、`keyPrefix`、または `rawKeyPrefix` で一致させます。最初の deny が優先されます。 +- **`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`: 古いエントリの期限切れまでの期間（デフォルト `30d`）。 + - `mode`: `warn` は警告のみ出力し、`enforce` はクリーンアップを適用します。 + - `pruneAfter`: 古いエントリの期限 cutoff（デフォルト `30d`）。 - `maxEntries`: `sessions.json` 内の最大エントリ数（デフォルト `500`）。 - `rotateBytes`: `sessions.json` がこのサイズを超えたらローテーションします（デフォルト `10mb`）。 - - `resetArchiveRetention`: `*.reset.` transcript アーカイブの保持期間。デフォルトでは `pruneAfter` を使います。無効にするには `false` を設定します。 - - `maxDiskBytes`: 任意の sessions ディレクトリのディスク予算。`warn` モードでは警告を記録し、`enforce` モードでは最も古い成果物/session から削除します。 + - `resetArchiveRetention`: `*.reset.` transcript アーカイブの保持期間。デフォルトは `pruneAfter`。無効にするには `false` を設定します。 + - `maxDiskBytes`: 任意の sessions ディレクトリのディスク予算。`warn` モードでは警告をログ出力し、`enforce` モードでは最も古い artifact/session から削除します。 - `highWaterBytes`: 予算クリーンアップ後の任意の目標値。デフォルトは `maxDiskBytes` の `80%` です。 -- **`threadBindings`**: スレッドバインド session 機能のグローバルデフォルト。 +- **`threadBindings`**: thread-bound session 機能のグローバルデフォルト。 - `enabled`: マスターのデフォルトスイッチ（provider ごとに上書き可能。Discord は `channels.discord.threadBindings.enabled` を使用） - - `idleHours`: 非アクティブ時の自動 unfocus のデフォルト時間数（`0` で無効。provider ごとに上書き可能） - - `maxAgeHours`: ハード最大経過時間のデフォルト時間数（`0` で無効。provider ごとに上書き可能） + - `idleHours`: 非アクティブ時の自動 unfocus を時間単位で指定するデフォルト（`0` で無効。provider ごとに上書き可能） + - `maxAgeHours`: ハードな最大経過時間を時間単位で指定するデフォルト（`0` で無効。provider ごとに上書き可能） @@ -2016,7 +2017,7 @@ scripts/sandbox-browser-setup.sh # 任意の browser イメージ ```json5 { messages: { - responsePrefix: "🦞", // または "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -2031,7 +2032,7 @@ scripts/sandbox-browser-setup.sh # 任意の browser イメージ }, }, inbound: { - debounceMs: 2000, // 0 で無効 + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -2041,7 +2042,7 @@ scripts/sandbox-browser-setup.sh # 任意の browser イメージ } ``` -### 応答プレフィックス +### レスポンスプレフィックス channel/account ごとのオーバーライド: `channels..responsePrefix`、`channels..accounts..responsePrefix`。 @@ -2049,30 +2050,30 @@ channel/account ごとのオーバーライド: `channels..responsePref **テンプレート変数:** -| 変数 | 説明 | 例 | -| ----------------- | -------------------- | --------------------------- | -| `{model}` | 短い model 名 | `claude-opus-4-6` | -| `{modelFull}` | 完全な model 識別子 | `anthropic/claude-opus-4-6` | -| `{provider}` | provider 名 | `anthropic` | +| 変数 | 説明 | 例 | +| ----------------- | ---------------------- | --------------------------- | +| `{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"` と同じ） | +| `{identity.name}` | agent identity 名 | （`"auto"` と同じ） | 変数は大文字小文字を区別しません。`{think}` は `{thinkingLevel}` の alias です。 -### 確認リアクション +### Ack reaction -- デフォルトはアクティブな agent の `identity.emoji`、それ以外は `"👀"` です。無効にするには `""` を設定します。 +- デフォルトはアクティブ agent の `identity.emoji`、それ以外は `"👀"` です。無効にするには `""` を設定します。 - channel ごとのオーバーライド: `channels..ackReaction`、`channels..accounts..ackReaction`。 - 解決順序: account → channel → `messages.ackReaction` → identity フォールバック。 - スコープ: `group-mentions`（デフォルト）、`group-all`、`direct`、`all`。 - `removeAckAfterReply`: Slack、Discord、Telegram で返信後に ack を削除します。 -- `messages.statusReactions.enabled`: Slack、Discord、Telegram でライフサイクル status リアクションを有効にします。 - Slack と Discord では、未設定の場合、ack リアクションが有効なら status リアクションも有効のままになります。 - Telegram では、ライフサイクル status リアクションを有効にするには明示的に `true` を設定してください。 +- `messages.statusReactions.enabled`: Slack、Discord、Telegram でライフサイクル status reaction を有効にします。 + Slack と Discord では、未設定の場合、ack reaction が有効なら status reaction も有効のままになります。 + Telegram では、ライフサイクル status reaction を有効にするには明示的に `true` を設定してください。 ### 受信 debounce -同じ送信者からの連続するテキストのみのメッセージを 1 回の agent ターンにまとめます。media/添付ファイルは即時フラッシュされます。制御コマンドは debouncing をバイパスします。 +同じ送信者からの短時間のテキストのみのメッセージを、1 回の agent turn にまとめます。media/attachments は即座に flush されます。制御コマンドは debouncing をバイパスします。 ### TTS（text-to-speech） @@ -2115,18 +2116,18 @@ channel/account ごとのオーバーライド: `channels..responsePref } ``` -- `auto` はデフォルトの自動 TTS モードを制御します: `off`、`always`、`inbound`、または `tagged`。`/tts on|off` でローカル設定を上書きでき、`/tts status` で実効状態を確認できます。 -- `summaryModel` は、自動要約に対して `agents.defaults.model.primary` を上書きします。 +- `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 エンドポイントを上書きします。解決順序は、設定、次に `OPENAI_TTS_BASE_URL`、最後に `https://api.openai.com/v1` です。 -- `openai.baseUrl` が OpenAI 以外のエンドポイントを指している場合、OpenClaw はそれを OpenAI 互換 TTS サーバーとして扱い、model/voice 検証を緩和します。 +- `openai.baseUrl` は OpenAI TTS エンドポイントを上書きします。解決順序は config、その次に `OPENAI_TTS_BASE_URL`、その次に `https://api.openai.com/v1` です。 +- `openai.baseUrl` が OpenAI 以外のエンドポイントを指している場合、OpenClaw はそれを OpenAI 互換 TTS サーバーとして扱い、model/voice の検証を緩和します。 --- ## Talk -Talk mode（macOS/iOS/Android）のデフォルト設定です。 +Talk mode（macOS/iOS/Android）のデフォルトです。 ```json5 { @@ -2150,51 +2151,51 @@ Talk mode（macOS/iOS/Android）のデフォルト設定です。 } ``` -- `talk.provider` は、複数の Talk provider が設定されている場合、`talk.providers` 内のキーと一致している必要があります。 -- 従来のフラットな Talk キー（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）は互換性専用であり、`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` は、Talk mode がユーザーの無音後に transcript を送信するまで待機する時間を制御します。未設定の場合はプラットフォームのデフォルト待機時間が使われます（`macOS と Android では 700 ms、iOS では 900 ms`）。 +- `providers.*.apiKey` は平文文字列または SecretRef オブジェクトを受け付けます。 +- `ELEVENLABS_API_KEY` のフォールバックは、Talk API キーが設定されていない場合にのみ適用されます。 +- `providers.*.voiceAliases` により、Talk ディレクティブでフレンドリー名を使用できます。 +- `silenceTimeoutMs` は、ユーザーが無言になってから transcript を送信するまで Talk mode が待機する時間を制御します。未設定の場合はプラットフォームのデフォルトの待機時間を使用します（`macOS と Android では 700 ms、iOS では 900 ms`）。 --- ## Tools -### Tool プロファイル +### Tool profile -`tools.profile` は、`tools.allow`/`tools.deny` の前に基本 allowlist を設定します。 +`tools.profile` は、`tools.allow`/`tools.deny` より前に基本 allowlist を設定します: -ローカルのオンボーディングでは、新しいローカル設定で未設定の場合、デフォルトで `tools.profile: "coding"` を設定します（既存の明示的なプロファイルは保持されます）。 +ローカルのオンボーディングでは、未設定の場合に新しいローカル設定をデフォルトで `tools.profile: "coding"` にします（既存の明示的な 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` | 制限なし（未設定と同じ） | +| 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` | 制限なし（未設定と同じ） | -### Tool グループ +### Tool 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` の alias として受け付けます） | +| `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` | すべての組み込み 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 の許可/拒否ポリシーです（deny が優先）。大文字小文字を区別せず、`*` ワイルドカードをサポートします。Docker sandbox がオフでも適用されます。 +グローバルな tool の allow/deny ポリシーです（deny が優先）。大文字小文字を区別せず、`*` ワイルドカードをサポートします。Docker sandbox が無効でも適用されます。 ```json5 { @@ -2204,7 +2205,7 @@ Talk mode（macOS/iOS/Android）のデフォルト設定です。 ### `tools.byProvider` -特定の provider または model に対して tools をさらに制限します。順序: ベースプロファイル → provider プロファイル → allow/deny。 +特定の provider または model に対してさらに tools を制限します。順序: 基本 profile → provider profile → allow/deny。 ```json5 { @@ -2220,7 +2221,7 @@ Talk mode（macOS/iOS/Android）のデフォルト設定です。 ### `tools.elevated` -sandbox の外での elevated exec アクセスを制御します: +sandbox 外での elevated `exec` アクセスを制御します: ```json5 { @@ -2237,8 +2238,8 @@ sandbox の外での elevated exec アクセスを制御します: ``` - agent ごとのオーバーライド（`agents.list[].tools.elevated`）は、さらに制限することしかできません。 -- `/elevated on|off|ask|full` は状態を session ごとに保存します。インラインディレクティブは 1 件のメッセージにのみ適用されます。 -- Elevated `exec` は sandbox 化をバイパスし、設定された escape path を使います（デフォルトは `gateway`、exec ターゲットが `node` の場合は `node`）。 +- `/elevated on|off|ask|full` は状態を session ごとに保存します。インライン directive は単一メッセージにのみ適用されます。 +- elevated `exec` は sandbox 化をバイパスし、設定された escape path（デフォルトは `gateway`、`exec` のターゲットが `node` の場合は `node`）を使用します。 ### `tools.exec` @@ -2262,8 +2263,8 @@ sandbox の外での elevated exec アクセスを制御します: ### `tools.loopDetection` -tool ループの安全チェックは**デフォルトで無効**です。有効化するには `enabled: true` を設定してください。 -設定はグローバルに `tools.loopDetection` で定義でき、agent ごとに `agents.list[].tools.loopDetection` で上書きできます。 +tool ループ安全チェックはデフォルトでは**無効**です。検出を有効にするには `enabled: true` を設定してください。 +設定はグローバルの `tools.loopDetection` で定義でき、agent ごとに `agents.list[].tools.loopDetection` で上書きできます。 ```json5 { @@ -2284,13 +2285,13 @@ tool ループの安全チェックは**デフォルトで無効**です。有 } ``` -- `historySize`: ループ分析のために保持する tool 呼び出し履歴の最大数。 +- `historySize`: ループ解析用に保持する tool 呼び出し履歴の最大数。 - `warningThreshold`: 警告を出す、進捗なしの繰り返しパターンのしきい値。 - `criticalThreshold`: 重大なループをブロックするための、より高い繰り返ししきい値。 -- `globalCircuitBreakerThreshold`: あらゆる進捗なし実行に対するハード停止しきい値。 -- `detectors.genericRepeat`: 同じ tool/同じ引数の繰り返し呼び出しに警告します。 -- `detectors.knownPollNoProgress`: 既知の poll tools（`process.poll`、`command_status` など）に対して警告/ブロックします。 -- `detectors.pingPong`: 交互に続く進捗なしのペアパターンに警告/ブロックします。 +- `globalCircuitBreakerThreshold`: あらゆる進捗なし実行に対するハードストップしきい値。 +- `detectors.genericRepeat`: 同じ tool/同じ引数の呼び出し繰り返しで警告します。 +- `detectors.knownPollNoProgress`: 既知の poll tool（`process.poll`、`command_status` など）で進捗がない場合に警告/ブロックします。 +- `detectors.pingPong`: 進捗なしの交互ペアパターンに対して警告/ブロックします。 - `warningThreshold >= criticalThreshold` または `criticalThreshold >= globalCircuitBreakerThreshold` の場合、検証は失敗します。 ### `tools.web` @@ -2301,14 +2302,14 @@ tool ループの安全チェックは**デフォルトで無効**です。有 web: { search: { enabled: true, - apiKey: "brave_api_key", // または BRAVE_API_KEY env + apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // 任意。自動検出する場合は省略 + provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2325,7 +2326,7 @@ tool ループの安全チェックは**デフォルトで無効**です。有 ### `tools.media` -受信 media 理解（画像/音声/動画）を設定します: +受信 media 理解（image/audio/video）を設定します: ```json5 { @@ -2333,7 +2334,7 @@ tool ループの安全チェックは**デフォルトで無効**です。有 media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: 完了した非同期 music/video を channel に直接送信 + directSend: false, // opt-in: send finished async music/video directly to the channel }, audio: { enabled: true, @@ -2363,7 +2364,7 @@ tool ループの安全チェックは**デフォルトで無効**です。有 - `provider`: API provider id（`openai`、`anthropic`、`google`/`gemini`、`groq` など） - `model`: model id オーバーライド -- `profile` / `preferredProfile`: `auth-profiles.json` のプロファイル選択 +- `profile` / `preferredProfile`: `auth-profiles.json` の profile 選択 **CLI エントリ**（`type: "cli"`）: @@ -2374,14 +2375,14 @@ tool ループの安全チェックは**デフォルトで無効**です。有 - `capabilities`: 任意のリスト（`image`、`audio`、`video`）。デフォルト: `openai`/`anthropic`/`minimax` → image、`google` → image+audio+video、`groq` → audio。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`: エントリごとのオーバーライド。 -- 失敗した場合は次のエントリにフォールバックします。 +- 失敗時は次のエントリにフォールバックします。 -provider の auth は標準順序に従います: `auth-profiles.json` → env vars → `models.providers.*.apiKey`。 +provider 認証は標準順序に従います: `auth-profiles.json` → 環境変数 → `models.providers.*.apiKey`。 **非同期完了フィールド:** - `asyncCompletion.directSend`: `true` の場合、完了した非同期 `music_generate` - および `video_generate` タスクは、まず direct channel 配信を試みます。デフォルト: `false` + と `video_generate` タスクは、まず direct な channel 配信を試みます。デフォルト: `false` （従来の requester-session wake/model-delivery パス）。 @@ -2401,9 +2402,9 @@ provider の auth は標準順序に従います: `auth-profiles.json` → env v ### `tools.sessions` -session tools（`sessions_list`、`sessions_history`、`sessions_send`）でどの session を対象にできるかを制御します。 +session tool（`sessions_list`、`sessions_history`、`sessions_send`）で、どの session を対象にできるかを制御します。 -デフォルト: `tree`（現在の session + そこから spawn された session。たとえば subagents）。 +デフォルト: `tree`（現在の session + そこから spawn された session、たとえば subagent）。 ```json5 { @@ -2419,25 +2420,25 @@ session tools（`sessions_list`、`sessions_history`、`sessions_send`）でど 注意: - `self`: 現在の session key のみ。 -- `tree`: 現在の session + 現在の session から spawn された session（subagents）。 -- `agent`: 現在の agent id に属する任意の session（同じ agent id の下で送信者ごとの session を実行している場合、他のユーザーを含むことがあります）。 -- `all`: 任意の session。agent 間ターゲティングには引き続き `tools.agentToAgent` が必要です。 -- sandbox クランプ: 現在の session が sandbox 化されており、`agents.defaults.sandbox.sessionToolsVisibility="spawned"` の場合、`tools.sessions.visibility="all"` でも可視性は `tree` に強制されます。 +- `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` に強制されます。 ### `tools.sessions_spawn` -`sessions_spawn` のインライン添付サポートを制御します。 +`sessions_spawn` のインライン attachment サポートを制御します。 ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: true にするとインラインファイル添付を許可 - maxTotalBytes: 5242880, // すべてのファイル合計で 5 MB + enabled: false, // opt-in: set true to allow inline file attachments + maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, - maxFileBytes: 1048576, // 1 ファイルあたり 1 MB - retainOnSessionKeep: false, // cleanup="keep" のときに添付を保持 + maxFileBytes: 1048576, // 1 MB per file + retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, @@ -2446,22 +2447,22 @@ session tools（`sessions_list`、`sessions_history`、`sessions_send`）でど 注意: -- 添付は `runtime: "subagent"` でのみサポートされます。ACP ランタイムはこれを拒否します。 +- attachment は `runtime: "subagent"` でのみサポートされます。ACP runtime はそれらを拒否します。 - ファイルは子 workspace の `.openclaw/attachments//` に `.manifest.json` とともに実体化されます。 -- 添付内容は transcript 永続化から自動的に秘匿化されます。 -- Base64 入力は、厳格なアルファベット/パディング検査とデコード前サイズガードで検証されます。 +- attachment 内容は transcript 永続化から自動的に redaction されます。 +- Base64 入力は、厳格な alphabet/padding チェックと、デコード前サイズガードで検証されます。 - ファイル権限は、ディレクトリが `0700`、ファイルが `0600` です。 -- クリーンアップは `cleanup` ポリシーに従います: `delete` は常に添付を削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 +- クリーンアップは `cleanup` ポリシーに従います: `delete` は常に attachment を削除し、`keep` は `retainOnSessionKeep: true` の場合にのみ保持します。 ### `tools.experimental` -実験的な組み込み tool フラグです。strict-agentic GPT-5 の自動有効化ルールが適用される場合を除き、デフォルトはオフです。 +実験的な built-in tool フラグです。strict-agentic GPT-5 の自動有効化ルールが適用される場合を除き、デフォルトは off です。 ```json5 { tools: { experimental: { - planTool: true, // 実験的な update_plan を有効化 + planTool: true, // enable experimental update_plan }, }, } @@ -2469,9 +2470,9 @@ session tools（`sessions_list`、`sessions_history`、`sessions_send`）でど 注意: -- `planTool`: 自明でない複数ステップ作業の追跡用に、構造化された `update_plan` tool を有効にします。 -- デフォルト: `agents.defaults.embeddedPi.executionContract`（または agent ごとのオーバーライド）が OpenAI または OpenAI Codex の GPT-5 系実行に対して `"strict-agentic"` に設定されている場合を除き `false`。その範囲外でも強制的に有効にするには `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"` に設定されている場合は除きます。その範囲外でも強制的に有効にするには `true` を設定し、strict-agentic GPT-5 実行でも無効のままにするには `false` を設定します。 +- 有効な場合、system prompt にも使用ガイダンスが追加され、model はそれを実質的な作業にのみ使い、`in_progress` のステップを最大 1 つに保ちます。 ### `agents.defaults.subagents` @@ -2491,16 +2492,16 @@ session tools（`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` のデフォルトタイムアウト（秒）。`0` はタイムアウトなしを意味します。 -- sub-agent ごとの tool ポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `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 なしを意味します。 +- subagent ごとの tool ポリシー: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## カスタム provider と base URL -OpenClaw は組み込み model カタログを使用します。カスタム provider は設定の `models.providers` または `~/.openclaw/agents//agent/models.json` で追加できます。 +OpenClaw は組み込み model カタログを使用します。カスタム provider は config 内の `models.providers` または `~/.openclaw/agents//agent/models.json` を通じて追加します。 ```json5 { @@ -2529,48 +2530,48 @@ OpenClaw は組み込み model カタログを使用します。カスタム pro } ``` -- カスタム auth が必要な場合は `authHeader: true` + `headers` を使用します。 -- agent 設定ルートは `OPENCLAW_AGENT_DIR`（または legacy な環境変数 alias の `PI_CODING_AGENT_DIR`）で上書きできます。 +- カスタム認証が必要な場合は `authHeader: true` + `headers` を使用します。 +- agent 設定ルートは `OPENCLAW_AGENT_DIR`（または従来の環境変数 alias である `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 ヘッダー値も、ソースマーカー（env ref には `secretref-env:ENV_VAR_NAME`、file/exec ref には `secretref-managed`）から再更新されます。 - - agent の `apiKey`/`baseUrl` が空または欠落している場合は、設定の `models.providers` にフォールバックします。 - - 一致する model の `contextWindow`/`maxTokens` には、明示的な設定値と暗黙のカタログ値のうち高い方が使われます。 - - 一致する model の `contextTokens` は、明示的なランタイム上限が存在する場合それを保持します。ネイティブ model メタデータを変更せずに有効コンテキストを制限したい場合に使ってください。 - - 設定で `models.json` を完全に上書きしたい場合は `models.mode: "replace"` を使います。 - - マーカーの永続化はソース優先です。マーカーは、解決済みランタイム secret 値からではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。 + - 空でない 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 メタデータを変更せずに有効コンテキストを制限するにはこれを使用してください。 + - config で `models.json` を完全に上書きしたい場合は `models.mode: "replace"` を使用します。 + - マーカーの永続化はソースを正として行われます。マーカーは、解決済み runtime secret 値からではなく、アクティブなソース config snapshot（解決前）から書き込まれます。 -### Provider フィールド詳細 +### 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/env 置換の利用を推奨）。 +- `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.*.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.*.request`: model-provider HTTP リクエストの転送オーバーライド。 - - `request.headers`: 追加ヘッダー（provider デフォルトとマージ）。値には SecretRef を使えます。 - - `request.auth`: 認証戦略オーバーライド。モード: `"provider-default"`（provider 組み込み 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 を許可します（信頼済みセルフホスト OpenAI 互換 endpoint 用の operator opt-in）。WebSocket はヘッダー/TLS には同じ `request` を使いますが、その fetch SSRF ガードは使いません。デフォルトは `false`。 +- `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`。 - `models.providers.*.models`: 明示的な provider model カタログエントリ。 -- `models.providers.*.models.*.contextWindow`: model ネイティブのコンテキストウィンドウメタデータ。 -- `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 endpoint 用の任意の互換性ヒント。`true` の場合、OpenClaw はリクエスト送信前に、純粋なテキストの `messages[].content` 配列をプレーン文字列へ平坦化します。 +- `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` 配列をプレーン文字列へ平坦化します。 - `plugins.entries.amazon-bedrock.config.discovery`: Bedrock 自動検出設定のルート。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 暗黙的な検出をオン/オフします。 -- `plugins.entries.amazon-bedrock.config.discovery.region`: 検出に使う AWS リージョン。 +- `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.refreshInterval`: 検出更新のポーリング間隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出された models 用のフォールバック context window。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出された models 用のフォールバック最大出力 token 数。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 検出された model 用のフォールバック context window。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 検出された model 用のフォールバック最大出力 token 数。 ### Provider の例 @@ -2608,7 +2609,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` を使用します。 @@ -2625,7 +2626,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`。 @@ -2642,11 +2643,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/*` はどちらも alias として受け付けられます。ショートカット: `openclaw onboard --auth-choice zai-api-key`。 -- 一般 endpoint: `https://api.z.ai/api/paas/v4` -- コーディング endpoint（デフォルト）: `https://api.z.ai/api/coding/paas/v4` -- 一般 endpoint を使う場合は、base URL オーバーライド付きのカスタム provider を定義してください。 +- 一般エンドポイント: `https://api.z.ai/api/paas/v4` +- コーディングエンドポイント（デフォルト）: `https://api.z.ai/api/coding/paas/v4` +- 一般エンドポイントを使う場合は、base URL オーバーライド付きのカスタム provider を定義してください。 @@ -2685,10 +2686,11 @@ Cerebras には `cerebras/zai-glm-4.7` を使用し、Z.AI へ直接接続する } ``` -China endpoint 用: `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn`。 +China エンドポイント用: `baseUrl: "https://api.moonshot.cn/v1"` または `openclaw onboard --auth-choice moonshot-api-key-cn`。 -ネイティブ Moonshot endpoint は、共有の -`openai-completions` 転送上でストリーミング使用互換性を公開しており、OpenClaw は組み込み provider id だけでなく、その endpoint の機能に基づいてそれを判断します。 +ネイティブ Moonshot エンドポイントは、共有の +`openai-completions` 転送上でストリーミング利用互換性を公開しており、OpenClaw は +組み込み provider id だけでなく、そのエンドポイント capability に基づいてこれを判定します。 @@ -2749,7 +2751,7 @@ base URL には `/v1` を含めないでください（Anthropic クライアン - + ```json5 { @@ -2789,16 +2791,16 @@ base URL には `/v1` を含めないでください（Anthropic クライアン `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` に書き換えます。 - + -[Local Models](/ja-JP/gateway/local-models) を参照してください。要点: 十分な性能のハードウェア上で LM Studio Responses API を使って大きなローカル model を実行し、フォールバック用にホスト型 models もマージしたままにしておきます。 +[Local Models](/ja-JP/gateway/local-models) を参照してください。要点: 十分なハードウェア上で LM Studio Responses API を使って大きなローカル model を実行し、フォールバック用にホスト型 model はマージしたままにしてください。 @@ -2819,7 +2821,7 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // またはプレーンテキスト文字列 + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2831,11 +2833,12 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を - `allowBundled`: bundled Skills のみを対象にした任意の allowlist です（managed/workspace Skills には影響しません）。 - `load.extraDirs`: 追加の共有 skill ルート（最も低い優先順位）。 -- `install.preferBrew`: `true` の場合、`brew` が利用可能なら他の installer 種別へフォールバックする前に Homebrew installer を優先します。 +- `install.preferBrew`: true の場合、`brew` が利用可能なら + 他の installer 種類にフォールバックする前に Homebrew installer を優先します。 - `install.nodeManager`: `metadata.openclaw.install` - 指定用の node installer 優先設定（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false` は、その skill が bundled/installed であっても無効にします。 -- `entries..apiKey`: 主要 env var を宣言する Skills 向けの簡易設定です（プレーンテキスト文字列または SecretRef オブジェクト）。 + spec 用の node installer 優先設定（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false` は、bundled/installed されていても skill を無効にします。 +- `entries..apiKey`: プライマリ環境変数を宣言する Skills 向けの簡易設定です（平文文字列または SecretRef オブジェクト）。 --- @@ -2864,40 +2867,40 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を ``` - `~/.openclaw/extensions`、`/.openclaw/extensions`、および `plugins.load.paths` から読み込まれます。 -- 検出では、ネイティブ OpenClaw Plugins に加えて、互換性のある Codex bundle と Claude bundle も受け付けます。manifest のない Claude のデフォルトレイアウト bundle も含まれます。 +- 検出は、ネイティブ OpenClaw Plugin に加え、互換性のある Codex bundle と Claude bundle も受け付けます。manifest のない Claude デフォルトレイアウト bundle も含まれます。 - **設定変更には Gateway の再起動が必要です。** -- `allow`: 任意の allowlist（一覧にある Plugins のみ読み込まれます）。`deny` が優先されます。 -- `plugins.entries..apiKey`: Plugin レベルの API キー用簡易フィールド（Plugin がサポートしている場合）。 -- `plugins.entries..env`: Plugin スコープの env var マップ。 -- `plugins.entries..hooks.allowPromptInjection`: `false` の場合、core は `before_prompt_build` をブロックし、従来の `before_agent_start` からの prompt 変更フィールドを無視します。一方で、従来の `modelOverride` と `providerOverride` は保持します。ネイティブ Plugin hooks と、サポートされる bundle 提供の hook ディレクトリに適用されます。 -- `plugins.entries..subagent.allowModelOverride`: この Plugin が、バックグラウンド subagent 実行ごとに `provider` と `model` のオーバーライドを要求することを明示的に信頼します。 -- `plugins.entries..subagent.allowedModels`: 信頼済み subagent オーバーライド用の、正規 `provider/model` ターゲットの任意の allowlist。任意の model を許可したい意図がある場合にのみ `"*"` を使ってください。 +- `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 を許可したい意図がある場合にのみ `"*"` を使用してください。 - `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` env var にフォールバックします。 +- `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`）。 - - `onlyMainContent`: ページから主要コンテンツのみを抽出します（デフォルト: `true`）。 - - `maxAgeMs`: キャッシュの最大有効期間（ミリ秒）（デフォルト: `172800000` / 2 日）。 - - `timeoutSeconds`: スクレイプリクエストのタイムアウト秒数（デフォルト: `60`）。 + - `onlyMainContent`: ページからメインコンテンツのみを抽出します（デフォルト: `true`）。 + - `maxAgeMs`: キャッシュの最大有効期間（ミリ秒、デフォルト: `172800000` / 2 日）。 + - `timeoutSeconds`: スクレイプ要求の timeout（秒、デフォルト: `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 * * *"`）。 - - フェーズポリシーとしきい値は実装詳細であり、ユーザー向け設定キーではありません。 -- 完全な memory 設定は [メモリ設定リファレンス](/ja-JP/reference/memory-config) にあります: + - `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) にあります: - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 有効な Claude bundle Plugins は、`settings.json` から埋め込み Pi デフォルトも提供できます。OpenClaw はそれらを生の OpenClaw 設定パッチではなく、サニタイズ済み agent 設定として適用します。 -- `plugins.slots.memory`: アクティブな memory Plugin id を選択するか、memory Plugins を無効にするには `"none"` を指定します。 +- 有効な Claude bundle Plugin は、`settings.json` から embedded Pi デフォルトを提供することもできます。OpenClaw はそれらを生の OpenClaw config patch としてではなく、サニタイズされた 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) を参照してください。 @@ -2912,7 +2915,7 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 信頼できる private-network アクセスに対してのみ opt in + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2940,29 +2943,28 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を ``` - `evaluateEnabled: false` は `act:evaluate` と `wait --fn` を無効にします。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定時には無効なので、browser ナビゲーションはデフォルトで strict のままです。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定時には無効であるため、browser ナビゲーションはデフォルトで strict のままです。 - `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` は、private-network browser ナビゲーションを意図的に信頼する場合にのみ設定してください。 -- strict モードでは、リモート CDP profile endpoint（`profiles.*.cdpUrl`）にも、到達性/検出チェック時に同じ private-network ブロックが適用されます。 +- strict mode では、リモート CDP profile エンドポイント（`profiles.*.cdpUrl`）も、到達性/検出チェック中に同じ private-network ブロックの対象になります。 - `ssrfPolicy.allowPrivateNetwork` は従来の alias として引き続きサポートされます。 -- strict モードでは、明示的な例外には `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使います。 -- リモート profiles は attach-only です（start/stop/reset は無効）。 +- strict mode では、明示的な例外に `ssrfPolicy.hostnameAllowlist` と `ssrfPolicy.allowedHostnames` を使用してください。 +- リモート profile は attach-only です（start/stop/reset は無効）。 - `profiles.*.cdpUrl` は `http://`、`https://`、`ws://`、`wss://` を受け付けます。 - `/json/version` を OpenClaw に検出させたい場合は HTTP(S) を使い、 - provider が直接の DevTools WebSocket URL を提供する場合は WS(S) - を使ってください。 -- `existing-session` profiles は host 専用で、CDP の代わりに Chrome MCP を使います。 -- `existing-session` profiles では、特定の - Chromium ベース browser profile（Brave や Edge など）を対象にするために `userDataDir` を設定できます。 -- `existing-session` profiles は、現在の Chrome MCP ルート制限を維持します: + provider に直接の DevTools WebSocket URL がある場合は WS(S) を、 + OpenClaw に `/json/version` を検出させたい場合は HTTP(S) を使用してください。 +- `existing-session` profile はホスト専用で、CDP の代わりに Chrome MCP を使用します。 +- `existing-session` profile は、Brave や Edge のような特定の + Chromium ベース browser profile を対象にするために `userDataDir` を設定できます。 +- `existing-session` profile は、現在の Chrome MCP ルート制限を維持します: CSS セレクター指定ではなく snapshot/ref ベースのアクション、単一ファイルのアップロード - hooks、dialog タイムアウト上書きなし、`wait --load networkidle` なし、 - さらに `responsebody`、PDF エクスポート、ダウンロード傍受、バッチアクションもありません。 -- ローカル管理の `openclaw` profiles は `cdpPort` と `cdpUrl` を自動割り当てします。明示的に - `cdpUrl` を設定するのはリモート CDP の場合のみです。 + 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。 -- 制御サービス: loopback のみ（port は `gateway.port` から導出。デフォルト `18791`）。 -- `extraArgs` は、ローカル Chromium 起動に追加の起動フラグを付加します（たとえば - `--disable-gpu`、ウィンドウサイズ設定、デバッグフラグなど）。 +- Control service: loopback のみ（port は `gateway.port` から導出、デフォルト `18791`）。 +- `extraArgs` は、ローカル Chromium 起動に追加の launch フラグを付加します（たとえば + `--disable-gpu`、ウィンドウサイズ指定、デバッグフラグなど）。 --- @@ -2980,8 +2982,8 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を } ``` -- `seamColor`: ネイティブ app UI chrome 用のアクセントカラーです（Talk Mode のバブル色合いなど）。 -- `assistant`: Control UI の identity オーバーライド。アクティブな agent identity にフォールバックします。 +- `seamColor`: ネイティブ app UI chrome のアクセントカラー（Talk Mode のバブル色など）。 +- `assistant`: Control UI の identity オーバーライド。アクティブ agent identity にフォールバックします。 --- @@ -2997,7 +2999,7 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を mode: "token", // none | token | password | trusted-proxy token: "your-token", // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // mode=trusted-proxy 用。/gateway/trusted-proxy-auth を参照 + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3015,9 +3017,9 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // 危険: 絶対外部 http(s) 埋め込み URL を許可 - // allowedOrigins: ["https://control.example.com"], // 非 loopback の Control UI に必須 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危険な Host ヘッダー origin フォールバックモード + // 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 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3028,12 +3030,12 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // 任意。デフォルトは false。 + // Optional. Default false. allowRealIpFallback: false, tools: { - // /tools/invoke HTTP に対する追加 deny + // Additional /tools/invoke HTTP denies deny: ["browser"], - // デフォルトの HTTP deny リストから tools を除外 + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -3048,67 +3050,67 @@ Anthropic 互換ストリーミングパスでは、OpenClaw は `thinking` を } ``` - + -- `mode`: `local`（Gateway を実行）または `remote`（リモート Gateway に接続）。`local` でない限り Gateway は起動を拒否します。 +- `mode`: `local`（Gateway を実行）または `remote`（リモート Gateway に接続）。Gateway は `local` でない限り起動を拒否します。 - `port`: WS + HTTP 用の単一多重化ポート。優先順位: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`: `auto`、`loopback`（デフォルト）、`lan`（`0.0.0.0`）、`tailnet`（Tailscale IP のみ）、または `custom`。 -- **従来の bind alias**: `gateway.bind` にはホスト 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"`）を設定してください。 -- **Auth**: デフォルトで必須です。loopback 以外の bind には Gateway auth が必要です。実運用では、共有 token/password または `gateway.auth.mode: "trusted-proxy"` を使う ID 認識型 reverse proxy を意味します。オンボーディングウィザードはデフォルトで token を生成します。 -- `gateway.auth.token` と `gateway.auth.password` の両方が設定されている場合（SecretRef を含む）、`gateway.auth.mode` を `token` または `password` に明示設定してください。両方が設定されていて mode が未設定の場合、起動と service のインストール/修復フローは失敗します。 -- `gateway.auth.mode: "none"`: 明示的な no-auth mode。信頼できる local loopback 構成でのみ使用してください。これは意図的にオンボーディングプロンプトでは提供されません。 -- `gateway.auth.mode: "trusted-proxy"`: auth を ID 認識型 reverse proxy に委譲し、`gateway.trustedProxies` からの ID ヘッダーを信頼します（[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照）。この mode は**非 loopback** の proxy ソースを前提とします。同一ホストの loopback reverse proxy は trusted-proxy auth の要件を満たしません。 -- `gateway.auth.allowTailscale`: `true` の場合、Tailscale Serve の identity ヘッダーで Control UI/WebSocket auth を満たせます（`tailscale whois` で検証）。HTTP API endpoint はこの Tailscale ヘッダー auth を**使わず**、通常の Gateway HTTP auth mode に従います。この token なしフローは Gateway ホストが信頼されている前提です。`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 トラフィックも意図的にレート制限したい場合（テスト構成や厳格な proxy 配置など）は `false` に設定してください。 -- browser 由来の WS auth 試行は、loopback 免除を無効にした状態で常にスロットルされます（browser ベースの localhost ブルートフォースに対する多層防御）。 -- loopback 上では、それらの browser 由来ロックアウトは正規化された `Origin` - 値ごとに分離されるため、ある localhost origin からの繰り返し失敗が、 - 自動的に別の origin をロックアウトすることはありません。 -- `tailscale.mode`: `serve`（tailnet のみ、loopback bind）または `funnel`（公開、auth 必須）。 -- `controlUi.allowedOrigins`: Gateway WebSocket 接続用の明示的な browser origin allowlist。非 loopback origin から browser クライアントが接続する想定なら必須です。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host ヘッダー origin ポリシーに意図的に依存するデプロイ向けの、危険な Host ヘッダー origin フォールバックモードを有効にします。 +- **従来の 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 フォールバックを有効にする危険なモードです。 - `remote.transport`: `ssh`（デフォルト）または `direct`（ws/wss）。`direct` の場合、`remote.url` は `ws://` または `wss://` でなければなりません。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: クライアント側の非常時用オーバーライドで、信頼できる private-network IP への平文 `ws://` を許可します。デフォルトでは、平文は引き続き loopback のみです。 -- `gateway.remote.token` / `.password` はリモートクライアント用の認証情報フィールドです。これら自体は Gateway auth を設定しません。 -- `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 への送信タイムアウト（ミリ秒）。デフォルトは `10000`。 -- relay バック登録は特定の Gateway identity に委譲されます。ペア済み iOS app は `gateway.identity.get` を取得し、その identity を relay 登録に含め、登録スコープの送信権限を 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 ヘルスモニター間隔（分）。ヘルスモニター再起動をグローバルに無効にするには `0` を設定します。デフォルト: `5`。 -- `gateway.channelStaleEventThresholdMinutes`: 古い socket と見なすしきい値（分）。これは `gateway.channelHealthCheckMinutes` 以上に保ってください。デフォルト: `30`。 -- `gateway.channelMaxRestartsPerHour`: ローリング 1 時間あたりの、channel/account ごとのヘルスモニター再起動回数上限。デフォルト: `10`。 -- `channels..healthMonitor.enabled`: グローバルモニターを有効のまま、channel ごとにヘルスモニター再起動を opt out します。 -- `channels..accounts..healthMonitor.enabled`: マルチアカウント channel 用のアカウントごとのオーバーライド。設定されている場合、channel レベルのオーバーライドより優先されます。 -- ローカル Gateway 呼び出しパスでは、`gateway.auth.*` が未設定の場合にのみ `gateway.remote.*` をフォールバックとして使えます。 -- `gateway.auth.token` / `gateway.auth.password` が SecretRef 経由で明示設定されていて未解決の場合、解決はフェイルクローズします（リモートフォールバックで隠蔽されません）。 -- `trustedProxies`: TLS を終端する、または転送クライアントヘッダーを注入する reverse proxy の IP。自分が管理する proxy のみを列挙してください。loopback エントリは、同一ホスト proxy/ローカル検出構成（たとえば Tailscale Serve やローカル reverse proxy）では依然有効ですが、loopback リクエストが `gateway.auth.mode: "trusted-proxy"` の対象になるわけでは**ありません**。 -- `allowRealIpFallback`: `true` の場合、`X-Forwarded-For` がないときに `X-Real-IP` を受け入れます。デフォルトは、フェイルクローズ動作のため `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://` を許可するクライアント側の 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 名を除外します。 -### OpenAI 互換 endpoint +### 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 入力 hardening: +- Responses の URL 入力ハードニング: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` 空の allowlist は未設定として扱われます。URL 取得を無効にするには `gateway.http.endpoints.responses.files.allowUrl=false` - および/または `gateway.http.endpoints.responses.images.allowUrl=false` を使ってください。 -- 任意のレスポンス hardening ヘッダー: - - `gateway.http.securityHeaders.strictTransportSecurity`（自分が制御する HTTPS origin に対してのみ設定。 [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts) を参照） + および/または `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)） ### マルチインスタンス分離 -1 台のホストで複数の Gateway を、固有のポートと状態ディレクトリで実行します: +一意の port と state dir を使って、1 台のホストで複数の Gateway を実行します: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3116,7 +3118,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -便利なフラグ: `--dev`（`~/.openclaw-dev` + ポート `19001` を使用）、`--profile `（`~/.openclaw-` を使用）。 +便利なフラグ: `--dev`（`~/.openclaw-dev` + port `19001` を使用）、`--profile `（`~/.openclaw-` を使用）。 [Multiple Gateways](/ja-JP/gateway/multiple-gateways) を参照してください。 @@ -3136,11 +3138,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: Gateway リスナーで TLS 終端（HTTPS/WSS）を有効にします（デフォルト: `false`）。 +- `enabled`: Gateway リスナーでの TLS 終端（HTTPS/WSS）を有効にします（デフォルト: `false`）。 - `autoGenerate`: 明示的なファイルが設定されていない場合に、ローカルの自己署名 cert/key ペアを自動生成します。ローカル/開発用途専用です。 - `certPath`: TLS 証明書ファイルへのファイルシステムパス。 -- `keyPath`: TLS 秘密鍵ファイルへのファイルシステムパス。権限制限を維持してください。 -- `caPath`: クライアント検証またはカスタム信頼チェーン用の任意の CA バンドルパス。 +- `keyPath`: TLS 秘密鍵ファイルへのファイルシステムパス。権限制限をかけてください。 +- `caPath`: クライアント検証またはカスタム信頼チェーン用の任意の CA bundle パス。 ### `gateway.reload` @@ -3156,13 +3158,13 @@ openclaw gateway --port 19001 } ``` -- `mode`: 設定編集をランタイムでどのように適用するかを制御します。 +- `mode`: config 編集を runtime 中にどのように適用するかを制御します。 - `"off"`: ライブ編集を無視します。変更には明示的な再起動が必要です。 - - `"restart"`: 設定変更時に常に Gateway プロセスを再起動します。 + - `"restart"`: config 変更時に常に Gateway プロセスを再起動します。 - `"hot"`: 再起動せずにプロセス内で変更を適用します。 - - `"hybrid"`（デフォルト）: まず hot reload を試し、必要であれば restart にフォールバックします。 -- `debounceMs`: 設定変更を適用する前の debounce ウィンドウ（ms）（非負整数）。 -- `deferralTimeoutMs`: 進行中の操作を待ってから再起動を強制するまでの最大時間（ms）（デフォルト: `300000` = 5 分）。 + - `"hybrid"`（デフォルト）: まず hot reload を試し、必要に応じて再起動にフォールバックします。 +- `debounceMs`: config 変更を適用する前の debounce ウィンドウ（ms、非負整数）。 +- `deferralTimeoutMs`: 進行中処理を待ってから再起動を強制するまでの最大時間（ms、デフォルト: `300000` = 5 分）。 --- @@ -3199,37 +3201,37 @@ openclaw gateway --port 19001 } ``` -Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 +認証: `Authorization: Bearer ` または `x-openclaw-token: `。 クエリ文字列の hook token は拒否されます。 検証と安全性に関する注意: -- `hooks.enabled=true` には、空でない `hooks.token` が必要です。 -- `hooks.token` は `gateway.auth.token` と**異なっている必要があります**。Gateway token の再利用は拒否されます。 -- `hooks.path` は `/` にできません。`/hooks` のような専用サブパスを使ってください。 -- `hooks.allowRequestSessionKey=true` の場合は、`hooks.allowedSessionKeyPrefixes` を制限してください（例: `["hook:"]`）。 +- `hooks.enabled=true` には空でない `hooks.token` が必要です。 +- `hooks.token` は `gateway.auth.token` と**異なる**必要があります。Gateway token の再利用は拒否されます。 +- `hooks.path` は `/` にできません。`/hooks` のような専用サブパスを使用してください。 +- `hooks.allowRequestSessionKey=true` の場合は、`hooks.allowedSessionKeyPrefixes` を制約してください（たとえば `["hook:"]`）。 -**Endpoints:** +**エンドポイント:** - `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 アクションを返す JS/TS module を指せます。 - - `transform.module` は相対パスである必要があり、`hooks.transformsDir` 内にとどまります（絶対パスと path traversal は拒否されます）。 -- `agentId` は特定の agent にルーティングします。不明な ID はデフォルトへフォールバックします。 +- `transform` には hook action を返す JS/TS モジュールを指定できます。 + - `transform.module` は相対パスでなければならず、`hooks.transformsDir` 内に留まる必要があります（絶対パスと path traversal は拒否されます）。 +- `agentId` は特定の agent にルーティングします。不明な ID はデフォルトにフォールバックします。 - `allowedAgentIds`: 明示的なルーティングを制限します（`*` または省略 = すべて許可、`[]` = すべて拒否）。 -- `defaultSessionKey`: 明示的な `sessionKey` がない hook agent 実行用の任意の固定 session key。 +- `defaultSessionKey`: 明示的な `sessionKey` のない hook agent 実行用の任意の固定 session key。 - `allowRequestSessionKey`: `/hooks/agent` 呼び出し元が `sessionKey` を設定できるようにします（デフォルト: `false`）。 -- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（リクエスト + マッピング）用の任意の接頭辞 allowlist。例: `["hook:"]`。 +- `allowedSessionKeyPrefixes`: 明示的な `sessionKey` 値（request + mapping）向けの任意のプレフィックス allowlist。例: `["hook:"]`。 - `deliver: true` は最終返信を channel に送信します。`channel` のデフォルトは `last` です。 -- `model` はこの hook 実行用の LLM を上書きします（model カタログが設定されている場合、許可されている必要があります）。 +- `model` はこの hook 実行用の LLM を上書きします（model カタログが設定されている場合は許可されている必要があります）。 @@ -3268,21 +3270,21 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // または OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- agent が編集可能な HTML/CSS/JS と A2UI を、Gateway ポート配下の HTTP で配信します: +- Gateway port 配下の HTTP で、agent が編集可能な HTML/CSS/JS と A2UI を配信します: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - ローカル専用: `gateway.bind: "loopback"`（デフォルト）のままにしてください。 -- loopback 以外の bind では、canvas ルートにも他の Gateway HTTP サーフェスと同様に Gateway auth（token/password/trusted-proxy）が必要です。 -- Node WebViews は通常 auth ヘッダーを送信しません。node がペアリングされ接続されると、Gateway は canvas/A2UI アクセス用の node スコープ capability URL を通知します。 -- capability URL はアクティブな node WS セッションにバインドされ、すぐに期限切れになります。IP ベースのフォールバックは使われません。 +- 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 クライアントを注入します。 -- 空の場合はスターター `index.html` を自動作成します。 -- A2UI も `/__openclaw__/a2ui/` で配信します。 +- 空の場合は starter `index.html` を自動作成します。 +- `/__openclaw__/a2ui/` でも A2UI を配信します。 - 変更には Gateway の再起動が必要です。 - 大きなディレクトリや `EMFILE` エラーの場合は live reload を無効にしてください。 @@ -3304,7 +3306,7 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 - `minimal`（デフォルト）: TXT レコードから `cliPath` + `sshPort` を省略します。 - `full`: `cliPath` + `sshPort` を含めます。 -- hostname のデフォルトは `openclaw`。上書きするには `OPENCLAW_MDNS_HOSTNAME` を使います。 +- hostname のデフォルトは `openclaw` です。`OPENCLAW_MDNS_HOSTNAME` で上書きできます。 ### 広域（DNS-SD） @@ -3316,7 +3318,7 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 } ``` -`~/.openclaw/dns/` 配下にユニキャスト DNS-SD zone を書き込みます。ネットワーク間 discovery には、DNS サーバー（推奨: CoreDNS）+ Tailscale split DNS と組み合わせてください。 +`~/.openclaw/dns/` 配下にユニキャスト DNS-SD zone を書き込みます。ネットワークをまたぐ discovery には、DNS サーバー（CoreDNS 推奨）+ Tailscale split DNS と組み合わせてください。 セットアップ: `openclaw dns setup --apply`。 @@ -3324,7 +3326,7 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 ## Environment -### `env`（インライン env vars） +### `env`（インライン環境変数） ```json5 { @@ -3341,14 +3343,14 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 } ``` -- インライン env vars は、プロセス env にそのキーが存在しない場合にのみ適用されます。 -- `.env` ファイル: カレントディレクトリの `.env` + `~/.openclaw/.env`（どちらも既存の変数は上書きしません）。 -- `shellEnv`: ログイン shell プロファイルから、足りない想定キーを取り込みます。 +- インライン環境変数は、プロセス環境にそのキーが存在しない場合にのみ適用されます。 +- `.env` ファイル: CWD の `.env` + `~/.openclaw/.env`（どちらも既存の変数を上書きしません）。 +- `shellEnv`: login shell profile から不足している想定キーを取り込みます。 - 完全な優先順位は [Environment](/ja-JP/help/environment) を参照してください。 -### Env var 置換 +### 環境変数置換 -任意の設定文字列で `${VAR_NAME}` を使って env vars を参照できます: +任意の config 文字列内で `${VAR_NAME}` により環境変数を参照できます: ```json5 { @@ -3358,20 +3360,20 @@ Auth: `Authorization: Bearer ` または `x-openclaw-token: `。 } ``` -- 一致するのは大文字名のみです: `[A-Z_][A-Z0-9_]*`。 -- 変数が欠落している、または空の場合、設定読み込み時にエラーになります。 -- リテラルの `${VAR}` にするには `$${VAR}` でエスケープしてください。 +- 一致するのは大文字名のみ: `[A-Z_][A-Z0-9_]*`。 +- 欠落または空の変数は config 読み込み時にエラーになります。 +- リテラルの `${VAR}` にするには `$${VAR}` でエスケープします。 - `$include` でも動作します。 --- ## Secrets -Secret refs は加算的です。プレーンテキスト値も引き続き使えます。 +SecretRef は追加的です。平文値も引き続き使用できます。 ### `SecretRef` -次の 1 つのオブジェクト形を使います: +1 つのオブジェクト形状を使用します: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3383,13 +3385,13 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 - `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 には、`.` または `..` のスラッシュ区切りパスセグメントを含めてはいけません（例: `a/../b` は拒否されます） +- `source: "exec"` の id には、`.` または `..` のスラッシュ区切り path セグメントを含めてはいけません（例: `a/../b` は拒否されます） -### サポートされる認証情報サーフェス +### 対応する資格情報サーフェス -- 正規の一覧: [SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface) -- `secrets apply` は、サポートされる `openclaw.json` の認証情報パスを対象にします。 -- `auth-profiles.json` の refs もランタイム解決と監査対象に含まれます。 +- 正規の対応表: [SecretRef Credential Surface](/ja-JP/reference/secretref-credential-surface) +- `secrets apply` は、対応する `openclaw.json` 資格情報パスを対象にします。 +- `auth-profiles.json` の ref も runtime 解決と audit 対象に含まれます。 ### Secret provider 設定 @@ -3397,7 +3399,7 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 { secrets: { providers: { - default: { source: "env" }, // 任意の明示的 env provider + default: { source: "env" }, // optional explicit env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3423,11 +3425,11 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 - `file` provider は `mode: "json"` と `mode: "singleValue"` をサポートします（singleValue mode では `id` は `"value"` でなければなりません）。 - `exec` provider には絶対 `command` パスが必要で、stdin/stdout 上のプロトコル payload を使用します。 -- デフォルトでは symlink の command パスは拒否されます。解決後のターゲットパスを検証しつつ symlink パスを許可するには `allowSymlinkCommand: true` を設定してください。 +- デフォルトでは symlink command path は拒否されます。解決後のターゲットパスを検証しつつ symlink path を許可するには `allowSymlinkCommand: true` を設定してください。 - `trustedDirs` が設定されている場合、trusted-dir チェックは解決後のターゲットパスに適用されます。 -- `exec` 子プロセス環境はデフォルトで最小限です。必要な変数は `passEnv` で明示的に渡してください。 -- Secret refs は有効化時にメモリ内スナップショットへ解決され、その後のリクエストパスはそのスナップショットだけを読みます。 -- アクティブサーフェスフィルタリングは有効化中に適用されます。有効なサーフェス上の未解決 refs は起動/リロードを失敗させ、非アクティブなサーフェスは診断付きでスキップされます。 +- `exec` 子環境はデフォルトで最小限です。必要な変数は `passEnv` で明示的に渡してください。 +- Secret ref は有効化時にメモリ内 snapshot へ解決され、その後の request パスは snapshot のみを読み取ります。 +- 有効サーフェスのフィルタリングは有効化中に適用されます。有効なサーフェス上の未解決 ref は起動/reload を失敗させ、非アクティブなサーフェスは diagnostics 付きでスキップされます。 --- @@ -3449,13 +3451,13 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 } ``` -- agent ごとの profiles は `/auth-profiles.json` に保存されます。 -- `auth-profiles.json` は、静的認証モード用の値レベル refs（`api_key` には `keyRef`、`token` には `tokenRef`）をサポートします。 -- OAuth モード profile（`auth.profiles..mode = "oauth"`）は、SecretRef バックの auth-profile 認証情報をサポートしません。 -- 静的ランタイム認証情報はメモリ内の解決済みスナップショットから取得され、従来の静的 `auth.json` エントリは見つかると除去されます。 -- 従来の OAuth インポート元は `~/.openclaw/credentials/oauth.json` です。 +- 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 されます。 - [OAuth](/ja-JP/concepts/oauth) を参照してください。 -- Secrets ランタイム動作と `audit/configure/apply` ツール群: [Secrets Management](/ja-JP/gateway/secrets)。 +- Secrets runtime の動作と `audit/configure/apply` ツール: [Secrets Management](/ja-JP/gateway/secrets)。 ### `auth.cooldowns` @@ -3478,20 +3480,20 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 ``` - `billingBackoffHours`: 真の - billing/insufficient-credit エラーで profile が失敗したときの基本バックオフ時間（時）（デフォルト: `5`）。明示的な billing テキストは - `401`/`403` 応答でもここに入ることがありますが、provider 固有のテキスト - マッチャーはその provider に属するものだけに限定されます（例: OpenRouter の + billing/クレジット不足エラーにより profile が失敗したときの、時間単位の基本バックオフ + （デフォルト: `5`）。`401`/`403` 応答でも明示的な billing 文言があれば + ここに分類されることがありますが、provider 固有の文言 + マッチャーは引き続きその provider に限定されます（たとえば OpenRouter の `Key limit exceeded`）。再試行可能な HTTP `402` の使用量ウィンドウや - organization/workspace 支出上限メッセージは、代わりに `rate_limit` パス - に残ります。 + organization/workspace の支出上限メッセージは、代わりに `rate_limit` パスに留まります。 - `billingBackoffHoursByProvider`: billing バックオフ時間の任意の provider ごとの上書き。 -- `billingMaxHours`: billing バックオフ指数増加の上限時間（時）（デフォルト: `24`）。 -- `authPermanentBackoffMinutes`: 高信頼の `auth_permanent` 失敗に対する基本バックオフ時間（分）（デフォルト: `10`）。 -- `authPermanentMaxMinutes`: `auth_permanent` バックオフ増加の上限時間（分）（デフォルト: `60`）。 -- `failureWindowHours`: バックオフカウンターに使うローリングウィンドウ時間（時）（デフォルト: `24`）。 -- `overloadedProfileRotations`: overloaded エラーで model フォールバックに切り替える前に行う、同一 provider 内 auth-profile ローテーションの最大回数（デフォルト: `1`）。`ModelNotReadyException` のような provider busy 形状はここに入ります。 -- `overloadedBackoffMs`: overloaded な provider/profile ローテーションを再試行する前の固定遅延（デフォルト: `0`）。 -- `rateLimitedProfileRotations`: rate-limit エラーで model フォールバックに切り替える前に行う、同一 provider 内 auth-profile ローテーションの最大回数（デフォルト: `1`）。その rate-limit バケットには、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` のような 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 形状の文言も含まれます。 --- @@ -3512,8 +3514,8 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 - デフォルトのログファイル: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 安定したパスにするには `logging.file` を設定してください。 -- `consoleLevel` は `--verbose` で `debug` に上がります。 -- `maxFileBytes`: 書き込みを抑止する前の最大ログファイルサイズ（バイト）（正の整数。デフォルト: `524288000` = 500 MB）。本番デプロイでは外部ログローテーションを使ってください。 +- `consoleLevel` は `--verbose` 時に `debug` へ上がります。 +- `maxFileBytes`: 書き込みを抑止する前の最大ログファイルサイズ（バイト、正の整数、デフォルト: `524288000` = 500 MB）。production デプロイでは外部ログローテーションを使用してください。 --- @@ -3550,20 +3552,20 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 } ``` -- `enabled`: 計装出力のマスタートグルです（デフォルト: `true`）。 -- `flags`: 対象を絞ったログ出力を有効にするフラグ文字列の配列です（`"telegram.*"` や `"*"` のようなワイルドカードをサポートします）。 -- `stuckSessionWarnMs`: session が処理中状態のままの間に stuck-session 警告を出すための経過時間しきい値（ms）。 +- `enabled`: instrumentation 出力のマスタートグルです（デフォルト: `true`）。 +- `flags`: 対象を絞ったログ出力を有効にするフラグ文字列の配列です（`"telegram.*"` や `"*"` のようなワイルドカードをサポート）。 +- `stuckSessionWarnMs`: session が processing 状態のままの間に stuck-session 警告を出すための経過しきい値（ms）。 - `otel.enabled`: OpenTelemetry エクスポートパイプラインを有効にします（デフォルト: `false`）。 -- `otel.endpoint`: OTel エクスポート用の collector URL。 +- `otel.endpoint`: OTel エクスポート先 collector の URL。 - `otel.protocol`: `"http/protobuf"`（デフォルト）または `"grpc"`。 -- `otel.headers`: OTel エクスポートリクエストとともに送信される追加の HTTP/gRPC メタデータヘッダー。 -- `otel.serviceName`: リソース属性用のサービス名。 -- `otel.traces` / `otel.metrics` / `otel.logs`: trace、metrics、または log エクスポートを有効にします。 +- `otel.headers`: OTel エクスポート要求とともに送られる追加の HTTP/gRPC メタデータヘッダー。 +- `otel.serviceName`: resource 属性用の service 名。 +- `otel.traces` / `otel.metrics` / `otel.logs`: trace、metrics、または log のエクスポートを有効にします。 - `otel.sampleRate`: trace サンプリング率 `0`–`1`。 -- `otel.flushIntervalMs`: 定期テレメトリ flush 間隔（ms）。 -- `cacheTrace.enabled`: 埋め込み実行の cache trace スナップショットを記録します（デフォルト: `false`）。 +- `otel.flushIntervalMs`: 定期的な telemetry flush 間隔（ms）。 +- `cacheTrace.enabled`: embedded 実行用の cache trace snapshot をログに出力します（デフォルト: `false`）。 - `cacheTrace.filePath`: cache trace JSONL の出力パス（デフォルト: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: cache trace 出力に何を含めるかを制御します（すべてデフォルトは `true`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: cache trace 出力に何を含めるかを制御します（すべてデフォルト: `true`）。 --- @@ -3585,12 +3587,12 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 } ``` -- `channel`: npm/git インストール用のリリース channel — `"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`）。 +- `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`）。 --- @@ -3624,21 +3626,21 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 ``` - `enabled`: グローバル ACP 機能ゲート（デフォルト: `false`）。 -- `dispatch.enabled`: ACP session ターンディスパッチ用の独立したゲート（デフォルト: `true`）。ACP コマンドは利用可能なまま実行だけをブロックしたい場合は `false` に設定します。 -- `backend`: デフォルト ACP ランタイムバックエンド id（登録済み ACP ランタイム Plugin と一致している必要があります）。 -- `defaultAgent`: spawn 時に明示的なターゲットが指定されない場合のフォールバック ACP ターゲット agent id。 -- `allowedAgents`: ACP ランタイム session に許可される agent id の allowlist。空の場合は追加制限なしを意味します。 -- `maxConcurrentSessions`: 同時にアクティブになれる ACP session の最大数。 -- `stream.coalesceIdleMs`: ストリーミング text 用のアイドル flush ウィンドウ（ms）。 -- `stream.maxChunkChars`: ストリーミングされたブロック投影を分割する前の最大チャンクサイズ。 -- `stream.repeatSuppression`: ターンごとの繰り返し status/tool 行を抑制します（デフォルト: `true`）。 -- `stream.deliveryMode`: `"live"` は段階的にストリーミングし、`"final_only"` はターン終端イベントまでバッファリングします。 -- `stream.hiddenBoundarySeparator`: 非表示 tool イベントの後、可視 text の前に入れる区切り（デフォルト: `"paragraph"`）。 -- `stream.maxOutputChars`: ACP ターンごとに投影される assistant 出力文字数の上限。 +- `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。空は追加制限なしを意味します。 +- `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.maxSessionUpdateChars`: 投影される ACP status/update 行の最大文字数。 -- `stream.tagVisibility`: ストリーミングイベント用のタグ名から boolean 可視性オーバーライドへの記録。 -- `runtime.ttlMinutes`: クリーンアップ対象になるまでの ACP session worker のアイドル TTL（分）。 -- `runtime.installCommand`: ACP ランタイム環境をブートストラップするときに実行する任意の install コマンド。 +- `stream.tagVisibility`: ストリームイベント用のタグ名から boolean 可視性オーバーライドへの記録。 +- `runtime.ttlMinutes`: ACP session worker がクリーンアップ対象になるまでのアイドル TTL（分）。 +- `runtime.installCommand`: ACP runtime 環境を bootstrap する際に実行する任意の install コマンド。 --- @@ -3654,11 +3656,11 @@ Secret refs は加算的です。プレーンテキスト値も引き続き使 } ``` -- `cli.banner.taglineMode` はバナーのタグラインスタイルを制御します: - - `"random"`（デフォルト）: ローテーションする面白い/季節限定タグライン。 - - `"default"`: 固定の中立タグライン（`All your chats, one OpenClaw.`）。 - - `"off"`: タグラインテキストなし（バナーのタイトル/バージョンは引き続き表示）。 -- バナー全体を隠すには（タグラインだけでなく）、env `OPENCLAW_HIDE_BANNER=1` を設定してください。 +- `cli.banner.taglineMode` は banner の tagline スタイルを制御します: + - `"random"`（デフォルト）: ローテーションする面白い/季節ネタの tagline。 + - `"default"`: 固定の中立な tagline（`All your chats, one OpenClaw.`）。 + - `"off"`: tagline テキストなし（banner のタイトル/バージョンは引き続き表示）。 +- banner 全体を隠すには（tagline だけでなく）、環境変数 `OPENCLAW_HIDE_BANNER=1` を設定してください。 --- @@ -3682,15 +3684,15 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d ## Identity -[Agent のデフォルト設定](#agent-defaults) の `agents.list` identity フィールドを参照してください。 +[Agent のデフォルト](#agent-defaults) の `agents.list` identity フィールドを参照してください。 --- -## Bridge（legacy、削除済み） +## Bridge（従来、削除済み） -現在のビルドには TCP bridge は含まれていません。Nodes は Gateway WebSocket 経由で接続します。`bridge.*` キーはもはや設定 schema の一部ではありません（削除するまで検証は失敗します。`openclaw doctor --fix` で不明キーを除去できます）。 +現在の build には TCP bridge は含まれていません。Node は Gateway WebSocket 経由で接続します。`bridge.*` キーはもはや config schema の一部ではありません（削除するまで検証は失敗します。`openclaw doctor --fix` で未知キーを除去できます）。 - + ```json { @@ -3717,22 +3719,22 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 非推奨: 保存済み notify:true ジョブ用のフォールバック - webhookToken: "replace-with-dedicated-token", // 任意: outbound webhook auth 用 bearer token - sessionRetention: "24h", // duration 文字列または false + 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 runLog: { - maxBytes: "2mb", // デフォルト 2_000_000 bytes - keepLines: 2000, // デフォルト 2000 + maxBytes: "2mb", // default 2_000_000 bytes + keepLines: 2000, // default 2000 }, }, } ``` -- `sessionRetention`: 完了済みの isolated cron 実行 session を `sessions.json` から pruning するまで保持する期間です。アーカイブされた削除済み cron transcript のクリーンアップも制御します。デフォルト: `24h`。無効にするには `false` を設定します。 -- `runLog.maxBytes`: pruning 前の実行ログファイルごとの最大サイズ（`cron/runs/.jsonl`）。デフォルト: `2_000_000` bytes。 -- `runLog.keepLines`: 実行ログの pruning が発動したときに保持される最新行数。デフォルト: `2000`。 -- `webhookToken`: cron webhook POST 配信（`delivery.mode = "webhook"`）に使う bearer token。省略した場合、auth ヘッダーは送信されません。 -- `webhook`: 非推奨の従来フォールバック webhook URL（http/https）。まだ `notify: true` を持つ保存済みジョブにのみ使われます。 +- `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` を持つ保存済みジョブにのみ使用されます。 ### `cron.retry` @@ -3748,11 +3750,11 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d } ``` -- `maxAttempts`: 一過性エラー時の one-shot ジョブに対する最大 retry 回数（デフォルト: `3`、範囲: `0`–`10`）。 -- `backoffMs`: 各 retry 試行に対する backoff 遅延（ms）の配列（デフォルト: `[30000, 60000, 300000]`、1〜10 エントリ）。 -- `retryOn`: retry を引き起こすエラー種別 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略した場合、すべての一過性エラー種別を retry します。 +- `maxAttempts`: 一過性エラー時に one-shot ジョブで行う最大リトライ回数（デフォルト: `3`、範囲: `0`–`10`）。 +- `backoffMs`: 各リトライ試行のバックオフ遅延（ms）の配列（デフォルト: `[30000, 60000, 300000]`、1–10 エントリ）。 +- `retryOn`: リトライを引き起こすエラー種別 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略すると、すべての一過性種別をリトライします。 -これは one-shot cron ジョブにのみ適用されます。定期ジョブでは別の失敗処理が使われます。 +これは one-shot cron ジョブにのみ適用されます。定期実行ジョブでは別の失敗処理を使用します。 ### `cron.failureAlert` @@ -3770,11 +3772,11 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d } ``` -- `enabled`: cron ジョブの失敗アラートを有効にします（デフォルト: `false`）。 -- `after`: アラート発火までの連続失敗回数（正の整数、最小: `1`）。 -- `cooldownMs`: 同じジョブに対して繰り返しアラートを出すまでの最小間隔（ミリ秒）（非負整数）。 +- `enabled`: cron ジョブの failure alert を有効にします（デフォルト: `false`）。 +- `after`: alert が発火するまでの連続失敗回数（正の整数、最小: `1`）。 +- `cooldownMs`: 同じジョブに対する alert の再送までの最小間隔（ms、非負整数）。 - `mode`: 配信モード — `"announce"` は channel メッセージで送信し、`"webhook"` は設定済み webhook に POST します。 -- `accountId`: アラート配信のスコープを絞る任意の account または channel id。 +- `accountId`: alert 配信先のスコープを限定する任意の account または channel id。 ### `cron.failureDestination` @@ -3791,16 +3793,16 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d } ``` -- すべてのジョブに共通する、cron 失敗通知のデフォルト送信先です。 +- すべてのジョブに共通する、cron failure 通知のデフォルト送信先です。 - `mode`: `"announce"` または `"webhook"`。十分なターゲットデータが存在する場合、デフォルトは `"announce"` です。 -- `channel`: announce 配信用の channel オーバーライド。`"last"` は最後に使われた配信 channel を再利用します。 +- `channel`: announce 配信時の channel オーバーライド。`"last"` は最後にわかっている配信 channel を再利用します。 - `to`: 明示的な announce ターゲットまたは webhook URL。webhook mode では必須です。 -- `accountId`: 配信用の任意の account オーバーライド。 -- ジョブごとの `delivery.failureDestination` はこのグローバルデフォルトを上書きします。 -- グローバルにもジョブごとにも失敗送信先が設定されていない場合、すでに `announce` で配信するジョブは、失敗時にそのプライマリ announce ターゲットへフォールバックします。 -- `delivery.failureDestination` は、ジョブのプライマリ `delivery.mode` が `"webhook"` の場合を除き、`sessionTarget="isolated"` ジョブでのみサポートされます。 +- `accountId`: 配信の任意 account オーバーライド。 +- ジョブごとの `delivery.failureDestination` は、このグローバルデフォルトを上書きします。 +- グローバルにもジョブごとにも failure destination が設定されていない場合、すでに `announce` で配信しているジョブは、失敗時にその primary announce ターゲットへフォールバックします。 +- `delivery.failureDestination` は、ジョブの primary `delivery.mode` が `"webhook"` である場合を除き、`sessionTarget="isolated"` ジョブでのみサポートされます。 -[Cron Jobs](/ja-JP/automation/cron-jobs) を参照してください。isolated cron 実行は [background tasks](/ja-JP/automation/tasks) として追跡されます。 +[Cron Jobs](/ja-JP/automation/cron-jobs) を参照してください。分離された cron 実行は [background tasks](/ja-JP/automation/tasks) として追跡されます。 --- @@ -3808,34 +3810,34 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d `tools.media.models[].args` で展開されるテンプレートプレースホルダー: -| 変数 | 説明 | -| ------------------ | ----------------------------------------- | -| `{{Body}}` | 受信メッセージ本文全体 | -| `{{RawBody}}` | 生の本文（履歴/送信者ラッパーなし） | -| `{{BodyStripped}}` | グループメンションを除去した本文 | -| `{{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}}` | グループ件名（ベストエフォート） | -| `{{GroupMembers}}` | グループメンバーのプレビュー（ベストエフォート） | -| `{{SenderName}}` | 送信者表示名（ベストエフォート） | -| `{{SenderE164}}` | 送信者電話番号（ベストエフォート） | +| 変数 | 説明 | +| ------------------ | ---------------------------------------------- | +| `{{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） | | `{{Provider}}` | provider ヒント（whatsapp、telegram、discord など） | --- ## Config include（`$include`） -設定を複数ファイルに分割できます: +config を複数ファイルに分割します: ```json5 // ~/.openclaw/openclaw.json @@ -3851,11 +3853,11 @@ CLI のガイド付きセットアップフロー（`onboard`、`configure`、`d **マージ動作:** - 単一ファイル: そのオブジェクト全体を置き換えます。 -- ファイル配列: 順番に deep merge されます（後ろのものが前を上書き）。 -- 同階層キー: include の後にマージされます（include された値を上書き）。 -- ネストした include: 最大 10 レベル。 -- パス: include 元ファイルからの相対で解決されますが、トップレベル設定ディレクトリ（`openclaw.json` の `dirname`）内に収まっている必要があります。絶対パスや `../` 形式も、最終的にその境界内に解決される場合にのみ許可されます。 -- エラー: 欠落ファイル、解析エラー、循環 include に対して明確なメッセージが出ます。 +- ファイル配列: 順番に deep-merge されます（後のものが前のものを上書き）。 +- sibling キー: include 後にマージされます（include された値を上書き）。 +- ネストした include: 最大 10 レベルまで。 +- パス: include 元ファイルを基準に解決されますが、トップレベル config ディレクトリ（`openclaw.json` の `dirname`）の内側に留まる必要があります。絶対パス/`../` 形式も、その境界内に解決される場合にのみ許可されます。 +- エラー: 欠落ファイル、parse エラー、循環 include に対して明確なメッセージが出ます。 --- diff --git a/docs/ja-JP/gateway/protocol.md b/docs/ja-JP/gateway/protocol.md index 03aa95058..faef690b2 100644 --- a/docs/ja-JP/gateway/protocol.md +++ b/docs/ja-JP/gateway/protocol.md @@ -2,26 +2,26 @@ read_when: - Gateway WSクライアントの実装または更新 - プロトコルの不一致や接続失敗のデバッグ - - プロトコルスキーマ/モデルの再生成 -summary: 'Gateway WebSocketプロトコル: ハンドシェイク、フレーム、バージョニング' + - プロトコルスキーマ／モデルの再生成 +summary: Gateway WebSocketプロトコル：ハンドシェイク、フレーム、バージョニング title: Gatewayプロトコル x-i18n: - generated_at: "2026-04-16T04:44:16Z" + generated_at: "2026-04-18T04:40:12Z" model: gpt-5.4 provider: openai - source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3 + source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41 source_path: gateway/protocol.md workflow: 15 --- # Gatewayプロトコル（WebSocket） -Gateway WSプロトコルは、OpenClawの**単一のコントロールプレーン + ノード転送**です。すべてのクライアント（CLI、web UI、macOSアプリ、iOS/Androidノード、ヘッドレスノード）はWebSocket経由で接続し、ハンドシェイク時に自身の**role** + **scope**を宣言します。 +Gateway WSプロトコルは、OpenClawの**単一のコントロールプレーン + Nodeトランスポート**です。すべてのクライアント（CLI、Web UI、macOSアプリ、iOS/Android Node、ヘッドレスNode）はWebSocket経由で接続し、ハンドシェイク時に自身の**role** + **scope**を宣言します。 -## 転送 +## トランスポート -- WebSocket、JSONペイロードのテキストフレーム。 -- 最初のフレームは**必ず**`connect`リクエストでなければなりません。 +- WebSocket、JSONペイロードを持つテキストフレーム。 +- 最初のフレームは**必ず**`connect`リクエストである必要があります。 ## ハンドシェイク（connect） @@ -92,9 +92,20 @@ Gateway → Client: } ``` -`server`、`features`、`snapshot`、`policy`はすべてスキーマ（`src/gateway/protocol/schema/frames.ts`）で必須です。`auth`と`canvasHostUrl`は任意です。 +`server`、`features`、`snapshot`、`policy`はすべてスキーマ（`src/gateway/protocol/schema/frames.ts`）で必須です。`canvasHostUrl`は任意です。`auth`は利用可能な場合にネゴシエートされたrole/scopesを報告し、Gatewayが発行した場合は`deviceToken`も含みます。 -デバイストークンが発行される場合、`hello-ok`には次も含まれます: +デバイストークンが発行されない場合でも、`hello-ok.auth`はネゴシエートされた権限を報告できます。 + +```json +{ + "auth": { + "role": "operator", + "scopes": ["operator.read", "operator.write"] + } +} +``` + +デバイストークンが発行された場合、`hello-ok`には次も含まれます。 ```json { @@ -106,7 +117,7 @@ Gateway → Client: } ``` -信頼済みブートストラップのハンドオフ中、`hello-ok.auth`には`deviceTokens`内に追加の制限付きroleエントリが含まれる場合もあります: +信頼されたブートストラップのハンドオフ中、`hello-ok.auth`には`deviceTokens`内に追加の境界付きroleエントリが含まれることもあります。 ```json { @@ -125,7 +136,7 @@ Gateway → Client: } ``` -組み込みのnode/operatorブートストラップフローでは、主要なnodeトークンは`scopes: []`のままであり、引き渡されるoperatorトークンはブートストラップoperator allowlist（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）に制限されたままです。ブートストラップのscopeチェックはroleプレフィックス付きのままです。operatorエントリはoperatorリクエストのみを満たし、operator以外のroleでも引き続き自身のroleプレフィックス配下のscopeが必要です。 +組み込みのnode/operatorブートストラップフローでは、プライマリNodeトークンは`scopes: []`のままで、ハンドオフされたoperatorトークンはブートストラップoperator許可リスト（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）に制限されたままです。ブートストラップscopeチェックは引き続きroleプレフィックス付きです。operatorエントリはoperatorリクエストのみを満たし、非operatorロールは引き続き自身のroleプレフィックス配下のscopeを必要とします。 ### Nodeの例 @@ -164,18 +175,18 @@ Gateway → Client: ## フレーミング -- **リクエスト**: `{type:"req", id, method, params}` -- **レスポンス**: `{type:"res", id, ok, payload|error}` -- **イベント**: `{type:"event", event, payload, seq?, stateVersion?}` +- **Request**: `{type:"req", id, method, params}` +- **Response**: `{type:"res", id, ok, payload|error}` +- **Event**: `{type:"event", event, payload, seq?, stateVersion?}` -副作用を持つメソッドには**idempotency keys**が必要です（スキーマを参照）。 +副作用を伴うメソッドには**冪等性キー**が必要です（スキーマを参照）。 ## Roles + scopes ### Roles -- `operator` = コントロールプレーンクライアント（CLI/UI/automation）。 -- `node` = capabilityホスト（camera/screen/canvas/system.run）。 +- `operator` = コントロールプレーンクライアント（CLI/UI/自動化）。 +- `node` = 機能ホスト（camera/screen/canvas/system.run）。 ### Scopes（operator） @@ -188,153 +199,152 @@ Gateway → Client: - `operator.pairing` - `operator.talk.secrets` -`includeSecrets: true`を指定した`talk.config`には`operator.talk.secrets`（または`operator.admin`）が必要です。 +`includeSecrets: true`を伴う`talk.config`には`operator.talk.secrets`（または`operator.admin`）が必要です。 -Plugin登録済みのGateway RPCメソッドは独自のoperator scopeを要求できますが、予約済みのコア管理プレフィックス（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は常に`operator.admin`に解決されます。 +Plugin登録されたGateway RPCメソッドは独自のoperator scopeを要求できますが、予約済みのコア管理プレフィックス（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は常に`operator.admin`に解決されます。 -メソッドscopeは最初のゲートにすぎません。`chat.send`経由で到達する一部のスラッシュコマンドには、その上により厳しいコマンドレベルのチェックが適用されます。たとえば、永続的な`/config set`と`/config unset`の書き込みには`operator.admin`が必要です。 +メソッドscopeは最初のゲートにすぎません。`chat.send`経由で到達する一部のスラッシュコマンドには、その上により厳しいコマンドレベルのチェックが適用されます。たとえば、永続的な`/config set`および`/config unset`の書き込みには`operator.admin`が必要です。 -`node.pair.approve`にも、ベースのメソッドscopeに加えて追加の承認時scopeチェックがあります: +`node.pair.approve`にも、ベースメソッドscopeに加えて追加の承認時scopeチェックがあります。 - コマンドなしのリクエスト: `operator.pairing` -- exec以外のnodeコマンドを含むリクエスト: `operator.pairing` + `operator.write` -- `system.run`、`system.run.prepare`、または`system.which`を含むリクエスト: - `operator.pairing` + `operator.admin` +- non-exec Nodeコマンドを含むリクエスト: `operator.pairing` + `operator.write` +- `system.run`、`system.run.prepare`、または`system.which`を含むリクエスト: `operator.pairing` + `operator.admin` ### Caps/commands/permissions（node） -ノードは接続時にcapabilityクレームを宣言します: +Nodeは接続時に機能クレームを宣言します。 -- `caps`: 高レベルのcapabilityカテゴリ。 -- `commands`: invoke用のコマンドallowlist。 -- `permissions`: 細かなトグル（例: `screen.record`、`camera.capture`）。 +- `caps`: 高レベルな機能カテゴリ。 +- `commands`: invoke用のコマンド許可リスト。 +- `permissions`: 細粒度のトグル（例: `screen.record`、`camera.capture`）。 -Gatewayはこれらを**クレーム**として扱い、サーバー側allowlistを適用します。 +Gatewayはこれらを**クレーム**として扱い、サーバー側の許可リストを強制します。 ## プレゼンス -- `system-presence`は、デバイスIDをキーとしたエントリを返します。 -- プレゼンスエントリには`deviceId`、`roles`、`scopes`が含まれるため、UIはそのデバイスが**operator**と**node**の両方として接続している場合でも、デバイスごとに1行で表示できます。 +- `system-presence`はデバイスIDをキーとするエントリを返します。 +- プレゼンスエントリには`deviceId`、`roles`、`scopes`が含まれるため、UIは**operator**と**node**の両方として接続している場合でも、デバイスごとに1行で表示できます。 -## 一般的なRPCメソッドファミリー +## 一般的なRPCメソッド群 -このページは生成された完全ダンプではありませんが、公開WSサーフェスは上記のハンドシェイク/認証の例よりも広範です。現在Gatewayが公開している主要なメソッドファミリーは以下です。 +このページは生成された完全なダンプではありませんが、公開WSサーフェスは上記のハンドシェイク/認証の例よりも広範です。以下は、Gatewayが現在公開している主なメソッド群です。 -`hello-ok.features.methods`は、`src/gateway/server-methods-list.ts`とロード済みplugin/channelのメソッドエクスポートから構築される保守的なディスカバリー一覧です。これを機能ディスカバリーとして扱ってください。`src/gateway/server-methods/*.ts`に実装されている呼び出し可能なすべてのヘルパーの生成ダンプではありません。 +`hello-ok.features.methods`は、`src/gateway/server-methods-list.ts`とロードされたplugin/channelのメソッドexportから構築された保守的な検出リストです。これを機能検出として扱ってください。`src/gateway/server-methods/*.ts`で実装されているすべての呼び出し可能ヘルパーの生成ダンプではありません。 -### Systemとidentity +### システムとID -- `health`は、キャッシュ済みまたは新たにプローブされたgateway healthスナップショットを返します。 -- `status`は`/status`形式のgatewayサマリーを返します。機密フィールドは、admin scopeを持つoperatorクライアントにのみ含まれます。 -- `gateway.identity.get`は、relayおよびpairingフローで使われるgateway device identityを返します。 -- `system-presence`は、接続中のoperator/nodeデバイスの現在のプレゼンススナップショットを返します。 -- `system-event`はsystem eventを追加し、プレゼンスコンテキストを更新/ブロードキャストできます。 +- `health`は、キャッシュされた、または新たにプローブされたGatewayヘルススナップショットを返します。 +- `status`は`/status`スタイルのGatewayサマリーを返します。機微なフィールドは、admin scopeを持つoperatorクライアントにのみ含まれます。 +- `gateway.identity.get`は、relayおよびpairingフローで使用されるGatewayデバイスIDを返します。 +- `system-presence`は、接続中のoperator/Nodeデバイスの現在のプレゼンススナップショットを返します。 +- `system-event`はシステムイベントを追加し、プレゼンスコンテキストを更新/ブロードキャストできます。 - `last-heartbeat`は、最新の永続化されたHeartbeatイベントを返します。 -- `set-heartbeats`は、Gateway上のHeartbeat処理を切り替えます。 +- `set-heartbeats`は、Gateway上でHeartbeat処理を切り替えます。 -### Modelsとusage +### モデルと使用状況 -- `models.list`は、実行時に許可されたモデルカタログを返します。 +- `models.list`は、ランタイムで許可されたモデルカタログを返します。 - `usage.status`は、プロバイダー使用量ウィンドウ/残りクォータのサマリーを返します。 -- `usage.cost`は、日付範囲に対する集計済みコスト使用量サマリーを返します。 -- `doctor.memory.status`は、アクティブなデフォルトagent workspaceにおけるvector-memory / embeddingの準備状況を返します。 +- `usage.cost`は、日付範囲の集計コスト使用量サマリーを返します。 +- `doctor.memory.status`は、アクティブなデフォルトエージェントワークスペースのベクトルメモリ/埋め込み準備状況を返します。 - `sessions.usage`は、セッションごとの使用量サマリーを返します。 - `sessions.usage.timeseries`は、1つのセッションの時系列使用量を返します。 - `sessions.usage.logs`は、1つのセッションの使用量ログエントリを返します。 -### Channelsとloginヘルパー +### Channelsとログインヘルパー -- `channels.status`は、組み込み + バンドル済みchannel/pluginのステータスサマリーを返します。 -- `channels.logout`は、そのchannelがlogoutをサポートしている場合に特定のchannel/accountをlogoutします。 -- `web.login.start`は、現在のQR対応web channel providerのQR/web loginフローを開始します。 -- `web.login.wait`は、そのQR/web loginフローの完了を待ち、成功時にchannelを開始します。 -- `push.test`は、登録済みiOS nodeにテストAPNs pushを送信します。 +- `channels.status`は、組み込み + バンドルされたchannel/pluginのステータスサマリーを返します。 +- `channels.logout`は、そのchannelがログアウトをサポートしている場合に、特定のchannel/accountをログアウトします。 +- `web.login.start`は、現在のQR対応web channel providerに対するQR/webログインフローを開始します。 +- `web.login.wait`は、そのQR/webログインフローの完了を待機し、成功時にchannelを開始します。 +- `push.test`は、登録済みのiOS NodeにテストAPNsプッシュを送信します。 - `voicewake.get`は、保存されているウェイクワードトリガーを返します。 - `voicewake.set`は、ウェイクワードトリガーを更新し、変更をブロードキャストします。 -### Messagingとlogs +### メッセージングとログ -- `send`は、chat runner外でchannel/account/threadを対象にした送信を行う、直接のアウトバウンド配信RPCです。 -- `logs.tail`は、カーソル/制限および最大バイト制御付きで、設定済みgateway file-log tailを返します。 +- `send`は、chat runnerの外側でchannel/account/threadターゲット宛て送信を行うための直接の送信RPCです。 +- `logs.tail`は、設定されたGatewayファイルログの末尾を、cursor/limitおよびmax-byte制御付きで返します。 ### TalkとTTS - `talk.config`は、有効なTalk設定ペイロードを返します。`includeSecrets`には`operator.talk.secrets`（または`operator.admin`）が必要です。 -- `talk.mode`は、WebChat/Control UIクライアント向けに現在のTalkモード状態を設定/ブロードキャストします。 -- `talk.speak`は、アクティブなTalk speech providerを通じて音声合成します。 -- `tts.status`は、TTSの有効状態、アクティブなprovider、フォールバックprovider、およびprovider config状態を返します。 -- `tts.providers`は、表示可能なTTS provider一覧を返します。 +- `talk.mode`は、WebChat/Control UIクライアント向けの現在のTalk mode状態を設定/ブロードキャストします。 +- `talk.speak`は、アクティブなTalk speech providerを通じて音声を合成します。 +- `tts.status`は、TTS有効状態、アクティブprovider、フォールバックprovider、およびprovider設定状態を返します。 +- `tts.providers`は、表示可能なTTS providerインベントリを返します。 - `tts.enable`と`tts.disable`は、TTS設定状態を切り替えます。 - `tts.setProvider`は、優先TTS providerを更新します。 - `tts.convert`は、単発のtext-to-speech変換を実行します。 ### Secrets、config、update、wizard -- `secrets.reload`は、アクティブなSecretRefを再解決し、完全に成功した場合にのみ実行時secret状態を切り替えます。 -- `secrets.resolve`は、特定のcommand/targetセットに対するコマンド対象secret割り当てを解決します。 -- `config.get`は、現在のconfigスナップショットとハッシュを返します。 -- `config.set`は、検証済みconfigペイロードを書き込みます。 -- `config.patch`は、部分的なconfig更新をマージします。 -- `config.apply`は、完全なconfigペイロードを検証して置き換えます。 -- `config.schema`は、Control UIとCLIツールで使われるライブconfig schemaペイロードを返します。schema、`uiHints`、version、生成メタデータを含み、実行時にロード可能な場合はplugin + channel schemaメタデータも含みます。このschemaには、nested object、wildcard、array-item、および一致するフィールドドキュメントが存在する場合の`anyOf` / `oneOf` / `allOf`構成分岐を含め、UIで使われる同じラベルとヘルプテキストから導出されたフィールド`title` / `description`メタデータが含まれます。 -- `config.schema.lookup`は、1つのconfig pathに対するpathスコープのlookupペイロードを返します。正規化済みpath、浅いschema node、一致したhint + `hintPath`、およびUI/CLIのドリルダウン用の直下の子サマリーを返します。 - - lookup schema nodeは、ユーザー向けドキュメントと一般的な検証フィールドを保持します: `title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数値/文字列/配列/オブジェクトの制約、および`additionalProperties`、`deprecated`、`readOnly`、`writeOnly`のような真偽値フラグ。 - - 子サマリーは、`key`、正規化済み`path`、`type`、`required`、`hasChildren`、および一致した`hint` / `hintPath`を公開します。 -- `update.run`は、Gateway updateフローを実行し、update自体が成功した場合にのみ再起動をスケジュールします。 -- `wizard.start`、`wizard.next`、`wizard.status`、`wizard.cancel`は、オンボーディングウィザードをWS RPCで公開します。 +- `secrets.reload`は、アクティブなSecretRefを再解決し、完全に成功した場合にのみランタイムのシークレット状態を入れ替えます。 +- `secrets.resolve`は、特定のcommand/targetセットに対するコマンド対象シークレット割り当てを解決します。 +- `config.get`は、現在の設定スナップショットとハッシュを返します。 +- `config.set`は、検証済みの設定ペイロードを書き込みます。 +- `config.patch`は、部分的な設定更新をマージします。 +- `config.apply`は、完全な設定ペイロードを検証して置き換えます。 +- `config.schema`は、Control UIとCLIツールで使用されるライブ設定スキーマペイロードを返します。スキーマ、`uiHints`、バージョン、生成メタデータを含み、ランタイムがロードできる場合はplugin + channelのスキーマメタデータも含みます。このスキーマには、同じラベルとヘルプテキストから導出された`title` / `description`メタデータが含まれ、ネストされたオブジェクト、ワイルドカード、配列項目、および一致するフィールドドキュメントが存在する場合の`anyOf` / `oneOf` / `allOf`構成ブランチも含まれます。 +- `config.schema.lookup`は、1つの設定パスに対するパススコープのlookupペイロードを返します。正規化されたパス、浅いスキーマノード、一致したヒント + `hintPath`、およびUI/CLIドリルダウン用の直下の子サマリーを含みます。 + - Lookupスキーマノードは、ユーザー向けドキュメントと一般的な検証フィールドを保持します。`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数値/文字列/配列/オブジェクトの境界、および`additionalProperties`、`deprecated`、`readOnly`、`writeOnly`などの真偽値フラグです。 + - 子サマリーは、`key`、正規化された`path`、`type`、`required`、`hasChildren`に加えて、一致した`hint` / `hintPath`を公開します。 +- `update.run`は、Gateway更新フローを実行し、更新自体が成功した場合にのみ再起動をスケジュールします。 +- `wizard.start`、`wizard.next`、`wizard.status`、`wizard.cancel`は、WS RPC経由でオンボーディングウィザードを公開します。 ### 既存の主要ファミリー -#### Agentとworkspaceヘルパー +#### Agentとワークスペースのヘルパー - `agents.list`は、設定済みagentエントリを返します。 -- `agents.create`、`agents.update`、`agents.delete`は、agentレコードとworkspace接続を管理します。 -- `agents.files.list`、`agents.files.get`、`agents.files.set`は、agent向けに公開されるブートストラップworkspaceファイルを管理します。 -- `agent.identity.get`は、agentまたはsessionに対する有効なassistant identityを返します。 -- `agent.wait`は、実行の完了を待ち、利用可能であれば終端スナップショットを返します。 +- `agents.create`、`agents.update`、`agents.delete`は、agentレコードとワークスペース配線を管理します。 +- `agents.files.list`、`agents.files.get`、`agents.files.set`は、agentに公開されるブートストラップワークスペースファイルを管理します。 +- `agent.identity.get`は、agentまたはセッションに対する有効なアシスタントIDを返します。 +- `agent.wait`は、実行の完了を待機し、利用可能な場合は終端スナップショットを返します。 -#### Session制御 +#### セッション制御 - `sessions.list`は、現在のセッションインデックスを返します。 - `sessions.subscribe`と`sessions.unsubscribe`は、現在のWSクライアントに対するセッション変更イベント購読を切り替えます。 - `sessions.messages.subscribe`と`sessions.messages.unsubscribe`は、1つのセッションに対するtranscript/messageイベント購読を切り替えます。 -- `sessions.preview`は、特定のセッションキーに対する制限付きtranscriptプレビューを返します。 +- `sessions.preview`は、特定のセッションキーに対する境界付きtranscriptプレビューを返します。 - `sessions.resolve`は、セッションターゲットを解決または正規化します。 - `sessions.create`は、新しいセッションエントリを作成します。 - `sessions.send`は、既存のセッションにメッセージを送信します。 -- `sessions.steer`は、アクティブなセッション向けの割り込みして方向付けるバリアントです。 -- `sessions.abort`は、セッションのアクティブな処理を中止します。 +- `sessions.steer`は、アクティブなセッションに対する割り込みとsteerのバリアントです。 +- `sessions.abort`は、セッションのアクティブな作業を中止します。 - `sessions.patch`は、セッションメタデータ/オーバーライドを更新します。 - `sessions.reset`、`sessions.delete`、`sessions.compact`は、セッションメンテナンスを実行します。 -- `sessions.get`は、保存されている完全なセッション行を返します。 -- chat実行では引き続き`chat.history`、`chat.send`、`chat.abort`、`chat.inject`を使います。 -- `chat.history`は、UIクライアント向けに表示用に正規化されています。visible textからインラインdirectiveタグが削除され、プレーンテキストのtool-call XMLペイロード（`...`、`...`、`...`、`...`、および切り詰められたtool-callブロックを含む）と、漏れたASCII/全角のmodel control tokenが削除され、完全にsilent-tokenだけのassistant行（完全一致の`NO_REPLY` / `no_reply`など）は省略され、過大な行はプレースホルダーに置き換えられる場合があります。 +- `sessions.get`は、完全な保存済みセッション行を返します。 +- chat実行では引き続き`chat.history`、`chat.send`、`chat.abort`、`chat.inject`を使用します。 +- `chat.history`は、UIクライアント向けに表示正規化されています。インラインdirectiveタグは可視テキストから除去され、プレーンテキストのtool-call XMLペイロード（`...`、`...`、`...`、`...`、および切り詰められたtool-callブロックを含む）と漏出したASCII/全角のモデル制御トークンは除去され、正確な`NO_REPLY` / `no_reply`のような純粋なsilent-token assistant行は省略され、サイズの大きすぎる行はプレースホルダーに置き換えられることがあります。 #### デバイスペアリングとデバイストークン - `device.pair.list`は、保留中および承認済みのペア済みデバイスを返します。 - `device.pair.approve`、`device.pair.reject`、`device.pair.remove`は、デバイスペアリングレコードを管理します。 -- `device.token.rotate`は、承認済みのroleおよびscopeの範囲内でペア済みデバイストークンをローテーションします。 -- `device.token.revoke`は、ペア済みデバイストークンを無効化します。 +- `device.token.rotate`は、承認済みのroleおよびscope境界内でペア済みデバイストークンをローテーションします。 +- `device.token.revoke`は、ペア済みデバイストークンを失効させます。 #### Nodeのペアリング、invoke、保留中の作業 -- `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.verify`は、nodeのペアリングとブートストラップ検証を扱います。 -- `node.list`と`node.describe`は、既知/接続済みのnode状態を返します。 -- `node.rename`は、ペア済みnodeラベルを更新します。 -- `node.invoke`は、接続済みnodeにコマンドを転送します。 +- `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.verify`は、Nodeペアリングとブートストラップ検証を扱います。 +- `node.list`と`node.describe`は、既知の/接続中のNode状態を返します。 +- `node.rename`は、ペア済みNodeラベルを更新します。 +- `node.invoke`は、接続中のNodeにコマンドを転送します。 - `node.invoke.result`は、invokeリクエストの結果を返します。 -- `node.event`は、node由来のイベントをgatewayに戻します。 +- `node.event`は、Node起点のイベントをGatewayに戻します。 - `node.canvas.capability.refresh`は、スコープ付きcanvas-capabilityトークンを更新します。 -- `node.pending.pull`と`node.pending.ack`は、接続済みnodeキューAPIです。 -- `node.pending.enqueue`と`node.pending.drain`は、オフライン/切断中のnode向けの永続的な保留作業を管理します。 +- `node.pending.pull`と`node.pending.ack`は、接続中NodeキューAPIです。 +- `node.pending.enqueue`と`node.pending.drain`は、オフライン/切断中のNode向けの永続的な保留作業を管理します。 #### 承認ファミリー -- `exec.approval.request`、`exec.approval.get`、`exec.approval.list`、`exec.approval.resolve`は、単発のexec承認リクエストと、保留中承認の参照/再生を扱います。 -- `exec.approval.waitDecision`は、1件の保留中exec承認を待機し、最終判断を返します（タイムアウト時は`null`）。 -- `exec.approvals.get`と`exec.approvals.set`は、gateway exec承認ポリシースナップショットを管理します。 -- `exec.approvals.node.get`と`exec.approvals.node.set`は、node relayコマンド経由でnodeローカルのexec承認ポリシーを管理します。 +- `exec.approval.request`、`exec.approval.get`、`exec.approval.list`、`exec.approval.resolve`は、単発のexec承認リクエストと、保留中承認のlookup/replayを扱います。 +- `exec.approval.waitDecision`は、1つの保留中exec承認を待機し、最終決定を返します（タイムアウト時は`null`）。 +- `exec.approvals.get`と`exec.approvals.set`は、Gateway exec承認ポリシースナップショットを管理します。 +- `exec.approvals.node.get`と`exec.approvals.node.set`は、Node relayコマンド経由でNodeローカルexec承認ポリシーを管理します。 - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision`、`plugin.approval.resolve`は、Plugin定義の承認フローを扱います。 #### その他の主要ファミリー @@ -342,21 +352,21 @@ Gatewayはこれらを**クレーム**として扱い、サーバー側allowlist - automation: - `wake`は、即時または次回Heartbeat時のwakeテキスト注入をスケジュールします - `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` -- skills/tools: `commands.list`、`skills.*`、`tools.catalog`、`tools.effective` +- Skills/tools: `commands.list`、`skills.*`、`tools.catalog`、`tools.effective` ### 一般的なイベントファミリー - `chat`: `chat.inject`やその他のtranscript専用chatイベントなどのUI chat更新。 -- `session.message`と`session.tool`: 購読中セッション向けのtranscript/event-stream更新。 +- `session.message`と`session.tool`: 購読中セッション向けのtranscript/イベントストリーム更新。 - `sessions.changed`: セッションインデックスまたはメタデータが変更されました。 -- `presence`: system presenceスナップショット更新。 +- `presence`: システムプレゼンススナップショット更新。 - `tick`: 定期的なkeepalive / livenessイベント。 -- `health`: gateway healthスナップショット更新。 +- `health`: Gatewayヘルススナップショット更新。 - `heartbeat`: Heartbeatイベントストリーム更新。 -- `cron`: cron実行/ジョブ変更イベント。 -- `shutdown`: gatewayシャットダウン通知。 -- `node.pair.requested` / `node.pair.resolved`: nodeペアリングのライフサイクル。 -- `node.invoke.request`: node invokeリクエストのブロードキャスト。 +- `cron`: Cron実行/ジョブ変更イベント。 +- `shutdown`: Gatewayシャットダウン通知。 +- `node.pair.requested` / `node.pair.resolved`: Nodeペアリングのライフサイクル。 +- `node.invoke.request`: Node invokeリクエストのブロードキャスト。 - `device.pair.requested` / `device.pair.resolved`: ペア済みデバイスのライフサイクル。 - `voicewake.changed`: ウェイクワードトリガー設定が変更されました。 - `exec.approval.requested` / `exec.approval.resolved`: exec承認のライフサイクル。 @@ -364,125 +374,125 @@ Gatewayはこれらを**クレーム**として扱い、サーバー側allowlist ### Nodeヘルパーメソッド -- ノードは、auto-allowチェック用に現在のskill実行可能ファイル一覧を取得するために`skills.bins`を呼び出せます。 +- Nodeは、自動許可チェック用に現在のskill実行ファイル一覧を取得するために`skills.bins`を呼び出せます。 ### Operatorヘルパーメソッド -- operatorは、agentの実行時コマンド一覧を取得するために`commands.list`（`operator.read`）を呼び出せます。 - - `agentId`は任意です。省略するとデフォルトagent workspaceを参照します。 - - `scope`は、主要な`name`がどのサーフェスを対象にするかを制御します: - - `text`は、先頭の`/`を除いた主要なテキストコマンドトークンを返します - - `native`およびデフォルトの`both`パスは、利用可能な場合にprovider対応のnative名を返します - - `textAliases`は、`/model`や`/m`のような正確なスラッシュエイリアスを保持します。 - - `nativeName`は、存在する場合にprovider対応のnativeコマンド名を保持します。 - - `provider`は任意で、native命名とnative Pluginコマンドの可用性にのみ影響します。 +- Operatorは、agentのランタイムコマンドインベントリを取得するために`commands.list`（`operator.read`）を呼び出せます。 + - `agentId`は任意です。省略するとデフォルトagentワークスペースを読み取ります。 + - `scope`は、主`name`がどのサーフェスを対象にするかを制御します。 + - `text`は、先頭の`/`を除いた主textコマンドトークンを返します + - `native`およびデフォルトの`both`パスは、利用可能な場合にprovider対応native名を返します + - `textAliases`は、`/model`や`/m`のような正確なスラッシュ別名を保持します。 + - `nativeName`は、存在する場合にprovider対応nativeコマンド名を保持します。 + - `provider`は任意で、native名付けとnative Pluginコマンド可用性にのみ影響します。 - `includeArgs=false`は、レスポンスからシリアライズ済み引数メタデータを省略します。 -- operatorは、agentの実行時ツールカタログを取得するために`tools.catalog`（`operator.read`）を呼び出せます。レスポンスには、グループ化されたツールと出所メタデータが含まれます: +- Operatorは、agentのランタイムtoolカタログを取得するために`tools.catalog`（`operator.read`）を呼び出せます。レスポンスには、グループ化されたtoolsとprovenanceメタデータが含まれます。 - `source`: `core`または`plugin` - - `pluginId`: `source="plugin"`の場合のPlugin所有者 - - `optional`: Pluginツールが任意かどうか -- operatorは、セッションの実行時有効ツール一覧を取得するために`tools.effective`（`operator.read`）を呼び出せます。 + - `pluginId`: `source="plugin"`のときのPlugin所有者 + - `optional`: Plugin toolが任意かどうか +- Operatorは、セッションのランタイムで有効なtoolインベントリを取得するために`tools.effective`（`operator.read`）を呼び出せます。 - `sessionKey`は必須です。 - - gatewayは、呼び出し元が指定したauthやdeliveryコンテキストを受け入れる代わりに、サーバー側でセッションから信頼できる実行時コンテキストを導出します。 - - レスポンスはセッションスコープであり、core、Plugin、channelツールを含め、現在アクティブな会話で今使えるものを反映します。 -- operatorは、agentの表示可能なskill一覧を取得するために`skills.status`（`operator.read`）を呼び出せます。 - - `agentId`は任意です。省略するとデフォルトagent workspaceを参照します。 - - レスポンスには、生のsecret値を公開せずに、適格性、不足要件、configチェック、サニタイズ済みインストールオプションが含まれます。 -- operatorは、ClawHubディスカバリーメタデータ向けに`skills.search`と`skills.detail`（`operator.read`）を呼び出せます。 -- operatorは、`skills.install`（`operator.admin`）を2つのモードで呼び出せます: - - ClawHubモード: `{ source: "clawhub", slug, version?, force? }`は、skillフォルダーをデフォルトagent workspaceの`skills/`ディレクトリにインストールします。 - - Gateway installerモード: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`は、gatewayホスト上で宣言済み`metadata.openclaw.install`アクションを実行します。 -- operatorは、`skills.update`（`operator.admin`）を2つのモードで呼び出せます: - - ClawHubモードでは、デフォルトagent workspace内の1つの追跡対象slug、またはすべての追跡対象ClawHubインストールを更新します。 - - Configモードでは、`enabled`、`apiKey`、`env`などの`skills.entries.`値にパッチを適用します。 + - Gatewayは、呼び出し元から供給されたauthやdeliveryコンテキストを受け入れる代わりに、セッションから信頼できるランタイムコンテキストをサーバー側で導出します。 + - レスポンスはセッションスコープであり、core、Plugin、channel toolsを含めて、アクティブな会話が現在使用できるものを反映します。 +- Operatorは、agentの可視なskillインベントリを取得するために`skills.status`（`operator.read`）を呼び出せます。 + - `agentId`は任意です。省略するとデフォルトagentワークスペースを読み取ります。 + - レスポンスには、適格性、不足している要件、configチェック、生のシークレット値を公開しないサニタイズ済みinstallオプションが含まれます。 +- Operatorは、ClawHub検出メタデータのために`skills.search`と`skills.detail`（`operator.read`）を呼び出せます。 +- Operatorは、`skills.install`（`operator.admin`）を2つのモードで呼び出せます。 + - ClawHubモード: `{ source: "clawhub", slug, version?, force? }`は、デフォルトagentワークスペースの`skills/`ディレクトリにskillフォルダーをインストールします。 + - Gatewayインストーラーモード: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`は、Gatewayホスト上で宣言された`metadata.openclaw.install`アクションを実行します。 +- Operatorは、`skills.update`（`operator.admin`）を2つのモードで呼び出せます。 + - ClawHubモードは、1つの追跡対象slug、またはデフォルトagentワークスペース内のすべての追跡対象ClawHubインストールを更新します。 + - Configモードは、`enabled`、`apiKey`、`env`などの`skills.entries.`値をパッチします。 ## Exec承認 -- execリクエストに承認が必要な場合、gatewayは`exec.approval.requested`をブロードキャストします。 -- operatorクライアントは、`exec.approval.resolve`を呼び出して解決します（`operator.approvals` scopeが必要です）。 -- `host=node`の場合、`exec.approval.request`には`systemRunPlan`（正規化された`argv`/`cwd`/`rawCommand`/sessionメタデータ）を含める必要があります。`systemRunPlan`が欠けているリクエストは拒否されます。 -- 承認後、転送される`node.invoke system.run`呼び出しは、その正規化された`systemRunPlan`を権威あるコマンド/cwd/sessionコンテキストとして再利用します。 -- 呼び出し元がprepareと最終承認済み`system.run`転送の間で`command`、`rawCommand`、`cwd`、`agentId`、または`sessionKey`を変更した場合、gatewayは変更されたペイロードを信用せずに実行を拒否します。 +- execリクエストに承認が必要な場合、Gatewayは`exec.approval.requested`をブロードキャストします。 +- Operatorクライアントは、`exec.approval.resolve`を呼び出して解決します（`operator.approvals` scopeが必要です）。 +- `host=node`の場合、`exec.approval.request`には`systemRunPlan`（正規化された`argv`/`cwd`/`rawCommand`/セッションメタデータ）が含まれている必要があります。`systemRunPlan`がないリクエストは拒否されます。 +- 承認後、転送された`node.invoke system.run`呼び出しは、その正規の`systemRunPlan`を権威あるcommand/cwd/sessionコンテキストとして再利用します。 +- 呼び出し元がprepareと最終承認済み`system.run`転送の間で`command`、`rawCommand`、`cwd`、`agentId`、`sessionKey`を変更した場合、Gatewayは変更されたペイロードを信用せず、その実行を拒否します。 -## Agent deliveryフォールバック +## Agent配信フォールバック -- `agent`リクエストには、アウトバウンド配信を要求するために`deliver=true`を含めることができます。 -- `bestEffortDeliver=false`は厳密な動作を維持します。未解決または内部専用のdeliveryターゲットは`INVALID_REQUEST`を返します。 -- `bestEffortDeliver=true`は、外部配信可能なルートを解決できない場合（たとえばinternal/webchatセッションや曖昧なマルチchannel設定）に、セッション専用実行へのフォールバックを許可します。 +- `agent`リクエストには、送信先配信を要求するための`deliver=true`を含めることができます。 +- `bestEffortDeliver=false`は厳密な動作を維持します。未解決または内部専用の配信先ターゲットは`INVALID_REQUEST`を返します。 +- `bestEffortDeliver=true`は、外部配信可能ルートを解決できない場合（たとえば内部/webchatセッションや曖昧なマルチchannel設定）に、セッション専用実行へのフォールバックを許可します。 ## バージョニング - `PROTOCOL_VERSION`は`src/gateway/protocol/schema/protocol-schemas.ts`にあります。 - クライアントは`minProtocol` + `maxProtocol`を送信し、サーバーは不一致を拒否します。 -- スキーマ + モデルはTypeBox定義から生成されます: +- スキーマ + モデルはTypeBox定義から生成されます。 - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` ### クライアント定数 -`src/gateway/client.ts`のリファレンスクライアントは、これらのデフォルト値を使用します。値はprotocol v3全体で安定しており、サードパーティクライアントにとって期待されるベースラインです。 +`src/gateway/client.ts`のリファレンスクライアントは、これらのデフォルト値を使用します。値はプロトコルv3全体で安定しており、サードパーティクライアントに期待されるベースラインです。 | 定数 | デフォルト | ソース | -| --- | --- | --- | +| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | | `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | | リクエストタイムアウト（RPCごと） | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | -| 事前認証 / connect-challengeタイムアウト | `10_000` ms | `src/gateway/handshake-timeouts.ts`（`250`–`10_000`にクランプ） | +| preauth / connect-challengeタイムアウト | `10_000` ms | `src/gateway/handshake-timeouts.ts`（クランプ `250`–`10_000`） | | 初期再接続バックオフ | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | | 最大再接続バックオフ | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | -| device-token切断後の高速再試行クランプ | `250` ms | `src/gateway/client.ts` | +| device-token close後の高速リトライクランプ | `250` ms | `src/gateway/client.ts` | | `terminate()`前の強制停止猶予 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | -| `stopAndWait()`のデフォルトタイムアウト | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | +| `stopAndWait()`デフォルトタイムアウト | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | | デフォルトtick間隔（`hello-ok`前） | `30_000` ms | `src/gateway/client.ts` | -| tick-timeout切断 | 無通信が`tickIntervalMs * 2`を超えた場合はコード`4000` | `src/gateway/client.ts` | +| tickタイムアウトclose | 無通信が`tickIntervalMs * 2`を超えるとコード`4000` | `src/gateway/client.ts` | | `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024`（25 MB） | `src/gateway/server-constants.ts` | -サーバーは、有効な`policy.tickIntervalMs`、`policy.maxPayload`、`policy.maxBufferedBytes`を`hello-ok`で通知します。クライアントは、ハンドシェイク前のデフォルト値ではなく、これらの値を尊重する必要があります。 +サーバーは、有効な`policy.tickIntervalMs`、`policy.maxPayload`、`policy.maxBufferedBytes`を`hello-ok`で通知します。クライアントは、ハンドシェイク前のデフォルト値ではなく、それらの値に従うべきです。 ## 認証 -- 共有シークレットによるgateway認証は、設定された認証モードに応じて`connect.params.auth.token`または`connect.params.auth.password`を使います。 -- Tailscale Serve（`gateway.auth.allowTailscale: true`）や非loopbackの`gateway.auth.mode: "trusted-proxy"`のようなidentity付きモードでは、`connect.params.auth.*`ではなくリクエストヘッダーからconnect認証チェックを満たします。 -- private-ingressの`gateway.auth.mode: "none"`は共有シークレットのconnect認証を完全にスキップします。このモードを公開/信頼できないingressで公開しないでください。 -- ペアリング後、Gatewayは接続のrole + scopesにスコープされた**device token**を発行します。これは`hello-ok.auth.deviceToken`で返され、クライアントは今後の接続のためにこれを永続化する必要があります。 -- クライアントは、接続成功時には必ず主要な`hello-ok.auth.deviceToken`を永続化する必要があります。 -- その**保存済み**device tokenで再接続する場合は、そのトークンに対して保存済みの承認scopeセットも再利用する必要があります。これにより、すでに許可されているread/probe/statusアクセスが維持され、再接続時により狭い暗黙のadmin専用scopeへと黙って縮小されることを防げます。 -- クライアント側のconnect認証組み立て（`src/gateway/client.ts`内の`selectConnectAuth`）: - - `auth.password`は独立しており、設定されていれば常に転送されます。 - - `auth.token`は優先順で設定されます: まず明示的な共有トークン、次に明示的な`deviceToken`、その次に保存済みのデバイス単位トークン（`deviceId` + `role`をキーとする）。 - - `auth.bootstrapToken`は、上記のどれでも`auth.token`が解決されなかった場合にのみ送信されます。共有トークンまたは解決済みdevice tokenがあれば抑止されます。 - - one-shotの`AUTH_TOKEN_MISMATCH`再試行時の保存済みdevice tokenの自動昇格は、**trusted endpointsのみ**で有効です — loopback、またはピン留めされた`tlsFingerprint`を持つ`wss://`です。ピン留めなしの公開`wss://`は該当しません。 -- 追加の`hello-ok.auth.deviceTokens`エントリは、ブートストラップのハンドオフトークンです。`wss://`やloopback/local pairingのような信頼できる転送でブートストラップ認証を使って接続した場合にのみ永続化してください。 -- クライアントが明示的な**`deviceToken`**または明示的な**`scopes`**を指定した場合、その呼び出し元が要求したscopeセットが引き続き権威あるものです。キャッシュ済みscopeは、クライアントが保存済みのデバイス単位トークンを再利用している場合にのみ再利用されます。 -- device tokenは、`device.token.rotate`と`device.token.revoke`でローテーション/無効化できます（`operator.pairing` scopeが必要です）。 -- トークン発行/ローテーションは、そのデバイスのpairingエントリに記録された承認済みroleセットの範囲内に制限されます。トークンのローテーションによって、そのデバイスをpairing承認で一度も許可されていないroleへ拡張することはできません。 -- ペア済みデバイストークンセッションでは、呼び出し元が`operator.admin`も持っていない限り、デバイス管理は自分自身のスコープに限定されます。adminではない呼び出し元は、自分**自身の**デバイスエントリのみをremove/revoke/rotateできます。 -- `device.token.rotate`は、要求されたoperator scopeセットも、呼び出し元の現在のセッションscopeに照らしてチェックします。adminではない呼び出し元は、現在保持しているものより広いoperator scopeセットへトークンをローテーションできません。 -- 認証失敗には、`error.details.code`に加えて復旧ヒントが含まれます: +- 共有シークレットGateway認証は、設定された認証モードに応じて`connect.params.auth.token`または`connect.params.auth.password`を使用します。 +- Tailscale Serve（`gateway.auth.allowTailscale: true`）や非loopbackの`gateway.auth.mode: "trusted-proxy"`のようなID保持モードでは、`connect.params.auth.*`ではなくリクエストヘッダーからconnect認証チェックを満たします。 +- プライベートingressの`gateway.auth.mode: "none"`は共有シークレットconnect認証を完全にスキップします。このモードを公開/信頼できないingressで公開しないでください。 +- ペアリング後、Gatewayは接続のrole + scopesにスコープされた**device token**を発行します。これは`hello-ok.auth.deviceToken`で返され、クライアントは将来の接続のためにそれを永続化する必要があります。 +- クライアントは、成功したconnectの後に常にプライマリ`hello-ok.auth.deviceToken`を永続化する必要があります。 +- その**保存済み**device tokenで再接続する場合、そのトークンに対して保存済みの承認scopeセットも再利用する必要があります。これにより、すでに付与されたread/probe/statusアクセスが保持され、再接続がより狭い暗黙のadmin専用scopeへ静かに縮小されることを防ぎます。 +- クライアント側のconnect認証組み立て（`src/gateway/client.ts`の`selectConnectAuth`）: + - `auth.password`は直交しており、設定されている場合は常に転送されます。 + - `auth.token`は優先順位順に設定されます。最初に明示的な共有トークン、次に明示的な`deviceToken`、最後に保存済みのデバイス単位トークン（`deviceId` + `role`でキー付け）。 + - `auth.bootstrapToken`は、上記のいずれでも`auth.token`が解決されなかった場合にのみ送信されます。共有トークンまたは解決済みのdevice tokenがあれば送信されません。 + - 保存済みdevice tokenの自動昇格は、ワンショットの`AUTH_TOKEN_MISMATCH`リトライ時でも**信頼されたエンドポイントのみ**で有効です — loopback、または固定された`tlsFingerprint`を持つ`wss://`です。ピン留めなしの公開`wss://`は該当しません。 +- 追加の`hello-ok.auth.deviceTokens`エントリはブートストラップ引き継ぎトークンです。`wss://`またはloopback/local pairingのような信頼されたトランスポート上でブートストラップ認証を使った接続の場合にのみ永続化してください。 +- クライアントが明示的な`deviceToken`または明示的な`scopes`を指定した場合、その呼び出し元要求のscopeセットが引き続き権威を持ちます。キャッシュ済みscopeが再利用されるのは、クライアントが保存済みのデバイス単位トークンを再利用している場合だけです。 +- Device tokenは`device.token.rotate`と`device.token.revoke`でローテーション/失効できます（`operator.pairing` scopeが必要です）。 +- トークンの発行/ローテーションは、そのデバイスのペアリングエントリに記録された承認済みroleセットの範囲内に制限されます。トークンのローテーションによって、ペアリング承認が一度も許可していないroleへそのデバイスを拡張することはできません。 +- ペア済みデバイストークンセッションでは、呼び出し元が`operator.admin`も持っていない限り、デバイス管理は自身のスコープに限定されます。非admin呼び出し元は、自分**自身**のデバイスエントリのみをremove/revoke/rotateできます。 +- `device.token.rotate`は、要求されたoperator scopeセットが呼び出し元の現在のセッションscopeに対して適切かどうかも確認します。非admin呼び出し元は、自分が現在保持しているより広いoperator scopeセットへトークンをローテーションできません。 +- 認証失敗には、`error.details.code`と回復ヒントが含まれます: - `error.details.canRetryWithDeviceToken`（boolean） - `error.details.recommendedNextStep`（`retry_with_device_token`、`update_auth_configuration`、`update_auth_credentials`、`wait_then_retry`、`review_auth_configuration`） - `AUTH_TOKEN_MISMATCH`に対するクライアント動作: - - 信頼できるクライアントは、キャッシュ済みのデバイス単位トークンで1回だけ制限付き再試行を試みられます。 - - その再試行が失敗した場合、クライアントは自動再接続ループを停止し、operatorの対応ガイダンスを表示する必要があります。 + - 信頼されたクライアントは、キャッシュ済みのデバイス単位トークンで1回だけ制限付きリトライを試行できます。 + - そのリトライが失敗した場合、クライアントは自動再接続ループを停止し、オペレーターの対応ガイダンスを表示する必要があります。 ## デバイスID + ペアリング -- ノードは、キーペアのフィンガープリントから導出された安定したデバイスID（`device.id`）を含める必要があります。 +- Nodeは、キーペアフィンガープリントから導出された安定したデバイスID（`device.id`）を含める必要があります。 - Gatewayは、デバイス + roleごとにトークンを発行します。 -- 新しいデバイスIDには、ローカル自動承認が有効になっていない限り、ペアリング承認が必要です。 +- ローカル自動承認が有効でない限り、新しいデバイスIDにはペアリング承認が必要です。 - ペアリング自動承認は、直接のlocal loopback接続を中心にしています。 -- OpenClawには、信頼済み共有シークレットのヘルパーフロー向けに、限定的なbackend/container-local self-connectパスもあります。 -- 同一ホストのtailnetまたはLAN接続も、ペアリング上は引き続きリモートとして扱われ、承認が必要です。 -- すべてのWSクライアントは、`connect`時に`device` IDを含める必要があります（operator + node）。 - Control UIがこれを省略できるのは次のモードのみです: - - localhost専用の安全でないHTTP互換のための`gateway.controlUi.allowInsecureAuth=true`。 - - `gateway.auth.mode: "trusted-proxy"`によるoperator Control UI認証が成功している場合。 - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（緊急用、重大なセキュリティ低下）。 -- すべての接続は、サーバーが提供する`connect.challenge` nonceに署名する必要があります。 +- OpenClawには、信頼された共有シークレットヘルパーフロー向けの限定的なバックエンド/コンテナローカル自己接続パスもあります。 +- 同一ホストのtailnetまたはLAN接続は、依然としてpairing上はリモートとして扱われ、承認が必要です。 +- すべてのWSクライアントは、`connect`中に`device` IDを含める必要があります（operator + node）。 + Control UIがこれを省略できるのは、次のモードのみです: + - localhost専用の安全でないHTTP互換性のための`gateway.controlUi.allowInsecureAuth=true`。 + - 成功した`gateway.auth.mode: "trusted-proxy"` operator Control UI認証。 + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（非常時用、深刻なセキュリティ低下）。 +- すべての接続は、サーバー提供の`connect.challenge` nonceに署名する必要があります。 -### デバイス認証移行の診断 +### デバイス認証移行診断 -従来のchallenge前署名動作をまだ使っているレガシークライアント向けに、`connect`は現在、安定した`error.details.reason`とともに`error.details.code`配下で`DEVICE_AUTH_*`詳細コードを返します。 +従来のchallenge前署名動作をまだ使用しているレガシークライアント向けに、`connect`は現在、安定した`error.details.reason`の下で`error.details.code`に`DEVICE_AUTH_*`詳細コードを返します。 一般的な移行失敗: @@ -491,23 +501,23 @@ Gatewayはこれらを**クレーム**として扱い、サーバー側allowlist | `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | クライアントが`device.nonce`を省略した（または空で送信した）。 | | `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | クライアントが古い/誤ったnonceで署名した。 | | `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 署名ペイロードがv2ペイロードと一致しない。 | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 署名済みタイムスタンプが許容スキュー範囲外。 | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 署名済みタイムスタンプが許容されるスキュー範囲外。 | | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id`が公開鍵フィンガープリントと一致しない。 | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公開鍵形式/正規化に失敗した。 | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公開鍵の形式/正規化に失敗した。 | -移行先の目標: +移行目標: -- 必ず`connect.challenge`を待ちます。 -- サーバーnonceを含むv2ペイロードに署名します。 -- 同じnonceを`connect.params.device.nonce`で送信します。 -- 推奨される署名ペイロードは`v3`で、device/client/role/scopes/token/nonceフィールドに加えて`platform`と`deviceFamily`も束縛します。 -- レガシー`v2`署名も互換性のため引き続き受け入れられますが、ペア済みデバイスのメタデータ固定は、再接続時のコマンドポリシーを引き続き制御します。 +- 常に`connect.challenge`を待機する。 +- サーバーnonceを含むv2ペイロードに署名する。 +- 同じnonceを`connect.params.device.nonce`で送信する。 +- 推奨される署名ペイロードは`v3`で、device/client/role/scopes/token/nonceフィールドに加えて`platform`と`deviceFamily`を束縛します。 +- レガシー`v2`署名も互換性のため引き続き受け入れられますが、ペア済みデバイスメタデータのピン留めは再接続時のコマンドポリシーを引き続き制御します。 ## TLS + ピン留め -- WS接続でTLSがサポートされます。 -- クライアントは任意でgateway証明書フィンガープリントをピン留めできます（`gateway.tls`設定に加えて`gateway.remote.tlsFingerprint`またはCLIの`--tls-fingerprint`を参照）。 +- WS接続ではTLSがサポートされます。 +- クライアントは任意でGateway証明書フィンガープリントをピン留めできます（`gateway.tls` configおよび`gateway.remote.tlsFingerprint`またはCLI `--tls-fingerprint`を参照）。 ## スコープ -このプロトコルは、**完全なgateway API**（status、channels、models、chat、agent、sessions、nodes、approvalsなど）を公開します。正確なサーフェスは、`src/gateway/protocol/schema.ts`内のTypeBoxスキーマで定義されています。 +このプロトコルは**完全なGateway API**（status、channels、models、chat、agent、sessions、nodes、approvalsなど）を公開します。正確なサーフェスは`src/gateway/protocol/schema.ts`のTypeBoxスキーマで定義されています。 diff --git a/docs/ja-JP/help/testing.md b/docs/ja-JP/help/testing.md index 7fa50c600..22c5a315c 100644 --- a/docs/ja-JP/help/testing.md +++ b/docs/ja-JP/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - ローカルまたはCIでテストを実行する - - モデル/プロバイダーのバグに対するリグレッションを追加する - - Gateway + エージェントの動作をデバッグする -summary: テストキット：unit/e2e/liveスイート、Dockerランナー、および各テストがカバーする内容 + - モデル/プロバイダーのバグに対するリグレッションテストを追加する + - Gateway + agentの動作をデバッグする +summary: 'テストキット: unit/e2e/liveスイート、Dockerランナー、および各テストがカバーする内容' title: テスト x-i18n: - generated_at: "2026-04-17T04:44:00Z" + generated_at: "2026-04-18T04:40:08Z" model: gpt-5.4 provider: openai - source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 + source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a source_path: help/testing.md workflow: 15 --- @@ -18,98 +18,101 @@ x-i18n: OpenClawには3つのVitestスイート（unit/integration、e2e、live）と、少数のDockerランナーがあります。 -このドキュメントは「どのようにテストするか」のガイドです。 +このドキュメントは「OpenClawでどのようにテストするか」のガイドです。 -- 各スイートが何をカバーするか（および意図的に何をカバーしないか） +- 各スイートが何をカバーするか（そして意図的に _何をカバーしないか_） - 一般的なワークフロー（ローカル、push前、デバッグ）でどのコマンドを実行するか - liveテストがどのように認証情報を見つけ、モデル/プロバイダーを選択するか - 実際のモデル/プロバイダーの問題に対するリグレッションをどのように追加するか ## クイックスタート -ほとんどの日は以下です。 +たいていの日は次のとおりです。 -- フルゲート（push前に期待されるもの）: `pnpm build && pnpm check && pnpm test` +- フルゲート（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` +- 直接のファイル指定は、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` 実際のプロバイダー/モデルをデバッグするとき（実際の認証情報が必要）: -- liveスイート（models + Gateway tool/image probes）: `pnpm test:live` +- Liveスイート（モデル + 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` レーンを置き換えることなく、実験的なfixtureおよびプロトコルモックのカバレッジ向けに、ローカルのAIMockベースのプロバイダーサーバーを起動します。 + - デフォルトでは、分離されたgatewayワーカーを使って複数の選択シナリオを並列実行し、最大64ワーカーまたは選択シナリオ数まで使用します。`--concurrency `でワーカー数を調整するか、古い直列レーンには`--concurrency 1`を使います。 + - プロバイダーモード `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プロバイダー設定パス、存在する場合は `CODEX_HOME`。 - - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に維持する必要があります。 - - 通常のQAレポートとサマリーに加え、Multipassログを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - live実行では、ゲストにとって実用的な対応済みQA認証入力を転送します: + 環境変数ベースのプロバイダーキー、QA live provider configパス、および存在する場合は `CODEX_HOME`。 + - 出力ディレクトリは、ゲストがマウントされたワークスペース経由で書き戻せるよう、リポジトリルート配下に置く必要があります。 + - 通常の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ホームサーバーに対して、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は共有認証情報ソースフラグを公開しません。これは、このレーンが使い捨てユーザーをローカルでプロビジョニングするためです。 - - Matrix QAレポート、サマリー、observed-events artifact、結合されたstdout/stderr出力ログを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - 使い捨ての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/...` 配下に書き込みます。 - `pnpm openclaw qa telegram` - - 環境変数から取得したdriverおよびSUT botトークンを使って、実際のプライベートグループに対してTelegram live QAレーンを実行します。 - - `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` が必要です。グループIDは数値のTelegram chat idでなければなりません。 - - 共有プール認証情報用に `--credential-source convex` をサポートします。デフォルトではenvモードを使い、プールされたリースを使うには `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` を設定してください。 - - 同じプライベートグループ内に2つの異なるbotが必要で、SUT botはTelegram usernameを公開している必要があります。 - - 安定したbot間観測のために、`@BotFather` で両方のbotのBot-to-Bot Communication Modeを有効にし、driver botがグループ内のbotトラフィックを観測できることを確認してください。 - - Telegram QAレポート、サマリー、およびobserved-messages artifactを `.artifacts/qa-e2e/...` 配下に書き込みます。 + - 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/...` 配下に書き込みます。 -live transportレーンは、新しいtransportがずれないよう、1つの標準契約を共有します。 +liveトランスポートレーンは、追加される新しいトランスポートが逸脱しないよう、1つの標準契約を共有します。 -`qa-channel` は依然として広範な合成QAスイートであり、live transportカバレッジマトリクスには含まれません。 +`qa-channel` は引き続き広範な合成QAスイートであり、live +transport coverage matrixには含まれません。 -| レーン | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | +| Lane | 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） -`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ロール選択: - CLI: `--credential-role maintainer|ci` - - 環境変数デフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（デフォルトは `maintainer`） + - 環境変数のデフォルト: `OPENCLAW_QA_CREDENTIAL_ROLE`（デフォルトは `maintainer`） 任意の環境変数: @@ -118,12 +121,13 @@ live transportレーンは、新しいtransportがずれないよう、1つの - `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://` を使う必要があります。 -maintainer管理コマンド（プールの追加/削除/一覧表示）には、特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 +maintainer用の管理コマンド（pool add/remove/list）には、 +特に `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` が必要です。 maintainer向けCLIヘルパー: @@ -133,7 +137,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`）: @@ -147,73 +151,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種別のpayload形状: +Telegram kind用のペイロード形式: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` は数値のTelegram chat id文字列でなければなりません。 -- `admin/add` は `kind: "telegram"` に対してこの形状を検証し、不正なpayloadを拒否します。 +- `groupId` は数値のTelegram chat id文字列である必要があります。 +- `admin/add` は `kind: "telegram"` に対してこの形式を検証し、不正なペイロードを拒否します。 -### QAにチャネルを追加する +### QAにchannelを追加する -markdown QAシステムにチャネルを追加するには、正確に2つのものが必要です。 +markdown QAシステムにchannelを追加するには、必要なものは正確に2つだけです。 -1. そのチャネル用のtransport adapter -2. チャネル契約を実行するscenario pack +1. そのchannel用のtransport adapter。 +2. channel契約を検証するscenario pack。 -共有の `qa-lab` ホストがフローを所有できる場合、新しいトップレベルQAコマンドルートを追加しないでください。 +共有 `qa-lab` ホストがフローを管理できる場合、新しいトップレベルQAコマンドrootを追加しないでください。 -`qa-lab` は共有ホストメカニクスを所有します。 +`qa-lab` は共有ホストの仕組みを管理します: -- `openclaw qa` コマンドルート -- スイートの起動と終了処理 -- ワーカー並行性 -- artifactの書き込み +- `openclaw qa` コマンドroot +- スイートの起動と終了 +- ワーカー並列数 +- アーティファクト書き込み - レポート生成 - シナリオ実行 - 古い `qa-channel` シナリオ向けの互換エイリアス -Runner Pluginはtransport契約を所有します。 +runner Pluginはtransport契約を管理します: -- `openclaw qa ` が共有の `qa` ルート配下にどのようにマウントされるか -- そのtransport向けにGatewayがどのように設定されるか -- 準備完了をどのように確認するか -- inboundイベントをどのように注入するか -- outboundメッセージをどのように観測するか -- transcriptおよび正規化されたtransport状態をどのように公開するか -- transportベースのアクションをどのように実行するか +- `openclaw qa ` が共有 `qa` root配下でどのようにマウントされるか +- そのtransport向けにgatewayがどのように設定されるか +- readinessをどのように確認するか +- inbound eventをどのように注入するか +- outbound messageをどのように観測するか +- transcriptおよび正規化されたtransport stateをどのように公開するか +- transportを使ったactionをどのように実行するか - transport固有のリセットまたはクリーンアップをどのように処理するか -新しいチャネルの最低採用基準は以下です。 +新しいchannelを採用するための最小基準は次のとおりです。 -1. 共有 `qa` ルートの所有者は `qa-lab` のままにする。 -2. 共有 `qa-lab` ホストシーム上にtransport runnerを実装する。 -3. transport固有のメカニクスはrunner Pluginまたはチャネルharness内に保持する。 -4. 競合するルートコマンドを登録するのではなく、runnerを `openclaw qa ` としてマウントする。 - Runner Pluginは `openclaw.plugin.json` に `qaRunners` を宣言し、`runtime-api.ts` から一致する `qaRunnerCliRegistrations` 配列をエクスポートする必要があります。 - `runtime-api.ts` は軽量に保ってください。遅延CLIおよびrunner実行は、別のentrypointの背後に置く必要があります。 -5. `qa/scenarios/` 配下にmarkdownシナリオを作成または調整する。 -6. 新しいシナリオには汎用シナリオヘルパーを使う。 -7. リポジトリが意図的な移行を行っているのでない限り、既存の互換エイリアスを動作させ続ける。 +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. リポジトリが意図的な移行を行っている場合を除き、既存の互換エイリアスは動作したままにする。 判断ルールは厳格です。 - 振る舞いを `qa-lab` で一度だけ表現できるなら、`qa-lab` に置く。 -- 振る舞いが1つのチャネルtransportに依存するなら、そのrunner PluginまたはPlugin harnessに保持する。 -- シナリオが複数のチャネルで使える新しい機能を必要とするなら、`suite.ts` にチャネル固有の分岐を追加するのではなく、汎用ヘルパーを追加する。 -- 振る舞いが1つのtransportにのみ意味を持つなら、そのシナリオはtransport固有のままにし、シナリオ契約内でそれを明示する。 +- 振る舞いが1つのchannel transportに依存するなら、そのrunner Pluginまたはplugin harness内に保持する。 +- シナリオが複数のchannelで使える新しい機能を必要とするなら、`suite.ts` にchannel固有の分岐を追加するのではなく、汎用helperを追加する。 +- 振る舞いが1つのtransportにしか意味を持たないなら、そのシナリオをtransport固有のものとして保持し、それをシナリオ契約で明示する。 -新しいシナリオ向けの推奨汎用ヘルパー名は以下です。 +新しいシナリオ向けの推奨汎用helper名は次のとおりです。 - `waitForTransportReady` - `waitForChannelReady` @@ -228,7 +232,7 @@ Runner Pluginはtransport契約を所有します。 - `formatTransportTranscript` - `resetTransport` -既存シナリオ向けには、以下を含む互換エイリアスが引き続き利用できます。 +既存シナリオ向けには、次を含む互換エイリアスが引き続き利用できます。 - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -236,98 +240,99 @@ Runner Pluginはtransport契約を所有します。 - `formatConversationTranscript` - `resetBus` -新しいチャネル作業では、汎用ヘルパー名を使う必要があります。 -互換エイリアスは、一斉移行を避けるために存在するのであって、新しいシナリオ作成のモデルではありません。 +新しいchannel作業では、汎用helper名を使用する必要があります。 +互換エイリアスは一斉移行を避けるために存在しており、 +新しいシナリオ作成のモデルではありません。 -## テストスイート（どこで何が動くか） +## テストスイート（どこで何が実行されるか） -スイートは「現実性が増す順」（そして不安定さ/コストも増す順）と考えてください: +スイートは「現実性が増していくもの」（そして不安定さ/コストも増していくもの）として考えてください。 ### 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テスト -- スコープ: +- ファイル: `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） - - 既知のバグに対する決定論的なリグレッション + - プロセス内integrationテスト（gateway auth、routing、tooling、parsing、config） + - 既知のバグに対する決定的なリグレッション - 想定: - CIで実行される - 実際のキーは不要 - 高速で安定しているべき -- 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` は引き続きネイティブルートの `vitest.config.ts` project graphを使います。複数shardのwatchループは現実的でないためです。 - - `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-mode実行をそれらの軽量レーン内の明示的な隣接テストにマッピングするため、helper編集でそのディレクトリのフルheavyスイートを再実行せずに済みます。 - - `auto-reply` には現在、3つの専用バケットがあります: トップレベルのcore helper、トップレベルの `reply.*` integrationテスト、および `src/auto-reply/reply/**` サブツリーです。これにより、最も重いreply harness作業が、軽量なstatus/chunk/tokenテストに乗らないようにします。 -- embedded runnerに関する注記: - - メッセージtool discovery入力またはCompaction runtime contextを変更するときは、両方のレベルのカバレッジを維持してください。 - - 純粋なrouting/normalization境界に対する、焦点を絞ったhelperリグレッションを追加してください。 - - さらに、embedded runner integrationスイートも健全に保ってください: +- 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スイートも健全な状態に保ってください: `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を使います。 - - ルートUIレーンはその `jsdom` setupとoptimizerを維持していますが、現在は共有の非分離runnerでも実行されます。 + - これらのスイートは、スコープ付き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 compile churnを減らします。標準のV8挙動と比較したい場合は `OPENCLAW_VITEST_ENABLE_MAGLEV=1` を設定してください。 -- 高速なローカル反復に関する注記: - - `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-durationレポートとimport-breakdown出力を有効にします。 - - `pnpm test:perf:imports:changed` は、同じプロファイリング表示を `origin/main` 以降に変更されたファイルに限定します。 -- `pnpm test:perf:changed:bench -- --ref ` は、そのコミット済み差分に対するルーティング済み `test:changed` とネイティブルートprojectパスを比較し、wall timeとmacOS max RSSを表示します。 -- `pnpm test:perf:changed:bench -- --worktree` は、変更済みファイル一覧を `scripts/test-projects.mjs` とルートVitest設定経由でルーティングすることで、現在のdirty treeをベンチマークします。 - - `pnpm test:perf:profile:main` は、Vitest/Viteの起動とtransform overhead向けのmain-thread CPU profileを書き出します。 - - `pnpm test:perf:profile:runner` は、ファイル並列性を無効にしたunitスイート向けのrunner CPU+heap profileを書き出します。 + - 共有 `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を書き出します。 -### E2E（Gatewayスモーク） +### E2E（gateway smoke） - コマンド: `pnpm test:e2e` - 設定: `vitest.e2e.config.ts` - ファイル: `src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts` -- ランタイムデフォルト: - - リポジトリの他の部分に合わせて、Vitest `threads` と `isolate: false` を使います。 - - 適応型workerを使います（CI: 最大2、ローカル: デフォルトで1）。 - - コンソールI/O overheadを減らすため、デフォルトでsilent modeで実行します。 +- Runtimeのデフォルト: + - リポジトリの他の部分と同様に、Vitest `threads` を `isolate: false` で使用します。 + - 適応的workerを使用します（CI: 最大2、ローカル: デフォルト1）。 + - console I/Oオーバーヘッドを減らすため、デフォルトでsilent modeで実行します。 - 便利な上書き: - worker数を強制する `OPENCLAW_E2E_WORKERS=`（上限16） - - 詳細なコンソール出力を再度有効にする `OPENCLAW_E2E_VERBOSE=1` -- スコープ: - - 複数インスタンスのGateway end-to-end挙動 - - WebSocket/HTTP surface、Node pairing、およびより重いネットワーキング + - 詳細なconsole出力を再有効化する `OPENCLAW_E2E_VERBOSE=1` +- 範囲: + - 複数インスタンスgatewayのエンドツーエンド動作 + - WebSocket/HTTP surface、node pairing、およびより重いネットワーキング - 想定: - CIで実行される（パイプラインで有効な場合） - 実際のキーは不要 - - unitテストより可動部分が多い（遅くなることがある） + - unitテストよりも可動部分が多い（遅くなることがある） -### E2E: OpenShell backendスモーク +### E2E: OpenShell backend smoke - コマンド: `pnpm test:e2e:openshell` - ファイル: `test/openshell-sandbox.e2e.test.ts` -- スコープ: - - Docker経由でホスト上に分離されたOpenShell Gatewayを起動する +- 範囲: + - Docker経由でホスト上に分離されたOpenShell gatewayを起動する - 一時的なローカルDockerfileからsandboxを作成する - - 実際の `sandbox ssh-config` + SSH execを介してOpenClawのOpenShell backendを実行する - - sandbox fs bridgeを通じてremote-canonical filesystem挙動を検証する + - 実際の `sandbox ssh-config` + SSH execを介してOpenClawのOpenShell backendを検証する + - sandbox fs bridgeを通じてremote-canonical filesystemの挙動を検証する - 想定: - - オプトイン専用。デフォルトの `pnpm test:e2e` 実行には含まれない + - オプトインのみ。デフォルトの `pnpm test:e2e` 実行には含まれない - ローカルの `openshell` CLIと動作するDocker daemonが必要 - - 分離された `HOME` / `XDG_CONFIG_HOME` を使い、その後テストGatewayとsandboxを破棄する + - 分離された `HOME` / `XDG_CONFIG_HOME` を使用し、その後テストgatewayとsandboxを破棄する - 便利な上書き: - - より広いe2eスイートを手動実行するときにテストを有効化する `OPENCLAW_E2E_OPENSHELL=1` - - デフォルト以外のCLI binaryまたは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（実際のプロバイダー + 実際のモデル） @@ -335,142 +340,142 @@ Runner Pluginはtransport契約を所有します。 - 設定: `vitest.live.config.ts` - ファイル: `src/**/*.live.test.ts` - デフォルト: `pnpm test:live` により **有効**（`OPENCLAW_LIVE_TEST=1` を設定） -- スコープ: +- 範囲: - 「このプロバイダー/モデルは、実際の認証情報で _今日_ 本当に動くか？」 - - プロバイダーのフォーマット変更、tool-callingの癖、authの問題、rate limit挙動を検出する + - プロバイダー形式変更、tool-callingの癖、authの問題、rate limitの挙動を検出する - 想定: - 設計上CIで安定しない（実ネットワーク、実プロバイダーポリシー、quota、障害） - - コストがかかる / rate limitを消費する - - 「全部」よりも、絞り込んだサブセットを実行するのを優先する -- live実行は、欠けているAPIキーを取得するために `~/.profile` をsourceします。 -- デフォルトでは、live実行は依然として `HOME` を分離し、config/auth materialを一時テストホームにコピーします。これにより、unit fixtureが実際の `~/.openclaw` を変更できないようにします。 -- liveテストで実際のhomeディレクトリを意図的に使う必要がある場合にのみ、`OPENCLAW_LIVE_USE_REAL_HOME=1` を設定してください。 -- `pnpm test:live` は現在、より静かなモードがデフォルトです。`[live] ...` の進捗出力は維持しますが、追加の `~/.profile` 通知を抑制し、Gateway bootstrapログ/Bonjour chatterをミュートします。完全な起動ログを再び見たい場合は `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応答時に再試行します。 + - 費用がかかる / 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のコンソールキャプチャが静かなときでも活動中であることが見えるよう、進捗行をstderrに出力します。 - - `vitest.live.config.ts` はVitestのコンソールインターセプトを無効にしているため、プロバイダー/Gatewayの進捗行はlive実行中に即時ストリームされます。 + - 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` で調整します。 + - gateway/probeのHeartbeatは `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` で調整します。 ## どのスイートを実行すべきか？ この判断表を使ってください。 -- ロジック/テストを編集している: `pnpm test` を実行する（大きく変更した場合は `pnpm test:coverage` も） -- Gatewayネットワーキング / WS protocol / pairingに触れる: `pnpm test:e2e` を追加する -- 「botが落ちている」問題 / プロバイダー固有の失敗 / tool callingをデバッグしている: 絞り込んだ `pnpm test:live` を実行する +- ロジック/テストを編集している: `pnpm test` を実行する（大きく変更したなら `pnpm test:coverage` も） +- gateway networking / WS protocol / pairingに触れている: `pnpm test:e2e` も追加する +- 「自分のbotが落ちている」/ プロバイダー固有の失敗 / tool callingをデバッグしている: 絞り込んだ `pnpm test:live` を実行する ## Live: Android Node capability sweep - テスト: `src/gateway/android-node.capabilities.live.test.ts` - スクリプト: `pnpm android:test:integration` -- 目標: 接続されたAndroid Nodeが現在公開している **すべてのコマンド** を呼び出し、コマンド契約の挙動を検証する。 -- スコープ: - - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/実行/pairingは行いません）。 - - 選択されたAndroid Nodeに対する、コマンドごとのGateway `node.invoke` 検証。 -- 必要な事前セットアップ: - - AndroidアプリがすでにGatewayに接続済みで、pairing済みであること。 - - アプリが前面に維持されていること。 - - 成功を期待するcapabilityに対して、権限/キャプチャ同意が付与されていること。 -- 任意のターゲット上書き: +- 目的: 接続されたAndroid Nodeが現在通知している **すべてのコマンド** を呼び出し、コマンド契約の挙動を検証する。 +- 範囲: + - 前提条件付き/手動セットアップ（このスイートはアプリのインストール/実行/ペアリングを行いません）。 + - 選択したAndroid Nodeに対するコマンド単位のgateway `node.invoke` 検証。 +- 必須の事前セットアップ: + - Androidアプリがすでにgatewayに接続済みかつペアリング済みであること。 + - アプリがフォアグラウンドに維持されていること。 + - 成功を期待する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) -## Live: modelスモーク（profileキー） +## Live: model smoke（profile keys） -liveテストは、失敗を切り分けられるよう2つのレイヤーに分かれています。 +liveテストは、失敗を切り分けられるよう2つの層に分かれています。 -- 「Direct model」は、与えられたキーでそのプロバイダー/モデルが少なくとも応答できるかを示します。 -- 「Gateway smoke」は、そのモデルに対して完全なGateway+エージェントパイプラインが動作するか（sessions、history、tools、sandbox policyなど）を示します。 +- 「Direct model」は、そのキーでプロバイダー/モデルが少なくとも応答できることを示します。 +- 「Gateway smoke」は、そのモデルに対してgateway+agentパイプライン全体（sessions、history、tools、sandbox policyなど）が機能することを示します。 -### レイヤー1: Direct model completion（Gatewayなし） +### レイヤー1: 直接モデル完了（gatewayなし） - テスト: `src/agents/models.profiles.live.test.ts` -- 目標: - - 発見されたモデルを列挙する - - `getApiKeyForModel` を使って、認証情報を持つモデルを選択する - - モデルごとに小さなcompletionを実行する（必要に応じて対象を絞ったリグレッションも） +- 目的: + - 検出されたモデルを列挙する + - `getApiKeyForModel` を使って、認証情報を持っているモデルを選択する + - モデルごとに小さなcompletionを実行する（必要に応じて対象を絞ったリグレッションも実行する） - 有効化方法: - `pnpm test:live`（またはVitestを直接呼び出す場合は `OPENCLAW_LIVE_TEST=1`） -- このスイートを実際に実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、`modern` のエイリアス）を設定してください。そうしないと、`pnpm test:live` をGatewayスモークに集中させるためスキップされます +- 実際にこのスイートを実行するには `OPENCLAW_LIVE_MODELS=modern`（または `all`、`modern` のエイリアス）を設定します。そうしない場合、このスイートはskipされ、`pnpm test:live` はgateway smokeに集中したままになります。 - モデルの選択方法: - - `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=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 sweepはデフォルトで厳選された高シグナル上限を使います。網羅的なmodern sweepには `OPENCLAW_LIVE_MAX_MODELS=0`、より小さい上限には正の数を設定してください。 + - modern/allスイープはデフォルトで厳選された高シグナル上限を使います。網羅的なmodernスイープには `OPENCLAW_LIVE_MAX_MODELS=0` を、より小さい上限には正の数を設定してください。 - プロバイダーの選択方法: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（カンマ区切りallowlist） - キーの取得元: - - デフォルト: profile storeおよびenv fallback - - **profile store** のみを強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` を設定 + - デフォルト: profile storeとenvフォールバック + - **profile store** のみを強制するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` を設定する - これが存在する理由: - - 「プロバイダーAPIが壊れている / キーが無効」であることと、「Gatewayエージェントパイプラインが壊れている」ことを分離する - - 小さく分離されたリグレッションを含める（例: OpenAI Responses/Codex Responsesのreasoning replay + tool-callフロー） + - 「provider APIが壊れている / キーが無効である」と「gateway agentパイプラインが壊れている」を切り分けるため + - 小さく分離されたリグレッションを収めるため（例: OpenAI Responses/Codex Responsesのreasoning replay + tool-callフロー） -### レイヤー2: Gateway + devエージェントスモーク（`@openclaw` が実際に行うこと） +### レイヤー2: Gateway + dev agent smoke（`@openclaw` が実際に行うこと） - テスト: `src/gateway/gateway-models.profiles.live.test.ts` -- 目標: - - プロセス内Gatewayを起動する - - `agent:dev:*` sessionを作成/patchする（実行ごとのmodel override） - - キーを持つモデル群を反復し、以下を検証する: - - 「意味のある」応答（toolなし） - - 実際のtool呼び出しが動作すること（read probe） +- 目的: + - プロセス内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ファイルを書き込み、エージェントにそれを `read` してnonceを返答でそのまま返すよう求めます。 - - `exec+read` probe: テストはエージェントに `exec` でtempファイルへnonceを書かせ、その後それを `read` で読み戻させます。 - - image probe: テストは生成したPNG（猫 + ランダムコード）を添付し、モデルが `cat ` を返すことを期待します。 - - 実装参照: `src/gateway/gateway-models.profiles.live.test.ts` と `src/gateway/live-image-probe.ts`。 + - 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`。 - 有効化方法: - `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 sweepはデフォルトで厳選された高シグナル上限を使います。網羅的なmodern sweepには `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`、より小さな上限には正の数を設定してください。 -- プロバイダーの選択方法（「OpenRouterを全部」は避ける）: + - 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） -- このliveテストではtool + image probeは常に有効です: - - `read` probe + `exec+read` probe（tool stress） - - image probeは、モデルがimage input supportを公開している場合に実行されます +- Tool + image probeはこのliveテストでは常に有効です: + - `read` probe + `exec+read` probe（toolストレス） + - image入力サポートをモデルが通知している場合はimage probeが実行されます - フロー（高レベル）: - - テストは「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エージェントはmultimodal user messageをモデルへ転送する - - 検証: 返答に `cat` + そのコードが含まれること（OCR許容: 軽微な誤りは許容） + - テストは「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の許容: 軽微な誤りは可） -ヒント: 自分のマシンで何をテストできるか（および正確な `provider/model` id）を確認するには、以下を実行してください。 +ヒント: 自分のマシンで何をテストできるか（および正確な `provider/model` id）を確認するには、次を実行してください。 ```bash openclaw models list openclaw models list --json ``` -## Live: CLI backendスモーク（Claude、Codex、Gemini、またはその他のローカルCLI） +## Live: CLI backend smoke（Claude、Codex、Gemini、またはその他のローカルCLI） - テスト: `src/gateway/gateway-cli-backend.live.test.ts` -- 目標: デフォルトconfigに触れずに、ローカルCLI backendを使ってGateway + エージェントパイプラインを検証する。 -- backend固有のスモークデフォルトは、所有extensionの `cli-backend.ts` 定義にあります。 +- 目的: デフォルトconfigに触れずに、ローカルCLI backendを使ってGateway + agentパイプラインを検証する。 +- backend固有のsmokeデフォルトは、所有するextensionの `cli-backend.ts` 定義にあります。 - 有効化: - `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から取得されます。 + - command/args/imageの挙動は、所有するCLI backend Plugin metadataから取得します。 - 上書き（任意）: - `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 argsとして渡すには `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`。 - - `IMAGE_ARG` が設定されているときにimage argsの渡し方を制御するには `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`（選択したmodelがswitch targetをサポートしているときに強制的に有効化するには `1` を設定）。 + - 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` を設定）。 例: @@ -495,30 +500,30 @@ 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` userとしてlive CLI-backendスモークを実行します。 -- 所有extensionからCLI smoke metadataを解決し、その後、一致するLinux CLI package（`@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キー環境変数を保持せずに、2回のGateway CLI-backendターンを実行します。このsubscriptionレーンでは、Claudeが現在サードパーティapp利用を通常のsubscriptionプラン上限ではなく追加利用課金経由で扱うため、ClaudeのMCP/toolおよびimage probeはデフォルトで無効です。 -- live CLI-backendスモークは現在、Claude、Codex、Geminiに対して同じend-to-endフローを実行します: text turn、image classification turn、その後Gateway CLI経由で検証されるMCP `cron` tool call。 -- Claudeのデフォルトスモークは、sessionをSonnetからOpusへpatchし、再開したsessionが以前のメモをまだ覚えていることも検証します。 +- これは、リポジトリの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が以前のメモを引き続き覚えていることも検証します。 -## Live: ACP bindスモーク（`/acp spawn ... --bind here`） +## Live: ACP bind smoke（`/acp spawn ... --bind here`） - テスト: `src/gateway/gateway-acp-bind.live.test.ts` -- 目標: live ACPエージェントで実際のACP conversation-bindフローを検証する: - - `/acp spawn --bind here` を送る - - syntheticなmessage-channel conversationをその場でbindする - - 同じconversationで通常のfollow-upを送る +- 目的: live ACP agentを使った実際のACP conversation-bindフローを検証する: + - `/acp spawn --bind here` を送信する + - 合成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エージェント: `claude,codex,gemini` - - 直接 `pnpm test:live ...` 用のACPエージェント: `claude` - - synthetic channel: Slack DM風conversation context + - Docker内のACP agent: `claude,codex,gemini` + - 直接の `pnpm test:live ...` 用ACP agent: `claude` + - 合成channel: Slack DM形式のconversation context - ACP backend: `acpx` - 上書き: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -526,9 +531,9 @@ pnpm test:docker:live-cli-backend:gemini - `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@'` -- 注記: - - このレーンはGatewayの `chat.send` surfaceを使い、admin専用のsyntheticなoriginating-route fieldで、外部配信を装わずにmessage-channel contextを付与できるようにしています。 - - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、テストは選択したACP harness agentに対して、embedded `acpx` Pluginの組み込みagent registryを使います。 +- メモ: + - このレーンは、admin専用の合成originating-routeフィールドを持つgateway `chat.send` surfaceを使うため、外部配信を装わずにmessage-channel contextをテストが付与できます。 + - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` が未設定の場合、テストは選択したACP harness agentに対して、組み込み `acpx` Pluginの内蔵agent registryを使用します。 例: @@ -544,7 +549,7 @@ Dockerレシピ: pnpm test:docker:live-acp-bind ``` -単一エージェントのDockerレシピ: +単一agentのDockerレシピ: ```bash pnpm test:docker:live-acp-bind:claude @@ -552,32 +557,33 @@ 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エージェント `claude`、`codex`、`gemini` に対して順にACP bindスモークを実行します。 -- マトリクスを絞り込むには、`OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、または `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` を使ってください。 -- これは `~/.profile` をsourceし、一致するCLI auth materialをcontainerへステージし、`acpx` を書き込み可能なnpm prefixにインストールし、その後、必要なら要求されたlive CLI（`@anthropic-ai/claude-code`、`@openai/codex`、または `@google/gemini-cli`）をインストールします。 -- Docker内では、runnerは `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` を設定し、sourceしたprofile由来のprovider env varsが子harness CLIからも利用できるようにします。 +- デフォルトでは、対応するすべての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で使えるようにします。 -## Live: Codex app-server harnessスモーク +## Live: Codex app-server harness smoke -- 目標: 通常のGateway - `agent` methodを通じて、Plugin所有のCodex harnessを検証する: - - バンドルされた `codex` Pluginを読み込む +- 目的: 通常のgateway + `agent` メソッドを通じて、Plugin所有のCodex harnessを検証する: + - 同梱の `codex` Pluginを読み込む - `OPENCLAW_AGENT_RUNTIME=codex` を選択する - - `codex/gpt-5.4` に対して最初のGateway agent turnを送る - - 同じOpenClaw sessionに2回目のturnを送り、app-server threadがresumeできることを検証する - - 同じGateway command - path経由で `/codex status` と `/codex models` を実行する + - `codex/gpt-5.4` に対して最初のgateway agentターンを送信する + - 同じOpenClaw sessionに2ターン目を送信し、app-server + threadがresumeできることを検証する + - 同じgateway command + パスを通して `/codex status` と `/codex models` を実行する - テスト: `src/gateway/gateway-codex-harness.live.test.ts` - 有効化: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- デフォルトmodel: `codex/gpt-5.4` +- デフォルトモデル: `codex/gpt-5.4` - 任意の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へのサイレントfallbackで通過することはありません。 -- auth: shell/profileの `OPENAI_API_KEY` と、必要に応じてコピーされる +- このsmokeは `OPENCLAW_AGENT_HARNESS_FALLBACK=none` を設定するため、壊れたCodex + harnessがPIへのサイレントフォールバックで通過することはできません。 +- 認証: shell/profile由来の `OPENAI_API_KEY` と、任意でコピーされる `~/.codex/auth.json` および `~/.codex/config.toml` ローカルレシピ: @@ -598,52 +604,52 @@ source ~/.profile pnpm test:docker:live-codex-harness ``` -Dockerに関する注記: +Dockerメモ: - Dockerランナーは `scripts/test-live-codex-harness-docker.sh` にあります。 -- これはマウントされた `~/.profile` をsourceし、`OPENAI_API_KEY` を渡し、Codex CLI - authファイルが存在する場合はそれをコピーし、`@openai/codex` を書き込み可能なマウント済みnpm - prefixにインストールし、source treeをステージした後、Codex-harness liveテストのみを実行します。 -- DockerではimageおよびMCP/tool probeがデフォルトで有効です。より狭いデバッグ実行が必要な場合は、 +- これはマウントされた `~/.profile` を読み込み、`OPENAI_API_KEY` を渡し、存在する場合はCodex CLIの + authファイルをコピーし、`@openai/codex` を書き込み可能でマウントされたnpm + prefixにインストールし、source treeを配置した後、Codex-harness liveテストのみを実行します。 +- DockerではimageおよびMCP/tool probeがデフォルトで有効です。より狭いデバッグ実行が必要な場合は `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` または `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` を設定してください。 -- Dockerも `OPENCLAW_AGENT_HARNESS_FALLBACK=none` をエクスポートし、live - test設定と一致させるため、`openai-codex/*` やPI fallbackがCodex harness - regressionを隠すことはできません。 +- Dockerは `OPENCLAW_AGENT_HARNESS_FALLBACK=none` もエクスポートし、live + テスト設定に合わせるため、`openai-codex/*` やPIへのフォールバックでCodex harness + のリグレッションが隠れることはありません。 ### 推奨liveレシピ -狭く明示的なallowlistが最も高速で不安定さも最小です。 +狭く明示的なallowlistが、最も高速で不安定さも最小です。 -- 単一model、direct（Gatewayなし）: +- 単一モデル、direct（gatewayなし）: - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- 単一model、Gatewayスモーク: +- 単一モデル、gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - 複数プロバイダーにまたがる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 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` +- 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` - 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風エージェントエンドポイント）を使います。 -- `google-gemini-cli/...` はあなたのマシン上のローカルGemini CLIを使います（別個のauth + toolingの癖があります）。 -- Gemini APIとGemini CLIの違い: - - API: OpenClawはGoogleのホストされたGemini APIをHTTP経由で呼び出します（APIキー / profile auth）。これは、ほとんどのユーザーが「Gemini」と言うときに意味しているものです。 - - CLI: OpenClawはローカルの `gemini` binaryをshell outして使います。独自のauthを持ち、挙動も異なることがあります（streaming/tool support/version skew）。 +- `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）。 ## Live: model matrix（何をカバーするか） -固定の「CI model list」はありません（liveはオプトインです）が、キーを持つdevマシンで定期的にカバーすることを**推奨**するモデルは以下です。 +固定の「CI model list」はありません（liveはオプトイン）が、キーを持つ開発マシンで定期的にカバーすることを**推奨**するモデルは次のとおりです。 -### Modernスモークセット（tool calling + image） +### Modern smoke set（tool calling + image） -これは、動作し続けることを期待する「一般的なモデル」実行です。 +これは、動作を維持することが期待される「一般的なモデル」実行です。 - OpenAI（非Codex）: `openai/gpt-5.4`（任意: `openai/gpt-5.4-mini`） - OpenAI Codex: `openai-codex/gpt-5.4` @@ -653,12 +659,12 @@ Dockerに関する注記: - Z.AI（GLM）: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -tools + image付きでGatewayスモークを実行: +tools + image付きでgateway smokeを実行: `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） -少なくとも各プロバイダーファミリーから1つ選んでください。 +少なくともプロバイダーファミリーごとに1つ選んでください。 - OpenAI: `openai/gpt-5.4`（または `openai/gpt-5.4-mini`） - Anthropic: `anthropic/claude-opus-4-6`（または `anthropic/claude-sonnet-4-6`） @@ -668,42 +674,42 @@ tools + image付きでGatewayスモークを実行: 任意の追加カバレッジ（あると望ましい）: -- xAI: `xai/grok-4`（または利用可能な最新） -- Mistral: `mistral/`…（有効化されている「tools」対応モデルを1つ選ぶ） -- Cerebras: `cerebras/`…（アクセスできる場合） +- xAI: `xai/grok-4`（または利用可能な最新版） +- Mistral: `mistral/`…（有効化済みの「tools」対応モデルを1つ選ぶ） +- Cerebras: `cerebras/`…（アクセスがある場合） - LM Studio: `lmstudio/`…（ローカル。tool callingはAPI modeに依存） -### Vision: image送信（attachment → multimodal message） +### Vision: image send（attachment → multimodal message） -image probeを実行するために、少なくとも1つのimage対応モデル（Claude/Gemini/OpenAIのvision対応バリアントなど）を `OPENCLAW_LIVE_GATEWAY_MODELS` に含めてください。 +image probeを実行するために、少なくとも1つのimage対応モデルを `OPENCLAW_LIVE_GATEWAY_MODELS` に含めてください（Claude/Gemini/OpenAIのvision対応バリアントなど）。 -### Aggregator / 代替Gateway +### Aggregators / alternate gateways -キーが有効なら、以下経由でのテストもサポートしています。 +キーが有効であれば、次経由のテストもサポートしています。 -- OpenRouter: `openrouter/...`（数百のモデル。tool+image対応候補を見つけるには `openclaw models scan` を使用） -- OpenCode: Zen向けの `opencode/...` と、Go向けの `opencode-go/...`（authは `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`） +- OpenRouter: `openrouter/...`（数百のモデル。tool+image対応候補を見つけるには `openclaw models scan` を使ってください） +- OpenCode: Zen向けの `opencode/...` とGo向けの `opencode-go/...`（authは `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` 経由（カスタムエンドポイント）: `minimax`（cloud/API）、およびOpenAI/Anthropic互換の任意のproxy（LM Studio、vLLM、LiteLLMなど） +- 組み込み: `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など） -ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。権威ある一覧は、あなたのマシン上で `discoverModels(...)` が返すものと、利用可能なキーによって決まります。 +ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。権威ある一覧は、あなたのマシン上で `discoverModels(...)` が返すものと、利用可能なキーの組み合わせです。 ## 認証情報（絶対にコミットしない） -liveテストは、CLIと同じ方法で認証情報を見つけます。実務上の意味は以下です。 +liveテストは、CLIと同じ方法で認証情報を検出します。実用上の意味は次のとおりです。 - CLIが動くなら、liveテストも同じキーを見つけられるはずです。 -- liveテストが「認証情報なし」と言うなら、`openclaw models list` / model選択をデバッグするときと同じ方法でデバッグしてください。 +- 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/`（存在する場合はステージされたlive homeにコピーされますが、メインのprofile-key storeではありません） -- ローカルのlive実行は、デフォルトでアクティブなconfig、エージェントごとの `auth-profiles.json` ファイル、レガシー `credentials/`、およびサポートされる外部CLI authディレクトリを一時的なテストhomeへコピーします。ステージされたlive homeでは `workspace/` と `sandboxes/` をスキップし、`agents.*.workspace` / `agentDir` のパス上書きも削除されるため、probeが実際のホストworkspaceに触れないようになっています。 +- レガシー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に触れません。 -envキー（たとえば `~/.profile` でexportしたもの）に依存したい場合は、`source ~/.profile` の後にローカルテストを実行するか、以下のDockerランナーを使ってください（これらは `~/.profile` をcontainer内にマウントできます）。 +envキー（たとえば `~/.profile` にexportされたもの）に依存したい場合は、`source ~/.profile` の後にローカルテストを実行するか、以下のDockerランナーを使ってください（これらは `~/.profile` をコンテナにマウントできます）。 ## Deepgram live（音声文字起こし） @@ -714,33 +720,33 @@ envキー（たとえば `~/.profile` でexportしたもの）に依存したい - テスト: `src/agents/byteplus.live.test.ts` - 有効化: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- 任意のmodel上書き: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- 任意のモデル上書き: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## ComfyUI workflow media live - テスト: `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をスキップする - - comfy workflow submission、polling、downloads、またはPlugin registrationを変更した後に有用 +- 範囲: + - 同梱comfyのimage、video、および `music_generate` パスを検証する + - `models.providers.comfy.` が設定されていない場合は各capabilityをskipする + - comfy workflow送信、polling、download、またはPlugin登録を変更した後に有用 ## Image generation live - テスト: `src/image-generation/runtime.live.test.ts` - コマンド: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` -- スコープ: +- 範囲: - 登録されているすべてのimage-generation provider Pluginを列挙する - - probe前にログインshell（`~/.profile`）から不足しているprovider env varsを読み込む - - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠さない - - 使用可能なauth/profile/modelがないproviderはスキップする - - 共有runtime capabilityを通じて標準のimage-generationバリアントを実行する: + - probe前にlogin shell（`~/.profile`）から不足しているprovider env varsを読み込む + - デフォルトでは保存済みauth profileよりもlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠しません + - 使用可能なauth/profile/modelがないプロバイダーはskipする + - 共有runtime capabilityを通じて、標準のimage-generationバリアントを実行する: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- 現在カバーされているバンドルprovider: +- 現在カバーされている同梱プロバイダー: - `openai` - `google` - 任意の絞り込み: @@ -748,74 +754,74 @@ envキー（たとえば `~/.profile` でexportしたもの）に依存したい - `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挙動: - - profile-store authを強制し、env-only上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でprofile-store authを強制し、envのみの上書きを無視する ## Music generation 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` -- スコープ: - - 共有のバンドルされたmusic-generation providerパスを実行する +- 範囲: + - 共有の同梱music-generation providerパスを検証する - 現在はGoogleとMiniMaxをカバーする - - probe前にログインshell（`~/.profile`）からprovider env varsを読み込む - - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠さない - - 使用可能なauth/profile/modelがないproviderはスキップする + - probe前にlogin shell（`~/.profile`）からprovider env varsを読み込む + - デフォルトでは保存済みauth profileよりもlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠しません + - 使用可能なauth/profile/modelがないプロバイダーはskipする - 利用可能な場合は、宣言された両方のruntime modeを実行する: - - promptのみ入力の `generate` - - providerが `capabilities.edit.enabled` を宣言している場合の `edit` + - prompt-only入力による `generate` + - プロバイダーが `capabilities.edit.enabled` を宣言している場合の `edit` - 現在の共有レーンカバレッジ: - `google`: `generate`、`edit` - `minimax`: `generate` - - `comfy`: この共有sweepではなく、別の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挙動: - - profile-store authを強制し、env-only上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でprofile-store authを強制し、envのみの上書きを無視する ## Video generation 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` -- スコープ: - - 共有のバンドルされたvideo-generation providerパスを実行する - - デフォルトでは、リリース安全なスモークパスを使います: FAL以外のprovider、providerごとに1回のtext-to-videoリクエスト、1秒のlobster prompt、そして `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`（デフォルト `180000`）によるproviderごとのoperation上限 - - provider側のqueue latencyがリリース時間を支配することがあるため、FALはデフォルトでスキップされます。明示的に実行するには `--video-providers fal` または `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` を渡してください - - probe前にログインshell（`~/.profile`）からprovider env varsを読み込む - - デフォルトでは、保存済みauth profileよりlive/env APIキーを優先して使うため、`auth-profiles.json` 内の古いテストキーが実際のshell認証情報を隠さない - - 使用可能なauth/profile/modelがないproviderはスキップする +- 範囲: + - 共有の同梱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する - デフォルトでは `generate` のみを実行する - - 利用可能な場合に宣言されたtransform modeも実行するには `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` を設定: - - providerが `capabilities.imageToVideo.enabled` を宣言し、選択されたprovider/modelが共有sweep内でbuffer-backedなローカルimage入力を受け付ける場合の `imageToVideo` - - providerが `capabilities.videoToVideo.enabled` を宣言し、選択されたprovider/modelが共有sweep内でbuffer-backedなローカルvideo入力を受け付ける場合の `videoToVideo` - - 現在、共有sweepで宣言されているがスキップされる `imageToVideo` provider: - - `vydra`。バンドルされた `veo3` はtext-onlyで、バンドルされた `kling` はリモートimage URLを必要とするため - - provider固有のVydraカバレッジ: + - 利用可能な場合に宣言済み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カバレッジ: - `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` レーンを実行します + - このファイルは、`veo3` のtext-to-videoと、デフォルトでリモートimage URL fixtureを使う `kling` レーンを実行する - 現在の `videoToVideo` liveカバレッジ: - - 選択されたmodelが `runway/gen4_aleph` の場合の `runway` のみ - - 現在、共有sweepで宣言されているがスキップされる `videoToVideo` provider: - - `alibaba`、`qwen`、`xai`。これらのパスは現在、リモートの `http(s)` / MP4 reference URLを必要とするため - - `google`。現在の共有Gemini/Veoレーンはローカルのbuffer-backed入力を使っており、そのパスは共有sweepでは受け付けられないため - - `openai`。現在の共有レーンではorg固有のvideo inpaint/remixアクセス保証がないため + - 選択したモデルが `runway/gen4_aleph` のときのみ `runway` + - 共有スイープで現在は宣言済みだがskipされる `videoToVideo` プロバイダー: + - `alibaba`、`qwen`、`xai`。これらのパスは現在リモート `http(s)` / MP4 reference URLを必要とするため + - `google`。現在の共有Gemini/Veoレーンはローカルのbuffer-backed入力を使っており、そのパスは共有スイープでは受け付けられないため + - `openai`。現在の共有レーンには組織固有の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"` - - デフォルトsweep内のFALを含むすべてのproviderを含めるには `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` - - 積極的なスモーク実行向けに各providerのoperation上限を下げるには `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` + - FALを含むデフォルトスイープ内のすべてのプロバイダーを含めるには `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` + - 攻めたsmoke実行のために各プロバイダーの操作上限を短くするには `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` - 任意のauth挙動: - - profile-store authを強制し、env-only上書きを無視するには `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` でprofile-store authを強制し、envのみの上書きを無視する ## Media live harness - コマンド: `pnpm test:live:media` - 目的: - - 共有のimage、music、videoのliveスイートを、リポジトリネイティブな1つのentrypoint経由で実行する - - `~/.profile` から不足しているprovider env varsを自動で読み込む - - デフォルトでは、現在使用可能なauthを持つproviderに各スイートを自動で絞り込む + - 共有のimage、music、video liveスイートを、1つのリポジトリネイティブentrypoint経由で実行する + - `~/.profile` から不足しているprovider env varsを自動読み込みする + - デフォルトで、現在使用可能なauthを持つプロバイダーに各スイートを自動で絞り込む - `scripts/test-live.mjs` を再利用するため、Heartbeatおよびquiet-modeの挙動が一貫する - 例: - `pnpm test:live:media` @@ -825,182 +831,186 @@ envキー（たとえば `~/.profile` でexportしたもの）に依存したい ## 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` もsourceします）。対応するローカルentrypointは `test:live:models-profiles` と `test:live:gateway-profiles` です。 -- Docker liveランナーは、完全なDocker sweepを現実的に保つため、デフォルトでより小さなスモーク上限を使います: - `test:docker:live-models` はデフォルトで `OPENCLAW_LIVE_MAX_MODELS=12`、 +- 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`、および `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を1回だけbuildし、その後2つのlive Dockerレーンで再利用します。 -- containerスモークランナー: `test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:plugins` は、1つ以上の実コンテナを起動し、より高レベルなintegration pathを検証します。 + `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パスを検証します。 -live-model Dockerランナーは、必要なCLI auth homeのみ（または実行が絞り込まれていない場合はサポートされるものすべて）をbind-mountし、その後実行前にcontainer homeへコピーします。これにより、外部CLI OAuthがホストのauth storeを変更せずにトークンを更新できます。 +live-model Dockerランナーは、必要なCLI auth homeだけをbind-mountし（実行が絞り込まれていない場合はサポート対象すべて）、その後、外部CLI OAuthがホストauth storeを変更せずにトークンを更新できるよう、実行前にそれらをコンテナhomeにコピーします。 - Direct models: `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 backendスモーク: `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エージェント: `pnpm test:docker:live-gateway`（スクリプト: `scripts/test-live-gateway-models-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ネットワーキング（2つのcontainer、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（installスモーク + `/plugin` エイリアス + Claude-bundle restart semantics）: `pnpm test:docker:plugins`（スクリプト: `scripts/e2e/plugins-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`） +- 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`） -live-model Dockerランナーは、現在のcheckoutも読み取り専用でbind-mountし、container内の一時workdirへステージします。これにより、runtime -imageをスリムに保ちながら、正確にあなたのローカルsource/configに対してVitestを実行できます。 -ステージング手順では、大きなローカル専用キャッシュやアプリbuild出力、たとえば +live-model Dockerランナーは、現在のcheckoutもread-onlyでbind-mountし、 +コンテナ内の一時workdirにそれを配置します。これによりruntime +imageをスリムに保ちつつ、正確にあなたのローカルsource/configに対してVitestを実行できます。 +この配置ステップでは、大きなローカル専用キャッシュやアプリbuild出力、たとえば `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`、およびアプリローカルの `.build` や -Gradle出力ディレクトリをスキップするため、Docker live実行がマシン固有artifactのコピーに何分も費やすことはありません。 -また、container内で実際のTelegram/Discordなどのchannel workerを起動しないよう、 -`OPENCLAW_SKIP_CHANNELS=1` も設定します。 -`test:docker:live-models` は依然として `pnpm test:live` を実行するため、 -そのDockerレーンからGateway liveカバレッジを絞り込んだり除外したりする必要がある場合は、 +Gradle出力ディレクトリをskipするため、Docker live実行が +マシン固有アーティファクトのコピーに何分も費やしません。 +また、`OPENCLAW_SKIP_CHANNELS=1` も設定するため、gateway live probeが +コンテナ内で実際のTelegram/Discordなどのchannel workerを起動しません。 +`test:docker:live-models` は引き続き `pnpm test:live` を実行するため、 +そのDockerレーンでgateway liveカバレッジを絞り込んだり除外したりする必要がある場合は `OPENCLAW_LIVE_GATEWAY_*` も渡してください。 -`test:docker:openwebui` は、より高レベルな互換性スモークです。これは -OpenAI互換HTTPエンドポイントを有効にしたOpenClaw Gateway containerを起動し、 -そのGatewayに対して固定版のOpen WebUI containerを起動し、Open WebUI経由でサインインし、 +`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リクエストを送信します。 +Open WebUIの `/api/chat/completions` proxyを通して実際のchatリクエストを送信します。 初回実行は、Dockerが -Open WebUI imageをpullする必要があったり、Open WebUI自身のcold-start setupを完了する必要があったりするため、目立って遅いことがあります。 -このレーンは使用可能なlive model keyを必要とし、Docker化された実行でそれを提供する主な方法は -`OPENCLAW_PROFILE_FILE`（デフォルトは `~/.profile`）です。 -成功した実行では、`{ "ok": true, "model": +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:mcp-channels` は意図的に決定論的であり、 -実際のTelegram、Discord、またはiMessageアカウントを必要としません。これはseed済みGateway -containerを起動し、`openclaw mcp serve` を起動する2つ目のcontainerを立ち上げ、その後 -ルーティングされたconversation discovery、transcript読み取り、attachment metadata、 -live event queue挙動、outbound送信ルーティング、およびClaude風のchannel + -permission通知を、実際のstdio MCP bridge上で検証します。通知チェックは -生のstdio MCP frameを直接検査するため、このスモークは特定のclient SDKがたまたまsurfaceするものではなく、 -bridgeが実際に発行するものを検証します。 +`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が実際に何を出力するかを検証します。 -手動ACP平文threadスモーク（CIではない）: +手動ACP平文thread smoke（CIではない）: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- このスクリプトはリグレッション/デバッグワークフロー用に維持してください。ACP thread routing検証のために再び必要になる可能性があるので、削除しないでください。 +- このスクリプトはリグレッション/デバッグワークフロー用に保持してください。ACP thread routing検証で再度必要になる可能性があるため、削除しないでください。 便利なenv var: - `OPENCLAW_CONFIG_DIR=...`（デフォルト: `~/.openclaw`）を `/home/node/.openclaw` にマウント - `OPENCLAW_WORKSPACE_DIR=...`（デフォルト: `~/.openclaw/workspace`）を `/home/node/.openclaw/workspace` にマウント -- `OPENCLAW_PROFILE_FILE=...`（デフォルト: `~/.profile`）を `/home/node/.profile` にマウントし、テスト実行前にsource -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` で、`OPENCLAW_PROFILE_FILE` からsourceした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...` 配下にマウントされ、その後テスト開始前に `/home/node/...` へコピーされる +- `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/...` にコピーされる - デフォルトディレクトリ: `.minimax` - デフォルトファイル: `~/.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=...` -- container内でproviderをフィルタする `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` -- build不要の再実行で既存の `openclaw:local-live` imageを再利用する `OPENCLAW_SKIP_DOCKER_BUILD=1` -- 認証情報がprofile store由来であることを保証する `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`（envではない） -- Open WebUIスモークでGatewayが公開するmodelを選ぶ `OPENCLAW_OPENWEBUI_MODEL=...` -- Open WebUIスモークで使うnonceチェックpromptを上書きする `OPENCLAW_OPENWEBUI_PROMPT=...` -- 固定されたOpen WebUI image tagを上書きする `OPENWEBUI_IMAGE=...` + - 絞り込み済みプロバイダー実行では、`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=...` -## Docsの健全性確認 +## ドキュメントの健全性確認 -ドキュメント編集後はdocsチェックを実行してください: `pnpm check:docs`。 +ドキュメント編集後はdocsチェックを実行してください: `pnpm check:docs`。 ページ内見出しチェックも必要な場合は、完全なMintlify anchor検証を実行してください: `pnpm docs:check-links:anchors`。 -## Offlineリグレッション（CI-safe） +## オフラインリグレッション（CI-safe） -これらは、実プロバイダーなしでの「実際のパイプライン」リグレッションです。 +これらは、実際のプロバイダーなしでの「実際のパイプライン」リグレッションです。 -- Gateway tool calling（mock OpenAI、実際のGateway + エージェントループ）: `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 enforcedを書き込む）: `src/gateway/gateway.test.ts`（ケース: "runs wizard over ws and writes auth token config"） -## エージェント信頼性eval（Skills） +## Agent reliability evals（Skills） -すでに、いくつかのCI-safeな、いわば「エージェント信頼性eval」のようなテストがあります。 +すでに、次のようなCI-safeテストがいくつかあり、「agent reliability evals」のように振る舞います。 -- 実際のGateway + エージェントループを通じたmock tool-calling（`src/gateway/gateway.test.ts`）。 -- session配線とconfig効果を検証するend-to-endのウィザードフロー（`src/gateway/gateway.test.ts`）。 +- 実際のgateway + agent loopを通したmock tool-calling（`src/gateway/gateway.test.ts`）。 +- session wiringとconfig効果を検証するend-to-endウィザードフロー（`src/gateway/gateway.test.ts`）。 -Skillsについてまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: +Skillsに関してまだ不足しているもの（[Skills](/ja-JP/tools/skills) を参照）: -- **意思決定:** prompt内にSkillsが列挙されているとき、エージェントは正しいskillを選ぶか（または無関係なものを避けるか）？ -- **準拠:** エージェントは使用前に `SKILL.md` を読み、必須の手順/引数に従うか？ -- **ワークフロー契約:** tool順序、session historyの引き継ぎ、sandbox boundaryを検証する複数ターンのシナリオ。 +- **Decisioning:** promptにSkillsが列挙されているとき、agentは適切なskillを選ぶか（または無関係なものを避けるか）？ +- **Compliance:** agentは使用前に `SKILL.md` を読み、必要な手順/引数に従うか？ +- **Workflow contracts:** tool順序、session履歴の引き継ぎ、sandbox境界を検証するマルチターンシナリオ。 -今後のevalは、まず決定論的であるべきです。 +将来のevalは、まず決定的であることを維持すべきです。 -- mock providerを使ってtool call + 順序、skillファイル読み取り、session配線を検証するscenario runner。 -- skillに焦点を当てた小規模なシナリオスイート（使う/使わない、ゲーティング、prompt injection）。 -- CI-safeスイートが整ってからの、任意のlive eval（オプトイン、env gate付き）のみ。 +- mock providerを使ってtool呼び出し + 順序、skillファイル読み取り、session配線を検証するscenario runner。 +- skillに焦点を当てた小規模シナリオスイート（使う vs 使わない、gating、prompt injection）。 +- CI-safeスイートが整った後にのみ、任意のlive eval（オプトイン、env-gated）。 -## Contractテスト（Pluginおよびchannel shape） +## 契約テスト（Pluginおよびchannelの形状） -Contractテストは、登録されているすべてのPluginとchannelが -そのinterface contractに準拠していることを検証します。検出されたすべてのPluginを反復し、 -shapeと挙動の検証スイートを実行します。デフォルトの `pnpm test` unitレーンは意図的に -これらの共有seamおよびスモークファイルをスキップするため、共有channelまたはprovider surfaceに触れたときは -Contractコマンドを明示的に実行してください。 +契約テストは、登録されたすべてのPluginおよびchannelが、それぞれの +interface契約に準拠していることを検証します。検出されたすべてのPluginを反復し、 +形状と振る舞いに関する一連の検証を実行します。デフォルトの `pnpm test` unitレーンは、 +これらの共有seamおよびsmokeファイルを意図的にskipします。共有channelまたはprovider surfaceに触れた場合は、 +契約コマンドを明示的に実行してください。 ### コマンド -- すべてのcontract: `pnpm test:contracts` -- channel contractのみ: `pnpm test:contracts:channels` -- provider contractのみ: `pnpm test:contracts:plugins` +- すべての契約: `pnpm test:contracts` +- channel契約のみ: `pnpm test:contracts:channels` +- provider契約のみ: `pnpm test:contracts:plugins` -### channel contract +### Channel契約 `src/channels/plugins/contracts/*.contract.test.ts` にあります: -- **plugin** - 基本的なPlugin shape（id、name、capabilities） -- **setup** - セットアップ ウィザード契約 -- **session-binding** - Session bindingの挙動 -- **outbound-payload** - メッセージpayload構造 -- **inbound** - inboundメッセージ処理 +- **plugin** - 基本的なPlugin形状（id、name、capabilities） +- **setup** - セットアップウィザード契約 +- **session-binding** - session bindingの挙動 +- **outbound-payload** - message payload構造 +- **inbound** - inbound message処理 - **actions** - channel action handler - **threading** - thread ID処理 - **directory** - directory/roster API -- **group-policy** - グループポリシーの適用 +- **group-policy** - group policyの強制 -### provider status contract +### Provider status契約 `src/plugins/contracts/*.contract.test.ts` にあります。 - **status** - channel status probe -- **registry** - Plugin registry shape +- **registry** - Plugin registry形状 -### provider contract +### Provider契約 `src/plugins/contracts/*.contract.test.ts` にあります: -- **auth** - authフロー契約 -- **auth-choice** - authの選択/選定 +- **auth** - auth flow契約 +- **auth-choice** - auth choice/selection - **catalog** - model catalog API - **discovery** - Plugin discovery - **loader** - Plugin loading - **runtime** - provider runtime - **shape** - Plugin shape/interface -- **wizard** - セットアップ ウィザード +- **wizard** - セットアップウィザード ### 実行するタイミング - plugin-sdkのexportまたはsubpathを変更した後 - channelまたはprovider Pluginを追加または変更した後 -- Plugin registrationまたはdiscoveryをリファクタリングした後 +- Plugin登録またはdiscoveryをリファクタリングした後 -ContractテストはCIで実行され、実際のAPIキーは不要です。 +契約テストはCIで実行され、実際のAPIキーは不要です。 ## リグレッションを追加する（ガイダンス） liveで見つかったprovider/modelの問題を修正するとき: -- 可能であればCI-safeなリグレッションを追加してください（providerのmock/stub、または正確なrequest-shape変換のキャプチャ） -- 本質的にlive-onlyな場合（rate limit、authポリシー）は、liveテストを狭く保ち、env var経由のオプトインにしてください -- バグを捕捉できる最小のレイヤーを狙うことを優先してください: - - provider request conversion/replayバグ → direct modelsテスト - - Gateway session/history/tool pipelineバグ → Gateway liveスモークまたはCI-safeなGateway mockテスト +- 可能なら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 classごとに1つのサンプルtargetを導出し、その後、traversal-segment exec idが拒否されることを検証します。 - - `src/secrets/target-registry-data.ts` に新しい `includeInPlan` SecretRef target familyを追加する場合は、そのテスト内の `classifyTargetClass` を更新してください。このテストは、未分類のtarget idに対して意図的に失敗するため、新しいclassが黙ってスキップされることはありません。 + - `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されることはありません。 diff --git a/docs/ja-JP/platforms/macos.md b/docs/ja-JP/platforms/macos.md index 4f96ead5c..f95f35711 100644 --- a/docs/ja-JP/platforms/macos.md +++ b/docs/ja-JP/platforms/macos.md @@ -1,76 +1,68 @@ --- read_when: - - macOS appの機能を実装している場合 - - macOSでgatewayライフサイクルまたはnodeブリッジを変更している場合 -summary: OpenClaw macOS companion app（メニューバー + gatewayブローカー） -title: macOS App + - macOSアプリ機能の実装 + - macOSでのGatewayライフサイクルまたはNodeブリッジの変更 +summary: OpenClaw macOSコンパニオンアプリ（メニューバー + Gatewayブローカー） +title: macOSアプリ x-i18n: - generated_at: "2026-04-05T12:51:27Z" + generated_at: "2026-04-18T04:40:13Z" model: gpt-5.4 provider: openai - source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135 + source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0 source_path: platforms/macos.md workflow: 15 --- -# OpenClaw macOS Companion（メニューバー + gatewayブローカー） +# OpenClaw macOS Companion（メニューバー + Gatewayブローカー） -macOS appは、OpenClawの**メニューバーコンパニオン**です。権限を管理し、 -ローカルでGatewayを管理または接続し（launchdまたは手動）、macOSの -機能をnodeとしてagentに公開します。 +macOSアプリは、OpenClawの**メニューバーコンパニオン**です。権限を管理し、ローカルでGatewayを管理または接続し（launchdまたは手動）、macOSの機能をノードとしてエージェントに公開します。 -## 何をするか +## できること -- メニューバーにネイティブ通知とステータスを表示します。 -- TCCプロンプト（Notifications、Accessibility、Screen Recording、Microphone、 - Speech Recognition、Automation/AppleScript）を管理します。 -- Gatewayを実行または接続します（localまたはremote）。 +- ネイティブ通知とステータスをメニューバーに表示します。 +- TCCプロンプト（通知、アクセシビリティ、画面収録、マイク、音声認識、Automation/AppleScript）を管理します。 +- Gatewayを実行または接続します（ローカルまたはリモート）。 - macOS専用ツール（Canvas、Camera、Screen Recording、`system.run`）を公開します。 -- **remote** modeではローカルnode host serviceを開始し（launchd）、**local** modeでは停止します。 -- 必要に応じて **PeekabooBridge** をホストします。 -- 要求に応じてnpm、pnpm、またはbun経由でグローバルCLI（`openclaw`）をインストールします - （appはnpm、次にpnpm、最後にbunを優先します。Nodeは引き続き推奨されるGatewayランタイムです）。 +- **remote**モードではローカルのノードホストサービスを起動し（launchd）、**local**モードでは停止します。 +- 必要に応じて、UIオートメーション用の**PeekabooBridge**をホストします。 +- リクエストに応じて、グローバルCLI（`openclaw`）をnpm、pnpm、またはbun経由でインストールします（アプリはnpm、次にpnpm、最後にbunを優先します。Nodeは引き続き推奨されるGatewayランタイムです）。 -## local modeとremote mode +## localモードとremoteモード -- **Local**（デフォルト）: appは、実行中のローカルGatewayがあればそこへ接続します。 - なければ `openclaw gateway install` 経由でlaunchd serviceを有効化します。 -- **Remote**: appはSSH/Tailscale経由でGatewayへ接続し、ローカルprocessは決して起動しません。 - appはローカルの**node host service**を起動し、remote GatewayがこのMacへ到達できるようにします。 - appはGatewayを子プロセスとして起動しません。 - Gateway discoveryは現在、raw tailnet IPよりもTailscale MagicDNS名を優先するため、 - tailnet IPが変わったときでもMac appはより確実に復旧できます。 +- **Local**（デフォルト）: 実行中のローカルGatewayがあればアプリはそれに接続します。ない場合は、`openclaw gateway install` を使ってlaunchdサービスを有効にします。 +- **Remote**: アプリはSSH/Tailscale経由でGatewayに接続し、ローカルプロセスを起動しません。 + アプリはローカルの**ノードホストサービス**を起動して、リモートGatewayがこのMacに到達できるようにします。 + アプリはGatewayを子プロセスとして起動しません。 + Gateway検出は現在、生のtailnet IPよりもTailscale MagicDNS名を優先するため、tailnet IPが変わった場合でもMacアプリはより確実に復旧できます。 ## Launchd制御 -appは、ユーザーごとのLaunchAgent `ai.openclaw.gateway` -（`--profile`/`OPENCLAW_PROFILE` 使用時は `ai.openclaw.`。legacyな `com.openclaw.*` も引き続きunload対象）を管理します。 +アプリは、ユーザーごとのLaunchAgent `ai.openclaw.gateway` を管理します（`--profile`/`OPENCLAW_PROFILE`使用時は `ai.openclaw.`、従来の `com.openclaw.*` も引き続きアンロードされます）。 ```bash launchctl kickstart -k gui/$UID/ai.openclaw.gateway launchctl bootout gui/$UID/ai.openclaw.gateway ``` -名前付きprofileで実行している場合は、ラベルを `ai.openclaw.` に置き換えてください。 +名前付きプロファイルを実行する場合は、ラベルを `ai.openclaw.` に置き換えてください。 -LaunchAgentがインストールされていない場合は、appから有効化するか、 -`openclaw gateway install` を実行してください。 +LaunchAgentがインストールされていない場合は、アプリから有効にするか、`openclaw gateway install` を実行してください。 -## Node capabilities（mac） +## Nodeの機能（mac） -macOS appは自分自身をnodeとして提示します。一般的なコマンド: +macOSアプリは自身をNodeとして提示します。よく使うコマンド: - Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*` - Camera: `camera.snap`, `camera.clip` -- Screen: `screen.record` +- Screen: `screen.snapshot`, `screen.record` - System: `system.run`, `system.notify` -nodeは `permissions` マップを報告し、agentsが何が許可されているか判断できるようにします。 +Nodeは、エージェントが何を許可するか判断できるように `permissions` マップを報告します。 -Node service + app IPC: +Nodeサービス + アプリIPC: -- ヘッドレスのnode host serviceが実行中（remote mode）であるとき、それはnodeとしてGateway WSへ接続します。 -- `system.run` はローカルUnix socket経由でmacOS app（UI/TCCコンテキスト）内で実行されます。プロンプトと出力はapp内にとどまります。 +- ヘッドレスのノードホストサービスが実行中の場合（remoteモード）、NodeとしてGateway WSに接続します。 +- `system.run` はローカルUnixソケット経由でmacOSアプリ内（UI/TCCコンテキスト）で実行されます。プロンプトと出力はアプリ内に留まります。 図（SCI）: @@ -81,10 +73,10 @@ Gateway -> Node Service (WS) Mac App (UI + TCC + system.run) ``` -## Exec approvals（`system.run`） +## 実行承認（system.run） -`system.run` は、macOS app内の**Exec approvals**（Settings → Exec approvals）で制御されます。 -Security + ask + allowlistは、Mac上の次の場所にローカル保存されます: +`system.run` は、macOSアプリ内の**Exec approvals**（Settings → Exec approvals）で制御されます。 +セキュリティ + 確認 + 許可リストは、Mac上の以下にローカル保存されます: ``` ~/.openclaw/exec-approvals.json @@ -111,120 +103,101 @@ Security + ask + allowlistは、Mac上の次の場所にローカル保存され 注意: -- `allowlist` エントリは、解決済みバイナリパスに対するglobパターンです。 -- shell制御または展開構文（`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`）を含む - 生のshell command textはallowlist missとして扱われ、明示的承認が必要です - （またはshell binary自体をallowlistする必要があります）。 -- プロンプトで「Always Allow」を選ぶと、そのcommandがallowlistに追加されます。 -- `system.run` のenvironment overridesはフィルタされ（`PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4` を削除）、 - その後appのenvironmentとマージされます。 -- shell wrapper（`bash|sh|zsh ... -c/-lc`）では、request単位のenvironment overridesは、 - 小さな明示allowlist（`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`）に絞られます。 -- allowlist modeでのallow-always判断では、既知のdispatch wrapper（`env`, `nice`, `nohup`, `stdbuf`, `timeout`）については、 - wrapper pathではなく内側の実行ファイルパスが永続化されます。安全にunwrapできない場合は、 - allowlistエントリは自動では永続化されません。 +- `allowlist` エントリーは、解決済みバイナリパスに対するglobパターンです。 +- シェル制御または展開構文（`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`）を含む生のシェルコマンドテキストは、allowlistミスとして扱われ、明示的な承認が必要です（またはシェルバイナリをallowlistに追加する必要があります）。 +- プロンプトで「Always Allow」を選ぶと、そのコマンドがallowlistに追加されます。 +- `system.run` の環境変数オーバーライドはフィルタリングされ（`PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4` を除外）、その後アプリの環境変数とマージされます。 +- シェルラッパー（`bash|sh|zsh ... -c/-lc`）では、リクエスト単位の環境変数オーバーライドは、小さな明示的allowlist（`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`）に縮小されます。 +- allowlistモードで「常に許可」を選択した場合、既知のディスパッチラッパー（`env`, `nice`, `nohup`, `stdbuf`, `timeout`）では、ラッパーパスではなく内部の実行ファイルパスが保存されます。安全にアンラップできない場合、allowlistエントリーは自動保存されません。 ## ディープリンク -appはローカルアクション用に `openclaw://` URL schemeを登録します。 +アプリはローカルアクション用に `openclaw://` URLスキームを登録します。 ### `openclaw://agent` Gatewayの `agent` リクエストをトリガーします。 __OC_I18N_900004__ -クエリパラメーター: +クエリパラメータ: - `message`（必須） - `sessionKey`（任意） - `thinking`（任意） - `deliver` / `to` / `channel`（任意） - `timeoutSeconds`（任意） -- `key`（任意、unattended modeキー） +- `key`（任意の無人モードキー） 安全性: -- `key` がない場合、appは確認を求めます。 -- `key` がない場合、appは確認プロンプトに対して短いメッセージ上限を適用し、`deliver` / `to` / `channel` は無視します。 -- 有効な `key` がある場合、その実行はunattendedになります（個人用automation向け）。 +- `key` がない場合、アプリは確認を求めます。 +- `key` がない場合、アプリは確認プロンプト用に短いメッセージ長制限を適用し、`deliver` / `to` / `channel` を無視します。 +- 有効な `key` がある場合、実行は無人で行われます（個人用オートメーション向け）。 -## オンボーディングフロー（典型例） +## オンボーディングフロー（一般的な流れ） -1. **OpenClaw.app** をインストールして起動します。 -2. 権限チェックリストを完了します（TCCプロンプト）。 -3. **Local** modeが有効で、Gatewayが動作していることを確認します。 -4. terminalアクセスが必要ならCLIをインストールします。 +1. **OpenClaw.app**をインストールして起動します。 +2. 権限チェックリスト（TCCプロンプト）を完了します。 +3. **Local**モードが有効で、Gatewayが実行中であることを確認します。 +4. ターミナルアクセスが必要ならCLIをインストールします。 -## State dirの配置（macOS） +## 状態ディレクトリの配置（macOS） -OpenClaw state dirをiCloudやその他のクラウド同期フォルダーに置くのは避けてください。 -同期バックエンドのパスは遅延を増やし、sessionsやcredentialsに対して -ファイルロックや同期競合を起こすことがあります。 +OpenClawの状態ディレクトリは、iCloudやその他のクラウド同期フォルダに置かないでください。 +同期対応パスでは遅延が増える可能性があり、セッションや認証情報でファイルロックや同期競合が発生することがあります。 -次のような、ローカルで非同期のstate pathを推奨します: +次のような、同期されないローカル状態パスを推奨します: __OC_I18N_900005__ -`openclaw doctor` が次の配下にstateを検出した場合: +`openclaw doctor` が以下の場所に状態を検出した場合: - `~/Library/Mobile Documents/com~apple~CloudDocs/...` - `~/Library/CloudStorage/...` -警告を出し、ローカルパスへ戻すことを推奨します。 +警告を表示し、ローカルパスへの移動を推奨します。 -## Build & 開発ワークフロー（ネイティブ） +## ビルドと開発ワークフロー（ネイティブ） - `cd apps/macos && swift build` - `swift run OpenClaw`（またはXcode） -- appをパッケージ化: `scripts/package-mac-app.sh` +- アプリをパッケージ化: `scripts/package-mac-app.sh` -## Gateway接続をデバッグする（macOS CLI） +## Gateway接続のデバッグ（macOS CLI） -このデバッグCLIを使うと、appを起動せずに、 -macOS appが使うのと同じGateway WebSocketハンドシェイクとdiscovery -ロジックを試せます。 +アプリを起動せずに、macOSアプリと同じGateway WebSocketハンドシェイクと検出ロジックをデバッグCLIで試せます。 __OC_I18N_900006__ -connectオプション: +接続オプション: -- `--url `: configを上書き -- `--mode `: configから解決（デフォルト: configまたはlocal） -- `--probe`: 新しいhealth probeを強制 +- `--url `: 設定を上書き +- `--mode `: 設定から解決（デフォルト: 設定またはlocal） +- `--probe`: 新しいヘルスプローブを強制 - `--timeout `: リクエストタイムアウト（デフォルト: `15000`） -- `--json`: 差分確認向けの構造化出力 +- `--json`: diff比較用の構造化出力 -discoveryオプション: +検出オプション: -- `--include-local`: 「local」として除外されるはずのgatewaysも含める -- `--timeout `: discovery全体の待機時間（デフォルト: `2000`） -- `--json`: 差分確認向けの構造化出力 +- `--include-local`: 「local」として除外されるGatewayも含める +- `--timeout `: 全体の検出ウィンドウ（デフォルト: `2000`） +- `--json`: diff比較用の構造化出力 -ヒント: `openclaw gateway discover --json` と比較すると、 -macOS appのdiscoveryパイプライン（`local.` と設定済みwide-area domain、さらに -wide-areaとTailscale Serveのフォールバック付き）が、 -Node CLIの `dns-sd` ベースdiscoveryと異なるかどうかを確認できます。 +ヒント: `openclaw gateway discover --json` と比較して、macOSアプリの検出パイプライン（`local.` に加えて、設定済みの広域ドメイン、そして広域およびTailscale Serveのフォールバック）が、Node CLIの `dns-sd` ベースの検出と異なるか確認してください。 -## remote接続の内部構成（SSH tunnels） +## リモート接続の配管（SSHトンネル） -macOS appが **Remote** modeで動作するとき、ローカルUI -コンポーネントがremote Gatewayをlocalhost上にあるかのように扱えるよう、 -SSH tunnelを開きます。 +macOSアプリが**Remote**モードで実行されると、ローカルUIコンポーネントがリモートGatewayをlocalhost上にあるかのように扱えるよう、SSHトンネルを開きます。 -### Control tunnel（Gateway WebSocket port） +### 制御トンネル（Gateway WebSocketポート） -- **目的:** health checks、status、Web Chat、config、その他のcontrol-plane呼び出し。 -- **ローカルポート:** Gateway port（デフォルト `18789`）。常に固定です。 -- **リモートポート:** remote host上の同じGateway port。 -- **挙動:** ランダムなローカルポートは使いません。appは既存の健全なtunnelを再利用し、 - 必要なら再起動します。 -- **SSH形状:** `ssh -N -L :127.0.0.1:` に、BatchMode + - ExitOnForwardFailure + keepaliveオプションを付けます。 -- **IP報告:** SSH tunnelはloopbackを使うため、gatewayから見えるnode - IPは `127.0.0.1` になります。実際のclient IPを表示したい場合は、 - **Direct (ws/wss)** transportを使用してください（[macOS remote access](/platforms/mac/remote) を参照）。 +- **目的:** ヘルスチェック、ステータス、Web Chat、設定、その他のコントロールプレーン呼び出し。 +- **ローカルポート:** Gatewayポート（デフォルト `18789`）、常に固定。 +- **リモートポート:** リモートホスト上の同じGatewayポート。 +- **動作:** ランダムなローカルポートは使いません。アプリは既存の正常なトンネルを再利用し、必要であれば再起動します。 +- **SSHの形:** `ssh -N -L :127.0.0.1:` に、BatchMode + ExitOnForwardFailure + keepaliveオプションを付加。 +- **IPレポート:** SSHトンネルはloopbackを使うため、gatewayから見るノードIPは `127.0.0.1` になります。実際のクライアントIPを表示したい場合は、**Direct (ws/wss)** トランスポートを使用してください（[macOS remote access](/ja-JP/platforms/mac/remote)を参照）。 -セットアップ手順は [macOS remote access](/platforms/mac/remote) を参照してください。プロトコルの -詳細は [Gateway protocol](/gateway/protocol) を参照してください。 +セットアップ手順については、[macOS remote access](/ja-JP/platforms/mac/remote)を参照してください。プロトコルの詳細については、[Gateway protocol](/ja-JP/gateway/protocol)を参照してください。 ## 関連ドキュメント -- [Gateway runbook](/gateway) -- [Gateway (macOS)](/platforms/mac/bundled-gateway) -- [macOS permissions](/platforms/mac/permissions) -- [Canvas](/platforms/mac/canvas) +- [Gateway runbook](/ja-JP/gateway) +- [Gateway（macOS）](/ja-JP/platforms/mac/bundled-gateway) +- [macOS permissions](/ja-JP/platforms/mac/permissions) +- [Canvas](/ja-JP/platforms/mac/canvas) diff --git a/docs/ja-JP/plugins/sdk-channel-plugins.md b/docs/ja-JP/plugins/sdk-channel-plugins.md index aedc4d532..8b7518cee 100644 --- a/docs/ja-JP/plugins/sdk-channel-plugins.md +++ b/docs/ja-JP/plugins/sdk-channel-plugins.md @@ -1,87 +1,86 @@ --- read_when: - - 新しいメッセージングチャネルPluginを構築しています - - OpenClawをメッセージングプラットフォームに接続したいと考えています - - ChannelPluginアダプターの表面を理解する必要があります + - 新しいメッセージングチャネル Plugin を構築しています + - OpenClaw をメッセージングプラットフォームに接続したいと考えています + - ChannelPlugin アダプターの公開インターフェースを理解する必要があります sidebarTitle: Channel Plugins -summary: OpenClaw向けメッセージングチャネルPluginを構築するためのステップごとのガイド -title: チャネルPluginの構築 +summary: OpenClaw 向けメッセージングチャネル Plugin を構築するためのステップバイステップガイド +title: チャネル Plugin の構築 x-i18n: - generated_at: "2026-04-15T19:41:39Z" + generated_at: "2026-04-18T04:40:46Z" model: gpt-5.4 provider: openai - source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b + source_hash: 3dda53c969bc7356a450c2a5bf49fb82bf1283c23e301dec832d8724b11e724b source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# チャネルPluginの構築 +# チャネル Plugin の構築 -このガイドでは、OpenClawをメッセージングプラットフォームに接続するチャネルpluginの構築方法を説明します。最終的には、DMセキュリティ、ペアリング、返信スレッド化、送信メッセージングを備えた動作するチャネルを完成させます。 +このガイドでは、OpenClaw をメッセージングプラットフォームに接続するチャネル Plugin の構築手順を説明します。最後には、DM セキュリティ、ペアリング、返信スレッド化、送信メッセージングを備えた動作するチャネルが完成します。 - OpenClaw pluginをこれまでに一度も構築したことがない場合は、基本的なパッケージ構造とマニフェスト設定について、まず - [はじめに](/ja-JP/plugins/building-plugins)を読んでください。 + OpenClaw Plugin をまだ一度も作成したことがない場合は、まず基本的なパッケージ構造とマニフェスト設定について [はじめに](/ja-JP/plugins/building-plugins) を読んでください。 -## チャネルPluginの仕組み +## チャネル Plugin の仕組み -チャネルpluginには、独自の送信・編集・リアクションツールは不要です。OpenClawは、コアに1つの共有`message`ツールを保持しています。pluginが担うのは次の項目です。 +チャネル Plugin には、独自の send/edit/react ツールは不要です。OpenClaw は、コアに1つの共有 `message` ツールを保持します。あなたの Plugin が担うのは次の部分です。 -- **Config** — アカウント解決とセットアップウィザード -- **Security** — DMポリシーと許可リスト -- **Pairing** — DM承認フロー -- **Session grammar** — プロバイダー固有の会話IDを、ベースチャット、スレッドID、親フォールバックにどのように対応付けるか -- **Outbound** — テキスト、メディア、投票をプラットフォームへ送信すること -- **Threading** — 返信をどのようにスレッド化するか +- **設定** — アカウント解決とセットアップウィザード +- **セキュリティ** — DM ポリシーと許可リスト +- **ペアリング** — DM 承認フロー +- **セッショングラマー** — プロバイダー固有の会話 ID を、どのようにベースチャット、スレッド ID、親フォールバックへ対応付けるか +- **送信** — テキスト、メディア、投票をプラットフォームへ送信する処理 +- **スレッド化** — 返信をどのようにスレッド化するか -コアは、共有messageツール、プロンプト配線、外側のセッションキー形状、汎用的な`:thread:`管理、ディスパッチを担います。 +コアは、共有 message ツール、プロンプト配線、外側のセッションキー形状、汎用的な `:thread:` の管理、およびディスパッチを担います。 -チャネルがメディアソースを運ぶmessage-toolパラメーターを追加する場合は、それらのパラメーター名を`describeMessageTool(...).mediaSourceParams`を通じて公開してください。コアはその明示的なリストを、サンドボックスパスの正規化と送信メディアアクセス方針に使用するため、plugin側でプロバイダー固有のアバター、添付ファイル、またはカバー画像パラメーターのために共有コアの特別扱いを追加する必要はありません。 -できれば、`{ "set-profile": ["avatarUrl", "avatarPath"] }`のようなアクションキー付きマップを返してください。そうすることで、無関係なアクションが別のアクションのメディア引数を継承しません。意図的にすべての公開アクションで共有されるパラメーターであれば、フラットな配列でも引き続き利用できます。 +チャネルでメディアソースを運ぶ message ツールのパラメーターを追加する場合は、それらのパラメーター名を `describeMessageTool(...).mediaSourceParams` を通じて公開してください。コアはその明示的な一覧を、サンドボックス内のパス正規化および送信時のメディアアクセスポリシーに使用するため、Plugin 側でプロバイダー固有の avatar、attachment、cover-image パラメーター向けの共有コア特例は不要です。 +できれば、`{ "set-profile": ["avatarUrl", "avatarPath"] }` のようなアクションキー付きマップを返してください。そうすることで、無関係なアクションが別のアクションのメディア引数を引き継がずに済みます。意図的にすべての公開アクションで共有するパラメーターであれば、フラットな配列でも動作します。 -プラットフォームが会話IDの中に追加のスコープを保存する場合は、その解析をplugin内で`messaging.resolveSessionConversation(...)`を使って行ってください。これは、`rawId`をベース会話ID、任意のスレッドID、明示的な`baseConversationId`、および任意の`parentConversationCandidates`に対応付けるための正規のフックです。 -`parentConversationCandidates`を返す場合は、最も狭い親から最も広い/ベース会話までの順に並べてください。 +プラットフォームが会話 ID 内に追加スコープを保存する場合は、その解析を `messaging.resolveSessionConversation(...)` とともに Plugin 内に保持してください。これは、`rawId` をベース会話 ID、任意のスレッド ID、明示的な `baseConversationId`、および `parentConversationCandidates` へ対応付けるための正規フックです。 +`parentConversationCandidates` を返す場合は、最も狭い親から最も広い親/ベース会話の順に並べてください。 -チャネルレジストリが起動する前に同じ解析を必要とする同梱pluginは、一致する`resolveSessionConversation(...)`エクスポートを持つトップレベルの`session-key-api.ts`ファイルも公開できます。コアは、実行時pluginレジストリがまだ利用できない場合に限って、このブートストラップ安全なサーフェスを使用します。 +チャネルレジストリの起動前に同じ解析が必要な同梱 Plugin は、対応する `resolveSessionConversation(...)` エクスポートを持つトップレベルの `session-key-api.ts` ファイルも公開できます。コアは、ランタイム Plugin レジストリがまだ利用できないときに限り、このブートストラップ安全な公開インターフェースを使用します。 -`messaging.resolveParentConversationCandidates(...)`は、pluginが汎用/生のIDに加えて親フォールバックだけを必要とする場合の、レガシー互換フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず`resolveSessionConversation(...).parentConversationCandidates`を使用し、正規フックがそれらを省略した場合にのみ`resolveParentConversationCandidates(...)`へフォールバックします。 +`messaging.resolveParentConversationCandidates(...)` は、Plugin が汎用/raw ID の上に親フォールバックだけを必要とする場合の、レガシー互換フォールバックとして引き続き利用できます。両方のフックが存在する場合、コアはまず `resolveSessionConversation(...).parentConversationCandidates` を使用し、その正規フックがそれらを省略したときのみ `resolveParentConversationCandidates(...)` にフォールバックします。 ## 承認とチャネル機能 -ほとんどのチャネルpluginでは、承認固有のコードは不要です。 +ほとんどのチャネル Plugin では、承認専用コードは不要です。 -- コアは、同一チャット内の`/approve`、共有承認ボタンのペイロード、汎用フォールバック配信を担います。 -- チャネルが承認固有の動作を必要とする場合は、チャネルplugin上で1つの`approvalCapability`オブジェクトを使うようにしてください。 -- `ChannelPlugin.approvals`は削除されました。承認の配信/ネイティブ/レンダリング/認証に関する情報は`approvalCapability`に置いてください。 -- `plugin.auth`はlogin/logout専用です。コアはもはやそのオブジェクトから承認認証フックを読み取りません。 -- `approvalCapability.authorizeActorAction`と`approvalCapability.getActionAvailabilityState`が、正規の承認認証シームです。 -- 同一チャット承認の認証可用性には`approvalCapability.getActionAvailabilityState`を使用してください。 -- チャネルがネイティブexec承認を公開する場合、開始サーフェス/ネイティブクライアント状態が同一チャット承認認証と異なるときは、`approvalCapability.getExecInitiatingSurfaceState`を使用してください。コアはこのexec固有フックを使って、開始チャネルがネイティブexec承認をサポートしているかどうかを判定し、`enabled`と`disabled`を区別し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)`は、一般的なケース向けにこれを補います。 -- 重複するローカル承認プロンプトの非表示や、配信前の入力中インジケーター送信など、チャネル固有のペイロードライフサイクル動作には、`outbound.shouldSuppressLocalPayloadPrompt`または`outbound.beforeDeliverPayload`を使用してください。 -- `approvalCapability.delivery`は、ネイティブ承認ルーティングまたはフォールバック抑制にのみ使用してください。 -- チャネル所有のネイティブ承認情報には`approvalCapability.nativeRuntime`を使用してください。ホットなチャネルエントリーポイントでは、`createLazyChannelApprovalNativeRuntimeAdapter(...)`でこれを遅延化してください。これにより、コアが承認ライフサイクルを組み立てつつ、必要時に実行時モジュールをimportできます。 -- チャネルが共有レンダラーの代わりに本当にカスタム承認ペイロードを必要とする場合にのみ、`approvalCapability.render`を使用してください。 -- チャネルが、無効パスの返信でネイティブexec承認を有効化するために必要な正確なconfigノブを説明したい場合は、`approvalCapability.describeExecApprovalSetup`を使用してください。このフックは`{ channel, channelLabel, accountId }`を受け取ります。名前付きアカウントのチャネルは、トップレベルのデフォルトではなく、`channels..accounts..execApprovals.*`のようなアカウントスコープ付きパスを描画する必要があります。 -- チャネルが既存configから安定したオーナー的DMアイデンティティを推論できる場合は、承認固有のコアロジックを追加せずに同一チャット`/approve`を制限するため、`openclaw/plugin-sdk/approval-runtime`の`createResolvedApproverActionAuthAdapter`を使用してください。 -- チャネルがネイティブ承認配信を必要とする場合、チャネルコードはターゲット正規化と転送/表示情報に集中させてください。`openclaw/plugin-sdk/approval-runtime`の`createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability`を使用してください。チャネル固有の情報は`approvalCapability.nativeRuntime`の背後に置き、理想的には`createChannelApprovalNativeRuntimeAdapter(...)`または`createLazyChannelApprovalNativeRuntimeAdapter(...)`を通してください。そうすることで、コアがハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、有効期限、Gateway購読、別経路通知を担えます。`nativeRuntime`はいくつかのより小さなシームに分かれています。 -- `availability` — アカウントが設定されているか、およびリクエストを処理すべきかどうか -- `presentation` — 共有承認ビューモデルを、保留/解決済み/期限切れのネイティブペイロードまたは最終アクションへ対応付ける -- `transport` — ターゲットを準備し、ネイティブ承認メッセージを送信/更新/削除する -- `interactions` — ネイティブボタンやリアクションのための任意のbind/unbind/clear-actionフック +- コアは、同一チャット内の `/approve`、共有承認ボタンのペイロード、汎用フォールバック配信を担います。 +- チャネルで承認固有の挙動が必要な場合は、チャネル Plugin 上に1つの `approvalCapability` オブジェクトを置くのが望ましいです。 +- `ChannelPlugin.approvals` は削除されました。承認の配信/ネイティブ/レンダリング/認証に関する情報は `approvalCapability` に置いてください。 +- `plugin.auth` は login/logout 専用です。コアはそのオブジェクトから承認認証フックをもう読みません。 +- `approvalCapability.authorizeActorAction` と `approvalCapability.getActionAvailabilityState` が、承認認証の正規の公開インターフェースです。 +- 同一チャット内の承認認証の可用性には `approvalCapability.getActionAvailabilityState` を使用してください。 +- チャネルがネイティブ exec 承認を公開する場合は、開始サーフェス/ネイティブクライアントの状態が同一チャット承認認証と異なるときに `approvalCapability.getExecInitiatingSurfaceState` を使用してください。コアはこの exec 専用フックを使用して、`enabled` と `disabled` を区別し、開始チャネルがネイティブ exec 承認をサポートするかどうかを判断し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。`createApproverRestrictedNativeApprovalCapability(...)` は、この一般的なケースを埋めます。 +- 重複したローカル承認プロンプトを隠す、配信前に typing indicator を送る、といったチャネル固有のペイロードライフサイクル挙動には、`outbound.shouldSuppressLocalPayloadPrompt` または `outbound.beforeDeliverPayload` を使用してください。 +- `approvalCapability.delivery` は、ネイティブ承認のルーティングまたはフォールバック抑制にのみ使用してください。 +- `approvalCapability.nativeRuntime` は、チャネル所有のネイティブ承認情報に使用してください。ホットなチャネルエントリーポイントでは `createLazyChannelApprovalNativeRuntimeAdapter(...)` を使って遅延化し、必要時にランタイムモジュールを import できるようにしつつ、コアが承認ライフサイクルを組み立てられるようにしてください。 +- `approvalCapability.render` は、チャネルが共有レンダラーではなく本当にカスタム承認ペイロードを必要とする場合にのみ使用してください。 +- チャネルが、ネイティブ exec 承認を有効にするために必要な正確な設定項目を disabled 経路の返信で説明したい場合は、`approvalCapability.describeExecApprovalSetup` を使用してください。このフックは `{ channel, channelLabel, accountId }` を受け取ります。名前付きアカウントチャネルは、トップレベルのデフォルトではなく、`channels..accounts..execApprovals.*` のようなアカウントスコープのパスをレンダリングしてください。 +- チャネルが既存設定から安定した owner 類似の DM ID を推測できる場合は、承認固有のコアロジックを追加せずに、同一チャット内の `/approve` を制限するために `openclaw/plugin-sdk/approval-runtime` の `createResolvedApproverActionAuthAdapter` を使用してください。 +- チャネルがネイティブ承認配信を必要とする場合は、チャネルコードをターゲット正規化とトランスポート/表示情報に集中させてください。`openclaw/plugin-sdk/approval-runtime` の `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability` を使用してください。チャネル固有の情報は `approvalCapability.nativeRuntime` の背後に置き、理想的には `createChannelApprovalNativeRuntimeAdapter(...)` または `createLazyChannelApprovalNativeRuntimeAdapter(...)` を介してください。そうすることで、コアがハンドラーを組み立て、リクエストのフィルタリング、ルーティング、重複排除、有効期限、Gateway 購読、別経路ルーティング通知を担えます。`nativeRuntime` は、いくつかの小さな公開インターフェースに分かれています。 +- `availability` — アカウントが設定済みかどうか、およびリクエストを処理すべきかどうか +- `presentation` — 共有承認ビュー・モデルを pending/resolved/expired のネイティブペイロードや最終アクションへ変換 +- `transport` — ターゲットを準備し、ネイティブ承認メッセージを送信/更新/削除 +- `interactions` — ネイティブボタンやリアクション向けの任意の bind/unbind/clear-action フック - `observe` — 任意の配信診断フック -- チャネルがクライアント、トークン、Boltアプリ、Webhook受信側のような実行時所有オブジェクトを必要とする場合は、`openclaw/plugin-sdk/channel-runtime-context`を通じて登録してください。汎用のruntime-contextレジストリにより、コアは承認固有のラッパー接着コードを追加せずに、チャネル起動状態からcapability駆動ハンドラーをブートストラップできます。 -- capability駆動シームだけではまだ表現力が足りない場合にのみ、下位レベルの`createChannelApprovalHandler`または`createChannelNativeApprovalRuntime`に手を伸ばしてください。 -- ネイティブ承認チャネルは、`accountId`と`approvalKind`の両方をそれらのヘルパーに渡す必要があります。`accountId`は複数アカウント承認ポリシーを正しいbotアカウントにスコープし、`approvalKind`はコア内のハードコード分岐なしでexec対plugin承認動作をチャネルで利用可能にします。 -- コアは現在、承認の再ルーティング通知も担います。チャネルpluginは、`createChannelNativeApprovalRuntime`から独自の「承認はDM/別チャネルへ送られました」フォローアップメッセージを送信すべきではありません。代わりに、共有承認capabilityヘルパーを通じて正確な発信元+承認者DMルーティングを公開し、開始チャットへ通知を投稿する前に実際の配信をコアに集約させてください。 -- 配信済み承認IDの種類は、エンドツーエンドで保持してください。ネイティブクライアントは、チャネルローカル状態からexec対plugin承認ルーティングを推測したり書き換えたりしてはいけません。 -- 異なる承認種別は、意図的に異なるネイティブサーフェスを公開できます。 +- チャネルが client、token、Bolt app、Webhook レシーバーのようなランタイム所有オブジェクトを必要とする場合は、`openclaw/plugin-sdk/channel-runtime-context` を通じて登録してください。汎用 runtime-context レジストリにより、コアは承認固有のラッパー glue を追加せずに、チャネル起動状態から capability 駆動ハンドラーをブートストラップできます。 +- capability 駆動の公開インターフェースではまだ表現力が足りない場合にのみ、より低レベルの `createChannelApprovalHandler` または `createChannelNativeApprovalRuntime` を使ってください。 +- ネイティブ承認チャネルでは、`accountId` と `approvalKind` の両方をそれらのヘルパー経由でルーティングする必要があります。`accountId` は複数アカウントの承認ポリシーを正しい bot アカウントにスコープし、`approvalKind` は exec と Plugin 承認の挙動を、コアにハードコードされた分岐なしでチャネル側で扱えるようにします。 +- コアは現在、承認の再ルーティング通知も担います。チャネル Plugin は `createChannelNativeApprovalRuntime` から独自の「承認は DM / 別チャネルへ送られました」というフォローアップメッセージを送るべきではありません。代わりに、共有承認 capability ヘルパーを通じて正確な送信元 + approver-DM ルーティングを公開し、実際の配信を集約したうえで、必要な通知を開始チャットへ投稿するかどうかはコアに任せてください。 +- 配信された承認 ID の種類は、最初から最後まで保持してください。ネイティブクライアントは、チャネルローカルの状態から exec と Plugin 承認のルーティングを推測したり書き換えたりしてはいけません。 +- 異なる承認種別は、意図的に異なるネイティブサーフェスを公開してよい場合があります。 現在の同梱例: - - Slackは、execとpluginの両方のIDに対してネイティブ承認ルーティングを利用可能に保っています。 - - Matrixは、execとpluginの承認で認証を異ならせつつ、同じネイティブDM/チャネルルーティングとリアクションUXを維持しています。 -- `createApproverRestrictedNativeApprovalAdapter`は互換ラッパーとして引き続き存在しますが、新しいコードではcapability builderを優先し、plugin上に`approvalCapability`を公開してください。 + - Slack は exec と Plugin の両方の ID について、ネイティブ承認ルーティングを利用可能なままにしています。 + - Matrix は exec と Plugin 承認の両方で同じネイティブ DM/チャネルルーティングと reaction UX を維持しつつ、承認種別ごとに auth だけは異なるようにできます。 +- `createApproverRestrictedNativeApprovalAdapter` は互換ラッパーとしてまだ存在しますが、新しいコードでは capability builder を優先し、Plugin 上で `approvalCapability` を公開してください。 -ホットなチャネルエントリーポイントでは、そのファミリーの一部だけが必要な場合、より狭いruntimeサブパスを優先してください。 +ホットなチャネルエントリーポイントでは、そのファミリーの一部だけが必要な場合、より狭いランタイム subpath を優先してください。 - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -93,84 +92,71 @@ x-i18n: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -同様に、より広い傘型サーフェスが不要な場合は、`openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/reply-runtime`、`openclaw/plugin-sdk/reply-dispatch-runtime`、`openclaw/plugin-sdk/reply-reference`、`openclaw/plugin-sdk/reply-chunking`を優先してください。 +同様に、より広い包括的な公開インターフェースが不要な場合は、`openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/reply-runtime`、`openclaw/plugin-sdk/reply-dispatch-runtime`、`openclaw/plugin-sdk/reply-reference`、`openclaw/plugin-sdk/reply-chunking` を優先してください。 -セットアップについては、特に次のとおりです。 +セットアップについては特に以下の通りです。 -- `openclaw/plugin-sdk/setup-runtime`は、runtime-safeなセットアップヘルパーを扱います: - import-safeなセットアップパッチアダプター（`createPatchedAccountSetupAdapter`、 - `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`）、lookup-note出力、 - `promptResolvedAllowFrom`、`splitSetupEntries`、委譲された - setup-proxy builder -- `openclaw/plugin-sdk/setup-adapter-runtime`は、`createEnvPatchedAccountSetupAdapter`向けの狭いenv対応アダプターシームです -- `openclaw/plugin-sdk/channel-setup`は、オプションインストールのセットアップbuilderと、いくつかのセットアップ安全なプリミティブを扱います: - `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` は、ランタイム安全なセットアップヘルパーをカバーします: + import-safe なセットアップ patch アダプター（`createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`）、lookup-note 出力、`promptResolvedAllowFrom`、`splitSetupEntries`、および委譲セットアッププロキシ builder +- `openclaw/plugin-sdk/setup-adapter-runtime` は、`createEnvPatchedAccountSetupAdapter` のための、より狭い env 対応アダプター公開インターフェースです +- `openclaw/plugin-sdk/channel-setup` は、任意インストールのセットアップ builder と、いくつかのセットアップ安全な基本要素をカバーします: + `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、 -チャネルがenv駆動のセットアップまたは認証をサポートし、汎用の起動/configフローがruntimeロード前にそれらのenv名を知る必要がある場合は、pluginマニフェストで`channelEnvVars`として宣言してください。チャネルruntimeの`envVars`またはローカル定数は、運用者向けコピー専用にしてください。 -`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, -`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, および -`splitSetupEntries` +チャネルが env 駆動のセットアップや auth をサポートし、汎用的な起動/設定フローがランタイム読み込み前にその env 名を知る必要がある場合は、Plugin マニフェストで `channelEnvVars` に宣言してください。チャネルランタイムの `envVars` やローカル定数は、運用者向け説明文だけに使ってください。 +`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、および `splitSetupEntries` -- より重い共有セットアップ/configヘルパー、たとえば - `moveSingleAccountChannelSectionToDefaultAccount(...)`も必要な場合にのみ、より広い`openclaw/plugin-sdk/setup`シームを使用してください +- `moveSingleAccountChannelSectionToDefaultAccount(...)` のような、より重い共有セットアップ/設定ヘルパーも必要な場合にのみ、より広い `openclaw/plugin-sdk/setup` 公開インターフェースを使用してください -チャネルがセットアップサーフェス内で「まずこのpluginをインストールしてください」と告知したいだけなら、`createOptionalChannelSetupSurface(...)`を優先してください。生成されるアダプター/ウィザードはconfig書き込みと最終化でフェイルクローズし、検証、最終化、ドキュメントリンク文言の各所で同じインストール必須メッセージを再利用します。 +チャネルがセットアップ画面で「まずこの Plugin をインストールしてください」と案内したいだけであれば、`createOptionalChannelSetupSurface(...)` を優先してください。生成される adapter/wizard は、設定書き込みと最終確定に対して fail closed し、検証・finalize・docs リンク文面で同じインストール必須メッセージを再利用します。 -その他のホットなチャネルパスでも、より広いレガシーサーフェスより狭いヘルパーを優先してください。 +そのほかのホットなチャネルパスでも、より広いレガシー公開インターフェースではなく、より狭いヘルパーを優先してください。 -- `openclaw/plugin-sdk/account-core`、 - `openclaw/plugin-sdk/account-id`、 - `openclaw/plugin-sdk/account-resolution`、および - `openclaw/plugin-sdk/account-helpers` は、複数アカウントconfigと - デフォルトアカウントフォールバック向けです +- `openclaw/plugin-sdk/account-core` +- `openclaw/plugin-sdk/account-id` +- `openclaw/plugin-sdk/account-resolution` +- `openclaw/plugin-sdk/account-helpers` は、複数アカウント設定とデフォルトアカウントへのフォールバック向け - `openclaw/plugin-sdk/inbound-envelope` と - `openclaw/plugin-sdk/inbound-reply-dispatch` は、受信ルート/エンベロープと - record-and-dispatch配線向けです -- `openclaw/plugin-sdk/messaging-targets` は、ターゲット解析/マッチング向けです + `openclaw/plugin-sdk/inbound-reply-dispatch` は、受信ルート/エンベロープおよび record-and-dispatch 配線向け +- `openclaw/plugin-sdk/messaging-targets` は、ターゲットの解析/マッチング向け - `openclaw/plugin-sdk/outbound-media` と - `openclaw/plugin-sdk/outbound-runtime` は、メディア読み込みと送信 - アイデンティティ/送信デリゲート向けです -- `openclaw/plugin-sdk/thread-bindings-runtime` は、スレッドバインディングのライフサイクル - とアダプター登録向けです -- `openclaw/plugin-sdk/agent-media-payload` は、レガシーなagent/media - ペイロードのフィールドレイアウトが依然必要な場合にのみ使用してください -- `openclaw/plugin-sdk/telegram-command-config` は、Telegramカスタムコマンドの - 正規化、重複/競合検証、およびフォールバック安定なコマンド - config契約向けです + `openclaw/plugin-sdk/outbound-runtime` は、メディア読み込みと送信 identity/send delegate 向け +- `openclaw/plugin-sdk/thread-bindings-runtime` は、スレッドバインディングのライフサイクルと adapter 登録向け +- `openclaw/plugin-sdk/agent-media-payload` は、レガシー agent/media ペイロードのフィールドレイアウトがまだ必要な場合のみ +- `openclaw/plugin-sdk/telegram-command-config` は、Telegram カスタムコマンドの正規化、重複/競合検証、およびフォールバック安定なコマンド設定契約向け -認証専用チャネルは通常、デフォルトのパスで十分です。コアが承認を処理し、pluginは送信/認証capabilityを公開するだけです。Matrix、Slack、Telegram、カスタムチャット転送のようなネイティブ承認チャネルは、独自の承認ライフサイクルを実装するのではなく、共有ネイティブヘルパーを使うべきです。 +認証専用チャネルは通常、デフォルト経路で十分です。コアが承認を処理し、Plugin は送信/auth capability を公開するだけで済みます。Matrix、Slack、Telegram、およびカスタムチャット転送のようなネイティブ承認チャネルは、独自に承認ライフサイクルを実装するのではなく、共有ネイティブヘルパーを使用してください。 ## 受信メンションポリシー 受信メンション処理は、次の2層に分けてください。 -- plugin所有の証拠収集 +- Plugin 所有の証拠収集 - 共有ポリシー評価 -共有レイヤーには`openclaw/plugin-sdk/channel-inbound`を使用してください。 +メンションポリシーの判定には `openclaw/plugin-sdk/channel-mention-gating` を使用してください。 +より広い受信ヘルパーバレルが必要な場合にのみ `openclaw/plugin-sdk/channel-inbound` を使用してください。 -pluginローカルロジックに適しているもの: +Plugin ローカルロジックに向いているもの: -- botへの返信検出 -- bot引用の検出 +- bot への返信検出 +- bot の引用検出 - スレッド参加チェック -- サービス/システムメッセージの除外 -- bot参加を証明するために必要なプラットフォームネイティブキャッシュ +- service/system メッセージの除外 +- bot 参加を証明するために必要なプラットフォームネイティブのキャッシュ -共有ヘルパーに適しているもの: +共有ヘルパーに向いているもの: - `requireMention` - 明示的メンション結果 - 暗黙的メンション許可リスト - コマンドバイパス -- 最終スキップ判定 +- 最終的なスキップ判定 推奨フロー: -1. ローカルのメンション情報を計算します。 -2. その情報を`resolveInboundMentionDecision({ facts, policy })`に渡します。 -3. 受信ゲートでは`decision.effectiveWasMentioned`、`decision.shouldBypassMention`、`decision.shouldSkip`を使用します。 +1. ローカルのメンション事実を計算する。 +2. その事実を `resolveInboundMentionDecision({ facts, policy })` に渡す。 +3. `decision.effectiveWasMentioned`、`decision.shouldBypassMention`、`decision.shouldSkip` を受信ゲートで使用する。 ```typescript import { @@ -209,7 +195,7 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions`は、すでにruntime injectionに依存している同梱チャネルplugin向けに、同じ共有メンションヘルパーを公開します。 +`api.runtime.channel.mentions` は、すでにランタイム注入に依存している同梱チャネル Plugin 向けに、同じ共有メンションヘルパーを公開します。 - `buildMentionRegexes` - `matchesMentionPatterns` @@ -217,15 +203,16 @@ if (decision.shouldSkip) return; - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -古い`resolveMentionGating*`ヘルパーは、互換エクスポート専用として`openclaw/plugin-sdk/channel-inbound`に引き続き残っています。新しいコードでは`resolveInboundMentionDecision({ facts, policy })`を使用してください。 +`implicitMentionKindWhen` と `resolveInboundMentionDecision` だけが必要な場合は、無関係な受信ランタイムヘルパーの読み込みを避けるため、`openclaw/plugin-sdk/channel-mention-gating` から import してください。 + +古い `resolveMentionGating*` ヘルパーは、互換エクスポートとしてのみ `openclaw/plugin-sdk/channel-inbound` に残っています。新しいコードでは `resolveInboundMentionDecision({ facts, policy })` を使用してください。 ## ウォークスルー - 標準のpluginファイルを作成します。`package.json`内の`channel`フィールドが、これをチャネルpluginにする要素です。完全なパッケージメタデータのサーフェスについては、 - [Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel)を参照してください。 + 標準の Plugin ファイルを作成します。`package.json` の `channel` フィールドによって、これがチャネル Plugin になります。完全なパッケージメタデータの公開インターフェースについては、[Plugin Setup and Config](/ja-JP/plugins/sdk-setup#openclaw-channel) を参照してください。 ```json package.json @@ -274,10 +261,10 @@ if (decision.shouldSkip) return; - - `ChannelPlugin`インターフェースには、多数のオプションのアダプターサーフェスがあります。まずは最小限、つまり`id`と`setup`から始め、必要に応じてアダプターを追加してください。 + + `ChannelPlugin` インターフェースには、多くの任意アダプター公開インターフェースがあります。最小構成である `id` と `setup` から始め、必要に応じてアダプターを追加してください。 - `src/channel.ts`を作成します: + `src/channel.ts` を作成します: ```typescript src/channel.ts import { @@ -370,15 +357,15 @@ if (decision.shouldSkip) return; }); ``` - - 低レベルのアダプターインターフェースを手動で実装する代わりに、宣言的なオプションを渡すと、builderがそれらを組み合わせます。 + + 低レベルのアダプターインターフェースを手作業で実装する代わりに、宣言的なオプションを渡すことで、builder がそれらを組み立てます。 - | オプション | 配線される内容 | + | Option | 配線されるもの | | --- | --- | - | `security.dm` | configフィールドからスコープ付きDMセキュリティリゾルバー | - | `pairing.text` | コード交換を伴うテキストベースのDMペアリングフロー | - | `threading` | reply-to-modeリゾルバー（固定、アカウントスコープ、またはカスタム） | - | `outbound.attachedResults` | 結果メタデータ（メッセージID）を返す送信関数 | + | `security.dm` | 設定フィールドからのスコープ付き DM セキュリティリゾルバー | + | `pairing.text` | コード交換を伴うテキストベースの DM ペアリングフロー | + | `threading` | reply-to モードのリゾルバー（固定、アカウントスコープ、またはカスタム） | + | `outbound.attachedResults` | 結果メタデータ（message ID）を返す送信関数 | 完全な制御が必要な場合は、宣言的オプションの代わりに生のアダプターオブジェクトを渡すこともできます。 @@ -386,7 +373,7 @@ if (decision.shouldSkip) return; - `index.ts`を作成します: + `index.ts` を作成します: ```typescript index.ts import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -421,15 +408,14 @@ if (decision.shouldSkip) return; }); ``` - チャネル所有のCLI descriptorは`registerCliMetadata(...)`に置いてください。これにより、OpenClawは完全なチャネルruntimeを起動せずにルートヘルプでそれらを表示でき、通常の完全ロードでも実際のコマンド登録に同じdescriptorを利用できます。`registerFull(...)`はruntime専用の処理に使ってください。 - `registerFull(...)`がGateway RPCメソッドを登録する場合は、plugin固有のプレフィックスを使用してください。コア管理名前空間（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は予約されており、常に`operator.admin`に解決されます。 - `defineChannelPluginEntry`は、この登録モード分割を自動的に処理します。すべてのオプションについては - [Entry Points](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry)を参照してください。 + チャネル所有の CLI descriptor は `registerCliMetadata(...)` に置いてください。これにより、OpenClaw は完全なチャネルランタイムを有効化せずにそれらをルートヘルプに表示でき、通常の完全ロードでも実際のコマンド登録のために同じ descriptor を取得できます。`registerFull(...)` はランタイム専用の処理に保持してください。 + `registerFull(...)` が Gateway RPC メソッドを登録する場合は、Plugin 固有のプレフィックスを使用してください。コア管理 namespace（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は予約済みで、常に `operator.admin` に解決されます。 + `defineChannelPluginEntry` は登録モードの分割を自動的に処理します。すべてのオプションについては [Entry Points](/ja-JP/plugins/sdk-entrypoints#definechannelpluginentry) を参照してください。 - - オンボーディング中の軽量ロード用に`setup-entry.ts`を作成します: + + オンボーディング中の軽量ロード用に `setup-entry.ts` を作成します: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -438,15 +424,14 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClawは、チャネルが無効または未設定のときに、完全なエントリの代わりにこれをロードします。これにより、セットアップフロー中に重いruntimeコードを引き込まずに済みます。詳細は[Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry)を参照してください。 + OpenClaw は、チャネルが無効または未設定の場合に、完全なエントリーではなくこちらを読み込みます。これにより、セットアップフロー中に重いランタイムコードを引き込まずに済みます。詳細は [Setup and Config](/ja-JP/plugins/sdk-setup#setup-entry) を参照してください。 - セットアップ安全なエクスポートをサイドカーモジュールに分離している同梱workspaceチャネルは、 - `openclaw/plugin-sdk/channel-entry-contract`の`defineBundledChannelSetupEntry(...)`を使用できます。これは、明示的なセットアップ時runtime setterも必要な場合に有効です。 + セットアップ安全なエクスポートを sidecar モジュールへ分離する同梱ワークスペースチャネルは、明示的なセットアップ時ランタイム setter も必要とする場合、`openclaw/plugin-sdk/channel-entry-contract` の `defineBundledChannelSetupEntry(...)` を使用できます。 - pluginは、プラットフォームからメッセージを受信し、それをOpenClawへ転送する必要があります。一般的なパターンは、リクエストを検証し、チャネルの受信ハンドラーを通じてディスパッチするWebhookです。 + Plugin は、プラットフォームからメッセージを受信し、それを OpenClaw に転送する必要があります。典型的なパターンは、リクエストを検証し、チャネルの受信ハンドラー経由でディスパッチする Webhook です。 ```typescript registerFull(api) { @@ -470,15 +455,14 @@ if (decision.shouldSkip) return; ``` - 受信メッセージ処理はチャネル固有です。各チャネルpluginが独自の受信パイプラインを所有します。実際のパターンについては、同梱チャネルplugin - （たとえばMicrosoft TeamsまたはGoogle Chatのpluginパッケージ）を見てください。 + 受信メッセージ処理はチャネル固有です。各チャネル Plugin がそれぞれの受信パイプラインを所有します。実際のパターンについては、同梱チャネル Plugin（たとえば Microsoft Teams または Google Chat の Plugin パッケージ）を参照してください。 -`src/channel.test.ts`に同居テストを書いてください: +`src/channel.test.ts` に同居テストを書いてください: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -516,7 +500,7 @@ if (decision.shouldSkip) return; pnpm test -- /acme-chat/ ``` - 共有テストヘルパーについては、[Testing](/ja-JP/plugins/sdk-testing)を参照してください。 + 共有テストヘルパーについては、[Testing](/ja-JP/plugins/sdk-testing) を参照してください。 @@ -526,42 +510,42 @@ if (decision.shouldSkip) return; ``` /acme-chat/ ├── package.json # openclaw.channel メタデータ -├── openclaw.plugin.json # configスキーマを含むマニフェスト +├── openclaw.plugin.json # 設定スキーマを含むマニフェスト ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # 公開エクスポート（任意） -├── runtime-api.ts # 内部runtimeエクスポート（任意） +├── runtime-api.ts # 内部ランタイムエクスポート（任意） └── src/ - ├── channel.ts # createChatChannelPluginによるChannelPlugin + ├── channel.ts # createChatChannelPlugin による ChannelPlugin ├── channel.test.ts # テスト - ├── client.ts # プラットフォームAPIクライアント - └── runtime.ts # runtimeストア（必要な場合） + ├── client.ts # プラットフォーム API クライアント + └── runtime.ts # ランタイムストア（必要な場合） ``` ## 高度なトピック - 固定、アカウントスコープ、またはカスタムの返信モード + 固定、アカウントスコープ、またはカスタムの reply モード - - describeMessageTool とアクションディスカバリー + + describeMessageTool とアクション検出 - inferTargetChatType, looksLikeId, resolveTarget + inferTargetChatType、looksLikeId、resolveTarget - - api.runtime を介したTTS、STT、メディア、subagent + + api.runtime 経由の TTS、STT、メディア、subagent -一部の同梱ヘルパーシームは、同梱pluginの保守と互換性のために引き続き存在します。これらは新しいチャネルpluginに推奨されるパターンではありません。その同梱pluginファミリーを直接保守しているのでない限り、共通SDKサーフェスの汎用的なchannel/setup/reply/runtimeサブパスを優先してください。 +一部の同梱ヘルパー公開インターフェースは、同梱 Plugin の保守と互換性のためにまだ存在しています。これらは新しいチャネル Plugin に推奨されるパターンではありません。その同梱 Plugin ファミリーを直接保守しているのでない限り、共通 SDK 公開インターフェースの汎用 channel/setup/reply/runtime subpath を優先してください。 ## 次のステップ -- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — pluginがモデルも提供する場合 -- [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全なサブパスimportリファレンス -- [SDK Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティと契約テスト +- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) — Plugin がモデルも提供する場合 +- [SDK Overview](/ja-JP/plugins/sdk-overview) — 完全な subpath import リファレンス +- [SDK Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティとコントラクトテスト - [Plugin Manifest](/ja-JP/plugins/manifest) — 完全なマニフェストスキーマ diff --git a/docs/ja-JP/plugins/sdk-overview.md b/docs/ja-JP/plugins/sdk-overview.md index 679d7343d..ca14889ce 100644 --- a/docs/ja-JP/plugins/sdk-overview.md +++ b/docs/ja-JP/plugins/sdk-overview.md @@ -1,55 +1,73 @@ --- read_when: - - どのSDKサブパスからインポートするかを把握する必要があります - - OpenClawPluginApi上のすべての登録メソッドのリファレンスが必要です - - 特定のSDKエクスポートを調べています + - どのSDKサブパスからインポートすべきかを知る必要がある + - OpenClawPluginApi のすべての登録メソッドのリファレンスが欲しい + - 特定のSDKエクスポートを調べている sidebarTitle: SDK Overview -summary: インポートマップ、登録APIリファレンス、およびSDKアーキテクチャ -title: Plugin SDKの概要 +summary: インポートマップ、登録APIリファレンス、SDKアーキテクチャ +title: Plugin SDK の概要 x-i18n: - generated_at: "2026-04-17T04:43:57Z" + generated_at: "2026-04-18T04:40:48Z" model: gpt-5.4 provider: openai - source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a + source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331 source_path: plugins/sdk-overview.md workflow: 15 --- -# Plugin SDKの概要 +# Plugin SDK の概要 -plugin SDKは、Pluginとcoreの間にある型付きコントラクトです。このページは、**何をインポートするか**と**何を登録できるか**のリファレンスです。 +plugin SDKは、pluginとコアの間にある型付き契約です。このページは、**何をインポートするか** と **何を登録できるか** のリファレンスです。 - **ハウツーガイドをお探しですか？** - - 最初のPluginですか？ [はじめに](/ja-JP/plugins/building-plugins)から始めてください - - Channel Pluginですか？ [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins)を参照してください - - Provider Pluginですか？ [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins)を参照してください + **ハウツーガイドを探していますか？** + - 初めてのpluginですか？ [はじめに](/ja-JP/plugins/building-plugins) から始めてください + - Channel pluginですか？ [Channel Plugins](/ja-JP/plugins/sdk-channel-plugins) を参照してください + - Provider pluginですか？ [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) を参照してください ## インポート規約 -必ず特定のサブパスからインポートしてください。 +必ず特定のサブパスからインポートしてください： ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -各サブパスは、小さく自己完結したモジュールです。これにより起動を高速に保ち、循環依存の問題を防げます。channel固有のentry/buildヘルパーには、`openclaw/plugin-sdk/channel-core`を優先してください。`openclaw/plugin-sdk/core`は、より広いアンブレラサーフェスと、`buildChannelConfigSchema`のような共有ヘルパー向けに使ってください。 +各サブパスは、小さく自己完結したモジュールです。これにより起動を高速に保ち、 +循環依存の問題を防ぎます。channel固有のエントリ/ビルドヘルパーについては、 +`openclaw/plugin-sdk/channel-core` を優先し、より広いアンブレラサーフェスや +`buildChannelConfigSchema` のような共有ヘルパーには +`openclaw/plugin-sdk/core` を使ってください。 -`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`のようなprovider名ベースの便利用seamや、channelブランドのhelper seamを追加したり依存したりしないでください。bundled Pluginは、自身の`api.ts`または`runtime-api.ts` barrel内で汎用的なSDKサブパスを組み合わせるべきであり、coreはそれらのPluginローカルbarrelを使うか、本当にcross-channelな必要がある場合にのみ狭い汎用SDKコントラクトを追加すべきです。 +`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、 +`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp` のような +provider名付きの便利用シームや、channelブランド付きのヘルパーシームを +追加したり依存したりしないでください。バンドルされたpluginは、汎用的な +SDKサブパスを自身の `api.ts` または `runtime-api.ts` バレル内で組み合わせるべきであり、コアはそれらのpluginローカルバレルを使うか、本当に +チャネル横断の必要がある場合に限って狭い汎用SDK契約を追加すべきです。 -生成されたexport mapには、`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`、`plugin-sdk/matrix*`のような、bundled Plugin用helper seamの小さなセットが依然として含まれています。これらのサブパスは、bundled Pluginの保守と互換性のためだけに存在します。意図的に以下の共通テーブルからは除外されており、新しいサードパーティPluginには推奨されるインポートパスではありません。 +生成されたエクスポートマップには、`plugin-sdk/feishu`、 +`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 +`plugin-sdk/zalo-setup`、`plugin-sdk/matrix*` のような、 +少数のバンドルplugin用ヘルパーシームが依然として含まれています。これらの +サブパスは、バンドルpluginの保守と互換性のためだけに存在します。意図的に +下の共通テーブルからは除外されており、新しいサードパーティpluginに推奨される +インポートパスではありません。 ## サブパスリファレンス -目的別にグループ化した、最もよく使われるサブパスです。200以上あるサブパスの生成済み完全リストは`scripts/lib/plugin-sdk-entrypoints.json`にあります。 +目的別にまとめた、最も一般的に使われるサブパスです。200を超えるサブパスの +生成済み完全一覧は `scripts/lib/plugin-sdk-entrypoints.json` にあります。 -予約済みのbundled Plugin helper subpathも、その生成済みリストには引き続き表示されます。ドキュメントページで明示的に公開として案内されない限り、これらは実装詳細または互換性サーフェスとして扱ってください。 +予約済みのバンドルplugin用ヘルパーサブパスは、その生成済み一覧には依然として +表示されます。ドキュメントページで明示的に公開として推奨されていない限り、 +それらは実装詳細/互換性サーフェスとして扱ってください。 ### Plugin entry -| Subpath | 主なexports | +| Subpath | 主なエクスポート | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | @@ -58,284 +76,303 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; - | Subpath | 主なexports | + | Subpath | 主なエクスポート | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | ルート`openclaw.json` Zod schema export（`OpenClawSchema`） | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`、および`DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共有setupウィザードヘルパー、allowlistプロンプト、setup status builder | + | `plugin-sdk/config-schema` | ルート `openclaw.json` Zodスキーマエクスポート (`OpenClawSchema`) | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, および `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/setup` | 共有セットアップウィザードヘルパー、allowlistプロンプト、セットアップステータスビルダー | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 複数アカウントconfig/action-gate helper、default-account fallback helper | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id正規化helper | - | `plugin-sdk/account-resolution` | account lookup + default-fallback helper | - | `plugin-sdk/account-helpers` | 狭いaccount-list/account-action helper | + | `plugin-sdk/account-core` | マルチアカウント設定/アクションゲートヘルパー、デフォルトアカウントフォールバックヘルパー | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id正規化ヘルパー | + | `plugin-sdk/account-resolution` | アカウント検索 + デフォルトフォールバックヘルパー | + | `plugin-sdk/account-helpers` | 狭いaccount-list/account-actionヘルパー | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | channel config schema type | - | `plugin-sdk/telegram-command-config` | bundled-contract fallbackを備えたTelegram custom-command正規化/検証helper | + | `plugin-sdk/channel-config-schema` | Channel設定スキーマ型 | + | `plugin-sdk/telegram-command-config` | バンドル契約フォールバック付きのTelegramカスタムコマンド正規化/検証ヘルパー | + | `plugin-sdk/command-gating` | 狭いコマンド認可ゲートヘルパー | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | 共有inbound route + envelope builder helper | - | `plugin-sdk/inbound-reply-dispatch` | 共有inbound record-and-dispatch helper | - | `plugin-sdk/messaging-targets` | target解析/マッチングhelper | - | `plugin-sdk/outbound-media` | 共有outbound media読み込みhelper | - | `plugin-sdk/outbound-runtime` | outbound identity/send delegate helper | - | `plugin-sdk/thread-bindings-runtime` | thread-binding lifecycleおよびadapter helper | - | `plugin-sdk/agent-media-payload` | legacy agent media payload builder | - | `plugin-sdk/conversation-runtime` | conversation/thread binding、pairing、およびconfigured-binding helper | - | `plugin-sdk/runtime-config-snapshot` | runtime config snapshot helper | - | `plugin-sdk/runtime-group-policy` | runtime group-policy解決helper | - | `plugin-sdk/channel-status` | 共有channel status snapshot/summary helper | - | `plugin-sdk/channel-config-primitives` | 狭いchannel config-schema primitive | - | `plugin-sdk/channel-config-writes` | channel config-write認可helper | - | `plugin-sdk/channel-plugin-common` | 共有channel plugin prelude export | - | `plugin-sdk/allowlist-config-edit` | allowlist config edit/read helper | - | `plugin-sdk/group-access` | 共有group-access decision helper | - | `plugin-sdk/direct-dm` | 共有direct-DM auth/guard helper | - | `plugin-sdk/interactive-runtime` | interactive reply payload正規化/reduction helper | - | `plugin-sdk/channel-inbound` | inbound debounce、mention matching、mention-policy helper、およびenvelope helper | - | `plugin-sdk/channel-send-result` | reply result type | + | `plugin-sdk/inbound-envelope` | 共有の受信ルート + エンベロープビルダーヘルパー | + | `plugin-sdk/inbound-reply-dispatch` | 共有の受信record-and-dispatchヘルパー | + | `plugin-sdk/messaging-targets` | ターゲット解析/マッチングヘルパー | + | `plugin-sdk/outbound-media` | 共有の送信メディア読み込みヘルパー | + | `plugin-sdk/outbound-runtime` | 送信元identity/sendデリゲートヘルパー | + | `plugin-sdk/poll-runtime` | 狭いpoll正規化ヘルパー | + | `plugin-sdk/thread-bindings-runtime` | スレッドバインディングのライフサイクルおよびアダプタヘルパー | + | `plugin-sdk/agent-media-payload` | 旧来のagentメディアペイロードビルダー | + | `plugin-sdk/conversation-runtime` | 会話/スレッドバインディング、pairing、configured-bindingヘルパー | + | `plugin-sdk/runtime-config-snapshot` | ランタイム設定スナップショットヘルパー | + | `plugin-sdk/runtime-group-policy` | ランタイムgroup-policy解決ヘルパー | + | `plugin-sdk/channel-status` | 共有channelステータススナップショット/サマリーヘルパー | + | `plugin-sdk/channel-config-primitives` | 狭いchannel設定スキーマプリミティブ | + | `plugin-sdk/channel-config-writes` | channel設定書き込み認可ヘルパー | + | `plugin-sdk/channel-plugin-common` | 共有channel pluginプレリュードエクスポート | + | `plugin-sdk/allowlist-config-edit` | allowlist設定の編集/読み取りヘルパー | + | `plugin-sdk/group-access` | 共有group-access判定ヘルパー | + | `plugin-sdk/direct-dm` | 共有direct-DM認証/ガードヘルパー | + | `plugin-sdk/interactive-runtime` | 対話型返信ペイロードの正規化/削減ヘルパー | + | `plugin-sdk/channel-inbound` | 受信デバウンス、メンションマッチング、mention-policyヘルパー、およびエンベロープヘルパーの互換性バレル | + | `plugin-sdk/channel-mention-gating` | より広い受信ランタイムサーフェスを含まない、狭いmention-policyヘルパー | + | `plugin-sdk/channel-location` | channel位置コンテキストおよびフォーマットヘルパー | + | `plugin-sdk/channel-logging` | 受信ドロップおよびtyping/ack失敗のためのchannelロギングヘルパー | + | `plugin-sdk/channel-send-result` | 返信結果型 | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | target解析/マッチングhelper | - | `plugin-sdk/channel-contract` | channel contract type | - | `plugin-sdk/channel-feedback` | feedback/reaction wiring | - | `plugin-sdk/channel-secret-runtime` | `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`、およびsecret target typeのような狭いsecret-contract helper | + | `plugin-sdk/channel-targets` | ターゲット解析/マッチングヘルパー | + | `plugin-sdk/channel-contract` | Channel契約型 | + | `plugin-sdk/channel-feedback` | フィードバック/リアクション接続 | + | `plugin-sdk/channel-secret-runtime` | `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`、およびsecret target型のような狭いsecret-contractヘルパー | - | Subpath | 主なexports | + | Subpath | 主なエクスポート | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | 厳選されたlocal/self-hosted provider setup helper | - | `plugin-sdk/self-hosted-provider-setup` | OpenAI互換のself-hosted provider setupに特化したhelper | - | `plugin-sdk/cli-backend` | CLI backend default + watchdog定数 | - | `plugin-sdk/provider-auth-runtime` | Provider Plugin向けruntime API key解決helper | - | `plugin-sdk/provider-auth-api-key` | `upsertApiKeyProfile`などのAPI keyオンボーディング/profile-write helper | - | `plugin-sdk/provider-auth-result` | 標準OAuth auth-result builder | - | `plugin-sdk/provider-auth-login` | Provider Plugin向け共有interactive login helper | - | `plugin-sdk/provider-env-vars` | provider auth env-var lookup helper | + | `plugin-sdk/provider-setup` | 厳選されたローカル/セルフホストproviderセットアップヘルパー | + | `plugin-sdk/self-hosted-provider-setup` | OpenAI互換セルフホストprovider向けの特化セットアップヘルパー | + | `plugin-sdk/cli-backend` | CLIバックエンドのデフォルト + watchdog定数 | + | `plugin-sdk/provider-auth-runtime` | provider plugin向けのランタイムAPIキー解決ヘルパー | + | `plugin-sdk/provider-auth-api-key` | `upsertApiKeyProfile` などのAPIキーオンボーディング/プロファイル書き込みヘルパー | + | `plugin-sdk/provider-auth-result` | 標準OAuth認証結果ビルダー | + | `plugin-sdk/provider-auth-login` | provider plugin向けの共有対話型ログインヘルパー | + | `plugin-sdk/provider-env-vars` | provider認証env-var検索ヘルパー | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共有replay-policy builder、provider-endpoint helper、および`normalizeNativeXaiModelId`のようなmodel-id正規化helper | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, 共有replay-policyビルダー、providerエンドポイントヘルパー、および `normalizeNativeXaiModelId` のようなmodel-id正規化ヘルパー | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 汎用provider HTTP/endpoint capability helper | - | `plugin-sdk/provider-web-fetch-contract` | `enablePluginInConfig`や`WebFetchProviderPlugin`などの狭いweb-fetch config/selection contract helper | - | `plugin-sdk/provider-web-fetch` | web-fetch provider registration/cache helper | - | `plugin-sdk/provider-web-search-config-contract` | Plugin有効化wiringを必要としないprovider向けの狭いweb-search config/credential helper | - | `plugin-sdk/provider-web-search-contract` | `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`、およびスコープ付きcredential setter/getterなどの狭いweb-search config/credential contract helper | - | `plugin-sdk/provider-web-search` | web-search provider registration/cache/runtime helper | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema cleanup + diagnostics、および`resolveXaiModelCompatPatch` / `applyXaiModelCompat`のようなxAI互換helper | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage`など | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、stream wrapper type、および共有Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helper | - | `plugin-sdk/provider-onboard` | オンボーディングconfig patch helper | - | `plugin-sdk/global-singleton` | process-local singleton/map/cache helper | + | `plugin-sdk/provider-http` | 汎用provider HTTP/エンドポイント機能ヘルパー | + | `plugin-sdk/provider-web-fetch-contract` | `enablePluginInConfig` や `WebFetchProviderPlugin` のような、狭いweb-fetch設定/選択契約ヘルパー | + | `plugin-sdk/provider-web-fetch` | web-fetch provider登録/キャッシュヘルパー | + | `plugin-sdk/provider-web-search-config-contract` | plugin有効化接続を必要としないprovider向けの、狭いweb-search設定/認証情報ヘルパー | + | `plugin-sdk/provider-web-search-contract` | `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`、およびスコープ付き認証情報setter/getterのような、狭いweb-search設定/認証情報契約ヘルパー | + | `plugin-sdk/provider-web-search` | web-search provider登録/キャッシュ/ランタイムヘルパー | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Geminiスキーマクリーンアップ + 診断、および `resolveXaiModelCompatPatch` / `applyXaiModelCompat` のようなxAI互換ヘルパー | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` など | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, ストリームラッパー型、および共有のAnthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilotラッパーヘルパー | + | `plugin-sdk/provider-onboard` | オンボーディング設定パッチヘルパー | + | `plugin-sdk/global-singleton` | プロセスローカルsingleton/map/cacheヘルパー | - - | Subpath | 主なexports | + + | Subpath | 主なエクスポート | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、command registry helper、sender-authorization helper | - | `plugin-sdk/command-status` | `buildCommandsMessagePaginated`や`buildHelpMessage`などのcommand/help message builder | - | `plugin-sdk/approval-auth-runtime` | approver解決およびsame-chat action-auth helper | - | `plugin-sdk/approval-client-runtime` | native exec approval profile/filter helper | - | `plugin-sdk/approval-delivery-runtime` | native approval capability/delivery adapter | - | `plugin-sdk/approval-gateway-runtime` | 共有approval gateway-resolution helper | - | `plugin-sdk/approval-handler-adapter-runtime` | ホットなchannel entrypoint向けの軽量native approval adapter読み込みhelper | - | `plugin-sdk/approval-handler-runtime` | より広範なapproval handler runtime helper。より狭いadapter/gateway seamで十分な場合はそちらを優先してください | - | `plugin-sdk/approval-native-runtime` | native approval target + account-binding helper | - | `plugin-sdk/approval-reply-runtime` | exec/plugin approval reply payload helper | - | `plugin-sdk/command-auth-native` | native command auth + native session-target helper | - | `plugin-sdk/command-detection` | 共有command detection helper | - | `plugin-sdk/command-surface` | command-body正規化およびcommand-surface helper | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、コマンドレジストリヘルパー、送信者認可ヘルパー | + | `plugin-sdk/command-status` | `buildCommandsMessagePaginated` や `buildHelpMessage` のようなコマンド/ヘルプメッセージビルダー | + | `plugin-sdk/approval-auth-runtime` | 承認者解決および同一チャットのアクション認可ヘルパー | + | `plugin-sdk/approval-client-runtime` | ネイティブexec承認プロファイル/フィルタヘルパー | + | `plugin-sdk/approval-delivery-runtime` | ネイティブ承認機能/配信アダプタ | + | `plugin-sdk/approval-gateway-runtime` | 共有承認Gateway解決ヘルパー | + | `plugin-sdk/approval-handler-adapter-runtime` | ホットなchannelエントリポイント向けの軽量ネイティブ承認アダプタ読み込みヘルパー | + | `plugin-sdk/approval-handler-runtime` | より広い承認ハンドラーランタイムヘルパー。狭いadapter/gatewayシームで十分な場合はそちらを優先してください | + | `plugin-sdk/approval-native-runtime` | ネイティブ承認ターゲット + アカウントバインディングヘルパー | + | `plugin-sdk/approval-reply-runtime` | exec/plugin承認返信ペイロードヘルパー | + | `plugin-sdk/command-auth-native` | ネイティブコマンド認可 + ネイティブセッションターゲットヘルパー | + | `plugin-sdk/command-detection` | 共有コマンド検出ヘルパー | + | `plugin-sdk/command-surface` | コマンド本文の正規化およびコマンドサーフェスヘルパー | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | channel/plugin secret surface向けの狭いsecret-contract collection helper | - | `plugin-sdk/secret-ref-runtime` | secret-contract/config parsing向けの狭い`coerceSecretRef`およびSecretRef型付けhelper | - | `plugin-sdk/security-runtime` | 共有trust、DM gating、external-content、およびsecret-collection helper | - | `plugin-sdk/ssrf-policy` | host allowlistおよびprivate-network SSRF policy helper | - | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRF-guarded fetch、およびSSRF policy helper | - | `plugin-sdk/secret-input` | secret input parsing helper | - | `plugin-sdk/webhook-ingress` | Webhook request/target helper | - | `plugin-sdk/webhook-request-guards` | request body size/timeout helper | + | `plugin-sdk/channel-secret-runtime` | channel/plugin secretサーフェス向けの狭いsecret-contract収集ヘルパー | + | `plugin-sdk/secret-ref-runtime` | secret-contract/設定解析向けの、狭い `coerceSecretRef` および SecretRef 型ヘルパー | + | `plugin-sdk/security-runtime` | 共有の信頼、DMゲーティング、外部コンテンツ、およびsecret収集ヘルパー | + | `plugin-sdk/ssrf-policy` | ホストallowlistおよびプライベートネットワークSSRFポリシーヘルパー | + | `plugin-sdk/ssrf-dispatcher` | 広いinfraランタイムサーフェスを含まない、狭いpinned-dispatcherヘルパー | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRFガード付きfetch、およびSSRFポリシーヘルパー | + | `plugin-sdk/secret-input` | secret入力解析ヘルパー | + | `plugin-sdk/webhook-ingress` | Webhookリクエスト/ターゲットヘルパー | + | `plugin-sdk/webhook-request-guards` | リクエスト本文サイズ/タイムアウトヘルパー | - - | Subpath | 主なexports | + + | Subpath | 主なエクスポート | | --- | --- | - | `plugin-sdk/runtime` | 広範なruntime/logging/backup/plugin-install helper | - | `plugin-sdk/runtime-env` | 狭いruntime env、logger、timeout、retry、およびbackoff helper | - | `plugin-sdk/channel-runtime-context` | 汎用channel runtime-context登録およびlookup helper | + | `plugin-sdk/runtime` | 広範なランタイム/ロギング/バックアップ/pluginインストールヘルパー | + | `plugin-sdk/runtime-env` | 狭いランタイムenv、logger、timeout、retry、およびbackoffヘルパー | + | `plugin-sdk/channel-runtime-context` | 汎用channelランタイムコンテキスト登録および検索ヘルパー | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共有plugin command/hook/http/interactive helper | - | `plugin-sdk/hook-runtime` | 共有Webhook/internal hook pipeline helper | - | `plugin-sdk/lazy-runtime` | `createLazyRuntimeModule`、`createLazyRuntimeMethod`、`createLazyRuntimeSurface`などのlazy runtime import/binding helper | - | `plugin-sdk/process-runtime` | process exec helper | - | `plugin-sdk/cli-runtime` | CLI formatting、wait、およびversion helper | - | `plugin-sdk/gateway-runtime` | Gateway clientおよびchannel-status patch helper | - | `plugin-sdk/config-runtime` | config load/write helper | - | `plugin-sdk/telegram-command-config` | bundled Telegram contract surfaceが利用できない場合でも使える、Telegram command-name/description正規化およびduplicate/conflict check | - | `plugin-sdk/approval-runtime` | exec/plugin approval helper、approval-capability builder、auth/profile helper、native routing/runtime helper | - | `plugin-sdk/reply-runtime` | 共有inbound/reply runtime helper、chunking、dispatch、Heartbeat、reply planner | - | `plugin-sdk/reply-dispatch-runtime` | 狭いreply dispatch/finalize helper | - | `plugin-sdk/reply-history` | `buildHistoryContext`、`recordPendingHistoryEntry`、`clearHistoryEntriesIfEnabled`などの共有short-window reply-history helper | + | `plugin-sdk/plugin-runtime` | 共有pluginコマンド/hook/http/interactiveヘルパー | + | `plugin-sdk/hook-runtime` | 共有Webhook/internal hookパイプラインヘルパー | + | `plugin-sdk/lazy-runtime` | `createLazyRuntimeModule`、`createLazyRuntimeMethod`、`createLazyRuntimeSurface` のような遅延ランタイムimport/バインディングヘルパー | + | `plugin-sdk/process-runtime` | プロセスexecヘルパー | + | `plugin-sdk/cli-runtime` | CLI整形、待機、およびバージョンヘルパー | + | `plugin-sdk/gateway-runtime` | Gatewayクライアントおよびchannel-statusパッチヘルパー | + | `plugin-sdk/config-runtime` | 設定の読み込み/書き込みヘルパー | + | `plugin-sdk/telegram-command-config` | バンドルされたTelegram契約サーフェスが利用できない場合でも、Telegramコマンド名/説明の正規化および重複/競合チェック | + | `plugin-sdk/text-autolink-runtime` | 広いtext-runtimeバレルを含まない、ファイル参照自動リンク検出 | + | `plugin-sdk/approval-runtime` | exec/plugin承認ヘルパー、承認機能ビルダー、認可/プロファイルヘルパー、ネイティブルーティング/ランタイムヘルパー | + | `plugin-sdk/reply-runtime` | 共有の受信/返信ランタイムヘルパー、チャンク化、ディスパッチ、Heartbeat、返信プランナー | + | `plugin-sdk/reply-dispatch-runtime` | 狭い返信ディスパッチ/完了ヘルパー | + | `plugin-sdk/reply-history` | `buildHistoryContext`、`recordPendingHistoryEntry`、`clearHistoryEntriesIfEnabled` のような共有短期ウィンドウ返信履歴ヘルパー | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 狭いtext/markdown chunking helper | - | `plugin-sdk/session-store-runtime` | session store path + updated-at helper | - | `plugin-sdk/state-paths` | state/OAuth dir path helper | - | `plugin-sdk/routing` | `resolveAgentRoute`、`buildAgentSessionKey`、`resolveDefaultAgentBoundAccountId`などのroute/session-key/account binding helper | - | `plugin-sdk/status-helpers` | 共有channel/account status summary helper、runtime-state default、およびissue metadata helper | - | `plugin-sdk/target-resolver-runtime` | 共有target resolver helper | - | `plugin-sdk/string-normalization-runtime` | slug/string正規化helper | - | `plugin-sdk/request-url` | fetch/requestライクな入力から文字列URLを抽出 | - | `plugin-sdk/run-command` | 正規化されたstdout/stderr結果を返すtimed command runner | - | `plugin-sdk/param-readers` | 共通tool/CLI param reader | - | `plugin-sdk/tool-payload` | tool result objectから正規化済みpayloadを抽出 | - | `plugin-sdk/tool-send` | tool argsからcanonical send target fieldを抽出 | - | `plugin-sdk/temp-path` | 共有temp-download path helper | - | `plugin-sdk/logging-core` | subsystem loggerおよびredaction helper | - | `plugin-sdk/markdown-table-runtime` | Markdown table mode helper | - | `plugin-sdk/json-store` | 小さなJSON state read/write helper | - | `plugin-sdk/file-lock` | 再入可能なfile-lock helper | - | `plugin-sdk/persistent-dedupe` | disk-backed dedupe cache helper | - | `plugin-sdk/acp-runtime` | ACP runtime/sessionおよびreply-dispatch helper | - | `plugin-sdk/agent-config-primitives` | 狭いagent runtime config-schema primitive | - | `plugin-sdk/boolean-param` | 緩いboolean param reader | - | `plugin-sdk/dangerous-name-runtime` | dangerous-name matching解決helper | - | `plugin-sdk/device-bootstrap` | device bootstrapおよびpairing token helper | - | `plugin-sdk/extension-shared` | 共有passive-channel、status、およびambient proxy helper primitive | - | `plugin-sdk/models-provider-runtime` | `/models` command/provider reply helper | - | `plugin-sdk/skill-commands-runtime` | Skills command listing helper | - | `plugin-sdk/native-command-registry` | native command registry/build/serialize helper | - | `plugin-sdk/agent-harness` | 低レベルagent harness向けの実験的trusted-plugin surface: harness type、active-run steer/abort helper、OpenClaw tool bridge helper、およびattempt result utility | - | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint detection helper | - | `plugin-sdk/infra-runtime` | system event/Heartbeat helper | - | `plugin-sdk/collection-runtime` | 小さなbounded cache helper | - | `plugin-sdk/diagnostic-runtime` | diagnostic flagおよびevent helper | - | `plugin-sdk/error-runtime` | error graph、formatting、共有error classification helper、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | wrapped fetch、proxy、およびpinned lookup helper | - | `plugin-sdk/host-runtime` | hostnameおよびSCP host正規化helper | - | `plugin-sdk/retry-runtime` | retry configおよびretry runner helper | - | `plugin-sdk/agent-runtime` | agent dir/identity/workspace helper | - | `plugin-sdk/directory-runtime` | config-backed directory query/dedup | + | `plugin-sdk/reply-chunking` | 狭いテキスト/Markdownチャンク化ヘルパー | + | `plugin-sdk/session-store-runtime` | セッションストアパス + updated-atヘルパー | + | `plugin-sdk/state-paths` | state/OAuthディレクトリパスヘルパー | + | `plugin-sdk/routing` | `resolveAgentRoute`、`buildAgentSessionKey`、`resolveDefaultAgentBoundAccountId` のようなルート/セッションキー/アカウントバインディングヘルパー | + | `plugin-sdk/status-helpers` | 共有channel/accountステータスサマリーヘルパー、ランタイムstateデフォルト、およびissueメタデータヘルパー | + | `plugin-sdk/target-resolver-runtime` | 共有ターゲットリゾルバヘルパー | + | `plugin-sdk/string-normalization-runtime` | slug/文字列正規化ヘルパー | + | `plugin-sdk/request-url` | fetch/request風入力から文字列URLを抽出 | + | `plugin-sdk/run-command` | 正規化されたstdout/stderr結果を返す時間制限付きコマンドランナー | + | `plugin-sdk/param-readers` | 共通tool/CLIパラメータリーダー | + | `plugin-sdk/tool-payload` | tool結果オブジェクトから正規化済みペイロードを抽出 | + | `plugin-sdk/tool-send` | tool引数から正規の送信ターゲットフィールドを抽出 | + | `plugin-sdk/temp-path` | 共有一時ダウンロードパスヘルパー | + | `plugin-sdk/logging-core` | サブシステムloggerおよびredactionヘルパー | + | `plugin-sdk/markdown-table-runtime` | Markdown表モードヘルパー | + | `plugin-sdk/json-store` | 小規模JSON state読み書きヘルパー | + | `plugin-sdk/file-lock` | 再入可能ファイルロックヘルパー | + | `plugin-sdk/persistent-dedupe` | ディスクバックdedupeキャッシュヘルパー | + | `plugin-sdk/acp-runtime` | ACPランタイム/セッションおよびreply-dispatchヘルパー | + | `plugin-sdk/acp-binding-resolve-runtime` | ライフサイクル起動importなしの読み取り専用ACPバインディング解決 | + | `plugin-sdk/agent-config-primitives` | 狭いagentランタイム設定スキーマプリミティブ | + | `plugin-sdk/boolean-param` | 緩いbooleanパラメータリーダー | + | `plugin-sdk/dangerous-name-runtime` | 危険な名前のマッチング解決ヘルパー | + | `plugin-sdk/device-bootstrap` | デバイスbootstrapおよびpairing tokenヘルパー | + | `plugin-sdk/extension-shared` | 共有passive-channel、status、およびambient proxyヘルパープリミティブ | + | `plugin-sdk/models-provider-runtime` | `/models` コマンド/provider返信ヘルパー | + | `plugin-sdk/skill-commands-runtime` | skillコマンド一覧ヘルパー | + | `plugin-sdk/native-command-registry` | ネイティブコマンドレジストリの構築/シリアライズヘルパー | + | `plugin-sdk/agent-harness` | 低レベルagent harness向けの実験的trusted-pluginサーフェス: harness型、アクティブ実行のsteer/abortヘルパー、OpenClaw tool bridgeヘルパー、およびattempt resultユーティリティ | + | `plugin-sdk/provider-zai-endpoint` | Z.A.Iエンドポイント検出ヘルパー | + | `plugin-sdk/infra-runtime` | システムイベント/Heartbeatヘルパー | + | `plugin-sdk/collection-runtime` | 小規模な有界キャッシュヘルパー | + | `plugin-sdk/diagnostic-runtime` | 診断フラグおよびイベントヘルパー | + | `plugin-sdk/error-runtime` | エラーグラフ、整形、共有エラー分類ヘルパー、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | ラップされたfetch、proxy、およびpinned lookupヘルパー | + | `plugin-sdk/runtime-fetch` | proxy/guarded-fetch importなしのdispatcher対応ランタイムfetch | + | `plugin-sdk/response-limit-runtime` | 広いmediaランタイムサーフェスを含まない有界レスポンス本文リーダー | + | `plugin-sdk/session-binding-runtime` | 設定済みbindingルーティングやpairingストアを含まない現在の会話binding state | + | `plugin-sdk/session-store-runtime` | 広い設定書き込み/保守importを含まないセッションストア読み取りヘルパー | + | `plugin-sdk/context-visibility-runtime` | 広い設定/セキュリティimportを含まないコンテキスト可視性解決および補助コンテキストフィルタリング | + | `plugin-sdk/string-coerce-runtime` | Markdown/ロギングimportを含まない、狭いプリミティブrecord/文字列の強制変換および正規化ヘルパー | + | `plugin-sdk/host-runtime` | ホスト名およびSCPホスト正規化ヘルパー | + | `plugin-sdk/retry-runtime` | retry設定およびretry実行ヘルパー | + | `plugin-sdk/agent-runtime` | agentディレクトリ/identity/workspaceヘルパー | + | `plugin-sdk/directory-runtime` | 設定バックのディレクトリ照会/dedupe | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | Subpath | 主なexports | + + | Subpath | 主なエクスポート | | --- | --- | - | `plugin-sdk/media-runtime` | media payload builderに加え、共有media fetch/transform/store helper | - | `plugin-sdk/media-generation-runtime` | 共有media-generation failover helper、candidate selection、およびmissing-model messaging | - | `plugin-sdk/media-understanding` | media understanding provider typeおよびprovider向けimage/audio helper export | - | `plugin-sdk/text-runtime` | assistant-visible-text stripping、markdown render/chunking/table helper、redaction helper、directive-tag helper、安全なtext utilityなどの共有text/markdown/logging helper | - | `plugin-sdk/text-chunking` | outbound text chunking helper | - | `plugin-sdk/speech` | speech provider typeおよびprovider向けdirective、registry、validation helper | - | `plugin-sdk/speech-core` | 共有speech provider type、registry、directive、および正規化helper | - | `plugin-sdk/realtime-transcription` | realtime transcription provider typeおよびregistry helper | - | `plugin-sdk/realtime-voice` | realtime voice provider typeおよびregistry helper | - | `plugin-sdk/image-generation` | image generation provider type | - | `plugin-sdk/image-generation-core` | 共有image-generation type、failover、auth、およびregistry helper | - | `plugin-sdk/music-generation` | music generation provider/request/result type | - | `plugin-sdk/music-generation-core` | 共有music-generation type、failover helper、provider lookup、およびmodel-ref parsing | - | `plugin-sdk/video-generation` | video generation provider/request/result type | - | `plugin-sdk/video-generation-core` | 共有video-generation type、failover helper、provider lookup、およびmodel-ref parsing | - | `plugin-sdk/webhook-targets` | Webhook target registryおよびroute-install helper | - | `plugin-sdk/webhook-path` | Webhook path正規化helper | - | `plugin-sdk/web-media` | 共有remote/local media読み込みhelper | - | `plugin-sdk/zod` | Plugin SDK利用者向けにre-exportされた`zod` | - | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | + | `plugin-sdk/media-runtime` | メディアペイロードビルダーに加え、共有メディアfetch/変換/保存ヘルパー | + | `plugin-sdk/media-generation-runtime` | 共有メディア生成failoverヘルパー、候補選択、および不足モデルメッセージ | + | `plugin-sdk/media-understanding` | メディア理解provider型と、provider向け画像/音声ヘルパーエクスポート | + | `plugin-sdk/text-runtime` | アシスタント可視テキストの除去、Markdownレンダリング/チャンク化/表ヘルパー、redactionヘルパー、directive-tagヘルパー、安全なテキストユーティリティなどの共有テキスト/Markdown/ロギングヘルパー | + | `plugin-sdk/text-chunking` | 送信テキストチャンク化ヘルパー | + | `plugin-sdk/speech` | 音声provider型と、provider向けdirective、registry、および検証ヘルパー | + | `plugin-sdk/speech-core` | 共有音声provider型、registry、directive、および正規化ヘルパー | + | `plugin-sdk/realtime-transcription` | リアルタイム文字起こしprovider型とregistryヘルパー | + | `plugin-sdk/realtime-voice` | リアルタイム音声provider型とregistryヘルパー | + | `plugin-sdk/image-generation` | 画像生成provider型 | + | `plugin-sdk/image-generation-core` | 共有画像生成型、failover、認証、およびregistryヘルパー | + | `plugin-sdk/music-generation` | 音楽生成provider/request/result型 | + | `plugin-sdk/music-generation-core` | 共有音楽生成型、failoverヘルパー、provider検索、およびmodel-ref解析 | + | `plugin-sdk/video-generation` | 動画生成provider/request/result型 | + | `plugin-sdk/video-generation-core` | 共有動画生成型、failoverヘルパー、provider検索、およびmodel-ref解析 | + | `plugin-sdk/webhook-targets` | Webhookターゲットregistryおよびroute-installヘルパー | + | `plugin-sdk/webhook-path` | Webhookパス正規化ヘルパー | + | `plugin-sdk/web-media` | 共有リモート/ローカルメディア読み込みヘルパー | + | `plugin-sdk/zod` | plugin SDK利用者向けに再エクスポートされた `zod` | + | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` | - | Subpath | 主なexports | + | Subpath | 主なエクスポート | | --- | --- | - | `plugin-sdk/memory-core` | manager/config/file/CLI helper向けのbundled memory-core helper surface | - | `plugin-sdk/memory-core-engine-runtime` | memory index/search runtime facade | - | `plugin-sdk/memory-core-host-engine-foundation` | memory host foundation engine export | - | `plugin-sdk/memory-core-host-engine-embeddings` | memory host embedding contract、registry access、local provider、および汎用batch/remote helper | - | `plugin-sdk/memory-core-host-engine-qmd` | memory host QMD engine export | - | `plugin-sdk/memory-core-host-engine-storage` | memory host storage engine export | - | `plugin-sdk/memory-core-host-multimodal` | memory host multimodal helper | - | `plugin-sdk/memory-core-host-query` | memory host query helper | - | `plugin-sdk/memory-core-host-secret` | memory host secret helper | - | `plugin-sdk/memory-core-host-events` | memory host event journal helper | - | `plugin-sdk/memory-core-host-status` | memory host status helper | - | `plugin-sdk/memory-core-host-runtime-cli` | memory host CLI runtime helper | - | `plugin-sdk/memory-core-host-runtime-core` | memory host core runtime helper | - | `plugin-sdk/memory-core-host-runtime-files` | memory host file/runtime helper | - | `plugin-sdk/memory-host-core` | memory host core runtime helperのvendor-neutral alias | - | `plugin-sdk/memory-host-events` | memory host event journal helperのvendor-neutral alias | - | `plugin-sdk/memory-host-files` | memory host file/runtime helperのvendor-neutral alias | - | `plugin-sdk/memory-host-markdown` | memory隣接Plugin向けの共有managed-markdown helper | - | `plugin-sdk/memory-host-search` | search-manager access向けのActive Memory runtime facade | - | `plugin-sdk/memory-host-status` | memory host status helperのvendor-neutral alias | - | `plugin-sdk/memory-lancedb` | bundled memory-lancedb helper surface | + | `plugin-sdk/memory-core` | manager/config/file/CLIヘルパー向けのバンドルされたmemory-coreヘルパーサーフェス | + | `plugin-sdk/memory-core-engine-runtime` | メモリインデックス/検索ランタイムファサード | + | `plugin-sdk/memory-core-host-engine-foundation` | メモリホストfoundationエンジンエクスポート | + | `plugin-sdk/memory-core-host-engine-embeddings` | メモリホスト埋め込み契約、registryアクセス、ローカルprovider、および汎用バッチ/リモートヘルパー | + | `plugin-sdk/memory-core-host-engine-qmd` | メモリホストQMDエンジンエクスポート | + | `plugin-sdk/memory-core-host-engine-storage` | メモリホストストレージエンジンエクスポート | + | `plugin-sdk/memory-core-host-multimodal` | メモリホストマルチモーダルヘルパー | + | `plugin-sdk/memory-core-host-query` | メモリホストクエリヘルパー | + | `plugin-sdk/memory-core-host-secret` | メモリホストsecretヘルパー | + | `plugin-sdk/memory-core-host-events` | メモリホストイベントジャーナルヘルパー | + | `plugin-sdk/memory-core-host-status` | メモリホストステータスヘルパー | + | `plugin-sdk/memory-core-host-runtime-cli` | メモリホストCLIランタイムヘルパー | + | `plugin-sdk/memory-core-host-runtime-core` | メモリホストコアランタイムヘルパー | + | `plugin-sdk/memory-core-host-runtime-files` | メモリホストファイル/ランタイムヘルパー | + | `plugin-sdk/memory-host-core` | メモリホストコアランタイムヘルパーのベンダー中立エイリアス | + | `plugin-sdk/memory-host-events` | メモリホストイベントジャーナルヘルパーのベンダー中立エイリアス | + | `plugin-sdk/memory-host-files` | メモリホストファイル/ランタイムヘルパーのベンダー中立エイリアス | + | `plugin-sdk/memory-host-markdown` | メモリ隣接plugin向けの共有managed-markdownヘルパー | + | `plugin-sdk/memory-host-search` | 検索managerアクセス向けのActive Memoryランタイムファサード | + | `plugin-sdk/memory-host-status` | メモリホストステータスヘルパーのベンダー中立エイリアス | + | `plugin-sdk/memory-lancedb` | バンドルされたmemory-lancedbヘルパーサーフェス | - + | Family | 現在のサブパス | 想定用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser Pluginサポートhelper（`browser-support`は互換性barrelのままです） | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | bundled Matrix helper/runtime surface | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE helper/runtime surface | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled IRC helper surface | - | channel固有helper | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled channel互換性/helper seam | - | 認証/Plugin固有helper | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled feature/Plugin helper seam。`plugin-sdk/github-copilot-token`は現在`DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken`、`resolveCopilotApiToken`をexportします | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | バンドルされたbrowser pluginサポートヘルパー（`browser-support` は互換性バレルのままです） | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | バンドルされたMatrixヘルパー/ランタイムサーフェス | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | バンドルされたLINEヘルパー/ランタイムサーフェス | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | バンドルされたIRCヘルパーサーフェス | + | Channel固有ヘルパー | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | バンドルされたchannel互換性/helperシーム | + | 認証/plugin固有ヘルパー | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | バンドルされた機能/pluginヘルパーシーム。`plugin-sdk/github-copilot-token` は現在 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken`、`resolveCopilotApiToken` をエクスポートします | ## 登録API -`register(api)`コールバックは、次のメソッドを持つ`OpenClawPluginApi`オブジェクトを受け取ります。 +`register(api)` コールバックは、次のメソッドを持つ `OpenClawPluginApi` オブジェクトを受け取ります。 -### Capability登録 +### 機能登録 -| Method | 登録するもの | -| ------------------------------------------------ | ----------------------------------- | -| `api.registerProvider(...)` | テキスト推論（LLM） | -| `api.registerAgentHarness(...)` | 実験的な低レベルagent executor | -| `api.registerCliBackend(...)` | ローカルCLI推論backend | -| `api.registerChannel(...)` | メッセージングchannel | -| `api.registerSpeechProvider(...)` | text-to-speech / STT synthesis | -| `api.registerRealtimeTranscriptionProvider(...)` | ストリーミングリアルタイム文字起こし | -| `api.registerRealtimeVoiceProvider(...)` | 双方向リアルタイム音声セッション | -| `api.registerMediaUnderstandingProvider(...)` | 画像/音声/動画解析 | -| `api.registerImageGenerationProvider(...)` | 画像生成 | -| `api.registerMusicGenerationProvider(...)` | 音楽生成 | -| `api.registerVideoGenerationProvider(...)` | 動画生成 | -| `api.registerWebFetchProvider(...)` | Web fetch / scrape provider | -| `api.registerWebSearchProvider(...)` | Web検索 | +| メソッド | 登録するもの | +| -------------------------------------------------- | ------------------------------------- | +| `api.registerProvider(...)` | テキスト推論（LLM） | +| `api.registerAgentHarness(...)` | 実験的な低レベルagent実行器 | +| `api.registerCliBackend(...)` | ローカルCLI推論バックエンド | +| `api.registerChannel(...)` | メッセージングchannel | +| `api.registerSpeechProvider(...)` | テキスト読み上げ / STT合成 | +| `api.registerRealtimeTranscriptionProvider(...)` | ストリーミングのリアルタイム文字起こし | +| `api.registerRealtimeVoiceProvider(...)` | 双方向リアルタイム音声セッション | +| `api.registerMediaUnderstandingProvider(...)` | 画像/音声/動画解析 | +| `api.registerImageGenerationProvider(...)` | 画像生成 | +| `api.registerMusicGenerationProvider(...)` | 音楽生成 | +| `api.registerVideoGenerationProvider(...)` | 動画生成 | +| `api.registerWebFetchProvider(...)` | Web fetch / スクレイプprovider | +| `api.registerWebSearchProvider(...)` | Web検索 | -### Toolsとcommands +### ツールとコマンド -| Method | 登録するもの | -| ------------------------------- | ------------------------------------------- | -| `api.registerTool(tool, opts?)` | agent tool（必須または`{ optional: true }`） | -| `api.registerCommand(def)` | カスタムcommand（LLMをバイパス） | +| メソッド | 登録するもの | +| --------------------------------- | -------------------------------------------- | +| `api.registerTool(tool, opts?)` | agentツール（必須、または `{ optional: true }`） | +| `api.registerCommand(def)` | カスタムコマンド（LLMをバイパスする） | ### インフラストラクチャ -| Method | 登録するもの | -| ---------------------------------------------- | ------------------------------------- | -| `api.registerHook(events, handler, opts?)` | イベントhook | -| `api.registerHttpRoute(params)` | Gateway HTTP endpoint | -| `api.registerGatewayMethod(name, handler)` | Gateway RPC method | -| `api.registerCli(registrar, opts?)` | CLIサブコマンド | -| `api.registerService(service)` | バックグラウンドサービス | -| `api.registerInteractiveHandler(registration)` | interactive handler | -| `api.registerMemoryPromptSupplement(builder)` | 加算的なmemory隣接prompt section | -| `api.registerMemoryCorpusSupplement(adapter)` | 加算的なmemory search/read corpus | +| メソッド | 登録するもの | +| ------------------------------------------------ | ------------------------------------- | +| `api.registerHook(events, handler, opts?)` | イベントhook | +| `api.registerHttpRoute(params)` | Gateway HTTPエンドポイント | +| `api.registerGatewayMethod(name, handler)` | Gateway RPCメソッド | +| `api.registerCli(registrar, opts?)` | CLIサブコマンド | +| `api.registerService(service)` | バックグラウンドサービス | +| `api.registerInteractiveHandler(registration)` | 対話型ハンドラー | +| `api.registerMemoryPromptSupplement(builder)` | 追加的なメモリ隣接プロンプトセクション | +| `api.registerMemoryCorpusSupplement(adapter)` | 追加的なメモリ検索/読み取りコーパス | -予約済みのcore admin namespace（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）は、Pluginがより狭いGateway method scopeを割り当てようとしても、常に`operator.admin`のままです。Plugin所有のmethodには、Plugin固有のprefixを優先してください。 +予約済みのコア管理namespace（`config.*`、`exec.approvals.*`、`wizard.*`、 +`update.*`）は、pluginがより狭いGatewayメソッドスコープを割り当てようとしても、 +常に `operator.admin` のままです。plugin所有メソッドには、plugin固有のprefixを +優先してください。 ### CLI登録メタデータ -`api.registerCli(registrar, opts?)`は、2種類のトップレベルメタデータを受け取ります。 +`api.registerCli(registrar, opts?)` は、2種類のトップレベルメタデータを受け取ります： -- `commands`: registrarが所有する明示的なcommand root -- `descriptors`: ルートCLI help、routing、およびlazy Plugin CLI登録に使われるparse-time command descriptor +- `commands`: registrarが所有する明示的なコマンドルート +- `descriptors`: ルートCLIヘルプ、ルーティング、および遅延plugin CLI登録に使われる、解析時コマンド記述子 -Plugin commandを通常のルートCLIパスでlazy-loadedのままにしたい場合は、そのregistrarが公開するすべてのトップレベルcommand rootをカバーする`descriptors`を指定してください。 +通常のルートCLIパスでpluginコマンドを遅延ロードのままにしたい場合は、 +そのregistrarが公開するすべてのトップレベルコマンドルートをカバーする +`descriptors` を指定してください。 ```typescript api.registerCli( @@ -347,7 +384,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Matrixアカウント、認証、デバイス、およびprofile stateを管理する", + description: "Matrixアカウント、検証、デバイス、およびプロファイル状態を管理する", hasSubcommands: true, }, ], @@ -355,113 +392,130 @@ api.registerCli( ); ``` -`commands`単体を使うのは、lazyなルートCLI登録が不要な場合だけにしてください。そのeager互換パスは引き続きサポートされていますが、parse-time lazy loadingのためのdescriptor-backed placeholderはインストールされません。 +ルートCLIの遅延登録が不要な場合にのみ、`commands` を単独で使ってください。 +この即時互換パスは引き続きサポートされますが、解析時の遅延ロード用に +descriptorベースのプレースホルダーはインストールされません。 -### CLI backend登録 +### CLIバックエンド登録 -`api.registerCliBackend(...)`を使うと、Pluginが`codex-cli`のようなローカルAI CLI backendのdefault configを所有できます。 +`api.registerCliBackend(...)` により、pluginは `codex-cli` のようなローカル +AI CLIバックエンドのデフォルト設定を所有できます。 -- backendの`id`は、`codex-cli/gpt-5`のようなmodel ref内のprovider prefixになります。 -- backendの`config`は、`agents.defaults.cliBackends.`と同じ形を使います。 -- ユーザーconfigが引き続き優先されます。OpenClawは、CLIを実行する前に、Plugin defaultの上に`agents.defaults.cliBackends.`をマージします。 -- マージ後にbackendが互換性書き換えを必要とする場合（たとえば古いflag形状の正規化など）は、`normalizeConfig`を使ってください。 +- バックエンドの `id` は、`codex-cli/gpt-5` のようなmodel refにおけるprovider prefixになります。 +- バックエンドの `config` は `agents.defaults.cliBackends.` と同じ形を使います。 +- ユーザー設定が引き続き優先されます。OpenClawはCLIを実行する前に、 + pluginデフォルトの上に `agents.defaults.cliBackends.` をマージします。 +- マージ後にバックエンドで互換性書き換えが必要な場合 + （たとえば古いフラグ形状の正規化など）は、`normalizeConfig` を使ってください。 ### 排他的スロット -| Method | 登録するもの | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine（一度に1つだけ有効）。`assemble()`コールバックは`availableTools`と`citationsMode`を受け取るため、engineはそれに合わせてprompt追加を調整できます。 | -| `api.registerMemoryCapability(capability)` | 統一memory capability | -| `api.registerMemoryPromptSection(builder)` | memory prompt section builder | -| `api.registerMemoryFlushPlan(resolver)` | memory flush plan resolver | -| `api.registerMemoryRuntime(runtime)` | memory runtime adapter | +| メソッド | 登録するもの | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `api.registerContextEngine(id, factory)` | コンテキストエンジン（一度に1つだけアクティブ）。`assemble()` コールバックは `availableTools` と `citationsMode` を受け取り、エンジンがプロンプト追加内容を調整できるようにします。 | +| `api.registerMemoryCapability(capability)` | 統一メモリ機能 | +| `api.registerMemoryPromptSection(builder)` | メモリプロンプトセクションビルダー | +| `api.registerMemoryFlushPlan(resolver)` | メモリフラッシュプランリゾルバ | +| `api.registerMemoryRuntime(runtime)` | メモリランタイムアダプタ | -### Memory embedding adapter +### メモリ埋め込みアダプタ -| Method | 登録するもの | -| ---------------------------------------------- | -------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | アクティブなPlugin向けmemory embedding adapter | +| メソッド | 登録するもの | +| ------------------------------------------------ | ---------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | アクティブplugin向けメモリ埋め込みアダプタ | -- `registerMemoryCapability`は、推奨される排他的memory-Plugin APIです。 -- `registerMemoryCapability`は、companion Pluginが特定のmemory Pluginのprivate layoutに入り込む代わりに、`openclaw/plugin-sdk/memory-host-core`を通じてexportされたmemory artifactを利用できるよう、`publicArtifacts.listArtifacts(...)`を公開することもできます。 -- `registerMemoryPromptSection`、`registerMemoryFlushPlan`、および`registerMemoryRuntime`は、legacy互換の排他的memory-Plugin APIです。 -- `registerMemoryEmbeddingProvider`を使うと、アクティブmemory Pluginは1つ以上のembedding adapter id（たとえば`openai`、`gemini`、またはPlugin定義のカスタムid）を登録できます。 -- `agents.defaults.memorySearch.provider`や`agents.defaults.memorySearch.fallback`のようなユーザーconfigは、それらの登録済みadapter idに対して解決されます。 +- `registerMemoryCapability` は、推奨される排他的メモリplugin APIです。 +- `registerMemoryCapability` は `publicArtifacts.listArtifacts(...)` も公開でき、 + companion pluginはそれにより、特定のメモリpluginの非公開レイアウトに入り込まずに + `openclaw/plugin-sdk/memory-host-core` 経由でエクスポートされたメモリアーティファクトを利用できます。 +- `registerMemoryPromptSection`、`registerMemoryFlushPlan`、および + `registerMemoryRuntime` は、旧来互換の排他的メモリplugin APIです。 +- `registerMemoryEmbeddingProvider` により、アクティブなメモリpluginは1つ以上の + 埋め込みアダプタid（たとえば `openai`、`gemini`、またはplugin定義のカスタムid）を登録できます。 +- `agents.defaults.memorySearch.provider` や + `agents.defaults.memorySearch.fallback` のようなユーザー設定は、 + それらの登録済みアダプタidに対して解決されます。 ### イベントとライフサイクル -| Method | 動作内容 | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | 型付きライフサイクルhook | -| `api.onConversationBindingResolved(handler)` | conversation bindingコールバック | +| メソッド | 動作 | +| ---------------------------------------------- | ---- | +| `api.on(hookName, handler, opts?)` | 型付きライフサイクルhook | +| `api.onConversationBindingResolved(handler)` | 会話bindingコールバック | -### Hook決定セマンティクス +### Hook判定セマンティクス -- `before_tool_call`: `{ block: true }`を返すと終端です。いずれかのhandlerがこれを設定すると、より低い優先度のhandlerはスキップされます。 -- `before_tool_call`: `{ block: false }`を返しても決定なしとして扱われます（`block`を省略した場合と同じ）であり、オーバーライドではありません。 -- `before_install`: `{ block: true }`を返すと終端です。いずれかのhandlerがこれを設定すると、より低い優先度のhandlerはスキップされます。 -- `before_install`: `{ block: false }`を返しても決定なしとして扱われます（`block`を省略した場合と同じ）であり、オーバーライドではありません。 -- `reply_dispatch`: `{ handled: true, ... }`を返すと終端です。いずれかのhandlerがdispatchを引き受けると、より低い優先度のhandlerとデフォルトのmodel dispatch pathはスキップされます。 -- `message_sending`: `{ cancel: true }`を返すと終端です。いずれかのhandlerがこれを設定すると、より低い優先度のhandlerはスキップされます。 -- `message_sending`: `{ cancel: false }`を返しても決定なしとして扱われます（`cancel`を省略した場合と同じ）であり、オーバーライドではありません。 +- `before_tool_call`: `{ block: true }` を返すと終端になります。いずれかのハンドラーがこれを設定すると、それより低優先度のハンドラーはスキップされます。 +- `before_tool_call`: `{ block: false }` を返しても未決定として扱われます（`block` を省略した場合と同じ）ので、上書きにはなりません。 +- `before_install`: `{ block: true }` を返すと終端になります。いずれかのハンドラーがこれを設定すると、それより低優先度のハンドラーはスキップされます。 +- `before_install`: `{ block: false }` を返しても未決定として扱われます（`block` を省略した場合と同じ）ので、上書きにはなりません。 +- `reply_dispatch`: `{ handled: true, ... }` を返すと終端になります。いずれかのハンドラーがディスパッチを引き受けると、それより低優先度のハンドラーとデフォルトのモデルディスパッチ経路はスキップされます。 +- `message_sending`: `{ cancel: true }` を返すと終端になります。いずれかのハンドラーがこれを設定すると、それより低優先度のハンドラーはスキップされます。 +- `message_sending`: `{ cancel: false }` を返しても未決定として扱われます（`cancel` を省略した場合と同じ）ので、上書きにはなりません。 ### APIオブジェクトのフィールド -| Field | Type | 説明 | -| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Plugin id | -| `api.name` | `string` | 表示名 | -| `api.version` | `string?` | Pluginバージョン（任意） | -| `api.description` | `string?` | Pluginの説明（任意） | -| `api.source` | `string` | Pluginソースパス | -| `api.rootDir` | `string?` | Pluginルートディレクトリ（任意） | -| `api.config` | `OpenClawConfig` | 現在のconfigスナップショット（利用可能な場合は、アクティブなインメモリruntimeスナップショット） | -| `api.pluginConfig` | `Record` | `plugins.entries..config`からのPlugin固有config | -| `api.runtime` | `PluginRuntime` | [ランタイムヘルパー](/ja-JP/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | スコープ付きlogger（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 現在のload mode。`"setup-runtime"`は、軽量なfull-entry前のstartup/setupウィンドウです | -| `api.resolvePath(input)` | `(string) => string` | Pluginルートからの相対パスを解決 | +| Field | Type | 説明 | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Plugin id | +| `api.name` | `string` | 表示名 | +| `api.version` | `string?` | Pluginバージョン（任意） | +| `api.description` | `string?` | Plugin説明（任意） | +| `api.source` | `string` | Pluginソースパス | +| `api.rootDir` | `string?` | Pluginルートディレクトリ（任意） | +| `api.config` | `OpenClawConfig` | 現在の設定スナップショット（利用可能な場合は、アクティブなメモリ内ランタイムスナップショット） | +| `api.pluginConfig` | `Record` | `plugins.entries..config` にあるplugin固有設定 | +| `api.runtime` | `PluginRuntime` | [ランタイムヘルパー](/ja-JP/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | スコープ付きlogger（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 現在のロードモード。`"setup-runtime"` は、完全なエントリ起動/セットアップ前の軽量ウィンドウです | +| `api.resolvePath(input)` | `(string) => string` | pluginルート基準でパスを解決する | ## 内部モジュール規約 -Plugin内では、内部インポートにローカルbarrelファイルを使用してください。 +plugin内では、内部インポートにローカルバレルファイルを使ってください： ``` my-plugin/ - api.ts # 外部利用者向けの公開export - runtime-api.ts # 内部専用runtime export - index.ts # Plugin entry point - setup-entry.ts # 軽量なsetup専用entry（任意） + api.ts # 外部利用者向けの公開エクスポート + runtime-api.ts # 内部専用ランタイムエクスポート + index.ts # Pluginエントリポイント + setup-entry.ts # 軽量なセットアップ専用エントリ（任意） ``` - 本番コードから`openclaw/plugin-sdk/`経由で自分自身のPluginを - インポートしてはいけません。内部インポートは`./api.ts`または - `./runtime-api.ts`を経由させてください。SDKパスは外部コントラクト専用です。 + 本番コード内で、自分自身のpluginを `openclaw/plugin-sdk/` + 経由でインポートしてはいけません。内部インポートは `./api.ts` または + `./runtime-api.ts` を通してください。SDKパスは外部契約専用です。 -facade読み込みされたbundled Pluginの公開surface（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts`、および同様の公開entryファイル）は、OpenClawがすでに実行中であれば、現在はアクティブなruntime configスナップショットを優先します。まだruntimeスナップショットが存在しない場合は、ディスク上で解決されたconfigファイルにフォールバックします。 +ファサードロードされるバンドルplugin公開サーフェス（`api.ts`、`runtime-api.ts`、 +`index.ts`、`setup-entry.ts`、および同様の公開エントリファイル）は、OpenClawが +すでに実行中であれば、現在のランタイム設定スナップショットを優先するように +なりました。まだランタイムスナップショットが存在しない場合は、ディスク上の +解決済み設定ファイルにフォールバックします。 -Provider Pluginは、helperが意図的にprovider固有で、まだ汎用SDKサブパスに属していない場合、狭いPluginローカルのcontract barrelを公開することもできます。現在のbundled例として、Anthropic providerは、Anthropic beta-headerや`service_tier`ロジックを汎用`plugin-sdk/*`コントラクトに昇格させる代わりに、Claude stream helperを自身の公開`api.ts` / `contract-api.ts` seamに保持しています。 +Provider pluginは、helperが意図的にprovider固有で、まだ汎用SDKサブパスに属さない場合、狭いpluginローカル契約バレルを公開することもできます。現在のバンドル例として、Anthropic providerはClaudeストリームヘルパーを、自身の公開 `api.ts` / `contract-api.ts` シームに保持しており、Anthropicのベータヘッダーや `service_tier` ロジックを汎用の `plugin-sdk/*` 契約へ昇格させていません。 -その他の現在のbundled例: +現在のその他のバンドル例： -- `@openclaw/openai-provider`: `api.ts`はprovider builder、default-model helper、およびrealtime provider builderをexportします -- `@openclaw/openrouter-provider`: `api.ts`はprovider builderに加えて、オンボーディング/config helperをexportします +- `@openclaw/openai-provider`: `api.ts` はproviderビルダー、 + デフォルトモデルヘルパー、およびリアルタイムproviderビルダーをエクスポートします +- `@openclaw/openrouter-provider`: `api.ts` はproviderビルダーに加えて + オンボーディング/設定ヘルパーをエクスポートします - extensionの本番コードでも、`openclaw/plugin-sdk/`の - インポートは避けるべきです。helperが本当に共有されるべきなら、 - 2つのPluginを結合させるのではなく、`openclaw/plugin-sdk/speech`、 - `.../provider-model-shared`、または別のcapability指向surfaceのような - 中立的なSDKサブパスに昇格させてください。 + extensionの本番コードでも、`openclaw/plugin-sdk/` の + インポートは避けるべきです。helperが本当に共有されるべきものなら、2つのpluginを + 結合させるのではなく、`openclaw/plugin-sdk/speech`、 + `.../provider-model-shared`、または別の機能指向サーフェスのような + 中立的なSDKサブパスへ昇格させてください。 ## 関連 -- [Entry Points](/ja-JP/plugins/sdk-entrypoints) — `definePluginEntry`および`defineChannelPluginEntry`のオプション -- [ランタイムヘルパー](/ja-JP/plugins/sdk-runtime) — 完全な`api.runtime`名前空間リファレンス -- [Setup and Config](/ja-JP/plugins/sdk-setup) — パッケージング、manifest、config schema +- [Entry Points](/ja-JP/plugins/sdk-entrypoints) — `definePluginEntry` と `defineChannelPluginEntry` のオプション +- [ランタイムヘルパー](/ja-JP/plugins/sdk-runtime) — 完全な `api.runtime` namespaceリファレンス +- [セットアップと設定](/ja-JP/plugins/sdk-setup) — パッケージング、manifest、設定スキーマ - [Testing](/ja-JP/plugins/sdk-testing) — テストユーティリティとlintルール -- [SDK Migration](/ja-JP/plugins/sdk-migration) — 非推奨surfaceからの移行 -- [Plugin Internals](/ja-JP/plugins/architecture) — 詳細なアーキテクチャとcapability model +- [SDK Migration](/ja-JP/plugins/sdk-migration) — 非推奨サーフェスからの移行 +- [Plugin Internals](/ja-JP/plugins/architecture) — 詳細なアーキテクチャと機能モデル diff --git a/docs/ja-JP/refactor/qa.md b/docs/ja-JP/refactor/qa.md index fedd1ae6b..008b0da31 100644 --- a/docs/ja-JP/refactor/qa.md +++ b/docs/ja-JP/refactor/qa.md @@ -1,137 +1,137 @@ --- x-i18n: - generated_at: "2026-04-08T04:42:35Z" + generated_at: "2026-04-18T04:40:46Z" model: gpt-5.4 provider: openai - source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd + source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca source_path: refactor/qa.md workflow: 15 --- -# QA リファクタリング +# QAリファクタリング -ステータス: 基盤となる移行は着地済み。 +ステータス: 基盤となる移行は完了しました。 ## 目標 -OpenClaw QA を分割定義モデルから単一の信頼できる情報源へ移行する: +OpenClaw QAを分割定義モデルから単一の信頼できる情報源へ移行します: - シナリオメタデータ - モデルに送信されるプロンプト -- セットアップとティアダウン +- セットアップとクリーンアップ - ハーネスロジック - アサーションと成功条件 -- アーティファクトとレポートのヒント +- アーティファクトとレポートヒント -望ましい最終状態は、TypeScript にほとんどの動作をハードコードするのではなく、強力なシナリオ定義ファイルを読み込む汎用 QA ハーネスです。 +目指す最終状態は、TypeScript内にほとんどの挙動をハードコードするのではなく、強力なシナリオ定義ファイルを読み込む汎用QAハーネスです。 ## 現在の状態 -現在の主要な信頼できる情報源は `qa/scenarios/index.md` と、`qa/scenarios/*.md` 配下のシナリオごとの 1 ファイルにあります。 +現在の主な信頼できる情報源は `qa/scenarios/index.md` と、各シナリオごとの `qa/scenarios//*.md` にあります。 実装済み: - `qa/scenarios/index.md` - - 正式な QA パックメタデータ - - オペレーター ID + - 正式なQAパックメタデータ + - オペレーターID - キックオフミッション -- `qa/scenarios/*.md` - - シナリオごとに 1 つの markdown ファイル +- `qa/scenarios//*.md` + - シナリオごとに1つのMarkdownファイル - シナリオメタデータ - ハンドラーバインディング - シナリオ固有の実行設定 - `extensions/qa-lab/src/scenario-catalog.ts` - - markdown パックパーサー + zod バリデーション + - Markdownパックパーサー + zod検証 - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - - markdown パックからのプラン描画 + - Markdownパックからのプランレンダリング - `extensions/qa-lab/src/qa-agent-workspace.ts` - - 互換性ファイル群に加えて `QA_SCENARIOS.md` を生成して配置 + - 生成された互換ファイルと `QA_SCENARIOS.md` をシード - `extensions/qa-lab/src/suite.ts` - - markdown 定義のハンドラーバインディングを通じて実行可能なシナリオを選択 -- QA バスプロトコル + UI - - 画像/動画/音声/ファイル描画用の汎用インライン添付ファイル + - Markdownで定義されたハンドラーバインディングを通じて実行可能なシナリオを選択 +- QAバスプロトコル + UI + - 画像/動画/音声/ファイル表示用の汎用インライン添付 -分割されたまま残っている面: +依然として分割されたままの面: - `extensions/qa-lab/src/suite.ts` - - 依然として実行可能なカスタムハンドラーロジックの大半を保持 + - 依然として実行可能なカスタムハンドラーロジックの大半を管理 - `extensions/qa-lab/src/report.ts` - - 依然として実行時出力からレポート構造を導出 + - 依然としてレポート構造を実行時出力から導出 -つまり、信頼できる情報源の分割は修正されたものの、実行はまだ完全な宣言型ではなく、主にハンドラーバックのままです。 +つまり、信頼できる情報源の分割自体は解消されましたが、実行はまだ完全宣言的ではなく、主にハンドラーバックです。 -## 実際のシナリオ面はどう見えるか +## 実際のシナリオ面はどのようなものか -現在のスイートを読むと、いくつかの異なるシナリオクラスが見えてきます。 +現在のsuiteを読むと、いくつかの異なるシナリオクラスがあります。 -### シンプルなインタラクション +### シンプルなやり取り - チャネルベースライン -- DM ベースライン -- スレッド化されたフォローアップ +- DMベースライン +- スレッドでのフォローアップ - モデル切り替え -- 承認の継続実行 +- 承認フォロースルー - リアクション/編集/削除 ### 設定とランタイムの変更 -- 設定パッチによる Skill 無効化 -- 設定適用後の再起動ウェイクアップ -- 再起動時の設定機能切り替え -- ランタイムインベントリドリフトチェック +- config patch skill disable +- config apply restart wake-up +- config restart capability flip +- runtime inventory drift check ### ファイルシステムとリポジトリアサーション -- ソース/ドキュメント検出レポート -- Lobster Invaders をビルド -- 生成画像アーティファクトの検索 +- source/docs discovery report +- build Lobster Invaders +- generated image artifact lookup ### メモリオーケストレーション -- メモリリコール -- チャネルコンテキストでのメモリツール -- メモリ失敗フォールバック -- セッションメモリランキング -- スレッドメモリ分離 -- メモリ dreaming sweep +- memory recall +- channel context内のmemory tools +- memory failure fallback +- session memory ranking +- thread memory isolation +- memory dreaming sweep -### ツールと plugin 連携 +### ツールとPlugin統合 -- MCP plugin-tools 呼び出し -- Skill の可視性 -- Skill のホットインストール -- ネイティブ画像生成 -- 画像ラウンドトリップ -- 添付ファイルからの画像理解 +- MCP plugin-tools call +- skill visibility +- skill hot install +- native image generation +- image roundtrip +- 添付からの画像理解 ### マルチターンとマルチアクター -- サブエージェントのハンドオフ -- サブエージェントのファンアウト統合 -- 再起動リカバリ系フロー +- subagent handoff +- subagent fanout synthesis +- restart recovery style flows -これらのカテゴリは DSL 要件を左右するため重要です。プロンプト + 期待されるテキストの単純な一覧だけでは不十分です。 +これらのカテゴリはDSL要件を左右するため重要です。プロンプト + 期待テキストの単純な一覧だけでは不十分です。 -## 方向性 +## 方針 ### 単一の信頼できる情報源 -`qa/scenarios/index.md` と `qa/scenarios/*.md` を、作成時の信頼できる情報源として使います。 +`qa/scenarios/index.md` と `qa/scenarios//*.md` を、作成元の信頼できる情報源として使用します。 -パックは次を維持するべきです: +このパックは次を維持する必要があります: -- レビューで人が読みやすい -- 機械解析可能 -- 次を駆動できるだけの豊かさを持つ: - - スイート実行 - - QA ワークスペースのブートストラップ - - QA Lab UI メタデータ - - ドキュメント/検出プロンプト +- レビュー時に人間が読みやすいこと +- 機械で解析できること +- 次を駆動できるだけの表現力があること: + - suite実行 + - QAワークスペースのブートストラップ + - QA Lab UIメタデータ + - docs/discoveryプロンプト - レポート生成 -### 推奨する記述フォーマット +### 推奨する記述形式 -トップレベルのフォーマットとして markdown を使い、その中に構造化 YAML を入れます。 +トップレベル形式としてMarkdownを使用し、その中に構造化YAMLを埋め込みます。 推奨形状: @@ -144,11 +144,11 @@ OpenClaw QA を分割定義モデルから単一の信頼できる情報源へ - code refs - model/provider overrides - prerequisites -- 説明文セクション +- prose sections - objective - notes - debugging hints -- フェンス付き YAML ブロック +- fenced YAML blocks - setup - steps - assertions @@ -156,13 +156,13 @@ OpenClaw QA を分割定義モデルから単一の信頼できる情報源へ これにより次が得られます: -- 巨大な JSON よりも優れた PR 可読性 -- 純粋な YAML よりも豊かなコンテキスト -- 厳密なパースと zod バリデーション +- 巨大なJSONより優れたPR可読性 +- 純粋なYAMLより豊かな文脈 +- 厳密な解析とzod検証 -生の JSON は、中間的な生成形式としてのみ許容されます。 +生のJSONは、中間生成形式としてのみ許容されます。 -## 提案されるシナリオファイル形状 +## 提案するシナリオファイル形状 例: @@ -187,7 +187,7 @@ codeRefs: # Objective -生成されたメディアがフォローアップターンで再添付されることを確認する。 +Verify generated media is reattached on the follow-up turn. # Setup @@ -208,7 +208,7 @@ codeRefs: - action: agent.send session: agent:qa:image-roundtrip message: | - 画像生成チェック: QA 用の灯台画像を生成し、それを 1 文の短い文で要約してください。 + Image generation check: generate a QA lighthouse image and summarize it in one short sentence. - action: artifact.capture kind: generated-image promptSnippet: Image generation check @@ -216,7 +216,7 @@ codeRefs: - action: agent.send session: agent:qa:image-roundtrip message: | - ラウンドトリップ画像検査チェック: 生成された灯台の添付画像を 1 文の短い文で説明してください。 + Roundtrip image inspection check: describe the generated lighthouse attachment in one short sentence. attachments: - fromArtifact: lighthouseImage ``` @@ -235,9 +235,9 @@ codeRefs: ``` ```` -## DSL がカバーすべきランナー機能 +## DSLがカバーすべきランナー機能 -現在のスイートに基づくと、汎用ランナーにはプロンプト実行以上のものが必要です。 +現在のsuiteに基づくと、汎用ランナーにはプロンプト実行以上の機能が必要です。 ### 環境およびセットアップアクション @@ -273,7 +273,7 @@ codeRefs: - `artifact.captureGeneratedImage` - `artifact.capturePath` -### メモリおよび cron アクション +### メモリおよびCronアクション - `memory.indexForce` - `memory.searchCli` @@ -283,7 +283,7 @@ codeRefs: - `cron.waitCompletion` - `sessionTranscript.write` -### MCP アクション +### MCPアクション - `mcp.callTool` @@ -305,135 +305,135 @@ codeRefs: ## 変数とアーティファクト参照 -DSL は、保存された出力と後続参照をサポートする必要があります。 +DSLは、保存済み出力と後続参照をサポートする必要があります。 -現在のスイートの例: +現在のsuiteでの例: - スレッドを作成し、その後 `threadId` を再利用する - セッションを作成し、その後 `sessionKey` を再利用する - 画像を生成し、次のターンでそのファイルを添付する -- ウェイクマーカー文字列を生成し、それが後で現れることをアサートする +- wake marker文字列を生成し、それが後で現れることを検証する 必要な機能: - `saveAs` - `${vars.name}` - `${artifacts.name}` -- パス、セッションキー、スレッド ID、マーカー、ツール出力の型付き参照 +- path、session key、thread id、marker、tool outputに対する型付き参照 -変数サポートがなければ、ハーネスはシナリオロジックを TypeScript に逆流させ続けることになります。 +変数サポートがなければ、ハーネスはシナリオロジックをTypeScriptへ漏らし続けることになります。 ## エスケープハッチとして残すべきもの -フェーズ 1 で完全に純粋な宣言型ランナーを実現するのは現実的ではありません。 +フェーズ1で完全に純粋な宣言的ランナーを実現するのは現実的ではありません。 -一部のシナリオは本質的にオーケストレーション負荷が高いです: +いくつかのシナリオは本質的にオーケストレーションが重いものです: - memory dreaming sweep -- 設定適用後の再起動ウェイクアップ -- 再起動時の設定機能切り替え -- タイムスタンプ/パスによる生成画像アーティファクト解決 -- discovery-report 評価 +- config apply restart wake-up +- config restart capability flip +- timestamp/pathによるgenerated image artifact resolution +- discovery-report evaluation これらは、当面は明示的なカスタムハンドラーを使うべきです。 推奨ルール: -- 85-90% は宣言型 +- 85〜90%は宣言的 - 残りの難しい部分には明示的な `customHandler` ステップ -- 名前付きで文書化されたカスタムハンドラーのみ -- シナリオファイル内に匿名のインラインコードは禁止 +- カスタムハンドラーは名前付きかつ文書化されていること +- シナリオファイル内に匿名インラインコードを置かないこと -これにより、進捗を維持しつつ汎用エンジンをクリーンに保てます。 +これにより、進捗を維持しながら汎用エンジンをクリーンに保てます。 ## アーキテクチャ変更 ### 現在 -シナリオ markdown はすでに次の信頼できる情報源です: +シナリオMarkdownは、すでに次に対する信頼できる情報源です: -- スイート実行 +- suite実行 - ワークスペースブートストラップファイル -- QA Lab UI シナリオカタログ +- QA Lab UIシナリオカタログ - レポートメタデータ -- discovery prompts +- discoveryプロンプト -生成される互換性要素: +生成される互換要素: -- シードされたワークスペースには依然として `QA_KICKOFF_TASK.md` が含まれる -- シードされたワークスペースには依然として `QA_SCENARIO_PLAN.md` が含まれる -- シードされたワークスペースには теперь `QA_SCENARIOS.md` も含まれる +- シードされたワークスペースには引き続き `QA_KICKOFF_TASK.md` が含まれる +- シードされたワークスペースには引き続き `QA_SCENARIO_PLAN.md` が含まれる +- シードされたワークスペースには現在 `QA_SCENARIOS.md` も含まれる ## リファクタリング計画 -### フェーズ 1: ローダーとスキーマ +### Phase 1: loaderとschema 完了。 - `qa/scenarios/index.md` を追加 -- シナリオを `qa/scenarios/*.md` に分割 -- 名前付き markdown YAML パック内容用のパーサーを追加 -- zod でバリデーション -- パース済みパックを使うようコンシューマーを切り替え +- シナリオを `qa/scenarios//*.md` に分割 +- 名前付きMarkdown YAMLパック内容用のパーサーを追加 +- zodで検証 +- 利用側を解析済みパックへ切り替え - リポジトリレベルの `qa/seed-scenarios.json` と `qa/QA_KICKOFF_TASK.md` を削除 -### フェーズ 2: 汎用エンジン +### Phase 2: 汎用エンジン -- `extensions/qa-lab/src/suite.ts` を次に分割: +- `extensions/qa-lab/src/suite.ts` を以下に分割: - loader - engine - action registry - assertion registry - custom handlers -- 既存のヘルパー関数はエンジン操作として維持 +- 既存のヘルパー関数をエンジン操作として維持 成果物: -- エンジンがシンプルな宣言型シナリオを実行する +- エンジンがシンプルな宣言的シナリオを実行する -まずは主に prompt + wait + assert で構成されるシナリオから始める: +まずは、主に prompt + wait + assert で構成されるシナリオから開始します: -- スレッド化されたフォローアップ -- 添付ファイルからの画像理解 -- Skill の可視性と呼び出し -- チャネルベースライン +- threaded follow-up +- image understanding from attachment +- skill visibility and invocation +- channel baseline 成果物: -- 汎用エンジン経由で出荷される、最初の実際の markdown 定義シナリオ +- 最初の本格的なMarkdown定義シナリオが汎用エンジン経由で提供される -### フェーズ 4: 中程度のシナリオを移行 +### Phase 4: 中程度のシナリオを移行 -- 画像生成ラウンドトリップ -- チャネルコンテキストでのメモリツール -- セッションメモリランキング -- サブエージェントのハンドオフ -- サブエージェントのファンアウト統合 +- image generation roundtrip +- memory tools in channel context +- session memory ranking +- subagent handoff +- subagent fanout synthesis 成果物: -- 変数、アーティファクト、ツールアサーション、request-log アサーションが実証される +- variables、artifacts、tool assertions、request-log assertions が実証される -### フェーズ 5: 難しいシナリオはカスタムハンドラーに残す +### Phase 5: 難しいシナリオはカスタムハンドラーに残す - memory dreaming sweep -- 設定適用後の再起動ウェイクアップ -- 再起動時の設定機能切り替え -- ランタイムインベントリドリフト +- config apply restart wake-up +- config restart capability flip +- runtime inventory drift 成果物: -- 同じ記述フォーマットだが、必要な箇所に明示的な custom-step ブロックを使う +- 記述形式は同じだが、必要な箇所に明示的なcustom-stepブロックを使う -### フェーズ 6: ハードコードされたシナリオマップを削除 +### Phase 6: ハードコードされたシナリオマップを削除 パックのカバレッジが十分になったら: -- `extensions/qa-lab/src/suite.ts` からシナリオ固有の TypeScript 分岐の大半を削除 +- `extensions/qa-lab/src/suite.ts` からシナリオ固有のTypeScript分岐の大半を削除する -## Fake Slack / リッチメディア対応 +## Fake Slack / リッチメディアサポート -現在の QA バスは text-first です。 +現在のQAバスはtext-firstです。 関連ファイル: @@ -443,17 +443,17 @@ DSL は、保存された出力と後続参照をサポートする必要があ - `extensions/qa-lab/src/bus-server.ts` - `extensions/qa-lab/web/src/ui-render.ts` -今日の QA バスが対応しているもの: +現在QAバスがサポートしているもの: - テキスト - リアクション - スレッド -まだインラインメディア添付ファイルはモデル化されていません。 +まだインラインメディア添付はモデル化されていません。 ### 必要なトランスポート契約 -汎用的な QA バス添付ファイルモデルを追加します: +汎用QAバス添付モデルを追加します: ```ts type QaBusAttachment = { @@ -472,67 +472,67 @@ type QaBusAttachment = { }; ``` -そのうえで `attachments?: QaBusAttachment[]` を次に追加します: +次に `attachments?: QaBusAttachment[]` を以下へ追加します: - `QaBusMessage` - `QaBusInboundMessageInput` - `QaBusOutboundMessageInput` -### なぜまず汎用化なのか +### なぜ先に汎用化するのか -Slack 専用のメディアモデルを作らないでください。 +Slack専用のメディアモデルは作らないでください。 代わりに: -- 1 つの汎用 QA トランスポートモデル +- 1つの汎用QAトランスポートモデル - その上に複数のレンダラー - - 現在の QA Lab チャット - - 将来の fake Slack web - - その他の fake transport views + - 現在のQA Lab chat + - 将来のfake Slack web + - その他のfake transportビュー これによりロジックの重複を防ぎ、メディアシナリオをトランスポート非依存に保てます。 -### 必要な UI 作業 +### 必要なUI作業 -QA UI を更新して次を描画します: +QA UIを更新して以下をレンダリングします: - インライン画像プレビュー - インライン音声プレーヤー - インライン動画プレーヤー - ファイル添付チップ -現在の UI はすでにスレッドとリアクションを描画できるため、添付ファイル描画は同じメッセージカードモデルに積み重ねられるはずです。 +現在のUIはすでにスレッドとリアクションをレンダリングできるため、添付レンダリングは同じメッセージカードモデルの上に重ねられるはずです。 -### メディアトランスポートによって可能になるシナリオ作業 +### メディアトランスポートで可能になるシナリオ作業 -添付ファイルが QA バスを流れるようになれば、より豊かな fake-chat シナリオを追加できます: +添付がQAバスを流れるようになれば、より豊かなfake-chatシナリオを追加できます: -- fake Slack でのインライン画像返信 -- 音声添付ファイルの理解 -- 動画添付ファイルの理解 -- 混在添付ファイルの順序 +- fake Slackでのインライン画像返信 +- 音声添付の理解 +- 動画添付の理解 +- 混在添付の順序 - メディアを保持したスレッド返信 ## 推奨事項 -次の実装チャンクは、次にするべきです: +次に実装すべきまとまりは以下です: -1. markdown シナリオローダー + zod スキーマを追加 -2. markdown から現在のカタログを生成 +1. Markdownシナリオローダー + zod schemaを追加 +2. 現在のカタログをMarkdownから生成 3. まずいくつかのシンプルなシナリオを移行 -4. 汎用 QA バス添付ファイル対応を追加 -5. QA UI でインライン画像を描画 +4. 汎用QAバス添付サポートを追加 +5. QA UIでインライン画像をレンダリング 6. その後、音声と動画へ拡張 -これは、両方の目標を実証する最小の道筋です: +これは次の2つの目標を実証する最小の道筋です: -- 汎用的な markdown 定義 QA -- より豊かな fake messaging surfaces +- 汎用のMarkdown定義QA +- より豊かなfake messaging surfaces ## 未解決の質問 -- シナリオファイルで、変数補間付きの埋め込み markdown プロンプトテンプレートを許可するかどうか -- setup/cleanup を名前付きセクションにするか、単なる順序付きアクションリストにするか -- アーティファクト参照をスキーマ上で強く型付けするか、文字列ベースにするか -- カスタムハンドラーを 1 つのレジストリに置くか、surface ごとのレジストリにするか -- 移行期間中、生成される JSON 互換性ファイルを引き続きチェックインしておくべきかどうか +- シナリオファイルで、変数補間付きの埋め込みMarkdownプロンプトテンプレートを許可すべきかどうか +- setup/cleanupは名前付きセクションにすべきか、それとも単なる順序付きアクションリストにすべきか +- アーティファクト参照はschema内で強く型付けすべきか、それとも文字列ベースにすべきか +- カスタムハンドラーは1つのregistryに置くべきか、それともsurfaceごとのregistryにすべきか +- 移行期間中、生成されたJSON互換ファイルを引き続きチェックインしておくべきかどうか