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-23 15:05:47 +00:00
parent 1520aa5369
commit 422c56b6f1
6 changed files with 1324 additions and 1541 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
docs/ja-JP/channels/matrix-push-rules.md Normal file
View File

@ -0,0 +1,157 @@
---
read_when:
- セルフホスト型SynapseまたはTuwunel向けにMatrixの静かなストリーミングを設定する方法
- ユーザーは、すべてのプレビュー編集ではなく、完了したブロックでのみ通知を受け取りたいと考えています
summary: 静かな確定済みプレビュー編集に対する受信者ごとのMatrixプッシュルール
title: 静かなプレビューに対するMatrixプッシュルール
x-i18n:
generated_at: "2026-04-23T15:00:52Z"
model: gpt-5.4
provider: openai
source_hash: dbfdf2552ca352858d4e8d03a2a0f5f3b420d33b01063c111c0335c0229f0534
source_path: channels/matrix-push-rules.md
workflow: 15
---
# 静かなプレビューに対するMatrixプッシュルール
`channels.matrix.streaming` が `"quiet"` の場合、OpenClaw は単一のプレビューイベントをその場で編集し、確定した編集にカスタムのコンテンツフラグを付けます。Matrixクライアントが最終編集時にのみ通知するには、ユーザーごとのプッシュルールがそのフラグに一致する必要があります。このページは、Matrixをセルフホストしていて、受信者アカウントごとにそのルールをインストールしたい運用者向けです。
標準のMatrix通知動作だけが必要な場合は、`streaming: "partial"` を使うか、ストリーミングをオフのままにしてください。[Matrixチャネルの設定](/ja-JP/channels/matrix#streaming-previews)を参照してください。
## 前提条件
- recipient user = 通知を受け取る人
- bot user = 返信を送信するOpenClaw Matrixアカウント
- 以下のAPI呼び出しでは recipient user のアクセストークンを使用する
- プッシュルール内の `sender` は bot user の完全なMXID に一致させる
- recipient アカウントには、すでに動作する pusher が存在している必要があります。静かなプレビュールールは、通常のMatrixプッシュ配信が正常に機能している場合にのみ動作します
## 手順
<Steps>
<Step title="静かなプレビューを設定する">
```json5
{
channels: {
matrix: {
streaming: "quiet",
},
},
}
```
</Step>
<Step title="受信者のアクセストークンを取得する">
可能であれば既存のクライアントセッショントークンを再利用してください。新しく発行するには、次を実行します。
```bash
curl -sS -X POST \
"https://matrix.example.org/_matrix/client/v3/login" \
-H "Content-Type: application/json" \
--data '{
"type": "m.login.password",
"identifier": { "type": "m.id.user", "user": "@alice:example.org" },
"password": "REDACTED"
}'
```
</Step>
<Step title="pusher が存在することを確認する">
```bash
curl -sS \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
"https://matrix.example.org/_matrix/client/v3/pushers"
```
pusher が返ってこない場合は、続行する前にこのアカウントの通常のMatrixプッシュ配信を修正してください。
</Step>
<Step title="override プッシュルールをインストールする">
OpenClaw は、確定したテキストのみのプレビュー編集に `content["com.openclaw.finalized_preview"] = true` を付けます。このマーカーと bot MXID を送信者として一致させるルールをインストールしてください。
```bash
curl -sS -X PUT \
"https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"conditions": [
{ "kind": "event_match", "key": "type", "pattern": "m.room.message" },
{
"kind": "event_property_is",
"key": "content.m\\.relates_to.rel_type",
"value": "m.replace"
},
{
"kind": "event_property_is",
"key": "content.com\\.openclaw\\.finalized_preview",
"value": true
},
{ "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
],
"actions": [
"notify",
{ "set_tweak": "sound", "value": "default" },
{ "set_tweak": "highlight", "value": false }
]
}'
```
実行前に以下を置き換えてください。
- `https://matrix.example.org`: あなたのホームサーバーのベースURL
- `$USER_ACCESS_TOKEN`: recipient user のアクセストークン
- `openclaw-finalized-preview-botname`: 受信者ごと・bot ごとに一意な rule ID（パターン: `openclaw-finalized-preview-<botname>`）
- `@bot:example.org`: recipient ではなく、あなたのOpenClaw bot のMXID
</Step>
<Step title="確認する">
```bash
curl -sS \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
"https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
```
その後、ストリーミング返信をテストしてください。quiet モードでは、ルームには静かな下書きプレビューが表示され、ブロックまたはターンの完了時に一度だけ通知されます。
</Step>
</Steps>
後でルールを削除するには、recipient のトークンを使って同じルールURL に対して `DELETE` してください。
## 複数botに関する注意
プッシュルールは `ruleId` によって識別されます。同じID に対して `PUT` を再実行すると、単一のルールが更新されます。同じ recipient に複数のOpenClaw bot が通知する場合は、送信者一致条件が異なる bot ごとに1つのルールを作成してください。
新しいユーザー定義の `override` ルールは、デフォルトの抑制ルールより前に挿入されるため、追加の順序パラメーターは不要です。このルールが影響するのは、その場で確定可能なテキストのみのプレビュー編集だけです。メディアのフォールバックや古いプレビューのフォールバックでは、通常のMatrix配信が使われます。
## ホームサーバーに関する注意
<AccordionGroup>
<Accordion title="Synapse">
特別な `homeserver.yaml` の変更は不要です。通常のMatrix通知がすでにこのユーザーに届いている場合、主な設定手順は受信者トークンと上記の `pushrules` 呼び出しです。
Synapse をリバースプロキシや workers の背後で運用している場合は、`/_matrix/client/.../pushrules/` が正しくSynapse に到達することを確認してください。プッシュ配信はメインプロセスまたは `synapse.app.pusher` / 設定済みの pusher workers によって処理されるため、それらが正常であることを確認してください。
</Accordion>
<Accordion title="Tuwunel">
Synapse と同じフローで、確定済みプレビューマーカーのためのTuwunel固有設定は不要です。
ユーザーが別のデバイスでアクティブなときに通知が消える場合は、`suppress_push_when_active` が有効になっていないか確認してください。Tuwunel は 1.4.2（2025年9月）でこのオプションを追加しており、1つのデバイスがアクティブな間、他のデバイスへのプッシュを意図的に抑制することがあります。
</Accordion>
</AccordionGroup>
## 関連
- [Matrixチャネルの設定](/ja-JP/channels/matrix)
- [ストリーミングの概念](/ja-JP/concepts/streaming)

863
docs/ja-JP/channels/matrix.md
View File

File diff suppressed because it is too large Load Diff

139
docs/ja-JP/ci.md
View File

@ -1,107 +1,108 @@
---
read_when:
- CI ジョブが実行された、または実行されなかった理由を理解する必要がある
- 失敗している GitHub Actions チェックをデバッグしている
summary: CI ジョブグラフ、スコープゲート、および対応するローカルコマンド
- CI ジョブが実行された、または実行されなかった理由を把握する必要があります
- 失敗している GitHub Actions チェックをデバッグしています
summary: CI ジョブグラフ、スコープゲート、およびローカルコマンドの同等物
title: CI パイプライン
x-i18n:
generated_at: "2026-04-23T14:00:04Z"
generated_at: "2026-04-23T15:00:49Z"
model: gpt-5.4
provider: openai
source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f
source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d
source_path: ci.md
workflow: 15
---
# CI パイプライン
CI は `main` へのすべての push とすべての pull request で実行されます。スマートなスコープ判定を使用しており、変更が無関係な領域だけの場合は高コストのジョブをスキップします。
CI は `main` へのすべての push とすべての pull request で実行されます。スマートスコープを使用しており、変更が無関係な領域だけに限られる場合は高コストなジョブをスキップします。
QA Lab には、メインのスマートスコープワークフローの外側に専用の CI レーンがあります。
`Parity gate` ワークフローは、一致する PR 変更時と manual dispatch で実行されます。これは
プライベートな QA ランタイムをビルドし、モックの GPT-5.4 と Opus 4.6 の
QA Lab には、メインのスマートスコープワークフローとは別に専用の CI レーンがあります。
`Parity gate` ワークフローは、該当する PR の変更時と手動実行で走行し、
非公開の QA ランタイムをビルドして、モックの GPT-5.4 および Opus 4.6 の
agentic pack を比較します。`QA-Lab - All Lanes` ワークフローは、`main` で毎晩実行され、
manual dispatch でも実行されます。これはモック parity gate、ライブ Matrix レーン、
ライブ Telegram レーンを並列ジョブとして展開します。ライブジョブは `qa-live-shared`
environment を使用し、Telegram レーンは Convex leases を使用します。`OpenClaw Release
Checks` も、リリース承認前に同じ QA Lab レーンを実行します。
手動実行でも走行します。これは、モック parity gate、ライブ Matrix レーン、
ライブ Telegram レーンを並列ジョブとしてファンアウトします。ライブジョブは
`qa-live-shared` environment を使用し、Telegram レーンは Convex lease を使用します。
`OpenClaw Release Checks` も、リリース承認前に同じ QA Lab レーンを実行します。
## ジョブ概要
| ジョブ | 目的 | 実行されるタイミング |
| ---------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | docs-only の変更、変更スコープ、変更された extensions を検出し、CI manifest をビルドする | draft ではない push と PR で常に実行 |
| `security-scm-fast` | `zizmor` による秘密鍵検出とワークフロー監査 | draft ではない push と PR で常に実行 |
| `security-dependency-audit` | npm advisories に対する、依存関係不要の本番 lockfile 監査 | draft ではない push と PR で常に実行 |
| `security-fast` | 高速セキュリティジョブ用の必須 aggregate | draft ではない push と PR で常に実行 |
| `build-artifacts` | `dist/`、Control UI、built-artifact チェック、および再利用可能な下流 artifact のビルド | Node 関連の変更 |
| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速 Linux 正当性レーン | Node 関連の変更 |
| `checks-fast-contracts-channels` | 安定した aggregate check 結果を持つ、分割された channel contract チェック | Node 関連の変更 |
| `checks-node-extensions` | extension スイート全体にわたる bundled-plugin テストの完全 shard | Node 関連の変更 |
| `checks-node-core-test` | channel、bundled、contract、および extension レーンを除く、core Node テスト shard | Node 関連の変更 |
| `extension-fast` | 変更された bundled plugins のみに対する重点テスト | extension に変更がある pull request |
| `check` | 分割されたメインのローカル gate 相当: prod types、lint、guards、test types、および strict smoke | Node 関連の変更 |
| `check-additional` | architecture、boundary、extension-surface guards、package-boundary、および gateway-watch shard | Node 関連の変更 |
| `build-smoke` | built-CLI smoke テストと startup-memory smoke | Node 関連の変更 |
| `checks` | built-artifact channel テスト用 verifier と、push のみの Node 22 互換性 | Node 関連の変更 |
| `check-docs` | docs のフォーマット、lint、および broken-link チェック | docs が変更されたとき |
| `skills-python` | Python バックエンドの Skills 用 Ruff + pytest | Python-skill 関連の変更 |
| `checks-windows` | Windows 固有のテストレーン | Windows 関連の変更 |
| `macos-node` | 共有 built artifacts を使用する macOS TypeScript テストレーン | macOS 関連の変更 |
| `macos-swift` | macOS app 用の Swift lint、build、および tests | macOS 関連の変更 |
| `android` | 両フレーバー向けの Android unit tests と 1 つの debug APK ビルド | Android 関連の変更 |
| ジョブ | 目的 | 実行されるタイミング |
| ---------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- |
| `preflight` | docs-only の変更、変更されたスコープ、変更された extension を検出し、CI manifest を構築する | draft ではないすべての push と PR |
| `security-scm-fast` | `zizmor` による秘密鍵検出と workflow 監査 | draft ではないすべての push と PR |
| `security-dependency-audit` | npm advisory に対する、依存関係不要の本番 lockfile 監査 | draft ではないすべての push と PR |
| `security-fast` | 高速なセキュリティジョブ用の必須 aggregate | draft ではないすべての push と PR |
| `build-artifacts` | `dist/`、Control UI、ビルド済み artifact チェック、および下流で再利用可能な artifact をビルドする | Node 関連の変更 |
| `checks-fast-core` | bundled/plugin-contract/protocol チェックなどの高速 Linux 正当性レーン | Node 関連の変更 |
| `checks-fast-contracts-channels` | 安定した aggregate チェック結果を持つ shard 化された channel contract チェック | Node 関連の変更 |
| `checks-node-extensions` | extension suite 全体に対する完全な bundled-plugin テスト shard | Node 関連の変更 |
| `checks-node-core-test` | channel、bundled、contract、extension レーンを除く、core Node テスト shard | Node 関連の変更 |
| `extension-fast` | 変更された bundled plugin のみを対象にした絞り込みテスト | extension に変更がある pull request |
| `check` | shard 化されたメインのローカルゲート相当: 本番型、lint、guard、テスト型、strict smoke | Node 関連の変更 |
| `check-additional` | architecture、boundary、extension-surface guard、package-boundary、および gateway-watch shard | Node 関連の変更 |
| `build-smoke` | ビルド済み CLI の smoke テストと起動時メモリ smoke | Node 関連の変更 |
| `checks` | ビルド済み artifact の channel テストに加え、push 時のみ Node 22 互換性を検証する verifier | Node 関連の変更 |
| `check-docs` | docs のフォーマット、lint、リンク切れチェック | docs が変更されたとき |
| `skills-python` | Python ベースの Skills に対する Ruff + pytest | Python Skills 関連の変更 |
| `checks-windows` | Windows 固有のテストレーン | Windows 関連の変更 |
| `macos-node` | 共有ビルド artifact を使う macOS TypeScript テストレーン | macOS 関連の変更 |
| `macos-swift` | macOS app 向けの Swift lint、ビルド、およびテスト | macOS 関連の変更 |
| `android` | 両 flavor の Android unit test と、1 つの debug APK ビルド | Android 関連の変更 |
## Fail-Fast 順序
## Fail-Fast の順序
ジョブは、高コストなものが実行される前に低コストなチェックで失敗するよう順序付けされています:
ジョブは、安価なチェックが高コストなジョブより先に失敗するように順序付けされています。
1. `preflight` が、どのレーンをそもそも存在させるかを決定します。`docs-scope` と `changed-scope` ロジックは、このジョブ内のステップであり、独立したジョブではありません。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、および `skills-python` は、より重い artifact や platform matrix ジョブを待たずに素早く失敗します。
3. `build-artifacts` は高速 Linux レーンと並行して動作するため、共有 build の準備ができしだい下流の利用者が開始できます。
4. その後、より重い platform および runtime レーンが展開されます: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、PR 専用の `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、および `android`。
1. `preflight` が、どのレーンをそもそも存在させるかを決定します。`docs-scope` と `changed-scope` のロジックは、このジョブ内の step であり、独立したジョブではありません。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs`、`skills-python` は、より重い artifact ジョブや platform matrix ジョブを待たずに素早く失敗します。
3. `build-artifacts` は高速 Linux レーンと並行して実行されるため、下流の利用側は共有ビルドの準備ができ次第開始できます。
4. その後、より重い platform および runtime レーンがファンアウトします: `checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、PR 専用の `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift`、`android`。
スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` の unit tests でカバーされています。
CI ワークフローの編集では Node CI グラフとワークフロー lint が検証されますが、それ自体では Windows、Android、または macOS のネイティブ build を強制しません。これらの platform レーンは platform ソース変更に対してのみスコープされます。
Windows Node チェックは、Windows 固有の process/path wrapper、npm/pnpm/UI runner helper、package manager config、およびそのレーンを実行する CI ワークフロー表面にスコープされます。無関係なソース、Plugin、install-smoke、および test-only の変更は Linux Node レーンにとどまるため、通常の test shard ですでにカバーされている検証のために 16-vCPU の Windows worker を確保しません。
別個の `install-smoke` ワークフローは、自身の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。より狭い changed-smoke シグナルから `run_install_smoke` を算出するため、Docker/install smoke は install、packaging、container 関連の変更、bundled extension の本番変更、および Docker smoke ジョブが対象とする core の Plugin/channel/gateway/Plugin SDK 表面で実行されます。test-only と docs-only の編集では Docker worker を確保しません。その QR package smoke は、BuildKit の pnpm store cache を維持しつつ Docker の `pnpm install` レイヤーを強制的に再実行するため、毎回依存関係を再ダウンロードせずにインストールを検証します。その gateway-network e2e は、ジョブ内で先にビルドした runtime image を再利用するため、別の Docker build を追加せずに実際の container-to-container WebSocket カバレッジを追加します。ローカルの `test:docker:all` は、1 つの共有 live-test image と 1 つの共有 `scripts/e2e/Dockerfile` built-app image を事前ビルドし、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` で live/E2E smoke レーンを並列実行します。デフォルト並列数 4 は `OPENCLAW_DOCKER_ALL_PARALLELISM` で調整できます。ローカル aggregate は、デフォルトで最初の失敗後に新しい pooled レーンのスケジューリングを停止し、各レーンには `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` で上書き可能な 120 分タイムアウトがあります。startup または provider に敏感なレーンは、並列プールの後に排他的に実行されます。再利用可能な live/E2E ワークフローは、Docker matrix の前に 1 つの SHA タグ付き GHCR Docker E2E image をビルドして push し、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` で matrix を実行することで、この共有 image パターンを反映しています。scheduled live/E2E ワークフローは、完全な release-path Docker スイートを毎日実行します。QR と installer の Docker テストは、それぞれ独自の install 重視 Dockerfile を維持します。別個の `docker-e2e-fast` ジョブは、120 秒のコマンドタイムアウトのもとで制限付き bundled-plugin Docker profile を実行します: setup-entry 依存関係修復と、synthetic bundled-loader failure isolation です。完全な bundled update/channel matrix は、実際の npm update と doctor repair パスを繰り返し実行するため、manual/full-suite のままです。
スコープロジックは `scripts/ci-changed-scope.mjs` にあり、`src/scripts/ci-changed-scope.test.ts` の unit test でカバーされています。
CI workflow の編集では Node CI グラフと workflow linting が検証されますが、それ自体では Windows、Android、macOS のネイティブビルドは強制されません。これらの platform レーンは、引き続き platform のソース変更に対してのみスコープされます。
Windows Node チェックは、Windows 固有の process/path wrapper、npm/pnpm/UI runner helper、package manager 設定、およびそのレーンを実行する CI workflow surface に対してスコープされます。無関係なソース、plugin、install-smoke、テスト専用の変更は Linux の Node レーンに留まるため、通常のテスト shard ですでにカバーされている範囲のために 16-vCPU の Windows worker を確保することはありません。
別の `install-smoke` ワークフローは、独自の `preflight` ジョブを通じて同じスコープスクリプトを再利用します。これは、より狭い changed-smoke シグナルから `run_install_smoke` を計算するため、Docker/install smoke は install、packaging、container 関連の変更、bundled extension の本番変更、および Docker smoke ジョブが実行する core plugin/channel/gateway/Plugin SDK surface で走行します。テスト専用および docs 専用の編集では Docker worker は確保されません。その QR package smoke は、BuildKit pnpm store cache を維持しながら Docker の `pnpm install` layer の再実行を強制するため、毎回依存関係を再ダウンロードせずにインストールを引き続き検証できます。その gateway-network e2e は、ジョブ内の前段でビルドされた runtime image を再利用するため、追加の Docker build を増やさずに実際の container-to-container WebSocket カバレッジを追加します。ローカルの `test:docker:all` は、共有の live-test image を 1 つと共有の `scripts/e2e/Dockerfile` built-app image を 1 つ事前ビルドし、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` で live/E2E smoke レーンを並列実行します。デフォルトの並列度 4 は `OPENCLAW_DOCKER_ALL_PARALLELISM` で調整できます。ローカル aggregate は、デフォルトでは最初の失敗後に新しい pooled レーンのスケジューリングを停止し、各レーンには 120 分の timeout があり、`OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` で上書きできます。起動や provider に敏感なレーンは、並列プールの後に排他的に実行されます。再利用可能な live/E2E workflow は、この共有 image パターンを踏襲し、Docker matrix の前に SHA タグ付きの GHCR Docker E2E image を 1 つビルドして push し、その後 `OPENCLAW_SKIP_DOCKER_BUILD=1` で matrix を実行します。定期実行される live/E2E workflow は、リリースパスの Docker suite 全体を毎日実行します。QR と installer の Docker テストは、それぞれ独自の install 重視 Dockerfile を維持します。別個の `docker-e2e-fast` ジョブは、120 秒のコマンド timeout の下で、境界を絞った bundled-plugin Docker profile を実行します: setup-entry の依存関係修復と synthetic な bundled-loader 障害の分離です。完全な bundled update/channel matrix は、実際の npm update と doctor repair の反復実行を行うため、手動実行または full-suite にのみ残されています。
ローカルの changed-lane ロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。このローカル gate は、広い CI platform スコープよりも architecture boundary に対して厳格です。core の本番変更は core prod typecheck と core tests を実行し、core の test-only 変更は core test typecheck/tests のみを実行し、extension の本番変更は extension prod typecheck と extension tests を実行し、extension の test-only 変更は extension test typecheck/tests のみを実行します。公開 Plugin SDK または plugin-contract の変更は、extensions がそれらの core contract に依存するため、extension 検証まで拡張されます。リリースメタデータのみの version bump では、対象を絞った version/config/root-dependency チェックが実行されます。不明な root/config の変更は安全側に倒してすべてのレーンになります。
ローカルの changed-lane ロジックは `scripts/changed-lanes.mjs` にあり、`scripts/check-changed.mjs` によって実行されます。このローカルゲートは、広い CI platform scope よりも architecture boundary に対して厳格です。core の本番変更では core の本番 typecheck と core テストを実行し、core のテスト専用変更では core のテスト typecheck/tests のみを実行し、extension の本番変更では extension の本番 typecheck と extension テストを実行し、extension のテスト専用変更では extension のテスト typecheck/tests のみを実行します。公開 Plugin SDK または plugin-contract の変更は、extension がそれらの core contract に依存しているため、extension 検証まで拡張されます。リリースメタデータ専用の version bump では、対象を絞った version/config/root-dependency チェックを実行します。未知の root/config 変更は、安全側に倒してすべてのレーンを実行します。
push では、`checks` matrix に push 専用の `compat-node22` レーンが追加されます。pull request では、このレーンはスキップされ、matrix は通常の test/channel レーンに集中したままです。
push では、`checks` matrix に push 専用の `compat-node22` レーンが追加されます。pull request では、このレーンはスキップされ、matrix は通常の test/channel レーンに集中したままになります。
最も遅い Node テスト群は分割または均等化されており、各ジョブが小さく保たれます。channel contracts は registry と core カバレッジを合計 6 つの重み付き shard に分割し、bundled plugin テストは 6 つの extension worker にバランス配分され、auto-reply は 6 個の小さな worker ではなく 3 個のバランスされた worker として実行され、agentic gateway/plugin configs は built artifacts を待つ代わりに既存の source-only agentic Node ジョブに分散されます。広範な browser、QA、media、および miscellaneous plugin テストは、共有 plugin catch-all ではなく専用の Vitest config を使用します。広範な agents レーンは、単一の遅いテストファイルに支配されるのではなく import/スケジューリング支配型であるため、共有 Vitest の file-parallel scheduler を使用します。`runtime-config` は infra core-runtime shard とともに実行され、共有 runtime shard が最後尾を抱え込まないようにします。`check-additional` は package-boundary compile/canary 作業をまとめて保ち、runtime topology architecture を gateway watch カバレッジから分離します。boundary guard shard は、その小さく独立した guards を 1 つのジョブ内で並列実行します。Gateway watch、channel tests、および core support-boundary shard は、`dist/` と `dist-runtime/` がすでにビルドされた後に `build-artifacts` 内で並列実行され、古い check 名を軽量 verifier ジョブとして維持しつつ、追加の Blacksmith worker 2 台と 2 回目の artifact-consumer queue を回避します。
Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party フレーバーには別個の source set や manifest はありませんが、その unit-test レーンは SMS/call-log BuildConfig フラグ付きでそのフレーバーをコンパイルしつつ、Android 関連の各 push で重複した debug APK packaging ジョブを避けます。
`extension-fast` は PR 専用です。push 実行ではすでに完全な bundled plugin shard を実行しているためです。これにより、レビュー向けに changed-plugin フィードバックを維持しつつ、`main` で `checks-node-extensions` にすでに存在するカバレッジのために追加の Blacksmith worker を確保しません。
最も遅い Node テストファミリーは、各ジョブを小さく保ちつつ runner の過剰確保を避けるため、分割またはバランス調整されています。channel contract は重み付きの 3 shard で実行され、bundled plugin テストは 6 つの extension worker に分散され、小規模な core unit レーンはペア化され、auto-reply は 6 つの極小 worker ではなくバランスされた 3 worker で実行され、agentic gateway/plugin config は built artifact を待つ代わりに既存の source-only agentic Node ジョブに分散されます。広範な browser、QA、media、およびその他の plugin テストは、共有 plugin catch-all ではなく専用の Vitest config を使用します。広範な agents レーンは、単一の遅いテストファイルに支配されるのではなく import/scheduling が支配的であるため、共有 Vitest の file-parallel scheduler を使用します。`runtime-config` は infra core-runtime shard とともに実行され、共有 runtime shard が最後尾を抱え込まないようにしています。`check-additional` は package-boundary の compile/canary 作業をまとめて維持し、runtime topology architecture を gateway watch coverage から分離しています。boundary guard shard は、小さく独立した guard を 1 つのジョブ内で並行実行します。Gateway watch、channel テスト、および core support-boundary shard は、`dist/` と `dist-runtime/` がすでにビルドされた後に `build-artifacts` 内で並行実行され、従来の check 名を軽量な verifier ジョブとして維持しつつ、追加の Blacksmith worker 2 台と 2 回目の artifact-consumer queue を避けています。
Android CI は `testPlayDebugUnitTest` と `testThirdPartyDebugUnitTest` の両方を実行し、その後 Play debug APK をビルドします。third-party flavor には個別の source set や manifest はありませんが、その unit-test レーンでは SMS/call-log BuildConfig flag を使ってその flavor をコンパイルしつつ、Android 関連の push ごとに debug APK の packaging ジョブを重複実行することは避けています。
`extension-fast` は PR 専用です。push 実行ではすでに完全な bundled plugin shard が実行されるためです。これにより、レビュー向けには変更された plugin のフィードバックを維持しつつ、`main` で `checks-node-extensions` にすでに含まれているカバレッジのために余分な Blacksmith worker を確保せずに済みます。
GitHub は、同じ PR または `main` ref に新しい push が届いたとき、置き換えられたジョブを `cancelled` とマークすることがあります。同じ ref の最新実行も失敗している場合を除き、これは CI ノイズとして扱ってください。aggregate shard チェックは `!cancelled() && always()` を使用しているため、通常の shard failure は引き続き報告しますが、ワークフロー全体がすでに置き換えられている場合はキューに入りません。
CI の concurrency key はバージョン付き（`CI-v7-*`）なので、古い queue group に残った GitHub 側の zombie が新しい main 実行を無期限にブロックすることはありません。
同じ PR または `main` ref に新しい push が届いた場合、GitHub は置き換えられたジョブを `cancelled` とマークすることがあります。同じ ref に対する最新の実行も失敗していない限り、これは CI ノイズとして扱ってください。aggregate shard チェックは `!cancelled() && always()` を使用しているため、通常の shard failure は引き続き報告されますが、workflow 全体がすでに置き換えられた後にキューに入ることはありません。
CI の concurrency key はバージョン付き（`CI-v7-*`）であるため、古い queue group に残った GitHub 側の zombie が、新しい `main` 実行を無期限にブロックすることはありません。
## ランナー
| ランナー | ジョブ |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ubuntu-24.04` | `preflight`、高速セキュリティジョブと aggregate（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速 protocol/contract/bundled チェック、分割された channel contract チェック、lint を除く `check` shard、`check-additional` の shard と aggregate、Node テスト aggregate verifier、docs チェック、Python Skills、workflow-sanity、labeler、auto-response。install-smoke の preflight でも GitHub ホストの Ubuntu を使用するため、Blacksmith matrix をより早くキューに入れられます |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node テスト shard、bundled plugin テスト shard、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`。これは依然として CPU 感度が高く、8 vCPU では節約できた以上のコストがかかりました。install-smoke の Docker build では、32-vCPU のキュー時間が得られる節約以上のコストになりました |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`。fork では `macos-latest` にフォールバックします |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-swift`。fork では `macos-latest` にフォールバックします |
| ランナー | ジョブ |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`、高速セキュリティジョブとその aggregate（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、高速 protocol/contract/bundled チェック、shard 化された channel contract チェック、lint を除く `check` shard、`check-additional` の shard と aggregate、Node テスト aggregate verifier、docs チェック、Python Skills、workflow-sanity、labeler、auto-response；install-smoke の preflight も、Blacksmith matrix をより早くキューできるよう GitHub-hosted Ubuntu を使用します |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node テスト shard、bundled plugin テスト shard、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`。これは依然として CPU 依存性が高く、8 vCPU では節約できる以上にコストがかかりました；install-smoke の Docker build。こちらも 32-vCPU では節約できる以上にキュー時間のコストが大きくなりました |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-node`；fork では `macos-latest` にフォールバックします |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上の `macos-swift`；fork では `macos-latest` にフォールバックします |
## 対応するローカルコマンド
## ローカルでの同等コマンド
```bash
pnpm changed:lanes # origin/main...HEAD に対するローカルの changed-lane classifier を確認
pnpm check:changed # スマートなローカル gate: boundary レーンごとの changed typecheck/lint/tests
pnpm check # 高速ローカル gate: production tsgo + 分割 lint + 並列高速 guards
pnpm changed:lanes # origin/main...HEAD に対するローカル changed-lane classifier を確認
pnpm check:changed # スマートなローカルゲート: boundary lane ごとの変更対象 typecheck/lint/tests
pnpm check # 高速なローカルゲート: 本番 tsgo + shard 化された lint + 並列の高速 guard
pnpm check:test-types
pnpm check:timed # 同じ gate をステージごとの所要時間付きで実行
pnpm check:timed # ステージごとの所要時間付きの同じゲート
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # vitest tests
pnpm test # vitest テスト
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs # docs format + lint + broken links
pnpm build # CI の artifact/build-smoke レーンが関係する場合は dist をビルド
node scripts/ci-run-timings.mjs <run-id> # 実行時間、キュー時間、最も遅いジョブを要約
pnpm check:docs # docs の format + lint + broken link
pnpm build # CI の artifact/build-smoke レーンが関係する場合に dist をビルド
node scripts/ci-run-timings.mjs <run-id> # wall time、queue time、最も遅いジョブを要約
node scripts/ci-run-timings.mjs --recent 10 # 最近成功した main の CI 実行を比較
```

165
docs/ja-JP/gateway/authentication.md
View File

@ -1,14 +1,14 @@
---
read_when:
- モデル認証やOAuthの期限切れをデバッグしている
- 認証や認証情報ストレージをドキュメント化している
summary: 'モデル認証: OAuth、APIキー、Claude CLIの再利用、Anthropic setup-token'
- モデル認証またはOAuthの有効期限切れのデバッグ
- 認証または認証情報ストレージの文書化
summary: 'モデル認証: OAuth、APIキー、Claude CLIの再利用、およびAnthropicのセットアップトークン'
title: 認証
x-i18n:
generated_at: "2026-04-07T04:41:53Z"
generated_at: "2026-04-23T15:00:47Z"
model: gpt-5.4
provider: openai
source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231
source_hash: 37a7c20872b915d1d079f0578c933e43cbdb97eca1c60d8c4e6e5137ca83f8b2
source_path: gateway/authentication.md
workflow: 15
---
@ -16,36 +16,30 @@ x-i18n:
# 認証（モデルプロバイダー）
<Note>
このページでは**モデルプロバイダー**の認証（APIキー、OAuth、Claude CLIの再利用、Anthropic setup-token）を扱います。**Gateway接続**の認証（トークン、パスワード、trusted-proxy）については、[Configuration](/ja-JP/gateway/configuration) と [Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth) を参照してください。
このページでは、**モデルプロバイダー**の認証（APIキー、OAuth、Claude CLIの再利用、およびAnthropicのセットアップトークン）を扱います。**Gateway接続**の認証（トークン、パスワード、trusted-proxy）については、[Configuration](/ja-JP/gateway/configuration)および[Trusted Proxy Auth](/ja-JP/gateway/trusted-proxy-auth)を参照してください。
</Note>
OpenClawはモデルプロバイダー向けにOAuthとAPIキーをサポートしています。常時稼働のGateway
ホストでは、通常はAPIキーが最も予測しやすい選択肢です。サブスクリプション/OAuth
フローも、プロバイダーのアカウントモデルに合う場合はサポートされています。
OpenClawは、モデルプロバイダー向けにOAuthとAPIキーをサポートしています。常時稼働するGatewayホストでは、通常、APIキーが最も予測しやすい選択肢です。プロバイダーのアカウントモデルに合っていれば、サブスクリプション/OAuthフローもサポートされています。
完全なOAuthフローとストレージ
レイアウトについては [/concepts/oauth](/ja-JP/concepts/oauth) を参照してください。
SecretRefベースの認証（`env`/`file`/`exec` プロバイダー）については、[Secrets Management](/ja-JP/gateway/secrets) を参照してください。
`models status --probe` で使用される認証情報の適格性/理由コードのルールについては、
[Auth Credential Semantics](/ja-JP/auth-credential-semantics) を参照してください。
OAuthフロー全体とストレージレイアウトについては、[/concepts/oauth](/ja-JP/concepts/oauth)を参照してください。
SecretRefベースの認証（`env`/`file`/`exec`プロバイダー）については、[Secrets Management](/ja-JP/gateway/secrets)を参照してください。
`models status --probe`で使用される認証情報の適格性/理由コードのルールについては、
[Auth Credential Semantics](/ja-JP/auth-credential-semantics)を参照してください。
## 推奨セットアップ（APIキー、任意のプロバイダー）
長時間稼働するGatewayを動かしている場合は、選択した
プロバイダーのAPIキーから始めてください。
Anthropicについては特に、APIキー認証が依然として最も予測しやすいサーバー向け
セットアップですが、OpenClawはローカルのClaude CLIログインの再利用もサポートしています。
長期間稼働するGatewayを運用している場合は、選択したプロバイダーのAPIキーから始めてください。
Anthropicについては、APIキー認証が依然として最も予測しやすいサーバーセットアップですが、OpenClawはローカルのClaude CLIログインの再利用もサポートしています。
1. プロバイダーのコンソールでAPIキーを作成します。
2. それを**Gatewayホスト**（`openclaw gateway` を実行しているマシン）に配置します。
2. それを**Gatewayホスト**（`openclaw gateway`を実行しているマシン）に配置します。
```bash
export <PROVIDER>_API_KEY="..."
openclaw models status
```
3. Gatewayがsystemd/launchdの下で動作している場合は、デーモンが読み取れるように
`~/.openclaw/.env` にキーを置くことを推奨します。
3. Gatewayがsystemd/launchdの下で動作している場合は、デーモンが読み取れるように、キーを`~/.openclaw/.env`に配置することを推奨します。
```bash
cat >> ~/.openclaw/.env <<'EOF'
@ -53,7 +47,7 @@ cat >> ~/.openclaw/.env <<'EOF'
EOF
```
その後、デーモンを再起動する（またはGatewayプロセスを再起動する）か、再確認します。
その後、デーモンを再起動し（またはGatewayプロセスを再起動し）、再確認します。
```bash
openclaw models status
@ -63,33 +57,46 @@ openclaw doctor
環境変数を自分で管理したくない場合は、オンボーディングで
デーモン用のAPIキーを保存できます: `openclaw onboard`。
`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd における環境継承の詳細は [Help](/ja-JP/help) を参照してください。
`env`の継承（`env.shellEnv`、
`~/.openclaw/.env`、systemd/launchd）について詳しくは、[Help](/ja-JP/help)を参照してください。
## Anthropic: Claude CLIとトークン互換性
## Anthropic: Claude CLIとトークンの互換性
Anthropic setup-token認証は、OpenClawで引き続きサポートされているトークン
経路として利用できます。その後、Anthropicの担当者から、OpenClaw方式のClaude CLI利用は
再び許可されていると案内されたため、Anthropicが新しいポリシーを公開しない限り、
OpenClawはこの統合においてClaude CLIの再利用と `claude -p` の使用を認可済みとして扱います。ホスト上で
Claude CLIの再利用が利用できる場合、現在はこちらが推奨される経路です。
Anthropicのセットアップトークン認証は、OpenClawでサポートされているトークン経路として引き続き利用可能です。その後、Anthropicのスタッフから、OpenClawスタイルのClaude CLI使用は再び許可されていると伝えられたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはこの統合においてClaude CLIの再利用と`claude -p`の使用を許可されたものとして扱います。ホストでClaude CLIの再利用が可能な場合、現在はそれが推奨経路です。
長時間稼働するGatewayホストでは、Anthropic APIキーが依然として最も予測しやすい
セットアップです。同じホスト上の既存のClaudeログインを再利用したい場合は、オンボーディング/設定で
Anthropic Claude CLI経路を使用してください。
長期間稼働するGatewayホストでは、Anthropic APIキーが依然として最も予測しやすいセットアップです。同じホスト上で既存のClaudeログインを再利用したい場合は、オンボーディング/設定でAnthropic Claude CLI経路を使用してください。
手動トークン入力（任意のプロバイダー; `auth-profiles.json` に書き込み + 設定を更新）:
Claude CLI再利用の推奨ホストセットアップ:
```bash
# Gatewayホストで実行
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
```
これは2段階のセットアップです。
1. Gatewayホスト上でClaude Code自体をAnthropicにログインさせます。
2. Anthropicモデルの選択をローカルの`claude-cli`
バックエンドに切り替え、対応するOpenClaw認証プロファイルを保存するようOpenClawに指示します。
`claude`が`PATH`上にない場合は、まずClaude Codeをインストールするか、
`agents.defaults.cliBackends.claude-cli.command`を実際のバイナリパスに設定してください。
手動トークン入力（任意のプロバイダー; `auth-profiles.json`に書き込み + 設定を更新）:
```bash
openclaw models auth paste-token --provider openrouter
```
静的認証情報では認証プロファイル参照もサポートされています。
静的な認証情報向けに認証プロファイル参照もサポートされています。
- `api_key` 認証情報は `keyRef: { source, provider, id }` を使用できます
- `token` 認証情報は `tokenRef: { source, provider, id }` を使用できます
- OAuthモードのプロファイルはSecretRef認証情報をサポートしません。`auth.profiles.<id>.mode` が `"oauth"` に設定されている場合、そのプロファイルへのSecretRefベースの `keyRef`/`tokenRef` 入力は拒否されます。
- `api_key`認証情報は`keyRef: { source, provider, id }`を使用できます
- `token`認証情報は`tokenRef: { source, provider, id }`を使用できます
- OAuthモードのプロファイルはSecretRef認証情報をサポートしません。`auth.profiles.<id>.mode`が`"oauth"`に設定されている場合、そのプロファイルに対するSecretRefベースの`keyRef`/`tokenRef`入力は拒否されます。
自動化向けチェック（期限切れ/未設定で終了コード `1`、期限切れ間近で `2`）:
自動化向けチェック（期限切れ/未設定で終了コード`1`、期限が近い場合は`2`）:
```bash
openclaw models status --check
@ -101,28 +108,28 @@ openclaw models status --check
openclaw models status --probe
```
注記:
注意:
- プローブ行は、認証プロファイル、環境認証情報、または `models.json` から来ることがあります。
- 明示的な `auth.order.<provider>` で保存済みプロファイルが省かれている場合、プローブは
そのプロファイルを試す代わりに `excluded_by_auth_order` を報告します。
- 認証が存在していても、そのプロバイダー向けにプローブ可能なモデル候補をOpenClawが解決できない場合、
プローブは `status: no_model` を報告します。
- レート制限のクールダウンはモデル単位である場合があります。ある
モデルでクールダウン中のプロファイルでも、同じプロバイダー上の別のモデルでは使用可能なことがあります。
- プローブ行は、認証プロファイル、環境変数の認証情報、または`models.json`から取得される場合があります。
- 明示的な`auth.order.<provider>`に保存済みプロファイルが含まれていない場合、
プローブはそのプロファイルを試行せず、`excluded_by_auth_order`を
そのプロファイルに対して報告します。
- 認証が存在しても、そのプロバイダーに対してプローブ可能なモデル候補をOpenClawが解決できない場合、
プローブは`status: no_model`を報告します。
- レート制限のクールダウンはモデル単位の場合があります。ある
モデルでクールダウン中のプロファイルでも、同じプロバイダー上の兄弟モデルでは引き続き使用可能な場合があります。
任意の運用スクリプト（systemd/Termux）については、ここで説明しています:
[Auth monitoring scripts](/ja-JP/help/scripts#auth-monitoring-scripts)
オプションの運用スクリプト（systemd/Termux）については、こちらに記載されています:
[認証監視スクリプト](/ja-JP/help/scripts#auth-monitoring-scripts)
## Anthropicに関する注記
Anthropicの `claude-cli` バックエンドは再びサポートされています。
Anthropicの`claude-cli`バックエンドは再びサポートされています。
- Anthropicの担当者は、このOpenClaw統合経路は再び許可されていると案内しました。
- そのためOpenClawは、Anthropicが新しいポリシーを公開しない限り、
Anthropicベースの実行におけるClaude CLIの再利用と `claude -p` の使用を認可済みとして扱います。
- Anthropic APIキーは、長時間稼働するGateway
ホストと、明示的なサーバー側課金制御において、依然として最も予測しやすい選択肢です。
- Anthropicのスタッフから、このOpenClaw統合経路は再び許可されていると伝えられました。
- そのためOpenClawは、Anthropicが新しいポリシーを公開しない限り、Anthropicをバックエンドとする実行においてClaude CLIの再利用と`claude -p`の使用を許可されたものとして扱います。
- Anthropic APIキーは、長期間稼働するGateway
ホストおよび明示的なサーバー側課金管理のための最も予測しやすい選択肢であり続けます。
## モデル認証ステータスの確認
@ -131,36 +138,35 @@ openclaw models status
openclaw doctor
```
## APIキーのローテーション動作（Gateway）
## APIキーのローテーション動作（gateway）
一部のプロバイダーは、API呼び出しがプロバイダーのレート制限に達した場合に、
別のキーでリクエストを再試行することをサポートしています。
一部のプロバイダーでは、API呼び出しがプロバイダーのレート制限に達した際に、別のキーでリクエストを再試行することをサポートしています。
- 優先順位:
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（単一のオーバーライド）
- 優先順:
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（単一の上書き）
- `<PROVIDER>_API_KEYS`
- `<PROVIDER>_API_KEY`
- `<PROVIDER>_API_KEY_*`
- Googleプロバイダーでは、追加のフォールバックとして `GOOGLE_API_KEY` も含まれます。
- 同じキー一覧は使用前に重複排除されます。
- OpenClawは、レート制限エラーの場合にのみ次のキーで再試行します（たとえば
- Googleプロバイダーでは、追加のフォールバックとして`GOOGLE_API_KEY`も含まれます。
- 同じキーの一覧は、使用前に重複排除されます。
- OpenClawは、レート制限エラーの場合にのみ次のキーで再試行します（例:
`429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent
requests`、`ThrottlingException`、`concurrency limit reached`、または
`workers_ai ... quota limit exceeded`）。
- レート制限以外のエラーでは、代替キーで再試行しません。
- すべてのキーが失敗した場合は、最後の試行での最終エラーが返されます。
- レート制限以外のエラーでは、代替キーによる再試行は行われません。
- すべてのキーが失敗した場合は、最後の試行で発生した最終エラーが返されます。
## 使用する認証情報の制御
### セッションごと（チャットコマンド）
### セッション単位（チャットコマンド）
現在のセッションで特定のプロバイダー認証情報を固定するには、`/model <alias-or-id>@<profileId>` を使用します（プロファイルIDの例: `anthropic:default`、`anthropic:work`）。
現在のセッションで特定のプロバイダー認証情報を固定するには、`/model <alias-or-id>@<profileId>`を使用します（プロファイルIDの例: `anthropic:default`、`anthropic:work`）。
簡易ピッカーには `/model`（または `/model list`）を、完全表示には `/model status` を使用します（候補 + 次の認証プロファイル。設定されている場合はプロバイダーのエンドポイント詳細も表示）。
コンパクトなピッカーには`/model`（または`/model list`）を使用します。完全な表示（候補 + 次の認証プロファイル、および設定されている場合はプロバイダーのエンドポイント詳細）には`/model status`を使用します。
### エージェントごと（CLIオーバーライド）
### エージェント単位（CLI上書き）
エージェントに対する明示的な認証プロファイル順序のオーバーライドを設定します（そのエージェントの `auth-state.json` に保存されます）。
エージェントに対する明示的な認証プロファイル順序の上書きを設定します（そのエージェントの`auth-state.json`に保存されます）。
```bash
openclaw models auth order get --provider anthropic
@ -168,25 +174,24 @@ openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic
```
特定のエージェントを対象にするには `--agent <id>` を使用します。省略すると、設定されたデフォルトエージェントが使用されます。
順序の問題をデバッグするときは、`openclaw models status --probe` により、省かれた
保存済みプロファイルは黙ってスキップされるのではなく `excluded_by_auth_order` として表示されます。
クールダウンの問題をデバッグするときは、レート制限のクールダウンが
プロバイダープロファイル全体ではなく1つのモデルIDに結びついている可能性があることを覚えておいてください。
特定のエージェントを対象にするには`--agent <id>`を使用し、設定済みのデフォルトエージェントを使う場合は省略します。
順序の問題をデバッグする際、`openclaw models status --probe`は省略された
保存済みプロファイルを黙ってスキップする代わりに`excluded_by_auth_order`として表示します。
クールダウンの問題をデバッグする際は、レート制限のクールダウンが
プロバイダープロファイル全体ではなく、1つのモデルIDに結び付けられている場合があることを忘れないでください。
## トラブルシューティング
### 「認証情報が見つかりません」
Anthropicプロファイルがない場合は、
**Gatewayホスト**にAnthropic APIキーを設定するか、Anthropic setup-token経路を設定してから、再確認してください。
Anthropicプロファイルが存在しない場合は、
**Gatewayホスト**上でAnthropic APIキーを設定するか、Anthropicのセットアップトークン経路を設定してから、再確認してください。
```bash
openclaw models status
```
### トークンの有効期限切れ/期限切れ間近
### トークンの有効期限が近い/期限切れ
どのプロファイルの期限が近いかを確認するには `openclaw models status` を実行します。Anthropicの
トークンプロファイルが存在しない、または期限切れの場合は、
setup-tokenでその設定を更新するか、Anthropic APIキーへ移行してください。
どのプロファイルの有効期限が近いかを確認するには、`openclaw models status`を実行します。Anthropicトークンプロファイルが存在しない、または期限切れの場合は、
setup-tokenでそのセットアップを更新するか、Anthropic APIキーに移行してください。

261
docs/ja-JP/gateway/cli-backends.md
View File

@ -1,47 +1,41 @@
---
read_when:
- API provider が失敗したときの信頼できるフォールバックが必要な場合
- Codex CLI やその他のローカル AI CLI を実行していて、それらを再利用したい場合
- CLI バックエンドの tool アクセス向け MCP loopback ブリッジを理解したい場合
summary: 'CLI バックエンド: 任意の MCP tool ブリッジを備えたローカル AI CLI フォールバック'
title: CLI バックエンド
- APIプロバイダーが失敗したときに、信頼できるフォールバックが必要です
- Codex CLIやその他のローカルAI CLIを実行していて、それらを再利用したい場合
- CLIバックエンドのツールアクセスのためのMCP loopbackブリッジを理解したい場合
summary: 'CLIバックエンド: オプションのMCPツールブリッジを備えたローカルAI CLIフォールバック'
title: CLIバックエンド
x-i18n:
generated_at: "2026-04-23T14:03:42Z"
generated_at: "2026-04-23T15:00:48Z"
model: gpt-5.4
provider: openai
source_hash: 475923b36e4580d3e4e57014ff2e6b89e9eb52c11b0a0ab1fc8241655b07836e
source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316
source_path: gateway/cli-backends.md
workflow: 15
---
# CLI バックエンド（フォールバックランタイム）
# CLIバックエンド（フォールバックランタイム）
OpenClaw は、API provider が停止している、レート制限されている、または一時的に不安定な場合に、**ローカル AI CLI** を **テキスト専用フォールバック** として実行できます。これは意図的に保守的な設計です:
OpenClawは、APIプロバイダーがダウンしている、レート制限されている、または一時的に不安定なときに、**テキストのみのフォールバック**として**ローカルAI CLI**を実行できます。これは意図的に保守的な設計です。
- **OpenClaw tools は直接注入されません** が、`bundleMcp: true` を持つバックエンドは
loopback MCP ブリッジ経由で gateway tools を受け取れます。
- 対応する CLI 向けの **JSONL ストリーミング**。
- **セッションをサポート** しているため、追加入力でも一貫性が保たれます。
- CLI が画像 path を受け付ける場合、**画像も引き渡せます**。
- **OpenClawツールは直接注入されません**が、`bundleMcp: true` を持つバックエンドは、loopback MCPブリッジ経由でgatewayツールを受け取れます。
- 対応するCLI向けの**JSONLストリーミング**。
- **セッションをサポート**しているため、後続のターンでも一貫性が保たれます。
- CLIが画像パスを受け付ける場合は、**画像をそのまま渡せます**。
これはメイン経路というより **セーフティネット** として設計されています。外部 API に依存せず、
「とにかく動く」テキスト応答が欲しいときに使ってください。
これは、主要な経路というより**セーフティネット**として設計されています。外部APIに依存せずに「常に動作する」テキスト応答が必要なときに使ってください。
ACP セッション制御、バックグラウンドタスク、
thread/conversation バインディング、永続的な外部 coding セッションを備えた完全な harness runtime が必要なら、
代わりに [ACP Agents](/ja-JP/tools/acp-agents) を使用してください。CLI バックエンドは ACP ではありません。
ACPセッション制御、バックグラウンドタスク、スレッド/会話バインディング、永続的な外部コーディングセッションを備えた完全なハーネスランタイムが必要な場合は、代わりに [ACP Agents](/ja-JP/tools/acp-agents) を使ってください。CLIバックエンドはACPではありません。
## 初心者向けクイックスタート
設定なしでも Codex CLI を使用できます（バンドルされた OpenAI plugin が
デフォルトのバックエンドを登録します）:
Codex CLIは**設定なしで**使えます（同梱のOpenAI Pluginがデフォルトのバックエンドを登録します）。
```bash
openclaw agent --message "hi" --model codex-cli/gpt-5.4
```
gateway が launchd/systemd 配下で動作していて PATH が最小限の場合は、
コマンド path だけを追加してください:
gatewayがlaunchd/systemd配下で動作していてPATHが最小限の場合は、コマンドパスだけを追加してください。
```json5
{
@ -57,16 +51,13 @@ gateway が launchd/systemd 配下で動作していて PATH が最小限の場
}
```
これだけです。CLI 自体に必要なものを除いて、キーも追加の認証設定も不要です。
これだけです。CLI自体に必要なもの以外に、キーや追加の認証設定は不要です。
バンドルされた CLI バックエンドを gateway host 上の**主要メッセージ provider** として使う場合、
OpenClaw は、設定が model ref や
`agents.defaults.cliBackends` の下でそのバックエンドを明示的に参照していれば、
所有している bundled plugin を自動的に読み込むようになりました。
gatewayホスト上で、同梱のCLIバックエンドを**主要メッセージプロバイダー**として使う場合、設定でそのバックエンドをモデル参照、または `agents.defaults.cliBackends` 配下で明示的に参照すると、OpenClawはその所有元の同梱Pluginを自動読み込みするようになりました。
## フォールバックとして使う
CLI バックエンドをフォールバック一覧に追加すると、主要モデルが失敗したときだけ実行されます:
CLIバックエンドをフォールバックリストに追加すると、主要モデルが失敗したときだけ実行されます。
```json5
{
@ -87,20 +78,19 @@ CLI バックエンドをフォールバック一覧に追加すると、主要
注意:
- `agents.defaults.models`（許可リスト）を使う場合は、CLI バックエンドのモデルもそこに含める必要があります。
- 主要 provider が失敗した場合（認証、レート制限、タイムアウト）、OpenClaw は
次に CLI バックエンドを試します。
- `agents.defaults.models`（許可リスト）を使う場合は、CLIバックエンドのモデルもそこに含める必要があります。
- 主要プロバイダーが失敗した場合（認証、レート制限、タイムアウト）、OpenClawは次にCLIバックエンドを試します。
## 設定の概要
## 設定概要
すべての CLI バックエンドは以下に配置されます:
すべてのCLIバックエンドは次の場所にあります。
```
agents.defaults.cliBackends
```
各エントリは **provider id**（例: `codex-cli`, `my-cli`）をキーにします。
provider id は model ref の左側になります:
各エントリーは**provider id**（例: `codex-cli`, `my-cli`）でキー付けされます。
provider idはモデル参照の左側になります。
```
<provider>/<model>
@ -130,7 +120,7 @@ provider id は model ref の左側になります:
sessionMode: "existing",
sessionIdFields: ["session_id", "conversation_id"],
systemPromptArg: "--system",
// Codex-style CLIs can point at a prompt file instead:
// CodexスタイルのCLIでは、代わりにプロンプトファイルを指定できます:
// systemPromptFileConfigArg: "-c",
// systemPromptFileConfigKey: "model_instructions_file",
systemPromptWhen: "first",
@ -146,97 +136,75 @@ provider id は model ref の左側になります:
## 仕組み
1. provider 接頭辞（`codex-cli/...`）に基づいて **バックエンドを選択** します。
2. 同じ OpenClaw prompt + workspace コンテキストを使って **system prompt を構築** します。
3. 履歴の一貫性を保つため、CLI が対応していれば session id 付きで **CLI を実行** します。
バンドルされた `claude-cli` バックエンドは、OpenClaw セッションごとに
Claude stdio process を維持し、追加入力を stream-json stdin 経由で送ります。
4. 出力（JSON またはプレーンテキスト）を **解析** し、最終テキストを返します。
5. バックエンドごとに session id を **永続化** し、追加入力で同じ CLI セッションを再利用します。
1. providerプレフィックス（`codex-cli/...`）に基づいて**バックエンドを選択**します。
2. 同じOpenClawプロンプトとワークスペースコンテキストを使って**システムプロンプトを構築**します。
3. 履歴の一貫性を保つため、対応している場合はセッションid付きで**CLIを実行**します。
同梱の `claude-cli` バックエンドは、OpenClawセッションごとにClaude stdioプロセスを維持し、後続ターンをstream-json stdin経由で送信します。
4. **出力を解析**し（JSONまたはプレーンテキスト）、最終テキストを返します。
5. バックエンドごとに**セッションidを永続化**し、後続ターンで同じCLIセッションを再利用します。
<Note>
バンドルされた Anthropic `claude-cli` バックエンドは再びサポートされています。Anthropic のスタッフから、
OpenClaw スタイルの Claude CLI 利用は再び許可されると伝えられたため、Anthropic が新しいポリシーを公開しない限り、
OpenClaw はこの統合における `claude -p` 使用を許可済みとして扱います。
同梱のAnthropic `claude-cli` バックエンドが再びサポートされました。Anthropicのスタッフから、OpenClawスタイルのClaude CLI利用は再び許可されていると案内されたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはこの連携における `claude -p` の使用を公認済みとして扱います。
</Note>
バンドルされた OpenAI `codex-cli` バックエンドは、OpenClaw の system prompt を
Codex の `model_instructions_file` 設定上書き（`-c
model_instructions_file="..."`）経由で渡します。Codex には Claude スタイルの
`--append-system-prompt` フラグがないため、OpenClaw は新しい Codex CLI セッションごとに
組み立てた prompt を一時ファイルへ書き出します。
同梱のOpenAI `codex-cli` バックエンドは、Codexの `model_instructions_file` 設定オーバーライド（`-c model_instructions_file="..."`）を通して、OpenClawのシステムプロンプトを渡します。CodexはClaudeスタイルの `--append-system-prompt` フラグを公開していないため、OpenClawは新しいCodex CLIセッションごとに組み立てたプロンプトを一時ファイルに書き出します。
バンドルされた Anthropic `claude-cli` バックエンドは、OpenClaw の Skills スナップショットを
2 つの方法で受け取ります。ひとつは追加された system prompt 内のコンパクトな OpenClaw Skills カタログ、
もうひとつは `--plugin-dir` で渡される一時的な Claude Code plugin です。
その plugin には、その agent/session に適格な Skills だけが含まれているため、Claude Code のネイティブな Skill
resolver には、OpenClaw が prompt 内で通知するのと同じフィルタ済みセットが見えます。
Skill の env/API key 上書きは、実行時に引き続き OpenClaw が子プロセス環境へ適用します。
同梱のAnthropic `claude-cli` バックエンドは、OpenClawのSkillsスナップショットを2つの方法で受け取ります。1つは追加されたシステムプロンプト内のコンパクトなOpenClaw Skillsカタログ、もう1つは `--plugin-dir` で渡される一時的なClaude Code Pluginです。このPluginにはそのagent/セッションで利用資格のあるSkillsのみが含まれるため、Claude Codeネイティブのskill resolverは、OpenClawがそれ以外ならプロンプト内で通知するのと同じフィルタ済みセットを認識します。Skillのenv/APIキー上書きは、実行時にOpenClawから子プロセス環境へ引き続き適用されます。
OpenClawが同梱の `claude-cli` バックエンドを使う前に、Claude Code自体が同じホスト上ですでにログイン済みである必要があります。
```bash
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
```
`claude` バイナリがすでに `PATH` 上にある場合を除き、`agents.defaults.cliBackends.claude-cli.command` を使ってください。
## セッション
- CLI がセッションをサポートしている場合は、`sessionArg`（例: `--session-id`）または
`sessionArgs`（複数のフラグに `{sessionId}` を挿入する必要がある場合のプレースホルダー）を設定します。
- CLI が異なるフラグを使う **resume サブコマンド** を持つ場合は、
`resumeArgs`（resume 時に `args` を置き換える）と、必要に応じて
`resumeOutput`（JSON ではない resume 用）を設定します。
- CLIがセッションをサポートする場合は、`sessionArg`（例: `--session-id`）または `sessionArgs`（複数のフラグにIDを挿入する必要がある場合のプレースホルダー `{sessionId}`）を設定します。
- CLIが異なるフラグを持つ**resumeサブコマンド**を使う場合は、`resumeArgs`（再開時に `args` を置き換えます）を設定し、必要に応じて `resumeOutput`（非JSONのresume用）も設定します。
- `sessionMode`:
- `always`: 常に session id を送信します（保存済みがなければ新しい UUID）。
- `existing`: 以前に保存された session id がある場合のみ送信します。
- `none`: session id を送信しません。
- `claude-cli` はデフォルトで `liveSession: "claude-stdio"`、`output: "jsonl"`、
`input: "stdin"` を使うため、アクティブな間は追加入力でも生きている Claude process を再利用します。
現在は warm stdio がデフォルトであり、transport フィールドを省略したカスタム設定でも同様です。
Gateway が再起動したり、アイドル中の process が終了した場合は、
OpenClaw は保存済み Claude session id から再開します。保存済み session
id は、再開前に読み取り可能な既存 project transcript に対して検証されるため、
幽霊のようなバインディングは `--resume` 配下で黙って新しい Claude CLI セッションを始める代わりに
`reason=transcript-missing` でクリアされます。
- 保存された CLI セッションは provider 所有の継続性です。暗黙の日次セッション
リセットでは切断されません。`/reset` と明示的な `session.reset` ポリシーでは切断されます。
- `always`: 常にセッションidを送信します（保存済みがなければ新しいUUID）。
- `existing`: 以前に保存されている場合のみセッションidを送信します。
- `none`: セッションidを送信しません。
- `claude-cli` は、`liveSession: "claude-stdio"`、`output: "jsonl"`、`input: "stdin"` をデフォルトとし、アクティブな間は後続ターンがライブClaudeプロセスを再利用します。現在は、トランスポートフィールドを省略したカスタム設定も含め、ウォームなstdioがデフォルトです。Gatewayが再起動するか、アイドル状態のプロセスが終了した場合、OpenClawは保存されたClaudeセッションidから再開します。保存されたセッションidは再開前に既存の読み取り可能なプロジェクトトランスクリプトに対して検証されるため、実体のないバインディングは `--resume` で新しいClaude CLIセッションを黙って開始する代わりに、`reason=transcript-missing` でクリアされます。
- 保存されたCLIセッションはprovider所有の継続性です。暗黙の日次セッションリセットでは切断されませんが、`/reset` および明示的な `session.reset` ポリシーでは切断されます。
シリアライズに関する注意:
- `serialize: true` は同じレーンの実行順序を維持します。
- ほとんどの CLI は 1 つの provider レーンでシリアライズされます。
- OpenClaw は、選択された auth identity が変わると、保存済み CLI セッションの再利用を破棄します。
これには、auth profile id の変更、静的 API key、静的 token、
または CLI が公開している場合は OAuth account identity の変更が含まれます。OAuth access
token と refresh token のローテーションでは、保存済み CLI セッションは切断されません。
CLI が安定した OAuth account id を公開していない場合、OpenClaw はその CLI 側に resume 権限の強制を委ねます。
- ほとんどのCLIは1つのproviderレーンでシリアライズされます。
- 選択された認証IDが変わった場合、OpenClawは保存済みCLIセッションの再利用を破棄します。これには、auth profile idの変更、静的APIキー、静的トークン、またはCLIが公開している場合のOAuthアカウントIDの変更が含まれます。OAuthのアクセストークンとリフレッシュトークンのローテーションでは、保存済みCLIセッションは切断されません。CLIが安定したOAuthアカウントIDを公開しない場合、OpenClawはそのCLIにresume権限の強制を任せます。
## 画像（パススルー）
CLI が画像 path を受け付ける場合は、`imageArg` を設定します:
CLIが画像パスを受け付ける場合は、`imageArg` を設定します。
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw は base64 画像を一時ファイルへ書き出します。`imageArg` が設定されていれば、
それらの path が CLI 引数として渡されます。`imageArg` がない場合、OpenClaw は
ファイル path を prompt に追記します（path injection）。これは、単なる path からローカルファイルを自動読み込みする
CLI には十分です。
OpenClawはbase64画像を一時ファイルに書き出します。`imageArg` が設定されている場合、それらのパスはCLI引数として渡されます。`imageArg` がない場合、OpenClawはファイルパスをプロンプトに追記します（パス注入）。これは、プレーンなパスからローカルファイルを自動読み込みするCLIには十分です。
## 入力 / 出力
## 入出力
- `output: "json"`（デフォルト）は JSON の解析を試み、text + session id を抽出します。
- Gemini CLI の JSON 出力では、`usage` がないか空の場合、
OpenClaw は返信テキストを `response` から、使用量を `stats` から読み取ります。
- `output: "jsonl"` は JSONL ストリーム（たとえば Codex CLI `--json`）を解析し、最終 agent メッセージと
存在する session 識別子を抽出します。
- `output: "text"` は stdout を最終応答として扱います。
- `output: "json"`（デフォルト）はJSONを解析し、テキストとセッションidの抽出を試みます。
- Gemini CLIのJSON出力では、`usage` が存在しないか空の場合、OpenClawは返信テキストを `response` から、使用量を `stats` から読み取ります。
- `output: "jsonl"` はJSONLストリーム（たとえばCodex CLIの `--json`）を解析し、存在する場合は最終agentメッセージとセッション識別子を抽出します。
- `output: "text"` はstdoutを最終応答として扱います。
入力モード:
- `input: "arg"`（デフォルト）は prompt を最後の CLI 引数として渡します。
- `input: "stdin"` は prompt を stdin 経由で送ります。
- prompt が非常に長く、`maxPromptArgChars` が設定されている場合は stdin が使われます。
- `input: "arg"`（デフォルト）は、プロンプトを最後のCLI引数として渡します。
- `input: "stdin"` は、プロンプトをstdin経由で送信します。
- プロンプトが非常に長く、`maxPromptArgChars` が設定されている場合は、stdinが使われます。
## デフォルト（plugin 所有）
## デフォルト（Plugin所有）
バンドルされた OpenAI plugin は `codex-cli` 用のデフォルトも登録します:
同梱のOpenAI Pluginは、`codex-cli` 用のデフォルトも登録します。
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@ -247,7 +215,7 @@ CLI には十分です。
- `imageArg: "--image"`
- `sessionMode: "existing"`
バンドルされた Google plugin は `google-gemini-cli` 用のデフォルトも登録します:
同梱のGoogle Pluginは、`google-gemini-cli` 用のデフォルトも登録します。
- `command: "gemini"`
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
@ -258,32 +226,27 @@ CLI には十分です。
- `sessionMode: "existing"`
- `sessionIdFields: ["session_id", "sessionId"]`
前提条件: ローカルの Gemini CLI がインストールされ、`PATH` 上で
`gemini` として利用可能である必要があります（`brew install gemini-cli` または
`npm install -g @google/gemini-cli`）。
前提条件: ローカルのGemini CLIがインストールされ、`PATH` 上で `gemini` として利用可能である必要があります（`brew install gemini-cli` または `npm install -g @google/gemini-cli`）。
Gemini CLI JSON に関する注意:
Gemini CLI JSONに関する注意:
- 返信テキストは JSON の `response` フィールドから読み取られます。
- `usage` が存在しないか空の場合、使用量は `stats` にフォールバックします。
- `stats.cached` は OpenClaw の `cacheRead` に正規化されます。
- `stats.input` がない場合、OpenClaw は入力トークンを
`stats.input_tokens - stats.cached` から導出します。
- 返信テキストはJSONの `response` フィールドから読み取られます。
- 使用量は、`usage` が存在しない場合または空の場合に `stats` にフォールバックします。
- `stats.cached` はOpenClawの `cacheRead` に正規化されます。
- `stats.input` が存在しない場合、OpenClawは `stats.input_tokens - stats.cached` から入力トークンを導出します。
必要な場合にのみ上書きしてください（よくあるのは絶対 `command` path です）。
必要な場合のみ上書きしてください（一般的なのは絶対 `command` パスです）。
## Plugin 所有のデフォルト
## Plugin所有のデフォルト
CLI バックエンドのデフォルトは、現在は plugin サーフェスの一部です:
CLIバックエンドのデフォルトは、現在ではPluginサーフェスの一部です。
- Plugins は `api.registerCliBackend(...)` でそれらを登録します。
- バックエンドの `id` が model ref における provider 接頭辞になります。
- `agents.defaults.cliBackends.<id>` 内のユーザー設定は、引き続き plugin デフォルトを上書きします。
- バックエンド固有の設定クリーンアップは、任意の
`normalizeConfig` hook を通じて引き続き plugin 側が管理します。
- Pluginは `api.registerCliBackend(...)` でそれらを登録します。
- バックエンドの `id` はモデル参照のproviderプレフィックスになります。
- `agents.defaults.cliBackends.<id>` にあるユーザー設定は、引き続きPluginデフォルトを上書きします。
- バックエンド固有の設定クリーンアップは、オプションの `normalizeConfig` フックを通じて引き続きPlugin所有のままです。
小さな prompt/message 互換 shim が必要な plugin は、provider や CLI バックエンドを置き換えずに、
双方向のテキスト変換を宣言できます:
小さなプロンプト/メッセージ互換性シムが必要なPluginは、providerやCLIバックエンドを置き換えずに双方向のテキスト変換を宣言できます。
```typescript
api.registerTextTransforms({
@ -300,51 +263,41 @@ api.registerTextTransforms({
});
```
`input` は CLI に渡す system prompt と user prompt を書き換えます。`output`
は、OpenClaw が独自の control marker や channel 配信を処理する前に、
ストリーミングされる assistant delta と解析済み最終テキストを書き換えます。
`input` は、CLIに渡されるシステムプロンプトとユーザープロンプトを書き換えます。`output` は、OpenClawが自身の制御マーカー処理とチャネル配信を行う前に、ストリーミングされたassistant deltaと解析済みの最終テキストを書き換えます。
Claude Code の stream-json 互換 JSONL を出力する CLI では、
そのバックエンド設定に `jsonlDialect: "claude-stream-json"` を設定してください。
Claude Code stream-json互換のJSONLを出力するCLIでは、そのバックエンド設定に `jsonlDialect: "claude-stream-json"` を設定してください。
## Bundle MCP オーバーレイ
## Bundle MCPオーバーレイ
CLI バックエンドは **OpenClaw tool call を直接受け取りません** が、バックエンドは
`bundleMcp: true` で生成される MCP 設定オーバーレイに opt in できます。
CLIバックエンドは**OpenClawツール呼び出しを直接受け取りません**が、バックエンドは `bundleMcp: true` で生成されるMCP設定オーバーレイにオプトインできます。
現在の bundled の動作:
現在の同梱動作:
- `claude-cli`: 生成された strict MCP config file
- `codex-cli`: `mcp_servers` 用のインライン設定上書き
- `google-gemini-cli`: 生成された Gemini システム設定ファイル
- `claude-cli`: 生成されたstrict MCP設定ファイル
- `codex-cli`: `mcp_servers` 用のインライン設定オーバーライド
- `google-gemini-cli`: 生成されたGeminiシステム設定ファイル
bundle MCP が有効な場合、OpenClaw は次を行います:
bundle MCPが有効な場合、OpenClawは次を行います。
- gateway tools を CLI process に公開する loopback HTTP MCP server を起動する
- セッションごとの token（`OPENCLAW_MCP_TOKEN`）でブリッジを認証する
- tool アクセスを現在の session、account、channel コンテキストに限定する
- 現在の workspace で有効な bundle-MCP server を読み込む
- それらを既存のバックエンド MCP config/settings 形状とマージする
- 所有 extension の統合モードを使って起動設定を書き換える
- CLIプロセスにgatewayツールを公開するloopback HTTP MCPサーバーを起動する
- セッションごとのトークン（`OPENCLAW_MCP_TOKEN`）でブリッジを認証する
- ツールアクセスを現在のセッション、アカウント、チャネルコンテキストにスコープする
- 現在のワークスペースに対して有効なbundle-MCPサーバーを読み込む
- それらを既存のバックエンドMCP設定/設定形状とマージする
- 所有元extensionのバックエンド所有統合モードを使って起動設定を書き換える
有効な MCP server がない場合でも、バックエンドが bundle MCP に opt in していれば、
OpenClaw は strict config を注入するため、バックグラウンド実行は分離されたままです。
MCPサーバーが1つも有効でない場合でも、バックエンドがbundle MCPにオプトインしていれば、バックグラウンド実行を分離した状態に保つために、OpenClawはstrict設定を引き続き注入します。
## 制限
## 制限事項
- **OpenClaw tool call の直接呼び出しはありません。** OpenClaw は CLI バックエンドプロトコルに
tool call を直接注入しません。バックエンドが gateway tools を認識するのは、
`bundleMcp: true` に opt in した場合のみです。
- **ストリーミングはバックエンド依存です。** JSONL をストリーミングするバックエンドもあれば、
終了までバッファするものもあります。
- **構造化出力** は CLI の JSON 形式に依存します。
- **Codex CLI セッション** はテキスト出力経由で resume されるため（JSONL ではない）、
初回の `--json` 実行より構造化が弱くなります。それでも OpenClaw セッション自体は通常どおり動作します。
- **OpenClawツール呼び出しの直接利用はできません。** OpenClawはCLIバックエンドプロトコルにツール呼び出しを注入しません。バックエンドが `bundleMcp: true` にオプトインした場合にのみ、gatewayツールを認識できます。
- **ストリーミングはバックエンド依存です。** JSONLをストリーミングするバックエンドもあれば、終了までバッファするバックエンドもあります。
- **構造化出力**はCLIのJSON形式に依存します。
- **Codex CLIセッション**はテキスト出力経由で再開されます（JSONLではありません）。そのため、最初の `--json` 実行より構造化が弱くなります。それでもOpenClawセッション自体は通常どおり動作します。
## トラブルシューティング
- **CLI が見つからない**: `command` にフル path を設定してください。
- **model 名が間違っている**: `modelAliases` を使って `provider/model` → CLI model にマップしてください。
- **セッション継続性がない**: `sessionArg` が設定されていて、`sessionMode` が
`none` でないことを確認してください（現在 Codex CLI は JSON 出力では resume できません）。
- **画像が無視される**: `imageArg` を設定し（CLI が file path をサポートすることも確認してください）。
- **CLIが見つからない**: `command` にフルパスを設定してください。
- **モデル名が間違っている**: `modelAliases` を使って `provider/model` → CLIモデル をマッピングしてください。
- **セッションの継続性がない**: `sessionArg` が設定されていて、`sessionMode` が `none` ではないことを確認してください（Codex CLIは現在、JSON出力で再開できません）。
- **画像が無視される**: `imageArg` を設定し（あわせてCLIがファイルパスをサポートしていることを確認してください）。

1280
docs/ja-JP/help/testing.md
View File

File diff suppressed because it is too large Load Diff