From 83991f4473bbab486831789b390996c79af7b3f2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 30 Apr 2026 20:11:34 +0000 Subject: [PATCH] chore(i18n): refresh ja-JP translations --- docs/ja-JP/cli/doctor.md | 63 +- docs/ja-JP/cli/migrate.md | 121 ++- docs/ja-JP/concepts/agent-workspace.md | 165 ++-- docs/ja-JP/gateway/security/index.md | 1222 ++++++++++-------------- docs/ja-JP/plugins/codex-harness.md | 522 +++++----- docs/ja-JP/tools/skills.md | 226 ++--- 6 files changed, 1077 insertions(+), 1242 deletions(-) diff --git a/docs/ja-JP/cli/doctor.md b/docs/ja-JP/cli/doctor.md index 4c2c6e24d..48f5c124f 100644 --- a/docs/ja-JP/cli/doctor.md +++ b/docs/ja-JP/cli/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - 接続や認証に問題があり、ガイド付きの修正を利用したい - - 更新して、妥当性確認をしたい場合 -summary: '`openclaw doctor` の CLI リファレンス (ヘルスチェック + ガイド付き修復)' + - 接続/認証の問題があり、ガイド付きの修正を行いたい + - 更新したので健全性チェックをしたい +summary: '`openclaw doctor` のCLIリファレンス（ヘルスチェック + ガイド付き修復）' title: 診断 x-i18n: - generated_at: "2026-04-30T05:04:13Z" + generated_at: "2026-04-30T20:05:43Z" model: gpt-5.5 provider: openai - source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c + source_hash: 265d82a10da086cf89687886e491be018a720b70021e0b26bd8f39b25a907e14 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` -Gateway とチャンネルのヘルスチェックとクイック修正。 +Gateway とチャンネルのヘルスチェック + クイック修正。 関連: @@ -34,39 +34,40 @@ openclaw doctor --generate-gateway-token ## オプション -- `--no-workspace-suggestions`: ワークスペースのメモリ/検索候補を無効化 +- `--no-workspace-suggestions`: ワークスペースのメモリ/検索候補を無効にする - `--yes`: プロンプトなしでデフォルトを受け入れる -- `--repair`: プロンプトなしで推奨修復を適用 +- `--repair`: プロンプトなしで推奨修復を適用する - `--fix`: `--repair` のエイリアス -- `--force`: 必要に応じたカスタムサービス設定の上書きを含め、積極的な修復を適用 -- `--non-interactive`: プロンプトなしで実行。安全なマイグレーションのみ -- `--generate-gateway-token`: Gateway トークンを生成して設定 -- `--deep`: 追加の Gateway インストールについてシステムサービスをスキャン +- `--force`: 必要に応じてカスタムサービス設定の上書きを含む、積極的な修復を適用する +- `--non-interactive`: プロンプトなしで実行する。安全な移行のみ +- `--generate-gateway-token`: Gateway トークンを生成して設定する +- `--deep`: 追加の Gateway インストールがないかシステムサービスをスキャンする 注記: -- インタラクティブプロンプト（keychain/OAuth 修正など）は、stdin が TTY であり、`--non-interactive` が設定されて**いない**場合にのみ実行されます。ヘッドレス実行（cron、Telegram、ターミナルなし）ではプロンプトをスキップします。 -- パフォーマンス: 非インタラクティブの `doctor` 実行では積極的な Plugin 読み込みをスキップするため、ヘッドレスのヘルスチェックを高速に保てます。インタラクティブセッションでは、チェックが Plugin の寄与を必要とする場合は引き続き Plugin を完全に読み込みます。 -- `--fix`（`--repair` のエイリアス）は `~/.openclaw/openclaw.json.bak` にバックアップを書き込み、不明な設定キーを削除して、それぞれの削除を一覧表示します。 -- 状態整合性チェックは、sessions ディレクトリ内の孤立した transcript ファイルを検出するようになりました。それらを `.deleted.` としてアーカイブするにはインタラクティブな確認が必要です。`--fix`、`--yes`、ヘッドレス実行ではそのまま残します。 -- Doctor は `~/.openclaw/cron/jobs.json`（または `cron.store`）もスキャンして、レガシーな cron ジョブ形状を検出し、スケジューラーが実行時に自動正規化する前にその場で書き換えることができます。 -- Doctor は、パッケージ化されたグローバルインストールへ書き込まずに、欠落している同梱 Plugin ランタイム依存関係を修復します。root 所有の npm インストールや強化された systemd ユニットでは、`OPENCLAW_PLUGIN_STAGE_DIR` を `/var/lib/openclaw/plugin-runtime-deps` のような書き込み可能なディレクトリに設定してください。`/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps` のようなパスリストにすることもでき、その場合、前の root は読み取り専用の検索レイヤーで、最後の root が修復対象になります。 -- Doctor は、Plugin 検出が健全な場合、`plugins.allow`/`plugins.entries` から欠落した Plugin ID を削除し、一致するぶら下がったチャンネル設定、Heartbeat ターゲット、チャンネルモデルオーバーライドも削除して、古い Plugin 設定を修復します。 -- Doctor は、影響を受ける `plugins.entries.` エントリを無効化し、その無効な `config` ペイロードを削除することで、無効な Plugin 設定を隔離します。Gateway 起動はすでにその不正な Plugin のみをスキップするため、他の Plugin とチャンネルは実行を継続できます。 -- 別のスーパーバイザーが Gateway ライフサイクルを所有している場合は、`OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。Doctor は引き続き Gateway/サービスのヘルス状態を報告し、非サービス修復を適用しますが、サービスの install/start/restart/bootstrap とレガシーサービスのクリーンアップはスキップします。 +- 対話型プロンプト（keychain/OAuth 修正など）は、stdin が TTY で、`--non-interactive` が設定されて**いない**場合にのみ実行されます。ヘッドレス実行（cron、Telegram、端末なし）ではプロンプトはスキップされます。 +- パフォーマンス: 非対話型の `doctor` 実行では、ヘッドレスヘルスチェックを高速に保つため、先行 Plugin 読み込みをスキップします。対話型セッションでは、チェックが Plugin の寄与を必要とする場合、引き続き Plugin を完全に読み込みます。 +- `--fix`（`--repair` のエイリアス）はバックアップを `~/.openclaw/openclaw.json.bak` に書き込み、不明な設定キーを削除して、それぞれの削除を一覧表示します。 +- 状態整合性チェックは、sessions ディレクトリ内の孤立した transcript ファイルを検出するようになりました。それらを `.deleted.` としてアーカイブするには対話型確認が必要です。`--fix`、`--yes`、ヘッドレス実行ではそのまま残します。 +- Doctor は `~/.openclaw/cron/jobs.json`（または `cron.store`）もスキャンしてレガシー Cron ジョブ形状を検出し、スケジューラが実行時に自動正規化する前に、その場で書き換えられます。 +- Doctor は、パッケージ化されたグローバルインストールに書き込まずに、欠落しているバンドル Plugin ランタイム依存関係を修復します。root 所有の npm インストールまたは強化された systemd ユニットでは、`OPENCLAW_PLUGIN_STAGE_DIR` を `/var/lib/openclaw/plugin-runtime-deps` などの書き込み可能なディレクトリに設定してください。`/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps` のようなパスリストにすることもでき、前方の root は読み取り専用の検索レイヤー、最後の root は修復対象になります。 +- Doctor は、Plugin 検出が正常な場合、`plugins.allow`/`plugins.entries` から欠落している Plugin id を削除し、一致するぶら下がったチャンネル設定、Heartbeat ターゲット、チャンネルモデル上書きも削除して、古い Plugin 設定を修復します。 +- Doctor は、影響を受ける `plugins.entries.` エントリを無効化し、その無効な `config` ペイロードを削除することで、無効な Plugin 設定を隔離します。Gateway 起動時には既に、その問題のある Plugin だけをスキップするため、他の Plugin とチャンネルは実行を継続できます。 +- 別の supervisor が Gateway ライフサイクルを所有している場合は、`OPENCLAW_SERVICE_REPAIR_POLICY=external` を設定します。Doctor は引き続き Gateway/サービスの正常性を報告し、サービス以外の修復を適用しますが、サービスのインストール/開始/再起動/bootstrap とレガシーサービスのクリーンアップはスキップします。 - Linux では、doctor は非アクティブな追加の Gateway 風 systemd ユニットを無視し、修復中に実行中の systemd Gateway サービスの command/entrypoint メタデータを書き換えません。アクティブなランチャーを意図的に置き換えたい場合は、先にサービスを停止するか、`openclaw gateway install --force` を使用してください。 -- Doctor は、レガシーのフラットな Talk 設定（`talk.voiceId`、`talk.modelId` など）を `talk.provider` + `talk.providers.` に自動マイグレーションします。 -- `doctor --fix` の繰り返し実行は、差分がオブジェクトキー順序のみの場合、Talk 正規化を報告/適用しなくなりました。 -- Doctor にはメモリ検索の準備状態チェックが含まれ、embedding 認証情報が欠落している場合は `openclaw configure --section model` を推奨できます。 -- Doctor は、コマンド所有者が設定されていない場合に警告します。コマンド所有者とは、所有者専用コマンドの実行と危険な操作の承認を許可された人間のオペレーターアカウントです。DM ペアリングは誰かがボットと会話できるようにするだけです。初回所有者 bootstrap が存在する前に送信者を承認した場合は、`commands.ownerAllowFrom` を明示的に設定してください。 -- sandbox モードが有効でも Docker が利用できない場合、doctor は修復方法（`install Docker` または `openclaw config set agents.defaults.sandbox.mode off`）を含む高シグナルの警告を報告します。 -- `gateway.auth.token`/`gateway.auth.password` が SecretRef 管理であり、現在のコマンドパスで利用できない場合、doctor は読み取り専用の警告を報告し、平文のフォールバック認証情報を書き込みません。 -- fix パスでチャンネル SecretRef 検査が失敗した場合、doctor は早期終了せずに続行し、警告を報告します。 -- Telegram `allowFrom` ユーザー名の自動解決（`doctor --fix`）には、現在のコマンドパスで解決可能な Telegram トークンが必要です。トークン検査が利用できない場合、doctor は警告を報告し、その実行では自動解決をスキップします。 +- Doctor は、レガシーのフラットな Talk 設定（`talk.voiceId`、`talk.modelId` など）を `talk.provider` + `talk.providers.` に自動移行します。 +- `doctor --fix` の繰り返し実行で、唯一の差分がオブジェクトキー順序だけの場合、Talk 正規化は報告/適用されなくなりました。 +- Doctor にはメモリ検索準備状況チェックが含まれ、embedding 認証情報が欠落している場合は `openclaw configure --section model` を推奨できます。 +- Doctor はコマンド所有者が設定されていない場合に警告します。コマンド所有者は、owner-only コマンドを実行し、危険なアクションを承認できる人間のオペレーターアカウントです。DM ペアリングは誰かが bot と会話できるようにするだけです。first-owner bootstrap が存在する前に送信者を承認していた場合は、`commands.ownerAllowFrom` を明示的に設定してください。 +- Doctor は、Codex モードのエージェントが設定され、個人用 Codex CLI アセットがオペレーターの Codex home に存在する場合に警告します。ローカルの Codex app-server 起動では、エージェントごとに分離された home を使用するため、意図的に昇格すべきアセットを棚卸しするには `openclaw migrate codex --dry-run` を使用してください。 +- sandbox モードが有効でも Docker が利用できない場合、doctor は修復方法（`install Docker` または `openclaw config set agents.defaults.sandbox.mode off`）を含む高シグナルな警告を報告します。 +- `gateway.auth.token`/`gateway.auth.password` が SecretRef 管理で、現在のコマンドパスでは利用できない場合、doctor は読み取り専用の警告を報告し、平文のフォールバック認証情報を書き込みません。 +- 修正パスでチャンネル SecretRef 検査に失敗した場合、doctor は早期終了せずに続行し、警告を報告します。 +- Telegram `allowFrom` ユーザー名の自動解決（`doctor --fix`）には、現在のコマンドパスで解決可能な Telegram トークンが必要です。トークン検査を利用できない場合、doctor は警告を報告し、そのパスでの自動解決をスキップします。 -## macOS: `launchctl` 環境変数オーバーライド +## macOS: `launchctl` 環境変数の上書き -以前に `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（または `...PASSWORD`）を実行した場合、その値が設定ファイルを上書きし、永続的な「unauthorized」エラーを引き起こす可能性があります。 +以前に `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（または `...PASSWORD`）を実行していた場合、その値は設定ファイルを上書きし、永続的な「unauthorized」エラーを引き起こす可能性があります。 ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN diff --git a/docs/ja-JP/cli/migrate.md b/docs/ja-JP/cli/migrate.md index b7ef111f8..aa15b3ed5 100644 --- a/docs/ja-JP/cli/migrate.md +++ b/docs/ja-JP/cli/migrate.md @@ -1,21 +1,21 @@ --- read_when: - - Hermes または別のエージェントシステムから OpenClaw に移行したい - - Plugin が所有する移行プロバイダーを追加しています -summary: '`openclaw migrate` の CLI リファレンス（別のエージェントシステムから状態をインポート）' + - Hermes など別のエージェントシステムから OpenClaw へ移行したい場合 + - Plugin 所有のマイグレーションプロバイダーを追加する場合 +summary: '`openclaw migrate` のCLIリファレンス（別のエージェントシステムから状態をインポート）' title: 移行 x-i18n: - generated_at: "2026-04-30T05:05:22Z" + generated_at: "2026-04-30T20:05:35Z" model: gpt-5.5 provider: openai - source_hash: d3db14c16b8f9dcbf86a4f12558cf4e8555aa9a255637034fb804148996a225e + source_hash: ffcd9e874bdaa0a5195e712d4fccd7b3d53034cb362c7f7462e9c7df72477b1a source_path: cli/migrate.md workflow: 16 --- # `openclaw migrate` -Plugin が所有する移行プロバイダーを通じて、別のエージェントシステムから状態をインポートします。バンドルされたプロバイダーは [Claude](/ja-JP/install/migrating-claude) と [Hermes](/ja-JP/install/migrating-hermes) に対応しています。サードパーティのプラグインは追加プロバイダーを登録できます。 +Plugin が所有する移行プロバイダーを通じて、別のエージェントシステムから状態をインポートします。バンドルされたプロバイダーは Codex CLI の状態、[Claude](/ja-JP/install/migrating-claude)、[Hermes](/ja-JP/install/migrating-hermes) を扱います。サードパーティ Plugin は追加プロバイダーを登録できます。 ユーザー向けの手順は、[Claude からの移行](/ja-JP/install/migrating-claude) と [Hermes からの移行](/ja-JP/install/migrating-hermes) を参照してください。[移行ハブ](/ja-JP/install/migrating) にはすべてのパスが一覧表示されています。 @@ -26,8 +26,12 @@ Plugin が所有する移行プロバイダーを通じて、別のエージェ ```bash openclaw migrate list openclaw migrate claude --dry-run +openclaw migrate codex --dry-run +openclaw migrate codex --skill gog-vault77-google-workspace openclaw migrate hermes --dry-run openclaw migrate hermes +openclaw migrate apply codex --yes --skill gog-vault77-google-workspace +openclaw migrate apply codex --yes openclaw migrate apply claude --yes openclaw migrate apply hermes --yes openclaw migrate apply hermes --include-secrets --yes @@ -37,64 +41,67 @@ openclaw onboard --import-from hermes --import-source ~/.hermes ``` - 登録済み移行プロバイダーの名前です。例: `hermes`。インストール済みプロバイダーを確認するには `openclaw migrate list` を実行します。 + 登録済み移行プロバイダーの名前。例: `hermes`。インストール済みプロバイダーを確認するには `openclaw migrate list` を実行します。 - プランを作成し、状態を変更せずに終了します。 + 計画を作成して、状態を変更せずに終了します。 ソース状態ディレクトリを上書きします。Hermes のデフォルトは `~/.hermes` です。 - サポートされている認証情報をインポートします。デフォルトではオフです。 + 対応している認証情報をインポートします。デフォルトではオフです。 - プランで競合が報告された場合に、apply が既存のターゲットを置き換えることを許可します。 + 計画が競合を報告した場合に、apply が既存のターゲットを置き換えることを許可します。 確認プロンプトをスキップします。非対話モードでは必須です。 + + スキル名またはアイテム ID で、コピー対象のスキル項目を 1 つ選択します。複数のスキルを移行するには、このフラグを繰り返します。省略した場合、対話型 Codex 移行ではチェックボックス選択が表示され、非対話型移行では計画されたすべてのスキルが保持されます。 + apply 前のバックアップをスキップします。ローカルの OpenClaw 状態が存在する場合は `--force` が必要です。 - apply が通常ならバックアップのスキップを拒否する場合に、`--no-backup` と併用する必要があります。 + apply が通常ならバックアップのスキップを拒否する場合に、`--no-backup` とあわせて必要です。 - プランまたは apply 結果を JSON として出力します。`--json` を指定し、`--yes` を指定しない場合、apply はプランを出力し、状態を変更しません。 + 計画または apply 結果を JSON として出力します。`--json` を指定し、`--yes` を指定しない場合、apply は計画を出力し、状態を変更しません。 -## 安全性モデル +## 安全モデル `openclaw migrate` はプレビュー優先です。 - - プロバイダーは、変更が行われる前に、競合、スキップされた項目、機密項目を含む項目別プランを返します。JSON プラン、apply 出力、移行レポートでは、API キー、トークン、認可ヘッダー、Cookie、パスワードなど、シークレットのように見えるネストされたキーがマスクされます。 + + プロバイダーは、何かが変更される前に、競合、スキップされた項目、機密項目を含む項目別の計画を返します。JSON 計画、apply 出力、移行レポートでは、API キー、トークン、認可ヘッダー、Cookie、パスワードなど、シークレットらしいネストされたキーが伏せられます。 - `openclaw migrate apply ` はプランをプレビューし、`--yes` が設定されていない限り、状態を変更する前に確認します。非対話モードでは、apply に `--yes` が必要です。 + `openclaw migrate apply ` は、`--yes` が設定されていない限り、状態を変更する前に計画をプレビューして確認を求めます。非対話モードでは、apply に `--yes` が必要です。 - apply は移行を適用する前に OpenClaw バックアップを作成して検証します。ローカルの OpenClaw 状態がまだ存在しない場合、バックアップ手順はスキップされ、移行を続行できます。状態が存在する場合にバックアップをスキップするには、`--no-backup` と `--force` の両方を渡します。 + apply は、移行を適用する前に OpenClaw バックアップを作成して検証します。ローカルの OpenClaw 状態がまだ存在しない場合、バックアップ手順はスキップされ、移行を続行できます。状態が存在する場合にバックアップをスキップするには、`--no-backup` と `--force` の両方を渡します。 - プランに競合がある場合、apply は続行を拒否します。プランを確認し、既存ターゲットを置き換える意図がある場合は `--overwrite` を付けて再実行します。プロバイダーは、上書きされたファイルについて、移行レポートディレクトリに項目レベルのバックアップを書き込む場合があります。 + 計画に競合がある場合、apply は続行を拒否します。計画を確認し、既存のターゲットを置き換える意図がある場合は `--overwrite` を付けて再実行します。プロバイダーは、上書きされたファイルについて、移行レポートディレクトリに項目単位のバックアップを書き込む場合があります。 - シークレットはデフォルトではインポートされません。サポートされている認証情報をインポートするには `--include-secrets` を使用します。 + シークレットはデフォルトではインポートされません。対応している認証情報をインポートするには `--include-secrets` を使用します。 ## Claude プロバイダー -バンドルされた Claude プロバイダーは、デフォルトで `~/.claude` にある Claude Code の状態を検出します。特定の Claude Code ホームまたはプロジェクトルートをインポートするには `--from ` を使用します。 +バンドルされた Claude プロバイダーは、デフォルトで `~/.claude` にある Claude Code の状態を検出します。特定の Claude Code ホームまたはプロジェクトルートをインポートするには、`--from ` を使用します。 ユーザー向けの手順は、[Claude からの移行](/ja-JP/install/migrating-claude) を参照してください。 -### Claude がインポートするもの +### Claude がインポートする内容 - プロジェクトの `CLAUDE.md` と `.claude/CLAUDE.md` を OpenClaw エージェントワークスペースへ。 - ユーザーの `~/.claude/CLAUDE.md` をワークスペースの `USER.md` に追記。 @@ -102,33 +109,55 @@ openclaw onboard --import-from hermes --import-source ~/.hermes - `SKILL.md` を含む Claude スキルディレクトリ。 - Claude コマンド Markdown ファイルを、手動呼び出し専用の OpenClaw スキルに変換。 -### アーカイブと手動レビュー状態 +### アーカイブおよび手動レビュー状態 -Claude のフック、権限、環境デフォルト、ローカルメモリ、パススコープルール、サブエージェント、キャッシュ、プラン、プロジェクト履歴は、移行レポートに保存されるか、手動レビュー項目として報告されます。OpenClaw は、フックの実行、広範な許可リストのコピー、OAuth/Desktop 認証情報状態の自動インポートを行いません。 +Claude のフック、権限、環境デフォルト、ローカルメモリ、パススコープのルール、サブエージェント、キャッシュ、計画、プロジェクト履歴は、移行レポートに保持されるか、手動レビュー項目として報告されます。OpenClaw は、フックの実行、広範な許可リストのコピー、OAuth/Desktop 認証情報状態の自動インポートを行いません。 + +## Codex プロバイダー + +バンドルされた Codex プロバイダーは、デフォルトで `~/.codex` にある Codex CLI の状態を検出します。または、その環境変数が設定されている場合は `CODEX_HOME` にある状態を検出します。特定の Codex ホームをインベントリするには `--from ` を使用します。 + +OpenClaw Codex ハーネスへ移行し、有用な個人用 Codex CLI アセットを意図的に昇格したい場合に、このプロバイダーを使用します。ローカルの Codex アプリサーバー起動では、エージェントごとの `CODEX_HOME` と `HOME` ディレクトリを使用するため、デフォルトでは個人用 Codex CLI 状態を読み取りません。 + +対話型ターミナルで `openclaw migrate codex` を実行すると、完全な計画をプレビューしたあと、最終的な apply 確認の前に、スキルコピー項目用のチェックボックス選択が開きます。すべてのスキルは選択済みで開始します。このエージェントへコピーしたくないスキルのチェックを外してください。スクリプト実行または厳密な実行では、スキルごとに `--skill ` を 1 回渡します。例: + +```bash +openclaw migrate codex --dry-run --skill gog-vault77-google-workspace +openclaw migrate apply codex --yes --skill gog-vault77-google-workspace +``` + +### Codex がインポートする内容 + +- `$CODEX_HOME/skills` 配下の Codex CLI スキルディレクトリ。ただし Codex の `.system` キャッシュは除外します。 +- `$HOME/.agents/skills` 配下の個人用 AgentSkills。エージェントごとの所有にしたい場合、現在の OpenClaw エージェントワークスペースへコピーされます。 + +### 手動レビュー対象の Codex 状態 + +Codex ネイティブ Plugin、`config.toml`、ネイティブ `hooks/hooks.json` は自動的には有効化されません。Plugin は MCP サーバー、アプリ、フック、その他の実行可能な動作を公開する場合があるため、プロバイダーはそれらを OpenClaw に読み込むのではなく、レビュー対象として報告します。設定ファイルとフックファイルは、手動レビューのために移行レポートへコピーされます。 ## Hermes プロバイダー バンドルされた Hermes プロバイダーは、デフォルトで `~/.hermes` にある状態を検出します。Hermes が別の場所にある場合は `--from ` を使用します。 -### Hermes がインポートするもの +### Hermes がインポートする内容 -- `config.yaml` からデフォルトモデル設定。 -- `providers` と `custom_providers` から、設定済みモデルプロバイダーとカスタム OpenAI 互換エンドポイント。 -- `mcp_servers` または `mcp.servers` から MCP サーバー定義。 +- `config.yaml` からのデフォルトモデル設定。 +- `providers` と `custom_providers` からの設定済みモデルプロバイダーおよびカスタム OpenAI 互換エンドポイント。 +- `mcp_servers` または `mcp.servers` からの MCP サーバー定義。 - `SOUL.md` と `AGENTS.md` を OpenClaw エージェントワークスペースへ。 -- `memories/MEMORY.md` と `memories/USER.md` をワークスペースメモリファイルに追記。 -- OpenClaw ファイルメモリ用のメモリ設定デフォルト、および Honcho などの外部メモリプロバイダー用のアーカイブまたは手動レビュー項目。 +- `memories/MEMORY.md` と `memories/USER.md` をワークスペースのメモリファイルへ追記。 +- OpenClaw ファイルメモリ用のメモリ設定デフォルト、および Honcho などの外部メモリプロバイダー用のアーカイブ項目または手動レビュー項目。 - `skills//` 配下に `SKILL.md` ファイルを含む Skills。 -- `skills.config` からスキルごとの設定値。 -- `.env` からサポートされている API キー。`--include-secrets` を指定した場合のみ。 +- `skills.config` からのスキルごとの設定値。 +- `.env` からの対応 API キー。`--include-secrets` を指定した場合のみ。 -### サポートされている `.env` キー +### 対応している `.env` キー `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`. -### アーカイブ専用状態 +### アーカイブのみの状態 -OpenClaw が安全に解釈できない Hermes の状態は、手動レビュー用に移行レポートへコピーされますが、ライブの OpenClaw 設定や認証情報には読み込まれません。これにより、不透明または安全でない状態を、OpenClaw が自動的に実行または信頼できるかのように扱うことなく保持できます。 +OpenClaw が安全に解釈できない Hermes 状態は、手動レビューのために移行レポートへコピーされますが、稼働中の OpenClaw 設定や認証情報には読み込まれません。これにより、OpenClaw が自動的に実行または信頼できると見せかけることなく、不透明または安全でない状態を保持できます。 - `plugins/` - `sessions/` @@ -144,9 +173,9 @@ OpenClaw が安全に解釈できない Hermes の状態は、手動レビュー openclaw doctor ``` -## Plugin コントラクト +## Plugin 契約 -移行ソースはプラグインです。プラグインは `openclaw.plugin.json` でプロバイダー ID を宣言します。 +移行ソースは Plugin です。Plugin は `openclaw.plugin.json` でプロバイダー ID を宣言します。 ```json { @@ -156,22 +185,22 @@ openclaw doctor } ``` -実行時にプラグインは `api.registerMigrationProvider(...)` を呼び出します。プロバイダーは `detect`、`plan`、`apply` を実装します。コアは CLI オーケストレーション、バックアップポリシー、プロンプト、JSON 出力、競合の事前確認を所有します。コアはレビュー済みプランを `apply(ctx, plan)` に渡し、プロバイダーは互換性のためにその引数がない場合のみプランを再構築できます。 +実行時に Plugin は `api.registerMigrationProvider(...)` を呼び出します。プロバイダーは `detect`、`plan`、`apply` を実装します。コアは CLI オーケストレーション、バックアップポリシー、プロンプト、JSON 出力、競合の事前確認を所有します。コアはレビュー済み計画を `apply(ctx, plan)` に渡し、互換性のためにその引数がない場合のみ、プロバイダーは計画を再構築できます。 -プロバイダープラグインは、項目の構築とサマリー件数に `openclaw/plugin-sdk/migration` を使用でき、競合を認識するファイルコピー、アーカイブ専用レポートコピー、キャッシュされた設定ランタイムラッパー、移行レポートには `openclaw/plugin-sdk/migration-runtime` を使用できます。 +プロバイダー Plugin は、項目構築とサマリー数に `openclaw/plugin-sdk/migration` を使用でき、競合を考慮したファイルコピー、アーカイブ専用レポートコピー、キャッシュされた config-runtime ラッパー、移行レポートに `openclaw/plugin-sdk/migration-runtime` を使用できます。 ## オンボーディング連携 -プロバイダーが既知のソースを検出した場合、オンボーディングは移行を提示できます。`openclaw onboard --flow import` と `openclaw setup --wizard --import-from hermes` はどちらも同じプラグイン移行プロバイダーを使用し、適用前に引き続きプレビューを表示します。 +プロバイダーが既知のソースを検出した場合、オンボーディングは移行を提案できます。`openclaw onboard --flow import` と `openclaw setup --wizard --import-from hermes` はどちらも同じ Plugin 移行プロバイダーを使用し、適用前には引き続きプレビューを表示します。 -オンボーディングインポートには、新規の OpenClaw セットアップが必要です。すでにローカル状態がある場合は、まず設定、認証情報、セッション、ワークスペースをリセットしてください。既存セットアップ向けのバックアップと上書き、またはマージインポートは機能ゲートされています。 +オンボーディングインポートには、新規の OpenClaw セットアップが必要です。ローカル状態がすでにある場合は、先に設定、認証情報、セッション、ワークスペースをリセットしてください。既存セットアップ向けのバックアップ付き上書きまたはマージインポートは、機能ゲートされています。 -## 関連 +## 関連項目 -- [Hermes からの移行](/ja-JP/install/migrating-hermes): ユーザー向け手順。 -- [Claude からの移行](/ja-JP/install/migrating-claude): ユーザー向け手順。 -- [移行](/ja-JP/install/migrating): OpenClaw を新しいマシンへ移動します。 -- [Doctor](/ja-JP/gateway/doctor): 移行適用後のヘルスチェック。 -- [プラグイン](/ja-JP/tools/plugin): プラグインのインストールと登録。 +- [Hermes からの移行](/ja-JP/install/migrating-hermes): ユーザー向けの手順。 +- [Claude からの移行](/ja-JP/install/migrating-claude): ユーザー向けの手順。 +- [移行](/ja-JP/install/migrating): OpenClaw を新しいマシンへ移動する。 +- [Doctor](/ja-JP/gateway/doctor): 移行を適用した後のヘルスチェック。 +- [Plugins](/ja-JP/tools/plugin): Plugin のインストールと登録。 diff --git a/docs/ja-JP/concepts/agent-workspace.md b/docs/ja-JP/concepts/agent-workspace.md index 75f65f9d6..957246359 100644 --- a/docs/ja-JP/concepts/agent-workspace.md +++ b/docs/ja-JP/concepts/agent-workspace.md @@ -1,34 +1,34 @@ --- read_when: - - エージェントワークスペースまたはそのファイルレイアウトを説明する必要がある - - エージェントワークスペースをバックアップまたは移行したい + - エージェントのワークスペースまたはそのファイル構成を説明する必要がある + - エージェントワークスペースをバックアップまたは移行したい場合 sidebarTitle: Agent workspace -summary: 'エージェントワークスペース: 場所、レイアウト、バックアップ戦略' -title: エージェントワークスペース +summary: 'エージェントのワークスペース: 場所、レイアウト、バックアップ戦略' +title: エージェントのワークスペース x-i18n: - generated_at: "2026-04-26T11:27:17Z" - model: gpt-5.4 + generated_at: "2026-04-30T20:05:31Z" + model: gpt-5.5 provider: openai - source_hash: 35d59d1f0dec05db30f9166a43bfa519d7299b08d093bbeb905d8f83e5cd022a + source_hash: b1ccf74cbec3ff20f4c1c1ce52f099a7ca3365b2536b0aad6ff1d3a5fafcca0a source_path: concepts/agent-workspace.md - workflow: 15 + workflow: 16 --- -ワークスペースはエージェントのホームです。これは、ファイルツールとワークスペースコンテキストで使用される唯一の作業ディレクトリです。プライベートに保ち、メモリとして扱ってください。 +ワークスペースはエージェントのホームです。ファイルツールとワークスペースコンテキストで使用される唯一の作業ディレクトリです。非公開に保ち、メモリとして扱ってください。 -これは、config、credentials、sessions を保存する `~/.openclaw/` とは別です。 +これは、設定、認証情報、セッションを保存する `~/.openclaw/` とは別です。 -ワークスペースはハードなサンドボックスではなく、**デフォルトの cwd** です。ツールは相対パスをワークスペース基準で解決しますが、sandboxing が有効でない限り、絶対パスでは引き続きホスト上の他の場所に到達できます。分離が必要な場合は、[`agents.defaults.sandbox`](/ja-JP/gateway/sandboxing)（および/またはエージェントごとのsandbox config）を使用してください。 +ワークスペースは**デフォルトの cwd**であり、厳密なサンドボックスではありません。ツールは相対パスをワークスペースを基準に解決しますが、サンドボックスが有効でない限り、絶対パスはホスト上の別の場所にも到達できます。分離が必要な場合は、[`agents.defaults.sandbox`](/ja-JP/gateway/sandboxing)（および/またはエージェントごとのサンドボックス設定）を使用してください。 -sandboxing が有効で、`workspaceAccess` が `"rw"` でない場合、ツールはホストのワークスペースではなく、`~/.openclaw/sandboxes` 配下のsandboxワークスペース内で動作します。 +サンドボックスが有効で、`workspaceAccess` が `"rw"` でない場合、ツールはホストのワークスペースではなく、`~/.openclaw/sandboxes` 配下のサンドボックスワークスペース内で動作します。 ## デフォルトの場所 - デフォルト: `~/.openclaw/workspace` - `OPENCLAW_PROFILE` が設定されていて `"default"` でない場合、デフォルトは `~/.openclaw/workspace-` になります。 -- `~/.openclaw/openclaw.json` で上書き: +- `~/.openclaw/openclaw.json` で上書きします: ```json5 { @@ -40,13 +40,13 @@ sandboxing が有効で、`workspaceAccess` が `"rw"` でない場合、ツー } ``` -`openclaw onboard`、`openclaw configure`、または `openclaw setup` は、ワークスペースを作成し、不足している場合はbootstrapファイルを初期配置します。 +`openclaw onboard`、`openclaw configure`、または `openclaw setup` は、ワークスペースを作成し、ブートストラップファイルが存在しない場合はそれらを初期配置します。 -Sandbox seed のコピーでは、ワークスペース内の通常ファイルのみ受け付けます。ソースワークスペースの外を指す symlink/hardlink エイリアスは無視されます。 +サンドボックスの初期コピーは、ワークスペース内の通常ファイルのみを受け入れます。ソースワークスペースの外部に解決されるシンボリックリンク/ハードリンクのエイリアスは無視されます。 -すでにワークスペースファイルを自分で管理している場合は、bootstrapファイル作成を無効にできます。 +ワークスペースファイルをすでに自分で管理している場合は、ブートストラップファイルの作成を無効にできます: ```json5 { agents: { defaults: { skipBootstrap: true } } } @@ -54,82 +54,83 @@ Sandbox seed のコピーでは、ワークスペース内の通常ファイル ## 追加のワークスペースフォルダー -古いインストールでは `~/openclaw` が作成されている場合があります。複数のワークスペースディレクトリを残しておくと、同時にアクティブなのは1つだけなので、認証や状態のずれがわかりにくくなることがあります。 +古いインストールでは `~/openclaw` が作成されている場合があります。複数のワークスペースディレクトリを残しておくと、一度に有効なのは1つのワークスペースだけであるため、認証や状態のずれで混乱が生じる可能性があります。 -**推奨:** アクティブなワークスペースは1つだけにしてください。追加フォルダーをもう使っていない場合は、アーカイブするかゴミ箱へ移動してください（例: `trash ~/openclaw`）。意図的に複数のワークスペースを保持する場合は、`agents.defaults.workspace` がアクティブなものを指していることを確認してください。 +**推奨:** 有効なワークスペースは1つだけにしてください。追加のフォルダーをもう使用していない場合は、アーカイブするかゴミ箱に移動してください（例: `trash ~/openclaw`）。意図的に複数のワークスペースを維持する場合は、`agents.defaults.workspace` が有効なものを指していることを確認してください。 `openclaw doctor` は、追加のワークスペースディレクトリを検出すると警告します。 ## ワークスペースファイルマップ -これらは、OpenClaw がワークスペース内にあることを想定する標準ファイルです。 +これらは OpenClaw がワークスペース内にあることを想定する標準ファイルです: - - エージェント向けの運用指示と、メモリの使い方。すべてのセッション開始時に読み込まれます。ルール、優先順位、「どう振る舞うか」の詳細を書くのに適しています。 + + エージェントの操作指示と、メモリの使い方です。すべてのセッション開始時に読み込まれます。ルール、優先順位、「どのように振る舞うか」の詳細を書くのに適しています。 - ペルソナ、トーン、境界。毎セッション読み込まれます。ガイド: [SOUL.md personality guide](/ja-JP/concepts/soul)。 + ペルソナ、トーン、境界です。すべてのセッションで読み込まれます。ガイド: [SOUL.md パーソナリティガイド](/ja-JP/concepts/soul)。 - - ユーザーが誰か、どう呼びかけるか。毎セッション読み込まれます。 + + ユーザーが誰で、どのように呼びかけるかです。すべてのセッションで読み込まれます。 - エージェントの名前、雰囲気、絵文字。bootstrap ritual 中に作成/更新されます。 + エージェントの名前、雰囲気、絵文字です。ブートストラップ儀式中に作成/更新されます。 - ローカルツールや慣例に関するメモ。ツールの可用性は制御せず、ガイダンスのみです。 + ローカルツールと慣例に関するメモです。ツールの利用可否を制御するものではなく、ガイダンスにすぎません。 - - Heartbeat実行用の任意の小さなチェックリスト。トークン消費を避けるため短く保ってください。 + + Heartbeat 実行用の任意の小さなチェックリストです。トークン消費を避けるため短くしてください。 - gateway再起動時に自動実行される任意の起動チェックリスト（[internal hooks](/ja-JP/automation/hooks) が有効な場合）。短く保ち、送信にはmessageツールを使ってください。 + Gateway 再起動時に自動実行される任意の起動チェックリストです（[内部フック](/ja-JP/automation/hooks)が有効な場合）。短く保ち、外部送信にはメッセージツールを使用してください。 - - 一度きりの初回実行ritual。真新しいワークスペースにのみ作成されます。ritual が完了したら削除してください。 + + 1回限りの初回実行の儀式です。完全に新しいワークスペースにのみ作成されます。儀式が完了したら削除してください。 - 日次メモリログ（1日1ファイル）。セッション開始時に今日分と昨日分を読むことを推奨します。 + 日次メモリログ（1日につき1ファイル）です。セッション開始時に今日と昨日を読むことを推奨します。 - - キュレートされた長期メモリ。メインのプライベートセッションでのみ読み込んでください（共有/グループコンテキストではありません）。ワークフローと自動メモリflushについては [Memory](/ja-JP/concepts/memory) を参照してください。 + + キュレーション済みの長期メモリです。メインの非公開セッションでのみ読み込んでください（共有/グループコンテキストでは使用しません）。ワークフローと自動メモリフラッシュについては [Memory](/ja-JP/concepts/memory) を参照してください。 - - ワークスペース固有のSkills。そのワークスペースで最も優先度の高いskillの場所です。名前が衝突した場合、project agent skills、personal agent skills、managed skills、bundled skills、`skills.load.extraDirs` より優先されます。 + + ワークスペース固有の Skills です。そのワークスペースで最も優先度の高い Skills の場所です。名前が衝突した場合、プロジェクトエージェント Skills、個人エージェント Skills、管理対象 Skills、バンドル済み Skills、および `skills.load.extraDirs` を上書きします。 - - Node表示用のCanvas UIファイル（例: `canvas/index.html`）。 + + ノード表示用の Canvas UI ファイルです（例: `canvas/index.html`）。 -bootstrapファイルが欠けている場合、OpenClaw はセッションに「missing file」マーカーを注入して続行します。大きいbootstrapファイルは注入時に切り詰められます。上限は `agents.defaults.bootstrapMaxChars`（デフォルト: 12000）と `agents.defaults.bootstrapTotalMaxChars`（デフォルト: 60000）で調整できます。`openclaw setup` は既存ファイルを上書きせずに、不足しているデフォルトを再作成できます。 +ブートストラップファイルが欠けている場合、OpenClaw は「missing file」マーカーをセッションに挿入して続行します。大きなブートストラップファイルは挿入時に切り詰められます。制限は `agents.defaults.bootstrapMaxChars`（デフォルト: 12000）と `agents.defaults.bootstrapTotalMaxChars`（デフォルト: 60000）で調整してください。`openclaw setup` は、既存ファイルを上書きせずに欠けているデフォルトを再作成できます。 ## ワークスペースに含まれないもの -これらは `~/.openclaw/` 配下にあり、ワークスペースrepoにコミットすべきではありません。 +これらは `~/.openclaw/` 配下にあり、ワークスペースリポジトリにコミットすべきではありません: -- `~/.openclaw/openclaw.json`（config） -- `~/.openclaw/agents//agent/auth-profiles.json`（モデル認証プロファイル: OAuth + API keys） -- `~/.openclaw/credentials/`（チャネル/プロバイダー状態およびレガシーOAuthインポートデータ） -- `~/.openclaw/agents//sessions/`（session transcript + metadata） -- `~/.openclaw/skills/`（managed Skills） +- `~/.openclaw/openclaw.json`（設定） +- `~/.openclaw/agents//agent/auth-profiles.json`（モデル認証プロファイル: OAuth + API キー） +- `~/.openclaw/agents//agent/codex-home/`（エージェントごとの Codex ランタイムアカウント、設定、Skills、plugins、ネイティブスレッド状態） +- `~/.openclaw/credentials/`（チャンネル/プロバイダー状態とレガシー OAuth インポートデータ） +- `~/.openclaw/agents//sessions/`（セッションのトランスクリプト + メタデータ） +- `~/.openclaw/skills/`（管理対象 Skills） -sessions や config を移行する必要がある場合は、それらを別途コピーし、バージョン管理には入れないでください。 +セッションや設定を移行する必要がある場合は、別途コピーし、バージョン管理に含めないでください。 -## Gitバックアップ（推奨、プライベート） +## Git バックアップ（推奨、非公開） -ワークスペースはプライベートメモリとして扱ってください。**プライベートな** git repo に入れて、バックアップおよび復旧可能にしてください。 +ワークスペースは非公開メモリとして扱ってください。バックアップと復旧ができるよう、**private** git リポジトリに置いてください。 -これらの手順は、Gateway が動作しているマシン上で実行してください（ワークスペースはそこにあります）。 +これらの手順は Gateway が動作するマシン上で実行してください（そこにワークスペースがあります）。 - - git がインストールされていれば、真新しいワークスペースは自動的に初期化されます。このワークスペースがまだrepoでない場合は、次を実行してください。 + + git がインストールされている場合、完全に新しいワークスペースは自動的に初期化されます。このワークスペースがまだリポジトリでない場合は、次を実行します: ```bash cd ~/.openclaw/workspace @@ -139,13 +140,13 @@ sessions や config を移行する必要がある場合は、それらを別途 ``` - + - - 1. GitHubで新しい**プライベート**リポジトリを作成します。 - 2. README付きでは初期化しないでください（merge conflict を避けるため）。 - 3. HTTPSのremote URLをコピーします。 - 4. remoteを追加してpushします。 + + 1. GitHub で新しい **private** リポジトリを作成します。 + 2. README で初期化しないでください（マージコンフリクトを避けるため）。 + 3. HTTPS リモート URL をコピーします。 + 4. リモートを追加して push します: ```bash git branch -M main @@ -159,11 +160,11 @@ sessions や config を移行する必要がある場合は、それらを別途 gh repo create openclaw-workspace --private --source . --remote origin --push ``` - - 1. GitLabで新しい**プライベート**リポジトリを作成します。 - 2. README付きでは初期化しないでください（merge conflict を避けるため）。 - 3. HTTPSのremote URLをコピーします。 - 4. remoteを追加してpushします。 + + 1. GitLab で新しい **private** リポジトリを作成します。 + 2. README で初期化しないでください（マージコンフリクトを避けるため）。 + 3. HTTPS リモート URL をコピーします。 + 4. リモートを追加して push します: ```bash git branch -M main @@ -184,19 +185,19 @@ sessions や config を移行する必要がある場合は、それらを別途 -## secrets をコミットしない +## シークレットをコミットしない -プライベートrepoであっても、ワークスペースにsecretsを保存するのは避けてください。 +private リポジトリであっても、ワークスペースにシークレットを保存することは避けてください: -- API keys、OAuth tokens、passwords、またはprivate credentials。 -- `~/.openclaw/` 配下のもの。 -- チャットや機密添付の生ダンプ。 +- API キー、OAuth トークン、パスワード、または非公開認証情報。 +- `~/.openclaw/` 配下のあらゆるもの。 +- チャットや機密添付ファイルの生ダンプ。 -機密参照を保存する必要がある場合は、placeholder を使い、実際のsecretは別の場所（password manager、environment variables、または `~/.openclaw/`）に保持してください。 +機密参照を保存する必要がある場合は、プレースホルダーを使用し、実際のシークレットは別の場所（パスワードマネージャー、環境変数、または `~/.openclaw/`）に保管してください。 -推奨される `.gitignore` の初期例: +推奨 `.gitignore` スターター: ```gitignore .DS_Store @@ -209,28 +210,28 @@ sessions や config を移行する必要がある場合は、それらを別途 ## ワークスペースを新しいマシンへ移動する - - 目的のパス（デフォルトは `~/.openclaw/workspace`）にrepoをcloneします。 + + 目的のパス（デフォルトは `~/.openclaw/workspace`）にリポジトリをクローンします。 - - `~/.openclaw/openclaw.json` の `agents.defaults.workspace` をそのパスに設定します。 + + `~/.openclaw/openclaw.json` で `agents.defaults.workspace` をそのパスに設定します。 - - `openclaw setup --workspace ` を実行して、不足しているファイルを初期配置します。 + + `openclaw setup --workspace ` を実行して、欠けているファイルを初期配置します。 - - sessions が必要な場合は、古いマシンの `~/.openclaw/agents//sessions/` を別途コピーしてください。 + + セッションが必要な場合は、古いマシンから `~/.openclaw/agents//sessions/` を別途コピーします。 -## 高度な注意事項 +## 詳細メモ - マルチエージェントルーティングでは、エージェントごとに異なるワークスペースを使用できます。ルーティング設定については [Channel routing](/ja-JP/channels/channel-routing) を参照してください。 -- `agents.defaults.sandbox` が有効な場合、non-main sessions は `agents.defaults.sandbox.workspaceRoot` 配下のセッションごとのsandboxワークスペースを使用できます。 +- `agents.defaults.sandbox` が有効な場合、メイン以外のセッションは `agents.defaults.sandbox.workspaceRoot` 配下のセッションごとのサンドボックスワークスペースを使用できます。 ## 関連 - [Heartbeat](/ja-JP/gateway/heartbeat) — HEARTBEAT.md ワークスペースファイル -- [Sandboxing](/ja-JP/gateway/sandboxing) — sandbox環境でのワークスペースアクセス -- [Session](/ja-JP/concepts/session) — session保存パス -- [Standing orders](/ja-JP/automation/standing-orders) — ワークスペースファイル内の永続的な指示 +- [サンドボックス化](/ja-JP/gateway/sandboxing) — サンドボックス環境でのワークスペースアクセス +- [セッション](/ja-JP/concepts/session) — セッション保存パス +- [常設指示](/ja-JP/automation/standing-orders) — ワークスペースファイル内の永続的な指示 diff --git a/docs/ja-JP/gateway/security/index.md b/docs/ja-JP/gateway/security/index.md index ea30b5689..fb5865e01 100644 --- a/docs/ja-JP/gateway/security/index.md +++ b/docs/ja-JP/gateway/security/index.md @@ -1,42 +1,42 @@ --- read_when: - アクセスや自動化を拡大する機能の追加 -summary: シェルアクセス権を持つ AI Gateway を実行する際のセキュリティ上の考慮事項と脅威モデル +summary: シェルアクセスを備えた AI Gateway を実行する際のセキュリティ上の考慮事項と脅威モデル title: セキュリティ x-i18n: - generated_at: "2026-04-30T05:16:00Z" + generated_at: "2026-04-30T20:05:26Z" model: gpt-5.5 provider: openai - source_hash: 7a1733675f30b5eb8a45eae671aaa8cf41323e16d2543a02ed7bda558c4ebad1 + source_hash: 20cc63aa79aff1ec42a9c1a10037b11ad5dcc1a3a23d9e76842d4ffd9a920ad7 source_path: gateway/security/index.md workflow: 16 --- - **パーソナルアシスタントの信頼モデル。** このガイダンスは、Gateway ごとに 1 つの信頼された - オペレーター境界（単一ユーザーのパーソナルアシスタントモデル）があることを前提としています。 - OpenClaw は、1 つのエージェントまたは Gateway を複数の敵対的ユーザーが共有するための - 敵対的マルチテナントのセキュリティ境界では**ありません**。混在した信頼レベルや - 敵対的ユーザーによる運用が必要な場合は、信頼境界を分割してください（別々の Gateway + - 認証情報、理想的には別々の OS ユーザーまたはホスト）。 + **パーソナルアシスタントの信頼モデル。** このガイダンスは、Gatewayごとに1つの信頼済み + オペレーター境界があることを前提としています（単一ユーザーのパーソナルアシスタントモデル）。 + OpenClawは、1つのエージェントまたはGatewayを共有する複数の + 敵対的ユーザーに対する、敵対的なマルチテナントセキュリティ境界では**ありません**。混在した信頼または + 敵対的ユーザーの運用が必要な場合は、信頼境界を分割してください（別々のGateway + + 認証情報、理想的には別々のOSユーザーまたはホスト）。 -## まずスコープ: パーソナルアシスタントのセキュリティモデル +## まずスコープを定める: パーソナルアシスタントのセキュリティモデル -OpenClaw のセキュリティガイダンスは、**パーソナルアシスタント**としてのデプロイを前提としています。つまり、信頼されたオペレーター境界が 1 つあり、エージェントは複数存在し得る構成です。 +OpenClawのセキュリティガイダンスは、**パーソナルアシスタント**としてのデプロイを前提としています。つまり、1つの信頼済みオペレーター境界と、場合によっては複数のエージェントです。 -- サポートされるセキュリティ態勢: Gateway ごとに 1 つのユーザー/信頼境界（境界ごとに OS ユーザー/ホスト/VPS を 1 つにすることを推奨）。 -- サポートされないセキュリティ境界: 互いに信頼できない、または敵対的なユーザーが使用する共有 Gateway/エージェント。 -- 敵対的ユーザーの分離が必要な場合は、信頼境界ごとに分割してください（別々の Gateway + 認証情報、理想的には別々の OS ユーザー/ホスト）。 -- 信頼できない複数のユーザーが 1 つのツール有効エージェントにメッセージを送れる場合、それらのユーザーはそのエージェントの同じ委任済みツール権限を共有しているものとして扱ってください。 +- サポートされるセキュリティ姿勢: Gatewayごとに1つのユーザー/信頼境界（境界ごとに1つのOSユーザー/ホスト/VPSを推奨）。 +- サポートされるセキュリティ境界ではないもの: 相互に信頼されていない、または敵対的なユーザーが使用する1つの共有Gateway/エージェント。 +- 敵対的ユーザーの分離が必要な場合は、信頼境界ごとに分割します（別々のGateway + 認証情報、理想的には別々のOSユーザー/ホスト）。 +- 信頼されていない複数のユーザーが、ツール有効化済みの1つのエージェントにメッセージを送信できる場合、そのユーザーたちはそのエージェントに委任された同じツール権限を共有しているものとして扱います。 -このページでは、**そのモデル内での**堅牢化を説明します。1 つの共有 Gateway 上で敵対的マルチテナント分離を提供すると主張するものではありません。 +このページでは、**このモデルの範囲内**での堅牢化について説明します。1つの共有Gateway上で敵対的なマルチテナント分離を提供すると主張するものではありません。 ## クイックチェック: `openclaw security audit` 関連項目: [形式検証（セキュリティモデル）](/ja-JP/security/formal-verification) -これを定期的に実行してください（特に設定を変更した後やネットワーク面を公開した後）。 +これを定期的に実行してください（特に設定を変更した後、またはネットワークサーフェスを公開した後）。 ```bash openclaw security audit @@ -47,115 +47,113 @@ openclaw security audit --json `security audit --fix` は意図的に狭い範囲にとどまります。一般的な開いたグループ ポリシーを許可リストに切り替え、`logging.redactSensitive: "tools"` を復元し、 -状態/設定/インクルードファイルの権限を厳格化し、Windows 上で実行している場合は -POSIX `chmod` ではなく Windows ACL リセットを使用します。 +状態/設定/include-fileのパーミッションを強化し、Windows上で実行している場合は +POSIX `chmod` ではなくWindows ACLのリセットを使用します。 -一般的な落とし穴（Gateway 認証の露出、ブラウザー制御の露出、昇格された許可リスト、ファイルシステム権限、寛容な exec 承認、開いたチャネルでのツール露出）を検出します。 +これは一般的な落とし穴（Gateway認証の公開、ブラウザー制御の公開、昇格された許可リスト、ファイルシステムのパーミッション、寛容なexec承認、オープンチャンネルでのツール公開）を検出します。 -OpenClaw は製品であると同時に実験でもあります。フロンティアモデルの挙動を、実際のメッセージング面と実際のツールに接続します。**「完全に安全な」セットアップは存在しません。** 目標は、次の点を意識的に決めることです。 +OpenClawは製品であると同時に実験でもあります。フロンティアモデルの挙動を、実際のメッセージングサーフェスと実際のツールに接続します。**「完全に安全」な設定はありません。** 目標は、次の点を意図的に決めることです。 -- 誰がボットに話しかけられるか +- 誰がボットと会話できるか - ボットがどこで動作を許可されるか - ボットが何に触れられるか -まずは機能する最小限のアクセスから始め、自信がつくにつれて広げてください。 +まずは動作する最小限のアクセスから始め、確信が持てるようになったら範囲を広げます。 ### デプロイとホストの信頼 -OpenClaw は、ホストと設定境界が信頼されていることを前提としています。 +OpenClawは、ホストと設定境界が信頼されていることを前提としています。 -- 誰かが Gateway ホストの状態/設定（`openclaw.json` を含む `~/.openclaw`）を変更できる場合、その人は信頼されたオペレーターとして扱ってください。 -- 互いに信頼できない、または敵対的な複数のオペレーターのために 1 つの Gateway を実行する構成は、**推奨されるセットアップではありません**。 -- 信頼レベルが混在するチームでは、別々の Gateway（または少なくとも別々の OS ユーザー/ホスト）で信頼境界を分割してください。 -- 推奨されるデフォルト: マシン/ホスト（または VPS）ごとに 1 ユーザー、そのユーザーに 1 つの Gateway、その Gateway 内に 1 つ以上のエージェント。 -- 1 つの Gateway インスタンス内では、認証済みオペレーターアクセスは信頼された制御プレーンのロールであり、ユーザーごとのテナントロールではありません。 -- セッション識別子（`sessionKey`、セッション ID、ラベル）はルーティングセレクターであり、認可トークンではありません。 -- 複数の人が 1 つのツール有効エージェントにメッセージを送れる場合、その各人が同じ権限セットを誘導できます。ユーザーごとのセッション/メモリ分離はプライバシーには役立ちますが、共有エージェントをユーザーごとのホスト認可に変えるものではありません。 +- 誰かがGatewayホストの状態/設定（`openclaw.json` を含む `~/.openclaw`）を変更できる場合、その人を信頼済みオペレーターとして扱います。 +- 相互に信頼されていない/敵対的な複数のオペレーターに1つのGatewayを実行することは、**推奨される設定ではありません**。 +- 信頼が混在するチームでは、別々のGateway（または最低限、別々のOSユーザー/ホスト）で信頼境界を分割します。 +- 推奨されるデフォルト: マシン/ホスト（またはVPS）ごとに1ユーザー、そのユーザー用に1つのGateway、そのGateway内に1つ以上のエージェント。 +- 1つのGatewayインスタンス内では、認証済みオペレーターアクセスは信頼済みのコントロールプレーンロールであり、ユーザーごとのテナントロールではありません。 +- セッション識別子（`sessionKey`、セッションID、ラベル）はルーティングセレクターであり、認可トークンではありません。 +- 複数の人が1つのツール有効化済みエージェントにメッセージを送信できる場合、それぞれが同じ権限セットを操作できます。ユーザーごとのセッション/メモリ分離はプライバシーに役立ちますが、共有エージェントをユーザーごとのホスト認可に変えるものではありません。 -### 共有 Slack ワークスペース: 実際のリスク +### 共有Slackワークスペース: 実際のリスク -「Slack の全員がボットにメッセージを送れる」場合、中核的なリスクは委任されたツール権限です。 +「Slackの全員がボットにメッセージを送信できる」場合、中核となるリスクは委任されたツール権限です。 -- 許可された送信者なら誰でも、エージェントのポリシー内でツール呼び出し（`exec`、ブラウザー、ネットワーク/ファイルツール）を誘導できます。 -- ある送信者からのプロンプト/コンテンツインジェクションにより、共有状態、デバイス、出力に影響するアクションが起きる可能性があります。 -- 1 つの共有エージェントが機密の認証情報/ファイルを持っている場合、許可された送信者なら誰でもツール使用を通じて持ち出しを誘導できる可能性があります。 +- 許可された任意の送信者が、エージェントのポリシー内でツール呼び出し（`exec`、ブラウザー、ネットワーク/ファイルツール）を誘発できます。 +- ある送信者からのプロンプト/コンテンツインジェクションにより、共有状態、デバイス、または出力に影響するアクションが発生する可能性があります。 +- 1つの共有エージェントが機密性の高い認証情報/ファイルを持っている場合、許可された任意の送信者がツール使用を通じて流出を引き起こせる可能性があります。 -チームワークフローには、最小限のツールを備えた別々のエージェント/Gateway を使用してください。個人データを扱うエージェントは非公開に保ってください。 +チームワークフローには、最小限のツールを備えた別々のエージェント/Gatewayを使用します。個人データを扱うエージェントは非公開にしてください。 ### 会社共有エージェント: 許容されるパターン -そのエージェントを使用する全員が同じ信頼境界内（たとえば 1 つの会社チーム）にいて、エージェントが厳密に業務スコープに限定されている場合、これは許容されます。 +そのエージェントを使用する全員が同じ信頼境界内（たとえば1つの会社チーム）にあり、エージェントが厳密に業務スコープに限定されている場合、これは許容されます。 -- 専用のマシン/VM/コンテナで実行する。 -- そのランタイム用に専用の OS ユーザー + 専用のブラウザー/プロファイル/アカウントを使用する。 -- そのランタイムに個人の Apple/Google アカウントや個人のパスワードマネージャー/ブラウザープロファイルでサインインしない。 +- 専用のマシン/VM/コンテナー上で実行します。 +- そのランタイムには専用のOSユーザー + 専用ブラウザー/プロファイル/アカウントを使用します。 +- そのランタイムを個人のApple/Googleアカウントや個人のパスワードマネージャー/ブラウザープロファイルにサインインさせないでください。 -同じランタイム上で個人 ID と会社 ID を混在させると、分離が崩れ、個人データの露出リスクが増加します。 +同じランタイム上で個人IDと会社IDを混在させると、分離が崩れ、個人データの露出リスクが高まります。 -## Gateway と Node の信頼概念 +## Gatewayとノードの信頼概念 -Gateway と Node は、役割が異なる 1 つのオペレーター信頼ドメインとして扱ってください。 +Gatewayとノードは、異なるロールを持つ1つのオペレーター信頼ドメインとして扱います。 -- **Gateway** は制御プレーンおよびポリシー面（`gateway.auth`、ツールポリシー、ルーティング）です。 -- **Node** は、その Gateway にペアリングされたリモート実行面（コマンド、デバイス操作、ホストローカル機能）です。 -- Gateway に認証された呼び出し元は、Gateway スコープで信頼されます。ペアリング後、Node のアクションはその Node 上の信頼されたオペレーターアクションになります。 -- 共有 Gateway のトークン/パスワードで認証された直接 loopback バックエンドクライアントは、ユーザー - デバイス ID を提示せずに内部制御プレーン RPC を実行できます。これはリモートまたはブラウザーのペアリングバイパスではありません。ネットワーク - クライアント、Node クライアント、デバイストークンクライアント、明示的なデバイス ID は、 +- **Gateway** はコントロールプレーンとポリシーサーフェスです（`gateway.auth`、ツールポリシー、ルーティング）。 +- **Node** は、そのGatewayにペアリングされたリモート実行サーフェスです（コマンド、デバイスアクション、ホストローカル機能）。 +- Gatewayに認証された呼び出し元は、Gatewayスコープで信頼されます。ペアリング後、ノードのアクションはそのノード上の信頼済みオペレーターアクションになります。 +- 共有Gatewayトークン/パスワードで認証された直接のループバックバックエンドクライアントは、 + ユーザーデバイスIDを提示せずに内部コントロールプレーンRPCを実行できます。 + これはリモートまたはブラウザーのペアリング回避ではありません。ネットワーク + クライアント、ノードクライアント、デバイストークンクライアント、明示的なデバイスIDは 引き続きペアリングとスコープアップグレードの強制を通過します。 - `sessionKey` はルーティング/コンテキスト選択であり、ユーザーごとの認証ではありません。 -- Exec 承認（許可リスト + 確認）はオペレーター意図のガードレールであり、敵対的マルチテナント分離ではありません。 -- OpenClaw の信頼された単一オペレーターセットアップにおける製品デフォルトでは、`gateway`/`node` でのホスト exec は承認プロンプトなしで許可されます（締めない限り `security="full"`、`ask="off"`）。そのデフォルトは意図的な UX であり、それ自体が脆弱性ではありません。 -- Exec 承認は、正確なリクエストコンテキストとベストエフォートの直接ローカルファイルオペランドに結び付きます。すべてのランタイム/インタープリターローダーパスを意味論的にモデル化するものではありません。強い境界にはサンドボックス化とホスト分離を使用してください。 +- Exec承認（許可リスト + 確認）はオペレーターの意図に対するガードレールであり、敵対的なマルチテナント分離ではありません。 +- 信頼済み単一オペレーター設定に対するOpenClawの製品デフォルトでは、`gateway`/`node` 上のホストexecは承認プロンプトなしで許可されます（強化しない限り `security="full"`、`ask="off"`）。このデフォルトは意図的なUXであり、それ自体は脆弱性ではありません。 +- Exec承認は、正確なリクエストコンテキストとベストエフォートの直接ローカルファイルオペランドに紐づきます。すべてのランタイム/インタープリターローダーパスを意味論的にモデル化するものではありません。強い境界にはサンドボックス化とホスト分離を使用してください。 -敵対的ユーザーの分離が必要な場合は、OS ユーザー/ホストごとに信頼境界を分割し、別々の Gateway を実行してください。 +敵対的ユーザーの分離が必要な場合は、OSユーザー/ホストごとに信頼境界を分割し、別々のGatewayを実行してください。 -## 信頼境界マトリクス +## 信頼境界マトリックス -リスクをトリアージするときのクイックモデルとして使用してください。 +リスクをトリアージするときの簡易モデルとして使用してください。 -| 境界または制御 | 意味 | よくある誤読 | -| --------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- | -| `gateway.auth`（トークン/パスワード/信頼プロキシ/デバイス認証） | Gateway API への呼び出し元を認証する | 「安全であるには全フレームでメッセージごとの署名が必要」 | -| `sessionKey` | コンテキスト/セッション選択のルーティングキー | 「セッションキーはユーザー認証境界である」 | -| プロンプト/コンテンツのガードレール | モデル悪用リスクを減らす | 「プロンプトインジェクションだけで認証バイパスが証明される」 | -| `canvas.eval` / ブラウザー evaluate | 有効化時の意図されたオペレーター機能 | 「どの JS eval プリミティブも、この信頼モデルでは自動的に脆弱性である」 | -| ローカル TUI `!` シェル | オペレーターが明示的に起動するローカル実行 | 「ローカルシェルの便利コマンドはリモートインジェクションである」 | -| Node ペアリングと Node コマンド | ペアリング済みデバイス上のオペレーターレベルのリモート実行 | 「リモートデバイス制御はデフォルトで信頼できないユーザーアクセスとして扱うべき」 | -| `gateway.nodes.pairing.autoApproveCidrs` | オプトインの信頼ネットワーク Node 登録ポリシー | 「デフォルトで無効な許可リストは自動ペアリング脆弱性である」 | +| 境界または制御 | 意味 | よくある誤解 | +| --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | +| `gateway.auth`（トークン/パスワード/信頼済みプロキシ/デバイス認証） | Gateway APIへの呼び出し元を認証する | 「安全にするには、すべてのフレームでメッセージごとの署名が必要」 | +| `sessionKey` | コンテキスト/セッション選択用のルーティングキー | 「セッションキーはユーザー認証境界である」 | +| プロンプト/コンテンツガードレール | モデル悪用リスクを低減する | 「プロンプトインジェクションだけで認証回避が証明される」 | +| `canvas.eval` / ブラウザー評価 | 有効化されている場合の意図的なオペレーター機能 | 「この信頼モデルでは、任意のJS evalプリミティブは自動的に脆弱性である」 | +| ローカルTUI `!` シェル | 明示的にオペレーターがトリガーするローカル実行 | 「ローカルシェルの便利コマンドはリモートインジェクションである」 | +| ノードペアリングとノードコマンド | ペアリング済みデバイス上でのオペレーターレベルのリモート実行 | 「リモートデバイス制御はデフォルトで信頼されていないユーザーアクセスとして扱うべき」 | +| `gateway.nodes.pairing.autoApproveCidrs` | オプトインの信頼済みネットワークノード登録ポリシー | 「デフォルトで無効な許可リストは自動的なペアリング脆弱性である」 | -## 設計上の非脆弱性 +## 設計上、脆弱性ではないもの - + -これらのパターンは頻繁に報告されますが、実際の境界バイパスが示されない限り、 +これらのパターンは頻繁に報告されますが、実際の境界回避が示されない限り、 通常は対応不要としてクローズされます。 -- ポリシー、認証、またはサンドボックスのバイパスを伴わない、プロンプトインジェクションのみの連鎖。 -- 1 つの共有ホストまたは - 設定上で敵対的マルチテナント運用を前提とする主張。 -- 共有 Gateway セットアップにおいて、通常のオペレーターの読み取りパスアクセス（たとえば - `sessions.list` / `sessions.preview` / `chat.history`）を IDOR と分類する主張。 -- localhost のみのデプロイに関する指摘（たとえば loopback のみの - Gateway における HSTS）。 -- このリポジトリに存在しないインバウンドパスに対する Discord インバウンド Webhook 署名の指摘。 -- `system.run` の隠れた第 2 のコマンドごと承認レイヤーとして Node ペアリングメタデータを扱う報告。 - 実際の実行境界は引き続き Gateway のグローバル Node コマンドポリシーと、 - Node 自身の exec +- ポリシー、認証、またはサンドボックス回避を伴わない、プロンプトインジェクションのみのチェーン。 +- 1つの共有ホストまたは設定で敵対的なマルチテナント運用を前提とする主張。 +- 通常のオペレーター読み取りパスアクセス（たとえば + `sessions.list` / `sessions.preview` / `chat.history`）を、共有Gateway設定でのIDORとして分類する主張。 +- localhostのみのデプロイに関する指摘（たとえばループバックのみの + Gateway上のHSTS）。 +- このリポジトリに存在しないインバウンドパスに対するDiscordインバウンドWebhook署名の指摘。 +- `system.run` に対する隠れた2段目のコマンドごとの承認レイヤーとしてノードペアリングメタデータを扱う報告。実際の実行境界は引き続き + Gatewayのグローバルノードコマンドポリシーとノード自身のexec 承認です。 -- 設定済みの `gateway.nodes.pairing.autoApproveCidrs` をそれ自体で - 脆弱性として扱う報告。この設定はデフォルトで無効であり、明示的な - CIDR/IP エントリを必要とし、要求スコープなしの初回 `role: node` ペアリングにのみ適用されます。また、オペレーター/ブラウザー/Control UI、 +- 設定済みの `gateway.nodes.pairing.autoApproveCidrs` 自体を脆弱性として扱う報告。この設定はデフォルトで無効であり、 + 明示的なCIDR/IPエントリーを必要とし、要求されたスコープがない + 初回の `role: node` ペアリングにのみ適用され、オペレーター/ブラウザー/Control UI、 WebChat、ロールアップグレード、スコープアップグレード、メタデータ変更、公開鍵変更、 - または loopback 信頼プロキシ認証が明示的に有効化されていない限り、同一ホストの loopback 信頼プロキシヘッダーパスを自動承認しません。 -- `sessionKey` を認証 - トークンとして扱う「ユーザーごとの認可不足」の指摘。 + または同一ホストのループバック信頼済みプロキシヘッダーパスは、ループバック信頼済みプロキシ認証が明示的に有効化されていない限り、自動承認しません。 +- `sessionKey` を認証トークンとして扱う「ユーザーごとの認可不足」の指摘。 -## 60 秒で堅牢なベースライン +## 60秒でできる堅牢化ベースライン -まずこのベースラインを使用し、その後、信頼されたエージェントごとに必要なツールを選択的に再有効化してください。 +まずこのベースラインを使用し、その後で信頼済みエージェントごとにツールを選択的に再有効化します。 ```json5 { @@ -180,122 +178,119 @@ Gateway と Node は、役割が異なる 1 つのオペレーター信頼ドメ } ``` -これにより、Gateway はローカルのみになり、DM は分離され、制御プレーン/ランタイムツールはデフォルトで無効になります。 +これにより、Gatewayはローカル専用のままになり、DMが分離され、コントロールプレーン/ランタイムツールがデフォルトで無効になります。 ## 共有受信箱のクイックルール -複数の人がボットに DM できる場合: +複数の人がボットにDMできる場合: -- `session.dmScope: "per-channel-peer"`（またはマルチアカウントチャネルでは `"per-account-channel-peer"`）を設定する。 -- `dmPolicy: "pairing"` または厳格な許可リストを維持する。 -- 共有 DM と広範なツールアクセスを決して組み合わせない。 -- これは協調的な共有受信箱を堅牢化しますが、ユーザーがホスト/設定への書き込みアクセスを共有する場合の敵対的な共同テナント分離としては設計されていません。 +- `session.dmScope: "per-channel-peer"`（複数アカウントのチャンネルでは `"per-account-channel-peer"`）を設定します。 +- `dmPolicy: "pairing"` または厳格な許可リストを維持します。 +- 共有DMと広範なツールアクセスを組み合わせないでください。 +- これは協調的/共有受信箱を堅牢化しますが、ユーザーがホスト/設定への書き込みアクセスを共有している場合の敵対的な共同テナント分離としては設計されていません。 ## コンテキスト可視性モデル -OpenClaw は 2 つの概念を分離します。 +OpenClawは2つの概念を分離します。 - **トリガー認可**: 誰がエージェントをトリガーできるか（`dmPolicy`、`groupPolicy`、許可リスト、メンションゲート）。 - **コンテキスト可視性**: モデル入力に注入される補足コンテキスト（返信本文、引用テキスト、スレッド履歴、転送メタデータ）。 -許可リストはトリガーとコマンド認可を制御します。`contextVisibility` 設定は、補足コンテキスト（引用返信、スレッドルート、取得された履歴）のフィルタリング方法を制御します。 +許可リストは、トリガーとコマンド認可を制御します。`contextVisibility` 設定は、補足コンテキスト（引用返信、スレッドルート、取得された履歴）のフィルタリング方法を制御します。 -- `contextVisibility: "all"`（デフォルト）は、受信した補足コンテキストをそのまま保持します。 -- `contextVisibility: "allowlist"` は、アクティブな許可リストチェックで許可された送信者に補足コンテキストをフィルタリングします。 -- `contextVisibility: "allowlist_quote"` は `allowlist` と同様に動作しますが、明示的に引用された返信を 1 つ保持します。 +- `contextVisibility: "all"`（デフォルト）は、補足コンテキストを受信時のまま保持します。 +- `contextVisibility: "allowlist"` は、有効な許可リストチェックで許可された送信者に補足コンテキストをフィルタリングします。 +- `contextVisibility: "allowlist_quote"` は `allowlist` のように動作しますが、明示的に引用された返信を1つ保持します。 -チャネルごと、またはルーム/会話ごとに `contextVisibility` を設定してください。設定の詳細は [グループチャット](/ja-JP/channels/groups#context-visibility-and-allowlists) を参照してください。 +チャンネルごと、またはルーム/会話ごとに `contextVisibility` を設定します。設定の詳細は [グループチャット](/ja-JP/channels/groups#context-visibility-and-allowlists) を参照してください。 -アドバイザリのトリアージガイダンス: +アドバイザリートリアージのガイダンス: -- 「モデルが非許可リスト送信者からの引用テキストまたは履歴テキストを見られる」ことだけを示す主張は、`contextVisibility` で対処できる強化所見であり、それ自体では認証またはサンドボックス境界のバイパスではありません。 -- セキュリティへの影響があると見なすには、レポートには引き続き、信頼境界のバイパス（認証、ポリシー、サンドボックス、承認、または別の文書化された境界）の実証が必要です。 +- 「モデルは非許可リスト送信者からの引用テキストまたは履歴テキストを参照できる」ことだけを示す主張は、`contextVisibility` で対処できる強化上の所見であり、それ自体では認証やサンドボックス境界のバイパスではありません。 +- セキュリティ影響があるとみなされるには、レポートでは引き続き、信頼境界のバイパス（認証、ポリシー、サンドボックス、承認、または別の文書化された境界）が実証されている必要があります。 -## 監査で確認する内容（概要） +## 監査が確認する内容（概要） -- **インバウンドアクセス**（DM ポリシー、グループポリシー、許可リスト）: 見知らぬ人がボットを起動できるか。 -- **ツールの影響範囲**（昇格ツール + オープンなルーム）: プロンプトインジェクションがシェル/ファイル/ネットワーク操作につながる可能性があるか。 -- **実行承認のずれ**（`security=full`、`autoAllowSkills`、`strictInlineEval` のないインタープリター許可リスト）: ホスト実行のガードレールは、まだ想定どおりに機能しているか。 - - `security="full"` は広範な姿勢警告であり、バグの証拠ではありません。信頼済みの個人アシスタント設定向けに選ばれているデフォルトです。脅威モデルで承認または許可リストのガードレールが必要な場合にのみ、厳格化してください。 -- **ネットワーク公開**（Gateway のバインド/認証、Tailscale Serve/Funnel、脆弱または短い認証トークン）。 -- **ブラウザー制御の公開**（リモートノード、リレーポート、リモート CDP エンドポイント）。 +- **インバウンドアクセス**（DM ポリシー、グループポリシー、許可リスト）: 見知らぬ相手がボットを起動できるか？ +- **ツールの影響範囲**（昇格ツール + オープンなルーム）: プロンプトインジェクションがシェル/ファイル/ネットワーク操作につながり得るか？ +- **exec 承認のドリフト**（`security=full`、`autoAllowSkills`、`strictInlineEval` なしのインタープリター許可リスト）: ホスト exec のガードレールは、まだ想定どおりに機能しているか？ + - `security="full"` は広範な姿勢の警告であり、バグの証明ではありません。これは信頼済みの個人アシスタント構成向けに選ばれたデフォルトです。承認や許可リストのガードレールが脅威モデル上必要な場合にのみ厳格化してください。 +- **ネットワーク露出**（Gateway の bind/auth、Tailscale Serve/Funnel、弱い/短い認証トークン）。 +- **ブラウザー制御の露出**（リモート Node、リレーポート、リモート CDP エンドポイント）。 - **ローカルディスクの衛生状態**（権限、シンボリックリンク、設定の include、「同期フォルダー」パス）。 - **Plugin**（Plugin が明示的な許可リストなしで読み込まれる）。 -- **ポリシーのずれ/誤設定**（サンドボックス Docker 設定は構成されているがサンドボックスモードがオフ、`gateway.nodes.denyCommands` パターンが無効。マッチングは正確なコマンド名のみ（例: `system.run`）で、シェルテキストは検査しないため。危険な `gateway.nodes.allowCommands` エントリ。グローバルな `tools.profile="minimal"` がエージェントごとのプロファイルで上書きされている。Plugin 所有ツールが許容的なツールポリシーの下で到達可能）。 -- **ランタイム期待値のずれ**（たとえば、`tools.exec.host` のデフォルトが現在 `auto` であるにもかかわらず、暗黙の実行がまだ `sandbox` を意味すると仮定する、またはサンドボックスモードがオフの状態で `tools.exec.host="sandbox"` を明示的に設定する）。 -- **モデルの衛生状態**（設定済みモデルがレガシーに見える場合に警告する。ハードブロックではない）。 +- **ポリシードリフト/設定ミス**（サンドボックス docker 設定が構成されているのにサンドボックスモードがオフ、`gateway.nodes.denyCommands` パターンが無効になっている。これは照合が正確なコマンド名のみ（例: `system.run`）で、シェルテキストを検査しないため、危険な `gateway.nodes.allowCommands` エントリ、グローバルな `tools.profile="minimal"` がエージェント単位のプロファイルで上書きされている、許可的なツールポリシー下で Plugin 所有ツールに到達可能）。 +- **ランタイム期待値のドリフト**（たとえば、`tools.exec.host` が現在はデフォルトで `auto` になっているのに暗黙的 exec がまだ `sandbox` を意味すると想定する、またはサンドボックスモードがオフなのに `tools.exec.host="sandbox"` を明示的に設定する）。 +- **モデルの衛生状態**（構成されたモデルがレガシーに見える場合に警告する。厳格なブロックではない）。 -`--deep` を実行すると、OpenClaw はベストエフォートのライブ Gateway プローブも試行します。 +`--deep` を実行すると、OpenClaw はベストエフォートでライブ Gateway プローブも試行します。 ## 認証情報ストレージマップ -アクセスを監査する場合や、バックアップ対象を決める場合に使用してください。 +アクセス監査やバックアップ対象の判断に使用してください。 - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Telegram ボットトークン**: config/env または `channels.telegram.tokenFile`（通常ファイルのみ。シンボリックリンクは拒否） +- **Telegram ボットトークン**: config/env または `channels.telegram.tokenFile`（通常ファイルのみ。シンボリックリンクは拒否されます） - **Discord ボットトークン**: config/env または SecretRef（env/file/exec プロバイダー） - **Slack トークン**: config/env（`channels.slack.*`） - **ペアリング許可リスト**: - `~/.openclaw/credentials/-allowFrom.json`（デフォルトアカウント） - `~/.openclaw/credentials/--allowFrom.json`（非デフォルトアカウント） - **モデル認証プロファイル**: `~/.openclaw/agents//agent/auth-profiles.json` -- **ファイルベースのシークレットペイロード（任意）**: `~/.openclaw/secrets.json` +- **Codex ランタイム状態**: `~/.openclaw/agents//agent/codex-home/` +- **ファイル backed の secrets ペイロード（任意）**: `~/.openclaw/secrets.json` - **レガシー OAuth インポート**: `~/.openclaw/credentials/oauth.json` ## セキュリティ監査チェックリスト -監査で所見が出力された場合は、次の優先順位として扱ってください。 +監査が所見を出力したら、次の優先順位として扱ってください。 -1. **何らかの「オープン」+ ツール有効**: まず DM/グループをロックダウンし（ペアリング/許可リスト）、次にツールポリシー/サンドボックス化を厳格化します。 -2. **パブリックネットワーク公開**（LAN バインド、Funnel、認証なし）: 直ちに修正します。 -3. **ブラウザー制御のリモート公開**: オペレーターアクセスと同様に扱います（tailnet のみ、ノードを意図的にペアリング、公開を避ける）。 -4. **権限**: state/config/credentials/auth がグループ/全員に読み取り可能でないことを確認します。 +1. **「オープン」なもの + ツール有効**: まず DM/グループをロックダウン（ペアリング/許可リスト）し、次にツールポリシー/サンドボックス化を厳格化します。 +2. **パブリックネットワーク露出**（LAN bind、Funnel、認証欠如）: 直ちに修正します。 +3. **ブラウザー制御のリモート露出**: オペレーターアクセスと同様に扱います（tailnet のみ、Node を意図的にペアリングし、公開露出を避ける）。 +4. **権限**: state/config/credentials/auth がグループ/ワールド読み取り可能でないことを確認します。 5. **Plugin**: 明示的に信頼するものだけを読み込みます。 -6. **モデル選択**: ツールを持つボットには、最新で命令強化されたモデルを優先します。 +6. **モデル選択**: ツール付きのボットでは、モダンで命令に強化されたモデルを優先します。 ## セキュリティ監査用語集 -各監査所見は、構造化された `checkId`（例: -`gateway.bind_no_auth` または `tools.exec.security_full_configured`）でキー付けされます。一般的な -重大度クラスは次のとおりです。 +各監査所見には、構造化された `checkId`（例: +`gateway.bind_no_auth` または `tools.exec.security_full_configured`）が付与されます。一般的な +重大度クラス: -- `fs.*` — state、config、credentials、auth profiles のファイルシステム権限。 -- `gateway.*` — バインドモード、認証、Tailscale、Control UI、trusted-proxy 設定。 -- `hooks.*`、`browser.*`、`sandbox.*`、`tools.exec.*` — サーフェスごとの強化。 -- `plugins.*`、`skills.*` — Plugin/Skills のサプライチェーンとスキャン所見。 -- `security.exposure.*` — アクセスポリシーとツールの影響範囲が交わる横断的チェック。 +- `fs.*` — state、config、credentials、auth プロファイルに対するファイルシステム権限。 +- `gateway.*` — bind モード、認証、Tailscale、Control UI、trusted-proxy 設定。 +- `hooks.*`、`browser.*`、`sandbox.*`、`tools.exec.*` — サーフェス単位の強化。 +- `plugins.*`、`skills.*` — Plugin/skill のサプライチェーンとスキャン所見。 +- `security.exposure.*` — アクセスポリシーとツールの影響範囲が交差する横断的チェック。 重大度レベル、修正キー、自動修正サポートを含む完全なカタログは [セキュリティ監査チェック](/ja-JP/gateway/security/audit-checks) を参照してください。 ## HTTP 経由の Control UI -Control UI は、デバイス ID を生成するために **セキュアコンテキスト**（HTTPS または localhost）を必要とします。`gateway.controlUi.allowInsecureAuth` はローカル互換性トグルです。 +Control UI がデバイス ID を生成するには **セキュアコンテキスト**（HTTPS または localhost）が必要です。`gateway.controlUi.allowInsecureAuth` はローカル互換性トグルです。 -- localhost では、ページが非セキュア HTTP 経由で読み込まれた場合に、デバイス ID なしで Control UI 認証を許可します。 -- ペアリングチェックはバイパスしません。 -- リモート（非 localhost）のデバイス ID 要件は緩和しません。 +- localhost では、ページが非セキュア HTTP 経由で読み込まれた場合に、デバイス ID なしの Control UI 認証を許可します。 +- ペアリングチェックをバイパスしません。 +- リモート（非 localhost）のデバイス ID 要件を緩和しません。 -HTTPS（Tailscale Serve）を優先するか、`127.0.0.1` で UI を開いてください。 +HTTPS（Tailscale Serve）を優先するか、UI を `127.0.0.1` で開いてください。 -緊急時のみに限り、`gateway.controlUi.dangerouslyDisableDeviceAuth` -はデバイス ID チェックを完全に無効にします。これは深刻なセキュリティ低下です。 -積極的にデバッグしていて、すぐに元に戻せる場合を除き、オフのままにしてください。 +緊急時専用のシナリオでは、`gateway.controlUi.dangerouslyDisableDeviceAuth` +がデバイス ID チェックを完全に無効化します。これは重大なセキュリティ低下です。 +積極的にデバッグ中で、すぐに戻せる場合を除き、オフのままにしてください。 -これらの危険なフラグとは別に、`gateway.auth.mode: "trusted-proxy"` が成功すると、 -デバイス ID なしで **operator** Control UI セッションを許可できます。これは -意図された認証モードの動作であり、`allowInsecureAuth` のショートカットではありません。また、 -node-role Control UI セッションには引き続き拡張されません。 +これらの危険なフラグとは別に、`gateway.auth.mode: "trusted-proxy"` が成功すると、デバイス ID なしで **operator** Control UI セッションを受け入れられます。これは意図された認証モードの動作であり、`allowInsecureAuth` の近道ではありません。また、Node ロールの Control UI セッションには依然として拡張されません。 -`openclaw security audit` は、この設定が有効な場合に警告します。 +この設定が有効な場合、`openclaw security audit` は警告します。 -## 安全でないまたは危険なフラグの要約 +## 安全でない、または危険なフラグの概要 -`openclaw security audit` は、既知の安全でない/危険なデバッグスイッチが有効な場合に -`config.insecure_or_dangerous_flags` を出します。本番環境ではこれらを未設定のままにしてください。 +既知の安全でない/危険なデバッグスイッチが有効な場合、`openclaw security audit` は `config.insecure_or_dangerous_flags` を発生させます。本番環境ではこれらを未設定のままにしてください。 - + - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` @@ -306,15 +301,15 @@ node-role Control UI セッションには引き続き拡張されません。 - + Control UI とブラウザー: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - チャンネル名マッチング（バンドル済みおよび Plugin チャンネル。該当する場合は - `accounts.` ごとにも利用可能）: + チャンネル名照合（同梱チャンネルと Plugin チャンネル。該当する場合は + `accounts.` 単位でも利用可能）: - `channels.discord.dangerouslyAllowNameMatching` - `channels.slack.dangerouslyAllowNameMatching` @@ -326,11 +321,11 @@ node-role Control UI セッションには引き続き拡張されません。 - `channels.irc.dangerouslyAllowNameMatching`（Plugin チャンネル） - `channels.mattermost.dangerouslyAllowNameMatching`（Plugin チャンネル） - ネットワーク公開: + ネットワーク露出: - - `channels.telegram.network.dangerouslyAllowPrivateNetwork`（アカウントごとにも設定可能） + - `channels.telegram.network.dangerouslyAllowPrivateNetwork`（アカウント単位にも対応） - サンドボックス Docker（デフォルト + エージェントごと）: + Sandbox Docker（デフォルト + エージェント単位）: - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` - `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` @@ -341,16 +336,16 @@ node-role Control UI セッションには引き続き拡張されません。 ## リバースプロキシ設定 -Gateway をリバースプロキシ（nginx、Caddy、Traefik など）の背後で実行する場合は、 -転送されたクライアント IP を適切に扱うために `gateway.trustedProxies` を設定してください。 +Gateway をリバースプロキシ（nginx、Caddy、Traefik など）の背後で実行する場合は、適切な転送元クライアント IP 処理のために +`gateway.trustedProxies` を構成してください。 -Gateway が `trustedProxies` に **含まれていない** アドレスからのプロキシヘッダーを検出した場合、その接続をローカルクライアントとして扱いません。Gateway 認証が無効な場合、それらの接続は拒否されます。これにより、プロキシされた接続が localhost から来たように見えて自動的に信頼される認証バイパスを防ぎます。 +Gateway が `trustedProxies` に **含まれていない** アドレスからのプロキシヘッダーを検出した場合、その接続をローカルクライアントとして扱いません。Gateway 認証が無効な場合、それらの接続は拒否されます。これにより、プロキシ経由の接続が localhost から来たように見えて自動的に信頼される認証バイパスを防ぎます。 -`gateway.trustedProxies` は `gateway.auth.mode: "trusted-proxy"` にも渡されますが、その認証モードはより厳格です。 +`gateway.trustedProxies` は `gateway.auth.mode: "trusted-proxy"` にも使われますが、この認証モードはより厳格です。 -- trusted-proxy 認証は、デフォルトで **ループバック送信元プロキシに対してフェイルクローズ** します -- 同一ホストのループバックリバースプロキシは、ローカルクライアント検出と転送 IP 処理に `gateway.trustedProxies` を使用できます -- 同一ホストのループバックリバースプロキシが `gateway.auth.mode: "trusted-proxy"` を満たせるのは、`gateway.auth.trustedProxy.allowLoopback = true` の場合のみです。それ以外の場合はトークン/パスワード認証を使用してください +- trusted-proxy 認証は **デフォルトで loopback 送信元プロキシに対して fail closed します** +- 同一ホストの loopback リバースプロキシは、ローカルクライアント検出と転送 IP 処理に `gateway.trustedProxies` を使用できます +- 同一ホストの loopback リバースプロキシは、`gateway.auth.trustedProxy.allowLoopback = true` の場合にのみ `gateway.auth.mode: "trusted-proxy"` を満たせます。それ以外の場合はトークン/パスワード認証を使用してください ```yaml gateway: @@ -364,73 +359,73 @@ gateway: password: ${OPENCLAW_GATEWAY_PASSWORD} ``` -`trustedProxies` が設定されている場合、Gateway は `X-Forwarded-For` を使用してクライアント IP を決定します。`gateway.allowRealIpFallback: true` が明示的に設定されていない限り、`X-Real-IP` はデフォルトで無視されます。 +`trustedProxies` が構成されている場合、Gateway はクライアント IP の判定に `X-Forwarded-For` を使用します。`gateway.allowRealIpFallback: true` が明示的に設定されていない限り、`X-Real-IP` はデフォルトで無視されます。 -信頼済みプロキシヘッダーは、ノードデバイスのペアリングを自動的に信頼済みにしません。 -`gateway.nodes.pairing.autoApproveCidrs` は、デフォルトで無効な別個の -オペレーターポリシーです。有効な場合でも、ループバック送信元の trusted-proxy ヘッダーパスは -ノード自動承認から除外されます。これは、ループバック trusted-proxy 認証が明示的に有効な場合を含め、 +信頼済みプロキシヘッダーによって、Node デバイスペアリングが自動的に信頼されるわけではありません。 +`gateway.nodes.pairing.autoApproveCidrs` は独立した、デフォルト無効の +オペレーターポリシーです。有効な場合でも、loopback 送信元の trusted-proxy ヘッダーパスは +Node 自動承認から除外されます。これは、loopback trusted-proxy 認証が明示的に有効な場合を含め、 ローカル呼び出し元がそれらのヘッダーを偽造できるためです。 -適切なリバースプロキシの動作（受信した転送ヘッダーを上書き）: +良いリバースプロキシ動作（受信した転送ヘッダーを上書き）: ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -不適切なリバースプロキシの動作（信頼できない転送ヘッダーを追加/保持）: +悪いリバースプロキシ動作（信頼できない転送ヘッダーを追加/保持）: ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## HSTS とオリジンに関する注意 +## HSTS とオリジンに関する注記 -- OpenClaw gateway はローカル/ループバック優先です。リバースプロキシで TLS を終端する場合は、そこでプロキシ向け HTTPS ドメインに HSTS を設定してください。 -- gateway 自体が HTTPS を終端する場合は、`gateway.http.securityHeaders.strictTransportSecurity` を設定して OpenClaw レスポンスから HSTS ヘッダーを出力できます。 +- OpenClaw gateway はローカル/loopback ファーストです。TLS をリバースプロキシで終端する場合は、そこでプロキシ向け HTTPS ドメインに HSTS を設定してください。 +- gateway 自体が HTTPS を終端する場合は、`gateway.http.securityHeaders.strictTransportSecurity` を設定して OpenClaw レスポンスから HSTS ヘッダーを発行できます。 - 詳細なデプロイガイダンスは [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth#tls-termination-and-hsts) にあります。 -- 非ループバックの Control UI デプロイでは、`gateway.controlUi.allowedOrigins` がデフォルトで必須です。 -- `gateway.controlUi.allowedOrigins: ["*"]` は、明示的な全許可ブラウザーオリジンポリシーであり、強化されたデフォルトではありません。厳密に管理されたローカルテスト以外では避けてください。 -- ループバック上のブラウザーオリジン認証失敗は、一般的なループバック例外が有効な場合でもレート制限されますが、ロックアウトキーは共有 localhost バケット 1 つではなく、正規化された `Origin` 値ごとにスコープされます。 -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` は Host ヘッダーのオリジンフォールバックモードを有効にします。危険な、オペレーターが選択したポリシーとして扱ってください。 -- DNS リバインディングとプロキシ Host ヘッダーの動作はデプロイ強化上の懸念として扱い、`trustedProxies` を厳密に保ち、gateway を直接インターネットに公開しないでください。 +- 非 loopback の Control UI デプロイでは、デフォルトで `gateway.controlUi.allowedOrigins` が必要です。 +- `gateway.controlUi.allowedOrigins: ["*"]` は明示的な全ブラウザーオリジン許可ポリシーであり、強化されたデフォルトではありません。厳密に管理されたローカルテスト以外では避けてください。 +- loopback 上のブラウザーオリジン認証失敗は、一般的な loopback 例外が有効な場合でもレート制限されますが、ロックアウトキーは共有 localhost バケット 1 つではなく、正規化された `Origin` 値ごとにスコープされます。 +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` は Host ヘッダーのオリジンフォールバックモードを有効にします。危険なオペレーター選択ポリシーとして扱ってください。 +- DNS rebinding と proxy-host ヘッダーの動作はデプロイ時の強化上の懸念として扱ってください。`trustedProxies` を厳格に保ち、gateway をパブリックインターネットへ直接公開することは避けてください。 -## ローカルセッションログはディスク上に存在します +## ローカルセッションログはディスク上に保存されます OpenClaw はセッショントランスクリプトを `~/.openclaw/agents//sessions/*.jsonl` 配下のディスクに保存します。 -これはセッション継続性と（任意で）セッションメモリインデックス作成に必要ですが、同時に -**ファイルシステムアクセスを持つ任意のプロセス/ユーザーがそれらのログを読める** ことも意味します。ディスクアクセスを信頼 -境界として扱い、`~/.openclaw` の権限をロックダウンしてください（下の監査セクションを参照）。エージェント間で +これはセッション継続性と（任意の）セッションメモリインデックス化に必要ですが、同時に +**ファイルシステムアクセス権を持つ任意のプロセス/ユーザーがそれらのログを読める** ことも意味します。ディスクアクセスを信頼 +境界として扱い、`~/.openclaw` の権限をロックダウンしてください（下記の監査セクションを参照）。エージェント間で より強い分離が必要な場合は、別々の OS ユーザーまたは別々のホストで実行してください。 ## Node 実行（system.run） -macOS ノードがペアリングされている場合、Gateway はそのノードで `system.run` を呼び出せます。これは Mac 上の **リモートコード実行** です: +macOS Node がペアリングされている場合、Gateway はその Node で `system.run` を呼び出せます。これは Mac 上の **リモートコード実行** です: -- node pairing（承認 + トークン）が必要です。 -- Gateway の node pairing は、コマンドごとの承認サーフェスではありません。ノードの identity/trust とトークン発行を確立します。 -- Gateway は、`gateway.nodes.allowCommands` / `denyCommands` によって粗いグローバルなノードコマンドポリシーを適用します。 -- Mac では **設定 → 実行承認**（セキュリティ + 確認 + 許可リスト）で制御します。 -- ノードごとの `system.run` ポリシーは、そのノード自身の実行承認ファイル（`exec.approvals.node.*`）であり、Gateway のグローバルなコマンド ID ポリシーより厳しくも緩くもできます。 -- `security="full"` かつ `ask="off"` で動作しているノードは、デフォルトの信頼済みオペレーターモデルに従っています。デプロイでより厳しい承認や許可リストの姿勢を明示的に要求していない限り、これは想定どおりの動作として扱ってください。 -- 承認モードは、正確なリクエストコンテキストと、可能な場合は 1 つの具体的なローカルスクリプト/ファイルオペランドに結び付きます。OpenClaw がインタープリター/ランタイムコマンドに対して直接のローカルファイルを正確に 1 つ特定できない場合、完全な意味的カバレッジを約束するのではなく、承認に基づく実行は拒否されます。 -- `host=node` の場合、承認に基づく実行では正規化された準備済みの - `systemRunPlan` も保存されます。後続の承認済み転送はその保存済みプランを再利用し、Gateway +- Node ペアリング（承認 + トークン）が必要です。 +- Gateway Node ペアリングは、コマンド単位の承認サーフェスではありません。Node の ID/信頼とトークン発行を確立します。 +- Gateway は、`gateway.nodes.allowCommands` / `denyCommands` を通じて大まかなグローバル Node コマンドポリシーを適用します。 +- Mac では **Settings → Exec approvals**（security + ask + allowlist）で制御します。 +- Node 単位の `system.run` ポリシーは、その Node 自身の exec approvals ファイル（`exec.approvals.node.*`）であり、Gateway のグローバルなコマンド ID ポリシーより厳しくも緩くもできます。 +- `security="full"` かつ `ask="off"` で実行されている Node は、既定の信頼されたオペレーターモデルに従っています。デプロイでより厳格な承認や allowlist の姿勢を明示的に要求していない限り、これは期待される動作として扱ってください。 +- 承認モードは、正確なリクエストコンテキストと、可能な場合は 1 つの具体的なローカルスクリプト/ファイルオペランドに結び付けられます。OpenClaw がインタープリター/ランタイムコマンドに対して直接のローカルファイルを正確に 1 つ特定できない場合、完全な意味的カバレッジを約束するのではなく、承認に基づく実行は拒否されます。 +- `host=node` の場合、承認に基づく実行は正規化された準備済みの + `systemRunPlan` も保存します。後続の承認済み転送はその保存済みプランを再利用し、Gateway の検証は、承認リクエスト作成後に呼び出し元が command/cwd/session コンテキストを編集することを拒否します。 -- リモート実行が不要な場合は、セキュリティを **deny** に設定し、その Mac の node pairing を削除してください。 +- リモート実行を望まない場合は、security を **deny** に設定し、その Mac の Node ペアリングを削除してください。 この区別はトリアージで重要です。 -- 再接続したペアリング済みノードが異なるコマンドリストを広告しても、Gateway のグローバルポリシーとノードのローカル実行承認が実際の実行境界を引き続き強制しているなら、それ自体は脆弱性ではありません。 -- node pairing メタデータを、2 つ目の隠れたコマンドごとの承認レイヤーとして扱うレポートは、通常はセキュリティ境界のバイパスではなく、ポリシー/UX の混同です。 +- 再接続したペアリング済み Node が異なるコマンドリストを広告しても、Gateway のグローバルポリシーと Node のローカル exec approvals が実際の実行境界を依然として強制しているなら、それ自体は脆弱性ではありません。 +- Node ペアリングメタデータを、2 つ目の隠れたコマンド単位承認レイヤーとして扱う報告は、通常はセキュリティ境界のバイパスではなく、ポリシー/UX の混同です。 -## 動的 Skills（ウォッチャー / リモートノード） +## 動的 Skills（watcher / リモート Node） OpenClaw はセッション中に Skills リストを更新できます。 -- **Skills ウォッチャー**: `SKILL.md` への変更は、次のエージェントターンで Skills スナップショットを更新できます。 -- **リモートノード**: macOS ノードを接続すると、（bin のプロービングに基づいて）macOS 専用 Skills が対象になり得ます。 +- **Skills watcher**: `SKILL.md` への変更は、次のエージェントターンで Skills スナップショットを更新できます。 +- **リモート Node**: macOS Node が接続すると、bin のプローブに基づいて macOS 専用 Skills が対象になり得ます。 Skill フォルダーは **信頼済みコード** として扱い、変更できる人を制限してください。 @@ -441,7 +436,7 @@ AI アシスタントは次のことができます。 - 任意のシェルコマンドを実行する - ファイルを読み書きする - ネットワークサービスにアクセスする -- （WhatsApp アクセスを与えた場合）誰にでもメッセージを送信する +- 誰にでもメッセージを送信する（WhatsApp アクセスを与えた場合） あなたにメッセージを送る人は次のことができます。 @@ -449,22 +444,22 @@ AI アシスタントは次のことができます。 - データへのアクセスをソーシャルエンジニアリングする - インフラの詳細を探る -## コアコンセプト: 知能より先にアクセス制御 +## 中核概念: 知能より前にアクセス制御 -ここでの失敗の多くは高度なエクスプロイトではありません。「誰かがボットにメッセージを送り、ボットが依頼されたことを実行した」というものです。 +ここでの失敗の多くは高度なエクスプロイトではなく、「誰かが bot にメッセージを送り、bot が頼まれたことを実行した」というものです。 OpenClaw の姿勢: -- **まずアイデンティティ:** 誰がボットと会話できるかを決める（DM pairing / 許可リスト / 明示的な「open」）。 -- **次にスコープ:** ボットがどこで動作できるかを決める（グループ許可リスト + メンションゲート、ツール、サンドボックス、デバイス権限）。 -- **最後にモデル:** モデルは操作され得ると想定し、操作されても影響範囲が限定されるように設計する。 +- **まず ID:** 誰が bot と会話できるかを決めます（DM ペアリング / allowlist / 明示的な「open」）。 +- **次にスコープ:** bot がどこで動作を許可されるかを決めます（グループ allowlist + メンションゲート、ツール、サンドボックス化、デバイス権限）。 +- **最後にモデル:** モデルは操作され得ると想定し、操作されても影響範囲が限定されるように設計します。 ## コマンド認可モデル -スラッシュコマンドとディレクティブは、**認可済み送信者** に対してのみ尊重されます。認可は、 -チャネルの許可リスト/pairing と `commands.useAccessGroups` から導出されます（[設定](/ja-JP/gateway/configuration) -および [スラッシュコマンド](/ja-JP/tools/slash-commands) を参照）。チャネル許可リストが空、または `"*"` を含む場合、 -そのチャネルではコマンドが実質的に公開されます。 +スラッシュコマンドとディレクティブは、**認可済み送信者** に対してのみ尊重されます。認可は +チャネル allowlist/ペアリングと `commands.useAccessGroups` から導出されます（[設定](/ja-JP/gateway/configuration) +および [スラッシュコマンド](/ja-JP/tools/slash-commands) を参照）。チャネル allowlist が空、または `"*"` を含む場合、 +そのチャネルではコマンドが実質的に開放されます。 `/exec` は、認可済みオペレーター向けのセッション内限定の便利機能です。設定を書き込んだり、 他のセッションを変更したりするものでは **ありません**。 @@ -474,16 +469,17 @@ OpenClaw の姿勢: 2 つの組み込みツールは、永続的なコントロールプレーン変更を行えます。 - `gateway` は `config.schema.lookup` / `config.get` で設定を検査でき、`config.apply`、`config.patch`、`update.run` で永続的な変更を行えます。 -- `cron` は、元のチャット/タスク終了後も実行され続けるスケジュールジョブを作成できます。 +- `cron` は、元のチャット/タスク終了後も実行され続けるスケジュール済みジョブを作成できます。 -所有者専用の `gateway` ランタイムツールは、現在も -`tools.exec.ask` や `tools.exec.security` の書き換えを拒否します。レガシーの `tools.bash.*` エイリアスは、 -書き込み前に同じ保護された実行パスへ正規化されます。 -エージェント駆動の `gateway config.apply` および `gateway config.patch` 編集は、 -デフォルトで fail-closed です。エージェントが調整できるのは、プロンプト、モデル、メンションゲートの -限定的なパスだけです。そのため、新しい機密設定ツリーは、意図的に許可リストへ追加されない限り保護されます。 +所有者専用の `gateway` ランタイムツールであっても、 +`tools.exec.ask` または `tools.exec.security` の書き換えは拒否されます。レガシーの `tools.bash.*` エイリアスは、 +書き込み前に同じ保護対象の exec パスへ正規化されます。 +エージェント駆動の `gateway config.apply` と `gateway config.patch` の編集は、 +既定で fail-closed です。エージェントが調整できるのは、prompt、model、mention-gating +パスの狭い集合だけです。そのため、新しい機微な設定ツリーは +allowlist に意図的に追加されない限り保護されます。 -信頼できないコンテンツを扱うエージェント/サーフェスでは、デフォルトでこれらを拒否してください。 +信頼できないコンテンツを扱うエージェント/サーフェスでは、既定でこれらを拒否してください。 ```json5 { @@ -493,33 +489,33 @@ OpenClaw の姿勢: } ``` -`commands.restart=false` は再起動アクションのみをブロックします。`gateway` の設定/更新アクションを無効化するものではありません。 +`commands.restart=false` は再起動アクションだけをブロックします。`gateway` の config/update アクションは無効化しません。 -## Plugins +## Plugin -Plugins は Gateway と **同一プロセス内** で実行されます。信頼済みコードとして扱ってください。 +Plugin は Gateway と **同一プロセス内** で実行されます。信頼済みコードとして扱ってください。 -- 信頼できるソースの Plugins だけをインストールしてください。 -- 明示的な `plugins.allow` 許可リストを優先してください。 -- 有効化する前に Plugin 設定を確認してください。 +- 信頼できるソースからの Plugin だけをインストールしてください。 +- 明示的な `plugins.allow` allowlist を推奨します。 +- 有効化する前に Plugin 設定をレビューしてください。 - Plugin 変更後は Gateway を再起動してください。 -- Plugins をインストールまたは更新する場合（`openclaw plugins install `、`openclaw plugins update `）、信頼できないコードを実行するのと同様に扱ってください。 - - インストールパスは、有効な Plugin インストールルート配下の Plugin ごとのディレクトリです。 - - OpenClaw はインストール/更新前に組み込みの危険コードスキャンを実行します。`critical` の検出結果はデフォルトでブロックされます。 - - OpenClaw は `npm pack` を使用し、そのディレクトリでプロジェクトローカルの `npm install --omit=dev --ignore-scripts` を実行します。継承されたグローバル npm インストール設定は無視されるため、依存関係は Plugin インストールパス配下に留まります。 - - 固定された正確なバージョン（`@scope/pkg@1.2.3`）を優先し、有効化する前にディスク上の展開済みコードを検査してください。 - - `--dangerously-force-unsafe-install` は、Plugin のインストール/更新フローにおける組み込みスキャンの偽陽性に対する緊急時専用です。Plugin の `before_install` フックポリシーブロックをバイパスせず、スキャン失敗もバイパスしません。 - - Gateway ベースの Skill 依存関係インストールは、同じ危険/疑わしいの分割に従います。組み込みの `critical` 検出結果は、呼び出し元が明示的に `dangerouslyForceUnsafeInstall` を設定しない限りブロックされます。一方、疑わしい検出結果は引き続き警告のみです。`openclaw skills install` は、別個の ClawHub Skill ダウンロード/インストールフローのままです。 +- Plugin をインストールまたは更新する場合（`openclaw plugins install `、`openclaw plugins update `）、信頼できないコードを実行するのと同じように扱ってください。 + - インストール先は、アクティブな Plugin インストールルート配下の Plugin 単位ディレクトリです。 + - OpenClaw はインストール/更新前に組み込みの危険コードスキャンを実行します。`critical` の検出結果は既定でブロックされます。 + - OpenClaw は `npm pack` を使用し、そのディレクトリ内でプロジェクトローカルの `npm install --omit=dev --ignore-scripts` を実行します。依存関係が Plugin インストール先配下に留まるよう、継承されたグローバル npm インストール設定は無視されます。 + - ピン留めされた正確なバージョン（`@scope/pkg@1.2.3`）を推奨し、有効化前にディスク上で展開されたコードを確認してください。 + - `--dangerously-force-unsafe-install` は、Plugin インストール/更新フローで組み込みスキャンの誤検知がある場合のみの非常手段です。Plugin の `before_install` フックポリシーブロックはバイパスせず、スキャン失敗もバイパスしません。 + - Gateway に基づく Skill 依存関係のインストールも、同じ dangerous/suspicious の分離に従います。組み込みの `critical` 検出結果は、呼び出し元が `dangerouslyForceUnsafeInstall` を明示的に設定しない限りブロックされます。一方で suspicious の検出結果は引き続き警告のみです。`openclaw skills install` は、別個の ClawHub Skill ダウンロード/インストールフローのままです。 -詳細: [Plugins](/ja-JP/tools/plugin) +詳細: [Plugin](/ja-JP/tools/plugin) -## DM アクセスモデル: pairing、許可リスト、open、disabled +## DM アクセスモデル: ペアリング、allowlist、open、disabled -現在の DM 対応チャネルはすべて、メッセージ処理 **前** に受信 DM をゲートする DM ポリシー（`dmPolicy` または `*.dm.policy`）をサポートします。 +現在のすべての DM 対応チャネルは、メッセージ処理 **前** に受信 DM をゲートする DM ポリシー（`dmPolicy` または `*.dm.policy`）をサポートしています。 -- `pairing`（デフォルト）: 不明な送信者は短い pairing コードを受け取り、承認されるまでボットはそのメッセージを無視します。コードは 1 時間後に期限切れになります。新しいリクエストが作成されるまで、DM を繰り返してもコードは再送されません。保留中のリクエストは、デフォルトで **チャネルごとに 3 件** までに制限されます。 -- `allowlist`: 不明な送信者はブロックされます（pairing ハンドシェイクなし）。 -- `open`: 誰でも DM できるようにします（公開）。チャネル許可リストに `"*"` が含まれていることが **必要** です（明示的なオプトイン）。 +- `pairing`（既定）: 未知の送信者は短いペアリングコードを受け取り、bot は承認されるまでそのメッセージを無視します。コードは 1 時間後に期限切れになります。新しいリクエストが作成されるまで、DM を繰り返してもコードは再送されません。保留中のリクエストは既定で **チャネルごとに 3 件** に制限されます。 +- `allowlist`: 未知の送信者はブロックされます（ペアリングハンドシェイクなし）。 +- `open`: 誰でも DM できるようにします（公開）。チャネル allowlist に `"*"` を含めることが **必要** です（明示的なオプトイン）。 - `disabled`: 受信 DM を完全に無視します。 CLI で承認します。 @@ -529,11 +525,11 @@ openclaw pairing list openclaw pairing approve ``` -詳細 + ディスク上のファイル: [Pairing](/ja-JP/channels/pairing) +詳細 + ディスク上のファイル: [ペアリング](/ja-JP/channels/pairing) ## DM セッション分離（マルチユーザーモード） -デフォルトでは、OpenClaw は **すべての DM をメインセッションへルーティング** するため、アシスタントはデバイスやチャネルをまたいで継続性を持てます。**複数人** がボットに DM できる場合（open DM または複数人の許可リスト）、DM セッションの分離を検討してください。 +既定では、OpenClaw は **すべての DM をメインセッションへルーティング** するため、アシスタントはデバイスやチャネルをまたいだ継続性を持てます。**複数人** が bot に DM できる場合（open DM または複数人 allowlist）、DM セッションの分離を検討してください。 ```json5 { @@ -541,76 +537,76 @@ openclaw pairing approve } ``` -これにより、グループチャットを分離したまま、ユーザー間のコンテキスト漏えいを防げます。 +これにより、グループチャットは分離されたまま、ユーザー間のコンテキスト漏えいを防ぎます。 これはメッセージングコンテキストの境界であり、ホスト管理者の境界ではありません。ユーザー同士が相互に敵対的で、同じ Gateway ホスト/設定を共有している場合は、信頼境界ごとに別々の Gateway を実行してください。 -### セキュア DM モード（推奨） +### 安全な DM モード（推奨） -上記のスニペットを **セキュア DM モード** として扱ってください。 +上記のスニペットを **安全な DM モード** として扱ってください。 -- デフォルト: `session.dmScope: "main"`（継続性のため、すべての DM が 1 つのセッションを共有します）。 -- ローカル CLI オンボーディングのデフォルト: 未設定の場合に `session.dmScope: "per-channel-peer"` を書き込みます（既存の明示的な値は維持します）。 -- セキュア DM モード: `session.dmScope: "per-channel-peer"`（各チャネル+送信者ペアが分離された DM コンテキストを持ちます）。 -- クロスチャネルのピア分離: `session.dmScope: "per-peer"`（各送信者が同じ種類のすべてのチャネルにまたがって 1 つのセッションを持ちます）。 +- 既定: `session.dmScope: "main"`（継続性のため、すべての DM が 1 つのセッションを共有します）。 +- ローカル CLI オンボーディングの既定: 未設定時に `session.dmScope: "per-channel-peer"` を書き込みます（既存の明示値は維持します）。 +- 安全な DM モード: `session.dmScope: "per-channel-peer"`（各チャネル+送信者ペアが分離された DM コンテキストを持ちます）。 +- クロスチャネルのピア分離: `session.dmScope: "per-peer"`（各送信者が同じ種類のすべてのチャネルをまたいで 1 つのセッションを持ちます）。 -同じチャネルで複数アカウントを運用する場合は、代わりに `per-account-channel-peer` を使用してください。同じ人が複数チャネルで連絡してくる場合は、`session.identityLinks` を使用してそれらの DM セッションを 1 つの正規 identity にまとめてください。[セッション管理](/ja-JP/concepts/session) と [設定](/ja-JP/gateway/configuration) を参照してください。 +同じチャネルで複数アカウントを実行する場合は、代わりに `per-account-channel-peer` を使用してください。同じ人物が複数チャネルで連絡してくる場合は、`session.identityLinks` を使用してそれらの DM セッションを 1 つの正規 ID にまとめてください。[セッション管理](/ja-JP/concepts/session) と [設定](/ja-JP/gateway/configuration) を参照してください。 -## DM とグループの許可リスト +## DM とグループの allowlist -OpenClaw には、「誰が自分をトリガーできるか？」に関する 2 つの別個のレイヤーがあります。 +OpenClaw には「誰が自分をトリガーできるか」というレイヤーが 2 つあります。 -- **DM 許可リスト**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`、レガシー: `channels.discord.dm.allowFrom`、`channels.slack.dm.allowFrom`）: ダイレクトメッセージでボットと会話することを許可される人。 - - `dmPolicy="pairing"` の場合、承認は `~/.openclaw/credentials/` 配下のアカウントスコープの pairing 許可リストストア（デフォルトアカウントでは `-allowFrom.json`、非デフォルトアカウントでは `--allowFrom.json`）に書き込まれ、設定の許可リストとマージされます。 -- **グループ許可リスト**（チャネル固有）: ボットがそもそもメッセージを受け付けるグループ/チャネル/ギルド。 +- **DM allowlist**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; レガシー: `channels.discord.dm.allowFrom`、`channels.slack.dm.allowFrom`）: ダイレクトメッセージで bot と会話できる人。 + - `dmPolicy="pairing"` の場合、承認は `~/.openclaw/credentials/` 配下のアカウントスコープのペアリング allowlist ストア（既定アカウントでは `-allowFrom.json`、非既定アカウントでは `--allowFrom.json`）に書き込まれ、設定の allowlist とマージされます。 +- **グループ allowlist**（チャネル固有）: bot がそもそもどのグループ/チャネル/ギルドからのメッセージを受け入れるか。 - 一般的なパターン: - - `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`: `requireMention` のようなグループごとのデフォルト。設定すると、グループ許可リストとしても機能します（すべて許可の動作を維持するには `"*"` を含めます）。 - - `groupPolicy="allowlist"` + `groupAllowFrom`: グループセッション _内_ でボットをトリガーできる人を制限します（WhatsApp/Telegram/Signal/iMessage/Microsoft Teams）。 - - `channels.discord.guilds` / `channels.slack.channels`: サーフェスごとの許可リスト + メンションのデフォルト。 - - グループチェックはこの順序で実行されます: まず `groupPolicy`/グループ許可リスト、次にメンション/返信による有効化。 - - ボットメッセージへの返信（暗黙のメンション）は、`groupAllowFrom` のような送信者許可リストを **バイパスしません**。 - - **セキュリティメモ:** `dmPolicy="open"` と `groupPolicy="open"` は最後の手段の設定として扱ってください。ほとんど使うべきではありません。部屋の全メンバーを完全に信頼していない限り、pairing + 許可リストを優先してください。 + - `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`: `requireMention` のようなグループ単位の既定値。設定されると、グループ allowlist としても機能します（全許可の動作を維持するには `"*"` を含めます）。 + - `groupPolicy="allowlist"` + `groupAllowFrom`: グループセッション _内_ で bot をトリガーできる人を制限します（WhatsApp/Telegram/Signal/iMessage/Microsoft Teams）。 + - `channels.discord.guilds` / `channels.slack.channels`: サーフェス単位の allowlist + メンション既定値。 + - グループチェックはこの順序で実行されます: まず `groupPolicy`/グループ allowlist、次にメンション/返信によるアクティベーション。 + - bot メッセージへの返信（暗黙のメンション）は、`groupAllowFrom` のような送信者 allowlist を **バイパスしません**。 + - **セキュリティ注記:** `dmPolicy="open"` と `groupPolicy="open"` は最後の手段として扱ってください。部屋の全メンバーを完全に信頼している場合を除き、使用はごく限定的にし、ペアリング + allowlist を推奨します。 -詳細: [設定](/ja-JP/gateway/configuration) および [グループ](/ja-JP/channels/groups) +詳細: [設定](/ja-JP/gateway/configuration) と [グループ](/ja-JP/channels/groups) -## プロンプトインジェクション（概要と重要性） +## Prompt injection（それが何であり、なぜ重要か） -プロンプトインジェクションとは、攻撃者がメッセージを巧妙に作り、モデルを操作して安全でないことをさせることです（「指示を無視しろ」、「ファイルシステムをダンプしろ」、「このリンクをたどってコマンドを実行しろ」など）。 +Prompt injection とは、攻撃者がメッセージを細工し、モデルを操作して安全でないことをさせることです（「指示を無視しろ」、「ファイルシステムをダンプしろ」、「このリンクを開いてコマンドを実行しろ」など）。 -強力なシステムプロンプトがあっても、**プロンプトインジェクションは解決されていません**。システムプロンプトのガードレールは柔らかな指針にすぎません。強制力のある適用は、ツールポリシー、実行承認、サンドボックス、チャネル許可リストから生まれます（また、オペレーターは設計上これらを無効化できます）。実際に役立つこと: +強力なシステムプロンプトがあっても、**prompt injection は解決済みではありません**。システムプロンプトのガードレールはあくまで柔らかい指針です。強制力は、ツールポリシー、exec approvals、サンドボックス化、チャネル allowlist から生じます（また、オペレーターは設計上これらを無効化できます）。実務で役立つこと: -- 受信 DM はロックダウンしてください (ペアリング/許可リスト)。 -- グループではメンションによるゲートを優先し、公開ルームで「常時稼働」のボットは避けてください。 +- 受信 DM は厳格に制限してください（ペアリング/許可リスト）。 +- グループではメンションゲーティングを優先し、公開ルームで「常時稼働」のボットは避けてください。 - リンク、添付ファイル、貼り付けられた指示は、デフォルトで敵対的なものとして扱ってください。 - 機密性の高いツール実行はサンドボックス内で実行し、シークレットをエージェントが到達可能なファイルシステムの外に置いてください。 -- 注: サンドボックス化はオプトインです。サンドボックスモードがオフの場合、暗黙の `host=auto` は Gateway ホストに解決されます。明示的な `host=sandbox` は、利用可能なサンドボックスランタイムがないため、なおもフェイルクローズします。その動作を設定で明示したい場合は `host=gateway` を設定してください。 -- 高リスクのツール (`exec`, `browser`, `web_fetch`, `web_search`) は、信頼済みエージェントまたは明示的な許可リストに制限してください。 -- インタープリター (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`) を許可リストに入れる場合は、インライン eval 形式にも明示的な承認が必要になるように `tools.exec.strictInlineEval` を有効にしてください。 -- Shell 承認分析は、**引用符なしの heredoc** 内にある POSIX パラメーター展開形式 (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) も拒否します。そのため、許可リストに入った heredoc 本文が、プレーンテキストとしての許可リストレビューをすり抜けて Shell 展開を行うことはできません。リテラル本文セマンティクスを選ぶには、heredoc 終端子を引用符で囲んでください (例: `<<'EOF'`)。変数を展開するはずだった引用符なし heredoc は拒否されます。 -- **モデルの選択は重要です:** 古い/小さい/レガシーモデルは、プロンプトインジェクションやツールの悪用に対して大幅に堅牢性が低くなります。ツール有効エージェントでは、利用可能な中で最も強力な最新世代の、指示に対して強化されたモデルを使用してください。 +- 注意: サンドボックス化はオプトインです。サンドボックスモードがオフの場合、暗黙の `host=auto` は Gateway ホストに解決されます。明示的な `host=sandbox` は、利用可能なサンドボックスランタイムがないため、なおもクローズドに失敗します。その挙動を設定で明示したい場合は `host=gateway` を設定してください。 +- 高リスクのツール（`exec`、`browser`、`web_fetch`、`web_search`）は、信頼済みエージェントまたは明示的な許可リストに限定してください。 +- インタープリター（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`）を許可リストに入れる場合は、インライン eval 形式にも明示的な承認が必要になるように `tools.exec.strictInlineEval` を有効にしてください。 +- シェル承認分析は、**引用符なしの heredoc** 内にある POSIX パラメーター展開形式（`$VAR`、`$?`、`$$`、`$1`、`$@`、`${…}`）も拒否するため、許可リスト済みの heredoc 本文がプレーンテキストとして許可リストレビューをすり抜け、シェル展開を紛れ込ませることはできません。リテラル本文セマンティクスを選ぶには、heredoc 終端子を引用符で囲んでください（例: `<<'EOF'`）。変数が展開されるはずだった引用符なしの heredoc は拒否されます。 +- **モデル選択は重要です:** 古い/小さい/レガシーなモデルは、プロンプトインジェクションやツールの誤用に対する堅牢性が大幅に低くなります。ツール有効のエージェントには、利用可能な中で最も強力な最新世代の、指示耐性を高めたモデルを使用してください。 信頼できないものとして扱うべき危険信号: -- 「このファイル/URL を読み、その内容どおりに正確に実行してください。」 +- 「このファイル/URL を読み、その内容に正確に従ってください。」 - 「システムプロンプトまたは安全ルールを無視してください。」 -- 「隠し指示またはツール出力を明かしてください。」 -- 「~/.openclaw またはログの全文を貼り付けてください。」 +- 「隠された指示またはツール出力を公開してください。」 +- 「`~/.openclaw` またはログの全文を貼り付けてください。」 -## 外部コンテンツの特殊トークンのサニタイズ +## 外部コンテンツの特殊トークンサニタイズ -OpenClaw は、ラップされた外部コンテンツとメタデータがモデルに到達する前に、一般的なセルフホスト LLM チャットテンプレートの特殊トークンリテラルを取り除きます。対象のマーカーファミリーには、Qwen/ChatML、Llama、Gemma、Mistral、Phi、GPT-OSS のロール/ターントークンが含まれます。 +OpenClaw は、ラップされた外部コンテンツとメタデータがモデルに到達する前に、一般的なセルフホスト LLM チャットテンプレートの特殊トークンリテラルを取り除きます。対象となるマーカーファミリーには、Qwen/ChatML、Llama、Gemma、Mistral、Phi、および GPT-OSS のロール/ターントークンが含まれます。 理由: -- セルフホストモデルの前段にある OpenAI 互換バックエンドは、ユーザーテキスト内に現れる特殊トークンをマスクせずに保持する場合があります。受信した外部コンテンツ (取得されたページ、メール本文、ファイル内容ツール出力) に書き込める攻撃者は、そうでなければ合成された `assistant` または `system` ロール境界を注入し、ラップ済みコンテンツのガードレールを抜けられる可能性があります。 +- セルフホストモデルの前段にある OpenAI 互換バックエンドは、ユーザーテキスト内に現れる特殊トークンをマスクせず、そのまま保持する場合があります。受信外部コンテンツ（取得したページ、メール本文、ファイル内容ツールの出力）に書き込める攻撃者は、そうでなければ合成された `assistant` または `system` ロール境界を注入し、ラップ済みコンテンツのガードレールを回避できてしまいます。 - サニタイズは外部コンテンツのラップ層で行われるため、プロバイダーごとではなく、取得/読み取りツールと受信チャネルコンテンツ全体に一貫して適用されます。 -- 送信モデル応答には、漏えいした ``、``、``、``、および類似の内部ランタイム足場を、最終チャネル配信境界でユーザーに見える返信から取り除く別のサニタイザーがすでにあります。外部コンテンツサニタイザーは、その受信側の対応物です。 +- 送信モデル応答にはすでに別のサニタイザーがあり、最終的なチャネル配信境界で、ユーザーに表示される返信から漏洩した ``、``、``、``、および同様の内部ランタイム足場を取り除きます。外部コンテンツサニタイザーは、その受信側の対応物です。 -これは、このページの他の強化策を置き換えるものではありません。`dmPolicy`、許可リスト、exec 承認、サンドボックス化、`contextVisibility` が引き続き主要な役割を担います。これは、特殊トークンをそのまま含むユーザーテキストを転送するセルフホストスタックに対する、特定のトークナイザー層バイパスを 1 つ塞ぐものです。 +これは、このページにある他の強化策を置き換えるものではありません。`dmPolicy`、許可リスト、exec 承認、サンドボックス化、`contextVisibility` が引き続き主要な役割を担います。これは、特殊トークンをそのまま含むユーザーテキストを転送するセルフホストスタックに対する、特定のトークナイザー層バイパスを 1 つ塞ぐものです。 ## 安全でない外部コンテンツのバイパスフラグ -OpenClaw には、外部コンテンツの安全ラップを無効化する明示的なバイパスフラグが含まれています。 +OpenClaw には、外部コンテンツの安全ラップを無効にする明示的なバイパスフラグが含まれています。 - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` @@ -618,497 +614,408 @@ OpenClaw には、外部コンテンツの安全ラップを無効化する明 ガイダンス: -- 本番環境ではこれらを未設定/false のままにしてください。 -- 厳密にスコープされたデバッグのために、一時的にのみ有効にしてください。 -- 有効にする場合は、そのエージェントを分離してください (サンドボックス + 最小限のツール + 専用セッション名前空間)。 +- 本番環境では、これらを未設定/false のままにしてください。 +- 厳密にスコープを限定したデバッグのためにのみ、一時的に有効にしてください。 +- 有効にする場合は、そのエージェントを隔離してください（サンドボックス + 最小限のツール + 専用セッション名前空間）。 -フックのリスクに関する注意: +Hooks リスク注意: -- 配信元が管理下のシステムであっても、フックペイロードは信頼できないコンテンツです (メール/ドキュメント/Web コンテンツはプロンプトインジェクションを運ぶ可能性があります)。 -- 弱いモデル階層はこのリスクを高めます。フック駆動の自動化では、強力で現代的なモデル階層を優先し、ツールポリシーを厳格に保ってください (`tools.profile: "messaging"` またはそれ以上に厳格)。可能な場合はサンドボックス化も併用してください。 +- フックペイロードは、配信元が自分で管理するシステムであっても信頼できないコンテンツです（メール/ドキュメント/Web コンテンツはプロンプトインジェクションを含む可能性があります）。 +- 弱いモデル階層はこのリスクを高めます。フック駆動の自動化では、強力な最新モデル階層を優先し、ツールポリシーを厳しく保ちます（`tools.profile: "messaging"` 以上に厳格な設定）。可能な場合はサンドボックス化も併用します。 -### プロンプトインジェクションに公開 DM は不要 +### プロンプトインジェクションには公開DMは不要です -**自分だけ**がボットにメッセージを送れる場合でも、ボットが読む任意の**信頼できないコンテンツ** (Web 検索/取得結果、ブラウザーページ、メール、ドキュメント、添付ファイル、貼り付けられたログ/コード) を通じて、プロンプトインジェクションは発生し得ます。言い換えると、送信者だけが脅威面ではありません。**コンテンツ自体**が敵対的な指示を運ぶ可能性があります。 +**自分だけ**がボットにメッセージを送れる場合でも、ボットが読む +あらゆる**信頼できないコンテンツ**（Web 検索/取得結果、ブラウザページ、 +メール、ドキュメント、添付ファイル、貼り付けられたログ/コード）を通じて、プロンプトインジェクションは発生し得ます。言い換えると、送信者だけが脅威面ではありません。**コンテンツ自体**が敵対的な指示を含む可能性があります。 -ツールが有効な場合、典型的なリスクはコンテキストの流出またはツール呼び出しの誘発です。影響範囲を減らすには: +ツールが有効な場合、典型的なリスクはコンテキストの外部流出や +ツール呼び出しの誘発です。影響範囲を小さくするには、次のようにします。 -- 信頼できないコンテンツを要約するために、読み取り専用またはツール無効の**リーダーエージェント**を使用し、その要約をメインエージェントに渡します。 -- ツール有効エージェントでは、必要でない限り `web_search` / `web_fetch` / `browser` をオフにしておきます。 -- OpenResponses URL 入力 (`input_file` / `input_image`) では、`gateway.http.endpoints.responses.files.urlAllowlist` と `gateway.http.endpoints.responses.images.urlAllowlist` を厳しく設定し、`maxUrlParts` を低く保ちます。空の許可リストは未設定として扱われます。URL 取得を完全に無効化したい場合は、`files.allowUrl: false` / `images.allowUrl: false` を使用してください。 -- OpenResponses ファイル入力では、デコードされた `input_file` テキストは引き続き**信頼できない外部コンテンツ**として注入されます。Gateway がローカルでデコードしたからといって、ファイルテキストが信頼済みであるとは見なさないでください。このパスでは長い `SECURITY NOTICE:` バナーは省略されますが、注入されたブロックには明示的な `<<>>` 境界マーカーと `Source: External` メタデータが引き続き含まれます。 -- 添付ドキュメントからメディア理解がテキストを抽出し、そのテキストをメディアプロンプトに追加する場合にも、同じマーカーベースのラップが適用されます。 -- 信頼できない入力に触れる任意のエージェントに対して、サンドボックス化と厳格なツール許可リストを有効にします。 -- シークレットをプロンプトに入れないでください。代わりに Gateway ホスト上の env/config 経由で渡します。 +- 読み取り専用またはツール無効化された**リーダーエージェント**を使って信頼できないコンテンツを要約し、 + その要約をメインのエージェントに渡します。 +- ツール有効化されたエージェントでは、必要な場合を除き `web_search` / `web_fetch` / `browser` をオフにします。 +- OpenResponses の URL 入力（`input_file` / `input_image`）では、 + `gateway.http.endpoints.responses.files.urlAllowlist` と + `gateway.http.endpoints.responses.images.urlAllowlist` を厳しく設定し、`maxUrlParts` を低く保ちます。 + 空の許可リストは未設定として扱われます。URL 取得を完全に無効化したい場合は、`files.allowUrl: false` / `images.allowUrl: false` + を使用します。 +- OpenResponses のファイル入力では、デコードされた `input_file` テキストも + **信頼できない外部コンテンツ**として注入されます。Gateway がローカルでデコードしたからといって、 + ファイルテキストが信頼できるものだと見なさないでください。注入されたブロックには、この経路では長い `SECURITY NOTICE:` バナーが省略されるものの、 + 明示的な `<<>>` 境界マーカーと `Source: External` + メタデータが引き続き含まれます。 +- 添付ドキュメントからメディア理解がテキストを抽出し、そのテキストをメディアプロンプトに追加する場合にも、同じマーカーベースのラッピングが適用されます。 +- 信頼できない入力に触れるすべてのエージェントで、サンドボックス化と厳格なツール許可リストを有効にします。 +- シークレットをプロンプトに含めず、代わりに Gateway ホスト上の env/config 経由で渡します。 -### セルフホスト LLM バックエンド +### セルフホスト型 LLM バックエンド -vLLM、SGLang、TGI、LM Studio、またはカスタム Hugging Face トークナイザースタックなどの OpenAI 互換セルフホストバックエンドは、チャットテンプレートの特殊トークンの扱いがホスト型プロバイダーと異なる場合があります。バックエンドが `<|im_start|>`、`<|start_header_id|>`、`` などのリテラル文字列を、ユーザーコンテンツ内で構造的なチャットテンプレートトークンとしてトークン化する場合、信頼できないテキストがトークナイザー層でロール境界を偽造しようとする可能性があります。 +vLLM、SGLang、TGI、LM Studio、 +またはカスタム Hugging Face トークナイザースタックのような OpenAI 互換のセルフホスト型バックエンドは、 +チャットテンプレートの特殊トークンの扱いがホスト型プロバイダーと異なる場合があります。バックエンドが +`<|im_start| -OpenClaw は、モデルにディスパッチする前に、ラップされた外部コンテンツから一般的なモデルファミリーの特殊トークンリテラルを取り除きます。外部コンテンツのラップは有効なままにし、利用可能な場合は、ユーザー提供コンテンツ内の特殊トークンを分割またはエスケープするバックエンド設定を優先してください。OpenAI や Anthropic などのホスト型プロバイダーは、すでに独自のリクエスト側サニタイズを適用しています。 +OpenClaw は、モデルへ送信する前に、ラップされた外部コンテンツから一般的なモデルファミリーの特殊トークンリテラルを取り除きます。外部コンテンツのラップは有効のままにし、利用できる場合は、ユーザー提供コンテンツ内の特殊トークンを分割またはエスケープするバックエンド設定を優先してください。OpenAI や Anthropic などのホステッドプロバイダーは、すでに独自のリクエスト側サニタイズを適用しています。 -### モデル強度 (セキュリティ注意) +### モデルの強度（セキュリティ上の注意） -プロンプトインジェクション耐性は、モデル階層全体で**均一ではありません**。小さい/安価なモデルは、特に敵対的なプロンプト下で、一般にツールの悪用や指示の乗っ取りに対してより脆弱です。 +プロンプトインジェクション耐性は、モデル階層全体で**一様ではありません**。小型または低価格のモデルは、特に敵対的なプロンプト下では、一般にツールの誤用や命令の乗っ取りを受けやすくなります。 -ツール有効エージェント、または信頼できないコンテンツを読むエージェントでは、古い/小さいモデルによるプロンプトインジェクションリスクは高すぎることがよくあります。そのようなワークロードを弱いモデル階層で実行しないでください。 +ツールを有効にしたエージェントや信頼できないコンテンツを読むエージェントでは、古いモデルや小さいモデルのプロンプトインジェクションリスクは高すぎることがよくあります。そのようなワークロードを弱いモデル階層で実行しないでください。 推奨事項: -- ツールを実行できる、またはファイル/ネットワークに触れる任意のボットには、**最新世代の最上位モデル**を使用してください。 -- ツール有効エージェントまたは信頼できない受信箱には、**古い/弱い/小さい階層を使用しないでください**。プロンプトインジェクションリスクが高すぎます。 -- 小さいモデルを使わざるを得ない場合は、**影響範囲を減らしてください** (読み取り専用ツール、強力なサンドボックス化、最小限のファイルシステムアクセス、厳格な許可リスト)。 -- 小さいモデルを実行する場合は、入力が厳密に制御されていない限り、**すべてのセッションでサンドボックス化を有効にし**、**web_search/web_fetch/browser を無効化**してください。 -- 信頼済み入力でツールなしのチャット専用パーソナルアシスタントでは、通常、小さいモデルでも問題ありません。 +- ツールを実行したりファイルやネットワークにアクセスしたりできるボットには、**最新世代の最上位モデルを使用**してください。 +- ツールを有効にしたエージェントや信頼できない受信箱には、**古い、弱い、または小さい階層を使用しないでください**。プロンプトインジェクションリスクが高すぎます。 +- 小さいモデルを使わざるを得ない場合は、**影響範囲を縮小**してください（読み取り専用ツール、強力なサンドボックス化、最小限のファイルシステムアクセス、厳格な許可リスト）。 +- 小さいモデルを実行する場合は、入力が厳密に制御されていない限り、**すべてのセッションでサンドボックス化を有効**にし、**web_search/web_fetch/browser を無効**にしてください。 +- 信頼できる入力のみを扱い、ツールを使わないチャット専用の個人アシスタントでは、通常、小さいモデルでも問題ありません。 -## グループ内の Reasoning と詳細出力 +## グループでの推論と詳細出力 -`/reasoning`、`/verbose`、`/trace` は、公開チャネル向けではなかった内部推論、ツール出力、または Plugin 診断を公開する可能性があります。グループ設定では、これらを**デバッグ専用**として扱い、明示的に必要な場合を除いてオフにしておいてください。 +`/reasoning`、`/verbose`、`/trace` は、公開チャンネル向けではない内部推論、ツール出力、または Plugin診断を露出する可能性があります。グループ設定では、これらを**デバッグ専用**として扱い、明示的に必要な場合を除いてオフにしておいてください。 ガイダンス: - 公開ルームでは `/reasoning`、`/verbose`、`/trace` を無効のままにしてください。 -- 有効にする場合は、信頼済み DM または厳密に制御されたルームでのみ行ってください。 -- 注意: verbose と trace 出力には、ツール引数、URL、Plugin 診断、およびモデルが見たデータが含まれる可能性があります。 +- 有効にする場合は、信頼できる DM または厳密に管理されたルームのみにしてください。 +- 注意: verbose と trace の出力には、ツール引数、URL、Plugin診断情報、モデルが見たデータが含まれることがあります。 -## 設定強化の例 +## 設定の強化例 ### ファイル権限 -Gateway ホスト上で config + state を非公開に保ってください。 +Gatewayホスト上の設定と状態を非公開にしてください: -- `~/.openclaw/openclaw.json`: `600` (ユーザーの読み取り/書き込みのみ) +- `~/.openclaw/openclaw.json`: `600` (ユーザーの読み書きのみ) - `~/.openclaw`: `700` (ユーザーのみ) -`openclaw doctor` は、これらの権限について警告し、強化を提案できます。 +`openclaw doctor` は、これらの権限について警告し、より厳しくする提案を行えます。 ### ネットワーク公開 (バインド、ポート、ファイアウォール) -Gateway は単一ポートで **WebSocket + HTTP** を多重化します。 +Gateway は単一ポートで **WebSocket + HTTP** を多重化します: - デフォルト: `18789` -- 設定/フラグ/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` +- 設定/フラグ/env: `gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT` -この HTTP サーフェスには、Control UI とキャンバスホストが含まれます。 +この HTTP サーフェスには Control UI とキャンバスホストが含まれます: - Control UI (SPA アセット) (デフォルトベースパス `/`) - キャンバスホスト: `/__openclaw__/canvas/` と `/__openclaw__/a2ui/` (任意の HTML/JS。信頼できないコンテンツとして扱ってください) -通常のブラウザーでキャンバスコンテンツを読み込む場合は、他の信頼できない Web ページと同じように扱ってください。 +通常のブラウザーでキャンバスコンテンツを読み込む場合は、他の信頼できない Web ページと同様に扱ってください: - キャンバスホストを信頼できないネットワーク/ユーザーに公開しないでください。 -- 影響を完全に理解していない限り、キャンバスコンテンツを特権 Web サーフェスと同じオリジンで共有させないでください。 +- 影響を完全に理解していない限り、キャンバスコンテンツを特権 Web サーフェスと同じオリジンで共有しないでください。 -バインドモードは、Gateway がリッスンする場所を制御します。 +バインドモードは Gateway が待ち受ける場所を制御します: - `gateway.bind: "loopback"` (デフォルト): ローカルクライアントのみ接続できます。 -- 非 loopback バインド (`"lan"`, `"tailnet"`, `"custom"`) は攻撃対象領域を広げます。Gateway 認証 (共有トークン/パスワード、または正しく設定された信頼済みプロキシ) と実際のファイアウォールを併用する場合にのみ使用してください。 +- 非 loopback バインド (`"lan"`、`"tailnet"`、`"custom"`) は攻撃対象領域を広げます。Gateway認証 (共有トークン/パスワード、または正しく設定された信頼済みプロキシ) と実際のファイアウォールがある場合にのみ使用してください。 -経験則: +目安: -- LAN バインドよりも Tailscale Serve を優先してください (Serve は Gateway を loopback 上に保ち、Tailscale がアクセスを処理します)。 -- LAN にバインドせざるを得ない場合は、ポートを送信元 IP の厳格な許可リストにファイアウォールで制限してください。広範囲にポートフォワードしないでください。 -- Gateway を `0.0.0.0` で認証なしに公開しないでください。 +- LAN バインドよりも Tailscale Serve を優先してください (Serve は Gateway を loopback に保ち、Tailscale がアクセスを処理します)。 +- LAN にバインドする必要がある場合は、送信元 IP の厳密な許可リストに対してポートをファイアウォールで制限してください。広範にポートフォワードしないでください。 +- 認証なしの Gateway を `0.0.0.0` で公開しないでください。 ### UFW での Docker ポート公開 -VPS 上の Docker で OpenClaw を実行する場合、公開されたコンテナポート (`-p HOST:CONTAINER` または Compose `ports:`) は、ホストの `INPUT` ルールだけでなく、Docker の転送チェーンを通じてルーティングされることを覚えておいてください。 +VPS 上の Docker で OpenClaw を実行する場合、公開されたコンテナポート +(`-p HOST:CONTAINER` または Compose の `ports:`) は、ホストの `INPUT` ルールだけでなく、Docker の転送チェーン経由でルーティングされることを覚えておいてください。 -Docker トラフィックをファイアウォールポリシーと一致させるには、`DOCKER-USER` でルールを強制してください (このチェーンは Docker 自身の accept ルールより前に評価されます)。多くの現代的なディストリビューションでは、`iptables`/`ip6tables` は `iptables-nft` フロントエンドを使用し、これらのルールを nftables バックエンドにも適用します。 +Docker トラフィックをファイアウォールポリシーと一致させるには、 +`DOCKER-USER` でルールを適用してください (このチェーンは Docker 独自の accept ルールより前に評価されます)。 +多くの最新ディストリビューションでは、`iptables`/`ip6tables` は `iptables-nft` フロントエンドを使用し、 +それでもこれらのルールを nftables バックエンドに適用します。 最小限の許可リスト例 (IPv4): +__OC_I18N_900008__ +IPv6 には別のテーブルがあります。 +Docker IPv6 が有効な場合は、`/etc/ufw/after6.rules` に対応するポリシーを追加してください。 -```bash -# /etc/ufw/after.rules (append as its own *filter section) -*filter -:DOCKER-USER - [0:0] --A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN --A DOCKER-USER -s 127.0.0.0/8 -j RETURN --A DOCKER-USER -s 10.0.0.0/8 -j RETURN --A DOCKER-USER -s 172.16.0.0/12 -j RETURN --A DOCKER-USER -s 192.168.0.0/16 -j RETURN --A DOCKER-USER -s 100.64.0.0/10 -j RETURN --A DOCKER-USER -p tcp --dport 80 -j RETURN --A DOCKER-USER -p tcp --dport 443 -j RETURN --A DOCKER-USER -m conntrack --ctstate NEW -j DROP --A DOCKER-USER -j RETURN -COMMIT -``` +ドキュメントのスニペットでは、`eth0` のようなインターフェイス名をハードコードするのを避けてください。インターフェイス名は VPS イメージによって異なり (`ens3`、`enp*` など)、不一致があると拒否ルールが誤ってスキップされる可能性があります。 -IPv6 には別のテーブルがあります。Docker IPv6 が有効な場合は、`/etc/ufw/after6.rules` に一致するポリシーを追加してください。 - -ドキュメントのスニペットで `eth0` のようなインターフェイス名をハードコードすることは避けてください。インターフェイス名は VPS イメージによって異なり (`ens3`, `enp*` など)、不一致があると拒否ルールを意図せずスキップする可能性があります。 - -リロード後の簡易検証: - -```bash -ufw reload -iptables -S DOCKER-USER -ip6tables -S DOCKER-USER -nmap -sT -p 1-65535 --open -``` - -想定される外部ポートは、意図的に公開したものだけであるべきです (ほとんどのセットアップでは SSH + リバースプロキシポート)。 +再読み込み後のクイック検証: +__OC_I18N_900009__ +想定される外部ポートは、意図的に公開したものだけであるべきです (ほとんどの +セットアップでは SSH + リバースプロキシのポート)。 ### mDNS/Bonjour 検出 -Gateway は、ローカルデバイス検出のために mDNS (`_openclaw-gw._tcp`、ポート 5353) 経由で自身の存在をブロードキャストします。フルモードでは、運用上の詳細を公開する可能性がある TXT レコードが含まれます。 +Gateway は、ローカルデバイス検出のために mDNS (`_openclaw-gw._tcp`、ポート 5353) で自身の存在をブロードキャストします。フルモードでは、運用上の詳細を公開する可能性がある TXT レコードが含まれます: -- `cliPath`: CLI バイナリへの完全なファイルシステムパス（ユーザー名とインストール場所が明らかになる） -- `sshPort`: ホスト上で SSH が利用可能であることを通知する +- `cliPath`: CLI バイナリへの完全なファイルシステムパス（ユーザー名とインストール場所が明らかになります） +- `sshPort`: ホスト上で SSH が利用可能であることを通知します - `displayName`, `lanHost`: ホスト名情報 -**運用上のセキュリティ考慮事項:** インフラの詳細をブロードキャストすると、ローカルネットワーク上の誰にとっても偵察が容易になります。ファイルシステムパスや SSH の利用可否のような「無害」な情報でさえ、攻撃者が環境を把握する助けになります。 +**運用上のセキュリティ考慮事項:** インフラ詳細をブロードキャストすると、ローカルネットワーク上の誰でも偵察しやすくなります。ファイルシステムパスや SSH の可用性のような「無害」な情報でも、攻撃者が環境を把握する助けになります。 **推奨事項:** -1. **最小モード**（デフォルト、公開された Gateway に推奨）: mDNS ブロードキャストから機密フィールドを省略します。 - - ```json5 - { - discovery: { - mdns: { mode: "minimal" }, - }, - } - ``` - -2. **完全に無効化** ローカルデバイス探索が不要な場合: - - ```json5 - { - discovery: { - mdns: { mode: "off" }, - }, - } - ``` - +1. **最小モード**（デフォルト、公開されたゲートウェイに推奨）: mDNS ブロードキャストから機密フィールドを省略します。 +__OC_I18N_900010__ +2. **完全に無効化** ローカルデバイス検出が不要な場合: +__OC_I18N_900011__ 3. **フルモード**（オプトイン）: TXT レコードに `cliPath` + `sshPort` を含めます。 +__OC_I18N_900012__ +4. **環境変数**（代替）: 設定を変更せずに mDNS を無効化するには `OPENCLAW_DISABLE_BONJOUR=1` を設定します。 - ```json5 - { - discovery: { - mdns: { mode: "full" }, - }, - } - ``` - -4. **環境変数**（代替）: `OPENCLAW_DISABLE_BONJOUR=1` を設定して、設定変更なしで mDNS を無効化します。 - -最小モードでは、Gateway はデバイス探索に十分な情報（`role`, `gatewayPort`, `transport`）を引き続きブロードキャストしますが、`cliPath` と `sshPort` は省略します。CLI パス情報が必要なアプリは、代わりに認証済み WebSocket 接続経由で取得できます。 +最小モードでは、Gateway はデバイス検出に十分な情報（`role`, `gatewayPort`, `transport`）を引き続きブロードキャストしますが、`cliPath` と `sshPort` は省略します。CLI パス情報が必要なアプリは、代わりに認証済みの WebSocket 接続経由で取得できます。 ### Gateway WebSocket をロックダウンする（ローカル認証） -Gateway 認証は**デフォルトで必須**です。有効な Gateway 認証パスが設定されていない場合、 +Gateway 認証は**デフォルトで必須**です。有効なゲートウェイ認証パスが設定されていない場合、 Gateway は WebSocket 接続を拒否します（フェイルクローズ）。 -オンボーディングはデフォルトでトークンを生成するため（loopback の場合でも）、 +オンボーディングではデフォルトでトークンが生成されるため（loopback の場合でも）、 ローカルクライアントは認証する必要があります。 -トークンを設定して、**すべての** WS クライアントに認証を必須にします。 - -```json5 -{ - gateway: { - auth: { mode: "token", token: "your-token" }, - }, -} -``` - -Doctor はトークンを生成できます: `openclaw doctor --generate-gateway-token`。 +**すべての** WS クライアントに認証を必須にするには、トークンを設定します。 +__OC_I18N_900013__ +Doctor で生成できます: `openclaw doctor --generate-gateway-token`. -`gateway.remote.token` と `gateway.remote.password` はクライアントの認証情報ソースです。それ自体ではローカル WS アクセスを保護しません。ローカル呼び出しパスは、`gateway.auth.*` が未設定の場合にのみ `gateway.remote.*` をフォールバックとして使用できます。`gateway.auth.token` または `gateway.auth.password` が SecretRef 経由で明示的に設定されていて解決できない場合、解決はフェイルクローズします（リモートフォールバックによるマスクはありません）。 +`gateway.remote.token` と `gateway.remote.password` はクライアント認証情報のソースです。それら自体ではローカル WS アクセスを保護しません。ローカル呼び出しパスは、`gateway.auth.*` が未設定の場合にのみ `gateway.remote.*` をフォールバックとして使用できます。`gateway.auth.token` または `gateway.auth.password` が SecretRef 経由で明示的に設定され、解決できない場合、解決はフェイルクローズします（リモートフォールバックによるマスクはありません）。 -任意: `wss://` を使用する場合は `gateway.remote.tlsFingerprint` でリモート TLS をピン留めします。 -平文の `ws://` はデフォルトで loopback のみに限定されます。信頼済みのプライベートネットワーク -パスでは、非常時対応としてクライアントプロセスに +任意: `wss://` を使用する場合は `gateway.remote.tlsFingerprint` でリモート TLS を固定します。 +平文の `ws://` はデフォルトで loopback 専用です。信頼済みのプライベートネットワーク +パスでは、ブレークグラスとしてクライアントプロセスに `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` を設定します。これは意図的にプロセス環境のみであり、 `openclaw.json` の設定キーではありません。 -モバイルペアリングと Android の手動またはスキャン済み Gateway ルートは、より厳格です。 -クリアテキストは loopback では受け入れられますが、private-LAN、link-local、`.local`、および -ドットを含まないホスト名では、信頼済みプライベートネットワークのクリアテキストパスに明示的にオプトインしない限り TLS が必要です。 +モバイルペアリングと Android の手動またはスキャンされたゲートウェイルートはさらに厳格です。 +平文は loopback では受け入れられますが、プライベート LAN、リンクローカル、`.local`、および +ドットなしホスト名では、信頼済みプライベートネットワークの平文パスへ明示的にオプトインしない限り TLS が必要です。 -ローカルデバイスペアリング: +ローカルデバイスのペアリング: -- 同一ホストのクライアントを円滑に保つため、直接の local loopback 接続ではデバイスペアリングが自動承認されます。 -- OpenClaw には、信頼済み共有シークレットのヘルパーフロー向けに、狭いバックエンド/コンテナローカルの自己接続パスもあります。 -- 同一ホストの tailnet バインドを含む Tailnet と LAN 接続は、ペアリング上はリモートとして扱われ、引き続き承認が必要です。 -- loopback リクエスト上の転送ヘッダー証拠は、loopback ローカリティの資格を失わせます。メタデータアップグレードの自動承認は狭くスコープされています。両方のルールについては [Gateway ペアリング](/ja-JP/gateway/pairing) を参照してください。 +- デバイスペアリングは、同一ホストのクライアントをスムーズにするため、直接の local loopback 接続では自動承認されます。 +- OpenClaw には、信頼済み共有シークレットのヘルパーフロー向けに、狭く限定されたバックエンド/コンテナローカルの自己接続パスもあります。 +- 同一ホストの tailnet バインドを含む tailnet と LAN 接続は、ペアリングではリモートとして扱われ、引き続き承認が必要です。 +- loopback リクエスト上の転送ヘッダー証拠は、loopback のローカリティを無効にします。メタデータアップグレードの自動承認は狭くスコープされています。両方のルールについては [Gateway ペアリング](/gateway/pairing) を参照してください。 認証モード: -- `gateway.auth.mode: "token"`: 共有 bearer トークン（ほとんどの設定に推奨）。 +- `gateway.auth.mode: "token"`: 共有ベアラートークン（ほとんどのセットアップに推奨）。 - `gateway.auth.mode: "password"`: パスワード認証（env 経由での設定を推奨: `OPENCLAW_GATEWAY_PASSWORD`）。 -- `gateway.auth.mode: "trusted-proxy"`: ID 対応のリバースプロキシがユーザーを認証し、ヘッダー経由で ID を渡すことを信頼します（[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth) を参照）。 +- `gateway.auth.mode: "trusted-proxy"`: ID 対応リバースプロキシを信頼してユーザーを認証し、ヘッダー経由で ID を渡します（[信頼済みプロキシ認証](/gateway/trusted-proxy-auth) を参照）。 ローテーションチェックリスト（トークン/パスワード）: -1. 新しいシークレット（`gateway.auth.token` または `OPENCLAW_GATEWAY_PASSWORD`）を生成/設定します。 -2. Gateway を再起動します（または macOS アプリが Gateway を監督している場合は macOS アプリを再起動します）。 -3. すべてのリモートクライアントを更新します（Gateway を呼び出すマシン上の `gateway.remote.token` / `.password`）。 +1. 新しいシークレットを生成/設定します（`gateway.auth.token` または `OPENCLAW_GATEWAY_PASSWORD`）。 +2. Gateway を再起動します（または macOS アプリが Gateway を監視している場合は macOS アプリを再起動します）。 +3. リモートクライアントを更新します（Gateway に呼び出すマシン上の `gateway.remote.token` / `.password`）。 4. 古い認証情報では接続できなくなったことを確認します。 -### Tailscale Serve ID ヘッダー +### Tailscale Serve の ID ヘッダー -`gateway.auth.allowTailscale` が `true` の場合（Serve のデフォルト）、OpenClaw は Control -UI/WebSocket 認証に Tailscale Serve の ID ヘッダー（`tailscale-user-login`）を受け入れます。OpenClaw は、ローカル Tailscale デーモン（`tailscale whois`）を通じて -`x-forwarded-for` アドレスを解決し、それをヘッダーと照合することで ID を検証します。これは、Tailscale によって注入される -`x-forwarded-for`、`x-forwarded-proto`、`x-forwarded-host` を含み、loopback に到達したリクエストに対してのみ発動します。 -この非同期 ID チェックパスでは、同じ `{scope, ip}` に対する失敗試行は、リミッターが失敗を記録する前に直列化されます。そのため、1 つの Serve クライアントからの同時の不正な再試行は、2 つの単純な不一致として競合して通過するのではなく、2 回目の試行を即座にロックアウトできます。 -HTTP API エンドポイント（例: `/v1/*`、`/tools/invoke`、`/api/channels/*`）は -Tailscale ID ヘッダー認証を使用しません。これらは引き続き Gateway に設定された -HTTP 認証モードに従います。 +`gateway.auth.allowTailscale` が `true` の場合（Serve のデフォルト）、OpenClaw は +Control UI/WebSocket 認証に Tailscale Serve の ID ヘッダー（`tailscale-user-login`）を受け入れます。OpenClaw は、ローカル Tailscale デーモン（`tailscale whois`）を通じて +`x-forwarded-for` アドレスを解決し、それをヘッダーと照合することで ID を検証します。これは loopback に到達し、Tailscale によって注入される +`x-forwarded-for`、`x-forwarded-proto`、`x-forwarded-host` を含むリクエストに対してのみ発動します。 +この非同期 ID チェックパスでは、同じ `{scope, ip}` に対する失敗した試行は、リミッターが失敗を記録する前に直列化されます。そのため、1 つの Serve クライアントからの同時の不正な再試行は、単純な不一致として 2 回すり抜ける競合になるのではなく、2 回目の試行を即座にロックアウトできます。 +HTTP API エンドポイント（たとえば `/v1/*`、`/tools/invoke`、`/api/channels/*`）は +Tailscale ID ヘッダー認証を使用しません。これらは引き続き、ゲートウェイに設定された HTTP 認証モードに従います。 -重要な境界に関する注意: +重要な境界メモ: -- Gateway HTTP bearer 認証は、実質的に全か無かのオペレーターアクセスです。 -- `/v1/chat/completions`、`/v1/responses`、または `/api/channels/*` を呼び出せる認証情報は、その Gateway に対するフルアクセスのオペレーターシークレットとして扱ってください。 -- OpenAI 互換 HTTP サーフェスでは、共有シークレット bearer 認証により、完全なデフォルトのオペレータースコープ（`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`）と agent ターンの所有者セマンティクスが復元されます。より狭い `x-openclaw-scopes` 値は、その共有シークレットパスを縮小しません。 -- HTTP 上のリクエスト単位のスコープセマンティクスは、信頼済みプロキシ認証やプライベート ingress 上の `gateway.auth.mode="none"` など、ID を持つモードからリクエストが来る場合にのみ適用されます。 -- これらの ID を持つモードでは、`x-openclaw-scopes` を省略すると通常のオペレーターのデフォルトスコープセットにフォールバックします。より狭いスコープセットが必要な場合は、ヘッダーを明示的に送信してください。 -- `/tools/invoke` は同じ共有シークレットルールに従います。トークン/パスワードの bearer 認証もそこでフルオペレーターアクセスとして扱われますが、ID を持つモードでは引き続き宣言されたスコープが尊重されます。 -- これらの認証情報を信頼できない呼び出し元と共有しないでください。信頼境界ごとに別々の Gateway を使うことを推奨します。 +- Gateway HTTP ベアラー認証は、実質的に全権限か無権限かのオペレーターアクセスです。 +- `/v1/chat/completions`、`/v1/responses`、または `/api/channels/*` を呼び出せる認証情報は、そのゲートウェイのフルアクセスオペレーターシークレットとして扱ってください。 +- OpenAI 互換 HTTP サーフェスでは、共有シークレットのベアラー認証により、完全なデフォルトオペレータースコープ（`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`）とエージェントターンの所有者セマンティクスが復元されます。より狭い `x-openclaw-scopes` 値でも、その共有シークレットパスは縮小されません。 +- HTTP 上のリクエストごとのスコープセマンティクスは、信頼済みプロキシ認証やプライベート ingress 上の `gateway.auth.mode="none"` のような ID 付きモードからリクエストが来る場合にのみ適用されます。 +- これらの ID 付きモードでは、`x-openclaw-scopes` を省略すると通常のオペレーターのデフォルトスコープセットにフォールバックします。より狭いスコープセットが必要な場合は、ヘッダーを明示的に送信してください。 +- `/tools/invoke` は同じ共有シークレットルールに従います。トークン/パスワードのベアラー認証はそこでもフルオペレーターアクセスとして扱われますが、ID 付きモードでは引き続き宣言されたスコープが尊重されます。 +- これらの認証情報を信頼できない呼び出し元と共有しないでください。信頼境界ごとに個別のゲートウェイを用意することを推奨します。 -**信頼の前提:** トークンなしの Serve 認証は、Gateway ホストが信頼済みであることを前提とします。 -これを、敵対的な同一ホストプロセスに対する保護として扱わないでください。信頼できない -ローカルコードが Gateway ホスト上で実行される可能性がある場合は、`gateway.auth.allowTailscale` +**信頼の前提:** トークンレス Serve 認証は、ゲートウェイホストが信頼済みであることを前提とします。 +敵対的な同一ホストプロセスからの保護として扱わないでください。信頼できない +ローカルコードがゲートウェイホスト上で実行される可能性がある場合は、`gateway.auth.allowTailscale` を無効化し、`gateway.auth.mode: "token"` または `"password"` による明示的な共有シークレット認証を必須にしてください。 -**セキュリティルール:** これらのヘッダーを独自のリバースプロキシから転送しないでください。Gateway の前で TLS を終端するかプロキシする場合は、 -`gateway.auth.allowTailscale` を無効化し、共有シークレット認証（`gateway.auth.mode: -"token"` または `"password"`）または [信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth) +**セキュリティルール:** これらのヘッダーを自分のリバースプロキシから転送しないでください。ゲートウェイの手前で +TLS を終端する、またはプロキシする場合は、`gateway.auth.allowTailscale` を無効化し、 +共有シークレット認証（`gateway.auth.mode: +"token"` または `"password"`）または [信頼済みプロキシ認証](/gateway/trusted-proxy-auth) を代わりに使用してください。 信頼済みプロキシ: -- Gateway の前で TLS を終端する場合は、`gateway.trustedProxies` をプロキシの IP に設定します。 -- OpenClaw は、それらの IP からの `x-forwarded-for`（または `x-real-ip`）を信頼し、ローカルペアリングチェックと HTTP 認証/ローカルチェックのためのクライアント IP を判定します。 -- プロキシが `x-forwarded-for` を**上書き**し、Gateway ポートへの直接アクセスをブロックしていることを確認してください。 +- Gateway の手前で TLS を終端する場合は、`gateway.trustedProxies` をプロキシ IP に設定します。 +- OpenClaw は、それらの IP からの `x-forwarded-for`（または `x-real-ip`）を信頼して、ローカルペアリングチェックと HTTP 認証/ローカルチェックのためのクライアント IP を判断します。 +- プロキシが `x-forwarded-for` を**上書き**し、Gateway ポートへの直接アクセスをブロックすることを確認してください。 -[Tailscale](/ja-JP/gateway/tailscale) と [Web 概要](/ja-JP/web) を参照してください。 +[Tailscale](/gateway/tailscale) と [Web 概要](/web) を参照してください。 -### node host 経由のブラウザー制御（推奨） +### ノードホスト経由のブラウザー制御（推奨） -Gateway がリモートにあり、ブラウザーが別のマシンで動作している場合は、ブラウザーマシン上で **node host** -を実行し、Gateway にブラウザー操作をプロキシさせます（[ブラウザーツール](/ja-JP/tools/browser) を参照）。 -node ペアリングは管理者アクセスのように扱ってください。 +Gateway がリモートにあり、ブラウザーが別のマシンで動作している場合は、ブラウザーマシン上で +**ノードホスト**を実行し、Gateway にブラウザーアクションをプロキシさせます（[ブラウザーツール](/tools/browser) を参照）。 +ノードペアリングは管理者アクセスのように扱ってください。 推奨パターン: -- Gateway と node host を同じ tailnet（Tailscale）上に保ちます。 -- node を意図的にペアリングします。ブラウザープロキシルーティングが不要な場合は無効化します。 +- Gateway とノードホストを同じ tailnet（Tailscale）上に保ちます。 +- ノードを意図的にペアリングします。不要な場合はブラウザープロキシルーティングを無効化します。 -避けること: +避けるべきこと: -- relay/control ポートを LAN または公開インターネットに公開すること。 -- ブラウザー制御エンドポイントに Tailscale Funnel を使うこと（公開露出）。 +- リレー/制御ポートを LAN またはパブリックインターネットに公開する。 +- ブラウザー制御エンドポイントに Tailscale Funnel を使用する（公開露出）。 ### ディスク上のシークレット -`~/.openclaw/`（または `$OPENCLAW_STATE_DIR/`）配下のものはすべて、シークレットまたはプライベートデータを含む可能性があると想定してください。 +`~/.openclaw/`（または `$OPENCLAW_STATE_DIR/`）配下のものは、すべてシークレットまたはプライベートデータを含む可能性があると想定してください。 -- `openclaw.json`: 設定にはトークン（Gateway、リモート Gateway）、プロバイダー設定、許可リストが含まれる場合があります。 -- `credentials/**`: チャンネル認証情報（例: WhatsApp 認証情報）、ペアリング許可リスト、レガシー OAuth インポート。 +- `openclaw.json`: 設定にはトークン（ゲートウェイ、リモートゲートウェイ）、プロバイダー設定、許可リストが含まれる可能性があります。 +- `credentials/**`: チャネル認証情報（例: WhatsApp 認証情報）、ペアリング許可リスト、レガシー OAuth インポート。 - `agents//agent/auth-profiles.json`: API キー、トークンプロファイル、OAuth トークン、および任意の `keyRef`/`tokenRef`。 -- `secrets.json`（任意）: `file` SecretRef プロバイダー（`secrets.providers`）で使用されるファイルバックのシークレットペイロード。 -- `agents//agent/auth.json`: レガシー互換ファイル。静的な `api_key` エントリは検出時に削除されます。 -- `agents//sessions/**`: セッショントランスクリプト（`*.jsonl`）+ プライベートメッセージやツール出力を含む可能性があるルーティングメタデータ（`sessions.json`）。 -- バンドル済み Plugin パッケージ: インストール済み Plugin（およびその `node_modules/`）。 -- `sandboxes/**`: ツールサンドボックスのワークスペース。サンドボックス内で読み書きしたファイルのコピーが蓄積されることがあります。 +- `agents//agent/codex-home/**`: エージェントごとの Codex アプリサーバーアカウント、設定、Skills、plugins、ネイティブスレッド状態、診断。 +- `secrets.json`（任意）: `file` SecretRef プロバイダー（`secrets.providers`）で使用されるファイルバックシークレットペイロード。 +- `agents//agent/auth.json`: レガシー互換ファイル。静的な `api_key` エントリは検出時にスクラブされます。 +- `agents//sessions/**`: プライベートメッセージやツール出力を含む可能性があるセッショントランスクリプト（`*.jsonl`）+ ルーティングメタデータ（`sessions.json`）。 +- バンドルされた plugin パッケージ: インストール済み plugins（およびそれらの `node_modules/`）。 +- `sandboxes/**`: ツールサンドボックスワークスペース。サンドボックス内で読み書きしたファイルのコピーが蓄積される可能性があります。 強化のヒント: -- 権限を厳しく保ちます（ディレクトリは `700`、ファイルは `600`）。 -- Gateway ホストでフルディスク暗号化を使用します。 -- ホストを共有している場合は、Gateway 専用の OS ユーザーアカウントを使うことを推奨します。 +- 権限を厳格に保ちます（ディレクトリは `700`、ファイルは `600`）。 +- ゲートウェイホストでフルディスク暗号化を使用します。 +- ホストが共有されている場合は、Gateway 専用の OS ユーザーアカウントを推奨します。 ### ワークスペースの `.env` ファイル -OpenClaw は agent とツールのためにワークスペースローカルの `.env` ファイルを読み込みますが、それらのファイルが Gateway ランタイム制御を静かに上書きすることは決して許可しません。 +OpenClaw はエージェントとツール向けにワークスペースローカルの `.env` ファイルを読み込みますが、それらのファイルがゲートウェイランタイム制御を黙って上書きすることは決して許可しません。 - `OPENCLAW_*` で始まるキーは、信頼できないワークスペース `.env` ファイルからブロックされます。 -- Matrix、Mattermost、IRC、Synology Chat のチャンネルエンドポイント設定も、ワークスペース `.env` による上書きからブロックされます。そのため、クローンされたワークスペースが、ローカルエンドポイント設定を通じてバンドル済みコネクタートラフィックをリダイレクトすることはできません。エンドポイント env キー（`MATRIX_HOMESERVER`、`MATTERMOST_URL`、`IRC_HOST`、`SYNOLOGY_CHAT_INCOMING_URL` など）は、ワークスペースから読み込まれる `.env` ではなく、Gateway プロセス環境または `env.shellEnv` から来る必要があります。 -- ブロックはフェイルクローズです。将来のリリースで追加された新しいランタイム制御変数は、チェックインされた `.env` や攻撃者が提供した `.env` から継承されることはありません。そのキーは無視され、Gateway は自身の値を保持します。 -- 信頼済みプロセス/OS 環境変数（Gateway 自身のシェル、launchd/systemd ユニット、アプリバンドル）は引き続き適用されます。これは `.env` ファイルの読み込みのみを制約します。 +- Matrix、Mattermost、IRC、Synology Chat のチャネルエンドポイント設定も、ワークスペース `.env` の上書きからブロックされます。そのため、クローンされたワークスペースがローカルエンドポイント設定を通じてバンドル済みコネクタートラフィックをリダイレクトすることはできません。エンドポイント env キー（`MATRIX_HOMESERVER`、`MATTERMOST_URL`、`IRC_HOST`、`SYNOLOGY_CHAT_INCOMING_URL` など）は、ワークスペースから読み込まれた `.env` ではなく、ゲートウェイプロセス環境または `env.shellEnv` から来る必要があります。 +- ブロックはフェイルクローズです。将来のリリースで新しいランタイム制御変数が追加されても、チェックインされた `.env` や攻撃者が提供した `.env` から継承されることはありません。そのキーは無視され、ゲートウェイは自身の値を保持します。 +- 信頼済みのプロセス/OS 環境変数（ゲートウェイ自身のシェル、launchd/systemd ユニット、アプリバンドル）は引き続き適用されます。これは `.env` ファイルの読み込みだけを制約します。 -理由: ワークスペース `.env` ファイルは agent コードの隣に置かれることが多く、誤ってコミットされたり、ツールによって書き込まれたりします。`OPENCLAW_*` プレフィックス全体をブロックすることで、後から新しい `OPENCLAW_*` フラグを追加しても、ワークスペース状態からの静かな継承へ退行することはありません。 +理由: ワークスペースの `.env` ファイルは、エージェントコードの隣に置かれることが多く、誤ってコミットされたり、ツールによって書き込まれたりします。`OPENCLAW_*` プレフィックス全体をブロックすることで、後から新しい `OPENCLAW_*` フラグを追加しても、ワークスペース状態から黙って継承される退行が起きることはありません。 -### ログとトランスクリプト（墨消しと保持） +### ログとトランスクリプト（リダクションと保持） -アクセス制御が正しくても、ログとトランスクリプトは機密情報を漏らす可能性があります。 +アクセス制御が正しくても、ログとトランスクリプトから機密情報が漏れる可能性があります。 -- Gateway ログには、ツール概要、エラー、URL が含まれる場合があります。 -- セッショントランスクリプトには、貼り付けられたシークレット、ファイル内容、コマンド出力、リンクが含まれる場合があります。 +- Gateway ログには、ツール概要、エラー、URL が含まれる可能性があります。 +- セッショントランスクリプトには、貼り付けられたシークレット、ファイル内容、コマンド出力、リンクが含まれる可能性があります。 推奨事項: -- ログとトランスクリプトの墨消しを有効のままにします（`logging.redactSensitive: "tools"`、デフォルト）。 -- `logging.redactPatterns` を使用して、環境に合わせたカスタムパターン（トークン、ホスト名、内部 URL）を追加します。 -- 診断情報を共有する場合は、生ログではなく `openclaw status --all`（貼り付け可能、シークレットは墨消し済み）を推奨します。 +- ログとトランスクリプトのリダクションを有効に保ちます（`logging.redactSensitive: "tools"`、デフォルト）。 +- `logging.redactPatterns` を通じて、環境に合わせたカスタムパターン（トークン、ホスト名、内部 URL）を追加します。 +- 診断を共有するときは、生ログではなく `openclaw status --all`（貼り付け可能、シークレットはリダクション済み）を推奨します。 - 長期保持が不要な場合は、古いセッショントランスクリプトとログファイルを削除します。 -詳細: [ロギング](/ja-JP/gateway/logging) - -### DM: デフォルトでペアリング - -```json5 -{ - channels: { whatsapp: { dmPolicy: "pairing" } }, -} -``` +詳細: [ロギング](/gateway/logging) +### DM: デフォルトではペアリング +__OC_I18N_900014__ ### グループ: すべての場所でメンションを必須にする +__OC_I18N_900015__ +グループチャットでは、明示的にメンションされた場合にのみ応答します。 -```json -{ - "channels": { - "whatsapp": { - "groups": { - "*": { "requireMention": true } - } - } - }, - "agents": { - "list": [ - { - "id": "main", - "groupChat": { "mentionPatterns": ["@openclaw", "@mybot"] } - } - ] - } -} -``` +### 番号を分ける（WhatsApp、Signal、Telegram） -グループチャットでは、明示的にメンションされた場合のみ応答します。 - -### 別の番号（WhatsApp、Signal、Telegram） - -電話番号ベースのチャンネルでは、個人用とは別の電話番号で AI を実行することを検討してください。 +電話番号ベースのチャンネルでは、個人用とは別の電話番号で AI を動かすことを検討してください。 - 個人用番号: 会話は非公開のままです -- ボット用番号: AI が適切な境界を保ちながらこれらを処理します +- ボット用番号: 適切な境界を設けて、AI がこれらを処理します ### 読み取り専用モード（サンドボックスとツール経由） -次を組み合わせて、読み取り専用プロファイルを構築できます: +次を組み合わせて、読み取り専用プロファイルを構築できます。 -- `agents.defaults.sandbox.workspaceAccess: "ro"`（またはワークスペースアクセスなしの場合は `"none"`） -- `write`、`edit`、`apply_patch`、`exec`、`process` などをブロックするツールの許可/拒否リスト +- `agents.defaults.sandbox.workspaceAccess: "ro"`（ワークスペースアクセスなしの場合は `"none"`） +- `write`、`edit`、`apply_patch`、`exec`、`process` などをブロックするツール許可/拒否リスト 追加の強化オプション: -- `tools.exec.applyPatch.workspaceOnly: true`（既定）: サンドボックス化がオフの場合でも、`apply_patch` がワークスペースディレクトリ外に書き込み/削除できないようにします。`apply_patch` に意図的にワークスペース外のファイルを触らせたい場合にのみ `false` に設定してください。 -- `tools.fs.workspaceOnly: true`（任意）: `read`/`write`/`edit`/`apply_patch` パスと、ネイティブプロンプト画像の自動読み込みパスをワークスペースディレクトリに制限します（現在絶対パスを許可していて、単一のガードレールが必要な場合に便利です）。 -- ファイルシステムルートは狭く保ってください: エージェントワークスペース/サンドボックスワークスペースにホームディレクトリのような広いルートを避けてください。広いルートは、機密性の高いローカルファイル（たとえば `~/.openclaw` 配下の状態/設定）をファイルシステムツールに露出させる可能性があります。 +- `tools.exec.applyPatch.workspaceOnly: true`（デフォルト）: サンドボックスがオフの場合でも、`apply_patch` がワークスペースディレクトリの外に書き込んだり削除したりできないようにします。`apply_patch` が意図的にワークスペース外のファイルに触れる必要がある場合にのみ `false` に設定してください。 +- `tools.fs.workspaceOnly: true`（任意）: `read`/`write`/`edit`/`apply_patch` のパスと、ネイティブプロンプト画像の自動読み込みパスをワークスペースディレクトリに制限します（現在絶対パスを許可しており、単一のガードレールが欲しい場合に便利です）。 +- ファイルシステムのルートは狭く保ってください: エージェントワークスペース/サンドボックスワークスペースに、ホームディレクトリのような広いルートを使うことは避けてください。広いルートは、機密性の高いローカルファイル（たとえば `~/.openclaw` 配下の状態/設定）をファイルシステムツールに露出させる可能性があります。 -### 安全なベースライン（コピー/貼り付け） +### セキュアなベースライン（コピー/貼り付け） -Gateway を非公開に保ち、DM ペアリングを必須にし、常時稼働のグループボットを避ける一つの「安全な既定」設定: +Gateway を非公開に保ち、DM ペアリングを必須にし、常時稼働のグループボットを避ける「安全なデフォルト」設定の一例です。 +__OC_I18N_900016__ +ツール実行も「デフォルトでより安全」にしたい場合は、オーナー以外のエージェントに対してサンドボックスを追加し、危険なツールを拒否してください（下の「エージェントごとのアクセスプロファイル」の例を参照）。 -```json5 -{ - gateway: { - mode: "local", - bind: "loopback", - port: 18789, - auth: { mode: "token", token: "your-long-random-token" }, - }, - channels: { - whatsapp: { - dmPolicy: "pairing", - groups: { "*": { requireMention: true } }, - }, - }, -} -``` - -ツール実行も「既定でより安全」にしたい場合は、非所有者エージェント向けにサンドボックスと危険なツールの拒否を追加します（下の「エージェントごとのアクセスプロファイル」の例を参照）。 - -チャット駆動のエージェントターン向けの組み込みベースライン: 非所有者の送信者は `cron` または `gateway` ツールを使用できません。 +チャット駆動のエージェントターン向けの組み込みベースライン: オーナー以外の送信者は `cron` または `gateway` ツールを使用できません。 ## サンドボックス化（推奨） -専用ドキュメント: [サンドボックス化](/ja-JP/gateway/sandboxing) +専用ドキュメント: [サンドボックス化](/gateway/sandboxing) 相互補完的な 2 つのアプローチ: -- **Gateway 全体を Docker で実行**（コンテナ境界）: [Docker](/ja-JP/install/docker) -- **ツールサンドボックス**（`agents.defaults.sandbox`、ホスト Gateway + サンドボックスで隔離されたツール。Docker が既定のバックエンド）: [サンドボックス化](/ja-JP/gateway/sandboxing) +- **Gateway 全体を Docker で実行する**（コンテナ境界）: [Docker](/install/docker) +- **ツールサンドボックス**（`agents.defaults.sandbox`、ホスト Gateway + サンドボックスで分離されたツール。Docker がデフォルトバックエンド）: [サンドボックス化](/gateway/sandboxing) -エージェント間アクセスを防ぐには、`agents.defaults.sandbox.scope` を `"agent"`（既定）のままにするか、より厳密なセッションごとの隔離には `"session"` にしてください。`scope: "shared"` は単一のコンテナまたはワークスペースを使用します。 +エージェント間アクセスを防ぐには、`agents.defaults.sandbox.scope` を `"agent"`（デフォルト）のままにするか、より厳密なセッション単位の分離には `"session"` にしてください。`scope: "shared"` は単一のコンテナまたはワークスペースを使用します。 -サンドボックス内のエージェントワークスペースアクセスも検討してください: +サンドボックス内でのエージェントワークスペースアクセスも検討してください。 -- `agents.defaults.sandbox.workspaceAccess: "none"`（既定）はエージェントワークスペースを立ち入り禁止にします。ツールは `~/.openclaw/sandboxes` 配下のサンドボックスワークスペースに対して実行されます +- `agents.defaults.sandbox.workspaceAccess: "none"`（デフォルト）はエージェントワークスペースをアクセス不可にし、ツールは `~/.openclaw/sandboxes` 配下のサンドボックスワークスペースに対して実行されます - `agents.defaults.sandbox.workspaceAccess: "ro"` はエージェントワークスペースを `/agent` に読み取り専用でマウントします（`write`/`edit`/`apply_patch` を無効化） -- `agents.defaults.sandbox.workspaceAccess: "rw"` はエージェントワークスペースを `/workspace` に読み取り/書き込みでマウントします -- 追加の `sandbox.docker.binds` は、正規化および正準化されたソースパスに対して検証されます。親シンボリックリンクのトリックや正準的なホームエイリアスも、`/etc`、`/var/run`、OS ホーム配下の認証情報ディレクトリなどのブロック対象ルートに解決される場合はフェイルクローズします。 +- `agents.defaults.sandbox.workspaceAccess: "rw"` はエージェントワークスペースを `/workspace` に読み書き可能でマウントします +- 追加の `sandbox.docker.binds` は、正規化および正準化されたソースパスに対して検証されます。親シンボリックリンクのトリックや正準的なホーム別名も、`/etc`、`/var/run`、または OS ホーム配下の認証情報ディレクトリなど、ブロック対象ルートに解決される場合はフェイルクローズします。 -`tools.elevated` は、サンドボックス外で exec を実行するグローバルなベースラインのエスケープハッチです。有効なホストは既定では `gateway`、exec ターゲットが `node` に設定されている場合は `node` です。`tools.elevated.allowFrom` は厳しく保ち、見知らぬ相手には有効にしないでください。`agents.list[].tools.elevated` により、エージェントごとに elevated をさらに制限できます。[Elevated モード](/ja-JP/tools/elevated)を参照してください。 +`tools.elevated` は、サンドボックス外で exec を実行するグローバルなベースラインのエスケープハッチです。有効なホストはデフォルトで `gateway`、または exec ターゲットが `node` に設定されている場合は `node` です。`tools.elevated.allowFrom` は厳しく保ち、見知らぬ相手には有効にしないでください。`agents.list[].tools.elevated` を使うと、エージェントごとに elevated をさらに制限できます。[Elevated mode](/tools/elevated) を参照してください。 ### サブエージェント委任のガードレール -セッションツールを許可する場合、委任されたサブエージェント実行も別の境界判断として扱ってください: +セッションツールを許可する場合は、委任されたサブエージェント実行を別の境界判断として扱ってください。 - エージェントが本当に委任を必要としない限り、`sessions_spawn` を拒否してください。 - `agents.defaults.subagents.allowAgents` と、エージェントごとの `agents.list[].subagents.allowAgents` オーバーライドは、既知の安全なターゲットエージェントに制限してください。 -- サンドボックス化されたままである必要があるワークフローでは、`sandbox: "require"` で `sessions_spawn` を呼び出してください（既定は `inherit`）。 +- サンドボックス内に留める必要があるワークフローでは、`sessions_spawn` を `sandbox: "require"`（デフォルトは `inherit`）で呼び出してください。 - `sandbox: "require"` は、ターゲットの子ランタイムがサンドボックス化されていない場合に即座に失敗します。 ## ブラウザ制御のリスク ブラウザ制御を有効にすると、モデルは実際のブラウザを操作できるようになります。 -そのブラウザプロファイルにすでにログイン済みセッションが含まれている場合、モデルは -それらのアカウントとデータにアクセスできます。ブラウザプロファイルは**機密状態**として扱ってください: +そのブラウザプロファイルにログイン済みセッションがすでに含まれている場合、モデルは +それらのアカウントとデータにアクセスできます。ブラウザプロファイルは **機密状態** として扱ってください。 -- エージェント専用プロファイル（既定の `openclaw` プロファイル）を優先してください。 -- エージェントに個人の日常利用プロファイルを指させないでください。 +- エージェント専用プロファイル（デフォルトの `openclaw` プロファイル）を推奨します。 +- エージェントに個人用の日常使用プロファイルを指させることは避けてください。 - 信頼していない限り、サンドボックス化されたエージェントではホストブラウザ制御を無効のままにしてください。 -- スタンドアロンの loopback ブラウザ制御 API は共有シークレット認証 - （Gateway トークン bearer 認証または Gateway パスワード）のみを尊重します。trusted-proxy や Tailscale Serve の ID ヘッダーは使用しません。 -- ブラウザのダウンロードは信頼できない入力として扱ってください。隔離されたダウンロードディレクトリを優先してください。 +- スタンドアロンの loopback ブラウザ制御 API は、共有シークレット認証 + （Gateway トークンベアラー認証または Gateway パスワード）のみを尊重します。trusted-proxy または Tailscale Serve の ID ヘッダーは使用しません。 +- ブラウザのダウンロードは信頼できない入力として扱い、分離されたダウンロードディレクトリを推奨します。 - 可能であれば、エージェントプロファイルでブラウザ同期/パスワードマネージャーを無効にしてください（影響範囲を減らします）。 -- リモート Gateway では、「ブラウザ制御」はそのプロファイルが到達できるものへの「オペレーターアクセス」と同等だと想定してください。 -- Gateway と node ホストは tailnet のみにしてください。ブラウザ制御ポートを LAN や公開インターネットに公開しないでください。 +- リモート Gateway では、「ブラウザ制御」は、そのプロファイルが到達できるものへの「オペレーターアクセス」と同等だと想定してください。 +- Gateway とノードホストは tailnet 専用に保ち、ブラウザ制御ポートを LAN や公開インターネットに露出しないでください。 - 不要な場合はブラウザプロキシルーティングを無効にしてください（`gateway.nodes.browser.mode="off"`）。 -- Chrome MCP の既存セッションモードは「より安全」では**ありません**。そのホストの Chrome プロファイルが到達できるものに、あなたとして作用できます。 +- Chrome MCP の既存セッションモードは「より安全」**ではありません**。そのホストの Chrome プロファイルが到達できる範囲で、あなたとして動作できます。 -### ブラウザ SSRF ポリシー（既定で厳格） +### ブラウザ SSRF ポリシー（デフォルトで厳格） -OpenClaw のブラウザナビゲーションポリシーは既定で厳格です: 明示的にオプトインしない限り、プライベート/内部宛先はブロックされたままです。 +OpenClaw のブラウザナビゲーションポリシーはデフォルトで厳格です。明示的にオプトインしない限り、プライベート/内部宛先はブロックされたままです。 -- 既定: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定のため、ブラウザナビゲーションはプライベート/内部/特殊用途の宛先をブロックし続けます。 -- レガシーエイリアス: `browser.ssrfPolicy.allowPrivateNetwork` は互換性のため現在も受け付けられます。 -- オプトインモード: プライベート/内部/特殊用途の宛先を許可するには、`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` を設定します。 -- 厳格モードでは、明示的な例外として `hostnameAllowlist`（`*.example.com` のようなパターン）と `allowedHostnames`（`localhost` のようなブロック対象名を含む正確なホスト例外）を使用します。 -- リダイレクトベースのピボットを減らすため、ナビゲーションはリクエスト前にチェックされ、ナビゲーション後の最終 `http(s)` URL でベストエフォートにより再チェックされます。 +- デフォルト: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` は未設定のため、ブラウザナビゲーションはプライベート/内部/特殊用途の宛先をブロックし続けます。 +- レガシー別名: `browser.ssrfPolicy.allowPrivateNetwork` は互換性のため引き続き受け入れられます。 +- オプトインモード: プライベート/内部/特殊用途の宛先を許可するには、`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` を設定してください。 +- 厳格モードでは、明示的な例外として `hostnameAllowlist`（`*.example.com` のようなパターン）と `allowedHostnames`（`localhost` のようなブロック対象名を含む、正確なホスト例外）を使用します。 +- リダイレクトベースのピボットを減らすため、ナビゲーションはリクエスト前にチェックされ、ナビゲーション後の最終 `http(s)` URL でもベストエフォートで再チェックされます。 厳格ポリシーの例: - -```json5 -{ - browser: { - ssrfPolicy: { - dangerouslyAllowPrivateNetwork: false, - hostnameAllowlist: ["*.example.com", "example.com"], - allowedHostnames: ["localhost"], - }, - }, -} -``` - +__OC_I18N_900017__ ## エージェントごとのアクセスプロファイル（マルチエージェント） -マルチエージェントルーティングでは、各エージェントが独自のサンドボックス + ツールポリシーを持てます: -これを使用して、エージェントごとに**フルアクセス**、**読み取り専用**、または**アクセスなし**を付与します。 -詳細と優先順位ルールは [マルチエージェントのサンドボックスとツール](/ja-JP/tools/multi-agent-sandbox-tools) を参照してください。 +マルチエージェントルーティングでは、各エージェントに独自のサンドボックス + ツールポリシーを持たせることができます。 +これを使って、エージェントごとに **フルアクセス**、**読み取り専用**、または **アクセスなし** を付与してください。 +詳細と優先順位ルールについては、[マルチエージェントのサンドボックスとツール](/tools/multi-agent-sandbox-tools) を参照してください。 一般的なユースケース: @@ -1117,162 +1024,65 @@ OpenClaw のブラウザナビゲーションポリシーは既定で厳格で - 公開エージェント: サンドボックス化 + ファイルシステム/シェルツールなし ### 例: フルアクセス（サンドボックスなし） - -```json5 -{ - agents: { - list: [ - { - id: "personal", - workspace: "~/.openclaw/workspace-personal", - sandbox: { mode: "off" }, - }, - ], - }, -} -``` - +__OC_I18N_900018__ ### 例: 読み取り専用ツール + 読み取り専用ワークスペース - -```json5 -{ - agents: { - list: [ - { - id: "family", - workspace: "~/.openclaw/workspace-family", - sandbox: { - mode: "all", - scope: "agent", - workspaceAccess: "ro", - }, - tools: { - allow: ["read"], - deny: ["write", "edit", "apply_patch", "exec", "process", "browser"], - }, - }, - ], - }, -} -``` - +__OC_I18N_900019__ ### 例: ファイルシステム/シェルアクセスなし（プロバイダーメッセージングは許可） - -```json5 -{ - agents: { - list: [ - { - id: "public", - workspace: "~/.openclaw/workspace-public", - sandbox: { - mode: "all", - scope: "agent", - workspaceAccess: "none", - }, - // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools - // to the current session + spawned subagent sessions, but you can clamp further if needed. - // See `tools.sessions.visibility` in the configuration reference. - tools: { - sessions: { visibility: "tree" }, // self | tree | agent | all - allow: [ - "sessions_list", - "sessions_history", - "sessions_send", - "sessions_spawn", - "session_status", - "whatsapp", - "telegram", - "slack", - "discord", - ], - deny: [ - "read", - "write", - "edit", - "apply_patch", - "exec", - "process", - "browser", - "canvas", - "nodes", - "cron", - "gateway", - "image", - ], - }, - }, - ], - }, -} -``` - +__OC_I18N_900020__ ## インシデント対応 -AI が問題のある動作をした場合: +AI が悪いことをした場合: ### 封じ込め -1. **停止する:** macOS アプリ（Gateway を監視している場合）を停止するか、`openclaw gateway` プロセスを終了します。 -2. **露出を閉じる:** 何が起きたか理解するまで、`gateway.bind: "loopback"` を設定します（または Tailscale Funnel/Serve を無効にします）。 -3. **アクセスを凍結する:** リスクのある DM/グループを `dmPolicy: "disabled"` に切り替えるかメンション必須にし、`"*"` の全許可エントリがある場合は削除します。 +1. **停止する:** macOS アプリ（Gateway を監督している場合）を停止するか、`openclaw gateway` プロセスを終了します。 +2. **露出を閉じる:** 何が起きたかを理解するまで、`gateway.bind: "loopback"` を設定します（または Tailscale Funnel/Serve を無効にします）。 +3. **アクセスを凍結する:** リスクの高い DM/グループを `dmPolicy: "disabled"` / メンション必須に切り替え、`"*"` の全許可エントリがある場合は削除します。 ### ローテーション（シークレットが漏えいした場合は侵害を想定） -1. Gateway 認証（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）をローテーションし、再起動します。 -2. Gateway を呼び出せるすべてのマシンで、リモートクライアントシークレット（`gateway.remote.token` / `.password`）をローテーションします。 +1. Gateway 認証（`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`）をローテーションして再起動します。 +2. Gateway を呼び出せる任意のマシンで、リモートクライアントシークレット（`gateway.remote.token` / `.password`）をローテーションします。 3. プロバイダー/API 認証情報（WhatsApp 認証情報、Slack/Discord トークン、`auth-profiles.json` 内のモデル/API キー、使用している場合は暗号化されたシークレットペイロード値）をローテーションします。 ### 監査 1. Gateway ログを確認します: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`（または `logging.file`）。 2. 関連するトランスクリプトを確認します: `~/.openclaw/agents//sessions/*.jsonl`。 -3. 最近の設定変更（アクセスを広げた可能性のあるもの: `gateway.bind`、`gateway.auth`、DM/グループポリシー、`tools.elevated`、Plugin 変更）を確認します。 -4. `openclaw security audit --deep` を再実行し、重大な検出事項が解決済みであることを確認します。 +3. 最近の設定変更を確認します（アクセスを広げた可能性があるもの: `gateway.bind`、`gateway.auth`、DM/グループポリシー、`tools.elevated`、Plugin 変更）。 +4. `openclaw security audit --deep` を再実行し、重大な検出結果が解決されていることを確認します。 -### 報告用に収集 +### レポート用に収集 - タイムスタンプ、Gateway ホスト OS + OpenClaw バージョン -- セッショントランスクリプト + 短いログ末尾（秘匿後） +- セッショントランスクリプト + 短いログ末尾（墨消し後） - 攻撃者が送信した内容 + エージェントが行ったこと -- Gateway が loopback を越えて露出していたかどうか（LAN/Tailscale Funnel/Serve） +- Gateway が loopback を超えて露出していたかどうか（LAN/Tailscale Funnel/Serve） ## detect-secrets によるシークレットスキャン CI は `secrets` ジョブで `detect-secrets` pre-commit フックを実行します。 -`main` への push では常に全ファイルスキャンが実行されます。プルリクエストでは、ベースコミットが利用可能な場合は変更ファイルの -高速パスを使用し、それ以外の場合は全ファイルスキャンにフォールバックします。 -失敗した場合、ベースラインにまだ含まれていない新しい候補があります。 +`main` へのプッシュでは常に全ファイルスキャンが実行されます。プルリクエストでは、ベースコミットが利用可能な場合は変更ファイルの +高速パスを使用し、それ以外の場合は全ファイルスキャンにフォールバックします。失敗した場合、ベースラインにまだ含まれていない新しい候補があります。 ### CI が失敗した場合 -1. ローカルで再現します: +1. ローカルで再現します。 +__OC_I18N_900021__ +2. ツールを理解します。 + - pre-commit 内の `detect-secrets` は、リポジトリのベースラインと除外設定を使って `detect-secrets-hook` を実行します。 + - `detect-secrets audit` は、各ベースライン項目を本物または誤検知としてマークするための対話型レビューを開きます。 +3. 本物のシークレットの場合: ローテーション/削除してからスキャンを再実行し、ベースラインを更新します。 +4. 誤検知の場合: 対話型監査を実行し、それらを false としてマークします。 +__OC_I18N_900022__ +5. 新しい除外が必要な場合は、`.detect-secrets.cfg` に追加し、一致する `--exclude-files` / `--exclude-lines` フラグでベースラインを再生成します（この設定ファイルは参照専用です。detect-secrets は自動的には読み込みません）。 - ```bash - pre-commit run --all-files detect-secrets - ``` - -2. ツールを理解します: - - pre-commit の `detect-secrets` は、リポジトリの - ベースラインと除外設定を使用して `detect-secrets-hook` を実行します。 - - `detect-secrets audit` は、各ベースライン - 項目を本物または誤検知としてマークする対話型レビューを開きます。 -3. 本物のシークレットの場合: ローテーション/削除し、スキャンを再実行してベースラインを更新します。 -4. 誤検知の場合: 対話型監査を実行して誤検知としてマークします: - - ```bash - detect-secrets audit .secrets.baseline - ``` - -5. 新しい除外が必要な場合は、`.detect-secrets.cfg` に追加し、対応する `--exclude-files` / `--exclude-lines` フラグで - ベースラインを再生成します（設定ファイルは参照専用です。detect-secrets は自動では読み取りません）。 - -意図した状態を反映したら、更新済みの `.secrets.baseline` をコミットします。 +意図した状態を反映したら、更新済みの `.secrets.baseline` をコミットしてください。 ## セキュリティ問題の報告 -OpenClaw に脆弱性を見つけましたか？責任ある報告をお願いします: +OpenClaw に脆弱性を見つけましたか？責任ある形で報告してください。 1. メール: [security@openclaw.ai](mailto:security@openclaw.ai) 2. 修正されるまで公開しないでください -3. クレジットします（匿名を希望する場合を除く） +3. あなたをクレジットします（匿名を希望する場合を除く） diff --git a/docs/ja-JP/plugins/codex-harness.md b/docs/ja-JP/plugins/codex-harness.md index 6aa1b4cb8..0fb0408e4 100644 --- a/docs/ja-JP/plugins/codex-harness.md +++ b/docs/ja-JP/plugins/codex-harness.md @@ -1,190 +1,135 @@ --- read_when: - - バンドルされている Codex アプリサーバー ハーネスを使用したい場合 + - バンドルされている Codex アプリサーバーハーネスを使用したい場合 - Codex ハーネス設定の例が必要です - - Codex のみのデプロイで、PI にフォールバックするのではなく失敗させたい + - Codex のみのデプロイで、PI にフォールバックするのではなく失敗させたい場合 summary: バンドルされた Codex app-server ハーネスを通じて OpenClaw の埋め込みエージェントターンを実行する title: Codex ハーネス x-i18n: - generated_at: "2026-04-30T05:24:18Z" + generated_at: "2026-04-30T20:05:45Z" model: gpt-5.5 provider: openai - source_hash: 93abb72e9590aad265e5b6b8691dd16314178c4d255679b4e53da33b792a6e6b + source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f source_path: plugins/codex-harness.md workflow: 16 --- -バンドルされた `codex` Plugin により、OpenClaw は組み込み PI ハーネスではなく -Codex アプリサーバーを通じて埋め込みエージェントターンを実行できます。 +同梱の `codex` Plugin により、OpenClaw は組み込みの PI ハーネスではなく Codex app-server を通じて埋め込みエージェントターンを実行できます。 -低レベルのエージェントセッションを Codex に任せたい場合に使用します。モデル -検出、ネイティブスレッド再開、ネイティブ Compaction、アプリサーバー実行です。 -OpenClaw は引き続き、チャットチャネル、セッションファイル、モデル選択、ツール、 -承認、メディア配信、表示されるトランスクリプトミラーを所有します。 +低レベルのエージェントセッション、つまりモデル検出、ネイティブスレッドの再開、ネイティブ Compaction、app-server 実行を Codex に所有させたい場合に使用します。OpenClaw は引き続き、チャットチャネル、セッションファイル、モデル選択、ツール、承認、メディア配信、表示されるトランスクリプトミラーを所有します。 -全体像を把握したい場合は、 -[エージェントランタイム](/ja-JP/concepts/agent-runtimes) から始めてください。短く言うと、 -`openai/gpt-5.5` はモデル参照、`codex` はランタイムで、Telegram、 -Discord、Slack、または別のチャネルが通信面のままです。 +全体像を把握したい場合は、[エージェントランタイム](/ja-JP/concepts/agent-runtimes) から始めてください。短く言えば、`openai/gpt-5.5` はモデル参照、`codex` はランタイムであり、Telegram、Discord、Slack、または別のチャネルが通信サーフェスのままです。 ## この Plugin が変更すること -バンドルされた `codex` Plugin は、いくつかの独立した機能を提供します。 +同梱の `codex` Plugin は、複数の独立した機能を提供します。 -| 機能 | 使い方 | 動作 | +| 機能 | 使い方 | 何をするか | | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| ネイティブ埋め込みランタイム | `agentRuntime.id: "codex"` | OpenClaw の埋め込みエージェントターンを Codex アプリサーバー経由で実行します。 | -| ネイティブチャット制御コマンド | `/codex bind`, `/codex resume`, `/codex steer`, ... | メッセージング会話から Codex アプリサーバースレッドをバインドおよび制御します。 | -| Codex アプリサーバープロバイダー/カタログ | `codex` 内部、ハーネス経由で公開 | ランタイムがアプリサーバーモデルを検出および検証できるようにします。 | -| Codex メディア理解パス | `codex/*` 画像モデル互換パス | サポート対象の画像理解モデル向けに、境界付きの Codex アプリサーバーターンを実行します。 | -| ネイティブフックリレー | Codex ネイティブイベント周辺の Plugin フック | OpenClaw がサポート対象の Codex ネイティブツール/終了イベントを監視/ブロックできるようにします。 | +| ネイティブ組み込みランタイム | `agentRuntime.id: "codex"` | Codex app-server を通じて OpenClaw の埋め込みエージェントターンを実行します。 | +| ネイティブチャット制御コマンド | `/codex bind`, `/codex resume`, `/codex steer`, ... | メッセージング会話から Codex app-server スレッドをバインドおよび制御します。 | +| Codex app-server プロバイダー/カタログ | `codex` 内部、ハーネス経由で公開 | ランタイムが app-server モデルを検出および検証できるようにします。 | +| Codex メディア理解パス | `codex/*` 画像モデル互換パス | 対応する画像理解モデル向けに境界付きの Codex app-server ターンを実行します。 | +| ネイティブフックリレー | Codex ネイティブイベント周辺の Plugin フック | 対応する Codex ネイティブのツール/完了イベントを OpenClaw が監視/ブロックできるようにします。 | -Plugin を有効にすると、これらの機能が利用可能になります。これは次のことを**行いません**。 +この Plugin を有効にすると、これらの機能が利用可能になります。次のことは**行いません**。 - すべての OpenAI モデルで Codex を使い始める - `openai-codex/*` モデル参照をネイティブランタイムに変換する - ACP/acpx をデフォルトの Codex パスにする -- すでに PI ランタイムを記録している既存セッションをホットスイッチする -- OpenClaw のチャネル配信、セッションファイル、認証プロファイル保存、または - メッセージルーティングを置き換える +- すでに PI ランタイムを記録した既存セッションをホットスイッチする +- OpenClaw のチャネル配信、セッションファイル、認証プロファイル保存、またはメッセージルーティングを置き換える -同じ Plugin は、ネイティブの `/codex` チャット制御コマンド面も所有します。 -Plugin が有効で、ユーザーがチャットから Codex スレッドのバインド、再開、誘導、停止、または検査を求めた場合、 -エージェントは ACP より `/codex ...` を優先するべきです。ACP は、ユーザーが ACP/acpx を求めた場合、または ACP -Codex アダプターをテストしている場合の明示的なフォールバックのままです。 +同じ Plugin は、ネイティブの `/codex` チャット制御コマンドサーフェスも所有します。Plugin が有効で、ユーザーがチャットから Codex スレッドのバインド、再開、ステアリング、停止、または調査を求めた場合、エージェントは ACP よりも `/codex ...` を優先するべきです。ユーザーが ACP/acpx を求めている場合、または ACP Codex アダプターをテストしている場合、ACP は明示的なフォールバックのままです。 -ネイティブ Codex ターンは、OpenClaw Plugin フックを公開互換レイヤーとして維持します。 -これらはプロセス内 OpenClaw フックであり、Codex `hooks.json` コマンドフックではありません。 +ネイティブ Codex ターンでは、OpenClaw Plugin フックが公開互換レイヤーとして維持されます。これらはプロセス内の OpenClaw フックであり、Codex の `hooks.json` コマンドフックではありません。 - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write` ミラーされたトランスクリプトレコード用 -- Codex `Stop` リレー経由の `before_agent_finalize` +- `before_message_write`（ミラーされたトランスクリプトレコード用） +- Codex `Stop` リレーを通じた `before_agent_finalize` - `agent_end` -Plugin は、OpenClaw がツールを実行した後、結果が Codex に返される前に -OpenClaw の動的ツール結果を書き換える、ランタイム中立のツール結果ミドルウェアも登録できます。 -これは、OpenClaw が所有するトランスクリプトのツール結果書き込みを変換する公開 -`tool_result_persist` Plugin フックとは別のものです。 +Plugin は、ランタイム中立のツール結果ミドルウェアも登録でき、OpenClaw がツールを実行した後、結果が Codex に返される前に OpenClaw の動的ツール結果を書き換えられます。これは公開 `tool_result_persist` Plugin フックとは別のものです。このフックは、OpenClaw が所有するトランスクリプトのツール結果書き込みを変換します。 -Plugin フックのセマンティクス自体については、[Plugin フック](/ja-JP/plugins/hooks) -および [Plugin ガード動作](/ja-JP/tools/plugin) を参照してください。 +Plugin フックのセマンティクス自体については、[Plugin フック](/ja-JP/plugins/hooks) と [Plugin ガード動作](/ja-JP/tools/plugin) を参照してください。 -ハーネスはデフォルトでオフです。新しい設定では、OpenAI モデル参照を -`openai/gpt-*` として正規化したままにし、ネイティブアプリサーバー実行が必要な場合は -`agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を明示的に強制するべきです。 -レガシーの `codex/*` モデル参照は互換性のために引き続きハーネスを自動選択しますが、 -ランタイムで裏付けられたレガシープロバイダープレフィックスは通常のモデル/プロバイダー選択肢として表示されません。 +ハーネスはデフォルトで無効です。新しい設定では、OpenAI モデル参照を `openai/gpt-*` として正規のまま維持し、ネイティブ app-server 実行が必要な場合は `agentRuntime.id: "codex"` または `OPENCLAW_AGENT_RUNTIME=codex` を明示的に強制するべきです。レガシーの `codex/*` モデル参照は互換性のために引き続きハーネスを自動選択しますが、ランタイムに裏付けられたレガシープロバイダープレフィックスは通常のモデル/プロバイダー選択肢として表示されません。 -`codex` Plugin が有効でも、プライマリモデルがまだ -`openai-codex/*` の場合、`openclaw doctor` は経路を変更せずに警告します。これは意図的です。 -`openai-codex/*` は PI Codex OAuth/サブスクリプションパスのままであり、 -ネイティブアプリサーバー実行は明示的なランタイム選択のままです。 +`codex` Plugin が有効でも、プライマリモデルがまだ `openai-codex/*` の場合、`openclaw doctor` は経路を変更せずに警告します。これは意図的なものです。`openai-codex/*` は PI Codex OAuth/サブスクリプションパスのままであり、ネイティブ app-server 実行は明示的なランタイム選択のままです。 ## ルートマップ 設定を変更する前に、この表を使用してください。 -| 望ましい動作 | モデル参照 | ランタイム設定 | Plugin 要件 | 期待されるステータスラベル | +| 望ましい動作 | モデル参照 | ランタイム設定 | Plugin 要件 | 期待されるステータスラベル | | --------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | -| 通常の OpenClaw ランナー経由の OpenAI API | `openai/gpt-*` | 省略または `runtime: "pi"` | OpenAI プロバイダー | `Runtime: OpenClaw Pi Default` | -| PI 経由の Codex OAuth/サブスクリプション | `openai-codex/gpt-*` | 省略または `runtime: "pi"` | OpenAI Codex OAuth プロバイダー | `Runtime: OpenClaw Pi Default` | -| ネイティブ Codex アプリサーバー埋め込みターン | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` | -| 保守的な自動モードでの混在プロバイダー | プロバイダー固有の参照 | `agentRuntime.id: "auto"` | 任意の Plugin ランタイム | 選択されたランタイムに依存 | -| 明示的な Codex ACP アダプターセッション | ACP プロンプト/モデル依存 | `sessions_spawn` と `runtime: "acp"` | 正常な `acpx` バックエンド | ACP タスク/セッションステータス | +| 通常の OpenClaw ランナー経由の OpenAI API | `openai/gpt-*` | 省略、または `runtime: "pi"` | OpenAI プロバイダー | `Runtime: OpenClaw Pi Default` | +| PI 経由の Codex OAuth/サブスクリプション | `openai-codex/gpt-*` | 省略、または `runtime: "pi"` | OpenAI Codex OAuth プロバイダー | `Runtime: OpenClaw Pi Default` | +| ネイティブ Codex app-server 組み込みターン | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` | +| 保守的な自動モードでの混在プロバイダー | プロバイダー固有の参照 | `agentRuntime.id: "auto"` | 任意の Plugin ランタイム | 選択されたランタイムに依存 | +| 明示的な Codex ACP アダプターセッション | ACP プロンプト/モデルに依存 | `sessions_spawn` with `runtime: "acp"` | 正常な `acpx` バックエンド | ACP タスク/セッションステータス | 重要な分離は、プロバイダーとランタイムの違いです。 -- `openai-codex/*` は「PI はどのプロバイダー/認証経路を使うべきか?」に答えます -- `agentRuntime.id: "codex"` は「どのループがこの - 埋め込みターンを実行するべきか?」に答えます -- `/codex ...` は「このチャットはどのネイティブ Codex 会話をバインドまたは制御するべきか?」 - に答えます -- ACP は「acpx はどの外部ハーネスプロセスを起動するべきか?」に答えます +- `openai-codex/*` は「PI はどのプロバイダー/認証経路を使用するべきか？」に答えます +- `agentRuntime.id: "codex"` は「この埋め込みターンをどのループで実行するべきか？」に答えます +- `/codex ...` は「このチャットはどのネイティブ Codex 会話をバインドまたは制御するべきか？」に答えます +- ACP は「acpx はどの外部ハーネスプロセスを起動するべきか？」に答えます -## 正しいモデルプレフィックスを選ぶ +## 適切なモデルプレフィックスを選ぶ -OpenAI ファミリーのルートはプレフィックス固有です。PI 経由の Codex OAuth が必要な場合は `openai-codex/*` を使用し、 -直接の OpenAI API アクセスが必要な場合、またはネイティブ Codex アプリサーバーハーネスを強制している場合は -`openai/*` を使用します。 +OpenAI ファミリーのルートはプレフィックス固有です。PI 経由の Codex OAuth が必要な場合は `openai-codex/*` を使用し、直接の OpenAI API アクセスが必要な場合、またはネイティブ Codex app-server ハーネスを強制する場合は `openai/*` を使用します。 | モデル参照 | ランタイムパス | 使用する場合 | | --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | OpenClaw/PI 配管経由の OpenAI プロバイダー | `OPENAI_API_KEY` で現在の直接 OpenAI Platform API アクセスを使いたい場合。 | -| `openai-codex/gpt-5.5` | OpenClaw/PI 経由の OpenAI Codex OAuth | デフォルト PI ランナーで ChatGPT/Codex サブスクリプション認証を使いたい場合。 | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex アプリサーバーハーネス | 埋め込みエージェントターンでネイティブ Codex アプリサーバー実行を使いたい場合。 | +| `openai/gpt-5.4` | OpenClaw/PI 配管経由の OpenAI プロバイダー | `OPENAI_API_KEY` による現在の直接 OpenAI Platform API アクセスが必要な場合。 | +| `openai-codex/gpt-5.5` | OpenClaw/PI 経由の OpenAI Codex OAuth | デフォルトの PI ランナーで ChatGPT/Codex サブスクリプション認証が必要な場合。 | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server ハーネス | 埋め込みエージェントターンでネイティブ Codex app-server 実行が必要な場合。 | -GPT-5.5 は現在 OpenClaw ではサブスクリプション/OAuth のみです。PI OAuth には -`openai-codex/gpt-5.5` を使用し、Codex アプリサーバーハーネスには `openai/gpt-5.5` を使用します。 -OpenAI が GPT-5.5 を公開 API で有効にすると、`openai/gpt-5.5` の直接 API キーアクセスがサポートされます。 +GPT-5.5 は現在 OpenClaw ではサブスクリプション/OAuth のみです。PI OAuth には `openai-codex/gpt-5.5` を使用し、Codex app-server ハーネスには `openai/gpt-5.5` を使用してください。OpenAI が公開 API で GPT-5.5 を有効にすると、`openai/gpt-5.5` の直接 API キーアクセスがサポートされます。 -レガシーの `codex/gpt-*` 参照は互換エイリアスとして引き続き受け入れられます。Doctor -互換性移行は、レガシーのプライマリランタイム参照を正規モデル参照に書き換え、ランタイムポリシーを別に記録します。 -一方、フォールバックのみのレガシー参照は、ランタイムがエージェントコンテナー全体に対して設定されるため変更されません。 -新しい PI Codex OAuth 設定では `openai-codex/gpt-*` を使用するべきです。新しいネイティブ -アプリサーバーハーネス設定では `openai/gpt-*` に加えて -`agentRuntime.id: "codex"` を使用するべきです。 +レガシーの `codex/gpt-*` 参照は、互換エイリアスとして引き続き受け入れられます。Doctor の互換移行は、レガシーのプライマリランタイム参照を正規モデル参照に書き換え、ランタイムポリシーを別に記録します。一方で、フォールバック専用のレガシー参照は、ランタイムがエージェントコンテナ全体に対して設定されるため変更されません。新しい PI Codex OAuth 設定では `openai-codex/gpt-*` を使用し、新しいネイティブ app-server ハーネス設定では `openai/gpt-*` と `agentRuntime.id: "codex"` を組み合わせて使用してください。 -`agents.defaults.imageModel` も同じプレフィックス分離に従います。画像理解を OpenAI -Codex OAuth プロバイダーパス経由で実行するべき場合は `openai-codex/gpt-*` を使用します。画像理解を -境界付き Codex アプリサーバーターン経由で実行するべき場合は `codex/gpt-*` を使用します。Codex アプリサーバーモデルは -画像入力サポートを宣伝している必要があります。テキストのみの Codex モデルは、メディアターンの開始前に失敗します。 +`agents.defaults.imageModel` も同じプレフィックス分離に従います。画像理解を OpenAI Codex OAuth プロバイダーパス経由で実行する必要がある場合は `openai-codex/gpt-*` を使用してください。画像理解を境界付きの Codex app-server ターン経由で実行する必要がある場合は `codex/gpt-*` を使用してください。Codex app-server モデルは画像入力サポートを公開している必要があります。テキスト専用の Codex モデルは、メディアターンが開始する前に失敗します。 -現在のセッションで有効なハーネスを確認するには `/status` を使用します。選択が予想外の場合は、 -`agents/harness` サブシステムのデバッグログを有効にし、Gateway の構造化された `agent harness selected` レコードを調べます。 -これには、選択されたハーネス ID、選択理由、ランタイム/フォールバックポリシー、および -`auto` モードでは各 Plugin 候補のサポート結果が含まれます。 +現在のセッションで有効なハーネスを確認するには `/status` を使用してください。選択が予想外の場合は、`agents/harness` サブシステムのデバッグログを有効にし、Gateway の構造化された `agent harness selected` レコードを調べてください。これには、選択されたハーネス ID、選択理由、ランタイム/フォールバックポリシー、および `auto` モードでは各 Plugin 候補のサポート結果が含まれます。 ### doctor 警告の意味 `openclaw doctor` は、次のすべてが真の場合に警告します。 -- バンドルされた `codex` Plugin が有効または許可されている +- 同梱の `codex` Plugin が有効、または許可されている - エージェントのプライマリモデルが `openai-codex/*` - そのエージェントの有効なランタイムが `codex` ではない -この警告が存在するのは、ユーザーが「Codex Plugin が有効」を「ネイティブ Codex アプリサーバーランタイム」を意味すると期待しがちだからです。 -OpenClaw はその飛躍を行いません。この警告の意味は次のとおりです。 +この警告が存在するのは、ユーザーがしばしば「Codex Plugin が有効」であれば「ネイティブ Codex app-server ランタイム」も意味すると期待するためです。OpenClaw はその飛躍を行いません。この警告の意味は次のとおりです。 - PI 経由の ChatGPT/Codex OAuth を意図していた場合、**変更は不要です**。 -- ネイティブアプリサーバー実行を意図していた場合は、モデルを `openai/` に変更し、 - `agentRuntime.id: "codex"` を設定します。 -- ランタイム変更後も、既存セッションには `/new` または `/reset` が必要です。 - セッションランタイムピンは固定的だからです。 +- ネイティブ app-server 実行を意図していた場合は、モデルを `openai/` に変更し、`agentRuntime.id: "codex"` を設定してください。 +- セッションランタイムピンは固定されるため、ランタイム変更後も既存セッションには `/new` または `/reset` が必要です。 -ハーネス選択はライブセッション制御ではありません。埋め込みターンが実行されると、 -OpenClaw は選択されたハーネス ID をそのセッションに記録し、同じセッション ID の後続ターンでもそれを使い続けます。 -将来のセッションで別のハーネスを使いたい場合は、`agentRuntime` 設定または -`OPENCLAW_AGENT_RUNTIME` を変更します。既存の会話を PI と Codex の間で切り替える前に、新しいセッションを開始するには -`/new` または `/reset` を使用します。これにより、1 つのトランスクリプトを互換性のない 2 つのネイティブセッションシステムで再生することを避けられます。 +ハーネス選択はライブセッション制御ではありません。埋め込みターンが実行されると、OpenClaw は選択されたハーネス ID をそのセッションに記録し、同じセッション ID の後続ターンでもそれを使用し続けます。将来のセッションで別のハーネスを使いたい場合は、`agentRuntime` 設定または `OPENCLAW_AGENT_RUNTIME` を変更してください。既存の会話を PI と Codex の間で切り替える前には、`/new` または `/reset` を使用して新しいセッションを開始してください。これにより、1 つのトランスクリプトを互換性のない 2 つのネイティブセッションシステムで再生することを避けられます。 -ハーネスピンが導入される前に作成されたレガシーセッションは、トランスクリプト履歴を持つと PI にピン留めされたものとして扱われます。 -設定を変更した後、その会話を Codex にオプトインするには `/new` または `/reset` を使用します。 +ハーネスピン導入前に作成されたレガシーセッションは、トランスクリプト履歴があると PI ピン済みとして扱われます。設定を変更した後、その会話を Codex に参加させるには `/new` または `/reset` を使用してください。 -`/status` は有効なモデルランタイムを表示します。デフォルト PI ハーネスは -`Runtime: OpenClaw Pi Default` として表示され、Codex アプリサーバーハーネスは -`Runtime: OpenAI Codex` として表示されます。 +`/status` は有効なモデルランタイムを表示します。デフォルトの PI ハーネスは `Runtime: OpenClaw Pi Default` と表示され、Codex app-server ハーネスは `Runtime: OpenAI Codex` と表示されます。 ## 要件 -- バンドルされた `codex` Plugin が利用可能な OpenClaw。 -- Codex アプリサーバー `0.125.0` 以降。バンドルされた Plugin はデフォルトで互換性のある - Codex アプリサーバーバイナリを管理するため、`PATH` 上のローカル `codex` コマンドは - 通常のハーネス起動に影響しません。 -- アプリサーバープロセスまたは OpenClaw の Codex 認証ブリッジで利用可能な Codex 認証。 +- 同梱の `codex` Plugin が利用可能な OpenClaw。 +- Codex app-server `0.125.0` 以降。同梱 Plugin はデフォルトで互換性のある Codex app-server バイナリを管理するため、`PATH` 上のローカル `codex` コマンドは通常のハーネス起動に影響しません。 +- app-server プロセス、または OpenClaw の Codex 認証ブリッジで利用可能な Codex 認証。ローカルの app-server 起動は、各エージェント用の OpenClaw 管理 Codex ホームと分離された子 `HOME` を使用するため、デフォルトでは個人の `~/.codex` アカウント、Skills、Plugin、設定、スレッド状態、またはネイティブ `$HOME/.agents/skills` を読み取りません。 -Plugin は、古いまたはバージョン未設定のアプリサーバーハンドシェイクをブロックします。これにより、 -OpenClaw はテスト済みのプロトコル面に留まります。 +Plugin は、古い、またはバージョンなしの app-server ハンドシェイクをブロックします。これにより、OpenClaw はテスト済みのプロトコルサーフェス上に維持されます。 -ライブおよび Docker スモークテストでは、認証は通常 Codex CLI アカウントまたは OpenClaw -`openai-codex` 認証プロファイルから取得されます。ローカル stdio アプリサーバー起動では、 -アカウントが存在しない場合に `CODEX_API_KEY` / `OPENAI_API_KEY` にフォールバックすることもできます。 +ライブおよび Docker スモークテストでは、認証は通常 Codex CLI アカウント、または OpenClaw の `openai-codex` 認証プロファイルから取得されます。ローカル stdio app-server 起動では、アカウントが存在しない場合に `CODEX_API_KEY` / `OPENAI_API_KEY` にフォールバックすることもできます。 ## 最小設定 -`openai/gpt-5.5` を使用し、バンドルされた Plugin を有効にし、`codex` ハーネスを強制します。 +`openai/gpt-5.5` を使用し、同梱 Plugin を有効にして、`codex` ハーネスを強制します。 ```json5 { @@ -206,7 +151,7 @@ OpenClaw はテスト済みのプロトコル面に留まります。 } ``` -設定で `plugins.allow` を使用している場合は、そこにも `codex` を含めます。 +設定で `plugins.allow` を使用している場合は、そこにも `codex` を含めてください。 ```json5 { @@ -221,24 +166,19 @@ OpenClaw はテスト済みのプロトコル面に留まります。 } ``` -`agents.defaults.model` またはエージェントモデルを -`codex/` に設定するレガシー設定でも、バンドルされた `codex` Plugin は引き続き自動で有効になります。 -新しい設定では、上記の明示的な `agentRuntime` エントリに加えて `openai/` を優先するべきです。 +`agents.defaults.model` またはエージェントモデルを `codex/` に設定するレガシー設定では、引き続き同梱の `codex` Plugin が自動的に有効になります。新しい設定では、上記の明示的な `agentRuntime` エントリと組み合わせて `openai/` を使用することを推奨します。 -## 他のモデルと並べて Codex を追加する +## Codex を他のモデルと併用する -同じエージェントが Codex と非 Codex プロバイダーモデルを自由に切り替えるべき場合は、`agentRuntime.id: "codex"` をグローバルに設定しないでください。 -強制ランタイムは、そのエージェントまたはセッションのすべての埋め込みターンに適用されます。そのランタイムが強制されている状態で Anthropic モデルを選択した場合、 -OpenClaw は引き続き Codex ハーネスを試し、そのターンを PI 経由で静かにルーティングするのではなく、クローズドに失敗します。 +同じエージェントが Codex と非 Codex プロバイダーモデルの間を自由に切り替える必要がある場合は、`agentRuntime.id: "codex"` をグローバルに設定しないでください。強制されたランタイムは、そのエージェントまたはセッションのすべての埋め込みターンに適用されます。そのランタイムが強制されている状態で Anthropic モデルを選択すると、OpenClaw は引き続き Codex ハーネスを試行し、そのターンを PI 経由で黙ってルーティングするのではなく、クローズドに失敗します。 -代わりに、次のいずれかの形を使用します。 +代わりに、次のいずれかの形を使用してください。 -- `agentRuntime.id: "codex"` を指定した専用エージェントに Codex を配置する。 +- `agentRuntime.id: "codex"` を設定した専用エージェントに Codex を置く。 - 通常の混在プロバイダー利用では、デフォルトエージェントを `agentRuntime.id: "auto"` と PI フォールバックのままにする。 -- レガシーの `codex/*` 参照は互換性のためだけに使用する。新しい設定では、`openai/*` に加えて明示的な Codex ランタイムポリシーを優先する。 +- レガシーの `codex/*` 参照は互換性のためだけに使用する。新しい設定では、`openai/*` と明示的な Codex ランタイムポリシーを優先する。 -たとえば、これはデフォルトエージェントを通常の自動選択のままにし、 -別の Codex エージェントを追加します。 +たとえば、これはデフォルトエージェントを通常の自動選択のままにし、別の Codex エージェントを追加します。 ```json5 { @@ -277,31 +217,31 @@ OpenClaw は引き続き Codex ハーネスを試し、そのターンを PI 経 この形では次のようになります。 -- デフォルトの `main` エージェントは、通常のプロバイダーパスと PI 互換フォールバックを使用する。 -- `codex` エージェントは Codex アプリサーバーハーネスを使用する。 -- `codex` エージェントで Codex が見つからない、またはサポートされていない場合、静かに PI を使用するのではなく、そのターンは失敗する。 +- デフォルトの `main` エージェントは、通常のプロバイダーパスと PI 互換フォールバックを使用します。 +- `codex` エージェントは Codex app-server ハーネスを使用します。 +- `codex` エージェントで Codex が見つからない、またはサポートされていない場合、そのターンは PI を静かに使うのではなく失敗します。 ## エージェントコマンドのルーティング -エージェントは、「Codex」という単語だけでなく、意図に基づいてユーザーリクエストをルーティングする必要があります。 +エージェントは「Codex」という単語だけではなく、意図に基づいてユーザーリクエストをルーティングする必要があります。 -| ユーザーが求めること... | エージェントが使用すべきもの... | +| ユーザーの依頼... | エージェントが使用すべきもの... | | -------------------------------------------------------- | ------------------------------------------------ | -| 「このチャットを Codex にバインドして」 | `/codex bind` | -| 「Codex スレッド `` をここで再開して」 | `/codex resume ` | -| 「Codex スレッドを表示して」 | `/codex threads` | -| 「不適切な Codex 実行のサポートレポートを提出して」 | `/diagnostics [note]` | -| 「この添付スレッドについてのみ Codex フィードバックを送って」 | `/codex diagnostics [note]` | -| 「このエージェントのランタイムとして Codex を使って」 | `agentRuntime.id` への設定変更 | -| 「通常の OpenClaw で ChatGPT/Codex サブスクリプションを使って」 | `openai-codex/*` モデル参照 | -| 「ACP/acpx 経由で Codex を実行して」 | ACP `sessions_spawn({ runtime: "acp", ... })` | -| 「Claude Code/Gemini/OpenCode/Cursor をスレッドで開始して」 | ACP/acpx、`/codex` でもネイティブサブエージェントでもない | +| 「このチャットを Codex にバインドして」 | `/codex bind` | +| 「Codex スレッド `` をここで再開して」 | `/codex resume ` | +| 「Codex スレッドを表示して」 | `/codex threads` | +| 「問題のある Codex 実行についてサポートレポートを提出して」 | `/diagnostics [note]` | +| 「この添付スレッドについてのみ Codex フィードバックを送信して」 | `/codex diagnostics [note]` | +| 「このエージェントのランタイムとして Codex を使用して」 | `agentRuntime.id` への設定変更 | +| 「通常の OpenClaw で自分の ChatGPT/Codex サブスクリプションを使って」 | `openai-codex/*` モデル参照 | +| 「ACP/acpx 経由で Codex を実行して」 | ACP `sessions_spawn({ runtime: "acp", ... })` | +| 「スレッド内で Claude Code/Gemini/OpenCode/Cursor を開始して」 | `/codex` やネイティブサブエージェントではなく ACP/acpx | -OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれたランタイムバックエンドに支えられている場合にのみ、ACP spawn ガイダンスをエージェントに提示します。ACP が利用できない場合、システムプロンプトと Plugin Skills は、ACP ルーティングについてエージェントに教えるべきではありません。 +OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれたランタイムバックエンドに支えられている場合にのみ、エージェントへ ACP spawn ガイダンスを提示します。ACP が利用できない場合、システムプロンプトと Plugin Skills はエージェントに ACP ルーティングを教えるべきではありません。 ## Codex 専用デプロイ -すべての埋め込みエージェントターンで Codex が使われることを証明する必要がある場合は、Codex ハーネスを強制します。明示的な Plugin ランタイムはデフォルトで PI フォールバックなしになるため、`fallback: "none"` は任意ですが、ドキュメントとして役立つことがよくあります。 +すべての埋め込みエージェントターンが Codex を使用することを証明する必要がある場合は、Codex ハーネスを強制します。明示的な Plugin ランタイムはデフォルトで PI フォールバックなしになるため、`fallback: "none"` は任意ですが、ドキュメントとして有用なことがよくあります。 ```json5 { @@ -323,11 +263,11 @@ OpenClaw は、ACP が有効で、ディスパッチ可能で、読み込まれ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Codex が強制されている場合、Codex Plugin が無効、アプリサーバーが古すぎる、またはアプリサーバーを起動できないと、OpenClaw は早期に失敗します。欠落したハーネス選択を意図的に PI に処理させたい場合にのみ、`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` を設定してください。 +Codex が強制されている場合、OpenClaw は Codex Plugin が無効、app-server が古すぎる、または app-server を起動できない場合に早期に失敗します。ハーネス選択が見つからない場合に PI で処理させたいことを意図している場合にのみ、`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` を設定してください。 ## エージェントごとの Codex -デフォルトエージェントは通常の自動選択を維持しつつ、1 つのエージェントだけを Codex 専用にできます。 +デフォルトエージェントは通常の自動選択を維持したまま、1 つのエージェントを Codex 専用にできます。 ```json5 { @@ -358,11 +298,11 @@ Codex が強制されている場合、Codex Plugin が無効、アプリサー } ``` -エージェントとモデルの切り替えには通常のセッションコマンドを使用します。`/new` は新しい OpenClaw セッションを作成し、Codex ハーネスは必要に応じてサイドカーアプリサーバースレッドを作成または再開します。`/reset` は、そのスレッドの OpenClaw セッションバインドを消去し、次のターンで現在の設定からハーネスを再解決できるようにします。 +エージェントとモデルの切り替えには通常のセッションコマンドを使用します。`/new` は新しい OpenClaw セッションを作成し、Codex ハーネスは必要に応じてサイドカー app-server スレッドを作成または再開します。`/reset` はそのスレッドの OpenClaw セッションバインディングをクリアし、次のターンで現在の設定からハーネスを再解決できるようにします。 ## モデル検出 -デフォルトでは、Codex Plugin は利用可能なモデルをアプリサーバーに問い合わせます。検出が失敗するかタイムアウトした場合、次のバンドル済みフォールバックカタログを使用します。 +デフォルトでは、Codex Plugin は利用可能なモデルを app-server に問い合わせます。検出に失敗するかタイムアウトした場合、次のバンドル済みフォールバックカタログを使用します。 - GPT-5.5 - GPT-5.4 mini @@ -388,7 +328,7 @@ Codex が強制されている場合、Codex Plugin が無効、アプリサー } ``` -起動時に Codex へのプローブを避け、フォールバックカタログに固定したい場合は、検出を無効にします。 +起動時に Codex のプローブを避け、フォールバックカタログに固定したい場合は検出を無効にします。 ```json5 { @@ -407,7 +347,7 @@ Codex が強制されている場合、Codex Plugin が無効、アプリサー } ``` -## アプリサーバー接続とポリシー +## app-server の接続とポリシー デフォルトでは、Plugin は OpenClaw の管理対象 Codex バイナリをローカルで次のように起動します。 @@ -415,13 +355,11 @@ Codex が強制されている場合、Codex Plugin が無効、アプリサー codex app-server --listen stdio:// ``` -管理対象バイナリはバンドル済み Plugin ランタイム依存関係として宣言され、残りの `codex` Plugin 依存関係とともにステージングされます。これにより、アプリサーバーのバージョンは、ローカルにたまたまインストールされている別の Codex CLI ではなく、バンドル済み Plugin に結び付けられます。別の実行ファイルを意図的に実行したい場合にのみ、`appServer.command` を設定してください。 +管理対象バイナリは、バンドル済み Plugin ランタイム依存関係として宣言され、残りの `codex` Plugin 依存関係とともにステージングされます。これにより、app-server のバージョンは、ローカルにインストールされている別の Codex CLI ではなく、バンドル済み Plugin に紐付けられます。別の実行可能ファイルを意図的に実行したい場合にのみ、`appServer.command` を設定してください。 -デフォルトでは、OpenClaw はローカル Codex ハーネスセッションを YOLO モードで開始します。 -`approvalPolicy: "never"`、`approvalsReviewer: "user"`、および -`sandbox: "danger-full-access"` です。これは自律 Heartbeat に使用される信頼済みローカルオペレーターの姿勢です。Codex は、応答する人がいないネイティブ承認プロンプトで停止することなく、シェルとネットワークツールを使用できます。 +デフォルトでは、OpenClaw はローカル Codex ハーネスセッションを YOLO モードで開始します。`approvalPolicy: "never"`、`approvalsReviewer: "user"`、および `sandbox: "danger-full-access"` です。これは自律的な Heartbeat に使用される、信頼されたローカルオペレーターの姿勢です。Codex は、応答する人がいないネイティブ承認プロンプトで停止せずに、シェルとネットワークツールを使用できます。 -Codex のガーディアンレビュー付き承認にオプトインするには、`appServer.mode: +Codex のガーディアンレビュー付き承認を有効にするには、`appServer.mode: "guardian"` を設定します。 ```json5 @@ -442,13 +380,11 @@ Codex のガーディアンレビュー付き承認にオプトインするに } ``` -Guardian モードは Codex のネイティブ自動レビュー承認パスを使用します。Codex がサンドボックスから出る、ワークスペース外へ書き込む、またはネットワークアクセスのような権限を追加することを求める場合、Codex はその承認リクエストを人間のプロンプトではなくネイティブレビュアーにルーティングします。レビュアーは Codex のリスクフレームワークを適用し、特定のリクエストを承認または拒否します。YOLO モードより多くのガードレールが必要だが、無人エージェントにも進捗が必要な場合に Guardian を使用します。 +Guardian モードは Codex のネイティブ自動レビュー承認パスを使用します。Codex が sandbox を離れる、ワークスペース外に書き込む、またはネットワークアクセスなどの権限を追加するよう求める場合、Codex はその承認リクエストを人間のプロンプトではなくネイティブレビュアーへルーティングします。レビュアーは Codex のリスクフレームワークを適用し、特定のリクエストを承認または拒否します。YOLO モードより多くのガードレールが欲しいが、無人エージェントを進行させる必要がある場合は Guardian を使用してください。 -`guardian` プリセットは、`approvalPolicy: "on-request"`、 -`approvalsReviewer: "auto_review"`、および `sandbox: "workspace-write"` に展開されます。 -個別のポリシーフィールドは引き続き `mode` を上書きするため、高度なデプロイではプリセットと明示的な選択を混在できます。古い `guardian_subagent` レビュアー値は互換エイリアスとして引き続き受け入れられますが、新しい設定では `auto_review` を使用するべきです。 +`guardian` プリセットは、`approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"`、および `sandbox: "workspace-write"` に展開されます。個々のポリシーフィールドは引き続き `mode` を上書きするため、高度なデプロイではプリセットと明示的な選択を組み合わせることができます。古い `guardian_subagent` レビュアー値は互換エイリアスとして引き続き受け付けられますが、新しい設定では `auto_review` を使用する必要があります。 -すでに実行中のアプリサーバーには、WebSocket トランスポートを使用します。 +すでに実行中の app-server には、WebSocket トランスポートを使用します。 ```json5 { @@ -470,13 +406,25 @@ Guardian モードは Codex のネイティブ自動レビュー承認パスを } ``` -stdio アプリサーバー起動は、デフォルトで OpenClaw のプロセス環境を継承しますが、OpenClaw が Codex アプリサーバーのアカウントブリッジを所有します。認証は次の順序で選択されます。 +Stdio app-server の起動はデフォルトで OpenClaw のプロセス環境を継承しますが、OpenClaw は Codex app-server アカウントブリッジを所有し、`CODEX_HOME` と `HOME` の両方を、そのエージェントの OpenClaw 状態配下にあるエージェントごとのディレクトリに設定します。Codex 独自の skill ローダーは `$CODEX_HOME/skills` と `$HOME/.agents/skills` を読み取るため、ローカル app-server 起動では両方の値が分離されます。これにより、Codex ネイティブの Skills、Plugin、設定、アカウント、スレッド状態は、オペレーター個人の Codex CLI ホームから漏れ込むのではなく、OpenClaw エージェントにスコープされます。 -1. エージェントの明示的な OpenClaw Codex 認証プロファイル。 -2. ローカル Codex CLI ChatGPT サインインなど、アプリサーバーの既存アカウント。 -3. ローカル stdio アプリサーバー起動のみで、アプリサーバーアカウントが存在せず、OpenAI 認証がまだ必要な場合、`CODEX_API_KEY`、次に `OPENAI_API_KEY`。 +OpenClaw Plugin と OpenClaw skill スナップショットは、引き続き OpenClaw 独自の Plugin レジストリと skill ローダーを通ります。個人の Codex CLI アセットは通りません。OpenClaw エージェントの一部にすべき有用な Codex CLI Skills や Plugin がある場合は、明示的に棚卸ししてください。 -OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロファイルを検出すると、spawn された Codex 子プロセスから `CODEX_API_KEY` と `OPENAI_API_KEY` を削除します。これにより、Gateway レベルの API キーは埋め込みや直接の OpenAI モデルで利用可能なまま、ネイティブ Codex アプリサーバーターンが誤って API 経由で課金されることを防げます。明示的な Codex API キープロファイルとローカル stdio env-key フォールバックは、継承された子プロセス環境ではなくアプリサーバーログインを使用します。WebSocket アプリサーバー接続は Gateway 環境の API キーフォールバックを受け取りません。明示的な認証プロファイル、またはリモートアプリサーバー自身のアカウントを使用してください。 +```bash +openclaw migrate codex --dry-run +openclaw migrate apply codex --yes +``` + +Codex 移行プロバイダーは Skills を現在の OpenClaw エージェントワークスペースへコピーします。Codex ネイティブの Plugin、フック、設定ファイルは、コマンドを実行したり、MCP サーバーを公開したり、資格情報を含んだりする可能性があるため、自動的に有効化されるのではなく、手動レビュー用に報告またはアーカイブされます。 + +認証は次の順序で選択されます。 + +1. エージェント用の明示的な OpenClaw Codex 認証プロファイル。 +2. そのエージェントの Codex ホーム内にある app-server の既存アカウント。 +3. ローカル stdio app-server 起動のみで、app-server アカウントが存在せず OpenAI 認証が引き続き必要な場合、`CODEX_API_KEY`、次に + `OPENAI_API_KEY`。 + +OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロファイルを検出すると、spawn される Codex 子プロセスから `CODEX_API_KEY` と `OPENAI_API_KEY` を削除します。これにより、Gateway レベルの API キーを埋め込みや直接の OpenAI モデルで利用可能にしたまま、ネイティブ Codex app-server ターンが誤って API 経由で課金されることを防ぎます。明示的な Codex API キープロファイルとローカル stdio 環境キーのフォールバックは、継承された子プロセス環境ではなく app-server ログインを使用します。WebSocket app-server 接続は Gateway 環境 API キーフォールバックを受け取りません。明示的な認証プロファイルまたはリモート app-server 独自のアカウントを使用してください。 デプロイで追加の環境分離が必要な場合は、それらの変数を `appServer.clearEnv` に追加します。 @@ -497,31 +445,40 @@ OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロフ } ``` -`appServer.clearEnv` は、spawn された Codex アプリサーバー子プロセスにのみ影響します。 +`appServer.clearEnv` は spawn された Codex app-server 子プロセスにのみ影響します。 -サポートされる `appServer` フィールド: +サポートされている `appServer` フィールド: -| フィールド | デフォルト | 意味 | -| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` は Codex を起動し、`"websocket"` は `url` に接続します。 | -| `command` | 管理対象の Codex バイナリ | stdio トランスポート用の実行ファイル。管理対象バイナリを使う場合は未設定のままにし、明示的に上書きする場合にのみ設定します。 | -| `args` | `["app-server", "--listen", "stdio://"]` | stdio トランスポート用の引数。 | -| `url` | 未設定 | WebSocket app-server URL。 | -| `authToken` | 未設定 | WebSocket トランスポート用の Bearer token。 | -| `headers` | `{}` | 追加の WebSocket ヘッダー。 | -| `clearEnv` | `[]` | OpenClaw が継承環境を構築した後、生成された stdio app-server プロセスから削除される追加の環境変数名。 | -| `requestTimeoutMs` | `60000` | app-server コントロールプレーン呼び出しのタイムアウト。 | -| `mode` | `"yolo"` | YOLO 実行または guardian レビュー付き実行のプリセット。 | -| `approvalPolicy` | `"never"` | スレッドの開始、再開、ターンに送信されるネイティブ Codex 承認ポリシー。 | -| `sandbox` | `"danger-full-access"` | スレッドの開始、再開に送信されるネイティブ Codex サンドボックスモード。 | -| `approvalsReviewer` | `"user"` | Codex にネイティブ承認プロンプトをレビューさせるには `"auto_review"` を使用します。`guardian_subagent` は従来のエイリアスのままです。 | -| `serviceTier` | 未設定 | 任意の Codex app-server サービス階層: `"fast"`、`"flex"`、または `null`。無効な従来値は無視されます。 | +| フィールド | デフォルト | 意味 | +| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` は Codex を起動します。`"websocket"` は `url` に接続します。 | +| `command` | 管理対象の Codex バイナリ | stdio トランスポート用の実行ファイル。管理対象バイナリを使う場合は未設定のままにします。明示的に上書きする場合にのみ設定してください。 | +| `args` | `["app-server", "--listen", "stdio://"]` | stdio トランスポート用の引数。 | +| `url` | 未設定 | WebSocket app-server URL。 | +| `authToken` | 未設定 | WebSocket トランスポート用の Bearer トークン。 | +| `headers` | `{}` | 追加の WebSocket ヘッダー。 | +| `clearEnv` | `[]` | OpenClaw が継承環境を構築したあと、起動された stdio app-server プロセスから削除される追加の環境変数名。`CODEX_HOME` と `HOME` は、ローカル起動時の OpenClaw のエージェントごとの Codex 分離用に予約されています。 | +| `requestTimeoutMs` | `60000` | app-server コントロールプレーン呼び出しのタイムアウト。 | +| `mode` | `"yolo"` | YOLO または guardian レビュー付き実行のプリセット。 | +| `approvalPolicy` | `"never"` | スレッドの開始、再開、ターンに送信されるネイティブ Codex 承認ポリシー。 | +| `sandbox` | `"danger-full-access"` | スレッドの開始、再開に送信されるネイティブ Codex サンドボックスモード。 | +| `approvalsReviewer` | `"user"` | Codex にネイティブ承認プロンプトをレビューさせるには `"auto_review"` を使います。`guardian_subagent` は従来のエイリアスとして残っています。 | +| `serviceTier` | 未設定 | 任意の Codex app-server サービスティア: `"fast"`、`"flex"`、または `null`。無効な従来の値は無視されます。 | -OpenClaw 所有の動的ツール呼び出しは、`appServer.requestTimeoutMs` とは独立して制限されます。各 Codex `item/tool/call` リクエストは、30 秒以内に OpenClaw の応答を受け取る必要があります。タイムアウト時、OpenClaw はサポートされている場合はツールシグナルを中止し、失敗した動的ツール応答を Codex に返すことで、セッションを `processing` のままにせずターンを続行できるようにします。 +OpenClaw が所有する動的ツール呼び出しは、`appServer.requestTimeoutMs` とは +独立して制限されます。各 Codex `item/tool/call` リクエストは、30 秒以内に +OpenClaw のレスポンスを受け取る必要があります。タイムアウト時、OpenClaw は対応している場合にツール +シグナルを中止し、失敗した動的ツールレスポンスを Codex に返すため、 +セッションを `processing` のまま残す代わりにターンを続行できます。 -OpenClaw が Codex のターンスコープ app-server リクエストに応答した後、ハーネスは Codex がネイティブターンを `turn/completed` で完了することも想定します。その応答後に app-server が 60 秒間沈黙した場合、OpenClaw はベストエフォートで Codex ターンに割り込み、診断タイムアウトを記録し、OpenClaw セッションレーンを解放して、後続のチャットメッセージが古いネイティブターンの後ろでキューに入らないようにします。 +OpenClaw が Codex のターンスコープ app-server リクエストに応答したあと、ハーネスは +Codex がネイティブターンを `turn/completed` で完了することも期待します。その +応答後に app-server が 60 秒間無応答になった場合、OpenClaw はベストエフォートで +Codex ターンに割り込み、診断タイムアウトを記録し、 +OpenClaw セッションレーンを解放して、後続のチャットメッセージが古い +ネイティブターンの背後にキューされないようにします。 -環境上書きはローカルテストで引き続き使用できます。 +ローカルテストでは環境による上書きが引き続き利用できます。 - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -529,18 +486,29 @@ OpenClaw が Codex のターンスコープ app-server リクエストに応答 - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`appServer.command` が未設定の場合、`OPENCLAW_CODEX_APP_SERVER_BIN` は管理対象バイナリを迂回します。 +`OPENCLAW_CODEX_APP_SERVER_BIN` は、`appServer.command` が未設定の場合に +管理対象バイナリをバイパスします。 -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` は削除されました。代わりに `plugins.entries.codex.config.appServer.mode: "guardian"` を使用するか、単発のローカルテストでは `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` を使用してください。反復可能なデプロイでは設定を使うことが推奨されます。これにより、Plugin の動作が Codex ハーネス設定の他の部分と同じレビュー済みファイルに保持されるためです。 +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` は削除されました。代わりに +`plugins.entries.codex.config.appServer.mode: "guardian"` を使うか、 +一回限りのローカルテストでは `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` を使います。繰り返し可能なデプロイでは、 +Codex ハーネス設定の他の部分と同じレビュー済みファイルに Plugin の動作を保持できるため、 +設定を使うことが推奨されます。 ## コンピューター使用 -コンピューター使用については、専用の設定ガイドで説明しています。 -[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use)。 +Computer Use は専用のセットアップガイドで扱います: +[Codex Computer Use](/ja-JP/plugins/codex-computer-use)。 -要約すると、OpenClaw はデスクトップ制御アプリをベンダー化せず、デスクトップアクション自体も実行しません。Codex app-server を準備し、`computer-use` MCP サーバーが使用可能であることを確認してから、Codex モードのターン中にネイティブ MCP ツール呼び出しの処理を Codex に任せます。 +短く言えば、OpenClaw はデスクトップ制御アプリをベンダー提供せず、デスクトップ操作も +自ら実行しません。OpenClaw は Codex app-server を準備し、 +`computer-use` MCP サーバーが利用可能であることを検証してから、Codex モードのターン中に +ネイティブ MCP ツール呼び出しを Codex に処理させます。 -Codex marketplace フローの外で TryCua ドライバーに直接アクセスするには、`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` で `cua-driver mcp` を登録します。Codex 所有のコンピューター使用と直接 MCP 登録の違いについては、[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use) を参照してください。 +Codex marketplace フロー外で TryCua ドライバーに直接アクセスするには、 +`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` で +`cua-driver mcp` を登録します。Codex が所有する Computer Use と直接 MCP 登録の違いについては、 +[Codex Computer Use](/ja-JP/plugins/codex-computer-use) を参照してください。 最小設定: @@ -570,20 +538,30 @@ Codex marketplace フローの外で TryCua ドライバーに直接アクセス } ``` -設定はコマンドサーフェスから確認またはインストールできます。 +セットアップはコマンド面から確認またはインストールできます。 - `/codex computer-use status` - `/codex computer-use install` - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -コンピューター使用は macOS 固有であり、Codex MCP サーバーがアプリを制御できるようになる前にローカル OS 権限が必要になる場合があります。`computerUse.enabled` が true で MCP サーバーが使用できない場合、Codex モードのターンは、ネイティブのコンピューター使用ツールなしで黙って実行されるのではなく、スレッドが開始される前に失敗します。marketplace の選択肢、リモートカタログの制限、ステータス理由、トラブルシューティングについては、[Codex コンピューター使用](/ja-JP/plugins/codex-computer-use) を参照してください。 +Computer Use は macOS 固有で、Codex MCP サーバーがアプリを制御できるようになる前に +ローカル OS 権限が必要になる場合があります。`computerUse.enabled` が true で MCP +サーバーが利用できない場合、Codex モードのターンは、ネイティブ Computer Use ツールなしで +黙って実行されるのではなく、スレッド開始前に失敗します。marketplace の選択肢、 +リモートカタログの制限、ステータス理由、トラブルシューティングについては +[Codex Computer Use](/ja-JP/plugins/codex-computer-use) を参照してください。 -`computerUse.autoInstall` が true の場合、Codex がまだローカル marketplace を検出していなければ、OpenClaw は `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` から標準バンドルの Codex Desktop marketplace を登録できます。ランタイムまたはコンピューター使用の設定を変更した後は、既存セッションが古い PI または Codex スレッドバインディングを保持しないように、`/new` または `/reset` を使用してください。 +`computerUse.autoInstall` が true の場合、Codex がまだローカル marketplace を検出していなければ、 +OpenClaw は +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` から標準の +バンドル済み Codex Desktop marketplace を登録できます。ランタイムまたは Computer Use 設定を変更したあとは、 +既存のセッションが古い PI または Codex スレッドバインディングを保持しないように、 +`/new` または `/reset` を使います。 ## 一般的なレシピ -デフォルトの stdio トランスポートを使用するローカル Codex: +デフォルトの stdio トランスポートを使うローカル Codex: ```json5 { @@ -597,7 +575,7 @@ Codex marketplace フローの外で TryCua ドライバーに直接アクセス } ``` -Codex のみのハーネス検証: +Codex 専用ハーネス検証: ```json5 { @@ -641,7 +619,7 @@ guardian レビュー付き Codex 承認: } ``` -明示的なヘッダーを使用するリモート app-server: +明示的なヘッダーを持つリモート app-server: ```json5 { @@ -664,145 +642,157 @@ guardian レビュー付き Codex 承認: } ``` -モデル切り替えは OpenClaw が制御します。OpenClaw セッションが既存の Codex スレッドに接続されている場合、次のターンは現在選択されている OpenAI モデル、プロバイダー、承認ポリシー、サンドボックス、サービス階層を app-server に再送信します。`openai/gpt-5.5` から `openai/gpt-5.2` に切り替えてもスレッドバインディングは維持されますが、新しく選択されたモデルで続行するよう Codex に要求します。 +モデル切り替えは OpenClaw が制御したままです。OpenClaw セッションが +既存の Codex スレッドにアタッチされている場合、次のターンは現在選択されている +OpenAI モデル、プロバイダー、承認ポリシー、サンドボックス、サービスティアを +app-server に再送信します。`openai/gpt-5.5` から `openai/gpt-5.2` に切り替えると、 +スレッドバインディングは保持されますが、新しく選択されたモデルで続行するよう Codex に要求します。 ## Codex コマンド -バンドルされた Plugin は、認可済みスラッシュコマンドとして `/codex` を登録します。これは汎用であり、OpenClaw テキストコマンドをサポートする任意のチャンネルで動作します。 +バンドルされた Plugin は、`/codex` を承認済みスラッシュコマンドとして登録します。これは +汎用であり、OpenClaw テキストコマンドに対応する任意のチャンネルで動作します。 一般的な形式: -- `/codex status` は、ライブ app-server 接続、モデル、アカウント、レート制限、MCP サーバー、Skills を表示します。 +- `/codex status` は、ライブ app-server 接続性、モデル、アカウント、レート制限、MCP サーバー、Skills を表示します。 - `/codex models` は、ライブ Codex app-server モデルを一覧表示します。 - `/codex threads [filter]` は、最近の Codex スレッドを一覧表示します。 -- `/codex resume ` は、現在の OpenClaw セッションを既存の Codex スレッドに接続します。 -- `/codex compact` は、接続されたスレッドをコンパクト化するよう Codex app-server に要求します。 -- `/codex review` は、接続されたスレッドに対して Codex ネイティブレビューを開始します。 -- `/codex diagnostics [note]` は、接続されたスレッドの Codex 診断フィードバックを送信する前に確認します。 -- `/codex computer-use status` は、設定済みのコンピューター使用 Plugin と MCP サーバーを確認します。 -- `/codex computer-use install` は、設定済みのコンピューター使用 Plugin をインストールし、MCP サーバーを再読み込みします。 +- `/codex resume ` は、現在の OpenClaw セッションを既存の Codex スレッドにアタッチします。 +- `/codex compact` は、アタッチされたスレッドを compact するよう Codex app-server に依頼します。 +- `/codex review` は、アタッチされたスレッドの Codex ネイティブレビューを開始します。 +- `/codex diagnostics [note]` は、アタッチされたスレッドの Codex 診断フィードバックを送信する前に確認します。 +- `/codex computer-use status` は、設定済みの Computer Use Plugin と MCP サーバーを確認します。 +- `/codex computer-use install` は、設定済みの Computer Use Plugin をインストールし、MCP サーバーをリロードします。 - `/codex account` は、アカウントとレート制限のステータスを表示します。 - `/codex mcp` は、Codex app-server MCP サーバーのステータスを一覧表示します。 - `/codex skills` は、Codex app-server skills を一覧表示します。 ### 一般的なデバッグワークフロー -Codex バックエンドのエージェントが Telegram、Discord、Slack、または別のチャンネルで予期しないことをした場合は、問題が発生した会話から始めます。 +Codex ベースのエージェントが Telegram、Discord、Slack、 +または別のチャンネルで予想外の動作をした場合は、問題が発生した会話から開始します。 -1. `/diagnostics bad tool choice after image upload`、または見た内容を説明する別の短いメモを実行します。 -2. 診断リクエストを一度承認します。承認によりローカル Gateway 診断 zip が作成され、セッションが Codex ハーネスを使用しているため、関連する Codex フィードバックバンドルも OpenAI サーバーに送信されます。 -3. 完了した診断返信をバグレポートまたはサポートスレッドにコピーします。これには、ローカルバンドルパス、プライバシー概要、OpenClaw セッション ID、Codex スレッド ID、および各 Codex スレッドの `Inspect locally` 行が含まれます。 -4. 実行を自分でデバッグしたい場合は、表示された `Inspect locally` コマンドをターミナルで実行します。これは `codex resume ` のような形で、ネイティブ Codex スレッドを開くため、会話を調査したり、ローカルで続行したり、特定のツールや計画を選んだ理由を Codex に尋ねたりできます。 +1. 見た内容を説明する `/diagnostics bad tool choice after image upload` または別の短いメモを実行します。 +2. 診断リクエストを一度承認します。この承認によりローカル Gateway + 診断 zip が作成され、セッションが Codex ハーネスを使用しているため、 + 関連する Codex フィードバックバンドルも OpenAI サーバーに送信されます。 +3. 完了した診断返信をバグレポートまたはサポートスレッドにコピーします。 + そこには、ローカルバンドルパス、プライバシー概要、OpenClaw セッション ID、 + Codex スレッド ID、および各 Codex スレッドの `Inspect locally` 行が含まれます。 +4. 自分で実行をデバッグしたい場合は、表示された `Inspect locally` + コマンドをターミナルで実行します。これは `codex resume ` のような形で、 + ネイティブ Codex スレッドを開くため、会話を調査したり、ローカルで続行したり、 + Codex が特定のツールや計画を選んだ理由を Codex に尋ねたりできます。 -現在接続されているスレッドについて、完全な OpenClaw Gateway 診断バンドルなしで Codex フィードバックアップロードのみを明示的に行いたい場合にだけ、`/codex diagnostics [note]` を使用してください。ほとんどのサポートレポートでは、ローカル Gateway 状態と Codex スレッド ID を 1 つの返信にまとめられるため、`/diagnostics [note]` がより良い開始点です。完全なプライバシーモデルとグループチャットでの動作については、[診断エクスポート](/ja-JP/gateway/diagnostics) を参照してください。 +`/codex diagnostics [note]` は、OpenClaw Gateway 診断バンドル全体なしで、現在アタッチされているスレッドの Codex フィードバックアップロードだけを明示的に必要とする場合にのみ使用します。ほとんどのサポートレポートでは、`/diagnostics [note]` のほうが適切な開始点です。これは、ローカル Gateway の状態と Codex スレッド ID を 1 つの返信で結び付けるためです。完全なプライバシーモデルとグループチャットの動作については、[診断エクスポート](/ja-JP/gateway/diagnostics)を参照してください。 -OpenClaw コアは、一般的な Gateway 診断コマンドとして、所有者専用の `/diagnostics [note]` も公開しています。その承認プロンプトには、機密データの前置き、[診断エクスポート](/ja-JP/gateway/diagnostics) へのリンクが表示され、毎回明示的な exec 承認を通じて `openclaw gateway diagnostics export --json` を要求します。allow-all ルールで診断を承認しないでください。承認後、OpenClaw はローカルバンドルパスとマニフェスト概要を含む貼り付け可能なレポートを送信します。アクティブな OpenClaw セッションが Codex ハーネスを使用している場合、その同じ承認により、関連する Codex フィードバックバンドルを OpenAI サーバーに送信することも認可されます。承認プロンプトには Codex フィードバックが送信されることが記載されますが、承認前には Codex セッション ID やスレッド ID は一覧表示されません。 +Core OpenClaw は、一般的な Gateway 診断コマンドとして、オーナー専用の `/diagnostics [note]` も公開しています。その承認プロンプトには機微データに関する前文が表示され、[診断エクスポート](/ja-JP/gateway/diagnostics)へのリンクがあり、毎回、明示的な exec 承認を通じて `openclaw gateway diagnostics export --json` を要求します。allow-all ルールで診断を承認しないでください。承認後、OpenClaw はローカルバンドルパスとマニフェスト概要を含む貼り付け可能なレポートを送信します。アクティブな OpenClaw セッションが Codex ハーネスを使用している場合、同じ承認により、関連する Codex フィードバックバンドルを OpenAI サーバーへ送信することも許可されます。承認プロンプトには Codex フィードバックが送信されることが記載されますが、承認前に Codex セッション ID やスレッド ID は表示されません。 -`/diagnostics` がグループチャットで所有者によって呼び出された場合、OpenClaw は共有チャンネルをクリーンに保ちます。グループには短い通知のみが送られ、診断の前置き、承認プロンプト、Codex セッション/スレッド ID はプライベート承認ルート経由で所有者に送信されます。プライベート所有者ルートがない場合、OpenClaw はグループリクエストを拒否し、DM から実行するよう所有者に求めます。 +グループチャットでオーナーが `/diagnostics` を呼び出した場合、OpenClaw は共有チャンネルをクリーンに保ちます。グループには短い通知だけが届き、診断の前文、承認プロンプト、Codex セッション/スレッド ID はプライベート承認ルートを通じてオーナーに送信されます。プライベートなオーナールートがない場合、OpenClaw はグループでの要求を拒否し、DM から実行するようオーナーに求めます。 -承認された Codex アップロードは Codex app-server の `feedback/upload` を呼び出し、利用可能な場合は、リストされた各スレッドと生成された Codex サブスレッドのログを含めるよう app-server に要求します。アップロードは Codex の通常のフィードバック経路を通じて OpenAI サーバーへ送信されます。その app-server で Codex フィードバックが無効になっている場合、コマンドは app-server エラーを返します。完了した診断の返信には、送信されたスレッドについて、チャンネル、OpenClaw セッション ID、Codex スレッド ID、ローカルの `codex resume ` コマンドが一覧表示されます。承認を拒否または無視した場合、OpenClaw はそれらの Codex ID を出力しません。このアップロードはローカルの Gateway 診断エクスポートを置き換えるものではありません。 +承認された Codex アップロードは、Codex app-server の `feedback/upload` を呼び出し、一覧に含まれる各スレッドと、利用可能な場合は生成された Codex サブスレッドのログを含めるよう app-server に要求します。アップロードは Codex の通常のフィードバック経路を通じて OpenAI サーバーへ送信されます。その app-server で Codex フィードバックが無効になっている場合、コマンドは app-server エラーを返します。完了した診断返信には、送信されたスレッドについて、チャンネル、OpenClaw セッション ID、Codex スレッド ID、ローカルの `codex resume ` コマンドが一覧表示されます。承認を拒否または無視した場合、OpenClaw はそれらの Codex ID を出力しません。このアップロードは、ローカル Gateway 診断エクスポートの代替ではありません。 -`/codex resume` は、通常のターンでハーネスが使用するものと同じサイドカーのバインディングファイルを書き込みます。次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw モデルを app-server に渡し、拡張履歴を有効なままにします。 +`/codex resume` は、通常のターンでハーネスが使用するものと同じサイドカー束縛ファイルを書き込みます。次のメッセージで、OpenClaw はその Codex スレッドを再開し、現在選択されている OpenClaw モデルを app-server に渡し、拡張履歴を有効に保ちます。 -### CLI から Codex スレッドを調べる +### CLI から Codex スレッドを調査する -問題のある Codex 実行を理解する最速の方法は、ネイティブの Codex スレッドを直接開くことです。 +問題のある Codex 実行を理解する最速の方法は、多くの場合、ネイティブの Codex スレッドを直接開くことです。 ```sh codex resume ``` -チャンネル会話でバグに気づき、問題の Codex セッションを調べる、ローカルで続行する、または特定のツールや推論の選択を行った理由を Codex に尋ねる場合に使用します。通常、最も簡単な方法は先に `/diagnostics [note]` を実行することです。承認後、完了したレポートには各 Codex スレッドが一覧表示され、たとえば `codex resume ` のような `Inspect locally` コマンドが出力されます。そのコマンドをそのままターミナルにコピーできます。 +チャンネル会話でバグに気付き、問題のある Codex セッションを調査したい場合、ローカルで続行したい場合、または特定のツールや推論の選択をした理由を Codex に尋ねたい場合に使用します。通常、最も簡単な手順は、先に `/diagnostics [note]` を実行することです。承認後、完了したレポートには各 Codex スレッドが一覧表示され、たとえば `codex resume ` のような `Inspect locally` コマンドが出力されます。そのコマンドをそのままターミナルにコピーできます。 現在のチャットについては `/codex binding` から、最近の Codex app-server スレッドについては `/codex threads [filter]` からスレッド ID を取得し、シェルで同じ `codex resume` コマンドを実行することもできます。 -このコマンドサーフェスには Codex app-server `0.125.0` 以降が必要です。将来版またはカスタムの app-server がその JSON-RPC メソッドを公開していない場合、個々の制御メソッドは `unsupported by this Codex app-server` として報告されます。 +このコマンドサーフェスには Codex app-server `0.125.0` 以降が必要です。将来の app-server またはカスタム app-server がその JSON-RPC メソッドを公開していない場合、個々の制御メソッドは `unsupported by this Codex app-server` と報告されます。 ## フック境界 -Codex ハーネスには 3 つのフックレイヤーがあります。 +Codex ハーネスには 3 つのフック層があります。 -| レイヤー | 所有者 | 目的 | +| 層 | オーナー | 目的 | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw Plugin フック | OpenClaw | PI と Codex ハーネス間の製品/Plugin 互換性。 | -| Codex app-server 拡張ミドルウェア | OpenClaw 同梱 Plugin | OpenClaw 動的ツール周辺のターンごとのアダプター動作。 | -| Codex ネイティブフック | Codex | Codex 設定からの低レベル Codex ライフサイクルとネイティブツールポリシー。 | +| OpenClaw Plugin フック | OpenClaw | PI と Codex ハーネス全体での製品/Plugin 互換性。 | +| Codex app-server 拡張ミドルウェア | OpenClaw バンドル Plugin | OpenClaw 動的ツール周辺のターンごとのアダプター動作。 | +| Codex ネイティブフック | Codex | Codex 設定からの低レベル Codex ライフサイクルとネイティブツールポリシー。 | -OpenClaw は、OpenClaw Plugin の動作をルーティングするためにプロジェクトまたはグローバルの Codex `hooks.json` ファイルを使用しません。サポートされるネイティブツールと権限ブリッジについては、OpenClaw は `PreToolUse`、`PostToolUse`、`PermissionRequest`、`Stop` 用のスレッド単位の Codex 設定を注入します。`SessionStart` や `UserPromptSubmit` など、その他の Codex フックは Codex レベルの制御のままです。これらは v1 コントラクトでは OpenClaw Plugin フックとして公開されません。 +OpenClaw は、OpenClaw Plugin の動作をルーティングするために、プロジェクトまたはグローバルの Codex `hooks.json` ファイルを使用しません。サポートされるネイティブツールと権限ブリッジについて、OpenClaw は `PreToolUse`、`PostToolUse`、`PermissionRequest`、`Stop` 用に、スレッドごとの Codex 設定を注入します。`SessionStart` や `UserPromptSubmit` などの他の Codex フックは Codex レベルの制御のままです。これらは v1 契約では OpenClaw Plugin フックとして公開されません。 -OpenClaw 動的ツールについては、Codex が呼び出しを要求した後に OpenClaw がツールを実行するため、OpenClaw はハーネスアダプター内で所有する Plugin とミドルウェアの動作を発火します。Codex ネイティブツールについては、Codex が正規のツールレコードを所有します。OpenClaw は選択されたイベントをミラーできますが、Codex が app-server またはネイティブフックコールバックを通じてその操作を公開しない限り、ネイティブ Codex スレッドを書き換えることはできません。 +OpenClaw 動的ツールでは、Codex が呼び出しを要求した後に OpenClaw がツールを実行するため、OpenClaw は自分が所有する Plugin とミドルウェアの動作をハーネスアダプター内で発火します。Codex ネイティブツールでは、Codex が正規のツールレコードを所有します。OpenClaw は選択されたイベントをミラーできますが、Codex が app-server またはネイティブフックコールバックを通じてその操作を公開しない限り、ネイティブ Codex スレッドを書き換えることはできません。 -Compaction と LLM ライフサイクルの投影は、ネイティブ Codex フックコマンドではなく、Codex app-server 通知と OpenClaw アダプター状態から得られます。OpenClaw の `before_compaction`、`after_compaction`、`llm_input`、`llm_output` イベントはアダプターレベルの観測であり、Codex 内部のリクエストまたは Compaction ペイロードをバイト単位で取得したものではありません。 +Compaction と LLM ライフサイクル投影は、ネイティブ Codex フックコマンドではなく、Codex app-server 通知と OpenClaw アダプター状態から得られます。OpenClaw の `before_compaction`、`after_compaction`、`llm_input`、`llm_output` イベントはアダプターレベルの観測であり、Codex の内部リクエストや Compaction ペイロードをバイト単位で取得したものではありません。 -Codex ネイティブの `hook/started` と `hook/completed` app-server 通知は、軌跡とデバッグ用の `codex_app_server.hook` エージェントイベントとして投影されます。これらは OpenClaw Plugin フックを呼び出しません。 +Codex ネイティブの `hook/started` および `hook/completed` app-server 通知は、軌跡とデバッグ用に `codex_app_server.hook` エージェントイベントとして投影されます。これらは OpenClaw Plugin フックを呼び出しません。 -## V1 サポートコントラクト +## V1 サポート契約 -Codex モードは、内部のモデル呼び出しだけを変更した PI ではありません。Codex はネイティブモデルループのより多くを所有し、OpenClaw はその境界に合わせて Plugin とセッションサーフェスを適応させます。 +Codex モードは、下層のモデル呼び出しだけが異なる PI ではありません。Codex はネイティブモデルループのより多くを所有し、OpenClaw はその境界に合わせて Plugin とセッションのサーフェスを適応させます。 -Codex ランタイム v1 でサポートされるもの: +Codex runtime v1 でサポートされるもの: -| サーフェス | サポート | 理由 | +| サーフェス | サポート | 理由 | | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Codex 経由の OpenAI モデルループ | サポート | Codex app-server が OpenAI ターン、ネイティブスレッドの再開、ネイティブツールの継続を所有します。 | -| OpenClaw チャンネルルーティングと配信 | サポート | Telegram、Discord、Slack、WhatsApp、iMessage、その他のチャンネルはモデルランタイムの外側に留まります。 | -| OpenClaw 動的ツール | サポート | Codex が OpenClaw にこれらのツールの実行を依頼するため、OpenClaw は実行経路に留まります。 | -| プロンプトとコンテキストの Plugin | サポート | OpenClaw はスレッドの開始または再開前に、プロンプトオーバーレイを構築し、コンテキストを Codex ターンへ投影します。 | -| コンテキストエンジンのライフサイクル | サポート | Codex ターンでは、組み立て、取り込みまたはターン後メンテナンス、コンテキストエンジンの Compaction 調整が実行されます。 | -| 動的ツールフック | サポート | `before_tool_call`、`after_tool_call`、およびツール結果ミドルウェアは、OpenClaw が所有する動的ツールの周辺で実行されます。 | -| ライフサイクルフック | アダプター観測としてサポート | `llm_input`、`llm_output`、`agent_end`、`before_compaction`、`after_compaction` は、Codex モードに忠実なペイロードで発火します。 | -| 最終回答の修正ゲート | ネイティブフックリレー経由でサポート | Codex `Stop` は `before_agent_finalize` に中継されます。`revise` は最終化前にもう 1 回モデルパスを行うよう Codex に要求します。 | -| ネイティブ shell、patch、MCP のブロックまたは観測 | ネイティブフックリレー経由でサポート | Codex `PreToolUse` と `PostToolUse` は、Codex app-server `0.125.0` 以降の MCP ペイロードを含む、コミット済みのネイティブツールサーフェスに中継されます。ブロックはサポートされますが、引数の書き換えはサポートされません。 | -| ネイティブ権限ポリシー | ネイティブフックリレー経由でサポート | Codex `PermissionRequest` は、ランタイムが公開する場合、OpenClaw ポリシーを通じてルーティングできます。OpenClaw が判断を返さない場合、Codex は通常のガーディアンまたはユーザー承認経路を続行します。 | -| App-server 軌跡キャプチャ | サポート | OpenClaw は app-server に送信したリクエストと、受信した app-server 通知を記録します。 | +| Codex 経由の OpenAI モデルループ | サポート | Codex app-server が OpenAI ターン、ネイティブスレッド再開、ネイティブツール継続を所有します。 | +| OpenClaw チャンネルルーティングと配信 | サポート | Telegram、Discord、Slack、WhatsApp、iMessage、その他のチャンネルはモデル runtime の外側に残ります。 | +| OpenClaw 動的ツール | サポート | Codex は OpenClaw にこれらのツールの実行を依頼するため、OpenClaw は実行経路内に残ります。 | +| プロンプトとコンテキスト Plugin | サポート | OpenClaw はプロンプトオーバーレイを構築し、スレッドの開始または再開前にコンテキストを Codex ターンへ投影します。 | +| コンテキストエンジンライフサイクル | サポート | Codex ターンでは、組み立て、取り込みまたはターン後メンテナンス、コンテキストエンジン Compaction 調整が実行されます。 | +| 動的ツールフック | サポート | `before_tool_call`、`after_tool_call`、ツール結果ミドルウェアは、OpenClaw 所有の動的ツールの周辺で実行されます。 | +| ライフサイクルフック | アダプター観測としてサポート | `llm_input`、`llm_output`、`agent_end`、`before_compaction`、`after_compaction` は、正直な Codex モードペイロードで発火します。 | +| 最終回答修正ゲート | ネイティブフックリレーを通じてサポート | Codex `Stop` は `before_agent_finalize` にリレーされます。`revise` は最終化前にもう 1 回のモデルパスを Codex に要求します。 | +| ネイティブシェル、パッチ、MCP のブロックまたは観測 | ネイティブフックリレーを通じてサポート | Codex `PreToolUse` と `PostToolUse` は、Codex app-server `0.125.0` 以降での MCP ペイロードを含め、確定済みのネイティブツールサーフェスに対してリレーされます。ブロックはサポートされますが、引数の書き換えはサポートされません。 | +| ネイティブ権限ポリシー | ネイティブフックリレーを通じてサポート | Codex `PermissionRequest` は、runtime が公開している場合、OpenClaw ポリシーを通じてルーティングできます。OpenClaw が決定を返さない場合、Codex は通常の guardian またはユーザー承認経路を通じて続行します。 | +| App-server 軌跡キャプチャ | サポート | OpenClaw は app-server に送信したリクエストと、受信した app-server 通知を記録します。 | -Codex ランタイム v1 でサポートされないもの: +Codex runtime v1 でサポートされないもの: -| サーフェス | V1 境界 | 将来の経路 | +| サーフェス | V1 境界 | 将来のパス | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| ネイティブツール引数の変更 | Codex ネイティブのプリツールフックはブロックできますが、OpenClaw は Codex ネイティブツールの引数を書き換えません。 | 置換ツール入力のための Codex フック/スキーマサポートが必要です。 | -| 編集可能な Codex ネイティブのトランスクリプト履歴 | Codex が正規のネイティブスレッド履歴を所有します。OpenClaw はミラーを所有し、将来のコンテキストを投影できますが、サポートされていない内部状態を変更すべきではありません。 | ネイティブスレッドの手術が必要な場合は、明示的な Codex app-server API を追加します。 | -| Codex ネイティブツールレコード用の `tool_result_persist` | そのフックは OpenClaw が所有するトランスクリプト書き込みを変換するものであり、Codex ネイティブツールレコードを変換するものではありません。 | 変換済みレコードをミラーすることは可能ですが、正規の書き換えには Codex のサポートが必要です。 | -| リッチなネイティブ Compaction メタデータ | OpenClaw は Compaction の開始と完了を観測しますが、安定した保持/破棄リスト、トークン差分、または要約ペイロードを受け取りません。 | よりリッチな Codex Compaction イベントが必要です。 | -| Compaction への介入 | 現在の OpenClaw Compaction フックは Codex モードでは通知レベルです。 | Plugin がネイティブ Compaction を拒否または書き換える必要がある場合は、Codex の Compaction 前後フックを追加します。 | -| バイト単位のモデル API リクエストキャプチャ | OpenClaw は app-server リクエストと通知をキャプチャできますが、Codex core が最終的な OpenAI API リクエストを内部で構築します。 | Codex モデルリクエストトレースイベントまたはデバッグ API が必要です。 | +| ネイティブツール引数の変更 | Codex ネイティブのツール前フックはブロックできるが、OpenClaw は Codex ネイティブのツール引数を書き換えない。 | 置換用ツール入力には Codex のフック/スキーマサポートが必要。 | +| 編集可能な Codex ネイティブのトランスクリプト履歴 | Codex が正規のネイティブスレッド履歴を所有する。OpenClaw はミラーを所有し、将来のコンテキストを投影できるが、サポートされていない内部状態を変更すべきではない。 | ネイティブスレッドの手術が必要な場合は、明示的な Codex app-server API を追加する。 | +| Codex ネイティブツールレコード向けの `tool_result_persist` | そのフックは OpenClaw が所有するトランスクリプト書き込みを変換するものであり、Codex ネイティブのツールレコードを変換するものではない。 | 変換済みレコードをミラーできる可能性はあるが、正規の書き換えには Codex のサポートが必要。 | +| リッチなネイティブ Compaction メタデータ | OpenClaw は Compaction の開始と完了を観測するが、安定した保持/破棄リスト、トークン差分、または要約ペイロードは受け取らない。 | よりリッチな Codex Compaction イベントが必要。 | +| Compaction 介入 | 現在の OpenClaw Compaction フックは Codex モードでは通知レベル。 | Plugin がネイティブ Compaction を拒否または書き換える必要がある場合は、Codex の Compaction 前後フックを追加する。 | +| バイト単位で同一のモデル API リクエストキャプチャ | OpenClaw は app-server のリクエストと通知をキャプチャできるが、Codex コアは最終的な OpenAI API リクエストを内部で構築する。 | Codex のモデルリクエストトレースイベントまたはデバッグ API が必要。 | ## ツール、メディア、Compaction -Codex ハーネスは低レベルの埋め込みエージェント実行器のみを変更します。 +Codex ハーネスは、低レベルの組み込みエージェント実行器のみを変更する。 -OpenClaw は引き続きツールリストを構築し、ハーネスから動的ツール結果を受け取ります。テキスト、画像、動画、音楽、TTS、承認、メッセージングツールの出力は、通常の OpenClaw 配信経路を引き続き通過します。 +OpenClaw は引き続きツールリストを構築し、ハーネスから動的ツール結果を受け取る。テキスト、画像、動画、音楽、TTS、承認、メッセージングツールの出力は、通常の OpenClaw 配信パスを通り続ける。 -ネイティブフックリレーは意図的に汎用的ですが、v1 サポートコントラクトは OpenClaw がテストする Codex ネイティブツールおよび権限経路に限定されています。Codex ランタイムでは、これに shell、patch、MCP の `PreToolUse`、`PostToolUse`、`PermissionRequest` ペイロードが含まれます。ランタイムコントラクトが名前を挙げるまでは、将来のすべての Codex フックイベントが OpenClaw Plugin サーフェスであると想定しないでください。 +ネイティブフックリレーは意図的に汎用的だが、v1 のサポート契約は OpenClaw がテストする Codex ネイティブのツールと権限のパスに限定される。Codex ランタイムでは、これに shell、patch、MCP の `PreToolUse`、`PostToolUse`、`PermissionRequest` ペイロードが含まれる。ランタイム契約で名前が示されるまでは、将来のすべての Codex フックイベントが OpenClaw Plugin サーフェスであると想定しないこと。 -`PermissionRequest` について、OpenClaw はポリシーが判断した場合にのみ、明示的な許可または拒否の判断を返します。判断なしの結果は許可ではありません。Codex はそれをフック判断なしとして扱い、独自のガーディアンまたはユーザー承認経路にフォールスルーします。 +`PermissionRequest` について、OpenClaw はポリシーが判断した場合にのみ明示的な許可または拒否の決定を返す。決定なしの結果は許可ではない。Codex はそれをフック決定なしとして扱い、独自のガーディアンまたはユーザー承認パスへフォールスルーする。 -Codex MCP ツール承認の聞き取りは、Codex が `_meta.codex_approval_kind` を `"mcp_tool_call"` としてマークした場合、OpenClaw の Plugin 承認フローを通じてルーティングされます。Codex の `request_user_input` プロンプトは元のチャットに送信され、次にキューに入ったフォローアップメッセージは追加コンテキストとして誘導されるのではなく、そのネイティブサーバーリクエストへの回答になります。その他の MCP 聞き取りリクエストは引き続きフェイルクローズされます。 +Codex MCP ツール承認の elicitation は、Codex が `_meta.codex_approval_kind` を `"mcp_tool_call"` としてマークした場合、OpenClaw の Plugin 承認フローを通じてルーティングされる。Codex の `request_user_input` プロンプトは元のチャットへ送り返され、次にキューされたフォローアップメッセージは、追加コンテキストとしてステアリングされる代わりに、そのネイティブサーバーリクエストに回答する。他の MCP elicitation リクエストは引き続き fail closed する。 -Active-run キューのステアリングは、Codex app-server の `turn/steer` に対応します。 -デフォルトの `messages.queue.mode: "steer"` では、OpenClaw は設定された静音ウィンドウの間、キューに入ったチャットメッセージをまとめ、到着順に 1 つの `turn/steer` リクエストとして送信します。レガシーの `queue` モードでは、個別の `turn/steer` リクエストを送信します。Codex のレビューターンと手動 Compaction ターンでは、同一ターンのステアリングが拒否される場合があります。その場合、選択されたモードがフォールバックを許可していれば、OpenClaw はフォローアップキューを使用します。[ステアリングキュー](/ja-JP/concepts/queue-steering)を参照してください。 +アクティブ実行キューステアリングは Codex app-server の `turn/steer` に対応する。デフォルトの `messages.queue.mode: "steer"` では、OpenClaw は設定された静音ウィンドウの間、キューされたチャットメッセージをまとめ、到着順に 1 つの `turn/steer` リクエストとして送信する。レガシーの `queue` モードは個別の `turn/steer` リクエストを送信する。Codex レビューと手動 Compaction ターンは同一ターンのステアリングを拒否する場合があり、その場合 OpenClaw は選択されたモードでフォールバックが許可されているときにフォローアップキューを使用する。[ステアリングキュー](/ja-JP/concepts/queue-steering)を参照。 -選択されたモデルが Codex ハーネスを使用する場合、ネイティブスレッドの Compaction は Codex app-server に委譲されます。OpenClaw は、チャンネル履歴、検索、`/new`、`/reset`、および将来のモデルまたはハーネスの切り替えのために、トランスクリプトのミラーを保持します。このミラーには、ユーザープロンプト、最終的なアシスタントテキスト、および app-server が出力した場合の軽量な Codex 推論またはプラン記録が含まれます。現時点では、OpenClaw はネイティブ Compaction の開始シグナルと完了シグナルのみを記録します。人間が読める Compaction サマリーや、Compaction 後に Codex が保持したエントリの監査可能な一覧は、まだ公開していません。 +選択したモデルが Codex ハーネスを使用する場合、ネイティブスレッド Compaction は Codex app-server に委任される。OpenClaw はチャンネル履歴、検索、`/new`、`/reset`、および将来のモデルまたはハーネス切り替えのためにトランスクリプトミラーを保持する。ミラーには、ユーザープロンプト、最終アシスタントテキスト、および app-server が出力する場合の軽量な Codex 推論または計画レコードが含まれる。現在、OpenClaw はネイティブ Compaction の開始と完了シグナルのみを記録する。Codex が Compaction 後に保持したエントリーについて、人間が読める Compaction 要約や監査可能なリストはまだ公開していない。 -Codex が正規のネイティブスレッドを所有しているため、`tool_result_persist` は現在 Codex ネイティブのツール結果レコードを書き換えません。これは、OpenClaw が OpenClaw 所有のセッショントランスクリプトのツール結果を書き込む場合にのみ適用されます。 +Codex が正規のネイティブスレッドを所有するため、`tool_result_persist` は現在、Codex ネイティブのツール結果レコードを書き換えない。これは OpenClaw が所有するセッショントランスクリプトのツール結果を OpenClaw が書き込む場合にのみ適用される。 -メディア生成に PI は不要です。画像、動画、音楽、PDF、TTS、およびメディア理解は、引き続き `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel`、`messages.tts` など、対応するプロバイダー/モデル設定を使用します。 +メディア生成に PI は不要。画像、動画、音楽、PDF、TTS、メディア理解は、`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel`、`messages.tts` など、対応するプロバイダー/モデル設定を引き続き使用する。 ## トラブルシューティング -**Codex が通常の `/model` プロバイダーとして表示されない:** 新しい設定では想定どおりです。`agentRuntime.id: "codex"` を指定した `openai/gpt-*` モデル（またはレガシーの `codex/*` 参照）を選択し、`plugins.entries.codex.enabled` を有効にして、`plugins.allow` が `codex` を除外していないか確認してください。 +**Codex が通常の `/model` プロバイダーとして表示されない:** 新しい設定では想定どおり。`agentRuntime.id: "codex"` を指定した `openai/gpt-*` モデル（またはレガシーの `codex/*` ref）を選択し、`plugins.entries.codex.enabled` を有効にし、`plugins.allow` が `codex` を除外していないか確認する。 -**OpenClaw が Codex ではなく PI を使用する:** `agentRuntime.id: "auto"` では、実行を要求する Codex ハーネスがない場合、互換性バックエンドとして PI を引き続き使用できます。テスト中に Codex の選択を強制するには、`agentRuntime.id: "codex"` を設定してください。強制された Codex ランタイムは、`agentRuntime.fallback: "pi"` を明示的に設定しない限り、PI にフォールバックせず失敗するようになりました。Codex app-server が選択されると、その失敗は追加のフォールバック設定なしで直接表面化します。 +**OpenClaw が Codex ではなく PI を使用する:** `agentRuntime.id: "auto"` は、Codex ハーネスが実行を要求しない場合、互換性バックエンドとして引き続き PI を使用できる。テスト中に Codex 選択を強制するには `agentRuntime.id: "codex"` を設定する。強制された Codex ランタイムは、`agentRuntime.fallback: "pi"` を明示的に設定しない限り、PI へフォールバックせず失敗するようになった。Codex app-server が選択されると、その失敗は追加のフォールバック設定なしで直接表面化する。 -**app-server が拒否される:** app-server ハンドシェイクがバージョン `0.125.0` 以降を報告するように Codex をアップグレードしてください。`0.125.0-alpha.2` や `0.125.0+custom` のような同一バージョンのプレリリースまたはビルドサフィックス付きバージョンは拒否されます。OpenClaw がテストするのは安定版 `0.125.0` のプロトコル下限だからです。 +**app-server が拒否される:** app-server ハンドシェイクがバージョン `0.125.0` 以降を報告するように Codex をアップグレードする。同一バージョンのプレリリースや、`0.125.0-alpha.2` または `0.125.0+custom` のようなビルドサフィックス付きバージョンは拒否される。OpenClaw がテストする安定版のプロトコル下限が `0.125.0` だからである。 -**モデル探索が遅い:** `plugins.entries.codex.config.discovery.timeoutMs` を下げるか、探索を無効にしてください。 +**モデル検出が遅い:** `plugins.entries.codex.config.discovery.timeoutMs` を下げるか、検出を無効にする。 -**WebSocket トランスポートがすぐに失敗する:** `appServer.url`、`authToken`、およびリモート app-server が同じ Codex app-server プロトコルバージョンを話すことを確認してください。 +**WebSocket トランスポートが即座に失敗する:** `appServer.url`、`authToken`、およびリモート app-server が同じ Codex app-server プロトコルバージョンを話していることを確認する。 -**非 Codex モデルが PI を使用する:** そのエージェントに対して `agentRuntime.id: "codex"` を強制した場合、またはレガシーの `codex/*` 参照を選択した場合を除き、これは想定どおりです。プレーンな `openai/gpt-*` やその他のプロバイダー参照は、`auto` モードでは通常のプロバイダーパスに留まります。`agentRuntime.id: "codex"` を強制した場合、そのエージェントのすべての埋め込みターンは Codex がサポートする OpenAI モデルである必要があります。 +**Codex 以外のモデルが PI を使用する:** そのエージェントに対して `agentRuntime.id: "codex"` を強制した場合、またはレガシーの `codex/*` ref を選択した場合を除き、これは想定どおり。通常の `openai/gpt-*` とその他のプロバイダー ref は、`auto` モードでは通常のプロバイダーパスに留まる。`agentRuntime.id: "codex"` を強制する場合、そのエージェントのすべての組み込みターンは Codex がサポートする OpenAI モデルでなければならない。 -**Computer Use はインストールされているがツールが実行されない:** 新しいセッションから `/codex computer-use status` を確認してください。ツールが `Native hook relay unavailable` を報告する場合は、`/new` または `/reset` を使用してください。それでも続く場合は、Gateway を再起動して古いネイティブフック登録をクリアしてください。`computer-use.list_apps` がタイムアウトする場合は、Codex Computer Use または Codex Desktop を再起動してから再試行してください。 +**Computer Use はインストールされているがツールが実行されない:** 新しいセッションから `/codex computer-use status` を確認する。ツールが `Native hook relay unavailable` を報告する場合は `/new` または `/reset` を使用する。継続する場合は、古いネイティブフック登録をクリアするために Gateway を再起動する。`computer-use.list_apps` がタイムアウトする場合は、Codex Computer Use または Codex Desktop を再起動して再試行する。 ## 関連 diff --git a/docs/ja-JP/tools/skills.md b/docs/ja-JP/tools/skills.md index d3a6ee1ae..919af8cff 100644 --- a/docs/ja-JP/tools/skills.md +++ b/docs/ja-JP/tools/skills.md @@ -1,25 +1,25 @@ --- read_when: - Skills の追加または変更 - - スキルのゲート制御、許可リスト、読み込みルールを変更する - - Skills の優先順位とスナップショット動作を理解する + - スキルのゲーティング、許可リスト、読み込みルールの変更 + - スキルの優先順位とスナップショット動作を理解する sidebarTitle: Skills -summary: 'Skills: 管理対象とワークスペース、ゲート規則、エージェント許可リスト、設定の結線' +summary: 'Skills: 管理型とワークスペースの違い、ゲート規則、エージェント許可リスト、設定の接続' title: Skills x-i18n: - generated_at: "2026-04-30T09:34:58Z" + generated_at: "2026-04-30T20:05:41Z" model: gpt-5.5 provider: openai - source_hash: d7dd17f52119bf0a0bb197025070abb68f7667a7d22c3d5fa6ef2f666110a45a + source_hash: b58d690786756bd3539940aae9f2abcb8a497798ed7b6afeb5e6d6e255fcf257 source_path: tools/skills.md workflow: 16 --- -OpenClaw は、エージェントにツールの使い方を教えるために **[AgentSkills](https://agentskills.io)互換**のスキルフォルダーを使用します。各スキルは、YAML フロントマターと手順を含む `SKILL.md` を持つディレクトリです。OpenClaw はバンドルされたスキルと任意のローカルオーバーライドを読み込み、環境、設定、バイナリの有無に基づいて読み込み時にフィルタリングします。 +OpenClaw は、エージェントにツールの使い方を教えるために、**[AgentSkills](https://agentskills.io) 互換**のスキルフォルダーを使用します。各スキルは、YAML フロントマターと手順を含む `SKILL.md` を持つディレクトリです。OpenClaw はバンドル済みスキルに加えて任意のローカルオーバーライドを読み込み、環境、設定、バイナリの有無に基づいて読み込み時にフィルタリングします。 ## 場所と優先順位 -OpenClaw は次のソースからスキルを読み込みます。**優先順位が高い順**です。 +OpenClaw は以下のソースからスキルを読み込みます。**優先順位が高い順**です。 | # | ソース | パス | | --- | --------------------- | -------------------------------- | @@ -27,28 +27,30 @@ OpenClaw は次のソースからスキルを読み込みます。**優先順位 | 2 | プロジェクトエージェントスキル | `/.agents/skills` | | 3 | 個人エージェントスキル | `~/.agents/skills` | | 4 | 管理対象/ローカルスキル | `~/.openclaw/skills` | -| 5 | バンドルスキル | インストールに同梱 | +| 5 | バンドル済みスキル | インストールに同梱 | | 6 | 追加スキルフォルダー | `skills.load.extraDirs` (設定) | スキル名が競合する場合、最も高いソースが優先されます。 -## エージェント別スキルと共有スキル +Codex CLI ネイティブの `$CODEX_HOME/skills` ディレクトリは、これらの OpenClaw スキルルートには含まれません。Codex ハーネスモードでは、ローカルアプリサーバーの起動にエージェントごとに分離された Codex ホームを使用するため、個人用 Codex CLI スキルは暗黙的には読み込まれません。`openclaw migrate codex --dry-run` を使用してそれらを棚卸しし、`openclaw migrate codex` を使用して、現在の OpenClaw エージェントワークスペースへコピーする前に対話型チェックボックスプロンプトでスキルディレクトリを選択します。非対話実行では、コピーする正確なスキルごとに `--skill ` を繰り返します。 + +## エージェントごとのスキルと共有スキル **マルチエージェント**構成では、各エージェントが独自のワークスペースを持ちます。 -| スコープ | パス | 表示対象 | +| スコープ | パス | 表示先 | | -------------------- | ------------------------------------------- | --------------------------- | -| エージェント別 | `/skills` | そのエージェントのみ | +| エージェントごと | `/skills` | そのエージェントのみ | | プロジェクトエージェント | `/.agents/skills` | そのワークスペースのエージェントのみ | | 個人エージェント | `~/.agents/skills` | そのマシン上のすべてのエージェント | | 共有管理対象/ローカル | `~/.openclaw/skills` | そのマシン上のすべてのエージェント | | 共有追加ディレクトリ | `skills.load.extraDirs` (最低優先順位) | そのマシン上のすべてのエージェント | -複数の場所に同じ名前がある場合 → 最も高いソースが優先されます。ワークスペースは、プロジェクトエージェント、個人エージェント、管理対象/ローカル、バンドル、追加ディレクトリより優先されます。 +複数の場所に同じ名前がある場合 → 最も高いソースが優先されます。ワークスペースはプロジェクトエージェントに優先し、プロジェクトエージェントは個人エージェントに優先し、個人エージェントは管理対象/ローカルに優先し、管理対象/ローカルはバンドル済みに優先し、バンドル済みは追加ディレクトリに優先します。 -## エージェントスキルの許可リスト +## エージェントスキル許可リスト -スキルの**場所**とスキルの**可視性**は別々の制御です。場所/優先順位は、同名スキルのどのコピーが優先されるかを決定します。エージェントの許可リストは、エージェントが実際に使用できるスキルを決定します。 +スキルの**場所**とスキルの**可視性**は別々の制御です。場所/優先順位は、同名スキルのどのコピーが優先されるかを決定します。エージェント許可リストは、エージェントが実際に使用できるスキルを決定します。 ```json5 { @@ -66,63 +68,62 @@ OpenClaw は次のソースからスキルを読み込みます。**優先順位 ``` - - - 既定でスキルを制限しない場合は、`agents.defaults.skills` を省略します。 + + - デフォルトでスキルを無制限にするには、`agents.defaults.skills` を省略します。 - `agents.defaults.skills` を継承するには、`agents.list[].skills` を省略します。 - スキルなしにするには、`agents.list[].skills: []` を設定します。 - - 空でない `agents.list[].skills` リストは、そのエージェントの**最終的な**セットです。既定値とはマージされません。 - - 有効な許可リストは、プロンプト構築、スキルのスラッシュコマンド検出、サンドボックス同期、スキルスナップショット全体に適用されます。 - + - 空でない `agents.list[].skills` リストは、そのエージェントの**最終的な**セットです。デフォルトとはマージされません。 + - 有効な許可リストは、プロンプト構築、スキルスラッシュコマンド検出、サンドボックス同期、スキルスナップショット全体に適用されます。 ## Plugin とスキル -Plugin は、`openclaw.plugin.json` に `skills` ディレクトリを列挙することで、独自のスキルを同梱できます (パスは Plugin ルートからの相対パス)。Plugin のスキルは、その Plugin が有効なときに読み込まれます。これは、ツール説明に収めるには長すぎるが、Plugin がインストールされているときには利用可能にしておくべきツール固有の運用ガイドに適した場所です。たとえば、ブラウザー Plugin は複数ステップのブラウザー制御用に `browser-automation` スキルを同梱しています。 +Plugin は、`openclaw.plugin.json` に `skills` ディレクトリを列挙することで、独自のスキルを同梱できます (パスは Plugin ルートからの相対パス)。Plugin スキルは、Plugin が有効なときに読み込まれます。これは、ツールの説明に含めるには長すぎるが、Plugin がインストールされているときは常に利用可能にすべき、ツール固有の操作ガイドに適した場所です。たとえば、ブラウザー Plugin は複数ステップのブラウザー制御用に `browser-automation` スキルを同梱しています。 -Plugin のスキルディレクトリは `skills.load.extraDirs` と同じ低優先順位のパスにマージされるため、同名のバンドル、管理対象、エージェント、またはワークスペーススキルがそれらを上書きします。Plugin の設定エントリで `metadata.openclaw.requires.config` を使って制御できます。 +Plugin スキルディレクトリは、`skills.load.extraDirs` と同じ低優先順位のパスへマージされるため、同名のバンドル済み、管理対象、エージェント、またはワークスペーススキルによって上書きされます。Plugin の設定エントリ上の `metadata.openclaw.requires.config` によって、それらをゲートできます。 検出/設定については [Plugins](/ja-JP/tools/plugin) を、それらのスキルが教えるツールサーフェスについては [Tools](/ja-JP/tools) を参照してください。 -## スキルワークショップ +## Skill Workshop -任意の実験的な **Skill Workshop** Plugin は、エージェント作業中に観測された再利用可能な手順からワークスペーススキルを作成または更新できます。既定では無効で、`plugins.entries.skill-workshop` で明示的に有効化する必要があります。 +任意の実験的な **Skill Workshop** Plugin は、エージェント作業中に観測された再利用可能な手順からワークスペーススキルを作成または更新できます。デフォルトでは無効であり、`plugins.entries.skill-workshop` によって明示的に有効にする必要があります。 -Skill Workshop は `/skills` にのみ書き込み、生成された内容をスキャンし、承認待ちまたは自動の安全な書き込みをサポートし、安全でない提案を隔離し、書き込み成功後にスキルスナップショットを更新して、Gateway の再起動なしで新しいスキルを利用可能にします。 +Skill Workshop は `/skills` にのみ書き込み、生成された内容をスキャンし、保留中の承認または自動的な安全書き込みをサポートし、安全でない提案を隔離し、書き込み成功後にスキルスナップショットを更新するため、Gateway の再起動なしで新しいスキルを利用可能にします。 -_"次回は GIF の帰属を検証する"_ のような修正や、メディア QA チェックリストのように苦労して得たワークフローに使用します。承認待ちから始めてください。自動書き込みは、提案をレビューした後、信頼できるワークスペースでのみ使用してください。完全なガイド: [Skill Workshop plugin](/ja-JP/plugins/skill-workshop)。 +「次回は GIF の帰属表示を確認する」のような修正や、メディア QA チェックリストのような苦労して得たワークフローに使用します。保留中の承認から始めてください。自動書き込みは、提案を確認した後の信頼できるワークスペースでのみ使用してください。完全なガイド: [Skill Workshop plugin](/ja-JP/plugins/skill-workshop)。 ## ClawHub (インストールと同期) [ClawHub](https://clawhub.ai) は OpenClaw の公開スキルレジストリです。検出/インストール/更新にはネイティブの `openclaw skills` コマンドを使用するか、公開/同期ワークフローには別の `clawhub` CLI を使用します。完全なガイド: [ClawHub](/ja-JP/tools/clawhub)。 -| アクション | コマンド | +| 操作 | コマンド | | ---------------------------------- | -------------------------------------- | -| スキルをワークスペースにインストール | `openclaw skills install ` | -| インストール済みスキルをすべて更新 | `openclaw skills update --all` | -| 同期 (スキャン + 更新の公開) | `clawhub sync --all` | +| ワークスペースにスキルをインストール | `openclaw skills install ` | +| インストール済みのすべてのスキルを更新 | `openclaw skills update --all` | +| 同期 (スキャン + 更新公開) | `clawhub sync --all` | -ネイティブの `openclaw skills install` は、アクティブなワークスペースの `skills/` ディレクトリにインストールします。別の `clawhub` CLI も、現在の作業ディレクトリ配下の `./skills` にインストールします (または設定済みの OpenClaw ワークスペースにフォールバックします)。OpenClaw は次のセッションでそれを `/skills` として拾います。 -設定済みのスキルルートでは、`skills///SKILL.md` のように 1 階層のグループ化もサポートされるため、広範な再帰スキャンなしで関連するサードパーティスキルを共有フォルダー配下に保持できます。 +ネイティブの `openclaw skills install` は、アクティブなワークスペースの `skills/` ディレクトリにインストールします。別の `clawhub` CLI も、現在の作業ディレクトリ配下の `./skills` にインストールします (または、設定済みの OpenClaw ワークスペースにフォールバックします)。OpenClaw は次のセッションでそれを `/skills` として取り込みます。 +設定済みスキルルートは、`skills///SKILL.md` のように 1 レベルのグループ化もサポートしているため、関連するサードパーティスキルを、広範な再帰スキャンなしで共有フォルダー配下に保持できます。 -ClawHub のスキルページは、インストール前に最新のセキュリティスキャン状態を公開し、VirusTotal、ClawScan、静的解析のスキャナー詳細ページを提供します。`openclaw skills install ` は引き続きインストール経路のみです。公開者は ClawHub ダッシュボードまたは `clawhub skill rescan ` を通じて誤検出から復旧します。 +ClawHub スキルページは、インストール前に最新のセキュリティスキャン状態を表示し、VirusTotal、ClawScan、静的解析のスキャナー詳細ページも提供します。`openclaw skills install ` はインストール経路でしかありません。公開者は ClawHub ダッシュボードまたは `clawhub skill rescan ` を通じて誤検出から回復します。 ## セキュリティ -サードパーティスキルは**信頼できないコード**として扱ってください。有効化する前に読んでください。信頼できない入力や危険なツールには、サンドボックス化された実行を優先してください。エージェント側の制御については [Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。 +サードパーティスキルは**信頼されていないコード**として扱ってください。有効化する前に読んでください。信頼されていない入力やリスクのあるツールには、サンドボックス化された実行を推奨します。エージェント側の制御については [サンドボックス化](/ja-JP/gateway/sandboxing) を参照してください。 -- ワークスペースおよび追加ディレクトリのスキル検出は、解決済みの realpath が設定済みルート内に留まるスキルルートと `SKILL.md` ファイルのみを受け入れます。 -- Gateway バックのスキル依存関係インストール (`skills.install`、オンボーディング、Skills設定UI) は、インストーラーメタデータを実行する前に組み込みの危険コードスキャナーを実行します。呼び出し元が危険なオーバーライドを明示的に設定しない限り、`critical` の検出結果は既定でブロックされます。疑わしい検出結果は引き続き警告のみです。 -- `openclaw skills install ` は別物です。これは ClawHub スキルフォルダーをワークスペースにダウンロードし、上記のインストーラーメタデータ経路は使用しません。 +- ワークスペースおよび追加ディレクトリのスキル検出は、解決済み realpath が設定済みルート内に留まるスキルルートと `SKILL.md` ファイルのみを受け入れます。 +- Gateway-backed スキル依存関係インストール (`skills.install`、オンボーディング、Skills 設定 UI) は、インストーラーメタデータを実行する前に組み込みの危険コードスキャナーを実行します。`critical` の検出結果は、呼び出し元が危険なオーバーライドを明示的に設定しない限りデフォルトでブロックされます。不審な検出結果は警告のみのままです。 +- `openclaw skills install ` は異なります。これは ClawHub スキルフォルダーをワークスペースにダウンロードし、上記のインストーラーメタデータ経路を使用しません。 - `skills.entries.*.env` と `skills.entries.*.apiKey` は、そのエージェントターンの**ホスト**プロセスにシークレットを注入します (サンドボックスではありません)。シークレットをプロンプトやログに含めないでください。 -より広範な脅威モデルとチェックリストについては、[Security](/ja-JP/gateway/security) を参照してください。 +より広範な脅威モデルとチェックリストについては、[セキュリティ](/ja-JP/gateway/security) を参照してください。 ## SKILL.md 形式 -`SKILL.md` には少なくとも次を含める必要があります。 +`SKILL.md` には少なくとも以下を含める必要があります。 ```markdown --- @@ -131,15 +132,15 @@ description: Generate or edit images via a provider-backed image workflow --- ``` -OpenClaw はレイアウト/意図について AgentSkills 仕様に従います。埋め込みエージェントで使用されるパーサーは、**単一行**のフロントマターキーのみをサポートします。`metadata` は**単一行の JSON オブジェクト**にしてください。手順内でスキルフォルダーパスを参照するには `{baseDir}` を使用します。 +OpenClaw はレイアウト/意図について AgentSkills 仕様に従います。組み込みエージェントで使用されるパーサーは、**単一行**のフロントマターキーのみをサポートします。`metadata` は**単一行の JSON オブジェクト**にする必要があります。手順内でスキルフォルダーパスを参照するには `{baseDir}` を使用します。 ### 任意のフロントマターキー - macOS Skills UI で「Webサイト」として表示される URL。`metadata.openclaw.homepage` 経由でもサポートされます。 + macOS Skills UI で「Website」として表示される URL。`metadata.openclaw.homepage` 経由でもサポートされます。 - `true` の場合、スキルはユーザーのスラッシュコマンドとして公開されます。 + `true` の場合、スキルはユーザースラッシュコマンドとして公開されます。 `true` の場合、スキルはモデルプロンプトから除外されます (ユーザー呼び出しでは引き続き利用可能)。 @@ -151,10 +152,10 @@ OpenClaw はレイアウト/意図について AgentSkills 仕様に従います `command-dispatch: tool` が設定されている場合に呼び出すツール名。 - ツールディスパッチでは、生の引数文字列をツールへ転送します (コア側の解析なし)。ツールは `{ command: "", commandName: "", skillName: "" }` で呼び出されます。 + ツールディスパッチでは、生の引数文字列をツールに転送します (コア解析なし)。ツールは `{ command: "", commandName: "", skillName: "" }` で呼び出されます。 -## ゲート制御 (読み込み時フィルター) +## ゲーティング (読み込み時フィルター) OpenClaw は `metadata` (単一行 JSON) を使用して、読み込み時にスキルをフィルタリングします。 @@ -176,16 +177,16 @@ metadata: `metadata.openclaw` 配下のフィールド: - `true` の場合、常にスキルを含めます (他のゲートをスキップします)。 + `true` の場合、常にスキルを含めます (他のゲートをスキップ)。 macOS Skills UI で使用される任意の絵文字。 - macOS Skills UI で「Webサイト」として表示される任意の URL。 + macOS Skills UI で「Website」として表示される任意の URL。 - 任意のプラットフォーム一覧。設定されている場合、スキルはそれらの OS でのみ対象になります。 + 任意のプラットフォーム一覧。設定すると、スキルはそれらの OS でのみ対象になります。 それぞれが `PATH` 上に存在する必要があります。 @@ -200,23 +201,23 @@ metadata: truthy である必要がある `openclaw.json` パスの一覧。 - `skills.entries..apiKey` に関連付けられる環境変数名。 + `skills.entries..apiKey` に関連付けられた環境変数名。 macOS Skills UI で使用される任意のインストーラー仕様 (brew/node/go/uv/download)。 -`metadata.openclaw` が存在しない場合、スキルは常に対象になります (設定で無効化されている場合や、バンドルスキルに対して `skills.allowBundled` によってブロックされている場合を除く)。 +`metadata.openclaw` が存在しない場合、スキルは常に対象になります (設定で無効化されている場合、またはバンドル済みスキルに対して `skills.allowBundled` でブロックされている場合を除く)。 -`metadata.openclaw` が存在しない場合は、従来の `metadata.clawdbot` ブロックも引き続き受け入れられるため、古いインストール済みスキルは依存関係ゲートとインストーラーヒントを維持します。新規および更新されたスキルでは `metadata.openclaw` を使用してください。 +レガシーの `metadata.clawdbot` ブロックは、`metadata.openclaw` が存在しない場合も引き続き受け入れられるため、古いインストール済みスキルは依存関係ゲートとインストーラーヒントを維持します。新規および更新済みスキルでは `metadata.openclaw` を使用してください。 ### サンドボックス化の注意事項 -- `requires.bins` はスキル読み込み時に**ホスト**上でチェックされます。 -- エージェントがサンドボックス化されている場合、バイナリは**コンテナ内**にも存在する必要があります。`agents.defaults.sandbox.docker.setupCommand` (またはカスタムイメージ) でインストールします。`setupCommand` はコンテナ作成後に 1 回実行されます。パッケージのインストールには、ネットワーク送信、書き込み可能なルート FS、サンドボックス内の root ユーザーも必要です。 -- 例: `summarize` スキル (`skills/summarize/SKILL.md`) は、そこで実行するためにサンドボックスコンテナ内の `summarize` CLI を必要とします。 +- `requires.bins` はスキル読み込み時に**ホスト**上で確認されます。 +- エージェントがサンドボックス化されている場合、そのバイナリは**コンテナ内**にも存在する必要があります。`agents.defaults.sandbox.docker.setupCommand` (またはカスタムイメージ) 経由でインストールしてください。`setupCommand` はコンテナ作成後に 1 回実行されます。パッケージインストールには、ネットワーク送信、書き込み可能なルート FS、サンドボックス内の root ユーザーも必要です。 +- 例: `summarize` スキル (`skills/summarize/SKILL.md`) は、そこで実行するためにサンドボックスコンテナ内に `summarize` CLI が必要です。 ### インストーラー仕様 @@ -247,25 +248,25 @@ metadata: - - 複数のインストーラーが一覧されている場合、Gateway は単一の優先オプションを選びます（利用可能なら brew、それ以外は node）。 - - すべてのインストーラーが `download` の場合、OpenClaw は利用可能なアーティファクトを確認できるように各エントリを一覧します。 - - インストーラー仕様には `os: ["darwin"|"linux"|"win32"]` を含め、プラットフォーム別にオプションを絞り込めます。 - - Node インストールは `openclaw.json` の `skills.install.nodeManager` に従います（デフォルト: npm、オプション: npm/pnpm/yarn/bun）。これは skill インストールのみに影響します。Gateway ランタイムは引き続き Node であるべきです。Bun は WhatsApp/Telegram には推奨されません。 - - Gateway ベースのインストーラー選択は優先順位に基づきます。インストール仕様に複数の種類が混在する場合、OpenClaw は `skills.install.preferBrew` が有効で `brew` が存在すれば Homebrew を優先し、次に `uv`、設定済みの node マネージャー、さらに `go` や `download` などの他のフォールバックを選びます。 - - すべてのインストール仕様が `download` の場合、OpenClaw は 1 つの優先インストーラーにまとめず、すべてのダウンロードオプションを提示します。 + - 複数のインストーラーが一覧されている場合、Gateway は単一の優先オプションを選択します（利用可能なら brew、それ以外は node）。 + - すべてのインストーラーが `download` の場合、OpenClaw は各エントリを一覧表示し、利用可能なアーティファクトを確認できるようにします。 + - インストーラー仕様には、プラットフォームでオプションを絞り込むために `os: ["darwin"|"linux"|"win32"]` を含めることができます。 + - Node インストールは `openclaw.json` の `skills.install.nodeManager` に従います（デフォルト: npm、オプション: npm/pnpm/yarn/bun）。これは skill のインストールにのみ影響します。Gateway ランタイムは引き続き Node であるべきです。WhatsApp/Telegram には Bun は推奨されません。 + - Gateway ベースのインストーラー選択は優先設定に基づきます。インストール仕様に複数の種類が混在する場合、OpenClaw は `skills.install.preferBrew` が有効で `brew` が存在すれば Homebrew を優先し、次に `uv`、次に設定済みの node マネージャー、その後 `go` や `download` などのフォールバックを選びます。 + - すべてのインストール仕様が `download` の場合、OpenClaw は 1 つの優先インストーラーにまとめず、すべてのダウンロードオプションを表示します。 - - **Go インストール:** `go` がなく `brew` が利用可能な場合、Gateway はまず Homebrew 経由で Go をインストールし、可能な場合は `GOBIN` を Homebrew の `bin` に設定します。 - - **ダウンロードインストール:** `url`（必須）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（デフォルト: アーカイブ検出時に自動）、`stripComponents`、`targetDir`（デフォルト: `~/.openclaw/tools/`）。 + - **Go インストール:** `go` がなく、`brew` が利用可能な場合、Gateway はまず Homebrew 経由で Go をインストールし、可能であれば `GOBIN` を Homebrew の `bin` に設定します。 + - **ダウンロードインストール:** `url`（必須）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（デフォルト: アーカイブ検出時は自動）、`stripComponents`、`targetDir`（デフォルト: `~/.openclaw/tools/`）。 ## 設定の上書き -バンドルおよび管理対象の Skills は、`~/.openclaw/openclaw.json` の -`skills.entries` 配下で切り替えたり env 値を指定したりできます。 +バンドル済みおよび管理対象の skills は、`~/.openclaw/openclaw.json` の +`skills.entries` 配下で切り替えたり、env 値を指定したりできます。 ```json5 { @@ -290,14 +291,14 @@ metadata: ``` - `false` は、その skill がバンドル済みまたはインストール済みであっても無効化します。 + `false` は、その skill がバンドル済みまたはインストール済みであっても無効にします。 バンドル済みの `coding-agent` skill はオプトインです。エージェントに公開する前に `skills.entries.coding-agent.enabled: true` を設定し、 - そのうえで `claude`、`codex`、`opencode`、または `pi` のいずれかがインストールされ、 + その後、`claude`、`codex`、`opencode`、または `pi` のいずれかがインストールされ、 それ自身の CLI で認証済みであることを確認してください。 - `metadata.openclaw.primaryEnv` を宣言する Skills 向けの簡易指定です。平文または SecretRef をサポートします。 + `metadata.openclaw.primaryEnv` を宣言する skills 向けの便利設定です。プレーンテキストまたは SecretRef をサポートします。 変数がプロセス内でまだ設定されていない場合にのみ注入されます。 @@ -306,21 +307,21 @@ metadata: skill ごとのカスタムフィールド用の任意の入れ物です。カスタムキーはここに置く必要があります。 - **バンドル済み** Skills のみを対象にする任意の許可リストです。設定した場合、リスト内のバンドル済み Skills だけが対象になります（管理対象/workspace Skills には影響しません）。 + **バンドル済み** skills のみに対する任意の許可リストです。設定した場合、一覧内のバンドル済み skills のみが対象になります（管理対象/workspace skills には影響しません）。 skill 名にハイフンが含まれる場合は、キーを引用符で囲みます（JSON5 では引用符付き キーが許可されます）。設定キーはデフォルトで **skill 名** と一致します。skill が -`metadata.openclaw.skillKey` を定義している場合は、`skills.entries` 配下でそのキーを使用してください。 +`metadata.openclaw.skillKey` を定義している場合は、そのキーを `skills.entries` 配下で使用してください。 OpenClaw 内で標準の画像生成/編集を行う場合は、バンドル済み skill ではなく、 `agents.defaults.imageGenerationModel` とともにコアの -`image_generate` ツールを使用してください。ここでの skill 例は、カスタムまたはサードパーティの -ワークフロー向けです。ネイティブ画像分析には -`agents.defaults.imageModel` とともに `image` ツールを使用してください。 -`openai/*`、`google/*`、`fal/*`、またはその他のプロバイダー固有の画像モデルを選ぶ場合は、そのプロバイダーの -auth/API キーも追加してください。 +`image_generate` ツールを使用してください。ここでの skill の例は、カスタムまたはサードパーティの +ワークフロー向けです。ネイティブ画像分析には、 +`agents.defaults.imageModel` とともに `image` ツールを使用してください。`openai/*`、`google/*`、 +`fal/*`、または別のプロバイダー固有の画像モデルを選ぶ場合は、そのプロバイダーの +認証/API キーも追加してください。 ## 環境の注入 @@ -329,38 +330,39 @@ auth/API キーも追加してください。 1. skill メタデータを読み取ります。 2. `skills.entries..env` と `skills.entries..apiKey` を `process.env` に適用します。 -3. **対象となる** Skills を含めてシステムプロンプトを構築します。 +3. **対象となる** skills を含むシステムプロンプトを構築します。 4. 実行終了後に元の環境を復元します。 -環境の注入は**エージェント実行にスコープされる**もので、グローバルなシェル +環境の注入は **エージェント実行にスコープされる** ものであり、グローバルなシェル 環境ではありません。 バンドル済みの `claude-cli` バックエンドでは、OpenClaw は同じ -対象スナップショットを一時的な Claude Code Plugin として実体化し、 -`--plugin-dir` で渡します。これにより Claude Code はネイティブの skill リゾルバーを使用でき、 -同時に OpenClaw は優先順位、エージェントごとの許可リスト、ゲート、および -`skills.entries.*` の env/API キー注入を引き続き管理します。他の CLI バックエンドは +対象スナップショットを一時的な Claude Code plugin として実体化し、 +`--plugin-dir` で渡します。Claude Code はその後、ネイティブの skill リゾルバーを使用できますが、 +OpenClaw は引き続き優先順位、エージェントごとの許可リスト、ゲート制御、および +`skills.entries.*` の env/API キー注入を管理します。他の CLI バックエンドは プロンプトカタログのみを使用します。 ## スナップショットと更新 -OpenClaw は、**セッション開始時**に対象 Skills のスナップショットを作成し、 -同じセッション内の後続ターンではその一覧を再利用します。Skills または設定の変更は、 +OpenClaw は **セッション開始時** に対象 skills のスナップショットを作成し、 +同じセッション内の以降のターンでその一覧を再利用します。skills または設定の変更は 次の新しいセッションで有効になります。 -Skills は次の 2 つの場合にセッション途中で更新できます。 +skills は次の 2 つの場合にセッション途中で更新できます。 -- Skills ウォッチャーが有効になっている。 -- 新しい対象リモートノードが現れる。 +- skills ウォッチャーが有効になっている。 +- 新しい対象リモートノードが出現した。 -これは**ホットリロード**と考えてください。更新された一覧は次の -エージェントターンで反映されます。そのセッションに対する有効なエージェント skill 許可リストが変わった場合、 -OpenClaw はスナップショットを更新し、表示される Skills が現在のエージェントと一致し続けるようにします。 +これは **ホットリロード** と考えてください。更新された一覧は、次の +エージェントターンで取得されます。そのセッションの有効なエージェント skill 許可リストが変わった場合、 +OpenClaw はスナップショットを更新し、表示される skills が +現在のエージェントと揃った状態を保ちます。 ### Skills ウォッチャー デフォルトでは、OpenClaw は skill フォルダーを監視し、 -`SKILL.md` ファイルが変更されると Skills スナップショットを更新します。`skills.load` 配下で設定します。 +`SKILL.md` ファイルが変わると skills スナップショットを更新します。`skills.load` 配下で設定します。 ```json5 { @@ -373,23 +375,24 @@ OpenClaw はスナップショットを更新し、表示される Skills が現 } ``` -### リモート macOS ノード（Linux Gateway） +### リモート macOS ノード（Linux gateway） -Gateway が Linux 上で実行されているが、**macOS ノード**が -`system.run` 許可付きで接続されている場合（Exec 承認セキュリティが `deny` に設定されていない場合）、 -OpenClaw は必要なバイナリがそのノード上に存在するとき、macOS 専用 Skills を対象として扱えます。 -エージェントは `host=node` を指定した `exec` ツール経由でそれらの Skills を実行するべきです。 +Gateway が Linux 上で実行されていても、**macOS ノード** が接続され、 +`system.run` が許可されている（Exec 承認セキュリティが `deny` に設定されていない）場合、 +OpenClaw は必要なバイナリがそのノード上に存在すれば、macOS 専用 skills を対象として扱えます。 +エージェントは、それらの skills を `host=node` の `exec` ツール経由で実行する必要があります。 -これは、ノードがコマンドサポートを報告すること、および `system.which` または `system.run` による -bin プローブに依存します。オフラインノードは**リモート専用** Skills を表示対象にしません。 -接続済みノードが bin プローブに応答しなくなった場合、OpenClaw はキャッシュ済みの bin 一致をクリアし、 -現在そこで実行できない Skills がエージェントに表示されないようにします。 +これは、ノードがコマンドサポートを報告することと、 +`system.which` または `system.run` 経由の bin プローブに依存します。オフラインノードでは +リモート専用 skills は表示されません。接続済みノードが bin +プローブに応答しなくなった場合、OpenClaw はキャッシュ済みの bin 一致をクリアするため、 +エージェントには現在そこで実行できない skills が表示されなくなります。 ## トークンへの影響 -Skills が対象になると、OpenClaw は利用可能な Skills のコンパクトな XML 一覧を -システムプロンプトに注入します（`pi-coding-agent` の `formatSkillsForPrompt` 経由）。 -コストは決定的です。 +skills が対象になると、OpenClaw は利用可能な +skills のコンパクトな XML 一覧をシステムプロンプトに注入します（`pi-coding-agent` の +`formatSkillsForPrompt` 経由）。コストは決定的です。 - **基本オーバーヘッド**（skill が 1 つ以上ある場合のみ）: 195 文字。 - **skill ごと:** 97 文字 + XML エスケープ済みの ``、``、`` 値の長さ。 @@ -400,28 +403,29 @@ Skills が対象になると、OpenClaw は利用可能な Skills のコンパ total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped)) ``` -XML エスケープでは `& < > " '` がエンティティ（`&`、`<` など）に展開されるため、 -長さが増えます。トークン数はモデルのトークナイザーによって異なります。OpenAI 風の概算では -約 4 文字/トークンなので、**97 文字 ≈ 24 トークン**が skill ごとにかかり、さらに実際のフィールド長が加わります。 +XML エスケープでは `& < > " '` がエンティティ（`&`、`<` など）に展開され、 +長さが増えます。トークン数はモデルのトークナイザーによって異なります。大まかな +OpenAI 形式の見積もりでは約 4 文字/トークンなので、**97 文字 ≈ 24 トークン** が +skill ごとにかかり、これに実際のフィールド長が加わります。 -## 管理対象 Skills のライフサイクル +## 管理対象 skills のライフサイクル OpenClaw は、インストール（npm パッケージまたは OpenClaw.app）に -**バンドル済み Skills** として基本セットの Skills を同梱しています。 -`~/.openclaw/skills` はローカル上書き用です。たとえば、バンドル済みコピーを変更せずに -skill を固定したりパッチしたりできます。Workspace Skills はユーザー所有であり、 +**バンドル済み skills** として基本セットを同梱します。`~/.openclaw/skills` は +ローカルの上書き用に存在します。たとえば、バンドル済みコピーを変更せずに +skill をピン留めしたりパッチしたりできます。Workspace skills はユーザー所有であり、 名前の競合時には両方を上書きします。 -## さらに Skills を探す場合 +## さらに skills を探す [https://clawhub.ai](https://clawhub.ai) を参照してください。完全な設定 スキーマ: [Skills 設定](/ja-JP/tools/skills-config)。 ## 関連 -- [ClawHub](/ja-JP/tools/clawhub) — 公開 Skills レジストリ -- [Skills の作成](/ja-JP/tools/creating-skills) — カスタム Skills の構築 -- [Plugins](/ja-JP/tools/plugin) — Plugin システムの概要 -- [Skill Workshop Plugin](/ja-JP/plugins/skill-workshop) — エージェント作業から Skills を生成 +- [ClawHub](/ja-JP/tools/clawhub) — 公開 skills レジストリ +- [skills の作成](/ja-JP/tools/creating-skills) — カスタム skills の構築 +- [Plugins](/ja-JP/tools/plugin) — plugin システムの概要 +- [Skill Workshop plugin](/ja-JP/plugins/skill-workshop) — エージェント作業から skills を生成 - [Skills 設定](/ja-JP/tools/skills-config) — skill 設定リファレンス - [スラッシュコマンド](/ja-JP/tools/slash-commands) — 利用可能なすべてのスラッシュコマンド