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

chore(i18n): refresh ja-JP translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 20:11:34 +00:00
parent c018d1c6ca
commit 83991f4473
6 changed files with 1077 additions and 1242 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/ja-JP/cli/doctor.md
View File

@ -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.<timestamp>` としてアーカイブするにはインタラクティブな確認が必要です。`--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.<id>` エントリを無効化し、その無効な `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.<timestamp>` としてアーカイブするには対話型確認が必要です。`--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.<id>` エントリを無効化し、その無効な `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.<provider>` に自動マイグレーションします。
- `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.<provider>` に自動移行します。
- `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

121
docs/ja-JP/cli/migrate.md
View File

@ -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 は追加プロバイダーを登録できます。
<Tip>
ユーザー向けの手順は、[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
```
<ParamField path="<provider>" type="string">
登録済み移行プロバイダーの名前です。例: `hermes`。インストール済みプロバイダーを確認するには `openclaw migrate list` を実行します。
登録済み移行プロバイダーの名前。例: `hermes`。インストール済みプロバイダーを確認するには `openclaw migrate list` を実行します。
</ParamField>
<ParamField path="--dry-run" type="boolean">
プランを作成し、状態を変更せずに終了します。
計画を作成して、状態を変更せずに終了します。
</ParamField>
<ParamField path="--from <path>" type="string">
ソース状態ディレクトリを上書きします。Hermes のデフォルトは `~/.hermes` です。
</ParamField>
<ParamField path="--include-secrets" type="boolean">
サポートされている認証情報をインポートします。デフォルトではオフです。
対応している認証情報をインポートします。デフォルトではオフです。
</ParamField>
<ParamField path="--overwrite" type="boolean">
プランで競合が報告された場合に、apply が既存のターゲットを置き換えることを許可します。
計画が競合を報告した場合に、apply が既存のターゲットを置き換えることを許可します。
</ParamField>
<ParamField path="--yes" type="boolean">
確認プロンプトをスキップします。非対話モードでは必須です。
</ParamField>
<ParamField path="--skill <name>" type="string">
スキル名またはアイテム ID で、コピー対象のスキル項目を 1 つ選択します。複数のスキルを移行するには、このフラグを繰り返します。省略した場合、対話型 Codex 移行ではチェックボックス選択が表示され、非対話型移行では計画されたすべてのスキルが保持されます。
</ParamField>
<ParamField path="--no-backup" type="boolean">
apply 前のバックアップをスキップします。ローカルの OpenClaw 状態が存在する場合は `--force` が必要です。
</ParamField>
<ParamField path="--force" type="boolean">
apply が通常ならバックアップのスキップを拒否する場合に、`--no-backup` と併用する必要があります。
apply が通常ならバックアップのスキップを拒否する場合に、`--no-backup` とあわせて必要です。
</ParamField>
<ParamField path="--json" type="boolean">
プランまたは apply 結果を JSON として出力します。`--json` を指定し、`--yes` を指定しない場合、apply はプランを出力し、状態を変更しません。
計画または apply 結果を JSON として出力します。`--json` を指定し、`--yes` を指定しない場合、apply は計画を出力し、状態を変更しません。
</ParamField>
## 安全性モデル
## 安全モデル
`openclaw migrate` はプレビュー優先です。
<AccordionGroup>
<Accordion title="適用前のプレビュー">
プロバイダーは、変更が行われる前に、競合、スキップされた項目、機密項目を含む項目別プランを返します。JSON プラン、apply 出力、移行レポートでは、API キー、トークン、認可ヘッダー、Cookie、パスワードなど、シークレットのように見えるネストされたキーがマスクされます。
<Accordion title="apply 前のプレビュー">
プロバイダーは、何かが変更される前に、競合、スキップされた項目、機密項目を含む項目別の計画を返します。JSON 計画、apply 出力、移行レポートでは、API キー、トークン、認可ヘッダー、Cookie、パスワードなど、シークレットらしいネストされたキーが伏せられます。
`openclaw migrate apply <provider>` はプランをプレビューし、`--yes` が設定されていない限り、状態を変更する前に確認します。非対話モードでは、apply に `--yes` が必要です。
`openclaw migrate apply <provider>` は、`--yes` が設定されていない限り、状態を変更する前に計画をプレビューして確認を求めます。非対話モードでは、apply に `--yes` が必要です。
</Accordion>
<Accordion title="バックアップ">
apply は移行を適用する前に OpenClaw バックアップを作成して検証します。ローカルの OpenClaw 状態がまだ存在しない場合、バックアップ手順はスキップされ、移行を続行できます。状態が存在する場合にバックアップをスキップするには、`--no-backup` と `--force` の両方を渡します。
apply は、移行を適用する前に OpenClaw バックアップを作成して検証します。ローカルの OpenClaw 状態がまだ存在しない場合、バックアップ手順はスキップされ、移行を続行できます。状態が存在する場合にバックアップをスキップするには、`--no-backup` と `--force` の両方を渡します。
</Accordion>
<Accordion title="競合">
プランに競合がある場合、apply は続行を拒否します。プランを確認し、既存ターゲットを置き換える意図がある場合は `--overwrite` を付けて再実行します。プロバイダーは、上書きされたファイルについて、移行レポートディレクトリに項目レベルのバックアップを書き込む場合があります。
計画に競合がある場合、apply は続行を拒否します。計画を確認し、既存のターゲットを置き換える意図がある場合は `--overwrite` を付けて再実行します。プロバイダーは、上書きされたファイルについて、移行レポートディレクトリに項目単位のバックアップを書き込む場合があります。
</Accordion>
<Accordion title="シークレット">
シークレットはデフォルトではインポートされません。サポートされている認証情報をインポートするには `--include-secrets` を使用します。
シークレットはデフォルトではインポートされません。対応している認証情報をインポートするには `--include-secrets` を使用します。
</Accordion>
</AccordionGroup>
## Claude プロバイダー
バンドルされた Claude プロバイダーは、デフォルトで `~/.claude` にある Claude Code の状態を検出します。特定の Claude Code ホームまたはプロジェクトルートをインポートするには `--from <path>` を使用します。
バンドルされた Claude プロバイダーは、デフォルトで `~/.claude` にある Claude Code の状態を検出します。特定の Claude Code ホームまたはプロジェクトルートをインポートするには、`--from <path>` を使用します。
<Tip>
ユーザー向けの手順は、[Claude からの移行](/ja-JP/install/migrating-claude) を参照してください。
</Tip>
### 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 <path>` を使用します。
OpenClaw Codex ハーネスへ移行し、有用な個人用 Codex CLI アセットを意図的に昇格したい場合に、このプロバイダーを使用します。ローカルの Codex アプリサーバー起動では、エージェントごとの `CODEX_HOME` と `HOME` ディレクトリを使用するため、デフォルトでは個人用 Codex CLI 状態を読み取りません。
対話型ターミナルで `openclaw migrate codex` を実行すると、完全な計画をプレビューしたあと、最終的な apply 確認の前に、スキルコピー項目用のチェックボックス選択が開きます。すべてのスキルは選択済みで開始します。このエージェントへコピーしたくないスキルのチェックを外してください。スクリプト実行または厳密な実行では、スキルごとに `--skill <name>` を 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 <path>` を使用します。
### 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/<name>/` 配下に `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 移行プロバイダーを使用し、適用前には引き続きプレビューを表示します。
<Note>
オンボーディングインポートには、新規の OpenClaw セットアップが必要です。すでにローカル状態がある場合は、まず設定、認証情報、セッション、ワークスペースをリセットしてください。既存セットアップ向けのバックアップと上書き、またはマージインポートは機能ゲートされています。
オンボーディングインポートには、新規の OpenClaw セットアップが必要です。ローカル状態がすでにある場合は、先に設定、認証情報、セッション、ワークスペースをリセットしてください。既存セットアップ向けのバックアップ付き上書きまたはマージインポートは、機能ゲートされています。
</Note>
## 関連
## 関連項目
- [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 のインストールと登録。

165
docs/ja-JP/concepts/agent-workspace.md
View File

@ -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/` とは別です。
<Warning>
ワークスペースはハードなサンドボックスではなく、**デフォルトの 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` 配下のサンドボックスワークスペース内で動作します。
</Warning>
## デフォルトの場所
- デフォルト: `~/.openclaw/workspace`
- `OPENCLAW_PROFILE` が設定されていて `"default"` でない場合、デフォルトは `~/.openclaw/workspace-<profile>` になります。
- `~/.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` は、ワークスペースを作成し、ブートストラップファイルが存在しない場合はそれらを初期配置します。
<Note>
Sandbox seed のコピーでは、ワークスペース内の通常ファイルのみ受け付けます。ソースワークスペースの外を指す symlink/hardlink エイリアスは無視されます。
サンドボックスの初期コピーは、ワークスペース内の通常ファイルのみを受け入れます。ソースワークスペースの外部に解決されるシンボリックリンク/ハードリンクのエイリアスは無視されます。
</Note>
すでにワークスペースファイルを自分で管理している場合は、bootstrapファイル作成を無効にできます。
ワークスペースファイルをすでに自分で管理している場合は、ブートストラップファイルの作成を無効にできます:
```json5
{ agents: { defaults: { skipBootstrap: true } } }
@ -54,82 +54,83 @@ Sandbox seed のコピーでは、ワークスペース内の通常ファイル
## 追加のワークスペースフォルダー
古いインストールでは `~/openclaw` が作成されている場合があります。複数のワークスペースディレクトリを残しておくと、同時にアクティブなのは1つだけなので、認証や状態のずれがわかりにくくなることがあります。
古いインストールでは `~/openclaw` が作成されている場合があります。複数のワークスペースディレクトリを残しておくと、一度に有効なのは1つのワークスペースだけであるため、認証や状態のずれで混乱が生じる可能性があります。
<Note>
**推奨:** アクティブなワークスペースは1つだけにしてください。追加フォルダーをもう使っていない場合は、アーカイブするかゴミ箱へ移動してください（例: `trash ~/openclaw`）。意図的に複数のワークスペースを保持する場合は、`agents.defaults.workspace` がアクティブなものを指していることを確認してください。
**推奨:** 有効なワークスペースは1つだけにしてください。追加のフォルダーをもう使用していない場合は、アーカイブするかゴミ箱に移動してください（例: `trash ~/openclaw`）。意図的に複数のワークスペースを維持する場合は、`agents.defaults.workspace` が有効なものを指していることを確認してください。
`openclaw doctor` は、追加のワークスペースディレクトリを検出すると警告します。
</Note>
## ワークスペースファイルマップ
これらは、OpenClaw がワークスペース内にあることを想定する標準ファイルです。
これらは OpenClaw がワークスペース内にあることを想定する標準ファイルです:
<AccordionGroup>
<Accordion title="AGENTS.md — 運用指示">
エージェント向けの運用指示と、メモリの使い方。すべてのセッション開始時に読み込まれます。ルール、優先順位、「どう振る舞うか」の詳細を書くのに適しています。
<Accordion title="AGENTS.md — 操作指示">
エージェントの操作指示と、メモリの使い方です。すべてのセッション開始時に読み込まれます。ルール、優先順位、「どのように振る舞うか」の詳細を書くのに適しています。
</Accordion>
<Accordion title="SOUL.md — ペルソナとトーン">
ペルソナ、トーン、境界。毎セッション読み込まれます。ガイド: [SOUL.md personality guide](/ja-JP/concepts/soul)。
ペルソナ、トーン、境界です。すべてのセッションで読み込まれます。ガイド: [SOUL.md パーソナリティガイド](/ja-JP/concepts/soul)。
</Accordion>
<Accordion title="USER.md — ユーザー情報">
ユーザーが誰か、どう呼びかけるか。毎セッション読み込まれます。
<Accordion title="USER.md — ユーザーについて">
ユーザーが誰で、どのように呼びかけるかです。すべてのセッションで読み込まれます。
</Accordion>
<Accordion title="IDENTITY.md — 名前、雰囲気、絵文字">
エージェントの名前、雰囲気、絵文字。bootstrap ritual 中に作成/更新されます。
エージェントの名前、雰囲気、絵文字です。ブートストラップ儀式中に作成/更新されます。
</Accordion>
<Accordion title="TOOLS.md — ローカルツールの慣例">
ローカルツールや慣例に関するメモ。ツールの可用性は制御せず、ガイダンスのみです。
ローカルツールと慣例に関するメモです。ツールの利用可否を制御するものではなく、ガイダンスにすぎません。
</Accordion>
<Accordion title="HEARTBEAT.md — Heartbeatチェックリスト">
Heartbeat実行用の任意の小さなチェックリスト。トークン消費を避けるため短く保ってください。
<Accordion title="HEARTBEAT.md — Heartbeat チェックリスト">
Heartbeat 実行用の任意の小さなチェックリストです。トークン消費を避けるため短くしてください。
</Accordion>
<Accordion title="BOOT.md — 起動チェックリスト">
gateway再起動時に自動実行される任意の起動チェックリスト（[internal hooks](/ja-JP/automation/hooks) が有効な場合）。短く保ち、送信にはmessageツールを使ってください。
Gateway 再起動時に自動実行される任意の起動チェックリストです（[内部フック](/ja-JP/automation/hooks)が有効な場合）。短く保ち、外部送信にはメッセージツールを使用してください。
</Accordion>
<Accordion title="BOOTSTRAP.md — 初回実行ritual">
一度きりの初回実行ritual。真新しいワークスペースにのみ作成されます。ritual が完了したら削除してください。
<Accordion title="BOOTSTRAP.md — 初回実行の儀式">
1回限りの初回実行の儀式です。完全に新しいワークスペースにのみ作成されます。儀式が完了したら削除してください。
</Accordion>
<Accordion title="memory/YYYY-MM-DD.md — 日次メモリログ">
日次メモリログ（1日1ファイル）。セッション開始時に今日分と昨日分を読むことを推奨します。
日次メモリログ（1日につき1ファイル）です。セッション開始時に今日と昨日を読むことを推奨します。
</Accordion>
<Accordion title="MEMORY.md — キュレートされた長期メモリ（任意）">
キュレートされた長期メモリ。メインのプライベートセッションでのみ読み込んでください（共有/グループコンテキストではありません）。ワークフローと自動メモリflushについては [Memory](/ja-JP/concepts/memory) を参照してください。
<Accordion title="MEMORY.md — キュレーション済み長期メモリ（任意）">
キュレーション済みの長期メモリです。メインの非公開セッションでのみ読み込んでください（共有/グループコンテキストでは使用しません）。ワークフローと自動メモリフラッシュについては [Memory](/ja-JP/concepts/memory) を参照してください。
</Accordion>
<Accordion title="skills/ — ワークスペースSkills（任意）">
ワークスペース固有のSkills。そのワークスペースで最も優先度の高いskillの場所です。名前が衝突した場合、project agent skills、personal agent skills、managed skills、bundled skills、`skills.load.extraDirs` より優先されます。
<Accordion title="skills/ — ワークスペース Skills（任意）">
ワークスペース固有の Skills です。そのワークスペースで最も優先度の高い Skills の場所です。名前が衝突した場合、プロジェクトエージェント Skills、個人エージェント Skills、管理対象 Skills、バンドル済み Skills、および `skills.load.extraDirs` を上書きします。
</Accordion>
<Accordion title="canvas/ — Canvas UIファイル（任意）">
Node表示用のCanvas UIファイル（例: `canvas/index.html`）。
<Accordion title="canvas/ — Canvas UI ファイル（任意）">
ノード表示用の Canvas UI ファイルです（例: `canvas/index.html`）。
</Accordion>
</AccordionGroup>
<Note>
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` は、既存ファイルを上書きせずに欠けているデフォルトを再作成できます。
</Note>
## ワークスペースに含まれないもの
これらは `~/.openclaw/` 配下にあり、ワークスペースrepoにコミットすべきではありません。
これらは `~/.openclaw/` 配下にあり、ワークスペースリポジトリにコミットすべきではありません:
- `~/.openclaw/openclaw.json`（config）
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（モデル認証プロファイル: OAuth + API keys）
- `~/.openclaw/credentials/`（チャネル/プロバイダー状態およびレガシーOAuthインポートデータ）
- `~/.openclaw/agents/<agentId>/sessions/`（session transcript + metadata）
- `~/.openclaw/skills/`（managed Skills）
- `~/.openclaw/openclaw.json`（設定）
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（モデル認証プロファイル: OAuth + API キー）
- `~/.openclaw/agents/<agentId>/agent/codex-home/`（エージェントごとの Codex ランタイムアカウント、設定、Skills、plugins、ネイティブスレッド状態）
- `~/.openclaw/credentials/`（チャンネル/プロバイダー状態とレガシー OAuth インポートデータ）
- `~/.openclaw/agents/<agentId>/sessions/`（セッションのトランスクリプト + メタデータ）
- `~/.openclaw/skills/`（管理対象 Skills）
sessions や config を移行する必要がある場合は、それらを別途コピーし、バージョン管理には入れないでください。
セッションや設定を移行する必要がある場合は、別途コピーし、バージョン管理に含めないでください。
## Gitバックアップ（推奨、プライベート）
## Git バックアップ（推奨、非公開）
ワークスペースはプライベートメモリとして扱ってください。**プライベートな** git repo に入れて、バックアップおよび復旧可能にしてください。
ワークスペースは非公開メモリとして扱ってください。バックアップと復旧ができるよう、**private** git リポジトリに置いてください。
これらの手順は、Gateway が動作しているマシン上で実行してください（ワークスペースはそこにあります）。
これらの手順は Gateway が動作するマシン上で実行してください（そこにワークスペースがあります）。
<Steps>
<Step title="repoを初期化する">
git がインストールされていれば、真新しいワークスペースは自動的に初期化されます。このワークスペースがまだrepoでない場合は、次を実行してください。
<Step title="リポジトリを初期化する">
git がインストールされている場合、完全に新しいワークスペースは自動的に初期化されます。このワークスペースがまだリポジトリでない場合は、次を実行します:
```bash
cd ~/.openclaw/workspace
@ -139,13 +140,13 @@ sessions や config を移行する必要がある場合は、それらを別途
```
</Step>
<Step title="プライベートremoteを追加する">
<Step title="非公開リモートを追加する">
<Tabs>
<Tab title="GitHub web UI">
1. GitHubで新しい**プライベート**リポジトリを作成します。
2. README付きでは初期化しないでください（merge conflict を避けるため）。
3. HTTPSのremote URLをコピーします。
4. remoteを追加してpushします。
<Tab title="GitHub Web UI">
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
```
</Tab>
<Tab title="GitLab web UI">
1. GitLabで新しい**プライベート**リポジトリを作成します。
2. README付きでは初期化しないでください（merge conflict を避けるため）。
3. HTTPSのremote URLをコピーします。
4. remoteを追加してpushします。
<Tab title="GitLab Web UI">
1. GitLab で新しい **private** リポジトリを作成します。
2. README で初期化しないでください（マージコンフリクトを避けるため）。
3. HTTPS リモート URL をコピーします。
4. リモートを追加して push します:
```bash
git branch -M main
@ -184,19 +185,19 @@ sessions や config を移行する必要がある場合は、それらを別途
</Step>
</Steps>
## secrets をコミットしない
## シークレットをコミットしない
<Warning>
プライベートrepoであっても、ワークスペースにsecretsを保存するのは避けてください。
private リポジトリであっても、ワークスペースにシークレットを保存することは避けてください:
- API keys、OAuth tokens、passwords、またはprivate credentials。
- `~/.openclaw/` 配下のもの。
- チャットや機密添付の生ダンプ。
- API キー、OAuth トークン、パスワード、または非公開認証情報。
- `~/.openclaw/` 配下のあらゆるもの。
- チャットや機密添付ファイルの生ダンプ。
機密参照を保存する必要がある場合は、placeholder を使い、実際のsecretは別の場所（password manager、environment variables、または `~/.openclaw/`）に保持してください。
機密参照を保存する必要がある場合は、プレースホルダーを使用し、実際のシークレットは別の場所（パスワードマネージャー、環境変数、または `~/.openclaw/`）に保管してください。
</Warning>
推奨される `.gitignore` の初期例:
推奨 `.gitignore` スターター:
```gitignore
.DS_Store
@ -209,28 +210,28 @@ sessions や config を移行する必要がある場合は、それらを別途
## ワークスペースを新しいマシンへ移動する
<Steps>
<Step title="repoをcloneする">
目的のパス（デフォルトは `~/.openclaw/workspace`）にrepoをcloneします。
<Step title="リポジトリをクローンする">
目的のパス（デフォルトは `~/.openclaw/workspace`）にリポジトリをクローンします。
</Step>
<Step title="configを更新する">
`~/.openclaw/openclaw.json` の `agents.defaults.workspace` をそのパスに設定します。
<Step title="設定を更新する">
`~/.openclaw/openclaw.json` で `agents.defaults.workspace` をそのパスに設定します。
</Step>
<Step title="不足ファイルを初期配置する">
`openclaw setup --workspace <path>` を実行して、不足しているファイルを初期配置します。
<Step title="欠けているファイルを初期配置する">
`openclaw setup --workspace <path>` を実行して、欠けているファイルを初期配置します。
</Step>
<Step title="sessions をコピーする（任意）">
sessions が必要な場合は、古いマシンの `~/.openclaw/agents/<agentId>/sessions/` を別途コピーしてください。
<Step title="セッションをコピーする（任意）">
セッションが必要な場合は、古いマシンから `~/.openclaw/agents/<agentId>/sessions/` を別途コピーします。
</Step>
</Steps>
## 高度な注意事項
## 詳細メモ
- マルチエージェントルーティングでは、エージェントごとに異なるワークスペースを使用できます。ルーティング設定については [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) — ワークスペースファイル内の永続的な指示

1222
docs/ja-JP/gateway/security/index.md
View File

File diff suppressed because it is too large Load Diff

522
docs/ja-JP/plugins/codex-harness.md
View File

@ -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/<model>` に変更し、
`agentRuntime.id: "codex"` を設定します。
- ランタイム変更後も、既存セッションには `/new` または `/reset` が必要です。
セッションランタイムピンは固定的だからです。
- ネイティブ app-server 実行を意図していた場合は、モデルを `openai/<model>` に変更し、`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/<model>` に設定するレガシー設定でも、バンドルされた `codex` Plugin は引き続き自動で有効になります。
新しい設定では、上記の明示的な `agentRuntime` エントリに加えて `openai/<model>` を優先するべきです。
`agents.defaults.model` またはエージェントモデルを `codex/<model>` に設定するレガシー設定では、引き続き同梱の `codex` Plugin が自動的に有効になります。新しい設定では、上記の明示的な `agentRuntime` エントリと組み合わせて `openai/<model>` を使用することを推奨します。
## 他のモデルと並べて 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 スレッド `<id>` をここで再開して」 | `/codex resume <id>` |
| 「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 スレッド `<id>` をここで再開して」 | `/codex resume <id>` |
| 「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 <marketplace-source>`
- `/codex computer-use install --marketplace-path <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 <thread-id>` は、現在の 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 <thread-id>` は、現在の 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 <thread-id>` のような形で、ネイティブ 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 <thread-id>` のような形で、
ネイティブ 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 <thread-id>` コマンドが一覧表示されます。承認を拒否または無視した場合、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 <thread-id>` コマンドが一覧表示されます。承認を拒否または無視した場合、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 <thread-id>
```
チャンネル会話でバグに気づき、問題の Codex セッションを調べる、ローカルで続行する、または特定のツールや推論の選択を行った理由を Codex に尋ねる場合に使用します。通常、最も簡単な方法は先に `/diagnostics [note]` を実行することです。承認後、完了したレポートには各 Codex スレッドが一覧表示され、たとえば `codex resume <thread-id>` のような `Inspect locally` コマンドが出力されます。そのコマンドをそのままターミナルにコピーできます。
チャンネル会話でバグに気付き、問題のある Codex セッションを調査したい場合、ローカルで続行したい場合、または特定のツールや推論の選択をした理由を Codex に尋ねたい場合に使用します。通常、最も簡単な手順は、先に `/diagnostics [note]` を実行することです。承認後、完了したレポートには各 Codex スレッドが一覧表示され、たとえば `codex resume <thread-id>` のような `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 を再起動して再試行する。
## 関連

226
docs/ja-JP/tools/skills.md
View File

@ -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 | プロジェクトエージェントスキル | `<workspace>/.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 <name>` を繰り返します。
## エージェントごとのスキルと共有スキル
**マルチエージェント**構成では、各エージェントが独自のワークスペースを持ちます。
| スコープ | パス | 表示対象 |
| スコープ | パス | 表示先 |
| -------------------- | ------------------------------------------- | --------------------------- |
| エージェント別 | `<workspace>/skills` | そのエージェントのみ |
| エージェントごと | `<workspace>/skills` | そのエージェントのみ |
| プロジェクトエージェント | `<workspace>/.agents/skills` | そのワークスペースのエージェントのみ |
| 個人エージェント | `~/.agents/skills` | そのマシン上のすべてのエージェント |
| 共有管理対象/ローカル | `~/.openclaw/skills` | そのマシン上のすべてのエージェント |
| 共有追加ディレクトリ | `skills.load.extraDirs` (最低優先順位) | そのマシン上のすべてのエージェント |
複数の場所に同じ名前がある場合 → 最も高いソースが優先されます。ワークスペースは、プロジェクトエージェント、個人エージェント、管理対象/ローカル、バンドル、追加ディレクトリより優先されます。
複数の場所に同じ名前がある場合 → 最も高いソースが優先されます。ワークスペースはプロジェクトエージェントに優先し、プロジェクトエージェントは個人エージェントに優先し、個人エージェントは管理対象/ローカルに優先し、管理対象/ローカルはバンドル済みに優先し、バンドル済みは追加ディレクトリに優先します。
## エージェントスキルの許可リスト
## エージェントスキル許可リスト
スキルの**場所**とスキルの**可視性**は別々の制御です。場所/優先順位は、同名スキルのどのコピーが優先されるかを決定します。エージェントの許可リストは、エージェントが実際に使用できるスキルを決定します。
スキルの**場所**とスキルの**可視性**は別々の制御です。場所/優先順位は、同名スキルのどのコピーが優先されるかを決定します。エージェント許可リストは、エージェントが実際に使用できるスキルを決定します。
```json5
{
@ -66,63 +68,62 @@ OpenClaw は次のソースからスキルを読み込みます。**優先順位
```
<AccordionGroup>
<Accordion title="Allowlist rules">
- 既定でスキルを制限しない場合は、`agents.defaults.skills` を省略します。
<Accordion title="許可リストルール">
- デフォルトでスキルを無制限にするには、`agents.defaults.skills` を省略します。
- `agents.defaults.skills` を継承するには、`agents.list[].skills` を省略します。
- スキルなしにするには、`agents.list[].skills: []` を設定します。
- 空でない `agents.list[].skills` リストは、そのエージェントの**最終的な**セットです。既定値とはマージされません。
- 有効な許可リストは、プロンプト構築、スキルのスラッシュコマンド検出、サンドボックス同期、スキルスナップショット全体に適用されます。
- 空でない `agents.list[].skills` リストは、そのエージェントの**最終的な**セットです。デフォルトとはマージされません。
- 有効な許可リストは、プロンプト構築、スキルスラッシュコマンド検出、サンドボックス同期、スキルスナップショット全体に適用されます。
</Accordion>
</AccordionGroup>
## 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 は `<workspace>/skills` にのみ書き込み、生成された内容をスキャンし、承認待ちまたは自動の安全な書き込みをサポートし、安全でない提案を隔離し、書き込み成功後にスキルスナップショットを更新して、Gateway の再起動なしで新しいスキルを利用可能にします。
Skill Workshop は `<workspace>/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 <skill-slug>` |
| インストール済みスキルをすべて更新 | `openclaw skills update --all` |
| 同期 (スキャン + 更新の公開) | `clawhub sync --all` |
| ワークスペースにスキルをインストール | `openclaw skills install <skill-slug>` |
| インストール済みのすべてのスキルを更新 | `openclaw skills update --all` |
| 同期 (スキャン + 更新公開) | `clawhub sync --all` |
ネイティブの `openclaw skills install` は、アクティブなワークスペースの `skills/` ディレクトリにインストールします。別の `clawhub` CLI も、現在の作業ディレクトリ配下の `./skills` にインストールします (または設定済みの OpenClaw ワークスペースにフォールバックします)。OpenClaw は次のセッションでそれを `<workspace>/skills` として拾います。
設定済みのスキルルートでは、`skills/<group>/<skill>/SKILL.md` のように 1 階層のグループ化もサポートされるため、広範な再帰スキャンなしで関連するサードパーティスキルを共有フォルダー配下に保持できます。
ネイティブの `openclaw skills install` は、アクティブなワークスペースの `skills/` ディレクトリにインストールします。別の `clawhub` CLI も、現在の作業ディレクトリ配下の `./skills` にインストールします (または、設定済みの OpenClaw ワークスペースにフォールバックします)。OpenClaw は次のセッションでそれを `<workspace>/skills` として取り込みます。
設定済みスキルルートは、`skills/<group>/<skill>/SKILL.md` のように 1 レベルのグループ化もサポートしているため、関連するサードパーティスキルを、広範な再帰スキャンなしで共有フォルダー配下に保持できます。
ClawHub のスキルページは、インストール前に最新のセキュリティスキャン状態を公開し、VirusTotal、ClawScan、静的解析のスキャナー詳細ページを提供します。`openclaw skills install <slug>` は引き続きインストール経路のみです。公開者は ClawHub ダッシュボードまたは `clawhub skill rescan <slug>` を通じて誤検出から復旧します。
ClawHub スキルページは、インストール前に最新のセキュリティスキャン状態を表示し、VirusTotal、ClawScan、静的解析のスキャナー詳細ページも提供します。`openclaw skills install <slug>` はインストール経路でしかありません。公開者は ClawHub ダッシュボードまたは `clawhub skill rescan <slug>` を通じて誤検出から回復します。
## セキュリティ
<Warning>
サードパーティスキルは**信頼できないコード**として扱ってください。有効化する前に読んでください。信頼できない入力や危険なツールには、サンドボックス化された実行を優先してください。エージェント側の制御については [Sandboxing](/ja-JP/gateway/sandboxing) を参照してください。
サードパーティスキルは**信頼されていないコード**として扱ってください。有効化する前に読んでください。信頼されていない入力やリスクのあるツールには、サンドボックス化された実行を推奨します。エージェント側の制御については [サンドボックス化](/ja-JP/gateway/sandboxing) を参照してください。
</Warning>
- ワークスペースおよび追加ディレクトリのスキル検出は、解決済みの realpath が設定済みルート内に留まるスキルルートと `SKILL.md` ファイルのみを受け入れます。
- Gateway バックのスキル依存関係インストール (`skills.install`、オンボーディング、Skills設定UI) は、インストーラーメタデータを実行する前に組み込みの危険コードスキャナーを実行します。呼び出し元が危険なオーバーライドを明示的に設定しない限り、`critical` の検出結果は既定でブロックされます。疑わしい検出結果は引き続き警告のみです。
- `openclaw skills install <slug>` は別物です。これは ClawHub スキルフォルダーをワークスペースにダウンロードし、上記のインストーラーメタデータ経路は使用しません。
- ワークスペースおよび追加ディレクトリのスキル検出は、解決済み realpath が設定済みルート内に留まるスキルルートと `SKILL.md` ファイルのみを受け入れます。
- Gateway-backed スキル依存関係インストール (`skills.install`、オンボーディング、Skills 設定 UI) は、インストーラーメタデータを実行する前に組み込みの危険コードスキャナーを実行します。`critical` の検出結果は、呼び出し元が危険なオーバーライドを明示的に設定しない限りデフォルトでブロックされます。不審な検出結果は警告のみのままです。
- `openclaw skills install <slug>` は異なります。これは 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}` を使用します。
### 任意のフロントマターキー
<ParamField path="homepage" type="string">
macOS Skills UI で「Webサイト」として表示される URL。`metadata.openclaw.homepage` 経由でもサポートされます。
macOS Skills UI で「Website」として表示される URL。`metadata.openclaw.homepage` 経由でもサポートされます。
</ParamField>
<ParamField path="user-invocable" type="boolean" default="true">
`true` の場合、スキルはユーザーのスラッシュコマンドとして公開されます。
`true` の場合、スキルはユーザースラッシュコマンドとして公開されます。
</ParamField>
<ParamField path="disable-model-invocation" type="boolean" default="false">
`true` の場合、スキルはモデルプロンプトから除外されます (ユーザー呼び出しでは引き続き利用可能)。
@ -151,10 +152,10 @@ OpenClaw はレイアウト/意図について AgentSkills 仕様に従います
`command-dispatch: tool` が設定されている場合に呼び出すツール名。
</ParamField>
<ParamField path="command-arg-mode" type='"raw"' default="raw">
ツールディスパッチでは、生の引数文字列をツールへ転送します (コア側の解析なし)。ツールは `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }` で呼び出されます。
ツールディスパッチでは、生の引数文字列をツールに転送します (コア解析なし)。ツールは `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }` で呼び出されます。
</ParamField>
## ゲート制御 (読み込み時フィルター)
## ゲーティング (読み込み時フィルター)
OpenClaw は `metadata` (単一行 JSON) を使用して、読み込み時にスキルをフィルタリングします。
@ -176,16 +177,16 @@ metadata:
`metadata.openclaw` 配下のフィールド:
<ParamField path="always" type="boolean">
`true` の場合、常にスキルを含めます (他のゲートをスキップします)。
`true` の場合、常にスキルを含めます (他のゲートをスキップ)。
</ParamField>
<ParamField path="emoji" type="string">
macOS Skills UI で使用される任意の絵文字。
</ParamField>
<ParamField path="homepage" type="string">
macOS Skills UI で「Webサイト」として表示される任意の URL。
macOS Skills UI で「Website」として表示される任意の URL。
</ParamField>
<ParamField path="os" type='"darwin" | "linux" | "win32"' >
任意のプラットフォーム一覧。設定されている場合、スキルはそれらの OS でのみ対象になります。
任意のプラットフォーム一覧。設定すると、スキルはそれらの OS でのみ対象になります。
</ParamField>
<ParamField path="requires.bins" type="string[]">
それぞれが `PATH` 上に存在する必要があります。
@ -200,23 +201,23 @@ metadata:
truthy である必要がある `openclaw.json` パスの一覧。
</ParamField>
<ParamField path="primaryEnv" type="string">
`skills.entries.<name>.apiKey` に関連付けられる環境変数名。
`skills.entries.<name>.apiKey` に関連付けられた環境変数名。
</ParamField>
<ParamField path="install" type="object[]">
macOS Skills UI で使用される任意のインストーラー仕様 (brew/node/go/uv/download)。
</ParamField>
`metadata.openclaw` が存在しない場合、スキルは常に対象になります (設定で無効化されている場合や、バンドルスキルに対して `skills.allowBundled` によってブロックされている場合を除く)。
`metadata.openclaw` が存在しない場合、スキルは常に対象になります (設定で無効化されている場合、またはバンドル済みスキルに対して `skills.allowBundled` でブロックされている場合を除く)。
<Note>
`metadata.openclaw` が存在しない場合は、従来の `metadata.clawdbot` ブロックも引き続き受け入れられるため、古いインストール済みスキルは依存関係ゲートとインストーラーヒントを維持します。新規および更新されたスキルでは `metadata.openclaw` を使用してください。
レガシーの `metadata.clawdbot` ブロックは、`metadata.openclaw` が存在しない場合も引き続き受け入れられるため、古いインストール済みスキルは依存関係ゲートとインストーラーヒントを維持します。新規および更新済みスキルでは `metadata.openclaw` を使用してください。
</Note>
### サンドボックス化の注意事項
- `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:
<AccordionGroup>
<Accordion title="インストーラー選択ルール">
- 複数のインストーラーが一覧されている場合、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 つの優先インストーラーにまとめず、すべてのダウンロードオプションを表示します。
</Accordion>
<Accordion title="インストーラーごとの詳細">
- **Go インストール:** `go` がなく `brew` が利用可能な場合、Gateway はまず Homebrew 経由で Go をインストールし、可能な場合は `GOBIN` を Homebrew の `bin` に設定します。
- **ダウンロードインストール:** `url`（必須）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（デフォルト: アーカイブ検出時に自動）、`stripComponents`、`targetDir`（デフォルト: `~/.openclaw/tools/<skillKey>`）。
- **Go インストール:** `go` がなく、`brew` が利用可能な場合、Gateway はまず Homebrew 経由で Go をインストールし、可能であれば `GOBIN` を Homebrew の `bin` に設定します。
- **ダウンロードインストール:** `url`（必須）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（デフォルト: アーカイブ検出時は自動）、`stripComponents`、`targetDir`（デフォルト: `~/.openclaw/tools/<skillKey>`）。
</Accordion>
</AccordionGroup>
## 設定の上書き
バンドルおよび管理対象の Skills は、`~/.openclaw/openclaw.json` の
`skills.entries` 配下で切り替えたり env 値を指定したりできます。
バンドル済みおよび管理対象の skills は、`~/.openclaw/openclaw.json` の
`skills.entries` 配下で切り替えたり、env 値を指定したりできます。
```json5
{
@ -290,14 +291,14 @@ metadata:
```
<ParamField path="enabled" type="boolean">
`false` は、その skill がバンドル済みまたはインストール済みであっても無効化します。
`false` は、その skill がバンドル済みまたはインストール済みであっても無効にします。
バンドル済みの `coding-agent` skill はオプトインです。エージェントに公開する前に
`skills.entries.coding-agent.enabled: true` を設定し、
そのうえで `claude`、`codex`、`opencode`、または `pi` のいずれかがインストールされ、
その後、`claude`、`codex`、`opencode`、または `pi` のいずれかがインストールされ、
それ自身の CLI で認証済みであることを確認してください。
</ParamField>
<ParamField path="apiKey" type='string | { source, provider, id }'>
`metadata.openclaw.primaryEnv` を宣言する Skills 向けの簡易指定です。平文または SecretRef をサポートします。
`metadata.openclaw.primaryEnv` を宣言する skills 向けの便利設定です。プレーンテキストまたは SecretRef をサポートします。
</ParamField>
<ParamField path="env" type="Record<string, string>">
変数がプロセス内でまだ設定されていない場合にのみ注入されます。
@ -306,21 +307,21 @@ metadata:
skill ごとのカスタムフィールド用の任意の入れ物です。カスタムキーはここに置く必要があります。
</ParamField>
<ParamField path="allowBundled" type="string[]">
**バンドル済み** Skills のみを対象にする任意の許可リストです。設定した場合、リスト内のバンドル済み Skills だけが対象になります（管理対象/workspace Skills には影響しません）。
**バンドル済み** skills のみに対する任意の許可リストです。設定した場合、一覧内のバンドル済み skills のみが対象になります（管理対象/workspace skills には影響しません）。
</ParamField>
skill 名にハイフンが含まれる場合は、キーを引用符で囲みます（JSON5 では引用符付き
キーが許可されます）。設定キーはデフォルトで **skill 名** と一致します。skill が
`metadata.openclaw.skillKey` を定義している場合は、`skills.entries` 配下でそのキーを使用してください。
`metadata.openclaw.skillKey` を定義している場合は、そのキーを `skills.entries` 配下で使用してください。
<Note>
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 キーも追加してください。
</Note>
## 環境の注入
@ -329,38 +330,39 @@ auth/API キーも追加してください。
1. skill メタデータを読み取ります。
2. `skills.entries.<key>.env` と `skills.entries.<key>.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 エスケープ済みの `<name>`、`<description>`、`<location>` 値の長さ。
@ -400,28 +403,29 @@ Skills が対象になると、OpenClaw は利用可能な Skills のコンパ
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
```
XML エスケープでは `& < > " '` がエンティティ（`&amp;`、`&lt;` など）に展開されるため、
長さが増えます。トークン数はモデルのトークナイザーによって異なります。OpenAI 風の概算では
約 4 文字/トークンなので、**97 文字 ≈ 24 トークン**が skill ごとにかかり、さらに実際のフィールド長が加わります。
XML エスケープでは `& < > " '` がエンティティ（`&amp;`、`&lt;` など）に展開され、
長さが増えます。トークン数はモデルのトークナイザーによって異なります。大まかな
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) — 利用可能なすべてのスラッシュコマンド